# Spec: the design-corpus system ``` Type: spec Status: IMPLEMENTED Status note: typed ownership, structured Design and dependency anchors, the shared corpus gate, guarded doorway, generated-page ownership, migration protocol, visible renderer roles, and spec-owned work-order metadata with a generated ROADMAP live index landed 2026-07-09 through 2026-07-10. Stage: Process Design: - wiki/process/living-spec.md#the-corpus-rule - wiki/vision/player-contract.md#the-player-contract-non-technical-law Depends on: none ``` ## Behavior “The spec” means the complete typed wiki. The `spec` in `Type: spec` is a narrower term: an agent-targetable work order inside that corpus. ## Page types ### Law A `Type: law` page states durable intent or a cross-system invariant. It owns the reason and boundary, not every implementation detail. Law pages have no status lifecycle: they are current until deliberately amended. ### Spec A `Type: spec` page owns one system. It must be precise enough to implement or audit without reconstructing the conversation that produced it. Every spec page declares: - **Status** — one exact lifecycle value. - **Status note** — optional prose explaining incomplete or unusual state. - **Stage** — `B1`, `B2`, `B3`, `Deferred`, `Release`, or `Process`. - **Design** — a structured list of the binding clauses this system realizes. Each line has the exact repository-root form ` - wiki/path.md#heading-anchor`. The target must be a `Type: law` or `Type: spec` page, the file and heading must exist, and prose is not allowed in the field. The corpus gate checks all of those properties. - **Depends on** — contracts that must be read and re-verified with this one. Use `Depends on: none` or a structured list in the exact form ` - wiki/path.md#heading-anchor`. Targets may be current law, spec, or knowledge pages; logs are history and cannot be dependencies. The system heading is an appropriate anchor when the whole target contract applies. Relationship rationale belongs in prose under `## Dependency notes`, never inline in this field. The corpus gate checks format, target, role, anchor, duplicates, and self-dependencies. - **Acceptance criteria** — observable proof that the system is implemented. ### Work-order metadata Every spec whose `Status:` is not `IMPLEMENTED` also declares the dispatch facts below in the same fenced metadata block: ```text Work order: machine-work Work priority: 10 Work class: save Blocked by: none Exclusive keys: - crates/misaligned-core/src/sim/mod.rs - crates/misaligned-core/src/save.rs ``` - **Work order** is a unique lowercase task slug and becomes the default worktree/activity id. - **Work priority** is a positive integer; lower numbers run sooner within the current stage. Stage discipline still outranks the number, so a B3 priority `1` cannot jump ahead of unfinished B1 work. - **Work class** is exactly `docs`, `frontend`, `sim`, `save`, or `process`, matching the activity helper. - **Blocked by** is either `none` or a structured list of anchored `Type: spec` references, using the same repository-root syntax as `Depends on`. This field names only hard dispatch blockers; ordinary contracts remain in `Depends on`. - **Exclusive keys** is the legacy field name for a non-empty structured list of likely edit surfaces: repository paths or logical keys prefixed with `@`. Repository paths must currently exist. Overlap is advisory and may never become a hard blocker; the name remains stable so existing spec metadata and tooling do not require a corpus-wide schema migration. `Status:` remains the lifecycle owner; no separate dispatch-state field is allowed. `tools/work_orders.py` generates the live work-order region in `process/ROADMAP.md` and provides a check mode. The hand-authored remainder of ROADMAP explains priority and history but cannot override the generated state. Implemented specs may retain work metadata as historical routing information, but are not required to declare it. ### Knowledge A `Type: knowledge` page records current-state facts. It carries no status. A code or design change that makes it stale fixes it in the same commit. ### Log A `Type: log` page is append-only history. Logs can record proposals, rejections, and superseded choices, so they never define current behavior. The owning law or spec page must contain every adopted current decision. Historical prose is immutable. A deliberate whole-corpus migration may add or repair structural role metadata such as the `Type:` block when that is needed to classify or render an existing log, but it must not rewrite the historical account. Record the exception in the migration log. ### Generated indexes Any derived page declares exactly one repository-root generator path in the same metadata block as its role: ```text Generated: tools/generator-name.sh ``` The target must exist. A generated page is a replaceable projection, never the owner of current design or historical prose. Agents edit its uniquely owned source pages and run the declared generator; the generator must provide a check mode that fails when the committed projection is stale. A generated log index is therefore exempt from log-body immutability, while the dated source logs it indexes remain immutable. `wiki/log/decisions.md` is an index, not a forever-growing current volume. Append decisions to the current dated volume under `wiki/log/decisions/` and roll to a new dated volume when the date changes. Older volumes do not receive new decisions. In every disagreement, the current owning law/spec wins over the decision history. ## Status semantics `Status:` is exactly one of: - **DRAFT** — design is still forming; do not implement except named exploratory scaffolding. - **READY** — scoped tightly enough to implement. - **IN PROGRESS** — implementation has started and criteria remain. - **BLOCKED** — an explicit decision, contradiction, or external dependency prevents progress. - **IMPLEMENTED** — all criteria hold in the sim, both frontends surface the behavior where applicable, save/load covers relevant state, and knowledge is current. Status prose belongs in `Status note:`, never beside the enum. An as-built spec may begin at IMPLEMENTED when it verifies already-shipped code. Its criteria still have to be real; unmet criteria remain explicit. ## Authority and contradictions The corpus is authoritative by role and scope: 1. Law owns enduring promises and cross-system constraints. 2. A spec owns exact behavior inside those laws. 3. Knowledge must match the current design and build. 4. Logs explain history only. A more detailed page does not silently repeal a broader law. A law/spec conflict, two specs claiming incompatible shared behavior, or knowledge that disagrees with the build is a tick finding. Fix or deliberately amend the owning pages together. Every current rule has one exact owner: - a law owns the promise, design reason, and cross-system boundary; - one spec owns each exact identifier, formula, state transition, or interface; - other pages link to that owner and label any necessary summary as non-authoritative. Shared identifiers and interfaces must therefore be stated in one owning spec and named through `Depends on`. Changing a spec includes rechecking its dependency contracts and their references back into the changed system. Duplicated exact rules are a contradiction even when their words currently match, because they create two future amendment sites. **Citations (decided 2026-07-10).** A named cross-page concept — an authored beat, a named law, another system — links its owning page at first mention in a page's prose, and a concept a spec builds on also appears in `Depends on`. A name without a link ("the Hands beat", "the flow law") forces the reader to reconstruct ownership by search; treat it as a tick finding, the same class as a duplicated rule. If a concept has no owning anchor to cite, that is the finding — give it one before citing it. Enforcement is editorial; the corpus gate checks only the structured fields. ## Stage discipline A current-stage acceptance set may contain only work achievable in that stage. Future behavior belongs in a later-stage spec or a clearly marked deferred section. Split a spec when stage boundaries are real; do not leave a current spec permanently half-implemented by hiding future work in its criteria. ## Acceptance-criteria rules Criteria are: - **Observable** through player surface, sim state, log output, save fields, or tests. - **Testable** by a future implementer. - **Scoped** to the declared stage. - **Self-contained** in the repository. - **Contract-linked** to the design promise or dependency they prove. A bug should name the violated law, spec criterion, or knowledge fact. If the corpus has no statement to violate, clarify it or raise the required human decision instead of treating the bug as vibes. ## Change rule Every behavior-changing commit amends the binding page that owns the behavior: - amend the `Type: spec` page when exact system behavior changes; - also amend the relevant `Type: law` page when the game's promise or cross-system invariant changes; - update knowledge made stale; - append decision and session history without using logs as a substitute for current design. Mechanical gates require a Rust-changing commit to include a changed `Type: law` or `Type: spec` wiki page. Every behavior-changing commit also carries a `Defense:` paragraph naming the corpus clause it implements or the reason for its amendment. ## Whole-corpus migration protocol An authority or structure migration is a semantic rebase of the repository, not a file-moving cleanup. It must land atomically enough that no commit on the main branch presents two competing authority models. Before editing, capture a baseline inventory: - headings and their destination pages; - decision-entry counts by historical volume; - every page's declared role; - current-authority phrases and retired-authority phrases; - internal links, navigation reachability, and rendered routes. During the migration: 1. Establish the new ownership and page-role model first. 2. Move current law and exact behavior into their single owners. 3. Preserve decision history verbatim except for the structural metadata exception above. 4. Rewrite entry points, instructions, skills, prompts, hooks, local checks, CI, and the public renderer in the same change. 5. Keep the root doorway intentionally weak and mechanically bounded. Before landing, repeat the inventory and prove losslessness: heading coverage, decision counts, one valid role per page, no retired current-authority wording, no broken or orphaned links, and a successful site build. After rebasing onto current `origin/main`, inspect concurrent commits semantically with targeted `git show -- ` reads. Reapply their current decisions to the new owners instead of accepting a whole-file merge that resurrects the retired structure. ## Acceptance criteria 1. [../SUMMARY.md](../SUMMARY.md) reaches every non-dated wiki page. 2. Every wiki page declares exactly one supported `Type:`. 3. Every `Type: spec` page carries Status, Stage, structured anchored Design references, structured anchored Depends on references (or exact `none`), and acceptance criteria. 4. Every Design and dependency target exists, has an allowed role, and contains the named heading; dependencies are unique and non-reflexive. 5. Status values use the exact enum. 6. A source change cannot pass the commit gates without a changed binding wiki page. 7. Root `DESIGN.md` remains a short doorway with no binding page structure, unique law, or decision history. 8. Current decisions live in their single law/spec owners; logs are historical only. 9. Local and CI corpus checks invoke the same gate script. 10. The public renderer makes every page's law/spec/knowledge/log role visible and marks the root doorway as navigation without authority. 11. Every non-IMPLEMENTED spec carries valid work-order metadata; current ROADMAP dispatch status is generated from those owning fields and checked for freshness.