Add multi-core scaling benchmark; fix stale spdlog finding claim

Author: czhao-dev

README.md

@@ -177,14 +177,48 @@ Measured on an 8-core Apple M3, Release build, average of 3 runs each,
 there being only 7 TUs to spread across the pool, not 8, plus thread-pool
 startup overhead. Peak RSS scales up correspondingly, since parallel runs
 keep multiple TUs' ASTs alive in memory at once instead of one at a time.
-Both modes report byte-for-byte identical findings (verified via `diff`),
-including the same real, pre-existing `redundant-move-return` case in
-spdlog's own `pattern_formatter-inl.h` found back in the M4 benchmark.
-
-This is one honest number, not a benchmark suite -- see
-[`docs/spec.md`](docs/spec.md) §10/§14 for what's deliberately out of
-scope for the MVP (a benchmark corpus, scaling studies beyond this one
-data point).
+Both modes report byte-for-byte identical findings (verified via `diff`).
+(The M4 benchmark's real `redundant-move-return` finding in spdlog's own
+`pattern_formatter-inl.h` no longer surfaces under this toolchain: that
+line sits behind `#if defined(__GNUC__) && __GNUC__ < 5`, which Clang
+preprocesses out, so it was never actually visible to the analyzer in
+this configuration -- not a regression, just a preprocessor conditional
+worth being honest about rather than repeating a stale claim.)
+
+### Scaling study
+
+To see parallel speedup past 8 cores, measured on a 32-vCPU GCP
+`c2d-standard-32` VM (Ubuntu 24.04, ephemeral -- provisioned, benchmarked,
+and torn down for this one run), average of 3 runs per `--jobs` value.
+Two corpora, since spdlog's 7 TUs cap meaningful parallelism regardless
+of core count:
+
+| `--jobs` | spdlog (7 TUs) | speedup | self-scan (53 TUs) | speedup |
+|---|---|---|---|---|
+| 1 | 6.64 s | 1.00x | 189.65 s | 1.00x |
+| 2 | 3.77 s | 1.76x | 99.74 s | 1.90x |
+| 4 | 3.01 s | 2.20x | 53.32 s | 3.56x |
+| 8 | 2.35 s | 2.82x | 28.95 s | 6.55x |
+| 16 | 2.35 s | 2.82x | 18.34 s | 10.34x |
+| 32 | 2.35 s | 2.82x | 17.52 s | 10.82x |
+
+spdlog plateaus immediately at 8 cores (exactly the 7-TU cap predicted
+above -- more threads than TUs buys nothing). Self-scan, with more TUs
+than cores at every step up to 32, keeps climbing, but with clearly
+diminishing returns past 16 (16 -> 32 only gains ~5% more despite
+doubling the core count) -- Amdahl's-law-style overhead (the final sort,
+thread-pool teardown, and each task's own fixed per-TU setup cost) that
+core count alone can't parallelize away. Peak RSS at `--jobs 32` on the
+self-scan was ~11.1 GiB (vs. ~0.98 GiB at `--jobs 1`) -- a real memory
+cost worth knowing about before pointing high job counts at a large
+project on a memory-constrained machine. All job counts produced
+identical findings (verified via `diff`), including on the demo project
+run directly on this VM.
+
+This is still closer to "two honest data points" than a real benchmark
+suite -- see [`docs/spec.md`](docs/spec.md) §14 for what a full suite
+(synthetic corpus, cold/warm, scaling *and* memory as first-class
+dimensions, regression gating) would still need to add.
 
 ## Known limitations