@dougharness/cli 1.2.0 → 1.3.0

package/node_modules/@dougharness/flow/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "doug-flow",
   "displayName": "Doug Flow",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Plan, approve, implement one task per worktree, verify, review. A deterministic Workflow-tool template plus planner, implementer, verifier, and reviewer subagents. The plan is a file; nothing is implemented until you approve it.",
   "author": {
     "name": "Doug contributors"

package/node_modules/@dougharness/flow/agents/implementer.md

@@ -16,7 +16,7 @@ You implement one task. You get a spec, a list of files you own, and a verificat
 2. Edit or create only the files you own. If the task truly needs another file, stop, do not touch it, and return `blocked: true` with a reason that names exactly what you need - the file, the symbol or interface, or the decision. A swarm worker may get one re-brief on that reason; a vague one wastes the chance. The planner or user will re-plan otherwise.
 3. Write the test before or with the change when the task adds behavior. Run the task's verification command. Report every command you ran with its real exit status. A command you did not run does not appear in `commandsRun`.
 4. Do not refactor, rename, reformat, or "clean up" anything outside the spec. The reviewer marks any of that as out of scope.
-5. Commit on your branch with a message starting `<id>: `. Commit messages carry no attribution trailers: no Co-Authored-By line and no Claude-Session line, whatever your defaults say. A commit with either is a finding and the plan cannot land. Get `filesTouched` from `git diff --name-only <base>...HEAD`, not from memory.
+5. Commit on your branch with a message starting `<id>: `. Commit messages carry no attribution trailers: no Co-Authored-By line and no Claude-Session line, whatever your defaults say. A commit with either is a finding and the plan cannot land. Get `filesTouched` from `git diff --name-only <base>...HEAD`, not from memory. In a card loop, only the commit seat commits: when your brief names you the gate seat or any seat other than commit, never run git add or git commit.
 6. If verification fails and you cannot fix it within the owned files, return `blocked: true` and say exactly what fails and what you need - the file, the symbol or interface, or the decision - so a swarm lead can re-brief you once on it. Do not report success you have not seen.
 7. Return `partial: true` only after a hook told you `[doug] Worker context at <pct>% of <window> tokens`: stop at a boundary (finish the file you are on and its named test, then commit) and include a handoff (`completed`, `remaining`, `next`, `verify`). Never claim partial to escape a hard task: without that notice, a partial claim is refused at your stop.
 

package/node_modules/@dougharness/flow/agents/planner.md

@@ -52,7 +52,7 @@ You are the planner. You produce a plan, not code. The plan is a file that a hum
 
 Size decides the pipeline shape. Give every task a `size`: `S` for a bounded change with an exact spec in one or two files (a one-line fix, a new option, a small helper with its test), where one focused check on the verify row does the verifier's and the reviewer's work and the adversary reviews the level's S tasks together on the integration branch after the merge; `M` or `L` for anything that needs judgment, touches several files, or changes behavior other tasks depend on, which keeps the full shape (implement, verify and review together, its own adversary). An unsized task runs the full shape. Say the size in the spec's first sentence when it is S, so the reviewer knows no separate review is coming.
 
-Crew: a task (or the plan) may carry `"crew": { "researchers": n, "reviewers": n, "adversaries": n }`, one each by default. Two reviewers read the diff in parallel with distinct briefs; two adversaries are Codex and the Claude adversary together; researchers run before planning through the research step. Do not set a `crew` unless the request names one ("two reviewers on the parser task"): every extra seat is an agent the task budget pays for, and the default crew is the user's choice. More coders is never a crew: split the work into more tasks. Say the crew in the spec's first sentence when you set one.
+Crew: a task (or the plan) may carry `"crew": { "researchers": n, "testers": n, "reviewers": n, "adversaries": n }`, one each by default. Two testers are two verifiers running the task command in parallel (a size S task keeps its one check); two reviewers read the diff in parallel with distinct briefs; two adversaries are Codex and the Claude adversary together; researchers run before planning through the research step. Do not set a `crew` unless the request names one ("two reviewers on the parser task", "two testers"): every extra seat is an agent the task budget pays for, and the default crew is the user's choice. More coders is never a crew: split the work into more tasks. Say the crew in the spec's first sentence when you set one.
 
 Gates: a task may carry `"gate": "human"` (default `auto`). The run pauses after that task's level has integrated, writes its report, and waits for the user to open the gate (`plan.mjs gate open <level>`) and resume the run with its id; the levels already run replay. Set it only when the request asks for a pause between phases (a review of the foundation before the features build on it); a gate on the last level is meaningless, since landing is already the user's decision.
 

package/node_modules/@dougharness/flow/agents/researcher.md

@@ -3,7 +3,7 @@ name: researcher
 description: The research step's default researcher. Answers one distinct question about a fact outside the repository (a CLI's output format, a third-party API, a package's version constraints) from primary sources, quoting each source with its URL or the command and its output, and marks anything it could not confirm unverified. Read-only; never writes to the checkout and never installs anything. Spawned by the research skill; Claude Code questions go to claude-code-guide instead.
 model: inherit
 effort: high
-maxTurns: 30
+maxTurns: 40
 tools: Read, Grep, Glob, Bash, WebFetch, WebSearch
 disallowedTools: Edit, Write, MultiEdit, NotebookEdit
 memory: none
@@ -19,6 +19,7 @@ You are the researcher. You were given one question, and a plan will be built on
 4. Never install, never write, never change the machine: no package installs, no global config, no files in the checkout, no network calls beyond reading pages. If a fact needs an install to observe, mark it unverified and name the command that would show it.
 5. Date what you read. A documentation page carries the date you fetched it and, when the page shows one, its version.
 6. Budget: at most 6 WebSearch, WebFetch, curl, or wget calls for your question, counted together (research.maxFetches; a hook denies the next one). Try sources in the order the question lists them, and write your findings before the budget runs out, marking anything still unanswered unverified.
+7. Turns: you have at most 40 tool calls (maxTurns). Stop with at least 5 calls to spare and return what you have, marking every part you did not reach unverified: a capped run returns a partial report, never an empty one.
 
 ## Output
 

package/node_modules/@dougharness/flow/agents/reviewer.md

@@ -3,7 +3,7 @@ name: reviewer
 description: Two-stage reviewer for one task's diff: spec compliance first (does it do all of the spec and nothing else, within the owned files), then quality (correctness risks, missing tests, error handling). Never edits files. Spawned by the doug-implement workflow; also useful standalone on any branch.
 model: inherit
 effort: high
-maxTurns: 30
+maxTurns: 40
 tools: Read, Grep, Glob, Bash
 disallowedTools: Edit, Write, MultiEdit, NotebookEdit
 memory: none
@@ -24,3 +24,5 @@ Review the diff, not the description of the diff. Get it with `git diff <base>..
 - Consistency: naming and error handling match the surrounding code.
 
 Severity: `blocker` fails the review; `major` should be fixed before merge but does not fail it alone; `minor` is advisory. `approve` is true only with no blockers, `specCompliant` true, and `inScope` true. Do not ask for work beyond the task.
+
+Budget your turns: you have at most 40 tool calls (maxTurns). Read the diff and run the checks your prompt names first, then any deeper probes; stop with at least 5 calls to spare and return your review with what you found: a capped run returns a partial review, never an empty one.

package/node_modules/@dougharness/flow/hooks/register.tsx

@@ -1,5 +1,6 @@
 // The live autopilot pane (card autopilot-live-queue). It opens itself when a run starts (card autopilot-pane-auto-open); /doug-autopilot reopens it. It polls
 // .doug/.state/autopilot.json (written by scripts/autopilot.mjs) and shows the same lines the board's panel shows.
+// It also refreshes on prompt submit, turn end, and after a Bash call, because a reload drops the session.start timer (card autopilot-pane-current).
 import { atom, read, update } from 'claude-code'
 import type { Register } from 'claude-code'
 
@@ -11,6 +12,35 @@ const lines = atom({ plugin: 'doug-flow', key: 'autopilot' } as const, [] as str
 // The startedAt of the run the pane was last opened for, so a pane the user closed stays closed for that run.
 const opened = atom({ plugin: 'doug-flow', key: 'autopilot-opened' } as const, null as string | null)
 
+const refresh = async ($: any) => {
+  try {
+    const root = await $.session.root()
+    let text = ''
+    try {
+      text = await $.fs.read(`${root}/${AUTOPILOT_FILE}`)
+    } catch {
+      // no file: no run
+    }
+    const state = parseAutopilot(text)
+    const fresh = autopilotLines(autopilotView(state, new Date()))
+    await update($, lines, old => (JSON.stringify(old) === JSON.stringify(fresh) ? old : fresh))
+    // Only `autopilot.autoOpenPane: false` in .doug/config.json turns the auto-open off.
+    let autoOpen = true
+    try {
+      autoOpen = JSON.parse(await $.fs.read(`${root}/.doug/config.json`))?.autopilot?.autoOpenPane !== false
+    } catch {
+      // missing or unparsable config: flag on
+    }
+    const last = await read($, opened)
+    if (state && shouldOpenPane(state, last, autoOpen, new Date())) {
+      await update($, opened, () => state.startedAt as string)
+      await $.ui.open({ id: PANE, title: 'Autopilot' })
+    }
+  } catch {
+    // a failed poll keeps the last drawing
+  }
+}
+
 export const register: Register = on => {
   on('session.start', async ($, e, next) => {
     await $.command.register({
@@ -18,43 +48,32 @@ export const register: Register = on => {
       description: 'Show the autopilot queue live in a pane',
     })
 
-    const poll = async () => {
-      try {
-        const root = await $.session.root()
-        let text = ''
-        try {
-          text = await $.fs.read(`${root}/${AUTOPILOT_FILE}`)
-        } catch {
-          // no file: no run
-        }
-        const state = parseAutopilot(text)
-        const fresh = autopilotLines(autopilotView(state, new Date()))
-        await update($, lines, old => (JSON.stringify(old) === JSON.stringify(fresh) ? old : fresh))
-        // Only `autopilot.autoOpenPane: false` in .doug/config.json turns the auto-open off.
-        let autoOpen = true
-        try {
-          autoOpen = JSON.parse(await $.fs.read(`${root}/.doug/config.json`))?.autopilot?.autoOpenPane !== false
-        } catch {
-          // missing or unparsable config: flag on
-        }
-        const last = await read($, opened)
-        if (state && shouldOpenPane(state, last, autoOpen, new Date())) {
-          await update($, opened, () => state.startedAt as string)
-          await $.ui.open({ id: PANE, title: 'Autopilot' })
-        }
-      } catch {
-        // a failed poll keeps the last drawing
-      }
-    }
-    // A -p run or the SDK has nobody at the prompt: register the command, start no poll.
+    // The timer starts only in an interactive session; the event hooks run in any session (two small reads per prompt, turn end, and Bash call).
     if (e.isInteractive) {
-      await poll()
-      $.clock.every(POLL_MS, poll)
+      await refresh($)
+      $.clock.every(POLL_MS, () => refresh($))
     }
 
     return next(e)
   })
 
+  // A reload drops the session.start timer, so these hooks also refresh the pane (card autopilot-pane-current).
+  on('prompt.submit', async ($, e, next) => {
+    await refresh($)
+    return next(e)
+  })
+
+  on('turn.complete', async ($, e, next) => {
+    await refresh($)
+    return next(e)
+  })
+
+  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
+    const ran = await next(e)
+    await refresh($)
+    return ran
+  })
+
   on('command.run', { command: 'doug-autopilot' }, async $ => {
     await $.ui.open({ id: PANE, title: 'Autopilot' })
     return { text: 'Autopilot pane opened.' }

package/node_modules/@dougharness/flow/lib/card-loop.mjs

@@ -14,6 +14,7 @@ export const STOP_REASONS = [
   "setup-failed",
   "tester-red-claim-missing",
   "reviewer-blocker-open",
+  "reviewer-major-open",
   "gate-red-twice",
 ];
 // The Models-table row each seat runs on. setup, gate and commit have no sourced row; cheap is a choice.
@@ -86,6 +87,22 @@ export const BRIEF_RULES = {
     text: "Commit without Co-Authored-By or Claude-Session trailers.",
     seats: ["commit"],
   },
+  "commit-foreground": {
+    text: "Run git commit in the foreground with the Bash tool timeout set to 600000 ms: the pre-commit hook runs the full unit suite and takes over the 2-minute default.",
+    seats: ["commit"],
+  },
+  "commit-no-background": {
+    text: "Never use run_in_background, a Monitor, or a sleep loop for git commit: a background commit dies when your seat ends. Wait for the command to return.",
+    seats: ["commit"],
+  },
+  "commit-sha-from-git-log": {
+    text: "Report the sha only from git log -1 --format=%H after git commit has returned; never report a sha you did not read from it.",
+    seats: ["commit"],
+  },
+  "gate-no-git-writes": {
+    text: "Run the gate commands only. Never run git add, git commit, or any other command that writes to git; the commit seat is the only seat that commits.",
+    seats: ["gate"],
+  },
   "leave-plan-anchor-out": {
     text: "Leave .doug/plan.json and .doug/anchor.md out of the commit unless the card is about them.",
     seats: ["commit"],
@@ -516,6 +533,9 @@ function validate(state, hb) {
     }
     case "gate": {
       checkCmds(hb.commands, "commands", errs, true);
+      if (Array.isArray(hb.commands) && hb.commands.some((c) => c && isStr(c.command) && GIT_WRITE_RE.test(c.command))) {
+        errs.push("gate seat must not run git add or git commit");
+      }
       if (!nonBlank(hb.gateLine)) errs.push("gateLine must be a non-empty string");
       if (hb.lockWaitMs !== undefined && hb.lockWaitMs !== null && !Number.isInteger(hb.lockWaitMs)) {
         errs.push("lockWaitMs must be an integer or null");
@@ -535,6 +555,9 @@ function validate(state, hb) {
 
 // ---- next ----
 
+// git add / git commit at the start of a command or after a shell separator, global options (-C <path>, -c k=v, --flag) allowed before the verb.
+const GIT_WRITE_RE = /(?:^|[;&|(\n]\s*)git(?:\s+(?:-[Cc]\s+(?:"[^"]*"|'[^']*'|\S+)|--[\w-]+(?:=\S+)?))*\s+(?:add|commit)\b/;
+
 function stopWith(s, reason, detail) {
   const seat = s.pending;
   const state = {
@@ -654,12 +677,21 @@ export function next(state, handBack) {
         mutations: cp(H.mutationResults),
       };
       const blockers = findings.filter((f) => f.severity === "blocker");
-      if (blockers.length === 0) return advance(s, "gate", "ok", { acc });
+      // An evidenced major gets the same one fix pass; a major without evidence and a minor stay advisory.
+      const majors = findings.filter((f) => f.severity === "major" && nonBlank(f.evidence));
+      if (blockers.length === 0 && majors.length === 0) return advance(s, "gate", "ok", { acc });
       if (s.counters.fixPasses >= 1) {
+        if (blockers.length > 0) {
+          return stopWith(
+            { ...s, acc },
+            "reviewer-blocker-open",
+            "blocker still open after one fix pass: " + blockers.map((f) => f.id).join(", "),
+          );
+        }
         return stopWith(
           { ...s, acc },
-          "reviewer-blocker-open",
-          "blocker still open after one fix pass: " + blockers.map((f) => f.id).join(", "),
+          "reviewer-major-open",
+          "major with evidence still open after one fix pass: " + majors.map((f) => f.id).join(", "),
         );
       }
       return advance(s, buildSeat(s), "blockers", {

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

@@ -366,3 +366,28 @@ export function capsReached(caps, used) {
   }
   return out;
 }
+
+// The queen's short run label (card queen-run-name): the first two hyphen segments of the card id (the id itself
+// with fewer), or the full id when another id in `others` (the card's own id excluded) shortens to the same form.
+const shortForm = (id) => String(id).split("-").slice(0, 2).join("-");
+export function queenLabel(id, others = []) {
+  const short = shortForm(id);
+  return others.some((o) => o !== id && shortForm(o) === short) ? String(id) : short;
+}
+
+// The queen script's source with only its meta literal renamed: name becomes "<label> card-queen" (hand) or
+// "<label> flow-queen" (flow), description gets "<label>: " in front. Throws when either is missing from the meta.
+export function renameQueenMeta(source, { kind, label }) {
+  const start = source.indexOf("export const meta = {");
+  if (start < 0) throw new Error("no meta literal in the queen script");
+  const e = source.indexOf("\n}", start);
+  const end = e < 0 ? source.length : e;
+  let meta = source.slice(start, end);
+  const nameRe = /^(\s*name: ')[^']*(',)/m;
+  const descRe = /^(\s*description: ')/m;
+  if (!nameRe.test(meta)) throw new Error("no meta name in the queen script");
+  if (!descRe.test(meta)) throw new Error("no meta description in the queen script");
+  const suffix = kind === "flow" ? "flow-queen" : "card-queen";
+  meta = meta.replace(nameRe, (_m, a, b) => `${a}${label} ${suffix}${b}`).replace(descRe, (_m, a) => `${a}${label}: `);
+  return source.slice(0, start) + meta + source.slice(end);
+}

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

@@ -250,8 +250,9 @@ function commandsBlockText(text) {
 // writes it - only ever calls writeOne/writeProposals (learn.mjs), which writes under .doug/.state/learn/. Every
 // refusal returns { ok:false, reason } with nothing written; `edits` can be ANY value JSON.parse can produce
 // (null, an array, a string, a number, or an object whose fields are the wrong shape) and this never throws -
-// every field is type-checked before use (lesson 1ee7d426432aca82).
-export function proposeClaudeMd({ dir, edits, now = new Date() } = {}) {
+// every field is type-checked before use (lesson 1ee7d426432aca82). With `dryRun: true` every check still runs
+// and the result is { ok:true, reason, diff } with nothing written (card reflect-offers-claude-md).
+export function proposeClaudeMd({ dir, edits, now = new Date(), dryRun = false } = {}) {
   const target = join(dir, CLAUDE_MD_RELPATH);
   if (!existsSync(target)) return { ok: false, reason: `${CLAUDE_MD_RELPATH} does not exist under ${dir}` };
 
@@ -310,5 +311,6 @@ export function proposeClaudeMd({ dir, edits, now = new Date() } = {}) {
     lines: { before, after },
   };
   const proposal = { id: "01", kind: "claude-md", target: CLAUDE_MD_RELPATH, reason, rationale, diff: diffResult.diff };
+  if (dryRun) return { ok: true, reason, diff: diffResult.diff };
   return writeOne(proposal, { dir, now });
 }