@connorbritain/roadmap 0.3.0

package/scripts/dispatch.mjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+// roadmap dispatch <key> [--to claude-cloud|claude|codex|oz] — send a slice/backlog item to a
+// CLOUD agent instead of a local worktree. The wave-scale version is `roadmap fan --cloud`.
+//
+// Two transports:
+//   claude-cloud (RECOMMENDED) — fires a Claude Code cloud session directly via the Routines
+//     API (code.claude.com/docs/en/routines). Needs NO Linear at all; runs on the CURRENTLY
+//     AUTHED claude.ai account's plan limits (multi-account hot-swap via ~/.claude-routines.json
+//     keyed by account email — see docs/DEPLOYMENT.md § Cloud dispatch). BETA API: the fire
+//     endpoint ships under an experimental header and may change.
+//   claude|codex|oz — posts an @-mention capsule comment on the mapped Linear issue. The
+//     comment is live-verified; whether the mention SUMMONS an agent requires the agent's
+//     integration installed in the Linear workspace (Linear's native coding sessions are
+//     paid-plan-gated; the delegate-field mutation remains unverified).
+
+import { readFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { loadGraph, flatten, computeWaves, coherenceEnabled } from "./lib/graph.mjs";
+import { loadBacklog, roadmapPaths } from "./lib/store.mjs";
+import { runSync, postDispatchComment } from "./linear.mjs";
+import { linearState, linearStatusLine, machineFooter, normalizeLinearConfig } from "./lib/linear-core.mjs";
+import { outOfCycle } from "./lib/cycle-core.mjs";
+
+export const DISPATCH_AGENTS = { claude: "@Claude", codex: "@Codex", oz: "@Oz" };
+
+// ── claude-cloud transport ────────────────────────────────────────────────────
+// Resolve WHICH routine to fire (PURE — inputs injected). Precedence:
+//   1. CLAUDE_ROUTINE_TRIGGER + CLAUDE_ROUTINE_TOKEN env (explicit single-account / CI override)
+//   2. CLAUDE_ROUTINE_PROFILE env naming a profile in the routines file (manual pin)
+//   3. the profile whose `account` matches the CURRENTLY AUTHED claude.ai account email —
+//      this is the multi-account hot-swap: `claude /login` as someone else, next dispatch
+//      fires on their limits, no config change.
+// Within a profile: routines[<owner/repo>] wins over routines.default (routines are repo-bound).
+// `tier` selects an alternate routine variant keyed "<repo>#<tier>" (or "default#<tier>") —
+// e.g. a "fable" routine whose claude.ai model selector is set to the frontier tier for
+// slices that need judgment, not just execution. A requested tier that isn't configured
+// THROWS rather than silently downgrading: the slice asked for frontier intelligence, and a
+// quiet fallback to the standard tier is exactly the kind of silent failure that erodes trust.
+export function resolveRoutine({ env = {}, profiles = null, accountEmail = null, repoSlug = null, tier = null } = {}) {
+  if (env.CLAUDE_ROUTINE_TRIGGER && env.CLAUDE_ROUTINE_TOKEN) {
+    return { trigger: env.CLAUDE_ROUTINE_TRIGGER, token: env.CLAUDE_ROUTINE_TOKEN, source: "env" };
+  }
+  if (!profiles || !Object.keys(profiles).length) {
+    throw new Error("no claude-cloud routine configured — set CLAUDE_ROUTINE_TRIGGER + CLAUDE_ROUTINE_TOKEN, or create ~/.claude-routines.json (docs/DEPLOYMENT.md § Cloud dispatch)");
+  }
+  let label = env.CLAUDE_ROUTINE_PROFILE || null;
+  let entry = label ? profiles[label] : null;
+  if (label && !entry) throw new Error(`CLAUDE_ROUTINE_PROFILE "${label}" not in the routines file (profiles: ${Object.keys(profiles).join(", ")})`);
+  if (!entry) {
+    if (!accountEmail) throw new Error("couldn't detect the current claude.ai account (is the Claude CLI logged in?) — set CLAUDE_ROUTINE_PROFILE to pin a profile explicitly");
+    const found = Object.entries(profiles).find(([, p]) => p.account && String(p.account).toLowerCase() === accountEmail.toLowerCase());
+    if (!found) throw new Error(`no routines profile matches the authed claude.ai account ${accountEmail} (profiles: ${Object.keys(profiles).join(", ")}) — add one or set CLAUDE_ROUTINE_PROFILE`);
+    [label, entry] = found;
+  }
+  const routines = entry.routines || {};
+  if (tier) {
+    const rt = (repoSlug && routines[`${repoSlug}#${tier}`]) || routines[`default#${tier}`];
+    if (!rt || !rt.trigger || !rt.token) {
+      throw new Error(`profile "${label}" has no "${tier}"-tier routine for ${repoSlug || "(unknown repo)"} — add routines["${repoSlug || "owner/repo"}#${tier}"] (or routines["default#${tier}"]) { trigger, token }; a ${tier}-tier dispatch never silently falls back to the standard routine`);
+    }
+    return { trigger: rt.trigger, token: rt.token, source: `profile:${label}:${repoSlug && routines[`${repoSlug}#${tier}`] ? repoSlug : "default"}#${tier}`, account: entry.account };
+  }
+  const r = (repoSlug && routines[repoSlug]) || routines.default;
+  if (!r || !r.trigger || !r.token) {
+    throw new Error(`profile "${label}" has no routine for ${repoSlug || "(unknown repo)"} and no default — add routines["${repoSlug || "owner/repo"}"] or routines.default { trigger, token }`);
+  }
+  return { trigger: r.trigger, token: r.token, source: `profile:${label}${repoSlug && routines[repoSlug] ? `:${repoSlug}` : ":default"}`, account: entry.account };
+}
+
+// The currently AUTHED claude.ai account email (from the CLI's own config) — the hot-swap key.
+export function currentClaudeAccount(home = homedir()) {
+  try {
+    const j = JSON.parse(readFileSync(join(home, ".claude.json"), "utf8"));
+    return (j.oauthAccount && j.oauthAccount.emailAddress) || null;
+  } catch { return null; }
+}
+
+export function loadRoutineProfiles(env = process.env, home = homedir()) {
+  const p = env.CLAUDE_ROUTINES_FILE || join(home, ".claude-routines.json");
+  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; }
+}
+
+// owner/repo from the git remote — routines are repo-bound, so this keys the per-repo lookup.
+export function repoSlugOf(root) {
+  try {
+    const r = spawnSync("git", ["remote", "get-url", "origin"], { cwd: root, encoding: "utf8" });
+    const m = /github\.com[:/]([^/]+)\/([^/\s]+?)(?:\.git)?\s*$/.exec(r.stdout || "");
+    return m ? `${m[1]}/${m[2]}` : null;
+  } catch { return null; }
+}
+
+// Fire the routine (BETA endpoint — experimental header, shapes may change).
+// `trigger` accepts either the bare trig_… id OR the full endpoint URL exactly as
+// claude.ai's API-trigger modal shows it (the modal displays a URL, never a labeled id).
+export function routineEndpoint(trigger) {
+  if (/^https?:\/\//.test(trigger)) {
+    const t = trigger.replace(/\/+$/, "");
+    return t.endsWith("/fire") ? t : `${t}/fire`;
+  }
+  return `https://api.anthropic.com/v1/claude_code/routines/${trigger}/fire`;
+}
+
+export async function fireRoutine(routine, text, fetchImpl = fetch) {
+  const res = await fetchImpl(routineEndpoint(routine.trigger), {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${routine.token}`,
+      "anthropic-beta": "experimental-cc-routine-2026-04-01",
+      "anthropic-version": "2023-06-01",
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ text }),
+  });
+  if (!res.ok) {
+    const hint = res.status === 401 ? " — routine token invalid/expired (re-create the API trigger)"
+      : res.status === 404 ? " — trigger id wrong, routine deleted, or the beta shape changed" : "";
+    throw new Error(`routine fire HTTP ${res.status}${hint} (beta API — check code.claude.com/docs/en/routines)`);
+  }
+  return await res.json();   // { claude_code_session_id, claude_code_session_url }
+}
+
+export async function runDispatch(root, key, opts = {}) {
+  const env = opts.env || process.env;
+  const to = (opts.to || "claude-cloud").toLowerCase();
+  const io = { apiKey: env.LINEAR_API_KEY, fetchImpl: opts.fetchImpl || fetch };
+
+  const find = () => {
+    const graph = loadGraph(roadmapPaths(root).yaml);
+    const node = flatten(graph).nodes.find((n) => n.invoke === key);
+    if (node) return { type: "slice", identifier: node.linear, graph, status: node.status, tier: node.dispatchTier || null };
+    const item = ((loadBacklog(root) || {}).items || []).find((i) => i.id === key);
+    if (item) return { type: "backlog", identifier: item.linear, graph, tier: item.dispatch_tier || null };
+    return null;
+  };
+
+  let found = find();
+  if (!found) throw new Error(`no slice or backlog item "${key}"`);
+
+  // Cycle lock (slices only — backlog is erratic work by design, grab stays unguarded): with
+  // cycles on, out-of-cycle work doesn't dispatch. --force is the logged escape hatch; the
+  // launch surfaces as scope change on Linear's cycle graph either way.
+  if (found.type === "slice" && !opts.force && outOfCycle(normalizeLinearConfig(found.graph.meta || {}), found.status)) {
+    throw new Error(`'${key}' is out of the current cycle (status ${found.status}) — elect it first ('roadmap cycle plan', then 'roadmap cycle lock --promote ${key}'), or re-run with --force to override the cycle lock.`);
+  }
+
+  // ── claude-cloud: fire a Claude Code cloud session directly (NO Linear required) ──
+  if (to === "claude-cloud") {
+    // Tier precedence: explicit --tier beats the node's declared dispatch_tier (the human is
+    // overriding for this one launch); the node's field is the durable routing.
+    const tier = opts.tier || found.tier || null;
+    const routine = resolveRoutine({
+      env,
+      profiles: opts.profiles !== undefined ? opts.profiles : loadRoutineProfiles(env),
+      accountEmail: opts.accountEmail !== undefined ? opts.accountEmail : currentClaudeAccount(),
+      repoSlug: opts.repoSlug !== undefined ? opts.repoSlug : repoSlugOf(root),
+      tier,
+    });
+    const text = [
+      machineFooter({ type: found.type, key }, null),
+      "",
+      "This is a roadmap cloud dispatch. The repo is cloned for you. Open docs/SLICES.md#" + key +
+      " and the entry (including its prompt) in docs/roadmap/roadmap.yaml — the YAML is canonical." +
+      " Honor the verification gate before committing, then open a PR whose DESCRIPTION includes the exact line" +
+      ` 'roadmap: ${found.type}=${key}' (that line is how the roadmap reconciles cloud PRs). NEVER merge.` +
+      " Leftovers go to the BACKLOG ONLY — never new sprints or PIs (YAGNI applies to captures).",
+    ].join("\n");
+    const fired = await fireRoutine(routine, text, opts.fetchImpl || fetch);
+    const result = { dispatched: key, transport: "claude-cloud", routine: routine.source,
+      sessionId: fired.claude_code_session_id, sessionUrl: fired.claude_code_session_url };
+    // Board loop: when the node is Linear-mapped and we're authed, link the session on the
+    // issue. Best-effort — a failure here never fails the dispatch.
+    if (found.identifier && linearState({ meta: found.graph.meta, env }).authed) {
+      try {
+        await postDispatchComment(found.identifier, `Claude Code cloud session started for \`${key}\`: ${result.sessionUrl}`, io);
+        result.linearComment = found.identifier;
+      } catch { /* board link is a bonus, not a dependency */ }
+    }
+    return result;
+  }
+
+  const agent = DISPATCH_AGENTS[to];
+  if (!agent) throw new Error(`unknown dispatch target "${opts.to}" (claude-cloud | ${Object.keys(DISPATCH_AGENTS).join(" | ")})`);
+  const state = linearState({ meta: found.graph.meta, env });
+  if (!state.configured || !state.authed) throw new Error(linearStatusLine(state));
+
+  let pushed = false;
+  if (!found.identifier) {
+    await runSync(root, { pushOnly: true, env, fetchImpl: opts.fetchImpl });
+    pushed = true;
+    found = find();
+    if (!found.identifier) {
+      throw new Error(`push didn't map "${key}" to a Linear issue — check meta.linear.granularity (and per-PI overrides) covers it.`);
+    }
+  }
+
+  const body = [
+    `${agent} please work this issue.`,
+    "",
+    machineFooter({ type: found.type, key }, null),
+    "",
+    `Follow the repo's dispatch guidance (CLAUDE.md/AGENTS.md — 'Working a roadmap-dispatched Linear issue'). In short: the repo's docs/roadmap YAML is canonical, honor the slice's gate, open a PR whose description includes the line 'roadmap: ${found.type}=${key}', never merge, leftovers to the backlog only.`,
+  ].join("\n");
+
+  try {
+    await postDispatchComment(found.identifier, body, io);
+  } catch (e) {
+    throw new Error(`dispatch failed — tried: push-map (${pushed ? "pushed" : "already mapped"} → ${found.identifier}), commentCreate on ${found.identifier} (${e.message}). Delegate-field mutation not attempted (unverified).`);
+  }
+  return { dispatched: key, identifier: found.identifier, agent, pushed };
+}
+
+// Conduct a cloud fanout of one ready wave — the worktree-free, disk-free fanout that lets a
+// local session orchestrate cloud workers. PREVIEW unless opts.confirm (firing spends plan
+// usage + opens PRs). Cloud has no machine ceiling, so the cap defaults to the review ceiling
+// (a human still merges) — mirrors `fan --cloud`. opts.dispatch is forwarded to each
+// runDispatch (transport injection for tests).
+export async function runFanCloud(root, opts = {}) {
+  const graph = loadGraph(roadmapPaths(root).yaml);
+  const cap = opts.cap || 5;
+  const { waves } = computeWaves(flatten(graph), cap, { coherence: coherenceEnabled(graph.meta) });
+  const waveIdx = opts.wave || 1;
+  let wave = waves[waveIdx - 1] || [];
+  // Cycle lock at wave scale: out-of-cycle slices drop from the launch selection (reported,
+  // never silent — a silent cap reads as "covered everything"). opts.all includes them anyway.
+  // computeWaves itself stays untouched: the wave math is shared planning, the lock is a launch gate.
+  const cfg = normalizeLinearConfig(graph.meta || {});
+  let excluded = [];
+  if (!opts.all) {
+    excluded = wave.filter((n) => outOfCycle(cfg, n.status)).map((n) => n.invoke);
+    if (excluded.length) wave = wave.filter((n) => !outOfCycle(cfg, n.status));
+  }
+  const slices = wave.map((n) => n.invoke);
+  if (!opts.confirm) {
+    // Read-only pre-flight: resolve each slice's routine (its dispatch_tier against the
+    // active profile) WITHOUT firing, so a wave that would burn N frontier launches shows
+    // its unresolvable slices before confirm instead of failing them mid-wave. Resolution
+    // failures are captured per-slice — the whole point is showing them, never throwing.
+    const d = opts.dispatch || {};
+    const envv = d.env || opts.env || process.env;
+    const profiles = d.profiles !== undefined ? d.profiles : loadRoutineProfiles(envv);
+    const accountEmail = d.accountEmail !== undefined ? d.accountEmail : currentClaudeAccount();
+    const repoSlug = d.repoSlug !== undefined ? d.repoSlug : repoSlugOf(root);
+    const byTier = new Map();
+    const preflight = (tier) => {
+      if (!byTier.has(tier)) {
+        try { resolveRoutine({ env: envv, profiles, accountEmail, repoSlug, tier }); byTier.set(tier, { resolvable: true }); }
+        catch (e) { byTier.set(tier, { resolvable: false, error: e.message }); }
+      }
+      return byTier.get(tier);
+    };
+    const detail = wave.map((nd) => {
+      const tier = nd.dispatchTier || null;
+      const pf = preflight(tier);
+      return { invoke: nd.invoke, tier, resolvable: pf.resolvable, ...(pf.error ? { error: pf.error } : {}) };
+    });
+    const unresolvable = detail.filter((s) => !s.resolvable).map((s) => s.invoke);
+    return { preview: true, wave: waveIdx, cap, slices: detail,
+      ...(excluded.length ? { excludedOutOfCycle: excluded } : {}),
+      note: `${detail.length} slice(s) would each fire a cloud session on the authed claude.ai account and open a PR.${unresolvable.length ? ` ${unresolvable.length} slice(s) CANNOT resolve their routine (${unresolvable.join(", ")}) — fix ~/.claude-routines.json or their dispatch_tier before confirming.` : ""}${excluded.length ? ` ${excluded.length} out-of-cycle slice(s) excluded (${excluded.join(", ")}) — elect them or pass all=true.` : ""} Re-call with confirm=true to fire.` };
+  }
+  const results = [];
+  for (const invoke of slices) {
+    // force: the fan-level filter above IS the cycle gate (and opts.all is an explicit human
+    // include) — re-guarding per dispatch would veto what the wave already admitted.
+    try { const r = await runDispatch(root, invoke, { ...(opts.dispatch || {}), force: true }); results.push({ slice: invoke, ok: true, sessionUrl: r.sessionUrl }); }
+    catch (e) { results.push({ slice: invoke, ok: false, error: e.message }); }
+  }
+  return { fired: results.filter((r) => r.ok).length, of: slices.length, wave: waveIdx, ...(excluded.length ? { excludedOutOfCycle: excluded } : {}), results };
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const args = process.argv.slice(2);
+  const val = (n) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : undefined; };
+  const key = args.find((a) => !a.startsWith("-"));
+  if (!key) {
+    console.error(`usage: roadmap dispatch <slice-invoke|backlog-id> [--to claude-cloud|${Object.keys(DISPATCH_AGENTS).join("|")}]   (default claude-cloud)`);
+    process.exit(2);
+  }
+  try {
+    const r = await runDispatch(process.cwd(), key, { to: val("--to"), force: args.includes("--force"), tier: val("--tier") });
+    if (r.transport === "claude-cloud") {
+      console.log(`dispatched ${r.dispatched} → Claude Code cloud session (${r.routine}).`);
+      console.log(`session: ${r.sessionUrl}`);
+      if (r.linearComment) console.log(`board:   session link commented on ${r.linearComment}`);
+      console.log(`(beta Routines API — if shapes change, check code.claude.com/docs/en/routines)`);
+    } else {
+      console.log(`dispatched ${r.dispatched} → ${r.identifier} via ${r.agent} @-mention comment.`);
+      console.log(`VERIFY the agent picked it up. Live-tested finding: the comment posts fine, but summoning requires the agent's`);
+      console.log(`integration to be INSTALLED in the Linear workspace (Linear's native coding sessions are paid-plan-gated);`);
+      console.log(`without it there is nothing to summon. If installed and nothing happens, delegate by hand — the capsule`);
+      console.log(`comment is already on the issue to orient the agent.`);
+    }
+  } catch (e) {
+    console.error(`✗ ${e.message}`);
+    process.exit(1);
+  }
+}

