feat(release): APR-RELEASE-001 §5 P0·Instrument — make build-report reads the 1092 ledger records nothing read

[noahgift]

What

APR-RELEASE-001 §5 P0·Instrument's Done test is "≥ 20 records; make build-report runs on a clean checkout". Measured on main: 1092 ledger records are committed under docs/build-ledger/ in exactly the P0·Instrument schema — 1084 of them job records — and nothing in the tree read one. So the first half passes 54× over and the second half had no mechanism, which is why §1's p95, §1's max-PRs-per-train and the whole of §7's gate: line were still [U] while the data sat in git.

This is the sccache class: recorded thousands of times, never compared.

scripts/build_report.sh reads them in 0.27 s, byte-identical across runs.

What it says — the numbers that were [U] until now

host_class	n	p50 total_s	p95 total_s	p50 queue_s	p95 queue_s
gx10	509	366	2282	137	1399
intel	454	666	4994	34	1066
yoga	121	340	3518	11	832

gate:    p95 ci/gate 20.1 | max PRs/train 120 | queue p95 intel 1066 yoga 832 gx10 1399

Two things fall out of that table that no occupancy average could show. gx10 carries more jobs than intel (509 vs 454) and has the worst queue p95 (1399 s vs 1066 s) — the box the packing rule treats as spare capacity is the busiest by count and the slowest to start. And intel is the slowest per job (p95 4994 s).

The correction §1 needs

The first run of the report falsified the spec's own equation. §1 computes max PRs/train ≈ 3 × 72 h / p95(ci / gate). The required checks on main are gate and workspace-test, and a PR merges when the slowest one is green:

required check	n	p95 total_s
workspace-test	147	6451 ← binds
ci / gate	163	1205
gate	158	255

So §1 as written answers 645 and the honest answer is 120 — a 5.4× overstatement, on the one number §8 uses to decide whether to stop cutting trains ("measured max PRs/train < 10 [A]"). The report computes the bound over the required-check set, names which check binds, and prints the ratio by which §1's own form overstates. The gate: line keeps its specified shape; only the number is honest.

Both spellings are listed because they are one check: branch protection names ci / gate, ruleset 13878864 names a bare gate, and scripts/pr_review_quorum_arm.sh already accepts either for that reason.

Contract

scripts/check_build_report.sh, 35 assertions, run from make lint-scripts and from the new workflow:

• exit 2 + decline: below the §8 floor of 20 job records — a report over a thin ledger that prints 0 reads exactly like a fast fleet
• exit 1 + reject: on anything that is not a JSON object, never a silent skip
• a valid record with no total_s is skipped and the skip is printed (8 of 1092: 5 fleet-pack, 2 reconcile, 1 train)
• nearest-rank percentiles, case-tabled over 1..100 at k=1, 7, 29, 50, 95, 100 and over [7] and [1,2,3]

The ledger is per job, not per test target; the output says so where §5 asks for "10 slowest test targets" rather than inventing per-target numbers. peak_rss_mb and free_disk_gb are null on every record because the Actions REST API does not expose them — the report prints them as [U], it does not drop them.

Review found four defects, and they are fixed

make gate and a 3-lane review quorum ran against the first green implementation.

#	Found by	Defect
1	3/3 lanes, grounding=measured	a JSON value that is not an object aborted jq with exit 5, not the contracted exit 1. The guard had only tried plain text, which jq rejects cleanly — so the contract looked kept
2	3/3 lanes	an empty or whitespace-only file parsed to nothing and exited 0 — silently dropped, never counted
3	1/3 lanes	ceil(k/100.0 × n) in floating point: (7/100.0)*100 is 7.000000000000001, so p7 of 1..100 answered 8. The same lane correctly judged that a k=50/95/100 table cannot reach it — too coarse, not wrong
4	check_guards_are_wired.sh	build_report.sh was named by no workflow. make lint-scripts runs its guard, but Makefile-only means make tier3, which CI does not run — the same gap toolchain-ceiling.yml documents for check_msrv.sh. Unwired guards grew 3 → 4

Each has a case-table row that goes RED without its fix. Defect 4 is why .github/workflows/build-report.yml exists; the guard is back to its 3-entry baseline.

Gate

make gate reports 4 failures on this branch. None is caused by this diff — each was run on this branch and on a branch without these changes, in the same minute:

check	this branch	without these changes	verdict
check_baseline_ratchets	rc=1	rc=1	pre-existing: baselines recorded under pmat 3.39.0 / bashrs 7.0.1, runner has 3.40.0 / 7.4.1
check_complexity_ratchet	rc=1	rc=1	pre-existing, same instrument drift
check_silicon_coverage	rc=0 now, rc=1 15 min earlier	rc=0	time-dependent — the verdict changed with no commit between. A guard whose answer moves on the wall clock is worth its own ticket
check_guards_are_wired	rc=0	rc=0	was mine (3 → 4), fixed

How it composes with #3207

#3207 is the writer — scripts/collect_build_ledger.sh plus the nightly that appends records. This is the reader. Disjoint files; neither blocks the other. #3207 is what keeps this report's input growing; without it the ledger stops at 1092.

no-close: P0·Instrument has no issue of its own — the row is named in docs/specifications/APR-RELEASE-001-train-and-build-kaizen.md §5, and arrival already outruns closure 2:1, so this files nothing new.

ont-delta: none — no entity type, shape or resolves: target yet; the §11.1 delta for this surface is a code contract over the ledger record schema, and it waits on ONT-1 (pv census), epic #3269.

🤖 Generated with Claude Code

[github-actions]

§13.11 rung 1 — quorum shadow verdict

S13-SHADOW pr=3271 head=f28f9d295e148371690c3d3a1978b275132e33cb verdict=REFUSE class=Q1 arm_rc=1

Shadow mode: this records a verdict and merges nothing. A refusal
to arm is not a block (§13 adds zero rows to §7) — the pull request is
exactly as green as it was.

[noahgift]

This tool just answered a §5 row that the spec still lists as unstarted work

Dogfooding build_report.sh's own data against §5 P2 · Shard across hosts, whose Done test reads: "one PR's gate runs on ≥ 2 hosts; build-report prints p95 queue-wait per host; zero ENOSPC in 10 trains."

Measured over the committed ledger (1084 job records, 119 distinct shas):

clause	verdict
one PR's gate runs on ≥ 2 hosts	112 of 119 shas (94%) ran jobs on ≥ 2 host classes; 50 on ≥ 3
build-report prints p95 queue-wait per host	this PR — queue p95 intel 1066 yoga 832 gx10 1399
zero ENOSPC in 10 trains	trailing-window, belongs to P0 · Reap

03a00ad55 -> ['gx10', 'intel', 'yoga']
03b526185 -> ['gx10', 'intel']
092cf3ea5 -> ['gx10', 'intel']

So P2 is not pending work — the fleet has been sharding gates across hosts for 119 shas and nothing read the record that proves it. That is the same shape as the row this PR closes: the data was there, nothing compared it.

Worth noting for whoever plans the next build row: §5's queue should be re-derived from the Done tests, not worked top-to-bottom. P0 · Instrument was two-thirds satisfied before this PR (321 gate records ≫ the floor of 20); P2 is two-thirds satisfied now. A row's position in the list is not evidence about its state.

🤖 Generated with Claude Code