@dev-loops/core 0.2.6 → 0.3.0

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

@@ -6,6 +6,107 @@ import { main as moveQueueItemMain } from "../../../../scripts/projects/move-que
 
 const DEFAULT_NON_SUCCESS_COLUMN = "Backlog";
 
+// ── State → board column mapping (AC1, AC3, AC5) ─────────────────────────
+//
+// The mapping is intentionally stateless: it is a pure function of the loop
+// state. Because of that, a reverted loop state (e.g. a merged PR reopened, or
+// a ready PR demoted back to draft) maps backward to the earlier column for
+// free (AC5) — there is no persisted "furthest reached" column to unwind.
+
+/** Logical board columns. Display names are config-driven (AC3). */
+export const LOGICAL_COLUMN = Object.freeze({
+  NEXT_UP: "next_up",
+  IN_PROGRESS: "in_progress",
+  READY_FOR_REVIEW: "ready_for_review",
+  DONE: "done",
+});
+
+/** Allow-list of recognized logical column tokens (for config validation). */
+const KNOWN_LOGICAL_COLUMNS = new Set(Object.values(LOGICAL_COLUMN));
+
+/** Keys that must never be copied from untrusted config (prototype pollution). */
+const DANGEROUS_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+
+/** Default display name for each logical column (AC1 values). */
+export const DEFAULT_STATE_COLUMN_NAMES = Object.freeze({
+  [LOGICAL_COLUMN.NEXT_UP]: "Next Up",
+  [LOGICAL_COLUMN.IN_PROGRESS]: "In Progress",
+  // Ready for Review is opt-in: by default it resolves to In Progress so that
+  // final_approval_ready keeps "In Progress" unless a board configures it.
+  [LOGICAL_COLUMN.READY_FOR_REVIEW]: "In Progress",
+  [LOGICAL_COLUMN.DONE]: "Done",
+});
+
+/**
+ * Default loop-state → logical-column map. Covers both the lifecycle states
+ * (lifecycle-state.mjs) and the inner Copilot loop states (copilot-loop-state.mjs),
+ * plus the conceptual names used by issue #793. Unknown states fall back to
+ * IN_PROGRESS (a safe, visible "work is happening" column) rather than throwing.
+ */
+export const DEFAULT_STATE_LOGICAL_MAP = Object.freeze({
+  // Next Up — work not yet actively in flight
+  issue_opened: LOGICAL_COLUMN.NEXT_UP,
+  issue_intake: LOGICAL_COLUMN.NEXT_UP,
+  refinement: LOGICAL_COLUMN.NEXT_UP,
+  no_pr: LOGICAL_COLUMN.NEXT_UP,
+  pr_draft: LOGICAL_COLUMN.NEXT_UP,
+
+  // In Progress — active implementation / review / feedback resolution
+  implementation: LOGICAL_COLUMN.IN_PROGRESS,
+  // Tolerated alias for `implementation` (conceptual name from issue #793);
+  // the queue driver passes the real `implementation` lifecycle state.
+  local_implementation_active: LOGICAL_COLUMN.IN_PROGRESS,
+  draft_gate: LOGICAL_COLUMN.IN_PROGRESS,
+  pr_ready_no_feedback: LOGICAL_COLUMN.IN_PROGRESS,
+  feedback_resolution: LOGICAL_COLUMN.IN_PROGRESS,
+  copilot_review: LOGICAL_COLUMN.IN_PROGRESS,
+  waiting_for_copilot_review: LOGICAL_COLUMN.IN_PROGRESS,
+  ready_to_rerequest_review: LOGICAL_COLUMN.IN_PROGRESS,
+  unresolved_feedback_present: LOGICAL_COLUMN.IN_PROGRESS,
+  already_fixed_needs_reply_resolve: LOGICAL_COLUMN.IN_PROGRESS,
+  waiting_for_ci: LOGICAL_COLUMN.IN_PROGRESS,
+  review_request_unavailable: LOGICAL_COLUMN.IN_PROGRESS,
+  round_cap_reached: LOGICAL_COLUMN.IN_PROGRESS,
+  round_cap_clean_fallback: LOGICAL_COLUMN.IN_PROGRESS,
+  internal_tooling_direct_gate: LOGICAL_COLUMN.IN_PROGRESS,
+  low_signal_converged: LOGICAL_COLUMN.IN_PROGRESS,
+  blocked_needs_user_decision: LOGICAL_COLUMN.IN_PROGRESS,
+
+  // Ready for Review — final approval gate. Resolves to In Progress unless a
+  // board configures a distinct "Ready for Review" column name (AC1).
+  pre_approval_gate: LOGICAL_COLUMN.READY_FOR_REVIEW,
+  final_approval_ready: LOGICAL_COLUMN.READY_FOR_REVIEW,
+
+  // Done — terminal (lifecycle MERGE = "merge", queue terminal = "done")
+  merge: LOGICAL_COLUMN.DONE,
+  done: LOGICAL_COLUMN.DONE,
+  // Tolerated aliases (conceptual names from issue #793).
+  merged: LOGICAL_COLUMN.DONE,
+  issue_closed: LOGICAL_COLUMN.DONE,
+});
+
+/** Safe default logical column for any state we do not explicitly map. */
+const DEFAULT_LOGICAL_COLUMN = LOGICAL_COLUMN.IN_PROGRESS;
+
+/**
+ * Pure mapping: loop state → board column display name.
+ *
+ * @param {string|null|undefined} loopState - a lifecycle or inner loop state
+ *   name. `null`, `undefined`, and any unrecognized value fall through to the
+ *   safe default logical column (IN_PROGRESS).
+ * @param {{stateColumnMap?:Object, columnNames?:Object}} [mapping]
+ *   Optional overrides. `stateColumnMap` overrides state→logical-column;
+ *   `columnNames` overrides logical-column→display-name. Both fall back to
+ *   the AC1 defaults.
+ * @returns {string} the target board column display name.
+ */
+export function boardColumnForLoopState(loopState, mapping = {}) {
+  const stateMap = { ...DEFAULT_STATE_LOGICAL_MAP, ...(mapping.stateColumnMap ?? {}) };
+  const columnNames = { ...DEFAULT_STATE_COLUMN_NAMES, ...(mapping.columnNames ?? {}) };
+  const logical = stateMap[loopState] ?? DEFAULT_LOGICAL_COLUMN;
+  return columnNames[logical] ?? columnNames[DEFAULT_LOGICAL_COLUMN];
+}
+
 // ── Local config loader ─────────────────────────────────────────────────
 
 function readDevloopsSettings(repoRoot) {
@@ -46,6 +147,62 @@ export function loadBoardConfig(repoRoot) {
   return { enabled: false };
 }
 
+/**
+ * Load the config-driven state→column mapping from `.devloops` `queue` (AC3).
+ *
+ * Reads two optional config keys, both gated behind the same opt-in `queue`
+ * section as `loadBoardConfig` (AC2/AC6):
+ *   - `queue.statusColumns`  — logical-column → display-name overrides
+ *     (keys: next_up, in_progress, ready_for_review, done)
+ *   - `queue.stateColumnMap` — loop-state → logical-column overrides
+ *
+ * Returns a `{ stateColumnMap, columnNames }` shape consumable by
+ * `boardColumnForLoopState`. Missing config yields the AC1 defaults.
+ *
+ * Hardened against untrusted `.devloops` input:
+ *   - `statusColumns` keys are allow-listed to the known logical columns;
+ *     unrecognized keys are ignored.
+ *   - `stateColumnMap` entries whose value is not a known logical column are
+ *     ignored.
+ *   - Dangerous keys (`__proto__`, `prototype`, `constructor`) are skipped and
+ *     results are built on null-prototype objects, so a malicious config key
+ *     cannot pollute Object.prototype.
+ */
+export function loadStateColumnMap(repoRoot) {
+  const { settings: queue } = 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);
+
+  const statusColumns = queue?.statusColumns;
+  if (statusColumns && typeof statusColumns === "object") {
+    for (const logical of Object.keys(statusColumns)) {
+      if (DANGEROUS_KEYS.has(logical)) continue;
+      // Allow-list: only recognized logical columns may be renamed.
+      if (!KNOWN_LOGICAL_COLUMNS.has(logical)) continue;
+      const name = statusColumns[logical];
+      if (typeof name === "string" && name.trim().length > 0) {
+        columnNames[logical] = name.trim();
+      }
+    }
+  }
+
+  const stateMap = queue?.stateColumnMap;
+  if (stateMap && typeof stateMap === "object") {
+    for (const state of Object.keys(stateMap)) {
+      if (DANGEROUS_KEYS.has(state)) continue;
+      const logical = stateMap[state];
+      // Ignore values that are not a recognized logical column.
+      if (typeof logical !== "string") continue;
+      const trimmed = logical.trim();
+      if (!KNOWN_LOGICAL_COLUMNS.has(trimmed)) continue;
+      stateColumnMap[state] = trimmed;
+    }
+  }
+
+  return { columnNames, stateColumnMap };
+}
+
 // ── Minimal project lookup (read-only, no create/repair) ────────────────
 
 const GET_USER_ID = [
@@ -187,6 +344,14 @@ export async function syncBoardStatus(
   env = process.env,
   dependencies = {},
 ) {
+  // AC4: the not-on-board / fail-open path is a logged no-op. Default to
+  // console.error so it logs in real runs; tests inject their own stub. The
+  // log fires at most once per syncBoardStatus call (single catch, no internal
+  // retry), so it cannot spam.
+  const log = typeof dependencies.log === "function"
+    ? dependencies.log
+    : (msg) => console.error(msg);
+
   const config = loadBoardConfig(repoRoot);
   if (!config.enabled) {
     return { ok: true, skipped: true, reason: config.reason ?? "board not configured" };
@@ -205,12 +370,27 @@ export async function syncBoardStatus(
   const moveItem = dependencies.moveQueueItem ?? moveQueueItemMain;
   try {
     const result = await moveItem(
-      { repo, project: projectNumber, item: itemNumber, toColumn: targetColumn },
+      // move-queue-item validates project + item as string refs (CLI contract);
+      // resolveProjectNumber yields a number and itemNumber is numeric, so
+      // stringify both.
+      { repo, project: String(projectNumber), item: String(itemNumber), toColumn: targetColumn },
       { env, runChild: dependencies.runChild },
     );
     return { ok: true, skipped: false, result };
   } catch (err) {
-    return { ok: true, skipped: true, reason: err.message ?? "board sync failed" };
+    // Fail-open: a board hiccup (rate limit, missing column, item not on board)
+    // must never break the loop.
+    const reason = err?.message ?? "board sync failed";
+    // AC4: the explicit "item not on board" case is a clean, logged no-op.
+    // Other fail-open failures (rate limit, missing column, etc.) get a
+    // distinct, distinguishable message so they are not conflated with AC4.
+    const notOnBoard = err?.code === "ITEM_NOT_FOUND" || err?.code === "ITEM_NOT_ON_BOARD";
+    if (notOnBoard) {
+      log(`[board-sync] no-op: item ${itemNumber} is not on the board (${reason})`);
+    } else {
+      log(`[board-sync] sync failed (fail-open) for item ${itemNumber} → "${targetColumn}": ${reason}`);
+    }
+    return { ok: true, skipped: true, reason };
   }
 }
 

package/src/loop/queue-driver.mjs

@@ -13,7 +13,12 @@ import {
   RECOVERABLE_FAILURES,
   appendBugIssue,
 } from "./queue-state.mjs";
-import { syncBoardStatus, nonSuccessBoardColumn } from "./queue-board-sync.mjs";
+import {
+  syncBoardStatus,
+  nonSuccessBoardColumn,
+  boardColumnForLoopState,
+  loadStateColumnMap,
+} from "./queue-board-sync.mjs";
 import { resolveNextUpOrder } from "./queue-board-ordering.mjs";
 
 export const DEFAULT_QUEUE_DRIVER_OPTIONS = {
@@ -52,6 +57,19 @@ export async function runQueue(repoRoot, repo, options = {}) {
   const opts = { ...DEFAULT_QUEUE_DRIVER_OPTIONS, ...options };
   const queue = await readQueue(repoRoot);
 
+  // Config-driven loop-state → board-column mapping (#793, AC1/AC3). Loaded
+  // once per run; resolves logical columns to configured display names, with
+  // the AC1 defaults when no `queue.statusColumns`/`queue.stateColumnMap` is set.
+  const stateColumnMap = loadStateColumnMap(repoRoot);
+  const columnFor = (loopState) => boardColumnForLoopState(loopState, stateColumnMap);
+
+  // Per-item dedup: a single run may resolve consecutive loop states to the
+  // same display column (e.g. implementation → final_approval_ready both
+  // default to "In Progress"). Skip the redundant board write/API call when the
+  // target column is unchanged for that item; a genuinely different column
+  // (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.
@@ -95,15 +113,26 @@ export async function runQueue(repoRoot, repo, options = {}) {
       boardSync.push(r);
       return r;
     };
+    // Sync a target to a column, short-circuiting (no API call) when the column
+    // is unchanged from the last sync for the same item in this run.
+    const syncColumn = async (target, column) => {
+      if (lastSyncedColumn.get(target) === column) {
+        return recordBoardSync(Promise.resolve({
+          ok: true, skipped: true, reason: "column unchanged",
+        }));
+      }
+      const r = await recordBoardSync(syncBoardStatus(
+        repo, repoRoot, target, column, opts.env ?? process.env, boardSyncDeps,
+      ));
+      // Only remember the column when the move actually landed, so a fail-open
+      // skip does not suppress a later retry to the same column.
+      if (r.ok && r.skipped !== true) lastSyncedColumn.set(target, column);
+      return r;
+    };
 
-    await recordBoardSync(syncBoardStatus(
-      repo,
-      repoRoot,
-      entry.target,
-      "In Progress",
-      opts.env ?? process.env,
-      boardSyncDeps,
-    ));
+    // Entry has been picked up and is actively running: implementation phase
+    // (real lifecycle state, lifecycle-state.mjs LIFECYCLE_STATE.IMPLEMENTATION).
+    await syncColumn(entry.target, columnFor("implementation"));
 
     try {
       const entryResult = opts.runEntry
@@ -117,12 +146,18 @@ export async function runQueue(repoRoot, repo, options = {}) {
           if (opts.mergeAuthorized) {
             await doTransition(entry, "merging", queue, repoRoot, opts);
             await doTransition(entry, "done", queue, repoRoot, opts, { retrospectiveWritten: true });
-            await recordBoardSync(syncBoardStatus(repo, repoRoot, entry.target, "Done", opts.env ?? process.env, boardSyncDeps));
+            await syncColumn(entry.target, columnFor("done"));
+          } else {
+            // PR is up with gates passing but merge is not authorized: the work
+            // is awaiting final approval/merge. Map to the final-approval column
+            // (configured "Ready for Review" if present, else "In Progress").
+            // Deduped: when this resolves to the same column already synced for
+            // this item, no extra board write/API call is made.
+            await syncColumn(entry.target, columnFor("final_approval_ready"));
           }
-          // else: stays at gates_passing for future merge run
         } else {
           await doTransition(entry, "done", queue, repoRoot, opts);
-          await recordBoardSync(syncBoardStatus(repo, repoRoot, entry.target, "Done", opts.env ?? process.env, boardSyncDeps));
+          await syncColumn(entry.target, columnFor("done"));
         }
         results.push({ target: entry.target, ok: true, entry: snapshotEntry(entry), boardSync });
       } else {

package/src/loop/queue-membership.mjs

@@ -0,0 +1,145 @@
+/**
+ * Queue membership reconciliation (issue #864).
+ *
+ * A configured GitHub Projects board is the authoritative source of queue
+ * MEMBERSHIP (which issues to work) and ordering — not just status. Before a
+ * queue run, this module folds the board's "Next Up" items into the local
+ * `.pi/dev-loop-queue.json` entries so the board drives membership, and reports
+ * a clear, non-misleading emptiness verdict.
+ *
+ * This is the testable orchestration seam used by `scripts/loop/run-queue.mjs`.
+ * Board config loading, Next Up resolution, and queue persistence are all
+ * injectable so the policy can be exercised without GitHub or the filesystem.
+ */
+
+import { loadBoardConfig } from "./queue-board-sync.mjs";
+import { resolveNextUpOrder } from "./queue-board-ordering.mjs";
+import { reconcileEntriesFromBoard, writeQueue, pendingEntries } from "./queue-state.mjs";
+
+/**
+ * Reconcile a configured board's Next Up membership into the queue, then
+ * classify emptiness.
+ *
+ * Behavior:
+ *   - Board NOT configured: no reconcile. Emptiness is judged purely on the
+ *     local queue (preserving the legacy "Queue is empty" behavior).
+ *   - Board configured: resolve Next Up targets and reconcile them in. If the
+ *     resolver fails-open (returns no targets) the board membership simply
+ *     contributes nothing; we never crash. Newly added targets are persisted
+ *     via `writeQueue`.
+ *
+ * Emptiness verdict (`emptiness`):
+ *   - `null`              — there is pending work; the caller should run the queue.
+ *   - "queue_empty"       — board not configured and the local queue is empty
+ *                           (legacy "Queue is empty" message).
+ *   - "board_empty"       — board IS configured, Next Up resolved successfully
+ *                           (reason == null) but is genuinely empty, and there is
+ *                           no pending local work. Distinct from the misleading
+ *                           generic empty case.
+ *   - "board_unavailable" — board IS configured but Next Up resolution failed
+ *                           (fail-open: empty order WITH a non-null reason) and
+ *                           the local queue had no pending work to fall back to.
+ *                           This must NOT be reported as "board_empty" — the
+ *                           board may well have items we simply could not read.
+ *
+ * @param {string} repoRoot
+ * @param {string} repo - "owner/name"
+ * @param {{version:number, entries:Array}} queue
+ * @param {object} [deps]
+ * @param {(repoRoot:string)=>{enabled:boolean}} [deps.loadBoardConfig]
+ * @param {(repo:string, repoRoot:string, env:object, d:object)=>Promise<{ok:boolean, order:number[], reason:?string}>} [deps.resolveNextUpOrder]
+ * @param {(repoRoot:string, queue:object)=>Promise<void>} [deps.writeQueue]
+ * @param {(msg:string)=>void} [deps.log]
+ * @returns {Promise<{queue:object, added:number[], boardConfigured:boolean, emptiness:(null|"queue_empty"|"board_empty"|"board_unavailable"), reason:(string|null)}>}
+ */
+export async function reconcileBoardMembership(repoRoot, repo, queue, deps = {}) {
+  const loadConfig = deps.loadBoardConfig ?? loadBoardConfig;
+  const resolveOrder = deps.resolveNextUpOrder ?? resolveNextUpOrder;
+  const persist = deps.writeQueue ?? writeQueue;
+  const log = typeof deps.log === "function" ? deps.log : (msg) => console.error(msg);
+
+  let boardConfigured = false;
+  try {
+    const config = loadConfig(repoRoot);
+    boardConfigured = Boolean(config?.enabled);
+    // loadBoardConfig does not throw on read/parse failures; it reports them
+    // via `{ enabled: false, reason: ... }`. Surface that reason so a genuine
+    // config read/parse error is visible instead of being silently treated as
+    // "board not configured". The ordinary "board not configured" case carries
+    // no reason and must stay quiet.
+    if (!boardConfigured && config?.reason) {
+      log(`[queue-membership] board config unavailable (fail-open): ${config.reason}`);
+    }
+  } catch (err) {
+    // Config read errors must not crash the queue; treat as unconfigured.
+    log(`[queue-membership] board config read failed (fail-open): ${err?.message ?? err}`);
+    boardConfigured = false;
+  }
+
+  let added = [];
+  let reason = null;
+  // True when the board is configured but Next Up could not be resolved: the
+  // resolver is fail-open, so this surfaces as an empty order WITH a non-null
+  // reason (or a thrown error caught below). We must not confuse this with a
+  // genuinely empty Next Up (empty order AND reason == null).
+  let resolutionFailed = false;
+
+  if (boardConfigured) {
+    let nextUp = [];
+    try {
+      // env/board dependencies use resolveNextUpOrder's own defaults
+      // (process.env / {}); the production caller never overrides them, and
+      // tests inject a stubbed resolveNextUpOrder.
+      const result = await resolveOrder(repo, repoRoot, process.env, {});
+      reason = result?.reason ?? null;
+      nextUp = Array.isArray(result?.order) ? result.order : [];
+      // Fail-open contract: an empty order paired with a non-null reason means
+      // resolution failed (API error, board lookup failure, etc.) — NOT that the
+      // board's Next Up is genuinely empty.
+      if (nextUp.length === 0 && reason != null) {
+        resolutionFailed = true;
+        log(`[queue-membership] Next Up resolution failed (fail-open), using local queue: ${reason}`);
+      }
+    } catch (err) {
+      // resolveNextUpOrder is itself fail-open, but guard anyway: a board
+      // resolution error falls back to the local queue without crashing.
+      reason = err?.message ?? "board resolution failed";
+      resolutionFailed = true;
+      log(`[queue-membership] Next Up resolution failed (fail-open), using local queue: ${reason}`);
+      nextUp = [];
+    }
+
+    if (nextUp.length > 0) {
+      const outcome = reconcileEntriesFromBoard(queue, nextUp);
+      added = outcome.added;
+      if (added.length > 0) {
+        log(`[queue-membership] added ${added.length} entr${added.length === 1 ? "y" : "ies"} from board Next Up: ${added.join(", ")}`);
+        try {
+          await persist(repoRoot, queue);
+        } catch (err) {
+          // A write failure should not crash the run; entries still drive this
+          // in-memory run, they just are not persisted for the next invocation.
+          log(`[queue-membership] failed to persist reconciled queue (continuing in-memory): ${err?.message ?? err}`);
+        }
+      }
+    }
+  }
+
+  const pending = pendingEntries(queue);
+  let emptiness = null;
+  if (pending.length === 0) {
+    if (!boardConfigured) {
+      emptiness = "queue_empty";
+    } else if (resolutionFailed) {
+      // Board configured but we could not read Next Up and the local queue is
+      // empty: the board may have items we simply failed to fetch. Report a
+      // distinct verdict instead of the misleading "board_empty".
+      emptiness = "board_unavailable";
+    } else {
+      // Board configured, Next Up resolved cleanly (reason == null) and empty.
+      emptiness = "board_empty";
+    }
+  }
+
+  return { queue, added, boardConfigured, emptiness, reason };
+}

package/src/loop/queue-state.mjs

@@ -81,7 +81,7 @@ export async function writeQueue(repoRoot, queue) {
 export function createEntry(target, kind, dependsOn = []) {
   return {
     target,
-    kind,           // "issue" | "pr"
+    kind,           // "issue" | "pr" | "board" (board = issue-or-PR, resolved by number at run time)
     status: "queued",
     dependsOn: Array.isArray(dependsOn) ? dependsOn : [],
     pr: null,
@@ -211,6 +211,61 @@ export function pendingEntries(queue) {
   );
 }
 
+// ── Board membership reconciliation ──────────────────────────────────
+
+/**
+ * Reconcile board-driven membership into the local queue (issue #864).
+ *
+ * A configured GitHub Projects board is the authoritative source of queue
+ * MEMBERSHIP (which issues should be worked), not just ordering/status. This
+ * pure helper folds the board's "Next Up" targets into the queue: for each
+ * target not already present (by `findEntry`), it appends a fresh queued
+ * `createEntry(target, "board")`. Existing entries — and their status, order,
+ * and metadata — are preserved untouched, and targets already present are
+ * skipped (dedup).
+ *
+ * Entry kind is `"board"` rather than `"issue"`: the board's Next Up can hold
+ * issues OR PRs, and `resolveNextUpOrder` collapses each item to a bare number
+ * (`issueNumber ?? prNumber`), discarding the artifact kind. The queue driver
+ * never branches on `entry.kind`; it dispatches purely by `entry.target` and
+ * the per-entry startup resolver resolves the actual artifact (issue or PR) by
+ * number at run time. So a neutral `"board"` kind correctly records the
+ * provenance without falsely asserting "issue" for PR-backed board items.
+ *
+ * Pure: performs no I/O. Mutates and returns the passed `queue` object (its
+ * `entries` array is appended to in place) plus the list of newly added
+ * targets so the caller can log/report.
+ *
+ * @param {{version:number, entries:Array}} queue - the current queue.
+ * @param {Array<number>} nextUpTargets - board "Next Up" issue/PR numbers.
+ * @returns {{queue:{version:number, entries:Array}, added:number[]}}
+ */
+export function reconcileEntriesFromBoard(queue, nextUpTargets) {
+  const added = [];
+  if (!queue || !Array.isArray(queue.entries)) {
+    return { queue, added };
+  }
+  if (!Array.isArray(nextUpTargets) || nextUpTargets.length === 0) {
+    return { queue, added };
+  }
+  for (const target of nextUpTargets) {
+    // Guard against malformed/duplicate board input: only positive-integer
+    // targets, and never add the same target twice (even if it repeats in the
+    // board list and was not yet in the queue at the start of this loop).
+    //
+    // The integer guard is critical for NaN: a NaN target never dedups via
+    // findEntry (NaN !== NaN), so accepting it would re-append a fresh NaN
+    // entry on every reconcile. Infinity, non-integers, negatives, and 0 are
+    // never valid issue/PR numbers either, so reject anything that is not a
+    // positive integer.
+    if (!Number.isInteger(target) || target <= 0) continue;
+    if (findEntry(queue, target)) continue;
+    queue.entries.push(createEntry(target, "board"));
+    added.push(target);
+  }
+  return { queue, added };
+}
+
 // ── Bug injection ────────────────────────────────────────────────────
 
 export function appendBugIssue(queue, issueNumber, dependsOn = null) {