@connorbritain/roadmap 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@connorbritain/roadmap",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Roadmap + backlog graph with prioritized, deterministic multi-session fanout. YAML canonical, SLICES.md/BACKLOG.md generated.",
   "type": "module",
   "private": false,

package/schema/backlog.schema.json

@@ -58,7 +58,19 @@
         "dispatch_tier": { "type": "string", "description": "Cloud-dispatch routine tier for this item (e.g. 'fable'). Dispatch resolves routines[\"<owner/repo>#<tier>\"] (or \"default#<tier>\") from ~/.claude-routines.json and THROWS if the tier isn't configured — never a silent fallback to the standard routine. Absent: the standard repo routine. CLI --tier overrides per launch." },
         "prs": { "type": "array", "items": { "type": "string" } },
         "completed_on": { "type": "string", "description": "ISO date the item closed (done/dropped)" },
-        "promoted_to": { "type": "string", "description": "pi-id/sprint-id nodeKey written by promote; the back-link to the roadmap" }
+        "promoted_to": { "type": "string", "description": "pi-id/sprint-id nodeKey written by promote; the back-link to the roadmap" },
+        "receipts": {
+          "type": "object", "additionalProperties": false,
+          "description": "Optional completion evidence — same shape as a slice's receipts; each value is a PR#, path, url, or note. Carried by grab-launched work.",
+          "properties": {
+            "build": { "type": "string" },
+            "test": { "type": "string" },
+            "clone_install": { "type": "string" },
+            "screenshot": { "type": "string" },
+            "signoff": { "type": "string" },
+            "publish": { "type": "string" }
+          }
+        }
       }
     }
   }

package/schema/roadmap.schema.json

