clay-borg/workplans/CB-WP-0019-the-am4-family.md

id	kind	title	status
CB-WP-0019	meta	Budgets: what the meta budget is for, AM-4b's scope, and the self-quoting rule	todo

Purpose

structural tier  M   (changes how the loop constrains its own operation:
                      a budget's scope and target, and a reporting rule)
chaos            d8 = 5  → no override
declared tier    M

Declaration 2 of chaos window 2, and the first roll at d8.

Meta budget is 0% over the trailing three, all product. ADR-0006 D2 exempts instrument repair anyway, and this is the repair four evidence files have listed as owed.

Two numbers that have been owed for five passes

Both were measured before this declaration, so the work is scoped against facts rather than an intention to find them.

AM-4b's scope, owed since CB-EV-0012 §3:

	crates	lines
AM-4b as instrumented (games-ground, --edges normal)	29	317,021
the whole workspace, dev edges included	57	725,258
uncounted	28	408,237

The dev-toolchain budget is blind to more source than its own target of 350,000. criterion, clap, ciborium, quick-js and now cb-game-runtime's dev graph are all invisible to it.

AM-4b's proc-macro share, owed since ADR-0008 D2: 109,585 lines, 15.1% of the real graph.

That 15.1% is worth stating plainly, because it vindicates a decision made for the right reason. ADR-0008 D2 refused to correct AM-4b using AM-4a's measured 36.2%, saying "correcting a second instrument on the strength of the first one's ratio is the error this change exists to fix." The shares are 36.2% and 15.1%. Borrowing would have been wrong by a factor of more than two.

Task: give AM-4b a scope, and a target that matches it

id: CB-WP-0019-T01
status: todo
priority: high

Decide what AM-4b is for, then instrument that.

The two honest candidates, and the choice needs an argument rather than a default:

• Widen it to the whole workspace with dev edges — everything a contributor's cargo test acquires. Then the target must move with the instrument, exactly as ADR-0008 D3 moved AM-4a's, and the target moves to fit the measurement, not the measurement to fit the target.
• Narrow the claim to what it actually measures and rename it, if "one package's non-dev graph" is the thing worth bounding.

Whichever wins, do not repeat ADR-0008 D3's generosity by reflex. That decision gave back a small rounding-up because a target with 1.5% of room fails on a patch release; a target set 130% above the current reading would not be a budget at all.

Controls:

• the mutation must still go red — AM-4b's row is currently enforced and must stay so;
• a test that the configuration measures what its name says: if it claims dev edges, a dev-only dependency must move the number. quick-js is the case to use, because it is dev-only and it is what exposed this.

Task: the proc-macro share, decided not just measured

id: CB-WP-0019-T02
status: todo
priority: high

15.1% is measured. What is owed is the decision: does the dev budget exclude proc-macro crates as the shipped one does?

The shipped case was easy — a proc-macro never reaches a shipped binary, so counting it in "what a game ships" was simply wrong. The dev case is not the same question. A proc-macro is acquired, is compiled, is unaudited third-party source on a contributor's machine, and the acquisition rule (ADR-0007 D3) counts what the build causes to be fetched.

So the arguments point opposite ways and the answer is not inherited. Decide it, and say which of the two rules governs when they disagree.

Whatever is decided, ADR-0008 D2's note that AM-4b's share is unmeasured must stop being true in the source.

Task: write the self-quoting rule down

id: CB-WP-0019-T03
status: todo
priority: high

Six passes, six under-reports, both halves of the defect diagnosed, and the rule still lives only in evidence files:

pass	reported mid-flight	settled	under by
CB-WP-0009	$6.73	$11.31	40%
CB-WP-0011	$4.23	$7.02	40%
CB-WP-0012	$8.82	$14.52	39%
CB-WP-0013	$5.78	$8.26	30%
CB-WP-0015	$15.14	$22.70	33%
CB-WP-0017	$5.19	$9.48	45%

Six for six, always low, never by less than 30%. That is not noise; it is a systematic bias with two identified causes (CB-EV-0013 §5, CB-EV-0015 §6):

1. a pass's window runs to the next pass's first commit, so the previous pass is not final until the one after it starts;
2. a figure read earlier in a session is an in-flight figure regardless of whose name is on it — quoting from memory defeats the rule even when the boundary is right.

Put it in specs/InnerLoop.md as a rule with both halves, and make loop-lint check what it can. A rule that lives only in prose has been re-derived three times already.

The honest question to answer while writing it: is the right rule "quote two passes back", or "re-run the instrument at quote time", or both? T03 of CB-WP-0018 used the second and it worked. Say which is load bearing.

Task: say what the meta budget is for, and set it at 80/20

id: CB-WP-0019-T05
status: todo
priority: high

The maintainer, 2026-08-03:

"we should establish a rule for what the budget is for. The main budget should be spent on the task at hand while some of the budget should be spent on control, review and improvement of the process we use to propell us forward. We can make that 80/20 to start with and allow for increasing or lowering the meta budget based on the phase or task at hand."

META-25 has a threshold and no stated purpose — which is why it has been argued about as a number three times. Write the purpose first; the number follows from it.

The window and the ratio have to be chosen together

The budget is measured over a trailing 3-pass window. One meta pass among three, at the same cost as its neighbours, is already 33%. So a 20% soft line over three passes does not mean "one pass in five is meta" — it means "one in five and at half the cost of a product pass", which pushes meta work toward being rushed rather than rare.

window	what a 20% line requires of a meta pass
trailing 3	costs half a product pass
trailing 5	costs the same as a product pass

80/20 over a trailing 5-pass window is the literal reading of the instruction: one pass in five, at normal cost. Adopt that, and say in the spec that the ratio and the window are a pair — changing one without the other changes what the rule means.

The phase dial, and why it must not be a dial

"increasing or lowering based on the phase or task at hand" is right — stage 0 and a stabilisation phase should not carry the same ratio. But a threshold anyone may move is not a threshold, and this project has a standing rule that a limit is fixed structurally rather than raised (four loadability breaches, make status's 40 lines).

So the phase setting must be declared, argued, and expiring, in the same shape gates.toml already uses: a value, a reason, a review_by after which it reverts to 20 unless re-argued. Raising it silently to pass a breach is the failure this shape exists to prevent.

Controls: status.py's self-test must cover the new window and ratio, and must fail if a phase override has no reason or no expiry.

Task: evidence

id: CB-WP-0019-T04
status: todo
priority: high

evidence/CB-EV-0017-*.md.

• The AM-4 family, closed or not. Four defects found across five passes, none by looking for them. State whether any remain and whether the family is now trustworthy — and if a fifth is plausible, say where.
• What five passes of being "owed" cost. These two numbers were carried as open items in four consecutive evidence files. Either the carrying was cheap and correct, or it was a way of not doing the work; say which, with the cost.
• Quote CB-WP-0018's cost by re-running the instrument. Under the rule T03 writes down.
• The meta budget's new shape, and what it would have said about the last five passes had it been in force. If 80/20 over trailing-5 would have failed passes that were plainly right to run, say so — that is the ratio being wrong, not the passes.
• Chaos: declaration 2 of 12 in window 2, first roll at d8.