@dev-loops/core 1.0.0-rc.6 → 1.0.0-rc.7

package/src/loop/review-dispatch-plan.mjs

@@ -22,7 +22,10 @@
  *     briefing block and before the late volatile tail + angle suffix.
  *  4. Dispatch-plan builder — one deterministic per-gate-round artifact that
  *     records the complete cache-relevant request shape without duplicating
- *     briefing content (Section A).
+ *     briefing content (Section A). `buildAngleRequestGroups` partitions a
+ *     caller's angle -> concrete-model resolutions into that plan's
+ *     `requestGroups` shape, bucketing angles with no override into an
+ *     explicit "inherit" key rather than merging them into a concrete group.
  *  5. Primer-form default — deterministic default by harness capability
  *     (Section C/D): first-output-observable harnesses may let a lead reviewer
  *     prime; completion-only harnesses default to a short dedicated primer
@@ -187,20 +190,51 @@ export function sha256Hex(content) {
   return `sha256:${h.digest("hex")}`;
 }
 
-const isPlainObject = (v) =>
-  v != null && typeof v === "object" && !Array.isArray(v) && !Buffer.isBuffer(v);
+/** True for a non-null value whose prototype is exactly Object.prototype or null (a JSON-shaped record, never a Date/Map/Set/class instance). */
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
 
-/** Recursively sort object keys for a byte-deterministic serialization. */
-function stableStringify(value) {
-  if (Array.isArray(value)) return value.map(stableStringify);
+/**
+ * Recursively sort object keys for a byte-deterministic serialization (arrays
+ * keep their order — order is itself cache-relevant for tool definitions and
+ * content-block boundaries).
+ *
+ * Trust-boundary validation, refusing loudly rather than silently colliding
+ * two distinct inputs onto one fingerprint: a non-finite number (NaN/
+ * Infinity) is rejected rather than let `JSON.stringify` collapse it to
+ * `null`, a non-plain object (Date/Map/Set/...) is rejected rather than let
+ * `Object.keys` see it as keyless (and therefore indistinguishable from
+ * `{}`), and undefined/function/symbol/bigint are rejected rather than
+ * silently dropped or crash-serialized by `JSON.stringify` itself. The
+ * accumulator is null-prototype so an own `__proto__` key (a realistic shape
+ * for JSON.parse'd input) is kept as a plain data property instead of
+ * vanishing into the prototype chain.
+ * @param {*} value
+ * @param {string} [keyPath] — dotted path to `value`, for the error message
+ * @returns {*}
+ */
+function stableStringify(value, keyPath = "$") {
+  if (Array.isArray(value)) return value.map((entry, i) => stableStringify(entry, `${keyPath}[${i}]`));
   // Canonicalize nested Buffers to hex (the `__buffer:` prefix keeps a Buffer
   // distinct from a string that happens to equal its hex, so bytes and text can
   // never collide). Mirrors sha256Hex's top-level Buffer handling so a push/pull
   // through memory vs disk yields identical bytes even for nested buffers.
   if (Buffer.isBuffer(value)) return `__buffer:${value.toString("hex")}`;
-  if (isPlainObject(value)) {
-    const out = {};
-    for (const key of Object.keys(value).sort()) out[key] = stableStringify(value[key]);
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    throw new Error(`sha256Hex: fingerprint input at ${keyPath} is a non-finite number (${value}) — refusing to collapse it to JSON null`);
+  }
+  if (value === undefined || typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") {
+    throw new Error(`sha256Hex: fingerprint input at ${keyPath} is a ${typeof value} — refusing to silently drop or crash-serialize it`);
+  }
+  if (value !== null && typeof value === "object") {
+    if (!isPlainObject(value)) {
+      throw new Error(`sha256Hex: fingerprint input at ${keyPath} is not a plain object (got ${Object.prototype.toString.call(value)}) — refusing to canonicalize a keyless collision`);
+    }
+    const out = Object.create(null);
+    for (const key of Object.keys(value).sort()) out[key] = stableStringify(value[key], `${keyPath}.${key}`);
     return out;
   }
   return value;
@@ -491,6 +525,107 @@ function validateRequestGroups(requestGroups) {
   });
 }
 
