@connorbritain/roadmap 0.3.0 → 0.4.0

package/scripts/lib/linear-core.mjs

@@ -779,7 +779,13 @@ export function buildPullProposals({ cfg, inbound, graph, backlog }) {
         if (to === "canceled") {
           if (known.kind === "item") { if (known.status !== "dropped") deltas.push({ kind: known.kind, key: known.key, identifier: iss.identifier, field: "status", from: known.status, to: "dropped" }); }
           else deltas.push({ kind: known.kind, key: known.key, identifier: iss.identifier, field: "status", from: known.status, to: null, note: `canceled in Linear — no roadmap equivalent; decide by hand` });
-        } else if (to && to !== known.status && !(known.kind === "item" && to === "active" && known.status === "in_progress")) {
+        } else if (to && to !== known.status && pushedType !== "completed" && !(known.kind === "item" && to === "active" && known.status === "in_progress")) {
+          // pushedType === "completed" guard: completion is roadmap-authoritative (a slice is done when
+          // its PR merges). A stale Linear "In Progress"/"Todo" on a shipped slice must NOT propose
+          // un-completing it — that delta would hold the stateId push (buildPushPlan), and since pull is
+          // propose-only the delta never applies, so the issue is stuck non-Done in Linear forever. Let
+          // the push re-assert Done instead. (A genuine human COMPLETION in Linear — roadmap active,
+          // Linear completed — has pushedType "started" and still proposes, as before.)
           deltas.push({ kind: known.kind, key: known.key, identifier: iss.identifier, field: "status", from: known.status, to: known.kind === "item" && to === "active" ? "in_progress" : to });
         }
       }

package/scripts/lib/mcp-core.mjs

@@ -22,7 +22,7 @@ const SETTABLE = new Set([
   "title", "what", "status", "status_label", "est_sessions", "weight",
   "deps", "touches", "owns", "gate", "gated_on", "read_order", "resume_action",
   "prs", "completed_on", "optional", "execution", "track", "priority", "prompt", "kickoff_brief", "linear", "milestone", "dispatch_tier",
-  "shape", "risks", "estimate",
+  "shape", "risks", "estimate", "receipts", "outcome",
 ]);
 
 // ── tool registry ─────────────────────────────────────────────────────────────
@@ -54,7 +54,7 @@ export const TOOLS = [
       owns: { type: "array", items: { type: "string" } }, gate: { type: "string" },
       weight: { enum: ["heavy", "medium", "light"] }, gated_on: { type: "string" },
       read_order: { type: "array", items: { type: "string" } }, resume_action: { type: "string" },
-      prompt: { type: "string" }, milestone: { type: "string" }, status_label: { type: "string" },
+      prompt: { type: "string" }, milestone: { type: "string" }, outcome: { type: "string" }, status_label: { type: "string" },
       dispatch_tier: { type: "string" }, kickoff_brief: { type: "string" }, optional: { type: "boolean" },
       track: { type: "string" }, risks: { type: "array", items: { type: "string" } },
       priority: { type: "object", properties: { tier: { enum: ["P0", "P1", "P2", "P3"] }, weight: { type: "number", minimum: 0, maximum: 100 }, reason: { type: "string" } } } } } },
