geneseed 3.8.0 → 3.9.0

package/js/inspect/checks-authoring.mjs

@@ -13,7 +13,8 @@
  */
 import path from 'node:path';
 import {
-  CONFIG, PACK_ORDER, PLUGIN_SRC, ROOT, SRC, THEMES, knownRuleIds,
+  CONFIG, PACK_ORDER, PLUGIN_SRC, RETIRED_RULE_IDS, ROOT, RULE_ID_RE, SRC, THEMES, canonFiles,
+  knownRuleIds, ruleCanon, titleKey,
 } from '../build/source.mjs';
 import { themeFiles } from '../hosts/installs.mjs';
 import { descBlockProblem, firstBlockquote } from '../hosts/native.mjs';
@@ -47,7 +48,11 @@ export function romanToInt(num) {
 }
 
 /**
- * `_harness_build._LAW_META_ROW` — `<arabic>: ['<class>', '<principle>'],` in the web page.
+ * `_harness_build._LAW_META_ROW` — `<arabic>: ['<class>', '<principle>', '<id>'],` in the web page.
+ *
+ * The third field PINS the row to a rule id. The key is the number the catalogue renders, and a
+ * number is only a position: remove a law and every later row describes its predecessor's
+ * neighbour, with every class still plausible. The pin is what makes that a doctor failure.
  *
  * Either quote style, because a principle carrying an apostrophe is double-quoted. Every
  * `\s*` spans newlines and the trailing comma before `]` is optional, so a row a prettier has
@@ -57,7 +62,8 @@ export function romanToInt(num) {
  * `(?m)` is the `m` flag; JS has no inline form. The `.` inside the captures must NOT match a
  * newline (Python has no `re.S` here), which is JS's default.
  */
