@dev-loops/core 1.0.4-pre.1 → 1.0.4-pre.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "1.0.4-pre.1",
+  "version": "1.0.4-pre.2",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -72,6 +72,7 @@
     "./loop/execution-record": "./src/loop/execution-record.mjs",
     "./loop/primer-evidence": "./src/loop/primer-evidence.mjs",
     "./loop/review-dispatch-plan": "./src/loop/review-dispatch-plan.mjs",
+    "./loop/review-operation": "./src/loop/review-operation.mjs",
     "./loop/reviewer-loop-state": "./src/loop/reviewer-loop-state.mjs",
     "./loop/role-budget-bound": "./src/loop/role-budget-bound.mjs",
     "./loop/run-context": "./src/loop/run-context.mjs",

package/src/config/config.mjs

@@ -110,6 +110,7 @@ const RefinementConfig = z.strictObject({
   fanOut: z.number().int().min(1).max(10).describe("Parallel reviewers per refinement round."),
   mode: z.enum(["parallel", "sequential"]).describe("Whether refinement reviewers run in parallel or one after another."),
   maxCopilotRounds: z.number().int().nonnegative().default(5).describe("Automated Copilot review rounds before converging; 0 disables Copilot review."),
+  requireCopilotConvergenceAtLatestHead: z.boolean().default(false).describe("Require a converged Copilot review at the latest head. False (default): one converged Copilot review stands for later heads, which pre_approval_gate covers. True: a significant change after convergence opens a new Copilot cycle."),
   lowSignal: LowSignalConfig.optional().describe("Early-stop policy for low-signal Copilot rounds."),
   roles: z.array(z.string().trim().min(1)).describe("Review lenses the refinement fan-out dispatches.").optional(),
 });
@@ -1971,6 +1972,20 @@ export function resolveEffectiveCopilotRoundCap(config, { lightweight = false }
   return Math.min(effectiveLightCap, maxCopilotRounds);
 }
 
+/**
+ * Resolve the Copilot convergence mode. False (the default) selects the
+ * converged-once rule: one converged Copilot review stands for later heads.
+ * True restores the strict rule: a significant change after convergence opens
+ * a new Copilot cycle, and only a docs-only or integrate-only delta carries.
+ * Loop and merge both read the mode through this resolver. Light-dispatched
+ * PRs use the same value.
+ * @param {DevLoopConfig} config
+ * @returns {boolean}
+ */
+export function resolveRequireCopilotConvergenceAtLatestHead(config) {
+  return config?.refinement?.requireCopilotConvergenceAtLatestHead === true;
+}
+
 /** Label that forces full fan-out regardless of change size. */
 export const GATE_FULL_LABEL = "gate:full";
 

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

