@rafinery/cli 0.8.15 → 0.10.0

package/lib/releases.mjs

@@ -264,6 +264,36 @@ export const RELEASES = [
       "first branch checkout (bounded; a failure never breaks the checkout). " +
       "`rafa update` re-vendors the post-checkout hook.",
   },
+  {
+    version: "0.8.13",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "LEDGER HYDRATION: `rafa hydrate improvement <id>` faults a ledger item into " +
+      ".rafa/improve/improvements/<id>.md — the CANONICAL path — so bloom edits the " +
+      "same file the org brain carries (never a path twin). SOPs updated: an " +
+      "improvement the plan ADOPTS is hydrated AT PLAN TIME (bloom engages from the " +
+      "start, not only at build end); ledger status edits always hydrate first. " +
+      "Platform fixes ride server-side: set_active_plan now resolves v2 epics " +
+      "(was v1 parent-only — the not_found bug), get_improvement serves summary.",
+  },
+  {
+    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.15",
     contract: 1,
@@ -284,34 +314,73 @@ export const RELEASES = [
       "aware recall (tier-labeled), compass sitback, gap lifecycle beats.",
   },
   {
-    version: "0.8.14",
+    version: "0.8.16",
     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.",
+      "THE SESSION TAIL NEVER STRANDS (live-catch 2026-07-24: brain notes " +
+      "authored AFTER the last code commit sat uncommitted while `rafa " +
+      "checkpoint` said clean — capture plane synced, git plane dirty). " +
+      "`rafa checkpoint` now owns BOTH planes: after the working-set sync it " +
+      "fires the vendored brain-commit worker whenever the brain tree is " +
+      "dirty, so the tail commits + pushes at the same beat that creates it. " +
+      "The worker is tail-aware: HEAD already mirrored ⇒ a distinct " +
+      "`session tail · N file(s)` subject on the same code-commit trailer " +
+      "(never a look-alike duplicate), and an empty tail is a no-op. " +
+      "review.json (the review gate's scored-ranges artifact) joins the " +
+      "local-state exclusion — machine state, never brain knowledge.",
   },
   {
-    version: "0.8.13",
+    version: "0.9.0",
     contract: 1,
     plans: 2,
     requires: "update",
     summary:
-      "LEDGER HYDRATION: `rafa hydrate improvement <id>` faults a ledger item into " +
-      ".rafa/improve/improvements/<id>.md — the CANONICAL path — so bloom edits the " +
-      "same file the org brain carries (never a path twin). SOPs updated: an " +
-      "improvement the plan ADOPTS is hydrated AT PLAN TIME (bloom engages from the " +
-      "start, not only at build end); ledger status edits always hydrate first. " +
-      "Platform fixes ride server-side: set_active_plan now resolves v2 epics " +
-      "(was v1 parent-only — the not_found bug), get_improvement serves summary.",
+      "WAVE 5 — trust plane + transport economics (the QA-dogfood fixes). " +
+      "Loop events are STRICT (no legacy path): required actor envelope " +
+      "{model, agent, runner} + required verification {method: static|live, " +
+      "tool, evidence} on verdict/gate categories + idempotent dedupeKey + " +
+      "tier — pre-0.9.0 emits reject loudly (owner: old CLIs discarded). " +
+      "One beat per task boundary: patch_plan_item (field-level item patch) " +
+      "+ checkpoint_task (patch + loop event + decisions, ONE transaction). " +
+      "verify-citations --fix heals drifted cites (unique-grep only — never " +
+      "guesses) and hydrate re-bases served cites on arrival. NEW `rafa " +
+      "facts`: the session-facts plane (memoized verification, sha-anchored " +
+      "invalidation). The SessionStart digest computes 'sage due' from a " +
+      "checkpoint-written loop-event cache — sage's trigger is mechanical. " +
+      "Plan tasks gain validation_tier (light|standard|full — prism depth " +
+      "only; the Done-check never relaxes). Cards/SOPs re-vendored: prism " +
+      "0.8.0 (tool authenticity · structured return · bounded invariant " +
+      "citation) · atlas 3.9.0 · sage 0.4.0 · conductor 2.1.0.",
+  },
+  {
+    version: "0.10.0",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    summary:
+      "WAVE 6 — the capability arc. NEW: consent-gated SKILL DEPENDENCIES — " +
+      "this release declares 7 third-party skills (tdd · frontend-design · " +
+      "vercel-composition-patterns · requesting-code-review · " +
+      "improve-codebase-architecture · grill-me · grilling), and `rafa " +
+      "update`/`init` offers them ONCE with per-skill reasons, installs " +
+      "package-manager style into the HARNESS-NEUTRAL .agents/skills/ " +
+      "(Claude Code · Codex · Cursor read the same convention), verifies " +
+      "(frontmatter · hashes · licenses), and stamps rafa.json. Declined is " +
+      "remembered (re-offer: --skills); --yes for CI; a declined set NEVER " +
+      "breaks anything (F1: cards never point at .agents). Agent upgrades " +
+      "riding it: TDD-DEFAULT builds (atlas 4.0.0 — the Done-check is a " +
+      "failing test first at a dev-approved seam; red→green evidence; prism " +
+      "verifies tier-scaled), the UI design method (frontend-design invoked, " +
+      "brain conventions win), the plan-gate GRILL pass (tier-bounded " +
+      "adversarial interview; vacuous Done-checks caught), severity-labeled " +
+      "findings (Critical/Important/Minor — Minor never flips a verdict; " +
+      "prism 0.9.0), and bloom's architecture method (deletion test · " +
+      "Confidence-lined candidates; bloom 0.9.0). Conductor 2.2.0: the " +
+      "toolbox recall surface includes .agents/skills; `rafa leverage " +
+      "--json` carries the harness-neutral agentSkills + skillDeps blocks; " +
+      "doctor gains a capabilities section.",
   },
 ];
 

