@rafinery/cli 0.5.0 → 0.7.0

package/lib/gate/compile.mjs

@@ -119,6 +119,41 @@ export function runCompile(argv = []) {
   // 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);
+  // The code repo root — cite `file`s are relative to it (same anchor the checker
+  // resolves against). `.rafa/` sits inside the code repo, so `..` reaches the root.
+  const repoRoot = join(ROOT, "..");
+
+  // ── deterministic size estimation (recall-savings, additive optional) ────────
+  // Feeds the platform's recall-savings estimator: a note's token cost and each
+  // cited file's token cost, so it can price "read the note" vs "re-read the code".
+  // Estimate = ceil(chars / 4) — the ~4-bytes-per-token rule of thumb for English
+  // source/prose. DETERMINISTIC: pure function of the file bytes, no LLM, no network.
+  // These are ADDITIVE OPTIONAL manifest fields (contract §1) — a note without them
+  // still compiles and ingest tolerates their absence; a target we cannot read is
+  // OMITTED, never defaulted to a guessed 0 (contract §0 / compile's own law above).
+  const estimateTokens = (s) => Math.ceil(s.length / 4);
+  // The prose body = everything after the closing `---` fence (never parsed, only sized).
+  function noteBody(text) {
+    if (!text.startsWith("---")) return text;
+    const end = text.indexOf("\n---", text.indexOf("\n"));
+    if (end === -1) return "";
+    const nl = text.indexOf("\n", end + 1); // newline after the closing `---` line
+    return nl === -1 ? "" : text.slice(nl + 1);
+  }
+  // Cited-file token estimate, cached per path (a file is cited by many notes).
+  // null = unreadable at compile time → the caller OMITS the field (honest absence).
+  const citeTokenCache = new Map();
+  function citeTargetTokens(file) {
+    if (citeTokenCache.has(file)) return citeTokenCache.get(file);
+    let tokens = null;
+    try {
+      tokens = estimateTokens(readFileSync(join(repoRoot, file), "utf8"));
+    } catch {
+      tokens = null; // missing/unreadable → omit, never guess
+    }
+    citeTokenCache.set(file, tokens);
+    return tokens;
+  }
 
   const errors = [];
   const fail = (path, field, rule) => errors.push({ path, field, rule });
@@ -184,17 +219,38 @@ export function runCompile(argv = []) {
     const notes = [];
     for (const path of walk(dir)) {
       const name = path.split("/").pop();
-      const { data, error } = parseFrontmatter(read(path));
+      const raw = read(path);
+      const { data, error } = parseFrontmatter(raw);
       if (error) {
         fail(path, "frontmatter", error);
         continue;
       }
       checkVersion(data, path);
       const id = checkId(data, path, name);
+      // `anchor:` / `absent:` are checker-side declarations (verify-citations gates
+      // B2/B3 on them) — optional here, but if present they must be non-empty.
+      for (const key of ["anchor", "absent"])
+        if (
+          key in data &&
+          (typeof data[key] !== "string" || data[key].trim() === "")
+        )
+          fail(path, key, "optional · non-empty token (or `none`)");
+      // 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);
+      for (const c of cites) {
+        const t = citeTargetTokens(c.file);
+        if (t !== null) c.targetTokens = t;
+      }
       notes.push({
         id,
         kind,
-        type: reqEnum(data, "type", ["contract", "convention", "flow", "how-to"], path),
+        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),
@@ -202,7 +258,8 @@ export function runCompile(argv = []) {
         ...(data.failure === "silent" || data.failure === "loud"
           ? { failure: data.failure }
           : {}),
-        cites: parseCites(data.cites, path),
+        bodyTokens: estimateTokens(noteBody(raw)),
+        cites,
         path: rel(path),
       });
     }
@@ -226,17 +283,33 @@ export function runCompile(argv = []) {
         !isEnum(lev?.impact, ["low", "medium", "high"]) ||
         !isEnum(lev?.effort, ["low", "medium", "high"])
       )
-        fail(path, "leverage", "required · { impact, 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"],
+          [
+            "security",
+            "correctness",
+            "performance",
+            "architecture",
+            "product",
+            "ops",
+          ],
+          path,
+        ),
+        status: reqEnum(
+          data,
+          "status",
+          ["open", "backlog", "fixed", "wontfix"],
           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),
@@ -265,7 +338,10 @@ export function runCompile(argv = []) {
     checkVersion(data, path);
     const g = data.gates,
       c = data.counts;
-    if (!isEnum(g?.fidelity, ["pass", "fail"]) || !isEnum(g?.coverage, ["pass", "fail"]))
+    if (
+      !isEnum(g?.fidelity, ["pass", "fail"]) ||
+      !isEnum(g?.coverage, ["pass", "fail"])
+    )
       fail(path, "gates", "required · { fidelity, coverage } ∈ pass|fail");
     if (
       typeof c?.blockers !== "number" ||
@@ -273,11 +349,15 @@ export function runCompile(argv = []) {
       typeof c?.minors !== "number"
     )
       fail(path, "counts", "required · { blockers, majors, minors } ints");
-    if (typeof data.score !== "number") fail(path, "score", "required · 0–100 int");
+    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" },
+      gates: {
+        fidelity: g?.fidelity ?? "fail",
+        coverage: g?.coverage ?? "fail",
+      },
       counts: {
         blockers: c?.blockers ?? 0,
         majors: c?.majors ?? 0,
@@ -332,15 +412,70 @@ export function runCompile(argv = []) {
         fail(path, `domains.${domain}`, `status ∈ ${STATUS.join("|")}`);
       domains.push({ domain, status: String(status) });
     }
+    // Optional `inventory:` block list — `<name> :: <glob> :: <count>` per entry.
+    // Checker-side (verify-citations recomputes each via git ls-files); validated
+    // here so a malformed declaration fails loudly at the gate, never silently.
+    if ("inventory" in data) {
+      if (!Array.isArray(data.inventory) || data.inventory.length === 0) {
+        fail(
+          path,
+          "inventory",
+          "optional · block list of `<name> :: <glob> :: <count>`",
+        );
+      } else {
+        for (const entry of data.inventory)
+          if (!/^.+?\s*::\s*.+?\s*::\s*\d+$/.test(String(entry)))
+            fail(
+              path,
+              "inventory",
+              `malformed entry: ${JSON.stringify(entry)} · must be \`<name> :: <glob> :: <count>\``,
+            );
+      }
+    }
     return { domains };
   }
 
+  // citation-check.json — the checker's machine record of its last run (generated
+  // by `rafa verify-citations`). Folded into manifest.citations so the platform
+  // knows which gate level this brain passed. Absent file → null (an honest
+  // "no recorded run"); a malformed one is a tool bug and fails loudly.
+  function compileCitations() {
+    const path = join(ROOT, "brain", "citation-check.json");
+    if (!existsSync(path)) return null;
+    let rec;
+    try {
+      rec = JSON.parse(read(path));
+    } catch (e) {
+      fail(path, "json", `unparseable: ${e instanceof Error ? e.message : e}`);
+      return null;
+    }
+    if (
+      typeof rec.checkerVersion !== "number" ||
+      typeof rec.pass !== "boolean" ||
+      typeof rec.at !== "string"
+    ) {
+      fail(
+        path,
+        "shape",
+        "required · { checkerVersion: int, pass: bool, at: ISO string }",
+      );
+      return null;
+    }
+    return { checkerVersion: rec.checkerVersion, pass: rec.pass, at: rec.at };
+  }
+
   // Plans (contract §7 v2 — the work-item tree, plans data version 2): one epic
   // (root) → tasks → subtasks. Vendor-blended vocabulary; `blocked` is DERIVED
   // (unresolved blocked_by / blocked_reason), never stored. VALIDATED here
   // (files are the authoring surface — determinism holds) but plans do NOT ride
   // the manifest: they travel through the push-on-approval plans channel.
-  const PLAN_STATUSES = ["todo", "in-progress", "done", "superseded", "abandoned"];
+  const PLAN_STATUSES = [
+    "todo",
+    "in-progress",
+    "done",
+    "superseded",
+    "abandoned",
+  ];
   const PLAN_KINDS = ["epic", "task", "subtask"];
   function compilePlans() {
     const plans = [];
@@ -355,46 +490,95 @@ export function runCompile(argv = []) {
       checkVersion(data, path);
       const id = checkId(data, path, name);
       if (seen.has(id))
-        fail(path, "id", `duplicate plan id "${id}" (also ${seen.get(id)}) · ids are globally unique across plans/**`);
+        fail(
+          path,
+          "id",
+          `duplicate plan id "${id}" (also ${seen.get(id)}) · ids are globally unique across plans/**`,
+        );
       seen.set(id, path);
       if ("progress" in data)
-        fail(path, "progress", "never stored · progress = done leaves / total leaves, derived");
+        fail(
+          path,
+          "progress",
+          "never stored · progress = done leaves / total leaves, derived",
+        );
       if (data.kind === "parent" || data.kind === "child")
-        fail(path, "kind", `plans v1 shape ("${data.kind}") — run \`rafa migrate\` (v2: epic|task|subtask)`);
+        fail(
+          path,
+          "kind",
+          `plans v1 shape ("${data.kind}") — run \`rafa migrate\` (v2: epic|task|subtask)`,
+        );
       const kind = reqEnum(data, "kind", PLAN_KINDS, path);
       const plan = reqStr(data, "plan", path);
       const status = data.status;
       if (status === "blocked")
-        fail(path, "status", "removed in v2 — blocked is DERIVED from blocked_by/blocked_reason (run `rafa migrate`)");
+        fail(
+          path,
+          "status",
+          "removed in v2 — blocked is DERIVED from blocked_by/blocked_reason (run `rafa migrate`)",
+        );
       if (kind === "epic") {
         if (data.parent !== null && data.parent !== "null")
           fail(path, "parent", "must be null for kind: epic (the root)");
-        if (plan !== id) fail(path, "plan", `must equal id "${id}" for kind: epic`);
+        if (plan !== id)
+          fail(path, "plan", `must equal id "${id}" for kind: epic`);
         if (status !== undefined && !isEnum(status, PLAN_STATUSES))
           fail(path, "status", `optional (epic) · ${PLAN_STATUSES.join("|")}`);
       } else {
         if (!isEnum(status, PLAN_STATUSES))
-          fail(path, "status", `required (${kind}) · ${PLAN_STATUSES.join("|")}`);
+          fail(
+            path,
+            "status",
+            `required (${kind}) · ${PLAN_STATUSES.join("|")}`,
+          );
         if (typeof data.parent !== "string" || data.parent === "")
           fail(path, "parent", `required (${kind}) · the parent item id`);
         if (data.domains !== undefined)
-          fail(path, "domains", "epic only · the blast radius belongs to the plan, not an item");
+          fail(
+            path,
+            "domains",
+            "epic only · the blast radius belongs to the plan, not an item",
+          );
       }
       if (data.domains !== undefined && !Array.isArray(data.domains))
         fail(path, "domains", "optional · flow list of domain strings");
       if (data.blocked_by !== undefined && !Array.isArray(data.blocked_by))
-        fail(path, "blocked_by", "optional · flow list of item ids this item waits on");
+        fail(
+          path,
+          "blocked_by",
+          "optional · flow list of item ids this item waits on",
+        );
       if (
         data.priority !== undefined &&
-        !(Number.isInteger(data.priority) && data.priority >= 0 && data.priority <= 4)
+        !(
+          Number.isInteger(data.priority) &&
+          data.priority >= 0 &&
+          data.priority <= 4
+        )
+      )
+        fail(
+          path,
+          "priority",
+          "optional · int 0–4 (0 none · 1 urgent · 2 high · 3 medium · 4 low)",
+        );
+      if (
+        data.estimate !== undefined &&
+        !(Number.isInteger(data.estimate) && data.estimate >= 0)
       )
-        fail(path, "priority", "optional · int 0–4 (0 none · 1 urgent · 2 high · 3 medium · 4 low)");
-      if (data.estimate !== undefined && !(Number.isInteger(data.estimate) && data.estimate >= 0))
         fail(path, "estimate", "optional · non-negative int (points)");
       if (data.external !== undefined) {
         const ex = data.external;
-        if (typeof ex !== "object" || Array.isArray(ex) || typeof ex.provider !== "string" || typeof ex.key !== "string")
-          fail(path, "external", "optional · { provider, key, url? } flow map — tracker identity (read-only to sessions)");
+        if (
+          typeof ex !== "object" ||
+          Array.isArray(ex) ||
+          typeof ex.provider !== "string" ||
+          typeof ex.key !== "string"
+        )
+          fail(
+            path,
+            "external",
+            "optional · { provider, key, url? } flow map — tracker identity (read-only to sessions)",
+          );
       }
       plans.push({
         id,
@@ -412,8 +596,11 @@ export function runCompile(argv = []) {
         ...(typeof data.assignee === "string" && data.assignee !== ""
           ? { assignee: data.assignee }
           : {}),
-        ...(Array.isArray(data.blocked_by) ? { blockedBy: data.blocked_by.map(String) } : {}),
-        ...(typeof data.blocked_reason === "string" && data.blocked_reason !== ""
+        ...(Array.isArray(data.blocked_by)
+          ? { blockedBy: data.blocked_by.map(String) }
+          : {}),
+        ...(typeof data.blocked_reason === "string" &&
+        data.blocked_reason !== ""
           ? { blockedReason: data.blocked_reason }
           : {}),
         ...(Number.isInteger(data.priority) ? { priority: data.priority } : {}),
@@ -427,7 +614,9 @@ export function runCompile(argv = []) {
         ...(Array.isArray(data.domains) && kind === "epic"
           ? { domains: data.domains.map(String) }
           : {}),
-        ...(typeof data.external === "object" && !Array.isArray(data.external) && data.external !== null
+        ...(typeof data.external === "object" &&
+        !Array.isArray(data.external) &&
+        data.external !== null
           ? { external: data.external }
           : {}),
         path: rel(path),
@@ -439,24 +628,45 @@ export function runCompile(argv = []) {
     for (const p of plans) if (p.kind === "epic") roots.set(p.id, p);
     for (const p of plans) {
       if (!roots.has(p.plan))
-        fail(p.path, "plan", `no kind:epic "${p.plan}" in this compile (dangling item)`);
+        fail(
+          p.path,
+          "plan",
+          `no kind:epic "${p.plan}" in this compile (dangling item)`,
+        );
       if (p.kind === "task") {
         const parent = byId.get(p.parent);
         if (!parent || parent.kind !== "epic" || parent.id !== p.plan)
-          fail(p.path, "parent", `a task's parent must be its epic ("${p.plan}")`);
+          fail(
+            p.path,
+            "parent",
+            `a task's parent must be its epic ("${p.plan}")`,
+          );
       }
       if (p.kind === "subtask") {
         const parent = byId.get(p.parent);
         if (!parent || parent.kind !== "task")
-          fail(p.path, "parent", "a subtask's parent must be a task in the same plan");
+          fail(
+            p.path,
+            "parent",
+            "a subtask's parent must be a task in the same plan",
+          );
         else if (parent.plan !== p.plan)
-          fail(p.path, "parent", `parent task belongs to plan "${parent.plan}", not "${p.plan}"`);
+          fail(
+            p.path,
+            "parent",
+            `parent task belongs to plan "${parent.plan}", not "${p.plan}"`,
+          );
       }
       for (const b of p.blockedBy ?? []) {
         const target = byId.get(b);
         if (!target || target.plan !== p.plan)
-          fail(p.path, "blocked_by", `"${b}" does not resolve to an item in plan "${p.plan}"`);
-        if (b === p.id) fail(p.path, "blocked_by", "an item cannot block itself");
+          fail(
+            p.path,
+            "blocked_by",
+            `"${b}" does not resolve to an item in plan "${p.plan}"`,
+          );
+        if (b === p.id)
+          fail(p.path, "blocked_by", "an item cannot block itself");
       }
     }
     // blocked_by acyclicity (per plan; DFS with colors).
@@ -474,7 +684,11 @@ export function runCompile(argv = []) {
     };
     for (const p of plans)
       if (!color.has(p.id) && cyc(p))
-        fail(p.path, "blocked_by", "dependency cycle — blocked_by must be acyclic");
+        fail(
+          p.path,
+          "blocked_by",
+          "dependency cycle — blocked_by must be acyclic",
+        );
     return plans;
   }
 
@@ -487,13 +701,21 @@ export function runCompile(argv = []) {
     const first = read(path).split("\n")[0].trim();
     const m = first.match(/^#\s+(.+)$/);
     if (!m) {
-      fail(path, "pointer", 'first line must be "# <plan-id>" or "# No active plan"');
+      fail(
+        path,
+        "pointer",
+        'first line must be "# <plan-id>" or "# No active plan"',
+      );
       return null;
     }
     const val = m[1].trim();
     if (/^no active plan$/i.test(val)) return null;
     if (!plans.some((p) => p.kind === "epic" && p.id === val)) {
-      fail(path, "pointer", `active plan "${val}" is not a kind:epic plan in this compile`);
+      fail(
+        path,
+        "pointer",
+        `active plan "${val}" is not a kind:epic plan in this compile`,
+      );
       return null;
     }
     return val;
@@ -517,7 +739,8 @@ export function runCompile(argv = []) {
       }
       count++;
       const stem = name.replace(/\.md$/, "");
-      if (data.name !== stem) fail(path, "name", `must equal filename stem "${stem}"`);
+      if (data.name !== stem)
+        fail(path, "name", `must equal filename stem "${stem}"`);
       if (!/^\d+\.\d+\.\d+$/.test(String(data.version ?? "")))
         fail(path, "version", "required · semver MAJOR.MINOR.PATCH");
       reqStr(data, "model", path);
@@ -537,12 +760,20 @@ export function runCompile(argv = []) {
       for (const d of duties) {
         const m = String(d).match(DUTY_RE);
         if (!m) {
-          fail(path, "duties", `malformed duty (want "<duty> :: <sop> :: <bar>"): ${JSON.stringify(d)}`);
+          fail(
+            path,
+            "duties",
+            `malformed duty (want "<duty> :: <sop> :: <bar>"): ${JSON.stringify(d)}`,
+          );
           continue;
         }
         const sop = m[2];
         if (!existsSync(join(repoRoot, sop)) && !existsSync(join(ROOT, sop)))
-          fail(path, "duties", `sop does not resolve: ${sop} (a duty without a procedure is a claim)`);
+          fail(
+            path,
+            "duties",
+            `sop does not resolve: ${sop} (a duty without a procedure is a claim)`,
+          );
       }
     }
     return count;
@@ -569,10 +800,13 @@ export function runCompile(argv = []) {
     ...compileNotes("rule", join(ROOT, "brain", "rules")),
     ...compileNotes("playbook", join(ROOT, "brain", "playbooks")),
   ];
-  const improvements = compileImprovements(join(ROOT, "improve", "improvements"));
+  const improvements = compileImprovements(
+    join(ROOT, "improve", "improvements"),
+  );
   const health = compileHealth();
   const ledger = compileLedger();
   const coverage = compileCoverage();
+  const citations = compileCitations();
   const plans = compilePlans();
   const activePlanId = compileActivePlanId(plans);
   const agentCards = compileAgentCards();
@@ -583,16 +817,27 @@ export function runCompile(argv = []) {
     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}`);
+      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]}`);
+        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 the contract (.claude/rafa/contract.md), then re-run compile.`);
+    for (const e of errors)
+      console.error(`  ${e.path}  ·  ${e.field}  ·  ${e.rule}`);
+    console.error(
+      `\nFix these files to match the contract (.claude/rafa/contract.md), then re-run compile.`,
+    );
     return 1;
   }
 
@@ -607,10 +852,14 @@ export function runCompile(argv = []) {
     health,
     ledger,
     coverage,
+    citations,
     notes,
     improvements,
   };
-  writeFileSync(join(ROOT, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+  writeFileSync(
+    join(ROOT, "manifest.json"),
+    JSON.stringify(manifest, null, 2) + "\n",
+  );
   console.log(
     `✓ rafa compile: ${notes.length} notes · ${improvements.length} improvements · ` +
       `${plans.length} plans validated${activePlanId ? ` (active: ${activePlanId})` : ""} (plans travel via the plans channel, not the manifest) · ` +