gates: close the audit findings — enforce the gates the docs claimed

An adversarial audit found the enforcement story ahead of the code: gates
that were documented as hard gates were advisory, manual, or absent, and
several human-facing claims outran the machine record. This makes the
claims true.

High findings

- Differential fuzz was documentation, not enforcement: verdict hardcoded
  fuzz_iters=0 and diff-test hardcoded the gate to Skipped, while the case
  studies claimed 10k-iteration fuzz on the same wins. Fuzz is now a real
  pipeline gate (strict FUZZ-RESULT contract, executed count recorded), and
  it is inherently baseline-vs-candidate, so it runs on the accept path and
  reports Skipped in the standalone `just gates` flow. New hard rule: a
  machine `accepted` verdict is impossible unless the fuzz gate actually
  passed — otherwise it caps at needs-human-review.
- The agent's system prompt claimed FP/concurrency/unsafe patches were
  "routed to human review automatically". No such mechanism existed. Added
  a conservative lexical risk classifier (crates/verdict/src/risk.rs) that
  forces needs-human-review on any would-be accept carrying those signals;
  fp-tolerance equivalence always signals.
- The local verdict path ran agent-influenced code unsandboxed. It now runs
  under scripts/no-net.sh (network namespace) and fails closed. Upstream
  test suites are hash-verified against corpora/<t>/TESTSUITE.sha256 when
  present (scripts/pin-testsuite.sh generates them).

Also fixed, found while fixing the above

- The pipeline script's `set -e` was inert (brace group as the left operand
  of `&&`), so a failing candidate build did not abort the run and verdict
  could bench a stale binary. Now a scoped subshell whose status is branched
  on at top level.
- A wrapper that exits before exec'ing (no-net.sh refusing, bad wrapper path)
  stranded RUNNING.lock and left read_verdict polling forever. Failure
  accounting now lives outside the wrapper.
- harnessd's patch allowlist ignored git rename/copy headers and --no-prefix
  diffs; the rename-escape case is now a committed regression test.
- The workspace did not compile on Windows (ungated Unix APIs). cfg-gated;
  71 portable tests now run on both platforms.
- pin-check regenerated the corpus manifest instead of verifying it; it is
  now verify-only, with a deliberate `just pin-corpus` to re-pin.
- Max RSS is captured per run on Unix; PMU counters are opt-in diagnostics
  (compare --perf-stat), never part of the accept decision.

Docs now match the code, including what is NOT yet enforced: no target ships
a TESTSUITE.sha256 pin, no target declares [build].tsan, and matmul is not
wired to the fp-tolerance gate — each is stated as mechanized-but-inert
rather than done. Corrected the stale "33 ledger rows" (34), the playbook's
class-3 cJSON win (rejected), adversarial-review.md's sanitizer-separation
claim (five accepted rows carry sanitizers_clean=false), the unsupported
"40,000 requests" figure, and the blanket "historical rows record
fuzz_iters=0" (8 of 10; phase0-tokei-002/-003 record 4,332).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/src/equivalence.md

@@ -7,6 +7,22 @@ candidate must prove it does the same thing the baseline does. These are
 
 ## The layers
 
+0. **Pin checks.** Before any gate runs, the corpus is verified against its
+   committed `MANIFEST.sha256` and the harness **refuses to run** on a
+   mismatch — nothing is measured on tampered inputs. This ships and is
+   enforced for every target.
+
+   The *test suite* has the same machinery but is **not yet active**:
+   `diff-test` verifies `corpora/<t>/TESTSUITE.sha256` when the file is
+   present (mismatch = hard refusal) and prints an explicit "suite unpinned"
+   warning when it is absent. **No target ships a suite pin today**, so this
+   check currently constrains nothing. It matters because upstream suites
+   are vendored under `targets/<t>/workspace/` — an agent-writable path — so
+   "the agent cannot edit the tests" rests on a pin that still has to be
+   generated (`scripts/pin-testsuite.sh`, a deliberate human action, run
+   after a fetch). Until then, that specific guarantee is a mechanism, not
+   a fact.
+
 1. **Upstream test suite.** The target's own tests, run against the patched
    code. For cJSON that is the vendored Unity/CTest suite (19 tests:
    `parse_number`, `parse_string`, `print_*`, `misc_tests`, …); for the Rust
@@ -20,15 +36,49 @@ candidate must prove it does the same thing the baseline does. These are
    mismatch.
 
 3. **Differential fuzzing.** Pristine vs candidate on thousands of mutated
