altimate-receipts 0.3.2 → 0.4.0

package/dist/cli.js

@@ -45,14 +45,291 @@ import {
 } from "./chunk-UHI6BGLE.js";
 
 // src/cli.ts
-import { spawnSync } from "child_process";
-import { existsSync, mkdirSync, readFileSync as readFileSync4, realpathSync, writeFileSync } from "fs";
-import { join as join4, relative } from "path";
+import { spawnSync as spawnSync3 } from "child_process";
+import {
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync6,
+  readdirSync as readdirSync3,
+  realpathSync,
+  unlinkSync,
+  writeFileSync as writeFileSync3
+} from "fs";
+import { homedir } from "os";
+import { join as join6, relative } from "path";
 import { pathToFileURL } from "url";
 
+// src/hook/installGitHook.ts
+import { spawnSync } from "child_process";
+import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { isAbsolute, join } from "path";
+var MARKER = "altimate-receipts";
+var HOOK_SCRIPT = `#!/bin/sh
+# Verified-by-Receipts pre-push hook \u2014 generated by \`receipts install-hook\` (altimate-receipts).
+# Attaches this branch's agent receipt before pushing. Best-effort: only the
+# deliberate "receipt attached, push again" signal (exit 42) ever stops a push.
+hookdir=$(dirname "$0")
+if [ -x "$hookdir/pre-push.local" ]; then
+  "$hookdir/pre-push.local" "$@" </dev/null || exit $?
+fi
+command -v npx >/dev/null 2>&1 || exit 0
+npx -y altimate-receipts@latest hook pre-push --agent git
+[ "$?" -eq 42 ] && exit 1
+exit 0
+`;
+function hooksDir(cwd) {
+  const r = spawnSync("git", ["rev-parse", "--git-path", "hooks"], { encoding: "utf8", cwd });
+  if (r.status !== 0) {
+    return null;
+  }
+  const p = r.stdout.trim();
+  return isAbsolute(p) ? p : join(cwd ?? process.cwd(), p);
+}
+function installGitHook(cwd) {
+  const dir = hooksDir(cwd);
+  if (!dir) {
+    return { ok: false, reason: "not a git repository" };
+  }
+  const target = join(dir, "pre-push");
+  const local = join(dir, "pre-push.local");
+  if (existsSync(target)) {
+    const current = readFileSync(target, "utf8");
+    if (current.includes(MARKER)) {
+      if (current === HOOK_SCRIPT) {
+        return { ok: true, action: "unchanged" };
+      }
+      writeFileSync(target, HOOK_SCRIPT);
+      chmodSync(target, 493);
+      return { ok: true, action: "installed" };
+    }
+    if (existsSync(local)) {
+      return {
+        ok: false,
+        reason: `${target} and ${local} both exist and aren't receipts hooks \u2014 resolve manually`
+      };
+    }
+    renameSync(target, local);
+    writeFileSync(target, HOOK_SCRIPT);
+    chmodSync(target, 493);
+    return { ok: true, action: "chained" };
+  }
+  writeFileSync(target, HOOK_SCRIPT);
+  chmodSync(target, 493);
+  return { ok: true, action: "installed" };
+}
+var PREPARE_CMD = "npx -y altimate-receipts@latest install-hook";
+function wirePrepareScript(pkgPath) {
+  if (!existsSync(pkgPath)) {
+    return { ok: false, reason: `${pkgPath} not found \u2014 \`--prepare\` needs a package.json` };
+  }
+  const raw = readFileSync(pkgPath, "utf8");
+  let pkg;
+  try {
+    pkg = JSON.parse(raw);
+  } catch {
+    return { ok: false, reason: `${pkgPath} is not valid JSON \u2014 leaving it untouched` };
+  }
+  if (pkg.scripts === void 0) {
+    pkg.scripts = {};
+  }
+  const scripts = pkg.scripts;
+  const prepare = scripts.prepare;
+  if (prepare?.includes(PREPARE_CMD)) {
+    return { ok: true, changed: false };
+  }
+  scripts.prepare = prepare ? `${prepare} && ${PREPARE_CMD}` : PREPARE_CMD;
+  const indent = raw.match(/^(\s+)"/m)?.[1] ?? "  ";
+  writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}
+`);
+  return { ok: true, changed: true };
+}
+
+// src/hook/prePush.ts
+import { spawnSync as spawnSync2 } from "child_process";
+import { existsSync as existsSync2 } from "fs";
+import { join as join2 } from "path";
+var REPUSH_EXIT = 42;
+var ATTACH_SUBJECT = (branch) => `chore(receipts): attach agent receipt for ${branch}`;
+function git(args, cwd) {
+  const r = spawnSync2("git", args, { encoding: "utf8", cwd });
+  return r.status === 0 ? r.stdout.trim() : "";
+}
+var WRAPPERS = /* @__PURE__ */ new Set(["command", "exec", "nohup", "time", "env"]);
+var GIT_VALUE_FLAGS = /* @__PURE__ */ new Set(["-C", "-c", "--git-dir", "--work-tree", "--exec-path"]);
+var TAG_REFSPEC = /^(refs\/tags\/|v\d+(\.\d+)*$)/;
+function isGitPush(command) {
+  const blanked = command.replace(/\\["']/g, "  ").replace(/'[^']*'/g, " ").replace(/"[^"]*"/g, " ");
+  for (const simple of blanked.split(/(?:&&|\|\||[;|\n])/)) {
+    const tokens = simple.trim().split(/\s+/).filter(Boolean);
+    let i = 0;
+    while (i < tokens.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i]) || WRAPPERS.has(tokens[i]))) {
+      i++;
+    }
+    if (tokens[i] !== "git") {
+      continue;
+    }
+    i++;
+    while (i < tokens.length && tokens[i].startsWith("-")) {
+      const flag = tokens[i];
+      i++;
+      if (GIT_VALUE_FLAGS.has(flag)) {
+        i++;
+      }
+    }
+    if (tokens[i] !== "push") {
+      continue;
+    }
+    const rest = tokens.slice(i + 1);
+    if (rest.includes("--dry-run") || rest.includes("-n") || rest.includes("--tags")) {
+      continue;
+    }
+    const positionals = rest.filter((t) => !t.startsWith("-"));
+    const refspecs = positionals.slice(1);
+    if (refspecs.length > 0 && refspecs.every((r) => TAG_REFSPEC.test(r))) {
+      continue;
+    }
+    return true;
+  }
+  return false;
+}
+function gitStdinPushesBranch(stdin) {
+  return stdin.split("\n").some((line) => line.trim().startsWith("refs/heads/"));
+}
+function repoOptedIn(repoRoot) {
+  return existsSync2(join2(repoRoot, ".github", "workflows", "receipts.yml")) || existsSync2(join2(repoRoot, ".receipts"));
+}
+function headIsAttachCommit(branch, cwd) {
+  return git(["log", "-1", "--format=%s"], cwd) === ATTACH_SUBJECT(branch);
+}
+async function readStdin(stream = process.stdin) {
+  let data = "";
+  for await (const chunk of stream) {
+    data += chunk;
+  }
+  return data;
+}
+async function runHookPrePush(dialect, stdin, generate) {
+  try {
+    if (process.env.RECEIPTS_HOOK === "0") {
+      return { exit: 0 };
+    }
+    if ((process.env.RECEIPTS_STORE || "commit").toLowerCase() === "none") {
+      return { exit: 0 };
+    }
+    if (dialect === "claude") {
+      let payload;
+      try {
+        payload = JSON.parse(stdin);
+      } catch {
+        return { exit: 0 };
+      }
+      if (payload.tool_name !== "Bash" || !payload.tool_input?.command) {
+        return { exit: 0 };
+      }
+      if (payload.cwd && existsSync2(payload.cwd)) {
+        process.chdir(payload.cwd);
+      }
+      if (!isGitPush(payload.tool_input.command)) {
+        return { exit: 0 };
+      }
+    } else if (!gitStdinPushesBranch(stdin)) {
+      return { exit: 0 };
+    }
+    const repoRoot = git(["rev-parse", "--show-toplevel"]);
+    if (!repoRoot || !repoOptedIn(repoRoot)) {
+      return { exit: 0 };
+    }
+    const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]);
+    if (!branch || branch === "HEAD") {
+      return { exit: 0 };
+    }
+    if (dialect === "git" && headIsAttachCommit(branch)) {
+      return { exit: 0 };
+    }
+    const write = process.stderr.write.bind(process.stderr);
+    process.stderr.write = (() => true);
+    let generated;
+    try {
+      generated = await generate();
+    } finally {
+      process.stderr.write = write;
+    }
+    if (generated !== 0) {
+      return { exit: 0 };
+    }
+    if (!git(["status", "--porcelain", ".receipts/"])) {
+      return { exit: 0 };
+    }
+    spawnSync2("git", ["add", ".receipts/"], { encoding: "utf8" });
+    const commit = spawnSync2(
+      "git",
+      ["commit", "--no-verify", "-m", ATTACH_SUBJECT(branch), "--", ".receipts/"],
+      { encoding: "utf8" }
+    );
+    if (commit.status !== 0) {
+      return { exit: 0 };
+    }
+    if (dialect === "git") {
+      return {
+        exit: REPUSH_EXIT,
+        message: `\u{1F4CE} Receipts: attached an agent receipt for '${branch}' \u2014 run \`git push\` again to include it.`
+      };
+    }
+    return {
+      exit: 0,
+      message: `receipts: attached an agent receipt for '${branch}' \u2014 it rides this push.`
+    };
+  } catch {
+    return { exit: 0 };
+  }
+}
+
+// src/hook/settingsMerge.ts
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname } from "path";
+var HOOK_COMMAND = "npx -y altimate-receipts@latest hook pre-push";
+function mergeHookIntoSettings(path) {
+  let settings = {};
+  if (existsSync3(path)) {
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync2(path, "utf8"));
+    } catch {
+      return { ok: false, reason: `${path} is not valid JSON \u2014 leaving it untouched` };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return { ok: false, reason: `${path} is not a JSON object \u2014 leaving it untouched` };
+    }
+    settings = parsed;
+  }
+  if (settings.hooks === void 0) {
+    settings.hooks = {};
+  }
+  const hooks = settings.hooks;
+  if (typeof hooks !== "object" || hooks === null || Array.isArray(hooks)) {
+    return { ok: false, reason: `${path} has a non-object "hooks" key \u2014 leaving it untouched` };
+  }
+  if (hooks.PreToolUse === void 0) {
+    hooks.PreToolUse = [];
+  }
+  const pre = hooks.PreToolUse;
+  if (!Array.isArray(pre)) {
+    return { ok: false, reason: `${path} has a non-array hooks.PreToolUse \u2014 leaving it untouched` };
+  }
+  const present = pre.some((e) => e?.hooks?.some((h) => h?.command === HOOK_COMMAND));
+  if (present) {
+    return { ok: true, changed: false };
+  }
+  pre.push({ matcher: "Bash", hooks: [{ type: "command", command: HOOK_COMMAND }] });
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync2(path, `${JSON.stringify(settings, null, 2)}
+`);
+  return { ok: true, changed: true };
+}
+
 // src/receipt/assert.ts
