@connorbritain/roadmap 0.3.0

package/scripts/lib/sync-core.mjs

@@ -0,0 +1,89 @@
+// roadmap — reconcile brain (PURE). Detects slices whose work has merged but whose roadmap
+// status still says open, so the SessionStart hook and the PR monitor can nudge the agent to
+// reconcile (mark complete + record the PR, then re-render). No IO: the caller supplies the
+// merged-PR list (from gh); this just matches it against the graph by fanout branch.
+
+import { flatten, isDone } from "./graph.mjs";
+import { branchFor } from "./brief.mjs";
+import { normalizeExecution, dirClusters } from "./execution.mjs";
+
+// findUnrecordedMerges(graph, mergedPrs): mergedPrs is [{ number, headRefName, title?, body? }]
+// (state=merged). Returns the not-done slices whose work has a merged PR: [{ invoke, pr, branch }].
+// Two matching layers:
+//   1. branch — headRefName equals the slice's convention branch (local fanout worktrees).
+//   2. marker — the PR title/body contains the machine line `roadmap: slice=<invoke>` (cloud
+//      dispatches push unpredictable claude/-prefixed branches, so the capsule + dispatch
+//      guidance require the marker in the PR description; the kickoff brief adds it too).
+export function findUnrecordedMerges(graph, mergedPrs) {
+  const byBranch = new Map();
+  const byMarker = new Map();   // invoke -> pr number (first match wins)
+  for (const pr of mergedPrs || []) {
+    if (!pr) continue;
+    if (pr.headRefName && !byBranch.has(pr.headRefName)) byBranch.set(pr.headRefName, pr.number);
+    const text = `${pr.title || ""}\n${pr.body || ""}`;
+    for (const m of text.matchAll(/roadmap: slice=([a-z0-9][a-z0-9-]*)/g)) {
+      if (!byMarker.has(m[1])) byMarker.set(m[1], pr.number);
+    }
+  }
+  const model = flatten(graph);
+  const out = [];
+  for (const n of model.nodes) {
+    if (isDone(n.status)) continue;
+    const branch = branchFor(n, graph);
+    if (byBranch.has(branch)) out.push({ invoke: n.invoke, pr: byBranch.get(branch), branch });
+    else if (byMarker.has(n.invoke)) out.push({ invoke: n.invoke, pr: byMarker.get(n.invoke), branch: "(cloud — matched by PR marker)" });
+  }
+  return out;
+}
+
+// Post-run guardrail (the under-parallelization warning surfaced in /sync). `runStats` is the
+// observed run telemetry/log: [{ invoke, workers }] (the LIVE worker count a slice actually ran with).
+// Flags any slice that declares a `min_concurrency` floor, touches ≥2 disjoint dir clusters (so it
+// COULD have parallelized), and ran with fewer live workers than its floor. Returns warning strings.
+export function underParallelizedWarnings(graph, runStats) {
+  const model = flatten(graph);
+  const byInvoke = new Map(model.nodes.map((n) => [n.invoke, n]));
+  const out = [];
+  for (const r of runStats || []) {
+    if (!r || r.workers == null || !Number.isFinite(r.workers)) continue;
+    const n = byInvoke.get(r.invoke);
+    if (!n || !n.execution) continue;
+    const exec = normalizeExecution(n.execution);
+    if (!exec || exec.minConcurrency == null) continue;
+    const disjoint = dirClusters([...(n.touches || []), ...(n.owns || [])]).size >= 2;
+    if (disjoint && r.workers < exec.minConcurrency) {
+      out.push(`slice ${r.invoke} ran ${r.workers} worker${r.workers === 1 ? "" : "s"}; min_concurrency ${exec.minConcurrency} — under-parallelized`);
+    }
+  }
+  return out;
+}
+
+// Scope-discipline knob: max (captured items + added sprints) per completed slice per review
+// window before the sprawl warning fires. The knob is meta.discipline.capture_ratio.
+export const captureRatio = (meta) => (meta && meta.discipline && meta.discipline.capture_ratio) ?? 2;
+
+// Post-run scope guardrail (the sprawl warning surfaced in /sync and /debrief). Counts are
+// window-relative: what completed vs what was captured/added since the last review anchor.
+// PIs are ALWAYS flagged regardless of ratio — a PI is strategic scope and should never
+// appear from a worker session without a human decision.
+export function sprawlWarnings({ completed = 0, captured = 0, addedSprints = 0, addedPis = [], ratioThreshold = 2 } = {}) {
+  const out = [];
+  const grown = captured + addedSprints;
+  const ratio = grown / Math.max(completed, 1);
+  if (grown > 0 && ratio > ratioThreshold) {
+    out.push(`sprawl: ${grown} captured (${captured} item(s) + ${addedSprints} sprint(s)) vs ${completed} completed since the last review — ratio ${ratio.toFixed(1)} exceeds capture_ratio ${ratioThreshold}; scope is growing faster than it ships. Triage before adding more.`);
+  }
+  for (const pi of addedPis || []) {
+    out.push(`sprawl: PI "${pi}" added since the last review — new PIs are strategic scope; confirm this was a human decision, not an agent capture.`);
+  }
+  return out;
+}
+
+// One-line, actionable nudge for the agent. Empty string when nothing is unrecorded (stay quiet).
+export function reconcileNudge(unrecorded) {
+  if (!unrecorded || !unrecorded.length) return "";
+  const items = unrecorded.map((u) => `${u.invoke} (PR #${u.pr})`).join(", ");
+  return `${unrecorded.length} slice(s) have a merged PR but are still open: ${items}. `
+    + `Reconcile the roadmap: run /sync, or call the roadmap set_status tool for each `
+    + `(status=complete, record the PR). It re-renders SLICES.md.`;
+}

