@dev-loops/core 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -57,6 +57,11 @@
     "./loop/timeout-policy": "./src/loop/timeout-policy.mjs",
     "./loop/tracker-pr-state": "./src/loop/tracker-pr-state.mjs",
     "./loop/ui-e2e-scoping": "./src/loop/ui-e2e-scoping.mjs",
+    "./loop/ui-review-provision": "./src/loop/ui-review-provision.mjs",
+    "./loop/ui-review-drive": "./src/loop/ui-review-drive.mjs",
+    "./loop/ui-review-diagnose": "./src/loop/ui-review-diagnose.mjs",
+    "./loop/ui-review-report": "./src/loop/ui-review-report.mjs",
+    "./loop/ui-review-teardown": "./src/loop/ui-review-teardown.mjs",
     "./projects/list-queue-items": "./src/projects/list-queue-items.mjs",
     "./projects/move-queue-item": "./src/projects/move-queue-item.mjs",
     "./projects/resolve-project": "./src/projects/resolve-project.mjs",

package/src/claude/asset-generation.mjs

@@ -88,6 +88,28 @@ export function rewriteCliInvocation(body, version) {
   return String(body).split("node <dev-loops-package-root>/cli/index.mjs").join(`npx dev-loops@${version}`);
 }
 
+/**
+ * Rewrite repo-root `../docs/…` *inline* markdown links `](../docs/…)` in a generated *command*
+ * body so they resolve from the generated file's deeper location. Only the inline `](…)` link form
+ * is rewritten (reference-style `[label]: …` and HTML `<a href>` links are left as-is) — command
+ * bodies only use inline links, so that is the sole form that occurs. Source commands live at
+ * `commands/<name>.command.md`, so `../docs/x` resolves to repo-root `docs/x`; the generated
+ * wrapper lives one level deeper at `.claude/commands/<name>.md`, where `../docs/x` would wrongly
+ * resolve to `.claude/docs/x` (there is no such dir). Repo-root `docs/` is NOT mirrored into
+ * `.claude/`, so the link must gain one `../` to reach repo-root: `../docs/x` → `../../docs/x`.
+ *
+ * Scoped to `../docs/` on purpose. Other `../…` command links point at subtrees the generator
+ * mirrors under `.claude/` (e.g. `../skills/docs/x` → the bundled `.claude/skills/docs/x`), whose
+ * relative depth is preserved verbatim — shifting those would break them. Skills need no rewrite
+ * at all for the same reason (their `../docs/x` targets the bundled `.claude/skills/docs/x`).
+ *
+ * @param {string} body
+ * @returns {string}
+ */
+export function rewriteCommandRepoLinks(body) {
+  return String(body).replace(/(\]\(<?)(\.\.\/docs\/)/g, "$1../$2");
+}
+
 /**
  * Map a single Pi tool name to its Claude tool name(s).
  * @param {string} name
@@ -180,7 +202,7 @@ export function transformAgent({ source, raw, version = "latest" }) {
  */
 export function transformCommand({ source, raw, version = "latest" }) {
   const { frontmatter, body: rawBody } = splitFrontmatter(raw, source);
-  const body = rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version);
+  const body = rewriteCommandRepoLinks(rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version));
 
   const lines = ["---"];
   if (frontmatter.description != null) {

package/src/config/config.mjs

@@ -178,6 +178,179 @@ const WorktreeConfig = z.strictObject({
   linkOnInit: z.array(z.string().trim().min(1)).optional(),
 });
 
+/**
+ * Dev-DB migration sub-recipe for the ui-review run recipe. `statusCommand`
+ * lists pending migrations (one per line); `applyCommand` applies them.
+ *
+ * Destructive detection is EXPLICIT and status-format-dependent: the
+ * `destructivePattern` regex is matched (case-insensitive, per line) against the
+ * STATUS OUTPUT — not against the migration files. The shipped default
+ * (DEFAULT_DESTRUCTIVE_MIGRATION_PATTERN) assumes SQL-bearing status output
+ * (DROP/TRUNCATE/DELETE FROM ...); against a status command that emits migration
+ * identifiers or filenames instead, it matches nothing and the destructive guard
+ * is inert. A project whose status output is NOT SQL therefore MUST set a
+ * `destructivePattern` that matches its own status format (e.g. a `destructive`/
+ * `down` marker), or make `statusCommand` emit the destructive SQL/marker — the
+ * default cannot detect what its status output never prints.
+ */
+const UiReviewMigrateConfig = z.strictObject({
+  statusCommand: z.string().trim().min(1),
+  applyCommand: z.string().trim().min(1),
+  destructivePattern: z
+    .string()
+    .trim()
+    .min(1)
+    .refine((p) => {
+      try {
+        // Validate under the exact flags the runtime compile uses at the
+        // destructive-migration safety boundary (inspectMigrations), so a
+        // pattern valid bare but invalid under `u` is rejected at load time.
+        new RegExp(p, "iu");
+        return true;
+      } catch {
+        return false;
+      }
+    }, "destructivePattern must be a valid regex")
+    .optional(),
+});
+
+/**
+ * Per-project boot recipe: a shell `command` that starts the branch's app and a
+ * `readyUrl` an HTTP readiness probe polls until the app is up (never a fixed
+ * sleep). No app is hard-coded — a project declares its own recipe. `cwd` is an
+ * optional worktree-relative subdir to run in.
+ */
+const UiReviewRunConfig = z.strictObject({
+  command: z.string().trim().min(1),
+  readyUrl: z
+    .string()
+    .trim()
+    .url()
+    .refine((u) => {
+      try {
+        const p = new URL(u).protocol;
+        return p === "http:" || p === "https:";
+      } catch {
+        return false;
+      }
+    }, "readyUrl must be an http(s) URL"),
+  readyTimeoutMs: z.number().int().min(1).max(600000).default(60000),
+  readyIntervalMs: z.number().int().min(1).max(60000).default(1000),
+  cwd: z.string().trim().min(1).optional(),
+  migrate: UiReviewMigrateConfig.optional(),
+});
+
+/**
+ * Per-project dev-login recipe (Stage 2). The drive stage obtains a session for
+ * the change's target role by driving this login form in the browser. Nothing
+ * is hard-coded here — a project declares its own login URL, field selectors,
+ * and the shared dev credential (never a real user secret; a dev-only password
+ * or role). `successSelector` is what proves the session was established;
+ * without it the drive stage cannot confirm auth and fails closed.
+ */
+const UiReviewLoginConfig = z.strictObject({
+  loginUrl: z
+    .string()
+    .trim()
+    .url()
+    .refine((u) => {
+      try {
+        const p = new URL(u).protocol;
+        return p === "http:" || p === "https:";
+      } catch {
+        return false;
+      }
+    }, "loginUrl must be an http(s) URL"),
+  usernameSelector: z.string().trim().min(1).optional(),
+  usernameValue: z.string().min(1).optional(),
+  passwordSelector: z.string().trim().min(1).optional(),
+  passwordValue: z.string().min(1).optional(),
+  submitSelector: z.string().trim().min(1),
+  successSelector: z.string().trim().min(1),
+});
+
+/** A config-declared interstitial (cookie consent etc.) dismissed ONCE per
+ * browser context. */
+const UiReviewInterstitialConfig = z.strictObject({
+  selector: z.string().trim().min(1),
+});
+
+/** One driven step. The action set is deliberately small and maps 1:1 to a
+ * Playwright page call in the harness — enough to render a page and exercise the
+ * create/edit/reorder/upload/toggle interactions plus dispatch a real event. */
+const UiReviewFlowStepConfig = z.strictObject({
+  name: z.string().trim().min(1).optional(),
+  action: z.enum(["goto", "click", "fill", "select", "upload", "dispatch"]),
+  selector: z.string().trim().min(1).optional(),
+  path: z.string().trim().min(1).optional(),
+  value: z.string().optional(),
+  event: z.string().trim().min(1).optional(),
+}).superRefine((step, ctx) => {
+  // Every action but `goto` targets an element, so a missing selector is a
+  // config error, not a runtime step-failure. (`goto` uses `path`/url.)
+  if (step.action !== "goto" && (step.selector == null || step.selector.trim().length === 0)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["selector"], message: `step action "${step.action}" requires a selector` });
+  }
+  // Action-specific required fields. Rejecting these at parse time turns a silent
+  // wrong drive into a clear config error: a missing `goto.path` would drive "/",
+  // and a missing `upload.value` becomes setInputFiles(sel, "") which throws mid
+  // walk as a step-failure rather than a config problem.
+  if (step.action === "goto" && (step.path == null || step.path.trim().length === 0)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["path"], message: `step action "goto" requires a path` });
+  }
+  if (step.action === "upload" && (step.value == null || step.value.trim().length === 0)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["value"], message: `step action "upload" requires a value (the file path to upload)` });
+  }
+});
+
+/** An allowlisted changed flow. `pathPatterns` are plain substrings matched
+ * against the PR's changed file paths to decide whether the flow is in scope
+ * (the bounded changed-flow heuristic); a flow with none is always driven. */
+const UiReviewFlowConfig = z.strictObject({
+  name: z.string().trim().min(1),
+  pathPatterns: z.array(z.string().trim().min(1)).optional(),
+  steps: z.array(UiReviewFlowStepConfig).min(1),
+});
+
+/** Bounded drive caps (Stage 2). Every field is optional and clamped to a
+ * ceiling at resolve time — a project may only tighten a cap, never loosen it. */
+const UiReviewCapsConfig = z.strictObject({
+  maxScreenshots: z.number().int().min(1).optional(),
+  maxFlows: z.number().int().min(1).optional(),
+  maxStepsPerFlow: z.number().int().min(1).optional(),
+});
+
+/**
+ * UI-review route config: the generic, per-project provision+boot recipe (Stage
+ * 1) plus the drive recipe (Stage 2: login, interstitials, changed-flow
+ * allowlist, and an optional server-log path/pattern for tailing). Absent (the
+ * default) means no recipe is declared — the corresponding stage stops with that
+ * as a stated reason rather than guessing how to run or drive the app.
+ */
+const UiReviewConfig = z.strictObject({
+  run: UiReviewRunConfig.optional(),
+  login: UiReviewLoginConfig.optional(),
+  interstitials: z.array(UiReviewInterstitialConfig).optional(),
+  flows: z.array(UiReviewFlowConfig).optional(),
+  caps: UiReviewCapsConfig.optional(),
+  // Filesystem path (worktree-relative or absolute) to the project's server log.
+  // The drive stage tails it so a swallowed 500 the UI hid is still recorded.
+  serverLogPath: z.string().trim().min(1).optional(),
+  serverLogExceptionPattern: z
+    .string()
+    .trim()
+    .min(1)
+    .refine((p) => {
+      try {
+        new RegExp(p, "iu");
+        return true;
+      } catch {
+        return false;
+      }
+    }, "serverLogExceptionPattern must be a valid regex")
+    .optional(),
+});
+
 /** Internal path whitelist for internal-only PR detection — flat array of regex strings */
 const InternalPatternsConfig = z.array(z.string().trim().min(1)).min(1);
 
