@connorbritain/roadmap 0.3.0

package/scripts/lib/estimate-core.mjs

@@ -0,0 +1,204 @@
+// roadmap — estimation brain (PURE: no fs, no network, no spawn). Bridges agent-time's
+// estimator.py into the roadmap: builds the estimator CLI args from a slice, parses its
+// JSON record, shapes the compact `estimate` block cached on the slice, and validates the
+// estimation config + fields. The IO (spawning python, YAML write-back) lives in
+// scripts/estimate.mjs; the timeline rollup (Phase 2) adds to this file.
+//
+// agent-time owns the shape/risk vocabulary — its SHAPES/RISKS tables validate and reject
+// unknown values — so the roadmap deliberately does NOT duplicate the enum (no drift).
+
+import { flatten, computeWaves, isDone } from "./graph.mjs";
+
+const DEFAULTS = { python: "python3", hours_per_day: 6, point: "expected", model: "opus-4.8" };
+
+// meta.estimation → a filled config (defaults applied). Estimation is an explicit command,
+// so this returns a usable config even when meta.estimation is absent; the block just
+// overrides defaults. `engine: null` → the IO layer resolves the default estimator path.
+export function estimationConfig(meta) {
+  const raw = (meta && meta.estimation) || {};
+  return {
+    engine: raw.engine || null,
+    python: raw.python || DEFAULTS.python,
+    hours_per_day: typeof raw.hours_per_day === "number" && raw.hours_per_day > 0 ? raw.hours_per_day : DEFAULTS.hours_per_day,
+    point: raw.point === "high" ? "high" : DEFAULTS.point,
+    model: raw.model || DEFAULTS.model,
+  };
+}
+
+// argv for `estimator.py estimate` from a slice. A FRESH estimate every call: agent-time's
+// reestimate needs rounds-spent from a live session, which batch planning doesn't have, so
+// re-estimation is a fresh estimate (via --force), not a reestimate. Throws when the slice
+// isn't classified — an explicit shape is required (no silent heuristic).
+export function estimateArgs(sprint, cfg) {
+  if (!sprint || !sprint.shape) {
+    throw new Error(`slice "${(sprint && sprint.invoke) || "?"}" has no shape — set shape (+ optional risks) before estimating`);
+  }
+  const args = ["estimate", "--summary", sprint.title || sprint.invoke, "--shape", sprint.shape, "--json"];
+  const risks = Array.isArray(sprint.risks) ? sprint.risks.filter((r) => typeof r === "string" && r) : [];
+  if (risks.length) args.push("--risks", risks.join(","));
+  if (cfg && cfg.model) args.push("--model", cfg.model);
+  return args;
+}
+
+// `estimate --json` prints a markdown block, a blank line, then the pretty JSON record LAST.
+// Pull the trailing top-level object (the record starts on its own `{` line).
+export function parseEstimateRecord(stdout) {
+  const s = String(stdout || "").replace(/\r\n/g, "\n");   // Windows python emits CRLF
+  const at = s.lastIndexOf("\n{\n");
+  const jsonText = at >= 0 ? s.slice(at + 1) : (s.trimStart().startsWith("{") ? s : null);
+  if (!jsonText) throw new Error("no JSON record in estimator output (was --json passed?)");
+  let rec;
+  try { rec = JSON.parse(jsonText.trim()); } catch { throw new Error("could not parse the estimator's JSON record"); }
+  if (!rec || rec.type !== "estimate" || !rec.est_minutes) throw new Error("estimator record missing est_minutes");
+  // Trust boundary: the estimator is an external process. A status-0 response with a present-but-
+  // non-numeric est_minutes would otherwise cache a bogus block that only warns on validate — reject it.
+  const m = rec.est_minutes;
+  if (["low", "expected", "high"].some((k) => typeof m[k] !== "number")) throw new Error("estimator record has non-numeric est_minutes");
+  return rec;
+}
+
+// The compact block cached on the slice (schema: sprint.estimate).
+export function applyEstimate(record) {
+  const m = (record && record.est_minutes) || {};
+  return {
+    minutes: { low: m.low, expected: m.expected, high: m.high },
+    confidence: record.confidence,
+    task_id: record.task_id,
+    at: record.ts,
+    basis: record.calibration_basis,
+  };
+}
+
+export const LOG_STATUSES = ["pass", "fail", "partial", "abandoned"];   // agent-time's outcome statuses (single source)
+
+// argv for `estimator.py log` — the calibration outcome for a completed slice. agent-time auto-fills
+// actual rounds/minutes from its own session tracking when present; we always pass --status, and the
+// optional actuals for a manual entry. Throws when the slice was never estimated (no task_id to key on).
+export function logArgs(sprint, status, opts = {}) {
+  const tid = sprint && sprint.estimate && sprint.estimate.task_id;
+  if (!tid) throw new Error(`slice "${(sprint && sprint.invoke) || "?"}" has no estimate.task_id — run 'roadmap estimate ${(sprint && sprint.invoke) || "<slice>"}' first`);
+  const st = status || "pass";
+  if (!LOG_STATUSES.includes(st)) throw new Error(`status must be one of ${LOG_STATUSES.join("|")} (got "${st}")`);
+  const args = ["log", "--task-id", tid, "--status", st];
+  if (typeof opts.actualMinutes === "number") args.push("--actual-minutes", String(opts.actualMinutes));
+  if (typeof opts.actualRounds === "number") args.push("--actual-rounds", String(opts.actualRounds));
+  return args;
+}
+
+// Has agent-time already logged an outcome for this task_id? Idempotency for the calibration loop —
+// reads agent-time's own JSONL history (its store, not the roadmap's), so re-firing never double-counts.
+export function alreadyLogged(historyText, taskId) {
+  if (!historyText || !taskId) return false;
+  for (const line of String(historyText).split("\n")) {
+    const t = line.trim();
+    if (!t) continue;
+    let rec; try { rec = JSON.parse(t); } catch { continue; }
+    if (rec && rec.type === "outcome" && rec.task_id === taskId) return true;
+  }
+  return false;
+}
+
+// A calendar date `offsetMinutes` of agent wall-clock after `anchor`, at `hoursPerDay`
+// productive hours/day. Calendar days (ceil), not business days (a deferred knob). `anchor`
+// is a fixed YYYY-MM-DD string, so this stays deterministic (no wall-clock read).
+export function calendarFromMinutes(offsetMinutes, { hoursPerDay, anchor }) {
+  const days = Math.ceil(Math.max(0, offsetMinutes) / (hoursPerDay * 60));
+  const d = new Date(`${anchor}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + days);
+  return d.toISOString().slice(0, 10);
+}
+
+// Roll per-slice durations up into a projected target date per PI. Uses the SAME wave
+// schedule the fanout runs (computeWaves: dependency + concurrency + file-contention order),
+// so the projection matches how work actually flows. A wave runs concurrently → its span is
+// the MAX slice duration in it (not the sum); waves are sequential → spans accumulate. Each PI's
+// finish is its last scheduled slice's cumulative offset, laid on the calendar from `anchor`.
+//
+// Honest bounds (surfaced, never a silent hole in the DATE):
+//  · Unpriced slice (no estimate) → it's scheduled work of unknown length, so it SUPPRESSES its
+//    PI's date entirely (a PI is dated only when every remaining slice is priced) and is listed in
+//    `unpriced`. We never emit a date that quietly omits it.
+//  · Held slice (blocked / gated-on-human) → not schedulable, so computeWaves excludes it from the
+//    makespan; it's listed in `held`. The date reflects the schedulable frontier, deliberately
+//    optimistic there — but that's a labelled, surfaced exclusion, not a zero folded into the number.
+export function timelinePlan(graph, opts = {}) {
+  const cfg = estimationConfig(graph.meta || {});
+  const point = opts.point || cfg.point;
+  const hoursPerDay = opts.hoursPerDay || cfg.hours_per_day;
+  const concurrency = opts.concurrency || (graph.meta && graph.meta.default_concurrency) || 3;
+  const activeStarts = (graph.pis || []).filter((p) => p.status === "active" && p.start_date).map((p) => p.start_date).sort();
+  const anchor = opts.anchor || activeStarts[0] || (opts.now ? opts.now.slice(0, 10) : null);
+  if (!anchor) throw new Error("timelinePlan needs an anchor: no active start_date and no `now` supplied");
+
+  const minsAt = (minutes) => (minutes && typeof minutes[point] === "number") ? minutes[point] : null;
+
+  // Pricing gate from the GRAPH (authoritative — covers held slices too, which never reach the waves):
+  // a PI earns a date only when it has a priced remaining slice AND no unpriced one.
+  const unpriced = [];
+  const hasPriced = new Set();
+  const hasUnpriced = new Set();
+  for (const pi of graph.pis || []) {
+    for (const sp of pi.sprints || []) {
+      if (isDone(sp.status)) continue;
+      if (minsAt(sp.estimate && sp.estimate.minutes) == null) { unpriced.push(sp.invoke); hasUnpriced.add(pi.id); }
+      else hasPriced.add(pi.id);
+    }
+  }
+
+  // Makespan from the wave schedule: span = slowest slice (parallel), waves accumulate (sequential).
+  // Every scheduled node registers its PI's finish (Math.max, so a 0-min wave still records offset 0).
+  const model = flatten(graph);
+  const { waves, held } = computeWaves(model, concurrency);
+  const finishByPi = new Map();
+  let cumulative = 0;
+  for (const wave of waves) {
+    let span = 0;
+    for (const n of wave) { const m = minsAt(n.estMinutes); if (m != null && m > span) span = m; }
+    cumulative += span;
+    for (const n of wave) finishByPi.set(n.piId, Math.max(finishByPi.get(n.piId) ?? 0, cumulative));
+  }
+
+  const pis = [];
+  for (const pi of graph.pis || []) {
+    if (!hasPriced.has(pi.id) || hasUnpriced.has(pi.id)) continue;   // needs a basis AND no unpriced hole
+    if (!finishByPi.has(pi.id)) continue;   // priced but every slice is held (none scheduled) → no makespan
+    pis.push({ pi: pi.id, projected_target_date: calendarFromMinutes(finishByPi.get(pi.id), { hoursPerDay, anchor }) });
+  }
+  const heldInvokes = [...(held.onHuman || []), ...(held.blocked || [])].map((n) => n.invoke);
+  return { anchor, concurrency, hoursPerDay, point, pis, unpriced, held: heldInvokes };
+}
+
+// Optional estimation config + per-slice estimate fields. Absent → no-op. Mirrors
+// validateLinearConfig: returns { errors, warnings } folded into the main validator.
+export function validateEstimation(graph) {
+  const errors = [];
+  const warnings = [];
+  const raw = graph.meta && graph.meta.estimation;
+  if (raw != null) {
+    if (typeof raw !== "object" || Array.isArray(raw)) errors.push("meta.estimation must be a mapping");
+    else {
+      if (raw.hours_per_day != null && !(typeof raw.hours_per_day === "number" && raw.hours_per_day > 0)) {
+        errors.push("meta.estimation.hours_per_day must be a number > 0");
+      }
+      if (raw.point != null && raw.point !== "expected" && raw.point !== "high") {
+        errors.push('meta.estimation.point must be "expected" or "high"');
+      }
+    }
+  }
+  for (const pi of graph.pis || []) {
+    for (const sp of pi.sprints || []) {
+      const where = `${pi.id}/${sp.id || "?"}`;
+      if (sp.shape != null && typeof sp.shape !== "string") errors.push(`${where}: shape must be a string`);
+      if (sp.risks != null && (!Array.isArray(sp.risks) || sp.risks.some((r) => typeof r !== "string"))) {
+        errors.push(`${where}: risks must be an array of strings`);
+      }
+      if (sp.estimate != null) {
+        if (typeof sp.estimate !== "object" || Array.isArray(sp.estimate)) errors.push(`${where}: estimate must be a mapping`);
+        else if (sp.estimate.minutes != null && typeof sp.estimate.minutes.expected !== "number") {
+          warnings.push(`${where}: estimate.minutes has no numeric expected — re-run 'roadmap estimate ${sp.invoke} --force'`);
+        }
+      }
+    }
+  }
+  return { errors, warnings };
+}

package/scripts/lib/execution.mjs

@@ -0,0 +1,186 @@
+// roadmap — execution strategy brain (PURE).
+// A per-slice `execution:` block declares HOW to staff the slice: the fan-out topology
+// (solo / subagents / dynamic-workflow / agent-team), a suggested LIVE worker count, a
+// floor, and the team composition. Agents chronically under-parallelize (a lone subagent
+// where a team fits); this turns the author's intent into an IMPERATIVE directive the
+// launched session reads, instead of leaving the call to gut feel.
+//
+// No IO. The block is OPTIONAL and BACKWARD-COMPATIBLE: a slice without it behaves exactly
+// as before. validate-core checks it, render-core / show / brief render the directive, and
+// fanout honors the topology.
+
+export const EXEC_MODES = ["solo", "subagents", "dynamic-workflow", "agent-team"];
+export const EXEC_ROLES = ["verifier", "implementer", "reviewer", "researcher", "integrator"];
+
+// Cap the auto-suggested floor so a slice touching dozens of dirs doesn't recommend an
+// absurd worker count — past ~6 the review/merge cost dominates the parallelism win.
+export const CLUSTER_CAP = 6;
+
+// Distinct disjoint top-level dir clusters from a file list. "src/a.ts" and "src/b.ts"
+// share the `src` cluster (one shared lane); "src/x" + "docs/y" are two disjoint lanes.
+export function dirClusters(files = []) {
+  const set = new Set();
+  for (const f of files || []) {
+    const s = String(f).trim();
+    if (!s) continue;
+    set.add(s.split("/")[0]);
+  }
+  return set;
+}
+
+// Suggested concurrency FLOOR derived from a slice's touched files = the count of distinct
+// disjoint top-level dir clusters (capped). A HINT, never a hard default. null when the
+// slice declares no files to reason about.
+export function suggestedConcurrency(node) {
+  const files = [...((node && node.touches) || []), ...((node && node.owns) || [])];
+  const n = dirClusters(files).size;
+  if (n <= 0) return null;
+  return Math.min(CLUSTER_CAP, Math.max(1, n));
+}
+
+// Normalize a raw sprint.execution block to a stable shape (or null when absent). team[].count
+// defaults to 1. Does NOT validate — validateExecution does that; this just shapes for rendering.
+export function normalizeExecution(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const team = Array.isArray(raw.team)
+    ? raw.team
+        .filter((t) => t && typeof t === "object")
+        .map((t) => ({ role: t.role, count: Number.isInteger(t.count) ? t.count : 1 }))
+    : null;
+  return {
+    mode: raw.mode || null,
+    concurrency: raw.concurrency != null ? raw.concurrency : null,
+    minConcurrency: raw.min_concurrency != null ? raw.min_concurrency : null,
+    team: team && team.length ? team : null,
+    rationale: raw.rationale || null,
+  };
+}
+
+// Total declared head-count across the team composition (null when no team).
+export function teamSize(team) {
+  if (!team || !team.length) return null;
+  return team.reduce((a, t) => a + (Number.isInteger(t.count) ? t.count : 1), 0);
+}
+
+// Validate a raw execution block. Returns { errors, warnings } (both arrays, possibly empty).
+// Absent block → no errors (backward-compatible). `where` is the "pi/sprint" locator for messages.
+export function validateExecution(raw, where) {
+  const errors = [];
+  const warnings = [];
+  if (raw == null) return { errors, warnings };
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    errors.push(`${where}: execution must be a mapping`);
+    return { errors, warnings };
+  }
+
+  if (raw.mode != null && !EXEC_MODES.includes(raw.mode)) {
+    errors.push(`${where}: execution.mode "${raw.mode}" invalid (one of ${EXEC_MODES.join(" | ")})`);
+  }
+
+  for (const k of ["concurrency", "min_concurrency"]) {
+    if (raw[k] != null && (!Number.isInteger(raw[k]) || raw[k] < 1)) {
+      errors.push(`${where}: execution.${k} must be an integer ≥1 (got ${JSON.stringify(raw[k])})`);
+    }
+  }
+
+  if (
+    Number.isInteger(raw.concurrency) && Number.isInteger(raw.min_concurrency) &&
+    raw.min_concurrency > raw.concurrency
+  ) {
+    errors.push(`${where}: execution.min_concurrency (${raw.min_concurrency}) must be ≤ concurrency (${raw.concurrency})`);
+  }
+
+  if (raw.team != null) {
+    if (!Array.isArray(raw.team)) {
+      errors.push(`${where}: execution.team must be a list of { role, count? }`);
+    } else {
+      let sum = 0;
+      let summable = raw.team.length > 0;
+      raw.team.forEach((t, i) => {
+        if (!t || typeof t !== "object" || Array.isArray(t)) {
+          errors.push(`${where}: execution.team[${i}] must be a mapping { role, count? }`);
+          summable = false;
+          return;
+        }
+        if (!EXEC_ROLES.includes(t.role)) {
+          errors.push(`${where}: execution.team[${i}].role "${t.role}" invalid (one of ${EXEC_ROLES.join(" | ")})`);
+        }
+        if (t.count != null && (!Number.isInteger(t.count) || t.count < 1)) {
+          errors.push(`${where}: execution.team[${i}].count must be an integer ≥1`);
+          summable = false;
+        }
+        sum += t.count != null ? (Number.isInteger(t.count) ? t.count : 0) : 1;
+      });
+      // Head-count consistency: when BOTH a team and a concurrency are given, they must agree.
+      if (summable && Number.isInteger(raw.concurrency) && sum !== raw.concurrency) {
+        errors.push(`${where}: execution.team head-count (${sum}) is inconsistent with concurrency (${raw.concurrency})`);
+      }
+      if (raw.mode === "solo" && raw.team.length) {
+        warnings.push(`${where}: execution.mode is solo but a team is declared (a solo slice does not fan out)`);
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+// The IMPERATIVE directive lines for a slice — the single canonical block reused verbatim by
+// SLICES.md, `roadmap show`/`/slice`, and the kickoff brief. Returns null when no execution block.
+// Example (agent-team):
+//   ▶ EXECUTION: agent-team — 5 workers (1 verifier · 3 implementers · 1 reviewer).
+//     The touched files are disjoint. DO NOT run solo or fewer than 4. Invoke Agent Teams now (set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1).
+//     Rationale: 16 disjoint fault-class files; verifier-first; one reviewer reconciles.
+export function executionDirectiveLines(node) {
+  const exec = normalizeExecution(node && node.execution);
+  if (!exec) return null;
+
+  const mode = exec.mode || "subagents";
+  const suggested = suggestedConcurrency(node);
+  const workers = exec.concurrency ?? teamSize(exec.team) ?? suggested ?? (mode === "solo" ? 1 : null);
+  const floor = exec.minConcurrency ?? exec.concurrency ?? suggested ?? null;
+  const comp = composition(exec.team);
+  const lines = [];
+
+  // Line 1 — headline: mode + worker count + composition.
+  if (mode === "solo") {
+    lines.push(`▶ EXECUTION: solo — single agent, no fan-out.`);
+  } else {
+    const wk = workers != null ? `${workers} worker${workers === 1 ? "" : "s"}` : `worker count TBD`;
+    lines.push(`▶ EXECUTION: ${mode} — ${wk}${comp ? ` (${comp})` : ""}.`);
+  }
+
+  // Line 2 — the imperative instruction, per topology.
+  const floorClause = mode !== "solo" && floor != null ? ` DO NOT run solo or fewer than ${floor}.` : "";
+  if (mode === "agent-team") {
+    lines.push(`  The touched files are disjoint.${floorClause} Invoke Agent Teams now (set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1).`);
+  } else if (mode === "subagents") {
+    const n = workers != null ? `${workers} ` : "";
+    lines.push(`  Spawn ${n}background subagents per CLAUDE.md § Subagent Hand-off (disjoint files; the lead merges).${floorClause}`);
+  } else if (mode === "dynamic-workflow") {
+    lines.push(`  Run an in-slice pipeline — each step gates the next; do not collapse it to a single pass.${floorClause}`);
+  } else if (mode === "solo") {
+    lines.push(`  Single agent, no fan-out — atomic/exploratory/branching-sequential. Do not spawn workers.`);
+  }
+
+  if (exec.rationale) lines.push(`  Rationale: ${exec.rationale}`);
+  return lines;
+}
+
+// "1 verifier · 3 implementers · 1 reviewer" from a normalized team (null when none).
+export function composition(team) {
+  if (!team || !team.length) return null;
+  return team
+    .map((t) => {
+      const c = Number.isInteger(t.count) ? t.count : 1;
+      return `${c} ${t.role}${c === 1 ? "" : "s"}`;
+    })
+    .join(" · ");
+}
+
+// Keep only the wave nodes whose track matches `track` (case-insensitive). No-op when track
+// is falsy. Forward-compat with the three-track partition: a person fans out only their lane.
+export function filterByTrack(nodes, track) {
+  if (!track) return nodes;
+  const want = String(track).toLowerCase();
+  return nodes.filter((n) => n.track != null && String(n.track).toLowerCase() === want);
+}

package/scripts/lib/fanout-core.mjs

@@ -0,0 +1,39 @@
+// Pure launch decision for the fanout.
+// Default is to LAUNCH (interactive, watchable) — that matches the proven fanout pattern
+// and is low-risk (you're at the keyboard). Preview without spawning via --dry / --out.
+// Autonomous (headless claude -p that commits/pushes/PRs) is the only dangerous mode and
+// additionally requires the --yes-spawn-autonomous double-ack.
+export function launchDecision({ dry = false, out = null, autonomous = false, okAutonomous = false } = {}) {
+  if (out) return { spawn: false, mode: "wrote-script" };
+  if (dry) return { spawn: false, mode: "dry" };
+  if (autonomous && !okAutonomous) return { spawn: false, mode: "autonomous-needs-ack" };
+  return { spawn: true, mode: autonomous ? "autonomous" : "interactive" };
+}
+
+// Per-node launch-script fragments shared by fanout.mjs (waves) and grab.mjs (one backlog
+// item): the worktree-add-or-reuse line plus the .kickoff.md write, in bash and PowerShell
+// forms — so a quoting/format fix lands once, not in two scripts.
+export function bashWorktreeLines(wt, br, baseRef, brief) {
+  return [
+    `git worktree add "${wt}" -b "${br}" ${baseRef} 2>/dev/null || echo "worktree ${wt} exists, reusing"`,
+    `cat > "${wt}/.kickoff.md" <<'KICKOFF_EOF'`,
+    brief.trimEnd(),
+    `KICKOFF_EOF`,
+  ];
+}
+export function pwshWorktreeLines(wt, br, baseRef, brief) {
+  return [
+    `git worktree add "${wt}" -b "${br}" ${baseRef} 2>$null; if ($LASTEXITCODE -ne 0) { Write-Host "worktree ${wt} exists, reusing" }`,
+    `Set-Content -LiteralPath "${wt}/.kickoff.md" -Encoding utf8 -Value @'`,
+    brief.trimEnd(),
+    `'@`,
+  ];
+}
+
+// The disk hard-block refusal, shared by fan and grab.
+export function diskBlockLines(disk) {
+  return [
+    `✗ not enough disk for even one worktree: need ~${disk.perWorktreeGb.toFixed(1)}GB, ${disk.freeGb.toFixed(1)}GB free on the worktree volume.`,
+    `  Free space, point meta.worktree_root at a roomier volume, or calibrate meta.worktree_gb if the estimate is off.`,
+  ];
+}