@dev-loops/core 0.7.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -41,6 +41,7 @@
     "./loop/pr-lifecycle": "./src/loop/pr-lifecycle.mjs",
     "./loop/pr-title-markers": "./src/loop/pr-title-markers.mjs",
     "./loop/public-dev-loop-routing": "./src/loop/public-dev-loop-routing.mjs",
+    "./loop/refinement-grill-state": "./src/loop/refinement-grill-state.mjs",
     "./loop/queue-board-ordering": "./src/loop/queue-board-ordering.mjs",
     "./loop/queue-board-sync": "./src/loop/queue-board-sync.mjs",
     "./loop/queue-driver": "./src/loop/queue-driver.mjs",
@@ -56,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/claude/hook-decisions.mjs

@@ -61,7 +61,7 @@ export const DEV_LOOP_AGENT_TYPE = "dev-loop";
  *     clean current-head draft_gate + pre_approval_gate). The loop runs this check before merging;
  *     gating it here closes the hole where a hand-run `gh pr merge` skips the pre-approval gate
  *     entirely. Everything else passes through.
- *   - raw `gh issue create` / `gh issue comment` / `gh pr comment` — blocked ONLY when the call
+ *   - raw `gh issue create` / `gh issue comment` / `gh issue edit` / `gh pr comment` — blocked ONLY when the call
  *     originates from a SUBAGENT context (`agentType` is a non-null string) and targets the repo.
  *     Sanctioned external writes flow through node wrappers (gate-verdict comments via
  *     `upsert-checkpoint-verdict.mjs`, review replies via `reply-resolve*.mjs`, board sync,
@@ -85,7 +85,7 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
     return ALLOW;
   }
   // Subagent-scoped external-write guard: block ad-hoc `gh issue create`/`gh issue comment`/
