@rafinery/cli 0.12.0 → 0.14.0

package/blueprint/.claude/skills/rafa-plan/SKILL.md

@@ -23,13 +23,13 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
   the tools; the dev never asks for it. Repo not platform-connected (no `rafinery`
   MCP in the session)? Fall back to reading `.rafa/brain/` files directly — same
   knowledge, just unserved.*
-- **bloom pulls** — `list_improvements` in the blast radius (PLUS any open
-  `category: security` P0 regardless of region — the one class that travels;
-  one line, dismissible, never blocking); surface the
+- **bloom pulls** — `list_improvements` in the blast radius, surfacing the
   top-leverage open items as optional *"while-you're-here"* child tasks
-  (leverage-ranked, dismissible, never blocking). **Any improvement the plan
-  ADOPTS (as a task or the plan's very subject) is hydrated NOW** —
-  `rafa hydrate improvement <id>` — so the canonical ledger file is in the
+  (leverage-ranked, dismissible, never blocking). Open `category: security` P0s
+  come along too — the one class that travels regardless of region (contract
+  §12.5), one line, still dismissible, never blocking. **Any improvement the
+  plan ADOPTS** — as a task or as the plan's very subject — **is hydrated NOW**
+  (`rafa hydrate improvement <id>`), so the canonical ledger file is in the
   branch working set from the start and the eventual `status: fixed` edit lands
   on that same file, never a path-drifted twin authored at build's end.
   **Also pull `get_knowledge_gaps`** (the open backlog — what devs asked that
@@ -102,17 +102,17 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
    the pivotal choices are logged as DECISIONS at approval (`log_decision`:
    context · options · decision · rationale; actor = the dev for their calls).
 3. **Ledger pull** (bloom) → optional leverage tasks in the blast radius.
-3b. **Security transparency** (2026-07-26 r2 — "security is not an aftermath").
-   Run `npx @rafinery/cli audit --json` (seconds; reuse a same-session
-   `security-audit.json` if fresh) and present the picture TO THE DEV, verbatim
-   and unburied, before the plan is approved: one line of severity totals +
-   which tiers ran, then any critical/high finding whose package or file sits
-   in THIS plan's blast radius (per [rafa-security](../rafa-security/SKILL.md)'s
-   reachability method). A blast-radius critical/high → propose it as a plan
-   child task (the fix rides the work); open `category: security` P0s surface
-   regardless of region. Transparent means: the dev sees the counts even when
-   everything is clean — "dependency tier clean at <sha>" is one honest line,
-   never silence.
+3b. **Security transparency — integral, never an aftermath** (contract §12.5;
+   owner 2026-07-26). Run `npx @rafinery/cli audit --json` (seconds; reuse a
+   same-session `security-audit.json` if fresh) and put the picture in front of
+   the dev — verbatim and unburied — before the plan is approved: one line of
+   severity totals plus which tiers ran, then any critical/high finding whose
+   package or file sits in THIS plan's blast radius (per
+   [rafa-security](../rafa-security/SKILL.md)'s reachability method). A
+   blast-radius critical/high becomes a plan child task, so the fix rides the
+   work. Transparency is the whole point — the dev sees the counts even when
+   nothing is wrong: *"dependency tier clean at <sha>"* is one honest line,
+   said out loud, never silence.
 4. **Leverage-match** — recommend existing skills/tools/MCP that fit the tasks;
    never plan to hand-roll what a capability already does.
 5. **prism plan-validation** → REJECT/fix loop until clean.

package/blueprint/.claude/skills/rafa-scan/SKILL.md

@@ -201,12 +201,13 @@ retrieval index. Bodies read like a senior engineer explaining that one concept
 6. **Flow tracing** [LLM, cited] — from each entry point, hop-by-hop to termination
    (render / DB write / response) → `flow` playbooks. Add `how-to` playbooks for the
    recurring "add X" procedures these flows imply.
-   **One `security-posture` playbook is required** (2026-07-26): the repo's trust
-   boundaries (what's server-exposed vs build-time), auth chokepoints (where
-   authz is enforced — cited), and the secret-handling convention (where env
-   names are read; names only, per the step-4 guardrail). This is durable
-   KNOWLEDGE, not findings — it grounds bloom's security profile
-   ([rafa-security](../rafa-security/SKILL.md)): reachability annotations on
+   **One `security-posture` playbook is required** (owner 2026-07-26): the repo's
+   trust boundaries (what's server-exposed vs build-time), auth chokepoints
+   (where authz is enforced — cited), and the secret-handling convention (where
+   env names are read; names only, per the step-4 guardrail). This is durable
+   KNOWLEDGE, not findings — it is the flow-trace of the repo's trust surface,
+   and it grounds bloom's security profile
+   ([rafa-security](../rafa-security/SKILL.md)): the reachability annotations on
    CVE rows come FROM this note's map.
 
 7. **Verification & synthesis** — apply the 100× filter (a note earns a file only if it
@@ -246,10 +247,38 @@ subagent it calls in step 1/5. **`init`** = ensure structure idempotently (`.raf
 pipeline; **`--brain-only`** stops after the brain is validated (step 5 PASS) — skips improve
 + push, a cheap knowledge refresh.
 
-1. **Scan — spawn `atlas`** context-isolated: *"Run the scan per this SOP: comprehensive,
-   breadth-before-depth, cited notes → `.rafa/brain/{rules,playbooks}/` + `coverage.md`. Run
-   `npx @rafinery/cli verify-citations` until it **exits 0**. Return a coverage summary only —
-   not the raw reads."*
+0. **RESOLVE THE REAL BRAIN FIRST — mandatory and mechanical (the canonical
+   continuity law, [contract §12.4](../../rafa/contract.md)).** Before ANY scan
+   step, run `npx @rafinery/cli pull --full` — materialize the org brain into
+   `.rafa/` and confirm it sits at the brain remote's HEAD
+   (`git -C .rafa fetch origin && git -C .rafa status`). A stale local `.rafa`
+   (e.g. parked on an old genesis commit) is exactly how a session scans blind
+   and mints a parallel brain (the incident this step exists to prevent — see
+   the anti-patterns). **Founding is PLATFORM truth, never local emptiness**:
+   founding ⇔ the platform serves zero knowledge
+   (`search_knowledge`/`list_improvements` both empty). If ANY notes exist, this
+   is a **REFRESH**, not a founding scan:
+   - **Ids are stable forever.** One concept = one id. atlas UPDATES the
+     existing file in place (content, cites, links); it NEVER mints a new id
+     for a concept an existing note covers.
+   - **Retirement is a TOMBSTONE, never a deletion** (the §2 lifecycle law): set
+     `status: retired` in the existing file and append a dated `## Retired`
+     body section — why it no longer holds, what supersedes it (linked).
+     The file stays as history (excluded from recall by the platform);
+     a state change is never recorded by removing a file.
+   - New ids are for genuinely new concepts only — and each new note names, in
+     its body, why no existing note covers it.
+   - The founding-scan coach offer (step 9) NEVER fires on a refresh.
+1. **Scan — spawn `atlas`** context-isolated. On a REFRESH, the spawn prompt
+   MUST carry the existing inventory: *"REFRESH mode — the org brain is
+   materialized under `.rafa/brain/` (<N> rules · <M> playbooks · <K>
+   improvements). Update in place: ids are stable; never write a new note for
+   a concept an existing note covers; deletions are explicit. Run the scan per
+   this SOP: comprehensive, breadth-before-depth, cited notes →
+   `.rafa/brain/{rules,playbooks}/` + `coverage.md`. Run
+   `npx @rafinery/cli verify-citations` until it **exits 0**. Return a
+   coverage summary only — not the raw reads."* (Founding keeps the same
+   prompt minus the refresh preamble.)
 2. **Gate 1 — checker (trust-but-verify):** re-run `npx @rafinery/cli verify-citations`
    yourself. Must **exit 0** (else re-spawn atlas to fix). It writes `citation-check.md`.
 3. **Gate 2 — prism:** spawn `prism` **context-isolated**, passing ONLY: *"Validate the scan
@@ -344,6 +373,11 @@ The report must state PASS/FAIL **per criterion** (not a summary verdict), so it
 targets the exact failing box.
 
 ## Anti-patterns (do NOT do)
+- **Scan without pulling the real brain (the parallel-brain incident,
+  2026-07-27).** A blind re-scan mints new ids for concepts that already have
+  notes — 28 duplicates against 14 existing notes, zero continuity. Step 0 is
+  mandatory; the reconciler's duplicate guard will CONTEST parallel notes, but
+  contested duplicates are cleanup, not a workflow.
 - Cherry-pick the flashiest seam — the exact failure this capability prevents.
 - Single-file conventions only — the old scan's shallowness.
 - **Inferred / sampled / from-memory citations** — every `file:line` is grep-or-read

package/blueprint/.claude/skills/rafa-security/SKILL.md

@@ -6,9 +6,10 @@ description: "rafa SOP — the security profile: run the self-contained `rafa au
 # security — the profile  (woven, never a command)
 
 rafa's security posture is **woven into the loop, not a chore**: the dev never
-types a security command. Owner doctrine (2026-07-26 r2): *"security is not an
-aftermath — it is an integral part of the development cycle."* The engine
-fires at every moment of that cycle:
+types a security command. Owner doctrine (owner 2026-07-26, consolidated in
+[contract §12.5](../../rafa/contract.md)): *"security is not an aftermath — it
+is an integral part of the development cycle."* The engine fires at every
+moment of that cycle:
 
 - **plan** — the audit runs before approval and its picture is presented to
   the dev verbatim (rafa-plan §3b): totals + blast-radius criticals; clean is
@@ -28,9 +29,13 @@ the platform's Security tab reads the merge-level rows.
 Run **`npx @rafinery/cli audit --json`** and parse the `rafa.audit/v1`
 envelope. The engine is SELF-CONTAINED — it needs no installs, ever:
 
-- **dependency** — built-in pnpm-lock parser + the OSV.dev advisory API,
-  merged with `pnpm audit`; per finding: package · GHSA/CVE + aliases ·
-  severity + CVSS · direct-vs-transitive chain · fixed-in · dev-only flag.
+- **dependency** — a built-in **multi-manager** lockfile parser (pnpm · npm ·
+  yarn · bun, resolved dynamically richest-first — never a pnpm hardcode) +
+  the keyless OSV.dev advisory API, merged with `pnpm audit` on pnpm repos;
+  per finding: package · GHSA/CVE + aliases · severity + CVSS ·
+  direct-vs-transitive chain (pnpm/npm; yarn/bun are honestly packages-only) ·
+  fixed-in · dev-only flag. No lockfile → the tier is `ran:false` and
+  `rafa doctor` prints the per-manager command to generate one.
 - **secrets** — built-in curated ruleset over tracked files (`.env*` never
   opened; fingerprints, never secret bytes). gitleaks enhances if present.
 - **sast** — semgrep if installed (pinned `p/security-audit`), otherwise the
@@ -59,8 +64,10 @@ Required frontmatter as ever (`title` · `summary` · `fix` · `leverage` ·
 
 **Reconcile like any improvement**: dedupe against existing rows by the stable
 finding id (in the body); auto-close rows whose finding vanished from a fresh
-audit (`status: fixed` — the lockfile bump landed); preserve the dev's triage
-(backlog/wontfix stay).
+audit (`status: fixed` — the lockfile bump landed) **with a dated closure line
+in the body naming the evidence (the new lockfile version / the vanished
+advisory) — a tombstone, never a removal** (the §2/§12.4 lifecycle law);
+preserve the dev's triage (backlog/wontfix stay).
 
 ## Brain-ground the reachability (the judgment part)
 

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

@@ -41,7 +41,6 @@ export const BLUEPRINT = {
     ".claude/skills/rafa-commit",
     ".claude/skills/rafa-review",
     ".claude/skills/rafa-improve",
-    ".claude/skills/rafa-distill",
     ".claude/skills/rafa-insights",
     ".claude/skills/rafa-leverage",
     ".claude/skills/rafa-sage",

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";
@@ -27,7 +27,7 @@ export async function runDoctor(ROOT = process.cwd()) {
   console.log("rafa doctor — proving the capture machinery\n");
 
   // 1 · provisioning — the same resolution the real tools use, so a doctor
-  // pass here means checkpoint/distill auth will resolve identically.
+  // pass here means checkpoint/reconcile auth will resolve identically.
   console.log("• provisioning");
   let provisioned = false;
   try {
@@ -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/gate/compile.mjs

@@ -221,9 +221,15 @@ export function runCompile(argv = []) {
         const t = citeTargetTokens(c.file);
         if (t !== null) c.targetTokens = t;
       }
+      // Lifecycle (r7c, tombstone doctrine): notes are NEVER deleted — a
+      // retired note keeps its file with `status: retired` + a dated body
+      // section explaining why. Optional; absent = active by contract.
+      if ("status" in data && !isEnum(data.status, ["active", "retired"]))
+        fail(path, "status", "optional · active|retired (retirement is a tombstone, never a deletion)");
       notes.push({
         id,
         kind,
+        ...(data.status === "retired" ? { status: "retired" } : {}),
         type: reqEnum(
           data,
           "type",

package/lib/gate/verify-citations.mjs

@@ -263,7 +263,14 @@ export function runVerifyCitations(argv = []) {
 
   for (const note of notes) {
     const rel = note.replace(ROOT + "/", "");
-    const lines = readFileSync(note, "utf8").split("\n");
+    const raw = readFileSync(note, "utf8");
+    // TOMBSTONES are history, not claims (r7c): a retired note / closed
+    // improvement keeps its (possibly dead) citations as the record of what it
+    // once claimed — the checker skips them entirely; only LIVE knowledge is
+    // verified. (status: is frontmatter-only, so a body mention can't trip this.)
+    const fm = raw.startsWith("---") ? (raw.split("\n---")[0] ?? "") : "";
+    if (/^status:\s*(retired|fixed|wontfix)\s*$/m.test(fm)) continue;
+    const lines = raw.split("\n");
     const cites = [];
     const anchors = [];
     const absents = [];