dev-loops 0.5.0 → 0.7.1

package/scripts/projects/reorder-queue-item.mjs

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { runChild as _runChild } from "../_cli-primitives.mjs";
+import { resolveProjectSelector, findProject, applyDevloopsBoard } from "./_resolve-project.mjs";
 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 reorder --repo <owner/name> --project <number|id> --item <number|node-id> [--after <number|node-id>]
-  dev-loops queue reorder move-to-top <ref> --repo <owner/name> --project <number|id>
-  dev-loops queue reorder move-after <ref> <after-ref> --repo <owner/name> --project <number|id>
-  dev-loops queue reorder order <ref1> <ref2> ... --repo <owner/name> --project <number|id>
+  dev-loops queue reorder --repo <owner/name> --project <number|id|board-uri> --item <number|node-id> [--after <number|node-id>]
+  dev-loops queue reorder move-to-top <ref> --repo <owner/name> --project <number|id|board-uri>
+  dev-loops queue reorder move-after <ref> <after-ref> --repo <owner/name> --project <number|id|board-uri>
+  dev-loops queue reorder order <ref1> <ref2> ... --repo <owner/name> --project <number|id|board-uri>
   (dev-loops project reorder … is a back-compat alias)
 
 Reorder GitHub Projects V2 items by board position via updateProjectV2ItemPosition.
@@ -22,22 +24,27 @@ Forms:
 A <ref> is an issue/PR number OR a project item node ID. Works for both issues and PRs.
 
 Options:
