simt-dev 0.6.0 → 0.6.3

package/src/memory/decide.mjs

@@ -7,6 +7,7 @@ import { execFile } from 'node:child_process';
 import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
+import { journaledWriteFile } from '../journal.mjs';
 
 const exec = promisify(execFile);
 
@@ -360,9 +361,13 @@ export async function scaffoldDecision(root, options = {}) {
     supersedes,
   });
 
+  // A caller-supplied journal records the scaffold so `undo` can restore it
+  // (R49). Callers without one (probes, tests staging fixtures) keep the old
+  // behaviour exactly.
   if (options.write) {
     await mkdir(decisionsDir, { recursive: true });
-    await writeFile(fullPath, text, 'utf8');
+    if (options.journal) await journaledWriteFile(root, options.journal, fullPath, text);
+    else await writeFile(fullPath, text, 'utf8');
   }
 
   return {

package/src/memory/lessons.mjs

@@ -642,6 +642,17 @@ export async function promoteLesson(root, options = {}) {
   const relPath = `${LESSONS_DIR}/${num}-${slug}.md`;
   const markdown = renderLessonMarkdown(target, options);
 
+  // The `--diff` before-side, read before anything is written so the diff is true
+  // in preview and in apply alike (R50). Always a creation in practice — the
+  // number is fresh — but a hand-placed file at the same path would be
+  // overwritten, and a diff that claimed a creation there would lie about it.
+  let before = null;
+  try {
+    before = await readFile(join(root, relPath), 'utf8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+
   if (options.apply) {
     const fullPath = join(root, relPath);
     await mkdir(dirname(fullPath), { recursive: true });
@@ -656,6 +667,7 @@ export async function promoteLesson(root, options = {}) {
     candidate: target,
     path: relPath,
     markdown,
+    before,
     written: Boolean(options.apply),
   };
 }

package/src/output/index.mjs

@@ -144,20 +144,90 @@ export function jsonIndentDefault(pretty = process.stdout.isTTY === true) {
  * the only consumer is a person: the compact document saves them nothing and costs them
  * the diff they were about to read.
  */
+function withSchemaVersion(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) && value.schemaVersion === undefined
+    ? { schemaVersion: SCHEMA_VERSION, ...value }
+    : value;
+}
+
+function stringifyJson(value, pretty) {
+  return pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value);
+}
+
+/**
+ * Shrink a payload to a byte ceiling by emptying its longest arrays first.
+ *
+ * Byte-cutting JSON produces a document that parses or exits non-zero, never both —
+ * `why --json --max-bytes 120` used to exit 0 with half a token on stdout (Q10). An
+ * importer owns nothing here: the trimmed arrays are named in `truncated`, so a reader
+ * knows exactly which list lost how many items, and the document still parses.
+ *
+ * Returns the fitted payload, or null when no array-trimming fits (the caller then
+ * answers with the `MAX_BYTES` error envelope instead).
+ */
+function fitJsonArrays(payload, maxBytes, pretty) {
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) return null;
+  const slots = [];
+  const walk = (node, path) => {
+    if (Array.isArray(node)) {
+      if (node.length > 0) slots.push({ node, path, length: node.length });
+      node.forEach((item, i) => walk(item, `${path}[${i}]`));
+    } else if (node !== null && typeof node === 'object') {
+      for (const key of Object.keys(node)) walk(node[key], path === '' ? key : `${path}.${key}`);
+    }
+  };
+  walk(payload, '');
+  if (slots.length === 0) return null;
+  slots.sort((a, b) => b.length - a.length);
+  const candidate = structuredClone(payload);
+  const trimmed = [];
+  const sizeOf = (extra) =>
+    Buffer.byteLength(stringifyJson(extra ? { ...candidate, truncated: extra } : candidate, pretty));
+  const segmentsOf = (path) =>
+    path.split('.').flatMap((part) => {
+      const m = /^(.*?)\[(\d+)\]$/.exec(part);
+      return m ? [m[1], Number(m[2])] : [part];
+    });
+  for (const slot of slots) {
+    const at = segmentsOf(slot.path);
+    let target = candidate;
+    for (let i = 0; i < at.length - 1; i += 1) target = target[at[i]];
+    if (target === null || typeof target !== 'object') continue;
+    target[at[at.length - 1]] = [];
+    trimmed.push({ field: slot.path, omitted: slot.length });
+    const extra = trimmed.length === 1
+      ? { field: trimmed[0].field, omitted: trimmed[0].omitted, limit: maxBytes }
+      : { fields: trimmed, limit: maxBytes };
+    if (sizeOf(extra) <= maxBytes) return { ...candidate, truncated: extra };
+  }
+  return null;
+}
+
 export function emitJson(value, { stream = process.stdout, pretty = prettyDefault, maxBytes = 0 } = {}) {
-  const payload =
-    value !== null && typeof value === 'object' && !Array.isArray(value) && value.schemaVersion === undefined
-      ? { schemaVersion: SCHEMA_VERSION, ...value }
-      : value;
-  const text = `${pretty ? JSON.stringify(payload, null, 2) : JSON.stringify(payload)}\n`;
-  // The same ceiling and the same announcement `emit` applies: a reader who asked for a
-  // bounded answer gets a bounded answer and is told how much is missing, rather than a
-  // half-parsed document it believes is whole.
+  const payload = withSchemaVersion(value);
+  const text = `${stringifyJson(payload, pretty)}\n`;
+  // JSON is never byte-truncated: a cut document parses as a lie, and exit 0 calls it
+  // true. Arrays shrink with a `truncated` record naming what lost how much, and a
+  // document no trimming can fit becomes a `MAX_BYTES` error envelope (Q10, ADR-105).
   if (maxBytes > 0 && Buffer.byteLength(text) > maxBytes) {
-    const slice = Buffer.from(text).subarray(0, maxBytes).toString('utf8');
-    const cut = slice.lastIndexOf('\n');
-    stream.write(cut > 0 ? `${slice.slice(0, cut)}\n` : slice);
-    stream.write(`TRUNCATED ${Buffer.byteLength(text) - maxBytes} bytes omitted, raise maxBytes\n`);
+    const fitted = fitJsonArrays(payload, maxBytes, pretty);
+    if (fitted !== null) {
+      stream.write(`${stringifyJson(fitted, pretty)}\n`);
+      return false;
+    }
+    const envelope = withSchemaVersion({
+      ...(payload !== null && typeof payload === 'object' && !Array.isArray(payload) && typeof payload.command === 'string'
+        ? { command: payload.command }
+        : {}),
+      ok: false,
+      error: {
+        code: 'MAX_BYTES',
+        message: `output exceeded the --max-bytes ceiling of ${maxBytes} bytes`,
+        remedy: 'rerun with --max-bytes 0 for the whole document',
+      },
+      truncated: { omitted: Buffer.byteLength(text) - maxBytes, limit: maxBytes },
+    });
+    stream.write(`${stringifyJson(envelope, pretty)}\n`);
     return false;
   }
   stream.write(text);

package/src/package-version.mjs

@@ -14,9 +14,11 @@
 //     must match: npm pins the node_modules copy for us, but nothing pins a binary, so
 //     the gate compares the running version against the pin and refuses on a mismatch.
 
+import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { stat } from 'node:fs/promises';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { MANIFEST_FILE } from './name.mjs';
 
@@ -38,6 +40,52 @@ export function packageVersion() {
   }
 }
 
+/** The directory this package is installed in, whatever resolved the import. */
+function packageRootDir() {
+  return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+
+/**
+ * The short commit this checkout is at, or null outside a git checkout (an
+ * installed tarball or wheel has no `.git`). Read-only and best-effort: a
+ * version string must never fail because the VCS is absent (Q05).
+ */
+export function checkoutSha() {
+  try {
+    const sha = execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
+      cwd: packageRootDir(),
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return /^[0-9a-f]+$/.test(sha) ? sha : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What `--version` prints: the package version, plus the checkout SHA when run
+ * from a source tree past its tag. A `main` 26 commits past v0.6.2 reporting
+ * bare `0.6.2` is the drift Q05 closes: the number alone claims a release the
+ * bytes are not (Q05).
+ */
+export function describeVersion() {
+  const version = packageVersion();
+  const sha = checkoutSha();
+  if (!sha) return `simt-dev ${version}`;
+  try {
+    const tag = execFileSync('git', ['describe', '--tags', '--exact-match'], {
+      cwd: packageRootDir(),
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (tag === `v${version}`) return `simt-dev ${version}`;
+  } catch {
+    // Not exactly on the release tag: fall through to the SHA suffix.
+  }
+  return `simt-dev ${version} (${sha})`;
+}
+
 /**
  * Whether a repository has a package.json, i.e. whether it pins simt-dev as a
  * devDependency (npm) or must download the release binary (ADR-098). Async because the render

package/src/packs/manage.mjs

@@ -14,7 +14,8 @@
 // copied in and pinned by digest, never fetched at render time.
 
 import { execFile } from 'node:child_process';
-import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, stat } from 'node:fs/promises';
+import { commitJournal, journaledWriteFile } from '../journal.mjs';
 import { createHash } from 'node:crypto';
 import { basename, dirname, join } from 'node:path';
 import { promisify } from 'node:util';
@@ -545,8 +546,14 @@ export async function publishPack(dir, { apply = false } = {}) {
   return { pack: linted.pack, ok: true, published: true, skipped: false, planned, findings };
 }
 
-/** Write scaffold files into a directory that must not already exist. */
-export async function writeScaffold(dir, files) {
+/**
+ * Write scaffold files into a directory that must not already exist.
+ *
+ * `root` is the repository the journal set belongs to — usually the scaffold's
+ * own parent, so `undo` runs where the files live. Recorded (R49) because a
+ * scaffold is repo files like any other write.
+ */
+export async function writeScaffold(dir, files, root = dirname(dir)) {
   try {
     await stat(dir);
     throw new Error(
@@ -555,9 +562,11 @@ export async function writeScaffold(dir, files) {
   } catch (error) {
     if (error?.message?.startsWith('refusing to scaffold')) throw error;
   }
+  const journal = [];
   for (const file of files) {
     const abs = join(dir, file.path);
     await mkdir(dirname(abs), { recursive: true });
-    await writeFile(abs, file.text, 'utf8');
+    await journaledWriteFile(root, journal, abs, file.text);
   }
+  await commitJournal(root, 'pack new', journal);
 }

package/src/plan/index.mjs

@@ -632,6 +632,12 @@ export async function planDone(root, id, { sha = null, test = null, state = null
     line: found.index + 1,
     from,
     to: cells[slice.stateIdx],
+    // The `--diff` sides for the one changed row (plan 0003 R50). The full file
+    // is not carried: one table row is the whole write, and a context-less hunk
+    // over the row says exactly what changed. Captured pre-write, so the diff
+    // is true in preview and in apply alike.
+    beforeLine: original,
+    afterLine: newLine,
     state: format.readState(display),
     wouldChange,
     changed: wouldChange && !dryRun,

package/src/plugins.mjs

@@ -24,7 +24,9 @@
 // leaves the machine it was built on. The command says so rather than pretending.
 
 import { cp, mkdir, readFile, writeFile } from 'node:fs/promises';
-import { basename, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readBefore } from './diff.mjs';
 import { hookDocument } from './agenthooks/render.mjs';
 import { desiredRegion } from './projection/rules.mjs';
 import { PACKAGE_NAME, BIN_REL } from './name.mjs';
@@ -32,6 +34,15 @@ import { PACKAGE_NAME, BIN_REL } from './name.mjs';
 /** The kinds `simt plugin` builds, in the order the help line names them. */
 export const PLUGIN_KINDS = ['claude', 'gemini', 'cursor'];
 
+/**
+ * The package this code ships in: the runtime a generated package copies. Resolved
+ * from the module URL, not from the consumer's cwd, so `plugin` built with
+ * `--root <consumer>` still ships this tool rather than the consumer's files (Q03).
+ */
+function packageRoot() {
+  return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+
 /** Where the runtime copy lands inside a package, relative to the package root. */
 function runtimeDir(kind) {
   return kind === 'cursor' ? join('.cursor', 'simt') : '.';
@@ -71,7 +82,7 @@ const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
  * it is many files; this returns only the handful that are authored here.
  */
 async function packageFiles(kind, { root = process.cwd(), out } = {}) {
-  const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+  const pkg = JSON.parse(await readFile(join(packageRoot(), 'package.json'), 'utf8'));
   const command = `${entryPoint(kind)} agent-hook pre-tool-use --harness ${kind}${rootFlag(kind)}`;
   const files = [];
 
@@ -128,12 +139,21 @@ export async function buildPackage(kind, { root = process.cwd(), out, apply = fa
     throw new Error(`unknown package kind \`${kind}\`; one of: ${PLUGIN_KINDS.join(', ')}`);
   }
 
-  const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+  const pkg = JSON.parse(await readFile(join(packageRoot(), 'package.json'), 'utf8'));
   const files = await packageFiles(kind, { root, out });
   const notes = [
     'the skill registry is workspace data (ADR-061) and is not shipped; run `simt skills index` in the profile to list what a workspace would offer',
   ];
 
+  // The `--diff` before-sides, read before anything is written so the diff is
+  // true in preview and in apply alike (R50). Always captured: the files are a
+  // handful of small generated configs. The runtime copy below is excluded — it
+  // is a mechanical copy of this tool's own sources, not planned content, and
+  // diffing it would reprint the tool into the review.
+  for (const f of files) {
+    f.before = await readBefore(join(out, f.path));
+  }
+
   if (apply) {
     const runtimeTarget = join(out, runtimeDir(kind));
     await mkdir(runtimeTarget, { recursive: true });
@@ -142,10 +162,11 @@ export async function buildPackage(kind, { root = process.cwd(), out, apply = fa
     // dies on the first MCP call: the server reads templates/ and rules/, which a
     // bin+src-only copy leaves behind. The `files` field is the definition of "a working
     // copy of this tool", so it is the set a package ships.
+    const runtimeRoot = packageRoot();
     for (const part of pkg.files) {
-      await cp(join(root, part), join(runtimeTarget, part), { recursive: true });
+      await cp(join(runtimeRoot, part), join(runtimeTarget, part), { recursive: true });
     }
-    await cp(join(root, 'package.json'), join(runtimeTarget, 'package.json'));
+    await cp(join(runtimeRoot, 'package.json'), join(runtimeTarget, 'package.json'));
     for (const f of files) {
       const target = join(out, f.path);
       await mkdir(join(target, '..'), { recursive: true });
@@ -158,7 +179,7 @@ export async function buildPackage(kind, { root = process.cwd(), out, apply = fa
     out,
     apply,
     runtime: { target: runtimeDir(kind), parts: [...pkg.files, 'package.json'] },
-    files: files.map(({ text, ...rest }) => rest),
+    files,
     notes,
   };
 }

package/src/prbody.mjs

@@ -0,0 +1,251 @@
+// The `simt pr-body` engine (plan 0003 R55).
+//
+// A pull request body assembled from what the tool already knows, rather than
+// what its author remembers to write: the evidence block from the ledger (R17),
+// the decision records the diff touches, the gate state from the last check,
+// and the residual risk in ADR-008's verdict vocabulary. Read-only throughout:
+// it names the tree, reads the ledger, reads the check cache and diffs names,
+// and writes nothing, so it needs no preview, no `--yes` and no journal entry.
+//
+// The base defaults to the branch's upstream fork point (`origin/main`, then
+// `main`), and `--base` names anything else. When no base resolves, the body
+// falls back to the working-tree diff against HEAD: a report that refused
+// without a base would be useless on a repository with a single branch.
+
+import { execFile } from 'node:child_process';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { readLedger, treeId } from './ledger/index.mjs';
+import { readCheckCache } from './status.mjs';
+import { readManifest } from './projection/manifest.mjs';
+import { splitFrontmatter } from './memory/decide.mjs';
+
+const exec = promisify(execFile);
+
+const DECISIONS_DIR = join('docs', 'decisions');
+
+/**
+ * The ref the body diffs against: the override when given, else the first
+ * candidate that shares history with HEAD. Returns the ref, or null when the
+ * repository has a single branch and the body should diff the worktree.
+ */
+async function resolveBase(root, override = null) {
+  if (override !== null && override !== undefined && String(override) !== '') {
+    try {
+      await exec('git', ['rev-parse', '--verify', '--quiet', `${override}^{commit}`], { cwd: root });
+      return { base: String(override), error: null };
+    } catch {
+      return { base: null, error: `unknown base ${override}` };
+    }
+  }
+  for (const candidate of ['origin/main', 'main', 'origin/master', 'master']) {
+    try {
+      await exec('git', ['merge-base', 'HEAD', candidate], { cwd: root });
+      return { base: candidate, error: null };
+    } catch {
+      // Not present or shares no history; the next candidate may.
+    }
+  }
+  return { base: null, error: null };
+}
+
+/**
+ * Every path the pull request would carry: the branch range when there is a
+ * base, plus whatever the worktree adds on top. Sorted, deduplicated, and
+ * without `.simt/` state: the ledger and the check cache prove the body, they
+ * are not its content.
+ */
+async function changedPaths(root, base) {
+  const paths = new Set();
+  const add = (stdout) => {
+    for (const line of String(stdout ?? '').split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed !== '' && !trimmed.startsWith('.simt/')) paths.add(trimmed);
+    }
+  };
+  if (base !== null) {
+    try {
+      const { stdout } = await exec('git', ['diff', '--name-only', `${base}...HEAD`], {
+        cwd: root,
+        maxBuffer: 16 << 20,
+      });
+      add(stdout);
+    } catch {
+      // An unborn HEAD or an unreadable range contributes nothing; the worktree
+      // reads below still answer.
+    }
+  }
+  for (const args of [
+    ['diff', '--name-only', 'HEAD'],
+    ['ls-files', '--others', '--exclude-standard'],
+  ]) {
+    try {
+      const { stdout } = await exec('git', args, { cwd: root, maxBuffer: 16 << 20 });
+      add(stdout);
+    } catch {
+      // Not a repository, or no commit yet: the body reports the absence.
+    }
+  }
+  return [...paths].sort();
+}
+
+/**
+ * The decision records the diff touches: one entry per `docs/decisions/*.md`
+ * in the changed paths, carrying the id from the filename and the title and
+ * status from the file itself. Sorted by id; a file that will not parse is
+ * reported with what it has rather than dropping the row.
+ */
+async function changedDecisions(root, paths) {
+  const names = paths.filter((p) => p.startsWith(`${DECISIONS_DIR}/`) && p.toLowerCase().endsWith('.md'));
+  try {
+    await readdir(join(root, DECISIONS_DIR));
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names.sort()) {
+    const id = /^ADR-\d{3,}/i.exec(name.slice(DECISIONS_DIR.length + 1))?.[0].toUpperCase() ?? name;
+    let title = id;
+    let status = 'unknown';
+    try {
+      const text = await readFile(join(root, name), 'utf8');
+      const { body } = splitFrontmatter(text);
+      const heading = /^#\s+(.*)$/m.exec(body)?.[1] ?? id;
+      title = heading.replace(/^ADR-\d{3,}\s*[—–-]\s*/i, '').trim() || id;
+      status = /^Status:\s*(.+)$/im.exec(body)?.[1].trim() ?? 'unknown';
+    } catch {
+      // An unreadable record is still a changed decision; the body says so
+      // rather than silently omitting a file the diff names.
+    }
+    out.push({ path: name, id, title, status });
+  }
+  return out;
+}
+
+/**
+ * Assemble the whole body. Never throws for a missing ledger, cache or base:
+ * each absence is a line in the report, because a PR body whose evidence is
+ * missing is precisely the case the residual-risk section exists to say out loud.
+ */
+export async function buildPrBody(root, { base = null } = {}) {
+  const resolved = await resolveBase(root, base);
+  if (resolved.error !== null) return { error: resolved.error };
+
+  let tree = null;
+  let treeError = null;
+  try {
+    tree = await treeId(root);
+  } catch (error) {
+    treeError = String(error.message ?? error);
+  }
+
+  let entries = [];
+  let ledgerErrors = [];
+  try {
+    const ledger = await readLedger(root);
+    entries = tree === null ? [] : ledger.entries.filter((e) => e.tree === tree);
+    ledgerErrors = ledger.errors;
+  } catch (error) {
+    ledgerErrors = [String(error.message ?? error)];
+  }
+
+  const cache = await readCheckCache(root).catch(() => null);
+  const { manifest } = await readManifest(root).catch(() => ({ manifest: null }));
+  const declared = [
+    ...(manifest?.gates?.preCommit ?? []),
+    ...(manifest?.gates?.prePush ?? []),
+  ];
+  const evidenceMode = manifest?.gates?.evidence;
+
+  const paths = await changedPaths(root, resolved.base);
+  const decisions = await changedDecisions(root, paths);
+
+  const passing = entries.filter((e) => e.exit === 0);
+  const unreviewed = [];
+  if (tree === null) unreviewed.push(`the tree could not be named (${treeError ?? 'not a git repository'})`);
+  else if (passing.length === 0) unreviewed.push('no passing run is recorded for this tree');
+  if (cache === null) unreviewed.push('gate state unmeasured (no check has run)');
+  for (const error of ledgerErrors) unreviewed.push(`ledger unreadable: ${error}`);
+
+  // ADR-008's vocabulary, exactly: BLOCK for a known failure, APPROVE WITH
+  // RESIDUAL RISK when the review budget ran out before something was read,
+  // APPROVE only when everything was. The constraint travels with the verdict:
+  // a residual-risk body never converts a known failure into an approval.
+  const blocking = cache?.blocking ?? 0;
+  const verdict = blocking > 0 ? 'BLOCK' : unreviewed.length > 0 ? 'APPROVE WITH RESIDUAL RISK' : 'APPROVE';
+
+  return {
+    error: null,
+    base: resolved.base,
+    tree,
+    evidence: { entries, errors: ledgerErrors },
+    decisions,
+    paths,
+    gates: {
+      declared,
+      evidenceMode: evidenceMode ?? null,
+      run: cache === null ? null : { gatesRun: cache.gatesRun, gatesTotal: cache.gatesTotal },
+      rulesOk: cache?.rulesOk ?? null,
+      hooksOk: cache?.hooksOk ?? null,
+      blocking,
+      warnings: cache?.warnings ?? 0,
+      cached: cache !== null,
+    },
+    verdict,
+    unreviewed,
+  };
+}
+
+/**
+ * The markdown body: four sections in a fixed order — evidence, changed
+ * decisions, gates, residual risk — so a snapshot can pin it byte for byte.
+ */
+export function renderPrBody(report) {
+  const lines = [];
+  lines.push('## Evidence');
+  lines.push('');
+  if (report.tree === null) {
+    lines.push('No tree recorded: run this inside a git repository.');
+  } else if (report.evidence.entries.length === 0) {
+    lines.push(`tree ${report.tree}`);
+    lines.push('No run is recorded for this tree.');
+  } else {
+    lines.push(`tree ${report.tree}`);
+    lines.push('');
+    for (const e of report.evidence.entries) {
+      lines.push(`- ${e.exit === 0 ? 'pass' : 'fail'} \`${e.cmd}\` (exit ${e.exit}, ${e.summary})`);
+    }
+  }
+  for (const error of report.evidence.errors) lines.push(`- ledger error: ${error}`);
+  lines.push('');
+  lines.push('## Changed decisions');
+  lines.push('');
+  if (report.decisions.length === 0) {
+    lines.push(`None${report.base === null ? ' (worktree diff against HEAD)' : ` (range ${report.base}...HEAD, plus worktree)`}.`);
+  } else {
+    for (const d of report.decisions) lines.push(`- ${d.id} — ${d.title} (${d.status})`);
+  }
+  lines.push('');
+  lines.push('## Gates');
+  lines.push('');
+  if (report.gates.cached) {
+    const g = report.gates;
+    lines.push(`- rules: ${g.rulesOk ? 'ok' : 'failing'}, hooks: ${g.hooksOk ? 'ok' : 'failing'}`);
+    lines.push(`- gates run: ${g.run.gatesRun}/${g.run.gatesTotal}, blocking: ${g.blocking}, warnings: ${g.warnings}`);
+    if (g.declared.length > 0) lines.push(`- declared: ${g.declared.join(', ')}`);
+  } else {
+    lines.push('No check has run: gate state unmeasured.');
+  }
+  lines.push('');
+  lines.push('## Residual risk (ADR-008)');
+  lines.push('');
+  lines.push(`Verdict: ${report.verdict}`);
+  if (report.unreviewed.length > 0) {
+    lines.push('');
+    lines.push('Not reviewed:');
+    for (const item of report.unreviewed) lines.push(`- ${item}`);
+  }
+  return `${lines.join('\n')}\n`;
+}

package/src/projection/manifest.mjs

@@ -18,6 +18,7 @@
 import { readFile, rename, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
+import { journaledWriteFile } from '../journal.mjs';
 // gates.mjs imports nothing, so this direction cannot cycle. It is the gate table
 // this file already selects from; duplicating the runnability rules here would be two
 // answers to "can this repo run that gate", which is precisely the kind of drift this
@@ -225,6 +226,12 @@ export function gateRunnable(gate, capability = {}) {
       : { runnable: true, why: `runs: ${declared}` };
   }
 
+  if (gate.kind === 'builtin') {
+    // The one kind with no external requirement: the implementation ships inside
+    // the binary that is reading this manifest (ADR-100). Saying otherwise would
+    // make `check` report a gate as unrunnable that runs on every commit.
+    return { runnable: true, why: 'runs inside the tool itself; nothing to install' };
+  }
   if (gate.kind === 'command') {
     return { runnable: false, why: `no command is declared for it in gates.commands` };
   }
@@ -851,13 +858,17 @@ export async function readManifest(root) {
   }
 }
 
-export async function writeManifest(root, manifest) {
+export async function writeManifest(root, manifest, journal = null) {
   // A repository still holding the old name gets it moved, not shadowed. Two manifests
   // in one repo is a manifest nobody can reason about, and the second would be the one
   // that is never read - so the window closes by moving the file, not by leaving both.
   const previous = join(root, MANIFEST_LEGACY);
   const fresh = join(root, MANIFEST);
   if (existsSync(previous) && !existsSync(fresh)) await rename(previous, fresh);
-  await writeFile(fresh, manifestText(manifest));
+  // A journaled manifest is one `undo` can restore, like every other repo file a
+  // command writes (R49). Callers that span repos or the repo boundary (shared,
+  // bench) pass nothing and keep the old behaviour exactly.
+  if (journal) await journaledWriteFile(root, journal, fresh, manifestText(manifest));
+  else await writeFile(fresh, manifestText(manifest));
   return fresh;
 }

package/src/projection/shared.mjs

@@ -307,7 +307,10 @@ export async function sharedState(path, rules, meta) {
  * user-level AGENTS.md is the most likely file in a reader's home directory to contain
  * something they wrote themselves. Only the bytes between the markers are ours.
  */
-function injectShared(before, rules, meta) {
+// Exported so `shared install --diff` previews the same bytes the write applies:
+// a diff rendered from a second implementation of this injection would be a
+// second opinion about what "current" means (plan 0003 R50).
+export function injectShared(before, rules, meta) {
   return inject(before, sharedBody(rules), meta, { compose: composeShared });
 }