@dev-loops/core 0.2.7 → 0.4.0

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) {

package/src/loop/run-context.mjs

@@ -1,15 +1,11 @@
 /**
  * Neutral run-id / async-context contract.
  *
- * The dev-loop async path historically keyed off Pi's `PI_SUBAGENT_RUN_ID` env var to
+ * The dev-loop async path keys off the harness-neutral `DEVLOOPS_RUN_ID` env var to
  * identify an inspectable per-subagent run (runner ownership, async-start enforcement,
- * human-comment gating). This module generalizes that into a harness-neutral
- * `DEVLOOPS_RUN_ID`, keeping `PI_SUBAGENT_RUN_ID` as a backward-compatible alias, and
- * provides a mint-and-propagate path for harnesses (e.g. Claude Code) that inject no
- * native per-subagent run id.
- *
- * Marker precedence is neutral-first: a present `DEVLOOPS_RUN_ID` wins; otherwise the Pi
- * alias is honored. Existing Pi runs that set only `PI_SUBAGENT_RUN_ID` behave identically.
+ * human-comment gating), and provides a mint-and-propagate path for harnesses (e.g. Claude
+ * Code) that inject no native per-subagent run id. The harness sets `DEVLOOPS_RUN_ID` when
+ * dispatching an async subagent.
  *
  * This module is pure except for the explicit file/IO helpers (writeRunContext/readRunContext),
  * which take an injectable `fs` and `root` for testability.
@@ -21,16 +17,13 @@ import path from "node:path";
 
 /**
  * Env var names that carry the async-context run id, in resolution precedence order.
- * Neutral `DEVLOOPS_RUN_ID` first; Pi `PI_SUBAGENT_RUN_ID` retained as a compatibility alias.
+ * The neutral `DEVLOOPS_RUN_ID` is the sole marker.
  */
-export const RUN_ID_MARKERS = Object.freeze(["DEVLOOPS_RUN_ID", "PI_SUBAGENT_RUN_ID"]);
+export const RUN_ID_MARKERS = Object.freeze(["DEVLOOPS_RUN_ID"]);
 
 /** Neutral env var name used when minting/propagating a run id. */
 export const NEUTRAL_RUN_ID_VAR = "DEVLOOPS_RUN_ID";
 
-/** Pi-compatibility alias env var name. */
-export const PI_RUN_ID_ALIAS_VAR = "PI_SUBAGENT_RUN_ID";
-
 /** State-file name (under `.pi/`, consistent with existing dev-loop checkpoint files). */
 export const RUN_CONTEXT_FILENAME = "dev-loop-run-context.json";
 
@@ -56,7 +49,7 @@ export function isClaudeHarness(env = process.env) {
 }
 
 /**
- * Resolve the active run id from the environment, neutral marker first.
+ * Resolve the active run id from the environment.
  *
  * @param {Record<string, string|undefined>} [env]
  * @returns {string|null} The trimmed run id, or null when none is set.
@@ -154,8 +147,8 @@ export function readRunContext({ root, fs = fsDefault }) {
  * Resolve the active run id, or mint one and persist a run-context state file.
  *
  * This is the "mint at startup and propagate" primitive a Claude dev-loop agent (or a
- * headless entry) calls before dispatching child work. When the env already carries a run
- * id (Pi alias or neutral), it is reused and no new id is minted.
+ * headless entry) calls before dispatching child work. When the env already carries a
+ * `DEVLOOPS_RUN_ID`, it is reused and no new id is minted.
  *
  * @param {object} [params]
  * @param {Record<string, string|undefined>} [params.env]

package/src/loop/worktree-guard.mjs

@@ -121,32 +121,22 @@ export function isListedWorktree(cwd, worktreePaths) {
  * Neutral environment variable name checked by `detectSubagentAvailability`.
  *
  * Set `DEVLOOPS_SUBAGENT_AVAILABLE=1` when the runtime supports subagent dispatch.
- * This is consistent with the `PI_WORKTREE_BYPASS` pattern and other repo-local
+ * This is consistent with the `DEVLOOPS_WORKTREE_BYPASS` pattern and other repo-local
  * runtime configuration gates already present in the repo.
  */
 export const DEVLOOPS_SUBAGENT_AVAILABLE_VAR = "DEVLOOPS_SUBAGENT_AVAILABLE";
 
-/**
- * Pi-compatibility alias for {@link DEVLOOPS_SUBAGENT_AVAILABLE_VAR}; honored when the
- * neutral var is unset so existing Pi runtimes keep working unchanged.
- */
-export const PI_SUBAGENT_AVAILABLE_VAR = "PI_SUBAGENT_AVAILABLE";
-
-/** Availability env var names, neutral-first. */
-export const SUBAGENT_AVAILABLE_VARS = Object.freeze([
-  DEVLOOPS_SUBAGENT_AVAILABLE_VAR,
-  PI_SUBAGENT_AVAILABLE_VAR,
-]);
+/** Availability env var names. */
+export const SUBAGENT_AVAILABLE_VARS = Object.freeze([DEVLOOPS_SUBAGENT_AVAILABLE_VAR]);
 
 /**
  * Detect whether subagent dispatch is available in the current runtime.
  *
  * This is an env-var-based heuristic, consistent with other bypass/availability
  * patterns in the repo. It is intentionally simple — the gate's subagent check
- * is advisory (fails-open) and never hard-blocks on subagent absence. Precedence is
- * neutral-first: the first var that is *set* (non-blank) is authoritative — so an explicit
- * `DEVLOOPS_SUBAGENT_AVAILABLE=0` is respected even when `PI_SUBAGENT_AVAILABLE=1`. The Pi
- * alias is only consulted when the neutral var is unset/blank.
+ * is advisory (fails-open) and never hard-blocks on subagent absence. The var that is
+ * *set* (non-blank) is authoritative — so an explicit `DEVLOOPS_SUBAGENT_AVAILABLE=0` is
+ * respected as a hard "not available".
  *
  * @param {{ env?: Record<string, string | undefined> }} [options]
  * @returns {boolean}