@nurix/etna 0.20.35 → 0.20.36

package/data/harnesses/delivery/skills/documentation/references/source-comments.md

@@ -0,0 +1,19 @@
+# Source comments — what stays in the file and what moves to docs
+
+Load when: writing or sweeping source-file comments, or cutting a comment whose claim belongs in a document. Not needed to write a document.
+
+**In `docs/`, never in the file's comments** — and this skill is the half of that rule that makes it safe. A source file carries a repo-relative path header of two or three present-tense sentences and one third-person sentence above each non-obvious function; the shape is the harness's `CLAUDE.md` § File Structure, which is canonical and is not restated here. That header's `docs/…` path is also the file's edge into the knowledge graph: the header pointer names the document that speaks for the file, which is how ownership is computed ([`frontmatter.md`](frontmatter.md)). What lands **here** is everything that shape displaces: design rationale, the alternatives weighed, the measurement behind a constant, the reason an obvious-looking change is wrong.
+
+**Cutting a comment is a move, not a deletion.** A claim taken out of a source file is owed one of two things before the cut is done, and the choice is per claim, not per file:
+
+| The claim is | What it earns |
+| --- | --- |
+| Worth keeping, and its doc does not state it | A section in the **owning feature doc** (the ownership index resolves which), carrying the claim and the argument for why the codebase is worse without it — never the comment's wording, which was written for a reader holding the code |
+| Already stated in its doc | Nothing — but you **open that doc and find the sentence** before saying so. An assumed duplicate is how a claim is lost |
+| History, a ticket or decision-record reference, a dated note, a divider, or narration of code that no longer exists | Nothing, and no record. A record lives in `docs/history/`; these are not claims about the present |
+
+**Count what you cut, and prove the cut was only comments.** A comment sweep states comment lines before and after per file, so a drop nobody accounted for is visible as a number rather than as a feeling. [`scripts/comment-strip.mjs`](../scripts/comment-strip.mjs) turns that from a claim into a check: it strips comments from both revisions — honouring strings, template and character literals, regex literals, raw strings and JSX comment braces — and diffs what is left, so a sweep that quietly changed executable code cannot pass as a cleanup. `comment-strip.mjs --rev <before> --to <after> <paths…>` exits 0 for "no executable code changed" and 1 naming the file and the first diverging line. Run it over any pass that touches more than a handful of files; a sweep without it is an assertion.
+
+**The mechanical half of the shape is checked, not remembered.** [`scripts/source-lint.mjs`](../scripts/source-lint.mjs) `--changed` reports a header that names another path or none, a change whose added lines are over a quarter comments, and the four shapes the convention deletes outright — narration, ALL-CAPS emphasis, an over-long header, a comment block that has become a document. Block-severity findings must be fixed; the escape hatch is a `source-lint-disable: <id>` comment with the reason in a second comment beside it, and the only finding that legitimately takes one is a booby trap. The harness detector raises a bookkeeping row for the same condition, so an unfixed breach outlives the session that wrote it.
+
+**Never convert a booby trap into a one-liner.** A comment whose subject is a danger on an edge that looks safe — a pinned dependency's limitation, a measurement that justifies a narrow allowlist, a two-clock interaction — is load-bearing where it sits, because the reader who needs it is mid-edit and will not go looking. Compress it if it rambles; do not relocate it. The tell is that the comment names a version, a measurement, or a condition under which it expires.

package/data/harnesses/delivery/skills/documentation/references/style-guide.md

@@ -11,7 +11,7 @@ A document is read by a person who wants to understand something or to act on it
 
 ### Principles
 
-1. **Two natures:** every document is a truth document (what is, now, rewritten in place) or a record (what happened, dated and frozen). A truth document never narrates history and a record is never edited to match the present, because a reader must be able to trust each without the other.
+1. **Three natures:** every document is a truth document (what is, now, rewritten in place), a record (what happened, dated and frozen) or a queue (work not done yet, rows appended and deleted when resolved). A truth document never narrates history, a record is never edited to match the present, and a queue holds only open rows, because a reader must be able to trust each without the others.
 2. **The outside-in shape:** an explaining document opens on the question it answers and its boundary, then the model with its numbered principles, then the parts and their relations, then each part's decisions, and stops at its genre's deepest layer. Each layer is complete on its own, so a reader who stops at any layer holds a picture that is coarse but true, never a teaser the next section completes.
 3. **The stability test:** a sentence that would have to change when a function is renamed, a file moves, a route, column, error code or cookie attribute changes, or a constant is retuned without the design changing belongs to the code, which the code graph computes on demand (`docs/architecture/systems/knowledge-layer.md`), and not to the document. A copy typed into a document is at best a duplicate of the code and at worst a stale one.
 4. **The authority split:** the code is the authority on *what*; the document is the authority on *why*. A disagreement on *what* means the document is stale and the code wins; a disagreement on *why* or on an invariant is a defect to raise, because one side is wrong on purpose.
@@ -32,9 +32,10 @@ Every genre takes the same shape (principle 2) and the same labels (principle 5)
 | Feature (`docs/features/`) | Truth | The behaviour a person meets, in full: each state the surface can be in, each edge case, what a refusal tells them, the wording where the wording is promised. This genre runs deepest toward its end, in Promises, because a promise is checked by a person or a test and the code cannot state it as intent | Columns, routes, guards, functions, files |
 | Reference (API reference, environment registry) | Truth | The contract itself: signatures, shapes, variables | Nothing. The detail is the point |
 | Operations procedure, migration runbook | Truth, record | The exact commands, in order, with their expected output | Nothing. The detail is the point |