package/scripts/lib/validate-core.mjs

@@ -0,0 +1,130 @@
+// roadmap — pure validator: roadmap graph -> { errors, warnings, nodeCount }.
+// No IO. validate.mjs prints + exits on the result; the MCP `validate` read tool returns it.
+// Structural checks + dependency resolution (via flatten) + cycle detection.
+
+import { flatten, detectCycle, STATUS } from "./graph.mjs";
+import { validateExecution } from "./execution.mjs";
+import { validatePriority } from "./priority.mjs";
+import { validateLinearConfig } from "./linear-core.mjs";
+import { validateEstimation } from "./estimate-core.mjs";
+
+const isDone = (s) => !!(STATUS[s] && STATUS[s].done);
+
+export function validateGraph(graph) {
+  const errors = [];
+  const warnings = [];
+  const err = (m) => errors.push(m);
+  const warn = (m) => warnings.push(m);
+
+  const meta = graph.meta || {};
+  if (meta.schema_version !== 1) err(`meta.schema_version must be 1 (got ${JSON.stringify(meta.schema_version)})`);
+  if (!meta.program) err("meta.program is required");
+  if (meta.terminal && !["warp", "wt", "tmux", "iterm", "background", "print"].includes(meta.terminal)) {
+    err(`meta.terminal "${meta.terminal}" is not a known adapter`);
+  }
+  if (meta.assistants != null) {
+    if (typeof meta.assistants !== "object" || Array.isArray(meta.assistants)) err("meta.assistants must be a mapping");
+    else {
+      if (meta.assistants.default != null && typeof meta.assistants.default !== "string") err("meta.assistants.default must be a profile name string");
+      if (meta.assistants.profiles != null && (typeof meta.assistants.profiles !== "object" || Array.isArray(meta.assistants.profiles))) err("meta.assistants.profiles must be a mapping");
+    }
+  }
+
+  // Jira is the designed follow-up but NOT implemented — surface a stray block instead of
+  // letting someone believe it syncs (docs/DEPLOYMENT.md documents the planned shape).
+  if (meta.jira != null) warn("meta.jira is not implemented yet (Linear is the only tracker today) — the block is ignored");
+
+  // Scope-discipline knobs + the review anchor. Absent → no-op.
+  if (meta.discipline != null) {
+    if (typeof meta.discipline !== "object" || Array.isArray(meta.discipline)) err("meta.discipline must be a mapping");
+    else {
+      if (meta.discipline.capture_ratio != null && !(typeof meta.discipline.capture_ratio === "number" && meta.discipline.capture_ratio > 0)) {
+        err("meta.discipline.capture_ratio must be a number > 0");
+      }
+      if (meta.discipline.coherence != null && typeof meta.discipline.coherence !== "boolean") {
+        err("meta.discipline.coherence must be a boolean");
+      }
+      if (meta.discipline.pi_min_slices != null && !(Number.isInteger(meta.discipline.pi_min_slices) && meta.discipline.pi_min_slices >= 1)) {
+        err("meta.discipline.pi_min_slices must be an integer >= 1 (a bad knob silently disabling a guardrail is the failure mode)");
+      }
+      // Composition SHAPE (capture_ratio guards growth RATE): a PI under the floor is usually a
+      // slice wearing a PI's coat — 13 one-slice PIs is how a 64-project wall happens. ONE
+      // aggregated warning (signal, not a wall); complete PIs exempt (history is what it is).
+      const floor = meta.discipline.pi_min_slices;
+      if (Number.isInteger(floor) && floor >= 1) {
+        const thin = (graph.pis || []).filter((pi) => !isDone(pi.status) && (pi.sprints || []).length < floor);
+        if (thin.length) {
+          warn(`composition: ${thin.length} non-complete PI(s) hold fewer than ${floor} slice(s) (${thin.map((p) => p.id).join(", ")}) — a PI is a strategic bet; fold these into siblings or grow them`);
+        }
+      }
+    }
+  }
+  if (meta.last_review != null) {
+    if (typeof meta.last_review !== "object" || Array.isArray(meta.last_review) || typeof meta.last_review.date !== "string" || typeof meta.last_review.commit !== "string") {
+      err("meta.last_review must be a mapping with string date + commit");
+    }
+  }
+
+  // Optional meta.linear + per-PI overrides + sprint linear fields. Absent → no-op.
+  const lin = validateLinearConfig(graph);
+  for (const e of lin.errors) err(e);
+  for (const w of lin.warnings) warn(w);
+
+  // Optional agent-time estimation config + per-slice estimate fields. Absent → no-op.
+  const est = validateEstimation(graph);
+  for (const e of est.errors) err(e);
+  for (const w of est.warnings) warn(w);
+
+  const validStatus = new Set(Object.keys(STATUS));
+  const seenPiIds = new Set();
+  for (const pi of graph.pis || []) {
+    if (!pi.id) { err("a PI is missing id"); continue; }
+    if (seenPiIds.has(pi.id)) err(`duplicate PI id "${pi.id}"`);
+    seenPiIds.add(pi.id);
+    if (!pi.title) err(`PI ${pi.id}: title required`);
+    if (pi.initiative != null && typeof pi.initiative !== "string") err(`PI ${pi.id}: initiative must be a string (the Linear initiative name)`);
+    for (const e of validatePriority(pi.priority, `PI ${pi.id}`).errors) err(e);
+    if (pi.target_date != null && !/^\d{4}-\d{2}-\d{2}$/.test(pi.target_date)) err(`PI ${pi.id}: target_date must be YYYY-MM-DD (got ${JSON.stringify(pi.target_date)})`);
+    if (pi.start_date != null && !/^\d{4}-\d{2}-\d{2}$/.test(pi.start_date)) err(`PI ${pi.id}: start_date must be YYYY-MM-DD (got ${JSON.stringify(pi.start_date)})`);
+    if (pi.projected_target_date != null && !/^\d{4}-\d{2}-\d{2}$/.test(pi.projected_target_date)) err(`PI ${pi.id}: projected_target_date must be YYYY-MM-DD (got ${JSON.stringify(pi.projected_target_date)})`);
+    if (pi.summary != null && (typeof pi.summary !== "string" || pi.summary.length > 255)) err(`PI ${pi.id}: summary must be a string of at most 255 chars (it's the Linear subtitle — keep it to one line)`);
+    if (!validStatus.has(pi.status)) err(`PI ${pi.id}: status "${pi.status}" invalid`);
+    if (!Array.isArray(pi.sprints) || pi.sprints.length === 0) { err(`PI ${pi.id}: needs >=1 sprint`); continue; }
+    const seenSprintIds = new Set();
+    for (const sp of pi.sprints) {
+      const where = `${pi.id}/${sp.id || "?"}`;
+      if (!sp.id) err(`${pi.id}: a sprint is missing id`);
+      else if (seenSprintIds.has(sp.id)) err(`${pi.id}: duplicate sprint id "${sp.id}"`);
+      seenSprintIds.add(sp.id);
+      if (!sp.title) err(`${where}: title required`);
+      if (!validStatus.has(sp.status)) err(`${where}: status "${sp.status}" invalid`);
+      if (!sp.invoke) err(`${where}: invoke key required`);
+      if (sp.gated_on && sp.status !== "gated") warn(`${where}: gated_on set but status is "${sp.status}" (expected gated)`);
+      if (!isDone(sp.status) && sp.est_sessions == null) warn(`${where}: no est_sessions (sessions-remaining rollup will undercount)`);
+      // Optional execution-strategy hint. Absent → no-op (backward-compatible); present → enum/type/consistency checks.
+      const exec = validateExecution(sp.execution, where);
+      for (const e of exec.errors) err(e);
+      for (const w of exec.warnings) warn(w);
+      // Optional priority block. Absent → no-op.
+      for (const e of validatePriority(sp.priority, where).errors) err(e);
+    }
+  }
+
+  // flatten resolves deps + unique invoke keys (throws on failure), then cycle-detect.
+  let model = null;
+  try {
+    model = flatten(graph);
+  } catch (e) {
+    err(e.message);
+  }
+  if (model) {
+    try {
+      const cyc = detectCycle(model);
+      if (cyc) err(`dependency cycle: ${cyc.join(" → ")}`);
+    } catch (e) {
+      err(`cycle detection failed: ${e.message}`);
+    }
+  }
+
+  return { errors, warnings, nodeCount: model ? model.nodes.length : 0 };
+}

