@dev-loops/core 0.7.1 → 0.8.0

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

@@ -34,6 +34,16 @@ export const REFINEMENT_ARTIFACT_STATUS = Object.freeze({
 
 export const REFINEMENT_ARTIFACT_FINDING = "missing_refinement_artifact";
 
+/**
+ * `refinementArtifact.specSource` values: which of the three sanctioned
+ * spec-of-record origins (artifact-authority-contract.md) backed the check.
+ */
+export const REFINEMENT_ARTIFACT_SPEC_SOURCE = Object.freeze({
+  LINKED_ISSUE: "linked_issue",
+  PR_BODY: "pr_body",
+  PLAN_FILE: "plan_file",
+});
+
 export const PR_CHECKPOINT_ACTION = Object.freeze({
   RUN_DRAFT_GATE: "run_draft_gate",
   MARK_READY_FOR_REVIEW: "mark_ready_for_review",
@@ -227,7 +237,15 @@ function normalizeRefinementArtifactStatus(value) {
   return REFINEMENT_ARTIFACT_STATUS.UNKNOWN;
 }
 
-function formatRefinementBlockedReason(linkedIssue, status) {
+// Issue-less refinement artifacts (specSource "pr_body"/"plan_file") carry
+// their own validation-failure reason from the detector; that reason must
+// replace the "linked issue" wording, which does not apply when the PR is the
+// spec-of-record and no linked issue was ever expected.
+function formatRefinementBlockedReason(linkedIssue, status, refinementArtifact) {
+  const specSource = refinementArtifact?.specSource;
+  if (specSource != null && specSource !== REFINEMENT_ARTIFACT_SPEC_SOURCE.LINKED_ISSUE && typeof refinementArtifact?.reason === "string" && refinementArtifact.reason.length > 0) {
+    return `The draft gate cannot complete: ${refinementArtifact.reason} finding=${REFINEMENT_ARTIFACT_FINDING}`;
+  }
   if (linkedIssue !== null && Number.isInteger(linkedIssue)) {
     return `Linked issue #${linkedIssue} has no refinement artifact (Acceptance criteria / DoD / linked refinement doc). Run refinement first, add ACs/DoD to the issue, then re-open the draft PR. finding=${REFINEMENT_ARTIFACT_FINDING}`;
   }
@@ -470,6 +488,110 @@ const TITLE_MARKER_GUARDED_BOUNDARIES = Object.freeze([
   PR_CHECKPOINT.FINAL_APPROVAL_READY,
 ]);
 
+/**
+ * Independent gate-ENTRY re-check (issue #1190): even when the caller's
+ * lifecycleState/sameHeadCleanConverged claims a settled Copilot convergence,
+ * an outstanding (`requested`/`already-requested`) Copilot review request on
+ * the CURRENT head is a second, independent "unsettled" signal — not derived
+ * from sameHeadCleanConverged — that must refuse pre_approval_gate /
+ * final-approval entry outright.
+ *
+ * This mirrors the fail-closed predicate that previously only fired at
+ * *verdict-post* time (upsert-checkpoint-verdict.mjs, which refuses to post a
+ * pre_approval_gate verdict while this same evaluator forbids
+ * RUN_PRE_APPROVAL_GATE): asserting it here, at gate *entry*, refuses the
+ * pre-approval fan-out up front instead of only after reviewer tokens have
+ * already been spent.
+ *
+ * Skipped when Copilot review is not required at all — `reviewMode:
+ * "internal_only"` or `maxCopilotRounds: 0` — preserving the existing #613 /
+ * #1210 exemptions (internal-only and light-dispatched-with-disabled-review
+ * PRs never need a Copilot round in the first place).
+ */
+const PRE_APPROVAL_ENTRY_BOUNDARIES = Object.freeze([
+  PR_CHECKPOINT.PRE_APPROVAL_GATE_NEEDED,
+  PR_CHECKPOINT.PRE_APPROVAL_GATE_WINDOW,
+  PR_CHECKPOINT.FINAL_APPROVAL_READY,
+]);
+
+function applyUnsettledCopilotReviewEntryGuard(input, result) {
+  if (!result || typeof result !== "object" || !PRE_APPROVAL_ENTRY_BOUNDARIES.includes(result.gateBoundary)) {
+    return null;
+  }
+  if (input.maxCopilotRounds === 0) {
+    return null;
+  }
+  const reviewMode = typeof input.reviewMode === "string" ? input.reviewMode.trim().toLowerCase() : null;
+  if (reviewMode === "internal_only") {
+    return null;
+  }
+  const copilotReviewRequestStatus = typeof input.copilotReviewRequestStatus === "string"
+    ? input.copilotReviewRequestStatus.trim().toLowerCase()
+    : "none";
+  if (copilotReviewRequestStatus !== "requested" && copilotReviewRequestStatus !== "already-requested") {
+    return null;
+  }
+  // Round-cap exemption (mirrors shouldGuardCopilotReviewRequest, #896/#848):
+  // past the cap a lingering requested/already-requested status is for a review
+  // that can never come (no further round is permitted), so treating it as
+  // "unsettled" here would re-introduce the infinite-wait dead-end the
+  // ROUND_CAP_CLEAN_FALLBACK routing exists to prevent. When the cap is reached
+  // 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() : "";
+  const roundCapCleanFallback = lifecycleState === STATE.ROUND_CAP_CLEAN_FALLBACK;
+  if (
+    roundCapReached
+    && (input.sameHeadCleanConverged === true || roundCapCleanFallback)
+    && input.postConvergenceSignificantChange !== true
+  ) {
+    return null;
+  }
+
+  const allowedNextActions = [];
+  const forbiddenActions = [];
+  pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.WAIT_FOR_COPILOT_REVIEW]);
+  // 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
+  // here would let a draft_gate verdict post on a non-draft PR slip through where
+  // the replaced result would have refused it.
+  pushUnique(forbiddenActions, [
+    PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
+    PR_CHECKPOINT_ACTION.MARK_READY_FOR_REVIEW,
+    PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE,
+    PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL,
+    PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY,
+  ]);
+
+  return buildResult({
+    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,
+    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.",
+    mergeStateStatus: result.mergeStateStatus ?? null,
+    conflictFiles: result.conflictFiles ?? [],
+    refinementArtifact: result.refinementArtifact ?? null,
+    copilotReviewRoundCount: normalizeNonNegativeInteger(input.copilotReviewRoundCount),
+  });
+}
+
 /**
  * Evaluates PR gate coordination, then re-asserts the merge-blocking title guard
  * (issue #842) at the pre-approval / final-approval boundary for non-draft PRs.
@@ -482,6 +604,11 @@ const TITLE_MARKER_GUARDED_BOUNDARIES = Object.freeze([
 export function evaluatePrGateCoordination(input = {}) {
   const result = evaluatePrGateCoordinationCore(input);
 
+  const unsettledReviewResult = applyUnsettledCopilotReviewEntryGuard(input, result);
+  if (unsettledReviewResult) {
+    return unsettledReviewResult;
+  }
+
   const prDraft = input.prDraft === true;
   const prTitle = typeof input.prTitle === "string" ? input.prTitle : "";
   // Draft PRs may legitimately carry a WIP title; the marker only blocks once
@@ -755,7 +882,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         allowedNextActions,
         forbiddenActions,
         nextAction: PR_CHECKPOINT_ACTION.REPORT_BLOCKED,
-        reason: formatRefinementBlockedReason(refinementLinkedIssue, refinementArtifactStatus),
+        reason: formatRefinementBlockedReason(refinementLinkedIssue, refinementArtifactStatus, refinementArtifact),
         mergeStateStatus,
         conflictFiles,
         refinementArtifact,

package/src/loop/pr-lifecycle.mjs

@@ -0,0 +1,79 @@
+/**
+ * PR lifecycle: the 13-state vocabulary + required transitions from
+ * skills/docs/pr-lifecycle-contract.md (issue #1193), promoted to a real
+ * exported contract surface.
+ *
+ * This is the single source of truth for the family-local PR lifecycle graph:
+ * both scripts/pages/build-state-atlas.mjs (site diagram generator) and
+ * scripts/docs/validate-state-machine-conformance.mjs (the L2/L3 conformance
+ * harness) import this same table, instead of one importing the other's
+ * module (which would pull the whole page generator — eager mermaid diagram
+ * rendering, duplicate core module instances via relative imports — into the
+ * harness's process at load time).
+ *
+ * Pure data + one derivation, no imports, no side effects.
+ */
+export const PR_LIFECYCLE_STATES = Object.freeze([
+  'draft_local_review_gate',
+  'draft_local_remediation',
+  'ready_state_needs_copilot_request',
+  'waiting_for_copilot_review',
+  'copilot_feedback_remediation',
+  'copilot_reply_resolve_pending',
+  'merge_conflict_resolution',
+  'final_local_preapproval_gate',
+  'final_gate_remediation',
+  'waiting_for_human_pr_approval',
+  'waiting_for_merge',
+  'terminal_slice_complete',
+  'stopped_needs_user_decision',
+]);
+
+// '[*]' is the synthetic terminal-marker target (see build-state-atlas.mjs's
+// renderStateDiagram and validate-state-machine-conformance.mjs's realEdges):
+// a row `[state, '[*]']` marks `state` as absorbing without being a real edge.
+const TERMINAL_MARKER = '[*]';
+
+export const PR_LIFECYCLE_TRANSITIONS = Object.freeze([
+  Object.freeze(['draft_local_review_gate', 'draft_local_remediation']),
+  Object.freeze(['draft_local_review_gate', 'ready_state_needs_copilot_request']),
+  Object.freeze(['draft_local_review_gate', 'stopped_needs_user_decision']),
+  Object.freeze(['draft_local_remediation', 'draft_local_review_gate']),
+  Object.freeze(['ready_state_needs_copilot_request', 'waiting_for_copilot_review']),
+  Object.freeze(['ready_state_needs_copilot_request', 'stopped_needs_user_decision']),
+  Object.freeze(['waiting_for_copilot_review', 'copilot_feedback_remediation']),
+  Object.freeze(['copilot_feedback_remediation', 'copilot_reply_resolve_pending']),
+  Object.freeze(['copilot_reply_resolve_pending', 'ready_state_needs_copilot_request']),
+  Object.freeze(['waiting_for_copilot_review', 'merge_conflict_resolution']),
+  Object.freeze(['merge_conflict_resolution', 'waiting_for_copilot_review']),
+  Object.freeze(['waiting_for_copilot_review', 'final_local_preapproval_gate']),
+  Object.freeze(['final_local_preapproval_gate', 'final_gate_remediation']),
+  Object.freeze(['final_local_preapproval_gate', 'waiting_for_human_pr_approval']),
+  Object.freeze(['final_gate_remediation', 'final_local_preapproval_gate']),
+  Object.freeze(['waiting_for_human_pr_approval', 'waiting_for_merge']),
+  Object.freeze(['waiting_for_human_pr_approval', 'draft_local_review_gate']),
+  Object.freeze(['waiting_for_merge', 'terminal_slice_complete']),
+  Object.freeze(['terminal_slice_complete', TERMINAL_MARKER]),
+  Object.freeze(['stopped_needs_user_decision', TERMINAL_MARKER]),
+]);
+
+// Derived, not hand-listed (lesson from #1157: a hand-copied terminal list can
+// silently drift from the transition table it is supposed to describe). A
+// state is terminal when it has zero real (non-marker) outgoing edges.
+function deriveTerminalStates(states, transitions) {
+  const hasRealOutgoing = new Set(
+    transitions.filter(([, to]) => to !== TERMINAL_MARKER).map(([from]) => from),
+  );
+  return states.filter((state) => !hasRealOutgoing.has(state));
+}
+
+export const PR_LIFECYCLE_TERMINAL_STATES = Object.freeze(deriveTerminalStates(PR_LIFECYCLE_STATES, PR_LIFECYCLE_TRANSITIONS));
+
+// Enum-style access (SCREAMING_SNAKE_CASE key -> the same state string), so
+// handoff scripts can reference `PR_LIFECYCLE_STATE.READY_STATE_NEEDS_COPILOT_REQUEST`
+// instead of hardcoding the literal, mirroring the STATE/OUTER_STATE/REVIEWER_STATE
+// convention used by the other loop state machines. Derived from PR_LIFECYCLE_STATES
+// so a new state cannot be added to one without the other.
+export const PR_LIFECYCLE_STATE = Object.freeze(
+  Object.fromEntries(PR_LIFECYCLE_STATES.map((state) => [state.toUpperCase(), state])),
+);

package/src/loop/queue-board-ordering.mjs

@@ -1,5 +1,5 @@
 import { loadBoardConfig, resolveProjectNumber, loadStateColumnMap, LOGICAL_COLUMN } from "./queue-board-sync.mjs";
-import { main as listQueueItemsMain } from "../../../../scripts/projects/list-queue-items.mjs";
+import { main as listQueueItemsMain } from "../projects/list-queue-items.mjs";
 
 // Canonical fail-closed Next Up tokens — the SINGLE source of truth so the reason
 // codes and the empty-queue message stay byte-identical across every layer that

package/src/loop/queue-board-sync.mjs

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { runChild as coreRunChild } from "../cli/primitives.mjs";
-import { main as moveQueueItemMain } from "../../../../scripts/projects/move-queue-item.mjs";
+import { main as moveQueueItemMain } from "../projects/move-queue-item.mjs";
 
 const DEFAULT_NON_SUCCESS_COLUMN = "Backlog";
 

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

@@ -0,0 +1,173 @@
+/**
+ * Deterministic state machine for the refinement/grill sub-loop.
+ *
+ * The refinement loop runs the grill as a CLOSED, DETERMINISTIC sub-loop:
+ * detect-gaps -> auto-answer -> synthesize -> re-grill -> terminal. The
+ * iteration lives entirely in the transition graph below; the LLM answer and
+ * 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).
+ *
+ * Mirrors the shape of `reviewer-loop-state.mjs` / `copilot-loop-state.mjs`:
+ * a frozen STATE vocabulary, a frozen TRANSITIONS adjacency table, a
+ * `normalize*Snapshot` canonicalizer, and a pure `interpret*State` that maps a
+ * point-in-time snapshot to exactly one current state plus its legal exits.
+ *
+ * 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.
+ */
+
+export const GRILL_STATE = Object.freeze({
+  LOAD_TARGET: "load_target",
+  DETECT_GAPS: "detect_gaps",
+  AWAIT_ANSWERS: "await_answers",
+  SYNTHESIZE: "synthesize",
+  RE_GRILL: "re_grill",
+  GRILL_CLEAN: "grill_clean",
+  NEEDS_HUMAN_HANDOFF: "needs_human_handoff",
+  BLOCKED_NEEDS_USER_DECISION: "blocked_needs_user_decision",
+});
+
+// The iterate-to-clean loop: detect_gaps -> await_answers -> synthesize ->
+// 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.
+export const GRILL_TRANSITIONS = Object.freeze({
+  [GRILL_STATE.LOAD_TARGET]: [
+    GRILL_STATE.DETECT_GAPS,
+    GRILL_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
+  [GRILL_STATE.DETECT_GAPS]: [
+    GRILL_STATE.AWAIT_ANSWERS,
+    GRILL_STATE.GRILL_CLEAN,
+    GRILL_STATE.NEEDS_HUMAN_HANDOFF,
+    GRILL_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
+  [GRILL_STATE.AWAIT_ANSWERS]: [
+    GRILL_STATE.SYNTHESIZE,
+    GRILL_STATE.NEEDS_HUMAN_HANDOFF,
+    GRILL_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
+  [GRILL_STATE.SYNTHESIZE]: [
+    GRILL_STATE.RE_GRILL,
+    GRILL_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
+  [GRILL_STATE.RE_GRILL]: [
+    GRILL_STATE.DETECT_GAPS,
+    GRILL_STATE.GRILL_CLEAN,
+    GRILL_STATE.NEEDS_HUMAN_HANDOFF,
+    GRILL_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
+  [GRILL_STATE.GRILL_CLEAN]: [],
+  [GRILL_STATE.NEEDS_HUMAN_HANDOFF]: [],
+  [GRILL_STATE.BLOCKED_NEEDS_USER_DECISION]: [],
+});
+
+const GRILL_NEXT_ACTIONS = Object.freeze({
+  [GRILL_STATE.LOAD_TARGET]: "Load the target issue/PR/plan body for grilling",
+  [GRILL_STATE.DETECT_GAPS]: "Run the loop-grill gap detectors on the loaded spec",
+  [GRILL_STATE.AWAIT_ANSWERS]: "Consume the bounded answer input: --auto self-answer with a citation, or ask the human interactively",
+  [GRILL_STATE.SYNTHESIZE]: "Synthesize Acceptance criteria / Definition of done / Non-goals into the body; write raw Q&A only to the ephemeral tmp artifact",
+  [GRILL_STATE.RE_GRILL]: "Re-run gap detection to check for a fixed point",
+  [GRILL_STATE.GRILL_CLEAN]: "Grill reached a fixed point; synthesized spec is clean",
+  [GRILL_STATE.NEEDS_HUMAN_HANDOFF]: "Stop and hand off the named unanswerable question(s) to the human; headless parks with the recorded reason",
+  [GRILL_STATE.BLOCKED_NEEDS_USER_DECISION]: "Stop and request explicit user direction",
+});
+
+const VALID_SURFACES = new Set(["issue", "pr", "plan"]);
+
+function normalizeCount(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? Math.floor(value)
+    : 0;
+}
+
+function normalizeStringOrNull(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+/**
+ * Canonicalize a raw grill snapshot into a deterministic shape.
+ *
+ * @param {object} raw
+ * @returns {object}
+ */
+export function normalizeGrillSnapshot(raw) {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("Snapshot must be a non-null object");
+  }
+
+  return {
+    surface: VALID_SURFACES.has(raw.surface) ? raw.surface : "issue",
+    targetRef: normalizeStringOrNull(raw.targetRef),
+
+    loaded: Boolean(raw.loaded),
+    loadFailed: Boolean(raw.loadFailed),
+
+    detectRan: Boolean(raw.detectRan),
+    // answerable gaps still awaiting an answer this pass
+    openGapCount: normalizeCount(raw.openGapCount),
+    // uncitable gaps that must hand off honestly (never fabricated)
+    unresolvedGapCount: normalizeCount(raw.unresolvedGapCount),
+
+    // the bounded LLM answer input, consumed at await_answers
+    answersReady: Boolean(raw.answersReady),
+    // synthesized AC/DoD/Non-goals applied to the body this iteration
+    synthesized: Boolean(raw.synthesized),
+
+    // post-synthesis re-grill fixed-point signals
+    reGrillRan: Boolean(raw.reGrillRan),
+    reGrillFixedPoint: Boolean(raw.reGrillFixedPoint),
+  };
+}
+
+/**
+ * Deterministically interpret the current refinement-grill state.
+ *
+ * @param {object} snapshot
+ * @returns {{state: string, allowedTransitions: string[], nextAction: string}}
+ */
+export function interpretRefinementGrillState(snapshot) {
+  const s = normalizeGrillSnapshot(snapshot);
+
+  let state;
+
+  if (s.loadFailed) {
+    // Fail closed on any load/parse failure, from any point in the loop.
+    state = GRILL_STATE.BLOCKED_NEEDS_USER_DECISION;
+  } else if (!s.loaded) {
+    state = GRILL_STATE.LOAD_TARGET;
+  } else if (s.unresolvedGapCount > 0) {
+    // Honest handoff outranks everything else: never fabricate to converge.
+    state = GRILL_STATE.NEEDS_HUMAN_HANDOFF;
+  } else if (s.synthesized) {
+    if (!s.reGrillRan) {
+      // Synthesis applied -> re-grill to check the fixed point.
+      state = GRILL_STATE.RE_GRILL;
+    } else if (s.reGrillFixedPoint) {
+      state = GRILL_STATE.GRILL_CLEAN;
+    } else {
+      // Re-grill surfaced a new answerable gap -> iterate.
+      state = GRILL_STATE.DETECT_GAPS;
+    }
+  } else if (s.answersReady) {
+    // 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;
+  } else {
+    state = GRILL_STATE.DETECT_GAPS;
+  }
+
+  return {
+    state,
+    allowedTransitions: [...GRILL_TRANSITIONS[state]],
+    nextAction: GRILL_NEXT_ACTIONS[state],
+  };
+}

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

@@ -18,40 +18,55 @@ export const REVIEWER_STATE = Object.freeze({
   BLOCKED_NEEDS_USER_DECISION: "blocked_needs_user_decision",
 });
 
+// The reviewSubmissionStatus guard applies only after the {!prExists, prMerged, prClosed,
+// prDraft} pre-gates, then fires ahead of the state-specific branches: failed ->
+// blocked_needs_user_decision, submitted -> submitted_review. The table declares every such pair.
 export const REVIEWER_TRANSITIONS = Object.freeze({
-  [REVIEWER_STATE.WAITING_FOR_REVIEW_REQUEST]: [REVIEWER_STATE.REVIEW_REQUESTED],
+  [REVIEWER_STATE.WAITING_FOR_REVIEW_REQUEST]: [
+    REVIEWER_STATE.REVIEW_REQUESTED,
+    REVIEWER_STATE.SUBMITTED_REVIEW,
+    REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
   [REVIEWER_STATE.REVIEW_REQUESTED]: [
     REVIEWER_STATE.DETERMINE_REVIEW_PLAN,
+    REVIEWER_STATE.SUBMITTED_REVIEW,
     REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
   ],
   [REVIEWER_STATE.DETERMINE_REVIEW_PLAN]: [
     REVIEWER_STATE.REVIEWS_RUNNING,
+    REVIEWER_STATE.SUBMITTED_REVIEW,
     REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
   ],
   [REVIEWER_STATE.REVIEWS_RUNNING]: [
     REVIEWER_STATE.MERGE_RESULTS,
+    REVIEWER_STATE.SUBMITTED_REVIEW,
     REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
   ],
   [REVIEWER_STATE.MERGE_RESULTS]: [
     REVIEWER_STATE.DRAFT_REVIEW_READY,
+    REVIEWER_STATE.SUBMITTED_REVIEW,
     REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
   ],
   [REVIEWER_STATE.DRAFT_REVIEW_READY]: [
     REVIEWER_STATE.DRAFT_REVIEW_POSTED,
+    REVIEWER_STATE.SUBMITTED_REVIEW,
     REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
   ],
   [REVIEWER_STATE.DRAFT_REVIEW_POSTED]: [
     REVIEWER_STATE.WAITING_FOR_USER_SUBMIT,
     REVIEWER_STATE.REVIEW_INVALIDATED,
     REVIEWER_STATE.SUBMITTED_REVIEW,
+    REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
   ],
   [REVIEWER_STATE.WAITING_FOR_USER_SUBMIT]: [
     REVIEWER_STATE.SUBMITTED_REVIEW,
     REVIEWER_STATE.REVIEW_INVALIDATED,
+    REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
   ],
   [REVIEWER_STATE.SUBMITTED_REVIEW]: [
     REVIEWER_STATE.REVIEW_REQUESTED,
     REVIEWER_STATE.WAITING_FOR_REVIEW_REQUEST,
+    REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
   ],
   [REVIEWER_STATE.WAITING_FOR_AUTHOR_FOLLOWUP]: [
     REVIEWER_STATE.SUBMITTED_REVIEW,
@@ -62,7 +77,10 @@ export const REVIEWER_TRANSITIONS = Object.freeze({
     REVIEWER_STATE.REVIEW_REQUESTED,
     REVIEWER_STATE.SUBMITTED_REVIEW,
   ],
-  [REVIEWER_STATE.REVIEW_INVALIDATED]: [REVIEWER_STATE.REVIEW_REQUESTED],
+  [REVIEWER_STATE.REVIEW_INVALIDATED]: [
+    REVIEWER_STATE.REVIEW_REQUESTED,
+    REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
   [REVIEWER_STATE.BLOCKED_NEEDS_USER_DECISION]: [],
 });