@dev-loops/core 1.0.2 → 1.0.4-pre.0

package/src/loop/finding-cluster.mjs

@@ -0,0 +1,296 @@
+/**
+ * finding-cluster.mjs — deterministic fan-in finding clustering for the
+ * gate-review sub-loop. Collapses duplicate findings (the SAME root cause
+ * reported by more than one reviewer/angle) into one cluster so the judge's
+ * relevance disposition and the fixer's act list both reason about root
+ * causes, not raw finding count.
+ *
+ * Pure and offline: no file reads, no network, no state held across calls.
+ * Every function deep-clones before enriching and never mutates a caller's
+ * array/objects.
+ */
+
+import { normalizeSeverity, resolveFindingFile } from "./gate-fanin.mjs";
+
+// NUL separates the three key components so a value inside one component
+// (e.g. a recommendation that happens to contain a colon or digits matching
+// another component) can never be misread as spanning a boundary.
+const ROOT_CAUSE_KEY_SEPARATOR = "\u0000";
+
+/** @param {unknown} value @returns {boolean} */
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * The canonical root-cause key for a finding: `(reviewed head, primary
+ * location "file:line", normalized remediation target)`. A finding missing
+ * ANY of the three components is UNKEYABLE and returns null — it is never
+ * grouped with another finding, keyable or not.
+ *
+ * @param {{file?: unknown, files?: unknown, line?: unknown, recommendation?: unknown}} finding
+ * @param {{headSha?: unknown}} [options] — the round's reviewed head; a
+ *   finding never carries its own head, so this is always caller-supplied.
+ * @returns {string|null}
+ */
+export function computeRootCauseKey(finding, { headSha } = {}) {
+  if (!finding || typeof finding !== "object") return null;
+  if (!isNonEmptyString(headSha)) return null;
+  const file = resolveFindingFile(finding);
+  if (!isNonEmptyString(file)) return null;
+  const line = finding.line;
+  if (!Number.isInteger(line) || line < 1) return null;
+  const recommendation = finding.recommendation;
+  if (!isNonEmptyString(recommendation)) return null;
+
+  const normalizedRecommendation = recommendation.trim().toLowerCase().replace(/\s+/g, " ");
+  return [headSha.trim(), `${file}:${line}`, normalizedRecommendation].join(ROOT_CAUSE_KEY_SEPARATOR);
+}
+
+/**
+ * Group findings by EXACT root-cause key match. Every UNKEYABLE finding
+ * (see {@link computeRootCauseKey}) is its own singleton cluster, never
+ * grouped with another unkeyable finding. Deterministic: clusters are
+ * ordered by `representativeIndex` ascending (first appearance), and a
+ * cluster's `memberIndices` are ascending.
+ *
+ * FAIL-OPEN: a non-array `findings`, a missing/empty/non-string `headSha`,
+ * or any internal error returns `{ ok: false, reason, clusters }` where
+ * `clusters` is one singleton (`keyable: false`) per ORIGINAL finding in
+ * input order — so a caller passes every original finding through to the
+ * judge unchanged. Never throws.
+ *
+ * @param {unknown} findings
+ * @param {{headSha?: unknown}} [options]
+ * @returns {{ ok: true, clusters: Array<{key: string|null, keyable: boolean, memberIndices: number[], representativeIndex: number}> }
+ *   | { ok: false, reason: string, clusters: Array<{key: null, keyable: false, memberIndices: number[], representativeIndex: number}> }}
+ */
+export function clusterFindings(findings, options = {}) {
+  try {
+    if (!Array.isArray(findings)) {
+      throw new Error("clusterFindings requires findings to be an array");
+    }
+    if (!isNonEmptyString(options?.headSha)) {
+      throw new Error("clusterFindings requires a non-empty options.headSha");
+    }
+    const headSha = options.headSha;
+    // A Map preserves insertion order, and every finding is visited index
+    // ascending below, so the FIRST index to create a cluster entry is
+    // always that cluster's smallest (representative) member — clusters is
+    // therefore already representativeIndex-ascending with no extra sort.
+    const byKey = new Map();
+    const clusters = [];
+    findings.forEach((finding, index) => {
+      const key = computeRootCauseKey(finding, { headSha });
+      if (key === null) {
+        clusters.push({ key: null, keyable: false, memberIndices: [index], representativeIndex: index });
+        return;
+      }
+      let cluster = byKey.get(key);
+      if (!cluster) {
+        cluster = { key, keyable: true, memberIndices: [], representativeIndex: index };
+        byKey.set(key, cluster);
+        clusters.push(cluster);
+      }
+      cluster.memberIndices.push(index);
+    });
+    return { ok: true, clusters };
+  } catch (err) {
+    const list = Array.isArray(findings) ? findings : [];
+    return {
+      ok: false,
+      reason: err instanceof Error ? err.message : String(err),
+      clusters: list.map((_finding, index) => ({ key: null, keyable: false, memberIndices: [index], representativeIndex: index })),
+    };
+  }
+}
+
+/**
+ * Reconstruct the clusters array from findings a producer already stamped
+ * with `clusterId` — the LOSSLESS identity consolidate-fanin.mjs computes
+ * (via {@link clusterFindings}) on pre-truncation finding text and stamps
+ * onto each ledger finding as `finding.clusterId = cluster.representativeIndex`.
+ * A consumer reading the ledger back (e.g. judge-pass.mjs) must group by this
+ * stamp rather than re-running {@link clusterFindings} on the ledger's own
+ * `recommendation`/`file` text, which the ledger pipeline TRUNCATES after
+ * clustering — re-deriving from truncated text can merge findings that only
+ * share a long truncated prefix, silently discarding the lossless grouping.
+ *
+ * Every finding must carry an integer `clusterId` (fails closed otherwise —
+ * a caller unsure every finding is stamped should fall back to
+ * {@link clusterFindings} instead of calling this). Deterministic: clusters
+ * are ordered by `representativeIndex` ascending, and each cluster's
+ * `memberIndices` are ascending (findings are visited index-ascending).
+ *
+ * @param {Array<{clusterId?: unknown}>} findings
+ * @returns {Array<{key: null, keyable: true, memberIndices: number[], representativeIndex: number}>}
+ */
+export function clustersFromStampedIds(findings) {
+  if (!Array.isArray(findings)) {
+    throw new TypeError("clustersFromStampedIds requires findings to be an array");
+  }
+  const byClusterId = new Map();
+  findings.forEach((finding, index) => {
+    const clusterId = finding?.clusterId;
+    if (!Number.isInteger(clusterId)) {
+      throw new TypeError(`clustersFromStampedIds requires every finding to carry an integer clusterId (index ${index} does not)`);
+    }
+    let cluster = byClusterId.get(clusterId);
+    if (!cluster) {
+      cluster = { key: null, keyable: true, memberIndices: [], representativeIndex: clusterId };
+      byClusterId.set(clusterId, cluster);
+    }
+    cluster.memberIndices.push(index);
+  });
+  return [...byClusterId.values()].sort((a, b) => a.representativeIndex - b.representativeIndex);
+}
+
+/**
+ * Project every multi-member cluster's REPRESENTATIVE judge disposition
+ * (`judgeDisposition`/`judgeRationale`/`judgeCriterion`/`followUpDraft`) onto
+ * every member of that cluster — one judge decision per root cause, applied
+ * to every finding reporting it. Singleton clusters are unchanged. Pure:
+ * deep-clones before enriching, never mutates `enrichedFindings`.
+ *
+ * Fails closed (throws) when a cluster is malformed or its
+ * `memberIndices`/`representativeIndex` reference an out-of-range position.
+ *
+ * @param {Array<object>} enrichedFindings
+ * @param {Array<{memberIndices: number[], representativeIndex: number}>} clusters
+ * @returns {Array<object>} a new, deep-cloned array.
+ */
+export function projectClusterDisposition(enrichedFindings, clusters) {
+  if (!Array.isArray(enrichedFindings)) {
+    throw new TypeError("projectClusterDisposition requires enrichedFindings to be an array");
+  }
+  if (!Array.isArray(clusters)) {
+    throw new TypeError("projectClusterDisposition requires clusters to be an array");
+  }
+  const result = enrichedFindings.map((finding) => structuredClone(finding));
+  for (const cluster of clusters) {
+    if (!cluster || !Array.isArray(cluster.memberIndices) || !Number.isInteger(cluster.representativeIndex)) {
+      throw new TypeError("projectClusterDisposition requires every cluster to carry memberIndices[] and a representativeIndex");
+    }
+    if (cluster.representativeIndex < 0 || cluster.representativeIndex >= result.length) {
+      throw new RangeError(`projectClusterDisposition: cluster representativeIndex ${cluster.representativeIndex} is out of range (${result.length} findings)`);
+    }
+    for (const memberIndex of cluster.memberIndices) {
+      if (!Number.isInteger(memberIndex) || memberIndex < 0 || memberIndex >= result.length) {
+        throw new RangeError(`projectClusterDisposition: cluster memberIndices references out-of-range index ${memberIndex} (${result.length} findings)`);
+      }
+    }
+    if (cluster.memberIndices.length === 0) {
+      throw new RangeError("projectClusterDisposition: a cluster must have at least one member (memberIndices is empty)");
+    }
+    if (!cluster.memberIndices.includes(cluster.representativeIndex)) {
+      throw new RangeError(
+        `projectClusterDisposition: cluster representativeIndex ${cluster.representativeIndex} is not one of its own memberIndices [${cluster.memberIndices.join(", ")}]`
+      );
+    }
+    if (cluster.memberIndices.length <= 1) continue; // singleton: shape validated above, nothing to project.
+    const representative = result[cluster.representativeIndex];
+    for (const memberIndex of cluster.memberIndices) {
+      const target = result[memberIndex];
+      target.judgeDisposition = representative.judgeDisposition;
+      target.judgeRationale = representative.judgeRationale;
+      if (representative.judgeCriterion !== undefined) target.judgeCriterion = representative.judgeCriterion;
+      else delete target.judgeCriterion;
+      if (representative.followUpDraft !== undefined) target.followUpDraft = representative.followUpDraft;
+      else delete target.followUpDraft;
+    }
+  }
+  return result;
+}
+
+/**
+ * Reduce an ACT list to at most one finding per acted cluster — the fixer's
+ * one-remediation-per-root-cause input. `allFindings` is the SAME array
+ * `clusters` was computed against; each act finding is matched back to its
+ * original position in it by reference, then to that position's cluster.
+ *
+ * A cluster's `representativeIndex` is by construction its smallest member
+ * index (see {@link clusterFindings}), so — given `actFindings` preserves
+ * the round's original relative order, which every producer in this
+ * pipeline does — the first member of a cluster encountered here is always
+ * either the representative itself, or, when the representative was not
+ * itself act-disposed, the earliest-index act member of that cluster: the
+ * exact preference rule this function implements, with no extra bookkeeping.
+ *
+ * A finding whose cluster cannot be resolved (absent from `allFindings`, or
+ * no cluster covers its position) passes through unchanged — fail-open,
+ * never silently dropped.
+ *
+ * @param {Array<object>} actFindings
+ * @param {Array<{memberIndices: number[], representativeIndex: number}>} clusters
+ * @param {Array<object>} allFindings
+ * @returns {Array<object>}
+ */
+export function dedupeActListByCluster(actFindings, clusters, allFindings) {
+  if (!Array.isArray(actFindings)) {
+    throw new TypeError("dedupeActListByCluster requires actFindings to be an array");
+  }
+  const clusterList = Array.isArray(clusters) ? clusters : [];
+  const findingsList = Array.isArray(allFindings) ? allFindings : [];
+
+  const representativeIndexByPosition = new Map();
+  for (const cluster of clusterList) {
+    if (!cluster || !Array.isArray(cluster.memberIndices) || !Number.isInteger(cluster.representativeIndex)) continue;
+    for (const memberIndex of cluster.memberIndices) {
+      representativeIndexByPosition.set(memberIndex, cluster.representativeIndex);
+    }
+  }
+
+  const seenClusters = new Set();
+  const kept = [];
+  for (const finding of actFindings) {
+    const position = findingsList.indexOf(finding);
+    const representativeIndex = position === -1 ? undefined : representativeIndexByPosition.get(position);
+    if (representativeIndex === undefined) {
+      kept.push(finding); // Fail-open: unresolvable membership always passes through.
+      continue;
+    }
+    if (seenClusters.has(representativeIndex)) continue;
+    seenClusters.add(representativeIndex);
+    kept.push(finding);
+  }
+  return kept;
+}
+
+/**
+ * A "clean" verdict means no finding at a BLOCKING severity remains open. It is
+ * invalid only when a finding at a blocking severity was acted on — that is
+ * unresolved blocking work, so the round cannot be clean. Acting on a
+ * NON-BLOCKING finding (a medium in the fix window, a low the fixer triages) is
+ * expected under a clean verdict per `GATE-EXEC-BLOCKING-ONLY-FIX`: the fix
+ * cycle covers non-blocking findings even though they never block clean, so a
+ * clean verdict routinely carries non-blocking act findings.
+ *
+ * Throws a clear Error on `overallVerdict === "clean"` with any act finding at a
+ * blocking severity; returns `overallVerdict` unchanged otherwise.
+ *
+ * @param {unknown} overallVerdict
+ * @param {Array<{severity?: unknown}>} actFindings — the round's act-disposed findings.
+ * @param {string[]} [blockingSeverities] — the gate's blocking severities (default ["high"]).
+ * @returns {unknown} `overallVerdict`, unchanged.
+ */
+export function assertCleanImpliesNoBlockingAct(overallVerdict, actFindings, blockingSeverities) {
+  if (!Array.isArray(actFindings)) {
+    throw new TypeError("assertCleanImpliesNoBlockingAct requires actFindings to be an array");
+  }
+  if (overallVerdict !== "clean") return overallVerdict;
+  const blocking = new Set(
+    (Array.isArray(blockingSeverities) && blockingSeverities.length > 0 ? blockingSeverities : ["high"]).map((s) =>
+      normalizeSeverity(s),
+    ),
+  );
+  const offending = actFindings.filter((f) => blocking.has(normalizeSeverity(f?.severity)));
+  if (offending.length > 0) {
+    const severities = [...new Set(offending.map((f) => normalizeSeverity(f?.severity)))].join(", ");
+    throw new Error(
+      `clean verdict is invalid with ${offending.length} acted finding(s) at a blocking severity (${severities}): ` +
+        `a blocking-severity finding acted on this round cannot be clean. Non-blocking act findings are allowed under ` +
+        `a clean verdict (GATE-EXEC-BLOCKING-ONLY-FIX).`,
+    );
+  }
+  return overallVerdict;
+}

