simt-dev 0.6.2 → 0.7.0

package/src/commands/agenthook.mjs

@@ -22,13 +22,18 @@
 // tool call. Failures of this command exit 1, which a harness reports as a failed hook,
 // and that is the right blast radius for a hook that is broken rather than refusing.
 
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+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 { AGENT_HOOK_SHIM, renderAgentHookShim } from '../agenthooks/shim.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
-import { CLI } from '../name.mjs';
-import { ALLOW_ENV, EVENTS, POLICY_IDS } from '../agenthooks/policy.mjs';
+import { CLI, MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
+import { ALLOW_ENV, EVENTS, POLICY_IDS, SESSION_ENV } from '../agenthooks/policy.mjs';
 import { decide, factsFor } from '../agenthooks/decide.mjs';
+import { repoRoot } from '../repo-root.mjs';
 import {
   adapter,
   adapters,
@@ -95,10 +100,33 @@ export async function agentHookCommand(args, flags) {
   // `--root` outranks the payload: a packaged hook runs from the plugin directory and the
   // harness's environment variable names the project, so a payload cwd that is the plugin's
   // own working directory must not win. The repository-install path passes no flag, and the
-  // payload's cwd is what the harness reports.
-  const { root, command, writes } = factsFrom(row, payload, { root: flags.root });
-  const facts = await factsFor(root, { command, writes });
-  const decision = decide({ event, facts, env: process.env });
+  // payload's cwd is what the harness reports. The answer is then resolved to the
+  // repository's top level: a harness reports the directory it happens to be in, and an
+  // agent works from subdirectories, so every repository-relative fact (the lease file,
+  // `.gitmodules`) must resolve against the root git itself uses, not the cwd (review
+  // 0003 Q16).
+  const { root: payloadRoot, command, writes, session: payloadSession } = factsFrom(row, payload, { root: flags.root });
+  const root = repoRoot(payloadRoot);
+  // A relative write path is relative to the directory the harness is in, not to the
+  // repository root the facts resolve against: an agent editing `keep.mjs` from `src/`
+  // means `src/keep.mjs`, and a path joined to the wrong base is a path the lease file
+  // will never meet (review 0003 Q16).
+  // Writes are `{path, ...edit}` rows (Q17): the path resolves against the harness
+  // cwd, the edit detail travels untouched so the region check sees the old_string.
+  const writesAbsolute = writes.map((w) => {
+    const path = typeof w === 'string' ? w : w?.path;
+    const abs = typeof path === 'string' && isAbsolute(path) ? path : join(payloadRoot, path);
+    return typeof w === 'string' ? abs : { ...w, path: abs };
+  });
+  const facts = await factsFor(root, { command, writes: writesAbsolute });
+  // Harness hook processes rarely carry SIMT_SESSION, so the payload's own
+  // session id is the fallback: without it an agent is blocked by its own
+  // lease (review 0003 Q20). The environment still wins when it names one.
+  const session =
+    typeof process.env[SESSION_ENV] === 'string' && process.env[SESSION_ENV] !== ''
+      ? process.env[SESSION_ENV]
+      : (payloadSession ?? '');
+  const decision = decide({ event, facts, env: { ...process.env, [SESSION_ENV]: session } });
 
   // Both notes are about a conclusion the author is about to draw: a lift that did
   // nothing because of a typo, and a lift that is the reason the command they expected to
@@ -113,7 +141,11 @@ export async function agentHookCommand(args, flags) {
   const json = decisionJson(row, decision);
   if (json === null) return EXIT.OK;
 
-  if (root) {
+  // A denial is recorded only for a repository that adopted the tool: hook
+  // denials in a never-adopted repo are noise about someone else's policy, and
+  // that is how an unadopted checkout accumulated 23 candidates nobody would
+  // ever promote (review 0003 Q36). The manifest is the adoption mark.
+  if (root && (existsSync(join(root, MANIFEST_FILE)) || existsSync(join(root, MANIFEST_LEGACY)))) {
     try {
       const { recordHookDenial } = await import('../memory/lessons.mjs');
       await recordHookDenial(root, {
@@ -141,8 +173,24 @@ export async function agentHooksCommand(sub, args, flags) {
   return fail(`unknown agent-hooks subcommand ${sub}`, EXIT.USAGE, `run: ${CLI} agent-hooks status`);
 }
 
+// The label for a reader the run did not write, by the state that names why:
+// `none` documents no hooks file, `other` is a reader this tool does not write,
+// `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);
+  // `--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(', ')}`,
+    );
+  }
   // 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
   // import for the same reason the hook delivers through one.
@@ -153,8 +201,9 @@ 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 plan = [];
-  for (const row of adapters()) {
+  for (const row of rows) {
     const path = hookPath(row.id);
     const existing = await readIfExists(join(root, path));
     const result = rendered(row, existing, { prompt: optIn.optedIn, post: hasLessons });
@@ -176,15 +225,40 @@ async function installHooks(root, flags) {
 
   // The readers this tool does not write an entry for, reported rather than skipped in
   // silence: a command that writes four files and says nothing about the fifth harness
-  // in the repository reads as "that one is covered too".
+  // in the repository reads as "that one is covered too". A narrowed install adds a
+  // third state: an adapter that is this tool's but was not requested (ADR-107).
   const others = [];
   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) {
+      others.push({ id: r.id, path: r.path, state: 'skipped', note: 'not requested; install without --harness to write every harness' });
+    }
   }
 
   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.
+  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 };
+
+  // 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 Promise.all(
+        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 }]),
+      )
+      : [];
+
   if (!mode.apply) {
     if (isJson(flags)) {
       emitJson({
@@ -193,8 +267,10 @@ async function installHooks(root, flags) {
         root,
         dryRun: true,
         plan: plan.map(({ text, ...rest }) => rest),
+        shim: shimRow,
         notWritten: others,
         filesWritten: false,
+        ...diffField(diffs, flags),
       });
       return refused.length > 0 ? EXIT.FAIL : EXIT.OK;
     }
@@ -202,15 +278,18 @@ 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})` : ''}`),
-        ...others.map((o) => `${o.state === 'none' ? 'NO FILE ' : 'NOT OURS'} ${o.id.padEnd(12)} ${o.path ?? '(no hooks file is documented)'}`),
+        `${shimAction.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,
         '',
         refused.length > 0
           ? `REFUSED  ${refused.length} config file(s) could not be read; nothing written`
-          : `PLAN     nothing written; apply with: ${CLI} agent-hooks install --yes`,
+          :        `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);
     return refused.length > 0 ? EXIT.FAIL : EXIT.OK;
   }
 
