simt-dev 0.7.0 → 0.8.0

package/src/commands/agenthook.mjs

@@ -25,7 +25,8 @@
 import { existsSync } from 'node:fs';
 import { mkdir, readFile } from 'node:fs/promises';
 import { dirname, isAbsolute, join } from 'node:path';
-import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { commitJournal } from '../journal.mjs';
+import { applyPlan, change } from '../write/plan.mjs';
 import { AGENT_HOOK_SHIM, renderAgentHookShim } from '../agenthooks/shim.mjs';
 import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 
@@ -44,6 +45,7 @@ import {
   installedIn,
   rendered,
 } from '../agenthooks/render.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 export async function agentHookCommand(args, flags) {
   const event = args[0];
@@ -77,7 +79,7 @@ export async function agentHookCommand(args, flags) {
   // dynamic import that only this event opens.
   if (event === 'prompt-submit') {
     const { deliverPrompt } = await import('../agenthooks/prompt.mjs');
-    const delivered = await deliverPrompt(row, payload);
+    const delivered = await deliverPrompt(row, payload, { root: flags.root });
     if (delivered.skipped) {
       note(`note     ${id}: no packet delivered (${delivered.skipped})`);
       return EXIT.OK;
@@ -167,7 +169,7 @@ export async function agentHookCommand(args, flags) {
 }
 
 export async function agentHooksCommand(sub, args, flags) {
-  const root = flags.root ?? args[0] ?? process.cwd();
+  const root = commandRoot(flags, args);
   if (sub === 'install') return installHooks(root, flags);
   if (sub === 'status') return hooksStatus(root, flags);
   return fail(`unknown agent-hooks subcommand ${sub}`, EXIT.USAGE, `run: ${CLI} agent-hooks status`);
@@ -178,18 +180,26 @@ export async function agentHooksCommand(sub, args, flags) {
 // `skipped` was an adapter the caller did not ask for (ADR-107).
 const OTHER_LABEL = { none: 'NO FILE ', other: 'NOT OURS', skipped: 'SKIPPED ' };
 
-async function installHooks(root, flags) {
-  const mode = writeMode(flags);
+/**
+ * The agent-hooks install, split from `installHooks` into the plan and the apply so
+ * `init` can run the same writes inside its own journal (ADR-002: a second real use).
+ *
+ * The plan is pure: it reads each documented config, renders the entry, and returns the
+ * shim the same way, so a preview and an apply describe the same set of files. A config
+ * this tool cannot parse lands in `refused` with its action set to `refused`, and the
+ * caller decides what that means — this command blocks on it, and `init` inherits the
+ * refusal because writing the other configs while one is unreadable would leave the
+ * repository in a state where the report it printed is no longer true.
+ */
+export async function planAgentHooks(root, { harness }) {
   // `--harness` narrows the install to one reader (ADR-107). The id is validated
   // against the same table the loop reads, so a typo fails before anything is
   // planned; the remedy names the ids the way `agent-hook` does.
-  const selected = flags.harness;
-  if (selected !== undefined && adapter(selected) === null) {
-    return fail(
-      `unknown harness \`${selected}\``,
-      EXIT.USAGE,
-      `--harness <id>, one of: ${adapters().map((a) => a.id).join(', ')}`,
-    );
+  if (harness !== undefined && adapter(harness) === null) {
+    return {
+      error: `unknown harness \`${harness}\``,
+      remedy: `--harness <id>, one of: ${adapters().map((a) => a.id).join(', ')}`,
+    };
   }
   // The delivery is a second entry in the same config, and a repository asks for it by
   // declaring a `brief` key rather than by having the entry. Read through a dynamic
@@ -201,7 +211,7 @@ async function installHooks(root, flags) {
     listPromotedLessons(root).catch(() => []),
   ]);
   const hasLessons = promotedLessons.length > 0;
-  const rows = selected === undefined ? adapters() : adapters().filter((r) => r.id === selected);
+  const rows = harness === undefined ? adapters() : adapters().filter((r) => r.id === harness);
   const plan = [];
   for (const row of rows) {
     const path = hookPath(row.id);
@@ -231,7 +241,7 @@ async function installHooks(root, flags) {
   for (const r of hookRows()) {
     if (r.path === null) others.push({ id: r.id, path: null, state: 'none', note: r.note });
     else if (adapter(r.id) === null) others.push({ id: r.id, path: r.path, state: 'other', note: r.note });
-    else if (selected !== undefined && r.id !== selected) {
+    else if (harness !== undefined && r.id !== harness) {
       others.push({ id: r.id, path: r.path, state: 'skipped', note: 'not requested; install without --harness to write every harness' });
     }
   }
@@ -239,13 +249,48 @@ async function installHooks(root, flags) {
   const refused = plan.filter((p) => p.error);
 
   // The shim every harness config points at: without it the entries above name a
-  // binary no harness has on PATH (review 0003 Q21). Its remedy installs the
-  // dependency the same way the git shims' does — a devDependency where the
-  // repository has a package.json, the release binary where it does not.
+  // binary no harness has on PATH (review 0003 Q21).
   const shimText = renderAgentHookShim({ npm: (await readIfExists(join(root, 'package.json'))) !== null });
   const shimBefore = await readBefore(join(root, AGENT_HOOK_SHIM));
   const shimAction = shimBefore === null ? 'create' : shimBefore === shimText ? 'unchanged' : 'update';
-  const shimRow = { id: 'shim', path: AGENT_HOOK_SHIM, action: shimAction };
+  const shim = { text: shimText, before: shimBefore, action: shimAction, row: { id: 'shim', path: AGENT_HOOK_SHIM, action: shimAction } };
+
+  return { plan, shim, others, promptLine, refused };
+}
+
+/**
+ * Write the planned agent-hooks entries and the shim into the caller's journal. Nothing
+ * is committed here: the caller commits its own journal under its own label, which is
+ * what separates this command's run (a standalone `agent-hooks install`) from `init`'s
+ * absorbed one (part of the adoption, committed with the rest of it).
+ */
+export async function applyAgentHooks(root, journal, { plan, shim, owner }) {
+  const written = [];
+  const hookChanges = [];
+  for (const p of plan.filter((x) => x.action !== 'unchanged')) {
+    const path = join(root, p.path);
+    hookChanges.push(change({ path, before: await readBefore(path), after: p.text, owner, reason: p.action }));
+    written.push(p);
+  }
+  // The shim is a file like the configs: unchanged installs leave it alone, and a
+  // changed one is journaled so `undo` removes or restores it with the configs.
+  let shimWritten = false;
+  if (shim.action !== 'unchanged') {
+    const shimPath = join(root, AGENT_HOOK_SHIM);
+    hookChanges.push(change({ path: shimPath, before: await readBefore(shimPath), after: shim.text, owner, reason: shim.action, mode: 0o755 }));
+    shimWritten = true;
+  }
+  await applyPlan(root, hookChanges, { mode: { apply: true }, journal, commit: false });
+  return { written, shimWritten };
+}
+
+async function installHooks(root, flags) {
+  const mode = writeMode(flags);
+  const planned = await planAgentHooks(root, { harness: flags.harness });
+  if (planned.error) {
+    return fail(planned.error, EXIT.USAGE, planned.remedy);
+  }
+  const { plan, shim, others, promptLine, refused } = planned;
 
   // The `--diff` pairs, read before anything is written so the before side is
   // true in preview and in apply alike (R50).
@@ -255,7 +300,7 @@ async function installHooks(root, flags) {
         plan
           .filter((p) => p.action !== 'unchanged')
           .map(async (p) => ({ path: p.path, before: await readBefore(join(root, p.path)), after: p.text }))
-          .concat(shimAction === 'unchanged' ? [] : [{ path: AGENT_HOOK_SHIM, before: shimBefore, after: shimText }]),
+          .concat(shim.action === 'unchanged' ? [] : [{ path: AGENT_HOOK_SHIM, before: shim.before, after: shim.text }]),
       )
       : [];
 
@@ -267,7 +312,7 @@ async function installHooks(root, flags) {
         root,
         dryRun: true,
         plan: plan.map(({ text, ...rest }) => rest),
-        shim: shimRow,
+        shim: shim.row,
         notWritten: others,
         filesWritten: false,
         ...diffField(diffs, flags),
@@ -278,7 +323,7 @@ async function installHooks(root, flags) {
       [
         `repo     ${root}`,
         ...plan.map((p) => `${p.action.toUpperCase().padEnd(9)} ${p.id.padEnd(12)} ${p.path}${p.error ? `  (${p.error})` : ''}`),
-        `${shimAction.toUpperCase().padEnd(9)} shim         ${AGENT_HOOK_SHIM}`,
+        `${shim.action.toUpperCase().padEnd(9)} shim         ${AGENT_HOOK_SHIM}`,
         ...others.map((o) => `${OTHER_LABEL[o.state]} ${o.id.padEnd(12)} ${o.path ?? '(no hooks file is documented)'}`),
         ...promptLine,
         '',
@@ -286,7 +331,6 @@ async function installHooks(root, flags) {
           ? `REFUSED  ${refused.length} config file(s) could not be read; nothing written`
           :        `PLAN     nothing written; apply with: ${CLI} agent-hooks install --yes`,
       ].join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     // After the report: the report says what, the diff shows it (R50).
     emitDiffs(diffs, flags);
@@ -302,20 +346,7 @@ async function installHooks(root, flags) {
 
   // Journaled so `undo` restores this run (R49).
   const journal = [];
-  const written = [];
-  for (const p of plan.filter((x) => x.action !== 'unchanged')) {
-    await mkdir(join(root, dirname(p.path)), { recursive: true });
-    await journaledWriteFile(root, journal, join(root, p.path), p.text);
-    written.push(p);
-  }
-  // The shim is a file like the configs: unchanged installs leave it alone, and a
-  // changed one is journaled so `undo` removes or restores it with the configs.
-  let shimWritten = false;
-  if (shimAction !== 'unchanged') {
-    await mkdir(join(root, dirname(AGENT_HOOK_SHIM)), { recursive: true });
-    await journaledWriteFile(root, journal, join(root, AGENT_HOOK_SHIM), shimText, { mode: 0o755 });
-    shimWritten = true;
-  }
+  const { written, shimWritten } = await applyAgentHooks(root, journal, { plan, shim, owner: 'agent-hooks install' });
   await commitJournal(root, 'agent-hooks install', journal);
 
   const notes = [];
@@ -331,7 +362,7 @@ async function installHooks(root, flags) {
       command: 'agent-hooks install',
       root,
       plan: plan.map(({ text, ...rest }) => rest),
-      shim: { ...shimRow, written: shimWritten },
+      shim: { ...shim.row, written: shimWritten },
       notWritten: others,
       written: written.map((p) => p.path),
       filesWritten: true,
@@ -344,13 +375,12 @@ async function installHooks(root, flags) {
     [
       `repo     ${root}`,
       ...plan.map((p) => `${p.action.toUpperCase().padEnd(9)} ${p.id.padEnd(12)} ${p.path}`),
-      `${shimAction.toUpperCase().padEnd(9)} shim         ${AGENT_HOOK_SHIM}`,
+      `${shim.action.toUpperCase().padEnd(9)} shim         ${AGENT_HOOK_SHIM}`,
       ...others.map((o) => `${OTHER_LABEL[o.state]} ${o.id.padEnd(12)} ${o.path ?? '(no hooks file is documented)'}`),
       ...promptLine,
       '',
       `WROTE    ${written.length} hooks file(s)${shimWritten ? ' and the shim' : ''}; each one runs the ${AGENT_HOOK_SHIM} shim before the tool call`,
     ].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   // After the report: the report says what, the diff shows it (R50).
   emitDiffs(diffs, flags);
@@ -448,7 +478,7 @@ async function hooksStatus(root, flags) {
     lines.push('', 'problems:');
     for (const p of problems) lines.push(`  ${p}`);
   }
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return problems.length === 0 ? EXIT.OK : EXIT.FAIL;
 }
 

package/src/commands/bench.mjs

@@ -5,11 +5,13 @@
 // default and write artifacts to `.simt/bench/` only when authorised with
 // `--yes` (and not `--dry-run`). `bench report` is read-only.
 
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 
 import { CLI } from '../name.mjs';
 import { EXIT, emit, emitJson, fail, isJson, writeMode } from '../output/index.mjs';
 import { DEFAULT_MINE_TARGET, mineTasks } from '../bench/mine.mjs';
+import { buildCorpusDocument, verifyCorpusDocument, writeCorpusDocument } from '../measure/corpus.mjs';
 import { regradeRun, runBench } from '../bench/run.mjs';
 import { buildBenchReport } from '../bench/report.mjs';
 import { formatRecall, measureRecall } from '../index/map.mjs';
@@ -18,14 +20,33 @@ import { runBenchProbes } from '../bench/probes.mjs';
 import { selectRuleVariants } from '../bench/variants.mjs';
 import { criticBench } from '../review/critic.mjs';
 import { listFlag } from './skills.mjs';
+import { commandRoot } from '../repo-root.mjs';
+
+/**
+ * Refuse an authorised bench run that names no harness.
+ *
+ * The default harness is `gold`, which applies the reference patch instead of asking
+ * an agent: a `--yes` run with no harness measured the grader and stored the result as
+ * an arm's evidence (review 0003 Q49). A default cannot be mistaken for a measurement
+ * if there is no default.
+ */
+function requireHarness(flags, command) {
+  if (typeof flags.harness === 'string' && flags.harness.length > 0) return null;
+  return fail(
+    `${command} --yes needs an explicit --harness`,
+    EXIT.USAGE,
+    `pass --harness <name>: an agent adapter such as \`--harness claude\`, or a calibration harness (\`gold\`, \`noop\`)`, 
+  );
+}
 
 export async function benchMineCommand(positional, flags) {
-  const root = resolve(flags.root ?? positional[0] ?? process.cwd());
+  const root = resolve(commandRoot(flags, positional));
   const { dryRun, apply } = writeMode(flags);
 
   const result = await mineTasks(root, {
     apply,
     target: DEFAULT_MINE_TARGET,
+    replace: flags.replace === true,
   });
 
   if (!result.ok) {
@@ -64,7 +85,7 @@ export async function benchMineCommand(positional, flags) {
     for (const task of result.tasks) {
       const subject = task.prompt.split('\n')[0];
       lines.push(
-        `task     ${task.id}  f2p=${task.f2p.length}  p2p=${task.f2p.length}  files=${task.gold.files}  +${task.gold.linesAdded}/-${task.gold.linesRemoved}  ${subject}`,
+        `task     ${task.id}  f2p=${task.f2p.length}  p2p=${task.p2p.length}  files=${task.gold.files}  +${task.gold.linesAdded}/-${task.gold.linesRemoved}  ${subject}`,
       );
     }
   } else {
@@ -75,12 +96,12 @@ export async function benchMineCommand(positional, flags) {
     lines.push(`remedy   run: ${CLI} bench mine --yes`);
   }
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
 export async function benchRunCommand(positional, flags) {
-  const root = resolve(flags.root ?? positional[0] ?? process.cwd());
+  const root = resolve(commandRoot(flags, positional));
   const { dryRun, apply } = writeMode(flags);
 
   if (flags.regrade !== undefined) {
@@ -123,10 +144,15 @@ export async function benchRunCommand(positional, flags) {
         `run      ${run.runId}/${run.task}  arm=${run.arm}  resolved=${run.resolved}  gates=${run.gatesPassed}  reproduced=${run.reproduced}`,
       );
     }
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     return code;
   }
 
+  if (apply) {
+    const missing = requireHarness(flags, 'bench run');
+    if (missing !== null) return missing;
+  }
+
   const arms = listFlag(flags.arm);
   const tasks = listFlag(flags.task);
   const harness = flags.harness ?? 'gold';
@@ -189,7 +215,7 @@ export async function benchRunCommand(positional, flags) {
     lines.push(`remedy   run: ${CLI} bench run --yes`);
   }
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
@@ -207,7 +233,7 @@ export async function benchReportCommand(positional, flags) {
     );
   }
 
-  const root = resolve(flags.root ?? pos[0] ?? process.cwd());
+  const root = resolve(commandRoot(flags, pos));
   const arms = listFlag(flags.arm);
 
   let report;
@@ -243,7 +269,7 @@ export async function benchReportCommand(positional, flags) {
     return EXIT.OK;
   }
 
-  emit(`${report.markdown}\n\n### Map\n\n${formatRecall(mapRecall)}`, { maxBytes: flags.maxBytes ?? 0 });
+  emit(`${report.markdown}\n\n### Map\n\n${formatRecall(mapRecall)}`);
   return EXIT.OK;
 }
 
@@ -256,8 +282,12 @@ async function recallOrUnmeasured(root) {
 }
 
 export async function benchAblateCommand(positional, flags) {
-  const root = resolve(flags.root ?? positional[0] ?? process.cwd());
+  const root = resolve(commandRoot(flags, positional));
   const { dryRun, apply } = writeMode(flags);
+  if (apply) {
+    const missing = requireHarness(flags, 'bench ablate');
+    if (missing !== null) return missing;
+  }
   const harness = flags.harness ?? 'gold';
   const model = flags.model;
   const reps = flags.reps ?? 1;
@@ -302,13 +332,18 @@ export async function benchAblateCommand(positional, flags) {
     lines.push(`remedy   run: ${CLI} bench ablate --yes`);
   }
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
 export async function benchProbesCommand(positional, flags) {
-  const root = resolve(flags.root ?? positional[0] ?? process.cwd());
+  const root = resolve(commandRoot(flags, positional));
   const { dryRun, apply } = writeMode(flags);
+  if (apply) {
+    const missing = requireHarness(flags, 'bench probes');
+    if (missing !== null) return missing;
+  }
+
   const arms = listFlag(flags.arm);
   const probes = listFlag(flags.task);
   const harness = flags.harness ?? 'gold';
@@ -353,13 +388,17 @@ export async function benchProbesCommand(positional, flags) {
     lines.push(`remedy   run: ${CLI} bench probes --yes`);
   }
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
 export async function benchVariantsCommand(positional, flags) {
-  const root = resolve(flags.root ?? positional[0] ?? process.cwd());
+  const root = resolve(commandRoot(flags, positional));
   const { dryRun, apply } = writeMode(flags);
+  if (apply) {
+    const missing = requireHarness(flags, 'bench variants');
+    if (missing !== null) return missing;
+  }
   let result;
   try {
     result = await selectRuleVariants(root, {
@@ -390,7 +429,7 @@ export async function benchVariantsCommand(positional, flags) {
     ),
   ];
   if (!result.applied) lines.push(`remedy   run: ${CLI} bench variants --yes`);
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
@@ -405,13 +444,13 @@ export async function benchVariantsCommand(positional, flags) {
 // the row says precision >= 0.8 on >= 30 labelled diffs promotes it to a gate,
 // and until a bench here shows that, every report calls the critic advisory.
 export async function benchCriticCommand(positional, flags, commands = []) {
-  const root = resolve(flags.root ?? positional[0] ?? process.cwd());
+  const root = resolve(commandRoot(flags, positional));
   const labelsPath = flags.labels ?? '.simt/local/critic-labels.jsonl';
   const result = await criticBench(root, { labelsPath, flags, commands });
   if (typeof result === 'number') return result;
 
   if (isJson(flags)) {
-    emitJson(result, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    emitJson(result);
     return EXIT.OK;
   }
   const lines = [
@@ -424,6 +463,140 @@ export async function benchCriticCommand(positional, flags, commands = []) {
   ];
   if (result.labelsNote) lines.push(`labels   ${result.labelsNote}`);
   for (const error of result.errors) lines.push(`error    ${error}`);
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
+  return EXIT.OK;
+}
+
+// `simt bench export` / `simt bench import` (review 0003 Q48).
+//
+// The vault is keyed on the repository's root commit and lives outside every
+// checkout. That is what makes it safe as a hidden verifier, and it is also
+// why a clone cannot read the corpus mined on another machine: the committed
+// tasks failed with ENOENT from every other checkout. A sealed document
+// carries the descriptors and both patches for every task in one file, so an
+// export on one machine and an import on another reproduce the corpus
+// exactly, and the seal is checked before a single byte is trusted.
+
+export async function benchExportCommand(positional, flags) {
+  const out = positional[0];
+  if (!out) {
+    return fail(
+      'bench export needs a target file: bench export <corpus.json>',
+      EXIT.USAGE,
+      `export the sealed corpus: ${CLI} bench export corpus.json --yes`,
+    );
+  }
+  const root = resolve(commandRoot(flags));
+  const { dryRun, apply } = writeMode(flags);
+
+  let doc;
+  try {
+    doc = await buildCorpusDocument(root);
+  } catch (error) {
+    return fail(
+      `${root}: ${error.message ?? error}`,
+      EXIT.CONFIG,
+      `mine tasks first: ${CLI} bench mine --yes`,
+    );
+  }
+
+  if (doc.taskCount === 0) {
+    return fail(
+      `${root}: no mined tasks to export`,
+      EXIT.USAGE,
+      `mine tasks first: ${CLI} bench mine --yes`,
+    );
+  }
+
+  if (apply) {
+    const absOut = resolve(out);
+    await mkdir(dirname(absOut), { recursive: true });
+    await writeFile(absOut, `${JSON.stringify(doc, null, 2)}\n`, 'utf8');
+  }
+
+  if (isJson(flags)) {
+    emitJson({
+      ok: true,
+      command: 'bench export',
+      root,
+      dryRun,
+      applied: apply,
+      out: resolve(out),
+      taskCount: doc.taskCount,
+      seal: doc.seal,
+    });
+    return EXIT.OK;
+  }
+
+  const lines = [
+    `bench    export  ${resolve(out)}`,
+    `mode     ${apply ? 'applied' : dryRun ? 'dry-run (writes nothing)' : 'preview (pass --yes to write)'}`,
+    `tasks    ${doc.taskCount}`,
+    `seal     ${doc.seal}`,
+  ];
+  if (!apply) lines.push(`remedy   run: ${CLI} bench export ${out} --yes`);
+  emit(lines.join('\n'));
+  return EXIT.OK;
+}
+
+export async function benchImportCommand(positional, flags) {
+  const file = positional[0];
+  if (!file) {
+    return fail(
+      'bench import needs a corpus file: bench import <corpus.json>',
+      EXIT.USAGE,
+      `import a sealed corpus: ${CLI} bench import corpus.json --yes`,
+    );
+  }
+  const root = resolve(commandRoot(flags));
+  const { dryRun, apply } = writeMode(flags);
+
+  let doc;
+  try {
+    doc = JSON.parse(await readFile(file, 'utf8'));
+  } catch (error) {
+    return fail(
+      `${file}: ${error.message ?? error}`,
+      EXIT.USAGE,
+      `export one with: ${CLI} bench export ${file} --yes`,
+    );
+  }
+
+  const problem = verifyCorpusDocument(doc);
+  if (problem !== null) {
+    return fail(
+      `${file}: ${problem}`,
+      EXIT.CONFIG,
+      `export a fresh corpus: ${CLI} bench export ${file} --yes`,
+    );
+  }
+
+  const result = await writeCorpusDocument(root, doc, { apply });
+
+  if (isJson(flags)) {
+    emitJson({
+      ok: true,
+      command: 'bench import',
+      root,
+      file: resolve(file),
+      dryRun,
+      applied: result.applied,
+      taskCount: result.tasks,
+      tasksDir: result.tasksDir,
+      vaultRoot: result.vaultRoot,
+      seal: doc.seal,
+    });
+    return EXIT.OK;
+  }
+
+  const lines = [
+    `bench    import  ${resolve(file)}`,
+    `mode     ${apply ? 'applied' : dryRun ? 'dry-run (writes nothing)' : 'preview (pass --yes to write)'}`,
+    `imported ${result.tasks} task(s)  seal=${doc.seal}`,
+    `tasks    ${result.tasksDir}`,
+    `vault    ${result.vaultRoot}`,
+  ];
+  if (!apply) lines.push(`remedy   run: ${CLI} bench import ${file} --yes`);
+  emit(lines.join('\n'));
   return EXIT.OK;
 }

package/src/commands/brief.mjs

@@ -19,8 +19,9 @@ import { CLI } from '../name.mjs';
 import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { DEFAULT_BRIEF_BYTES, explainPacket } from '../brief/packet.mjs';
 import { assembleBrief } from '../brief/assemble.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
-export async function briefCommand(args, flags) {
+export async function briefCommand(args, flags, commands = []) {
   if (args.length > 1) {
     return fail(`brief takes one task, not ${args.length}`, EXIT.USAGE, `run: ${CLI} brief "<task>"`);
   }
@@ -33,11 +34,12 @@ export async function briefCommand(args, flags) {
   }
 
   const result = await assembleBrief({
-    root: flags.root ?? process.cwd(),
+    root: commandRoot(flags),
     task: String(args[0] ?? flags.task ?? ''),
     paths: flags.paths === undefined ? null : flags.paths,
     budget,
     flags,
+    commands,
   });
   if (result.error) return result.error;
   // Unreachable from here — only a delivered brief asks for a cold index to be reported
@@ -67,12 +69,11 @@ export async function briefCommand(args, flags) {
         explain: flags.explain === true ? explainPacket(items, { cut }) : undefined,
         text: packed.text,
       },
-      { pretty: flags.pretty === true, maxBytes: Number(flags.maxBytes ?? 0) || 0 },
     );
     return EXIT.OK;
   }
 
   const body = flags.explain === true ? [packed.text, '', 'EXPLAIN', ...explainPacket(items, { cut })] : [packed.text];
-  emit(body.join('\n'), { maxBytes: Number(flags.maxBytes ?? 0) || 0 });
+  emit(body.join('\n'));
   return EXIT.OK;
 }

package/src/commands/ci.mjs

@@ -18,15 +18,15 @@
 // commands owns which file would be learning about ownership twice to learn nothing
 // new, and the next .github file would arrive with a third command to remember.
 
-import { mkdir, readFile } from 'node:fs/promises';
-import { dirname } from 'node:path';
-import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { readFile } from 'node:fs/promises';
+import { applyPlan, change } from '../write/plan.mjs';
 import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 
 import { EXIT, emit, emitJson, isJson, note, writeMode } from '../output/index.mjs';
 import { planWorkflow, renderWorkflow, WORKFLOW_FILE } from '../ci/workflow.mjs';
 import { planDependabot, renderDependabot, DEPENDABOT_FILE } from '../ci/dependabot.mjs';
 import { CLI } from '../name.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 /**
  * The two plans, with the render and the plan-time data each needs kept attached.
@@ -38,12 +38,12 @@ import { CLI } from '../name.mjs';
 function targets() {
   return [
     { key: 'workflow', file: WORKFLOW_FILE, plan: planWorkflow, render: () => renderWorkflow({ own: true }) },
-    { key: 'dependabot', file: DEPENDABOT_FILE, plan: planDependabot, render: (plan) => renderDependabot(plan.facts ?? [], { stack: plan.stack ?? [], own: true }) },
+    { key: 'dependabot', file: DEPENDABOT_FILE, plan: planDependabot, render: (plan) => renderDependabot(plan.facts ?? [], { stack: plan.stack ?? [], own: true, root: plan.root }) },
   ];
 }
 
 export async function ciCommand(positional, flags) {
-  const root = flags.root ?? positional[0] ?? process.cwd();
+  const root = commandRoot(flags, positional);
   const mode = writeMode(flags);
   const checkOnly = flags.check === true;
 
@@ -152,19 +152,18 @@ export async function ciCommand(positional, flags) {
     return EXIT.OK;
   }
 
-  // Journaled so `undo` restores this run (R49).
-  const journal = [];
+  // Journaled so `undo` restores this run (R49). The renderer takes the plan because
+  // detection-driven content is a function of this repo's facts: a dependabot config
+  // rendered without them would watch nothing, which is the same silent-nothing the
+  // detection ruling exists to stop.
+  const changes = [];
   for (const { key, plan, render } of targets()) {
     const p = plans.find((x) => x.key === key);
     if (p.action === 'unchanged') continue;
-    await mkdir(dirname(p.path), { recursive: true });
-    // The renderer takes the plan because detection-driven content is a function of
-    // this repo's facts: a dependabot config rendered without them would watch
-    // nothing, which is the same silent-nothing the detection ruling exists to stop.
-    await journaledWriteFile(root, journal, p.path, render(p));
-    note(`wrote    ${p.file} (${p.action}; the template and this copy now agree)`);
+    changes.push(change({ path: p.path, before: await readBefore(p.path), after: render(p), owner: 'ci', reason: 'the template and this copy now agree' }));
   }
-  await commitJournal(root, 'ci', journal);
+  await applyPlan(root, changes, { mode, label: 'ci' });
+  for (const c of changes) note(`wrote    ${c.path.replace(`${root}/`, '')} (${c.action}; ${c.reason})`);
   if (isJson(flags)) {
     emitJson(
       {