package/src/loop/fixer-disposition.mjs

@@ -0,0 +1,200 @@
+// GATE-EXEC-FIXER-DISPOSITION-BOUNDARY (skills/docs/gate-review-sub-loop-contract.md):
+// fail closed when a fixer push leaves the review threads it claims to have
+// tackled incomplete (missing evidence, uncontained commit, unreplied, or
+// unresolved). This module is a PURE evaluator — every GitHub/git fact
+// (live thread state, commit containment) is injected as data, never fetched
+// here, so the same decision is shared verbatim across every harness.
+
+/** Disposition values a handoff entry may carry. Only "tackled" entries are
+ * auto-disposed by evaluateFixerDisposition; every other value keeps its
+ * existing judgment path untouched (see the boundary rule's scope note). */
+export const FIXER_DISPOSITION_KIND = Object.freeze({
+  TACKLED: "tackled",
+  DEFERRED: "deferred",
+  REJECTED: "rejected",
+});
+
+export const FIXER_DISPOSITION_FAILED_STEP = Object.freeze({
+  MISSING_FROM_HANDOFF: "missing_from_handoff",
+  COMMIT_NOT_CONTAINED: "commit_not_contained",
+  REPLY_MISSING: "reply_missing",
+  NOT_RESOLVED: "not_resolved",
+});
+
+// The only legal next action while disposition is incomplete. Kept as a plain
+// literal (not imported from pr-gate-coordination.mjs) so this module stays a
+// dependency-free leaf; pr-gate-coordination.mjs's own PR_CHECKPOINT_ACTION
+// token for this action is asserted (by test) to equal this same string.
+export const COMPLETE_FIXER_DISPOSITION_ACTION = "complete_fixer_disposition";
+
+// Broader than pr-gate-coordination's postDraftForbidden: the failure this
+// boundary closes is the NEXT review/gate round opening over a dirty review
+// surface, so every review-(re)request and gate-dispatch token is forbidden
+// too, not just the draft/merge transition tokens. Literal tokens (not
+// imported) for the same dependency-free-leaf reason as above.
+export const FIXER_DISPOSITION_FORBIDDEN_ACTIONS = Object.freeze([
+  "run_draft_gate",
+  "reconcile_draft_gate",
+  "mark_ready_for_review",
+  "request_copilot_review",
+  "rerequest_copilot_review",
+  "run_pre_approval_gate",
+  "await_final_human_approval",
+  "declare_merge_ready",
+]);
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Validate + normalize a raw fixer-disposition handoff. Throws on any
+ * structural gap the evaluator must never silently tolerate: a missing
+ * headSha, a non-array dispositions field, a missing
+ * threadId/fixingCommitSha/disposition on any entry, an unrecognized
+ * disposition value, or a duplicate threadId/fingerprint across entries.
+ *
+ * @param {object} raw
+ * @returns {{ headSha: string, dispositions: Array<{ threadId: string, fingerprint: string|null, fixingCommitSha: string, disposition: string, validation: string|null }> }}
+ */
+export function normalizeFixerDispositionHandoff(raw) {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("Fixer disposition handoff must be an object");
+  }
+  if (!isNonEmptyString(raw.headSha)) {
+    throw new Error("Fixer disposition handoff is missing headSha");
+  }
+  if (raw.dispositions !== undefined && !Array.isArray(raw.dispositions)) {
+    throw new Error("Fixer disposition handoff dispositions must be an array");
+  }
+  const rawDispositions = raw.dispositions ?? [];
+  const seenThreadIds = new Set();
+  const seenFingerprints = new Set();
+  const dispositions = rawDispositions.map((entry, index) => {
+    if (!entry || typeof entry !== "object") {
+      throw new Error(`Fixer disposition handoff entry ${index} must be an object`);
+    }
+    if (!isNonEmptyString(entry.threadId)) {
+      throw new Error(`Fixer disposition handoff entry ${index} is missing threadId`);
+    }
+    const threadId = entry.threadId.trim();
+    if (seenThreadIds.has(threadId)) {
+      throw new Error(`Fixer disposition handoff has a duplicate threadId: ${threadId}`);
+    }
+    seenThreadIds.add(threadId);
+    if (!isNonEmptyString(entry.fixingCommitSha)) {
+      throw new Error(`Fixer disposition handoff entry for thread ${threadId} is missing fixingCommitSha`);
+    }
+    if (!isNonEmptyString(entry.disposition)) {
+      throw new Error(`Fixer disposition handoff entry for thread ${threadId} is missing disposition`);
+    }
+    const fingerprint = isNonEmptyString(entry.fingerprint) ? entry.fingerprint.trim() : null;
+    if (fingerprint !== null) {
+      if (seenFingerprints.has(fingerprint)) {
+        throw new Error(`Fixer disposition handoff has a duplicate fingerprint: ${fingerprint}`);
+      }
+      seenFingerprints.add(fingerprint);
+    }
+    const disposition = entry.disposition.trim().toLowerCase();
+    if (!Object.values(FIXER_DISPOSITION_KIND).includes(disposition)) {
+      throw new Error(`Fixer disposition handoff entry for thread ${threadId} has an unrecognized disposition: ${disposition}`);
+    }
+    return {
+      threadId,
+      fingerprint,
+      fixingCommitSha: entry.fixingCommitSha.trim(),
+      disposition,
+      validation: isNonEmptyString(entry.validation) ? entry.validation.trim() : null,
+    };
+  });
+  return {
+    headSha: raw.headSha.trim(),
+    dispositions,
+  };
+}
+
+function formatIncompleteReason(incomplete) {
+  const parts = incomplete.map((entry) => (
+    `thread ${entry.threadId} (expected commit ${entry.expectedCommit ?? "unknown"}, failed step: ${entry.failedStep})`
+  ));
+  return `Fixer disposition is incomplete for ${incomplete.length} tackled thread(s): ${parts.join("; ")}. `
+    + `The only legal next action is ${COMPLETE_FIXER_DISPOSITION_ACTION}.`;
+}
+
+/**
+ * PURE evaluator: given a normalized handoff, the live thread state, and an
+ * injected commit-containment fact table, decide whether every thread the
+ * fixer claims to have tackled is fully disposed (commit contained, replied
+ * with that commit's evidence, and resolved). No I/O — every fact the
+ * decision needs is a plain argument, which is what keeps this seam shared
+ * verbatim across harnesses.
+ *
+ * @param {object} params
+ * @param {{ headSha: string, dispositions: Array<object> }} params.handoff - raw or already-normalized; ALWAYS re-validated via normalizeFixerDispositionHandoff (idempotent on already-normalized input), so a malformed array-bearing handoff can never bypass schema+enum validation just by already carrying an array
+ * @param {Array<{ threadId: string, isResolved: boolean, replyBodies?: string[], claimedTackled?: boolean }>} [params.liveThreads]
+ * @param {Record<string, boolean>} [params.containment] - fixingCommitSha -> true when the observed PR head contains it
+ * @returns {{ ok: boolean, incomplete: Array<{ threadId: string, expectedCommit: string|null, failedStep: string }>, forbiddenActions: string[], nextAction: string|null, reason: string|null }}
+ */
+export function evaluateFixerDisposition({ handoff, liveThreads = [], containment = {} } = {}) {
+  const normalizedHandoff = normalizeFixerDispositionHandoff(handoff ?? {});
+  const handoffByThreadId = new Map(normalizedHandoff.dispositions.map((entry) => [entry.threadId, entry]));
+  const liveByThreadId = new Map(
+    (Array.isArray(liveThreads) ? liveThreads : [])
+      .filter((entry) => entry && typeof entry.threadId === "string")
+      .map((entry) => [entry.threadId, entry]),
+  );
+
+  // The must-check set: every handoff entry explicitly marked "tackled", plus
+  // any live thread independently flagged claimedTackled (e.g. a fixer's own
+  // claim the CLI cross-referenced against live GitHub state) that has no
+  // handoff counterpart at all — that gap is exactly missing_from_handoff.
+  const tackledThreadIds = new Set();
+  for (const entry of normalizedHandoff.dispositions) {
+    if (entry.disposition === FIXER_DISPOSITION_KIND.TACKLED) {
+      tackledThreadIds.add(entry.threadId);
+    }
+  }
+  for (const liveThread of liveByThreadId.values()) {
+    if (liveThread.claimedTackled === true) {
+      tackledThreadIds.add(liveThread.threadId);
+    }
+  }
+
+  const incomplete = [];
+  for (const threadId of tackledThreadIds) {
+    const handoffEntry = handoffByThreadId.get(threadId) ?? null;
+    if (!handoffEntry) {
+      incomplete.push({ threadId, expectedCommit: null, failedStep: FIXER_DISPOSITION_FAILED_STEP.MISSING_FROM_HANDOFF });
+      continue;
+    }
+    const expectedCommit = handoffEntry.fixingCommitSha;
+    // Non-goal enforcement: a SHA alone is never evidence. Only an injected
+    // containment[sha] === true (the observed PR head provably contains the
+    // commit) can authorize the reply/resolve steps below.
+    if (containment?.[expectedCommit] !== true) {
+      incomplete.push({ threadId, expectedCommit, failedStep: FIXER_DISPOSITION_FAILED_STEP.COMMIT_NOT_CONTAINED });
+      continue;
+    }
+    const liveThread = liveByThreadId.get(threadId) ?? null;
+    const replyBodies = Array.isArray(liveThread?.replyBodies) ? liveThread.replyBodies : [];
+    const hasEvidencedReply = replyBodies.some((body) => (
+      typeof body === "string" && body.toLowerCase().includes(expectedCommit.toLowerCase())
+    ));
+    if (!hasEvidencedReply) {
+      incomplete.push({ threadId, expectedCommit, failedStep: FIXER_DISPOSITION_FAILED_STEP.REPLY_MISSING });
+      continue;
+    }
+    if (liveThread?.isResolved !== true) {
+      incomplete.push({ threadId, expectedCommit, failedStep: FIXER_DISPOSITION_FAILED_STEP.NOT_RESOLVED });
+    }
+  }
+
+  const ok = incomplete.length === 0;
+  return {
+    ok,
+    incomplete,
+    forbiddenActions: ok ? [] : [...FIXER_DISPOSITION_FORBIDDEN_ACTIONS],
+    nextAction: ok ? null : COMPLETE_FIXER_DISPOSITION_ACTION,
+    reason: ok ? null : formatIncompleteReason(incomplete),
+  };
+}

