clay-borg/decisions/ADR-0012-the-design-instrument.md

ADR-0012: clay-borg is a design instrument, and §Underdetermined is the register

status: accepted date: 2026-08-05 decided by: agent, under the standing loop authorization tier: L (structural L — named a high-leverage pass by the maintainer and it amends INTENT; chaos d8=6 → no override). Tier L requires a separate survey, an adversarial review, then this document. references: CB-WP-0022, CB-RES-0007, challenge / response, ADR-0007 D3, GROUND-WP-0002, GROUND-WP-0004 T02 (ground-game's shape ruling)

Context

Nineteen passes of building a rigorous simulator produced findings about the game's rules as a by-product, because an engine that refuses to proceed past an undecided rule cannot help but locate the undecided rules. Six such findings exist. They live in eleven files, no index, and one sat unread in an inbox for four days.

The review changed what this ADR has to decide. The survey proposed a new register governed by an existence rule — a finding is not admissible without its reproduction. C1 falsified the example that rule was built on, and C4 pointed out the incumbent was never evaluated. Both are load-bearing here, so both are answered before anything is built.

The correction this ADR is built on

CB-WP-0022:61 justified the rule with "GR-E01 is admissible because 4/6/9 against 5/7/9 is a computation anyone can rerun." Commit 2da19a4 had already rerun it: 6/9/12 against 5/7/9, and the scenario was renamed -unreachable- → -reachable-. The conclusion inverted.

That finding was one of the two that passed the reproduction rule. So:

wrong premise	reached ground-game?	passed an existence test?
"12 in the file" — a sum with no deal table	yes	—
"SOLVE offered on a face-down Problem" — wrong condition named	yes	—
"4/6/9, no dataset reconciles them"	stopped in flight, 2026-08-05	yes

Existence is not the property that was missing. Three findings went wrong on their description, and the one that carried an artifact carried a green one that no longer matched its prose. This ADR's rule is written against that, not against the survey's.

---

D1 — INTENT gains a fourth property: the engine is an instrument

INTENT.md states three properties — Clay, Borg, product-driven evolution. It gains a fourth, and the wording is deliberately about a mechanism, not an ambition:

4. Instrument — the engine is rigorous enough that it cannot proceed past a rule that does not decide. What it cannot execute, it reports: findings about the game's design are a product of building the simulator, not a side activity, and they are carried back to the game's owner with the artifact that produced them.

Why this is earned rather than aspirational. It is a restatement of something that has already happened six times without anyone deciding it should. The alternative wording considered and rejected — "clay-borg is a game design tool" — claims a product we do not have and invites building one; this claims a property we already exhibit and makes it a duty.

Falsifier, and it is real: if a pass ships with the engine having tolerated an undecided rule by quietly picking a default and not raising it, property 4 is false and INTENT is lying. provisional: true plus its age report is what keeps it honest, and D2 puts the duty where that machinery already lives.

D2 — §Underdetermined is the register. Nothing parallel is built.

C4 lands. specs/GroundRules.md §Underdetermined was never evaluated as a candidate, and against CB-RES-0007's own five benchmarks it already delivers four:

benchmark	§Underdetermined today
findability — one register with an index	yes, U1–U10 in one section
closure — the source changes, not an annotation	yes: "a ruling flips the scenario, not the kernel" (:231-233)
time raised → read	owner and raise date per item, make coverage warns past 30 days
taxonomy fits reality	untested either way
reproducibility — 100% carry a replayable artifact	no. This is the gap.

The survey went to Magic to discover the Oracle property. We had written it down ourselves eight days earlier, in our own words. A second register would immediately disagree with the first, and this project has a standing rule that a gate must cash out.

Decision: extend, do not replace. §Underdetermined becomes the finding register for all five kinds in D4, not only for dataset ambiguities. Its existing machinery — owner, raise date, provisional: true, the age warning — is the mechanism, unchanged. What is added is D3's admissibility rule, D4's kind, and D5's state.

What this costs, stated plainly: the register lives in a spec file about GROUND's rules, so a finding about the engine's behaviour sits in a document about the game. That is tolerable because every finding in scope is about the game by definition (D7), and it is the price of not running two registers that drift.

D3 — admissibility: exists, has the ruled shape, and can fail

The survey's rule was one clause. It is now three, and all three are required:

1. It exists. A scenario, an arithmetic check that prints the contradiction, a recorded game the reader can replay, or a named test.

2. It has the ruled shape. Per GROUND-WP-0004 T02, an arithmetic finding ships a row-level table — Surface and each hidden priority listed separately — never a sum, never "deal depth N". Promoted here from the T04 addendum it was, because two of three wrong premises were quantities summed without a table.

3. It can fail. The artifact must be capable of going red, and its current colour is recorded. A reproduction that has gone green is not a closed finding — it is a finding whose claim is now in question, and it must be resolved to applied or withdrawn by a human reading it.

Clause 3 is the one the review bought. GR-E01's scenario went green when the edition landed, and the finding stayed admissible and stayed queued for transmission, because nothing in the rule said a passing artifact was a signal. A green reproduction is an alarm, not a reassurance.

Falsifier for D3 as a whole: if a finding reaches ground-game whose prose describes a quantity its own artifact does not compute, D3 has failed and the next revision needs the description generated from the artifact rather than written beside it.

D4 — taxonomy, grounded in the six we have

Five kinds, each with the existing finding that forces it. No kind is included that no finding of ours instantiates — that is the whole discipline, and T05's backfill is its test.

kind	means	our instance
underdetermined	the rules do not say	U1–U10
inconsistent	the rules disagree with each other or with the dataset	GR-E01 as raised (now withdrawn)
inert	a rule that cannot fire	SOLVE on a face-down Problem
degenerate	fires, but collapses play	GR-A13 wasted SOLVE
unplayed	implemented, never played to the end	GR-E03 / GR-E04

If backfill needs a sixth kind, the taxonomy was invented rather than observed and T07 must say so.

D5 — lifecycle: a queue that empties, a log that does not

raised ──► reported ──► ruled ──► applied
   │                                 
   └──────────► withdrawn ◄──────────┘

state	means	owner
raised	admissible under D3, in clay-borg	clay-borg
reported	delivered to ground-game as a file under their workplan	clay-borg
ruled	ground-game has answered	ground-game
applied	the source changed — dataset or rules text — and our provisional default was deleted	clay-borg
withdrawn	the finding was wrong, or dissolved	whoever finds it wrong

applied means the source changed. It does not mean a ruling was recorded — Magic's Oracle property, and CB-RES-0007 §2 is right about it.

The queue is raised + reported; the log is applied + withdrawn. C6 asked whether keeping resolved findings contradicts "a queue that empties." It does not: the open queue empties, the closed log accumulates so a close rate can be computed. Falsifier: if the default view shows closed findings mixed with open ones, the queue property is gone — so make design reports the queue, and the log only on request.

withdrawn is reported, not deleted. GR-E01 is the reason: a claim retracted silently is how the first three survived. When a finding is withdrawn after being reported, the withdrawal goes downstream too.

D6 — a finding without a reproduction is a note, and a note is not reportable

The survey left this open (§6) and the honest options were refusal or a note tier. Notes are admitted, under three constraints that make the tier costly to sit in:

1. A note may not be reported to ground-game. It has no reported state. This is the whole point: the unread-inbox failure was prose crossing a repo boundary.
2. A note expires at 30 days and make design flags it, reusing §Underdetermined's existing age mechanism rather than adding one.
3. A note that is promoted acquires a reproduction meeting D3 — there is no path from note to reported that skips it.

Why not refusal. A finding from play — the maintainer's "I felt it was too easy but then we lost" — is real, has no cheap artifact, and is the seed of CB-WP-0025. Refusing it would throw away the only class of finding the engine cannot produce by itself. Why not silence. A note that cannot expire ages into an apparent finding, which is the failure this register exists to stop.

D7 — no engine-evolution register, on a corrected inventory

The declaration's judgment survives; its argument did not, and the difference is recorded rather than smoothed over. My inventory named evidence/, decisions/, gates.toml and workplans. C5 found two places it missed — specs/InnerLoopReference.md, 383 lines with sections headed "moved from InnerLoop v1.6", and 769 lines of history/ retrospectives. So the "third thing" the maintainer asked about does exist and did find homes, somewhat by accident.

Decision: no new register, because a third place to look for material currently in two makes it less findable, not more. This is argued and narrowed, not settled — if InnerLoopReference keeps absorbing content that is neither a decision nor a finding, that is the signal to revisit.

D8 — tools/design-baseline.py is retired, not extended

C2 dismantled it: a hand-maintained dict counting itself (:16-36, :89), a has_reproduction that never checks the file exists (:38-43) so its own YES-control is green against a path 2da19a4 deleted (:63), date literals for the 4-day figure (:96-98), and Makefile:127 running only --self-test so the reporting path has no CI at all.

The 33% is withdrawn as a measured rate. What survives is direction: eleven files with no index and 0 of 10 U-items ruled are both checkable without the tool.

make design (T05) reports over the register, which is real data with real files behind it, and its reproduction check stats the file. The baseline stays in the repo as the survey's dated snapshot, marked superseded — deleting it would erase the evidence for how the number got in.

D9 — where a finding lives, and where it is delivered

The survey did not settle this. Both, with distinct roles:

• clay-borg holds the finding and its reproduction, in §Underdetermined. The artifact cannot leave — it only runs here.
• ground-game receives a generated report file under its own workplan, not an inbox message. Per CB-WP-0022 T06: the message that sat unread for four days is the baseline to beat, and the failure was not the message — it was that nothing pointed at it.

The report cites the reproduction by path, which is the half of GROUND-WP-0004 T02's ruling that is theirs to keep, and makes the split survivable: they read a claim, we hold the thing that proves it.

Consequences

• INTENT.md gains property 4 (D1) — the change with the longest half-life in this pass.
• specs/GroundRules.md §Underdetermined becomes the register and gains kind and state per item (D2, D4, D5); no new file, no new schema.
• T04's spec inherits D3 as a rule, not an addendum, and must say what a reproduction has to show.
• T05 builds make design over the register and backfills all six. If a sixth kind is needed, the taxonomy was invented.
• T06 reports the queue and GR-E01's withdrawal.
• Notes carry a 30-day expiry (D6) on the existing age machinery.

What was rejected

rejected	why
a new register file with its own schema	C4 — the incumbent already delivers 4 of 5 benchmarks
the existence-only admissibility rule	C1 — its own showcase finding passed it and was false
refusing findings without reproductions	throws away findings from play, which is CB-WP-0025's entire input
an engine-evolution register	D7 — a third home for material already in two
extending design-baseline.py	C2 — it counts itself and its positive control is green against a deleted file