@connorbritain/roadmap 0.3.0

package/scripts/mcp.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+// roadmap — MCP server (hand-rolled JSON-RPC 2.0 over stdio, newline-delimited).
+// Exposes the roadmap as agent-callable tools: read (plan / ready_wave / show / validate) and
+// mutate (add_pi / add_sprint / set_status / set_fields / prune). Mutations edit roadmap.yaml
+// through the yaml Document API (comments preserved), validate the result before writing, and
+// re-render SLICES.md. Zero new deps: just `yaml` + the repo's own libs.
+//
+// Bundled in the plugin via .mcp.json; also runnable as `roadmap mcp` for debugging.
+
+import { createInterface } from "node:readline";
+import { findRepoRoot, REL } from "./lib/cli-core.mjs";
+import { loadGraph } from "./lib/graph.mjs";
+import { mutateRoadmap, mutateBacklog, mutateBoth, loadBacklog, roadmapPaths, originBacklogIds } from "./lib/store.mjs";
+import { TOOLS, READ_HANDLERS, MUTATION_HANDLERS } from "./lib/mcp-core.mjs";
+import { BACKLOG_TOOLS, BACKLOG_READ_HANDLERS, BACKLOG_MUTATION_HANDLERS, performPromotion } from "./lib/backlog-core.mjs";
+import { linearState, linearStatusLine, normalizeLinearConfig } from "./lib/linear-core.mjs";
+import { platedKeys } from "./lib/plate-core.mjs";
+import { runSync, runNote, runNotes, runProjectUpdate } from "./linear.mjs";
+import { runDispatch, runFanCloud } from "./dispatch.mjs";
+import { runEstimate, runTimeline, runLog } from "./estimate.mjs";
+import { LOG_STATUSES } from "./lib/estimate-core.mjs";
+
+// Always registered; politely erroring when unconfigured beats config-gated registration
+// (tools/list would need IO). linear_sync reuses linear.mjs's runSync — one sync implementation.
+const LINEAR_TOOLS = [
+  { name: "linear_status", description: "Linear integration state for this roadmap (configured / authed / last sync). Zero network. Read-only.",
+    inputSchema: { type: "object", properties: {} } },
+  { name: "linear_sync", description: "Run the Linear sync: push the roadmap/backlog projection, fetch the pull inbox. dry=true plans without writing. With meta.linear.pull=propose the inbox is returned as proposals for you to apply via backlog_add/set_status/backlog_set.",
+    inputSchema: { type: "object", properties: { dry: { type: "boolean" }, push: { type: "boolean" }, pull: { type: "boolean" } } } },
+];
+
+// Cloud dispatch — lets the SESSION conduct a cloud fanout. Fires on the currently-authed
+// claude.ai account's plan (no local worktree/disk). fan_cloud PREVIEWS by default; confirm=true
+// actually fires (it spends plan usage + opens real PRs). Needs ~/.claude-routines.json configured.
+const CLOUD_TOOLS = [
+  { name: "dispatch", description: "Fire a Claude Code CLOUD session for ONE slice or backlog item via the Routines API — runs on the currently-authed claude.ai account's plan, no local worktree or disk. Returns the session URL (and comments it on the Linear issue when the node is mapped). With meta.linear.cycles on, an out-of-cycle slice refuses (elect it via 'roadmap cycle', or pass force=true — the logged escape hatch, surfaces as scope change). Requires ~/.claude-routines.json (docs/DEPLOYMENT.md § Cloud dispatch).",
+    inputSchema: { type: "object", required: ["key"], properties: { key: { type: "string", description: "slice invoke key or backlog id" }, force: { type: "boolean", description: "override the cycle lock for this one dispatch (out-of-cycle work; surfaces as scope change)" } } } },
+  { name: "fan_cloud", description: "Conduct a cloud FANOUT of a ready wave — the worktree-free, disk-free fanout. Each slice fires a Claude Code cloud session on the authed account's plan and opens a PR. DEFAULT is a dry preview (lists what would fire, spawns nothing); pass confirm=true to actually fire. With meta.linear.cycles on, out-of-cycle slices are excluded from the wave (reported in excludedOutOfCycle; pass all=true to include). Returns session URLs when confirmed. The conducting session reconciles the resulting PRs via the roadmap marker (/sync).",
+    inputSchema: { type: "object", properties: {
+      wave: { type: "integer", minimum: 1, description: "which ready wave (default 1)" },
+      cap: { type: "integer", minimum: 1, description: "max slices in the wave (default the review ceiling, 5 — machine limits don't apply to cloud)" },
+      confirm: { type: "boolean", description: "false/absent = preview only; true = actually fire the cloud sessions" },
+      all: { type: "boolean", description: "include out-of-cycle slices in the wave (explicit override of the cycle lock)" } } } },
+];
+
+// plate_list is a read that needs the backlog too (in_progress items), so it's handled inline here
+// rather than in mcp-core's graph-only READ_HANDLERS. The plate_set/add/remove mutations live in TOOLS.
+const PLATE_TOOLS = [
+  { name: "plate_list", description: "The current plate — the curated batch projected to Linear's My Issues (assignee=you): explicit meta.plate entries plus auto-included active/in_progress work. Returns { enabled, explicit, plate, plate_max }. Read-only.",
+    inputSchema: { type: "object", properties: {} } },
+];
+
+// The journal — progress notes on the mapped issue, so in-flight work survives a dead session.
+const JOURNAL_TOOLS = [
+  { name: "issue_note", description: "Post a progress note to a slice/backlog item's mapped Linear issue — the resumability trail. Use at checkpoints (a gate cleared, a blocker hit, a logical unit done) so a session that dies mid-flight can be picked up from where it left off. kind: progress|blocker|done.",
+    inputSchema: { type: "object", required: ["key", "text"], properties: { key: { type: "string", description: "slice invoke key or backlog id" }, text: { type: "string" }, kind: { enum: ["progress", "blocker", "done"] } } } },
+  { name: "issue_notes", description: "Read a slice/backlog item's Linear issue comment stream (chronological). Call this FIRST when picking up in-flight work — it's where the last session left off. Read-only.",
+    inputSchema: { type: "object", required: ["key"], properties: { key: { type: "string", description: "slice invoke key or backlog id" } } } },
+  { name: "project_update", description: "Post a PI-level digest to its Linear project update (the 'where this bet stands' rollup) — for milestones, not per-checkpoint. Degradation-guarded: returns { posted:false } if Linear rejects it.",
+    inputSchema: { type: "object", required: ["pi", "body"], properties: { pi: { type: "string" }, body: { type: "string" } } } },
+];
+
+// agent-time bridge — a slice's duration estimate, cached on the slice for the timeline rollup.
+const ESTIMATE_TOOLS = [
+  { name: "estimate", description: "Estimate a slice's duration via agent-time (calibrated agent-rounds → wall-clock minutes) and cache it on the slice. Set the slice's shape (+ optional risks) first — an unclassified slice is skipped. Skips an already-estimated slice unless force=true; all=true estimates every classified slice. Needs the agent-time-estimator skill installed (or meta.estimation.engine).",
+    inputSchema: { type: "object", properties: { invoke: { type: "string", description: "slice invoke key" }, all: { type: "boolean" }, force: { type: "boolean" } } } },
+  { name: "timeline", description: "Roll the cached per-slice estimates up into a projected target date per PI (using the same wave/dependency/concurrency schedule the fanout runs) and write pi.projected_target_date back — the estimate-driven Linear timeline. Never overwrites an explicit pi.target_date. Returns the per-PI dates plus any unpriced/held slices excluded from the projection.",
+    inputSchema: { type: "object", properties: {} } },
+  { name: "estimate_log", description: "Log a completed slice's outcome to agent-time's calibration history (status pass|fail|partial|abandoned) so future estimates self-correct — the calibration loop. Requires the slice to have been estimated (carries estimate.task_id). Pass actual_rounds (and optionally actual_minutes) unless agent-time's round-counter hook auto-filled them; without either, agent-time rejects the log. Idempotent per task_id.",
+    inputSchema: { type: "object", required: ["invoke"], properties: { invoke: { type: "string", description: "slice invoke key" }, status: { enum: LOG_STATUSES }, actual_rounds: { type: "integer", minimum: 0 }, actual_minutes: { type: "number", minimum: 0 }, force: { type: "boolean" } } } },
+];
+
+const PROTOCOL_VERSION = "2024-11-05";
+const SERVER_INFO = { name: "graph", version: "0.2.0" };
+
+function repoRoot() {
+  const root = findRepoRoot(process.env.CODEX_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd());
+  if (!root) throw new Error(`no ${REL.join("/")} found at or above the project directory`);
+  return root;
+}
+
+function callTool(name, args) {
+  if (READ_HANDLERS[name]) {
+    const graph = loadGraph(roadmapPaths(repoRoot()).yaml);
+    return READ_HANDLERS[name](graph, args || {});
+  }
+  if (MUTATION_HANDLERS[name]) {
+    // mutateRoadmap = read → mutate → validate → write → re-render; a throw leaves files untouched.
+    return mutateRoadmap(repoRoot(), (doc) => MUTATION_HANDLERS[name](doc, args || {}));
+  }
+  if (BACKLOG_READ_HANDLERS[name]) {
+    return BACKLOG_READ_HANDLERS[name](loadBacklog(repoRoot()), args || {});
+  }
+  if (BACKLOG_MUTATION_HANDLERS[name]) {
+    // backlog_add gets origin/main ids injected so concurrent sessions cannot mint the same bNN.
+    const margs = name === "backlog_add" ? { ...(args || {}), origin_ids: (args && args.origin_ids) || originBacklogIds(repoRoot()) } : (args || {});
+    return mutateBacklog(repoRoot(), (doc) => BACKLOG_MUTATION_HANDLERS[name](doc, margs),
+      { createIfMissing: name === "backlog_add" });
+  }
+  if (name === "backlog_promote") {
+    // Spans both YAMLs: both validated before either is written.
+    return mutateBoth(repoRoot(), (rDoc, bDoc) => performPromotion(rDoc, bDoc, args || {}));
+  }
+  if (name === "linear_status") {
+    const root = repoRoot();
+    const graph = loadGraph(roadmapPaths(root).yaml);
+    const st = linearState({ meta: graph.meta, env: process.env });
+    return { configured: st.configured, authed: st.authed,
+      ...(st.cfg ? { team: st.cfg.team, granularity: st.cfg.granularity, pull: st.cfg.pull } : {}),
+      status: linearStatusLine(st) };
+  }
+  if (name === "linear_sync") {
+    // async; the tools/call path awaits. runSync itself throws the setup-guidance errors.
+    return runSync(repoRoot(), { dry: !!args.dry, pushOnly: args.pull === false, pullOnly: args.push === false });
+  }
+  if (name === "dispatch") {
+    // async; runDispatch fires the routine (or the Linear @-mention) and returns the session/comment.
+    return runDispatch(repoRoot(), args.key, { force: !!args.force });
+  }
+  if (name === "fan_cloud") {
+    // preview unless confirm=true; runFanCloud loops runDispatch over the ready wave.
+    return runFanCloud(repoRoot(), args || {});
+  }
+  if (name === "plate_list") {
+    const root = repoRoot();
+    const graph = loadGraph(roadmapPaths(root).yaml);
+    const set = platedKeys(graph, loadBacklog(root));
+    const explicit = Array.isArray(graph.meta && graph.meta.plate) ? graph.meta.plate : [];
+    const cfg = normalizeLinearConfig(graph.meta || {});
+    return { enabled: set != null, explicit, plate: set ? [...set] : [], plate_max: cfg ? cfg.plate_max : 7 };
+  }
+  if (name === "estimate") {
+    // sync (spawnSync); the tools/call path Promise-wraps it. Writes est_minutes back to the YAML.
+    return runEstimate(repoRoot(), { invoke: args.invoke, all: !!args.all, force: !!args.force });
+  }
+  if (name === "timeline") {
+    // pure rollup over cached estimates + write-back; no network.
+    return runTimeline(repoRoot(), {});
+  }
+  if (name === "estimate_log") {
+    // sync (spawnSync estimator log); idempotent per task_id. No YAML write.
+    return runLog(repoRoot(), { invoke: args.invoke, status: args.status, force: !!args.force,
+      actualRounds: args.actual_rounds, actualMinutes: args.actual_minutes });
+  }
+  if (name === "issue_note") return runNote(repoRoot(), args.key, { kind: args.kind, text: args.text }, {});
+  if (name === "issue_notes") return runNotes(repoRoot(), args.key, {});
+  if (name === "project_update") return runProjectUpdate(repoRoot(), args.pi, args.body, {});
+  throw new Error(`unknown tool "${name}"`);
+}
+
+const out = (obj) => process.stdout.write(JSON.stringify(obj) + "\n");
+
+function handle(msg) {
+  const { id, method, params } = msg;
+  if (method === "initialize") {
+    return out({ jsonrpc: "2.0", id, result: { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER_INFO } });
+  }
+  if (method === "notifications/initialized" || method === "initialized") return; // notification: no reply
+  if (method === "ping") return out({ jsonrpc: "2.0", id, result: {} });
+  if (method === "tools/list") {
+    return out({ jsonrpc: "2.0", id, result: { tools: [...TOOLS, ...BACKLOG_TOOLS, ...LINEAR_TOOLS, ...CLOUD_TOOLS, ...PLATE_TOOLS, ...JOURNAL_TOOLS, ...ESTIMATE_TOOLS] } });
+  }
+  if (method === "tools/call") {
+    const name = params && params.name;
+    const args = (params && params.arguments) || {};
+    // Promise-wrapped so async tools (linear_sync) work; sync tools resolve immediately.
+    return Promise.resolve().then(() => callTool(name, args)).then(
+      (result) => out({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] } }),
+      // MCP convention: tool failures come back as a result with isError, so the model sees why.
+      (e) => out({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true } }),
+    );
+  }
+  if (id !== undefined && id !== null) {
+    return out({ jsonrpc: "2.0", id, error: { code: -32601, message: `method not found: ${method}` } });
+  }
+}
+
+const rl = createInterface({ input: process.stdin });
+rl.on("line", (line) => {
+  const text = line.trim();
+  if (!text) return;
+  let msg;
+  try {
+    msg = JSON.parse(text);
+  } catch {
+    return out({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } });
+  }
+  try {
+    handle(msg);
+  } catch (e) {
+    if (msg && msg.id !== undefined) out({ jsonrpc: "2.0", id: msg.id, error: { code: -32603, message: e.message } });
+  }
+});

