@rafinery/cli 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -4,6 +4,49 @@ The machine-readable version of this lives in [`lib/releases.mjs`](lib/releases.
 CLI reads it to tell a client, on `rafa update`, exactly what an upgrade requires (nothing,
 a re-scan, or a `rafa migrate`).
 
+## 0.13.0 — whole-brain mandatory capture (r4–r6)
+
+Owner doctrine, verbatim: *"if the brain did not capture what happened during
+the session and missed a few steps, it's a failure."* Capture no longer
+depends on anyone — model or dev — remembering an SOP line:
+
+- **`rafa guard --pre-push`** — the capture-integrity gate the pre-push hook
+  now runs first: every outgoing commit must carry its 1-1 brain mirror;
+  a miss self-heals, a genuine miss **blocks the push**
+  (`RAFA_HOOKS_DISABLED=1` is the deliberate escape hatch). Post-commit
+  mirror failures print the repair command instead of vanishing.
+- **`rafa checkpoint`** auto-converges reported improvement flips into real
+  ledger files, and **compulsorily hydrates** every note citing code the
+  branch touched (dirty queue ∪ `git diff trunk...HEAD` — manual edits
+  count), so affected-note edits happen *during* development.
+- Server-side backstops (platform): the reconciler unions
+  reported-but-unconverged flips at merge time, sweeps merge-affected notes
+  when the dev-side capture signal is untrusted, and the run page says
+  "already banked" / "re-verified" instead of the misleading "unchanged".
+- **Multi-manager lockfiles** in the audit core: pnpm · npm (v3+v1) ·
+  yarn (classic+berry) · bun (text lockfile), resolved dynamically —
+  never a pnpm hardcode. `rafa doctor` fails a `package.json` repo with no
+  lockfile and prints the exact per-manager generate command.
+
+## 0.12.0 — the security module
+
+Security as the fourth harnessed input, integral to the cycle
+(spec: `.arohi/2026-07-26-security-module-spec.md`):
+
+- **`rafa audit`** — self-contained (`rafa.audit/v1`): dependency CVEs via
+  the built-in lockfile parser + keyless OSV.dev (merged with `pnpm audit`),
+  secrets via the built-in ruleset (tracked files only, `.env*` never
+  opened, fingerprints never bytes), SAST via semgrep only if present —
+  a tier that didn't run says `ran:false`. Nothing bundled, nothing
+  installed, ever. Exit 0 clean · 1 findings · 2 error.
+- Improvement frontmatter **`lens` → `category`** (same enum); `lens` stays
+  accepted as a deprecated alias, so existing ledgers keep compiling.
+- New blueprint SOP **rafa-security** (woven at bloom's moments, never a dev
+  verb): mechanical priority map (critical→P0 … dev-only→P3), reachability
+  annotated from the brain, P0 security rows may surface outside the blast
+  radius. bloom 0.10.0 · atlas 4.1.0 (plan-time audit transparency) · the
+  scan's required security-posture playbook · doctor's security-tools block.
+
 ## 0.11.0 — schema-aware reconciliation (the 4-case ladder)
 
 Distillation is where knowledge from two lineages meets — so it is now also

package/bin/rafa.mjs

@@ -56,6 +56,7 @@ const COMMANDS = [
   "ci-setup",
   "leverage",
   "audit",
+  "guard",
   "benchmark",
   "manifest",
   "review",
@@ -143,6 +144,9 @@ Commands:
                        PR merge) and name the CI secrets to configure.
   leverage             Inspect your agent toolbox (permissions, skills, MCP) and print
                        prioritized tips for getting more out of it. Advisory — changes nothing.
+  guard --pre-push     Capture-integrity gate (hook-invoked): every outgoing commit must
+                       have its 1-1 brain mirror; missing → self-heal → still missing →
+                       the push BLOCKS (whole-brain capture is mandatory, 2026-07-26 r5).
   audit                Self-contained security engine (rafa.audit/v1): dependency CVEs via
                        the built-in lockfile parser + OSV.dev (pnpm audit merged in),
                        secrets via the built-in ruleset (tracked files only, .env* never

package/blueprint/.claude/rafa/hooks/post-commit

@@ -7,5 +7,12 @@
 # the dev never maintains the brain. Non-blocking and silent on every path.
 [ "$RAFA_HOOKS_DISABLED" = "1" ] && exit 0
 [ -f "rafa.json" ] || exit 0
-node ".claude/rafa/hooks/brain-commit.mjs" >/dev/null 2>&1 || true
+# r5 (whole-brain capture): a mirror failure is LOUD + recorded — the commit
+# already happened (post-commit can't block), but the pre-push guard will
+# refuse to ship an unmirrored commit, so the failure surfaces NOW, not never.
+node ".claude/rafa/hooks/brain-commit.mjs" >/dev/null 2>&1 || {
+  echo "rafa · BRAIN MIRROR FAILED for this commit — capture incomplete." >&2
+  echo "  Repair before pushing: node .claude/rafa/hooks/brain-commit.mjs  (the pre-push guard will block until mirrored)" >&2
+  mkdir -p .rafa 2>/dev/null && printf '{"t":%s000,"hook":"post-commit","error":"brain mirror failed"}\n' "$(date +%s)" >> .rafa/sensor-errors.jsonl 2>/dev/null || true
+}
 exit 0

package/blueprint/.claude/rafa/hooks/pre-push

@@ -12,6 +12,12 @@
 [ "$RAFA_HOOKS_DISABLED" = "1" ] && exit 0
 [ -f "rafa.json" ] || exit 0
 
+# WHOLE-BRAIN CAPTURE GUARD (owner 2026-07-26 r5, non-negotiable): every
+# outgoing commit must carry its 1-1 brain mirror. Git-local check with
+# self-heal; a genuine miss BLOCKS the push — capture loss never ships
+# silently. RAFA_HOOKS_DISABLED=1 is the on-the-record escape hatch.
+npx -y @rafinery/cli guard --pre-push || exit 1
+
 echo "rafa · checkpoint (pre-push boundary) …"
 npx -y @rafinery/cli checkpoint || {
   code=$?

package/lib/audit/core.mjs

@@ -17,6 +17,130 @@ export const SEVERITIES = ["critical", "high", "moderate", "low", "info"];
 const SEV_RANK = Object.fromEntries(SEVERITIES.map((s, i) => [s, i]));
 const TIER_ORDER = { dependency: 0, secret: 1, sast: 2 };
 
+// package-lock.json v2/v3 (`packages` map) with a v1 (`dependencies` tree)
+// fallback. npm's lockfile carries per-entry `dev` flags and the root's
+// direct-dep names, so reachability is PREFILLED from the file itself (no BFS
+// — npm's nested-resolution graph doesn't reduce to exact-version edges).
+export function parseNpmLock(text) {
+  const json = JSON.parse(text);
+  const packages = new Map();
+  const reachability = new Map();
+  const put = (name, version, { direct, dev }) => {
+    const id = `${name}@${version}`;
+    packages.set(id, { name, version });
+    const prev = reachability.get(id);
+    if (!prev || (prev.dev && !dev))
+      reachability.set(id, { direct, dev, path: direct ? [id] : [] });
+  };
+  if (json.packages && typeof json.packages === "object") {
+    const root = json.packages[""] ?? {};
+    const directNames = new Set([
+      ...Object.keys(root.dependencies ?? {}),
+      ...Object.keys(root.devDependencies ?? {}),
+      ...Object.keys(root.optionalDependencies ?? {}),
+    ]);
+    for (const [path, entry] of Object.entries(json.packages)) {
+      if (path === "" || !entry || typeof entry.version !== "string") continue;
+      if (entry.link === true) continue; // workspace links
+      const name = path.split("node_modules/").pop();
+      if (!name) continue;
+      put(name, entry.version, { direct: directNames.has(name), dev: entry.dev === true });
+    }
+  } else if (json.dependencies && typeof json.dependencies === "object") {
+    const walk = (deps, depth, devCtx) => {
+      for (const [name, e] of Object.entries(deps ?? {})) {
+        if (!e || typeof e !== "object") continue;
+        const dev = e.dev === true || devCtx;
+        if (typeof e.version === "string") put(name, e.version, { direct: depth === 0, dev });
+        if (e.dependencies) walk(e.dependencies, depth + 1, dev);
+      }
+    };
+    walk(json.dependencies, 0, false);
+  }
+  return { manager: "npm", version: String(json.lockfileVersion ?? ""), packages: [...packages.values()], reachability };
+}
+
+// yarn.lock — BOTH classic v1 (`"name@range":` + `version "x"`) and berry
+// (`"name@npm:range":` + `version: x`). Selector blocks → resolved versions.
+// No dependency graph is derivable without resolution → packages-only.
+export function parseYarnLock(text) {
+  const packages = new Map();
+  let names = null;
+  for (const raw of String(text ?? "").split("\n")) {
+    if (!raw.trim() || raw.trim().startsWith("#")) continue;
+    const indent = raw.length - raw.trimStart().length;
+    if (indent === 0 && raw.trim().endsWith(":")) {
+      names = raw
+        .trim()
+        .slice(0, -1)
+        .split(",")
+        .map((k) => {
+          const s = unquote(k.trim());
+          const at = s.lastIndexOf("@");
+          return at > 0 ? s.slice(0, at) : null; // scoped names keep their leading @
+        })
+        .filter(Boolean);
+    } else if (names && /^ {2}version:?\s/.test(raw)) {
+      const version = unquote(raw.trim().replace(/^version:?\s*/, ""));
+      if (version && !version.startsWith("0.0.0-use.local")) {
+        for (const name of new Set(names)) packages.set(`${name}@${version}`, { name, version });
+      }
+      names = null;
+    }
+  }
+  return { manager: "yarn", version: null, packages: [...packages.values()], reachability: null };
+}
+
+// bun.lock — bun's TEXT lockfile (JSONC: comments + trailing commas allowed);
+// `packages` entries resolve as ["name@version", …]. The binary bun.lockb is
+// NOT parsed — callers detect it and tell the dev to generate the text form
+// (`bun install --save-text-lockfile`). Packages-only.
+export function parseBunLock(text) {
+  const json = JSON.parse(
+    String(text ?? "")
+      .replace(/\/\/[^\n]*/g, "")
+      .replace(/,\s*([}\]])/g, "$1"),
+  );
+  const packages = new Map();
+  for (const val of Object.values(json.packages ?? {})) {
+    const spec = Array.isArray(val) ? val[0] : null;
+    if (typeof spec !== "string") continue;
+    const at = spec.lastIndexOf("@");
+    if (at <= 0) continue;
+    const name = spec.slice(0, at);
+    const version = spec.slice(at + 1);
+    if (!version || version.includes(":")) continue; // workspace:/git: refs are not registry versions
+    packages.set(`${name}@${version}`, { name, version });
+  }
+  return { manager: "bun", version: null, packages: [...packages.values()], reachability: null };
+}
+
+// The one entry point every caller uses: filename → uniform
+// { manager, packages, reachability } (reachability null when the format
+// cannot honestly provide direct/dev/chain).
+export function analyzeLockfile(filename, text) {
+  switch (filename) {
+    case "pnpm-lock.yaml": {
+      const parsed = parsePnpmLock(text);
+      return { manager: "pnpm", packages: parsed.packages, reachability: classifyReachability(parsed) };
+    }
+    case "package-lock.json": {
+      const parsed = parseNpmLock(text);
+      return { manager: "npm", packages: parsed.packages, reachability: parsed.reachability };
+    }
+    case "yarn.lock": {
+      const parsed = parseYarnLock(text);
+      return { manager: "yarn", packages: parsed.packages, reachability: null };
+    }
+    case "bun.lock": {
+      const parsed = parseBunLock(text);
+      return { manager: "bun", packages: parsed.packages, reachability: null };
+    }
+    default:
+      throw new Error(`unknown lockfile: ${filename}`);
+  }
+}
+
 // Bounded-concurrency map — shared control flow for the OSV detail fetches
 // (both callers cap at ~8). Pure orchestration; the fn does the I/O.
 export async function mapConcurrent(items, limit, fn) {
@@ -50,6 +174,19 @@ const normSeverity = (label) => {
   return null;
 };
 
+// ---------------------------------------------------------------------------
+// Lockfiles — the MULTI-MANAGER registry (owner 2026-07-26 r3: "we should
+// dynamically solve these problems, not hardcode pnpm"). Every parser returns
+// the same shape; `analyzeLockfile` is the one entry point the three callers
+// (CLI · reconcile lane · branch-merge action) use. Depth is honest per
+// manager: pnpm + npm lockfiles carry enough to classify direct/dev/chain;
+// yarn + bun yield packages-only (reachability: null — findings carry
+// chain:null/dev:null, never a guessed classification).
+// ---------------------------------------------------------------------------
+
+// Detection order: richest-information lockfile first.
+export const LOCKFILE_NAMES = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lock"];
+
 // ---------------------------------------------------------------------------
 // pnpm-lock.yaml v9 — a rigid machine-emitted YAML subset; a line scanner is
 // enough and keeps the CLI at one runtime dep (no @pnpm/lockfile-file, whose
@@ -291,7 +428,9 @@ export function fromOsvBatch(osvResults, packages, vulnDetails, reachability) {
       const vuln = vulnDetails?.get?.(hit.id) ?? hit;
       const cvss = cvssScoreOf(vuln);
       const label = normSeverity(vuln.database_specific?.severity);
-      const chain = chainFor(pkg, reachability);
+      // No reachability map (yarn/bun lockfiles) → chain/dev stay null —
+      // "unknown" is never rendered as "transitive".
+      const chain = reachability ? chainFor(pkg, reachability) : null;
       const entry = reachability?.get(`${pkg.name}@${pkg.version}`);
       out.push(
         finding({

package/lib/audit.mjs

@@ -18,10 +18,11 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   AUDIT_SCHEMA,
+  LOCKFILE_NAMES,
   SECRET_PATTERNS,
+  analyzeLockfile,
   buildOsvQueries,
   buildReport,
-  classifyReachability,
   dedupeFindings,
   entropyOf,
   fromGitleaks,
@@ -30,7 +31,6 @@ import {
   fromRegexSecrets,
   fromSemgrepSarif,
   mapConcurrent,
-  parsePnpmLock,
 } from "./audit/core.mjs";
 
 const OSV_BATCH = "https://api.osv.dev/v1/querybatch";
@@ -56,20 +56,30 @@ async function osvFetch(url, body) {
   return res.json();
 }
 
-// Tier a — dependency CVEs. Built-in OSV primary; `pnpm audit` secondary.
+// 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 lockPath = join(root, "pnpm-lock.yaml");
-  if (!existsSync(lockPath))
-    return { tier: { ran: false, tool: null, reason: "no pnpm-lock.yaml here" }, findings: [] };
+  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 parsed = parsePnpmLock(readFileSync(lockPath, "utf8"));
-  const reachability = classifyReachability(parsed);
+  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(parsed.packages);
+    const chunks = buildOsvQueries(packages);
     const results = [];
     for (const chunk of chunks) {
       const res = await osvFetch(OSV_BATCH, { queries: chunk });
@@ -84,7 +94,7 @@ async function dependencyTier(root) {
         /* a detail we cannot fetch yields a shallower finding, never a guessed one */
       }
     });
-    findings.push(...fromOsvBatch(results, parsed.packages, details, reachability));
+    findings.push(...fromOsvBatch(results, packages, details, reachability));
     osvOk = true;
   } catch (e) {
     reason = `OSV unreachable (${e.message})`;
@@ -95,7 +105,7 @@ async function dependencyTier(root) {
   // 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 (hasBinary("pnpm")) {
+  if (manager === "pnpm" && hasBinary("pnpm")) {
     try {
       let stdout;
       try {
@@ -113,8 +123,8 @@ async function dependencyTier(root) {
 
   if (!osvOk && !pnpmOk)
     return { tier: { ran: false, tool: null, reason: reason ?? "registry unreachable" }, findings: [] };
-  const tool = osvOk && pnpmOk ? "osv-api+pnpm-audit" : osvOk ? "osv-api" : "pnpm-audit";
-  return { tier: { ran: true, tool }, findings: dedupeFindings(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);

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/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,13 +97,50 @@ export async function runDoctor(ROOT = process.cwd()) {
     }
   }
 
-  // 3b · security tools — the audit engine's core (lockfile parser + OSV +
+  // 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"],

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/releases.mjs

@@ -409,6 +409,53 @@ export const RELEASES = [
       "origin/HEAD → main) drives the checkpoint trunk guard + CI distill " +
       "target.",
   },
+  {
+    version: "0.12.0",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "THE SECURITY MODULE (owner-ratified 2026-07-26; spec " +
+      ".arohi/2026-07-26-security-module-spec.md): `rafa audit` — the " +
+      "SELF-CONTAINED engine (rafa.audit/v1): dep CVEs via the built-in " +
+      "lockfile parser + keyless OSV.dev merged with pnpm audit; secrets via " +
+      "the built-in ruleset (tracked files only, .env* never opened, " +
+      "fingerprints never bytes); SAST via semgrep IF present — a tier that " +
+      "didn't run says ran:false, never an empty list. NO binaries bundled " +
+      "or installed, ever. Improvement frontmatter `lens` RENAMED `category` " +
+      "(same enum; `lens` accepted as a deprecated alias — old ledgers keep " +
+      "compiling). New blueprint SOP rafa-security (never a dev verb): " +
+      "mechanical priority map critical→P0…dev-only→P3, reachability " +
+      "annotated from the brain, P0 security rows travel outside the blast " +
+      "radius; bloom 0.10.0 (security-profile duty), atlas 4.1.0 (plan-time " +
+      "audit transparency — clean is said out loud), scan requires the " +
+      "security-posture playbook. doctor gains the security-tools block.",
+  },
+  {
+    version: "0.13.0",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "WHOLE-BRAIN MANDATORY CAPTURE (owner r4–r6, 2026-07-26 — 'if the " +
+      "brain did not capture what happened during the session, it's a " +
+      "failure'): `rafa guard --pre-push` — the capture-integrity gate the " +
+      "pre-push hook runs FIRST: every outgoing commit must carry its 1-1 " +
+      "brain mirror; missing → self-heal → still missing → the push BLOCKS " +
+      "(RAFA_HOOKS_DISABLED=1 is the on-the-record escape hatch); " +
+      "post-commit mirror failures go LOUD. `rafa checkpoint` auto-CONVERGES " +
+      "reported improvement flips into real ledger files and COMPULSORILY " +
+      "hydrates notes citing touched code (dirty queue ∪ git branch-vs-trunk " +
+      "diff — manual edits count) so affected-note edits happen DURING " +
+      "development. report_improvement_status returns required_next. " +
+      "MULTI-MANAGER lockfiles in the audit core: pnpm · npm (v3+v1, " +
+      "dev/direct from the lockfile) · yarn (classic+berry) · bun (text " +
+      "JSONC), resolved dynamically richest-first; yarn/bun are honestly " +
+      "packages-only (chain/dev null); binary bun.lockb detected and pointed " +
+      "at --save-text-lockfile; doctor FAILS a package.json repo with no " +
+      "lockfile and prints the per-manager generate command. review.json " +
+      "joins the brain-repo bootstrap ignore.",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "rafa — the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
   "type": "module",
   "bin": {

package/skills-bundle/skills-manifest.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-07-26T15:51:05.847Z",
+  "generatedAt": "2026-07-26T18:16:15.258Z",
   "skills": {
     "tdd": {
       "version": "1.0.0",