dev-loops 0.7.1 → 0.7.2

package/scripts/github/upsert-checkpoint-verdict.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
-import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
-import { loadDevLoopConfig, resolveGateConfig, resolveRefinementConfig } from "@dev-loops/core/config";
+import { buildParseError, formatCliError, isDirectCliRun, parseJsonText, sanitizeCopilotSummonTokens } from "../_core-helpers.mjs";
+import { loadDevLoopConfig, resolveEffectiveCopilotRoundCap, resolveGateAngleContract, resolveGateConfig, resolveRefinementConfig, resolveRejectForeignAngles } from "@dev-loops/core/config";
+import { checkFanoutAngleCoverage } from "@dev-loops/core/loop/gate-fanin";
 import { parseArgs } from "node:util";
 import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
@@ -72,6 +73,11 @@ Optional:
   --gate <draft_gate|pre_approval_gate>     Auto-resolved from coordination state
                                             when omitted. Explicit gate is validated
                                             against allowed coordination actions.
+  --lightweight                             This PR is light-dispatched (#1210):
+                                            resolve the Copilot round cap as
+                                            min(lightMode.maxCopilotRounds ?? 1,
+                                            refinement.maxCopilotRounds) instead of
+                                            refinement.maxCopilotRounds alone.
   --findings-severity-counts <json>         JSON object mapping severity to count
                                              (e.g. '{"must-fix":0,"worth-fixing-now":0}').
                                              Required for --verdict clean when
@@ -261,6 +267,7 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
       "findings-severity-counts": { type: "string" },
       "execution-mode": { type: "string" },
       "inline-reason": { type: "string" },
+      lightweight: { type: "boolean" },
       ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
@@ -281,6 +288,7 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
     findingsSeverityCounts: undefined,
     executionMode: undefined,
     inlineReason: undefined,
+    lightweight: false,
     jq: undefined,
     silent: false,
   };
@@ -306,6 +314,10 @@ export function parseUpsertCheckpointVerdictCliArgs(argv) {
       options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
       continue;
     }
