dev-loops 0.5.0 → 0.7.1

package/scripts/github/list-issues.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import { requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
+
+const STATES = new Set(["open", "closed", "all"]);
+
+const USAGE = `Usage: list-issues.mjs --repo <owner/name> [--state <open|closed|all>] [--label <l>] [--limit <n>]
+List/filter repository issues. Thin wrapper over \`gh issue list\` — use this instead
+of an agent-level raw \`gh issue list\` so the loop's internal-tooling record stays
+clean (#993). The queue tool lists the project board, not arbitrary issue queries;
+this fills that gap (siblings: comment-issue.mjs, fetch-ci-logs.mjs).
+Required:
+  --repo <owner/name>           Repository slug (e.g. owner/repo)
+Optional:
+  --state <open|closed|all>     Issue state filter (default open)
+  --label <l>                   Filter by label (repeatable; AND-combined by gh)
+  --limit <n>                   Return at most <n> issues (default 30)
+Output (stdout, JSON):
+  { "ok": true, "issues": [{ "number": 17, "title": "...", "state": "open", "labels": ["bug"] }, ...] }
+Error output (stderr, JSON):
+  { "ok": false, "error": "...", "usage"?: "..." }
+${JQ_OUTPUT_USAGE}
+Exit codes:
+  0  Success
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
+const parseError = buildParseError(USAGE);
+
+export function parseListIssuesCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      state: { type: "string" },
+      label: { type: "string", multiple: true },
+      limit: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = {
+    help: false,
+    repo: undefined,
+    state: "open",
+    labels: [],
+    limit: 30,
+    jq: undefined,
+    silent: false,
+  };
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
+      options.help = true;
+      return options;
+    }
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
+      continue;
+    }
+    if (token.name === "state") {
+      const state = requireTokenValue(token, parseError).trim().toLowerCase();
+      if (!STATES.has(state)) {
+        throw parseError("--state must be one of: open, closed, all");
+      }
+      options.state = state;
+      continue;
+    }
+    if (token.name === "label") {
+      const label = requireTokenValue(token, parseError).trim();
+      if (label.length === 0) {
+        throw parseError("--label must be a non-empty string");
+      }
+      options.labels.push(label);
+      continue;
+    }
+    if (token.name === "limit") {
+      const raw = requireTokenValue(token, parseError);
+      const value = Number(raw);
+      if (!Number.isInteger(value) || value < 1) {
+        throw parseError(`--limit must be a positive integer, got "${raw}"`);
+      }
+      options.limit = value;
+      continue;
+    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  if (options.repo === undefined) {
+    throw parseError("Listing issues requires --repo <owner/name>");
+  }
+  try {
+    parseRepoSlug(options.repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return options;
+}
+
+// Returns a well-typed issue, or null if the gh entry is missing/invalid in any
+// required field. Callers filter the nulls so the emitted shape stays
+// well-typed (documented output) and --jq filters never hit null number/title/state.
+function normalizeIssue(raw) {
+  if (!Number.isInteger(raw?.number) || typeof raw?.title !== "string" || typeof raw?.state !== "string") {
+    return null;
+  }
+  return {
+    number: raw.number,
+    title: raw.title,
+    // gh reports issue state UPPERCASE (OPEN/CLOSED); normalize to lowercase to
+    // match the --state flag vocabulary.
+    state: raw.state.toLowerCase(),
+    labels: Array.isArray(raw?.labels)
+      ? raw.labels.map((l) => (typeof l?.name === "string" ? l.name : null)).filter((n) => n !== null)
+      : [],
+  };
+}
+
+export async function listIssues(options, { env = process.env, ghCommand = "gh", run = runChild } = {}) {
+  const args = [
+    "issue",
+    "list",
+    "--repo",
+    options.repo,
+    "--state",
+    options.state,
+    "--limit",
+    String(options.limit),
+    "--json",
+    "number,title,state,labels",
+  ];
+  for (const label of options.labels) {
+    args.push("--label", label);
+  }
+  const result = await run(ghCommand, args, env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh issue list failed: ${detail}`);
+  }
+  const payload = parseJsonText(result.stdout, { label: "gh issue list" });
+  if (!Array.isArray(payload)) {
+    throw new Error("gh issue list did not return a JSON array");
+  }
+  return { ok: true, issues: payload.map(normalizeIssue).filter((issue) => issue !== null) };
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh", run = runChild } = {},
+) {
+  let options;
+  try {
+    options = parseListIssuesCliArgs(argv);
+  } catch (error) {
+    stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  let result;
+  try {
+    result = await listIssues(options, { env, ghCommand, run });
+  } catch (error) {
+    stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })}\n`);
+    return 1;
+  }
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().then((code) => { process.exitCode = code; });
+}

package/scripts/github/manage-sub-issues.mjs

@@ -3,6 +3,7 @@ import { parseArgs } from "node:util";
 import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { parsePositiveInteger, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage: manage-sub-issues.mjs <command> --repo <owner/name> --issue <number> [options]
 Deterministic helper for reading, linking, ordering, and verifying GitHub sub-issue trees.
 Commands:
@@ -37,7 +38,8 @@ Error output (stderr, JSON):
   Argument/usage errors:
     { "ok": false, "error": "...", "usage": "..." }
   gh/runtime failures:
-    { "ok": false, "error": "..." }`.trim();
+    { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}`.trim();
 const parseError = buildParseError(USAGE);
 function parseIssueList(value) {
   if (typeof value !== "string" || value.trim().length === 0) {
@@ -87,6 +89,7 @@ export function parseManageSubIssuesCliArgs(argv) {
       order: { type: "string" },
       expected: { type: "string" },
       ordered: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -127,6 +130,7 @@ export function parseManageSubIssuesCliArgs(argv) {
       options.ordered = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.issue === undefined) {
@@ -224,15 +228,33 @@ function normalizeSubIssue(raw) {
   return { id, number, title, state };
 }
 
+function extractEndpoint(args) {
+  return args.find((a) => typeof a === "string" && a.startsWith("repos/")) ?? "unknown endpoint";
+}
+function extractHttpStatus(output) {
+  const match = /^HTTP\/\S+\s+(\d{3})/m.exec(output ?? "");
+  return match ? match[1] : null;
+}
 /**
  * Call gh api with optional JSON parsing.
  * @param {boolean} [expectJson=true] - When false, skip JSON parsing (for empty-body responses like PATCH reorder).
  */
 async function ghApi(ghCommand, args, env, expectJson = true) {
-  const result = await runChild(ghCommand, ["api", ...args], env);
+  // Non-JSON calls (POST/PATCH with empty bodies) pass -i so a non-2xx response
+  // still surfaces its HTTP status even when the body is empty. JSON calls are
+  // left untouched since -i would break body parsing.
+  const captureStatus = !expectJson;
+  const apiArgs = captureStatus ? ["-i", ...args] : args;
+  const result = await runChild(ghCommand, ["api", ...apiArgs], env);
   if (result.code !== 0) {
-    const detail = result.stderr.trim() || `exit code ${result.code}`;
-    throw new Error(`gh api command failed: ${detail}`);
+    const endpoint = extractEndpoint(args);
+    const status = captureStatus ? extractHttpStatus(result.stdout) : null;
+    // "empty response body" only makes sense for the -i (captureStatus) path;
+    // for JSON/GET calls an empty stderr means fall back to the exit code.
+    const detail = result.stderr.trim()
+      || (captureStatus ? "empty response body" : `exit code ${result.code}`);
+    const statusPart = status ? ` (HTTP ${status})` : "";
+    throw new Error(`gh api command failed${statusPart} for ${endpoint}: ${detail}`);
   }
   if (!expectJson) {
     return null;
@@ -297,12 +319,26 @@ export async function runReorder({ repo, issue, order }, { env = process.env, gh
     }
   }
   const reorderPath = buildSubIssueReorderPath(owner, name, issue);
-  let afterId = 0;
-  for (const n of order) {
-    const subIssueId = idByNumber.get(n);
+  // GitHub's priority endpoint rejects after_id=0 (the "no predecessor" cursor)
+  // with an HTTP 500. To place the first requested item at the head, move it
+  // before the current head instead — or skip the call entirely if it's
+  // already there.
+  const currentHeadId = subIssues[0]?.id;
+  let afterId;
+  for (let index = 0; index < order.length; index += 1) {
+    const subIssueId = idByNumber.get(order[index]);
+    if (index === 0) {
+      afterId = subIssueId;
+      if (subIssueId === currentHeadId) {
+        continue; // already at the head; no call needed
+      }
+      const fieldArgs = ["-F", `sub_issue_id=${subIssueId}`, "-F", `before_id=${currentHeadId}`];
+      await ghApi(ghCommand, ["-X", "PATCH", reorderPath, ...fieldArgs], env, false);
+      continue;
+    }
     const fieldArgs = ["-F", `sub_issue_id=${subIssueId}`, "-F", `after_id=${afterId}`];
-    await ghApi(ghCommand, ["-X", "PATCH", reorderPath, ...fieldArgs], env, false);
     afterId = subIssueId;
+    await ghApi(ghCommand, ["-X", "PATCH", reorderPath, ...fieldArgs], env, false);
   }
   return {
     ok: true,
@@ -387,7 +423,7 @@ export async function runVerify(
 }
 export async function runCli(
   argv = process.argv.slice(2),
-  { stdout = process.stdout, env = process.env, ghCommand = "gh" } = {},
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh" } = {},
 ) {
   const options = parseManageSubIssuesCliArgs(argv);
   if (options.help) {
@@ -405,7 +441,7 @@ export async function runCli(
   } else if (command === "verify") {
     result = await runVerify({ repo, issue, expected, ordered }, { env, ghCommand });
   }
-  stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 if (isDirectCliRun(import.meta.url)) {
   runCli().catch((error) => {

package/scripts/github/offer-human-handoff.mjs

@@ -4,6 +4,7 @@ import { parsePrNumber, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { loadDevLoopConfig } from "@dev-loops/core/config";
 import { resolveHandoffCandidates } from "./resolve-handoff-candidates.mjs";
+import { JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage: offer-human-handoff.mjs --repo <owner/name> --pr <number> [--assign <login>...] [--request-review <login>...] [--changed-files <csv>] [--pr-author <login>]
 Human-handoff offer at the pre-approval / merge-handoff boundary (#920, Request B
@@ -28,9 +29,11 @@ Optional:
 Output (stdout, JSON):
   Offer mode:  { "ok": true, "mode": "offer", "enabled", "candidates": [...], ... }
   Apply mode:  { "ok": true, "mode": "apply", "assigned": [...], "requestedReview": [...] }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success (including disabled no-op offer)
-  1  Argument error or gh failure`.trim();
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -70,6 +73,8 @@ export function parseOfferCliArgs(argv) {
       continue;
     }
     if (token === "--pr-author") { options.prAuthor = nextValue(args, ++i, "--pr-author").trim().replace(/^@/, ""); continue; }
