dev-loops 0.6.0 → 0.7.2

package/scripts/projects/resolve-active-board-item.mjs

@@ -1,28 +1,42 @@
 #!/usr/bin/env node
-// Collapse the board's "In Progress" column to a SINGLE continue target (#988 P1).
+// Resolve the board's single continue target for the live `/loop-continue` path
+// (#988 P1, extended #1091). It lists the "In Progress" column and, failing
+// that, the "Next Up" column via list-queue-items.mjs — with NO routing opinions
+// beyond a single pick and NO guessing. It never touches Backlog.
 //
-// Pure list->single-target collapse with NO routing opinions: it lists the
-// In-Progress items via list-queue-items.mjs and either returns the lone target
-// or FAILS CLOSED. It never guesses among multiple active items.
-//
-//   exactly one  -> { ok: true, target: { kind: "issue"|"pr", number } }
-//   zero         -> { ok: false, reason: "..." }  (no in-progress item)
-//   multiple     -> { ok: false, reason: "..." }  (names the items)
+//   exactly one In Progress   -> { ok: true, target: {kind,number}, source: "in-progress" }
+//   multiple In Progress      -> { ok: false, reason: "..." }  (names the items)
+//   zero In Progress:
+//     Next Up has items        -> { ok: true, target: {kind,number}, source: "next-up" }
+//                                  (HEAD of Next Up, by POSITION ascending)
+//     Next Up empty            -> { ok: false, reason: <canonical empty-queue msg>, source: "next-up" }
+//     Next Up query errors     -> propagates (fail closed — surface it, no fallback)
 //
 // Downstream (the dev-loop skill) resolves authoritative state from this number;
 // this helper deliberately makes no further decisions.
 import { formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { parseArgs } from "node:util";
-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";
 import { main as listQueueItems } from "./list-queue-items.mjs";
+import { EMPTY_NEXT_UP_MESSAGE } from "@dev-loops/core/loop/queue-board-ordering";
+import { loadStateColumnMap, LOGICAL_COLUMN } from "@dev-loops/core/loop/queue-board-sync";
 
+// Illustrative default labels for USAGE/help + comments only; the actual query
+// columns resolve through queue.statusColumns.in_progress / .next_up at
+// runtime (#1098, #1143).
 const IN_PROGRESS_COLUMN = "In Progress";
+const NEXT_UP_COLUMN = "Next Up";
+// Canonical fail-closed empty-queue message — matches queue-driver.mjs so
+// operators see one string regardless of which layer detects it (#1091).
+const EMPTY_QUEUE_REASON = EMPTY_NEXT_UP_MESSAGE;
 
 const USAGE = `Usage: dev-loops queue resolve-active --repo <owner/name> --project <number|id>
 
-Collapse the board's "${IN_PROGRESS_COLUMN}" column to a single continue target.
-Used by bare \`/continue\` to pick up the one in-progress item. Fails closed
-(no guessing) when the board has zero or more than one in-progress item.
+Resolve the board's single continue target for bare \`/loop-continue\`:
+continues the one "${IN_PROGRESS_COLUMN}" item; if there is none, picks the HEAD
+of "${NEXT_UP_COLUMN}" by POSITION ascending. Fails closed (no guessing) on
+multiple in-progress items, and when "${NEXT_UP_COLUMN}" is empty. Never pulls
+from Backlog.
 
 Options:
   --repo <owner/name>     Required. Repository to scope the project search.
@@ -31,19 +45,21 @@ Options:
 
 Output (stdout):
   JSON, exactly one in-progress item:
-    { ok: true, target: { kind: "issue"|"pr", number } }
-  JSON, zero or multiple (fail closed):
+    { ok: true, target: { kind: "issue"|"pr", number }, source: "in-progress" }
+  JSON, zero in-progress + "${NEXT_UP_COLUMN}" head:
+    { ok: true, target: { kind: "issue"|"pr", number }, source: "next-up" }
+  JSON, fail closed (multiple in-progress, or empty "${NEXT_UP_COLUMN}"):
     { ok: false, reason: "..." }
 
 ${JQ_OUTPUT_USAGE}
 
 Exit codes (default / unfiltered output):
-  0 — exactly one in-progress item resolved
+  0 — a single continue target resolved (in-progress or "${NEXT_UP_COLUMN}" head)
   1 — usage or argument error
   2 — GitHub API error / invalid --jq filter
-  3 — fail closed (pass an explicit issue/PR): zero or multiple in-progress
-      items, or the board/project could not be resolved (project, status
-      field, or "${IN_PROGRESS_COLUMN}" column not found)
+  3 — fail closed (pass an explicit issue/PR): multiple in-progress items, an
+      empty "${NEXT_UP_COLUMN}" column, or the board/project could not be
+      resolved (project, status field, or the column not found)
 
 With --jq/--silent the result is filtered to a value/predicate, so the exit code
 follows the shared jq-output contract (0 = truthy/ok, 1 = falsy/non-ok, 2 =
@@ -94,14 +110,10 @@ function parseCliArgs(argv) {
       case "project":
         args.project = requireValue(token, "--project requires a value (number or node ID)");
         break;
-      case "jq":
-        args.jq = requireValue(token, "--jq requires a filter");
-        break;
-      case "silent":
-        args.silent = true;
-        break;
-      default:
+      default: {
+        if (matchJqOutputToken(token, args, (t) => requireValue(t, "--jq requires a filter"))) break;
         throw parseError(`Unknown flag: ${token.rawName}`);
+      }
     }
   }
   return args;
@@ -112,36 +124,86 @@ function describeItem(item) {
   return item.title ? `${ref} (${item.title})` : ref;
 }
 
-// Collapse a list of board items to a single continue target. Prefer the linked
-// PR number when present (the canonical artifact once work is in flight), else
-// the issue. No routing opinion beyond that single pick.
+// Prefer the linked PR number when present (the canonical artifact once work is
+// in flight), else the issue. No routing opinion beyond that single pick.
+function itemToTarget(item) {
+  return item.prNumber != null
+    ? { kind: "pr", number: item.prNumber }
+    : { kind: "issue", number: item.issueNumber };
+}
+
+// Collapse the "In Progress" column to a single continue target. The caller only
+// invokes this with a NON-EMPTY column (zero In Progress falls through to
+// resolveNextUpHead in main()), so this only decides among the in-progress items
+// and never guesses when there is more than one.
 function collapseToTarget(items) {
-  if (items.length === 0) {
-    return {
-      ok: false,
-      reason: `No in-progress board item to continue. Pass an explicit issue/PR, e.g. \`/continue #N\`.`,
-    };
-  }
   if (items.length > 1) {
     const listed = items.map(describeItem).join(", ");
     return {
       ok: false,
-      reason: `${items.length} in-progress board items: ${listed}. Pass an explicit issue/PR to disambiguate, e.g. \`/continue #N\`.`,
+      reason: `${items.length} in-progress board items: ${listed}. Pass an explicit issue/PR to disambiguate, e.g. \`/loop-continue #N\`.`,
     };
   }