@@ -112,7 +112,8 @@
           "properties": {
             "capture_ratio": { "type": "number", "exclusiveMinimum": 0, "default": 2, "description": "Max (captured backlog items + added sprints) per completed slice per review window before the sprawl warning fires" },
             "pi_min_slices": { "type": "integer", "minimum": 1, "description": "Composition floor: validate warns (one aggregated line) when a non-complete PI holds fewer slices than this. A PI under ~3 slices is usually a slice wearing a PI's coat — fold it into a sibling or grow it. Absent → off." },
-            "coherence": { "type": "boolean", "default": true, "description": "Wave-packing coherence: prefer finishing started PIs over opening fresh ones (strictly below declared priority). false restores pure priority/status/est ordering." }
+            "coherence": { "type": "boolean", "default": true, "description": "Wave-packing coherence: prefer finishing started PIs over opening fresh ones (strictly below declared priority). false restores pure priority/status/est ordering." },
+            "required_receipts": { "type": "array", "items": { "enum": ["build", "test", "clone_install", "screenshot", "signoff", "publish"] }, "description": "Finishing-discipline knob: receipt keys a slice MUST carry once complete. A complete slice missing any listed key WARNS (opt-in — absent → off)." }
           }
         },
         "last_review": {
@@ -232,7 +233,20 @@
         "prompt": { "type": "string", "description": "Author-stashed pickup instructions, embedded VERBATIM in the synthesized kickoff brief and shown by /slice and roadmap show. Update as new info comes in (set_fields / roadmap set)." },
         "milestone": { "type": "string", "description": "Optional stage name within the PI's Linear project (e.g. 'harness', 'hardening', 'ship'). Sync creates the distinct milestones per project and attaches this slice's issue — turning a project's flat issue list into legible stages. Project-scoped: the same name under two PIs is two milestones. Opt-in; absent everywhere → no milestone sync." },
         "dispatch_tier": { "type": "string", "description": "Cloud-dispatch routine tier for this slice (e.g. 'fable' = a routine whose claude.ai model selector is set to the frontier tier). Dispatch resolves routines[\"<owner/repo>#<tier>\"] (or \"default#<tier>\") from ~/.claude-routines.json and THROWS if the tier isn't configured — a frontier slice never silently falls back to the standard routine. Absent: the standard repo routine. CLI --tier overrides per launch." },
-        "linear": { "type": "string", "description": "Linear issue identifier (e.g. ABC-123) this slice maps to — written back by the first push. The {linear} branch_convention token uses it so Linear auto-links the PR." }
+        "linear": { "type": "string", "description": "Linear issue identifier (e.g. ABC-123) this slice maps to — written back by the first push. The {linear} branch_convention token uses it so Linear auto-links the PR." },
+        "receipts": {
+          "type": "object", "additionalProperties": false,
+          "description": "Optional per-slice completion evidence — each value is a PR#, path, url, or note proving a finishing step actually happened. Opt-in enforcement: list keys in meta.discipline.required_receipts and a complete slice missing one WARNS. Absent → no-op.",
+          "properties": {
+            "build": { "type": "string" },
+            "test": { "type": "string" },
+            "clone_install": { "type": "string" },
+            "screenshot": { "type": "string" },
+            "signoff": { "type": "string" },
+            "publish": { "type": "string" }
+          }
+        },
+        "outcome": { "type": "string", "description": "Optional founder-review outcome this slice rolls up into — sibling slices sharing a name group into one OUTCOME line in SLICES.md summarizing their done-state. Absent → no rollup." }
       }
     },
     "priority": {

package/scripts/cli.mjs

@@ -39,10 +39,12 @@ COMMANDS
   mcp             run the MCP server (stdio); read + mutate tools over JSON-RPC
   watch           watch fanout PRs and print a line as each lands (lead notifications)
   review          date-anchored review digest: what shipped vs what grew since meta.last_review
+  doctor          reconcile the roadmap against reality (merged PRs, docs, Linear, worktrees,
+                  structure) and report drift — read-only; exits non-zero when drift is found
   linear          optional Linear sync: status [--probe] | auth | setup --team KEY | provision | sync [--dry]
                   | note <key> "<text>" [--kind progress|blocker|done] | notes <key> | post-update
-  init            create a minimal roadmap or configure portable assistant profiles
-  assistant       list | configure | doctor local assistant profiles
+  init            create a minimal roadmap or configure portable assistant profiles
+  assistant       list | configure | doctor local assistant profiles
   help            this help
 
 OPTIONS (short | long)
@@ -69,12 +71,12 @@ OPTIONS (short | long)
                                 bypassPermissions = skip ALL prompts (avoid). Tip: a committed
                                 .claude/settings.json permissions.allow is inherited by every
                                 worktree. The launch prompt steers the worker to plan + wait first.
-  -lc | --lead-claude           fan: make the lead pane a Claude coordinator (reviews PRs + merges;
+  -lc | --lead-claude           fan: make the lead pane a Claude coordinator (reviews PRs + merges;
                                 it can't see workers' context, but observes via gh/git)
        --worktree-root <dir>    fan: override the worktree parent dir
-       --review-ceiling N       plan/fan: human review cap (default 5)
-       --assistant <name>       fan: manual | claude | codex | custom profile (manual is default)
-       --launch                 fan: explicitly launch a locally authorized assistant profile
+       --review-ceiling N       plan/fan: human review cap (default 5)
+       --assistant <name>       fan: manual | claude | codex | custom profile (manual is default)
+       --launch                 fan: explicitly launch a locally authorized assistant profile
 
 EXAMPLES
   roadmap                            # where am I / what's runnable
@@ -112,8 +114,8 @@ if (action.kind === "notyet") {
 }
 if (action.kind === "unknown") { console.error(`roadmap: unknown command "${cmd}".\n\n${HELP}`); process.exit(2); }
 
-const root = findRepoRoot(process.cwd());
-if (!root && cmd !== "init") { console.error(missingRoadmapHelp(process.cwd())); process.exit(2); }
-
-const r = spawnSync("node", [join(SCRIPTS, action.script), ...buildArgs(cmd, expandShort(rest))], { stdio: "inherit", cwd: root || process.cwd() });
+const root = findRepoRoot(process.cwd());
+if (!root && cmd !== "init") { console.error(missingRoadmapHelp(process.cwd())); process.exit(2); }
+
+const r = spawnSync("node", [join(SCRIPTS, action.script), ...buildArgs(cmd, expandShort(rest))], { stdio: "inherit", cwd: root || process.cwd() });
 process.exit(r.status ?? 0);

package/scripts/doctor.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// roadmap doctor — reconcile the roadmap against reality and report DRIFT. READ-ONLY: it never
+// writes the YAML, the docs, or Linear. It gathers merged PRs, open PRs, fanout worktrees, a
+// rendered-vs-disk doc diff, and the Linear pull deltas, then lib/doctor-core.mjs classifies
+// them. Every gatherer is guarded: gh/git/Linear missing or slow → that section degrades to
+// empty (like the SessionStart hook), so doctor stays fast and never throws on a bare checkout.
+// Usage: roadmap doctor [--json]   (--json like review.mjs; exits 1 when drift is found.)
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadGraph } from "./lib/graph.mjs";
+import { loadBacklog, roadmapPaths, slicesRenderOpts } from "./lib/store.mjs";
+import { renderMarkdown } from "./lib/render-core.mjs";
+import { renderBacklogMarkdown } from "./lib/backlog-core.mjs";
+import { mergedPrs, allPrs, worktrees } from "./lib/external-state.mjs";
+import { doctorReport } from "./lib/doctor-core.mjs";
+
+const root = process.cwd();
+const args = process.argv.slice(2);
+
+// The merged-PR / open-PR / fanout-worktree probes are the shared, guarded gatherers in
+// external-state.mjs (imported above). Only the two doctor-specific reads live here:
+
+// Generated docs whose on-disk bytes differ from a fresh render. Line endings are normalized
+// (renderMarkdown emits LF; a Windows checkout may hold CRLF) so a checkout-style newline
+// difference never masquerades as content drift. A MISSING generated doc counts as stale — a
+// roadmap with content but no rendered catalog is drift the same 'roadmap render' fixes.
+function staleDocs(graph, backlog) {
+  const stale = [];
+  const norm = (s) => s.replace(/\r\n/g, "\n");
+  const check = (rel, rendered) => {
+    let disk = null;
+    try { disk = readFileSync(join(root, rel), "utf8"); } catch { /* missing/unreadable → below */ }
+    if (disk == null || norm(disk) !== norm(rendered)) stale.push(rel);
+  };
+  try { check("docs/SLICES.md", renderMarkdown(graph, slicesRenderOpts(root, backlog))); } catch { /* render failure → skip */ }
+  if (backlog) { try { check("docs/BACKLOG.md", renderBacklogMarkdown(backlog)); } catch { /* skip */ } }
+  return { staleDocs: stale };
+}
+
+// Linear pull deltas (dry, pull-only → zero writes). null when Linear is off/unauthed/unreachable,
+// which doctor-core reads as "skip the Linear section".
+async function linearDeltas() {
+  try {
+    const { runSync } = await import("./linear.mjs");
+    const r = await runSync(root, { dry: true, pullOnly: true });
+    return (r.proposals && r.proposals.deltas) || null;
+  } catch { return null; }
+}
+
+// ── run ──────────────────────────────────────────────────────────────────────
+let graph;
+try {
+  graph = loadGraph(roadmapPaths(root).yaml);
+} catch (e) {
+  console.error(`✗ could not load the roadmap: ${e.message}`);
+  process.exit(2);
+}
+const backlog = loadBacklog(root);
+
+const report = doctorReport({
+  graph,
+  backlog,
+  mergedPrs: mergedPrs(root),
+  allPrs: allPrs(root) || [],
+  worktrees: worktrees(root, graph.meta || {}),
+  renderedVsDisk: staleDocs(graph, backlog),
+  linearDeltas: await linearDeltas(),
+});
+
+if (args.includes("--json")) {
+  process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+  process.exit(report.driftCount ? 1 : 0);
+}
+
+if (!report.driftCount) {
+  console.log("✓ no drift — the roadmap matches reality (merged PRs, docs, Linear, worktrees, structure).");
+  process.exit(0);
+}
+console.log(`roadmap doctor — ${report.driftCount} drift signal(s):\n`);
+for (const s of report.sections) {
+  console.log(`${s.title} (${s.items.length}):`);
+  for (const item of s.items) console.log(`  • ${item}`);
+  console.log("");
+}
+console.log("Read-only — nothing was changed. Reconcile with /sync, 'roadmap render', or the set tools.");
+process.exit(1);

package/scripts/fanout.mjs

@@ -19,12 +19,12 @@ import os from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadGraph, flatten, computeWaves, readyNodes, coherenceEnabled } from "./lib/graph.mjs";
-import { recommendConcurrency, probeDisk } from "./lib/recommend.mjs";
+import { recommendConcurrency, probeDisk, probeReviewDebt } from "./lib/recommend.mjs";
 import { synthesizeBrief, branchFor, worktreeFor, launchPrompt, baseRefOf, remoteOf, agentCmdFor } from "./lib/brief.mjs";
 import { launchDecision, bashWorktreeLines, pwshWorktreeLines, diskBlockLines } from "./lib/fanout-core.mjs";
 import { terminalChoices } from "./lib/wizard-core.mjs";
