@nathapp/nax 0.18.1

package/src/config/schemas.ts

@@ -0,0 +1,286 @@
+/**
+ * Zod Schema Definitions
+ *
+ * Runtime validation schemas for nax configuration.
+ */
+
+import { z } from "zod";
+
+/** Zod schema for runtime validation */
+const TokenPricingSchema = z.object({
+  inputPer1M: z.number().min(0),
+  outputPer1M: z.number().min(0),
+});
+
+const ModelDefSchema = z.object({
+  provider: z.string().min(1, "Provider must be non-empty"),
+  model: z.string().min(1, "Model must be non-empty"),
+  pricing: TokenPricingSchema.optional(),
+  env: z.record(z.string(), z.string()).optional(),
+});
+
+const ModelEntrySchema = z.union([z.string().min(1, "Model identifier must be non-empty"), ModelDefSchema]);
+
+const ModelMapSchema = z.object({
+  fast: ModelEntrySchema,
+  balanced: ModelEntrySchema,
+  powerful: ModelEntrySchema,
+});
+
+const ModelTierSchema = z.string().min(1, "Tier name must be non-empty");
+
+const TierConfigSchema = z.object({
+  tier: z.string().min(1, "Tier name must be non-empty"),
+  attempts: z.number().int().min(1).max(20, { message: "attempts must be 1-20" }),
+});
+
+const AutoModeConfigSchema = z.object({
+  enabled: z.boolean(),
+  defaultAgent: z.string().trim().min(1, "defaultAgent must be non-empty"),
+  fallbackOrder: z.array(z.string()),
+  complexityRouting: z.object({
+    simple: ModelTierSchema,
+    medium: ModelTierSchema,
+    complex: ModelTierSchema,
+    expert: ModelTierSchema,
+  }),
+  escalation: z.object({
+    enabled: z.boolean(),
+    tierOrder: z.array(TierConfigSchema).min(1, { message: "tierOrder must have at least one tier" }),
+    escalateEntireBatch: z.boolean().optional(),
+  }),
+});
+
+const RectificationConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  maxRetries: z.number().int().min(0).max(10).default(2),
+  fullSuiteTimeoutSeconds: z.number().int().min(10).max(600).default(120),
+  maxFailureSummaryChars: z.number().int().min(500).max(10000).default(2000),
+  abortOnIncreasingFailures: z.boolean().default(true),
+});
+
+const RegressionGateConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  timeoutSeconds: z.number().int().min(10).max(600).default(120),
+});
+
+const ExecutionConfigSchema = z.object({
+  maxIterations: z.number().int().positive({ message: "maxIterations must be > 0" }),
+  iterationDelayMs: z.number().int().nonnegative(),
+  costLimit: z.number().positive({ message: "costLimit must be > 0" }),
+  sessionTimeoutSeconds: z.number().int().positive({ message: "sessionTimeoutSeconds must be > 0" }),
+  verificationTimeoutSeconds: z.number().int().min(1).max(3600).default(300),
+  maxStoriesPerFeature: z.number().int().positive(),
+  rectification: RectificationConfigSchema,
+  regressionGate: RegressionGateConfigSchema,
+  contextProviderTokenBudget: z
+    .number()
+    .int()
+    .positive({ message: "contextProviderTokenBudget must be > 0" })
+    .default(2000),
+  lintCommand: z.string().nullable().optional(),
+  typecheckCommand: z.string().nullable().optional(),
+  dangerouslySkipPermissions: z.boolean().default(true),
+});
+
+const QualityConfigSchema = z.object({
+  requireTypecheck: z.boolean(),
+  requireLint: z.boolean(),
+  requireTests: z.boolean(),
+  commands: z.object({
+    typecheck: z.string().optional(),
+    lint: z.string().optional(),
+    test: z.string().optional(),
+  }),
+  forceExit: z.boolean().default(false),
+  detectOpenHandles: z.boolean().default(true),
+  detectOpenHandlesRetries: z.number().int().min(0).max(5).default(1),
+  gracePeriodMs: z.number().int().min(500).max(30000).default(5000),
+  drainTimeoutMs: z.number().int().min(0).max(10000).default(2000),
+  shell: z.string().default("/bin/sh"),
+  stripEnvVars: z.array(z.string()).default(["CLAUDECODE", "REPL_ID", "AGENT"]),
+  environmentalEscalationDivisor: z.number().min(1).max(10).default(2),
+});
+
+const TddConfigSchema = z.object({
+  maxRetries: z.number().int().nonnegative(),
+  autoVerifyIsolation: z.boolean(),
+  autoApproveVerifier: z.boolean(),
+  strategy: z.enum(["auto", "strict", "lite", "off"]).default("auto"),
+  sessionTiers: z
+    .object({
+      testWriter: z.string().optional(),
+      implementer: z.string().optional(),
+      verifier: z.string().optional(),
+    })
+    .optional(),
+  testWriterAllowedPaths: z.array(z.string()).optional(),
+  rollbackOnFailure: z.boolean().optional(),
+  greenfieldDetection: z.boolean().optional(),
+});
+
+const ConstitutionConfigSchema = z.object({
+  enabled: z.boolean(),
+  path: z.string().min(1, "constitution.path must be non-empty"),
+  maxTokens: z.number().int().positive({ message: "constitution.maxTokens must be > 0" }),
+  skipGlobal: z.boolean().optional(),
+});
+
+const AnalyzeConfigSchema = z.object({
+  llmEnhanced: z.boolean(),
+  model: ModelTierSchema,
+  fallbackToKeywords: z.boolean(),
+  maxCodebaseSummaryTokens: z.number().int().positive(),
+});
+
+const ReviewConfigSchema = z.object({
+  enabled: z.boolean(),
+  checks: z.array(z.enum(["typecheck", "lint", "test"])),
+  commands: z.object({
+    typecheck: z.string().optional(),
+    lint: z.string().optional(),
+    test: z.string().optional(),
+  }),
+});
+
+const PlanConfigSchema = z.object({
+  model: ModelTierSchema,
+  outputPath: z.string().min(1, "plan.outputPath must be non-empty"),
+});
+
+const AcceptanceConfigSchema = z.object({
+  enabled: z.boolean(),
+  maxRetries: z.number().int().nonnegative(),
+  generateTests: z.boolean(),
+  testPath: z.string().min(1, "acceptance.testPath must be non-empty"),
+});
+
+const TestCoverageConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  detail: z.enum(["names-only", "names-and-counts", "describe-blocks"]).default("names-and-counts"),
+  maxTokens: z.number().int().min(50).max(5000).default(500),
+  testDir: z.string().optional(),
+  testPattern: z.string().default("**/*.test.{ts,js,tsx,jsx}"),
+  scopeToStory: z.boolean().default(true),
+});
+
+const ContextAutoDetectConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  maxFiles: z.number().int().min(1).max(20).default(5),
+  traceImports: z.boolean().default(false),
+});
+
+const ContextConfigSchema = z.object({
+  testCoverage: TestCoverageConfigSchema,
+  autoDetect: ContextAutoDetectConfigSchema,
+});
+
+const AdaptiveRoutingConfigSchema = z.object({
+  minSamples: z.number().int().positive({ message: "adaptive.minSamples must be > 0" }),
+  costThreshold: z.number().min(0).max(1, { message: "adaptive.costThreshold must be 0-1" }),
+  fallbackStrategy: z.enum(["keyword", "llm", "manual"]),
+});
+
+const LlmRoutingConfigSchema = z.object({
+  model: z.string().optional(),
+  fallbackToKeywords: z.boolean().optional(),
+  cacheDecisions: z.boolean().optional(),
+  mode: z.enum(["one-shot", "per-story", "hybrid"]).optional(),
+  batchMode: z.boolean().optional(), // deprecated, for backward compat
+  timeoutMs: z.number().int().positive({ message: "llm.timeoutMs must be > 0" }).optional(),
+});
+
+const RoutingConfigSchema = z
+  .object({
+    strategy: z.enum(["keyword", "llm", "manual", "adaptive", "custom"]),
+    customStrategyPath: z.string().optional(),
+    adaptive: AdaptiveRoutingConfigSchema.optional(),
+    llm: LlmRoutingConfigSchema.optional(),
+  })
+  .refine(
+    (data) => {
+      // If strategy is "custom", customStrategyPath is required
+      if (data.strategy === "custom" && !data.customStrategyPath) {
+        return false;
+      }
+      return true;
+    },
+    {
+      message: "routing.customStrategyPath is required when strategy is 'custom'",
+      path: ["customStrategyPath"],
+    },
+  );
+
+const OptimizerConfigSchema = z.object({
+  enabled: z.boolean(),
+  strategy: z.enum(["rule-based", "llm", "noop"]).optional(),
+});
+
+const PluginConfigEntrySchema = z.object({
+  module: z.string().min(1, "plugin.module must be non-empty"),
+  config: z.record(z.string(), z.unknown()).optional(),
+});
+
+const HooksConfigSchema = z.object({
+  skipGlobal: z.boolean().optional(),
+  hooks: z.record(z.string(), z.unknown()),
+});
+
+const InteractionConfigSchema = z.object({
+  plugin: z.string().default("cli"),
+  config: z.record(z.string(), z.unknown()).optional(),
+  defaults: z.object({
+    timeout: z.number().int().min(1000).max(3600000).default(600000),
+    fallback: z.enum(["continue", "skip", "escalate", "abort"]).default("escalate"),
+  }),
+  triggers: z
+    .record(
+      z.string(),
+      z.union([
+        z.boolean(),
+        z.object({
+          enabled: z.boolean(),
+          fallback: z.string().optional(),
+          timeout: z.number().optional(),
+        }),
+      ]),
+    )
+    .default({}),
+});
+
+const StorySizeGateConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  maxAcCount: z.number().int().min(1).max(50).default(6),
+  maxDescriptionLength: z.number().int().min(100).max(10000).default(2000),
+  maxBulletPoints: z.number().int().min(1).max(100).default(8),
+});
+
+const PrecheckConfigSchema = z.object({
+  storySizeGate: StorySizeGateConfigSchema,
+});
+
+export const NaxConfigSchema = z
+  .object({
+    version: z.number(),
+    models: ModelMapSchema,
+    autoMode: AutoModeConfigSchema,
+    routing: RoutingConfigSchema,
+    execution: ExecutionConfigSchema,
+    quality: QualityConfigSchema,
+    tdd: TddConfigSchema,
+    constitution: ConstitutionConfigSchema,
+    analyze: AnalyzeConfigSchema,
+    review: ReviewConfigSchema,
+    plan: PlanConfigSchema,
+    acceptance: AcceptanceConfigSchema,
+    context: ContextConfigSchema,
+    optimizer: OptimizerConfigSchema.optional(),
+    plugins: z.array(PluginConfigEntrySchema).optional(),
+    hooks: HooksConfigSchema.optional(),
+    interaction: InteractionConfigSchema.optional(),
+    precheck: PrecheckConfigSchema.optional(),
+  })
+  .refine((data) => data.version === 1, {
+    message: "Invalid version: expected 1",
+    path: ["version"],
+  });

