@rafinery/cli 0.10.0 → 0.12.0

package/lib/audit.mjs

@@ -0,0 +1,279 @@
+// 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,
+  SECRET_PATTERNS,
+  buildOsvQueries,
+  buildReport,
+  classifyReachability,
+  dedupeFindings,
+  entropyOf,
+  fromGitleaks,
+  fromOsvBatch,
+  fromPnpmAudit,
+  fromRegexSecrets,
+  fromSemgrepSarif,
+  mapConcurrent,
+  parsePnpmLock,
+} 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; `pnpm audit` secondary.
+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 parsed = parsePnpmLock(readFileSync(lockPath, "utf8"));
+  const reachability = classifyReachability(parsed);
+  const findings = [];
+  let osvOk = false;
+  let reason = null;
+
+  try {
+    const chunks = buildOsvQueries(parsed.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, parsed.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 (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 tool = osvOk && pnpmOk ? "osv-api+pnpm-audit" : osvOk ? "osv-api" : "pnpm-audit";
+  return { tier: { ran: true, tool }, 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/checkpoint.mjs

@@ -108,11 +108,20 @@ export default async function checkpoint() {
 
   // The working set is BRANCH state. On the trunk, knowledge changes go
   // through scan → compile → rafa push (the org brain's one writer surface).
-  if (branch === "main" || branch === "master") {
-    console.log(
-      `• on ${branch} — the working set is branch-scoped; org-brain changes on the trunk go through /rafa scan + rafa push. Nothing to checkpoint.`,
-    );
-    return;
+  // The trunk is RESOLVED, never hardcoded (owner 2026-07-26): the stamped
+  // prodBranch → origin/HEAD → "main"; the main|master pair stays as a belt
+  // ONLY for unconfigured repos (with prodBranch set, "main" can be a plain
+  // feature-carrying branch and its working set checkpoints normally).
+  {
+    const { trunkBranchOf, readStamp } = await import("./stamp.mjs");
+    const trunk = trunkBranchOf(ROOT);
+    const configured = typeof readStamp(ROOT).prodBranch === "string";
+    if (branch === trunk || (!configured && (branch === "main" || branch === "master"))) {
+      console.log(
+        `• on ${branch} (the trunk) — the working set is branch-scoped; org-brain changes on the trunk go through /rafa scan + rafa push. Nothing to checkpoint.`,
+      );
+      return;
+    }
   }
 
   // The commit this capture is grounded against (contract: capturedAtSha —

package/lib/distill.mjs

@@ -40,8 +40,17 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { callTool } from "./mcp-client.mjs";
-import { runCompile } from "./gate/compile.mjs";
+import { trunkBranchOf } from "./stamp.mjs";
+import { runCompile, SCHEMA_VERSION } from "./gate/compile.mjs";
 import { runVerifyCitations } from "./gate/verify-citations.mjs";
+import {
+  applyLadder,
+  brainSchemaVersion,
+  classOf,
+  resolveSchemaPlan,
+  sourceSchemaVersion,
+  walkBrainNotes,
+} from "./distiller/schema-ladder.mjs";
 import pull from "./pull.mjs";
 import push from "./push.mjs";
 
@@ -192,7 +201,7 @@ export default async function distill(args = []) {
     try {
       await callTool(ROOT, "report_distill_run", {
         branch,
-        toBranch: process.env.RAFA_TARGET_BRANCH || "main",
+        toBranch: process.env.RAFA_TARGET_BRANCH || trunkBranchOf(ROOT),
         mergeCommitSha: mergeSha,
         status,
         note: summary,
@@ -371,6 +380,35 @@ export default async function distill(args = []) {
   await pull(["--full"]);
   console.log(`  ⏱ brain mirror: ${secs(tPull)}s`);
 
+  // 2b · SCHEMA LADDER (0.11.0 — the owner's 4-case doctrine): resolve the
+  // version lattice BEFORE any claim-level judging, so knowledge from two
+  // lineages always meets on ONE schema — the newest this runner understands.
+  // Lifted target notes ride THIS run's gates + push (one migration+reconcile
+  // commit); an unknown future schema aborts loudly, never downgrades.
+  {
+    const target = brainSchemaVersion(join(ROOT, ".rafa"));
+    const source = sourceSchemaVersion(active.map((f) => f.content));
+    const plan = resolveSchemaPlan({ target, source, latest: SCHEMA_VERSION });
+    console.log(
+      `• schema ladder: target v${target} · source v${source} · runner v${SCHEMA_VERSION} → ${plan.mode}`,
+    );
+    if (plan.mode === "abort-newer-than-runner") die(plan.reason);
+    if (plan.mode !== "diff") console.log(`  ${plan.reason}`);
+    // Per-OKF-type lifts (class derives from the PATH — typed-candidates
+    // doctrine); non-laddered paths (intent records …) pass through untouched.
+    if (plan.upgradeSource)
+      for (const f of active) {
+        const cls = classOf(f.path);
+        if (cls) f.content = applyLadder(f.content, plan.toVersion, cls);
+      }
+    if (plan.rewriteTarget)
+      for (const noteFile of walkBrainNotes(join(ROOT, ".rafa"))) {
+        const cls = classOf(noteFile);
+        if (cls)
+          writeFileSync(noteFile, applyLadder(readFileSync(noteFile, "utf8"), plan.toVersion, cls));
+      }
+  }
+
   // 3 · stage the incoming working set for the agent (gitignored inside .rafa).
   const stagingRoot = join(ROOT, ".rafa", "distill-incoming");
   rmSync(stagingRoot, { recursive: true, force: true });
@@ -554,7 +592,22 @@ ${fileList}`;
     (f) => byPath.get(f.path).verdict === "distilled",
   ).length;
   if (distilledCount > 0) {
-    await push(["--verb=distill"]);
+    // Descriptive reconciliation commit (owner 2026-07-26): the subject says
+    // WHAT this run did — branch, per-verdict counts, the banked ids — so any
+    // agent (ours or a foreign OKF reader) walking the brain log understands
+    // the commit without opening it. brain-for trailer untouched (push owns it).
+    {
+      const counts = { distilled: 0, refuted: 0, "needs-adjudication": 0 };
+      for (const v of verdicts) counts[v.verdict] = (counts[v.verdict] ?? 0) + 1;
+      const banked = verdicts
+        .filter((v) => v.verdict === "distilled")
+        .map((v) => String(v.path).split("/").pop().replace(/\.md$/, ""));
+      const idList = banked.slice(0, 4).join(", ") + (banked.length > 4 ? " …" : "");
+      await push([
+        "--verb=distill",
+        `--message=reconcile(${branch}): ${counts.distilled} banked · ${counts.refuted} refuted · ${counts["needs-adjudication"]} adjudication${banked.length ? ` — ${idList}` : ""}`,
+      ]);
+    }
   } else {
     console.log("• no survivors — nothing to push to the brain repo");
   }

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/distiller/schema-ladder.mjs

@@ -0,0 +1,186 @@
+// The schema ladder (0.11.0 — schema-aware reconciliation, owner's 4-case
+// doctrine, 2026-07-25). Distillation is where knowledge from two lineages
+// meets, so it is ALSO where brain schema versions meet — the reconciler
+// resolves the version lattice BEFORE any claim-level judging, and the merged
+// result always lands on the newest schema the RUNNER understands:
+//
+//   1. target < source            → REWRITE-TARGET: the whole target brain
+//      lifts to the newer schema (the incoming side already speaks it).
+//   2. target > source            → UPGRADE-SOURCE: incoming old-schema
+//      candidates lift into the target's newer schema before judging.
+//   3. target == source < latest  → REWRITE-MERGED: both sides lift; the
+//      merged target is a full rewrite onto the latest schema.
+//   4. target == source == latest → DIFF: the happy flow, exactly today.
+//   ∅. either side > latest       → ABORT LOUDLY: a newer CLI authored this;
+//      this runner cannot judge a schema it does not know — update the
+//      runner, NEVER downgrade knowledge.
+//
+// Every non-abort mode converges in ONE pass: toVersion is always the
+// runner's latest (which case 1/2's higher side already equals or precedes —
+// the runner can never know less than what it authored). Transforms are
+// REGISTERED per step (v(N-1)→vN) in LADDER below; a missing step throws —
+// the ladder never guesses a schema (no assumed values). v1 is the baseline
+// and the only schema in existence today, so the registry ships empty: this
+// module is the SEAM, proven by tests, that makes a future v2 a one-entry
+// change instead of a migration crisis.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+// Per-step, PER-OKF-TYPE transforms (owner 2026-07-26: each file class has its
+// own shape in the contract's type registry, so each ladder step declares each
+// class EXPLICITLY):
+//
+//   LADDER[2] = {
+//     describe: "what v2 changes",
+//     rule: (content) => content2,     // a real shape change for rules
+//     playbook: "unchanged",           // EXPLICIT identity — visible, auditable
+//     improvement: (content) => …,
+//   }
+//
+// Only the three DURABLE knowledge classes ladder (rule · playbook ·
+// improvement — the classes distillation judges and the brain keeps). Derived/
+// generated files (coverage, checklist, ledger, reconciliation reports,
+// manifest) are NEVER migrated — their producers regenerate them at the new
+// schema. A step missing a class entry is a LOUD error, not implicit identity:
+// "unchanged" must be declared, never assumed. Every applied step (identity
+// included) re-stamps the note's own `schemaVersion:` line.
+export const LADDER = {};
+
+export const LADDER_CLASSES = ["rule", "playbook", "improvement"];
+
+// Class resolution chain (owner 2026-07-26): DIRECTORY first — inside rafa's
+// transport the path is governed identity (the CAS row key, the registry
+// glob, the hydrate target; it cannot drift without becoming a different
+// row) — then the PORTABLE filename suffix (`.rule.md` · `.playbook.md` ·
+// `.improvement.md`), which travels WITH a file that leaves the canonical
+// tree (foreign OKF bundles, out-of-context shares) while staying outside
+// the corruptible content. When BOTH are present they must AGREE — a
+// contradiction throws loudly, never a guess. Returns null for non-laddered
+// paths (intent records, reports, …) — those pass through untouched.
+const SUFFIX_CLASS = {
+  ".rule.md": "rule",
+  ".playbook.md": "playbook",
+  ".improvement.md": "improvement",
+};
+export function classOf(path) {
+  const p = String(path).replace(/\\/g, "/");
+  const byDir = p.includes("brain/rules/")
+    ? "rule"
+    : p.includes("brain/playbooks/")
+      ? "playbook"
+      : p.includes("improve/improvements/")
+        ? "improvement"
+        : null;
+  const bySuffix =
+    Object.entries(SUFFIX_CLASS).find(([s]) => p.endsWith(s))?.[1] ?? null;
+  if (byDir && bySuffix && byDir !== bySuffix)
+    throw new Error(
+      `schema ladder: directory class "${byDir}" contradicts filename class "${bySuffix}" (${p}) — ` +
+        "fix the file's home or its name; the ladder never guesses",
+    );
+  return byDir ?? bySuffix;
+}
+
+// A note's OWN declared schema (first-fence `schemaVersion:`). Default 1 — the
+// founding schema, same convention as stampedVersions defaulting to the first
+// release (a pre-stamp file predates versioning, it isn't unversioned).
+export function noteSchemaVersion(content) {
+  if (typeof content !== "string" || !content.startsWith("---")) return 1;
+  const end = content.indexOf("\n---", 3);
+  const fm = end === -1 ? content : content.slice(0, end);
+  const m = fm.match(/^schemaVersion:\s*(\d+)\s*$/m);
+  return m ? Number(m[1]) : 1;
+}
+
+const NOTE_DIRS = ["brain/rules", "brain/playbooks", "improve/improvements"];
+
+export function walkBrainNotes(rafaDir) {
+  const out = [];
+  const walk = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const e of readdirSync(dir)) {
+      const p = join(dir, e);
+      if (statSync(p).isDirectory()) walk(p);
+      else if (e.endsWith(".md") && !e.startsWith("_") && !e.endsWith(".theirs.md"))
+        out.push(p);
+    }
+  };
+  for (const d of NOTE_DIRS) walk(join(rafaDir, d));
+  return out;
+}
+
+// The TARGET brain's schema: manifest.json first (the compiled truth), else
+// the max over its notes' own declarations, else the founding schema.
+export function brainSchemaVersion(rafaDir) {
+  try {
+    const m = JSON.parse(readFileSync(join(rafaDir, "manifest.json"), "utf8"));
+    if (Number.isInteger(m.schemaVersion)) return m.schemaVersion;
+  } catch {
+    /* no manifest — fall through to the notes */
+  }
+  const versions = walkBrainNotes(rafaDir).map((f) =>
+    noteSchemaVersion(readFileSync(f, "utf8")),
+  );
+  return versions.length ? Math.max(...versions) : 1;
+}
+
+// The SOURCE side's schema: the max over the incoming candidates' own
+// declarations (a working set may be mixed if it straddled an upgrade).
+export function sourceSchemaVersion(contents) {
+  const versions = (contents ?? []).map(noteSchemaVersion);
+  return versions.length ? Math.max(...versions) : 1;
+}
+
+// The lattice. Returns {mode, toVersion, rewriteTarget, upgradeSource, reason}.
+export function resolveSchemaPlan({ target, source, latest }) {
+  if (target > latest || source > latest)
+    return {
+      mode: "abort-newer-than-runner",
+      toVersion: null,
+      rewriteTarget: false,
+      upgradeSource: false,
+      reason:
+        `brain schema v${Math.max(target, source)} is NEWER than this runner's v${latest} — ` +
+        "a newer CLI authored it. Update @rafinery/cli and re-run; knowledge is never downgraded.",
+    };
+  const base = { toVersion: latest, rewriteTarget: target < latest, upgradeSource: source < latest };
+  if (target < source)
+    return { mode: "rewrite-target", ...base, reason: `target v${target} < source v${source} — full target rewrite onto v${latest}` };
+  if (source < target)
+    return { mode: "upgrade-source", ...base, reason: `source v${source} < target v${target} — incoming candidates lift into v${latest}` };
+  if (target < latest)
+    return { mode: "rewrite-merged", ...base, reason: `both sides v${target} < runner v${latest} — merged result rewrites onto v${latest}` };
+  return { mode: "diff", ...base, reason: `both sides already v${latest} — plain diff reconcile` };
+}
+
+const stampVersion = (content, v) =>
+  content.replace(/^schemaVersion:\s*\d+\s*$/m, `schemaVersion: ${v}`);
+
+// Lift ONE note of ONE class from its own declared version to `to`, one
+// registered step at a time. A missing step OR a missing class entry within a
+// step is a loud error, never a guess; the explicit "unchanged" is the only
+// legal identity, and even it re-stamps the note's schemaVersion line.
+export function applyLadder(content, to, cls) {
+  if (!LADDER_CLASSES.includes(cls))
+    throw new Error(
+      `schema ladder: "${cls}" is not a laddered class (${LADDER_CLASSES.join("|")}) — ` +
+        "derived/generated files regenerate at the new schema, they never migrate",
+    );
+  let from = noteSchemaVersion(content);
+  let out = content;
+  while (from < to) {
+    const step = LADDER[from + 1];
+    const t = step?.[cls];
+    if (t === undefined)
+      throw new Error(
+        `schema ladder: no registered ${cls} transform v${from}→v${from + 1} — every step ` +
+          'declares every class (a function, or the EXPLICIT "unchanged"); ' +
+          "update @rafinery/cli to a release that ships it (the ladder never guesses a schema)",
+      );
+    out = t === "unchanged" ? out : t(out);
+    out = stampVersion(out, from + 1);
+    from += 1;
+  }
+  return out;
+}

package/lib/doctor.mjs

@@ -97,6 +97,22 @@ export async function runDoctor(ROOT = process.cwd()) {
     }
   }
 
+  // 3b · security tools — the audit engine's core (lockfile parser + 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");
+    console.log("• security tools (rafa audit)");
+    ok("core engine built in (dep CVEs via OSV · secrets ruleset)");
+    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");