@rafinery/cli 0.11.0 → 0.13.0

package/lib/audit.mjs

@@ -0,0 +1,289 @@
+// rafa audit — the deterministic security engine (finding shape rafa.audit/v1).
+//
+// SELF-CONTAINED (owner, 2026-07-26: "rafa audit should already have what it
+// needs — it should just run"): dependency CVEs via the built-in pnpm-lock v9
+// parser + the free keyless OSV.dev API (merged with `pnpm audit --json` as a
+// secondary source), secrets via the built-in curated ruleset over TRACKED
+// files only (`.env*` never opened; fingerprints, never secret bytes). semgrep
+// is the ONE optional external (SAST, pinned config) — used if present,
+// honestly absent otherwise; gitleaks enhances the secrets tier the same way.
+// NO binaries are installed by this command, ever.
+//
+// Exit codes: 0 clean · 1 findings present · 2 engine error.
+
+import { execSync, execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  AUDIT_SCHEMA,
+  LOCKFILE_NAMES,
+  SECRET_PATTERNS,
+  analyzeLockfile,
+  buildOsvQueries,
+  buildReport,
+  dedupeFindings,
+  entropyOf,
+  fromGitleaks,
+  fromOsvBatch,
+  fromPnpmAudit,
+  fromRegexSecrets,
+  fromSemgrepSarif,
+  mapConcurrent,
+} from "./audit/core.mjs";
+
+const OSV_BATCH = "https://api.osv.dev/v1/querybatch";
+const OSV_VULN = "https://api.osv.dev/v1/vulns/";
+const SEMGREP_CONFIG = "p/security-audit"; // pinned — never `--config auto` (it phones home to pick rules)
+
+export const hasBinary = (name) => {
+  try {
+    execSync(`command -v ${name}`, { stdio: "ignore", shell: "/bin/sh" });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+async function osvFetch(url, body) {
+  const res = await fetch(url, {
+    method: body ? "POST" : "GET",
+    headers: body ? { "content-type": "application/json" } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) throw new Error(`OSV ${res.status} on ${url}`);
+  return res.json();
+}
+
+// Tier a — dependency CVEs. Built-in OSV primary over WHICHEVER lockfile the
+// repo has (pnpm · npm · yarn · bun — dynamic, never a pnpm hardcode);
+// `pnpm audit` secondary on pnpm repos.
+async function dependencyTier(root) {
+  const lockName = LOCKFILE_NAMES.find((n) => existsSync(join(root, n)));
+  if (!lockName) {
+    const reason = existsSync(join(root, "bun.lockb"))
+      ? "bun.lockb is binary — generate the text lockfile: `bun install --save-text-lockfile`"
+      : `no lockfile (${LOCKFILE_NAMES.join(" / ")}) — dependency scanning not covered; \`rafa doctor\` shows the command to generate one`;
+    return { tier: { ran: false, tool: null, reason }, findings: [] };
+  }
+
+  const { manager, packages, reachability } = analyzeLockfile(
+    lockName,
+    readFileSync(join(root, lockName), "utf8"),
+  );
+  if (packages.length === 0)
+    return { tier: { ran: false, tool: null, reason: `${lockName} parsed to zero packages` }, findings: [] };
+  const findings = [];
+  let osvOk = false;
+  let reason = null;
+
+  try {
+    const chunks = buildOsvQueries(packages);
+    const results = [];
+    for (const chunk of chunks) {
+      const res = await osvFetch(OSV_BATCH, { queries: chunk });
+      results.push(...(res.results ?? []));
+    }
+    const ids = [...new Set(results.flatMap((r) => (r?.vulns ?? []).map((v) => v.id)))];
+    const details = new Map();
+    await mapConcurrent(ids, 8, async (id) => {
+      try {
+        details.set(id, await osvFetch(OSV_VULN + id));
+      } catch {
+        /* a detail we cannot fetch yields a shallower finding, never a guessed one */
+      }
+    });
+    findings.push(...fromOsvBatch(results, packages, details, reachability));
+    osvOk = true;
+  } catch (e) {
+    reason = `OSV unreachable (${e.message})`;
+  }
+
+  // Secondary source — pnpm audit builds its tree from the lockfile and asks
+  // the registry; it exits non-zero WHEN VULNS EXIST, so parse stdout
+  // regardless of exit code. Run without --prod: dev deps ride with dev:true
+  // and the priority map downgrades them — never silent omission.
+  let pnpmOk = false;
+  if (manager === "pnpm" && hasBinary("pnpm")) {
+    try {
+      let stdout;
+      try {
+        stdout = execSync("pnpm audit --json", { cwd: root, maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] });
+      } catch (e) {
+        stdout = e.stdout; // non-zero exit = findings, not failure
+      }
+      const json = JSON.parse(String(stdout));
+      findings.push(...fromPnpmAudit(json, reachability));
+      pnpmOk = true;
+    } catch {
+      /* unparseable output = tool failure; OSV may still have run */
+    }
+  }
+
+  if (!osvOk && !pnpmOk)
+    return { tier: { ran: false, tool: null, reason: reason ?? "registry unreachable" }, findings: [] };
+  const base = osvOk && pnpmOk ? "osv-api+pnpm-audit" : osvOk ? "osv-api" : "pnpm-audit";
+  return { tier: { ran: true, tool: `${base} (${lockName})` }, findings: dedupeFindings(findings) };
+}
+
+const isEnvFile = (p) => /(^|\/)\.env(\.|$)/.test(p);
+const looksBinary = (buf) => buf.includes(0);
+
+// Tier b — secrets over tracked files only. The matched text NEVER leaves the
+// process: findings carry a sha256 fingerprint of (file:line:rule:match).
+function secretsTier(root) {
+  let files;
+  try {
+    files = execSync("git ls-files", { cwd: root, maxBuffer: 64 * 1024 * 1024 })
+      .toString()
+      .split("\n")
+      .filter(Boolean)
+      .filter((f) => !isEnvFile(f));
+  } catch {
+    return { tier: { ran: false, tool: null, reason: "not a git repository" }, findings: [] };
+  }
+
+  const rows = [];
+  for (const file of files) {
+    const abs = join(root, file);
+    let buf;
+    try {
+      if (statSync(abs).size > 1024 * 1024) continue; // generated/vendored blobs
+      buf = readFileSync(abs);
+    } catch {
+      continue;
+    }
+    if (looksBinary(buf)) continue;
+    const lines = buf.toString("utf8").split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      for (const p of SECRET_PATTERNS) {
+        const m = lines[i].match(p.re);
+        if (!m) continue;
+        if (p.entropy && entropyOf(m[1] ?? m[0]) < p.entropy) continue;
+        rows.push({
+          rule: p.rule,
+          title: p.title,
+          severity: p.severity,
+          file,
+          line: i + 1,
+          fingerprint: createHash("sha256").update(`${file}:${i + 1}:${p.rule}:${m[0]}`).digest("hex").slice(0, 16),
+        });
+      }
+    }
+  }
+  let findings = fromRegexSecrets(rows);
+  let tool = "regex-fallback";
+
+  // gitleaks enhancer — merged in when present, keyed off its own report file.
+  if (hasBinary("gitleaks")) {
+    const report = join(tmpdir(), `rafa-gitleaks-${process.pid}.json`);
+    try {
+      try {
+        execFileSync("gitleaks", ["detect", "--source", root, "--no-banner", "--report-format", "json", "--report-path", report], { stdio: "ignore" });
+      } catch {
+        /* gitleaks exits 1 when it finds leaks — the report still writes */
+      }
+      if (existsSync(report)) {
+        const rowsGl = JSON.parse(readFileSync(report, "utf8"));
+        findings = dedupeFindings([...findings, ...fromGitleaks(Array.isArray(rowsGl) ? rowsGl.filter((r) => !isEnvFile(r.File ?? "")) : [])]);
+        tool = "regex-fallback+gitleaks";
+      }
+    } catch {
+      /* enhancer failure never fails the built-in tier */
+    }
+  }
+  return { tier: { ran: true, tool }, findings };
+}
+
+// Tier c — SAST via semgrep, the one optional external.
+function sastTier(root) {
+  if (!hasBinary("semgrep"))
+    return { tier: { ran: false, tool: null, reason: "semgrep not installed (optional — `brew install semgrep`)" }, findings: [] };
+  try {
+    let stdout;
+    try {
+      stdout = execFileSync("semgrep", ["scan", "--config", SEMGREP_CONFIG, "--sarif", "--quiet"], { cwd: root, maxBuffer: 256 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] });
+    } catch (e) {
+      stdout = e.stdout; // semgrep exits non-zero on findings with some flags
+    }
+    const findings = fromSemgrepSarif(JSON.parse(String(stdout)));
+    return { tier: { ran: true, tool: "semgrep" }, findings };
+  } catch (e) {
+    return { tier: { ran: false, tool: "semgrep", reason: `semgrep failed (${e.message})` }, findings: [] };
+  }
+}
+
+const SEV_ICON = { critical: "✗", high: "✗", moderate: "~", low: "·", info: "·" };
+
+function renderHuman(report) {
+  const lines = [`rafa audit — ${report.summary.total} finding(s)`, ""];
+  for (const [t, s] of Object.entries(report.tiers)) {
+    lines.push(s.ran ? `  ✓ ${t} ran (${s.tool})` : `  ○ ${t} did not run — ${s.reason}`);
+  }
+  lines.push("", `  critical ${report.summary.critical} · high ${report.summary.high} · moderate ${report.summary.moderate} · low ${report.summary.low} · info ${report.summary.info}`, "");
+  for (const f of report.findings.slice(0, 20)) {
+    const where = f.package ? `${f.package.name}@${f.package.version}${f.chain?.direct ? "" : " (transitive)"}${f.dev ? " [dev]" : ""}` : f.location ? `${f.location.file}:${f.location.line ?? "?"}` : "";
+    lines.push(`  ${SEV_ICON[f.severity]} [${f.severity}] ${f.title}${where ? ` — ${where}` : ""}${f.fixedIn ? ` → fixed in ${f.fixedIn}` : ""}`);
+  }
+  if (report.findings.length > 20) lines.push(`  … ${report.findings.length - 20} more in security-audit.json`);
+  return lines.join("\n");
+}
+
+function renderRecord(report) {
+  const md = [
+    "---",
+    'type: "Security Audit"',
+    `title: Security audit — ${report.summary.total} finding(s)`,
+    `description: "critical ${report.summary.critical} · high ${report.summary.high} · moderate ${report.summary.moderate} · low ${report.summary.low}"`,
+    "---",
+    "",
+    "# Security audit",
+    "",
+    `Generated by \`rafa audit\` (${AUDIT_SCHEMA}). Machine record: \`security-audit.json\`.`,
+    "",
+    "| severity | tier | finding | subject | fixed in |",
+    "|---|---|---|---|---|",
+    ...report.findings.map((f) => {
+      const subject = f.package ? `${f.package.name}@${f.package.version}` : f.location ? `${f.location.file}:${f.location.line ?? "?"}` : "—";
+      return `| ${f.severity} | ${f.tier} | ${f.vulnId ?? f.ruleId ?? f.id} | ${subject} | ${f.fixedIn ?? "—"} |`;
+    }),
+    "",
+  ];
+  return md.join("\n");
+}
+
+export async function runAudit(args = []) {
+  const rootArg = args.find((a) => a.startsWith("--root="));
+  const root = rootArg ? rootArg.slice("--root=".length) : process.cwd();
+  const json = args.includes("--json");
+
+  try {
+    const [dep, sec, sast] = [await dependencyTier(root), secretsTier(root), sastTier(root)];
+    const report = buildReport({
+      at: new Date().toISOString(),
+      ref: null,
+      tiers: { dependency: dep.tier, secrets: sec.tier, sast: sast.tier },
+      findings: dedupeFindings([...dep.findings, ...sec.findings, ...sast.findings]),
+    });
+
+    // Dual record beside the ledger (the verify-citations convention) — only
+    // when a .rafa/ bundle exists; a bare repo still gets the stdout report.
+    const improveDir = join(root, ".rafa", "improve");
+    if (existsSync(join(root, ".rafa"))) {
+      mkdirSync(improveDir, { recursive: true });
+      writeFileSync(join(improveDir, "security-audit.json"), JSON.stringify(report, null, 2) + "\n");
+      writeFileSync(join(improveDir, "security-audit.md"), renderRecord(report));
+    }
+
+    console.log(json ? JSON.stringify(report, null, 2) : renderHuman(report));
+    return report.summary.total > 0 ? 1 : 0;
+  } catch (e) {
+    console.error(`✗ rafa audit: ${e.message}`);
+    return 2;
+  }
+}
+
+export default async function audit(args = []) {
+  process.exit(await runAudit(args));
+}

