@rafinery/cli 0.8.16 → 0.11.0

package/lib/distiller/schema-ladder.mjs

@@ -0,0 +1,186 @@
+// The schema ladder (0.11.0 — schema-aware reconciliation, owner's 4-case
+// doctrine, 2026-07-25). Distillation is where knowledge from two lineages
+// meets, so it is ALSO where brain schema versions meet — the reconciler
+// resolves the version lattice BEFORE any claim-level judging, and the merged
+// result always lands on the newest schema the RUNNER understands:
+//
+//   1. target < source            → REWRITE-TARGET: the whole target brain
+//      lifts to the newer schema (the incoming side already speaks it).
+//   2. target > source            → UPGRADE-SOURCE: incoming old-schema
+//      candidates lift into the target's newer schema before judging.
+//   3. target == source < latest  → REWRITE-MERGED: both sides lift; the
+//      merged target is a full rewrite onto the latest schema.
+//   4. target == source == latest → DIFF: the happy flow, exactly today.
+//   ∅. either side > latest       → ABORT LOUDLY: a newer CLI authored this;
+//      this runner cannot judge a schema it does not know — update the
+//      runner, NEVER downgrade knowledge.
+//
+// Every non-abort mode converges in ONE pass: toVersion is always the
+// runner's latest (which case 1/2's higher side already equals or precedes —
+// the runner can never know less than what it authored). Transforms are
+// REGISTERED per step (v(N-1)→vN) in LADDER below; a missing step throws —
+// the ladder never guesses a schema (no assumed values). v1 is the baseline
+// and the only schema in existence today, so the registry ships empty: this
+// module is the SEAM, proven by tests, that makes a future v2 a one-entry
+// change instead of a migration crisis.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+// Per-step, PER-OKF-TYPE transforms (owner 2026-07-26: each file class has its
+// own shape in the contract's type registry, so each ladder step declares each
+// class EXPLICITLY):
+//
+//   LADDER[2] = {
+//     describe: "what v2 changes",
+//     rule: (content) => content2,     // a real shape change for rules
+//     playbook: "unchanged",           // EXPLICIT identity — visible, auditable
+//     improvement: (content) => …,
+//   }
+//
+// Only the three DURABLE knowledge classes ladder (rule · playbook ·
+// improvement — the classes distillation judges and the brain keeps). Derived/
+// generated files (coverage, checklist, ledger, reconciliation reports,
+// manifest) are NEVER migrated — their producers regenerate them at the new
+// schema. A step missing a class entry is a LOUD error, not implicit identity:
+// "unchanged" must be declared, never assumed. Every applied step (identity
+// included) re-stamps the note's own `schemaVersion:` line.
+export const LADDER = {};
+
+export const LADDER_CLASSES = ["rule", "playbook", "improvement"];
+
+// Class resolution chain (owner 2026-07-26): DIRECTORY first — inside rafa's
+// transport the path is governed identity (the CAS row key, the registry
+// glob, the hydrate target; it cannot drift without becoming a different
+// row) — then the PORTABLE filename suffix (`.rule.md` · `.playbook.md` ·
+// `.improvement.md`), which travels WITH a file that leaves the canonical
+// tree (foreign OKF bundles, out-of-context shares) while staying outside
+// the corruptible content. When BOTH are present they must AGREE — a
+// contradiction throws loudly, never a guess. Returns null for non-laddered
+// paths (intent records, reports, …) — those pass through untouched.
+const SUFFIX_CLASS = {
+  ".rule.md": "rule",
+  ".playbook.md": "playbook",
+  ".improvement.md": "improvement",
+};
+export function classOf(path) {
+  const p = String(path).replace(/\\/g, "/");
+  const byDir = p.includes("brain/rules/")
+    ? "rule"
+    : p.includes("brain/playbooks/")
+      ? "playbook"
+      : p.includes("improve/improvements/")
+        ? "improvement"
+        : null;
+  const bySuffix =
+    Object.entries(SUFFIX_CLASS).find(([s]) => p.endsWith(s))?.[1] ?? null;
+  if (byDir && bySuffix && byDir !== bySuffix)
+    throw new Error(
+      `schema ladder: directory class "${byDir}" contradicts filename class "${bySuffix}" (${p}) — ` +
+        "fix the file's home or its name; the ladder never guesses",
+    );
+  return byDir ?? bySuffix;
+}
+
+// A note's OWN declared schema (first-fence `schemaVersion:`). Default 1 — the
+// founding schema, same convention as stampedVersions defaulting to the first
+// release (a pre-stamp file predates versioning, it isn't unversioned).
+export function noteSchemaVersion(content) {
+  if (typeof content !== "string" || !content.startsWith("---")) return 1;
+  const end = content.indexOf("\n---", 3);
+  const fm = end === -1 ? content : content.slice(0, end);
+  const m = fm.match(/^schemaVersion:\s*(\d+)\s*$/m);
+  return m ? Number(m[1]) : 1;
+}
+
+const NOTE_DIRS = ["brain/rules", "brain/playbooks", "improve/improvements"];
+
+export function walkBrainNotes(rafaDir) {
+  const out = [];
+  const walk = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const e of readdirSync(dir)) {
+      const p = join(dir, e);
+      if (statSync(p).isDirectory()) walk(p);
+      else if (e.endsWith(".md") && !e.startsWith("_") && !e.endsWith(".theirs.md"))
+        out.push(p);
+    }
+  };
+  for (const d of NOTE_DIRS) walk(join(rafaDir, d));
+  return out;
+}
+
+// The TARGET brain's schema: manifest.json first (the compiled truth), else
+// the max over its notes' own declarations, else the founding schema.
+export function brainSchemaVersion(rafaDir) {
+  try {
+    const m = JSON.parse(readFileSync(join(rafaDir, "manifest.json"), "utf8"));
+    if (Number.isInteger(m.schemaVersion)) return m.schemaVersion;
+  } catch {
+    /* no manifest — fall through to the notes */
+  }
+  const versions = walkBrainNotes(rafaDir).map((f) =>
+    noteSchemaVersion(readFileSync(f, "utf8")),
+  );
+  return versions.length ? Math.max(...versions) : 1;
+}
+
+// The SOURCE side's schema: the max over the incoming candidates' own
+// declarations (a working set may be mixed if it straddled an upgrade).
+export function sourceSchemaVersion(contents) {
+  const versions = (contents ?? []).map(noteSchemaVersion);
+  return versions.length ? Math.max(...versions) : 1;
+}
+
+// The lattice. Returns {mode, toVersion, rewriteTarget, upgradeSource, reason}.
+export function resolveSchemaPlan({ target, source, latest }) {
+  if (target > latest || source > latest)
+    return {
+      mode: "abort-newer-than-runner",
+      toVersion: null,
+      rewriteTarget: false,
+      upgradeSource: false,
+      reason:
+        `brain schema v${Math.max(target, source)} is NEWER than this runner's v${latest} — ` +
+        "a newer CLI authored it. Update @rafinery/cli and re-run; knowledge is never downgraded.",
+    };
+  const base = { toVersion: latest, rewriteTarget: target < latest, upgradeSource: source < latest };
+  if (target < source)
+    return { mode: "rewrite-target", ...base, reason: `target v${target} < source v${source} — full target rewrite onto v${latest}` };
+  if (source < target)
+    return { mode: "upgrade-source", ...base, reason: `source v${source} < target v${target} — incoming candidates lift into v${latest}` };
+  if (target < latest)
+    return { mode: "rewrite-merged", ...base, reason: `both sides v${target} < runner v${latest} — merged result rewrites onto v${latest}` };
+  return { mode: "diff", ...base, reason: `both sides already v${latest} — plain diff reconcile` };
+}
+
+const stampVersion = (content, v) =>
+  content.replace(/^schemaVersion:\s*\d+\s*$/m, `schemaVersion: ${v}`);
+
+// Lift ONE note of ONE class from its own declared version to `to`, one
+// registered step at a time. A missing step OR a missing class entry within a
+// step is a loud error, never a guess; the explicit "unchanged" is the only
+// legal identity, and even it re-stamps the note's schemaVersion line.
+export function applyLadder(content, to, cls) {
+  if (!LADDER_CLASSES.includes(cls))
+    throw new Error(
+      `schema ladder: "${cls}" is not a laddered class (${LADDER_CLASSES.join("|")}) — ` +
+        "derived/generated files regenerate at the new schema, they never migrate",
+    );
+  let from = noteSchemaVersion(content);
+  let out = content;
+  while (from < to) {
+    const step = LADDER[from + 1];
+    const t = step?.[cls];
+    if (t === undefined)
+      throw new Error(
+        `schema ladder: no registered ${cls} transform v${from}→v${from + 1} — every step ` +
+          'declares every class (a function, or the EXPLICIT "unchanged"); ' +
+          "update @rafinery/cli to a release that ships it (the ladder never guesses a schema)",
+      );
+    out = t === "unchanged" ? out : t(out);
+    out = stampVersion(out, from + 1);
+    from += 1;
+  }
+  return out;
+}

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

