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

package/src/loop/merge-approval.mjs

@@ -20,7 +20,7 @@
  * precondition, and the aggregate naming.
  */
 
-import { isCopilotLogin, classifyCopilotReviewBodyDisposition, COPILOT_DISPOSITION, SUBMITTED_REVIEW_STATES } from "../github/copilot-helpers.mjs";
+import { isCopilotLogin, classifyCopilotReviewBodyDisposition, COPILOT_DISPOSITION, SUBMITTED_REVIEW_STATES, extractReviewCommitSha } from "../github/copilot-helpers.mjs";
 import { findBlockingTitleMarkers } from "./pr-title-markers.mjs";
 import { resolveSizeBudgetHumanApprovalRequired } from "./size-budget-merge-gate.mjs";
 import { deriveLoopCiStatusFromRollup } from "./copilot-ci-status.mjs";
@@ -84,6 +84,15 @@ function reviewCommit(entry) {
   return null;
 }
 
+// Copilot-only login extraction for evaluateCopilotConvergence: accepts the
+// `gh pr view` GraphQL shape (author.login) in addition to the REST shape
+// (user.login | login) reviewLogin reads. Scoped to the Copilot-convergence
+// eval so verifyFreshHumanApproval's human-approval matching is unchanged.
+function copilotConvergenceReviewLogin(entry) {
+  if (typeof entry?.author?.login === "string" && entry.author.login.length > 0) return entry.author.login;
+  return reviewLogin(entry);
+}
+
 /**
  * Verify a fresh, agent-unforgeable, head-pinned human approval by `approvedBy`.
  *
@@ -153,13 +162,25 @@ export function verifyFreshHumanApproval({ approvedBy, currentHeadSha, reviews =
   };
 }
 
+export const COPILOT_CONVERGENCE_STATE = Object.freeze({
+  CURRENT_HEAD_CLEAN: "current_head_clean",
+  CURRENT_HEAD_FINDINGS: "current_head_findings",
+  NO_CURRENT_HEAD_REVIEW: "no_current_head_review",
+});
+
+/** ADR 0012 end states (amended by ADR 0090) that may satisfy convergence without a current-head review. */
+export const COPILOT_ABSENT_REVIEW_DISPOSITION = Object.freeze({
+  CONVERGED_ONCE: "converged_once",
+  ROUND_CAP_CLEAN_FALLBACK: "round_cap_clean_fallback",
+  DOCS_ONLY_SUPPRESSION: "docs_only_suppression",
+  COPILOT_GATE_DISABLED: "copilot_gate_disabled",
+});
+const SANCTIONED_ABSENT_REVIEW_DISPOSITIONS = new Set(Object.values(COPILOT_ABSENT_REVIEW_DISPOSITION));
+
 /**
- * Copilot-convergence merge precondition. Wires the current-head Copilot
- * body-disposition detection into the merge gate so the merge wrapper
- * and the loop (`copilotBodyFeedbackUnresolved`) read the SAME classification
- * (`classifyCopilotReviewBodyDisposition`). The classification is shared, so it
- * cannot drift; the POLICY differs by design (the loop self-blocks on 🔵, this
- * gate treats 🔵 as conductor-overridable). Fail-closed.
+ * Shared Copilot-convergence evaluation for pre-approval entry and merge.
+ * Both treat a thread-clean 🔵 as conductor-overridable; unresolved threads
+ * still block independently. Fail-closed.
  *
  * Only the LATEST Copilot review pinned to `currentHeadSha` is judged, so a
  * stale non-approval at an earlier head never blocks and a later same-head 🟢
@@ -175,16 +196,28 @@ export function verifyFreshHumanApproval({ approvedBy, currentHeadSha, reviews =
  *      threads — the conductor's override is choosing to run the merge on a
  *      thread-clean 🔵.
  *   unrecognized disposition -> BLOCK (fail closed on a Copilot format change).
- *   🟢 clean / no current-head Copilot review / stale earlier-head -> PASS.
+ *   🟢 clean / headerless -> PASS.
  *
- * @returns {{ ok: boolean, disposition: string|null, reason: string|null }}
+ * Three distinct states (`state` on the result):
+ *   current_head_clean     a current-head review passes (🟢 / headerless / 🔵);
+ *   current_head_findings  a current-head review blocks (🟡 / unrecognized);
+ *   no_current_head_review no current-head Copilot review exists (none yet, or
+ *                          every review is on an earlier head). This state
+ *                          passes ONLY through a sanctioned disposition recorded
+ *                          for the current head (`absentReviewDisposition`
+ *                          `{ kind, headSha }`, kind in
+ *                          COPILOT_ABSENT_REVIEW_DISPOSITION). Absence alone never
+ *                          converges, and a stale earlier-head review is never
+ *                          inherited as the current-head verdict.
+ *
+ * @returns {{ ok: boolean, state: string|null, disposition: string|null, reason: string|null }}
  */
