@connorbritain/roadmap 0.3.0

package/scripts/lib/mcp-core.mjs

@@ -0,0 +1,313 @@
+// roadmap — MCP brain (PURE). Tool registry, read handlers, YAML-Document mutation
+// functions, and the pre-write integrity gate. No IO: the server (mcp.mjs) does the fs reads,
+// writes, and JSON-RPC. Mutations operate on a `yaml` Document (parseDocument) so comments and
+// formatting in roadmap.yaml survive the edit; reads operate on a plain graph object.
+
+import { flatten, detectCycle, STATUS } from "./graph.mjs";
+import { buildPlan } from "./plan.mjs";
+import { validateGraph } from "./validate-core.mjs";
+import { normalizeExecution, suggestedConcurrency, validateExecution } from "./execution.mjs";
+import { validatePriority } from "./priority.mjs";
+import { checkPiOverrideAck, normalizeLinearConfig } from "./linear-core.mjs";
+import { outOfCycle } from "./cycle-core.mjs";
+import { setPlateDoc } from "./plate-core.mjs";
+
+const STATUSES = Object.keys(STATUS);
+const VALID_STATUS = new Set(STATUSES);
+const DONE = new Set(STATUSES.filter((s) => STATUS[s].done));
+
+// Fields a caller may set on a sprint via set_fields / add_sprint (allow-list; protects id/invoke
+// integrity by omission — invoke is set only at creation, ids are structural).
+const SETTABLE = new Set([
+  "title", "what", "status", "status_label", "est_sessions", "weight",
+  "deps", "touches", "owns", "gate", "gated_on", "read_order", "resume_action",
+  "prs", "completed_on", "optional", "execution", "track", "priority", "prompt", "kickoff_brief", "linear", "milestone", "dispatch_tier",
+  "shape", "risks", "estimate",
+]);
+
+// ── tool registry ─────────────────────────────────────────────────────────────
+export const TOOLS = [
+  { name: "plan", description: "Recommended concurrency cap + execution waves + held-on-human. Read-only.",
+    inputSchema: { type: "object", properties: { cap: { type: "integer", minimum: 1 }, reviewCeiling: { type: "integer", minimum: 1 } } } },
+  { name: "ready_wave", description: "The slices runnable right now (wave 1) under the recommended or given cap. Read-only.",
+    inputSchema: { type: "object", properties: { cap: { type: "integer", minimum: 1 } } } },
+  { name: "show", description: "One slice's detail by its invoke key. Read-only.",
+    inputSchema: { type: "object", required: ["invoke"], properties: { invoke: { type: "string" } } } },
+  { name: "validate", description: "Structural + dependency + cycle checks. Returns { ok, errors, warnings }. Read-only.",
+    inputSchema: { type: "object", properties: {} } },
+  { name: "add_pi", description: "Append a new PI (program increment). Validates and re-renders SLICES.md. A linear.granularity that conflicts with the global meta.linear.granularity requires yes_linear_override: true. Scope discipline: a PI is strategic scope — add one only when the user explicitly asked for it; follow-up work goes to backlog_add.",
+    inputSchema: { type: "object", required: ["id", "title"], properties: {
+      id: { type: "string" }, title: { type: "string" }, status: { enum: STATUSES },
+      theme: { type: "string" }, program_label: { type: "string" }, estimate_weeks: { type: "string" },
+      exit_criteria: { type: "string" }, deps: { type: "array", items: { type: "string" } },
+      summary: { type: "string", description: "One crisp human line — the Linear project subtitle; a PI without one lands as a shell" },
+      priority: { type: "object", properties: { tier: { enum: ["P0", "P1", "P2", "P3"] }, weight: { type: "number", minimum: 0, maximum: 100 }, reason: { type: "string" } } },
+      initiative: { type: "string" }, detail: { type: "string" }, exec_hint: { type: "string" },
+      start_date: { type: "string" }, target_date: { type: "string" },
+      linear: { type: "object", properties: { granularity: { enum: ["pis", "slices", "slices+backlog"] }, project: { type: "string" } } },
+      yes_linear_override: { type: "boolean" } } } },
+  { name: "add_sprint", description: "Append a sprint to an existing PI. Validates and re-renders SLICES.md. Scope discipline: scope decisions belong to the human — prefer backlog_add for follow-up work discovered mid-session; add sprints only when the user asked for them.",
+    inputSchema: { type: "object", required: ["pi", "id", "title", "invoke"], properties: {
+      pi: { type: "string" }, id: { type: "string" }, title: { type: "string" }, invoke: { type: "string" },
+      status: { enum: STATUSES }, what: { type: "string" }, est_sessions: { type: "number" },
+      deps: { type: "array", items: { type: "string" } }, touches: { type: "array", items: { type: "string" } },
+      owns: { type: "array", items: { type: "string" } }, gate: { type: "string" },
+      weight: { enum: ["heavy", "medium", "light"] }, gated_on: { type: "string" },
+      read_order: { type: "array", items: { type: "string" } }, resume_action: { type: "string" },
+      prompt: { type: "string" }, milestone: { type: "string" }, status_label: { type: "string" },
+      dispatch_tier: { type: "string" }, kickoff_brief: { type: "string" }, optional: { type: "boolean" },
+      track: { type: "string" }, risks: { type: "array", items: { type: "string" } },
+      priority: { type: "object", properties: { tier: { enum: ["P0", "P1", "P2", "P3"] }, weight: { type: "number", minimum: 0, maximum: 100 }, reason: { type: "string" } } } } } },
+  { name: "set_status", description: "Set a slice's status (by invoke), optionally recording PRs + completed_on. Re-renders.",
+    inputSchema: { type: "object", required: ["invoke", "status"], properties: {
+      invoke: { type: "string" }, status: { enum: STATUSES },
+      prs: { type: "array", items: { type: "string" } }, completed_on: { type: "string" } } } },
+  { name: "set_fields", description: "Set one or more allowed fields on a slice (by invoke). null value deletes a field. Re-renders.",
+    inputSchema: { type: "object", required: ["invoke", "fields"], properties: {
+      invoke: { type: "string" }, fields: { type: "object" } } } },
+  { name: "bulk_set", description: "Set allowed fields on MANY slices in one atomic edit (one validate, one write, one re-render — all-or-nothing). Each update mirrors set_fields: { invoke, fields }, null value deletes a field.",
+    inputSchema: { type: "object", required: ["updates"], properties: {
+      updates: { type: "array", minItems: 1, items: { type: "object", required: ["invoke", "fields"], properties: {
+        invoke: { type: "string" }, fields: { type: "object" } } } } } } },
+  { name: "prune", description: "Remove a slice (by invoke), a whole PI (by pi id), or every complete slice (scope='completed'). Re-renders SLICES.md. Validated before writing: the removal is rejected with no change made if it would orphan a dependency, duplicate an invoke key, or otherwise break the graph.",
+    inputSchema: { type: "object", properties: {
+      invoke: { type: "string" }, pi: { type: "string" }, scope: { enum: ["completed"] } } } },
+  { name: "plate_set", description: "Replace the plate (meta.plate) with `keys` — the curated batch you'll work NOW, projected to Linear's My Issues (assignee=you) on the next sync. The intended use from a planning session (/prioritize): load the top-ranked ready slices. Keep it under plate_max — active work auto-shows on top and completed slices auto-drain, so this is just the deliberate 'on my desk' set.",
+    inputSchema: { type: "object", required: ["keys"], properties: { keys: { type: "array", items: { type: "string" }, description: "slice invoke keys / backlog ids" } } } },
+  { name: "plate_add", description: "Add slice invoke keys / backlog ids to the plate (meta.plate) — creates it (enables the plate) if absent. For folding a newly-relevant slice into the current batch without replacing it.",
+    inputSchema: { type: "object", required: ["keys"], properties: { keys: { type: "array", minItems: 1, items: { type: "string" } } } } },
+  { name: "plate_remove", description: "Remove entries from the plate (meta.plate). Completed slices auto-drain on sync; use this to pull something off your plate early.",
+    inputSchema: { type: "object", required: ["keys"], properties: { keys: { type: "array", minItems: 1, items: { type: "string" } } } } },
+];
+
+// ── read handlers (operate on a plain graph object) ────────────────────────────
+export function readPlan(graph, args = {}) {
+  return buildPlan(graph, { cap: args.cap, reviewCeiling: args.reviewCeiling });
+}
+export function readReadyWave(graph, args = {}) {
+  const plan = buildPlan(graph, { cap: args.cap });
+  // Advisory cycle-lock annotation (reads never block): with cycles on, callers see which wave
+  // slices dispatch/fan would refuse, so planning skills steer to the election instead.
+  const cfg = normalizeLinearConfig(graph.meta || {});
+  const wave = (plan.waves[0] || []).map((n) => (outOfCycle(cfg, n.status) ? { ...n, outOfCycle: true } : n));
+  return { cap: plan.cap, recommended: plan.recommended, wave, held: plan.held };
+}
+export function readShow(graph, args) {
+  if (!args || !args.invoke) throw new Error("show requires invoke");
+  const model = flatten(graph);
+  const n = model.nodes.find((x) => x.invoke === args.invoke);
+  if (!n) throw new Error(`no slice with invoke "${args.invoke}"`);
+  return {
+    invoke: n.invoke, pi: n.piId, sprint: n.id, title: n.title, status: n.status, what: n.what,
+    deps: n.deps, piDeps: n.piDeps, touches: n.touches, owns: n.owns, gate: n.gate,
+    gatedOn: n.gatedOn, readOrder: n.readOrder, resumeAction: n.resumeAction,
+    estSessions: n.estSessions, prs: n.prs,
+    track: n.track, execution: normalizeExecution(n.execution), suggestedConcurrency: suggestedConcurrency(n),
+    priority: n.priority, prompt: n.prompt, linear: n.linear,
+    ...(n.dispatchTier ? { dispatchTier: n.dispatchTier } : {}),
+  };
+}
+export function readValidate(graph) {
+  const { errors, warnings, nodeCount } = validateGraph(graph);
+  return { ok: errors.length === 0, errors, warnings, nodeCount };
+}
+
+export const READ_HANDLERS = { plan: readPlan, ready_wave: readReadyWave, show: readShow, validate: readValidate };
+
+// ── Document helpers (yaml AST navigation) ──────────────────────────────────────
+function pisSeq(doc) {
+  const s = doc.get("pis");
+  if (!s || !s.items) throw new Error("roadmap has no pis sequence");
+  return s;
+}
+function piIndexById(doc, piId) {
+  const items = pisSeq(doc).items;
+  for (let i = 0; i < items.length; i++) if (String(items[i].get("id")) === piId) return i;
+  return -1;
+}
+function sprintLocByInvoke(doc, invoke) {
+  const pis = pisSeq(doc).items;
+  for (let i = 0; i < pis.length; i++) {
+    const sprints = pis[i].get("sprints");
+    const items = (sprints && sprints.items) || [];
+    for (let j = 0; j < items.length; j++) {
+      if (String(items[j].get("invoke")) === invoke) return { pi: i, sprint: j };
+    }
+  }
+  return null;
+}
+
+// ── mutation functions (operate on a yaml Document; mutate in place, return a summary) ──
+// Linear-ready field sets: what a node needs so it lands on the board (and in an election)
+// fully dialed instead of as a shell needing a second pass. Returned as `missing` by the add
+// mutations — a nudge at the add seam, never a block (drafts are legitimate).
+const PI_READY = ["summary", "priority"];
+const SPRINT_READY = ["what", "gate", "est_sessions", "priority"];
+export function readinessGaps(node, kind) {
+  return (kind === "pi" ? PI_READY : SPRINT_READY).filter((k) => node[k] == null);
+}
+
+export function addPi(doc, args) {
+  if (!args || !args.id || !args.title) throw new Error("add_pi requires id + title");
+  if (piIndexById(doc, args.id) >= 0) throw new Error(`PI "${args.id}" already exists`);
+  // A per-PI Linear granularity that conflicts with the global must be explicitly acked
+  // (mirrors --yes-spawn-autonomous); the throw happens before any Document mutation.
+  if (args.linear) checkPiOverrideAck(normalizeLinearConfig(doc.toJS().meta || {}), args.linear, args.yes_linear_override, args.id);
+  const node = { id: args.id, title: args.title, status: args.status || "scheduled" };
+  // Every schema-legal add-time field is copied. This list silently dropping fields the
+  // caller passed is exactly how a fully-specified PI landed on the live board as a shell
+  // (summary/priority/initiative vanished) — extend it whenever the schema grows.
+  for (const k of ["theme", "program_label", "estimate_weeks", "exit_criteria", "linear",
+    "summary", "priority", "initiative", "detail", "exec_hint", "start_date", "target_date"]) if (args[k] != null) node[k] = args[k];
+  if (Array.isArray(args.deps)) node.deps = args.deps;
+  node.sprints = [];
+  // createNode: addIn stores a plain object un-wrapped, which breaks later AST reads (.get)
+  // on the same Document (e.g. add_pi then add_sprint in one batch).
+  doc.addIn(["pis"], doc.createNode(node));
+  const missing = readinessGaps(node, "pi");
+  return missing.length ? { added: "pi", id: args.id, missing } : { added: "pi", id: args.id };
+}
+
+export function addSprint(doc, args) {
+  for (const k of ["pi", "id", "title", "invoke"]) if (!args || !args[k]) throw new Error(`add_sprint requires ${k}`);
+  const pi = piIndexById(doc, args.pi);
+  if (pi < 0) throw new Error(`no PI "${args.pi}"`);
+  const node = { id: args.id, title: args.title, status: args.status || "scheduled", invoke: args.invoke };
+  // Same silent-drop hazard as addPi: keep in step with the sprint schema.
+  for (const k of ["what", "est_sessions", "gate", "weight", "gated_on", "resume_action", "prompt", "priority", "linear", "milestone",
+    "shape", "estimate", "optional", "kickoff_brief", "track", "execution", "status_label", "dispatch_tier"]) if (args[k] != null) node[k] = args[k];
+  for (const k of ["deps", "touches", "owns", "read_order", "risks"]) if (Array.isArray(args[k])) node[k] = args[k];
+  const piMap = pisSeq(doc).items[pi];
+  if (!piMap.has("sprints") || !piMap.get("sprints")) doc.setIn(["pis", pi, "sprints"], doc.createNode([node]));
+  else doc.addIn(["pis", pi, "sprints"], doc.createNode(node));
+  const missing = readinessGaps(node, "sprint");
+  return missing.length ? { added: "sprint", pi: args.pi, invoke: args.invoke, missing } : { added: "sprint", pi: args.pi, invoke: args.invoke };
+}
+
+export function setStatus(doc, args) {
+  if (!args || !args.invoke || !args.status) throw new Error("set_status requires invoke + status");
+  if (!VALID_STATUS.has(args.status)) throw new Error(`invalid status "${args.status}"`);
+  const loc = sprintLocByInvoke(doc, args.invoke);
+  if (!loc) throw new Error(`no slice "${args.invoke}"`);
+  const base = ["pis", loc.pi, "sprints", loc.sprint];
+  doc.setIn([...base, "status"], args.status);
+  if (Array.isArray(args.prs)) doc.setIn([...base, "prs"], args.prs);
+  if (args.completed_on) doc.setIn([...base, "completed_on"], args.completed_on);
+  return { updated: args.invoke, status: args.status };
+}
+
+export function setFields(doc, args) {
+  if (!args || !args.invoke || !args.fields) throw new Error("set_fields requires invoke + fields");
+  const loc = sprintLocByInvoke(doc, args.invoke);
+  if (!loc) throw new Error(`no slice "${args.invoke}"`);
+  const base = ["pis", loc.pi, "sprints", loc.sprint];
+  const changed = [];
+  for (const [k, v] of Object.entries(args.fields)) {
+    if (!SETTABLE.has(k)) throw new Error(`field "${k}" is not settable`);
+    if (v === null) doc.deleteIn([...base, k]);
+    else doc.setIn([...base, k], v);
+    changed.push(k);
+  }
+  return { updated: args.invoke, fields: changed };
+}
+
+// Atomicity is the caller's single write: every update mutates the same Document, one
+// validateDocOrThrow gates the write, so a bad field in update N leaves updates 1..N-1 unwritten.
+export function bulkSet(doc, args) {
+  if (!args || !Array.isArray(args.updates) || !args.updates.length) {
+    throw new Error("bulk_set requires updates: [{invoke, fields}, ...]");
+  }
+  const updated = [];
+  for (const u of args.updates) updated.push(setFields(doc, u).updated);
+  return { updated, count: updated.length };
+}
+
+export function prune(doc, args = {}) {
+  if (args.invoke) {
+    const loc = sprintLocByInvoke(doc, args.invoke);
+    if (!loc) throw new Error(`no slice "${args.invoke}"`);
+    doc.deleteIn(["pis", loc.pi, "sprints", loc.sprint]);
+    return { pruned: [args.invoke] };
+  }
+  if (args.pi) {
+    const i = piIndexById(doc, args.pi);
+    if (i < 0) throw new Error(`no PI "${args.pi}"`);
+    doc.deleteIn(["pis", i]);
+    return { pruned: [`PI:${args.pi}`] };
+  }
+  if (args.scope === "completed") {
+    const graph = doc.toJS();
+    const doneInvokes = [];
+    for (const pi of graph.pis || []) for (const sp of pi.sprints || []) if (DONE.has(sp.status) && sp.invoke) doneInvokes.push(sp.invoke);
+    for (const inv of doneInvokes) {
+      const loc = sprintLocByInvoke(doc, inv);     // re-find each time; indices shift as we delete
+      if (loc) doc.deleteIn(["pis", loc.pi, "sprints", loc.sprint]);
+    }
+    const pis = pisSeq(doc).items;
+    for (let i = pis.length - 1; i >= 0; i--) {     // drop PIs left empty, from the end
+      const s = pis[i].get("sprints");
+      if (!s || !s.items || s.items.length === 0) doc.deleteIn(["pis", i]);
+    }
+    return { pruned: doneInvokes };
+  }
+  throw new Error("prune requires one of: invoke, pi, or scope='completed'");
+}
+
+// ── plate mutations (meta.plate → Linear My Issues) ── operate on the Document like set_fields;
+// setPlateDoc writes a block-style seq. The read side (plate_list) lives in the server (needs backlog).
+function plateListFromDoc(doc) {
+  const arr = (doc.toJS().meta || {}).plate;   // via the Document (a bare node.toJS() needs the doc passed in)
+  return Array.isArray(arr) ? arr.filter((k) => typeof k === "string") : [];
+}
+export function setPlate(doc, args) {
+  if (!args || !Array.isArray(args.keys)) throw new Error("plate_set requires keys: [string, ...]");
+  const keys = [...new Set(args.keys.filter((k) => typeof k === "string"))];
+  setPlateDoc(doc, keys);
+  return { plate: "set", keys };
+}
+export function addPlate(doc, args) {
+  if (!args || !Array.isArray(args.keys) || !args.keys.length) throw new Error("plate_add requires keys: [string, ...]");
+  const keys = [...new Set([...plateListFromDoc(doc), ...args.keys.filter((k) => typeof k === "string")])];
+  setPlateDoc(doc, keys);
+  return { plate: "add", keys };
+}
+export function removePlate(doc, args) {
+  if (!args || !Array.isArray(args.keys) || !args.keys.length) throw new Error("plate_remove requires keys: [string, ...]");
+  const keys = plateListFromDoc(doc).filter((k) => !args.keys.includes(k));
+  setPlateDoc(doc, keys);
+  return { plate: "remove", keys };
+}
+
+export const MUTATION_HANDLERS = { add_pi: addPi, add_sprint: addSprint, set_status: setStatus, set_fields: setFields, bulk_set: bulkSet, prune, plate_set: setPlate, plate_add: addPlate, plate_remove: removePlate };
+
+// ── pre-write integrity gate ────────────────────────────────────────────────────
+// Throws if the edited Document would corrupt the roadmap (duplicate invoke, unresolved
+// dependency, dependency cycle, or an invalid status). Returns the plain graph on success,
+// so the server can hand it straight to renderMarkdown.
+// Serialize a mutated Document back to YAML with options that MINIMIZE diff churn against a
+// hand-authored roadmap.yaml: lineWidth 0 (never re-wrap long scalars like resume_action) and no
+// flow-collection padding (match the common ["#1"] / [s1] style). Comments survive either way.
+// Residual churn is irreducible when the source mixes flow styles; this picks the lower-churn side.
+export function serialize(doc) {
+  return doc.toString({ lineWidth: 0, flowCollectionPadding: false });
+}
+
+export function validateDocOrThrow(doc) {
+  const graph = doc.toJS();
+  let model;
+  try {
+    model = flatten(graph);   // throws on duplicate invoke / unresolved dep
+  } catch (e) {
+    throw new Error(`edit would corrupt the roadmap: ${e.message}`);
+  }
+  const cyc = detectCycle(model);
+  if (cyc) throw new Error(`edit would create a dependency cycle: ${cyc.join(" -> ")}`);
+  for (const n of model.nodes) {
+    if (!VALID_STATUS.has(n.status)) throw new Error(`invalid status "${n.status}" on slice "${n.invoke}"`);
+    const { errors } = validateExecution(n.execution, n.invoke);
+    if (errors.length) throw new Error(`edit would corrupt the roadmap: ${errors[0]}`);
+    const pri = validatePriority(n.priority, n.invoke);
+    if (pri.errors.length) throw new Error(`edit would corrupt the roadmap: ${pri.errors[0]}`);
+  }
+  return graph;
+}