package/src/config/types.ts

@@ -0,0 +1,423 @@
+/**
+ * Configuration Type Definitions
+ *
+ * All TypeScript interfaces, type aliases, and utility functions
+ * for the nax configuration system.
+ */
+
+export type Complexity = "simple" | "medium" | "complex" | "expert";
+export type TestStrategy = "test-after" | "three-session-tdd" | "three-session-tdd-lite";
+export type TddStrategy = "auto" | "strict" | "lite" | "off";
+
+export interface EscalationEntry {
+  from: string;
+  to: string;
+}
+
+/** Model tier names — extensible (TYPE-3 fix: preserve autocomplete for known tiers) */
+export type ModelTier = "fast" | "balanced" | "powerful" | (string & {});
+
+export interface TokenPricing {
+  inputPer1M: number;
+  outputPer1M: number;
+}
+
+export interface ModelDef {
+  provider: string;
+  model: string;
+  pricing?: TokenPricing;
+  env?: Record<string, string>;
+}
+
+export type ModelEntry = ModelDef | string;
+export type ModelMap = Record<ModelTier, ModelEntry>;
+
+export interface TierConfig {
+  tier: string;
+  attempts: number;
+}
+
+/** Auto mode configuration */
+export interface AutoModeConfig {
+  enabled: boolean;
+  /** Default agent to use */
+  defaultAgent: string;
+  /** Fallback order when agent is rate-limited */
+  fallbackOrder: string[];
+  /** Model tier per complexity */
+  complexityRouting: Record<Complexity, ModelTier>;
+  /** Escalation config */
+  escalation: {
+    enabled: boolean;
+    /** Ordered tier escalation with per-tier attempt budgets */
+    tierOrder: TierConfig[];
+    /** When a batch fails, escalate all stories in the batch (default: true) */
+    escalateEntireBatch?: boolean;
+  };
+}
+
+/** Rectification config (v0.11) */
+export interface RectificationConfig {
+  /** Enable rectification loop (retry failed tests with failure context) */
+  enabled: boolean;
+  /** Max retry attempts per story (default: 2) */
+  maxRetries: number;
+  /** Timeout for full test suite run in seconds (default: 120) */
+  fullSuiteTimeoutSeconds: number;
+  /** Max characters in failure summary sent to agent (default: 2000) */
+  maxFailureSummaryChars: number;
+  /** Abort rectification if failure count increases (default: true) */
+  abortOnIncreasingFailures: boolean;
+}
+
+/** Regression gate config (BUG-009) */
+export interface RegressionGateConfig {
+  /** Enable full-suite regression gate after scoped verification (default: true) */
+  enabled: boolean;
+  /** Timeout for full-suite regression run in seconds (default: 120) */
+  timeoutSeconds: number;
+}
+
+/** Execution limits */
+export interface ExecutionConfig {
+  /** Max iterations per feature run (auto-calculated from tierOrder sum if not set) */
+  maxIterations: number;
+  /** Delay between iterations (ms) */
+  iterationDelayMs: number;
+  /** Max cost (USD) before pausing */
+  costLimit: number;
+  /** Timeout per agent coding session (seconds) */
+  sessionTimeoutSeconds: number;
+  /** Verification subprocess timeout in seconds (ADR-003 Decision 4) */
+  verificationTimeoutSeconds: number;
+  /** Max stories per feature (prevents memory exhaustion) */
+  maxStoriesPerFeature: number;
+  /** Rectification loop settings (v0.11) */
+  rectification: RectificationConfig;
+  /** Regression gate settings (BUG-009) */
+  regressionGate: RegressionGateConfig;
+  /** Token budget for plugin context providers (default: 2000) */
+  contextProviderTokenBudget: number;
+  /** Test command override (null = disabled, undefined = auto-detect from package.json) */
+  testCommand?: string | null;
+  /** Lint command override (null = disabled, undefined = auto-detect from package.json) */
+  lintCommand?: string | null;
+  /** Typecheck command override (null = disabled, undefined = auto-detect from package.json) */
+  typecheckCommand?: string | null;
+  /** Use --dangerously-skip-permissions flag for agent (default: true for backward compat, SEC-1 fix) */
+  dangerouslySkipPermissions?: boolean;
+}
+
+/** Quality gate config */
+export interface QualityConfig {
+  /** Require typecheck to pass */
+  requireTypecheck: boolean;
+  /** Require lint to pass */
+  requireLint: boolean;
+  /** Require tests to pass */
+  requireTests: boolean;
+  /** Custom quality commands */
+  commands: {
+    typecheck?: string;
+    lint?: string;
+    test?: string;
+  };
+  /** Append --forceExit to test command to prevent open handle hangs (default: false) */
+  forceExit: boolean;
+  /** Append --detectOpenHandles on timeout retry to diagnose hangs (default: true) */
+  detectOpenHandles: boolean;
+  /** Max retries with --detectOpenHandles before falling back to --forceExit (default: 1) */
+  detectOpenHandlesRetries: number;
+  /** Grace period in ms after SIGTERM before sending SIGKILL (default: 5000) */
+  gracePeriodMs: number;
+  /** Deadline in ms to drain stdout/stderr after killing process (Bun stream workaround, default: 2000) */
+  drainTimeoutMs: number;
+  /** Shell to use for running verification commands (default: /bin/sh) */
+  shell: string;
+  /** Environment variables to strip during verification (prevents AI-optimized output) */
+  stripEnvVars: string[];
+  /** Divisor for environmental failure early escalation (default: 2 = half the tier budget) */
+  environmentalEscalationDivisor: number;
+}
+
+/** TDD config */
+export interface TddConfig {
+  /** Max retries for each session before escalating */
+  maxRetries: number;
+  /** Auto-verify isolation between sessions */
+  autoVerifyIsolation: boolean;
+  /** TDD strategy override (default: 'auto') */
+  strategy: TddStrategy;
+  /** Session 3 verifier: auto-approve legitimate fixes */
+  autoApproveVerifier: boolean;
+  /** Per-session model tier overrides. Defaults: test-writer=balanced, implementer=story tier, verifier=fast */
+  sessionTiers?: {
+    /** Model tier for test-writer session (default: "balanced") */
+    testWriter?: ModelTier;
+    /** Model tier for implementer session (default: uses story's routed tier) */
+    implementer?: ModelTier;
+    /** Model tier for verifier session (default: "fast") */
+    verifier?: ModelTier;
+  };
+  /** Glob patterns for files test-writer can modify (soft violations, logged as warnings) */
+  testWriterAllowedPaths?: string[];
+  /** Rollback git changes when TDD fails (default: true). Prevents partial commits when TDD fails. */
+  rollbackOnFailure?: boolean;
+  /** Enable greenfield detection to force test-after on projects with no test files (default: true, BUG-010) */
+  greenfieldDetection?: boolean;
+}
+
+/** Constitution config */
+export interface ConstitutionConfig {
+  /** Enable constitution loading and injection */
+  enabled: boolean;
+  /** Path to constitution file relative to nax/ directory */
+  path: string;
+  /** Maximum tokens allowed for constitution content */
+  maxTokens: number;
+  /** Skip loading global constitution (default: false) */
+  skipGlobal?: boolean;
+}
+
+/** Analyze config */
+export interface AnalyzeConfig {
+  /** Enable LLM-enhanced analysis */
+  llmEnhanced: boolean;
+  /** Model tier for decompose+classify (default: balanced) */
+  model: ModelTier;
+  /** Fall back to keyword matching on LLM failure */
+  fallbackToKeywords: boolean;
+  /** Max tokens for codebase summary */
+  maxCodebaseSummaryTokens: number;
+}
+
+/** Review config */
+export interface ReviewConfig {
+  /** Enable review phase */
+  enabled: boolean;
+  /** List of checks to run */
+  checks: Array<"typecheck" | "lint" | "test">;
+  /** Custom commands per check */
+  commands: {
+    typecheck?: string;
+    lint?: string;
+    test?: string;
+  };
+}
+
+/** Plan config */
+export interface PlanConfig {
+  /** Model tier for planning (default: balanced) */
+  model: ModelTier;
+  /** Output path for generated spec (relative to nax/ directory) */
+  outputPath: string;
+}
+
+/** Acceptance validation config */
+export interface AcceptanceConfig {
+  /** Enable acceptance test generation and validation */
+  enabled: boolean;
+  /** Maximum retry loops for fix stories (default: 2) */
+  maxRetries: number;
+  /** Generate acceptance tests during analyze (default: true) */
+  generateTests: boolean;
+  /** Path to acceptance test file (relative to feature directory) */
+  testPath: string;
+}
+
+/** Optimizer config (v0.10) */
+export interface OptimizerConfig {
+  /** Enable prompt optimizer */
+  enabled: boolean;
+  /** Optimization strategy: "rule-based" | "llm" | "noop" */
+  strategy?: "rule-based" | "llm" | "noop";
+  /** Strategy-specific configurations */
+  strategies?: {
+    "rule-based"?: {
+      stripWhitespace?: boolean;
+      compactCriteria?: boolean;
+      deduplicateContext?: boolean;
+      maxPromptTokens?: number;
+    };
+    llm?: {
+      model?: ModelTier;
+      targetReduction?: number;
+      minPromptTokens?: number;
+    };
+    custom?: {
+      module?: string;
+      options?: Record<string, unknown>;
+    };
+  };
+}
+
+export interface PluginConfigEntry {
+  module: string;
+  config?: Record<string, unknown>;
+}
+
+export interface HooksConfig {
+  skipGlobal?: boolean;
+  hooks: Record<string, unknown>;
+}
+
+/** Interaction config (v0.15.0) */
+export interface InteractionConfig {
+  /** Plugin to use for interactions (default: "cli") */
+  plugin: string;
+  /** Plugin-specific configuration */
+  config?: Record<string, unknown>;
+  /** Default settings */
+  defaults: {
+    /** Default timeout in milliseconds (default: 600000 = 10 minutes) */
+    timeout: number;
+    /** Default fallback behavior (default: "escalate") */
+    fallback: "continue" | "skip" | "escalate" | "abort";
+  };
+  /** Enable/disable built-in triggers */
+  triggers: Partial<Record<string, boolean | { enabled: boolean; fallback?: string; timeout?: number }>>;
+}
+
+/** Test coverage context config */
+export interface TestCoverageConfig {
+  /** Enable test coverage context injection (default: true) */
+  enabled: boolean;
+  /** Detail level for test summary */
+  detail: "names-only" | "names-and-counts" | "describe-blocks";
+  /** Max tokens for the summary (default: 500) */
+  maxTokens: number;
+  /** Test directory relative to workdir (default: auto-detect) */
+  testDir?: string;
+  /** Glob pattern for test files */
+  testPattern: string;
+  /** Scope test coverage to story-relevant files only (default: true) */
+  scopeToStory: boolean;
+}
+
+export interface ContextAutoDetectConfig {
+  enabled: boolean;
+  maxFiles: number;
+  traceImports: boolean;
+}
+
+export interface ContextConfig {
+  testCoverage: TestCoverageConfig;
+  autoDetect: ContextAutoDetectConfig;
+}
+
+/** Story size gate thresholds (v0.16.0) */
+export interface StorySizeGateConfig {
+  /** Enable story size gate (default: true) */
+  enabled: boolean;
+  /** Max acceptance criteria count before flagging (default: 6) */
+  maxAcCount: number;
+  /** Max description character length before flagging (default: 2000) */
+  maxDescriptionLength: number;
+  /** Max bullet point count before flagging (default: 8) */
+  maxBulletPoints: number;
+}
+
+/** Precheck configuration (v0.16.0) */
+export interface PrecheckConfig {
+  /** Story size gate settings */
+  storySizeGate: StorySizeGateConfig;
+}
+
+export type RoutingStrategyName = "keyword" | "llm" | "manual" | "adaptive" | "custom";
+
+export interface AdaptiveRoutingConfig {
+  minSamples: number;
+  costThreshold: number;
+  fallbackStrategy: "keyword" | "llm" | "manual";
+}
+
+export type LlmRoutingMode = "one-shot" | "per-story" | "hybrid";
+
+/** LLM routing config */
+export interface LlmRoutingConfig {
+  /** Model tier for routing call (default: "fast") */
+  model?: string;
+  /** Fall back to keyword strategy on LLM failure (default: true) */
+  fallbackToKeywords?: boolean;
+  /** Max input tokens for story context (default: 2000) */
+  /** Cache routing decisions per story ID (default: true) */
+  cacheDecisions?: boolean;
+  /** Routing mode (default: "hybrid")
+   * - "one-shot": batch-route ALL pending stories once at run start, use keyword fallback on cache miss
+   * - "per-story": route each story individually just before execution (max LLM calls = N stories)
+   * - "hybrid": batch-route upfront, re-route individually on retry/failure (best quality + cost balance)
+   */
+  mode?: LlmRoutingMode;
+  /** @deprecated Use mode instead. Will be removed in v1.0 */
+  batchMode?: boolean;
+  /** Timeout for LLM call in milliseconds (default: 15000) */
+  timeoutMs?: number;
+}
+
+/** Routing config */
+export interface RoutingConfig {
+  /** Strategy to use (default: "keyword") */
+  strategy: RoutingStrategyName;
+  /** Path to custom strategy file (required if strategy = "custom") */
+  customStrategyPath?: string;
+  /** Adaptive routing settings (used when strategy = "adaptive") */
+  adaptive?: AdaptiveRoutingConfig;
+  /** LLM routing settings (used when strategy = "llm") */
+  llm?: LlmRoutingConfig;
+}
+
+/** Full nax configuration */
+export interface NaxConfig {
+  /** Schema version */
+  version: 1;
+  /** Model mapping — abstract tiers to actual model identifiers */
+  models: ModelMap;
+  /** Auto mode / routing config */
+  autoMode: AutoModeConfig;
+  /** Routing strategy config */
+  routing: RoutingConfig;
+  /** Execution limits */
+  execution: ExecutionConfig;
+  /** Quality gates */
+  quality: QualityConfig;
+  /** TDD settings */
+  tdd: TddConfig;
+  /** Constitution settings */
+  constitution: ConstitutionConfig;
+  /** Analyze settings */
+  analyze: AnalyzeConfig;
+  /** Review settings */
+  review: ReviewConfig;
+  /** Plan settings */
+  plan: PlanConfig;
+  /** Acceptance validation settings */
+  acceptance: AcceptanceConfig;
+  /** Context injection settings */
+  context: ContextConfig;
+  /** Optimizer settings (v0.10) */
+  optimizer?: OptimizerConfig;
+  /** Plugin configurations (v0.10) */
+  plugins?: PluginConfigEntry[];
+  /** Hooks configuration (v0.10) */
+  hooks?: HooksConfig;
+  /** Interaction settings (v0.15.0) */
+  interaction?: InteractionConfig;
+  /** Precheck settings (v0.16.0) */
+  precheck?: PrecheckConfig;
+}
+
+/** Resolve a ModelEntry (string shorthand or full object) into a ModelDef */
+export function resolveModel(entry: ModelEntry): ModelDef {
+  if (typeof entry === "string") {
+    // Infer provider from model name
+    const provider = entry.startsWith("claude")
+      ? "anthropic"
+      : entry.startsWith("gpt") || entry.startsWith("o1") || entry.startsWith("o3")
+        ? "openai"
+        : entry.startsWith("gemini")
+          ? "google"
+          : "unknown";
+    return { provider, model: entry };
+  }
+  return entry;
+}