simt-dev 0.6.2 → 0.6.3

package/src/commands/help.mjs

@@ -1,13 +1,18 @@
-import { emit } from '../output/index.mjs';
-import { parse } from '../argv.mjs';
-import { CLI, MANIFEST_FILE } from '../name.mjs';
+import { emit, fail, jsonFailMode } from '../output/index.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';
 
 const COMMANDS = `${CLI} init [path]            adopt or scaffold a repo into the ecosystem
                            (dry-run unless --yes; conflicts block without
                            --accept-conflicts; in place unless --backup;
                            never commits or pushes)
-${CLI} doctor                 classify a repo and check config health
+${CLI} doctor [--fix]        classify a repo and check config health (with --fix:
+                           apply the remedies flagged safe and list the rest;
+                           dry-run unless --yes)
+${CLI} status --line         one line from the last check, for prompts and tmux
+                           (as of the last check; STALE after new commits)
 ${CLI} check                  the gate: projection drift, manifest validity, policy
 ${CLI} sync [--yes]           regenerate the projection (idempotent)
                            (prints the plan and exits 1 on drift without --yes,
@@ -58,20 +63,41 @@ ${CLI} agent-hooks install     write this repo's policies into the harnesses tha
                             key it does not own; Codex needs the hook trusted)
 ${CLI} agent-hooks status      what each harness will run, and what is not trusted yet
 ${CLI} plugin <claude|gemini|cursor>  generate a harness package from the same tables
-                            (dry-run unless --yes; writes a self-contained runtime, the
-                            hooks and MCP registration, and for cursor the kernel rules;
-                            the skill registry is workspace data and is not shipped)
+                           (dry-run unless --yes; writes a self-contained runtime, the
+                           hooks and MCP registration, and for cursor the kernel rules;
+                           the skill registry is workspace data and is not shipped)
+${CLI} completions <shell>    print a bash, zsh or fish completion script
+                           (generated from the command registry, so every command
+                           completes; deterministic bytes; stdout only - redirect
+                           or source it)
 ${CLI} plan status             count tracker rows
                            (${MANIFEST_FILE} key plans when set, otherwise
                            the ${DEFAULT_TEMPLATE} template:
                            ${DEFAULT_DIRECTORIES.join(' and ')})
 ${CLI} plan next [<id>]        one ready slice's section, or the one named; ~1 KB
 ${CLI} plan done <id> [<sha>]  mark one row; dry-run unless --yes
+${CLI} slice start <id>     give a slice its own worktree and branch, preload the
+                           brief, and mark the row In progress (dry-run unless
+                           --yes; the worktree is ${STATE_DIR}/worktrees/<id> on
+                           branch slice/<id>, the brief ${STATE_DIR}/brief.md in it)
+${CLI} slice finish <id>    run the pre-commit gates, commit what is staged with a
+                           Conventional subject from the row's title, then record
+                           the SHA and the --test command on the row (dry-run
+                           unless --yes; --type picks the type, default feat)
+${CLI} lease [<paths>...]    claim files for one session and a TTL, or list the
+                           claims (dry-run unless --yes; the session is --session
+                           <id> or ${SESSION_ENV}; a pre-edit hook refuses an edit
+                           to a path another session holds — ADR-101)
 ${CLI} graph lint              check the skill registry against the skills on disk
                            (byte counts, dangling edges, unresolvable variants)
 ${CLI} ci                     simt-dev's own .github files: create or refresh them
                            (dry-run unless --yes; refreshes the templates' own copies
                             and no repository else's)
+${CLI} ignore [--yes]         render the one .simtignore list into .cursorignore,
+                           .aiderignore, .geminiignore and Claude's
+                           permissions.deny Read(...) entries (dry-run unless
+                           --yes; --diff prints the plan as unified diffs; the
+                           Claude settings file is merged, never replaced)
 ${CLI} compare                org-wide matrix across every sibling repo
                            (read-only; exits non-zero on defects, not on
                            repos that have not adopted yet)
@@ -93,6 +119,11 @@ ${CLI} map [--task "<text>"] [--level outline|names|signatures]
                            --budget bytes (default 2048; 0 is unlimited). outline
                            is paths, names adds exports, signatures adds the line.
                            --recall reports gold-file recall@10 on mined tasks
+${CLI} pr-body [--base <ref>]  a pull request body: the evidence block for this tree,
+                           the decision records the diff touches, the gate
+                           state from the last check, and the residual risk
+                           in ADR-008 vocabulary (read-only; the exit code
+                           never carries the verdict)
 ${CLI} evidence                the runs recorded against the tree on disk
 ${CLI} evidence check <file>   a commit message that claims a run this tree does not
                            have: a warning, or a block when gates.evidence is "block"
@@ -100,10 +131,17 @@ ${CLI} lessons list            deterministic lesson candidates in .simt/lessons.
                            and promoted lessons in docs/lessons/*.md
 ${CLI} lessons review [<id>]   promote a lesson candidate to docs/lessons/NNNN-<slug>.md
                            (dry-run unless --yes; writes Appendix A 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)
 ${CLI} decide [<title>]        scaffold an ADR with the next free number, a Status: line,
                            a rulings skeleton, and structured simt-affects +
                            simt-supersedes frontmatter (dry-run unless --yes;
                            --check lints ADRs for prose-only partial supersessions)
+${CLI} undo                  restore the last journaled set of writes, but only
+                           when every file in it is untouched since (dry-run
+                           unless --yes; a touched file refuses the whole undo
+                           and nothing is restored)
 ${CLI} local doctor            probe configured local model endpoints (chat and embed)
                            (reads local in ${MANIFEST_FILE}; opens no socket when
                            unset; refuses non-loopback URLs without --allow-remote)
@@ -192,6 +230,9 @@ const FLAGS = `--json                 structured output (compact; one document,
 --task "<text>"         the task text used for capability resolution
 --paths <globs>         comma-separated path globs used for path resolution
 --root <path>           repository root (default: cwd)
+--base <ref>           pr-body: the ref the body diffs against
+                        (default: origin/main, then main; falls back to the
+                        worktree diff against HEAD when neither exists)
 --out <path>            plugin: where the generated package lands (required)
 --surfaces <ids>        comma-separated editors to write rule files for;
                          "" means AGENTS.md only (default: every surface,
@@ -202,6 +243,13 @@ const FLAGS = `--json                 structured output (compact; one document,
 --dry-run               report what would change, change nothing
 --yes                   assume yes; required in automation, never prompts
 --check                 report drift and write nothing (sync, ci)
+--diff                  print the plan as unified diffs (every writer;
+                        changes nothing about what the run writes)
+--line                  status: print the one-line gate summary from the last
+                        check (the only mode status has)
+--fix                   doctor: apply the remedies flagged safe (local,
+                        idempotent, journaled); list the rest (dry-run
+                        unless --yes)
 --frozen                check: the lock must match this projection; an output
                         change no input change explains fails the gate
 --explain               sync: name each line dropped as already inferable, with
@@ -238,8 +286,10 @@ const FLAGS = `--json                 structured output (compact; one document,
 --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
 --compare <a> <b>       bench report: compare two arms with deltas and p-values
---test <cmd>            plan done: the test command that closes the row
+--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)
+--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)
 --source <spec>         pack new: where the pack's bytes come from
@@ -268,9 +318,12 @@ const PRINCIPLES = `design rules:
   bounded output      one fact per line, fixed field order, explicit TRUNCATED lines`;
 
 export async function help(argv) {
-  const { ok, value } = parse(argv);
-  if (!ok) return value.code;
-  const { flags } = value;
+  const parsed = parse(argv);
+  if (!parsed.ok) {
+    jsonFailMode(rawJsonFlag(argv));
+    return fail(parsed.error.message, parsed.error.code);
+  }
+  const { flags } = parsed.value;
   if (flags.version) {
     emit((await version()).trim());
     return 0;
@@ -300,10 +353,6 @@ export async function help(argv) {
 }
 
 async function version() {
-  const { readFile } = await import('node:fs/promises');
-  const { fileURLToPath } = await import('node:url');
-  const { dirname, join } = await import('node:path');
-  const root = join(dirname(fileURLToPath(import.meta.url)), '..');
-  const pkg = JSON.parse(await readFile(join(root, '..', 'package.json'), 'utf8'));
-  return `simt-dev ${pkg.version}\n`;
+  const { describeVersion } = await import('../package-version.mjs');
+  return `${describeVersion()}\n`;
 }

package/src/commands/hooks.mjs

@@ -13,7 +13,10 @@
 // foreign hook is found by asking git rather than by reading config.
 
 import { execFile } from 'node:child_process';
-import { chmod, mkdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, readFile, realpath } from 'node:fs/promises';
+import { commitJournal, journaledRemoveFile, journaledWriteFile } from '../journal.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
+import { invalidateCheckCache } from '../status.mjs';
 import { isAbsolute, join, relative } from 'node:path';
 import { promisify } from 'node:util';
 
@@ -23,7 +26,7 @@ import { EVENTS, HOOKS_DIR, HOOKS_PATH_KEY, SHIM_MARKER, fileFor, renderChainedS
 import { GATE_KEY, gateCount, readHooksPath, readHooksState, wantsShim } from '../compare/hooksstate.mjs';
 import { GATES } from '../hooks/gates.mjs';
 import { knownGates } from '../hooks/resolve.mjs';
-import { runGates } from '../hooks/dispatcher.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';
@@ -60,14 +63,7 @@ async function runHook(args, flags) {
   }
 
   for (const n of result.notes ?? []) note(`note     ${n}`);
-  const lines = [`hooks    ${event}`, `gates    ${(manifest.gates[GATE_KEY[event]] ?? []).join(', ') || '(none declared)'}`];
-  for (const g of result.gates) {
-    lines.push(`${g.status.toUpperCase().padEnd(8)} ${g.name.padEnd(20)} ${g.detail}${g.adr ? `  [${g.adr}]` : ''}`);
-    if (g.remedy) lines.push(`        remedy: ${g.remedy}`);
-    if (g.output) lines.push(...g.output.split('\n').map((l) => `        ${l}`));
-  }
-  lines.push(result.failed ? 'BLOCKED  at least one gate failed' : 'PASSED');
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(renderGateReport(event, manifest.gates[GATE_KEY[event]] ?? [], result).join('\n'), { maxBytes: flags.maxBytes ?? 0 });
   return result.failed ? EXIT.FAIL : EXIT.OK;
 }
 
@@ -101,27 +97,26 @@ async function relativeTarget(root, target) {
   return rel === '' || rel.startsWith('..') ? resolved : rel;
 }
 
-async function installHooks(root, flags) {
-  const { manifest, exists, error } = await readManifest(root);
-  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}`);
-  }
-
+/**
+ * What `hooks install` would write, computed without writing or reporting (plan 0003 R47).
+ *
+ * `installHooks` and `doctor --fix` share this rather than each deriving the write
+ * set: the set nothing else here touches (obsolete shims, chained foreign hooks)
+ * is exactly the set a second derivation gets wrong, and a fix that writes bytes
+ * the command would not is a fix that lies about what it did. Reporting stays
+ * with the callers — the plan table belongs to the command, the finding line to
+ * the doctor — so this returns facts, never text.
+ *
+ * @returns the install inputs `applyHooksInstall` needs, plus the guards each
+ *   caller enforces in its own voice (`takeover`, and the `wanted`/`obsolete`
+ *   emptiness the command refuses on)
+ */
+export async function planHooksInstall(root, { manifest, exists }) {
   const declaresGate = (event) => wantsShim(manifest, exists, event);
   const state = await readHooksState(root, { declaresGate });
   const current = state.current;
   const wants = HOOKS_DIR;
 
-  // 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
-  // said otherwise, which made it the last writer still writing by default after
-  // ADR-035 and ADR-036 had settled that none of them may. Review 0002's S24
-  // listed it among the writers that "all preview first"; that was wrong, and the
-  // migration script in the same review tells an operator to run `hooks install`
-  // for a plan and then `--yes` - advice that printed a plan and wrote anyway.
-  const mode = writeMode(flags);
-
   // The release this install renders, and the kind of repository it installs into: the
   // remedy a shim prints when it cannot find the binary must name the install that
   // actually works here — a devDependency where package.json exists, a pinned global
@@ -240,6 +235,148 @@ async function installHooks(root, flags) {
     if (at !== -1) chained.splice(at, 1);
   }
 
+  const routed = wanted.length > 0 || chained.length > 0 || evidenceDeclared;
+  const takeover = (current !== null && current !== wants) || state.foreign.length > 0;
+  return {
+    manifest,
+    state,
+    current,
+    wants,
+    npm,
+    version,
+    wanted,
+    chained,
+    leftRunning,
+    obsolete,
+    evidenceDeclared,
+    evidenceSource,
+    evidenceFile,
+    // Returned so a caller can tell a current claim check from a stale one
+    // without re-reading the file: the evidence shim is not one of EVENTS, so
+    // neither the problems list nor the obsolete set names its staleness.
+    evidenceExisting,
+    routed,
+    takeover,
+  };
+}
+
+/**
+ * Write a planned install: shims, chains, removals, and the git routing (plan 0003 R47).
+ *
+ * The caller's journal records the file writes, and the caller commits it under
+ * its own command name — `hooks install` here, `doctor --fix` there — so `undo`
+ * 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
+ */
+export async function applyHooksInstall(root, planned, journal) {
+  const { wanted, chained, obsolete, evidenceSource, evidenceFile, npm, version, routed, wants, current } =
+    planned;
+  // Shim and evidence bytes are journaled so `undo` restores them (R49). The
+  // `core.hooksPath` config below is deliberately not journaled: it is git
+  // config, not a repo file, and `undo` restores files.
+  const wrote = [];
+  await mkdir(join(root, HOOKS_DIR), { recursive: true });
+  for (const event of wanted) {
+    const path = join(root, fileFor(event));
+    await journaledWriteFile(root, journal, path, renderShim(event, { npm, version }));
+    await chmod(path, 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));
+    await chmod(path, 0o755);
+    wrote.push(fileFor(c.event));
+  }
+  for (const h of obsolete) {
+    await journaledRemoveFile(root, journal, join(root, fileFor(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);
+    await chmod(path, 0o755);
+    wrote.push(evidenceFile);
+  }
+  // `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
+  // only way back, and this is the only place that knows the last shim just left.
+  if (routed) {
+    await exec('git', ['config', HOOKS_PATH_KEY, wants], { cwd: root });
+  } else if (current === wants) {
+    await exec('git', ['config', '--unset', HOOKS_PATH_KEY], { cwd: root });
+  }
+  return { wrote };
+}
+
+/**
+ * The `--diff` pairs for a planned install: current disk against what the
+ * install would write, re-rendered from the same inputs `applyHooksInstall`
+ * writes (plan 0003 R50). Read-only, so preview and apply share it, and
+ * `doctor --fix` reuses it rather than deriving a second answer.
+ */
+export async function plannedDiffs(root, planned) {
+  const { wanted, chained, obsolete, evidenceSource, evidenceFile, npm, version } = planned;
+  const pairs = [];
+  for (const event of wanted) {
+    const path = fileFor(event);
+    pairs.push({ path, before: await readBefore(join(root, path)), after: renderShim(event, { npm, version }) });
+  }
+  for (const c of chained) {
+    const path = fileFor(c.event);
+    pairs.push({ path, before: await readBefore(join(root, path)), after: renderChainedShim(c.event, c.target) });
+  }
+  for (const h of obsolete) {
+    const path = fileFor(h.event);
+    pairs.push({ path, before: await readBefore(join(root, path)), after: null });
+  }
+  if (evidenceSource) {
+    pairs.push({ path: evidenceFile, before: await readBefore(join(root, evidenceFile)), after: evidenceSource });
+  }
+  return pairs;
+}
+
+async function installHooks(root, flags) {
+  const { manifest, exists, error } = await readManifest(root);
+  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}`);
+  }
+
+  // One computation, two callers (R47): the write set is derived once in
+  // `planHooksInstall` and shared with `doctor --fix`, so a fix applies exactly
+  // the bytes this command would write. Reporting stays here.
+  const {
+    state,
+    current,
+    wants,
+    npm,
+    version,
+    wanted,
+    chained,
+    leftRunning,
+    obsolete,
+    evidenceDeclared,
+    evidenceSource,
+    evidenceFile,
+    evidenceExisting,
+    routed,
+    takeover,
+  } = await planHooksInstall(root, { manifest, exists });
+
+  // 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
+  // said otherwise, which made it the last writer still writing by default after
+  // ADR-035 and ADR-036 had settled that none of them may. Review 0002's S24
+  // listed it among the writers that "all preview first"; that was wrong, and the
+  // migration script in the same review tells an operator to run `hooks install`
+  // for a plan and then `--yes` - advice that printed a plan and wrote anyway.
+  const mode = writeMode(flags);
+
   // Nothing to write and nothing to take away is the only refusal. It sits after
   // `obsolete` because a repository whose last gate just left the manifest has
   // something to take away, and blocking that one left no way out except undoing
@@ -307,7 +444,6 @@ async function installHooks(root, flags) {
       note: 'commit-msg checks a verification claim against the ledger',
     });
   }
-  const routed = wanted.length > 0 || chained.length > 0 || evidenceDeclared;
 
   // 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`
@@ -324,7 +460,6 @@ async function installHooks(root, flags) {
   // being unset while a hook sits in the default location (4 KB of real logic in
   // .git/hooks/pre-commit). Reading unset as
   // "no hooks" is what let install replace a working gate with no warning.
-  const takeover = (current !== null && current !== wants) || state.foreign.length > 0;
   if (takeover && !flags.yes) {
     const detail = state.foreign.length > 0
       ? state.foreign.map((f) => `  git runs ${f.event} at ${f.path} (${f.bytes} bytes)`)
@@ -348,12 +483,29 @@ async function installHooks(root, flags) {
     return EXIT.FAIL;
   }
 
+  // The `--diff` pairs, read before anything is written so the before side is
+  // true in preview and in apply alike (R50).
+  const diffs =
+    flags.diff === true
+      ? await plannedDiffs(root, { wanted, chained, obsolete, evidenceSource, evidenceFile, npm, version })
+      : [];
+
   if (!mode.apply) {
     if (isJson(flags)) {
       // `leaves`, not `wants`. A plan that would remove the last shim also un-routes
       // git, and a payload promising to set a directory the command is about to unset
       // is the same lie in a shape a machine reads.
-      emitJson({ ok: true, command: 'hooks install', root, dryRun: true, currentHooksPath: current, wouldSet: leaves, plan, filesWritten: false });
+      emitJson({
+        ok: true,
+        command: 'hooks install',
+        root,
+        dryRun: true,
+        currentHooksPath: current,
+        wouldSet: leaves,
+        plan,
+        filesWritten: false,
+        ...diffField(diffs, flags),
+      });
       return EXIT.OK;
     }
     emit(
@@ -373,39 +525,23 @@ async function installHooks(root, flags) {
       ),
       { maxBytes: flags.maxBytes ?? 0 },
     );
+    // After the report: the report says what, the diff shows it (R50).
+    emitDiffs(diffs, flags);
     return EXIT.OK;
   }
 
-  await mkdir(join(root, HOOKS_DIR), { recursive: true });
-  for (const event of wanted) {
-    const path = join(root, fileFor(event));
-    await writeFile(path, renderShim(event, { npm, version }));
-    await chmod(path, 0o755);
-  }
-  for (const c of chained) {
-    const path = join(root, fileFor(c.event));
-    await writeFile(path, renderChainedShim(c.event, c.target));
-    await chmod(path, 0o755);
-  }
-  for (const h of obsolete) {
-    await rm(join(root, 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 writeFile(path, evidenceSource);
-    await chmod(path, 0o755);
-  }
-
-  // `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
-  // only way back, and this is the only place that knows the last shim just left.
-  if (routed) {
-    await exec('git', ['config', HOOKS_PATH_KEY, wants], { cwd: root });
-  } else if (current === wants) {
-    await exec('git', ['config', '--unset', HOOKS_PATH_KEY], { cwd: root });
-  }
+  // Same bytes, two callers (R47): the write itself lives in `applyHooksInstall`
+  // and is shared with `doctor --fix`, so a fix installs what the command would.
+  const journal = [];
+  await applyHooksInstall(
+    root,
+    { wanted, chained, obsolete, evidenceSource, evidenceFile, npm, version, routed, wants, current },
+    journal,
+  );
+  await commitJournal(root, 'hooks install', journal);
+  // Shims and routing changed, so the hooks slot of the last `check` is stale
+  // (R48). Gated on the journal: an already-current install changes nothing.
+  if (journal.length > 0) await invalidateCheckCache(root);
 
   const notes = [];
   const chainedEvents = new Set(chained.map((c) => c.event));
@@ -453,7 +589,17 @@ async function installHooks(root, flags) {
   }
 
   if (isJson(flags)) {
-    emitJson({ ok: true, command: 'hooks install', root, hooksPath: leaves, previousHooksPath: current, plan, filesWritten: true, notes });
+    emitJson({
+      ok: true,
+      command: 'hooks install',
+      root,
+      hooksPath: leaves,
+      previousHooksPath: current,
+      plan,
+      filesWritten: true,
+      notes,
+      ...diffField(diffs, flags),
+    });
     return EXIT.OK;
   }
   emit(
@@ -468,6 +614,8 @@ async function installHooks(root, flags) {
     ),
     { maxBytes: flags.maxBytes ?? 0 },
   );
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
   for (const n of notes) note(`note     ${n}`);
   note(`note     never committed or pushed (ADR-001); review, then commit yourself`);
   return EXIT.OK;

package/src/commands/ignore.mjs

@@ -0,0 +1,152 @@
+// `simt ignore` — render the one ignore list into every reader's dialect
+// (plan 0003 R52).
+//
+// Shape copied from `ci`: the plan is printed first, nothing is written
+// without `--yes`, `--diff` shows the same plan as unified diffs and `undo`
+// restores the set (R49). Three of the four targets are generated from the
+// list; `.claude/settings.json` is merged, never replaced — see src/ignore.mjs
+// for why that distinction exists.
+
+import { join } from 'node:path';
+
+import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
+import { CLAUDE_SETTINGS, IGNORE_FILE, parseIgnoreList, planIgnore } from '../ignore.mjs';
+
+export async function ignoreCommand(args, flags) {
+  const root = flags.root ?? process.cwd();
+
+  let source;
+  try {
+    source = await readBefore(join(root, IGNORE_FILE));
+  } catch (error) {
+    return fail(`${IGNORE_FILE} could not be read: ${error.message}`, EXIT.FAIL, `fix the file's permissions, then re-run: ${CLI} ignore`);
+  }
+  if (source === null) {
+    // A missing list is a missing input, not an empty one: rendering four empty
+    // files from a file that does not exist would answer the request with
+    // silence the reader has no way to tell from success.
+    return fail(
+      `no ${IGNORE_FILE} in ${root}`,
+      EXIT.FAIL,
+      `create ${IGNORE_FILE} with one path or glob per line (# comments), then: ${CLI} ignore`,
+    );
+  }
+
+  const entries = parseIgnoreList(source);
+  if (entries.length === 0) {
+    return fail(
+      `${IGNORE_FILE} parses to zero entries`,
+      EXIT.FAIL,
+      `add one path or glob per line to ${IGNORE_FILE}, then: ${CLI} ignore`,
+    );
+  }
+
+  const plan = await planIgnore(entries, (path) => readBefore(join(root, path)));
+  if (!plan.ok) {
+    return fail(plan.error, EXIT.FAIL, `repair ${CLAUDE_SETTINGS} by hand, then re-run: ${CLI} ignore`);
+  }
+
+  const mode = writeMode(flags);
+  const changed = plan.targets.filter((t) => t.action !== 'unchanged');
+  const diffs =
+    flags.diff === true
+      ? changed.map((t) => ({ path: t.path, before: t.before, after: t.after }))
+      : [];
+
+  // Nothing to do: the report says so from the same plan the write would have
+  // used, so "unchanged" cannot disagree with what `--yes` would have written.
+  if (changed.length === 0) {
+    if (isJson(flags)) {
+      emitJson({
+        ok: true,
+        command: 'ignore',
+        root,
+        source: IGNORE_FILE,
+        entries: entries.length,
+        files: plan.targets.map((t) => ({ path: t.path, action: t.action, bytes: byteLen(t.after) })),
+        written: false,
+        dryRun: false,
+      });
+    } else {
+      emit(plan.targets.map((t) => `current  ${t.path}  ${byteLen(t.after)} bytes`).join('\n'));
+      note('every target already matches the list; nothing to write');
+    }
+    return EXIT.OK;
+  }
+
+  const lines = [
+    `repo      ${root}`,
+    `source    ${IGNORE_FILE} (${entries.length} entr${entries.length === 1 ? 'y' : 'ies'})`,
+    '',
+  ];
+  for (const t of plan.targets) {
+    lines.push(`file      ${t.path}`, `action    ${t.action}`);
+    if (t.action === 'update' && t.before !== null) {
+      // An update whose before side has lines the list does not: those lines
+      // are about to stop existing. Named here because a preview that only says
+      // "update" hides the deletion inside the diff the reader has to ask for.
+      const dropped = countDropped(t.before, t.after);
+      if (dropped > 0) lines.push(`replaces  ${dropped} line(s) not in ${IGNORE_FILE} (shown by --diff)`);
+    }
+  }
+
+  // Exactly one JSON document per run, emitted once on whichever path ends it:
+  // a preview and its write are two phases of ONE answer, and a reader that
+  // parses the first document gets "written: false" while the run writes.
+  const payload = (written) => ({
+    ok: true,
+    command: 'ignore',
+    root,
+    source: IGNORE_FILE,
+    entries: entries.length,
+    files: plan.targets.map((t) => ({ path: t.path, action: t.action, bytes: byteLen(t.after) })),
+    written,
+    dryRun: !mode.apply,
+    ...diffField(diffs, flags),
+  });
+
+  if (!isJson(flags)) emit(lines.join('\n'));
+
+  if (!mode.apply) {
+    // After the report: the report says what, the diff shows it (R50).
+    emitDiffs(diffs, flags);
+    if (isJson(flags)) {
+      emitJson(payload(false));
+    } else {
+      note('');
+      note(mode.dryRun ? 'dry-run  nothing written' : `dry-run  nothing written; apply with: ${CLI} ignore --yes`);
+    }
+    return EXIT.OK;
+  }
+
+  // Journaled so `undo` restores this run (R49). Every note writes to stderr,
+  // so the `--json` document remains the only bytes on stdout.
+  const journal = [];
+  for (const t of changed) {
+    await journaledWriteFile(root, journal, join(root, t.path), t.after);
+    note(`wrote    ${t.path} (${t.action})`);
+  }
+  await commitJournal(root, 'ignore', journal);
+
+  if (isJson(flags)) emitJson(payload(true));
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
+  return EXIT.OK;
+}
+
+function byteLen(text) {
+  return Buffer.byteLength(text, 'utf8');
+}
+
+/**
+ * How many lines the new bytes drop from the old: lines the current file has
+ * that the list does not produce. Used only for the plan's `replaces` note —
+ * the diff is the authoritative statement of what goes.
+ */
+function countDropped(before, after) {
+  const kept = new Set(after.split('\n'));
+  return before.split('\n').filter((line) => line.trim() !== '' && !kept.has(line)).length;
+}