-export function evaluateCopilotConvergence({ currentHeadSha = null, reviews = [] } = {}) {
+export function evaluateCopilotConvergence({ currentHeadSha = null, reviews = [], absentReviewDisposition = null } = {}) {
   const head = typeof currentHeadSha === "string" ? currentHeadSha.trim() : "";
   // Head unknown: no current-head review can be pinned. Fail closed (matches
   // verifyFreshHumanApproval), so this precondition can never pass without a
   // known head to pin the Copilot disposition to.
-  if (head.length === 0) return { ok: false, disposition: null, reason: "current head SHA is unknown; cannot pin a Copilot review to it" };
+  if (head.length === 0) return { ok: false, state: null, disposition: null, reason: "current head SHA is unknown; cannot pin a Copilot review to it" };
 
   // Mirror summarizeCopilotReviews' current-head finding selection BYTE-FOR-BYTE
   // so the merge gate and the loop can never diverge (they already share
@@ -199,36 +232,65 @@ export function evaluateCopilotConvergence({ currentHeadSha = null, reviews = []
   // array order never silently drops a finding.
   let latestDisposition = null;
   let latestAt = null;
+  // The id of the review that owns latestDisposition: the review a
+  // copilot-body-disposition record must name to clear a finding. Null when two
+  // tied reviews both block, so no single record can clear the tie.
+  let latestReviewId = null;
   for (const entry of Array.isArray(reviews) ? reviews : []) {
-    const login = reviewLogin(entry);
+    // Shape-tolerant Copilot-login + commit extraction: the merge gate feeds
+    // REST-shaped reviews (user.login/commit_id) while the gate-ENTRY detector
+    // feeds `gh pr view` GraphQL-shaped reviews (author.login/commit.oid). Both
+    // call sites route through this one evaluateCopilotConvergence, so it must
+    // recognize BOTH shapes to produce ONE convergence verdict. Only Copilot
+    // reviews matter here, so broadening the login read to author.login cannot
+    // affect verifyFreshHumanApproval (which keeps its own REST-only
+    // reviewLogin/reviewCommit).
+    const login = copilotConvergenceReviewLogin(entry);
     if (login === null || !isCopilotLogin(login)) continue;
-    if (reviewCommit(entry) !== head) continue; // only current-head reviews
+    if (extractReviewCommitSha(entry) !== head) continue; // only current-head reviews
     const state = typeof entry?.state === "string" ? entry.state.toUpperCase() : "";
     if (state === "PENDING" || !SUBMITTED_REVIEW_STATES.has(state)) continue; // PENDING/unknown never sets the finding
     const disposition = classifyCopilotReviewBodyDisposition(state, entry?.body);
+    const reviewId = entry?.id !== null && entry?.id !== undefined ? String(entry.id) : null;
     const submittedAt = typeof entry?.submittedAt === "string"
       ? entry.submittedAt
       : (typeof entry?.submitted_at === "string" ? entry.submitted_at : null);
     if (submittedAt !== null && (latestAt === null || submittedAt > latestAt)) {
       latestDisposition = disposition; // a lexicographically-later submittedAt supersedes (matches summarize)
+      latestReviewId = reviewId;
       latestAt = submittedAt;
-    } else if (submittedAt !== null && submittedAt === latestAt) {
-      latestDisposition = latestDisposition === null ? disposition : moreBlockingDisposition(latestDisposition, disposition);
-    } else if (submittedAt === null && latestAt === null) {
-      latestDisposition = latestDisposition === null ? disposition : moreBlockingDisposition(latestDisposition, disposition);
+    } else if (submittedAt === latestAt) {
+      // Equal-string tie, or both null.
+      ({ disposition: latestDisposition, reviewId: latestReviewId } = foldTiedReview(
+        { disposition: latestDisposition, reviewId: latestReviewId },
+        { disposition, reviewId },
+      ));
     }
     // a null submittedAt once a non-null latest exists is ignored (mirrors summarize)
   }
-  if (latestDisposition === null) return { ok: true, disposition: null, reason: null };
+  if (latestDisposition === null) {
+    const absent = COPILOT_CONVERGENCE_STATE.NO_CURRENT_HEAD_REVIEW;
+    const kind = absentReviewDisposition?.kind;
+    if (SANCTIONED_ABSENT_REVIEW_DISPOSITIONS.has(kind) && absentReviewDisposition?.headSha === head) {
+      return { ok: true, state: absent, disposition: kind, reason: null };
+    }
+    return {
+      ok: false,
+      state: absent,
+      disposition: null,
+      reason: `no current-head Copilot review exists on head ${head}; convergence requires a clean current-head review or a sanctioned disposition recorded for this head (${[...SANCTIONED_ABSENT_REVIEW_DISPOSITIONS].join(", ")})`,
+    };
+  }
 
+  const findings = COPILOT_CONVERGENCE_STATE.CURRENT_HEAD_FINDINGS;
   if (latestDisposition === COPILOT_DISPOSITION.CHANGES_RECOMMENDED) {
-    return { ok: false, disposition: latestDisposition, reason: `current-head Copilot review is "Changes recommended" (🟡, actionable non-approval); converge to "Approval recommended" (🟢) or resolve the feedback before merge` };
+    return { ok: false, state: findings, disposition: latestDisposition, reviewId: latestReviewId, reason: `current-head Copilot review is "Changes recommended" (🟡, actionable non-approval); converge to "Approval recommended" (🟢) or resolve the feedback before merge` };
   }
   if (latestDisposition === COPILOT_DISPOSITION.UNRECOGNIZED) {
-    return { ok: false, disposition: latestDisposition, reason: `current-head Copilot review carries an unrecognized disposition header (fail closed); a recognized "Approval recommended" (🟢) is required` };
+    return { ok: false, state: findings, disposition: latestDisposition, reviewId: latestReviewId, reason: `current-head Copilot review carries an unrecognized disposition header (fail closed); a recognized "Approval recommended" (🟢) is required` };
   }
   // CLEAN, NONE, and NEEDS_CLOSER_LOOK (🔵, conductor-overridable) pass.
-  return { ok: true, disposition: latestDisposition, reason: null };
+  return { ok: true, state: COPILOT_CONVERGENCE_STATE.CURRENT_HEAD_CLEAN, disposition: latestDisposition, reviewId: latestReviewId, reason: null };
 }
 
 // Disposition blocking precedence, most-blocking first. Used to fold an
@@ -250,6 +312,19 @@ function moreBlockingDisposition(a, b) {
   return ra <= rb ? a : b;
 }
 
+// Fold one tied current-head review into the running latest. The disposition
+// folds toward the most blocking. The owning review id follows the blocking
+// review; two tied blocking reviews leave no single owner (null).
+const BLOCKING_CONVERGENCE_DISPOSITIONS = new Set([COPILOT_DISPOSITION.CHANGES_RECOMMENDED, COPILOT_DISPOSITION.UNRECOGNIZED]);
+function foldTiedReview(latest, next) {
+  if (latest.disposition === null) return next;
+  if (BLOCKING_CONVERGENCE_DISPOSITIONS.has(latest.disposition) && BLOCKING_CONVERGENCE_DISPOSITIONS.has(next.disposition)) {
+    return { disposition: moreBlockingDisposition(latest.disposition, next.disposition), reviewId: null };
+  }
+  const disposition = moreBlockingDisposition(latest.disposition, next.disposition);
+  return { disposition, reviewId: disposition === latest.disposition ? latest.reviewId : next.reviewId };
+}
+
 /**
  * Decide whether merge is authorized given the class, the standing
  * authorization signal, and any fresh per-merge approval.
@@ -327,6 +402,12 @@ export function evaluateMergePreconditions({
   comments = [],
   standingAuthorized = false,
   stableRelease = false,
+  copilotAbsentReviewDisposition = null,
+  copilotBodyDisposition = null,
+  // Refusal reason when a Copilot review submitted after the current-head
+  // verdict review sits on an earlier commit and is not converged (the latest
+  // review decides); null otherwise.
+  copilotLaterReviewRefusal = null,
 } = {}) {
   const failures = [];
 
@@ -375,9 +456,21 @@ export function evaluateMergePreconditions({
 
   // Copilot-convergence precondition: refuse a current-head Copilot non-approval
   // body disposition, mirroring the loop's copilotBodyFeedbackUnresolved.
-  const copilotConvergence = evaluateCopilotConvergence({ currentHeadSha, reviews });
-  if (!copilotConvergence.ok) {
+  // A trusted copilot-body-disposition record resolved for the current head
+  // (`{ headSha, reviewId, ... }`) clears a current-head finding, as it does
+  // at gate entry, only when it names the review that raised the finding.
+  const copilotConvergence = evaluateCopilotConvergence({ currentHeadSha, reviews, absentReviewDisposition: copilotAbsentReviewDisposition });
+  const head = typeof currentHeadSha === "string" ? currentHeadSha.trim().toLowerCase() : "";
+  const bodyCleared = copilotConvergence.state === COPILOT_CONVERGENCE_STATE.CURRENT_HEAD_FINDINGS
+    && head.length > 0
+    && typeof copilotBodyDisposition?.headSha === "string" && copilotBodyDisposition.headSha.toLowerCase() === head
+    // The record clears only the review that raised the current-head finding.
+    && copilotConvergence.reviewId !== null
+    && String(copilotBodyDisposition.reviewId) === copilotConvergence.reviewId;
+  if (!copilotConvergence.ok && !bodyCleared) {
     failures.push({ precondition: "copilot_convergence", reason: copilotConvergence.reason });
+  } else if (typeof copilotLaterReviewRefusal === "string") {
+    failures.push({ precondition: "copilot_convergence", reason: copilotLaterReviewRefusal });
   }
 
   const mergeClass = resolveMergeClass({ sizeOutcome, touchesT1, stableRelease });
@@ -391,9 +484,12 @@ export function evaluateMergePreconditions({
     failures,
     mergeClass,
     approvalVia: decision.authorized ? decision.via : null,
-    // Audit trace: the current-head Copilot disposition this verdict saw, so a
-    // merge that ran on a conductor-overridable 🔵 (or any disposition) is
-    // recorded on the machine-readable result rather than being invisible.
+    // Audit trace: which convergence state applied and what settled it (the
+    // current-head review disposition, or the sanctioned disposition kind when
+    // no current-head review exists), so a merge on a conductor-overridable 🔵
+    // or without a current-head review is recorded, never invisible.
+    copilotConvergenceState: copilotConvergence.state,
     copilotDisposition: copilotConvergence.disposition,
+    copilotBodyDisposition: bodyCleared ? copilotBodyDisposition : null,
   };
 }