@rafinery/cli 0.8.16 → 0.10.0

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

@@ -91,6 +91,24 @@ convention — see [RSC client boundary](/brain/rules/rsc-client-boundary.md)).
    performance · architecture · product · ops**. Weight the **silent** issues (directive 2):
    convention violations the brain documents, framework boundary breaches (e.g. RSC), missing
    authz, drifting contracts. The brain's conventions are your oracle for "what's a violation here."
+
+   **The architecture lens has a METHOD (wave 6)** — criteria adapted from the installed
+   `improve-codebase-architecture` skill (READ as criteria, never invoked — it is
+   `disable-model-invocation`; the method below stands whether or not the skill is installed):
+   - **Scope by heat, not by sweep** (YAGNI): unless the dev named a direction, walk
+     `git log --oneline` for the hot spots — churn is where depth pays; cold code waits.
+   - **Deep vs shallow judgment**: a module earns its interface when the interface is smaller
+     than what it hides. Bouncing between many small modules to follow one behavior, pure
+     functions extracted only for testability, and leaky seams are the friction signals.
+   - **The deletion test**: would deleting this module CONCENTRATE complexity somewhere honest,
+     or just smear it around? "Concentrates" marks a candidate.
+   - **Candidates are normal §3 improvement files** (zero schema change): before/after as body
+     prose + a `Confidence: Strong | Worth exploring | Speculative` body line; inside these
+     notes use the depth vocabulary — module · interface · implementation · seam · adapter ·
+     depth · leverage · locality — and keep it INSIDE the architecture lens (the rest of the
+     ledger speaks the repo's own language).
+   - **The big-bang guard is sovereign** (directive 1): a `Strong` candidate lands as its first
+     10-minute slice or a P2 backlog item — never a grand refactor plan.
 3. **Delegate security.** Run `pnpm audit` (dep CVEs). Recommend/run the **`security-review`**
    skill and semgrep/CodeQL if available. Record *tool* results as improvements; the LLM pass is
    observational only — never present it as an authoritative audit.
@@ -166,3 +184,7 @@ the ledger the nudge will read.
   beyond the deterministic cite-check.
 - Debt-score weighting calibrated from real runs.
 - Per-lens diverse validators (a security lens checked by a security-minded validator).
+- A visual before/after artifact for architecture candidates (the
+  improve-codebase-architecture skill's HTML report) — deliberately SKIPPED for now: its
+  CDN-loaded Tailwind/Mermaid + temp-file-and-open mechanics violate the deterministic,
+  no-network posture; the ledger IS the report.

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

@@ -44,7 +44,12 @@ at the fix. This is platform DNA: **leverage what's present; never reinvent it.*
 
 The engine ([`lib/leverage/engine.mjs`](../../../packages/cli/lib/leverage/engine.mjs)) gathers
 light, tool-agnostic repo signals (`repoContext`: stack deps, `.env` files + whether they're
-ignored, declared MCP servers), then runs every **detected** adapter and ranks the tips.
+ignored, declared MCP servers, **and the harness-neutral `.agents/skills/` inventory +
+skill-dependency status (wave 6)** — `.agents/` is ONE convention Claude Code · Codex ·
+Cursor all read, so it lives in the engine, never inside a per-toolchain adapter), then runs
+every **detected** adapter and ranks the tips. The engine emits its own rafa-level tip —
+`skill-deps-missing` (`P2`, fix = `rafa update --skills`) — because rafa's declared skill
+dependencies are harness-neutral by definition.
 
 Each adapter implements one contract ([`lib/leverage/adapters/index.mjs`](../../../packages/cli/lib/leverage/adapters/index.mjs)):
 

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

@@ -41,6 +41,34 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
   A plan whose children lack Done-checks is REJECTED here — compile never parses
   bodies (invariant #3); this gate is prism's.
 
+  **The grill pass (wave 6 — tier-bounded adversarial interview).** On top of
+  the two invariants, prism GRILLS the draft — the same procedure the installed
+  `grilling` skill carries (`.agents/skills/grilling/SKILL.md`; prism READS it
+  as criteria when installed, and this SOP carries the method regardless —
+  never invoked mid-validation, per its card). Per task, up the probe ladder:
+  **grounding** (which claims rest on assumption? name it, demand its
+  evidence — a session-fact id counts, vibes don't) · **unstated dependencies**
+  (what must exist for this task that no `blocked_by` declares?) · **vacuous
+  Done-check** (can it pass while the feature is broken? a check that
+  recomputes its expectation the way the code will, or that a no-op satisfies,
+  is TAUTOLOGICAL — criteria per the tdd skill's anti-patterns when installed)
+  · **YAGNI** (does the INTENT need this task, or did thoroughness invent it?).
+  Budget scales with the task's `validation_tier`: **light** = the two
+  invariants only (exactly today) · **standard** = ≤2 probes per task, ≤10 per
+  plan · **full** = the complete grilling procedure (one probe at a time,
+  survives-three-consecutive ends it). Every probe finding cites the plan line
+  it hits — an uncited probe is dropped, and findings feed the existing
+  REJECT-with-cited-reasons loop. Plan-lite drafts grill at light.
+
+  **The seam ritual (wave 6 — TDD's consent moment, no new prompt).** For code
+  tasks in TDD-eligible repos (the tdd skill installed + a test harness
+  detected — the build SOP's gate), every LEAF's `## Done-check` NAMES the seam
+  under test: *"`<runner>` on `<test-file>` at seam `<the public interface>`
+  exits 0"*. Seams come from recall (the brain's contracts/flows) — never
+  invented at build time. The plan-approval summary lists the seams as their
+  own line, so **the dev approving the plan IS the tdd skill's "confirm seams
+  with the user" step** — consent rides the existing approval gate.
+
 ## Procedure
 
 1. **Staleness check** — compare the platform envelope's `brainForSha` against the
@@ -58,7 +86,14 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
    carries the glimpse fields — `title` (what) · `description` (why) ·
    `approach` (how, one line) · `assignee` when known · `blocked_by` for
    intra-plan dependencies (a dependency IS a blocker; blocked is DERIVED,
-   never a status) · optional `priority` 0–4 / `estimate`. Every LEAF carries a
+   never a status) · optional `priority` 0–4 / `estimate` ·
+   **`validation_tier` (wave 5 — rigor scales with blast radius, not with
+   process): assign per LEAF from what the task touches — contract/state-shape/
+   graph surface → `full` · pure types/docs/leaf-UI → `light` · everything else
+   → `standard` (the default when omitted). The tier bounds prism's
+   RE-DERIVATION DEPTH only; the Done-check gate itself never relaxes, and the
+   tier rides the task's loop events so sage can audit the tiering against
+   escaped-bug reality instead of anyone guessing.** Every LEAF carries a
    `## Done-check`. The blast radius goes on the EPIC's `domains:` — it rides
    `push_plan` and the platform renders the plan's brain slice beside it.
    ADR material (alternatives, risks, non-goals) lives in the epic body AND

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

@@ -104,8 +104,16 @@ its OWN question:
 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).
+   file:line). **Severity rides every finding (wave 6 — the
+   requesting-code-review taxonomy): `Critical (Must Fix)` · `Important
+   (Should Fix)` · `Minor (Nice to Have)`. ITERATE iff ≥1 Critical or
+   Important; Minor NEVER flips the verdict** (advisory noise must not
+   masquerade as a gate — and "not everything is Critical" is the taxonomy's
+   own first rule). Findings feed atlas (validate-and-correct — atlas fixes,
+   the judge re-checks; the reviewer never edits). The fresh-context reviewer
+   discipline the installed requesting-code-review skill prescribes
+   (precisely-crafted context, never the session's history) IS rafa's spawn
+   model already — confirmation, not new machinery.
 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.
@@ -124,3 +132,9 @@ its OWN question:
 - 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.
+- **Mutating anything while judging** (wave 6, from the code-reviewer's
+  read-only rule): the review never touches the working tree, the index, HEAD,
+  or branch state — inspect another revision via `git show`/a throwaway
+  worktree, never a checkout on this one.
+- **Severity inflation** — a verdict where everything is Critical has stopped
+  discriminating; that is itself a review failure.

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

@@ -58,8 +58,14 @@ boundary; its product is a ledger reviewed *later*, never a live nudge. No mid-f
 ### 2. evidence-cited — SHAPES only, via `get_loop_events`
 Every learning cites its evidence, and evidence is **loop-event shapes and categories only**:
 verdict TYPES, gap CLASSES, miss TAXONOMIES, and the aggregate counts/rates over them — read via
-`get_loop_events` (category ∈ `prism-verdict | gate-result | reflex-outcome | distill-refutation`;
-outcome enum per category; `subject` is a shape reference, never content). A learning with no
+`get_loop_events` (category ∈ `prism-verdict | gate-result | reflex-outcome | distill-refutation |
+review-verdict`; outcome enum per category; `subject` is a shape reference, never content). Wave 5
+enriched every event with THREE new analysis dimensions — split every rate by them: **verification
+method** (`static` vs `live` — a PASS-rate that holds only on static rulings is a coverage gap, not
+health), **actor envelope** (model · agent@version · runner — attribute a miss class to the agent
+structure that produced it), and **tier** (`light|standard|full` — audit the tiering itself: a
+light-tier task class that later produced escaped bugs is evidence the planner's tier rule needs a
+diff; a full-tier class whose findings-density is ~zero is evidence of ceremony). A learning with no
 event-shape evidence is a hunch — drop it. sage never cites a customer artifact (no `file:line`
 into customer code; that field does not exist in the schema below).
 

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

@@ -155,7 +155,10 @@ retrieval index. Bodies read like a senior engineer explaining that one concept
 3b. **Toolbox inventory** [deterministic] — ratified 2026-07-12: the REPO toolbox is a
    first-class brain domain (`toolbox`). Run `npx @rafinery/cli leverage --json` (the
    deterministic extractor) and author cited notes for the committed toolbox — skills
-   (`.claude/skills/*/SKILL.md` name+description), commands, `.mcp.json` servers,
+   (`.claude/skills/*/SKILL.md` name+description), **the harness-neutral
+   `.agents/skills/*/SKILL.md` (wave 6 — the `agentSkills` block in the JSON: one
+   convention Claude Code · Codex · Cursor all read; consent-installed by
+   `rafa update`)**, commands, `.mcp.json` servers,
    granted permissions — cites into the config files themselves (contract §2; they are
    citable file:line). This makes the toolbox recallable through the SAME MCP surface
    as all knowledge and refreshable like any note. Personal `~/.claude/` is NEVER

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"];
+  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 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

@@ -248,22 +248,24 @@ export default async function checkpoint() {
   // durable mirror of the dev's current copies; .theirs.md files are ignored.)
   mirrorTail(ROOT, branch);
 
-  // prism-verdict backstop (harness-arc wave 0): gate-result/reflex-outcome are
-  // emitted mechanically by the CLI, but prism verdicts are LLM judgments only
-  // the session can report. The checkpoint beat — the SOP's own emit moment —
-  // checks the store and reminds while it's still empty. Best-effort, one line.
+  // prism-verdict backstop (harness-arc wave 0) + the sage-due cache (wave
+  // 5.5): the SAME single best-effort call, enriched. It now fetches recent
+  // events (no category filter) and caches their SHAPES locally
+  // (.rafa/loop-events-tail.json — category/at only, subjects excluded) so the
+  // SessionStart digest computes "sage due" with ZERO added platform calls.
+  // The old prism-verdict reminder derives from the same response.
   try {
-    const evts = await callTool(ROOT, "get_loop_events", {
-      category: "prism-verdict",
-      limit: 1,
-    });
-    if ((evts.events ?? []).length === 0)
+    const { writeLoopCache } = await import("./loop-cache.mjs");
+    const evts = await callTool(ROOT, "get_loop_events", { limit: 200 });
+    const events = evts.events ?? [];
+    writeLoopCache(ROOT, { fetchedAt: new Date().toISOString(), events });
+    if (events.filter((e) => e.category === "prism-verdict").length === 0)
       console.log(
         "  ℹ no prism-verdict loop events recorded yet — the build SOP emits " +
           "report_loop_event(prism-verdict, PASS|ITERATE, <task id>) at each Done-check ruling.",
       );
   } catch {
-    /* unprovisioned/unreachable — the reminder is best-effort */
+    /* unprovisioned/unreachable — the reminder + cache are best-effort */
   }
   if (conflicts) process.exit(2);
 }

package/lib/distiller/doctrine.mjs

@@ -164,22 +164,11 @@ export function citesGround(content, cwd = process.cwd()) {
 }
 
 // Rewrite a survivor's frontmatter `cites:` DSL so a re-grounded citation points
-// at where the token NOW lives on main — otherwise banking it as authored would
-// fail the checker (the stale line no longer resolves). Mechanical string
-// substitution on the exact `file:line :: token` locator; untouched lines pass
-// through. Returns the rewritten content.
-export function rewriteCites(content, regroundings) {
-  let out = content;
-  for (const r of regroundings ?? []) {
-    const fromLoc = r.cite.loc; // file:line[-end]
-    const toLoc = r.to.loc; // file:line
-    // Match the DSL line `  - <fromLoc> :: <token>` and swap the locator only.
-    const esc = fromLoc.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const re = new RegExp(`(-\\s+)${esc}(\\s*::\\s*)`, "g");
-    out = out.replace(re, `$1${toLoc}$2`);
-  }
-  return out;
-}
+// at where the token NOW lives on main. MOVED to the gate (wave 5.3) so
+// `verify-citations --fix` can use it without an import cycle (this module
+// imports the gate's primitives, never the reverse); re-exported here so the
+// doctrine's callers keep their import path.
+export { rewriteCites } from "../gate/verify-citations.mjs";
 
 // ── folding N branch working sets into ONE run (case 1 · case 5) ────────────────
 // Input: [{ branch, capturedAtSha, mergedAt, files: [{ path, content }] }].

package/lib/doctor.mjs

@@ -79,7 +79,25 @@ export async function runDoctor(ROOT = process.cwd()) {
     }
   }
 
-  // 3 · the round-trip — the heartbeat must LAND, not just send. A recorded
+  // 3 · capabilities — every STAMPED-installed skill dependency re-verified
+  // against disk (wave 6): dir present, frontmatter parses, hashes match the
+  // bundle, license file where required. Declined/never-offered = silent.
+  {
+    const { verifyInstalled, neededSkills } = await import("./skill-deps.mjs");
+    const results = verifyInstalled(ROOT);
+    const pending = neededSkills(ROOT).length;
+    if (results.length || pending) {
+      console.log("• capabilities (skill dependencies)");
+      for (const r of results) {
+        if (r.ok) ok(`${r.name} installed + verified`);
+        else bad(`${r.name} ${r.reason}`, "re-install: `rafa update --skills`");
+      }
+      if (pending)
+        console.log(`  · ${pending} declared dep(s) not installed — offer: \`rafa update --skills\``);
+    }
+  }
+
+  // 4 · the round-trip — the heartbeat must LAND, not just send. A recorded
   // response proves key + url + repo scoping + the platform handler, end to end.
   console.log("• platform round-trip");
   if (provisioned) {

package/lib/facts.mjs

@@ -0,0 +1,130 @@
+// rafa facts — the session-facts surface (wave 5.4, memoized verification).
+//
+//   rafa facts                        list facts + staleness (the conductor's read)
+//   rafa facts --json                 machine read (spawn-prompt slices)
+//   rafa facts add --claim="…" --command="…" --exit=0 [--depends=a,b] [--tool=…]
+//                                     bank ONE verified fact (stamps HEAD sha)
+//   rafa facts invalidate <SF-n>      drop a fact deliberately
+//   rafa facts prune --stale          drop every mechanically-stale fact
+//
+// A fact is never an assumption: `add` REQUIRES the command + exit code that
+// proved it, and staleness is mechanical (dependsOn ∩ git diff since the
+// verifying sha, working tree included). Subagents read first and cite
+// "SF-<n> unchanged" instead of re-deriving — prism's bounded exception.
+
+import { execSync } from "node:child_process";
+import {
+  factsPath,
+  nextFactId,
+  readFacts,
+  staleFacts,
+  validateFact,
+  writeFacts,
+} from "./session-facts.mjs";
+
+const die = (m) => {
+  console.error(`✗ ${m}`);
+  process.exit(1);
+};
+
+export default async function facts(args = []) {
+  const ROOT = process.cwd();
+  const arg = (k) => {
+    const m = args.find((a) => a.startsWith(`--${k}=`));
+    return m ? m.slice(k.length + 3) : undefined;
+  };
+  const [sub, subArg] = args.filter((a) => !a.startsWith("-"));
+
+  if (sub === "add") {
+    const claim = arg("claim");
+    const command = arg("command");
+    const exit = arg("exit");
+    if (!claim || !command || exit === undefined)
+      die('usage: rafa facts add --claim="…" --command="…" --exit=0 [--depends=a,b]');
+    let sha = "";
+    try {
+      sha = execSync("git rev-parse HEAD", {
+        cwd: ROOT,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+    } catch {
+      die("not a git repo — session facts anchor to a verifying sha");
+    }
+    const doc = readFacts(ROOT);
+    const fact = {
+      id: nextFactId(doc),
+      claim,
+      evidence: { command, exitCode: Number(exit) },
+      verifiedAtSha: sha,
+      dependsOn: (arg("depends") ?? "").split(",").map((s) => s.trim()).filter(Boolean),
+      at: new Date().toISOString(),
+    };
+    const bad = validateFact(fact);
+    if (bad) die(bad);
+    doc.facts.push(fact);
+    writeFacts(ROOT, doc);
+    console.log(
+      `✓ ${fact.id} banked — "${claim}"\n` +
+        `  evidence: \`${command}\` → exit ${fact.evidence.exitCode} @ ${sha.slice(0, 7)}` +
+        (fact.dependsOn.length
+          ? `\n  citable while untouched: ${fact.dependsOn.join(", ")}` +
+            (fact.dependsOn.every((p) => !p.endsWith("/"))
+              ? "\n  note: invalidation is NOT transitive — if this fact spans a subsystem, declare the" +
+                "\n  enclosing directory (e.g. --depends=src/) so indirect changes stale it. Breadth is the conservative move."
+              : "")
+          : "\n  no dependsOn — environment-shaped; invalidate by hand when the env changes"),
+    );
+    return;
+  }
+
+  if (sub === "invalidate") {
+    if (!subArg) die("usage: rafa facts invalidate <SF-n>");
+    const doc = readFacts(ROOT);
+    const before = doc.facts.length;
+    doc.facts = doc.facts.filter((f) => f.id !== subArg);
+    if (doc.facts.length === before) die(`no fact ${subArg} (see \`rafa facts\`)`);
+    writeFacts(ROOT, doc);
+    console.log(`✓ ${subArg} invalidated`);
+    return;
+  }
+
+  if (sub === "prune") {
+    if (!args.includes("--stale")) die("usage: rafa facts prune --stale");
+    const doc = readFacts(ROOT);
+    const stale = new Set(staleFacts(ROOT, doc).map((s) => s.id));
+    const before = doc.facts.length;
+    doc.facts = doc.facts.filter((f) => !stale.has(f.id));
+    writeFacts(ROOT, doc);
+    console.log(`✓ pruned ${before - doc.facts.length} stale fact(s) · ${doc.facts.length} remain`);
+    return;
+  }
+
+  // Default: list.
+  const doc = readFacts(ROOT);
+  if (args.includes("--json")) {
+    console.log(JSON.stringify({ ...doc, stale: staleFacts(ROOT, doc) }, null, 2));
+    return;
+  }
+  if (doc.facts.length === 0) {
+    console.log(
+      "no session facts banked — `rafa facts add` after verifying something expensive\n" +
+        `  (${factsPath(ROOT).replace(ROOT + "/", "")} · read-first for every spawned agent)`,
+    );
+    return;
+  }
+  const stale = new Map(staleFacts(ROOT, doc).map((s) => [s.id, s.reason]));
+  for (const f of doc.facts) {
+    const s = stale.get(f.id);
+    console.log(
+      `${s ? "!" : "✓"} ${f.id} — ${f.claim}\n` +
+        `    \`${f.evidence.command}\` → exit ${f.evidence.exitCode} @ ${f.verifiedAtSha.slice(0, 7)}` +
+        (s ? `\n    STALE: ${s}` : ""),
+    );
+  }
+  const staleCount = stale.size;
+  console.log(
+    `${doc.facts.length} fact(s)` +
+      (staleCount ? ` · ${staleCount} STALE — re-verify or \`rafa facts prune --stale\`` : " · all fresh"),
+  );
+}

package/lib/gate/compile.mjs

@@ -579,6 +579,15 @@ export function runCompile(argv = []) {
         !(Number.isInteger(data.estimate) && data.estimate >= 0)
       )
         fail(path, "estimate", "optional · non-negative int (points)");
+      if (
+        data.validation_tier !== undefined &&
+        !["light", "standard", "full"].includes(data.validation_tier)
+      )
+        fail(
+          path,
+          "validation_tier",
+          "optional · light|standard|full — bounds prism re-derivation depth ONLY (the Done-check gate never relaxes)",
+        );
       if (data.external !== undefined) {
         const ex = data.external;
         if (
@@ -618,6 +627,9 @@ export function runCompile(argv = []) {
           : {}),
         ...(Number.isInteger(data.priority) ? { priority: data.priority } : {}),
         ...(Number.isInteger(data.estimate) ? { estimate: data.estimate } : {}),
+        ...(["light", "standard", "full"].includes(data.validation_tier)
+          ? { validationTier: data.validation_tier }
+          : {}),
         ...(typeof data.branch === "string" && data.branch !== ""
           ? { branch: data.branch }
           : {}),

package/lib/gate/verify-citations.mjs

@@ -119,6 +119,31 @@ function gitLsGlob(glob, cwd = process.cwd()) {
   }
 }
 
+// EXPORTED — moved here from distiller/doctrine.mjs (wave 5.3; doctrine
+// re-exports it) so the gate's `--fix` can use it without an import cycle
+// (doctrine imports citeResolves/gitGrep FROM this file). Rewrites frontmatter
+// `cites:` DSL locators so a re-grounded citation points at where the token
+// NOW lives. Token-anchored when the cite carries one — two cites sharing
+// file:line with different tokens must not clobber each other; falls back to
+// the locator-only match for callers that pass no token.
+export function rewriteCites(content, regroundings) {
+  let out = content;
+  for (const r of regroundings ?? []) {
+    const fromLoc = r.cite.loc; // file:line[-end]
+    const toLoc = r.to.loc; // file:line
+    const esc = fromLoc.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (r.cite.token !== undefined) {
+      const escTok = String(r.cite.token).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const re = new RegExp(`(-\\s+)${esc}(\\s*::\\s*${escTok}\\s*)$`, "gm");
+      out = out.replace(re, `$1${toLoc}$2`);
+    } else {
+      const re = new RegExp(`(-\\s+)${esc}(\\s*::\\s*)`, "g");
+      out = out.replace(re, `$1${toLoc}$2`);
+    }
+  }
+  return out;
+}
+
 // EXPORTED (refinery-arc-p1-distiller): the doctrine validates a candidate's
 // citations against merged main through the exact same predicate the gate uses,
 // so "resolves for the checker" and "resolves for arbitration" can never drift.
@@ -160,6 +185,14 @@ 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
+  // --fix (wave 5.3): heal DRIFTED line-cites in place — a failing cite whose
+  // token still lives at exactly ONE grep site gets its locator rewritten, then
+  // the whole verification re-runs clean. gone (0 hits) and ambiguous (>1)
+  // stay untouched and keep failing — the checker never guesses.
+  const FIX = argv.includes("--fix");
+  const fixDrifted = []; // { notePath, cite: {loc, token}, to: {loc} }
+  const fixGone = []; // { note, loc, token }
+  const fixAmbiguous = []; // { note, loc, token, hits }
 
   // --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
@@ -264,7 +297,22 @@ export function runVerifyCitations(argv = []) {
     // RESOLUTION
     for (const ct of cites) {
       const { ok, reason } = citeResolves(ct.file, ct.start, ct.end, ct.token);
-      resolution.push({ note: rel, loc: `${ct.file}:${ct.start}${ct.end !== ct.start ? "-" + ct.end : ""}`, token: ct.token, ok, reason });
+      const loc = `${ct.file}:${ct.start}${ct.end !== ct.start ? "-" + ct.end : ""}`;
+      resolution.push({ note: rel, loc, token: ct.token, ok, reason });
+      if (!ok && FIX) {
+        // Classify with the gate's OWN primitives — deliberately NOT
+        // arbitrateCite, which takes hits[0] blindly; the gate never guesses.
+        const hits = gitGrep(ct.token);
+        if (hits.length === 1)
+          fixDrifted.push({
+            notePath: note,
+            cite: { loc, token: ct.token },
+            to: { loc: `${hits[0].file}:${hits[0].line}` },
+            ranged: ct.end !== ct.start,
+          });
+        else if (hits.length === 0) fixGone.push({ note: rel, loc, token: ct.token });
+        else fixAmbiguous.push({ note: rel, loc, token: ct.token, hits: hits.length });
+      }
     }
 
     // COMPLETENESS
@@ -355,6 +403,35 @@ export function runVerifyCitations(argv = []) {
     }
   }
 
+  // ── --fix apply + re-run (wave 5.3) ────────────────────────────────────────
+  if (FIX && (fixDrifted.length || fixGone.length || fixAmbiguous.length)) {
+    const byNote = new Map();
+    for (const f of fixDrifted) {
+      if (!byNote.has(f.notePath)) byNote.set(f.notePath, []);
+      byNote.get(f.notePath).push(f);
+    }
+    for (const [notePath, fixes] of byNote) {
+      const before = readFileSync(notePath, "utf8");
+      const after = rewriteCites(before, fixes);
+      if (after !== before) writeFileSync(notePath, after);
+    }
+    for (const f of fixDrifted)
+      console.log(
+        `  ✓ fixed drifted ${f.cite.loc} → ${f.to.loc} :: ${f.cite.token}` +
+          (f.ranged ? "  (range collapsed to the found line)" : ""),
+      );
+    for (const g of fixGone)
+      console.log(`  ✗ gone ${g.loc} :: ${g.token} — token nowhere in the tree, not fixable [${g.note}]`);
+    for (const a2 of fixAmbiguous)
+      console.log(`  · ambiguous ${a2.loc} :: ${a2.token} — ${a2.hits} grep sites, never guessed [${a2.note}]`);
+    console.log(
+      `--fix: ${fixDrifted.length} drifted healed · ${fixGone.length} gone · ${fixAmbiguous.length} ambiguous (untouched)`,
+    );
+    // Re-run WITHOUT --fix so the report + exit code reflect the healed state
+    // (gone/ambiguous cites still fail — honestly).
+    return runVerifyCitations(argv.filter((a2) => a2 !== "--fix"));
+  }
+
   const rFail = resolution.filter((r) => !r.ok);
   const cFail = completeness.filter((r) => !r.ok);
   const pFail = policy.filter((r) => !r.ok);

package/lib/hydrate.mjs

@@ -22,6 +22,7 @@ import { execSync } from "node:child_process";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { callTool } from "./mcp-client.mjs";
+import { citeResolves, gitGrep } from "./gate/verify-citations.mjs";
 import {
   hashOf,
   materializeImprovement,
@@ -35,6 +36,42 @@ const die = (m) => {
   process.exit(1);
 };
 
+// Wave 5.3 — hydrate-time citation re-basing. Served cites were authored
+// against the brain's base sha; the LOCAL checkout may be newer. Before
+// materializing, re-ground each {file, line, token} with the gate's own
+// primitives: resolves → keep; exactly ONE grep hit → re-cite there;
+// gone/ambiguous → keep the original + a ⚠ (the push gate still catches it).
+// Fail-soft by construction: any error (not a git repo, missing file) keeps
+// the served original untouched. Exported for tests.
+export function rebaseCites(cites, cwd = process.cwd()) {
+  const out = [];
+  const notes = [];
+  for (const c of cites ?? []) {
+    try {
+      const [startRaw, endRaw] = String(c.line).split("-");
+      const start = Number(startRaw);
+      const end = Number(endRaw ?? startRaw);
+      if (!Number.isFinite(start) || citeResolves(join(cwd, c.file), start, end, c.token).ok) {
+        out.push(c);
+        continue;
+      }
+      const hits = gitGrep(c.token, cwd);
+      if (hits.length === 1) {
+        out.push({ ...c, file: hits[0].file, line: hits[0].line });
+        notes.push(`✓ re-based ${c.file}:${c.line} → ${hits[0].file}:${hits[0].line} :: ${c.token}`);
+      } else {
+        out.push(c);
+        notes.push(
+          `⚠ ${c.file}:${c.line} did not re-base (${hits.length === 0 ? "gone" : `ambiguous — ${hits.length} sites`}) — served line may be stale`,
+        );
+      }
+    } catch {
+      out.push(c);
+    }
+  }
+  return { cites: out, notes };
+}
+
 export default async function hydrate(args = []) {
   const ROOT = process.cwd();
 
@@ -94,6 +131,14 @@ export default async function hydrate(args = []) {
     die(e instanceof Error ? e.message : String(e));
   }
   const brainForSha = payload.envelope?.brainForSha ?? null;
+  // Wave 5.3 — arrive pre-healed: re-base served cites against THIS checkout
+  // before the file is written (drifted-but-unique tokens re-cite; gone/
+  // ambiguous keep the original + a ⚠ so nothing is ever guessed).
+  if (Array.isArray(payload.cites) && payload.cites.length > 0) {
+    const { cites, notes } = rebaseCites(payload.cites, ROOT);
+    payload.cites = cites;
+    for (const n of notes) console.log(`  ${n}`);
+  }
   const rel =
     kind === "improvement"
       ? materializeImprovement(ROOT, payload, brainForSha)

package/lib/init.mjs

@@ -131,6 +131,13 @@ export default async function init(args) {
     for (const u of r.updated) console.log(`  ✓ repo MCPs → ${u}`);
   }
 
+  // Wave 6 — offer the declared skill dependencies (consent-gated, verified,
+  // stamped; declined remembered). .agents/skills is COMMITTED dev toolbox.
+  {
+    const { installSkillDeps } = await import("./skill-deps.mjs");
+    await installSkillDeps(TARGET, { args });
+  }
+
   // Keep the brain out of the code repo's diffs; keep the per-dev MCP key out of git.
   const ensureIgnored = (line, label) => {
     const gi = join(TARGET, ".gitignore");
@@ -200,7 +207,8 @@ export default async function init(args) {
 
   console.log(
     `\n✓ Provisioned.\n\nNext steps:\n` +
-      "  1. Commit the vendored files (agents, /rafa command, skills, contract, rafa.json)\n" +
+      "  1. Commit the vendored files (agents, /rafa command, skills, contract, rafa.json,\n" +
+      "     and .agents/skills/ if you installed the skill dependencies)\n" +
       "     — protected-main teams: via a normal MR. The brain remote lives in rafa.json,\n" +
       "     so any teammate's clone bootstraps with  npx rafa pull  (no init needed).\n" +
       "  2. Restart Claude Code in this repo (reload the /rafa command + agents + skills" +