-const LAW_META_ROW = /^[^\S\n]*(\d+):\s*\[\s*(['"])(.*?)\2\s*,\s*(['"])(.*?)\4\s*,?\s*\]\s*,?[^\S\n]*$/gm;
+const LAW_META_ROW =
+  /^[^\S\n]*(\d+):\s*\[\s*(['"])(.*?)\2\s*,\s*(['"])(.*?)\4\s*(?:,\s*(['"])(.*?)\6\s*)?,?\s*\]\s*,?[^\S\n]*$/gm;
 
 /**
  * `_harness_build._law_meta_problems` — the web Laws ledger's per-rule copy stays complete.
@@ -67,7 +73,7 @@ const LAW_META_ROW = /^[^\S\n]*(\d+):\s*\[\s*(['"])(.*?)\2\s*,\s*(['"])(.*?)\4\s
  * description and the wrong class chip, while everything upstream is fine. That is exactly
  * how two laws shipped description-less.
  */
-export function lawMetaProblems(lawNums, lawClass, lawClasses) {
+export function lawMetaProblems(lawNums, lawClass, lawClasses, lawIds = null) {
   const page = path.join(ROOT, 'web', 'src', 'pages', 'Laws.jsx');
   let text;
   try { text = readText(page); } catch (e) {
@@ -80,11 +86,11 @@ export function lawMetaProblems(lawNums, lawClass, lawClasses) {
   }
   const meta = new Map();
   for (const m of block[1].matchAll(LAW_META_ROW)) {
-    meta.set(Number(m[1]), [m[3], m[5]]);
+    meta.set(Number(m[1]), [m[3], m[5], m[7]]);
   }
   const problems = [];
   const seen = new Set();
-  for (const roman of lawNums) {
+  for (const [i, roman] of lawNums.entries()) {
     const n = romanToInt(roman);
     seen.add(n);
     if (!meta.has(n)) {
@@ -93,7 +99,12 @@ export function lawMetaProblems(lawNums, lawClass, lawClasses) {
         + 'render it with a blank Principle');
       continue;
     }
-    const [klass, principle] = meta.get(n);
+    const [klass, principle, pin] = meta.get(n);
+    if (lawIds && pin !== lawIds[i]) {
+      problems.push(`[authoring] LAW_META[${n}] is pinned to '${pin ?? '(no id)'}' but rule ${roman} is `
+        + `'${lawIds[i]}' — the rows no longer follow the canon's order, so this principle `
+        + 'describes a different law');
+    }
     if (!principle.trim()) {
       problems.push(`[authoring] LAW_META[${n}] has an empty principle line — rule `
         + `${roman} would render with a blank description`);
@@ -112,9 +123,9 @@ export function lawMetaProblems(lawNums, lawClass, lawClasses) {
   return problems;
 }
 
-/** `LAW_META_ROW`'s twin for a STRING key — `'<pack>.<n>': ['<pack>', '<principle>'],`. */
+/** `LAW_META_ROW`'s twin for a STRING key — `'<pack>.<n>': ['<pack>', '<principle>', '<id>'],`. */
 const DOCTRINE_META_ROW =
-  /^[^\S\n]*(['"])([a-z]+\.\d+)\1:\s*\[\s*(['"])(.*?)\3\s*,\s*(['"])(.*?)\5\s*,?\s*\]\s*,?[^\S\n]*$/gm;
+  /^[^\S\n]*(['"])([a-z]+\.\d+)\1:\s*\[\s*(['"])(.*?)\3\s*,\s*(['"])(.*?)\5\s*(?:,\s*(['"])(.*?)\7\s*)?,?\s*\]\s*,?[^\S\n]*$/gm;
 
 /**
  * `lawMetaProblems`' doctrine half — the console's per-rule Principle column stays complete.
@@ -130,7 +141,7 @@ const DOCTRINE_META_ROW =
  * 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) {
+export function doctrineMetaProblems(addrs, ids = null) {
   const page = path.join(ROOT, 'web', 'src', 'pages', 'Laws.jsx');
   let text;
   try { text = readText(page); } catch (e) {
@@ -142,17 +153,21 @@ export function doctrineMetaProblems(addrs) {
       + "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]]);
+  for (const m of block[1].matchAll(DOCTRINE_META_ROW)) meta.set(m[2], [m[4], m[6], m[8]]);
   const problems = [];
   const seen = new Set();
-  for (const addr of addrs) {
+  for (const [i, addr] of addrs.entries()) {
     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);
+    const [klass, principle, pin] = meta.get(addr);
+    if (ids && pin !== ids[i]) {
+      problems.push(`[authoring] DOCTRINE_META['${addr}'] is pinned to '${pin ?? '(no id)'}' but `
+        + `that address is '${ids[i]}' now — the row describes a different rule`);
+    }
     if (!principle.trim()) {
       problems.push(`[authoring] DOCTRINE_META['${addr}'] has an empty principle line — that `
         + 'rule would render with a blank description');
@@ -267,22 +282,35 @@ export function proseMirrorProblems(readme, web, counts, skillStems, shipped = '
 
 /** `_build_render._TMPL_SPEC_RE`, as the count gate spells it. */
 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/inspect/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 rule is DECLARED by its heading and CITED by its id — see `ruleCanon` in
+// `js/build/source.mjs`. The gates below read the RAW source, because the render resolves ids and
+// a bad one would already be gone from what it hands back.
+const DECL_LINE_RE = /^### \{\{(LAW|DOCTRINE):([^}]*)\}\}[ \t]+\S/;
+const ID_CITE_RE = /\{\{(LAW|DOCTRINE):([^}]*)\}\}/g;
+// The pre-id spellings. Either one in src/ is a citation that names a POSITION, which is exactly
+// what stops being true the next time the canon moves.
+const BARE_CITE_RE = /\{\{LAW\}\}\s+[IVXLCDM]+\b|\{\{DOCTRINE\}\}\s+[a-z]+\s+\d+\b/g;
+// `{{DOCTRINE}}` or `{{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(?:\}\}|:)/;
+
+/**
+ * The rules the hooks enforce at the tool boundary, and the address each is bound to there. The
+ * hook path cannot afford to read the canon on every tool call, so its gate-ledger keys
+ * (`law-1`, `law-4`, `process-1`, `process-5` in `js/hosts/hooks.mjs` and the OpenCode guard
+ * plugin), `CONSENT_RULE` in `js/hosts/settings.mjs` and the console's `HOOK_GATED` stay
+ * number-keyed — and this pin is what turns a renumber that moves one of these rules into a
+ * doctor failure instead of a gate silently guarding its neighbour.
+ */
+export const HOOK_PINNED = {
+  'sealed-secrets': 'I', 'deletion-is-deliberate': 'IV',
+  'persist-insight': 'process 1', 'consent-before-push': 'process 5',
+};
 
 /**
  * The LEAN block grammar, and the heading split, both duplicated from `js/build/render.mjs`.
  *
- * Deliberately duplicated, the way `DOCTRINE_HEADING_RE` above is: both are module-private
+ * Deliberately duplicated rather than imported: both are module-private
  * there, and exporting them so one gate could borrow them would widen the renderer's surface
  * for a reader that only needs to know the shape. Two literals, one paragraph apart from the
  * rule they encode, is cheaper than a seam.
@@ -377,48 +405,84 @@ export function leanBlockProblems() {
  * ⚠ 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_XI` equality and the single-word tier noun each need a gate
+ * `DOC_*` coverage, the `LEX_*` 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`);
+  // ---- every rule declares an id, every id is well-formed and unique, none is retired.
+  //
+  // Numbers are positional now (`ruleCanon`), so contiguity and filing cannot go wrong; what can
+  // is the declaration itself. A `### ` line in a canon file that is not `{{KIND:id}} Name`
+  // renders nowhere as a rule — no number, no title — and a duplicated id makes every citation
+  // of it ambiguous.
+  for (const [kind, pack, file] of canonFiles(SRC)) {
+    const rel = path.relative(SRC, file).split(path.sep).join('/');
     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');
+      problems.push(`[authoring] ${rel} is ${pack ? 'named in PACK_ORDER' : 'the canon'} but `
+        + `unreadable: ${e.message} — every citation into it breaks`);
       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}`);
+    let count = 0;
+    for (const line of text.split('\n').filter((l) => l.startsWith('### '))) {
+      const m = DECL_LINE_RE.exec(line);
+      if (!m || m[1] !== kind) {
+        problems.push(`[authoring] ${rel}: '${line}' is not a rule declaration — a rule heading `
+          + `here reads '### {{${kind}:<id>}} <Principle Name>'; without an id it has no number, `
+          + 'no title and no way to be cited');
+        continue;
       }
-      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');
+      count += 1;
+      if (!RULE_ID_RE.test(m[2])) {
+        problems.push(`[authoring] ${rel}: rule id '${m[2]}' is not kebab-case (a-z, 0-9, '-')`);
       }
-      rules.set(`${named}.${Number(n)}`, true);
-    });
+    }
+    if (!count) {
+      const why = pack ? 'the pack would render as an empty section' : 'there would be no invariants';
+      problems.push(`[authoring] ${rel} declares no rule — ${why}`);
+    }
+  }
+  const canon = ruleCanon(SRC);
+  const seenIds = new Map();
+  const seenNames = new Map();
+  for (const r of canon.rules) {
+    const where = r.kind === 'LAW' ? `law ${r.label}` : `doctrine ${r.label}`;
+    if (seenIds.has(r.id)) {
+      problems.push(`[authoring] rule id '${r.id}' is declared twice (${seenIds.get(r.id)} and `
+        + `${where}) — ids are unique across laws and doctrines, or a citation names two rules`);
+    } else seenIds.set(r.id, where);
+    const lower = r.name.toLowerCase();
+    if (seenNames.has(lower)) {
+      problems.push(`[authoring] principle name '${r.name}' is declared twice (${seenNames.get(lower)} `
+        + `and ${where}) — a citation renders as the name, so two rules would read as one`);
+    } else seenNames.set(lower, where);
+    const retiredAs = RETIRED_RULE_IDS[r.id];
+    if (retiredAs && retiredAs.liveAs !== r.kind) {
+      problems.push(`[authoring] ${where} reuses the retired id '${r.id}' (${retiredAs.was}, `
+        + `${retiredAs.note}) — an id that meant one rule in someone's notes must never come back `
+        + 'meaning another; pick a new one');
+    }
+  }
+  const rules = new Map(canon.rules.filter((r) => r.kind === 'DOCTRINE')
+    .map((r) => [`${r.pack}.${r.n}`, r]));
+
+  // ---- the hook-gated rules are still at the address the hooks key them by.
+  for (const [id, label] of Object.entries(HOOK_PINNED)) {
+    const r = canon.byId.get(id);
+    if (!r || r.label !== label) {
+      problems.push(`[authoring] the hooks gate '${id}' as ${label} (js/hosts/hooks.mjs ledger keys, `
+        + `settings.mjs CONSENT_RULE, the console's HOOK_GATED), but the canon ${r ? `numbers it ${r.label}`
+          : 'no longer declares it'} — move those keys with it, or the tool boundary guards a `
+        + 'different rule than the prompt names');
+    }
   }
 
   // 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()]));
+  problems.push(...doctrineMetaProblems([...rules.keys()], [...rules.values()].map((r) => r.id)));
 
   // ---- `--exclude-rules` closes against the SAME rules this walk just found.
   //
@@ -440,41 +504,11 @@ export function constitutionProblems() {
       + 'no switch for it');
   }
 
-  // ---- the consent gate's address still names the consent rule.
-  //
-  // ⚠ THE ONE HARDCODED ADDRESS IN THE CODEBASE, and the one whose drift is silent AND unsafe.
-  // `js/hosts/settings.mjs` keys the git-gate hooks on `process.5` by literal; a renumber of the
-  // process pack moves that rule's neighbours under it, and the boundary would then follow
-  // whatever rule inherited the number while the prompt still said `process 5`. Checked
-  // against the pack file's own title token rather than against prose, so a reworded rule is
-  // not a false alarm and a MOVED one is not a silent pass.
-  const consentTitle = 'DOC_PROCESS_5';
-  let processText = '';
-  try { processText = readText(path.join(dir, 'process.md')); } catch { /* reported above */ }
-  if (processText && !new RegExp(`^### \\{\\{DOCTRINE\\}\\} process 5 — \\{\\{${consentTitle}\\}\\}`,
-    'm').test(processText)) {
-    problems.push('[authoring] js/hosts/settings.mjs gates git commit/push on doctrine \'process 5\', '
-      + `but doctrines/process.md does not number {${consentTitle}} 5 — the tool boundary and `
-      + 'the prompt now name different rules');
-  }
-
-  // ---- every `{{DOCTRINE}} <pack> <n>` anywhere in src/ resolves to a rule that exists.
+  // ---- every citation in src/ is by id, and every id resolves.
   //
-  // 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.
+  // The whole tree, not the template: a skill footer citing a rule that does not exist is as
+  // broken as a template one, and it renders into every bundle.
   const cited = new Map();                                    // 'process.5' -> [rel, …]
-  // ⚠ A RETIRED LAW KEEPS ITS NUMBER, SO A CITATION OF IT STILL RESOLVES — to "Retired". Laws
-  // are appended, never renumbered, which is what keeps ~150 cross-references stable; the price
-  // is that nothing else notices `{{LAW}} IX` in a skill that means "ask first" (it is rigor 5
-  // now) or `{{LAW}} XI` that means "verify" (folded into III). Read off the canon itself, so a
-  // law retired tomorrow is covered the same day.
-  const retired = new Set();
-  try {
-    for (const [, num] of readText(path.join(SRC, 'laws', 'universal.md'))
-      .matchAll(/^### \{\{LAW\}\} ([IVXLCDM]+) —[^\n]*\n<!-- LEAN:begin -->\nRetired\b/gm)) {
-      retired.add(num);
-    }
-  } catch { /* an unreadable canon is reported elsewhere */ }
   for (const p of rglob(SRC)) {
     if (!isFile(p) || !(p.endsWith('.md') || p.endsWith('.tmpl'))) continue;
     let text;
@@ -489,35 +523,33 @@ export function constitutionProblems() {
         + 'reference a toggleable one, or a pack-off build ships a rule pointing at text '
         + 'that is not there. State the point directly instead');
     }
-    if (rel !== 'laws/universal.md') {
-      for (const [, num] of text.matchAll(/\{\{LAW\}\}\s+([IVXLCDM]+)\b/g)) {
-        if (retired.has(num)) {
-          problems.push(`[authoring] ${rel} cites {{LAW}} ${num}, which is retired — cite the `
-            + 'law or rule its text now lives in');
+    for (const [bare] of text.matchAll(BARE_CITE_RE)) {
+      problems.push(`[authoring] ${rel} cites '${bare.replace(/\s+/g, ' ')}' by number — numbers are `
+        + 'positional and move when the canon does; cite {{LAW:<id>}} / {{DOCTRINE:<id>}}');
+    }
+    for (const [whole, kind, id] of text.matchAll(ID_CITE_RE)) {
+      const r = canon.byId.get(id);
+      if (r && r.kind === kind) {
+        if (kind === 'DOCTRINE') {
+          const key = `${r.pack}.${r.n}`;
+          if (!cited.has(key)) cited.set(key, []);
+          cited.get(key).push(rel);
         }
+        continue;
       }
+      const retiredAs = RETIRED_RULE_IDS[id];
+      let why = 'which no law or doctrine declares — it would render as the raw token';
+      if (r) why = `but '${id}' is a ${r.kind === 'LAW' ? 'law' : 'doctrine rule'} — use {{${r.kind}:${id}}}`;
+      else if (retiredAs) {
+        why = `a retired id (${retiredAs.was}, ${retiredAs.note}) — cite the rule its text now lives in`;
+      }
+      problems.push(`[authoring] ${rel} cites ${whole}, ${why}`);
     }
-    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', 'X', 'XI']
-    .map((r) => `LEX_${r}`);
+  // ---- the vocabulary every theme owes the source: one title per declared rule, keyed by id.
+  const wanted = new Set(canon.rules.filter((r) => r.kind === 'DOCTRINE').map((r) => titleKey(r.kind, r.id)));
+  const lexWant = canon.rules.filter((r) => r.kind === 'LAW').map((r) => titleKey(r.kind, r.id));
   // `_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')];
@@ -532,13 +564,13 @@ export function constitutionProblems() {
     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 `
+        problems.push(`[authoring] ${name} has no {${key}} — a doctrine rule declares 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 `
+        problems.push(`[authoring] ${name} defines {${key}}, which no doctrine rule declares — a `
           + 'dead voice key ships a title for a rule that does not exist');
       }
     }
@@ -549,8 +581,8 @@ export function constitutionProblems() {
     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}} — no law heading carries this `
-        + 'numeral and nothing renders this key, so it is a title for a rule that no longer exists');
+      problems.push(`[authoring] ${name} still defines {${k}} — no law declares this id 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 invariants would `
@@ -670,9 +702,10 @@ export function countTableProblems() {
     problems.push(`[authoring] SKILL_CLASS lists '${stale}' but no skills/${stale}.md exists`);
   }
 
-  const lawsMd = path.join(SRC, 'laws', 'universal.md');
-  const lawNums = isFile(lawsMd)
-    ? [...readText(lawsMd).matchAll(LAW_HEADING_RE)].map((m) => m[1]) : [];
+  // The numerals the laws RENDER with — positional, off the canon — because LAW_CLASS and the
+  // console's LAW_META are keyed the way the rendered catalogue numbers them.
+  const lawRules = ruleCanon(SRC).rules.filter((r) => r.kind === 'LAW');
+  const lawNums = lawRules.map((r) => r.label);
   for (const num of lawNums) {
     if (!has(LAW_CLASS, num)) {
       problems.push(`[authoring] laws/universal.md rule ${num} has no class in LAW_CLASS`);
@@ -686,7 +719,7 @@ export function countTableProblems() {
         + `class ${formatRepr(LAW_CLASSES)}`);
     }
   }
-  problems.push(...lawMetaProblems(lawNums, LAW_CLASS, LAW_CLASSES));
+  problems.push(...lawMetaProblems(lawNums, LAW_CLASS, LAW_CLASSES, lawRules.map((r) => r.id)));
 
   // WHAT SHIPS, NOT WHAT IS FLAT. A folder skill (`src/skills/<name>/SKILL.md`, vendored with
   // its scripts or references) ships exactly like a flat one, so the badge, the README list and

package/js/inspect/inventory.mjs

@@ -70,8 +70,7 @@ const PACK_LEAD_RE = /^\*\*(.+?)\*\*\s+[—-]\s+(.+?)\s*$/;
 /** `_harness_tui.LAW_CLASS` — each rule's class, keyed by Roman numeral. */
 export const LAW_CLASS = {
   I: 'security', II: 'process', III: 'verify', IV: 'security', V: 'verify',
-  VI: 'security', VII: 'security', VIII: 'craft', IX: 'security', X: 'verify',
-  XI: 'verify',
+  VI: 'security', VII: 'security', VIII: 'craft', IX: 'verify',
 };
 
 /** `_harness_tui.ENTITY_STATUSES` — the lifecycle statuses `registry.json` may carry. */

package/js/ui/tui.mjs

@@ -347,7 +347,7 @@ export function themePreview(key) {
   if (data.TAGLINE) lines.push(['dim', data.TAGLINE], ['', '']);
   if (data.LOADED_SIGIL) lines.push(['ok', data.LOADED_SIGIL], ['', '']);
   if (data.VOICE) lines.push(['', `Voice — ${data.VOICE}`], ['', '']);
-  if (data.LEX_I) lines.push(['', `e.g.  Rule I — ${data.LEX_I}`]);
+  if (data.LEX_SEALED_SECRETS) lines.push(['', `e.g.  Rule I — ${data.LEX_SEALED_SECRETS}`]);
   if (data.BENEDICTION) lines.push(['', ''], ['dim', data.BENEDICTION]);
   return lines;
 }

package/js/web/api.mjs

@@ -35,6 +35,7 @@ import { readText, withDiscardableStderr, isDir, isFile } from '../lib/fs.mjs';
 import { comparePaths, normcase, within } from '../lib/paths.mjs';
 import { stripWhitespace, percentDecode } from '../lib/text.mjs';
 import { readJsonc } from '../hosts/settings.mjs';
+import { PROFILE_STUB } from '../build/stubs.mjs';
 import { apiActivity, apiActivityDetail } from './activity.mjs';
 import { apiMcp, apiRules } from './actions.mjs';
 
@@ -755,7 +756,11 @@ function apiProfile(state) {
   const p = profilePath(state);
   if (!isFile(p)) return { exists: false, path: p, text: '', fingerprint: '' };
   const text = readMaybe(p) ?? '';
-  return { exists: true, path: p, text, fingerprint: fingerprint(text) };
+  // `seeded`: the file is still the template the build wrote once and never touched since.
+  // `readMaybe` normalises line endings, so a CRLF copy (the emit writes the platform's, and
+  // an editor may re-save either way) still compares equal to the LF literal.
+  const seeded = text === PROFILE_STUB;
+  return { exists: true, path: p, text, fingerprint: fingerprint(text), seeded };
 }
 
 /** The dashboard aggregate. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "Every field here is argued and gated in tests/unit/package_manifest.test.mjs. `files`, `bin` and `engines` each have a test that fails when reality drifts from this file; `version` mirrors harness.config.json and is gated too. Read that docblock before editing this one.",
   "name": "geneseed",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "description": "A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.",
   "keywords": [
     "ai",

package/registry.json

@@ -463,6 +463,13 @@
       "added": "2026-07-29",
       "last_verified": ""
     },
+    "skills/explain-changes": {
+      "status": "experimental",
+      "version": "1.0.0",
+      "owner": "Guillaume Lemer",
+      "added": "2026-09-30",
+      "last_verified": ""
+    },
     "skills/wayfinder": {
       "status": "approved",
       "version": "1.0.0",

package/src/AGENT.md.tmpl

@@ -168,13 +168,13 @@ contract you do not already know.
 {{AGENT}} spec ends with a **self-improvement loop**: when a report carries a
 `spec-feedback:` line, weigh it — fold a real flaw back into that {{AGENT}}'s
 file (with the user's assent); {{MEMORY}} gets a record only when it clears
-{{DOCTRINE}} process 1's bar.
+{{DOCTRINE:persist-insight}}'s bar.
 
 **Dispatching a multi-part goal.** When a goal spans several capabilities,
 decompose it into independent subtasks, route each to the single owning {{AGENT}}
 above, and converge the results yourself. Every handoff carries an **envelope** —
 the subtask goal, the inputs the {{AGENT}} needs, and its output contract — and the
-constraints travel with it: dispatched {{AGENTS}} never commit or push ({{DOCTRINE}} process 5
+constraints travel with it: dispatched {{AGENTS}} never commit or push ({{DOCTRINE:consent-before-push}}
 stays with you), and an unfulfilled contract returns as a stated gap, never invented
 content. Where the host exposes a `workflow` tool, prefer the saved `dispatch`
 workflow ([workflow {{SKILL}}]({{DIR_SKILLS}}/workflow.md)); where it does not, run
@@ -256,9 +256,9 @@ demand.
 When a task repeats and no {{SKILL}} covers it, forge one through the
 [skill-forge]({{DIR_SKILLS}}/skill-forge.md) {{SKILL}}: copy
 [`{{DIR_SKILLS}}/_template.md`]({{DIR_SKILLS}}/_template.md), keep it to one coherent
-domain ({{DOCTRINE}} craft 1), and list it wherever this file carries a catalogue. Every {{SKILL}} ends with a
+domain ({{DOCTRINE:automate-repetition}}), and list it wherever this file carries a catalogue. Every {{SKILL}} ends with a
 **self-improvement loop** — honour it: fold what a run teaches back into the
-file, or into {{MEMORY}} ({{DOCTRINE}} process 1).
+file, or into {{MEMORY}} ({{DOCTRINE:persist-insight}}).
 
 **Folder {{SKILLS}}.** Some {{SKILLS}} ship as self-contained folders under
 `{{DIR_SKILLS}}/`, each with its own format and provenance (`VENDOR.md`) —
@@ -270,6 +270,8 @@ its domain comes up:
   non-obvious connections between notes via parallel synthesis + critique.
 - [token-report]({{DIR_SKILLS}}/token-report/SKILL.md) — session token usage breakdown
   tables: context baseline, growth, per-tool attribution.
+- [explain-changes]({{DIR_SKILLS}}/explain-changes/SKILL.md) — offline HTML walkthrough
+  of a diff: intent, risks, side-by-side git diff.
 
 ---
 
@@ -283,22 +285,24 @@ local `MEMORY.md`. Read that index at the start of a session; write a new memory
 whenever the conversation yields a durable fact, a correction, or a decision worth
 keeping — through the [rule]({{DIR_SKILLS}}/rule.md) {{SKILL}}, which settles with
 the user whether it is a memory or a standing rule before either is written
-({{DOCTRINE}} process 1). The `{{DIR_MEMORY}}/` directory is **personal and git-ignored** — it is
+({{DOCTRINE:persist-insight}}). The `{{DIR_MEMORY}}/` directory is **personal and git-ignored** — it is
 never committed or shared; to share knowledge, put it in code, docs, or the
 project's `user-rules.md` (§1). When the same feedback lesson keeps recurring,
 propose promoting it into a standing rule — the [rule]({{DIR_SKILLS}}/rule.md)
 {{SKILL}} carries the procedure. A memory that records a decision or stance may
 carry an optional `force` (constraint · choice · conviction · tempered): when new
 evidence contradicts one, revise it rather than ignore it, and never overturn a
-`constraint` yourself — surface it to the user. Full
-convention: [`{{DIR_MEMORY}}/README.md`]({{DIR_MEMORY}}/README.md).
+`constraint` yourself — surface it to the user. In anything that outlives
+the session — memory, notebook, notes, commits, docs — cite a rule by its principle
+("Verify Before Asserting"), never its number: numbers are positional. Full convention: [`{{DIR_MEMORY}}/README.md`]({{DIR_MEMORY}}/README.md).
 <!-- LEAN:else -->
 Durable facts live in [`{{DIR_MEMORY}}/`]({{DIR_MEMORY}}/), one per file, indexed by
 `MEMORY.md` — **read that index at the start of a session**. Write one through the
 [rule]({{DIR_SKILLS}}/rule.md) {{SKILL}}, which settles with the user whether a
-lesson is a memory or a standing rule ({{DOCTRINE}} process 1). The directory is
+lesson is a memory or a standing rule ({{DOCTRINE:persist-insight}}). The directory is
 **personal and git-ignored**; shared knowledge goes in code, docs, or `user-rules.md`
-(§1). Convention, including the optional `force` field:
+(§1). In anything that outlives the session, cite a rule by its principle ("Verify Before
+Asserting"), never its number — numbers change. Convention, incl. `force`:
 [`{{DIR_MEMORY}}/README.md`]({{DIR_MEMORY}}/README.md).
 <!-- LEAN:end -->
 
@@ -325,7 +329,7 @@ tree. Read `NOTEBOOK.md` at the start of a session to recall what
 you keep here, and keep the space referable across sessions — the seeded index
 is one way; replace it with whatever scheme serves you better. When a note
 hardens into a durable fact worth recalling verbatim, propose it for {{MEMORY}}
-through the rule {{SKILL}} (§5, {{DOCTRINE}} process 1). Keep the two stores distinct by *role*, not just by
+through the rule {{SKILL}} (§5, {{DOCTRINE:persist-insight}}). Keep the two stores distinct by *role*, not just by
 format: {{MEMORY}} holds durable insight for future sessions, the {{NOTEBOOK}}
 holds your working artifacts. The one fixed law: `{{DIR_NOTEBOOK}}/` is **personal and
 git-ignored** — never committed or shared, and the `.gitignore` that guarantees
@@ -359,9 +363,9 @@ the rule {{SKILL}} (§5) so it outlives the session.
 
 Because the folder is shared, two cautions hold:
 - **You do not own it.** Files you did not create are not yours to move, rename,
-  or delete unless the task explicitly requires it ({{LAW}} IV).
+  or delete unless the task explicitly requires it ({{LAW:deletion-is-deliberate}}).
 - **Do not assume.** Before treating a file as harness scaffolding or as
-  disposable, verify what it actually is ({{LAW}} III).
+  disposable, verify what it actually is ({{LAW:verify-before-asserting}}).
 
 And it receives only the **deliverables** of the task. Your own working files —
 scratch scripts, analysis dumps, drafts, experiments — are made in the
@@ -371,7 +375,7 @@ scratch scripts, analysis dumps, drafts, experiments — are made in the
 prior work — is knowledge to read and learn from, not scaffolding to reorganise;
 propose a durable fact from it for {{MEMORY}} through the rule {{SKILL}} (§5). You do not own the folder: files
 you did not create are not yours to move or delete unless the task requires it
-({{LAW}} IV), and a file is verified before it is treated as disposable ({{LAW}} III).
+({{LAW:deletion-is-deliberate}}), and a file is verified before it is treated as disposable ({{LAW:verify-before-asserting}}).
 It receives only the task's deliverables; your working files go in the {{NOTEBOOK}}
 (§6).
 <!-- LEAN:end -->
@@ -437,7 +441,7 @@ is loaded for you.) Before your first reply, act on each entry by its `load` mod
   house conventions, branch/commit policy, the Definition of Done. That content is
   **project law for this repo, as binding as anything in this file**.
 - **`"lazy"`** — read it **only when the task in hand needs it**, never up front
-  ({{DOCTRINE}} process 3). Large or occasional docs: architecture notes, API references.
+  ({{DOCTRINE:context-economy}}). Large or occasional docs: architecture notes, API references.
 
 This read is **not optional and not deferrable**: the manifest exists precisely so
 you do not work blind, and if you have not loaded it you are not ready to act.
@@ -449,7 +453,7 @@ comment carries its schema and setup notes.
 deferrable.** It sits beside this AGENT.md and is how the project hands you its own
 knowledge (on OpenCode it is loaded for you). `"eager"` entries are read now and are
 **project law for this repo, as binding as this file**; `"lazy"` entries only when
-the task needs them ({{DOCTRINE}} process 3). Schema and setup notes are in the file's
+the task needs them ({{DOCTRINE:context-economy}}). Schema and setup notes are in the file's
 own comment.
 <!-- LEAN:end -->
 

package/src/agents/_template.md

@@ -1,7 +1,7 @@
 <!--
   Authoring a new agent:
   1. Reuse first — if an existing {{AGENT}}'s capability already covers the need,
-     extend it instead of adding a file ({{DOCTRINE}} craft 1 applies to specialists too).
+     extend it instead of adding a file ({{DOCTRINE:automate-repetition}} applies to specialists too).
   2. Copy this file to agents/<name>.md and fill in every section. In an installed
      harness the purpose line is plain prose; in the Geneseed source repo it is the
      DESC_<NAME> token with the prose defined per theme.
@@ -42,7 +42,7 @@
 
 ## Procedure
 0. If `{{DIR_MEMORY}}/agents/<your-name>.md` exists in the harness, read it first —
-   it holds your durable lessons from prior dispatches ({{DOCTRINE}} process 1).
+   it holds your durable lessons from prior dispatches ({{DOCTRINE:persist-insight}}).
 1. Step-by-step method this {{AGENT}} follows.
 
 ## Output contract
@@ -73,4 +73,4 @@ that proved wrong, a step you could not execute — end your report with one lin
 `spec-feedback: <what failed — the one-line fix>`. Omit it when there is no
 friction. The caller weighs the feedback, folds a real flaw back into this file
 with the user's assent, and records it to {{MEMORY}} only if it clears
-{{DOCTRINE}} process 1's bar — most reports carry no feedback at all.
+{{DOCTRINE:persist-insight}}'s bar — most reports carry no feedback at all.