@connorbritain/roadmap 0.3.0

package/scripts/scheduler.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// roadmap — wave scheduler CLI (print-only; spawns nothing).
+// Builds the execution plan via lib/plan.mjs (recommended cap + waves) and prints it,
+// or emits it as JSON (consumed by fanout.mjs / adapters / the MCP read tools).
+//
+// Usage:
+//   node scheduler.mjs [--in docs/roadmap/roadmap.yaml] [--cap N] [--json]
+//                      [--use-free-ram] [--review-ceiling N] [--wave N]
+//   --cap N         override the recommended cap
+//   --json          emit the plan as JSON
+//   --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 { buildPlan } from "./lib/plan.mjs";
+import { baseRefOf, remoteOf } from "./lib/brief.mjs";
+import { tierBadge } from "./lib/priority.mjs";
+
+const args = process.argv.slice(2);
+const val = (name, def) => {
+  const i = args.indexOf(name);
+  return i >= 0 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : def;
+};
+const has = (name) => args.includes(name);
+
+const inPath = val("--in", "docs/roadmap/roadmap.yaml");
+const asJson = has("--json");
+const useFree = has("--use-free-ram");
+const reviewCeiling = Number(val("--review-ceiling", 5));
+const detailWave = Number(val("--wave", 1));
+
+const hasCap = has("--cap");
+const capVal = hasCap ? Number(val("--cap", "")) : null;
+
+const graph = loadGraph(inPath);
+
+let plan;
+try {
+  plan = buildPlan(graph, { cap: hasCap && Number.isFinite(capVal) ? capVal : undefined, useFree, reviewCeiling });
+} catch (e) {
+  console.error(`✗ ${e.message}`);
+  process.exit(1);
+}
+
+if (asJson) {
+  process.stdout.write(JSON.stringify(plan, null, 2) + "\n");
+  process.exit(0);
+}
+
+// ── human plan ─────────────────────────────────────────────────────────────
+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}`);
+console.log(`  machine:  ${plan.sys.cores} cores, ${plan.sys.totalGb}GB total / ${plan.sys.freeGb}GB free (${plan.sys.platform})`);
+console.log(`  ceilings: ${plan.candidates.map((c) => `${c.n} [${c.why.split(" — ")[0]}]`).join("  ·  ")}`);
+console.log("");
+if (!plan.waves.length) console.log("No agent-runnable slices right now.");
+plan.waves.forEach((w, i) => {
+  const marker = i + 1 === detailWave ? " ◀ detail" : "";
+  const closes = (plan.waveCloses && plan.waveCloses[i]) || [];
+  console.log(`Wave ${i + 1}${marker} — ${w.length} concurrent${closes.length ? ` (closes ${closes.join(", ")})` : ""}:`);
+  for (const n of w) console.log(`  • ${tierBadge(n.priority) ? `[${tierBadge(n.priority)}] ` : ""}${n.invoke}  (${n.weight}, ~${n.est_sessions ?? "?"} sess)  — ${n.what}`);
+});
+if (plan.held.onHuman.length) {
+  console.log(`\nHeld on a human:`);
+  for (const n of plan.held.onHuman) console.log(`  • ${n.invoke} — gated on ${n.gatedOn}`);
+}
+
+// Expand launch commands for the detail wave (print-only — copy/paste or feed to fanout).
+const dw = plan.waves[detailWave - 1];
+if (dw && dw.length) {
+  console.log(`\n--- Wave ${detailWave} launch (illustrative) — 'roadmap fan --wave ${detailWave}' does this AND writes each worktree's .kickoff.md (which the session reads) ---`);
+  console.log(`git fetch ${remoteOf(graph)} --quiet`);
+  for (const n of dw) {
+    console.log(`git worktree add "${n.worktree}" -b "${n.branch}" ${baseRefOf(graph)}`);
+    console.log(`(cd "${n.worktree}" && claude "${n.prompt}")   # ${n.invoke}`);
+  }
+}

