geneseed 3.13.0 → 3.14.0

package/CHANGELOG.md

@@ -8,6 +8,45 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [3.14.0] — 2026-10-04
+
+**Upgrading:** re-emit (`geneseed rebuild-all`) so installed hooks pick up the gate fixes and the
+per-verb hook modules; then `geneseed web restart`.
+
+### Security
+- **Sealed Secrets gate** — `sk-ant-` keys containing `_` (base64url, most real keys) no longer
+  slip past; `MultiEdit` (`edits[].new_string`) and `NotebookEdit` (`notebook_path`/`new_source`)
+  are now scanned like `Write`/`Edit`.
+- **Destructive-git gate** — catches `git push -f`, `git push origin +main`, `git reset -q --hard`
+  and `git clean -d -f` (flags anywhere after the verb); `LAW_IV_BASH` mirrors it.
+- **Memory names** — a model-written memory `name:` that is not a plain slug is refused instead
+  of becoming a path outside the memory dir (Claude `learn` hook and the OpenCode learn plugin).
+- **Uninstall** — manifest paths are contained to the install dir before unlinking (as deactivate
+  already did); empty-directory pruning stops at the base.
+
+### Fixed
+- `--exclude-rules` is carried through every re-render: `geneseed diff` no longer reports drift on
+  an install with excluded rules, console Restore and `geneseed migrate` no longer re-admit them,
+  and `validate` honours every render axis. Unknown ids in `harness.config.json` now warn and are
+  dropped instead of breaking every later rebuild.
+- Claude `settings.json` that is not a JSON object, or unreadable, is refused instead of
+  overwritten; every JSON config write is atomic.
+- Loop: a malformed `record --card` is refused before it can wedge the loop; `check` resolves
+  bricks from the git root; `next` no longer rewrites `LOOP.md`; a clean tree is recognised.
+- Console: the Docs host selector follows the deployed install instead of sticking to OpenCode;
+  the About page shows the installed and source fingerprints; the outline strips inline markdown.
+- `theme --transparent-only` names the file it wrote; `validate --help` prints its own usage.
+- Doctor's module-map check keys by folder, so twin module names can no longer hide a missing row.
+- `learn` reports on stderr when it cannot start the model CLI.
+
+### Changed
+- The hook binary loads one verb's module per call (`hooks.mjs` gates, `hooks-context.mjs`,
+  `hooks-learn.mjs`): gate cold import ~16 → ~10 ms, on every tool call. The memory-file helpers
+  live in the no-spawn `memory-files.mjs`, so the CLI no longer reaches `child_process`.
+- Internal splits: `js/hosts/shim.mjs`, `js/build/args.mjs`, `checks-constitution.mjs`,
+  `checks-counts.mjs`; one JSON-object reader and one `CLAUDE_STYLE` host list; dead code and
+  Python-era comments removed.
+
 ## [3.13.0] — 2026-10-04
 
 **Upgrading:** re-emit (`geneseed rebuild-all`) so the installed `loop` skill knows the new

package/SHIPPED.md

@@ -20,7 +20,7 @@ historical references, not files distributed with the repo.
 > **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
 > human-readable label only. The canonical identity of an installed harness is the
 > **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
-> string. Current label: **3.13.0**.
+> string. Current label: **3.14.0**.
 
 ## Capabilities
 

package/adapters/opencode/plugins/geneseed-learn.js

@@ -251,6 +251,11 @@ function parseFrontmatter(chunk) {
   return fm
 }
 
+// A memory `name:` becomes a FILENAME and the model writes it, so it is a plain slug or
+// nothing — no separator, no `..`, no drive. The same rule as MEMORY_SLUG_RE in
+// js/hosts/hooks.mjs, inlined because this file ships standalone.
+const MEMORY_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/
+
 async function writeMemories(output, memDir, existing) {
   const written = []
   const indexLines = []
@@ -259,7 +264,7 @@ async function writeMemories(output, memDir, existing) {
     if (!chunk || chunk.toUpperCase() === "NOTHING") continue
     const fm = parseFrontmatter(chunk)
     const name = (fm.name || "").trim()
-    if (!name || existing.has(name)) continue
+    if (!MEMORY_SLUG_RE.test(name) || existing.has(name)) continue
     await fs.writeFile(path.join(memDir, `${name}.md`), chunk.replace(/\n+$/, "") + "\n", "utf8")
     existing.add(name)
     written.push(name)
@@ -393,4 +398,8 @@ export const GeneseedLearn = async ({ client }) => {
   }
 }
 
+// OpenCode treats every export as a plugin and rejects non-functions; hang the test
+// helpers off the factory instead — reachable via import, invisible to the loader.
+Object.assign(GeneseedLearn, { writeMemories })
+
 export default GeneseedLearn

package/bin/geneseed-cli.mjs

@@ -58,7 +58,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.
@@ -302,7 +302,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 +311,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

@@ -27,9 +27,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 +40,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 +70,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;
@@ -128,8 +136,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 +144,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.14.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 |
@@ -220,7 +229,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 |