@rafinery/cli 0.5.0 → 0.6.0

package/lib/claude-config.mjs

@@ -13,6 +13,83 @@ export const RAFA_PERMISSIONS = [
   "Bash(rafa:*)",
 ];
 
+// The M5 sensor hooks (capture engine): SessionStart injects the state digest
+// (staleness · conflicts · active plan), PostToolUse dirty-marks edited code
+// files into .rafa/dirty.jsonl. Both scripts are vendored LOCKSTEP at
+// .claude/rafa/hooks/ and are no-ops outside a rafa-provisioned repo.
+export const RAFA_HOOKS = {
+  SessionStart: {
+    matcher: "startup|resume|clear",
+    command: 'node "$CLAUDE_PROJECT_DIR/.claude/rafa/hooks/session-start.mjs"',
+  },
+  PostToolUse: {
+    matcher: "Edit|Write|MultiEdit|NotebookEdit",
+    command: 'node "$CLAUDE_PROJECT_DIR/.claude/rafa/hooks/post-tool.mjs"',
+  },
+  // The correction reflex (M5 sensor #4): detect correction-shaped prompts,
+  // queue them, and inject the bank-it-now steering at exactly that moment.
+  UserPromptSubmit: {
+    matcher: "*",
+    command: 'node "$CLAUDE_PROJECT_DIR/.claude/rafa/hooks/user-prompt-submit.mjs"',
+  },
+};
+
+// The ambient loop-state statusline (frictionless loop, 2026-07-13). Set ONLY
+// when the dev has no statusline of their own, or theirs is already ours —
+// a configured statusline is the dev's turf, never replaced (merge, don't own).
+export const RAFA_STATUSLINE = {
+  type: "command",
+  command: 'node "$CLAUDE_PROJECT_DIR/.claude/rafa/hooks/statusline.mjs"',
+};
+
+export function mergeStatusLine(targetDir) {
+  const file = settingsPath(targetDir);
+  const existing = readClaudeSettings(targetDir);
+  if (existing && existing.error) {
+    return { skipped: `.claude/settings.json is not valid JSON (${existing.error})` };
+  }
+  const settings = existing ?? {};
+  const cur = settings.statusLine;
+  const ours = typeof cur?.command === "string" && cur.command.includes(".claude/rafa/hooks/statusline.mjs");
+  if (cur && !ours) return { skipped: "you already have a statusline — keeping yours (rafa's shows via `rafa status --line`)" };
+  if (ours && cur.command === RAFA_STATUSLINE.command) return { added: [] };
+  const next = { ...settings, statusLine: { ...RAFA_STATUSLINE } };
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(next, null, 2) + "\n");
+  return { added: ["statusLine"] };
+}
+
+// Merge rafa's sensor hooks into .claude/settings.json WITHOUT clobbering the
+// dev's own hook config: a rafa hook is recognized by its script path — if any
+// handler for that event already points at .claude/rafa/hooks/<script>, the
+// event is left untouched (matcher/command tuning survives updates). Returns
+// { added: [eventNames] } or { skipped: "reason" }.
+export function mergeClaudeHooks(targetDir, defs = RAFA_HOOKS) {
+  const file = settingsPath(targetDir);
+  const existing = readClaudeSettings(targetDir);
+  if (existing && existing.error) {
+    return { skipped: `.claude/settings.json is not valid JSON (${existing.error})` };
+  }
+  const settings = existing ?? {};
+  const hooks = { ...(settings.hooks ?? {}) };
+  const added = [];
+  for (const [event, def] of Object.entries(defs)) {
+    const groups = Array.isArray(hooks[event]) ? hooks[event] : [];
+    const marker = def.command.match(/\.claude\/rafa\/hooks\/[\w.-]+/)?.[0] ?? def.command;
+    const present = groups.some((g) =>
+      (g?.hooks ?? []).some((h) => typeof h?.command === "string" && h.command.includes(marker)),
+    );
+    if (present) continue;
+    hooks[event] = [...groups, { matcher: def.matcher, hooks: [{ type: "command", command: def.command }] }];
+    added.push(event);
+  }
+  if (added.length === 0 && existing) return { added: [] };
+  const next = { ...settings, hooks };
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(next, null, 2) + "\n");
+  return { added };
+}
+
 // Merge the repo's .mcp.json server names into the OWNED agent cards' tools
 // lines (ratified 2026-07-12: subagents must be able to reach the repo's MCPs
 // — a Convex repo's mcp__convex tools were structurally invisible to atlas).

