@connorbritain/roadmap 0.3.0

package/scripts/lib/backlog-core.mjs

@@ -0,0 +1,318 @@
+// roadmap — backlog brain (PURE). The erratic-work tracker beside the roadmap: validation,
+// yaml-Document mutations (comment-preserving, mirroring mcp-core), the BACKLOG.md renderer,
+// the item→node adapter that lets `grab` reuse the fanout brief machinery, and pickNext —
+// the highest-priority ready thing across roadmap AND backlog. No IO.
+
+import { flatten, readyNodes } from "./graph.mjs";
+import { comparePriority, tierBadge, validatePriority, TIERS } from "./priority.mjs";
+import { addSprint } from "./mcp-core.mjs";
+
+export const KINDS = ["bug", "chore", "followup", "urgent", "idea"];
+export const ITEM_STATUSES = ["open", "in_progress", "promoted", "done", "dropped"];
+const OPEN = new Set(["open", "in_progress"]);
+const SLUG = /^[a-z0-9][a-z0-9-]*$/;
+
+// Fields a caller may set on an item via backlog_set (id is structural, set only at add).
+const ITEM_SETTABLE = new Set([
+  "title", "kind", "status", "priority", "source", "refs", "touches",
+  "est_sessions", "gate", "prompt", "prs", "completed_on", "promoted_to", "linear", "dispatch_tier",
+]);
+
+// ── validation (plain object) ───────────────────────────────────────────────
+export function validateBacklog(backlog) {
+  const errors = [];
+  const warnings = [];
+  const meta = (backlog && backlog.meta) || {};
+  if (meta.schema_version !== 1) errors.push(`backlog meta.schema_version must be 1 (got ${JSON.stringify(meta.schema_version)})`);
+  const items = (backlog && backlog.items) || [];
+  const seen = new Set();
+  for (const it of items) {
+    const where = `backlog/${it.id || "?"}`;
+    if (!it.id || !SLUG.test(it.id)) errors.push(`${where}: id required (lowercase slug)`);
+    else if (seen.has(it.id)) errors.push(`duplicate backlog id "${it.id}"`);
+    seen.add(it.id);
+    if (!it.title) errors.push(`${where}: title required`);
+    if (!KINDS.includes(it.kind)) errors.push(`${where}: kind "${it.kind}" is not one of ${KINDS.join("|")}`);
+    if (!ITEM_STATUSES.includes(it.status)) errors.push(`${where}: status "${it.status}" is not one of ${ITEM_STATUSES.join("|")}`);
+    for (const e of validatePriority(it.priority, where).errors) errors.push(e);
+    if (it.est_sessions != null && (typeof it.est_sessions !== "number" || it.est_sessions < 0)) {
+      errors.push(`${where}: est_sessions must be a number >= 0`);
+    }
+    if (it.status === "promoted" && !it.promoted_to) warnings.push(`${where}: promoted but promoted_to is unset (no back-link)`);
+  }
+  return { errors, warnings, itemCount: items.length };
+}
+
+// ── Document helpers + mutations (yaml AST; mirror mcp-core's style) ─────────
+function itemsSeq(doc) {
+  const s = doc.get("items");
+  if (!s || !s.items) throw new Error("backlog has no items sequence");
+  return s;
+}
+function itemLocById(doc, id) {
+  const items = itemsSeq(doc).items;
+  for (let i = 0; i < items.length; i++) if (String(items[i].get("id")) === id) return i;
+  return -1;
+}
+
+// Next free auto-id b1..bN. Scans the local doc AND any caller-supplied id list — the IO
+// layers pass origin/main's ids (store.originBacklogIds) so concurrent sessions allocating
+// against stale checkouts stop minting the same bNN (five live collisions on 2026-07-10).
+// Custom slugs don't collide with the counter.
+function nextAutoId(doc, alsoIds = []) {
+  let max = 0;
+  const bump = (id) => { const m = /^b(\d+)$/.exec(String(id)); if (m) max = Math.max(max, Number(m[1])); };
+  for (const it of itemsSeq(doc).items) bump(it.get("id"));
+  for (const id of alsoIds) bump(id);
+  return `b${max + 1}`;
+}
+
+export function addItem(doc, args) {
+  if (!args || !args.title) throw new Error("backlog_add requires title");
+  const originIds = args.origin_ids || [];
+  const id = args.id || nextAutoId(doc, originIds);
+  if (itemLocById(doc, id) >= 0) throw new Error(`backlog item "${id}" already exists`);
+  // An explicit id that origin/main already holds is the OTHER half of the id race — the
+  // local file hasn't pulled it yet, so the local-duplicate check above can't see it.
+  if (args.id && originIds.includes(String(args.id))) {
+    throw new Error(`backlog item "${args.id}" already exists on origin/main — pull/rebase first, or choose another id`);
+  }
+  const node = { id, title: args.title, kind: args.kind || "chore", status: args.status || "open" };
+  for (const k of ["priority", "source", "refs", "touches", "est_sessions", "gate", "prompt", "linear", "dispatch_tier"]) {
+    if (args[k] != null) node[k] = args[k];
+  }
+  // createNode: addIn stores a plain object un-wrapped, which breaks later AST reads (.get)
+  // on the same Document (e.g. a second add in one mutation batch).
+  doc.addIn(["items"], doc.createNode(node));
+  return { added: id };
+}
+
+export function setItemFields(doc, args) {
+  if (!args || !args.id || !args.fields) throw new Error("backlog_set requires id + fields");
+  const i = itemLocById(doc, args.id);
+  if (i < 0) throw new Error(`no backlog item "${args.id}"`);
+  const changed = [];
+  for (const [k, v] of Object.entries(args.fields)) {
+    if (!ITEM_SETTABLE.has(k)) throw new Error(`field "${k}" is not settable on a backlog item`);
+    if (v === null) doc.deleteIn(["items", i, k]);
+    else doc.setIn(["items", i, k], v);
+    changed.push(k);
+  }
+  return { updated: args.id, fields: changed };
+}
+
+// Pre-write gate: throws if the edited Document would corrupt the backlog; returns the
+// plain backlog on success so the caller hands it straight to renderBacklogMarkdown.
+export function validateBacklogDocOrThrow(doc) {
+  const backlog = doc.toJS();
+  const { errors } = validateBacklog(backlog);
+  if (errors.length) throw new Error(`edit would corrupt the backlog: ${errors[0]}`);
+  return backlog;
+}
+
+// ── ordering + counts ────────────────────────────────────────────────────────
+// Stable priority sort (JS sort is stable: equal priorities keep capture order).
+export function sortByPriority(items) {
+  return [...items].sort((a, b) => comparePriority(a.priority, b.priority));
+}
+export function openItems(backlog) {
+  return ((backlog && backlog.items) || []).filter((it) => OPEN.has(it.status));
+}
+export function openCount(backlog) {
+  return openItems(backlog).length;
+}
+
+// ── BACKLOG.md renderer (pure: backlog -> markdown) ──────────────────────────
+export function renderBacklogMarkdown(backlog) {
+  const items = (backlog && backlog.items) || [];
+  const lines = [];
+  const w = (s = "") => lines.push(s);
+  const B = "`";
+
+  w("<!-- GENERATED from docs/roadmap/backlog.yaml (roadmap backlog / the backlog_* MCP tools). Do not edit this file directly — edit the YAML and re-render. -->");
+  w("# Backlog — the erratic-work tracker");
+  w("");
+  w(`> ${openCount(backlog)} open item(s). Roadmap = planned feature/value work; backlog = the follow-up, trivial, or urgent work that surfaces erratically. Capture with ${B}/backlog${B} or ${B}roadmap backlog add${B}; launch a small item directly with ${B}roadmap grab <id>${B}; promote a bigger one into the roadmap with ${B}roadmap promote <id> --pi <pi>${B}.`);
+  w("");
+
+  const open = sortByPriority(items.filter((it) => it.status === "open"));
+  const tierOf = (it) => tierBadge(it.priority) || "Untriaged";
+  for (const tier of [...TIERS, "Untriaged"]) {
+    const group = open.filter((it) => tierOf(it) === tier);
+    if (!group.length) continue;
+    w(`## ${tier}`);
+    w("");
+    table(group);
+  }
+  if (!open.length) {
+    w("_No open items._");
+    w("");
+  }
+
+  const inProgress = sortByPriority(items.filter((it) => it.status === "in_progress"));
+  if (inProgress.length) {
+    w("## In progress");
+    w("");
+    table(inProgress);
+  }
+  const promoted = items.filter((it) => it.status === "promoted");
+  if (promoted.length) {
+    w("## Promoted to the roadmap");
+    w("");
+    w("| Id | Title | Now at |");
+    w("|---|---|---|");
+    for (const it of promoted) w(`| ${B}${it.id}${B} | ${esc(it.title)} | ${it.promoted_to ? B + it.promoted_to + B : "—"} |`);
+    w("");
+  }
+  const closed = items.filter((it) => it.status === "done" || it.status === "dropped");
+  if (closed.length) {
+    w("## Recently closed");
+    w("");
+    w("| Id | Title | Status | PRs | Closed |");
+    w("|---|---|---|---|---|");
+    for (const it of closed) w(`| ${B}${it.id}${B} | ${esc(it.title)} | ${it.status} | ${(it.prs || []).join(" ") || "—"} | ${it.completed_on || "—"} |`);
+    w("");
+  }
+  return lines.join("\n") + "\n";
+
+  function table(group) {
+    w("| Id | Kind | Wt | Title | Est | Source | Refs |");
+    w("|---|---|---|---|---|---|---|");
+    for (const it of group) {
+      const wt = it.priority && it.priority.weight != null ? it.priority.weight : "—";
+      const reason = it.priority && it.priority.reason ? ` _(${esc(it.priority.reason)})_` : "";
+      const src = it.source ? [it.source.slice && B + it.source.slice + B, it.source.date].filter(Boolean).join(" ") : "—";
+      const refs = (it.refs || []).map((r) => B + r + B).join(", ") || "—";
+      w(`| ${B}${it.id}${B} | ${it.kind} | ${wt} | ${esc(it.title)}${reason} | ${it.est_sessions != null ? "~" + it.est_sessions : "?"} | ${src || "—"} | ${refs} |`);
+    }
+    w("");
+  }
+  function esc(s) {
+    return String(s).replace(/\|/g, "\\|").replace(/\s*\n\s*/g, " ");
+  }
+}
+
+// ── item → node adapter ──────────────────────────────────────────────────────
+// Shapes a backlog item like a flattened sprint node so brief.mjs (branchFor / worktreeFor /
+// synthesizeBrief / launchPrompt) works unchanged: branch backlog/<id>, worktree <root>/backlog-<id>.
+// ponytail: collides only if a real PI is literally named "backlog" AND has a sprint id == item id.
+export function backlogItemToNode(item) {
+  return {
+    nodeKey: `backlog/${item.id}`,
+    piId: "backlog",
+    piTitle: "Backlog",
+    programLabel: "BACKLOG",
+    id: item.id,
+    invoke: item.id,
+    title: item.title,
+    status: item.status === "in_progress" ? "active" : "next",
+    statusLabel: null,
+    what: item.title,
+    estSessions: typeof item.est_sessions === "number" ? item.est_sessions : null,
+    deps: [], piDeps: [], rawDeps: [],
+    touches: item.touches || [],
+    owns: [],
+    gate: item.gate || "default",
+    gatedOn: null,
+    optional: false,
+    execution: null,
+    track: null,
+    priority: item.priority || null,
+    prompt: item.prompt || null,
+    readOrder: [],
+    resumeAction: (item.source && item.source.note) || "",
+    kickoffBrief: "brief",
+    prs: item.prs || [],
+    completedOn: item.completed_on || null,
+  };
+}
+
+// ── pickNext: the single highest-priority ready thing across both trackers ───
+// Roadmap wins full ties (planned value work outranks erratic work at equal priority).
+// backlog may be null (no backlog.yaml). Returns { type: "slice"|"backlog", node|item } or null.
+export function pickNext(graph, backlog) {
+  const ready = readyNodes(flatten(graph));
+  const topSlice = ready.length
+    ? [...ready].sort((a, b) => {
+        const pc = comparePriority(a.priority, b.priority);
+        if (pc) return pc;
+        return a.invoke.localeCompare(b.invoke);
+      })[0]
+    : null;
+  const open = backlog ? sortByPriority(((backlog.items) || []).filter((it) => it.status === "open")) : [];
+  const topItem = open[0] || null;
+  if (!topSlice && !topItem) return null;
+  if (!topItem) return { type: "slice", node: topSlice };
+  if (!topSlice) return { type: "backlog", item: topItem };
+  return comparePriority(topItem.priority, topSlice.priority) < 0
+    ? { type: "backlog", item: topItem }
+    : { type: "slice", node: topSlice };
+}
+
+// ── promote: backlog item → roadmap sprint (both Documents, caller writes) ───
+// The item's id becomes the sprint's invoke key (a collision with an existing invoke is
+// rejected by the roadmap's pre-write gate). The caller (store.mutateBoth) validates BOTH
+// documents before writing either.
+export function performPromotion(rDoc, bDoc, { id, pi, sprint_id } = {}) {
+  if (!id || !pi) throw new Error("promote requires a backlog id and a --pi target");
+  const item = ((bDoc.toJS().items) || []).find((it) => it.id === id);
+  if (!item) throw new Error(`no backlog item "${id}"`);
+  if (item.status !== "open" && item.status !== "in_progress") {
+    throw new Error(`backlog item "${id}" is ${item.status} — only open/in_progress items promote`);
+  }
+  const piObj = ((rDoc.toJS().pis) || []).find((p) => p.id === pi);
+  if (!piObj) throw new Error(`no PI "${pi}"`);
+  let sid = sprint_id;
+  if (!sid) {
+    let max = 0;
+    for (const s of piObj.sprints || []) {
+      const m = /^s(\d+)$/.exec(String(s.id));
+      if (m) max = Math.max(max, Number(m[1]));
+    }
+    sid = `s${max + 1}`;
+  }
+  const args = { pi, id: sid, title: item.title, invoke: item.id, status: "scheduled", what: item.title };
+  for (const k of ["est_sessions", "gate", "prompt", "priority"]) if (item[k] != null) args[k] = item[k];
+  if (Array.isArray(item.touches) && item.touches.length) args.touches = item.touches;
+  // The item's Linear issue TRANSFERS to the sprint (same issue continues life as roadmap
+  // work — next sync morphs its description/labels/project). Leaving it on the item would
+  // orphan an open issue on the board and double-map the identifier.
+  if (item.linear) args.linear = item.linear;
+  addSprint(rDoc, args);
+  setItemFields(bDoc, { id, fields: { status: "promoted", promoted_to: `${pi}/${sid}`, ...(item.linear ? { linear: null } : {}) } });
+  return { promoted: id, to: `${pi}/${sid}` };
+}
+
+// ── MCP tool registry (spread into TOOLS by mcp.mjs) ─────────────────────────
+const PRIORITY_SCHEMA = { type: "object", properties: {
+  tier: { enum: ["P0", "P1", "P2", "P3"] }, weight: { type: "number", minimum: 0, maximum: 100 }, reason: { type: "string" } } };
+
+export const BACKLOG_TOOLS = [
+  { name: "backlog_list", description: "Backlog items, priority-sorted. Read-only. all=true includes promoted/done/dropped.",
+    inputSchema: { type: "object", properties: { all: { type: "boolean" } } } },
+  { name: "backlog_add", description: "Add a backlog item (erratic/follow-up/urgent work). Creates docs/roadmap/backlog.yaml on first use; re-renders BACKLOG.md. id auto-assigned (b1..bN) when omitted.",
+    inputSchema: { type: "object", required: ["title"], properties: {
+      title: { type: "string" }, id: { type: "string" }, kind: { enum: KINDS },
+      priority: PRIORITY_SCHEMA,
+      source: { type: "object", properties: { slice: { type: "string" }, date: { type: "string" }, note: { type: "string" },
+        linear: { type: "object", properties: { team: { type: "string" }, project: { type: "string" }, issue: { type: "string" } } } } },
+      refs: { type: "array", items: { type: "string" } }, touches: { type: "array", items: { type: "string" } },
+      est_sessions: { type: "number" }, gate: { type: "string" }, prompt: { type: "string" }, linear: { type: "string" },
+      dispatch_tier: { type: "string" },
+      origin_ids: { type: "array", items: { type: "string" }, description: "ids already taken upstream (the MCP server injects origin/main's ids automatically; callers normally omit this)" } } } },
+  { name: "backlog_set", description: "Set allowed fields on a backlog item (by id). null value deletes a field. Re-renders BACKLOG.md.",
+    inputSchema: { type: "object", required: ["id", "fields"], properties: {
+      id: { type: "string" }, fields: { type: "object" } } } },
+  { name: "backlog_promote", description: "Promote a backlog item into a roadmap sprint (item id becomes the invoke key; carries title/est/gate/touches/prompt/priority; back-links promoted_to). Both YAMLs validated before either is written; re-renders both generated views.",
+    inputSchema: { type: "object", required: ["id", "pi"], properties: {
+      id: { type: "string" }, pi: { type: "string" }, sprint_id: { type: "string" } } } },
+];
+
+export function readBacklogList(backlog, args = {}) {
+  if (!backlog) return { items: [], note: "no docs/roadmap/backlog.yaml yet — backlog_add creates it" };
+  const items = args.all ? backlog.items || [] : openItems(backlog);
+  return { items: sortByPriority(items), open: openCount(backlog) };
+}
+
+export const BACKLOG_READ_HANDLERS = { backlog_list: readBacklogList };
+export const BACKLOG_MUTATION_HANDLERS = { backlog_add: addItem, backlog_set: setItemFields };