-import { filterByTrack } from "./lib/execution.mjs";
-import { readLocalConfig, resolveProfile, commandFor, launchDecisionForProfile } from "./lib/assistant-core.mjs";
+import { filterByTrack } from "./lib/execution.mjs";
+import { readLocalConfig, resolveProfile, commandFor, launchDecisionForProfile } from "./lib/assistant-core.mjs";
 
 const args = process.argv.slice(2);
 const val = (n, d) => { const i = args.indexOf(n); return i >= 0 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : d; };
@@ -37,9 +37,9 @@ const lane = val("--lane", "max");              // max (subscription) | api (ANT
 const autonomous = has("--autonomous");          // headless claude -p (else interactive, watchable)
 const dry = has("--dry") || has("--print");      // preview only — launch is the DEFAULT
 const okAutonomous = has("--yes-spawn-autonomous");
-const leadClaude = has("--lead-claude");         // launch claude in the lead pane (else a shell)
-const requestedAssistant = val("--assistant", null);
-const requestedLaunch = has("--launch");
+const leadClaude = has("--lead-claude");         // launch claude in the lead pane (else a shell)
+const requestedAssistant = val("--assistant", null);
+const requestedLaunch = has("--launch");
 const outFile = val("--out", null);
 // The lead pane's claude prompt (only with --lead-claude). It coordinates; it cannot see the
 // workers' context (separate processes) but observes their PRs/branches and merges.
@@ -53,9 +53,9 @@ const model = flatten(graph);
 // Windows → Windows Terminal tabs; elsewhere → tmux panes. terminalChoices() owns that rule.
 const term = val("--term", (graph.meta && graph.meta.terminal) || terminalChoices(os.platform())[0]);
 // Worker permission mode: flag > meta.worker_mode > 'plan'. The lead session uses the same mode.
-const workerMode = val("--worker-mode", (graph.meta && graph.meta.worker_mode) || "plan");
-const { config: localConfig } = readLocalConfig(process.cwd());
-const profile = resolveProfile(graph, localConfig, requestedAssistant);
+const workerMode = val("--worker-mode", (graph.meta && graph.meta.worker_mode) || "plan");
+const { config: localConfig } = readLocalConfig(process.cwd());
+const profile = resolveProfile(graph, localConfig, requestedAssistant);
 
 // ── cloud fanout: dispatch the wave to CLOUD agents via Linear instead of local worktrees.
 // Placed BEFORE all worktree/disk/terminal logic on purpose — no disk ceiling, no checkout:
