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

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",
+  };
 }

package/src/loop/gate-fanin.mjs

@@ -828,6 +828,7 @@ export function consolidateFanin({ angleResults, blockCleanOnFindingSeverities }
           disposition: deriveDisposition(severity, { isBlocking, locatable: hasLocatableShape(f) }),
         };
         if (typeof f.file === "string" && f.file.trim().length > 0) entry.file = f.file.trim();
+        if (Array.isArray(f.files)) entry.files = f.files.filter((file) => typeof file === "string" && file.trim().length > 0).map((file) => file.trim());
         if (typeof f.line === "number" && Number.isFinite(f.line)) entry.line = f.line;
         if (typeof f.recommendation === "string" && f.recommendation.trim().length > 0) {
           entry.recommendation = f.recommendation.trim();
@@ -871,6 +872,38 @@ export function consolidateFanin({ angleResults, blockCleanOnFindingSeverities }
  */
 export const JUDGE_DISPOSITIONS = Object.freeze(["act", "defer", "reject"]);
 
+/**
+ * The `scopeDrift.verdict` vocabulary — the single shared source. The validator
+ * below consumes it directly, and a divergence-guard test asserts the judge
+ * persona surface (`agents/judge.agent.md`) documents exactly this set, so the
+ * producer and enforcer cannot silently drift apart.
+ */
+export const SCOPE_DRIFT_VERDICTS = Object.freeze(["within_scope", "drift_detected"]);
+
+/**
+ * Aliases a persona-following judge reaches for, normalized to the canonical
+ * vocabulary before validation. `none` is the intuitive no-drift spelling; it
+ * maps to `within_scope` so a semantically-correct verdict passes with no
+ * resend or hand-edit, disposition and rationale byte-intact.
+ */
+export const SCOPE_DRIFT_VERDICT_ALIASES = Object.freeze({ none: "within_scope" });
+
+/**
+ * Normalize a `scopeDrift.verdict` alias to its canonical value. Canonical and
+ * unknown values pass through untouched; validation rejects unknowns.
+ * @param {unknown} verdict
+ * @returns {unknown}
+ */
+export function normalizeScopeDriftVerdict(verdict) {
+  // Only a primitive string spelling normalizes. `hasOwnProperty.call` coerces
+  // its key argument, so without this guard a boxed `new String("none")` or an
+  // object whose `toString()` returns `"none"` would alias to `within_scope` —
+  // a fail-open contradicting the validator's non-string-fails-closed contract.
+  return typeof verdict === "string" && Object.prototype.hasOwnProperty.call(SCOPE_DRIFT_VERDICT_ALIASES, verdict)
+    ? SCOPE_DRIFT_VERDICT_ALIASES[verdict]
+    : verdict;
+}
+
 /**
  * Validate a judge verdict artifact shape (the `judge` agent's only write).
  * Pure; throws on a malformed verdict rather than enriching findings with
@@ -901,8 +934,9 @@ export function validateJudgeVerdict(verdict) {
     throw new Error("judge verdict.scopeDrift must be an object");
   }
   const sd = /** @type {Record<string, unknown>} */ (v.scopeDrift);
-  if (sd.verdict !== "within_scope" && sd.verdict !== "drift_detected") {
-    throw new Error("judge verdict.scopeDrift.verdict must be 'within_scope' or 'drift_detected'");
+  const normalizedVerdict = normalizeScopeDriftVerdict(sd.verdict);
+  if (!SCOPE_DRIFT_VERDICTS.includes(/** @type {string} */ (normalizedVerdict))) {
+    throw new Error(`judge verdict.scopeDrift.verdict must be one of: ${SCOPE_DRIFT_VERDICTS.join(", ")}`);
   }
   if (typeof sd.rationale !== "string" || sd.rationale.trim().length === 0) {
     throw new Error("judge verdict.scopeDrift.rationale must be a non-empty string");
@@ -949,7 +983,7 @@ export function validateJudgeVerdict(verdict) {
       }
     }
   }
-  return { headSha: v.headSha, scopeDrift: v.scopeDrift, dispositions: v.dispositions };
+  return { headSha: v.headSha, scopeDrift: { ...sd, verdict: normalizedVerdict }, dispositions: v.dispositions };
 }
 
 /**

package/src/loop/issue-refinement-artifact.mjs

@@ -949,14 +949,95 @@ function sectionHasBody(section) {
   return false;
 }
 
+// A top-level list marker line (any GFM/CommonMark family: `-`/`*`/`+`,
+// ordered `N.`/`N)`, optional leading blockquote `>` runs) with NO checkbox.
+// `validatePrBodySpec`-local: unlike `parseChecklistItems` (whose
+// `checked: null` state fires ONLY for the bare-dash form — see its
+// docstring), this recognizes every marker family, so a mixed AC/DoD section
+// (`- [ ] works` next to `* plain`) cannot escape detection just because the
+// plain line used a non-dash marker. No leading-space match before the
+// marker/blockquote keeps this top-level only: an indented continuation
+// (`  - detail`) is sub-content and is not matched. The negative lookahead
+// excludes a real checkbox line so `- [ ] works` is never double-counted; the
+// lookahead treats end-of-line as a checkbox terminator too (`(?:\s|$)`), so
+// an empty checkbox placeholder (`- [ ]`/`- [x]`, no trailing text) is
+// excluded rather than mis-caught as a plain bullet — `parseChecklistItems`
+// already documents empty placeholders as skipped, and this scan must not
+// contradict that.
+const TOP_LEVEL_NON_CHECKBOX_BULLET_PATTERN = /^(?:>\s*)*(?:[-*+]|\d+[.)])\s+(?!\[[ xX]\](?:\s|$))(.+?)\s*$/u;
+
+// A spaced Markdown thematic break (`* * *`, `- - -`) also matches
+// `TOP_LEVEL_NON_CHECKBOX_BULLET_PATTERN` (marker, whitespace, more marker
+// text) but is a divider, not a bullet — `parseChecklistItems` never treats
+// it as an item, so counting it here would reject a legitimate AC/DoD
+// section over a divider line. `***`/`---` (no spaces) already fail the
+// bullet pattern's `\s+` requirement, so only the spaced form needs this
+// guard. Same-marker-only via the backreference, and only `-`/`*`/`_` per
+// the CommonMark thematic-break rule (3+ of the SAME char, optional spaces,
+// nothing else) — `+` is NOT a valid thematic-break marker, so `+ + +`
+// stays correctly counted as a real (single-item) plain bullet.
+const THEMATIC_BREAK_RE = /^([-*_])(?:[ \t]*\1){2,}[ \t]*$/u;
+
+/**
+ * Scan a flattened section body for top-level non-checkbox bullet lines
+ * (`TOP_LEVEL_NON_CHECKBOX_BULLET_PATTERN`). Fence-skipped via the shared
+ * `stepFence` so a fenced fake bullet cannot spoof this check. Thematic-break
+ * divider lines (`THEMATIC_BREAK_RE`) are excluded — see its docstring.
+ */
+function scanTopLevelNonCheckboxBulletLines(text) {
+  if (typeof text !== "string" || text.length === 0) return [];
+  const found = [];
+  let fence = null;
+  for (const line of text.split(/\r?\n/u)) {
+    const step = stepFence(fence, line);
+    fence = step.fence;
+    if (step.insideFence) continue;
+    const match = TOP_LEVEL_NON_CHECKBOX_BULLET_PATTERN.exec(line);
+    if (!match || match[1].trim().length === 0) continue;
+    const strippedLine = line.replace(/^(?:>\s*)*/u, "").trim();
+    if (THEMATIC_BREAK_RE.test(strippedLine)) continue;
+    found.push(match[1].trim());
+  }
+  return found;
+}
+
+/**
+ * Scan every section the completeness block would read (ALL sections matching
+ * `patterns`, deep-flattened past `###` sub-headings via
+ * `findAllSectionsByPatterns` + `flattenSectionDeep` — the same union
+ * `extractPrBodyUncheckedChecklistItems` reads) for top-level plain bullets
+ * of ANY marker (no checkbox). Shares the section-set read with the
+ * completeness block on purpose: a plain bullet invisible to
+ * `validatePrBodySpec`'s own single-section read but visible to the
+ * completeness block (a duplicate AC/DoD heading, or a bullet nested under a
+ * `###` sub-heading) must still reject here, or the two surfaces diverge on
+ * the same checkbox-marker fail-open class this module closes for the simple
+ * single-section case. Local `scanTopLevelNonCheckboxBulletLines` scan, not
+ * `parseChecklistItems`'s `checked: null` state, so a non-dash plain bullet
+ * (`*`/`+`/ordered) is caught too — `parseChecklistItems` and the shared
+ * deterministic pre-approval completeness-block logic it backs (see
+ * acceptance-criteria-verification.md) stay untouched.
+ */
+function scanPlainBullets(sections, patterns) {
+  const matched = findAllSectionsByPatterns(sections, patterns);
+  const items = [];
+  for (let i = 0; i < sections.length; i += 1) {
+    if (!matched.includes(sections[i])) continue;
+    items.push(...scanTopLevelNonCheckboxBulletLines(flattenSectionDeep(sections, i)));
+  }
+  return items;
+}
+
 /**
  * Validate that a PR body carries every invariant required to serve as the
  * lightweight spec-of-record: Objective/why, in-scope, explicit non-goals,
- * testable Acceptance criteria (>=1 checklist item), Definition of done
- * (>=1 checklist item), Open questions/risks, and — unless issue-less mode is
+ * testable Acceptance criteria (>=1 checkbox item), Definition of done
+ * (>=1 checkbox item), Open questions/risks, and — unless issue-less mode is
  * requested — a GitHub closing-keyword issue reference. Reuses the generic
  * markdown logic so there is no parallel validator. Fails closed: every missing
- * invariant is reported under its distinct `missing_*` code. Pure; no I/O.
+ * invariant is reported under its distinct `missing_*` code (plus the two
+ * `*_not_checkboxes` codes for a plain-bullet AC/DoD section — see
+ * `scanPlainBullets`). Pure; no I/O.
  *
  * Issue-less mode (`issueLess: true`): the closing-issue linkage flips from
  * REQUIRED to FORBIDDEN (the PR is the sole artifact), failing closed under
@@ -1044,21 +1125,48 @@ export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess
     }
   }
 
+  // Checkbox markers are REQUIRED (not just any bullet): the completeness
+  // block (extractPrBodyUncheckedChecklistItems) only ever sees checkbox
+  // items, so a plain bullet here would fail-open the completeness check
+  // even though this validator accepted it. The plain-bullet scan reads the
+  // SAME section set the completeness block reads (scanPlainBullets), not
+  // just the first section, so a duplicate heading or a bullet nested under a
+  // `###` sub-heading cannot hide from this check either. The scan runs
+  // INDEPENDENTLY of parseChecklistItems (not gated on it finding items) and
+  // is checked FIRST: an AC/DoD section made entirely of non-dash plain
+  // bullets (`* plain`, `1. plain`) yields zero parsed checkbox items, so
+  // gating the scan on "items found" would misreport that case as
+  // missing_acceptance_criteria/missing_definition_of_done instead of the
+  // distinct *_not_checkboxes code.
   const acSection = findSectionByPatterns(sections, ACCEPTANCE_SECTION_PATTERNS);
-  const acItems = acSection ? extractChecklistItems(acSection.bodyLines.join("\n")) : [];
-  if (acItems.length === 0) {
+  const acParsed = acSection ? parseChecklistItems(acSection.bodyLines.join("\n")) : [];
+  const acItems = acParsed.filter((item) => item.checked !== null).map((item) => item.text);
+  const acPlainBullets = scanPlainBullets(sections, ACCEPTANCE_SECTION_PATTERNS);
+  if (acPlainBullets.length > 0) {
+    errors.push({
+      code: "acceptance_criteria_not_checkboxes",
+      message: `Acceptance criteria must use checkbox markers ('- [ ]'/'- [x]'), not plain bullets (found ${acPlainBullets.length} plain bullet(s)); plain bullets fail-open the completeness block.`,
+    });
+  } else if (acParsed.length === 0) {
     errors.push({
       code: "missing_acceptance_criteria",
-      message: "Missing testable Acceptance criteria (no checklist items found).",
+      message: "Missing testable Acceptance criteria (no checkbox items found).",
     });
   }
 
   const dodSection = findSectionByPatterns(sections, DOD_SECTION_PATTERNS);
-  const dodItems = dodSection ? extractChecklistItems(dodSection.bodyLines.join("\n")) : [];
-  if (dodItems.length === 0) {
+  const dodParsed = dodSection ? parseChecklistItems(dodSection.bodyLines.join("\n")) : [];
+  const dodItems = dodParsed.filter((item) => item.checked !== null).map((item) => item.text);
+  const dodPlainBullets = scanPlainBullets(sections, DOD_SECTION_PATTERNS);
+  if (dodPlainBullets.length > 0) {
+    errors.push({
+      code: "definition_of_done_not_checkboxes",
+      message: `Definition of done must use checkbox markers ('- [ ]'/'- [x]'), not plain bullets (found ${dodPlainBullets.length} plain bullet(s)); plain bullets fail-open the completeness block.`,
+    });
+  } else if (dodParsed.length === 0) {
     errors.push({
       code: "missing_definition_of_done",
-      message: "Missing Definition of done (no checklist items found).",
+      message: "Missing Definition of done (no checkbox items found).",
     });
   }
 

package/src/loop/merge-approval.mjs

@@ -11,13 +11,16 @@
  *
  * It reuses, never re-derives, the existing precondition set:
  * `resolveSizeBudgetHumanApprovalRequired` (size-budget-merge-gate),
- * `findBlockingTitleMarkers` (pr-title-markers), and the detect-checkpoint-evidence
+ * `findBlockingTitleMarkers` (pr-title-markers), the detect-checkpoint-evidence
  * `preMergeGateCheck` bundle (draft/pre-approval verdicts, threads, runner lock,
- * fan-out provenance). This module adds ONLY the human-approver identity, the
- * merge-class split, and the aggregate naming.
+ * fan-out provenance), and `classifyCopilotReviewBodyDisposition` (copilot-helpers,
+ * the same current-head Copilot disposition detection the loop's
+ * `copilotBodyFeedbackUnresolved` reads). This module adds ONLY the
+ * human-approver identity, the merge-class split, the Copilot-convergence
+ * precondition, and the aggregate naming.
  */
 
-import { isCopilotLogin } from "../github/copilot-helpers.mjs";
+import { isCopilotLogin, classifyCopilotReviewBodyDisposition, COPILOT_DISPOSITION, SUBMITTED_REVIEW_STATES } from "../github/copilot-helpers.mjs";
 import { findBlockingTitleMarkers } from "./pr-title-markers.mjs";
 import { resolveSizeBudgetHumanApprovalRequired } from "./size-budget-merge-gate.mjs";
 import { deriveLoopCiStatusFromRollup } from "./copilot-ci-status.mjs";
@@ -150,6 +153,103 @@ export function verifyFreshHumanApproval({ approvedBy, currentHeadSha, reviews =
   };
 }
 
+/**
+ * Copilot-convergence merge precondition. Wires the current-head Copilot
+ * body-disposition detection into the merge gate so the merge wrapper
+ * and the loop (`copilotBodyFeedbackUnresolved`) read the SAME classification
+ * (`classifyCopilotReviewBodyDisposition`). The classification is shared, so it
+ * cannot drift; the POLICY differs by design (the loop self-blocks on 🔵, this
+ * gate treats 🔵 as conductor-overridable). Fail-closed.
+ *
+ * Only the LATEST Copilot review pinned to `currentHeadSha` is judged, so a
+ * stale non-approval at an earlier head never blocks and a later same-head 🟢
+ * clears an earlier same-head finding.
+ *
+ * Policy (operator-resolved during the v1.0.4 drain):
+ *   🟡 "Changes recommended" on the current head -> BLOCK (actionable; the review
+ *      body is unresolved feedback even with zero inline threads — the exact
+ *      body-only fail-open the loop detects and this precondition enforces at merge).
+ *   🔵 "Needs a closer look" -> conductor-OVERRIDABLE (soft), NOT blocked here.
+ *      Unresolved threads still gate it (detect-checkpoint-evidence refuses any
+ *      unresolved review thread), so a 🔵 merges only with zero unresolved
+ *      threads — the conductor's override is choosing to run the merge on a
+ *      thread-clean 🔵.
+ *   unrecognized disposition -> BLOCK (fail closed on a Copilot format change).
+ *   🟢 clean / no current-head Copilot review / stale earlier-head -> PASS.
+ *
+ * @returns {{ ok: boolean, disposition: string|null, reason: string|null }}
+ */
+export function evaluateCopilotConvergence({ currentHeadSha = null, reviews = [] } = {}) {
+  const head = typeof currentHeadSha === "string" ? currentHeadSha.trim() : "";
+  // Head unknown: no current-head review can be pinned. Fail closed (matches
+  // verifyFreshHumanApproval), so this precondition can never pass without a
+  // known head to pin the Copilot disposition to.
+  if (head.length === 0) return { ok: false, disposition: null, reason: "current head SHA is unknown; cannot pin a Copilot review to it" };
+
+  // Mirror summarizeCopilotReviews' current-head finding selection BYTE-FOR-BYTE
+  // so the merge gate and the loop can never diverge (they already share
+  // classifyCopilotReviewBodyDisposition at the detection layer). Use the SAME
+  // comparison the loop uses — the RAW submittedAt string (a non-string is null),
+  // compared with `>`/`===`, NOT a parsed timestamp: parsing would diverge on a
+  // malformed/mixed-offset submittedAt (an invalid-timestamp 🟡 that the loop
+  // keeps as latest could otherwise be superseded here — a fail-open). Consider
+  // only SUBMITTED current-head reviews, skip PENDING drafts (a PENDING never
+  // sets the finding), pick the latest by submittedAt string, and on an
+  // equal-string tie (or both-null) fold toward the most-blocking disposition so
+  // array order never silently drops a finding.
+  let latestDisposition = null;
+  let latestAt = null;
+  for (const entry of Array.isArray(reviews) ? reviews : []) {
+    const login = reviewLogin(entry);
+    if (login === null || !isCopilotLogin(login)) continue;
+    if (reviewCommit(entry) !== head) continue; // only current-head reviews
+    const state = typeof entry?.state === "string" ? entry.state.toUpperCase() : "";
+    if (state === "PENDING" || !SUBMITTED_REVIEW_STATES.has(state)) continue; // PENDING/unknown never sets the finding
+    const disposition = classifyCopilotReviewBodyDisposition(state, entry?.body);
+    const submittedAt = typeof entry?.submittedAt === "string"
+      ? entry.submittedAt
+      : (typeof entry?.submitted_at === "string" ? entry.submitted_at : null);
+    if (submittedAt !== null && (latestAt === null || submittedAt > latestAt)) {
+      latestDisposition = disposition; // a lexicographically-later submittedAt supersedes (matches summarize)
+      latestAt = submittedAt;
+    } else if (submittedAt !== null && submittedAt === latestAt) {
+      latestDisposition = latestDisposition === null ? disposition : moreBlockingDisposition(latestDisposition, disposition);
+    } else if (submittedAt === null && latestAt === null) {
+      latestDisposition = latestDisposition === null ? disposition : moreBlockingDisposition(latestDisposition, disposition);
+    }
+    // a null submittedAt once a non-null latest exists is ignored (mirrors summarize)
+  }
+  if (latestDisposition === null) return { ok: true, disposition: null, reason: null };
+
+  if (latestDisposition === COPILOT_DISPOSITION.CHANGES_RECOMMENDED) {
+    return { ok: false, disposition: latestDisposition, reason: `current-head Copilot review is "Changes recommended" (🟡, actionable non-approval); converge to "Approval recommended" (🟢) or resolve the feedback before merge` };
+  }
+  if (latestDisposition === COPILOT_DISPOSITION.UNRECOGNIZED) {
+    return { ok: false, disposition: latestDisposition, reason: `current-head Copilot review carries an unrecognized disposition header (fail closed); a recognized "Approval recommended" (🟢) is required` };
+  }
+  // CLEAN, NONE, and NEEDS_CLOSER_LOOK (🔵, conductor-overridable) pass.
+  return { ok: true, disposition: latestDisposition, reason: null };
+}
+
+// Disposition blocking precedence, most-blocking first. Used to fold an
+// equal-timestamp same-head tie toward the most-blocking disposition so a tied
+// 🟡/unrecognized is never silently dropped by a co-timestamped 🟢/🔵.
+const COPILOT_DISPOSITION_BLOCKING_ORDER = [
+  COPILOT_DISPOSITION.CHANGES_RECOMMENDED,
+  COPILOT_DISPOSITION.UNRECOGNIZED,
+  COPILOT_DISPOSITION.NEEDS_CLOSER_LOOK,
+  COPILOT_DISPOSITION.CLEAN,
+  COPILOT_DISPOSITION.NONE,
+];
+function moreBlockingDisposition(a, b) {
+  const ia = COPILOT_DISPOSITION_BLOCKING_ORDER.indexOf(a);
+  const ib = COPILOT_DISPOSITION_BLOCKING_ORDER.indexOf(b);
+  // A value absent from the order (defensive) sorts last.
+  const ra = ia === -1 ? COPILOT_DISPOSITION_BLOCKING_ORDER.length : ia;
+  const rb = ib === -1 ? COPILOT_DISPOSITION_BLOCKING_ORDER.length : ib;
+  return ra <= rb ? a : b;
+}
+
 /**
  * Decide whether merge is authorized given the class, the standing
  * authorization signal, and any fresh per-merge approval.
@@ -273,11 +373,27 @@ export function evaluateMergePreconditions({
     failures.push({ precondition: "size_budget_human_approval", reason: "size-budget requires a human APPROVED review OR a head-pinned \"approve merge <headSha>\" operator comment, with zero unresolved CHANGES_REQUESTED, for this escalated/T1 PR" });
   }
 
+  // Copilot-convergence precondition: refuse a current-head Copilot non-approval
+  // body disposition, mirroring the loop's copilotBodyFeedbackUnresolved.
+  const copilotConvergence = evaluateCopilotConvergence({ currentHeadSha, reviews });
+  if (!copilotConvergence.ok) {
+    failures.push({ precondition: "copilot_convergence", reason: copilotConvergence.reason });
+  }
+
   const mergeClass = resolveMergeClass({ sizeOutcome, touchesT1, stableRelease });
   const decision = resolveMergeApprovalDecision({ mergeClass, standingAuthorized, freshApproval });
   if (!decision.authorized) {
     failures.push({ precondition: "merge_approval", reason: decision.reason });
   }
 
-  return { ok: failures.length === 0, failures, mergeClass, approvalVia: decision.authorized ? decision.via : null };
+  return {
+    ok: failures.length === 0,
+    failures,
+    mergeClass,
+    approvalVia: decision.authorized ? decision.via : null,
+    // Audit trace: the current-head Copilot disposition this verdict saw, so a
+    // merge that ran on a conductor-overridable 🔵 (or any disposition) is
+    // recorded on the machine-readable result rather than being invisible.
+    copilotDisposition: copilotConvergence.disposition,
+  };
 }

package/src/loop/pr-gate-coordination.mjs

@@ -592,7 +592,59 @@ function applyUnsettledCopilotReviewEntryGuard(input, result) {
   const copilotReviewRequestStatus = typeof input.copilotReviewRequestStatus === "string"
     ? input.copilotReviewRequestStatus.trim().toLowerCase()
     : "none";
-  if (copilotReviewRequestStatus !== "requested" && copilotReviewRequestStatus !== "already-requested") {
+  const sameHeadCleanConverged = input.sameHeadCleanConverged === true;
+  const copilotReviewRoundCount = normalizeNonNegativeInteger(input.copilotReviewRoundCount);
+  const copilotReviewOnCurrentHead = input.copilotReviewOnCurrentHead === true;
+  const outstandingRequest = copilotReviewRequestStatus === "requested"
+    || copilotReviewRequestStatus === "already-requested";
+  const roundCapReached = isCopilotRoundCapReached({
+    copilotReviewRoundCount: input.copilotReviewRoundCount,
+    maxCopilotRounds: input.maxCopilotRounds,
+  });
+  // Absent / never-driven: Copilot review is enabled (maxCopilotRounds
+  // > 0, not internal_only) but no round was requested or received for the
+  // CURRENT head, so a clean pre_approval_gate verdict would rest on nothing the
+  // loop actually drove on the head under review. The reconciled status alone is
+  // ambiguous: the reconciler (resolveCopilotReviewRequestStatus) folds a clean
+  // same-head submitted review into "none" too. Three facts each prove this is
+  // not the never-driven case and exempt this branch:
+  //   - sameHeadCleanConverged: a clean same-head submitted Copilot review
+  //     exists on THIS head (including GitHub's incidental auto-review) — the
+  //     no-redundant-re-request case;
+  //   - copilotReviewOnCurrentHead: a submitted Copilot review exists on THIS
+  //     head (a settled current-head round; at a grant boundary its threads are
+  //     already resolved). This is keyed on CURRENT-HEAD evidence, never a raw
+  //     across-PR round count: copilotReviewRoundCount counts reviews on ANY
+  //     head, so a PR with prior-head rounds and a NEW current head that carries
+  //     no review (interpreter state low_signal_converged with
+  //     copilotReviewOnCurrentHead false) must still fail closed;
+  //   - roundCapReached: at/past the cap no further Copilot round can be driven,
+  //     so requiring a current-head review is impossible to satisfy — the
+  //     pre_approval_gate reviews the post-cap head. The core only reaches a
+  //     grant boundary here after gating CI/threads, and a significant
+  //     post-convergence change routes to a rerequest (a new cycle) before this
+  //     guard runs, so this exemption cannot mask a genuinely-unreviewed change;
+  //   - postConvergenceReviewSuppressed: an operator verified (via
+  //     withdraw-copilot-review-request) that the current-head delta since
+  //     Copilot's last submitted review is a pure doc/prose bump, so the prior
+  //     converged review stands for this head — the core grants pre_approval on
+  //     the same basis (never derived here from other snapshot facts).
+  // Fail closed on ANY non-outstanding status, not only the literal "none":
+  // this is the independent gate-ENTRY re-check, so it must not trust the
+  // caller's status string. A non-canonical/unknown value ("", "unavailable",
+  // "failed", a typo) with a grant-y lifecycleState and no current-head review
+  // fails closed rather than slipping through the "none"-only default. Only a
+  // driven current-head review (or the impossible-further-round cap state, or an
+  // operator-verified pure-doc-bump suppression) exempts, so an agent that skips
+  // the explicit Copilot round cannot reach a clean pre_approval verdict via any
+  // grant-y lifecycleState (e.g. a stale/racy low_signal_converged label, or one
+  // carried by prior-head rounds).
+  const absentNeverDriven = !outstandingRequest
+    && !copilotReviewOnCurrentHead
+    && !sameHeadCleanConverged
+    && !roundCapReached
+    && input.postConvergenceReviewSuppressed !== true;
+  if (!outstandingRequest && !absentNeverDriven) {
     return null;
   }
   // Round-cap exemption (mirrors shouldGuardCopilotReviewRequest):
@@ -603,10 +655,6 @@ function applyUnsettledCopilotReviewEntryGuard(input, result) {
   // and the head is clean — either sameHeadCleanConverged or the interpreter's
   // round_cap_clean_fallback state — the pre_approval_gate proceeds unless
   // significant post-convergence changes require a new review cycle.
-  const roundCapReached = isCopilotRoundCapReached({
-    copilotReviewRoundCount: input.copilotReviewRoundCount,
-    maxCopilotRounds: input.maxCopilotRounds,
-  });
   const lifecycleState = typeof input.lifecycleState === "string" ? input.lifecycleState.trim().toLowerCase() : "";
   // Also exempt the evaluator's own ROUND_CAP_REACHED grant shape:
   // without this, this guard would rewrite that grant back to
@@ -624,7 +672,15 @@ function applyUnsettledCopilotReviewEntryGuard(input, result) {
 
   const allowedNextActions = [];
   const forbiddenActions = [];
-  pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.WAIT_FOR_COPILOT_REVIEW]);
+  // Two shapes fail closed here. An OUTSTANDING request (requested/
+  // already-requested) waits for the current-head review to settle. The
+  // ABSENT / never-driven case has nothing to wait for — no request is
+  // in flight — so the loop must first REQUEST a Copilot review, mirroring the
+  // detector-side shouldGuardCopilotReviewRequest override.
+  const nextAction = absentNeverDriven
+    ? PR_CHECKPOINT_ACTION.REQUEST_COPILOT_REVIEW
+    : PR_CHECKPOINT_ACTION.WAIT_FOR_COPILOT_REVIEW;
+  pushUnique(allowedNextActions, [nextAction]);
   // Full postDraftForbidden set (matching the canonical WAITING_FOR_COPILOT_REVIEW
   // result this guard synthesizes) plus the final-approval actions the replaced
   // boundary result also forbade — dropping RUN_DRAFT_GATE/MARK_READY_FOR_REVIEW
@@ -642,18 +698,24 @@ function applyUnsettledCopilotReviewEntryGuard(input, result) {
     repo: input.repo ?? null,
     pr: Number.isInteger(input.pr) ? input.pr : null,
     currentHeadSha: result.currentHeadSha ?? null,
-    lifecycleState: STATE.WAITING_FOR_COPILOT_REVIEW,
-    loopDisposition: DISPOSITION.PENDING,
+    lifecycleState: absentNeverDriven ? STATE.PR_READY_NO_FEEDBACK : STATE.WAITING_FOR_COPILOT_REVIEW,
+    loopDisposition: absentNeverDriven ? DISPOSITION.ACTION_REQUIRED : DISPOSITION.PENDING,
     gateBoundary: PR_CHECKPOINT.POST_DRAFT_EXTERNAL_REVIEW,
     draftGateAlreadySatisfied: result.draftGateAlreadySatisfied === true,
     draftGate: result.draftGate,
     preApprovalGate: result.preApprovalGate,
     allowedNextActions,
     forbiddenActions,
-    nextAction: PR_CHECKPOINT_ACTION.WAIT_FOR_COPILOT_REVIEW,
-    reason: "A Copilot review request is still outstanding on the current head (independent gate-entry "
-      + "re-check, issue #1190) — pre_approval_gate/final-approval entry is refused until the current-head "
-      + "review settles, even though the caller-reported convergence signal claims otherwise.",
+    nextAction,
+    reason: absentNeverDriven
+      ? "Copilot review is enabled for this repo (maxCopilotRounds > 0) but no Copilot review round has been "
+        + "requested or received for the current head (independent gate-entry re-check, issue #2146) — a clean "
+        + "pre_approval_gate/final-approval verdict requires a Copilot round the loop actually drove and awaited, "
+        + "so request Copilot review first. A clean same-head submitted Copilot review (including GitHub's "
+        + "auto-review) would satisfy this; an absent/never-driven round is not settled convergence."
+      : "A Copilot review request is still outstanding on the current head (independent gate-entry "
+        + "re-check, issue #1190) — pre_approval_gate/final-approval entry is refused until the current-head "
+        + "review settles, even though the caller-reported convergence signal claims otherwise.",
     mergeStateStatus: result.mergeStateStatus ?? null,
     conflictFiles: result.conflictFiles ?? [],
     refinementArtifact: result.refinementArtifact ?? null,

package/src/loop/run-inspection.mjs

@@ -555,6 +555,12 @@ export function composeRunInspectionSnapshot({
   if (lifecyclePhase === null) {
     // Fallback: derive from available PR facts
     const loopIter = loopIterations ?? {};
+    // Deferring the loop-iteration fan-out cannot change the phase: every copilot
+    // state maps to one (COPILOT_INNER_STATE_MAP is total over STATE), so whenever
+    // copilot evidence is present the phase is already resolved above and this
+    // fallback never runs. It runs only when that evidence is ABSENT, where there
+    // is no thread count to consult from any source — so there is nothing here to
+    // reconcile between a deferred and a full inspection.
     const hasUnresolvedThreads = typeof loopIter.unresolvedReviewThreads === "number"
       && loopIter.unresolvedReviewThreads > 0;
     const copilotState = copilotLiveOk && copilotEvidence !== null

package/src/loop/spec-authority.mjs

@@ -98,6 +98,17 @@ export const SPEC_AUTHORITY_OUTCOME_VALUES = Object.freeze(
  * three resolve autonomously. Exported so no consumer re-hardcodes the set. */
 export const HUMAN_SPEC_DECISION_OUTCOME = SPEC_AUTHORITY_OUTCOMES.SPEC_CANNOT_DECIDE;
 
+/** The two outcomes that REQUIRE explicit conflict evidence: a non-empty
+ * `conflictingCriteria` array of criterion ids (SPEC-AUTHORITY-CONFLICT-EVIDENCE).
+ * The enforcer and the divergence guard bind to this set directly; the guard
+ * also pins the producer contract prose (`agents/judge.agent.md`) to it, so
+ * producer and enforcer cannot silently diverge. SPEC-AUTHORITY-CONFLICT-EVIDENCE
+ * in this module is the governing rule. */
+export const SPEC_AUTHORITY_CONFLICT_OUTCOMES = Object.freeze([
+  SPEC_AUTHORITY_OUTCOMES.FINDING_CONFLICTS,
+  SPEC_AUTHORITY_OUTCOMES.REMEDIATION_CONFLICTS,
+]);
+
 /**
  * Does an outcome require the loop to stop at the human-spec-decision state?
  * Only `spec_cannot_decide` does — a finding/remediation conflict alone never
@@ -364,15 +375,17 @@ export function validateSpecAuthorityDecision(decision, { specDigest, headSha, c
   // The two conflict outcomes require explicit conflict evidence: a non-empty
   // conflictingCriteria drawn from the spec. Autonomous rejection is only
   // legitimate when it names what the finding/remedy conflicts with.
-  const isConflict =
-    d.outcome === SPEC_AUTHORITY_OUTCOMES.FINDING_CONFLICTS ||
-    d.outcome === SPEC_AUTHORITY_OUTCOMES.REMEDIATION_CONFLICTS;
+  const isConflict = SPEC_AUTHORITY_CONFLICT_OUTCOMES.includes(d.outcome);
   let conflictingCriteria = [];
   if (isConflict) {
-    const conflicts = normalizeIdSet(d.conflictingCriteria, "decision.conflictingCriteria");
-    if (conflicts.size === 0) {
-      throw new Error(`SPEC-AUTHORITY-CONFLICT-EVIDENCE: ${d.outcome} decision requires non-empty conflictingCriteria (explicit conflict evidence; fail closed)`);
+    // Absent, non-array, and empty all mean "no conflict evidence". Route them
+    // to the named rule (not the generic id-set shape error) so a human hitting
+    // this is pointed at the fix — populate the field — rather than a hand-edit;
+    // naming the criteria in `rationale` prose alone does not satisfy it.
+    if (!Array.isArray(d.conflictingCriteria) || d.conflictingCriteria.length === 0) {
+      throw new Error(`SPEC-AUTHORITY-CONFLICT-EVIDENCE: ${d.outcome} decision requires a non-empty conflictingCriteria array of criterion ids (explicit conflict evidence; naming them in rationale prose alone does not satisfy it; fail closed)`);
     }
+    const conflicts = normalizeIdSet(d.conflictingCriteria, "decision.conflictingCriteria");
     const unknownConflicts = [...conflicts].filter((id) => !fullCriteria.has(id));
     if (unknownConflicts.length > 0) {
       throw new Error(`spec-authority decision.conflictingCriteria names unknown criterion id(s): ${unknownConflicts.join(", ")}`);