@rafinery/cli 0.3.0 → 0.4.0

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,39 +0,0 @@
-# build — execute the plan, trio-choreographed, compounding  (capability #4)
-
-> Status: **active.** The work-time loop where recall + validation + improvement all
-> fire — the mission payoff. Depends on: plan (#3), brain (#1), ledger (#2).
-> Invoke via `/rafa build`.
-
-Execute the approved plan with all three agents in the loop, knowledge served by the
-platform MCP (one read path — the same surface any third-party agent uses).
-
-## The trio at build time
-
-| Role | Agent | Job per task |
-|---|---|---|
-| **Executor** | atlas | RECALL the task's brain slice via MCP (`search_knowledge` + `get_rule`/`get_playbook`; honor non-exemplars) → implement, convention-adherent |
-| **Validator** | prism | validate the execution against the child's `## Done-check` — strict, unbiased, against code + brain, never against atlas's claims. **`status: done` only on prism PASS**; FAIL → atlas corrects (validate-and-correct at work time). This gate is conductor-flow SOP — deterministic enforcement is the deferred capture-engine's job |
-| **Improver** | bloom | **push**: new improvement opportunities spotted during execution → new ledger files. **close**: improvements fixed in passing → `status: fixed`. **nudge**: top-leverage open item in the task's blast radius — opt-in, never blocking |
-
-## Procedure
-
-1. **Resume** — `get_active_plan` (platform) or local `active.md`; staleness check
-   (envelope `brainForSha` vs local stamp → prompt `rafa push` if behind).
-2. **Per task:** atlas recalls → implements → prism validates vs `## Done-check` →
-   bloom sweeps (push new / close fixed / nudge) → update the child file's `status`
-   → periodic `rafa compile` + `rafa push` so the platform (and every MCP consumer)
-   reflects live progress.
-3. **Brain changes mid-build** — execution may invalidate rules or teach new ones.
-   v1: run a full `/rafa scan` (regenerate → prism → compile → push); the whole
-   brain re-stamps at the new sha, so `brain = f(code@sha)` stays exact. NEVER
-   hand-edit brain files around the gate.
-4. **Verify** (prism-style) before declaring the plan done; final compile + push.
-
-## Deferred / open
-- **The capture engine** — `Stop`/`PostToolUse` hooks making the gates + capture
-  automatic rather than conductor-driven SOP (deterministic-enforcement lesson).
-- **Incremental re-scan** — cite-graph invalidation (diff → invalidate notes citing
-  changed files → re-verify/regenerate only those). Needs: partial-brain cache-key
-  semantics + the seam-neighbor scope rule. Designed (see
-  .fable/sessions/2026-07-07-brain-versioning-and-incremental.md); first post-loop item.
-- Show-thinking + pivot protocol from the atlas character.