package/scripts/lib/brief.mjs

@@ -0,0 +1,123 @@
+// roadmap — kickoff-brief synthesizer.
+// Turns a sprint node into the self-contained brief a launched session reads to
+// "just start". Mirrors the 6-part subagent-handoff contract (target/scope, reference,
+// gate+commands, branch/commit/PR, DO NOT MERGE, report-back) so an autonomous or
+// watched session owns its atomic sequence and never merges its own work.
+
+import { resolveGate } from "./graph.mjs";
+import { executionDirectiveLines } from "./execution.mjs";
+import { resolve } from "node:path";
+
+// Repo conventions (default to git's common defaults; overridable in meta).
+export const remoteOf = (graph) => (graph.meta && graph.meta.remote) || "origin";
+export const baseBranchOf = (graph) => (graph.meta && graph.meta.base_branch) || "main";
+export const baseRefOf = (graph) => `${remoteOf(graph)}/${baseBranchOf(graph)}`;
+
+export function branchFor(node, graph) {
+  const conv = (graph.meta && graph.meta.branch_convention) || "{pi}/{sprint}";
+  let br = conv.replace("{pi}", node.piId).replace("{sprint}", node.id);
+  // {linear} = the node's Linear issue identifier, lowercased — a branch containing it is
+  // auto-linked to the issue by Linear. Cleanup runs ONLY when the token was used, so
+  // conventions without it stay byte-identical; a node without an id degrades gracefully
+  // ({pi}/{linear}-{sprint} -> platform/s1, no "/-" or "--" residue).
+  if (conv.includes("{linear}")) {
+    br = br.replace("{linear}", String(node.linear || "").toLowerCase())
+      .replace(/--+/g, "-").replace(/\/-/g, "/").replace(/-+$/, "");
+  }
+  return br;
+}
+
+// Launch-command template for INTERACTIVE worker/lead sessions. meta.agent_cmd swaps the
+// agent (e.g. a codex invocation) — {mode} = permission mode, {prompt} = the prompt wrapped
+// in the call site's quote char (each shell context picks its own). The default template
+// produces today's claude command byte-for-byte.
+// ponytail: interactive-only lever; autonomous headless launches stay hardcoded to claude —
+// add a second template when someone actually runs a non-claude headless agent.
+export const DEFAULT_AGENT_CMD = "claude --permission-mode {mode} {prompt}";
+export function agentCmdFor(graph, { prompt, mode, quote = '"' }) {
+  const tpl = (graph.meta && graph.meta.agent_cmd) || DEFAULT_AGENT_CMD;
+  return tpl.replace("{mode}", mode).replace("{prompt}", `${quote}${prompt}${quote}`);
+}
+
+export function worktreeFor(node, graph) {
+  // Default to an absolute sibling of the repo (<cwd>/../_worktrees) when unset — the CLI
+  // runs with cwd = repo root, so this is portable + machine-specific-free in the committed YAML.
+  const root = (graph.meta && graph.meta.worktree_root) || resolve(process.cwd(), "..", "_worktrees");
+  return `${root}/${node.piId}-${node.id}`;
+}
+
+// The prompt each launched session starts with. SELF-CONTAINED: it reads the kickoff brief
+// written into the worktree, so it works whether or not the roadmap plugin/skill is
+// installed in the spawned session. ASCII + no quote chars (it's embedded in shell quotes).
+export function launchPrompt(node) {
+  // Steers to research -> plan -> WAIT -> implement. Combined with a permissive --worker-mode
+  // (acceptEdits / bypassPermissions) the research runs without approval prompts, but the agent
+  // still pauses for you to approve the plan before it changes anything. No ';' (wt's delimiter).
+  return `Read the .kickoff.md file in this directory. First research autonomously - read the brief read-order and explore the code, without asking - to build a thorough plan. Then present the plan and STOP: wait for my approval before you implement anything. After I approve, carry it out - build, test, commit, push, open a PR. Do NOT merge.`;
+}
+
+// The full brief written to <worktree>/.kickoff.md (uncommitted).
+export function synthesizeBrief(node, graph) {
+  if (node.kickoffBrief && node.kickoffBrief !== "brief") {
+    // inline brief or a path — pass through (caller resolves a path if needed)
+    return node.kickoffBrief;
+  }
+  const gate = resolveGate(node, graph) || "(see SLICES.md default gate)";
+  const branch = branchFor(node, graph);
+  const owns = [...(node.owns || []), ...(node.touches || [])];
+  const ro = (node.readOrder || []).map((r, i) => `${i + 1}. ${r}`).join("\n") || "_(see the slice's detail entry in docs/SLICES.md)_";
+
+  // Carry the imperative execution directive VERBATIM (only when the slice declares one), so the
+  // launched session staffs at the declared topology — an agent-team slice invokes Agent Teams
+  // rather than running solo. Section 0 = the very first thing the session reads.
+  const execLines = executionDirectiveLines(node);
+  const execSection = execLines
+    ? `## 0. Execution strategy — staff this BEFORE you start
+${execLines.join("\n")}
+
+`
+    : "";
+
+  // Author-stashed pickup instructions, carried VERBATIM (only when the slice declares one —
+  // a slice without a prompt gets a byte-identical brief).
+  const promptSection = node.prompt
+    ? `## 0.5 Author instructions (verbatim)
+${String(node.prompt).trimEnd()}
+
+`
+    : "";
+
+  return `# Kickoff — ${node.invoke}  (${node.programLabel} · ${node.id.toUpperCase()})
+
+> Uncommitted brief for this fanout session. You own the atomic sequence
+> **read → plan → build → test → commit → push → open PR**. Do **NOT** merge — the lead merges.
+
+**Slice:** \`${node.invoke}\`  ·  **Branch:** \`${branch}\`
+**What:** ${node.what || node.title}
+
+**Resuming?** \`roadmap linear notes ${node.invoke}\` shows any prior-session notes on this slice's tracker issue — read them first if present (that's where a dead session left off).
+
+${execSection}${promptSection}## 1. Scope / target
+${owns.length ? owns.map((f) => `- \`${f}\``).join("\n") : "- (scope to this slice only; see read-order)"}
+
+## 2. Read-order (orient first — paths are relative to \`docs/\`; you're at the repo root, so e.g. \`sprints/...\` = \`docs/sprints/...\`, and \`../STATUS.md\` = \`STATUS.md\`)
+${ro}
+
+## 3. Next action
+${node.resumeAction || "(see the slice detail entry)"}
+
+## 4. Verification gate (must pass before commit)
+\`\`\`
+${gate}
+\`\`\`
+
+## 5. Commit + PR
+- Commit style: \`<area>: <what> (${node.piId}-${node.id.toUpperCase()})\`, professional, no AI attribution.
+- Open a PR \`--base ${baseBranchOf(graph)} --head ${branch}\` whose description includes the exact line \`roadmap: slice=${node.invoke}\` (the reconcile marker). **Do NOT merge.**
+
+## 6. Report back
+LOC delta · file inventory · gate result (pass/fail with output) · commit SHA · PR # · 2–3 line retro.
+Journal as you go: at each checkpoint — a gate cleared, a blocker hit, a logical unit done — post \`roadmap linear note ${node.invoke} "…" [--kind progress|blocker|done]\` (a no-op if this slice isn't tracker-mapped), so if this session dies the next one resumes from the trail, not from zero.
+Leftovers: before opening the PR, file anything that genuinely blocks or follows this slice (discovered bugs, broken contracts, deferred gate items) to the BACKLOG ONLY — the \`backlog_add\` MCP tool if available, else \`roadmap backlog add "<title>" -k followup --slice ${node.invoke}\`, else a **Leftovers** heading in the PR body (the lead's /sync harvests it). NEVER add sprints or PIs from this session — scope decisions belong to the human. Skip speculative ideas entirely (YAGNI applies to captures too).
+`;
+}