+/* ------------------------------------------------------------------ *
+ * 4b. Angle model bucketing (per-caller angle -> concrete model resolution)
+ * ------------------------------------------------------------------ */
+
+/**
+ * `requestGroups` bucket key for angles whose model resolution is "no
+ * override" (inherit). Reserved: a caller-resolved concrete model literally
+ * named this would otherwise collide with the "no override" bucket and
+ * become indistinguishable from genuine inherit.
+ */
+export const INHERIT_MODEL_KEY = "inherit";
+
+/**
+ * Partition a caller's angle -> concrete-model resolutions into fingerprinted
+ * request groups ready for {@link buildReviewDispatchPlan}'s `requestGroups`
+ * input. Angles resolving to the same concrete model id share one group;
+ * angles with no override (`model: null`/`undefined`) form their own explicit
+ * {@link INHERIT_MODEL_KEY} bucket, never merged with a concrete id. An angle
+ * listed twice with two DIFFERENT models is a caller bug and throws (an angle
+ * cannot honestly belong to two request groups). A concrete model literally
+ * named {@link INHERIT_MODEL_KEY} also throws — it would otherwise silently
+ * collide with the reserved bucket key and become indistinguishable from
+ * genuine no-override.
+ *
+ * Each group's `requestPrefixFingerprint` is computed via
+ * {@link fingerprintRequestPrefix} over every cache-relevant input this layer
+ * observes for that group (the bucket's model, tool set/order, instructions,
+ * settings, content-block boundaries, the shared-prefix bytes, and the
+ * declared cache boundary/TTL intent) — changing only the angle set within a
+ * bucket never changes its fingerprint.
+ *
+ * @param {object} input
+ * @param {Array<{angle: string, model: string|null}>} input.angleModels
+ * @param {string} [input.sharedPrefixHash] — folded in as the fingerprint's shared-artifact reference.
+ * @param {Array<string|object>} [input.toolDefinitions] — tool names/definitions in dispatch order
+ * @param {string|string[]} [input.instructions] — system/project/agent instruction bytes (or a digest)
+ * @param {object} [input.settings] — thinking/tool-choice settings
+ * @param {string[]} [input.blockBoundaries] — content-block boundary markers, in order
+ * @param {string} [input.cacheBoundary]
+ * @param {string} [input.ttlIntent] — one of TTL_INTENT_VALUES
+ * @returns {RequestGroup[]} sorted by model (code-unit order, never localeCompare — ICU-dependent
+ *   sorting could order the same two model ids differently across runtimes); angles sorted within a group.
+ */
+export function buildAngleRequestGroups({
+  angleModels,
+  sharedPrefixHash,
+  toolDefinitions = [],
+  instructions = "",
+  settings = {},
+  blockBoundaries = [],
+  cacheBoundary = CACHE_BOUNDARY_AFTER_SHARED_PREFIX,
+  ttlIntent = "harness_managed",
+} = {}) {
+  if (!Array.isArray(angleModels)) {
+    throw new Error("buildAngleRequestGroups: angleModels must be an array of { angle, model }");
+  }
+
+  const angleToModelKey = new Map();
+  const anglesByModelKey = new Map();
+  for (const entry of angleModels) {
+    const angle = typeof entry?.angle === "string" ? entry.angle.trim() : "";
+    if (angle.length === 0) {
+      throw new Error("buildAngleRequestGroups: every angleModels entry needs a non-empty string angle");
+    }
+    const rawModel = entry.model;
+    if (rawModel != null && (typeof rawModel !== "string" || rawModel.trim().length === 0)) {
+      throw new Error(`buildAngleRequestGroups: angleModels entry for "${angle}" has an invalid model (must be a non-empty string, or null/undefined for inherit)`);
+    }
+    const modelKey = rawModel == null ? INHERIT_MODEL_KEY : rawModel.trim();
+    if (rawModel != null && modelKey === INHERIT_MODEL_KEY) {
+      throw new Error(`buildAngleRequestGroups: angle "${angle}" has a concrete model literally named ${JSON.stringify(INHERIT_MODEL_KEY)}, which collides with the bucket key reserved for "no override" — rename the model, or resolve it to null/undefined instead of the literal string`);
+    }
+
+    const priorKey = angleToModelKey.get(angle);
+    if (priorKey !== undefined && priorKey !== modelKey) {
+      throw new Error(`buildAngleRequestGroups: angle "${angle}" is listed with two different models ("${priorKey}" and "${modelKey}") — an angle cannot belong to two request groups`);
+    }
+    angleToModelKey.set(angle, modelKey);
+
+    if (!anglesByModelKey.has(modelKey)) anglesByModelKey.set(modelKey, new Set());
+    anglesByModelKey.get(modelKey).add(angle);
+  }
+
+  return [...anglesByModelKey.entries()]
+    .map(([model, angleSet]) => {
+      const angles = [...angleSet].sort();
+      const { fingerprint } = fingerprintRequestPrefix({
+        model,
+        tools: toolDefinitions,
+        systemInstructions: instructions,
+        settings,
+        contentBlocks: blockBoundaries,
+        sharedArtifact: sharedPrefixHash,
+        cacheBoundary,
+        ttlIntent,
+      });
+      return { model, requestPrefixFingerprint: fingerprint, cacheBoundary, ttlIntent, angles };
+    })
+    .sort((a, b) => (a.model < b.model ? -1 : a.model > b.model ? 1 : 0));
+}
+
 /* ------------------------------------------------------------------ *
  * 5. Primer-form default (Section C/D)
  * ------------------------------------------------------------------ */