package/scripts/lib/plan.mjs

@@ -0,0 +1,68 @@
+// roadmap — pure plan builder: roadmap graph -> the execution plan object.
+// No IO: flattens, recommends a cap, computes the waves, and returns the structured plan
+// (cap, recommended, binding, sys, candidates, waves[], held). scheduler.mjs prints it;
+// the MCP read tools (plan / ready_wave) return it as JSON. computeWaves may throw on a
+// dependency cycle; callers catch.
+
+import { flatten, computeWaves, readyNodes, coherenceEnabled, isDone } from "./graph.mjs";
+import { recommendConcurrency, nodeWeight, probeDisk } from "./recommend.mjs";
+import { branchFor, worktreeFor, launchPrompt } from "./brief.mjs";
+import { normalizeExecution, suggestedConcurrency } from "./execution.mjs";
+
+const round = (x) => Math.round(x * 10) / 10;
+
+// buildPlan(graph, { cap, useFree, reviewCeiling, disk }). cap omitted -> the recommended cap.
+// disk: undefined -> probe the machine (the real surfaces); null/object -> injected (tests).
+export function buildPlan(graph, opts = {}) {
+  const model = flatten(graph);
+  const ready = readyNodes(model);
+  const rec = recommendConcurrency(ready, graph, {
+    useFree: opts.useFree,
+    reviewCeiling: opts.reviewCeiling ?? 5,
+    disk: opts.disk !== undefined ? opts.disk : probeDisk(graph),
+  });
+  const cap = opts.cap != null ? Number(opts.cap) : rec.recommended;
+  const { waves, held } = computeWaves(model, cap, { coherence: coherenceEnabled(graph.meta) });
+
+  // Which PIs each wave CLOSES (all sprints done once the wave lands, counting earlier waves
+  // optimistically) — the coherence read-out: "this wave finishes auth".
+  const doneKeys = new Set(model.nodes.filter((n) => isDone(n.status)).map((n) => n.nodeKey));
+  const waveCloses = waves.map((w) => {
+    w.forEach((n) => doneKeys.add(n.nodeKey));
+    return [...new Set(w.map((n) => n.piId))].filter((pi) =>
+      model.nodes.filter((m) => m.piId === pi).every((m) => doneKeys.has(m.nodeKey)));
+  });
+
+  return {
+    cap,
+    recommended: rec.recommended,
+    binding: rec.binding,
+    sys: { cores: rec.sys.cores, totalGb: round(rec.sys.totalGb), freeGb: round(rec.sys.freeGb), platform: rec.sys.platform },
+    disk: rec.disk ? { perWorktreeGb: round(rec.disk.perWorktreeGb), freeGb: round(rec.disk.freeGb), cap: rec.disk.cap } : null,
+    candidates: rec.candidates,
+    waveCloses,
+    waves: waves.map((w) =>
+      w.map((n) => ({
+        invoke: n.invoke,
+        pi: n.piId,
+        sprint: n.id,
+        status: n.status,
+        ...(n.dispatchTier ? { dispatch_tier: n.dispatchTier } : {}),
+        weight: nodeWeight(n, graph),
+        est_sessions: n.estSessions,
+        branch: branchFor(n, graph),
+        worktree: worktreeFor(n, graph),
+        prompt: launchPrompt(n),
+        what: n.what,
+        track: n.track,
+        priority: n.priority,
+        execution: normalizeExecution(n.execution),
+        suggestedConcurrency: suggestedConcurrency(n),
+      }))
+    ),
+    held: {
+      onHuman: held.onHuman.map((n) => ({ invoke: n.invoke, gatedOn: n.gatedOn, what: n.what })),
+      blocked: held.blocked.map((n) => ({ invoke: n.invoke, what: n.what })),
+    },
+  };
+}