-   inputs, comparing output. Every accepted win cleared **10,000 mutated
-   inputs with 0 divergences** — the tokei wins after canonicalizing benign
-   parallel-walker output ordering (a real finding: differential gates must
-   compare *semantics*, not bytes, where the target is legitimately
-   nondeterministic in presentation), the cJSON win on quote/number/escape
-   edge cases.
+   inputs, comparing output.
 
-4. **Sanitizers.** ASan/LSan for Rust, ASan+UBSan for C. Run on **every
-   would-be accept** — this is machine-enforced, not manual (see below).
+   *Where it runs.* Fuzz is the one gate that is **not** a property of the
+   candidate alone: it differs the candidate against a **pristine baseline**,
+   so it needs both binaries. That means it runs **only on the accept path**
+   (`just verdict`, the one flow that rebuilds a pristine baseline). The
+   standalone `just gates` flow has no baseline, so the gate reports
+   **Skipped, with that reason recorded** — it is never faked by comparing
+   the candidate against itself. `just gates` is a fast equivalence check,
+   **not** a fuzz run. The gate is graded strictly: `diff-test` runs the
+   target's declared `[gates].fuzz` command and parses a
+   `FUZZ-RESULT iters=<n> divergences=<m>` line; a run that never prints one
+   **fails**, rather than passing by silence.
+
+   *The hard rule.* A machine `accepted` verdict is now **impossible**
+   without this gate having actually passed. A skipped or failed fuzz gate
+   caps the verdict at `needs-human-review` — because an accept minted
+   without differential fuzz is an unverified claim.
+
+   *Honest history.* Through Phase 5 this ran as an **out-of-band
+   per-attempt script** (`scripts/diff-fuzz-<target>.py`), not inside the
+   pipeline — so **8 of the 10 accepted ledger rows record `fuzz_iters=0`**
+   even where a 10,000-input audit run is documented in the case study. The
+   two exceptions are the Phase 0 tokei rows, which record 4,332. Those
+   out-of-band runs produced real findings — the tokei wins passed only
+   after canonicalizing benign parallel-walker output ordering (differential
+   gates must compare *semantics*, not bytes, where the target is
+   legitimately nondeterministic in presentation), and the cJSON win cleared
+   quote/number/escape edge cases with 0 divergences.
+
+4. **Sanitizers.** ASan+UBSan (ASan/LSan on the Rust targets) is built and
+   run against the pinned workload on **every would-be accept** — the
+   sanitizer gate is machine-enforced, not manual (see below). A flagged
+   run, *or* a target that declares no sanitizer build at all, caps the
+   accept at `needs-human-review`.
+
+   A **TSan lane** exists on the same accept path, but it only runs when a
+   target declares `[build].tsan`. **No target declares it today, so there
+   is currently no TSan coverage** — the lane is wired and dormant, and a
+   patch touching threads needs that opt-in added before it can be checked.
+   (MIRI, named in the spec, was never implemented.) The concurrency safety
+   net that *is* live is the review tier below, which routes any
+   concurrency-token patch to a human.
 
 ## The tier rule (SPEC §8)
 
@@ -36,7 +86,11 @@ Some changes can pass every gate and still be unsafe to auto-ship. A change
 that touches floating-point ordering, concurrency primitives, `unsafe`, or
 carries a sanitizer flag is **never** auto-accepted — its verdict is capped
 at `needs-human-review`. The tier is decided by the *nature* of the change,
-never by the size of the number. The mimalloc allocator swap
+never by the size of the number. The routing is machine-enforced: `verdict`
+runs a conservative **lexical risk classifier** over the patch's changed
+lines (concurrency / unsafe / floating-point token lists — deliberately
+over-triggering, not a semantic analysis) and any signal, or the use of
+fp-tolerance equivalence mode at all, forces a would-be accept to review. The mimalloc allocator swap
 ([case study](./case-studies/build-flags.md)) is the canonical example: a
 real +4.6% win, correctly held for a human ruling because a global
 allocator change's safety is not something one benchmark can clear.

docs/src/introduction.md

@@ -29,7 +29,7 @@ and every one survived the gates above. These are not projections.
 | cJSON HTTP service — p50 latency under replayed load | +6.2%, CI [+5.8%, +7.2%] |
 | comrak (Rust) — mimalloc allocator swap (class 2) | +4.6%, CI [+3.3%, +5.8%], human-ruled |
 
-Across **five phases and 33 ledger rows**, with **zero shipped false
+Across **five phases and 34 ledger rows**, with **zero shipped false
 accepts** — including two occasions where the pipeline itself over-accepted
 and the audit caught it before anything shipped, each becoming a permanent
 new gate.

docs/src/isolation.md

