docs(requirements): design the requirements doc surface — generate the view, never annotate the docs

`meta docs` gains a third surface, `requirements`, rendering the declared ledger as
documentation: one human markdown index plus one TOON artifact, from metadata alone.

THE DIRECTION INVERTS. The original ask — annotate documents with requirement refs, then
strip them at deploy — was declined by a two-arm challenge, both arms independently: an
annotated doc is a second authoring surface that must track the model (the duplication this
project exists to remove), and "this passage depends on X" is a violation-predicate in doc
clothing, which the capability ledger already rules out. So the view is GENERATED from the
ledger. The "stripper" it needed already exists as a convention and needs no code: notes is
chartered internal-only and never emitted (documentation.json:15,39).

Why an emitter rather than a format: measured on an adopting estate, the ledger is the
disciplined system (~321 nodes, ~790 implementedBy claims, zero ERR_REQUIREMENT_*) while its
prose is not (193 of 403 specs carry no status line, 7+ unnormalised spellings). That estate
had already hand-rolled a ~165-line script to do this.

NO TEST LINK, AND THAT IS THE DESIGN. A challenge (record requirements-doc-derived-testlink,
pinned 415549d) asked whether the generated docs should scan the repo's test sources and
render a derived "verified by" while @Verifiedby stays retired from source metadata. Two arms,
same verdict from disjoint premises. The intent — observed evidence belongs in the output, not
the prescriptive source — is preserved everywhere else here; the SCAN fails on a narrower
point: there is no join key left. `name`/dotted-path are author-chosen (and `name` also keys
the future stub path, so gaming a published column would corrupt codegen identity), and
@implementedBy is disqualified BY MEASUREMENT for exactly this use — FR-038 §7 found it
"worthless for retrieval (11/24 with structured links against 12/24 with entities named in
prose)", salvaged only as a mechanical codegen input, "not a retrieval hint". It is also
L4/L5-only, so upper tiers have no key at all. Labelling it "unverified mention" reaches one
of the four audited failures; the other three are semantic and no lexical rule reaches them.
And it would put a scan-derived link against FIVE shipped statements — the migration guide,
the adopter feature doc, the capability ledger, the byte-gated agent-context skill, and the
batch plan — which is precisely the two-load-bearing-statements-disagreeing failure that
forced the retirement.

Shape A + C, not B: an index (1 file, ~11.9K tokens) plus backlinks on existing entity pages
(~466 bytes each). Page-per-L1 is dominated on measurement — 19 files, ~30.5K tokens, one page
at 86KB. C is also why this beats a standalone script: only something inside the codegen
pipeline holds both halves of the model.

TOON for the declared-count header, NOT the token saving — measured with the real encoder on
321 rows it is 42.1% smaller than JSON but only 7.3% smaller than a markdown table, which is
already header-once. `requirements[321]{...}:` lets a reader verify it got all 321. It reuses
what exists: @toon-format/toon is already a cli dependency and toonEncode already established
"humans at a terminal get text; pipes/agents get TOON" (format.ts:17-18). TOON quotes every
comma-bearing string, which is why prose stays in the markdown and structure in the TOON.

Both files emit unconditionally rather than behind --format: `meta docs` writes FILES while
--format selects a STDOUT encoding, and a drift gate wants the machine artifact committed
regardless of who ran the command.

The surface reads metadata and nothing else — docs.ts:1-12 guarantees output "from metadata
ALONE", and that one sentence is what rules out the scan. An empty ledger emits NOTHING (not
an empty page), which is what makes default-on a no-op for every project without requirements.

The test link returns structurally once requirementTests() ships, as a derived path rather
than an inference — with the tension stated rather than papered over: the stub path is an app
seam living in gen config, which this command does not read. The precedent is the `api`
surface, which materialises only with a loadable config (docs.ts:412) — config-gated
enrichment on a metadata-alone surface, so rule 1 stays intact instead of quietly eroding.