package/scripts/next.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// roadmap next — print the single highest-priority ready thing across the roadmap AND the
+// backlog, with its pickup brief. Roadmap wins ties (planned value work outranks erratic
+// work at equal priority). Read-only.
+
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { loadGraph } from "./lib/graph.mjs";
+import { loadBacklog } from "./lib/store.mjs";
+import { pickNext } from "./lib/backlog-core.mjs";
+import { tierBadge } from "./lib/priority.mjs";
+
+const graph = loadGraph("docs/roadmap/roadmap.yaml");
+const backlog = loadBacklog(process.cwd());
+const next = pickNext(graph, backlog);
+
+if (!next) {
+  console.log("Nothing ready: no runnable slices, no open backlog items. ('roadmap plan' shows what's held and why.)");
+  process.exit(0);
+}
+
+if (next.type === "slice") {
+  console.log(`Next up (roadmap): ${next.node.invoke}\n`);
+  const r = spawnSync("node", [join(dirname(fileURLToPath(import.meta.url)), "show.mjs"), next.node.invoke], { stdio: "inherit" });
+  console.log(`\nPick it up: /slice ${next.node.invoke}  ·  or fan it out: roadmap fan`);
+  process.exit(r.status ?? 0);
+}
+
+const it = next.item;
+const badge = tierBadge(it.priority);
+console.log(`Next up (backlog): ${it.id}  [${it.kind}${badge ? ` · ${badge}${it.priority.weight != null ? ` ${it.priority.weight}` : ""}` : ""}]`);
+console.log(`What:  ${it.title}`);
+if (it.priority && it.priority.reason) console.log(`Why:   ${it.priority.reason}`);
+if (it.source && (it.source.slice || it.source.note)) {
+  console.log(`From:  ${[it.source.slice, it.source.note].filter(Boolean).join(" — ")}`);
+}
+if (it.est_sessions != null) console.log(`Est:   ~${it.est_sessions} session(s)`);
+if (it.prompt) {
+  console.log(`\nPrompt (author instructions, verbatim):`);
+  String(it.prompt).trimEnd().split("\n").forEach((l) => console.log(`  ${l}`));
+}
+console.log(`\nPick it up: roadmap grab ${it.id}  ·  or promote it: roadmap promote ${it.id} --pi <pi>`);

