@rafinery/cli 0.8.13 → 0.8.15

package/bin/rafa.mjs

@@ -54,6 +54,7 @@ const COMMANDS = [
   "leverage",
   "benchmark",
   "manifest",
+  "review",
   "migrate",
 ];
 const [cmd, ...rest] = process.argv.slice(2);
@@ -133,6 +134,13 @@ Commands:
                        count harness tokens, emit a MEASURED benchmark.json. --dry-run
                        exercises the scaffold from fixture counts; --help documents the
                        agent-driven run procedure. Measured — never the estimated baseline.
+  review               Brain-grounded review pre-pass (deterministic, zero LLM): the
+                       diff's changed lines ∩ the brain's cite graph → everything the
+                       change touches — rules AND playbooks (flow-still-true), open
+                       improvements, stale-cite risk flags, open knowledge gaps,
+                       related plans (.rafa/review.json + summary). The rafa-review
+                       SOP's judge rules on precisely that list — generic "review
+                       this PR" never happens. Advisory; never blocks.
   migrate              Bring this repo's structured files (plans, config) up to the schema
                        the installed CLI ships. Idempotent; review the diff after.
 

package/blueprint/.claude/rafa/hooks/brain-commit.mjs

@@ -142,6 +142,33 @@ try {
       `\n`,
   );
 
