geneseed 3.4.0 → 3.6.0

package/bin/geneseed-cli.mjs

@@ -54,7 +54,7 @@
 // table below now holds one LOADER per row (`() => import(…).then(m => m.cmdX)`), so a verb
 // loads its slice of the tree and no other verb's. The spawn allow-list gate still sees the
 // whole graph: `tests/unit/hook_cli.test.mjs`'s `importClosure` follows both import spellings.
-import { cliSpec, printHelp } from '../js/ui/cli.mjs';
+import { cliSpec, printHelp, printVerbList } from '../js/ui/cli.mjs';
 import { parseIntStrict } from '../js/lib/text.mjs';
 import { printErr } from '../js/lib/fs.mjs';
 
@@ -279,10 +279,15 @@ async function main(argv) {
   // 'error' event and a stack trace.
   process.stdout.on('error', (e) => { if (e.code === 'EPIPE') process.exit(0); });
 
+  // Bare = `home`, as both launchers (`geneseed`, `geneseed.cmd`) already did — but the npm
+  // `bin` names THIS file, so a bare `geneseed` off PATH used to die asking for a verb.
+  if (!argv.length) argv = ['home'];
   const verb = argv[0];
-  if (!verb || verb === '-h' || verb === '--help') {
-    return die(2, `the following arguments are required: cmd (one of ${
-      Object.keys(VERBS).join(', ')})`);
+  if (verb === '-h' || verb === '--help') {
+    return printVerbList('geneseed', [...Object.keys(VERBS), 'validate'], {
+      update: 'an alias of upgrade',
+      validate: "check the source tree without emitting (the generator's --validate-only)",
+    });
   }
   // `validate` — the generator's `--validate-only`, and the one verb this entry answers that is NOT
   // in the table above. It is dispatched here, before the lookup, for a reason that is a
@@ -302,7 +307,7 @@ async function main(argv) {
     // Lazy for the same reason the table rows are — `parseDriverArgs` alone drags the whole
     // generator driver in, and every OTHER verb was paying for it.
     const [{ cmdValidate }, { parseDriverArgs }] = await Promise.all([
-      import('../js/inspect/validate.mjs'), import('./build-driver.mjs'),
+      import('../js/inspect/validate.mjs'), import('../js/build/driver.mjs'),
     ]);
     try {
       return cmdValidate(parseDriverArgs(argv.slice(1)));
@@ -319,7 +324,7 @@ async function main(argv) {
     // just about to become false — it was already claiming a third place for verbs that do
     // not exist.
     return die(2, `invalid choice: '${verb}'. This entry point carries only `
-      + `${Object.keys(VERBS).join(', ')}; the four hook verbs live in `
+      + `${Object.keys(VERBS).join(', ')}; the five hook verbs live in `
       + 'bin/geneseed-hook.mjs.');
   }
   // `js/cli-table.json`, the CLI as data. A verb this table dispatches and the file does not

package/bin/geneseed-hook.mjs

@@ -48,7 +48,7 @@ import { printErr } from '../js/lib/fs.mjs';
 const HOSTED = { '--root': 'root', '--host': 'host' };
 const VERBS = {
   context: { fn: cmdContext, flags: HOSTED },
-  'git-gate': { fn: cmdGitGate, flags: HOSTED },
+  'git-gate': { fn: cmdGitGate, flags: HOSTED, switches: { '--no-consent': 'noConsent' } },
   'rule-gate': { fn: cmdRuleGate, flags: HOSTED },
   'tool-gate': { fn: cmdToolGate, flags: HOSTED },
   learn: {
@@ -72,7 +72,9 @@ function die(code, msg) {
  * positional.
  */
 function parse(spec, argv) {
-  const args = { root: null, host: null, memory: null, consolidate: false, file: null };
+  const args = {
+    root: null, host: null, memory: null, consolidate: false, noConsent: false, file: null,
+  };
   for (let i = 0; i < argv.length; i += 1) {
     const tok = argv[i];
     const eq = tok.indexOf('=');

package/docs/candidate-hosts.md

@@ -36,7 +36,7 @@ current host gets. Skills are the largest surface by file count and they cost no
 - **Codex CLI — cheapest, and the only one with an ask tier.** Its hook schema is
   Claude's with `hooks.json`/`config.toml` as the carrier, its payload field names are
   Claude's, and `permissionDecision: "ask"` exists. The Claude engine with `host: "codex"`
-  covers instructions (`AGENTS.md`), skills (`.agents/skills`) and the four hook verbs
+  covers instructions (`AGENTS.md`), skills (`.agents/skills`) and the hook verbs
   unchanged; the only new code is the carrier writer (a `hooks.json` merge or a TOML
   table) and the config-dir resolver (`~/.codex`, `$CODEX_HOME`). Roughly the Copilot
   port minus the dialect work.

package/docs/design-history.md

@@ -4,7 +4,7 @@
 
 **The Node port, P2 → P10 (2026-06 → 2026-08). A record, not a spec.**
 
-[← Back to DESIGN.md](../DESIGN.md) · [What this tool does not prove](limits.md) · [What it costs to add one thing](extending.md)
+[← Back to DESIGN.md](../DESIGN.md) · [What it costs to add one thing](extending.md)
 
 </div>
 
@@ -31,7 +31,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
 ---
 
 ## ⚙️ Generator contract — the port narrative
-- **The render core has a Node twin: [`js/build/render.mjs`](js/build/render.mjs).** It is a
+- **The render core has a Node twin: [`js/build/render.mjs`](../js/build/render.mjs).** It is a
   translation of `_build_render.py`'s pure pipeline, byte-identical by test rather than by
   intent — `tests/test_render_parity.py` renders both over every theme × footprint ×
   catalog × laws-prefix × posture × mode and compares the written trees byte for byte,
@@ -39,7 +39,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   sort. `js/lib/fs.mjs` holds the primitives where the two runtimes disagree in silence;
   `Path.write_text`'s `\n` → `os.linesep` translation is the load-bearing one. Zero
   dependencies on that side too.
-- **The host-native layer has one too: [`js/hosts/native.mjs`](js/hosts/native.mjs)** — the point where
+- **The host-native layer has one too: [`js/hosts/native.mjs`](../js/hosts/native.mjs)** — the point where
   RENDER stops being a pure function of `src/`. Its output depends on your
   `agent-overrides.json`, on which files already exist in the target (claim-on-create never
   overwrites a file Geneseed did not write), and on which of the three host dialects is
@@ -49,7 +49,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   items and compares the written tree byte for byte, the returned ownership list *in order*,
   and the warning stream — and asserts the Node side printed nothing at all on stdout,
   because the emitted hook gates signal their verdict there and return 0 on every path.
-- **The OpenCode extras are ported too: [`js/hosts/opencode.mjs`](js/hosts/opencode.mjs)** — the
+- **The OpenCode extras are ported too: [`js/hosts/opencode.mjs`](../js/hosts/opencode.mjs)** — the
   branded and curated colour themes, the opt-in primary agent and slash-command layer, the
   always-on `/ponytail` switch, the verbatim plugin/workflow copies, and the
   `agent-overrides.json` stub with its staleness notice. Half of it sits behind
@@ -61,7 +61,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   streams** — the staleness notice goes to stdout where every native-layer warning goes to
   stderr, an asymmetry inherited from the Python rather than corrected.
 - **The seam is now a real process boundary: `build.py` spawns Node once per emit.**
-  [`js/build/emit.mjs`](js/build/emit.mjs) writes the bundle (`build`) and the OpenCode layer's RENDER
+  `js/build/emit.mjs` writes the bundle (`build`) and the OpenCode layer's RENDER
   stage; Python keeps WIRE, PRUNE, MANIFEST and VERIFY, and drives — so doctor, web deploy,
   setup and rebuild-all keep calling `build.emit_*` in-process with no call site changed.
   Node falls back to Python when `node` is missing, silently and by design: the whole claim
@@ -121,7 +121,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   (with the bundle in a subfolder, so `--out` and the target are not the same directory), a
   `.claude/` the user got to first, and every write-once file edited *between* two emits —
   the only way a byte comparison can tell "kept your store" from "re-seeded it".
-- **The wiring layer has a Node twin as well: [`js/hosts/settings.mjs`](js/hosts/settings.mjs)** — the
+- **The wiring layer has a Node twin as well: [`js/hosts/settings.mjs`](../js/hosts/settings.mjs)** — the
   JSONC reader, the `opencode.json` and `settings.json` merges, the hook shim, the
   managed-block machinery and the settings integrity check. It was proven before it was
   wired, the way every piece before it was; the emit now drives it. It was the last unit to
@@ -203,7 +203,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   writes — a write through the facade cannot be restored reliably, and a redirect that
   silently outlives its test poisons every later read. A bare `SRC` left in a submodule
   raises `NameError` rather than quietly reading a stale copy; that noise is the point.
-- **There is a second driver: [`bin/geneseed.mjs`](bin/geneseed.mjs), and it is ADDED beside
+- **There is a second driver: `bin/geneseed.mjs`, and it is ADDED beside
   `main()` rather than replacing it.** `build.py` is also the `import build` facade that 19
   `rituals/` modules read 55 distinct names from, and roughly eleven sites spawn it as a
   subprocess; none of them flip, because flipping them would make Node mandatory for the
@@ -336,7 +336,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
 - **The runtime port starts with the four HOOK verbs, and with a gate rather than with
   code.** `context`, `git-gate`, `rule-gate` and `learn` are the four commands an emitted
   `settings.json` actually invokes, and they now have a Node twin:
-  [`js/hosts/hooks.mjs`](js/hosts/hooks.mjs) behind [`bin/geneseed-hook.mjs`](bin/geneseed-hook.mjs), a
+  [`js/hosts/hooks.mjs`](../js/hosts/hooks.mjs) behind [`bin/geneseed-hook.mjs`](../bin/geneseed-hook.mjs), a
   **second binary** rather than a subcommand of the generator driver — `learn` must spawn
   whatever `$GENESEED_LLM` names, and `bin/geneseed.mjs` is under a hard `child_process`
   ban that is half the proof it is not a passthrough. The hook entry loads none of the
@@ -345,7 +345,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   to import `build` for the marker filenames they need.
   **A cell is not an emit here, and that is the phase's first design question.** A verb's
   observable surface is stdout, stderr, the **exit code** and whatever it wrote, so
-  [`tests/helpers/cli_golden.mjs`](tests/helpers/cli_golden.mjs) compares all four across 103 seeded
+  [`tests/helpers/cli_golden.mjs`](../tests/helpers/cli_golden.mjs) compares all four across 103 seeded
   worlds — reusing `golden.py`'s `cell_env`, `_normalise`, `_snapshot` and `_split` rather
   than growing a second set of rules about sandboxes and CRLF. `cwd` is an **input** to
   three of the four (discovery, the sovereign bypass, and learn's memory search all read
@@ -417,7 +417,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   transitive relative imports instead — the same assertion, one level out, added because of
   this phase.
 - **`status` and `version` cross, and the phase's method is a CORPUS beside the matrix.**
-  [`js/inspect/status.mjs`](js/inspect/status.mjs) answers both from `bin/geneseed-cli.mjs`. Two structural
+  [`js/inspect/status.mjs`](../js/inspect/status.mjs) answers both from `bin/geneseed-cli.mjs`. Two structural
   things came with them.
   **A closure walk counts what the callee COMPUTES; the caller consumes a fraction of it.**
   An `ast` walk puts `status` at 527 LOC across 7 modules — `_tui_inventory` returns every
@@ -441,7 +441,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   the handoff offered.** `_color_enabled()` is `sys.stdout.isatty()`, every harness captures
   through a pipe, so deleting every escape code would be byte-identical across the whole
   matrix — ship it ungated or drop it and regress a real terminal. `_status_lines` is
-  documented pure, so [`tests/snapshot/pure_snapshot.test.mjs`](tests/snapshot/pure_snapshot.test.mjs)
+  documented pure, so `tests/snapshot/pure_snapshot.test.mjs`
   calls it directly on both sides over a corpus of dashboards × colour × ASCII, and the tty
   question never arises. Three more cell-unreachable functions ride along for the same
   reason — `_version_verdict`'s up-to-date branch, `_manifest_is_claude` (only consulted for
@@ -459,8 +459,8 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   now has one owner for the primitive instead of two.
 - **The first NON-hook verb crosses, and it needed a third binary rather than a row in an
   existing table.** `harness exclude add|remove|list` — the sovereign-repo exclusions —
-  is now [`js/inspect/excludes.mjs`](js/inspect/excludes.mjs) behind
-  [`bin/geneseed-cli.mjs`](bin/geneseed-cli.mjs). The *reader* had been ported since P5a
+  is now [`js/inspect/excludes.mjs`](../js/inspect/excludes.mjs) behind
+  [`bin/geneseed-cli.mjs`](../bin/geneseed-cli.mjs). The *reader* had been ported since P5a
   (`sovereignBypass` runs on every hook call); this is the writer, which maintains
   `excludes.json` across every global install and wires each host's native per-repo
   suppression into the excluded repo.
@@ -492,7 +492,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   atomic (temp + rename) on both sides, so a concurrent pair loses an edit rather than
   tearing the file.
 - **`build`, `prompt` and `theme` cross — the generator's own CLI face —** as
-  [`js/build/generate.mjs`](js/build/generate.mjs). **Ten of the 24 subcommands are now Node.** Three
+  [`js/build/generate.mjs`](../js/build/generate.mjs). **Ten of the 24 subcommands are now Node.** Three
   things are worth recording, and the first is about measurement rather than code.
   **A closure walk cannot see through a `subprocess`, and `build` is nothing but one.**
   `cmd_build` measures three lines because the work is `run([sys.executable, BUILD])`. Its
@@ -524,7 +524,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   `test_the_fence_corpus_still_describes_the_real_tree` re-derives it and fails the day a
   source file grows a four-backtick run — at which point a cell becomes writable and should
   be written. The corpus file is renamed to
-  [`tests/snapshot/pure_snapshot.test.mjs`](tests/snapshot/pure_snapshot.test.mjs) with it: it was
+  `tests/snapshot/pure_snapshot.test.mjs` with it: it was
   named for the status panel when the panel was all it held.
   **Three of the six verbs the phase was scoped around did not cross, each for a measured
   reason.** `sync-self` is a five-line alias whose body is `_update.sync_self` → `upgrade()`,
@@ -536,16 +536,16 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   interpreter using the discovery the shim flip deleted; and a shim naming
   `bin/geneseed-cli.mjs` instead would answer three of the 24 verbs. The npm `bin` map is
   what replaces them, so they belong to the publish phase and not to this one.
-- **`diff` and `rebuild-all` cross** as [`js/inspect/diff.mjs`](js/inspect/diff.mjs) and `cmdRebuildAll` in
-  [`js/build/generate.mjs`](js/build/generate.mjs), with the install detectors extracted to
-  [`js/hosts/installs.mjs`](js/hosts/installs.mjs) and the registry to [`js/inspect/registry.mjs`](js/inspect/registry.mjs).
+- **`diff` and `rebuild-all` cross** as [`js/inspect/diff.mjs`](../js/inspect/diff.mjs) and `cmdRebuildAll` in
+  [`js/build/generate.mjs`](../js/build/generate.mjs), with the install detectors extracted to
+  [`js/hosts/installs.mjs`](../js/hosts/installs.mjs) and the registry to [`js/inspect/registry.mjs`](../js/inspect/registry.mjs).
   **Twelve of the 24 subcommands are now Node.**
   **A closure walk cannot see through the standard library either.** An `ast` walk puts
   `diff` at 252 LOC of marker and manifest reading, and the verb's *entire* user-visible
   payload is `difflib.unified_diff`, which the walk counts as zero because `difflib` is not in
   `rituals/`. There is no lazier answer than reproducing it: a generic JS diff produces a
   correct diff and a *different* one, and what the acceptance matrix compares is bytes. So
-  [`js/lib/udiff.mjs`](js/lib/udiff.mjs) is `SequenceMatcher` and `unified_diff`, including
+  [`js/lib/udiff.mjs`](../js/lib/udiff.mjs) is `SequenceMatcher` and `unified_diff`, including
   `autojunk` — the popular-line purge that engages at 200 elements and rewrites the hunks of
   every real harness file, and which no fixture is large enough to reach.
   **The rest of the diff is gated by cells and the algorithm by a corpus**, with the
@@ -582,10 +582,10 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   does not exist yet: copy the checkout into the sandbox, plant one fault, and run *both*
   binaries from the copy so their two `ROOT`s move together. That is the next phase's first
   design decision rather than a corner of this one.
-- **`doctor` crosses** as [`js/inspect/doctor.mjs`](js/inspect/doctor.mjs), and the fixture came first.
+- **`doctor` crosses** as [`js/inspect/doctor.mjs`](../js/inspect/doctor.mjs), and the fixture came first.
   **Thirteen of the 24 subcommands are now Node.**
   **The copy-the-checkout fixture, measured rather than feared.** `_copy_checkout` in
-  [`tests/helpers/cli_golden.mjs`](tests/helpers/cli_golden.mjs) gives each cell its own copy of the
+  [`tests/helpers/cli_golden.mjs`](../tests/helpers/cli_golden.mjs) gives each cell its own copy of the
   working tree (`git ls-files --cached --others --exclude-standard`), plants one fault in it,
   and runs *both* binaries from the copy so the two `ROOT`s move together. 511 files, 5.2 MB,
   **0.31 s** against a `doctor` run of ~2.1 s — a seventh of the cell, so it is one copy per
@@ -621,7 +621,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   indistinguishable), and one of the mutations is aimed at the FIXTURE: with `_copy_checkout`
   planting nothing, a planted-fault cell does not go red, it goes *vacuous* — which is the
   absolute half of a cell doing its job one layer further out than it ever has.
-- **`uninstall` crosses** as [`js/maintain/uninstall.mjs`](js/maintain/uninstall.mjs), and it is the first verb
+- **`uninstall` crosses** as [`js/maintain/uninstall.mjs`](../js/maintain/uninstall.mjs), and it is the first verb
   in the port that **deletes**. **Fourteen of the 24 subcommands are now Node**; of the ten
   left, `setup`/`menu`/`home` are P5's and the rest belong to P6–P10.
   **A deletion needs the gate to prove what SURVIVED.** Every cell before this one asserts
@@ -660,7 +660,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   question about the corpus of inputs before it is a question about the code. The control had to
   be re-chosen too; the first one shared mechanism with half the mutations and reported four
   over-reaches that were nothing of the kind.
-- **`setup` crosses** as [`js/maintain/setup.mjs`](js/maintain/setup.mjs), and it is the first **interactive**
+- **`setup` crosses** as [`js/maintain/setup.mjs`](../js/maintain/setup.mjs), and it is the first **interactive**
   verb in the port. **Fifteen of the 24 subcommands are now Node**, and P5 is done: the nine
   left belong to P6–P10.
   **`cmd_setup` is a dispatcher, and that is the phase's first finding.** It is 21 lines: a
@@ -717,7 +717,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
 - **The web console's HTTP shell crosses, and it needed a third acceptance harness.**
   `tests/golden.py` compares the tree a generator writes; `tests/harness_golden.py` compares
   one verb invocation on stdout/stderr/exit/files. An endpoint writes nothing and never
-  exits, so [`tests/helpers/web_fixture.mjs`](tests/helpers/web_fixture.mjs) asks a different question: one
+  exits, so [`tests/helpers/web_fixture.mjs`](../tests/helpers/web_fixture.mjs) asks a different question: one
   seeded world, one **sequence of requests** against a freshly started server, compared on
   the status line, the response body as bytes, the five headers the handler *chooses*, the
   daemon record, and the server's own streams. **Both sides are real processes**, started on
@@ -757,7 +757,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
 - **Eight web read endpoints cross, and six of them were a JSON face over work already
   done.** `/api/overview`, `/api/themes`, `/api/doctor`, `/api/diff`, `/api/installs`,
   `/api/excludes`, `/api/setup` and `/api/profile` now answer from
-  [`js/web/api.mjs`](js/web/api.mjs) as well as from `rituals/_web_*.py`. **No subcommand
+  [`js/web/api.mjs`](../js/web/api.mjs) as well as from `rituals/_web_*.py`. **No subcommand
   crosses here and the count stays fifteen** — `web` the verb is P6h's, and until then the
   only caller of this code is the acceptance harness. `api_setup` is `statusData()` plus
   four fields; `api_diff` is `diffCollect()` reshaped; `api_excludes` is
@@ -788,7 +788,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   seconds apart — so the harness normalises them, which means a twin formatting in UTC, or
   padding wrong, would compare equal in every web cell. The stamp is a pure function of an
   epoch second and the local zone, so it is gated in
-  [`tests/snapshot/pure_snapshot.test.mjs`](tests/snapshot/pure_snapshot.test.mjs) over five
+  `tests/snapshot/pure_snapshot.test.mjs` over five
   instants chosen for what they break: single-digit month/day/hour/minute, both sides of a
   UTC date rollover, a DST transition, and a fractional second.
   **Two gates, two findings, and neither came from review.** The harness's own self-check
@@ -821,8 +821,8 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   the control — without which every 501 in the list is vacuous.
 - **The catalog crosses, and the taxonomy it needed was already ported.**
   `/api/catalog/<section>`, `/api/item/<type>/<name>` and the wiki reader answer from
-  [`js/web/api.mjs`](js/web/api.mjs), over a new
-  [`js/inspect/inventory.mjs`](js/inspect/inventory.mjs) — `_harness_tui.py`'s catalog half. **Still
+  [`js/web/api.mjs`](../js/web/api.mjs), over a new
+  [`js/inspect/inventory.mjs`](../js/inspect/inventory.mjs) — `_harness_tui.py`'s catalog half. **Still
   fifteen subcommands; still no call site until P6h.**
   **The measurement is the finding.** `js/inspect/status.mjs` had said since P5d that "the ~111
   lines of TUI taxonomy" were P7's and not ported. `LAW_CLASS`, `SKILL_CLASS`,
@@ -858,7 +858,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   cell whose target does not exist proves nothing.** Closed by seeding files that ARE there
   and naming, in each cell, the content that must not come back.
 - **The Docs pages cross for 57 of 59, and the two that do not are declared rather than
-  discovered.** [`js/web/docs.mjs`](js/web/docs.mjs) answers `/api/docs` and
+  discovered.** [`js/web/docs.mjs`](../js/web/docs.mjs) answers `/api/docs` and
   `/api/docs/page/<id>` for the `markdown`, `concept` and `glossary` kinds — the harness-
   block stripping, the slug rules, the section slicing, the live-count substitution and the
   theme-aware glossary. **Still fifteen subcommands.** The measurement that scoped it is
@@ -878,7 +878,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   Python's `\s` on a `str` pattern is not JavaScript's, and the standing note read "differs
   only at U+FEFF". Measured: `python \s = js \s − U+FEFF + U+001C..U+001F + U+0085`. A
   heading carrying an information separator slugged differently on each side. `PY_SPACE`
-  in [`js/lib/fs.mjs`](js/lib/fs.mjs) is the measured set, and no cell could have found
+  in [`js/lib/fs.mjs`](../js/lib/fs.mjs) is the measured set, and no cell could have found
   it — nobody has written that heading.
   **Twelve mutations, eleven fire, six of them on the corpus rather than a cell** — which
   is what "a corpus phase" means in practice. The survivor is honest: dropping a blank
@@ -886,8 +886,8 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   the empty string and a missing value reach the same fallback. Indistinguishable through
   its one consumer, not unreachable, and kept for the reason the POST body drain was.
 - **The capability graph and the live-activity surface cross, and the spawn the plan warned
-  about was never there.** [`js/web/graph.mjs`](js/web/graph.mjs) and
-  [`js/web/activity.mjs`](js/web/activity.mjs) answer `/api/graph`, `/api/activity` (GET)
+  about was never there.** `js/web/graph.mjs` and
+  [`js/web/activity.mjs`](../js/web/activity.mjs) answer `/api/graph`, `/api/activity` (GET)
   and `/api/activity/<sid>` — **22 of 29 web paths, still fifteen subcommands.** The plan
   scored the pid probe as a `tasklist` spawn needing a sixth allow-list row; the source is
   `ctypes` over `OpenProcess`, so **neither implementation spawns anything** and
@@ -912,7 +912,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   **Eighteen mutations, eighteen fire, no survivors** — two of them visible only in the file
   snapshot, because the response body is byte-identical with the unlink removed.
 - **The web console starts WRITING, and the argv-in-a-response-body trap had a false
-  premise.** [`js/web/actions.mjs`](js/web/actions.mjs) and [`js/hosts/mcp.mjs`](js/hosts/mcp.mjs) answer
+  premise.** [`js/web/actions.mjs`](../js/web/actions.mjs) and [`js/hosts/mcp.mjs`](../js/hosts/mcp.mjs) answer
   the eight mutating POSTs that own their own path plus the `/api/rules` and `/api/mcp` GETs
   that had to cross with them — **27 of 29 web paths, still fifteen subcommands.** The plan
   called `api_install_cmd`'s `{"cmd": [sys.executable, "build.py", …]}` "a Python argv, as
@@ -941,7 +941,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   not be closed by any cell, so the 409 column itself became the thing under test, read out of
   the reference by `ast` and compared against the table `doPost` dispatches on.
 - **The console runs BACKGROUND JOBS, and the port's one sanctioned spawn is argued rather
-  than assumed.** [`js/web/jobs.mjs`](js/web/jobs.mjs) answers the last two web paths —
+  than assumed.** [`js/web/jobs.mjs`](../js/web/jobs.mjs) answers the last two web paths —
   **29 of 29, still fifteen subcommands** — and it is the only module in the port allowed to
   start a copy of *this program*. **Isolation is the discriminator and it is a property of the
   RUNTIME, not of the verb**: the reference's daemon is threaded, Node's server is
@@ -975,7 +975,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   get one writes a file whose NAME carries a clock. **A destamp that only reaches inside files
   leaves the filename as an ungateable axis.**
 - **The `web` VERB crosses — sixteen of 24 subcommands — and the TEARDOWN decided which cells
-  exist.** [`js/web/server.mjs`](js/web/server.mjs) grows the daemon lifecycle in one file, as
+  exist.** [`js/web/server.mjs`](../js/web/server.mjs) grows the daemon lifecycle in one file, as
   the reference keeps it: `_probe`, `_live_daemon`, `_spawn_detached`, `start|stop|status|
   restart`, `_build_plan`'s consumer, `_npm_build`, the browser open, `cmd_web`, and the last
   POST — `/api/restart`. `bin/geneseed-cli.mjs` finally imports the web tree, which is what
@@ -1009,7 +1009,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   every non-interactive run; the reference's `input()` raises there. The byte reader now
   reports that case as null, gated by a stdin-seeded corpus.
 - **The install TOGGLE crosses and the web console is whole — 29 of 29 paths ANSWER, still
-  sixteen subcommands.** [`js/maintain/uninstall.mjs`](js/maintain/uninstall.mjs) gains the reversible half it was
+  sixteen subcommands.** [`js/maintain/uninstall.mjs`](../js/maintain/uninstall.mjs) gains the reversible half it was
   written expecting: deactivate MOVES every owned artifact into a sibling stash and drops the
   wiring, reactivate moves the same bytes back, and the stash directory's PRESENCE is the
   disabled flag — no recorded state that could drift from the filesystem. `/api/pick-folder` is
@@ -1038,7 +1038,7 @@ pointer whatever the prose around it says. Dead **prose paths** are left as writ
   default the hook shim's runner and entry, so the Claude reactivate answered with that refusal
   on its first Node run instead of quietly wiring hooks at an invented path.
 - **`upgrade` crosses — seventeen of 24 — and the phase's real work was a fixture that could
-  WRITE.** [`js/maintain/update.mjs`](js/maintain/update.mjs) is `rituals/_update.py`'s upgrade half: the
+  WRITE.** [`js/maintain/update.mjs`](../js/maintain/update.mjs) is `rituals/_update.py`'s upgrade half: the
   preflight, the streamed fetch, the four upstream classifications, the fast-forward, the
   doctor gate with its exact rollback, and the two rebuilds. Every other verb in this port
   READS the checkout; this one rewrites it, so its cells needed a git repository they could

package/docs/extending.md

@@ -32,7 +32,7 @@ Three seams, and almost every question about "where do I edit?" resolves to one
 Two rules follow from the table and they cause most of the surprises:
 
 - **Nothing propagates by itself.** A bundle is a *render*. Editing `src/` changes nothing on any
-  machine until something re-emits (`js/build/emit.mjs:362` re-fingerprints, `js/inspect/status.mjs:80`
+  machine until something re-emits (`sourceFingerprint` in `js/build/version.mjs` re-fingerprints, `js/inspect/status.mjs`
   reports the drift).
 - **`docs/web/` is data, `web/src/` is code.** A new documentation page is one file and no
   rebuild. A new screen is a new hashed chunk and a mandatory `web/dist` commit.
@@ -58,10 +58,10 @@ badge keys `agents`/`skills`/`laws`/`themes`/`plugins`; `proseMirrorProblems` ho
 
 ---
 
-## 1 — The baseline, and the five commands that reproduce CI
+## 1 — The baseline, and the seven commands that reproduce CI
 
-Verified on this checkout: `doctor --all` green on 14 themes; the Node suite reports
-**1033 tests, 1029 pass, 4 skipped, 0 fail**.
+The baseline is whatever these commands report on your checkout — run them; no count is
+written here, because a typed count is stale by the next commit.
 
 CI is **four jobs expanding to six runs** (`.github/workflows/ci.yml`): `validate` and
 `node-cells` on Linux *and* Windows, plus `package-no-python` and `web` on Linux. From the repo
@@ -83,6 +83,10 @@ node tests/golden.mjs --idempotent
 node tests/golden.mjs --deletion
 ```
 
+```bash
+node tests/golden.mjs --cli
+```
+
 ```bash
 node tests/mutate.mjs --verify
 ```
@@ -100,6 +104,11 @@ Notes that matter:
 - `--test-reporter=tap` is not decoration. Both workflows gate on the *count* (`# tests N ≥ 500`)
   because `node --test` over a glob that matches nothing prints `# tests 0` and **exits 0**. Node's
   default reporter changed between majors, which is how a green 1043-test suite once reported zero.
+- `--cli` runs the ~320-cell CLI/hook matrix against the expectations written in each cell —
+  the only end-to-end gate on what a verb prints. CI runs it in `node-cells` on both platforms.
+  A cell that needs a broken checkout plants its fault as an **edit of the real file**
+  (`{ "edit": [[find, replace]] }` in `tests/helpers/matrix/cli.*.json`), never as a copy of it;
+  a `find` that stops matching exactly once fails the cell loudly.
 - `--deletion` is the only thing that exercises the write-before-delete prune. Anyone renaming or
   removing a plugin, a skill or an emitted file needs it.
 - **A local pass is weaker than CI.** ~18 tests in `tests/unit/package_manifest.test.mjs` carry
@@ -107,12 +116,12 @@ Notes that matter:
   on PATH they report *skipped* and the run is green.
 - CI additionally re-runs the packaging suite under `npm@latest` (Linux, last in the job) and
   packs the tarball into a `node:22-slim` container with no interpreter. Neither is reproducible
-  from the five commands; the container one is reachable locally through
+  from the seven commands; the container one is reachable locally through
   `tests/helpers/no-python-container.sh` with a docker daemon.
 - **Two assertions in `tests/unit/claude.test.mjs` silently stand down** on any machine where an
   ancestor of the temp sandbox is a `.claude`/`.bob` install — which is every developer machine
   with Claude Code installed under `~`. They are replaced by a `t.diagnostic`, so the TAP
-  `# skipped` count does **not** move. Locally you read `1035/1031/0/4` and see no sign of it.
+  `# skipped` count does **not** move, and a local run shows no sign of it.
 
 ### The gates CI does not run
 
@@ -162,11 +171,15 @@ 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.
+Five files, plus the written-out rule totals in four test files. 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/inspect/doctor.mjs`) sit on this: the pack named in
+   the body, wrapped in a `LEAN` block with **both halves authored** — the heading stays outside the
+   block, the full text goes in `LEAN:begin`, and the lean half is the rule *and its mechanism*, no
+   maxims (the style rule is in `src/doctrines/README.md`, and `leanBlockProblems` refuses a rule
+   with no block or an empty half). Two gates in `constitutionProblems`
+   (`js/inspect/checks-authoring.mjs`) sit on this too: 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
@@ -198,9 +211,18 @@ on purpose so that the invariant slot stays scarce.
 
 - **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
+- **No count in the product.** 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.
+- **No renumber risk.** But there *are* written-out rule totals to bump — expected values are
+  written out, never recorded — in `tests/unit/emit_smoke.test.mjs`, `harness.test.mjs`,
+  `setup.test.mjs` and `web_api.test.mjs`. Each fails loudly with the new count; change the
+  number *and* the comment that explains it. A rule in **craft** moves more: `setup` and
+  `web_api` also pin the craft-only narrowed counts, `generate.test.mjs` excludes every craft
+  rule by address to empty the pack, and `harness.test.mjs`'s contiguity fixture plants a rule at
+  the first free craft id — the doctrine twin of §2c step 8. Grep `tests/` for the previous
+  rule's address before trusting this list. A rule long enough to matter can also breach the
+  `full` carrier ceiling in `emit_smoke` — raise it with a dated note there, as every earlier
+  move did.
 
 ⚠ **Cite only downward.** An always-on tier may never reference a toggleable one:
 `constitutionProblems` refuses a `{{DOCTRINE}}` token anywhere under `src/ontology/` or
@@ -217,10 +239,9 @@ Steps 1 and 9 of §2c, plus `LAW_META` if the Principle line moved. Two cautions
 
 - `--footprint` defaults to **lean**, and a law's lean text is the authored `LEAN:else` half of
   its block in `src/laws/universal.md` (`resolveLean` in `js/build/render.mjs`). Amend **both**
-  halves, or the amendment does not exist for most installs. A doctrine rule is different: it is
-  still machine-cut to its heading plus first sentence (`terseBlocks`), so a clause in its second
-  paragraph is invisible in the default build. The on-disk `laws/` and `ontology/` copies always
-  render at full, whatever the footprint.
+  halves, or the amendment does not exist for most installs — and a doctrine rule is no different,
+  since its rules got the same block. The on-disk `laws/`, `ontology/` and `doctrines/` copies
+  always render at full, whatever the footprint.
 
 ### 2c — Adding an INVARIANT
 
@@ -232,7 +253,7 @@ the bar is in `DESIGN.md` Decision 7, and most candidates belong in a doctrine p
    citations in `js/hosts/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
+   `constitutionProblems` holds `LEX_I..LEX_XI` 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.
@@ -245,7 +266,7 @@ the bar is in `DESIGN.md` Decision 7, and most candidates belong in a doctrine p
 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
+   the *first free numeral*, which is `XII` now that the invariants are I..XI. 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`).
 
@@ -256,9 +277,9 @@ error — the heading simply stops matching and the whole tier parses to nothing
 
 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
+(half the ceiling) on the rendered size. Its docblock carries the current measurement against
+the largest carrier — the host-agnostic `files` bundle; no figure is repeated here, because a
+typed headroom is stale by the next rule. 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.
 
@@ -284,7 +305,7 @@ Rare, and mechanical. On top of §2a for each rule the pack carries:
 
 ## 3 — Adding a SKILL or an AGENT
 
-**Order matters at the first two steps.** `missingReferencedSpecs` (in `js/build/emit.mjs`) *aborts the
+**Order matters at the first two steps.** `missingReferencedSpecs` (in `js/build/bundle.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.
@@ -308,6 +329,10 @@ emit leaves the prior install intact.
    `·`-separated name in the 🛠 row (that enumeration is gated two ways, unlike the laws' one).
 7. `SHIPPED.md` — the `N laws, N agents, N skills` triple.
 8. `doctor --all`, then the suite.
+9. **Skills only, and optional** — cases in `tests/fixtures/skill_triggers.json` (positives *and*
+   near-miss negatives), then `node tests/skill_triggers.mjs --only <name>`. It is the one check
+   that asks a real model whether the description routes: every gate above passes a skill that
+   never fires. Hand-run, spends model calls on your own login, not part of the suite.
 
 **A vendored skill folder** (`src/skills/<name>/SKILL.md`) is a different shape: add it to
 `VENDORED_SKILL_DIRS` (`js/hosts/native.mjs:37` — the literal is frozen in
@@ -537,7 +562,7 @@ only, at best, on its presence.
 |---|---|---|
 | `§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 |
-| 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 |
+| 588 themed constitution titles (42 keys × 14 voices) — `LEX_I..LEX_XI` (11), `DOC_<PACK>_<n>` (27), `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 |
@@ -545,7 +570,7 @@ only, at best, on its presence.
 | `LOADED_SIGIL` uniqueness | `themes/*.json` | nothing, and it is load-bearing for theme detection |
 | `adapters/claude-code/settings.json` | — | nothing compares it to what the emitter writes; **it is already divergent** |
 | `NATIVE`, twice | two test files | they check each other, which is the gate that makes the duplication safe |
-| The emit-size `CEILING` | `tests/unit/emit_smoke.test.mjs:54` | a hand-transcribed measurement |
+| The emit-size `CEILING` | `tests/unit/emit_smoke.test.mjs` (`const CEILING`) | a hand-transcribed measurement |
 | Stale docblock counts | `js/build/themes.mjs:62` ("137 values" → 140), `js/build/render.mjs:116` ("145 tokens" → 148) | nothing |
 
 ---
@@ -624,7 +649,7 @@ gated. Every other appearance is derived at runtime (`.geneseed-version` markers
 why no test pins a version string and none should.
 
 Do not run `npm version`. Bump the two files by hand, add the `CHANGELOG` section, update
-`SHIPPED.md`, rebuild `web/dist` if `web/src` moved, run the five commands from §1, push, tag,
+`SHIPPED.md`, rebuild `web/dist` if `web/src` moved, run the seven commands from §1, push, tag,
 then rehearse and fire the workflow:
 
 ```bash