dev-loops 0.6.0 → 0.7.2

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) {

package/scripts/loop/sanctioned-commands.mjs

@@ -0,0 +1,106 @@
+/**
+ * Canonical sanctioned operation → wrapper command map (issue #1081).
+ *
+ * SINGLE SOURCE OF TRUTH for "which wrapper does a dev-loop subagent use for
+ * which GitHub/loop operation". Previously this knowledge was re-derived per
+ * handoff and scattered across SKILL.md / copilot-loop-operations.md /
+ * pr-lifecycle-contract.md, so subagents burned cycles rediscovering e.g.
+ * `gh pr ready` → scripts/github/ready-for-review.mjs.
+ *
+ * This lives in the CONSUMER layer (scripts/), NOT in @dev-loops/core, because
+ * the values are THIS repo's `scripts/...` wrapper paths. Core stays
+ * consumer-agnostic: it defines the envelope SHAPE and carries whatever
+ * `sanctionedCommands` object the consumer supplies. The
+ * `loop build-envelope` CLI injects this map into every emitted envelope so a
+ * spawned subagent receives it verbatim by DEFAULT, regardless of who wrote
+ * the handoff.
+ *
+ * Wrapper paths are repo-root-relative. A contract test
+ * (test/contracts/sanctioned-commands-exist.test.mjs) asserts every mapped
+ * wrapper exists on disk and fails closed if one is renamed/removed.
+ */
+
+export const SANCTIONED_COMMANDS = Object.freeze({
+  // Read-only lookups. Each value is the sanctioned wrapper; several also
+  // accept `loop info` as an equivalent aggregate read (noted in the doc).
+  reads: Object.freeze({
+    "pr-facts": "scripts/github/view-pr.mjs",
+    "ci-status": "scripts/github/probe-ci-status.mjs",
+    "ci-wait": "scripts/github/wait-pr-checks.mjs",
+    "ci-logs": "scripts/github/fetch-ci-logs.mjs",
+    "issue-list": "scripts/github/list-issues.mjs",
+    "copilot-review-state": "scripts/github/probe-copilot-review.mjs",
+    "review-threads": "scripts/github/list-review-threads.mjs",
+    "gate-coordination": "scripts/loop/detect-pr-gate-coordination-state.mjs",
+  }),
+
+  // Metadata edits.
+  edits: Object.freeze({
+    "pr-body-title-assignee-milestone": "scripts/github/edit-pr.mjs",
+    "issue-comment": "scripts/github/comment-issue.mjs",
+  }),
+
+  // Lifecycle mutations a subagent MAY perform (state transitions on the PR /
+  // review). Board status transitions are deliberately NOT here — they are
+  // orchestratorOwned (see below): in the current batch model the orchestrator
+  // owns board moves, and a subagent's In-Progress move rides ready-for-review.mjs
+  // (#1069), so there is no standalone subagent-sanctioned board-sync op.
+  lifecycle: Object.freeze({
+    "ready-for-review": "scripts/github/ready-for-review.mjs",
+    "pr-create": "scripts/github/create-pr.mjs",
+    "copilot-request": "scripts/github/request-copilot-review.mjs",
+    "reply-resolve-thread": "scripts/github/reply-resolve-review-thread.mjs",
+    "reply-resolve-threads": "scripts/github/reply-resolve-review-threads.mjs",
+    "gate-verdict-comment": "scripts/github/upsert-checkpoint-verdict.mjs",
+  }),
+
+  // Never allowed for any operation above — the sanctioned wrapper is mandatory.
+  forbidden: Object.freeze([
+    "gh pr view",
+    "gh pr checks",
+    "gh pr edit",
+    "node -e",
+    "node --input-type=module -e",
+    "node -p",
+    "python -c",
+    "python3 -c",
+    "tailing subagent transcripts",
+    "sleep-poll loops",
+  ]),
+
+  // Orchestrator-owned: a spawned dev-loop subagent must NEVER do these. Board
+  // status transitions live here (not in `lifecycle`) — the orchestrator owns
+  // move-queue-item/sync-item-status in the current batch model.
+  orchestratorOwned: Object.freeze([
+    "gh pr merge",
+    "board status transitions (move-queue-item / sync-item-status.mjs; current batch model)",
+  ]),
+});
+
+// The wrapper-path-bearing groups are the object-valued groups (reads/edits/
+// lifecycle); `forbidden`/`orchestratorOwned` are string arrays, not path maps.
+const PATH_GROUP_KEYS = Object.freeze(
+  Object.keys(SANCTIONED_COMMANDS).filter(
+    (k) => !Array.isArray(SANCTIONED_COMMANDS[k]),
+  ),
+);
+
+/**
+ * EVERY value named across the path-bearing groups — with NO shape filtering,
+ * so a malformed/typo'd entry is RETURNED (and then fails the contract test's
+ * shape+existence assertions) rather than being silently skipped. Auto-includes
+ * any future path-bearing group. This is what keeps the map from drifting off
+ * disk (#1081). For a well-formed map every element is a repo-root-relative
+ * `scripts/*.mjs` string; the no-filtering contract means a malformed map can
+ * yield a non-string here, which the contract test is designed to catch.
+ * @returns {unknown[]} wrapper-path values (strings for a well-formed map)
+ */
+export function listSanctionedWrapperPaths() {
+  const out = [];
+  for (const key of PATH_GROUP_KEYS) {
+    for (const value of Object.values(SANCTIONED_COMMANDS[key])) {
+      out.push(value);
+    }
+  }
+  return out;
+}

package/scripts/loop/steer-loop.mjs

@@ -34,6 +34,7 @@ import {
 import { formatCliError } from "../_core-helpers.mjs";
 import { requireTokenValue as readSharedTokenValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 const SUBMIT_USAGE = `Usage:
   steer-loop.mjs submit --repo <owner/name> --pr <number>
     --kind stop_at_next_safe_gate --directive <text> --seq <n>
@@ -61,7 +62,9 @@ Optional:
 Output (stdout, JSON):
   { "ok": true, "acknowledgement": { ... }, "result": { ... }, "steeringState": { ... } }
 Error output (stderr, JSON):
-  { "ok": false, "error": "...", "usage": "..." }`.trim();
+  { "ok": false, "error": "...", "usage": "..." }
+
+${JQ_OUTPUT_USAGE}`.trim();
 const STATUS_USAGE = `Usage:
   steer-loop.mjs status --run-id <id> [--state-file <path>]
   steer-loop.mjs status --repo <owner/name> --pr <number> [--state-file <path>]
@@ -75,7 +78,9 @@ Optional:
 Output (stdout, JSON):
   { "ok": true, "status": { ... } }
 Error output (stderr, JSON):
-  { "ok": false, "error": "...", "usage": "..." }`.trim();
+  { "ok": false, "error": "...", "usage": "..." }
+
+${JQ_OUTPUT_USAGE}`.trim();
 const PROMOTE_USAGE = `Usage:
   steer-loop.mjs promote --run-id <id> --loop-state <state> [--state-file <path>]
   steer-loop.mjs promote --repo <owner/name> --pr <number>
@@ -93,7 +98,9 @@ Optional:
 Output (stdout, JSON):
   { "ok": true, "promotedCount": <n>, "promoted": [ ... ], "steeringState": { ... } }
 Error output (stderr, JSON):
-  { "ok": false, "error": "...", "usage": "..." }`.trim();
+  { "ok": false, "error": "...", "usage": "..." }
+
+${JQ_OUTPUT_USAGE}`.trim();
 const TOP_USAGE = `Usage:
   steer-loop.mjs <subcommand> [options]
 Subcommands:
@@ -171,6 +178,7 @@ export function parseSubmitCliArgs(argv) {
       "event-id": { type: "string" },
       "copilot-input": { type: "string" },
       "reviewer-input": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -250,6 +258,7 @@ export function parseSubmitCliArgs(argv) {
       options.reviewerInputPath = readRequiredOptionValue(token, SUBMIT_USAGE);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => readRequiredOptionValue(t, SUBMIT_USAGE))) continue;
     throw usageError(`Unknown argument: ${token.rawName}`, SUBMIT_USAGE);
   }
   if (!options.help) {
@@ -290,6 +299,7 @@ export function parseStatusCliArgs(argv) {
       repo: { type: "string" },
       pr: { type: "string" },
       "state-file": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -324,6 +334,7 @@ export function parseStatusCliArgs(argv) {
       options.stateFile = readRequiredOptionValue(token, STATUS_USAGE);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => readRequiredOptionValue(t, STATUS_USAGE))) continue;
     throw usageError(`Unknown argument: ${token.rawName}`, STATUS_USAGE);
   }
   if (!options.help) {
@@ -357,6 +368,7 @@ export function parsePromoteCliArgs(argv) {
       pr: { type: "string" },
       "state-file": { type: "string" },
       "loop-state": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -399,6 +411,7 @@ export function parsePromoteCliArgs(argv) {
       options.loopState = val;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => readRequiredOptionValue(t, PROMOTE_USAGE))) continue;
     throw usageError(`Unknown argument: ${token.rawName}`, PROMOTE_USAGE);
   }
   if (!options.help) {
@@ -651,7 +664,7 @@ function rejectUnsteerableInspection(inspection, { runId, eventId, seq, directiv
 }
 export async function runSubmit(
   argv = [],
-  { stdout = process.stdout, cwd = process.cwd(), env = process.env, ghCommand = "gh" } = {},
+  { stdout = process.stdout, stderr = process.stderr, cwd = process.cwd(), env = process.env, ghCommand = "gh" } = {},
 ) {
   const options = parseSubmitCliArgs(argv);
   if (options.help) {
@@ -793,12 +806,12 @@ export async function runSubmit(
     } catch {
       steeringState = createSteeringState(runId, target);
     }
-    stdout.write(`${JSON.stringify({
+    process.exitCode = emitResult({
       ok: true,
       acknowledgement: validationRejection.acknowledgement,
       result: validationRejection.result,
       steeringState,
-    })}\n`);
+    }, { jq: options.jq, silent: options.silent, stdout, stderr });
     return;
   }
   const { steeringState: newState, result } = await withStateFileLock(stateFilePath, async () => {
@@ -828,9 +841,9 @@ export async function runSubmit(
     safePointCategory,
     readbackPath,
   });
-  stdout.write(`${JSON.stringify({ ok: true, acknowledgement, result, steeringState: newState })}\n`);
+  process.exitCode = emitResult({ ok: true, acknowledgement, result, steeringState: newState }, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
-export async function runStatus(argv = [], { stdout = process.stdout, cwd = process.cwd() } = {}) {
+export async function runStatus(argv = [], { stdout = process.stdout, stderr = process.stderr, cwd = process.cwd() } = {}) {
   const options = parseStatusCliArgs(argv);
   if (options.help) {
     stdout.write(`${STATUS_USAGE}\n`);
@@ -843,9 +856,9 @@ export async function runStatus(argv = [], { stdout = process.stdout, cwd = proc
   const stateFilePath = options.stateFile ?? (target ? defaultStateFilePathForTarget(target, cwd) : defaultStateFilePath(runId, cwd));
   const steeringState = await loadOrCreateSteeringState(stateFilePath, runId, target);
   const status = getSteeringStatus(steeringState);
-  stdout.write(`${JSON.stringify({ ok: true, status })}\n`);
+  process.exitCode = emitResult({ ok: true, status }, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
-export async function runPromote(argv = [], { stdout = process.stdout, cwd = process.cwd() } = {}) {
+export async function runPromote(argv = [], { stdout = process.stdout, stderr = process.stderr, cwd = process.cwd() } = {}) {
   const options = parsePromoteCliArgs(argv);
   if (options.help) {
     stdout.write(`${PROMOTE_USAGE}\n`);
@@ -864,16 +877,16 @@ export async function runPromote(argv = [], { stdout = process.stdout, cwd = pro
     }
     return nextState;
   });
-  stdout.write(`${JSON.stringify({
+  process.exitCode = emitResult({
     ok: true,
     promotedCount: promotedState.promoted.length,
     promoted: promotedState.promoted,
     steeringState: promotedState.steeringState,
-  })}\n`);
+  }, { jq: options.jq, silent: options.silent, stdout, stderr });
 }
 export async function runCli(
   argv = process.argv.slice(2),
-  { stdout = process.stdout, cwd = process.cwd(), env = process.env, ghCommand = "gh" } = {},
+  { stdout = process.stdout, stderr = process.stderr, cwd = process.cwd(), env = process.env, ghCommand = "gh" } = {},
 ) {
   const [subcommand, ...rest] = argv;
   if (!subcommand || subcommand === "--help" || subcommand === "-h") {
@@ -881,13 +894,13 @@ export async function runCli(
     return;
   }
   if (subcommand === "submit") {
-    return runSubmit(rest, { stdout, cwd, env, ghCommand });
+    return runSubmit(rest, { stdout, stderr, cwd, env, ghCommand });
   }
   if (subcommand === "promote") {
-    return runPromote(rest, { stdout, cwd });
+    return runPromote(rest, { stdout, stderr, cwd });
   }
   if (subcommand === "status") {
-    return runStatus(rest, { stdout, cwd });
+    return runStatus(rest, { stdout, stderr, cwd });
   }
   const error = usageError(`Unknown subcommand: ${subcommand}`, TOP_USAGE);
   throw error;

package/scripts/loop/validate-pr-body-spec.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * Validate that a PR body carries the invariants required to serve as the
+ * lightweight spec-of-record (issue #1025): Objective/why, in-scope, explicit
+ * non-goals, testable Acceptance criteria, Definition of done, and Open
+ * questions/risks.
+ *
+ * Thin CLI wrapper (parallel to detect-issue-refinement-artifact.mjs): fetches
+ * the PR body via `gh pr view <n> --json body` and runs the shared pure
+ * validator `validatePrBodySpec` (reuses issue-refinement-artifact markdown
+ * logic — no parallel validator). Fails closed (non-zero + per-section reason)
+ * when any invariant is missing.
+ */
+import { readFile } from "node:fs/promises";
+import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import { requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { parseArgs } from "node:util";
+import { validatePrBodySpec } from "@dev-loops/core/loop/issue-refinement-artifact";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
+
+const USAGE = `Usage:
+  validate-pr-body-spec.mjs --repo <owner/name> --pr <number> [--expected-issue <n>]
+  validate-pr-body-spec.mjs --input <path> [--expected-issue <n>]
+Validate that a PR body carries the lightweight spec-of-record invariants
+(Objective/why, In scope, Explicit non-goals, testable Acceptance criteria,
+Definition of done, Open questions/risks, and — unless --no-issue is given —
+a GitHub closing-keyword issue reference such as \`Closes #123\`).
+Required (exactly one):
+  --repo <owner/name> --pr <number>   Fetch the PR body via gh and validate it
+  --input <path>                      Path to a JSON file with { "body": "..." }
+                                      (optional "repo" and "pr" fields are echoed
+                                      back in the result when present)
+Optional:
+  --expected-issue <n>                Positive integer; the referenced closing
+                                      issue(s) must include this number, else
+                                      "closes_wrong_issue". Mutually exclusive
+                                      with --no-issue.
+  --no-issue                          Explicit issue-less mode (#1210): the PR
+                                      is the sole artifact, so a closing-issue
+                                      reference is FORBIDDEN rather than
+                                      required — one present fails closed under
+                                      "unexpected_closing_issue_reference".
+                                      Mutually exclusive with --expected-issue.
+Success output (stdout, JSON):
+  {
+    "ok": true | false,
+    "checker": "validate-pr-body-spec",
+    "repo": "owner/name" | null,
+    "pr": 123 | null,
+    "errors": [ { "code": "missing_...", "message": "..." } ],
+    "sections": [...],
+    "acItems": [...],
+    "dodItems": [...],
+    "closesIssues": [...]
+  }
+Exit: 0 when every invariant is present; 1 (fail closed) when any is missing.
+Error output (stderr, JSON):
+  { "ok": false, "error": "...", "usage": "..." }
+${JQ_OUTPUT_USAGE}`.trim();
+
+const parseError = buildParseError(USAGE);
+
+export function parseValidatePrBodySpecCliArgs(argv) {
+  const options = {
+    help: false,
+    repo: undefined,
+    pr: undefined,
+    input: undefined,
+    expectedIssue: undefined,
+    noIssue: false,
+  };
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      input: { type: "string" },
+      "expected-issue": { type: "string" },
+      "no-issue": { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
+      options.help = true;
+      return options;
+    }
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
+      continue;
+    }
+    if (token.name === "pr") {
+      const value = requireTokenValue(token, parseError);
+      if (!/^\d+$/.test(value) || Number(value) === 0) {
+        throw parseError("--pr must be a positive integer");
+      }
+      options.pr = Number(value);
+      continue;
+    }
+    if (token.name === "input") {
+      options.input = requireTokenValue(token, parseError).trim();
+      continue;
+    }
+    if (token.name === "expected-issue") {
+      const value = requireTokenValue(token, parseError);
+      if (!/^\d+$/.test(value) || Number(value) === 0) {
+        throw parseError("--expected-issue must be a positive integer");
+      }
+      options.expectedIssue = Number(value);
+      continue;
+    }
+    if (token.name === "no-issue") {
+      options.noIssue = true;
+      continue;
+    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  if (options.help) {
+    return options;
+  }
+  if (options.noIssue && Number.isInteger(options.expectedIssue)) {
+    throw parseError("--no-issue is mutually exclusive with --expected-issue; provide exactly one issue-linkage mode");
+  }
+  const hasInput = typeof options.input === "string" && options.input.length > 0;
+  const hasAnyRemote = (typeof options.repo === "string" && options.repo.length > 0) || Number.isInteger(options.pr);
+  const hasRemotePair = typeof options.repo === "string" && options.repo.length > 0 && Number.isInteger(options.pr);
+  // --input and the remote mode are mutually exclusive input sources: a stray
+  // --repo/--pr alongside --input must fail closed, not be silently ignored.
+  if (hasInput && hasAnyRemote) {
+    throw parseError("--input is mutually exclusive with --repo/--pr; provide exactly one input mode");
+  }
+  if (hasInput === hasRemotePair) {
+    throw parseError("Provide exactly one of --input <path> or --repo <owner/name> --pr <number>");
+  }
+  return options;
+}
+
+async function fetchPrBody({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
+  const result = await runChild(
+    ghCommand,
+    ["pr", "view", String(pr), "--repo", repo, "--json", "body"],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh command failed: ${detail}`);
+  }
+  const payload = parseJsonText(result.stdout, { label: "gh pr view" });
+  if (!payload || typeof payload !== "object") {
+    throw new Error("Invalid gh pr view payload: missing body");
+  }
+  return typeof payload.body === "string" ? payload.body : "";
+}
+
+async function loadInputPayload(inputPath) {
+  const text = await readFile(inputPath, "utf8");
+  const payload = parseJsonText(text, { label: `input file ${inputPath}` });
+  if (!payload || typeof payload !== "object") {
+    throw new Error(`Input file ${inputPath} must be a JSON object`);
+  }
+  return payload;
+}
+
+export async function validatePrBodySpecFromOptions(options, { env = process.env, ghCommand = "gh" } = {}) {
+  if (typeof options.input === "string" && options.input.length > 0) {
+    const payload = await loadInputPayload(options.input);
+    const body = typeof payload.body === "string" ? payload.body : "";
+    const repo = typeof payload.repo === "string" ? payload.repo : options.repo ?? null;
+    const pr = Number.isInteger(payload.pr) ? payload.pr : options.pr ?? null;
+    return { ...validatePrBodySpec({ body, expectedIssue: options.expectedIssue ?? null, issueLess: options.noIssue }), repo, pr };
+  }
+  parseRepoSlug(options.repo);
+  const body = await fetchPrBody({ repo: options.repo, pr: options.pr }, { env, ghCommand });
+  return {
+    ...validatePrBodySpec({ body, expectedIssue: options.expectedIssue ?? null, issueLess: options.noIssue }),
+    repo: options.repo,
+    pr: options.pr,
+  };
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh" } = {},
+) {
+  let options;
+  try {
+    options = parseValidatePrBodySpecCliArgs(argv);
+  } catch (error) {
+    stderr.write(`${formatCliError(error, { usage: USAGE })}\n`);
+    return 1;
+  }
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  try {
+    const result = await validatePrBodySpecFromOptions(options, { env, ghCommand });
+    // Fail closed: a body missing any invariant maps result.ok=false to exit 1.
+    return emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
+  } catch (error) {
+    stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  const code = await runCli();
+  if (code !== 0) {
+    process.exitCode = code;
+  }
+}

package/scripts/loop/watch-initial-copilot-pr.mjs

@@ -5,6 +5,7 @@ import { parseArgs } from "node:util";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { parseIssueNumber, requireTokenValue } from "../_cli-primitives.mjs";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 import { detectInitialCopilotPrState, LINKED_PR_STATE } from "./detect-initial-copilot-pr-state.mjs";
 import { enforcePersistentInternalWaitTimeout } from "@dev-loops/core/loop/timeout-policy";
 import {
@@ -45,9 +46,11 @@ Error output (stderr, JSON):
     { "ok": false, "error": "...", "usage": "..." }
   gh/runtime failures:
     { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success (ready_for_followup, timed_out, and prior_linked_pr_closed_unmerged are all ok:true)
-  1  Argument error or gh failure`.trim();
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
 const parseError = buildParseError(USAGE);
 function rejectRemovedFlag(token) {
   throw parseError(
@@ -108,6 +111,7 @@ export function parseWatchInitialCopilotPrCliArgs(argv) {
       help: { type: "boolean", short: "h" },
       repo: { type: "string" },
       issue: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -135,6 +139,7 @@ export function parseWatchInitialCopilotPrCliArgs(argv) {
       options.issue = parseIssueNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.repo === undefined || options.issue === undefined) {
@@ -251,7 +256,7 @@ export async function watchInitialCopilotPr(
 }
 export async function runCli(
   argv = process.argv.slice(2),
-  { stdout = process.stdout, env = process.env, ghCommand = "gh" } = {},
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh" } = {},
 ) {
   const options = parseWatchInitialCopilotPrCliArgs(argv);
   if (options.help) {
@@ -259,7 +264,7 @@ export async function runCli(
     return;
   }
   const result = await watchInitialCopilotPr(options, { env, ghCommand });
-  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) => {