From 4e57601515205bdefbd5735cf1150013d5882642 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 9 Sep 2026 03:03:32 +0000 Subject: [PATCH] docs(adr): a code block inside a record is a specimen, not an example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) Claude-Session: https://claude.ai/code/session_01HxLw5aKDPR5RJgyUR7Exkd --- CONTRIBUTING.md | 2 ++ scripts/check-doc-snippet-types.mjs | 11 +++++++++++ 2 files changed, 13 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 69c37de84b..f535508edd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -425,6 +425,8 @@ We use fumadocs for documentation. The published pages live in `content/docs/**` 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. +**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. + ```bash # Start the documentation site dev server pnpm site:dev diff --git a/scripts/check-doc-snippet-types.mjs b/scripts/check-doc-snippet-types.mjs index 53f21d9f5b..5f4d17d489 100644 --- a/scripts/check-doc-snippet-types.mjs +++ b/scripts/check-doc-snippet-types.mjs @@ -917,6 +917,17 @@ const UNGATED_DOCS = { // gate already never reads — "a marker on a block the gate no longer collects is // debt nothing would ever fail to prompt the removal of", one level up. ⇒ Card 2 // wrote no marker and edited no record. + // + // ⛔ TERMINAL STATE — these four rows are not a debt anybody may pay down. + // Maintainer ruling A on objectui#8363 (director seat, decision batch #88, + // 2026-09-08): a code block inside an ADR or a dated audit is a SPECIMEN of what + // was decided or measured, never an example to copy. ⇒ ⛔ No record below is + // edited to make it compile, and ⛔ no row is deleted to "clear" the ledger — a + // row leaves only with the record it names. New ADRs and audits state the + // convention instead (CONTRIBUTING.md): a specimen block is fenced `plaintext`, + // which this gate does not compile, so this list does not grow. + // ⚠️ Nothing else is relaxed: each of the four still owes its written reason and + // is still re-derived every run against a document that really holds a block. 'docs/adr/0001-master-detail-subform.md': '2 `ts` blocks (fences 142, 211), 15 diagnostics, ALL syntax-phase: TS1005 x5, TS1109 x8, TS1011 x1 — ' + 'the semantic half is unmeasured, not clean. Both blocks are schema SKETCHES written in prose ' +