clay-borg/specs/GameDesign.md

GameDesign — findings about the game, and the trials that produce them

v1.0 — CB-WP-0022 T04, 2026-08-05. Normative. Implements ADR-0012; INTENT property 4 (Instrument) is what this spec discharges.

This is not a register. The register is GroundRules.md §Underdetermined — ADR-0012 D2. This document says what may go in it, what a reproduction must show, how a finding moves and dies, and how a trial game is run so "we played it and X happened" is replayable rather than remembered.

---

1. Admissibility

A finding is admissible when its reproduction exists, has the ruled shape, and can fail. All three. (ADR-0012 D3.)

1.1 Exists

One of: a scenario under scenarios/ground/, an arithmetic check that prints the contradiction, a .cbreplay bundle or recorded scenario the reader can replay, or a named test — crate::module::test_name, so it can be run.

The register entry names the artifact by path. A finding whose artifact path does not resolve is not admissible, and §4's check stats the file rather than pattern-matching the string — design-baseline.py's has_reproduction matched startswith("scenarios/") and its own positive control was green against a file that had been deleted (ADR-0012 D8).

1.2 Has the ruled shape

Per ground-game, GROUND-WP-0004 T02:

An arithmetic finding ships a row-level table — Surface and each hidden priority listed separately — never "sum of file", never "deal depth N".

A reproduction must show the quantity the prose claims. This is the clause that exists because passing artifacts accompanied wrong descriptions:

wrong premise	what shipped	what a row-level table would have shown
"12 in the file"	a sum	which rows, at which priorities
"4/6/9 against 5/7/9"	a scenario, green	6/9/12 — the deal, per row
"SOLVE offered on a face-down Problem"	a condition named	which filter actually fired

Requirement. Where a finding asserts a number, the register entry quotes the number and the artifact prints the rows it came from. A finding stating a total without its rows is inadmissible even if the total is right — "12" was arithmetically defensible and still wrong about the game.

1.3 Can fail

The artifact must be capable of going red, and the register records its current colour. A reproduction that has gone green is not a closed finding — it is a finding whose claim is now in question, and §4 reports it as needing resolution to applied or withdrawn.

A reproduction has a role, and only one of them alarms. This distinction was not in ADR-0012; T05's backfill produced it, when the first report cried wolf over U2.

role	what it is	green means
counterexample	demonstrates the defect — the model-checker shape	alarm. It should be red while the finding is open
default	encodes a provisional choice so it is testable and visible	expected. It passes because our default is implemented, which says nothing about whether the owner agrees

U2's scenario is green because the default it documents is implemented. GR-E01's was a counterexample that went green when the edition landed, and sat that way for four days. Same colour, opposite meaning — a register that cannot tell them apart either alarms constantly or never.

Rationale, and it is the expensive one. gr-e01-threshold-…-2p.yaml went green when the edition landed on 2026-08-04. The finding remained admissible, remained in the register, and remained queued for transmission to ground-game for four days, because nothing treated a passing artifact as a signal. It was stopped by an adversarial review, not by a control.

1.4 It must move when its subject moves

A measured claim names the variable it depends on, and shows the measurement moving with it. A number that does not move when its subject moves is measuring something else.

ADR-0018. This is the fourth clause and the first three are unchanged — each was bought by an earlier mistake and a rewrite would drop what they paid for.

Why it exists. Seven claims in this project have been wrong the same way: the arithmetic right, the subject wrong. Two of them were caught only because someone varied something —

• a per-node cost that fell as branching rose (no per-node cost can), and
• a win rate attributed to the game that collapsed to 0% under a second policy on the same deals.

Both were already printed when they shipped. Nobody looked at whether the number moved the way its subject demanded.

Where it binds: register findings whose claim is arithmetic, and anything leaving the repo. Not every number everywhere — a rule that binds everywhere is obeyed nowhere.

What it does not catch, stated so nobody stops looking: a count that was never made (there is no sensitivity to state), and a claim that is not a number. No syntactic gate detects a wrong subject in general. It is a semantic error; loop-lint checks that a sensitivity line is present, never that it is adequate.

2. Kinds

Five (ADR-0012 D4). No kind exists without a finding that instantiates it; a sixth appearing during backfill means the taxonomy was invented rather than observed, and T07 must say so.

underdetermined · inconsistent · inert · degenerate · unplayed

3. States, owners, and death

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

• applied means the source changed — dataset or rules text — and our provisional default was deleted. Not "a ruling was recorded."
• The queue is raised + reported. The log is applied + withdrawn. make design reports the queue by default; the log only on request. If the default view mixes them, the queue property is gone.
• withdrawn is reported downstream, not deleted. A claim retracted silently is how three wrong premises survived.

3.1 Notes

A finding without a reproduction is a note (ADR-0012 D6). A note:

1. has no reported state — it may not cross the repo boundary;
2. expires at 30 days, flagged by §4 on the same mechanism that ages provisional items (rule-coverage.py:54, PROVISIONAL_WARN_DAYS);
3. is promoted only by acquiring a reproduction meeting §1 — there is no path from note to reported that skips it.

4. Metrics

make design reports these. Every number is computed over the register, never from a maintained list (ADR-0012 D8).

metric	target	notes
findings with a resolving reproduction	100%	denominator includes withdrawn; notes counted separately, never folded in
reproductions that have gone green while open	0	the §1.3 alarm. Non-zero is a queue that needs reading, not a passing suite
arithmetic findings whose artifact prints rows	100%	§1.2
median days raised → reported	the number this exists to fix	the baseline it must beat is 4 days to first read
open findings by kind, with age	reported, not targeted
notes past 30 days	0
findings closed by a ruling vs still open	reported, with age

Falsifier for this spec. If a finding reaches ground-game whose prose describes a quantity its own artifact does not compute, §1.2 has failed and the next revision must generate the description from the artifact rather than let it be written alongside.

No baseline rate is quoted here. CB-RES-0007's 33% was withdrawn as a measured figure (ADR-0012 D8); the first honest denominator is the one T05's backfill produces.

5. The trial protocol

The part with no precedent in this repo. A trial game is a recorded session plus an observation log — so a claim from play is replayable.

It must cost almost nothing or it will not be done. The engine already records: cb-play --record FILE writes the finished game as a scenario YAML (main.rs:30), and games/ground/src/record.rs is trustworthy because its round trip is the test.

A trial is therefore:

cb-play --players N --serve PORT --record trials/<date>-<slug>.yaml

plus a sibling trials/<date>-<slug>.md carrying, and nothing more:

• who played which seats, and which were bots (with policy);
• what was observed — in the player's own words, not cleaned up;
• the seed, which the scenario already carries;
• which observations became findings or notes, by register id, or explicitly none.

Rules.

1. An observation is a note until it has a reproduction (§3.1). A trial log is not a finding source by itself — it is where findings are noticed.
2. The recording is the artifact for unplayed findings. GR-E03/E04 were "never played to the end"; a trial that plays them to the end both closes that finding and produces the reproduction for anything found on the way.
3. A trial whose recording does not replay is a bug in the engine, reported as one, not a design finding.

Why the log is prose and stays prose. The maintainer's "I felt it was too easy but then we lost, so who knows" is exactly the observation this protocol exists to catch: real, unreproducible as stated, and the seed of CB-WP-0025. Forcing it into a schema at the moment of observation would lose it. §3.1 is what stops it aging into an apparent finding.