@avee1234/selfpatch 0.1.0

package/bin/selfpatch.js

@@ -0,0 +1,1377 @@
+#!/usr/bin/env node
+// selfpatch CLI. v0.1 ships `validate`, `propose`, `verify`, and `gate`; the
+// dispatcher is structured so `ledger` slots in later.
+//
+// Exit codes:
+//   validate: 0 — all files valid; 1 — a well-formed file failed validation;
+//             2 — usage error, file not found, or invalid JSON.
+//   propose:  0 — a valid self-patch was produced; 2 — usage/IO error or the
+//             inputs could not form a valid self-patch.
+//   verify:   0 — verified (candidate green, not regressed); 1 — a valid patch
+//             that did not verify (candidate red and/or regressed); 2 — usage/IO
+//             error, invalid-JSON/invalid patch, or an unexecutable check.
+//   gate:     0 — approve; 1 — human-gate (needs a human); 3 — block (policy
+//             denied); 2 — usage/IO error, invalid JSON, or an invalid patch or
+//             policy. (2 means "couldn't evaluate", consistent across subcommands.)
+//   apply:    0 — the patch was applied and recorded; 2 — usage/IO error,
+//             invalid patch, drift (before_after target ≠ diff.before), or a
+//             unified diff that would not apply cleanly. Fails closed: on a 2 the
+//             surface is left untouched and nothing is recorded.
+//   revert:   0 — the pre-patch surface was restored and recorded; 1 — nothing
+//             to revert (never applied, or already reverted); 2 — usage/IO
+//             error, a broken (tampered) chain, or an ambiguous id prefix.
+//   log:      0 — chain intact (including an empty history); 1 — chain broken
+//             (tamper detected); 2 — usage/IO error.
+//   guard-skill-edit: the worst outcome across all changed skills wins (fail
+//             closed). 0 — no changes, or every changed skill approved (and
+//             applied when --apply); 1 — at least one skill needs a human
+//             (effective human-gate, or an unsupported removal) and none blocked;
+//             3 — at least one skill blocked (protected surface, over blast
+//             radius, or failed/regressed its held-out check); 2 — usage/IO
+//             error, missing/unreadable dir, missing/invalid policy, a patch that
+//             fails the schema, or an unrunnable check.
+//
+// SECURITY: `verify` runs the patch's `eval_contract.command` as a real shell
+// command (`shell: true`). It executes arbitrary code the proposer authored —
+// only run it inside the propose→verify→gate pipeline, against a world you
+// control. `gate` runs no commands — it is a pure read of patch + policy.
+// `guard-skill-edit` runs the propose→verify→gate→(apply) pipeline over a skills
+// diff; the eval command it runs is the OPERATOR-supplied `--eval` (never
+// anything from the skills diff), so it introduces no new code-execution surface
+// beyond `verify`'s.
+
+import {
+  readFileSync,
+  writeFileSync,
+  appendFileSync,
+  mkdirSync,
+  existsSync,
+  rmSync,
+  mkdtempSync,
+  readdirSync,
+} from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, dirname, isAbsolute, resolve, relative } from "node:path";
+import { tmpdir } from "node:os";
+import process from "node:process";
+import {
+  validateSelfPatch,
+  validatePolicy,
+  proposeSelfPatch,
+  proposeSkillEdits,
+  skillTargetPath,
+  ProposeError,
+  verifySelfPatch,
+  gate,
+  blobRef,
+  buildAppliedEntry,
+  buildRevertedEntry,
+  verifyChain,
+  findRevertable,
+  LedgerError,
+} from "../src/index.js";
+
+const USAGE = `Usage:
+  selfpatch validate <file...> [--json] [--as patch|policy]
+  selfpatch propose --layer L --target T --rationale R --author A --eval CMD
+                    [--diff FILE | --before FILE --after FILE]
+                    [--meta FILE] [--requires auto|human-gate|forbidden]
+                    [--surface S]... [--created ISO] [--compact]
+  selfpatch verify <patch.json> [--cwd DIR] [--baseline DIR] [--timeout MS] [--json]
+  selfpatch gate <patch.json> --policy <policy.json> [--json]
+  selfpatch apply <patch.json> [--dir DIR] [--reason TEXT] [--json]
+  selfpatch revert <id> [--dir DIR] [--json]
+  selfpatch log [--dir DIR] [--id ID] [--json]
+  selfpatch guard-skill-edit <before-dir> <after-dir> --policy <policy.json>
+                    [--skills-root DIR] [--eval CMD] [--author A] [--rationale R]
+                    [--requires auto|human-gate|forbidden] [--dir DIR]
+                    [--cwd DIR] [--baseline DIR] [--timeout MS] [--apply] [--json]
+
+  validate    Validate self-patch or policy JSON files.
+              Auto-detects: a document with \`protected_surfaces\` is a policy,
+              otherwise a self-patch. Override with --as.
+    --json    Emit the raw { valid, errors } result (array for multiple files).
+    --as KIND Force validator: "patch" or "policy".
+
+  propose     Assemble a raw self-edit into a validated self-patch JSON with a
+              deterministic content-hash id, printed to stdout. Applies nothing.
+    --diff FILE       Unified diff patch text (use "-" for stdin). Omit all
+                      diff flags to read a unified diff from stdin.
+    --before/--after  Two versions of the surface (before_after diff).
+    --meta FILE       JSON object of metadata; individual flags override it.
+    --requires        Approval level (default: human-gate).
+    --surface S       Blast-radius surface (repeatable). Default: [target].
+    --created ISO     Override the timestamp (default: now).
+    --compact         Emit single-line JSON (for piping).
+
+  verify      Run a self-patch's held-out check (eval_contract) OUTSIDE the loop
+              and report whether the candidate is green and whether it regressed
+              a check that was green before. Applies nothing. The check command
+              runs in a real shell — only run against a world you control.
+    <patch.json>      The self-patch to verify ("-" for stdin). Validated first.
+    --cwd DIR         Candidate (after) world (default: current directory).
+    --baseline DIR    Baseline (before) world (default: same as --cwd, so a
+                      regression can only fire when a distinct baseline is set).
+    --timeout MS      Bound each command run; a timed-out check is red.
+    --json            Emit the raw { passed, regressed, checks } result.
+              Exit: 0 verified; 1 red/regressed; 2 usage/IO/invalid/unrunnable.
+
+  gate        Decide approve | human-gate | block for a self-patch under a
+              policy, with an explicit reason. Runs no commands — a pure read of
+              the patch + policy. Blocks a patch that touches a protected surface
+              or exceeds the policy's blast-radius limits; routes to a human when
+              the effective \`requires\` is human-gate; else approves.
+    <patch.json>      The self-patch to gate ("-" for stdin). Validated first.
+    --policy, -p FILE The policy JSON ("-" for stdin). Required. Validated first.
+    --json            Emit the raw { decision, reason } result.
+              Exit: 0 approve; 1 human-gate; 3 block; 2 usage/IO/invalid.
+
+  apply       Apply an approved self-patch to its target surface and append a
+              hash-linked \`applied\` entry to the ledger. Validates the patch
+              first (invalid ⇒ no mutation). Snapshots the real pre- and
+              post-images to a content-addressed object store, so \`revert\` is
+              exact and format-agnostic. Does NOT re-gate or re-verify.
+    <patch.json>      The self-patch to apply ("-" for stdin). Validated first.
+    --dir DIR         The ledger directory (default: .selfpatch).
+    --reason TEXT     A free-text note recorded on the entry (e.g. the gate
+                      decision that authorized the apply).
+    --json            Emit the new ledger entry as JSON.
+              Exit: 0 applied; 2 usage/IO/invalid/drift/unappliable.
+
+  revert      Restore the pre-patch surface of a patch's most recent, un-reverted
+              apply and append a hash-linked \`reverted\` entry. Restores a stored
+              snapshot (byte-exact for both diff formats), not a reverse-diff.
+              Verifies the chain first — refuses to act on a tampered ledger.
+    <id>              A self-patch id (sha256:…; a unique prefix is accepted).
+    --dir DIR         The ledger directory (default: .selfpatch).
+    --json            Emit the new ledger entry as JSON.
+              Exit: 0 reverted; 1 nothing to revert; 2 usage/IO/tampered/ambiguous.
+
+  log         Print the ledger history and verify the hash chain on read (reading
+              the history IS the integrity check). A missing ledger is an empty
+              history, not an error.
+    --dir DIR         The ledger directory (default: .selfpatch).
+    --id ID           Filter to one patch id's entries (its apply/revert history).
+    --json            Emit { entries, integrity: { valid, brokenAt } }.
+              Exit: 0 intact/empty; 1 chain broken; 2 usage/IO.
+
+  guard-skill-edit  Govern the factory's retro loop: diff two \`.agents/skills\`
+              trees into one scaffolding self-patch per changed skill, then run
+              propose → verify → gate over each and report a per-skill verdict.
+              With --apply, an approved patch is applied to its cwd target and
+              appended to the ledger. Protected skills (per the policy) are
+              blocked; a removed skill is surfaced for a human, never actuated.
+    <before-dir>      The committed (HEAD) skills tree.
+    <after-dir>       The proposed skills tree.
+    --policy, -p FILE The protected-surface policy JSON. Required. Validated first.
+    --skills-root DIR The logical repo path the targets carry (default:
+                      .agents/skills). A logical prefix, not a host path.
+    --eval CMD        The held-out check each patch runs (default: npm test).
+    --author A        Patch author (default: agent://foundry-retro).
+    --rationale R     Override the per-skill default rationale.
+    --requires        Baseline approval level (default: human-gate).
+    --dir DIR         The ledger directory for --apply (default: .selfpatch).
+    --cwd DIR         Candidate (after) world for the check (default: cwd).
+    --baseline DIR    Baseline (before) world for the check (default: --cwd).
+    --timeout MS      Bound each check run; a timed-out check is red.
+    --apply           Apply every approved patch to its cwd target + ledger.
+    --json            Emit the per-skill verdict array.
+              Exit: worst outcome wins — 0 all approved/no changes; 1 needs a
+              human; 3 blocked; 2 usage/IO/invalid/unrunnable.`;
+
+function fail(message) {
+  process.stderr.write(message + "\n");
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const files = [];
+  let json = false;
+  let as = null;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json") {
+      json = true;
+    } else if (arg === "--as") {
+      as = argv[++i];
+      if (as !== "patch" && as !== "policy") {
+        fail(`error: --as must be "patch" or "policy"\n\n${USAGE}`);
+      }
+    } else if (arg.startsWith("--as=")) {
+      as = arg.slice("--as=".length);
+      if (as !== "patch" && as !== "policy") {
+        fail(`error: --as must be "patch" or "policy"\n\n${USAGE}`);
+      }
+    } else if (arg.startsWith("-")) {
+      fail(`error: unknown flag ${arg}\n\n${USAGE}`);
+    } else {
+      files.push(arg);
+    }
+  }
+  return { files, json, as };
+}
+
+function pickValidator(doc, as) {
+  if (as === "patch") return validateSelfPatch;
+  if (as === "policy") return validatePolicy;
+  // Auto-detect: `protected_surfaces` present ⇒ policy, else patch.
+  if (doc && typeof doc === "object" && !Array.isArray(doc) && "protected_surfaces" in doc) {
+    return validatePolicy;
+  }
+  return validateSelfPatch;
+}
+
+// Read a file argument, or stdin when the path is "-".
+function readSource(path, label) {
+  try {
+    return readFileSync(path === "-" ? 0 : path, "utf8");
+  } catch (e) {
+    fail(`error: cannot read ${label} ${path}: ${e.code === "ENOENT" ? "no such file" : e.message}`);
+  }
+}
+
+const PROPOSE_FLAGS = new Set([
+  "--layer", "--target", "--rationale", "--author", "--eval",
+  "--requires", "--created", "--diff", "--before", "--after", "--meta",
+  "--surface", "--compact",
+]);
+
+// `--compact` takes no value; `--surface` may repeat, accumulating into an array.
+const PROPOSE_BOOL_FLAGS = new Set(["--compact"]);
+const PROPOSE_LIST_FLAGS = new Set(["--surface"]);
+
+// Metadata keys a `--meta` JSON file may supply; individual flags override them.
+const META_FILE_KEYS = [
+  "layer", "target", "rationale", "author", "eval", "requires", "created",
+];
+
+function parseProposeArgs(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    let key = arg;
+    let inlineValue = null;
+    const eq = arg.indexOf("=");
+    if (arg.startsWith("--") && eq !== -1) {
+      key = arg.slice(0, eq);
+      inlineValue = arg.slice(eq + 1);
+    }
+    if (!PROPOSE_FLAGS.has(key)) {
+      fail(`error: unknown flag ${arg}\n\n${USAGE}`);
+    }
+    if (PROPOSE_BOOL_FLAGS.has(key)) {
+      opts[key.slice(2)] = true;
+      continue;
+    }
+    const value = inlineValue !== null ? inlineValue : argv[++i];
+    if (value === undefined) {
+      fail(`error: ${key} needs a value\n\n${USAGE}`);
+    }
+    if (PROPOSE_LIST_FLAGS.has(key)) {
+      (opts[key.slice(2)] ??= []).push(value);
+    } else {
+      opts[key.slice(2)] = value;
+    }
+  }
+  return opts;
+}
+
+function runPropose(argv) {
+  const o = parseProposeArgs(argv);
+
+  // A `--meta` file supplies metadata defaults; individual flags override them.
+  if (o.meta !== undefined) {
+    const raw = readSource(o.meta, "meta");
+    let fileMeta;
+    try {
+      fileMeta = JSON.parse(raw);
+    } catch (e) {
+      fail(`error: --meta ${o.meta}: invalid JSON: ${e.message}`);
+    }
+    if (fileMeta === null || typeof fileMeta !== "object" || Array.isArray(fileMeta)) {
+      fail(`error: --meta ${o.meta}: expected a JSON object`);
+    }
+    for (const key of META_FILE_KEYS) {
+      if (o[key] === undefined && fileMeta[key] !== undefined) {
+        o[key] = fileMeta[key];
+      }
+    }
+    delete o.meta;
+  }
+
+  for (const req of ["layer", "target", "rationale", "author", "eval"]) {
+    if (typeof o[req] !== "string" || o[req].trim() === "") {
+      fail(`error: propose requires --${req}\n\n${USAGE}`);
+    }
+  }
+
+  const hasDiff = o.diff !== undefined;
+  const hasBeforeAfter = o.before !== undefined || o.after !== undefined;
+  if (hasDiff && hasBeforeAfter) {
+    fail(`error: propose takes either --diff or --before/--after, not both\n\n${USAGE}`);
+  }
+  if (hasBeforeAfter && (o.before === undefined || o.after === undefined)) {
+    fail(`error: before_after needs both --before and --after\n\n${USAGE}`);
+  }
+
+  // The `edit` is the diff itself: a plain unified-diff string, or a
+  // before_after object.
+  let edit;
+  if (hasDiff) {
+    edit = readSource(o.diff, "diff");
+  } else if (hasBeforeAfter) {
+    edit = {
+      format: "before_after",
+      before: readSource(o.before, "before"),
+      after: readSource(o.after, "after"),
+    };
+  } else {
+    // Neither diff flag given ⇒ read a unified diff from stdin.
+    edit = readSource("-", "diff");
+  }
+
+  const meta = {
+    author: o.author,
+    layer: o.layer,
+    target: o.target,
+    rationale: o.rationale,
+    command: o.eval,
+  };
+  if (o.surface !== undefined) meta.surfaces = o.surface;
+  if (o.requires !== undefined) meta.requires = o.requires;
+  if (o.created !== undefined) meta.created = o.created;
+
+  let patch;
+  try {
+    patch = proposeSelfPatch(edit, meta);
+  } catch (e) {
+    // A validation failure (ProposeError, carries `.errors`) prints the same
+    // error lines as `validate`. Per the propose contract, both a validation
+    // failure and a usage/IO problem exit 2 (propose defines only 0 and 2).
+    if (Array.isArray(e.errors)) {
+      process.stderr.write(e.message + "\n");
+      process.exit(2);
+    }
+    fail(`error: ${e.message}`);
+  }
+
+  const out = o.compact
+    ? JSON.stringify(patch)
+    : JSON.stringify(patch, null, 2);
+  process.stdout.write(out + "\n");
+  process.exit(0);
+}
+
+const VERIFY_FLAGS = new Set(["--cwd", "--baseline", "--timeout", "--json"]);
+const VERIFY_BOOL_FLAGS = new Set(["--json"]);
+
+function parseVerifyArgs(argv) {
+  const opts = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    let key = arg;
+    let inlineValue = null;
+    const eq = arg.indexOf("=");
+    if (eq !== -1) {
+      key = arg.slice(0, eq);
+      inlineValue = arg.slice(eq + 1);
+    }
+    if (!VERIFY_FLAGS.has(key)) {
+      fail(`error: unknown flag ${arg}\n\n${USAGE}`);
+    }
+    if (VERIFY_BOOL_FLAGS.has(key)) {
+      opts[key.slice(2)] = true;
+      continue;
+    }
+    const value = inlineValue !== null ? inlineValue : argv[++i];
+    if (value === undefined) {
+      fail(`error: ${key} needs a value\n\n${USAGE}`);
+    }
+    opts[key.slice(2)] = value;
+  }
+  return { opts, positionals };
+}
+
+// Build the side-effecting run-check seam shared by `verify` and
+// `guard-skill-edit`: run the check command in a real shell against the
+// candidate (`after`) world or the baseline (`before`) world. A spawn error
+// (non-timeout, e.g. cwd missing) maps to exitCode:null (red) so a bad command
+// reports a failed check, not a crash.
+function makeRunCheck({ cwdDir, baselineDir, timeout }) {
+  return (command, phase) => {
+    const r = spawnSync(command, {
+      shell: true,
+      cwd: phase === "before" ? baselineDir : cwdDir,
+      encoding: "utf8",
+      timeout,
+    });
+    const timedOut = r.error != null && r.error.code === "ETIMEDOUT";
+    return {
+      exitCode: r.status,
+      signal: r.signal,
+      timedOut,
+      stdout: r.stdout,
+      stderr: r.stderr,
+    };
+  };
+}
+
+function runVerify(argv) {
+  const { opts, positionals } = parseVerifyArgs(argv);
+  if (positionals.length === 0) {
+    fail(`error: verify needs a patch file\n\n${USAGE}`);
+  }
+  if (positionals.length > 1) {
+    fail(`error: verify takes a single patch file\n\n${USAGE}`);
+  }
+
+  let timeout;
+  if (opts.timeout !== undefined) {
+    timeout = Number(opts.timeout);
+    if (!Number.isFinite(timeout) || timeout < 0) {
+      fail(`error: --timeout must be a non-negative number of milliseconds\n\n${USAGE}`);
+    }
+  }
+
+  const raw = readSource(positionals[0], "patch");
+  let patch;
+  try {
+    patch = JSON.parse(raw);
+  } catch (e) {
+    fail(`error: ${positionals[0]}: invalid JSON: ${e.message}`);
+  }
+
+  // Never run a check for an invalid patch — validate first, print the same
+  // error lines as `validate`, and exit 2.
+  const result = validateSelfPatch(patch);
+  if (!result.valid) {
+    process.stderr.write(`✗ ${positionals[0]} — ${result.errors.length} error(s)\n`);
+    for (const er of result.errors) {
+      const loc = er.path === "" ? "(root)" : er.path;
+      process.stderr.write(`  ${loc}: ${er.message} [${er.code}]\n`);
+    }
+    process.exit(2);
+  }
+
+  const cwdDir = opts.cwd !== undefined ? opts.cwd : process.cwd();
+  const baselineDir = opts.baseline !== undefined ? opts.baseline : cwdDir;
+
+  // The only side-effecting seam: run the check command in a real shell against
+  // the chosen world.
+  const runCheck = makeRunCheck({ cwdDir, baselineDir, timeout });
+
+  let verdict;
+  try {
+    verdict = verifySelfPatch(patch, { runCheck });
+  } catch (e) {
+    // An unverifiable patch (VerifyError — e.g. an eval_contract yielding no
+    // runnable command) fails closed at exit 2, never silently "passed".
+    fail(`error: ${e.message}`);
+  }
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(verdict, null, 2) + "\n");
+  } else {
+    const overall = verdict.passed && !verdict.regressed
+      ? "✓ verified"
+      : verdict.regressed
+        ? "✗ regressed"
+        : "✗ failed";
+    process.stdout.write(overall + "\n");
+    for (const c of verdict.checks) {
+      const b = c.before && c.before.exitCode !== undefined ? c.before.exitCode : "?";
+      const a = c.after && c.after.exitCode !== undefined ? c.after.exitCode : "?";
+      const mark = c.regressed ? "✗ regressed" : c.passed ? "✓" : "✗";
+      process.stdout.write(`  ${mark}  ${c.command}  (before: ${b}, after: ${a})\n`);
+    }
+  }
+
+  process.exit(verdict.passed && !verdict.regressed ? 0 : 1);
+}
+
+const GATE_FLAGS = new Set(["--policy", "--json"]);
+const GATE_BOOL_FLAGS = new Set(["--json"]);
+
+function parseGateArgs(argv) {
+  const opts = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    // `-p` is a documented short alias for `--policy`.
+    if (arg === "-p") {
+      const value = argv[++i];
+      if (value === undefined) fail(`error: -p needs a value\n\n${USAGE}`);
+      opts.policy = value;
+      continue;
+    }
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    let key = arg;
+    let inlineValue = null;
+    const eq = arg.indexOf("=");
+    if (eq !== -1) {
+      key = arg.slice(0, eq);
+      inlineValue = arg.slice(eq + 1);
+    }
+    if (!GATE_FLAGS.has(key)) {
+      fail(`error: unknown flag ${arg}\n\n${USAGE}`);
+    }
+    if (GATE_BOOL_FLAGS.has(key)) {
+      opts[key.slice(2)] = true;
+      continue;
+    }
+    const value = inlineValue !== null ? inlineValue : argv[++i];
+    if (value === undefined) {
+      fail(`error: ${key} needs a value\n\n${USAGE}`);
+    }
+    opts[key.slice(2)] = value;
+  }
+  return { opts, positionals };
+}
+
+// Read a JSON file (or stdin for "-"), parse it, and validate it with the given
+// validator. Any read/parse/validation failure exits 2 — "couldn't evaluate" —
+// so `gate` never decides on a malformed patch or policy (fail closed).
+function readValidatedJson(path, label, validator) {
+  const raw = readSource(path, label);
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (e) {
+    fail(`error: ${path}: invalid JSON: ${e.message}`);
+  }
+  const result = validator(doc);
+  if (!result.valid) {
+    process.stderr.write(`✗ ${label} ${path} — ${result.errors.length} error(s)\n`);
+    for (const er of result.errors) {
+      const loc = er.path === "" ? "(root)" : er.path;
+      process.stderr.write(`  ${loc}: ${er.message} [${er.code}]\n`);
+    }
+    process.exit(2);
+  }
+  return doc;
+}
+
+function runGate(argv) {
+  const { opts, positionals } = parseGateArgs(argv);
+  if (positionals.length === 0) {
+    fail(`error: gate needs a patch file\n\n${USAGE}`);
+  }
+  if (positionals.length > 1) {
+    fail(`error: gate takes a single patch file\n\n${USAGE}`);
+  }
+  if (opts.policy === undefined) {
+    fail(`error: gate requires --policy <policy.json>\n\n${USAGE}`);
+  }
+  if (positionals[0] === "-" && opts.policy === "-") {
+    fail(`error: only one of the patch or --policy may be read from stdin\n\n${USAGE}`);
+  }
+
+  const patch = readValidatedJson(positionals[0], "patch", validateSelfPatch);
+  const policy = readValidatedJson(opts.policy, "policy", validatePolicy);
+
+  let verdict;
+  try {
+    verdict = gate(patch, policy);
+  } catch (e) {
+    // A GateError (non-object input) fails closed at exit 2 — never a silent
+    // approve. Validation above makes this unreachable in practice.
+    fail(`error: ${e.message}`);
+  }
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(verdict, null, 2) + "\n");
+  } else {
+    const mark =
+      verdict.decision === "approve" ? "✓" : verdict.decision === "human-gate" ? "⚠" : "✗";
+    process.stdout.write(`${mark} ${verdict.decision} — ${verdict.reason}\n`);
+  }
+
+  const code = verdict.decision === "approve" ? 0 : verdict.decision === "human-gate" ? 1 : 3;
+  process.exit(code);
+}
+
+// --- ledger: apply / revert / log -------------------------------------------
+//
+// The pure chain/selection logic lives in src/ledger.js; everything below is the
+// CLI's injected I/O — the on-disk ledger (append-only JSONL), the
+// content-addressed object store, and the target surfaces.
+
+// Resolve the ledger's on-disk layout under `--dir` (default `.selfpatch`).
+function ledgerPaths(dir) {
+  const root = dir || ".selfpatch";
+  return {
+    root,
+    ledgerFile: join(root, "ledger.jsonl"),
+    objectsDir: join(root, "objects"),
+  };
+}
+
+// Parse `ledger.jsonl` into an entries array (missing file ⇒ []). A malformed
+// line is a corrupt ledger ⇒ exit 2 (never act on a ledger we cannot read).
+function readLedger(paths) {
+  let raw;
+  try {
+    raw = readFileSync(paths.ledgerFile, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return [];
+    fail(`error: cannot read ledger ${paths.ledgerFile}: ${e.message}`);
+  }
+  const entries = [];
+  const lines = raw.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === "") continue;
+    try {
+      entries.push(JSON.parse(lines[i]));
+    } catch (e) {
+      fail(`error: ${paths.ledgerFile}: malformed JSON on line ${i + 1}: ${e.message}`);
+    }
+  }
+  return entries;
+}
+
+// Append one entry line. Creates `--dir` on first write; never rewrites or
+// truncates the file — the ledger is append-only in practice.
+function appendEntry(paths, entry) {
+  mkdirSync(paths.root, { recursive: true });
+  appendFileSync(paths.ledgerFile, JSON.stringify(entry) + "\n");
+}
+
+// Object store, keyed by the hex after the `sha256:` prefix.
+function blobPath(paths, ref) {
+  return join(paths.objectsDir, ref.slice("sha256:".length));
+}
+
+// Write-once: identical snapshots dedupe, and an existing blob is never mutated.
+// `null` content ⇒ `null` ref (an absent surface).
+function writeBlob(paths, content) {
+  if (content === null || content === undefined) return null;
+  const ref = blobRef(content);
+  const p = blobPath(paths, ref);
+  if (!existsSync(p)) {
+    mkdirSync(paths.objectsDir, { recursive: true });
+    writeFileSync(p, content);
+  }
+  return ref;
+}
+
+function readBlob(paths, ref) {
+  try {
+    return readFileSync(blobPath(paths, ref), "utf8");
+  } catch (e) {
+    fail(`error: cannot read snapshot ${ref}: ${e.message}`);
+  }
+}
+
+// Resolve a patch target to an absolute path, refusing anything that escapes the
+// cwd (an absolute path or a `..` climb). A self-patch must not relocate the
+// ledger or write outside the tree — fail closed on a suspicious target.
+function resolveTarget(target) {
+  if (typeof target !== "string" || target.trim() === "") {
+    fail("error: patch.target must be a non-empty path");
+  }
+  if (isAbsolute(target)) {
+    fail(`error: refusing to write outside the tree: ${target} (absolute path)`);
+  }
+  const abs = resolve(process.cwd(), target);
+  const rel = relative(process.cwd(), abs);
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+    fail(`error: refusing to write outside the tree: ${target}`);
+  }
+  return abs;
+}
+
+// Read the current surface bytes, or `null` when the file is absent.
+function readSurface(abs) {
+  try {
+    return readFileSync(abs, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return null;
+    fail(`error: cannot read target ${abs}: ${e.message}`);
+  }
+}
+
+function writeSurface(abs, content) {
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, content);
+}
+
+function removeSurface(abs) {
+  rmSync(abs, { force: true });
+}
+
+// Derive the path a unified diff targets from its `+++ ` header, stripping the
+// one leading component that `git apply -p1` removes (the `a/`/`b/` prefix), so
+// we can seed a scratch tree at that exact path.
+function unifiedTargetPath(patchText) {
+  for (const line of patchText.split("\n")) {
+    if (!line.startsWith("+++ ")) continue;
+    let p = line.slice(4).trim();
+    const tab = p.indexOf("\t");
+    if (tab !== -1) p = p.slice(0, tab);
+    if (p === "/dev/null") continue;
+    const slash = p.indexOf("/");
+    return slash === -1 ? p : p.slice(slash + 1);
+  }
+  return null;
+}
+
+// The only new side-effecting seam: materialize a `unified` diff via the system
+// `git apply`. Seeds a throwaway tree with the pre-image at the diff's target
+// path, applies the patch, and reads the result back. Throws (⇒ caller exits 2,
+// surface untouched) if git is unavailable or the patch does not apply cleanly.
+function applyUnified(before, patchText) {
+  const targetPath = unifiedTargetPath(patchText);
+  if (targetPath === null) {
+    throw new Error("could not determine the target path from the unified diff");
+  }
+  const scratch = mkdtempSync(join(tmpdir(), "selfpatch-apply-"));
+  try {
+    const filePath = join(scratch, targetPath);
+    if (relative(scratch, filePath).startsWith("..")) {
+      throw new Error("unified diff target escapes the scratch tree");
+    }
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, before ?? "");
+    const patchFile = join(scratch, "__selfpatch.diff");
+    writeFileSync(patchFile, patchText);
+    const r = spawnSync("git", ["apply", "--unsafe-paths", "-p1", patchFile], {
+      cwd: scratch,
+      encoding: "utf8",
+    });
+    if (r.error) throw new Error(`git apply unavailable: ${r.error.message}`);
+    if (r.status !== 0) {
+      throw new Error(`git apply failed: ${(r.stderr || "").trim() || `exit ${r.status}`}`);
+    }
+    return readFileSync(filePath, "utf8");
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+// Shared flag parser for the ledger subcommands (`--k v` / `--k=v`, positionals).
+function parseLedgerArgs(argv, flags, boolFlags) {
+  const opts = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    let key = arg;
+    let inlineValue = null;
+    const eq = arg.indexOf("=");
+    if (eq !== -1) {
+      key = arg.slice(0, eq);
+      inlineValue = arg.slice(eq + 1);
+    }
+    if (!flags.has(key)) {
+      fail(`error: unknown flag ${arg}\n\n${USAGE}`);
+    }
+    if (boolFlags.has(key)) {
+      opts[key.slice(2)] = true;
+      continue;
+    }
+    const value = inlineValue !== null ? inlineValue : argv[++i];
+    if (value === undefined) {
+      fail(`error: ${key} needs a value\n\n${USAGE}`);
+    }
+    opts[key.slice(2)] = value;
+  }
+  return { opts, positionals };
+}
+
+// The short display hash: the 12 hex chars after the `sha256:` prefix.
+function shortHash(ref) {
+  if (typeof ref !== "string") return "-";
+  return ref.replace(/^sha256:/, "").slice(0, 12) || "-";
+}
+
+const APPLY_FLAGS = new Set(["--dir", "--reason", "--json"]);
+const REVERT_FLAGS = new Set(["--dir", "--json"]);
+const LOG_FLAGS = new Set(["--dir", "--id", "--json"]);
+const LEDGER_BOOL_FLAGS = new Set(["--json"]);
+
+// The apply actuator shared by `apply` and `guard-skill-edit --apply`. Given a
+// VALID self-patch, resolves its target in the cwd, derives the post-image
+// (before_after drift-guard / unified via `applyUnified`), snapshots the pre-
+// and post-images to the object store, writes the surface, and appends a
+// hash-linked `applied` entry to the ledger under `dir`. Returns the new entry.
+// Throws a plain `Error` on drift or an unappliable/unsupported diff (the caller
+// decides the exit code — `apply` exits 2, `guard-skill-edit` marks the patch
+// blocked); the injected IO helpers still exit 2 directly on read/write errors.
+function applyPatchToLedger(patch, { dir, reason } = {}) {
+  const paths = ledgerPaths(dir);
+  const absTarget = resolveTarget(patch.target);
+  const pre = readSurface(absTarget); // the real pre-image (null ⇒ absent)
+  const diff = patch.diff;
+
+  // Derive the post-image from the diff. Fail closed on drift or an unappliable
+  // unified diff — never write a surface we cannot faithfully record.
+  let post;
+  if (diff.format === "before_after") {
+    const current = pre === null ? "" : pre;
+    if (current !== diff.before) {
+      throw new Error(
+        `target ${patch.target} has drifted from diff.before; refusing to apply`
+      );
+    }
+    post = diff.after;
+  } else if (diff.format === "unified") {
+    try {
+      post = applyUnified(pre, diff.patch);
+    } catch (e) {
+      throw new Error(`cannot apply unified diff to ${patch.target}: ${e.message}`);
+    }
+  } else {
+    throw new Error(`unsupported diff.format ${JSON.stringify(diff.format)}`);
+  }
+
+  // Read the ledger BEFORE touching the surface — an unreadable/corrupt ledger
+  // must fail closed (exit 2) with the surface untouched and nothing recorded.
+  const entries = readLedger(paths);
+  const last = entries[entries.length - 1];
+
+  // Snapshot both images, then write the surface, then record — the object store
+  // holds the bytes; the entry references them by hash.
+  const preRef = writeBlob(paths, pre);
+  const postRef = writeBlob(paths, post);
+  writeSurface(absTarget, post);
+
+  const entry = buildAppliedEntry({
+    patch,
+    target: patch.target,
+    pre: preRef,
+    post: postRef,
+    ts: new Date().toISOString(),
+    seq: entries.length,
+    prev: last ? last.hash : null,
+    reason,
+  });
+  appendEntry(paths, entry);
+  return entry;
+}
+
+function runApply(argv) {
+  const { opts, positionals } = parseLedgerArgs(argv, APPLY_FLAGS, LEDGER_BOOL_FLAGS);
+  if (positionals.length === 0) {
+    fail(`error: apply needs a patch file\n\n${USAGE}`);
+  }
+  if (positionals.length > 1) {
+    fail(`error: apply takes a single patch file\n\n${USAGE}`);
+  }
+
+  const raw = readSource(positionals[0], "patch");
+  let patch;
+  try {
+    patch = JSON.parse(raw);
+  } catch (e) {
+    fail(`error: ${positionals[0]}: invalid JSON: ${e.message}`);
+  }
+
+  // Never mutate a surface for an invalid patch — validate first, print the same
+  // error lines as `validate`, and exit 2 (fail closed).
+  const result = validateSelfPatch(patch);
+  if (!result.valid) {
+    process.stderr.write(`✗ ${positionals[0]} — ${result.errors.length} error(s)\n`);
+    for (const er of result.errors) {
+      const loc = er.path === "" ? "(root)" : er.path;
+      process.stderr.write(`  ${loc}: ${er.message} [${er.code}]\n`);
+    }
+    process.exit(2);
+  }
+
+  let entry;
+  try {
+    entry = applyPatchToLedger(patch, { dir: opts.dir, reason: opts.reason });
+  } catch (e) {
+    // Drift (before_after target ≠ diff.before) or an unappliable/unsupported
+    // diff fails closed at exit 2 — the surface is left untouched, nothing
+    // recorded. IO problems already exit 2 via the injected helpers.
+    fail(`error: ${e.message}`);
+  }
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(entry, null, 2) + "\n");
+  } else {
+    process.stdout.write(
+      `applied ${shortHash(entry.hash)} — ${entry.patch_id} → ${entry.target}\n`
+    );
+  }
+  process.exit(0);
+}
+
+function runRevert(argv) {
+  const { opts, positionals } = parseLedgerArgs(argv, REVERT_FLAGS, LEDGER_BOOL_FLAGS);
+  if (positionals.length === 0) {
+    fail(`error: revert needs a patch id\n\n${USAGE}`);
+  }
+  if (positionals.length > 1) {
+    fail(`error: revert takes a single patch id\n\n${USAGE}`);
+  }
+  const id = positionals[0];
+
+  const paths = ledgerPaths(opts.dir);
+  const entries = readLedger(paths);
+
+  // Refuse to act on a tampered ledger — reading it IS the integrity check.
+  const integrity = verifyChain(entries);
+  if (!integrity.valid) {
+    fail(`error: ledger chain broken at seq ${integrity.brokenAt}; refusing to act on a tampered ledger`);
+  }
+
+  let found;
+  try {
+    found = findRevertable(entries, id);
+  } catch (e) {
+    if (e instanceof LedgerError) {
+      fail(`error: ${e.message}`);
+    }
+    throw e;
+  }
+  if (found.entry === null) {
+    const why =
+      found.reason === "already-reverted"
+        ? "its most recent apply is already reverted"
+        : "no applied entry for that id";
+    process.stdout.write(`nothing to revert — ${why}\n`);
+    process.exit(1);
+  }
+
+  const applied = found.entry;
+  const absTarget = resolveTarget(applied.target);
+
+  // Snapshot the current bytes (the post-apply state) as the reverted entry's
+  // `pre`, then restore the applied entry's pre-image.
+  const beforeRevert = readSurface(absTarget);
+  const preRef = writeBlob(paths, beforeRevert);
+
+  if (applied.pre === null) {
+    // The apply created this file — undo means delete it.
+    removeSurface(absTarget);
+  } else {
+    writeSurface(absTarget, readBlob(paths, applied.pre));
+  }
+  const postRef = applied.pre; // the restored content's ref (or null ⇒ deleted)
+
+  const last = entries[entries.length - 1];
+  const entry = buildRevertedEntry({
+    patchId: applied.patch_id,
+    target: applied.target,
+    reverts: applied.hash,
+    pre: preRef,
+    post: postRef,
+    ts: new Date().toISOString(),
+    seq: entries.length,
+    prev: last ? last.hash : null,
+  });
+  appendEntry(paths, entry);
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(entry, null, 2) + "\n");
+  } else {
+    process.stdout.write(
+      `reverted ${shortHash(entry.hash)} — ${entry.patch_id} → ${entry.target}\n`
+    );
+  }
+  process.exit(0);
+}
+
+function runLog(argv) {
+  const { opts, positionals } = parseLedgerArgs(argv, LOG_FLAGS, LEDGER_BOOL_FLAGS);
+  if (positionals.length > 0) {
+    fail(`error: log takes no positional arguments\n\n${USAGE}`);
+  }
+
+  const paths = ledgerPaths(opts.dir);
+  const entries = readLedger(paths);
+  // Verify the FULL chain (before any --id filtering, which would break indices).
+  const integrity = verifyChain(entries);
+
+  const shown =
+    opts.id !== undefined
+      ? entries.filter((e) => typeof e.patch_id === "string" && e.patch_id.startsWith(opts.id))
+      : entries;
+
+  if (opts.json) {
+    process.stdout.write(
+      JSON.stringify({ entries: shown, integrity }, null, 2) + "\n"
+    );
+  } else {
+    // Newest-first for a human skim (git log feel).
+    for (let i = shown.length - 1; i >= 0; i--) {
+      const e = shown[i];
+      const rev =
+        e.event === "reverted" && e.reverts ? `  ⟲ reverts ${shortHash(e.reverts)}` : "";
+      process.stdout.write(
+        `${e.seq}  ${e.event}  ${shortHash(e.hash)}  ${shortHash(e.patch_id)}  ${e.target}  ${e.ts}${rev}\n`
+      );
+    }
+    process.stdout.write(
+      integrity.valid
+        ? `✓ chain intact (${entries.length} entries)\n`
+        : `✗ chain broken at seq ${integrity.brokenAt}\n`
+    );
+  }
+  process.exit(integrity.valid ? 0 : 1);
+}
+
+// --- guard-skill-edit: the Foundry dogfood pipeline -------------------------
+//
+// Diff two `.agents/skills` trees into one scaffolding self-patch per changed
+// skill (the pure adapter), then run the shipped verify → gate → (optional) apply
+// over each and report a per-skill verdict. The eval command and policy are
+// operator-supplied — never anything from the skills diff.
+
+// Recursively walk `dir` into a `{ posixRelPath → content }` map (UTF-8). Uses
+// hand-rolled recursion (not readdirSync's `recursive` option) to stay Node ≥18
+// compatible, and POSIX-joins rel paths so `target`s are stable across OSes. A
+// missing/unreadable dir ⇒ exit 2 (fail closed).
+function readTree(dir) {
+  const out = {};
+  const walk = (abs, prefix) => {
+    let entries;
+    try {
+      entries = readdirSync(abs, { withFileTypes: true });
+    } catch (e) {
+      fail(
+        `error: cannot read directory ${abs}: ${e.code === "ENOENT" ? "no such directory" : e.message}`
+      );
+    }
+    for (const ent of entries) {
+      const childAbs = join(abs, ent.name);
+      const rel = prefix === "" ? ent.name : `${prefix}/${ent.name}`;
+      if (ent.isDirectory()) {
+        walk(childAbs, rel);
+      } else if (ent.isFile()) {
+        let content;
+        try {
+          content = readFileSync(childAbs, "utf8");
+        } catch (e) {
+          fail(`error: cannot read ${childAbs}: ${e.message}`);
+        }
+        out[rel] = content;
+      }
+      // Symlinks / other node types are skipped — the skills tree is regular files.
+    }
+  };
+  walk(dir, "");
+  return out;
+}
+
+const GUARD_FLAGS = new Set([
+  "--policy", "--skills-root", "--eval", "--author", "--rationale",
+  "--requires", "--dir", "--cwd", "--baseline", "--timeout", "--apply", "--json",
+]);
+const GUARD_BOOL_FLAGS = new Set(["--apply", "--json"]);
+
+function parseGuardArgs(argv) {
+  const opts = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    // `-p` is the documented short alias for `--policy` (as in `gate`).
+    if (arg === "-p") {
+      const value = argv[++i];
+      if (value === undefined) fail(`error: -p needs a value\n\n${USAGE}`);
+      opts.policy = value;
+      continue;
+    }
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    let key = arg;
+    let inlineValue = null;
+    const eq = arg.indexOf("=");
+    if (eq !== -1) {
+      key = arg.slice(0, eq);
+      inlineValue = arg.slice(eq + 1);
+    }
+    if (!GUARD_FLAGS.has(key)) {
+      fail(`error: unknown flag ${arg}\n\n${USAGE}`);
+    }
+    if (GUARD_BOOL_FLAGS.has(key)) {
+      opts[key.slice(2)] = true;
+      continue;
+    }
+    const value = inlineValue !== null ? inlineValue : argv[++i];
+    if (value === undefined) {
+      fail(`error: ${key} needs a value\n\n${USAGE}`);
+    }
+    opts[key.slice(2)] = value;
+  }
+  return { opts, positionals };
+}
+
+function runGuardSkillEdit(argv) {
+  const { opts, positionals } = parseGuardArgs(argv);
+  if (positionals.length < 2) {
+    fail(`error: guard-skill-edit needs <before-dir> <after-dir>\n\n${USAGE}`);
+  }
+  if (positionals.length > 2) {
+    fail(`error: guard-skill-edit takes exactly <before-dir> <after-dir>\n\n${USAGE}`);
+  }
+  if (opts.policy === undefined) {
+    fail(`error: guard-skill-edit requires --policy <policy.json>\n\n${USAGE}`);
+  }
+
+  let timeout;
+  if (opts.timeout !== undefined) {
+    timeout = Number(opts.timeout);
+    if (!Number.isFinite(timeout) || timeout < 0) {
+      fail(`error: --timeout must be a non-negative number of milliseconds\n\n${USAGE}`);
+    }
+  }
+
+  const before = readTree(positionals[0]);
+  const after = readTree(positionals[1]);
+  const policy = readValidatedJson(opts.policy, "policy", validatePolicy);
+
+  const skillsRoot = opts["skills-root"] !== undefined ? opts["skills-root"] : ".agents/skills";
+
+  // Build one scaffolding self-patch per changed skill. A patch that fails the #1
+  // schema surfaces as a ProposeError ⇒ exit 2 (fail closed).
+  let proposal;
+  try {
+    proposal = proposeSkillEdits(before, after, {
+      skillsRoot,
+      author: opts.author !== undefined ? opts.author : "agent://foundry-retro",
+      rationale: opts.rationale,
+      evalCommand: opts.eval !== undefined ? opts.eval : "npm test",
+      requires: opts.requires !== undefined ? opts.requires : "human-gate",
+    });
+  } catch (e) {
+    if (Array.isArray(e.errors)) {
+      process.stderr.write(e.message + "\n");
+      process.exit(2);
+    }
+    fail(`error: ${e.message}`);
+  }
+
+  const { patches, changes } = proposal;
+  if (patches.length === 0 && changes.removed.length === 0) {
+    process.stdout.write("no skill changes\n");
+    process.exit(0);
+  }
+
+  const cwdDir = opts.cwd !== undefined ? opts.cwd : process.cwd();
+  const baselineDir = opts.baseline !== undefined ? opts.baseline : cwdDir;
+  const runCheck = makeRunCheck({ cwdDir, baselineDir, timeout });
+
+  const rows = [];
+
+  for (const patch of patches) {
+    // Verify the held-out check outside the loop, then gate under the policy.
+    let verdict;
+    try {
+      verdict = verifySelfPatch(patch, { runCheck });
+    } catch (e) {
+      // An unrunnable check fails closed at exit 2 — never a silent pass.
+      fail(`error: ${e.message}`);
+    }
+    const gateVerdict = gate(patch, policy);
+
+    // Fail-closed precedence: a red/regressed check OR a gate block ⇒ blocked;
+    // an effective human-gate ⇒ needs-human; else approved.
+    let outcome;
+    let reason;
+    if (!verdict.passed || verdict.regressed) {
+      outcome = "blocked";
+      reason = verdict.regressed
+        ? "regressed its held-out check"
+        : "failed its held-out check";
+    } else if (gateVerdict.decision === "block") {
+      outcome = "blocked";
+      reason = gateVerdict.reason;
+    } else if (gateVerdict.decision === "human-gate") {
+      outcome = "needs-human";
+      reason = gateVerdict.reason;
+    } else {
+      outcome = "approved";
+      reason = gateVerdict.reason;
+    }
+
+    let applied = false;
+    if (opts.apply && outcome === "approved") {
+      try {
+        applyPatchToLedger(patch, {
+          dir: opts.dir,
+          reason: `guard-skill-edit: gate approved (${gateVerdict.reason})`,
+        });
+        applied = true;
+      } catch (e) {
+        // Drift/unappliable at apply time fails this patch closed (blocked); the
+        // live surface is untouched and nothing is recorded.
+        outcome = "blocked";
+        reason = `apply refused: ${e.message}`;
+      }
+    }
+
+    rows.push({
+      target: patch.target,
+      patch_id: patch.id,
+      verify: { passed: verdict.passed, regressed: verdict.regressed },
+      gate: { decision: gateVerdict.decision, reason: gateVerdict.reason },
+      outcome,
+      reason,
+      applied,
+    });
+  }
+
+  // A removed skill is surfaced for a human — never auto-actuated in v0.1 (a
+  // `before_after` patch with after:"" would blank the file, not delete it).
+  for (const rel of changes.removed) {
+    rows.push({
+      target: skillTargetPath(skillsRoot, rel),
+      patch_id: null,
+      verify: null,
+      gate: null,
+      outcome: "needs-human",
+      reason: "removal unsupported in v0.1 — needs a human",
+      applied: false,
+    });
+  }
+
+  if (opts.json) {
+    const out = rows.map((r) => ({
+      target: r.target,
+      patch_id: r.patch_id,
+      verify: r.verify,
+      gate: r.gate,
+      outcome: r.outcome,
+      applied: r.applied,
+    }));
+    process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+  } else {
+    for (const r of rows) {
+      const mark =
+        r.outcome === "approved" ? "✓" : r.outcome === "needs-human" ? "⚠" : "✗";
+      const v = r.verify
+        ? r.verify.regressed
+          ? "regressed"
+          : r.verify.passed
+            ? "pass"
+            : "fail"
+        : "—";
+      const d = r.gate ? r.gate.decision : "—";
+      const appliedNote = r.applied ? " [applied]" : "";
+      process.stdout.write(
+        `${mark} ${r.target} — verify:${v} gate:${d} → ${r.outcome} (${r.reason})${appliedNote}\n`
+      );
+    }
+  }
+
+  // Worst outcome wins (fail closed): any blocked ⇒ 3; else any needs-human ⇒ 1;
+  // else 0. (2 is reserved for the usage/IO/schema/unrunnable failures above.)
+  const anyBlocked = rows.some((r) => r.outcome === "blocked");
+  const anyHuman = rows.some((r) => r.outcome === "needs-human");
+  process.exit(anyBlocked ? 3 : anyHuman ? 1 : 0);
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const sub = argv[0];
+
+  if (!sub || sub === "--help" || sub === "-h") {
+    process.stdout.write(USAGE + "\n");
+    process.exit(sub ? 0 : 2);
+  }
+
+  if (sub === "propose") {
+    runPropose(argv.slice(1));
+    return;
+  }
+
+  if (sub === "verify") {
+    runVerify(argv.slice(1));
+    return;
+  }
+
+  if (sub === "gate") {
+    runGate(argv.slice(1));
+    return;
+  }
+
+  if (sub === "apply") {
+    runApply(argv.slice(1));
+    return;
+  }
+
+  if (sub === "revert") {
+    runRevert(argv.slice(1));
+    return;
+  }
+
+  if (sub === "log") {
+    runLog(argv.slice(1));
+    return;
+  }
+
+  if (sub === "guard-skill-edit") {
+    runGuardSkillEdit(argv.slice(1));
+    return;
+  }
+
+  if (sub !== "validate") {
+    fail(`error: unknown subcommand "${sub}"\n\n${USAGE}`);
+  }
+
+  const { files, json, as } = parseArgs(argv.slice(1));
+  if (files.length === 0) {
+    fail(`error: validate needs at least one file\n\n${USAGE}`);
+  }
+
+  const results = [];
+  let anyInvalid = false;
+
+  for (const file of files) {
+    let raw;
+    try {
+      raw = readFileSync(file, "utf8");
+    } catch (e) {
+      fail(`error: cannot read ${file}: ${e.code === "ENOENT" ? "no such file" : e.message}`);
+    }
+
+    let doc;
+    try {
+      doc = JSON.parse(raw);
+    } catch (e) {
+      fail(`error: ${file}: invalid JSON: ${e.message}`);
+    }
+
+    const validator = pickValidator(doc, as);
+    const result = validator(doc);
+    results.push(result);
+    if (!result.valid) anyInvalid = true;
+
+    if (!json) {
+      if (result.valid) {
+        process.stdout.write(`✓ ${file} valid\n`);
+      } else {
+        process.stdout.write(`✗ ${file} — ${result.errors.length} error(s)\n`);
+        for (const er of result.errors) {
+          const loc = er.path === "" ? "(root)" : er.path;
+          process.stdout.write(`  ${loc}: ${er.message} [${er.code}]\n`);
+        }
+      }
+    }
+  }
+
+  if (json) {
+    const out = results.length === 1 ? results[0] : results;
+    process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+  }
+
+  process.exit(anyInvalid ? 1 : 0);
+}
+
+main();