-  // `gh pr comment` on the target repo from a subagent, so external writes flow through the
+  // `gh issue edit`/`gh pr comment` on the target repo from a subagent, so external writes flow through the
   // sanctioned node wrappers. The main-agent/operator path (agentType null) is unaffected (#1051).
   if (typeof agentType === "string" && commandContainsRawExternalWrite(command)) {
     const cwdTargets = (repoSlug ?? "").toLowerCase() === TARGET_REPO_SLUG.toLowerCase();
@@ -101,9 +101,10 @@ export function decideBashGate({ command, repoSlug = null, gatePassed = false, g
       return {
         decision: "deny",
         reason:
-          "Ad-hoc GitHub issue/PR creation and comments from a subagent are blocked. Use the sanctioned " +
+          "Ad-hoc GitHub issue/PR creation, comments, and edits from a subagent are blocked. Use the sanctioned " +
           "node wrappers instead — gate-verdict comments via scripts/github/upsert-checkpoint-verdict.mjs, " +
-          "review-thread replies via scripts/github/reply-resolve*.mjs, board sync, or scripts/github/comment-issue.mjs. " +
+          "review-thread replies via scripts/github/reply-resolve*.mjs, board sync, issue comments via " +
+          "scripts/github/comment-issue.mjs, or issue-body edits via scripts/github/edit-issue.mjs. " +
           "Direct `gh issue create` is reserved for the main agent / operator.",
       };
     }

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/bash-command-classify.mjs

@@ -234,18 +234,19 @@ function extractRepoFlagsFromGhSubcmdVerbSegments(command, subcmd, verb) {
 
 /**
  * The raw external-write verb forms that must be blocked when originating from a subagent:
- * ad-hoc GitHub issue/PR creation and comments run directly via `gh` (not the sanctioned node
- * wrappers). Each entry is `[subcmd, verb]`.
+ * ad-hoc GitHub issue/PR creation, comments, and edits run directly via `gh` (not the sanctioned
+ * node wrappers). Each entry is `[subcmd, verb]`.
  */
 const EXTERNAL_WRITE_VERB_FORMS = Object.freeze([
   ["issue", "create"],
   ["issue", "comment"],
+  ["issue", "edit"],
   ["pr", "comment"],
 ]);
 
 /**
- * Whether `command` contains a raw `gh issue create`, `gh issue comment`, or `gh pr comment`
- * invocation in ANY shell segment (ignoring --help/-h). PreToolUse gate use only — the gate
+ * Whether `command` contains a raw `gh issue create`, `gh issue comment`, `gh issue edit`, or
+ * `gh pr comment` invocation in ANY shell segment (ignoring --help/-h). PreToolUse gate use only — the gate
  * blocks these when they originate from a subagent context. Node-wrapper commands
  * (`node scripts/github/comment-issue.mjs …`) never match (first token is `node`, not `gh`).
  * @param {string} command @returns {boolean}
@@ -255,8 +256,8 @@ export function commandContainsRawExternalWrite(command) {
 }
 
 /**
- * Return `{ segment, explicitRepo }` for every raw external-write segment across all three verb
- * forms (`gh issue create` / `gh issue comment` / `gh pr comment`). PreToolUse gate use only —
+ * Return `{ segment, explicitRepo }` for every raw external-write segment across all four verb
+ * forms (`gh issue create` / `gh issue comment` / `gh issue edit` / `gh pr comment`). PreToolUse gate use only —
  * lets the gate decide in-scope-ness per segment so a leading out-of-scope write can't shield a
  * later in-scope one. `explicitRepo` is the segment's `--repo`/`-R` value or null.
  * @param {string} command @returns {{ segment: string, explicitRepo: string|null }[]}

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", {
@@ -280,6 +307,9 @@ function deriveRequiredReads(bundle, resolverOutput) {
  * (scripts/github/resolve-tracker-local-spec.mjs), which the envelope does not
  * model (deriveSpecSource coerces it to null).
  */
+// Distinct from refinementArtifact.specSource (linked_issue|pr_body|plan_file,
+// REFINEMENT_ARTIFACT_SPEC_SOURCE in packages/core/src/loop/pr-gate-coordination.mjs):
+// same field name, different object, different value space — intentionally separate enums.
 export const CANONICAL_SPEC_SOURCE = Object.freeze({
   PHASE_DOC: "phase_doc",
   PR_BODY: "pr_body",

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.
@@ -378,6 +387,8 @@ function extractClosingIssueNumbers(body) {
   // backtick-run-delimited span (equal-length runs pair, so ``a `b` c`` works).
   // ponytail: not full CommonMark span matching; an unbalanced stray backtick
   // over-strips toward fail-closed, which is the safe direction for this gate.
+  // Revisit with a real CommonMark span parser only if valid closing refs in
+  // backtick-heavy bodies start being over-stripped into false negatives.
   const text = unfenced.join("\n").replace(/(`+)[\s\S]*?\1/gu, " ");
   const seen = new Set();
   const numbers = [];
@@ -499,6 +510,37 @@ export function validatePrBodySpec({ body = "", expectedIssue = null, issueLess
   };
 }
 
+/**
+ * Decide what an enqueue caller should do with a refinement-artifact result,
+ * so an un-refined item never lands in the Next Up pickup column in the first
+ * place. The draft gate remains the backstop for whatever slips through.
+ *
+ * Pure decision table, no I/O:
+ *   - target isn't the pickup column, or the artifact is present → enqueue
+ *     as requested.
+ *   - pickup target, artifact missing, interactive caller → block (caller
+ *     throws; no mutation).
+ *   - pickup target, artifact missing, headless/auto caller → divert (caller
+ *     parks the item in the non-pickup column instead of failing the run).
+ *
+ * @param {{ artifact: ReturnType<typeof detectIssueRefinementArtifact>, targetIsPickup: boolean, auto?: boolean }} input
+ * @returns {{ action: "enqueue" } | { action: "block"|"divert", reason: string, missing: string[] }}
+ */
+export function decideEnqueueRefinementGate({ artifact, targetIsPickup, auto = false }) {
+  // `artifact.finding === null` is the explicit "has ANY refinement artifact"
+  // signal (AC checklist OR DoD checklist OR linked doc) — clearer than reading
+  // `hasACs`, whose name understates that a DoD or linked doc also satisfies it.
+  if (!targetIsPickup || artifact.finding === null) {
+    return { action: "enqueue" };
+  }
+  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 " +
+    "(e.g. run `/loop-grill <issue> --auto`, or the refiner) — before it enters the pickup queue.";
+  return { action: auto ? "divert" : "block", reason, missing };
+}
+
 /**
  * Map a draft-gate refinement check to the result surface consumed by
  * `evaluatePrGateCoordination`. The mapping keeps the contract

package/src/loop/plan-file-promote-contract.mjs

@@ -43,6 +43,28 @@ export const PLAN_FILE_PROMOTE_ACTION = Object.freeze({
  */
 export const PLAN_FILE_PR_FRONT_MATTER_KEY = "prNumber";
 
+/**
+ * Build the plan-file promotion marker sentence: the single source of truth
+ * for the PR-body text that names the committed plan doc as the spec-of-record.
+ * `buildPromotionPrBody` emits it and `PLAN_FILE_PROMOTION_DOC_PATH_PATTERN`
+ * (below) parses it back out — keep the two in lockstep.
+ *
+ * @param {string} docPath  repo-relative path of the committed plan doc
+ * @returns {string}
+ */
+export function buildPlanFilePromotionMarker(docPath) {
+  return `Spec-of-record: the committed plan doc \`${docPath}\` is the authority for this work.`;
+}
+
+/**
+ * Matches the marker sentence `buildPlanFilePromotionMarker` produces and
+ * captures the plan doc path. The captured path is bounded to a single line
+ * and a `.md` suffix so a multi-line/unbounded body cannot smuggle an
+ * oversized or cross-line "path".
+ */
+export const PLAN_FILE_PROMOTION_DOC_PATH_PATTERN =
+  /Spec-of-record: the committed plan doc `([^`\n]{1,200}?\.md)`/u;
+
 /**
  * Minimal additive front-matter support for plan files (an escalated extension
  * to P1's format): a leading `---\n...\n---\n` block of simple `key: value`
@@ -219,7 +241,7 @@ export function buildPromotionPrBody({ planDocPath, acceptanceCriteria, definiti
   const safeAc = neutralizeIssueCloseKeywords(ac);
   const safeDod = neutralizeIssueCloseKeywords(dod);
   return [
-    `Spec-of-record: the committed plan doc \`${docPath}\` is the authority for this work.`,
+    buildPlanFilePromotionMarker(docPath),
     "This PR was opened by PR-FIRST promotion; no tracker issue exists.",
     "",
     "## Acceptance criteria",

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}`;
   }
@@ -864,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,