@rafinery/cli 0.7.1 → 0.8.1

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 }}"
 
@@ -71,6 +72,7 @@ jobs:
         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
@@ -103,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/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;
 }

package/lib/gate/okf-emit.mjs

@@ -0,0 +1,335 @@
+// The OKF surface emitter — makes the brain repo a conformant Open Knowledge
+// Format v0.1 bundle (contract §11). Runs inside `rafa push` BEFORE compile, so
+// everything it writes goes back through the gate like any authored file.
+//
+// The format machinery lives in @rafinery/okf (parser · concept primitives ·
+// links · citations · indexes · validator · generator); this module is the thin
+// orchestrator that applies the rafa PROFILE to a bundle:
+//
+//   stamp   · missing `type`/`title`/`description`/`timestamp`/`tags` where
+//             DERIVABLE from authored data or git history — authored values are
+//             never rewritten; a value we cannot derive is OMITTED, never guessed.
+//   render  · a generated `# Citations` body section from the `cites:` DSL
+//             (sha-pinned GitHub URLs when the repo is known), inside markers so
+//             re-emits replace their own section and never touch prose.
+//   links   · `[[wikilink]]` → `[Title](/brain/rules/<id>.md)` bundle-relative
+//             markdown links, ONLY when the id resolves (a dangling wikilink is
+//             not-yet-written knowledge — left for the checker's WARN lane).
+//   index   · an `index.md` at the bundle root and in every concept directory
+//             (OKF §6) so a foreign agent reaches any concept from the root in
+//             ≤ 2 hops with no rafa tooling. Root index frontmatter carries
+//             `okf_version: "0.1"` + provenance (repo · codeSha) — the only
+//             index frontmatter OKF permits.
+//
+// Never touched: log.md (OKF-reserved trail), active.md (one-line pointer
+// protocol — documented exception, surfaced by `rafa okf check`), citation-
+// check.* (the checker's artifact), contract.md (push stamps it), plans/**
+// (work objects — the plans channel).
+//
+// CLI:  rafa okf [--root=.rafa] [--repo=owner/repo] [--codeSha=<sha>]
+
+import {
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  existsSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import {
+  parseFrontmatter,
+  OKF_VERSION,
+  OKF_RESERVED,
+  splitConcept,
+  joinConcept,
+  missingStamps,
+  transpileWikilinks,
+  parseCites,
+  citationsSection,
+  upsertCitations,
+  indexBullet,
+  renderIndex,
+  renderRootIndex,
+  FILE_CLASSES,
+  derivedStamps,
+} from "@rafinery/okf";
+
+export function runOkfEmit(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");
+  const gitOpts = (cwd) => ({
+    encoding: "utf8",
+    cwd,
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  const codeGit = (cmd, d = "") => {
+    try {
+      return execSync(cmd, gitOpts(process.cwd())).trim();
+    } catch {
+      return d;
+    }
+  };
+  const repo =
+    arg("repo", "") ||
+    (() => {
+      const origin = codeGit("git remote get-url origin");
+      const m = origin.match(/[/:]([^/:]+)\/([^/]+?)(?:\.git)?\/?$/);
+      return m ? `${m[1]}/${m[2]}` : "";
+    })();
+  const codeSha = arg("codeSha", "") || codeGit("git rev-parse HEAD");
+  const now = new Date().toISOString();
+
+  // Last meaningful change of a bundle file — real signals only (contract §11):
+  // dirty/untracked in the brain repo → it is changing in THIS emit → now;
+  // clean → its last commit time; no git at all → now (the file is being
+  // materialized into a fresh bundle). Never a placeholder.
+  function fileTimestamp(relPath) {
+    try {
+      const dirty = execSync(
+        `git status --porcelain -- ${JSON.stringify(relPath)}`,
+        gitOpts(ROOT),
+      ).trim();
+      if (dirty) return now;
+      const t = execSync(
+        `git log -1 --format=%cI -- ${JSON.stringify(relPath)}`,
+        gitOpts(ROOT),
+      ).trim();
+      return t || now;
+    } catch {
+      return now;
+    }
+  }
+
+  function walk(dir) {
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir)
+      .sort()
+      .flatMap((e) => {
+        const p = join(dir, e);
+        return statSync(p).isDirectory()
+          ? walk(p)
+          : e.endsWith(".md") &&
+              !e.startsWith("_") &&
+              !e.endsWith(".theirs.md") && // pending human decision — compile gates it
+              !OKF_RESERVED.has(e)
+            ? [p]
+            : [];
+      });
+  }
+  const rel = (p) => p.slice(ROOT.length + 1);
+  const read = (p) => readFileSync(p, "utf8");
+
+  // ── collect the bundle's concept files (per the rafa profile registry) ────
+  const concepts = [];
+  const collect = (paths, kind) => {
+    for (const path of paths) {
+      const raw = read(path);
+      const split = splitConcept(raw);
+      const parsed = split ? parseFrontmatter(raw) : { error: "no frontmatter" };
+      if (!split || parsed.error) {
+        console.log(`  ! ${rel(path)} — ${parsed.error} (skipped; compile will fail it)`);
+        continue;
+      }
+      concepts.push({ path, kind, raw, ...split, data: parsed.data });
+    }
+  };
+  for (const [kind, cls] of Object.entries(FILE_CLASSES)) {
+    if (cls.singleton) {
+      const p = join(ROOT, cls.path);
+      if (existsSync(p)) collect([p], kind);
+    } else {
+      collect(walk(join(ROOT, cls.dir)), kind);
+    }
+  }
+
+  // Nothing to materialize is ABSENCE, not success: write no scaffold over an
+  // empty root (wrong --root, or a lazy .rafa before pull/scan). Standalone
+  // `rafa okf` exits 1 on this; push logs it and continues — a lazy instance
+  // is a legitimate state there, and the gates behind it stay honest.
+  if (concepts.length === 0) {
+    console.log(
+      `! rafa okf: no concepts under ${ROOT} — nothing to materialize ` +
+        `(brain-repo clone → --root=. · code repo → .rafa after \`rafa pull --full\` or a scan)`,
+    );
+    return 1;
+  }
+
+  // id → { title, bundlePath } for wikilink transpilation.
+  const resolve = new Map();
+  for (const c of concepts) {
+    if (!c.data.id) continue;
+    resolve.set(String(c.data.id), {
+      title: c.data.title ?? c.data.id,
+      bundlePath: "/" + rel(c.path),
+    });
+  }
+
+  // ── stamp + transform every concept ───────────────────────────────────────
+  let stamped = 0;
+  let transpiled = 0;
+  let citesSections = 0;
+  for (const c of concepts) {
+    const derived = derivedStamps(c.kind, c.data);
+    // timestamp: authored created/found verbatim → brain-repo git history → now.
+    if (!("timestamp" in c.data))
+      derived.timestamp = c.data.created ?? c.data.found ?? fileTimestamp(rel(c.path));
+    const stamps = missingStamps(c.data, derived);
+    let body = c.body;
+    const before = body;
+    body = transpileWikilinks(body, resolve);
+    if (body !== before) transpiled++;
+    const cites = parseCites(c.data.cites);
+    if (cites.length) {
+      body = upsertCitations(body, citationsSection(cites, { repo, sha: codeSha }));
+      citesSections++;
+    }
+    const next = joinConcept(c.fmLines, stamps, body);
+    if (next !== c.raw) {
+      writeFileSync(c.path, next);
+      if (stamps.length) stamped++;
+    }
+  }
+
+  // ── the index.md tree (OKF §6 progressive disclosure) ─────────────────────
+  const byKind = (k) => concepts.filter((c) => c.kind === k);
+  const meta = (c) => {
+    // post-stamp values: authored wins, then what emit just derived
+    const { data } = parseFrontmatter(read(c.path));
+    return {
+      title: data.title ?? data.id ?? rel(c.path),
+      description: data.description ?? data.summary ?? "",
+      name: c.path.split("/").pop(),
+    };
+  };
+  const bullets = (list) =>
+    list.map(meta).map((m) => indexBullet(m.title, m.name, m.description));
+
+  const indexes = [];
+  const writeIndex = (relPath, content) => {
+    writeFileSync(join(ROOT, relPath), content);
+    indexes.push(relPath);
+  };
+
+  for (const [kind, cls] of Object.entries(FILE_CLASSES)) {
+    if (cls.singleton || !cls.indexTitle) continue;
+    const list = byKind(kind);
+    if (!list.length) continue;
+    writeIndex(
+      join(cls.dir, "index.md"),
+      renderIndex([{ heading: cls.indexTitle, bullets: bullets(list) }]),
+    );
+  }
+
+  // Plans index — one section per epic, items listed beneath it (work items
+  // nest in subdirectories, so URLs are relative to plans/).
+  const planItems = byKind("plan");
+  if (planItems.length) {
+    const planUrl = (c) => rel(c.path).replace(/^plans\//, "");
+    writeIndex(
+      "plans/index.md",
+      renderIndex(
+        planItems
+          .filter((c) => c.data.kind === "epic")
+          .map((epic) => ({
+            heading: `${epic.data.title ?? epic.data.id} (${epic.data.id})`,
+            bullets: planItems
+              .filter((c) => c.data.plan === epic.data.id)
+              .map((c) => {
+                const m = meta(c);
+                return indexBullet(m.title, planUrl(c), m.description);
+              }),
+          })),
+      ),
+    );
+  }
+
+  const singleton = (kind, url) => {
+    const c = byKind(kind)[0];
+    return c ? indexBullet(meta(c).title, url, meta(c).description) : null;
+  };
+  if (existsSync(join(ROOT, "brain"))) {
+    const rules = byKind("rule");
+    const playbooks = byKind("playbook");
+    writeIndex(
+      "brain/index.md",
+      renderIndex([
+        {
+          heading: "Knowledge",
+          bullets: [
+            rules.length &&
+              indexBullet("Rules", "rules/", `${rules.length} cited invariants/contracts`),
+            playbooks.length &&
+              indexBullet("Playbooks", "playbooks/", `${playbooks.length} cited how-to/flow notes`),
+          ],
+        },
+        {
+          heading: "Reports",
+          bullets: [
+            singleton("coverage", "coverage.md"),
+            singleton("health", "checklist.md"),
+            existsSync(join(ROOT, "brain", "citation-check.md")) &&
+              indexBullet("Citation check", "citation-check.md", "generated gate report — every cite re-verified"),
+            existsSync(join(ROOT, "brain", "log.md")) &&
+              indexBullet("Scan log", "log.md", "chronological trail of scans and validations"),
+          ],
+        },
+      ]),
+    );
+  }
+  if (existsSync(join(ROOT, "improve"))) {
+    const improvements = byKind("improvement");
+    writeIndex(
+      "improve/index.md",
+      renderIndex([
+        {
+          heading: "Continuous improvement",
+          bullets: [
+            improvements.length &&
+              indexBullet("Improvements", "improvements/", `${improvements.length} items, leverage-ranked`),
+            singleton("ledger", "ledger.md"),
+          ],
+        },
+      ]),
+    );
+  }
+
+  // Root index — the bundle's front door (frontmatter: okf_version + provenance).
+  writeIndex(
+    "index.md",
+    renderRootIndex({
+      title: `${repo || "rafa brain"} — verified knowledge bundle`,
+      intro: [
+        `A rafa brain: every concept is cited into the code${codeSha ? ` at \`${codeSha.slice(0, 12)}\`` : ""} and`,
+        "mechanically re-verified on every push (cite resolution · anchor completeness ·",
+        `absence re-grep · coverage inventory). Conformant Open Knowledge Format v${OKF_VERSION} —`,
+        "any OKF consumer can read it; the verification layer is rafa's.",
+      ],
+      provenance: { ...(repo ? { repo } : {}), ...(codeSha ? { codeSha } : {}) },
+      sections: [
+        {
+          heading: "Contents",
+          bullets: [
+            existsSync(join(ROOT, "brain")) &&
+              indexBullet("Brain", "brain/", "the knowledge map — cited rules + playbooks, coverage, health"),
+            existsSync(join(ROOT, "improve")) &&
+              indexBullet("Improve", "improve/", "bloom's prioritized improvement ledger (P0–P3)"),
+            planItems.length > 0 &&
+              indexBullet("Plans", "plans/", "work-item trees (epic → task → subtask), per-epic index"),
+            existsSync(join(ROOT, "contract.md")) &&
+              indexBullet("Contract", "contract.md", "the file protocol this bundle conforms to (stamped copy)"),
+          ],
+        },
+      ],
+    }),
+  );
+
+  console.log(
+    `✓ rafa okf: ${concepts.length} concepts · ${stamped} stamped · ${transpiled} bodies transpiled · ` +
+      `${citesSections} citations sections · ${indexes.length} indexes → ${ROOT} (OKF v${OKF_VERSION} bundle)`,
+  );
+  return 0;
+}