-import { readFileSync } from "fs";
-import { join } from "path";
+import { readFileSync as readFileSync3 } from "fs";
+import { join as join3 } from "path";
 var OPS = /* @__PURE__ */ new Set([
   "eq",
   "ne",
@@ -147,10 +424,10 @@ function validateAssertion(raw) {
   };
 }
 function loadAsserts(repoRoot) {
-  const path = join(repoRoot, ".receipts", "asserts.json");
+  const path = join3(repoRoot, ".receipts", "asserts.json");
   let text;
   try {
-    text = readFileSync(path, "utf8");
+    text = readFileSync3(path, "utf8");
   } catch {
     return [];
   }
@@ -374,8 +651,8 @@ function renderFieldScan(s) {
 }
 
 // src/report/log.ts
-import { readFileSync as readFileSync2, readdirSync } from "fs";
-import { join as join2 } from "path";
+import { readFileSync as readFileSync4, readdirSync } from "fs";
+import { join as join4 } from "path";
 var SEV_ICON2 = { critical: "\u26D4", high: "\u26A0\uFE0F", medium: "\u{1F50D}", low: "\xB7" };
 var SEV_RANK = { critical: 0, high: 1, medium: 2, low: 3 };
 var NON_RECEIPT = /(?:^|\/)(?:asserts(?:\.example)?|sample)\.json$/i;
@@ -399,7 +676,7 @@ function loadReceiptHistory(dir) {
   for (const f of files) {
     let input;
     try {
-      input = JSON.parse(readFileSync2(join2(dir, f), "utf8"));
+      input = JSON.parse(readFileSync4(join4(dir, f), "utf8"));
     } catch {
       continue;
     }
@@ -457,6 +734,26 @@ ${lines.join("\n")}
 `;
 }
 
+// src/report/prune.ts
+var PROTECTED = /(?:^|\/)(?:asserts(?:\.example)?|sample)\.json$/i;
+function branchSlug(branch) {
+  return branch.replace(/[/\\]/g, "-");
+}
+function planPrune(files, liveSlugs) {
+  const keep = [];
+  const remove = [];
+  for (const f of files) {
+    const base = f.split("/").pop() ?? f;
+    const slug = base.replace(/\.json$/i, "");
+    if (PROTECTED.test(base) || liveSlugs.has(slug)) {
+      keep.push(f);
+    } else {
+      remove.push(f);
+    }
+  }
+  return { keep, remove };
+}
+
 // src/report/sarif.ts
 var INFO_URI = "https://github.com/AltimateAI/altimate-receipts";
 function levelOf(severity) {
@@ -542,8 +839,8 @@ function toSarif(receipt) {
 }
 
 // src/report/stats.ts
-import { readFileSync as readFileSync3, readdirSync as readdirSync2 } from "fs";
-import { join as join3 } from "path";
+import { readFileSync as readFileSync5, readdirSync as readdirSync2 } from "fs";
+import { join as join5 } from "path";
 var NON_RECEIPT2 = /(?:^|\/)(?:asserts(?:\.example)?|sample)\.json$/i;
 function computeStats(dir) {
   let files;
@@ -561,7 +858,7 @@ function computeStats(dir) {
   for (const f of files) {
     let input;
     try {
-      input = JSON.parse(readFileSync3(join3(dir, f), "utf8"));
+      input = JSON.parse(readFileSync5(join5(dir, f), "utf8"));
     } catch {
       skipped++;
       continue;
@@ -704,7 +1001,14 @@ Usage
   receipts eval                 Flag-rate of the detectors over your real local sessions (--last N, --json)
   receipts badge [receipt]      shields.io endpoint JSON for a README/PR badge (--out f)
   receipts sarif [receipt]      SARIF 2.1.0 for GitHub code-scanning (inline + Security tab; --out f)
-  receipts init                 Scaffold the PR-check workflow into this repo (1-command adopt)
+  receipts prune [dir]          Remove committed receipts for merged/deleted branches (--dry-run)
+  receipts init                 One-command adopt: PR-check workflow + the repo-committed
+                                agent hook (--prepare also wires the git-hook floor)
+  receipts hook pre-push        (called by hooks, not humans) attach the receipt on push
+                                (--agent claude | git selects the payload dialect)
+  receipts install-hook         Write the self-updating pre-push hook into .git/hooks
+  receipts setup-local          Add the hook to YOUR ~/.claude/settings.json (only fires
+                                in repos that have adopted the Receipts workflow)
   receipts rederive <file>      Reproduce the canonical Receipt from a transcript
   receipts assert [selector]    Check the receipt against committed .receipts/asserts.json (CI gate)
   receipts mcp                  Start the MCP server (stdio) for IDEs/agents
@@ -756,9 +1060,13 @@ var COMMANDS = /* @__PURE__ */ new Set([
   "stats",
   "eval",
   "badge",
+  "prune",
   "sarif",
   "init",
-  "assert"
+  "assert",
+  "hook",
+  "install-hook",
+  "setup-local"
 ]);
 function parseArgs(argv) {
   const args = argv.slice(2);
@@ -772,7 +1080,9 @@ function parseArgs(argv) {
     handoff: false,
     redact: false,
     copy: false,
+    dryRun: false,
     wholeSession: false,
+    prepare: false,
     color: !process.env.NO_COLOR && process.stdout.isTTY === true
   };
   const positionals = [];
@@ -811,13 +1121,20 @@ function parseArgs(argv) {
       if (Number.isFinite(n) && n > 0) {
         parsed.last = Math.floor(n);
       }
+    } else if (a === "--dry-run") {
+      parsed.dryRun = true;
     } else if (a === "--whole-session") {
       parsed.wholeSession = true;
+    } else if (a === "--prepare") {
+      parsed.prepare = true;
     } else if (a === "--agent") {
       const next = args[i + 1];
       if (next && agentIds().includes(next)) {
         parsed.agent = next;
         i++;
+      } else if (next === "claude" || next === "git") {
+        parsed.hookDialect = next;
+        i++;
       }
     } else if (a === "--no-color") {
       parsed.color = false;
@@ -872,8 +1189,20 @@ async function run(argv) {
   if (args.command === "sarif") {
     return runSarif(args.file, { out: args.out });
   }
+  if (args.command === "prune") {
+    return runPrune(args.file, { dryRun: args.dryRun });
+  }
   if (args.command === "init") {
-    return runInit();
+    return runInit({ prepare: args.prepare });
+  }
+  if (args.command === "hook") {
+    return runHook(args.file, args.hookDialect ?? "claude");
+  }
+  if (args.command === "install-hook") {
+    return runInstallHook();
+  }
+  if (args.command === "setup-local") {
+    return runSetupLocal();
   }
   if (args.command === "rederive") {
     return runRederive(args.file, {
@@ -960,7 +1289,7 @@ Run a coding-agent session first, then try again.
     }
     const out = args.compact ? canonicalize(receipt) : JSON.stringify(receipt, null, 2);
     if (args.out) {
-      writeFileSync(args.out, `${out}
+      writeFileSync3(args.out, `${out}
 `);
       process.stderr.write(`Receipt written to ${args.out}
 `);
@@ -983,8 +1312,8 @@ Run a coding-agent session first, then try again.
   process.stdout.write(renderCard({ summary, derived, findings }, { color: args.color }));
   return 0;
 }
-function git(args) {
-  const r = spawnSync("git", args, { encoding: "utf8" });
+function git2(args) {
+  const r = spawnSync3("git", args, { encoding: "utf8" });
   return r.status === 0 ? r.stdout.trim() : "";
 }
 var PR_SELECT_SCAN = 150;
@@ -1021,8 +1350,8 @@ async function pickForDiff(all, branch, repoRoot, files) {
   return best ?? primary;
 }
 async function runPr(opts) {
-  const branch = opts.branch || git(["rev-parse", "--abbrev-ref", "HEAD"]);
-  const repoRoot = git(["rev-parse", "--show-toplevel"]);
+  const branch = opts.branch || git2(["rev-parse", "--abbrev-ref", "HEAD"]);
+  const repoRoot = git2(["rev-parse", "--show-toplevel"]);
   if (!branch || branch === "HEAD") {
     process.stderr.write("receipts pr: not on a git branch (use --branch <name>).\n");
     return 1;
@@ -1087,11 +1416,11 @@ Build the branch with a coding agent first, or run \`receipts --list\`.
 `);
   }
   const safe = branch.replace(/[/\\]/g, "-");
-  const dir = join4(repoRoot || ".", ".receipts");
-  const out = opts.out ?? join4(dir, `${safe}.json`);
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(out, json);
-  git(["add", out]);
+  const dir = join6(repoRoot || ".", ".receipts");
+  const out = opts.out ?? join6(dir, `${safe}.json`);
+  mkdirSync2(dir, { recursive: true });
+  writeFileSync3(out, json);
+  git2(["add", out]);
   const rel = repoRoot ? relative(repoRoot, out) : out;
   process.stderr.write(
     `receipts pr: wrote ${rel} (Grade ${receipt.predicate.grade}, ${scopeNote}) from "${summary.title ?? "untitled"}".
@@ -1118,8 +1447,8 @@ async function runGuardrails(opts) {
   const rules = collectGuardrails(findingSets);
   const block = renderGuardrailsBlock(rules, opts.json ? "json" : "md");
   if (opts.out) {
-    const existing = existsSync(opts.out) ? readFileSync4(opts.out, "utf8") : "";
-    writeFileSync(opts.out, upsertGuardrailsSection(existing, block));
+    const existing = existsSync4(opts.out) ? readFileSync6(opts.out, "utf8") : "";
+    writeFileSync3(opts.out, upsertGuardrailsSection(existing, block));
     process.stderr.write(
       `guardrails: wrote ${rules.length} rule(s) to ${opts.out} (from ${findingSets.length} session${findingSets.length === 1 ? "" : "s"}).
 `
@@ -1151,8 +1480,8 @@ async function runTrends(opts) {
   const trends = computeTrends(inputs, requested);
   if (opts.out) {
     const block = renderTrends(trends, "md");
-    const existing = existsSync(opts.out) ? readFileSync4(opts.out, "utf8") : "";
-    writeFileSync(opts.out, upsertTrendsSection(existing, block));
+    const existing = existsSync4(opts.out) ? readFileSync6(opts.out, "utf8") : "";
+    writeFileSync3(opts.out, upsertTrendsSection(existing, block));
     process.stderr.write(
       `trends: wrote section to ${opts.out} (from ${trends.window.used} sessions).
 `
@@ -1178,7 +1507,7 @@ function runEnvelope(file) {
     return 1;
   }
   try {
-    const receipt = JSON.parse(readFileSync4(file, "utf8"));
+    const receipt = JSON.parse(readFileSync6(file, "utf8"));
     process.stdout.write(`${JSON.stringify(toDsseEnvelope(receipt), null, 2)}
 `);
     return 0;
@@ -1195,7 +1524,7 @@ async function runVerify(file, opts = {}) {
   }
   let input;
   try {
-    input = JSON.parse(readFileSync4(file, "utf8"));
+    input = JSON.parse(readFileSync6(file, "utf8"));
   } catch (err) {
     process.stderr.write(`Could not read ${file}: ${err instanceof Error ? err.message : err}
 `);
@@ -1249,8 +1578,8 @@ function runDiff(fileA, fileB, opts = {}) {
       );
       return 1;
     }
-    pathA = join4(".receipts", `${hist[1].name}.json`);
-    pathB = join4(".receipts", `${hist[0].name}.json`);
+    pathA = join6(".receipts", `${hist[1].name}.json`);
+    pathB = join6(".receipts", `${hist[0].name}.json`);
     process.stdout.write(`receipts diff: ${hist[1].name} \u2192 ${hist[0].name} (most recent two)
 
 `);
@@ -1264,7 +1593,7 @@ function runDiff(fileA, fileB, opts = {}) {
   const read = (f) => {
     let input;
     try {
-      input = JSON.parse(readFileSync4(f, "utf8"));
+      input = JSON.parse(readFileSync6(f, "utf8"));
     } catch (err) {
       process.stderr.write(`Could not read ${f}: ${err instanceof Error ? err.message : err}
 `);
@@ -1287,7 +1616,7 @@ function runDiff(fileA, fileB, opts = {}) {
   const output = opts.json ? `${JSON.stringify(delta, null, 2)}
 ` : renderDiff(delta);
   if (opts.out) {
-    writeFileSync(opts.out, output);
+    writeFileSync3(opts.out, output);
     process.stdout.write(`receipts diff: wrote ${opts.out}
 `);
   } else {
@@ -1301,7 +1630,7 @@ function runLog(dir, opts = {}) {
   const output = opts.json ? `${JSON.stringify(shown, null, 2)}
 ` : renderLog(shown, all.length);
   if (opts.out) {
-    writeFileSync(opts.out, output);
+    writeFileSync3(opts.out, output);
     process.stdout.write(`receipts log: wrote ${opts.out}
 `);
   } else {
@@ -1314,7 +1643,7 @@ function runStats(dir, opts = {}) {
   const output = opts.json ? `${JSON.stringify(stats, null, 2)}
 ` : renderStats(stats);
   if (opts.out) {
-    writeFileSync(opts.out, output);
+    writeFileSync3(opts.out, output);
     process.stdout.write(`receipts stats: wrote ${opts.out}
 `);
   } else {
@@ -1323,10 +1652,10 @@ function runStats(dir, opts = {}) {
   return 0;
 }
 function runBadge(file, opts = {}) {
-  const repoRoot = git(["rev-parse", "--show-toplevel"]) || ".";
-  const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]);
-  const path = file ?? (branch && branch !== "HEAD" ? join4(repoRoot, ".receipts", `${branch.replace(/[/\\]/g, "-")}.json`) : void 0);
-  if (!path || !existsSync(path)) {
+  const repoRoot = git2(["rev-parse", "--show-toplevel"]) || ".";
+  const branch = git2(["rev-parse", "--abbrev-ref", "HEAD"]);
+  const path = file ?? (branch && branch !== "HEAD" ? join6(repoRoot, ".receipts", `${branch.replace(/[/\\]/g, "-")}.json`) : void 0);
+  if (!path || !existsSync4(path)) {
     process.stderr.write(
       `receipts badge: no receipt found${path ? ` at ${path}` : ""}. Run \`receipts pr\` first, or pass a receipt path.
 `
@@ -1335,7 +1664,7 @@ function runBadge(file, opts = {}) {
   }
   let input;
   try {
-    input = JSON.parse(readFileSync4(path, "utf8"));
+    input = JSON.parse(readFileSync6(path, "utf8"));
   } catch {
     process.stderr.write(`receipts badge: could not parse ${path}
 `);
@@ -1350,7 +1679,7 @@ function runBadge(file, opts = {}) {
   const output = `${JSON.stringify(badgeEndpoint(res.receipt.predicate), null, 2)}
 `;
   if (opts.out) {
-    writeFileSync(opts.out, output);
+    writeFileSync3(opts.out, output);
     process.stdout.write(`receipts badge: wrote ${opts.out}
 `);
   } else {
@@ -1359,10 +1688,10 @@ function runBadge(file, opts = {}) {
   return 0;
 }
 function runSarif(file, opts = {}) {
-  const repoRoot = git(["rev-parse", "--show-toplevel"]) || ".";
-  const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]);
-  const path = file ?? (branch && branch !== "HEAD" ? join4(repoRoot, ".receipts", `${branch.replace(/[/\\]/g, "-")}.json`) : void 0);
-  if (!path || !existsSync(path)) {
+  const repoRoot = git2(["rev-parse", "--show-toplevel"]) || ".";
+  const branch = git2(["rev-parse", "--abbrev-ref", "HEAD"]);
+  const path = file ?? (branch && branch !== "HEAD" ? join6(repoRoot, ".receipts", `${branch.replace(/[/\\]/g, "-")}.json`) : void 0);
+  if (!path || !existsSync4(path)) {
     process.stderr.write(
       `receipts sarif: no receipt found${path ? ` at ${path}` : ""}. Run \`receipts pr\` first, or pass a receipt path.
 `
@@ -1371,7 +1700,7 @@ function runSarif(file, opts = {}) {
   }
   let input;
   try {
-    input = JSON.parse(readFileSync4(path, "utf8"));
+    input = JSON.parse(readFileSync6(path, "utf8"));
   } catch {
     process.stderr.write(`receipts sarif: could not parse ${path}
 `);
@@ -1386,7 +1715,7 @@ function runSarif(file, opts = {}) {
   const output = `${JSON.stringify(toSarif(res.receipt), null, 2)}
 `;
   if (opts.out) {
-    writeFileSync(opts.out, output);
+    writeFileSync3(opts.out, output);
     process.stdout.write(`receipts sarif: wrote ${opts.out}
 `);
   } else {
@@ -1394,6 +1723,59 @@ function runSarif(file, opts = {}) {
   }
   return 0;
 }
+function runPrune(dir, opts = {}) {
+  const repoRoot = git2(["rev-parse", "--show-toplevel"]) || ".";
+  const dpath = dir ?? join6(repoRoot, ".receipts");
+  let files;
+  try {
+    files = readdirSync3(dpath).filter((f) => f.endsWith(".json"));
+  } catch {
+    process.stderr.write(`receipts prune: no ${dpath} directory.
+`);
+    return 0;
+  }
+  const ls = git2(["ls-remote", "--heads", "origin"]);
+  if (ls === null) {
+    process.stderr.write(
+      "receipts prune: could not list remote branches (offline / no 'origin'?) \u2014 aborting, nothing removed.\n"
+    );
+    return 1;
+  }
+  const liveSlugs = new Set(
+    ls.split("\n").map((l) => l.split("refs/heads/")[1]).filter(Boolean).map((b) => branchSlug(b.trim()))
+  );
+  const { keep, remove } = planPrune(files, liveSlugs);
+  if (remove.length === 0) {
+    process.stdout.write(`receipts prune: nothing to prune (${keep.length} receipt(s) kept).
+`);
+    return 0;
+  }
+  if (opts.dryRun) {
+    process.stdout.write(
+      `receipts prune (dry-run): would remove ${remove.length}/${files.length} receipt(s), keep ${keep.length}:
+`
+    );
+    for (const f of remove) {
+      process.stdout.write(`  - ${f}
+`);
+    }
+    return 0;
+  }
+  for (const f of remove) {
+    const p = join6(dpath, f);
+    if (git2(["rm", "-f", "--", p]) === null) {
+      try {
+        unlinkSync(p);
+      } catch {
+      }
+    }
+  }
+  process.stdout.write(
+    `receipts prune: removed ${remove.length} receipt(s) for merged/deleted branches; kept ${keep.length}.
+`
+  );
+  return 0;
+}
 async function runEval(opts = {}) {
   const limit = opts.limit && opts.limit > 0 ? opts.limit : 200;
   const summaries = (await listSessions(opts.agent)).slice(0, limit);
@@ -1414,17 +1796,53 @@ async function runEval(opts = {}) {
 ` : renderFieldScan(scan));
   return 0;
 }
-function runInit() {
+function runInit(opts = {}) {
+  const lines = [];
   const v = getVersion();
-  const tag = /^\d+\.\d+\.\d+$/.test(v) ? `v${v}` : "v0.2.2";
+  const major = /^(\d+)\.\d+\.\d+/.exec(v)?.[1];
+  const tag = major ? `v${major}` : "v0";
   const dir = ".github/workflows";
   const path = `${dir}/receipts.yml`;
-  if (existsSync(path)) {
-    process.stdout.write(`receipts init: ${path} already exists \u2014 leaving it untouched.
-`);
-    return 0;
+  if (existsSync4(path)) {
+    lines.push(`receipts init: ${path} already exists \u2014 leaving it untouched.`);
+  } else {
+    mkdirSync2(dir, { recursive: true });
+    writeFileSync3(path, workflowContent(tag, v));
+    lines.push(`receipts init: wrote ${path} (tracking ${tag}, quiet + non-blocking).`);
+  }
+  const settingsPath = join6(".claude", "settings.json");
+  const merged = mergeHookIntoSettings(settingsPath);
+  if (!merged.ok) {
+    lines.push(`receipts init: ${merged.reason}.`);
+  } else if (merged.changed) {
+    lines.push(`receipts init: added the receipts pre-push hook to ${settingsPath}.`);
+  } else {
+    lines.push(`receipts init: ${settingsPath} already has the receipts hook.`);
+  }
+  const ignorePath = join6(".claude", ".gitignore");
+  if (!existsSync4(ignorePath)) {
+    writeFileSync3(ignorePath, "*\n!settings.json\n!.gitignore\n");
+    lines.push(`receipts init: wrote ${ignorePath} (commit settings.json, ignore the rest).`);
+  }
+  if (opts.prepare) {
+    const wired = wirePrepareScript("package.json");
+    if (!wired.ok) {
+      lines.push(`receipts init: ${wired.reason}.`);
+    } else if (wired.changed) {
+      lines.push(
+        "receipts init: wired `prepare` in package.json \u2014 `npm install` now self-installs the git hook."
+      );
+    } else {
+      lines.push("receipts init: package.json `prepare` already wired.");
+    }
   }
-  const content = `name: Verified by Receipts
+  lines.push("  Commit these, open a PR, and receipts attach themselves from then on.");
+  process.stdout.write(`${lines.join("\n")}
+`);
+  return 0;
+}
+function workflowContent(tag, v) {
+  return `name: Verified by Receipts
 
 # Deterministic "what did the coding agent actually do?" check on PRs. Quiet + non-blocking
 # pilot: acts only when a branch commits an agent Receipt (.receipts/<branch>.json);
@@ -1443,21 +1861,56 @@ permissions:
 
 jobs:
   receipts:
+    # Tracks the ${tag} major tag (auto-gets minor/patch features). Pin a full version
+    # (e.g. @v${v}) or a commit SHA for immutability.
     uses: AltimateAI/altimate-receipts/.github/workflows/receipts.reusable.yml@${tag}
     with:
       require-receipt: false # never fail a PR that has no receipt (soft pilot)
       notify-when-missing: false # stay silent unless a receipt is present
       # block-on: ""          # informational check; never blocks a merge
 `;
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(path, content);
+}
+async function runHook(kind, dialect) {
+  if (kind !== "pre-push") {
+    process.stderr.write("Usage: receipts hook pre-push [--agent claude|git]\n");
+    return 1;
+  }
+  const stdin = await readStdin();
+  const res = await runHookPrePush(dialect, stdin, async () => runPr({}));
+  if (res.message) {
+    process.stderr.write(`${res.message}
+`);
+  }
+  return res.exit;
+}
+function runInstallHook() {
+  const res = installGitHook();
+  if (!res.ok) {
+    process.stderr.write(`receipts install-hook: ${res.reason}.
+`);
+    return 1;
+  }
+  const note = {
+    installed: "installed .git/hooks/pre-push",
+    unchanged: ".git/hooks/pre-push already installed",
+    chained: "installed .git/hooks/pre-push (existing hook preserved as pre-push.local, runs first)"
+  }[res.action];
+  process.stdout.write(`receipts install-hook: ${note}.
+`);
+  return 0;
+}
+function runSetupLocal() {
+  const path = join6(homedir(), ".claude", "settings.json");
+  const res = mergeHookIntoSettings(path);
+  if (!res.ok) {
+    process.stderr.write(`receipts setup-local: ${res.reason}.
+`);
+    return 1;
+  }
   process.stdout.write(
-    [
-      `receipts init: wrote ${path} (pinned to ${tag}, quiet + non-blocking).`,
-      "  Commit it, open a PR, and the Receipts check runs on every PR.",
-      "  Generate receipts locally with the pre-push hook \u2014 see docs/onboarding-internal.md.",
-      ""
-    ].join("\n")
+    res.changed ? `receipts setup-local: added the receipts hook to ${path} \u2014 active only in repos with the Receipts workflow.
+` : `receipts setup-local: ${path} already has the receipts hook.
+`
   );
   return 0;
 }
@@ -1478,7 +1931,7 @@ async function runRederive(file, opts = {}) {
   return 0;
 }
 async function runAssert(opts) {
-  const repoRoot = git(["rev-parse", "--show-toplevel"]) || ".";
+  const repoRoot = git2(["rev-parse", "--show-toplevel"]) || ".";
   let asserts;
   try {
     asserts = loadAsserts(repoRoot);