package/scripts/lib/cli-core.mjs

@@ -0,0 +1,97 @@
+// roadmap CLI — pure core (no side effects on import, so it's unit-testable).
+// cli.mjs wires these to process.argv / spawn / process.exit.
+
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+export const REL = ["docs", "roadmap", "roadmap.yaml"];
+const MAP = { plan: "scheduler.mjs", render: "render.mjs", fan: "fanout.mjs", fanout: "fanout.mjs", validate: "validate.mjs", show: "show.mjs", cleanup: "cleanup.mjs", wizard: "wizard.mjs", go: "wizard.mjs", mcp: "mcp.mjs", watch: "watch-prs.mjs", set: "set.mjs", backlog: "backlog.mjs", grab: "grab.mjs", promote: "promote.mjs", next: "next.mjs", linear: "linear.mjs", review: "review.mjs", dispatch: "dispatch.mjs", plate: "plate.mjs", estimate: "estimate.mjs", cycle: "cycle.mjs", init: "init.mjs", assistant: "assistant.mjs" };
+const NOT_YET = { sync: "P4" };
+
+// Walk up from `start` to the first dir containing docs/roadmap/roadmap.yaml; null if none.
+// `exists` is injectable for testing.
+export function findRepoRoot(start, exists = existsSync) {
+  let dir = resolve(start);
+  for (;;) {
+    if (exists(join(dir, ...REL))) return dir;
+    const up = dirname(dir);
+    if (up === dir) return null;
+    dir = up;
+  }
+}
+
+// Parse argv (already sliced past node + script) into { cmd, rest }.
+// Bare → plan; a leading flag → plan with those flags; -h/--help → help.
+export function route(argv) {
+  if (argv.length === 0) return { cmd: "plan", rest: [] };
+  if (argv[0].startsWith("-")) {
+    if (argv[0] === "-h" || argv[0] === "--help") return { cmd: "help", rest: [] };
+    return { cmd: "plan", rest: argv };
+  }
+  return { cmd: argv[0], rest: argv.slice(1) };
+}
+
+// Classify a command into an action the wrapper acts on.
+export function classify(cmd) {
+  if (cmd === "help") return { kind: "help" };
+  if (NOT_YET[cmd]) return { kind: "notyet", phase: NOT_YET[cmd] };
+  if (MAP[cmd]) return { kind: "run", script: MAP[cmd] };
+  return { kind: "unknown" };
+}
+
+// validate.mjs takes a positional path; the others take relative defaults from repo root.
+export function buildArgs(cmd, rest, relPath = join(...REL)) {
+  if (cmd === "validate" && !rest.some((a) => !a.startsWith("-"))) return [relPath, ...rest];
+  return rest;
+}
+
+// Split `field=value` CLI assignments (roadmap set / backlog set). Splits on the FIRST '='
+// (values may contain '='). `@path` marks read-value-from-file (multiline prompts/briefs);
+// everything else is YAML-parsed by the caller, so `null` deletes per set_fields semantics.
+export function parseAssignments(args) {
+  return args.map((a) => {
+    const i = a.indexOf("=");
+    if (i <= 0) throw new Error(`expected field=value, got "${a}"`);
+    const field = a.slice(0, i), raw = a.slice(i + 1);
+    return raw.startsWith("@") ? { field, fromFile: raw.slice(1) } : { field, raw };
+  });
+}
+
+// Single-letter flag aliases, expanded to their long form before the target script sees them.
+const SHORT = {
+  "-w": "--wave", "-c": "--cap", "-t": "--term", "-o": "--out", "-i": "--in",
+  "-d": "--dry", "-j": "--json", "-a": "--autonomous", "-y": "--yes-spawn-autonomous",
+  "-f": "--force", "-s": "--stdout", "-l": "--lane", "-r": "--remove",
+  "-lc": "--lead-claude", "-wm": "--worker-mode",
+};
+export function expandShort(args) {
+  return args.map((a) => SHORT[a] || a);
+}
+
+// Friendly guidance when no roadmap.yaml is found — say WHERE it goes + how to start one,
+// instead of a terse error. Shown for any command (incl. bare `roadmap`).
+export function missingRoadmapHelp(cwd) {
+  const rel = REL.join("/");
+  return [
+    `roadmap: couldn't find ${rel} at or above`,
+    `  ${cwd}`,
+    ``,
+    `The CLI walks UP from your current directory looking for the roadmap graph,`,
+    `so run it from anywhere inside a repo whose root has:`,
+    `  <repo-root>/${rel}`,
+    ``,
+    `Don't have one yet? A minimal starter:`,
+    `  meta:`,
+    `    schema_version: 1`,
+    `    program: MYPROJ`,
+    `  pis:`,
+    `    - id: first`,
+    `      title: First initiative`,
+    `      status: active`,
+    `      sprints:`,
+    `        - { id: s1, title: First sprint, status: next, invoke: first-s1, est_sessions: 1 }`,
+    ``,
+    `Save that to ${rel}, then 'roadmap validate' and 'roadmap render'.`,
+    `Run 'roadmap init' from the repo root for a safe bootstrap preview.`,
+  ].join("\n");
+}