Verification is built around the failure that matters — a doc generator that silently drops
rows looks complete and is not: the TOON count must equal rows emitted on a NESTED fixture (a
flat one cannot tell a depth-first walk from top-level-only), `notes` must appear in no
artifact on a fixture carrying BOTH description and notes (one alone cannot tell suppression
from absence), an unclaimed entity's page must stay byte-identical, and no test link may emit
even when requirement names exactly match real test files — the case that would regress the
ruling silently.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: dmealing

docs/superpowers/specs/2026-08-21-requirements-doc-surface-design.md

@@ -0,0 +1,280 @@
+# The requirements documentation surface — generate the view, never annotate the docs
+
+**Status:** design, ready to plan. Additive; no vocabulary change, no breaking change.
+**Depends on:** nothing. **Unblocks:** the structural test link, once FR-038 ships (§7).
+
+`meta docs` gains a third surface, `requirements`, that renders the declared `requirement.*`
+ledger as documentation. It emits two files: one for people, one for machines. It reads
+metadata and nothing else.
+
+---
+
+## 1. The problem, measured
+
+A capability ledger and a documentation set answer overlapping questions, and only one of them
+is disciplined.
+
+Measured against an adopting estate (an external project; the numbers are reported here, not
+reproducible from this repository):
+
+| | |
+|---|---:|
+| requirement nodes in the ledger | ~321 |
+| `@implementedBy` claims across them | ~790 |
+| `ERR_REQUIREMENT_*` diagnostics on a `verify` run | **0** |
+| that project's specification documents carrying **no** status line | 193 of 403 |
+| distinct unnormalised spellings of status found in prose | 7+ |
+
+The ledger is loaded, validated and gated in five language ports. The prose is not checked by
+anything. That estate had already hand-written a ~165-line script to render a registry view out
+of its own ledger — the demand signal for this feature, and evidence that the missing piece is
+an emitter rather than a format.
+
+## 2. The direction inverts — the ruling that shapes everything below
+
+The original request was the opposite of this design: **annotate the documents with requirement
+references, then strip the annotations at deployment.** That was declined by a two-arm
+challenge, both arms independently, on two grounds:
+
+1. An annotated document is **a second authoring surface that must track the model** — the
+   duplication this project exists to remove.
+2. "This passage depends on `@promptStyle` living on `template.prompt`" is a
+   **violation-predicate wearing documentation clothing**, which
+   [`spec/capability-ledger.md`](../../../spec/capability-ledger.md) already rules out.
+
+**So the doc view is generated FROM the ledger.** Nothing is authored twice, and the view cannot
+drift from the model because it has no independent existence.
+
+The "stripper" the original ask needed **already exists as a convention** and requires no code:
+`description` is chartered user-facing and `notes` is internal-only, never emitted to generated
+user-facing documentation ([`spec/metamodel/documentation.json:15,39`](../../../spec/metamodel/documentation.json)).
+This surface honours that split; it does not reinvent it.
+
+## 3. There is no test link, and that is deliberate
+
+**Decided by challenge on 2026-08-21** (record: `requirements-doc-derived-testlink`, pinned at
+`415549d63`; two arms, same verdict, reached from disjoint premises).
+
+The question put was whether the generated documentation should **scan the repository's test
+sources** and render a derived "verified by" link, with the `@verifiedBy` attribute staying
+retired from source metadata. The intent behind it is sound and is preserved everywhere else in
+this design — *observed evidence belongs in the output, not in the prescriptive source.* The
+scan fails on a narrower and more concrete point.
+
+**There is no join key left to scan on.**
+
+- **`name` / the dotted path** are author-chosen. The retirement's argument —
+  *"the author picks the string, so the cheapest way to satisfy the check is to find a name
+  that already exists"*
+  ([`verified-by-retirement.md:111-115`](../../features/migrations/verified-by-retirement.md)) —
+  applies verbatim, and worse: the requirement `name` also keys the future generated stub path
+  (§7), so gaming a published column would corrupt codegen identity.
+- **`@implementedBy` is disqualified by measurement, for this exact use.** FR-038 §7 records
+  that round 5 of the requirements investigation found it *"worthless **for retrieval** (11/24
+  with structured links against 12/24 with entities named in prose)"*, and salvages it only as
+  *"a **mechanical** codegen input … not a retrieval hint"*
+  ([design §7](2026-08-15-fr-038-requirement-derived-test-stubs-design.md)). Structured links
+  scored **worse than prose**. A documentation scan is retrieval.
+  It is also legal on **L4/L5 only** ([`spec/metamodel/requirement.json:69-76`](../../../spec/metamodel/requirement.json)),
+  so the upper tiers of any ledger have no key at all; and it is unbounded where present — one
+  architectural requirement claimed by 123 entities would render as "verified by" essentially
+  every test in the estate.
+- **The corpus classifier is gone too.** The deleted scan's own module header called its
+  test-file patterns *"a GUESS about someone else's repository"*, and the seam that let a
+  project correct it (`verify.testFiles`) was deleted with it.
+
+**Labelling it "unverified mention" does not rescue it.** Comment-only matches were already
+downgraded to a warning, which reaches one of the four audited failures; the other three are
+semantic, and no lexical rule reaches them
+([`verified-by-retirement.md:113-115`](../../features/migrations/verified-by-retirement.md)).
+
+**And it would contradict five shipped statements**, which is the specific failure that forced
+the retirement in the first place — two load-bearing statements disagreeing about this same
+vocabulary:
+
+| where | what it says |
+|---|---|
+| [`docs/features/migrations/verified-by-retirement.md:118-126`](../../features/migrations/verified-by-retirement.md) | "Nothing yet, deliberately … the replacement inverts the direction" |
+| [`docs/features/requirements.md:167-177`](../../features/requirements.md) | adopter-facing: tying a requirement to a test "is instead the job of a generator that emits the test **from** the requirement" |
+| [`spec/capability-ledger.md:234-244`](../../../spec/capability-ledger.md) | `verifiedBy` — RETIRED |
+| `agent-context/skills/metaobjects-verify/references/requirements.md:59-64` | agent-facing, **byte-gated** in `agent-context-conformance` |
+| [`docs/superpowers/plans/2026-08-21-coordinated-pre-1.0-breaking-batch.md:50`](../plans/2026-08-21-coordinated-pre-1.0-breaking-batch.md) | "a requirement with no test link is a legitimate declared state" |
+
+**So the surface prints no test link at all, and says so.** Silence here is consistent with
+five shipped statements rather than a gap in the output. The structural replacement arrives in
+§7.
+
+## 4. Shape: an index, plus backlinks — not a page per node
+
+Three shapes were measured. (Token counts from the same external estate; reported, not
+reproducible here.)
+
+| shape | output | verdict |
+|---|---|---|
+| **A** — one index page | 1 file, ~11.9K tokens | **adopt** |
+| **B** — page per L1 node | 19 files, ~30.5K tokens, one page at **86KB** | **dominated** — strictly more output, worse to read, worse to diff |
+| **C** — backlinks on existing entity pages | ~466 bytes average per page | **adopt** |
+
+**A + C.** The index is the readable whole; the backlinks put the claim where the reader
+already is. B is rejected on measurement, not taste — an 86KB page is not a documentation page.
+
+**Shape C is the reason this beats a standalone script.** A hand-rolled registry generator can
+produce A. Only something inside the codegen pipeline can add "this entity is claimed by these
+requirements" to the entity's own page, because only it holds both halves of the model.
+
+## 5. Two artifacts, both emitted unconditionally
+
+### `requirements.md` — for people
+
+The index. Requirement nodes in ledger order, nesting preserved (hierarchy **is** nesting), each
+carrying `@statement`, `@violation`, `@level`, `@status`, `@disposition`, `@trackedBy` and its
+resolved `@implementedBy` targets.
+
+`description` is emitted. **`notes` is not**, per
+[`documentation.json:15,39`](../../../spec/metamodel/documentation.json) — it is the
+internal-only slot, and the whole point of the charter is that a generated user-facing document
+honours it without anyone remembering to strip anything.
+
+### `requirements.toon` — for machines
+
+The same data, TOON-encoded. **The reason is the declared-count header, not the token saving.**
+
+Measured with the real `@toon-format/toon` encoder on 321 rows: TOON is **42.1% smaller than
+JSON but only 7.3% smaller than a markdown table** — a table is already header-once, so the
+compression argument is nearly absent. What TOON adds is:
+
+```
+requirements[321]{path,level,status,claims,statement}:
+```
+
+A reader can verify it received all 321 rows. That is worth more than 7.3%.
+
+This reuses infrastructure that already exists: `@toon-format/toon` is already a dependency of
+`@metaobjectsdev/cli` (`package.json:61`) and `toonEncode` already lives in
+[`lib/format.ts`](../../../server/typescript/packages/cli/src/lib/format.ts), which established
+the convention at `:17-18` — *"humans at a terminal get text; pipes/agents get TOON."*
+
+**Caveat, stated because it constrains the split:** TOON quotes every comma-bearing string, so
+prose dilutes it badly. That is precisely why prose belongs in the markdown and structure
+belongs in the TOON, rather than either file trying to be both.
+
+### Why both, unconditionally, rather than a `--format` flag
+
+`meta docs` **writes files**; `--format` on `gen`/`migrate` selects a **stdout** encoding. Reusing
+the flag name would make it mean something materially different on this command. And a drift
+gate wants the machine-readable artifact committed regardless of who ran the command or from
+what kind of terminal.
+
+## 6. The surface contract
+
+`DocsSurface` gains a third member
+([`metaobjects-config.ts:195`](../../../server/typescript/packages/codegen-ts/src/metaobjects-config.ts)):
+
+```ts
+export type DocsSurface = "model" | "api" | "requirements";
+```
+
+plus a `--requirements` CLI flag, narrowing markdown surfaces exactly as `--model` / `--api` do.
+`--site` and `--metamodel` are **not** surfaces — they are separate branches in `docs.ts` — so
+nothing there changes.
+
+**Three rules govern it:**
+
+1. **Metadata alone.** `meta docs` guarantees it emits *"from metadata **ALONE** — no gen
+   config, no codegen pipeline … The neutrality of the output is therefore guaranteed"*
+   ([`docs.ts:1-12`](../../../server/typescript/packages/cli/src/commands/docs.ts)). This
+   surface introduces **no** new input. That single sentence is what rules out §3's scan, and
+   it must keep being true.
+2. **An empty ledger emits nothing** — not an empty page. A project declaring no `requirement.*`
+   nodes sees no change at all, matching the feature's existing posture (no requirement nodes ⇒
+   no diagnostics). This is what makes adding `requirements` to the default surface list safe.
+3. **Default on.** `surfaces` defaults to `["model", "api"]` today; it becomes
+   `["model", "api", "requirements"]`. Rule 2 is what makes that a no-op for every project
+   without a ledger.
+
+## 7. The test link returns structurally, later
+
+When `requirementTests()` ships (FR-038 slice 1,
+[plan](../plans/2026-08-16-fr-038-requirement-test-codegen.md), targeting 1.1), it emits
+`tests/requirements/<requirement dotted path>.<concern>.test.ts`. The link then becomes a
+**derived path, not an inference** — no scanning, nothing matched, nothing guessed.
+
+**One tension must be resolved before that lands, and it is not resolved here.** The stub's
+location is an app seam (design §6, `path`) and §13 leaves "where do stubs live" an open
+default. So the stub path lives in **gen config** — which rule 1 above says this command does
+not read.
+
+The precedent for that already exists in the same file: the `api` surface materialises only
+with a loadable gen config, *because* api docs describe a generated surface that only exists
+when there is one ([`docs.ts:412`](../../../server/typescript/packages/cli/src/commands/docs.ts)):
+
+```ts
+const apiSelected = docsCfg.surfaces.includes("api") && loadedConfig !== undefined;
+```
+
+A structural test link takes the same shape: **config-gated enrichment on a metadata-alone
+surface.** Absent a loadable config, the requirements surface still emits — just without the
+link. That keeps rule 1 intact rather than quietly eroding it.
+
+**A stronger form worth preferring if it is cheap:** have the generated stub carry a
+machine-readable back-reference to its requirement's FQN. Documentation reading a *generated
+artifact's own declaration* is derivation; documentation matching strings in prose is not.
+
+## 8. The spec-citation slot is a separate defect, and A does not dissolve it
+
+A generated index reproduces a citation like `title: "FR-448 — …"` as **inert text**. It renders
+it; it does not resolve it. So the citation problem survives this feature.
+
+**But it is better posed as field overloading than as "free text needs a check."** A citation is
+living in a node's display label *because there is nowhere else for it to live* — `title` is a
+noun phrase, and a citation is not a name. Framed that way it is a candidate for the
+[ADR-0037](../../../spec/decisions/ADR-0037-metamodel-vocabulary-expansion-decision-framework.md)
+decision procedure, which the "add a check to free text" framing could never pass.
+
+Note the shape of the nearest precedent before proposing vocabulary: `@trackedBy` (0.23.0) is
+free-form and **deliberately never resolved**, because `verify` has no network and two systems
+holding the same answer will drift. Any citation slot must say why it differs — or reuse
+`@trackedBy` and stop there. **Out of scope for this design**; recorded so it is not mistaken
+for something this feature delivered.
+
+## 9. Verification
+
+The gate that matters is not "a file was emitted." It is that the emitted view **cannot silently
+lose the ledger**, since a documentation generator that quietly drops rows produces a document
+that looks complete and is not.
+
+- a **`codegen-conformance` fixture** whose model carries a nested `requirement.*` tree, gating
+  both artifacts byte-for-byte — this is the mechanism that keeps A and C in agreement
+- the TOON header's declared count **equals** the number of rows emitted, asserted on a fixture
+  with nesting (a flat fixture cannot tell a depth-first walk from a top-level-only one)
+- a model with **zero** requirement nodes emits **no** requirements file — proving rule 2, which
+  is what makes the default-on decision safe
+- **`notes` appears in no emitted artifact**, asserted on a fixture where a requirement carries
+  both `description` and `notes` — a fixture with only one of them cannot tell suppression from
+  absence
+- shape C: an entity claimed by a requirement gains its backlink; an unclaimed entity's page is
+  **byte-identical** to today's
+- **no test link is emitted under any input**, including a model whose requirement names exactly
+  match real test files in the repo — the case that would regress §3 silently
+- the surface is proven able to fail: sabotage the fixture and watch the lane go red, per this
+  repository's standing rule that a gate never demonstrated failing is decorative
+
+## 10. What this does not solve
+
+- **It does not check the prose.** 193 of 403 documents carrying no status line stay that way;
+  this generates a parallel view, it does not conscript the existing corpus.
+- **It does not prove a requirement is met.** No documentation surface can. The unfakeable
+  formulation remains `@violation`-driven mutation, which is out of scope for the same reason it
+  is out of scope for `verify`: *"it never runs them"* is byte-gated across five ports.
+- **It is TypeScript-only at first.** `meta docs` is a Node-CLI-owned surface. Nothing here
+  blocks a per-port equivalent, and nothing here requires one.
+
+## 11. Open questions
+
+- **Where does the requirements index sit relative to `outputLayout`?** The model surface follows
+  the project's layout; an index is a single root-level page and may want to ignore it.
+- **Does shape C's backlink belong on projections and values, or only on entities?** Object
+  coverage is entity-grain today ([`spec/capability-ledger.md:285-296`](../../../spec/capability-ledger.md)),
+  which argues for entities only.
+- **Does the TOON artifact belong under the docs `outDir` at all**, or beside the metadata? It is
+  a machine artifact in a directory otherwise meant for humans.