@rafinery/cli 0.7.0 → 0.8.0

package/lib/ci-setup.mjs

@@ -46,6 +46,7 @@ jobs:
       - name: Mechanical fold (no LLM — rigor lives at main)
         env:
           RAFA_MCP_KEY: \${{ secrets.RAFA_MCP_KEY }}
+          RAFA_MCP_URL: \${{ secrets.RAFA_MCP_URL }} # deployed platform /api/mcp — localhost never works from CI
           RAFA_HOOKS_DISABLED: "1" # headless — the M5 sensors are session instruments
         run: npx -y @rafinery/cli fold --from "\${{ github.event.pull_request.head.ref }}" --to "\${{ github.event.pull_request.base.ref }}"
 
@@ -60,13 +61,20 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 20
-      - name: Install the Agent SDK (runs on the org's own key)
-        run: npm i --no-save @anthropic-ai/claude-agent-sdk
+      # ISOLATED install — never \`npm i\` inside the client checkout: a pnpm
+      # workspace repo has "workspace:*" deps npm cannot parse (EUNSUPPORTEDPROTOCOL).
+      - name: Install the Agent SDK (isolated dir; runs on the org's own key)
+        run: |
+          mkdir -p "\$RUNNER_TEMP/rafa-sdk" && cd "\$RUNNER_TEMP/rafa-sdk"
+          npm init -y > /dev/null
+          npm i @anthropic-ai/claude-agent-sdk
       - name: Distill into the org brain (prism-validated, compile-gated)
         env:
           ANTHROPIC_API_KEY: \${{ secrets.ANTHROPIC_API_KEY }}
           RAFA_MCP_KEY: \${{ secrets.RAFA_MCP_KEY }}
+          RAFA_MCP_URL: \${{ secrets.RAFA_MCP_URL }} # deployed platform /api/mcp — localhost never works from CI
           RAFA_BRAIN_TOKEN: \${{ secrets.RAFA_BRAIN_TOKEN }}
+          RAFA_AGENT_SDK_DIR: \${{ runner.temp }}/rafa-sdk
           RAFA_HOOKS_DISABLED: "1" # headless — the M5 sensors are session instruments
         run: npx -y @rafinery/cli distill --headless "\${{ github.event.pull_request.head.ref }}"
 `;
@@ -97,12 +105,14 @@ export default async function ciSetup(args = []) {
   console.log(`
 Next steps (repo Settings → Secrets and variables → Actions):
   1. RAFA_MCP_KEY       — mint on the platform (repo → Agent access); scope: this repo.
-  2. ANTHROPIC_API_KEY  — the ORG'S OWN LLM key. Used only inside YOUR CI for
+  2. RAFA_MCP_URL       — your DEPLOYED platform's MCP endpoint (https://<host>/api/mcp).
+                          A localhost dev URL can never work from a CI runner.
+  3. ANTHROPIC_API_KEY  — the ORG'S OWN LLM key. Used only inside YOUR CI for
                           merge-to-main distillation; never stored on the rafinery
                           platform (hard rule).
-  3. RAFA_BRAIN_TOKEN   — a token with push access to the BRAIN repo (the distill
+  4. RAFA_BRAIN_TOKEN   — a token with push access to the BRAIN repo (the distill
                           job pushes validated knowledge there).
-  4. Commit the workflow via your normal MR flow.
+  5. Commit the workflow via your normal MR flow.
 
 The rigor gradient this wires: dev↔dev = CAS + session prompt · branch↔branch =
 free mechanical fold · branch→main = full distillation + gates. Cost tracks

package/lib/distill.mjs

@@ -17,7 +17,13 @@
 // Fallback chain when this can't run (no key, no CI): the dev-session flow —
 // /rafa distill <branch> in Claude Code (the bootstrap digest offers it).
 
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -35,27 +41,35 @@ const die = (m) => {
 // A brain-relative path from the platform must stay inside .rafa/ — a row that
 // would escape is refused loudly (never written, never guessed).
 const safeRel = (p) => {
-  if (p.startsWith("/") || p.split("/").includes("..")) die(`unsafe working-set path: ${p}`);
+  if (p.startsWith("/") || p.split("/").includes(".."))
+    die(`unsafe working-set path: ${p}`);
   return p;
 };
 
 // The Agent SDK is deliberately NOT a dependency of this CLI (it is heavy and
-// only CI distillation needs it). Resolution order: normal import → the host
-// repo's node_modules (the workflow installs it with `npm i --no-save`).
+// only CI distillation needs it). Resolution order: $RAFA_AGENT_SDK_DIR (the
+// workflow's ISOLATED install — `npm i` inside the client checkout breaks on
+// pnpm workspaces, "workspace:*" is not an npm protocol) → normal import →
+// the host repo's node_modules.
 async function loadAgentSdk(cwd) {
-  try {
-    return await import("@anthropic-ai/claude-agent-sdk");
-  } catch {
+  const roots = [process.env.RAFA_AGENT_SDK_DIR, null, cwd];
+  for (const root of roots) {
     try {
-      const req = createRequire(join(cwd, "package.json"));
-      return await import(pathToFileURL(req.resolve("@anthropic-ai/claude-agent-sdk")).href);
-    } catch {
-      die(
-        "@anthropic-ai/claude-agent-sdk is not installed — the reconcile workflow runs\n" +
-          "  `npm i --no-save @anthropic-ai/claude-agent-sdk` before this command (see rafa ci-setup).",
+      if (root === null) return await import("@anthropic-ai/claude-agent-sdk");
+      if (!root) continue;
+      const req = createRequire(join(root, "package.json"));
+      return await import(
+        pathToFileURL(req.resolve("@anthropic-ai/claude-agent-sdk")).href
       );
+    } catch {
+      // try the next root
     }
   }
+  die(
+    "@anthropic-ai/claude-agent-sdk is not installed — the reconcile workflow installs it\n" +
+      "  into an isolated dir and points RAFA_AGENT_SDK_DIR at it (see rafa ci-setup;\n" +
+      "  re-run `npx @rafinery/cli ci-setup --overwrite` if your workflow predates this).",
+  );
 }
 
 const VERDICTS = ["distilled", "refuted", "needs-adjudication"];
@@ -76,7 +90,8 @@ export default async function distill(args = []) {
     die(
       "ANTHROPIC_API_KEY is not set — CI distillation runs on the ORG'S OWN LLM key from CI\n" +
         "  secrets (never stored on the rafinery platform). Add the secret (rafa ci-setup names\n" +
-        "  it), or fall back to the dev session: /rafa distill " + branch,
+        "  it), or fall back to the dev session: /rafa distill " +
+        branch,
     );
 
   const ROOT = process.cwd();
@@ -90,10 +105,16 @@ export default async function distill(args = []) {
   console.log(`• collecting working set for ${branch} …`);
   let active, flagged;
   try {
-    active = (await callTool(ROOT, "get_working_set", { branch, status: "active" })).files ?? [];
-    flagged =
-      (await callTool(ROOT, "get_working_set", { branch, status: "needs-adjudication" }))
+    active =
+      (await callTool(ROOT, "get_working_set", { branch, status: "active" }))
         .files ?? [];
+    flagged =
+      (
+        await callTool(ROOT, "get_working_set", {
+          branch,
+          status: "needs-adjudication",
+        })
+      ).files ?? [];
   } catch (e) {
     die(e instanceof Error ? e.message : String(e));
   }
@@ -131,7 +152,9 @@ export default async function distill(args = []) {
 
   // 4 · the judgment pass (org's own key; gates stay deterministic below).
   const sdk = await loadAgentSdk(ROOT);
-  const fileList = active.map((f) => `- ${f.path} (author: ${f.lastAuthor})`).join("\n");
+  const fileList = active
+    .map((f) => `- ${f.path} (author: ${f.lastAuthor})`)
+    .join("\n");
   const prompt = `You are running rafa's CI DISTILLATION — merge-time reconciliation of branch "${branch}"'s
 working set into the org brain. The checked-out repo IS merged main (the ground truth).
 The current org brain is mirrored at .rafa/brain/. The incoming candidate-grade files are
@@ -162,7 +185,9 @@ with EXACTLY one entry per staged file listed below. Do not modify anything outs
 Staged files:
 ${fileList}`;
 
-  console.log("• running the distillation agent (org's own ANTHROPIC_API_KEY) …");
+  console.log(
+    "• running the distillation agent (org's own ANTHROPIC_API_KEY) …",
+  );
   const tAgent = Date.now();
   const run = sdk.query({
     prompt,
@@ -179,7 +204,10 @@ ${fileList}`;
   let lastLine = "";
   let agentModel = "unreported";
   for await (const message of run) {
-    if (message.type === "assistant" && typeof message.message?.model === "string")
+    if (
+      message.type === "assistant" &&
+      typeof message.message?.model === "string"
+    )
       agentModel = message.message.model;
     if (message.type === "assistant") {
       const blocks = message.message?.content ?? [];
@@ -194,7 +222,9 @@ ${fileList}`;
     }
     if (message.type === "result") {
       if (message.subtype !== "success")
-        die(`distillation agent did not complete (${message.subtype}) — nothing resolved, nothing pushed`);
+        die(
+          `distillation agent did not complete (${message.subtype}) — nothing resolved, nothing pushed`,
+        );
       console.log(
         `  ⏱ agent: ${secs(tAgent)}s (${message.num_turns ?? "?"} turns · ` +
           `$${(message.total_cost_usd ?? 0).toFixed(4)} on the org's key)`,
@@ -206,32 +236,46 @@ ${fileList}`;
           model: agentModel,
           inputTokens: message.usage?.input_tokens ?? 0,
           outputTokens: message.usage?.output_tokens ?? 0,
-          ...(typeof message.total_cost_usd === "number" ? { costUsd: message.total_cost_usd } : {}),
+          ...(typeof message.total_cost_usd === "number"
+            ? { costUsd: message.total_cost_usd }
+            : {}),
           purpose: "distill",
           runner: "ci",
         });
       } catch (e) {
-        console.log(`  ! usage not reported: ${e instanceof Error ? e.message : e}`);
+        console.log(
+          `  ! usage not reported: ${e instanceof Error ? e.message : e}`,
+        );
       }
     }
   }
 
   // 5 · verdicts must be complete — a missing entry is a hard stop, never a guess.
   if (!existsSync(verdictsPath))
-    die("agent produced no .rafa/distill-verdicts.json — nothing resolved, nothing pushed; working set left intact");
+    die(
+      "agent produced no .rafa/distill-verdicts.json — nothing resolved, nothing pushed; working set left intact",
+    );
   let verdicts;
   try {
     verdicts = JSON.parse(readFileSync(verdictsPath, "utf8")).verdicts;
   } catch {
-    die("distill-verdicts.json is not valid JSON — nothing resolved, nothing pushed");
+    die(
+      "distill-verdicts.json is not valid JSON — nothing resolved, nothing pushed",
+    );
   }
-  if (!Array.isArray(verdicts)) die("distill-verdicts.json has no verdicts[] — aborting");
+  if (!Array.isArray(verdicts))
+    die("distill-verdicts.json has no verdicts[] — aborting");
   const byPath = new Map(verdicts.map((v) => [v.path, v]));
   for (const f of active) {
     const v = byPath.get(f.path);
     if (!v || !VERDICTS.includes(v.verdict))
-      die(`no valid verdict for ${f.path} — nothing resolved, nothing pushed; working set left intact`);
-    if (v.verdict !== "distilled" && (typeof v.note !== "string" || v.note.trim() === ""))
+      die(
+        `no valid verdict for ${f.path} — nothing resolved, nothing pushed; working set left intact`,
+      );
+    if (
+      v.verdict !== "distilled" &&
+      (typeof v.note !== "string" || v.note.trim() === "")
+    )
       die(`${f.path}: verdict "${v.verdict}" requires a cited note — aborting`);
   }
 
@@ -239,14 +283,20 @@ ${fileList}`;
   console.log("• re-running the gates (trust-but-verify) …");
   const tGates = Date.now();
   if (runVerifyCitations([]) !== 0)
-    die("citation checker failed on the authored brain — nothing resolved, nothing pushed");
+    die(
+      "citation checker failed on the authored brain — nothing resolved, nothing pushed",
+    );
   if (runCompile([]) !== 0)
-    die("compile gate failed on the authored brain — nothing resolved, nothing pushed");
+    die(
+      "compile gate failed on the authored brain — nothing resolved, nothing pushed",
+    );
   console.log(`  ⏱ gates: ${secs(tGates)}s`);
 
   // 7 · ship: brain repo push (webhook → ingest), staging cleaned first.
   rmSync(stagingRoot, { recursive: true, force: true });
-  const distilledCount = active.filter((f) => byPath.get(f.path).verdict === "distilled").length;
+  const distilledCount = active.filter(
+    (f) => byPath.get(f.path).verdict === "distilled",
+  ).length;
   if (distilledCount > 0) {
     await push([]);
   } else {
@@ -268,9 +318,13 @@ ${fileList}`;
         actorMeta: { agent: "rafa-distill", runner: "ci", model: agentModel },
         ...(v.note ? { note: v.note } : {}),
       });
-      console.log(`  ${v.verdict === "distilled" ? "✓" : "!"} ${f.path} → ${v.verdict}${v.note ? ` (${v.note})` : ""}`);
+      console.log(
+        `  ${v.verdict === "distilled" ? "✓" : "!"} ${f.path} → ${v.verdict}${v.note ? ` (${v.note})` : ""}`,
+      );
     } catch (e) {
-      console.log(`  ✗ ${f.path} — resolve failed: ${e instanceof Error ? e.message : e}`);
+      console.log(
+        `  ✗ ${f.path} — resolve failed: ${e instanceof Error ? e.message : e}`,
+      );
     }
   }
   rmSync(verdictsPath, { force: true });

package/lib/gate/compile.mjs

@@ -21,91 +21,14 @@ import {
 import { join } from "node:path";
 import { execSync } from "node:child_process";
 
-const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 1; // the contract version — single numeric source; the generator imports it
 
-// ── strict frontmatter parser (contract §0 grammar) ─────────────────────────
-// Legal value forms only: scalar | "quoted" | [flow,list] | { flow: map }.
-// Plus `key:` followed by `  - item` block lists and folded scalars. Anything
-// else → error.
-function parseScalar(raw) {
-  const s = raw.trim();
-  if (s === "") return "";
-  if (/^".*"$/.test(s) || /^'.*'$/.test(s)) return s.slice(1, -1);
-  if (s === "true") return true;
-  if (s === "false") return false;
-  if (/^-?\d+$/.test(s)) return Number(s);
-  return s;
-}
-// Strip a trailing YAML comment ( whitespace + # … ) from an UNQUOTED top-level
-// scalar. Not applied to block-list items (cites/links are exact strings that may
-// legitimately contain `#`).
-function stripComment(s) {
-  if (/^["']/.test(s.trim())) return s;
-  const i = s.search(/\s#/);
-  return i === -1 ? s : s.slice(0, i);
-}
-function parseFlowList(raw) {
-  const inner = raw.trim().slice(1, -1).trim();
-  if (inner === "") return [];
-  return inner.split(",").map((x) => parseScalar(x));
-}
-function parseFlowMap(raw) {
-  const inner = raw.trim().slice(1, -1).trim();
-  const out = {};
-  if (inner === "") return out;
-  for (const pair of inner.split(",")) {
-    const i = pair.indexOf(":");
-    if (i === -1) return null; // malformed
-    out[pair.slice(0, i).trim()] = parseScalar(pair.slice(i + 1));
-  }
-  return out;
-}
-// Returns { data } or { error: "reason" }.
-export function parseFrontmatter(text) {
-  if (!text.startsWith("---")) return { error: "no frontmatter block" };
-  const end = text.indexOf("\n---", text.indexOf("\n"));
-  if (end === -1) return { error: "unterminated frontmatter" };
-  const lines = text.slice(text.indexOf("\n") + 1, end).split("\n");
-  const data = {};
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (line.trim() === "" || line.trimStart().startsWith("#")) continue;
-    const m = line.match(/^([A-Za-z_][A-Za-z0-9_]*):(.*)$/);
-    if (!m) return { error: `illegal line: ${JSON.stringify(line)}` };
-    const key = m[1];
-    // Strip a trailing comment first, so `cites:   # note` reads as an empty value
-    // (block list follows), not as the comment being the value.
-    const rest = stripComment(m[2]).trim();
-    if (rest === "") {
-      // block list follows
-      const items = [];
-      while (i + 1 < lines.length && /^\s*-\s+/.test(lines[i + 1])) {
-        items.push(parseScalar(lines[++i].replace(/^\s*-\s+/, "")));
-      }
-      data[key] = items;
-    } else if (rest === ">-" || rest === ">") {
-      // folded scalar (contract §0): indented continuation lines join with one space
-      const parts = [];
-      while (i + 1 < lines.length && /^\s+\S/.test(lines[i + 1])) {
-        parts.push(lines[++i].trim());
-      }
-      data[key] = parts.join(" ");
-    } else if (rest.startsWith("[")) {
-      const close = rest.lastIndexOf("]"); // ignore any trailing comment after ]
-      if (close === -1) return { error: `unclosed flow list at ${key}` };
-      data[key] = parseFlowList(rest.slice(0, close + 1));
-    } else if (rest.startsWith("{")) {
-      const close = rest.lastIndexOf("}");
-      if (close === -1) return { error: `unclosed flow map at ${key}` };
-      const fm = parseFlowMap(rest.slice(0, close + 1));
-      if (fm === null) return { error: `malformed flow map at ${key}` };
-      data[key] = fm;
-    } else {
-      data[key] = parseScalar(rest);
-    }
-  }
-  return { data };
-}
+// The strict frontmatter parser (contract §0 grammar) lives in @rafinery/okf
+// (2026-07-15, the OKF surface arc) so the gate, the emitter, the validator,
+// and the platform all parse knowledge files identically. Re-exported here —
+// existing consumers keep importing it from the gate.
+import { parseFrontmatter } from "@rafinery/okf";
+export { parseFrontmatter };
 
 const CITE_RE = /^(.+):(\d+(?:-\d+)?)\s*::\s*(.+)$/;
 const DUTY_RE = /^(\S[^:]*?)\s+::\s+(\S+)\s+::\s+(\S.*)$/;
@@ -201,18 +124,73 @@ export function runCompile(argv = []) {
     if (d.id !== stem) fail(path, "id", `must equal filename stem "${stem}"`);
     return stem;
   }
+  // OKF surface fields (contract §11) — OPTIONAL everywhere, validated when
+  // present so the emitted bundle never carries a malformed value. `rafa okf`
+  // stamps them where derivable; a brain without them still compiles (additive,
+  // schemaVersion unchanged per §8). `typed` also validates the stamped
+  // `type`/`title` on singleton files (notes/improvements validate their own).
+  function checkOkfFields(d, path, { typed = false } = {}) {
+    if (typed) {
+      for (const key of ["type", "title"])
+        if (key in d && (typeof d[key] !== "string" || d[key].trim() === ""))
+          fail(path, key, "optional · non-empty string (OKF concept surface)");
+    }
+    if (
+      "description" in d &&
+      (typeof d.description !== "string" || d.description.trim() === "")
+    )
+      fail(path, "description", "optional · non-empty string");
+    if (
+      "timestamp" in d &&
+      !/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/.test(
+        String(d.timestamp),
+      )
+    )
+      fail(path, "timestamp", "optional · ISO 8601 date or datetime");
+    if (
+      "tags" in d &&
+      (!Array.isArray(d.tags) ||
+        d.tags.some((t) => typeof t !== "string" || t.trim() === ""))
+    )
+      fail(path, "tags", "optional · flow list of non-empty strings");
+  }
 
+  // index.md + log.md are OKF-reserved (contract §11): listings/trails at any
+  // level, never concept documents — the gate never parses them as data files.
+  // `*.theirs.md` checkpoint-conflict copies are excluded here and flagged as a
+  // TYPED error by sweepConflicts below (never a cryptic id mismatch).
+  const OKF_RESERVED = new Set(["index.md", "log.md"]);
   function walk(dir) {
     if (!existsSync(dir)) return [];
     return readdirSync(dir).flatMap((e) => {
       const p = join(dir, e);
       return statSync(p).isDirectory()
         ? walk(p)
-        : e.endsWith(".md") && !e.startsWith("_")
+        : e.endsWith(".md") &&
+            !e.startsWith("_") &&
+            !e.endsWith(".theirs.md") &&
+            !OKF_RESERVED.has(e)
           ? [p]
           : [];
     });
   }
+  // Unresolved checkpoint conflicts BLOCK the gate with an explicit rule — a
+  // brain with a pending human decision must never compile past it silently.
+  function sweepConflicts(dir) {
+    if (!existsSync(dir)) return;
+    for (const e of readdirSync(dir)) {
+      const p = join(dir, e);
+      if (statSync(p).isDirectory()) {
+        if (e !== ".git") sweepConflicts(p);
+      } else if (e.endsWith(".theirs.md")) {
+        fail(
+          p,
+          "conflict",
+          "unresolved checkpoint conflict — decide (keep yours or adopt theirs), delete the .theirs.md copy, re-run",
+        );
+      }
+    }
+  }
   const read = (p) => readFileSync(p, "utf8");
 
   function compileNotes(kind, dir) {
@@ -235,6 +213,7 @@ export function runCompile(argv = []) {
           (typeof data[key] !== "string" || data[key].trim() === "")
         )
           fail(path, key, "optional · non-empty token (or `none`)");
+      checkOkfFields(data, path); // note `type`/`title` have their own required checks
       // Size stamps (additive optional): body cost + per-cite target-file cost. A
       // target we can't read → the cite simply carries no `targetTokens` (omitted).
       const cites = parseCites(data.cites, path);
@@ -277,6 +256,7 @@ export function runCompile(argv = []) {
       }
       checkVersion(data, path);
       const id = checkId(data, path, name);
+      checkOkfFields(data, path, { typed: true }); // stamped `type: Improvement` etc.
       const lev = data.leverage;
       if (
         typeof lev !== "object" ||
@@ -336,6 +316,7 @@ export function runCompile(argv = []) {
       return null;
     }
     checkVersion(data, path);
+    checkOkfFields(data, path, { typed: true }); // stamped OKF surface (§11)
     const g = data.gates,
       c = data.counts;
     if (
@@ -375,6 +356,7 @@ export function runCompile(argv = []) {
       return null;
     }
     checkVersion(data, path);
+    checkOkfFields(data, path, { typed: true }); // stamped OKF surface (§11)
     const bp = data.by_priority;
     const okBp =
       bp && ["P0", "P1", "P2", "P3"].every((k) => typeof bp[k] === "number");
@@ -400,6 +382,7 @@ export function runCompile(argv = []) {
       return null;
     }
     checkVersion(data, path);
+    checkOkfFields(data, path, { typed: true }); // stamped OKF surface (§11)
     const d = data.domains;
     if (typeof d !== "object" || Array.isArray(d)) {
       fail(path, "domains", "required · { domain: status } flow map");
@@ -489,6 +472,7 @@ export function runCompile(argv = []) {
       }
       checkVersion(data, path);
       const id = checkId(data, path, name);
+      checkOkfFields(data, path, { typed: true }); // stamped `type: Plan Epic|Task|Subtask` etc.
       if (seen.has(id))
         fail(
           path,
@@ -779,6 +763,64 @@ export function runCompile(argv = []) {
     return count;
   }
 
+  // Shipped SOPs are contract-governed like agent cards (§10/§11 — local gate,
+  // never in the manifest): the rafa-* skills the blueprint vendors and the
+  // conductor command. A workforce whose procedures don't parse doesn't ship.
+  function compileShippedSops() {
+    const repoRoot = join(ROOT, "..");
+    let count = 0;
+    const skillsDir = join(repoRoot, ".claude", "skills");
+    if (existsSync(skillsDir))
+      for (const e of readdirSync(skillsDir)) {
+        if (!e.startsWith("rafa-")) continue; // the dev's own skills are theirs
+        const path = join(skillsDir, e, "SKILL.md");
+        if (!existsSync(path)) continue;
+        const { data, error } = parseFrontmatter(read(path));
+        if (error) {
+          fail(path, "frontmatter", error);
+          continue;
+        }
+        count++;
+        if (data.name !== e)
+          fail(path, "name", `must equal skill directory "${e}"`);
+        reqStr(data, "description", path);
+      }
+    const conductor = join(repoRoot, ".claude", "commands", "rafa.md");
+    if (existsSync(conductor)) {
+      const { data, error } = parseFrontmatter(read(conductor));
+      if (error) fail(conductor, "frontmatter", error);
+      else {
+        count++;
+        if (!/^\d+\.\d+\.\d+$/.test(String(data.version ?? "")))
+          fail(conductor, "version", "required · semver MAJOR.MINOR.PATCH");
+        reqStr(data, "description", conductor);
+      }
+    }
+    return count;
+  }
+
+  // sage's learnings (.claude/rafa/learnings/*.md) — the same self-describing
+  // protocol outside the bundle (§11), mechanically gated: OKF quartet + stable
+  // id. ledger.md there is sage's generated index (skipped like a listing).
+  function compileLearnings() {
+    const dir = join(ROOT, "..", ".claude", "rafa", "learnings");
+    let count = 0;
+    for (const path of walk(dir)) {
+      const name = path.split("/").pop();
+      if (name === "ledger.md") continue;
+      const { data, error } = parseFrontmatter(read(path));
+      if (error) {
+        fail(path, "frontmatter", error);
+        continue;
+      }
+      count++;
+      checkId(data, path, name);
+      for (const key of ["type", "title", "description"])
+        reqStr(data, key, path);
+    }
+    return count;
+  }
+
   // ── assemble ─────────────────────────────────────────────────────────────
   const gitOpts = { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }; // no stderr leak
   function gitSha() {
@@ -810,6 +852,9 @@ export function runCompile(argv = []) {
   const plans = compilePlans();
   const activePlanId = compileActivePlanId(plans);
   const agentCards = compileAgentCards();
+  const shippedSops = compileShippedSops();
+  const learnings = compileLearnings();
+  sweepConflicts(ROOT);
 
   // Cross-check: ledger.open / by_priority must match the actual open improvements.
   if (ledger) {
@@ -865,7 +910,7 @@ export function runCompile(argv = []) {
       `${plans.length} plans validated${activePlanId ? ` (active: ${activePlanId})` : ""} (plans travel via the plans channel, not the manifest) · ` +
       `health ${health ? "ok" : "—"} · ledger ${ledger ? "ok" : "—"} · ` +
       `coverage ${coverage ? `${coverage.domains.length} domains` : "—"} · ` +
-      `${agentCards} agent cards (local gate) → ${ROOT}/manifest.json`,
+      `${agentCards} agent cards + ${shippedSops} SOPs${learnings ? ` + ${learnings} learnings` : ""} (local gate) → ${ROOT}/manifest.json`,
   );
   return 0;
 }