package/scripts/plate.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// roadmap plate [list|add|rm|set|clear] — the curated batch that projects to Linear's My Issues (assignee=you).
+//   roadmap plate                 show the current plate (explicit entries + auto-included active work)
+//   roadmap plate add <key>...    add slice invoke keys / backlog ids (creates meta.plate if absent → feature on)
+//   roadmap plate rm  <key>...    remove explicit entries
+//   roadmap plate set <key>...    replace the explicit list
+//   roadmap plate clear           empty the explicit list (feature stays on; active work still auto-shows)
+// Assignment lands on the next 'roadmap linear sync' (or /sync). Completed slices auto-drain there.
+
+import { loadGraph } from "./lib/graph.mjs";
+import { loadBacklog, mutateRoadmap, roadmapPaths } from "./lib/store.mjs";
+import { setPlateDoc, platedKeys } from "./lib/plate-core.mjs";
+import { normalizeLinearConfig } from "./lib/linear-core.mjs";
+
+const args = process.argv.slice(2);
+const sub = args[0] && !args[0].startsWith("-") ? args[0] : "list";
+const keys = (sub === args[0] ? args.slice(1) : args).filter((a) => !a.startsWith("-"));
+const root = process.cwd();
+
+// key → { title, status, mapped } across slices + backlog items (for the list view)
+function indexOf(graph, backlog) {
+  const idx = new Map();
+  for (const pi of graph.pis || []) for (const sp of pi.sprints || []) idx.set(sp.invoke, { title: sp.title, status: sp.status, mapped: !!sp.linear });
+  for (const it of (backlog && backlog.items) || []) idx.set(it.id, { title: it.title, status: it.status, mapped: !!it.linear });
+  return idx;
+}
+
+try {
+  const graph = loadGraph(roadmapPaths(root).yaml);
+  const backlog = loadBacklog(root);
+  const explicit = Array.isArray(graph.meta && graph.meta.plate) ? graph.meta.plate.slice() : null;
+
+  if (sub === "list") {
+    const set = platedKeys(graph, backlog);
+    if (set == null) { console.log("The plate is OFF (no meta.plate). Turn it on:  roadmap plate add <slice-or-id>"); process.exit(0); }
+    const idx = indexOf(graph, backlog);
+    const cfg = normalizeLinearConfig(graph.meta || {});
+    const cap = cfg ? cfg.plate_max : 7;
+    const exp = Array.isArray(explicit) ? explicit : [];   // malformed meta.plate (validate errors on it) shouldn't raw-crash the list
+    console.log(`Plate — ${set.size} on My Issues${exp.length > cap ? `  (⚠ ${exp.length} explicit > plate_max ${cap})` : ""}`);
+    if (!set.size) console.log("  (empty)");
+    for (const key of set) {
+      const info = idx.get(key);
+      const auto = !exp.includes(key) ? "  (auto: active)" : "";
+      if (!info) console.log(`  • ${key}  — ⚠ matches no slice/backlog item (typo?)`);
+      else console.log(`  • ${key}  [${info.status}] ${info.title}${info.mapped ? "" : " — not in Linear yet (pushes on sync)"}${auto}`);
+    }
+    console.log("\nAssignment lands on the next 'roadmap linear sync'. Completed slices auto-drain.");
+    process.exit(0);
+  }
+
+  if (sub === "clear") {
+    const r = mutateRoadmap(root, (doc) => { setPlateDoc(doc, []); return { plate: "cleared" }; });
+    console.log(`✓ plate cleared (feature stays on; active work still auto-shows).  (re-rendered ${r.rerendered})`);
+    process.exit(0);
+  }
+
+  if (["add", "rm", "set"].includes(sub)) {
+    if (!keys.length) { console.error(`usage: roadmap plate ${sub} <slice-invoke-or-backlog-id> ...`); process.exit(2); }
+    let next;
+    if (sub === "set") next = [...new Set(keys)];
+    else if (sub === "add") next = [...new Set([...(explicit || []), ...keys])];
+    else { // rm
+      if (explicit == null) { console.log("The plate is off (no meta.plate) — nothing to remove."); process.exit(0); }
+      next = explicit.filter((k) => !keys.includes(k));
+    }
+    const r = mutateRoadmap(root, (doc) => { setPlateDoc(doc, next); return { plate: next.length }; });
+    console.log(`✓ plate ${sub}: ${next.length} explicit entr${next.length === 1 ? "y" : "ies"}${next.length ? ` [${next.join(", ")}]` : ""}  (sync to apply · re-rendered ${r.rerendered})`);
+    process.exit(0);
+  }
+
+  console.error(`roadmap plate: unknown subcommand "${sub}" (list | add | rm | set | clear)`);
+  process.exit(2);
+} catch (e) {
+  console.error(`✗ ${e.message}`);
+  process.exit(1);
+}