-  --repo <owner/name>         Required. Repository to scope the project search.
-  --project <number|id>       Required. Project number (integer) or node ID.
-  --item <number|node-id>     Flag form: item to reorder.
-  --after <number|node-id>    Flag form: position after this item. When omitted, move to top.
-  --dry-run                   Print the intended GraphQL mutation(s) without executing.
-  --help, -h                  Show this help.
+  --repo <owner/name>                 Required. Repository to scope the project search.
+  --project <number|id|board-uri>     Project number, node ID, or board URI
+                                      (e.g. https://github.com/users/me/projects/3).
+                                      When omitted, resolved from .devloops
+                                      queue.projectNumber / queue.boardTitle.
+  --item <number|node-id>             Flag form: item to reorder.
+  --after <number|node-id>            Flag form: position after this item. When omitted, move to top.
+  --dry-run                           Print the intended GraphQL mutation(s) without executing.
+  --help, -h                          Show this help.
 
 Output (stdout):
   JSON. Move/move-to-top: { ok, item, after_ref|null, before, after }.
         order: { ok, moves: [...], before, after }.
         dry-run: { ok, dryRun: true, mutations: [{ query, variables }], before }.
 
+${JQ_OUTPUT_USAGE}
+
 Exit codes:
   0 — success
   1 — usage or argument error
-  2 — GitHub API error
+  2 — GitHub API error / invalid --jq filter
   3 — project, item, or after-item not found
 `.trim();
 
@@ -70,6 +77,7 @@ function parseCliArgs(argv) {
       after: { type: "string" },
       "dry-run": { type: "boolean" },
       help: { type: "boolean", short: "h" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -109,8 +117,10 @@ function parseCliArgs(argv) {
         }
         args.dryRun = true;
         break;
-      default:
+      default: {
+        if (matchJqOutputToken(token, args, (t) => requireValue(t, "--jq requires a filter"))) break;
         throw parseError(`Unknown flag: ${token.rawName}`);
+      }
     }
   }
   return args;
@@ -144,24 +154,6 @@ function validateRepo(repo) {
   return repo;
 }
 
-function parseProjectRef(raw) {
-  if (!raw || typeof raw !== "string" || raw.trim().length === 0) {
-    throw Object.assign(new Error("--project is required"), { code: "INVALID_PROJECT" });
-  }
-  const trimmed = raw.trim();
-  const asNum = Number(trimmed);
-  if (Number.isInteger(asNum) && asNum > 0 && String(asNum) === trimmed) {
-    return { kind: "number", value: asNum };
-  }
-  if (trimmed === "0") {
-    throw Object.assign(new Error(`--project must be a positive integer or a node ID, got "${raw}"`), { code: "INVALID_PROJECT" });
-  }
-  if (GLOBAL_NODE_ID_RE.test(trimmed)) {
-    return { kind: "id", value: trimmed };
-  }
-  throw Object.assign(new Error(`--project must be a positive integer or a node ID, got "${raw}"`), { code: "INVALID_PROJECT" });
-}
-
 function parseItemRef(raw) {
   if (!raw || typeof raw !== "string" || raw.trim().length === 0) {
     throw Object.assign(new Error("--item is required"), { code: "INVALID_ITEM" });
@@ -522,19 +514,17 @@ function classifyExitCode(err) {
 
 // ── Resolve owner + project (shared) ──────────────────────────────────────
 
-async function resolveProject(owner, projectRef, env, child) {
-  const { kind: ownerKind } = await resolveOwner(owner, env, child);
-  const projects = await listAllProjects(owner, ownerKind, env, child);
-  const project = projectRef.kind === "id"
-    ? projects.find((p) => p.id === projectRef.value)
-    : projects.find((p) => p.number === projectRef.value);
-  if (!project) {
-    throw Object.assign(
-      new Error(`Project ${projectRef.kind === "id" ? `"${projectRef.value}"` : `number ${projectRef.value}`} not found under owner "${owner}"`),
-      { code: "PROJECT_NOT_FOUND" },
-    );
-  }
-  return project;
+// Resolve the project based on a selector (from resolveProjectSelector).
+// When the selector contains a URI ref, the URI-encoded owner overrides the
+// repo-derived owner so cross-scope boards (user vs org) resolve unambiguously.
+async function resolveProject(repoOwner, selector, env, child) {
+  const projectRef = selector.projectRef;
+  const effectiveOwner = projectRef?.kind === "uri" ? projectRef.owner : repoOwner;
+  const ownerKind = projectRef?.kind === "uri"
+    ? projectRef.ownerKind
+    : (await resolveOwner(repoOwner, env, child)).kind;
+  const projects = await listAllProjects(effectiveOwner, ownerKind, env, child);
+  return findProject(projects, selector, effectiveOwner);
 }
 
 function executePosition(projectId, itemId, afterId) {
@@ -742,7 +732,7 @@ async function main(args, { env = process.env, runChild } = {}) {
   const child = runChild ?? _runChild;
   const repo = validateRepo(args.repo);
   const [owner, repoName] = repo.split("/");
-  const projectRef = parseProjectRef(args.project);
+  const selector = resolveProjectSelector(args);
 
   // Fail closed: the legacy flag form takes no positional arguments. A stray
   // token (e.g. `reorder 630 --item ...`) must not be silently ignored.
@@ -753,7 +743,7 @@ async function main(args, { env = process.env, runChild } = {}) {
     );
   }
 
-  const project = await resolveProject(owner, projectRef, env, child);
+  const project = await resolveProject(owner, selector, env, child);
 
   if (args._subcommand) {
     return mainSubcommand(args, { env, child, repo, project });
@@ -763,7 +753,7 @@ async function main(args, { env = process.env, runChild } = {}) {
 
 // ── CLI entrypoint ──────────────────────────────────────────────────────
 
-async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env } = {}) {
+async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env, cwd = process.cwd() } = {}) {
   let args;
   try {
     args = parseCliArgs(argv);
@@ -776,9 +766,13 @@ async function runCli(argv, { stdout = process.stdout, stderr = process.stderr,
     stdout.write(USAGE);
     return;
   }
+
+  // Resolve the board from .devloops when --project is absent.
+  applyDevloopsBoard(args, cwd);
+
   try {
     const result = await main(args, { env });
-    stdout.write(JSON.stringify(result) + "\n");
+    process.exitCode = emitResult(result, { jq: args.jq, silent: args.silent, stdout, stderr });
   } catch (err) {
     stderr.write(JSON.stringify({ ok: false, error: err.message, code: err.code ?? "UNKNOWN" }) + "\n");
     process.exitCode = classifyExitCode(err);

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

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+// 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.
+//
+//   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, 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>
+
+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.
+  --project <number|id>   Required. Project number (integer) or node ID.
+  --help, -h              Show this help.
+
+Output (stdout):
+  JSON, exactly one in-progress item:
+    { 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 — 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): 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 =
+invalid filter) — fail closed surfaces as a falsy \`.ok\`, i.e. exit 1, not 3.
+`.trim();
+
+function parseCliArgs(argv) {
+  const parseError = (message) => Object.assign(new Error(message), { usage: USAGE, code: "INVALID_ARGS" });
+  const requireValue = (token, message) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0 || v.startsWith("-")) {
+      throw parseError(message);
+    }
+    return v;
+  };
+
+  const args = {};
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      repo: { type: "string" },
+      project: { type: "string" },
+      help: { type: "boolean", short: "h" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unexpected argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    switch (token.name) {
+      case "help":
+        if (token.value !== undefined) {
+          throw parseError(`Unknown flag: ${token.rawName}=${token.value}`);
+        }
+        args.help = true;
+        break;
+      case "repo":
+        args.repo = requireValue(token, "--repo requires a value (owner/name)");
+        break;
+      case "project":
+        args.project = requireValue(token, "--project requires a value (number or node ID)");
+        break;
+      default: {
+        if (matchJqOutputToken(token, args, (t) => requireValue(t, "--jq requires a filter"))) break;
+        throw parseError(`Unknown flag: ${token.rawName}`);
+      }
+    }
+  }
+  return args;
+}
+
+function describeItem(item) {
+  const ref = item.prNumber != null ? `PR #${item.prNumber}` : `issue #${item.issueNumber}`;
+  return item.title ? `${ref} (${item.title})` : ref;
+}
+
+// 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 > 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. \`/loop-continue #N\`.`,
+    };
+  }
+  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, 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: inProgressColumn },
+    { env, runChild },
+  );
+  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) {
+  if (err.code === "INVALID_ARGS" || err.code === "INVALID_REPO" || err.code === "INVALID_PROJECT") return 1;
+  if (err.code === "PROJECT_NOT_FOUND" || err.code === "FIELD_NOT_FOUND" || err.code === "COLUMN_NOT_FOUND") return 3;
+  return 2;
+}
+
+async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env, runChild, cwd = process.cwd() } = {}) {
+  let args;
+  try {
+    args = parseCliArgs(argv);
+  } catch (err) {
+    stderr.write(`${formatCliError(err)}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (args.help) {
+    stdout.write(USAGE);
+    return;
+  }
+  try {
+    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, {
+      jq: args.jq,
+      silent: args.silent,
+      stdout,
+      stderr,
+      ok: result.ok,
+    });
+    if (result.ok !== true && args.jq === undefined && !args.silent) {
+      process.exitCode = 3;
+    }
+  } catch (err) {
+    stderr.write(JSON.stringify({ ok: false, error: err.message, code: err.code ?? "UNKNOWN" }) + "\n");
+    process.exitCode = classifyExitCode(err);
+  }
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(JSON.stringify({ ok: false, error: error.message, code: error.code ?? "UNKNOWN" }) + "\n");
+    process.exitCode = 2;
+  });
+}
+
+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)`,