@rafinery/cli 0.7.1 → 0.8.0

package/lib/gate/verify-citations.mjs

@@ -38,6 +38,11 @@ import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, mkdtemp
 import { execSync } from "node:child_process";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
+// Format utilities only (splitConcept/extractLinks/unresolvedLinks) — the five
+// GATES above stay independently implemented; the LINKS lane below is a
+// non-failing warn lane, so sharing the format package does not couple a gate
+// to the producer it checks.
+import { splitConcept, extractLinks, unresolvedLinks, OKF_RESERVED } from "@rafinery/okf";
 
 export const CHECKER_VERSION = 2; // v1 = the 3-gate era (resolution/completeness/policy)
 
@@ -60,7 +65,26 @@ 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("_")) ? [p] : []; // ignore _*.md scratch
+    if (statSync(p).isDirectory()) return walk(p);
+    // ignore _*.md scratch + OKF-reserved listings (index.md is generated, never
+    // a note) + *.theirs.md conflict copies (compile gates those with a typed error)
+    return e.endsWith(".md") &&
+      !e.startsWith("_") &&
+      !e.endsWith(".theirs.md") &&
+      !OKF_RESERVED.has(e)
+      ? [p]
+      : [];
+  });
+}
+
+// Every .md in the bundle (reserved included — they are legitimate mdlink
+// targets), as "/bundle-relative" paths for the LINKS lane's resolution set.
+function walkBundleMd(dir, base = dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).flatMap((e) => {
+    const p = join(dir, e);
+    if (statSync(p).isDirectory()) return e === ".git" ? [] : walkBundleMd(p, base);
+    return e.endsWith(".md") ? ["/" + p.slice(base.length + 1)] : [];
   });
 }
 
@@ -178,12 +202,24 @@ export function runVerifyCitations(argv = []) {
     return 0;
   }
 
+  // LINKS lane resolution sets — BUNDLE-wide (a note may link across dirs):
+  // ids = concept stems of every knowledge class; paths = every bundle .md as
+  // "/bundle-relative" (reserved files included — legitimate mdlink targets).
+  const BUNDLE_ROOT = join(ROOT, "..");
+  const bundleIds = new Set(
+    ["brain/rules", "brain/playbooks", "improve/improvements"]
+      .flatMap((d) => walk(join(BUNDLE_ROOT, d)))
+      .map((p) => p.split("/").pop().replace(/\.md$/, "")),
+  );
+  const bundlePaths = new Set(walkBundleMd(BUNDLE_ROOT));
+
   const resolution = []; // { note, loc, token, ok, reason }
   const completeness = []; // { note, anchor, site, ok, reason }
   const policy = []; // { note, ok, reason }
   const absence = []; // { note, token, site, ok, reason }
   const inventory = []; // { name, glob, declared, found, ok, reason, paths }
   const warns = []; // { note, phrase }  — heuristic, never fails the gate
+  const linkWarns = []; // { note, kind, target } — dangling links (OKF §5.3), never fails the gate
 
   for (const note of notes) {
     const rel = note.replace(ROOT + "/", "");
@@ -256,6 +292,40 @@ export function runVerifyCitations(argv = []) {
       const m = (title + " · " + summary).match(ABSENCE_HEURISTIC);
       if (m) warns.push({ note: rel, phrase: m[0] });
     }
+
+    // LINKS lane (non-failing, OKF §5.3): every frontmatter `links:` id, body
+    // [[wikilink]], and body bundle-relative markdown link should resolve to a
+    // bundle concept/file. A dangling link may be not-yet-written knowledge —
+    // prism's worklist, never a gate failure.
+    {
+      const raw = lines.join("\n");
+      const split = splitConcept(raw);
+      const body = split ? split.body : raw;
+      const fmLinks = [];
+      let inLinks = false;
+      for (const l of split?.fmLines ?? []) {
+        const flow = l.match(/^links:\s*\[(.*)\]\s*$/);
+        if (flow) {
+          for (const item of flow[1].split(",")) {
+            const v = strip(item);
+            if (v) fmLinks.push(v);
+          }
+          inLinks = false;
+          continue;
+        }
+        if (/^links:\s*$/.test(l)) { inLinks = true; continue; }
+        if (inLinks) {
+          const item = l.match(/^\s*-\s+(.+?)\s*$/);
+          if (item) { fmLinks.push(strip(item[1])); continue; }
+          if (/^\S/.test(l)) inLinks = false;
+        }
+      }
+      const dangling = unresolvedLinks(extractLinks({ links: fmLinks }, body), {
+        ids: bundleIds,
+        paths: bundlePaths,
+      });
+      for (const d of dangling) linkWarns.push({ note: rel, kind: d.kind, target: d.target });
+    }
   }
 
   // INVENTORY — coverage.md declared counts vs tracked reality