package/lib/leverage/engine.mjs

@@ -6,6 +6,7 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { adapters } from "./adapters/index.mjs";
+import { listAgentSkills, neededSkills, skillsStamp } from "../skill-deps.mjs";
 
 // Merge dependencies from the cwd package.json and any apps/*/package.json (monorepo).
 function readDeps(cwd) {
@@ -66,17 +67,45 @@ export function repoContext(cwd) {
     envFiles,
     envGitignored: envFiles.length === 0 || envIgnored(cwd),
     mcp: readMcp(cwd),
+    // The cross-harness toolbox (wave 6): `.agents/skills/` is harness-NEUTRAL
+    // (Claude Code · Codex · Cursor read the same SKILL.md convention; the
+    // vendored deps ship Codex manifests alongside). Every adapter sees the
+    // same inventory — never a per-toolchain re-read.
+    agentSkills: listAgentSkills(cwd),
+    skillDeps: {
+      needed: neededSkills(cwd).map((d) => ({ name: d.name, why: d.why })),
+      ...skillsStamp(cwd),
+    },
   };
 }
 
 const RANK = { P1: 0, P2: 1, P3: 2 };
 
+// Engine-level tips — rafa's OWN dependency system, harness-neutral by
+// definition (the fix is a rafa command, whatever the host toolchain).
+function engineTips(ctx) {
+  const tips = [];
+  const missing = ctx.skillDeps?.needed ?? [];
+  if (missing.length) {
+    tips.push({
+      id: "skill-deps-missing",
+      priority: "P2",
+      title: `${missing.length} declared skill dependenc${missing.length === 1 ? "y" : "ies"} not installed`,
+      detail: missing.map((d) => `${d.name} — ${d.why}`).join(" · "),
+      fix: "run `rafa update --skills` (consent-gated; declined is remembered)",
+      tool: "rafa",
+    });
+  }
+  return tips;
+}
+
 // Run every detected adapter, tag tips with their tool, and rank by priority.
 export function advise(cwd) {
   const ctx = repoContext(cwd);
   const active = adapters.filter((a) => a.detect(cwd));
-  const tips = active
-    .flatMap((a) => a.recommend(cwd, ctx).map((t) => ({ ...t, tool: a.name })))
-    .sort((x, y) => (RANK[x.priority] ?? 9) - (RANK[y.priority] ?? 9));
+  const tips = [
+    ...engineTips(ctx),
+    ...active.flatMap((a) => a.recommend(cwd, ctx).map((t) => ({ ...t, tool: a.name }))),
+  ].sort((x, y) => (RANK[x.priority] ?? 9) - (RANK[y.priority] ?? 9));
   return { ctx, detected: active.map((a) => a.name), tips };
 }

package/lib/leverage.mjs

@@ -7,16 +7,25 @@ import { adapters, PLANNED } from "./leverage/adapters/index.mjs";
 
 export default async function leverage(args = []) {
   const cwd = process.cwd();
-  const { detected, tips } = advise(cwd);
+  const { ctx, detected, tips } = advise(cwd);
 
   // --json: the DETERMINISTIC toolbox inventory (ratified 2026-07-12) — what
   // the conductor loads at bootstrap and atlas consults during scan's toolbox
   // pass. Machine truth: only what is actually installed, never inferred.
+  // `agentSkills` (wave 6) is the HARNESS-NEUTRAL `.agents/skills/` inventory
+  // — top-level, not under any one toolchain: Claude Code, Codex, and Cursor
+  // all read the same skill convention.
   if (args.includes("--json")) {
     const inventory = {};
     for (const a of adapters)
       if (a.detect(cwd)) inventory[a.id] = a.inspect(cwd);
-    console.log(JSON.stringify({ detected, inventory, tips }, null, 2));
+    console.log(
+      JSON.stringify(
+        { detected, agentSkills: ctx.agentSkills, skillDeps: ctx.skillDeps, inventory, tips },
+        null,
+        2,
+      ),
+    );
     return;
   }