@@ -593,3 +728,307 @@ export function partitionPrimerGroups(requestGroups, capabilities = {}) {
   }
   return out;
 }
+
+/* ------------------------------------------------------------------ *
+ * 6. Dispatch-prompt layout alignment (issue #1841, completes #1468)
+ * ------------------------------------------------------------------ */
+
+// Leading-bytes capture cap for a dispatched reviewer prompt (issue #1841's
+// record-dispatch-prompt-layout.mjs). Sized comfortably above
+// write-gate-context.mjs's BRIEFING_PREFIX_INLINE_DIFF_CAP_BYTES (200 KiB) so
+// a full byte-for-byte alignment check never runs out of captured bytes for
+// an inline-mode round.
+export const DISPATCH_PROMPT_LEADING_CAP_BYTES = 512 * 1024;
+
+/**
+ * Render the byte-identical pointer LINE a reviewer prompt must lead with
+ * under pointer-seeding mode (GATE-EXEC-BRIEFING-PREFIX's "Cache alignment"
+ * paragraph): the orchestrator points every reviewer of the round at the SAME
+ * invariant-prefix file path rather than inlining its bytes. Deterministic in
+ * `prefixPath` alone, so two reviewers given the same path render the
+ * identical line, and a per-reviewer/angle-varying path (which would defeat
+ * prefix matching) renders a DIFFERENT line, exactly reproducing the defect
+ * this line exists to catch.
+ *
+ * @param {string} prefixPath — the invariant-prefix file path every reviewer
+ *   of the round is pointed at (e.g. the `<gate>-<headSha>.briefing-prefix.txt`
+ *   path).
+ * @returns {string}
+ */
+export function renderBriefingPointerLine(prefixPath) {
+  if (typeof prefixPath !== "string" || prefixPath.trim().length === 0) {
+    throw new Error("renderBriefingPointerLine requires a non-empty prefixPath");
+  }
+  return `Read ${prefixPath.trim()} FIRST, in full, before anything else in this prompt — it is this round's byte-identical invariant briefing prefix (GATE-EXEC-BRIEFING-PREFIX). Your angle-specific instructions follow below, after it.`;
+}
+
+/**
+ * Deterministically compose a full reviewer prompt: the round's
+ * byte-identical invariant prefix INLINED as the leading bytes, followed by
+ * the (also round-invariant) volatile tail, followed by the per-group angle
+ * suffix (issue #1852). This is the ONE function every reviewer prompt on the
+ * canonical fan-out path is built from — never a hand-assembled per-group
+ * preamble that leads with dynamic prose ahead of the prefix (the
+ * "angle-first" / pointer-seeding failure mode `verifyPromptLeadingAlignment`
+ * exists to catch).
+ *
+ * Byte-identical-prefix-across-groups falls out of the arguments alone: any
+ * two calls sharing the same `prefixBytes`/`volatileBytes` (true for every
+ * dispatch unit of one round, since both are round-scoped, not group-scoped)
+ * produce prompts whose leading span is identical regardless of
+ * `angleSuffix` — the property AC1 requires, provable by construction rather
+ * than by review.
+ *
+ * Pure and offline: takes already-read bytes, never reads a file itself (the
+ * CLI wrapper, `compose-reviewer-prompt.mjs`, owns I/O and the
+ * record-dispatch-prompt-layout.mjs capture that makes the composed prompt's
+ * layout binding on `verify-dispatch-prompt-layout.mjs`).
+ *
+ * @param {object} input
+ * @param {string} input.prefixBytes — the round's invariant-prefix bytes
+ *   (`<gate>-<headSha>.briefing-prefix.txt`), non-empty.
+ * @param {string} [input.volatileBytes] — the round's volatile-tail bytes
+ *   (`<gate>-<headSha>.briefing-volatile.txt`); absent/non-string treated as
+ *   "" (best-effort — a round that never wrote one still composes).
+ * @param {string} input.angleSuffix — the per-group/angle-specific prompt
+ *   text, non-empty (an empty suffix would compose a prompt naming no work).
+ * @returns {string} the exact full reviewer prompt text.
+ */
+export function composeReviewerPromptText({ prefixBytes, volatileBytes, angleSuffix } = {}) {
+  if (typeof prefixBytes !== "string" || prefixBytes.length === 0) {
+    throw new Error("composeReviewerPromptText requires non-empty prefixBytes (the round's invariant prefix)");
+  }
+  if (typeof angleSuffix !== "string" || angleSuffix.trim().length === 0) {
+    throw new Error("composeReviewerPromptText requires a non-empty angleSuffix (the per-group angle-specific prompt)");
+  }
+  const volatile = typeof volatileBytes === "string" ? volatileBytes : "";
+  return prefixBytes + volatile + angleSuffix;
+}
+
+/**
+ * Decide whether a dispatched reviewer prompt's LEADING bytes are
+ * cache-aligned (GATE-EXEC-BRIEFING-PREFIX layout, issue #1841): either the
+ * prompt's leading bytes are byte-identical to the round's invariant prefix
+ * (inline mode), or the prompt leads with the byte-identical pointer line
+ * naming the round's invariant-prefix path (pointer-seeding mode), with any
+ * angle-specific text strictly AFTER it. An angle-first prompt (dynamic
+ * per-unit prose ahead of the prefix/pointer) matches neither and is
+ * REJECTED — this is the mechanical proof the prose-only rule lacked.
+ *
+ * Pure and offline: takes the already-captured leading bytes and the already-
+ * read prefix bytes/path, never reads a file itself (the CLI wrapper owns
+ * I/O), so this is directly unit-testable with in-memory strings.
+ *
+ * @param {object} input
+ * @param {string} input.promptLeading — the captured leading bytes of the
+ *   ACTUAL reviewer prompt (record-dispatch-prompt-layout.mjs's capture).
+ * @param {string} input.prefixBytes — the round's recorded byte-identical
+ *   invariant-prefix content (the `<gate>-<headSha>.briefing-prefix.txt`
+ *   bytes).
+ * @param {string} input.prefixPath — the path used to render this round's
+ *   pointer line (must be the SAME path every reviewer was pointed at).
+ * @returns {{ aligned: boolean, mode: "inline"|"pointer"|null, reason: string|null }}
+ */
+export function verifyPromptLeadingAlignment({ promptLeading, prefixBytes, prefixPath } = {}) {
+  const leading = typeof promptLeading === "string" ? promptLeading : "";
+  if (typeof prefixBytes === "string" && prefixBytes.length > 0 && leading.startsWith(prefixBytes)) {
+    return { aligned: true, mode: "inline", reason: null };
+  }
+  if (typeof prefixPath === "string" && prefixPath.trim().length > 0) {
+    const pointerLine = renderBriefingPointerLine(prefixPath);
+    if (leading.startsWith(pointerLine)) {
+      return { aligned: true, mode: "pointer", reason: null };
+    }
+  }
+  return {
+    aligned: false,
+    mode: null,
+    reason: "reviewer prompt does not LEAD with the round's byte-identical invariant prefix (inline mode) or its byte-identical pointer line (pointer-seeding mode) — an angle-first prompt (dynamic per-unit prose ahead of the prefix/pointer) defeats prefix matching (GATE-EXEC-BRIEFING-PREFIX)",
+  };
+}
+
+/* ------------------------------------------------------------------ *
+ * 7. Diff filtering for the shared per-head block (issue #1853)
+ * ------------------------------------------------------------------ */
+
+/**
+ * Default excluded path patterns for the diff INLINED into a reviewer
+ * prompt's shared per-head block: lockfiles (high-churn, not
+ * review-relevant — the file's CHANGE is still listed in the changed-files
+ * summary, only its hunk text is dropped from the inlined diff) and common
+ * generated/vendored trees. ALWAYS applied on top of any caller-supplied
+ * `excludeGlobs` in {@link filterDiffForInline} — never replaced by it, so a
+ * project-specific config gap can't silently un-exclude a lockfile. A file
+ * excluded here is not deleted from the repo or the diff on disk; it stays
+ * readable on demand (`git diff -- <path>` in the reviewed worktree, or the
+ * full unfiltered `.diff` pointer file), only not inlined by default.
+ *
+ * Glob subset: `**\/` matches zero-or-more whole path segments, a lone `**`
+ * matches any suffix, a single `*` matches within one path segment only —
+ * see {@link matchesDiffExcludeGlob}.
+ */
+export const DEFAULT_DIFF_EXCLUDE_GLOBS = Object.freeze([
+  // Lockfiles.
+  "package-lock.json", "**/package-lock.json",
+  "npm-shrinkwrap.json", "**/npm-shrinkwrap.json",
+  "yarn.lock", "**/yarn.lock",
+  "pnpm-lock.yaml", "**/pnpm-lock.yaml",
+  "*-lock.yaml", "**/*-lock.yaml",
+  "*-lock.yml", "**/*-lock.yml",
+  "Cargo.lock", "**/Cargo.lock",
+  "Gemfile.lock", "**/Gemfile.lock",
+  "composer.lock", "**/composer.lock",
+  // Generated/vendored trees.
+  "dist/**", "**/dist/**",
+  "lib/**", "**/lib/**",
+  "coverage/**", "**/coverage/**",
+  "node_modules/**", "**/node_modules/**",
+  ".claude/**", "**/.claude/**",
+]);
+
+function escapeDiffGlobLiteral(ch) {
+  return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+}
+
+const diffGlobPatternCache = new Map();
+
+/**
+ * Minimal shell-glob subset compiler (mirrors the established pattern used
+ * elsewhere in this repo for config-driven path patterns): `**\/` matches
+ * zero-or-more whole path segments, a lone `**` matches any suffix
+ * (including `/`), a single `*` matches within one path segment only,
+ * everything else is literal. No glob dependency is installed in this repo
+ * and none of the callers need more than this subset.
+ * @param {string} relPath — POSIX-normalized repo-relative path
+ * @param {string} pattern
+ * @returns {boolean}
+ */
+export function matchesDiffExcludeGlob(relPath, pattern) {
+  if (typeof relPath !== "string" || typeof pattern !== "string" || pattern.length === 0) return false;
+  let compiled = diffGlobPatternCache.get(pattern);
+  if (!compiled) {
+    let re = "";
+    for (let i = 0; i < pattern.length; i++) {
+      const ch = pattern[i];
+      if (ch === "*" && pattern[i + 1] === "*") {
+        if (pattern[i + 2] === "/") {
+          re += "(?:.*/)?";
+          i += 2;
+        } else {
+          re += ".*";
+          i += 1;
+        }
+      } else if (ch === "*") {
+        re += "[^/]*";
+      } else {
+        re += escapeDiffGlobLiteral(ch);
+      }
+    }
+    compiled = new RegExp(`^${re}$`);
+    diffGlobPatternCache.set(pattern, compiled);
+  }
+  return compiled.test(relPath);
+}
+
+/**
+ * Classify why a diff file is excluded from inlining, or `null` when it
+ * should be inlined. Checks {@link DEFAULT_DIFF_EXCLUDE_GLOBS} first, then
+ * any caller-supplied `excludeGlobs` — the default set can never be
+ * disabled by a caller's config.
+ * @param {string} relPath
+ * @param {{ excludeGlobs?: string[] }} [opts]
+ * @returns {"default"|"configured"|null}
+ */
+export function classifyDiffFileExclusion(relPath, { excludeGlobs = [] } = {}) {
+  const posix = String(relPath).replace(/\\/g, "/");
+  for (const pattern of DEFAULT_DIFF_EXCLUDE_GLOBS) {
+    if (matchesDiffExcludeGlob(posix, pattern)) return "default";
+  }
+  for (const pattern of excludeGlobs) {
+    if (matchesDiffExcludeGlob(posix, pattern)) return "configured";
+  }
+  return null;
+}
+
+/**
+ * Extract a diff file-block's resulting path. Prefers the `+++ b/<path>`
+ * line (present for every non-deletion block), falls back to `--- a/<path>`
+ * (deletions), then to the `diff --git a/X b/Y` header's second token. This
+ * is a best-effort extraction for FILTERING purposes only (unlike a
+ * content-fidelity transform, a path this misses just fails open to
+ * "inlined" — never mis-drops a file), so it does not attempt full
+ * git-quoted-path decoding (rare: a path containing a quote/control
+ * byte/non-ASCII byte under core.quotePath) — see
+ * `scripts/github/write-gate-context.mjs`'s `decodeGitDiffPathToken` for
+ * that fuller decode if this ever needs it.
+ * @param {string[]} blockLines
+ * @returns {string|null}
+ */
+function extractDiffBlockPath(blockLines) {
+  for (const line of blockLines) {
+    if (line.startsWith("+++ ") && !line.includes("/dev/null")) {
+      return line.slice(4).trim().replace(/^[abiwco]\//, "");
+    }
+  }
+  for (const line of blockLines) {
+    if (line.startsWith("--- ") && !line.includes("/dev/null")) {
+      return line.slice(4).trim().replace(/^[abiwco]\//, "");
+    }
+  }
+  const header = blockLines[0] ?? "";
+  const m = /^diff --git \S+ (\S+)$/.exec(header);
+  return m ? m[1].replace(/^[abiwco]\//, "") : null;
+}
+
+/**
+ * Filter a unified diff (`git diff` output) down to the files that should be
+ * INLINED into a reviewer prompt's shared per-head block (issue #1853):
+ * lockfiles, generated/vendored trees, and any caller-configured
+ * `excludeGlobs` are dropped whole-file (header + all hunks), every other
+ * file's block passes through byte-for-byte unchanged. Excluding a file here
+ * only affects what this function returns — it never touches the diff on
+ * disk or in the reviewed worktree, so an excluded file stays readable on
+ * demand.
+ *
+ * Pure and offline: string in, string out, no I/O — the caller (currently
+ * `write-gate-context.mjs`, before rendering the invariant prefix) supplies
+ * already-captured diff text.
+ *
+ * @param {string} diffText — `git diff` output (or `""`/absent).
+ * @param {{ excludeGlobs?: string[] }} [opts] — additional exclude globs,
+ *   layered on top of {@link DEFAULT_DIFF_EXCLUDE_GLOBS} (never replacing it).
+ * @returns {{ filteredDiff: string, excludedFiles: Array<{path: string, reason: "default"|"configured"}>, includedFiles: string[] }}
+ */
+export function filterDiffForInline(diffText, { excludeGlobs = [] } = {}) {
+  if (typeof diffText !== "string" || diffText.length === 0) {
+    return { filteredDiff: typeof diffText === "string" ? diffText : "", excludedFiles: [], includedFiles: [] };
+  }
+  const lines = diffText.split("\n");
+  const blockStarts = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith("diff --git ")) blockStarts.push(i);
+  }
+  // No recognizable `diff --git` file boundary — not a shape this filter
+  // understands; pass through unfiltered rather than guess.
+  if (blockStarts.length === 0) {
+    return { filteredDiff: diffText, excludedFiles: [], includedFiles: [] };
+  }
+  const keptChunks = [];
+  const excludedFiles = [];
+  const includedFiles = [];
+  if (blockStarts[0] > 0) keptChunks.push(lines.slice(0, blockStarts[0]).join("\n"));
+  for (let b = 0; b < blockStarts.length; b++) {
+    const start = blockStarts[b];
+    const end = b + 1 < blockStarts.length ? blockStarts[b + 1] : lines.length;
+    const blockLines = lines.slice(start, end);
+    const relPath = extractDiffBlockPath(blockLines);
+    const reason = relPath ? classifyDiffFileExclusion(relPath, { excludeGlobs }) : null;
+    if (reason) {
+      excludedFiles.push({ path: relPath, reason });
+    } else {
+      if (relPath) includedFiles.push(relPath);
+      keptChunks.push(blockLines.join("\n"));
+    }
+  }
+  return { filteredDiff: keptChunks.join("\n"), excludedFiles, includedFiles };
+}

package/src/loop/reviewer-loop-state.mjs

@@ -2,6 +2,7 @@
  * Deterministic state machine and bounded planning/merge contracts for reviewer-side PR loops.
  */
 import { SUBMITTED_REVIEW_STATES } from "../github/copilot-helpers.mjs";
+import { trimmedOrNull } from "./normalize.mjs";
 
 export const REVIEWER_STATE = Object.freeze({
   WAITING_FOR_REVIEW_REQUEST: "waiting_for_review_request",
@@ -117,10 +118,6 @@ const SUPPORTED_REVIEW_ANGLES = Object.freeze([
 const DEFAULT_REVIEW_MAX_PARALLEL = 3;
 const HARD_REVIEW_MAX_PARALLEL = 4;
 
-function normalizeSha(value) {
-  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
-}
-
 function normalizePositiveInt(value) {
   return typeof value === "number" && Number.isFinite(value) && value > 0
     ? Math.floor(value)
@@ -167,7 +164,7 @@ export function normalizeReviewerSnapshot(raw) {
     prDraft: Boolean(raw.prDraft),
     prMerged: Boolean(raw.prMerged),
     prClosed: Boolean(raw.prClosed),
-    prHeadSha: prExists ? normalizeSha(raw.prHeadSha) : null,
+    prHeadSha: prExists ? trimmedOrNull(raw.prHeadSha) : null,
 
     reviewerScope,
     reviewerLogin: reviewerScope === "single_reviewer" ? reviewerLogin : null,
@@ -180,10 +177,8 @@ export function normalizeReviewerSnapshot(raw) {
 
     draftReviewPosted: Boolean(raw.draftReviewPosted),
     draftReviewId: normalizePositiveInt(raw.draftReviewId),
-    draftReviewUrl: typeof raw.draftReviewUrl === "string" && raw.draftReviewUrl.trim().length > 0
-      ? raw.draftReviewUrl.trim()
-      : null,
-    draftReviewCommitSha: normalizeSha(raw.draftReviewCommitSha),
+    draftReviewUrl: trimmedOrNull(raw.draftReviewUrl),
+    draftReviewCommitSha: trimmedOrNull(raw.draftReviewCommitSha),
     draftReviewNotificationStatus: normalizeStatus(
       raw.draftReviewNotificationStatus,
       VALID_DRAFT_NOTIFICATION_STATUSES,
@@ -191,7 +186,7 @@ export function normalizeReviewerSnapshot(raw) {
     ),
 
     submittedReviewPresent: Boolean(raw.submittedReviewPresent),
-    submittedReviewCommitSha: normalizeSha(raw.submittedReviewCommitSha),
+    submittedReviewCommitSha: trimmedOrNull(raw.submittedReviewCommitSha),
     submittedReviewState: normalizeSubmittedReviewState(raw.submittedReviewState),
     reviewSubmissionStatus: normalizeStatus(raw.reviewSubmissionStatus, VALID_SUBMISSION_STATUSES, "none"),
   };
@@ -343,7 +338,7 @@ function findingDedupKey(finding) {
  * @returns {{headSha:string|null, verdict:string, inlineComments:object[], summaryFindings:object[], totalFindings:number, runsMerged:number}}
  */
 export function mergeReviewerResults(input = {}) {
-  const headSha = normalizeSha(input.headSha);
+  const headSha = trimmedOrNull(input.headSha);
   const runResults = Array.isArray(input.runResults) ? input.runResults : [];
 
   const deduped = [];
@@ -388,7 +383,7 @@ export function mergeReviewerResults(input = {}) {
 }
 
 export function buildDraftReviewPayload(mergedResult = {}) {
-  const headSha = normalizeSha(mergedResult.headSha);
+  const headSha = trimmedOrNull(mergedResult.headSha);
   const verdict = normalizeDraftVerdict(mergedResult.verdict);
   const inlineComments = Array.isArray(mergedResult.inlineComments) ? mergedResult.inlineComments : [];
   const summaryFindings = Array.isArray(mergedResult.summaryFindings) ? mergedResult.summaryFindings : [];
@@ -396,7 +391,7 @@ export function buildDraftReviewPayload(mergedResult = {}) {
   const comments = inlineComments
     .filter((finding) => finding && typeof finding === "object")
     .map((finding) => ({
-      path: typeof finding.path === "string" && finding.path.trim().length > 0 ? finding.path.trim() : null,
+      path: trimmedOrNull(finding.path),
       line: typeof finding.line === "number" && finding.line > 0 ? Math.floor(finding.line) : null,
       body: typeof finding.message === "string" ? finding.message.trim() : "",
       side: "RIGHT",