@@ -309,10 +379,24 @@ export function runVerifyCitations(argv = []) {
     `## Warns (heuristic, non-failing — existence-shaped title/summary with no \`absent:\` declared): ${warns.length}`,
     ...warns.map((w) => `⚠ ${w.note} — reads as an absence claim ("${w.phrase}") — declare \`absent: <token>\` so the gate can re-grep it, or reword`),
     "",
+    `## Links (non-failing, OKF §5.3 — dangling cross-links, bundle-wide resolution): ${linkWarns.length}`,
+    ...linkWarns.map((w) => `⚠ ${w.note} — ${w.kind} → ${w.target} does not resolve in the bundle (not-yet-written knowledge, a typo, or a moved file)`),
+    "",
     fail ? `**${fail} FAILED.**` : "**All pass.**",
     "",
   ].join("\n");
-  writeFileSync(join(ROOT, "citation-check.md"), md);
+  // The report is itself a generated concept (contract §11): it self-describes.
+  const at = new Date().toISOString();
+  const reportFm = [
+    "---",
+    'type: "Citation Check"',
+    'title: "Citation check report"',
+    `description: "checker v${CHECKER_VERSION} — ${fail ? `${fail} failed` : "all gates pass"} · ${warns.length + linkWarns.length} warn(s)"`,
+    `timestamp: ${at}`,
+    "---",
+    "",
+  ].join("\n");
+  writeFileSync(join(ROOT, "citation-check.md"), reportFm + md);
 
   // Machine record of THIS run — compile folds it into manifest.citations so the
   // platform knows the gate level a brain passed. Recorded, never assumed.
