@dev-loops/core 0.6.0 → 0.7.2

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

@@ -1,6 +1,35 @@
-import { loadBoardConfig, resolveProjectNumber } from "./queue-board-sync.mjs";
-import { main as listQueueItemsMain } from "../../../../scripts/projects/list-queue-items.mjs";
+import { loadBoardConfig, resolveProjectNumber, loadStateColumnMap, LOGICAL_COLUMN } from "./queue-board-sync.mjs";
+import { main as listQueueItemsMain } from "../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

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { runChild as coreRunChild } from "../cli/primitives.mjs";
-import { main as moveQueueItemMain } from "../../../../scripts/projects/move-queue-item.mjs";
+import { main as moveQueueItemMain } from "../projects/move-queue-item.mjs";
 
 const DEFAULT_NON_SUCCESS_COLUMN = "Backlog";
 
@@ -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) ────────────────

package/src/loop/queue-driver.mjs

@@ -9,6 +9,7 @@ import {
   transitionEntry,
   snapshotEntry,
   nextReadyEntry,
+  findEntry,
   allDone,
   RECOVERABLE_FAILURES,
   appendBugIssue,
@@ -19,7 +20,13 @@ import {
   boardColumnForLoopState,
   loadStateColumnMap,
 } from "./queue-board-sync.mjs";
-import { resolveNextUpOrder } from "./queue-board-ordering.mjs";
+import {
+  resolveNextUpOrder,
+  REASON_NEXT_UP_EMPTY,
+  REASON_BOARD_QUERY_ERROR,
+  REASON_NEXT_UP_TARGET_MISSING_LOCALLY,
+  EMPTY_NEXT_UP_MESSAGE,
+} from "./queue-board-ordering.mjs";
 
 export const DEFAULT_QUEUE_DRIVER_OPTIONS = {
   mergeAuthorized: false,
@@ -92,23 +99,88 @@ export async function runQueue(repoRoot, repo, options = {}) {
   // (e.g. a configured "Ready for Review") still syncs. (#793 round-1 #1)
   const lastSyncedColumn = new Map();
 
-  // Optional board-aware ordering: fetch Next Up order before processing.
-  // Fail-open: if the board is unreachable, orderHint stays empty and the
-  // driver falls back to the existing queue order.
-  const ordering = opts.useBoardOrdering !== false && !allDone(queue)
+  // Next Up is the NORMATIVE, fail-closed pickup source (#1091). When a board is
+  // configured, the driver picks ONLY entries whose target is in Next Up, by
+  // POSITION ascending; entries absent from Next Up are never auto-picked. It
+  // NEVER falls back to Backlog or to the non-board local queue order.
+  //
+  // Single-issue/PR runs do not reach this gating at all — they run via the
+  // dev-loop routing path, not the queue driver — so an explicit --issue/--pr
+  // target is inherently unaffected by Next Up.
+  const ordering = !allDone(queue)
     ? await resolveNextUpOrder(repo, repoRoot, opts.env ?? process.env, opts.queueBoardSyncDependencies ?? {})
-    : { ok: true, order: [], reason: "board ordering disabled or queue idle" };
-  const orderHint = ordering.ok ? ordering.order : [];
+    : { ok: true, configured: false, order: [], reason: "queue idle" };
+
+  // (b) Board-query ERROR → surface it and stop. Do NOT fall back to Backlog
+  // or local order (fail-closed). Distinct from an empty Next Up below.
+  if (ordering.ok === false) {
+    return {
+      ok: false,
+      stopped: true,
+      reason: REASON_BOARD_QUERY_ERROR,
+      message: `Next Up query failed (${ordering.reason}); refusing to fall back to Backlog/local order`,
+      error: ordering.reason ?? "board query failed",
+      results: [],
+      queue,
+      ordering,
+    };
+  }
+
+  // Board-gated only when a board is configured.
+  const boardGated = ordering.configured === true;
+  const orderHint = ordering.order;
+  const allowedTargets = boardGated ? new Set(orderHint) : null;
+
+  // (a) Empty Next Up (successful query, zero items) → fail CLOSED: idle/stop
+  // with an actionable, machine-readable outcome. Never pull from Backlog.
+  if (boardGated && orderHint.length === 0) {
+    return {
+      ok: true,
+      idle: true,
+      reason: REASON_NEXT_UP_EMPTY,
+      message: EMPTY_NEXT_UP_MESSAGE,
+      results: [],
+      queue,
+      ordering,
+    };
+  }
+
+  // (a2) Next Up resolved one or more targets that have NO matching local queue
+  // entry (membership reconcile not run/persisted, or the board changed between
+  // reconcile and this query). Filtering them out would return a silent empty
+  // idle while real Next Up work goes undispatched — so fail CLOSED with an
+  // actionable stop instead. Distinct from the genuine empty-Next-Up idle above.
+  // Never pull from Backlog. (#1091)
+  if (boardGated) {
+    const missingTargets = orderHint.filter((t) => !findEntry(queue, t));
+    if (missingTargets.length > 0) {
+      return {
+        ok: false,
+        stopped: true,
+        reason: REASON_NEXT_UP_TARGET_MISSING_LOCALLY,
+        missingTargets,
+        message:
+          "Next Up contains items with no local queue entry — run membership reconcile / re-add them",
+        results: [],
+        queue,
+        ordering,
+      };
+    }
+  }
 
   let autoFiledCount = 0;
   const results = [];
   let incomplete = false;
 
   while (!allDone(queue)) {
-    const entry = nextReadyEntry(queue, opts.reDispatchMaxRetries, orderHint);
+    const entry = nextReadyEntry(queue, opts.reDispatchMaxRetries, orderHint, allowedTargets);
     if (!entry) {
+      // When board-gated, entries absent from Next Up are intentionally NOT
+      // picked (and are not "blocked by deps") — only unfinished Next Up members
+      // count toward an incomplete verdict.
       const remaining = queue.entries.filter(
         (e) => e.status !== "done" && e.status !== "blocked" && e.status !== "failed"
+             && (!allowedTargets || allowedTargets.has(e.target))
       );
       if (remaining.length > 0) {
         incomplete = true;

package/src/loop/queue-state.mjs

@@ -183,9 +183,20 @@ function applyOrderHint(ordered, orderHint) {
   return [...inHint, ...rest];
 }
 
-export function nextReadyEntry(queue, maxRetries = 1, orderHint = []) {
+/**
+ * Pick the next ready entry.
+ *
+ * @param {object} queue
+ * @param {number} maxRetries
+ * @param {number[]} orderHint - preferred order (targets sorted to the front).
+ * @param {Set<number>|null} allowedTargets - when non-null, ONLY entries whose
+ *   target is in this set are eligible. Used for board-gated (Next Up)
+ *   selection (#1091): entries absent from Next Up are never auto-picked.
+ */
+export function nextReadyEntry(queue, maxRetries = 1, orderHint = [], allowedTargets = null) {
   const ordered = topologicalOrder(queue.entries);
-  const sorted = applyOrderHint(ordered, orderHint);
+  const restricted = allowedTargets ? ordered.filter((e) => allowedTargets.has(e.target)) : ordered;
+  const sorted = applyOrderHint(restricted, orderHint);
   for (const entry of sorted) {
     if (entry.status === "queued" && entryDependenciesSatisfied(queue, entry)) {
       return entry;

package/src/loop/reviewer-loop-state.mjs

@@ -18,40 +18,55 @@ export const REVIEWER_STATE = Object.freeze({
   BLOCKED_NEEDS_USER_DECISION: "blocked_needs_user_decision",
 });
 
+// The reviewSubmissionStatus guard applies only after the {!prExists, prMerged, prClosed,
+// prDraft} pre-gates, then fires ahead of the state-specific branches: failed ->
+// blocked_needs_user_decision, submitted -> submitted_review. The table declares every such pair.
 export const REVIEWER_TRANSITIONS = Object.freeze({
-  [REVIEWER_STATE.WAITING_FOR_REVIEW_REQUEST]: [REVIEWER_STATE.REVIEW_REQUESTED],
+  [REVIEWER_STATE.WAITING_FOR_REVIEW_REQUEST]: [
+    REVIEWER_STATE.REVIEW_REQUESTED,
+    REVIEWER_STATE.SUBMITTED_REVIEW,
+    REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
   [REVIEWER_STATE.REVIEW_REQUESTED]: [
     REVIEWER_STATE.DETERMINE_REVIEW_PLAN,
+    REVIEWER_STATE.SUBMITTED_REVIEW,
     REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
   ],
   [REVIEWER_STATE.DETERMINE_REVIEW_PLAN]: [
     REVIEWER_STATE.REVIEWS_RUNNING,
+    REVIEWER_STATE.SUBMITTED_REVIEW,
     REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
   ],
   [REVIEWER_STATE.REVIEWS_RUNNING]: [
     REVIEWER_STATE.MERGE_RESULTS,
+    REVIEWER_STATE.SUBMITTED_REVIEW,
     REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
   ],
   [REVIEWER_STATE.MERGE_RESULTS]: [
     REVIEWER_STATE.DRAFT_REVIEW_READY,
+    REVIEWER_STATE.SUBMITTED_REVIEW,
     REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
   ],
   [REVIEWER_STATE.DRAFT_REVIEW_READY]: [
     REVIEWER_STATE.DRAFT_REVIEW_POSTED,
+    REVIEWER_STATE.SUBMITTED_REVIEW,
     REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
   ],
   [REVIEWER_STATE.DRAFT_REVIEW_POSTED]: [
     REVIEWER_STATE.WAITING_FOR_USER_SUBMIT,
     REVIEWER_STATE.REVIEW_INVALIDATED,
     REVIEWER_STATE.SUBMITTED_REVIEW,
+    REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
   ],
   [REVIEWER_STATE.WAITING_FOR_USER_SUBMIT]: [
     REVIEWER_STATE.SUBMITTED_REVIEW,
     REVIEWER_STATE.REVIEW_INVALIDATED,
+    REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
   ],
   [REVIEWER_STATE.SUBMITTED_REVIEW]: [
     REVIEWER_STATE.REVIEW_REQUESTED,
     REVIEWER_STATE.WAITING_FOR_REVIEW_REQUEST,
+    REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
   ],
   [REVIEWER_STATE.WAITING_FOR_AUTHOR_FOLLOWUP]: [
     REVIEWER_STATE.SUBMITTED_REVIEW,
@@ -62,7 +77,10 @@ export const REVIEWER_TRANSITIONS = Object.freeze({
     REVIEWER_STATE.REVIEW_REQUESTED,
     REVIEWER_STATE.SUBMITTED_REVIEW,
   ],
-  [REVIEWER_STATE.REVIEW_INVALIDATED]: [REVIEWER_STATE.REVIEW_REQUESTED],
+  [REVIEWER_STATE.REVIEW_INVALIDATED]: [
+    REVIEWER_STATE.REVIEW_REQUESTED,
+    REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
   [REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION]: [],
 });