package/lib/blueprint.mjs

@@ -46,6 +46,7 @@ export const BLUEPRINT = {
     ".claude/skills/rafa-leverage",
     ".claude/skills/rafa-sage",
     ".claude/skills/rafa-okf",
+    ".claude/skills/rafa-security",
   ],
   lockstep: [".claude/rafa/contract.md"],
   // The M5 sensor hooks — deterministic protocol machinery (like the contract):

package/lib/brain-repo.mjs

@@ -77,7 +77,7 @@ export function ensureBrainRepo(cwd, { requireRemote = true } = {}) {
   // (not knowledge). MERGED line-by-line so clones ignored under an older CLI
   // still gain new exclusions.
   const ignore = join(rafaDir, ".gitignore");
-  const IGNORES = ["hydration.json", "*.theirs.md", "distill-incoming/", "distill-verdicts.json", "dirty.jsonl", "reflex.jsonl", "sensor-errors.jsonl", "benchmark.demo.json", "session-facts.json", "loop-events-tail.json"];
+  const IGNORES = ["hydration.json", "*.theirs.md", "distill-incoming/", "distill-verdicts.json", "dirty.jsonl", "reflex.jsonl", "sensor-errors.jsonl", "benchmark.demo.json", "session-facts.json", "loop-events-tail.json", "review.json"];
   const cur = existsSync(ignore) ? readFileSync(ignore, "utf8") : "";
   const have = new Set(cur.split("\n").map((l) => l.trim()).filter(Boolean));
   const missing = IGNORES.filter((l) => !have.has(l));

package/lib/checkpoint.mjs

@@ -124,6 +124,99 @@ export default async function checkpoint() {
     }
   }
 
