@connorbritain/roadmap 0.3.0

package/scripts/assistant.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import { loadGraph } from "./lib/graph.mjs";
+import { LOCAL_CONFIG_REL, BUILTIN_PROFILES, readLocalConfig, configuredProfiles } from "./lib/assistant-core.mjs";
+
+const args = process.argv.slice(2);
+const action = args[0] || "list";
+const graph = loadGraph("docs/roadmap/roadmap.yaml");
+const root = process.cwd();
+const { path, config } = readLocalConfig(root);
+if (action === "list") {
+  const all = configuredProfiles(graph, config);
+  console.log(`default: ${all.defaultProfile}`);
+  for (const p of Object.values(all.profiles)) console.log(`${p.name}\tlaunch=${Boolean(p.launch)}\tautonomous=${Boolean(p.autonomous)}\t${p.description || ""}`);
+} else if (action === "doctor") {
+  const all = configuredProfiles(graph, config);
+  console.log(existsSync(path) ? `ok: ${LOCAL_CONFIG_REL} found` : `warning: ${LOCAL_CONFIG_REL} absent; manual profile is active`);
+  for (const p of Object.values(all.profiles)) if (p.launch && !p.command) console.log(`error: ${p.name} is launch-enabled but has no command`);
+  console.log("ok: no credentials found in local assistant configuration");
+} else if (action === "configure") {
+  const name = args[1];
+  if (!name || !BUILTIN_PROFILES[name]) { console.error(`usage: roadmap assistant configure <${Object.keys(BUILTIN_PROFILES).join("|")}> [--enable-launch]`); process.exit(2); }
+  mkdirSync(join(root, ".roadmap"), { recursive: true });
+  const command = BUILTIN_PROFILES[name].command || "REPLACE_ME {prompt}";
+  const next = { version: 1, ...config, assistants: { ...(config.assistants || {}), [name]: { ...(config.assistants?.[name] || {}), command, launch: args.includes("--enable-launch") } } };
+  writeFileSync(path, `# Machine-local. Do not commit secrets.\n${stringify(next)}`, "utf8");
+  console.log(`configured ${name}; launch=${args.includes("--enable-launch")}`);
+} else { console.error("assistant: expected list | configure | doctor"); process.exit(2); }

