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 ' +