@dev-loops/core 1.0.0-rc.3 → 1.0.0-rc.5

package/src/loop/handoff-envelope.mjs

@@ -21,7 +21,7 @@ import {
 import { normalizeRepoSlug } from "../github/repo-slug.mjs";
 import { COPILOT_REVIEW_WAIT_TIMEOUT_MS } from "./policy-constants.mjs";
 import { resolveEffectiveAsyncStartMode } from "./async-start-contract.mjs";
-import { resolveGateConfig, resolveHumanMergeOnly } from "../config/config.mjs";
+import { resolveGateAngleContract, resolveGateAngles, resolveGateConfig, resolveHumanMergeOnly } from "../config/config.mjs";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -95,7 +95,7 @@ register(INTERNAL_DEV_LOOP_STRATEGY.COPILOT_PR_FOLLOWUP, "watch", {
 register(INTERNAL_DEV_LOOP_STRATEGY.COPILOT_PR_FOLLOWUP, "pre-approval", {
   criteria: [
     { id: "full-gate-chain", must: "Complete pre-approval gate chain with all configured review angles.", severity: "required" },
-    { id: "clean-verdict", must: "Pre-approval gate must return clean verdict (no must-fix or worth-fixing-now findings).", severity: "required" },
+    { id: "clean-verdict", must: "Pre-approval gate must return clean verdict (no findings at a severity in the gate's configured blockCleanOnFindingSeverities, high by default).", severity: "required" },
     { id: "unresolved-threads", must: "All review threads must be resolved before pre-approval gate runs.", severity: "required" },
     { id: "ci-green", must: "CI must be green on the current head SHA.", severity: "required" },
   ],
@@ -356,14 +356,25 @@ function deriveGateConfig(settings, subGate) {
   const gateKey = subGate === "pre-approval" ? "preApproval" : subGate;
   if (!settings?.gates?.[gateKey]) return undefined;
 
-  // Route through the canonical resolver rather than re-parsing
-  // gates.<gate>.angles by hand: resolveGateConfig already folds the unified
-  // angle-entry shape (mandatory/enabled per-entry, D3) into this same
-  // exclude-filtered angles + separate excludeAngles list the envelope
-  // contract has always shipped.
+  // Route through the canonical resolvers rather than re-parsing
+  // gates.<gate>.angles by hand: resolveGateConfig folds the unified
+  // angle-entry shape (mandatory/enabled per-entry, D3) into excludeAngles/
+  // blockCleanOnFindingSeverities/requireCi, the envelope contract's
+  // long-standing shape. `angles` is the RUN-set (the configured angles the
+  // orchestrator is told to dispatch) with every validator-MANDATORY angle
+  // merged in — never resolveGateAngleContract's `pool`, which is the
+  // enforcement CEILING and deliberately widens to the whole lens catalog
+  // under gates.<gate>.dynamic.additive (advertising that as the run-set
+  // would tell the orchestrator to dispatch 20+ angles). The parity contract
+  // (test/contracts/envelope-validator-angle-parity.test.mjs) pins both
+  // invariants: everything advertised is within the validator pool, and
+  // every mandatory angle is advertised.
   const resolved = resolveGateConfig(settings, gateKey);
+  const { mandatoryAngles } = resolveGateAngleContract(settings, gateKey);
+  const runSet = resolveGateAngles(settings, gateKey) ?? [];
+  const angles = [...new Set([...runSet, ...mandatoryAngles])];
   return {
-    angles: resolved.angles ?? [],
+    angles,
     excludeAngles: resolved.excludeAngles.length > 0 ? resolved.excludeAngles : undefined,
     blockCleanOnFindingSeverities: resolved.blockCleanOnFindingSeverities,
     requireCi: resolved.requireCi,
@@ -613,14 +624,9 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
 
   const envelope = {
     handoffVersion: ENVELOPE_HANDOFF_VERSION,
-    derivedAt: (now ?? new Date()).toISOString(),
 
     target,
     currentGate: subGate,
-    currentHeadSha: gs.currentHeadSha,
-    ciStatus: gs.ciStatus,
-    unresolvedThreadCount: gs.unresolvedThreadCount,
-    copilotRoundCount: gs.copilotRoundCount,
     maxCopilotRounds: settings?.refinement?.maxCopilotRounds ?? 5,
     executionMode,
 
@@ -674,6 +680,20 @@ export function buildDevLoopHandoffEnvelope(resolverOutput, settings, gateState
     envelope.specSource = specSource;
   }
 
+  // #1462: the ONLY per-round-varying block, kept LAST. Every field here changes
+  // between builds/rounds (the timestamp, the head SHA, CI status, thread/round
+  // counts); isolating them as the envelope's tail keeps everything above a
+  // byte-stable prefix that a fresh reviewer spawn can cache-READ instead of
+  // re-billing the full contract scaffolding each round. Consumers must treat
+  // gateState as volatile — read it last, or re-derive it fresh via detectors.
+  envelope.gateState = {
+    derivedAt: (now ?? new Date()).toISOString(),
+    currentHeadSha: gs.currentHeadSha,
+    ciStatus: gs.ciStatus,
+    unresolvedThreadCount: gs.unresolvedThreadCount,
+    copilotRoundCount: gs.copilotRoundCount,
+  };
+
   return deepFreeze(envelope);
 }
 
@@ -940,9 +960,10 @@ export function validateHandoffEnvelope(envelope) {
     }
   }
 
-  // ----- derivedAt (informational, warn on missing) -----
-  if (typeof envelope.derivedAt !== "string" || !envelope.derivedAt.trim()) {
-    warnings.push({ field: "derivedAt", reason: "should be an ISO 8601 timestamp" });
+  // ----- gateState.derivedAt (informational, warn on missing) — #1462 moved the
+  // volatile timestamp into the gateState tail so the rest stays byte-stable -----
+  if (typeof envelope.gateState?.derivedAt !== "string" || !envelope.gateState.derivedAt.trim()) {
+    warnings.push({ field: "gateState.derivedAt", reason: "should be an ISO 8601 timestamp" });
   }
 
   return {

package/src/loop/issue-refinement-artifact.mjs

@@ -148,20 +148,25 @@ function findSectionByPatterns(sections, patterns) {
 }
 
 /**
- * Extract bullet items from a section body. Counts both `- [ ]`/`- [x]`
- * checklist items and top-level plain `- ` bullets (dash at column 0, so
- * nested/indented sub-bullets are not counted). Empty checkbox placeholders
- * (`- [ ]` / `- [x]` with no trailing text) are skipped, not counted, so a
- * section of only unfilled placeholders reports as unrefined. Returns the
- * trimmed item text for each matching line. The checkbox state (checked vs
- * unchecked) is intentionally not preserved: callers only need the item
- * text to satisfy the refinement-artifact contract.
+ * Parse bullet/checkbox items from a section body into item states. Each
+ * checkbox item (`- [ ]`/`- [x]`/`- [X]`) becomes `{ text, checked }`
+ * (`checked` true only for a ticked `[x]`/`[X]`); a top-level plain bullet
+ * (`- text`, dash at column 0 so nested/indented sub-bullets are not counted)
+ * becomes `{ text, checked: null }` — it has no checkbox to tick. Empty
+ * checkbox placeholders (`- [ ]` / `- [x]` with no trailing text) are skipped,
+ * not counted, so a section of only unfilled placeholders reports as unrefined.
+ * Code-fenced lines are skipped (same fence logic as parseMarkdownSections,
+ * issue #1025) so a body cannot spoof the AC/DoD gate with code-fenced
+ * checkboxes.
  *
- * This is only ever called on the body of an already-recognized AC/DoD
- * section (see `detectIssueRefinementArtifact`), so counting plain bullets
- * is scoped to those sections and never affects prose sections.
+ * Shared by `extractChecklistItems` (text-only) and the unticked-AC check
+ * (`extractUncheckedChecklistItems`) so the two never drift on what counts as
+ * a checklist item or on the checkbox-state read (#1621). Only ever called on
+ * the body of an already-recognized AC/DoD section (see
+ * `detectIssueRefinementArtifact`), so counting plain bullets is scoped to
+ * those sections and never affects prose sections.
  */
-export function extractChecklistItems(sectionBody) {
+function parseChecklistItems(sectionBody) {
   if (typeof sectionBody !== "string" || sectionBody.length === 0) {
     return [];
   }
@@ -171,9 +176,6 @@ export function extractChecklistItems(sectionBody) {
   let fence = null;
 
   for (const line of lines) {
-    // Checkboxes/bullets inside a fenced code span are non-interactive text, not
-    // real items — skip them so a body cannot spoof the AC/DoD gate with
-    // code-fenced checkboxes (issue #1025). Same fence logic as parseMarkdownSections.
     const step = stepFence(fence, line);
     fence = step.fence;
     if (step.insideFence) {
@@ -186,7 +188,10 @@ export function extractChecklistItems(sectionBody) {
     if (checkboxMatch) {
       const text = (checkboxMatch[1] ?? "").trim();
       if (text.length > 0) {
-        items.push(text);
+        // `checked` is true only for a ticked box; `[ ]` (space) is false.
+        // A plain bullet has no checkbox, so it stays `null` below — it is
+        // neither ticked nor unticked and does not count as an unticked AC.
+        items.push({ text, checked: /^\s*-\s+\[[xX]\]/u.test(line) });
       }
       continue;
     }
@@ -196,7 +201,7 @@ export function extractChecklistItems(sectionBody) {
     if (bulletMatch) {
       const text = bulletMatch[1].trim();
       if (text.length > 0) {
-        items.push(text);
+        items.push({ text, checked: null });
       }
     }
   }
@@ -204,6 +209,32 @@ export function extractChecklistItems(sectionBody) {
   return items;
 }
 
+/**
+ * Extract bullet items from a section body. Counts both `- [ ]`/`- [x]`
+ * checklist items and top-level plain `- ` bullets. Empty checkbox placeholders
+ * are skipped. Returns the trimmed item text for each matching line; the
+ * checkbox state is not preserved (use `extractUncheckedChecklistItems` for
+ * that). Thin wrapper over `parseChecklistItems` so the text-only contract
+ * stays byte-identical to its pre-#1621 shape.
+ */
+export function extractChecklistItems(sectionBody) {
+  return parseChecklistItems(sectionBody).map((item) => item.text);
+}
+
+/**
+ * Extract the text of UNCHECKED checkbox items (`- [ ]`) from a section body.
+ * A ticked box (`- [x]`/`- [X]`) and a plain bullet (no checkbox) are both
+ * excluded — only an actual unticked checkbox is an "unticked AC item"
+ * (#1621, ACCEPT-CRITERIA-VERIFY-AND-REFLECT). Empty placeholders are skipped.
+ * Thin wrapper over `parseChecklistItems` so the unticked read never drifts
+ * from `extractChecklistItems` on what counts as a checklist item.
+ */
+export function extractUncheckedChecklistItems(sectionBody) {
+  return parseChecklistItems(sectionBody)
+    .filter((item) => item.checked === false)
+    .map((item) => item.text);
+}
+
 /**
  * Detect a linked refinement doc path from the issue body.
  * Looks for explicit `tmp/refinement/<n>-plan.md` style paths and the
@@ -246,6 +277,7 @@ export function detectLinkedRefinementDoc(body) {
  *   hasACs: boolean,
  *   source: string,
  *   acItems: string[],
+ *   uncheckedAcItems: string[],
  *   dodItems: string[],
  *   sections: string[],
  *   linkedDoc: { found: boolean, path: string|null, reason: string },
@@ -259,6 +291,7 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null }
       hasACs: false,
       source: REFINEMENT_SOURCE.MISSING,
       acItems: [],
+      uncheckedAcItems: [],
       dodItems: [],
       sections: [],
       linkedDoc: { found: false, path: null, reason: "empty-body" },
@@ -274,6 +307,11 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null }
   const dodSection = findSectionByPatterns(sections, DOD_SECTION_PATTERNS);
 
   const acItems = acceptanceSection ? extractChecklistItems(acceptanceSection.bodyLines.join("\n")) : [];
+  // Unticked AC checkboxes (`- [ ]`) of the spec-of-record — the
+  // ACCEPT-CRITERIA-VERIFY-AND-REFLECT precondition a clean pre_approval_gate
+  // must refuse on (#1621). Only actual unticked checkboxes count; a ticked
+  // box and a plain bullet (no checkbox) are both excluded.
+  const uncheckedAcItems = acceptanceSection ? extractUncheckedChecklistItems(acceptanceSection.bodyLines.join("\n")) : [];
   const dodItems = dodSection ? extractChecklistItems(dodSection.bodyLines.join("\n")) : [];
 
   const linkedDoc = detectLinkedRefinementDoc(body);
@@ -283,6 +321,7 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null }
       hasACs: true,
       source: REFINEMENT_SOURCE.ISSUE_BODY_AC,
       acItems,
+      uncheckedAcItems,
       dodItems,
       sections: sectionNames,
       linkedDoc,
@@ -296,6 +335,7 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null }
       hasACs: true,
       source: REFINEMENT_SOURCE.ISSUE_BODY_DOD,
       acItems,
+      uncheckedAcItems,
       dodItems,
       sections: sectionNames,
       linkedDoc,
@@ -309,6 +349,7 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null }
       hasACs: true,
       source: REFINEMENT_SOURCE.LINKED_DOC,
       acItems: [],
+      uncheckedAcItems: [],
       dodItems: [],
       sections: sectionNames,
       linkedDoc,
@@ -321,6 +362,7 @@ export function detectIssueRefinementArtifact({ body = "", issueNumber = null }
     hasACs: false,
     source: REFINEMENT_SOURCE.MISSING,
     acItems: [],
+    uncheckedAcItems: [],
     dodItems: [],
     sections: sectionNames,
     linkedDoc,
@@ -537,7 +579,7 @@ export function decideEnqueueRefinementGate({ artifact, targetIsPickup, auto = f
   const reason =
     `Issue has no refinement artifact (none of: ${missing.join(", ")}). ` +
     "Add at least ONE of them — an Acceptance criteria section, a Definition of done section, or a linked refinement doc " +
-    "(e.g. run `/loop-grill <issue> --auto`, or the refiner) — before it enters the pickup queue.";
+    "(e.g. run `/dev-loops:loop-grill <issue> --auto` (or `/loop-grill <issue> --auto` in the dev-loops repo itself), or the refiner) — before it enters the pickup queue.";
   return { action: auto ? "divert" : "block", reason, missing };
 }
 

package/src/loop/main-checkout-ff.mjs

@@ -0,0 +1,58 @@
+/**
+ * Main-checkout fast-forward command shape (#1596).
+ *
+ * The dev-loop merges remotely (`gh pr merge` → origin/main) but neither the merge
+ * procedure nor the post-merge hooks fast-forwarded the main checkout's local
+ * `main`. Read-only gate scripts (`probe-ci-status.mjs`, `detect-copilot-loop-state.mjs`,
+ * …) run from the main checkout, so a stale local `main` made them execute pre-merge
+ * code — re-introducing the CI-wait stall every PR (e.g. #1531's fix was invisible
+ * until the main checkout caught up).
+ *
+ * This module owns the shared, dependency-free command string both harness hooks
+ * (Pi `post-merge-update`, Claude `post-tool-use-merge`) run after a successful
+ * merge. It is best-effort and NON-BLOCKING: `--ff-only` refuses a diverged `main`
+ * without rewriting history, so a diverged checkout fails the merge step cleanly and
+ * the caller treats that as warn-and-continue (never a hard failure, never a force
+ * push). `mainCheckout` is POSIX single-quoted so consumer checkout paths containing
+ * spaces or shell metacharacters cannot break or inject into the shell string.
+ *
+ * The `merge --ff-only` is guarded to only run when the main checkout is currently on
+ * `main`, so a non-`main` checkout (detached HEAD, or another branch checked out)
+ * warns-and-continues instead of fast-forwarding the wrong branch. No `git switch` is
+ * performed (a state change) — only the guard test runs.
+ *
+ * No imports so this file vendors into the `.claude/hooks/` bundle unchanged
+ * (vendored modules may only import `node:` builtins or relative paths).
+ */
+
+/**
+ * Timeout (ms) for the `git worktree list` resolution step (the fetch-half budget;
+ * a separate fetch timeout isn't applied — the fetch runs inline within the merge
+ * command under `MAIN_CHECKOUT_FF_MERGE_TIMEOUT_MS`).
+ */
+export const MAIN_CHECKOUT_FF_FETCH_TIMEOUT_MS = 60_000;
+
+/** Timeout (ms) for the `git merge --ff-only origin/main` half. */
+export const MAIN_CHECKOUT_FF_MERGE_TIMEOUT_MS = 60_000;
+
+/**
+ * POSIX single-quote a path so spaces/shell metacharacters in a consumer's checkout
+ * path cannot break or inject into the shell string.
+ */
+function shellQuotePath(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Build the best-effort main-checkout fast-forward command string.
+ *
+ * @param {string} mainCheckout - Absolute path to the main (primary) git checkout.
+ * @returns {string} `git -C '<main>' fetch origin main && [ "$(git -C '<main>' rev-parse --abbrev-ref HEAD)" = main ] && git -C '<main>' merge --ff-only origin/main` (path POSIX single-quoted; merge only runs when the main checkout is on `main`)
+ */
+export function buildMainCheckoutFastForwardCommand(mainCheckout) {
+  const quoted = shellQuotePath(mainCheckout);
+  // ponytail: guard with a `[ ... = main ]` test instead of switching branches — a
+  // non-main checkout fails the && chain (warn-and-continue) rather than ff-ing the
+  // wrong branch. No state change, no git switch.
+  return `git -C ${quoted} fetch origin main && [ "$(git -C ${quoted} rev-parse --abbrev-ref HEAD)" = main ] && git -C ${quoted} merge --ff-only origin/main`;
+}

package/src/loop/pr-gate-coordination.mjs

@@ -252,8 +252,26 @@ function formatRefinementBlockedReason(linkedIssue, status, refinementArtifact)
   return `The draft gate cannot complete: the linked issue has no detectable refinement artifact (Acceptance criteria / DoD / linked refinement doc). finding=${REFINEMENT_ARTIFACT_FINDING}`;
 }
 
-function buildRoundExhaustionGateEvidenceNote({ copilotReviewRoundCount, maxCopilotRounds }) {
-  return `Copilot review rounds exhausted (${copilotReviewRoundCount}/${maxCopilotRounds}); current head has zero unresolved threads and green or credibly green CI, so pre_approval_gate fallback is allowed without another Copilot re-request.`;
+// #1472: describes the CI state a round-cap-reached fallback branch actually
+// granted on, for human-read reason text. preApprovalRequireCi:false plus a
+// non-success/non-crediblyGreen ciStatus is not "green CI" — claiming it is
+// would be the same false-CI-claim buildRoundExhaustionGateEvidenceNote below
+// exists to avoid. The `ciStatus === "success"` fallback covers the
+// requireCi:true path, where these callers are only reachable with ciStatus
+// "success" (failure/crediblyGreen/pending/none all return earlier).
+function describeAcceptedCiState(ciStatus, preApprovalRequireCi) {
+  if (ciStatus === "crediblyGreen") return "credibly green CI";
+  if (ciStatus === "success" || preApprovalRequireCi !== false) return "green CI";
+  return "CI not required by config";
+}
+
+function buildRoundExhaustionGateEvidenceNote({ copilotReviewRoundCount, maxCopilotRounds, ciStatus, preApprovalRequireCi, ciDescriptor }) {
+  // One rule serves both the reason string and this note. A branch whose CI
+  // acceptance differs from describeAcceptedCiState (the strict-green grant
+  // rejects crediblyGreen as a basis) passes its own descriptor explicitly so
+  // reason and note can never disagree.
+  const descriptor = ciDescriptor ?? describeAcceptedCiState(ciStatus, preApprovalRequireCi);
+  return `Copilot review rounds exhausted (${copilotReviewRoundCount}/${maxCopilotRounds}); current head has zero unresolved threads and ${descriptor}, so pre_approval_gate fallback is allowed without another Copilot re-request.`;
 }
 
 /**
@@ -514,6 +532,21 @@ const PRE_APPROVAL_ENTRY_BOUNDARIES = Object.freeze([
   PR_CHECKPOINT.FINAL_APPROVAL_READY,
 ]);
 
+/**
+ * Identifies the ROUND_CAP_REACHED branch's own defensive grant shape (see
+ * that branch below): lifecycleState stays round_cap_reached (never
+ * round_cap_clean_fallback) while gateBoundary settles on
+ * pre_approval_gate_window. Every caller that exempts the round-cap clean
+ * fallback from the formal-request / unsettled-review guards
+ * (applyUnsettledCopilotReviewEntryGuard below, and
+ * detect-pr-gate-coordination-state.mjs's shouldGuardCopilotReviewRequest
+ * wiring) must exempt this shape too, or the grant this evaluator just
+ * returned gets rewritten straight back to a Copilot-review wait.
+ */
+export function isRoundCapReachedCleanGrant({ lifecycleState, gateBoundary } = {}) {
+  return lifecycleState === STATE.ROUND_CAP_REACHED && gateBoundary === PR_CHECKPOINT.PRE_APPROVAL_GATE_WINDOW;
+}
+
 function applyUnsettledCopilotReviewEntryGuard(input, result) {
   if (!result || typeof result !== "object" || !PRE_APPROVAL_ENTRY_BOUNDARIES.includes(result.gateBoundary)) {
     return null;
@@ -544,7 +577,12 @@ function applyUnsettledCopilotReviewEntryGuard(input, result) {
     maxCopilotRounds: input.maxCopilotRounds,
   });
   const lifecycleState = typeof input.lifecycleState === "string" ? input.lifecycleState.trim().toLowerCase() : "";
-  const roundCapCleanFallback = lifecycleState === STATE.ROUND_CAP_CLEAN_FALLBACK;
+  // Also exempt the evaluator's own ROUND_CAP_REACHED grant shape (#1472):
+  // without this, this guard would rewrite that grant back to
+  // waiting_for_copilot_review the instant it is produced, re-introducing the
+  // never-arriving-review dead-end the round-cap exemption exists to prevent.
+  const roundCapCleanFallback = lifecycleState === STATE.ROUND_CAP_CLEAN_FALLBACK
+    || isRoundCapReachedCleanGrant(result);
   if (
     roundCapReached
     && (input.sameHeadCleanConverged === true || roundCapCleanFallback)
@@ -647,6 +685,14 @@ function evaluatePrGateCoordinationCore(input = {}) {
   const prClosed = input.prClosed === true;
   const prMerged = input.prMerged === true;
   const sameHeadCleanConverged = input.sameHeadCleanConverged === true;
+  // Operator-authorized post-convergence suppression (#1441): set only when the
+  // caller has verified an explicit prior withdrawal (withdraw-copilot-review-
+  // request.mjs) recorded a suppression marker for this EXACT head, proving the
+  // delta since Copilot's last submitted review is a pure doc/prose bump. Never
+  // derived here from other snapshot facts — this evaluator trusts the caller's
+  // verification rather than re-deriving it, so it cannot become an automatic
+  // loosening of the round-below-cap precondition.
+  const postConvergenceReviewSuppressed = input.postConvergenceReviewSuppressed === true;
   // maxCopilotRounds: 0 disables the external Copilot review gate entirely
   // (for repos without Copilot / local-harness-only review). It reuses the
   // existing internal_only routing — skip the Copilot cycle, go straight to
@@ -668,6 +714,15 @@ function evaluatePrGateCoordinationCore(input = {}) {
   const copilotReviewRoundCount = normalizeNonNegativeInteger(input.copilotReviewRoundCount);
   const maxCopilotRounds = normalizePositiveInteger(input.maxCopilotRounds);
   const roundCapReached = isCopilotRoundCapReached({ copilotReviewRoundCount, maxCopilotRounds });
+  // #1472: explicit current-head unresolved-thread signal for the round-cap
+  // fallback check below (STATE.ROUND_CAP_REACHED). Unlike copilotReviewRoundCount
+  // (which safely defaults to 0 when absent), an absent/invalid count here must
+  // NOT be coerced to 0 — that would silently treat an unknown thread count as
+  // clean and wrongly unblock the fallback. `null` means "unknown" (fail closed).
+  const unresolvedThreadCount = Number.isInteger(input.unresolvedThreadCount)
+    && input.unresolvedThreadCount >= 0
+    ? input.unresolvedThreadCount
+    : null;
   const postConvergenceSignificantChange = input.postConvergenceSignificantChange === true;
   const roundCapNewCycleRequired = roundCapReached && copilotReviewRoundCount > 0 && postConvergenceSignificantChange;
   const prTitle = typeof input.prTitle === "string" ? input.prTitle : "";
@@ -1255,10 +1310,10 @@ function evaluatePrGateCoordinationCore(input = {}) {
     }
 
     const roundExhaustionGateEvidenceNote = (roundCapReached && !roundCapNewCycleRequired)
-      ? buildRoundExhaustionGateEvidenceNote({ copilotReviewRoundCount, maxCopilotRounds })
+      ? buildRoundExhaustionGateEvidenceNote({ copilotReviewRoundCount, maxCopilotRounds, ciStatus, preApprovalRequireCi })
       : null;
 
-    if (!sameHeadCleanConverged && (!roundCapReached || roundCapNewCycleRequired)) {
+    if (!sameHeadCleanConverged && !postConvergenceReviewSuppressed && (!roundCapReached || roundCapNewCycleRequired)) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REREQUEST_COPILOT_REVIEW]);
       pushUnique(forbiddenActions, postDraftForbidden);
       return buildResult({
@@ -1334,7 +1389,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         forbiddenActions,
         nextAction: PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL,
         reason: roundCapReached
-          ? `Round-cap clean fallback accepted as draft gate equivalent (${copilotReviewRoundCount}/${maxCopilotRounds} rounds, zero unresolved threads, ${ciStatus === "crediblyGreen" ? "credibly green" : "green"} CI). The current head has clean \`pre_approval_gate\` evidence, so the PR is at the final approval boundary.`
+          ? `Round-cap clean fallback accepted as draft gate equivalent (${copilotReviewRoundCount}/${maxCopilotRounds} rounds, zero unresolved threads, ${describeAcceptedCiState(ciStatus, preApprovalRequireCi)}). The current head has clean \`pre_approval_gate\` evidence, so the PR is at the final approval boundary.`
           : (ciStatus === "crediblyGreen"
             ? "The current head has both a clean settled review cycle and clean `pre_approval_gate` evidence, and its zero-suite CI state is accepted as credibly green, so the PR is at the final approval boundary."
             : "The current head has both a clean settled review cycle and clean `pre_approval_gate` evidence, so the PR is at the final approval boundary."),
@@ -1365,10 +1420,12 @@ function evaluatePrGateCoordinationCore(input = {}) {
       forbiddenActions,
       nextAction: PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE,
       reason: roundCapReached
-        ? `The Copilot round limit is exhausted (${copilotReviewRoundCount}/${maxCopilotRounds}), and the current head has zero unresolved threads with ${ciStatus === "crediblyGreen" ? "credibly green" : "green"} CI, so \`pre_approval_gate\` fallback is now the next legal boundary.`
-        : (ciStatus === "crediblyGreen"
-          ? "The current head has a clean settled post-draft review cycle, and its zero-suite CI state is accepted as credibly green, so `pre_approval_gate` is now the next legal boundary."
-          : "The current head has a clean settled post-draft review cycle, so `pre_approval_gate` is now the next legal boundary."),
+        ? `The Copilot round limit is exhausted (${copilotReviewRoundCount}/${maxCopilotRounds}), and the current head has zero unresolved threads with ${describeAcceptedCiState(ciStatus, preApprovalRequireCi)}, so \`pre_approval_gate\` fallback is now the next legal boundary.`
+        : (postConvergenceReviewSuppressed && !sameHeadCleanConverged
+          ? "An operator explicitly withdrew a stranded Copilot review request for this exact head, whose delta since Copilot's last submitted review is a provable pure doc/prose bump; the prior converged Copilot review still stands, so `pre_approval_gate` is now the next legal boundary."
+          : (ciStatus === "crediblyGreen"
+            ? "The current head has a clean settled post-draft review cycle, and its zero-suite CI state is accepted as credibly green, so `pre_approval_gate` is now the next legal boundary."
+            : "The current head has a clean settled post-draft review cycle, so `pre_approval_gate` is now the next legal boundary.")),
       mergeStateStatus,
       conflictFiles,
       gateEvidenceNote: roundCapReached ? roundExhaustionGateEvidenceNote : null,
@@ -1497,7 +1554,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         allowedNextActions,
         forbiddenActions,
         nextAction: PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL,
-        reason: `Round-cap clean fallback accepted as draft gate equivalent (${copilotReviewRoundCount}/${maxCopilotRounds} rounds, zero unresolved threads, ${ciStatus === "crediblyGreen" ? "credibly green" : "green"} CI). The current head has clean \`pre_approval_gate\` evidence, so the PR is at the final approval boundary.`,
+        reason: `Round-cap clean fallback accepted as draft gate equivalent (${copilotReviewRoundCount}/${maxCopilotRounds} rounds, zero unresolved threads, ${describeAcceptedCiState(ciStatus, preApprovalRequireCi)}). The current head has clean \`pre_approval_gate\` evidence, so the PR is at the final approval boundary.`,
         mergeStateStatus,
         conflictFiles,
           refinementArtifact,
@@ -1524,15 +1581,139 @@ function evaluatePrGateCoordinationCore(input = {}) {
       allowedNextActions,
       forbiddenActions,
       nextAction: PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE,
-      reason: `The Copilot round limit is exhausted (${copilotReviewRoundCount}/${maxCopilotRounds}), and the current head has zero unresolved threads with ${ciStatus === "crediblyGreen" ? "credibly green" : "green"} CI, so \`pre_approval_gate\` fallback is now the next legal boundary (it reviews the current post-cap head; no further Copilot re-request is permitted).`,
+      reason: `The Copilot round limit is exhausted (${copilotReviewRoundCount}/${maxCopilotRounds}), and the current head has zero unresolved threads with ${describeAcceptedCiState(ciStatus, preApprovalRequireCi)}, so \`pre_approval_gate\` fallback is now the next legal boundary (it reviews the current post-cap head; no further Copilot re-request is permitted).`,
       mergeStateStatus,
       conflictFiles,
       refinementArtifact,
-      gateEvidenceNote: buildRoundExhaustionGateEvidenceNote({ copilotReviewRoundCount, maxCopilotRounds }),
+      gateEvidenceNote: buildRoundExhaustionGateEvidenceNote({ copilotReviewRoundCount, maxCopilotRounds, ciStatus, preApprovalRequireCi }),
     copilotReviewRoundCount,
     });
   }
 
+  // Defensive gate-entry re-check for ROUND_CAP_REACHED (#1472): the compound
+  // "unresolved threads OR non-clean CI" hard stop that copilot-loop-state.mjs
+  // emits has no dedicated boundary of its own, so without this branch the
+  // generic fallback below always names `report_blocked`. Both shipped
+  // callers read lifecycleState and the CI/thread facts from ONE snapshot, and
+  // the interpreter's own CI predicate is strictly wider than this branch's
+  // (it also accepts `crediblyGreen`, #1371): whenever this branch's narrower
+  // predicate and zero unresolved threads hold, the interpreter has already
+  // classified the snapshot ROUND_CAP_CLEAN_FALLBACK, never ROUND_CAP_REACHED
+  // (see the equivalence test in pr-gate-coordination.test.mjs). This branch
+  // is therefore unreachable through the shipped callers — it is pure
+  // defense-in-depth, demanded by issue 1472's corrected AC so the three
+  // fields can never disagree if a future caller hands the evaluator a
+  // round_cap_reached label alongside facts that satisfy the grant. The
+  // predicate intentionally mirrors every other pre-approval CI boundary in
+  // this file (success, or CI not required) — `crediblyGreen` is unconfirmed
+  // CI and stays blocked here exactly as it does everywhere else (#1371). Any
+  // other combination (threads still unresolved, an unknown thread count, or
+  // CI not confirmed green) falls through unchanged to the generic default
+  // below, preserving today's blocked behavior exactly.
+  if (effectiveLifecycleState === STATE.ROUND_CAP_REACHED && roundCapReached) {
+    const ciConfirmedGreen = ciStatus === "success" || !preApprovalRequireCi;
+    // ciConfirmedGreen above is only true when ciStatus is literally "success"
+    // OR CI is not required by config — never for an unconfirmed/failing/absent
+    // status gated in only because requireCi is false. Naming it "green" in
+    // human-read reason/evidence text for the latter case would be a false CI
+    // claim (#1472 defer), so describe the actual grant basis instead.
+    const ciClause = ciStatus === "success" ? "green CI" : "CI not required by config";
+    if (unresolvedThreadCount === 0 && ciConfirmedGreen) {
+      if (preApprovalGate.currentHeadClean) {
+        // Inline title-marker check, mirroring ROUND_CAP_CLEAN_FALLBACK: the
+        // outer post-pass guards FINAL_APPROVAL_READY and
+        // PRE_APPROVAL_GATE_WINDOW, but NOT the DRAFT_GATE_NEEDED boundary the
+        // sub-branch below can return — without this check a marker-titled
+        // head would route to reconcile_draft_gate instead of blocking.
+        const grantTitleMarkers = findBlockingTitleMarkers(prTitle);
+        if (grantTitleMarkers.length > 0) {
+          return buildTitleMarkerBlockedResult({
+            input,
+            currentHeadSha,
+            draftGateAlreadySatisfied: true,
+            draftGate,
+            preApprovalGate,
+            mergeStateStatus,
+            conflictFiles,
+            markers: grantTitleMarkers,
+            refinementArtifact,
+          });
+        }
+        // Mirror ROUND_CAP_CLEAN_FALLBACK/#579: a clean current head with no clean
+        // draft_gate evidence must reconcile the draft gate rather than jump to
+        // final approval.
+        if (!draftGate.cleanEvidenceExists) {
+          return buildDraftGateNeededForMergeResult({
+            input,
+            currentHeadSha,
+            draftGate,
+            preApprovalGate,
+            mergeStateStatus,
+            conflictFiles,
+            underlyingReason: "Round-cap exhaustion fallback has clean pre_approval_gate but no clean draft_gate evidence.",
+            refinementArtifact,
+            effectiveLifecycleState,
+          });
+        }
+
+        pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL]);
+        pushUnique(forbiddenActions, [
+          PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
+          PR_CHECKPOINT_ACTION.MARK_READY_FOR_REVIEW,
+          PR_CHECKPOINT_ACTION.REQUEST_COPILOT_REVIEW,
+          PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY,
+        ]);
+        return buildResult({
+          repo: input.repo ?? null,
+          pr: Number.isInteger(input.pr) ? input.pr : null,
+          currentHeadSha,
+          lifecycleState: effectiveLifecycleState,
+          loopDisposition: loopDisposition ?? DISPOSITION.CLEAN_CONVERGED,
+          gateBoundary: PR_CHECKPOINT.FINAL_APPROVAL_READY,
+          draftGateAlreadySatisfied: true,
+          draftGate,
+          preApprovalGate,
+          allowedNextActions,
+          forbiddenActions,
+          nextAction: PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL,
+          reason: `Round-cap exhaustion fallback accepted as draft gate equivalent (${copilotReviewRoundCount}/${maxCopilotRounds} rounds, zero unresolved threads, ${ciClause}). The current head has clean \`pre_approval_gate\` evidence, so the PR is at the final approval boundary.`,
+          mergeStateStatus,
+          conflictFiles,
+          refinementArtifact,
+        });
+      }
+
+      pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE]);
+      pushUnique(forbiddenActions, [
+        PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
+        PR_CHECKPOINT_ACTION.MARK_READY_FOR_REVIEW,
+        PR_CHECKPOINT_ACTION.REQUEST_COPILOT_REVIEW,
+        PR_CHECKPOINT_ACTION.REREQUEST_COPILOT_REVIEW,
+        PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY,
+      ]);
+      return buildResult({
+        repo: input.repo ?? null,
+        pr: Number.isInteger(input.pr) ? input.pr : null,
+        currentHeadSha,
+        lifecycleState: effectiveLifecycleState,
+        loopDisposition: loopDisposition ?? DISPOSITION.CLEAN_CONVERGED,
+        gateBoundary: PR_CHECKPOINT.PRE_APPROVAL_GATE_WINDOW,
+        draftGateAlreadySatisfied: true,
+        draftGate,
+        preApprovalGate,
+        allowedNextActions,
+        forbiddenActions,
+        nextAction: PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE,
+        reason: `The Copilot round limit is exhausted (${copilotReviewRoundCount}/${maxCopilotRounds}), and the current head has zero unresolved threads and ${ciClause}, so \`pre_approval_gate\` fallback is now the next legal boundary (it reviews the current post-cap head; no further Copilot re-request is permitted).`,
+        mergeStateStatus,
+        conflictFiles,
+        refinementArtifact,
+        gateEvidenceNote: buildRoundExhaustionGateEvidenceNote({ copilotReviewRoundCount, maxCopilotRounds, ciDescriptor: ciClause }),
+        copilotReviewRoundCount,
+      });
+    }
+  }
+
   if (effectiveLifecycleState === STATE.LOW_SIGNAL_CONVERGED) {
     if (preApprovalRequireCi && (ciStatus === "failure" || ciStatus === "crediblyGreen")) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);