package/scripts/lib/plate-core.mjs

@@ -0,0 +1,53 @@
+// roadmap — "the plate" (PURE): the curated batch that projects to Linear's My Issues (assignee=you).
+// meta.plate is an explicit list of slice invoke keys / backlog item ids; the live plate ALSO includes
+// whatever you're actively working (active slices, in_progress items) so "what I'm doing" is always on it.
+// The feature is OFF (byte-identical, no assignee projection) unless meta.plate is defined.
+// No IO: linear.mjs fetches the viewer id + assignee snapshot and does the assign/unassign; this decides.
+
+import { isDone } from "./graph.mjs";
+
+// The set of keys that should be assigned to you right now, or null when the feature is off.
+// = meta.plate (explicit) ∪ active slices ∪ in_progress backlog items ("active is always on the plate").
+export function platedKeys(graph, backlog = null) {
+  const meta = graph.meta || {};
+  if (meta.plate == null) return null;
+  const keys = new Set(Array.isArray(meta.plate) ? meta.plate.filter((k) => typeof k === "string") : []);
+  for (const pi of graph.pis || []) for (const sp of pi.sprints || []) if (sp.status === "active" && sp.invoke) keys.add(sp.invoke);
+  for (const it of (backlog && backlog.items) || []) if (it.status === "in_progress" && it.id) keys.add(it.id);
+  return keys;
+}
+
+// Which EXPLICIT meta.plate entries should auto-drain — "complete only": the work finished (slice done,
+// or item done/dropped/promoted). Blocked/paused/gated stay (a visible reminder). Active is never here.
+// Returns the keys to REMOVE from meta.plate (a subset of the explicit list).
+export function plateDrainKeys(graph, backlog = null) {
+  const list = (graph.meta && graph.meta.plate) || [];
+  if (!Array.isArray(list) || !list.length) return [];
+  const done = new Set();
+  for (const pi of graph.pis || []) for (const sp of pi.sprints || []) if (isDone(sp.status) && sp.invoke) done.add(sp.invoke);
+  for (const it of (backlog && backlog.items) || []) if (["done", "dropped", "promoted"].includes(it.status)) done.add(it.id);
+  return list.filter((k) => done.has(k));
+}
+
+// Set meta.plate to `keys` on a YAML Document (block style — a flow seq goes unreadable once it grows).
+// Empty list is written (not deleted) so "the feature is on, batch is empty" stays distinct from "off".
+export function setPlateDoc(doc, keys) {
+  const node = doc.createNode([...keys]);
+  node.flow = false;
+  doc.setIn(["meta", "plate"], node);
+  return keys.length;
+}
+
+// Structural validation + the signal-preservation cap. Reference checking (a key that matches no
+// slice/item) is done at projection time (buildPushPlan reports unmatchedPlate) since it needs the backlog.
+export function validatePlate(graph, plateMax) {
+  const errors = [], warnings = [];
+  const p = graph.meta && graph.meta.plate;
+  if (p == null) return { errors, warnings };
+  if (!Array.isArray(p)) { errors.push("meta.plate must be a list of slice invoke keys / backlog item ids"); return { errors, warnings }; }
+  for (const k of p) if (typeof k !== "string") errors.push(`meta.plate entries must be strings (got ${JSON.stringify(k)})`);
+  if (plateMax && p.length > plateMax) {
+    warnings.push(`meta.plate has ${p.length} explicit entries > plate_max ${plateMax} — trim it so My Issues stays signal (active work adds on top automatically)`);
+  }
+  return { errors, warnings };
+}

