Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
11 changes: 11 additions & 0 deletions scripts/check-doc-snippet-types.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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 ' +
Expand Down
Loading