docs(reference): drift sweep over all seven reference docs, and bind the version header

[stellarfeline]

What this is

A drift sweep over all seven files in docs/reference/, hunting one defect class: a fact a reader ACTS on, bound to nothing that can contradict it. Not stale prose — for every claim the question was what would fail if this became false? When the answer was "nothing", that was the finding, even where the claim happened to be true today.

No Rust behaviour is touched (git diff --name-only main...HEAD | grep -c '\.rs$' → 0). Where a doc was right and the code was wrong, it is a finding below, not a change here.

Counts

Files examined	7 of 7
Claims checked	~530 (compiler.md ~120 · tools.md ~150 · grammar.md ~230 · i18n 28 · playtest ~30 · skill-workflow ~30 · worktree-bootstrap 6)
Claims corrected	23
Claims unverifiable (reason stated)	13
Findings recorded, not fixed	11
New binding	1 gate + 14 tests

Every correction cites the command that measured it, in its commit message. Nothing was asserted from memory.

The binding: tools/check-reference-versions.py

compiler.md's first factual claim — the version header — was bound to nothing. It read delvec 0.1.0, dsl 0.8.0, dsl_version 0.2.0 … 0.8.0 while the build is at delvec 1.1.0 / dsl 0.9.0 and accepts 0.9.0. The body of that same file documented the v0.9 surface correctly; only the header a reader consults first to pick a stage envelope's dsl_version was wrong, and every gate was green because no gate related the two.

A second instance surfaced while fixing the first: the DW0102 catalog row restates the supported set by hand and had gone stale the same way. check-dw-codes.py was green on it and always would be — it proves a code EXISTS in source and doc and is asserted by a test, never that the behaviour the doc ascribes to it is the behaviour the code has.