package/scripts/promote.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// roadmap promote <backlog-id> --pi <pi> [--id sN] — convert a backlog item into a roadmap
+// sprint. The item's id becomes the sprint's invoke key; title/est/gate/touches/prompt/priority
+// carry over; the item is marked promoted with a promoted_to back-link. Both YAMLs are
+// validated before either is written; both generated views re-render.
+
+import { mutateBoth } from "./lib/store.mjs";
+import { performPromotion } from "./lib/backlog-core.mjs";
+
+const args = process.argv.slice(2);
+const val = (n) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : undefined; };
+const id = args.find((a) => !a.startsWith("-") && a !== val("--pi") && a !== val("--id"));
+const pi = val("--pi");
+
+if (!id || !pi) {
+  console.error("usage: roadmap promote <backlog-id> --pi <pi> [--id sN]");
+  process.exit(2);
+}
+
+try {
+  const r = mutateBoth(process.cwd(), (rDoc, bDoc) => performPromotion(rDoc, bDoc, { id, pi, sprint_id: val("--id") }));
+  console.log(`✓ promoted ${r.promoted} → ${r.to}  (invoke stays '${r.promoted}'; re-rendered ${r.rerendered})`);
+  console.log(`  Next: roadmap show ${r.promoted} · scope it (deps/touches/read_order) via roadmap set or the slice-scoper agent.`);
+} catch (e) {
+  console.error(`✗ ${e.message}`);
+  process.exit(1);
+}