@@ -174,7 +174,7 @@ export function addSprint(doc, args) {
   if (pi < 0) throw new Error(`no PI "${args.pi}"`);
   const node = { id: args.id, title: args.title, status: args.status || "scheduled", invoke: args.invoke };
   // Same silent-drop hazard as addPi: keep in step with the sprint schema.
-  for (const k of ["what", "est_sessions", "gate", "weight", "gated_on", "resume_action", "prompt", "priority", "linear", "milestone",
+  for (const k of ["what", "est_sessions", "gate", "weight", "gated_on", "resume_action", "prompt", "priority", "linear", "milestone", "outcome",
     "shape", "estimate", "optional", "kickoff_brief", "track", "execution", "status_label", "dispatch_tier"]) if (args[k] != null) node[k] = args[k];
   for (const k of ["deps", "touches", "owns", "read_order", "risks"]) if (Array.isArray(args[k])) node[k] = args[k];
   const piMap = pisSeq(doc).items[pi];

package/scripts/lib/plan.mjs

@@ -5,24 +5,29 @@
 // dependency cycle; callers catch.
 
 import { flatten, computeWaves, readyNodes, coherenceEnabled, isDone } from "./graph.mjs";
-import { recommendConcurrency, nodeWeight, probeDisk } from "./recommend.mjs";
+import { recommendConcurrency, nodeWeight, probeDisk, probeReviewDebt } from "./recommend.mjs";
 import { branchFor, worktreeFor, launchPrompt } from "./brief.mjs";
 import { normalizeExecution, suggestedConcurrency } from "./execution.mjs";
 
 const round = (x) => Math.round(x * 10) / 10;
 
-// buildPlan(graph, { cap, useFree, reviewCeiling, disk }). cap omitted -> the recommended cap.
-// disk: undefined -> probe the machine (the real surfaces); null/object -> injected (tests).
+// buildPlan(graph, { cap, useFree, reviewCeiling, reviewDebt, today, disk }). cap omitted -> the
+// recommended cap. disk/reviewDebt: undefined -> probe the real surfaces; value -> injected (tests).
 export function buildPlan(graph, opts = {}) {
   const model = flatten(graph);
   const ready = readyNodes(model);
+  const today = opts.today ?? new Date().toISOString().slice(0, 10);
   const rec = recommendConcurrency(ready, graph, {
     useFree: opts.useFree,
     reviewCeiling: opts.reviewCeiling ?? 5,
+    reviewDebt: opts.reviewDebt !== undefined ? opts.reviewDebt : probeReviewDebt(process.cwd(), graph),
+    today,
     disk: opts.disk !== undefined ? opts.disk : probeDisk(graph),
   });
   const cap = opts.cap != null ? Number(opts.cap) : rec.recommended;
-  const { waves, held } = computeWaves(model, cap, { coherence: coherenceEnabled(graph.meta) });
+  // Command-lane float: pass meta + today so an active lane's member slices sort first in the wave
+  // (see computeWaves). Inactive/absent lane → byte-identical to the pre-lane order.
+  const { waves, held } = computeWaves(model, cap, { coherence: coherenceEnabled(graph.meta), meta: graph.meta, today });
 
   // Which PIs each wave CLOSES (all sprints done once the wave lands, counting earlier waves
   // optimistically) — the coherence read-out: "this wave finishes auth".

package/scripts/lib/priority.mjs

@@ -41,3 +41,11 @@ export function comparePriority(a, b) {
 export function tierBadge(p) {
   return p && TIER_RANK.has(p.tier) ? p.tier : null;
 }
+
+// Command-lane sort boost (see graph.mjs commandLaneMembers/Active). When a dated command lane is
+// active, its member slices sort FIRST — ahead of even declared priority — so finishing the committed
+// objective beats discovering the next slice. Inactive (or no lane) → always 0, so the caller's
+// existing ordering is byte-for-byte untouched: the backward-compat guarantee.
+export function laneComparator(members, active) {
+  return (a, b) => active ? ((members.has(a.invoke) ? 0 : 1) - (members.has(b.invoke) ? 0 : 1)) : 0;
+}

package/scripts/lib/recommend.mjs

@@ -9,7 +9,8 @@ import os from "node:os";
 import { existsSync, statfsSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { dirname, resolve } from "node:path";
-import { resolveGate } from "./graph.mjs";
+import { resolveGate, commandLaneActive, commandLaneMembers } from "./graph.mjs";
+import { allPrs, worktrees } from "./external-state.mjs";
 
 // Per-session resource cost by weight class — cross-language defaults (a full test
 // suite / heavy compile ~3.5GB/2 cores; a build/lint ~1.5GB/1 core; docs cheap).
@@ -113,6 +114,20 @@ export function probeDisk(graph, cwd = process.cwd()) {
   }
 }
 
+// Review-debt probe: how much unresolved review work already awaits a human — the backpressure
+// signal that dials concurrency DOWN when PRs/worktrees pile up faster than they merge. Counts open
+// non-draft PRs stuck DIRTY/BLOCKED/UNSTABLE + dirty-or-unmerged fanout worktrees. Fully GUARDED via
+// external-state (gh/git absent, slow, or outside a repo → empty), so it returns 0, never throws.
+export function probeReviewDebt(root, graph) {
+  const meta = (graph && graph.meta) || {};
+  const STUCK = new Set(["DIRTY", "BLOCKED", "UNSTABLE"]);
+  const stuckPrs = (allPrs(root) || []).filter(
+    (p) => p.state === "OPEN" && !p.isDraft && STUCK.has(p.mergeStateStatus)
+  ).length;
+  const stuckWts = worktrees(root, meta).filter((w) => w.dirty || !w.isMerged).length;
+  return stuckPrs + stuckWts;
+}
+
 export function systemInfo() {
   const cpus = os.cpus() || [];
   return {
@@ -130,7 +145,11 @@ const avg = (xs) => (xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0);
 //         disk ({ perWorktreeGb, freeGb } from probeDisk; absent/null → no disk ceiling) }
 export function recommendConcurrency(ready, graph, opts = {}) {
   const sys = opts.sys || systemInfo();
-  const reviewCeiling = opts.reviewCeiling ?? 5;
+  // Review-debt backpressure: each stuck PR / unresolved worktree lowers the review ceiling, so a
+  // growing merge queue auto-throttles new fanout. reviewDebt is INJECTED (stays pure, like disk);
+  // callers probe it via probeReviewDebt. Floors at 1 — the soft ceiling never blocks the lane.
+  const reviewDebt = opts.reviewDebt ?? 0;
+  const reviewCeiling = Math.max(1, (opts.reviewCeiling ?? 5) - reviewDebt);
   const coreReserve = opts.osCoreReserve ?? 2;     // leave cores for the OS/editor/lead
   const ramReserve = opts.osRamReserveGb ?? 4;
   const disk = opts.disk || null;                  // stays PURE: callers probe (probeDisk) and inject
@@ -154,7 +173,9 @@ export function recommendConcurrency(ready, graph, opts = {}) {
     { n: cpuCap,        why: `CPU — ${sys.cores} cores (− ${coreReserve} reserved) ÷ ~${avgCores.toFixed(1)}/session` },
     { n: ramCap,        why: `RAM — ~${ramBasis.toFixed(0)}GB usable ÷ ~${avgRam.toFixed(1)}GB/session` },
     { n: workCap,       why: `work — ${ready.length} independent ready slice(s)` },
-    { n: reviewCeiling, why: `review — PR review/merge bottleneck (soft ceiling)` },
+    { n: reviewCeiling, why: reviewDebt > 0
+        ? `review — PR review/merge bottleneck (soft ceiling, −${reviewDebt} review debt)`
+        : `review — PR review/merge bottleneck (soft ceiling)` },
   ];
   // Disk ceiling — the only one allowed to compute to 0: recommended stays >= 1 (soft
   // auto-dial), but callers that create worktrees (fan, grab) hard-block on disk.cap < 1.
@@ -164,6 +185,13 @@ export function recommendConcurrency(ready, graph, opts = {}) {
     diskCap = Math.floor(Math.max(0, disk.freeGb - diskReserve) / Math.max(disk.perWorktreeGb, 0.01));
     candidates.push({ n: Math.max(diskCap, 0), why: `disk — need ~${disk.perWorktreeGb.toFixed(1)}GB/worktree, ${disk.freeGb.toFixed(1)}GB free` });
   }
+  // Command-lane cap — while a dated command-lane objective is ACTIVE, don't fan wider than the lane
+  // itself has ready: keep the machine finishing the committed outcome instead of diluting attention
+  // across off-lane slices. Gated on active (needs the injected `today`); absent/inactive → no candidate.
+  if (commandLaneActive(graph, opts.today)) {
+    const members = commandLaneMembers(graph);
+    candidates.push({ n: ready.filter((n) => members.has(n.invoke)).length, why: `command-lane — cap to lane` });
+  }
   const binding = candidates.reduce((a, b) => (b.n < a.n ? b : a));
   return {
     recommended: Math.max(1, binding.n),

package/scripts/lib/render-core.mjs

@@ -31,7 +31,7 @@ export function renderMarkdown(graph, opts = {}) {
   ].filter(Boolean);
   w(`> **What this is:** the menu, grouped by PI (Program Increment) with sprints nested under each. Each sprint is a named **slice** you can pick up cold: spin up a session, name the slice, and it reads that slice's prescribed read-order and self-orients. Slice names are the \`/slice\` keys${introRefs.length ? ", " + introRefs.join(", ") : ""}.`);
   w("");
-  w("Use `roadmap show <name>` to orient on a menu entry; `roadmap plan` computes ready waves; `roadmap fan` prepares worktrees and can launch an explicitly configured assistant; `roadmap render` refreshes this file after merges. Claude slash skills are optional conveniences where installed.");
+  w("Use `roadmap show <name>` to orient on a menu entry; `roadmap plan` computes ready waves; `roadmap fan` prepares worktrees and can launch an explicitly configured assistant; `roadmap render` refreshes this file after merges. Claude slash skills are optional conveniences where installed.");
   w("");
   // Backlog pointer — emitted only when the repo has a backlog (opts.backlog), so a
   // backlog-free repo renders byte-identically.
@@ -43,7 +43,7 @@ export function renderMarkdown(graph, opts = {}) {
   // ---- cross-PI wave map ----------------------------------------------------
   w(`## Ready now — wave map (cap ${cap})`);
   w("");
-  w("Derived from the dependency graph: which slices can run concurrently right now, what waits behind them, and what is held on a human. Change the cap with `roadmap plan --cap N` or `roadmap fan --cap N`.");
+  w("Derived from the dependency graph: which slices can run concurrently right now, what waits behind them, and what is held on a human. Change the cap with `roadmap plan --cap N` or `roadmap fan --cap N`.");
   w("");
   let waveResult;
   try {
@@ -88,6 +88,16 @@ export function renderMarkdown(graph, opts = {}) {
     // sprint-status strip
     const strip = (pi.sprints || []).map((s) => `${s.id.toUpperCase()} ${emojiFor(s.status)}`).join(" · ");
     if (strip) w(`> Sprints: ${strip}`);
+    // Outcome rollups: group this PI's slices by `outcome` into one founder-review line each
+    // (done/total). First-seen order. No slice carries an outcome → no lines (byte-identical).
+    const outcomes = new Map();
+    for (const s of pi.sprints || []) {
+      if (!s.outcome) continue;
+      const o = outcomes.get(s.outcome) || { done: 0, total: 0 };
+      o.total++; if (isDone(s.status)) o.done++;
+      outcomes.set(s.outcome, o);
+    }
+    for (const [name, o] of outcomes) w(`> OUTCOME ${name}: ${o.done}/${o.total} ${emojiFor("complete")}`);
     if (plan) w(`> Exec plan: ${plan}${pi.exec_hint ? `  _(human hint: ${pi.exec_hint})_` : ""}`);
     if (pi.deps && pi.deps.length) w(`> Deps: ${pi.deps.map((d) => d.toUpperCase()).join(", ")}`);
     if (pi.exit_criteria) w(`> Exit: ${oneLine(pi.exit_criteria)}`);
@@ -99,9 +109,11 @@ export function renderMarkdown(graph, opts = {}) {
       const sess = isDone(sp.status) ? "—" : (typeof sp.est_sessions === "number" ? `~${fmt(sp.est_sessions)}` : "?");
       const deps = depCell(node);
       const prs = (sp.prs && sp.prs.length) ? ` · ${sp.prs.join(" ")}` : "";
+      const rcptKeys = sp.receipts ? Object.keys(sp.receipts).filter((k) => sp.receipts[k]) : [];
+      const rcpts = rcptKeys.length ? ` · 📎 ${rcptKeys.join(",")}` : "";
       const badge = tierBadge(sp.priority);
       const dtier = sp.dispatch_tier ? ` · ${B}dispatch: ${sp.dispatch_tier}${B}` : "";
-      w(`| ${sp.id.toUpperCase()} | ${B}/slice ${sp.invoke}${B} | ${statusDisplay(sp.status, sp.status_label)}${badge ? ` · **${badge}**` : ""}${dtier} | ${sess} | ${deps} | ${sp.what || sp.title}${prs} |`);
+      w(`| ${sp.id.toUpperCase()} | ${B}/slice ${sp.invoke}${B} | ${statusDisplay(sp.status, sp.status_label)}${badge ? ` · **${badge}**` : ""}${dtier} | ${sess} | ${deps} | ${sp.what || sp.title}${prs}${rcpts} |`);
     }
     w("");
   }

package/scripts/lib/review-core.mjs

@@ -16,8 +16,10 @@ export function graphDiff(oldGraph, newGraph) {
   const oldByInvoke = new Map(oldM.nodes.map((n) => [n.invoke, n]));
   const newByInvoke = new Map(newM.nodes.map((n) => [n.invoke, n]));
   const oldPis = new Set(((oldGraph && oldGraph.pis) || []).map((p) => p.id));
+  const newPis = new Set((newGraph.pis || []).map((p) => p.id));
 
   const addedPis = (newGraph.pis || []).filter((p) => !oldPis.has(p.id)).map((p) => ({ id: p.id, title: p.title }));
+  const removedPis = ((oldGraph && oldGraph.pis) || []).filter((p) => !newPis.has(p.id)).map((p) => ({ id: p.id, title: p.title }));
   const addedSprints = [];
   const completedSlices = [];
   const statusFlips = [];
@@ -44,7 +46,7 @@ export function graphDiff(oldGraph, newGraph) {
   const removedSprints = oldM.nodes.filter((o) => !newByInvoke.has(o.invoke))
     .map((o) => ({ invoke: o.invoke, pi: o.piId, title: o.title }));
 
-  return { addedPis, addedSprints, completedSlices, removedSprints, statusFlips, priorityChanges, stillHeld };
+  return { addedPis, removedPis, addedSprints, completedSlices, removedSprints, statusFlips, priorityChanges, stillHeld };
 }
 
 // Either snapshot may be null (no backlog.yaml then/now).
@@ -81,6 +83,10 @@ export function pisInFlight(graph) {
 export function reviewDigest({ gd, bd, graph }) {
   const added = bd.captured.length + gd.addedSprints.length;
   const completed = gd.completedSlices.length;
+  // Closure budget: sessions still owed across every not-done slice (null est → 0).
+  const estOpenSessions = flatten(graph).nodes
+    .filter((n) => !isDone(n.status))
+    .reduce((acc, n) => acc + (n.estSessions || 0), 0);
   return {
     shipped: gd.completedSlices,
     captured: { items: bd.captured, sprints: gd.addedSprints },
@@ -96,6 +102,8 @@ export function reviewDigest({ gd, bd, graph }) {
     }),
     aging: gd.stillHeld,
     newPis: gd.addedPis,
+    removedPis: gd.removedPis,
+    estOpenSessions,
     removed: gd.removedSprints,
     pisInFlight: pisInFlight(graph),
     priorityChanges: gd.priorityChanges,

package/scripts/lib/validate-core.mjs

@@ -2,7 +2,7 @@
 // No IO. validate.mjs prints + exits on the result; the MCP `validate` read tool returns it.
 // Structural checks + dependency resolution (via flatten) + cycle detection.
 
-import { flatten, detectCycle, STATUS } from "./graph.mjs";
+import { flatten, detectCycle, STATUS, HELD_STATUSES, validateCommandLane } from "./graph.mjs";
 import { validateExecution } from "./execution.mjs";
 import { validatePriority } from "./priority.mjs";
 import { validateLinearConfig } from "./linear-core.mjs";
@@ -10,6 +10,10 @@ import { validateEstimation } from "./estimate-core.mjs";
 
 const isDone = (s) => !!(STATUS[s] && STATUS[s].done);
 
+// Known per-slice completion-evidence keys (sp.receipts). meta.discipline.required_receipts
+// opts a repo into WARNing when a complete slice omits one.
+export const RECEIPT_KEYS = ["build", "test", "clone_install", "screenshot", "signoff", "publish"];
+
 export function validateGraph(graph) {
   const errors = [];
   const warnings = [];
@@ -19,16 +23,16 @@ export function validateGraph(graph) {
   const meta = graph.meta || {};
   if (meta.schema_version !== 1) err(`meta.schema_version must be 1 (got ${JSON.stringify(meta.schema_version)})`);
   if (!meta.program) err("meta.program is required");
-  if (meta.terminal && !["warp", "wt", "tmux", "iterm", "background", "print"].includes(meta.terminal)) {
-    err(`meta.terminal "${meta.terminal}" is not a known adapter`);
-  }
-  if (meta.assistants != null) {
-    if (typeof meta.assistants !== "object" || Array.isArray(meta.assistants)) err("meta.assistants must be a mapping");
-    else {
-      if (meta.assistants.default != null && typeof meta.assistants.default !== "string") err("meta.assistants.default must be a profile name string");
-      if (meta.assistants.profiles != null && (typeof meta.assistants.profiles !== "object" || Array.isArray(meta.assistants.profiles))) err("meta.assistants.profiles must be a mapping");
-    }
-  }
+  if (meta.terminal && !["warp", "wt", "tmux", "iterm", "background", "print"].includes(meta.terminal)) {
+    err(`meta.terminal "${meta.terminal}" is not a known adapter`);
+  }
+  if (meta.assistants != null) {
+    if (typeof meta.assistants !== "object" || Array.isArray(meta.assistants)) err("meta.assistants must be a mapping");
+    else {
+      if (meta.assistants.default != null && typeof meta.assistants.default !== "string") err("meta.assistants.default must be a profile name string");
+      if (meta.assistants.profiles != null && (typeof meta.assistants.profiles !== "object" || Array.isArray(meta.assistants.profiles))) err("meta.assistants.profiles must be a mapping");
+    }
+  }
 
   // Jira is the designed follow-up but NOT implemented — surface a stray block instead of
   // letting someone believe it syncs (docs/DEPLOYMENT.md documents the planned shape).
@@ -47,6 +51,15 @@ export function validateGraph(graph) {
       if (meta.discipline.pi_min_slices != null && !(Number.isInteger(meta.discipline.pi_min_slices) && meta.discipline.pi_min_slices >= 1)) {
         err("meta.discipline.pi_min_slices must be an integer >= 1 (a bad knob silently disabling a guardrail is the failure mode)");
       }
+      if (meta.discipline.active_pi_cap != null && !(Number.isInteger(meta.discipline.active_pi_cap) && meta.discipline.active_pi_cap >= 1)) {
+        err("meta.discipline.active_pi_cap must be an integer >= 1 (the max concurrently-active PIs the portfolio allows)");
+      }
+      // Finishing-discipline: which receipts a complete slice must carry (opt-in). A bad value
+      // would silently disable the check, so reject a non-array or an unknown key.
+      const rr = meta.discipline.required_receipts;
+      if (rr != null && !(Array.isArray(rr) && rr.every((k) => RECEIPT_KEYS.includes(k)))) {
+        err(`meta.discipline.required_receipts must be an array of known receipt keys (${RECEIPT_KEYS.join("|")})`);
+      }
       // Composition SHAPE (capture_ratio guards growth RATE): a PI under the floor is usually a
       // slice wearing a PI's coat — 13 one-slice PIs is how a 64-project wall happens. ONE
       // aggregated warning (signal, not a wall); complete PIs exempt (history is what it is).
@@ -57,6 +70,16 @@ export function validateGraph(graph) {
           warn(`composition: ${thin.length} non-complete PI(s) hold fewer than ${floor} slice(s) (${thin.map((p) => p.id).join(", ")}) — a PI is a strategic bet; fold these into siblings or grow them`);
         }
       }
+      // WIP cap: too many concurrently-ACTIVE PIs is how a portfolio stops finishing and starts
+      // sprawling. The roadmap should reward closure over discovery — one aggregated warning when
+      // the funded-active count exceeds policy (complete/held/scheduled PIs don't count against it).
+      const cap = meta.discipline.active_pi_cap;
+      if (Number.isInteger(cap) && cap >= 1) {
+        const activePis = (graph.pis || []).filter((pi) => pi.status === "active");
+        if (activePis.length > cap) {
+          warn(`WIP: ${activePis.length} active PI(s) exceed the cap of ${cap} (${activePis.map((p) => p.id).join(", ")}) — finish an active PI before starting another; the roadmap rewards closure over discovery`);
+        }
+      }
     }
   }
   if (meta.last_review != null) {
@@ -65,6 +88,12 @@ export function validateGraph(graph) {
     }
   }
 
+  // Optional meta.command_lane: a dated finishing override, SHAPE-validated in graph.mjs beside the
+  // lane helpers (expiry vs `until` is a PLAN-time concern — the pure validator has no clock).
+  const cl = validateCommandLane(graph);
+  for (const e of cl.errors) err(e);
+  for (const w of cl.warnings) warn(w);
+
   // Optional meta.linear + per-PI overrides + sprint linear fields. Absent → no-op.
   const lin = validateLinearConfig(graph);
   for (const e of lin.errors) err(e);
@@ -75,6 +104,7 @@ export function validateGraph(graph) {
   for (const e of est.errors) err(e);
   for (const w of est.warnings) warn(w);
 
+  const requiredReceipts = (meta.discipline && Array.isArray(meta.discipline.required_receipts)) ? meta.discipline.required_receipts : [];
   const validStatus = new Set(Object.keys(STATUS));
   const seenPiIds = new Set();
   for (const pi of graph.pis || []) {
@@ -100,6 +130,12 @@ export function validateGraph(graph) {
       if (!validStatus.has(sp.status)) err(`${where}: status "${sp.status}" invalid`);
       if (!sp.invoke) err(`${where}: invoke key required`);
       if (sp.gated_on && sp.status !== "gated") warn(`${where}: gated_on set but status is "${sp.status}" (expected gated)`);
+      // Finishing discipline (opt-in): a done slice must carry every required receipt; a missing one
+      // means "done" was declared without the evidence. Off entirely when required_receipts is absent.
+      if (requiredReceipts.length && isDone(sp.status)) {
+        const missing = requiredReceipts.filter((k) => !(sp.receipts && sp.receipts[k]));
+        if (missing.length) warn(`receipt: ${where} is complete but missing required receipt(s): ${missing.join(", ")}`);
+      }
       if (!isDone(sp.status) && sp.est_sessions == null) warn(`${where}: no est_sessions (sessions-remaining rollup will undercount)`);
       // Optional execution-strategy hint. Absent → no-op (backward-compatible); present → enum/type/consistency checks.
       const exec = validateExecution(sp.execution, where);
@@ -108,6 +144,22 @@ export function validateGraph(graph) {
       // Optional priority block. Absent → no-op.
       for (const e of validatePriority(sp.priority, where).errors) err(e);
     }
+    // Active-state integrity: an "active" PI must hold REAL agent-runnable work, or the board lies
+    // about what's in flight and the concurrency planner over-recommends. Two failure modes:
+    //   (a) every sprint is complete → a stale-active PI that should have rolled up to complete;
+    //   (b) no sprint is advanceable → every open sprint is held (gated/blocked/paused) or parked
+    //       (optionality), so it's a human-gated lane, not active development — a session dispatched
+    //       here has nothing to run. This is the "gated decision counted as runnable work" smell.
+    if (pi.status === "active" && Array.isArray(pi.sprints) && pi.sprints.length) {
+      const open = pi.sprints.filter((sp) => !isDone(sp.status));
+      if (open.length === 0) {
+        warn(`active-integrity: PI ${pi.id} is active but every sprint is complete — mark it complete (a stale-active PI inflates the in-flight count and hides real closure)`);
+      } else if (open.every((sp) => HELD_STATUSES.includes(sp.status) || sp.status === "optionality")) {
+        const held = open.filter((sp) => HELD_STATUSES.includes(sp.status)).length;
+        const parked = open.length - held;
+        warn(`active-integrity: PI ${pi.id} is active but has no agent-runnable slice — ${held} held (gated/blocked/paused)${parked ? ` + ${parked} optionality` : ""}; this is a human-gated lane, not active development`);
+      }
+    }
   }
 
   // flatten resolves deps + unique invoke keys (throws on failure), then cycle-detect.

package/scripts/next.mjs

@@ -13,7 +13,7 @@ import { tierBadge } from "./lib/priority.mjs";
 
 const graph = loadGraph("docs/roadmap/roadmap.yaml");
 const backlog = loadBacklog(process.cwd());
-const next = pickNext(graph, backlog);
+const next = pickNext(graph, backlog, new Date().toISOString().slice(0, 10));
 
 if (!next) {
   console.log("Nothing ready: no runnable slices, no open backlog items. ('roadmap plan' shows what's held and why.)");

package/scripts/review.mjs

@@ -72,6 +72,7 @@ out.push(anchor
 out.push(`shipped (${digest.shipped.length}): ${digest.shipped.map((s) => `${s.invoke}${s.prs && s.prs.length ? ` (${s.prs.join(" ")})` : ""}`).join(", ") || "—"}`);
 out.push(`captured (${digest.netGrowth.added}): ${digest.captured.items.length} backlog item(s), ${digest.captured.sprints.length} sprint(s)`);
 out.push(`net growth: +${digest.netGrowth.added} / -${digest.shipped.length + digest.closedItems.length} (ratio ${digest.netGrowth.ratio})`);
+out.push(`closure: ${digest.newPis.length} PI(s) born / ${digest.removedPis.length} died · capture-to-ship ratio ${digest.netGrowth.ratio} · ~${digest.estOpenSessions} open session(s) remaining`);
 if (digest.aging.length) out.push(`held since before last review: ${digest.aging.map((a) => `${a.invoke} (${a.status})`).join(", ")}`);
 if (digest.newPis.length) out.push(`new PIs: ${digest.newPis.map((p) => p.id).join(", ")}`);
 if (digest.pisInFlight > 1) out.push(`PIs in flight: ${digest.pisInFlight}`);

package/scripts/scheduler.mjs

@@ -11,7 +11,7 @@
 //   --use-free-ram  size RAM off currently-free memory instead of 75% of total
 //   --wave N        when printing, mark the launch detail for wave N (default 1)
 
-import { loadGraph } from "./lib/graph.mjs";
+import { loadGraph, commandLaneActive, commandLaneMembers, isDone } from "./lib/graph.mjs";
 import { buildPlan } from "./lib/plan.mjs";
 import { baseRefOf, remoteOf } from "./lib/brief.mjs";
 import { tierBadge } from "./lib/priority.mjs";
@@ -33,10 +33,11 @@ const hasCap = has("--cap");
 const capVal = hasCap ? Number(val("--cap", "")) : null;
 
 const graph = loadGraph(inPath);
+const today = new Date().toISOString().slice(0, 10);   // one clock read for the whole run (plan + banner)
 
 let plan;
 try {
-  plan = buildPlan(graph, { cap: hasCap && Number.isFinite(capVal) ? capVal : undefined, useFree, reviewCeiling });
+  plan = buildPlan(graph, { cap: hasCap && Number.isFinite(capVal) ? capVal : undefined, useFree, reviewCeiling, today });
 } catch (e) {
   console.error(`✗ ${e.message}`);
   process.exit(1);
@@ -48,6 +49,19 @@ if (asJson) {
 }
 
 // ── human plan ─────────────────────────────────────────────────────────────
+// Command-lane banner. Prints only while the lane is armed: past `until` or once every member ships,
+// commandLaneActive goes false and the banner disappears. Reuses the single `today` computed above.
+if (commandLaneActive(graph, today)) {
+  const lane = graph.meta.command_lane;
+  const members = commandLaneMembers(graph);
+  let laneOpen = 0;
+  for (const pi of graph.pis || []) for (const sp of pi.sprints || []) {
+    if (sp.invoke && members.has(sp.invoke) && !isDone(sp.status)) laneOpen++;
+  }
+  console.log(`COMMAND LANE: ${lane.objective} (until ${lane.until}) — ${laneOpen} lane slice(s) sort first`);
+  console.log("");
+}
+
 const capNote = hasCap ? `(you set --cap ${plan.cap}; recommended ${plan.recommended})` : `(recommended)`;
 console.log(`Concurrency cap: ${plan.cap} ${capNote}`);
 console.log(`  bound by: ${plan.binding.why}`);