package/scripts/backlog.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// roadmap backlog [list|add|set] — the erratic-work tracker CLI.
+//   roadmap backlog                          priority-sorted open items (--all includes closed)
+//   roadmap backlog add "title" [-k kind] [--id slug] [--tier P1] [--weight N] [--note s] [--slice invoke] [--est N]
+//   roadmap backlog set <id> field=value ... (field=@file | field=null; same semantics as roadmap set)
+// First `add` creates docs/roadmap/backlog.yaml. Every mutation re-renders BACKLOG.md (+ the
+// SLICES.md open-count pointer).
+
+import { readFileSync } from "node:fs";
+import YAML from "yaml";
+import { parseAssignments } from "./lib/cli-core.mjs";
+import { loadBacklog, mutateBacklog, originBacklogIds } from "./lib/store.mjs";
+import { addItem, setItemFields, sortByPriority, openCount, KINDS } from "./lib/backlog-core.mjs";
+import { tierBadge } from "./lib/priority.mjs";
+
+const args = process.argv.slice(2);
+const sub = args[0] && !args[0].startsWith("-") ? args[0] : "list";
+const rest = sub === args[0] ? args.slice(1) : args;
+const val = (...names) => {
+  for (const n of names) {
+    const i = rest.indexOf(n);
+    if (i >= 0 && rest[i + 1] != null) return rest[i + 1];
+  }
+  return undefined;
+};
+
+try {
+  if (sub === "list") {
+    const backlog = loadBacklog(process.cwd());
+    if (!backlog) {
+      console.log(`No backlog yet. Capture the first item:\n  roadmap backlog add "fix the thing" -k bug --tier P1`);
+      process.exit(0);
+    }
+    const all = rest.includes("--all");
+    const items = sortByPriority(all ? backlog.items || [] : (backlog.items || []).filter((it) => it.status === "open" || it.status === "in_progress"));
+    console.log(`Backlog — ${openCount(backlog)} open item(s)${all ? ` (${(backlog.items || []).length} total)` : ""}`);
+    if (!items.length) console.log("  (empty)");
+    for (const it of items) {
+      const badge = tierBadge(it.priority);
+      const bits = [
+        badge ? `[${badge}${it.priority.weight != null ? ` ${it.priority.weight}` : ""}]` : null,
+        `${it.id}`, `(${it.kind}${all ? `, ${it.status}` : ""})`, `— ${it.title}`,
+        it.source && it.source.slice ? `· from ${it.source.slice}` : null,
+      ].filter(Boolean);
+      console.log(`  ${bits.join(" ")}`);
+      if (it.priority && it.priority.reason) console.log(`      why: ${it.priority.reason}`);
+    }
+    console.log(`\nGrab one: roadmap grab <id> · promote one: roadmap promote <id> --pi <pi>`);
+  } else if (sub === "add") {
+    const title = rest.find((a) => !a.startsWith("-") && a !== val("-k", "--kind") && a !== val("--id") && a !== val("--tier") && a !== val("--weight") && a !== val("--why") && a !== val("--note") && a !== val("--slice") && a !== val("--est"));
+    if (!title) { console.error(`usage: roadmap backlog add "title" [-k ${KINDS.join("|")}] [--id slug] [--tier P0-P3] [--weight 0-100] [--why reason] [--note s] [--slice invoke] [--est N]`); process.exit(2); }
+    const tier = val("--tier"), weight = val("--weight"), why = val("--why"), note = val("--note"), slice = val("--slice"), est = val("--est");
+    const item = {
+      title,
+      id: val("--id"),
+      kind: val("-k", "--kind"),
+      est_sessions: est != null ? Number(est) : undefined,
+    };
+    if (tier || weight || why) item.priority = { ...(tier ? { tier } : {}), ...(weight != null ? { weight: Number(weight) } : {}), ...(why ? { reason: why } : {}) };
+    if (note || slice) item.source = { ...(slice ? { slice } : {}), date: new Date().toISOString().slice(0, 10), ...(note ? { note } : {}) };
+    else item.source = { date: new Date().toISOString().slice(0, 10) };
+    const r = mutateBacklog(process.cwd(), (doc) => addItem(doc, { ...item, origin_ids: originBacklogIds(process.cwd()) }), { createIfMissing: true });
+    console.log(`✓ added ${r.added}  (re-rendered ${r.rerendered})`);
+  } else if (sub === "set") {
+    const id = rest.find((a) => !a.includes("=") && !a.startsWith("-"));
+    const assigns = rest.filter((a) => a.includes("="));
+    if (!id || !assigns.length) { console.error("usage: roadmap backlog set <id> field=value [...]   (field=@file | field=null)"); process.exit(2); }
+    const fields = {};
+    for (const a of parseAssignments(assigns)) {
+      fields[a.field] = a.fromFile !== undefined ? readFileSync(a.fromFile, "utf8") : YAML.parse(a.raw);
+    }
+    const r = mutateBacklog(process.cwd(), (doc) => setItemFields(doc, { id, fields }));
+    console.log(`✓ ${id}: set ${r.fields.join(", ")}  (re-rendered ${r.rerendered})`);
+  } else {
+    console.error(`roadmap backlog: unknown subcommand "${sub}" (list | add | set)`);
+    process.exit(2);
+  }
+} catch (e) {
+  console.error(`✗ ${e.message}`);
+  process.exit(1);
+}

