@dev-loops/core 1.0.3 → 1.0.4-pre.1

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,
   };
 }
@@ -592,7 +635,60 @@ function applyUnsettledCopilotReviewEntryGuard(input, result) {
   const copilotReviewRequestStatus = typeof input.copilotReviewRequestStatus === "string"
     ? input.copilotReviewRequestStatus.trim().toLowerCase()
     : "none";
-  if (copilotReviewRequestStatus !== "requested" && copilotReviewRequestStatus !== "already-requested") {
+  const sameHeadCleanConverged = input.sameHeadCleanConverged === true;
+  const copilotReviewRoundCount = normalizeNonNegativeInteger(input.copilotReviewRoundCount);
+  const copilotReviewOnCurrentHead = input.copilotReviewOnCurrentHead === true;
+  const outstandingRequest = copilotReviewRequestStatus === "requested"
+    || copilotReviewRequestStatus === "already-requested";
+  const roundCapReached = isCopilotRoundCapReached({
+    copilotReviewRoundCount: input.copilotReviewRoundCount,
+    maxCopilotRounds: input.maxCopilotRounds,
+  });
+  // Absent / never-driven: Copilot review is enabled (maxCopilotRounds
+  // > 0, not internal_only) but no round was requested or received for the
+  // CURRENT head, so a clean pre_approval_gate verdict would rest on nothing the
+  // loop actually drove on the head under review. The reconciled status alone is
+  // ambiguous: the reconciler (resolveCopilotReviewRequestStatus) folds a clean
+  // same-head submitted review into "none" too. Three facts each prove this is
+  // not the never-driven case and exempt this branch:
+  //   - sameHeadCleanConverged: a clean same-head submitted Copilot review
+  //     exists on THIS head (including GitHub's incidental auto-review) — the
+  //     no-redundant-re-request case;
+  //   - copilotReviewOnCurrentHead: a submitted Copilot review exists on THIS
+  //     head (a settled current-head round; at a grant boundary its threads are
+  //     already resolved). This is keyed on CURRENT-HEAD evidence, never a raw
+  //     across-PR round count: copilotReviewRoundCount counts reviews on ANY
+  //     head, so a PR with prior-head rounds and a NEW current head that carries
+  //     no review (interpreter state low_signal_converged with
+  //     copilotReviewOnCurrentHead false) must still fail closed;
+  //   - roundCapReached: at/past the cap no further Copilot round can be driven,
+  //     so requiring a current-head review is impossible to satisfy — the
+  //     pre_approval_gate reviews the post-cap head. The core only reaches a
+  //     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: the caller verified a carried
+  //     convergence (or an operator suppression marker) for this head: no
+  //     outstanding request, zero unresolved threads, and a provably docs-only
+  //     or integrate-only delta since Copilot's last submitted review, so the
+  //     prior converged review 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
+  // 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).
+  const absentNeverDriven = !outstandingRequest
+    && !copilotReviewOnCurrentHead
+    && !sameHeadCleanConverged
+    && !roundCapReached
+    && input.postConvergenceReviewSuppressed !== true;
+  if (!outstandingRequest && !absentNeverDriven) {
     return null;
   }
   // Round-cap exemption (mirrors shouldGuardCopilotReviewRequest):
@@ -603,10 +699,6 @@ function applyUnsettledCopilotReviewEntryGuard(input, result) {
   // and the head is clean — either sameHeadCleanConverged or the interpreter's
   // round_cap_clean_fallback state — the pre_approval_gate proceeds unless
   // significant post-convergence changes require a new review cycle.
-  const roundCapReached = isCopilotRoundCapReached({
-    copilotReviewRoundCount: input.copilotReviewRoundCount,
-    maxCopilotRounds: input.maxCopilotRounds,
-  });
   const lifecycleState = typeof input.lifecycleState === "string" ? input.lifecycleState.trim().toLowerCase() : "";
   // Also exempt the evaluator's own ROUND_CAP_REACHED grant shape:
   // without this, this guard would rewrite that grant back to
@@ -624,7 +716,15 @@ function applyUnsettledCopilotReviewEntryGuard(input, result) {
 
   const allowedNextActions = [];
   const forbiddenActions = [];
-  pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.WAIT_FOR_COPILOT_REVIEW]);
+  // Two shapes fail closed here. An OUTSTANDING request (requested/
+  // already-requested) waits for the current-head review to settle. The
+  // ABSENT / never-driven case has nothing to wait for — no request is
+  // in flight — so the loop must first REQUEST a Copilot review, mirroring the
+  // detector-side shouldGuardCopilotReviewRequest override.
+  const nextAction = absentNeverDriven
+    ? PR_CHECKPOINT_ACTION.REQUEST_COPILOT_REVIEW
+    : PR_CHECKPOINT_ACTION.WAIT_FOR_COPILOT_REVIEW;
+  pushUnique(allowedNextActions, [nextAction]);
   // Full postDraftForbidden set (matching the canonical WAITING_FOR_COPILOT_REVIEW
   // result this guard synthesizes) plus the final-approval actions the replaced
   // boundary result also forbade — dropping RUN_DRAFT_GATE/MARK_READY_FOR_REVIEW
@@ -642,18 +742,24 @@ function applyUnsettledCopilotReviewEntryGuard(input, result) {
     repo: input.repo ?? null,
     pr: Number.isInteger(input.pr) ? input.pr : null,
     currentHeadSha: result.currentHeadSha ?? null,
-    lifecycleState: STATE.WAITING_FOR_COPILOT_REVIEW,
-    loopDisposition: DISPOSITION.PENDING,
+    lifecycleState: absentNeverDriven ? STATE.PR_READY_NO_FEEDBACK : STATE.WAITING_FOR_COPILOT_REVIEW,
+    loopDisposition: absentNeverDriven ? DISPOSITION.ACTION_REQUIRED : DISPOSITION.PENDING,
     gateBoundary: PR_CHECKPOINT.POST_DRAFT_EXTERNAL_REVIEW,
     draftGateAlreadySatisfied: result.draftGateAlreadySatisfied === true,
     draftGate: result.draftGate,
     preApprovalGate: result.preApprovalGate,
     allowedNextActions,
     forbiddenActions,
-    nextAction: PR_CHECKPOINT_ACTION.WAIT_FOR_COPILOT_REVIEW,
-    reason: "A Copilot review request is still outstanding on the current head (independent gate-entry "
-      + "re-check, issue #1190) — pre_approval_gate/final-approval entry is refused until the current-head "
-      + "review settles, even though the caller-reported convergence signal claims otherwise.",
+    nextAction,
+    reason: absentNeverDriven
+      ? "Copilot review is enabled for this repo (maxCopilotRounds > 0) but no Copilot review round has been "
+        + "requested or received for the current head (independent gate-entry re-check, issue #2146) — a clean "
+        + "pre_approval_gate/final-approval verdict requires a Copilot round the loop actually drove and awaited, "
+        + "so request Copilot review first. A clean same-head submitted Copilot review (including GitHub's "
+        + "auto-review) would satisfy this; an absent/never-driven round is not settled convergence."
+      : "A Copilot review request is still outstanding on the current head (independent gate-entry "
+        + "re-check, issue #1190) — pre_approval_gate/final-approval entry is refused until the current-head "
+        + "review settles, even though the caller-reported convergence signal claims otherwise.",
     mergeStateStatus: result.mergeStateStatus ?? null,
     conflictFiles: result.conflictFiles ?? [],
     refinementArtifact: result.refinementArtifact ?? null,
@@ -661,6 +767,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.
@@ -669,31 +836,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,
@@ -703,7 +877,7 @@ export function evaluatePrGateCoordination(input = {}) {
     conflictFiles: result.conflictFiles ?? [],
     markers,
     refinementArtifact: result.refinementArtifact ?? null,
-  });
+  }), { prDraft });
 }
 
 function evaluatePrGateCoordinationCore(input = {}) {
@@ -713,14 +887,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, 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
@@ -771,9 +946,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);
 
