dev-loops 0.5.0 → 0.7.1

package/scripts/loop/resolve-dev-loop-startup.mjs

@@ -34,7 +34,10 @@ import {
   PLAN_FILE_REFINEMENT_SECTIONS,
 } from "@dev-loops/core/loop/plan-file-intake-contract";
 import { evaluateSpikeIntakeState } from "@dev-loops/core/loop/spike-intake-contract";
+import { loadBoardConfig } from "@dev-loops/core/loop/queue-board-sync";
+import { main as reconcileQueue } from "../projects/reconcile-queue.mjs";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const USAGE = `Usage:
   resolve-dev-loop-startup.mjs --issue <number>
   resolve-dev-loop-startup.mjs --pr <number>
@@ -54,9 +57,23 @@ Required (exactly one):
   --input <path>  Path to a JSON file with canonical-state payload
   --plan-file <path>  Path to a phase-doc-format plan to start locally
   --spike <path>  Path to a spike artifact to start a spike loop locally
+Optional modifier:
+  --lightweight  With --issue: use the PR body as the spec-of-record
+                 (canonicalSpecSource: pr_body) — no phase/plan doc minted or
+                 committed. Same gate sequence; only the backing artifact
+                 differs. Rejected with --plan-file (its opposite). The secondary
+                 heuristic (chore/fix commit type + no --plan-file + small change)
+                 is a documented manual signal; --lightweight is the explicit,
+                 deterministic trigger.
+${JQ_OUTPUT_USAGE}
+
 Exit codes:
   0  Success
-  1  Argument error, runtime failure, or async-start contract rejection`.trim();
+  1  Argument error, runtime failure, or async-start contract rejection
+  2  Invalid --jq filter`.trim();
+// Upper bound on the awaited best-effort startup reconcile so a slow or hung gh
+// can never delay startup completion.
+const STARTUP_RECONCILE_BUDGET_MS = 20000;
 const SHARED_PUBLIC_CONTRACT = "skills/docs/public-dev-loop-contract.md";
 const SHARED_RETROSPECTIVE_CONTRACT = "skills/docs/retrospective-checkpoint-contract.md";
 const STRATEGY_REQUIRED_READS = {
@@ -123,6 +140,7 @@ export function parseResolveDevLoopStartupCliArgs(argv) {
     pr: undefined,
     planFile: undefined,
     spike: undefined,
+    lightweight: false,
   };
   const { tokens } = parseArgs({
     args: [...argv],
@@ -133,6 +151,8 @@ export function parseResolveDevLoopStartupCliArgs(argv) {
       pr: { type: "string" },
       "plan-file": { type: "string" },
       spike: { type: "string" },
+      lightweight: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -169,6 +189,11 @@ export function parseResolveDevLoopStartupCliArgs(argv) {
       options.spike = requireTokenValue(token, 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}`);
   }
   const modeCount = [options.inputPath, options.issue, options.pr, options.planFile, options.spike].filter(v => v !== undefined).length;
@@ -178,6 +203,15 @@ export function parseResolveDevLoopStartupCliArgs(argv) {
   if (modeCount === 0) {
     throw parseError("--input <path>, --issue <n>, --pr <n>, --plan-file <path>, or --spike <path> is required");
   }
+  // --lightweight is a MODIFIER (not a 6th mode): it makes the PR body the
+  // spec-of-record for the --issue local path. It is the opposite of --plan-file
+  // (which commits a durable plan doc as the spec) and only composes with --issue.
+  if (options.lightweight && options.planFile !== undefined) {
+    throw parseError("--lightweight and --plan-file are opposites: --plan-file commits a durable plan doc as the spec-of-record, --lightweight makes the PR body the spec. Provide only one.");
+  }
+  if (options.lightweight && options.issue === undefined) {
+    throw parseError("--lightweight is a modifier for the --issue path (the PR body becomes the spec-of-record). Combine it with --issue <n>.");
+  }
   return options;
 }
 function ghJson(args, cwd) {
@@ -264,7 +298,7 @@ function resolveTargetPreference(cwd) {
     } catch {
     }
   }