@@ -321,7 +405,7 @@ export function runVerifyCitations(argv = []) {
     JSON.stringify(
       {
         checkerVersion: CHECKER_VERSION,
-        at: new Date().toISOString(),
+        at,
         pass: fail === 0,
         gates: {
           resolution: { pass: resolution.length - rFail.length, total: resolution.length },
@@ -331,6 +415,7 @@ export function runVerifyCitations(argv = []) {
           inventory: { pass: inventory.length - iFail.length, total: inventory.length },
         },
         warns: warns.length,
+        linkWarns: linkWarns.length, // additive optional — compile only reads { checkerVersion, pass, at }
       },
       null,
       2,
@@ -341,6 +426,7 @@ export function runVerifyCitations(argv = []) {
   console.log(
     `resolution ${resolution.length - rFail.length}/${resolution.length} · completeness ${completeness.length - cFail.length}/${completeness.length} · policy ${policy.length - pFail.length}/${policy.length} · absence ${absence.length - aFail.length}/${absence.length} · inventory ${inventory.length - iFail.length}/${inventory.length}` +
       (warns.length ? ` · ${warns.length} warn(s)` : "") +
+      (linkWarns.length ? ` · ${linkWarns.length} dangling link(s)` : "") +
       (fail ? ` · ${fail} FAILED` : " · all pass"),
   );
   return fail ? 1 : 0;

package/lib/mcp-client.mjs

@@ -26,7 +26,9 @@ const readJson = (file) => {
 // The platform repo id this working copy is provisioned for.
 export function repoIdOf(cwd) {
   const stamp = readStamp(cwd);
-  return typeof stamp.repoId === "string" && stamp.repoId !== "" ? stamp.repoId : null;
+  return typeof stamp.repoId === "string" && stamp.repoId !== ""
+    ? stamp.repoId
+    : null;
 }
 
 export function resolveMcp(cwd) {
@@ -66,26 +68,51 @@ let rpcId = 0;
 // message on transport or tool errors.
 export async function callTool(cwd, tool, args = {}) {
   const { repoId, key, mcpUrl } = resolveMcp(cwd);
-  const res = await fetch(mcpUrl, {
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-      authorization: `Bearer ${key}`,
-    },
-    body: JSON.stringify({
-      jsonrpc: "2.0",
-      id: ++rpcId,
-      method: "tools/call",
-      params: { name: tool, arguments: { repo: repoId, ...args } },
-    }),
-  });
+  // A localhost platform is only reachable on the machine running the dev
+  // server — on a CI runner it is a guaranteed dead end; say so up front
+  // instead of a bare "fetch failed".
+  if (
+    process.env.CI &&
+    /\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0)[:/]/.test(mcpUrl)
+  )
+    throw new Error(
+      `platform MCP url is ${mcpUrl} — a localhost dev server is not reachable from CI.\n` +
+        `  Set the RAFA_MCP_URL secret to your deployed platform's /api/mcp URL, or run the\n` +
+        `  session fallback instead (/rafa distill <branch> in Claude Code).`,
+    );
+  let res;
+  try {
+    res = await fetch(mcpUrl, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${key}`,
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: ++rpcId,
+        method: "tools/call",
+        params: { name: tool, arguments: { repo: repoId, ...args } },
+      }),
+    });
+  } catch (e) {
+    throw new Error(
+      `cannot reach the platform MCP at ${mcpUrl} (${e instanceof Error ? e.message : e}) — ` +
+        `check the URL (RAFA_MCP_URL / credentials.json / .mcp.json) and that the platform is deployed and reachable from here.`,
+    );
+  }
   if (res.status === 401)
-    throw new Error("agent key rejected (401) — revoked or wrong platform; mint a new one (repo → Agent access)");
+    throw new Error(
+      "agent key rejected (401) — revoked or wrong platform; mint a new one (repo → Agent access)",
+    );
   if (res.status === 429)
     throw new Error("rate limited (429) — back off and retry");
   if (!res.ok) throw new Error(`MCP endpoint returned HTTP ${res.status}`);
   const body = await res.json();
-  if (body.error) throw new Error(`MCP error: ${body.error.message ?? JSON.stringify(body.error)}`);
+  if (body.error)
+    throw new Error(
+      `MCP error: ${body.error.message ?? JSON.stringify(body.error)}`,
+    );
   const result = body.result ?? {};
   const payload = result.structuredContent ?? null;
   if (result.isError) {

package/lib/okf.mjs

@@ -0,0 +1,110 @@
+// rafa okf — the OKF surface commands (contract §11). The format machinery is
+// @rafinery/okf; the rafa profile decides where classes live and what stamps
+// are derivable.
+//
+//   rafa okf                 materialize the surface on .rafa (stamps · link
+//                            transpile · citations sections · index tree).
+//                            Runs automatically inside `rafa push`.
+//   rafa okf check           OKF §9 conformance walk of the bundle — errors
+//                            fail (exit 1), soft guidance warns. Exemptions
+//                            (active.md) are explicit and surfaced.
+//   rafa okf new <class> <id> [--key=value …] [--cite="f:l :: tok" …] [--link=id …]
+//                            mint a conformant concept skeleton in the class's
+//                            directory. Nothing is invented: flags you omit are
+//                            absent, and `rafa compile` fails required ones
+//                            loudly — that is the validate-and-correct loop.
+
+import { existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { runOkfEmit } from "./gate/okf-emit.mjs";
+import { SCHEMA_VERSION } from "./gate/compile.mjs";
+import {
+  OKF_VERSION,
+  validateBundle,
+  newConcept,
+  FILE_CLASSES,
+  RAFA_EXEMPT,
+} from "@rafinery/okf";
+
+export default async function okf(args = []) {
+  const [sub, ...rest] = args[0]?.startsWith("--") ? [undefined, ...args] : args;
+  const ROOT =
+    (args.find((a) => a.startsWith("--root=")) ?? "").slice(7) || ".rafa";
+
+  if (sub === undefined || sub === "emit") {
+    process.exit(runOkfEmit(args.filter((a) => a.startsWith("--"))));
+  }
+
+  if (sub === "check") {
+    const { conformant, checked, errors, warnings } = validateBundle(ROOT, {
+      exempt: RAFA_EXEMPT,
+    });
+    for (const e of errors) console.log(`✗ ${e.path} — ${e.rule}`);
+    for (const w of warnings) console.log(`⚠ ${w.path} — ${w.rule}`);
+    console.log(
+      `${conformant ? "✓" : "✗"} rafa okf check: ${checked} files · ` +
+        `${errors.length} error(s) · ${warnings.length} warning(s) — ` +
+        (conformant ? `bundle conforms to OKF v${OKF_VERSION}` : "bundle is NOT conformant"),
+    );
+    process.exit(conformant ? 0 : 1);
+  }
+
+  if (sub === "new") {
+    const [cls, id] = rest.filter((a) => !a.startsWith("--"));
+    const registry = FILE_CLASSES[cls];
+    if (!registry || registry.singleton) {
+      console.error(
+        `✗ rafa okf new: <class> must be one of ${Object.entries(FILE_CLASSES)
+          .filter(([, c]) => !c.singleton)
+          .map(([k]) => k)
+          .join(" | ")} (singletons are authored at their fixed path)`,
+      );
+      process.exit(1);
+    }
+    if (!id) {
+      console.error("✗ rafa okf new: missing <id> (kebab-case, becomes the filename stem)");
+      process.exit(1);
+    }
+    const fields = { schemaVersion: SCHEMA_VERSION }; // never a literal — moves with the contract
+    const listFields = { cites: [], links: [] };
+    for (const a of rest.filter((a) => a.startsWith("--"))) {
+      const m = a.match(/^--([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+      if (!m) continue;
+      const [, key, value] = m;
+      if (key === "cite") listFields.cites.push(value);
+      else if (key === "link") listFields.links.push(value);
+      else if (key !== "root") fields[key] = value;
+    }
+    // The improvement class's OKF type is constant; notes author their own
+    // contract enum via --type (compile owns the enum — no default here).
+    const type = fields.type ?? registry.okfType ?? "";
+    delete fields.type;
+    let content;
+    try {
+      content = newConcept({ type, id, fields, listFields });
+    } catch (e) {
+      console.error(`✗ rafa okf new: ${e instanceof Error ? e.message : e}`);
+      console.error(
+        cls === "improvement"
+          ? ""
+          : "  notes require --type=<contract|convention|flow|how-to> (the compile enum)",
+      );
+      process.exit(1);
+    }
+    const path = join(ROOT, registry.dir, `${id}.md`);
+    if (existsSync(path)) {
+      console.error(`✗ rafa okf new: ${path} already exists — refusing to overwrite`);
+      process.exit(1);
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+    console.log(
+      `✓ rafa okf new: ${path} — now write the body + fill required fields, ` +
+        `then \`rafa verify-citations\` + \`rafa compile\` gate it.`,
+    );
+    process.exit(0);
+  }
+
+  console.error(`✗ rafa okf: unknown subcommand "${sub}" (emit | check | new)`);
+  process.exit(1);
+}

package/lib/push.mjs

@@ -14,6 +14,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { runCompile } from "./gate/compile.mjs";
 import { runVerifyCitations } from "./gate/verify-citations.mjs";
+import { runOkfEmit } from "./gate/okf-emit.mjs";
 import { ensureBrainRepo, remoteDefaultBranch, inDir, die } from "./brain-repo.mjs";
 import { CLI_VERSION } from "./releases.mjs";
 
@@ -40,6 +41,38 @@ export default async function push(args = []) {
     /* no origin — manifest.repo stays "" */
   }
 
+  // ── stamped contract copy rides the push (before emit so the root index
+  // lists it from the very first push) ──
+  const canonical = join(ROOT, ".claude", "rafa", "contract.md");
+  if (existsSync(canonical)) {
+    // The copy is itself a generated concept (contract §11): it self-describes.
+    const stampFm =
+      `---\n` +
+      `type: Reference\n` +
+      `title: "rafa brain contract (stamped copy)"\n` +
+      `description: "the file protocol this bundle conforms to — canonical: .claude/rafa/contract.md in the code repo"\n` +
+      `timestamp: ${new Date().toISOString()}\n` +
+      `---\n\n`;
+    const stampHeader =
+      `<!-- STAMPED COPY — canonical: .claude/rafa/contract.md in the code repo.\n` +
+      `     cli: ${CLI_VERSION} · brain-for: ${codeSha} · stamped: ${new Date().toISOString()} -->\n\n`;
+    writeFileSync(join(rafaDir, "contract.md"), stampFm + stampHeader + readFileSync(canonical, "utf8"));
+  } else {
+    console.log(
+      "  ! no .claude/rafa/contract.md in this repo — pushing without the stamped contract copy " +
+        "(run `rafa update` to vendor it)",
+    );
+  }
+
+  // ── OKF surface (in-process, contract §11) ──
+  // Materialize the interchange surface BEFORE the gates so everything the
+  // emitter writes is checked like any authored file: stamps (type/description/
+  // timestamp/tags where derivable), wikilink→markdown-link transpile, generated
+  // `# Citations` sections, and the index.md tree. A pushed brain repo is a
+  // conformant OKF v0.1 bundle any foreign consumer can read without rafa.
+  console.log("• rafa okf — materializing the OKF surface (stamps · links · citations · indexes) …");
+  runOkfEmit([`--repo=${repoFull}`]);
+
   // ── citation gate (in-process) ──
   // Re-run the checker HERE so the record that rides the push is the record of
   // THIS push — a stale/hand-stamped citation-check.json can never ship
@@ -70,23 +103,6 @@ export default async function push(args = []) {
         "authoring agent (atlas/bloom/prism) correct them, then re-push.",
     );
 
-  // ── stamped contract copy rides the push ──
-  // The canonical contract lives in the CODE repo (.claude/rafa/contract.md);
-  // the brain repo carries a stamped copy so any reader of the brain repo knows
-  // exactly which contract version this brain conforms to.
-  const canonical = join(ROOT, ".claude", "rafa", "contract.md");
-  if (existsSync(canonical)) {
-    const stampHeader =
-      `<!-- STAMPED COPY — canonical: .claude/rafa/contract.md in the code repo.\n` +
-      `     cli: ${CLI_VERSION} · brain-for: ${codeSha} · stamped: ${new Date().toISOString()} -->\n\n`;
-    writeFileSync(join(rafaDir, "contract.md"), stampHeader + readFileSync(canonical, "utf8"));
-  } else {
-    console.log(
-      "  ! no .claude/rafa/contract.md in this repo — pushing without the stamped contract copy " +
-        "(run `rafa update` to vendor it)",
-    );
-  }
-
   inRafa("git add -A");
   try {
     inRafa(`git commit -m "brain: scan" -m "brain-for: ${codeSha}"`);

package/lib/releases.mjs

@@ -168,6 +168,41 @@ export const RELEASES = [
       "never ship). Brain data schema unchanged; no re-scan; adopt with `rafa update` " +
       "(re-vendors hooks, merges settings + statusline, installs the pre-push boundary).",
   },
+  {
+    version: "0.8.0",
+    contract: 1,
+    plans: 2,
+    requires: "update",
+    recommends: ["push"],
+    summary:
+      "THE OKF SURFACE (contract §11): every generated .md self-describes, and a pushed " +
+      "brain repo is a conformant Open Knowledge Format v0.1 bundle any foreign agent can " +
+      "read without rafa tooling. New @rafinery/okf package (zero-dep: strict parser · " +
+      "concept primitives · links · citations · indexes · §9 validator · generator) — the " +
+      "gate now imports the parser from it. New `rafa okf` (emit — runs inside push, before " +
+      "the gates, so its output is gate-checked) · `rafa okf check` (conformance walk; " +
+      "documented exemptions surface as warnings) · `rafa okf new <class> <id>` (mint a " +
+      "conformant concept skeleton; the rafa-okf skill is the SOP). Emit stamps ONLY " +
+      "derivable values (description from summary · singleton type/title from the class " +
+      "registry · timestamp from authored created:/found: → brain-repo git history → the " +
+      "emit run; never a guess), renders `# Citations` (sha-pinned GitHub URLs when the " +
+      "repo is known) inside okf:citations markers, transpiles resolvable [[wikilinks]] to " +
+      "bundle-relative markdown links (the authored form going forward — SOPs updated), and " +
+      "generates the index.md tree (root index carries okf_version + repo + codeSha). " +
+      "Plan items carry the surface too (type: Plan Epic|Task|Subtask derived from kind; " +
+      "per-epic plans/index.md). " +
+      "Checker: non-failing LINKS warn lane (dangling link = not-yet-written knowledge, " +
+      "OKF §5.3 — prism's worklist; closes the 2026-06-19 [[…]]-lint ratchet) and the " +
+      "citation-check.md report now self-describes. index.md/log.md are reserved names " +
+      "(skipped by every walker). Agent cards: okf-surface duty on atlas · bloom · prism · " +
+      "sage; okf-awareness on compass (bundles are PORTABLE — person-scoped content never " +
+      "lands in one); the conductor verb map carries the protocol note. TOTALITY: "
+      + "*.theirs.md conflicts fail compile with a typed rule (walkers skip them); "
+      + "shipped SOPs (rafa-* skills + conductor) and sage learnings are compile-gated "
+      + "local classes beside the agent cards. WIRE UNCHANGED: " +
+      "manifest shape + schemaVersion 1 + checker v2 — all additive " +
+      "(§8); no re-scan, adopt with `rafa update`, then `rafa push` materializes the bundle.",
+  },
 ];
 
 // The release this CLI build ships (last entry).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafinery/cli",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "rafa — the AI engineer CLI. Vendors the rafa blueprint into your repo (shadcn-style) and runs the deterministic contract gates.",
   "type": "module",
   "bin": {
@@ -15,13 +15,12 @@
   "engines": {
     "node": ">=18"
   },
+  "dependencies": {
+    "@rafinery/okf": "0.1.0"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "bundle": "node scripts/bundle-blueprint.mjs",
-    "prepare": "node scripts/bundle-blueprint.mjs"
-  },
   "keywords": [
     "rafa",
     "rafinery",
@@ -37,5 +36,9 @@
     "url": "git+https://github.com/rafinery-ai/rafinery.git",
     "directory": "packages/cli"
   },
-  "homepage": "https://github.com/rafinery-ai/rafinery/tree/main/packages/cli"
-}
+  "homepage": "https://github.com/rafinery-ai/rafinery/tree/main/packages/cli",
+  "scripts": {
+    "bundle": "node scripts/bundle-blueprint.mjs",
+    "test": "node --test"
+  }
+}