+    if (token === "--jq") { options.jq = nextValue(args, ++i, "--jq"); continue; }
+    if (token === "--silent" || token === "-s") { options.silent = true; continue; }
     throw parseError(`Unknown argument: ${token}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
@@ -123,8 +128,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
         { repo: options.repo, pr: options.pr, assign: options.assign, requestReview: options.requestReview },
         { run, ghCommand },
       );
-      process.stdout.write(`${JSON.stringify(applied)}\n`);
-      return 0;
+      return emitResult(applied, { jq: options.jq, silent: options.silent });
     } catch (error) {
       process.stderr.write(`${formatCliError(error)}\n`);
       return 1;
@@ -138,8 +142,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
     { repo: options.repo, pr: options.pr, changedFiles: options.changedFiles, prAuthor: options.prAuthor ?? null },
     { ...deps, config, repoRoot, run, ghCommand },
   );
-  process.stdout.write(`${JSON.stringify({ ...offer, mode: "offer" })}\n`);
-  return 0;
+  return emitResult({ ...offer, mode: "offer" }, { jq: options.jq, silent: options.silent });
 }
 
 if (isDirectCliRun(import.meta.url)) {

package/scripts/github/post-gate-findings.mjs

@@ -3,6 +3,7 @@ import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { loadDevLoopConfig, resolveGatePostFindingsComments } from "@dev-loops/core/config";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage: post-gate-findings.mjs --repo <owner/name> --pr <number> --gate <draft_gate|pre_approval_gate> --head-sha <sha> --findings <json>
 Post (or idempotently update) a visible, marker-tagged PR issue comment that lists the
@@ -23,9 +24,12 @@ Required:
                                    ([{severity, angle, summary, disposition?, files?}])
 Output (stdout, JSON):
   { "ok": true, "action": "created"|"updated"|"noop"|"skipped", ... }
+
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error or gh failure`.trim();
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
 
 const VALID_SEVERITIES = new Set(["must-fix", "worth-fixing-now", "defer"]);
 // Severity ordering for grouped rendering (most-blocking first).
@@ -142,6 +146,14 @@ export function parsePostGateFindingsCliArgs(argv) {
       options.findings = requireOptionValue(args, "--findings", parseError);
       continue;
     }
+    if (token === "--jq") {
+      options.jq = requireOptionValue(args, "--jq", parseError);
+      continue;
+    }
+    if (token === "--silent" || token === "-s") {
+      options.silent = true;
+      continue;
+    }
     throw parseError(`Unknown argument: ${token}`);
   }
   const missing = ["repo", "pr", "gate", "headSha", "findings"]
