Skip to content

Commit 4e57601

Browse files
committed
docs(adr): a code block inside a record is a specimen, not an example
Ruling A on objectui#8363 (director seat, decision batch #88, 2026-09-08) lands as text. CONTRIBUTING.md's `docs/` paragraph now states the convention once: a code block inside an ADR or a dated audit is a SPECIMEN of what was decided or measured, fenced `plaintext` — an unhighlighted spelling check-doc-fence-languages.mjs already lists and check-doc-snippet-types.mjs does not compile — never ts/tsx/typescript. Code a reader may copy stays in content/docs/** and skills/objectui/**, where a gate compiles it. The UNGATED_DOCS header comment in check-doc-snippet-types.mjs annotates the four ledgered rows as the terminal state: no record is edited to make it compile, no row is deleted to clear the ledger, and new records carry the convention instead so the list does not grow. Both edits are additive text. No record is edited, no ledger row is added, removed or reworded, and no gate behaviour moves. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HxLw5aKDPR5RJgyUR7Exkd
1 parent 32f1008 commit 4e57601

2 files changed

Lines changed: 13 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -425,6 +425,8 @@ We use fumadocs for documentation. The published pages live in `content/docs/**`
425425

426426
The repository root also has a `docs/` directory, and it is **not** part of the site: it holds internal engineering material (ADRs, audits, architecture notes) that the fumadocs collection never reads, so none of it is rendered or reachable at a `/docs/...` route. A page filed there never reaches the site.
427427

428+
**A code block inside one of those records is a SPECIMEN, not an example to copy.** An ADR states what was decided on a date and a dated audit states what was measured on one, so a snippet inside either is part of the record — edited until it compiles, it makes the record say something it never said. Fence such a block `plaintext` (an unhighlighted spelling `scripts/check-doc-fence-languages.mjs` already lists, and one `scripts/check-doc-snippet-types.mjs` does not compile), never `ts` / `tsx` / `typescript`. Code a reader may copy belongs in `content/docs/**` or `skills/objectui/**`, where a gate compiles it and a wrong line can be fixed without falsifying a record. Maintainer ruling 2026-09-08 (objectui#8363); the four records that predate it are not edited — they are named, with their measured counts, in that gate's `UNGATED_DOCS` ledger.
429+
428430
```bash
429431
# Start the documentation site dev server
430432
pnpm site:dev

‎scripts/check-doc-snippet-types.mjs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -917,6 +917,17 @@ const UNGATED_DOCS = {
917917
// gate already never reads — "a marker on a block the gate no longer collects is
918918
// debt nothing would ever fail to prompt the removal of", one level up. ⇒ Card 2
919919
// wrote no marker and edited no record.
920+
//
921+
// ⛔ TERMINAL STATE — these four rows are not a debt anybody may pay down.
922+
// Maintainer ruling A on objectui#8363 (director seat, decision batch #88,
923+
// 2026-09-08): a code block inside an ADR or a dated audit is a SPECIMEN of what
924+
// was decided or measured, never an example to copy. ⇒ ⛔ No record below is
925+
// edited to make it compile, and ⛔ no row is deleted to "clear" the ledger — a
926+
// row leaves only with the record it names. New ADRs and audits state the
927+
// convention instead (CONTRIBUTING.md): a specimen block is fenced `plaintext`,
928+
// which this gate does not compile, so this list does not grow.
929+
// ⚠️ Nothing else is relaxed: each of the four still owes its written reason and
930+
// is still re-derived every run against a document that really holds a block.
920931
'docs/adr/0001-master-detail-subform.md':
921932
'2 `ts` blocks (fences 142, 211), 15 diagnostics, ALL syntax-phase: TS1005 x5, TS1109 x8, TS1011 x1 — ' +
922933
'the semantic half is unmeasured, not clean. Both blocks are schema SKETCHES written in prose ' +

0 commit comments

Comments
 (0)