-  const item = items[0];
-  const target = item.prNumber != null
-    ? { kind: "pr", number: item.prNumber }
-    : { kind: "issue", number: item.issueNumber };
-  return { ok: true, target };
+  return { ok: true, target: itemToTarget(items[0]), source: "in-progress" };
+}
+
+// Zero in-progress: the live continue path falls through to the "Next Up"
+// column, HEAD by POSITION ascending (list-queue-items returns position order).
+// NEVER pulls from Backlog; empty Next Up fails closed with the canonical
+// message, and a query error propagates (fail closed — surface it, no fallback).
+async function resolveNextUpHead(args, { env, runChild, cwd = process.cwd() } = {}) {
+  // Resolve the next_up column name through the SAME statusColumns mapping
+  // board-sync uses (#1098): a repo that renamed Next Up (e.g. to "Todo") gets
+  // its configured column queried, not the literal default. Pickup SEMANTICS
+  // (position-ascending HEAD, fail-closed on empty, never Backlog) are unchanged.
+  const { columnNames, error: configError } = loadStateColumnMap(cwd);
+  if (configError) {
+    // A malformed `.devloops` must fail CLOSED — never silently fall back to the
+    // literal "Next Up" and risk selecting the wrong item from a stale/renamed
+    // column (#1098). Throw so the CLI surfaces it (exit 2), mirroring a Next Up
+    // query error's "propagate, no fallback" contract.
+    throw Object.assign(
+      new Error(`could not resolve next_up column (config read/parse error: ${configError})`),
+      { code: "CONFIG_ERROR" },
+    );
+  }
+  const nextUpColumn = columnNames[LOGICAL_COLUMN.NEXT_UP];
+  const listed = await listQueueItems(
+    { repo: args.repo, project: args.project, column: nextUpColumn },
+    { env, runChild },
+  );
+  const items = listed.items ?? [];
+  if (items.length === 0) {
+    return { ok: false, reason: EMPTY_QUEUE_REASON, source: "next-up" };
+  }
+  return { ok: true, target: itemToTarget(items[0]), source: "next-up" };
 }
 