-| Record (plan, changelog entry, journal, memory) | Record | Its template's fields, as of the moment it describes | Nothing. Its prose follows § Voice and § Labels; the dates and the journey are its own |
+| Record (plan, changelog entry, runbook) | Record | Its template's fields, as of the moment it describes | Nothing. Its prose follows § Voice and § Labels; the dates and the journey are its own |
+| Queue (backlog, journal, bookkeeping, memory) | Queue | One row per open item, in its template's row grammar | Nothing. A row may carry its own date; a resolved row is deleted |
 
-- **Owning documents:** feature, package and system are the three genres that speak for code: source files name them in their headers, and the ownership scan resolves paths to them (`frontmatter.md`). They take principles 5 and 6 in full, their sections are fixed (§ Owning documents — the body and the footer), and `doc-lint` reads them.
+- **Owning documents:** feature, package and system are the three genres that speak for code: source files name them in their headers, and the ownership scan resolves paths to them (`frontmatter.md`). They take principles 5 and 6 in full, their sections are fixed (§ Owning documents — the body and the footer), and `doc-lint` reads them. A UX document also speaks for a surface's components where none of the three does; its sections are its own genre's (`templates/ux-behavior.md`).
 - **Doctrine:** the same shape and labels as an owning document, speaking for no code and describing no mechanism. Its model layer may argue in paragraphs; below the model it is bullets like every other explaining document.
 - **Reference documents and procedures:** the one place a signature, a shape, a variable table, a command list or a file path is the content. They keep the detail the owning genres hand to the graph (§ Reference documents).
 - **Indexes:** a folder's `Readme.md` describes directories, never files — no link, filename or record ID per file; each file's own `description:` frontmatter is its account. The root README follows `templates/root-readme.md`. Both take § Labels.
@@ -51,6 +52,16 @@ Every truth document a person reads to understand something is written from the
 4. **Each part in turn:** for each part, the decisions it rests on and why. A part's section opens with why the part exists, never with how it is built.
 5. **The genre's deepest layer:** the row for the genre in § The genres, and nothing deeper.
 
+An owning or doctrine document's fixed sections carry these layers; nothing is added beside them to hold a layer:
+
+| Layer | Feature | System | Package | Doctrine |
+| --- | --- | --- | --- | --- |
+| The question and its boundary | Goal line, Scope | Opening paragraph, Scope | Identity and goal lines, Scope | Opening paragraph |
+| The model | Scope's Covers bullet | Flow's opening | Usage's opening | The model |
+| The parts | Flows | Flow | Ownership, Usage | The parts |
+| Each part's decisions | Decisions | Decisions | Decisions | The parts in depth |
+| The deepest layer | Promises | Promises | Promises | — |
+
 ### The stability test
 
 The test (principle 3) decides what a sentence may say. These survive it:
@@ -62,7 +73,9 @@ The test (principle 3) decides what a sentence may say. These survive it:
 - **Cross-component contracts:** what no single file shows, such as two clients that must classify the same answer identically.
 - **Decided-but-unbuilt intent:** what the code cannot reveal because it does not yet do it, wrapped in `<!-- UNBUILT:START — {what, and the evidence it is not built} -->` … `<!-- UNBUILT:END -->` in plain words. A design decided *against* carries no marker.
 
-The authority split (principle 4) is stated in the opening of any document whose readers include agents, so a reader who finds the code and the document disagreeing knows which way to resolve it.
+Unbuilt work has one home per kind. Decided design the code does not do yet is an `UNBUILT` block where the design is stated; a shortfall in what is built (a promise the code does not keep, a case it mishandles) is one bullet under Gaps; the work that would close either is a backlog row, and the document never tracks that work's progress.
+
+The authority split (principle 4) is stated once, where agents enter the docs (the root instruction file or `docs/README.md`), so a reader who finds the code and the document disagreeing knows which way to resolve it. A doctrine document restates it in its model where its readers would otherwise not know; a feature, package or system document never does, because its opening is fixed to its goal.
 
 ### Diagrams and length by layer
 
@@ -144,11 +157,12 @@ A feature adds its pages, because an address is what a person points at; a packa
 
 ## The Two Natures — tense and history
 
-Every document is a truth document or a record (principle 1); `SKILL.md` § The Two Natures gives the split, the folders and the lifecycle. The tense rules follow directly.
+Every document is a truth document, a record or a queue (principle 1); `SKILL.md` § The three natures gives the split and the genre registry (`templates/Readme.md`) gives each genre's nature. The tense rules follow directly.
 
-- **Truth documents:** everything outside `docs/history/`, `docs/research/` and `docs/memory/` states what the system *is* and how it works *today*, as if it had always been so. The journey (dates, migrations, progress) lives only in records.
+- **Truth documents:** every genre the registry marks `truth` states what the system *is* and how it works *today*, as if it had always been so. The journey (dates, migrations, progress) lives only in records.
 - **The one bridge:** an Architecture Decision's **Decision Changelog** tail carries that decision's dated revision history while its body stays current-truth-only; head is truth, tail is provenance. No other truth document carries a dated line, apart from the frontmatter's tooling keys and a dated path inside a link or code span, which cites a record rather than claiming a date. The `maintenance` agent's Health Log is a record of its own (`docs/history/health-log.md`), not a tail.
 - **Records:** never edited to match the present. A frozen plan stays wrong-in-hindsight; a changelog entry describes what shipped as it shipped. A scope change gets a new dated record that links back.
+- **Queues:** a row is appended when the work appears and deleted when it is done, drained or promoted, never marked done in place. A row may carry its date; nothing else in a queue is edited.
 
 | ❌ Historical narration (a record's) | ✅ Present-tense fact (the truth document's) |
 | --- | --- |
