@dev-loops/core 0.9.0 → 1.0.0-rc.2

package/src/config/config.mjs

@@ -13,52 +13,123 @@ import { z } from "zod";
 // ============================================================================
 
 const StrategyConfig = z.strictObject({
-  default: z.enum(["local-first", "github-first"]),
+  default: z.enum(["local-first", "github-first"]).describe("Default work-intake strategy: local-first starts from a repo plan file, github-first from a tracked issue."),
 });
 
 const InputSourceConfig = z.strictObject({
-  default: z.enum(["tracker", "phase-docs"]),
+  default: z.enum(["tracker", "phase-docs"]).describe("Where local-first work reads its spec: the tracker issue body, or repo phase docs."),
 });
 
-const ModelsConfig = z.strictObject({
-  conductor: z.string().trim().min(1).optional(),
-  roles: z.record(z.string(), z.string().trim().min(1)).optional(),
+// 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).describe("Model override for the conductor (dev-loop) session; absent = inherit the session model.").optional(),
+  roles: z.record(z.string(), z.string().trim().min(1)).describe("Concrete per-role/angle model overrides (highest precedence, above tiers).").optional(),
+  // Tier alias → per-harness concrete model (null = inherit / no-op).
+  tiers: z.record(z.string().min(1), ModelTierMapping).describe("Tier alias → per-harness concrete model; null on a harness means inherit (no override).").optional(),
+  // Role / angle → tier alias (a built-in/custom alias or "inherit").
+  roleTiers: z.record(z.string().min(1), z.string().trim().min(1)).describe("Role or gate angle → tier alias: a built-in alias (low, high), a custom models.tiers alias, or \"inherit\".").optional(),
 });
 
+const ModelsConfig = ModelsConfigBase.superRefine(refineRoleTiers);
+
 const RefinementConfig = z.strictObject({
-  fanOut: z.number().int().min(1).max(10),
-  mode: z.enum(["parallel", "sequential"]),
-  maxCopilotRounds: z.number().int().nonnegative().default(5),
-  stopOnLowSignal: z.boolean().default(false),
-  lowSignalRoundThreshold: z.number().int().nonnegative().default(3),
-  lowSignalMaxComments: z.number().int().nonnegative().default(2),
-  roles: z.array(z.string().trim().min(1)).optional(),
+  fanOut: z.number().int().min(1).max(10).describe("Parallel reviewers per refinement round."),
+  mode: z.enum(["parallel", "sequential"]).describe("Whether refinement reviewers run in parallel or one after another."),
+  maxCopilotRounds: z.number().int().nonnegative().default(5).describe("Automated Copilot review rounds before converging; 0 disables Copilot review."),
+  stopOnLowSignal: z.boolean().default(false).describe("Stop Copilot rounds early once they stop producing signal."),
+  lowSignalRoundThreshold: z.number().int().nonnegative().default(3).describe("Rounds counted toward the low-signal stop decision."),
+  lowSignalMaxComments: z.number().int().nonnegative().default(2).describe("A round with at most this many comments counts as low-signal."),
+  roles: z.array(z.string().trim().min(1)).describe("Review lenses the refinement fan-out dispatches.").optional(),
 });
 
 const GateConfig = z.strictObject({
-  angles: z.array(z.string().trim().min(1)).optional(),
-  excludeAngles: z.array(z.string().trim().min(1)).default([]),
-  mandatoryAngles: z.array(z.string().trim().min(1)).default([]),
-  required: z.boolean().default(true),
-  requireCi: z.boolean().default(true),
+  angles: z.array(z.string().trim().min(1)).describe("Review lenses this gate fans out to.").optional(),
+  excludeAngles: z.array(z.string().trim().min(1)).default([]).describe("Angles removed from the resolved angle list."),
+  mandatoryAngles: z.array(z.string().trim().min(1)).default([]).describe("Angles that always run, regardless of diff-based dynamic selection."),
+  required: z.boolean().default(true).describe("Whether this gate must run."),
+  requireCi: z.boolean().default(true).describe("Per-gate CI prerequisite (default true): the gate requires green CI on the current head; false opts this gate out of the CI precondition entirely, including a real failure."),
   blockCleanOnFindingSeverities: z
     .array(z.enum(["must-fix", "worth-fixing-now", "defer"]))
     .min(1)
-    .default(["must-fix"]),
-  dynamicAngles: z.boolean().default(false),
+    .default(["must-fix"])
+    .describe("Finding severities that block a clean gate verdict."),
+  dynamicAngles: z.boolean().default(false).describe("Enable diff-driven dynamic angle resolution for this gate."),
   // Additive counterpart to the subtractive dynamicAngles path (#1048): when
   // true, the context-builder may also ADD catalog angles — from
   // resolveAnglePool() (gates.anglePool, or else the union of the persona
   // registry and this config's own configured angles) — that change-category
   // heuristics recommend but that are not already in this gate's configured
   // pool. Default false preserves today's subtractive-only behavior exactly.
-  additiveAngles: z.boolean().default(false),
+  additiveAngles: z.boolean().default(false).describe("Allow diff-driven addition of catalog angles beyond this gate's configured pool."),
 });
 
 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 →
