geneseed 2.1.0 → 3.1.0

package/js/installs.mjs

@@ -35,7 +35,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 
-import { CONFIG, THEMES, discoverNames } from './checkout.mjs';
+import { CONFIG, PACK_ORDER, THEMES, discoverNames } from './checkout.mjs';
 import { GLOBAL_MANIFEST, HOSTS, pyResolve } from './hosts.mjs';
 import { registryRoots } from './registry.mjs';
 import { comparePaths, pyPrintErr, pyRepr, readText } from './lib/fs.mjs';
@@ -91,6 +91,17 @@ export const defaultTheme = () => configuredDefault('theme', 'neutral');
 export const defaultPosture = () => configuredDefault('posture', 'peer');
 export const defaultMode = () => configuredDefault('mode', 'direct');
 
+// There is deliberately no `defaultDoctrines()` beside the three above, and its absence is
+// the invariant. `theme`, `posture` and `mode` may fall back to `harness.config.json` when an
+// install does not say, because the worst a wrong answer does there is cosmetic. The pack
+// selection is not like them: it decides whether the commit/push consent gate is wired, so
+// resolving "this install does not say" out of a MACHINE-WIDE config file narrows every
+// pre-2.3 install on its first upgrade — `{"doctrines":["craft"]}` and the gate is gone from
+// carriers that never asked. Unknown resolves to ALL packs; see `doctrinesForBuild` below.
+// The config value keeps exactly one legitimate reader: `configDefaults()` in
+// `bin/geneseed.mjs`, which answers `geneseed build` — the case where there is no install to
+// ask in the first place.
+
 // ---- theme, footprint, posture, mode, read back off a deployed tree -----------------------
 
 /**
@@ -159,7 +170,8 @@ const FOOTPRINTS = ['lean', 'full'];
  *
  * `status` reads no footprint row at all; the WARN is why this function is ported there, and
  * `diff` and `rebuild-all` read the RETURN value as well. An unrecognised marker is reported
- * rather than swallowed (Rule VII), and a compared stderr is what makes that observable —
+ * rather than swallowed (Rule V, *Surface Failures* — VII before the three-tier renumber, and
+ * VII now names *Least Privilege*), and a compared stderr is what makes that observable —
  * `status/a-bogus-footprint-marker-warns-on-stderr` is the cell.
  */
 export function footprintOfDir(d) {
@@ -208,6 +220,76 @@ function leadOfDir(d, names) {
 export const postureOfDir = (d) => leadOfDir(d, discoverNames('postures', 'peer'));
 export const modeOfDir = (d) => leadOfDir(d, discoverNames('modes', 'direct'));
 
+/** The `Active packs:` marker line the template emits, in one of the five carriers. */
+const ACTIVE_PACKS_RE = /^Active packs:[ \t]*(.+?)[ \t]*$/m;
+
+/**
+ * The doctrine packs a DEPLOYED install carries — the third register read back off disk,
+ * beside `postureOfDir` and `modeOfDir`, and the first that is a SET.
+ *
+ * MARKERED IN PROSE, like posture and mode and unlike theme/footprint: `src/AGENT.md.tmpl`
+ * writes a literal `Active packs: <list>` line under the doctrines section, so no extra dotfile
+ * has to survive a copy. The label is NOT token-substituted, so a themed bundle still answers.
+ *
+ * ⚠ THREE RETURN STATES, AND THE NULL IS THE SAFETY ONE.
+ *   - `null` — no marker in any carrier. That is a pre-migration install, or a carrier that
+ *     never had one, and it means "unknown", NOT "no packs". Every consumer must read it as
+ *     the process pack being ACTIVE, so the commit/push consent gate stays installed. Write
+ *     `doctrinesOfDir(root)` into an explicit `=== null` / `??` test — never
+ *     `doctrinesOfDir(root)?.includes('process')`, which is falsy on `null` and would strip
+ *     the gate from every existing install on its next upgrade.
+ *   - `[]` — the marker is present and reads `none`. A deliberate empty selection (invariants
+ *     and ontology only) and a real configuration: the gate comes OFF.
+ *   - a list — the packs named, re-ordered through `PACK_ORDER`, because this value is
+ *     compared against a marker the build writes in that order.
+ *
+ * A marker line this checkout cannot read WHOLE falls back to `null` rather than to whatever
+ * part of it did parse, for the same reason: a corrupt line is unknown, and unknown fails
+ * closed. ⚠ "Whole" is the strict word and it is what the first cut of this got wrong. The
+ * regex is single-line, so a marker a wrapper had folded — `Active packs: craft, rigor,\nops,
+ * process` — matched its first half, every name in that half was known, and the function
+ * answered the NARROWED set `['craft','rigor']` with no complaint. That is fail-OPEN against
+ * this docblock's own promise: the process pack disappears from an install that has it, and
+ * the gate goes with it. So every comma-separated field must be non-empty AND a pack this
+ * checkout ships; one that is not condemns the whole line to `null`. A trailing comma is
+ * exactly the empty field a fold leaves behind, which is what makes this catch it.
+ */
+export function doctrinesOfDir(d) {
+  for (const carrier of CARRIERS) {
+    const text = readMaybe(path.join(d, carrier));
+    if (text === null) continue;
+    const m = ACTIVE_PACKS_RE.exec(text);
+    if (!m) continue;
+    if (m[1] === 'none') return [];
+    const named = m[1].split(',').map((s) => s.trim());
+    if (!named.every((n) => PACK_ORDER.includes(n))) return null;
+    return PACK_ORDER.filter((p) => named.includes(p));
+  }
+  return null;
+}
+
+/**
+ * `doctrinesOfDir` with the `null` RESOLVED — the one spelling every build-side consumer uses.
+ *
+ * ⚠ UNKNOWN RESOLVES TO ALL PACKS, NEVER TO A CONFIG VALUE. `doctrinesOfDir`'s docblock puts
+ * the rule on the reader; this function is what makes it true of the readers, because the
+ * previous shape (`doctrinesOfDir(root) ?? defaultDoctrines()`) left every consumer free to
+ * pick its own fallback and all five of them picked `harness.config.json`. With
+ * `{"doctrines":["craft"]}` in that file, an `upgrade`/`rebuild-all`/`migrate` re-emitted every
+ * pre-2.3 install at ONE pack and took the commit/push consent gate off installs whose owners
+ * had never been asked — the exact outcome the fail-closed reading exists to prevent, and it
+ * got WIDER when the reader was hardened, because more inputs now answer `null`.
+ *
+ * A config value is a legitimate default only where there is NO INSTALL TO ASK: a fresh
+ * `geneseed build`, which `configDefaults()` in `bin/geneseed.mjs` answers. Anything holding a
+ * directory has an install to ask, so it calls this and never the config.
+ *
+ * `[]` still passes through untouched — a marker that reads `none` is an answer, not a silence.
+ */
+export function doctrinesForBuild(d) {
+  return doctrinesOfDir(d) ?? [...PACK_ORDER];
+}
+
 // ---- what host a deployed dir belongs to (`_harness_mcp`) ---------------------------------
 
 /** `_harness_mcp._claude_read_manifest`. */
@@ -333,7 +415,7 @@ export function installTargets() {
 // ---- what this machine installed (`_harness_setup._installed_defaults`) --------------------
 
 /**
- * `_harness_setup._installed_defaults` — all five keys, as of P5i.
+ * `_harness_setup._installed_defaults` — all six keys.
  *
  * It carried only `theme` and `emit` for four phases because those are the two `status`
  * prints and the two `doctor` reads, and the port's keep-vs-delete rule is "part of an
@@ -342,9 +424,20 @@ export function installTargets() {
  * `inst.posture` / `inst.mode` / `inst.footprint`, so a three-key answer would have silently
  * pre-selected the CONFIGURED default over the DEPLOYED one on three of its five questions.
  * Nothing in `status` or `doctor` moves: both read the keys they already read.
+ *
+ * `doctrines` joined last, for the same reason and one phase later: the wizard's pack question
+ * shipped before the marker reader existed, so it defaulted to `all` for everyone and re-asked
+ * an installer who had already narrowed their selection. ⚠ THIS KEY IS THE ONE WITH THREE
+ * STATES, and the `=== null` tests below preserve all three: `null` is "no carrier on this
+ * machine said", `[]` is a carrier that said `none`, a list is a carrier that named packs.
+ * Only a WIZARD may read it — it is a pre-selection shown to a human who then answers. No
+ * build-side consumer resolves a pack set from here; that is `doctrinesForBuild(dir)`, which
+ * asks one named install rather than whichever candidate this walk happens to reach first.
  */
 export function installedDefaults() {
-  const found = { theme: null, posture: null, mode: null, emit: null, footprint: null };
+  const found = {
+    theme: null, posture: null, mode: null, emit: null, footprint: null, doctrines: null,
+  };
   const candidates = [];
   for (const { host, configDir } of HOSTS) {
     try { candidates.push([configDir(), `${host}-global`]); } catch { /* as the Python */ }
@@ -373,6 +466,10 @@ export function installedDefaults() {
     if (found.footprint === null && isFile(path.join(base, '.geneseed-footprint'))) {
       found.footprint = footprintOfDir(base);
     }
+    // `doctrinesOfDir` and not `doctrinesForBuild`: the resolved form answers `[...PACK_ORDER]`
+    // for a carrier with no marker, which would end this walk at the FIRST candidate and hide
+    // a later carrier that does say. The null has to survive to the caller here.
+    if (found.doctrines === null) found.doctrines = doctrinesOfDir(base);
   }
   return found;
 }

package/js/inventory.mjs

@@ -21,7 +21,7 @@
  */
 import path from 'node:path';
 
-import { ROOT, SRC, makeCfg } from './checkout.mjs';
+import { ROOT, SRC, makeCfg, PACK_ORDER } from './checkout.mjs';
 import { firstBlockquote } from './native.mjs';
 import { renderAll } from './render.mjs';
 import { pyResolve } from './hosts.mjs';
@@ -29,30 +29,59 @@ import { parseJson, readText } from './lib/fs.mjs';
 
 /**
  * `_harness_tui.LAW_HEADING_RE` — a heading in the RENDERED laws file, e.g.
- * `### Rule XVIII — Load the Project Context`.
+ * `### Rule IV — Deletion Is Deliberate`.
  *
  * Not `js/doctor.mjs`'s `LAW_HEADING_RE`, which matches the `{{LAW}}` token in the
  * unrendered source. Two patterns, two inputs, two names in Python as well.
  */
 export const LAW_HEADING_RE = /^###\s+\S+\s+([IVXLCDM]+)\s+[—-]\s+(.+?)\s*$/;
 
+/**
+ * A heading in a RENDERED doctrine pack, e.g. `### Doctrine craft 1 — Automate Repetition`.
+ *
+ * THE TIER NOUN IS THEMED AND THE ADDRESS IS NOT, exactly as the invariants work: `{{LAW}}`
+ * plus a Roman numeral there, `{{DOCTRINE}}` plus `<pack> <n>` here. So `\S+` for the noun —
+ * ⚠ which is why a theme's `DOCTRINE` value must be ONE WORD, and why `doctor` asserts it in
+ * all fourteen. A two-word noun does not error; it silently stops matching, and a pack quietly
+ * parses to zero rules.
+ *
+ * It cannot collide with `LAW_HEADING_RE` in either direction and the reason is case:
+ * `([a-z]+)` refuses `Rule I`'s uppercase numeral, and `([IVXLCDM]+)` refuses a lowercase pack
+ * id. Measured across all fourteen themes — zero cross-matches either way.
+ */
+export const DOCTRINE_HEADING_RE = /^###\s+\S+\s+([a-z]+)\s+(\d+)\s+[—-]\s+(.+?)\s*$/;
+
+/**
+ * A section heading in the RENDERED ontology, e.g. `#### Telos`.
+ *
+ * FOUR HASHES, and that is the whole reason the ontology can share `universal.md`'s basename
+ * with the laws file without either parser seeing the other's headings. The section names come
+ * from `STRUCTURE` rather than from a theme, so the id below is stable across all fourteen
+ * voices and is safe to put in a deep link.
+ */
+export const ONTOLOGY_HEADING_RE = /^####\s+(.+?)\s*$/;
+
+/** The lead line of a pack file — `**Craft** — how code is written.` */
+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: 'craft',
-  VI: 'context', VII: 'verify', VIII: 'comms', IX: 'comms', X: 'comms',
-  XI: 'craft', XII: 'craft', XIII: 'craft', XIV: 'process', XV: 'process',
-  XVI: 'context', XVII: 'context', XVIII: 'context', XIX: 'context', XX: 'security',
-  XXI: 'process', XXII: 'security', XXIII: 'security', XXIV: 'craft', XXV: 'craft',
-  XXVI: 'craft', XXVII: 'verify', XXVIII: 'process', XXIX: 'comms', XXX: 'comms',
-  XXXI: 'comms', XXXII: 'craft', XXXIII: 'craft', XXXIV: 'verify', XXXV: 'verify',
-  XXXVI: 'security', XXXVII: 'process', XXXVIII: 'verify', XXXIX: 'comms',
-  XL: 'comms',
+  I: 'security', II: 'process', III: 'verify', IV: 'security', V: 'verify',
+  VI: 'security', VII: 'security', VIII: 'craft', IX: 'security',
 };
 
 /** `_harness_tui.ENTITY_STATUSES` — the lifecycle statuses `registry.json` may carry. */
 export const ENTITY_STATUSES = ['experimental', 'approved', 'deprecated'];
 
-/** `_harness_tui.LAW_CLASSES` — the six governance classes a law may carry. */
+/**
+ * `_harness_tui.LAW_CLASSES` — the six governance classes a law may carry.
+ *
+ * ⚠ SIX, THOUGH ONLY FOUR ARE IN USE. When the corpus became nine invariants, `context` and
+ * `comms` stopped having a member — that material moved to the ontology and the doctrine packs,
+ * neither of which is classed here. The list stays six because it is the VOCABULARY, not a
+ * census: `doctor` quotes it verbatim in the message a bad class earns, and two recorded cells
+ * in `tests/helpers/matrix/cli.*.json` hold that message byte for byte.
+ */
 export const LAW_CLASSES = ['security', 'process', 'verify', 'craft', 'context', 'comms'];
 
 /** `_harness_tui.SKILL_CLASS` — each skill's category, keyed by file stem. */
@@ -106,6 +135,68 @@ export function parseLaws(text) {
   return laws;
 }
 
+/**
+ * One rendered doctrine pack file split into `{pack, n, title, klass, body}` rows.
+ *
+ * Same accumulator as `parseLaws`, and deliberately so: text before the first heading — the
+ * pack's own lead line — is dropped on the floor because `cur` is still null, and each body is
+ * trimmed at its ends only.
+ *
+ * `klass` IS THE PACK ID, not one of `LAW_CLASSES`. A doctrine rule is grouped by the pack it
+ * belongs to and there is no second taxonomy over it; the six-class chip is the invariants'.
+ * The collision with the class names `craft` and `process` is real and harmless — the two
+ * lists are separate end to end and nothing ever unions them.
+ *
+ * `pack` is read from the HEADING and not from the filename, so a rule filed under the wrong
+ * pack is visible rather than silently renamed by its container. `doctor` is what compares the
+ * two; this function just reports what the text says.
+ */
+export function parseDoctrines(text) {
+  const rules = [];
+  let cur = null;
+  for (const line of text.split('\n')) {
+    const m = DOCTRINE_HEADING_RE.exec(line);
+    if (m) {
+      if (cur) rules.push(cur);
+      cur = { pack: m[1], n: Number(m[2]), title: m[3], klass: m[1], body: '' };
+    } else if (cur !== null) {
+      cur.body += `${line}\n`;
+    }
+  }
+  if (cur) rules.push(cur);
+  for (const rule of rules) rule.body = rule.body.trim();
+  return rules;
+}
+
+/**
+ * The rendered ontology split into `{id, title, body}` sections.
+ *
+ * `id` is the slugified title, and it is an ADDRESS: `#/item/law/ont:telos` is how the console
+ * deep-links a section, so it has to survive a theme change. It does, because the four titles
+ * come from `STRUCTURE` in `js/render.mjs` and not from any theme file — the same reason a
+ * citation can spell itself `({{ONTOLOGY}}: {{ONT_TELOS}})` with a token on both sides.
+ *
+ * The preamble above the first `####` is dropped, as in the two parsers above. It is the
+ * paragraph that states the tier order, and it renders into AGENT.md whole — the catalogue
+ * lists sections, and the preamble is not one.
+ */
+export function parseOntology(text) {
+  const sections = [];
+  let cur = null;
+  for (const line of text.split('\n')) {
+    const m = ONTOLOGY_HEADING_RE.exec(line);
+    if (m) {
+      if (cur) sections.push(cur);
+      cur = { id: m[1].toLowerCase().replace(/\s+/g, '-'), title: m[1], body: '' };
+    } else if (cur !== null) {
+      cur.body += `${line}\n`;
+    }
+  }
+  if (cur) sections.push(cur);
+  for (const s of sections) s.body = s.body.trim();
+  return sections;
+}
+
 /**
  * `_harness_tui.load_registry` — the `entities` map from `registry.json`, or `{}`.
  *
@@ -144,33 +235,71 @@ export function entityStatus(registry, key) {
 }
 
 /**
- * `_harness_tui._tui_inventory` — render-accurate inventory: every agent and skill with
- * its one-line purpose, full rendered spec, source path and lifecycle badge, and every law
- * with its title, body and governance class.
+ * `_harness_tui._tui_inventory` — render-accurate inventory of all three constitutional tiers,
+ * plus every agent and skill with its one-line purpose, rendered spec, source and badge.
+ *
+ * THE WHOLE CATALOGUE, NOT THE BUILT SUBSET. All four pack files ship in every bundle
+ * (`OWNED_SRC_DIRS`), which is what lets a cross-pack citation resolve when its pack is not
+ * built into AGENT.md — and it is also what lets the console show an inactive pack greyed out
+ * with the command that would enable it. So the packs are always all parsed; `doctrines` only
+ * decides which of them carry `active: true`. Passing `null` — the default, and what `catalog`,
+ * `status` and the graph do — means "no install to ask", and every pack reads active, matching
+ * `makeCfg()`'s own default and `doctrinesForBuild`'s resolution of unknown.
+ *
+ * `laws` KEEPS ITS NAME and means the invariants. Renaming it to `invariants` would churn
+ * `status`, `catalog`, `tui`, the web API, its `SECTIONS` id, three test fixtures and two
+ * recorded corpora to say the same thing in a different word.
  */
-export function tuiInventory(themeName) {
+export function tuiInventory(themeName, doctrines = null) {
   const { items } = renderAll(makeCfg(), themeName);
   const registry = loadRegistry();
   const agents = [];
   const skills = [];
   let laws = [];
+  let ontology = [];
+  const packs = new Map();
   for (const { text, src } of items) {
     if (text === null) continue;
     const parts = path.relative(SRC, src).split(path.sep);
-    if (parts.length === 2 && parts[1].endsWith('.md') && !parts[1].startsWith('_')) {
-      const name = parts[1].slice(0, -3);
+    const two = parts.length === 2 && parts[1].endsWith('.md') && !parts[1].startsWith('_');
+    const name = two ? parts[1].slice(0, -3) : null;
+    if (two && (parts[0] === 'agents' || parts[0] === 'skills')) {
       const entry = { name, desc: firstBlockquote(text), body: text,
         source: pyResolve(src), status: entityStatus(registry, `${parts[0]}/${name}`) };
       if (parts[0] === 'agents') agents.push(entry);
-      else if (parts[0] === 'skills') {
+      else {
         entry.klass = has(SKILL_CLASS, name) ? SKILL_CLASS[name] : 'build';
         skills.push(entry);
       }
     }
-    if (parts[parts.length - 1] === 'universal.md') laws = parseLaws(text);
+    // Every `.md` in the dir is read; `PACK_ORDER` below decides which of them is a pack. The
+    // dir also holds a `README.md`, which passes the `_`-scaffold filter, and a second
+    // membership test here would be a second owner of the same rule — one that has to agree
+    // with the one that actually publishes the list.
+    if (two && parts[0] === 'doctrines') {
+      const lead = text.split('\n').map((l) => PACK_LEAD_RE.exec(l)).find(Boolean);
+      packs.set(name, { pack: name, title: lead ? lead[1] : name, desc: lead ? lead[2] : '',
+        source: pyResolve(src), rules: parseDoctrines(text) });
+    }
+    // Scoped to the laws dir, not matched on the basename: `src/ontology/universal.md`
+    // shares the name, sorts after `laws/`, and would clobber the parse with `[]` —
+    // `LAW_HEADING_RE` wants `###` and the ontology uses `####`. Same spelling as the
+    // already-scoped sites at `js/render.mjs`'s `rel === 'laws/universal.md'`.
+    if (parts.join('/') === 'laws/universal.md') laws = parseLaws(text);
+    if (parts.join('/') === 'ontology/universal.md') ontology = parseOntology(text);
   }
   const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
   agents.sort(byName);
   skills.sort(byName);
-  return { agents, skills, laws, theme: themeName };
+  // ⚠ `PACK_ORDER` IS THE SINGLE OWNER OF THE SET, and of its order. Filtering the order by
+  // what was found — rather than publishing what was found — is what keeps `README.md` and any
+  // other stray `.md` in that directory out of the catalogue, and it is the same membership
+  // rule `js/render.mjs` refuses the build over, so a fifth pack cannot be silently dropped
+  // here either. Order because `sortedSourceFiles` walks alphabetically, which puts `ops`
+  // second: the narrative order is the reading order, and it is what the marker line, the
+  // wizard and the rendered section all use.
+  const on = Array.isArray(doctrines) ? doctrines : PACK_ORDER;
+  const built = PACK_ORDER.filter((p) => packs.has(p))
+    .map((p) => ({ ...packs.get(p), active: on.includes(p) }));
+  return { agents, skills, laws, ontology, doctrines: built, theme: themeName };
 }

package/js/migrate.mjs

@@ -35,8 +35,8 @@ import path from 'node:path';
 import { main as driverMain } from '../bin/geneseed.mjs';
 import { ROOT } from './checkout.mjs';
 import {
-  EMIT_HOST_SCOPE, defaultMode, defaultPosture, defaultTheme, footprintOfDir, installState,
-  installTargets, modeOfDir, postureOfDir, readMaybe, themeOfDir,
+  EMIT_HOST_SCOPE, defaultMode, defaultPosture, defaultTheme, doctrinesForBuild,
+  footprintOfDir, installState, installTargets, modeOfDir, postureOfDir, readMaybe, themeOfDir,
 } from './installs.mjs';
 import { DEFAULT_EMIT, setupBuildArgs } from './generate.mjs';
 import {
@@ -206,7 +206,12 @@ export function cmdMigrate(args = {}) {
     try { rmSync(stash, { recursive: true, force: true }); } catch { /* nothing to undo */ }
   };
 
-  // Step 3 — re-emit, in each install's OWN five values. Same reads as `cmdRebuildAll`.
+  // Step 3 — re-emit, in each install's OWN six values. Same reads as `cmdRebuildAll`, and
+  // the pack selection is the sixth: leaving it out re-emitted a narrowed install at whatever
+  // `harness.config.json` said, which WIDENS a constitution its owner had cut down (and, the
+  // other way, can strip the consent gate). `null` — a pre-marker carrier, which on a MIGRATION
+  // is the common case and not the rare one — resolves to ALL packs through
+  // `doctrinesForBuild`, never to `harness.config.json`, which is what makes it fail-closed.
   for (const r of rows) {
     const marker = r.marker && (EMIT_HOST_SCOPE.get(r.marker) ?? ['', ''])[0] === r.host
       ? r.marker : '';
@@ -214,7 +219,8 @@ export function cmdMigrate(args = {}) {
     const theme = themeOfDir(r.root) || defaultTheme();
     const out = r.scope === 'global' ? null : r.root;
     const argv = setupBuildArgs(theme, emit, out, out, footprintOfDir(r.root),
-      postureOfDir(r.root) || defaultPosture(), modeOfDir(r.root) || defaultMode());
+      postureOfDir(r.root) || defaultPosture(), modeOfDir(r.root) || defaultMode(),
+      doctrinesForBuild(r.root));
     const label = `${r.host}:${r.scope} (${r.root})`;
     pyPrint(`[migrate] re-emitting ${label}: theme=${theme} emit=${emit}\n`);
     let rc = 1;

package/js/render.mjs

@@ -29,13 +29,20 @@
 import { readdirSync, statSync, existsSync } from 'node:fs';
 import path from 'node:path';
 import { readText, parseJson, normcase, comparePaths } from './lib/fs.mjs';
+// `js/checkout.mjs` imports nothing but node builtins, so this direction cannot cycle.
+import { PACK_ORDER } from './checkout.mjs';
 
 /** Document STRUCTURE is theme-INDEPENDENT — mirrors `_build_render.STRUCTURE`. */
 export const STRUCTURE = {
   HARNESS: 'Geneseed', CHARTER: 'Charter', CONTEXT: 'Context',
   SCRIPT: 'Script', SCRIPTS: 'Scripts',
   DIR_LAWS: 'laws', DIR_AGENTS: 'agents', DIR_SKILLS: 'skills', DIR_MEMORY: 'memory',
-  DIR_NOTEBOOK: 'notebook',
+  DIR_NOTEBOOK: 'notebook', DIR_ONTOLOGY: 'ontology', DIR_DOCTRINES: 'doctrines',
+  // Ontology section names. Theme-INDEPENDENT on purpose: a citation reads
+  // `({{ONTOLOGY}}: {{ONT_TELOS}})` — token on both sides, so the heading and every
+  // reference to it move together and a rename can never desync them.
+  ONT_TELOS: 'Telos', ONT_EVIDENCE: 'Evidence', ONT_DECISIONS: 'Decisions',
+  ONT_CONDUCT: 'Conduct',
 };
 
 /**
@@ -46,11 +53,15 @@ export const STRUCTURE = {
 export const SRC_DIR_TOKENS = {
   laws: 'DIR_LAWS', agents: 'DIR_AGENTS', skills: 'DIR_SKILLS',
   memory: 'DIR_MEMORY', notebook: 'DIR_NOTEBOOK',
+  ontology: 'DIR_ONTOLOGY', doctrines: 'DIR_DOCTRINES',
 };
 
 const TEXT_SUFFIXES = new Set(['.md', '.tmpl', '.json', '.txt', '.yml', '.yaml']);
 
-const TOKEN_RE = /\{\{([A-Z_]+)\}\}/g;
+// Digits are legal after the first character: `DOC_<PACK>_<n>` (the doctrine rule titles) are
+// the first token names in the project to carry one, and without `0-9` here `{{DOC_CRAFT_1}}`
+// silently never substitutes. A leading digit stays illegal, so `{{1}}` is still not a token.
+const TOKEN_RE = /\{\{([A-Z_][A-Z0-9_]*)\}\}/g;
 const INCLUDE_RE = /^[ \t]*<!--[ \t]*INCLUDE:[ \t]*(?<path>[^ \t]+)[ \t]*-->[ \t]*$/gm;
 const CATALOG_BLOCK_RE =
   /[ \t]*<!-- CATALOG:begin -->\n(?<table>[\s\S]*?)[ \t]*<!-- CATALOG:else -->\n(?<pointer>[\s\S]*?)[ \t]*<!-- CATALOG:end -->\n/g;
@@ -152,8 +163,18 @@ function splitAtLawHeadings(text) {
   return out;
 }
 
-/** `_build_render._terse_laws`. */
-export function terseLaws(text, theme, lawsPrefix = '') {
+/**
+ * `_terse_laws` minus its pointer paragraph — heading + first sentence, per `### ` block.
+ *
+ * Split out rather than parameterised. The pointer was baked into the function body, and
+ * the doctrines axis needs the same truncation under a DIFFERENT closing paragraph (one
+ * that names the pack catalogue, not `laws/universal.md`, and drops the
+ * secrets/deletion/git-history clause, which is the invariants' domain and not a pack's).
+ * An extraction leaves `terseLaws` byte-identical for the laws path — the recorded lean
+ * AGENT.md does not move — where a fourth parameter would have put a branch inside the one
+ * function every frozen lean render already goes through.
+ */
+function terseBlocks(text) {
   const blocks = splitAtLawHeadings(text);
   const out = [blocks[0].trimEnd()];
   for (const b of blocks.slice(1)) {
@@ -169,6 +190,11 @@ export function terseLaws(text, theme, lawsPrefix = '') {
     const m = /^([\s\S]+?[.!?])(?:\s|$)/.exec(body);
     out.push(`${heading}\n${m ? m[1].trim() : body}`);
   }
+  return out.join('\n\n');
+}
+
+/** `_build_render._terse_laws`. */
+export function terseLaws(text, theme, lawsPrefix = '') {
   const law = theme.LAW ?? 'Law';
   const lawsDir = theme.DIR_LAWS ?? 'laws';
   const pointer =
@@ -176,7 +202,7 @@ export function terseLaws(text, theme, lawsPrefix = '') {
     + `complete, binding text of every ${law} is in \`${lawsPrefix}${lawsDir}/universal.md\`; `
     + `read it whenever a ${law}'s application is unclear, and before any act touching `
     + `secrets, deletion, git history, scope, or untrusted content.`;
-  return out.join('\n\n') + '\n\n' + pointer;
+  return terseBlocks(text) + '\n\n' + pointer;
 }
 
 /** `_build_render.render_file`. */
@@ -213,6 +239,75 @@ function registerBody(cfg, theme, dir, selected, fallback) {
   return '';
 }
 
+/**
+ * The doctrine packs this build actually renders, in `PACK_ORDER` — and the two gates
+ * that stand between `cfg.doctrines` and a silently wrong AGENT.md.
+ *
+ * GATE 1 (stray pack): a `.md` under `src/doctrines/` that `PACK_ORDER` does not name is a
+ * refusal, not a skip. Discovery sorts alphabetically and `PACK_ORDER` does not, so the two
+ * cannot be the same list; without this gate a fifth pack file would render into no install
+ * and no test would say so.
+ *
+ * GATE 2 (missing file): a pack named in `cfg.doctrines` with no file is a refusal too. The
+ * CLI validates `--doctrines` against discovery, but `makeCfg({doctrines})` is a public
+ * entry point and an emit that quietly dropped a pack the user asked for is exactly the
+ * failure the `Active packs:` marker would then attest to.
+ *
+ * Both throw with `exitCode`, the marker `bin/geneseed.mjs`'s `main` turns into a status.
+ */
+function activeDoctrines(cfg) {
+  const dir = path.join(cfg.src, 'doctrines');
+  const onDisk = existsSync(dir)
+    ? readdirSync(dir)
+      .filter((f) => f.endsWith('.md') && path.basename(f, '.md').toLowerCase() !== 'readme')
+      .map((f) => path.basename(f, '.md'))
+    : [];
+  const stray = onDisk.filter((n) => !PACK_ORDER.includes(n));
+  if (stray.length) {
+    const e = new Error(`doctrine pack file(s) ${stray.join(', ')} exist under src/doctrines/ `
+      + 'but are missing from PACK_ORDER (js/checkout.mjs) — add them there, or they render '
+      + 'into no install at all');
+    e.exitCode = 1;
+    throw e;
+  }
+  const wanted = cfg.doctrines ?? PACK_ORDER;
+  for (const name of wanted) {
+    if (!onDisk.includes(name)) {
+      const e = new Error(`doctrine pack '${name}' is selected but src/doctrines/${name}.md `
+        + `does not exist (packs on disk: ${onDisk.join(', ') || 'none'})`);
+      e.exitCode = 1;
+      throw e;
+    }
+  }
+  return PACK_ORDER.filter((p) => wanted.includes(p));
+}
+
+/**
+ * `{{DOCTRINES_BODY}}` — the active packs concatenated, the multi-select answer to
+ * `registerBody`'s single-select one.
+ *
+ * `registerBody` reads ONE file because a posture and a mode are scalars; a doctrine set is
+ * 0-4 files, so this loops instead of wrapping it. Under `lean` each pack gets the same
+ * heading + first-sentence treatment the invariants get, and the whole section — not each
+ * pack — closes with one pointer at the full catalogue, which ships in every bundle whether
+ * or not a pack is active.
+ */
+function doctrinesBody(cfg, theme, active, footprint, lawsPrefix) {
+  if (!active.length) return '';
+  const parts = active.map((name) => {
+    const body = substitute(readText(path.join(cfg.src, 'doctrines', `${name}.md`)), theme).trim();
+    return footprint === 'lean' ? terseBlocks(body) : body;
+  });
+  if (footprint === 'lean') {
+    const doctrine = theme.DOCTRINE ?? 'Doctrine';
+    const dir = theme.DIR_DOCTRINES ?? 'doctrines';
+    parts.push(`> Each ${doctrine} above is given in brief — the rule, not its reasoning. `
+      + `The complete text of every pack, active or not, is in \`${lawsPrefix}${dir}/\`; read `
+      + `the pack file whenever a ${doctrine}'s application is unclear.`);
+  }
+  return parts.join('\n\n');
+}
+
 /**
  * `_build_render.effective_theme`.
  *
@@ -223,10 +318,18 @@ function registerBody(cfg, theme, dir, selected, fallback) {
  * it reaches nothing at all unless it travels. The constant stays as the default for the
  * parity harnesses, which drive this module directly.
  */
-export function effectiveTheme(cfg, themeName) {
+export function effectiveTheme(cfg, themeName, { footprint = 'full', lawsPrefix = '' } = {}) {
   const theme = { ...loadTheme(cfg, themeName), ...(cfg.structure ?? STRUCTURE) };
   theme.POSTURE_BODY = registerBody(cfg, theme, 'postures', cfg.posture ?? 'peer', 'peer');
   theme.MODE_BODY = registerBody(cfg, theme, 'modes', cfg.mode ?? 'direct', 'direct');
+  // The doctrines pair is threaded, not read off `cfg`: `footprint` is a per-RENDER value
+  // (`renderAll`'s option, and the same cfg renders both ways in one process), so parking it
+  // on cfg would make the terse/full choice sticky across calls. An options object rather
+  // than two positional params keeps the existing two-arg call sites — every test, and
+  // `renderAll` — compiling unchanged, and defaults to the full text if a caller forgets.
+  const active = activeDoctrines(cfg);
+  theme.DOCTRINES_BODY = doctrinesBody(cfg, theme, active, footprint, lawsPrefix);
+  theme.DOCTRINES_LIST = active.length ? active.join(', ') : 'none';
   return theme;
 }
 
@@ -271,7 +374,7 @@ export function destRel(rel) {
 export function renderAll(cfg, themeName, {
   footprint = 'full', lawsPrefix = '', nativeCatalog = false,
 } = {}) {
-  const theme = effectiveTheme(cfg, themeName);
+  const theme = effectiveTheme(cfg, themeName, { footprint, lawsPrefix });
   const items = [];
   for (const file of sortedSourceFiles(cfg.src)) {
     const rel = path.relative(cfg.src, file);