package/scripts/cleanup.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// roadmap cleanup — prune fanout worktrees whose branch is merged to <remote>/<base> and
+// whose tree is clean. DRY by default (lists the plan); --remove acts; --force includes
+// unmerged/dirty. ONLY touches worktrees under the configured worktree_root (the fanout's
+// own) — never the main checkout or your manual worktrees.
+
+import { spawnSync } from "node:child_process";
+import { resolve, sep } from "node:path";
+import { loadGraph } from "./lib/graph.mjs";
+
+const args = process.argv.slice(2);
+const has = (n) => args.includes(n);
+const doRemove = has("--remove");
+const force = has("--force");
+
+const git = (...a) => spawnSync("git", a, { encoding: "utf8" });
+
+let meta = {};
+try { meta = loadGraph("docs/roadmap/roadmap.yaml").meta || {}; } catch { /* no roadmap — fall back to defaults */ }
+const remote = meta.remote || "origin";
+const base = meta.base_branch || "main";
+const wtRoot = resolve(meta.worktree_root || resolve(process.cwd(), "..", "_worktrees"));
+
+git("fetch", remote, "--quiet");
+
+// Parse `git worktree list --porcelain` into {path, branch}.
+const porcelain = (git("worktree", "list", "--porcelain").stdout || "").trim();
+const worktrees = (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 mergedOut = git("branch", "--merged", `${remote}/${base}`, "--format=%(refname:short)").stdout || "";
+const merged = new Set(mergedOut.split("\n").map((s) => s.trim()).filter(Boolean));
+
+const underRoot = (p) => { const rp = resolve(p); return rp === wtRoot || rp.startsWith(wtRoot + sep); };
+const candidates = worktrees.filter((w) => underRoot(w.path));
+
+if (!candidates.length) { console.log(`No fanout worktrees under ${wtRoot}.`); process.exit(0); }
+
+const plan = candidates.map((w) => {
+  const dirty = ((git("-C", w.path, "status", "--porcelain").stdout) || "").trim().length > 0;
+  const isMerged = w.branch ? merged.has(w.branch) : false;
+  return { ...w, dirty, isMerged, removable: isMerged && !dirty };
+});
+
+console.log(`Fanout worktrees under ${wtRoot} (merged into ${remote}/${base}?):`);
+for (const p of plan) {
+  const flags = `${p.isMerged ? "merged" : "UNMERGED"}, ${p.dirty ? "DIRTY" : "clean"}`;
+  const action = (p.removable || force) ? (doRemove ? "→ removing" : "→ would remove") : "→ keep";
+  console.log(`  ${(p.branch || "(detached)").padEnd(40)} [${flags}]  ${action}`);
+  console.log(`      ${p.path}`);
+}
+
+if (!doRemove) {
+  console.log(`\n(dry — nothing removed. 'roadmap cleanup --remove' prunes merged+clean; add --force for unmerged/dirty.)`);
+  process.exit(0);
+}
+
+let removed = 0;
+for (const p of plan) {
+  if (!(p.removable || force)) continue;
+  const rm = git("worktree", "remove", ...(p.dirty || !p.isMerged ? ["--force"] : []), p.path);
+  if (rm.status !== 0) { console.error(`  ✗ ${p.path}: ${(rm.stderr || "").trim()}`); continue; }
+  if (p.branch) git("branch", force ? "-D" : "-d", p.branch);
+  console.log(`  ✓ removed ${p.path}`);
+  removed++;
+}
+console.log(`\nremoved ${removed} worktree(s).`);

package/scripts/cli.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// roadmap — the roadmap shell CLI.
+// Dispatches `roadmap <command> [args]` from ANYWHERE inside a repo: it walks up from cwd
+// to find docs/roadmap/roadmap.yaml and runs the target script with cwd = that repo root,
+// so every relative default (--in, --out) just works. Pure logic lives in lib/cli-core.mjs.
+
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { route, classify, buildArgs, findRepoRoot, missingRoadmapHelp, expandShort, REL } from "./lib/cli-core.mjs";
+
+const SCRIPTS = dirname(fileURLToPath(import.meta.url));
+
+const HELP = `roadmap — roadmap CLI   (run from anywhere inside a repo with ${REL.join("/")})
+
+USAGE
+  roadmap <command> [options]        bare 'roadmap' = interactive console (TTY) / plan (piped)
+
+COMMANDS
+  (no command)    interactive console — walk through terminal / wave / cap, then launch  (in a TTY)
+  go              the same interactive console (force it when TTY detection is off)
+  plan            recommended concurrency cap + execution waves
+  next            the single highest-priority ready thing across roadmap + backlog
+  show <name>     one slice's detail (what / priority / prompt / read-order / next / gate / branch)
+  set <name> f=v  edit a slice's fields (f=@file for multiline, f=null deletes)
+  render          regenerate docs/SLICES.md (+ docs/BACKLOG.md when a backlog exists)
+  fan             launch a wave — a lead + one pane/tab per slice, each in its own worktree
+                  (--cloud dispatches the wave to CLOUD agents via Linear instead — no worktrees)
+  dispatch <key>  fire a Claude Code CLOUD session for one slice/backlog item (default --to claude-cloud;
+                  --to claude|codex|oz posts a Linear @-mention capsule instead)
+  backlog         erratic-work tracker: list | add "title" [-k kind --tier PN] | set <id> f=v
+  plate           the My Issues hopper: list | add/rm/set <key>... | clear  (curated batch → assignee=you)
+  cycle           the weekly election: plan [--capacity N] [--json] (stale first, capacity-packed
+                  candidates) | lock --promote a,b [--demote x,y]  (scheduled↔next, one atomic write)
+  grab <id>       launch ONE backlog item in its own worktree + session
+  promote <id>    promote a backlog item into a roadmap sprint (--pi <pi> [--id sN])
+  cleanup         prune fanout worktrees merged into the base branch + clean
+  validate        structural + dependency + cycle checks
+  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
+  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
+  help            this help
+
+OPTIONS (short | long)
+  -w | --wave N                 which wave (fan, plan)
+  -c | --cap N                  max concurrent sessions (fan, plan, render)
+  -t | --term <adapter>         wt | warp | tmux | print | background     (fan)
+  -d | --dry                    fan: preview only, spawn nothing
+  -o | --out <file>             write the launch script / SLICES.md to a file
+  -a | --autonomous             fan: headless 'claude -p' workers (needs -y)
+  -y | --yes-spawn-autonomous   fan: acknowledge autonomous spawning
+  -l | --lane <max|api>         fan: credential lane (default max)
+  -j | --json                   plan: emit the plan as JSON
+  -s | --stdout                 render: print instead of writing the file
+  -r | --remove                 cleanup: actually remove (otherwise dry)
+  -f | --force                  cleanup: include unmerged/dirty worktrees
+  -i | --in <yaml>              override the roadmap path (auto-discovered otherwise)
+  -wm | --worker-mode <mode>    fan: worker + lead permission mode (-> claude --permission-mode).
+                                Default comes from meta.worker_mode in roadmap.yaml (falls back to
+                                plan if unset); this flag overrides it for one run.
+                                plan          = read-only research, plan gates edits
+                                auto          = auto-approve tool/bash/MCP calls w/ safety checks
+                                                (the "auto mode" toggle — NOT a bypass)
+                                acceptEdits   = auto-accept file edits only (still asks for bash/MCP)
+                                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;
+                                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
+
+EXAMPLES
+  roadmap                            # where am I / what's runnable
+  roadmap fan -w 1 -c 2 -t warp      # launch wave 1, 2 sessions, in Warp
+  roadmap fan -w 1 -d                # preview the launch script (spawn nothing)
+  roadmap show auth-sessions
+  roadmap cleanup -r                 # prune merged+clean worktrees
+
+PLATFORM
+  Terminal defaults per OS: Windows -> wt, macOS/Linux -> tmux. Run 'fan' from the shell
+  where your terminal lives (tmux in WSL/macOS/Linux; wt or warp in Windows PowerShell).
+  Install per environment with 'npm link' (once in each Node you use, e.g. Windows + WSL).`;
+
+// Bare `roadmap` in an interactive terminal → the wizard (it hot-loads this repo's roadmap and
+// walks you through terminal/wave/cap). Bare + non-TTY keeps printing the plan, so pipes and
+// scripts (roadmap | cat, CI) are unaffected. `roadmap go` forces the wizard regardless.
+const RAW = process.argv.slice(2);
+if (RAW.length === 0 && process.stdin.isTTY) {
+  const root = findRepoRoot(process.cwd());
+  if (!root) { console.error(missingRoadmapHelp(process.cwd())); process.exit(2); }
+  const r = spawnSync("node", [join(SCRIPTS, "wizard.mjs")], { stdio: "inherit", cwd: root });
+  process.exit(r.status ?? 0);
+}
+
+// Normal dispatch — reached only when args are present, or bare + non-TTY (the wizard branch above
+// has already handled bare + TTY and exited). The findRepoRoot below is the single root walk on
+// this path (the wizard branch's own walk only runs in the early-exit case).
+const { cmd, rest } = route(process.argv.slice(2));
+const action = classify(cmd);
+
+if (action.kind === "help") { console.log(HELP); process.exit(0); }
+if (action.kind === "notyet") {
+  console.error(`roadmap ${cmd}: not built yet (lands in ${action.phase}). For now: edit ${REL.join("/")}, then 'roadmap render'.`);
+  process.exit(2);
+}
+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() });
+process.exit(r.status ?? 0);

