dev-loops 0.6.0 → 0.7.2

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

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { readFile } from "node:fs/promises";
 import path from "node:path";
 import {
   buildParseError,
@@ -12,15 +11,18 @@ import {
   summarizeCopilotReviews,
 } from "../_core-helpers.mjs";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
-import { loadDevLoopConfig, resolveGateConfig, resolveRefinement, resolveRefinementConfig, resolveWorkflowConfig } from "@dev-loops/core/config";
+import { loadDevLoopConfig, resolveEffectiveCopilotRoundCap, 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 { buildSnapshotFromPrFacts, interpretLoopState, isCopilotRoundCapReached, summarizeLoopInterpretation } from "@dev-loops/core/loop/copilot-loop-state";
 import { evaluatePrGateCoordination, PR_CHECKPOINT, PR_CHECKPOINT_ACTION } from "@dev-loops/core/loop/pr-gate-coordination";
 import { shouldGuardCopilotReviewRequest } from "@dev-loops/core/loop/pr-gate-coordination";
 import { UI_E2E_CHECK_NAMES } from "@dev-loops/core/loop/ui-e2e-scoping";
 import { fetchGithubReviewThreadsPayload } from "../github/capture-review-threads.mjs";
+import { detectPostConvergenceSignificantChange } from "./_post-convergence-change.mjs";
 import { detectCheckpointEvidence } from "../github/detect-checkpoint-evidence.mjs";
+import { resolveRepoRoot } from "./_repo-root-resolver.mjs";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const UNMERGED_GIT_STATUS_CODES = new Set(["DD", "AU", "UD", "UA", "DU", "AA", "UU"]);
 const USAGE = `Usage: detect-pr-gate-coordination-state.mjs --repo <owner/name> --pr <number>
 Determine which PR gate/transition is legal next for a pull request.
@@ -28,6 +30,12 @@ Required:
   --repo <owner/name>   Repository slug (e.g. owner/repo)
   --pr <number>         Pull request number
 Optional:
+  --lightweight   This PR is light-dispatched (#1210): compose the Copilot
+                  round cap with localImplementation.lightMode.maxCopilotRounds
+                  (default 1) via min(lightMode.maxCopilotRounds,
+                  refinement.maxCopilotRounds) instead of using
+                  refinement.maxCopilotRounds alone. refinement.maxCopilotRounds:
+                  0 still disables Copilot rounds even with --lightweight.
 Output (stdout, JSON):
   {
     "ok": true,
@@ -67,15 +75,18 @@ Output (stdout, JSON):
 Error output (stderr, JSON):
   { "ok": false, "error": "...", "usage": "..." }
   { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error or gh/runtime failure`.trim();
+  1  Argument error or gh/runtime failure
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 export function parseDetectPrGateCoordinationCliArgs(argv) {
   const options = {
     help: false,
     repo: undefined,
     pr: undefined,
+    lightweight: false,
   };
   const { tokens } = parseArgs({
     args: [...argv],
@@ -83,6 +94,8 @@ export function parseDetectPrGateCoordinationCliArgs(argv) {
       help: { type: "boolean", short: "h" },
       repo: { type: "string" },
       pr: { type: "string" },
+      lightweight: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -107,6 +120,11 @@ export function parseDetectPrGateCoordinationCliArgs(argv) {
       options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
+    if (token.name === "lightweight") {
+      options.lightweight = true;
+      continue;
+    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {
@@ -221,30 +239,38 @@ export function deriveUiE2ePassed(prData, checkNames = UI_E2E_CHECK_NAMES) {
   return present.every((entry) => {
     const conclusion = String(entry?.conclusion ?? "").toUpperCase();
     const state = String(entry?.state ?? "").toUpperCase();
-    return conclusion === "SUCCESS" || state === "SUCCESS";
+    // SKIPPED = "not applicable to this run" (e.g. viewer-smoke when no viewer files changed) — not a failure.
+    return conclusion === "SUCCESS" || conclusion === "SKIPPED" || state === "SUCCESS" || state === "SKIPPED";
   });
 }
 
-export function resolveLinkedIssueFromPr(prData) {
-  if (!prData || typeof prData !== "object") return null;
+// Ordered, de-duplicated list of ALL closing-referenced issue numbers for a PR.
+// Umbrella PRs legitimately close multiple issues (#1052), so the refinement
+// guard resolves against every one of them, not just a unique single ref.
+export function resolveLinkedIssuesFromPr(prData) {
+  if (!prData || typeof prData !== "object") return [];
+  const dedupe = (nums) => {
+    const seen = new Set();
+    const out = [];
+    for (const n of nums) {
+      if (Number.isInteger(n) && n > 0 && !seen.has(n)) {
+        seen.add(n);
+        out.push(n);
+      }
+    }
+    return out;
+  };
   const closing = Array.isArray(prData.closingIssuesReferences) ? prData.closingIssuesReferences : [];
-  const closingNumbers = closing
-    .map((entry) => Number(entry?.number))
-    .filter((n) => Number.isInteger(n) && n > 0);
-  if (closingNumbers.length === 1) {
-    return closingNumbers[0];
+  const closingNumbers = dedupe(closing.map((entry) => Number(entry?.number)));
+  if (closingNumbers.length > 0) {
+    return closingNumbers;
   }
   const body = typeof prData.body === "string" ? prData.body : "";
-  if (body.length === 0) return null;
+  if (body.length === 0) return [];
   const matches = body.match(/(?:closes|fixes|resolves)\s+#(\d+)/gi) || [];
-  const bodyNumbers = matches
-    .map((m) => Number((/(\d+)/.exec(m) || [])[1]))
-    .filter((n) => Number.isInteger(n) && n > 0);
-  if (bodyNumbers.length === 1) {
-    return bodyNumbers[0];
-  }
-  return null;
+  return dedupe(matches.map((m) => Number((/(\d+)/.exec(m) || [])[1])));
 }
+
 async function fetchIssueBody({ repo, issue }, { env = process.env, ghCommand = "gh" } = {}) {
   const result = await runChild(
     ghCommand,
@@ -261,58 +287,118 @@ async function fetchIssueBody({ repo, issue }, { env = process.env, ghCommand =
     return null;
   }
 }
-async function loadRefinementArtifact({ repo, prData, prDraft, prClosed, prMerged }, { env = process.env, ghCommand = "gh" } = {}) {
-  const linkedIssue = resolveLinkedIssueFromPr(prData);
-  if (linkedIssue === null) {
+export async function loadRefinementArtifact({ repo, prData, prDraft, prClosed, prMerged }, { env = process.env, ghCommand = "gh" } = {}) {
+  const linkedIssues = resolveLinkedIssuesFromPr(prData);
+  if (linkedIssues.length === 0) {
     if (prDraft) {
       return {
         status: "missing",
         linkedIssue: null,
-        reason: "Draft PR has no deterministically resolvable linked issue (no closingIssuesReferences, no unique Closes/Fixes/Resolves pattern in body); draft gate cannot verify a refinement artifact.",
+        linkedIssues: [],
+        reason: "Draft PR has no deterministically resolvable linked issue (no closingIssuesReferences and no Closes/Fixes/Resolves #n reference in body); draft gate cannot verify a refinement artifact.",
         finding: "missing_refinement_artifact",
       };
     }
     return {
       status: "unknown",
       linkedIssue: null,
-      reason: "No deterministically resolvable linked issue (no closingIssuesReferences, no unique Closes/Fixes/Resolves pattern in body).",
+      linkedIssues: [],
+      reason: "No deterministically resolvable linked issue (no closingIssuesReferences and no Closes/Fixes/Resolves #n reference in body).",
     };
   }
+  const scopeLabel = linkedIssues.map((n) => `#${n}`).join(", ");
   if (!prDraft && !prClosed && !prMerged) {
     return {
       status: "unknown",
-      linkedIssue,
-      reason: `Linked issue #${linkedIssue} detected; refinement check is a draft-gate boundary and the PR is not draft, so the check is informational only and does not fetch the issue body.`,
+      linkedIssue: linkedIssues.length === 1 ? linkedIssues[0] : null,
+      linkedIssues,
+      reason: `Linked issue(s) ${scopeLabel} detected (${linkedIssues.length}); refinement check is a draft-gate boundary and the PR is not draft, so the check is informational only and does not fetch issue bodies.`,
+    };
+  }
+  const { detectIssueRefinementArtifact } = await import("@dev-loops/core/loop/issue-refinement-artifact");
+  // Fetch and evaluate every closing-referenced issue. An umbrella PR's scope
+  // is refined if AT LEAST ONE linked issue carries a refinement artifact.
+  const evaluated = [];
+  for (const issue of linkedIssues) {
+    const body = await fetchIssueBody({ repo, issue }, { env, ghCommand });
+    if (body === null) {
+      evaluated.push({ issue, artifact: null });
+      continue;
+    }
+    evaluated.push({ issue, artifact: detectIssueRefinementArtifact({ body, issueNumber: issue }) });
+  }
+  const refinedIssues = evaluated
+    .filter((e) => e.artifact && e.artifact.hasACs === true)
+    .map((e) => e.issue);
+  const firstPresent = evaluated.find((e) => e.artifact && e.artifact.hasACs === true);
+  const isUmbrella = linkedIssues.length > 1;
+
+  if (firstPresent) {
+    const a = firstPresent.artifact;
+    return {
+      status: "present",
+      linkedIssue: firstPresent.issue,
+      linkedIssues,
+      refinedIssues,
+      source: a.source,
+      acItems: a.acItems,
+      dodItems: a.dodItems,
+      sections: a.sections,
+      linkedDoc: a.linkedDoc,
+      reason: isUmbrella
+        ? `Refinement artifact present via linked issue #${firstPresent.issue} (umbrella PR closes ${scopeLabel}).`
+        : a.reason,
+      finding: a.finding,
+      _onlyEnforcedWhenDraft: prDraft === true,
     };
   }
-  const body = await fetchIssueBody({ repo, issue: linkedIssue }, { env, ghCommand });
-  if (body === null) {
+
+  // None of the linked issues carry a refinement artifact (or all bodies failed
+  // to fetch). Report against the first linked issue for single-value consumers.
+  // Note: `finding`/`missing` here is only enforced by the gate when the PR is
+  // draft (`_onlyEnforcedWhenDraft`); closed/merged PRs surface it informationally.
+  const firstEvaluated = evaluated[0];
+  const allFailed = evaluated.every((e) => e.artifact === null);
+  if (allFailed) {
+    // Preserve prior single-issue semantics: draft → missing, else unknown.
     if (prDraft) {
       return {
         status: "missing",
-        linkedIssue,
-        reason: `Failed to fetch body for linked issue #${linkedIssue}; draft gate cannot verify a refinement artifact, treating as missing.`,
+        linkedIssue: firstEvaluated.issue,
+        linkedIssues,
+        refinedIssues,
+        reason: `Failed to fetch body for linked issue(s) ${scopeLabel}; draft gate cannot verify a refinement artifact, treating as missing.`,
         finding: "missing_refinement_artifact",
       };
     }
     return {
       status: "unknown",
-      linkedIssue,
-      reason: `Failed to fetch body for linked issue #${linkedIssue}; refinement status is unknown.`,
+      linkedIssue: linkedIssues.length === 1 ? linkedIssues[0] : firstEvaluated.issue,
+      linkedIssues,
+      refinedIssues,
+      reason: `Failed to fetch body for linked issue(s) ${scopeLabel}; refinement status is unknown.`,
     };
   }
-  const { detectIssueRefinementArtifact } = await import("@dev-loops/core/loop/issue-refinement-artifact");
-  const artifact = detectIssueRefinementArtifact({ body, issueNumber: linkedIssue });
+  // Mixed branch: not allFailed, so at least one body fetched but none is
+  // refined. Report against the first successfully-fetched (non-null) issue —
+  // `evaluated[0]` may be a failed fetch: it still retains its `issue` field but
+  // has `artifact: null` (body fetch / artifact detection failed for that issue).
+  const firstFetched = evaluated.find((e) => e.artifact !== null);
+  const first = firstFetched.artifact;
   return {
-    status: artifact.hasACs ? "present" : "missing",
-    linkedIssue,
-    source: artifact.source,
-    acItems: artifact.acItems,
-    dodItems: artifact.dodItems,
-    sections: artifact.sections,
-    linkedDoc: artifact.linkedDoc,
-    reason: artifact.reason,
-    finding: artifact.finding,
+    status: "missing",
+    linkedIssue: firstFetched.issue,
+    linkedIssues,
+    refinedIssues,
+    source: first.source,
+    acItems: first.acItems,
+    dodItems: first.dodItems,
+    sections: first.sections,
+    linkedDoc: first.linkedDoc,
+    reason: isUmbrella
+      ? `No linked issue (${scopeLabel}) carries a refinement artifact (ACs/DoD); draft gate cannot verify a refinement artifact.`
+      : first.reason,
+    finding: "missing_refinement_artifact",
     _onlyEnforcedWhenDraft: prDraft === true,
   };
 }
@@ -332,16 +418,6 @@ async function fetchLocalConflictFiles({ env = process.env, gitCommand = "git" }
   }
   return parseGitStatusConflictFiles(result.stdout);
 }
-async function loadRetrospectiveCheckpoint(repoRoot) {
-  const checkpointPath = path.join(repoRoot, ".pi", "dev-loop-retrospective-checkpoint.json");
-  try {
-    const checkpointText = await readFile(checkpointPath, "utf8");
-    const checkpoint = parseJsonText(checkpointText, { label: "retrospective checkpoint" });
-    return checkpoint && typeof checkpoint === "object" ? checkpoint : null;
-  } catch (error) {
-    return null;
-  }
-}
 export async function loadPrGateCoordinationContext(options, runtime = {}) {
   const prData = await fetchPrFactsWithSettledMergeable(options, runtime);
   const currentHeadSha = typeof prData?.headRefOid === "string" && prData.headRefOid.trim().length > 0
@@ -392,11 +468,22 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
   // 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 interpreterRepoRoot = runtime.repoRoot ?? resolveRepoRoot(process.cwd());
   const interpreterConfigResult = await loadDevLoopConfig({ repoRoot: interpreterRepoRoot });
-  const interpreterRefinementConfig = (Array.isArray(interpreterConfigResult.errors) && interpreterConfigResult.errors.length > 0)
+  const interpreterConfigHasErrors = Array.isArray(interpreterConfigResult.errors) && interpreterConfigResult.errors.length > 0;
+  const interpreterRefinementConfig = interpreterConfigHasErrors
     ? resolveRefinement({ version: 1 })
     : resolveRefinement(interpreterConfigResult.config ?? { version: 1 });
+  if (options.lightweight) {
+    // Compose (not replace) the round cap for light-dispatched PRs (#1210):
+    // min(lightMode.maxCopilotRounds ?? 1, refinement.maxCopilotRounds), so
+    // maxCopilotRounds: 0 still disables Copilot rounds everywhere. Shared with
+    // the maxCopilotRounds resolution below (#1126 requires the two to agree).
+    interpreterRefinementConfig.maxCopilotRounds = resolveEffectiveCopilotRoundCap(
+      interpreterConfigHasErrors ? { version: 1 } : (interpreterConfigResult.config ?? { version: 1 }),
+      { lightweight: true },
+    );
+  }
   const interpretation = interpretLoopState(snapshot, interpreterRefinementConfig);
   const disposition = summarizeLoopInterpretation(interpretation, interpreterRefinementConfig);
   const mergeStateStatus = typeof prData?.mergeStateStatus === "string" && prData.mergeStateStatus.trim().length > 0
@@ -446,15 +533,37 @@ async function fetchCopilotEverFormallyRequested({ repo, pr }, { env = process.e
 
 export async function detectPrGateCoordinationState(options, runtime = {}) {
   const context = await loadPrGateCoordinationContext(options, runtime);
-  const repoRoot = runtime.repoRoot ?? process.cwd();
+  const repoRoot = runtime.repoRoot ?? resolveRepoRoot(process.cwd());
   const configLoadResult = await loadDevLoopConfig({ repoRoot });
   const hasConfigErrors = Array.isArray(configLoadResult.errors) && configLoadResult.errors.length > 0;
   const config = hasConfigErrors ? {} : (configLoadResult.config ?? {});
   const draftGateConfig = resolveGateConfig(config, "draft");
-  const maxCopilotRounds = resolveRefinementConfig(config, "maxCopilotRounds");
-  const requireRetrospectiveGate = resolveWorkflowConfig(config, "requireRetrospectiveGate");
-  const requireRetrospectiveInternalTooling = resolveWorkflowConfig(config, "requireRetrospectiveInternalTooling");
-  const retrospectiveCheckpoint = await loadRetrospectiveCheckpoint(repoRoot);
+  // Shared with interpreterRefinementConfig.maxCopilotRounds in
+  // loadPrGateCoordinationContext (#1126: the two must never disagree at the
+  // cap boundary) — the same lightweight composition (#1210) is applied here.
+  const maxCopilotRounds = options.lightweight
+    ? resolveEffectiveCopilotRoundCap(config, { lightweight: true })
+    : resolveRefinementConfig(config, "maxCopilotRounds");
+  // Shared with interpretLoopState (consumed by copilot-pr-handoff.mjs) and
+  // evaluatePrGateCoordination — the single source of truth for "is the
+  // Copilot round cap reached" so this detector cannot disagree with the
+  // handoff at the cap boundary (#1126).
+  const roundCapReached = isCopilotRoundCapReached({
+    copilotReviewRoundCount: context.snapshot?.copilotReviewRoundCount,
+    maxCopilotRounds,
+  });
+  const postConvergenceSignificantChange = await detectPostConvergenceSignificantChange(
+    {
+      repo: context.repo,
+      pr: context.pr,
+      currentHeadSha: context.currentHeadSha,
+      reviews: context.prData?.reviews,
+      changedFiles: context.prData?.files,
+      roundCapReached: roundCapReached && context.interpretation?.roundCapCleanEligible === true,
+      regularCopilotRounds: (context.snapshot?.copilotReviewRoundCount ?? 0) > 0,
+    },
+    runtime,
+  );
   const result = evaluatePrGateCoordination({
     repo: context.repo,
     pr: context.pr,
@@ -475,15 +584,17 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     copilotReviewRoundCount: context.snapshot?.copilotReviewRoundCount ?? 0,
     maxCopilotRounds,
     sameHeadCleanConverged: context.interpretation.sameHeadCleanConverged,
+    // Independent gate-ENTRY re-check (#1190): fed alongside (not derived from)
+    // sameHeadCleanConverged, so an outstanding request on the current head refuses
+    // RUN_PRE_APPROVAL_GATE even if sameHeadCleanConverged were somehow stale/wrong.
+    copilotReviewRequestStatus: context.snapshot?.copilotReviewRequestStatus ?? "none",
     draftGateRequireCi: draftGateConfig.requireCi,
-    requireRetrospectiveGate,
-    requireRetrospectiveInternalTooling,
-    retrospectiveCheckpoint,
     draftGate: context.gateEvidence.draftGate,
     draftGateMarker: context.gateEvidence.draftGateMarker,
     preApprovalGate: context.gateEvidence.preApprovalGate,
     preApprovalGateMarker: context.gateEvidence.preApprovalGateMarker,
     refinementArtifact: context.refinementArtifact,
+    postConvergenceSignificantChange,
   });
   // Copilot review request guard (#613): When Copilot has reviewed the PR
   // but no formal review request was made, block pre-approval gate entry.
@@ -495,9 +606,6 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     PR_CHECKPOINT.PRE_APPROVAL_GATE_WINDOW,
     PR_CHECKPOINT.FINAL_APPROVAL_READY,
   ]);
-  const roundCapReached = maxCopilotRounds !== null
-    && 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
@@ -505,7 +613,13 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
   const roundCapCleanFallback = context.interpretation?.roundCapCleanEligible ?? false;
   const copilotReviewEverFormallyRequested = copilotReviewRequestStatus === "none"
     && guardBoundaries.has(result.gateBoundary)
-    && !(roundCapReached && (sameHeadCleanConverged || roundCapCleanFallback))
+    // cap-0 disables the Copilot gate, so shouldGuardCopilotReviewRequest always
+    // returns false here — skip the timeline fetch it would never need (#1126).
+    // (Restores the suppression the roundCapReached predicate swap dropped.)
+    && maxCopilotRounds !== 0
+    && !(roundCapReached
+      && (sameHeadCleanConverged || roundCapCleanFallback)
+      && !postConvergenceSignificantChange)
     ? await fetchCopilotEverFormallyRequested(
         { repo: context.repo, pr: context.pr },
         runtime,
@@ -518,6 +632,7 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     maxCopilotRounds,
     sameHeadCleanConverged,
     roundCapCleanFallback,
+    postConvergenceSignificantChange,
     gateBoundary: result.gateBoundary,
   })) {
     result.gateBoundary = PR_CHECKPOINT.POST_DRAFT_EXTERNAL_REVIEW;
@@ -590,7 +705,7 @@ async function main() {
   }
   try {
     const result = await detectPrGateCoordinationState(options);
-    process.stdout.write(`${JSON.stringify(result)}\n`);
+    process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent });
   } catch (error) {
     process.stderr.write(`${formatCliError(error)}\n`);
     process.exitCode = 1;

package/scripts/loop/detect-reviewer-loop-state.mjs

@@ -8,6 +8,7 @@ import {
   interpretReviewerLoopState,
   normalizeReviewerSnapshot,
 } from "@dev-loops/core/loop/reviewer-loop-state";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const HELP = `Usage: detect-reviewer-loop-state.mjs [--input <path> | --repo <owner/name> --pr <number>] [--review-requested <true|false>] [--local-state <path>]
 Detect reviewer loop state for a pull request.
 Modes:
@@ -17,9 +18,13 @@ Options (auto-detect mode only):
   --review-requested <bool>     Override review-requested detection (true/false)
   --local-state <path>          Path to local state file for snapshot merging
 Reviewer scope is auto-resolved from PR requested reviewers.
+
+${JQ_OUTPUT_USAGE}
+
 Exit codes:
   0   Success
   1   Error
+  2   Invalid --jq filter
 `;
 function parseBool(value, flag) {
   if (value === "true") return true;
@@ -36,6 +41,7 @@ export function parseDetectReviewerCliArgs(argv) {
       pr: { type: "string" },
       "review-requested": { type: "string" },
       "local-state": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -83,6 +89,7 @@ export function parseDetectReviewerCliArgs(argv) {
       options.localStatePath = requireTokenValue(token);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t))) continue;
     throw new Error(`Unknown argument: ${token.rawName}`);
   }
   if (options.inputPath !== undefined) {
@@ -231,7 +238,7 @@ export async function autoDetectReviewerSnapshot(
 }
 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 = parseDetectReviewerCliArgs(argv);
   if (options.help) { stdout.write(HELP); return; }
@@ -243,7 +250,10 @@ export async function runCli(
     snapshot = await autoDetectReviewerSnapshot(options, { env, ghCommand });
   }
   const interpretation = interpretReviewerLoopState(snapshot);
-  stdout.write(`${JSON.stringify({ ok: true, snapshot, state: interpretation.state, allowedTransitions: interpretation.allowedTransitions, nextAction: interpretation.nextAction })}\n`);
+  process.exitCode = emitResult(
+    { ok: true, snapshot, state: interpretation.state, allowedTransitions: interpretation.allowedTransitions, nextAction: interpretation.nextAction },
+    { jq: options.jq, silent: options.silent, stdout, stderr },
+  );
 }
 if (isDirectCliRun(import.meta.url)) {
   runCli().catch((error) => { process.stderr.write(`${formatCliError(error)}\n`); process.exitCode = 1; });

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

@@ -3,6 +3,7 @@ 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";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 function showHelp() {
   process.stdout.write(`Usage: detect-tracker-first-loop-state.mjs --repo <owner/name> --issue <number>
@@ -11,9 +12,13 @@ Options:
   --repo <owner/name>   GitHub repository slug
   --issue <number>      GitHub issue number
   --help, -h            Show this help
+
+${JQ_OUTPUT_USAGE}
+
 Exit codes:
   0   Success
   1   Error
+  2   Invalid --jq filter
 `);
   process.exit(0);
 }
@@ -25,6 +30,7 @@ function parseCliArgs(argv) {
       repo: { type: "string" },
       issue: { type: "string" },
       help: { type: "boolean", short: "h" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -46,7 +52,9 @@ function parseCliArgs(argv) {
       }
       if (token.name === "issue") {
         opts.issue = token.value ?? null;
+        continue;
       }
+      if (matchJqOutputToken(token, opts)) continue;
     }
   }
   return opts;
@@ -90,7 +98,7 @@ async function main() {
     return;
   }
   const result = interpretTrackerLoopState({ trackerState: rawState, prContext });
-  process.stdout.write(JSON.stringify(result) + "\n");
+  process.exitCode = emitResult(result, { jq: rawOpts.jq, silent: rawOpts.silent });
 }
 const isDirectRun =
   process.argv[1] && process.argv[1].includes("detect-tracker-first-loop-state.mjs");

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

@@ -9,6 +9,7 @@ import {
   interpretTrackerPrState,
   normalizeTrackerPrSnapshot,
 } from "@dev-loops/core/loop/tracker-pr-state";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage:
   detect-tracker-pr-state.mjs --input <path>
 Interpret a pre-built tracker-PR snapshot JSON and emit the current lifecycle
@@ -47,9 +48,11 @@ Output (stdout, JSON):
 Error output (stderr, JSON):
   Argument/usage errors: { "ok": false, "error": "...", "usage": "..." }
   Runtime failures:      { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error or runtime failure`.trim();
+  1  Argument error or runtime failure
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 export function parseDetectTrackerPrCliArgs(argv) {
   const options = {
@@ -61,6 +64,7 @@ export function parseDetectTrackerPrCliArgs(argv) {
     options: {
       help: { type: "boolean", short: "h" },
       input: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -81,6 +85,7 @@ export function parseDetectTrackerPrCliArgs(argv) {
       options.inputPath = requireTokenValue(token, parseError);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.inputPath === undefined) {
@@ -92,6 +97,7 @@ export async function runCli(
   argv = process.argv.slice(2),
   {
     stdout = process.stdout,
+    stderr = process.stderr,
   } = {},
 ) {
   const options = parseDetectTrackerPrCliArgs(argv);
@@ -103,8 +109,9 @@ export async function runCli(
   const raw = parseJsonText(text);
   const snapshot = normalizeTrackerPrSnapshot(raw);
   const { state, allowedTransitions, nextAction, reverseSyncAction } = interpretTrackerPrState(snapshot);
-  stdout.write(
-    `${JSON.stringify({ ok: true, snapshot, state, allowedTransitions, nextAction, reverseSyncAction })}\n`,
+  process.exitCode = emitResult(
+    { ok: true, snapshot, state, allowedTransitions, nextAction, reverseSyncAction },
+    { jq: options.jq, silent: options.silent, stdout, stderr },
   );
 }
 const isDirectRun =

package/scripts/loop/ensure-worktree.mjs

@@ -27,6 +27,7 @@ import { parseArgs } from "node:util";
 import { resolveWorktreePath } from "@dev-loops/core/loop/handoff-envelope";
 import { provisionWorktree } from "./provision-worktree.mjs";
 import { canonicalize } from "./_worktree-path.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage:
   ensure-worktree.mjs --repo-root <p> (--issue <n> | --pr <n>) [--branch <name>] [--base <ref>]
@@ -43,7 +44,9 @@ Optional:
   -h, --help        Show this help.
 Output (stdout, JSON):
   { "ok": true, "path": <p>, "created": bool, "reused": bool,
-    "provision": { "actions": [...], "summary": {...} } }`.trim();
+    "provision": { "actions": [...], "summary": {...} } }
+
+${JQ_OUTPUT_USAGE}`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -71,6 +74,7 @@ export function parseEnsureWorktreeCliArgs(argv) {
       pr: { type: "string" },
       branch: { type: "string" },
       base: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -103,6 +107,7 @@ export function parseEnsureWorktreeCliArgs(argv) {
       options.base = requireTokenValue(token, parseError, { flagPattern: /^-/u });
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.help) return options;
@@ -201,14 +206,14 @@ export async function ensureWorktree(
   return { ok: true, path: target, created: true, reused: false, provision: summary };
 }
 
-export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout, stderr = process.stderr } = {}) {
   const options = parseEnsureWorktreeCliArgs(argv);
   if (options.help) {
     stdout.write(`${USAGE}\n`);
     return;
   }
   const result = await ensureWorktree(options);
-  stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 
 if (isDirectCliRun(import.meta.url)) {