Verdicts say what; nothing said why. A rejection that reads only
rejected-bench teaches nothing, and the loop's compounding value is that
the next hypothesis is better than the last. This ships the teaching layer,
built so it can never contaminate the thing it explains.
New crate crates/explain (`just explain <run-id>`):
- Advisory, strictly off the accept path: runs after the verdict is
recorded; nothing it emits feeds gates, bench, verdict, or ledger. Not
agent-facing: harnessd stays at seven ops, by design (SPEC §3.7 says why
- better hypotheses must never become a feedback channel into
measurement).
- Ledger-only inputs, deterministic: consumes exactly one row via the new
ledger::attempt_row; no config, no clock, no re-benching. Identical row,
byte-identical text - proven live (cmp on two runs of a real row).
- Record vs inference is typographic: restatements print plain; anything
beyond is prefixed `inference:` so an explanation can never be quoted as
a measurement.
- The narrative must agree with the machine verdict. The first live run
caught this class of bug: an accepted row without a recorded threshold
was narrated as "a policy rejection" two lines under "verdict: accepted".
Accepted rows are now always described by their CI lower bound (the
defensible claim); rejected-bench rows classify against 1.0 (measured
regression / null result / real-but-below-bar); NHR rows name the
recorded cap and state the numbers were not the deciding factor;
rejected-gate rows name the failing gate. Regression-tested.
- Historical rows are flagged, not laundered: accepted with
sanitizers_clean=false prints the doctrine caution (comrak-010 shows it);
fuzz_iters=0 accepts are named pre-integration rows.
verdict now records accept_threshold (the bar in force for that run) into
the bench env fingerprint, so rows are self-contained going forward -
explain never substitutes today's config for a historical bar, and says so
on older rows instead.
SPEC §3.7 (Added 2026-07-20) carries the invariants; book chapter
docs/src/explain.md shows real output from real rows (the accepted cJSON
win, the caught false-accept, the kernel-lane NHR); CLAUDE.md, README,
justfile, and the architecture layout updated (the layout also gains the
previously-omitted crates/policy line).
Verified: 21 workspace test suites green (6 new explain tests incl.
determinism and verdict-narrative agreement), clippy -D warnings clean,
fmt clean, mdbook builds, live runs against phase3-cjson-002,
phase5-matmul-opt, phase2-comrak-010, and phase4-cjson-service.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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>
phase3-cjson-002 (class 5+3): stack-buffer number parsing + strtod
round-trip replacing sscanf. +8.85% median, 95% CI [+7.5%, +10.0%] on
the C target, banked. 100% audit: byte-identical golden replay,
independent ASan+UBSan clean, 10k-input differential fuzz 0 divergences,
patch bounds/free-gating verified by eye.
- verdict: an infrastructure sanitizer-BUILD failure (missing runtime,
broken toolchain) now caps the accept at needs-human-review and logs
it, instead of crashing the verdict and losing a measured bench.
- results/phase3/: four public case studies (tokei class-5 wins; build
flags + allocators; the comrak caught false-accept; the cJSON
cross-language proof) + README. Compound-speedup claim stated as an
approximation, not a measured figure (CIs don't multiply).
- .gitignore: cjson build-artifact dirs.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EcKPWQ3MQD4NdEHwar96u2
20 audited attempts, 0 shipped false accepts, 3 verified auto-accepted
wins (tokei class-5: +10.7%, +3.7%, +9.9%; ~1.25x vs upstream with
Phase-0 wins). Independent 20-way adversarial re-audit (phase2-final-audit
workflow) confirmed every verdict follows its evidence, correct
equivalence tier, no harness-gaming, ledger append-only intact.
Closeout changes:
- case study: full 20-row attempt table, scoreboard, corrected
comrak-010 CI upper bound (+12.1%, was +12.2%), exit-criteria section
flipped to ALL MET, OS-isolation gap marked closed.
- CLAUDE.md Current-phase line: Phase 2 complete, next Phase 3.
- verdict: derive the ledger 'phase' column from the run_id namespace
(phaseN-*) instead of the hardcoded 1 the re-audit flagged; historical
rows are immutable and stay as written (run_id prefix is authoritative).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EcKPWQ3MQD4NdEHwar96u2
The pipeline auto-accepted an LSan-flagged teardown patch (+10.7%
median) because ASan/LSan were per-attempt manual; the 100% audit
overturned it (black_box liveness ends at scope close, process::exit
runs after — 384-byte arena chunk unreachable at exit). verdict now
builds the patched tree with ASan+LSan and runs the pinned workload on
every would-be accept, capping flagged wins at needs-human-review per
SPEC §8. Shipped false accepts remain 0; the win was not banked; case
study carries the corrective record.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EcKPWQ3MQD4NdEHwar96u2
Closes the CI-reachable slice of the Phase 1 infra gaps:
- trust-layer job: cargo test + clippy -D warnings + fmt
- target-gates-no-net: fetches pinned targets (new targets/fetch.sh),
regenerates + verifies corpora, runs 'just gates tokei'
mechanically, and executes the bench workload inside a
--network=none container (SPEC 3.1/10 no-net requirement)
- runner-calibration (informational): A/A + injection harness measures
the shared runner's noise floor per run, evidence uploaded as an
artifact — environments are judged empirically, not assumed
- perf-probe (informational): reports which perf event sources work
docs/infra.md maps each remaining hardware requirement (pinned cores,
governor/SMT control, separate-uid trust layer) to the bench-metal
self-hosted runner setup a human can complete in ~15 min.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EcKPWQ3MQD4NdEHwar96u2
Adds crates/verdict ('just verdict'): runs the core gates on the
candidate binary, then an interleaved A/B bench vs the baseline with
the CI-lower-bound rule, and writes the append-only ledger row with
per-side median CIs, workload statement, and env fingerprint. Gate
failure short-circuits to rejected-gate; --needs-human-review caps an
accepted verdict (never upgrades). CPU pinning moves into accept.toml
(pin_prefix, machine-specific, applied to both sides identically).
The smoke test caught a real trust gap: pointing --baseline-bin at the
workspace build (phase1-verdict-smoke-001) measured patched-vs-patched
and returned null, because gate runs rebuild the workspace binary from
the patched tree. Fix: --rebuild-baseline stashes the patch, builds
the baseline into isolated targets/<name>/baseline/, and restores the
patch — SPEC 3.1's pristine-checkout rule, now enforced by the
harness. Re-run (phase1-verdict-smoke-002) reproduces the Phase 0
result mechanically: +10.4% median, 95% CI [1.0932, 1.1137], accepted.
Both smoke rows are in the ledger, including the null one.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EcKPWQ3MQD4NdEHwar96u2
benbrownandClaude Fable 5