@@ -239,7 +253,7 @@ flowchart LR
 - **Retrieval keys:** search and agents retrieve a section out of context, where a bare `### Failures` reads identically across every document. A generic `###` heading, and every heading in an untemplated document, is qualified by its topic (`### Sign-in failures`, `### Merge rules — data sync`) so it stands alone when retrieved. A short document whose H1 disambiguates can keep bare headings.
 - **Sentence case:** headings are sentence case; a product, a proper name or a named concept (`The Two Natures`) keeps its own casing.
 - **No hard-wrapped prose:** a paragraph is one line in the source (`.prettierrc.json` keeps `proseWrap: never`); the renderer wraps it.
-- **No empty stubs:** a section with nothing real to say is omitted; an explicit "None" is written only where the absence itself is information (`SKILL.md` § The Two Natures).
+- **No empty stubs:** a section with nothing real to say is omitted; an explicit "None" is written only where the absence itself is information (`SKILL.md` § Truth documents).
 - **No file rosters:** a file list belongs in no document. The ownership index and the code graph answer "which file" for every genre, and a folder index describes directories, never files.
 - **The reference-document layout:** a document that is not an owning genre and whose content is the contract itself (an API reference, an environment registry, a procedure's appendix) opens on its goal, as a `**Goal:**` line or one sentence, and proceeds straight to its contract or procedure sections:
 

package/data/harnesses/delivery/skills/documentation/references/untemplated.md

@@ -6,10 +6,11 @@ A template is a pre-made set of shape decisions. With no template, make the same
 
 ## 1. Decide the nature — truth or record
 
-Every document is exactly one (`SKILL.md` § The Two Natures). Ask: *when reality changes, is this file rewritten, or is it frozen?*
+Every document is exactly one (`SKILL.md` § The three natures). Ask: *when reality changes, is this file rewritten, frozen, or does it lose a row?*
 
-- Rewritten in place → **truth document**. Topic-named (`kebab-case.md`), lives outside `docs/history/`, present tense throughout — the iron rule in `SKILL.md` § Present tense, always.
-- Frozen or append-only → **record**. Date-named (`YYYY-MM-DD-slug.md`), lives in `docs/history/` — inside an existing subfolder where it fits (an investigation or research writeup → `history/research/{topic}/`); a genuinely new category of record needs a `docs/structure.md` folder-rule row in the same change, never an invented folder.
+- Rewritten in place → **truth document**. Topic-named (`kebab-case.md`), lives outside `docs/history/`, present tense throughout — the iron rule in `SKILL.md` § The three natures.
+- A list of open work whose rows are added and deleted → **queue**. A fixed name, one row per item; extend an existing queue before inventing one.
+- Frozen → **record**. Date-named (`YYYY-MM-DD-slug.md`), lives in `docs/history/` — inside an existing subfolder where it fits (an investigation or research writeup → `history/research/{topic}/`); a genuinely new category of record needs a `docs/structure.md` folder-rule row in the same change, never an invented folder.
 
 When a draft wants to be both — the current state *and* the story of getting there — split it: the state becomes a truth document, the story becomes a record that links to it. Never mix the natures in one body.
 
@@ -17,7 +18,7 @@ When a draft wants to be both — the current state *and* the story of getting t
 
 - `docs/structure.md` is the placement authority — match the document's topic to its folder map before inventing a location.
 - **One canonical home per topic.** If a document on the topic already exists, extend it; a second document on the same topic is drift waiting to happen. Link, don't copy.
-- A new topic *folder* gets a `Readme.md` landing page that introduces and indexes it.
+- A new topic *folder* gets a `Readme.md` landing page that describes what the folder holds and how its files are named, never a row per file (`type: folder-index`).
 
 ## 3. Shape it
 
@@ -35,6 +36,6 @@ When a draft wants to be both — the current state *and* the story of getting t
 
 ## 5. With a human in the loop — the co-authoring workflow
 
-**Stage 1 — context gathering.** Ask: audience? purpose? existing format to match? Have the user dump all the context they hold, then ask 5–10 clarifying questions before proposing anything.
+**Stage 1 — context gathering.** Read what already exists on the topic, then draft the structure from §1–3 with sensible defaults for audience, purpose and format. Ask only the questions whose answer the repository cannot give and a default would get wrong (usually one to three), each with your recommended answer, in one message.
 
-**Stage 2 — structure & draft.** Propose the section structure from §1–3 above, then draft section by section. The user indicates changes — learn their style from their edits; don't silently rewrite them.
+**Stage 2 — draft.** Show the structure with the questions, then draft the whole document on the answers or the defaults. The user indicates changes — learn their style from their edits; don't silently rewrite them.

package/data/harnesses/delivery/skills/documentation/scripts/doc-lint.mjs

@@ -1,49 +1,147 @@
-// skills/documentation/scripts/doc-lint.mjs - mechanical checks over markdown docs (tense narration, dates, stubs, redirects)
+// skills/documentation/scripts/doc-lint.mjs - mechanical checks over markdown docs (tense and history narration, dates, redirect stubs, frontmatter, index shape, owning-document body)
 // Usage: node doc-lint.mjs <file.md ...> | node doc-lint.mjs --changed   (git-changed + untracked .md)
-// Exit 1 when any block-severity finding survives. Escape hatch: <!-- doc-lint-disable: id[, id] --> (file-wide, or on the offending line).
+// Exit 1 when any block-severity finding survives. Escape hatch: <!-- doc-lint-disable: id[, id] --> alone on its
+// own line (file-wide, with a reason comment beside it) or at the end of the offending line (that line only).
+// Genre facts (nature, type, location, required keys and sections) come from ../templates/Readme.md § Registry.
 
 import { readFileSync, existsSync, statSync, readdirSync } from 'node:fs';
 import { execSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+
+const MONTH = '(?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|June?|July?|Aug(?:ust)?|Sep(?:t(?:ember)?)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?)';
+const DATE = new RegExp(`\\b20\\d{2}[-/.]\\d{1,2}[-/.]\\d{1,2}\\b|\\b\\d{1,2}/\\d{1,2}/20\\d{2}\\b|\\b${MONTH}\\.? (\\d{1,2},? )?20\\d{2}\\b|\\b\\d{1,2} ${MONTH}\\.? 20\\d{2}\\b`);
 
 const RULES = [
   { id: 'stale-tripwire', severity: 'block', scope: 'truth', pattern: /treat (any )?[\w`./-]+ ?(references? )?as stale|superseded (by|the)|\bused to (be|target|live|hold)\b/i, message: 'stale-reference tripwire / supersession talk — fix the references, state the present fact' },
-  { id: 'history-narration', severity: 'block', scope: 'truth', pattern: /\bno longer\b|\bwas (renamed|removed|extracted|folded|migrated|replaced)\b|\bmoved (to|from|into) [\w`./-]+ \(?20\d{2}/i, message: 'history narration — the journey belongs in a dated record' },
+  { id: 'history-narration', severity: 'block', scope: 'truth', pattern: /\b(was|were|has been|have been) (renamed|extracted|folded|migrated|replaced|superseded)\b|\bmoved (to|from|into) [\w`./-]+ \(?20\d{2}/i, message: 'history narration — the journey belongs in a dated record' },
+  // A ticked box in a committed checklist or procedure records one run's state inside a document about the present.
+  { id: 'ticked-checkbox', severity: 'warn', scope: 'truth', only: /(^|\/)docs\/(tests|operations|acceptance)\//, pattern: /^\s*[-*] \[[xX]\]/, message: 'ticked box in a truth document — a run\'s result belongs to the changelog entry of the unit that ran it; commit the box unticked' },
   { id: 'progress-marker', severity: 'block', scope: 'truth', pattern: /\bphases?\s+\d[^.\n]{0,40}\b(complete|done)\b|\b(build|implementation) (is )?(\d+%|partially) (complete|done)\b/i, message: 'progress marker — progress lives in the plan/backlog record' },
   { id: 'temporal-hedge', severity: 'warn', scope: 'truth', pattern: /\bnot yet\b|\bfor now\b|\bcurrently\b|\bstill (unsupported|missing|pending|unimplemented|in progress)\b/i, message: 'temporal hedge — state the fact without "currently / not yet / for now"' },
-  // "previously-fetched" is a hyphenated adjective naming a thing, not a predecessor design — don't fire on it.
-  { id: 'predecessor-frame', severity: 'warn', scope: 'truth', pattern: /\bpreviously\b(?!-)|\bthe old \w+\b|\blegacy \w+ (was|is)\b/i, message: 'predecessor framing — describe the one current design' },
+  // "previously-fetched" is a hyphenated adjective naming a thing, not a predecessor design — don't fire on it. "No longer"
+  // and "was removed" also describe a state a person meets ("a removed member no longer sees the panel"), so they warn.
+  { id: 'predecessor-frame', severity: 'warn', scope: 'truth', pattern: /\bpreviously\b(?!-)|\bthe old \w+\b|\blegacy \w+ (was|is)\b|\bno longer\b|\bwas removed\b|\bv\d+(\.\d+)*\s*(→|->)\s*v?\d+/i, message: 'predecessor framing — describe the one current design' },
   // docs/tests/ behavioral checklists use `- [ ]` as test-step notation (step → **Assert**) and docs/operations/
   // procedures use it for operator verification steps — neither is progress tracking. Every other truth doc still bans checkboxes.
-  { id: 'status-glyph', severity: 'warn', scope: 'truth', exempt: /(^|\/)docs\/(tests|operations)\//, pattern: /(^|\s)(✅|⏳|- \[[ x]\])/u, message: 'status glyph / checklist in a truth doc — tracking belongs in a record' },
+  { id: 'status-glyph', severity: 'warn', scope: 'truth', exempt: /(^|\/)docs\/(tests|operations|acceptance)\//, pattern: /(^|\s)(✅|⏳|- \[[ xX]\](?!\())/u, message: 'status glyph / checklist in a truth doc — tracking belongs in a record' },
   // Truth docs are supposed to cite records, and record filenames are dated — so a date inside a link
-  // target or a code span is a path, not narration. Strip those before matching.
-  { id: 'date-in-truth-doc', severity: 'block', scope: 'truth', strip: /\[[^\]]*\]\([^)]*\)|`[^`]*`|^(last-reviewed|last-updated|rev|harness-version):.*$/gm, pattern: /\b20\d{2}-\d{2}-\d{2}\b/, message: 'date in a truth doc — cite the record by name and link; the closed exceptions are the frontmatter tooling keys, an AD Decision Changelog tail and a dated path inside a link or code span' },
+  // target is a path, not narration. Code spans are stripped before every rule.
+  { id: 'date-in-truth-doc', severity: 'block', scope: 'truth', strip: /\[[^\]]*\]\([^)]*\)|^(last-reviewed|last-updated|rev|harness-version):.*$/gm, pattern: DATE, message: 'date in a truth doc — cite the record by name and link; the closed exceptions are the frontmatter tooling keys, an AD Decision Changelog tail and a dated path inside a link or code span' },
 ];
 
-// Sections inside a truth doc where dated history is sanctioned (the two bridges).
-const BRIDGE_HEADINGS = /^#{1,4}\s+(decision changelog|health log)\b/i;
-// Instruction files, the three harness-installed mirrors and generated trees are out of scope; the authoring
-// roots are anchored to the repo root.
-const SKIP = /^(\.claude|\.agents|\.codex|skills|rules|agents|harness)\/|(^|\/)(node_modules|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$|\.bkp\./;
+// The one section inside a truth doc where dated history is sanctioned: an AD's Decision Changelog.
+const BRIDGE_HEADINGS = /^#{1,4}\s+decision changelog\b/i;
+// Instruction files, the three harness-installed mirrors, generated trees and the hook-written bookkeeping queue
+// (hooks/lib/state.mjs, a fixed header and a dated row grammar) are out of scope; the authoring roots are anchored
+// to the repo root.
+const SKIP = /^(\.claude|\.agents|\.codex|skills|rules|agents|harness)\/|(^|\/)(node_modules|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$|\.bkp\.|(^|\/)docs\/operations\/bookkeeping\.md$/;
 // `operations/issues/YYYY-MM-DD-{slug}.md` is a sanctioned record genre (`type: issue`, the
 // `issue-bridge` skill's local pack) living outside the record folders, so it is named here too —
 // graded as a truth document it fails the date rule for carrying the date its filename already does.
 const RECORD = /(^|\/)docs\/(history|research|memory)\/|(^|\/)docs\/operations\/issues\/|(^|\/)docs\/operations\/release-notes\/(?!readme\.md$)[^/]+\.md$/i;
 
-const RECORD_TYPES = /^(changelog-entry|plan|migration|migration-runbook|research|brainstorm|journal|record|ledger|issue|triage|project-memory|agent-memory)$/;
+const RECORD_TYPES = /^(changelog-entry|plan|migration|migration-runbook|research|brainstorm|journal|record|ledger|issue|triage|handover|project-memory|agent-memory)$/;
 const TRUTH_LOCATIONS = /(^|\/)docs\/(features|architecture|tests|acceptance)\//;
+// Types other skills stamp on documents this registry does not template (product-dna's ledger, generic records).
+const EXTERNAL_TYPES = /^(ledger|record|migration|migration-runbook|changelog-entry|plan|journal)$/;
+
+// The genre registry (templates/Readme.md § Registry), one entry per row, or null when the skill's templates are
+// not installed beside this script — every registry check then skips, and scope falls back to the path rules.
+function loadRegistry() {
+  let text;
+  try { text = readFileSync(new URL('../templates/Readme.md', import.meta.url), 'utf8'); } catch { return null; }
+  const at = text.search(/^## Registry\s*$/m);
+  if (at === -1) return null;
+  const ticks = (cell) => [...cell.matchAll(/`([^`]+)`/g)].map((m) => m[1]);
+  const rows = [];
+  for (const line of text.slice(at).split('\n').slice(1)) {
+    if (/^## /.test(line)) break;
+    if (!line.startsWith('|') || /^\|\s*(Genre|-{3})/.test(line)) continue;
+    const cells = line.split('|').slice(1, -1).map((c) => c.trim());
+    if (cells.length !== 7) continue;
+    const [genre, , nature, type, location, keys, sections] = cells;
+    const where = ticks(location)[0] || null;
+    rows.push({
+      genre,
+      nature,
+      type: ticks(type)[0] || null,
+      location: where,
+      match: where ? locationPattern(where) : null,
+      // Literal characters outside placeholders: the most specific location wins a tie (`{surface}-ux.md` over `{feature}.md`).
+      specificity: where ? where.replace(/\{[^}]+\}|YYYY-MM-DD|NNN|X\.Y\.Z/g, '').length : 0,
+      keys: ticks(keys),
+      sections: sections === '—' ? [] : sections.split('·').map((x) => x.trim()).filter(Boolean),
+    });
+  }
+  return rows.length ? rows : null;
+}
+
+// A registry location as a path RegExp: `{name}` is one segment, the date and number placeholders their digits, a trailing slash any file beneath.
+function locationPattern(location) {
+  const body = location
+    .replace(/[.+?^$()[\]\\|]/g, '\\$&')
+    .replace(/\\\{[^}]+\}|\{[^}]+\}/g, '[^/]+')
+    .replace(/YYYY-MM-DD/g, '\\d{4}-\\d{2}-\\d{2}')
+    .replace(/NNN/g, '\\d{3}')
+    .replace(/X\\\.Y\\\.Z/g, '[\\d.]+');
+  // A location with no folder (the root README) sits at the repo root only, never at any depth.
+  return new RegExp(`${location.includes('/') ? '(^|/)' : '^(\\./)?'}${body}${location.endsWith('/') ? '' : '$'}`, 'i');
+}
+
+const REGISTRY = loadRegistry();
+
+// The registry row a document belongs to: its declared `type:` first (the location breaking a tie between genres
+// sharing a type), else the most specific location it sits at; null when neither names one.
+function genreOf(path, text) {
+  if (!REGISTRY) return null;
+  const declared = text === undefined ? null : declaredType(text);
+  // A folder's Readme is an index whatever folder it sits in, and only an index location can claim one.
+  const isIndex = /(^|\/)readme\.md$/i.test(path);
+  const at = REGISTRY.filter((r) => r.match && r.match.test(path) && /(^|\/)readme\.md$/i.test(r.location) === isIndex)
+    .sort((a, b) => b.specificity - a.specificity);
+  if (declared) {
+    const typed = REGISTRY.filter((r) => r.type === declared);
+    return typed.find((r) => at.includes(r)) || typed[0] || null;
+  }
+  return at[0] || null;
+}
 
 // The genre a document declares for itself, from its own frontmatter `type:` key, or null.
 function declaredType(text) {
   if (!text.startsWith('---')) return null;
   const end = text.indexOf('\n---', 3);
-  const m = /^type:\s*(\S+)\s*$/m.exec(end === -1 ? text : text.slice(0, end));
-  return m ? m[1] : null;
+  const m = /^type:\s*(\S+)\s*(#.*)?$/m.exec(end === -1 ? text : text.slice(0, end));
+  return m ? m[1].replace(/^["']|["']$/g, '') : null;
+}
+
+// Top-level frontmatter keys and their raw values (a block list joined one item per line), or null with no block.
+function frontmatter(text) {
+  if (!/^---\r?\n/.test(text)) return null;
+  const end = text.indexOf('\n---', 3);
+  if (end === -1) return null;
+  const keys = new Map();
+  let last = null;
+  for (const line of text.slice(text.indexOf('\n') + 1, end).split('\n')) {
+    const key = /^([A-Za-z][\w-]*):[ \t]*(.*)$/.exec(line);
+    if (key) { last = key[1]; keys.set(last, key[2].replace(/\s+#.*$/, '').trim()); continue; }
+    const item = /^\s+-\s+(.*)$/.exec(line);
+    if (item && last) keys.set(last, [keys.get(last), item[1].replace(/\s+#.*$/, '').trim()].filter(Boolean).join('\n'));
+  }
+  return keys;
+}
+
+// A frontmatter value as a list: a flow list, a block list, or one scalar; quotes dropped, empties removed.
+function listValue(raw) {
+  if (!raw) return [];
+  const items = raw.startsWith('[') ? raw.replace(/^\[|\]$/g, '').split(',') : raw.split('\n');
+  return items.map((v) => v.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
 }
 
-// Classify a document: record or truth, the declared genre outranking the path.
+// Classify a document: truth, record, queue or out of scope — the registry's nature first, then the path rules.
 function scopeOf(path, text) {
   if (SKIP.test(path)) return 'skip';
+  const genre = genreOf(path, text);
+  if (genre) return genre.nature === 'truth' ? 'truth' : genre.nature === 'queue' ? 'queue' : 'record';
   if (RECORD.test(path)) return 'record';
   const declared = text === undefined ? null : declaredType(text);
   return declared && RECORD_TYPES.test(declared) ? 'record' : 'truth';
@@ -80,14 +178,27 @@ function proseLines(text) {
   return out;
 }
 
-// Collect file-wide disabled rule ids from <!-- doc-lint-disable: a, b --> comments.
+// Collect file-wide disabled rule ids: a <!-- doc-lint-disable: a, b --> comment alone on its own line. One that shares
+// a line with prose disables that line only, and is honoured where each rule reads its lines.
 function fileDisables(text) {
   const ids = new Set();
-  for (const m of text.matchAll(/<!--\s*doc-lint-disable:\s*([\w-,\s]+?)\s*-->/g))
+  for (const m of text.matchAll(/^\s*<!--\s*doc-lint-disable:\s*([\w-,\s]+?)\s*-->\s*$/gm))
     m[1].split(',').forEach((id) => ids.add(id.trim()));
   return ids;
 }
 
+// File-wide disables with no reason beside them: no comment on the next non-blank line, the way SKILL.md asks.
+function unexplainedDisables(text) {
+  const lines = text.split('\n');
+  const out = [];
+  lines.forEach((line, i) => {
+    if (!/^\s*<!--\s*doc-lint-disable:[^>]*-->\s*$/.test(line)) return;
+    const next = lines.slice(i + 1).find((l) => l.trim());
+    if (!next || !/^\s*<!--/.test(next) || /doc-lint-disable:/.test(next)) out.push({ n: i + 1, line });
+  });
+  return out;
+}
+
 function lintFile(path, findings) {
   if (SKIP.test(path) || !existsSync(path)) return;
   const text = readFileSync(path, 'utf8');
@@ -99,11 +210,17 @@ function lintFile(path, findings) {
   if (scope === 'truth' && nonEmpty <= 10 && /\b(moved to|relocated to|see [\w`./-]+ instead)\b/i.test(text) && !disabled.has('redirect-doc'))
     findings.push({ path, n: 1, severity: 'block', id: 'redirect-doc', message: 'redirect stub — delete the file and repoint every inbound link' });
 
+  for (const { n, line } of unexplainedDisables(text))
+    if (!disabled.has('disable-without-reason')) findings.push({ path, n, severity: 'warn', id: 'disable-without-reason', message: 'file-wide doc-lint-disable with no reason comment on the next line — say why the rule does not apply here', excerpt: line.trim().slice(0, 90) });
+
   for (const rule of RULES) {
     if (rule.scope !== scope || disabled.has(rule.id)) continue;
     if (rule.exempt && rule.exempt.test(path)) continue;
+    if (rule.only && !rule.only.test(path)) continue;
     for (const { n, line } of lines) {
-      const subject = rule.strip ? line.replace(rule.strip, '') : line;
+      // A code span quotes a name or a phrase rather than saying it, so no tense rule reads inside one.
+      const bare = line.replace(/`[^`]*`/g, '');
+      const subject = rule.strip ? bare.replace(rule.strip, '') : bare;
       if (!rule.pattern.test(subject)) continue;
       if (line.includes(`doc-lint-disable: ${rule.id}`) || new RegExp(`doc-lint-disable:[^>]*\\b${rule.id}\\b`).test(line)) continue;
       findings.push({ path, n, severity: rule.severity, id: rule.id, message: rule.message, excerpt: line.trim().slice(0, 90) });
@@ -120,14 +237,16 @@ function lintFile(path, findings) {
   // A folder index (Readme.md/README.md) is a browse page, not a feature doc — it owns no code.
   const isFolderIndex = /(^|\/)(readme)\.md$/i.test(path);
 
-  // An index names folders, never files (SKILL.md § The Two Natures). A link from a folder index or
+  // An index names folders, never files (SKILL.md § Indexes and descriptions). A link from a folder index or
   // the authority map to an individual document is a row that must be edited on every add, rename
   // and retirement; the only files an index may link are the mandated scaffolds and a sibling
   // folder's own Readme.
   const isAuthorityMap = /(^|\/)docs\/structure\.md$/.test(path);
   const isRootReadme = /^(\.\/)?README\.md$/i.test(path.replace(process.cwd() + '/', ''));
-  if (scope === 'truth' && (isFolderIndex || isAuthorityMap) && !disabled.has('index-lists-files')) {
-    const SCAFFOLD = /(^|\/)(readme|structure|changelog|backlog|main|health-log|journal|claude|agents)\.md$|(^|\/)operations\/setup\.md$/i;
+  // Only the docs tree's indexes and the repo-root README are graded as indexes: a package's README links its own CONTRIBUTING.md.
+  const inDocs = /(^|\/)docs\//.test(path);
+  if (scope === 'truth' && ((isFolderIndex && (inDocs || isRootReadme)) || isAuthorityMap) && !disabled.has('index-lists-files')) {
+    const SCAFFOLD = /(^|\/)(readme|structure|changelog|backlog|main|health-log|journal|claude|agents|contributing|license|security|code_of_conduct)\.md$|(^|\/)operations\/setup\.md$/i;
     for (const { n, line } of lines) {
       if (line.includes('doc-lint-disable: index-lists-files')) continue;
       for (const m of line.matchAll(/\]\(([^)\s#]+\.md)(#[^)]*)?\)/g)) {
@@ -142,18 +261,16 @@ function lintFile(path, findings) {
     }
   }
   // A folder index describes directories; a drawn tree is a file roster in another costume
-  // (SKILL.md § Indexes describe directories, never files). structure.md is the authority map and keeps its tree.
+  // (SKILL.md § Indexes and descriptions). structure.md is the authority map and keeps its tree.
   if (scope === 'truth' && isFolderIndex && (isRootReadme || /(^|\/)docs\//.test(path)) && !disabled.has('index-file-tree')) {
     // Raw lines, not proseLines: a tree is drawn inside a code fence, which proseLines drops. The repo-root README routes by a Map table; its tree is docs/structure.md's too (templates/root-readme.md).
     const rawLines = text.split('\n').map((line, i) => ({ n: i + 1, line }));
     const tree = rawLines.find(({ line }) => /^\s*[│├└]/.test(line));
     if (tree) findings.push({ path, n: tree.n, severity: 'block', id: 'index-file-tree', message: 'a tree drawn in a folder index — describe each directory in a sentence; the tree is docs/structure.md\'s', excerpt: tree.line.trim().slice(0, 90) });
   }
-  // A file or record named without a link is the same per-file row as a link (SKILL.md § Every document describes itself).
+  // A file or record named without a link is the same per-file row as a link (SKILL.md § Indexes and descriptions).
   // docs/dna/ is the product-dna skill's generated tree, laid out by that skill's own schema.
   const isGeneratedTree = /(^|\/)docs\/dna\//.test(path);
-  // The bookkeeping queue is written by the harness hooks from a fixed header (hooks/lib/state.mjs); it carries no frontmatter.
-  const isHookQueue = /(^|\/)docs\/operations\/bookkeeping\.md$/.test(path);
   if (scope === 'truth' && isFolderIndex && /(^|\/)docs\//.test(path) && !isGeneratedTree && !disabled.has('index-names-records')) {
     const SCAFFOLD_NAME = /^(readme|structure|changelog|backlog|main|health-log|journal|claude|agents|setup)\.md$/i;
     for (const { n, line } of lines) {
@@ -164,7 +281,7 @@ function lintFile(path, findings) {
     }
   }
   // Every truth document and folder index under docs/ describes itself in at most 300 characters (references/frontmatter.md § description:).
-  if (scope === 'truth' && /(^|\/)docs\//.test(path) && !isGeneratedTree && !isAuthorityMap && !isHookQueue && !disabled.has('description-missing')) {
+  if (scope === 'truth' && /(^|\/)docs\//.test(path) && !isGeneratedTree && !isAuthorityMap && !disabled.has('description-missing')) {
     const fmEnd = text.startsWith('---') ? text.indexOf('\n---', 3) : -1;
     const fmText = fmEnd === -1 ? '' : text.slice(0, fmEnd);
     const m = /^description:[ \t]*(.*)$/m.exec(fmText);
@@ -177,7 +294,7 @@ function lintFile(path, findings) {
         for (const l of rest) { if (/^\s+\S/.test(l)) block.push(l.trim()); else break; }
         value = block.join(' ');
       }
-      value = value.replace(/^(["'])(.*)\1$/, '$2');
+      value = /^["']/.test(value) ? value.replace(/^(["'])(.*)\1\s*(#.*)?$/, '$2') : value.replace(/\s+#.*$/, '');
       if (!value) findings.push({ path, n: 1, severity: 'block', id: 'description-missing', message: '`description:` is empty — at most 300 characters saying what this document settles and where its boundary sits' });
       else if (value.length > 300 && !disabled.has('description-length')) findings.push({ path, n: 1, severity: 'block', id: 'description-length', message: `\`description:\` is ${value.length} characters — at most 300` });
     }
@@ -190,24 +307,47 @@ function lintFile(path, findings) {
     const chrome = raw.findIndex((l) => /shields\.io|<img\b|<div\b|<p align|^!\[/.test(l));
     if (!disabled.has('root-readme-chrome') && chrome !== -1) findings.push({ path, n: chrome + 1, severity: 'block', id: 'root-readme-chrome', message: 'badge, image or HTML layout in the root README — agents cannot read it and the team does not need it', excerpt: raw[chrome].trim().slice(0, 90) });
   }
-  if (scope === 'truth' && !isFolderIndex && /(^|\/)docs\/features\/[^/]+\.md$/.test(path)) {
-    const fm = text.startsWith('---') ? text.slice(0, text.indexOf('\n---', 3)) : '';
-    for (const key of ['objects:', 'status:', 'type:'])
-      if (!fm.includes(key)) findings.push({ path, n: 1, severity: 'block', id: 'feature-frontmatter', message: `feature doc missing \`${key}\` frontmatter` });
+  // The genre's own contract, from the registry: its required keys, its required sections, and a `type:` it knows.
+  const genre = genreOf(path, text);
+  const fmKeys = frontmatter(text) || new Map();
+  const declared = declaredType(text);
+  if (REGISTRY && declared && !REGISTRY.some((r) => r.type === declared) && !EXTERNAL_TYPES.test(declared) && !disabled.has('type-unknown'))
+    findings.push({ path, n: 1, severity: 'warn', id: 'type-unknown', message: `\`type: ${declared}\` names no genre in the registry (templates/Readme.md) — use its row's value` });
+  // An owning genre's keys are what the ownership scan and the graph read, so their absence blocks; elsewhere it warns.
+  const owningGenre = genre && ['feature', 'package', 'system'].includes(genre.type);
+  if (scope === 'truth' && genre && !isFolderIndex && !disabled.has('required-key') && !(genre.type === 'feature' && disabled.has('feature-frontmatter'))) {
+    for (const key of genre.keys) {
+      // `description` carries its own rule above, and an owning document's `objects` its own below.
+      if (key === 'description' || (key === 'objects' && owningGenre) || fmKeys.has(key)) continue;
+      findings.push({ path, n: 1, severity: owningGenre ? 'block' : 'warn', id: 'required-key', message: `${genre.genre.toLowerCase()} document missing \`${key}:\` frontmatter (templates/Readme.md § Registry)` });
+    }
+  }
+  if (scope === 'truth' && genre && genre.sections.length && !isFolderIndex && fmKeys.get('status') !== 'deprecated' && !disabled.has('section-missing')) {
+    const headings = new Set(lines.map(({ line }) => /^##\s+(.+?)\s*$/.exec(line)).filter(Boolean).map((m) => m[1].toLowerCase()));
+    for (const section of genre.sections)
+      if (!headings.has(section.toLowerCase())) findings.push({ path, n: 1, severity: 'warn', id: 'section-missing', message: `${genre.genre.toLowerCase()} document has no \`## ${section}\` section (templates/Readme.md § Registry)` });
+  }
+  // A `verifies:` edge is the one doc → doc edge a person authors; a target that does not exist is a typo or a deletion.
+  for (const target of listValue(fmKeys.get('verifies'))) {
+    if (disabled.has('dangling-edge') || existsSync(target) || existsSync(join(dirname(path), target))) continue;
+    findings.push({ path, n: 1, severity: 'block', id: 'dangling-edge', message: `\`verifies: ${target}\` names no document — repo-relative path of the document whose promises this proves` });
   }
 
   // An owning document (feature, package, system) is intent and promises; the sections that narrate
   // mechanism — a file roster, a walk through the code, a schema or route table — are the graph's
-  // to compute and are retired from the genre (SKILL.md § A document is intent and promises).
-  const isOwningDoc = scope === 'truth' && !isFolderIndex && /(^|\/)docs\/(features|architecture\/(packages|systems))\/[^/]+\.md$/.test(path);
+  // to compute and are retired from the genre (SKILL.md § Truth documents).
+  const isOwningDoc = scope === 'truth' && !isFolderIndex && /(^|\/)docs\/(features\/(?:[^/]+\/)*|architecture\/(packages|systems)\/)[^/]+\.md$/.test(path);
+  if (isOwningDoc && /(^|\/)docs\/features\/[^/]+\/.+\.md$/.test(path) && !disabled.has('nested-feature'))
+    findings.push({ path, n: 1, severity: 'warn', id: 'nested-feature', message: 'feature document in a subfolder — `docs/features/` is flat; a subject too large for one file is two files' });
   if (isOwningDoc && !disabled.has('mechanism-section')) {
-    const RETIRED = /^#{2,4}\s+(Files|Current Behavior|Key Functions|Data|API|Refusals?|Architecture|State|Redux|Affected Modules|Conventions to Follow|Ownership Conflicts|Tests|The shape|Layout|Build and test|Commands|Routes|Schema|Wire)\b/i;
+    // Whole headings only: "## Data retention" is a promise, "## Data" the retired table.
+    const RETIRED = /^#{2,4}\s+(Files|Key files|Current Behavior|Key Functions|Data|Data model|Data flow|API|API surface|Refusals?|Architecture|State|State management|Redux|Affected Modules|Conventions to Follow|Ownership Conflicts|Tests|The shape|Layout|Build and test|Commands|Routes|Schema|Wire)\s*:?\s*$/i;
     for (const { n, line } of lines) {
       if (!RETIRED.test(line) || line.includes('doc-lint-disable: mechanism-section')) continue;
       findings.push({ path, n, severity: 'block', id: 'mechanism-section', message: 'mechanism section in an owning document — columns, routes, guards, functions and files are the graph\'s to compute; keep the decision or the promise, point by name, cut the rest', excerpt: line.trim().slice(0, 90) });
     }
-    const fm = text.startsWith('---') ? text.slice(0, text.indexOf('\n---', 3)) : '';
-    if (!/^objects:/m.test(fm)) findings.push({ path, n: 1, severity: 'block', id: 'objects-missing', message: 'owning document names no `objects:` — the product objects it designs are its edge into the graph and its discovery terms' });
+    if (!disabled.has('objects-missing') && !listValue(fmKeys.get('objects')).length)
+      findings.push({ path, n: 1, severity: 'block', id: 'objects-missing', message: 'owning document names no `objects:` — the product objects it designs are its edge into the graph and its discovery terms' });
   }
 
   // The body of an owning document is scanned by people; its "For the agent" footer holds the pointers