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

package/src/config/config.mjs

@@ -20,11 +20,78 @@ const InputSourceConfig = z.strictObject({
   default: z.enum(["tracker", "phase-docs"]),
 });
 
-const ModelsConfig = z.strictObject({
+// Built-in tier aliases shipped with zero config. A tier alias maps a
+// harness-neutral name (low/high) to a concrete per-harness model id; `null`
+// means "inherit" (pass no model override → genuine no-op on that harness).
+// Pi ships null on every built-in tier, so zero-config resolution is a no-op on
+// Pi until an operator sets concrete Pi ids.
+export const BUILTIN_TIER_ALIASES = Object.freeze(["low", "high"]);
+
+const BUILTIN_TIERS = Object.freeze({
+  low: Object.freeze({ claude: "sonnet", pi: null }),
+  high: Object.freeze({ claude: "opus", pi: null }),
+});
+
+// Built-in role→tier policy: routine subagents run on the low tier, planning
+// (refiner) and critical review (review, incl. gate fan-out angles via their
+// review persona) run high, and the conductor (dev-loop) inherits (no override).
+const BUILTIN_ROLE_TIERS = Object.freeze({
+  developer: "low",
+  docs: "low",
+  fixer: "low",
+  quality: "low",
+  refiner: "high",
+  review: "high",
+  "dev-loop": "inherit",
+});
+
+// A tier alias's per-harness concrete model. Either harness may be a concrete
+// model id or `null` (inherit / no-op on that harness). strictObject rejects
+// unknown harness keys.
+const ModelTierMapping = z
+  .strictObject({
+    claude: z.string().trim().min(1).nullable().optional(),
+    pi: z.string().trim().min(1).nullable().optional(),
+  })
+  // A tier mapping with both harnesses absent/null resolves to a null no-op on
+  // every harness — a silent dead alias that roleTiers could reference. Require
+  // at least one concrete harness model so an empty/all-null tier fails closed.
+  .refine((m) => typeof m.claude === "string" || typeof m.pi === "string", {
+    message: "tier mapping must set at least one of claude/pi to a non-null model id",
+  });
+
+/**
+ * Reject `models.roleTiers` entries that reference a tier alias which is neither
+ * a built-in alias (low/high), the literal "inherit", nor defined in this
+ * config's own `models.tiers`. Applied to both the merged and file-level
+ * ModelsConfig so a typo'd alias fails closed with a clear message.
+ * @param {Record<string, unknown>|undefined} models
+ * @param {z.RefinementCtx} ctx
+ */
+function refineRoleTiers(models, ctx) {
+  const known = new Set([...BUILTIN_TIER_ALIASES, ...Object.keys(models?.tiers ?? {})]);
+  for (const [role, tier] of Object.entries(models?.roleTiers ?? {})) {
+    if (tier !== "inherit" && !known.has(tier)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["roleTiers", role],
+        message: `unknown model tier alias "${tier}" — define it under models.tiers, use a built-in alias (${BUILTIN_TIER_ALIASES.join(", ")}), or "inherit"`,
+      });
+    }
+  }
+}
+
+const ModelsConfigBase = z.strictObject({
   conductor: z.string().trim().min(1).optional(),
   roles: z.record(z.string(), z.string().trim().min(1)).optional(),
+  // Tier alias → per-harness concrete model (null = inherit / no-op).
+  tiers: z.record(z.string().min(1), ModelTierMapping).optional(),
+  // Role / angle → tier alias (a built-in/custom alias or "inherit").
+  roleTiers: z.record(z.string().min(1), z.string().trim().min(1)).optional(),
 });
 
