@rafinery/cli 0.8.14 → 0.8.15

package/bin/rafa.mjs

@@ -135,10 +135,12 @@ Commands:
                        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 → the exact rules/
-                       improvements the change touches (.rafa/review.json + summary).
-                       The rafa-review SOP's judge then rules on precisely that list —
-                       generic "review this PR" never happens. Advisory; never blocks.
+                       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/skills/rafa-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rafa-review
-description: "rafa SOP — the brain-grounded review gate: `rafa review` computes the exact rules/improvements a diff touches (cite-intersection, zero LLM); 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."
+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)
@@ -16,34 +16,97 @@ 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):
+ranges ∩ the brain's cite graph (`get_code_context` per file), BOTH note kinds:
 
-- **◆ direct** — a changed line falls inside a rule's cited anchor range: the
-  code the rule stands on MOVED. Highest priority; also a staleness signal
+- **◆ 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 rule governs 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:
+For the work list ONLY — never the whole diff, never taste. Each data kind has
+its OWN question:
 
-1. Per **rule hit**: fetch the rule (`get_rule`, with `branch:` for the
-   working-set overlay) → does the diff still honor it? Judge against code +
-   rule, never against the author's claims. A `failure: silent` rule gets
-   extra scrutiny — that class never announces itself.
-2. Per **open improvement**: touched for better or worse? Fixed-in-passing →
+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).
-3. **The active task's Done-check** (from `get_active_plan`): does the diff
+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?
-4. Verdict: **PASS** or **ITERATE** with per-finding citations (rule id +
+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).
-5. Emit **`report_loop_event(category: "review-verdict", outcome:
+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.
 

package/lib/releases.mjs

@@ -264,19 +264,40 @@ 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:
-      "LOCAL-STATE EXCLUSION (zero-leak mirrors): the hydration sidecar + sensor " +
-      "queues (hydration.json · dirty/reflex/sensor-errors.jsonl · benchmark.demo.json " +
-      "· distill staging · *.theirs.md) are machine state, never knowledge — the " +
-      "post-commit brain hook now ENSURES the .rafa/.gitignore entries AND untracks " +
-      "anything an earlier window let git track (gitignore alone never untracks), so " +
-      "the next mirror commit cleans the branch. ensureBrainRepo's ignore list gains " +
-      "sensor-errors.jsonl + benchmark.demo.json. `rafa update` re-vendors the hook.",
+      "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",

package/lib/review.mjs

@@ -1,10 +1,12 @@
 // 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/playbooks/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 rules
-// against THESE lines.
+// 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]
 //
@@ -71,6 +73,50 @@ export function citeHits(citeLine, ranges) {
   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"))) {
@@ -88,6 +134,7 @@ export default async function review(args = []) {
 
   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",
@@ -106,18 +153,43 @@ export default async function review(args = []) {
       break; // one transport failure fails them all — say so, don't half-report
     }
     const fileRanges = ranges.get(path) ?? [];
-    const rules = (ctx.notes ?? []).map((n) => ({
-      id: n.id,
-      kind: n.kind,
-      title: n.title,
-      domain: n.domain,
-      line: n.line,
-      ...(n.failure ? { failure: n.failure } : {}),
-      hit: citeHits(n.line, fileRanges) ? "direct" : "file",
-    }));
+    // 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 (rules.length > 0 || improvements.length > 0)
-      out.push({ path, ranges: fileRanges, rules, improvements, relatedPlans: ctx.relatedPlans ?? [] });
+    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 = {
@@ -128,6 +200,7 @@ export default async function review(args = []) {
     ...(dropped > 0 ? { dropped } : {}),
     ...(unreachable ? { unreachable } : {}),
     files: out,
+    ...(gaps.length > 0 ? { openGaps: gaps } : {}),
   };
   writeFileSync(join(ROOT, ".rafa", "review.json"), JSON.stringify(report, null, 2) + "\n");
 
@@ -135,9 +208,12 @@ export default async function review(args = []) {
     console.log(JSON.stringify(report, null, 2));
     return;
   }
-  const direct = out.flatMap((f) => f.rules.filter((r) => r.hit === "direct"));
-  const fileHits = out.flatMap((f) => f.rules.filter((r) => r.hit === "file"));
+  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)` : ""),
@@ -149,12 +225,20 @@ export default async function review(args = []) {
   }
   for (const f of out) {
     console.log(`  ${f.path}`);
-    for (const r of f.rules)
-      console.log(`    ${r.hit === "direct" ? "◆" : "·"} ${r.id} [${r.domain}] ${r.title}${r.failure ? ` (failure: ${r.failure})` : ""}`);
+    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(
-    `→ ${direct.length} direct anchor hit(s) · ${fileHits.length} same-file rule(s) · ${imps.length} open improvement(s)` +
-      `\n  The judge rules on exactly these (rafa-review SOP): does the diff still honor each rule; does it satisfy the active task's Done-check.`,
+    `→ 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.14",
+  "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": {