dev-loops 0.6.0 → 0.7.2

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

@@ -21,7 +21,8 @@ import {
 } from "@dev-loops/core/loop/async-start-contract";
 import { detectRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { isCopilotLogin } from "@dev-loops/core/github/copilot-helpers";
-import { loadDevLoopConfig, resolveWorkflowConfig } from "@dev-loops/core/config";
+import { loadDevLoopConfig, resolveLightMode, resolveWorkflowConfig } from "@dev-loops/core/config";
+import { detectScope } from "./detect-change-scope.mjs";
 import { createPiAdapter } from "@dev-loops/core/harness";
 import { validatePlanFile } from "../refine/validate-plan-file.mjs";
 import {
@@ -34,7 +35,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 +58,31 @@ 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.
+                 Used ALONE (no --issue/--pr/--input/--plan-file/--spike):
+                 issue-less PR-first (#1210) — no tracker binding at all
+                 (canonicalSpecSource: pr_body, no issue-keyed worktree
+                 requirement). Gated on localImplementation.lightMode being
+                 enabled AND the live change scope (git diff) staying within
+                 its maxFiles/maxLines threshold; fails closed with a distinct
+                 reason (light mode disabled / scope undetectable / over
+                 threshold) requiring --issue above the threshold.
+${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 +149,7 @@ export function parseResolveDevLoopStartupCliArgs(argv) {
     pr: undefined,
     planFile: undefined,
     spike: undefined,
+    lightweight: false,
   };
   const { tokens } = parseArgs({
     args: [...argv],
@@ -133,6 +160,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,14 +198,34 @@ 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;
   if (modeCount > 1) {
     throw parseError("--issue, --pr, --input, --plan-file, and --spike are mutually exclusive; provide exactly one");
   }
-  if (modeCount === 0) {
-    throw parseError("--input <path>, --issue <n>, --pr <n>, --plan-file <path>, or --spike <path> is required");
+  // --lightweight is normally a MODIFIER (not a 6th mode): it makes the PR body
+  // the spec-of-record for the --issue local path. Used ALONE (modeCount === 0,
+  // issue #1210) it is instead the issue-less PR-first trigger — no tracker
+  // binding at all — so the "no mode selected" error is skipped in that case.
+  if (modeCount === 0 && !options.lightweight) {
+    throw parseError("--input <path>, --issue <n>, --pr <n>, --plan-file <path>, --spike <path>, or --lightweight (issue-less PR-first) is required");
+  }
+  // --lightweight is the opposite of --plan-file (which commits a durable plan
+  // doc as the spec) regardless of mode.
+  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.");
+  }
+  // When another mode IS selected, --lightweight only composes with --issue
+  // (not --pr/--input/--spike). Used with no mode selected at all, it is the
+  // issue-less PR-first trigger handled above.
+  if (options.lightweight && modeCount > 0 && 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>, or use --lightweight alone (no other mode flag) for the issue-less PR-first path.");
   }
   return options;
 }
@@ -264,7 +313,7 @@ function resolveTargetPreference(cwd) {
     } catch {
     }
   }
-  return "prefer_github_first";
+  return "prefer_local";
 }
 function normalizeConfigInputSource(value) {
   if (value === "phase-docs") return "phase-docs";
@@ -511,6 +560,120 @@ export function buildSpikeInput({ spikeFilePath }) {
     },
   };
 }
+// Candidate default-branch refs for issue-less scope measurement, in preference
+// order. origin/HEAD tracks the remote default branch when set; the rest cover
+// the common names.
+const ISSUELESS_BASE_REF_CANDIDATES = ["origin/HEAD", "origin/main", "origin/master", "main", "master"];
+
+function resolveIssuelessMergeBase(cwd) {
+  for (const ref of ISSUELESS_BASE_REF_CANDIDATES) {
+    try {
+      return execFileSync("git", ["merge-base", ref, "HEAD"], {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+      }).trim();
+    } catch {
+      // try the next candidate
+    }
+  }
+  return null;
+}
+
+/**
+ * Decide whether the live change scope is eligible for issue-less lightweight
+ * PR-first (#1210): reuses the same localImplementation.lightMode threshold
+ * that gates inline vs full-fanout gate dispatch, so "genuinely small" means
+ * the same thing everywhere in the repo.
+ *
+ * Scope is measured from the merge-base with the default branch to the WORKING
+ * TREE (`git diff --stat <merge-base>`), so multi-commit branches and
+ * uncommitted changes are both counted — a HEAD~1-only measure would fail OPEN
+ * on a branch whose earlier commits already exceed the threshold. Fails CLOSED
+ * on every negative path (disabled / no resolvable base / undetectable diff /
+ * over threshold) with a distinct reason so the caller can report why --issue
+ * is required instead of silently defaulting one way or the other.
+ *
+ * Every git invocation is bound to `cwd` (the adapter-resolved repoRoot),
+ * matching the rest of this file's git calls — process.cwd() is never relied
+ * on implicitly so this stays correct when invoked from a subdirectory or
+ * with a harness cwd that differs from the OS process cwd.
+ *
+ * @param {import("@dev-loops/core/config").DevLoopConfig} config
+ * @param {string} [cwd] - Repo root to run git commands in (defaults to process.cwd() when omitted).
+ * @returns {{ eligible: true, scope: object, threshold: {maxFiles:number,maxLines:number} } | { eligible: false, reason: "light_mode_disabled"|"scope_detection_failed"|"over_threshold", scope?: object, threshold?: object, detail?: string }}
+ */
+export function resolveIssuelessLightweightEligibility(config, cwd) {
+  const threshold = resolveLightMode(config);
+  if (!threshold) {
+    return { eligible: false, reason: "light_mode_disabled" };
+  }
+  const mergeBase = resolveIssuelessMergeBase(cwd);
+  if (mergeBase === null) {
+    return {
+      eligible: false,
+      reason: "scope_detection_failed",
+      detail: `no merge-base with any default-branch candidate (${ISSUELESS_BASE_REF_CANDIDATES.join(", ")})`,
+    };
+  }
+  // detectScope with only `base` diffs base..working-tree in one measure
+  // (committed branch delta + uncommitted changes).
+  const scope = detectScope({ base: mergeBase, cwd });
+  if (scope.ok === false) {
+    return { eligible: false, reason: "scope_detection_failed", detail: scope.error };
+  }
+  if (scope.filesChanged > threshold.maxFiles || scope.linesChanged > threshold.maxLines) {
+    return { eligible: false, reason: "over_threshold", scope, threshold };
+  }
+  return { eligible: true, scope, threshold };
+}
+
+/**
+ * Build a `--lightweight` startup input with NO tracker binding at all
+ * (issue-less PR-first, #1210): `--lightweight` used alone, no --issue.
+ *
+ * Read-only: no tracker mutation, no GitHub calls, no issue/PR number. Gated
+ * by {@link resolveIssuelessLightweightEligibility} — an ineligible change
+ * throws so the CLI fails closed (exit 1, no readiness bundle) with a message
+ * naming the distinct reason, mirroring buildPlanFileInput/buildSpikeInput's
+ * fail-closed-on-invalid-input convention. Exempt from the worktree-isolation
+ * guard like the plan-file/spike paths: there is no issue number to key a
+ * worktree on.
+ *
+ * @param {{ config: import("@dev-loops/core/config").DevLoopConfig, cwd?: string }} params
+ * @returns {object} startup input with canonicalSpecSource: "pr_body"
+ */
+export function buildLightweightIssuelessInput({ config, cwd }) {
+  const eligibility = resolveIssuelessLightweightEligibility(config, cwd);
+  if (!eligibility.eligible) {
+    if (eligibility.reason === "light_mode_disabled") {
+      throw new Error("--lightweight without --issue (issue-less PR-first) requires localImplementation.lightMode.enabled in .devloops; enable light mode or provide --issue <n>.");
+    }
+    if (eligibility.reason === "scope_detection_failed") {
+      throw new Error(`--lightweight without --issue (issue-less PR-first) requires a measurable change scope; git diff failed (${eligibility.detail}). Provide --issue <n> instead.`);
+    }
+    throw new Error(`--lightweight without --issue (issue-less PR-first) requires the change to stay within the light-mode threshold (maxFiles=${eligibility.threshold.maxFiles}, maxLines=${eligibility.threshold.maxLines}); this change is ${eligibility.scope.filesChanged} files / ${eligibility.scope.linesChanged} lines. Provide --issue <n> for above-threshold changes.`);
+  }
+  return {
+    intent: "start_issue_locally",
+    mode: "bounded_handoff",
+    targetPreference: "prefer_local",
+    artifactState: "not_applicable",
+    issueLinkageResolution: "not_applicable",
+    issueReadiness: "not_applicable",
+    issueAssignmentState: "not_applicable",
+    loopState: "implementation_pending",
+    canonicalSpecSource: "pr_body",
+    planFileExempt: true,
+    currentState: {
+      target: { kind: "local_phase", issue: null, pr: null, linkedPr: null, branch: null, phase: "lightweight-issueless" },
+      ownership: "local",
+      nextActor: "local",
+      status: "active",
+      authorization: "authorized",
+    },
+  };
+}
 export function summarizeCanonicalState(bundle) {
   return {
     target: bundle.canonicalState?.target ?? null,
@@ -541,7 +704,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 +818,7 @@ export function buildResolveDevLoopStartupResult(input, { adapter = createPiAdap
     canonicalStateSummary: summarizeCanonicalState(bundle),
     ...(planFileIntakeState !== null ? { planFileIntakeState } : {}),
     ...(spikeIntakeState !== null ? { spikeIntakeState } : {}),
+    ...(canonicalSpecSource !== null ? { canonicalSpecSource } : {}),
     bundle,
   };
 }
@@ -672,7 +839,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 +860,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 +870,19 @@ 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 if (options.lightweight) {
+    // --lightweight used ALONE (no other mode flag): issue-less PR-first (#1210).
+    // A broken config must surface as ITS OWN failure, not decay to the
+    // misleading light_mode_disabled reason a bare {version:1} would produce.
+    if (configErrors.length > 0) {
+      throw new Error(`--lightweight without --issue (issue-less PR-first) requires a loadable dev-loop config, but config loading failed: ${configErrors.map((e) => e?.message ?? String(e)).join("; ")}. Fix the config or provide --issue <n>.`);
+    }
+    input = buildLightweightIssuelessInput({ config: devLoopConfig, cwd: repoRoot });
   } else {
     input = buildAutoResolvedInput({
       pr: options.pr,
@@ -711,11 +892,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",
@@ -78,6 +81,7 @@ export function parseCliArgs(argv) {
     options: {
       help: { type: "boolean", short: "h" },
       repo: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -98,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) {
@@ -280,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(),
@@ -295,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;