package/scripts/lib/pr-watch-core.mjs

@@ -0,0 +1,72 @@
+// roadmap — PR-watch brain (PURE). Decides which PR changes are worth telling the lead
+// about, and which branches belong to this roadmap's fanout. No IO: watch-prs.mjs polls `gh`,
+// normalizes each PR, and feeds snapshots through here. The watcher stays quiet until a PR
+// actually changes phase, so an always-on monitor never spams.
+
+import { flatten } from "./graph.mjs";
+import { branchFor } from "./brief.mjs";
+
+// Reduce a PR's statusCheckRollup (raw `gh` JSON) to one of: none | passing | pending | failing.
+// Pure, so the rollup-to-enum mapping that prPhase keys off is unit-testable without calling gh.
+export function checksOf(pr) {
+  const rollup = (pr && pr.statusCheckRollup) || [];
+  if (!rollup.length) return "none";
+  const states = rollup.map((c) => String(c.conclusion || c.state || c.status || "").toUpperCase());
+  if (states.some((s) => ["FAILURE", "ERROR", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE"].includes(s))) return "failing";
+  if (states.some((s) => ["PENDING", "IN_PROGRESS", "QUEUED", "WAITING", "REQUESTED", ""].includes(s))) return "pending";
+  return "passing";
+}
+
+// The single phase we'd tell the lead about. Derived from the normalized PR fields
+// { state, isDraft, mergeStateStatus, checks }.
+export function prPhase(pr) {
+  if (pr.state === "MERGED") return "merged";
+  if (pr.state === "CLOSED") return "closed";
+  if (pr.isDraft) return "draft";
+  if (pr.mergeStateStatus === "CONFLICTING" || pr.mergeStateStatus === "DIRTY") return "conflicts";
+  if (pr.checks === "failing") return "checks-failing";
+  if (pr.checks === "pending") return "checks-pending";
+  return "ready"; // open, not draft, no conflicts, checks passing or none
+}
+
+const PHASE_MSG = {
+  merged: "merged — reconcile the roadmap (/sync or the set_status tool)",
+  closed: "closed without merging",
+  draft: "opened as a draft",
+  conflicts: "has merge conflicts",
+  "checks-failing": "checks failing",
+  "checks-pending": "checks running",
+  ready: "ready to merge",
+};
+
+// diffPrStates(prev, curr): both are { [number]: normalizedPr }. Returns one event per PR that is
+// newly seen or has changed phase, each with a one-line message for the lead. Deterministic.
+export function diffPrStates(prev, curr) {
+  const events = [];
+  for (const num of Object.keys(curr)) {
+    const pr = curr[num];
+    const before = prev[num];
+    const phase = prPhase(pr);
+    if (before && prPhase(before) === phase) continue; // unchanged
+    events.push({
+      number: pr.number,
+      headRefName: pr.headRefName,
+      title: pr.title,
+      phase,
+      message: `PR #${pr.number} (${pr.headRefName}) ${PHASE_MSG[phase] || phase}`,
+    });
+  }
+  return events;
+}
+
+// The branch names this roadmap's slices fan out onto (one per node, via branchFor).
+export function roadmapBranches(graph) {
+  const model = flatten(graph);
+  return new Set(model.nodes.map((n) => branchFor(n, graph)));
+}
+
+// Is a PR's head branch one of this roadmap's fanout branches? (So the lead only hears about
+// its own wave, not every PR in the repo.)
+export function matchesRoadmapBranches(headRef, graph) {
+  return roadmapBranches(graph).has(headRef);
+}

package/scripts/lib/priority.mjs

@@ -0,0 +1,43 @@
+// roadmap — priority brain (PURE). Shared by roadmap sprints and backlog items:
+// priority: { tier: P0..P3, weight: 0..100, reason }. Every field optional; sort
+// order is DERIVED (tier asc, then weight desc), never stored.
+
+export const TIERS = ["P0", "P1", "P2", "P3"];
+const TIER_RANK = new Map(TIERS.map((t, i) => [t, i]));
+
+// Validate an optional priority block. Absent → no errors (backward-compatible).
+export function validatePriority(raw, where) {
+  const errors = [];
+  if (raw == null) return { errors };
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    return { errors: [`${where}: priority must be a mapping { tier, weight, reason }`] };
+  }
+  if (raw.tier != null && !TIER_RANK.has(raw.tier)) {
+    errors.push(`${where}: priority.tier "${raw.tier}" is not one of ${TIERS.join("|")}`);
+  }
+  if (raw.weight != null && (typeof raw.weight !== "number" || raw.weight < 0 || raw.weight > 100)) {
+    errors.push(`${where}: priority.weight must be a number 0..100 (got ${JSON.stringify(raw.weight)})`);
+  }
+  if (raw.reason != null && typeof raw.reason !== "string") {
+    errors.push(`${where}: priority.reason must be a string`);
+  }
+  return { errors };
+}
+
+// Sort comparator. Tier ascending (absent tier ranks AFTER P3), then weight descending
+// (absent = 0). Returns 0 when both are absent — the backward-compat guarantee: an
+// unprioritized graph falls through to the caller's existing ordering untouched.
+export function comparePriority(a, b) {
+  if (a == null && b == null) return 0;
+  const ta = a && TIER_RANK.has(a.tier) ? TIER_RANK.get(a.tier) : TIERS.length;
+  const tb = b && TIER_RANK.has(b.tier) ? TIER_RANK.get(b.tier) : TIERS.length;
+  if (ta !== tb) return ta - tb;
+  const wa = (a && typeof a.weight === "number") ? a.weight : 0;
+  const wb = (b && typeof b.weight === "number") ? b.weight : 0;
+  return wb - wa;
+}
+
+// "P0" | null — the compact badge for renders and plan listings.
+export function tierBadge(p) {
+  return p && TIER_RANK.has(p.tier) ? p.tier : null;
+}