simt-dev 0.7.0 → 0.8.0

package/src/commands/help.mjs

@@ -1,8 +1,12 @@
-import { emit, fail, jsonFailMode } from '../output/index.mjs';
+import { emit, emitJson, fail, jsonFailMode } from '../output/index.mjs';
+import { SPEC, SPEC_PATHS, tierOf } from './spec.mjs';
 import { parse, rawJsonFlag } from '../argv.mjs';
 import { CLI, MANIFEST_FILE, STATE_DIR } from '../name.mjs';
 import { SESSION_ENV } from '../agenthooks/policy.mjs';
 import { DEFAULT_DIRECTORIES, DEFAULT_TEMPLATE } from '../plan/template.mjs';
+import { commandRoot } from '../repo-root.mjs';
+import { readManifest } from '../projection/manifest.mjs';
+import { assertVersionPin } from '../package-version.mjs';
 
 const COMMANDS = `${CLI} init [path]            adopt or scaffold a repo into the ecosystem
                            (dry-run unless --yes; conflicts block without
@@ -145,7 +149,7 @@ ${CLI} lessons list            deterministic lesson candidates in .simt/local/le
                            and promoted lessons in docs/lessons/*.md (reads nothing else)
 ${CLI} lessons capture         scan the ledger and git history for new candidates (the write half of list)
 ${CLI} lessons review [<id>]   promote a lesson candidate to docs/lessons/NNNN-<slug>.md
-                           (dry-run unless --yes; writes Appendix A frontmatter)
+                           (dry-run unless --yes; writes the lesson frontmatter)
 ${CLI} explain <CODE>        what a check finding means: the decision behind it, how
                            to fix it, and a concrete trigger (DRIFT, UNMANAGED,
                            PACK-DIGEST-MISMATCH, ...; case-insensitive)
@@ -168,7 +172,7 @@ ${CLI} distill <skill|doc>     a budgeted proposal summary of a skill body or do
                            from the configured chat model instead; the cache is
                            keyed by source digest and budget, --refresh regenerates)
 ${CLI} review [--local]        an ADR-008 verdict skeleton for the staged diff,
-                           the brief listing everything that governs it (R25)
+                           the brief listing everything that governs it
                            (deterministic without --local: the brief and its
                            governing ids only; --local proposes from the
                            configured chat model and writes
@@ -219,6 +223,16 @@ ${CLI} bench critic          precision and recall of the local critic over a lab
                             overrides --labels; labels are human-written verdicts
                             under ADR-008; the critic is advisory until precision
                             reaches 0.8 on 30 labelled diffs)
+${CLI} bench export <file> [--yes]
+                            sealed export of the mined corpus: every task
+                            descriptor and both hidden patches in one signed
+                            JSON file, for import on another machine
+                            (dry-run unless --yes; --root selects the repository)
+${CLI} bench import <file> [--yes]
+                            import a sealed corpus: verify the seal, then write
+                            the task descriptors and hidden patches into the
+                            repository's vault (dry-run unless --yes; --root
+                            selects the repository)
 ${CLI} pack new <name> --source <spec>
                            scaffold a versioned pack: pack.json, an unmeasured
                            bench.json, and one stack rule (dry-run unless --yes;
@@ -231,6 +245,7 @@ ${CLI} pack publish [dir] [--yes]
                            publish an npm-sourced pack to the registry
                            (dry-run unless --yes; skips a version already live;
                            a git-sourced pack names the tag-and-push instead)
+${CLI} docs readme --yes      render the README command list from the spec
 ${CLI} mcp                    the read-only surface as MCP tools over stdio
                            (--list prints it without reading stdin; init, sync,
                            upgrade and the installers stay CLI-only by design)`;