@@ -78,7 +78,12 @@ if (has("--cloud")) {
 }
 
 const ready = readyNodes(model);
-const rec = recommendConcurrency(ready, graph, { reviewCeiling: Number(val("--review-ceiling", 5)), disk: probeDisk(graph) });
+const rec = recommendConcurrency(ready, graph, {
+  reviewCeiling: Number(val("--review-ceiling", 5)),
+  reviewDebt: probeReviewDebt(process.cwd(), graph),
+  today: new Date().toISOString().slice(0, 10),
+  disk: probeDisk(graph),
+});
 // Disk hard-block: auto-dialing handles the soft path (recommended >= 1), but when even ONE
 // worktree won't fit, launching would fail mid-checkout — refuse before creating anything.
 if (rec.disk && rec.disk.cap < 1) {
@@ -102,13 +107,13 @@ if (!wave.length) {
 
 // claude invocation per session. Interactive workers START IN PLAN MODE (--permission-mode
 // plan) so each plans its slice before touching anything; autonomous workers run headless.
-function claudeCmd(node) {
-  const prompt = launchPrompt(node);
-  if (profile.name === "manual") return `echo "${node.invoke}: worktree and .kickoff.md ready; start your configured assistant here."`;
-  // meta.agent_cmd remains the legacy Claude compatibility path. New local profiles win.
-  const base = profile.command
-    ? commandFor(profile, { prompt, mode: autonomous ? "acceptEdits" : workerMode })
-    : agentCmdFor(graph, { prompt, mode: workerMode });
+function claudeCmd(node) {
+  const prompt = launchPrompt(node);
+  if (profile.name === "manual") return `echo "${node.invoke}: worktree and .kickoff.md ready; start your configured assistant here."`;
+  // meta.agent_cmd remains the legacy Claude compatibility path. New local profiles win.
+  const base = profile.command
+    ? commandFor(profile, { prompt, mode: autonomous ? "acceptEdits" : workerMode })
+    : agentCmdFor(graph, { prompt, mode: workerMode });
   const withLane = lane === "api"
     ? `ANTHROPIC_API_KEY="$ROADMAP_API_KEY" ${base}`     // api overflow lane (rarely used)
     : base;                                                    // max: inherit the logged-in subscription
@@ -177,13 +182,13 @@ function basicTerminalScript(kind) {
 
 // claude invocation for a PowerShell tab (single-quote the prompt so the outer -Command "" needs no escaping).
 // Interactive workers start in PLAN MODE; autonomous run headless.
-function claudeCmdPwsh(node) {
-  const prompt = launchPrompt(node);
-  if (profile.name === "manual") return `Write-Host '${node.invoke}: worktree and .kickoff.md ready; start your configured assistant here.'`;
-  return profile.command
-    ? commandFor(profile, { prompt, mode: autonomous ? "acceptEdits" : workerMode })
-    : agentCmdFor(graph, { prompt, mode: workerMode, quote: "'" });
-}
+function claudeCmdPwsh(node) {
+  const prompt = launchPrompt(node);
+  if (profile.name === "manual") return `Write-Host '${node.invoke}: worktree and .kickoff.md ready; start your configured assistant here.'`;
+  return profile.command
+    ? commandFor(profile, { prompt, mode: autonomous ? "acceptEdits" : workerMode })
+    : agentCmdFor(graph, { prompt, mode: workerMode, quote: "'" });
+}
 
 // Windows Terminal adapter: a self-contained PowerShell script — worktree + brief per slice,
 // then one `wt` window with a LEAD tab + one tab per slice (each cd'd into its worktree).
@@ -283,13 +288,13 @@ else artifact = basicTerminalScript(term);   // background
 const psScript = term === "wt" || term === "warp";
 const withBom = (s) => (psScript ? "" : "") + s;
 
-// Manual is the default. A locally authorized profile plus --launch is required to spawn.
-let decision;
-try {
-  decision = outFile ? { spawn: false, mode: "wrote-script" } : dry ? { spawn: false, mode: "dry" }
-    : launchDecisionForProfile(profile, { requestedLaunch, autonomous });
-  if (autonomous && decision.spawn && !okAutonomous) decision = { spawn: false, mode: "autonomous-needs-ack" };
-} catch (e) { console.error(`fanout: ${e.message}`); process.exit(2); }
+// Manual is the default. A locally authorized profile plus --launch is required to spawn.
+let decision;
+try {
+  decision = outFile ? { spawn: false, mode: "wrote-script" } : dry ? { spawn: false, mode: "dry" }
+    : launchDecisionForProfile(profile, { requestedLaunch, autonomous });
+  if (autonomous && decision.spawn && !okAutonomous) decision = { spawn: false, mode: "autonomous-needs-ack" };
+} catch (e) { console.error(`fanout: ${e.message}`); process.exit(2); }
 
 console.error(`fanout: wave ${waveIdx}/${waves.length} · cap ${cap} (recommended ${rec.recommended}, bound by ${rec.binding.why.split(" — ")[0]}) · term=${term} · lane=${lane}${track ? ` · track=${track}` : ""} · ${decision.mode}`);
 console.error(`slices: ${wave.map((n) => n.invoke).join(", ")}`);

package/scripts/lib/backlog-core.mjs

@@ -3,8 +3,8 @@
 // the item→node adapter that lets `grab` reuse the fanout brief machinery, and pickNext —
 // the highest-priority ready thing across roadmap AND backlog. No IO.
 
-import { flatten, readyNodes } from "./graph.mjs";
-import { comparePriority, tierBadge, validatePriority, TIERS } from "./priority.mjs";
+import { flatten, readyNodes, commandLaneMembers, commandLaneActive } from "./graph.mjs";
+import { comparePriority, laneComparator, tierBadge, validatePriority, TIERS } from "./priority.mjs";
 import { addSprint } from "./mcp-core.mjs";
 
 export const KINDS = ["bug", "chore", "followup", "urgent", "idea"];
@@ -15,7 +15,7 @@ const SLUG = /^[a-z0-9][a-z0-9-]*$/;
 // Fields a caller may set on an item via backlog_set (id is structural, set only at add).
 const ITEM_SETTABLE = new Set([
   "title", "kind", "status", "priority", "source", "refs", "touches",
-  "est_sessions", "gate", "prompt", "prs", "completed_on", "promoted_to", "linear", "dispatch_tier",
+  "est_sessions", "gate", "prompt", "prs", "completed_on", "promoted_to", "linear", "dispatch_tier", "receipts",
 ]);
 
 // ── validation (plain object) ───────────────────────────────────────────────
@@ -229,11 +229,16 @@ export function backlogItemToNode(item) {
 
 // ── pickNext: the single highest-priority ready thing across both trackers ───
 // Roadmap wins full ties (planned value work outranks erratic work at equal priority).
-// backlog may be null (no backlog.yaml). Returns { type: "slice"|"backlog", node|item } or null.
-export function pickNext(graph, backlog) {
+// backlog may be null (no backlog.yaml). `today` (YYYY-MM-DD, optional) arms the command-lane
+// boost among slices; absent → lane inactive → the pick order is byte-identical to today.
+// Returns { type: "slice"|"backlog", node|item } or null.
+export function pickNext(graph, backlog, today) {
   const ready = readyNodes(flatten(graph));
+  const laneCmp = laneComparator(commandLaneMembers(graph), commandLaneActive(graph, today));
   const topSlice = ready.length
     ? [...ready].sort((a, b) => {
+        const lc = laneCmp(a, b);
+        if (lc) return lc;
         const pc = comparePriority(a.priority, b.priority);
         if (pc) return pc;
         return a.invoke.localeCompare(b.invoke);

package/scripts/lib/cli-core.mjs

@@ -5,8 +5,8 @@ import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 
 export const REL = ["docs", "roadmap", "roadmap.yaml"];
-const MAP = { plan: "scheduler.mjs", render: "render.mjs", fan: "fanout.mjs", fanout: "fanout.mjs", validate: "validate.mjs", show: "show.mjs", cleanup: "cleanup.mjs", wizard: "wizard.mjs", go: "wizard.mjs", mcp: "mcp.mjs", watch: "watch-prs.mjs", set: "set.mjs", backlog: "backlog.mjs", grab: "grab.mjs", promote: "promote.mjs", next: "next.mjs", linear: "linear.mjs", review: "review.mjs", dispatch: "dispatch.mjs", plate: "plate.mjs", estimate: "estimate.mjs", cycle: "cycle.mjs", init: "init.mjs", assistant: "assistant.mjs" };
-const NOT_YET = { sync: "P4" };
+const MAP = { plan: "scheduler.mjs", render: "render.mjs", fan: "fanout.mjs", fanout: "fanout.mjs", validate: "validate.mjs", show: "show.mjs", cleanup: "cleanup.mjs", wizard: "wizard.mjs", go: "wizard.mjs", mcp: "mcp.mjs", watch: "watch-prs.mjs", set: "set.mjs", backlog: "backlog.mjs", grab: "grab.mjs", promote: "promote.mjs", next: "next.mjs", linear: "linear.mjs", review: "review.mjs", dispatch: "dispatch.mjs", plate: "plate.mjs", estimate: "estimate.mjs", cycle: "cycle.mjs", init: "init.mjs", assistant: "assistant.mjs", doctor: "doctor.mjs" };
+const NOT_YET = { sync: "P4" };
 
 // Walk up from `start` to the first dir containing docs/roadmap/roadmap.yaml; null if none.
 // `exists` is injectable for testing.
@@ -92,6 +92,6 @@ export function missingRoadmapHelp(cwd) {
     `        - { id: s1, title: First sprint, status: next, invoke: first-s1, est_sessions: 1 }`,
     ``,
     `Save that to ${rel}, then 'roadmap validate' and 'roadmap render'.`,
-    `Run 'roadmap init' from the repo root for a safe bootstrap preview.`,
+    `Run 'roadmap init' from the repo root for a safe bootstrap preview.`,
   ].join("\n");
 }

package/scripts/lib/doctor-core.mjs

@@ -0,0 +1,63 @@
+// roadmap — doctor brain (PURE). Reconciles the roadmap against reality and reports DRIFT
+// between the plan and what actually shipped/tracked. No IO: doctor.mjs gathers the merged
+// PRs, open PRs, fanout worktrees, the rendered-vs-disk doc diff, and the Linear pull deltas,
+// then this classifies them into report sections. It REUSES the existing detection brains
+// (findUnrecordedMerges, prPhase/matchesRoadmapBranches, validateGraph) rather than re-deriving
+// them, so doctor can never disagree with /sync or the PR watcher. Structural (static) checks are
+// NOT drift — they're `roadmap validate`'s job — so they are deliberately not folded in here.
+
+import { findUnrecordedMerges } from "./sync-core.mjs";
+import { prPhase, matchesRoadmapBranches, checksOf } from "./pr-watch-core.mjs";
+
+// Open-PR phases that count as drift — a PR sitting in one of these needs a human/agent nudge.
+// "ready" (mergeable) and the transient "checks-pending" are NOT drift; merged/closed aren't open.
+const OPEN_PR_DRIFT = new Set(["draft", "conflicts", "checks-failing"]);
+
+// doctorReport(inputs) -> { sections: [{ title, items }], driftCount }.
+// A section is included ONLY when it has drift items, so a clean roadmap yields
+// { sections: [], driftCount: 0 }. Inputs are already-gathered (see doctor.mjs):
+//   graph           parsed roadmap YAML
+//   mergedPrs       [{ number, headRefName, title, body }]        (state=merged)
+//   allPrs          [{ number, headRefName, state, isDraft, mergeStateStatus, statusCheckRollup }]
+//   worktrees       fanout worktrees [{ branch, path, dirty, isMerged }]
+//   renderedVsDisk  { staleDocs: [path, ...] } — generated docs whose on-disk bytes != a fresh render
+//   linearDeltas    result.proposals.deltas, or null when Linear is unconfigured/unreachable
+export function doctorReport({ graph, mergedPrs = [], allPrs = [], worktrees = [], renderedVsDisk = {}, linearDeltas = null } = {}) {
+  const sections = [];
+  const add = (title, items) => { if (items.length) sections.push({ title, items }); };
+
+  // 1. SHIPPED-BUT-NOT-MARKED — a merged PR whose slice is still open in the roadmap.
+  add("Shipped but not marked complete",
+    findUnrecordedMerges(graph, mergedPrs).map(
+      (u) => `${u.invoke} — merged in PR #${u.pr} (${u.branch}) but still open; reconcile (roadmap set / /sync).`));
+
+  // 2. STALE GENERATED DOCS — the YAML moved but SLICES.md/BACKLOG.md weren't re-rendered.
+  add("Generated docs stale",
+    (renderedVsDisk.staleDocs || []).map((p) => `${p} differs from a fresh render — run 'roadmap render'.`));
+
+  // 3. LINEAR != ROADMAP — pull-only sync deltas (status/priority the tracker disagrees on).
+  //    null = Linear off/unreachable → skip the section entirely (the graceful guard).
+  if (linearDeltas) {
+    add("Linear disagrees with the roadmap",
+      linearDeltas.map((d) => `${d.kind} ${d.key}: ${d.field} ${d.from} → ${d.to ?? `(${d.note})`} in Linear.`));
+  }
+
+  // 4. OPEN-PR REALITY — roadmap-branch PRs stuck in a drift phase (draft/conflicts/failing).
+  //    allPrs may be null (gh absent) — external-state signals "unknown" that way; treat as none.
+  //    Normalize the raw rollup → `checks` via checksOf FIRST (the same step watch-prs does): prPhase
+  //    keys off pr.checks, so without this the "checks-failing" signal could never fire.
+  add("Open PRs needing attention",
+    (allPrs || [])
+      .map((pr) => ({ ...pr, checks: checksOf(pr) }))
+      .filter((pr) => matchesRoadmapBranches(pr.headRefName, graph) && OPEN_PR_DRIFT.has(prPhase(pr)))
+      .map((pr) => `PR #${pr.number} (${pr.headRefName}) — ${prPhase(pr)}.`));
+
+  // 5. STALE WORKTREES — fanout worktrees left unmerged or dirty (work parked mid-air).
+  add("Stale fanout worktrees",
+    worktrees
+      .filter((w) => !w.isMerged || w.dirty)
+      .map((w) => `${w.branch || "(detached)"} — ${w.isMerged ? "merged" : "UNMERGED"}, ${w.dirty ? "dirty" : "clean"} (${w.path}).`));
+
+  const driftCount = sections.reduce((n, s) => n + s.items.length, 0);
+  return { sections, driftCount };
+}

package/scripts/lib/external-state.mjs

@@ -0,0 +1,67 @@
+// roadmap — external reality probes (git + gh). IMPURE but GUARDED: every probe returns a safe/empty
+// value when git/gh is missing, unauthed, slow, or errors, so callers never throw and stay fast. The
+// same gatherers were inlined in hooks/session-start.mjs, scripts/watch-prs.mjs, and scripts/cleanup.mjs;
+// this is the ONE shared home so drift-doctor + review-debt backpressure don't add a fourth/fifth copy.
+// The parsing is split into a PURE helper (parseWorktrees) so it can be unit-tested without a repo.
+
+import { spawnSync } from "node:child_process";
+import { resolve, sep } from "node:path";
+
+const git = (root, ...a) => spawnSync("git", a, { cwd: root, encoding: "utf8" });
+
+// TODO(dedupe): hooks/session-start.mjs, scripts/watch-prs.mjs, and scripts/cleanup.mjs still carry
+// their own inline copies of these gatherers (pre-dating this module). Fold them onto this one home
+// in a follow-up so there's a single implementation. Tracked in the finishing-discipline backlog.
+
+// Merged PRs: [{ number, headRefName, title, body }]. [] on any failure. 5s cap.
+export function mergedPrs(root) {
+  try {
+    const r = spawnSync("gh", ["pr", "list", "--state", "merged", "--limit", "100", "--json", "number,headRefName,title,body"],
+      { cwd: root, encoding: "utf8", timeout: 5000 });
+    if (r.status !== 0 || !r.stdout) return [];
+    return JSON.parse(r.stdout);
+  } catch { return []; }
+}
+
+// All PRs incl. open/draft with merge + check state:
+// [{ number, title, headRefName, state, isDraft, mergeStateStatus, statusCheckRollup }].
+// null on failure (lets a caller distinguish "gh absent" from "zero PRs"). 5s cap.
+export function allPrs(root) {
+  try {
+    const r = spawnSync("gh", ["pr", "list", "--state", "all", "--limit", "100",
+      "--json", "number,title,headRefName,state,isDraft,mergeStateStatus,statusCheckRollup"],
+      { cwd: root, encoding: "utf8", timeout: 5000 });
+    if (r.status !== 0) return null;
+    return JSON.parse(r.stdout);
+  } catch { return null; }
+}
+
+// PURE: parse `git worktree list --porcelain` → [{ path, branch, isMerged }], optionally filtered to
+// those under wtRoot. mergedSet = branch names merged into the base (from `git branch --merged`).
+export function parseWorktrees(porcelain, { mergedSet = new Set(), wtRoot = null } = {}) {
+  const all = (porcelain ? porcelain.split(/\n\n+/) : []).map((b) => ({
+    path: (b.match(/^worktree (.+)$/m) || [])[1],
+    branch: (b.match(/^branch refs\/heads\/(.+)$/m) || [])[1] || null,
+  })).filter((w) => w.path);
+  const under = wtRoot
+    ? all.filter((w) => { const rp = resolve(w.path); return rp === wtRoot || rp.startsWith(wtRoot + sep); })
+    : all;
+  return under.map((w) => ({ ...w, isMerged: w.branch ? mergedSet.has(w.branch) : false }));
+}
+
+// Fanout worktrees under wtRoot with dirty + merged classification: [{ path, branch, isMerged, dirty }].
+// [] on any failure. meta drives remote/base/worktree_root exactly as cleanup.mjs resolves them.
+export function worktrees(root, meta = {}) {
+  try {
+    const remote = meta.remote || "origin";
+    const base = meta.base_branch || "main";
+    const wtRoot = resolve(meta.worktree_root || resolve(root, "..", "_worktrees"));
+    const porcelain = (git(root, "worktree", "list", "--porcelain").stdout || "").trim();
+    const mergedOut = git(root, "branch", "--merged", `${remote}/${base}`, "--format=%(refname:short)").stdout || "";
+    const mergedSet = new Set(mergedOut.split("\n").map((s) => s.trim()).filter(Boolean));
+    return parseWorktrees(porcelain, { mergedSet, wtRoot }).map((w) => ({
+      ...w,
+      dirty: ((git(root, "-C", w.path, "status", "--porcelain").stdout) || "").trim().length > 0,
+    }));
+  } catch { return []; }
+}

package/scripts/lib/graph.mjs

@@ -6,7 +6,7 @@
 
 import { readFileSync } from "node:fs";
 import YAML from "yaml";
-import { comparePriority } from "./priority.mjs";
+import { comparePriority, laneComparator } from "./priority.mjs";
 
 export const STATUS = {
   active:      { emoji: "🟢", label: "Active",      done: false, rank: 0 },
@@ -84,6 +84,8 @@ export function flatten(graph) {
         resumeAction: sp.resume_action || "",
         kickoffBrief: sp.kickoff_brief || "brief",
         prs: sp.prs || [],
+        receipts: sp.receipts || null,   // optional per-slice completion evidence (see validate-core required_receipts)
+        outcome: sp.outcome || null,     // optional founder-review rollup group (render groups siblings by this)
         completedOn: sp.completed_on || null,
         pi,
         sprint: sp,
@@ -253,9 +255,67 @@ export function coherenceEnabled(meta) {
   return !(meta && meta.discipline && meta.discipline.coherence === false);
 }
 
+// Command lane: meta.command_lane = { objective, until: "YYYY-MM-DD", pi?, slices?: [invoke,...] }.
+// A dated objective that outranks generic priority until its date passes OR its slices all complete —
+// so the roadmap makes finishing the most important outcome easier than discovering the next slice.
+// members(): the set of slice invoke keys in the lane (by explicit `slices` and/or every sprint of `pi`).
+export function commandLaneMembers(graph) {
+  const lane = graph && graph.meta && graph.meta.command_lane;
+  if (!lane) return new Set();
+  const members = new Set();
+  if (Array.isArray(lane.slices)) for (const s of lane.slices) members.add(s);
+  if (lane.pi) for (const pi of graph.pis || []) if (pi.id === lane.pi) for (const sp of pi.sprints || []) if (sp.invoke) members.add(sp.invoke);
+  return members;
+}
+
+// active: lane set, not past `until` (YYYY-MM-DD lexical compare), and >=1 member slice still open.
+// Once every member ships (or the date passes) the override releases and ordering returns to normal.
+// `today` is injected (a YYYY-MM-DD string) so the gate is testable and deterministic.
+export function commandLaneActive(graph, today) {
+  const lane = graph && graph.meta && graph.meta.command_lane;
+  if (!lane) return false;
+  if (lane.until && today && String(today) > lane.until) return false;
+  const members = commandLaneMembers(graph);
+  if (!members.size) return false;
+  for (const pi of graph.pis || []) for (const sp of pi.sprints || []) {
+    if (sp.invoke && members.has(sp.invoke) && !isDone(sp.status)) return true;
+  }
+  return false;
+}
+
+// SHAPE validation for meta.command_lane (called by validate-core, living beside the lane helpers the
+// way validatePriority lives beside comparePriority). Errors on a malformed lane; WARNS on a dangling
+// pi/slice ref — the lane would look armed but boost nothing. No clock here: expiry vs `until` is a
+// PLAN-time concern. Returns { errors, warnings }; empty when no command_lane is set.
+export function validateCommandLane(graph) {
+  const errors = [], warnings = [];
+  const lane = graph && graph.meta && graph.meta.command_lane;
+  if (lane == null) return { errors, warnings };
+  if (typeof lane !== "object" || Array.isArray(lane)) {
+    errors.push("meta.command_lane must be a mapping { objective, until, pi?, slices? }");
+    return { errors, warnings };
+  }
+  if (typeof lane.objective !== "string" || !lane.objective) errors.push("meta.command_lane.objective must be a non-empty string");
+  if (typeof lane.until !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(lane.until)) errors.push(`meta.command_lane.until must be YYYY-MM-DD (got ${JSON.stringify(lane.until)})`);
+  const piIds = new Set((graph.pis || []).map((p) => p.id));
+  const invokeKeys = new Set();
+  for (const p of graph.pis || []) for (const s of p.sprints || []) if (s.invoke) invokeKeys.add(s.invoke);
+  if (lane.pi != null) {
+    if (typeof lane.pi !== "string") errors.push("meta.command_lane.pi must be a PI id string");
+    else if (!piIds.has(lane.pi)) warnings.push(`meta.command_lane.pi "${lane.pi}" matches no PI — the lane covers nothing via pi`);
+  }
+  if (lane.slices != null) {
+    if (!Array.isArray(lane.slices)) errors.push("meta.command_lane.slices must be an array of invoke keys");
+    else for (const s of lane.slices) if (!invokeKeys.has(s)) warnings.push(`meta.command_lane.slices: "${s}" resolves to no slice invoke`);
+  }
+  return { errors, warnings };
+}
+
 // Compute execution waves under a concurrency cap N.
 // Returns { waves: [[node,...],...], held: { onHuman:[node], blocked:[node] } }.
 // opts.coherence (default true): PI-coherence tiebreak in the ready sort — see coherenceEnabled.
+// opts.meta + opts.today: an active command lane (see commandLaneMembers/Active) floats its member
+//   slices to the top of the ready sort. Both absent → lane inactive → ordering byte-identical to today.
 export function computeWaves(model, N = 3, opts = {}) {
   const coherence = opts.coherence !== false;
   const { nodes, sprintIndex } = model;
@@ -266,6 +326,12 @@ export function computeWaves(model, N = 3, opts = {}) {
     throw err;
   }
 
+  // Command-lane boost, computed once per call. model.pis is graph.pis; meta rides in via opts.
+  const laneGraph = { meta: opts.meta, pis: model.pis };
+  const laneMembers = commandLaneMembers(laneGraph);
+  const laneActive = commandLaneActive(laneGraph, opts.today);
+  const laneCmp = laneComparator(laneMembers, laneActive);
+
   // Work on a mutable copy of statuses so optimistic completion drives layering.
   const status = new Map(nodes.map((n) => [n.nodeKey, n.status]));
   const localDone = (key) => isDone(status.get(key));
@@ -301,6 +367,8 @@ export function computeWaves(model, N = 3, opts = {}) {
     }
 
     ready.sort((a, b) => {
+      const lc = laneCmp(a, b);                             // active command lane floats its members first
+      if (lc) return lc;                                    // inactive/absent → 0 → priority, coherence, existing order
       const pc = comparePriority(a.priority, b.priority);  // declared priority wins the cap slot
       if (pc) return pc;                                    // both absent → 0 → coherence, then existing order
       if (coherence && a.piId !== b.piId) {