package/src/loop/gate-carry-forward.mjs

@@ -177,10 +177,19 @@ export function angleReviewSurface(angle, { alwaysRerun } = {}) {
  * @param {AngleReviewSurface} [input.angleSurface] — the angle's declared surface;
  *   derived from {@link angleReviewSurface} when omitted.
  * @param {string[]} input.changedFiles — repo-relative paths changed between head
- *   A and head B (the delta, NOT the full PR diff against base).
+ *   A and head B (the delta, NOT the full PR diff against base). For a base-move
+ *   re-gate the caller passes the MAIN-RELATIVE incremental delta: files changed
+ *   since head A whose head-B content is genuinely PR-own (differs from
+ *   origin/main), NOT the raw two-dot A..B delta — so an integrate-only base-move
+ *   that only replays already-merged main commits contributes an empty delta.
  * @param {string} input.prevVerdict — the angle's verdict at head A. "clean" and
  *   "findings_present" are carry-forward-eligible; anything else (e.g.
  *   "blocked", missing) is not.
+ * @param {boolean} [input.deltaComplete=false] — the caller PROVES `changedFiles`
+ *   is the complete, successfully-computed delta (git succeeded and, for a
+ *   base-move, the main-relative reduction ran). Only then does an EMPTY delta
+ *   mean "nothing PR-own changed" and carry forward; without the proof an empty
+ *   delta is indistinguishable from an unavailable one and still fails closed.
  * @returns {{ carryForward: boolean, reason: string }}
  */
 
@@ -207,7 +216,7 @@ export function isDevLoopConfigSourcePath(filePath) {
   return DEV_LOOP_CONFIG_SOURCE_RE.test(filePath.trim().replace(/\\/g, "/"));
 }
 
-export function resolveAngleCarryForward({ angle, angleSurface, changedFiles, prevVerdict }) {
+export function resolveAngleCarryForward({ angle, angleSurface, changedFiles, prevVerdict, deltaComplete = false }) {
   if (!CARRY_FORWARD_ELIGIBLE_VERDICTS.has(prevVerdict)) {
     return {
       carryForward: false,
@@ -221,7 +230,16 @@ export function resolveAngleCarryForward({ angle, angleSurface, changedFiles, pr
   if (surface.kind === "unknown") {
     return { carryForward: false, reason: "angle has no declared review surface (fail-closed)" };
   }
-  if (!Array.isArray(changedFiles) || changedFiles.length === 0) {
+  if (!Array.isArray(changedFiles)) {
+    return { carryForward: false, reason: "delta is unavailable (fail-closed)" };
+  }
+  // A PROVEN-complete empty delta (deltaComplete) means the main-relative
+  // reduction found NO PR-own change since the prior reviewed head — an
+  // integrate-only base-move that only replays already-merged main commits.
+  // That carries forward: the zero-file loop below proves the surface untouched.
+  // Without that proof an empty delta is indistinguishable from an unavailable
+  // one, so it still fails closed.
+  if (changedFiles.length === 0 && !deltaComplete) {
     return { carryForward: false, reason: "delta is empty or unavailable (fail-closed)" };
   }
   for (const file of changedFiles) {
@@ -287,12 +305,22 @@ const COPILOT_REVIEW_SURFACE_KINDS = new Set(["code", "test", "config", "ci"]);
  * re-runs, since classifyFile is path-based). Any code/test/config/CI file, an unclassifiable
  * file, or an empty/unavailable delta -> re-run (fresh blocking round required).
  *
+ * `deltaComplete` mirrors {@link resolveAngleCarryForward}: when the caller PROVES
+ * `changedFiles` is the complete main-relative reduction, an EMPTY delta means an
+ * integrate-only base-move touched no Copilot surface and the convergence carries
+ * forward. Without the proof an empty delta still fails closed.
+ *
  * @param {object} input
  * @param {string[]} input.changedFiles — delta since the converged head
+ * @param {boolean} [input.deltaComplete=false] — proof the empty case is a real
+ *   "nothing PR-own changed", not an unavailable delta
  * @returns {{ carryForward: boolean, reason: string }}
  */
-export function resolveConvergenceCarryForward({ changedFiles }) {
-  if (!Array.isArray(changedFiles) || changedFiles.length === 0) {
+export function resolveConvergenceCarryForward({ changedFiles, deltaComplete = false }) {
+  if (!Array.isArray(changedFiles)) {
+    return { carryForward: false, reason: "delta is unavailable (fail-closed)" };
+  }
+  if (changedFiles.length === 0 && !deltaComplete) {
     return { carryForward: false, reason: "delta is empty or unavailable (fail-closed)" };
   }
   for (const file of changedFiles) {
@@ -304,5 +332,10 @@ export function resolveConvergenceCarryForward({ changedFiles }) {
       return { carryForward: false, reason: `delta touches Copilot's review surface (${kind}): ${file}` };
     }
   }
-  return { carryForward: true, reason: "delta is a pure doc/prose bump, provably outside Copilot's review surface" };
+  return {
+    carryForward: true,
+    reason: changedFiles.length === 0
+      ? "no PR-own change since the converged head (integrate-only base-move), provably outside Copilot's review surface"
+      : "delta is a pure doc/prose bump, provably outside Copilot's review surface",
+  };
 }