@dev-loops/core 0.5.0 → 0.7.1

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

@@ -1,11 +1,13 @@
-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";
 
 export const PR_CHECKPOINT = Object.freeze({
   DRAFT_REVIEW: "draft_review",
   POST_DRAFT_EXTERNAL_REVIEW: "post_draft_external_review",
   FEEDBACK_RESOLUTION: "feedback_resolution",
   CONFLICT_RESOLUTION: "conflict_resolution",
+  UI_E2E_SCOPING: "ui_e2e_scoping",
   PRE_APPROVAL_GATE_WINDOW: "pre_approval_gate_window",
   FINAL_APPROVAL_READY: "final_approval_ready",
   PRE_APPROVAL_GATE_NEEDED: "pre_approval_gate_needed",
@@ -48,6 +50,7 @@ export const PR_CHECKPOINT_ACTION = Object.freeze({
   RECONCILE_DRAFT_GATE: "reconcile_draft_gate",
   REPORT_BLOCKED: "report_blocked",
   REPORT_DONE: "report_done",
+  RUN_UI_E2E_SUITE: "run_ui_e2e_suite",
 });
 
 function normalizeGateComment(summary = null) {
@@ -235,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
@@ -548,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}
  */
@@ -558,6 +410,7 @@ export function shouldGuardCopilotReviewRequest({
   maxCopilotRounds = null,
   sameHeadCleanConverged = false,
   roundCapCleanFallback = false,
+  postConvergenceSignificantChange = false,
   gateBoundary,
 }) {
   const gateBoundariesRequiringCopilotFormalRequest = new Set([
@@ -590,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;
@@ -680,13 +535,14 @@ 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.
+  const changedFiles = Array.isArray(input.changedFiles) ? input.changedFiles : [];
+  const uiE2ePassed = input.uiE2ePassed === true ? true : (input.uiE2ePassed === false ? false : null);
   const refinementArtifact = input.refinementArtifact && typeof input.refinementArtifact === "object"
     ? input.refinementArtifact
     : null;
@@ -836,6 +692,45 @@ function evaluatePrGateCoordinationCore(input = {}) {
     });
   }
 
+  // UI e2e auto-scoping precondition (#976). Path-triggered + fail-closed:
+  // if the PR's changed files touch a rendered artifact (a deck under
+  // docs/articles|presentations, or the inspect-run viewer source), it MUST be
+  // 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) preconditions to minimize
+  // merge-time conflict. Non-UI changes pass through untouched (required=false).
+  const uiE2eScoping = evaluateUiE2eScoping(changedFiles, { uiE2ePassed });
+  if (uiE2eScoping.required && !uiE2eScoping.satisfied) {
+    pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.RUN_UI_E2E_SUITE]);
+    pushUnique(forbiddenActions, [
+      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: effectiveLifecycleState,
+      loopDisposition: DISPOSITION.ACTION_REQUIRED,
+      gateBoundary: PR_CHECKPOINT.UI_E2E_SCOPING,
+      draftGateAlreadySatisfied,
+      draftGate,
+      preApprovalGate,
+      allowedNextActions,
+      forbiddenActions,
+      nextAction: PR_CHECKPOINT_ACTION.RUN_UI_E2E_SUITE,
+      reason: uiE2eScoping.reason,
+      mergeStateStatus,
+      conflictFiles,
+      refinementArtifact,
+      copilotReviewRoundCount,
+    });
+  }
+
   if (prDraft || effectiveLifecycleState === STATE.PR_DRAFT) {
     if (refinementArtifactStatus === REFINEMENT_ARTIFACT_STATUS.MISSING) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
@@ -1015,24 +910,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,
@@ -1245,11 +1122,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({
@@ -1265,7 +1142,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,
@@ -1287,23 +1166,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({
@@ -1392,6 +1254,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);
@@ -1453,23 +1344,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
@@ -1613,23 +1487,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/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.

package/src/loop/queue-board-ordering.mjs

@@ -1,6 +1,35 @@
-import { loadBoardConfig, resolveProjectNumber } from "./queue-board-sync.mjs";
+import { loadBoardConfig, resolveProjectNumber, loadStateColumnMap, LOGICAL_COLUMN } from "./queue-board-sync.mjs";
 import { main as listQueueItemsMain } from "../../../../scripts/projects/list-queue-items.mjs";
 
+// Canonical fail-closed Next Up tokens — the SINGLE source of truth so the reason
+// codes and the empty-queue message stay byte-identical across every layer that
+// detects them (queue-driver, run-queue, resolve-active-board-item). These strings
+// drifted twice before centralization (#1091); import them, never re-inline them.
+export const REASON_NEXT_UP_EMPTY = "next-up-empty";
+export const REASON_BOARD_QUERY_ERROR = "board-query-error";
+export const REASON_NEXT_UP_TARGET_MISSING_LOCALLY = "next-up-target-missing-locally";
+export const EMPTY_NEXT_UP_MESSAGE = "queue empty — prioritize Backlog items into Next Up";
+
+/**
+ * Resolve the board's "Next Up" pickup order (issue #1091).
+ *
+ * Next Up is the NORMATIVE, fail-closed pickup source. This resolver reports
+ * enough to let the driver distinguish three cases cleanly (it never silently
+ * collapses them):
+ *
+ *   - Board NOT configured → `{ ok:true, configured:false, order:[] }`. The
+ *     Next Up concept does not exist; the driver keeps its legacy local order.
+ *   - Board configured, Next Up query SUCCEEDS → `{ ok:true, configured:true,
+ *     order:[…], reason:null }`. `order` may be empty (a genuinely empty Next
+ *     Up → the driver fails closed / idles, it MUST NOT fall back to Backlog).
+ *   - Board configured, query ERRORS (unreachable / project unresolvable / API
+ *     failure) → `{ ok:false, configured:true, order:[], reason:<msg> }`. The
+ *     driver surfaces the error and stops; it MUST NOT fall back to Backlog.
+ *
+ * `order` and `reason` are always present so the fail-open membership layer
+ * (queue-membership.mjs), which predates the `ok`/`configured` fields, keeps
+ * working unchanged (it reads `order`/`reason` only).
+ */
 export async function resolveNextUpOrder(
   repo,
   repoRoot,
@@ -9,19 +38,32 @@ export async function resolveNextUpOrder(
 ) {
   const config = loadBoardConfig(repoRoot);
   if (!config.enabled) {
-    return { ok: true, order: [], reason: config.reason ?? "board not configured" };
+    return { ok: true, configured: false, order: [], reason: config.reason ?? "board not configured" };
   }
 
   let projectNumber;
   try {
     projectNumber = await resolveProjectNumber(repo, config, env, dependencies.runChild);
   } catch (err) {
-    return { ok: true, order: [], reason: err.message ?? "board lookup failed" };
+    // Board IS configured but we cannot resolve/reach it: this is a query ERROR,
+    // not an empty Next Up. Fail closed at the driver, never Backlog fallback.
+    return { ok: false, configured: true, order: [], reason: err.message ?? "board lookup failed" };
   }
   if (!projectNumber) {
-    return { ok: true, order: [], reason: "could not resolve board project" };
+    return { ok: false, configured: true, order: [], reason: "could not resolve board project" };
   }
 
+  // Resolve the logical next_up column through the SAME statusColumns mapping
+  // board-sync uses (#1098), so a renamed Next Up column (e.g. "Todo") is
+  // queried by its configured display name instead of the literal default.
+  // No config-error guard here: loadBoardConfig above already short-circuits any
+  // `.devloops` read/parse error to `enabled:false` (early return at the top of
+  // this function), so a malformed config never reaches this point. The
+  // fail-closed-on-config-error guard lives on the direct-read pickup path
+  // (resolve-active-board-item), which does NOT go through loadBoardConfig.
+  const { columnNames } = loadStateColumnMap(repoRoot);
+  const nextUpColumn = columnNames[LOGICAL_COLUMN.NEXT_UP];
+
   const listItems = dependencies.listQueueItems ?? listQueueItemsMain;
   try {
     const result = await listItems(
@@ -29,14 +71,16 @@ export async function resolveNextUpOrder(
       // resolveProjectNumber yields a number, so stringify it. Passing the raw
       // number trips parseProjectRef's `typeof raw !== "string"` guard, which
       // surfaces as a misleading "--project is required" (#901).
-      { repo, project: String(projectNumber), column: "Next Up" },
+      { repo, project: String(projectNumber), column: nextUpColumn },
       { env, runChild: dependencies.runChild },
     );
     const order = (result?.items ?? [])
       .map((it) => it.issueNumber ?? it.prNumber)
       .filter((n) => typeof n === "number");
-    return { ok: true, order, reason: null };
+    // Successful query — order may be empty (genuinely empty Next Up).
+    return { ok: true, configured: true, order, reason: null };
   } catch (err) {
-    return { ok: true, order: [], reason: err.message ?? "Next Up query failed" };
+    // Query ERROR — surface it; the driver stops and never falls back.
+    return { ok: false, configured: true, order: [], reason: err.message ?? "Next Up query failed" };
   }
 }

package/src/loop/queue-board-sync.mjs

@@ -107,6 +107,61 @@ export function boardColumnForLoopState(loopState, mapping = {}) {
   return columnNames[logical] ?? columnNames[DEFAULT_LOGICAL_COLUMN];
 }
 
+/**
+ * Derive the board's target LOGICAL column for a queue item from live GitHub
+ * facts (#1069). Returns LOGICAL_COLUMN.DONE, LOGICAL_COLUMN.IN_PROGRESS, or
+ * null when the item should be left where it is (Backlog/Next Up untouched).
+ *
+ * facts: {
+ *   itemKind: "issue" | "pr",
+ *   issueState: "OPEN" | "CLOSED" | null,   // for issue items
+ *   prState:    "OPEN" | "CLOSED" | "MERGED" | null, // item PR, or the issue's linked PR
+ *   prIsDraft:  boolean | null,
+ * }
+ */
+export function deriveReconcileColumn(facts = {}) {
+  const { itemKind, issueState, prState, prIsDraft } = facts;
+  // Merged PR (item is a PR, or issue's linked PR merged) => Done.
+  if (prState === "MERGED") return LOGICAL_COLUMN.DONE;
+  if (itemKind === "issue" && issueState === "CLOSED") return LOGICAL_COLUMN.DONE;
+  // Open, ready (non-draft) PR => In Progress.
+  if (prState === "OPEN" && prIsDraft === false) return LOGICAL_COLUMN.IN_PROGRESS;
+  // Otherwise leave the item untouched (Backlog / Next Up ordering preserved).
+  return null;
+}
+
+/**
+ * Pure reconcile planner (#1069). Given listed board items, a map of live facts
+ * keyed by the item's stable GraphQL node id (`item.itemId`), and the resolved
+ * column display names, return the set of moves needed to converge the board and
+ * a count of items left unchanged. Idempotent: when every item already sits in
+ * its derived column, the moves array is empty.
+ *
+ * Keying by the stable `itemId` (not the bare issue/PR number) keeps reconcile
+ * deterministic on a multi-repo GitHub Projects board, where two items can share
+ * a number (repo-A PR #5 vs repo-B issue #5) — number-keying would collide and
+ * make moves order-dependent.
+ *
+ * items: [{ itemId, issueNumber, prNumber, status, ... }]  (from list-queue-items)
+ * factsByItemId: Map<itemId, factsObject>   (facts as consumed by deriveReconcileColumn)
+ * columnNames: { in_progress, done, ... }   (LOGICAL_COLUMN -> display name)
+ */
+export function planReconcile(items = [], factsByItemId = new Map(), columnNames = {}) {
+  const moves = [];
+  let unchanged = 0;
+  for (const item of items) {
+    const facts = factsByItemId.get(item.itemId);
+    const logical = facts ? deriveReconcileColumn(facts) : null;
+    if (logical == null) { unchanged += 1; continue; }
+    const target = columnNames[logical];
+    if (!target || item.status === target) { unchanged += 1; continue; }
+    // `number` is kept only for reporting; the move is applied by node id.
+    const number = item.prNumber != null ? item.prNumber : item.issueNumber;
+    moves.push({ itemId: item.itemId, number, from: item.status ?? null, to: target });
+  }
+  return { moves, unchanged };
+}
+
 // ── Local config loader ─────────────────────────────────────────────────
 
 function readDevloopsSettings(repoRoot) {
@@ -169,7 +224,7 @@ export function loadBoardConfig(repoRoot) {
  *     cannot pollute Object.prototype.
  */
 export function loadStateColumnMap(repoRoot) {
-  const { settings: queue } = readDevloopsSettings(repoRoot);
+  const { settings: queue, error } = readDevloopsSettings(repoRoot);
   // Null-prototype objects: untrusted keys can never reach Object.prototype.
   const columnNames = Object.assign(Object.create(null), DEFAULT_STATE_COLUMN_NAMES);
   const stateColumnMap = Object.create(null);
@@ -200,7 +255,11 @@ export function loadStateColumnMap(repoRoot) {
     }
   }
 
-  return { columnNames, stateColumnMap };
+  // Surface a non-ENOENT read/parse error (mirrors loadBoardConfig). Callers on
+  // the fail-closed next_up pickup path MUST honor it rather than silently
+  // querying the default literal column against a stale/renamed board (#1098).
+  // Existing `.columnNames`-only callers ignore this field and behave unchanged.
+  return { columnNames, stateColumnMap, error: error ?? null };
 }
 
 // ── Minimal project lookup (read-only, no create/repair) ────────────────