package/scripts/set.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// roadmap set <invoke> field=value [...] — edit one slice's fields from the shell.
+// Values are YAML scalars/flow (deps=[s1,s2], priority='{tier: P1, weight: 60}'),
+// field=@path reads the value from a file (multiline prompts/briefs), field=null deletes.
+// Same allow-list + pre-write gate as the MCP set_fields tool.
+
+import { readFileSync } from "node:fs";
+import YAML from "yaml";
+import { parseAssignments } from "./lib/cli-core.mjs";
+import { mutateRoadmap } from "./lib/store.mjs";
+import { setFields } from "./lib/mcp-core.mjs";
+
+const args = process.argv.slice(2);
+const invoke = args.find((a) => !a.includes("=") && !a.startsWith("-"));
+const assigns = args.filter((a) => a.includes("="));
+if (!invoke || !assigns.length) {
+  console.error("usage: roadmap set <invoke> field=value [field2=value2 ...]   (field=@file reads a file; field=null deletes)");
+  process.exit(2);
+}
+
+try {
+  const fields = {};
+  for (const a of parseAssignments(assigns)) {
+    fields[a.field] = a.fromFile !== undefined ? readFileSync(a.fromFile, "utf8") : YAML.parse(a.raw);
+  }
+  const r = mutateRoadmap(process.cwd(), (doc) => setFields(doc, { invoke, fields }));
+  console.log(`✓ ${invoke}: set ${r.fields.join(", ")}  (re-rendered ${r.rerendered})`);
+} catch (e) {
+  console.error(`✗ ${e.message}`);
+  process.exit(1);
+}

package/scripts/show.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// roadmap show <invoke> — print one slice's detail (what / deps / read-order / next / gate
+// + branch/worktree), for /slice orientation. Read-only.
+
+import { loadGraph, flatten, statusDisplay, resolveGate } from "./lib/graph.mjs";
+import { branchFor, worktreeFor } from "./lib/brief.mjs";
+import { executionDirectiveLines } from "./lib/execution.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; };
+const inPath = val("--in", "docs/roadmap/roadmap.yaml");
+const invoke = args.find((a) => !a.startsWith("--"));
+
+if (!invoke) { console.error("usage: roadmap show <slice-invoke>"); process.exit(2); }
+
+const graph = loadGraph(inPath);
+const model = flatten(graph);
+const node = model.nodes.find((n) => n.invoke === invoke);
+if (!node) {
+  const names = model.nodes.map((n) => n.invoke).sort();
+  console.error(`roadmap: no slice "${invoke}". Available:\n  ${names.join("\n  ")}`);
+  process.exit(2);
+}
+
+const gate = resolveGate(node, graph).replace(/\{\{\s*default\s*\}\}/gi, "default gate").trim();
+const deps = [...node.deps.map((d) => d.split("/")[1].toUpperCase()), ...node.piDeps.map((p) => p.toUpperCase())];
+const out = [];
+out.push(`Slice: ${node.invoke}  [${statusDisplay(node.status, node.statusLabel)}]`);
+out.push(`PI:    ${node.programLabel} · ${node.id.toUpperCase()}${node.estSessions != null ? `  (~${node.estSessions} sessions)` : ""}`);
+out.push(`What:  ${node.what}`);
+if (node.priority) {
+  const parts = [node.priority.tier, node.priority.weight != null ? `weight ${node.priority.weight}` : null].filter(Boolean).join(" · ");
+  out.push(`Priority: ${parts || "(set)"}${node.priority.reason ? ` — ${node.priority.reason}` : ""}`);
+}
+// Execution directive at the top of the read-out (only when the slice declares one).
+const execLines = executionDirectiveLines(node);
+if (execLines) { out.push(""); execLines.forEach((l) => out.push(l)); }
+if (deps.length) out.push(`Deps:  ${deps.join(", ")}`);
+out.push(`Branch:   ${branchFor(node, graph)}`);
+out.push(`Worktree: ${worktreeFor(node, graph)}`);
+if (node.gatedOn) out.push(`Gated on: ${node.gatedOn} — an agent prepares; it does NOT perform the gate.`);
+out.push("");
+out.push("Read-order:");
+(node.readOrder.length ? node.readOrder : ["(none listed — see the PI's detail dir)"]).forEach((r, i) => out.push(`  ${i + 1}. ${r}`));
+out.push("");
+out.push(`Next: ${node.resumeAction ? node.resumeAction.trim() : "(see read-order)"}`);
+if (node.prompt) {
+  out.push("");
+  out.push("Prompt (author instructions, verbatim):");
+  node.prompt.trimEnd().split("\n").forEach((l) => out.push(`  ${l}`));
+}
+out.push(`Gate: ${gate}`);
+console.log(out.join("\n"));