dev-loops 0.7.1 → 0.8.0

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;
+  });
+}

package/scripts/github/write-gate-context.mjs

@@ -29,6 +29,7 @@
  *   <tmpRoot>/gate-context/<repo-slug>/pr-<N>/<gate>-<headSha>.json
  */
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { parseArgs } from "node:util";
@@ -38,6 +39,7 @@ import { resolveGateAnglesDynamic } from "@dev-loops/core/config";
 import { parsePrNumber, requireTokenValue } from "../_cli-primitives.mjs";
 import { formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { buildAdjacentBundle, DEFAULT_MAX_FILE_BYTES } from "./build-adjacent-bundle.mjs";
+import { GATE_NAMES } from "./_gate-names.mjs";
 import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 /**
@@ -117,8 +119,10 @@ Optional:
   --branch <name>                Source branch name
   --touched-files <json>         JSON array of changed file path strings (separate from the diff-derived scope.changedFiles)
   --base <ref>                   Git ref to diff against (git diff <ref>...HEAD); populates scope.diffPath, scope.changedFiles, and adjacentCode (the full build-once bundle). Without it, the CLI emits an explicit thin briefing (scope.diffSource="none") — see docs/gate-review-sub-loop-contract.md.
-  --acceptance-criteria <ptr>    Pointer to acceptance criteria (issue ref, doc path, URL)
+  --acceptance-criteria <ptr>    Pointer to acceptance criteria (issue ref, doc path, URL); also used as the linked-issue label in the rendered briefing prefix
   --validation-posture <text>    Short description of the validation posture
+  --pr-body <text>               PR description text, inlined into the rendered briefing prefix
+  --issue-body <text>            Linked-issue body text, inlined into the briefing prefix under --acceptance-criteria's label; omitted entirely when absent
   --tmp-root <path>              Root tmp directory (default: tmp/)
 
 ${JQ_OUTPUT_USAGE}
@@ -129,7 +133,7 @@ function parseError(message) {
 }
 
 function normalizeGate(value) {
-  const gates = new Set(["draft_gate", "pre_approval_gate"]);
+  const gates = new Set(GATE_NAMES);
   const normalized = String(value).trim().toLowerCase();
   return gates.has(normalized) ? normalized : null;
 }
@@ -149,6 +153,9 @@ function normalizeHeadSha(value) {
 // with our own "<base>...HEAD" triple-dot construction). Everything else —
 // including HEAD@{upstream}, main@{1}, tag-peel v1.0.0^{commit}, HEAD~3 — is
 // accepted.
+// Revisit toward an explicit allowlist if `base` ever reaches a shell (or any
+// call without execFileSync's no-shell argv guarantee), or if a malformed ref
+// shape is found slipping past these checks into `git diff`.
 function normalizeBaseRef(value) {
   const trimmed = String(value).trim();
   if (trimmed.length === 0 || trimmed.startsWith("-") || trimmed.includes("..")) return null;
@@ -231,6 +238,8 @@ export function parseWriteGateContextCliArgs(argv) {
       base: { type: "string" },
       "acceptance-criteria": { type: "string" },
       "validation-posture": { type: "string" },
+      "pr-body": { type: "string" },
+      "issue-body": { type: "string" },
       "tmp-root": { type: "string" },
       ...JQ_OUTPUT_PARSE_OPTIONS,
     },
@@ -250,6 +259,8 @@ export function parseWriteGateContextCliArgs(argv) {
     base: null,
     acceptanceCriteria: null,
     validationPosture: null,
+    prBody: null,
+    issueBody: null,
     tmpRoot: "tmp",
   };
   for (const token of tokens) {
@@ -312,6 +323,14 @@ export function parseWriteGateContextCliArgs(argv) {
       options.validationPosture = requireTokenValue(token, parseError).trim();
       continue;
     }
+    if (token.name === "pr-body") {
+      options.prBody = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "issue-body") {
+      options.issueBody = requireTokenValue(token, parseError);
+      continue;
+    }
     if (token.name === "tmp-root") {
       options.tmpRoot = requireTokenValue(token, parseError).trim();
       continue;
@@ -360,8 +379,8 @@ export function buildGateContextPath({ repo, pr, gate, headSha, tmpRoot = "tmp"
  * @returns {{ pr: number, gate: string, headSha: string }}
  */
 function validatePathSegments({ pr, gate, headSha }) {
-  if (gate !== "draft_gate" && gate !== "pre_approval_gate") {
-    throw new Error(`--gate segment ${JSON.stringify(gate)} is unsafe (expected draft_gate or pre_approval_gate)`);
+  if (!GATE_NAMES.includes(gate)) {
+    throw new Error(`--gate segment ${JSON.stringify(gate)} is unsafe (expected ${GATE_NAMES.join(" or ")})`);
   }
   // Require a CANONICAL positive integer: the trimmed string must be all digits
   // (`/^\d+$/`) and > 0. This mirrors the CLI's parsePrNumber rule so the path
@@ -426,6 +445,137 @@ export function buildGateDiffPath({ repo, pr, gate, headSha, tmpRoot = "tmp" })
   return path.join(tmpRoot, "gate-context", repoSlug, `pr-${safePr}`, `${safeGate}-${safeSha}.diff`);
 }
 
+/**
+ * Build the deterministic path for the rendered invariant briefing prefix
+ * (GATE-EXEC-BRIEFING-PREFIX): the byte-identical block every per-angle
+ * reviewer of this gate pass is seeded with, before their angle-specific
+ * suffix. Mirrors buildGateContextPath/buildGateDiffPath. Exported so the
+ * fan-out reviewers and `verify-fresh-review-context.mjs --prefix-file` agree
+ * on the path with the context-builder.
+ *
+ * @param {object} input
+ * @param {string} input.repo — owner/name
+ * @param {number|string} input.pr
+ * @param {string} input.gate — draft_gate | pre_approval_gate
+ * @param {string} input.headSha
+ * @param {string} [input.tmpRoot] — default "tmp"
+ * @returns {string} relative briefing-prefix path
+ */
+export function buildGateBriefingPrefixPath({ repo, pr, gate, headSha, tmpRoot = "tmp" }) {
+  const repoSlug = repoSlugFor(repo);
+  const { pr: safePr, gate: safeGate, headSha: safeSha } = validatePathSegments({ pr, gate, headSha });
+  return path.join(tmpRoot, "gate-context", repoSlug, `pr-${safePr}`, `${safeGate}-${safeSha}.briefing-prefix.txt`);
+}
+
+/**
+ * Size cap (bytes) above which the rendered briefing prefix falls back to
+ * pointer mode for the diff section (a scope.diffPath reference when present,
+ * else an explicit unavailable-pointer disclosure) instead of inlining the
+ * diff text in a fenced block. No `gates.*` config knob exists for this
+ * yet — a named constant is the right size for a single fixed threshold;
+ * promote to config only if a real need for tuning it emerges.
+ */
+export const BRIEFING_PREFIX_INLINE_DIFF_CAP_BYTES = 200 * 1024;
+
+/**
+ * Render the invariant briefing-prefix text (GATE-EXEC-BRIEFING-PREFIX):
+ * header (repo/PR/head/gate/worktree + the mandatory verify-fresh-review-context.mjs
+ * instruction), PR body, linked-issue body (when present), the full diff at the
+ * reviewed head (inlined up to `capBytes`, else a pointer to `diffPath`), and a
+ * changed-files/adjacent-code summary — in that fixed order. Pure and
+ * deterministic: identical input always renders identical bytes, so two builds
+ * at the same head produce a byte-identical prefix (the fan-out's shared-prefix
+ * requirement).
+ *
+ * @param {object} input
+ * @param {string} input.repo
+ * @param {number|string} input.pr
+ * @param {string} input.gate
+ * @param {string} input.headSha
+ * @param {string} input.worktreeRoot — absolute path reviewers run in
+ * @param {string} input.contextPath — the sibling JSON artifact path
+ * @param {string} input.briefingPrefixPath — this rendered file's own path
+ * @param {string|null} [input.prBody]
+ * @param {string|null} [input.issueRef] — label for the linked-issue section (e.g. "#877")
+ * @param {string|null} [input.issueBody] — omit the whole section when null/empty
+ * @param {string|null} [input.diffOutput] — full diff text, when captured
+ * @param {string|null} [input.diffPath] — persisted `.diff` pointer (pointer-mode fallback)
+ * @param {string[]} [input.changedFiles]
+ * @param {object|null} [input.adjacentCode] — buildAdjacentBundle output
+ * @param {number} [input.capBytes] — default BRIEFING_PREFIX_INLINE_DIFF_CAP_BYTES
+ * @returns {{ text: string, prefixMode: "inline"|"pointer", diffBytes: number }}
+ */
+export function renderBriefingPrefix({
+  repo, pr, gate, headSha, worktreeRoot, contextPath, briefingPrefixPath,
+  prBody = null, issueRef = null, issueBody = null,
+  diffOutput = null, diffPath = null, changedFiles = [], adjacentCode = null,
+  capBytes = BRIEFING_PREFIX_INLINE_DIFF_CAP_BYTES,
+}) {
+  const hasDiffText = typeof diffOutput === "string" && diffOutput.length > 0;
+  const diffBytes = hasDiffText ? Buffer.byteLength(diffOutput, "utf8") : 0;
+  const prefixMode = hasDiffText && diffBytes > capBytes ? "pointer" : "inline";
+
+  const lines = [];
+  lines.push("# Gate Review Briefing — invariant prefix (GATE-EXEC-BRIEFING-PREFIX)");
+  lines.push("");
+  lines.push(`repo: ${repo}`);
+  lines.push(`pr: #${pr}`);
+  lines.push(`gate: ${gate}`);
+  lines.push(`head: ${headSha}`);
+  lines.push(`worktree: ${worktreeRoot}`);
+  lines.push(`prefixMode: ${prefixMode}`);
+  lines.push("");
+  lines.push(
+    `Mandatory: before doing any angle-specific work, run \`node scripts/github/verify-fresh-review-context.mjs --scope ${gate.replace(/_/g, "-")}-<your-angle> --context-path ${contextPath} --prefix-file ${briefingPrefixPath}\`. Refuse to proceed on contamination or a missing artifact.`,
+  );
+  lines.push("");
+  lines.push("## PR body");
+  lines.push("");
+  lines.push(typeof prBody === "string" && prBody.trim().length > 0 ? prBody.trim() : "(no PR body provided)");
+  lines.push("");
+  const hasIssueBody = typeof issueBody === "string" && issueBody.trim().length > 0;
+  if (hasIssueBody) {
+    lines.push(`## Linked issue${issueRef ? ` ${issueRef}` : ""}`);
+    lines.push("");
+    lines.push(issueBody.trim());
+    lines.push("");
+  }
+  lines.push(`## Diff at reviewed head (${headSha})`);
+  lines.push("");
+  if (!hasDiffText) {
+    lines.push("(no diff text captured for this bundle)");
+  } else if (prefixMode === "inline") {
+    lines.push("```diff");
+    lines.push(diffOutput.endsWith("\n") ? diffOutput.slice(0, -1) : diffOutput);
+    lines.push("```");
+  } else {
+    lines.push(
+      `Diff exceeds the ${capBytes}-byte inline cap (${diffBytes} bytes) — pointer mode. Read the full diff from:`,
+    );
+    lines.push(`  ${diffPath ?? "(diff pointer unavailable — re-derive with git diff)"}`);
+  }
+  lines.push("");
+  lines.push("## Changed files + adjacent-code summary");
+  lines.push("");
+  const files = Array.isArray(changedFiles) ? changedFiles : [];
+  lines.push(`Changed files (${files.length}):`);
+  for (const f of files) lines.push(`- ${f}`);
+  const adjacentFiles = adjacentCode && Array.isArray(adjacentCode.files)
+    ? adjacentCode.files.filter((f) => f.role !== "changed")
+    : [];
+  if (adjacentCode) {
+    lines.push(`Adjacent files (${adjacentFiles.length}):`);
+    for (const f of adjacentFiles) lines.push(`- ${f.path} (${f.role})`);
+    lines.push(
+      `Stripped: ${adjacentCode.stripped?.length ?? 0}, Truncated: ${adjacentCode.truncated?.length ?? 0}, Missing: ${adjacentCode.missing?.length ?? 0}`,
+    );
+  } else {
+    lines.push("Adjacent files (0): (no adjacent-code bundle for this briefing)");
+  }
+
+  return { text: lines.join("\n") + "\n", prefixMode, diffBytes };
+}
+
 /**
  * Parse `git diff --name-status` output into full repo-relative changed file
  * paths. Handles rename/copy entries (R100 old new, C75 old new) by recording
@@ -500,6 +650,12 @@ export function buildGateContextArtifact(options) {
   if (options.adjacentCode && typeof options.adjacentCode === "object") {
     artifact.adjacentCode = options.adjacentCode;
   }
+  // Whether the rendered briefing prefix inlined the reviewed-head diff (in a
+  // fenced block) or fell back to the diffPath pointer (size cap). Only set
+  // when a caller actually rendered a prefix (writeGateContext does, always).
+  if (typeof options.prefixMode === "string" && options.prefixMode.length > 0) {
+    artifact.prefixMode = options.prefixMode;
+  }
   return artifact;
 }
 
@@ -520,7 +676,7 @@ export function buildGateContextArtifact(options) {
  * @param {string} input.tmpRoot
  * @param {number} [input.maxFileBytes]
  * @param {{ repoRoot: string }} opts
- * @returns {Promise<{ diffPath: string|null, changedFiles: string[], adjacentCode: object|null }>}
+ * @returns {Promise<{ diffPath: string|null, changedFiles: string[], adjacentCode: object|null, diffOutput: string|null }>}
  */
 async function resolveDiffScope({ diff, repo, pr, gate, headSha, tmpRoot, maxFileBytes }, { repoRoot }) {
   const diffOutput = diff?.diffOutput;
@@ -562,7 +718,7 @@ async function resolveDiffScope({ diff, repo, pr, gate, headSha, tmpRoot, maxFil
     }
   }
 
-  return { diffPath, changedFiles, adjacentCode };
+  return { diffPath, changedFiles, adjacentCode, diffOutput: typeof diffOutput === "string" ? diffOutput : null };
 }
 
 /**
@@ -647,6 +803,19 @@ export function captureDiffFromBase(base, { repoRoot, maxBuffer = 64 * 1024 * 10
   return { nameStatusOutput, diffOutput };
 }
 
+/**
+ * Write both the JSON context artifact AND its sibling rendered briefing
+ * prefix (GATE-EXEC-BRIEFING-PREFIX): the byte-identical invariant block every
+ * per-angle reviewer of this gate pass is seeded with. The prefix's
+ * `prefixMode` (inline|pointer, from the diff-size cap) is recorded on the
+ * JSON artifact so both files stay in sync.
+ *
+ * @param {object} options — parsed CLI options shape, optionally carrying
+ *   `diffOutput`, `prBody`, `issueBody` (all null-safe; a caller with none of
+ *   these still gets a valid — if thin — prefix).
+ * @param {{ repoRoot?: string }} [runtime]
+ * @returns {Promise<{ ok: boolean, path: string, artifact: object, prefixPath: string, prefixHash: string, prefixMode: "inline"|"pointer" }>}
+ */
 export async function writeGateContext(options, { repoRoot = process.cwd() } = {}) {
   const contextPath = buildGateContextPath({
     repo: options.repo,
@@ -655,14 +824,49 @@ export async function writeGateContext(options, { repoRoot = process.cwd() } = {
     headSha: options.headSha,
     tmpRoot: options.tmpRoot || "tmp",
   });
+  const briefingPrefixPath = buildGateBriefingPrefixPath({
+    repo: options.repo,
+    pr: options.pr,
+    gate: options.gate,
+    headSha: options.headSha,
+    tmpRoot: options.tmpRoot || "tmp",
+  });
+  const rendered = renderBriefingPrefix({
+    repo: options.repo,
+    pr: options.pr,
+    gate: options.gate,
+    headSha: options.headSha,
+    worktreeRoot: path.resolve(repoRoot),
+    contextPath,
+    briefingPrefixPath,
+    prBody: options.prBody ?? null,
+    issueRef: options.acceptanceCriteria ?? null,
+    issueBody: options.issueBody ?? null,
+    diffOutput: options.diffOutput ?? null,
+    diffPath: options.diffPath ?? null,
+    changedFiles: options.changedFiles ?? [],
+    adjacentCode: options.adjacentCode ?? null,
+  });
+
   const fullPath = path.resolve(repoRoot, contextPath);
   const artifact = {
-    ...buildGateContextArtifact(options),
+    ...buildGateContextArtifact({ ...options, prefixMode: rendered.prefixMode }),
     loggedAt: new Date().toISOString(),
   };
+  // Write ORDER matters: the sibling briefing prefix goes first and the JSON
+  // artifact last, so the artifact's existence is the completion marker for
+  // the whole set. Downstream consumers (readGateContext, the reviewers'
+  // --context-path guard) key on the JSON — a prefix-write failure must not
+  // leave a complete-looking artifact pointing at a missing prefix file.
+  const fullPrefixPath = path.resolve(repoRoot, briefingPrefixPath);
+  await mkdir(path.dirname(fullPrefixPath), { recursive: true });
+  await writeFile(fullPrefixPath, rendered.text, "utf8");
+  const prefixHash = createHash("sha256").update(rendered.text, "utf8").digest("hex");
+
   await mkdir(path.dirname(fullPath), { recursive: true });
   await writeFile(fullPath, JSON.stringify(artifact, null, 2) + "\n", "utf8");
-  return { ok: true, path: contextPath, artifact };
+
+  return { ok: true, path: contextPath, artifact, prefixPath: briefingPrefixPath, prefixHash, prefixMode: rendered.prefixMode };
 }
 
 /**
@@ -685,10 +889,12 @@ export async function writeGateContext(options, { repoRoot = process.cwd() } = {
  * @param {string[]} [input.touchedFiles]
  * @param {string|null} [input.acceptanceCriteria]
  * @param {string|null} [input.validationPosture]
+ * @param {string|null} [input.prBody] — PR description text, inlined into the rendered briefing prefix
+ * @param {string|null} [input.issueBody] — linked-issue body text, inlined under `acceptanceCriteria`'s label; omitted when absent
  * @param {number} [input.maxFileBytes] — per-file cap for the adjacent-code bundle (default DEFAULT_MAX_FILE_BYTES)
  * @param {string} [input.tmpRoot]
  * @param {{ repoRoot?: string }} [opts]
- * @returns {Promise<{ ok: boolean, path: string, artifact: object, resolver: object }>}
+ * @returns {Promise<{ ok: boolean, path: string, artifact: object, prefixPath: string, prefixHash: string, prefixMode: "inline"|"pointer", resolver: object }>}
  *
  * The artifact additionally carries a deterministic, neutral `adjacentCode`
  * bundle (#895) when changed files are present: 1-hop import in/out-edges of the
@@ -707,7 +913,7 @@ export async function buildGateContext(input, { repoRoot = process.cwd() } = {})
   // Diff-derived scope: persisted FULL diff (scope.diffPath), parsed
   // scope.changedFiles, and the neutral adjacentCode bundle, all built ONCE by
   // the shared resolveDiffScope helper (also used by the CLI --base path, #1140).
-  const { diffPath, changedFiles, adjacentCode } = await resolveDiffScope(
+  const { diffPath, changedFiles, adjacentCode, diffOutput } = await resolveDiffScope(
     { diff: input.diff, repo: input.repo, pr: input.pr, gate: input.gate, headSha: input.headSha, tmpRoot, maxFileBytes: input.maxFileBytes },
     { repoRoot },
   );
@@ -724,9 +930,12 @@ export async function buildGateContext(input, { repoRoot = process.cwd() } = {})
       touchedFiles: input.touchedFiles ?? [],
       changedFiles,
       diffPath,
+      diffOutput,
       adjacentCode,
       acceptanceCriteria: input.acceptanceCriteria ?? null,
       validationPosture: input.validationPosture ?? null,
+      prBody: input.prBody ?? null,
+      issueBody: input.issueBody ?? null,
       tmpRoot,
     },
     { repoRoot },
@@ -800,6 +1009,7 @@ export async function main(argv = process.argv.slice(2), { repoRoot = process.cw
       options.changedFiles = scope.changedFiles;
       options.diffPath = scope.diffPath;
       options.adjacentCode = scope.adjacentCode;
+      options.diffOutput = scope.diffOutput;
       options.diffSource = "base";
     } else {
       process.stderr.write("[write-gate-context] warning: no --base given; emitting a THIN briefing (scope.diffPath=null, scope.changedFiles=[], no adjacentCode). Pass --base <ref> for the full build-once bundle.\n");

package/scripts/github/write-gate-findings-log.mjs

@@ -5,7 +5,8 @@ import { parseArgs } from "node:util";
 import { parsePrNumber, requireTokenValue } from "../_cli-primitives.mjs";
 import { formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
-import { provenanceConsistencyError } from "@dev-loops/core/loop/gate-fanin";
+import { checkFanoutAngleCoverage, provenanceConsistencyError } from "@dev-loops/core/loop/gate-fanin";
+import { loadDevLoopConfig, resolveGateAngleContract, resolveRejectForeignAngles } from "@dev-loops/core/config";
 const USAGE = `Usage: write-gate-findings-log.mjs --repo <owner/name> --pr <number> --gate <draft_gate|pre_approval_gate> --head-sha <sha> --verdict <clean|findings_present|blocked> --findings <json> [--tmp-root <path>]
 Write a durable <gate>-<headSha>.json log under deterministic tmp/ paths.
 Required:
@@ -30,6 +31,7 @@ function normalizeGate(value) {
   const normalized = String(value).trim().toLowerCase();
   return gates.has(normalized) ? normalized : null;
 }
+const GATE_CONFIG_KEY = { draft_gate: "draft", pre_approval_gate: "preApproval" };
 function normalizeVerdict(value) {
   const verdicts = new Set(["clean", "findings_present", "blocked"]);
   const normalized = String(value).trim().toLowerCase();
@@ -148,6 +150,42 @@ export function parseProvenanceJson(raw) {
   }
   return normalized;
 }
+/**
+ * Validate recorded provenance.perAngle against the gate's configured angle
+ * contract (mandatoryAngles + pool, resolved from .devloops/defaults). A
+ * missing mandatory angle always fails the write. A foreign (out-of-pool)
+ * angle fails the write unless `gates.rejectForeignAngles: false`, in which
+ * case it is returned as a warning instead. Throws a `parseError`-shaped Error
+ * (matching this module's other validation failures) on a fail-closed
+ * rejection.
+ *
+ * @param {{ perAngle: Array<{ angle: string }> }} provenance
+ * @param {"draft_gate"|"pre_approval_gate"} gate
+ * @param {{ repoRoot?: string }} [options]
+ * @returns {Promise<{ warning: string|null }>}
+ */
+export async function checkProvenanceAngleCoverage(provenance, gate, { repoRoot = process.cwd() } = {}) {
+  const { config } = await loadDevLoopConfig({ repoRoot });
+  const gateKey = GATE_CONFIG_KEY[gate];
+  const { mandatoryAngles, pool } = resolveGateAngleContract(config, gateKey);
+  const { missingMandatory, foreignAngles } = checkFanoutAngleCoverage(provenance.perAngle, {
+    mandatoryAngles,
+    pool,
+  });
+  if (missingMandatory.length > 0) {
+    throw parseError(
+      `--provenance.perAngle is missing mandatory angle(s) for ${gate}: ${missingMandatory.join(", ")} (configured in gates.${gateKey}.mandatoryAngles)`,
+    );
+  }
+  if (foreignAngles.length > 0) {
+    const message = `--provenance.perAngle names angle(s) outside the configured pool for ${gate}: ${foreignAngles.join(", ")}`;
+    if (resolveRejectForeignAngles(config)) {
+      throw parseError(`${message} (add them to gates.${gateKey}.angles, or set gates.rejectForeignAngles: false to warn instead of fail)`);
+    }
+    return { warning: `${message} (gates.rejectForeignAngles is false; recorded as a warning)` };
+  }
+  return { warning: null };
+}
 export function parseWriteGateFindingsLogCliArgs(argv) {
   const { tokens } = parseArgs({
     args: [...argv],
@@ -250,6 +288,12 @@ export function buildLogPath({ repo, pr, gate, headSha, tmpRoot }) {
 export async function writeGateFindingsLog(options, { repoRoot = process.cwd() } = {}) {
   const findings = parseFindingsJson(options.findings);
   const provenance = options.provenance === undefined ? undefined : parseProvenanceJson(options.provenance);
+  // Angle-coverage enforcement (fail-closed on missing mandatory angles / foreign
+  // angles) only applies when provenance is actually recorded — provenance
+  // remains optional and additive (inline_single_agent writes never carry it).
+  const angleCoverage = provenance !== undefined
+    ? await checkProvenanceAngleCoverage(provenance, options.gate, { repoRoot })
+    : { warning: null };
   const logPath = buildLogPath({
     repo: options.repo,
     pr: options.pr,
@@ -276,7 +320,9 @@ export async function writeGateFindingsLog(options, { repoRoot = process.cwd() }
   }
   await mkdir(path.dirname(fullPath), { recursive: true });
   await writeFile(fullPath, JSON.stringify(log, null, 2) + "\n", "utf8");
-  return { ok: true, path: logPath, log };
+  return angleCoverage.warning
+    ? { ok: true, path: logPath, log, warning: angleCoverage.warning }
+    : { ok: true, path: logPath, log };
 }
 async function main() {
   let options;
@@ -293,6 +339,12 @@ async function main() {
   }
   try {
     const result = await writeGateFindingsLog(options);
+    // rejectForeignAngles: false is WARNING mode, not silence — surface the
+    // angle-coverage warning on stderr too (the JSON result carries it as
+    // `warning`). Suppressed under --silent.
+    if (result.warning && !options.silent) {
+      process.stderr.write(`WARNING: ${result.warning}\n`);
+    }
     process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent });
   } catch (error) {
     process.stderr.write(JSON.stringify({

package/scripts/loop/_post-convergence-change.mjs

@@ -8,7 +8,7 @@
 // It lives in scripts/loop/ (not packages/core) because significance is derived
 // from a `gh api .../compare` diff — gh I/O that does not belong in core.
 import { extractReviewCommitSha, isCopilotLogin, parseJsonText } from "../_core-helpers.mjs";
-import { runChild } from "../_cli-primitives.mjs";
+import { runChild as defaultRunChild } from "../_cli-primitives.mjs";
 
 export function getLatestSubmittedCopilotReviewHeadSha(reviews) {
   const copilotSubmitted = (Array.isArray(reviews) ? reviews : [])
@@ -149,7 +149,7 @@ export function isCommentOnlyFileChange(file) {
 
 export async function detectPostConvergenceSignificantChange(
   { repo, pr, currentHeadSha, reviews, changedFiles, roundCapReached, regularCopilotRounds },
-  { env = process.env, ghCommand = "gh" } = {},
+  { env = process.env, ghCommand = "gh", runChild = defaultRunChild } = {},
 ) {
   if (!roundCapReached || !regularCopilotRounds) {
     return false;