@nurix/etna 0.20.35 → 0.20.37

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) });
@@ -117,17 +234,20 @@ function lintFile(path, findings) {
       findings.push({ path, n: 1, severity: 'block', id: 'record-type-in-truth-location', message: `\`type: ${declared}\` is a record genre declared in a truth location — move the file to \`docs/history/\` if it is a record, or give it its location's genre` });
   }
 
-  // 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);
+  // A folder index (Readme.md/README.md) is a browse page that owns no code; a Readme declaring an owning genre is
+  // that folder's landing document and is graded as its genre instead.
+  const isFolderIndex = /(^|\/)(readme)\.md$/i.test(path) && !['feature', 'package', 'system'].includes(declaredType(text));
 
-  // 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 +262,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 +282,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 +295,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 +308,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

package/data/harnesses/delivery/skills/documentation/templates/Readme.md

@@ -1,41 +1,68 @@
-# Documentation Templates
-
-One file per template. Every template is either a **truth document** (states current absolutes, updated in place) or a **record** (dated account of activity, frozen or append-only) — the split is defined in `SKILL.md` § The Two Natures, and each template names its nature in its opening line.
-
-| Template | File | Nature |
-| --- | --- | --- |
-| Feature (LLD) | [feature.md](feature.md) | Truth |
-| Package (one workspace package) | [package.md](package.md) | Truth |
-| Doctrine (one concern the platform handles everywhere) | [doctrine.md](doctrine.md) | Truth |
-| System (one machine spanning packages) | [system.md](system.md) | Truth |
-| Architecture Decision (AD) | [architecture-decision.md](architecture-decision.md) | Truth (Decision Changelog tail sanctioned) |
-| System overview | [system-overview.md](system-overview.md) | Truth |
-| Domain model | [domain-model.md](domain-model.md) | Truth |
-| Glossary | [glossary.md](glossary.md) | Truth |
-| Non-goals | [non-goals.md](non-goals.md) | Truth |
-| API reference | [api-reference.md](api-reference.md) | Truth |
-| Environment registry | [environment-registry.md](environment-registry.md) | Truth |
-| Security overview | [security-overview.md](security-overview.md) | Truth |
-| Testing strategy | [testing-strategy.md](testing-strategy.md) | Truth |
-| Behavioral checklist | [behavioral-checklist.md](behavioral-checklist.md) | Truth |
-| UX behavior | [ux-behavior.md](ux-behavior.md) | Truth |
-| Setup (first run, one per repo) | [setup.md](setup.md) | Truth |
-| Operations procedure | [operations-procedure.md](operations-procedure.md) | Truth |
-| Implementation map | [implementation-map.md](implementation-map.md) | Truth |
-| Bookkeeping ledger | [bookkeeping.md](bookkeeping.md) | Truth (work queue) |
-| Protected files | [protected-files.md](protected-files.md) | Truth |
-| Project root README (outward opening, then orientation and routing) | [root-readme.md](root-readme.md) | Truth |
-| docs/README.md (doc index) | [docs-readme.md](docs-readme.md) | Truth |
-| Plan | [plan.md](plan.md) | Record |
-| Changelog entry | [changelog-entry.md](changelog-entry.md) | Record |
-| Migration runbook | [migration-runbook.md](migration-runbook.md) | Record |
-| Journal | [journal.md](journal.md) | Record (append-only) |
-| CHANGELOG master index | [changelog-index.md](changelog-index.md) | Record index (append-only) |
-| Backlog | [backlog.md](backlog.md) | Record (append-only) |
-| Memory (main agent) | [memory-main.md](memory-main.md) | Record (append-only ledger) |
-
-**The `type:` enum lives here.** A doc's `type:` frontmatter takes its value from this table — one genre per template (`feature`, `architecture-decision`, `non-goals`, …). External generators consume this list rather than defining their own; a type this table does not name defaults to `docs/architecture/` placement and is never added to the protected-files list.
-
-**Baseline scaffolds** — files that must exist after every baseline (`docs/structure.md` is not among them: it is harness-owned, shipped whole by the installer and overwritten on every refresh, and has no template); the `maintenance` agent (baseline mode) creates any that are missing: [docs-readme.md](docs-readme.md), [changelog-index.md](changelog-index.md), [backlog.md](backlog.md), [memory-main.md](memory-main.md), [setup.md](setup.md) (when the repo has a lockfile and a runnable root script; never overwriting an existing first-run procedure), and [root-readme.md](root-readme.md) (never overwriting an existing root README).
-
-**Ownership.** Three genres speak for code — **feature**, **package**, **system**. A document names the objects it designs in `objects:`; a source file names the document that speaks for it in its path header; which document speaks for a path is computed from those headers and the object closure, and answered per path by the ownership index (`references/frontmatter.md`). Until the harness's ownership scan switches to that computation, it reads a transitional `owns:` region glob on each of the three genres: `packages/{name}/**` on a package document (the residual owner), a machine's subtrees on a system document, a feature's own directory on a feature document; the narrower glob wins.
+# Genre registry
+
+Every fact about a genre lives in one row of the table below: its template, its nature, its `type:` value, where it lives, the frontmatter keys it must carry and the sections it must have. `SKILL.md`, the `maintenance` agent and the shipped `docs/structure.md` name genres and defer here for these facts, and `scripts/doc-lint.mjs` reads this table to check them. The column order is a contract: the lint parses the table, and `packages/cli/tests/scripts/genreRegistry.test.mjs` in the forge fails when a row stops parsing or a template stops agreeing with it.
+
+## The three natures
+
+| Nature | Holds | Changes by | Dates | Ends |
+| --- | --- | --- | --- | --- |
+| `truth` | What is true now | Rewritten in place, present tense; no history in the body (an AD's Decision Changelog tail is the one bridge) | Frontmatter tooling keys only | Deleted, or `status: deprecated`, when its subject is gone |
+| `record` | What happened | Written while live, then frozen at its terminal status; never edited after | In the filename or header | Never; it is the archive |
+| `queue` | Work not done yet | Rows appended at the end and deleted when resolved, drained or promoted; nothing else is edited | Per row, as row metadata | Never; an empty queue is the healthy state |
+
+## Registry
+
+| Genre | Template | Nature | `type:` | Location | Required keys | Required sections |
+| --- | --- | --- | --- | --- | --- | --- |
+| Feature | [feature.md](feature.md) | truth | `feature` | `docs/features/{feature}.md` | `type` `description` `status` `objects` | Scope · Promises · For the agent |
+| Package | [package.md](package.md) | truth | `package` | `docs/architecture/packages/{package}.md` | `type` `description` `status` `objects` | Scope · Ownership · Usage · Promises · For the agent |
+| System | [system.md](system.md) | truth | `system` | `docs/architecture/systems/{system}.md` | `type` `description` `status` `objects` | Scope · Flow · Promises · For the agent |
+| Doctrine | [doctrine.md](doctrine.md) | truth | `doctrine` | `docs/architecture/common/{concern}.md` | `type` `description` `status` `objects` | The model · For the agent |
+| Architecture decision | [architecture-decision.md](architecture-decision.md) | truth | `architecture-decision` | `docs/architecture/decisions/AD-NNN-{subject}.md` | `type` `title` `description` `status` `last-updated` | Decision · Context · Consequences |
+| UX behavior | [ux-behavior.md](ux-behavior.md) | truth | `ux` | `docs/features/{surface}-ux.md` | `type` `description` `status` `objects` | Purpose · Anatomy · States · Affordances · Promises · Transitions |
+| System overview | [system-overview.md](system-overview.md) | truth | `system-overview` | `docs/architecture/system-design.md` | `type` `description` | — |
+| Domain model | [domain-model.md](domain-model.md) | truth | `domain-model` | `docs/architecture/domain-model.md` | `type` `description` | — |
+| Glossary | [glossary.md](glossary.md) | truth | `glossary` | `docs/architecture/glossary.md` | `type` `description` | — |
+| Non-goals | [non-goals.md](non-goals.md) | truth | `non-goals` | `docs/architecture/non-goals.md` | `type` `description` | — |
+| Security overview | [security-overview.md](security-overview.md) | truth | `security-overview` | `docs/architecture/security.md` | `type` `description` | — |
+| Testing strategy | [testing-strategy.md](testing-strategy.md) | truth | `testing-strategy` | `docs/architecture/common/testing.md` | `type` `description` | — |
+| API reference | [api-reference.md](api-reference.md) | truth | `api-reference` | `docs/architecture/api.md` | `type` `description` | — |
+| Environment registry | [environment-registry.md](environment-registry.md) | truth | `environment-registry` | `docs/operations/environment.md` | `type` `description` | — |
+| Behavioral checklist | [behavioral-checklist.md](behavioral-checklist.md) | truth | `checklist` | `docs/tests/{feature}.md` | `type` `description` `verifies` | — |
+| Acceptance criteria | [acceptance-criteria.md](acceptance-criteria.md) | truth | `acceptance-criteria` | `docs/acceptance/{capability}.md` | `type` `description` `status` | — |
+| Setup | [setup.md](setup.md) | truth | `operations` | `docs/operations/setup.md` | `type` `description` | Installation · First run · Verification |
+| Operations procedure | [operations-procedure.md](operations-procedure.md) | truth | `operations` | `docs/operations/{procedure}.md` | `type` `description` | Steps · Verification |
+| Implementation map | [implementation-map.md](implementation-map.md) | truth | `implementation-map` | `docs/operations/implementation-map.md` | `type` `description` | Waves · Active wave |
+| Protected files | [protected-files.md](protected-files.md) | truth | `protected-files` | `docs/operations/protected-files.md` | `type` `description` | — |
+| Docs index | [docs-readme.md](docs-readme.md) | truth | `docs-readme` | `docs/README.md` | `type` `description` | — |
+| Folder index | — | truth | `folder-index` | `docs/{folder}/Readme.md` | `type` `description` | — |
+| Changelog guide | [changelog-index.md](changelog-index.md) | truth | `changelog-guide` | `docs/history/CHANGELOG.md` | `type` `description` | — |
+| Root README | [root-readme.md](root-readme.md) | truth | — | `README.md` | — | — |
+| Plan | [plan.md](plan.md) | record | — | `docs/history/plans/YYYY-MM-DD-{slug}.md` | — | Background · Proposed Changes · Doc Obligations · Implementation Steps · Test Obligations |
+| Changelog entry | [changelog-entry.md](changelog-entry.md) | record | — | `docs/history/changelog/YYYY-MM-DD-{three-words}.md` | — | — |
+| Migration runbook | [migration-runbook.md](migration-runbook.md) | record | — | `docs/history/migrations/YYYY-MM-DD-{slug}.md` | — | — |
+| Hand-over | [handover.md](handover.md) | record | `handover` | `docs/history/handovers/YYYY-MM-DD-{slug}.md` | `type` `description` `status` | — |
+| Health log | — | record | — | `docs/history/health-log.md` | — | — |
+| Deep research | — | record | `research` | `docs/history/research/{topic}/` | — | — |
+| Brainstorm session | — | record | `brainstorm` | `docs/research/{topic}-brainstorm/` | — | — |
+| Issue | — | record | `issue` | `docs/operations/issues/YYYY-MM-DD-{slug}.md` | — | — |
+| Triage dossier | — | record | `triage` | `docs/operations/triage/YYYY-MM-DD-{slug}.md` | — | — |
+| Release note | — | record | — | `docs/operations/release-notes/YYYY-MM-DD-vX.Y.Z.md` | — | — |
+| Backlog | [backlog.md](backlog.md) | queue | — | `docs/history/backlog.md` | — | — |
+| Journal | [journal.md](journal.md) | queue | — | `docs/history/journal.md` | — | — |
+| Bookkeeping | [bookkeeping.md](bookkeeping.md) | queue | — | `docs/operations/bookkeeping.md` | — | — |
+| Project memory | [memory-main.md](memory-main.md) | queue | `project-memory` | `docs/memory/main.md` | `type` `description` | — |
+| Agent memory | — | queue | `agent-memory` | `docs/memory/{agent}.md` | — | — |
+
+- **`type:` values:** a genre's `type:` value is the one its template's skeleton carries, and two genres may share one (setup and operations procedure are both `operations`). A dash means the genre carries no frontmatter, or carries none it must have. A value this table does not name is reported by the lint as `type-unknown`.
+- **Locations:** `{name}` is one kebab-case path segment, `YYYY-MM-DD` a date, `AD-NNN` a zero-padded number. A location is where the genre lives in a repository that uses it; a folder nothing uses is absent.
+- **Required sections:** the `##` headings every document of the genre carries, by name; the template states the optional ones and when each is written. A dash means the template's sections are guidance, not a fixed set. The lint checks them on truth documents; a plan's are checked by the hooks that read it.
+- **Rows without a template:** each is written by its own tool (the `maintenance` agent's Health Log, the `brainstorm` skill, the deep-research and `issue-bridge` packs, a release pipeline) and is listed so its nature and place are settled here too.
+
+## Ownership
+
+Three genres speak for code — **feature**, **package**, **system** — and a **UX** document speaks for a surface's components where none of them does (`ux-behavior.md`). A document names the objects it designs in `objects:`; a source file names the document that speaks for it in its path header. The harness's ownership scan reads one edge, the transitional `owns:` region glob on each owning document (`packages/{name}/**` on a package, a machine's subtrees on a system, a feature's own directory on a feature), and the narrower glob wins. The header pointer is written alongside it so the scan can switch to it and the object closure without a second pass over the code (`references/frontmatter.md`).
+
+## Baseline scaffolds
+
+The `maintenance` agent's baseline creates these when missing, from their templates: the docs index, the changelog guide, the backlog, project memory, setup (when the repo has a lockfile and a runnable root script; never a second first-run document) and the root README (never overwriting one). `docs/structure.md` is not among them: the installer ships it whole and overwrites it on every refresh.

package/data/harnesses/delivery/skills/documentation/templates/acceptance-criteria.md

@@ -1,23 +1,13 @@
-# Acceptance Criteria
+# Acceptance criteria
 
-Truth document. Use for: the promises one capability must keep, stated as machine-parseable
-claims. Lives in `docs/acceptance/`, one `kebab-case.md` per capability. Written at specification
-time — before implementation — and read by verification surfaces, which parse each `AC-n` line as
-a claim to grade the built product against.
+Truth document. Use for: the promises one capability must keep, stated as machine-parseable claims. Lives in `docs/acceptance/`, one `kebab-case.md` per capability. Written at specification time — before implementation — and read by verification surfaces, which parse each `AC-n` line as a claim to grade the built product against.
 
 ### Rules
 
-- **Frontmatter is required**: `type: acceptance-criteria`, `status:` (`draft` → `active` →
-  `deprecated`). No `owns:` — acceptance criteria own no code.
-- **One `AC-n` key per criterion, stable forever.** Keys are never renumbered and never reused: a
-  criterion that no longer applies is marked retired in place, so every claim a past verification
-  graded still resolves.
-- **Each criterion is one observable assert**, phrased as a checkable statement about the running
-  product — never about the code's internals. If it cannot be observed from outside, it is a
-  design note, not a criterion.
-- **The `AC-n:` line grammar is load-bearing** — verification parses these lines. Keep the key at
-  line start, exactly `AC-<number>:`, followed by the assert sentence. Formatting that buries the
-  key (tables, emphasis-wrapped keys, nested bullets) breaks the parse.
+- **Frontmatter is required**: `type: acceptance-criteria`, `status:` (`draft` → `active` → `deprecated`). No `owns:` — acceptance criteria own no code.
+- **One `AC-n` key per criterion, stable forever.** Keys are never renumbered and never reused: a criterion that no longer applies is marked retired in place, so every claim a past verification graded still resolves.
+- **Each criterion is one observable assert**, phrased as a checkable statement about the running product — never about the code's internals. If it cannot be observed from outside, it is a design note, not a criterion.
+- **The `AC-n:` line grammar is load-bearing** — verification parses these lines. Keep the key at line start, exactly `AC-<number>:`, followed by the assert sentence. Formatting that buries the key (tables, emphasis-wrapped keys, nested bullets) breaks the parse.
 
 ### Template
 
@@ -32,7 +22,9 @@ status: draft
 
 Scope: {one line — what part of the product these criteria bind}.
 
-- AC-1: {observable assert about the running product}.
-- AC-2: {observable assert}.
-- AC-3 (retired): {kept verbatim, marked retired — never renumbered}.
+AC-1: {observable assert about the running product}.
+
+AC-2: {observable assert}.
+
+AC-3: (retired) {kept verbatim, marked retired — never renumbered}.
 ```

package/data/harnesses/delivery/skills/documentation/templates/api-reference.md

@@ -1,10 +1,15 @@
-# API Reference (docs/architecture/api.md)
+# API reference (docs/architecture/api.md)
 
-Truth document. Use for: the consolidated catalog of the system's HTTP surface — every live route in one place. This is the **index**: request/response shapes stay in the owning feature docs; this doc answers "what exists and where is it documented." If the repo generates an OpenAPI spec, this doc points at it and carries only what the spec can't (auth model, conventions, ownership links).
+Truth document. Use for: the consolidated catalog of the system's HTTP surface — every live route in one place. This is the **reference document** for the API surface: a route's shape lives here or in the generated spec, never in a feature doc, which states what the route promises and leaves its shape to this catalog. If the repo generates an OpenAPI spec, this doc points at it and carries only what the spec can't (auth model, conventions, ownership links).
 
 Required: **Conventions**, the **route tables**. One row per live route; a route that isn't here doesn't exist.
 
-```
+```markdown
+---
+type: api-reference
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # API Reference
 
 ## Conventions