@rafinery/cli 0.4.1 → 0.6.0

package/lib/dirty.mjs

@@ -0,0 +1,114 @@
+// rafa dirty — the cite-graph invalidator's query surface (M5, agent-internal:
+// the conductor runs this at boundaries; devs never need to remember it).
+//
+//   rafa dirty             human view: dirty code files + the brain notes citing them
+//   rafa dirty --json      the same, machine-shaped (conductor bootstrap / spawn prompts)
+//   rafa dirty --consume   clear the queue AFTER a completed scoped refresh — the
+//                          refresh must have shipped (gates + checkpoint/push) first
+//
+// The queue (.rafa/dirty.jsonl) is written by the PostToolUse hook the moment an
+// edit happens (monotonic, no session-end dependency). Citing notes resolve from
+// the LOCAL manifest when one exists (full pull / prior compile); otherwise the
+// mapping is honestly "unresolved here" — counts still serve, and the platform's
+// get_code_context covers work-time recall. Never guesses.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const DIRTY_FILES_ALARM = 15; // ≥ → recommend /rafa scan --brain-only
+export const CITED_NOTES_ALARM = 10;
+
+export function readDirty(root = process.cwd()) {
+  const file = join(root, ".rafa", "dirty.jsonl");
+  const files = new Map(); // path → last touch
+  if (!existsSync(file)) return { file, files: [] };
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e && typeof e.f === "string") files.set(e.f, e.t ?? "");
+    } catch {
+      /* torn line — skip, never fail the query */
+    }
+  }
+  return { file, files: [...files.entries()].map(([f, t]) => ({ f, t })) };
+}
+
+// file → citing notes from the local manifest; null = no manifest here (lazy .rafa).
+export function resolveCiters(root, dirtyFiles) {
+  const path = join(root, ".rafa", "manifest.json");
+  if (!existsSync(path)) return null;
+  let m;
+  try {
+    m = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+  const want = new Set(dirtyFiles);
+  const notes = [];
+  for (const group of [m.notes ?? [], m.improvements ?? []]) {
+    for (const n of group) {
+      const files = [...new Set((n.cites ?? []).filter((c) => want.has(c.file)).map((c) => c.file))];
+      if (files.length) notes.push({ id: n.id, path: n.path, files });
+    }
+  }
+  return notes;
+}
+
+export default async function dirty(args = []) {
+  const ROOT = process.cwd();
+  const { file, files } = readDirty(ROOT);
+
+  if (args.includes("--consume")) {
+    if (files.length === 0) {
+      console.log("✓ dirty queue already clean");
+      return;
+    }
+    writeFileSync(file, "");
+    console.log(
+      `✓ consumed ${files.length} dirty file(s) — do this ONLY after the scoped refresh shipped (gates + checkpoint/push)`,
+    );
+    return;
+  }
+
+  const notes = resolveCiters(ROOT, files.map((e) => e.f));
+  const alarm =
+    files.length >= DIRTY_FILES_ALARM || (notes !== null && notes.length >= CITED_NOTES_ALARM);
+
+  if (args.includes("--json")) {
+    console.log(
+      JSON.stringify(
+        {
+          files: files.map((e) => e.f),
+          notes, // null = unresolved here (no local manifest) — an honest unknown, not zero
+          thresholds: { files: DIRTY_FILES_ALARM, notes: CITED_NOTES_ALARM },
+          alarm,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  if (files.length === 0) {
+    console.log("✓ dirty queue clean — no code edits recorded since the last brain reconcile");
+    return;
+  }
+  console.log(`${files.length} code file(s) edited since the last brain reconcile:`);
+  for (const e of files) console.log(`  · ${e.f}`);
+  if (notes === null) {
+    console.log("citing notes: unresolved here (lazy .rafa, no local manifest) — recall still");
+    console.log("serves fresh knowledge via the platform; run a scoped refresh from a session.");
+  } else if (notes.length === 0) {
+    console.log("citing notes: none — nothing in the brain cites these files (nothing to refresh).");
+  } else {
+    console.log(`${notes.length} brain note(s) cite them:`);
+    for (const n of notes) console.log(`  · ${n.id}  ←  ${n.files.join(", ")}`);
+  }
+  console.log(
+    alarm
+      ? `⚠ drift past threshold — recommend a brain refresh from main (/rafa scan --brain-only), then \`rafa dirty --consume\`.`
+      : `→ at the next boundary: scoped refresh of the citing notes (atlas re-derives ONLY those → gates → checkpoint), then \`rafa dirty --consume\`.`,
+  );
+}

package/lib/distill.mjs

@@ -61,6 +61,10 @@ async function loadAgentSdk(cwd) {
 const VERDICTS = ["distilled", "refuted", "needs-adjudication"];
 
 export default async function distill(args = []) {
+  // U7 recursion guard, belt-and-braces: the Agent SDK worker must never fire
+  // the M5 session sensors (a worker's own tool calls re-triggering hooks would
+  // loop). The ci-setup workflow sets this too; this covers ad-hoc invocations.
+  process.env.RAFA_HOOKS_DISABLED = "1";
   const branch = args.filter((a) => !a.startsWith("-"))[0];
   if (!args.includes("--headless"))
     die(
@@ -76,6 +80,10 @@ export default async function distill(args = []) {
     );
 
   const ROOT = process.cwd();
+  // Telemetry (owner feedback #9): every phase is timed and printed, so a CI
+  // log answers "where is it, and where did the time go" at a glance.
+  const t0 = Date.now();
+  const secs = (t) => ((Date.now() - t) / 1000).toFixed(1);
 
   // 1 · collect the branch working set. Adjudication-flagged rows are LEFT for
   // a human session (CI can flag divergence, never resolve it).
@@ -101,7 +109,9 @@ export default async function distill(args = []) {
 
   // 2 · mirror the org brain locally — the authoring target + the base the
   // survivors fold into. (CI checkout is merged main = the validation target.)
+  const tPull = Date.now();
   await pull(["--full"]);
+  console.log(`  ⏱ brain mirror: ${secs(tPull)}s`);
 
   // 3 · stage the incoming working set for the agent (gitignored inside .rafa).
   const stagingRoot = join(ROOT, ".rafa", "distill-incoming");
@@ -153,6 +163,7 @@ Staged files:
 ${fileList}`;
 
   console.log("• running the distillation agent (org's own ANTHROPIC_API_KEY) …");
+  const tAgent = Date.now();
   const run = sdk.query({
     prompt,
     options: {
@@ -163,14 +174,45 @@ ${fileList}`;
       maxTurns: 150,
     },
   });
+  // Stream the agent's narration lines — a silent multi-minute CI step reads
+  // as hung; a narrated one reads as working (and shows WHERE it hangs).
+  let lastLine = "";
+  let agentModel = "unreported";
   for await (const message of run) {
+    if (message.type === "assistant" && typeof message.message?.model === "string")
+      agentModel = message.message.model;
+    if (message.type === "assistant") {
+      const blocks = message.message?.content ?? [];
+      for (const b of blocks) {
+        if (b.type !== "text" || !b.text?.trim()) continue;
+        const line = b.text.trim().split("\n")[0].slice(0, 110);
+        if (line && line !== lastLine) {
+          console.log(`  · ${line}`);
+          lastLine = line;
+        }
+      }
+    }
     if (message.type === "result") {
       if (message.subtype !== "success")
         die(`distillation agent did not complete (${message.subtype}) — nothing resolved, nothing pushed`);
       console.log(
-        `  agent done (${message.num_turns ?? "?"} turns · ` +
+        `  ⏱ agent: ${secs(tAgent)}s (${message.num_turns ?? "?"} turns · ` +
           `$${(message.total_cost_usd ?? 0).toFixed(4)} on the org's key)`,
       );
+      // Self-report the metered run (backlog #6) — best-effort, never fatal.
+      try {
+        await callTool(ROOT, "log_usage", {
+          provider: "anthropic",
+          model: agentModel,
+          inputTokens: message.usage?.input_tokens ?? 0,
+          outputTokens: message.usage?.output_tokens ?? 0,
+          ...(typeof message.total_cost_usd === "number" ? { costUsd: message.total_cost_usd } : {}),
+          purpose: "distill",
+          runner: "ci",
+        });
+      } catch (e) {
+        console.log(`  ! usage not reported: ${e instanceof Error ? e.message : e}`);
+      }
     }
   }
 
@@ -195,10 +237,12 @@ ${fileList}`;
 
   // 6 · trust-but-verify: OUR gates re-run regardless of what the agent claims.
   console.log("• re-running the gates (trust-but-verify) …");
+  const tGates = Date.now();
   if (runVerifyCitations([]) !== 0)
     die("citation checker failed on the authored brain — nothing resolved, nothing pushed");
   if (runCompile([]) !== 0)
     die("compile gate failed on the authored brain — nothing resolved, nothing pushed");
+  console.log(`  ⏱ gates: ${secs(tGates)}s`);
 
   // 7 · ship: brain repo push (webhook → ingest), staging cleaned first.
   rmSync(stagingRoot, { recursive: true, force: true });
@@ -221,6 +265,7 @@ ${fileList}`;
         branch,
         path: f.path,
         resolution: v.verdict,
+        actorMeta: { agent: "rafa-distill", runner: "ci", model: agentModel },
         ...(v.note ? { note: v.note } : {}),
       });
       console.log(`  ${v.verdict === "distilled" ? "✓" : "!"} ${f.path} → ${v.verdict}${v.note ? ` (${v.note})` : ""}`);
@@ -232,6 +277,6 @@ ${fileList}`;
 
   console.log(
     `✓ distillation: ${distilledCount} into the org brain · ${refuted} refuted (reported, cited) · ` +
-      `${adjudication} flagged needs-adjudication (next session's digest)`,
+      `${adjudication} flagged needs-adjudication (next session's digest) · total ${secs(t0)}s`,
   );
 }

package/lib/gate/compile.mjs

@@ -191,6 +191,11 @@ export function runCompile(argv = []) {
       }
       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`)");
       notes.push({
         id,
         kind,
@@ -332,23 +337,49 @@ 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 };
   }
 
-  // Plans (contract §7): parent+child files under plans/**. Global id uniqueness,
-  // parent/child cross-checks, progress never stored, active.md → activePlanId.
-  // VALIDATED here (files are the authoring surface — determinism holds) but
-  // since 0.4.0 plans do NOT ride the manifest: they travel through the
-  // dedicated push-on-approval plans channel (push_plan). Terminal statuses
-  // (superseded/abandoned) close a plan honestly without pretending `done`.
-  const PLAN_STATUSES = [
-    "todo",
-    "in-progress",
-    "done",
-    "blocked",
-    "superseded",
-    "abandoned",
-  ];
+  // 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_KINDS = ["epic", "task", "subtask"];
   function compilePlans() {
     const plans = [];
     const seen = new Map(); // id → path (global uniqueness across plans/**)
@@ -365,43 +396,123 @@ export function runCompile(argv = []) {
         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 · parent progress is derived by counting children");
-      const kind = reqEnum(data, "kind", ["parent", "child"], path);
+        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)`);
+      const kind = reqEnum(data, "kind", PLAN_KINDS, path);
       const plan = reqStr(data, "plan", path);
       const status = data.status;
-      if (kind === "child") {
-        if (!isEnum(status, PLAN_STATUSES))
-          fail(path, "status", `required (child) · ${PLAN_STATUSES.join("|")}`);
-        if (data.parent !== plan)
-          fail(path, "parent", `must equal plan "${plan}" for a child (flat v1)`);
-      } else {
+      if (status === "blocked")
+        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: parent");
-        if (plan !== id) fail(path, "plan", `must equal id "${id}" for kind: parent`);
+          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 (status !== undefined && !isEnum(status, PLAN_STATUSES))
-          fail(path, "status", `optional (parent) · ${PLAN_STATUSES.join("|")}`);
+          fail(path, "status", `optional (epic) · ${PLAN_STATUSES.join("|")}`);
+      } else {
+        if (!isEnum(status, PLAN_STATUSES))
+          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");
+      }
+      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");
+      if (
+        data.priority !== undefined &&
+        !(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, "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)");
       }
       plans.push({
         id,
         plan,
-        parent: kind === "parent" ? null : plan,
+        parent: kind === "epic" ? null : String(data.parent ?? ""),
         kind,
         title: reqStr(data, "title", path),
         ...(isEnum(status, PLAN_STATUSES) ? { status } : {}),
+        ...(typeof data.description === "string" && data.description !== ""
+          ? { description: data.description }
+          : {}),
+        ...(typeof data.approach === "string" && data.approach !== ""
+          ? { approach: data.approach }
+          : {}),
+        ...(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 !== ""
+          ? { blockedReason: data.blocked_reason }
+          : {}),
+        ...(Number.isInteger(data.priority) ? { priority: data.priority } : {}),
+        ...(Number.isInteger(data.estimate) ? { estimate: data.estimate } : {}),
         ...(typeof data.branch === "string" && data.branch !== ""
           ? { branch: data.branch }
           : {}),
         ...(typeof data.baseSha === "string" && data.baseSha !== ""
           ? { baseSha: String(data.baseSha) }
           : {}),
+        ...(Array.isArray(data.domains) && kind === "epic"
+          ? { domains: data.domains.map(String) }
+          : {}),
+        ...(typeof data.external === "object" && !Array.isArray(data.external) && data.external !== null
+          ? { external: data.external }
+          : {}),
         path: rel(path),
       });
     }
-    // Cross-check: every child's plan resolves to a kind:parent in this compile.
-    const parents = new Set(plans.filter((p) => p.kind === "parent").map((p) => p.id));
+    // Cross-checks: tree shape + blocked_by resolution, per plan.
+    const byId = new Map(plans.map((p) => [p.id, p]));
+    const roots = new Map(); // plan id → epic item
+    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)`);
+      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}")`);
+      }
+      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");
+        else if (parent.plan !== 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");
+      }
+    }
+    // blocked_by acyclicity (per plan; DFS with colors).
+    const color = new Map();
+    const cyc = (p) => {
+      color.set(p.id, 1);
+      for (const b of p.blockedBy ?? []) {
+        const t = byId.get(b);
+        if (!t) continue;
+        if (color.get(t.id) === 1) return true;
+        if (!color.has(t.id) && cyc(t)) return true;
+      }
+      color.set(p.id, 2);
+      return false;
+    };
     for (const p of plans)
-      if (p.kind === "child" && !parents.has(p.plan))
-        fail(p.path, "plan", `no parent plan "${p.plan}" in this compile (dangling child)`);
+      if (!color.has(p.id) && cyc(p))
+        fail(p.path, "blocked_by", "dependency cycle — blocked_by must be acyclic");
     return plans;
   }
 
@@ -419,8 +530,8 @@ export function runCompile(argv = []) {
     }
     const val = m[1].trim();
     if (/^no active plan$/i.test(val)) return null;
-    if (!plans.some((p) => p.kind === "parent" && p.id === val)) {
-      fail(path, "pointer", `active plan "${val}" is not a kind:parent plan in this compile`);
+    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`);
       return null;
     }
     return val;
@@ -500,6 +611,7 @@ export function runCompile(argv = []) {
   const health = compileHealth();
   const ledger = compileLedger();
   const coverage = compileCoverage();
+  const citations = compileCitations();
   const plans = compilePlans();
   const activePlanId = compileActivePlanId(plans);
   const agentCards = compileAgentCards();
@@ -534,6 +646,7 @@ export function runCompile(argv = []) {
     health,
     ledger,
     coverage,
+    citations,
     notes,
     improvements,
   };