package/scripts/lib/wizard-core.mjs

@@ -0,0 +1,50 @@
+// roadmap — interactive console core (PURE, unit-tested).
+// The bare-`roadmap` wizard's decisions live here so they're testable without a TTY:
+// which terminal to default to, how arrow-keys move a selection, how the cap field parses,
+// and how the collected answers translate into the exact `fanout.mjs` flags. The raw-mode IO
+// lives in prompt.mjs; the orchestration in wizard.mjs. No side effects on import.
+
+// Terminal adapters offered by the wizard, platform default first (it's the safe Enter).
+// Windows → Windows Terminal; everything else → tmux. All adapters stay selectable.
+export function terminalChoices(platform) {
+  const def = platform === "win32" ? "wt" : "tmux";
+  const all = ["wt", "warp", "tmux", "print", "background"];
+  return [def, ...all.filter((t) => t !== def)];
+}
+
+// Arrow-key navigation for a list of length `len`, wrapping at both ends (k/j alias up/down).
+// Unrelated keys leave the index unchanged.
+export function moveSelection(idx, key, len) {
+  if (len <= 0) return 0;
+  if (key === "up" || key === "k") return (idx - 1 + len) % len;
+  if (key === "down" || key === "j") return (idx + 1) % len;
+  return idx;
+}
+
+// Parse the max-concurrency field. Blank → the recommended default; non-numeric or out-of-range
+// → an error message (so the prompt re-asks rather than silently coercing a thrashing/no-op cap).
+export function parseCap(input, { min = 1, max = Infinity, def } = {}) {
+  const str = String(input ?? "").trim();
+  if (str === "") return { value: def };
+  if (!/^\d+$/.test(str)) return { error: `Enter a whole number between ${min} and ${max}.` };
+  const n = Number(str);
+  if (n < min || n > max) return { error: `Must be between ${min} and ${max}.` };
+  return { value: n };
+}
+
+// Translate the wizard's collected answers into the argv `fanout.mjs` understands.
+// launch = fanout's default (no extra flag); dry = --dry; save = --out <name>.
+export function buildFanArgs({ term, cap, wave, lead, mode, outName }) {
+  const args = ["--term", String(term), "--cap", String(cap), "--wave", String(wave)];
+  if (lead) args.push("--lead-claude");
+  if (mode === "dry") args.push("--dry");
+  else if (mode === "save") args.push("--out", outName);
+  return args;
+}
+
+// Default filename for the "save script" action — the extension must match the target shell
+// (PowerShell for wt/warp, bash for tmux/print/background) or the saved script won't run.
+export function autoOutName(term, wave) {
+  const ext = term === "wt" || term === "warp" ? "ps1" : "sh";
+  return `wave${wave}.${ext}`;
+}