@dreki-gg/pi-code-reviewer 0.4.0 → 0.5.0

package/README.md

@@ -35,6 +35,32 @@ This creates:
 
 The `code_review` tool is also available for programmatic use by the agent.
 
+## How the review runs (Bugbot-style pipeline)
+
+When a session model is available, the `code_review` tool **runs the review
+itself** rather than returning a prompt for one downstream pass. It drives a
+multi-stage pipeline modeled on Cursor's Bugbot:
+
+1. **Parallel adversarial passes** (default 5) over the diff. Each pass gets a
+   different focus — trust boundaries, control flow, async/lifecycle, types,
+   state integrity, security, resources, contracts — plus a temperature jitter,
+   so passes reason down different paths instead of collapsing onto the same
+   findings.
+2. **Bucket + majority vote.** Near-duplicate findings are fused (same file +
+   line proximity + message similarity) and tracked by how many distinct passes
+   surfaced them. Low-signal single-pass *notes* are dropped; blockers and
+   warnings are never dropped for low votes.
+3. **Validator stage.** One batched call tries to *falsify* each surviving
+   candidate and drops false positives. It **fails open** — if the validator
+   errors, candidates are surfaced unvalidated rather than silently lost.
+
+The tool returns finished, validated findings as a Markdown report (vote count,
+confidence, validator justification) plus structured `details`.
+
+**Fallback:** if no model is available (e.g. print mode) or `review.passes` is
+`0`, the tool returns the previous single-pass review prompt and the calling
+agent produces findings in its follow-up message.
+
 ## Lenses
 
 A lens is a markdown file that defines review criteria, project tools to run, and severity rules:
@@ -88,7 +114,17 @@ Run `/review-init` to scaffold these (customized for your project's tools) into
   "lensDir": ".code-review/lenses",
   "defaultLenses": ["code-quality", "maintainability"],
   "toolTimeoutMs": 60000,
-  "toolConcurrency": 4
+  "toolConcurrency": 4,
+  "review": {
+    "passes": 5,
+    "validate": true,
+    "minVotes": 2,
+    "concurrency": 5,
+    "temperature": 0.4,
+    "maxFindings": 50,
+    "passModels": [{ "model": "anthropic/claude-opus-4-8", "reasoning": "low" }],
+    "validateModel": { "model": "anthropic/claude-opus-4-8", "reasoning": "medium" }
+  }
 }
 ```
 
@@ -98,4 +134,30 @@ Run `/review-init` to scaffold these (customized for your project's tools) into
 | `defaultLenses` | `[]` (all) | Lenses to run when none specified |
 | `toolTimeoutMs` | `60000` | Per-tool wall-clock timeout (ms); an exceeding tool is killed and reported as timed-out |
 | `toolConcurrency` | `4` | Max distinct tools run in parallel (tools are deduped across lenses first) |
+| `review.passes` | `5` | Parallel adversarial bug-finding passes. `0` disables the pipeline (single-pass prompt fallback). |
+| `review.validate` | `true` | Run the validator stage that falsifies each surviving candidate. |
+| `review.minVotes` | `2` | Min distinct passes a NOTE bucket needs to survive pre-validation (blockers/warnings exempt). |
+| `review.concurrency` | `= passes` | Max passes run concurrently. |
+| `review.temperature` | `0.4` | Base sampling temperature; each pass adds a small jitter so passes diverge. |
+| `review.maxFindings` | `50` | Hard cap on findings returned. |
+| `review.passModel` | session model | Model for ALL passes: a spec string (`"provider/id"`, bare id, or name) or `{ "model", "reasoning" }`. |
+| `review.passModels` | — | List of models **rotated round-robin across passes** — a bake-off in one run. Overrides `passModel`. |
+| `review.validateModel` | session model | Model for the validator stage (string or `{ "model", "reasoning" }`). |
+
+Each step accepts either a plain spec string or `{ "model": "provider/id", "reasoning": "low" }`
+where `reasoning` is one of `minimal` / `low` / `medium` / `high` / `xhigh` (applied as the
+thinking effort for that step; ignored by providers that don't support it).
+
+> By default the pipeline reuses the **session's current model** (`ctx.model`) —
+> no separate API key or model config. More passes = deeper coverage but higher
+> token/latency cost; tune `review.passes` to taste (3 = cheap, 8 = Bugbot
+> parity).
+>
+> **Model bake-off.** Set `passModels` to a list to run the same diff through
+> several models in one review and compare. Models are assigned round-robin to
+> passes, each finding is annotated with the model(s) that caught it, and the
+> report shows a per-model breakdown. Use a cheap model for `passModels` and a
+> stronger one for `validateModel` (or vice-versa) to probe the speed/cost/
+> quality frontier. Specs are matched as `provider/id`, a bare `id`, or a
+> display `name`; an unknown spec falls back to the session model with a warning.
 

package/extensions/code-reviewer/commands/review-init.ts

@@ -14,7 +14,11 @@ export function registerReviewInitCommand(pi: ExtensionAPI) {
           `1. Read the project's AGENTS.md, package.json, and any CONTEXT.md to understand the stack and conventions.`,
           `2. Create a \`.code-review.json\` config file at the project root. Supported keys:`,
           `   - \`lensDir\` (default \`.code-review/lenses\`), \`defaultLenses\` (lenses run when none are specified),`,
