geneseed 3.13.0 → 3.15.0

package/bin/geneseed-cli.mjs

@@ -8,7 +8,8 @@
  * specific.
  *
  *   * GROWING `bin/geneseed-hook.mjs` weakens the gate the design now rests on.
- *     `test_the_entry_carries_exactly_the_verbs_the_emitter_wires` asserts EQUALITY between
+ *     'the hook entry carries exactly the verbs the emitter wires' (`tests/unit/hook_cli.test.mjs`)
+ *     asserts EQUALITY between
  *     that file's table and the hooks `js/hosts/settings.mjs` wires, and P5b made it load-bearing:
  *     the shim is machine-wide (`~/.geneseed/bin/geneseed-hook[.cmd]`, no per-install
  *     component) and last-writer-wins, so a Node emit owns the hooks of installs Python
@@ -23,23 +24,24 @@
  *     no-op and a success are one observation.
  *   * `bin/build-driver.mjs` IS `build.py`'s `main()` — a different Python program from
  *     `rituals/harness.py`, not a different half of the same one. It parses generator FLAGS
- *     with a partition asserted over them (`test_the_node_driver_classifies_every_emit`),
- *     `tests/golden.py` drives it 259 times per run, and it is under a hard `child_process`
+ *     with a partition asserted over them ('the driver classifies every emit',
+ *     `tests/unit/node_driver.test.mjs`),
+ *     `tests/golden.mjs` drives it over every emit configuration, and it is under a hard `child_process`
  *     ban that is half the proof it is not a passthrough. `exclude` spawns nothing and would
  *     not have broken that ban — but `web`, `upgrade` and `setup` will, and the ban should
  *     outlive them rather than be dismantled by the first verb that does not need it.
  *
  * What this costs is what the P5b handoff predicted: a second acceptance matrix. It is paid
- * in `tests/harness_golden.py`, which now carries a `bin` per cell and takes `--new-cli`
- * beside `--new` — and it would have been paid identically by the `bin/build-driver.mjs` option,
+ * in `tests/golden.mjs --cli` (`tests/helpers/matrix/cli.<platform>.json`), which carries a
+ * `bin` per cell — and it would have been paid identically by the `bin/build-driver.mjs` option,
  * so it is not a discriminator between the two.
  *
  * THE VERB SET REFUSES THE REST BY NAME, exactly as the hook entry does. It carries 22 of the
  * 26 names the reference's parser answered to (25 subparsers, plus the alias) — the other
  * four are the hook verbs — and, since the three rows at the end of the table below, three
- * that the reference never had at all. `test_the_two_entry_points_carry_disjoint_verb_sets`
- * keeps the two tables from ever answering the same verb twice, since the shim bakes only one
- * of them.
+ * that the reference never had at all. 'the two entry points carry disjoint verb sets'
+ * (`tests/unit/hook_cli.test.mjs`) keeps the two tables from ever answering the same verb
+ * twice, since the shim bakes only one of them.
  *
  * P6h MADE THE DISPATCH ASYNCHRONOUS and put `js/web/` on this entry's import graph — LAZILY,
  * since the slim pass: every command module loads through its verb's thunk, so the graph is
@@ -58,7 +60,7 @@
 import '../js/lib/node-floor.mjs';
 import { cliSpec, printHelp, printVerbList } from '../js/ui/cli.mjs';
 import { parseIntStrict } from '../js/lib/text.mjs';
