@dev-loops/core 0.6.0 → 0.7.2

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

@@ -1,4 +1,4 @@
-import { DISPOSITION, STATE } from "./copilot-loop-state.mjs";
+import { DISPOSITION, isCopilotRoundCapReached, STATE } from "./copilot-loop-state.mjs";
 import { findBlockingTitleMarkers } from "./pr-title-markers.mjs";
 import { evaluateUiE2eScoping } from "./ui-e2e-scoping.mjs";
 
@@ -238,160 +238,6 @@ function buildRoundExhaustionGateEvidenceNote({ copilotReviewRoundCount, maxCopi
   return `Copilot review rounds exhausted (${copilotReviewRoundCount}/${maxCopilotRounds}); current head has zero unresolved threads and green or credibly green CI, so pre_approval_gate fallback is allowed without another Copilot re-request.`;
 }
 
-/**
- * Render the (user-authored) rawCallViolations array into a bounded, single-line
- * fragment for the gate failure reason. Collapses whitespace/newlines per entry,
- * caps per-entry length, and caps the number of entries shown so a large or
- * garbled checkpoint cannot bloat or break gate output. Still fails closed —
- * this only formats the reason; the violation count above does the gating.
- */
-function summarizeRawCallViolations(violations, { maxEntries = 10, maxEntryLen = 200 } = {}) {
-  const shown = violations.slice(0, maxEntries).map((v) => {
-    const flat = String(v).replace(/\s+/g, " ").trim();
-    return flat.length > maxEntryLen ? `${flat.slice(0, maxEntryLen)}…` : flat;
-  });
-  const more = violations.length - shown.length;
-  return more > 0 ? `${shown.join("; ")}; …(+${more} more)` : shown.join("; ");
-}
-
-function evaluateRetrospectiveMergeApproval(checkpoint, { developerMode = false } = {}) {
-  if (!checkpoint || typeof checkpoint !== "object") {
-    return { approved: false, reason: "No retrospective checkpoint was found." };
-  }
-
-  const state = typeof checkpoint.state === "string" ? checkpoint.state.trim().toLowerCase() : "";
-  if (state !== "complete") {
-    return { approved: false, reason: `Retrospective is not complete (state: ${state || "missing"}).` };
-  }
-
-  // Read merge approval from behavioralReview (existing format) or top-level (future flat format).
-  const br = checkpoint.behavioralReview && typeof checkpoint.behavioralReview === "object"
-    ? checkpoint.behavioralReview
-    : null;
-  const mergeApproved = br !== null ? br.mergeApproved : checkpoint.mergeApproved;
-  if (mergeApproved !== true) {
-    return { approved: false, reason: "Retrospective does not explicitly approve merge (`mergeApproved: true` is required)." };
-  }
-
-  // followedWorkingAgreement: required boolean (existing checkpoint uses behavioralReview.followedWorkingAgreement).
-  const followedWorkingAgreement = br !== null
-    ? br.followedWorkingAgreement
-    : checkpoint.followedWorkingAgreement;
-  if (typeof followedWorkingAgreement !== "boolean") {
-    return { approved: false, reason: "Retrospective is missing `followedWorkingAgreement` (true/false)." };
-  }
-
-  // gateQuality: require gateQualityAcceptable=true AND non-empty notes (behavioralReview)
-  // or explicit gateQuality string (flat format). Avoid empty-notes bypass.
-  const gateQualityAcceptable = br !== null
-    ? br.gateQualityAcceptable
-    : checkpoint.gateQualityAcceptable;
-  if (typeof gateQualityAcceptable !== "boolean" || gateQualityAcceptable !== true) {
-    return { approved: false, reason: `Retrospective gate quality is not explicitly acceptable (gateQualityAcceptable: ${String(gateQualityAcceptable)}).` };
-  }
-  const gateQuality = typeof checkpoint.gateQuality === "string" && checkpoint.gateQuality.trim().length > 0
-    ? checkpoint.gateQuality
-    : null;
-  if (!gateQuality) {
-    return { approved: false, reason: "Retrospective is missing `gateQuality` details; provide a notes field with gate-quality assessment or an explicit gateQuality string." };
-  }
-
-  // unexpectedFindings: derive from behavioralReview.drifts if flat field absent. Empty array is valid (no findings).
-  const unexpectedFindings = typeof checkpoint.unexpectedFindings === "string" && checkpoint.unexpectedFindings.trim().length > 0
-    ? checkpoint.unexpectedFindings
-    : (br !== null && Array.isArray(br.drifts)
-      ? (br.drifts.length > 0 ? br.drifts.join("; ") : "none")
-      : null);
-  if (!unexpectedFindings) {
-    return { approved: false, reason: "Retrospective is missing `unexpectedFindings` details." };
-  }
-
-  // mergeRecommendation: require explicit mergeRecommendation field (string).
-  const mergeRecommendation = typeof checkpoint.mergeRecommendation === "string" && checkpoint.mergeRecommendation.trim().length > 0
-    ? checkpoint.mergeRecommendation
-    : null;
-  if (!mergeRecommendation) {
-    return { approved: false, reason: "Retrospective is missing explicit `mergeRecommendation`." };
-  }
-
-  // internalToolingOnly: the loop's own execution must have used internal dev-loops
-  // tooling only — no agent-level raw `gh`/`python`/`python3`/`node -e` (issue #982).
-  // This is a DEVELOPER-MODE retro step: it enforces the dev-loops maintainers'
-  // own dogfooding discipline and is opt-in via `workflow.requireRetrospectiveInternalTooling`
-  // (default OFF). CONSUMERS of the extension are never blocked by it — they may
-  // legitimately use raw gh/python/node -e in their own workflow — so when the flag
-  // is OFF these fields are neither required nor enforced (a complete checkpoint
-  // without them passes exactly as it did before #982). When ON it fails closed:
-  // a complete checkpoint must explicitly attest a clean tooling record, and an OLD
-  // checkpoint missing `internalToolingOnly` fails (not a silent pass). Re-record the
-  // retrospective with the new fields to clear it.
-  if (developerMode) {
-    const internalToolingOnly = br !== null ? br.internalToolingOnly : checkpoint.internalToolingOnly;
-    if (internalToolingOnly !== true) {
-      return {
-        approved: false,
-        reason: "Retrospective does not attest internal-tooling-only execution (`internalToolingOnly: true` is required in developer mode; agent-level raw gh/python/node -e is a violation). — re-record the retrospective with internalToolingOnly + rawCallViolations.",
-      };
-    }
-    const rawCallViolations = br !== null ? br.rawCallViolations : checkpoint.rawCallViolations;
-    if (!Array.isArray(rawCallViolations)) {
-      return { approved: false, reason: "Retrospective is missing `rawCallViolations` (array; empty when clean). — re-record the retrospective with internalToolingOnly + rawCallViolations." };
-    }
-    if (rawCallViolations.length > 0) {
-      return {
-        approved: false,
-        reason: `Retrospective records ${rawCallViolations.length} raw-call violation(s) (agent-level gh/python/node -e): ${summarizeRawCallViolations(rawCallViolations)}.`,
-      };
-    }
-  }
-
-  return { approved: true, reason: null };
-}
-
-function buildRetrospectiveGatePendingResult({
-  input,
-  currentHeadSha,
-  draftGateAlreadySatisfied,
-  draftGate,
-  preApprovalGate,
-  mergeStateStatus,
-  conflictFiles,
-  reason,
-  refinementArtifact = null,
-}) {
-  const allowedNextActions = [];
-  const forbiddenActions = [];
-  pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
-  pushUnique(forbiddenActions, [
-    PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
-    PR_CHECKPOINT_ACTION.MARK_READY_FOR_REVIEW,
-    PR_CHECKPOINT_ACTION.REQUEST_COPILOT_REVIEW,
-    PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE,
-    PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL,
-    PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY,
-  ]);
-
-  return buildResult({
-    repo: input.repo ?? null,
-    pr: Number.isInteger(input.pr) ? input.pr : null,
-    currentHeadSha,
-    lifecycleState: "retrospective_gate_pending",
-    loopDisposition: DISPOSITION.BLOCKED,
-    gateBoundary: PR_CHECKPOINT.BLOCKED,
-    draftGateAlreadySatisfied,
-    draftGate,
-    preApprovalGate,
-    allowedNextActions,
-    forbiddenActions,
-    nextAction: PR_CHECKPOINT_ACTION.REPORT_BLOCKED,
-    reason,
-    mergeStateStatus,
-    conflictFiles,
-      refinementArtifact,
-  });
-}
-
-
 /**
  * Blocked result for a PR that would otherwise reach final_approval_ready but
  * still carries a merge-blocking marker in its title (issue #842). The title is
@@ -551,6 +397,9 @@ function buildResult({
  *   the current head, including a post-cap head Copilot has not (and will not)
  *   re-review. No further Copilot round is permitted, so the formal-request guard
  *   must not fire — the pre_approval_gate reviews the post-cap head (per #848).
+ * @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 {string} params.gateBoundary - current gate boundary
  * @returns {boolean}
  */
@@ -561,6 +410,7 @@ export function shouldGuardCopilotReviewRequest({
   maxCopilotRounds = null,
   sameHeadCleanConverged = false,
   roundCapCleanFallback = false,
+  postConvergenceSignificantChange = false,
   gateBoundary,
 }) {
   const gateBoundariesRequiringCopilotFormalRequest = new Set([
@@ -593,10 +443,12 @@ export function shouldGuardCopilotReviewRequest({
   //    CI) but Copilot has NOT reviewed THIS head (e.g. a post-cap commit). No further
   //    Copilot round is permitted, so forcing a formal request would dead-end the loop;
   //    the pre_approval_gate reviews the post-cap head instead (per #848).
-  const roundCapReached = maxCopilotRounds !== null
-    && typeof copilotReviewRoundCount === "number"
-    && copilotReviewRoundCount >= maxCopilotRounds;
-  if (roundCapReached && (sameHeadCleanConverged || roundCapCleanFallback)) {
+  const roundCapReached = isCopilotRoundCapReached({ copilotReviewRoundCount, maxCopilotRounds });
+  if (
+    roundCapReached
+    && (sameHeadCleanConverged || roundCapCleanFallback)
+    && !postConvergenceSignificantChange
+  ) {
     return false;
   }
   return true;
@@ -618,6 +470,110 @@ const TITLE_MARKER_GUARDED_BOUNDARIES = Object.freeze([
   PR_CHECKPOINT.FINAL_APPROVAL_READY,
 ]);
 
+/**
+ * Independent gate-ENTRY re-check (issue #1190): even when the caller's
+ * lifecycleState/sameHeadCleanConverged claims a settled Copilot convergence,
+ * an outstanding (`requested`/`already-requested`) Copilot review request on
+ * the CURRENT head is a second, independent "unsettled" signal — not derived
+ * from sameHeadCleanConverged — that must refuse pre_approval_gate /
+ * final-approval entry outright.
+ *
+ * This mirrors the fail-closed predicate that previously only fired at
+ * *verdict-post* time (upsert-checkpoint-verdict.mjs, which refuses to post a
+ * pre_approval_gate verdict while this same evaluator forbids
+ * RUN_PRE_APPROVAL_GATE): asserting it here, at gate *entry*, refuses the
+ * pre-approval fan-out up front instead of only after reviewer tokens have
+ * already been spent.
+ *
+ * Skipped when Copilot review is not required at all — `reviewMode:
+ * "internal_only"` or `maxCopilotRounds: 0` — preserving the existing #613 /
+ * #1210 exemptions (internal-only and light-dispatched-with-disabled-review
+ * PRs never need a Copilot round in the first place).
+ */
+const PRE_APPROVAL_ENTRY_BOUNDARIES = Object.freeze([
+  PR_CHECKPOINT.PRE_APPROVAL_GATE_NEEDED,
+  PR_CHECKPOINT.PRE_APPROVAL_GATE_WINDOW,
+  PR_CHECKPOINT.FINAL_APPROVAL_READY,
+]);
+
+function applyUnsettledCopilotReviewEntryGuard(input, result) {
+  if (!result || typeof result !== "object" || !PRE_APPROVAL_ENTRY_BOUNDARIES.includes(result.gateBoundary)) {
+    return null;
+  }
+  if (input.maxCopilotRounds === 0) {
+    return null;
+  }
+  const reviewMode = typeof input.reviewMode === "string" ? input.reviewMode.trim().toLowerCase() : null;
+  if (reviewMode === "internal_only") {
+    return null;
+  }
+  const copilotReviewRequestStatus = typeof input.copilotReviewRequestStatus === "string"
+    ? input.copilotReviewRequestStatus.trim().toLowerCase()
+    : "none";
+  if (copilotReviewRequestStatus !== "requested" && copilotReviewRequestStatus !== "already-requested") {
+    return null;
+  }
+  // Round-cap exemption (mirrors shouldGuardCopilotReviewRequest, #896/#848):
+  // past the cap a lingering requested/already-requested status is for a review
+  // that can never come (no further round is permitted), so treating it as
+  // "unsettled" here would re-introduce the infinite-wait dead-end the
+  // ROUND_CAP_CLEAN_FALLBACK routing exists to prevent. When the cap is reached
+  // 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() : "";
+  const roundCapCleanFallback = lifecycleState === STATE.ROUND_CAP_CLEAN_FALLBACK;
+  if (
+    roundCapReached
+    && (input.sameHeadCleanConverged === true || roundCapCleanFallback)
+    && input.postConvergenceSignificantChange !== true
+  ) {
+    return null;
+  }
+
+  const allowedNextActions = [];
+  const forbiddenActions = [];
+  pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.WAIT_FOR_COPILOT_REVIEW]);
+  // 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
+  // here would let a draft_gate verdict post on a non-draft PR slip through where
+  // the replaced result would have refused it.
+  pushUnique(forbiddenActions, [
+    PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
+    PR_CHECKPOINT_ACTION.MARK_READY_FOR_REVIEW,
+    PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE,
+    PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL,
+    PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY,
+  ]);
+
+  return buildResult({
+    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,
+    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.",
+    mergeStateStatus: result.mergeStateStatus ?? null,
+    conflictFiles: result.conflictFiles ?? [],
+    refinementArtifact: result.refinementArtifact ?? null,
+    copilotReviewRoundCount: normalizeNonNegativeInteger(input.copilotReviewRoundCount),
+  });
+}
+
 /**
  * Evaluates PR gate coordination, then re-asserts the merge-blocking title guard
  * (issue #842) at the pre-approval / final-approval boundary for non-draft PRs.
@@ -630,6 +586,11 @@ const TITLE_MARKER_GUARDED_BOUNDARIES = Object.freeze([
 export function evaluatePrGateCoordination(input = {}) {
   const result = evaluatePrGateCoordinationCore(input);
 
+  const unsettledReviewResult = applyUnsettledCopilotReviewEntryGuard(input, result);
+  if (unsettledReviewResult) {
+    return unsettledReviewResult;
+  }
+
   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
@@ -683,12 +644,9 @@ function evaluatePrGateCoordinationCore(input = {}) {
   const draftGateRequireCi = input.draftGateRequireCi !== false;
   const copilotReviewRoundCount = normalizeNonNegativeInteger(input.copilotReviewRoundCount);
   const maxCopilotRounds = normalizePositiveInteger(input.maxCopilotRounds);
-  const roundCapReached = maxCopilotRounds !== null && copilotReviewRoundCount >= maxCopilotRounds;
-  const requireRetrospectiveGate = input.requireRetrospectiveGate === true;
-  // Developer-mode flag (#982): only the dev-loops repo dogfooding itself enforces the
-  // internal-tooling-only retro discipline. Default OFF so consumer state changes pass.
-  const requireRetrospectiveInternalTooling = input.requireRetrospectiveInternalTooling === true;
-  const retrospectiveCheckpoint = input.retrospectiveCheckpoint;
+  const roundCapReached = isCopilotRoundCapReached({ copilotReviewRoundCount, maxCopilotRounds });
+  const postConvergenceSignificantChange = input.postConvergenceSignificantChange === true;
+  const roundCapNewCycleRequired = roundCapReached && copilotReviewRoundCount > 0 && postConvergenceSignificantChange;
   const prTitle = typeof input.prTitle === "string" ? input.prTitle : "";
   // UI e2e auto-scoping (#976): the PR changed-file set + whether the shared UI
   // e2e suite passed for this head. Inclusion is path-triggered, never annotated.
@@ -849,7 +807,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
   // registered in the shared UI e2e suite AND that suite must have passed for
   // this head. A rendered-artifact change with no registered/passing coverage
   // blocks here with a reason naming the artifact. Distinct seam from the
-  // mergeability (#980) and retrospective (#982) preconditions to minimize
+  // mergeability (#980) preconditions to minimize
   // merge-time conflict. Non-UI changes pass through untouched (required=false).
   const uiE2eScoping = evaluateUiE2eScoping(changedFiles, { uiE2ePassed });
   if (uiE2eScoping.required && !uiE2eScoping.satisfied) {
@@ -1061,24 +1019,6 @@ function evaluatePrGateCoordinationCore(input = {}) {
             refinementArtifact,
           });
         }
-        if (requireRetrospectiveGate) {
-          const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint, { developerMode: requireRetrospectiveInternalTooling });
-          if (!retrospectiveGate.approved) {
-            return buildRetrospectiveGatePendingResult({
-              input,
-              currentHeadSha,
-              draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
-              draftGate,
-              preApprovalGate,
-              mergeStateStatus,
-              conflictFiles,
-              reason: `Merge remains blocked: retrospective_gate_pending. ${retrospectiveGate.reason}`,
-            refinementArtifact,
-            });
-          }
-        }
-
-
         if (!draftGate.cleanEvidenceExists) {
           return buildDraftGateNeededForMergeResult({
             input,
@@ -1291,11 +1231,11 @@ function evaluatePrGateCoordinationCore(input = {}) {
       });
     }
 
-    const roundExhaustionGateEvidenceNote = roundCapReached
+    const roundExhaustionGateEvidenceNote = (roundCapReached && !roundCapNewCycleRequired)
       ? buildRoundExhaustionGateEvidenceNote({ copilotReviewRoundCount, maxCopilotRounds })
       : null;
 
-    if (!sameHeadCleanConverged && !roundCapReached) {
+    if (!sameHeadCleanConverged && (!roundCapReached || roundCapNewCycleRequired)) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REREQUEST_COPILOT_REVIEW]);
       pushUnique(forbiddenActions, postDraftForbidden);
       return buildResult({
@@ -1311,7 +1251,9 @@ function evaluatePrGateCoordinationCore(input = {}) {
         allowedNextActions,
         forbiddenActions,
         nextAction: PR_CHECKPOINT_ACTION.REREQUEST_COPILOT_REVIEW,
-        reason: "The review loop is between passes, but the current head does not yet have a clean settled Copilot convergence point, so `pre_approval_gate` is still forbidden.",
+        reason: roundCapNewCycleRequired
+          ? "The previous Copilot cycle converged at the round cap, but significant post-convergence changes landed on a newer head; start a new Copilot review cycle and re-request review before `pre_approval_gate`."
+          : "The review loop is between passes, but the current head does not yet have a clean settled Copilot convergence point, so `pre_approval_gate` is still forbidden.",
         mergeStateStatus,
         conflictFiles,
           refinementArtifact,
@@ -1333,23 +1275,6 @@ function evaluatePrGateCoordinationCore(input = {}) {
           refinementArtifact,
         });
       }
-      if (requireRetrospectiveGate) {
-        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint, { developerMode: requireRetrospectiveInternalTooling });
-        if (!retrospectiveGate.approved) {
-          return buildRetrospectiveGatePendingResult({
-            input,
-            currentHeadSha,
-            draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
-            draftGate,
-            preApprovalGate,
-            mergeStateStatus,
-            conflictFiles,
-            reason: `Merge remains blocked: retrospective_gate_pending. ${retrospectiveGate.reason}`,
-          refinementArtifact,
-          });
-        }
-      }
-
 
       if (!draftGate.cleanEvidenceExists && !roundCapReached) {
         return buildDraftGateNeededForMergeResult({
@@ -1438,6 +1363,35 @@ function evaluatePrGateCoordinationCore(input = {}) {
   // blocked states are handled earlier, so genuinely-blocked states still forbid
   // pre_approval. Mirrors LOW_SIGNAL_CONVERGED routing with round-cap reasoning.
   if (effectiveLifecycleState === STATE.ROUND_CAP_CLEAN_FALLBACK) {
+    if (roundCapNewCycleRequired) {
+      pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REREQUEST_COPILOT_REVIEW]);
+      pushUnique(forbiddenActions, [
+        PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
+        PR_CHECKPOINT_ACTION.MARK_READY_FOR_REVIEW,
+        PR_CHECKPOINT_ACTION.REQUEST_COPILOT_REVIEW,
+        PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE,
+        PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY,
+      ]);
+      return buildResult({
+        repo: input.repo ?? null,
+        pr: Number.isInteger(input.pr) ? input.pr : null,
+        currentHeadSha,
+        lifecycleState: STATE.READY_TO_REREQUEST_REVIEW,
+        loopDisposition: DISPOSITION.ACTION_REQUIRED,
+        gateBoundary: PR_CHECKPOINT.POST_DRAFT_EXTERNAL_REVIEW,
+        draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
+        draftGate,
+        preApprovalGate,
+        allowedNextActions,
+        forbiddenActions,
+        nextAction: PR_CHECKPOINT_ACTION.REREQUEST_COPILOT_REVIEW,
+        reason: `The previous Copilot cycle converged at the round cap (${copilotReviewRoundCount}/${maxCopilotRounds}), but significant post-convergence changes landed on the current head. Open a new cycle and re-request Copilot review before entering \`pre_approval_gate\`.`,
+        mergeStateStatus,
+        conflictFiles,
+        refinementArtifact,
+        copilotReviewRoundCount,
+      });
+    }
     if (ciStatus === "failure" || ciStatus === "crediblyGreen") {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
       pushUnique(forbiddenActions, postDraftForbidden);
@@ -1499,23 +1453,6 @@ function evaluatePrGateCoordinationCore(input = {}) {
           refinementArtifact,
         });
       }
-      if (requireRetrospectiveGate) {
-        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint, { developerMode: requireRetrospectiveInternalTooling });
-        if (!retrospectiveGate.approved) {
-          return buildRetrospectiveGatePendingResult({
-            input,
-            currentHeadSha,
-            draftGateAlreadySatisfied: true,
-            draftGate,
-            preApprovalGate,
-            mergeStateStatus,
-            conflictFiles,
-            reason: `Merge remains blocked: retrospective_gate_pending. ${retrospectiveGate.reason}`,
-            refinementArtifact,
-          });
-        }
-      }
-
       // Mirror LOW_SIGNAL_CONVERGED (#579): 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
@@ -1659,23 +1596,6 @@ function evaluatePrGateCoordinationCore(input = {}) {
           refinementArtifact,
         });
       }
-      if (requireRetrospectiveGate) {
-        const retrospectiveGate = evaluateRetrospectiveMergeApproval(retrospectiveCheckpoint, { developerMode: requireRetrospectiveInternalTooling });
-        if (!retrospectiveGate.approved) {
-          return buildRetrospectiveGatePendingResult({
-            input,
-            currentHeadSha,
-            draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
-            draftGate,
-            preApprovalGate,
-            mergeStateStatus,
-            conflictFiles,
-            reason: `Merge remains blocked: retrospective_gate_pending. ${retrospectiveGate.reason}`,
-          refinementArtifact,
-          });
-        }
-      }
-
 
       if (!draftGate.cleanEvidenceExists) {
         return buildDraftGateNeededForMergeResult({

package/src/loop/pr-lifecycle.mjs

@@ -0,0 +1,79 @@
+/**
+ * PR lifecycle: the 13-state vocabulary + required transitions from
+ * skills/docs/pr-lifecycle-contract.md (issue #1193), promoted to a real
+ * exported contract surface.
+ *
+ * This is the single source of truth for the family-local PR lifecycle graph:
+ * both scripts/pages/build-state-atlas.mjs (site diagram generator) and
+ * scripts/docs/validate-state-machine-conformance.mjs (the L2/L3 conformance
+ * harness) import this same table, instead of one importing the other's
+ * module (which would pull the whole page generator — eager mermaid diagram
+ * rendering, duplicate core module instances via relative imports — into the
+ * harness's process at load time).
+ *
+ * Pure data + one derivation, no imports, no side effects.
+ */
+export const PR_LIFECYCLE_STATES = Object.freeze([
+  'draft_local_review_gate',
+  'draft_local_remediation',
+  'ready_state_needs_copilot_request',
+  'waiting_for_copilot_review',
+  'copilot_feedback_remediation',
+  'copilot_reply_resolve_pending',
+  'merge_conflict_resolution',
+  'final_local_preapproval_gate',
+  'final_gate_remediation',
+  'waiting_for_human_pr_approval',
+  'waiting_for_merge',
+  'terminal_slice_complete',
+  'stopped_needs_user_decision',
+]);
+
+// '[*]' is the synthetic terminal-marker target (see build-state-atlas.mjs's
+// renderStateDiagram and validate-state-machine-conformance.mjs's realEdges):
+// a row `[state, '[*]']` marks `state` as absorbing without being a real edge.
+const TERMINAL_MARKER = '[*]';
+
+export const PR_LIFECYCLE_TRANSITIONS = Object.freeze([
+  Object.freeze(['draft_local_review_gate', 'draft_local_remediation']),
+  Object.freeze(['draft_local_review_gate', 'ready_state_needs_copilot_request']),
+  Object.freeze(['draft_local_review_gate', 'stopped_needs_user_decision']),
+  Object.freeze(['draft_local_remediation', 'draft_local_review_gate']),
+  Object.freeze(['ready_state_needs_copilot_request', 'waiting_for_copilot_review']),
+  Object.freeze(['ready_state_needs_copilot_request', 'stopped_needs_user_decision']),
+  Object.freeze(['waiting_for_copilot_review', 'copilot_feedback_remediation']),
+  Object.freeze(['copilot_feedback_remediation', 'copilot_reply_resolve_pending']),
+  Object.freeze(['copilot_reply_resolve_pending', 'ready_state_needs_copilot_request']),
+  Object.freeze(['waiting_for_copilot_review', 'merge_conflict_resolution']),
+  Object.freeze(['merge_conflict_resolution', 'waiting_for_copilot_review']),
+  Object.freeze(['waiting_for_copilot_review', 'final_local_preapproval_gate']),
+  Object.freeze(['final_local_preapproval_gate', 'final_gate_remediation']),
+  Object.freeze(['final_local_preapproval_gate', 'waiting_for_human_pr_approval']),
+  Object.freeze(['final_gate_remediation', 'final_local_preapproval_gate']),
+  Object.freeze(['waiting_for_human_pr_approval', 'waiting_for_merge']),
+  Object.freeze(['waiting_for_human_pr_approval', 'draft_local_review_gate']),
+  Object.freeze(['waiting_for_merge', 'terminal_slice_complete']),
+  Object.freeze(['terminal_slice_complete', TERMINAL_MARKER]),
+  Object.freeze(['stopped_needs_user_decision', TERMINAL_MARKER]),
+]);
+
+// Derived, not hand-listed (lesson from #1157: a hand-copied terminal list can
+// silently drift from the transition table it is supposed to describe). A
+// state is terminal when it has zero real (non-marker) outgoing edges.
+function deriveTerminalStates(states, transitions) {
+  const hasRealOutgoing = new Set(
+    transitions.filter(([, to]) => to !== TERMINAL_MARKER).map(([from]) => from),
+  );
+  return states.filter((state) => !hasRealOutgoing.has(state));
+}
+
+export const PR_LIFECYCLE_TERMINAL_STATES = Object.freeze(deriveTerminalStates(PR_LIFECYCLE_STATES, PR_LIFECYCLE_TRANSITIONS));
+
+// Enum-style access (SCREAMING_SNAKE_CASE key -> the same state string), so
+// handoff scripts can reference `PR_LIFECYCLE_STATE.READY_STATE_NEEDS_COPILOT_REQUEST`
+// instead of hardcoding the literal, mirroring the STATE/OUTER_STATE/REVIEWER_STATE
+// convention used by the other loop state machines. Derived from PR_LIFECYCLE_STATES
+// so a new state cannot be added to one without the other.
+export const PR_LIFECYCLE_STATE = Object.freeze(
+  Object.fromEntries(PR_LIFECYCLE_STATES.map((state) => [state.toUpperCase(), state])),
+);

package/src/loop/public-dev-loop-routing.mjs

@@ -1304,9 +1304,9 @@ export function resolveAuthoritativeStartupResumeBundle(input = {}) {
 }
 
 
-const BUILT_IN_DEFAULT_TARGET_PREFERENCE = DEV_LOOP_TARGET_PREFERENCE.PREFER_GITHUB_FIRST;
+const BUILT_IN_DEFAULT_TARGET_PREFERENCE = DEV_LOOP_TARGET_PREFERENCE.PREFER_LOCAL;
 
-// DEFAULT_TARGET_PREFERENCE uses the built-in default (github-first).
+// DEFAULT_TARGET_PREFERENCE uses the built-in default (local-first).
 // Config-based target preference is resolved by the startup resolver
 // (resolveTargetPreference in scripts/loop/resolve-dev-loop-startup.mjs)
 // and passed explicitly via input.targetPreference.