+const ModelsConfig = ModelsConfigBase.superRefine(refineRoleTiers);
+
 const RefinementConfig = z.strictObject({
   fanOut: z.number().int().min(1).max(10),
   mode: z.enum(["parallel", "sequential"]),
@@ -57,8 +124,11 @@ const GateConfig = z.strictObject({
 
 const GatesConfig = z.strictObject({
   draft: GateConfig.optional(),
-  // `requireCi` is only behaviorally configurable for the draft gate.
-  // preApproval always requires CI even if config repeats `requireCi`.
+  // `requireCi` is honored on both gates: default true keeps CI a precondition,
+  // false is an opt-out escape hatch so a repo with no CI is not held at the
+  // gate. The pre-approval gate mirrors the draft gate's `requireCi` semantics —
+  // when false the CI verdict is ignored entirely at that boundary, including a
+  // real failure (not merely "green optional").
   preApproval: GateConfig.optional(),
   // Relaxed spike gate profile (#965). A spike's deliverable is a findings doc,
   // not production code, so it should not carry the full draft → pre-approval →
@@ -178,6 +248,198 @@ 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 dev-DB row-teardown recipe (Stage 5). The drive stamps each
+ * mutating step it drives with a drive-session id (advertised to the app on the
+ * DRIVE_SESSION_HEADER request header); this `deleteCommand` deletes exactly the
+ * rows the app tagged with that session — the id is passed in the
+ * UI_REVIEW_DRIVE_SESSION env var and the command runs in the provisioned
+ * worktree (dev DB only). Teardown runs it only on explicit confirmation.
+ */
+const UiReviewRowTeardownConfig = z.strictObject({
+  deleteCommand: z.string().trim().min(1),
+});
+
+/**
+ * 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(),
+  rowTeardown: UiReviewRowTeardownConfig.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(),
+  // Responsive/stateful captures: a declared viewport resizes the page before the
+  // step and bakes into the named-state slug, so the mobile vs desktop (or
+  // default vs error) render lands in a distinct reviewable directory. The route
+  // NAMES its interaction states — the drive never enumerates them itself.
+  viewport: z.strictObject({ width: z.number().int().positive(), height: z.number().int().positive() }).optional(),
+  interactionState: z.enum(["none", "focus", "hover", "error"]).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 +494,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(),
@@ -293,7 +556,7 @@ export const FileConfigSchema = z.strictObject({
   version: z.literal(1),
   strategy: StrategyConfig.partial().optional(),
   inputSource: InputSourceConfig.partial().optional(),
-  models: ModelsConfig.partial().optional(),
+  models: ModelsConfigBase.partial().superRefine(refineRoleTiers).optional(),
   refinement: RefinementConfig.partial().optional(),
   gates: FileGatesConfig.optional(),
   autonomy: AutonomyConfig.partial().optional(),
@@ -304,6 +567,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(),
@@ -341,6 +605,7 @@ const BUILTIN_PERSONAS = Object.freeze({
   yagni:       { persona: "review", defaultModel: null },
   "contract-surface":  { persona: "review", defaultModel: null },
   "input-validation":  { persona: "review", defaultModel: null },
+  "threat-model":      { persona: "review", defaultModel: null },
   "packaging-runtime": { persona: "review", defaultModel: null },
   "state-concurrency": { persona: "review", defaultModel: null },
   "renderer-security": { persona: "review", defaultModel: null },
@@ -412,6 +677,76 @@ export function resolveReviewerRole(config, angle) {
   };
 }
 
+/**
+ * Resolve the concrete model for a subagent role/angle on a given harness, or
+ * `null` (inherit → pass no model override).
+ *
+ * Precedence:
+ *   1. `models.roles[role]` — concrete per-role/angle override (highest).
+ *   2. Tier alias, mapped through `models.tiers[tier][harness]` (or built-in
+ *      tiers); `inherit`/absent/null → `null`. The alias depends on `kind`:
+ *      - `kind: "angle"` (gate review dispatch): an explicit
+ *        `models.roleTiers[role]` override, else the `review` tier. A gate
+ *        review runs at review quality even when the angle's name collides with
+ *        a routine role — e.g. the `docs` angle resolves via the `review` tier
+ *        (high), not the `docs` writer role's low tier. (Its persona/agent still
+ *        comes from `resolveReviewerRole`; only the tier is forced to review.)
+ *      - `kind: "role"`/absent (routine subagent): `models.roleTiers[role]` (or
+ *        the built-in role tier), else — when the name is not a named role — the
+ *        tier for its review persona (so a non-colliding gate angle passed
+ *        without `kind` still resolves high via `review`).
+ *
+ * Callers dispatching a gate review angle whose name may collide with a routine
+ * role (only `docs` today) MUST pass `kind: "angle"` to avoid the silent
+ * downgrade; role dispatch leaves `kind` unset.
+ *
+ * Zero-config is a genuine no-op on Pi (built-in tiers are null for pi) and
+ * reproduces the standing policy on Claude (routine=low, refiner/review=high,
+ * dev-loop=inherit).
+ *
+ * @param {DevLoopConfig} config
+ * @param {{ role: string, harness: "claude"|"pi", kind?: "role"|"angle" }} params
+ * @returns {string|null}
+ */
+export function resolveRoleModel(config, { role, harness, kind } = {}) {
+  if (!role || (harness !== "claude" && harness !== "pi")) return null;
+
+  // 1. Concrete per-role/angle override wins outright (over any tier).
+  const concrete = config?.models?.roles?.[role];
+  if (typeof concrete === "string" && concrete.trim().length > 0) {
+    return concrete.trim();
+  }
+
+  // 2. Resolve a tier alias for this role/angle.
+  const roleTiers = { ...BUILTIN_ROLE_TIERS, ...(config?.models?.roleTiers ?? {}) };
+  let tierAlias;
+  if (kind === "angle") {
+    // Gate review angle: an explicit per-angle override wins, else the review
+    // tier — a gate review is review-quality regardless of a coincidental
+    // routine-role persona name (the `docs` angle must not inherit `docs`→low).
+    tierAlias = config?.models?.roleTiers?.[role] ?? roleTiers.review;
+  } else {
+    tierAlias = roleTiers[role];
+    if (tierAlias === undefined) {
+      // Not a named role — treat as a gate angle and inherit its review
+      // persona's tier (critical angles resolve high via the `review` persona).
+      const { persona } = resolveReviewerRole(config, role);
+      tierAlias = roleTiers[persona];
+    }
+  }
+  if (!tierAlias || tierAlias === "inherit") return null;
+
+  // Deep-merge the alias mapping so a partial override (e.g. `{ pi: "..." }`,
+  // which the schema allows) preserves the untouched built-in harness key rather
+  // than erasing the whole {claude,pi} mapping and resolving null for that harness.
+  const builtinMapping = BUILTIN_TIERS[tierAlias];
+  const configMapping = config?.models?.tiers?.[tierAlias];
+  if (!builtinMapping && !configMapping) return null;
+  const mapping = { ...builtinMapping, ...configMapping };
+  const model = mapping[harness];
+  return typeof model === "string" && model.trim().length > 0 ? model.trim() : null;
+}
+
 // ============================================================================
 // Error types
 // ============================================================================
@@ -952,7 +1287,13 @@ export function resolveRefinement(config) {
   const stopOnLowSignal = /** @type {boolean} */ (resolveRefinementConfig(config, "stopOnLowSignal"));
   const lowSignalRoundThreshold = /** @type {number} */ (resolveRefinementConfig(config, "lowSignalRoundThreshold"));
   const lowSignalMaxComments = /** @type {number} */ (resolveRefinementConfig(config, "lowSignalMaxComments"));
-  return { fanOut, mode, roles, maxCopilotRounds, stopOnLowSignal, lowSignalRoundThreshold, lowSignalMaxComments };
+  // #1337: centralize the pre-approval CI opt-out here so every caller that
+  // builds its interpreter refinement config from `resolveRefinement(config)`
+  // (detect-copilot-loop-state, copilot-pr-handoff, gate coordination, etc.)
+  // reliably honors `gates.preApproval.requireCi: false` — otherwise a CI-less
+  // repo would still be interpreted as waiting_for_ci / blocked in those tools.
+  const preApprovalRequireCi = resolveGateConfig(config, "preApproval").requireCi;
+  return { fanOut, mode, roles, maxCopilotRounds, stopOnLowSignal, lowSignalRoundThreshold, lowSignalMaxComments, preApprovalRequireCi };
 }
 
 /**
@@ -1385,6 +1726,114 @@ 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 },
+ *   rowTeardown: null | { deleteCommand: 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;
+  const rowTeardown =
+    run.rowTeardown && typeof run.rowTeardown.deleteCommand === "string" && run.rowTeardown.deleteCommand.trim().length > 0
+      ? { deleteCommand: run.rowTeardown.deleteCommand.trim() }
+      : 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,
+    rowTeardown,
+  };
+}
+
+/**
+ * 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

@@ -39,6 +39,7 @@ gates:
       - gate-evidence
       - no-op
       - input-validation
+      - threat-model
       - packaging-runtime
       - state-concurrency
       - renderer-security
@@ -352,6 +353,12 @@ personas:
       Review this change for renderer security. Check HTML text escaping, URL encoding, attribute encoding, JSON/script embedding, and rendering of user-controlled content. Treat titles, names, URLs, statuses, errors, and external payload fields as untrusted. Flag raw interpolation into HTML or attributes and tests that expect unsafe output.
     defaultModel: null
 
+  threat-model:
+    persona: review
+    prompt: >-
+      Adversarially threat-model this change end to end — you are an attacker with control over every caller-/plan-influenced input (descriptors, paths, URLs, flags, env, fixture data). Do NOT spot-check; return a trust-boundary CHECKLIST and a verdict per item. Enumerate exhaustively for every seam the diff touches: (1) INPUT ALLOWLISTS — are actions/commands/schemes/hosts allowlisted (not denylisted), and enforced BEFORE any dangerous use (browser launch, exec, read)? (2) NAVIGATION/ORIGIN CONFINEMENT — same-origin/scheme enforced both pre-launch AND at runtime after every redirect / click / server-response (a pre-check the runtime can defeat is a hole). (3) RESOURCE/LOOP BOUNDS — step/size/time/recursion caps on attacker-influenced counts. (4) DATA-AT-REST + CLEANUP — sensitive intermediate artifacts minimized and removed on EVERY fail-closed path (not just the happy path); no off-origin/partial artifact left on disk on error. (5) EXPORTED/ENTRY-POINT TRUST — does every exported function / alternate entry self-validate, or can it bypass the parse-time validation the CLI does? (6) ERROR/TEARDOWN SAFETY — a throw in rm/close/teardown must not break the fail-closed envelope or leak state. (7) PATH TRAVERSAL / DESERIALIZATION — reject absolute/`..`/escape-base paths before read; no unsafe deserialization of untrusted data. (8) SHELL/PROCESS — no unescaped interpolation into a shell; prefer argv arrays; no `shell:true` with caller input. For each category that applies, state whether the change is safe and cite the guarding code (file:line) or flag the specific abuse and a failing-input example. If a category does not apply to the touched seam, say so explicitly rather than skipping it.
+    defaultModel: null
+
   determinism:
     persona: review
     prompt: >-
@@ -396,7 +403,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/debt/shape.mjs

@@ -200,15 +200,3 @@ export function shapeFindings(findings) {
     return { outcome, artifact, findingId: f.id };
   });
 }
-
-/**
- * Run the full pipeline: cluster → score → shape, return shaped artifacts.
- *
- * @param {Array<object>} signals — debt_signal-compatible array
- * @returns {Array<{ outcome: ShapeOutcome, artifact: object|null, findingId: string }>}
- */
-export async function runPipeline(signals) {
-  const { clusterSignalsEnriched } = await import("./cluster.mjs");
-  const findings = clusterSignalsEnriched(signals);
-  return shapeFindings(findings);
-}

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

@@ -136,7 +136,25 @@ export const NEXT_ACTIONS = Object.freeze({
 
 const SAME_HEAD_CLEAN_CONVERGED_NEXT_ACTION = "Current head already has a clean submitted Copilot review; suppress automatic same-head re-request unless a meaningful remediation event occurs, or explicitly request another Copilot pass";
 
-const VALID_REVIEW_REQUEST_STATUSES = new Set(["requested", "already-requested", "unavailable", "none", "failed"]);
+/**
+ * Canonical snapshot request-status enum (single source of truth). Any request
+ * outcome plumbed into the shared loop contract MUST normalize to one of these;
+ * richer request-tool outcomes (round_cap_reached, suppressed_*, etc.) collapse
+ * to "none" here because they mean "no active Copilot request is in flight".
+ */
+export const VALID_REVIEW_REQUEST_STATUSES = new Set(["requested", "already-requested", "unavailable", "none", "failed"]);
+
+/**
+ * Collapse an arbitrary request-tool outcome to the canonical snapshot
+ * request-status enum. Unrecognized statuses (round cap / suppression
+ * diagnostics) map to "none" so they never leak into the shared contract.
+ *
+ * @param {string|undefined} status
+ * @returns {string} a member of VALID_REVIEW_REQUEST_STATUSES
+ */
+export function toSharedRequestStatus(status) {
+  return VALID_REVIEW_REQUEST_STATUSES.has(status) ? status : "none";
+}
 const VALID_CI_STATUSES = new Set(["success", "failure", "pending", "none", "crediblyGreen"]);
 const ACTIVE_REQUEST_STATUSES = new Set(["requested", "already-requested"]);
 
@@ -341,6 +359,9 @@ export function applyConfirmedReviewRequest(snapshot, reviewRequestStatus) {
  * @param {number} [refinementConfig.lowSignalRoundThreshold]
  * @param {number} [refinementConfig.lowSignalMaxComments]
  * @param {number} [refinementConfig.maxCopilotRounds]
+ * @param {boolean} [refinementConfig.preApprovalRequireCi] - #1337: default true. When false,
+ *   the pre-approval CI precondition is opted out, so a non-draft PR with a pending/none/failure
+ *   CI verdict is not routed to waiting_for_ci / blocked_needs_user_decision (it is past the draft gate).
  * @returns {{
  *   state: string,
  *   allowedTransitions: string[],
@@ -353,6 +374,17 @@ export function applyConfirmedReviewRequest(snapshot, reviewRequestStatus) {
 export function interpretLoopState(snapshot, refinementConfig) {
   const s = normalizeSnapshot(snapshot);
 
+  // Pre-approval CI opt-out (#1337): when `gates.preApproval.requireCi` is false,
+  // the CI verdict must not gate progression at the pre-approval boundary. A
+  // non-draft PR is past the draft gate, so this is the applicable knob — treat
+  // pending/none/failure CI as non-blocking here so a repo with no CI is not
+  // routed to WAITING_FOR_CI / BLOCKED_NEEDS_USER_DECISION before the downstream
+  // gate-coordination guards (which already honor this flag) are ever reached.
+  // Default true preserves current behavior for every caller that does not thread it.
+  const preApprovalRequireCi = refinementConfig?.preApprovalRequireCi !== false;
+  const ciBlocks = preApprovalRequireCi && isBlockedCiStatus(s.ciStatus);
+  const ciWaits = preApprovalRequireCi && isWaitingCiStatus(s.ciStatus);
+
   let state;
 
   if (!s.prExists) {
@@ -403,7 +435,7 @@ export function interpretLoopState(snapshot, refinementConfig) {
       && state !== STATE.NO_PR && state !== STATE.DONE
       && state !== STATE.PR_DRAFT && state !== STATE.REVIEW_REQUEST_UNAVAILABLE
       && state !== STATE.BLOCKED_NEEDS_USER_DECISION) {
-    const ciClean = s.ciStatus === "success" || s.ciStatus === "crediblyGreen";
+    const ciClean = s.ciStatus === "success" || s.ciStatus === "crediblyGreen" || !preApprovalRequireCi;
     const cleanThreads = s.unresolvedThreadCount === 0;
     if (cleanThreads && ciClean) {
       // Clean PR at the cap: proceed to the pre_approval_gate fallback regardless of a
@@ -430,18 +462,18 @@ export function interpretLoopState(snapshot, refinementConfig) {
       state = STATE.WAITING_FOR_COPILOT_REVIEW;
     } else if (s.copilotReviewPresent) {
       // Copilot has reviewed at least once; all threads resolved
-      if (isBlockedCiStatus(s.ciStatus)) {
+      if (ciBlocks) {
         state = STATE.BLOCKED_NEEDS_USER_DECISION;
-      } else if (isWaitingCiStatus(s.ciStatus)) {
+      } else if (ciWaits) {
         state = STATE.WAITING_FOR_CI;
       } else {
         state = STATE.READY_TO_REREQUEST_REVIEW;
       }
     } else {
       // No Copilot review yet; not currently requested
-      if (isBlockedCiStatus(s.ciStatus)) {
+      if (ciBlocks) {
         state = STATE.BLOCKED_NEEDS_USER_DECISION;
-      } else if (isWaitingCiStatus(s.ciStatus)) {
+      } else if (ciWaits) {
         state = STATE.WAITING_FOR_CI;
       } else {
         state = STATE.PR_READY_NO_FEEDBACK;