avtc-pi-featyard 1.1.0

package/src/review/review-loops.ts

@@ -0,0 +1,217 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Review loop logic — deciding whether to continue review, generating reports,
+ * and transitioning to UAT/finish after review completion.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { NO_COMPACT_CALLBACK, triggerContextCompact } from "../compaction/compact-trigger.js";
+import type { AutoAgentCallback } from "../kanban/auto-agent/auto-agent-state-machine.js";
+import { log } from "../log.js";
+import { syncEnvVarsFromState } from "../phases/env-sync.js";
+import { transitionToFinishPhase, transitionToUatPhase } from "../phases/phase-transitions.js";
+import { toRouteConfig } from "../phases/workflow-router.js";
+import { type FeatyardSettings, getSettings, resolveReviewSkill } from "../settings/settings-ui.js";
+import { NO_AGENT_NAME, NO_FEATURE_STATE_OVERRIDE } from "../shared/workflow-refs.js";
+import type { FeatureSession } from "../state/feature-session.js";
+import { DEFAULT_DIR, type ExpandSkillCommandFn, type FeatureState, saveFeatureState } from "../state/feature-state.js";
+import { schedulePostTurnFollowUp } from "../state/post-turn-dispatch.js";
+import { worthNotesPointerFor } from "../state/worth-notes.js";
+import { NO_FEATURE_STATE, updateWidget } from "../ui/featyard-widget.js";
+import { generateReviewReport } from "./review-report.js";
+
+/** Sentinel for "no review-report context to merge" at the off/after-finish UAT paths and the
+ *  non-loop call sites (manual /fy:next, verify re-entry). Required (no-optional-params convention);
+ *  pass this instead of a bare `null`. */
+export const NO_REVIEW_CONTEXT: {
+  report: string | null;
+  level: "info" | "warning";
+  pointer: string | null;
+} | null = null;
+
+/**
+ * Decide whether a review loop should continue based on settings and results.
+ */
+export function resolveReviewLoopDecision(
+  settings: { reviewLoops: number; minReviewLoops: number },
+  currentLoop: number,
+  issuesFound: number,
+): { shouldLoop: boolean } {
+  const numericMax = settings.reviewLoops;
+  const numericMin = settings.minReviewLoops;
+  const effectiveMax = Math.max(numericMax, numericMin);
+  const loopsCompleted = currentLoop + 1;
+  const minMet = loopsCompleted >= numericMin;
+  const shouldLoop = numericMax !== 0 && (issuesFound > 0 || !minMet) && loopsCompleted < effectiveMax;
+  return { shouldLoop };
+}
+
+/** Dependencies injected from the factory closure */
+export interface ReviewLoopDeps {
+  handler: FeatureSession;
+  expandSkillCommand: ExpandSkillCommandFn;
+  applyModelOverrideForPhase: (pi: ExtensionAPI, ctx: ExtensionContext, stage: string) => Promise<void>;
+  getAutoAgentCallback: () => AutoAgentCallback | null;
+  /** Recover a failed ctx.compact — injected from the compaction module. */
+  recoverCompactFailure: () => void;
+  pi: ExtensionAPI;
+}
+
+export function createReviewLoopHandlers(deps: ReviewLoopDeps) {
+  const { handler, expandSkillCommand, applyModelOverrideForPhase, getAutoAgentCallback, recoverCompactFailure, pi } =
+    deps;
+
+  async function handleReviewLoopEnd(
+    ctx: ExtensionContext,
+    opts: {
+      slug: string;
+      featureState: FeatureState;
+      issuesFound: number;
+      cannotFixIssues: number;
+      logPrefix: string;
+    },
+  ): Promise<void> {
+    const { slug, featureState, issuesFound, cannotFixIssues, logPrefix } = opts;
+    const settings = getSettings();
+    const currentLoop = featureState.review.reviewLoopCount ?? 0;
+    const { shouldLoop } = resolveReviewLoopDecision(
+      { reviewLoops: settings.maxFeatureReviewRounds, minReviewLoops: settings.minReviewLoops },
+      currentLoop,
+      issuesFound,
+    );
+    log.info(
+      `[workflow] DIAGNOSTICS: handleReviewLoopEnd slug=${slug}, currentLoop=${currentLoop}, issuesFound=${issuesFound}, maxFeatureReviewRounds=${settings.maxFeatureReviewRounds}, minReviewLoops=${settings.minReviewLoops}, shouldLoop=${shouldLoop}`,
+    );
+
+    if (shouldLoop) {
+      featureState.review.reviewLoopCount = currentLoop + 1;
+      saveFeatureState(featureState, DEFAULT_DIR);
+      syncEnvVarsFromState(handler);
+      updateWidget(handler, NO_FEATURE_STATE);
+      const reviewSkill = resolveReviewSkill(settings);
+      log.info(`[workflow] DIAGNOSTICS: resolveReviewSkill returned=${reviewSkill}`);
+      if (reviewSkill) {
+        // Compact between review loops (reviewIterationCompact). triggerContextCompact
+        // re-injects the phase skill (fy-review) after compaction; if it doesn't
+        // compact (none / below threshold), fall back to re-dispatching directly.
+        const compacted = await triggerContextCompact(
+          ctx,
+          {
+            settingValue: settings.reviewIterationCompact,
+            skillName: reviewSkill,
+            message: `Run code review iteration #${currentLoop + 1}`,
+            logLabel: "code-review loop compact",
+          },
+          NO_COMPACT_CALLBACK,
+          recoverCompactFailure,
+        );
+        if (!compacted) {
+          const skillText = expandSkillCommand(`/skill:${reviewSkill}`, NO_FEATURE_STATE_OVERRIDE, NO_AGENT_NAME);
+          schedulePostTurnFollowUp(skillText);
+        }
+      }
+    } else {
+      // Loop ends — clean up and transition
+      saveFeatureState(featureState, DEFAULT_DIR);
+
+      // Generate the review report and its level (always computed — needed by the after-review
+      // MERGE below even in headless mode; level is hoisted above the hasUI guard for that).
+      const report = generateReviewReport(featureState);
+      const level: "info" | "warning" = cannotFixIssues > 0 ? "warning" : "info";
+      // Worth-notes pointer (existence + path) for the active feature — merged into the boundary
+      // notify so it never stands alone (notifications are exclusive). Absent/empty → null.
+      const pointer = worthNotesPointerFor(slug);
+
+      // uatMode after-review: the report + UAT-handoff + worth-notes pointer are MERGED into ONE
+      // notification — the standalone report notify is suppressed on this path so the
+      // handoff doesn't hide it (pre-existing data-loss bug). off/after-finish keep the standalone
+      // report notify (the natural review-completion boundary) with the worth-notes pointer appended.
+      const guard = globalThis.__piCtx;
+      const hasUi = guard?.hasUI && guard?.ui?.notify;
+      if (settings.uatMode !== "after-review" && hasUi) {
+        guard.ui.notify(pointer ? `${report}\n\n${pointer}` : report, level);
+      }
+      // Always log the report in headless mode (or after-review, where the standalone notify is
+      // suppressed in favor of the merged handoff) so the review stats remain observable there.
+      if (!hasUi) {
+        log.info(`[workflow] ${logPrefix} — report: ${report}`);
+      }
+
+      // Transition to UAT based on uatMode setting. For after-review, thread the report + level
+      // + pointer so handleReviewToUatTransition builds the combined notify (report + handoff +
+      // pointer) in ONE notification with the report's level.
+      await handleReviewToUatTransition(ctx, slug, settings, { report, level, pointer });
+    }
+  }
+
+  /**
+   * Handle transition from completed review phase to UAT/finish based on uatMode.
+   * Called after review loop ends (shouldLoop=false) or zero-issues review.
+   */
+  async function handleReviewToUatTransition(
+    ctx: ExtensionContext,
+    slug: string,
+    settings: FeatyardSettings,
+    // Optional review-report context. Provided by handleReviewLoopEnd on the
+    // after-review path so the report + UAT-handoff + worth-notes pointer MERGE into ONE notify
+    // (notifications are exclusive — otherwise the handoff hides the report). null at the
+    // off/after-finish paths and the non-loop call sites (no merge there) — required per the
+    // project's no-optional-params convention; explicit null passed from those call sites.
+    reportCtx: { report: string | null; level: "info" | "warning"; pointer: string | null } | null,
+  ): Promise<void> {
+    const uatMode = settings.uatMode;
+    log.info(`[workflow] handleReviewToUatTransition: uatMode=${uatMode}, slug=${slug}`);
+
+    // Complete the review phase FIRST
+    handler.completeCurrentWorkflowPhase(toRouteConfig(settings)); // marks review as "complete"
+
+    // Load feature state once — each branch syncs handler workflow state into it
+    const featureState = handler.getActiveFeatureState();
+
+    if (uatMode === "off") {
+      // Skip UAT, auto-proceed to finish
+      handler.setCurrentPhase("finish"); // skip
+      await transitionToFinishPhase(featureState, { pi, ctx, handler, applyModelOverrideForPhase, expandSkillCommand });
+    } else if (uatMode === "after-review") {
+      // Pause at UAT — user advances via /fy:next (works in place, then advances).
+      // MERGE the review report + UAT-handoff + worth-notes pointer into ONE notification (design
+      // ): the report notify was already suppressed in handleReviewLoopEnd for this path,
+      // so the combined message here is the single boundary notify that carries everything. The
+      // report's level (warning if cannot-fix) is preserved via notifyLevel.
+      const handoffMsg = `Feature "${slug}" is ready for UAT. Work in place, then /fy:next to advance.`;
+      const report = reportCtx?.report;
+      const pointer = reportCtx?.pointer;
+      const notifyMessage =
+        report != null
+          ? pointer
+            ? `${report}\n\n${handoffMsg}\n${pointer}`
+            : `${report}\n\n${handoffMsg}`
+          : pointer
+            ? `${handoffMsg}\n${pointer}`
+            : handoffMsg;
+      await transitionToUatPhase(
+        ctx,
+        slug,
+        featureState,
+        {
+          pi,
+          handler,
+          applyModelOverrideForPhase,
+          getAutoAgentCallback,
+        },
+        {
+          kanbanNote: "review complete — UAT handoff",
+          notifyMessage,
+          notifyLevel: reportCtx?.level,
+        },
+      );
+    } else if (uatMode === "after-finish") {
+      // Proceed to finish; after-finish UAT is driven by the derived check in phase_ready.
+      await transitionToFinishPhase(featureState, { pi, ctx, handler, applyModelOverrideForPhase, expandSkillCommand });
+    }
+  }
+
+  return { handleReviewLoopEnd, handleReviewToUatTransition };
+}

