geneseed 2.0.0 → 3.0.0

package/js/doctor.mjs

@@ -1,14 +1,14 @@
 /**
  * `_harness_build.cmd_doctor` — validate the build.
  *
- * Sixteen `_*_problems` checks over one theme (or every theme) — the newest is P10c's `cli`
- * — and `[doctor] ok — …` when all sixteen find nothing. That last sentence is why this
- * module's gate looks the way it does, and it is worth stating here rather than only in the
- * spec: **delete any single check
- * and a clean run is byte-identical**, so a cross-implementation comparison cannot tell this
- * file from a stub that prints the OK line. `tests/harness_golden.py` therefore plants ONE
- * FAULT PER CHECK, in a private copy of the checkout — see `_copy_checkout` there for why a
- * verb that reads `ROOT` needed a fixture kind that did not exist until this phase.
+ * Fifteen `*Problems` checks over one theme (or every theme) — and `[doctor] ok — …` when all
+ * fifteen find nothing. That last sentence is why this module's gate looks the way it does, and
+ * it is worth stating here rather than only in the spec: **delete any single check
+ * and a clean run is byte-identical**, so a comparison of two runs cannot tell this
+ * file from a stub that prints the OK line. `tests/unit/harness.test.mjs` and
+ * `tests/unit/authoring_gates.test.mjs` therefore plant ONE FAULT PER CHECK, in a private copy
+ * of the checkout — see `copyCheckout` in `tests/helpers/cli_golden.mjs` for why a verb that
+ * reads `ROOT` needed a fixture kind that did not exist until the port.
  *
  * WHY THIS IS THE VERB THAT SPAWNS. `bin/geneseed-cli.mjs` was under a blanket transitive
  * `child_process` ban, and its own docblock predicted the day a verb that genuinely spawns
@@ -33,7 +33,9 @@ import { spawnSync } from 'node:child_process';
 import os from 'node:os';
 import path from 'node:path';
 
-import { CONFIG, PLUGIN_SRC, ROOT, SRC, THEMES, WORKFLOW_SRC, makeCfg } from './checkout.mjs';
+import {
+  CONFIG, PACK_ORDER, PLUGIN_SRC, ROOT, SRC, THEMES, WORKFLOW_SRC, makeCfg,
+} from './checkout.mjs';
 import {
   buildInto, main as driverMain, emitGlobalInto, emitProjectInto,
 } from '../bin/geneseed.mjs';
@@ -48,7 +50,7 @@ import {
 } from './native.mjs';
 import { PALETTE_ROLES, colorThemeFiles } from './opencode.mjs';
 import { STRUCTURE, renderAll } from './render.mjs';
-import { SHIM_ARGV, hookShimPath } from './settings.mjs';
+import { hookShimPath, shimDeadPaths } from './settings.mjs';
 import { pySplitLines } from './lib/udiff.mjs';
 import { NO_WINDOW } from './lib/proc.mjs';
 import {
@@ -61,7 +63,10 @@ import {
 // --------------------------------------------------------------------------------------
 
 /** `_harness_core.TOKEN_RE` / `LINK_RE` / `ABS_LINK_RE`. `g` where `findall` is used. */