-          `   - \`toolTimeoutMs\` (per-tool timeout, default 60000), \`toolConcurrency\` (parallel tools, default 4).`,
+          `   - \`toolTimeoutMs\` (per-tool timeout, default 60000), \`toolConcurrency\` (parallel tools, default 4),`,
+          `   - \`review\` (self-driving pipeline): \`passes\` (default 5, 0 disables), \`validate\` (default true),`,
+          `     \`minVotes\` (default 2), \`concurrency\` (default = passes), \`temperature\` (default 0.4), \`maxFindings\` (default 50),`,
+          `     and per-step models for a bake-off: \`passModel\`, \`passModels\` (rotated across passes), \`validateModel\``,
+          `     (each a "provider/id", bare id, or display name; default = the session model).`,
           `3. Create lens files in \`.code-review/lenses/\` — start with: code-quality.md, maintainability.md`,
           `4. Each lens's \`## Tools\` must list ONLY fast, non-side-effecting commands that EXIT on their own`,
           `   (e.g. typecheck, lint, unit tests). Do NOT list dev servers, watch mode, e2e suites, or full`,

package/extensions/code-reviewer/commands/review-tool.ts

@@ -4,7 +4,16 @@ import { Type } from 'typebox';
 import { loadConfig, getLensDir } from '../config';
 import { collectDiff, getChangedFiles } from '../diff';
 import { discoverLenses, getLensContent } from '../lenses';
-import { buildDiffSection, buildLensResult, pickLensToolOutputs, runTools } from '../reviewer';
+import { resolveModelPlan } from '../model-plan';
+import { runPipeline } from '../passes';
+import {
+  buildDiffSection,
+  buildLensResult,
+  buildReviewBasePrompt,
+  pickLensToolOutputs,
+  renderPipelineReport,
+  runTools,
+} from '../reviewer';
 import type { DiffSource } from '../diff';
 import type { LensResult, ReviewConfig } from '../types';
 
@@ -106,23 +115,75 @@ export function registerReviewTool(pi: ExtensionAPI) {
         results.push(buildLensResult(lens, content, pickLensToolOutputs(lens, toolOutputs)));
       }
 
+      const changedFiles = await getChangedFiles(pi, cwd, {
+        base: params.base,
+        staged: params.staged,
+      });
+
+      // Self-driving path: when a model is available and passes are enabled,
+      // the tool runs the Bugbot-style pipeline itself (parallel adversarial
+      // passes → bucket → majority vote → validate) and returns FINISHED,
+      // validated findings — not a prompt for a single downstream pass.
+      const lensSections = results.map((result) => result._lensSection).filter(Boolean) as string[];
+      if (ctx.model && config.review.passes > 0 && lensSections.length > 0 && !signal?.aborted) {
+        try {
+          const { resolution, plan, warnings } = resolveModelPlan(
+            config.review,
+            ctx.model,
+            ctx.modelRegistry,
+          );
+          for (const warning of warnings) ctx.ui.notify(warning, 'warning');
+          const basePrompt = buildReviewBasePrompt(lensSections, diff);
+          const pipeline = await runPipeline(
+            resolution,
+            plan,
+            basePrompt,
+            config.review,
+            {
+              onStage: (stage) => {
+                ctx.ui.setStatus('code-review', `🔍 ${stage}...`);
+                onUpdate?.({ content: [{ type: 'text', text: stage }], details: { stage } });
+              },
+            },
+            signal,
+          );
+          ctx.ui.setStatus('code-review', undefined);
+          return {
+            content: [{ type: 'text', text: renderPipelineReport(pipeline, diff) }],
+            details: {
+              mode: 'pipeline',
+              lensCount: lensNames.length,
+              availableLenses: [...available.keys()],
+              changedFiles,
+              findings: pipeline.findings,
+              telemetry: pipeline.telemetry,
+            },
+          };
+        } catch (cause) {
+          // Pipeline failed hard (e.g. model/pi-ai unavailable at runtime) —
+          // degrade to the single-pass prompt instead of failing the review.
+          ctx.ui.setStatus('code-review', undefined);
+          onUpdate?.({
+            content: [{ type: 'text', text: 'pipeline unavailable — single-pass fallback' }],
+            details: { pipelineError: cause instanceof Error ? cause.message : String(cause) },
+          });
+        }
+      }
+
       ctx.ui.setStatus('code-review', undefined);
 
