dev-loops 0.2.7 → 0.4.0

package/scripts/loop/run-queue.mjs

@@ -14,10 +14,13 @@
  */
 
 import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
 import { runQueue, DEFAULT_QUEUE_DRIVER_OPTIONS } from "@dev-loops/core/loop/queue-driver";
 import { computeParallelSchedule } from "@dev-loops/core/loop/queue-parallel";
 import { readQueue } from "@dev-loops/core/loop/queue-state";
+import { reconcileBoardMembership } from "@dev-loops/core/loop/queue-membership";
 import { parsePositiveInteger } from "@dev-loops/core/cli/primitives";
+import { loadDevLoopConfig, resolveEffectiveMergeAuthorizedFromLoad } from "@dev-loops/core/config";
 
 const REPO_ROOT = fileURLToPath(new URL("../..", import.meta.url));
 
@@ -27,7 +30,7 @@ const USAGE = `Usage:
 Run the dev-loop queue driver over entries in .pi/dev-loop-queue.json.
 Exit codes: 0 success, 1 error`.trim();
 
-function parseArgs(argv) {
+function parseCliArgs(argv) {
   const args = {
     repo: null,
     mergeAuthorized: false,
@@ -37,27 +40,58 @@ function parseArgs(argv) {
     help: false,
   };
 
-  for (let i = 0; i < argv.length; i++) {
-    switch (argv[i]) {
-      case "--repo":
-        args.repo = argv[++i];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      repo: { type: "string" },
+      "merge-authorized": { type: "boolean" },
+      parallel: { type: "boolean" },
+      "redispatch-max-retries": { type: "string" },
+      "max-parallel": { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw new Error(`unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    switch (token.name) {
+      case "repo":
+        args.repo = token.value;
         break;
-      case "--merge-authorized":
+      case "merge-authorized":
+        if (token.value !== undefined) {
+          throw new Error(`unknown argument: ${token.rawName}=${token.value}`);
+        }
         args.mergeAuthorized = true;
         break;
-      case "--parallel":
+      case "parallel":
+        if (token.value !== undefined) {
+          throw new Error(`unknown argument: ${token.rawName}=${token.value}`);
+        }
         args.parallel = true;
         break;
-      case "--redispatch-max-retries":
-        args.reDispatchMaxRetries = parsePositiveInteger(argv[++i], "--redispatch-max-retries");
+      case "redispatch-max-retries":
+        args.reDispatchMaxRetries = parsePositiveInteger(token.value, "--redispatch-max-retries");
         break;
-      case "--max-parallel":
-        args.maxParallel = parsePositiveInteger(argv[++i], "--max-parallel");
+      case "max-parallel":
+        args.maxParallel = parsePositiveInteger(token.value, "--max-parallel");
         break;
-      case "--help":
-      case "-h":
+      case "help":
+        if (token.value !== undefined) {
+          throw new Error(`unknown argument: ${token.rawName}=${token.value}`);
+        }
         args.help = true;
         break;
+      default:
+        throw new Error(`unknown argument: ${token.rawName}`);
     }
   }
 
@@ -65,7 +99,7 @@ function parseArgs(argv) {
 }
 
 async function main() {
-  const args = parseArgs(process.argv.slice(2));
+  const args = parseCliArgs(process.argv.slice(2));
 
   if (args.help) {
     console.log(USAGE);
@@ -79,7 +113,46 @@ async function main() {
 
   const queue = await readQueue(REPO_ROOT);
 
-  if (queue.entries.length === 0) {
+  // A configured GitHub Projects board is the authoritative queue MEMBERSHIP
+  // source (issue #864): fold its "Next Up" items into the queue before judging
+  // emptiness so a populated board with an empty local queue is no longer a
+  // silent no-op. Fail-open — a board hiccup falls back to the local queue.
+  // reconcileBoardMembership already logs an "added N ... from board Next Up"
+  // line to stderr (single source of truth); we deliberately do not duplicate
+  // it here to avoid noise for JSON consumers of stdout.
+  const membership = await reconcileBoardMembership(REPO_ROOT, args.repo, queue);
+
+  if (membership.emptiness === "board_empty") {
+    // Distinct from the legacy generic "Queue is empty": the board is the
+    // membership source and it currently has nothing in Next Up. This branch is
+    // only reached for a genuinely empty Next Up (reason == null), never for a
+    // resolution failure (which falls through to the local queue below).
+    console.log(JSON.stringify({
+      ok: true,
+      message: "Board configured but Next Up is empty; nothing to run",
+      boardConfigured: true,
+      reason: null,
+      results: [],
+    }));
+    return;
+  }
+
+  if (membership.emptiness === "board_unavailable") {
+    // The board IS configured but Next Up resolution failed (fail-open) and the
+    // local queue had nothing to fall back to. Do NOT claim "Next Up is empty";
+    // surface the real reason so consumers can distinguish an outage from an
+    // intentionally empty board.
+    console.log(JSON.stringify({
+      ok: true,
+      message: `Board configured but unavailable (${membership.reason}); nothing to run`,
+      boardConfigured: true,
+      reason: membership.reason ?? null,
+      results: [],
+    }));
+    return;
+  }
+
+  if (membership.emptiness === "queue_empty") {
     console.log(JSON.stringify({ ok: true, message: "Queue is empty", results: [] }));
     return;
   }
@@ -109,9 +182,32 @@ async function main() {
     console.error("Parallel dispatch via async subagents not yet wired; falling back to sequential.");
   }
 
+  // Authoritative merge-authorization gate: when the repo enforces
+  // humanMergeOnly, --merge-authorized is ignored (fails closed) so the queue
+  // driver never auto-merges. `loadDevLoopConfig` never throws — it returns an
+  // `errors` array — so a try/catch would not catch an unreadable/invalid
+  // `.devloops` (which may be the very file declaring humanMergeOnly). FAIL
+  // CLOSED on any config load/validation error: if the config cannot be
+  // confirmed, do NOT grant merge authorization. A compliance invariant must
+  // never be silently dropped because its config could not be read.
+  let effectiveMergeAuthorized = args.mergeAuthorized;
+  if (args.mergeAuthorized) {
+    const load = await loadDevLoopConfig({ repoRoot: REPO_ROOT });
+    effectiveMergeAuthorized = resolveEffectiveMergeAuthorizedFromLoad(args.mergeAuthorized, load);
+    if ((load.errors?.length ?? 0) > 0) {
+      console.error(
+        JSON.stringify({
+          ok: true,
+          warning: "dev-loop config could not be loaded/validated; failing closed on merge authorization (not auto-merging).",
+          errors: load.errors.map((e) => (e && e.message) || String(e)),
+        }),
+      );
+    }
+  }
+
   const result = await runQueue(REPO_ROOT, args.repo, {
     ...DEFAULT_QUEUE_DRIVER_OPTIONS,
-    mergeAuthorized: args.mergeAuthorized,
+    mergeAuthorized: effectiveMergeAuthorized,
     reDispatchMaxRetries: args.reDispatchMaxRetries,
   });
 

package/scripts/loop/run-watch-cycle.mjs

@@ -5,7 +5,10 @@ import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helper
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION } from "@dev-loops/core/loop/public-dev-loop-routing";
 import { watchCopilotReview } from "../github/probe-copilot-review.mjs";
+import { watchCiStatus } from "../github/probe-ci-status.mjs";
 import { runHandoff } from "./copilot-pr-handoff.mjs";
+import { STATE } from "@dev-loops/core/loop/copilot-loop-state";
+import { DEFAULT_POLL_INTERVAL_MS } from "@dev-loops/core/loop/policy-constants";
 import { detectCopilotSessionActivity } from "./detect-copilot-session-activity.mjs";
 import { parseArgs } from "node:util";
 import {
@@ -124,16 +127,33 @@ function buildWatchCycleContractTrace({
   cycleDisposition,
   sessionActivity = null,
   workflowRunWatch = null,
+  ciWatchArgs = null,
+  ciWatchStatus = null,
 }) {
-  const boundaryClassification = handoff.action !== "watch"
-    ? (handoff.loopDisposition === "blocked"
+  // The CI-watch branch (waiting_for_ci) routes through probe-ci-status.mjs even
+  // though handoff.action !== "watch". It is an observational wait, so it mirrors
+  // the Copilot watch classification: a quiet timeout is a HEALTHY_WAIT, while
+  // success/failure/changed route a follow-up. Without this the boundary-action
+  // path below would misclassify a CI timeout as routed_followup.
+  const isCiWatch = ciWatchArgs !== null;
+  const isWatchBoundary = handoff.action === "watch" || isCiWatch;
+  const observedStatus = isCiWatch ? ciWatchStatus : watchStatus;
+  const boundaryClassification = isWatchBoundary
+    ? (observedStatus === "timeout" || observedStatus === "idle"
+      ? DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.HEALTHY_WAIT
+      : DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.ROUTED_FOLLOWUP)
+    : handoff.loopDisposition === "blocked"
       ? DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.BLOCKED
       : handoff.terminal
         ? DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.TERMINAL
-        : DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.ROUTED_FOLLOWUP)
-    : watchStatus === "changed"
-      ? DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.ROUTED_FOLLOWUP
-      : DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.HEALTHY_WAIT;
+        : DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.ROUTED_FOLLOWUP;
+  const healthyWait = boundaryClassification === DEV_LOOP_CONTRACT_TRACE_CLASSIFICATION.HEALTHY_WAIT;
+  const helper = handoff.action === "watch"
+    ? "scripts/github/probe-copilot-review.mjs"
+    : isCiWatch
+      ? "scripts/github/probe-ci-status.mjs"
+      : null;
+  const effectiveArgs = isCiWatch ? ciWatchArgs : watchArgs;
   return {
     handoff: {
       action: handoff.action,
@@ -142,38 +162,37 @@ function buildWatchCycleContractTrace({
       terminal: Boolean(handoff.terminal),
     },
     waitStrategy: {
-      helper: handoff.action === "watch" ? "scripts/github/probe-copilot-review.mjs" : null,
-      mode: handoff.action === "watch"
-        ? "persistent_watch"
-        : "not_applicable",
-      effectiveTimeoutMs: watchArgs?.timeoutMs ?? null,
-      effectivePollIntervalMs: watchArgs?.pollIntervalMs ?? null,
+      helper,
+      mode: isWatchBoundary ? "persistent_watch" : "not_applicable",
+      effectiveTimeoutMs: effectiveArgs?.timeoutMs ?? null,
+      effectivePollIntervalMs: effectiveArgs?.pollIntervalMs ?? null,
       timeoutPolicyClassification: watchTimeoutPolicy?.classification ?? null,
     },
     orchestration: {
       emittedWatchArgs: handoff.watchArgs ?? null,
-      effectiveWatchArgs: watchArgs,
+      effectiveWatchArgs: effectiveArgs,
+      ciWatchArgs,
       sessionActivity,
       workflowRunWatch,
     },
-    stateRefresh: handoff.action === "watch"
+    stateRefresh: isWatchBoundary
       ? {
           boundaryKind: "post_watch_or_probe",
-          observedStatus: watchStatus,
+          observedStatus,
           refreshRequired: true,
-          refreshReason: watchStatus === "changed"
-            ? "Watch boundaries with fresh activity require an authoritative state refresh before routing the follow-up path."
-            : "Healthy watch boundaries are observational only; refresh authoritative state before treating timeout/idle as stop or completion.",
+          refreshReason: healthyWait
+            ? "Healthy watch boundaries are observational only; refresh authoritative state before treating timeout/idle as stop or completion."
+            : "Watch boundaries with fresh activity require an authoritative state refresh before routing the follow-up path.",
         }
       : null,
     stopReason: {
       classification: boundaryClassification,
       terminal: Boolean(handoff.terminal),
       cycleDisposition,
-      reason: handoff.action === "watch"
-        ? (watchStatus === "changed"
-          ? "Fresh watcher activity requires follow-up instead of staying in a healthy wait boundary."
-          : "Quiet watcher boundaries remain healthy waits and must not be treated as terminal completion by themselves.")
+      reason: isWatchBoundary
+        ? (healthyWait
+          ? "Quiet watcher boundaries remain healthy waits and must not be treated as terminal completion by themselves."
+          : "Fresh watcher activity requires follow-up instead of staying in a healthy wait boundary.")
         : handoff.nextAction,
     },
   };
@@ -236,6 +255,7 @@ export async function runWatchCycle(
     ghCommand = "gh",
     runHandoffImpl = runHandoff,
     watchCopilotReviewImpl = watchCopilotReview,
+    watchCiStatusImpl = watchCiStatus,
     detectCopilotSessionActivityImpl = detectCopilotSessionActivity,
     fetchPrHeadBranchImpl = fetchPrHeadBranch,
     watchWorkflowRunImpl = watchWorkflowRun,
@@ -267,6 +287,39 @@ export async function runWatchCycle(
   if (handoff.watchTimeoutPolicy !== undefined) {
     result.watchTimeoutPolicy = handoff.watchTimeoutPolicy;
   }
+  // Provider-agnostic CI wait (#917): a waiting_for_ci boundary would otherwise
+  // dead-end at action:"stop". Route it to the helper-owned CI watcher
+  // (CircleCI / GH Actions / external commit-status), not gh run watch.
+  if (handoff.action !== "watch" && handoff.state === STATE.WAITING_FOR_CI) {
+    // Mirror determineWatchTimeout but with a CI-specific context label so
+    // timeout diagnostics read "CI wait" instead of "Copilot review wait".
+    const ciTimeoutMs = enforceExternalHealthyWaitTimeout({
+      timeoutMs: EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY.defaultTimeoutMs,
+      contextLabel: "CI wait",
+    });
+    const ciWatchArgs = {
+      repo: options.repo,
+      pr: options.pr,
+      pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
+      timeoutMs: ciTimeoutMs,
+    };
+    const ciWatch = await watchCiStatusImpl(ciWatchArgs, { env, ghCommand });
+    result.ciWatchArgs = ciWatchArgs;
+    result.ciWatch = ciWatch;
+    result.watchStatus = ciWatch.status;
+    // success/failure/changed all need authoritative re-detection (follow-up);
+    // a quiet timeout stays a healthy pending wait.
+    result.cycleDisposition = ciWatch.status === "timeout" ? "pending" : "needs_followup";
+    result.terminal = false;
+    result.contractTrace = buildWatchCycleContractTrace({
+      handoff,
+      watchTimeoutPolicy: result.watchTimeoutPolicy ?? null,
+      cycleDisposition: result.cycleDisposition,
+      ciWatchArgs,
+      ciWatchStatus: ciWatch.status,
+    });
+    return result;
+  }
   if (handoff.action !== "watch") {
     result.contractTrace = buildWatchCycleContractTrace({
       handoff,

package/scripts/projects/add-queue-item.mjs

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { runChild as _runChild } from "../_cli-primitives.mjs";
+import { parseArgs } from "node:util";
 
-const USAGE = `Usage: dev-loops project add --repo <owner/name> --project <number|id> --item <number>
+const USAGE = `Usage: dev-loops queue add --repo <owner/name> --project <number|id> --item <number>
+       dev-loops project add … (back-compat alias for "queue add")
 
 Add an existing issue or PR to a GitHub Projects V2 board.
 
@@ -10,7 +12,8 @@ Options:
   --repo <owner/name>         Required. Repository containing the issue/PR.
   --project <number|id>       Required. Project number (integer) or node ID.
   --item <number>             Required. Issue or PR number to add.
-  --status <name>             Initial Status column (default: "Backlog").
+  --column <name>             Initial Status column (default: "Backlog").
+  --status <name>             Back-compat alias for --column.
   --help, -h                  Show this help.
 
 Output (stdout):
@@ -23,52 +26,75 @@ Exit codes:
   3 — project, field, column, or issue/PR not found
 `.trim();
 
-const VALID_ARGS = new Set(["--repo", "--project", "--item", "--status", "--help", "-h"]);
+function parseCliArgs(argv) {
+  const parseError = (message) => Object.assign(new Error(message), { usage: USAGE });
+  const requireValue = (token, message) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0 || v.startsWith("-")) {
+      throw parseError(message);
+    }
+    return v;
+  };
 
-function parseArgs(argv) {
   const args = {};
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (!VALID_ARGS.has(arg) && arg.startsWith("-")) {
-      throw Object.assign(
-        new Error(`Unknown flag: ${arg}`),
-        { code: "INVALID_ARGS", usage: USAGE },
-      );
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      repo: { type: "string" },
+      project: { type: "string" },
+      item: { type: "string" },
+      column: { type: "string" },
+      status: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw Object.assign(new Error(`Unexpected argument: ${token.value}`), { code: "INVALID_ARGS", usage: USAGE });
     }
-    if (arg === "--repo") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(new Error("--repo requires a value (owner/name)"), { code: "INVALID_REPO" });
-      }
-      args.repo = argv[++i];
-    } else if (arg === "--project") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(new Error("--project requires a value (number or node ID)"), { code: "INVALID_PROJECT" });
-      }
-      args.project = argv[++i];
-    } else if (arg === "--item") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(new Error("--item requires a value (number)"), { code: "INVALID_ITEM" });
-      }
-      const val = Number(argv[++i]);
-      if (!Number.isInteger(val) || val < 1) {
-        throw Object.assign(
-          new Error(`--item must be a positive integer, got "${argv[i]}"`),
-          { code: "INVALID_ITEM" },
-        );
-      }
-      args.item = val;
-    } else if (arg === "--status") {
-      if (i + 1 >= argv.length || argv[i + 1].startsWith("-")) {
-        throw Object.assign(new Error("--status requires a value"), { code: "INVALID_STATUS" });
+    if (token.kind !== "option") {
+      continue;
+    }
+    switch (token.name) {
+      case "help":
+        if (token.value !== undefined) {
+          throw Object.assign(new Error(`Unknown flag: ${token.rawName}=${token.value}`), { code: "INVALID_ARGS", usage: USAGE });
+        }
+        args.help = true;
+        break;
+      case "repo":
+        args.repo = requireValue(token, "--repo requires a value (owner/name)");
+        break;
+      case "project":
+        args.project = requireValue(token, "--project requires a value (number or node ID)");
+        break;
+      case "item": {
+        const raw = requireValue(token, "--item requires a value (number)");
+        const val = Number(raw);
+        if (!Number.isInteger(val) || val < 1) {
+          throw Object.assign(
+            new Error(`--item must be a positive integer, got "${raw}"`),
+            { code: "INVALID_ITEM" },
+          );
+        }
+        args.item = val;
+        break;
       }
-      args.status = argv[++i];
-    } else if (arg === "--help" || arg === "-h") {
-      args.help = true;
-    } else {
-      throw Object.assign(
-        new Error(`Unexpected argument: ${arg}`),
-        { code: "INVALID_ARGS", usage: USAGE },
-      );
+      case "column":
+        args.column = requireValue(token, "--column requires a value");
+        break;
+      case "status":
+        // Back-compat alias for --column (issue #912). Kept separate so a
+        // conflicting `--column X --status Y` is rejected rather than silently
+        // resolved by argv order.
+        args.status = requireValue(token, "--status requires a value");
+        break;
+      default:
+        throw Object.assign(new Error(`Unknown flag: ${token.rawName}`), { code: "INVALID_ARGS", usage: USAGE });
     }
   }
   return args;
@@ -358,9 +384,15 @@ async function main(args, { env = process.env, runChild } = {}) {
   if (!Number.isInteger(itemNumber) || itemNumber < 1) {
     throw Object.assign(new Error("--item is required and must be a positive integer"), { code: "INVALID_ITEM" });
   }
-  const targetStatus = (args.status ?? "Backlog").trim();
+  if (args.column != null && args.status != null && args.column.trim() !== args.status.trim()) {
+    throw Object.assign(
+      new Error(`Conflicting --column ("${args.column}") and --status ("${args.status}") — pass only one (prefer --column).`),
+      { code: "INVALID_ARGS", usage: USAGE },
+    );
+  }
+  const targetStatus = (args.column ?? args.status ?? "Backlog").trim();
   if (!targetStatus) {
-    throw Object.assign(new Error("--status must not be empty"), { code: "INVALID_STATUS" });
+    throw Object.assign(new Error("--column must not be empty"), { code: "INVALID_STATUS" });
   }
 
   // 1. Resolve owner
@@ -499,7 +531,7 @@ async function main(args, { env = process.env, runChild } = {}) {
 async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env } = {}) {
   let args;
   try {
-    args = parseArgs(argv);
+    args = parseCliArgs(argv);
   } catch (err) {
     stderr.write(`${formatCliError(err)}\n`);
     process.exitCode = 1;
@@ -525,4 +557,4 @@ if (isDirectCliRun(import.meta.url)) {
   });
 }
 
-export { main };
+export { main, parseCliArgs };