@@ -221,12 +300,23 @@ async function installHooks(root, flags) {
     return fail(`refused to write ${refused.map((p) => `${p.path} (${p.error})`).join('; ')}`, EXIT.FAIL);
   }
 
+  // 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 writeFile(join(root, p.path), p.text);
+    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;
+  }
+  await commitJournal(root, 'agent-hooks install', journal);
 
   const notes = [];
   for (const p of written) {
@@ -241,10 +331,12 @@ async function installHooks(root, flags) {
       command: 'agent-hooks install',
       root,
       plan: plan.map(({ text, ...rest }) => rest),
+      shim: { ...shimRow, written: shimWritten },
       notWritten: others,
       written: written.map((p) => p.path),
       filesWritten: true,
       notes,
+      ...diffField(diffs, flags),
     });
     return EXIT.OK;
   }
@@ -252,13 +344,16 @@ async function installHooks(root, flags) {
     [
       `repo     ${root}`,
       ...plan.map((p) => `${p.action.toUpperCase().padEnd(9)} ${p.id.padEnd(12)} ${p.path}`),
-      ...others.map((o) => `${o.state === 'none' ? 'NO FILE ' : 'NOT OURS'} ${o.id.padEnd(12)} ${o.path ?? '(no hooks file is documented)'}`),
+      `${shimAction.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); each one runs ${CLI} agent-hook before the tool call`,
+      `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);
   for (const o of others) note(`note     ${o.id}: not written - ${o.note}`);
   for (const n of notes) note(`note     ${n}`);
   note(`note     never committed or pushed (ADR-001); review, then commit yourself`);
@@ -268,10 +363,31 @@ async function installHooks(root, flags) {
 async function hooksStatus(root, flags) {
   const rows = [];
   const problems = [];
+  // The plugin file this tool owns whole is compared against what `install` would write
+  // right now, so status reads the same opt-in install reads: a file that matches the
+  // preview is present, anything else is drift an install will rewrite.
+  const { promptOptIn } = await import('../agenthooks/prompt.mjs');
+  const optIn = await promptOptIn(root);
 
   for (const row of adapters()) {
     const path = hookPath(row.id);
     const existing = await readIfExists(join(root, path));
+    if (row.file) {
+      if (existing === null) {
+        rows.push({ id: row.id, path, state: 'absent', entries: 0, prompt: row.prompt ? 'absent' : null, note: null });
+      } else {
+        const present = rendered(row, existing, { prompt: optIn.optedIn }).action === 'unchanged';
+        rows.push({
+          id: row.id,
+          path,
+          state: present ? 'present' : 'drift',
+          entries: present ? 1 : 0,
+          prompt: row.prompt ? (present && optIn.optedIn ? 'present' : 'absent') : null,
+          note: present ? null : 'differs from what install would write; run install to restore it',
+        });
+      }
+      continue;
+    }
     if (existing === null) {
       rows.push({ id: row.id, path, state: 'absent', entries: 0, prompt: row.prompt ? 'absent' : null, note: null });
       continue;
@@ -319,7 +435,7 @@ async function hooksStatus(root, flags) {
 
   const lines = [`repo     ${root}`];
   for (const r of rows) {
-    const state = { present: 'PRESENT ', absent: 'ABSENT  ', unreadable: 'INVALID ', none: 'NO FILE ', other: 'NOT OURS' }[r.state];
+    const state = { present: 'PRESENT ', absent: 'ABSENT  ', unreadable: 'INVALID ', drift: 'DRIFT   ', none: 'NO FILE ', other: 'NOT OURS' }[r.state];
     lines.push(`${state} ${r.id.padEnd(12)} ${r.path ?? '(no hooks file is documented)'}`);
     if (r.state === 'absent') lines.push(`          ${' '.repeat(12)} install: ${CLI} agent-hooks install --yes`);
     // The second event is a separate answer to a separate question: a harness can carry

package/src/commands/bench.mjs

@@ -217,6 +217,7 @@ export async function benchReportCommand(positional, flags) {
       harness: flags.harness,
       model: flags.model,
       compare: compareItems.length === 2 ? compareItems : null,
+      crossGroup: Boolean(flags.crossGroup),
     });
   } catch (error) {
     return fail(
@@ -405,7 +406,7 @@ export async function benchVariantsCommand(positional, flags) {
 // 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 labelsPath = flags.labels ?? '.simt/critic-labels.jsonl';
+  const labelsPath = flags.labels ?? '.simt/local/critic-labels.jsonl';
   const result = await criticBench(root, { labelsPath, flags, commands });
   if (typeof result === 'number') return result;
 

package/src/commands/ci.mjs

@@ -18,8 +18,10 @@
 // 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, writeFile } from 'node:fs/promises';
+import { mkdir, readFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import { commitJournal, journaledWriteFile } from '../journal.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';
@@ -121,18 +123,37 @@ export async function ciCommand(positional, 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 renders = new Map(targets().map(({ key, render }) => [key, render]));
+  const diffs =
+    flags.diff === true
+      ? await Promise.all(
+        plans
+          .filter((p) => p.action !== 'unchanged')
+          .map(async (p) => ({ path: p.file, before: await readBefore(p.path), after: renders.get(p.key)(p) })),
+      )
+      : [];
+
   if (isJson(flags)) {
-    emitJson({ ok: true, command: 'ci', root, files: todo.map(publicPlan), written: false, dryRun: !mode.apply }, {});
+    emitJson(
+      { ok: true, command: 'ci', root, files: todo.map(publicPlan), written: false, dryRun: !mode.apply, ...diffField(diffs, flags) },
+      {},
+    );
   } else {
     emit(lines.join('\n'));
   }
 
   if (!mode.apply) {
+    // After the report: the report says what, the diff shows it (R50).
+    emitDiffs(diffs, flags);
     note('');
     note(mode.dryRun ? 'dry-run  nothing written' : `dry-run  nothing written; apply with: ${CLI} ci --yes`);
     return EXIT.OK;
   }
 
+  // Journaled so `undo` restores this run (R49).
+  const journal = [];
   for (const { key, plan, render } of targets()) {
     const p = plans.find((x) => x.key === key);
     if (p.action === 'unchanged') continue;
@@ -140,9 +161,10 @@ export async function ciCommand(positional, flags) {
     // 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 writeFile(p.path, render(p));
+    await journaledWriteFile(root, journal, p.path, render(p));
     note(`wrote    ${p.file} (${p.action}; the template and this copy now agree)`);
   }
+  await commitJournal(root, 'ci', journal);
   if (isJson(flags)) {
     emitJson(
       {
@@ -151,10 +173,13 @@ export async function ciCommand(positional, flags) {
         root,
         files: plans.map((p) => ({ file: p.file, action: p.action, bytes: p.bytes })),
         written: true,
+        ...diffField(diffs, flags),
       },
       {},
     );
   }
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
   return EXIT.OK;
 }
 

package/src/commands/compare.mjs

@@ -24,7 +24,7 @@ import { basename, resolve } from 'node:path';
 import { EXIT, emit, emitJson, fail, isJson, note } from '../output/index.mjs';
 import { provenanceDigest } from '../projection/project.mjs';
 import { GATES } from '../hooks/gates.mjs';
-import { buildRow, summarise } from '../compare/row.mjs';
+import { buildRows, resolveConcurrency, summarise } from '../compare/row.mjs';
 import { discover } from '../compare/discover.mjs';
 import { learnAcrossEstate, renderLearningLines } from '../compare/learn.mjs';
 import { targetRoot, WORKSPACE_REMEDY } from '../workspace.mjs';
@@ -60,12 +60,13 @@ export async function compareCommand(positional, flags) {
   const expectedSha = await provenanceDigest();
   const context = { expectedSha, gates: new Set(Object.keys(GATES)), gateKinds: GATE_KINDS };
 
-  // Sequential on purpose. 16 fingerprint+region computations each spawn a git
-  // process; running them concurrently produces a burst of subprocesses and no
-  // measurable speedup, because the work is process-spawn bound rather than CPU
-  // bound. Determinism of the output matters more than wall clock on a dashboard.
-  const rows = [];
-  for (const repo of found.repos) rows.push(await buildRow(repo, context));
+  // Parallel with a cap, in discovery order. 16 fingerprint+region computations
+  // each spawn a git process; unbounded parallelism is a burst of subprocesses
+  // with no speedup, and sequential builds are what took 48 s over MCP for 17
+  // repos (review 0003 Q38). The cap keeps the burst bounded while overlapping
+  // the spawn wait; the rows still come back in input order, so two runs diff
+  // cleanly and determinism of the output is untouched.
+  const rows = await buildRows(found.repos, context, { concurrency: resolveConcurrency(flags) });
   const learning = await learnAcrossEstate(found.repos);
 
   const summary = summarise(rows, {

package/src/commands/completions.mjs

@@ -0,0 +1,27 @@
+// `simt completions <shell>` — print a completion script (plan 0003 R51).
+//
+// The script goes to stdout and nothing else does, because the install is a
+// redirect: `source <(simt completions bash)`, or the zsh file dropped onto
+// `$fpath`. A report line above it would be a report line in the user's shell
+// config.
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { SHELLS, renderCompletions } from '../completions.mjs';
+
+export async function completionsCommand(args, flags, commands) {
+  const shell = args[0];
+  if (shell === undefined) {
+    return fail('completions needs a shell', EXIT.USAGE, `one of: ${SHELLS.join(', ')}`);
+  }
+  if (!SHELLS.includes(shell)) {
+    return fail(`unknown shell \`${shell}\``, EXIT.USAGE, `one of: ${SHELLS.join(', ')}`);
+  }
+
+  const script = renderCompletions(shell, commands);
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'completions', shell, script });
+    return EXIT.OK;
+  }
+  emit(script, { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}

package/src/commands/decide.mjs

@@ -2,20 +2,23 @@
 // a rulings skeleton, and structured `simt-affects` + `simt-supersedes` frontmatter
 // (plan 0003 R34).
 
-import { join, resolve } from 'node:path';
+import { join } from 'node:path';
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
-import { DECISIONS_DIR } from '../decisions/index.mjs';
+import { decisionsCutoff, decisionsDir } from '../decisions/dir.mjs';
 import { lintDecisions, scaffoldDecision } from '../memory/decide.mjs';
+import { commitJournal } from '../journal.mjs';
+import { diffField, emitDiffs } from '../diff.mjs';
 import { parsePathList } from '../argv.mjs';
 
 export async function decideCommand(args, flags) {
   const root = flags.root ?? process.cwd();
 
   if (flags.check === true) {
-    const decisionsDir = join(root, 'docs', 'decisions');
-    const allowHistorical = resolve(decisionsDir) === DECISIONS_DIR;
-    const res = await lintDecisions(decisionsDir, { allowHistorical });
+    // Q55: one resolution — the manifest key, then the detected directory —
+    // and the cutoff from the same config, never a hard-coded number or path.
+    const relDir = await decisionsDir(root);
+    const res = await lintDecisions(join(root, relDir), { historicalCutoff: await decisionsCutoff(root) });
 
     if (isJson(flags)) {
       emitJson({
@@ -49,12 +52,17 @@ export async function decideCommand(args, flags) {
   const parsedPaths = parsePathList(flags.paths);
   const explicitPaths = flags.paths !== undefined ? parsedPaths : undefined;
 
+  // Journaled so `undo` restores the scaffold (R49); committed only when the
+  // run actually wrote, which commitJournal already guarantees.
+  const journal = [];
   const res = await scaffoldDecision(root, {
     title,
     affects: explicitPaths,
     supersedes: flags.supersedes,
     write: mode.apply,
+    journal: mode.apply ? journal : undefined,
   });
+  if (mode.apply && res.ok) await commitJournal(root, 'decide', journal);
 
   if (!res.ok) {
     return fail(
@@ -70,6 +78,10 @@ export async function decideCommand(args, flags) {
     note('dry-run  no files written');
   }
 
+  // A scaffold always creates: the number is free by construction, so the
+  // before side is empty and the pair is the whole file (R50).
+  const diffs = flags.diff === true ? [{ path: res.relPath, before: null, after: res.text }] : [];
+
   if (isJson(flags)) {
     emitJson({
       ok: true,
@@ -84,10 +96,10 @@ export async function decideCommand(args, flags) {
       supersedes: res.supersedes,
       written: res.written,
       dryRun: !mode.apply,
+      ...diffField(diffs, flags),
     });
     return EXIT.OK;
   }
-
   const supersedesLabel =
     res.supersedes.length > 0
       ? res.supersedes
@@ -112,5 +124,7 @@ export async function decideCommand(args, flags) {
   ];
 
   emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
   return EXIT.OK;
 }