-      // The tool returns a pre-review skeleton + the review task. Findings are
-      // produced by the agent in its follow-up message (per the instructions
-      // below), NOT parsed back here — so we deliberately do not render a
-      // findings scoreboard that would always read "0".
+      // Fallback: return the review task for a single downstream pass (the
+      // agent produces findings in its follow-up message). Used when no model
+      // is available (e.g. print mode) or passes are disabled in config.
       const text = buildToolContext(results, diff);
 
       return {
         content: [{ type: 'text', text }],
         details: {
+          mode: 'single-pass',
           lensCount: lensNames.length,
           availableLenses: [...available.keys()],
-          changedFiles: await getChangedFiles(pi, cwd, {
-            base: params.base,
-            staged: params.staged,
-          }),
+          changedFiles,
         },
       };
     },

package/extensions/code-reviewer/commands/review.ts

@@ -3,7 +3,16 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { loadConfig, getLensDir } from '../config';
 import { collectDiff } from '../diff';
 import { discoverLenses, getLensContent } from '../lenses';
-import { buildDiffSection, buildLensResult, pickLensToolOutputs, runTools } from '../reviewer';
+import { resolveModelPlan } from '../model-plan';
+import { runPipeline } from '../passes';
+import {
+  buildDiffSection,
+  buildLensResult,
+  buildReviewBasePrompt,
+  pickLensToolOutputs,
+  renderPipelineReport,
+  runTools,
+} from '../reviewer';
 import { parseReviewArgs } from '../parse-args';
 
 export function registerReviewCommand(pi: ExtensionAPI) {
@@ -71,6 +80,32 @@ export function registerReviewCommand(pi: ExtensionAPI) {
 
       ctx.ui.setStatus('code-review', undefined);
 
+      // Self-driving path: run the Bugbot-style pipeline in-command and deliver
+      // the validated report in-session for discussion. Mirrors the tool.
+      if (ctx.model && config.review.passes > 0 && lensSections.length > 0) {
+        try {
+          const { resolution, plan, warnings } = resolveModelPlan(
+            config.review,
+            ctx.model,
+            ctx.modelRegistry,
+          );
+          for (const warning of warnings) ctx.ui.notify(warning, 'warning');
+          const basePrompt = buildReviewBasePrompt(lensSections, diff);
+          const pipeline = await runPipeline(resolution, plan, basePrompt, config.review, {
+            onStage: (stage) => ctx.ui.setStatus('code-review', `🔍 ${stage}...`),
+          });
+          ctx.ui.setStatus('code-review', undefined);
+          pi.sendUserMessage(renderPipelineReport(pipeline, diff), { deliverAs: 'followUp' });
+          return;
+        } catch (cause) {
+          ctx.ui.setStatus('code-review', undefined);
+          ctx.ui.notify(
+            `Pipeline unavailable (${cause instanceof Error ? cause.message : String(cause)}) — single-pass fallback`,
+            'warning',
+          );
+        }
+      }
+
       const combinedPrompt = [
         `Review the following changes through ${lensNames.length} lens(es): ${lensNames.join(', ')}.`,
         '',

package/extensions/code-reviewer/config.ts

@@ -10,19 +10,90 @@ import { Effect } from 'effect';
 import { resolve } from 'node:path';
 
 import { FileSystem, nodeFileSystemService } from './effects/filesystem';
-import type { ReviewConfig } from './types';
+import type { ModelStepConfig, ReasoningLevel, ReviewConfig, ReviewPipelineConfig } from './types';
+
+const REASONING_LEVELS = new Set<ReasoningLevel>(['minimal', 'low', 'medium', 'high', 'xhigh']);
 
 const CONFIG_FILE = '.code-review.json';
 const DEFAULT_LENS_DIR = '.code-review/lenses';
 const DEFAULT_TOOL_TIMEOUT_MS = 60_000;
 const DEFAULT_TOOL_CONCURRENCY = 4;
 
+const DEFAULT_PIPELINE: ReviewPipelineConfig = {
+  passes: 5,
+  validate: true,
+  minVotes: 2,
+  concurrency: 5,
+  temperature: 0.4,
+  maxFindings: 50,
+};
+
 function defaultConfig(): ReviewConfig {
   return {
     lensDir: DEFAULT_LENS_DIR,
     defaultLenses: [],
     toolTimeoutMs: DEFAULT_TOOL_TIMEOUT_MS,
     toolConcurrency: DEFAULT_TOOL_CONCURRENCY,
+    review: { ...DEFAULT_PIPELINE },
+  };
+}
+
+/** Coerce a config value to a non-negative integer (0 allowed: disables passes). */
+function nonNegativeIntOr(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0
+    ? Math.floor(value)
+    : fallback;
+}
+
+/** Coerce a config value to a number within [min, max]. */
+function clampNumberOr(value: unknown, fallback: number, min: number, max: number): number {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? Math.min(max, Math.max(min, value))
+    : fallback;
+}
+
+/** Coerce a config value to a model step: a non-empty spec string or
+ *  `{ model, reasoning }`. Returns undefined for anything else. */
+function parseModelStep(value: unknown): ModelStepConfig | undefined {
+  if (typeof value === 'string') return value.trim() ? value.trim() : undefined;
+  if (typeof value === 'object' && value !== null) {
+    const record = value as Record<string, unknown>;
+    const model = typeof record.model === 'string' ? record.model.trim() : '';
+    if (!model) return undefined;
+    const reasoning =
+      typeof record.reasoning === 'string' &&
+      REASONING_LEVELS.has(record.reasoning as ReasoningLevel)
+        ? (record.reasoning as ReasoningLevel)
+        : undefined;
+    return reasoning ? { model, reasoning } : { model };
+  }
+  return undefined;
+}
+
+/** Coerce a config value to a non-empty array of model steps, or undefined. */
+function parseModelStepArray(value: unknown): ModelStepConfig[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const steps = value
+    .map(parseModelStep)
+    .filter((step): step is ModelStepConfig => step !== undefined);
+  return steps.length > 0 ? steps : undefined;
+}
+
+function parsePipeline(raw: unknown): ReviewPipelineConfig {
+  if (typeof raw !== 'object' || raw === null) return { ...DEFAULT_PIPELINE };
+  const review = raw as Record<string, unknown>;
+  const passes = nonNegativeIntOr(review.passes, DEFAULT_PIPELINE.passes);
+  return {
+    passes,
+    validate: typeof review.validate === 'boolean' ? review.validate : DEFAULT_PIPELINE.validate,
+    minVotes: positiveIntOr(review.minVotes, DEFAULT_PIPELINE.minVotes),
+    // Default concurrency tracks pass count so all passes fan out at once.
+    concurrency: positiveIntOr(review.concurrency, Math.max(1, passes)),
+    temperature: clampNumberOr(review.temperature, DEFAULT_PIPELINE.temperature, 0, 2),
+    maxFindings: positiveIntOr(review.maxFindings, DEFAULT_PIPELINE.maxFindings),
+    passModel: parseModelStep(review.passModel),
+    passModels: parseModelStepArray(review.passModels),
+    validateModel: parseModelStep(review.validateModel),
   };
 }
 
@@ -46,6 +117,7 @@ export function loadConfigEffect(cwd: string): Effect.Effect<ReviewConfig, never
         defaultLenses: parsed.defaultLenses ?? [],
         toolTimeoutMs: positiveIntOr(parsed.toolTimeoutMs, DEFAULT_TOOL_TIMEOUT_MS),
         toolConcurrency: positiveIntOr(parsed.toolConcurrency, DEFAULT_TOOL_CONCURRENCY),
+        review: parsePipeline((parsed as { review?: unknown }).review),
       };
     } catch {
       // Malformed config — fall back to defaults.

package/extensions/code-reviewer/effects/model.ts

@@ -0,0 +1,112 @@
+/**
+ * Reviewer service — wraps the session's current model so a single completion
+ * becomes an injectable, typed Effect. The self-driving pipeline (see
+ * `passes.ts`) depends on this Tag; the live implementation drives
+ * `@earendil-works/pi-ai`'s `completeSimple` over `ctx.model`, while tests
+ * provide a deterministic fake instead of calling a real provider.
+ *
+ * `@earendil-works/pi-ai` is an OPTIONAL peer dependency, so the runtime import
+ * is deferred (`import()`), reached only when the harness actually hands us a
+ * model. The extension stays loadable in environments without pi-ai.
+ */
+
+import type { Api, AssistantMessage, Model, TextContent } from '@earendil-works/pi-ai';
+import { Context, Effect } from 'effect';
+
+import { ModelError } from '../errors';
+import type { ReasoningLevel } from '../types';
+
+/** The model key meaning "use the session's current model". */
+export const DEFAULT_MODEL_KEY = 'default';
+
+export type CompletionRequest = {
+  /** Which model to run this call on — {@link DEFAULT_MODEL_KEY} or a key the
+   *  resolution map holds. Unknown keys fall back to the default model. */
+  modelKey: string;
+  system: string;
+  user: string;
+  /** Sampling temperature; the pipeline jitters this per pass. */
+  temperature?: number;
+  /** Reasoning/thinking effort for this call (provider-dependent). */
+  reasoning?: ReasoningLevel;
+  /** Identifies which pipeline stage is calling, for error context. */
+  stage: string;
+  signal?: AbortSignal;
+};
+
+export interface ReviewerService {
+  readonly complete: (request: CompletionRequest) => Effect.Effect<string, ModelError>;
+}
+
+export class Reviewer extends Context.Tag('CodeReviewer/Reviewer')<Reviewer, ReviewerService>() {}
+
+/** Resolved models the pipeline can run against: a default (session) model plus
+ *  any config-specified models keyed by their spec string. */
+export type ModelResolution = {
+  defaultModel: Model<Api>;
+  byKey: Map<string, Model<Api>>;
+};
+
+/** Resolve a config model spec to a registered model. Accepts "provider/id",
+ *  a bare model `id`, a `"provider/id"` composite, or a display `name`. */
+export function resolveModelSpec(
+  registry: { getAll: () => Model<Api>[] },
+  spec: string,
+): Model<Api> | undefined {
+  const trimmed = spec.trim();
+  if (!trimmed) return undefined;
+  const all = registry.getAll();
+
+  const slash = trimmed.indexOf('/');
+  if (slash > 0) {
+    const provider = trimmed.slice(0, slash);
+    const id = trimmed.slice(slash + 1);
+    const exact = all.find((model) => model.provider === provider && model.id === id);
+    if (exact) return exact;
+  }
+  return (
+    all.find((model) => model.id === trimmed) ??
+    all.find((model) => `${model.provider}/${model.id}` === trimmed) ??
+    all.find((model) => model.name === trimmed)
+  );
+}
+
+/** Flatten an assistant message to its plain-text content (drop thinking/tool). */
+export function extractText(message: AssistantMessage): string {
+  return message.content
+    .filter((block): block is TextContent => block.type === 'text')
+    .map((block) => block.text)
+    .join('\n')
+    .trim();
+}
+
+/** Build a live Reviewer that routes each call to the model named by its
+ *  `modelKey` (falling back to the default/session model) via pi-ai. */
+export function makeReviewerService(resolution: ModelResolution): ReviewerService {
+  return {
+    complete: (request) =>
+      Effect.tryPromise({
+        try: async () => {
+          const { completeSimple } = await import('@earendil-works/pi-ai');
+          const model = resolution.byKey.get(request.modelKey) ?? resolution.defaultModel;
+          const message = await completeSimple(
+            model,
+            {
+              systemPrompt: request.system,
+              messages: [{ role: 'user', content: request.user, timestamp: Date.now() }],
+            },
+            {
+              temperature: request.temperature,
+              reasoning: request.reasoning,
+              signal: request.signal,
+            },
+          );
+          if (message.stopReason === 'error') {
+            throw new Error(message.errorMessage ?? 'model returned an error stop reason');
+          }
+          return extractText(message);
+        },
+        catch: (cause) => new ModelError({ stage: request.stage, cause }),
+      }),
+  };
+}

package/extensions/code-reviewer/errors.ts

@@ -28,7 +28,16 @@ export class ExecError extends Data.TaggedError('ExecError')<{
   }
 }
 
-export type CodeReviewerError = FileReadError | ExecError;
+export class ModelError extends Data.TaggedError('ModelError')<{
+  readonly stage: string;
+  readonly cause: unknown;
+}> {
+  get message(): string {
+    return `Model call failed during ${this.stage}: ${causeMessage(this.cause)}`;
+  }
+}
+
+export type CodeReviewerError = FileReadError | ExecError | ModelError;
 
 // ── Helpers ───────────────────────────────────────────────────────────────
 

package/extensions/code-reviewer/model-plan.ts

@@ -0,0 +1,84 @@
+/**
+ * Resolve the per-step model plan for a review run.
+ *
+ * The pipeline can run each step on a different model AND reasoning level so you
+ * can A/B which models / efforts review best / fastest / cheapest. Config
+ * supplies steps as a spec string ("provider/id", a bare id, or a display name)
+ * or `{ model, reasoning }`. This module turns them into a {@link ModelResolution}
+ * (key → real model) plus a {@link ModelPlan} (which model + reasoning each pass
+ * and the validator use). Unresolvable specs degrade to the session model with a
+ * warning, so a typo never fails the review.
+ */
+
+import type { Api, Model } from '@earendil-works/pi-ai';
+
+import { DEFAULT_MODEL_KEY, type ModelResolution, resolveModelSpec } from './effects/model';
+import type { ModelAssignment, ModelPlan, ModelStepConfig, ReviewPipelineConfig } from './types';
+
+export type ResolvedModelPlan = {
+  resolution: ModelResolution;
+  plan: ModelPlan;
+  warnings: string[];
+};
+
+function stepParts(step: ModelStepConfig | undefined): {
+  spec?: string;
+  reasoning?: ModelAssignment['reasoning'];
+} {
+  if (step === undefined) return {};
+  if (typeof step === 'string') return { spec: step };
+  return { spec: step.model, reasoning: step.reasoning };
+}
+
+function labelFor(key: string, reasoning?: ModelAssignment['reasoning']): string {
+  return reasoning ? `${key} (${reasoning})` : key;
+}
+
+export function resolveModelPlan(
+  review: ReviewPipelineConfig,
+  defaultModel: Model<Api>,
+  registry: { getAll: () => Model<Api>[] },
+): ResolvedModelPlan {
+  const byKey = new Map<string, Model<Api>>();
+  const warnings: string[] = [];
+
+  // Resolve one step to an assignment; cache resolved models so a spec
+  // referenced by several passes only resolves once.
+  const assign = (step: ModelStepConfig | undefined): ModelAssignment => {
+    const { spec, reasoning } = stepParts(step);
+    if (!spec || !spec.trim()) {
+      return { key: DEFAULT_MODEL_KEY, label: labelFor(DEFAULT_MODEL_KEY, reasoning), reasoning };
+    }
+    const key = spec.trim();
+    if (key !== DEFAULT_MODEL_KEY && !byKey.has(key)) {
+      const model = resolveModelSpec(registry, key);
+      if (!model) {
+        warnings.push(`review model "${key}" not found — using the session model for those steps`);
+        return { key: DEFAULT_MODEL_KEY, label: labelFor(DEFAULT_MODEL_KEY, reasoning), reasoning };
+      }
+      byKey.set(key, model);
+    }
+    return { key, label: labelFor(key, reasoning), reasoning };
+  };
+
+  // passModels (rotated round-robin) overrides passModel overrides default.
+  const passSteps =
+    review.passModels && review.passModels.length > 0 ? review.passModels : [review.passModel];
+
+  const passes: ModelAssignment[] = [];
+  for (let index = 0; index < review.passes; index += 1) {
+    passes.push(assign(passSteps[index % passSteps.length]));
+  }
+  const validator = assign(review.validateModel);
+
+  return { resolution: { defaultModel, byKey }, plan: { passes, validator }, warnings };
+}
+
+/** Default plan: every step on the session model. Used as a fallback and in tests. */
+export function defaultModelPlan(passes: number): ModelPlan {
+  const step: ModelAssignment = { key: DEFAULT_MODEL_KEY, label: DEFAULT_MODEL_KEY };
+  return {
+    passes: Array.from({ length: passes }, () => ({ ...step })),
+    validator: { ...step },
+  };
+}