@@ -232,6 +405,7 @@ export const DevLoopConfigSchema = z.strictObject({
   personas: PersonasConfig.optional(),
   internalPathPatterns: InternalPatternsConfig.optional(),
   worktree: WorktreeConfig.optional(),
+  uiReview: UiReviewConfig.optional(),
   // Deprecated (removed in #1088): tolerated so consumer .devloops files that
   // still carry a localPlanning block keep parsing. Accepted, never read.
   localPlanning: z.unknown().optional(),
@@ -304,6 +478,7 @@ export const FileConfigSchema = z.strictObject({
   personas: FilePersonasConfig.optional(),
   internalPathPatterns: InternalPatternsConfig.optional(),
   worktree: WorktreeConfig.partial().optional(),
+  uiReview: UiReviewConfig.partial().optional(),
   // Deprecated (removed in #1088): tolerated so consumer .devloops files that
   // still carry a localPlanning block keep parsing. Accepted, never read.
   localPlanning: z.unknown().optional(),
@@ -1385,6 +1560,108 @@ export function resolveWorktreeConfig(config) {
   return { copyOnInit: list(wt?.copyOnInit), linkOnInit: list(wt?.linkOnInit) };
 }
 
+/**
+ * Default destructive-migration signal: SQL statements that drop or wipe data.
+ * Matched (case-insensitive, per line) against the migration STATUS OUTPUT. This
+ * default only detects destructive intent when the status output is itself
+ * SQL-bearing; against status output that lists migration identifiers/filenames
+ * it matches nothing and the guard is inert (no false positives, but also no
+ * protection). Such a project MUST override via
+ * `uiReview.run.migrate.destructivePattern` to match its own status format (or
+ * emit the destructive SQL/marker from `statusCommand`).
+ */
+export const DEFAULT_DESTRUCTIVE_MIGRATION_PATTERN =
+  "\\b(DROP\\s+(TABLE|COLUMN|DATABASE|SCHEMA)|TRUNCATE|DELETE\\s+FROM|ALTER\\s+TABLE\\s+.*\\bDROP\\b)";
+
+/**
+ * Resolve the ui-review provision+boot run recipe from the merged config.
+ *
+ * Returns null when no `uiReview.run.command` is declared — the provision+boot
+ * stage treats that as a stated stop reason (no app is ever guessed). Numeric
+ * probe bounds fall back to sane defaults defensively: zod `.partial()` is
+ * shallow (it does not drop nested numeric defaults), so a schema-validated
+ * config already carries them — the fallback covers programmatically-built
+ * config objects that bypass schema defaulting, not the `.partial()` path.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {null | { command: string, readyUrl: string, readyTimeoutMs: number,
+ *   readyIntervalMs: number, cwd: string|null,
+ *   migrate: null | { statusCommand: string, applyCommand: string, destructivePattern: string } }}
+ */
+export function resolveUiReviewRunRecipe(config) {
+  const run = config?.uiReview?.run;
+  if (!run || typeof run.command !== "string" || run.command.trim().length === 0) return null;
+  if (typeof run.readyUrl !== "string" || run.readyUrl.trim().length === 0) return null;
+  const migrate = run.migrate
+    ? {
+        statusCommand: run.migrate.statusCommand,
+        applyCommand: run.migrate.applyCommand,
+        destructivePattern: run.migrate.destructivePattern ?? DEFAULT_DESTRUCTIVE_MIGRATION_PATTERN,
+      }
+    : null;
+  return {
+    command: run.command.trim(),
+    readyUrl: run.readyUrl.trim(),
+    readyTimeoutMs: Number.isInteger(run.readyTimeoutMs) ? run.readyTimeoutMs : 60000,
+    readyIntervalMs: Number.isInteger(run.readyIntervalMs) ? run.readyIntervalMs : 1000,
+    cwd: typeof run.cwd === "string" && run.cwd.trim().length > 0 ? run.cwd.trim() : null,
+    migrate,
+  };
+}
+
+/**
+ * Default server-log exception signal for the drive stage's log tail. Matched
+ * (case-insensitive, per line) against the tailed server-log text. This is a
+ * HEURISTIC default tuned for common framework logs (a 5xx status, an
+ * uncaught/unhandled marker, an exception/traceback). A project whose log format
+ * these miss MUST override `uiReview.serverLogExceptionPattern` to match its own
+ * server log — the default cannot detect what its log never prints.
+ */
+export const DEFAULT_SERVER_LOG_EXCEPTION_PATTERN =
+  "\\b(5\\d{2}\\b|Internal Server Error|Unhandled|Uncaught|Traceback|Exception|FATAL|\\bERROR\\b)";
+
+/**
+ * Resolve the ui-review drive recipe (Stage 2) from the merged config.
+ *
+ * Returns null when no `uiReview.login` is declared — the drive stage treats
+ * that as a stated stop reason (it cannot authenticate, so it drives nothing).
+ * The server-log exception pattern falls back to the shipped heuristic default
+ * when a `serverLogPath` is set without an explicit pattern.
+ *
+ * @param {DevLoopConfig} config
+ * @returns {null | { login: object, interstitials: object[], flows: object[],
+ *   caps: object, serverLogPath: string|null, serverLogExceptionPattern: string }}
+ */
+export function resolveUiReviewDriveRecipe(config) {
+  const ui = config?.uiReview;
+  const login = ui?.login;
+  if (!login || typeof login.loginUrl !== "string" || login.loginUrl.trim().length === 0) return null;
+  if (typeof login.submitSelector !== "string" || login.submitSelector.trim().length === 0) return null;
+  if (typeof login.successSelector !== "string" || login.successSelector.trim().length === 0) return null;
+  const serverLogPath = typeof ui.serverLogPath === "string" && ui.serverLogPath.trim().length > 0 ? ui.serverLogPath.trim() : null;
+  return {
+    login: {
+      loginUrl: login.loginUrl.trim(),
+      usernameSelector: login.usernameSelector ?? null,
+      usernameValue: login.usernameValue ?? null,
+      passwordSelector: login.passwordSelector ?? null,
+      passwordValue: login.passwordValue ?? null,
+      submitSelector: login.submitSelector.trim(),
+      successSelector: login.successSelector.trim(),
+    },
+    interstitials: Array.isArray(ui.interstitials)
+      ? ui.interstitials.map((i) => ({ selector: i.selector }))
+      : [],
+    flows: Array.isArray(ui.flows) ? ui.flows : [],
+    caps: ui.caps ?? {},
+    serverLogPath,
+    serverLogExceptionPattern:
+      typeof ui.serverLogExceptionPattern === "string" && ui.serverLogExceptionPattern.trim().length > 0
+        ? ui.serverLogExceptionPattern.trim()
+        : DEFAULT_SERVER_LOG_EXCEPTION_PATTERN,
+  };
+}
+
 /**
  * Resolve the human-handoff config from the merged dev-loop config (#920).
  *

package/src/config/extension-defaults.yaml

@@ -396,7 +396,6 @@ personas:
       The PR body is the implementation contract — it must have:
       - A Summary section explaining what changed and why
       - A Scope and context section defining the boundary of the change
-      - A File-by-file changes section listing every touched file and what changed in it
       - An Acceptance criteria section with the linked issue acceptance criteria
       - A Definition of done section
       - A Non-goals section

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/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);