dev-loops 0.2.7 → 0.3.0

package/scripts/loop/detect-change-scope.mjs

@@ -1,12 +1,9 @@
 #!/usr/bin/env node
 import { execFileSync } from "node:child_process";
 import process from "node:process";
-function parseArgs() {
-  const args = process.argv.slice(2);
-  const opts = { base: null, head: null };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--help" || args[i] === "-h") {
-      process.stdout.write(`Usage: detect-change-scope.mjs [--base <ref>] [--head <ref>]
+import { parseArgs } from "node:util";
+
+const USAGE = `Usage: detect-change-scope.mjs [--base <ref>] [--head <ref>]
 Detect change scope from git diff for light-mode eligibility.
 Options:
   --base <ref>   Override base ref (default: HEAD~1)
@@ -15,11 +12,39 @@ Options:
 Exit codes:
   0   Success
   1   Error
-`);
-      process.exit(0);
+`;
+
+function parseCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      base: { type: "string" },
+      head: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  const opts = { base: null, head: null };
+  for (const token of tokens) {
+    if (token.kind === "option") {
+      if (token.name === "help") {
+        if (token.value !== undefined) {
+          throw new Error(`unknown argument: ${token.rawName}=${token.value}`);
+        }
+        process.stdout.write(USAGE);
+        process.exit(0);
+      }
+      if (token.name === "base") {
+        opts.base = token.value ?? null;
+        continue;
+      }
+      if (token.name === "head") {
+        opts.head = token.value ?? null;
+      }
     }
-    if (args[i] === "--base" && i + 1 < args.length) opts.base = args[++i];
-    else if (args[i] === "--head" && i + 1 < args.length) opts.head = args[++i];
   }
   return opts;
 }
@@ -64,7 +89,7 @@ function isEligibleForLightMode(scope, threshold) {
   return scope.filesChanged <= threshold.maxFiles && scope.linesChanged <= threshold.maxLines;
 }
 async function main() {
-  const opts = parseArgs();
+  const opts = parseCliArgs(process.argv.slice(2));
   const scope = detectScope(opts);
   let threshold = { maxFiles: 3, maxLines: 200 };
   let eligible = false;

package/scripts/loop/detect-pr-gate-coordination-state.mjs

@@ -6,13 +6,13 @@ import {
   formatCliError,
   isCopilotLogin,
   isDirectCliRun,
-  normalizeTimestamp,
   parseJsonText,
   parseReviewThreads,
+  resolveDraftGateRoundResetMs,
   summarizeCopilotReviews,
 } from "../_core-helpers.mjs";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
-import { loadDevLoopConfig, resolveGateConfig, resolveRefinementConfig, resolveWorkflowConfig } from "@dev-loops/core/config";
+import { loadDevLoopConfig, resolveGateConfig, resolveRefinement, resolveRefinementConfig, resolveWorkflowConfig } from "@dev-loops/core/config";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { buildSnapshotFromPrFacts, interpretLoopState, summarizeLoopInterpretation } from "@dev-loops/core/loop/copilot-loop-state";
 import { evaluatePrGateCoordination, PR_CHECKPOINT, PR_CHECKPOINT_ACTION } from "@dev-loops/core/loop/pr-gate-coordination";
@@ -303,18 +303,13 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
   const gateEvidence = await detectCheckpointEvidence(options, runtime);
   // When draft gate was re-passed on a different head, use its timestamp
   // to reset the Copilot round count — only reviews after the re-pass count.
-  // Use prefix matching for the head SHA comparison so shortened SHAs (7+)
-  // from gate comments match the full headRefOid.
-  const draftGateHeadSha = gateEvidence.draftGate?.headSha;
-  const draftGateOnCurrentHead = typeof draftGateHeadSha === "string"
-    && typeof currentHeadSha === "string"
-    && currentHeadSha.startsWith(draftGateHeadSha);
-  const draftGateResetAtMs = gateEvidence.draftGate?.verdict === "clean"
-    && typeof draftGateHeadSha === "string"
-    && !draftGateOnCurrentHead
-    && typeof gateEvidence.draftGate?.updatedAt === "string"
-    ? normalizeTimestamp(gateEvidence.draftGate.updatedAt)
-    : null;
+  // Shared with request-copilot-review so both scripts compute the same
+  // completed round count / cap (#896). Prefix matching for the head SHA lets
+  // shortened SHAs (7+) from gate comments match the full headRefOid.
+  const draftGateResetAtMs = resolveDraftGateRoundResetMs({
+    draftGate: gateEvidence.draftGate,
+    currentHeadSha,
+  });
   const reviewSummary = summarizeCopilotReviews(prData?.reviews, { headSha: currentHeadSha, draftGateResetAtMs });
   const reviewRequestStatus = requestedReviewers.requested
     ? "requested"
@@ -338,8 +333,19 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
   if (gateEvidence.currentHeadSha !== currentHeadSha) {
     throw new Error(`PR head changed while loading gate coordination facts for ${options.repo}#${options.pr}; refuse to evaluate mixed-head gate state.`);
   }
-  const interpretation = interpretLoopState(snapshot);
-  const disposition = summarizeLoopInterpretation(interpretation);
+  // Resolve the refinement config (round cap, low-signal heuristic) and feed it to
+  // the interpreter. Without it, the interpreter cannot see maxCopilotRounds and so
+  // never resolves ROUND_CAP_CLEAN_FALLBACK — a post-cap clean head would fall to
+  // READY_TO_REREQUEST_REVIEW, dead-ending the loop at the round cap (#896). This
+  // keeps the gate-coordination interpretation consistent with the standalone
+  // detect-copilot-loop-state path and with request-copilot-review's cap logic.
+  const interpreterRepoRoot = runtime.repoRoot ?? process.cwd();
+  const interpreterConfigResult = await loadDevLoopConfig({ repoRoot: interpreterRepoRoot });
+  const interpreterRefinementConfig = (Array.isArray(interpreterConfigResult.errors) && interpreterConfigResult.errors.length > 0)
+    ? resolveRefinement({ version: 1 })
+    : resolveRefinement(interpreterConfigResult.config ?? { version: 1 });
+  const interpretation = interpretLoopState(snapshot, interpreterRefinementConfig);
+  const disposition = summarizeLoopInterpretation(interpretation, interpreterRefinementConfig);
   const mergeStateStatus = typeof prData?.mergeStateStatus === "string" && prData.mergeStateStatus.trim().length > 0
     ? prData.mergeStateStatus.trim().toUpperCase()
     : null;
@@ -362,6 +368,7 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
     interpretation,
     disposition,
     refinementArtifact,
+    refinementConfig: interpreterRefinementConfig,
   };
 }
 