package/scripts/estimate.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// roadmap estimate — bridges agent-time's estimator.py into the roadmap.
+//   roadmap estimate <slice> [--force]      estimate one slice (skips if already estimated)
+//   roadmap estimate --all [--force]        estimate every classified, un-estimated slice
+//   roadmap estimate timeline [--now DATE]  roll durations up into projected_target_date per PI
+//   roadmap estimate log <slice> --status … log a completed slice's outcome → agent-time calibration
+// The brain is lib/estimate-core.mjs (pure). This layer resolves the engine, spawns python
+// (injectable for tests), and writes the est_minutes block back via lib/store.mjs.
+
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadGraph } from "./lib/graph.mjs";
+import { mutateRoadmap, roadmapPaths } from "./lib/store.mjs";
+import { setFields } from "./lib/mcp-core.mjs";
+import { estimationConfig, estimateArgs, parseEstimateRecord, applyEstimate, timelinePlan, logArgs, alreadyLogged, LOG_STATUSES } from "./lib/estimate-core.mjs";
+
+// Resolve estimator.py: explicit meta.estimation.engine → $AGENT_TIME_ENGINE → the installed skill.
+export function resolveEngine(cfg, env = process.env, exists = existsSync) {
+  const cands = [cfg && cfg.engine, env.AGENT_TIME_ENGINE,
+    join(homedir(), ".claude", "skills", "agent-time-estimator", "estimator.py")].filter(Boolean);
+  for (const c of cands) if (exists(c)) return c;
+  throw new Error(
+    "agent-time estimator not found. Install the agent-time-estimator skill, set $AGENT_TIME_ENGINE, " +
+    "or set meta.estimation.engine to the path of estimator.py."
+  );
+}
+
+// Default runner: spawn python, return spawnSync's { status, stdout, stderr, error }.
+// python3 → python fallback for Windows boxes without the python3 shim. PYTHONIOENCODING
+// forces UTF-8 stdout — the estimator prints →/× and Python otherwise defaults to the
+// Windows cp1252 codec on a non-console pipe and crashes on encode.
+function spawnEstimator(python, engine, args, cwd) {
+  const opts = { cwd, encoding: "utf8", env: { ...process.env, PYTHONIOENCODING: "utf-8" } };
+  const r = spawnSync(python, [engine, ...args], opts);
+  if (r.error && r.error.code === "ENOENT" && python === "python3") {
+    return spawnSync("python", [engine, ...args], opts);
+  }
+  return r;
+}
+
+// Estimate selected slices. opts: { invoke?, all?, force?, runEstimator? }. runEstimator(args,{cwd})
+// is injectable (default = real spawn) and returns { status, stdout, stderr }. The python calls
+// happen here (IO); a single transactional mutateRoadmap writes every successful estimate back.
+// Returns { estimated, skipped, errors }.
+export function runEstimate(root, opts = {}) {
+  const graph = loadGraph(roadmapPaths(root).yaml);
+  const cfg = estimationConfig(graph.meta || {});
+  const run = opts.runEstimator || (() => { const e = resolveEngine(cfg); return (args, o) => spawnEstimator(cfg.python, e, args, o.cwd); })();
+
+  const all = [];
+  for (const pi of graph.pis || []) for (const sp of pi.sprints || []) all.push(sp);
+  let targets;
+  if (opts.invoke) {
+    const sp = all.find((s) => s.invoke === opts.invoke);
+    if (!sp) throw new Error(`no slice "${opts.invoke}"`);
+    targets = [sp];
+  } else if (opts.all) {
+    targets = all.filter((s) => s.shape);   // only classified slices are candidates
+  } else {
+    throw new Error("estimate needs a slice invoke key or --all");
+  }
+
+  const estimated = [], skipped = [], errors = [];
+  const blocks = {};   // invoke -> estimate block
+  for (const sp of targets) {
+    if (!sp.shape) { skipped.push({ invoke: sp.invoke, why: "no shape" }); continue; }
+    if (sp.estimate && !opts.force) { skipped.push({ invoke: sp.invoke, why: "already estimated (use --force)" }); continue; }
+    let args;
+    try { args = estimateArgs(sp, cfg); } catch (e) { errors.push({ invoke: sp.invoke, error: e.message }); continue; }
+    const r = run(args, { cwd: root });
+    if (!r || r.status !== 0) {
+      const detail = (r && (r.stderr || (r.error && r.error.message))) || "";
+      errors.push({ invoke: sp.invoke, error: `estimator exited ${r ? r.status : "?"}: ${String(detail).trim().slice(0, 200)}` });
+      continue;
+    }
+    try { blocks[sp.invoke] = applyEstimate(parseEstimateRecord(r.stdout)); }
+    catch (e) { errors.push({ invoke: sp.invoke, error: e.message }); continue; }
+    const b = blocks[sp.invoke];
+    estimated.push({ invoke: sp.invoke, minutes: b.minutes, confidence: b.confidence });
+  }
+
+  if (Object.keys(blocks).length) {
+    // One validate + write for the whole batch; a throw leaves the YAML untouched.
+    mutateRoadmap(root, (doc) => {
+      for (const [invoke, block] of Object.entries(blocks)) setFields(doc, { invoke, fields: { estimate: block } });
+      return { estimated: Object.keys(blocks) };
+    });
+  }
+  return { estimated, skipped, errors };
+}
+
+// Roll the per-slice estimates up into a projected_target_date per PI and write it back (never
+// touching an explicit target_date — a separate field, so the commitment always wins). Only PIs
+// whose projection changed are written. `now` is injectable for deterministic tests. Returns the
+// plan plus `changed` (the PI ids whose projected_target_date moved).
+export function runTimeline(root, opts = {}) {
+  const graph = loadGraph(roadmapPaths(root).yaml);
+  const now = opts.now || new Date().toISOString();
+  const plan = timelinePlan(graph, { now, concurrency: opts.concurrency });
+  const wanted = new Map(plan.pis.map((p) => [p.pi, p.projected_target_date]));
+  const changed = [];
+  for (const pi of graph.pis || []) {
+    const cur = pi.projected_target_date || null;
+    const want = wanted.has(pi.id) ? wanted.get(pi.id) : null;
+    if (cur !== want) changed.push(pi.id);
+  }
+  if (changed.length) {
+    mutateRoadmap(root, (doc) => {
+      const items = (doc.get("pis") || {}).items || [];
+      for (let i = 0; i < items.length; i++) {
+        const id = String(items[i].get("id"));
+        const want = wanted.has(id) ? wanted.get(id) : null;
+        if (want) doc.setIn(["pis", i, "projected_target_date"], want);
+        else if (items[i].get("projected_target_date") != null) doc.deleteIn(["pis", i, "projected_target_date"]);
+      }
+      return { projected: plan.pis.length };
+    });
+  }
+  return { ...plan, changed };
+}
+
+// agent-time's history path for this repo — same resolution the estimator uses when spawned with
+// cwd=root (<root>/.claude/agent-time/history.jsonl), or $AGENT_TIME_DATA. Used only for idempotency.
+export function resolveHistory(root, env = process.env) {
+  return env.AGENT_TIME_DATA || join(root, ".claude", "agent-time", "history.jsonl");
+}
+
+// Log a completed slice's outcome to agent-time so its estimates self-correct (the calibration loop).
+// Idempotent per task_id via agent-time's own history — re-firing (e.g. the Stop hook on every session
+// end) never double-counts. Best-effort on the spawn: a failure is returned, never thrown through.
+// opts: { invoke, status?, force?, actualMinutes?, actualRounds?, runEstimator? }.
+export function runLog(root, opts = {}) {
+  const graph = loadGraph(roadmapPaths(root).yaml);
+  const cfg = estimationConfig(graph.meta || {});
+  let sprint = null;
+  for (const pi of graph.pis || []) for (const sp of pi.sprints || []) if (sp.invoke === opts.invoke) sprint = sp;
+  if (!sprint) throw new Error(`no slice "${opts.invoke}"`);
+  const status = opts.status || "pass";
+  const args = logArgs(sprint, status, { actualMinutes: opts.actualMinutes, actualRounds: opts.actualRounds });   // throws if not estimated
+
+  const histPath = resolveHistory(root);
+  if (!opts.force && existsSync(histPath) && alreadyLogged(readFileSync(histPath, "utf8"), sprint.estimate.task_id)) {
+    return { skipped: true, invoke: opts.invoke, reason: "already calibrated (use --force)" };
+  }
+  const run = opts.runEstimator || (() => { const e = resolveEngine(cfg); return (a, o) => spawnEstimator(cfg.python, e, a, o.cwd); })();
+  const r = run(args, { cwd: root });
+  if (!r || r.status !== 0) {
+    const detail = (r && (r.stderr || (r.error && r.error.message))) || "";
+    return { error: `estimator log exited ${r ? r.status : "?"}: ${String(detail).trim().slice(0, 200)}`, invoke: opts.invoke };
+  }
+  return { invoke: opts.invoke, logged: true, status, task_id: sprint.estimate.task_id };
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const args = process.argv.slice(2);
+  const has = (n) => args.includes(n);
+  const val = (n) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : undefined; };
+  const positional = args.filter((a) => !a.startsWith("-"));
+  const sub = positional[0];
+  const root = process.cwd();
+  try {
+    if (sub === "timeline") {
+      const nowArg = val("--now");
+      const r = runTimeline(root, nowArg ? { now: nowArg } : {});
+      console.log(`timeline: anchored ${r.anchor} · ${r.concurrency}-wide · ${r.point} · ${r.hoursPerDay}h/day`);
+      for (const p of r.pis) console.log(`  ${p.pi} → ${p.projected_target_date}`);
+      console.log(r.changed.length ? `projected_target_date updated on ${r.changed.length} PI(s): ${r.changed.join(", ")}` : "projected_target_date: already current (no change).");
+      if (r.unpriced.length) console.log(`unpriced (no estimate — 0 span, run 'roadmap estimate --all'): ${[...new Set(r.unpriced)].join(", ")}`);
+      if (r.held.length) console.log(`held (blocked / gated — not scheduled, excluded): ${r.held.join(", ")}`);
+      process.exit(0);
+    }
+    if (sub === "log") {
+      const invoke = positional[1];
+      if (!invoke) { console.error(`usage: roadmap estimate log <slice> [--status ${LOG_STATUSES.join("|")}] [--actual-rounds N] [--actual-minutes M] [--force]`); process.exit(2); }
+      const ar = val("--actual-rounds"), am = val("--actual-minutes");
+      const r = runLog(root, { invoke, status: val("--status"), force: has("--force"),
+        actualRounds: ar != null ? Number(ar) : undefined, actualMinutes: am != null ? Number(am) : undefined });
+      if (r.skipped) console.log(`- ${r.invoke}: ${r.reason}`);
+      else if (r.error) { console.error(`✗ ${r.invoke}: ${r.error}`); process.exit(1); }
+      else console.log(`✓ ${r.invoke}: outcome logged (${r.status}) → agent-time calibration updated.`);
+      process.exit(0);
+    }
+    const opts = { force: has("--force") };
+    if (has("--all")) opts.all = true;
+    else if (sub) opts.invoke = sub;
+    else { console.error("usage: roadmap estimate <slice> [--force] | roadmap estimate --all [--force]"); process.exit(2); }
+    const r = runEstimate(root, opts);
+    for (const e of r.estimated) console.log(`✓ ${e.invoke}: ${e.minutes.expected} min (≈ ${e.minutes.low}–${e.minutes.high}) · ${e.confidence}`);
+    for (const s of r.skipped) console.log(`- ${s.invoke} skipped (${s.why})`);
+    for (const x of r.errors) console.error(`✗ ${x.invoke}: ${x.error}`);
+    if (!r.estimated.length && r.errors.length) process.exit(1);
+  } catch (e) {
+    console.error(`✗ ${e.message}`);
+    process.exit(1);
+  }
+}