@dougharness/cli 1.2.0 → 1.4.0

package/node_modules/@dougharness/flow/scripts/autopilot.mjs

@@ -9,23 +9,30 @@
 //   autopilot.mjs stop <id> --reason "<why>"
 //   autopilot.mjs filed <id> --kind <follow-up|user> [--from <card>] --position "<text>"
 //   autopilot.mjs caps [--usd <n>] [--wall <min>] [--context <pct>]
-//   autopilot.mjs pick [--max <n>]            JSON { launch, needsPlan, held, alone }; a held line per held card on stderr
-//   autopilot.mjs queen-args <id> --kind <flow|hand>   writes .doug/.state/reports/<id>/queen-args.json, prints its path
+//   autopilot.mjs pick [--max <n>] [--milestone <id>]            JSON { launch, needsPlan, held, alone }; a held line per held card on stderr
+//   autopilot.mjs queen-args <id> --kind <flow|hand> [--with <id,id,...>] [--research on|off]   writes .doug/.state/reports/<id>/queen-args.json and the per-card queen.js beside it, prints both paths (args, then queen.js)
+//   autopilot.mjs agent-types --kind <flow|hand>   prints the agent types that queen spawns, one per line
 //   autopilot.mjs launched <id> --run <wf_id> --kind <flow|hand> --worktree <abs> --args-file <path>
-//   autopilot.mjs report --run <wf_id> --file <result.json>   saves the queen's report, prints land|resume|ask
-//   autopilot.mjs resumed <id> --run <wf_id>
+//   autopilot.mjs report --run <wf_id> --file <result.json>   saves the queen's report (a hand card's inline researchNote is written to .doug/.state/research/<id>.md so record promotes it), prints land|resume|ask
+//   autopilot.mjs answer <id> --answer "<text>"   records the user's answer to any asking stop in queen-args.json options.answers
+//   autopilot.mjs resumed <id> --run <wf_id>   counts every resume, plain or with the answer, against the single plain resume
+//   autopilot.mjs rerun-alone <id>   records a rerun-alone answer for a gate-timeout stop; refuses while another queen is in flight or after the card's one resume
+//   autopilot.mjs leave <id> --reason "<text>"   records the user's choice to leave a card In flow
 //   autopilot.mjs lock-wait <id> --ms <n>
+//   autopilot.mjs clear   drops an ended or inactive run; a running run is kept
 //   autopilot.mjs end
 // --dir <d> names the project (default cwd). Exit 0 done; 1 no run or unknown card; 2 bad usage.
 import { execFileSync } from "node:child_process";
-import { copyFileSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadModels } from "../lib/models.mjs";
-import { AUTOPILOT_FILE, STEPS, readAutopilot } from "../lib/autopilot-view.mjs";
+import { AUTOPILOT_FILE, STEPS, clearable, readAutopilot } from "../lib/autopilot-view.mjs";
 import { contextThreshold } from "../lib/context.mjs";
-import { classifyNotification, pickCards, workersMax } from "../lib/coordinator.mjs";
+import { classifyNotification, pickCards, queenLabel, renameQueenMeta, workersMax } from "../lib/coordinator.mjs";
 import { nextReadyCards } from "../lib/board.mjs";
+import { SEATS } from "../lib/card-loop.mjs";
 import { planFor, reportPathFor } from "../lib/plan.mjs";
 
 const argv = process.argv.slice(2);
@@ -81,10 +88,43 @@ function cardOf(s, cardId) {
   if (!c) fail(`unknown card ${cardId}`);
   return c;
 }
+const IN_FLIGHT = ["running", "done", "landing"];
+const RERUN_ALONE = "Rerun alone: no other queen is in flight now.";
+const othersInFlight = (s, id) => s.cards.filter((x) => x.id !== id && IN_FLIGHT.includes(x.state));
+// The saved stop report and queen-args of a card, for the commands that answer an asking stop.
+function savedStop(id, c) {
+  const reportDir = join(dir, ".doug/.state/reports", id);
+  let rep;
+  try {
+    rep = JSON.parse(readFileSync(join(reportDir, "card-report.json"), "utf8"));
+  } catch (e) {
+    fail(`cannot read the saved report for ${id}: ${e.code || e.message}`);
+  }
+  if (!rep || rep.outcome !== "stopped" || rep.reason === "agent-null" || !SEATS.includes(rep.stoppedAt)) fail(`${id} did not stop on an answerable ask stop`);
+  const argsPath = join(reportDir, "queen-args.json");
+  let qa;
+  try {
+    qa = JSON.parse(readFileSync(argsPath, "utf8"));
+  } catch (e) {
+    fail(`cannot read ${argsPath}: ${e.code || e.message}`);
+  }
+  const stopped = (Array.isArray(rep.history) ? rep.history : []).filter((h) => h && h.result === "stopped").pop();
+  const entry = { seat: rep.stoppedAt, question: rep.detail, answer: "" };
+  if (stopped && Number.isInteger(stopped.round) && stopped.round > 0) entry.round = stopped.round;
+  entry.run = c.runId;
+  return { rep, argsPath, qa, entry };
+}
 const clearStep = (c) => {
   delete c.step;
   delete c.stepStartedAt;
+  delete c.seats;
 };