@@ -283,6 +298,8 @@ const FLAGS = `--json                 structured output (compact; one document,
 --accept-conflicts      init: adopt rules that collide with hand-written ones
 --backup                init: tag the pre-adoption commit and branch onto
                         simt-dev/adopt before writing (the undo path)
+--no-agents             init: skip the agent files and the agent-hooks in one flag;
+                        the standalone agents / agent-hooks install commands remain
 --spec <name>           graph lint: also check every skill against a named
                         specification (one exists: agentskills)
 --user                  harness detect: also report the directories in your home
@@ -302,7 +319,9 @@ const FLAGS = `--json                 structured output (compact; one document,
 --harness <id>          bench run: adapter to invoke (claude, codex, gemini, opencode,
                          cursor, aider, gold, noop; default: gold);
                          agent-hook: which dialect to answer in (claude, cursor,
-                         codex, antigravity)
+                         codex, antigravity); agent-hooks / agents install: which
+                         reader to write (one, not all); init: narrows the agent
+                         files and the agent-hooks to one reader
 --model <id>            bench run: model identifier recorded and passed to the adapter
 --reps <n>              bench run: repetitions per task and arm (default: 3)
 --regrade <run>         bench run: re-grade a stored run from its archived agent patch
@@ -310,6 +329,8 @@ const FLAGS = `--json                 structured output (compact; one document,
 --test <cmd>            plan done / slice finish: the test command that closes the row
 --state <name>          plan done: target state (default: Complete)
 --type <name>           slice finish: the Conventional Commits type (default: feat)
+--id <name>             slice start: the slice id when -- starts one from a prompt
+                        (default: a slug of the prompt text)
 --ttl <seconds>         lease: how long a claim lasts (default: 3600)
 --level <name>          map: detail level (outline, names, signatures)
 --supersedes <spec>     decide: superseded ADR or ruling (ADR-NNN or ADR-NNN:<ruling>[:<kind>]; repeatable)
@@ -322,8 +343,14 @@ const FLAGS = `--json                 structured output (compact; one document,
 --embed                 index / map / brief: compute or query optional local vector embeddings
                         (off by default unless recall@10 gains at least 10 points)
 --labels <path>         bench critic: the labelled set of historical diffs to score
+--cross-group           bench ablate: compare across harness, model and experiment
+                        groups instead of refusing the comparison
+--expires <when>        lessons capture: how long a captured candidate stays eligible
                         (default .simt/critic-labels.jsonl; one human-written
                         {sha, verdict} pair per line)
+--replace               bench mine: delete task files the current mine does not
+                        reproduce (off by default: mining is append-only; a
+                        re-mine adds, it does not replace the corpus)
 --refresh               distill / review: regenerate a proposal that is already cached
 --local                 distill / review: propose the answer from the configured
                          local chat model (local.chat); off by default, which
@@ -338,42 +365,164 @@ const PRINCIPLES = `design rules:
   zero dependencies   a DX tool that needs an install step fails on a fresh machine
   bounded output      one fact per line, fixed field order, explicit TRUNCATED lines`;
 
-export async function help(argv) {
-  const parsed = parse(argv);
+export async function help(argv, dispatched) {
+  // `dispatched` is what `dispatch` already parsed. Called from a test or another
+  // command with only argv, help parses it itself.
+  const parsed =
+    dispatched === undefined
+      ? parse(argv)
+      : dispatched.parseError === undefined
+        ? { ok: true, value: { flags: dispatched.flags, positional: dispatched.positional } }
+        : { ok: false, error: dispatched.parseError };
   if (!parsed.ok) {
     jsonFailMode(rawJsonFlag(argv));
     return fail(parsed.error.message, parsed.error.code);
   }
-  const { flags } = parsed.value;
+  const { flags, positional } = parsed.value;
   if (flags.version) {
     emit((await version()).trim());
     return 0;
   }
+  // A reader who names one command gets that command, not the whole surface (review
+  // 0003 Q61): `simt help gate` and `simt gate --help` both printed 23 KB, so the one
+  // fact being asked for was 40 screens down.
+  const asked = commandFromHelp(positional);
+  if (asked !== null) {
+    emit(commandPage(asked));
+    return 0;
+  }
+  if (flags.json === true) {
+    emitJson(SPEC.map(specRow));
+    return 0;
+  }
+  // The standard page is where a reader asks "what can this do, and where do I start".
+  // A repository that has not been adopted, or that pins a version this binary is not,
+  // has a prerequisite worth stating before the catalogue: no manifest means init is the
+  // first move, a stale pin means sync is the fix. Fully ready, the page stands on its
+  // own and the banner is nothing.
+  const banner = await prerequisiteBanner(flags, positional);
+  const bannerLines = banner === null ? [] : ['', banner, ''];
+  // `--all` prints every command and every flag; the default page lists the core tier and
+  // says where the rest is. A reader asking "what can this do" needs the shape, not 23 KB
+  // of flag reference (review 0003 Q61).
+  if (flags.all === true) {
+    emit(
+      [
+        'simt-dev - shared agent rules, skills and gates for a repo ecosystem',
+        '',
+        `usage: ${CLI} <command> [args] [flags]`,
+        ...bannerLines,
+        'commands:',
+        COMMANDS,
+        '',
+        'flags:',
+        FLAGS,
+        '',
+        PRINCIPLES,
+        '',
+        `rulings  ${CLI} rules list   the decisions behind the rules you just read`,
+      ].join('\n'),
+    );
+    return 0;
+  }
+  // One line per group and one per bare command: listing every subcommand with its
+  // summary does not fit in the 2 KB a reader will actually read (review 0003 Q61).
+  const groups = new Map();
+  const bare = [];
+  for (const row of SPEC) {
+    if (tierOf(row.path) !== 'core') continue;
+    const [head, sub] = row.path.split(' ');
+    if (sub === undefined) bare.push(row);
+    else groups.set(head, [...(groups.get(head) ?? []), sub]);
+  }
   emit(
     [
       'simt-dev - shared agent rules, skills and gates for a repo ecosystem',
       '',
       `usage: ${CLI} <command> [args] [flags]`,
-      '',
+      ...bannerLines,
       'commands:',
-      COMMANDS,
-      '',
-      'flags:',
-      FLAGS,
-      '',
-      PRINCIPLES,
+      ...[...groups].map(([group, subs]) => `  ${CLI} ${group} <${subs.join('|')}>`),
+      ...bare.map((row) => `  ${CLI} ${row.path.padEnd(8)} ${row.summary.length > 46 ? `${row.summary.slice(0, 43)}...` : row.summary}`),
       '',
-      // The plans ship inside the installed package but have no command that surfaces
-      // them, so naming the path would again be advice the reader cannot take. They
-      // are an implementation record; the rulings are the part a reader can act on.
-      `rulings  ${CLI} rules list   the decisions behind the rules you just read`,
+      `more      ${CLI} help --all (every command and flag), ${CLI} help <command>`,
+      `rulings   ${CLI} rules list (the decisions behind the rules)`,
     ].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   return 0;
 }
 
+/**
+ * The prerequisite line for the standard help page, or null when the repository is fully
+ * ready. No manifest (or one that cannot be read) means the adoption has not happened and
+ * `init` is the first move; a manifest that pins a version the running binary is not means
+ * `sync` is the fix. These are the two states in which a reader opening help is about to
+ * run a command that would fail in a predictable way, so the page says so before it lists
+ * the commands.
+ */
+async function prerequisiteBanner(flags, positional) {
+  const root = commandRoot(flags, positional);
+  const { manifest, exists, error } = await readManifest(root);
+  if (!exists) {
+    return `prerequisite  no ${MANIFEST_FILE} here; run: ${CLI} init <path>`;
+  }
+  if (error !== null) {
+    return `prerequisite  ${MANIFEST_FILE} cannot be read (${error}); run: ${CLI} init <path>`;
+  }
+  const stale = assertVersionPin(manifest);
+  if (stale !== null) {
+    return `prerequisite  ${stale}; run: ${CLI} sync`;
+  }
+  return null;
+}
+
 async function version() {
   const { describeVersion } = await import('../package-version.mjs');
   return `${describeVersion()}\n`;
 }
+
+/** The command a help request names, or null when it names none. */
+function commandFromHelp(positional) {
+  const words = positional[0] === 'help' ? positional.slice(1) : positional;
+  const two = words.slice(0, 2).join(' ');
+  if (SPEC_PATHS.includes(two)) return two;
+  return SPEC_PATHS.includes(words[0]) ? words[0] : null;
+}
+
+/** One spec row as the JSON a UI or a harness reads. */
+function specRow(row) {
+  return { path: row.path, summary: row.summary, ...(row.defaultFor === undefined ? {} : { defaultFor: row.defaultFor }) };
+}
+
+const PAGE_WIDTH = 78;
+
+/** The summary broken to the page width, so a narrow terminal keeps it readable. */
+function wrapped(text) {
+  const lines = [];
+  let line = '';
+  for (const word of text.split(' ')) {
+    if (line !== '' && line.length + 1 + word.length > PAGE_WIDTH) {
+      lines.push(line);
+      line = word;
+    } else {
+      line = line === '' ? word : `${line} ${word}`;
+    }
+  }
+  if (line !== '') lines.push(line);
+  return lines;
+}
+
+/**
+ * One command's page: what it is, and where the rest of the answers are. The flags a
+ * single command declares arrive with the spec's `flags` field (Q62); until then the
+ * page points at the global list rather than inventing one per command.
+ */
+export function commandPage(path) {
+  const row = SPEC.find((r) => r.path === path);
+  if (row === undefined) return '';
+  const lines = [`${CLI} ${path} [args] [flags]`, '', ...wrapped(row.summary), ''];
+  if (row.defaultFor !== undefined) lines.push(`default  ${CLI} ${row.defaultFor} runs this command`);
+  lines.push(`flags    --json --pretty --root --max-bytes, and every global flag`);
+  lines.push(`all      ${CLI} --help   every command, and every flag it takes`);
+  return `${lines.join('\n')}\n`;
+}

package/src/commands/hooks.mjs

@@ -12,27 +12,33 @@
 // DEFAULT location, which core.hooksPath being unset does not reveal, so a
 // foreign hook is found by asking git rather than by reading config.
 
-import { mkdir, readFile, realpath } from 'node:fs/promises';
-import { commitJournal, journaledGitConfig, journaledRemoveFile, journaledWriteFile } from '../journal.mjs';
+import { mkdir, readFile, readdir, realpath, rm, stat } from 'node:fs/promises';
+import { repoContext } from '../context.mjs';
+import { commitJournal, journaledGitConfig, journaledRemoveFile } from '../journal.mjs';
+import { applyPlan, change } from '../write/plan.mjs';
 import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 import { invalidateCheckCache } from '../status.mjs';
 import { isAbsolute, join, relative } from 'node:path';
 
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
 import { MANIFEST, readManifest } from '../projection/manifest.mjs';
-import { EVENTS, HOOKS_DIR, HOOKS_PATH_KEY, SHIM_MARKER, fileFor, renderChainedShim, renderEvidenceShim, renderShim } from '../hooks/shim.mjs';
+import { CHAIN_MARKER, EVENTS, HOOKS_DIR, HOOKS_DIR_LEGACY, HOOKS_PATH_KEY, SHIM_MARKER, fileFor, renderChainedShim, renderEvidenceShim, renderShim } from '../hooks/shim.mjs';
 import { GATE_KEY, gateCount, readHooksPath, readHooksState, wantsShim } from '../compare/hooksstate.mjs';
-import { GATES } from '../hooks/gates.mjs';
-import { knownGates } from '../hooks/resolve.mjs';
+import { gateNames, getGate } from '../hooks/gates.mjs';
 import { renderGateReport, runGates } from '../hooks/dispatcher.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 import { packageVersion, hasNpm } from '../package-version.mjs';
+import { commandRoot } from '../repo-root.mjs';
+import { readIfExists } from '../util/fs.mjs';
 
 export async function hooksCommand(sub, args, flags) {
-  const root = flags.root ?? args[0] ?? process.cwd();
-  if (sub === 'install') return installHooks(root, flags);
-  if (sub === 'status') return hooksStatus(root, flags);
+  const root = commandRoot(flags, args);
+  // One context for the subcommand: install and status each ask about the same
+  // repository, and `doctor --fix` asks alongside them (review 0003 Q67).
+  const ctx = repoContext(root);
+  if (sub === 'install') return installHooks(root, flags, ctx);
+  if (sub === 'status') return hooksStatus(root, flags, ctx);
   if (sub === 'run') return runHook(args, flags);
   return fail(`unknown hooks subcommand ${sub}`, EXIT.USAGE, `run: ${CLI} hooks status`);
 }
@@ -40,11 +46,12 @@ export async function hooksCommand(sub, args, flags) {
 /** The shim execs this; the event name is baked into the shim, so it is arg 0. */
 async function runHook(args, flags) {
   const event = args[0];
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
+  const ctx = repoContext(root);
   if (!EVENTS.includes(event)) {
     return fail(`unknown hook event ${event}`, EXIT.USAGE, `known events: ${EVENTS.join(', ')}`);
   }
-  const { manifest, exists, error } = await readManifest(root);
+  const { manifest, exists, error } = await ctx.manifest();
   if (error) return fail(`${MANIFEST_FILE}: ${error}`, EXIT.CONFIG);
   if (!exists) {
     return fail(`${root} has no ${MANIFEST_FILE}; the hook cannot know its gate list`, EXIT.CONFIG, `run: ${CLI} init --root ${root}`);
@@ -64,7 +71,7 @@ async function runHook(args, flags) {
   }
 
   for (const n of result.notes ?? []) note(`note     ${n}`);
-  emit(renderGateReport(event, manifest.gates[GATE_KEY[event]] ?? [], result).join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(renderGateReport(event, manifest.gates[GATE_KEY[event]] ?? [], result).join('\n'));
   return result.failed ? EXIT.FAIL : EXIT.OK;
 }
 
@@ -135,7 +142,7 @@ async function relativeTarget(root, target) {
  *   caller enforces in its own voice (`takeover`, and the `wanted`/`obsolete`
  *   emptiness the command refuses on)
  */
-export async function planHooksInstall(root, { manifest, exists }) {
+export async function planHooksInstall(root, { manifest, exists }, ctx = null) {
   const declaresGate = (event) => wantsShim(manifest, exists, event);
   const state = await readHooksState(root, { declaresGate });
   const current = state.current;
@@ -159,8 +166,10 @@ export async function planHooksInstall(root, { manifest, exists }) {
     } catch {
       // Unreadable here leaves the npm default; the manifest path reports it.
     }
-    const { fingerprint } = await import('../resolve/fingerprint.mjs');
-    const detected = await fingerprint(root);
+    // The dynamic import stays: a hook run must not pull the fingerprint module in
+    // just by loading this one. A caller that already holds a context passes it and
+    // the walk is shared (review 0003 Q67).
+    const detected = ctx ? await ctx.fingerprint() : await (await import('../resolve/fingerprint.mjs')).fingerprint(root);
     manager = resolveNodeRunner({ facts: detected.facts, packageManager }).id;
   }
 
@@ -190,8 +199,8 @@ export async function planHooksInstall(root, { manifest, exists }) {
   //
   // `foreignHooks` lists every executable file in the directory git reads hooks from -
   // and when that directory is this tool's own, a file a person dropped in there is
-  // listed too. Chaining it means writing a shim at `.simt-hooks/<name>` whose TARGET is
-  // `.simt-hooks/<name>`: the same path. The shim overwrites the hook it was written to
+  // listed too. Chaining it means writing a shim at `.simt/hooks/<name>` whose TARGET is
+  // `.simt/hooks/<name>`: the same path. The shim overwrites the hook it was written to
   // preserve and then runs itself, so the hook stops working and git recurses in a loop
   // nothing reports. Confirmed at the previous release, which printed
   // `UPDATED .simt-hooks/mine (chained: runs .simt-hooks/mine)`.
@@ -298,9 +307,50 @@ export async function planHooksInstall(root, { manifest, exists }) {
     evidenceExisting,
     routed,
     takeover,
+    // The legacy directory's removal rides on the same planned write, so the
+    // scan is here and the deletion is in `applyHooksInstall` (ADR-122).
+    legacy: await legacyHooksScan(root),
   };
 }
 
+/**
+ * Scan the legacy top-level shim directory (ADR-122). A repository installed
+ * before the move into the state directory still carries it, and it is
+ * removable only when every entry in it is a regular file that carries a
+ * simt-dev marker: the install re-routes git to the new directory, and a
+ * file this tool cannot recognise as its own is never deleted on its way.
+ *
+ * @returns {Promise<{path: string, removable: boolean}|null>} null when the
+ *   directory is absent or empty; otherwise the directory and whether the
+ *   install may take it down. `applyHooksInstall` acts on this, so the
+ *   judgment is made once, in the plan. Module-local: one caller needs no
+ *   export, and an export is a promise to a caller (deadcode).
+ */
+async function legacyHooksScan(root) {
+  const dir = join(root, HOOKS_DIR_LEGACY);
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return null;
+  }
+  if (entries.length === 0) return null;
+  let removable = true;
+  for (const name of entries) {
+    const st = await stat(join(dir, name));
+    if (!st.isFile()) {
+      removable = false;
+      break;
+    }
+    const text = await readFile(join(dir, name), 'utf8');
+    if (!text.includes(SHIM_MARKER) && !text.includes(CHAIN_MARKER)) {
+      removable = false;
+      break;
+    }
+  }
+  return { path: HOOKS_DIR_LEGACY, removable };
+}
+
 /**
  * Write a planned install: shims, chains, removals, and the git routing (plan 0003 R47).
  *
@@ -309,10 +359,11 @@ export async function planHooksInstall(root, { manifest, exists }) {
  * names the run that actually changed something. Reporting stays with the
  * caller for the same reason it does in `planHooksInstall`.
  *
- * @returns {{wrote: string[]}} the shim paths written, removed, or refreshed
+ * @returns {{wrote: string[], removed: string[]}} the shim paths written,
+ *   removed or refreshed, and the legacy-directory files taken down
  */
 export async function applyHooksInstall(root, planned, journal) {
-  const { wanted, chained, obsolete, evidenceSource, evidenceFile, npm, manager, version, routed, wants, current } =
+  const { wanted, chained, obsolete, evidenceSource, evidenceFile, npm, manager, version, routed, wants, current, legacy } =
     planned;
   // Shim and evidence bytes are journaled so `undo` restores them (R49), with
   // the executable bit they are written with: a shim the run chmodded is one
@@ -322,27 +373,33 @@ export async function applyHooksInstall(root, planned, journal) {
   // at their directory silently stops the repository's own hooks (review 0003
   // Q22).
   const wrote = [];
+  const removed = [];
   await mkdir(join(root, HOOKS_DIR), { recursive: true });
+  const hookChanges = [];
   for (const event of wanted) {
     const path = join(root, fileFor(event));
-    await journaledWriteFile(root, journal, path, renderShim(event, { npm, manager, version }), { mode: 0o755 });
+    hookChanges.push(change({ path, before: await readBefore(path), after: renderShim(event, { npm, manager, version }), owner: 'hooks install', reason: event, mode: 0o755 }));
     wrote.push(fileFor(event));
   }
   for (const c of chained) {
     const path = join(root, fileFor(c.event));
-    await journaledWriteFile(root, journal, path, renderChainedShim(c.event, c.target), { mode: 0o755 });
+    hookChanges.push(change({ path, before: await readBefore(path), after: renderChainedShim(c.event, c.target), owner: 'hooks install', reason: c.event, mode: 0o755 }));
     wrote.push(fileFor(c.event));
   }
   for (const h of obsolete) {
-    await journaledRemoveFile(root, journal, join(root, fileFor(h.event)));
+    const obsoletePath = join(root, fileFor(h.event));
+    hookChanges.push(
+      change({ path: obsoletePath, kind: 'remove', before: await readBefore(obsoletePath), after: null, owner: 'hooks install', reason: h.event }),
+    );
     wrote.push(fileFor(h.event));
   }
   // After the chain loop, so a chained commit-msg cannot replace the claim check.
   if (evidenceSource) {
     const path = join(root, evidenceFile);
-    await journaledWriteFile(root, journal, path, evidenceSource, { mode: 0o755 });
+    hookChanges.push(change({ path, before: await readBefore(path), after: evidenceSource, owner: 'hooks install', reason: 'the evidence shim', mode: 0o755 }));
     wrote.push(evidenceFile);
   }
+  await applyPlan(root, hookChanges, { mode: { apply: true }, journal, commit: false });
   // `core.hooksPath` tells git to read ONE directory for EVERY event, so leaving it
   // pointing at a directory of no shims stops the repository's own hooks - the ones in
   // `.git/hooks` that predate this tool - from running, silently. Unsetting it is the
@@ -352,7 +409,20 @@ export async function applyHooksInstall(root, planned, journal) {
   } else if (current === wants) {
     await journaledGitConfig(root, journal, HOOKS_PATH_KEY, null);
   }
-  return { wrote };
+  // The move into the state directory (ADR-122): the routing now points
+  // elsewhere, so a legacy directory left behind is the only place that looks
+  // like a hooks directory while holding nothing git reads. The scan in the
+  // plan already judged it removable — every file a simt-dev marker — so
+  // deletion is journaled per file, and `undo` restores the directory.
+  if (legacy?.removable) {
+    for (const name of await readdir(join(root, HOOKS_DIR_LEGACY))) {
+      await journaledRemoveFile(root, journal, join(root, HOOKS_DIR_LEGACY, name));
+      removed.push(`${HOOKS_DIR_LEGACY}/${name}`);
+    }
+    await rm(join(root, HOOKS_DIR_LEGACY), { recursive: true });
+  }
+  return { wrote, removed };
+
 }
 
 /**
@@ -382,8 +452,8 @@ export async function plannedDiffs(root, planned) {
   return pairs;
 }
 
-async function installHooks(root, flags) {
-  const { manifest, exists, error } = await readManifest(root);
+async function installHooks(root, flags, ctx = repoContext(root)) {
+  const { manifest, exists, error } = await ctx.manifest();
   if (error) return fail(`${MANIFEST_FILE}: ${error}`, EXIT.CONFIG);
   if (!exists) {
     return fail(`${root} has no ${MANIFEST_FILE}; gates must be declared before hooks can run them`, EXIT.CONFIG, `run: ${CLI} init --root ${root}`);
@@ -409,7 +479,8 @@ async function installHooks(root, flags) {
     evidenceExisting,
     routed,
     takeover,
-  } = await planHooksInstall(root, { manifest, exists });
+    legacy,
+  } = await planHooksInstall(root, { manifest, exists }, ctx);
 
   // Read through `writeMode` like every other writer, and only now: this command
   // used to consult `flags.yes` and `flags.dryRun` directly and write when neither
@@ -438,7 +509,6 @@ async function installHooks(root, flags) {
         '         and replace it with a gate that checks nothing.',
         `REMEDY  add the gates this repo can actually run to ${MANIFEST_FILE}, then re-run.`,
       ].join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return EXIT.FAIL;
   }
@@ -487,11 +557,21 @@ async function installHooks(root, flags) {
       note: 'commit-msg checks a verification claim against the ledger',
     });
   }
+  if (legacy?.removable) {
+    plan.push({
+      file: HOOKS_DIR_LEGACY,
+      action: 'removed',
+      // Named in the plan for the same reason the obsolete shims are: the
+      // reader approving this write is about to lose a directory, and the
+      // routing line above does not say the old one goes too (ADR-122).
+      note: `legacy shim directory; the shims now live in ${HOOKS_DIR}`,
+    });
+  }
 
   // The routing this install leaves behind, which is not always `wants`. A repository
   // that removed its last gate has no shims to route to, and leaving `core.hooksPath`
   // pointed at the directory would stop its own hooks running - the plan has to say so,
-  // because a plan that prints "core.hooksPath updated .simt-hooks -> .simt-hooks" while
+  // because a plan that prints "core.hooksPath updated .simt/hooks -> .simt/hooks" while
   // the command unsets it is worse than no plan.
   const leaves = routed ? wants : null;
   const pathAction =
@@ -521,7 +601,6 @@ async function installHooks(root, flags) {
         '         Taking over replaces that routing. Inspect the existing hooks first,',
         '         then re-run with --yes to accept, or set core.hooksPath yourself.',
       ].join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return EXIT.FAIL;
   }
@@ -566,7 +645,6 @@ async function installHooks(root, flags) {
           : `PLAN     nothing written; apply with: ${CLI} hooks install --root ${root} --yes`,
         manifest,
       ),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     // After the report: the report says what, the diff shows it (R50).
     emitDiffs(diffs, flags);
@@ -578,7 +656,7 @@ async function installHooks(root, flags) {
   const journal = [];
   await applyHooksInstall(
     root,
-    { wanted, chained, obsolete, evidenceSource, evidenceFile, npm, manager, version, routed, wants, current },
+    { wanted, chained, obsolete, evidenceSource, evidenceFile, npm, manager, version, routed, wants, current, legacy },
     journal,
   );
   await commitJournal(root, 'hooks install', journal);
@@ -655,7 +733,6 @@ async function installHooks(root, flags) {
       routed ? 'WROTE    shims and set core.hooksPath' : 'WROTE    no shims remain; core.hooksPath unset',
       manifest,
     ),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   // After the report: the report says what, the diff shows it (R50).
   emitDiffs(diffs, flags);
@@ -679,13 +756,13 @@ function describeGates(manifest, key) {
   const list = manifest?.gates?.[key];
   if (!Array.isArray(list) || list.length === 0) return '(none declared)';
   return list.map((name) => {
-    const gate = GATES[name];
+    const gate = getGate(name, manifest?.gates?.commands);
     return gate ? name : `${name} (UNKNOWN - the hook will fail)`;
   }).join(', ');
 }
 
-async function hooksStatus(root, flags) {
-  const { manifest, exists, error } = await readManifest(root);
+async function hooksStatus(root, flags, ctx = repoContext(root)) {
+  const { manifest, exists, error } = await ctx.manifest();
   if (error) return fail(`${MANIFEST_FILE}: ${error}`, EXIT.CONFIG);
 
   const state = await readHooksState(root, { declaresGate: (e) => wantsShim(manifest, exists, e) });
@@ -748,7 +825,7 @@ async function hooksStatus(root, flags) {
     lines.push('', 'would run:');
     for (const key of ['preCommit', 'prePush']) {
       for (const name of manifest?.gates?.[key] ?? []) {
-        const known = GATES[name];
+        const known = getGate(name, commands);
         // A declared command wins for every kind, so the status must say so too —
         // printing "run script" for a gate the dispatcher will shell out to `./gradlew`
         // for is the same one-question-two-answers defect ADR-018 was written about.
@@ -767,17 +844,17 @@ async function hooksStatus(root, flags) {
     if (undeclared.length > 0) {
       lines.push('', `declared but never run: ${undeclared.join(', ')}`);
     }
-    const unknown = [...(manifest?.gates?.preCommit ?? []), ...(manifest?.gates?.prePush ?? [])].filter((n) => !GATES[n]);
+    const unknown = [...(manifest?.gates?.preCommit ?? []), ...(manifest?.gates?.prePush ?? [])].filter((n) => !getGate(n, commands));
     if (unknown.length > 0) {
       lines.push('', `unknown gates (the hook will fail): ${unknown.join(', ')}`);
-      lines.push(`known gates: ${knownGates().join(', ')}`);
+      lines.push(`known gates: ${gateNames().join(', ')}`);
     }
   }
   if (problems.length > 0) {
     lines.push('', 'problems:');
     for (const p of problems) lines.push(`  ${p}`);
   }
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return code;
 }
 
@@ -799,8 +876,9 @@ function collectProblems({ exists, current, installed, manifest, foreign = [] })
   if (exists) {
     for (const key of ['preCommit', 'prePush']) {
       for (const name of manifest?.gates?.[key] ?? []) {
-        if (!GATES[name]) problems.push(`gate "${name}" in ${key} is not a known gate`);
-        else if (GATES[name].kind === 'command' && !manifest?.gates?.commands?.[name]) {
+        const gate = getGate(name, manifest?.gates?.commands);
+        if (!gate) problems.push(`gate "${name}" in ${key} is not a known gate`);
+        else if (gate.kind === 'command' && !manifest?.gates?.commands?.[name]) {
           problems.push(`gate "${name}" in ${key} is a command gate with no declared command; the hook will fail`);
         }
       }
@@ -808,11 +886,3 @@ function collectProblems({ exists, current, installed, manifest, foreign = [] })
   }
   return problems;
 }
-
-async function readIfExists(path) {
-  try {
-    return await readFile(path, 'utf8');
-  } catch {
-    return null;
-  }
-}