@rafinery/cli 0.2.2 → 0.4.0

package/blueprint/.rafa/bin/rafa-compile.mjs

@@ -1,390 +0,0 @@
-#!/usr/bin/env node
-/**
- * rafa compile — the deterministic gate between the agents' markdown and the
- * platform. Reads every brain file, parses its frontmatter with a STRICT grammar
- * (see .rafa/contract.md §0), validates it against the contract, and on success
- * emits .rafa/manifest.json — the exact JSON the platform ingests.
- *
- * NO ASSUMPTIONS: a missing required field, a bad enum, or a malformed cite is a
- * hard error (path · field · rule). It never fills a default for a required field.
- * Exits 1 with a structured error list so the authoring agent can correct + retry.
- *
- * Usage:  node .rafa/bin/rafa-compile.mjs [--repo=owner/repo] [--branch=main] [--codeSha=<sha>]
- */
-import {
-  readFileSync,
-  writeFileSync,
-  readdirSync,
-  existsSync,
-  statSync,
-} from "node:fs";
-import { join } from "node:path";
-import { execSync } from "node:child_process";
-
-const SCHEMA_VERSION = 1;
-const arg = (k, d) => {
-  const m = process.argv.find((a) => a.startsWith(`--${k}=`));
-  return m ? m.slice(k.length + 3) : d;
-};
-const ROOT = arg("root", ".rafa");
-// Paths in the manifest are relative to the brain-repo root (`.rafa/` IS the root),
-// so the platform can fetch a prose body straight from the brain repo.
-const rel = (p) => (p.startsWith(ROOT + "/") ? p.slice(ROOT.length + 1) : p);
-
-const errors = [];
-const fail = (path, field, rule) => errors.push({ path, field, rule });
-
-// ── strict frontmatter parser (contract §0 grammar) ─────────────────────────
-// Legal value forms only: scalar | "quoted" | [flow,list] | { flow: map }.
-// Plus `key:` followed by `  - item` block lists. 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" }.
-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.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 };
-}
-
-// ── validators (contract §2–§6) ──────────────────────────────────────────────
-const CITE_RE = /^(.+):(\d+(?:-\d+)?)\s*::\s*(.+)$/;
-function parseCites(list, path) {
-  if (!Array.isArray(list) || list.length === 0) {
-    fail(path, "cites", "required · ≥ 1");
-    return [];
-  }
-  const out = [];
-  for (const c of list) {
-    const m = String(c).match(CITE_RE);
-    if (!m) {
-      fail(path, "cites", `malformed cite: ${JSON.stringify(c)}`);
-      continue;
-    }
-    out.push({ file: m[1].trim(), line: m[2], token: m[3].trim() });
-  }
-  return out;
-}
-const isEnum = (v, allowed) => allowed.includes(v);
-function reqStr(d, key, path) {
-  const v = d[key];
-  if (typeof v !== "string" || v.trim() === "") {
-    fail(path, key, "required · non-empty string");
-    return "";
-  }
-  return v;
-}
-function reqEnum(d, key, allowed, path) {
-  const v = d[key];
-  if (!isEnum(v, allowed)) {
-    fail(path, key, `required · one of ${allowed.join("|")}`);
-    return allowed[0];
-  }
-  return v;
-}
-function checkVersion(d, path) {
-  if (d.schemaVersion !== SCHEMA_VERSION)
-    fail(path, "schemaVersion", `must be ${SCHEMA_VERSION}`);
-}
-function checkId(d, path, name) {
-  const stem = name.replace(/\.md$/, "");
-  if (d.id !== stem) fail(path, "id", `must equal filename stem "${stem}"`);
-  return stem;
-}
-
-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]
-        : [];
-  });
-}
-const read = (p) => readFileSync(p, "utf8");
-
-function compileNotes(kind, dir) {
-  const notes = [];
-  for (const path of walk(dir)) {
-    const name = path.split("/").pop();
-    const { data, error } = parseFrontmatter(read(path));
-    if (error) {
-      fail(path, "frontmatter", error);
-      continue;
-    }
-    checkVersion(data, path);
-    const id = checkId(data, path, name);
-    notes.push({
-      id,
-      kind,
-      type: reqEnum(data, "type", ["contract", "convention", "flow", "how-to"], path),
-      domain: reqStr(data, "domain", path),
-      title: reqStr(data, "title", path),
-      summary: reqStr(data, "summary", path),
-      links: Array.isArray(data.links) ? data.links.map(String) : [],
-      ...(data.failure === "silent" || data.failure === "loud"
-        ? { failure: data.failure }
-        : {}),
-      cites: parseCites(data.cites, path),
-      path: rel(path),
-    });
-  }
-  return notes;
-}
-
-function compileImprovements(dir) {
-  const out = [];
-  for (const path of walk(dir)) {
-    const name = path.split("/").pop();
-    const { data, error } = parseFrontmatter(read(path));
-    if (error) {
-      fail(path, "frontmatter", error);
-      continue;
-    }
-    checkVersion(data, path);
-    const id = checkId(data, path, name);
-    const lev = data.leverage;
-    if (
-      typeof lev !== "object" ||
-      !isEnum(lev?.impact, ["low", "medium", "high"]) ||
-      !isEnum(lev?.effort, ["low", "medium", "high"])
-    )
-      fail(path, "leverage", "required · { impact, effort } ∈ low|medium|high");
-    out.push({
-      id,
-      priority: reqEnum(data, "priority", ["P0", "P1", "P2", "P3"], path),
-      lens: reqEnum(
-        data,
-        "lens",
-        ["security", "correctness", "performance", "architecture", "product", "ops"],
-        path,
-      ),
-      status: reqEnum(data, "status", ["open", "backlog", "fixed", "wontfix"], path),
-      title: reqStr(data, "title", path),
-      summary: reqStr(data, "summary", path),
-      fix: reqStr(data, "fix", path),
-      leverage: {
-        impact: lev?.impact ?? "low",
-        effort: lev?.effort ?? "low",
-      },
-      blastRadius: Array.isArray(data.blast_radius)
-        ? data.blast_radius.map(String)
-        : [],
-      cites: parseCites(data.cites, path),
-      path: rel(path),
-    });
-  }
-  return out;
-}
-
-function compileHealth() {
-  const path = join(ROOT, "brain", "checklist.md");
-  if (!existsSync(path)) return null;
-  const { data, error } = parseFrontmatter(read(path));
-  if (error) {
-    fail(path, "frontmatter", error);
-    return null;
-  }
-  checkVersion(data, path);
-  const g = data.gates,
-    c = data.counts;
-  if (!isEnum(g?.fidelity, ["pass", "fail"]) || !isEnum(g?.coverage, ["pass", "fail"]))
-    fail(path, "gates", "required · { fidelity, coverage } ∈ pass|fail");
-  if (
-    typeof c?.blockers !== "number" ||
-    typeof c?.majors !== "number" ||
-    typeof c?.minors !== "number"
-  )
-    fail(path, "counts", "required · { blockers, majors, minors } ints");
-  if (typeof data.score !== "number") fail(path, "score", "required · 0–100 int");
-  return {
-    verdict: reqEnum(data, "verdict", ["PASS", "ITERATE"], path),
-    score: typeof data.score === "number" ? data.score : 0,
-    gates: { fidelity: g?.fidelity ?? "fail", coverage: g?.coverage ?? "fail" },
-    counts: {
-      blockers: c?.blockers ?? 0,
-      majors: c?.majors ?? 0,
-      minors: c?.minors ?? 0,
-    },
-  };
-}
-
-function compileLedger() {
-  const path = join(ROOT, "improve", "ledger.md");
-  if (!existsSync(path)) return null;
-  const { data, error } = parseFrontmatter(read(path));
-  if (error) {
-    fail(path, "frontmatter", error);
-    return null;
-  }
-  checkVersion(data, path);
-  const bp = data.by_priority;
-  const okBp =
-    bp &&
-    ["P0", "P1", "P2", "P3"].every((k) => typeof bp[k] === "number");
-  if (!okBp) fail(path, "by_priority", "required · { P0, P1, P2, P3 } ints");
-  if (typeof data.open !== "number") fail(path, "open", "required · int");
-  if (typeof data.debt_score !== "number")
-    fail(path, "debt_score", "required · int");
-  return {
-    open: typeof data.open === "number" ? data.open : 0,
-    debtScore: typeof data.debt_score === "number" ? data.debt_score : 0,
-    byPriority: okBp
-      ? { P0: bp.P0, P1: bp.P1, P2: bp.P2, P3: bp.P3 }
-      : { P0: 0, P1: 0, P2: 0, P3: 0 },
-  };
-}
-
-function compileCoverage() {
-  const path = join(ROOT, "brain", "coverage.md");
-  if (!existsSync(path)) return null;
-  const { data, error } = parseFrontmatter(read(path));
-  if (error) {
-    fail(path, "frontmatter", error);
-    return null;
-  }
-  checkVersion(data, path);
-  const d = data.domains;
-  if (typeof d !== "object" || Array.isArray(d)) {
-    fail(path, "domains", "required · { domain: status } flow map");
-    return { domains: [] };
-  }
-  const STATUS = ["mapped", "thin", "stubbed", "empty"];
-  const domains = [];
-  for (const [domain, status] of Object.entries(d)) {
-    if (!STATUS.includes(status))
-      fail(path, `domains.${domain}`, `status ∈ ${STATUS.join("|")}`);
-    domains.push({ domain, status: String(status) });
-  }
-  return { domains };
-}
-
-// ── assemble ─────────────────────────────────────────────────────────────────
-const gitOpts = { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }; // no stderr leak
-function gitSha() {
-  try {
-    return execSync("git rev-parse HEAD", gitOpts).trim();
-  } catch {
-    return arg("codeSha", "");
-  }
-}
-function gitBranch() {
-  try {
-    return execSync("git rev-parse --abbrev-ref HEAD", gitOpts).trim();
-  } catch {
-    return arg("branch", "main");
-  }
-}
-
-const notes = [
-  ...compileNotes("rule", join(ROOT, "brain", "rules")),
-  ...compileNotes("playbook", join(ROOT, "brain", "playbooks")),
-];
-const improvements = compileImprovements(join(ROOT, "improve", "improvements"));
-const health = compileHealth();
-const ledger = compileLedger();
-const coverage = compileCoverage();
-
-// Cross-check: ledger.open / by_priority must match the actual open improvements.
-if (ledger) {
-  const open = improvements.filter((i) => i.status === "open");
-  const bp = { P0: 0, P1: 0, P2: 0, P3: 0 };
-  for (const i of open) bp[i.priority]++;
-  if (ledger.open !== open.length)
-    fail("improve/ledger.md", "open", `says ${ledger.open}, rows have ${open.length}`);
-  for (const k of ["P0", "P1", "P2", "P3"])
-    if (ledger.byPriority[k] !== bp[k])
-      fail("improve/ledger.md", `by_priority.${k}`, `says ${ledger.byPriority[k]}, rows have ${bp[k]}`);
-}
-
-if (errors.length) {
-  console.error(`✗ rafa compile: ${errors.length} contract violation(s)\n`);
-  for (const e of errors) console.error(`  ${e.path}  ·  ${e.field}  ·  ${e.rule}`);
-  console.error(`\nFix these files to match .rafa/contract.md, then re-run compile.`);
-  process.exit(1);
-}
-
-const manifest = {
-  schemaVersion: SCHEMA_VERSION,
-  generatedAt: new Date().toISOString(),
-  repo: arg("repo", ""),
-  branch: gitBranch(),
-  codeSha: gitSha(),
-  health,
-  ledger,
-  coverage,
-  notes,
-  improvements,
-  plans: [],
-};
-writeFileSync(join(ROOT, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
-console.log(
-  `✓ rafa compile: ${notes.length} notes · ${improvements.length} improvements · ` +
-    `health ${health ? "ok" : "—"} · ledger ${ledger ? "ok" : "—"} · ` +
-    `coverage ${coverage ? `${coverage.domains.length} domains` : "—"} → .rafa/manifest.json`,
-);

package/blueprint/.rafa/bin/rafa-push.mjs

@@ -1,75 +0,0 @@
-#!/usr/bin/env node
-/**
- * rafa push — commit `.rafa/` and push it to the brain remote.
- *
- * `.rafa/` is its own git repo (set up by `rafa init`, remote `origin` = your brain
- * repo). This commits the current brain/improve state and pushes it, stamped
- * `brain-for: <code HEAD sha>` so the brain stays anchored to the code it describes.
- * Uses YOUR git auth — no credential passes through rafa. Run from the code repo root.
- */
-import { execSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-
-const die = (m) => {
-  console.error(`✗ ${m}`);
-  process.exit(1);
-};
-
-const ROOT = process.cwd();
-const RAFA = join(ROOT, ".rafa");
-if (!existsSync(join(RAFA, ".git")))
-  die("No `.rafa/` git repo here — run `rafa init` first, from your code repo root.");
-
-const inRafa = (cmd) =>
-  execSync(cmd, { cwd: RAFA, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" }).trim();
-
-try {
-  inRafa("git remote get-url origin");
-} catch {
-  die("`.rafa/` has no `origin` remote (the brain repo). Re-run `rafa init`.");
-}
-
-// Anchor the brain to the current code HEAD.
-let codeSha = "unknown";
-try {
-  codeSha = execSync("git rev-parse --short HEAD", { cwd: ROOT, encoding: "utf8" }).trim();
-} catch {
-  /* code repo may have no commits yet — fine */
-}
-
-// The CODE repo's full_name — stamped into the manifest as its identity.
-let repoFull = "";
-try {
-  const origin = execSync("git remote get-url origin", { cwd: ROOT, encoding: "utf8" }).trim();
-  const m = origin.match(/[/:]([^/:]+)\/([^/]+?)(?:\.git)?\/?$/);
-  if (m) repoFull = `${m[1]}/${m[2]}`;
-} catch {
-  /* no origin — manifest.repo stays "" */
-}
-
-// ── contract gate ──
-// Compile + validate the brain. A schema-invalid brain NEVER leaves the machine —
-// the platform ingests JSON, so what we push must already conform to the contract.
-console.log("• rafa compile — validating against .rafa/contract.md …");
-try {
-  execSync(`node ${join(RAFA, "bin", "rafa-compile.mjs")} --repo=${repoFull}`, {
-    cwd: ROOT,
-    stdio: "inherit",
-  });
-} catch {
-  die(
-    "brain failed the contract (see errors above). Fix the files, or have the " +
-      "authoring agent (atlas/bloom/prism) correct them, then re-push.",
-  );
-}
-
-inRafa("git add -A");
-try {
-  inRafa(`git commit -m "brain: scan" -m "brain-for: ${codeSha}"`);
-} catch {
-  console.log("• nothing new to commit — pushing current state");
-}
-inRafa("git branch -M main");
-inRafa("git push -u origin main");
-console.log(`✓ Pushed .rafa/ → brain remote (brain-for: ${codeSha})`);

package/blueprint/.rafa/bin/verify-citations.mjs

@@ -1,153 +0,0 @@
-#!/usr/bin/env node
-/**
- * Deterministic citation checker for the atlas scan output. Three gates:
- *
- *  RESOLUTION (B1)   — every cite `- <file>:<line>[-<end>] :: <token>` points at a line
- *                      that actually contains <token>. Catches off-by-N / wrong-file.
- *  COMPLETENESS (B2) — a note may declare `anchor: <token>`; the checker greps it repo-wide
- *                      (code only, docs excluded) and asserts EVERY hit is a cited site.
- *                      Catches the "3-place vs 5-place" omission bug.
- *  POLICY            — every `type: contract` MUST declare `anchor:` — a greppable token,
- *                      or `anchor: none` for composition/ordering contracts that don't grep
- *                      as one token. So completeness can't be silently skipped (closes F1:
- *                      the guarantee is mandatory, not opt-in; exemptions are explicit).
- *
- * Writes a generated report to .rafa/brain/citation-check.md (don't hand-paste it).
- * Exits 1 on any failure. Run from repo root:  node .rafa/bin/verify-citations.mjs
- */
-import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, mkdtempSync, rmSync } from "node:fs";
-import { execSync } from "node:child_process";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-
-const arg = (k, d) => { const m = process.argv.find((a) => a.startsWith(`--${k}=`)); return m ? m.slice(k.length + 3) : d; };
-const ROOT = arg("root", ".rafa/brain");                                   // --root=.rafa/improve for the improve ledger
-const NOTE_DIRS = arg("dirs", "rules,playbooks").split(",").filter(Boolean);  // --dirs=improvements
-const CITE = /^\s*-\s+(.+?):(\d+)(?:-(\d+))?\s*::\s*(.+?)\s*$/; // - file:start[-end] :: token
-const ANCHOR = /^anchor:\s*(.+?)\s*$/;
-const TYPE = /^type:\s*(.+?)\s*$/;
-
-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
-  });
-}
-
-function gitGrep(token) {
-  try {
-    const out = execSync(`git grep -nF -e ${JSON.stringify(token)}`, { encoding: "utf8" });
-    return out.split("\n").filter(Boolean).map((l) => {
-      const m = l.match(/^(.+?):(\d+):/);
-      return m ? { file: m[1], line: +m[2] } : null;
-    }).filter(Boolean);
-  } catch (e) {
-    if (e.status === 1) return []; // git grep: no matches
-    throw e;
-  }
-}
-
-function citeResolves(file, start, end, token) {
-  if (!existsSync(file)) return { ok: false, reason: "file missing" };
-  const src = readFileSync(file, "utf8").split("\n");
-  if (start < 1 || end > src.length) return { ok: false, reason: `lines ${start}-${end} out of range (${src.length})` };
-  if (src.slice(start - 1, end).some((l) => l.includes(token))) return { ok: true, reason: "" };
-  return { ok: false, reason: `token not on ${start}${end !== start ? "-" + end : ""}` };
-}
-
-// --selftest: prove the resolution logic fails on a bad cite and passes a good one, on a
-// throwaway temp file (no brain/repo pollution). prism runs this as its mutation probe —
-// re-running the checker is not proof it still works; this is.
-if (process.argv.includes("--selftest")) {
-  const dir = mkdtempSync(join(tmpdir(), "vc-selftest-"));
-  const f = join(dir, "sample.txt");
-  writeFileSync(f, "alpha\nTOKEN beta\ngamma\n");
-  const good = citeResolves(f, 2, 2, "TOKEN").ok; // expect true
-  const bad = citeResolves(f, 1, 1, "TOKEN").ok;  // expect false (off-by-one)
-  rmSync(dir, { recursive: true, force: true });
-  const sane = good === true && bad === false;
-  console.log(`checker self-test: ${sane ? "PASS" : "FAIL"} — good cite=${good} (expect true), bad cite=${bad} (expect false)`);
-  process.exit(sane ? 0 : 1);
-}
-
-const notes = NOTE_DIRS.flatMap((d) => walk(join(ROOT, d)));
-if (notes.length === 0) {
-  console.log(`No notes under ${ROOT}/{${NOTE_DIRS.join(",")}}/ — run a scan first.`);
-  process.exit(0);
-}
-
-const resolution = []; // { note, loc, token, ok, reason }
-const completeness = []; // { note, anchor, site, ok, reason }
-const policy = []; // { note, ok, reason }
-
-for (const note of notes) {
-  const rel = note.replace(ROOT + "/", "");
-  const lines = readFileSync(note, "utf8").split("\n");
-  const cites = [];
-  const anchors = [];
-  let noteType = "";
-  let fence = 0;
-  for (const line of lines) {
-    if (line.trim() === "---") { fence++; if (fence >= 2) break; continue; }
-    if (fence !== 1) continue;
-    const c = line.match(CITE);
-    if (c) { cites.push({ file: c[1], start: +c[2], end: c[3] ? +c[3] : +c[2], token: c[4] }); continue; }
-    const a = line.match(ANCHOR);
-    if (a) { anchors.push(a[1].replace(/\s+#.*$/, "").replace(/^["']|["']$/g, "").trim()); continue; }
-    const t = line.match(TYPE);
-    if (t) noteType = t[1].replace(/\s+#.*$/, "").trim();
-  }
-
-  // POLICY — every contract must declare an anchor (token or explicit `none`)
-  if (noteType === "contract") {
-    const ok = anchors.length > 0;
-    policy.push({ note: rel, ok, reason: ok ? "" : "type: contract must declare `anchor: <token>` (or `anchor: none` for composition/ordering contracts)" });
-  }
-
-  // RESOLUTION
-  for (const ct of cites) {
-    const { ok, reason } = citeResolves(ct.file, ct.start, ct.end, ct.token);
-    resolution.push({ note: rel, loc: `${ct.file}:${ct.start}${ct.end !== ct.start ? "-" + ct.end : ""}`, token: ct.token, ok, reason });
-  }
-
-  // COMPLETENESS
-  for (const anchor of anchors) {
-    if (anchor.toLowerCase() === "none") continue; // explicit, visible exemption
-    const hits = gitGrep(anchor).filter((h) => !h.file.endsWith(".md")); // docs excluded
-    if (hits.length === 0) {
-      completeness.push({ note: rel, anchor, site: "(none)", ok: false, reason: "anchor found nowhere in code — wrong token?" });
-      continue;
-    }
-    for (const h of hits) {
-      const covered = cites.some((ct) => ct.file === h.file && h.line >= ct.start && h.line <= ct.end);
-      completeness.push({ note: rel, anchor, site: `${h.file}:${h.line}`, ok: covered, reason: covered ? "" : "grep hit not cited — site omitted" });
-    }
-  }
-}
-
-const rFail = resolution.filter((r) => !r.ok);
-const cFail = completeness.filter((r) => !r.ok);
-const pFail = policy.filter((r) => !r.ok);
-const fail = rFail.length + cFail.length + pFail.length;
-
-const md = [
-  "# Citation check (generated — do not hand-edit)",
-  "",
-  `## Resolution (B1): ${resolution.length - rFail.length}/${resolution.length} ✓`,
-  ...resolution.map((r) => `${r.ok ? "✓" : "✗"} ${r.loc} :: ${r.token}${r.ok ? "" : "  — " + r.reason + " [" + r.note + "]"}`),
-  "",
-  `## Completeness (B2): ${completeness.length - cFail.length}/${completeness.length} ✓  (${new Set(completeness.map((c) => c.anchor)).size} anchors)`,
-  ...completeness.map((r) => `${r.ok ? "✓" : "✗"} anchor '${r.anchor}' → ${r.site}${r.ok ? "" : "  — " + r.reason + " [" + r.note + "]"}`),
-  "",
-  `## Policy (contract → anchor declared): ${policy.length - pFail.length}/${policy.length} ✓`,
-  ...policy.map((r) => `${r.ok ? "✓" : "✗"} ${r.note}${r.ok ? "" : "  — " + r.reason}`),
-  "",
-  fail ? `**${fail} FAILED.**` : "**All pass.**",
-  "",
-].join("\n");
-writeFileSync(join(ROOT, "citation-check.md"), md);
-
-console.log(md);
-console.log(`resolution ${resolution.length - rFail.length}/${resolution.length} · completeness ${completeness.length - cFail.length}/${completeness.length} · policy ${policy.length - pFail.length}/${policy.length}` + (fail ? ` · ${fail} FAILED` : " · all pass"));
-process.exit(fail ? 1 : 0);

package/blueprint/.rafa/capabilities/build.md

@@ -1,38 +0,0 @@
-# build — execute, brain-aware, compounding  (DRAFT · capability #4)
-
-> Status: **draft / spec.** The work-time loop where **recall + nudge + capture-back** all
-> fire — the mission payoff. Depends on: plan (#3), brain (#1), ledger (#2). Built last.
-
-Execute the approved plan with both stores in the loop. Invoke via `/build`.
-
-## Why build fits the mission (the flywheel closes here)
-
-Each task both **spends** the stores and **feeds** them — the compounding made real:
-
-- **RECALL** — per task, load the brain slice for the touched domains: follow
-  conventions/contracts; honor **non-exemplars** (don't pattern-match the salient-but-wrong
-  example — the audit showed a cold agent paying a 100K-token correction loop for exactly this).
-- **NUDGE** — surface the top-leverage open improvement in the task's blast radius: *"10-min fix
-  while you're here?"* Dismissible, never blocking. (bloom's deferred nudge, finally firing.)
-- **LEVERAGE (orchestrate, don't bury)** — before hand-rolling a task, surface the best-fit
-  existing capability (skill/tool/MCP — committed or the dev's personal) to the host, and any
-  config that would help it fire. Recommend; the host orchestrates. Never reinvent what's present.
-- **CAPTURE-BACK** — as work lands:
-  - decisions / scars → propose brain notes (**prism-validated** before they enter the brain),
-    **tool-agnostic** — capture *what + why + cited code*, never which (possibly personal) skill produced it,
-  - improvements fixed in passing → improve ledger **auto-close** (`status: fixed`),
-  - touched code → **incremental re-scan** of that domain so the brain stays fresh.
-
-## Procedure (draft)
-1. Resume from `active.md` (plan + active task).
-2. Per task: **recall** brain slice → implement (convention-adherent) → **nudge** a
-   blast-radius fix (opt-in) → done-check.
-3. **Capture-back**: distill decisions/scars (prism-validated); auto-close fixed improvements;
-   re-scan the touched domain.
-4. Verify (prism-style) before declaring done. Update `active.md`.
-
-## Deferred / open
-- **The capture engine** — `Stop`/`PostToolUse` hooks to make capture-back *automatic*, not
-  model-discretion (the deterministic-enforcement lesson, applied to capture).
-- **Incremental re-scan** — changed files + seam-neighbors only (keep it cheap).
-- Show-thinking + pivot protocol from the atlas character.