@@ -1056,7 +1242,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,
@@ -1076,6 +1262,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]);
@@ -1090,7 +1353,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,
@@ -1116,7 +1379,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,
@@ -1188,7 +1451,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,
@@ -1208,7 +1471,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
           return buildTitleMarkerBlockedResult({
             input,
             currentHeadSha,
-            draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+            draftGateAlreadySatisfied,
             draftGate,
             preApprovalGate,
             mergeStateStatus,
@@ -1240,7 +1503,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,
@@ -1264,7 +1527,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,
@@ -1391,7 +1654,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,
@@ -1416,7 +1679,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,
@@ -1450,7 +1713,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,
@@ -1471,7 +1734,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         return buildTitleMarkerBlockedResult({
           input,
           currentHeadSha,
-          draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+          draftGateAlreadySatisfied,
           draftGate,
           preApprovalGate,
           mergeStateStatus,
@@ -1481,7 +1744,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         });
       }
 
-      if (!draftGate.cleanEvidenceExists && !roundCapReached) {
+      if (!draftGate.cleanEvidenceExists) {
         return buildDraftGateNeededForMergeResult({
           input,
           currentHeadSha,
@@ -1509,14 +1772,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."),
@@ -1549,7 +1812,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: no request is outstanding, no review thread is unresolved, and the delta since Copilot's last submitted review is provably docs-only or integrate-only, 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.")),
@@ -1585,7 +1848,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         lifecycleState: STATE.BLOCKED_NEEDS_USER_DECISION,
         loopDisposition: DISPOSITION.BLOCKED,
         gateBoundary: PR_CHECKPOINT.BLOCKED,
-        draftGateAlreadySatisfied: true,
+        draftGateAlreadySatisfied,
         draftGate,
         preApprovalGate,
         allowedNextActions,
@@ -1609,7 +1872,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,
@@ -1627,7 +1890,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         return buildTitleMarkerBlockedResult({
           input,
           currentHeadSha,
-          draftGateAlreadySatisfied: true,
+          draftGateAlreadySatisfied,
           draftGate,
           preApprovalGate,
           mergeStateStatus,
@@ -1638,11 +1901,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) {
@@ -1675,13 +1939,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,
@@ -1702,7 +1966,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
       lifecycleState: effectiveLifecycleState,
       loopDisposition: loopDisposition ?? DISPOSITION.CLEAN_CONVERGED,
       gateBoundary: PR_CHECKPOINT.PRE_APPROVAL_GATE_WINDOW,
-      draftGateAlreadySatisfied: true,
+      draftGateAlreadySatisfied,
       draftGate,
       preApprovalGate,
       allowedNextActions,
@@ -1745,7 +2009,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
@@ -1757,7 +2029,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
           return buildTitleMarkerBlockedResult({
             input,
             currentHeadSha,
-            draftGateAlreadySatisfied: true,
+            draftGateAlreadySatisfied,
             draftGate,
             preApprovalGate,
             mergeStateStatus,
@@ -1797,13 +2069,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,
@@ -1825,7 +2097,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         lifecycleState: effectiveLifecycleState,
         loopDisposition: loopDisposition ?? DISPOSITION.CLEAN_CONVERGED,
         gateBoundary: PR_CHECKPOINT.PRE_APPROVAL_GATE_WINDOW,
-        draftGateAlreadySatisfied: true,
+        draftGateAlreadySatisfied,
         draftGate,
         preApprovalGate,
         allowedNextActions,
@@ -1852,7 +2124,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,
@@ -1876,7 +2148,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,
@@ -1894,7 +2166,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         return buildTitleMarkerBlockedResult({
           input,
           currentHeadSha,
-          draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+          draftGateAlreadySatisfied,
           draftGate,
           preApprovalGate,
           mergeStateStatus,
@@ -1932,7 +2204,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         lifecycleState: effectiveLifecycleState,
         loopDisposition: DISPOSITION.DONE,
         gateBoundary: PR_CHECKPOINT.FINAL_APPROVAL_READY,
-        draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+        draftGateAlreadySatisfied,
         draftGate,
         preApprovalGate,
         allowedNextActions,