+// Where the queen run's journal lives: the main session's run dir under the user's Claude dir; "" without a session id.
+function journalPath(run) {
+  const sid = process.env.CLAUDE_CODE_SESSION_ID;
+  if (!sid) return "";
+  return join(homedir(), ".claude", "projects", dir.replace(/[^A-Za-z0-9]/g, "-"), sid, "subagents", "workflows", run, "journal.jsonl");
+}
 
 function boardCard(cardId) {
   try {
@@ -168,6 +208,7 @@ switch (cmd) {
     const c = cardOf(s, id);
     c.step = arg2;
     c.stepStartedAt = new Date().toISOString();
+    c.seats = [...(Array.isArray(c.seats) ? c.seats : []), { step: arg2, startedAt: c.stepStartedAt }];
     save(s);
     say(`${id} ${arg2}`);
     break;
@@ -255,9 +296,14 @@ switch (cmd) {
       const b = boardCard(c.id);
       return b ? shape(b) : { id: c.id, goal: "", track: c.kind === "flow" ? "flow" : "hand" };
     });
-    const ready = nextReadyCards(board, { track: "any", batch: Math.max(1, board.cards.length) })
-      .cards.filter((c) => !flyingIds.has(c.id))
-      .map(shape);
+    if (opts.milestone === "") usage("--milestone needs an id");
+    let picked;
+    try {
+      picked = nextReadyCards(board, { track: "any", batch: Math.max(1, board.cards.length), milestone: opts.milestone });
+    } catch (e) {
+      fail(e instanceof Error ? e.message : String(e));
+    }
+    const ready = picked.cards.filter((c) => !flyingIds.has(c.id)).map(shape);
     const plans = {};
     for (const c of [...ready, ...inFlight]) {
       if (c.track !== "flow") continue;
@@ -279,6 +325,10 @@ switch (cmd) {
     if (!id) usage("queen-args needs a card id");
     const kind = need("kind");
     if (kind !== "flow" && kind !== "hand") usage("--kind must be flow or hand");
+    if (opts.research !== undefined) {
+      if (kind === "flow") usage("--research is for a hand card; research for a flow card runs before its plan (doug-next section 1)");
+      if (opts.research !== "on" && opts.research !== "off") usage("--research must be on or off");
+    }
     let args;
     if (kind === "flow") {
       try {
@@ -295,15 +345,21 @@ switch (cmd) {
       } catch {
         // absent or unreadable: no install command
       }
+      let base = "main";
+      try {
+        base = execFileSync("git", ["-C", dir, "symbolic-ref", "--short", "-q", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || "main";
+      } catch {
+        // not a git repo or a detached HEAD: main
+      }
       args = {
         card: { id: b.id, title: b.title ?? null, size: b.size ?? null, class: b.class ?? null, goal: b.goal ?? "" },
         options: {
           testerAgent: true,
-          research: false,
+          research: opts.research === "on",
           install: (config.commands && config.commands.install) || null,
           gateCommand: "node .doug/hooks/scripts/verify.mjs",
           branch: `card/${id}`,
-          base: "main",
+          base,
         },
         models: loadModels(dir),
         repoRoot: dir,
@@ -313,7 +369,39 @@ switch (cmd) {
     const out = join(dir, ".doug/.state/reports", id, "queen-args.json");
     mkdirSync(dirname(out), { recursive: true });
     writeFileSync(out, JSON.stringify(args) + "\n");
-    process.stdout.write(out + "\n");
+    const flying = (readAutopilot(dir)?.cards ?? []).filter((c) => ["running", "done", "landing"].includes(c.state)).map((c) => c.id);
+    const batch = String(opts.with ?? "").split(",").map((x) => x.trim()).filter(Boolean);
+    const srcFile = join(dirname(fileURLToPath(import.meta.url)), "..", "workflows", kind === "hand" ? "card-queen.js" : "doug-implement.js");
+    let renamed;
+    try {
+      renamed = renameQueenMeta(readFileSync(srcFile, "utf8"), { kind, label: queenLabel(id, [...flying, ...batch]) });
+    } catch (e) {
+      fail(`cannot build the per-card queen from ${srcFile}: ${e.message}`);
+    }
+    const script = join(dirname(out), "queen.js");
+    rmSync(script, { force: true });
+    writeFileSync(script, renamed);
+    process.stdout.write(out + "\n" + script + "\n");
+    break;
+  }
+  case "agent-types": {
+    const kind = need("kind");
+    if (kind !== "flow" && kind !== "hand") usage("--kind must be flow or hand");
+    const wf = join(dirname(fileURLToPath(import.meta.url)), "..", "workflows", kind === "hand" ? "card-queen.js" : "doug-implement.js");
+    let src;
+    try {
+      src = readFileSync(wf, "utf8");
+    } catch (e) {
+      fail(`cannot read ${wf}: ${e.message}`);
+    }
+    if (kind === "hand") {
+      const m = src.match(/const AGENT_TYPES = \{([^}]*)\}/);
+      if (!m) fail("AGENT_TYPES not found in card-queen.js");
+      src = m[1];
+    }
+    const types = [...new Set([...src.matchAll(kind === "hand" ? /'(doug-flow:[\w-]+)'/g : /agentType: '([^']+)'/g)].map((x) => x[1]))];
+    if (types.length === 0) fail("no agent types found");
+    process.stdout.write(types.join("\n") + "\n");
     break;
   }
   case "launched": {
@@ -337,6 +425,9 @@ switch (cmd) {
     c.kind = kind;
     c.worktree = worktree;
     clearStep(c);
+    delete c.journals;
+    const journal = journalPath(run);
+    if (journal) c.journals = [journal];
     save(s);
     say(`${id} launched as ${run}`);
     break;
@@ -360,6 +451,11 @@ switch (cmd) {
       // unreadable: classify says resume
     }
     const kind = c.kind === "flow" ? "flow" : "hand";
+    // The queen's task-output file wraps the result: {summary, agentCount, logs, result}.
+    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) && parsed.result !== null && typeof parsed.result === "object") {
+      const bare = kind === "flow" ? !("ok" in parsed) && !("paused" in parsed) : !("card" in parsed) && !("outcome" in parsed);
+      if (bare) parsed = parsed.result;
+    }
     if (parsed !== null) {
       const dest = kind === "flow" ? join(dir, reportPathFor(c.id)) : join(dir, ".doug/.state/reports", c.id, "card-report.json");
       try {
@@ -368,11 +464,94 @@ switch (cmd) {
       } catch (e) {
         process.stderr.write(`autopilot: warning: cannot write ${dest}: ${e.code || e.message}\n`);
       }
+      if (kind === "hand") {
+        const rep = parsed.report ?? parsed;
+        const note = rep && typeof rep.researchNote === "string" ? rep.researchNote : "";
+        if (note.trim() !== "") {
+          const noteDest = join(dir, ".doug/.state/research", `${c.id}.md`);
+          try {
+            const oneLine = note.trim();
+            let src = null;
+            if (!oneLine.includes("\n") && oneLine.startsWith("/") && resolve(oneLine) !== resolve(noteDest) && existsSync(oneLine)) src = oneLine;
+            if (resolve(oneLine) !== resolve(noteDest)) {
+              mkdirSync(dirname(noteDest), { recursive: true });
+              if (src) copyFileSync(src, noteDest);
+              else writeFileSync(noteDest, note);
+            }
+          } catch (e) {
+            process.stderr.write(`autopilot: warning: cannot write ${noteDest}: ${e.code || e.message}\n`);
+          }
+        }
+      }
     }
     const v = classifyNotification(kind, { status: "completed", result: parsed === null ? text : parsed });
+    if (v.action === "ask") {
+      let answered = false;
+      try {
+        const saved = JSON.parse(readFileSync(join(dir, ".doug/.state/reports", c.id, "queen-args.json"), "utf8"));
+        const rep = parsed?.report ?? parsed;
+        const stop = (Array.isArray(rep?.history) ? rep.history : []).filter((h) => h && h.result === "stopped").pop();
+        answered =
+          Array.isArray(saved?.options?.answers) &&
+          saved.options.answers.some(
+            (a) => a && a.run === run && a.seat === rep?.stoppedAt && stop && a.round === stop.round && a.question === rep?.detail,
+          );
+      } catch {
+        // no readable args: not answered
+      }
+      if (answered) {
+        say(`${c.id} resume with the answer`);
+        break;
+      }
+    }
+    if (v.action === "ask" && v.reason === "gate-timeout" && !c.resumes && othersInFlight(s, c.id).length > 0) {
+      c.state = "stopped";
+      c.reason = "gate-timeout: rerun alone pending";
+      save(s);
+      say(`${c.id} rerun alone gate-timeout`);
+      break;
+    }
     say(`${c.id} ${v.action}${v.reason ? ` ${v.reason}` : ""}`);
     break;
   }
+  case "answer": {
+    if (!id) usage("answer needs a card id");
+    const answer = need("answer");
+    if (answer.trim() === "") usage("--answer needs a non-blank answer");
+    const s = load();
+    const c = cardOf(s, id);
+    const { rep, argsPath, qa, entry } = savedStop(id, c);
+    entry.answer = answer;
+    qa.options = { ...(qa.options || {}), answers: [...(Array.isArray(qa.options?.answers) ? qa.options.answers : []), entry] };
+    writeFileSync(argsPath, JSON.stringify(qa, null, 2) + "\n");
+    say(`${id} answer recorded for ${entry.seat}`);
+    break;
+  }
+  case "rerun-alone": {
+    if (!id) usage("rerun-alone needs a card id");
+    const s = load();
+    const c = cardOf(s, id);
+    const others = othersInFlight(s, id);
+    if (others.length > 0) fail(`${others.map((x) => x.id).join(", ")} still in flight; rerun ${id} alone after it lands`);
+    if (c.resumes >= 1) fail(`${id} was already resumed once`);
+    const { rep, argsPath, qa, entry } = savedStop(id, c);
+    entry.answer = RERUN_ALONE;
+    qa.options = { ...(qa.options || {}), answers: [...(Array.isArray(qa.options?.answers) ? qa.options.answers : []), entry] };
+    writeFileSync(argsPath, JSON.stringify(qa, null, 2) + "\n");
+    say(`${id} rerun alone recorded for ${rep.stoppedAt}`);
+    break;
+  }
+  case "leave": {
+    if (!id) usage("leave needs a card id");
+    const reason = need("reason");
+    if (reason.trim() === "") usage("--reason needs a non-blank reason");
+    const s = load();
+    const c = cardOf(s, id);
+    c.left = reason;
+    save(s);
+    say(`${id} left In flow: ${reason}`);
+    break;
+  }
   case "resumed": {
     if (!id) usage("resumed needs a card id");
     const run = need("run");
@@ -380,6 +559,9 @@ switch (cmd) {
     const c = cardOf(s, id);
     c.resumes = (c.resumes || 0) + 1;
     c.runId = run;
+    c.state = "running";
+    const journal = journalPath(run);
+    if (journal) c.journals = [...(Array.isArray(c.journals) ? c.journals : []), journal];
     save(s);
     say(`${id} resumed as ${run}`);
     break;
@@ -394,8 +576,40 @@ switch (cmd) {
     say(`${id} lock wait ${c.lockWaitMs}ms`);
     break;
   }
+  case "clear": {
+    if (!existsSync(file)) say("nothing to clear");
+    else {
+      const s = readAutopilot(dir);
+      if (!s) say("kept the unreadable file");
+      else if (clearable(s, new Date())) {
+        rmSync(file);
+        say("cleared");
+      } else say("kept the running run");
+    }
+    break;
+  }
   case "end": {
     const s = load();
+    if (s.cards.length > 0) {
+      let board;
+      try {
+        board = JSON.parse(readFileSync(join(dir, ".doug/board.json"), "utf8"));
+      } catch (e) {
+        fail(`cannot read the board to check cards In flow: ${e.code || e.message}`);
+      }
+      const stuck = s.cards.filter((c) => {
+        if ((board.cards || []).find((b) => b.id === c.id)?.column !== "flow") return false;
+        if (c.resumes >= 1 || (typeof c.left === "string" && c.left.trim() !== "")) return false;
+        let answers = [];
+        try {
+          answers = JSON.parse(readFileSync(join(dir, ".doug/.state/reports", c.id, "queen-args.json"), "utf8")).options.answers;
+        } catch {
+          // no readable args: not answered
+        }
+        return !(Array.isArray(answers) && answers.some((a) => a && a.run === c.runId && a.answer !== RERUN_ALONE));
+      });
+      if (stuck.length > 0) fail(`cannot end: ${stuck.map((c) => c.id).join(", ")} still In flow, neither resumed nor answered`);
+    }
     s.status = "ended";
     s.endedAt = new Date().toISOString();
     save(s);
@@ -403,5 +617,5 @@ switch (cmd) {
     break;
   }
   default:
-    usage(`unknown subcommand${cmd ? ` ${cmd}` : ""}; use start, add, card, step, land, stop, filed, caps, pick, launched, report, resumed, lock-wait, or end`);
+    usage(`unknown subcommand${cmd ? ` ${cmd}` : ""}; use start, add, card, step, land, stop, filed, caps, pick, launched, report, answer, rerun-alone, leave, resumed, lock-wait, clear, or end`);
 }

package/node_modules/@dougharness/flow/scripts/board.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 // CLI for the development board, used by the /doug-next and doug-hand skills. Deterministic; no agents.
-//   board.mjs next [dir] [--track flow|hand|any] [--tag <tag>]
+//   board.mjs next [dir] [--track flow|hand|any] [--tag <tag>] [--epic <id>] [--milestone <id>]
 //                                                 the first Ready card on that track (default flow) whose deps are
 //                                                 Done, as JSON (exit 1 if none); --tag filters to cards carrying it
-//   board.mjs next --batch <n> [dir] [--track flow|hand|any] [--tag <tag>]
+//   board.mjs next --batch <n> [dir] [--track flow|hand|any] [--tag <tag>] [--epic <id>] [--milestone <id>]
 //                                                 the first n runnable Ready cards, in board order, as a JSON array
 //                                                 (exit 1 if none): the cards /doug-next plans together; stderr also
 //                                                 carries a `wall cap: <m> min` line (the cards' budgets from the size x class table)
@@ -14,16 +14,25 @@
 //                                                 Wall clock rows joined to the board, one line per cell and a final
 //                                                 `table:` line; writes nothing (replace WALL_BUDGET_MIN by hand). --usd does the same for the usd
 //                                                 table (USD_BUDGET) from the Cost rows of flow and hand entries
+//   board.mjs rollup [dir] [--epic <id> | --milestone <id>] [--from <live-runs file>]
+//                                                 per epic and milestone: columns, done/total, size-weighted progress,
+//                                                 measured cost and wall of Done cards, not-Done budget, as JSON; --from
+//                                                 defaults to docs/live-runs.md when present (else measured is null)
+//   board.mjs labels --check [dir]                one line per label colour under 3:1 against #ffffff or #1c2022; exit 0
 //   board.mjs card <id> [dir]                     one card as JSON
 //   board.mjs reorder <id> [dir] --before <other> | --after <other> | --top | --bottom
 //                                                 reorder a card within its column
 //   board.mjs move <id> <column> [dir] [--source <text>]
 //                                                 move a card
 //   board.mjs edit <id> [dir] [--title <t>] [--goal <g> | --goal-file <path>] [--size S|M|L] [--component <c>]
-//                     [--track flow|hand] [--class <c>] [--deps a,b] [--tag a,b] [--source <s>] [--force]
+//                     [--track flow|hand] [--class <c>] [--deps a,b] [--tag a,b] [--source <s>] [--epic <id>] [--milestone <id>] [--force]
 //                                                 changes a card's fields through the record's own validation
 //                                                 (never the id or the column; move stays the way to change that);
-//                                                 --tag "" clears a card's tags
+//                                                 --tag "" clears a card's tags; --epic "" / --milestone "" clear those
+//   board.mjs epic add <id> --title <t> --goal <g> [dir] [--version <v>] [--date YYYY-MM-DD]
+//   board.mjs epic edit <id> [dir] [--title <t>] [--goal <g>] [--version <v>] [--date <d>] [--status planned|active|done] [--force]
+//   board.mjs epic list [dir]                     epics as a JSON array; milestone add|edit|list takes the same flags.
+//                                                 --status done is refused while a member card is not Done (--force sets it, with a warning)
 //   board.mjs remove <id> [dir] [--force]         removes a card from the record: refused always when another card
 //                                                 lists it in deps; refused without --force when it is done, in
 //                                                 flow, or named by .doug/plan.json (each with --force removes it
@@ -49,29 +58,42 @@
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
-import { loadBoard, saveBoard, findCard, nextReadyCard, nextReadyCards, moveCard, editCard, removeCard, reorderCard, readyCapWarning, wallCapMinutes, WALL_BUDGET_MIN, WALL_BUDGET_MIN_N, parseLiveRunWalls, wallBudgetTable, USD_BUDGET, USD_BUDGET_MIN_N, usdCapDollars, parseLiveRunCosts, usdBudgetTable, runEntry, handEntry, handWallVerdict, runSummary, boardPath, parseAdversaryClasses, filterReportForCard, recordLanding } from "../lib/board.mjs";
+import { loadBoard, saveBoard, findCard, nextReadyCard, nextReadyCards, moveCard, editCard, editEpic, editMilestone, initLabelGroups, addEpic, addMilestone, removeCard, reorderCard, readyCapWarning, wallCapMinutes, WALL_BUDGET_MIN, WALL_BUDGET_MIN_N, parseLiveRunWalls, wallBudgetTable, USD_BUDGET, USD_BUDGET_MIN_N, usdCapDollars, parseLiveRunCosts, usdBudgetTable, rollup, checkFilters, labelContrastFailures, LIVE_RUNS_RELPATH, runEntry, handEntry, handWallVerdict, runSummary, boardPath, parseAdversaryClasses, filterReportForCard, recordLanding } from "../lib/board.mjs";
 import { loadPlan, planFor, unwrapReport, DEFAULT_BUDGET } from "../lib/plan.mjs";
 import { wallForRun } from "../lib/cost.mjs";
 
-const EDIT_FIELD_ORDER = ["title", "goal", "size", "component", "track", "class", "tags", "deps", "source"];
-const EDIT_USAGE = "usage: board.mjs edit <id> [dir] [--title <t>] [--goal <g> | --goal-file <path>] [--size S|M|L] [--component <c>] [--track flow|hand] [--class <c>] [--tag a,b] [--deps a,b] [--source <s>] [--force]";
+const EDIT_FIELD_ORDER = ["title", "goal", "size", "component", "track", "class", "tags", "deps", "source", "epic", "milestone"];
+const EDIT_USAGE = "usage: board.mjs edit <id> [dir] [--title <t>] [--goal <g> | --goal-file <path>] [--size S|M|L] [--component <c>] [--track flow|hand] [--class <c>] [--tag a,b] [--deps a,b] [--source <s>] [--epic <id>] [--milestone <id>] [--force]";
 
 const argv = process.argv.slice(2);
-const FLAGS = new Set(["hand", "top", "bottom", "force", "usd"]);
+const FLAGS = new Set(["hand", "top", "bottom", "force", "usd", "check"]);
 const REPEATABLE = new Set(["adversary"]);
 
 // Each subcommand's allowed flags, derived from what that case actually reads (card board-cli-unknown-flags).
 // `record` has two forms (--hand or not) with different allowed sets, handled separately below.
 const SUBCOMMAND_FLAGS = {
-  next: ["track", "batch", "tag"],
+  next: ["track", "batch", "tag", "epic", "milestone"],
   card: [],
   move: ["source"],
-  edit: ["title", "goal", "goal-file", "size", "component", "track", "class", "deps", "tag", "source", "force"],
+  edit: ["title", "goal", "goal-file", "size", "component", "track", "class", "deps", "tag", "source", "epic", "milestone", "force"],
   remove: ["force"],
   reorder: ["before", "after", "top", "bottom"],
   budgets: ["from", "usd"],
+  rollup: ["epic", "milestone", "from"],
+  labels: ["check"],
   summary: ["summary", "cost", "codex-cost", "wall", "commit", "card", "run", "claude-dir", "note"],
 };
+// epic and milestone: `<kind> add|edit|list`, each action with its own allowed flags.
+const PLAN_ACTION_FLAGS = {
+  add: ["title", "goal", "version", "date"],
+  edit: ["title", "goal", "version", "date", "status", "force"],
+  list: [],
+};
+const planUsage = (kind) => [
+  `usage: board.mjs ${kind} add <id> --title <t> --goal <g> [dir] [--version <v>] [--date YYYY-MM-DD]`,
+  `       board.mjs ${kind} edit <id> [dir] [--title <t>] [--goal <g>] [--version <v>] [--date YYYY-MM-DD] [--status planned|active|done] [--force]`,
+  `       board.mjs ${kind} list [dir]`,
+].join("\n");
 const RECORD_HAND_FLAGS = ["summary", "hand", "commit", "wall", "gate", "note", "rehearsal", "rehearsal-outcome", "cost"];
 const RECORD_REPORT_FLAGS = ["summary", "cost", "codex-cost", "wall", "commit", "adversary", "shared-cost", "note", "rehearsal", "rehearsal-outcome", "run", "claude-dir"];
 const opts = {};
@@ -98,13 +120,15 @@ function fail(msg, code = 1) {
 }
 
 const USAGE_FOR = {
-  next: "usage: board.mjs next [dir] [--track flow|hand|any] [--batch <n>] [--tag <tag>]",
+  next: "usage: board.mjs next [dir] [--track flow|hand|any] [--batch <n>] [--tag <tag>] [--epic <id>] [--milestone <id>]",
   card: "usage: board.mjs card <id> [dir]",
   move: "usage: board.mjs move <id> <column> [dir] [--source <text>]",
   edit: EDIT_USAGE,
   remove: "usage: board.mjs remove <id> [dir] [--force]",
   reorder: "usage: board.mjs reorder <id> [dir] --before <other> | --after <other> | --top | --bottom",
   budgets: "usage: board.mjs budgets [dir] [--usd] [--from <live-runs file>]",
+  rollup: "usage: board.mjs rollup [dir] [--epic <id> | --milestone <id>] [--from <live-runs file>]",
+  labels: "usage: board.mjs labels --check [dir] | labels init [dir]",
   summary: "usage: board.mjs summary <report.json> --summary \"<one sentence>\" [--cost <usd>] [--codex-cost <usd>] [--wall <text>] [--commit <sha>] [--card <id>] [--run <run-id>] [--claude-dir <dir>] [--note <text>]",
 };
 const RECORD_HAND_USAGE = "usage: board.mjs record <id> --hand [dir] --summary \"<one sentence>\" [--commit <sha>] [--wall <text>] [--gate <text>] [--note <text>] [--rehearsal <scenario> --rehearsal-outcome <passed|failed>] [--cost <usd>]";
@@ -124,6 +148,12 @@ function dirFrom(args, n) {
   return resolve(process.env.CLAUDE_PROJECT_DIR || args[n] || process.cwd());
 }
 
+if (cmd === "epic" || cmd === "milestone") {
+  const action = rest[0];
+  if (!Object.prototype.hasOwnProperty.call(PLAN_ACTION_FLAGS, action)) fail(planUsage(cmd), 2);
+  const unknown = Object.keys(opts).find((name) => !PLAN_ACTION_FLAGS[action].includes(name));
+  if (unknown !== undefined) fail(`unknown option --${unknown} for board.mjs ${cmd}\n${planUsage(cmd)}`, 2);
+}
 if (cmd === "record" || Object.prototype.hasOwnProperty.call(SUBCOMMAND_FLAGS, cmd)) {
   const unknown = unknownFlagFor(cmd, opts);
   if (unknown !== undefined) {
@@ -198,7 +228,7 @@ try {
       if (batch !== null && !(Number.isInteger(batch) && batch > 0)) fail(`--batch must be a positive integer, got ${JSON.stringify(opts.batch)}`, 2);
       if (opts.tag !== undefined && opts.tag.includes(",")) fail(`--tag takes one tag here; got "${opts.tag}"`, 2);
       const board = loadBoard(dir);
-      const { card, cards, skipped } = batch === null ? nextReadyCard(board, { track, tag: opts.tag }) : nextReadyCards(board, { track, batch, tag: opts.tag });
+      const { card, cards, skipped } = batch === null ? nextReadyCard(board, { track, tag: opts.tag, epic: opts.epic, milestone: opts.milestone }) : nextReadyCards(board, { track, batch, tag: opts.tag, epic: opts.epic, milestone: opts.milestone });
       for (const s of skipped) process.stderr.write(s.hand ? `skipping ${s.id}: hand track (a by-hand card; /doug-next ${s.id} takes it)\n` : s.flow ? `skipping ${s.id}: flow track (run it with /doug-next)\n` : `skipping ${s.id}: waiting on ${s.waitingOn.join(", ")}\n`);
       const capLine = readyCapWarning(board);
       if (capLine) process.stderr.write(capLine);
@@ -236,6 +266,42 @@ try {
       process.stdout.write(out.join("\n") + "\n");
       break;
     }
+    case "rollup": {
+      if (opts.epic !== undefined && opts.milestone !== undefined) fail(USAGE_FOR.rollup, 2);
+      const dir = dirFrom(rest, 0);
+      const board = loadBoard(dir);
+      try {
+        checkFilters(board, { epic: opts.epic, milestone: opts.milestone });
+      } catch (e) {
+        fail(e.message, 2);
+      }
+      let text = null;
+      if (opts.from !== undefined) {
+        try {
+          text = readFileSync(resolve(opts.from), "utf8");
+        } catch (e) {
+          fail(`cannot read --from file ${opts.from}: ${e.message}`, 2);
+        }
+      } else if (existsSync(join(dir, LIVE_RUNS_RELPATH))) {
+        text = readFileSync(join(dir, LIVE_RUNS_RELPATH), "utf8");
+      }
+      const r = rollup(board, text);
+      const out = opts.epic !== undefined ? r.epics.find((e) => e.id === opts.epic) : opts.milestone !== undefined ? r.milestones.find((m) => m.id === opts.milestone) : r;
+      process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+      break;
+    }
+    case "labels": {
+      if (rest[0] === "init" && opts.check !== true) {
+        const dir = dirFrom(rest, 1);
+        saveBoard(dir, initLabelGroups(loadBoard(dir)));
+        process.stdout.write(`Added label groups type and priority to ${relative(dir, boardPath(dir))}.\n`);
+        break;
+      }
+      if (opts.check !== true) fail(USAGE_FOR.labels, 2);
+      const lines = labelContrastFailures(loadBoard(dirFrom(rest, 0)));
+      if (lines.length) process.stdout.write(lines.join("\n") + "\n");
+      break;
+    }
     case "card": {
       const dir = dirFrom(rest, 1);
       process.stdout.write(JSON.stringify(findCard(loadBoard(dir), rest[0]), null, 2) + "\n");
@@ -272,6 +338,8 @@ try {
       if (opts.deps !== undefined) fields.deps = opts.deps.split(",").map((d) => d.trim()).filter(Boolean);
       if (opts.tag !== undefined) fields.tags = opts.tag.split(",").map((t) => t.trim()).filter(Boolean);
       if (opts.source !== undefined) fields.source = opts.source;
+      if (opts.epic !== undefined) fields.epic = opts.epic === "" ? null : opts.epic;
+      if (opts.milestone !== undefined) fields.milestone = opts.milestone === "" ? null : opts.milestone;
       const changed = EDIT_FIELD_ORDER.filter((k) => Object.prototype.hasOwnProperty.call(fields, k));
       if (!changed.length) fail(EDIT_USAGE, 2);
       const dir = dirFrom(rest, 1);
@@ -282,6 +350,47 @@ try {
       process.stdout.write(`Edited ${id} (${changed.join(", ")}) in ${relative(dir, boardPath(dir))}.\n`);
       break;
     }
+    case "epic":
+    case "milestone": {
+      const [action, id] = rest;
+      const add = cmd === "epic" ? addEpic : addMilestone;
+      const edit = cmd === "epic" ? editEpic : editMilestone;
+      const targetOf = () => {
+        const t = {};
+        if (opts.version !== undefined) t.version = opts.version === "" ? null : opts.version;
+        if (opts.date !== undefined) t.date = opts.date === "" ? null : opts.date;
+        return t;
+      };
+      if (action === "list") {
+        const board = loadBoard(dirFrom(rest, 1));
+        process.stdout.write(JSON.stringify(board[`${cmd}s`] || [], null, 2) + "\n");
+        break;
+      }
+      if (!id) fail(planUsage(cmd), 2);
+      if (action === "add") {
+        if (!opts.title || !opts.goal) fail(planUsage(cmd), 2);
+        const dir = dirFrom(rest, 2);
+        const target = {};
+        if (opts.version) target.version = opts.version;
+        if (opts.date) target.date = opts.date;
+        saveBoard(dir, add(loadBoard(dir), { id, title: opts.title, goal: opts.goal, ...(Object.keys(target).length ? { target } : {}) }));
+        process.stdout.write(`Added ${cmd} ${id} in ${relative(dir, boardPath(dir))}.\n`);
+        break;
+      }
+      const fields = {};
+      if (opts.title !== undefined) fields.title = opts.title;
+      if (opts.goal !== undefined) fields.goal = opts.goal;
+      if (opts.status !== undefined) fields.status = opts.status;
+      const target = targetOf();
+      if (Object.keys(target).length) fields.target = target;
+      if (!Object.keys(fields).length) fail(planUsage(cmd), 2);
+      const dir = dirFrom(rest, 2);
+      const { board, warnings } = edit(loadBoard(dir), id, fields, { force: !!opts.force });
+      saveBoard(dir, board);
+      for (const w of warnings) process.stderr.write(`warning: ${w}\n`);
+      process.stdout.write(`Edited ${cmd} ${id} (${Object.keys(fields).join(", ")}) in ${relative(dir, boardPath(dir))}.\n`);
+      break;
+    }
     case "remove": {
       const [id] = rest;
       if (!id) fail("usage: board.mjs remove <id> [dir] [--force]", 2);
@@ -389,7 +498,7 @@ try {
       break;
     }
     default:
-      fail("usage: board.mjs <next|card|reorder|move|edit|remove|record|summary> ...", 2);
+      fail("usage: board.mjs <next|card|reorder|move|edit|epic|milestone|rollup|labels|remove|record|summary> ...", 2);
   }
 } catch (err) {
   fail(err.message);

package/node_modules/@dougharness/flow/scripts/cost.mjs

@@ -14,13 +14,14 @@
 //     --claude-dir <path> where ~/.claude lives (tests point it at a fixture)
 //     --report <path>     a saved workflow report (card adversary-usage-in-report): prices its adversary relays'
 //                         Codex usage as a separate line/`codex` key, never mixed into the Claude total; default
-//                         <dir>/REPORT_RELPATH (the last report any run wrote there, not necessarily this run's -
-//                         the report carries no run id) when no --report is given and that file is readable
+//                         <dir>/REPORT_RELPATH when no --report is given and that file is readable. A report is
+//                         attached only when its top-level runId equals the run asked for; a report with no runId
+//                         is attached only when named with --report (card cost-run-codex-line-mismatch)
 // Exit 1 when the run's journal cannot be found, or an explicit --report cannot be read/parsed; the text output ends
 // with the run total and any unpriced agent. An unreadable/invalid default report is ignored, not a usage error.
 import { readFileSync } from "node:fs";
 import { resolve, join } from "node:path";
-import { costRun, costSession, renderSession, renderCost, costByCard, renderCostByCard } from "../lib/cost.mjs";
+import { reportForRun, costRun, costSession, renderSession, renderCost, costByCard, renderCostByCard } from "../lib/cost.mjs";
 import { planFor, REPORT_RELPATH, unwrapReport } from "../lib/plan.mjs";
 
 const argv = process.argv.slice(2);
@@ -81,6 +82,8 @@ try {
       reportPath = null;
     }
   }
+  report = reportForRun(report, runId, { named: Boolean(opts.report) });
+  if (!report) reportPath = null;
   const result = costRun({ runId, projectDir, claudeDir: opts["claude-dir"] ? resolve(opts["claude-dir"]) : undefined, report, reportPath });
   const byCard = opts["by-card"] ? costByCard(result, planFor(projectDir, opts.card)) : null;
   if (opts.json) process.stdout.write(JSON.stringify(byCard ? { ...result, byCard } : result, null, 2) + "\n");