-const TOKEN_RE = /\{\{[A-Z_]+\}\}/g;
+// Must stay in step with `js/render.mjs`'s TOKEN_RE: a token the renderer substitutes but this
+// scan cannot see is an unresolved-token gate that silently stops gating. Digits are legal after
+// the first character for `DOC_<PACK>_<n>`; a leading digit is still not a token.
+const TOKEN_RE = /\{\{[A-Z_][A-Z0-9_]*\}\}/g;
 const LINK_RE = /\]\((?!https?:\/\/|#)([^)]+)\)/g;
 const ABS_LINK_RE = /^([A-Za-z]:[\\/]|\/|~)/;
 const FENCE_RE = /```[\s\S]*?```/g;
@@ -516,9 +521,9 @@ export function shimProblems() {
     return [`[shim] ${p} exists but cannot be read (${e.message}) — hooks may be dead`];
   }
   // The body is machine-generated and quotes the two baked paths — plus, on POSIX, the argv
-  // placeholder `"$@"`, which is not a path. `SHIM_ARGV` is the single owner of that pair.
-  const quoted = [...body.matchAll(/"([^"]+)"/g)].map((m) => m[1]);
-  return quoted.filter((q) => !SHIM_ARGV.has(q) && !existsSync(q)).map(
+  // placeholder `"$@"`, which is not a path. `shimDeadPaths` is the single owner of that rule;
+  // `hookPrefix` is its other reader, and the two must not drift.
+  return shimDeadPaths(body).map(
     (m) => `[shim] ${p} pointed at ${m}, which does not exist — every hook in every `
       + "install was dead (the checkout most likely moved). This run's own "
       + 'emit has refreshed it; no further action needed.',
@@ -660,6 +665,63 @@ export function lawMetaProblems(lawNums, lawClass, lawClasses) {
   return problems;
 }
 
+/** `LAW_META_ROW`'s twin for a STRING key — `'<pack>.<n>': ['<pack>', '<principle>'],`. */
+const DOCTRINE_META_ROW =
+  /^[^\S\n]*(['"])([a-z]+\.\d+)\1:\s*\[\s*(['"])(.*?)\3\s*,\s*(['"])(.*?)\5\s*,?\s*\]\s*,?[^\S\n]*$/gm;
+
+/**
+ * `lawMetaProblems`' doctrine half — the console's per-rule Principle column stays complete.
+ *
+ * SAME DEFECT, ONE TIER OVER. `DOCTRINE_META` holds copy that exists nowhere else in the tree,
+ * and a rule with no row falls back to an empty principle: it renders with a blank description
+ * while every count upstream reads correct. Two invariants shipped exactly that way before
+ * `lawMetaProblems` existed, and 23 new rules is a much larger surface to lose one in.
+ *
+ * ⚠ THE CLASS ARM IS DIFFERENT FROM THE INVARIANTS'. An invariant's class is checked against
+ * `LAW_CLASSES`, a vocabulary of six; a doctrine rule has no second taxonomy — its class IS its
+ * pack — so the check is an EQUALITY against the pack in its own key. That catches the copy
+ * error a six-way vocabulary cannot: a row pasted from the pack above it, keeping the class of
+ * the pack it came from, which would colour the row and label its chip with the wrong pack.
+ */
+export function doctrineMetaProblems(addrs) {
+  const page = path.join(ROOT, 'web', 'src', 'pages', 'Laws.jsx');
+  let text;
+  try { text = readText(page); } catch (e) {
+    return [`[authoring] web/src/pages/Laws.jsx unreadable: ${e.message}`];
+  }
+  const block = /^const DOCTRINE_META = \{$([\s\S]*?)^\}$/m.exec(text);
+  if (!block) {
+    return ['[authoring] DOCTRINE_META literal not found in web/src/pages/Laws.jsx — the '
+      + "console's doctrine rows would have no gate on their Principle column"];
+  }
+  const meta = new Map();
+  for (const m of block[1].matchAll(DOCTRINE_META_ROW)) meta.set(m[2], [m[4], m[6]]);
+  const problems = [];
+  const seen = new Set();
+  for (const addr of addrs) {
+    seen.add(addr);
+    if (!meta.has(addr)) {
+      problems.push(`[authoring] doctrine rule ${addr} has no row in DOCTRINE_META `
+        + '(web/src/pages/Laws.jsx) — the console would render it with a blank Principle');
+      continue;
+    }
+    const [klass, principle] = meta.get(addr);
+    if (!principle.trim()) {
+      problems.push(`[authoring] DOCTRINE_META['${addr}'] has an empty principle line — that `
+        + 'rule would render with a blank description');
+    }
+    const pack = addr.split('.')[0];
+    if (klass !== pack) {
+      problems.push(`[authoring] DOCTRINE_META['${addr}'] carries pack '${klass}' — a doctrine `
+        + `rule's class IS its pack, so this must read '${pack}'`);
+    }
+  }
+  for (const addr of [...meta.keys()].filter((k) => !seen.has(k)).sort()) {
+    problems.push(`[authoring] DOCTRINE_META lists ${addr} but no pack file defines it`);
+  }
+  return problems;
+}
+
 /**
  * `_harness_build._prose_mirror_problems` — the human-readable count mirrors, the ones the
  * badge regex never sees.
@@ -736,6 +798,14 @@ export function proseMirrorProblems(readme, web, counts, skillStems, shipped = '
     }
   }
 
+  // ⚠ THE ABSENCE OF THIS TRIPLE IS CHECKED BY THE CALLER, NOT HERE, AND THAT IS FORCED RATHER
+  // THAN CHOSEN. This arm is satisfiable by DELETING THE SENTENCE — no match, no problem, green
+  // — which is a gate failing open. The obvious fix is an `else` right here, and it cannot go
+  // here: `prose_mirror_problems` is one of the pure functions recorded in
+  // `tests/__snapshots__/primitives/`, the recording holds a case that passes an EMPTY `shipped`
+  // and expects `[]`, and there is no recorder left to re-bless it. So the presence check lives
+  // in `countTableProblems`, which is not recorded — beside the read that already knows whether
+  // the file could be opened at all, which is where it reads better anyway.
   const s = /(\d+) laws, (\d+) agents, (\d+) skills/.exec(shipped);
   if (s) {
     for (const [got, want, label] of [[s[1], laws, 'laws'], [s[2], agents, 'agents'],
@@ -752,6 +822,237 @@ export function proseMirrorProblems(readme, web, counts, skillStems, shipped = '
 const TMPL_SPEC_RE = /\{\{DIR_(AGENTS|SKILLS)\}\}\/([A-Za-z0-9_-]+)\.md/g;
 const LAW_HEADING_RE = /^### \{\{LAW\}\} ([IVXLCDM]+)\b/gm;
 
+// The doctrine twins of `LAW_HEADING_RE`, over the UNRENDERED source — `js/inventory.mjs`'s
+// pair of the same names read the rendered form. A citation is the heading minus its `### `,
+// so one regex cannot serve both: a heading is an anchored line, a citation is anywhere.
+const DOCTRINE_HEADING_RE = /^### \{\{DOCTRINE\}\} ([a-z]+) (\d+)\b/gm;
+const DOCTRINE_CITE_RE = /\{\{DOCTRINE\}\}\s+([a-z]+)\s+(\d+)/g;
+// `\{\{DOCTRINE\}\}` and not `DOCTRINE`: `{{DOCTRINES}}` is the SECTION noun and is legal
+// everywhere, including in an invariant that points at the tier as a whole.
+const DOCTRINE_TOKEN_RE = /\{\{DOCTRINE\}\}/;
+const DOC_TOKEN_RE = /\{\{(DOC_[A-Z0-9_]+)\}\}/g;
+
+/**
+ * A line reported by the doctor that is NOT a failure — `[note] …` rather than `[authoring] …`.
+ *
+ * ⚠ ONE PRODUCER, AND IT IS THE ONLY THING THAT NEEDED A SECOND CHANNEL. A build with a
+ * doctrine pack off is LEGAL, and it leaves body prose citing rules that pack owns. That state
+ * has to be visible — a silent dangling citation is how prose and boundary drift apart — but
+ * reporting it as a problem would make `doctor` exit 1 over a configuration its owner chose.
+ * So `cmdDoctor` prints notes and does not count them.
+ */
+const NOTE = '[note] ';
+export const isDoctorNote = (p) => p.startsWith(NOTE);
+
+/**
+ * The three-tier constitution's own authoring gates — the doctrine twin of the `LAW_CLASS` /
+ * `LAW_META` family, plus the two purity rules the tiering rests on.
+ *
+ * IT LIVES BESIDE `countTableProblems` RATHER THAN INSIDE IT, and is called from
+ * `authoringProblems` beside `registry`/`secret`/`vendorPin`. `countTableProblems` opens by
+ * reading `AGENT.md.tmpl` and HARD-RETURNS if that read fails, so an arm placed inside it
+ * would go quiet on exactly the tree that is most broken. Nothing here needs the template's
+ * tables, and `proseMirrorProblems` — the frozen recording — is untouched either way.
+ *
+ * ⚠ THE VOCABULARY GATES ARE HERE BECAUSE `themeParityProblems` CANNOT SEE THEM. That check is
+ * presence-only and SYMMETRIC over the union of every theme's keys: a key missing from all
+ * fourteen is in parity, and a key whose VALUE breaks a parser is not its business at all. So
+ * `DOC_*` coverage, the `LEX_I..LEX_IX` equality and the single-word tier noun each need a gate
+ * that reads the SOURCE and asks what the source requires.
+ */
+export function constitutionProblems() {
+  const problems = [];
+  const dir = path.join(SRC, 'doctrines');
+
+  // ---- the packs themselves: present, contiguous from 1, and filed where they say they are.
+  const rules = new Map();                                    // 'craft.1' -> title-less marker
+  for (const pack of PACK_ORDER) {
+    const file = path.join(dir, `${pack}.md`);
+    let text;
+    try { text = readText(file); } catch (e) {
+      problems.push(`[authoring] doctrines/${pack}.md is named in PACK_ORDER but unreadable: `
+        + `${e.message} — the build ships the whole catalogue, so a missing pack file breaks `
+        + 'every citation into it, active or not');
+      continue;
+    }
+    const found = [...text.matchAll(DOCTRINE_HEADING_RE)];
+    if (!found.length) {
+      problems.push(`[authoring] doctrines/${pack}.md carries no '### {{DOCTRINE}} ${pack} <n>' `
+        + 'heading — the pack would render as an empty section');
+      continue;
+    }
+    found.forEach(([, named, n], i) => {
+      if (named !== pack) {
+        problems.push(`[authoring] doctrines/${pack}.md holds a rule addressed to '${named} `
+          + `${n}' — a rule's pack is read from its heading, so this one is unreachable at `
+          + `'${pack}.${n}' and shadows whatever ${named}.md numbers ${n}`);
+      }
+      if (Number(n) !== i + 1) {
+        problems.push(`[authoring] doctrines/${pack}.md rule ${n} is at position ${i + 1} — `
+          + 'pack ids must run contiguously from 1, or a citation addresses a gap');
+      }
+      rules.set(`${named}.${Number(n)}`, true);
+    });
+  }
+
+  // The console's Principle column, keyed off the rules just parsed — so the gate is driven by
+  // the SOURCE and a rule added to a pack file is caught the same day, not when someone
+  // notices a blank description in the browser.
+  problems.push(...doctrineMetaProblems([...rules.keys()]));
+
+  // ---- every `{{DOCTRINE}} <pack> <n>` anywhere in src/ resolves to a rule that exists.
+  //
+  // The whole tree, not the template: a skill footer citing `process 9` is as broken as a
+  // template one, and it is the shape 339 rewired citations could have left behind.
+  const cited = new Map();                                    // 'process.5' -> [rel, …]
+  for (const p of rglob(SRC)) {
+    if (!isFile(p) || !(p.endsWith('.md') || p.endsWith('.tmpl'))) continue;
+    let text;
+    try { text = readText(p); } catch { continue; }
+    const rel = path.relative(SRC, p).split(path.sep).join('/');
+    // ⚠ AN ALWAYS-ON TIER MAY NEVER CITE A TOGGLEABLE ONE (D2). A `--doctrines craft` build
+    // ships invariants that point at rules its AGENT.md does not contain; the ontology is
+    // worse still, being the tier that states the order the others sit in. Doctrine->doctrine
+    // citations are fine and stay: the full catalogue ships in every bundle.
+    if ((rel.startsWith('ontology/') || rel.startsWith('laws/')) && DOCTRINE_TOKEN_RE.test(text)) {
+      problems.push(`[authoring] ${rel} cites {{DOCTRINE}} — an always-on tier may never `
+        + 'reference a toggleable one, or a pack-off build ships a rule pointing at text '
+        + 'that is not there. State the point directly instead');
+    }
+    for (const [, pack, n] of text.matchAll(DOCTRINE_CITE_RE)) {
+      const key = `${pack}.${Number(n)}`;
+      if (!cited.has(key)) cited.set(key, []);
+      cited.get(key).push(rel);
+    }
+  }
+  for (const [key, where] of [...cited].sort()) {
+    if (rules.has(key)) continue;
+    problems.push(`[authoring] ${where[0]} cites {{DOCTRINE}} ${key.replace('.', ' ')}, which `
+      + `no pack file defines${where.length > 1 ? ` (and ${where.length - 1} more)` : ''}`);
+  }
+
+  // ---- the vocabulary every theme owes the source.
+  const wanted = new Set();
+  for (const pack of PACK_ORDER) {
+    let text;
+    try { text = readText(path.join(dir, `${pack}.md`)); } catch { continue; }
+    for (const [, key] of text.matchAll(DOC_TOKEN_RE)) wanted.add(key);
+  }
+  const lexWant = ['I', 'II', 'III', 'IV', 'V', 'VI', 'VII', 'VIII', 'IX'].map((r) => `LEX_${r}`);
+  // `_TEMPLATE.json` is included — it is the file `--sync-themes` seeds a new theme from, so a
+  // stale key there propagates into every voice added afterwards. `themeFiles()` excludes it.
+  const files = [...themeFiles(), path.join(THEMES, '_TEMPLATE.json')];
+  for (const f of files) {
+    const name = path.basename(f);
+    let theme;
+    try { theme = parseJson(readText(f)); } catch (e) {
+      problems.push(`[authoring] ${name} unreadable: ${e.message}`);
+      continue;
+    }
+    if (!theme || typeof theme !== 'object' || Array.isArray(theme)) continue;
+    const keys = Object.keys(theme);
+    for (const key of [...wanted].sort()) {
+      if (!Object.hasOwn(theme, key)) {
+        problems.push(`[authoring] ${name} has no {${key}} — a doctrine file names it, and `
+          + 'theme parity cannot see a key that is missing from every theme at once');
+      }
+    }
+    for (const key of keys.filter((k) => k.startsWith('DOC_')).sort()) {
+      if (!wanted.has(key)) {
+        problems.push(`[authoring] ${name} defines {${key}}, which no doctrine file uses — a `
+          + 'dead voice key ships a title for a rule that does not exist');
+      }
+    }
+    // I1 — an EQUALITY, not a presence check. The renumber left `LEX_XXII`, `LEX_XXIII`,
+    // `LEX_XXIV` and `LEX_XXXVI` behind in all fifteen files, and parity was silent because
+    // they were absent from nowhere.
+    const lex = keys.filter((k) => k.startsWith('LEX_')).sort();
+    const stale = lex.filter((k) => !lexWant.includes(k));
+    const missing = lexWant.filter((k) => !lex.includes(k));
+    for (const k of stale) {
+      problems.push(`[authoring] ${name} still defines {${k}} — the invariants are I..IX and `
+        + 'nothing renders this key, so it is a title for a rule that no longer exists');
+    }
+    for (const k of missing) {
+      problems.push(`[authoring] ${name} has no {${k}} — one of the nine invariants would `
+        + 'render with an empty title');
+    }
+    // M10 — ⚠ BOTH HEADING PARSERS MATCH THE TIER NOUN WITH `\S+`. A two-word value does not
+    // error; the heading stops matching and the tier silently parses to nothing. `_TEMPLATE`'s
+    // values are descriptive placeholders, so only real voices are held to this.
+    if (name === '_TEMPLATE.json') continue;
+    for (const key of ['LAW', 'DOCTRINE']) {
+      const v = theme[key];
+      if (typeof v === 'string' && /\s/.test(v)) {
+        problems.push(`[authoring] ${name} spells {${key}} as ${pyRepr(v)} — the heading `
+          + 'parsers match the tier noun with \\S+, so a value with a space makes every '
+          + `${key === 'LAW' ? 'invariant' : 'doctrine rule'} parse to nothing, in silence`);
+      }
+    }
+  }
+
+  // ---- every `§N` in src/ addresses a section the template actually declares.
+  //
+  // ⚠ THIS GATE IS NARROW AND SAYS SO. Inserting `## 2. Doctrines` pushed every later section
+  // down one, and the sweep that fixed the template's own cross-references stopped at the
+  // template — four satellites under `src/skills/` and `src/agents/` kept pointing at the
+  // section that used to be there, and they RENDER INTO EVERY BUNDLE. A range check would not
+  // have caught those: §7 still existed, it had just stopped being the Wiki.
+  //
+  // What it does catch is the other half of a renumber — a pointer past the end, which is what
+  // REMOVING a section leaves behind — and it is nearly free. The half it cannot catch is a
+  // judgement about intent, and `docs/extending.md` carries the manual sweep for it. Naming
+  // that limit here is the point: a reader who assumes this gate is total will skip the sweep.
+  const declared = new Set();
+  // Read here rather than borrowing `countTableProblems`' copy: that function hard-returns when
+  // the template is unreadable, and this gate must not inherit a silence it did not choose.
+  let tmpl = '';
+  try { tmpl = readText(path.join(SRC, 'AGENT.md.tmpl')); } catch { tmpl = ''; }
+  for (const [, n] of tmpl.matchAll(/^## (\d+)\.\s/gm)) declared.add(Number(n));
+  if (declared.size) {
+    for (const p of rglob(SRC)) {
+      if (!isFile(p) || !(p.endsWith('.md') || p.endsWith('.tmpl'))) continue;
+      let text;
+      try { text = readText(p); } catch { continue; }
+      const rel = path.relative(SRC, p).split(path.sep).join('/');
+      for (const [, n] of text.matchAll(/§(\d+)/g)) {
+        if (declared.has(Number(n))) continue;
+        problems.push(`[authoring] ${rel} cites AGENT.md §${n}, and the template declares no `
+          + `such section ${pyRepr([...declared].sort((a, b) => a - b).map(String))} — a `
+          + 'renumber moved it, and this pointer renders into every bundle');
+      }
+    }
+  }
+
+  // ---- the build default names packs that exist.
+  let cfgDoctrines = null;
+  try {
+    const cfg = parseJson(readText(CONFIG));
+    if (cfg && typeof cfg === 'object' && Array.isArray(cfg.doctrines)) cfgDoctrines = cfg.doctrines;
+  } catch { /* no config, or unreadable — `configDefaults()` is forgiving here too */ }
+  if (cfgDoctrines) {
+    for (const pack of cfgDoctrines) {
+      if (!PACK_ORDER.includes(pack)) {
+        problems.push(`[authoring] harness.config.json names doctrine pack ${pyRepr(pack)}, `
+          + `which this checkout does not ship ${pyRepr([...PACK_ORDER])} — every build reading `
+          + 'that default would fail');
+      }
+    }
+  }
+
+  // ---- D5, a NOTE and not a problem: what a narrowed default leaves pointing at the shelf.
+  const on = cfgDoctrines ?? [...PACK_ORDER];
+  const dangling = [...cited].filter(([k]) => rules.has(k) && !on.includes(k.split('.')[0]));
+  if (dangling.length) {
+    const packs = [...new Set(dangling.map(([k]) => k.split('.')[0]))].sort();
+    problems.push(`${NOTE}harness.config.json builds ${pyRepr(on)}, and ${dangling.length} `
+      + `citation(s) in src/ point into ${packs.join(', ')}. Those rules still SHIP — every `
+      + 'pack file is in the bundle — so the reference resolves on disk; it is the rendered '
+      + 'AGENT.md that will not contain them. Legal, and recorded here so it is not silent');
+  }
+  return problems;
+}
+
 /**
  * `_harness_build._count_table_problems` — the hand-authored AGENT.md tables and the README
  * badges, against `src/`.
@@ -821,9 +1122,19 @@ export function countTableProblems() {
   };
   let readme;
   try { readme = readText(path.join(ROOT, 'README.md')); } catch { return problems; }
+  // ⚠ PRESENCE FIRST, THEN THE VALUE — the same absence arm the SHIPPED triple needed, for the
+  // same reason: `if (m && …)` is green when there is no badge, so deleting a badge silences its
+  // own gate. The `continue` keeps the loop's MESSAGE ORDER intact, which is load-bearing (see
+  // the `plugins`-is-last comment above): a missing badge reports in its own slot rather than
+  // reordering the ones after it.
   for (const [key, n] of Object.entries(counts)) {
     const m = new RegExp(`badge/${key}-(\\d+)`).exec(readme);
-    if (m && Number(m[1]) !== n) {
+    if (!m) {
+      problems.push(`[authoring] README has no ${key} badge — deleting one is how this gate `
+        + 'goes green while the reader is told nothing');
+      continue;
+    }
+    if (Number(m[1]) !== n) {
       problems.push(`[authoring] README ${key} badge says ${m[1]} but src has ${n}`);
     }
   }
@@ -843,8 +1154,34 @@ export function countTableProblems() {
     web = globSorted(path.join(ROOT, 'docs', 'web'), (n) => n.endsWith('.md'))
       .map(readText).join('\n');
   } catch { web = ''; }
+  // ⚠ NOT FAIL-SOFT, UNLIKE `web` ABOVE, AND THE ASYMMETRY IS THE POINT. A missing `docs/web`
+  // tree is not an authoring fault — a checkout can legitimately lack it. SHIPPED.md is a
+  // tracked, shipped file that this function asserts the CONTENT of, so an unreadable one is
+  // indistinguishable from a deleted claim: swallowing it into `''` used to hand the triple arm
+  // an empty string and turn a hard read failure into a silent pass.
+  // ⚠ NOT FAIL-SOFT, UNLIKE `web` ABOVE, AND THE ASYMMETRY IS THE POINT. A missing `docs/web`
+  // tree is not an authoring fault — a checkout can legitimately lack it. SHIPPED.md is a
+  // tracked, shipped file whose CONTENT this function asserts, so an unreadable one was
+  // indistinguishable from a deleted claim: swallowing it into `''` handed the triple arm an
+  // empty string and turned a hard read failure into a silent pass.
+  //
+  // AND THE PRESENCE OF THE TRIPLE IS CHECKED HERE rather than inside `proseMirrorProblems`,
+  // which is where it belongs by subject and cannot go by construction — that function is
+  // recorded in `tests/__snapshots__/primitives/` with a case that passes an empty `shipped` and
+  // expects `[]`, and nothing can re-bless a recording whose recorder is deleted. This is the
+  // caller, it is not recorded, and it already owns the question "could the file be read".
   let shipped;
-  try { shipped = readText(path.join(ROOT, 'SHIPPED.md')); } catch { shipped = ''; }
+  try {
+    shipped = readText(path.join(ROOT, 'SHIPPED.md'));
+  } catch (e) {
+    problems.push(`[authoring] SHIPPED.md is unreadable (${e.message}) — the counts it carries `
+      + 'cannot be checked, and a gate that cannot read its subject must say so');
+    shipped = '';
+  }
+  if (shipped && !/(\d+) laws, (\d+) agents, (\d+) skills/.test(shipped)) {
+    problems.push('[authoring] SHIPPED.md carries no \'N laws, N agents, N skills\' line — '
+      + 'deleting it is how that gate goes green while the count drifts');
+  }
   problems.push(...proseMirrorProblems(readme, web, counts, skillFiles, shipped));
   return problems;
 }
@@ -943,6 +1280,7 @@ export function authoringProblems() {
   problems.push(...registryProblems());
   problems.push(...secretProblems());
   problems.push(...vendorPinProblems());
+  problems.push(...constitutionProblems());
   problems.push(...countTableProblems());
   return problems;
 }
@@ -1144,17 +1482,26 @@ function captureBoth(fn) {
  * maintainer sweep. The cross-theme parity check runs in every mode.
  */
 export function cmdDoctor(args) {
-  const [themes, problems] = doctorCollect({
+  const [themes, collected] = doctorCollect({
     theme: args.theme, allThemes: Boolean(args.all), bundle: args.bundle,
     noBundle: Boolean(args.noBundle),
   });
   if (!themes.length) {
-    pyPrint(`${problems.length ? problems[0] : '[doctor] no themes found'}\n`);
+    pyPrint(`${collected.length ? collected[0] : '[doctor] no themes found'}\n`);
     return 1;
   }
+  // ⚠ NOTES ARE PRINTED AND NOT COUNTED. The only producer is the pack-off citation report in
+  // `constitutionProblems`, and the state it describes is one the install's owner chose: a
+  // build that leaves body prose citing a pack it did not render. Silence there is how prose
+  // and boundary drift apart, and a non-zero exit there is doctor failing a legal
+  // configuration. Nothing in the recorded CLI corpus produces one — the checkout's own
+  // `harness.config.json` names no packs — so the byte-compared output is unmoved.
+  const notes = collected.filter(isDoctorNote);
+  const problems = collected.filter((p) => !isDoctorNote(p));
   const scoped = !args.theme && !args.all && themes.length === 1;
   const note = scoped
     ? `  (scoped to installed theme '${themes[0]}'; run with --all to sweep every theme)` : '';
+  for (const n of notes) pyPrint(`${n}\n`);
   if (problems.length) {
     pyPrint(`[doctor] ${problems.length} problem(s) across ${themes.length} theme(s):\n`);
     for (const p of problems) pyPrint(`  - ${p}\n`);
@@ -1163,15 +1510,16 @@ export function cmdDoctor(args) {
         + '`./geneseed update` (or re-sync src/), then re-check.\n');
     }
     if (problems.some((p) => p.startsWith('[themes]') && p.includes('missing key'))) {
-      // `./geneseed build --sync-themes`, and the spelling is a one-shot decision frozen in
-      // two fixtures, so it is argued here. The FRONT DOOR, not an interpreter and a file:
-      // `build` forwards its extra arguments to the generator, so the tip names a command that
-      // works today AND after the Python is deleted — which naming the interpreter and the
-      // generator's file, as the old tip did, would not. The `./` prefix matches the sibling tip
-      // five lines up (`./geneseed update`) and is honest about the audience: this problem is
-      // only reachable while authoring themes in a checkout, which is where `./geneseed` is.
+      // ⚠ THE TIP USED TO NAME `./geneseed build --sync-themes`, AND THAT COMMAND ERRORS.
+      // It was argued here on the premise that "`build` forwards its extra arguments to the
+      // generator" — which was true of the reference and is not true of `cmdBuild`
+      // (`js/generate.mjs`), which forwards `--theme` and nothing else. So the front door
+      // answered `unrecognized arguments: --sync-themes` to anyone who followed doctor's own
+      // advice, for as long as the premise went unchecked. The flag belongs to the GENERATOR,
+      // whose binary is `geneseed-build` — which is what `README.md` and `SETUP.md` have said
+      // all along. A hint is a command; if it is not runnable it is decoration.
       pyPrint('  tip: a theme is missing a key another theme defines — run '
-        + '`./geneseed build --sync-themes` to fill it from _TEMPLATE.json, '
+        + '`geneseed-build --sync-themes` to fill it from _TEMPLATE.json, '
         + 'then restyle the added key(s) and re-check.\n');
     }
     if (note) pyPrint(`${note}\n`);

package/js/emit.mjs

@@ -87,8 +87,29 @@ import {
 } from './lib/fs.mjs';
 /** `_build_render.SRC_DIRS_MARKER`. */
 const SRC_DIRS_MARKER = '.geneseed-srcdirs.json';
-/** `_build_render.OWNED_SRC_DIRS` — wiped and regenerated each run. */
-const OWNED_SRC_DIRS = ['laws', 'agents', 'skills'];
+/**
+ * `_build_render.OWNED_SRC_DIRS` — wiped and regenerated each run.
+ *
+ * `ontology` and `doctrines` are appended, not inserted: this array's iteration order is the
+ * key order of the `.geneseed-srcdirs.json` marker it fills, and appending keeps the three
+ * original keys where an existing install's marker already has them.
+ *
+ * They belong here for the same reason `laws` does — they are GENERATED, so an install must
+ * not keep a copy the source no longer produces. Without them a build writes the dirs on
+ * every run and never wipes them, which turns the doctrines toggle into a one-way switch:
+ * disable a pack, rebuild, and its rendered file sits in the install forever, contradicting
+ * the `Active packs:` line in the AGENT.md right beside it.
+ */
+const OWNED_SRC_DIRS = ['laws', 'agents', 'skills', 'ontology', 'doctrines'];
+
+/**
+ * The constitution dirs a LEAN emit re-ships in full text — see `shipLeanLaws`.
+ *
+ * Not all of `OWNED_SRC_DIRS`: `agents` and `skills` are already written as whole files by
+ * the native layer, and only the three constitution dirs are inlined into AGENT.md in a
+ * form (terse, or pack-filtered) that loses text the reader may still need.
+ */
+const LEAN_FULL_TEXT_DIRS = ['laws', 'ontology', 'doctrines'];
 
 /**
  * `_build_core.CAPABILITY_LINK_RE` — the DEFAULT only.
@@ -824,7 +845,8 @@ export function emitOpencodeRender(cfg, job) {
   // (`_rel_under` is the Python side by design), and only the BASENAME is consumed
   // downstream: `opencode.json`, or the `.jsonc` sibling when that is what is on disk.
   phaseLog('WIRE');
-  const cfgName = path.basename(mergeOpencodeJson(path.join(root, 'opencode.json'), agentPath));
+  const cfgName = path.basename(mergeOpencodeJson(path.join(root, 'opencode.json'), agentPath,
+    cfg.doctrines));
 
   return {
     owned,
@@ -929,16 +951,27 @@ function globalNotebook(cfgDir, items, legacy, srcRoot) {
  * output besides the files is what it APPENDS to `owned` — which travels back in the
  * payload for the manifest and the prune. It reads nothing any wiring stage writes, so
  * its new position is not merely legal, it has no dependency on the old one.
+ *
+ * NO LONGER LEAN-ONLY, and the name is kept because the lean case is still the whole reason
+ * it exists. `doctrines` ships at BOTH footprints, because the two footprints lose different
+ * things: lean loses text (every rule is truncated to its first sentence, so the full text has
+ * to be on disk), while FULL loses whole packs (only the active ones are inlined, so the
+ * inactive ones have to be on disk). AGENT.md tells the agent it may read a rule in a pack
+ * that is not active, and `src/doctrines/README.md` rests cross-pack citations on exactly
+ * that — a claim the emit has to make true, not merely the `files` bundle.
  */
-function shipLeanLaws(items, theme, cfgDir, owned) {
-  const lawsDir = theme.DIR_LAWS ?? 'laws';
+function shipLeanLaws(items, theme, cfgDir, owned, footprint) {
+  // Themed names, resolved through the same token table `build`'s wipe resolves, so the dir
+  // a lean emit re-ships and the dir it prunes can never be two different spellings.
+  const wanted = footprint === 'lean' ? LEAN_FULL_TEXT_DIRS : ['doctrines'];
+  const dirs = new Set(wanted.map((d) => theme[SRC_DIR_TOKENS[d]] ?? d));
   for (const { rel, text } of items) {
     const parts = rel.split('/');
     // `parts.length` mirrors Python's `parts and parts[0]`, where `Path("").parts` really
     // is empty. `String.split` never returns an empty array, so this half can never be
     // false here — kept for the mirror, and its mutation stays green because there is
     // nothing to detect, not because the gate cannot see it.
-    if (text !== null && parts.length && parts[0] === lawsDir) {
+    if (text !== null && parts.length && dirs.has(parts[0])) {
       const dest = path.join(cfgDir, ...parts);
       mkdirSync(path.dirname(dest), { recursive: true });
       writeText(dest, text);
@@ -1039,7 +1072,7 @@ export function emitOpencodeGlobalRender(cfg, job) {
   writeVersion(cfg, cfgDir);
   owned.push(VERSION_MARKER);
 
-  if (footprint === 'lean') shipLeanLaws(items, theme, cfgDir, owned);
+  shipLeanLaws(items, theme, cfgDir, owned, footprint);
 
   // WIRE — the one file of this emit the user co-owns, and the last render is now behind
   // us. Inlined the way `emitOpencodeRender`'s is (one call, the same merge, the same
@@ -1047,7 +1080,7 @@ export function emitOpencodeGlobalRender(cfg, job) {
   // that split is what `tests/test_emit_phase_order.py` walks, and it walks the Python.
   phaseLog('WIRE');
   const cfgName = path.basename(mergeOpencodeJson(path.join(cfgDir, 'opencode.json'),
-    agentPath));
+    agentPath, cfg.doctrines));
 
   return {
     owned,
@@ -1170,7 +1203,7 @@ export function emitClaudeRender(cfg, job) {
   writeVersion(cfg, cfgDir);
   owned.push(VERSION_MARKER);
 
-  if (footprint === 'lean') shipLeanLaws(items, theme, cfgDir, owned);
+  shipLeanLaws(items, theme, cfgDir, owned, footprint);
 
   // The last render of the emit, and the only one whose product is not written here.
   // Bob at GLOBAL scope gets no managed block at all, so nothing is rendered for it —
@@ -1183,7 +1216,7 @@ export function emitClaudeRender(cfg, job) {
 
   // WIRE — see `claudeWire` below. One child per emit, so the two halves are two
   // functions rather than two spawns; the seam between them is a call, not a process.
-  const managed = claudeWire(job, claudeMdText, agentText !== null);
+  const managed = claudeWire(job, claudeMdText, agentText !== null, cfg.doctrines);
 
   return {
     owned,
@@ -1218,7 +1251,7 @@ export function emitClaudeRender(cfg, job) {
  * not needed for it: Python tests `os.environ.get(...)` for truthiness and an env var is
  * always a string, so `''` is the only falsy value either language sees.
  */
-function claudeWire(job, claudeMdText, hasAgentText) {
+function claudeWire(job, claudeMdText, hasAgentText, doctrines = null) {
   phaseLog('WIRE');
   const { cfgDir, claudeMd, scope, host, oldManaged, preambleExclude, hookOpts } = job;
   const old = oldManaged && typeof oldManaged === 'object' && !Array.isArray(oldManaged)
@@ -1274,8 +1307,12 @@ function claudeWire(job, claudeMdText, hasAgentText) {
     // The merge prunes recorded groups that are no longer canonical and returns the
     // COMPLETE current claim set — store it as-is; unioning with prior would resurrect the
     // stale claims.
+    // `doctrines` decides whether the git-gate group is part of the canonical claim set. It
+    // travels from `cfg` rather than being re-read off the deployment: this is the emit that
+    // DECIDES the install's packs, so the marker on disk is still the previous build's.
     const [, managedHooks] = mergeClaudeSettings(
       settingsPath, scope, oldSf === settingsName ? get(old, 'settings_hooks') : null, hookOpts,
+      doctrines,
     );
     managed.settings_hooks = managedHooks;