The Spec Argues Back

Fourteen numbered documents specify the design. The machinery between them does the governing: a convention for recording being wrong, a register that tracks corrections across documents and stable ids that tie code, docs and roadmap together.

The map

docs/
├── 00-project-overview.md            # index + reading orders
├── 02-design-pillars.md              # the six non-negotiables
├── 05-generation-architecture.md     # these pages' main source
├── 11-deferred-design-questions.md   # locked decisions
├── 12-propagation-register.md        # cross-document correction ledger
├── roadmaps/mvp.md                   # task-level plan (projection of roadmaps.json)
└── spikes/                           # one write-up per design spike, named by task id

What happens when the spec is wrong

Specs usually meet implementation in one of two ways: the spec quietly rots while the code moves on, or somebody rewrites it and the reasoning behind the first version disappears. This suite does a third thing. When implementation contradicts doc 05, the original text stays put, and a dated implementation note lands directly beneath it recording what shipped instead, why, and which task made the change.

A concrete run of it, from this year:

1. Doc 05 §8.3 describes decoration recursion depth as a single table keyed on craft specialisation and decorative emphasis, with two middle corners reading "technically refined" and "simple techniques".
2. Someone builds against it. The two middle corners turn out unsatisfiable by any single volume scalar: they differ by kind, not magnitude, which the table's own wording already says but a shared fill-probability term can't express.
3. The table stays exactly as written. A note dated 2026-08-06 lands directly beneath it, explaining the volume/grade split that shipped instead and citing the task (2GN.98) that made the call.
4. Anyone who learned the table finds the correction exactly where their memory points; anyone arriving fresh reads the shipped mechanism and the table it replaced in the same screenful.

The register, the spikes, the ids

Three mechanisms keep fourteen documents from contradicting each other:

• The propagation register (doc 12). Corrections ripple: a ruling that changes doc 05 usually obliges edits in other documents, and the register is the ledger that tracks each ripple from logged to applied. Fifty entries had completed at the time of writing, two pending on unbuilt Milestone 3 world-state work.
• Design spikes get standalone write-ups in docs/spikes/ holding the full argument (measurements, alternatives rejected and why), while doc 11 holds only the ruling; the reasoning and the law live at different addresses, and each spike names where its ruling landed.
• Stable task ids stitch it all to the code. A comment reading 2GN.84 resolves to the same task in the roadmap, the same doc 12 entry and the same spike, so provenance survives in all directions; several passages on these pages were written by following one id across all three.

Reading order, if you go to the source

Start with doc 02 (the six pillars), then doc 03 (the systems map), then doc 05 with these pages beside it; doc 00 carries reading orders for other purposes (implementing, reviewing, catching up on decisions). For code, src/lib/engine/prng.ts then src/lib/engine/generation/grammar.ts top to bottom. Start each module at its JSDoc block: the contracts live there, several run longer than the code beneath them, and the doc-12 cross-references inside them are load-bearing rather than decorative.