-async function main(args, { env = process.env, runChild } = {}) {
+async function main(args, { env = process.env, runChild, cwd = process.cwd() } = {}) {
+  // Resolve the in_progress column name through the SAME statusColumns mapping
+  // board-sync uses (#1098, #1143): a repo that renamed In Progress gets its
+  // configured column queried, not the literal default. Fail CLOSED on a
+  // malformed `.devloops` — never silently query the literal "In Progress"
+  // and risk missing the active item on a renamed/stale column.
+  const { columnNames, error: configError } = loadStateColumnMap(cwd);
+  if (configError) {
+    throw Object.assign(
+      new Error(`could not resolve in_progress column (config read/parse error: ${configError})`),
+      { code: "CONFIG_ERROR" },
+    );
+  }
+  const inProgressColumn = columnNames[LOGICAL_COLUMN.IN_PROGRESS];
   const listed = await listQueueItems(
-    { repo: args.repo, project: args.project, column: IN_PROGRESS_COLUMN },
+    { repo: args.repo, project: args.project, column: inProgressColumn },
     { env, runChild },
   );
-  return collapseToTarget(listed.items ?? []);
+  const items = listed.items ?? [];
+  // Exactly one → continue it. Multiple → fail closed (never guess). Zero →
+  // fall through to the Next Up head (the live pickup path, #1091).
+  if (items.length === 0) {
+    return resolveNextUpHead(args, { env, runChild, cwd });
+  }
+  return collapseToTarget(items);
 }
 
 function classifyExitCode(err) {
@@ -150,7 +212,7 @@ function classifyExitCode(err) {
   return 2;
 }
 
-async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env, runChild } = {}) {
+async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env, runChild, cwd = process.cwd() } = {}) {
   let args;
   try {
     args = parseCliArgs(argv);
@@ -164,7 +226,7 @@ async function runCli(argv, { stdout = process.stdout, stderr = process.stderr,
     return;
   }
   try {
-    const result = await main(args, { env, runChild });
+    const result = await main(args, { env, runChild, cwd });
     // Fail closed (zero/multiple) is a clean, expected outcome — distinct exit code 3,
     // not a crash; --jq/--silent still apply so callers can probe `.ok`.
     process.exitCode = emitResult(result, {
@@ -190,4 +252,4 @@ if (isDirectCliRun(import.meta.url)) {
   });
 }
 
-export { main, collapseToTarget, runCli };
+export { main, collapseToTarget, resolveNextUpHead, runCli };

package/scripts/projects/sync-item-status.mjs

@@ -3,6 +3,7 @@ import { formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { runChild as _runChild } from "../_cli-primitives.mjs";
 import { syncBoardStatus } from "@dev-loops/core/loop/queue-board-sync";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage: dev-loops queue sync-status --repo <owner/name> --item <number> --to-column <name>
        (dev-loops project sync-status … is a back-compat alias)
@@ -26,9 +27,12 @@ Output (stdout):
     { ok: true, skipped: false, result: { item: { newColumn } } }
     { ok: true, skipped: true, reason: "board not configured" }
 
+${JQ_OUTPUT_USAGE}
+
 Exit codes:
   0 — always on a parsed command (best-effort sync; skips/failures are reported in JSON)
   1 — usage or argument error
+  2 — invalid --jq filter
 `.trim();
 
 function parseCliArgs(argv) {
@@ -48,6 +52,7 @@ function parseCliArgs(argv) {
       item: { type: "string" },
       "to-column": { type: "string" },
       help: { type: "boolean", short: "h" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -77,8 +82,10 @@ function parseCliArgs(argv) {
       case "to-column":
         args.toColumn = requireValue(token, "--to-column requires a value", "INVALID_COLUMN");
         break;
-      default:
+      default: {
+        if (matchJqOutputToken(token, args, (t) => requireValue(t, "--jq requires a filter", "INVALID_ARGS"))) break;
         throw Object.assign(new Error(`Unknown flag: ${token.rawName}`), { code: "INVALID_ARGS", usage: USAGE });
+      }
     }
   }
   return args;
@@ -174,17 +181,15 @@ async function runCli(argv, { stdout = process.stdout, stderr = process.stderr,
       return;
     }
     // Defensive: any unexpected error stays best-effort/non-fatal — report it
-    // as a skip and keep exit 0 so it never blocks the PR/merge caller.
-    stdout.write(JSON.stringify({ ok: true, skipped: true, reason: err.message ?? "board sync failed" }) + "\n");
-    // Explicitly assert success: a pre-existing non-zero process.exitCode from a
-    // long-lived caller must not leak through this best-effort path.
-    process.exitCode = 0;
+    // as a skip and keep exit 0 (ok:true) so it never blocks the PR/merge caller,
+    // unless --jq/--silent turns a filter/predicate into a non-zero exit — same
+    // shared contract as the normal result path below.
+    process.exitCode = emitResult({ ok: true, skipped: true, reason: err.message ?? "board sync failed" }, { jq: args.jq, silent: args.silent, stdout, stderr });
     return;
   }
-  stdout.write(JSON.stringify(result) + "\n");
-  // Best-effort contract: a parsed command always reports success. Explicitly
-  // clear any pre-existing non-zero process.exitCode so it cannot leak.
-  process.exitCode = 0;
+  // Best-effort contract: result.ok is always true, so without --jq/--silent this
+  // always exits 0. An invalid --jq filter still fails closed (exit 2).
+  process.exitCode = emitResult(result, { jq: args.jq, silent: args.silent, stdout, stderr });
 }
 
 if (isDirectCliRun(import.meta.url)) {

package/scripts/refine/_refine-helpers.mjs

@@ -5,6 +5,7 @@ import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "
 import { parseArgs } from "node:util";
 import { parsePositiveInteger, requireTokenValue, runChild } from "../_cli-primitives.mjs";
 import { detectRepoSlug, parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 export const FORBIDDEN_PROSE_PATTERNS = [
   /Child of #/iu,
@@ -16,7 +17,12 @@ export const FORBIDDEN_PROSE_PATTERNS = [
 export const DEFAULT_USAGE_SUFFIX = `
 Output:
   Default output is human-readable text.
-  Add --json for machine-readable JSON.`.trim();
+  Add --json for machine-readable JSON.
+
+${JQ_OUTPUT_USAGE}
+(--jq/--silent only apply together with --json; the verdict is always in the
+payload, never the exit code — a parsed --json run always exits 0 unless
+--jq/--silent explicitly turns the verdict into the exit code.)`.trim();
 
 export function normalizeIssueNumber(value, label, parseError) {
   return parsePositiveInteger(value, label, parseError);
@@ -26,7 +32,12 @@ export function parseCheckerCliArgs(argv, usage, checkerName) {
   const parseError = buildParseError(usage);
   const { tokens } = parseArgs({
     args: [...argv],
-    options: { help: { type: "boolean", short: "h" }, input: { type: "string" }, json: { type: "boolean" } },
+    options: {
+      help: { type: "boolean", short: "h" },
+      input: { type: "string" },
+      json: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
     allowPositionals: true,
     strict: false,
     tokens: true,
@@ -51,6 +62,7 @@ export function parseCheckerCliArgs(argv, usage, checkerName) {
       options.json = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (typeof options.input !== "string" || options.input.trim().length === 0) {
@@ -262,10 +274,13 @@ export function normalizeScopeToken(value) {
     .replace(/\s+/gu, " ");
 }
 
-export function writeCheckerOutput(result, { stdout = process.stdout, json = false }) {
+// Returns the process exit code to use. Documented contract: the verdict lives
+// in the payload, not the exit code — a parsed --json run exits 0 even when
+// result.ok is false, unless --jq/--silent explicitly turns the verdict into
+// the exit code (predicate/--silent semantics from the shared jq-output contract).
+export function writeCheckerOutput(result, { stdout = process.stdout, stderr = process.stderr, json = false, jq, silent }) {
   if (json) {
-    stdout.write(`${JSON.stringify(result)}\n`);
-    return;
+    return emitResult(result, { jq, silent, stdout, stderr, ok: true });
   }
 
   const status = result.ok ? "PASS" : "FAIL";
@@ -279,6 +294,7 @@ export function writeCheckerOutput(result, { stdout = process.stdout, json = fal
     }
   }
   stdout.write(`${lines.join("\n")}\n`);
+  return 0;
 }
 
 

package/scripts/refine/exit-spike.mjs

@@ -17,6 +17,7 @@ import {
   SPIKE_EXIT_ACTION,
   SPIKE_EXIT_DISPOSITION,
 } from "@dev-loops/core/loop/spike-exit-contract";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage:
   exit-spike.mjs --spike-file <path> --disposition <discard|graduate> [--plan-file <path>] [--json]
@@ -41,9 +42,14 @@ Optional:
   --plan-file <path>     Output plan-file path (required for graduate)
   --json                 Machine-readable JSON output
   --help                 Show this help
+
+${JQ_OUTPUT_USAGE}
+(--jq/--silent only apply together with --json; the default text output is unaffected.)
+
 Exit codes:
   0  Exit succeeded (discard recorded; or plan file written for graduate)
-  1  Argument error, or fail-closed (not ready / unknown disposition)`.trim();
+  1  Argument error, or fail-closed (not ready / unknown disposition)
+  2  Invalid --jq filter`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -56,6 +62,7 @@ export function parseExitSpikeCliArgs(argv) {
       disposition: { type: "string" },
       "plan-file": { type: "string" },
       json: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -87,6 +94,7 @@ export function parseExitSpikeCliArgs(argv) {
       options.json = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (typeof options.spikeFile !== "string" || options.spikeFile.trim().length === 0) {
@@ -104,11 +112,14 @@ export function parseExitSpikeCliArgs(argv) {
   return options;
 }
 
-function emit(stdout, json, summary, humanLines) {
-  if (json) {
-    stdout.write(`${JSON.stringify(summary)}\n`);
+// Sets process.exitCode from `summary.ok` (0/1), or the shared --jq/--silent
+// contract's exit code (0/1/2) when --json + --jq/--silent are in play.
+function emit(stdout, options, summary, humanLines) {
+  if (options.json) {
+    process.exitCode = emitResult(summary, { jq: options.jq, silent: options.silent, stdout });
   } else {
     stdout.write(`${humanLines.join("\n")}\n`);
+    process.exitCode = summary.ok ? 0 : 1;
   }
 }
 
@@ -136,15 +147,14 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   if (!decision.ok) {
     // Fail closed: no tracker artifact, no plan file — surface the reason.
     const summary = { ok: false, reason: decision.reason, spikeIntakeState: decision.spikeIntakeState ?? spikeIntakeState };
-    emit(stdout, options.json, summary, [`exit-spike: FAIL (${decision.reason})`]);
-    process.exitCode = 1;
+    emit(stdout, options, summary, [`exit-spike: FAIL (${decision.reason})`]);
     return summary;
   }
 
   // DISCARD: zero artifacts. The findings doc on disk is the whole record.
   if (decision.action === SPIKE_EXIT_ACTION.DISCARD) {
     const summary = { ok: true, action: SPIKE_EXIT_ACTION.DISCARD, spikeFile: spikePath };
-    emit(stdout, options.json, summary, [
+    emit(stdout, options, summary, [
       "exit-spike: PASS (discard)",
       `  spike: ${spikePath}`,
       "  no tracker artifact created (findings doc is the record)",
@@ -170,7 +180,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
     spikeFile: spikePath,
     planFile: planPath,
   };
-  emit(stdout, options.json, summary, [
+  emit(stdout, options, summary, [
     "exit-spike: PASS (graduate)",
     `  spike: ${spikePath}`,
     `  plan:  ${planPath} (local-first; promote with scripts/refine/promote-plan.mjs)`,

package/scripts/refine/promote-plan.mjs

@@ -17,6 +17,7 @@ import {
   writeLinkedPrNumber,
   PLAN_FILE_PROMOTE_ACTION,
 } from "@dev-loops/core/loop/plan-file-promote-contract";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const CREATE_PR_PATH = fileURLToPath(new URL("../github/create-pr.mjs", import.meta.url));
 
@@ -42,9 +43,14 @@ Optional:
   --branch <name>     Branch name to commit the plan on (default: derived from the plan path)
   --json              Machine-readable JSON output
   --help              Show this help
+
+${JQ_OUTPUT_USAGE}
+(--jq/--silent only apply together with --json; the default text output is unaffected.)
+
 Exit codes:
   0  Promotion succeeded (or idempotent no-op for an already-linked plan)
-  1  Argument error, or fail-closed (plan not ready / git / PR-create failure); no issue ever created`.trim();
+  1  Argument error, or fail-closed (plan not ready / git / PR-create failure); no issue ever created
+  2  Invalid --jq filter`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -57,6 +63,7 @@ export function parsePromotePlanCliArgs(argv) {
       base: { type: "string" },
       branch: { type: "string" },
       json: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -88,6 +95,7 @@ export function parsePromotePlanCliArgs(argv) {
       options.json = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (typeof options.planFile !== "string" || options.planFile.trim().length === 0) {
@@ -123,11 +131,14 @@ function parsePrNumberFromGhOutput(text) {
   return match ? Number.parseInt(match[1], 10) : null;
 }
 
-function emit(stdout, json, summary, humanLines) {
-  if (json) {
-    stdout.write(`${JSON.stringify(summary)}\n`);
+// Sets process.exitCode from `summary.ok` (0/1), or the shared --jq/--silent
+// contract's exit code (0/1/2) when --json + --jq/--silent are in play.
+function emit(stdout, options, summary, humanLines) {
+  if (options.json) {
+    process.exitCode = emitResult(summary, { jq: options.jq, silent: options.silent, stdout });
   } else {
     stdout.write(`${humanLines.join("\n")}\n`);
+    process.exitCode = summary.ok ? 0 : 1;
   }
 }
 
@@ -161,8 +172,7 @@ export async function runCli(argv = process.argv.slice(2), {
   if (!decision.ok) {
     // Fail closed: no git, no gh, no issue — surface the reason and stop.
     const summary = { ok: false, reason: decision.reason, planFileIntakeState: decision.planFileIntakeState ?? null };
-    emit(stdout, options.json, summary, [`promote-plan: FAIL (${decision.reason})`]);
-    process.exitCode = 1;
+    emit(stdout, options, summary, [`promote-plan: FAIL (${decision.reason})`]);
     return summary;
   }
 
@@ -174,7 +184,7 @@ export async function runCli(argv = process.argv.slice(2), {
       planFile: planPath,
       prNumber: decision.existingPrNumber,
     };
-    emit(stdout, options.json, summary, [
+    emit(stdout, options, summary, [
       "promote-plan: PASS (already promoted)",
       `  plan: ${planPath}`,
       `  pr: #${decision.existingPrNumber} (existing; opened nothing)`,
@@ -207,8 +217,7 @@ export async function runCli(argv = process.argv.slice(2), {
 
   const fail = (reason, detail) => {
     const summary = { ok: false, reason, detail: detail ?? null, planFile: planPath };
-    emit(stdout, options.json, summary, [`promote-plan: FAIL (${reason})${detail ? `: ${detail}` : ""}`]);
-    process.exitCode = 1;
+    emit(stdout, options, summary, [`promote-plan: FAIL (${reason})${detail ? `: ${detail}` : ""}`]);
     return summary;
   };
 
@@ -294,11 +303,10 @@ export async function runCli(argv = process.argv.slice(2), {
       branch,
       recovery: `gh pr create failed, so no PR was opened, but the plan is committed and branch ${branch} is pushed. Re-run promote-plan to recover: the commit step is idempotent (skips when nothing is staged) and the push is idempotent, so a clean re-run will retry opening the PR.`,
     };
-    emit(stdout, options.json, summary, [
+    emit(stdout, options, summary, [
       `promote-plan: FAIL (pr_create_failed)${detail ? `: ${detail}` : ""}`,
       `  branch: ${branch} (committed and pushed; no PR opened — re-run promote-plan to recover, it is idempotent and will retry opening the PR)`,
     ]);
-    process.exitCode = 1;
     return summary;
   }
   const prNumber = parsePrNumberFromGhOutput(prCreate.stdout);
@@ -315,11 +323,10 @@ export async function runCli(argv = process.argv.slice(2), {
       branch,
       recovery: `A draft PR was opened on branch ${branch} but its number could not be parsed from gh output. Find it with: gh pr list --head "${branch}" --json number,url. Then record the link with: node scripts/refine/promote-plan.mjs is idempotent only once the front-matter prNumber is set, so add it manually (prNumber: <n>) and commit ${planDocRelPath}.`,
     };
-    emit(stdout, options.json, summary, [
+    emit(stdout, options, summary, [
       `promote-plan: FAIL (pr_number_unparseable)`,
       `  branch: ${branch} (a draft PR is open; its number could not be parsed — recover via 'gh pr list --head "${branch}"')`,
     ]);
-    process.exitCode = 1;
     return summary;
   }
 
@@ -340,11 +347,10 @@ export async function runCli(argv = process.argv.slice(2), {
       prNumber,
       recovery: `PR #${prNumber} is open but the plan->PR link commit failed. ${planDocRelPath} now carries prNumber: ${prNumber} in its front-matter; record the link with: git add -- "${planDocRelPath}" && git commit -m "docs(plan): link to PR #${prNumber}" && git push.`,
     };
-    emit(stdout, options.json, summary, [
+    emit(stdout, options, summary, [
       `promote-plan: FAIL (${reason})${detail ? `: ${detail}` : ""}`,
       `  pr: #${prNumber} (open; plan->PR link NOT committed — recover manually)`,
     ]);
-    process.exitCode = 1;
     return summary;
   };
   const linkedMarkdown = writeLinkedPrNumber(markdownText, prNumber);
@@ -370,7 +376,7 @@ export async function runCli(argv = process.argv.slice(2), {
     branch,
     prNumber,
   };
-  emit(stdout, options.json, summary, [
+  emit(stdout, options, summary, [
     "promote-plan: PASS",
     `  plan: ${planPath}`,
     `  branch: ${branch}`,

package/scripts/refine/prose-linkage-detector.mjs

@@ -80,7 +80,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   }
   const tree = await loadTreeFromInput(options.input);
   const result = runProseLinkageDetector(tree);
-  writeCheckerOutput(result, { stdout, json: options.json });
+  process.exitCode = writeCheckerOutput(result, { stdout, json: options.json, jq: options.jq, silent: options.silent });
   return result;
 }
 

package/scripts/refine/refine-plan-file.mjs

@@ -13,6 +13,7 @@ import {
 } from "@dev-loops/core/loop/plan-file-refine-contract";
 import { PLAN_FILE_REFINEMENT_SECTIONS } from "@dev-loops/core/loop/plan-file-intake-contract";
 import { classifyDocsGrillFinding } from "../loop/docs-grill-contract.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage:
   refine-plan-file.mjs --plan-file <path> --payload <path> [--json]
@@ -31,9 +32,14 @@ Required:
 Optional:
   --json              Machine-readable JSON output
   --help              Show this help
+
+${JQ_OUTPUT_USAGE}
+(--jq/--silent only apply together with --json; the default text output is unaffected.)
+
 Exit codes:
   0  Refinement succeeded; plan written in place; stop for local human review
-  1  Argument error, or fail-closed refine/grill/ambiguous state (no write)`.trim();
+  1  Argument error, or fail-closed refine/grill/ambiguous state (no write)
+  2  Invalid --jq filter`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -45,6 +51,7 @@ export function parseRefinePlanFileCliArgs(argv) {
       "plan-file": { type: "string" },
       payload: { type: "string" },
       json: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -72,6 +79,7 @@ export function parseRefinePlanFileCliArgs(argv) {
       options.json = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (typeof options.planFile !== "string" || options.planFile.trim().length === 0) {
@@ -123,11 +131,12 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   if (!result.ok) {
     // Fail closed: surface the reason, do not write, do not advance, do not promote.
     if (options.json) {
-      stdout.write(`${JSON.stringify({ ok: false, reason: result.reason, planFileIntakeState: result.planFileIntakeState ?? null })}\n`);
+      const failurePayload = { ok: false, reason: result.reason, planFileIntakeState: result.planFileIntakeState ?? null };
+      process.exitCode = emitResult(failurePayload, { jq: options.jq, silent: options.silent, stdout });
     } else {
       stdout.write(`refine-plan-file: FAIL (${result.reason})\n`);
+      process.exitCode = 1;
     }
-    process.exitCode = 1;
     return result;
   }
 
@@ -142,7 +151,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
     grillDispositions: result.grillDispositions,
   };
   if (options.json) {
-    stdout.write(`${JSON.stringify(summary)}\n`);
+    process.exitCode = emitResult(summary, { jq: options.jq, silent: options.silent, stdout });
   } else {
     stdout.write(
       [