@dev-loops/core 1.0.0-rc.2 → 1.0.0-rc.4

package/src/loop/handoff-envelope.mjs

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

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

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

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

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

package/src/loop/pr-title-markers.mjs

@@ -12,30 +12,91 @@
  * It is intentionally pure and side-effect free.
  */
 
+/**
+ * Builds a status-marker tester for a bare word like "WIP" or "DRAFT".
+ *
+ * A status marker asserts, on its own, that the PR is unfinished: bracketed
+ * (`[WIP]`), parenthesized (`(draft)`), colon-suffixed (`WIP:`), or the
+ * entire title with nothing else attached (a bare standalone `DRAFT`). A
+ * plain `\bWORD\b` match also hits the same word inside a compound noun
+ * phrase that names a component instead — `draft-gate`, `draft gate`,
+ * `wip-branch` — because a hyphen or a space is itself a word boundary. An
+ * underscore is a word character, so `draft_gate` never matched `\bDRAFT\b`
+ * to begin with; it is listed among the exempt forms for consistency, not
+ * because it was ever flagged. None of those forms satisfy any construction
+ * below, so a component name is left unflagged while a real status claim
+ * still is. "swipe"/"wiped"/"drafting" already fail every construction
+ * because there is no boundary between the marker word and the letters that
+ * follow it; a hyphen-prefixed compound like "re-draft" DOES create such a
+ * boundary (`\b` sees the hyphen).
+ *
+ * A trailing tag set off by a dash (`Fix login flow — WIP`) is deliberately
+ * NOT its own construction, even though it reads as a real status claim.
+ * Any dash-based construction narrow enough to close a title's tag also
+ * reopens the compound-noun false positive whenever the joiner is a
+ * different dash character (`Handle en dash–draft–gate naming`), and any fix
+ * for that narrows the construction until it drops real status claims that
+ * were previously caught (`Fix login flow — WIP.`, `— WIP (rebasing)`). The
+ * bracket/paren/colon/standalone set stays free of both failure modes, so a
+ * dash-set-off marker is left unflagged; `WIP:`/`DRAFT:` remains one
+ * keystroke away and stays flagged, the same trade already accepted for
+ * `WIP foo bar`.
+ *
+ * The bracket/paren/colon constructions all require the opening delimiter
+ * (`[`, `(`, or the marker word itself for colon) to sit at the start of the
+ * title or after whitespace — never directly after a letter, `/`, or `-` —
+ * so a conventional-commit scope (`fix(draft): support x`), a path segment
+ * (`app/[draft]/page.tsx`), a scoped label (`feat/draft: x`, `docs/wip:
+ * notes`), and a hyphen-prefixed compound (`re-draft: cleanup`) are all read
+ * as a component name, not a status claim — the same anchoring rule as the
+ * hyphen/underscore/space compound-noun exemption above. This does introduce
+ * one accepted false-negative class: a marker preceded by punctuation other
+ * than whitespace with no space of its own, e.g. `Fix bug,(draft)` or `Fix
+ * login(wip)`. Widening the anchor to "start, whitespace, or punctuation"
+ * would also re-admit the very forms (`/`, `-`) the anchor exists to
+ * exclude, so the narrower, whitespace-only anchor is kept and this
+ * false-negative class is accepted as its cost.
+ *
+ * The colon construction additionally requires the colon itself to CLOSE the
+ * tag — followed by whitespace or the end of the title, never directly by
+ * another character — so a scheme/tag/ref that merely starts with the
+ * marker word (`draft://`, `draft:latest`, `wip:branch`) is read as an
+ * unrelated identifier, not a status claim.
+ */
+function statusMarkerTester(word) {
+  const bracket = new RegExp(`(?:^|\\s)\\[\\s*${word}\\s*\\]`, "i");
+  const paren = new RegExp(`(?:^|\\s)\\(\\s*${word}\\s*\\)`, "i");
+  const colon = new RegExp(`(?:^|\\s)${word}\\s*:(?:\\s|$)`, "i");
+  const standalone = new RegExp(`^\\s*${word}\\s*$`, "i");
+  return (title) => bracket.test(title) || paren.test(title) || colon.test(title)
+    || standalone.test(title);
+}
+
 /**
  * Canonical merge-blocking markers and how to detect them.
  *
- * Word-boundary matching is used for the alphabetic markers so that real words
- * are not false-positives (e.g. "swipe"/"wiped" must not match WIP;
- * "drafting"/"redraft" must not match DRAFT). Bracket/paren/colon punctuation
- * (`[WIP]`, `(wip)`, `WIP:`) are non-word characters, so `\b` boundaries still
- * match those variants. The construction emoji has no word boundary, so it is
- * matched literally anywhere in the title.
+ * "DO NOT MERGE" is a three-word phrase with no plausible compound-noun
+ * reading, so it keeps simple word-boundary matching. The construction emoji
+ * has no word boundary at all, so it is matched literally anywhere in the
+ * title.
  */
 const MARKER_MATCHERS = [
-  { label: "WIP", pattern: /\bWIP\b/i },
-  { label: "DRAFT", pattern: /\bDRAFT\b/i },
+  { label: "WIP", test: statusMarkerTester("WIP") },
+  { label: "DRAFT", test: statusMarkerTester("DRAFT") },
   // Flexible (any) whitespace between the phrase words, case-insensitive.
-  { label: "DO NOT MERGE", pattern: /\bDO\s+NOT\s+MERGE\b/i },
-  { label: "🚧", pattern: /🚧/u },
+  { label: "DO NOT MERGE", test: (title) => /\bDO\s+NOT\s+MERGE\b/i.test(title) },
+  { label: "🚧", test: (title) => /🚧/u.test(title) },
 ];
 
 /**
  * Finds merge-blocking markers in a PR title.
  *
- * Returns the canonical labels of every matched marker, de-duped and in a
- * stable order (the declaration order of {@link MARKER_MATCHERS}). Returns an
- * empty array when the title is clean, empty, or not a string.
+ * Returns the canonical labels of every matched marker, in a stable order
+ * (the declaration order of {@link MARKER_MATCHERS}). Each label can appear
+ * at most once: MARKER_MATCHERS visits each entry exactly once and every
+ * entry's label is distinct, so the result is de-duped by construction —
+ * there is no separate dedupe step to fail. Returns an empty array when the
+ * title is clean, empty, or not a string.
  *
  * @param {unknown} title - The PR title to inspect.
  * @returns {string[]} Canonical labels of matched markers, e.g. ["WIP"] or
@@ -47,8 +108,8 @@ export function findBlockingTitleMarkers(title) {
   }
 
   const matched = [];
-  for (const { label, pattern } of MARKER_MATCHERS) {
-    if (pattern.test(title) && !matched.includes(label)) {
+  for (const { label, test } of MARKER_MATCHERS) {
+    if (test(title)) {
       matched.push(label);
     }
   }