@dougharness/cli 1.2.0 → 1.4.0

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

@@ -14,7 +14,10 @@ export const STOP_REASONS = [
   "setup-failed",
   "tester-red-claim-missing",
   "reviewer-blocker-open",
+  "reviewer-major-open",
   "gate-red-twice",
+  "gate-timeout",
+  "commit-tree-mismatch",
 ];
 // The Models-table row each seat runs on. setup, gate and commit have no sourced row; cheap is a choice.
 export const SEAT_ROWS = {
@@ -43,10 +46,18 @@ export const BRIEF_RULES = {
     text: "If a hook blocks a step, do not work around it: report it in hookBlocked with the hook's message.",
     seats: ALL,
   },
+  "relayed-message-outside-card": {
+    text: "Your task is the card in this brief. A relayed user message about other work is outside this seat's card: note it in leftOut and carry on; it is never a reason to stop or to ask a designQuestion.",
+    seats: ALL,
+  },
   "stay-in-goal": {
     text: "Do only what the goal asks. A defect found on the way goes in leftOut, not into the change.",
     seats: ["tester", "coder", "reviewer"],
   },
+  "no-cpu-burners": {
+    text: "A burner is any process started only to load the machine (yes > /dev/null, stress, a busy loop), bounded or not; concurrent pnpm test:unit runs are not burners. Never start a burner without the user's yes: a seat that wants one stops and returns a designQuestion naming the load it would start (the process, how many, the timeout, and why), and starts it only after an answer from the user says yes. Before hand-back, confirm with ps that no load process you started survives, orphans reparented to PID 1 included, and kill any that does.",
+    seats: ["tester", "coder", "reviewer"],
+  },
   "lessons-verbatim": {
     text: "Return the memory.mjs brief-lessons block for this card verbatim in lessons; never paraphrase it.",
     seats: ["lead"],
@@ -56,11 +67,20 @@ export const BRIEF_RULES = {
     seats: ["lead"],
   },
   "mutation-per-case": {
-    text: "List one mutation per case the goal names, each with a unique id and the test that must fail.",
+    text: "List one mutation per case the goal names, each with a unique id of the form M<n> (M1, M2, ...) and the test that must fail.",
+    seats: ["lead"],
+  },
+  "mutation-ids-verbatim": {
+    text: "Report each listed mutation in mutationResults under its exact listed id from MUTATION IDS; never renumber, shorten, or rename an id (a split mutation adds one letter: M8a, M8b).",
+    seats: ["tester", "coder", "reviewer"],
+    when: "mutations",
+  },
+  "mutation-is-code-change": {
+    text: "A mutation is a code change to a file in the card worktree that a test catches; a check that is not a code mutation (a git diff, a file-absence check) goes in reviewerChecks, never in mutations.",
     seats: ["lead"],
   },
   "red-claim": {
-    text: "Tests that are red by design are named in tests_red_by_design; without the claim the card stops.",
+    text: "Tests that are red by design are named in tests_red_by_design; without the claim the card stops. If the new tests pass at baseline (pins), return tests_red_by_design [] and report every listed mutation in mutationResults, run in a scratch copy; the card goes on only when each one failed.",
     seats: ["tester"],
     when: "full",
   },
@@ -86,6 +106,38 @@ 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"],
+  },
+  "gate-timeout-is-load": {
+    text: "When verify.mjs prints `exit timeout` for a command, report that command with timedOut: true; a timeout is load, not a red or a block, so leave blocked unset.",
+    seats: ["gate"],
+  },
+  "commit-no-file-edits": {
+    text: "Never edit, create, delete, or format a file: commit exactly the tree the gate seat passed (GATED TREE). A change the commit seems to need goes in blocked, never into the tree.",
+    seats: ["commit"],
+  },
+  "commit-reports-tree": {
+    text: "After git commit returns, run node .doug/hooks/lib/verified-tree.mjs tree with the card worktree path as its argument and report its output as tree; a tree that differs from GATED TREE stops the card.",
+    seats: ["commit"],
+  },
+  "gate-reports-tree": {
+    text: "After the gate commands, run node .doug/hooks/lib/verified-tree.mjs tree with the card worktree path as its argument and report its output as tree.",
+    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"],
@@ -96,11 +148,13 @@ export const BRIEF_RULES = {
 
 const S = { type: "string" };
 const NES = { type: "string", minLength: 1 };
+const MUTATION_ID_PATTERN = "^M[1-9][0-9]*$";
+const TREE = { type: "string", pattern: "^([0-9a-f]{40}|[0-9a-f]{64})$" };
 const INT_OR_NULL = { type: ["integer", "null"] };
 const STRS = { type: "array", items: S };
 const CMD = {
   type: "object",
-  properties: { command: S, exitCode: INT_OR_NULL },
+  properties: { command: S, exitCode: INT_OR_NULL, timedOut: { type: "boolean" } },
   required: ["command", "exitCode"],
 };
 const MUT_RESULT = {
@@ -108,6 +162,11 @@ const MUT_RESULT = {
   properties: { id: S, failed: { type: "boolean" }, test: S, assertion: S, own: { type: "boolean" } },
   required: ["id", "failed", "test"],
 };
+const CODER_MUT_RESULT = {
+  type: "object",
+  properties: { id: S, failed: { type: "boolean" }, test: S, assertion: S, own: { type: "boolean" }, notRun: NES },
+  required: ["id"],
+};
 const ENVELOPE = {
   seat: { type: "string", enum: SEATS },
   hookBlocked: { type: "object", properties: { message: NES }, required: ["message"] },
@@ -139,11 +198,12 @@ export const HAND_BACK_SCHEMAS = {
       },
       unverified: STRS,
       testFiles: STRS,
+      reviewerChecks: STRS,
       mutations: {
         type: "array",
         items: {
           type: "object",
-          properties: { id: NES, case: S, mutation: S, test: S },
+          properties: { id: { type: "string", minLength: 1, pattern: MUTATION_ID_PATTERN }, case: S, mutation: S, test: S },
           required: ["id", "case", "mutation", "test"],
         },
       },
@@ -168,7 +228,7 @@ export const HAND_BACK_SCHEMAS = {
         type: "array",
         items: { type: "object", properties: { file: S, reason: NES }, required: ["file", "reason"] },
       },
-      mutationResults: { type: "array", items: MUT_RESULT },
+      mutationResults: { type: "array", items: CODER_MUT_RESULT },
     },
     ["filesChanged", "commandsRun", "testsEdited"],
   ),
@@ -197,12 +257,25 @@ export const HAND_BACK_SCHEMAS = {
   ),
   gate: schema(
     "gate",
-    { commands: { type: "array", items: CMD, minItems: 1 }, gateLine: NES, lockWaitMs: INT_OR_NULL },
-    ["commands", "gateLine"],
+    { commands: { type: "array", items: CMD, minItems: 1 }, gateLine: NES, lockWaitMs: INT_OR_NULL, tree: TREE },
+    ["commands", "gateLine", "tree"],
   ),
-  commit: schema("commit", { sha: { type: "string", pattern: "^[0-9a-f]{7,40}$" }, branch: S }, ["sha", "branch"]),
+  commit: schema("commit", { sha: { type: "string", pattern: "^[0-9a-f]{7,40}$" }, branch: S, tree: TREE }, ["sha", "branch", "tree"]),
 };
 
+// The schema a seat is handed on a lane. Only the tests-only tester may report notRun (validateHandBack's tester
+// case), so only there are its mutationResults items CODER_MUT_RESULT; the plain table is the full-lane contract.
+export function handBackSchema(seat, lane) {
+  if (seat === "tester" && lane === "tests-only") {
+    const base = HAND_BACK_SCHEMAS.tester;
+    return {
+      ...base,
+      properties: { ...base.properties, mutationResults: { type: "array", items: CODER_MUT_RESULT } },
+    };
+  }
+  return HAND_BACK_SCHEMAS[seat];
+}
+
 // ---- small helpers ----
 
 const cp = (x) => JSON.parse(JSON.stringify(x));
@@ -226,14 +299,25 @@ function checkCmds(list, path, errs, needOne) {
   });
 }
 
