@dev-loops/core 0.2.6 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "type": "module",
   "description": "Shared deterministic support package for dev-loop skills, repo-local scripts, and GitHub automation.",
   "exports": {
@@ -28,6 +28,7 @@
     "./loop/copilot-ci-status": "./src/loop/copilot-ci-status.mjs",
     "./loop/copilot-loop-iterations": "./src/loop/copilot-loop-iterations.mjs",
     "./loop/copilot-loop-state": "./src/loop/copilot-loop-state.mjs",
+    "./loop/gate-fanin": "./src/loop/gate-fanin.mjs",
     "./loop/handoff-envelope": "./src/loop/handoff-envelope.mjs",
     "./loop/lifecycle-state": "./src/loop/lifecycle-state.mjs",
     "./loop/issue-refinement-artifact": "./src/loop/issue-refinement-artifact.mjs",
@@ -36,7 +37,9 @@
     "./loop/pr-gate-coordination": "./src/loop/pr-gate-coordination.mjs",
     "./loop/pr-title-markers": "./src/loop/pr-title-markers.mjs",
     "./loop/public-dev-loop-routing": "./src/loop/public-dev-loop-routing.mjs",
+    "./loop/queue-board-sync": "./src/loop/queue-board-sync.mjs",
     "./loop/queue-driver": "./src/loop/queue-driver.mjs",
+    "./loop/queue-membership": "./src/loop/queue-membership.mjs",
     "./loop/queue-parallel": "./src/loop/queue-parallel.mjs",
     "./loop/queue-state": "./src/loop/queue-state.mjs",
     "./loop/reviewer-loop-state": "./src/loop/reviewer-loop-state.mjs",

package/src/bash-exit-one.mjs

@@ -1,5 +1,6 @@
 import { appendFile, mkdir } from "node:fs/promises";
 import path from "node:path";
+import { parseArgs } from "node:util";
 
 export const DEFAULT_OUTPUT_LIMIT = 4000;
 
@@ -79,23 +80,40 @@ export async function appendBashExitOneRecord(logPath, record) {
 }
 
 export function parseCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      log: { type: "string" },
+      record: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
   let logPath;
   let recordJson;
 
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--log") {
-      logPath = args.shift();
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw new Error(`Unknown argument: ${token.value}`);
+    }
+
+    if (token.kind !== "option") {
+      continue;
+    }
+
+    if (token.name === "log") {
+      logPath = token.value;
       continue;
     }
 