@@ -34,6 +34,35 @@ The SDK's tool allow/deny list is defense-in-depth, not the boundary —
   path into the repo is the harnessd Unix socket; the trust layer is owned
   by another uid. This is the production shape (`docs/infra.md`).
 
+## Network isolation on the verdict path
+
+Target code should not be able to phone home during a measurement. What
+is actually enforced, stated honestly:
+
+- **The agent path is wrapped.** When `harnessd` launches the verdict
+  pipeline, it execs through `scripts/no-net.sh`, which runs it inside an
+  unprivileged **network namespace** (`unshare --net --map-current-user`).
+  `HOTPATH_VERDICT_WRAPPER` overrides the wrapper.
+- **It fails closed.** Where namespaces are unavailable the wrapper **exits
+  97 without running the pipeline** — it does not degrade silently. The one
+  bypass, `HOTPATH_ALLOW_UNISOLATED=1`, runs the pipeline **with full
+  network access**; it warns loudly on stderr *and* the resulting ledger row
+  records the isolation note `no-net.sh (HOTPATH_ALLOW_UNISOLATED=1 —
+  network NOT isolated)`. A run cannot claim an isolation it did not have.
+- **In CI**, the bench workload runs under `docker run --network=none`.
+
+Two limits, stated plainly rather than buried:
+
+- **Only the harnessd (agent) path is wrapped.** A human who invokes
+  `just verdict` directly runs it **unwrapped on the host**; those rows are
+  stamped `isolation: "unwrapped-host"` in the ledger. The wrapper is a
+  property of the agent pipeline, not of the `verdict` binary.
+- **Full-container isolation is still an open gap.** The namespace isolates
+  the *network* — not the filesystem, not the syscall surface. The
+  fully containerized, seccomp-restricted bench container of SPEC §10 is
+  **not built**. The agent-side OS boundary above is a separate mechanism
+  and *is* shipped.
+
 ## The two times the pipeline was wrong
 
 Anti-reward-hacking is not "it never fails" — it is "when it fails, the

docs/src/measurement.md

@@ -27,6 +27,22 @@ reproduces). A change is accepted only if the **CI lower bound** clears the
 threshold in `config/accept.toml` (default 2%) — not the median. The number
 you commit to is the one that survives the interval.
 
+## Beyond wall time: max RSS and PMU counters
+
+Wall time is the **only** metric a verdict is ever decided on. Two
+supporting measurements exist alongside it:
+
+- **Max RSS** is captured for every timed run on Unix (`wait4`'s
+  `ru_maxrss`) and recorded in the run's environment fingerprint as
+  baseline/candidate medians — so a speedup that quietly pays for itself
+  in memory is visible next to the number it bought.
+- **PMU counters** (cycles, instructions, cache misses, branch misses)
+  are opt-in diagnostics: `bench-runner compare --perf-stat` wraps each
+  timed run in `perf stat` and prints per-side medians with the workload
+  caveat attached. PMU access is unavailable in most VMs, and the
+  counters never participate in the accept decision — they explain a
+  wall-time delta, they do not replace it.
+
 ## The hardware has to earn trust first
 
 Before any measurement session, the harness runs two self-tests, recorded

docs/src/playbook.md

@@ -8,14 +8,16 @@ the ledger stops you from re-grinding a class that already has a verdict.
 |---|---|---|---|
 | 1 | Build config | LTO, codegen-units, target-cpu | tokei ✅ +10.4% |
 | 2 | Allocator | Global allocator swap (mimalloc) | comrak ✅ +4.6% (human-ruled) |
-| 3 | Allocation churn | Remove per-item malloc/free | tokei ✅, cJSON ✅ (+ one overturned) |
+| 3 | Allocation churn | Remove per-item malloc/free | tokei ✅; cJSON rejected-bench (+ one overturned) |
 | 4 | Data layout | Make the cache hierarchy fit the access pattern | comrak (attempted) |
 | 5 | Algorithmic | Eliminate redundant work | tokei ×3 ✅, cJSON ✅ |
 | 6 | SIMD | Autovectorization enablement | comrak, tokei (attempted) |
 | 7 | Concurrency | Parallelism — always `needs-human-review` | — |
 
 Six classes were exercised across the case studies, with verified wins on
-classes 1, 2, 3, and 5 across **both a Rust and a C target**.
+classes 1, 2, 3, and 5 — spanning **both a Rust and a C target** (the C
+win is the class-5 cJSON rewrite; cJSON's class-3 attempt was an honest
+`rejected-bench`, its CI lower bound short of the 2% bar).
 
 ## Why the ordering is load-bearing
 

docs/src/reproduce.md

