@connorbritain/roadmap 0.3.0

package/scripts/lib/recommend.mjs

@@ -0,0 +1,178 @@
+// roadmap — concurrency recommender.
+// Recommends a max-parallel-sessions cap from a resource + repo-purpose eval, and
+// reports WHICH constraint binds. The point: concurrency that exceeds your RAM/CPU
+// thrashes the machine, concurrency that exceeds free DISK fails mid-checkout, and
+// concurrency that exceeds independent work or your ability to review the resulting
+// PRs is wasted. So we take the min of five real ceilings.
+
+import os from "node:os";
+import { existsSync, statfsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { resolveGate } from "./graph.mjs";
+
+// Per-session resource cost by weight class — cross-language defaults (a full test
+// suite / heavy compile ~3.5GB/2 cores; a build/lint ~1.5GB/1 core; docs cheap).
+// A repo can override any of these via meta.weight_cost: { heavy: {ram, cores}, ... }.
+const WEIGHT_COST = {
+  heavy:  { ram: 3.5, cores: 2.0 },
+  medium: { ram: 1.5, cores: 1.0 },
+  light:  { ram: 0.6, cores: 0.5 },
+};
+
+// Anything that isn't documentation counts as "code-ish" (so it floors at medium when
+// the gate's runner isn't recognized). Language-agnostic on purpose.
+const DOCISH = /\.(md|mdx|rst|txt|ya?ml|toml|json)$|(^|\/)docs?\//i;
+
+// Built-in, MULTI-ECOSYSTEM runner → weight. heavy = a full test suite or a heavy
+// compile; medium = a build / typecheck / lint. Repos EXTEND or override via
+// meta.weight_patterns: { heavy: ["regex", ...], medium: [...] } (strings, case-insensitive).
+const BUILTIN_PATTERNS = {
+  heavy: [
+    /dotnet test/, /\bcargo test\b/, /\bpytest\b/, /\bgo test\b/, /\btox\b/, /\bnox\b/,
+    /gradlew?\b[^\n]*\b(test|check)\b/, /\bmvn\b[^\n]*\b(test|verify)\b/, /\brspec\b/, /\bphpunit\b/,
+    /\bmix test\b/, /\bctest\b/, /\bbazel test\b/, /\bjest\b/, /vitest\b[^\n]*\brun\b/,
+    /(npm|yarn|pnpm)\s+(run\s+)?test\b/, /\bdeno test\b/, /\bmake\b[^\n]*\btest\b/, /\brake\b[^\n]*\btest\b/,
+  ],
+  medium: [
+    /dotnet build/, /\bcargo (build|check|clippy)\b/, /\bgo build\b/, /gradlew?\b[^\n]*\bbuild\b/,
+    /\bmvn\b[^\n]*\b(compile|package)\b/, /\btsc\b/, /\bvitest\b/, /\beslint\b/, /\bruff\b/, /\bmypy\b/,
+    /(npm|yarn|pnpm)\s+(run\s+)?build\b/, /\bmake\b/, /\bcmake\b/, /\bbundle\b/, /\bwebpack\b/, /\bvite build\b/,
+  ],
+};
+
+function compilePatterns(graph) {
+  const extra = (graph.meta && graph.meta.weight_patterns) || {};
+  const toRe = (s) => (s instanceof RegExp ? s : new RegExp(s, "i"));
+  return {
+    heavy: [...BUILTIN_PATTERNS.heavy, ...((extra.heavy) || []).map(toRe)],
+    medium: [...BUILTIN_PATTERNS.medium, ...((extra.medium) || []).map(toRe)],
+  };
+}
+
+function costTable(graph) {
+  const o = (graph.meta && graph.meta.weight_cost) || {};
+  return {
+    heavy:  { ...WEIGHT_COST.heavy,  ...(o.heavy  || {}) },
+    medium: { ...WEIGHT_COST.medium, ...(o.medium || {}) },
+    light:  { ...WEIGHT_COST.light,  ...(o.light  || {}) },
+  };
+}
+
+// Classify a slice's weight: explicit `weight` override wins; else docs-only → light;
+// else match the resolved gate against the built-in + repo runner patterns; else a slice
+// that touches non-docs files floors at medium; else meta.default_weight (or light).
+export function nodeWeight(node, graph) {
+  if (node.sprint && node.sprint.weight) return node.sprint.weight;
+  const gate = (resolveGate(node, graph) || "").toLowerCase();
+  const touches = [...(node.touches || []), ...(node.owns || [])];
+  const allDocish = touches.length > 0 && touches.every((f) => DOCISH.test(f));
+  if (allDocish) return "light";
+  const pats = compilePatterns(graph);
+  if (pats.heavy.some((re) => re.test(gate))) return "heavy";
+  if (pats.medium.some((re) => re.test(gate))) return "medium";
+  if (touches.some((f) => !DOCISH.test(f))) return "medium";  // unknown runner but touches code
+  return (graph.meta && graph.meta.default_weight) || "light";
+}
+
+// Disk feasibility probe: what one more worktree costs vs what the worktree volume has free.
+// Per-worktree cost = the checked-out tree's blob bytes (git ls-tree -r -l HEAD; one fast
+// command, no fs walk) × a safety factor, overridable via meta.worktree_gb — the calibration
+// knob for repos whose gates install node_modules or build artifacts per worktree.
+// ponytail: 1.3× covers normal build litter; per-worktree package installs can exceed it —
+// meta.worktree_gb is the knob, no measurement machinery.
+// Returns { perWorktreeGb, freeGb } or null when undetectable (no git HEAD, statfs
+// unsupported) — the caller then simply skips the disk ceiling.
+export function probeDisk(graph, cwd = process.cwd()) {
+  try {
+    const meta = (graph && graph.meta) || {};
+    let perWorktreeGb = typeof meta.worktree_gb === "number" ? meta.worktree_gb : null;
+    if (perWorktreeGb == null) {
+      const r = spawnSync("git", ["ls-tree", "-r", "-l", "HEAD"], { cwd, encoding: "utf8", maxBuffer: 64 * 2 ** 20 });
+      if (r.status !== 0 || !r.stdout) return null;
+      let bytes = 0;
+      for (const line of r.stdout.split("\n")) {
+        const m = /\s(\d+)\t/.exec(line);   // blob size column; trees show "-"
+        if (m) bytes += Number(m[1]);
+      }
+      if (!bytes) return null;
+      perWorktreeGb = (bytes / 2 ** 30) * 1.3;
+    }
+    // Free space on the volume that will hold the worktrees — walk worktree_root up to its
+    // nearest EXISTING ancestor (the root itself may not exist until the first fanout).
+    let dir = resolve(meta.worktree_root || resolve(cwd, "..", "_worktrees"));
+    while (!existsSync(dir)) {
+      const up = dirname(dir);
+      if (up === dir) break;
+      dir = up;
+    }
+    const s = statfsSync(dir);   // Node >= 18.15, win32 + POSIX
+    return { perWorktreeGb, freeGb: (s.bavail * s.bsize) / 2 ** 30 };
+  } catch {
+    return null;
+  }
+}
+
+export function systemInfo() {
+  const cpus = os.cpus() || [];
+  return {
+    cores: cpus.length || 4,
+    totalGb: os.totalmem() / 2 ** 30,
+    freeGb: os.freemem() / 2 ** 30,
+    platform: os.platform(),
+  };
+}
+
+const avg = (xs) => (xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0);
+
+// Recommend a concurrency cap over the set of slices we'd actually fan out (`ready`).
+// opts: { sys, useFree (RAM basis), reviewCeiling, osCoreReserve, osRamReserveGb,
+//         disk ({ perWorktreeGb, freeGb } from probeDisk; absent/null → no disk ceiling) }
+export function recommendConcurrency(ready, graph, opts = {}) {
+  const sys = opts.sys || systemInfo();
+  const reviewCeiling = opts.reviewCeiling ?? 5;
+  const coreReserve = opts.osCoreReserve ?? 2;     // leave cores for the OS/editor/lead
+  const ramReserve = opts.osRamReserveGb ?? 4;
+  const disk = opts.disk || null;                  // stays PURE: callers probe (probeDisk) and inject
+
+  const COST = costTable(graph);
+  const costs = (ready.length ? ready : [null]).map((n) =>
+    n ? COST[nodeWeight(n, graph)] : COST.medium
+  );
+  const avgRam = avg(costs.map((c) => c.ram)) || COST.medium.ram;
+  const avgCores = avg(costs.map((c) => c.cores)) || COST.medium.cores;
+
+  const usableCores = Math.max(1, sys.cores - coreReserve);
+  const ramBasis = opts.useFree ? sys.freeGb : sys.totalGb * 0.75; // 75% of total, or live-free
+  const usableRamGb = Math.max(1, ramBasis - ramReserve);
+
+  const cpuCap = Math.max(1, Math.floor(usableCores / avgCores));
+  const ramCap = Math.max(1, Math.floor(usableRamGb / avgRam));
+  const workCap = Math.max(1, ready.length || 1);
+
+  const candidates = [
+    { n: cpuCap,        why: `CPU — ${sys.cores} cores (− ${coreReserve} reserved) ÷ ~${avgCores.toFixed(1)}/session` },
+    { n: ramCap,        why: `RAM — ~${ramBasis.toFixed(0)}GB usable ÷ ~${avgRam.toFixed(1)}GB/session` },
+    { n: workCap,       why: `work — ${ready.length} independent ready slice(s)` },
+    { n: reviewCeiling, why: `review — PR review/merge bottleneck (soft ceiling)` },
+  ];
+  // Disk ceiling — the only one allowed to compute to 0: recommended stays >= 1 (soft
+  // auto-dial), but callers that create worktrees (fan, grab) hard-block on disk.cap < 1.
+  let diskCap = null;
+  if (disk) {
+    const diskReserve = opts.diskReserveGb ?? 2;
+    diskCap = Math.floor(Math.max(0, disk.freeGb - diskReserve) / Math.max(disk.perWorktreeGb, 0.01));
+    candidates.push({ n: Math.max(diskCap, 0), why: `disk — need ~${disk.perWorktreeGb.toFixed(1)}GB/worktree, ${disk.freeGb.toFixed(1)}GB free` });
+  }
+  const binding = candidates.reduce((a, b) => (b.n < a.n ? b : a));
+  return {
+    recommended: Math.max(1, binding.n),
+    binding,
+    candidates,
+    sys,
+    disk: disk ? { ...disk, cap: diskCap } : null,
+    avgRam,
+    avgCores,
+    weights: ready.map((n) => ({ invoke: n.invoke, weight: nodeWeight(n, graph) })),
+  };
+}

package/scripts/lib/render-core.mjs

@@ -0,0 +1,215 @@
+// roadmap — pure renderer: roadmap graph -> SLICES.md string.
+// No IO: takes a parsed graph, returns the markdown. render.mjs writes it to a file;
+// the MCP mutate tools call it to re-render SLICES.md after editing the YAML, so the
+// generated view and the source can never drift.
+
+import {
+  flatten, computeWaves, execPlan, sessionsRemaining,
+  statusDisplay, emojiFor, isDone, coherenceEnabled,
+} from "./graph.mjs";
+import { executionDirectiveLines } from "./execution.mjs";
+import { tierBadge } from "./priority.mjs";
+
+// renderMarkdown(graph, { cap }) -> string. cap defaults to meta.default_concurrency (or 3).
+export function renderMarkdown(graph, opts = {}) {
+  const model = flatten(graph);
+  const cap = opts.cap != null ? Number(opts.cap) : ((graph.meta && graph.meta.default_concurrency) || 3);
+  const links = (graph.meta && graph.meta.links) || {};   // optional repo cross-refs (narrative/status/tracker/bootstrap/strategy)
+  const mdlink = (label, path) => (path ? `[\`${path}\`](${path})` : null);
+
+  const B = "`";
+  const lines = [];
+  const w = (s = "") => lines.push(s);
+
+  // ---- header / intro -------------------------------------------------------
+  w("<!-- GENERATED from docs/roadmap/roadmap.yaml by /sync (render.mjs). Do not edit this file directly — edit the YAML and re-render. -->");
+  w("# Slices — the pickup-able work catalog");
+  w("");
+  const introRefs = [
+    links.narrative && `mirrored in ${mdlink("narrative", links.narrative)}`,
+    (links.status || links.tracker) && `tracked in ${[mdlink("status", links.status), mdlink("tracker", links.tracker)].filter(Boolean).join(" + ")}`,
+  ].filter(Boolean);
+  w(`> **What this is:** the menu, grouped by PI (Program Increment) with sprints nested under each. Each sprint is a named **slice** you can pick up cold: spin up a session, name the slice, and it reads that slice's prescribed read-order and self-orients. Slice names are the \`/slice\` keys${introRefs.length ? ", " + introRefs.join(", ") : ""}.`);
+  w("");
+  w("Use `roadmap show <name>` to orient on a menu entry; `roadmap plan` computes ready waves; `roadmap fan` prepares worktrees and can launch an explicitly configured assistant; `roadmap render` refreshes this file after merges. Claude slash skills are optional conveniences where installed.");
+  w("");
+  // Backlog pointer — emitted only when the repo has a backlog (opts.backlog), so a
+  // backlog-free repo renders byte-identically.
+  if (opts.backlog) {
+    w(`> **Backlog:** ${opts.backlog.open} open item(s) — erratic/follow-up work lives in [\`docs/BACKLOG.md\`](BACKLOG.md); capture with \`/backlog\` or \`roadmap backlog add\`, launch with \`roadmap grab <id>\`.`);
+    w("");
+  }
+
+  // ---- cross-PI wave map ----------------------------------------------------
+  w(`## Ready now — wave map (cap ${cap})`);
+  w("");
+  w("Derived from the dependency graph: which slices can run concurrently right now, what waits behind them, and what is held on a human. Change the cap with `roadmap plan --cap N` or `roadmap fan --cap N`.");
+  w("");
+  let waveResult;
+  try {
+    waveResult = computeWaves(model, cap, { coherence: coherenceEnabled(graph.meta) });
+  } catch (e) {
+    w(`> ⚠ ${e.message}`);
+    waveResult = { waves: [], held: { onHuman: [], blocked: [] } };
+  }
+  if (waveResult.waves.length === 0) {
+    w("_No agent-runnable slices right now._");
+  } else {
+    waveResult.waves.forEach((wave, i) => {
+      w(`**Wave ${i + 1}** — launch concurrently (disjoint files, deps satisfied):`);
+      for (const n of wave) {
+        const files = [...n.touches, ...n.owns];
+        const fileNote = files.length ? ` · touches ${files.map((f) => B + short(f) + B).join(", ")}` : "";
+        const badge = tierBadge(n.priority);
+        w(`- ${badge ? `**[${badge}]** ` : ""}${B}/slice ${n.invoke}${B} — ${n.what}${fileNote}`);
+      }
+      w("");
+    });
+  }
+  if (waveResult.held.onHuman.length) {
+    w("**Held on a human:**");
+    for (const n of waveResult.held.onHuman) {
+      w(`- ${B}/slice ${n.invoke}${B} — gated on **${n.gatedOn}** — ${n.what}`);
+    }
+    w("");
+  }
+  w("---");
+  w("");
+
+  // ---- roadmap: PIs → sprints ----------------------------------------------
+  w("## Roadmap — PIs → sprints");
+  w("");
+  for (const pi of graph.pis) {
+    const rem = sessionsRemaining(pi);
+    const remStr = rem > 0 ? ` · ~${fmt(rem)} session${rem === 1 ? "" : "s"} remaining` : "";
+    const plan = execPlan(pi);
+    w(`### ${pi.program_label || pi.id.toUpperCase()} — ${pi.title} · ${statusDisplay(pi.status)}${remStr}`);
+    if (pi.theme) w(`> ${pi.theme}`);
+    // sprint-status strip
+    const strip = (pi.sprints || []).map((s) => `${s.id.toUpperCase()} ${emojiFor(s.status)}`).join(" · ");
+    if (strip) w(`> Sprints: ${strip}`);
+    if (plan) w(`> Exec plan: ${plan}${pi.exec_hint ? `  _(human hint: ${pi.exec_hint})_` : ""}`);
+    if (pi.deps && pi.deps.length) w(`> Deps: ${pi.deps.map((d) => d.toUpperCase()).join(", ")}`);
+    if (pi.exit_criteria) w(`> Exit: ${oneLine(pi.exit_criteria)}`);
+    w("");
+    w("| Sprint | Invoke | Status | Sessions | Deps | What |");
+    w("|---|---|---|---|---|---|");
+    for (const sp of pi.sprints) {
+      const node = model.nodes.find((n) => n.nodeKey === `${pi.id}/${sp.id}`);
+      const sess = isDone(sp.status) ? "—" : (typeof sp.est_sessions === "number" ? `~${fmt(sp.est_sessions)}` : "?");
+      const deps = depCell(node);
+      const prs = (sp.prs && sp.prs.length) ? ` · ${sp.prs.join(" ")}` : "";
+      const badge = tierBadge(sp.priority);
+      const dtier = sp.dispatch_tier ? ` · ${B}dispatch: ${sp.dispatch_tier}${B}` : "";
+      w(`| ${sp.id.toUpperCase()} | ${B}/slice ${sp.invoke}${B} | ${statusDisplay(sp.status, sp.status_label)}${badge ? ` · **${badge}**` : ""}${dtier} | ${sess} | ${deps} | ${sp.what || sp.title}${prs} |`);
+    }
+    w("");
+  }
+  w("---");
+  w("");
+
+  // ---- recently completed ---------------------------------------------------
+  const completed = model.nodes.filter((n) => isDone(n.status) && (n.prs.length || n.completedOn));
+  if (completed.length) {
+    w(`**Recently completed:**`);
+    w("");
+    w("| Slice | PI | PRs |");
+    w("|---|---|---|");
+    for (const n of completed) {
+      w(`| ${n.id.toUpperCase()} | ${n.programLabel} | ${n.prs.join(" ") || "—"} |`);
+    }
+    w("");
+  }
+
+  // ---- default gate ---------------------------------------------------------
+  if (graph.meta && graph.meta.default_gate) {
+    w("**Default verification gate** (every slice, unless its entry overrides `gate`):");
+    w("");
+    w("```bash");
+    w(graph.meta.default_gate.trimEnd());
+    w("```");
+    w("");
+  }
+  w("---");
+  w("");
+
+  // ---- detail entries (pickup-able = not complete) --------------------------
+  w("## Detail — `/slice <name>` reads these");
+  w("");
+  for (const pi of graph.pis) {
+    for (const sp of pi.sprints) {
+      if (isDone(sp.status)) continue;
+      const node = model.nodes.find((n) => n.nodeKey === `${pi.id}/${sp.id}`);
+      w(`### ${B}${sp.invoke}${B}`);
+      // Execution directive at the TOP of the read-out (only when the slice declares one — a
+      // slice without an execution block renders byte-identically to before).
+      const exec = executionDirectiveLines(node);
+      if (exec) {
+        exec.forEach((line) => w(`> ${line}`));
+        w("");
+      }
+      w(`- **What:** ${sp.what || sp.title}`);
+      w(`- **Status:** ${statusDisplay(sp.status, sp.status_label)} (${pi.program_label || pi.id.toUpperCase()}${pi.id ? ` · ${sp.id.toUpperCase()}` : ""})`);
+      if (sp.priority && (tierBadge(sp.priority) || sp.priority.weight != null || sp.priority.reason)) {
+        const parts = [tierBadge(sp.priority), sp.priority.weight != null ? `weight ${sp.priority.weight}` : null].filter(Boolean).join(" · ");
+        w(`- **Priority:** ${parts || "(set)"}${sp.priority.reason ? ` — ${oneLine(sp.priority.reason)}` : ""}`);
+      }
+      if (node && (node.deps.length || node.piDeps.length)) {
+        w(`- **Deps:** ${depCell(node)}`);
+      }
+      if (sp.read_order && sp.read_order.length) {
+        w(`- **Read-order:**`);
+        sp.read_order.forEach((r, i) => w(`  ${i + 1}. ${r}`));
+      }
+      if (sp.resume_action) w(`- **Resume / next action:** ${oneLine(sp.resume_action)}`);
+      const gateText = !sp.gate || sp.gate === "default"
+        ? "default verification gate"
+        : oneLine(sp.gate).replace(/\{\{\s*default\s*\}\}/gi, "default gate");
+      w(`- **Gate:** ${gateText}`);
+      if (sp.gated_on) w(`- **Gated on:** ${sp.gated_on} (an agent prepares; it does not perform the gate).`);
+      w("");
+    }
+  }
+
+  // ---- footer ---------------------------------------------------------------
+  w("---");
+  w("");
+  w("## Maintaining this catalog");
+  w("");
+  w("This file is **generated** from [`roadmap/roadmap.yaml`](roadmap/roadmap.yaml). To change it, edit the YAML and run `/sync` (which reconciles statuses against merged PRs + the tracker, then re-renders). `/slice` reads the YAML directly to orient; `/fanout` reads it to compute waves and launch sessions. Slice **invoke keys are stable** — they are the `/slice` keys and are referenced from `ROADMAP.md`.");
+  w("");
+  const seeAlso = [
+    links.narrative && `- **Narrative shape** → ${mdlink("narrative", links.narrative)}`,
+    links.bootstrap && `- **Cold-start orientation** → ${mdlink("bootstrap", links.bootstrap)}`,
+    (links.status || links.tracker) && `- **Live status** → ${[mdlink("status", links.status), mdlink("tracker", links.tracker)].filter(Boolean).join(" + ")}`,
+    links.strategy && `- **Strategy / positioning** → ${mdlink("strategy", links.strategy)}`,
+    "- **Resume a specific session** → `/pickup`",
+  ].filter(Boolean);
+  if (seeAlso.length) {
+    w("## See also");
+    w("");
+    seeAlso.forEach((l) => w(l));
+    w("");
+  }
+
+  return lines.join("\n") + "\n";
+
+  // ---- helpers --------------------------------------------------------------
+  function depCell(node) {
+    if (!node) return "—";
+    const parts = [];
+    for (const d of node.deps) parts.push(d.split("/")[1].toUpperCase());
+    for (const p of node.piDeps) parts.push(p.toUpperCase());
+    return parts.length ? parts.join(", ") : "—";
+  }
+  function oneLine(s) {
+    return String(s).replace(/\s*\n\s*/g, " ").trim();
+  }
+  function fmt(n) {
+    return String(n);
+  }
+  function short(p) {
+    const segs = String(p).split("/");
+    return segs[segs.length - 1] || p;
+  }
+}

package/scripts/lib/review-core.mjs

@@ -0,0 +1,104 @@
+// roadmap — review brain (PURE). Diffs two graph/backlog snapshots (old = the YAML at the
+// review anchor via git show, new = the working tree) into the /debrief digest: what shipped,
+// what grew, what's stuck, and whether scope is outrunning shipping. No IO — scripts/review.mjs
+// resolves the anchor commit and injects both parsed YAMLs.
+
+import { flatten, isDone, HELD_STATUSES } from "./graph.mjs";
+import { sprawlWarnings, captureRatio } from "./sync-core.mjs";
+
+const HELD = new Set(HELD_STATUSES);
+
+// Sprints keyed by invoke (the stable key); PIs by id. A sprint added AND completed inside
+// the window appears in both addedSprints and completedSlices — that's honest, not a bug.
+export function graphDiff(oldGraph, newGraph) {
+  const oldM = flatten(oldGraph && oldGraph.pis ? oldGraph : { pis: [] });
+  const newM = flatten(newGraph);
+  const oldByInvoke = new Map(oldM.nodes.map((n) => [n.invoke, n]));
+  const newByInvoke = new Map(newM.nodes.map((n) => [n.invoke, n]));
+  const oldPis = new Set(((oldGraph && oldGraph.pis) || []).map((p) => p.id));
+
+  const addedPis = (newGraph.pis || []).filter((p) => !oldPis.has(p.id)).map((p) => ({ id: p.id, title: p.title }));
+  const addedSprints = [];
+  const completedSlices = [];
+  const statusFlips = [];
+  const priorityChanges = [];
+  const stillHeld = [];
+
+  for (const n of newM.nodes) {
+    const o = oldByInvoke.get(n.invoke);
+    if (!o) {
+      addedSprints.push({ invoke: n.invoke, pi: n.piId, title: n.title });
+      if (isDone(n.status)) completedSlices.push({ invoke: n.invoke, pi: n.piId, title: n.title, prs: n.prs });
+      continue;
+    }
+    if (!isDone(o.status) && isDone(n.status)) {
+      completedSlices.push({ invoke: n.invoke, pi: n.piId, title: n.title, prs: n.prs });
+    } else if (o.status !== n.status) {
+      statusFlips.push({ invoke: n.invoke, from: o.status, to: n.status });
+    }
+    const ot = (o.priority && o.priority.tier) || null;
+    const nt = (n.priority && n.priority.tier) || null;
+    if (ot !== nt) priorityChanges.push({ invoke: n.invoke, from: ot, to: nt });
+    if (HELD.has(o.status) && HELD.has(n.status)) stillHeld.push({ invoke: n.invoke, status: n.status });
+  }
+  const removedSprints = oldM.nodes.filter((o) => !newByInvoke.has(o.invoke))
+    .map((o) => ({ invoke: o.invoke, pi: o.piId, title: o.title }));
+
+  return { addedPis, addedSprints, completedSlices, removedSprints, statusFlips, priorityChanges, stillHeld };
+}
+
+// Either snapshot may be null (no backlog.yaml then/now).
+export function backlogDiff(oldB, newB) {
+  const oldItems = new Map((((oldB && oldB.items) || [])).map((i) => [i.id, i]));
+  const captured = [];
+  const closed = [];
+  const promoted = [];
+  for (const i of (newB && newB.items) || []) {
+    const o = oldItems.get(i.id);
+    if (!o) { captured.push({ id: i.id, title: i.title, kind: i.kind }); continue; }
+    const wasOpen = o.status === "open" || o.status === "in_progress";
+    if (wasOpen && (i.status === "done" || i.status === "dropped")) closed.push({ id: i.id, title: i.title, status: i.status });
+    if (o.status !== "promoted" && i.status === "promoted") promoted.push({ id: i.id, promoted_to: i.promoted_to || null });
+  }
+  return { captured, closed, promoted };
+}
+
+// Fragmentation: PIs with work both started (done/active sprint) AND still open — the count
+// of half-open PIs the coherence scheduler exists to shrink.
+export function pisInFlight(graph) {
+  let count = 0;
+  for (const pi of graph.pis || []) {
+    const sprints = pi.sprints || [];
+    const started = sprints.some((s) => isDone(s.status) || s.status === "active");
+    const open = sprints.some((s) => !isDone(s.status));
+    if (started && open) count += 1;
+  }
+  return count;
+}
+
+// The /debrief evidence base. The sprawl lines come from the SAME function /sync uses —
+// the two guardrails can never disagree.
+export function reviewDigest({ gd, bd, graph }) {
+  const added = bd.captured.length + gd.addedSprints.length;
+  const completed = gd.completedSlices.length;
+  return {
+    shipped: gd.completedSlices,
+    captured: { items: bd.captured, sprints: gd.addedSprints },
+    closedItems: bd.closed,
+    promoted: bd.promoted,
+    netGrowth: { added, completed, ratio: Math.round((added / Math.max(completed, 1)) * 10) / 10 },
+    sprawl: sprawlWarnings({
+      completed,
+      captured: bd.captured.length,
+      addedSprints: gd.addedSprints.length,
+      addedPis: gd.addedPis.map((p) => p.id),
+      ratioThreshold: captureRatio(graph.meta),
+    }),
+    aging: gd.stillHeld,
+    newPis: gd.addedPis,
+    removed: gd.removedSprints,
+    pisInFlight: pisInFlight(graph),
+    priorityChanges: gd.priorityChanges,
+    statusFlips: gd.statusFlips,
+  };
+}

package/scripts/lib/store.mjs

@@ -0,0 +1,113 @@
+// roadmap — shared mutation IO. The ONE read → mutate → validate → write → re-render
+// sequence every mutating surface uses (mcp.mjs, set.mjs, backlog.mjs, promote.mjs), so a
+// validation failure can never leave a half-written YAML or a stale generated view.
+// Both mutators re-render BOTH generated files when both sources exist (a backlog edit
+// changes the open-count pointer in SLICES.md; a roadmap edit changes nothing in BACKLOG.md
+// but re-rendering is cheaper than proving it).
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import YAML from "yaml";
+import { REL } from "./cli-core.mjs";
+import { loadGraph } from "./graph.mjs";
+import { renderMarkdown } from "./render-core.mjs";
+import { validateDocOrThrow, serialize } from "./mcp-core.mjs";
+import { validateBacklogDocOrThrow, renderBacklogMarkdown, openCount } from "./backlog-core.mjs";
+
+export const BACKLOG_REL = ["docs", "roadmap", "backlog.yaml"];
+const EMPTY_BACKLOG = "meta:\n  schema_version: 1\nitems: []\n";
+
+export function roadmapPaths(root) {
+  return { yaml: join(root, ...REL), slices: join(root, "docs", "SLICES.md") };
+}
+export function backlogPaths(root) {
+  return { yaml: join(root, ...BACKLOG_REL), md: join(root, "docs", "BACKLOG.md") };
+}
+
+// Plain backlog object, or null when the repo has no backlog.yaml.
+export function loadBacklog(root) {
+  const p = backlogPaths(root).yaml;
+  if (!existsSync(p)) return null;
+  return YAML.parse(readFileSync(p, "utf8"));
+}
+
+// Backlog item ids as of origin/main's LAST-FETCHED state (the remote-tracking ref — no
+// network call). Concurrent sessions each allocate ids against their own stale checkout;
+// five bNN collisions in one day (2026-07-10) came from exactly that. Feeding these ids
+// into addItem closes most of the race window without a fetch. Degrades to [] on any
+// failure (no git, no remote-tracking ref, no backlog upstream) — allocation then falls
+// back to local-only, exactly the pre-guard behavior.
+export function originBacklogIds(root, { ref = "origin/main" } = {}) {
+  try {
+    const r = spawnSync("git", ["show", `${ref}:${BACKLOG_REL.join("/")}`], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    if (r.status !== 0 || !r.stdout) return [];
+    const parsed = YAML.parse(r.stdout);
+    return (parsed && parsed.items ? parsed.items : []).map((i) => String(i.id));
+  } catch { return []; }
+}
+
+// Render opts for SLICES.md: the backlog pointer appears only when backlog.yaml exists.
+export function slicesRenderOpts(root, backlog = loadBacklog(root)) {
+  return backlog ? { backlog: { open: openCount(backlog) } } : {};
+}
+
+// fn(doc) mutates the roadmap Document in place and returns a summary object.
+// Any throw (from fn or the pre-write gate) leaves every file untouched.
+export function mutateRoadmap(root, fn) {
+  const p = roadmapPaths(root);
+  const doc = YAML.parseDocument(readFileSync(p.yaml, "utf8"));
+  const summary = fn(doc);
+  const graph = validateDocOrThrow(doc);
+  writeFileSync(p.yaml, serialize(doc), "utf8");
+  writeFileSync(p.slices, renderMarkdown(graph, slicesRenderOpts(root)), "utf8");
+  return { ...summary, rerendered: "docs/SLICES.md" };
+}
+
+// Two-file mutation (promote): fn(roadmapDoc, backlogDoc) edits both; BOTH are validated
+// before EITHER is written, so the only remaining failure window is an fs error between the
+// two writes. ponytail: not truly atomic; temp-file+rename choreography across two files
+// isn't worth it for a local dev tool.
+export function mutateBoth(root, fn) {
+  const rp = roadmapPaths(root);
+  const bp = backlogPaths(root);
+  if (!existsSync(bp.yaml)) throw new Error(`no ${BACKLOG_REL.join("/")} — nothing to promote from`);
+  const rDoc = YAML.parseDocument(readFileSync(rp.yaml, "utf8"));
+  const bDoc = YAML.parseDocument(readFileSync(bp.yaml, "utf8"));
+  const summary = fn(rDoc, bDoc);
+  const graph = validateDocOrThrow(rDoc);
+  const backlog = validateBacklogDocOrThrow(bDoc);
+  writeFileSync(rp.yaml, serialize(rDoc), "utf8");
+  writeFileSync(bp.yaml, serialize(bDoc), "utf8");
+  writeFileSync(rp.slices, renderMarkdown(graph, { backlog: { open: openCount(backlog) } }), "utf8");
+  writeFileSync(bp.md, renderBacklogMarkdown(backlog), "utf8");
+  return { ...summary, rerendered: "docs/SLICES.md + docs/BACKLOG.md" };
+}
+
+// Same sequence for backlog.yaml → BACKLOG.md, plus a SLICES.md refresh (open-count pointer).
+// createIfMissing: backlog_add bootstraps the file on first capture.
+export function mutateBacklog(root, fn, { createIfMissing = false } = {}) {
+  const p = backlogPaths(root);
+  let src;
+  let created = false;
+  if (existsSync(p.yaml)) src = readFileSync(p.yaml, "utf8");
+  else if (createIfMissing) { src = EMPTY_BACKLOG; created = true; }
+  else throw new Error(`no ${BACKLOG_REL.join("/")} — capture something first ('roadmap backlog add' or the backlog_add tool creates it)`);
+  const doc = YAML.parseDocument(src);
+  if (created) {
+    // Block style from birth — the template's `items: []` is a flow seq, and items added to a
+    // flow collection stay flow (unreadable once prompts go multiline). Existing files keep
+    // whatever style their author chose.
+    const seq = doc.get("items");
+    if (seq) seq.flow = false;
+  }
+  const summary = fn(doc);
+  const backlog = validateBacklogDocOrThrow(doc);
+  writeFileSync(p.yaml, serialize(doc), "utf8");
+  writeFileSync(p.md, renderBacklogMarkdown(backlog), "utf8");
+  const rp = roadmapPaths(root);
+  if (existsSync(rp.yaml)) {
+    writeFileSync(rp.slices, renderMarkdown(loadGraph(rp.yaml), slicesRenderOpts(root, backlog)), "utf8");
+  }
+  return { ...summary, rerendered: "docs/BACKLOG.md" };
+}