-    if (token === "--record") {
-      recordJson = args.shift();
+    if (token.name === "record") {
+      recordJson = token.value;
       continue;
     }
 
-    throw new Error(`Unknown argument: ${token}`);
+    throw new Error(`Unknown argument: ${token.rawName}`);
   }
 
   if (!logPath) {

package/src/claude/asset-generation.mjs

@@ -72,6 +72,22 @@ export function stripPiOnlyBlocks(body) {
     .replace(/\n{3,}/g, "\n\n");
 }
 
+/**
+ * Rewrite the Pi package-local CLI invocation into the Claude version-pinned `npx` form (#801,
+ * #833). The Pi runtime sources invoke the CLI as `node <dev-loops-package-root>/cli/index.mjs`
+ * (resolves unambiguously from the installed package). The Claude plugin does NOT bundle `cli/`,
+ * so for the generated tree those tokens become `npx dev-loops@<version>` — pinning the version
+ * keeps the CLI from drifting against the published plugin version (#833). The Pi-only
+ * package-root resolution note is removed separately by `stripPiOnlyBlocks`.
+ *
+ * @param {string} body
+ * @param {string} version dev-loops package version to pin (e.g. "0.2.6").
+ * @returns {string}
+ */
+export function rewriteCliInvocation(body, version) {
+  return String(body).split("node <dev-loops-package-root>/cli/index.mjs").join(`npx dev-loops@${version}`);
+}
+
 /**
  * Map a single Pi tool name to its Claude tool name(s).
  * @param {string} name
@@ -131,12 +147,12 @@ function normalizeToolList(value) {
 
 /**
  * Transform a canonical `agents/*.agent.md` into a Claude `.claude/agents/*.md` document.
- * @param {{ source: string, raw: string }} input
+ * @param {{ source: string, raw: string, version?: string }} input
  * @returns {string} Full generated file content.
  */
-export function transformAgent({ source, raw }) {
+export function transformAgent({ source, raw, version = "latest" }) {
   const { frontmatter, body: rawBody } = splitFrontmatter(raw, source);
-  const body = stripPiOnlyBlocks(rawBody);
+  const body = rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version);
   const tools = mapTools(normalizeToolList(frontmatter.tools));
 
   const lines = ["---"];
@@ -155,12 +171,12 @@ export function transformAgent({ source, raw }) {
 
 /**
  * Transform a canonical `skills/<name>/SKILL.md` into a Claude `.claude/skills/<name>/SKILL.md`.
- * @param {{ source: string, raw: string }} input
+ * @param {{ source: string, raw: string, version?: string }} input
  * @returns {string} Full generated file content.
  */
-export function transformSkill({ source, raw }) {
+export function transformSkill({ source, raw, version = "latest" }) {
   const { frontmatter, body: rawBody } = splitFrontmatter(raw, source);
-  const body = stripPiOnlyBlocks(rawBody);
+  const body = rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version);
   const tools = mapTools(normalizeToolList(frontmatter["allowed-tools"]));
 
   const lines = ["---"];

package/src/cli/primitives.mjs

@@ -1,10 +1,75 @@
 import { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
 
 /**
  * Shared CLI primitives for arg parsing, validation, and child process execution.
  * Extracted from scripts/_cli-primitives.mjs per issue #548 Phase 2.
  */
 
+/**
+ * Parse argv with node:util parseArgs while preserving the legacy hand-rolled
+ * parser semantics that several callers depend on:
+ *
+ * - Unknown options/positionals throw `Unknown argument: <raw>`.
+ * - A string option whose value is missing or looks like another flag throws
+ *   `Missing value for <--flag>` (matching {@link requireOptionValue}).
+ *
+ * Returns a Map of canonical option name -> value (last-wins for repeats, which
+ * matches the legacy while/shift loops that simply reassigned on each match).
+ *
+ * @param {string[]} argv
+ * @param {Record<string, { type: "string" | "boolean", short?: string }>} options
+ * @param {(message: string) => Error} [parseError]
+ * @param {{ allowPositionals?: boolean, flagPattern?: RegExp }} [config]
+ * @returns {{ values: Map<string, string | boolean>, positionals: string[] }}
+ */
+export function parseCliTokens(argv, options, parseError = null, { allowPositionals = false, flagPattern = /^--/u } = {}) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options,
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  const values = new Map();
+  const positionals = [];
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      if (allowPositionals) {
+        positionals.push(token.value);
+        continue;
+      }
+      throw toCliError(`Unknown argument: ${token.value}`, parseError);
+    }
+
+    if (token.kind !== "option") {
+      continue;
+    }
+
+    const spec = options[token.name];
+    if (!spec) {
+      throw toCliError(`Unknown argument: ${token.rawName}`, parseError);
+    }
+
+    if (spec.type === "boolean") {
+      // A bare boolean flag carries no value (parseArgs → undefined) and means true;
+      // an explicit inline value (e.g. --flag=false) is honored rather than forced true.
+      values.set(token.name, token.value === undefined ? true : token.value !== "false");
+      continue;
+    }
+
+    const value = token.value;
+    if (typeof value !== "string" || value.length === 0 || flagPattern.test(value)) {
+      throw toCliError(`Missing value for ${token.rawName}`, parseError);
+    }
+    values.set(token.name, value);
+  }
+
+  return { values, positionals };
+}
+
 function toCliError(message, parseError) {
   if (typeof parseError === "function") {
     return parseError(message);
@@ -20,6 +85,25 @@ export function requireOptionValue(args, flag, parseError = null, { flagPattern
   return value;
 }
 
+/**
+ * Token-based equivalent of {@link requireOptionValue} for callers that have
+ * migrated to node:util parseArgs with `tokens: true`. Validates the value
+ * attached to a parsed option token, rejecting missing or flag-like values with
+ * the same `Missing value for <--flag>` message the legacy parsers emitted.
+ *
+ * @param {{ value?: string, rawName?: string }} token - a parseArgs option token
+ * @param {(message: string) => Error} [parseError]
+ * @param {{ flagPattern?: RegExp }} [config]
+ * @returns {string}
+ */
+export function requireTokenValue(token, parseError = null, { flagPattern = /^--/u } = {}) {
+  const value = token?.value;
+  if (typeof value !== "string" || value.length === 0 || flagPattern.test(value)) {
+    throw toCliError(`Missing value for ${token?.rawName}`, parseError);
+  }
+  return value;
+}
+
 export function parsePositiveInteger(value, flag, parseError = null) {
   if (!/^\d+$/.test(value) || Number(value) === 0) {
     throw toCliError(`${flag} must be a positive integer`, parseError);

package/src/config/config.mjs

@@ -53,6 +53,22 @@ const GatesConfig = z.strictObject({
   // `requireCi` is only behaviorally configurable for the draft gate.
   // preApproval always requires CI even if config repeats `requireCi`.
   preApproval: GateConfig.optional(),
+  // Fail-closed enforcement that a gate verdict was produced by the
+  // fan-out/fan-in review sub-loop (executionMode === "fanout_fanin" plus a
+  // durable findings-log ledger), not an inline single-agent run. Default
+  // true (opt-out): a clean gate verdict requires fan-out/fan-in evidence
+  // unless explicitly disabled. See docs/gate-review-sub-loop-contract.md.
+  requireFanoutEvidence: z.boolean().default(true),
+  // Cap on how many scoped `review` reviewers the gate fan-out spawns in
+  // parallel. When the resolved angle set exceeds this cap, the overflow runs
+  // in sequential batches and the degradation is recorded in the gate evidence.
+  maxFanoutReviewers: z.number().int().min(1).max(64).default(8),
+  // Post the consolidated gate fan-out findings as a visible, marker-tagged PR
+  // comment so they are auditable and Copilot/humans are aware of them. Default
+  // true (opt-out). The disposition ledger is written regardless; this flag only
+  // suppresses the PR comment when explicitly false. See
+  // docs/gate-review-sub-loop-contract.md.
+  postFindingsComments: z.boolean().default(true),
 });
 
 const AutonomyConfig = z.strictObject({
@@ -85,6 +101,7 @@ const QueueConfig = z.strictObject({
   reDispatchMaxRetries: z.number().int().min(0).max(10).default(1),
   projectNumber: z.number().int().positive().optional(),
   boardTitle: z.string().trim().min(1).optional(),
+  archiveOlderThanDays: z.number().int().positive().optional(),
 });
 
 /** Internal path whitelist for internal-only PR detection — flat array of regex strings */
@@ -106,6 +123,9 @@ const FileGateConfig = GateConfig.partial();
 const FileGatesConfig = z.strictObject({
   draft: FileGateConfig.optional(),
   preApproval: FileGateConfig.optional(),
+  requireFanoutEvidence: z.boolean().optional(),
+  maxFanoutReviewers: z.number().int().min(1).max(64).optional(),
+  postFindingsComments: z.boolean().optional(),
 });
 
 // Partial persona entries for file-level config (allows omitting fields)
@@ -230,6 +250,8 @@ const BUILTIN_PERSONAS = Object.freeze({
   "state-concurrency": { persona: "review", defaultModel: null },
   "renderer-security": { persona: "review", defaultModel: null },
   determinism:          { persona: "review", defaultModel: null },
+  "acceptance-criteria": { persona: "review", defaultModel: null },
+  "ac-dod":              { persona: "review", defaultModel: null },
 });
 
 const DEFAULT_REVIEWER_PERSONA = "default-reviewer";
@@ -814,6 +836,66 @@ export function resolveGateConfig(config, gate) {
   };
 }
 
+/**
+ * Resolve whether fan-out/fan-in review evidence is required for a gate verdict.
+ *
+ * Default-on (opt-out): enforcement is ON unless `gates.requireFanoutEvidence`
+ * is explicitly set to false. When ON, the pre-merge evidence check fails
+ * closed unless a required gate's recorded executionMode is "fanout_fanin" and
+ * a durable findings-log ledger exists for that gate + head SHA. Using a
+ * `!== false` test (rather than `=== true`) keeps the opt-out semantics robust
+ * for programmatically-built config objects that bypass schema defaulting. See
+ * docs/gate-review-sub-loop-contract.md.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {boolean}
+ */
+export function resolveRequireFanoutEvidence(config) {
+  return config?.gates?.requireFanoutEvidence !== false;
+}
+
+/** Default parallel fan-out reviewer cap (mirrors GatesConfig.maxFanoutReviewers). */
+export const DEFAULT_MAX_FANOUT_REVIEWERS = 8;
+
+/**
+ * Resolve the parallel fan-out reviewer cap for the gate sub-loop.
+ *
+ * Returns the configured `gates.maxFanoutReviewers` when it is an integer in
+ * the schema-bounded range 1..64; otherwise the built-in default (8). Clamping
+ * here (not just the Zod schema) keeps programmatically-constructed config
+ * objects that bypass schema validation within the same bound. The fan-out
+ * spawns at most this many scoped `review` reviewers in parallel; overflow runs
+ * sequentially.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {number}
+ */
+export function resolveMaxFanoutReviewers(config) {
+  const raw = config?.gates?.maxFanoutReviewers;
+  if (typeof raw === "number" && Number.isInteger(raw) && raw >= 1 && raw <= 64) {
+    return raw;
+  }
+  return DEFAULT_MAX_FANOUT_REVIEWERS;
+}
+
+/**
+ * Resolve whether the consolidated gate fan-out findings should be posted as a
+ * visible, marker-tagged PR comment.
+ *
+ * Returns true (post the comment) unless `gates.postFindingsComments` is
+ * explicitly set to false. Using a `!== false` test (rather than `=== true`)
+ * keeps the opt-out semantics robust for programmatically-built config objects
+ * that bypass schema defaulting. The disposition ledger is written regardless;
+ * this flag only suppresses the auditable PR comment. See
+ * docs/gate-review-sub-loop-contract.md.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {boolean}
+ */
+export function resolveGatePostFindingsComments(config) {
+  return config?.gates?.postFindingsComments !== false;
+}
+
 /**
  * Resolve local implementation light mode config.
  *

package/src/config/extension-defaults.yaml

@@ -382,6 +382,18 @@ personas:
       Do not block on formatting preferences other than checkbox correctness.
     defaultModel: null
 
+  acceptance-criteria:
+    persona: review
+    prompt: >-
+      Verify that each acceptance criterion and definition-of-done item from the
+      linked issue/PR is actually satisfied by the implementation — not merely
+      listed. For every criterion, cite the concrete code/test/behavior evidence
+      that meets it; flag any criterion that is unmet, only partially met, or
+      unverifiable from the diff as a blocking finding. Confirm definition-of-done
+      items (tests, docs, validation) are done and that declared non-goals are
+      respected (no scope creep).
+    defaultModel: null
+
   pr-checklist-matrix:
     persona: review
     prompt: >-

package/src/github/copilot-helpers.mjs

@@ -9,6 +9,7 @@
 const SUBMITTED_REVIEW_STATES = new Set(["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"]);
 const GATE_REVIEW_NAMES = new Set(["draft_gate", "pre_approval_gate"]);
 const GATE_REVIEW_VERDICTS = new Set(["clean", "findings_present", "blocked"]);
+const GATE_EXECUTION_MODES = new Set(["fanout_fanin", "inline_single_agent"]);
 
 export function isCopilotLogin(login) {
   return typeof login === "string" && /^copilot(?:[^a-z]|$)/i.test(login);
@@ -63,6 +64,11 @@ function normalizeGateReviewHeadSha(value) {
   return /^[0-9a-f]{7,64}$/i.test(normalized) ? normalized : null;
 }
 
+function normalizeGateExecutionMode(value) {
+  const normalized = stripOptionalCodeTicks(value).toLowerCase();
+  return GATE_EXECUTION_MODES.has(normalized) ? normalized : null;
+}
+
 function parseGateReviewCommentFields(body) {
   if (typeof body !== "string" || body.trim().length === 0) {
     return null;
@@ -74,6 +80,8 @@ function parseGateReviewCommentFields(body) {
     verdict: null,
     findingsSummary: null,
     nextAction: null,
+    executionMode: null,
+    inlineReason: null,
   };
 
   for (const rawLine of body.split(/\r?\n/u)) {
@@ -112,6 +120,24 @@ function parseGateReviewCommentFields(body) {
       fields.nextAction = match[1].trim();
       continue;
     }
+
+    match = line.match(/^(?:[-*]\s*)?execution\s+mode\s*:\s*(.+)$/iu);
+    if (match) {
+      const rest = match[1].trim();
+      // Split on the first em-dash / en-dash / " - " separator to recover an
+      // optional inline reason: "inline_single_agent — <reason>".
+      const sepMatch = rest.match(/^(.*?)\s*(?:[—–]|\s-\s)\s*(.*)$/u);
+      const modeToken = sepMatch ? sepMatch[1].trim() : rest;
+      const reasonToken = sepMatch ? sepMatch[2].trim() : "";
+      fields.executionMode = normalizeGateExecutionMode(modeToken);
+      // Only record an inline reason for inline_single_agent. A trailing
+      // "— text" on a fanout_fanin (or invalid) mode line must not surface an
+      // inconsistent mode/reason pair, so leave inlineReason null otherwise.
+      if (reasonToken.length > 0 && fields.executionMode === "inline_single_agent") {
+        fields.inlineReason = reasonToken;
+      }
+      continue;
+    }
   }
 
   // Lenient fallback: detect gate name and head SHA anywhere in body
@@ -178,6 +204,8 @@ export function parseGateReviewCommentMarkerBody(body) {
     verdict: fields.verdict,
     findingsSummary: fields.findingsSummary,
     nextAction: fields.nextAction,
+    executionMode: fields.executionMode,
+    inlineReason: fields.inlineReason,
     contractComplete: Boolean(fields.verdict && fields.findingsSummary && fields.nextAction),
   };
 }
@@ -205,6 +233,8 @@ export function summarizeGateReviewComments(comments) {
       verdict: parsed.verdict,
       findingsSummary: parsed.findingsSummary,
       nextAction: parsed.nextAction,
+      executionMode: parsed.executionMode ?? null,
+      inlineReason: parsed.inlineReason ?? null,
       commentId: Number.isInteger(comment?.id) ? comment.id : null,
       commentUrl: typeof comment?.html_url === "string" && comment.html_url.trim().length > 0 ? comment.html_url.trim() : null,
       updatedAt: typeof (comment?.updated_at ?? comment?.updatedAt) === "string"
@@ -253,6 +283,8 @@ export function summarizeGateReviewCommentMarkers(comments, { headSha } = {}) {
       verdict: parsed.verdict,
       findingsSummary: parsed.findingsSummary,
       nextAction: parsed.nextAction,
+      executionMode: parsed.executionMode ?? null,
+      inlineReason: parsed.inlineReason ?? null,
       contractComplete: parsed.contractComplete,
       commentId: Number.isInteger(comment?.id) ? comment.id : null,
       commentUrl: typeof comment?.html_url === "string" && comment.html_url.trim().length > 0 ? comment.html_url.trim() : null,
@@ -274,6 +306,39 @@ export function summarizeGateReviewCommentMarkers(comments, { headSha } = {}) {
   return summary;
 }
 
+/**
+ * Resolve the draft-gate round-reset timestamp (ms) used to suppress stale Copilot
+ * review rounds from the count (#896 consistency).
+ *
+ * When the draft gate was re-passed clean on a DIFFERENT head than the current one,
+ * only Copilot reviews submitted after that re-pass should count toward the round
+ * cap. Returning the re-pass `updatedAt` (ms) lets {@link summarizeCopilotReviews}
+ * drop earlier rounds. Returns null when no reset applies (no clean draft gate, or
+ * the clean draft gate is already on the current head).
+ *
+ * Both detect-pr-gate-coordination-state and request-copilot-review must derive the
+ * reset identically, or the two scripts disagree on the completed round count and
+ * the cap (the inconsistency reported in #896). This is the single shared source.
+ *
+ * @param {object} params
+ * @param {{ verdict?: string|null, headSha?: string|null, updatedAt?: string|null }|null} params.draftGate
+ * @param {string|null} params.currentHeadSha
+ * @returns {number|null} reset timestamp in ms, or null
+ */
+export function resolveDraftGateRoundResetMs({ draftGate, currentHeadSha } = {}) {
+  const draftGateHeadSha = typeof draftGate?.headSha === "string" ? draftGate.headSha : null;
+  const draftGateOnCurrentHead = typeof draftGateHeadSha === "string"
+    && typeof currentHeadSha === "string"
+    && currentHeadSha.startsWith(draftGateHeadSha);
+  if (draftGate?.verdict === "clean"
+    && typeof draftGateHeadSha === "string"
+    && !draftGateOnCurrentHead
+    && typeof draftGate?.updatedAt === "string") {
+    return normalizeTimestamp(draftGate.updatedAt);
+  }
+  return null;
+}
+
 export function summarizeCopilotReviews(reviews, { headSha, draftGateResetAtMs } = {}) {
   const allReviews = Array.isArray(reviews) ? reviews : [];
   const copilotReviews = allReviews.filter((review) => isCopilotLogin(review?.author?.login));

package/src/github/review-threads.mjs

@@ -1,5 +1,7 @@
 import { readFile } from "node:fs/promises";
 
+import { parseCliTokens } from "../cli/primitives.mjs";
+
 function normalizeId(value, fallback) {
   if (typeof value === "string" && value.trim().length > 0) {
     return value.trim();
@@ -266,34 +268,14 @@ export function classifyReviewThreadsSignal(parsedResult, isCopilotLoginFn) {
 }
 
 
-function requireOptionValue(args, flag) {
-  const value = args.shift();
-
-  if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
-    throw new Error(`Missing value for ${flag}`);
-  }
-
-  return value;
-}
-
 export function parseCliArgs(argv) {
-  const args = [...argv];
-  const options = {
-    inputPath: undefined,
-  };
-
-  while (args.length > 0) {
-    const token = args.shift();
-
-    if (token === "--input") {
-      options.inputPath = requireOptionValue(args, "--input");
-      continue;
-    }
-
-    throw new Error(`Unknown argument: ${token}`);
-  }
+  const { values } = parseCliTokens(argv, {
+    input: { type: "string" },
+  });
 
-  return options;
+  return {
+    inputPath: values.get("input"),
+  };
 }
 
 export async function readInput({ inputPath, stdin = process.stdin } = {}) {

package/src/loop/copilot-loop-state.mjs

@@ -229,12 +229,6 @@ function isAutoRerequestEligible(snapshot, state) {
  */
 const VALID_SIGNAL_LEVELS = new Set(["high", "mid", "low"]);
 
-function hasExplicitCurrentHeadReviewSignal(raw) {
-  return Boolean(raw)
-    && typeof raw === "object"
-    && Object.prototype.hasOwnProperty.call(raw, "copilotReviewOnCurrentHead");
-}
-
 export function normalizeSnapshot(raw) {
   if (!raw || typeof raw !== "object") {
     throw new Error("Snapshot must be a non-null object");
@@ -351,34 +345,54 @@ export function interpretLoopState(snapshot, refinementConfig) {
 
   // Round-cap enforcement: when maxCopilotRounds is configured and the review-round
   // count has been exhausted, stop re-requests before entering fix/reply-resolve routing.
-  // Gating here (before unresolved-thread checks) ensures round cap takes priority over
-  // the normal fix loop, including unresolved threads, pending CI, and CI failures.
-  // Clean PRs are usually eligible for pre_approval_gate fallback; the only automatic
-  // exception is when the head has advanced since the last submitted Copilot review,
-  // all prior feedback is resolved, and CI is green/credibly green again. In that case
-  // the state re-opens to READY_TO_REREQUEST_REVIEW instead of terminating as clean fallback.
-  // Does NOT interrupt an in-flight review request (requested/already-requested).
+  // Gating here (before unresolved-thread checks) lets a CLEAN PR at the cap terminate as
+  // ROUND_CAP_CLEAN_FALLBACK ahead of the normal fix/wait routing. It does NOT blanket-
+  // override that routing: a NOT-clean PR (unresolved threads or non-green CI) with an
+  // in-flight request deliberately falls through to the normal fix/wait routing below
+  // (see the `!reviewInFlight` branch), and only a not-clean PR with no in-flight request
+  // hard-stops at ROUND_CAP_REACHED.
+  //
+  // Precedence at the cap: copilotReviewRoundCount counts COMPLETED rounds, so at
+  // `>= maxRounds` every permitted Copilot round is already done and any lingering
+  // in-flight request (requested/already-requested) is for a forbidden over-cap round.
+  // A stale Copilot reviewer assignment must therefore NOT block the clean fallback:
+  // when threads are clean and CI is green, route to ROUND_CAP_CLEAN_FALLBACK even if
+  // copilotReviewRequestStatus is requested/already-requested. Otherwise a lingering
+  // assignment would dead-end the loop at WAITING_FOR_COPILOT_REVIEW waiting for a
+  // review that can never come (no further round is permitted past the cap). The
+  // pre_approval_gate (current-head clean evidence, enforced elsewhere) reviews any
+  // post-cap head change, so this proceeds without skipping review of new code.
+  //
+  // An in-flight request only still blocks the cap block when the PR is NOT clean
+  // (unresolved threads or non-green CI) — that legitimately stays in the fix/wait
+  // routing below rather than terminating as a clean fallback.
+  //
+  // Head-advanced handling: even when the head has advanced past the last submitted
+  // Copilot review with clean threads and green CI, re-requesting another Copilot pass
+  // is forbidden at the cap, so this routes to ROUND_CAP_CLEAN_FALLBACK (not
+  // READY_TO_REREQUEST_REVIEW, which would trigger an illegal auto re-request). The
+  // pre_approval_gate handles the current head.
   const maxRounds = refinementConfig?.maxCopilotRounds;
   const reviewInFlight = s.copilotReviewRequestStatus === "requested"
     || s.copilotReviewRequestStatus === "already-requested";
   if (typeof maxRounds === "number" && maxRounds > 0
       && s.copilotReviewRoundCount >= maxRounds
-      && !reviewInFlight
       && state !== STATE.NO_PR && state !== STATE.DONE
       && state !== STATE.PR_DRAFT && state !== STATE.REVIEW_REQUEST_UNAVAILABLE
       && state !== STATE.BLOCKED_NEEDS_USER_DECISION) {
     const ciClean = s.ciStatus === "success" || s.ciStatus === "crediblyGreen";
     const cleanThreads = s.unresolvedThreadCount === 0;
-    const headAdvancedSinceLastSubmittedCopilotReview = s.copilotReviewPresent
-      && hasExplicitCurrentHeadReviewSignal(snapshot)
-      && !s.copilotReviewOnCurrentHead;
-    if (cleanThreads && ciClean && headAdvancedSinceLastSubmittedCopilotReview) {
-      state = STATE.READY_TO_REREQUEST_REVIEW;
-    } else if (cleanThreads && ciClean) {
+    if (cleanThreads && ciClean) {
+      // Clean PR at the cap: proceed to the pre_approval_gate fallback regardless of a
+      // lingering Copilot reviewer assignment or an advanced head — no further Copilot
+      // round is permitted, so never re-open for re-request or wait on Copilot here.
       state = STATE.ROUND_CAP_CLEAN_FALLBACK;
-    } else {
+    } else if (!reviewInFlight) {
+      // Not clean and no in-flight request: hard stop at the cap.
       state = STATE.ROUND_CAP_REACHED;
     }
+    // Not clean WITH an in-flight request: leave state undecided so the normal
+    // fix/reply-resolve/wait routing below handles it (do not force a clean fallback).
   }
 
   if (state === undefined) {