@dev-loops/core 1.0.4-pre.0 → 1.0.4-pre.2

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

@@ -100,7 +100,19 @@ function normalizeGateComment(summary = null) {
   };
 }
 
-function toGateStatus(comment, marker, currentHeadSha) {
+// `unresolvedGateThreadCount` (ADR 0088): the gate-authored review-thread
+// invariant close-gate-findings.mjs/ready-for-review.mjs already enforce
+// (GATE-EXEC-FINDING-THREADS) — a clean marker verdict alone is not
+// sufficient while a gate-authored thread (e.g. an unanswered or
+// not-yet-judge-rejected `question`) still dangles. Folded ONLY into
+// `currentHeadClean` here, never `cleanEvidenceExists`: `undefined`/`null`
+// (the caller did not supply the signal — preApprovalGate's own
+// toGateStatus call never does) preserves the marker-only definition
+// exactly, so only draftGate's `currentHeadClean` — the one field that
+// gates MARK_READY_FOR_REVIEW below — gains this guard. -1 (fail-closed
+// "could not read thread state") counts as NOT clean, same as any positive
+// count.
+function toGateStatus(comment, marker, currentHeadSha, unresolvedGateThreadCount) {
   const normalizedComment = normalizeGateComment(comment);
   const normalizedMarker = normalizeGateComment(marker);
   const markerHeadMatches = normalizedMarker.headSha !== null
@@ -109,6 +121,26 @@ function toGateStatus(comment, marker, currentHeadSha) {
   const anyVisible = normalizedComment.visible || normalizedMarker.visible;
 
   const cleanEvidenceExists = normalizedComment.visible && normalizedComment.verdict === "clean" && normalizedComment.headSha !== null;
+  // Only null/undefined means "the caller supplied no signal" (preApprovalGate's
+  // own toGateStatus call never passes this argument). Anything else that is
+  // not a non-negative integer — NaN, a float, a string, a negative number
+  // other than -1 — is a malformed signal from a future caller, treated the
+  // same as -1 (unreadable) rather than "no signal": this is a public core
+  // export, and failing open on a malformed count would let a broken caller
+  // report currentHeadClean=true with a dangling thread.
+  const hasThreadSignal = unresolvedGateThreadCount !== null && unresolvedGateThreadCount !== undefined;
+  const safeThreadCount = hasThreadSignal
+    ? (Number.isInteger(unresolvedGateThreadCount) && unresolvedGateThreadCount >= 0 ? unresolvedGateThreadCount : -1)
+    : null;
+  const gateThreadsClean = !hasThreadSignal || safeThreadCount === 0;
+  // -1 is a distinct signal from a real positive count: it means the caller
+  // could not even READ the thread state (API failure) or supplied a
+  // malformed value, not that a thread is known to dangle. Both still block
+  // MARK_READY_FOR_REVIEW, but the two get different reasons below (a real
+  // thread names its own remedy; an unreadable count names retrying the read
+  // instead).
+  const gateThreadCountUnreadable = safeThreadCount === -1;
+  const markerVerdictClean = normalizedMarker.visible && markerHeadMatches && normalizedMarker.verdict === "clean" && normalizedMarker.contractComplete;
 
   return {
     visible: normalizedComment.visible,
@@ -120,7 +152,18 @@ function toGateStatus(comment, marker, currentHeadSha) {
     findingsSummary: normalizedComment.findingsSummary ?? normalizedMarker.findingsSummary,
     nextAction: normalizedComment.nextAction ?? normalizedMarker.nextAction,
     contractComplete: normalizedMarker.visible && markerHeadMatches && normalizedMarker.contractComplete,
-    currentHeadClean: normalizedMarker.visible && markerHeadMatches && normalizedMarker.verdict === "clean" && normalizedMarker.contractComplete,
+    currentHeadClean: markerVerdictClean && gateThreadsClean,
+    // ADR 0088: the marker verdict is clean on its own terms, but a
+    // gate-authored thread still dangles — distinct from "not clean at all"
+    // (draftGate below uses this to name the thread blocker directly rather
+    // than re-running the draft gate or blocking on CI, neither of which can
+    // ever clear a dangling thread). Excludes the -1 (unreadable) case below,
+    // which gets its own distinct reason.
+    markerCleanThreadsUnresolved: markerVerdictClean && !gateThreadsClean && !gateThreadCountUnreadable,
+    // The thread-state READ itself failed (-1) rather than reporting a real
+    // dangling thread — MARK_READY_FOR_REVIEW stays forbidden either way, but
+    // this names "retry the read" instead of "resolve a thread".
+    markerCleanThreadStateUnreadable: markerVerdictClean && gateThreadCountUnreadable,
     cleanEvidenceExists,
   };
 }
@@ -467,6 +510,9 @@ function buildResult({
  * @param {boolean} [params.postConvergenceSignificantChange=false] - significant
  *   post-convergence changes on a newer head start a new review cycle and must
  *   not be treated as round-cap clean-fallback suppression.
+ * @param {boolean} [params.postConvergenceReviewSuppressed=false] - the caller
+ *   verified a carried convergence for this head, so no further Copilot request
+ *   is due (mirrors applyUnsettledCopilotReviewEntryGuard).
  * @param {string} params.gateBoundary - current gate boundary
  * @returns {boolean}
  */
@@ -478,6 +524,7 @@ export function shouldGuardCopilotReviewRequest({
   sameHeadCleanConverged = false,
   roundCapCleanFallback = false,
   postConvergenceSignificantChange = false,
+  postConvergenceReviewSuppressed = false,
   gateBoundary,
 }) {
   const gateBoundariesRequiringCopilotFormalRequest = new Set([
@@ -497,6 +544,11 @@ export function shouldGuardCopilotReviewRequest({
   if (copilotReviewRequestStatus !== "none") {
     return false;
   }
+  // A carried convergence settles this head without a new Copilot round; the
+  // request tool would return a suppressed status, so a forced request livelocks.
+  if (postConvergenceReviewSuppressed === true) {
+    return false;
+  }
   // Durable signal: if Copilot was ever formally requested as a reviewer,
   // the current "none" status is from a fulfilled request (normal cycle),
   // not from a missing request. Do not guard the happy path.
@@ -624,18 +676,21 @@ function applyUnsettledCopilotReviewEntryGuard(input, result) {
   //     grant boundary here after gating CI/threads, and a significant
   //     post-convergence change routes to a rerequest (a new cycle) before this
   //     guard runs, so this exemption cannot mask a genuinely-unreviewed change;
-  //   - postConvergenceReviewSuppressed: an operator verified (via
-  //     withdraw-copilot-review-request) that the current-head delta since
-  //     Copilot's last submitted review is a pure doc/prose bump, so the prior
-  //     converged review stands for this head — the core grants pre_approval on
-  //     the same basis (never derived here from other snapshot facts).
+  //   - postConvergenceReviewSuppressed: the caller verified a carried
+  //     convergence (or an operator suppression marker) for this head: no
+  //     outstanding request, zero unresolved threads, and a converged latest
+  //     Copilot review on an earlier head. By default that review carries
+  //     whatever the delta (converged-once); under the strict setting only a
+  //     provably docs-only or integrate-only delta carries. The prior converged
+  //     review then stands for this head (never derived here from other
+  //     snapshot facts).
   // Fail closed on ANY non-outstanding status, not only the literal "none":
   // this is the independent gate-ENTRY re-check, so it must not trust the
   // caller's status string. A non-canonical/unknown value ("", "unavailable",
   // "failed", a typo) with a grant-y lifecycleState and no current-head review
   // fails closed rather than slipping through the "none"-only default. Only a
-  // driven current-head review (or the impossible-further-round cap state, or an
-  // operator-verified pure-doc-bump suppression) exempts, so an agent that skips
+  // driven current-head review (or the impossible-further-round cap state, or a
+  // caller-verified carried convergence) exempts, so an agent that skips
   // the explicit Copilot round cannot reach a clean pre_approval verdict via any
   // grant-y lifecycleState (e.g. a stale/racy low_signal_converged label, or one
   // carried by prior-head rounds).
@@ -723,6 +778,67 @@ function applyUnsettledCopilotReviewEntryGuard(input, result) {
   });
 }
 
+/**
+ * Boundaries at which a PR must carry clean draft_gate evidence; without it
+ * the only legal next action is reconcile_draft_gate
+ * (skills/docs/pr-lifecycle-contract.md, LIFECYCLE-FAIL-CLOSED).
+ */
+const DRAFT_GATE_EVIDENCE_GUARDED_BOUNDARIES = Object.freeze([
+  PR_CHECKPOINT.POST_DRAFT_EXTERNAL_REVIEW,
+  PR_CHECKPOINT.FEEDBACK_RESOLUTION,
+  PR_CHECKPOINT.PRE_APPROVAL_GATE_NEEDED,
+  PR_CHECKPOINT.PRE_APPROVAL_GATE_WINDOW,
+  PR_CHECKPOINT.FINAL_APPROVAL_READY,
+]);
+
+function applyDraftGateEvidenceGuard(result, { prDraft = false } = {}) {
+  if (!result || typeof result !== "object") {
+    return result;
+  }
+  // The PR is still draft: absent/not-yet-clean draft_gate evidence is the
+  // EXPECTED state while draft_gate remediation is in progress (e.g. a fixer
+  // mid-way through COMPLETE_FIXER_DISPOSITION for threads it tackled from an
+  // earlier draft_gate round) — the PR_DRAFT branch above already owns this
+  // state (RUN_DRAFT_GATE / MARK_READY_FOR_REVIEW). This guard exists for the
+  // POST-draft merge-path boundaries only (mirrors the wrapper's own
+  // prDraft skip for the title-marker guard, below); rewriting an in-progress
+  // draft-side result to reconcile_draft_gate would misdirect the fixer.
+  if (prDraft) {
+    return result;
+  }
+  if (result.draftGate?.cleanEvidenceExists === true) {
+    return result;
+  }
+  if (!DRAFT_GATE_EVIDENCE_GUARDED_BOUNDARIES.includes(result.gateBoundary)) {
+    return result;
+  }
+
+  const allowedNextActions = [];
+  const forbiddenActions = [];
+  pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.RECONCILE_DRAFT_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.WAIT_FOR_COPILOT_REVIEW,
+    PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE,
+    PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL,
+    PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY,
+  ]);
+
+  return {
+    ...result,
+    gateBoundary: PR_CHECKPOINT.DRAFT_GATE_NEEDED,
+    nextAction: PR_CHECKPOINT_ACTION.RECONCILE_DRAFT_GATE,
+    allowedNextActions,
+    forbiddenActions,
+    reason: result.draftGate?.anyVisible
+      ? "Clean draft_gate evidence is required before merge (no gate exemptions, #579). A draft_gate comment exists but is not clean; convert the PR back to draft before re-running draft_gate, or clear the existing evidence before running reconcile_draft_gate."
+      : "Clean draft_gate evidence is required before merge (no gate exemptions, #579). No visible clean draft_gate comment exists for this PR; run reconcile_draft_gate before proceeding.",
+    gateEvidenceNote: null,
+  };
+}
+
 /**
  * Evaluates PR gate coordination, then re-asserts the merge-blocking title guard
  * at the pre-approval / final-approval boundary for non-draft PRs.
@@ -731,31 +847,38 @@ function applyUnsettledCopilotReviewEntryGuard(input, result) {
  * sites (defense in depth); this wrapper additionally covers the pre-approval
  * gate boundary, which is reached before any pre-approval evidence exists and so
  * is not protected by the inline checks.
+ *
+ * Invariant: every return path passes through `applyDraftGateEvidenceGuard`,
+ * which rewrites the five DRAFT_GATE_EVIDENCE_GUARDED_BOUNDARIES boundaries to
+ * DRAFT_GATE_NEEDED / reconcile_draft_gate whenever clean draft_gate evidence
+ * is absent — a still-draft PR is exempted (ADR 0088): absent/not-yet-clean
+ * draft_gate evidence is the normal state while draft_gate remediation is in
+ * progress, and the PR_DRAFT branch already owns that state.
  */
 export function evaluatePrGateCoordination(input = {}) {
   const result = evaluatePrGateCoordinationCore(input);
+  const prDraft = input.prDraft === true;
 
   const unsettledReviewResult = applyUnsettledCopilotReviewEntryGuard(input, result);
   if (unsettledReviewResult) {
-    return unsettledReviewResult;
+    return applyDraftGateEvidenceGuard(unsettledReviewResult, { prDraft });
   }
 
-  const prDraft = input.prDraft === true;
   const prTitle = typeof input.prTitle === "string" ? input.prTitle : "";
   // Draft PRs may legitimately carry a WIP title; the marker only blocks once
   // the PR has left draft and is at a pre-approval/final-approval boundary.
   if (prDraft || !result || typeof result !== "object") {
-    return result;
+    return applyDraftGateEvidenceGuard(result, { prDraft });
   }
   if (!TITLE_MARKER_GUARDED_BOUNDARIES.includes(result.gateBoundary)) {
-    return result;
+    return applyDraftGateEvidenceGuard(result, { prDraft });
   }
   const markers = findBlockingTitleMarkers(prTitle);
   if (markers.length === 0) {
-    return result;
+    return applyDraftGateEvidenceGuard(result, { prDraft });
   }
 
-  return buildTitleMarkerBlockedResult({
+  return applyDraftGateEvidenceGuard(buildTitleMarkerBlockedResult({
     input,
     currentHeadSha: result.currentHeadSha ?? null,
     draftGateAlreadySatisfied: result.draftGateAlreadySatisfied === true,
@@ -765,7 +888,7 @@ export function evaluatePrGateCoordination(input = {}) {
     conflictFiles: result.conflictFiles ?? [],
     markers,
     refinementArtifact: result.refinementArtifact ?? null,
-  });
+  }), { prDraft });
 }
 
 function evaluatePrGateCoordinationCore(input = {}) {
@@ -775,14 +898,15 @@ function evaluatePrGateCoordinationCore(input = {}) {
   const prDraft = input.prDraft === true;
   const prClosed = input.prClosed === true;
   const prMerged = input.prMerged === true;
-  const sameHeadCleanConverged = input.sameHeadCleanConverged === true;
-  // Operator-authorized post-convergence suppression: 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 copilotConvergenceOk = input.copilotConvergenceOk === true;
+  // Carried convergence: set only when the caller verified, through the
+  // shared carried-convergence predicate the Copilot request tool also uses,
+  // that the prior converged Copilot review still stands for this head (no
+  // outstanding request, zero unresolved threads, and in strict mode a
+  // provably docs-only or integrate-only delta), or that an operator suppression marker re-verifies
+  // on the same terms. Never derived here from other snapshot facts: this
+  // evaluator trusts the caller's verification, so the request tool and the
+  // gate cannot disagree about the same head.
   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
@@ -833,9 +957,20 @@ function evaluatePrGateCoordinationCore(input = {}) {
   const refinementArtifactStatus = normalizeRefinementArtifactStatus(refinementArtifact?.status);
   const refinementLinkedIssue = Number.isInteger(refinementArtifact?.linkedIssue) ? refinementArtifact.linkedIssue : null;
 
-  const effectiveLifecycleState = lifecycleState;
-
-  const draftGate = toGateStatus(input.draftGate, input.draftGateMarker, currentHeadSha);
+  // Keep the shared loop's body-feedback signal intact. Gate entry alone may
+  // reinterpret a thread-clean, current-head review that the shared convergence
+  // evaluator accepts (notably a conductor-overridable blue review).
+  const gateEntryConverged = copilotConvergenceOk
+    && input.copilotReviewOnCurrentHead === true
+    && unresolvedThreadCount === 0;
+  const effectiveLifecycleState = gateEntryConverged && lifecycleState === STATE.UNRESOLVED_FEEDBACK_PRESENT
+    ? STATE.READY_TO_REREQUEST_REVIEW
+    : (gateEntryConverged && lifecycleState === STATE.ROUND_CAP_REACHED
+        ? STATE.ROUND_CAP_CLEAN_FALLBACK
+        : lifecycleState);
+  const sameHeadCleanConverged = input.sameHeadCleanConverged === true || gateEntryConverged;
+
+  const draftGate = toGateStatus(input.draftGate, input.draftGateMarker, currentHeadSha, input.unresolvedGateThreadCount);
   const preApprovalGate = toGateStatus(input.preApprovalGate, input.preApprovalGateMarker, currentHeadSha);
   const draftGateAlreadySatisfied = !prDraft && (draftGate?.cleanEvidenceExists ?? false);
 
@@ -1118,7 +1253,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         lifecycleState: STATE.BLOCKED_NEEDS_USER_DECISION,
         loopDisposition: DISPOSITION.BLOCKED,
         gateBoundary: PR_CHECKPOINT.BLOCKED,
-        draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+        draftGateAlreadySatisfied,
         draftGate,
         preApprovalGate,
         allowedNextActions,
@@ -1138,6 +1273,83 @@ function evaluatePrGateCoordinationCore(input = {}) {
       PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY,
     ];
 
+    // ADR 0088: the round's draft_gate marker verdict is ALREADY clean — CI
+    // pending/failing or re-running draft_gate can never clear a dangling
+    // gate-authored thread (e.g. an answered, judge-rejected `question`
+    // close-gate-findings has not yet reject-closed), so this must run BEFORE
+    // the CI-status checks below: neither a CI-blocked nor a run_draft_gate
+    // result would name the real blocker, and a loop that followed
+    // run_draft_gate would re-run a gate round that already passed.
+    // reply_resolve_review_threads (FEEDBACK_RESOLUTION) is reused as-is —
+    // resolving the thread (reject-close or fixer triage) is exactly what
+    // this action already means on the post-draft path.
+    if (draftGate.markerCleanThreadsUnresolved) {
+      pushUnique(allowedNextActions, [
+        PR_CHECKPOINT_ACTION.REPLY_RESOLVE_REVIEW_THREADS,
+        // The reason text names "stop for the operator" as the remedy for an
+        // unanswered question that cannot be answered — that escalation must
+        // be a legal next action, not just prose an allowedNextActions-honoring
+        // conductor has no sanctioned way to take.
+        PR_CHECKPOINT_ACTION.REPORT_BLOCKED,
+      ]);
+      pushUnique(forbiddenActions, [
+        PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
+        ...draftReviewForbidden,
+      ]);
+      return buildResult({
+        repo: input.repo ?? null,
+        pr: Number.isInteger(input.pr) ? input.pr : null,
+        currentHeadSha,
+        lifecycleState: lifecycleState || STATE.PR_DRAFT,
+        loopDisposition: DISPOSITION.UNRESOLVED_FEEDBACK,
+        gateBoundary: PR_CHECKPOINT.FEEDBACK_RESOLUTION,
+        draftGateAlreadySatisfied,
+        draftGate,
+        preApprovalGate,
+        allowedNextActions,
+        forbiddenActions,
+        nextAction: PR_CHECKPOINT_ACTION.REPLY_RESOLVE_REVIEW_THREADS,
+        reason: "The PR is still draft and this round's draft_gate verdict is clean, but a gate-authored review thread is still unresolved (ADR 0088) — reply/resolve it rather than re-running the draft gate. An open defect thread is resolved via fixer fix-close, or the disposition pass's defer-close (close-gate-findings) once eligible. A question thread's remedy depends on the judge's disposition: unanswered — post an answer reply, then rerun close-gate-findings, which reject-closes it if the judge disposed it reject; answered and judge-disposed reject — rerun close-gate-findings to reject-close it; answered and judge-disposed act — resolved by the fixer's own answer-and-resolve path; judge-deferred, or ambiguous/unrecorded disposition — needs an operator decision, no automated path.",
+        mergeStateStatus,
+        conflictFiles,
+        refinementArtifact,
+        copilotReviewRoundCount,
+      });
+    }
+
+    // Distinct from markerCleanThreadsUnresolved above: the thread-state READ
+    // itself failed (unresolvedGateThreadCount === -1), not a real dangling
+    // thread — naming "resolve the thread" would be misleading when there is
+    // no known thread to resolve. MARK_READY_FOR_REVIEW stays forbidden
+    // either way (draftReviewForbidden); reply_resolve_review_threads is
+    // reused as-is rather than adding a new action for "retry the read".
+    if (draftGate.markerCleanThreadStateUnreadable) {
+      pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPLY_RESOLVE_REVIEW_THREADS]);
+      pushUnique(forbiddenActions, [
+        PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
+        ...draftReviewForbidden,
+      ]);
+      return buildResult({
+        repo: input.repo ?? null,
+        pr: Number.isInteger(input.pr) ? input.pr : null,
+        currentHeadSha,
+        lifecycleState: lifecycleState || STATE.PR_DRAFT,
+        loopDisposition: DISPOSITION.UNRESOLVED_FEEDBACK,
+        gateBoundary: PR_CHECKPOINT.FEEDBACK_RESOLUTION,
+        draftGateAlreadySatisfied,
+        draftGate,
+        preApprovalGate,
+        allowedNextActions,
+        forbiddenActions,
+        nextAction: PR_CHECKPOINT_ACTION.REPLY_RESOLVE_REVIEW_THREADS,
+        reason: "The PR is still draft and this round's draft_gate verdict is clean, but this round's gate-authored review-thread count could not be read (API failure) — could not read review-thread state; re-run when API connectivity is restored, rather than treating an unreadable count as either clean or a real dangling thread.",
+        mergeStateStatus,
+        conflictFiles,
+        refinementArtifact,
+        copilotReviewRoundCount,
+      });
+    }
+
     if (!draftGate.currentHeadClean && draftGateRequireCi) {
       if (ciStatus === "failure") {
         pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
@@ -1152,7 +1364,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
           lifecycleState: STATE.BLOCKED_NEEDS_USER_DECISION,
           loopDisposition: DISPOSITION.BLOCKED,
           gateBoundary: PR_CHECKPOINT.BLOCKED,
-          draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+          draftGateAlreadySatisfied,
           draftGate,
           preApprovalGate,
           allowedNextActions,
@@ -1178,7 +1390,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
           lifecycleState: STATE.WAITING_FOR_CI,
           loopDisposition: DISPOSITION.PENDING,
           gateBoundary: PR_CHECKPOINT.DRAFT_REVIEW,
-          draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+          draftGateAlreadySatisfied,
           draftGate,
           preApprovalGate,
           allowedNextActions,
@@ -1250,7 +1462,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
           lifecycleState: STATE.BLOCKED_NEEDS_USER_DECISION,
           loopDisposition: DISPOSITION.BLOCKED,
           gateBoundary: PR_CHECKPOINT.BLOCKED,
-          draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+          draftGateAlreadySatisfied,
           draftGate,
           preApprovalGate,
           allowedNextActions,
@@ -1270,7 +1482,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
           return buildTitleMarkerBlockedResult({
             input,
             currentHeadSha,
-            draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+            draftGateAlreadySatisfied,
             draftGate,
             preApprovalGate,
             mergeStateStatus,
@@ -1302,7 +1514,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
           lifecycleState: effectiveLifecycleState,
           loopDisposition: loopDisposition ?? DISPOSITION.CLEAN_CONVERGED,
           gateBoundary: PR_CHECKPOINT.FINAL_APPROVAL_READY,
-          draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+          draftGateAlreadySatisfied,
           draftGate,
           preApprovalGate,
           allowedNextActions,
@@ -1326,7 +1538,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         lifecycleState: effectiveLifecycleState,
         loopDisposition: loopDisposition ?? DISPOSITION.ACTION_REQUIRED,
         gateBoundary: PR_CHECKPOINT.PRE_APPROVAL_GATE_WINDOW,
-        draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+        draftGateAlreadySatisfied,
         draftGate,
         preApprovalGate,
         allowedNextActions,
@@ -1453,7 +1665,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         lifecycleState: STATE.BLOCKED_NEEDS_USER_DECISION,
         loopDisposition: DISPOSITION.BLOCKED,
         gateBoundary: PR_CHECKPOINT.BLOCKED,
-        draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+        draftGateAlreadySatisfied,
         draftGate,
         preApprovalGate,
         allowedNextActions,
@@ -1478,7 +1690,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         lifecycleState: STATE.WAITING_FOR_CI,
         loopDisposition: DISPOSITION.PENDING,
         gateBoundary: PR_CHECKPOINT.POST_DRAFT_EXTERNAL_REVIEW,
-        draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+        draftGateAlreadySatisfied,
         draftGate,
         preApprovalGate,
         allowedNextActions,
@@ -1512,7 +1724,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         lifecycleState: effectiveLifecycleState,
         loopDisposition: loopDisposition ?? DISPOSITION.ACTION_REQUIRED,
         gateBoundary: PR_CHECKPOINT.POST_DRAFT_EXTERNAL_REVIEW,
-        draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+        draftGateAlreadySatisfied,
         draftGate,
         preApprovalGate,
         allowedNextActions,
@@ -1533,7 +1745,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         return buildTitleMarkerBlockedResult({
           input,
           currentHeadSha,
-          draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+          draftGateAlreadySatisfied,
           draftGate,
           preApprovalGate,
           mergeStateStatus,
@@ -1543,7 +1755,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         });
       }
 
-      if (!draftGate.cleanEvidenceExists && !roundCapReached) {
+      if (!draftGate.cleanEvidenceExists) {
         return buildDraftGateNeededForMergeResult({
           input,
           currentHeadSha,
@@ -1571,14 +1783,14 @@ function evaluatePrGateCoordinationCore(input = {}) {
         lifecycleState: effectiveLifecycleState,
         loopDisposition: loopDisposition ?? DISPOSITION.CLEAN_CONVERGED,
         gateBoundary: PR_CHECKPOINT.FINAL_APPROVAL_READY,
-        draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+        draftGateAlreadySatisfied,
         draftGate,
         preApprovalGate,
         allowedNextActions,
         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, ${describeAcceptedCiState(ciStatus, preApprovalRequireCi)}). The current head has clean \`pre_approval_gate\` evidence, so the PR is at the final approval boundary.`
+          ? `Round-cap clean fallback (${copilotReviewRoundCount}/${maxCopilotRounds} rounds, zero unresolved threads, ${describeAcceptedCiState(ciStatus, preApprovalRequireCi)}) with clean draft_gate evidence; 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."),
@@ -1611,7 +1823,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
       reason: roundCapReached
         ? `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."
+          ? "The current head carries the prior converged Copilot review (carriedConvergence names the source review): no request is outstanding, no review thread is unresolved, and the carry rule holds (converged-once by default; a provably docs-only or integrate-only delta under refinement.requireCopilotConvergenceAtLatestHead), 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.")),
@@ -1647,7 +1859,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         lifecycleState: STATE.BLOCKED_NEEDS_USER_DECISION,
         loopDisposition: DISPOSITION.BLOCKED,
         gateBoundary: PR_CHECKPOINT.BLOCKED,
-        draftGateAlreadySatisfied: true,
+        draftGateAlreadySatisfied,
         draftGate,
         preApprovalGate,
         allowedNextActions,
@@ -1671,7 +1883,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         lifecycleState: STATE.WAITING_FOR_CI,
         loopDisposition: DISPOSITION.PENDING,
         gateBoundary: PR_CHECKPOINT.POST_DRAFT_EXTERNAL_REVIEW,
-        draftGateAlreadySatisfied: true,
+        draftGateAlreadySatisfied,
         draftGate,
         preApprovalGate,
         allowedNextActions,
@@ -1689,7 +1901,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         return buildTitleMarkerBlockedResult({
           input,
           currentHeadSha,
-          draftGateAlreadySatisfied: true,
+          draftGateAlreadySatisfied,
           draftGate,
           preApprovalGate,
           mergeStateStatus,
@@ -1700,11 +1912,12 @@ function evaluatePrGateCoordinationCore(input = {}) {
       }
       // Mirror LOW_SIGNAL_CONVERGED: a clean current head with no clean
       // draft_gate evidence must reconcile the draft gate rather than jump to
-      // final approval. This keeps the core handler consistent with the
-      // detect-pr-gate-coordination-state post-pass, which unconditionally
-      // downgrades FINAL_APPROVAL_READY → DRAFT_GATE_NEEDED when
-      // draftGate.cleanEvidenceExists is false (no ROUND_CAP_CLEAN_FALLBACK
-      // exemption). Without this guard the final-approval-without-draft-gate
+      // final approval. This is the SAME rule applyDraftGateEvidenceGuard
+      // enforces generically for every DRAFT_GATE_EVIDENCE_GUARDED_BOUNDARIES
+      // boundary on a non-draft PR (draftGate.cleanEvidenceExists false →
+      // reconcile_draft_gate); this inline check covers the same outcome for
+      // FINAL_APPROVAL_READY specifically, before that wrapper-level guard
+      // runs. Without this guard the final-approval-without-draft-gate
       // branch is dead through the real script and asserts behavior it never
       // produces.
       if (!draftGate.cleanEvidenceExists) {
@@ -1737,13 +1950,13 @@ function evaluatePrGateCoordinationCore(input = {}) {
         lifecycleState: effectiveLifecycleState,
         loopDisposition: loopDisposition ?? DISPOSITION.CLEAN_CONVERGED,
         gateBoundary: PR_CHECKPOINT.FINAL_APPROVAL_READY,
-        draftGateAlreadySatisfied: true,
+        draftGateAlreadySatisfied,
         draftGate,
         preApprovalGate,
         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, ${describeAcceptedCiState(ciStatus, preApprovalRequireCi)}). The current head has clean \`pre_approval_gate\` evidence, so the PR is at the final approval boundary.`,
+        reason: `Round-cap clean fallback (${copilotReviewRoundCount}/${maxCopilotRounds} rounds, zero unresolved threads, ${describeAcceptedCiState(ciStatus, preApprovalRequireCi)}) with clean draft_gate evidence; the current head has clean \`pre_approval_gate\` evidence, so the PR is at the final approval boundary.`,
         mergeStateStatus,
         conflictFiles,
           refinementArtifact,
@@ -1764,7 +1977,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
       lifecycleState: effectiveLifecycleState,
       loopDisposition: loopDisposition ?? DISPOSITION.CLEAN_CONVERGED,
       gateBoundary: PR_CHECKPOINT.PRE_APPROVAL_GATE_WINDOW,
-      draftGateAlreadySatisfied: true,
+      draftGateAlreadySatisfied,
       draftGate,
       preApprovalGate,
       allowedNextActions,
@@ -1807,7 +2020,15 @@ function evaluatePrGateCoordinationCore(input = {}) {
     // human-read reason/evidence text for the latter case would be a false CI
     // claim, so describe the actual grant basis instead.
     const ciClause = ciStatus === "success" ? "green CI" : "CI not required by config";
-    if (unresolvedThreadCount === 0 && ciConfirmedGreen) {
+    // No current-head Copilot review at the cap IS the round-cap clean
+    // fallback, so the convergence evaluator's absent-review refusal must not
+    // block this grant; a current-head review with findings still does. An
+    // unknown head never opens the absent-review branch. Nor does an
+    // earlier-head body-only finding without a disposition record: the caller
+    // must state it absent (fail closed when the fact is missing).
+    const absentReviewFallback = currentHeadSha !== null && input.copilotReviewOnCurrentHead === false
+      && input.copilotPriorHeadBodyFeedbackUnresolved === false;
+    if (unresolvedThreadCount === 0 && ciConfirmedGreen && (copilotConvergenceOk || absentReviewFallback)) {
       if (preApprovalGate.currentHeadClean) {
         // Inline title-marker check, mirroring ROUND_CAP_CLEAN_FALLBACK: the
         // outer post-pass guards FINAL_APPROVAL_READY and
@@ -1819,7 +2040,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
           return buildTitleMarkerBlockedResult({
             input,
             currentHeadSha,
-            draftGateAlreadySatisfied: true,
+            draftGateAlreadySatisfied,
             draftGate,
             preApprovalGate,
             mergeStateStatus,
@@ -1859,13 +2080,13 @@ function evaluatePrGateCoordinationCore(input = {}) {
           lifecycleState: effectiveLifecycleState,
           loopDisposition: loopDisposition ?? DISPOSITION.CLEAN_CONVERGED,
           gateBoundary: PR_CHECKPOINT.FINAL_APPROVAL_READY,
-          draftGateAlreadySatisfied: true,
+          draftGateAlreadySatisfied,
           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.`,
+          reason: `Round-cap exhaustion fallback (${copilotReviewRoundCount}/${maxCopilotRounds} rounds, zero unresolved threads, ${ciClause}) with clean draft_gate evidence; the current head has clean \`pre_approval_gate\` evidence, so the PR is at the final approval boundary.`,
           mergeStateStatus,
           conflictFiles,
           refinementArtifact,
@@ -1887,7 +2108,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         lifecycleState: effectiveLifecycleState,
         loopDisposition: loopDisposition ?? DISPOSITION.CLEAN_CONVERGED,
         gateBoundary: PR_CHECKPOINT.PRE_APPROVAL_GATE_WINDOW,
-        draftGateAlreadySatisfied: true,
+        draftGateAlreadySatisfied,
         draftGate,
         preApprovalGate,
         allowedNextActions,
@@ -1914,7 +2135,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         lifecycleState: STATE.BLOCKED_NEEDS_USER_DECISION,
         loopDisposition: DISPOSITION.BLOCKED,
         gateBoundary: PR_CHECKPOINT.BLOCKED,
-        draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+        draftGateAlreadySatisfied,
         draftGate,
         preApprovalGate,
         allowedNextActions,
@@ -1938,7 +2159,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         lifecycleState: STATE.WAITING_FOR_CI,
         loopDisposition: DISPOSITION.PENDING,
         gateBoundary: PR_CHECKPOINT.POST_DRAFT_EXTERNAL_REVIEW,
-        draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+        draftGateAlreadySatisfied,
         draftGate,
         preApprovalGate,
         allowedNextActions,
@@ -1956,7 +2177,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         return buildTitleMarkerBlockedResult({
           input,
           currentHeadSha,
-          draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+          draftGateAlreadySatisfied,
           draftGate,
           preApprovalGate,
           mergeStateStatus,
@@ -1994,7 +2215,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         lifecycleState: effectiveLifecycleState,
         loopDisposition: DISPOSITION.DONE,
         gateBoundary: PR_CHECKPOINT.FINAL_APPROVAL_READY,
-        draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+        draftGateAlreadySatisfied,
         draftGate,
         preApprovalGate,
         allowedNextActions,