+  // Local-state exclusion (owner 2026-07-24): the hydration sidecar + sensor
+  // queues are MACHINE state, never knowledge — ensure the ignore entries and
+  // UNTRACK anything an earlier CLI's window let git track (a .gitignore entry
+  // alone never untracks; `git add -A` would keep committing it forever).
+  // Best-effort: exclusion must never block a code commit.
+  try {
+    const LOCAL_STATE = [
+      "hydration.json",
+      "dirty.jsonl",
+      "reflex.jsonl",
+      "sensor-errors.jsonl",
+      "distill-verdicts.json",
+      "benchmark.demo.json",
+    ];
+    const gi = join(rafa, ".gitignore");
+    const cur = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+    const have = new Set(cur.split("\n").map((l) => l.trim()).filter(Boolean));
+    const missing = [...LOCAL_STATE, "*.theirs.md", "distill-incoming/"].filter((l) => !have.has(l));
+    if (missing.length)
+      writeFileSync(gi, cur + (cur === "" || cur.endsWith("\n") ? "" : "\n") + missing.join("\n") + "\n");
+    for (const p of LOCAL_STATE) shR(`git rm -q --cached --ignore-unmatch "${p}"`);
+    shR('git rm -q -r --cached --ignore-unmatch distill-incoming');
+    shR('git rm -q --cached --ignore-unmatch "*.theirs.md"');
+  } catch {
+    /* exclusion is best-effort */
+  }
+
   shR("git add -A");
   disposeHydrations(branch);
   shR(

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

@@ -19,6 +19,7 @@ platform MCP (one read path — the same surface any third-party agent uses).
 | **Executor** | atlas | RECALL the task's brain slice via MCP (`search_knowledge` + `get_rule`/`get_playbook`; honor non-exemplars) → implement, convention-adherent |
 | **Validator** | prism | validate the execution against the child's `## Done-check` — strict, unbiased, against code + brain, never against atlas's claims. **`status: done` only on prism PASS**; FAIL → atlas corrects (validate-and-correct at work time). Plan-done adds one line to the verdict: **working set reviewed — captured, or clean-with-reason** (a build that learned nothing SAYS so; a build that learned something SHOWS the files) |
 | **Improver** | bloom | **push**: new improvement opportunities spotted during execution → new ledger files. **close**: improvements fixed in passing → `status: fixed` in the ledger file + `report_improvement_status(id, fixed)` so the platform shows it LIVE as pending-reconciliation (the ledger row itself changes only at the next brain push — K1). **nudge**: top-leverage open item in the task's blast radius — opt-in, never blocking |
+| **Coach** | compass | **sitback** (harness-arc): after each task's verdict + sweep, one beat of reflection — did THIS task reveal something about how this DEV works (a preference, a recurring friction, a steering pattern)? Repo knowledge goes to the working set, never here. A genuine dev-level observation becomes its OWN opt-in offer (consent doctrine: insights are NEVER under session consent) → `put_dev_insight` on yes. No observation = no offer — silence is the honest default |
 
 ## Procedure
 
@@ -26,6 +27,11 @@ platform MCP (one read path — the same surface any third-party agent uses).
    (envelope `brainForSha` vs local stamp → prompt `rafa push` if behind). MCP
    recall is automatic throughout — SOP-driven, never dev-invoked; a repo without
    the `rafinery` MCP connected falls back to local `.rafa/` file reads.
+   **On a feature branch, pass `branch: <current git branch>` to
+   search_knowledge/get_rule/get_playbook/get_improvement** — recall then
+   overlays the branch's live working set on canon, every non-canonical result
+   tier-labeled (the alert rule: a `source: {tier: "candidate"}` or
+   `branchOverlay` is branch state, not org truth — say so when you rely on it).
    **Session consent (asked ONCE, verbs ENUMERATED):** *"keep the platform
    updated as I work? That means exactly: (1) plan status + Log pushes on
    cadence, (2) checkpointing this branch's working set (edited/new brain
@@ -82,7 +88,10 @@ platform MCP (one read path — the same surface any third-party agent uses).
    **Gap close-out:** authored knowledge that answers an in-scope knowledge
    gap (adopted at plan time via `get_knowledge_gaps`) closes the loop —
    `set_gap_status(q, "closed")` at the same beat the note is authored.
-4. **Verify** (prism-style) before declaring the plan done; final `push_plan` +
+4. **Verify** (prism-style) before declaring the plan done — including the
+   [rafa-review](../rafa-review/SKILL.md) gate: `rafa review` scopes the exact
+   rules/improvements the branch's diff touches; the judge rules on that list
+   + each Done-check, emits `review-verdict`; final `push_plan` +
    `set_active_plan` (clear) + `rafa checkpoint`. **Dual status (single/double
    tick):** `status: done` is the dev ✓ — prism-earned, session-set, for
    leaves AND the epic (the epic's ✓ = every leaf verified done). DELIVERY is

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

@@ -46,7 +46,14 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
 1. **Staleness check** — compare the platform envelope's `brainForSha` against the
    local brain stamp; if the platform is behind, surface "run `rafa push`" (never
    proceed silently on knowledge you know is stale — never block either).
-2. **Recall** (atlas, via MCP) → **decompose** into the WORK-ITEM TREE (contract
+2. **Recall** (atlas, via MCP) — `get_coverage` now carries **`recentDeltas`**
+   (the last trunk merges' knowledge changes + which plan delivered each):
+   open the plan draft with a TWO-LINE BRIEFING of what changed in the blast
+   radius since it was last touched — planning starts from the deltas, never a
+   stale mental model. `search_knowledge` may return a **`decisions`** block
+   (prior recorded calls matching the query): read it BEFORE re-litigating a
+   settled decision — reopening one is the owner's move, not the plan's.
+   Then **decompose** into the WORK-ITEM TREE (contract
    §7 v2): one epic → tasks → subtasks (three ranks, never deeper). Every item
    carries the glimpse fields — `title` (what) · `description` (why) ·
    `approach` (how, one line) · `assignee` when known · `blocked_by` for

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

@@ -0,0 +1,126 @@
+---
+name: rafa-review
+description: "rafa SOP — the brain-grounded review gate: `rafa review` computes exactly what a diff touches (cite-intersection, zero LLM): rules AND playbooks, open improvements, stale-cite risk, open gaps, related plans' decisions; a prism-style judge rules ONLY on that list + the active task's Done-check; findings feed atlas; the verdict emits a review-verdict loop event. Loaded before push/merge or on request."
+---
+
+# review — the brain-grounded gate  (harness-arc wave 2)
+
+> Status: **active.** The at-the-gate moment: defects caught BEFORE merge, by
+> the repo's own rules — not generic review taste. Depends on: brain (#1),
+> plans (#3, for the Done-check). Runs at the pre-push beat (offer, never
+> block) and on demand.
+
+Generic "review this PR" is banned here. The gate is two passes with a hard
+split:
+
+## Pass 1 — mechanical (the CLI, zero LLM)
+
+`rafa review [--json]` — diff vs merge-base(origin default) → changed line
+ranges ∩ the brain's cite graph (`get_code_context` per file), BOTH note kinds:
+
+- **◆ direct** — a changed line falls inside a note's cited anchor range: the
+  code the note stands on MOVED. Highest priority; also a staleness signal
+  (the note may need a scoped refresh — the dirty queue already tracks it).
+- **· file** — the file changed elsewhere but the note governs it.
+- **⚠ stale cites** — the freshness sweep already flagged this note's anchors
+  as drifted: a RISK marker (verify the note against code before relying on
+  it in judgment — it may describe a world that no longer exists).
+- **! open improvements** citing a touched file — is this change making the
+  debt better, worse, or is it the fix itself (then bloom's close flow)?
+- **open knowledge gaps** (top-missed queries) — live demand near the change.
+
+Output: `.rafa/review.json` + summary. A bounded pass SAYS what it dropped
+(never a silent cap); a mid-pass transport failure marks the list PARTIAL.
+
+## Token economy — BINDING (the gate must cost less than the bugs it catches)
+
+The judge's spend is proportional to the DIFF, never to the brain. Owner rule
+(2026-07-24): review checks only the diff; hydrated fields serve the judgment;
+querying files wholesale is a waste. Concretely:
+
+1. **The pre-pass is free AND selective** — zero LLM; every note carries a
+   deterministic RELEVANCE score (direct-hit +3 · failure:silent +2 · cite
+   anchor token appears in the diff's added lines +2 · title/summary keyword
+   overlap +1 each, capped) and an **`engage` tier**:
+   - `deep` — body-worthy: hydrate/fetch and judge fully;
+   - `triage` — summary-only: rule in/out from metadata + diff, fetch a body
+     ONLY if that makes a violation plausible;
+   - `skip` — governs the file but nothing in the change relates: NEVER
+     judged, never fetched — listed in review.json so nothing drops silently.
+   (Semantic relevance stays contract-reserved via `matchKind` — keywords +
+   citations are the v1 scorer; vectors arrive on evidence, never blindly.)
+2. **Honor the tiers.** The judge never upgrades a `skip`, and upgrades a
+   `triage` to a body fetch only with a stated reason (the finding cites it).
+3. **Local-first, never re-serve.** A note already hydrated under
+   `.rafa/brain/**` (plan/build recall put it there) is read FROM DISK —
+   no MCP round-trip, no double-serving. Fetch via `get_rule`/`get_playbook`
+   only for shortlist notes absent locally; `rafa hydrate <kind> <id>` them
+   so a re-judge after atlas's fix re-reads the disk copy (disposable-cache
+   semantics keep them out of commits).
+   **Frontmatter-first (the OKF leverage):** every file type has a strict
+   format (contract §11), so the MACHINE fields — `cites` · `anchor` ·
+   `failure` · `links` · `type` — parse without touching the prose body.
+   Judge from frontmatter + diff first; read the body only when they can't
+   settle it. A `contract` note's check is half-mechanical before any prose:
+   does the diff touch its `anchor` token anywhere without updating every
+   cited site (the B2 completeness question)?
+4. **Deep-judge cap: 10 notes**, leverage-ranked (◆ direct > failure:silent >
+   ⚠ stale-and-direct > · file). Anything beyond the cap is ruled on metadata
+   only and the verdict SAYS SO ("N notes judged shallow") — an honest bound,
+   never a silent one.
+5. **Metadata-only lanes stay metadata-only**: gaps, decisions, relatedPlans,
+   improvements are judged from what the pre-pass/`get_plan` already carries —
+   no body fetches, no extra searches. NEVER load the whole brain, never
+   fetch a note the pre-pass didn't flag.
+
+## Pass 2 — the judge (prism-style, scoped)
+
+For the work list ONLY — never the whole diff, never taste. Each data kind has
+its OWN question:
+
+1. Per **rule hit** — the OKF `type` names the violation shape:
+   - `convention` → does the new code FOLLOW the local pattern the rule names?
+   - `contract` → the cross-file class: does the diff change any occurrence of
+     the rule's `anchor` without updating EVERY cited site (B2 completeness —
+     half-mechanical from frontmatter, see the economy rules)? `failure:
+     silent` contracts get the deepest scrutiny — that class never announces
+     itself.
+   Judge against code + rule, never against the author's claims.
+2. Per **playbook hit** (`flow` / `how-to` types): is the documented
+   FLOW/how-to still TRUE after this change (steps, ordering, file routes)?
+   A diff that silently invalidates a playbook ships a lie to the next dev —
+   that's an ITERATE finding (or a working-set edit updating the playbook,
+   authored the branch way).
+3. Per **⚠ stale-cite note**: verify the note against current code BEFORE
+   using it in judgment; if the diff is the thing that staled it further,
+   surface the scoped-refresh offer.
+4. Per **open improvement**: touched for better or worse? Fixed-in-passing →
+   bloom's close flow (hydrate first, `status: fixed`, report).
+5. **Related plans' decisions** (`get_plan` for each `relatedPlans` entry):
+   does the diff contradict a recorded decision? Contradicting one is the
+   owner's call to reopen — an ITERATE finding, never silently overridden.
+6. **Open gaps**: does this change ANSWER one (author the note, close the
+   gap) — or deepen it?
+7. **The active task's Done-check** (from `get_active_plan`): does the diff
+   satisfy what the plan said done means?
+8. Verdict: **PASS** or **ITERATE** with per-finding citations (note id +
+   file:line). Findings feed atlas (validate-and-correct — atlas fixes, the
+   judge re-checks; the reviewer never edits).
+9. Emit **`report_loop_event(category: "review-verdict", outcome:
+   PASS|ITERATE, subject: <task id or branch>)`** at the ruling — sage's
+   evidence, monotonic, never a session-end sweep.
+
+## When it runs
+
+- **The pre-push beat** — before `git push`, offer the gate ("review the
+  branch against the brain? <n> rules touched"). Opt-in, advisory, never
+  blocks a push (a declined offer is honored, not re-asked this session).
+- **Plan-done verify** — rafa-build's final verify runs it as part of
+  declaring the build complete.
+- **On demand** — `/rafa review` any time.
+
+## Anti-patterns
+- Judging files the pre-pass didn't flag (scope creep = generic review).
+- Trusting the diff author's summary — judge code against rules.
+- Blocking on the gate — it is advisory; the merge reconciler is the hard gate.
+- Findings without citations (rule id + file:line) — uncited = unactionable.

package/lib/blueprint.mjs

@@ -39,6 +39,7 @@ export const BLUEPRINT = {
     ".claude/skills/rafa-plan",
     ".claude/skills/rafa-build",
     ".claude/skills/rafa-commit",
+    ".claude/skills/rafa-review",
     ".claude/skills/rafa-improve",
     ".claude/skills/rafa-distill",
     ".claude/skills/rafa-insights",

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"];
+  const IGNORES = ["hydration.json", "*.theirs.md", "distill-incoming/", "distill-verdicts.json", "dirty.jsonl", "reflex.jsonl", "sensor-errors.jsonl", "benchmark.demo.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/releases.mjs

@@ -264,6 +264,41 @@ export const RELEASES = [
       "first branch checkout (bounded; a failure never breaks the checkout). " +
       "`rafa update` re-vendors the post-checkout hook.",
   },
+  {
+    version: "0.8.15",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "THE REVIEW GATE + ZERO-LEAK MIRRORS. `rafa review`: deterministic brain-" +
+      "grounded review pre-pass — diff's changed lines ∩ the cite graph → rules AND " +
+      "playbooks + open improvements + stale-cite risk + open gaps, each note " +
+      "relevance-scored (OKF type-aware: contract class weighs heavier) into " +
+      "deep/triage/skip engage tiers so the judge's tokens scale with the DIFF, " +
+      "never the brain (rafa-review SOP: local-first + frontmatter-first reads, " +
+      "10-note deep cap, skips listed never judged). LOCAL-STATE EXCLUSION: the " +
+      "post-commit hook now ensures .rafa/.gitignore AND untracks previously " +
+      "tracked machine state (hydration.json · sensor queues · demo benchmark · " +
+      "distill staging · *.theirs.md) — the next mirror commit cleans the branch. " +
+      "Plus wave-2 SOPs: delta briefing + decision recall at plan time, branch-" +
+      "aware recall (tier-labeled), compass sitback, gap lifecycle beats.",
+  },
+  {
+    version: "0.8.14",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "THE PROVENANCE SPINE (published 2026-07-24). Branch manifest: `rafa manifest` " +
+      "(zero-command — the post-commit brain hook regenerates it per mirrored commit): " +
+      "lenient snapshot with mode:branch · base.brainSha · per-note provenance " +
+      "{baseBrainSha, commits[], tasks[]} — the reconciler's three-way handoff doc. " +
+      "rafa-commit skill: subjects carry the active task id ([task-id] type: subject) " +
+      "and the manifest lifts it into per-note task lineage. Deterministic loop " +
+      "events: push gates emit gate-result from real exit codes; reflex --consume " +
+      "emits reflex-outcome. Benchmark is workflow-woven (scan's Prove-it step + " +
+      "session-start absence sensor) — never a dev-typed command.",
+  },
   {
     version: "0.8.13",
     contract: 1,

package/lib/review.mjs

@@ -0,0 +1,244 @@
+// rafa review — the brain-grounded review gate's DETERMINISTIC pre-pass
+// (harness-arc wave 2). Zero LLM here: the diff's changed line ranges are
+// intersected with the brain's cite graph (get_code_context — file → the
+// RULES *and* PLAYBOOKS and improvements that know about it), producing the
+// exact, scoped work list the rafa-review SOP's judge then rules on. Generic
+// "review this PR" never happens — the judge only ever sees THESE notes
+// against THESE lines. Also surfaced: per-note stale-cite RISK flags (the
+// freshness sweep's signal) and the repo's open knowledge gaps — the judge
+// weighs whether this change answers or worsens one.
+//
+//   rafa review [--base <ref>] [--json]
+//
+// Base defaults to merge-base(HEAD, origin/<default>) — the review covers
+// everything this branch changed (committed + working tree). Advisory always:
+// exit 0, never blocks. Output: .rafa/review.json + a human summary.
+//
+//   hit: "direct"  — a changed line falls INSIDE a cite's line range (the rule's
+//                    anchor itself moved — highest review priority)
+//   hit: "file"    — the file changed elsewhere; the rule still governs it
+//
+// Open improvements citing a touched file + stale-risk flags ride along. The
+// SOP (rafa-review) judges the work list, feeds findings to atlas, and emits
+// report_loop_event(review-verdict, PASS|ITERATE).
+
+import { execSync } from "node:child_process";
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { callTool } from "./mcp-client.mjs";
+
+const MAX_FILES = 50; // bounded fan-out — anything dropped is SAID, never silent
+
+const flag = (args, name) => {
+  const i = args.indexOf(name);
+  return i !== -1 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : null;
+};
+
+const sh = (cmd, cwd) => {
+  try {
+    return execSync(cmd, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "";
+  }
+};
+
+// Parse `git diff -U0` → path → changed NEW-side line ranges [{start, end}].
+export function changedRanges(diffText) {
+  const byFile = new Map();
+  let current = null;
+  for (const line of diffText.split("\n")) {
+    const f = line.match(/^\+\+\+ b\/(.+)$/);
+    if (f) {
+      current = f[1];
+      if (!byFile.has(current)) byFile.set(current, []);
+      continue;
+    }
+    const h = current && line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+    if (h) {
+      const start = Number(h[1]);
+      const count = h[2] !== undefined ? Number(h[2]) : 1;
+      if (count > 0) byFile.get(current).push({ start, end: start + count - 1 });
+      else byFile.get(current).push({ start, end: start }); // pure deletion → the seam line
+    }
+  }
+  return byFile;
+}
+
+// A cite line ("12" | "10-14") vs the changed ranges → direct hit?
+export function citeHits(citeLine, ranges) {
+  const m = String(citeLine ?? "").match(/^(\d+)(?:-(\d+))?$/);
+  if (!m) return false;
+  const a = Number(m[1]);
+  const b = m[2] !== undefined ? Number(m[2]) : a;
+  return ranges.some((r) => a <= r.end && b >= r.start);
+}
+
+// Identifier tokens from the diff's ADDED lines, per file — the relevance
+// vocabulary a note must intersect to earn the judge's attention.
+export function addedTokens(diffText) {
+  const byFile = new Map();
+  let current = null;
+  for (const line of diffText.split("\n")) {
+    const f = line.match(/^\+\+\+ b\/(.+)$/);
+    if (f) {
+      current = f[1];
+      if (!byFile.has(current)) byFile.set(current, new Set());
+      continue;
+    }
+    if (current && line.startsWith("+") && !line.startsWith("+++"))
+      for (const t of line.slice(1).toLowerCase().match(/[a-z_][a-z0-9_-]{2,}/g) ?? [])
+        byFile.get(current).add(t);
+  }
+  return byFile;
+}
+
+// Deterministic relevance (owner 2026-07-24: never hydrate/judge blindly —
+// keywords + citations decide whether a note ADDS VALUE to this diff; the OKF
+// type registry is leveraged: every type has a format, so every type has a
+// DEFINED violation shape and a deterministic weight):
+//   direct anchor hit        +3   (the cited code itself moved)
+//   type: contract           +2   (the cross-file class — breaks span files)
+//   failure: silent          +2   (the class that never announces itself)
+//   cite anchor token in diff +2  (the rule's own token appears in new code)
+//   title/summary keyword     +1 each, capped at +3
+// → engage: "deep" (≥3: body-worthy) · "triage" (1–2: summary-only) ·
+//   "skip" (0: governs the file but nothing relates — listed, never judged).
+export function relevanceOf(note, diffTokens) {
+  let score = 0;
+  if (note.hit === "direct") score += 3;
+  if (note.type === "contract") score += 2;
+  if (note.failure === "silent") score += 2;
+  const anchor = String(note.token ?? "").toLowerCase();
+  if (anchor && [...diffTokens].some((t) => anchor.includes(t) || t.includes(anchor))) score += 2;
+  let kw = 0;
+  const text = `${note.title ?? ""} ${note.summary ?? ""}`.toLowerCase();
+  for (const t of diffTokens) if (text.includes(t)) kw += 1;
+  score += Math.min(kw, 3);
+  return { score, engage: score >= 3 ? "deep" : score >= 1 ? "triage" : "skip" };
+}
+
+export default async function review(args = []) {
+  const ROOT = process.cwd();
+  if (!existsSync(join(ROOT, "rafa.json"))) {
+    console.error("✗ not a rafa repo (no rafa.json)");
+    process.exit(1);
+  }
+  const defaultBranch =
+    sh("git symbolic-ref --short refs/remotes/origin/HEAD", ROOT).replace(/^origin\//, "") || "main";
+  const base =
+    flag(args, "--base") ?? sh(`git merge-base HEAD "origin/${defaultBranch}"`, ROOT) ?? "";
+  if (!base) {
+    console.error(`✗ cannot resolve a review base (no origin/${defaultBranch}?) — pass --base <ref>`);
+    process.exit(1);
+  }
+
+  const diff = sh(`git diff -U0 ${base}`, ROOT);
+  const ranges = changedRanges(diff);
+  const tokensByFile = addedTokens(diff);
+  // Code files only — the brain plane reviews itself at reconcile, not here.
+  const files = [...ranges.keys()].filter(
+    (p) => !p.startsWith(".rafa/") && !p.startsWith(".claude/") && p !== "rafa.json",
+  );
+  const reviewed = files.slice(0, MAX_FILES);
+  const dropped = files.length - reviewed.length;
+
+  const out = [];
+  let unreachable = null;
+  for (const path of reviewed) {
+    let ctx;
+    try {
+      ctx = await callTool(ROOT, "get_code_context", { path });
+    } catch (e) {
+      unreachable = e instanceof Error ? e.message : String(e);
+      break; // one transport failure fails them all — say so, don't half-report
+    }
+    const fileRanges = ranges.get(path) ?? [];
+    // BOTH note kinds engage: a rule hit asks "does the diff still honor the
+    // convention/contract"; a playbook hit asks "is the documented flow/how-to
+    // still true after this change". staleCites = freshness RISK (the note may
+    // already describe drifted code — verify before relying on it).
+    const fileTokens = tokensByFile.get(path) ?? new Set();
+    const notes = (ctx.notes ?? []).map((n) => {
+      const base = {
+        id: n.id,
+        kind: n.kind,
+        ...(n.type ? { type: n.type } : {}),
+        title: n.title,
+        domain: n.domain,
+        line: n.line,
+        token: n.token,
+        ...(n.failure ? { failure: n.failure } : {}),
+        // The one-line summary IS the triage surface — the judge rules most
+        // notes in/out from this alone, fetching bodies only for the shortlist.
+        ...(n.summary ? { summary: n.summary } : {}),
+        ...(n.staleCites ? { staleCites: n.staleCites } : {}),
+        hit: citeHits(n.line, fileRanges) ? "direct" : "file",
+      };
+      const { score, engage } = relevanceOf(base, fileTokens);
+      return { ...base, relevance: score, engage };
+    });
+    const improvements = (ctx.improvements ?? []).filter((i) => i.status === "open");
+    if (notes.length > 0 || improvements.length > 0)
+      out.push({ path, ranges: fileRanges, notes, improvements, relatedPlans: ctx.relatedPlans ?? [] });
+  }
+
+  // Open knowledge gaps — live demand near this change (queries + counts only).
+  // The judge weighs: does this diff ANSWER one (close it) or deepen it?
+  let gaps = [];
+  try {
+    const g = await callTool(ROOT, "get_knowledge_gaps", { status: "open", limit: 5 });
+    gaps = (g.gaps ?? []).map((x) => ({ q: x.q, misses: x.misses }));
+  } catch {
+    /* gaps are context, not a gate — absence never fails the pass */
+  }
+
+  const report = {
+    schemaVersion: 1,
+    base,
+    filesChanged: files.length,
+    filesReviewed: reviewed.length,
+    ...(dropped > 0 ? { dropped } : {}),
+    ...(unreachable ? { unreachable } : {}),
+    files: out,
+    ...(gaps.length > 0 ? { openGaps: gaps } : {}),
+  };
+  writeFileSync(join(ROOT, ".rafa", "review.json"), JSON.stringify(report, null, 2) + "\n");
+
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  const direct = out.flatMap((f) => f.notes.filter((r) => r.hit === "direct"));
+  const fileHits = out.flatMap((f) => f.notes.filter((r) => r.hit === "file"));
+  const imps = out.flatMap((f) => f.improvements);
+  const stale = out.flatMap((f) => f.notes.filter((r) => r.staleCites));
+  const engaged = out.flatMap((f) => f.notes.filter((r) => r.engage !== "skip"));
+  const skipped = out.flatMap((f) => f.notes.filter((r) => r.engage === "skip"));
+  console.log(
+    `✓ review pre-pass vs ${base.slice(0, 7)}: ${files.length} changed file(s)` +
+      (dropped > 0 ? ` (${dropped} beyond the ${MAX_FILES}-file bound NOT reviewed)` : ""),
+  );
+  if (unreachable) console.log(`  ! platform unreachable mid-pass — the work list is PARTIAL: ${unreachable}`);
+  if (out.length === 0) {
+    console.log("  no governed lines touched — nothing for the judge (the brain has no rules citing these files)");
+    return;
+  }
+  for (const f of out) {
+    console.log(`  ${f.path}`);
+    for (const r of f.notes.filter((n) => n.engage !== "skip"))
+      console.log(
+        `    ${r.hit === "direct" ? "◆" : "·"} [${r.engage}] ${r.kind} ${r.id} [${r.domain}] ${r.title}` +
+          `${r.failure ? ` (failure: ${r.failure})` : ""}${r.staleCites ? ` ⚠ ${r.staleCites} stale cite(s)` : ""}`,
+      );
+    for (const i of f.improvements) console.log(`    ! open ${i.priority}: ${i.id} ${i.title}`);
+  }
+  if (gaps.length)
+    console.log(`  open knowledge gaps (does this change answer one?): ${gaps.map((g) => `"${g.q}"×${g.misses}`).join(" · ")}`);
+  console.log(
+    `→ engage ${engaged.length}/${engaged.length + skipped.length} note(s) (${direct.length} direct · ${fileHits.length} same-file` +
+      (skipped.length ? ` · ${skipped.length} governs-the-file-but-unrelated SKIPPED, listed in review.json` : "") +
+      `) · ${imps.length} open improvement(s)` +
+      (stale.length ? ` · ⚠ ${stale.length} stale-cite note(s) — verify before relying` : "") +
+      `\n  The judge rules on exactly the engaged set (rafa-review SOP): deep = body-worthy, triage = summary-only.`,
+  );
+}

package/package.json

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