-  return "prefer_github_first";
+  return "prefer_local";
 }
 function normalizeConfigInputSource(value) {
   if (value === "phase-docs") return "phase-docs";
@@ -541,7 +575,10 @@ export function buildResolveDevLoopStartupResult(input, { adapter = createPiAdap
   // evaluator does not model. Strip them before evaluation and re-apply them to
   // the result; `planFileExempt` waives the worktree-isolation guard because a
   // pre-promotion plan has no issue to key a worktree on.
-  const { planFileExempt = false, planFileIntakeState = null, spikeIntakeState = null, ...routingInput } = input;
+  // `canonicalSpecSource` (issue #1025) is a resolver-only field the pure routing
+  // evaluator does not model — strip it before evaluation and re-attach to the
+  // result, mirroring planFileIntakeState/spikeIntakeState.
+  const { planFileExempt = false, planFileIntakeState = null, spikeIntakeState = null, canonicalSpecSource = null, ...routingInput } = input;
   input = routingInput;
   try {
     const checkpointText = readFileSync(
@@ -652,6 +689,7 @@ export function buildResolveDevLoopStartupResult(input, { adapter = createPiAdap
     canonicalStateSummary: summarizeCanonicalState(bundle),
     ...(planFileIntakeState !== null ? { planFileIntakeState } : {}),
     ...(spikeIntakeState !== null ? { spikeIntakeState } : {}),
+    ...(canonicalSpecSource !== null ? { canonicalSpecSource } : {}),
     bundle,
   };
 }
@@ -672,7 +710,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
     ? devLoopConfig?.strategy?.default === "local-first"
       ? "prefer_local"
       : "prefer_github_first"
-    : "prefer_github_first";
+    : "prefer_local";
   const inputSource = configErrors.length === 0
     ? normalizeConfigInputSource(devLoopConfig?.inputSource?.default)
     : "tracker";
@@ -693,6 +731,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
       delete parsed.planFileExempt;
       delete parsed.planFileIntakeState;
       delete parsed.spikeIntakeState;
+      delete parsed.canonicalSpecSource;
     }
     input = parsed;
   } else if (options.issue !== undefined) {
@@ -702,6 +741,11 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
       targetPreference,
       inputSource,
     });
+    // --lightweight modifier (issue #1025): the PR body becomes the
+    // spec-of-record for this local session — no phase/plan doc minted.
+    if (options.lightweight) {
+      input = { ...input, canonicalSpecSource: "pr_body" };
+    }
   } else {
     input = buildAutoResolvedInput({
       pr: options.pr,
@@ -711,11 +755,36 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   }
   const result = buildResolveDevLoopStartupResult(input, { asyncStartMode, adapter });
   if (result.ok === false) {
-    stderr.write(`${JSON.stringify(result)}\n`);
-    process.exitCode = 1;
+    process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout: stderr, stderr });
     return;
   }
-  stdout.write(`${JSON.stringify(result)}\n`);
+  // Emit the deterministic bundle FIRST, before the best-effort self-heal below,
+  // so a slow or hung gh reconcile can never delay the startup result.
+  process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
+  // #1069: best-effort startup self-heal — converge the board from live GitHub
+  // state so merged→Done / ready→In Progress land deterministically. Gated on a
+  // configured board so it never shells out to gh in the no-.devloops unit tests;
+  // never writes stdout, never changes exit code, never throws. Skips
+  // --input/--plan-file/--spike modes.
+  if (options.issue !== undefined || options.pr !== undefined) {
+    let reconcileRoot = sessionCwd;
+    try {
+      reconcileRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+        cwd: sessionCwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
+      }).trim();
+    } catch { /* fall back to sessionCwd */ }
+    if (loadBoardConfig(reconcileRoot).enabled === true) {
+      try {
+        // The budget bounds startup latency; reconcile is best-effort and the
+        // board self-heals on the next entry if it doesn't finish. The timer is
+        // unref'd so it never keeps the event loop alive on its own.
+        await Promise.race([
+          reconcileQueue({ repo: detectRepoSlug(reconcileRoot) }, { env: adapter.getEnv(), cwd: reconcileRoot, skipTerminalColumn: true }),
+          new Promise((resolve) => { const t = setTimeout(resolve, STARTUP_RECONCILE_BUDGET_MS); t.unref?.(); }),
+        ]);
+      } catch { /* best-effort */ }
+    }
+  }
 }
 if (isDirectCliRun(import.meta.url)) {
   runCli().catch((error) => {

package/scripts/loop/resolve-gate-dispatch.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { parseArgs } from "node:util";
+import {
+  loadDevLoopConfig,
+  resolveGateDispatchMode,
+  GATE_FULL_LABEL,
+} from "@dev-loops/core/config";
+import { detectScope } from "./detect-change-scope.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+
+const USAGE = `Usage: resolve-gate-dispatch.mjs --gate <draft|preApproval> [--base <ref>] [--head <ref>] [--full-label] [--inline-severities <csv>]
+Decide inline vs full fan-out for a gate from lightMode config + PR facts.
+Options:
+  --gate <draft|preApproval>   Gate to resolve dispatch for (required)
+  --base <ref>                 Base ref for scope detection (default: HEAD~1)
+  --head <ref>                 Head ref; ignored unless --base is also set
+  --full-label                 PR has the ${GATE_FULL_LABEL} label (forces full fan-out)
+  --inline-severities <csv>    Comma-separated severities from the inline pass (escalation phase)
+  --help, -h                   Show this help
+Output (stdout, JSON):
+  { "ok": true, "gate": "draft", "scope": { "ok": true, "filesChanged": 1, "linesChanged": 5 }, "mode": "inline", "reason": "under_threshold", "threshold": { "maxFiles": 2, "maxLines": 20 } }
+  { "ok": true, "gate": "draft", "scope": { "ok": true, "filesChanged": 9, "linesChanged": 300 }, "mode": "full_fanout", "reason": "over_threshold", "threshold": { "maxFiles": 2, "maxLines": 20 } }
+  { "ok": true, "gate": "draft", "scope": { "ok": false, ... }, "mode": "full_fanout", "reason": "scope_detection_failed", "threshold": null }
+Error output (stderr, JSON):
+  { "ok": false, "error": "...", "usage"?: "..." }
+
+${JQ_OUTPUT_USAGE}
+
+Exit codes:
+  0   Success
+  1   Error
+  2   Invalid --jq filter
+`;
+
+const VALID_GATES = new Set(["draft", "preApproval"]);
+
+/** Parse a comma-separated severity list. Returns `undefined` when the flag is absent, otherwise a trimmed array (which may be empty `[]` for empty/whitespace-only input). */
+export function parseSeverities(csv) {
+  if (csv == null) return undefined;
+  const list = String(csv)
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  return list.length > 0 ? list : [];
+}
+
+function parseCliArgs(argv) {
+  const { values } = parseArgs({
+    args: [...argv],
+    options: {
+      gate: { type: "string" },
+      base: { type: "string" },
+      head: { type: "string" },
+      "full-label": { type: "boolean", default: false },
+      "inline-severities": { type: "string" },
+      help: { type: "boolean", short: "h" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: true,
+  });
+  if (values.help) {
+    process.stdout.write(USAGE);
+    process.exit(0);
+  }
+  if (!values.gate || !VALID_GATES.has(values.gate)) {
+    throw new Error("--gate must be one of: draft, preApproval");
+  }
+  return {
+    gate: values.gate,
+    base: values.base ?? null,
+    head: values.head ?? null,
+    hasFullLabel: Boolean(values["full-label"]),
+    inlineFindingSeverities: parseSeverities(values["inline-severities"]),
+    jq: values.jq,
+    silent: values.silent === true,
+  };
+}
+
+export async function run(argv) {
+  let opts;
+  try {
+    opts = parseCliArgs(argv);
+  } catch (err) {
+    process.stderr.write(
+      JSON.stringify({ ok: false, error: err.message, usage: USAGE.trim() }) + "\n"
+    );
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const { config } = await loadDevLoopConfig({ repoRoot: process.cwd() });
+    const scope = detectScope({ base: opts.base, head: opts.head });
+    // Fail CLOSED on unmeasurable scope: a broken/failed diff must route to the
+    // full gate, never silently collapse to inline (which would bypass review).
+    if (scope.ok === false) {
+      process.exitCode = emitResult({
+        ok: true,
+        gate: opts.gate,
+        scope,
+        mode: "full_fanout",
+        reason: "scope_detection_failed",
+        threshold: null,
+      }, { jq: opts.jq, silent: opts.silent });
+      return;
+    }
+    const decision = resolveGateDispatchMode(config, opts.gate, {
+      scope,
+      hasFullLabel: opts.hasFullLabel,
+      inlineFindingSeverities: opts.inlineFindingSeverities,
+    });
+    process.exitCode = emitResult(
+      { ok: true, gate: opts.gate, scope, ...decision },
+      { jq: opts.jq, silent: opts.silent },
+    );
+  } catch (err) {
+    process.stderr.write(
+      JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }) + "\n"
+    );
+    process.exitCode = 1;
+  }
+}
+
+const isDirectRun =
+  process.argv[1] && process.argv[1].includes("resolve-gate-dispatch.mjs");
+if (isDirectRun) {
+  run(process.argv.slice(2)).catch((err) => {
+    process.stderr.write(
+      JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }) + "\n"
+    );
+    process.exitCode = 1;
+  });
+}

package/scripts/loop/resolve-pr-conflicts.mjs

@@ -6,6 +6,7 @@ import { parseArgs } from "node:util";
 
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { requireTokenValue } from "../_cli-primitives.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage: resolve-pr-conflicts.mjs [--base <branch>] [--repo-root <dir>] [--no-verify] [--push] [--json]
 
@@ -36,9 +37,14 @@ Output (stdout, JSON with --json):
 Error output:
   { "ok": false, "error": "...", "conflictFiles": ["..."] }
 
+${JQ_OUTPUT_USAGE}
+(--jq/--silent apply to the JSON error output always, and to the success output
+with --json; the default non-JSON success summary is unaffected.)
+
 Exit codes:
   0  Clean merge (incl. already up to date) or auto-resolved CHANGELOG
-  1  Argument error, git failure, or UNRESOLVABLE conflict (fail closed)`.trim();
+  1  Argument error, git failure, or UNRESOLVABLE conflict (fail closed)
+  2  Invalid --jq filter`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -70,6 +76,7 @@ export function parseResolvePrConflictsCliArgs(argv) {
       "no-verify": { type: "boolean" },
       push: { type: "boolean" },
       json: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -101,8 +108,10 @@ export function parseResolvePrConflictsCliArgs(argv) {
       case "json":
         options.json = true;
         break;
-      default:
+      default: {
+        if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) break;
         throw parseError(`Unknown argument: ${token.rawName}`);
+      }
     }
   }
   return options;
