simt-dev 0.6.2 → 0.6.3

package/src/commands/index.mjs

@@ -51,7 +51,11 @@ import {
   benchCriticCommand,
 } from './bench.mjs';
 import { planCommand } from './plan.mjs';
-import { sharedPlanCommand, sharedInstallCommand, sharedWarning } from './shared.mjs';
+import { sliceCommand } from './slice.mjs';
+import { leaseCommand } from './lease.mjs';
+import { sharedPlanCommand, sharedInstallCommand } from './shared.mjs';
+import { runDoctor } from './doctor.mjs';
+import { statusCommand } from './status.mjs';
 import { evidenceCommand } from './evidence.mjs';
 import { indexCommand } from './repoindex.mjs';
 import { mapCommand } from './map.mjs';
@@ -61,13 +65,16 @@ import { gateCommand } from './gate.mjs';
 import { impactCommand } from './impact.mjs';
 import { lessonsListCommand, lessonsReviewCommand } from './lessons.mjs';
 import { decideCommand } from './decide.mjs';
+import { explainCommand } from './explain.mjs';
+import { undoCommand } from './undo.mjs';
+import { prBodyCommand } from './prbody.mjs';
+import { ignoreCommand } from './ignore.mjs';
+import { completionsCommand } from './completions.mjs';
 import { reviewCommand } from './review.mjs';
 import { localDoctorCommand } from './local.mjs';
 import { distillCommand } from './distill.mjs';
-import { parse } from '../argv.mjs';
+import { parse, rawJsonFlag } from '../argv.mjs';
 import { CLI } from '../name.mjs';
-import { fingerprint } from '../resolve/fingerprint.mjs';
-import { resolveWorkspace } from '../workspace.mjs';
 
 /** command path -> implementation sequence step (plan 0002 section 11). */
 // Every command named in plan 0002 section 5 is now implemented, so this map is empty.