-import { printErr } from '../js/lib/fs.mjs';
+import { printErr, printOut } from '../js/lib/fs.mjs';
 
 /**
  * The verbs this entry answers — and, since P10c, NOTHING ELSE ABOUT THEM.
@@ -73,9 +75,9 @@ import { printErr } from '../js/lib/fs.mjs';
  * hold: the FUNCTION.
  *
  * IT IS STILL A TABLE and still the DISPATCH rather than a declaration beside one.
- * `tests/test_hook_cli_parity.py` scrapes `const VERBS = {` for its three matrix gates, and
- * `main`'s refusal lists `Object.keys(VERBS)` IN THIS ORDER, which `harness_golden` cells
- * assert verbatim — the order is the old table's and is not alphabetical.
+ * `tests/unit/hook_cli.test.mjs` scrapes `const VERBS = {` for its matrix gates, and
+ * `main`'s refusal lists `Object.keys(VERBS)` IN THIS ORDER (no cell asserts the list
+ * verbatim any more) — the order is the old table's and is not alphabetical.
  *
  * FLATTENED TO `verb: fn` since Task 5, AND TO `verb: loader` since the lazy pass: every row
  * is now a thunk that imports the command's module and resolves to its function, so the one
@@ -104,9 +106,9 @@ const VERBS = {
   // `up.add_parser(..., aliases=["update"])`, reproduced in P8c as a ROW OF ITS OWN rather than
   // as an `aliases` field on the row above — because a field would be a DECLARATION and the
   // three matrix gates read this table as the DISPATCH (rule 7, and M23 is where it was
-  // learned). As a key it is a real verb: `test_every_entry_verb_is_a_real_harness_subcommand`
-  // reads argparse's aliases out of `harness.py` and finds it, and
-  // `test_the_matrix_covers_every_verb_it_claims` demands the `update/` cell group that proves
+  // learned). As a key it is a real verb: `tests/unit/hook_cli.test.mjs`'s 'every entry verb
+  // is a command the driver table dispatches' finds it in `js/cli-table.json`, and 'the matrix
+  // covers every verb each entry claims' demands the `update/` cell group that proves
   // it reaches `cmdUpgrade` — including the theme re-read, which is what separates it from
   // `sync-self`.
   //
@@ -129,8 +131,8 @@ const VERBS = {
   // exit code, and that arm crosses byte for byte. The panel behind it is P7c's;
   // `js/ui/tui.mjs`'s header argues why this entry falls back to `cmd_tui`'s own
   // panel-unavailable line rather than inventing a second full-screen UI, and
-  // `tests/test_tui_boundary.py` asserts that the arm it declares is genuinely unreachable
-  // here rather than merely untested.
+  // `tests/unit/no_panel.test.mjs` asserts that no panel lies behind it — the module paints
+  // nothing and refuses on a TTY too — rather than leaving that merely untested.
   tui: () => import('../js/ui/tui.mjs').then((m) => m.cmdTui),
   // THE THREE THAT NEVER HAD A PYTHON ORIGINAL, and they are last for that reason rather
   // than by alphabet: every row above is the twin of a subparser, and these three are not.
@@ -143,9 +145,9 @@ const VERBS = {
   // this change rather than after it. The recorded help corpus was rendered from a live
   // argparse object, and there was no subparser to render these from; the acceptance matrix
   // is a comparison of two implementations, and there is only one. So their gates are
-  // ABSOLUTE — `tests/snapshot/cli_help.test.mjs` splits the two populations by name and refuses a
-  // verb that falls into neither, and each has its own unit gate stating what it does rather
-  // than that it agrees.
+  // ABSOLUTE — `tests/unit/hook_cli.test.mjs`'s `NATIVE` list splits the two populations by
+  // name and refuses a verb that falls into neither, and each has its own unit gate stating
+  // what it does rather than that it agrees.
   catalog: () => import('../js/build/catalog.mjs').then((m) => m.cmdCatalog),
   mcp: () => import('../js/hosts/mcp.mjs').then((m) => m.cmdMcp),
   memory: () => import('../js/maintain/memory.mjs').then((m) => m.cmdMemory),
@@ -173,7 +175,7 @@ function die(code, msg) {
  *
  * The WORDING of an argparse failure is deliberately not reproduced — argparse prints a
  * usage block computed from the whole parser tree, and P5a set the precedent for the hook
- * entry: state the fault plainly, gate it absolutely in `test_hook_cli_parity.py`, and keep
+ * entry: state the fault plainly, gate it absolutely in `tests/unit/hook_cli.test.mjs`, and keep
  * it out of the compared matrix. What IS compared is every error the command's own body
  * raises, `exclude`'s missing-path refusal among them.
  */