@@ -109,12 +180,12 @@ const GatesConfig = z.strictObject({
 const AutonomyConfig = z.strictObject({
   stopAt: z.array(
     z.enum(["refinement", "draft-pr", "pre-approval", "merge"])
-  ),
+  ).describe("Checkpoints that require operator confirmation before the loop proceeds (default: [\"merge\"])."),
   // When true, merge is a fixed, non-overridable human action: the agent never
   // runs `gh pr merge`, `resolveAutonomyStopAt` always includes "merge", and
   // any per-run merge authorization (envelope flag / explicit instruction) is
   // ignored — it fails closed. See resolveHumanMergeOnly / resolveEffectiveMergeAuthorized.
-  humanMergeOnly: z.boolean().optional(),
+  humanMergeOnly: z.boolean().describe("Merge stays a fixed human-only action: the agent never merges and any per-run merge authorization is ignored (fails closed).").optional(),
 });
 
 /**
@@ -137,33 +208,42 @@ const ApprovalConfig = z.strictObject({
 });
 
 const WorkflowConfig = z.strictObject({
-  asyncStartMode: z.enum(["required", "allowed"]).default("required"),
-  requireRetrospective: z.boolean(),
-  requireDraftFirst: z.boolean(),
-  devModeDefault: z.boolean(),
+  asyncStartMode: z.enum(["required", "allowed"]).default("required").describe("Whether the async start contract is required or merely allowed."),
+  requireRetrospective: z.boolean().describe("Require a retrospective checkpoint before a loop completes."),
+  requireDraftFirst: z.boolean().describe("Open pull requests as drafts and promote via the draft gate."),
+  devModeDefault: z.boolean().describe("Default new loops to dev mode."),
 });
 
 const LocalImplementationConfig = z.strictObject({
   /** Opt into light mode for small scoped changes */
   lightMode: z.strictObject({
-    enabled: z.boolean(),
-    maxFiles: z.number().int().min(1),
-    maxLines: z.number().int().min(1),
+    enabled: z.boolean().describe("Opt small scoped changes into the lightweight dispatch path."),
+    maxFiles: z.number().int().min(1).describe("Light mode applies only when the change touches at most this many files."),
+    maxLines: z.number().int().min(1).describe("Light mode applies only when the change stays within this many lines."),
     // Copilot review round cap for light-dispatched PRs (#1210). Composes with
     // (does not replace) refinement.maxCopilotRounds — see
     // resolveEffectiveCopilotRoundCap.
-    maxCopilotRounds: z.number().int().nonnegative().default(1),
+    maxCopilotRounds: z.number().int().nonnegative().default(1).describe("Copilot round cap for light-dispatched PRs; composes as min(this, refinement.maxCopilotRounds)."),
+  }).optional(),
+  /**
+   * Opt into issue-less PR-first (`--lightweight` with no --issue) at ANY
+   * change scope. Decoupled from lightMode: gate dispatch still resolves
+   * inline vs full_fanout from scope on its own, so over-threshold issue-less
+   * PRs get the full fan-out and the full-PR Copilot round cap.
+   */
+  issueless: z.strictObject({
+    enabled: z.boolean().describe("Opt into issue-less PR-first dispatch at any change scope; gate dispatch still resolves inline vs full fan-out from scope on its own."),
   }).optional(),
 });
 
 /** Queue mode config */
 const QueueConfig = z.strictObject({
-  maxParallel: z.number().int().min(1).max(10).default(3),
-  maxAutoFiledIssues: z.number().int().min(0).max(100).default(10),
-  reDispatchMaxRetries: z.number().int().min(0).max(10).default(1),
-  projectNumber: z.number().int().positive().optional(),
-  boardTitle: z.string().trim().min(1).optional(),
-  archiveOlderThanDays: z.number().int().positive().optional(),
+  maxParallel: z.number().int().min(1).max(10).default(3).describe("Maximum queue items worked in parallel."),
+  maxAutoFiledIssues: z.number().int().min(0).max(100).default(10).describe("Cap on auto-filed issues per run."),
+  reDispatchMaxRetries: z.number().int().min(0).max(10).default(1).describe("Retries when re-dispatching a failed queue item."),
+  projectNumber: z.number().int().positive().describe("GitHub Projects board number (explicit opt-in to Projects-based queue ordering).").optional(),
+  boardTitle: z.string().trim().min(1).describe("GitHub Projects board title (explicit opt-in to Projects-based queue ordering).").optional(),
+  archiveOlderThanDays: z.number().int().positive().describe("Archive done board items older than this many days.").optional(),
 });
 
 /**
@@ -174,8 +254,8 @@ const QueueConfig = z.strictObject({
  * data). Both optional; empty/absent is a valid no-op.
  */
 const WorktreeConfig = z.strictObject({
-  copyOnInit: z.array(z.string().trim().min(1)).optional(),
-  linkOnInit: z.array(z.string().trim().min(1)).optional(),
+  copyOnInit: z.array(z.string().trim().min(1)).describe("Repo-relative paths/globs copied into a fresh worktree (isolated per worktree — use for mutable files).").optional(),
+  linkOnInit: z.array(z.string().trim().min(1)).describe("Repo-relative paths/globs symlinked to the main checkout (shared — read-only data only).").optional(),
 });
 
 /**
@@ -214,6 +294,18 @@ const UiReviewMigrateConfig = z.strictObject({
     .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
@@ -238,6 +330,7 @@ const UiReviewRunConfig = z.strictObject({
   readyIntervalMs: z.number().int().min(1).max(60000).default(1000),
   cwd: z.string().trim().min(1).optional(),
   migrate: UiReviewMigrateConfig.optional(),
+  rowTeardown: UiReviewRowTeardownConfig.optional(),
 });
 
 /**
@@ -285,6 +378,12 @@ const UiReviewFlowStepConfig = z.strictObject({
   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.)
@@ -366,17 +465,19 @@ const PersonasConfig = z.record(z.string().min(1), PersonaEntry);
 
 // Partial nested gate entries for file-level config (allows overriding only
 // requireCi/required/angles without restating the whole gate object).
-const FileGateConfig = GateConfig.partial();
 const FileGatesConfig = z.strictObject({
-  draft: FileGateConfig.optional(),
-  preApproval: FileGateConfig.optional(),
-  spike: FileGateConfig.optional(),
-  requireFanoutEvidence: z.boolean().optional(),
-  requireFanoutProvenance: z.boolean().optional(),
-  maxFanoutReviewers: z.number().int().min(1).max(64).optional(),
-  postFindingsComments: z.boolean().optional(),
-  anglePool: z.array(z.string().trim().min(1)).optional(),
-  rejectForeignAngles: z.boolean().optional(),
+  // Each gate gets its own GateConfig.partial() instance rather than three
+  // .describe() clones of one shared partial, so no underlying def is shared
+  // and per-gate metadata renders unambiguously.
+  draft: GateConfig.partial().describe("Draft gate config (runs before a PR leaves draft).").optional(),
+  preApproval: GateConfig.partial().describe("Pre-approval gate config (final re-review before the merge handoff).").optional(),
+  spike: GateConfig.partial().describe("Relaxed spike gate profile; applies only to spike-mode work.").optional(),
+  requireFanoutEvidence: z.boolean().describe("Require fan-out/fan-in review evidence on gate verdicts; inline single-agent verdicts are rejected except under the strict light-mode exception (under-threshold scope, no gate:full label, recorded inline reason).").optional(),
+  requireFanoutProvenance: z.boolean().describe("Additionally require recorded, internally-consistent fan-out provenance (distinct reviewer count + per-angle dispatch).").optional(),
+  maxFanoutReviewers: z.number().int().min(1).max(64).describe("Cap on parallel gate fan-out reviewers; overflow runs in sequential batches.").optional(),
+  postFindingsComments: z.boolean().describe("Post consolidated gate findings as a marker-tagged PR comment (default true).").optional(),
+  anglePool: z.array(z.string().trim().min(1)).describe("Explicit global lens catalog for additive angle selection.").optional(),
+  rejectForeignAngles: z.boolean().describe("Reject fan-out provenance naming angles outside the gate's configured pool (default true).").optional(),
 });
 
 // Partial persona entries for file-level config (allows omitting fields)
@@ -438,6 +539,7 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
   }),
   localImplementation: Object.freeze({
     lightMode: Object.freeze({ enabled: false, maxFiles: 3, maxLines: 200, maxCopilotRounds: 1 }),
+    issueless: Object.freeze({ enabled: false }),
   }),
   queue: Object.freeze({
     maxParallel: 3,
@@ -464,21 +566,21 @@ export const BUILT_IN_DEFAULTS = Object.freeze({
 // ============================================================================
 
 export const FileConfigSchema = z.strictObject({
-  version: z.literal(1),
-  strategy: StrategyConfig.partial().optional(),
-  inputSource: InputSourceConfig.partial().optional(),
-  models: ModelsConfig.partial().optional(),
-  refinement: RefinementConfig.partial().optional(),
-  gates: FileGatesConfig.optional(),
-  autonomy: AutonomyConfig.partial().optional(),
-  approval: ApprovalConfig.partial().optional(),
-  workflow: WorkflowConfig.partial().optional(),
-  localImplementation: LocalImplementationConfig.partial().optional(),
-  queue: QueueConfig.partial().optional(),
-  personas: FilePersonasConfig.optional(),
-  internalPathPatterns: InternalPatternsConfig.optional(),
-  worktree: WorktreeConfig.partial().optional(),
-  uiReview: UiReviewConfig.partial().optional(),
+  version: z.literal(1).describe("Config format version; always 1."),
+  strategy: StrategyConfig.partial().describe("Work-intake strategy defaults.").optional(),
+  inputSource: InputSourceConfig.partial().describe("Spec source for local-first work.").optional(),
+  models: ModelsConfigBase.partial().superRefine(refineRoleTiers).describe("Model routing: conductor override, per-role/angle overrides, tier aliases, and role→tier policy.").optional(),
+  refinement: RefinementConfig.partial().describe("Refinement fan-out and Copilot review-round behavior.").optional(),
+  gates: FileGatesConfig.describe("Gate review configuration: per-gate angle sets plus fan-out enforcement knobs.").optional(),
+  autonomy: AutonomyConfig.partial().describe("How far the loop proceeds without operator confirmation.").optional(),
+  approval: ApprovalConfig.partial().describe("Approval / merge-handoff behavior (human-handoff offer).").optional(),
+  workflow: WorkflowConfig.partial().describe("Workflow posture: draft-first, retrospectives, dev mode, async start.").optional(),
+  localImplementation: LocalImplementationConfig.partial().describe("Local implementation dispatch (light mode for small scoped changes).").optional(),
+  queue: QueueConfig.partial().describe("Queue mode: parallelism, auto-filing caps, and Projects board opt-in.").optional(),
+  personas: FilePersonasConfig.describe("Gate-angle → reviewer persona registry overrides (angle name → persona, prompt, default model).").optional(),
+  internalPathPatterns: InternalPatternsConfig.describe("Regex whitelist for internal-only PR detection.").optional(),
+  worktree: WorktreeConfig.partial().describe("Worktree provisioning: gitignored files/dirs copied or symlinked into fresh worktrees.").optional(),
+  uiReview: UiReviewConfig.partial().describe("UI-review route recipes: per-project run/boot, dev-login, driven flows, and caps.").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(),
@@ -516,6 +618,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 },
@@ -587,6 +690,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
 // ============================================================================
@@ -1127,7 +1300,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 };
 }
 
 /**
@@ -1258,6 +1437,19 @@ export function resolveLightMode(config) {
   };
 }
 
+/**
+ * Resolve the issue-less PR-first any-scope opt-in (#1349).
+ *
+ * True only when `localImplementation.issueless.enabled` is exactly `true`;
+ * absent, false, or malformed values resolve to false (fail closed).
+ *
+ * @param {DevLoopConfig} config
+ * @returns {boolean}
+ */
+export function resolveIssuelessEnabled(config) {
+  return config?.localImplementation?.issueless?.enabled === true;
+}
+
 /**
  * Resolve the effective Copilot review round cap for a PR (#1210).
  *
@@ -1586,7 +1778,8 @@ export const DEFAULT_DESTRUCTIVE_MIGRATION_PATTERN =
  * @param {DevLoopConfig} config
  * @returns {null | { command: string, readyUrl: string, readyTimeoutMs: number,
  *   readyIntervalMs: number, cwd: string|null,
- *   migrate: null | { statusCommand: string, applyCommand: string, destructivePattern: string } }}
+ *   migrate: null | { statusCommand: string, applyCommand: string, destructivePattern: string },
+ *   rowTeardown: null | { deleteCommand: string } }}
  */
 export function resolveUiReviewRunRecipe(config) {
   const run = config?.uiReview?.run;
@@ -1599,6 +1792,10 @@ export function resolveUiReviewRunRecipe(config) {
         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(),
@@ -1606,6 +1803,7 @@ export function resolveUiReviewRunRecipe(config) {
     readyIntervalMs: Number.isInteger(run.readyIntervalMs) ? run.readyIntervalMs : 1000,
     cwd: typeof run.cwd === "string" && run.cwd.trim().length > 0 ? run.cwd.trim() : null,
     migrate,
+    rowTeardown,
   };
 }
 

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: >-

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;