@@ -5,6 +5,10 @@ through the same commands.
 
 ## Prerequisites
 
+- **A Linux/POSIX host.** The pipeline is Unix-only at runtime: `harnessd`
+  (Unix sockets, `setsid`), service mode, the isolation wrapper, and every
+  sh-based gate assume it. Windows compiles the workspace and runs the
+  portable unit tests, but **cannot run the pipeline**.
 - Rust (stable) + `just`; `clang`/`cmake` for the C target; `valgrind` for
   callgrind profiling. Nightly Rust for the sanitizer gate.
 - Targets are vendored fresh (their `workspace/` is gitignored); each
@@ -21,6 +25,14 @@ just verdict <t> <bin> ...     # gates + bench vs pristine baseline + ledger row
 just report <run-id>           # ROI report from a ledger row
 ```
 
+> **`just gates` does not fuzz.** Differential fuzz differs the candidate
+> against a *pristine baseline*, and only `just verdict` builds one — so on
+> the `gates` flow the fuzz layer reports **Skipped**, with the reason
+> recorded, rather than comparing the candidate against itself. Use `gates`
+> as a fast equivalence check; the fuzz gate (and the sanitizer lanes) run
+> on the accept path, where an accept is impossible without a passed fuzz
+> gate.
+
 Service mode (Phase 4):
 
 ```
@@ -42,7 +54,7 @@ Every accepted win can be re-audited independently:
 
 ```
 python3 scripts/audit-attempt.py <run-id>        # mechanical re-check
-python3 scripts/diff-fuzz-<target>.py <dir> 10000 <candidate-bin>   # 10k fuzz
+python3 scripts/diff-fuzz-<target>.py <dir> 10000 <baseline-bin> <candidate-bin>
 ```
 
 The ledger itself is the record: `results/ledger.sqlite`, append-only,

docs/src/research-forks.md

@@ -52,6 +52,19 @@ tolerance is defensible for the workload, exactly as with the mimalloc
 allocator swap. The machine measures and gates; the human ratifies the
 tolerance.
 
+> **Scope, stated honestly.** The FP-tolerance *mechanism* is in the gate
+> pipeline — `diff-test` honors an `equivalence.toml` policy (it needs a
+> committed `[corpus].golden_reference`, and fails closed without one), and
+> `verdict` auto-routes any fp-tolerance run to `needs-human-review`. But
+> **`matmul` is not wired into that pipeline**: it has an `equivalence.toml`
+> and **no `target.toml`**, which is the file `diff-test`/`verdict` load a
+> target from. So the kernel lane is demonstrated **script-driven**
+> (`scripts/kernel-lane-demo.sh`, using the `fp-compare` binary and
+> `bench-runner compare` directly), and the `phase5-matmul-opt` ledger row
+> was recorded outside the automated verdict path. Promoting `matmul` to a
+> real pipeline target is open work — the policy is closed; that target's
+> wiring is not.
+
 **This is the GPU lane in miniature.** The environment has no GPU, so the
 GPU fork is shown on the CPU as what it actually is — the same trust
 machinery with a different timer. A Triton or CUDA kernel versus a reference

docs/src/roadmap.md

@@ -44,5 +44,23 @@ Full write-up: [Research forks](./research-forks.md).
 The end goal is not vendored OSS case studies — it is a **real production
 system**. The same gates that matter for a JSON parser matter far more for
 a live CMS: an equivalence failure there is a customer-facing bug, and the
-no-network sandbox and append-only audit trail are exactly what make it
-safe to point an optimization agent at code that a business depends on.
+network-isolated verdict path and append-only audit trail are what would
+make it safe to point an optimization agent at code that a business depends
+on.
+
+## Known gaps (what would have to close first)
+
+Honesty about the remaining edges, since the product is trust:
+
+- **Full-container isolation.** The verdict pipeline is network-isolated on
+  the agent path (`scripts/no-net.sh`); the seccomp-restricted bench
+  container of SPEC §10 is **not built**, and a human running `just verdict`
+  directly is unwrapped.
+- **Test-suite pins.** The verify-or-refuse machinery exists, but **no
+  target ships a `TESTSUITE.sha256` yet** — so "the agent cannot edit the
+  upstream tests" is currently a mechanism awaiting its pins.
+- **TSan.** The lane runs on the accept path only when a target declares
+  `[build].tsan`; **none does today**, so there is no TSan coverage. Class-7
+  (concurrency) work depends on that opt-in landing.
+- **Kernel lane wiring.** `matmul` demonstrates FP-tolerance equivalence
+  script-driven; it is not yet a `target.toml` pipeline target.