@dougharness/cli 1.0.1

package/node_modules/@dougharness/flow/lib/worktrees.mjs

@@ -0,0 +1,215 @@
+// Shared helper for removing finished task worktrees, used by plan.mjs land and plan.mjs replan.
+// A worktree is a candidate only when it is registered under `git worktree list --porcelain`, its
+// real path (fs.realpathSync, so /var vs /private/var on macOS never causes a miss) sits strictly
+// inside realpath(realpath(dir)/.claude/worktrees) — itself realpath'd, and never equal to that
+// worktrees directory — it is not the main worktree or a path in `keep`, and it has a branch
+// (detached worktrees are never touched). It qualifies for removal when its branch is one of
+// `branches`, or `mergedInto` is a string and the branch is an ancestor of it. Qualifying worktrees
+// are removed with `git worktree remove` (no --force); a refusal (modified/untracked files, or any
+// other error) leaves the worktree in place and reports it as kept. This helper never deletes branches.
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+
+function git(dir, args) {
+  return execFileSync("git", args, { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 60000 }).trim();
+}
+
+function tryGit(dir, args) {
+  try {
+    return git(dir, args);
+  } catch (err) {
+    return { error: err };
+  }
+}
+
+function lastNonEmptyLine(text) {
+  const lines = String(text || "").trimEnd().split("\n").filter((l) => l.trim());
+  return lines.length ? lines[lines.length - 1].trim() : "git worktree remove failed";
+}
+
+function realpathOrSelf(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+// Parses the plain (newline-delimited) output of `git worktree list --porcelain`. Deliberately not
+// the -z form: that needs git 2.36+ and this helper must work on older git too. Each block is a
+// run of non-blank lines ("worktree <path>", "HEAD <sha>", then either "branch refs/heads/<name>"
+// or "detached"), and blocks are separated by a blank line. A "worktree " line always starts a new
+// block. Every path Doug's own workflow creates under .claude/worktrees never contains a newline,
+// so this parser does not attempt to reassemble a path that spans multiple raw lines: a worktree
+// whose pathname contains a literal newline is unsupported (not a defect) and is simply not handled.
+function parsePorcelain(text) {
+  const lines = String(text || "").split("\n");
+  const out = [];
+  let cur = null;
+  const flush = () => {
+    if (cur && cur.path) out.push({ path: cur.path, branch: cur.detached ? null : cur.branch || null });
+    cur = null;
+  };
+  for (const line of lines) {
+    if (line.startsWith("worktree ")) {
+      flush();
+      cur = { path: line.slice("worktree ".length) };
+      continue;
+    }
+    if (line === "") {
+      flush();
+      continue;
+    }
+    if (!cur) continue;
+    if (line.startsWith("branch ")) cur.branch = line.slice("branch refs/heads/".length);
+    else if (line === "detached") cur.detached = true;
+  }
+  flush();
+  return out;
+}
+
+// Returns { removed: string[], kept: { path, reason }[] }.
+export function removeFinishedWorktrees(dir, { branches = [], mergedInto = null, keep = [] } = {}) {
+  const result = { removed: [], kept: [] };
+  const listing = tryGit(dir, ["worktree", "list", "--porcelain"]);
+  if (listing && listing.error) return result;
+
+  const worktrees = parsePorcelain(listing);
+
+  const rootReal = realpathOrSelf(dir);
+  const worktreesDirReal = realpathOrSelf(join(rootReal, ".claude", "worktrees"));
+  const baseDir = worktreesDirReal + sep;
+  const mainPath = worktrees.length ? worktrees[0].path : null;
+  const mainReal = mainPath ? realpathOrSelf(mainPath) : null;
+  // Resolve each keep entry against dir (never process.cwd()) before realpath'ing it.
+  const keepReal = new Set(keep.map((p) => realpathOrSelf(resolve(dir, p))));
+
+  for (const wt of worktrees) {
+    if (!wt.branch) continue; // detached, never touched
+    const real = realpathOrSelf(wt.path);
+    if (real === mainReal) continue;
+    if (real === worktreesDirReal) continue; // the worktrees dir itself is not inside itself
+    if (!(real + sep).startsWith(baseDir)) continue;
+    if (keepReal.has(real)) continue;
+
+    const inBranches = branches.includes(wt.branch);
+    const isMerged = typeof mergedInto === "string" && tryGit(dir, ["merge-base", "--is-ancestor", wt.branch, mergedInto]) === "";
+    if (!inBranches && !isMerged) continue;
+
+    const removal = tryGit(dir, ["worktree", "remove", wt.path]);
+    if (removal && removal.error) {
+      const stderr = removal.error.stderr || removal.error.message || "";
+      result.kept.push({ path: wt.path, reason: lastNonEmptyLine(stderr) });
+    } else {
+      result.removed.push(wt.path);
+    }
+  }
+
+  tryGit(dir, ["worktree", "prune"]);
+  return result;
+}
+
+// The worktrees registered under .claude/worktrees that sit on a branch, as { path, branch }.
+function taskWorktrees(dir) {
+  const listing = tryGit(dir, ["worktree", "list", "--porcelain"]);
+  if (listing && listing.error) return [];
+  const rootReal = realpathOrSelf(dir);
+  const worktreesDirReal = realpathOrSelf(join(rootReal, ".claude", "worktrees"));
+  const baseDir = worktreesDirReal + sep;
+  const worktrees = parsePorcelain(listing);
+  const mainReal = worktrees.length ? realpathOrSelf(worktrees[0].path) : null;
+  return worktrees.filter((wt) => {
+    if (!wt.branch) return false;
+    const real = realpathOrSelf(wt.path);
+    return real !== mainReal && real !== worktreesDirReal && (real + sep).startsWith(baseDir);
+  });
+}
+
+// Everything uncommitted in a worktree as one patch: tracked changes against HEAD, then each untracked file as an
+// addition. Empty when the worktree is clean.
+function uncommittedDiff(wtPath) {
+  const parts = [];
+  const tracked = tryGit(wtPath, ["diff", "HEAD"]);
+  if (typeof tracked === "string" && tracked) parts.push(tracked);
+  const untracked = tryGit(wtPath, ["ls-files", "--others", "--exclude-standard"]);
+  for (const f of (typeof untracked === "string" ? untracked : "").split("\n").filter(Boolean)) {
+    // diff --no-index exits 1 when the files differ, which is the normal case here.
+    const r = spawnSync("git", ["diff", "--no-index", "--", "/dev/null", f], { cwd: wtPath, encoding: "utf8", timeout: 60000 });
+    if (r.stdout && r.stdout.trim()) parts.push(r.stdout.trim());
+  }
+  return parts.length ? parts.join("\n") + "\n" : "";
+}
+
+// The head commit of a local branch, or null when it does not exist. A resolver for lib/plan.mjs reusePlan and
+// staleReuseErrors (their optional `git.branchHead`), used to find a recorded reuse branch that a prior replan
+// renamed to `<branch>-stale-<n>`.
+export function branchHead(dir, name) {
+  const r = tryGit(dir, ["rev-parse", "--verify", "--quiet", `refs/heads/${name}`]);
+  return typeof r === "string" && r ? r : null;
+}
+
+// Whether `dir` is inside a git working tree at all, by git's own test (`git rev-parse --git-dir`) rather than
+// checking for a `.git` entry: that check misses a repo whose GIT_DIR is set elsewhere, or a `dir` that is inside
+// a repo but not at its root (a subdirectory has no `.git` of its own). scripts/plan.mjs uses this to decide
+// whether to hand reusePlan/staleReuseErrors a branchHead resolver at all.
+export function isGitRepo(dir) {
+  const r = tryGit(dir, ["rev-parse", "--git-dir"]);
+  return typeof r === "string" && !!r;
+}
+
+// The smallest n >= 1 for which <branch>-stale-<n> is not a branch yet.
+function staleName(dir, branch) {
+  for (let n = 1; ; n++) {
+    const name = `${branch}-stale-${n}`;
+    if (tryGit(dir, ["rev-parse", "--verify", "--quiet", `refs/heads/${name}`]).error) return name;
+  }
+}
+
+// Retires the worktree and branch of every task replan marks fresh (card replan-clean-worktrees, 2026-09-07): the
+// worktree's uncommitted work is saved to <saveDir>/<task id>.diff first (only when there is any), the worktree is
+// removed with --force, and the branch is renamed to <branch>-stale-<n> so the next run's git checkout -b finds the
+// name free. Nothing is ever deleted: a branch is renamed, never removed. A task whose branch no longer exists, or
+// whose worktree is already gone, is skipped without error.
+// Returns { removed: string[], saved: { task, path }[], renamed: { task, from, to }[] }.
+export function retireTaskWorktrees(dir, { tasks = [], saveDir }) {
+  const result = { removed: [], saved: [], renamed: [] };
+  const worktrees = taskWorktrees(dir);
+  for (const t of tasks) {
+    if (!t || typeof t.branch !== "string" || !t.branch) continue;
+    for (const wt of worktrees.filter((w) => w.branch === t.branch)) {
+      const diff = uncommittedDiff(wt.path);
+      if (diff) {
+        mkdirSync(saveDir, { recursive: true });
+        const file = join(saveDir, `${t.id}.diff`);
+        writeFileSync(file, diff);
+        result.saved.push({ task: t.id, path: file });
+      }
+      const removal = tryGit(dir, ["worktree", "remove", "--force", wt.path]);
+      if (!(removal && removal.error)) result.removed.push(wt.path);
+    }
+    if (tryGit(dir, ["rev-parse", "--verify", "--quiet", `refs/heads/${t.branch}`]).error) continue;
+    const to = staleName(dir, t.branch);
+    const rename = tryGit(dir, ["branch", "-m", t.branch, to]);
+    if (!(rename && rename.error)) result.renamed.push({ task: t.id, from: t.branch, to });
+  }
+  tryGit(dir, ["worktree", "prune"]);
+  return result;
+}
+
+// Retires the integration worktree at .claude/worktrees/doug-integration, if one is registered (card
+// integration-worktree-stale, 2026-09-08): a leftover from an abandoned run must not survive into the next one,
+// since the workflow's own leftover-vs-this-run's-own check (integratePrompt's firstIntegration) only runs inside
+// a run already underway. Removed with --force; the branch is never renamed or deleted (the workflow's
+// `git worktree add -B` on the next run's first integration resets it from the base branch). A worktree that is
+// not there is not an error.
+// Returns { removed: string | null } - the path removed, or null when none was registered.
+export function retireIntegrationWorktree(dir) {
+  const target = join(realpathOrSelf(dir), ".claude", "worktrees", "doug-integration");
+  const match = taskWorktrees(dir).find((wt) => realpathOrSelf(wt.path) === realpathOrSelf(target));
+  if (!match) return { removed: null };
+  const removal = tryGit(dir, ["worktree", "remove", "--force", match.path]);
+  tryGit(dir, ["worktree", "prune"]);
+  return { removed: removal && removal.error ? null : match.path };
+}

package/node_modules/@dougharness/flow/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@dougharness/flow",
+  "version": "1.0.1",
+  "private": true,
+  "description": "Plan, approve, implement one task per worktree, verify, review: a Workflow-tool template and subagents for Claude Code.",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "agents",
+    "skills",
+    "workflows",
+    "scripts",
+    "lib",
+    ".claude-plugin"
+  ],
+  "engines": {
+    "node": ">=22.16"
+  }
+}

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

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+// CLI for the development board, used by the /doug-next and /core-next skills. Deterministic; no agents.
+//   board.mjs next [dir] [--track flow|hand] [--tag <tag>]
+//                                                 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] [--tag <tag>]
+//                                                 the first n runnable Ready cards, in board order, as a JSON array
+//                                                 (exit 1 if none): the cards /doug-next plans together
+//   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]
+//                                                 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
+//   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
+//                                                 and prints a warning to stderr); prints the removed card as JSON
+//                                                 to stdout so a mistaken removal can be re-added by hand
+//   board.mjs record <id> <report.json> [dir] [--cost <usd>] [--codex-cost <usd>] [--shared-cost <usd>] [--wall <text>] [--commit <sha>] [--adversary "<id>=<class>[: <reason>]"]... [--note <text>] [--rehearsal <scenario>]
+//                                                 append a run entry for the card to docs/live-runs.md; every adversary block
+//                                                 in the report is classified real, marginal, or false (repeat the flag per block).
+//                                                 When .doug/plan.json lists the card among its `cards` (a batch), the entry
+//                                                 shows only that card's tasks, --cost is that card's tasks' cost, and
+//                                                 --shared-cost <usd> the shared integration agents', counted once
+//   board.mjs record <id> --hand [dir] [--commit <sha>] [--wall <text>] [--gate <text>] [--note <text>] [--rehearsal <scenario>]
+//                                                 append a hand-track entry (no report) for the card
+//   --rehearsal <scenario> (either form) marks the entry as a rehearse.mjs run on the ts-basic fixture: the first
+//   prose line and the commit sha (abbreviated to 7 characters) read as the fixture's, not this repository's.
+//   Either record form also promotes .doug/.state/research/<id>.md to docs/research/<id>.md when that note
+//   exists and differs from the docs copy, copying it and printing one line saying so; a card with no note, or
+//   whose docs copy is already byte-identical, is untouched, silently.
+//   board.mjs summary <report.json> [--cost <usd>] [--codex-cost <usd>] [--wall <text>] [--commit <sha>] [--card <id>]
+//                                                 the three-line chat summary of a report (--card: that card's tasks only)
+
+import { readFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { loadBoard, saveBoard, findCard, nextReadyCard, nextReadyCards, moveCard, editCard, removeCard, reorderCard, runEntry, handEntry, runSummary, boardPath, parseAdversaryClasses, filterReportForCard, recordLanding } from "../lib/board.mjs";
+import { loadPlan, unwrapReport } from "../lib/plan.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 argv = process.argv.slice(2);
+const FLAGS = new Set(["hand", "top", "bottom", "force"]);
+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"],
+  card: [],
+  move: ["source"],
+  edit: ["title", "goal", "goal-file", "size", "component", "track", "class", "deps", "tag", "source", "force"],
+  remove: ["force"],
+  reorder: ["before", "after", "top", "bottom"],
+  summary: ["cost", "codex-cost", "wall", "commit", "card"],
+};
+const RECORD_HAND_FLAGS = ["hand", "commit", "wall", "gate", "note", "rehearsal"];
+const RECORD_REPORT_FLAGS = ["cost", "codex-cost", "wall", "commit", "adversary", "shared-cost", "note", "rehearsal"];
+const opts = {};
+const positional = [];
+for (let i = 0; i < argv.length; i++) {
+  if (!argv[i].startsWith("--")) {
+    positional.push(argv[i]);
+    continue;
+  }
+  const name = argv[i].slice(2);
+  if (FLAGS.has(name)) {
+    opts[name] = true;
+    continue;
+  }
+  if (REPEATABLE.has(name)) (opts[name] ||= []).push(argv[i + 1] ?? "");
+  else opts[name] = argv[i + 1] ?? "";
+  i++;
+}
+const [cmd, ...rest] = positional;
+
+function fail(msg, code = 1) {
+  process.stderr.write(msg + "\n");
+  process.exit(code);
+}
+
+const USAGE_FOR = {
+  next: "usage: board.mjs next [dir] [--track flow|hand] [--batch <n>] [--tag <tag>]",
+  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",
+  summary: "usage: board.mjs summary <report.json> [--cost <usd>] [--codex-cost <usd>] [--wall <text>] [--commit <sha>] [--card <id>]",
+};
+const RECORD_HAND_USAGE = "usage: board.mjs record <id> --hand [dir] [--commit <sha>] [--wall <text>] [--gate <text>] [--note <text>] [--rehearsal <scenario>]";
+const RECORD_REPORT_USAGE = "usage: board.mjs record <id> <report.json> [dir] [--cost <usd>] [--codex-cost <usd>] [--shared-cost <usd>] [--wall <text>] [--commit <sha>] [--adversary \"<id>=<class>[: <reason>]\"]... [--note <text>] [--rehearsal <scenario>]";
+
+// An unknown --flag for the given subcommand: exit 2, name the flag and the subcommand's usage.
+// Runs on flag names only (parse order doesn't matter), before any work or write.
+function unknownFlagFor(cmd, opts) {
+  const allowed = new Set(cmd === "record" ? (opts.hand ? RECORD_HAND_FLAGS : RECORD_REPORT_FLAGS) : SUBCOMMAND_FLAGS[cmd] || []);
+  for (const name of Object.keys(opts)) {
+    if (!allowed.has(name)) return name;
+  }
+  return undefined;
+}
+
+function dirFrom(args, n) {
+  return resolve(process.env.CLAUDE_PROJECT_DIR || args[n] || process.cwd());
+}
+
+if (cmd === "record" || Object.prototype.hasOwnProperty.call(SUBCOMMAND_FLAGS, cmd)) {
+  const unknown = unknownFlagFor(cmd, opts);
+  if (unknown !== undefined) {
+    const usageLine = cmd === "record" ? (opts.hand ? RECORD_HAND_USAGE : RECORD_REPORT_USAGE) : USAGE_FOR[cmd];
+    fail(`unknown option --${unknown} for board.mjs ${cmd}\n${usageLine}`, 2);
+  }
+}
+
+try {
+  switch (cmd) {
+    case "next": {
+      const dir = dirFrom(rest, 0);
+      const track = opts.track === "hand" ? "hand" : "flow";
+      if (opts.track !== undefined && opts.track !== "flow" && opts.track !== "hand") fail(`unknown track "${opts.track}"; tracks are flow, hand`, 2);
+      const batch = opts.batch !== undefined ? Number(opts.batch) : null;
+      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 });
+      for (const s of skipped) process.stderr.write(s.hand ? `skipping ${s.id}: hand track (built by hand with /core-next, not by doug-next)\n` : s.flow ? `skipping ${s.id}: flow track (run it with /doug-next)\n` : `skipping ${s.id}: waiting on ${s.waitingOn.join(", ")}\n`);
+      if (batch === null ? !card : !cards.length) fail(track === "hand" ? "No Ready hand-track card whose dependencies are Done." : "No Ready card whose dependencies are Done.");
+      process.stdout.write(JSON.stringify(batch === null ? card : cards, null, 2) + "\n");
+      break;
+    }
+    case "card": {
+      const dir = dirFrom(rest, 1);
+      process.stdout.write(JSON.stringify(findCard(loadBoard(dir), rest[0]), null, 2) + "\n");
+      break;
+    }
+    case "move": {
+      const [id, column] = rest;
+      if (!id || !column) fail("usage: board.mjs move <id> <column> [dir] [--source <text>]", 2);
+      const dir = dirFrom(rest, 2);
+      saveBoard(dir, moveCard(loadBoard(dir), id, column, { source: opts.source }));
+      process.stdout.write(`Moved ${id} to ${column} in ${relative(dir, boardPath(dir))}.\n`);
+      break;
+    }
+    case "edit": {
+      const [id] = rest;
+      if (!id) fail(EDIT_USAGE, 2);
+      if (opts.goal !== undefined && opts["goal-file"] !== undefined) fail(EDIT_USAGE, 2);
+      const fields = {};
+      if (opts.title !== undefined) fields.title = opts.title;
+      if (opts.goal !== undefined) fields.goal = opts.goal;
+      if (opts["goal-file"] !== undefined) fields.goal = readFileSync(resolve(opts["goal-file"]), "utf8").trimEnd();
+      if (opts.size !== undefined) fields.size = opts.size;
+      if (opts.component !== undefined) fields.component = opts.component;
+      if (opts.track !== undefined) fields.track = opts.track;
+      if (opts.class !== undefined) fields.class = opts.class;
+      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;
+      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);
+      const plan = loadPlan(dir);
+      const { board, warnings } = editCard(loadBoard(dir), id, fields, { force: !!opts.force, plan });
+      saveBoard(dir, board);
+      for (const w of warnings) process.stderr.write(`warning: ${w}\n`);
+      process.stdout.write(`Edited ${id} (${changed.join(", ")}) in ${relative(dir, boardPath(dir))}.\n`);
+      break;
+    }
+    case "remove": {
+      const [id] = rest;
+      if (!id) fail("usage: board.mjs remove <id> [dir] [--force]", 2);
+      const dir = dirFrom(rest, 1);
+      const plan = loadPlan(dir);
+      const { board, removed, warnings } = removeCard(loadBoard(dir), id, { force: !!opts.force, plan });
+      saveBoard(dir, board);
+      for (const w of warnings) process.stderr.write(`warning: ${w}\n`);
+      process.stdout.write(`Removed ${id} (${removed.column}) from ${relative(dir, boardPath(dir))}.\n`);
+      process.stdout.write(JSON.stringify(removed, null, 2) + "\n");
+      break;
+    }
+    case "reorder": {
+      const [id] = rest;
+      const optionCount = ["before", "after", "top", "bottom"].filter((k) => opts[k] !== undefined).length;
+      const validValue = (v) => typeof v === "string" && v !== "" && !v.startsWith("--");
+      const badValue = (opts.before !== undefined && !validValue(opts.before)) || (opts.after !== undefined && !validValue(opts.after));
+      if (!id || optionCount !== 1 || badValue) fail("usage: board.mjs reorder <id> [dir] --before <other> | --after <other> | --top | --bottom", 2);
+      const dir = dirFrom(rest, 1);
+      const board = loadBoard(dir);
+      const card = findCard(board, id);
+      const record = relative(dir, boardPath(dir));
+      let placement, message;
+      if (opts.before !== undefined) {
+        placement = { before: opts.before };
+        message = `Reordered ${id} before ${opts.before} in ${record}.\n`;
+      } else if (opts.after !== undefined) {
+        placement = { after: opts.after };
+        message = `Reordered ${id} after ${opts.after} in ${record}.\n`;
+      } else if (opts.top) {
+        placement = { index: 0 };
+        message = `Reordered ${id} to the top of ${card.column} in ${record}.\n`;
+      } else {
+        placement = { index: board.cards.filter((c) => c.column === card.column).length };
+        message = `Reordered ${id} to the bottom of ${card.column} in ${record}.\n`;
+      }
+      saveBoard(dir, reorderCard(board, id, placement));
+      process.stdout.write(message);
+      break;
+    }
+    case "record": {
+      if (opts.hand) {
+        const [id] = rest;
+        if (!id) fail("usage: board.mjs record <id> --hand [dir] [--commit <sha>] [--wall <text>] [--gate <text>] [--note <text>] [--rehearsal <scenario>]", 2);
+        const dir = dirFrom(rest, 1);
+        const card = findCard(loadBoard(dir), id);
+        const entry = handEntry({ card, commit: opts.commit ?? null, wallClock: opts.wall ?? null, gate: opts.gate ?? null, note: opts.note ?? null, record: relative(dir, boardPath(dir)), rehearsal: opts.rehearsal ?? null });
+        const { file, promoted } = recordLanding(dir, id, entry);
+        if (promoted) process.stdout.write(`Promoted the research note for ${id} to ${promoted}.\n`);
+        process.stdout.write(`Appended a hand-track entry for ${id} to ${file}.\n`);
+        break;
+      }
+      const [id, reportFile] = rest;
+      if (!id || !reportFile) fail("usage: board.mjs record <id> <report.json> [dir] [--cost <usd>] [--codex-cost <usd>] [--shared-cost <usd>] [--wall <text>] [--commit <sha>] [--adversary \"<id>=<class>[: <reason>]\"]... [--note <text>] [--rehearsal <scenario>]", 2);
+      const dir = dirFrom(rest, 2);
+      const card = findCard(loadBoard(dir), id);
+      const report = unwrapReport(JSON.parse(readFileSync(resolve(reportFile), "utf8")));
+      // A batch plan (its `cards` list this card) makes the entry that card's part of the run.
+      const plan = loadPlan(dir);
+      const batch = plan && Array.isArray(plan.cards) && plan.cards.includes(id) ? plan.cards : null;
+      const taskIds = batch ? plan.tasks.filter((t) => t.card === id).map((t) => t.id) : [];
+      const entry = runEntry({ card, report, cost: opts.cost !== undefined ? Number(opts.cost) : null, codexCost: opts["codex-cost"] !== undefined ? Number(opts["codex-cost"]) : null, wallClock: opts.wall ?? null, mergeCommit: opts.commit ?? null, record: relative(dir, boardPath(dir)), adversary: parseAdversaryClasses(opts.adversary || []), batch, taskIds, sharedCost: opts["shared-cost"] !== undefined ? Number(opts["shared-cost"]) : null, note: opts.note ?? null, rehearsal: opts.rehearsal ?? null });
+      const { file, promoted } = recordLanding(dir, id, entry);
+      if (promoted) process.stdout.write(`Promoted the research note for ${id} to ${promoted}.\n`);
+      process.stdout.write(`Appended a run entry for ${id} to ${file}.\n`);
+      break;
+    }
+    case "summary": {
+      const [reportFile] = rest;
+      if (!reportFile) fail("usage: board.mjs summary <report.json> [--cost <usd>] [--codex-cost <usd>] [--wall <text>] [--commit <sha>] [--card <id>]", 2);
+      let report = unwrapReport(JSON.parse(readFileSync(resolve(reportFile), "utf8")));
+      if (opts.card !== undefined) {
+        // With the plan at hand the filter also covers a report whose tasks carry no card.
+        const plan = loadPlan(dirFrom(rest, 1));
+        report = filterReportForCard(report, opts.card, plan && Array.isArray(plan.tasks) ? plan.tasks.filter((t) => t.card === opts.card).map((t) => t.id) : []);
+      }
+      process.stdout.write(runSummary({ report, cost: opts.cost !== undefined ? Number(opts.cost) : null, codexCost: opts["codex-cost"] !== undefined ? Number(opts["codex-cost"]) : null, wallClock: opts.wall ?? null, mergeCommit: opts.commit ?? null }));
+      break;
+    }
+    default:
+      fail("usage: board.mjs <next|card|reorder|move|edit|remove|record|summary> ...", 2);
+  }
+} catch (err) {
+  fail(err.message);
+}

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

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// Real cost of one doug-implement run from the local Claude Code transcripts; no network, nothing estimated.
+//   cost.mjs <run-id> [dir] [--json] [--claude-dir <path>]
+//     <run-id>            the Workflow run id (wf_...)
+//     [dir]               the project directory whose ~/.claude/projects slug is searched first (default cwd)
+//     --json              print the full result as JSON instead of the text tables
+//     --by-card           a batch run (the plan at [dir] lists `cards`): add the per-card table, each card's tasks'
+//                         agents summed for that card and the shared integration agents listed once (`byCard` in --json)
+//     --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
+// 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, renderCost, costByCard, renderCostByCard } from "../lib/cost.mjs";
+import { loadPlan, REPORT_RELPATH, unwrapReport } from "../lib/plan.mjs";
+
+const argv = process.argv.slice(2);
+const FLAGS = new Set(["json", "by-card"]);
+const opts = {};
+const positional = [];
+for (let i = 0; i < argv.length; i++) {
+  if (!argv[i].startsWith("--")) {
+    positional.push(argv[i]);
+    continue;
+  }
+  const name = argv[i].slice(2);
+  if (FLAGS.has(name)) {
+    opts[name] = true;
+    continue;
+  }
+  opts[name] = argv[i + 1] ?? "";
+  i++;
+}
+const [runId, dirArg] = positional;
+if (!runId) {
+  process.stderr.write("usage: cost.mjs <run-id> [dir] [--json] [--claude-dir <path>]\n");
+  process.exit(2);
+}
+try {
+  const projectDir = resolve(process.env.CLAUDE_PROJECT_DIR || dirArg || process.cwd());
+  let reportPath = opts.report ? resolve(opts.report) : join(projectDir, REPORT_RELPATH);
+  let report = null;
+  if (opts.report) {
+    report = unwrapReport(JSON.parse(readFileSync(reportPath, "utf8")));
+  } else {
+    // The default report is whichever run last wrote it, not necessarily this run's; missing, unreadable, or
+    // invalid JSON there is not this command's problem, so it is ignored rather than failing the whole run.
+    try {
+      report = unwrapReport(JSON.parse(readFileSync(reportPath, "utf8")));
+    } catch {
+      report = null;
+      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, loadPlan(projectDir)) : null;
+  if (opts.json) process.stdout.write(JSON.stringify(byCard ? { ...result, byCard } : result, null, 2) + "\n");
+  else process.stdout.write(renderCost(result) + (byCard ? "\n" + renderCostByCard(byCard) : ""));
+} catch (err) {
+  process.stderr.write(err.message + "\n");
+  process.exit(1);
+}