package/scripts/prompt.mjs

@@ -0,0 +1,124 @@
+// roadmap — zero-dependency terminal prompts for the bare-`roadmap` wizard.
+// IO file (raw-mode stdin, stdout, process.exit on cancel) — lives at scripts/ (not lib/), like the
+// other side-effecting entrypoints. select() uses raw-mode arrow-key navigation when the TTY
+// supports it, and DEGRADES to a numbered text prompt otherwise (so it never hangs on a terminal
+// without raw mode). number() and confirm() are line-based. Ctrl-C / ESC cancel cleanly (restore
+// the TTY, exit 0). The pure decision logic (movement, cap parsing) lives in lib/wizard-core.mjs.
+
+import readline from "node:readline";
+import { moveSelection, parseCap } from "./lib/wizard-core.mjs";
+
+const S = {
+  reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m",
+  cyan: "\x1b[36m", green: "\x1b[32m", red: "\x1b[31m",
+};
+
+const question = (rl, q) => new Promise((res) => rl.question(q, res));
+const clamp = (i, len) => Math.min(Math.max(0, i | 0), Math.max(0, len - 1));
+
+// Normalize a choice to { label, value, hint }. A bare string is both label and value.
+function norm(choice) {
+  if (typeof choice === "string") return { label: choice, value: choice, hint: "" };
+  return { label: choice.label, value: "value" in choice ? choice.value : choice.label, hint: choice.hint || "" };
+}
+
+function cancel() {
+  process.stdout.write(`\n${S.dim}Cancelled.${S.reset}\n`);
+  process.exit(0);
+}
+
+function renderList(items, idx) {
+  return items.map((it, i) => {
+    const sel = i === idx;
+    const cursor = sel ? `${S.cyan}❯${S.reset} ` : "  ";
+    const label = sel ? `${S.bold}${S.cyan}${it.label}${S.reset}` : it.label;
+    const hint = it.hint ? `  ${S.dim}${it.hint}${S.reset}` : "";
+    return `${cursor}${label}${hint}`;
+  });
+}
+
+// Single-select. Returns the chosen choice's value. Raw-mode arrows when available; else numbered.
+export function select(title, choices, opts = {}) {
+  const items = choices.map(norm);
+  const start = clamp(opts.defaultIdx ?? 0, items.length);
+  const canRaw = process.stdin.isTTY && typeof process.stdin.setRawMode === "function";
+  if (!canRaw) return numberedSelect(title, items, start);
+
+  return new Promise((resolve) => {
+    let idx = start;
+    process.stdout.write(`${S.bold}${title}${S.reset}  ${S.dim}(↑/↓, Enter)${S.reset}\n`);
+    process.stdout.write(renderList(items, idx).join("\n") + "\n");
+
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+
+    const redraw = () => {
+      process.stdout.write(`\x1b[${items.length}A`); // up to the first item line
+      for (const line of renderList(items, idx)) process.stdout.write(`\x1b[2K${line}\n`);
+    };
+    const teardown = () => {
+      process.stdin.setRawMode(false);
+      process.stdin.removeListener("keypress", onKey);
+      process.stdin.pause();
+    };
+    const onKey = (_str, key) => {
+      if (!key) return;
+      if (key.ctrl && key.name === "c") { teardown(); cancel(); return; }
+      if (key.name === "escape") { teardown(); cancel(); return; }
+      if (key.name === "return" || key.name === "enter") {
+        teardown();
+        process.stdout.write(`${S.green}✓${S.reset} ${S.dim}${title}:${S.reset} ${items[idx].label}\n`);
+        resolve(items[idx].value);
+        return;
+      }
+      const next = moveSelection(idx, key.name, items.length);
+      if (next !== idx) { idx = next; redraw(); }
+    };
+    process.stdin.on("keypress", onKey);
+  });
+}
+
+async function numberedSelect(title, items, startIdx) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  rl.on("SIGINT", () => { rl.close(); cancel(); });
+  try {
+    process.stdout.write(`${S.bold}${title}${S.reset}\n`);
+    items.forEach((it, i) =>
+      process.stdout.write(`  ${i + 1}) ${it.label}${it.hint ? `  ${S.dim}${it.hint}${S.reset}` : ""}\n`));
+    const def = startIdx + 1;
+    for (;;) {
+      const ans = (await question(rl, `Choose [1-${items.length}] (${def}): `)).trim();
+      if (ans === "") return items[startIdx].value;
+      const n = Number(ans);
+      if (Number.isInteger(n) && n >= 1 && n <= items.length) return items[n - 1].value;
+      process.stdout.write(`${S.red}Enter a number between 1 and ${items.length}.${S.reset}\n`);
+    }
+  } finally { rl.close(); }
+}
+
+// Whole-number prompt with a default and a [min,max] range. Re-asks on bad input.
+export async function number(title, { def, min = 1, max = Infinity } = {}) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  rl.on("SIGINT", () => { rl.close(); cancel(); });
+  try {
+    for (;;) {
+      const ans = await question(rl, `${S.bold}${title}${S.reset} ${S.dim}[${def}]${S.reset} `);
+      const res = parseCap(ans, { min, max, def });
+      if (res.error) { process.stdout.write(`${S.red}${res.error}${S.reset}\n`); continue; }
+      return res.value;
+    }
+  } finally { rl.close(); }
+}
+
+// Yes/No with a default. Blank → default.
+export async function confirm(title, def = false) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  rl.on("SIGINT", () => { rl.close(); cancel(); });
+  try {
+    const hint = def ? "Y/n" : "y/N";
+    const ans = (await question(rl, `${S.bold}${title}${S.reset} ${S.dim}[${hint}]${S.reset} `)).trim().toLowerCase();
+    if (ans === "") return def;
+    return ans === "y" || ans === "yes";
+  } finally { rl.close(); }
+}

