KN-86 Documentation Standard: the tier ladder in the docs tree

templates and entry rules live there); definitive-articles.md (the corpus index).

This is the documentation standard going forward. Every gameplay surface carries a complete, consistently shaped document chain, and the chain doubles as the instrument for evaluating functional completeness: a title’s header declares what is designed, to what depth, and what is built; the directory READMEs aggregate those headers into a matrix.

The ladder

The four-tier game-development document ladder (Rollings & Morris), adopted 2026-07-05.

Tier	Name	Content	Language
T1	Treatment	The hook, the operator fantasy, the loop in three sentences, feasibility verdict, deferred questions. One to two pages.	Operator + diegetic. No files, no APIs.
T2	Operator spec	What the operator senses, does, and chooses: core loop, systems, verb tables, session shape, onboarding.	Operator + diegetic. A file name belongs in T3.
T3	Detailed design	Screens, behavior tables, key maps, data shapes, mission templates, generation rules, CIPHER/nEmacs contributions.	Technical nouns legal, behind seam markers.
T4	Technical	Implementation references: runtime docs, API references, ADR-governed contracts, code.	Engineering.

Entry rules (per sdlc-orchestrator): a new cart or gameplay system enters at T1; a feature inside an approved system enters at T3; a bugfix or platform chore enters at T4. Section templates for T1–T3 live in the gameplay-engineer skill’s references/artifact-templates.md.

Where the ladder applies

Cart modules (docs/software/cartridges/modules/): full T1–T3 chain per title.
First-party programs (docs/software/programs/): full T1–T3 chain per title.
Campaign archetypes, onboarding arcs, visual briefs: single-tier companion docs; each declares the one tier it lives at.
Runtime docs (docs/software/runtime/): T4 technical references. They get a one-line ladder pointer up to the T2/T3 surface they serve; they are never retrofitted with treatments.
ADRs: outside the ladder. They are decision records, and they win over any ladder doc.

Shape: one file per title, tier-labeled sections

A title’s chain lives in one file, with the tiers as top-level sections in ladder order:

# <TITLE>
<header block>

## Tier 1 — Treatment
## Tier 2 — Operator spec
## Tier 3 — Detailed design
## Migration notes            (optional; drift flags from the migration pass)

Companion docs stay separate files beside the main spec. This shape is chosen over one-file-per-tier deliberately: the house convention is already one spec per module, mass renames would break the public site and every cross-link, and the chain reads in one pass.

The header block

Every chain doc opens with exactly this block (and drops all legacy status vocabulary):

**Ladder:** T1 approved · T2 approved · T3 draft | **Impl:** partial — nokia.c, ctest
**v2.1 | 2026-07-18**

Gate vocabulary, per tier: absent · draft · approved · rejected. A tier that merged through PR review is approved; gates are bare states, never sign-off prose.
Impl: none · partial · shipped, judged against the deepest approved tier, with a link to the code, the tests, or a demo recording that evidences the claim. This field is the functional-completeness readout.
Companion docs carry the same block with a single tier entry.

Language registers and seams

T1 and T2 speak operator and diegetic nouns only. T3 and T4 may name files, FFI signatures, and ADRs, and inside a chain doc that detail sits behind the seam marker:

> **Implementation seam (GWP-xxx):** <C files, FFI names, and ADRs may appear here>

Prose rules

Prose in this tree follows prose-rules.md: only people and mechanisms act (the deck, the water, and the map do not want, wait, remember, or hear), no em dash, no first or second person, and the banned words, frames, and rhythm rules listed there. That file carries the repair table and the pre-PR check. It is the local override named in the agent-level rules at ~/.agents/writing-rules.md.

Legacy status mapping

Legacy status	Ladder reading on migration
`Definitive`, `Engineering-Ready`, `Implementation Ready`	T1–T3 content present in the monolith; re-cut under tier headings; gates `approved` (they merged).
`v1 design`	T2 `approved`; inline technical detail re-fenced as T3 (`draft` or `approved` per depth); T1 `absent` (stub owed).
`Stub`, `charter stub`, `Draft (design)`	Chain largely `absent`; stubs owed per below.

Chain stubs: fill the basics only

A missing tier gets a stub: the template headings, populated only with basics already established elsewhere in canon (the ADRs, the design bibles, the roster charter), plus open questions. Gate draft. A stub invents no design; its job is to make the gap precise and give future work a fixed place to land.

The chain matrix

../software/programs/README.md and ../software/cartridges/modules/README.md carry the aggregate table:

| Title | File | T1 | T2 | T3 | Impl |

Matrix cells mirror the doc headers. A PR that changes a header updates the matrix row in the same PR (the spec-hygiene pattern). This table is what future completeness evaluations read.

Migration rules

Content moves; it is not rewritten. Existing sections regroup under tier headings. Trimming duplication is allowed; changing meaning is not.
Stale spec values are corrected against the Canonical Hardware Specification and current ADRs (80×25 grids, CIPHER on the main grid, retired key maps). Working code wins over stale prose.
Design drift is flagged, never silently redesigned. Where a monolith’s mechanics contradict a later ADR, the migration keeps the ADR’s reading in the body and records the conflict under ## Migration notes for a design pass.
Mechanical prose repairs ride along where they do not alter meaning. The rules are in prose-rules.md; em-dash connectors and anthropomorphism are the two that show up most in the older specs.
Registration indexes are preserved. The five-place registration set for modules (modules/README.md, verb-taxonomy-map §3, mission-type-catalog §2, definitive-articles.md, capability registration) survives migration untouched except for matrix columns.