dev-loops 0.6.0 → 0.7.2

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

@@ -17,7 +17,9 @@
  * This module maps that resolver's output into the persisted artifact:
  *   resolvedAngles  = resolver.recommendedAngles
  *   rationale       = resolver.skippedAngles (action 'dropped', reason from
- *                     resolver.reasons) + the rest as action 'kept'
+ *                     resolver.reasons) + the rest as action 'kept', except
+ *                     entries present in resolver.addedAngles are recorded as
+ *                     action 'added' (reason from resolver.addedReasons) — see #1048
  *
  * The artifact records the resolved angle set + rationale + change scope
  * (branch, head SHA, touched files, acceptance-criteria pointer, validation
@@ -26,6 +28,8 @@
  * Path scheme mirrors write-gate-findings-log.mjs `buildLogPath`:
  *   <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";
@@ -35,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 { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 /**
  * Map the artifact gate name (draft_gate | pre_approval_gate) to the config
@@ -52,8 +57,12 @@ export function mapGateToConfigKey(gate) {
  * Map a resolveGateAnglesDynamic result into the persisted artifact fields.
  * Does NOT re-derive angles — it only reshapes the resolver's output.
  *
- * @param {{ recommendedAngles: string[]|null, skippedAngles?: string[], reasons?: Record<string,string> }} resolverResult
- * @returns {{ resolvedAngles: string[], rationale: Array<{angle: string, action: "kept"|"dropped", reason: string}> }}
+ * Angles present in `resolverResult.addedAngles` (additive selection, #1048)
+ * are recorded with action 'added' (reason from `resolverResult.addedReasons`)
+ * instead of 'kept'.
+ *
+ * @param {{ recommendedAngles: string[]|null, skippedAngles?: string[], reasons?: Record<string,string>, addedAngles?: string[], addedReasons?: Record<string,string>, dynamicAnglesActive?: boolean }} resolverResult
+ * @returns {{ resolvedAngles: string[], rationale: Array<{angle: string, action: "kept"|"added"|"dropped", reason: string}> }}
  */
 export function rationaleFromResolver(resolverResult) {
   const recommended = Array.isArray(resolverResult?.recommendedAngles)
@@ -63,6 +72,8 @@ export function rationaleFromResolver(resolverResult) {
     ? resolverResult.skippedAngles
     : [];
   const reasons = resolverResult?.reasons ?? {};
+  const added = new Set(Array.isArray(resolverResult?.addedAngles) ? resolverResult.addedAngles : []);
+  const addedReasons = resolverResult?.addedReasons ?? {};
   const dynamicActive = resolverResult?.dynamicAnglesActive === true;
   const keptReason = dynamicActive
     ? "selected by dynamic angle resolver"
@@ -70,6 +81,16 @@ export function rationaleFromResolver(resolverResult) {
 
   const rationale = [];
   for (const angle of recommended) {
+    if (added.has(angle) && dynamicActive) {
+      rationale.push({
+        angle,
+        action: "added",
+        reason: typeof addedReasons[angle] === "string" && addedReasons[angle].length > 0
+          ? addedReasons[angle]
+          : "added by dynamic angle resolver (catalog addition)",
+      });
+      continue;
+    }
     rationale.push({ angle, action: "kept", reason: keptReason });
   }
   for (const angle of skipped) {
@@ -84,7 +105,7 @@ export function rationaleFromResolver(resolverResult) {
   return { resolvedAngles: [...recommended], rationale };
 }
 
-const USAGE = `Usage: write-gate-context.mjs --repo <owner/name> --pr <number> --gate <draft_gate|pre_approval_gate> --head-sha <sha> --angles <json> [--rationale <json>] [--branch <name>] [--touched-files <json>] [--acceptance-criteria <pointer>] [--validation-posture <text>] [--tmp-root <path>]
+const USAGE = `Usage: write-gate-context.mjs --repo <owner/name> --pr <number> --gate <draft_gate|pre_approval_gate> --head-sha <sha> --angles <json> [--rationale <json>] [--branch <name>] [--touched-files <json>] [--base <ref>] [--acceptance-criteria <pointer>] [--validation-posture <text>] [--tmp-root <path>]
 Write a deterministic gate-review context-builder handoff artifact under tmp/ paths.
 Required:
   --repo <owner/name>
@@ -95,10 +116,15 @@ Required:
 Optional:
   --rationale <json>             JSON array of {angle, action, reason} entries
   --branch <name>                Source branch name
-  --touched-files <json>         JSON array of changed file path strings
-  --acceptance-criteria <ptr>    Pointer to acceptance criteria (issue ref, doc path, URL)
+  --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); 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}
 `.trim();
 
 function parseError(message) {
@@ -116,6 +142,22 @@ function normalizeHeadSha(value) {
   return /^[0-9a-f]{7,64}$/i.test(normalized) ? normalized : null;
 }
 
+// ponytail: a DENYLIST, not an allowlist — the `git diff` call runs via
+// execFileSync's argv array (no shell), so `base` cannot inject shell syntax
+// and we don't need to enumerate every valid git revision grammar. We reject
+// only what is genuinely unsafe or malformed for OUR use, and let `git diff`
+// itself resolve validity (a syntactically-allowed but nonexistent ref fails
+// closed via the unresolvable-base path). Rejected: empty/whitespace-only; a
+// leading "-" (flag-injection shape, never a valid ref); and ".." (ambiguous
+// 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.
+function normalizeBaseRef(value) {
+  const trimmed = String(value).trim();
+  if (trimmed.length === 0 || trimmed.startsWith("-") || trimmed.includes("..")) return null;
+  return trimmed;
+}
+
 const VALID_ACTIONS = new Set(["kept", "added", "dropped", "joined"]);
 
 function parseAnglesJson(raw) {
@@ -189,9 +231,13 @@ export function parseWriteGateContextCliArgs(argv) {
       rationale: { type: "string" },
       branch: { type: "string" },
       "touched-files": { type: "string" },
+      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,
     },
     allowPositionals: true,
     strict: false,
@@ -206,8 +252,11 @@ export function parseWriteGateContextCliArgs(argv) {
     rationale: [],
     branch: null,
     touchedFiles: [],
+    base: null,
     acceptanceCriteria: null,
     validationPosture: null,
+    prBody: null,
+    issueBody: null,
     tmpRoot: "tmp",
   };
   for (const token of tokens) {
@@ -256,6 +305,12 @@ export function parseWriteGateContextCliArgs(argv) {
       options.touchedFiles = parseStringArrayJson(requireTokenValue(token, parseError), "--touched-files");
       continue;
     }
+    if (token.name === "base") {
+      const base = normalizeBaseRef(requireTokenValue(token, parseError));
+      if (!base) throw parseError("--base must be a plausible git ref (no leading '-', no '..')");
+      options.base = base;
+      continue;
+    }
     if (token.name === "acceptance-criteria") {
       options.acceptanceCriteria = requireTokenValue(token, parseError).trim();
       continue;
@@ -264,10 +319,19 @@ 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;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   const missing = ["repo", "pr", "gate", "headSha", "angles"]
@@ -377,6 +441,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 <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
@@ -437,15 +632,186 @@ export function buildGateContextArtifact(options) {
       validationPosture: options.validationPosture ?? null,
     },
   };
+  // ADD (#1140): an explicit posture marker distinguishing a full build-once
+  // bundle from a thin briefing. Only set by the CLI (`--base` present → "base";
+  // absent → "none"); programmatic `buildGateContext`/`writeGateContext` callers
+  // that never pass `diffSource` leave the field out entirely, so this stays
+  // backward compatible with the artifact shape they already assert on.
+  if (typeof options.diffSource === "string" && options.diffSource.length > 0) {
+    artifact.scope.diffSource = options.diffSource;
+  }
   // ADD (#895): the deterministic, neutral adjacent-code bundle. Only present
   // when the context-builder computed it — keeps the artifact shape backward
   // compatible for callers that build the artifact without an adjacency pass.
   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;
 }
 
+/**
+ * Resolve the diff-derived scope fields shared by `buildGateContext` (the
+ * programmatic `{ diff }` path) and the CLI `--base` path (#1140): the FULL
+ * diff persisted to a deterministic `.diff` file, the parsed `changedFiles`,
+ * and the neutral `adjacentCode` bundle built once from those changed files.
+ * Extracted to a single function so both callers stay in sync — see the
+ * doc comment on {@link buildGateContext} for the field semantics.
+ *
+ * @param {object} input
+ * @param {{ nameStatusOutput: string, diffOutput?: string }} [input.diff]
+ * @param {string} input.repo
+ * @param {number|string} input.pr
+ * @param {string} input.gate
+ * @param {string} input.headSha
+ * @param {string} input.tmpRoot
+ * @param {number} [input.maxFileBytes]
+ * @param {{ repoRoot: string }} opts
+ * @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;
+  let diffPath = null;
+  const changedFiles = parseChangedFiles(diff?.nameStatusOutput);
+  if (typeof diffOutput === "string" && diffOutput.length > 0) {
+    diffPath = buildGateDiffPath({ repo, pr, gate, headSha, tmpRoot });
+    const fullDiffPath = path.resolve(repoRoot, diffPath);
+    try {
+      await mkdir(path.dirname(fullDiffPath), { recursive: true });
+      await writeFile(fullDiffPath, diffOutput.endsWith("\n") ? diffOutput : diffOutput + "\n", "utf8");
+    } catch (err) {
+      // Best-effort: a diff-file write failure (disk, permissions) must not block
+      // the context artifact. Degrade to diffPath=null; reviewers reconstruct the
+      // diff with `git diff`. changedFiles (from nameStatusOutput) is unaffected.
+      process.stderr.write(`[gate-context] full-diff capture failed (continuing without scope.diffPath): ${err?.message ?? err}\n`);
+      diffPath = null;
+    }
+  }
+
+  // Build the deterministic, neutral adjacent-code bundle ONCE (#895): for each
+  // changed source file, include its 1-hop import out-edges (files it imports)
+  // and in-edges (files that import it), with size guards (skip
+  // lockfiles/generated/binary/minified; cap per-file bytes; truncate the long
+  // tail) recorded in a stripped/truncated manifest. Every independent reviewer
+  // is seeded with this identical bundle instead of re-deriving it — work-dedup.
+  // Best-effort: bundle computation must never block the context artifact.
+  let adjacentCode = null;
+  if (changedFiles.length > 0) {
+    try {
+      adjacentCode = await buildAdjacentBundle({
+        changedFiles,
+        repoRoot,
+        maxFileBytes: typeof maxFileBytes === "number" && maxFileBytes > 0 ? maxFileBytes : DEFAULT_MAX_FILE_BYTES,
+      });
+    } catch (err) {
+      process.stderr.write(`[gate-context] adjacent-code bundle failed (continuing without adjacentCode): ${err?.message ?? err}\n`);
+      adjacentCode = null;
+    }
+  }
+
+  return { diffPath, changedFiles, adjacentCode, diffOutput: typeof diffOutput === "string" ? diffOutput : null };
+}
+
+/**
+ * Capture a diff against `base` for the CLI `--base <ref>` flag: `git diff
+ * --name-status <base>...HEAD` and `git diff <base>...HEAD`, shaped as the
+ * `{ nameStatusOutput, diffOutput }` input `resolveDiffScope`/`buildGateContext`
+ * expect. Uses execFileSync with an argv array (no shell), so `base` cannot
+ * inject shell syntax; `parseWriteGateContextCliArgs` additionally validates it
+ * looks like a plausible ref before this runs.
+ *
+ * Split posture:
+ * - the `--name-status` capture is FAIL-CLOSED: it drives scope.changedFiles +
+ *   the adjacentCode bundle, so an unresolvable base / non-git-repo throws and
+ *   the CLI writes NO artifact (never a silent thin briefing).
+ * - the FULL diff capture is BEST-EFFORT: if it fails (output exceeds maxBuffer,
+ *   a rendering error, etc.) we warn and return an EMPTY diffOutput. downstream
+ *   resolveDiffScope then leaves scope.diffPath null while still populating
+ *   changedFiles + adjacentCode; reviewers fall back to re-deriving the diff
+ *   (the existing safety net). scope.diffSource stays "base" — it IS a
+ *   base-derived bundle, just without the persisted full diff.
+ *
+ * @param {string} base
+ * @param {{ repoRoot: string, maxBuffer?: number }} opts — maxBuffer overridable for tests
+ * @returns {{ nameStatusOutput: string, diffOutput: string }}
+ */
+export function captureDiffFromBase(base, { repoRoot, maxBuffer = 64 * 1024 * 1024 }) {
+  const range = `${base}...HEAD`;
+  // Isolate the persisted .diff BYTES from ambient global/system gitconfig so
+  // every reviewer is seeded with an IDENTICAL neutral bundle (the whole point
+  // of build-once). Without this isolation, an operator/CI with
+  // color.diff=always, a configured diff.external/difftool, or non-default
+  // prefix settings would make scope.diffPath environment-dependent.
+  // color.ui=false + color.diff=false strip ANSI; core.pager=cat neutralizes a
+  // configured pager; diff.noprefix=false + diff.mnemonicPrefix=false pin the
+  // a/ b/ prefixes; the --no-ext-diff flag (below) disables any external diff
+  // driver (NOT `-c diff.external=`, which makes git try to exec the empty
+  // string and die).
+  // CROSS-environment reproducibility (#1168): the overrides above only pin
+  // bytes WITHIN a single run/machine — an operator/CI box with a contrary
+  // local diff.renames/diff.algorithm/diff.context/core.abbrev/core.autocrlf
+  // would still produce different bytes than another box on the SAME base and
+  // HEAD. diff.algorithm=myers + diff.context=3 + core.abbrev=12 +
+  // core.autocrlf=false pin the diff body/hunk headers/blob-id length/line
+  // endings. diff.renames=true additionally pins rename DETECTION itself: with
+  // it off, a moved-and-edited file shows as a straight D+A pair in
+  // `--name-status` instead of an R### pair, which changes the SET of names in
+  // scope.changedFiles (and therefore adjacentCode's membership) across
+  // environments, not just the diff body's bytes.
+  const isolation = [
+    "-c", "color.ui=false",
+    "-c", "color.diff=false",
+    "-c", "core.pager=cat",
+    "-c", "diff.noprefix=false",
+    "-c", "diff.mnemonicPrefix=false",
+    "-c", "diff.renames=true",
+    "-c", "diff.algorithm=myers",
+    "-c", "diff.context=3",
+    "-c", "core.abbrev=12",
+    "-c", "core.autocrlf=false",
+  ];
+  const runGit = (args) => execFileSync("git", [...isolation, ...args], {
+    cwd: repoRoot,
+    encoding: "utf8",
+    maxBuffer,
+  });
+  // FAIL-CLOSED: --name-status feeds changedFiles + adjacentCode (the bundle's core).
+  let nameStatusOutput;
+  try {
+    nameStatusOutput = runGit(["diff", "--no-ext-diff", "--name-status", range]);
+  } catch (err) {
+    throw new Error(`git diff against --base ${JSON.stringify(base)} failed: ${err?.message ?? err}`);
+  }
+  // BEST-EFFORT: the full diff only feeds the persisted scope.diffPath; on
+  // failure degrade to an empty diffOutput (diffPath becomes null downstream).
+  let diffOutput = "";
+  try {
+    diffOutput = runGit(["diff", "--no-ext-diff", range]);
+  } catch (err) {
+    process.stderr.write(`[gate-context] full-diff capture against --base ${JSON.stringify(base)} failed (continuing without scope.diffPath): ${err?.message ?? err}\n`);
+    diffOutput = "";
+  }
+  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,
@@ -454,14 +820,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 };
 }
 
 /**
@@ -484,10 +885,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
@@ -503,58 +906,13 @@ export async function buildGateContext(input, { repoRoot = process.cwd() } = {})
 
   const tmpRoot = input.tmpRoot || "tmp";
 
-  // Best-effort full-diff capture: when the resolver was handed a diff with
-  // `diffOutput`, persist the ENTIRE diff to a deterministic `.diff` file next
-  // to the context artifact so scoped reviewers can read the full change set
-  // (not just hunks) and trace adjacent code. Reference it from `scope.diffPath`
-  // (relative) and record full repo-relative `scope.changedFiles` parsed from
-  // the diff's `nameStatusOutput`. We do NOT inline the diff in the JSON.
-  const diffOutput = input.diff?.diffOutput;
-  let diffPath = null;
-  let changedFiles = parseChangedFiles(input.diff?.nameStatusOutput);
-  if (typeof diffOutput === "string" && diffOutput.length > 0) {
-    diffPath = buildGateDiffPath({
-      repo: input.repo,
-      pr: input.pr,
-      gate: input.gate,
-      headSha: input.headSha,
-      tmpRoot,
-    });
-    const fullDiffPath = path.resolve(repoRoot, diffPath);
-    try {
-      await mkdir(path.dirname(fullDiffPath), { recursive: true });
-      await writeFile(fullDiffPath, diffOutput.endsWith("\n") ? diffOutput : diffOutput + "\n", "utf8");
-    } catch (err) {
-      // Best-effort: a diff-file write failure (disk, permissions) must not block
-      // the context artifact. Degrade to diffPath=null; reviewers reconstruct the
-      // diff with `git diff`. changedFiles (from nameStatusOutput) is unaffected.
-      process.stderr.write(`[gate-context] full-diff capture failed (continuing without scope.diffPath): ${err?.message ?? err}\n`);
-      diffPath = null;
-    }
-  }
-
-  // Build the deterministic, neutral adjacent-code bundle ONCE (#895): for each
-  // changed source file, include its 1-hop import out-edges (files it imports)
-  // and in-edges (files that import it), with size guards (skip
-  // lockfiles/generated/binary/minified; cap per-file bytes; truncate the long
-  // tail) recorded in a stripped/truncated manifest. Every independent reviewer
-  // is seeded with this identical bundle instead of re-deriving it — work-dedup.
-  // Best-effort: bundle computation must never block the context artifact.
-  let adjacentCode = null;
-  if (changedFiles.length > 0) {
-    try {
-      adjacentCode = await buildAdjacentBundle({
-        changedFiles,
-        repoRoot,
-        maxFileBytes: typeof input.maxFileBytes === "number" && input.maxFileBytes > 0
-          ? input.maxFileBytes
-          : DEFAULT_MAX_FILE_BYTES,
-      });
-    } catch (err) {
-      process.stderr.write(`[gate-context] adjacent-code bundle failed (continuing without adjacentCode): ${err?.message ?? err}\n`);
-      adjacentCode = null;
-    }
-  }
+  // 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, diffOutput } = await resolveDiffScope(
+    { diff: input.diff, repo: input.repo, pr: input.pr, gate: input.gate, headSha: input.headSha, tmpRoot, maxFileBytes: input.maxFileBytes },
+    { repoRoot },
+  );
 
   const writeResult = await writeGateContext(
     {
@@ -568,9 +926,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 },
@@ -604,10 +965,17 @@ export async function readGateContext(input, { repoRoot = process.cwd() } = {})
   }
 }
 
-async function main() {
+/**
+ * CLI entrypoint. Exported (argv + repoRoot both overridable) so tests can
+ * drive the `--base` diff-capture path against a throwaway git repo fixture
+ * without spawning a subprocess.
+ * @param {string[]} [argv]
+ * @param {{ repoRoot?: string }} [runtime]
+ */
+export async function main(argv = process.argv.slice(2), { repoRoot = process.cwd() } = {}) {
   let options;
   try {
-    options = parseWriteGateContextCliArgs(process.argv.slice(2));
+    options = parseWriteGateContextCliArgs(argv);
   } catch (error) {
     process.stderr.write(`${formatCliError(error, { usage: USAGE })}\n`);
     process.exitCode = 1;
@@ -618,8 +986,33 @@ async function main() {
     return;
   }
   try {
-    const result = await writeGateContext(options);
-    process.stdout.write(JSON.stringify(result) + "\n");
+    // AC3 (#1140): the CLI only produces the full build-once bundle
+    // (scope.diffPath + scope.changedFiles + adjacentCode) when it has a
+    // resolvable diff source. --base is OPTIONAL rather than required — making
+    // it required would break any existing caller that only ever passed
+    // --touched-files (angles + scope already resolved elsewhere) — so a run
+    // without --base does not fail closed; it explicitly WARNS and records the
+    // thin-briefing posture in scope.diffSource so it is never mistaken for a
+    // full bundle. A run WITH --base that then fails to resolve (bad ref, not a
+    // git repo, etc.) DOES fail closed: the caller opted into the full bundle,
+    // so a silent thin degrade there would be a worse surprise than an error.
+    if (options.base) {
+      const diff = captureDiffFromBase(options.base, { repoRoot });
+      const scope = await resolveDiffScope(
+        { diff, repo: options.repo, pr: options.pr, gate: options.gate, headSha: options.headSha, tmpRoot: options.tmpRoot || "tmp" },
+        { repoRoot },
+      );
+      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");
+      options.diffSource = "none";
+    }
+    const result = await writeGateContext(options, { repoRoot });
+    process.exitCode = emitResult(result, { jq: options.jq, silent: options.silent });
   } catch (error) {
     process.stderr.write(JSON.stringify({
       ok: false,