package/scripts/cycle.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// roadmap cycle — the weekly election surface.
+//   roadmap cycle plan [--capacity N] [--json]     zero-network: graph + sync cursor (stale set)
+//   roadmap cycle lock --promote a,b [--demote x,y] one atomic validated write (scheduled↔next)
+// The interview lives in the /cycle skill; this owns the data and the write. Statuses are the
+// bookkeeping: promote = scheduled→next (committed this cycle), demote = next→scheduled. The
+// Linear cycle itself follows on the next sync (cyclePlan mirrors active+next).
+
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadGraph, flatten } from "./lib/graph.mjs";
+import { roadmapPaths, mutateRoadmap } from "./lib/store.mjs";
+import { normalizeLinearConfig } from "./lib/linear-core.mjs";
+import { electionPlan } from "./lib/cycle-core.mjs";
+import { bulkSet } from "./lib/mcp-core.mjs";
+import { readCursor } from "./linear.mjs";
+
+export function runCyclePlan(root, opts = {}) {
+  const graph = loadGraph(roadmapPaths(root).yaml);
+  const cfg = normalizeLinearConfig(graph.meta || {});
+  const capacity = opts.capacity || (cfg && cfg.cycle_capacity) || 10;
+  const cursor = readCursor(root);
+  return electionPlan(graph, { capacity, staleInvokes: (cursor && cursor.stale) || [] });
+}
+
+// One atomic validated write via bulkSet — all promotions/demotions land together or not at
+// all. Pre-checks give the human a clear refusal instead of a store validation error.
+export function runCycleLock(root, { promote = [], demote = [] } = {}) {
+  if (!promote.length && !demote.length) throw new Error("cycle lock needs --promote and/or --demote invoke keys");
+  const graph = loadGraph(roadmapPaths(root).yaml);
+  const statusOf = new Map(flatten(graph).nodes.map((n) => [n.invoke, n.status]));
+  for (const k of promote) {
+    const s = statusOf.get(k);
+    if (s == null) throw new Error(`no slice "${k}"`);
+    if (s !== "scheduled" && s !== "optionality") throw new Error(`can't promote "${k}" (status ${s}) — the election promotes scheduled/optionality to next`);
+  }
+  for (const k of demote) {
+    const s = statusOf.get(k);
+    if (s == null) throw new Error(`no slice "${k}"`);
+    if (s !== "next") throw new Error(`can't demote "${k}" (status ${s}) — only next (committed, unstarted) demotes back to scheduled`);
+  }
+  const updates = [
+    ...promote.map((invoke) => ({ invoke, fields: { status: "next" } })),
+    ...demote.map((invoke) => ({ invoke, fields: { status: "scheduled" } })),
+  ];
+  mutateRoadmap(root, (doc) => bulkSet(doc, { updates }));
+  return { promoted: promote, demoted: demote };
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const args = process.argv.slice(2);
+  const sub = args[0];
+  const val = (n) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : undefined; };
+  const list = (n) => (val(n) ? val(n).split(",").map((s) => s.trim()).filter(Boolean) : []);
+  const root = process.cwd();
+  try {
+    if (sub === "plan" || sub == null) {
+      const p = runCyclePlan(root, { capacity: val("--capacity") ? Number(val("--capacity")) : undefined });
+      if (args.includes("--json")) { console.log(JSON.stringify(p, null, 2)); process.exit(0); }
+      const line = (x) => `  ${x.stale ? "⚠ STALE " : ""}${x.invoke} (${x.status}${x.est != null ? ` · ${x.est}s` : " · unestimated"}${x.priority && x.priority.tier ? ` · ${x.priority.tier}` : ""}) — ${x.title}`;
+      const staleElected = p.elected.filter((x) => x.stale);
+      if (staleElected.length) {
+        console.log(`STALE — review these FIRST (journal silence past stale_days):`);
+        for (const x of staleElected) console.log(line(x));
+      }
+      console.log(`committed (${p.elected.length}, ${p.elected.reduce((s, x) => s + (x.est || 0), 0)}s of ${p.capacity}s capacity):`);
+      for (const x of p.elected) console.log(line(x));
+      console.log(`fits on top (greedy prefix, priority order):`);
+      for (const x of p.packed) console.log(line(x));
+      if (!p.packed.length) console.log(`  (nothing — capacity full or no estimated ready candidates)`);
+      if (p.overflow.length) console.log(`over capacity (ready, estimated, doesn't fit): ${p.overflow.map((x) => x.invoke).join(", ")}`);
+      if (p.unestimated.length) console.log(`unestimated (never auto-packed — price or pass): ${p.unestimated.map((x) => x.invoke).join(", ")}`);
+      if (p.unpricedElected.length) console.log(`⚠ committed but unpriced (counts as ZERO in capacity — price these): ${p.unpricedElected.map((x) => x.invoke).join(", ")}`);
+      console.log(`lock with: roadmap cycle lock --promote <a,b,...> [--demote <x,y,...>]  · then 'roadmap linear sync' projects the cycle`);
+    } else if (sub === "lock") {
+      const r = runCycleLock(root, { promote: list("--promote"), demote: list("--demote") });
+      console.log(`locked: promoted ${r.promoted.length ? r.promoted.join(", ") : "none"} → next${r.demoted.length ? ` · demoted ${r.demoted.join(", ")} → scheduled` : ""}.`);
+      console.log(`run 'roadmap linear sync' to project the cycle (active+next join the active Linear cycle).`);
+    } else {
+      console.error(`usage: roadmap cycle plan [--capacity N] [--json] | roadmap cycle lock --promote a,b [--demote x,y]`);
+      process.exit(2);
+    }
+  } catch (e) {
+    console.error(`✗ ${e.message}`);
+    process.exit(1);
+  }
+}