@@ -302,7 +304,7 @@ async function main(argv) {
   // that binary is never reached, and its import graph is paid on every tool call.
   if (process.env.GENESEED_NO_SHIM_CHECK !== '1' && verb !== 'help'
     && !argv.some((t) => t === '-h' || t === '--help')) {
-    const { shimDead } = await import('../js/hosts/settings.mjs');
+    const { shimDead } = await import('../js/hosts/shim.mjs');
     const dead = shimDead();
     if (dead.length) {
       printErr(`[geneseed] ⚠ hooks are off on this machine: the hook shim points at `
@@ -311,25 +313,21 @@ async function main(argv) {
     }
   }
   // `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
-  // property of the gates rather than a preference:
-  //
-  //   * `VERBS` is asserted to be the twin of `rituals/harness.py`'s SUBPARSERS
-  //     (`test_every_entry_verb_is_a_real_harness_subcommand`), and `--validate-only` is a
-  //     GENERATOR flag — `harness.py` has never had a `validate` subcommand to be a twin of;
-  //   * `test_the_matrix_covers_every_verb_it_claims` demands a recorded cell group per table
-  //     row, and a cell has an `lf` half this host cannot produce.
-  //
-  // So a row would have meant amending two gates and recording a corpus half blind. It takes
-  // the generator's own parser (see `parseDriverArgs`) because its flags are the generator's,
+  // in the table above. It is dispatched here, before the lookup, because its flags are the
+  // GENERATOR's, not a table row's: it takes the generator's own parser (see `parseDriverArgs`),
   // and it is on THIS binary — not on `bin/build-driver.mjs` — because it runs the doctor, which
   // starts a process the driver is banned from reaching.
   if (verb === 'validate') {
     // 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([
+    const [{ cmdValidate, VALIDATE_USAGE }, { parseDriverArgs }] = await Promise.all([
       import('../js/inspect/validate.mjs'), import('../js/build/driver.mjs'),
     ]);
+    // Before the borrowed parser, whose own `-h` prints the GENERATOR's usage.
+    if (argv.slice(1).some((t) => t === '-h' || t === '--help')) {
+      printOut(VALIDATE_USAGE);
+      return 0;
+    }
     try {
       return cmdValidate(parseDriverArgs(argv.slice(1)));
     } catch (e) {

package/bin/geneseed-hook.mjs

@@ -7,7 +7,8 @@
  * and each alone would be enough:
  *
  *   * The generator driver is under a hard `child_process` ban
- *     (`test_the_driver_imports_no_child_process_module`), which is half of the proof that
+ *     (`tests/unit/hook_cli.test.mjs`'s 'the generator driver still reaches no child-process
+ *     module'), which is half of the proof that
  *     it is a real implementation rather than a passthrough to `build.py`. `learn` MUST
  *     spawn — the whole verb is "hand these notes to whatever `$GENESEED_LLM` names".
  *     Putting it in that file means either breaking the gate or weakening it.
@@ -15,7 +16,8 @@
  *     the Python side; a Node twin needs its own, invoked as `<node> <this> context
  *     --root "<cfg>"`.
  *   * `bin/build-driver.mjs` parses generator FLAGS (`--emit`, `--theme`, `--footprint`), and
- *     `test_the_node_driver_classifies_every_emit` asserts a partition over them. Verbs
+ *     'the driver classifies every emit' (`tests/unit/node_driver.test.mjs`) asserts a
+ *     partition over them. Verbs
  *     are a different shape and would sit awkwardly inside that.
  *
  * WHAT BAKES THIS FILE, SINCE P5b. `bin/build-driver.mjs` writes `<node> <checkout>/bin/
@@ -27,9 +29,10 @@
  * component — so the last driver to emit anything on a machine owns every install's hooks,
  * including installs the other driver wrote. That is safe exactly while the two entry
  * points answer the same verbs identically, which is not a hope:
- * `test_the_entry_carries_exactly_the_verbs_the_emitter_wires` pins the verb set to the
- * hooks the emitter wires, and `tests/harness_golden.py` runs this binary as a process
- * against the Python one on stdout, stderr, exit code and every file written.
+ * `tests/unit/hook_cli.test.mjs`'s "the hook entry carries exactly the verbs the emitter wires"
+ * pins the verb set to the hooks the emitter wires, and `node tests/golden.mjs --cli` runs
+ * this binary as a process with absolute assertions on stdout, stderr, exit code and every file
+ * written.
  *
  * The verb set is deliberately SMALL and refuses the rest by name. `harness.py` has 24
  * subparsers (25 invocable names — `update` is an alias of `upgrade`); a hook entry that
@@ -39,22 +42,29 @@
  */
 // FIRST, before anything it could fail to run: an old Node gets one sentence, not a stack trace.
 import '../js/lib/node-floor.mjs';
-import { cmdContext, cmdGitGate, cmdRuleGate, cmdToolGate, cmdLearn } from '../js/hosts/hooks.mjs';
-// Not a new module on the hot path: `js/hosts/hooks.mjs` above already imports
-// `js/lib/fs.mjs`, so this edge names a file the process has already loaded.
+// Not a new module on the hot path: every verb's module imports `js/lib/fs.mjs` too, so this
+// edge only loads early a file the process would load anyway.
 import { printErr } from '../js/lib/fs.mjs';
 
 // `--host` selects the verdict dialect (see js/hosts/hooks.mjs's header); the emitter bakes
 // it into the command for every host that is not Claude Code, so the hook never has to guess
 // its reader from the payload's shape.
+//
+// `load` is a DYNAMIC import per verb, so a process parses only its own verb's module: the gates
+// run on every tool call and must not pay for `context`'s discovery or `learn`'s spawn. The
+// specifiers stay literal strings — `tests/unit/hook_cli.test.mjs`'s import walk reads them.
 const HOSTED = { '--root': 'root', '--host': 'host' };
+const gates = () => import('../js/hosts/hooks.mjs');
 const VERBS = {
-  context: { fn: cmdContext, flags: HOSTED },
-  'git-gate': { fn: cmdGitGate, flags: HOSTED, switches: { '--no-consent': 'noConsent' } },
-  'rule-gate': { fn: cmdRuleGate, flags: HOSTED },
-  'tool-gate': { fn: cmdToolGate, flags: HOSTED },
+  context: { load: () => import('../js/hosts/hooks-context.mjs'), fn: 'cmdContext', flags: HOSTED },
+  'git-gate': {
+    load: gates, fn: 'cmdGitGate', flags: HOSTED, switches: { '--no-consent': 'noConsent' },
+  },
+  'rule-gate': { load: gates, fn: 'cmdRuleGate', flags: HOSTED },
+  'tool-gate': { load: gates, fn: 'cmdToolGate', flags: HOSTED },
   learn: {
-    fn: cmdLearn,
+    load: () => import('../js/hosts/hooks-learn.mjs'),
+    fn: 'cmdLearn',
     flags: { '--memory': 'memory' },
     switches: { '--consolidate': 'consolidate' },
     positional: 'file',
@@ -62,7 +72,7 @@ const VERBS = {
 };
 
 function die(code, msg) {
-  // CRLF on Windows, for the same reason `js/hosts/hooks.mjs`'s funnels translate: argparse
+  // CRLF on Windows, for the same reason the hook verbs' funnels translate: argparse
   // writes this line through `sys.stderr`, which does. `printErr` owns the `\n`-to-`os.linesep` rule.
   printErr(`geneseed-hook: error: ${msg}\n`);
   return code;
@@ -115,7 +125,8 @@ async function main(argv) {
   if (!spec) {
     // "elsewhere", not a file name: naming `bin/geneseed-cli.mjs` here would mean this entry
     // carrying a copy of its sibling's verb table — the one thing
-    // `test_the_two_entry_points_carry_disjoint_verb_sets` exists to keep from happening.
+    // 'the two entry points carry disjoint verb sets' (`tests/unit/hook_cli.test.mjs`) exists to
+    // keep from happening.
     // The COMMAND is not a table: `geneseed` is this package's `bin` entry for the CLI
     // (package.json), it answers every non-hook verb, and it survives the deletion of the
     // interpreter-plus-script invocation this line used to print.
@@ -128,8 +139,7 @@ async function main(argv) {
   // argument. The four hook verbs are four of the reference's 26 and had the same gap.
   // `js/ui/cli.mjs` is imported HERE, not at the top: a static import cost every tool call
   // of every session a module parse (~3 ms of an ~12 ms controllable budget) for a branch
-  // only a human at a terminal ever takes. The hook path never awaits it, so `main` staying
-  // async-shaped costs the hot verbs nothing.
+  // only a human at a terminal ever takes.
   if (argv.slice(1).some((t) => t === '-h' || t === '--help')) {
     const { printHelp } = await import('../js/ui/cli.mjs');
     const rc = printHelp('geneseed-hook', verb);
@@ -137,7 +147,7 @@ async function main(argv) {
   }
   const parsed = parse(spec, argv.slice(1));
   if (parsed.error) return die(2, parsed.error);
-  return spec.fn(parsed.args);
+  return (await spec.load())[spec.fn](parsed.args);
 }
 
 main(process.argv.slice(2)).then((code) => { process.exitCode = code; });

package/docs/extending.md

@@ -336,7 +336,7 @@ render — no citation moves, because none names a number. Then:
 3. Its `LEX_<ID>`/`DOC_<ID>` key in all fifteen theme files (the equality arm names each).
 4. The number-keyed tables, which the doctor checks against the canon: `LAW_CLASS`
    (`js/inspect/inventory.mjs`), `LAW_META`/`DOCTRINE_META` (their id pins fail on every shifted
-   row), and — only if a hook-gated rule moved — `HOOK_PINNED` in `checks-authoring.mjs` names the
+   row), and — only if a hook-gated rule moved — `HOOK_PINNED` in `checks-constitution.mjs` names the
    ledger keys, `CONSENT_RULE` and `HOOK_GATED` to move with it. `--exclude-rules` addresses are
    `<pack>.<n>` too, and an install that excluded a shifted doctrine rule excludes its neighbour
    after a re-emit: prefer appending in a pack, and say so in the CHANGELOG when you cannot.
@@ -391,9 +391,10 @@ Two traps worth knowing before you write the spec:
   re-opens bash on all three hosts (OpenCode gates it to `ask`), and `<!-- webfetch: allow -->`
   re-opens web fetch — the researcher is the one spec that carries it.
 - **The console has a fourth, ungated copy of the skill taxonomy.** `SKILL_CATS` in
-  `web/src/pages/Skills.jsx:19` mirrors `SKILL_CLASS` with nothing comparing them (contrast
+  `web/src/lib/lawCats.js` mirrors `SKILL_CLASS` with nothing comparing them (contrast
   `LAW_META`, which *is* cross-checked). Inventing a new *category* means editing that file —
-  which drags in the `web/dist` rebuild — and an unknown category renders as Build with no warning.
+  which drags in the `web/dist` rebuild — and an unknown category lands under Personal in the
+  Library (`splitSkills` in `web/src/pages/Library.jsx`) with no warning.
 
 
 ---
@@ -462,8 +463,7 @@ throws). The same file is what GitHub shows, so write for both
   passage for several hosts lists them, `<!--harness:claude,openclaude-->`, labelled
   `*(Claude Code and OpenClaude only)*` (names in the marker's order, joined by *and*).
 - No `{N_*}` token in `understand/` or `guides/` — GitHub would show it raw.
-- `kind: "markdown"` pulls from a repo file via `source:`, traversal-guarded, optionally sliced to
-  one section with `anchor:` + `slice: true`.
+- `kind: "markdown"` pulls from a repo file via `source:`, traversal-guarded.
 
 Inline `<!-- harness:claude -->` blocks strip per host and **fail open** on an unbalanced marker —
 the page renders, wrong, with nothing red.

package/harness.config.json

@@ -2,5 +2,5 @@
   "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
   "theme": "neutral",
   "product": "Geneseed",
-  "version": "3.13.0"
+  "version": "3.15.0"
 }

package/js/README.md

@@ -1,6 +1,6 @@
 # `js/` — the module map
 
-Sixty-one modules in eight folders. This page is the address book: **what each one owns**, and
+Sixty-six modules in eight folders. This page is the address book: **what each one owns**, and
 **which file to open first** for a given task. It is not documentation of behaviour — every module
 has a docblock for that, and the docblock is the thing to read before editing.
 
@@ -46,7 +46,8 @@ as a per-host install at project or global scope.
 | `emit-common.mjs` | Constants, tree walkers, and the three writers BOTH global emits share. Decides no host |
 | `stubs.mjs` | Write-once seed files: context, wiki, rules, excludes, profile, `.gitignore`, memory/notebook indexes |
 | `version.mjs` | The release marker: fingerprint the sources, read/compare/write an install's version, warn on downgrade |
-| `driver.mjs` | The generator driver: `--emit`/`--theme`/`--footprint` flag parsing, the nine emit targets, per-host emit orchestration, the prune and the manifest. `bin/build-driver.mjs` is only its entry |
+| `driver.mjs` | The generator driver: the nine emit targets, per-host emit orchestration, the prune and the manifest. `bin/build-driver.mjs` is only its entry |
+| `args.mjs` | The generator's flag surface: `harness.config.json` defaults, the `--emit`/`--theme`/`--footprint` parse tables and choices, `-h`, and `die` (a throw, so `rebuild-all` survives one bad install) |
 | `generate.mjs` | CLI verbs `build`, `prompt`, `theme`, `rebuild-all` — the thin face over `driver.mjs` |
 | `catalog.mjs` | `geneseed catalog` — prints the shipped roster. Classifies nothing itself |
 | `themes.mjs` | Maintainer-only `--sync-themes`: inserts `_TEMPLATE.json`'s missing keys into the committed themes |
@@ -67,19 +68,25 @@ user co-owns, and the hook verbs those emitted configs then run.
 
 | module | owns |
 |---|---|
-| `hosts.mjs` | The four host config dirs (opencode/claude/bob/openclaude), plus `resolvePath`/`expanduser` |
-| `hooks.mjs` | The verbs the emitted hooks run every session: `context`, `git-gate`, `rule-gate`, `tool-gate` (the two gates fused, for Bob), `learn`. `--host` picks the verdict dialect |
+| `hosts.mjs` | The four host config dirs (opencode/claude/bob/openclaude), their `family` (`CLAUDE_STYLE`), plus `resolvePath`/`expanduser` |
+| `hooks.mjs` | The gate verbs, run on every tool call: `git-gate`, `rule-gate`, `tool-gate` (the two gates fused, for Bob), plus `ask`/the gate ledger/`guardGate`. `--host` picks the verdict dialect |
+| `hooks-context.mjs` | The `context` verb — SessionStart: session files plus the repo's context docs |
+| `hooks-learn.mjs` | The `learn` verb — Stop/SubagentStop/PreCompact distiller; the hook path's ONE spawn (`$GENESEED_LLM`) |
+| `hooks-prims.mjs` | The Python path/text primitives the hook verbs share (`splitLines`, `readStdin`, a never-throwing `isFile`) |
+| `memory-files.mjs` | The memory store's file format — `frontmatter`, `MEMORY.md` index writes, agent lessons, consolidate. No spawn: the CLI and web console import it |
 | `gitref.mjs` | fs/path-only: `gitRootOf`, `gitDirOf`, `currentBranch`, `loopLaunched` — read straight off `.git`, never spawn git. Shared by `hooks.mjs`'s git-gate and `js/loop/cli.mjs`'s commit-message writer |
-| `settings.mjs` | Merges into user-owned `settings.json`/`opencode.json`; owns the hook shim and the managed blocks |
+| `settings.mjs` | Merges into user-owned `settings.json`/`opencode.json` (one `loadJsonObject` reader for all of them) and the managed blocks |
+| `shim.mjs` | The machine-wide hook shim: its path, body, liveness (`shimDead`, read on every CLI run), `hookPrefix`/`hookRunnerEntry`. Kept cheap to import |
 | `native.mjs` | Capability specs → host-native subagents and skills. The impure half of the emit |
 | `opencode.mjs` | OpenCode-only extras: colour themes, primary agent, `/commands`, plugins, overrides stub |
 | `installs.mjs` | Detects deployed installs and reads back their theme, footprint, posture, mode and loop trust preset |
 | `mcp.mjs` | MCP server presets, the per-host `mcpServers` config read/write, and toggle state |
 | `link.mjs` | `geneseed link`/`unlink` — the PATH shim, and the only Windows USER-Path registry edit |
 
-**Before editing:** `hooks.mjs` **is the hook path** — the verdict travels as JSON on stdout and
+**Before editing:** `hooks*.mjs` **are the hook path** — the verdict travels as JSON on stdout and
 every arm exits 0, so one stray printed byte turns a blocking gate silently permissive, and anything
-imported here is paid on every tool call. `hosts.mjs` is shared by the generator, the CLI and the
+`hooks.mjs` or `hooks-prims.mjs` imports is paid on every tool call. `bin/geneseed-hook.mjs` loads
+one verb's module per process, so keep context and learn code out of the gate module. `hosts.mjs` is shared by the generator, the CLI and the
 hook path, so it must stay free of `child_process`. `installs.mjs` reads through `readMaybe`, which
 folds CRLF — a bare `readFileSync` here is a bug.
 
@@ -92,8 +99,10 @@ Everything that inspects an already-built or already-deployed harness and report
 | `doctor.mjs` | The `geneseed doctor` **driver** only: picks themes, runs the checks, prints the verdict |
 | `checks-build.mjs` | Gates over what the build PRODUCED: links, tokens, theme parity, OpenCode colours, bundle drift |
 | `checks-repo.mjs` | Gates over the repo's own records: `registry.json`, committed secrets, the hook shim, vendored pins |
-| `checks-authoring.mjs` | Self-consistency: law/doctrine metadata, constitution numbering, the counts README and the web quote |
-| `scan.mjs` | The shared walk/sort/strip/test primitives all three `checks-*` use. Owns no judgement itself |
+| `checks-authoring.mjs` | `authoringProblems`, the aggregate self-consistency gate: spec purpose lines, the learn-prompt literal, `node --check` over the plugins (the doctor's one spawn), then the groups below |
+| `checks-constitution.mjs` | The constitution: rule declarations and citations, LEAN blocks, `HOOK_PINNED`, theme vocabulary, the console's `LAW_META`/`DOCTRINE_META` |
+| `checks-counts.mjs` | The hand-written counts: AGENT.md tables, README badges and prose, `SHIPPED.md`, held against `src/` |
+| `scan.mjs` | The shared walk/sort/strip/test primitives every `checks-*` uses. Owns no judgement itself |
 | `validate.mjs` | The `--validate-only` verb: renders a sandbox, scans it for tokens and dead links, own exit contract |
 | `inventory.mjs` | The one catalog walk and its taxonomy tables, read by status, the TUI and the web console |
 | `status.mjs` | `geneseed status` and `version` — the panel data, counts, accent colour, version verdict |
@@ -120,6 +129,7 @@ into files users have committed, so change the test that states it in the same c
 | `text.mjs` | String primitives: `codePointLength`, `WHITESPACE`, `parseIntStrict`, `percentDecode` |
 | `udiff.mjs` | `geneseed diff`'s own difflib clone — the alignment IS the printed hunks — plus `splitLines` |
 | `proc.mjs` | One constant: the `windowsHide` flag every spawn in `js/` must reuse |
+| `prompt.mjs` | The line-mode stdin readers — `ask`, `promptLine`, `confirm`, `askChoice` — read a byte at a time so they stop where Enter stops. Shared by `setup`, `uninstall` and `web` without dragging in the wizard |
 | `node-floor.mjs` | The first import of all three binaries: below Node 22.3, one sentence on stderr and exit 1 (0 in the hook) instead of a stack trace |
 
 **Before editing:** parse with `parseJson`, never `JSON.parse` — the latter collapses int `1` and
@@ -193,10 +203,13 @@ the deployed harness as JSON.
 | module | owns |
 |---|---|
 | `server.mjs` | `serve()`/`cmdWeb`: UI-build precheck, socket bind, token mint, daemon record wiring |
-| `routes.mjs` | Route DECLARATION only: the `POST_ROUTES` table and the ported/unported/declined sets |
-| `handler.mjs` | One function per request: dispatch, gzip, Host/CSRF guards, static SPA fallback |
-| `api.mjs` | `WebState` plus every GET read endpoint; owns `STATE_ROUTES`, `PREFIX_ROUTES`, `NotFound` |
-| `actions.mjs` | The mutating endpoints — rules, profile, memory, MCP, excludes — plus install/deploy argv |
+| `routes.mjs` | The route tables — `STATE_ROUTES`, `PREFIX_ROUTES`, `POST_ROUTES` (+ its 409 column) — and the inline lists |
+| `handler.mjs` | One function per request: dispatch, gzip, Host/CSRF guards and body cap (before the body is read), static SPA fallback |
+| `state.mjs` | `webState` — the resolved install view every endpoint reads, with its cached inventory and doctor |
+| `catalog.mjs` | The Library read model: inventory, constitution tiers, memory/notebook/wiki/config items, `apiCatalog`/`apiItem`, `NotFound` |
+| `api.mjs` | The dashboard and settings reads: overview, recent, themes, setup, doctor, diff, installs, excludes, loops |
+| `user-files.mjs` | The fingerprint-guarded editors for `user-rules.md` (incl. memory promotion) and `PROFILE.md`, read and write |
+| `actions.mjs` | The other mutating endpoints — memory delete, MCP, excludes, installs, view, restore — plus install/deploy argv |
 | `daemon.mjs` | Detached web start/stop/status/restart, the `.geneseed-web.json` record, and `openUrl` |
 | `jobs.mjs` | `JobManager` and the action→argv table. The only module here that spawns job children |
 | `docs.mjs` | The Docs tab: the `docs/<folder>/` page registry, `?harness=` filtering, link rewriting, the six page kinds |
@@ -220,7 +233,7 @@ and inline lists are held against a surface list written out in
 | a doctor check | `js/inspect/checks-{build,repo,authoring}.mjs` | register with `ran(...)` in `doctor.mjs`, then a PLANTED FAULT in `tests/unit/harness.test.mjs` |
 | a web endpoint | GET → `js/web/api.mjs`; POST → `js/web/actions.mjs` | declare it in `js/web/routes.mjs`; the partition test probes the real handler |
 | a CLI verb | `js/cli-table.json` — the table IS the parser | the `VERBS` row in `bin/geneseed-cli.mjs`, the row count in `cli_table.test.mjs`, `NATIVE` in **two** test files |
-| a hook verb | `js/hosts/hooks.mjs` | `claudeHookGroups` in `settings.mjs`, `VERBS` in `bin/geneseed-hook.mjs`. Keep the import graph tiny |
+| a hook verb | `js/hosts/hooks.mjs` (a gate) or its own `js/hosts/hooks-<verb>.mjs` | `claudeHookGroups` in `settings.mjs`, the `VERBS` row (with its `load`) in `bin/geneseed-hook.mjs`. Keep the import graph tiny |
 | a console doc page | `docs/<understand|guides|concepts|reference>/<id>.md` — the stem is the id | `docs/extending.md` §4c. Only `kind: "concept"` gets `{N_*}` substitution |
 | an OpenCode plugin | `adapters/opencode/plugins/geneseed-<name>.js` | `docs/extending.md` §4a — the `geneseed-` prefix is mechanically load-bearing |
-| to change a `js/lib/` primitive | `tests/fixtures/pure_probe.mjs` **first** | the docblock says which Node default it deliberately departs from — change that sentence too, or the next reader restores the default |
+| to change a `js/lib/` primitive | `tests/unit/lib_primitives.test.mjs` **first** | the docblock says which Node default it deliberately departs from — change that sentence too, or the next reader restores the default |