package/src/review/review-report.ts

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Review report generation.
+ *
+ * Produces a plain-text summary of review-round history from feature state.
+ *
+ * History partitioning: every entry carries a `phase` tag (design | plan | review).
+ * The report groups entries by phase (in phase order) and shows a per-phase subtotal,
+ * then overall totals. Entries that predate phase tagging (legacy) lack the tag and
+ * are excluded entirely — they cannot be reliably attributed to a phase.
+ *
+ * NOTE: the report is delivered via `ui.notify`, which renders PLAIN TEXT (a single
+ * Text component, no markdown parsing). Do not use markdown markers (##, **, |, -).
+ */
+
+import type { FeatureState, ReviewHistoryEntry, ReviewPhase } from "../state/feature-state.js";
+
+const PHASE_ORDER: ReviewPhase[] = ["design", "plan", "review"];
+
+const PHASE_LABEL: Record<ReviewPhase, string> = {
+  design: "Design Review",
+  plan: "Plan Review",
+  review: "Code Review",
+};
+
+/** A tagged entry belongs to a known review phase. Legacy entries (no phase) are excluded. */
+function isTaggedEntry(entry: ReviewHistoryEntry): entry is ReviewHistoryEntry & { phase: ReviewPhase } {
+  return entry.phase === "design" || entry.phase === "plan" || entry.phase === "review";
+}
+
+/**
+ * Entries that carry a phase tag and thus appear in reports. Legacy untagged entries
+ * (from before phase tagging) are excluded — they cannot be reliably attributed to a
+ * phase and would misattribute stats. Shared by the report and the cannot-fix level scan
+ * so they stay consistent.
+ */
+export function getReportableReviewHistory(featureState: FeatureState): ReviewHistoryEntry[] {
+  return (featureState.review.reviewHistory ?? []).filter(isTaggedEntry);
+}
+
+/** `1 issue` / `2 issues`, `1 false positive` / `2 false positives`. */
+function plural(n: number, singular: string, pluralForm: string): string {
+  return n === 1 ? singular : pluralForm;
+}
+
+/** Format one count line: `5 issues found, 1 false positive, 2 cannot-fix`. */
+function formatCounts(issues: number, falsePositives: number, cannotFix: number): string {
+  return (
+    `${issues} ${plural(issues, "issue", "issues")} found, ` +
+    `${falsePositives} ${plural(falsePositives, "false positive", "false positives")}, ` +
+    `${cannotFix} cannot-fix`
+  );
+}
+
+export function generateReviewReport(featureState: FeatureState): string {
+  const history = getReportableReviewHistory(featureState);
+  const lines: string[] = ["Review Round Summary"];
+
+  let totalIssues = 0;
+  let totalFalsePositives = 0;
+  let totalCannotFix = 0;
+
+  for (const phase of PHASE_ORDER) {
+    const entries = history.filter((e) => e.phase === phase);
+    if (entries.length === 0) continue;
+
+    const label = PHASE_LABEL[phase];
+    lines.push("");
+    lines.push(label);
+
+    let phaseIssues = 0;
+    let phaseFalsePositives = 0;
+    let phaseCannotFix = 0;
+    for (const entry of entries) {
+      lines.push(
+        `  Round #${entry.loopNumber}: ${formatCounts(entry.issuesFound, entry.falsePositives, entry.cannotFixIssues)}`,
+      );
+      phaseIssues += entry.issuesFound;
+      phaseFalsePositives += entry.falsePositives;
+      phaseCannotFix += entry.cannotFixIssues;
+    }
+    lines.push(`  ${label} total: ${formatCounts(phaseIssues, phaseFalsePositives, phaseCannotFix)}`);
+
+    totalIssues += phaseIssues;
+    totalFalsePositives += phaseFalsePositives;
+    totalCannotFix += phaseCannotFix;
+  }
+
+  lines.push("");
+  lines.push(
+    `Totals: ${totalIssues} ${plural(totalIssues, "issue", "issues")} found across ${history.length} ${plural(history.length, "round", "rounds")}`,
+  );
+  lines.push(`  False positives: ${totalFalsePositives}`);
+  if (totalCannotFix > 0) {
+    lines.push(`  ⚠️ Cannot fix: ${totalCannotFix}`);
+  }
+
+  return lines.join("\n");
+}

package/src/settings/model-overrides.ts

@@ -0,0 +1,269 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 avtc <tarasenkov@gmail.com>
+
+/**
+ * Featyard-specific model override configuration.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { log } from "../log.js";
+// (no pi-tui or avtc-pi-settings-ui imports needed — model overrides are not rendered as a settings tab)
+
+export type ModelOverride = string | string[];
+
+export interface FeatyardConfig {
+  "stage-models"?: Record<string, ModelOverride>;
+  "default-model": string | null;
+  "kanban-port"?: number | null;
+  /** File extensions counted as "source" files by the pre-commit/coverage gate (e.g. [".ts",".py"], ["+.md","-.css"]). null = use built-in defaults. */
+  "source-extensions"?: string[] | null;
+}
+
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+
+function isValidModelString(val: unknown): val is string {
+  if (typeof val !== "string") return false;
+  const idx = val.indexOf("/");
+  return idx > 0 && idx < val.length - 1;
+}
+
+function validateDefaultModel(val: unknown): string | null {
+  if (val == null) return null;
+  if (isValidModelString(val)) return val;
+  log.warn(`Skipping invalid default-model: ${JSON.stringify(val)}`);
+  return null;
+}
+
+function validateKanbanPort(val: unknown): number | null {
+  if (val == null) return null;
+  if (typeof val === "number" && Number.isInteger(val) && val >= 1 && val <= 65535) return val;
+  log.warn(`Skipping invalid kanban-port: ${JSON.stringify(val)} (must be integer 1-65535 or null)`);
+  return null;
+}
+
+/** Validate a source-extensions entry: must be a non-empty array of strings, else null. */
+function validateSourceExtensions(val: unknown): string[] | null {
+  if (val == null) return null;
+  if (Array.isArray(val) && val.every((v) => typeof v === "string")) {
+    return val.filter((v) => v.trim().length > 0);
+  }
+  log.warn(`Skipping invalid source-extensions: ${JSON.stringify(val)} (must be array of strings or null)`);
+  return null;
+}
+
+function validateOverride(val: unknown): ModelOverride | null {
+  if (isValidModelString(val)) return val;
+  if (Array.isArray(val)) {
+    const valid = val.filter((v) => isValidModelString(v));
+    return valid.length > 0 ? valid : null;
+  }
+  return null;
+}
+
+function filterValidOverrides(globalRaw: unknown, projectRaw: unknown): Record<string, ModelOverride> {
+  const result: Record<string, ModelOverride> = {};
+  for (const raw of [globalRaw, projectRaw]) {
+    if (typeof raw !== "object" || raw === null) continue;
+    for (const [key, val] of Object.entries(raw as Record<string, unknown>)) {
+      const validated = validateOverride(val);
+      if (validated) {
+        result[key] = validated;
+      } else if (val !== undefined) {
+        log.warn(`Skipping invalid model override '${key}': ${JSON.stringify(val)}`);
+      }
+    }
+  }
+  return result;
+}
+
+function extractFeatyardSection(raw: Record<string, unknown> | null): Record<string, unknown> | null {
+  if (!raw) return null;
+  const sp = raw["avtc-pi-featyard"];
+  if (!sp || typeof sp !== "object") return null;
+  return sp as Record<string, unknown>;
+}
+
+function readJsonFile(filePath: string): Record<string, unknown> | null {
+  try {
+    if (!existsSync(filePath)) return null;
+    const raw = readFileSync(filePath, "utf-8");
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch (err) {
+    log.warn(`readJsonFile failed for ${filePath}: ${err instanceof Error ? err.message : err}`);
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Config loading
+// ---------------------------------------------------------------------------
+
+function emptyConfig(): Required<FeatyardConfig> {
+  return {
+    "stage-models": {},
+    "default-model": null,
+    "kanban-port": null,
+    "source-extensions": null,
+  };
+}
+
+let _config: Required<FeatyardConfig> = emptyConfig();
+let _configLoaded = false;
+/** Serialized snapshot of the last loaded config, used to detect changes. */
+let _configSnapshot: string | null = null;
+
+function getDefaultGlobalDir(): string {
+  return join(homedir(), ".pi");
+}
+
+/** Read featyard sections from global and project config files. */
+function readConfigSections(
+  globalDir: string | null,
+  cwd: string | null,
+): {
+  globalSection: Record<string, unknown> | null;
+  projectSection: Record<string, unknown> | null;
+} {
+  const globalPath = join(globalDir ?? getDefaultGlobalDir(), "agent", "settings.json");
+  const globalSection = extractFeatyardSection(readJsonFile(globalPath));
+
+  let projectSection: Record<string, unknown> | null = null;
+  if (cwd) {
+    const projectPath = join(cwd, ".pi", "settings.json");
+    projectSection = extractFeatyardSection(readJsonFile(projectPath));
+  }
+
+  return { globalSection, projectSection };
+}
+
+/** Pass as `cwd` when no working directory override is needed. */
+/** Sentinel: no working directory override (use process.cwd()) */
+export const NO_CWD_OVERRIDE: string | null = null;
+
+/** Sentinel: no working directory specified (use process.cwd()) */
+export const NO_CWD: string | null = null;
+
+/** Sentinel: use the default global directory (the shared ~/.pi/agent/settings.json). */
+export const DEFAULT_GLOBAL_DIR: string | null = null;
+
+export function loadFeatyardConfig(globalDir: string | null, cwd: string | null): Required<FeatyardConfig> {
+  if (_configLoaded) return _config;
+
+  const { globalSection, projectSection } = readConfigSections(globalDir, cwd);
+
+  if (!globalSection && !projectSection) {
+    _config = emptyConfig();
+    _configLoaded = true;
+    _configSnapshot = JSON.stringify({ global: null, project: null });
+    return _config;
+  }
+
+  const globalModels = globalSection ?? {};
+  const projectModels = projectSection ?? {};
+
+  _config = {
+    "stage-models": filterValidOverrides(globalModels["stage-models"], projectModels["stage-models"]),
+    "default-model": validateDefaultModel(
+      "default-model" in projectModels ? projectModels["default-model"] : globalModels["default-model"],
+    ),
+    "kanban-port": validateKanbanPort(
+      "kanban-port" in projectModels ? projectModels["kanban-port"] : globalModels["kanban-port"],
+    ),
+    "source-extensions": validateSourceExtensions(
+      "source-extensions" in projectModels ? projectModels["source-extensions"] : globalModels["source-extensions"],
+    ),
+  };
+
+  _configLoaded = true;
+  _configSnapshot = JSON.stringify({ global: globalSection, project: projectSection });
+  log.info(
+    `Featyard config loaded: ${Object.keys(_config["stage-models"] ?? {}).length} stage-models, default-model=${_config["default-model"] ?? "<none>"}, kanban-port=${_config["kanban-port"] ?? "random"}, source-extensions=${_config["source-extensions"] ? "custom" : "default"}`,
+  );
+  return _config;
+}
+
+export function resetFeatyardConfig(): void {
+  _config = emptyConfig();
+  _configLoaded = false;
+  _configSnapshot = null;
+}
+
+export function setFeatyardConfig(config: Required<FeatyardConfig>): void {
+  _config = config;
+  _configLoaded = true;
+}
+
+export function invalidateConfigCache(): void {
+  _configLoaded = false;
+}
+
+/**
+ * Invalidate config cache only if the model-related config section actually changed.
+ * Reads the current config from disk and compares to the cached snapshot.
+ * This avoids unnecessary re-reads when only non-model settings were saved.
+ */
+export function invalidateConfigCacheIfChanged(globalDir: string | null, cwd: string | null): void {
+  if (!_configLoaded) return; // Already invalidated — nothing to check
+
+  const { globalSection, projectSection } = readConfigSections(globalDir, cwd);
+  const currentSnapshot = JSON.stringify({ global: globalSection, project: projectSection });
+  if (currentSnapshot !== _configSnapshot) {
+    _configLoaded = false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Model resolution
+// ---------------------------------------------------------------------------
+
+function resolveOverride(override: ModelOverride, loopIndex: number): string | null {
+  if (Array.isArray(override)) {
+    if (override.length === 0) return null;
+    const idx = ((loopIndex % override.length) + override.length) % override.length;
+    return override[idx] ?? null;
+  }
+  return override;
+}
+
+export function resolveModelOverride(stage: string | null, loopIndex: number, config: FeatyardConfig): string | null {
+  // Workflow callers (phase-transitions, review-context): stage-models -> default-model.
+  // If a stage-models entry EXISTS for the active stage, return its resolution
+  // (even if it resolves to null, e.g. an empty array) — do NOT fall through to
+  // default-model. default-model applies only when no entry exists for the stage.
+  // The entry is captured once (avoids double lookup) and the truthy guard mirrors
+  // the original semantics (arrays are truthy; empty/missing entries skip).
+  const entry = stage ? config["stage-models"]?.[stage] : undefined;
+  if (entry) return resolveOverride(entry, loopIndex);
+  // Truthy check (not ??) preserves original behavior: an empty-string
+  // default-model is treated as absent (validated configs never have "", but
+  // raw configs passed directly could).
+  if (config["default-model"]) return config["default-model"];
+  return null;
+}
+
+/**
+ * Stage-models only, NO default-model fallthrough. Used by the subagent hook so it
+ * yields to pi-subagent's Phase 3 default instead of shadowing it.
+ */
+export function resolveStageModelOnly(stage: string | null, loopIndex: number, config: FeatyardConfig): string | null {
+  const entry = stage ? config["stage-models"]?.[stage] : undefined;
+  if (entry) return resolveOverride(entry, loopIndex);
+  return null;
+}
+
+export function resolveReviewSkill(settings: { maxFeatureReviewRounds: number }): string | null {
+  if (settings.maxFeatureReviewRounds === 0) return null;
+  return "fy-review";
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+export function _resetModelResolution(): void {
+  _configLoaded = false;
+}