The gate binds both by equality in both directions to crates/compiler/Cargo.toml, crates/dsl/src/envelope.rs (SUPPORTED_DSL_VERSION + SUPPORTED_DSL_VERSIONS, as an ordered sequence) and versions.toml. Equality is the point: a gate that only rejected newer than the build is exactly what let a storybook ship a v1.0 marker through the whole v1.1 release green (#342), and stale-older is the direction that actually happens — docs are written once, the build moves.

Demonstrated red on the pre-fix header and red on the DW0102 row independently, green after. 14 regression tests; verified non-vacuous by mutation (stubbing the gate's problems list empty turns 8 of 14 red). Runs as a step of the existing docs (local link check) job, so no branch-protection change — check-required-contexts.py still resolves 12/12.

Corrections worth reading

The same phantom class, three more instances. #344 removed $DELVEWRIGHT_CAMPAIGNS_DIR from worktree-bootstrap.md §1 today — an override no code has ever read. §2 of the same file carried a parallel one and was not looked at: it said the local config holds "validation ports, container tooling paths" and that absence makes "validation compose runs inherit wrong defaults silently". Nothing in validation/ reads that file; no shell script and no Rust crate reads it. Exactly two Python tools do. A worker who skipped the copy and blamed a red ladder run on it was chasing a cause that does not exist.

A "coming soon" for something that already ships. i18n.md promised the dialogue-width diagnostic was "being added separately (engine task #110)". DW0331 landed 18 hours before that line was written (bf706ce, 2026-08-03 03:44 vs the line at 21:41) — and the same file cited it as an enforced gate 165 lines earlier. A translator reading the option-label section takes a hard error for advice.

skill-workflow.md §8 item 5 was false in every word. It said ADR-0016's version line "exists on paper only" and the skill frontmatter "carries name and description and nothing else". It carries version, requires and verified_with, and check-skill-version.py binds all three.

playtest-methodology.md was asserting the exact vacuity it exists to warn about. Rule 3 claimed /new-delve "requires all four" declarations. It requires three, and the compiler enforces those (DW0460/DW0481/DW0480). Nothing requires a combat TIER — grep -n tier SKILL.md finds it only under Authoring pitfalls, and DW0477 fires on a tiered fight nobody can measure, the opposite direction. An untiered set-piece fight compiles green. Also: the findings table's 0 for round 16 read as "she played and found nothing" — round 16 was an owner playtest, four items, all already-open findings, and it opened with the rebuke rule 4 comes from.

tools.md's env-forwarding claim was false, and the first count of it was also wrong. harness/src/ reads 15 DELVEWRIGHT_* variables; validation/*.yaml declares 10. The doc said all were forwarded. The first sweep named two exceptions; measuring the set difference rather than spot-checking found four — ACTOR_FLOOR, RETRY_ON_DEATH, CUTSCENE_GRACE_MS, ENTITY_SETTLE_TIMEOUT_MS — plus NOTE_TEXT, which is not a defect (its bot runs on the host). Also: .github/scripts/mecha_crosscheck.py, ADR-0011's cross-check and a required CI job, was entirely absent (grep -c mecha → 0) from the file that claims to be the whole tool surface.

grammar.md: store_room's documented smallest region was 5 × 5 × 3; tests/staging.rs:2469 asserts [5,5,5] expands and [5,5,4] does not. §4's Program::validate list reads as exhaustive and named 9 of 11 variants. "Two anchor names are shared across rules" — there are three (anchor/landing, drop_shaft + dumbwaiter), so a zone author composing a chute and a duct hits an AnchorCollision the doc told them not to expect. And §3 described two different test suites with one sentence, crediting the staging rules with byte-comparison determinism cover they do not have.

compiler.md also gained the missing task #179 / dsl_version 0.9.0 landed-bullet (semantics read off DW0490–DW0493), and pass-order row 11 listed two-tier DW0359 only under exit 3 — it is an EclipseError and a Diagnostic::warning, and the file's own convention lists two-tier DW0489 in both places.

Findings NOT fixed

Code defects — a doc was right, or the code is wrong. Not changed here by instruction.

1. validation/compose.yaml drops four harness env vars (above). DELVEWRIGHT_ACTOR_FLOOR=0 cannot be used through the ladder at all today. This is the general form of the one-variable fix task fix(compiler): effect producers/checkpoints nested in sequences are first-class #102 already applied by hand for RUN_TIMEOUT_MS — per the debug doctrine the instance fix isn't closed until the general form is a gate.
2. crates/grammar/src/library/store_room.rs:57 carries the same false minimum ("Z ≥ 3") its doc did, and tests/staging.rs:2467 comments "3 of row" beside a check of [5,5,5].
3. crates/dsl/src/envelope.rs's SUPPORTED_DSL_VERSIONS doc comment stops at v0.8 — it enumerates what each version added and never mentions 0.9, though is_v09 below it is documented.
4. SKILL.md contradicts itself about gate 4b's images. §4b (2026-08-07, feat(tools): refimg — draw the design-alignment gate's reference images #334) says reference art drawn before any prefab exists; step 9 says the design-alignment Artifact "should have been built from" post-build player-POV renders. Both cannot hold. Likeliest: step 9 predates feat(tools): refimg — draw the design-alignment gate's reference images #334.

Process / unresolvable without an owner or planner statement.

5. skill-workflow.md §8 says "while the bell remake is running the loop for the second time". Nothing tracked in the content repo says where the bell remake stands.
6. playtest-methodology.md's closing thesis — "the owner found nothing because everything machine-findable had already been found" — rests on a session that left no artifact; no post-round-22 owner playtest is recorded anywhere.
7. CLAUDE.md's tooling-sync rule was violated by feat(tools): refimg — draw the design-alignment gate's reference images #334 (updated the skill and tools.md, not skill-workflow.md). The rule has no check.
8. The CI job i18n translation tool (pytest) actually runs all of tools/tests — it covers eight checkers. The job NAME understates its binding; renaming is the 3-step branch-protection dance, so this is a real cost, not a nit.
9. tools.md has no rows for validation/Dockerfile.*, tools/tests/, or .github/actions/checkout-content.
10. §6 of grammar.md is illustrated by show_the_metadata, a test marked ignored that "asserts nothing" (the values are pinned elsewhere; the block itself binds to nothing).
11. compose::declared_anchors and compose::SEPARATOR are undocumented public surface.

Where a check should exist and today there is only a sentence

Ordered by value. None written here — flagged for scheduling.

1. tools/check-tool-inventory.py, bidirectional. Enumerate tools/, validation/, every [[bin]]/package name, and every script path invoked from any workflow run: block; assert each appears in tools.md and that every path tools.md names exists. Red either way, with a binding count. This would have caught the missing mecha_crosscheck.py row automatically, and it is the only thing that makes that file's own opening claim true.
2. An env-forwarding gate. Every DELVEWRIGHT_* read by harness/src/ must be declared in validation/compose.yaml's bot service or allowlisted with a reason. Closes finding 1's general form.
3. DW codes outside compiler.md are unchecked. check-dw-codes.py is bidirectional against compiler.md only; the other six reference docs cite 42 DW codes that nothing validates. Measured: 41 resolve, and DW0364 (in tools.md, ci.yml and build-every-campaign.py) exists on open PR feat(dsl,compiler): spec-0026 foundation — horizon library surface, per-area walk_y datum, DW0364/DW0366/DW0367 (dsl 0.9.0) #260 and nowhere on main — legitimate today, which is exactly why this check needs a PENDING concept like check-dw-codes.py's rather than a naive membership test.
4. grammar.md is referenced by no CI job at all (grep -rn "grammar.md" .github/workflows tools/ → empty). compiler.md gets a bidirectional gate; grammar.md gets nothing. Cheapest high-value form: assert every ProgramError/ExpandError variant appears in §4 and vice versa — that would have caught the 9-of-11 list on the day it landed. The §5c zone-gate table is the model to copy: its numbers are assert_eq!ed in tests/zones.rs, which is why it alone did not drift.
5. Nothing binds skill-workflow.md to the skill it describes. check-skill-version.py holds the skill against the CLI; no check holds this doc against the skill. Its item 5 was false for two days and its gate-4b row went stale the day refimg.py landed — both would have been ordinary reds.
6. Doc integers beside constants that already have assert_eq! tests: i18n.md's "143" (CLIENT_LANGS) and "thirteen" (chrome::ALL), grammar.md's "Smallest region" cells. The numbers are restated independently of the tests that pin them, which is precisely how store_room drifted while its test stayed green.

Merge note

Four branches (feat/runtime-state, feat/on-death-root, feat/lethal-volume, spike/death-and-teleport) will each add entries to compiler.md. Every edit here was kept surgical and line-local for that reason — no section was reflowed, and no surface from those branches is documented. compiler.md's diff is 5 hunks.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AjQ5p1Kv5MrkGPumi7yXWL