package/scripts/lib/cycle-core.mjs

@@ -0,0 +1,58 @@
+// roadmap — cycle election brain (PURE). The weekly lock: what's committed (active/next),
+// what's electable (ready scheduled work), what fits the capacity, and what's out of the
+// cycle (the dispatch guard's question). No IO — cycle.mjs (CLI) and dispatch.mjs consume
+// this; linear-core.mjs owns CYCLE_STATUSES (the committed set IS the cycle's semantic).
+
+import { flatten, readyNodes, isDone } from "./graph.mjs";
+import { comparePriority } from "./priority.mjs";
+import { CYCLE_STATUSES } from "./linear-core.mjs";
+
+// The dispatch/fan lock: with cycles on, work outside the committed set doesn't launch
+// without an explicit override. Null/absent cfg or cycles off → never locks (opt-in).
+export function outOfCycle(cfg, status) {
+  return !!cfg && cfg.cycles === "on" && !CYCLE_STATUSES.includes(status);
+}
+
+const summarize = (stale) => (n) => ({
+  invoke: n.invoke, title: n.title, status: n.status, pi: n.piId,
+  est: typeof n.estSessions === "number" ? n.estSessions : null,
+  priority: n.priority || null,
+  stale: stale.has(n.invoke),
+});
+
+// The election picture. elected = the current committed set (active/next) with the stale set
+// marked — the ritual reviews those FIRST. candidates = ready (deps satisfied, not held)
+// scheduled slices, priority-sorted then smallest-first; optionality is hand-promotable, never
+// auto-proposed. packed = the greedy candidate PREFIX that fits capacity on top of what's
+// already committed — priority order is honored strictly (no skip-ahead knapsack: a big P0
+// blocking the prefix is a signal to split it, not to sneak P2s past it). Slices with no
+// est_sessions are never silently packed (the honesty gate, mirroring the timeline rollup's
+// unpriced rule) — they land in `unestimated` for the human to price or pass on.
+export function electionPlan(graph, { capacity = 10, staleInvokes = [] } = {}) {
+  const model = flatten(graph);
+  const stale = new Set(staleInvokes);
+  const brief = summarize(stale);
+
+  const elected = model.nodes.filter((n) => !isDone(n.status) && CYCLE_STATUSES.includes(n.status)).map(brief);
+  // Elected-but-unpriced work can't hide from the capacity math as a silent zero — it's
+  // surfaced beside the candidate-side honesty gate so the ritual prices it or calls it out.
+  const unpricedElected = elected.filter((x) => x.est == null);
+  let used = elected.reduce((s, x) => s + (x.est || 0), 0);
+
+  const candidates = readyNodes(model)
+    .filter((n) => n.status === "scheduled")
+    .sort((a, b) => comparePriority(a.priority, b.priority) || (a.estSessions ?? Infinity) - (b.estSessions ?? Infinity))
+    .map(brief);
+  const unestimated = candidates.filter((c) => c.est == null);
+  const estimable = candidates.filter((c) => c.est != null);
+
+  const packed = [];
+  for (const c of estimable) {
+    if (used + c.est > capacity) break;
+    packed.push(c);
+    used += c.est;
+  }
+  const overflow = estimable.slice(packed.length);
+
+  return { elected, unpricedElected, candidates, packed, overflow, unestimated, capacity, estUsed: used };
+}