geneseed 2.0.0 → 3.0.0

package/js/render.mjs

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

package/js/settings.mjs

@@ -33,7 +33,8 @@
  * much larger change than the defect.
  */
 import {
-  chmodSync, existsSync, mkdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync,
+  chmodSync, existsSync, mkdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync,
+  writeFileSync,
 } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -66,17 +67,120 @@ function isDict(v) {
   return Boolean(v) && typeof v === 'object' && !Array.isArray(v);
 }
 
-/** `_build_settings._default_permission`. */
-export function defaultPermission() {
-  return {
-    bash: {
-      'rm -rf *': 'ask',
-      'git commit*': 'ask',
-      'git push*': 'ask',
-      'git push --force*': 'ask',
-      'git push -f*': 'ask',
-    },
-  };
+/**
+ * Is the `process` doctrine pack active for the install being emitted?
+ *
+ * ⚠ FAIL CLOSED, and the shape of the test is the whole point. Anything that is not an
+ * explicit array — `null`, `undefined`, a caller that never learned about packs — means
+ * "unknown", and unknown keeps the consent gate wired. `doctrinesOfDir` returns exactly that
+ * `null` for a pre-migration install, and `d?.includes('process')` would read it as "off" and
+ * silently unwire the gate from every carrier on disk. An empty array is NOT unknown: it is a
+ * deliberate `--doctrines none`, and it turns the gate off.
+ */
+const processPackOn = (d) => !Array.isArray(d) || d.includes('process');
+
+/**
+ * `_build_settings._default_permission`.
+ *
+ * WHAT THE PACK TOGGLE REACHES AND WHAT IT MUST NOT. `git commit*` and `git push*` are the
+ * BOUNDARY HALF of doctrine process 5 (consent before recording or sharing); with the process
+ * pack off, that rule is no longer binding — its text is not rendered into the carrier's
+ * doctrine section — and a boundary that keeps asking for a rule the install did not adopt is
+ * the one disagreement the tiering is not allowed to produce. (It does NOT follow that the
+ * string is gone from the bundle; see `claudeHookGroups` for what D5 ships anyway and why.)
+ * `rm -rf *`, `git push --force*` and `git push -f*` stay in EVERY build: they are
+ * Law IV's territory — an always-on invariant — not the process pack's, and the guard
+ * plugin's own force-push arm is unconditional for the same reason.
+ */
+export function defaultPermission(doctrines = null) {
+  const bash = { 'rm -rf *': 'ask' };
+  if (processPackOn(doctrines)) {
+    bash['git commit*'] = 'ask';
+    bash['git push*'] = 'ask';
+  }
+  bash['git push --force*'] = 'ask';
+  bash['git push -f*'] = 'ask';
+  return { bash };
+}
+
+/**
+ * Every `permission.bash` key Geneseed has ever written — the OWNED set, which is not the same
+ * as the set `defaultPermission` returns for a given selection. The two process-pack keys are
+ * in it whether or not this build wants them, because reconciling an EXISTING opencode.json
+ * has to be able to recognise a key that is Geneseed's business at all — to add it back when
+ * the pack returns, and to name it when this build no longer wants it but will not remove it.
+ */
+const OWNED_BASH = ['rm -rf *', 'git commit*', 'git push*', 'git push --force*', 'git push -f*'];
+
+/**
+ * Bring an ALREADY-WRITTEN `permission` block back into line with the pack selection, and
+ * touch nothing else. Returns `[changed, stranded]` — whether anything moved, and the owned
+ * keys this build does NOT want but refuses to take away.
+ *
+ * ⚠ THIS IS THE FIX FOR A BOUNDARY FROZEN AT FIRST WRITE. `mergeOpencodeJson` used to add the
+ * whole block only when the key was absent, so on a file that already had one the git gate was
+ * whatever the FIRST emit happened to write, forever — and the direction that matters is
+ * turning the process pack back ON, which left the gate ABSENT while AGENT.md stated the rule.
+ * That direction is pure ADDITION and it is fixed here. Claude's side never had the hole;
+ * `mergeClaudeSettings` prunes and re-adds its managed groups on every emit, because that file
+ * has a MANAGED BLOCK and this one does not.
+ *
+ * ⚠ REMOVAL IS GUARDED BY OWNERSHIP, NOT BY VALUE — and this is the second thing the first cut
+ * got wrong. `opencode.json` is USER CO-OWNED: the WIRE stage reconciles it, it does not own
+ * it. Geneseed may take back an entry it wrote; it may never take back one the user wrote.
+ * Dropping every unwanted key that still read `'ask'` treated the VALUE as the ownership
+ * record, so a user who had typed their own `"git commit*": "ask"` — a perfectly ordinary
+ * thing to want, and the value Geneseed writes precisely because it is the obvious one — had
+ * it DELETED by a pack-off build.
+ *
+ * NOTHING ON DISK RECORDS PROVENANCE, and none of the candidates survived contact: the value
+ * is what a user would write too; the carrier's `Active packs:` marker is rewritten by this
+ * same emit BEFORE `mergeOpencodeJson` runs (`emitOpencodeGlobalRender` writes AGENT.md at the
+ * top and wires the config at the bottom), so it answers with the NEW selection and would
+ * licence every removal; and a per-install ownership record would be a new marker file joining
+ * the owned set, the reversal markers and the deletion corpus — a much larger change than the
+ * defect. So removal is CONSERVATIVE: an unwanted owned key that is already on disk stays, and
+ * is reported to the caller as `stranded` so the user is told rather than left to discover it.
+ *
+ * That leaves a gate wired for a rule this build does not make binding, which is the
+ * FAIL-CLOSED direction — the boundary asks for a confirmation the constitution no longer
+ * compels, exactly as the commit skill's own consent step does with the pack off. The unsafe
+ * direction, a rule with no gate behind it, cannot occur here. A FRESH file is unaffected:
+ * `mergeOpencodeJson` writes `defaultPermission(doctrines)` whole, so a new pack-off install
+ * has no git gate at all.
+ *
+ * ⚠ KEY ORDER IS NOT RECONCILED, DELIBERATELY. `defaultPermission` emits its keys in a fixed
+ * order, so a FRESH write is tidy; an off→on reconcile appends the two process keys after the
+ * force-push pair and the block reads out of order from then on. Restoring the order means
+ * rewriting a map whose other entries belong to the user — sorting THEIR keys to tidy OURS is
+ * the value-over-ownership mistake in a second suit, and JSON object order carries no meaning
+ * to OpenCode. So the order is left as found and only membership is reconciled.
+ *
+ * Returns a third element, `opaque`: the shape reason wiring was impossible, or `null`. The
+ * caller warns on it. This is the one branch where the boundary can end up with NO Geneseed
+ * gate at all while the constitution states the rule — the unsafe direction — so it must not
+ * also be the silent one.
+ */
+function reconcileOpencodePermission(perm, want) {
+  // A `permission` that is not an object, or whose `bash` is not one — OpenCode also accepts a
+  // bare `"bash": "allow"` — is a shape this function has no owned keys inside of. Leaving it
+  // exactly as found is the whole point; rewriting it into a map would DELETE a blanket policy
+  // the user wrote, which is a bigger change than the one being reconciled.
+  if (!isDict(perm)) return [false, [], 'is not an object'];
+  if (has(perm, 'bash') && !isDict(get(perm, 'bash'))) {
+    return [false, [], 'has a "bash" that is not an object'];
+  }
+  const fresh = !has(perm, 'bash');
+  const bash = fresh ? {} : get(perm, 'bash');
+  let changed = false;
+  const stranded = [];
+  for (const k of OWNED_BASH) {
+    if (has(want.bash, k)) {
+      if (!has(bash, k)) { bash[k] = want.bash[k]; changed = true; }
+    } else if (has(bash, k)) stranded.push(k);
+  }
+  if (changed && fresh) perm.bash = bash;
+  return [changed, stranded, null];
 }
 
 /**
@@ -169,16 +273,27 @@ export function readJsonc(text) {
   }
 }
 
-/** `_build_settings._warn_commented_jsonc`. Prints to STDOUT — the Python's own choice. */
-export function warnCommentedJsonc(target, agentPath, includePermission,
-  includeLsp = false, prefix = 'geneseed') {
+/**
+ * `_build_settings._warn_commented_jsonc`. Prints to STDOUT — the Python's own choice.
+ *
+ * `permission` is THREE-STATE, not a boolean: `'add'` for a file with no `permission` key,
+ * `'reconcile'` for one that has a block this build would have wired gates into, and falsy for
+ * neither. A commented `.jsonc` is never rewritten — that is what "your edits are kept" buys —
+ * so the only thing this branch can do about a stale block is SAY SO, and telling a file that
+ * already has a `permission` key to add one is not saying so. Any other truthy value is read as
+ * `'add'`, which is what the boolean callers this replaced meant.
+ */
+export function warnCommentedJsonc(target, agentPath, permission,
+  includeLsp = false, prefix = 'geneseed', doctrines = null) {
   process.stdout.write(`[${prefix}] ${path.basename(target)} has comments — not rewriting `
     + 'it (your edits are kept). Add this to its "instructions" array by hand:\n');
   process.stdout.write(`[${prefix}]     ${jsonDumps(agentPath)}\n`);
-  if (includePermission) {
-    process.stdout.write(`[${prefix}] and, for Geneseed's default ask-gates, a `
-      + '"permission" key:\n');
-    for (const line of jsonDumpsIndent(defaultPermission()).split('\n')) {
+  if (permission) {
+    process.stdout.write(permission === 'reconcile'
+      ? `[${prefix}] and its "permission".bash is missing gates this build wires — `
+        + 'reconcile it by hand against:\n'
+      : `[${prefix}] and, for Geneseed's default ask-gates, a "permission" key:\n`);
+    for (const line of jsonDumpsIndent(defaultPermission(doctrines)).split('\n')) {
       process.stdout.write(`[${prefix}]     ${line}\n`);
     }
   }
@@ -207,7 +322,7 @@ export function atomicWriteJson(p, config) {
  * re-implements the inverse itself rather than inherit this one's permission/lsp side
  * effects, so the only crossings are the two emit-tree ones (`_build_emit.emit_opencode`,
  * `_build_global.emit_opencode_global`). */
-export function mergeOpencodeJson(p, agentPath) {
+export function mergeOpencodeJson(p, agentPath, doctrines = null) {
   const target = opencodeTarget(p);
   let config = { $schema: OPENCODE_SCHEMA, instructions: [] };
   let hadComments = false;
@@ -238,13 +353,58 @@ export function mergeOpencodeJson(p, agentPath) {
   const addInstr = indexOfEq(instr, agentPath) < 0;
   if (addInstr) instr.push(agentPath);
   config.instructions = instr;
+  // Absent ⇒ write the whole block; present ⇒ reconcile Geneseed's own git keys. Adding is
+  // unconditional; removal is not this stage's to make (see `reconcileOpencodePermission`), so
+  // the second return value is what it declined to take away. `addPerm` stays a separate flag
+  // from "something changed" because the two produce DIFFERENT advice on a commented file.
   const addPerm = !has(config, 'permission');
-  if (addPerm) config.permission = defaultPermission();
+  let permChanged = addPerm;
+  let stranded = [];
+  let opaque = null;
+  if (addPerm) config.permission = defaultPermission(doctrines);
+  else {
+    [permChanged, stranded, opaque] = reconcileOpencodePermission(get(config, 'permission'),
+      defaultPermission(doctrines));
+  }
+  // The shape said no. This is the direction the residue warning above is NOT — a rule stated
+  // in AGENT.md with nothing behind it — and it used to pass in silence, because a blanket
+  // `"permission": {"bash": "allow"}` makes every reconcile a no-op and the whole merge then
+  // short-circuits before any of the three WARNs below. Reported, never rewritten: the blanket
+  // policy is the user's answer and it wins (`generate.test.mjs` pins that it survives).
+  if (opaque) {
+    process.stderr.write(`[geneseed] WARN: "permission" in ${path.basename(target)} `
+      + `${opaque}, so Geneseed cannot wire its own gates into it — including `
+      + `${OWNED_BASH.filter((k) => has(defaultPermission(doctrines).bash, k))
+        .map((k) => jsonDumps(k)).join(', ')}. Your policy is left exactly as written; the `
+      + 'harness states those rules but nothing enforces them at this boundary.\n');
+  }
+  // Told, not silently left: these are gates for a rule this build does not make binding, kept
+  // because Geneseed cannot prove it was the one that wrote them. stderr, like the other two
+  // WARNs here — the emit's stdout is byte-compared by the golden corpus.
+  if (stranded.length) {
+    process.stderr.write(`[geneseed] WARN: ${path.basename(target)} keeps `
+      + `${stranded.map((k) => jsonDumps(k)).join(', ')} under "permission".bash — the `
+      + 'doctrine pack behind those gates is off in this build, but Geneseed cannot tell its '
+      + 'own entry from one you wrote, so it removes neither. Delete them by hand if you want '
+      + 'them gone.\n');
+  }
   const addLsp = !has(config, 'lsp');
   if (addLsp) config.lsp = true;
-  if (!addInstr && !addPerm && !addLsp) return target;
+  if (!addInstr && !permChanged && !addLsp) return target;
   if (path.extname(target) === '.jsonc' && hadComments) {
-    warnCommentedJsonc(target, agentPath, addPerm, addLsp);
+    // ⚠ THE TWO CASES GIVE OPPOSITE ADVICE, and telling a file that HAS a `permission` key to
+    // add one is how the first cut of this got it wrong. `add` = there is no block, here is the
+    // whole one; `reconcile` = there is a block and it is missing gates this build wires, and
+    // this branch cannot write them because rewriting would drop the user's comments.
+    //
+    // DECIDED, NOT DEFERRED: a commented `.jsonc` is never rewritten and never will be. A
+    // comment-preserving JSONC writer is a parser, an AST and a printer — a dependency-free
+    // one, since this package ships zero — to keep formatting nobody asked us to touch, in a
+    // file Geneseed co-owns rather than owns. The advice above is the whole remedy: the exact
+    // block to paste, split by which of the two situations the reader is actually in. It is
+    // stdout, not stderr, because on this path the paste-in IS the output.
+    warnCommentedJsonc(target, agentPath, addPerm ? 'add' : (permChanged && 'reconcile'),
+      addLsp, 'geneseed', doctrines);
     return target;
   }
   try {
@@ -294,6 +454,19 @@ export const SHIM_MARK = 'geneseed-hook';
  */
 export const SHIM_ARGV = new Set(['$@', '%*']);
 
+/**
+ * Every quoted token in a shim body that names a path which is not there — empty is healthy.
+ *
+ * ONE OWNER, because the rule has two consumers now and a second copy is a second place for the
+ * `"$@"` defect above to come back: `js/doctor.mjs` turns this into the `[shim] … does not
+ * exist` report, and `hookPrefix` reads it to decide whether the shim already on disk is worth
+ * protecting from a checkout that will not outlive the emit.
+ */
+export function shimDeadPaths(body) {
+  return [...body.matchAll(/"([^"]+)"/g)].map((m) => m[1])
+    .filter((q) => !SHIM_ARGV.has(q) && !existsSync(q));
+}
+
 /** `_SHIM_REL`, with the platform as an argument.
  *
  * Python computes it at IMPORT time from `sys.platform`, which is what makes the other
@@ -401,6 +574,50 @@ export function writeHookShim(p, body, platform = process.platform) {
   }
 }
 
+/** The OS temp root, resolved once. `.native` because a Windows `TEMP` can be an 8.3 alias —
+ * the same trap `tests/helpers/sandbox.mjs` documents, reached from the other side. */
+const TMP_REAL = (() => {
+  try { return realpathSync.native(os.tmpdir()); } catch { return os.tmpdir(); }
+})();
+
+/** Is `child` inside `parent`? `path.relative` compares case-insensitively on win32. */
+function isUnder(child, parent) {
+  const rel = path.relative(parent, child);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+/**
+ * Will the checkout holding `entry` outlive the emit that is baking it into the shim?
+ *
+ * TWO SHAPES, and both are in `docs/extending.md` §5.3 because both have really happened on this
+ * repo: a copied checkout under the OS temp root — the `copyCheckout` fixture, which builds its
+ * copy from `git ls-files` and therefore carries no `.git` at all, so only the temp root
+ * identifies it — and a git WORKTREE, whose `.git` is a FILE pointing at the main checkout
+ * rather than a directory. A plain checkout and an npm install are neither, and keep the
+ * ownership they have always had.
+ *
+ * `tmpRoot` IS A PARAMETER for the reason `shimRel`'s `platform` is: with the real temp root
+ * baked in, the second rule is unreachable in a test — anything a test can build under `mkdtemp`
+ * has already answered true on the first — so the worktree arm could only ever be exercised by
+ * whichever kind of checkout the run happened to sit in.
+ */
+export function ephemeralCheckout(entry, tmpRoot = TMP_REAL) {
+  let real = entry;
+  try { real = realpathSync.native(entry); } catch { /* not there yet — test the literal */ }
+  if (isUnder(real, tmpRoot)) return true;
+  // `<checkout>/bin/geneseed-hook.mjs` — the one shape `hookRunnerEntry` produces.
+  try { return statSync(path.join(path.dirname(path.dirname(real)), '.git')).isFile(); } catch {
+    return false;
+  }
+}
+
+/** Does the shim already on disk still name paths that all exist? */
+function shimIsLive(p) {
+  try { return statSync(p).isFile() && shimDeadPaths(readText(p)).length === 0; } catch {
+    return false;
+  }
+}
+
 /**
  * `_build_settings._hook_prefix` — the `<runner> <entrypoint>` every emitted hook starts
  * with, falling back to the pre-shim direct form when the shim cannot be written.
@@ -422,6 +639,26 @@ export function hookPrefix({ runner, entry, platform = process.platform } = {})
       + 'bakes them, and there is no correct value to guess from inside Node');
   }
   const p = hookShimPath(platform);
+  // ⚠ A DISPOSABLE CHECKOUT DOES NOT GET TO CLAIM THE MACHINE-WIDE SHIM. The shim has no
+  // per-install component, so the last checkout to emit owns EVERY install's hooks — and when
+  // that checkout is a test sandbox or a git worktree, deleting it kills hooks machine-wide with
+  // nothing to report it: hooks signal through stdout and return 0 on every path, and this file
+  // is excluded from the byte corpora by name. Measured twice in one session, from
+  // `tests/unit/harness.test.mjs`'s copied-checkout fixture; `docs/extending.md` §5.3 carries
+  // the worktree half.
+  //
+  // KEEP, NOT REFUSE, and that distinction is what makes this safe to add here rather than at
+  // each call site. Returning the existing shim path leaves the emitted hook command
+  // byte-identical to what a normal emit writes; taking the fallback below instead would move a
+  // hook command in every recorded bundle. The install being emitted then runs the DURABLE
+  // checkout's entry — which is exactly what last-writer-wins already handed every other install
+  // on the machine, so nothing is lost by it.
+  //
+  // ONLY A SHIM THAT STILL RESOLVES IS PROTECTED. An absent or already-dead one is no worse for
+  // being rewritten from here, and a sandboxed `GENESEED_HOME` (every emit test, every cell) has
+  // none — so the suite's own emits are unaffected and this cannot go green by silently
+  // skipping the write.
+  if (ephemeralCheckout(entry) && shimIsLive(p)) return `"${p}"`;
   const shim = writeHookShim(p, hookShimBody(runner, entry, platform), platform);
   if (shim !== null) return `"${shim}"`;
   process.stderr.write(`[geneseed] WARN: could not write the hook shim at ${p} — emitting `
@@ -430,8 +667,38 @@ export function hookPrefix({ runner, entry, platform = process.platform } = {})
   return `"${runner}" "${entry}"`;
 }
 
-/** `_build_settings._claude_hook_groups` — Geneseed's Claude hooks, keyed by event. */
-export function claudeHookGroups(cfg, hookOpts) {
+/**
+ * `_build_settings._claude_hook_groups` — Geneseed's Claude hooks, keyed by event.
+ *
+ * ⚠ `doctrines` IS WHERE PROMPT AND BOUNDARY ARE KEPT IN AGREEMENT. The `git-gate` group is
+ * the tool-boundary half of doctrine process 5. With the process pack off, that rule is no
+ * longer BINDING — `src/doctrines/process.md` is not rendered into the carrier's doctrine
+ * section and nothing in the constitution obliges the agent to it — so a gate that stopped
+ * every Bash call to ask for consent to a rule the install did not adopt is the disagreement
+ * the three-tier split forbids. Omitting the group here is also what UNWIRES it from an
+ * install that had it: `mergeClaudeSettings` prunes every previously-managed group that is not
+ * in this return value, so flipping the pack off and rebuilding takes the hook out of
+ * settings.json rather than leaving it orphaned.
+ *
+ * ⚠ WHAT THIS DOES **NOT** CLAIM, because it was written here once and it was false: that the
+ * string `process 5` is absent from a pack-off bundle. It is not — 18 emitted files still cite
+ * it (`grep -rl 'process 5' <off-bundle>`), and by owner decision D5 that is deliberate: the
+ * whole pack CATALOGUE ships in every build (`<bundle>/doctrines/process.md` is byte-identical
+ * on and off), so body-prose citations from craft, from the agents and from the skills stay
+ * RESOLVABLE rather than dangling. A citation is not an obligation.
+ *
+ * The one place that distinction is thin is `skills/commit.md`, which carries the operative
+ * procedure ("get explicit consent before committing") and not merely a pointer. It is left
+ * unconditional ON PURPOSE: a skill that asks before committing when nothing compelled it is
+ * never unsafe, whereas conditionalising it would put a second copy of the pack switch in the
+ * prose layer for no gain in safety. Asymmetric risk, asymmetric answer — the BOUNDARY follows
+ * the pack, the ASKING does not have to.
+ *
+ * The `rule-gate` group stays in every build. Its subject is which durable store a write
+ * belongs in — the user's call — not how work is run, so it is not the process pack's to
+ * remove. `default` here means unknown, and unknown keeps the gate (see `processPackOn`).
+ */
+export function claudeHookGroups(cfg, hookOpts, doctrines = null) {
   const run = hookPrefix(hookOpts);
   const mem = `--memory "${path.join(cfg, 'memory')}"`;
   // --root carries the install's own dir so a GLOBAL hook can stand down when a project
@@ -442,7 +709,8 @@ export function claudeHookGroups(cfg, hookOpts) {
   const learn = `${run} learn ${mem} || exit 0`;
   return {
     PreToolUse: [
-      { matcher: 'Bash', hooks: [{ type: 'command', command: gate }] },
+      ...(processPackOn(doctrines)
+        ? [{ matcher: 'Bash', hooks: [{ type: 'command', command: gate }] }] : []),
       {
         matcher: 'Write|Edit|MultiEdit|NotebookEdit',
         hooks: [{ type: 'command', command: ruleGate }],
@@ -472,7 +740,8 @@ export function claudeHookGroups(cfg, hookOpts) {
  *
  * `scope` is accepted and unused, exactly as in the Python.
  */
-export function mergeClaudeSettings(p, scope = 'global', priorHooks = null, hookOpts = {}) {
+export function mergeClaudeSettings(p, scope = 'global', priorHooks = null, hookOpts = {},
+  doctrines = null) {
   const prior = (priorHooks || []).filter(isDict);
   let config = {};
   let hadComments = false;
@@ -492,7 +761,7 @@ export function mergeClaudeSettings(p, scope = 'global', priorHooks = null, hook
   }
   let hooks = get(config, 'hooks');
   if (!isDict(hooks)) hooks = {};
-  const canonical = claudeHookGroups(path.dirname(p), hookOpts);
+  const canonical = claudeHookGroups(path.dirname(p), hookOpts, doctrines);
   const canonFlat = [];
   for (const [event, groups] of Object.entries(canonical)) {
     for (const g of groups) canonFlat.push({ event, group: g });