+  // MANDATORY CAPTURE — converge reported improvement flips into REAL ledger
+  // files (owner 2026-07-26 r4: "if the brain did not capture what happened
+  // during the session, it's a failure"). A session that called
+  // report_improvement_status but never hydrated the row would leave the flip
+  // stranded as an overlay; this step closes that gap MECHANICALLY on every
+  // checkpoint (and the pre-push hook runs checkpoint, so every push too):
+  // hydrate the canonical row, flip the status line, and the file rides THIS
+  // branch's working set. Best-effort per row — an unreachable platform never
+  // blocks the checkpoint (the reconciler's merge-time overlay net is the
+  // final backstop).
+  try {
+    const res = await callTool(ROOT, "list_improvements", {});
+    const rows = res?.data?.improvements ?? res?.improvements ?? [];
+    const mismatched = rows.filter(
+      (r) => r?.reported?.status && r.reported.status !== r.status,
+    );
+    if (mismatched.length) {
+      const { materializeImprovement } = await import("./working-set.mjs");
+      for (const r of mismatched) {
+        try {
+          const rel = `improve/improvements/${r.id}.md`;
+          const abs = join(ROOT, ".rafa", rel);
+          if (!existsSync(abs)) {
+            const payload = await callTool(ROOT, "get_improvement", { id: r.id });
+            materializeImprovement(ROOT, payload, payload.envelope?.brainForSha ?? null);
+          }
+          const cur = readFileSync(abs, "utf8");
+          if (!new RegExp(`^status: ${r.reported.status}\\s*$`, "m").test(cur)) {
+            // The status flip is an EDIT vs the hydration base → working set.
+            writeFileSync(abs, cur.replace(/^status: .*$/m, `status: ${r.reported.status}`));
+            console.log(`✓ converged reported ${r.reported.status} → .rafa/${rel} (mandatory capture)`);
+          }
+        } catch (e) {
+          console.log(`⚠ could not converge reported flip for "${r.id}" — ${e instanceof Error ? e.message : e} (the merge-time overlay net will catch it)`);
+        }
+      }
+    }
+  } catch {
+    /* unprovisioned/offline — the merge-time overlay net stands */
+  }
+
+  // COMPULSORY HYDRATION of touched-code citers (owner 2026-07-26 r5: "if some
+  // file is touched, it should hydrate compulsorily so edits happen DURING
+  // development"). The dirty queue knows which code files this session edited;
+  // the local manifest knows which notes cite them. Every citing note not
+  // already local is hydrated NOW — present for the session to edit, so the
+  // affected-note update happens in development, not discovered at merge (the
+  // merge-time affected lane stays the backstop). Unedited hydrations remain
+  // disposable cache — presence, never noise.
+  try {
+    const { readDirty, resolveCiters } = await import("./dirty.mjs");
+    const { files: dirtyFiles } = readDirty(ROOT);
+    // SENSOR-INDEPENDENT (r5 follow-up): the dirty queue only sees agent-session
+    // edits (a Claude Code hook) — a dev committing manually never populates it.
+    // Union with git's own truth: every file this BRANCH changed vs the trunk.
+    // Checkpoint runs from the git pre-push hook, which fires on manual pushes
+    // too — so manual workflows hydrate their citers all the same.
+    const touched = new Set(dirtyFiles.map((f) => f.path ?? f[0] ?? f));
+    try {
+      const { trunkBranchOf } = await import("./stamp.mjs");
+      const trunk = trunkBranchOf(ROOT);
+      for (const f of execSync(`git diff --name-only ${trunk}...HEAD`, {
+        cwd: ROOT,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      })
+        .split("\n")
+        .filter(Boolean))
+        touched.add(f);
+    } catch {
+      /* no trunk ref locally (shallow clone) — the sensor queue alone serves */
+    }
+    const citers = touched.size ? resolveCiters(ROOT, [...touched]) : null;
+    if (citers?.length) {
+      const { materializeImprovement, materializeNote } = await import("./working-set.mjs");
+      for (const n of citers) {
+        try {
+          if (!n.path || existsSync(join(ROOT, ".rafa", n.path))) continue; // already local
+          const kind = n.path.includes("improvements/") ? "improvement" : n.path.includes("playbooks/") ? "playbook" : "rule";
+          const payload = await callTool(ROOT, kind === "improvement" ? "get_improvement" : kind === "playbook" ? "get_playbook" : "get_rule", { id: n.id });
+          const base = payload.envelope?.brainForSha ?? null;
+          if (kind === "improvement") materializeImprovement(ROOT, payload, base);
+          else materializeNote(ROOT, kind, payload, base);
+          console.log(`✓ hydrated ${kind} "${n.id}" — cites code this session touched (${n.files.join(", ")}); update it as part of the work`);
+        } catch (e) {
+          console.log(`⚠ could not hydrate citer "${n.id}" — ${e instanceof Error ? e.message : e} (merge-time affected lane will re-ground it)`);
+        }
+      }
+    }
+  } catch {
+    /* no dirty queue / no manifest / offline — the merge-time affected lane stands */
+  }
+
   // The commit this capture is grounded against (contract: capturedAtSha —
   // absent = unknown grounding). One HEAD per checkpoint push; the merge-time
   // ancestry sweep keys on it, so a missing sha only narrows that sweep,