@@ -429,9 +436,13 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     && typeof (context.snapshot?.copilotReviewRoundCount) === "number"
     && context.snapshot?.copilotReviewRoundCount >= maxCopilotRounds;
   const sameHeadCleanConverged = context.interpretation?.sameHeadCleanConverged ?? false;
+  // Round-cap clean fallback (#896): the interpreter resolved a clean post-cap head
+  // (zero unresolved threads + green CI) that Copilot will not re-review. The formal
+  // request guard must not fire here — pre_approval_gate reviews the post-cap head.
+  const roundCapCleanFallback = context.interpretation?.roundCapCleanEligible ?? false;
   const copilotReviewEverFormallyRequested = copilotReviewRequestStatus === "none"
     && guardBoundaries.has(result.gateBoundary)
-    && !(roundCapReached && sameHeadCleanConverged)
+    && !(roundCapReached && (sameHeadCleanConverged || roundCapCleanFallback))
     ? await fetchCopilotEverFormallyRequested(
         { repo: context.repo, pr: context.pr },
         runtime,
@@ -442,7 +453,8 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     copilotReviewRoundCount: context.snapshot?.copilotReviewRoundCount ?? 0,
     copilotReviewEverFormallyRequested,
     maxCopilotRounds,
-    sameHeadCleanConverged: context.interpretation?.sameHeadCleanConverged ?? false,
+    sameHeadCleanConverged,
+    roundCapCleanFallback,
     gateBoundary: result.gateBoundary,
   })) {
     result.gateBoundary = PR_CHECKPOINT.POST_DRAFT_EXTERNAL_REVIEW;

package/scripts/loop/detect-tracker-first-loop-state.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import process from "node:process";
 import { execFileSync } from "node:child_process";
+import { parseArgs } from "node:util";
 import { interpretTrackerLoopState } from "@dev-loops/core/loop/tracker-first-loop-state";
+
 function showHelp() {
   process.stdout.write(`Usage: detect-tracker-first-loop-state.mjs --repo <owner/name> --issue <number>
 Detect tracker-first loop state for a GitHub issue.
@@ -15,40 +17,65 @@ Exit codes:
 `);
   process.exit(0);
 }
-function parseArgs() {
-  const args = process.argv.slice(2);
+
+function parseCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      repo: { type: "string" },
+      issue: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
   const opts = { repo: null, issue: null };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--help" || args[i] === "-h") {
-      showHelp();
+  for (const token of tokens) {
+    if (token.kind === "option") {
+      if (token.name === "help") {
+        if (token.value !== undefined) {
+          throw new Error(`unknown argument: ${token.rawName}=${token.value}`);
+        }
+        showHelp();
+      }
+      if (token.name === "repo") {
+        opts.repo = token.value ?? null;
+        continue;
+      }
+      if (token.name === "issue") {
+        opts.issue = token.value ?? null;
+      }
     }
-    if (args[i] === "--repo" && i + 1 < args.length) opts.repo = args[++i];
-    else if (args[i] === "--issue" && i + 1 < args.length) opts.issue = args[++i];
   }
   return opts;
 }
+
 async function main() {
-  const opts = parseArgs();
-  if (!opts.repo || !opts.issue) {
+  const rawOpts = parseCliArgs(process.argv.slice(2));
+  if (!rawOpts.repo || !rawOpts.issue) {
     process.stderr.write(
       JSON.stringify({ ok: false, error: "--repo and --issue required" }) + "\n"
     );
     process.exitCode = 1;
     return;
   }
+  const repo = rawOpts.repo;
+  const issue = rawOpts.issue;
   let rawState = "";
   let prContext = null;
   try {
     const issueJson = execFileSync(
       "gh",
-      ["issue", "view", String(opts.issue), "--repo", opts.repo, "--json", "state,title", "--jq", ".state"],
+      ["issue", "view", String(issue), "--repo", repo, "--json", "state,title", "--jq", ".state"],
       { encoding: "utf8" }
     ).trim();
     rawState = issueJson;
     try {
       const prJson = execFileSync(
         "gh",
-        ["pr", "list", "--repo", opts.repo, "--search", `${opts.issue} in:body`, "--state", "open", "--json", "number,state,headRefName", "--jq", ".[0]"],
+        ["pr", "list", "--repo", repo, "--search", `${issue} in:body`, "--state", "open", "--json", "number,state,headRefName", "--jq", ".[0]"],
         { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] }
       ).trim();
       if (prJson) prContext = JSON.parse(prJson);

package/scripts/loop/run-queue.mjs

@@ -14,9 +14,11 @@
  */
 
 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";
 
 const REPO_ROOT = fileURLToPath(new URL("../..", import.meta.url));
@@ -27,7 +29,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 +39,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 +98,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 +112,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;
   }

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

@@ -1,6 +1,7 @@
 #!/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>
 
@@ -23,52 +24,68 @@ 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" },
+      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 "status":
+        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;
@@ -499,7 +516,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;