-function checkMutResults(list, path, errs) {
+// A reported id covers listed id L when it is L or L plus one lowercase letter (a split such as M1a, M1b).
+function coversId(reported, listed) {
+  if (reported === listed) return true;
+  return typeof reported === "string" && reported.length === listed.length + 1 && reported.startsWith(listed) && /[a-z]$/.test(reported);
+}
+
+function checkMutResults(list, path, errs, allowNotRun = false) {
   if (!Array.isArray(list)) {
     errs.push(path + " must be an array");
     return false;
   }
   let good = true;
   list.forEach((m, i) => {
-    if (!isObj(m) || !nonBlank(m.id) || typeof m.failed !== "boolean" || !isStr(m.test)) {
+    if (allowNotRun && isObj(m) && m.notRun !== undefined) {
+      if (!nonBlank(m.id) || !nonBlank(m.notRun)) {
+        errs.push(`${path}[${i}] notRun needs id and a non-empty reason string`);
+        good = false;
+      }
+    } else if (!isObj(m) || !nonBlank(m.id) || typeof m.failed !== "boolean" || !isStr(m.test)) {
       errs.push(`${path}[${i}] needs id, failed (boolean) and test`);
       good = false;
     }
@@ -250,6 +334,21 @@ export function laneFor(card) {
   return "full";
 }
 
+// options.answers: the user's answers to design questions, { seat, question, answer, round?, run? } each.
+function checkAnswers(answers) {
+  if (answers === undefined || answers === null) return [];
+  const bad = (why) => new TypeError("options.answers " + why);
+  if (!Array.isArray(answers)) throw bad("must be an array");
+  return answers.map((a, i) => {
+    if (!isObj(a)) throw bad(`[${i}] must be an object`);
+    if (!SEATS.includes(a.seat)) throw bad(`[${i}].seat must be one of the seats`);
+    if (!isStr(a.question)) throw bad(`[${i}].question must be a string`);
+    if (!nonBlank(a.answer)) throw bad(`[${i}].answer must be a non-blank string`);
+    if (a.round !== undefined && !(Number.isInteger(a.round) && a.round > 0)) throw bad(`[${i}].round must be a positive integer`);
+    return { ...a };
+  });
+}
+
 export function initialState(card, options = {}) {
   if (!isObj(card) || !nonBlank(card.id) || !isStr(card.goal)) {
     throw new TypeError("card needs an id and a goal string");
@@ -257,6 +356,7 @@ export function initialState(card, options = {}) {
   const o = isObj(options) ? options : {};
   return {
     version: 1,
+    answers: checkAnswers(o.answers),
     card: {
       id: card.id,
       title: card.title ?? null,
@@ -273,13 +373,15 @@ export function initialState(card, options = {}) {
     base: o.base ?? "main",
     worktree: null,
     researchNote: null,
-    material: { lessons: "", facts: [], unverified: [], testFiles: [], mutations: [] },
+    material: { lessons: "", facts: [], unverified: [], testFiles: [], mutations: [], reviewerChecks: [] },
+    notRun: [],
     redTests: [],
     counters: { coderRounds: 0, fixPasses: 0, redGates: 0 },
     seatRuns: {},
     fixFor: null,
     lastFindings: [],
     lastGate: null,
+    gateTree: null,
     pending: "setup",
     outcome: null,
     history: [],
@@ -329,21 +431,27 @@ function buildBrief(s) {
     unverified: cp(s.material.unverified),
     testFiles: cp(s.material.testFiles),
     mutations: cp(effectiveMutations(s)),
+    reviewerChecks: seat === "reviewer" ? cp(s.material.reviewerChecks || []) : [],
+    notRun: seat === "reviewer" ? cp(s.notRun || []) : [],
     rules: Object.entries(BRIEF_RULES)
       .filter(([, r]) => ruleApplies(r, seat, s))
       .map(([id, r]) => ({ id, text: r.text })),
     findings: fixing && s.fixFor === "review" ? cp(s.lastFindings) : [],
     gate: fixing && s.fixFor === "gate" ? cp(s.lastGate) : null,
     redTests: cp(s.redTests),
+    answers: (s.answers || [])
+      .filter((a) => a.seat === seat && (a.round === undefined || a.round <= (s.seatRuns[seat] || 0) + 1))
+      .map((a) => ({ question: a.question, answer: a.answer })),
     writeTestsFirst: seat === "coder" && s.counters.coderRounds === 0 && (s.lane === "lean" || !s.testerAgent),
     researchNote: s.researchNote,
-    handBack: cp(HAND_BACK_SCHEMAS[seat]),
+    handBack: cp(handBackSchema(seat, s.lane)),
   };
   if (seat === "setup") {
     brief.install = s.install;
     brief.base = s.base;
   }
   if (seat === "gate" || seat === "reviewer") brief.gateCommand = s.gateCommand;
+  if (seat === "commit") brief.gateTree = s.gateTree;
   return brief;
 }
 
@@ -369,6 +477,7 @@ function buildReport(s) {
     testsEdited: cp(s.acc.testsEdited),
     filesChanged: cp(s.acc.filesChanged),
     followUps: cp(s.acc.followUps),
+    researchNote: s.researchNote ?? null,
     cost: null,
   };
 }
@@ -413,8 +522,8 @@ function validate(state, hb) {
   const muts = effectiveMutations(state);
   const needCover = (list, path, ids) => {
     if (!Array.isArray(list)) return;
-    const have = new Set(list.filter(isObj).map((m) => m.id));
-    for (const id of ids) if (!have.has(id)) errs.push(`${path} is missing listed mutation ${id}`);
+    const have = list.filter(isObj).map((m) => m.id);
+    for (const id of ids) if (!have.some((h) => coversId(h, id))) errs.push(`${path} is missing listed mutation ${id}`);
   };
   const first = state.counters.coderRounds === 0;
 
@@ -429,7 +538,7 @@ function validate(state, hb) {
       break;
     }
     case "research":
-      if (!isAbs(hb.note)) errs.push("note must be an absolute path");
+      if (!nonBlank(hb.note)) errs.push("note must be the researcher's cited note text or a path, not blank");
       break;
     case "lead": {
       if (!isStr(hb.lessons)) errs.push("lessons must be a string");
@@ -441,6 +550,7 @@ function validate(state, hb) {
       }
       if (!strArr(hb.unverified)) errs.push("unverified must be an array of strings");
       if (!strArr(hb.testFiles)) errs.push("testFiles must be an array of strings");
+      if (hb.reviewerChecks !== undefined && !strArr(hb.reviewerChecks)) errs.push("reviewerChecks must be an array of strings");
       if (!Array.isArray(hb.mutations)) errs.push("mutations must be an array");
       else {
         const ids = new Set();
@@ -448,6 +558,7 @@ function validate(state, hb) {
           if (!isObj(m) || !nonBlank(m.id) || !isStr(m.case) || !isStr(m.mutation) || !isStr(m.test)) {
             errs.push(`mutations[${i}] needs id, case, mutation and test`);
           } else if (ids.has(m.id)) errs.push(`mutations[${i}] repeats id ${m.id}`);
+          else if (!new RegExp(MUTATION_ID_PATTERN).test(m.id)) errs.push(`mutations[${i}] id ${m.id} must have the form M<n> (M1, M2, ...)`);
           else ids.add(m.id);
         });
       }
@@ -461,7 +572,14 @@ function validate(state, hb) {
         errs.push("tests_red_by_design must be an array of strings");
       }
       let shaped = true;
-      if (hb.mutationResults !== undefined) shaped = checkMutResults(hb.mutationResults, "mutationResults", errs);
+      if (hb.mutationResults !== undefined) shaped = checkMutResults(hb.mutationResults, "mutationResults", errs, state.lane === "tests-only");
+      if (state.lane === "tests-only" && shaped && Array.isArray(hb.mutationResults)) {
+        hb.mutationResults.forEach((m, i) => {
+          if (isObj(m) && m.notRun !== undefined && !muts.some((x) => x.id === m.id)) {
+            errs.push(`mutationResults[${i}] notRun id ${m.id} is not a listed mutation`);
+          }
+        });
+      }
       if (state.lane === "tests-only" && first && muts.length > 0) {
         if (hb.mutationResults === undefined) errs.push("mutationResults is required on the first run");
         else if (shaped) needCover(hb.mutationResults, "mutationResults", muts.map((m) => m.id));
@@ -478,7 +596,14 @@ function validate(state, hb) {
         });
       }
       let shaped = true;
-      if (hb.mutationResults !== undefined) shaped = checkMutResults(hb.mutationResults, "mutationResults", errs);
+      if (hb.mutationResults !== undefined) shaped = checkMutResults(hb.mutationResults, "mutationResults", errs, true);
+      if (shaped && Array.isArray(hb.mutationResults)) {
+        hb.mutationResults.forEach((m, i) => {
+          if (isObj(m) && m.notRun !== undefined && !muts.some((x) => x.id === m.id)) {
+            errs.push(`mutationResults[${i}] notRun id ${m.id} is not a listed mutation`);
+          }
+        });
+      }
       if (first && muts.length > 0) {
         if (hb.mutationResults === undefined) errs.push("mutationResults is required on the first round");
         else if (shaped) needCover(hb.mutationResults, "mutationResults", muts.map((m) => m.id));
@@ -505,18 +630,27 @@ function validate(state, hb) {
       }
       if (hb.verdict === "pass" && blocker) errs.push("verdict pass contradicts an evidenced blocker");
       checkCmds(hb.commandsRun, "commandsRun", errs, false);
+      if (Array.isArray(hb.mutationResults)) {
+        hb.mutationResults.forEach((m, i) => {
+          if (isObj(m) && m.notRun !== undefined) errs.push(`mutationResults[${i}] notRun is not allowed for the reviewer`);
+        });
+      }
       if (checkMutResults(hb.mutationResults, "mutationResults", errs)) {
         const listed = muts.map((m) => m.id);
         needCover(hb.mutationResults, "mutationResults", listed);
         for (const m of hb.mutationResults) {
-          if (!listed.includes(m.id) && m.own !== true) errs.push(`mutationResults id ${m.id} is not listed and not marked own`);
+          if (!listed.some((l) => coversId(m.id, l)) && m.own !== true) errs.push(`mutationResults id ${m.id} is not listed and not marked own`);
         }
       }
       break;
     }
     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 (!(isStr(hb.tree) && TREE_RE.test(hb.tree))) errs.push("tree must be 40 or 64 lowercase hex characters");
       if (hb.lockWaitMs !== undefined && hb.lockWaitMs !== null && !Number.isInteger(hb.lockWaitMs)) {
         errs.push("lockWaitMs must be an integer or null");
       }
@@ -525,6 +659,7 @@ function validate(state, hb) {
     case "commit": {
       if (!(isStr(hb.sha) && /^[0-9a-f]{7,40}$/.test(hb.sha))) errs.push("sha must be 7 to 40 lowercase hex characters");
       if (!nonBlank(hb.branch)) errs.push("branch must be a non-empty string");
+      if (!(isStr(hb.tree) && TREE_RE.test(hb.tree))) errs.push("tree must be 40 or 64 lowercase hex characters");
       break;
     }
     default:
@@ -535,6 +670,11 @@ function validate(state, hb) {
 
 // ---- next ----
 
+const TREE_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
+// 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 = {
@@ -581,6 +721,9 @@ export function next(state, handBack) {
   // C3 .. C6
   if (isObj(H.hookBlocked) && nonBlank(H.hookBlocked.message)) return stopWith(s, "hook-blocked", H.hookBlocked.message);
   if (nonBlank(H.designQuestion)) return stopWith(s, "design-decision", H.designQuestion);
+  if (P === "gate" && Array.isArray(H.commands) && H.commands.some((c) => isObj(c) && c.timedOut === true)) {
+    return stopWith({ ...s, lastGate: { commands: cp(H.commands), gateLine: H.gateLine } }, "gate-timeout", typeof H.gateLine === "string" ? H.gateLine : "a gate command timed out");
+  }
   if (nonBlank(H.blocked)) return stopWith(s, "seat-blocked", H.blocked);
   const errs = validateHandBack(s, H);
   if (errs.length > 0) return stopWith(s, "hand-back-invalid", errs.join("; "));
@@ -601,6 +744,7 @@ export function next(state, handBack) {
         unverified: cp(H.unverified),
         testFiles: cp(H.testFiles),
         mutations: cp(H.mutations),
+        reviewerChecks: strArr(H.reviewerChecks) ? cp(H.reviewerChecks) : [],
       };
       const to = s.lane === "lean" || !s.testerAgent ? "coder" : "tester";
       return advance(s, to, "ok", { material });
@@ -609,13 +753,41 @@ export function next(state, handBack) {
       const acc = { ...s.acc, filesChanged: union(s.acc.filesChanged, H.files) };
       if (Array.isArray(H.mutationResults) && s.lane === "tests-only") acc.mutations = cp(H.mutationResults);
       if (s.lane === "tests-only") {
+        const seenT = new Set((s.notRun || []).map((n) => n.id));
+        const notRunT = [...(s.notRun || [])];
+        for (const m of Array.isArray(H.mutationResults) ? H.mutationResults : []) {
+          if (isObj(m) && m.notRun !== undefined && !seenT.has(m.id)) {
+            seenT.add(m.id);
+            notRunT.push({ id: m.id, reason: m.notRun });
+          }
+        }
         return advance(s, "reviewer", "ok", {
           acc,
+          notRun: notRunT,
           fixFor: null,
           counters: { ...s.counters, coderRounds: s.counters.coderRounds + 1 },
         });
       }
       const claim = H.tests_red_by_design;
+      if (Array.isArray(claim) && claim.length === 0) {
+        // Pin-only card: the new tests pass at baseline. Go on only when every listed mutation was run and failed.
+        const listed = effectiveMutations(s).map((m) => m.id);
+        const results = Array.isArray(H.mutationResults) ? H.mutationResults.filter(isObj) : [];
+        const bad = listed.filter((id) => {
+          const cov = results.filter((m) => coversId(m.id, id));
+          return cov.length === 0 || cov.some((m) => m.failed !== true);
+        });
+        if (listed.length > 0 && bad.length === 0) {
+          return advance(s, "coder", "ok", { acc, redTests: [] });
+        }
+        return stopWith(
+          s,
+          "tester-red-claim-missing",
+          listed.length === 0
+            ? "the tester returned an empty tests_red_by_design claim and no mutation is listed to show the pins bite"
+            : `the tester returned an empty tests_red_by_design claim but mutation ${bad.join(", ")} was not run or survived`,
+        );
+      }
       if (!(Array.isArray(claim) && claim.length > 0 && claim.every(nonBlank))) {
         return stopWith(s, "tester-red-claim-missing", "the tester returned no tests_red_by_design claim");
       }
@@ -627,8 +799,17 @@ export function next(state, handBack) {
         filesChanged: union(s.acc.filesChanged, H.filesChanged),
         testsEdited: [...s.acc.testsEdited, ...H.testsEdited.map((t) => ({ round, file: t.file, reason: t.reason }))],
       };
+      const seen = new Set((s.notRun || []).map((n) => n.id));
+      const notRun = [...(s.notRun || [])];
+      for (const m of Array.isArray(H.mutationResults) ? H.mutationResults : []) {
+        if (isObj(m) && m.notRun !== undefined && !seen.has(m.id)) {
+          seen.add(m.id);
+          notRun.push({ id: m.id, reason: m.notRun });
+        }
+      }
       return advance(s, "reviewer", "ok", {
         acc,
+        notRun,
         fixFor: null,
         counters: { ...s.counters, coderRounds: s.counters.coderRounds + 1 },
       });
@@ -654,12 +835,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", {
@@ -674,7 +864,7 @@ export function next(state, handBack) {
       const waited = { ...s.acc, lockWaitMs: (s.acc.lockWaitMs || 0) + (Number.isInteger(H.lockWaitMs) ? H.lockWaitMs : 0) };
       s.acc = waited;
       if (H.commands.every((c) => c.exitCode === 0)) {
-        return advance(s, "commit", "ok", { lastGate, acc: { ...waited, gateLine: H.gateLine } });
+        return advance(s, "commit", "ok", { lastGate, gateTree: H.tree, acc: { ...waited, gateLine: H.gateLine } });
       }
       const redGates = s.counters.redGates + 1;
       const counters = { ...s.counters, redGates };
@@ -683,6 +873,9 @@ export function next(state, handBack) {
     }
     default: {
       // commit
+      if (H.tree !== s.gateTree) {
+        return stopWith(s, "commit-tree-mismatch", `commit ${H.sha} tree ${H.tree} differs from the gated tree ${s.gateTree}`);
+      }
       const state = {
         ...s,
         pending: null,
@@ -705,6 +898,9 @@ export function briefPrompt(brief, { repoRoot, worktreePath } = {}) {
   out.push(`SEAT: ${b.seat} (round ${b.round}, lane ${b.lane}, model row ${b.row})`);
   out.push(`CARD ${b.card.id}${b.card.title ? ": " + b.card.title : ""}`);
   out.push("GOAL:\n" + b.card.goal);
+  if (b.answers && b.answers.length > 0) {
+    out.push("ANSWERS FROM THE USER (to your design questions; build on them):\n" + bullets(b.answers.map((a) => `Q: ${a.question} A: ${a.answer}`)));
+  }
   out.push("WORKTREE: " + worktreePath);
   if (b.seat === "setup") {
     out.push(
@@ -715,14 +911,23 @@ export function briefPrompt(brief, { repoRoot, worktreePath } = {}) {
           : "There is no install command; skip the install and report install as null."),
     );
   }
-  if (b.researchNote) out.push("RESEARCH NOTE: " + b.researchNote);
+  if (b.researchNote) out.push("RESEARCH NOTE:" + (b.researchNote.includes("\n") ? "\n" : " ") + b.researchNote);
   if (b.lessons) out.push("LESSONS BLOCK verbatim:\n" + b.lessons);
   if (b.facts.length > 0) out.push("FACTS (with sources):\n" + bullets(b.facts.map((f) => `${f.text} [${f.source}]`)));
   if (b.unverified.length > 0) out.push("UNVERIFIED:\n" + bullets(b.unverified));
   if (b.testFiles.length > 0) out.push("TEST FILES:\n" + bullets(b.testFiles));
   if (b.mutations.length > 0) {
     out.push("MUTATIONS:\n" + bullets(b.mutations.map((m) => `${m.id} (${m.case}): ${m.mutation}; test that must fail: ${m.test}`)));
+    if ((b.rules || []).some((r) => r.id === "mutation-ids-verbatim")) {
+      out.push("MUTATION IDS (report each verbatim in mutationResults): " + b.mutations.map((m) => m.id).join(", "));
+    }
+  }
+  if (b.notRun && b.notRun.length > 0) {
+    out.push(
+      "NOT RUN BY THE CODER (report each with failed true or false):\n" + bullets(b.notRun.map((n) => `${n.id}: ${n.reason}`)),
+    );
   }
+  if (b.reviewerChecks && b.reviewerChecks.length > 0) out.push("REVIEWER CHECKS:\n" + bullets(b.reviewerChecks));
   if (b.redTests.length > 0) out.push("TESTS RED BY DESIGN:\n" + bullets(b.redTests));
   if (b.writeTestsFirst) out.push("Write the test first, in the file that covers the module, then the change.");
   if (b.findings.length > 0) {
@@ -740,6 +945,7 @@ export function briefPrompt(brief, { repoRoot, worktreePath } = {}) {
     );
   }
   if (b.gateCommand) out.push("GATE COMMAND: " + b.gateCommand);
+  if (b.gateTree) out.push("GATED TREE: " + b.gateTree);
   out.push("RULES:\n" + bullets(b.rules.map((r) => r.text)));
   out.push("HAND-BACK: return JSON matching this schema:\n" + JSON.stringify(b.handBack, null, 2));
   return out.join("\n\n") + "\n";

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/cost.mjs

@@ -243,6 +243,15 @@ export function priceCodexUsage(codexUsage, model = CODEX_DEFAULT_MODEL) {
 
 const CODEX_RELAY = "doug-flow:adversary";
 
+// The report a cost line may use for `runId`: a report carrying a runId attaches only on an exact match; one
+// carrying none attaches only when the caller named the file (`named`). Anything else is null.
+export function reportForRun(report, runId, { named = false } = {}) {
+  if (!report || typeof report !== "object") return null;
+  const id = typeof report.runId === "string" && report.runId !== "" ? report.runId : null;
+  if (id === null) return named ? report : null;
+  return id === runId ? report : null;
+}
+
 // Sum and price every agent of one run. Throws when the run cannot be found; an agent without a transcript or on
 // an unpriced model is reported in `notes`, never estimated.
 // `report` (card adversary-usage-in-report): a parsed workflow report, or null/omitted. When given and it carries

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 });
 }