@nathapp/nax 0.35.0 → 0.36.0

package/src/cli/config.ts

@@ -23,19 +23,27 @@ const FIELD_DESCRIPTIONS: Record<string, string> = {
   "models.powerful": "Powerful model for complex tasks (e.g., opus)",
 
   // Auto mode
-  autoMode: "Auto mode configuration for agent orchestration",
+  autoMode:
+    "Auto mode configuration for agent orchestration. Enables multi-agent routing with model tier selection per task complexity and escalation on failures.",
   "autoMode.enabled": "Enable automatic agent selection and escalation",
-  "autoMode.defaultAgent": "Default agent to use (e.g., claude, codex)",
-  "autoMode.fallbackOrder": "Fallback order when agent is rate-limited",
-  "autoMode.complexityRouting": "Model tier per complexity level",
-  "autoMode.complexityRouting.simple": "Model tier for simple tasks",
-  "autoMode.complexityRouting.medium": "Model tier for medium tasks",
-  "autoMode.complexityRouting.complex": "Model tier for complex tasks",
-  "autoMode.complexityRouting.expert": "Model tier for expert tasks",
-  "autoMode.escalation": "Escalation settings for failed stories",
+  "autoMode.defaultAgent":
+    "Default agent to use when no specific agent is requested. Examples: 'claude' (Claude Code), 'codex' (GitHub Copilot), 'opencode' (OpenCode). The agent handles the main coding tasks.",
+  "autoMode.fallbackOrder":
+    'Fallback order for agent selection when the primary agent is rate-limited, unavailable, or fails. Tries each agent in sequence until one succeeds. Example: ["claude", "codex", "opencode"] means try Claude first, then Copilot, then OpenCode.',
+  "autoMode.complexityRouting":
+    "Model tier routing rules mapped to story complexity levels. Determines which model (fast/balanced/powerful) to use based on task complexity: simple → fast, medium → balanced, complex → powerful, expert → powerful.",
+  "autoMode.complexityRouting.simple": "Model tier for simple tasks (low complexity, straightforward changes)",
+  "autoMode.complexityRouting.medium": "Model tier for medium tasks (moderate complexity, multi-file changes)",
+  "autoMode.complexityRouting.complex": "Model tier for complex tasks (high complexity, architectural decisions)",
+  "autoMode.complexityRouting.expert":
+    "Model tier for expert tasks (highest complexity, novel problems, design patterns)",
+  "autoMode.escalation":
+    "Escalation settings for failed stories. When a story fails after max attempts at current tier, escalate to the next tier in tierOrder. Enables progressive use of more powerful models.",
   "autoMode.escalation.enabled": "Enable tier escalation on failure",
-  "autoMode.escalation.tierOrder": "Ordered tier escalation with per-tier attempt budgets",
-  "autoMode.escalation.escalateEntireBatch": "Escalate all stories in batch when one fails",
+  "autoMode.escalation.tierOrder":
+    'Ordered tier escalation chain with per-tier attempt budgets. Format: [{"tier": "fast", "attempts": 2}, {"tier": "balanced", "attempts": 2}, {"tier": "powerful", "attempts": 1}]. Allows each tier to attempt fixes before escalating to the next.',
+  "autoMode.escalation.escalateEntireBatch":
+    "When enabled, escalate all stories in a batch if one fails. When disabled, only the failing story escalates (allows parallel attempts at different tiers).",
 
   // Routing
   routing: "Model routing strategy configuration",
@@ -528,9 +536,15 @@ function displayConfigWithDescriptions(
 
     // Display description comment if available
     if (description) {
-      // Include path for prompts section (where tests expect "prompts.overrides" to appear)
-      const isPromptsSubSection = currentPathStr.startsWith("prompts.");
-      const comment = isPromptsSubSection ? `${currentPathStr}: ${description}` : description;
+      // Include path for direct subsections of key configuration sections
+      // (to improve clarity of important configs like multi-agent setup)
+      const pathParts = currentPathStr.split(".");
+      // Only show path for 2-level paths (e.g., "autoMode.enabled", "models.fast")
+      // to keep deeply nested descriptions concise
+      const isDirectSubsection = pathParts.length === 2;
+      const isKeySection = ["prompts", "autoMode", "models", "routing"].includes(pathParts[0]);
+      const shouldIncludePath = isKeySection && isDirectSubsection;
+      const comment = shouldIncludePath ? `${currentPathStr}: ${description}` : description;
       console.log(`${indentStr}# ${comment}`);
     }
 

package/src/cli/generate.ts

@@ -26,7 +26,7 @@ export interface GenerateCommandOptions {
   noAutoInject?: boolean;
 }
 
-const VALID_AGENTS: AgentType[] = ["claude", "opencode", "cursor", "windsurf", "aider"];
+const VALID_AGENTS: AgentType[] = ["claude", "codex", "opencode", "cursor", "windsurf", "aider", "gemini"];
 
 /**
  * `nax generate` command handler.

package/src/cli/index.ts

@@ -37,3 +37,4 @@ export {
 } from "./interact";
 export { generateCommand, type GenerateCommandOptions } from "./generate";
 export { configCommand, type ConfigCommandOptions } from "./config";
+export { agentsListCommand } from "./agents";

package/src/context/generator.ts

@@ -11,7 +11,9 @@ import type { NaxConfig } from "../config";
 import { validateFilePath } from "../config/path-security";
 import { aiderGenerator } from "./generators/aider";
 import { claudeGenerator } from "./generators/claude";
+import { codexGenerator } from "./generators/codex";
 import { cursorGenerator } from "./generators/cursor";
+import { geminiGenerator } from "./generators/gemini";
 import { opencodeGenerator } from "./generators/opencode";
 import { windsurfGenerator } from "./generators/windsurf";
 import { buildProjectMetadata } from "./injector";
@@ -20,10 +22,12 @@ import type { AgentContextGenerator, AgentType, ContextContent, GeneratorMap } f
 /** Generator registry */
 const GENERATORS: GeneratorMap = {
   claude: claudeGenerator,
+  codex: codexGenerator,
   opencode: opencodeGenerator,
   cursor: cursorGenerator,
   windsurf: windsurfGenerator,
   aider: aiderGenerator,
+  gemini: geminiGenerator,
 };
 
 /** Generation result for a single agent */

package/src/context/generators/codex.ts

@@ -0,0 +1,28 @@
+/**
+ * Codex Config Generator (v0.16.1)
+ *
+ * Generates codex.md from nax/context.md + auto-injected metadata.
+ */
+
+import { formatMetadataSection } from "../injector";
+import type { AgentContextGenerator, ContextContent } from "../types";
+
+function generateCodexConfig(context: ContextContent): string {
+  const header = `# Codex Instructions
+
+This file is auto-generated from \`nax/context.md\`.
+DO NOT EDIT MANUALLY — run \`nax generate\` to regenerate.
+
+---
+
+`;
+
+  const metaSection = context.metadata ? formatMetadataSection(context.metadata) : "";
+  return header + metaSection + context.markdown;
+}
+
+export const codexGenerator: AgentContextGenerator = {
+  name: "codex",
+  outputFile: "codex.md",
+  generate: generateCodexConfig,
+};

package/src/context/generators/gemini.ts

@@ -0,0 +1,28 @@
+/**
+ * Gemini CLI Config Generator (v0.16.1)
+ *
+ * Generates GEMINI.md from nax/context.md + auto-injected metadata.
+ */
+
+import { formatMetadataSection } from "../injector";
+import type { AgentContextGenerator, ContextContent } from "../types";
+
+function generateGeminiConfig(context: ContextContent): string {
+  const header = `# Gemini CLI Context
+
+This file is auto-generated from \`nax/context.md\`.
+DO NOT EDIT MANUALLY — run \`nax generate\` to regenerate.
+
+---
+
+`;
+
+  const metaSection = context.metadata ? formatMetadataSection(context.metadata) : "";
+  return header + metaSection + context.markdown;
+}
+
+export const geminiGenerator: AgentContextGenerator = {
+  name: "gemini",
+  outputFile: "GEMINI.md",
+  generate: generateGeminiConfig,
+};

package/src/context/types.ts

@@ -40,7 +40,7 @@ export interface AgentContextGenerator {
 }
 
 /** All available generator types */
-export type AgentType = "claude" | "opencode" | "cursor" | "windsurf" | "aider";
+export type AgentType = "claude" | "codex" | "opencode" | "cursor" | "windsurf" | "aider" | "gemini";
 
 /** Generator registry map */
 export type GeneratorMap = Record<AgentType, AgentContextGenerator>;

package/src/pipeline/stages/execution.ts

@@ -36,7 +36,7 @@ import { checkMergeConflict, checkStoryAmbiguity, isTriggerEnabled } from "../..
 import { getLogger } from "../../logger";
 import type { FailureCategory } from "../../tdd";
 import { runThreeSessionTdd } from "../../tdd";
-import { detectMergeConflict } from "../../utils/git";
+import { autoCommitIfDirty, detectMergeConflict } from "../../utils/git";
 import type { PipelineContext, PipelineStage, StageResult } from "../types";
 
 /**
@@ -200,7 +200,7 @@ export const executionStage: PipelineStage = {
     ctx.agentResult = result;
 
     // BUG-058: Auto-commit if agent left uncommitted changes (single-session/test-after)
-    await autoCommitIfDirty(ctx.workdir, "single-session", ctx.story.id);
+    await autoCommitIfDirty(ctx.workdir, "execution", "single-session", ctx.story.id);
 
     // merge-conflict trigger: detect CONFLICT markers in agent output
     const combinedOutput = (result.output ?? "") + (result.stderr ?? "");
@@ -270,40 +270,3 @@ export const _executionDeps = {
   isAmbiguousOutput,
   checkStoryAmbiguity,
 };
-
-/**
- * BUG-058: Auto-commit safety net for single-session/test-after.
- * Mirrors the same function in tdd/session-runner.ts for three-session TDD.
- */
-async function autoCommitIfDirty(workdir: string, role: string, storyId: string): Promise<void> {
-  try {
-    const statusProc = Bun.spawn(["git", "status", "--porcelain"], {
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const statusOutput = await new Response(statusProc.stdout).text();
-    await statusProc.exited;
-
-    if (!statusOutput.trim()) return;
-
-    const logger = getLogger();
-    logger.warn("execution", `Agent did not commit after ${role} session — auto-committing`, {
-      role,
-      storyId,
-      dirtyFiles: statusOutput.trim().split("\n").length,
-    });
-
-    const addProc = Bun.spawn(["git", "add", "-A"], { cwd: workdir, stdout: "pipe", stderr: "pipe" });
-    await addProc.exited;
-
-    const commitProc = Bun.spawn(["git", "commit", "-m", `chore(${storyId}): auto-commit after ${role} session`], {
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    await commitProc.exited;
-  } catch {
-    // Silently ignore — auto-commit is best-effort
-  }
-}

package/src/pipeline/stages/routing.ts

@@ -25,6 +25,7 @@
  * ```
  */
 
+import { getAgent } from "../../agents/registry";
 import type { NaxConfig } from "../../config";
 import { isGreenfieldStory } from "../../context/greenfield";
 import { applyDecomposition } from "../../decompose/apply";
@@ -68,6 +69,10 @@ export const routingStage: PipelineStage = {
   async execute(ctx: PipelineContext): Promise<StageResult> {
     const logger = getLogger();
 
+    // Resolve agent adapter for LLM routing (shared with execution)
+    const agentName = ctx.config.execution?.agent ?? "claude";
+    const adapter = _routingDeps.getAgent(agentName);
+
     // Staleness detection (RRP-003):
     // - story.routing absent                   → cache miss (no prior routing)
     // - story.routing + no contentHash         → legacy cache hit (manual / pre-RRP-003 routing, honor as-is)
@@ -87,7 +92,7 @@ export const routingStage: PipelineStage = {
 
     if (isCacheHit) {
       // Cache hit: legacy routing (no contentHash) or matching contentHash — use cached values
-      routing = await _routingDeps.routeStory(ctx.story, { config: ctx.config }, ctx.workdir, ctx.plugins);
+      routing = await _routingDeps.routeStory(ctx.story, { config: ctx.config, adapter }, ctx.workdir, ctx.plugins);
       // Override with cached values only when they are actually set
       if (ctx.story.routing?.complexity) routing.complexity = ctx.story.routing.complexity;
       // BUG-062: Only honor stored testStrategy for legacy/manual routing (no contentHash).
@@ -106,7 +111,7 @@ export const routingStage: PipelineStage = {
       }
     } else {
       // Cache miss: no routing, or contentHash present but mismatched — fresh classification
-      routing = await _routingDeps.routeStory(ctx.story, { config: ctx.config }, ctx.workdir, ctx.plugins);
+      routing = await _routingDeps.routeStory(ctx.story, { config: ctx.config, adapter }, ctx.workdir, ctx.plugins);
       // currentHash already computed if a mismatch was detected; compute now if starting fresh
       currentHash = currentHash ?? _routingDeps.computeStoryContentHash(ctx.story);
       ctx.story.routing = {
@@ -223,4 +228,5 @@ export const _routingDeps = {
   applyDecomposition,
   runDecompose,
   checkStoryOversized,
+  getAgent,
 };

package/src/precheck/checks-agents.ts

@@ -0,0 +1,63 @@
+/**
+ * Precheck for multi-agent health
+ *
+ * Detects installed agents, reports version information,
+ * and checks health status for each configured agent.
+ */
+
+import { getAgentVersions } from "../agents/version-detection";
+import type { Check } from "./types";
+
+/**
+ * Check multi-agent health: installed agents and their versions
+ *
+ * This is a Tier 2 warning check. Reports which agents are available
+ * and their versions, but doesn't fail if no agents are installed
+ * (since the main configured agent is checked in Tier 1).
+ */
+export async function checkMultiAgentHealth(): Promise<Check> {
+  try {
+    const versions = await getAgentVersions();
+
+    // Separate installed from not installed
+    const installed = versions.filter((v) => v.installed);
+    const notInstalled = versions.filter((v) => !v.installed);
+
+    // Build message with agent status
+    const lines: string[] = [];
+
+    if (installed.length > 0) {
+      lines.push(`Installed agents (${installed.length}):`);
+      for (const agent of installed) {
+        const versionStr = agent.version ? ` v${agent.version}` : " (version unknown)";
+        lines.push(`  • ${agent.displayName}${versionStr}`);
+      }
+    } else {
+      lines.push("No additional agents detected (using default configured agent)");
+    }
+
+    if (notInstalled.length > 0) {
+      lines.push(`\nAvailable but not installed (${notInstalled.length}):`);
+      for (const agent of notInstalled) {
+        lines.push(`  • ${agent.displayName}`);
+      }
+    }
+
+    const message = lines.join("\n");
+
+    return {
+      name: "multi-agent-health",
+      tier: "warning",
+      passed: true, // Always pass - this is informational
+      message,
+    };
+  } catch (error) {
+    // If version detection fails, still pass but report error
+    return {
+      name: "multi-agent-health",
+      tier: "warning",
+      passed: true,
+      message: `Agent detection: ${error instanceof Error ? error.message : "Unknown error"}`,
+    };
+  }
+}

package/src/precheck/checks.ts

@@ -30,3 +30,6 @@ export {
   checkGitignoreCoversNax,
   checkPromptOverrideFiles,
 } from "./checks-warnings";
+
+// Agent checks
+export { checkMultiAgentHealth } from "./checks-agents";

package/src/precheck/index.ts

@@ -17,6 +17,7 @@ import {
   checkGitUserConfigured,
   checkGitignoreCoversNax,
   checkLintCommand,
+  checkMultiAgentHealth,
   checkOptionalCommands,
   checkPRDValid,
   checkPendingStories,
@@ -144,6 +145,7 @@ export async function runPrecheck(
       () => checkOptionalCommands(config, workdir),
       () => checkGitignoreCoversNax(workdir),
       () => checkPromptOverrideFiles(config, workdir),
+      () => checkMultiAgentHealth(),
     ];
 
     for (const checkFn of tier2Checks) {

package/src/tdd/rectification-gate.ts

@@ -11,7 +11,7 @@ import type { ModelTier, NaxConfig } from "../config";
 import { resolveModel } from "../config";
 import type { getLogger } from "../logger";
 import type { UserStory } from "../prd";
-import { captureGitRef } from "../utils/git";
+import { autoCommitIfDirty, captureGitRef } from "../utils/git";
 import {
   type RectificationState,
   executeWithTimeout,
@@ -178,7 +178,7 @@ async function runRectificationLoop(
 
     // BUG-063: Auto-commit after rectification agent — prevents uncommitted changes
     // from leaking into verifier/review stages. Same pattern as session-runner.ts.
-    await autoCommitIfDirty(workdir, "rectification", story.id, logger);
+    await autoCommitIfDirty(workdir, "tdd", "rectification", story.id);
 
     const rectifyIsolation = lite ? undefined : await verifyImplementerIsolation(workdir, rectifyBeforeRef);
 
@@ -231,47 +231,3 @@ async function runRectificationLoop(
   logger.info("tdd", "Full suite gate passed", { storyId: story.id });
   return true;
 }
-
-/**
- * BUG-063: Auto-commit safety net for rectification agent sessions.
- *
- * Rectification runs agent.run() directly (not via runTddSession), so it
- * needs its own auto-commit. Without this, uncommitted changes from
- * rectification leak into verifier/review stages causing spurious failures.
- */
-async function autoCommitIfDirty(
-  workdir: string,
-  role: string,
-  storyId: string,
-  logger: ReturnType<typeof getLogger>,
-): Promise<void> {
-  try {
-    const statusProc = Bun.spawn(["git", "status", "--porcelain"], {
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const statusOutput = await new Response(statusProc.stdout).text();
-    await statusProc.exited;
-
-    if (!statusOutput.trim()) return;
-
-    logger.warn("tdd", `Agent did not commit after ${role} session — auto-committing`, {
-      role,
-      storyId,
-      dirtyFiles: statusOutput.trim().split("\n").length,
-    });
-
-    const addProc = Bun.spawn(["git", "add", "-A"], { cwd: workdir, stdout: "pipe", stderr: "pipe" });
-    await addProc.exited;
-
-    const commitProc = Bun.spawn(["git", "commit", "-m", `chore(${storyId}): auto-commit after ${role} session`], {
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    await commitProc.exited;
-  } catch {
-    // Silently ignore — auto-commit is best-effort
-  }
-}

package/src/tdd/session-runner.ts

@@ -10,6 +10,7 @@ import { resolveModel } from "../config";
 import { getLogger } from "../logger";
 import type { UserStory } from "../prd";
 import { PromptBuilder } from "../prompts";
+import { autoCommitIfDirty } from "../utils/git";
 import { cleanupProcessTree } from "./cleanup";
 import { getChangedFiles, verifyImplementerIsolation, verifyTestWriterIsolation } from "./isolation";
 import type { IsolationCheck } from "./types";
@@ -146,7 +147,7 @@ export async function runTddSession(
   }
 
   // BUG-058: Auto-commit if agent left uncommitted changes
-  await autoCommitIfDirty(workdir, role, story.id);
+  await autoCommitIfDirty(workdir, "tdd", role, story.id);
 
   // Check isolation based on role and skipIsolation flag.
   let isolation: IsolationCheck | undefined;
@@ -200,51 +201,3 @@ export async function runTddSession(
     estimatedCost: result.estimatedCost,
   };
 }
-
-/**
- * BUG-058: Auto-commit safety net.
- *
- * If the agent left uncommitted changes, stage and commit them automatically.
- * This prevents the review stage from failing with "uncommitted changes" errors.
- * Only triggers when the agent forgot — if tree is clean, this is a no-op.
- */
-async function autoCommitIfDirty(workdir: string, role: string, storyId: string): Promise<void> {
-  const logger = getLogger();
-
-  // Check if working tree is dirty
-  try {
-    const statusProc = Bun.spawn(["git", "status", "--porcelain"], {
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const statusOutput = await new Response(statusProc.stdout).text();
-    await statusProc.exited;
-
-    if (!statusOutput.trim()) return; // Clean tree, nothing to do
-
-    logger.warn("tdd", `Agent did not commit after ${role} session — auto-committing`, {
-      role,
-      storyId,
-      dirtyFiles: statusOutput.trim().split("\n").length,
-    });
-
-    // Stage all changes
-    const addProc = Bun.spawn(["git", "add", "-A"], {
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    await addProc.exited;
-
-    // Commit with descriptive message
-    const commitProc = Bun.spawn(["git", "commit", "-m", `chore(${storyId}): auto-commit after ${role} session`], {
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    await commitProc.exited;
-  } catch {
-    // Silently ignore — auto-commit is best-effort
-  }
-}

package/src/tdd/verdict.ts

@@ -117,14 +117,127 @@ function isValidVerdict(obj: unknown): obj is VerifierVerdict {
   return true;
 }
 
+/**
+ * Coerce a free-form verdict object into the expected VerifierVerdict schema.
+ * Maps common agent-improvised patterns (verdict:"PASS", verification_summary, etc.)
+ * to the structured format. Returns null if too malformed to coerce.
+ */
+export function coerceVerdict(obj: Record<string, unknown>): VerifierVerdict | null {
+  try {
+    // Determine approval status
+    const verdictStr = String(obj.verdict ?? "").toUpperCase();
+    const approved = verdictStr === "PASS" || verdictStr === "APPROVED" || obj.approved === true;
+
+    // Parse test results from verification_summary or top-level
+    let passCount = 0;
+    let failCount = 0;
+    let allPassing = approved;
+    const summary = obj.verification_summary as Record<string, unknown> | undefined;
+    if (summary?.test_results && typeof summary.test_results === "string") {
+      // Parse "45/45 PASS" or "42/45 PASS" patterns
+      const match = (summary.test_results as string).match(/(\d+)\/(\d+)/);
+      if (match) {
+        passCount = Number.parseInt(match[1], 10);
+        const total = Number.parseInt(match[2], 10);
+        failCount = total - passCount;
+        allPassing = failCount === 0;
+      }
+    }
+    // Also check top-level tests object (partial schema compliance)
+    if (obj.tests && typeof obj.tests === "object") {
+      const t = obj.tests as Record<string, unknown>;
+      if (typeof t.passCount === "number") passCount = t.passCount;
+      if (typeof t.failCount === "number") failCount = t.failCount;
+      if (typeof t.allPassing === "boolean") allPassing = t.allPassing;
+    }
+
+    // Parse acceptance criteria from acceptance_criteria_review or acceptanceCriteria
+    const criteria: Array<{ criterion: string; met: boolean; note?: string }> = [];
+    let allMet = approved;
+    const acReview = obj.acceptance_criteria_review as Record<string, unknown> | undefined;
+    if (acReview) {
+      for (const [key, val] of Object.entries(acReview)) {
+        if (key.startsWith("criterion") && val && typeof val === "object") {
+          const c = val as Record<string, unknown>;
+          const met = String(c.status ?? "").toUpperCase() === "SATISFIED" || c.met === true;
+          criteria.push({
+            criterion: String(c.name ?? c.criterion ?? key),
+            met,
+            note: c.evidence ? String(c.evidence).slice(0, 200) : undefined,
+          });
+          if (!met) allMet = false;
+        }
+      }
+    }
+    // Also check top-level acceptanceCriteria
+    if (obj.acceptanceCriteria && typeof obj.acceptanceCriteria === "object") {
+      const ac = obj.acceptanceCriteria as Record<string, unknown>;
+      if (typeof ac.allMet === "boolean") allMet = ac.allMet;
+      if (Array.isArray(ac.criteria)) {
+        for (const c of ac.criteria) {
+          if (c && typeof c === "object") {
+            criteria.push(c as { criterion: string; met: boolean; note?: string });
+          }
+        }
+      }
+    }
+    // Parse summary AC count like "4/4 SATISFIED"
+    if (criteria.length === 0 && summary?.acceptance_criteria && typeof summary.acceptance_criteria === "string") {
+      const acMatch = (summary.acceptance_criteria as string).match(/(\d+)\/(\d+)/);
+      if (acMatch) {
+        const met = Number.parseInt(acMatch[1], 10);
+        const total = Number.parseInt(acMatch[2], 10);
+        allMet = met === total;
+      }
+    }
+
+    // Parse quality
+    let rating: "good" | "acceptable" | "poor" = "acceptable";
+    const qualityStr = summary?.code_quality
+      ? String(summary.code_quality).toLowerCase()
+      : obj.quality && typeof obj.quality === "object"
+        ? String((obj.quality as Record<string, unknown>).rating ?? "acceptable").toLowerCase()
+        : "acceptable";
+    if (qualityStr === "high" || qualityStr === "good") rating = "good";
+    else if (qualityStr === "low" || qualityStr === "poor") rating = "poor";
+
+    // Build coerced verdict
+    return {
+      version: 1,
+      approved,
+      tests: { allPassing, passCount, failCount },
+      testModifications: {
+        detected: false,
+        files: [],
+        legitimate: true,
+        reasoning: "Not assessed in free-form verdict",
+      },
+      acceptanceCriteria: { allMet, criteria },
+      quality: { rating, issues: [] },
+      fixes: Array.isArray(obj.fixes) ? (obj.fixes as string[]) : [],
+      reasoning:
+        typeof obj.reasoning === "string"
+          ? obj.reasoning
+          : typeof obj.overall_status === "string"
+            ? (obj.overall_status as string)
+            : summary?.overall_status
+              ? String(summary.overall_status)
+              : `Coerced from free-form verdict: ${verdictStr}`,
+    };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Read the verifier verdict file from the workdir.
  *
  * Returns the parsed VerifierVerdict when the file exists and is valid.
+ * Attempts tolerant coercion if the file doesn't match the strict schema.
  * Returns null if:
  * - File does not exist
  * - File is not valid JSON
- * - Required fields are missing or invalid
+ * - Required fields are missing and coercion fails
  *
  * Never throws.
  */
@@ -150,15 +263,29 @@ export async function readVerdict(workdir: string): Promise<VerifierVerdict | nu
       return null;
     }
 
-    if (!isValidVerdict(parsed)) {
-      logger.warn("tdd", "Verifier verdict file missing required fields — ignoring", {
-        path: verdictPath,
-        content: JSON.stringify(parsed).slice(0, 500),
-      });
-      return null;
+    if (isValidVerdict(parsed)) {
+      return parsed;
+    }
+
+    // Strict validation failed — attempt tolerant coercion
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      const coerced = coerceVerdict(parsed as Record<string, unknown>);
+      if (coerced) {
+        logger.info("tdd", "Coerced free-form verdict to structured format", {
+          path: verdictPath,
+          approved: coerced.approved,
+          passCount: coerced.tests.passCount,
+          failCount: coerced.tests.failCount,
+        });
+        return coerced;
+      }
     }
 
-    return parsed;
+    logger.warn("tdd", "Verifier verdict file missing required fields and coercion failed — ignoring", {
+      path: verdictPath,
+      content: JSON.stringify(parsed).slice(0, 500),
+    });
+    return null;
   } catch (err) {
     logger.warn("tdd", "Failed to read verifier verdict file — ignoring", {
       path: verdictPath,