@dev-loops/core 0.8.0 → 1.0.0-rc.1

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

@@ -0,0 +1,244 @@
+/**
+ * Gate carry-forward: a pure, fail-closed seam that decides whether a clean gate
+ * angle verdict recorded at head A may be CARRIED FORWARD to head B without
+ * re-running that angle's reviewer.
+ *
+ * Motivation: fresh-context-per-head re-fans ALL gate angles on every head bump,
+ * even when the delta between the two heads provably cannot affect most angles
+ * (e.g. a doc-only follow-up commit cannot change what a code-correctness angle
+ * would find). Carry-forward lets the gate reuse the prior clean verdict for such
+ * angles — but ONLY when it is provably safe.
+ *
+ * FAIL-CLOSED is paramount. An angle carries forward ONLY when EVERY changed file
+ * in the delta A..B is provably OUTSIDE that angle's declared review surface. The
+ * default in every uncertain case (non-clean prior verdict, empty/unavailable
+ * delta, an unclassifiable file, an angle with no declared surface, a mandatory /
+ * always-run angle) is MUST-RE-RUN. Carry-forward never fabricates a verdict: the
+ * caller records the carried verdict with provenance pointing at the PRIOR head's
+ * reviewer (that reviewer genuinely reviewed this angle's surface, which the delta
+ * did not touch), clearly marked as carried — see
+ * docs/gate-review-sub-loop-contract.md and write-gate-findings-log.mjs's
+ * `carriedFromHead` provenance field.
+ *
+ * The angle -> review-surface mapping is DERIVED from the single source of truth
+ * for change-category -> angle relevance (CATEGORY_ANGLE_MAP in
+ * ../analysis/change-classifier.mjs) so the two never drift: an angle's review
+ * surface is exactly the set of file "surface kinds" whose change could, under the
+ * existing dynamic-angle rules, implicate that angle. File classification reuses
+ * classifyFile() from the diff analyzer (the same classifier dynamic angle
+ * resolution already trusts).
+ *
+ * This module is intentionally pure and side-effect free.
+ */
+
+import { classifyFile } from "../analysis/diff-analyzer.mjs";
+import { ALWAYS_INCLUDE, CATEGORY_ANGLE_MAP } from "../analysis/change-classifier.mjs";
+
+/**
+ * File surface kind (classifyFile output) -> the change categories a change of
+ * that kind can produce. A code file can be either a logic change or a
+ * comment-only change; the other kinds each map to their single `_ONLY` category.
+ * "unknown" is intentionally ABSENT: an unclassifiable file is treated as
+ * touching EVERY angle's surface (fail-closed), so it never appears here.
+ *
+ * RENAME_ONLY is not a file kind — a renamed file still classifies by its
+ * destination path's kind, so the destination kind's own categories already
+ * implicate the right angles (a renamed code file -> code -> LOGIC_CHANGE, a
+ * renamed doc -> docs -> DOCS_ONLY). Folding RENAME_ONLY into every kind would
+ * over-attribute code angles to a doc-only delta and defeat the primary
+ * carry-forward case, so it is deliberately omitted here. A destination-kind
+ * classification alone, though, misses what the RENAME itself implicates (a
+ * moved doc can break a link; a moved test/code file shifts scope /
+ * contract-surface). Rename detection therefore lives at the DELTA layer: the
+ * CLI notices any rename/copy row and forces {@link RENAME_ONLY_ANGLES} to
+ * re-run for that run (fail-closed), instead of encoding a phantom "rename" file
+ * kind here.
+ *
+ * @type {Record<string, string[]>}
+ */
+const KIND_TO_CATEGORIES = {
+  docs: ["DOCS_ONLY"],
+  config: ["CONFIG_ONLY"],
+  test: ["TEST_ONLY"],
+  ci: ["CI_ONLY"],
+  code: ["LOGIC_CHANGE", "COMMENT_ONLY"],
+};
+
+/**
+ * The angles a pure rename implicates (CATEGORY_ANGLE_MAP[RENAME_ONLY]), minus
+ * any always-run angle (already never carried). A delta containing ANY rename
+ * forces these to re-run — a rename's effect (moved doc breaking a link, moved
+ * test/code shifting scope/contract-surface) is not captured by classifying the
+ * destination path alone. Derived from the single source of truth so it never
+ * drifts from the dynamic-angle rules.
+ *
+ * @type {string[]}
+ */
+export const RENAME_ONLY_ANGLES = (CATEGORY_ANGLE_MAP.RENAME_ONLY ?? []).filter(
+  (angle) => !ALWAYS_INCLUDE.has(angle),
+);
+
+/**
+ * angle -> Set<surface kind>: an angle's review surface is the set of file kinds
+ * whose change could implicate it, inverted from CATEGORY_ANGLE_MAP via
+ * KIND_TO_CATEGORIES. Built once at module load. ALWAYS_INCLUDE angles are NOT
+ * given a kinds surface here — they always re-run (handled in angleReviewSurface).
+ *
+ * @type {Map<string, Set<string>>}
+ */
+const ANGLE_SURFACE_KINDS = (() => {
+  const map = new Map();
+  for (const [kind, categories] of Object.entries(KIND_TO_CATEGORIES)) {
+    for (const category of categories) {
+      for (const angle of CATEGORY_ANGLE_MAP[category] ?? []) {
+        if (ALWAYS_INCLUDE.has(angle)) continue;
+        if (!map.has(angle)) map.set(angle, new Set());
+        map.get(angle).add(kind);
+      }
+    }
+  }
+  return map;
+})();
+
+/**
+ * @typedef {{ kind: "always" }
+ *   | { kind: "unknown" }
+ *   | { kind: "kinds", kinds: Set<string> }} AngleReviewSurface
+ */
+
+/**
+ * Resolve an angle's declared review surface (the pure angle -> surface mapping).
+ *
+ * - ALWAYS_INCLUDE angles (gate-evidence, renderer-security, pr-description) plus
+ *   any explicit alwaysRerun angle -> `{ kind: "always" }`. These review a surface
+ *   we cannot fully bound from the file delta alone (e.g. pr-description also
+ *   depends on the PR body, which is not a changed FILE), so they NEVER carry
+ *   forward.
+ * - A mapped angle -> `{ kind: "kinds", kinds }` (the file kinds that implicate it).
+ * - An unmapped / unknown angle -> `{ kind: "unknown" }` (fail-closed: never carry).
+ *
+ * @param {string} angle
+ * @param {{ alwaysRerun?: Iterable<string> }} [options]
+ * @returns {AngleReviewSurface}
+ */
+export function angleReviewSurface(angle, { alwaysRerun } = {}) {
+  const name = typeof angle === "string" ? angle.trim() : "";
+  if (name.length === 0) return { kind: "unknown" };
+  if (ALWAYS_INCLUDE.has(name)) return { kind: "always" };
+  if (alwaysRerun && new Set(alwaysRerun).has(name)) return { kind: "always" };
+  const kinds = ANGLE_SURFACE_KINDS.get(name);
+  if (!kinds || kinds.size === 0) return { kind: "unknown" };
+  return { kind: "kinds", kinds: new Set(kinds) };
+}
+
+/**
+ * Pure, deterministic, FAIL-CLOSED carry-forward decision for a single angle.
+ *
+ * Given a prior CLEAN verdict recorded at head A, the changed files of the delta
+ * A..B, and the angle's declared review surface, decide whether the clean verdict
+ * may be carried forward to head B (carryForward: true) or the angle MUST re-run
+ * (carryForward: false). Defaults to must-re-run in every uncertain case.
+ *
+ * @param {object} input
+ * @param {string} input.angle
+ * @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).
+ * @param {string} input.prevVerdict — the angle's verdict at head A. Only "clean"
+ *   is carry-forward-eligible.
+ * @returns {{ carryForward: boolean, reason: string }}
+ */
+export function resolveAngleCarryForward({ angle, angleSurface, changedFiles, prevVerdict }) {
+  if (prevVerdict !== "clean") {
+    return { carryForward: false, reason: `prior verdict is ${JSON.stringify(prevVerdict ?? null)}, not "clean"` };
+  }
+  const surface = angleSurface ?? angleReviewSurface(angle);
+  if (surface.kind === "always") {
+    return { carryForward: false, reason: "angle always re-runs (mandatory / always-include surface)" };
+  }
+  if (surface.kind === "unknown") {
+    return { carryForward: false, reason: "angle has no declared review surface (fail-closed)" };
+  }
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) {
+    return { carryForward: false, reason: "delta is empty or unavailable (fail-closed)" };
+  }
+  for (const file of changedFiles) {
+    const kind = classifyFile(file);
+    if (kind === "unknown") {
+      return { carryForward: false, reason: `delta contains an unclassifiable file (fail-closed): ${file}` };
+    }
+    if (surface.kinds.has(kind)) {
+      return { carryForward: false, reason: `delta touches the angle's review surface (${kind}): ${file}` };
+    }
+  }
+  return {
+    carryForward: true,
+    reason: `delta is provably outside the angle's review surface (surface kinds: ${[...surface.kinds].sort().join(", ")})`,
+  };
+}
+
+/**
+ * Convenience: partition a set of previously-clean angles into those that may be
+ * carried forward and those that must re-run, given the delta A..B. Each entry
+ * carries the decision reason. Non-clean angles are not carry-forward-eligible and
+ * belong in the re-run set — callers should pass only angles whose prior verdict
+ * was clean, or set `prevVerdict` per angle via the single-angle function.
+ *
+ * @param {object} input
+ * @param {string[]} input.prevAngles — angles that were clean at head A
+ * @param {string[]} input.changedFiles — delta A..B
+ * @param {{ alwaysRerun?: Iterable<string> }} [input.options]
+ * @returns {{ carried: Array<{ angle: string, reason: string }>, mustRerun: Array<{ angle: string, reason: string }> }}
+ */
+export function resolveCarryForwardAngles({ prevAngles, changedFiles, options = {} }) {
+  const carried = [];
+  const mustRerun = [];
+  for (const angle of Array.isArray(prevAngles) ? prevAngles : []) {
+    const decision = resolveAngleCarryForward({
+      angle,
+      angleSurface: angleReviewSurface(angle, options),
+      changedFiles,
+      prevVerdict: "clean",
+    });
+    (decision.carryForward ? carried : mustRerun).push({ angle, reason: decision.reason });
+  }
+  return { carried, mustRerun };
+}
+
+/**
+ * The file surface kinds the external Copilot code review actually reviews. Docs
+ * and comment-only prose are NOT part of it; everything a Copilot review could
+ * legitimately raise a code nit about is (code, tests, config, CI).
+ * @type {Set<string>}
+ */
+const COPILOT_REVIEW_SURFACE_KINDS = new Set(["code", "test", "config", "ci"]);
+
+/**
+ * AC2, fail-closed: decide whether a post-convergence head bump may carry forward
+ * a settled clean Copilot convergence instead of forcing a fresh BLOCKING Copilot
+ * round. Carries forward ONLY when the delta since the converged head is provably
+ * outside Copilot's review surface — a pure doc/prose-only bump (every changed
+ * file classifies as `docs`; a code comment-only change classifies as `code` and
+ * 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).
+ *
+ * @param {object} input
+ * @param {string[]} input.changedFiles — delta since the converged head
+ * @returns {{ carryForward: boolean, reason: string }}
+ */
+export function resolveConvergenceCarryForward({ changedFiles }) {
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) {
+    return { carryForward: false, reason: "delta is empty or unavailable (fail-closed)" };
+  }
+  for (const file of changedFiles) {
+    const kind = classifyFile(file);
+    if (kind === "unknown") {
+      return { carryForward: false, reason: `delta contains an unclassifiable file (fail-closed): ${file}` };
+    }
+    if (COPILOT_REVIEW_SURFACE_KINDS.has(kind)) {
+      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" };
+}

package/src/loop/handoff-envelope.mjs

@@ -44,6 +44,13 @@ const STRATEGY_DEFAULT_STOP_RULES = Object.freeze({
   [INTERNAL_DEV_LOOP_STRATEGY.WAIT_WATCH]: ["merge"],
   [INTERNAL_DEV_LOOP_STRATEGY.FINAL_APPROVAL]: ["merge"],
   [INTERNAL_DEV_LOOP_STRATEGY.LOCAL_IMPLEMENTATION]: [],
+  [INTERNAL_DEV_LOOP_STRATEGY.UI_REVIEW]: [
+    "no-product-code-writes",
+    "worktree-only",
+    "outward-review-pending",
+    "ack-destructive-migrations",
+    "merge",
+  ],
 });
 
 // ---------------------------------------------------------------------------
@@ -134,6 +141,26 @@ register(INTERNAL_DEV_LOOP_STRATEGY.WAIT_WATCH, "default", {
   activeNoticeAfterMs: WATCH_ACTIVE_NOTICE_MS,
 });
 
+// ui_review — running-app review sibling of reviewer/fixer. Scaffold slice:
+// self-validation only, no drive/report/provision/boot logic. The criteria
+// capture the route-specific review boundaries (no product-code writes,
+// worktree isolation, outward review stays pending/draft, destructive
+// migrations acknowledged before running) so the dispatched agent self-checks
+// them; the generic finalization stop rules (e.g. merge) are layered on
+// separately and are not restated here.
+register(INTERNAL_DEV_LOOP_STRATEGY.UI_REVIEW, "default", {
+  criteria: [
+    { id: "no-product-code-writes", must: "No product code is written; the UI-review route only observes and reports on the running app.", severity: "required" },
+    { id: "worktree-only", must: "All work stays inside the isolated worktree; nothing is written outside it.", severity: "required" },
+    { id: "outward-review-pending", must: "Any outward review stays pending/draft; no approval or merge is emitted from the UI-review route.", severity: "required" },
+    { id: "ack-destructive-migrations", must: "Destructive migrations are explicitly acknowledged before they are run.", severity: "required" },
+  ],
+  evidence: ["commands-run", "validation-output"],
+  maxFinalizationTurns: 4,
+  needsAttentionAfterMs: DEFAULT_NEEDS_ATTENTION_MS,
+  activeNoticeAfterMs: DEFAULT_ACTIVE_NOTICE_MS,
+});
+
 // Remaining strategies get a generic acceptance template
 function registerGeneric(strategy) {
   register(strategy, "default", {

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

@@ -29,6 +29,15 @@ export const REFINEMENT_SOURCE = Object.freeze({
 
 const REFINEMENT_ARTIFACT_FINDING = "missing_refinement_artifact";
 
+// The three artifact sources, any ONE of which satisfies the refinement gate.
+// Single source of truth for the "missing" vocabulary reported when none is
+// present — consumed by the enqueue gate and the parked-unrefined discovery.
+export const REFINEMENT_ARTIFACT_SOURCES = Object.freeze([
+  "Acceptance criteria section",
+  "Definition of done section",
+  "linked refinement doc",
+]);
+
 /**
  * Canonical list of section headings that satisfy the refinement check.
  * Matching is case-insensitive and tolerates trailing/leading whitespace.
@@ -524,11 +533,7 @@ export function decideEnqueueRefinementGate({ artifact, targetIsPickup, auto = f
   if (!targetIsPickup || artifact.finding === null) {
     return { action: "enqueue" };
   }
-  const missing = [
-    "Acceptance criteria section",
-    "Definition of done section",
-    "linked refinement doc",
-  ];
+  const missing = [...REFINEMENT_ARTIFACT_SOURCES];
   const reason =
     `Issue has no refinement artifact (none of: ${missing.join(", ")}). ` +
     "Add at least ONE of them — an Acceptance criteria section, a Definition of done section, or a linked refinement doc " +

package/src/loop/policy-constants.mjs

@@ -12,6 +12,3 @@ export const COPILOT_FIRST_DURABLE_WAIT_TIMEOUT_MS = 3_600_000;
 
 /** Copilot review wait: external healthy-wait budget */
 export const COPILOT_REVIEW_WAIT_TIMEOUT_MS = 1_800_000;
-
-/** Explicit single-check timeout value (used only for status probes) */
-export const PROBE_ONLY_TIMEOUT_MS = 0;

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

@@ -660,6 +660,11 @@ function evaluatePrGateCoordinationCore(input = {}) {
   const conflictFiles = normalizeConflictFiles(input.conflictFiles);
   const ciStatus = normalizeCiStatus(input.ciStatus);
   const draftGateRequireCi = input.draftGateRequireCi !== false;
+  // Opt-out CI precondition at the pre-approval boundary (mirrors the draft
+  // gate). Default true keeps CI required; false ignores the CI verdict
+  // entirely — a "none"/"pending"/"crediblyGreen"/"failure" head no longer
+  // waits on or blocks pre_approval.
+  const preApprovalRequireCi = input.preApprovalRequireCi !== false;
   const copilotReviewRoundCount = normalizeNonNegativeInteger(input.copilotReviewRoundCount);
   const maxCopilotRounds = normalizePositiveInteger(input.maxCopilotRounds);
   const roundCapReached = isCopilotRoundCapReached({ copilotReviewRoundCount, maxCopilotRounds });
@@ -998,7 +1003,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
   if (effectiveLifecycleState === STATE.PR_READY_NO_FEEDBACK) {
     if (reviewMode === "internal_only") {
       // Explicitly internal-only PR: skip the external Copilot review cycle
-      if (ciStatus === "failure" || ciStatus === "crediblyGreen") {
+      if (preApprovalRequireCi && (ciStatus === "failure" || ciStatus === "crediblyGreen")) {
         pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
         pushUnique(forbiddenActions, internalOnlyPostDraftForbidden);
         return buildResult({
@@ -1201,7 +1206,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
   }
 
   if (effectiveLifecycleState === STATE.READY_TO_REREQUEST_REVIEW) {
-    if (ciStatus === "failure" || ciStatus === "crediblyGreen") {
+    if (preApprovalRequireCi && (ciStatus === "failure" || ciStatus === "crediblyGreen")) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
       pushUnique(forbiddenActions, postDraftForbidden);
       return buildResult({
@@ -1226,7 +1231,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
       });
     }
 
-    if (ciStatus === "pending" || ciStatus === "none") {
+    if (preApprovalRequireCi && (ciStatus === "pending" || ciStatus === "none")) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.WAIT_FOR_CI]);
       pushUnique(forbiddenActions, postDraftForbidden);
       return buildResult({
@@ -1410,7 +1415,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
         copilotReviewRoundCount,
       });
     }
-    if (ciStatus === "failure" || ciStatus === "crediblyGreen") {
+    if (preApprovalRequireCi && (ciStatus === "failure" || ciStatus === "crediblyGreen")) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
       pushUnique(forbiddenActions, postDraftForbidden);
       return buildResult({
@@ -1434,7 +1439,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
           refinementArtifact,
       });
     }
-    if (ciStatus === "pending" || ciStatus === "none") {
+    if (preApprovalRequireCi && (ciStatus === "pending" || ciStatus === "none")) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.WAIT_FOR_CI]);
       pushUnique(forbiddenActions, postDraftForbidden);
       return buildResult({
@@ -1553,7 +1558,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
   }
 
   if (effectiveLifecycleState === STATE.LOW_SIGNAL_CONVERGED) {
-    if (ciStatus === "failure" || ciStatus === "crediblyGreen") {
+    if (preApprovalRequireCi && (ciStatus === "failure" || ciStatus === "crediblyGreen")) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
       pushUnique(forbiddenActions, postDraftForbidden);
       return buildResult({
@@ -1577,7 +1582,7 @@ function evaluatePrGateCoordinationCore(input = {}) {
           refinementArtifact,
       });
     }
-    if (ciStatus === "pending" || ciStatus === "none") {
+    if (preApprovalRequireCi && (ciStatus === "pending" || ciStatus === "none")) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.WAIT_FOR_CI]);
       pushUnique(forbiddenActions, postDraftForbidden);
       return buildResult({

package/src/loop/public-dev-loop-routing-contract.mjs

@@ -23,6 +23,7 @@ export const DEV_LOOP_PUBLIC_INTENT = Object.freeze({
   CONTINUE_CURRENT: "continue_current",
   AUTO_CONTINUE_CURRENT: "auto_continue_current",
   INSPECT_STATE: "inspect_state",
+  REVIEW_PR_UI: "review_pr_ui",
 });
 
 export const DEV_LOOP_TARGET_KIND = Object.freeze({
@@ -76,6 +77,7 @@ export const DEV_LOOP_GATE = Object.freeze({
   EXTERNAL_PR_FOLLOWUP: "external_pr_followup",
   REVIEWER_FIXER: "reviewer_fixer",
   COPILOT_PR_FOLLOWUP: "copilot_pr_followup",
+  UI_REVIEW: "ui_review",
   FAIL_CLOSED_RECONCILE: "fail_closed_reconcile",
 });
 
@@ -87,6 +89,7 @@ export const INTERNAL_DEV_LOOP_STRATEGY = Object.freeze({
   REVIEWER_FIXER: "reviewer_fixer",
   WAIT_WATCH: "wait_watch",
   FINAL_APPROVAL: "final_approval",
+  UI_REVIEW: "ui_review",
   NONE: null,
 });
 
@@ -267,6 +270,12 @@ export const PUBLIC_DEV_LOOP_GATE_CONTRACT = Object.freeze([
     selectedStrategy: INTERNAL_DEV_LOOP_STRATEGY.COPILOT_PR_FOLLOWUP,
     summary: "Copilot-owned PR state routes to Copilot PR follow-up; an already-linked open PR stays the canonical artifact for that issue until reconciled",
   }),
+  Object.freeze({
+    gate: DEV_LOOP_GATE.UI_REVIEW,
+    routeKind: DEV_LOOP_ROUTE_KIND.ROUTE,
+    selectedStrategy: INTERNAL_DEV_LOOP_STRATEGY.UI_REVIEW,
+    summary: "an explicit UI-review request on a PR target routes to the ui_review running-app review strategy",
+  }),
   Object.freeze({
     gate: DEV_LOOP_GATE.FAIL_CLOSED_RECONCILE,
     routeKind: DEV_LOOP_ROUTE_KIND.NEEDS_RECONCILE,

package/src/loop/public-dev-loop-routing.mjs

@@ -461,7 +461,7 @@ function toRoutableCanonicalState(canonicalState) {
   };
 }
 
-function selectGateForState(canonicalState) {
+function selectGateForState(canonicalState, { uiReviewRequested = false } = {}) {
   if (canonicalState.status === DEV_LOOP_STATUS.BLOCKED || canonicalState.authorization === DEV_LOOP_AUTHORIZATION.NOT_AUTHORIZED) {
     return DEV_LOOP_GATE.STOP_BLOCKED_OR_NOT_AUTHORIZED;
   }
@@ -499,6 +499,15 @@ function selectGateForState(canonicalState) {
     return DEV_LOOP_GATE.ISSUE_INTAKE;
   }
 
+  // An explicit UI-review request intercepts a PR target ahead of the
+  // ownership-derived PR gates: the running-app review is requested regardless
+  // of who owns the PR. It stays after the authoritative lifecycle stop/terminal/
+  // approval/waiting gates so it can never bypass them. Absent the signal this
+  // branch is inert, so existing routes stay byte-identical.
+  if (uiReviewRequested && canonicalState.target.kind === DEV_LOOP_TARGET_KIND.PR) {
+    return DEV_LOOP_GATE.UI_REVIEW;
+  }
+
   if (canonicalState.target.kind === DEV_LOOP_TARGET_KIND.PR && canonicalState.ownership === DEV_LOOP_ACTOR.EXTERNAL_HUMAN) {
     return DEV_LOOP_GATE.EXTERNAL_PR_FOLLOWUP;
   }
@@ -581,10 +590,11 @@ function routeForState(
     issueAssignmentState = null,
     gateReviewEvidence = null,
     targetPreference = null,
+    uiReviewRequested = false,
   } = {},
 ) {
   const routableCanonicalState = toRoutableCanonicalState(canonicalState);
-  const selectedGate = selectGateForState(routableCanonicalState);
+  const selectedGate = selectGateForState(routableCanonicalState, { uiReviewRequested });
   if (
     selectedGate === DEV_LOOP_GATE.FINAL_APPROVAL
     && routableCanonicalState.target.kind === DEV_LOOP_TARGET_KIND.PR
@@ -763,6 +773,18 @@ function routeForState(
     });
   }
 
+  if (selectedGate === DEV_LOOP_GATE.UI_REVIEW) {
+    return buildResult({
+      selectedGate,
+      routeKind: DEV_LOOP_ROUTE_KIND.ROUTE,
+      selectedStrategy: INTERNAL_DEV_LOOP_STRATEGY.UI_REVIEW,
+      executionMode,
+      canonicalState: routableCanonicalState,
+      nextAction: "Run the UI-review route for the current PR: prove the change in the running app from an isolated worktree. Do not write product code; keep any outward review pending/draft; acknowledge destructive migrations before running them.",
+      reason: "An explicit UI-review request on a PR target routes to the ui_review strategy — the running-app review sibling of the reviewer/fixer route.",
+    });
+  }
+
   return buildReconcile(
     "The canonical current state does not map cleanly to any first-slice internal strategy.",
     routableCanonicalState,
@@ -1171,6 +1193,7 @@ export function resolveAuthoritativeStartupResumeBundle(input = {}) {
     issueAssignmentState,
     gateReviewEvidence,
     targetPreference,
+    uiReviewRequested: intent === DEV_LOOP_PUBLIC_INTENT.REVIEW_PR_UI,
   });
   if (routed.routeKind === DEV_LOOP_ROUTE_KIND.NEEDS_RECONCILE) {
     return buildStartupResumeBundleReconcile({
@@ -1703,6 +1726,23 @@ export function evaluatePublicDevLoopRouting(input = {}) {
     ));
   }
 
+  if (intent === DEV_LOOP_PUBLIC_INTENT.REVIEW_PR_UI) {
+    if (!explicitTarget || explicitTarget.kind !== DEV_LOOP_TARGET_KIND.PR) {
+      return buildInputReconcile("`review_pr_ui` requires a PR target.", null, effectiveMode);
+    }
+    if (!explicitState || explicitState.target.kind !== DEV_LOOP_TARGET_KIND.PR) {
+      return buildInputReconcile("`review_pr_ui` requires a valid canonical PR state.", explicitState, effectiveMode);
+    }
+    if (explicitState.target.pr !== explicitTarget.pr) {
+      return buildInputReconcile("`review_pr_ui` target conflicts with the canonical current PR state.", explicitState, effectiveMode);
+    }
+
+    return finalizeRoutingResult(applyWatchValidation(
+      routeForState(explicitState, { ...routingOptions, executionMode: effectiveMode, uiReviewRequested: true }),
+      watchRequested,
+    ));
+  }
+
   if (intent === DEV_LOOP_PUBLIC_INTENT.CONTINUE_CURRENT) {
     if (!explicitState) {
       return buildInputReconcile("`continue_current` requires a valid canonical current state.", null, effectiveMode);

package/src/loop/queue-state.mjs

@@ -285,12 +285,3 @@ export function appendBugIssue(queue, issueNumber, dependsOn = null) {
   queue.entries.push(entry);
   return entry;
 }
-
-// ── Serialization helpers ────────────────────────────────────────────
-
-export function serializeQueue(queue) {
-  return {
-    version: queue.version,
-    entries: queue.entries.map((e) => ({ ...e })),
-  };
-}

package/src/loop/steering.mjs

@@ -718,10 +718,12 @@ export function getEffectiveConstraints(steeringState) {
  *
  * @param {object} snapshot - raw or normalized loop snapshot
  * @param {object} steeringState - current steering state for this run
+ * @param {object} [refinementConfig] - interpreter refinement config; pass a config-derived
+ *   `resolveRefinement(config)` so the base interpretation honors gates.preApproval.requireCi:false (#1337).
  * @returns {{ state: string, allowedTransitions: string[], nextAction: string, steeringApplied: boolean, pendingStopAtNextSafeGate: boolean, terminalStopAtNextSafeGate: boolean, effectiveConstraints: object }}
  */
-export function resolveEffectiveLoopState(snapshot, steeringState) {
-  const base = interpretLoopState(snapshot);
+export function resolveEffectiveLoopState(snapshot, steeringState, refinementConfig) {
+  const base = interpretLoopState(snapshot, refinementConfig);
   const constraints = getEffectiveConstraints(steeringState);
   const category = classifySafePoint(base.state);