@@ -445,8 +445,12 @@ export function interpretLoopState(snapshot, refinementConfig) {
       // A current-head Copilot request is still active/pending and must settle before gate progression.
       state = STATE.WAITING_FOR_COPILOT_REVIEW;
     } else if (s.copilotReviewPresent) {
-      // Copilot has reviewed at least once; all threads resolved
-      if (ciBlocks) {
+      // Copilot has reviewed at least once; all threads resolved. A later
+      // body-only finding on an earlier commit outranks a clean current-head
+      // review, and merge refuses on it. A re-request would stop at the
+      // same-head clean suppression, so only a copilot-body-disposition record
+      // naming that review clears it.
+      if (ciBlocks || (s.copilotReviewOnCurrentHead && s.copilotPriorHeadBodyFeedbackUnresolved)) {
         state = STATE.BLOCKED_NEEDS_USER_DECISION;
       } else if (ciWaits) {
         state = STATE.WAITING_FOR_CI;

package/src/loop/merge-approval.mjs

@@ -168,8 +168,9 @@ export const COPILOT_CONVERGENCE_STATE = Object.freeze({
   NO_CURRENT_HEAD_REVIEW: "no_current_head_review",
 });
 
-/** ADR 0012 end states that may satisfy convergence without a current-head review. */
+/** ADR 0012 end states (amended by ADR 0090) that may satisfy convergence without a current-head review. */
 export const COPILOT_ABSENT_REVIEW_DISPOSITION = Object.freeze({
+  CONVERGED_ONCE: "converged_once",
   ROUND_CAP_CLEAN_FALLBACK: "round_cap_clean_fallback",
   DOCS_ONLY_SUPPRESSION: "docs_only_suppression",
   COPILOT_GATE_DISABLED: "copilot_gate_disabled",
@@ -231,6 +232,10 @@ export function evaluateCopilotConvergence({ currentHeadSha = null, reviews = []
   // array order never silently drops a finding.
   let latestDisposition = null;
   let latestAt = null;
+  // The id of the review that owns latestDisposition: the review a
+  // copilot-body-disposition record must name to clear a finding. Null when two
+  // tied reviews both block, so no single record can clear the tie.
+  let latestReviewId = null;
   for (const entry of Array.isArray(reviews) ? reviews : []) {
     // Shape-tolerant Copilot-login + commit extraction: the merge gate feeds
     // REST-shaped reviews (user.login/commit_id) while the gate-ENTRY detector
@@ -246,16 +251,20 @@ export function evaluateCopilotConvergence({ currentHeadSha = null, 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 reviewId = entry?.id !== null && entry?.id !== undefined ? String(entry.id) : null;
     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)
+      latestReviewId = reviewId;
       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);
+    } else if (submittedAt === latestAt) {
+      // Equal-string tie, or both null.
+      ({ disposition: latestDisposition, reviewId: latestReviewId } = foldTiedReview(
+        { disposition: latestDisposition, reviewId: latestReviewId },
+        { disposition, reviewId },
+      ));
     }
     // a null submittedAt once a non-null latest exists is ignored (mirrors summarize)
   }
@@ -275,13 +284,13 @@ export function evaluateCopilotConvergence({ currentHeadSha = null, reviews = []
 
   const findings = COPILOT_CONVERGENCE_STATE.CURRENT_HEAD_FINDINGS;
   if (latestDisposition === COPILOT_DISPOSITION.CHANGES_RECOMMENDED) {
-    return { ok: false, state: findings, disposition: latestDisposition, reason: `current-head Copilot review is "Changes recommended" (🟡, actionable non-approval); converge to "Approval recommended" (🟢) or resolve the feedback before merge` };
+    return { ok: false, state: findings, disposition: latestDisposition, reviewId: latestReviewId, 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, state: findings, disposition: latestDisposition, reason: `current-head Copilot review carries an unrecognized disposition header (fail closed); a recognized "Approval recommended" (🟢) is required` };
+    return { ok: false, state: findings, disposition: latestDisposition, reviewId: latestReviewId, 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, state: COPILOT_CONVERGENCE_STATE.CURRENT_HEAD_CLEAN, disposition: latestDisposition, reason: null };
+  return { ok: true, state: COPILOT_CONVERGENCE_STATE.CURRENT_HEAD_CLEAN, disposition: latestDisposition, reviewId: latestReviewId, reason: null };
 }
 
 // Disposition blocking precedence, most-blocking first. Used to fold an
@@ -303,6 +312,19 @@ function moreBlockingDisposition(a, b) {
   return ra <= rb ? a : b;
 }
 
+// Fold one tied current-head review into the running latest. The disposition
+// folds toward the most blocking. The owning review id follows the blocking
+// review; two tied blocking reviews leave no single owner (null).
+const BLOCKING_CONVERGENCE_DISPOSITIONS = new Set([COPILOT_DISPOSITION.CHANGES_RECOMMENDED, COPILOT_DISPOSITION.UNRECOGNIZED]);
+function foldTiedReview(latest, next) {
+  if (latest.disposition === null) return next;
+  if (BLOCKING_CONVERGENCE_DISPOSITIONS.has(latest.disposition) && BLOCKING_CONVERGENCE_DISPOSITIONS.has(next.disposition)) {
+    return { disposition: moreBlockingDisposition(latest.disposition, next.disposition), reviewId: null };
+  }
+  const disposition = moreBlockingDisposition(latest.disposition, next.disposition);
+  return { disposition, reviewId: disposition === latest.disposition ? latest.reviewId : next.reviewId };
+}
+
 /**
  * Decide whether merge is authorized given the class, the standing
  * authorization signal, and any fresh per-merge approval.
@@ -382,6 +404,10 @@ export function evaluateMergePreconditions({
   stableRelease = false,
   copilotAbsentReviewDisposition = null,
   copilotBodyDisposition = null,
+  // Refusal reason when a Copilot review submitted after the current-head
+  // verdict review sits on an earlier commit and is not converged (the latest
+  // review decides); null otherwise.
+  copilotLaterReviewRefusal = null,
 } = {}) {
   const failures = [];
 
@@ -432,14 +458,19 @@ export function evaluateMergePreconditions({
   // body disposition, mirroring the loop's copilotBodyFeedbackUnresolved.
   // A trusted copilot-body-disposition record resolved for the current head
   // (`{ headSha, reviewId, ... }`) clears a current-head finding, as it does
-  // at gate entry.
+  // at gate entry, only when it names the review that raised the finding.
   const copilotConvergence = evaluateCopilotConvergence({ currentHeadSha, reviews, absentReviewDisposition: copilotAbsentReviewDisposition });
   const head = typeof currentHeadSha === "string" ? currentHeadSha.trim().toLowerCase() : "";
   const bodyCleared = copilotConvergence.state === COPILOT_CONVERGENCE_STATE.CURRENT_HEAD_FINDINGS
     && head.length > 0
-    && typeof copilotBodyDisposition?.headSha === "string" && copilotBodyDisposition.headSha.toLowerCase() === head;
+    && typeof copilotBodyDisposition?.headSha === "string" && copilotBodyDisposition.headSha.toLowerCase() === head
+    // The record clears only the review that raised the current-head finding.
+    && copilotConvergence.reviewId !== null
+    && String(copilotBodyDisposition.reviewId) === copilotConvergence.reviewId;
   if (!copilotConvergence.ok && !bodyCleared) {
     failures.push({ precondition: "copilot_convergence", reason: copilotConvergence.reason });
+  } else if (typeof copilotLaterReviewRefusal === "string") {
+    failures.push({ precondition: "copilot_convergence", reason: copilotLaterReviewRefusal });
   }
 
   const mergeClass = resolveMergeClass({ sizeOutcome, touchesT1, stableRelease });

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

@@ -510,6 +510,9 @@ function buildResult({
  * @param {boolean} [params.postConvergenceSignificantChange=false] - significant
  *   post-convergence changes on a newer head start a new review cycle and must
  *   not be treated as round-cap clean-fallback suppression.
+ * @param {boolean} [params.postConvergenceReviewSuppressed=false] - the caller
+ *   verified a carried convergence for this head, so no further Copilot request
+ *   is due (mirrors applyUnsettledCopilotReviewEntryGuard).
  * @param {string} params.gateBoundary - current gate boundary
  * @returns {boolean}
  */
@@ -521,6 +524,7 @@ export function shouldGuardCopilotReviewRequest({
   sameHeadCleanConverged = false,
   roundCapCleanFallback = false,
   postConvergenceSignificantChange = false,
+  postConvergenceReviewSuppressed = false,
   gateBoundary,
 }) {
   const gateBoundariesRequiringCopilotFormalRequest = new Set([
@@ -540,6 +544,11 @@ export function shouldGuardCopilotReviewRequest({
   if (copilotReviewRequestStatus !== "none") {
     return false;
   }
+  // A carried convergence settles this head without a new Copilot round; the
+  // request tool would return a suppressed status, so a forced request livelocks.
+  if (postConvergenceReviewSuppressed === true) {
+    return false;
+  }
   // Durable signal: if Copilot was ever formally requested as a reviewer,
   // the current "none" status is from a fulfilled request (normal cycle),
   // not from a missing request. Do not guard the happy path.
@@ -669,17 +678,19 @@ function applyUnsettledCopilotReviewEntryGuard(input, result) {
   //     guard runs, so this exemption cannot mask a genuinely-unreviewed change;
   //   - postConvergenceReviewSuppressed: the caller verified a carried
   //     convergence (or an operator suppression marker) for this head: no
-  //     outstanding request, zero unresolved threads, and a provably docs-only
-  //     or integrate-only delta since Copilot's last submitted review, so the
-  //     prior converged review stands for this head (never derived here from
-  //     other snapshot facts).
+  //     outstanding request, zero unresolved threads, and a converged latest
+  //     Copilot review on an earlier head. By default that review carries
+  //     whatever the delta (converged-once); under the strict setting only a
+  //     provably docs-only or integrate-only delta carries. The prior converged
+  //     review then stands for this head (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
+  // driven current-head review (or the impossible-further-round cap state, or a
+  // caller-verified carried convergence) 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).
@@ -891,8 +902,8 @@ function evaluatePrGateCoordinationCore(input = {}) {
   // Carried convergence: set only when the caller verified, through the
   // shared carried-convergence predicate the Copilot request tool also uses,
   // that the prior converged Copilot review still stands for this head (no
-  // outstanding request, zero unresolved threads, a provably docs-only or
-  // integrate-only delta), or that an operator suppression marker re-verifies
+  // outstanding request, zero unresolved threads, and in strict mode a
+  // provably docs-only or integrate-only delta), or that an operator suppression marker re-verifies
   // on the same terms. Never derived here from other snapshot facts: this
   // evaluator trusts the caller's verification, so the request tool and the
   // gate cannot disagree about the same head.
@@ -1812,7 +1823,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
       reason: roundCapReached
         ? `The Copilot round limit is exhausted (${copilotReviewRoundCount}/${maxCopilotRounds}), and the current head has zero unresolved threads with ${describeAcceptedCiState(ciStatus, preApprovalRequireCi)}, so \`pre_approval_gate\` fallback is now the next legal boundary.`
         : (postConvergenceReviewSuppressed && !sameHeadCleanConverged
-          ? "The current head carries the prior converged Copilot review: no request is outstanding, no review thread is unresolved, and the delta since Copilot's last submitted review is provably docs-only or integrate-only, so `pre_approval_gate` is now the next legal boundary."
+          ? "The current head carries the prior converged Copilot review (carriedConvergence names the source review): no request is outstanding, no review thread is unresolved, and the carry rule holds (converged-once by default; a provably docs-only or integrate-only delta under refinement.requireCopilotConvergenceAtLatestHead), so `pre_approval_gate` is now the next legal boundary."
           : (ciStatus === "crediblyGreen"
             ? "The current head has a clean settled post-draft review cycle, and its zero-suite CI state is accepted as credibly green, so `pre_approval_gate` is now the next legal boundary."
             : "The current head has a clean settled post-draft review cycle, so `pre_approval_gate` is now the next legal boundary.")),

package/src/loop/refinement-grill-state.mjs

@@ -7,7 +7,7 @@
  * synthesis enter ONLY as a bounded input consumed at the `await_answers`
  * state (and reflected in the `synthesized` snapshot flag), never as hidden
  * orchestration inside a deterministic coordinator script (keeps
- * OPS-NO-INLINE-INTERPRETER, #1224, clean).
+ * OPS-NO-INLINE-INTERPRETER clean).
  *
  * Mirrors the shape of `reviewer-loop-state.mjs` / `copilot-loop-state.mjs`:
  * a frozen STATE vocabulary, a frozen TRANSITIONS adjacency table, a
@@ -17,6 +17,15 @@
  * Honest handoff: when a gap is genuinely unanswerable (only-`inferred`, no
  * citation), the machine reaches `needs_human_handoff` naming the question
  * rather than fabricating an answer to force convergence.
+ *
+ * Zero-gap provenance (see ADR 0084, which amends ADR 0029): a zero-open-gap
+ * `detect_gaps` pass resolves to `grill_clean` only for a `plan` surface
+ * (shape-only, no comment surface) or when a `🔬 Grill / refinement results`
+ * comment is already recorded on the target; otherwise it stays at
+ * `detect_gaps` so the semantic pass still runs and records its own
+ * provenance, including a zero-gap outcome. `detectIssueRefinementArtifact`
+ * stays the sole shape/completeness predicate; provenance is a separate
+ * recorded fact, not a second refinedness detector.
  */
 
 import { trimmedOrNull } from "./normalize.mjs";
@@ -36,7 +45,10 @@ export const GRILL_STATE = Object.freeze({
 // re_grill, with re_grill either re-entering detect_gaps (a new answerable gap
 // surfaced) or terminating at grill_clean (fixed point). Any I/O/parse failure
 // fails closed to blocked_needs_user_decision; any unresolved (uncitable) gap
-// terminates honestly at needs_human_handoff.
+// terminates honestly at needs_human_handoff. A zero-open-gap detect_gaps pass
+// terminates at grill_clean only with recorded provenance (plan surface, or a
+// posted results comment); otherwise it stays at detect_gaps for the owed
+// semantic pass (ADR 0084).
 export const GRILL_TRANSITIONS = Object.freeze({
   [GRILL_STATE.LOAD_TARGET]: [
     GRILL_STATE.DETECT_GAPS,
@@ -81,12 +93,76 @@ const GRILL_NEXT_ACTIONS = Object.freeze({
 
 const VALID_SURFACES = new Set(["issue", "pr", "plan"]);
 
+// The exact comment title provenance is keyed on (GRILL-SUBLOOP-RATIONALE-COMMENT).
+const RESULTS_COMMENT_TITLE = "🔬 Grill / refinement results";
+// The exact first-line heading a results comment must carry -- SKILL.md Step 4
+// and the output artifact contract require exactly "## " (one hash pair, one
+// space), never a bare title or a different heading level.
+const RESULTS_COMMENT_HEADING = `## ${RESULTS_COMMENT_TITLE}`;
+// A results comment's recorded bypass line: "bypass: operator-authorized by <handle>",
+// with an optional leading @ before the handle and a case-insensitive "bypass:" key.
+const BYPASS_LINE_RE = /^bypass: operator-authorized by @?([A-Za-z0-9][A-Za-z0-9-]{0,38})\s*$/i;
+
 function normalizeCount(value) {
   return typeof value === "number" && Number.isFinite(value) && value > 0
     ? Math.floor(value)
     : 0;
 }
 
+/**
+ * Detect recorded grill provenance from a target's comments: a durable
+ * `🔬 Grill / refinement results` comment, optionally carrying an
+ * `bypass: operator-authorized by <handle>` line. The ephemeral
+ * `tmp/issues/issue-<n>/grill/` transcript is never a comment, so it never
+ * counts here.
+ *
+ * @param {Array<string|{body?: string}>} comments
+ * @returns {{provenanceRecorded: boolean, bypass: boolean, bypassBy: string|null}}
+ */
+export function detectGrillProvenance(comments) {
+  if (!Array.isArray(comments)) {
+    return { provenanceRecorded: false, bypass: false, bypassBy: null };
+  }
+
+  let provenanceRecorded = false;
+  let bypass = false;
+  let bypassBy = null;
+
+  for (const comment of comments) {
+    const body = typeof comment === "string"
+      ? comment
+      : (comment && typeof comment.body === "string" ? comment.body : null);
+    if (body === null) continue;
+
+    const lines = body.split(/\r?\n/);
+    // A comment counts as a results comment only when its FIRST non-empty
+    // line, trimmed, is EXACTLY the "## " heading -- this rejects a bare
+    // title, a different heading level (`###`), a missing space (`##🔬`),
+    // the title merely quoted in a code fence, or the title appearing later
+    // in an unrelated reply.
+    const firstNonEmpty = lines.find((line) => line.trim().length > 0);
+    const isResultsComment = firstNonEmpty !== undefined
+      && firstNonEmpty.trim() === RESULTS_COMMENT_HEADING;
+    if (!isResultsComment) continue;
+
+    provenanceRecorded = true;
+    if (!bypass) {
+      // Take the first bypass-line match across all results comments; a
+      // later comment's bypass line never overwrites an earlier one.
+      for (const line of lines) {
+        const match = line.trim().match(BYPASS_LINE_RE);
+        if (match) {
+          bypass = true;
+          bypassBy = match[1];
+          break;
+        }
+      }
+    }
+  }
+
+  return { provenanceRecorded, bypass, bypassBy };
+}
+
 /**
  * Canonicalize a raw grill snapshot into a deterministic shape.
  *
@@ -119,19 +195,32 @@ export function normalizeGrillSnapshot(raw) {
     // post-synthesis re-grill fixed-point signals
     reGrillRan: Boolean(raw.reGrillRan),
     reGrillFixedPoint: Boolean(raw.reGrillFixedPoint),
+
+    // recorded provenance: a posted `🔬 Grill / refinement results` comment
+    // (see detectGrillProvenance), and whether it carries a recorded bypass line.
+    // A bypass line only ever means anything alongside a recorded comment, so
+    // provenanceBypass is forced false when provenanceRecorded is false --
+    // never a standalone shortcut to grill_clean.
+    provenanceRecorded: Boolean(raw.provenanceRecorded),
+    provenanceBypass: Boolean(raw.provenanceRecorded) && Boolean(raw.provenanceBypass),
   };
 }
 
+const PROVENANCE_MISSING_NEXT_ACTION =
+  "Run the semantic gap pass on the loaded spec, then post the \"🔬 Grill / refinement results\" comment recording the outcome — including a zero-gap pass, which states that no gaps were found";
+
 /**
  * Deterministically interpret the current refinement-grill state.
  *
  * @param {object} snapshot
- * @returns {{state: string, allowedTransitions: string[], nextAction: string}}
+ * @returns {{state: string, allowedTransitions: string[], nextAction: string, reason: string|null, bypass: boolean}}
  */
 export function interpretRefinementGrillState(snapshot) {
   const s = normalizeGrillSnapshot(snapshot);
 
   let state;
+  let reason = null;
+  let bypass = false;
 
   if (s.loadFailed) {
     // Fail closed on any load/parse failure, from any point in the loop.
@@ -155,17 +244,40 @@ export function interpretRefinementGrillState(snapshot) {
     // Bounded answer input present -> apply synthesis.
     state = GRILL_STATE.SYNTHESIZE;
   } else if (s.detectRan) {
-    // Detection ran with no unresolved and no pending answers:
-    // open gaps -> await answers; zero gaps -> clean fixed point
-    // (also the already-refined, zero-iteration path).
-    state = s.openGapCount > 0 ? GRILL_STATE.AWAIT_ANSWERS : GRILL_STATE.GRILL_CLEAN;
+    if (s.openGapCount > 0) {
+      // Detection ran; answerable gaps still open -> await answers.
+      state = GRILL_STATE.AWAIT_ANSWERS;
+    } else if (s.surface === "plan") {
+      // Local plan files have no comment surface: shape-only, zero-iteration clean.
+      state = GRILL_STATE.GRILL_CLEAN;
+      reason = "plan_shape_only";
+    } else if (s.provenanceBypass) {
+      // A recorded bypass line still counts as recorded provenance.
+      state = GRILL_STATE.GRILL_CLEAN;
+      reason = "provenance_bypass_recorded";
+      bypass = true;
+    } else if (s.provenanceRecorded) {
+      state = GRILL_STATE.GRILL_CLEAN;
+      reason = "provenance_recorded";
+    } else {
+      // Zero open gaps but no recorded provenance: the semantic pass is still
+      // owed (ADR 0084) — stay at detect_gaps rather than short-circuiting.
+      state = GRILL_STATE.DETECT_GAPS;
+      reason = "provenance_missing";
+    }
   } else {
     state = GRILL_STATE.DETECT_GAPS;
   }
 
+  const nextAction = reason === "provenance_missing"
+    ? PROVENANCE_MISSING_NEXT_ACTION
+    : GRILL_NEXT_ACTIONS[state];
+
   return {
     state,
     allowedTransitions: [...GRILL_TRANSITIONS[state]],
-    nextAction: GRILL_NEXT_ACTIONS[state],
+    nextAction,
+    reason,
+    bypass,
   };
 }

package/src/loop/review-operation.mjs

@@ -0,0 +1,161 @@
+/**
+ * review-operation
+ *
+ * The ONE operation-scoped authority for the legal dispatchable-angle pool and
+ * the reviewer role it authorizes. write-gate-context.mjs's standalone-review
+ * angle union and the `dev-loops gate resolve-role` CLI both consume this
+ * module instead of reconstructing membership/eligibility rules of their own.
+ * The draft/pre-approval/spike dispatch paths keep calling
+ * `resolveGateAngleContract` directly for their pool, which this module wraps
+ * (see `resolveOperationAnglePool` below) rather than duplicating.
+ *
+ * `resolveOperationAnglePool` owns only the legal CANDIDATE catalog for an
+ * operation. Diff-/tier-/PR-fact-driven SELECTION from that catalog (which
+ * angles actually run this round) and any later spec-of-record pruning stay
+ * downstream dispatch/planning concerns (see write-gate-context.mjs's
+ * `resolveReviewGateAngles`, which imports this module for its union instead
+ * of recomputing it).
+ *
+ * `resolveOperationReviewerRole` is the authoritative exit-code boundary the
+ * `dev-loops gate resolve-role` CLI consumes for standalone/defensive role
+ * resolution: `ok` is fail-closed true only when the merged config loaded
+ * with no errors AND the requested angle is a legal member of the named
+ * operation's pool. `status` is a DIAGNOSTIC field only (never a second
+ * reviewer decision surface); see skills/docs/gate-review-comment-contract.md
+ * and skills/docs/gate-review-sub-loop-contract.md.
+ */
+import { resolveGateAngleContract, resolveGateAngles, resolveReviewerRole, resolveRoleModel } from "../config/config.mjs";
+import { GATE_CONFIG_KEY } from "./gate-fanin.mjs";
+
+/** The closed review-operation vocabulary. Standalone `review` is only ever selected by name, never inferred. */
+export const REVIEW_OPERATIONS = Object.freeze(["draft_gate", "pre_approval_gate", "review", "spike"]);
+
+// GATE_CONFIG_KEY (gate-fanin.mjs) has no `spike` entry — other code relies on
+// its absence of review/spike — so this operation-scoped table adds it locally
+// instead of widening the shared one.
+const OPERATION_GATE_KEY = Object.freeze({ ...GATE_CONFIG_KEY, spike: "spike" });
+
+/**
+ * Resolve the legal candidate angle pool for a review operation from the
+ * fully merged config:
+ *   - draft_gate / pre_approval_gate / spike: the effective `gates.<key>`
+ *     pool (`resolveGateAngleContract(config, key).pool` — mandatory/static/
+ *     additive rules applied, disabled/excluded angles removed).
+ *   - review: the de-duplicated, order-stable union of the static draft and
+ *     pre-approval angle sets (`resolveGateAngles`, NOT the additive/tier
+ *     pool) — standalone review's existing dedicated semantics; it gains no
+ *     diff-tier or additive selection here.
+ * An unrecognized operation throws (arg-identity error, not a config-layer
+ * concern; callers validate `--gate` before ever reaching config load).
+ * @param {import("../config/config.mjs").DevLoopConfig} config
+ * @param {"draft_gate"|"pre_approval_gate"|"review"|"spike"} operation
+ * @returns {string[]}
+ */
+export function resolveOperationAnglePool(config, operation) {
+  if (!REVIEW_OPERATIONS.includes(operation)) {
+    throw new Error(`Unknown review operation: ${JSON.stringify(operation)} (expected one of ${REVIEW_OPERATIONS.join(", ")})`);
+  }
+  if (operation === "review") {
+    return [...new Set([
+      ...(resolveGateAngles(config, "draft") ?? []),
+      ...(resolveGateAngles(config, "preApproval") ?? []),
+    ])];
+  }
+  return resolveGateAngleContract(config, OPERATION_GATE_KEY[operation]).pool ?? [];
+}
+
+/**
+ * @typedef {object} OperationReviewerRoleResult
+ * @property {boolean} ok - Fail-closed reviewer safety boundary: `configErrors.length === 0 && pool.includes(angle)`.
+ * @property {"draft_gate"|"pre_approval_gate"|"review"|"spike"} operation
+ * @property {string} angle
+ * @property {"claude"|"pi"} harness
+ * @property {string} persona
+ * @property {string|null} prompt
+ * @property {string|null} model - Authoritative merged model tier (`resolveRoleModel(..., { kind: "angle" })`).
+ * @property {boolean} fallback
+ * @property {"config-error"|"non-member"|"fallback"|"prompt-missing"|"resolved"} status - Diagnostic only; never a reviewer decision branch.
+ * @property {string[]} warnings
+ * @property {Array<unknown>} configErrors
+ */
+
+/**
+ * Resolve one angle's reviewer role for a review operation, authorized
+ * against `resolveOperationAnglePool`. This is the shared authority a CLI
+ * (`gate resolve-role`), dispatch/planning, or defensive validation all call —
+ * none of them may reimplement membership/union/additive/disabled/spike
+ * classification locally.
+ * @param {{ config: import("../config/config.mjs").DevLoopConfig, errors?: Array<unknown> }} loadResult - the `{ config, errors }` shape `loadDevLoopConfig` returns.
+ * @param {{ operation: "draft_gate"|"pre_approval_gate"|"review"|"spike", angle: string, harness: "claude"|"pi" }} params
+ * @returns {OperationReviewerRoleResult}
+ */
+export function resolveOperationReviewerRole(loadResult, { operation, angle, harness }) {
+  const config = loadResult?.config;
+  const configErrors = Array.isArray(loadResult?.errors) ? loadResult.errors : [];
+  const configErrorPresent = configErrors.length > 0;
+  // An unrecognized operation is a closed-vocabulary argument failure, not a
+  // config-layer concern; it must throw unconditionally, even when a config
+  // error is also on record — never degraded to a misleading config-error
+  // result below. Validate before the try so this throw is never swallowed.
+  if (!REVIEW_OPERATIONS.includes(operation)) {
+    throw new Error(`Unknown review operation: ${JSON.stringify(operation)} (expected one of ${REVIEW_OPERATIONS.join(", ")})`);
+  }
+  let pool;
+  try {
+    pool = resolveOperationAnglePool(config, operation);
+  } catch (error) {
+    // A config that already failed merged schema validation (non-empty
+    // `errors` from loadDevLoopConfig) can still reach here with a gate shape
+    // resolveGateConfig itself rejects (e.g. an invalid
+    // `gates.<gate>.blockCleanOnFindingSeverities`). That is a config-layer
+    // failure the caller's own config-error fail-closed status already
+    // covers, so degrade to an empty pool instead of an unhandled exception
+    // reaching the reviewer boundary. With no config error on record, this is
+    // a real schema-invalid gate shape a caller must see: rethrow.
+    if (!configErrorPresent) throw error;
+    pool = [];
+  }
+  const member = pool.includes(angle);
+  const ok = !configErrorPresent && member;
+
+  const role = resolveReviewerRole(config, angle);
+  const model = resolveRoleModel(config, { role: angle, harness, kind: "angle" });
+
+  const warnings = [];
+  let status;
+  if (configErrorPresent) {
+    status = "config-error";
+    warnings.push(
+      `${configErrors.length} config-layer error(s); the resolved role may be a shipped default and must not be trusted.`,
+    );
+  } else if (!member) {
+    status = "non-member";
+    warnings.push(`angle '${angle}' is not a member of the '${operation}' operation's legal candidate pool.`);
+  } else if (role.fallback) {
+    status = "fallback";
+    warnings.push(
+      `angle '${angle}' is authorized for '${operation}' but has no dedicated persona/prompt entry; the default-reviewer persona is returned.`,
+    );
+  } else if (typeof role.prompt !== "string" || role.prompt.trim() === "") {
+    status = "prompt-missing";
+    warnings.push(
+      `angle '${angle}' resolved persona '${role.persona}' but its focus prompt is null/empty; review with no angle-specific focus instruction.`,
+    );
+  } else {
+    status = "resolved";
+  }
+
+  return {
+    ok,
+    operation,
+    angle,
+    harness,
+    persona: role.persona,
+    prompt: role.prompt,
+    model,
+    fallback: role.fallback,
+    status,
+    warnings,
+    configErrors,
+  };
+}