package/scripts/render.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// roadmap — render roadmap.yaml → SLICES.md (+ backlog.yaml → BACKLOG.md when present).
+// Thin file-writer around lib/render-core.mjs / lib/backlog-core.mjs (the pure renderers).
+// Usage:
+//   node render.mjs [--in docs/roadmap/roadmap.yaml] [--out docs/SLICES.md] [--cap N] [--stdout]
+// Default: in=docs/roadmap/roadmap.yaml, out=docs/SLICES.md. --stdout prints SLICES only.
+
+import { writeFileSync } from "node:fs";
+import { loadGraph } from "./lib/graph.mjs";
+import { renderMarkdown } from "./lib/render-core.mjs";
+import { loadBacklog, slicesRenderOpts, backlogPaths } from "./lib/store.mjs";
+import { renderBacklogMarkdown } from "./lib/backlog-core.mjs";
+
+const args = process.argv.slice(2);
+function flag(name, def) {
+  const i = args.indexOf(name);
+  return i >= 0 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : def;
+}
+const inPath = flag("--in", "docs/roadmap/roadmap.yaml");
+const outPath = flag("--out", "docs/SLICES.md");
+const toStdout = args.includes("--stdout");
+const cap = args.includes("--cap") ? Number(flag("--cap")) : undefined;
+
+const graph = loadGraph(inPath);
+const backlog = loadBacklog(process.cwd());
+const out = renderMarkdown(graph, { cap, ...slicesRenderOpts(process.cwd(), backlog) });
+
+if (toStdout) {
+  process.stdout.write(out);
+} else {
+  writeFileSync(outPath, out, "utf8");
+  const sprintCount = (graph.pis || []).reduce((a, p) => a + ((p.sprints || []).length), 0);
+  console.error(`✓ rendered ${outPath} (${(graph.pis || []).length} PIs, ${sprintCount} sprints)`);
+  if (backlog) {
+    const mdPath = backlogPaths(process.cwd()).md;
+    writeFileSync(mdPath, renderBacklogMarkdown(backlog), "utf8");
+    console.error(`✓ rendered docs/BACKLOG.md (${(backlog.items || []).length} items)`);
+  }
+}

