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

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.9.0",
+  "version": "1.0.0-rc.1",
   "type": "module",
   "engines": {
     "node": ">=24"
   },
   "description": "Shared deterministic support package for dev-loop skills, repo-local scripts, and GitHub automation.",
   "exports": {
+    "./analysis/diff-analyzer": "./src/analysis/diff-analyzer.mjs",
     "./bash-exit-one": "./src/bash-exit-one.mjs",
     "./cli/helpers": "./src/cli/helpers.mjs",
     "./cli/primitives": "./src/cli/primitives.mjs",
@@ -28,6 +29,7 @@
     "./loop/copilot-ci-status": "./src/loop/copilot-ci-status.mjs",
     "./loop/copilot-loop-iterations": "./src/loop/copilot-loop-iterations.mjs",
     "./loop/copilot-loop-state": "./src/loop/copilot-loop-state.mjs",
+    "./loop/gate-carry-forward": "./src/loop/gate-carry-forward.mjs",
     "./loop/gate-fanin": "./src/loop/gate-fanin.mjs",
     "./loop/handoff-envelope": "./src/loop/handoff-envelope.mjs",
     "./loop/lifecycle-state": "./src/loop/lifecycle-state.mjs",

package/src/analysis/change-classifier.mjs

@@ -18,6 +18,10 @@ export const ChangeCategory = Object.freeze({
   CI_ONLY: "CI_ONLY",
   COMMENT_ONLY: "COMMENT_ONLY",
   LOGIC_CHANGE: "LOGIC_CHANGE",
+  // #1336: the diff touches a security-sensitive seam (browser automation,
+  // child_process/shell exec, untrusted network fetch, destructive filesystem
+  // ops / local-file upload). Triggers an up-front adversarial threat-model angle.
+  SECURITY_SENSITIVE_SEAM: "SECURITY_SENSITIVE_SEAM",
 });
 
 // ---------------------------------------------------------------------------
@@ -32,7 +36,7 @@ export const ChangeCategory = Object.freeze({
  *
  * @type {Record<string, string[]>}
  */
-const CATEGORY_ANGLE_MAP = {
+export const CATEGORY_ANGLE_MAP = {
   [ChangeCategory.RENAME_ONLY]: [
     "scope", "correctness", "contract-surface", "docs", "link-check",
   ],
@@ -54,8 +58,16 @@ const CATEGORY_ANGLE_MAP = {
   // Core review subset for any non-trivial code change. Peripheral lenses
   // (ci-guard, link-check, packaging-runtime, config-drift, etc.) are pulled in
   // only when the diff's other categories implicate them, not by logic alone.
+  // input-validation is included (#1336): it was pool-only and never auto-
+  // recommended, so entrypoint/input drift went unreviewed unless hand-picked.
   [ChangeCategory.LOGIC_CHANGE]: [
-    "scope", "correctness", "coverage", "determinism", "contract-surface",
+    "scope", "correctness", "coverage", "determinism", "contract-surface", "input-validation",
+  ],
+  // #1336: security-sensitive seam → up-front adversarial threat-model, plus
+  // input-validation and the core correctness/scope lenses. threat-model is
+  // never dropped for such a diff (a seam is dangerous regardless of size).
+  [ChangeCategory.SECURITY_SENSITIVE_SEAM]: [
+    "threat-model", "input-validation", "scope", "correctness",
   ],
 };
 
@@ -64,7 +76,7 @@ const CATEGORY_ANGLE_MAP = {
  *
  * @type {Set<string>}
  */
-const ALWAYS_INCLUDE = new Set(["gate-evidence", "renderer-security", "pr-description"]);
+export const ALWAYS_INCLUDE = new Set(["gate-evidence", "renderer-security", "pr-description"]);
 
 // ---------------------------------------------------------------------------
 // Resolution

package/src/analysis/diff-analyzer.mjs

@@ -68,9 +68,10 @@ export function analyzeT0(nameStatusOutput) {
   }
 
   const renameOnly = lines.length > 0 && renameCount === lines.length;
-  const allDocs = lines.length > 0 && files.every(
-    (f) => normalizeSep(f).startsWith("docs/") || f.endsWith(".md") || f === "README.md",
-  );
+  // Derive from the shared classifier so this predicate can't drift from it: a
+  // code/config/test file hosted under docs/ is not prose, so a mixed diff that
+  // includes one is not docs-only (it still gets the code-review surface).
+  const allDocs = lines.length > 0 && files.every((f) => classifyFile(f) === "docs");
 
   return {
     files,
@@ -96,9 +97,9 @@ export function classifyFile(filePath) {
   if (fp.startsWith(".github/")) {
     return "ci";
   }
-  if (fp.startsWith("docs/") || fp.endsWith(".md") || fp === "README.md") {
-    return "docs";
-  }
+  // A known code/config/test extension wins over the docs/ directory-prefix
+  // fallback: a code/config/test file hosted under docs/ is still that surface,
+  // not prose. Extension checks run before the prefix fallbacks below.
   if (
     fp.endsWith(".yml") || fp.endsWith(".yaml") ||
     fp.endsWith(".json") || fp === "package.json"
@@ -114,6 +115,9 @@ export function classifyFile(filePath) {
   ) {
     return "code";
   }
+  if (fp.startsWith("docs/") || fp.endsWith(".md") || fp === "README.md") {
+    return "docs";
+  }
   return "unknown";
 }
 // ---------------------------------------------------------------------------
@@ -142,6 +146,97 @@ function isNonLogicLine(content) {
   return false;
 }
 
+// Security-sensitive seams (#1336): touching these primitives on caller-/plan-
+// influenced input is where trust-boundary bugs concentrate (drove #1335's 8
+// serial Copilot rounds). A changed line matching any of these triggers the
+// SECURITY_SENSITIVE_SEAM category so an up-front adversarial threat-model angle
+// is selected. Fail-safe by design — over-selection just adds one review lens.
+// Plain readFile/writeFile are deliberately excluded (ubiquitous JSON I/O would
+// flag nearly every script diff); the browser/process/network/destructive-fs/
+// upload seams below cover the genuinely dangerous surface, including #1335's
+// Playwright driver.
+const SECURITY_SEAM_PATTERNS = [
+  // Browser automation (driving a real browser over semi-trusted navigation)
+  /\b(playwright|webkit|chromium|puppeteer)\b/i,
+  /\bpage\.(goto|click|fill|evaluate|type|press|selectOption|setInputFiles|route|addInitScript)\b/,
+  /\.newPage\s*\(/,
+  /\bbrowser\.newContext\b/,
+  // Child-process / shell execution
+  /\bchild_process\b/,
+  /\b(exec|execSync|execFile|execFileSync|spawn|spawnSync)\s*\(/,
+  /\bshell\s*:\s*true\b/,
+  // Untrusted network fetch
+  /\bfetch\s*\(/,
+  /\bhttps?\.(get|request)\s*\(/,
+  /\b(axios|node-fetch|undici)\b/,
+  // Destructive filesystem ops + local-file upload (caller-path removal/read)
+  /\b(rm|rmSync|unlink|unlinkSync|rmdir|rmdirSync)\s*\(/,
+  /\bsetInputFiles\s*\(/,
+];
+
+/**
+ * Whether a changed diff line (content, prefix stripped) touches a
+ * security-sensitive seam (#1336).
+ *
+ * @param {string} content — trimmed line content (without + / - prefix)
+ * @returns {boolean}
+ */
+function isSecuritySensitiveSeamLine(content) {
+  return SECURITY_SEAM_PATTERNS.some((re) => re.test(content));
+}
+
+/**
+ * Scan a unified diff for a security-sensitive seam (#1336) on any added/removed
+ * LOGIC line of a CODE file. Two gates keep it precise: (1) file-gate — only a
+ * file that `classifyFile()` calls `code` is scanned, so a yaml/markdown/json
+ * line that merely names a primitive (e.g. `shell: true` in a persona prompt, or
+ * `child_process` in a doc) never triggers; (2) `!isNonLogicLine` — within a code
+ * file, a comment/blank line that names a primitive (e.g. `// spawn( a child`)
+ * does not trigger either. Runs independently of the T0/T1 category path so it
+ * also covers a pure-code diff (all files classify as `code`), which is the MOST
+ * concentrated seam case (e.g. editing a Playwright/child_process driver) and the
+ * one #1336 targets.
+ *
+ * @param {string} diffOutput — raw unified diff output
+ * @returns {boolean}
+ */
+export function diffHasSecuritySeam(diffOutput) {
+  if (!diffOutput) return false;
+  let inHunk = false;
+  // Only CODE files can carry an executable seam — a YAML/markdown/JSON line that
+  // merely names a primitive (e.g. `shell: true` in a persona prompt) is not a
+  // seam. Track the current file from the unified-diff `--- a/`/`+++ b/` headers
+  // and gate the scan on `classifyFile(...) === "code"`. Bare-hunk input (no file
+  // header — used in tests / direct hunk analysis) defaults to code so it still
+  // scans; a real `git diff` always carries headers, so it is gated per file.
+  let currentFileIsCode = true;
+  let fromPath = null;
+  for (const line of diffOutput.split("\n")) {
+    if (line.startsWith("--- ")) {
+      const p = line.slice(4).trim().replace(/^a\//, "");
+      fromPath = p === "/dev/null" ? null : p;
+      inHunk = false;
+      continue;
+    }
+    if (line.startsWith("+++ ")) {
+      const p = line.slice(4).trim().replace(/^b\//, "");
+      const effective = p === "/dev/null" ? fromPath : p;
+      currentFileIsCode = effective != null && classifyFile(effective) === "code";
+      inHunk = false;
+      continue;
+    }
+    if (line.startsWith("@@")) { inHunk = true; continue; }
+    if (!inHunk || !currentFileIsCode) continue;
+    const isAdd = line.startsWith("+") && !line.startsWith("+++");
+    const isDel = line.startsWith("-") && !line.startsWith("---");
+    if (!isAdd && !isDel) continue;
+    const content = line.slice(1).trim();
+    if (isNonLogicLine(content)) continue;
+    if (isSecuritySensitiveSeamLine(content)) return true;
+  }
+  return false;
+}
+
 /**
  * Analyze unified diff hunks to classify change types.
  *
@@ -202,6 +297,9 @@ export function analyzeT1(diffOutput, t0) {
   // Build categories from T0 (shared with inferCategoriesFromT0) + hunk analysis.
   for (const c of t0FileCategories(t0)) categories.add(c);
   if (hasLogicChange) categories.add("LOGIC_CHANGE");
+  // #1336: a diff touching a security-sensitive seam gets an up-front adversarial
+  // threat-model angle, batched at draft time instead of drip-fed via Copilot.
+  if (diffHasSecuritySeam(diffOutput)) categories.add("SECURITY_SENSITIVE_SEAM");
   // Mixed diffs never satisfy the exclusive `_ONLY` checks above (some files are
   // code), so their peripheral surfaces would be dropped. In this hunk-level path
   // (only reached for genuinely mixed diffs), also union each surface by PRESENCE
@@ -328,6 +426,14 @@ export function analyzeDiff({ nameStatusOutput, diffOutput }) {
     };
   }
 
+  // #1336: seam detection runs on the raw diff regardless of the T0/T1 path, so a
+  // pure-code diff (single `code` category, T1 skipped) editing a browser/exec/
+  // fetch/fs-mutation driver still triggers the up-front threat-model angle — the
+  // most concentrated seam case, and the one this feature targets.
+  if (!t1.changeCategories.includes("SECURITY_SENSITIVE_SEAM") && diffHasSecuritySeam(diffOutput)) {
+    t1.changeCategories.push("SECURITY_SENSITIVE_SEAM");
+  }
+
   // `ambiguous` flags one specific case: a diff T0 could not classify (mixed file
   // categories, so t0Ambiguous) AND whose hunk analysis still produced no
   // category. It is NOT the only fallback trigger — resolveDynamicAngles also

package/src/claude/asset-generation.mjs

@@ -26,6 +26,8 @@
 
 import { parse as parseYaml } from "yaml";
 
+import { resolveRoleModel } from "../config/config.mjs";
+
 /** Pi→Claude tool-name map. A Pi name may expand to multiple Claude tools (search→Grep,Glob). */
 export const TOOL_NAME_MAP = Object.freeze({
   read: ["Read"],
@@ -89,24 +91,26 @@ export function rewriteCliInvocation(body, 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`.
+ * Rewrite repo-root `../docs/…` *inline* markdown links `](../docs/…)` in a generated *command* or
+ * *agent* 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/agent bodies only use inline links, so that is the sole form that occurs. Source
+ * commands/agents live at `commands/<name>.command.md` / `agents/<name>.agent.md`, so `../docs/x`
+ * resolves to repo-root `docs/x`; the generated wrapper lives one level deeper at
+ * `.claude/commands/<name>.md` / `.claude/agents/<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`. Both trees sit one
+ * level under `.claude/`, so the same single-level shift applies to each.
  *
- * 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`).
+ * Scoped to `../docs/` on purpose. Other `../…` 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) {
+export function rewriteGeneratedRepoDocLinks(body) {
   return String(body).replace(/(\]\(<?)(\.\.\/docs\/)/g, "$1../$2");
 }
 
@@ -169,13 +173,20 @@ function normalizeToolList(value) {
 
 /**
  * Transform a canonical `agents/*.agent.md` into a Claude `.claude/agents/*.md` document.
- * @param {{ source: string, raw: string, version?: string }} input
+ *
+ * Stamps the model-tier policy into `model:` frontmatter: the agent's role (its
+ * `name`) is resolved via `resolveRoleModel(config, { role, harness: "claude" })`;
+ * a concrete model is written, `inherit`/null omits the field. `config` defaults
+ * to `{}` so the committed tree bakes the zero-config built-in policy; pass a
+ * loaded config to tune the generated tree per repo.
+ * @param {{ source: string, raw: string, version?: string, config?: object }} input
  * @returns {string} Full generated file content.
  */
-export function transformAgent({ source, raw, version = "latest" }) {
+export function transformAgent({ source, raw, version = "latest", config = {} }) {
   const { frontmatter, body: rawBody } = splitFrontmatter(raw, source);
-  const body = rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version);
+  const body = rewriteGeneratedRepoDocLinks(rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version));
   const tools = mapTools(normalizeToolList(frontmatter.tools));
+  const model = resolveRoleModel(config, { role: String(frontmatter.name ?? ""), harness: "claude" });
 
   const lines = ["---"];
   lines.push(`name: ${JSON.stringify(String(frontmatter.name ?? ""))}`);
@@ -185,6 +196,12 @@ export function transformAgent({ source, raw, version = "latest" }) {
   if (tools.length > 0) {
     lines.push(`tools: ${tools.join(", ")}`);
   }
+  if (model != null) {
+    // Quote the stamped model id: resolveRoleModel can return any operator-provided
+    // id, and a value with YAML-significant chars would break frontmatter parsing.
+    // JSON string literals are valid YAML double-quoted scalars.
+    lines.push(`model: ${JSON.stringify(model)}`);
+  }
   lines.push("---");
   lines.push(GENERATED_NOTE(source));
   lines.push("");
@@ -202,7 +219,7 @@ export function transformAgent({ source, raw, version = "latest" }) {
  */
 export function transformCommand({ source, raw, version = "latest" }) {
   const { frontmatter, body: rawBody } = splitFrontmatter(raw, source);
-  const body = rewriteCommandRepoLinks(rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version));
+  const body = rewriteGeneratedRepoDocLinks(rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version));
 
   const lines = ["---"];
   if (frontmatter.description != null) {

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 →
@@ -214,6 +284,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 +320,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 +368,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.)
@@ -467,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(),
@@ -516,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 },
@@ -587,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
 // ============================================================================
@@ -1127,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 };
 }
 
 /**
@@ -1586,7 +1752,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 +1766,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 +1777,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);
-}