@@ -83,6 +90,10 @@ const GROUPS = new Map([
   ['rules', 'list'],
   ['hooks', 'status'],
   ['plan', 'status'],
+  // Plan 0003 R53. Both halves write, so a bare `slice` has no read to default to.
+  // `start` is the default because with the id it is missing it fails with a usage
+  // error before anything is created — the one default here that cannot mutate.
+  ['slice', 'start'],
   ['agent-hooks', 'status'],
   ['harness', 'detect'],
   ['bench', 'mine'],
@@ -114,6 +125,9 @@ const GROUPS = new Map([
 export const IMPLEMENTED = {
   brief: briefCommand,
   doctor: runDoctor,
+  // Plan 0003 R48. A bare command: the only mode is `--line`, so there is no
+  // group and no default subcommand to resolve.
+  status: statusCommand,
   'graph lint': lintCommand,
   'skills index': skillsIndex,
   'skills find': skillsFind,
@@ -131,6 +145,11 @@ export const IMPLEMENTED = {
   'plan status': (args, flags) => planCommand('status', args, flags),
   'plan next': (args, flags) => planCommand('next', args, flags),
   'plan done': (args, flags) => planCommand('done', args, flags),
+  // Plan 0003 R53. A group: `start` isolates the work on a branch with its brief,
+  // `finish` runs the gates, commits and records the evidence. Both take the slice
+  // id as a positional.
+  'slice start': (args, flags) => sliceCommand('start', args, flags),
+  'slice finish': (args, flags) => sliceCommand('finish', args, flags),
   'shared plan': sharedPlanCommand,
   'shared install': sharedInstallCommand,
   evidence: evidenceCommand,
@@ -143,6 +162,22 @@ export const IMPLEMENTED = {
   'lessons list': lessonsListCommand,
   'lessons review': lessonsReviewCommand,
   decide: decideCommand,
+  // Plan 0003 R46. A bare command: the code is a positional, so there is no
+  // group and no default subcommand to resolve.
+  explain: explainCommand,
+  // Plan 0003 R49. A bare command: restoring the last journaled set needs no
+  // subcommand, so there is no group and no default to resolve.
+  undo: undoCommand,
+  // Plan 0003 R55. A bare command: the body is derived from the tree, the
+  // ledger and the last check, so there is no subcommand to resolve and no
+  // write to confirm.
+  'pr-body': prBodyCommand,
+  // Plan 0003 R52. A bare command: the one list is `.simtignore`, so there is no
+  // group and no default subcommand to resolve.
+  ignore: ignoreCommand,
+  // Plan 0003 R54. A bare command: paths claim, no paths list, so the argument itself
+  // is the mode and there is no group to resolve.
+  lease: leaseCommand,
   distill: distillCommand,
   // R25 machinery needs the runnable command names for Affects command tokens,
   // same wiring `why` and `impact` get through their lambdas.
@@ -177,6 +212,9 @@ export const IMPLEMENTED = {
   // plan 0003 R43. A bare command: the kind is a positional, so there is no group and
   // no default subcommand to resolve.
   plugin: pluginCommand,
+  // Plan 0003 R51. A bare command: the shell is a positional. `COMMANDS` rides in
+  // from here so the engine keeps no second copy of the registry it completes.
+  completions: (args, flags) => completionsCommand(args, flags, COMMANDS),
   // Plan 0003 R45. A group, not a bare command: `new` and `publish` write (or
   // publish) and `lint` reads, and the dispatcher routes all three through one
   // subcommand switch the way `hooks` does.
@@ -192,7 +230,7 @@ export const IMPLEMENTED = {
 export const COMMANDS = Object.keys(IMPLEMENTED).sort();
 
 export async function dispatch(argv) {
-  const { flags, positional } = parseOrExit(argv);
+  const { flags, positional, parseError } = parseOrExit(argv);
 
   // The JSON shape is decided once, here, and every command inherits it. Threading a
   // `--pretty` through twenty-five call sites would mean twenty-five places to forget,
@@ -205,6 +243,10 @@ export async function dispatch(argv) {
   jsonIndentDefault(flags.pretty === true);
   jsonFailMode(flags.json === true);
 
+  // A parse failure is already the whole answer: report it once, in the asked-for
+  // shape, rather than falling through to `unknown command` on the empty path.
+  if (parseError !== undefined) return fail(parseError.message, parseError.code);
+
   // Help is shown only when explicitly asked for. An unknown command must fail with
   // a usage code, not print 40 lines of prose and exit 0 — an agent that mistyped
   // needs to be told so, not handed a wall of text it may misread as output.
@@ -267,102 +309,14 @@ function commandPath(first, second) {
 }
 
 function parseOrExit(argv) {
+  // Unreachable from `bin` (it renders the failure itself and exits), but `dispatch`
+  // is also called directly: carry the failure as data so the dispatcher reports it
+  // once, in the asked-for shape, instead of printing here and again below.
   const parsed = parse(argv);
-  if (!parsed.ok) return { flags: {}, positional: [] };
+  if (!parsed.ok) {
+    const json = rawJsonFlag(argv);
+    return { flags: { json }, positional: [], parseError: parsed.error };
+  }
   return parsed.value;
 }
 
-/**
- * Step 3 of the implementation sequence: classify a repo from marker files alone.
- * Deliberately shipped early — it needs no registry, no rules and no projection,
- * and it makes the tool useful before any content exists.
- */
-async function runDoctor(positional, flags) {
-  const root = flags.root ?? positional[0] ?? process.cwd();
-  const result = await fingerprint(root);
-  // Which source answered the workspace question, and where it looked. A tool
-  // that silently fell back to the wrong directory would make every downstream
-  // answer confidently wrong, so the answer is reported rather than inferred
-  // (ADR-014).
-  const ws = await resolveWorkspace(flags);
-  // The shared file this repository hands rules to (ADR-084). Asked here and nowhere else
-  // because it is the one thing about a repository that is true of the reader's machine
-  // rather than of the tree: `check` must not read `$HOME`, so `doctor` is the only command
-  // that can notice a region that dropped rules into a file nobody has. Reported, never
-  // blocking — a stale copy costs a reader some of their rules, which is worth knowing and
-  // is not this repository's gate failing.
-  const shared = await sharedWarning(root, result.manifest ?? null, flags);
-
-  // Under `--json` the document is the whole report, so it has to carry both
-  // failures the text path reports AND the workspace answer the text path prints.
-  // This branch used to return before either check, with `ok` hardcoded true: a
-  // caller asking whether their config is readable was told yes, and given exit
-  // 0, while the same command in a terminal exited 3 and named the file. A
-  // scripted consumer has only this document to go on, so `ok` is derived from
-  // the exit code rather than written as a constant (S10).
-  const failure = result.error
-    ? { error: `${root}: ${result.error}`, remedy: null }
-    : ws.error
-      ? {
-          error: `workspace config ${ws.detail}: ${ws.error}`,
-          remedy: 'fix the JSON, or remove the file',
-        }
-      : null;
-  const code = failure ? EXIT.CONFIG : EXIT.OK;
-
-  if (isJson(flags)) {
-    emitJson({
-      ok: code === EXIT.OK,
-      command: 'doctor',
-      root,
-      ...result,
-      // The workspace answer is a fact about which directory the tool would
-      // act on next (ADR-014). It is printed in the text report; leaving it
-      // out of the JSON meant a machine-readable caller could not see it at
-      // all, which is the one-question-two-answers defect again.
-      workspace: {
-        root: ws.root ?? null,
-        source: ws.source,
-        detail: ws.detail,
-        error: ws.error ?? null,
-      },
-      shared,
-      ...(failure ?? {}),
-    });
-    return code;
-  }
-  if (result.error) {
-    return fail(`${root}: ${result.error}`, EXIT.CONFIG);
-  }
-  emit(
-    [
-      `root     ${root}`,
-      `stack    ${result.stack.length > 0 ? result.stack.join(', ') : '(undetected)'}`,
-      `evidence ${result.evidence.length > 0 ? result.evidence.join(' ') : '(none)'}`,
-      // Facts are what a profile selects on when it wants to survive the
-      // framework being replaced, so they are reported with the path that proved
-      // each one rather than as a bare list (ADR-013).
-      `facts    ${
-        result.facts.length > 0
-          ? result.facts.map((f) => `${f}(${result.factEvidence[f] ?? '?'})`).join(' ')
-          : '(none)'
-      }`,
-      `manifest ${result.manifest ? (result.manifest.error ?? result.manifest.id ?? 'present') : '(absent)'}`,
-      `workspace ${ws.root ?? '(none)'}  (${ws.source}: ${ws.detail})`,
-      // Printed only when this repository handed rules to a workspace copy: a line in
-      // every `doctor` is a line in every reader's terminal, and the reader who has
-      // nothing to install is not served by one (ADR-084).
-      ...(shared.declared ? [`shared    ${shared.state}  ${shared.detail}`] : []),
-    ].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
-  );
-  // An unconfigured workspace is a fact, not a failure: a single repo with no
-  // workspace around it is a normal, supported case. A config file that EXISTS and
-  // does not parse is a real mistake, and that does fail - with the parse error,
-  // because naming the file without saying what is wrong with it sends the reader
-  // to the file and gives them nothing to look for.
-  if (ws.error) {
-    return fail(`workspace config ${ws.detail}: ${ws.error}`, EXIT.CONFIG, 'fix the JSON, or remove the file');
-  }
-  return EXIT.OK;
-}

package/src/commands/init.mjs

@@ -17,13 +17,16 @@
 
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { mkdir, readFile, symlink, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, symlink } from 'node:fs/promises';
+import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { invalidateCheckCache } from '../status.mjs';
 import { dirname, join } from 'node:path';
 
-import { EXIT, emit, emitJson, fail, isJson, note } from '../output/index.mjs';
+import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { rulePaths, scanDocument, summarise } from '../projection/conflicts.mjs';
-import { MANIFEST, buildManifest, manifestPath, readManifest, writeManifest, planGates } from '../projection/manifest.mjs';
+import { MANIFEST, buildManifest, manifestPath, manifestText, readManifest, writeManifest, planGates } from '../projection/manifest.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 import { readCapability } from '../hooks/capability.mjs';
 import { readHooksState } from '../compare/hooksstate.mjs';
 import { planWorkflow, renderWorkflow, WORKFLOWS_DIR } from '../ci/workflow.mjs';
@@ -105,9 +108,9 @@ export async function initCommand(positional, flags) {
   manifest.surfaces = projected.surfaces;
 
   const adoption = exists || Boolean(region?.exists);
-  const dryRun = flags.dryRun === true;
-  const approved = flags.yes === true;
-  const apply = approved && !dryRun;
+  // One decider for `--yes --dry-run`: the inline copy used to agree with it today,
+  // but a second copy of the same arithmetic is where the next bypass grows (Q09).
+  const { dryRun, apply } = writeMode(flags);
 
   const manifestAction = exists ? 'update' : 'create';
   const manifestFile = await manifestPath(root);
@@ -280,11 +283,69 @@ export async function initCommand(positional, flags) {
     );
   }
 
+  // The `--diff` pairs, read before anything is written so the before side is
+  // true in preview and in apply alike (R50). The after-bytes reuse the exact
+  // render calls the apply path below writes, so the diff shows the write
+  // rather than a second opinion about it. Pointers carry no bytes, so the
+  // plan lines naming the link targets are already their whole story.
+  let diffs = [];
+  if (flags.diff === true) {
+    diffs = [
+      {
+        path: MANIFEST_FILE,
+        before: await readBefore(manifestFile),
+        after: manifestText(manifest),
+      },
+    ];
+    if (payload.identity.action === 'created') {
+      diffs.push({
+        path: IDENTITY_FILE,
+        before: null,
+        after: renderIdentityFile(identity),
+      });
+    }
+    if (payload.ci.action === 'create') {
+      diffs.push({
+        path: payload.ci.file,
+        before: await readBefore(join(root, payload.ci.file)),
+        after: renderWorkflow({ own: payload.ci.own, npm, version }),
+      });
+    }
+    if (payload.dependabot.action === 'create') {
+      diffs.push({
+        path: payload.dependabot.file,
+        before: await readBefore(join(root, payload.dependabot.file)),
+        after: renderDependabot(payload.dependabot.facts, {
+          stack: payload.dependabot.stack,
+          own: payload.dependabot.own,
+        }),
+      });
+    }
+    if (payload.tsconfigBase.action === 'create') {
+      diffs.push({
+        path: payload.tsconfigBase.file,
+        before: await readBefore(join(root, payload.tsconfigBase.file)),
+        after: renderTsconfigBase(),
+      });
+    }
+    for (const target of projected.targets) {
+      if (target.action === 'unchanged' || target.action === 'malformed') continue;
+      diffs.push({
+        path: target.file,
+        before: await readBefore(target.path),
+        after: target.text,
+      });
+    }
+    Object.assign(payload, diffField(diffs, flags));
+  }
+
   // Step 4/5: report everything, then make changes only when told to.
   if (isJson(flags)) {
     if (!apply) emitJson(payload);
   } else {
     emit(render(payload, manifest, { npm, version }));
+    // After the report: the report says what, the diff shows it (R50).
+    emitDiffs(diffs, flags);
   }
   if (!apply) {
     note('');
@@ -331,7 +392,10 @@ export async function initCommand(positional, flags) {
     note(`branch   switched to ${git.branch}; ${git.from} is untouched and \`git checkout ${git.from}\` returns to it`);
   }
 
-  await writeManifest(root, manifest);
+  // Every repo-file write below is journaled, so `undo` can restore this run
+  // (R49). Pointer symlinks carry no bytes and are not journaled.
+  const journal = [];
+  await writeManifest(root, manifest, journal);
   note(`wrote    ${MANIFEST_FILE} (${manifestAction})`);
 
   // Identity last, and for the same reason the gate is written after the manifest:
@@ -345,7 +409,7 @@ export async function initCommand(positional, flags) {
   // because replacing it when it is already right would be a no-op that reads as
   // a change.
   if (payload.identity.action === 'created') {
-    await writeFile(join(root, IDENTITY_FILE), renderIdentityFile(identity));
+    await journaledWriteFile(root, journal, join(root, IDENTITY_FILE), renderIdentityFile(identity));
     await ignoreIdentity(root);
     note(`wrote    ${IDENTITY_FILE} (${identity.from === 'last-commit' ? 'from the last commit in this repository' : 'from the identity configured on this machine'}); gitignored, because it is yours and not the repository's`);
   } else if (payload.identity.action === 'unchanged') {
@@ -369,7 +433,7 @@ export async function initCommand(positional, flags) {
   // guaranteed to be misled.
   if (payload.ci.action === 'create') {
     await mkdir(dirname(join(root, payload.ci.file)), { recursive: true });
-    await writeFile(join(root, payload.ci.file), renderWorkflow({ own: payload.ci.own, npm, version }));
+    await journaledWriteFile(root, journal, join(root, payload.ci.file), renderWorkflow({ own: payload.ci.own, npm, version }));
     note(`wrote    ${payload.ci.file} (create; yours to edit from here, simt-dev will not rewrite it)`);
   }
   if (payload.dependabot.action === 'create') {
@@ -378,7 +442,9 @@ export async function initCommand(positional, flags) {
     // in the plan below are the bytes written here, and re-detecting would make the
     // printed entry list and the written one disagree the moment a manifest appears
     // between the two calls.
-    await writeFile(
+    await journaledWriteFile(
+      root,
+      journal,
       join(root, payload.dependabot.file),
       renderDependabot(payload.dependabot.facts, {
         stack: payload.dependabot.stack,
@@ -390,7 +456,7 @@ export async function initCommand(positional, flags) {
     );
   }
   if (payload.tsconfigBase.action === 'create') {
-    await writeFile(join(root, payload.tsconfigBase.file), renderTsconfigBase());
+    await journaledWriteFile(root, journal, join(root, payload.tsconfigBase.file), renderTsconfigBase());
     note(
       `wrote    ${payload.tsconfigBase.file} (create; ${TSCONFIG_BASE_FILE} is JSON, so it cannot say this itself — add "extends": "./${TSCONFIG_BASE_FILE}" to your tsconfig.json or nothing reads it)`,
     );
@@ -418,7 +484,7 @@ export async function initCommand(positional, flags) {
     // no such configuration at all will not have. Creating them is part of adopting,
     // not a detail of writing the file.
     await mkdir(dirname(target.path), { recursive: true });
-    await writeFile(target.path, target.text);
+    await journaledWriteFile(root, journal, target.path, target.text);
     note(`wrote    ${target.file} (${target.action})`);
   }
 
@@ -441,6 +507,10 @@ export async function initCommand(positional, flags) {
   for (const p of pointerBlocked) {
     note(`BLOCKED ${p.file}: ${p.detail} (${p.bytes} bytes); left as it is`);
   }
+  await commitJournal(root, 'init', journal);
+  // The tree changed, so the last `check` no longer describes it: the line
+  // goes back to "no cache" rather than reporting the tree as it was (R48).
+  await invalidateCheckCache(root);
   payload.written = true;
 
   if (isJson(flags)) emitJson(payload);

package/src/commands/lease.mjs

@@ -0,0 +1,136 @@
+// `simt lease [<paths>...]`: claim files for one session, or read the claims (R54).
+//
+// The claim is the half of ADR-101 a session does by hand: `lease src/a.mjs --session
+// alpha` records that alpha is working on the path until a TTL expires, the pre-edit
+// hook reads the same file to refuse anyone else, and a bare `lease` lists what is
+// currently held — because the first question a blocked session asks is "who has
+// this", and opening a JSON file by hand is not an answer the tool should outsource.
+//
+// Two refusals are deliberate and both come from ADR-101: a path another session
+// still holds is not taken (stealing is what the TTL is for, and the error names the
+// holder and the expiry), and a claim file that will not parse is not overwritten
+// (the hook fails closed on that same file, so writing over it would erase the very
+// claims the hook is about to enforce while telling the author it fixed something).
+
+import { EXIT, emit, emitJson, fail, isJson, writeMode } from '../output/index.mjs';
+import { DEFAULT_TTL_SECONDS, activeLeases, leasePathFor, readLeases, writeLeases } from '../lease.mjs';
+import { SESSION_ENV } from '../agenthooks/policy.mjs';
+import { CLI } from '../name.mjs';
+
+const ISO = (ms) => new Date(ms).toISOString();
+
+export async function leaseCommand(args, flags) {
+  const root = flags.root ?? process.cwd();
+
+  // A session or a TTL with no paths is a claim about nothing; the parser would
+  // otherwise hand back a list the caller never asked to see.
+  if (args.length === 0) {
+    if (flags.session !== undefined || flags.ttl !== undefined) {
+      return fail(`lease without paths is a list, so it takes neither --session nor --ttl`, EXIT.USAGE, `run: ${CLI} lease <paths> --session <id>`);
+    }
+    return listLeases(root, flags);
+  }
+
+  const session = String(flags.session ?? process.env[SESSION_ENV] ?? '');
+  if (session === '') {
+    return fail(`lease needs a session to hold the claim`, EXIT.USAGE, `run: ${CLI} lease <paths> --session <id> (or set ${SESSION_ENV})`);
+  }
+  const ttl = flags.ttl === undefined ? DEFAULT_TTL_SECONDS : Number(flags.ttl);
+  if (!Number.isInteger(ttl) || ttl < 1) {
+    return fail(`--ttl must be a positive number of seconds, received ${flags.ttl}`, EXIT.USAGE, `example: run: ${CLI} lease <paths> --ttl 900`);
+  }
+
+  const wanted = [];
+  const seen = new Set();
+  for (const arg of args) {
+    const rel = leasePathFor(root, arg);
+    if (rel === null) {
+      return fail(`${arg} is not a path inside the repository`, EXIT.USAGE, `leases are repository-relative: run: ${CLI} lease <path> --session ${session}`);
+    }
+    if (!seen.has(rel)) {
+      seen.add(rel);
+      wanted.push(rel);
+    }
+  }
+
+  const read = await readLeases(root);
+  if (read.error !== null) {
+    return fail(`${read.error}`, EXIT.FAIL, `fix or remove ${read.path}; the pre-edit hook fails closed on it too`);
+  }
+  const held = activeLeases(read);
+  const conflicts = held.filter((l) => seen.has(l.path) && l.session !== session);
+  if (conflicts.length > 0) {
+    return fail(
+      `${conflicts.map((c) => `${c.path} is leased by ${c.session} until ${ISO(c.expiresAt)}`).join('; ')}`,
+      EXIT.FAIL,
+      `wait for the TTL or ask the holder to release it; run: ${CLI} lease to see every claim`,
+    );
+  }
+
+  const expiresAt = Date.now() + ttl * 1000;
+  const apply = `run: ${CLI} lease ${wanted.map((p) => JSON.stringify(p)).join(' ')} --session ${session} --yes`;
+  const mode = writeMode(flags);
+  const mine = wanted.map((path) => ({ path, session, expiresAt }));
+
+  if (!mode.apply) {
+    if (isJson(flags)) {
+      emitJson({
+        ok: true,
+        command: 'lease',
+        root,
+        dryRun: true,
+        session,
+        ttl,
+        leases: mine,
+        remedy: apply,
+      });
+      return EXIT.OK;
+    }
+    const lines = [
+      `repo     ${root}`,
+      `session  ${session}`,
+      `ttl      ${ttl}s`,
+      ...mine.map((l) => `would    lease ${l.path} until ${ISO(l.expiresAt)}`),
+      `apply    ${apply}`,
+    ];
+    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+
+  // Keep every other live claim, refresh ours, and let an expired one fall out: the
+  // write is also the only sweep the file ever gets.
+  const others = held.filter((l) => !seen.has(l.path));
+  const path = await writeLeases(root, [...others, ...mine]);
+
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'lease', root, session, ttl, dryRun: false, leases: mine, file: path });
+    return EXIT.OK;
+  }
+  const lines = [
+    `repo     ${root}`,
+    `session  ${session}`,
+    `ttl      ${ttl}s`,
+    ...mine.map((l) => `LEASED   ${l.path}  until ${ISO(l.expiresAt)}`),
+  ];
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+async function listLeases(root, flags) {
+  const read = await readLeases(root);
+  if (read.error !== null) {
+    return fail(`${read.error}`, EXIT.FAIL, `fix or remove ${read.path}`);
+  }
+  const held = activeLeases(read);
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'lease', root, leases: held });
+    return EXIT.OK;
+  }
+  const lines = [
+    `repo     ${root}`,
+    ...held.map((l) => `LEASED   ${l.path}  ${l.session}  until ${ISO(l.expiresAt)}`),
+  ];
+  if (held.length === 0) lines.push(`(no active leases)`);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}

package/src/commands/lessons.mjs

@@ -4,6 +4,7 @@
 import { resolve } from 'node:path';
 
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
+import { diffField, emitDiffs } from '../diff.mjs';
 import { CLI } from '../name.mjs';
 import { parsePathList } from '../argv.mjs';
 import {
@@ -95,6 +96,14 @@ export async function lessonsReviewCommand(args, flags) {
     return fail(result.error, EXIT.FAIL, `record a session failure-then-fix or run: ${CLI} lessons`);
   }
 
+  // The `--diff` pair: the promoted lesson file, created or refreshed (R50). The
+  // before-side rides on the result from `promoteLesson`, read before anything
+  // was written, so the diff is true in preview and in apply alike.
+  const diffs =
+    flags.diff === true
+      ? [{ path: result.path, before: result.before ?? null, after: result.markdown }]
+      : [];
+
   const payload = {
     ok: true,
     command: 'lessons review',
@@ -104,6 +113,7 @@ export async function lessonsReviewCommand(args, flags) {
     path: result.path,
     candidate: result.candidate,
     markdown: result.markdown,
+    ...diffField(diffs, flags),
   };
 
   if (isJson(flags)) {
@@ -120,6 +130,8 @@ export async function lessonsReviewCommand(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);
   if (!mode.apply) {
     note(`note    dry-run  nothing written; apply with: ${CLI} lessons review --yes`);
   }

package/src/commands/mcp.mjs

@@ -45,10 +45,10 @@ export async function mcpCommand(positional, flags) {
       [
         `simt-dev ${version} - MCP surface over stdio (protocols ${SUPPORTED_VERSIONS.join(', ')})`,
         '',
-        `${TOOLS.length} read-only tools:`,
+        `${TOOLS.length} tools (all read-only except federation_query, which starts a declared server):`,
         ...TOOLS.map((t) => `  ${t.name.padEnd(16)} ${t.description.split('.')[0]}`),
         '',
-        'No tool here writes. init, sync, hooks install, skills install and upgrade stay in the',
+        'Nothing here writes to your repositories. init, sync, hooks install, skills install and upgrade stay in the',
         'CLI, because each is meant to be read as a diff by a human before it touches anything.',
         '',
         `serve them with: ${positional[0] ?? `${CLI} mcp`}`,

package/src/commands/pack.mjs

@@ -27,6 +27,7 @@ import {
   writeScaffold,
 } from '../packs/manage.mjs';
 import { readManifest } from '../projection/manifest.mjs';
+import { diffField, emitDiffs } from '../diff.mjs';
 
 export async function packCommand(sub, args, flags) {
   if (sub === 'new') return packNew(args, flags);
@@ -100,6 +101,9 @@ async function packNew(args, flags) {
   const dir = join(resolve(flags.root ?? process.cwd()), name);
   const files = scaffoldPack({ name, source });
   const { apply, dryRun } = writeMode(flags);
+  // A scaffold always creates into a directory that must not exist, so every
+  // before side is empty and each pair is a whole file (R50).
+  const diffs = flags.diff === true ? files.map((f) => ({ path: `${name}/${f.path}`, before: null, after: f.text })) : [];
 
   if (isJson(flags)) {
     emitJson({
@@ -110,6 +114,7 @@ async function packNew(args, flags) {
       files: files.map((f) => f.path),
       packFile: PACK_JSON,
       benchFile: BENCH_JSON,
+      ...diffField(diffs, flags),
     });
     return EXIT.OK;
   }
@@ -126,6 +131,8 @@ async function packNew(args, flags) {
       ].join('\n'),
       { maxBytes: flags.maxBytes ?? 0 },
     );
+    // After the report: the report says what, the diff shows it (R50).
+    emitDiffs(diffs, flags);
     return EXIT.OK;
   }
 
@@ -144,6 +151,8 @@ async function packNew(args, flags) {
     ].join('\n'),
     { maxBytes: flags.maxBytes ?? 0 },
   );
+  // After the report: the report says what, the diff shows it (R50).
+  emitDiffs(diffs, flags);
   return EXIT.OK;
 }
 

package/src/commands/plan.mjs

@@ -1,5 +1,7 @@
+import { relative } from 'node:path';
 import { EXIT, emit, emitJson, fail, isJson, writeMode } from '../output/index.mjs';
 import { formatCounts, planDone, planNext, planStatus } from '../plan/index.mjs';
+import { diffField, emitDiffs } from '../diff.mjs';
 import { CLI } from '../name.mjs';
 
 // Preview unless --yes, and --dry-run wins even then. A tracker row marked done
@@ -79,8 +81,16 @@ async function runDone(root, id, sha, flags) {
     dryRun: !mode.apply,
   });
   if (result.error) return fail(result.error, EXIT.USAGE, result.remedy);
+  // The `--diff` pair: the one changed tracker row (R50). The sides ride on the
+  // result from `planDone`, captured pre-write, so the diff is true in preview
+  // and in apply alike. When nothing changed the sides are equal and the diff
+  // renders empty.
+  const diffs =
+    flags.diff === true && result.beforeLine !== undefined
+      ? [{ path: relative(root, result.file), before: result.beforeLine, after: result.afterLine }]
+      : [];
   if (isJson(flags)) {
-    emitJson({ ok: true, command: 'plan done', ...result });
+    emitJson({ ok: true, command: 'plan done', ...result, ...diffField(diffs, flags) });
     return EXIT.OK;
   }
   const lines = [`repo     ${root}`];
@@ -95,5 +105,7 @@ async function runDone(root, id, sha, flags) {
   if (result.evidenceRecorded) lines.push(`evidence ${result.sha}${result.test ? `  test: ${result.test}` : ''}`);
   else if (result.evidenceNote) lines.push(`note     ${result.evidenceNote}`);
   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;
 }