+    if (token.name === "lightweight") {
+      options.lightweight = true;
+      continue;
+    }
     if (token.name === "gate") {
       const gate = normalizeGateName(requireTokenValue(token, parseError));
       if (!gate) {
@@ -742,7 +754,11 @@ export function renderGateReviewCommentBody({ gate, headSha, verdict, findingsSu
     "",
     `**Next action:** ${nextAction}`,
   );
-  return lines.join("\n");
+  // Neutralize any bare @copilot/`/copilot`* tokens in the rendered body (gate
+  // evidence legitimately quotes the anti-summon rule, e.g. from a findings
+  // excerpt) so posting this comment can never arm request-copilot-review.mjs's
+  // anti-summon guard on a later request.
+  return sanitizeCopilotSummonTokens(lines.join("\n"));
 }
 function resolveRequestedHeadSha(requestedHeadSha, currentHeadSha) {
   if (requestedHeadSha === currentHeadSha) {
@@ -949,13 +965,18 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
       // loadPrGateCoordinationContext call will surface the real error.
     }
   }
-  const coordinationContext = await loadPrGateCoordinationContext({ repo: options.repo, pr: options.pr }, { env, ghCommand });
+  // Thread the light-dispatch signal (#1210) so the context interpreter and the
+  // maxCopilotRounds resolution below both use the composed lightweight cap —
+  // the two must never disagree at the cap boundary (#1126).
+  const coordinationContext = await loadPrGateCoordinationContext({ repo: options.repo, pr: options.pr, lightweight: options.lightweight === true }, { env, ghCommand });
   const evidence = coordinationContext.gateEvidence;
   const canonicalHeadSha = resolveRequestedHeadSha(options.headSha, evidence.currentHeadSha);
   const { config } = await loadDevLoopConfig({ repoRoot });
   const draftGateConfig = resolveGateConfig(config, "draft");
   const preApprovalGateConfig = resolveGateConfig(config, "preApproval");
-  const maxCopilotRounds = resolveRefinementConfig(config, "maxCopilotRounds");
+  const maxCopilotRounds = options.lightweight === true
+    ? resolveEffectiveCopilotRoundCap(config, { lightweight: true })
+    : resolveRefinementConfig(config, "maxCopilotRounds");
   // Root cause 2: detect internal-only PRs so the Copilot convergence requirement
   // is suppressed. Docs-only / tooling-only PRs should go straight to pre_approval_gate
   // without requiring an external Copilot review cycle.
@@ -982,6 +1003,10 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
     copilotReviewRoundCount: coordinationContext.snapshot?.copilotReviewRoundCount ?? 0,
     maxCopilotRounds,
     sameHeadCleanConverged: coordinationContext.interpretation.sameHeadCleanConverged,
+    // Independent gate-ENTRY re-check (#1190): fed alongside (not derived from)
+    // sameHeadCleanConverged, so an outstanding request on the current head refuses
+    // RUN_PRE_APPROVAL_GATE even if sameHeadCleanConverged were somehow stale/wrong.
+    copilotReviewRequestStatus: coordinationContext.snapshot?.copilotReviewRequestStatus ?? "none",
     draftGateRequireCi: draftGateConfig.requireCi,
     draftGate: coordinationContext.gateEvidence.draftGate,
     draftGateMarker: coordinationContext.gateEvidence.draftGateMarker,
@@ -1122,6 +1147,7 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
   // multi-line per-angle breakdown and the `**Findings summary:**` line carries a
   // single-line digest (so the marker/parse contract still round-trips).
   let structuredFindings = null;
+  let rawFindingsInput = null;
   if (options.findingsJson) {
     let raw;
     try {
@@ -1140,6 +1166,7 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
     const candidate = Array.isArray(parsed)
       ? parsed
       : (Array.isArray(parsed?.angles) ? parsed.angles : (Array.isArray(parsed?.findings) ? parsed.findings : null));
+    rawFindingsInput = candidate;
     try {
       structuredFindings = normalizeStructuredFindings(candidate);
     } catch (err) {
@@ -1149,6 +1176,48 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
       throw new Error(`--findings-json "${options.findingsJson}" did not contain any renderable findings (expected a non-empty per-angle array of { angle, findings } entries, or a flat per-finding array of { severity, summary, angle? } entries)`);
     }
   }
+  // Fan-out angle-coverage enforcement (fail closed): a fanout_fanin verdict's
+  // structured per-angle results must cover every configured mandatory angle,
+  // and (default) must not name an angle outside the gate's configured pool.
+  // Only applies when structured per-angle results were actually supplied —
+  // a free-text --findings-summary fanout_fanin verdict carries no per-angle
+  // data to validate.
+  if (structuredFindings && (options.executionMode ?? DEFAULT_EXECUTION_MODE) === "fanout_fanin") {
+    // Angle-less entries would be bucketed under the synthetic `general` label
+    // by normalization and then surface as a CONFUSING foreign-angle error.
+    // Fail first with a dedicated message naming the real problem instead.
+    const angleless = (rawFindingsInput ?? []).filter(
+      (e) => !e || typeof e !== "object" || typeof e.angle !== "string" || e.angle.trim().length === 0,
+    ).length;
+    if (angleless > 0) {
+      throw new Error(
+        `--findings-json for ${options.gate}: ${angleless} entr${angleless === 1 ? "y" : "ies"} lack a non-empty .angle — a fanout_fanin verdict must attribute every per-angle entry/finding to its review angle (use the nested [{ angle, verdict, findings }] shape, or add .angle to each flat finding)`,
+      );
+    }
+    const gateKey = options.gate === "draft_gate" ? "draft" : "preApproval";
+    const { mandatoryAngles, pool } = resolveGateAngleContract(config, gateKey);
+    const { missingMandatory, foreignAngles } = checkFanoutAngleCoverage(structuredFindings, {
+      mandatoryAngles,
+      pool,
+    });
+    if (missingMandatory.length > 0) {
+      throw new Error(
+        `--findings-json for ${options.gate} is missing mandatory angle(s): ${missingMandatory.join(", ")} (configured in gates.${gateKey}.mandatoryAngles; add a per-angle entry for each before posting a fanout_fanin verdict)`,
+      );
+    }
+    if (foreignAngles.length > 0) {
+      const message = `--findings-json for ${options.gate} names angle(s) outside the configured pool: ${foreignAngles.join(", ")}`;
+      if (resolveRejectForeignAngles(config)) {
+        throw new Error(
+          `${message} (add them to gates.${gateKey}.angles, or set gates.rejectForeignAngles: false to warn instead of fail)`,
+        );
+      }
+      // rejectForeignAngles: false is WARNING mode, not silence — one line per call.
+      if (!options.silent) {
+        process.stderr.write(`WARNING: ${message} (gates.rejectForeignAngles is false; recorded as a warning)\n`);
+      }
+    }
+  }
   // --findings-json takes precedence; when structured findings are present, do not
   // read --findings-file at all (avoids a spurious hard failure if a caller passes
   // both and the file is missing/invalid even though it would be ignored anyway).

package/scripts/github/verify-briefing-prefixes.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+
+const USAGE = `Usage: verify-briefing-prefixes.mjs --head-sha <sha> [--help]
+Fan-in enforcement for GATE-EXEC-BRIEFING-PREFIX (docs/gate-review-sub-loop-contract.md):
+fails closed when this gate-review round's per-scope reviewer sentinels (written by
+verify-fresh-review-context.mjs --prefix-hash/--prefix-file) do not all record the SAME
+invariant-briefing prefix hash. Deterministic and offline: reads only the sentinel files
+already on disk under tmp/, keyed by the given head SHA.
+
+Required:
+  --head-sha <sha>  The FULL 40-char reviewed head SHA (git rev-parse HEAD); sentinels are read from
+                     tmp/checkpoint-context-sentinel-<scope>-<headSha>.json.
+
+Output (stdout, JSON):
+  { "ok": true, "verified": true, "headSha": "...", "reviewerCount": <n>, "prefixHash": "..." }
+  { "ok": true, "verified": true, "headSha": "...", "reviewerCount": 0, "reason": "no sentinels found for this round" }
+  { "ok": true, "verified": false, "headSha": "...", "reviewerCount": <n>, "reason": "...", "missing": [...], "mismatched": [...] }
+  On error (stderr, JSON):
+  { "ok": false, "error": "...", "usage": "..." }
+${JQ_OUTPUT_USAGE}
+Exit codes:
+  0  Verified: no sentinels found for this round (nothing to check), or every
+     sentinel records a hash and all hashes are identical (a single hashed
+     sentinel verifies — nothing to mismatch)
+  1  Fail closed: two or more sentinels record DIFFERENT prefix hashes, or ANY
+     sentinel for the round (even a lone one) records no prefix hash — a missing
+     hash is treated as a mismatch, never grandfathered
+  2  Usage or internal error, or invalid --jq filter
+
+Caveat: rounds are keyed by head SHA only. Two different gates reviewed at the
+SAME head share one sentinel namespace, so run this check per gate pass (the head
+advances between gate passes per GATE-EXEC-REGATE-MANDATORY; never manually clear sentinels); legitimately different per-gate prefixes at an identical
+head would otherwise flag as a mismatch (conservative fail-closed, never
+fail-open).`.trim();
+
+// Full 40-char SHA required: sentinel filenames embed the full `git rev-parse
+// HEAD` value, so a short prefix would glob zero sentinels and read as a
+// vacuous pass — fail closed on anything shorter instead.
+const HEAD_SHA_RE = /^[0-9a-f]{40}$/i;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const SENTINEL_PREFIX = "checkpoint-context-sentinel-";
+const parseError = buildParseError(USAGE);
+
+function resolveFlagValue(argv, flag) {
+  const idx = argv.indexOf(flag);
+  if (idx === -1) return null;
+  const val = argv[idx + 1];
+  if (val === undefined || val === "" || (val.length > 0 && val[0] === "-")) {
+    return ""; // provided but missing/empty/flag-like
+  }
+  return val;
+}
+
+/**
+ * Read every sentinel for the given round (head SHA) from `<tmpRoot>/`, extracting
+ * the reviewer scope (from the filename) and recorded `prefixHash` (from the JSON
+ * body, when present). A malformed/unreadable sentinel is still COUNTED, with
+ * `prefixHash: null` — downstream that reads as a missing hash and FAILS CLOSED,
+ * deliberately: a corrupt sentinel means the invariant-prefix proof cannot be
+ * verified for that reviewer, and silently dropping it would fail open.
+ * @param {string} tmpRoot
+ * @param {string} headSha — lowercase hex, already validated
+ * @returns {Promise<Array<{ scope: string, prefixHash: string|null }>>}
+ */
+async function readRoundSentinels(tmpRoot, headSha) {
+  const suffix = `-${headSha}.json`;
+  let entries;
+  try {
+    entries = await readdir(tmpRoot, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+  const matches = entries
+    .filter((e) => e.isFile() && e.name.startsWith(SENTINEL_PREFIX) && e.name.endsWith(suffix))
+    .map((e) => ({
+      file: e.name,
+      scope: e.name.slice(SENTINEL_PREFIX.length, -suffix.length),
+    }))
+    .filter((m) => m.scope.length > 0) // exclude the round-only (no-scope) sentinel name shape
+    // readdir order is filesystem-dependent; sort by scope so missing/mismatched
+    // output is deterministic across runs (this is a deterministic fan-in check).
+    .sort((a, b) => a.scope.localeCompare(b.scope));
+  const results = [];
+  for (const { file, scope } of matches) {
+    let prefixHash = null;
+    try {
+      const raw = await readFile(path.join(tmpRoot, file), "utf8");
+      const parsed = JSON.parse(raw);
+      // Only a well-formed sha256 counts as a recorded hash; anything else
+      // (corrupted/hand-edited value) is treated as missing so the round
+      // fails closed rather than comparing garbage.
+      if (parsed && typeof parsed.prefixHash === "string" && SHA256_RE.test(parsed.prefixHash.toLowerCase().trim())) {
+        prefixHash = parsed.prefixHash.toLowerCase().trim();
+      }
+    } catch {
+      // Malformed/unreadable sentinel: counted with prefixHash null so the
+      // evaluation fails closed on it (see the function doc comment).
+    }
+    results.push({ scope, prefixHash });
+  }
+  return results;
+}
+
+/**
+ * Pure comparison: given the round's sentinels, decide verified/reason/missing/mismatched.
+ * Exported for direct unit testing without touching the filesystem.
+ * @param {Array<{ scope: string, prefixHash: string|null }>} sentinels
+ * @returns {{ verified: boolean, reason?: string, missing?: string[], mismatched?: Array<{scope:string, prefixHash:string}> }}
+ */
+export function evaluateBriefingPrefixes(sentinels) {
+  if (sentinels.length === 0) {
+    return { verified: true, reason: "no sentinels found for this round" };
+  }
+  // A hashless sentinel fails closed even when it is the ONLY sentinel (a
+  // one-angle Phase-5 retry round is a real case): "never grandfathered" means
+  // the invariant-prefix proof must exist for every reviewer, not just when a
+  // sibling exists to compare against. A single HASHED sentinel stays verified —
+  // with one recorded hash there is nothing to mismatch.
+  const missing = sentinels.filter((s) => s.prefixHash === null).map((s) => s.scope);
+  if (missing.length > 0) {
+    return {
+      verified: false,
+      reason: `${missing.length} of ${sentinels.length} reviewer sentinel(s) for this round have no recorded prefix hash — the invariant-briefing-prefix proof (GATE-EXEC-BRIEFING-PREFIX) was never established for them. Missing hashes are treated as a mismatch, not grandfathered in.`,
+      missing,
+    };
+  }
+  const distinct = new Map();
+  for (const { scope, prefixHash } of sentinels) {
+    if (!distinct.has(prefixHash)) distinct.set(prefixHash, []);
+    distinct.get(prefixHash).push(scope);
+  }
+  if (distinct.size > 1) {
+    const mismatched = sentinels.map(({ scope, prefixHash }) => ({ scope, prefixHash }));
+    return {
+      verified: false,
+      reason: `Reviewer sentinels for this round recorded ${distinct.size} DIFFERENT invariant-briefing prefix hashes — the seeded briefings were not byte-identical (GATE-EXEC-BRIEFING-PREFIX).`,
+      mismatched,
+    };
+  }
+  return { verified: true, prefixHash: sentinels[0].prefixHash };
+}
+
+export async function main(argv = process.argv.slice(2), { tmpRoot = path.join(process.cwd(), "tmp") } = {}) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  const headShaArg = resolveFlagValue(argv, "--head-sha");
+  if (headShaArg === null || headShaArg === "" || !HEAD_SHA_RE.test(headShaArg)) {
+    process.stderr.write(`${formatCliError(
+      parseError(`--head-sha is required and must be the FULL 40-character hex head SHA (short prefixes would match zero sentinels and pass vacuously)${headShaArg ? ` (got ${JSON.stringify(headShaArg)})` : ""}.`)
+    )}\n`);
+    return 2;
+  }
+  const headSha = headShaArg.toLowerCase();
+  const jqArg = resolveFlagValue(argv, "--jq");
+  if (jqArg === "") {
+    process.stderr.write(`${formatCliError(parseError("Invalid --jq value: must be non-empty."))}\n`);
+    return 2;
+  }
+  const jq = jqArg === null ? undefined : jqArg;
+  const silent = argv.includes("--silent") || argv.includes("-s");
+
+  const sentinels = await readRoundSentinels(tmpRoot, headSha);
+  const verdict = evaluateBriefingPrefixes(sentinels);
+  const payload = {
+    ok: true,
+    verified: verdict.verified,
+    headSha,
+    reviewerCount: sentinels.length,
+    ...(verdict.reason ? { reason: verdict.reason } : {}),
+    ...(verdict.missing ? { missing: verdict.missing } : {}),
+    ...(verdict.mismatched ? { mismatched: verdict.mismatched } : {}),
+    ...(verdict.prefixHash ? { prefixHash: verdict.prefixHash } : {}),
+  };
+  return emitResult(payload, { jq, silent, ok: verdict.verified });
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  try {
+    process.exitCode = await main();
+  } catch (err) {
+    process.stderr.write(`${formatCliError(err)}\n`);
+    process.exitCode = 2;
+  }
+}

package/scripts/github/verify-fresh-review-context.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
-import { mkdir, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import path from "node:path";
 import { buildParseError, isDirectCliRun, formatCliError } from "../_core-helpers.mjs";
 import { JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 const USAGE = `Usage: verify-fresh-review-context.mjs [--help] [--scope <name>] [--context-path <path>]
+       [--prefix-hash <sha256>|--prefix-file <path>]
 Verify that the current scoped-reviewer session has fresh context.
 
 "Fresh" means the reviewer's context is the neutral gate-context builder
@@ -45,6 +47,19 @@ Options:
                   means either a stale/isolated checkout or a skipped
                   preamble, and the reviewer must refuse to proceed
                   rather than silently reviewing without seeded context.
+  --prefix-hash <sha256>  A 64-character hex SHA-256 digest (case-insensitive,
+                  normalized to lowercase) of the
+                  invariant briefing block this reviewer was seeded with
+                  (GATE-EXEC-BRIEFING-PREFIX in
+                  docs/gate-review-sub-loop-contract.md). Recorded on the
+                  reviewer's sentinel so \`verify-briefing-prefixes.mjs\` can
+                  fail closed when reviewers of the same gate pass were
+                  seeded with different invariant blocks. Mutually exclusive
+                  with --prefix-file.
+  --prefix-file <path>  Path to the invariant briefing block text; the tool
+                  hashes its raw bytes (sha256) and records the digest same
+                  as --prefix-hash. Fails closed (exit 1) if the file is
+                  missing. Mutually exclusive with --prefix-hash.
 Output (stdout, JSON):
   { "ok": true, "fresh": true, "sentinelCreated": true, "round": "<headSha|null>" }
   { "ok": true, "fresh": true, "sentinelCreated": true, "round": "...", "gateContextPath": "...", "gateContextPresent": true }
@@ -57,9 +72,12 @@ Exit codes:
   0  Clean (first run)
   1  Refuse to review: contaminated (prior session detected), OR (with
      --context-path) the seeded gate-context artifact is missing or resolves
-     outside the reviewer's working directory
-  2  Usage or internal error, or invalid --jq filter`.trim();
+     outside the reviewer's working directory, OR (with --prefix-file) the
+     prefix file is missing
+  2  Usage or internal error, invalid --jq filter, or invalid/conflicting
+     --prefix-hash/--prefix-file`.trim();
 const VALID_SCOPE_RE = /^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$/;
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
 const parseError = buildParseError(USAGE);
 // Resolve a `--flag <value>` argument. Returns null when the flag is absent,
 // "" when it is present but the value is missing/empty/flag-like (a following
@@ -90,6 +108,12 @@ function resolveValidatedScope(argv) {
 function resolveContextPath(argv) {
   return resolveFlagValue(argv, "--context-path");
 }
+function resolvePrefixHash(argv) {
+  return resolveFlagValue(argv, "--prefix-hash");
+}
+function resolvePrefixFile(argv) {
+  return resolveFlagValue(argv, "--prefix-file");
+}
 // Round = the current head SHA, so a retry on a new head gets a fresh key while
 // a same-head re-entry collides and fails closed. `git rev-parse HEAD` yields the
 // same full SHA on every invocation for a given head, so the key is deterministic
@@ -145,6 +169,32 @@ async function main(argv = process.argv.slice(2)) {
     )}\n`);
     return 2;
   }
+  const prefixHashArg = resolvePrefixHash(argv);
+  if (prefixHashArg === "") {
+    process.stderr.write(`${formatCliError(
+      parseError("Invalid --prefix-hash value: must be non-empty.")
+    )}\n`);
+    return 2;
+  }
+  const prefixFileArg = resolvePrefixFile(argv);
+  if (prefixFileArg === "") {
+    process.stderr.write(`${formatCliError(
+      parseError("Invalid --prefix-file value: must be non-empty.")
+    )}\n`);
+    return 2;
+  }
+  if (prefixHashArg !== null && prefixFileArg !== null) {
+    process.stderr.write(`${formatCliError(
+      parseError("--prefix-hash and --prefix-file are mutually exclusive — pass at most one.")
+    )}\n`);
+    return 2;
+  }
+  if (prefixHashArg !== null && !SHA256_HEX_RE.test(prefixHashArg.trim().toLowerCase())) {
+    process.stderr.write(`${formatCliError(
+      parseError(`Invalid --prefix-hash value "${prefixHashArg}": must be a 64-character hex SHA-256 digest (case-insensitive).`)
+    )}\n`);
+    return 2;
+  }
   const jqArg = resolveFlagValue(argv, "--jq");
   if (jqArg === "") {
     process.stderr.write(`${formatCliError(
@@ -195,6 +245,29 @@ async function main(argv = process.argv.slice(2)) {
       }, false);
     }
   }
+  // Resolve the invariant-briefing prefix hash (GATE-EXEC-BRIEFING-PREFIX) before
+  // sentinel creation, same ordering rationale as --context-path above: a failure
+  // here must not burn the scope sentinel.
+  let prefixHash = prefixHashArg !== null ? prefixHashArg.trim().toLowerCase() : null;
+  if (prefixHash === null && prefixFileArg !== null) {
+    let prefixFileBytes;
+    try {
+      prefixFileBytes = await readFile(path.resolve(process.cwd(), prefixFileArg));
+    } catch (err) {
+      // ANY read failure (ENOENT, EACCES, EPERM, ...) refuses the review in the
+      // normal fail-closed shape — an unreadable prefix file means the
+      // invariant-briefing proof cannot be established, which is an enforcement
+      // refusal, not a tool crash.
+      return finish({
+        ok: true,
+        fresh: false,
+        sentinelCreated: false,
+        round: round ?? null,
+        reason: `--prefix-file "${prefixFileArg}" unreadable (${err.code ?? "error"}) — cannot compute the invariant-briefing prefix hash (GATE-EXEC-BRIEFING-PREFIX).`,
+      }, false);
+    }
+    prefixHash = createHash("sha256").update(prefixFileBytes).digest("hex");
+  }
   const sentinelPath = path.resolve(process.cwd(), sentinelRelative(scope, round));
   try {
     await mkdir(path.dirname(sentinelPath), { recursive: true });
@@ -217,6 +290,7 @@ async function main(argv = process.argv.slice(2)) {
     pid: process.pid,
     ...(scope ? { scope } : {}),
     ...(round ? { round } : {}),
+    ...(prefixHash ? { prefixHash } : {}),
   };
   try {
     await writeFile(sentinelPath, JSON.stringify(sentinel, null, 2) + "\n", {
@@ -242,6 +316,7 @@ async function main(argv = process.argv.slice(2)) {
     sentinelCreated: true,
     round: round ?? null,
     ...(contextPathArg !== null ? { gateContextPath: contextPathArg, gateContextPresent: true } : {}),
+    ...(prefixHash ? { prefixHash } : {}),
   }, true);
 }
 if (isDirectCliRun(import.meta.url)) {

package/scripts/github/wait-pr-checks.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parseNonNegativeInteger, parsePositiveInteger, parsePrNumber, 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 {
+  DEFAULT_POLL_INTERVAL_MS,
+  COPILOT_REVIEW_WAIT_TIMEOUT_MS,
+} from "@dev-loops/core/loop/policy-constants";
+// Reuse probe-ci-status.mjs's watch engine verbatim (polling, heartbeats, the
+// not-yet-registered-check grace/race guard, head-change detection) instead of
+// re-implementing it. This wrapper only adds seconds-based flags and a direct
+// process-exit-code contract for shell/scripted callers.
+import { watchCiStatus } from "./probe-ci-status.mjs";
+
+const DEFAULT_TIMEOUT_SECONDS = Math.floor(COPILOT_REVIEW_WAIT_TIMEOUT_MS / 1000);
+const DEFAULT_POLL_SECONDS = Math.floor(DEFAULT_POLL_INTERVAL_MS / 1000);
+
+const USAGE = `Usage: wait-pr-checks.mjs --repo <owner/name> --pr <number> [--timeout <seconds>] [--poll <seconds>]
+Block until the current head SHA's CI checks/statuses settle, or the wait
+budget elapses. Replaces hand-rolled \`until [ "$(gh pr checks | grep -c pending)" = 0 ]\`
+shell loops with a single deterministic call.
+Required:
+  --repo <owner/name>     Repository slug (e.g. owner/repo)
+  --pr <number>           Pull request number
+Optional:
+  --timeout <seconds>     Total wait budget (default ${DEFAULT_TIMEOUT_SECONDS}; 0 = single
+                          immediate check, no wait)
+  --poll <seconds>        Delay between polls (default ${DEFAULT_POLL_SECONDS})
+Not-yet-registered-check race guard:
+  A freshly pushed head with zero registered checks does NOT settle green on
+  the first poll — a provider may post its first check a beat after the push.
+  The watcher requires either an observed check/status, or a stable empty
+  result across two consecutive polls, before treating the head as genuinely
+  check-less. A repo with no CI at all still settles after that grace instead
+  of hanging to timeout.
+Output (stdout, JSON, the final per-check summary):
+  { "ok": true, "status": "success"|"failure"|"pending"|"timeout"|"changed",
+    "settled": bool, "ciStatus": "success"|"failure"|"pending"|"none",
+    "failedChecks": [{ "name": "...", "conclusion"?: "..." }], "headSha": "...", "attempts": N }
+"changed" means the head SHA advanced during the wait; re-baseline and re-run.
+Diagnostic output (stderr):
+  { "ok": true, "type": "watch_heartbeat", "elapsedMs": N, "totalBudgetMs": N, "poll": N, "maxPolls": N }
+  { "ok": false, "error": "...", "usage"?: "..." }
+${JQ_OUTPUT_USAGE}
+Exit codes (default output, no --jq/--silent):
+  0  Green (status "success")
+  1  Red (status "failure"), or an argument/gh/runtime error
+  2  Not settled (status "timeout"/"changed"/"pending")
+With --jq/--silent, the standard jq-output contract above applies instead
+(0/1 by result truthiness; 2 reserved for an invalid --jq filter).`.trim();
+
+const parseError = buildParseError(USAGE);
+
+export function parseWaitPrChecksCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      pr: { type: "string" },
+      timeout: { type: "string" },
+      poll: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = {
+    help: false,
+    repo: undefined,
+    pr: undefined,
+    timeoutMs: DEFAULT_TIMEOUT_SECONDS * 1000,
+    pollIntervalMs: DEFAULT_POLL_SECONDS * 1000,
+  };
+  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") {
+      options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
+      continue;
+    }
+    if (token.name === "timeout") {
+      // Canonical-digits validation (shared /^\d+$/ primitives): rejects
+      // JS-coercible spellings like 1e3, 0x10, "1.0", or " 5 ".
+      options.timeoutMs = parseNonNegativeInteger(requireTokenValue(token, parseError), "--timeout", parseError) * 1000;
+      continue;
+    }
+    if (token.name === "poll") {
+      options.pollIntervalMs = parsePositiveInteger(requireTokenValue(token, parseError), "--poll", parseError) * 1000;
+      continue;
+    }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  if (options.repo === undefined || options.pr === undefined) {
+    throw parseError("Waiting on PR checks requires both --repo <owner/name> and --pr <number>");
+  }
+  try {
+    parseRepoSlug(options.repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return options;
+}
+
+// Direct process-exit-code contract for shell/scripted callers — this is the
+// tool's reason to exist alongside `dev-loops loop watch-ci`, whose CLI always
+// exits 0 and expects callers to branch on the JSON `status` field instead.
+export function exitCodeForWaitResult(result) {
+  if (result.status === "success") return 0;
+  if (result.status === "failure") return 1;
+  return 2;
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  {
+    stdout = process.stdout,
+    stderr = process.stderr,
+    env = process.env,
+    ghCommand = "gh",
+    delayImpl = undefined,
+    now = undefined,
+  } = {},
+) {
+  const options = parseWaitPrChecksCliArgs(argv);
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  const result = await watchCiStatus(
+    { repo: options.repo, pr: options.pr, timeoutMs: options.timeoutMs, pollIntervalMs: options.pollIntervalMs },
+    {
+      env,
+      ghCommand,
+      ...(delayImpl ? { delayImpl } : {}),
+      ...(now ? { now } : {}),
+    },
+  );
+  if (options.jq !== undefined || options.silent) {
+    return emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr, ok: result.status === "success" });
+  }
+  stdout.write(`${JSON.stringify(result)}\n`);
+  return exitCodeForWaitResult(result);
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().then((code) => {
+    if (typeof code === "number") {
+      process.exitCode = code;
+    }
+  }).catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}