package/lib/distiller/doctrine.mjs

@@ -275,7 +275,7 @@ export function mergeRangeSweep({ changedFiles, orgNotes, cwd = process.cwd() })
 
 // ── failure classification (case 3) ─────────────────────────────────────────────
 // Deterministic (config / gate rejection / schema): retrying only burns spend →
-// reconcile_report failure class "deterministic" → needs-attention immediately.
+// terminal-report failure class "deterministic" → needs-attention immediately.
 // Transient (network / boot / OOM / clone / timeout): backoff retry while a later
 // branch proceeds. An error may carry an explicit `errorClass`; else heuristics.
 const TRANSIENT_RE =
@@ -288,7 +288,7 @@ export function classifyError(err) {
 }
 
 // Tagged-error helpers so the loop can raise a failure of a known class and the
-// reconcile_report path carries it verbatim (never a re-guess at the boundary).
+// terminal-report path (reconciliations.recordResult) carries it verbatim (never a re-guess at the boundary).
 export function deterministicFailure(message) {
   const e = new Error(message);
   e.errorClass = "deterministic";
@@ -314,7 +314,7 @@ export function outcomeRow({ candidate, outcome, detail, reconciliationId, super
   };
 }
 
-// The reconcile_report `delta` shape (knowledgeGraph.deltaValidator): four buckets
+// The terminal report’s `delta` shape (knowledgeGraph.deltaValidator): four buckets
 // of { noteId, cites }. Built from the run's dispositions so the node the pointer
 // advance mints carries exactly what this run refined. `folded` losers do not
 // enter the delta (they were superseded, not banked) but ARE in the outcomes.
@@ -339,7 +339,7 @@ function toWireCites(cites = []) {
   }));
 }
 