package/scripts/review.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// roadmap review [--since <rev|date>] [--json] — the date-anchored review digest: what
+// shipped vs what grew since the last human review. The anchor chain: meta.last_review.commit
+// → --since (a YYYY-MM-DD resolves to the last commit before that date; anything else is a
+// git rev) → the last commit before a default 14-day window. Old YAML snapshots come from
+// `git show <commit>:docs/roadmap/roadmap.yaml` (forward slashes — git pathspecs, not OS paths).
+// Read-only; /debrief and /retro consume --json.
+
+import { spawnSync } from "node:child_process";
+import YAML from "yaml";
+import { loadGraph } from "./lib/graph.mjs";
+import { loadBacklog } from "./lib/store.mjs";
+import { graphDiff, backlogDiff, reviewDigest } from "./lib/review-core.mjs";
+
+const args = process.argv.slice(2);
+const val = (n) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : undefined; };
+const git = (...a) => spawnSync("git", a, { encoding: "utf8" });
+
+function resolveAnchor(graph) {
+  const lr = graph.meta && graph.meta.last_review;
+  const since = val("--since");
+  if (!since && lr && lr.commit) return { commit: lr.commit, date: lr.date || null, source: "meta.last_review" };
+  if (since) {
+    if (/^\d{4}-\d{2}-\d{2}$/.test(since)) {
+      const sha = git("rev-list", "-1", `--before=${since}`, "HEAD").stdout.trim();
+      return sha ? { commit: sha, date: since, source: "--since date" } : null;
+    }
+    return { commit: since, date: null, source: "--since rev" };
+  }
+  const d = new Date(Date.now() - 14 * 86400e3).toISOString().slice(0, 10);
+  const sha = git("rev-list", "-1", `--before=${d}`, "HEAD").stdout.trim();
+  return sha ? { commit: sha, date: d, source: "default 14-day window" } : null;
+}
+
+function yamlAt(commit, rel) {
+  const r = git("show", `${commit}:${rel}`);
+  return r.status === 0 ? YAML.parse(r.stdout) : null;   // file didn't exist at that rev
+}
+
+const graph = loadGraph("docs/roadmap/roadmap.yaml");
+const backlog = loadBacklog(process.cwd());
+const anchor = resolveAnchor(graph);
+let note = null;
+let oldGraph = { meta: {}, pis: [] };
+let oldBacklog = null;
+if (!anchor) {
+  note = "no anchor commit found (young repo?) — diffing against an empty roadmap";
+} else {
+  oldGraph = yamlAt(anchor.commit, "docs/roadmap/roadmap.yaml") || { meta: {}, pis: [] };
+  oldBacklog = yamlAt(anchor.commit, "docs/roadmap/backlog.yaml");
+}
+
+let digest;
+try {
+  digest = reviewDigest({ gd: graphDiff(oldGraph, graph), bd: backlogDiff(oldBacklog, backlog), graph });
+} catch (e) {
+  console.error(`✗ ${e.message}${anchor ? ` (old snapshot at ${anchor.commit})` : ""}`);
+  process.exit(1);
+}
+
+if (args.includes("--json")) {
+  process.stdout.write(JSON.stringify({ anchor, note, digest }, null, 2) + "\n");
+  process.exit(0);
+}
+
+// ── human digest ───────────────────────────────────────────────────────────────
+const short = (sha) => String(sha).slice(0, 8);
+const out = [];
+out.push(anchor
+  ? `review window: ${short(anchor.commit)}${anchor.date ? ` (${anchor.date})` : ""} → HEAD   [${anchor.source}]`
+  : `review window: (${note})`);
+out.push(`shipped (${digest.shipped.length}): ${digest.shipped.map((s) => `${s.invoke}${s.prs && s.prs.length ? ` (${s.prs.join(" ")})` : ""}`).join(", ") || "—"}`);
+out.push(`captured (${digest.netGrowth.added}): ${digest.captured.items.length} backlog item(s), ${digest.captured.sprints.length} sprint(s)`);
+out.push(`net growth: +${digest.netGrowth.added} / -${digest.shipped.length + digest.closedItems.length} (ratio ${digest.netGrowth.ratio})`);
+if (digest.aging.length) out.push(`held since before last review: ${digest.aging.map((a) => `${a.invoke} (${a.status})`).join(", ")}`);
+if (digest.newPis.length) out.push(`new PIs: ${digest.newPis.map((p) => p.id).join(", ")}`);
+if (digest.pisInFlight > 1) out.push(`PIs in flight: ${digest.pisInFlight}`);
+for (const w of digest.sprawl) out.push(w);
+console.log(out.join("\n"));