package/lib/review.mjs

@@ -117,6 +117,37 @@ export function relevanceOf(note, diffTokens) {
   return { score, engage: score >= 3 ? "deep" : score >= 1 ? "triage" : "skip" };
 }
 
+// Summary counters, deduped by id (wave 5 T7): get_code_context runs per
+// changed file, so a note citing N changed files lands in N per-file rows —
+// counting it N times inflated every summary number. Dedupe is DISPLAY-COUNT
+// only: the per-file sections (and review.json's files[]) stay per-file — a
+// note governing two files still prints under both. A note keeps its STRONGEST
+// classification: direct beats file-hit, engage beats skip.
+export function summarizeReview(out) {
+  const dedupe = (rows) => {
+    const seen = new Map();
+    for (const r of rows) if (!seen.has(r.id)) seen.set(r.id, r);
+    return [...seen.values()];
+  };
+  const allNotes = out.flatMap((f) => f.notes);
+  const direct = dedupe(allNotes.filter((r) => r.hit === "direct"));
+  const directIds = new Set(direct.map((r) => r.id));
+  const fileHits = dedupe(allNotes.filter((r) => r.hit === "file")).filter(
+    (r) => !directIds.has(r.id),
+  );
+  const engaged = dedupe(allNotes.filter((r) => r.engage !== "skip"));
+  const engagedIds = new Set(engaged.map((r) => r.id));
+  const skipped = dedupe(allNotes).filter((r) => !engagedIds.has(r.id));
+  return {
+    direct,
+    fileHits,
+    imps: dedupe(out.flatMap((f) => f.improvements)),
+    stale: dedupe(allNotes.filter((r) => r.staleCites)),
+    engaged,
+    skipped,
+  };
+}
+
 export default async function review(args = []) {
   const ROOT = process.cwd();
   if (!existsSync(join(ROOT, "rafa.json"))) {
@@ -208,12 +239,7 @@ export default async function review(args = []) {
     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"));
+  const { direct, fileHits, imps, stale, engaged, skipped } = summarizeReview(out);
   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)` : ""),

package/lib/session-facts.mjs

@@ -0,0 +1,108 @@
+// The session-facts plane (wave 5.4 — memoized verification).
+//
+// QA-session finding: six subagents independently re-derived the same
+// environment facts ("no node_modules, workspace:* deps") in one build. The fix
+// is NOT a trust-me cache — that would be the assumed-values disease. Every
+// fact carries its VERIFICATION EVIDENCE (the command + exit code that proved
+// it) and a MECHANICAL invalidation rule: the fact is citable only while
+// `git diff <verifiedAtSha>` (against the working tree, uncommitted edits
+// count) leaves its `dependsOn` paths untouched. Memoization with
+// invalidation — the same move as brain = f(code@sha), at session scale.
+//
+// File: .rafa/session-facts.json — machine/session state, excluded from brain
+// pushes (LOCAL_STATE in brain-commit.mjs + IGNORES in brain-repo.mjs; a
+// defensive self-ignore rides every write). Conductor writes via `rafa facts`;
+// subagents READ FIRST and cite "SF-<n> unchanged" instead of re-deriving.
+
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const FACTS_REL = "session-facts.json";
+export const factsPath = (cwd) => join(cwd, ".rafa", FACTS_REL);
+
+const EMPTY = () => ({ schemaVersion: 1, facts: [] });
+
+export function readFacts(cwd = process.cwd()) {
+  try {
+    const doc = JSON.parse(readFileSync(factsPath(cwd), "utf8"));
+    if (doc?.schemaVersion !== 1 || !Array.isArray(doc.facts)) return EMPTY();
+    return doc;
+  } catch {
+    return EMPTY();
+  }
+}
+
+// A malformed fact is rejected loudly at write time — never stored, never
+// silently dropped at read time. Returns an error string or null.
+export function validateFact(f) {
+  if (!f || typeof f !== "object") return "fact must be an object";
+  if (typeof f.id !== "string" || !/^SF-\d+$/.test(f.id)) return "id must be SF-<n>";
+  if (typeof f.claim !== "string" || f.claim.trim() === "") return "claim is required";
+  if (!f.evidence || typeof f.evidence.command !== "string" || f.evidence.command.trim() === "")
+    return "evidence.command is required — a fact without the command that proved it is an assumed value";
+  if (!Number.isInteger(f.evidence.exitCode)) return "evidence.exitCode must be an integer";
+  if (typeof f.verifiedAtSha !== "string" || f.verifiedAtSha.trim() === "")
+    return "verifiedAtSha is required";
+  if (!Array.isArray(f.dependsOn)) return "dependsOn must be an array of paths (may be empty)";
+  return null;
+}
+
+export function writeFacts(cwd, doc) {
+  const dir = join(cwd, ".rafa");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(factsPath(cwd), JSON.stringify(doc, null, 2) + "\n");
+  // Defensive self-ignore (post-tool.mjs pattern): the facts file must never
+  // ride a brain push even if this repo predates the wave-5 ignore lists.
+  try {
+    const gi = join(dir, ".gitignore");
+    const cur = existsSync(gi) ? readFileSync(gi, "utf8") : "";
+    const have = new Set(cur.split("\n").map((l) => l.trim()).filter(Boolean));
+    if (!have.has(FACTS_REL))
+      writeFileSync(gi, cur + (cur === "" || cur.endsWith("\n") ? "" : "\n") + FACTS_REL + "\n");
+  } catch {
+    /* ignore-file hygiene is best-effort — the canonical lists also carry it */
+  }
+}
+
+const short = (sha) => String(sha).slice(0, 7);
+
+// The mechanical invalidation rule. A fact goes stale when:
+//   - any dependsOn path changed since verifiedAtSha (working tree INCLUDED —
+//     an uncommitted edit invalidates just as hard), or
+//   - verifiedAtSha is unknown to this checkout (rebase/gc) → fail-honest.
+// Empty dependsOn = environment-shaped fact, never auto-stale (invalidate by hand).
+export function staleFacts(cwd = process.cwd(), doc = null) {
+  const d = doc ?? readFacts(cwd);
+  const out = [];
+  for (const f of d.facts) {
+    try {
+      const changed = execSync(`git diff --name-only ${f.verifiedAtSha}`, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      })
+        .split("\n")
+        .filter(Boolean);
+      const hit = (f.dependsOn ?? []).filter((p) =>
+        changed.some((c) => c === p || c.startsWith(p.endsWith("/") ? p : p + "/")),
+      );
+      if (hit.length)
+        out.push({ id: f.id, reason: `dependsOn touched since ${short(f.verifiedAtSha)}: ${hit.join(", ")}` });
+    } catch {
+      out.push({
+        id: f.id,
+        reason: `verifiedAtSha ${short(f.verifiedAtSha)} unknown to this checkout — re-verify or drop`,
+      });
+    }
+  }
+  return out;
+}
+
+export function nextFactId(doc) {
+  const max = doc.facts.reduce((m, f) => {
+    const n = Number(String(f.id).replace(/^SF-/, ""));
+    return Number.isFinite(n) && n > m ? n : m;
+  }, 0);
+  return `SF-${max + 1}`;
+}

package/lib/skill-deps.mjs

@@ -0,0 +1,377 @@
+// Skill dependencies (wave 6 — the capability arc).
+//
+// rafa's agents lean on a small set of third-party skills (TDD, design method,
+// composition rules, review taxonomy, the grilling interview). They are NOT
+// baked into the blueprint: the dev owns their toolbox, so the CLI DECLARES
+// them here and `rafa update`/`init` offers them ONCE with per-skill reasons —
+// package-manager style: consent → sequential install with progress → verify
+// (frontmatter parses · hashes match · licenses present) → stamp. A decline is
+// remembered (`rafa.json → rafa.skills.declined`; re-offer with `rafa update
+// --skills`), `--yes` installs unprompted (CI), and a verify failure removes
+// the partial dir and NEVER blocks provisioning — a missing capability
+// degrades the SOPs gracefully, it never bricks a repo.
+//
+// The skills ship inside the npm tarball (skills-bundle/, hashed at prepack —
+// deterministic, offline, license-complete). Install target: .agents/skills/
+// (committed — the repo owns the copies; the harness-neutral home, Codex
+// manifests ride along). Agent adoption is the point: the conductor's toolbox
+// slice + the rafa-* SOPs reference these BY CAPABILITY with when-installed
+// semantics — agent-card duty paths NEVER point here (F1: a declined skill
+// must never break a consumer's compile gate).
+
+import { createHash } from "node:crypto";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readStamp, writeStamp } from "./stamp.mjs";
+import { isInteractive, ask } from "./prompt.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url)); // …/packages/cli/lib
+
+// The declared dependencies. `version` is rafa's pin for the vendored snapshot;
+// `source`/`upstreamHash` mirror skills-lock.json provenance at authoring time;
+// `why` is the one-line reason shown in the consent prompt; `licenseFile` names
+// the in-dir license the verify pass requires (null = license carried in
+// frontmatter/metadata, or rafa-authored).
+export const SKILL_DEPS = [
+  {
+    name: "tdd",
+    version: "1.0.0",
+    source: "mattpocock/skills",
+    upstreamHash: "81eca2a5b53a",
+    targetDir: ".agents/skills/tdd",
+    license: "MIT",
+    licenseFile: "LICENSE",
+    why: "atlas builds test-first — the Done-check becomes an executable test (red → green)",
+    requiredBy: "atlas · rafa-build",
+  },
+  {
+    name: "frontend-design",
+    version: "1.0.0",
+    source: "anthropics/skills",
+    upstreamHash: "4eabc6618376",
+    targetDir: ".agents/skills/frontend-design",
+    license: "Apache-2.0",
+    licenseFile: "LICENSE.txt",
+    why: "UI tasks get a design method (token system · signature element) instead of template defaults",
+    requiredBy: "atlas · rafa-build",
+  },
+  {
+    name: "vercel-composition-patterns",
+    version: "1.0.0",
+    source: "vercel-labs/agent-skills",
+    upstreamHash: "575757e3e257",
+    targetDir: ".agents/skills/vercel-composition-patterns",
+    license: "MIT",
+    licenseFile: null, // license declared in SKILL.md frontmatter + metadata.json
+    why: "React composition rules for component tasks (no boolean-prop sprawl · compound components · React 19)",
+    requiredBy: "atlas · rafa-build",
+  },
+  {
+    name: "requesting-code-review",
+    version: "1.0.0",
+    source: "obra/superpowers",
+    upstreamHash: "2304d2073c62",
+    targetDir: ".agents/skills/requesting-code-review",
+    license: "MIT",
+    licenseFile: "LICENSE",
+    why: "review findings get Critical/Important/Minor severity — Minor never blocks",
+    requiredBy: "prism · rafa-review",
+  },
+  {
+    name: "improve-codebase-architecture",
+    version: "1.0.0",
+    source: "mattpocock/skills",
+    upstreamHash: "66e8a50c83c3",
+    targetDir: ".agents/skills/improve-codebase-architecture",
+    license: "MIT",
+    licenseFile: "LICENSE",
+    why: "bloom's architecture lens gets a real method (deletion test · deep/shallow modules)",
+    requiredBy: "bloom · rafa-improve",
+  },
+  {
+    name: "grill-me",
+    version: "1.0.0",
+    source: "mattpocock/skills",
+    upstreamHash: "f361db4e15e6",
+    targetDir: ".agents/skills/grill-me",
+    license: "MIT",
+    licenseFile: "LICENSE",
+    why: "/grill-me — adversarial interview of any plan (human-invoked)",
+    requiredBy: "dev · prism plan-gate",
+  },
+  {
+    name: "grilling",
+    version: "1.0.0",
+    source: "rafinery",
+    upstreamHash: null,
+    targetDir: ".agents/skills/grilling",
+    license: "rafinery (ships with the CLI)",
+    licenseFile: null,
+    why: "the interview procedure grill-me and the plan gate run (one probe at a time · survives-three ends it)",
+    requiredBy: "grill-me · prism plan-gate",
+  },
+];
+
+// ── bundle resolution (mirrors blueprintSource: bundled copy first, monorepo dev fallback) ──
+
+const walkFiles = (dir, base = dir) =>
+  readdirSync(dir).flatMap((e) => {
+    const p = join(dir, e);
+    if (statSync(p).isDirectory()) return walkFiles(p, base);
+    return [p.slice(base.length + 1)];
+  });
+
+export const hashFile = (abs) =>
+  createHash("sha256").update(readFileSync(abs)).digest("hex");
+
+// {dir, manifest: {skills: {name: {version, files: {rel: sha256}}}}} or null.
+export function loadSkillsBundle() {
+  const bundled = join(HERE, "..", "skills-bundle");
+  if (existsSync(join(bundled, "skills-manifest.json"))) {
+    try {
+      return {
+        dir: bundled,
+        manifest: JSON.parse(readFileSync(join(bundled, "skills-manifest.json"), "utf8")),
+      };
+    } catch {
+      return null;
+    }
+  }
+  // Dev fallback: the monorepo's .agents/skills IS the source — manifest computed live.
+  const dev = join(HERE, "..", "..", "..", ".agents", "skills");
+  if (!existsSync(dev)) return null;
+  const skills = {};
+  for (const d of SKILL_DEPS) {
+    const src = join(dev, d.name);
+    if (!existsSync(src)) continue;
+    skills[d.name] = {
+      version: d.version,
+      files: Object.fromEntries(walkFiles(src).map((rel) => [rel, hashFile(join(src, rel))])),
+    };
+  }
+  return { dir: dev, manifest: { skills } };
+}
+
+// ── stamp helpers ──────────────────────────────────────────────────────────────
+
+export function skillsStamp(cwd) {
+  const s = readStamp(cwd).rafa?.skills ?? {};
+  return { installed: s.installed ?? {}, declined: s.declined ?? [] };
+}
+
+function writeSkillsStamp(cwd, { installed, declined }) {
+  writeStamp(cwd, { rafa: { skills: { installed, declined } } });
+}
+
+export function neededSkills(cwd, { reoffer = false } = {}) {
+  const { installed, declined } = skillsStamp(cwd);
+  const declinedSet = new Set(declined);
+  return SKILL_DEPS.filter(
+    (d) => installed[d.name] === undefined && (reoffer || !declinedSet.has(d.name)),
+  );
+}
+
+// ── verify (also the doctor's capabilities check) ─────────────────────────────
+
+// Lenient head-parse for FOREIGN skill files: third-party SKILL.md frontmatter
+// is general YAML (folded scalars, nested maps) that the strict OKF grammar
+// rightly rejects — these are Claude skills, not OKF concepts. Verify only what
+// a skill needs to be loadable: a fenced frontmatter block carrying `name:`.
+export function skillHead(abs) {
+  let text;
+  try {
+    text = readFileSync(abs, "utf8");
+  } catch {
+    return null;
+  }
+  if (!text.startsWith("---")) return null;
+  const end = text.indexOf("\n---", 3);
+  if (end === -1) return null;
+  const fm = text.slice(3, end);
+  const name = fm.match(/^name:\s*(.+)$/m)?.[1]?.trim();
+  const description = fm.match(/^description:\s*(.+)$/m)?.[1]?.trim() ?? "";
+  return name ? { name, description } : null;
+}
+
+// The harness-neutral third-party toolbox inventory: every .agents/skills/<name>
+// with a loadable SKILL.md, as {name, description}. `.agents/` is the
+// cross-harness home (Claude Code · Codex · Cursor — the vendored skills ship
+// Codex `agents/openai.yaml` manifests alongside SKILL.md), so this reader
+// lives HERE, not inside any one toolchain adapter; the leverage engine's
+// repoContext, the conductor's spawn-prompt slice, and the scan's toolbox
+// domain all consume this one implementation.
+export function listAgentSkills(cwd) {
+  const root = join(cwd, ".agents", "skills");
+  if (!existsSync(root)) return [];
+  return readdirSync(root)
+    .filter((e) => {
+      try {
+        return statSync(join(root, e)).isDirectory();
+      } catch {
+        return false;
+      }
+    })
+    .map((e) => {
+      const head = skillHead(join(root, e, "SKILL.md"));
+      return head ? { name: head.name, description: head.description } : null;
+    })
+    .filter(Boolean);
+}
+
+function verifySkill(cwd, dep, bundleManifest) {
+  const dst = join(cwd, dep.targetDir);
+  if (!existsSync(join(dst, "SKILL.md"))) return { ok: false, reason: "SKILL.md missing" };
+  const head = skillHead(join(dst, "SKILL.md"));
+  if (!head) return { ok: false, reason: "SKILL.md frontmatter does not parse (no fenced name:)" };
+  if (dep.licenseFile && !existsSync(join(dst, dep.licenseFile)))
+    return { ok: false, reason: `license file ${dep.licenseFile} missing` };
+  const expect = bundleManifest?.skills?.[dep.name]?.files;
+  if (expect) {
+    for (const [rel, sha] of Object.entries(expect)) {
+      const abs = join(dst, rel);
+      if (!existsSync(abs)) return { ok: false, reason: `${rel} missing` };
+      if (hashFile(abs) !== sha) return { ok: false, reason: `${rel} hash mismatch` };
+    }
+  }
+  return { ok: true };
+}
+
+// Doctor's read: every STAMPED-installed skill re-verified against disk.
+export function verifyInstalled(cwd) {
+  const { installed } = skillsStamp(cwd);
+  const bundle = loadSkillsBundle();
+  const results = [];
+  for (const [name] of Object.entries(installed)) {
+    const dep = SKILL_DEPS.find((d) => d.name === name);
+    if (!dep) {
+      results.push({ name, ok: false, reason: "stamped but no longer a declared dependency" });
+      continue;
+    }
+    results.push({ name, ...verifySkill(cwd, dep, bundle?.manifest) });
+  }
+  return results;
+}
+
+// ── the consent-gated installer (owner's design, wave 6) ──────────────────────
+//
+// prompt is injectable for tests: async (question) => "y" | "n" | … | null
+// (null = non-interactive). Returns { installed, declined, failed, skipped }.
+export async function installSkillDeps(cwd, { prompt = null, args = [] } = {}) {
+  const reoffer = args.includes("--skills");
+  const yes = args.includes("--yes");
+  const needed = neededSkills(cwd, { reoffer });
+  const result = { installed: [], declined: [], failed: [], skipped: false };
+  if (needed.length === 0) return { ...result, skipped: true };
+
+  const bundle = loadSkillsBundle();
+  if (!bundle) {
+    console.log("  ! skill dependencies declared but no skills bundle in this CLI build — skipped");
+    return { ...result, skipped: true };
+  }
+  const available = needed.filter((d) => bundle.manifest.skills?.[d.name]);
+  if (available.length === 0) return { ...result, skipped: true };
+
+  console.log(`\nrafa needs ${available.length} skill(s) for better performance in this release:\n`);
+  for (const d of available)
+    console.log(
+      `    ${(d.name + " " + d.version).padEnd(38)}${d.why}  [${d.license}]`,
+    );
+  console.log(
+    "\n  They install to .agents/skills/ (committed — your repo owns the copies)." +
+      "\n  Decline with n; re-offer any time with `rafa update --skills`.\n",
+  );
+
+  const doAsk = prompt ?? (async (q) => (isInteractive() ? ask(q) : null));
+
+  let toInstall = [];
+  const newlyDeclined = [];
+  if (yes) {
+    toInstall = available;
+  } else if (reoffer) {
+    // Per-skill grammar (the makeConflictResolver interaction): y/N/a/q.
+    let all = false;
+    let quit = false;
+    for (const d of available) {
+      if (all) {
+        toInstall.push(d);
+        continue;
+      }
+      if (quit) {
+        newlyDeclined.push(d.name);
+        continue;
+      }
+      const a = await doAsk(`  • install ${d.name} ${d.version}? [y = yes · N = no · a = all · q = none] `);
+      if (a === null) return { ...result, skipped: true }; // non-TTY: record NOTHING
+      if (a === "a") {
+        all = true;
+        toInstall.push(d);
+      } else if (a === "q") {
+        quit = true;
+        newlyDeclined.push(d.name);
+      } else if (a === "y" || a === "yes") toInstall.push(d);
+      else newlyDeclined.push(d.name);
+    }
+  } else {
+    const a = await doAsk(`  Install all ${available.length}? [Y/n] `);
+    if (a === null) {
+      // Non-TTY without --yes: skip, stamp NOTHING — a human must decide;
+      // CI silently declining for them would be an assumed value.
+      console.log("  · non-interactive — skipped (install later: `rafa update --skills`, or pass --yes)");
+      return { ...result, skipped: true };
+    }
+    if (a === "" || a === "y" || a === "yes") toInstall = available;
+    else newlyDeclined.push(...available.map((d) => d.name));
+  }
+
+  for (const d of toInstall) {
+    const src = join(bundle.dir, d.name);
+    const dst = join(cwd, d.targetDir);
+    try {
+      mkdirSync(dirname(dst), { recursive: true });
+      cpSync(src, dst, { recursive: true });
+      const v = verifySkill(cwd, d, bundle.manifest);
+      if (!v.ok) {
+        rmSync(dst, { recursive: true, force: true });
+        console.log(`  ✗ ${d.name} ${d.version} — verify failed (${v.reason}); not installed`);
+        result.failed.push({ name: d.name, reason: v.reason });
+        continue;
+      }
+      console.log(`  ✓ ${d.name} ${d.version} — installed (${d.targetDir})`);
+      result.installed.push(d.name);
+    } catch (e) {
+      rmSync(dst, { recursive: true, force: true });
+      const reason = e instanceof Error ? e.message : String(e);
+      console.log(`  ✗ ${d.name} ${d.version} — install failed (${reason}); not installed`);
+      result.failed.push({ name: d.name, reason });
+    }
+  }
+
+  // Stamp: installed adds; declined = explicit human "no" only, deduped.
+  const cur = skillsStamp(cwd);
+  const installed = { ...cur.installed };
+  for (const n of result.installed) {
+    const dep = SKILL_DEPS.find((d) => d.name === n);
+    installed[n] = dep.version;
+  }
+  const declined = [...new Set([...cur.declined.filter((n) => !result.installed.includes(n)), ...newlyDeclined])];
+  writeSkillsStamp(cwd, { installed, declined });
+  result.declined = newlyDeclined;
+
+  if (result.installed.length)
+    console.log(
+      `  ✓ verified ${result.installed.length}/${toInstall.length} (frontmatter parses · hashes match · licenses present)` +
+        `\n  → commit .agents/skills/ — the repo owns its toolbox`,
+    );
+  if (newlyDeclined.length)
+    console.log(`  · declined ${newlyDeclined.length} — remembered; agents fall back per SOP (re-offer: rafa update --skills)`);
+  return result;
+}