geneseed 2.1.0 → 3.1.0

package/bin/geneseed.mjs

@@ -52,7 +52,7 @@ import {
 // P5d moved these out of this file for the reason P5c moved the host resolvers: `harness
 // status` renders to count, so `bin/geneseed-cli.mjs` needs the same checkout paths and the
 // same cfg. golden.py's 259 cells all build one, which is what made the move safe.
-import { ROOT, CONFIG, THEMES, discoverNames, makeCfg } from '../js/checkout.mjs';
+import { ROOT, CONFIG, THEMES, discoverNames, makeCfg, PACK_ORDER } from '../js/checkout.mjs';
 
 // P5f moved these, for the same arithmetic a third time: `harness rebuild-all` reads the
 // registry to find every install it must re-emit, and a CLI verb may not reach into a driver
@@ -122,7 +122,9 @@ export function resolveOut(raw) {
  * byte-for-byte by `tests/golden.py` (:316).
  */
 function configDefaults() {
-  const d = { theme: 'neutral', posture: 'peer', mode: 'direct' };
+  const d = {
+    theme: 'neutral', posture: 'peer', mode: 'direct', doctrines: [...PACK_ORDER],
+  };
   if (!existsSync(CONFIG)) return d;
   try {
     const data = JSON.parse(readFileSync(CONFIG, 'utf8'));
@@ -130,6 +132,20 @@ function configDefaults() {
       if (data.theme !== undefined) d.theme = data.theme;
       if (data.posture !== undefined) d.posture = data.posture;
       if (data.mode !== undefined) d.mode = data.mode;
+      // `doctrines` is the only config key that is a LIST, so it is the only one that can be
+      // the right type and still nonsense. A bad value warns and falls back to all packs
+      // rather than dying: this file is hand-editable, and a typo here must not brick every
+      // rebuild of an install whose AGENT.md is otherwise fine. `[]` is a legitimate value
+      // (no packs) and must survive the check — hence an explicit Array test, not truthiness.
+      if (data.doctrines !== undefined) {
+        const known = discoverNames('doctrines', PACK_ORDER[0]);
+        if (Array.isArray(data.doctrines) && data.doctrines.every((x) => known.includes(x))) {
+          d.doctrines = PACK_ORDER.filter((p) => data.doctrines.includes(p));
+        } else {
+          process.stderr.write(`[geneseed] WARN: ${path.basename(CONFIG)} "doctrines" is not a `
+            + 'list of known pack names — using all packs.\n');
+        }
+      }
     }
   } catch {
     process.stderr.write(`[geneseed] WARN: ${path.basename(CONFIG)} is unreadable — `
@@ -146,6 +162,7 @@ function configDefaults() {
  */
 const VALUED = {
   '--theme': 'theme', '--posture': 'posture', '--mode': 'mode',
+  '--doctrines': 'doctrines',
   '--out': 'out', '--target': 'out', '--emit': 'emit',
   '--footprint': 'footprint', '--root': 'root',
 };
@@ -160,6 +177,13 @@ const FLAGS = {
  * A function and not a constant because two of the four read the checkout: `discoverNames`
  * scans `postures/` and `modes/`, so the answer depends on the source tree this driver is
  * standing in and cannot be frozen at import.
+ *
+ * `--doctrines` is DELIBERATELY not a fifth row. Every consumer of this table treats an
+ * entry as one value drawn from a closed list — `choice` refuses anything else, and
+ * `usage`'s metavar prints the list as the whole legal surface. `--doctrines` takes a comma
+ * LIST plus the sentinel `none`, so a row here would have refused `craft,rigor` outright and
+ * advertised a metavar that lies. It is validated by `parseDoctrines` instead and prints the
+ * plain `DOCTRINES` metavar, exactly as `--theme` (also open-ended) already does.
  */
 function choicesFor() {
   return {
@@ -170,6 +194,33 @@ function choicesFor() {
   };
 }
 
+/**
+ * `--doctrines craft,rigor` / `--doctrines none` -> the cfg's pack array.
+ *
+ * Normalised into `PACK_ORDER` rather than kept in the order typed, which also dedupes: the
+ * rendered `Active packs:` line is a MARKER a later reader parses back out of a deployed
+ * carrier, and a marker whose contents depend on argument order is one that compares unequal
+ * to itself. Validation is against DISCOVERY, not `PACK_ORDER`, so the refusal names the
+ * packs the checkout actually has; a discovered pack missing from `PACK_ORDER` is a
+ * different fault and `js/render.mjs` refuses the whole build for it.
+ */
+function parseDoctrines(value) {
+  const s = value.trim();
+  const known = discoverNames('doctrines', PACK_ORDER[0]);
+  if (s === 'none') return [];
+  const names = s.split(',').map((x) => x.trim()).filter(Boolean);
+  if (!names.length) {
+    die(2, "argument --doctrines: expected a comma-separated list of packs, or 'none'");
+  }
+  for (const n of names) {
+    if (!known.includes(n)) {
+      die(2, `argument --doctrines: invalid choice: '${n}' (choose from `
+        + `${known.map((c) => `'${c}'`).join(', ')}, or 'none')`);
+    }
+  }
+  return PACK_ORDER.filter((p) => names.includes(p));
+}
+
 /**
  * `-h/--help` — the flag argparse handed the reference for free and this hand-rolled parser
  * did not, so the two entry points disagreed: the reference printed usage and exited 0 while
@@ -212,6 +263,7 @@ function usage() {
 function parseArgs(argv, defaults) {
   const args = {
     theme: defaults.theme, posture: defaults.posture, mode: defaults.mode,
+    doctrines: defaults.doctrines,
     out: 'Harness', emit: 'files', footprint: 'lean', root: null,
     syncThemes: false, validateOnly: false, verbose: false,
   };
@@ -241,6 +293,9 @@ function parseArgs(argv, defaults) {
   }
   const choices = choicesFor();
   for (const flag of Object.keys(choices)) choice(flag, args[VALUED[flag]], choices[flag]);
+  // Only when the flag was actually PASSED is this a string; left at its default it is
+  // already the array `configDefaults` built, and re-parsing an array would stringify it.
+  if (typeof args.doctrines === 'string') args.doctrines = parseDoctrines(args.doctrines);
   return args;
 }
 
@@ -897,9 +952,14 @@ const PROJECT_EMITS = {
   opencode: emitOpencode,
 };
 
-export function emitProjectInto(host, { theme, out, root, footprint = 'full' }) {
+export function emitProjectInto(host, { theme, out, root, footprint = 'full', doctrines = null }) {
   const emit = PROJECT_EMITS[host];
-  return withPyNewlines(() => emit(makeCfg(), { theme, footprint, root }, out));
+  // `doctrines` rides the same rail posture and mode ride into `emitGlobalInto`, and for the
+  // same reason: a drift reader that renders `expected` at the DEFAULT pack set reports the
+  // whole doctrines section as edited on every narrowed install. `null` means "no opinion" and
+  // `makeCfg` renders all four, which is what every validation caller wants.
+  return withPyNewlines(() => emit(makeCfg(doctrines ? { doctrines } : {}),
+    { theme, footprint, root }, out));
 }
 
 /**
@@ -917,7 +977,7 @@ export function buildInto({ theme, out, footprint = 'lean' }) {
 }
 
 export function emitGlobalInto(host, {
-  theme, out, cfgDir, footprint, posture = null, mode = null,
+  theme, out, cfgDir, footprint, posture = null, mode = null, doctrines = null,
 }) {
   // `build.HOSTS.get(host, build.HOSTS["opencode"])` — an unknown host falls back rather than
   // raising, because the host comes from a marker file a user can edit.
@@ -935,7 +995,13 @@ export function emitGlobalInto(host, {
   // that chose a register — the same scar the footprint left in `diffCollect`, one axis over.
   return withPyNewlines(
     () => emit(
-      makeCfg({ posture: posture || 'peer', mode: mode || 'direct' }),
+      // THE PACK SELECTION RIDES THE SAME RAIL, with one difference: `doctrinesOfDir` answers
+      // `null` for "no marker / undetectable", and that must render at ALL packs rather than
+      // at `[]`, so the key is OMITTED instead of passed through — `makeCfg`'s own default is
+      // the fail-closed answer and an explicit `doctrines: null` would not reach it.
+      makeCfg({
+        posture: posture || 'peer', mode: mode || 'direct', ...(doctrines ? { doctrines } : {}),
+      }),
       { theme, footprint, root: null, cfgDir }, out,
     ),
   );

package/docs/extending.md

@@ -1,8 +1,8 @@
 # Extending — what it costs to change this tool
 
 `docs/limits.md` is the standing answer to *"what does this tool not prove about itself?"*.
-This file is its companion: **"what does it cost to add one thing?"** — one law, one skill, one
-plugin, one hook verb, one doc page, one theme, one screen.
+This file is its companion: **"what does it cost to add one thing?"** — one invariant, one
+doctrine rule, one skill, one plugin, one hook verb, one doc page, one theme, one screen.
 
 It exists because the answer is never one file. Every user-visible noun in Geneseed has
 *satellites* — a themed title in fourteen voices, a class in a hand-written map, a count in a
@@ -10,6 +10,11 @@ badge, a row in a ledger, a page in the console — and the gates that keep them
 across `doctor`, the Node suite and four CI jobs. A contributor who knows the satellites ships in
 one pass; one who does not discovers them one red gate at a time.
 
+The governance surface is three tiers and they cost very different amounts. **Adding a doctrine
+rule is the cheap, common case** (§2a); **amending an invariant** is next (§2b); **adding an
+invariant** is the most expensive single edit in the repo after the CLI surface (§2c); **adding a
+whole pack** is rare and mechanical (§2d).
+
 Written after the Python migration completed (2026-08-18), against `main`. Verified: every
 file:line below was opened, and the commands were run.
 
@@ -35,11 +40,22 @@ Two rules follow from the table and they cause most of the surprises:
 
 ### Counts are computed — never type one
 
-`{N_LAWS}` `{N_AGENTS}` `{N_SKILLS}` `{N_PLUGINS}` are substituted at request time from the live
-inventory (`js/web/docs.mjs:169-172`). Typing a literal number into a `docs/web` page is caught by
-`proseMirrorProblems` (`js/doctor.mjs:715-737`). The README badges and prose, and the
-`N laws, N agents, N skills` line in `SHIPPED.md`, are the hand-written exceptions — and each has
-its own doctor arm (`js/doctor.mjs:676`, `:739`, `:822-829`).
+Eight tokens are substituted at request time from the live inventory, by `docCounts` in
+`js/web/docs.mjs`: `{N_LAWS}` `{N_AGENTS}` `{N_SKILLS}` `{N_PLUGINS}`, plus the four the
+three-tier split added — `{N_ONTOLOGY}` (the ontology's sections), `{N_PACKS}` (packs that exist),
+`{N_PACKS_ACTIVE}` (packs this install built in) and `{N_DOCTRINE_RULES}` (rules inside the active
+packs). `{N_LAWS}` is the **invariant** count and nothing else; there is deliberately no token
+meaning "the whole constitution", because `proseMirrorProblems` holds README and `SHIPPED.md`
+prose to that same number and a token that quietly meant something wider would put the docs and
+the gate at odds with no way to re-bless either.
+
+⚠ **Only a `kind: "concept"` page is substituted.** A `markdown`-kind page renders `{N_PACKS}`
+literally, on the screen, as those nine characters.
+
+Typing a literal number into a `docs/web` page is caught by `proseMirrorProblems`. The README
+badges and prose, and the `N laws, N agents, N skills` line in `SHIPPED.md`, are the hand-written
+exceptions — and each has its own arm in `js/doctor.mjs` (`countTableProblems` walks the five
+badge keys `agents`/`skills`/`laws`/`themes`/`plugins`; `proseMirrorProblems` holds the prose).
 
 ---
 
@@ -128,18 +144,38 @@ Notes that matter:
 
 ---
 
-## 2 — Adding a LAW
+## 2 — Changing the constitution
 
-Ten files, of which five are pure satellites. Ground truth: `git show --stat 1b53701` (law XXXVIII)
-touched 21 files, 14 of them themes.
+Three tiers, four different costs. The addresses are `{{LAW}} <roman>` for an invariant and
+`{{DOCTRINE}} <pack> <n>` for a doctrine rule; the ontology is cited by section name and adding a
+section to it is not a checklist, it is a design change.
 
-1. `src/laws/universal.md` — **append** `### {{LAW}} <roman> — {{LEX_<roman>}}` plus the body.
-   Never insert: 397 `{{LAW}} <numeral>` cross-references live in `src/`, plus hardcoded citations
-   in `js/hooks.mjs` and two OpenCode plugins, and **nothing resolves a cross-reference against the
-   canon**. Renumbering silently rewires every one of them.
-2. `themes/_TEMPLATE.json` — add `LEX_<roman>` in template order. **Nothing gates this file**
-   (`themeFiles()` filters `_`-prefixed names, `js/installs.mjs:113`), so forgetting it is green
-   today and starves the *next* law's sync.
+To count the cross-references either tier already carries, from the repo root:
+
+```bash
+grep -rhoE "\{\{LAW\}\} [IVXL]+" src/ | wc -l
+grep -rhoE "\{\{DOCTRINE\}\} [a-z]+ [0-9]+" src/ | wc -l
+```
+
+On this checkout that reports 153 and 209. Both numbers move on every wave of editing, which is
+why the commands are here and the answers are not load-bearing.
+
+### 2a — Adding a DOCTRINE RULE (the common case)
+
+Five files, none of them a count. This is the slot most new material belongs in, and it is cheap
+on purpose so that the invariant slot stays scarce.
+
+1. `src/doctrines/<pack>.md` — **append** `### {{DOCTRINE}} <pack> <n> — {{DOC_<PACK>_<n>}}` plus
+   the body. Two gates in `constitutionProblems` (`js/doctor.mjs`) sit on this: the pack named in
+   the *heading* is what addresses the rule (not the filename, so a rule filed in the wrong file is
+   reported rather than silently renamed), and ids must run **contiguously from 1**, so appending
+   at the end is the only place `n` is free. Packs are numbered independently — nothing outside
+   this file renumbers.
+2. `themes/_TEMPLATE.json` — add `DOC_<PACK>_<n>`. ⚠ **This file *is* gated for this key family.**
+   `themeFiles()` filters `_`-prefixed names and theme parity never sees the template, but
+   `constitutionProblems` reads it alongside the fourteen voices for `DOC_*` and `LEX_*`
+   specifically — because it is what `--sync-themes` seeds the *next* voice from. Every other key
+   family in that file is still ungated.
 3. Seed the fourteen themes:
 
    ```bash
@@ -147,37 +183,110 @@ touched 21 files, 14 of them themes.
    ```
 
    ⚠ Four spellings of this command are in circulation and two of them fail — `doctor`'s own tip
-   is one of the two. See §7.2 before you copy a command from anywhere else.
-4. Restyle all fourteen by hand. `--sync-themes` writes the template's `<themed title for …>`
-   placeholder and only *prints* `RESTYLE these`; a shipped placeholder passes every gate.
-5. `js/inventory.mjs:40` — `LAW_CLASS`, one of the six in `LAW_CLASSES` (`:56`).
-6. `web/src/pages/Laws.jsx:28` — `LAW_META`: same class, plus the one-line Principle. **This copy
-   exists nowhere else**; a law absent here renders with a blank description. It is why that one
-   React file ships alone out of `web/src` in `package.json` — `doctor` regex-parses its literal.
-7. `README.md` — badge `badge/laws-N` and the `N universal laws` sentence.
-8. `SHIPPED.md` — the `N laws, N agents, N skills` triple.
-9. `tests/unit/harness.test.mjs:293` — the negative fixture hardcodes the *next* free numeral;
-   bump it or it stops being a fixture and starts being a duplicate.
-10. `CHANGELOG.md`, then rebuild and commit `web/dist` (step 6 touched `web/src`).
-
-**Amending** a law is steps 1, 10 and — if the principle moved — 6. Two extra cautions:
+   is one of the two. See §7.2 before you copy a command from anywhere else. Then restyle all
+   fourteen by hand: `--sync-themes` writes the template's placeholder and only *prints*
+   `RESTYLE these`; a shipped placeholder passes every gate.
+4. `web/src/pages/Laws.jsx` — a `DOCTRINE_META` row keyed `'<pack>.<n>'`. Its first field is the
+   **pack**, not one of `LAW_CLASSES`' six; `doctrineMetaProblems` requires an *equality* between
+   that field and the key's own pack, which catches the copy error a six-way vocabulary cannot — a
+   row pasted from the pack above it, keeping the wrong pack. Its second field is the one-line
+   Principle, and **that copy exists nowhere else**; a rule absent here renders with a blank
+   description.
+5. `CHANGELOG.md`, then rebuild and commit `web/dist` (step 4 touched `web/src`).
+
+**What a doctrine rule does *not* cost**, and each of these is a deliberate asymmetry:
+
+- **No class entry.** There is no `LAW_CLASS` analogue: a doctrine rule's class *is* its pack, and
+  there is no second taxonomy over it.
+- **No count, anywhere.** No badge, no `SHIPPED.md` triple, no prose mirror. The console spends
+  `{N_PACKS}` / `{N_PACKS_ACTIVE}` / `{N_DOCTRINE_RULES}`, all computed at request time.
+- **No test fixture to bump**, and no renumber risk.
+
+⚠ **Cite only downward.** An always-on tier may never reference a toggleable one:
+`constitutionProblems` refuses a `{{DOCTRINE}}` token anywhere under `src/ontology/` or
+`src/laws/`, because a `--doctrines craft` build would then ship an invariant pointing at text its
+`AGENT.md` does not contain. Doctrine→doctrine citations are fine and stay — every pack file ships
+on disk whether or not it was built in. If the build's own default is narrowed,
+`constitutionProblems` emits a `[note]` naming every citation that points at a shelved pack; notes
+are printed and **not** counted, because a narrowed build is a configuration its owner chose, not
+a defect.
+
+### 2b — Amending an INVARIANT
+
+Steps 1 and 9 of §2c, plus `LAW_META` if the Principle line moved. Two cautions:
 
 - `--footprint` defaults to **lean**, and lean keeps only the heading plus the first sentence
-  (`js/render.mjs:167`). A clause added to the second paragraph is invisible in the default build.
-  Amend the first sentence, or the amendment does not exist for most installs.
-- ⚠ **Law I is frozen.** `LEX_I` is one of seven theme keys recorded byte-for-byte in the
-  primitives corpus (§5). Retitling Law I in any theme reddens a snapshot that cannot be re-blessed.
+  (`terseBlocks` in `js/render.mjs`). A clause added to the second paragraph is invisible in the
+  default build. Amend the first sentence, or the amendment does not exist for most installs. The
+  same is true of a doctrine rule; it is **not** true of the ontology, which ships whole at both
+  footprints.
+- ⚠ **Rule I is frozen.** `LEX_I` is one of seven theme keys recorded byte-for-byte in the
+  primitives corpus (§5.2). Retitling Rule I in any theme reddens a snapshot that cannot be
+  re-blessed.
+
+### 2c — Adding an INVARIANT
+
+Nine steps, and only the first is the rule itself. This is the expensive one, and it should be:
+the bar is in `DESIGN.md` Decision 7, and most candidates belong in a doctrine pack instead.
 
-The carrier itself is gated: `tests/unit/emit_smoke.test.mjs:211-265` checks every law reaches
-every one of nine emit modes in order and themed, under both footprints, with a ceiling **and** a
-floor on the rendered size. Headroom measured today: ~2 100 chars full, ~1 200 lean — about three
-average laws at full footprint, which is the binding one.
+1. `src/laws/universal.md` — **append** `### {{LAW}} <roman> — {{LEX_<roman>}}` plus the body.
+   Never insert: the `{{LAW}}` cross-references counted above live all over `src/`, plus hardcoded
+   citations in `js/hooks.mjs` and two OpenCode plugins, and **nothing resolves a cross-reference
+   against the canon**. Renumbering silently rewires every one of them.
+2. `themes/_TEMPLATE.json` — add `LEX_<roman>` in template order. Gated, as in §2a step 2:
+   `constitutionProblems` holds `LEX_I..LEX_IX` as an **equality** across all fifteen files (the
+   fourteen voices and the template), so both a missing key *and* a leftover one are reported. That
+   arm exists because the renumber left `LEX_XXII`, `LEX_XXIII`, `LEX_XXIV` and `LEX_XXXVI` behind
+   in every file and parity was silent — they were absent from nowhere.
+3. `--sync-themes`, then restyle all fourteen by hand (§2a step 3).
+4. `LAW_CLASS` in `js/inventory.mjs` — one of the six in `LAW_CLASSES` beside it.
+5. `LAW_META` in `web/src/pages/Laws.jsx` — same class, plus the one-line Principle. Note the map
+   is keyed by **arabic** number where `universal.md` heads with a Roman numeral. **This copy
+   exists nowhere else**; a rule absent here renders with a blank description. It is why that one
+   React file ships alone out of `web/src` in `package.json` — `doctor` regex-parses its literal.
+6. `README.md` — badge `badge/laws-N` and the `N universal laws` sentence.
+7. `SHIPPED.md` — the `N laws, N agents, N skills` triple.
+8. `tests/unit/harness.test.mjs` — the negative fixture for the `LAW_CLASS` gate plants a rule at
+   the *first free numeral*, which is `X` now that the invariants are I..IX. Bump it, or it stops
+   being a fixture and starts being a duplicate.
+9. `CHANGELOG.md`, then rebuild and commit `web/dist` (step 5 touched `web/src`).
+
+⚠ While restyling, `{{LAW}}` must stay a **single word** in every theme (and so must
+`{{DOCTRINE}}`). Both heading parsers match the tier noun with `\S+`, so a two-word value does not
+error — the heading simply stops matching and the whole tier parses to nothing, in silence.
+`constitutionProblems` refuses one, which is the only reason it is visible at all.
+
+The carrier itself is gated: `tests/unit/emit_smoke.test.mjs` checks every rule reaches every one
+of nine emit modes in order and themed, under both footprints, with a `CEILING` **and** a floor
+(half the ceiling) on the rendered size. Its docblock carries the current measurement: headroom is
+1,522 characters (2.8%) at full and 1,794 (4.8%) at lean, against the largest carrier — the
+host-agnostic `files` bundle. Read that docblock before adding text to any tier; it is
+re-measured, never nudged, and the ceiling is measured **with all four packs active**, which is
+the only configuration it can speak for.
+
+### 2d — Adding a whole PACK
+
+Rare, and mechanical. On top of §2a for each rule the pack carries:
+
+1. `src/doctrines/<pack>.md`, opening with its lead line — `**{{PACK_<NAME>}}** — how … .` A pack
+   file `PACK_ORDER` names but cannot read, or one carrying no `### {{DOCTRINE}} <pack> <n>`
+   heading at all, is a refusal.
+2. `PACK_ORDER` in `js/checkout.mjs` — the registration, and the render order. It is **narrative,
+   not alphabetical** (craft → rigor → ops → process); discovery sorts alphabetically and the
+   renderer refuses a `.md` under `src/doctrines/` that `PACK_ORDER` does not name, rather than
+   skipping it.
+3. `PACK_<NAME>` in `themes/_TEMPLATE.json` and all fourteen voices. Unlike `DOC_*`, this family is
+   held only by `themeParityProblems` — presence, across the voices, template excluded.
+4. `DOCTRINE_BLURBS` in `js/setup.mjs` — the one-line description an installer sees in the wizard,
+   and the only place a pack is ever explained to them. Missing entries fall back to the bare name.
+5. `harness.config.json` if the pack should be on by default; `constitutionProblems` refuses a
+   `doctrines` array naming a pack this checkout does not ship.
 
 ---
 
 ## 3 — Adding a SKILL or an AGENT
 
-**Order matters at the first two steps.** `missingReferencedSpecs` (`js/emit.mjs:493`) *aborts the
+**Order matters at the first two steps.** `missingReferencedSpecs` (in `js/emit.mjs`) *aborts the
 build* when `AGENT.md.tmpl` names a spec with no file — so the file comes before the table row, or
 nothing builds at all. The refusal is clean: `tests/unit/emit_gates.test.mjs:265` proves a refused
 emit leaves the prior install intact.
@@ -185,14 +294,14 @@ emit leaves the prior install intact.
 1. `src/skills/<name>.md` or `src/agents/<name>.md`. The shape is load-bearing: `# {{SKILL}}: <name>`,
    a blank line, then a `>` blockquote holding `{{DESC_<NAME>}}` — title, blockquote, nothing
    between. `doctor` checks both the presence of the purpose line and that the blockquote is the
-   *first* block (`js/doctor.mjs:899-908`).
+   *first* block (`authoringProblems`, via `firstBlockquote` and `descBlockProblem`).
 2. One row in the hand-authored table in `src/AGENT.md.tmpl` (agents `125-141`, skills `183-229`).
    Gated both ways: a row with no file, and a file with no row.
 3. `DESC_<NAME>` in **all fourteen** themes. Theme parity catches a missing one; nothing catches
    an unstyled placeholder.
-4. **Skills only** — `SKILL_CLASS` in `js/inventory.mjs:59`. Gated both ways
-   (`js/doctor.mjs:785-791`), which matters because the runtime fallback is silent: an unclassified
-   skill renders as `build` (`js/inventory.mjs:166`).
+4. **Skills only** — `SKILL_CLASS` in `js/inventory.mjs`. Gated both ways, inside
+   `countTableProblems`, which matters because the runtime fallback is silent: an unclassified
+   skill renders as `build`.
 5. `registry.json` — a row keyed `skills/<name>` or `agents/<name>` with `status` ∈
    {`experimental`, `approved`, `deprecated`}, a semver `version`, a non-blank `owner`, an ISO
    `added`, and `last_verified: ""`. **This is the most forgettable step**: four hand-typed fields,
@@ -231,7 +340,7 @@ The `geneseed-` prefix and the `.js` suffix are mechanically load-bearing: the b
 
 1. `adapters/opencode/plugins/geneseed-<name>.js` — ESM, zero dependencies. The factory-export
    convention is real (OpenCode requires it) but **ungated**; the only generic gate on plugin
-   source is `node --check` (`js/doctor.mjs:924-941`).
+   source is `node --check` (the one spawn in `authoringProblems`).
 2. `docs/web/plugin-<name>.md` — `group: plugins`, `title: "geneseed-<name>"`, `kind: "concept"`.
 3. `docs/web/plugins.md` — a bullet. The count above it renders from `{N_PLUGINS}`.
 4. `docs/web/model.md` — a second `{N_PLUGINS}` sentence whose **enumeration of the capabilities
@@ -396,8 +505,9 @@ only, at best, on its presence.
 
 | What | Where | Gated on |
 |---|---|---|
+| `§N` cross-references into `AGENT.md`'s anatomy | `src/skills/*`, `src/agents/*`, `adapters/**` | **range only.** `constitutionProblems` refuses a `§N` the template declares no section for — which catches a pointer past the end, the shape *removing* a section leaves. It cannot catch one that still resolves and now means something else, which is the shape *inserting* a section leaves, and is what actually happened when `## 2. Doctrines` pushed every later section down one. **Renumbering the anatomy means `grep -rn '§' src/ adapters/` and reading every hit.** Four satellites and a live OpenCode deny message shipped stale because the sweep stopped at `AGENT.md.tmpl` |
 | Per-law Principle lines | `web/src/pages/Laws.jsx` | presence and class only, never accuracy |
-| 560 themed law titles (40 × 14) | `themes/*.json` | key presence only — a shipped placeholder is green |
+| 504 themed constitution titles (36 keys × 14 voices) — `LEX_I..LEX_IX` (9), `DOC_<PACK>_<n>` (23), `PACK_<NAME>` (4) | `themes/*.json` | key presence only — a shipped placeholder is green. `LEX_*` and `DOC_*` are held across the template too, and in both directions; `PACK_*` only across the voices |
 | The README keyword enumerations | `README.md`, `docs/web/rules.md` | nothing |
 | The plugin capability enumeration | `docs/web/model.md` | nothing (the number substitutes; the list does not) |
 | Section labels and page subtitles | `web/src/lib/sections.js`, `web/src/pages/Docs/index.jsx` | nothing |
@@ -540,20 +650,19 @@ to kill every pid on the port, then `geneseed web start`.
 Ordered by what unblocks the most work per unit of effort. Each is small; none is urgent enough to
 stop a change today, and all of them cost a contributor a wrong turn until they are done.
 
-1. **Rewrite the authoring section of `DESIGN.md` (§7.1) and fix `doctor`'s tip (§7.2).** These are
-   the two documents a contributor reads *first* when adding a law, and both name programs that no
-   longer exist. Half an hour, and it removes the most likely first wrong turn.
-2. **Extend the fenced-command gate to `DESIGN.md` and `docs/**/*.md` (§7.3).** One array literal.
-   It would have caught item 1 the day it was written, and it keeps catching it.
-3. **Decide the hook-verb question (§5.1) before it is asked under pressure.** Either mirror the
+1. **Extend the fenced-command gate to `DESIGN.md` and `docs/**/*.md` (§7.3).** One array literal.
+   Today it covers four documents, and both of the pointer-to-nothing defects §7 records — the
+   `DESIGN.md` authoring section and `doctor`'s theme-parity tip, since fixed — sat outside its
+   reach. It keeps catching them.
+2. **Decide the hook-verb question (§5.1) before it is asked under pressure.** Either mirror the
    CLI side's exemption list onto the hook half, or write down that the hook verb set is closed.
    Either answer is fine; discovering the question mid-feature is not.
-4. **Write down the frozen-key list (§5.2) where a theme author will see it** — `themes/README.md`
+3. **Write down the frozen-key list (§5.2) where a theme author will see it** — `themes/README.md`
    is the natural home. Seven keys × fifteen files is a small enough surface to name explicitly,
    and today nothing warns you before the snapshot goes red.
-5. **Gate `AGENT_LESSON_PROMPT` like its sibling (§7.7), and either gate or delete
+4. **Gate `AGENT_LESSON_PROMPT` like its sibling (§7.7), and either gate or delete
    `adapters/claude-code/settings.json` (§7.10).** Two silent failure modes, both cheap to close.
-6. **Consider a `scripts` block in the root `package.json`.** There is currently no single command
+5. **Consider a `scripts` block in the root `package.json`.** There is currently no single command
    that runs what CI runs; every contributor reassembles the five by hand from this file. A
    `verify` script is three lines and makes §1 executable rather than descriptive.
 

package/docs/limits.md

@@ -78,10 +78,10 @@ nothing else — **M1, M2, M3, M4 and M8** (`EMIT`, `EMIT_IMPERIAL`, `EMIT_CLAUD
 `CLI_CONTEXT`). All five are killed by `tests/unit/` alone, the control included, and each row now
 **declares** the unit file that kills it rather than a replay that can no longer run — M1 and M3
 `maintainer_tools`, M2 `node_driver`, M4 `hook_form`, M8 `hook_cli`. A gate a matrix names and
-cannot run guards nothing, and is worse than none, because it is trusted (law XXXVIII). For every
-defect the mutation matrix knows how to plant, the corpus was redundant. That is the whole
-argument, and it is the only one that licenses a deletion: a test goes because a living gate
-already proves the property, never because it is red.
+cannot run guards nothing, and is worse than none, because it is trusted (Doctrine rigor 2,
+Honest Tests). For every defect the mutation matrix knows how to plant, the corpus was
+redundant. That is the whole argument, and it is the only one that licenses a deletion:
+a test goes because a living gate already proves the property, never because it is red.
 
 **What was knowingly LOST: byte-level regression detection on emit, cli and web output.** Nothing
 now notices that a rendered bundle, a verb's stdout / stderr / exit code, or an HTTP response body

package/docs/token-footprint.md

@@ -30,10 +30,21 @@ every host the same way instead of one silently falling behind.
 
 ## Where the tokens go
 
-- **The root file is ~76% of the bill**, and its Rules section alone is ~6.3k
-  of the ~10.7k. The [footprint dial](#/docs/footprint) (`full` vs `lean`)
-  exists precisely because this is the only lever that matters — trimming
-  anything else is noise.
+- **The root file is ~76% of the bill**, and the constitution inside it is the
+  bulk of that — no longer one section but three: the Ontology, the nine Rules,
+  and the doctrine packs this install built in. **Two** levers move it, not one.
+  The [footprint dial](#/docs/footprint) (`lean`, the default, keeps each Rule
+  and each doctrine rule as its heading plus first line, and ships the Ontology
+  *whole*; `full` inlines every rationale). And the
+  [doctrine packs](#/docs/setup-choices) — `geneseed-build --doctrines craft,rigor`
+  drops whole blocks of §2 at build time, which removes far more than the
+  footprint dial trims. Anything else is noise.
+
+  The three-tier split grew the root file: measured on `neutral`, `AGENT.md`
+  went from 31,457 bytes to 36,882 at `lean` (+17.2%) and 53,378 to 54,810 at
+  `full` (+2.7%). The lean growth is the larger one *by design* — the Ontology
+  is prose, and truncating four flowing sections to four orphan sentences would
+  have shipped a worldview nobody could read.
 - **Skill bodies (~53k) and agent bodies (~10k) are lazy** on every host —
   loaded only when invoked. A typical skill costs ≤3k per invocation; the
   heaviest (`react-view-transitions`, ~17.5k with its reference files) loads

package/docs/web/authoring.md

@@ -4,7 +4,7 @@ order: 0
 title: "Edit the source"
 kind: "concept"
 ---
-Everything theme-independent lives under `src/` — laws, agents, skills, memory and notebook conventions, and the `AGENT.md.tmpl` entrypoint. Voice tokens live under `themes/` as one JSON file per theme. After editing, `geneseed build --emit opencode-global` (or `geneseed update`) re-renders the deployed bundle. The `doctor` action verifies the result: unresolved theme tokens, dead links, hermetic escapes, theme-key parity, and that the committed bundle matches a fresh render.
+Everything theme-independent lives under `src/` — the constitution (`ontology/`, `laws/`, `doctrines/`), the `postures/` and `modes/` registers, agents, skills, memory and notebook conventions, and the `AGENT.md.tmpl` entrypoint. Voice tokens live under `themes/` as one JSON file per theme. After editing, `geneseed build --emit opencode-global` (or `geneseed update`) re-renders the deployed bundle. The `doctor` action verifies the result: unresolved theme tokens, dead links, hermetic escapes, theme-key parity, and that the committed bundle matches a fresh render.
 
 Each agent and skill also carries a lifecycle status — `experimental`, `approved` or `deprecated` — recorded in `registry.json` at the repo root alongside its version, owner and add-date. The file is maintainer-side: it is never rendered into a bundle, so a status costs no session context. Adding a spec means adding its row; `doctor` fails on a spec with no row and on a row with no spec, and the catalog badges anything that is not `approved`. The same pass refuses to let a credential ship, and holds every vendored skill folder to an immutable upstream commit rather than a moving branch.
 

package/docs/web/claude-hooks.md

@@ -9,8 +9,8 @@ Claude Code has no `instructions` array and no JS plugin dir — the harness rea
 ### The four hooks
 
 - **Context injection** — `SessionStart` (startup, clear, resume) runs `geneseed-hook context`: auto-discovers the repo's docs by convention and injects them before your first turn, plus your machine wiki. It honours the same `GENESEED_CONTEXT` manifest as the OpenCode context plugin.
-- **Git gate** — `PreToolUse` on Bash runs `geneseed-hook git-gate`: enforces the safety Laws at the tool boundary, before a shell command executes.
-- **Rule gate** — `PreToolUse` on the write tools runs `geneseed-hook rule-gate`: a write to `user-rules.md` or to a memory file asks first, because whether something you want kept is a standing rule or a durable fact is *your* call, settled through the [rule skill](#/docs/skills) (**Law VI**). Ordinary edits are untouched.
+- **Git gate** — `PreToolUse` on Bash runs `geneseed-hook git-gate`: a `git commit` or `git push` anywhere in the command line — a compound one-liner and a `-C <path>` form included — asks first, at the tool boundary and before the shell runs it (**Doctrine process 5**). It is the one hook that rides a doctrine pack: an install built without **process** never gets this group, because a boundary that keeps asking for a rule the install did not adopt is a gate arguing with its own harness.
+- **Rule gate** — `PreToolUse` on the write tools runs `geneseed-hook rule-gate`: a write to `user-rules.md` or to a memory file asks first, because whether something you want kept is a standing rule or a durable fact is *your* call, settled through the [rule skill](#/docs/skills) (**Doctrine process 1**). Ordinary edits are untouched.
 - **Learn** — `Stop` and `SubagentStop` run `geneseed-hook learn`: distils durable memories into the install's `memory/` store at session end; a subagent's stop routes to the per-agent lesson path (`memory/agents/<name>.md`).
 
 ### Where they live

package/docs/web/collaboration.md

@@ -4,7 +4,7 @@ order: 11
 title: "The collaboration layer"
 kind: "concept"
 ---
-Beyond the Laws, four mechanisms shape *how* the agent works with you — the register, the mutual contract, how memory binds, and who you are. All four are plain content in `AGENT.md` and its neighbours, so they ride to every host (OpenCode, Claude, Bob, Copilot) unchanged.
+Beside the [constitution](#/docs/rules), a handful of mechanisms shape *how* the agent works with you — the two registers, the mutual contract, how memory binds, and who you are. All of them are plain content in `AGENT.md` and its neighbours, so they ride to every host (OpenCode, Claude, Bob, Copilot) unchanged.
 
 ### Postures — the register
 
@@ -16,7 +16,7 @@ A **mode** is the session's operating register — *how* work gets executed, as
 
 ### The Pact — a two-way contract
 
-Where the Laws bind the agent, the **Pact** binds the collaboration. It holds three co-equal protections (you, the truth, the agent) and — unusually — names what *you* owe back: don't punish candour that honours the pact, give context up front, decide when shown a fork. It is framing, not an enforced rule.
+Where the Rules bind the agent, the **Pact** binds the collaboration — and it is not a layer beside them: it is stated inside the Ontology's **Telos**, the tier that is always in force, so it holds in every task and every repository. It carries three co-equal protections (you, the truth, the agent), never traded one for another, and — unusually — names what *you* owe back: don't punish candour that honours the pact, give context up front, decide when shown a fork. Your half is not enforceable against you; the agent's half is binding on it.
 
 ### Typed memory — binding force
 
@@ -24,4 +24,4 @@ A memory may carry an optional `force` — **constraint** (imposed, not the agen
 
 ### Your profile — identity
 
-`PROFILE.md`, seeded once beside `AGENT.md` and never overwritten, holds *who you are*: role, habits, register preferences. It is identity, not rules — it colours how the agent works but never binds (precedence is Laws, then `user-rules.md`, then the profile). Edit it here under the **Profile** tab, or in the file directly — or let the agent draft it: the [[profile]] skill interviews you (who you are, how you work, how you like answers pitched) and writes the file only with your consent, routing anything that is really a standing rule to `user-rules.md` instead.
+`PROFILE.md`, seeded once beside `AGENT.md` and never overwritten, holds *who you are*: role, habits, register preferences. It is identity, not rules — it colours how the agent works but never binds (precedence is the Ontology and the Rules, then `user-rules.md`, then the active Doctrines, then the profile). Edit it here under the **Profile** tab, or in the file directly — or let the agent draft it: the [[profile]] skill interviews you (who you are, how you work, how you like answers pitched) and writes the file only with your consent, routing anything that is really a standing rule to `user-rules.md` instead.

package/docs/web/first-session.md

@@ -8,7 +8,7 @@ Once installed, the agent doesn't change *how* you talk to your tool — it chan
 
 ### What loaded automatically
 
-- **`AGENT.md`** — {N_LAWS} universal Rules the agent obeys.
+- **`AGENT.md`** — the [constitution](#/docs/rules): the Ontology's {N_ONTOLOGY} sections, {N_LAWS} always-on Rules, and the {N_DOCTRINE_RULES} doctrine rules from the packs this install built in.
 - **Your repo's docs** — `README.md`, `CONTRIBUTING.md`, anything under `docs/` the harness discovers.
 - **Your machine's wiki** (if you [set one up](#/docs/configure-wiki)) — eager entries and a lazy listing of the rest.
 - **The skill and agent catalogue** — invokable by name.
@@ -25,4 +25,4 @@ Skills are repeatable workflows; agents are capability specialists. You invoke t
 
 ---
 
-**Catalog:** [Skills](#/section/skills) · [Agents](#/section/agents) · [Rules](#/laws)
+**Catalog:** [Skills](#/section/skills) · [Agents](#/section/agents) · [Constitution](#/laws)