-// Per-branch outcome rows for reconcile_report (perBranchOutcomeValidator:
+// Per-branch outcome rows for the terminal report (perBranchOutcomeValidator:
 // { branch, capturedAtSha, verdict }). One row per source branch, the verdict a
 // short mechanical summary of that branch's fate in the fold.
 export function perBranchOutcomes(branchSets, outcomeRows) {

package/lib/doctor.mjs

@@ -7,7 +7,7 @@
 // command exists to kill.
 
 import { execSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { callTool, resolveMcp } from "./mcp-client.mjs";
 import { collectSensorHealth } from "./sensor-health.mjs";
@@ -97,6 +97,59 @@ export async function runDoctor(ROOT = process.cwd()) {
     }
   }
 
+  // 3b · security tools — the audit engine's core (lockfile parsers + OSV +
+  // secrets ruleset) is BUILT IN and always on; gitleaks/semgrep are optional
+  // enhancers. Detection only — rafa never installs binaries.
+  {
+    const { hasBinary } = await import("./audit.mjs");
+    const { LOCKFILE_NAMES } = await import("./audit/core.mjs");
+    console.log("• security tools (rafa audit)");
+    ok("core engine built in (dep CVEs via OSV · secrets ruleset)");
+
+    // Lockfile coverage (owner r3): NO lockfile = the dependency tier cannot
+    // run — that is a real coverage hole, so it FAILS doctor with the exact
+    // command to close it (resolved per the repo's own package manager).
+    if (existsSync(join(ROOT, "package.json"))) {
+      const lock = LOCKFILE_NAMES.find((n) => existsSync(join(ROOT, n)));
+      if (lock) {
+        ok(`lockfile present (${lock}) — dependency scanning covered`);
+      } else if (existsSync(join(ROOT, "bun.lockb"))) {
+        bad(
+          "bun.lockb is binary — dependency scanning NOT covered",
+          "generate the text lockfile: `bun install --save-text-lockfile`",
+        );
+      } else {
+        const LOCK_HELP = {
+          pnpm: "pnpm install --lockfile-only",
+          npm: "npm install --package-lock-only",
+          yarn: "yarn install --mode update-lockfile",
+          bun: "bun install --save-text-lockfile",
+        };
+        let manager = null;
+        try {
+          const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
+          manager = String(pkg.packageManager ?? "").split("@")[0] || null;
+        } catch {
+          /* unreadable package.json — fall through to the full menu */
+        }
+        bad(
+          "no lockfile — dependency scanning NOT covered until one exists",
+          manager && LOCK_HELP[manager]
+            ? `generate it: \`${LOCK_HELP[manager]}\` (then commit the lockfile)`
+            : `generate one for your package manager, then commit it: pnpm \`${LOCK_HELP.pnpm}\` · npm \`${LOCK_HELP.npm}\` · yarn \`${LOCK_HELP.yarn}\` · bun \`${LOCK_HELP.bun}\``,
+        );
+      }
+    }
+
+    for (const [name, hint] of [
+      ["gitleaks", "brew install gitleaks"],
+      ["semgrep", "brew install semgrep"],
+    ]) {
+      if (hasBinary(name)) ok(`${name} present (optional enhancer)`);
+      else console.log(`  · ${name} not installed — optional enhancer (\`${hint}\`)`);
+    }
+  }
+
   // 4 · the round-trip — the heartbeat must LAND, not just send. A recorded
   // response proves key + url + repo scoping + the platform handler, end to end.
   console.log("• platform round-trip");

package/lib/gate/compile.mjs

@@ -268,22 +268,26 @@ export function runCompile(argv = []) {
           "leverage",
           "required · { impact, effort } ∈ low|medium|high",
         );
+      // `category` is canonical; `lens` is the pre-2026-07-26 name, accepted
+      // as a deprecated alias so already-authored ledgers keep compiling.
+      const category = reqEnum(
+        { category: data.category ?? data.lens },
+        "category",
+        [
+          "security",
+          "correctness",
+          "performance",
+          "architecture",
+          "product",
+          "ops",
+        ],
+        path,
+      );
       out.push({
         id,
         priority: reqEnum(data, "priority", ["P0", "P1", "P2", "P3"], path),
-        lens: reqEnum(
-          data,
-          "lens",
-          [
-            "security",
-            "correctness",
-            "performance",
-            "architecture",
-            "product",
-            "ops",
-          ],
-          path,
-        ),
+        category,
+        lens: category, // transitional dual-key — dropped with the backfill arc
         status: reqEnum(
           data,
           "status",

package/lib/guard.mjs

@@ -0,0 +1,107 @@
+// rafa guard — the capture-integrity gate (owner 2026-07-26 r5: whole-brain
+// capture is MANDATORY; "we need to guard post-commit and pre-push").
+//
+//   rafa guard --pre-push    verify every OUTGOING code commit has its 1-1
+//                            brain mirror commit; a missing mirror SELF-HEALS
+//                            (the brain-commit worker re-runs); still missing
+//                            → exit 1 and the push BLOCKS. Git-local — no
+//                            network — so a failure is genuine capture loss,
+//                            never flakiness.
+//
+// Exit: 0 capture intact (or nothing to guard) · 1 capture missing after
+// self-heal. Trunk pushes exit 0 (the brain trunk has one writer — the
+// reconciler; there is no mirror to demand).
+
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { trunkBranchOf, readStamp } from "./stamp.mjs";
+
+const sh = (cmd, cwd) =>
+  execSync(cmd, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+
+export function runGuard(args = []) {
+  const ROOT = process.cwd();
+  if (!args.includes("--pre-push")) {
+    console.log("usage: rafa guard --pre-push   (capture-integrity gate; hook-invoked)");
+    return 0;
+  }
+  const rafaDir = join(ROOT, ".rafa");
+  if (!existsSync(join(rafaDir, ".git"))) return 0; // no brain repo here — nothing to guard
+
+  let branch = "";
+  try {
+    branch = sh("git rev-parse --abbrev-ref HEAD", ROOT);
+  } catch {
+    return 0;
+  }
+  const trunk = trunkBranchOf(ROOT);
+  const configured = typeof readStamp(ROOT).prodBranch === "string";
+  if (branch === trunk || (!configured && (branch === "main" || branch === "master"))) return 0;
+
+  // Outgoing commits: upstream..HEAD when an upstream exists, else every local
+  // commit on this branch not on the trunk (first push of a new branch).
+  let outgoing = [];
+  try {
+    outgoing = sh("git rev-list @{u}..HEAD", ROOT).split("\n").filter(Boolean);
+  } catch {
+    try {
+      outgoing = sh(`git rev-list ${trunk}..HEAD`, ROOT).split("\n").filter(Boolean);
+    } catch {
+      outgoing = [];
+    }
+  }
+  if (outgoing.length === 0) return 0;
+
+  // The brain branch's mirror trailers — `code-commit: <sha>` — are the 1-1
+  // capture record (capture-engine P1). Missing sha = a commit whose brain
+  // state was never mirrored.
+  const mirrored = () => {
+    try {
+      return new Set(
+        sh(`git log --format=%B ${branch}`, rafaDir)
+          .split("\n")
+          .map((l) => l.match(/^code-commit:\s*([0-9a-f]{7,40})/)?.[1])
+          .filter(Boolean),
+      );
+    } catch {
+      return new Set(); // brain branch missing entirely — every commit is unmirrored
+    }
+  };
+
+  const missing = (set) => outgoing.filter((sha) => ![...set].some((m) => sha.startsWith(m) || m.startsWith(sha)));
+
+  let gone = missing(mirrored());
+  if (gone.length > 0) {
+    // SELF-HEAL: the brain-commit worker is idempotent and tail-aware — one
+    // re-run mirrors any stray session state onto the branch.
+    console.log(`rafa guard · ${gone.length} outgoing commit(s) missing a brain mirror — self-healing …`);
+    try {
+      execSync(`node ${JSON.stringify(join(ROOT, ".claude", "rafa", "hooks", "brain-commit.mjs"))}`, {
+        cwd: ROOT,
+        stdio: ["ignore", "ignore", "ignore"],
+      });
+    } catch {
+      /* verified below — the re-check is the truth, not this exit code */
+    }
+    gone = missing(mirrored());
+  }
+
+  if (gone.length > 0) {
+    console.error(
+      `✗ rafa guard: capture INCOMPLETE — ${gone.length} outgoing commit(s) have no brain mirror:\n` +
+        gone.map((s) => `    ${s.slice(0, 12)}`).join("\n") +
+        "\n  Whole-brain capture is mandatory (decision 2026-07-26 r5): a code commit whose brain" +
+        "\n  state was never mirrored is capture loss the reconciler cannot recover." +
+        "\n  Fix: `node .claude/rafa/hooks/brain-commit.mjs` (or re-commit), then push again." +
+        "\n  Escape hatch (capture loss accepted, on the record): RAFA_HOOKS_DISABLED=1 git push",
+    );
+    return 1;
+  }
+  console.log(`rafa guard · capture intact (${outgoing.length} outgoing commit(s), all mirrored)`);
+  return 0;
+}
+
+export default function guard(args = []) {
+  process.exit(runGuard(args));
+}

package/lib/init.mjs

@@ -183,8 +183,9 @@ export default async function init(args) {
     );
   }
 
-  // Reconciliation runs on the PLATFORM (App-only era, owner call 2026-07-18):
-  // merged PRs are detected and distilled by the platform's own sandbox — no
+  // Reconciliation runs on the PLATFORM (App-only era, owner call 2026-07-18;
+  // agent-native since 2026-07-21): merged PRs are detected and reconciled by
+  // the server-side LangGraph agent — no
   // CI workflow, no repo secrets, nothing to wire here. The org-CI adapter
   // stays available as an explicit opt-out for teams that want the compute in
   // their own CI: `rafa ci-setup`. Init no longer asks — one fewer question,