@@ -380,7 +392,7 @@ async function main() {
   }
   try {
     const result = await postGateFindings(options);
-    process.stdout.write(`${JSON.stringify(result)}\n`);
+    process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent });
   } catch (error) {
     process.stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })}\n`);
     process.exitCode = 1;

package/scripts/github/probe-ci-status.mjs

@@ -4,6 +4,7 @@ import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helper
 import { parseArgs } from "node:util";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 import {
   summarizeHeadScopedCheckRunsSignal,
   normalizeHeadScopedCommitStatus,
@@ -53,9 +54,11 @@ No-checks rule (grace, race-safe):
 Diagnostic output (stderr):
   { "ok": true, "type": "watch_heartbeat", "elapsedMs": N, "totalBudgetMs": N, "poll": N, "maxPolls": N }
   { "ok": false, "error": "...", "usage"?: "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error or gh failure`.trim();
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 
 export function parseCiWatchCliArgs(argv) {
@@ -67,6 +70,7 @@ export function parseCiWatchCliArgs(argv) {
       pr: { type: "string" },
       "timeout-ms": { type: "string" },
       "poll-interval-ms": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -106,6 +110,7 @@ export function parseCiWatchCliArgs(argv) {
       options.pollIntervalMs = parsePositiveMs(requireTokenValue(token, parseError), "--poll-interval-ms");
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
@@ -447,6 +452,7 @@ export async function runCli(
   argv = process.argv.slice(2),
   {
     stdout = process.stdout,
+    stderr = process.stderr,
     env = process.env,
     ghCommand = "gh",
   } = {},
@@ -457,7 +463,7 @@ export async function runCli(
     return;
   }
   const result = await watchCiStatus(options, { env, ghCommand });
-  stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 
 if (isDirectCliRun(import.meta.url)) {

package/scripts/github/probe-copilot-review.mjs

@@ -2,8 +2,8 @@
 import { setTimeout as delay } from "node:timers/promises";
 import { buildParseError, formatCliError, isCopilotLogin, isDirectCliRun, parseJsonText, parseReviewThreads } from "../_core-helpers.mjs";
 import { parseArgs } from "node:util";
-import { parsePositiveInteger, requireTokenValue, runChild } from "../_cli-primitives.mjs";
-import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+import { parsePositiveInteger, parseNonNegativeInteger, requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import {
   DEFAULT_POLL_INTERVAL_MS,
@@ -15,13 +15,18 @@ import {
 const WATCH_HEARTBEAT_MS = 45_000; // 45 seconds
 const REMOVED_FLAGS = new Set([
   "--poll-interval-ms",
-  "--timeout-ms",
 ]);
-const USAGE = `Usage: probe-copilot-review.mjs --repo <owner/name> --pr <number>
+const USAGE = `Usage: probe-copilot-review.mjs --repo <owner/name> --pr <number> [--timeout-ms <n>]
 Poll for fresh Copilot review activity on a GitHub pull request.
 Required:
   --repo <owner/name>           Repository slug (e.g. owner/repo)
   --pr <number>                 Pull request number
+Options:
+  --timeout-ms <n>              Total watch budget in ms (default ${COPILOT_REVIEW_WAIT_TIMEOUT_MS}, i.e. ${COPILOT_REVIEW_WAIT_TIMEOUT_MS / 60_000} min;
+                                0 = single immediate check, no wait — returns "idle" if
+                                no fresh activity). For a quick non-watch thread/state
+                                read without entering the watch loop, pass 0 here or use
+                                'dev-loops gate capture-threads'.
 Output (stdout, JSON):
   { "ok": true, "status": "changed"|"timeout"|"idle", "repo": "...", "pr": N, "attempts": N,
     "newComments": [...], "newReviews": [...], "newIssueComments": [...] }
@@ -32,10 +37,14 @@ ${JQ_OUTPUT_USAGE}
 Activity statuses:
   changed    Fresh Copilot review activity found (check newComments/newReviews/newIssueComments)
   timeout    Watch period elapsed with no fresh Copilot activity
-  idle       Zero-timeout single check found no change
+  idle       Zero-timeout (--timeout-ms 0) single check found no change
 Diagnostic output (stderr):
-  Progress/heartbeat (during watch):
+  Progress/heartbeat (during watch, --timeout-ms > 0):
     { "ok": true, "type": "watch_heartbeat", "elapsedMs": N, "totalBudgetMs": N, "poll": N, "maxPolls": N }
+  Heartbeat contract: watch-shaped runs (--timeout-ms > 0) emit watch_heartbeat lines to
+    stderr roughly every 45s as a liveness signal. Agents MUST NOT suppress stderr
+    (e.g. 2>/dev/null) on watch-shaped invocations — suppressing heartbeats makes a
+    legitimate watch look like a stall. Use --timeout-ms 0 for a non-watch single check.
   Argument/usage errors:
     { "ok": false, "error": "...", "usage": "..." }
   gh/runtime failures:
@@ -100,6 +109,7 @@ export function parseWatchCliArgs(argv) {
       help: { type: "boolean", short: "h" },
       repo: { type: "string" },
       pr: { type: "string" },
+      "timeout-ms": { type: "string" },
       concise: { type: "boolean" },
       summary: { type: "boolean" },
       ...JQ_OUTPUT_PARSE_OPTIONS,
@@ -140,18 +150,15 @@ export function parseWatchCliArgs(argv) {
       options.pr = parsePositiveInteger(requireTokenValue(token, parseError), "--pr", parseError);
       continue;
     }
-    if (token.name === "concise" || token.name === "summary") {
-      options.concise = true;
-      continue;
-    }
-    if (token.name === "jq") {
-      options.jq = requireTokenValue(token, parseError);
+    if (token.name === "timeout-ms") {
+      options.timeoutMs = parseNonNegativeInteger(requireTokenValue(token, parseError), "--timeout-ms", parseError);
       continue;
     }
-    if (token.name === "silent") {
-      options.silent = true;
+    if (token.name === "concise" || token.name === "summary") {
+      options.concise = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {

package/scripts/github/ready-for-review.mjs

@@ -5,15 +5,17 @@ import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.m
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { loadDevLoopConfig, resolveGateConfig } from "@dev-loops/core/config";
 import { findBlockingTitleMarkers } from "@dev-loops/core/loop/pr-title-markers";
+import { syncBoardStatus as realSyncBoardStatus, loadStateColumnMap, LOGICAL_COLUMN } from "@dev-loops/core/loop/queue-board-sync";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
-const USAGE = `Usage: ready-for-review.mjs --repo <owner/name> --pr <number>\nWrapper around gh pr ready that enforces gate-evidence validation.`;
+const USAGE = `Usage: ready-for-review.mjs --repo <owner/name> --pr <number>\nWrapper around gh pr ready that enforces gate-evidence validation.\n\n${JQ_OUTPUT_USAGE}`;
 const parseError = buildParseError(USAGE);
-const PR_VIEW_QUERY = `query($owner:String!, $name:String!, $number:Int!) { repository(owner:$owner, name:$name) { pullRequest(number:$number) { id, isDraft, headRefOid, state, mergeStateStatus, title } } }`;
+const PR_VIEW_QUERY = `query($owner:String!, $name:String!, $number:Int!) { repository(owner:$owner, name:$name) { pullRequest(number:$number) { id, isDraft, headRefOid, state, mergeStateStatus, title, closingIssuesReferences(first:10){ nodes{ number } } } } }`;
 
 export function parseReadyForReviewCliArgs(argv) {
   const { tokens } = parseArgs({
     args: [...argv],
-    options: { help: { type: "boolean", short: "h" }, repo: { type: "string" }, pr: { type: "string" } },
+    options: { help: { type: "boolean", short: "h" }, repo: { type: "string" }, pr: { type: "string" }, ...JQ_OUTPUT_PARSE_OPTIONS },
     allowPositionals: true,
     strict: false,
     tokens: true,
@@ -25,6 +27,7 @@ export function parseReadyForReviewCliArgs(argv) {
     if (token.name === "help") { opts.help = true; return opts; }
     if (token.name === "repo") { opts.repo = requireTokenValue(token, parseError).trim(); continue; }
     if (token.name === "pr") { opts.pr = parsePrNumber(requireTokenValue(token, parseError), parseError); continue; }
+    if (matchJqOutputToken(token, opts, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (!opts.repo || opts.pr === undefined) throw parseError("ready-for-review requires --repo and --pr");
@@ -43,7 +46,10 @@ async function fetchPrState({ repo, pr }, { env, ghCommand }) {
   const r = await runGhJson(["api", "graphql", "-f", `query=${PR_VIEW_QUERY}`, "-f", `owner=${owner}`, "-f", `name=${name}`, "-F", `number=${pr}`], { env, ghCommand });
   const d = r?.data?.repository?.pullRequest;
   if (!d) throw new Error(`Could not fetch PR #${pr}`);
-  return { id: d.id, isDraft: d.isDraft === true, headRefOid: typeof d.headRefOid === "string" ? d.headRefOid.trim() : null, state: typeof d.state === "string" ? d.state.trim() : null, mergeStateStatus: typeof d.mergeStateStatus === "string" ? d.mergeStateStatus.trim() : null, title: typeof d.title === "string" ? d.title : null };
+  const closingIssues = (d.closingIssuesReferences?.nodes ?? [])
+    .map((n) => n?.number)
+    .filter((n) => Number.isInteger(n) && n > 0);
+  return { id: d.id, isDraft: d.isDraft === true, headRefOid: typeof d.headRefOid === "string" ? d.headRefOid.trim() : null, state: typeof d.state === "string" ? d.state.trim() : null, mergeStateStatus: typeof d.mergeStateStatus === "string" ? d.mergeStateStatus.trim() : null, title: typeof d.title === "string" ? d.title : null, closingIssues };
 }
 
 async function fetchCiStatus({ repo, pr }, { env, ghCommand }) {
@@ -73,7 +79,7 @@ async function fetchGateEvidence({ repo, pr, headSha }, { env, ghCommand }) {
   return { draftGate: dg, draftGateMarker: dm, currentHeadClean: chc, cleanEvidenceExists: cee, effectiveHeadClean: chc || cphm };
 }
 
-export async function readyForReview(options, { env = process.env, ghCommand = "gh", repoRoot = process.cwd() } = {}) {
+export async function readyForReview(options, { env = process.env, ghCommand = "gh", repoRoot = process.cwd(), syncBoardStatus = realSyncBoardStatus } = {}) {
   const { config } = await loadDevLoopConfig({ repoRoot });
   const draftGateConfig = resolveGateConfig(config, "draft");
   const requireCi = draftGateConfig?.requireCi !== false;
@@ -89,15 +95,27 @@ export async function readyForReview(options, { env = process.env, ghCommand = "
   if (!gate.effectiveHeadClean) { const mv = gate.draftGateMarker?.visible; const mh = gate.draftGateMarker?.headSha; throw new Error(mv && mh ? `PR #${options.pr} draft_gate marker does not match current head ${headSha.slice(0,7)}. Re-run draft gate.` : `PR #${options.pr} draft_gate marker is missing or incomplete on current head ${headSha.slice(0,7)}. Re-run draft gate.`); }
   const readyResult = await runChild(ghCommand, ["pr", "ready", String(options.pr), "--repo", options.repo], env);
   if (readyResult.code !== 0) throw new Error(`gh pr ready failed`);
-  return { ok: true, action: "marked_ready", repo: options.repo, pr: options.pr, headSha, draftGateSatisfied: gate.effectiveHeadClean };
+  // #1069: couple the In-Progress board move to the ready transition. Best-effort
+  // and NON-FATAL — a board failure must NEVER block or fail marking ready.
+  let boardSync;
+  try {
+    const inProgressColumn = loadStateColumnMap(repoRoot).columnNames[LOGICAL_COLUMN.IN_PROGRESS];
+    const targets = prState.closingIssues.length > 0 ? prState.closingIssues : [options.pr];
+    boardSync = [];
+    for (const target of targets) {
+      boardSync.push(await syncBoardStatus(options.repo, repoRoot, target, inProgressColumn, env, {}));
+    }
+  } catch (err) {
+    boardSync = [{ ok: true, skipped: true, reason: err?.message ?? "board sync failed" }];
+  }
+  return { ok: true, action: "marked_ready", repo: options.repo, pr: options.pr, headSha, draftGateSatisfied: gate.effectiveHeadClean, boardSync };
 }
 
 export async function main(argv = process.argv.slice(2), runtime = {}) {
   const options = parseReadyForReviewCliArgs(argv);
   if (options.help) { process.stdout.write(`${USAGE}\n`); return 0; }
   const result = await readyForReview(options, runtime);
-  process.stdout.write(`${JSON.stringify(result)}\n`);
-  return 0;
+  return emitResult(result, { jq: options.jq, silent: options.silent });
 }
 
 if (isDirectCliRun(import.meta.url)) {

package/scripts/github/reconcile-draft-gate.mjs

@@ -6,6 +6,7 @@ import { loadDevLoopConfig, resolveGateConfig } from "@dev-loops/core/config";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { detectCheckpointEvidence } from "./detect-checkpoint-evidence.mjs";
 import { upsertCheckpointVerdict } from "./upsert-checkpoint-verdict.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage: reconcile-draft-gate.mjs --repo <owner/name> --pr <number>
 Optional/manual recovery tool for an already non-draft PR when you want to
 retroactively record clean \`draft_gate\` evidence.
@@ -32,14 +33,16 @@ Output (stdout, JSON):
 Error output (stderr, JSON):
   { "ok": false, "error": "...", "usage": "..." }
   { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success — PR was reconciled and gate evidence posted
-  1  Argument error, gh failure, or unrecoverable state`.trim();
+  1  Argument error, gh failure, or unrecoverable state
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 export function parseReconcileDraftGateCliArgs(argv) {
   const { tokens } = parseArgs({
     args: [...argv],
-    options: { help: { type: "boolean", short: "h" }, repo: { type: "string" }, pr: { type: "string" } },
+    options: { help: { type: "boolean", short: "h" }, repo: { type: "string" }, pr: { type: "string" }, ...JQ_OUTPUT_PARSE_OPTIONS },
     allowPositionals: true,
     strict: false,
     tokens: true,
@@ -68,6 +71,7 @@ export function parseReconcileDraftGateCliArgs(argv) {
       options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   const missing = ["repo", "pr"].filter((key) => options[key] === undefined);
@@ -327,7 +331,7 @@ async function main() {
   }
   try {
     const result = await reconcileDraftGate(options);
-    process.stdout.write(`${JSON.stringify(result)}\n`);
+    process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent });
   } catch (error) {
     process.stderr.write(
       `${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })}\n`