package/lib/dirty.mjs

@@ -0,0 +1,114 @@
+// rafa dirty — the cite-graph invalidator's query surface (M5, agent-internal:
+// the conductor runs this at boundaries; devs never need to remember it).
+//
+//   rafa dirty             human view: dirty code files + the brain notes citing them
+//   rafa dirty --json      the same, machine-shaped (conductor bootstrap / spawn prompts)
+//   rafa dirty --consume   clear the queue AFTER a completed scoped refresh — the
+//                          refresh must have shipped (gates + checkpoint/push) first
+//
+// The queue (.rafa/dirty.jsonl) is written by the PostToolUse hook the moment an
+// edit happens (monotonic, no session-end dependency). Citing notes resolve from
+// the LOCAL manifest when one exists (full pull / prior compile); otherwise the
+// mapping is honestly "unresolved here" — counts still serve, and the platform's
+// get_code_context covers work-time recall. Never guesses.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const DIRTY_FILES_ALARM = 15; // ≥ → recommend /rafa scan --brain-only
+export const CITED_NOTES_ALARM = 10;
+
+export function readDirty(root = process.cwd()) {
+  const file = join(root, ".rafa", "dirty.jsonl");
+  const files = new Map(); // path → last touch
+  if (!existsSync(file)) return { file, files: [] };
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e && typeof e.f === "string") files.set(e.f, e.t ?? "");
+    } catch {
+      /* torn line — skip, never fail the query */
+    }
+  }
+  return { file, files: [...files.entries()].map(([f, t]) => ({ f, t })) };
+}
+
+// file → citing notes from the local manifest; null = no manifest here (lazy .rafa).
+export function resolveCiters(root, dirtyFiles) {
+  const path = join(root, ".rafa", "manifest.json");
+  if (!existsSync(path)) return null;
+  let m;
+  try {
+    m = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+  const want = new Set(dirtyFiles);
+  const notes = [];
+  for (const group of [m.notes ?? [], m.improvements ?? []]) {
+    for (const n of group) {
+      const files = [...new Set((n.cites ?? []).filter((c) => want.has(c.file)).map((c) => c.file))];
+      if (files.length) notes.push({ id: n.id, path: n.path, files });
+    }
+  }
+  return notes;
+}
+
+export default async function dirty(args = []) {
+  const ROOT = process.cwd();
+  const { file, files } = readDirty(ROOT);
+
+  if (args.includes("--consume")) {
+    if (files.length === 0) {
+      console.log("✓ dirty queue already clean");
+      return;
+    }
+    writeFileSync(file, "");
+    console.log(
+      `✓ consumed ${files.length} dirty file(s) — do this ONLY after the scoped refresh shipped (gates + checkpoint/push)`,
+    );
+    return;
+  }
+
+  const notes = resolveCiters(ROOT, files.map((e) => e.f));
+  const alarm =
+    files.length >= DIRTY_FILES_ALARM || (notes !== null && notes.length >= CITED_NOTES_ALARM);
+
+  if (args.includes("--json")) {
+    console.log(
+      JSON.stringify(
+        {
+          files: files.map((e) => e.f),
+          notes, // null = unresolved here (no local manifest) — an honest unknown, not zero
+          thresholds: { files: DIRTY_FILES_ALARM, notes: CITED_NOTES_ALARM },
+          alarm,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  if (files.length === 0) {
+    console.log("✓ dirty queue clean — no code edits recorded since the last brain reconcile");
+    return;
+  }
+  console.log(`${files.length} code file(s) edited since the last brain reconcile:`);
+  for (const e of files) console.log(`  · ${e.f}`);
+  if (notes === null) {
+    console.log("citing notes: unresolved here (lazy .rafa, no local manifest) — recall still");
+    console.log("serves fresh knowledge via the platform; run a scoped refresh from a session.");
+  } else if (notes.length === 0) {
+    console.log("citing notes: none — nothing in the brain cites these files (nothing to refresh).");
+  } else {
+    console.log(`${notes.length} brain note(s) cite them:`);
+    for (const n of notes) console.log(`  · ${n.id}  ←  ${n.files.join(", ")}`);
+  }
+  console.log(
+    alarm
+      ? `⚠ drift past threshold — recommend a brain refresh from main (/rafa scan --brain-only), then \`rafa dirty --consume\`.`
+      : `→ at the next boundary: scoped refresh of the citing notes (atlas re-derives ONLY those → gates → checkpoint), then \`rafa dirty --consume\`.`,
+  );
+}

package/lib/distill.mjs

@@ -61,6 +61,10 @@ async function loadAgentSdk(cwd) {
 const VERDICTS = ["distilled", "refuted", "needs-adjudication"];
 
 export default async function distill(args = []) {
+  // U7 recursion guard, belt-and-braces: the Agent SDK worker must never fire
+  // the M5 session sensors (a worker's own tool calls re-triggering hooks would
+  // loop). The ci-setup workflow sets this too; this covers ad-hoc invocations.
+  process.env.RAFA_HOOKS_DISABLED = "1";
   const branch = args.filter((a) => !a.startsWith("-"))[0];
   if (!args.includes("--headless"))
     die(

package/lib/gate/compile.mjs

@@ -191,6 +191,11 @@ export function runCompile(argv = []) {
       }
       checkVersion(data, path);
       const id = checkId(data, path, name);
+      // `anchor:` / `absent:` are checker-side declarations (verify-citations gates
+      // B2/B3 on them) — optional here, but if present they must be non-empty.
+      for (const key of ["anchor", "absent"])
+        if (key in data && (typeof data[key] !== "string" || data[key].trim() === ""))
+          fail(path, key, "optional · non-empty token (or `none`)");
       notes.push({
         id,
         kind,
@@ -332,9 +337,42 @@ export function runCompile(argv = []) {
         fail(path, `domains.${domain}`, `status ∈ ${STATUS.join("|")}`);
       domains.push({ domain, status: String(status) });
     }
+    // Optional `inventory:` block list — `<name> :: <glob> :: <count>` per entry.
+    // Checker-side (verify-citations recomputes each via git ls-files); validated
+    // here so a malformed declaration fails loudly at the gate, never silently.
+    if ("inventory" in data) {
+      if (!Array.isArray(data.inventory) || data.inventory.length === 0) {
+        fail(path, "inventory", "optional · block list of `<name> :: <glob> :: <count>`");
+      } else {
+        for (const entry of data.inventory)
+          if (!/^.+?\s*::\s*.+?\s*::\s*\d+$/.test(String(entry)))
+            fail(path, "inventory", `malformed entry: ${JSON.stringify(entry)} · must be \`<name> :: <glob> :: <count>\``);
+      }
+    }
     return { domains };
   }
 
+  // citation-check.json — the checker's machine record of its last run (generated
+  // by `rafa verify-citations`). Folded into manifest.citations so the platform
+  // knows which gate level this brain passed. Absent file → null (an honest
+  // "no recorded run"); a malformed one is a tool bug and fails loudly.
+  function compileCitations() {
+    const path = join(ROOT, "brain", "citation-check.json");
+    if (!existsSync(path)) return null;
+    let rec;
+    try {
+      rec = JSON.parse(read(path));
+    } catch (e) {
+      fail(path, "json", `unparseable: ${e instanceof Error ? e.message : e}`);
+      return null;
+    }
+    if (typeof rec.checkerVersion !== "number" || typeof rec.pass !== "boolean" || typeof rec.at !== "string") {
+      fail(path, "shape", "required · { checkerVersion: int, pass: bool, at: ISO string }");
+      return null;
+    }
+    return { checkerVersion: rec.checkerVersion, pass: rec.pass, at: rec.at };
+  }
+
   // Plans (contract §7 v2 — the work-item tree, plans data version 2): one epic
   // (root) → tasks → subtasks. Vendor-blended vocabulary; `blocked` is DERIVED
   // (unresolved blocked_by / blocked_reason), never stored. VALIDATED here
@@ -573,6 +611,7 @@ export function runCompile(argv = []) {
   const health = compileHealth();
   const ledger = compileLedger();
   const coverage = compileCoverage();
+  const citations = compileCitations();
   const plans = compilePlans();
   const activePlanId = compileActivePlanId(plans);
   const agentCards = compileAgentCards();
@@ -607,6 +646,7 @@ export function runCompile(argv = []) {
     health,
     ledger,
     coverage,
+    citations,
     notes,
     improvements,
   };

package/lib/gate/verify-citations.mjs

@@ -1,6 +1,8 @@
 // Deterministic citation checker for the atlas scan output. Lives INSIDE
 // @rafinery/cli (blueprint split, 0.4.0) — run as `rafa verify-citations`.
-// Three gates:
+// Five gates (checker v2 — the 2026-06-08 ratchet: prism's two recommended
+// checks mechanized, per the disposition protocol "every prism catch gets
+// mechanized | eval-cased | judgment"):
 //
 //  RESOLUTION (B1)   — every cite `- <file>:<line>[-<end>] :: <token>` points at a line
 //                      that actually contains <token>. Catches off-by-N / wrong-file.
@@ -11,18 +13,48 @@
 //                      or `anchor: none` for composition/ordering contracts that don't grep
 //                      as one token. So completeness can't be silently skipped (closes F1:
 //                      the guarantee is mandatory, not opt-in; exemptions are explicit).
+//  ABSENCE (B3)      — a note may declare `absent: <token>` (repeatable, anchor-style):
+//                      "this token appears NOWHERE in code." The checker re-greps every
+//                      declared absence and FAILS if it now matches (docs/.md excluded).
+//                      Mechanizes the 2026-06-08 blocker class: a false absence-claim
+//                      (the note said stubbed; the code had grown the real thing).
+//  INVENTORY         — coverage.md may declare `inventory:` entries
+//                      `- <name> :: <glob> :: <count>`; the checker recomputes each via
+//                      `git ls-files ':(glob)<glob>'` and FAILS on drift. Mechanizes the
+//                      route-inventory diff (coverage claiming N surface files vs reality).
 //
-// Writes a generated report to <root>/citation-check.md (don't hand-paste it).
+// Plus a non-failing heuristic: notes whose title/summary reads existence-shaped
+// ("does not exist", "stubbed", "not implemented"…) without declaring `absent:` are
+// listed as WARNs — prism's worklist, never a gate failure (a heuristic that fails
+// the gate would be an assumed value).
+//
+// Writes a generated report to <root>/citation-check.md (don't hand-paste it) and a
+// machine record to <root>/citation-check.json ({ checkerVersion, pass, gates … }) —
+// `rafa compile` folds that record into manifest.citations so the platform knows
+// which gate level a brain actually passed (recorded run, never assumed).
 // Returns exit code 1 on any failure. Run from repo root:  rafa verify-citations
 
-import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, mkdtempSync, rmSync, mkdirSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
+export const CHECKER_VERSION = 2; // v1 = the 3-gate era (resolution/completeness/policy)
+
 const CITE = /^\s*-\s+(.+?):(\d+)(?:-(\d+))?\s*::\s*(.+?)\s*$/; // - file:start[-end] :: token
 const ANCHOR = /^anchor:\s*(.+?)\s*$/;
+const ABSENT = /^absent:\s*(.+?)\s*$/;
 const TYPE = /^type:\s*(.+?)\s*$/;
+const TITLE = /^title:\s*(.+?)\s*$/;
+const SUMMARY = /^summary:\s*(.+?)\s*$/;
+const INV_ENTRY = /^(.+?)\s*::\s*(.+?)\s*::\s*(\d+)$/; // name :: glob :: count
+
+// Existence-shaped phrases (title/summary only — the machine surface; the body is
+// never parsed). Deliberately narrow: policy claims ("never hardcode") must not hit.
+const ABSENCE_HEURISTIC =
+  /(does\s?n[o']?t exist|do not exist|no longer exists?|nowhere in|not (yet )?(implemented|built|wired|created|present)|only a stub|stubbed|unbuilt|unimplemented|nothing (reads|writes|calls|imports|consumes)|absent from)/i;
+
+const strip = (s) => s.replace(/\s+#.*$/, "").replace(/^["']|["']$/g, "").trim();
 
 function walk(dir) {
   if (!existsSync(dir)) return [];
@@ -32,19 +64,33 @@ function walk(dir) {
   });
 }
 
-function gitGrep(token) {
+function gitGrep(token, cwd = process.cwd()) {
   try {
-    const out = execSync(`git grep -nF -e ${JSON.stringify(token)}`, { encoding: "utf8" });
+    const out = execSync(`git grep -nF -e ${JSON.stringify(token)}`, { encoding: "utf8", cwd });
     return out.split("\n").filter(Boolean).map((l) => {
       const m = l.match(/^(.+?):(\d+):/);
       return m ? { file: m[1], line: +m[2] } : null;
-    }).filter(Boolean);
+    }).filter(Boolean)
+      // The brain is never "code": exclude .rafa/** categorically so the checker
+      // can't self-collide with manifests/notes if .rafa is (accidentally) tracked.
+      .filter((h) => !h.file.startsWith(".rafa/"));
   } catch (e) {
     if (e.status === 1) return []; // git grep: no matches
     throw e;
   }
 }
 
+// Tracked files matching a glob — deterministic inventory ground truth.
+// `:(glob)` pathspec magic makes `**` match across directories.
+function gitLsGlob(glob, cwd = process.cwd()) {
+  try {
+    const out = execSync(`git ls-files -- ${JSON.stringify(`:(glob)${glob}`)}`, { encoding: "utf8", cwd });
+    return out.split("\n").filter(Boolean);
+  } catch {
+    return null; // bad pathspec → caller reports it as a failure, never guesses 0
+  }
+}
+
 function citeResolves(file, start, end, token) {
   if (!existsSync(file)) return { ok: false, reason: "file missing" };
   const src = readFileSync(file, "utf8").split("\n");
@@ -53,28 +99,81 @@ function citeResolves(file, start, end, token) {
   return { ok: false, reason: `token not on ${start}${end !== start ? "-" + end : ""}` };
 }
 
+// coverage.md frontmatter `inventory:` block list → [{ name, glob, count }] + malformed lines.
+function parseCoverageInventory(path) {
+  const entries = [];
+  const malformed = [];
+  if (!existsSync(path)) return { entries, malformed };
+  const lines = readFileSync(path, "utf8").split("\n");
+  let fence = 0;
+  let inBlock = false;
+  for (const line of lines) {
+    if (line.trim() === "---") { fence++; if (fence >= 2) break; continue; }
+    if (fence !== 1) continue;
+    if (/^inventory:\s*$/.test(line)) { inBlock = true; continue; }
+    if (inBlock) {
+      const item = line.match(/^\s+-\s+(.+?)\s*$/);
+      if (item) {
+        const m = strip(item[1]).match(INV_ENTRY);
+        if (m) entries.push({ name: m[1].trim(), glob: m[2].trim(), count: +m[3] });
+        else malformed.push(item[1]);
+        continue;
+      }
+      if (/^\S/.test(line)) inBlock = false; // next top-level key ends the block
+    }
+  }
+  return { entries, malformed };
+}
+
 export function runVerifyCitations(argv = []) {
   const arg = (k, d) => { const m = argv.find((a) => a.startsWith(`--${k}=`)); return m ? m.slice(k.length + 3) : d; };
   const ROOT = arg("root", ".rafa/brain");                                      // --root=.rafa/improve for the improve ledger
   const NOTE_DIRS = arg("dirs", "rules,playbooks").split(",").filter(Boolean);  // --dirs=improvements
 
-  // --selftest: prove the resolution logic fails on a bad cite and passes a good one, on a
-  // throwaway temp file (no brain/repo pollution). prism runs this as its mutation probe —
-  // re-running the checker is not proof it still works; this is.
+  // --selftest: prove each gate's logic on throwaway fixtures (no brain/repo pollution).
+  // prism runs this as its mutation probe — re-running the checker is not proof it still
+  // works; this is. Covers: resolution (good+bad cite) · absence (present token must
+  // flag, missing token must pass) · inventory (count drift must flag, exact must pass).
   if (argv.includes("--selftest")) {
-    const dir = mkdtempSync(join(tmpdir(), "vc-selftest-"));
-    const f = join(dir, "sample.txt");
-    writeFileSync(f, "alpha\nTOKEN beta\ngamma\n");
-    const good = citeResolves(f, 2, 2, "TOKEN").ok; // expect true
-    const bad = citeResolves(f, 1, 1, "TOKEN").ok;  // expect false (off-by-one)
-    rmSync(dir, { recursive: true, force: true });
-    const sane = good === true && bad === false;
-    console.log(`checker self-test: ${sane ? "PASS" : "FAIL"} — good cite=${good} (expect true), bad cite=${bad} (expect false)`);
+    const results = [];
+    // resolution — pure file logic
+    {
+      const dir = mkdtempSync(join(tmpdir(), "vc-selftest-"));
+      const f = join(dir, "sample.txt");
+      writeFileSync(f, "alpha\nTOKEN beta\ngamma\n");
+      results.push(["resolution good cite", citeResolves(f, 2, 2, "TOKEN").ok === true]);
+      results.push(["resolution bad cite", citeResolves(f, 1, 1, "TOKEN").ok === false]);
+      rmSync(dir, { recursive: true, force: true });
+    }
+    // absence + inventory — need a real (temp) git index
+    {
+      const dir = mkdtempSync(join(tmpdir(), "vc-selftest-git-"));
+      try {
+        execSync("git init -q", { cwd: dir });
+        mkdirSync(join(dir, "app", "x"), { recursive: true });
+        writeFileSync(join(dir, "app", "x", "page.tsx"), "export default function X() { return SELFTEST_PRESENT; }\n");
+        writeFileSync(join(dir, "app", "readme.md"), "SELFTEST_PRESENT in docs must not count\n");
+        execSync("git add -A", { cwd: dir });
+        const present = gitGrep("SELFTEST_PRESENT", dir).filter((h) => !h.file.endsWith(".md"));
+        const gone = gitGrep("SELFTEST_TRULY_ABSENT", dir).filter((h) => !h.file.endsWith(".md"));
+        results.push(["absence flags a present token", present.length === 1]); // code hit only, .md excluded
+        results.push(["absence passes a truly absent token", gone.length === 0]);
+        const found = gitLsGlob("app/**/page.tsx", dir);
+        results.push(["inventory exact count passes", (found ?? []).length === 1]);
+        results.push(["inventory drift flags", (found ?? []).length !== 2]);
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    }
+    const sane = results.every(([, ok]) => ok);
+    for (const [name, ok] of results) console.log(`  ${ok ? "✓" : "✗"} ${name}`);
+    console.log(`checker self-test (v${CHECKER_VERSION}): ${sane ? "PASS" : "FAIL"}`);
     return sane ? 0 : 1;
   }
 
   const notes = NOTE_DIRS.flatMap((d) => walk(join(ROOT, d)));
-  if (notes.length === 0) {
+  const coveragePath = join(ROOT, "coverage.md");
+  if (notes.length === 0 && !existsSync(coveragePath)) {
     console.log(`No notes under ${ROOT}/{${NOTE_DIRS.join(",")}}/ — run a scan first.`);
     return 0;
   }
@@ -82,13 +181,19 @@ export function runVerifyCitations(argv = []) {
   const resolution = []; // { note, loc, token, ok, reason }
   const completeness = []; // { note, anchor, site, ok, reason }
   const policy = []; // { note, ok, reason }
+  const absence = []; // { note, token, site, ok, reason }
+  const inventory = []; // { name, glob, declared, found, ok, reason, paths }
+  const warns = []; // { note, phrase }  — heuristic, never fails the gate
 
   for (const note of notes) {
     const rel = note.replace(ROOT + "/", "");
     const lines = readFileSync(note, "utf8").split("\n");
     const cites = [];
     const anchors = [];
+    const absents = [];
     let noteType = "";
+    let title = "";
+    let summary = "";
     let fence = 0;
     for (const line of lines) {
       if (line.trim() === "---") { fence++; if (fence >= 2) break; continue; }
@@ -96,9 +201,15 @@ export function runVerifyCitations(argv = []) {
       const c = line.match(CITE);
       if (c) { cites.push({ file: c[1], start: +c[2], end: c[3] ? +c[3] : +c[2], token: c[4] }); continue; }
       const a = line.match(ANCHOR);
-      if (a) { anchors.push(a[1].replace(/\s+#.*$/, "").replace(/^["']|["']$/g, "").trim()); continue; }
+      if (a) { anchors.push(strip(a[1])); continue; }
+      const ab = line.match(ABSENT);
+      if (ab) { absents.push(strip(ab[1])); continue; }
       const t = line.match(TYPE);
-      if (t) noteType = t[1].replace(/\s+#.*$/, "").trim();
+      if (t) { noteType = strip(t[1]); continue; }
+      const ti = line.match(TITLE);
+      if (ti) { title = strip(ti[1]); continue; }
+      const s = line.match(SUMMARY);
+      if (s) summary = strip(s[1]);
     }
 
     // POLICY — every contract must declare an anchor (token or explicit `none`)
@@ -126,15 +237,56 @@ export function runVerifyCitations(argv = []) {
         completeness.push({ note: rel, anchor, site: `${h.file}:${h.line}`, ok: covered, reason: covered ? "" : "grep hit not cited — site omitted" });
       }
     }
+
+    // ABSENCE (B3) — a declared absence must still be absent
+    for (const token of absents) {
+      if (token.toLowerCase() === "none") continue;
+      const hits = gitGrep(token).filter((h) => !h.file.endsWith(".md")); // docs excluded, same rule as completeness
+      if (hits.length === 0) {
+        absence.push({ note: rel, token, site: "(nowhere — as claimed)", ok: true, reason: "" });
+      } else {
+        for (const h of hits) {
+          absence.push({ note: rel, token, site: `${h.file}:${h.line}`, ok: false, reason: "claimed absent but exists — the claim went stale" });
+        }
+      }
+    }
+
+    // WARN heuristic — existence-shaped claim with no declared `absent:` token
+    if (absents.length === 0) {
+      const m = (title + " · " + summary).match(ABSENCE_HEURISTIC);
+      if (m) warns.push({ note: rel, phrase: m[0] });
+    }
+  }
+
+  // INVENTORY — coverage.md declared counts vs tracked reality
+  {
+    const { entries, malformed } = parseCoverageInventory(coveragePath);
+    for (const bad of malformed)
+      inventory.push({ name: "(malformed)", glob: bad, declared: NaN, found: NaN, ok: false, reason: "entry must be `<name> :: <glob> :: <count>`", paths: [] });
+    for (const e of entries) {
+      const paths = gitLsGlob(e.glob);
+      if (paths === null) {
+        inventory.push({ name: e.name, glob: e.glob, declared: e.count, found: NaN, ok: false, reason: "glob is not a valid git pathspec", paths: [] });
+        continue;
+      }
+      const ok = paths.length === e.count;
+      inventory.push({
+        name: e.name, glob: e.glob, declared: e.count, found: paths.length, ok,
+        reason: ok ? "" : `declared ${e.count}, found ${paths.length} — coverage is stale (refresh the scan)`,
+        paths: ok ? [] : paths.slice(0, 20),
+      });
+    }
   }
 
   const rFail = resolution.filter((r) => !r.ok);
   const cFail = completeness.filter((r) => !r.ok);
   const pFail = policy.filter((r) => !r.ok);
-  const fail = rFail.length + cFail.length + pFail.length;
+  const aFail = absence.filter((r) => !r.ok);
+  const iFail = inventory.filter((r) => !r.ok);
+  const fail = rFail.length + cFail.length + pFail.length + aFail.length + iFail.length;
 
   const md = [
-    "# Citation check (generated — do not hand-edit)",
+    `# Citation check (generated — do not hand-edit) · checker v${CHECKER_VERSION}`,
     "",
     `## Resolution (B1): ${resolution.length - rFail.length}/${resolution.length} ✓`,
     ...resolution.map((r) => `${r.ok ? "✓" : "✗"} ${r.loc} :: ${r.token}${r.ok ? "" : "  — " + r.reason + " [" + r.note + "]"}`),
@@ -145,12 +297,51 @@ export function runVerifyCitations(argv = []) {
     `## Policy (contract → anchor declared): ${policy.length - pFail.length}/${policy.length} ✓`,
     ...policy.map((r) => `${r.ok ? "✓" : "✗"} ${r.note}${r.ok ? "" : "  — " + r.reason}`),
     "",
+    `## Absence (B3, declared \`absent:\` re-grepped): ${absence.length - aFail.length}/${absence.length} ✓`,
+    ...absence.map((r) => `${r.ok ? "✓" : "✗"} absent '${r.token}' → ${r.site}${r.ok ? "" : "  — " + r.reason + " [" + r.note + "]"}`),
+    "",
+    `## Inventory (coverage declared vs \`git ls-files\`): ${inventory.length - iFail.length}/${inventory.length} ✓`,
+    ...inventory.flatMap((r) => [
+      `${r.ok ? "✓" : "✗"} ${r.name} '${r.glob}' declared ${r.declared} · found ${r.found}${r.ok ? "" : "  — " + r.reason}`,
+      ...r.paths.map((p) => `    · ${p}`),
+    ]),
+    "",
+    `## Warns (heuristic, non-failing — existence-shaped title/summary with no \`absent:\` declared): ${warns.length}`,
+    ...warns.map((w) => `⚠ ${w.note} — reads as an absence claim ("${w.phrase}") — declare \`absent: <token>\` so the gate can re-grep it, or reword`),
+    "",
     fail ? `**${fail} FAILED.**` : "**All pass.**",
     "",
   ].join("\n");
   writeFileSync(join(ROOT, "citation-check.md"), md);
 
+  // Machine record of THIS run — compile folds it into manifest.citations so the
+  // platform knows the gate level a brain passed. Recorded, never assumed.
+  writeFileSync(
+    join(ROOT, "citation-check.json"),
+    JSON.stringify(
+      {
+        checkerVersion: CHECKER_VERSION,
+        at: new Date().toISOString(),
+        pass: fail === 0,
+        gates: {
+          resolution: { pass: resolution.length - rFail.length, total: resolution.length },
+          completeness: { pass: completeness.length - cFail.length, total: completeness.length },
+          policy: { pass: policy.length - pFail.length, total: policy.length },
+          absence: { pass: absence.length - aFail.length, total: absence.length },
+          inventory: { pass: inventory.length - iFail.length, total: inventory.length },
+        },
+        warns: warns.length,
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+
   console.log(md);
-  console.log(`resolution ${resolution.length - rFail.length}/${resolution.length} · completeness ${completeness.length - cFail.length}/${completeness.length} · policy ${policy.length - pFail.length}/${policy.length}` + (fail ? ` · ${fail} FAILED` : " · all pass"));
+  console.log(
+    `resolution ${resolution.length - rFail.length}/${resolution.length} · completeness ${completeness.length - cFail.length}/${completeness.length} · policy ${policy.length - pFail.length}/${policy.length} · absence ${absence.length - aFail.length}/${absence.length} · inventory ${inventory.length - iFail.length}/${inventory.length}` +
+      (warns.length ? ` · ${warns.length} warn(s)` : "") +
+      (fail ? ` · ${fail} FAILED` : " · all pass"),
+  );
   return fail ? 1 : 0;
 }