@@ -337,18 +346,16 @@ export async function runCli(argv, { stdout = process.stdout, stderr = process.s
   try {
     const result = await resolvePrConflicts(options, { env });
     if (options.json) {
-      stdout.write(`${JSON.stringify(result)}\n`);
-    } else {
-      stdout.write(`${result.action} (base ${result.base}${result.resolvedFiles.length ? `, resolved ${result.resolvedFiles.join(", ")}` : ""}${result.pushed ? ", pushed" : ""})\n`);
+      return emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
     }
+    stdout.write(`${result.action} (base ${result.base}${result.resolvedFiles.length ? `, resolved ${result.resolvedFiles.join(", ")}` : ""}${result.pushed ? ", pushed" : ""})\n`);
     return 0;
   } catch (error) {
     const payload = { ok: false, error: error instanceof Error ? error.message : String(error) };
     if (Array.isArray(error?.conflictFiles)) {
       payload.conflictFiles = error.conflictFiles;
     }
-    stderr.write(`${JSON.stringify(payload)}\n`);
-    return 1;
+    return emitResult(payload, { jq: options.jq, silent: options.silent, stdout: stderr, stderr });
   }
 }
 

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

@@ -15,9 +15,12 @@ import {
 } from "./_handoff-contract.mjs";
 import { listOpenPrs } from "./_loop-pr-aggregation.mjs";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 export { listOpenPrs };
 const USAGE = `Usage: run-conductor-cycle.mjs --repo <owner/name>
-Poll all open PRs, detect state, and output an ordered action queue.`.trim();
+Poll all open PRs, detect state, and output an ordered action queue.
+
+${JQ_OUTPUT_USAGE}`.trim();
 export const CHECKPOINT_ACTION_TO_CONDUCTOR_ACTION = Object.freeze({
   [PR_CHECKPOINT_ACTION.ADDRESS_REVIEW_FEEDBACK]: "fix_threads",
   [PR_CHECKPOINT_ACTION.REPLY_RESOLVE_REVIEW_THREADS]: "fix_threads",
@@ -32,11 +35,16 @@ export const CHECKPOINT_ACTION_TO_CONDUCTOR_ACTION = Object.freeze({
   [PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY]: "merge",
   [PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL]: "await_approval",
   [PR_CHECKPOINT_ACTION.RESOLVE_MERGE_CONFLICTS]: "resolve_conflicts",
+  [PR_CHECKPOINT_ACTION.RUN_UI_E2E_SUITE]: "run_ui_e2e",
   [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]: "blocked",
   [PR_CHECKPOINT_ACTION.REPORT_DONE]: "done",
 });
 export const ACTION_PRIORITY = Object.freeze({
   merge: 100,
+  // UI e2e auto-scoping fix work (#976): a path-triggered, fail-closed
+  // precondition — surface it ahead of feedback/draft work so the rendered
+  // artifact gets registered + covered before the gate proceeds.
+  run_ui_e2e: 95,
   fix_threads: 90,
   run_pre_approval: 80,
   draft_gate: 70,
@@ -73,6 +81,7 @@ export function parseCliArgs(argv) {
     options: {
       help: { type: "boolean", short: "h" },
       repo: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -93,6 +102,7 @@ export function parseCliArgs(argv) {
       options.repo = requireTokenValue(token, parseError).trim();
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined) {
@@ -275,6 +285,7 @@ export async function runCli(
   argv = process.argv.slice(2),
   {
     stdout = process.stdout,
+    stderr = process.stderr,
     env = process.env,
     ghCommand = "gh",
     cwd = process.cwd(),
@@ -290,7 +301,7 @@ export async function runCli(
     ghCommand,
     repoRoot: cwd,
   });
-  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/loop/run-queue.mjs

@@ -21,6 +21,11 @@ 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";
+import {
+  REASON_NEXT_UP_EMPTY,
+  REASON_BOARD_QUERY_ERROR,
+  EMPTY_NEXT_UP_MESSAGE,
+} from "@dev-loops/core/loop/queue-board-ordering";
 
 const REPO_ROOT = fileURLToPath(new URL("../..", import.meta.url));
 
@@ -129,24 +134,28 @@ async function main() {
     // 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",
+      // Canonical empty-Next-Up outcome — matches queue-driver.mjs so operators
+      // see one message regardless of which layer detects it.
+      message: EMPTY_NEXT_UP_MESSAGE,
       boardConfigured: true,
-      reason: null,
+      reason: REASON_NEXT_UP_EMPTY,
       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.
+    // The board IS configured but Next Up resolution failed and the local queue
+    // had nothing to fall back to. Align with the driver's canonical fail-closed
+    // board-query-error outcome (reason + framing) so operators see one shape
+    // regardless of which layer detects the outage — an outage halts the run
+    // rather than draining Backlog/local order.
     console.log(JSON.stringify({
-      ok: true,
-      message: `Board configured but unavailable (${membership.reason}); nothing to run`,
+      ok: false,
+      stopped: true,
+      reason: REASON_BOARD_QUERY_ERROR,
+      message: `Next Up query failed (${membership.reason}); refusing to fall back to Backlog/local order — nothing to run`,
       boardConfigured: true,
-      reason: membership.reason ?? null,
       results: [],
     }));
     return;

package/scripts/loop/run-refinement-audit.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { parsePositiveInteger, requireTokenValue, runCommand } from "../_cli-primitives.mjs";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const DEFAULT_MAX_LINES = 1000;
 const DEFAULT_DUPLICATE_WINDOW_LINES = 4;
 const DEFAULT_BRANCH_THRESHOLD = 25;
@@ -35,7 +36,9 @@ Success output (stdout, JSON):
   }
 Failure behavior (stderr, JSON, exit 1):
   - malformed arguments, blank paths, invalid thresholds, and zero auditable files fail closed
-  - findings are not a process failure; findings still return exit 0`.trim();
+  - findings are not a process failure; findings still return exit 0
+
+${JQ_OUTPUT_USAGE}`.trim();
 const parseError = buildParseError(USAGE);
 const BRANCH_TOKEN_PATTERN = /\b(?:if|else|switch|case|for|while|catch|finally|break|continue)\b|&&|\|\||\?(?![?.])/gu;
 const PRIORITY_ORDER = new Map([
@@ -67,6 +70,7 @@ export function parseRefinementAuditCliArgs(argv) {
       "branch-threshold": { type: "string" },
       "thin-wrapper-max-lines": { type: "string" },
       output: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -127,6 +131,7 @@ export function parseRefinementAuditCliArgs(argv) {
       options.output = requireTokenValue(token, parseError, { flagPattern: /^-/u });
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.paths !== undefined && options.pathsFile !== undefined) {
@@ -512,22 +517,16 @@ export async function runCli(
       fullRepoScan: false,
     },
   };
-  const serializedPayload = `${JSON.stringify(payload)}\n`;
   if (typeof options.output === "string") {
     const outputPath = path.resolve(cwd, options.output);
     await mkdir(path.dirname(outputPath), { recursive: true });
-    await writeFile(outputPath, serializedPayload, "utf8");
+    await writeFile(outputPath, `${JSON.stringify(payload)}\n`, "utf8");
   }
-  stdout.write(serializedPayload);
+  process.exitCode = emitResult(payload, { jq: options.jq, silent: options.silent, stdout, stderr });
   return payload;
 }
 if (isDirectCliRun(import.meta.url)) {
   runCli()
-    .then((result) => {
-      if (result?.ok === false) {
-        process.exitCode = 1;
-      }
-    })
     .catch((error) => {
       process.stderr.write(`${formatCliError(error)}\n`);
       process.exitCode = 1;

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

@@ -15,7 +15,7 @@ import {
   EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY,
   enforceExternalHealthyWaitTimeout,
 } from "@dev-loops/core/loop/timeout-policy";
-import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const REMOVED_FLAGS = new Set([
   "--force-rerequest-review",
   "--probe-only",
@@ -254,14 +254,7 @@ export function parseWatchCycleCliArgs(argv) {
       options.concise = true;
       continue;
     }
-    if (token.name === "jq") {
-      options.jq = requireTokenValue(token, parseError);
-      continue;
-    }
-    if (token.name === "silent") {
-      options.silent = true;
-      continue;
-    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.pr === undefined) {