@dougharness/cli 1.1.1 → 1.2.0

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

@@ -22,7 +22,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { acceptanceEntries, integrationBranchFor, savePlan } from "./plan.mjs";
+import { acceptanceEntries, integrationBranchFor, integrationWorktreeFor, savePlan, PLAN_RELPATH } from "./plan.mjs";
 import { removeFinishedWorktrees } from "./worktrees.mjs";
 
 export const INTEGRATION_WORKTREE = ".claude/worktrees/doug-integration";
@@ -109,7 +109,7 @@ function verifyViaVendored(script, dir, work, commands, timeoutMs) {
       const why = r.error && r.error.code === "ETIMEDOUT" ? "timed out" : "gave no readable result";
       return { error: `the vendored verify.mjs ${why}; land does not re-run the commands` };
     }
-    return out.results.map((x) => ({
+    const rows = out.results.map((x) => ({
       command: x.command,
       ok: x.ok === true,
       status: x.status,
@@ -118,13 +118,20 @@ function verifyViaVendored(script, dir, work, commands, timeoutMs) {
       outputTail: x.outputTail || "",
       ...(out.credited ? { credited: out.credited } : {}),
     }));
+    if (typeof out.lockWaitMs === "number") rows.lockWaitMs = out.lockWaitMs;
+    return rows;
   } catch (err) {
     return { error: `the vendored verify.mjs could not run: ${err && err.message}` };
   }
 }
 
 // Returns { ok: true, base, branch, mergeCommit, verify } or { ok: false, reason, verify? }. Never throws on a refusal.
-export function landPlan(dir, plan, { timeoutMs = 600000, now = () => new Date(), deleteBranches = false } = {}) {
+// Card parallel-card-queens B5: rebase (set by plan.mjs land --card) rebases the integration branch onto the base
+// when the base has moved, in the worktree that has the branch checked out, and verifies the rebased tree; a
+// conflict is aborted and refused as "rebase-conflict: <files>". ownOnly removes only this plan's own task
+// branches' worktrees and its own integration worktree (no sweep of worktrees merged into base). planRelpath is
+// where plan.landed is saved (the per-card plan under --card). The result carries lockWaitMs from verify.mjs.
+export function landPlan(dir, plan, { timeoutMs = 600000, now = () => new Date(), deleteBranches = false, rebase = false, ownOnly = false, planRelpath = PLAN_RELPATH } = {}) {
   if (!plan) return { ok: false, reason: "no plan" };
   if (plan.status !== "done") return { ok: false, reason: `plan status is "${plan.status}", not "done"; run plan.mjs done after a green doug-implement run` };
   if (plan.landed) return { ok: false, reason: `plan was already landed as ${plan.landed.mergeCommit} on ${plan.landed.at}` };
@@ -152,15 +159,17 @@ export function landPlan(dir, plan, { timeoutMs = 600000, now = () => new Date()
   if (dirty.length) return { ok: false, reason: `tracked files are modified: ${dirty.join(", ")}; commit or stash them first` };
 
   // Verify on the branch itself, in the integration worktree if the workflow left it, else a temporary one.
-  const existing = join(dir, INTEGRATION_WORKTREE);
+  const existing = join(dir, integrationWorktreeFor(plan));
   const reuse = existsSync(existing) && tryGit(existing, ["symbolic-ref", "--short", "-q", "HEAD"]) === branch;
   let work = reuse ? existing : null;
   let temp = null;
+  const needsRebase = rebase && tryGit(dir, ["merge-base", "--is-ancestor", base, branch]) === null;
   if (!work) {
     temp = mkdtempSync(join(tmpdir(), "doug-land-"));
     work = join(temp, "wt");
     try {
-      git(dir, ["worktree", "add", "--detach", work, branch]);
+      // A rebase moves the branch ref, so the temporary worktree then has the branch itself checked out.
+      git(dir, needsRebase ? ["worktree", "add", work, branch] : ["worktree", "add", "--detach", work, branch]);
     } catch (err) {
       rmSync(temp, { recursive: true, force: true });
       return { ok: false, reason: `could not create a worktree for ${branch}: ${tail(err.stderr || err.message, 3)}` };
@@ -168,7 +177,16 @@ export function landPlan(dir, plan, { timeoutMs = 600000, now = () => new Date()
   }
   const verify = [];
   const acceptance = [];
+  let lockWaitMs;
   try {
+    if (needsRebase) {
+      const rb = tryGitCapture(work, ["rebase", base]);
+      if (!rb.ok) {
+        const files = (tryGit(work, ["diff", "--name-only", "--diff-filter=U"]) || "").split("\n").filter(Boolean);
+        tryGit(work, ["rebase", "--abort"]);
+        return { ok: false, reason: `rebase-conflict: ${files.length ? files.join(", ") : tail(rb.error.stderr || rb.error.message, 3)}` };
+      }
+    }
     // card verified-tree-record: install always runs through run(). plan.verify goes through the vendored
     // verify.mjs when the project has one (it credits a verified-tree record of the branch's tree and writes one
     // for the main checkout after a green run); otherwise, or when it cannot be read, today's loop runs.
@@ -189,6 +207,7 @@ export function landPlan(dir, plan, { timeoutMs = 600000, now = () => new Date()
       return { ok: false, reason: `verify failed on ${branch}: ${viaVerify.error}`, verify, acceptance: [] };
     }
     if (viaVerify) {
+      if (typeof viaVerify.lockWaitMs === "number") lockWaitMs = viaVerify.lockWaitMs;
       for (const r of viaVerify) {
         verify.push(r);
         if (!r.ok) return failVerify(r);
@@ -249,7 +268,7 @@ export function landPlan(dir, plan, { timeoutMs = 600000, now = () => new Date()
     removedWorktrees.push(existingReal);
   }
   const taskBranches = (plan.tasks || []).flatMap((t) => [`doug/task-${t.id}`, ...(typeof t.reuse === "string" ? [t.reuse] : [])]);
-  const wtResult = removeFinishedWorktrees(dir, { branches: taskBranches, mergedInto: base });
+  const wtResult = removeFinishedWorktrees(dir, { branches: taskBranches, mergedInto: ownOnly ? null : base });
   const worktrees = { removed: [...removedWorktrees, ...wtResult.removed], kept: wtResult.kept };
 
   const branchesResult = { deleted: [], kept: [] };
@@ -278,6 +297,6 @@ export function landPlan(dir, plan, { timeoutMs = 600000, now = () => new Date()
     verify: verify.map((v) => ({ command: v.command, ok: v.ok, durationMs: v.durationMs, ...(v.credited ? { credited: v.credited } : {}) })),
     acceptance: acceptance.map((a) => ({ text: a.text, command: a.command, ok: a.ok, durationMs: a.durationMs, ...(a.reused ? { reused: a.reused } : {}) })),
   };
-  savePlan(dir, { ...plan, landed });
-  return { ok: true, base, branch, mergeCommit, verify, acceptance, worktrees, branches: branchesResult };
+  savePlan(dir, { ...plan, landed }, planRelpath);
+  return { ok: true, base, branch, mergeCommit, verify, acceptance, worktrees, branches: branchesResult, ...(lockWaitMs !== undefined ? { lockWaitMs } : {}) };
 }

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

@@ -55,7 +55,8 @@ const LESSON_KINDS = ["feedback", "project", "pitfall", "pattern"];
 // row. On a hand row the following columns are NULL because they do not exist on that track — never because
 // they measured zero: run_id, spec_hash, files, size, shape, models, implemented, verified, reviewed,
 // review_issues, review_issue_count, adversary_verdict, adversary_blocked, adversary_source, blocks, passes,
-// fix_passes, stop_reason, in_scope, budget_spent, tokens, usd, codex_usd, report_hash, report_path, partial. In particular
+// fix_passes, stop_reason, stop_class, in_scope, budget_spent, tokens, codex_usd, report_hash, report_path, partial (usd too,
+// except that a hand landing recorded with --cost carries its measured session cost there; card usd-budget-size-class). In particular
 // verified is null on a hand row even though the gate passed: no independent verifier ran on that track, and
 // the gate's own text lives in the `gate` column instead. A consumer that averages fix_passes or counts
 // blocks across both tracks must filter on track. wall_clock, gate, and note only exist on a hand row; they
@@ -108,6 +109,7 @@ const OUTCOMES_COLUMNS_SQL = `
   tokens TEXT,
   usd REAL,
   codex_usd REAL,
+  stop_class TEXT,
   commit_sha TEXT,
   track TEXT NOT NULL DEFAULT 'flow',
   wall_clock TEXT,
@@ -399,6 +401,27 @@ function migrateV7ToV8(db) {
   }
 }
 
+// v8 had no stop_class column on outcomes (card memory-stop-class): the typed cause of a stop, from
+// task.stopClass, so stops can be counted by cause across runs. Additive like v7->v8: one guarded ALTER, then
+// the version bump; old rows stay null. OUTCOMES_COLUMNS_SQL carries stop_class for a v1 store's rebuild, so
+// this step is a no-op there instead of a duplicate-column error.
+const V9_STOP_COLUMNS = [["stop_class", "TEXT"]];
+
+function migrateV8ToV9(db) {
+  db.exec("BEGIN");
+  try {
+    const cols = db.prepare("PRAGMA table_info(outcomes)").all().map((c) => c.name);
+    for (const [name, type] of V9_STOP_COLUMNS) {
+      if (!cols.includes(name)) db.exec(`ALTER TABLE outcomes ADD COLUMN ${name} ${type};`);
+    }
+    db.exec("PRAGMA user_version = 9");
+    db.exec("COMMIT");
+  } catch (err) {
+    db.exec("ROLLBACK");
+    throw err;
+  }
+}
+
 export function openMemory(dir) {
   const file = memoryPath(dir);
   mkdirSync(dirname(file), { recursive: true });
@@ -407,7 +430,7 @@ export function openMemory(dir) {
   const version = db.prepare("PRAGMA user_version").get().user_version;
   if (version === 0) {
     db.exec(SCHEMA_SQL);
-    db.exec("PRAGMA user_version = 8");
+    db.exec("PRAGMA user_version = 9");
   } else if (version === 1) {
     migrateV1ToV2(db);
     migrateV2ToV3(db);
@@ -416,6 +439,7 @@ export function openMemory(dir) {
     migrateV5ToV6(db);
     migrateV6ToV7(db);
     migrateV7ToV8(db);
+    migrateV8ToV9(db);
   } else if (version === 2) {
     migrateV2ToV3(db);
     migrateV3ToV4(db);
@@ -423,29 +447,37 @@ export function openMemory(dir) {
     migrateV5ToV6(db);
     migrateV6ToV7(db);
     migrateV7ToV8(db);
+    migrateV8ToV9(db);
   } else if (version === 3) {
     migrateV3ToV4(db);
     migrateV4ToV5(db);
     migrateV5ToV6(db);
     migrateV6ToV7(db);
     migrateV7ToV8(db);
+    migrateV8ToV9(db);
   } else if (version === 4) {
     migrateV4ToV5(db);
     migrateV5ToV6(db);
     migrateV6ToV7(db);
     migrateV7ToV8(db);
+    migrateV8ToV9(db);
   } else if (version === 5) {
     migrateV5ToV6(db);
     migrateV6ToV7(db);
     migrateV7ToV8(db);
+    migrateV8ToV9(db);
   } else if (version === 6) {
     migrateV6ToV7(db);
     migrateV7ToV8(db);
+    migrateV8ToV9(db);
   } else if (version === 7) {
     migrateV7ToV8(db);
-  } else if (version !== 8) {
+    migrateV8ToV9(db);
+  } else if (version === 8) {
+    migrateV8ToV9(db);
+  } else if (version !== 9) {
     db.close();
-    throw new Error(`memory store ${file} is user_version ${version}; this code understands up to version 8`);
+    throw new Error(`memory store ${file} is user_version ${version}; this code understands up to version 9`);
   }
   return {
     file,
@@ -479,7 +511,7 @@ export function probeSqliteFts5() {
 // Read-only look at the store for `doug doctor`: creates nothing, migrates nothing, never throws.
 export function inspectMemory(dir) {
   const file = memoryPath(dir);
-  const out = { file, exists: false, userVersion: null, maxUserVersion: 8, quickCheck: null, error: null };
+  const out = { file, exists: false, userVersion: null, maxUserVersion: 9, quickCheck: null, error: null };
   if (!existsSync(file)) return out;
   out.exists = true;
   let db;
@@ -719,7 +751,7 @@ export function checkCitation(lesson, checkoutDir, { report } = {}) {
     }
     const taskId = rest.slice(0, slash);
     const blockId = rest.slice(slash + 1);
-    const found = adversaryBlocks(report).some((b) => b.task === taskId && b.id === blockId);
+    const found = adversaryBlocks(report).some((b) => b.task === taskId && (b.id === blockId || b.id === `${taskId}/${blockId}`));
     return found ? { ok: true, reason: "block holds" } : { ok: false, reason: `no block "${blockId}" of task "${taskId}" in this report` };
   }
   const match = citation.match(CITATION_RE);
@@ -1259,6 +1291,7 @@ export function outcomeRows(report, opts) {
         passes,
         fix_passes: fixPasses,
         stop_reason: task.stopReason ?? null,
+        stop_class: task.stopClass ?? null,
         in_scope: toIntOrNull(task.inScope),
         budget_spent: (task.budget && task.budget.spent) || null,
         tokens,
@@ -1329,7 +1362,7 @@ export function conditionConfigHash(dir) {
 // null when none was found: null fills every one of the seven condition columns with null, exactly like a row
 // that has never been stamped. `backfilled` is always 0 here — only `memory.mjs condition backfill`, which never
 // goes through this function, ever sets it to 1.
-export function handOutcomeRow({ card, commit, wallClock = null, gate = null, note = null, now = nowIso(), condition = null } = {}) {
+export function handOutcomeRow({ card, commit, wallClock = null, gate = null, note = null, now = nowIso(), condition = null, cost = null } = {}) {
   if (!card) throw new Error("handOutcomeRow requires card");
   if (!commit) throw new Error("handOutcomeRow requires commit");
   return {
@@ -1357,10 +1390,11 @@ export function handOutcomeRow({ card, commit, wallClock = null, gate = null, no
     passes: null,
     fix_passes: null,
     stop_reason: null,
+    stop_class: null,
     in_scope: null,
     budget_spent: null,
     tokens: null,
-    usd: null,
+    usd: typeof cost === "number" && Number.isFinite(cost) ? cost : null,
     codex_usd: null,
     commit_sha: commit,
     track: "hand",
@@ -1381,7 +1415,7 @@ export function handOutcomeRow({ card, commit, wallClock = null, gate = null, no
 const OUTCOME_COLUMNS = [
   "recorded", "run", "run_id", "report_hash", "report_path", "card", "task", "spec_hash", "files", "size", "shape",
   "models", "implemented", "verified", "reviewed", "review_issues", "review_issue_count", "adversary_verdict",
-  "adversary_blocked", "adversary_source", "blocks", "passes", "fix_passes", "stop_reason", "in_scope",
+  "adversary_blocked", "adversary_source", "blocks", "passes", "fix_passes", "stop_reason", "stop_class", "in_scope",
   "budget_spent", "tokens", "usd", "codex_usd", "commit_sha", "track", "wall_clock", "gate", "note", "partial",
   "harness_commit", "config_hash", "class", "arm", "assigned_by", "explore_probability", "backfilled",
 ];
@@ -1507,7 +1541,7 @@ function reflectionRowToObject(row) {
 // Deterministic, no LLM. harmful is an explicit mark (card reflect-harmful-irrelevant-lessons): only an id in
 // `harmfulIds` (the lead's judgement that the lesson misled the work) gets harmful +1, once however often it is
 // named or used; a real block alone bumps nothing. For each task whose memoryUsed is non-empty, a real block earns
-// no helpful (real wins even when the task also verified), else a first-verified task bumps helpful on every used
+// no helpful (real wins even when the task also verified; except on the hand track, whose reviewer blocks never withhold it), else a first-verified task bumps helpful on every used
 // lesson not named harmful; neither verified nor real does nothing. An id naming no lesson is reported in
 // `unknown`, never an error. apply:false (a dry run's preview) computes the same result without writing anything.
 function computeReflectCounters(m, blocks, report, { apply, harmfulIds = [] }) {
@@ -1527,7 +1561,9 @@ function computeReflectCounters(m, blocks, report, { apply, harmfulIds = [] }) {
     for (const task of level.tasks || []) {
       const used = Array.isArray(task.memoryUsed) ? task.memoryUsed : [];
       if (!used.length) continue;
-      const real = blocks.some((b) => b.task === task.id && b.class === "real");
+      // A hand report's blocks are reviewer blockers a later round fixed (card reflect-review-key-text): they are no
+      // evidence the lesson misled, so they never withhold helpful; only --harmful marks that.
+      const real = report.track !== "hand" && blocks.some((b) => b.task === task.id && b.class === "real");
       if (real) {
         for (const id of used) {
           if (!getLesson(m, id) && !named.has(id)) unknown.push(id);
@@ -1595,7 +1631,7 @@ export function buildReflectPrompt(report, { blocks = [], plan = null, existingL
       if (Array.isArray(task.verifierFindings) && task.verifierFindings.length) lines.push(`  verifier findings: ${JSON.stringify(task.verifierFindings)}`);
       if (taskBlocks.length) {
         lines.push("  blocks:");
-        for (const b of taskBlocks) lines.push(`    - report:${task.id}/${b.id} class=${b.class || "unclassified"} reason=${b.reason || "none"}`);
+        for (const b of taskBlocks) lines.push(`    - report:${b.id.startsWith(`${task.id}/`) ? b.id : `${task.id}/${b.id}`} class=${b.class || "unclassified"} reason=${b.reason || "none"}`);
       }
       lines.push(`  memoryUsed: ${used.length ? used.join(", ") : "none"}`);
     }

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

@@ -9,6 +9,13 @@ import { isModelName, EFFORTS } from "./models.mjs";
 
 export const PLAN_RELPATH = ".doug/plan.json";
 export const REPORT_RELPATH = ".doug/.state/last-report.json";
+// Per-card plans (card parallel-card-queens): a card run as its own queen keeps its plan at the tracked
+// .doug/plans/<id>.json and its report at .doug/.state/reports/<id>/last-report.json.
+export const PLANS_RELPATH = ".doug/plans";
+export const REPORTS_RELPATH = ".doug/.state/reports";
+export const DEFAULT_INTEGRATION_WORKTREE = ".claude/worktrees/doug-integration";
+export const planPathFor = (card) => `${PLANS_RELPATH}/${card}.json`;
+export const reportPathFor = (card) => `${REPORTS_RELPATH}/${card}/last-report.json`;
 // One draft per card of a batch (card parallel-cards): the planner for card <id> writes .doug/.state/drafts/<id>.json
 // and `plan.mjs merge` joins them into the plan file.
 export const DRAFTS_RELPATH = ".doug/.state/drafts";
@@ -55,8 +62,24 @@ export function draftPath(card) {
   return `${DRAFTS_RELPATH}/${card}.json`;
 }
 
-export function savePlan(dir, plan) {
-  const file = join(dir, PLAN_RELPATH);
+// The plan a card's commands read: its per-card plan when one exists; else the single .doug/plan.json, but only
+// when no card is given or that plan is this card's (plan.card equals it, or plan.cards includes it), so a stale
+// plan for another card is never read. Null otherwise, and when neither exists.
+export function planFor(dir, card) {
+  const hasCard = typeof card === "string" && card !== "";
+  if (hasCard && existsSync(join(dir, planPathFor(card)))) return loadPlan(dir, planPathFor(card));
+  const plan = loadPlan(dir);
+  if (!plan || !hasCard) return plan;
+  return plan.card === card || (Array.isArray(plan.cards) && plan.cards.includes(card)) ? plan : null;
+}
+
+// The plan's integration worktree: its own when set (a per-card run), else the fixed shared path.
+export function integrationWorktreeFor(plan) {
+  return (plan && plan.integrationWorktree) || DEFAULT_INTEGRATION_WORKTREE;
+}
+
+export function savePlan(dir, plan, relpath = PLAN_RELPATH) {
+  const file = join(dir, relpath);
   mkdirSync(dirname(file), { recursive: true });
   const tmp = file + "." + process.pid + ".tmp";
   writeFileSync(tmp, JSON.stringify(plan, null, 2) + "\n");
@@ -76,8 +99,8 @@ export function withSpecHashes(plan) {
   return { ...plan, tasks: plan.tasks.map((t) => ({ ...t, specHash: specHash(t) })) };
 }
 
-export function loadReport(dir) {
-  const file = join(dir, REPORT_RELPATH);
+export function loadReport(dir, relpath = REPORT_RELPATH) {
+  const file = join(dir, relpath);
   if (!existsSync(file)) return null;
   try {
     return unwrapReport(JSON.parse(readFileSync(file, "utf8")));
@@ -396,6 +419,11 @@ export function validatePlan(plan) {
     });
   }
   if (!Array.isArray(plan.verify) || !plan.verify.every((v) => typeof v === "string" && v.trim())) errors.push("verify must be an array of command strings");
+  if (plan.integrationWorktree !== undefined) {
+    const w = plan.integrationWorktree;
+    const under = typeof w === "string" && w.startsWith(".claude/worktrees/") && w.length > ".claude/worktrees/".length && !w.split("/").includes("..");
+    if (!under) errors.push("integrationWorktree must be a path under .claude/worktrees/ (the gate only recognises worktrees there)");
+  }
   if (plan.card !== undefined && (typeof plan.card !== "string" || !plan.card.trim())) errors.push("card must be a non-empty string when present");
   // A batch (several cards in one plan) lists its cards; every task then names the card it belongs to.
   let cards = null;

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

@@ -198,15 +198,15 @@ export function retireTaskWorktrees(dir, { tasks = [], saveDir }) {
   return result;
 }
 
-// Retires the integration worktree at .claude/worktrees/doug-integration, if one is registered (card
+// Retires the integration worktree at `path` (default .claude/worktrees/doug-integration; a per-card run passes its own), 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");
+export function retireIntegrationWorktree(dir, path = ".claude/worktrees/doug-integration") {
+  const target = resolve(realpathOrSelf(dir), path);
   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]);

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

@@ -1,6 +1,6 @@
 {
   "name": "@dougharness/flow",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "private": true,
   "description": "Plan, approve, implement one task per worktree, verify, review: a Workflow-tool template and subagents for Claude Code.",
   "type": "module",