@nathapp/nax 0.42.0 → 0.42.1

package/bin/nax.ts

@@ -277,6 +277,7 @@ program
   .option("--parallel <n>", "Max parallel sessions (0=auto, omit=sequential)")
   .option("--plan", "Run plan phase first before execution", false)
   .option("--from <spec-path>", "Path to spec file (required when --plan is used)")
+  .option("--one-shot", "Skip interactive planning Q&A, use single LLM call (ACP only)", false)
   .option("--headless", "Force headless mode (disable TUI, use pipe mode)", false)
   .option("--verbose", "Enable verbose logging (debug level)", false)
   .option("--quiet", "Quiet mode (warnings and errors only)", false)
@@ -347,7 +348,7 @@ program
         const generatedPrdPath = await planCommand(workdir, config, {
           from: options.from,
           feature: options.feature,
-          auto: true, // AC-1: --auto mode for one-shot planning
+          auto: options.oneShot ?? false, // interactive by default; --one-shot skips Q&A
           branch: undefined,
         });
 
@@ -625,7 +626,8 @@ program
   .description("Generate prd.json from a spec file via LLM one-shot call (replaces deprecated 'nax analyze')")
   .requiredOption("--from <spec-path>", "Path to spec file (required)")
   .requiredOption("-f, --feature <name>", "Feature name (required)")
-  .option("--auto", "Run in auto (one-shot LLM) mode", false)
+  .option("--auto", "Run in one-shot LLM mode (alias: --one-shot)", false)
+  .option("--one-shot", "Run in one-shot LLM mode (alias: --auto)", false)
   .option("-b, --branch <branch>", "Override default branch name")
   .option("-d, --dir <path>", "Project directory", process.cwd())
   .action(async (description, options) => {
@@ -658,7 +660,7 @@ program
       const prdPath = await planCommand(workdir, config, {
         from: options.from,
         feature: options.feature,
-        auto: options.auto,
+        auto: options.auto || options.oneShot, // --auto and --one-shot are aliases
         branch: options.branch,
       });
 

package/dist/nax.js

@@ -19439,29 +19439,57 @@ class AcpAgentAdapter {
   }
   async complete(prompt, _options) {
     const model = _options?.model ?? "default";
-    const cmdStr = `acpx --model ${model} ${this.name}`;
-    const client = _acpAdapterDeps.createClient(cmdStr);
-    await client.start();
+    const timeoutMs = _options?.timeoutMs ?? 120000;
     const permissionMode = _options?.dangerouslySkipPermissions ? "approve-all" : "default";
-    let session = null;
-    try {
-      session = await client.createSession({ agentName: this.name, permissionMode });
-      const response = await session.prompt(prompt);
-      if (response.stopReason === "error") {
-        throw new CompleteError("complete() failed: stop reason is error");
-      }
-      const text = response.messages.filter((m) => m.role === "assistant").map((m) => m.content).join(`
+    let lastError;
+    for (let attempt = 0;attempt < MAX_RATE_LIMIT_RETRIES; attempt++) {
+      const cmdStr = `acpx --model ${model} ${this.name}`;
+      const client = _acpAdapterDeps.createClient(cmdStr);
+      await client.start();
+      let session = null;
+      try {
+        session = await client.createSession({ agentName: this.name, permissionMode });
+        let timeoutId;
+        const timeoutPromise = new Promise((_, reject) => {
+          timeoutId = setTimeout(() => reject(new Error(`complete() timed out after ${timeoutMs}ms`)), timeoutMs);
+        });
+        timeoutPromise.catch(() => {});
+        const promptPromise = session.prompt(prompt);
+        let response;
+        try {
+          response = await Promise.race([promptPromise, timeoutPromise]);
+        } finally {
+          clearTimeout(timeoutId);
+        }
+        if (response.stopReason === "error") {
+          throw new CompleteError("complete() failed: stop reason is error");
+        }
+        const text = response.messages.filter((m) => m.role === "assistant").map((m) => m.content).join(`
 `).trim();
-      if (!text) {
-        throw new CompleteError("complete() returned empty output");
-      }
-      return text;
-    } finally {
-      if (session) {
-        await session.close().catch(() => {});
+        if (!text) {
+          throw new CompleteError("complete() returned empty output");
+        }
+        return text;
+      } catch (err) {
+        const error48 = err instanceof Error ? err : new Error(String(err));
+        lastError = error48;
+        const shouldRetry = isRateLimitError(error48) && attempt < MAX_RATE_LIMIT_RETRIES - 1;
+        if (!shouldRetry)
+          throw error48;
+        const backoffMs = 2 ** (attempt + 1) * 1000;
+        getSafeLogger()?.warn("acp-adapter", "complete() rate limited, retrying", {
+          backoffSeconds: backoffMs / 1000,
+          attempt: attempt + 1
+        });
+        await _acpAdapterDeps.sleep(backoffMs);
+      } finally {
+        if (session) {
+          await session.close().catch(() => {});
+        }
+        await client.close().catch(() => {});
       }
-      await client.close().catch(() => {});
     }
+    throw lastError ?? new CompleteError("complete() failed with unknown error");
   }
   async plan(options) {
     const modelDef = options.modelDef ?? { provider: "anthropic", model: "default" };
@@ -21807,7 +21835,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@nathapp/nax",
-    version: "0.42.0",
+    version: "0.42.1",
     description: "AI Coding Agent Orchestrator \u2014 loops until done",
     type: "module",
     bin: {
@@ -21872,8 +21900,8 @@ var init_version = __esm(() => {
   NAX_VERSION = package_default.version;
   NAX_COMMIT = (() => {
     try {
-      if (/^[0-9a-f]{6,10}$/.test("a59af3a"))
-        return "a59af3a";
+      if (/^[0-9a-f]{6,10}$/.test("29c340c"))
+        return "29c340c";
     } catch {}
     try {
       const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
@@ -23550,11 +23578,23 @@ ${stderr}`;
         logger.info("acceptance", "All acceptance tests passed");
         return { action: "continue" };
       }
-      if (actualFailures.length === 0 && exitCode !== 0) {
-        logger.warn("acceptance", "Tests failed but no specific AC failures detected", {
+      if (failedACs.length > 0 && actualFailures.length === 0) {
+        logger.info("acceptance", "All failed ACs are overridden \u2014 treating as pass");
+        return { action: "continue" };
+      }
+      if (failedACs.length === 0 && exitCode !== 0) {
+        logger.error("acceptance", "Tests errored with no AC failures parsed", {
+          exitCode,
           output
         });
-        return { action: "continue" };
+        ctx.acceptanceFailures = {
+          failedACs: ["AC-ERROR"],
+          testOutput: output
+        };
+        return {
+          action: "fail",
+          reason: `Acceptance tests errored (exit code ${exitCode}): syntax error, import failure, or unhandled exception`
+        };
       }
       if (actualFailures.length > 0) {
         const overriddenFailures = failedACs.filter((acId) => overrides[acId]);
@@ -65505,6 +65545,7 @@ async function generateAcceptanceTestsForFeature(specContent, featureName, featu
 init_registry();
 import { existsSync as existsSync9 } from "fs";
 import { join as join10 } from "path";
+import { createInterface } from "readline";
 init_logger2();
 
 // src/prd/schema.ts
@@ -65584,7 +65625,9 @@ function validateStory(raw, index, allIds) {
     throw new Error(`[schema] story[${index}].routing.complexity "${rawComplexity}" is invalid. Valid values: ${VALID_COMPLEXITY.join(", ")}`);
   }
   const rawTestStrategy = routing.testStrategy ?? s.testStrategy;
-  const testStrategy = rawTestStrategy !== undefined && VALID_TEST_STRATEGIES.includes(rawTestStrategy) ? rawTestStrategy : "tdd-simple";
+  const STRATEGY_ALIASES = { "tdd-lite": "three-session-tdd-lite" };
+  const normalizedStrategy = typeof rawTestStrategy === "string" ? STRATEGY_ALIASES[rawTestStrategy] ?? rawTestStrategy : rawTestStrategy;
+  const testStrategy = normalizedStrategy !== undefined && VALID_TEST_STRATEGIES.includes(normalizedStrategy) ? normalizedStrategy : "tdd-simple";
   const rawDeps = s.dependencies;
   const dependencies = Array.isArray(rawDeps) ? rawDeps : [];
   for (const dep of dependencies) {
@@ -65722,7 +65765,20 @@ function createCliInteractionBridge() {
       return text.includes("?");
     },
     async onQuestionDetected(text) {
-      return text;
+      if (!process.stdin.isTTY) {
+        return "";
+      }
+      process.stdout.write(`
+\uD83E\uDD16 Agent: ${text}
+You: `);
+      return new Promise((resolve6) => {
+        const rl = createInterface({ input: process.stdin, terminal: false });
+        rl.once("line", (line) => {
+          rl.close();
+          resolve6(line.trim());
+        });
+        rl.once("close", () => resolve6(""));
+      });
     }
   };
 }
@@ -65798,7 +65854,7 @@ Generate a JSON object with this exact structure (no markdown, no explanation \u
       "passes": false,
       "routing": {
         "complexity": "simple | medium | complex | expert",
-        "testStrategy": "test-after | tdd-lite | three-session-tdd",
+        "testStrategy": "test-after | tdd-simple | three-session-tdd | three-session-tdd-lite",
         "reasoning": "string \u2014 brief classification rationale"
       },
       "escalations": [],
@@ -65810,15 +65866,16 @@ Generate a JSON object with this exact structure (no markdown, no explanation \u
 ## Complexity Classification Guide
 
 - simple: \u226450 LOC, single-file change, purely additive, no new dependencies \u2192 test-after
-- medium: 50\u2013200 LOC, 2\u20135 files, standard patterns, clear requirements \u2192 tdd-lite
+- medium: 50\u2013200 LOC, 2\u20135 files, standard patterns, clear requirements \u2192 tdd-simple
 - complex: 200\u2013500 LOC, multiple modules, new abstractions or integrations \u2192 three-session-tdd
-- expert: 500+ LOC, architectural changes, cross-cutting concerns, high risk \u2192 three-session-tdd
+- expert: 500+ LOC, architectural changes, cross-cutting concerns, high risk \u2192 three-session-tdd-lite
 
 ## Test Strategy Guide
 
 - test-after: Simple changes with well-understood behavior. Write tests after implementation.
-- tdd-lite: Medium complexity. Write key tests first, implement, then fill coverage.
-- three-session-tdd: Complex/expert. Full TDD cycle with separate sessions for tests and implementation.
+- tdd-simple: Medium complexity. Write key tests first, implement, then fill coverage.
+- three-session-tdd: Complex stories. Full TDD cycle with separate test-writer and implementer sessions.
+- three-session-tdd-lite: Expert/high-risk stories. Full TDD with additional verifier session.
 
 Output ONLY the JSON object. Do not wrap in markdown code blocks.`;
 }
@@ -76508,7 +76565,7 @@ Run \`nax generate\` to regenerate agent config files (CLAUDE.md, AGENTS.md, .cu
   console.log(source_default.dim(`
 Next: nax features create <name>`));
 });
-program2.command("run").description("Run the orchestration loop for a feature").requiredOption("-f, --feature <name>", "Feature name").option("-a, --agent <name>", "Force a specific agent").option("-m, --max-iterations <n>", "Max iterations", "20").option("--dry-run", "Show plan without executing", false).option("--no-context", "Disable context builder (skip file context in prompts)").option("--no-batch", "Disable story batching (execute all stories individually)").option("--parallel <n>", "Max parallel sessions (0=auto, omit=sequential)").option("--plan", "Run plan phase first before execution", false).option("--from <spec-path>", "Path to spec file (required when --plan is used)").option("--headless", "Force headless mode (disable TUI, use pipe mode)", false).option("--verbose", "Enable verbose logging (debug level)", false).option("--quiet", "Quiet mode (warnings and errors only)", false).option("--silent", "Silent mode (errors only)", false).option("--json", "JSON mode (raw JSONL output to stdout)", false).option("-d, --dir <path>", "Working directory", process.cwd()).option("--skip-precheck", "Skip precheck validations (advanced users only)", false).action(async (options) => {
+program2.command("run").description("Run the orchestration loop for a feature").requiredOption("-f, --feature <name>", "Feature name").option("-a, --agent <name>", "Force a specific agent").option("-m, --max-iterations <n>", "Max iterations", "20").option("--dry-run", "Show plan without executing", false).option("--no-context", "Disable context builder (skip file context in prompts)").option("--no-batch", "Disable story batching (execute all stories individually)").option("--parallel <n>", "Max parallel sessions (0=auto, omit=sequential)").option("--plan", "Run plan phase first before execution", false).option("--from <spec-path>", "Path to spec file (required when --plan is used)").option("--one-shot", "Skip interactive planning Q&A, use single LLM call (ACP only)", false).option("--headless", "Force headless mode (disable TUI, use pipe mode)", false).option("--verbose", "Enable verbose logging (debug level)", false).option("--quiet", "Quiet mode (warnings and errors only)", false).option("--silent", "Silent mode (errors only)", false).option("--json", "JSON mode (raw JSONL output to stdout)", false).option("-d, --dir <path>", "Working directory", process.cwd()).option("--skip-precheck", "Skip precheck validations (advanced users only)", false).action(async (options) => {
   let workdir;
   try {
     workdir = validateDirectory(options.dir);
@@ -76557,7 +76614,7 @@ program2.command("run").description("Run the orchestration loop for a feature").
       const generatedPrdPath = await planCommand(workdir, config2, {
         from: options.from,
         feature: options.feature,
-        auto: true,
+        auto: options.oneShot ?? false,
         branch: undefined
       });
       const generatedPrd = await loadPRD(generatedPrdPath);
@@ -76774,7 +76831,7 @@ Features:
   }
   console.log();
 });
-program2.command("plan [description]").description("Generate prd.json from a spec file via LLM one-shot call (replaces deprecated 'nax analyze')").requiredOption("--from <spec-path>", "Path to spec file (required)").requiredOption("-f, --feature <name>", "Feature name (required)").option("--auto", "Run in auto (one-shot LLM) mode", false).option("-b, --branch <branch>", "Override default branch name").option("-d, --dir <path>", "Project directory", process.cwd()).action(async (description, options) => {
+program2.command("plan [description]").description("Generate prd.json from a spec file via LLM one-shot call (replaces deprecated 'nax analyze')").requiredOption("--from <spec-path>", "Path to spec file (required)").requiredOption("-f, --feature <name>", "Feature name (required)").option("--auto", "Run in one-shot LLM mode (alias: --one-shot)", false).option("--one-shot", "Run in one-shot LLM mode (alias: --auto)", false).option("-b, --branch <branch>", "Override default branch name").option("-d, --dir <path>", "Project directory", process.cwd()).action(async (description, options) => {
   if (description) {
     console.error(source_default.red(`Error: Positional args removed in plan v2.
 
@@ -76798,7 +76855,7 @@ Use: nax plan -f <feature> --from <spec>`));
     const prdPath = await planCommand(workdir, config2, {
       from: options.from,
       feature: options.feature,
-      auto: options.auto,
+      auto: options.auto || options.oneShot,
       branch: options.branch
     });
     console.log(source_default.green(`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.42.0",
+  "version": "0.42.1",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {

package/src/agents/acp/adapter.ts

@@ -552,39 +552,74 @@ export class AcpAgentAdapter implements AgentAdapter {
 
   async complete(prompt: string, _options?: CompleteOptions): Promise<string> {
     const model = _options?.model ?? "default";
-    const cmdStr = `acpx --model ${model} ${this.name}`;
-    const client = _acpAdapterDeps.createClient(cmdStr);
-    await client.start();
-
-    // complete() is one-shot — ephemeral session, no session name, no sidecar
+    const timeoutMs = _options?.timeoutMs ?? 120_000; // 2-min safety net by default
     const permissionMode = _options?.dangerouslySkipPermissions ? "approve-all" : "default";
 
-    let session: AcpSession | null = null;
-    try {
-      session = await client.createSession({ agentName: this.name, permissionMode });
-      const response = await session.prompt(prompt);
+    let lastError: Error | undefined;
 
-      if (response.stopReason === "error") {
-        throw new CompleteError("complete() failed: stop reason is error");
-      }
+    for (let attempt = 0; attempt < MAX_RATE_LIMIT_RETRIES; attempt++) {
+      const cmdStr = `acpx --model ${model} ${this.name}`;
+      const client = _acpAdapterDeps.createClient(cmdStr);
+      await client.start();
 
-      const text = response.messages
-        .filter((m) => m.role === "assistant")
-        .map((m) => m.content)
-        .join("\n")
-        .trim();
+      let session: AcpSession | null = null;
+      try {
+        // complete() is one-shot — ephemeral session, no session name, no sidecar
+        session = await client.createSession({ agentName: this.name, permissionMode });
 
-      if (!text) {
-        throw new CompleteError("complete() returned empty output");
-      }
+        // Enforce timeout via Promise.race — session.prompt() can hang indefinitely
+        let timeoutId: ReturnType<typeof setTimeout> | undefined;
+        const timeoutPromise = new Promise<never>((_, reject) => {
+          timeoutId = setTimeout(() => reject(new Error(`complete() timed out after ${timeoutMs}ms`)), timeoutMs);
+        });
+        timeoutPromise.catch(() => {}); // prevent unhandled rejection if promptPromise wins
 
-      return text;
-    } finally {
-      if (session) {
-        await session.close().catch(() => {});
+        const promptPromise = session.prompt(prompt);
+
+        let response: AcpSessionResponse;
+        try {
+          response = await Promise.race([promptPromise, timeoutPromise]);
+        } finally {
+          clearTimeout(timeoutId);
+        }
+
+        if (response.stopReason === "error") {
+          throw new CompleteError("complete() failed: stop reason is error");
+        }
+
+        const text = response.messages
+          .filter((m) => m.role === "assistant")
+          .map((m) => m.content)
+          .join("\n")
+          .trim();
+
+        if (!text) {
+          throw new CompleteError("complete() returned empty output");
+        }
+
+        return text;
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        lastError = error;
+
+        const shouldRetry = isRateLimitError(error) && attempt < MAX_RATE_LIMIT_RETRIES - 1;
+        if (!shouldRetry) throw error;
+
+        const backoffMs = 2 ** (attempt + 1) * 1000;
+        getSafeLogger()?.warn("acp-adapter", "complete() rate limited, retrying", {
+          backoffSeconds: backoffMs / 1000,
+          attempt: attempt + 1,
+        });
+        await _acpAdapterDeps.sleep(backoffMs);
+      } finally {
+        if (session) {
+          await session.close().catch(() => {});
+        }
+        await client.close().catch(() => {});
       }
-      await client.close().catch(() => {});
     }
+
+    throw lastError ?? new CompleteError("complete() failed with unknown error");
   }
 
   async plan(options: PlanOptions): Promise<PlanResult> {

package/src/agents/types.ts

@@ -100,6 +100,12 @@ export interface CompleteOptions {
   model?: string;
   /** Whether to skip permission prompts (maps to permissionMode in ACP) */
   dangerouslySkipPermissions?: boolean;
+  /**
+   * Timeout for the completion call in milliseconds.
+   * Adapters that support it (e.g. ACP) will enforce this as a hard deadline.
+   * Callers may also wrap complete() in their own Promise.race for shorter timeouts.
+   */
+  timeoutMs?: number;
 }
 
 /**

package/src/cli/plan.ts

@@ -4,11 +4,12 @@
  * Reads a spec file (--from), builds a planning prompt with codebase context,
  * calls adapter.complete(), validates the JSON response, and writes prd.json.
  *
- * Interactive mode is not yet implemented (PLN-002).
+ * Interactive mode: uses ACP session + stdin bridge for Q&A.
  */
 
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { createInterface } from "node:readline";
 import { getAgent } from "../agents/registry";
 import type { AgentAdapter } from "../agents/types";
 import { scanCodebase } from "../analyze/scanner";
@@ -153,15 +154,26 @@ function createCliInteractionBridge(): {
 } {
   return {
     async detectQuestion(text: string): Promise<boolean> {
-      // Simple heuristic: detect if text contains a question mark
       return text.includes("?");
     },
 
     async onQuestionDetected(text: string): Promise<string> {
-      // For now, return the question text as-is to be used as follow-up prompt
-      // In a real CLI, this would read from stdin
-      // TODO: Implement stdin reading for actual CLI interaction
-      return text;
+      // In non-TTY mode (headless/pipes), skip interaction and continue
+      if (!process.stdin.isTTY) {
+        return "";
+      }
+
+      // Print agent question and read one line from stdin
+      process.stdout.write(`\n🤖 Agent: ${text}\nYou: `);
+
+      return new Promise<string>((resolve) => {
+        const rl = createInterface({ input: process.stdin, terminal: false });
+        rl.once("line", (line) => {
+          rl.close();
+          resolve(line.trim());
+        });
+        rl.once("close", () => resolve(""));
+      });
     },
   };
 }
@@ -262,7 +274,7 @@ Generate a JSON object with this exact structure (no markdown, no explanation
       "passes": false,
       "routing": {
         "complexity": "simple | medium | complex | expert",
-        "testStrategy": "test-after | tdd-lite | three-session-tdd",
+        "testStrategy": "test-after | tdd-simple | three-session-tdd | three-session-tdd-lite",
         "reasoning": "string — brief classification rationale"
       },
       "escalations": [],
@@ -274,15 +286,16 @@ Generate a JSON object with this exact structure (no markdown, no explanation
 ## Complexity Classification Guide
 
 - simple: ≤50 LOC, single-file change, purely additive, no new dependencies → test-after
-- medium: 50–200 LOC, 2–5 files, standard patterns, clear requirements → tdd-lite
+- medium: 50–200 LOC, 2–5 files, standard patterns, clear requirements → tdd-simple
 - complex: 200–500 LOC, multiple modules, new abstractions or integrations → three-session-tdd
-- expert: 500+ LOC, architectural changes, cross-cutting concerns, high risk → three-session-tdd
+- expert: 500+ LOC, architectural changes, cross-cutting concerns, high risk → three-session-tdd-lite
 
 ## Test Strategy Guide
 
 - test-after: Simple changes with well-understood behavior. Write tests after implementation.
-- tdd-lite: Medium complexity. Write key tests first, implement, then fill coverage.
-- three-session-tdd: Complex/expert. Full TDD cycle with separate sessions for tests and implementation.
+- tdd-simple: Medium complexity. Write key tests first, implement, then fill coverage.
+- three-session-tdd: Complex stories. Full TDD cycle with separate test-writer and implementer sessions.
+- three-session-tdd-lite: Expert/high-risk stories. Full TDD with additional verifier session.
 
 Output ONLY the JSON object. Do not wrap in markdown code blocks.`;
 }

package/src/pipeline/stages/acceptance.ts

@@ -149,19 +149,34 @@ export const acceptanceStage: PipelineStage = {
     const overrides = ctx.prd.acceptanceOverrides || {};
     const actualFailures = failedACs.filter((acId) => !overrides[acId]);
 
-    // If all failed ACs are overridden, treat as success
+    // If all tests passed cleanly
     if (actualFailures.length === 0 && exitCode === 0) {
       logger.info("acceptance", "All acceptance tests passed");
       return { action: "continue" };
     }
 
-    if (actualFailures.length === 0 && exitCode !== 0) {
-      // Tests failed but we couldn't parse which ACs
-      // This might be a setup/teardown error
-      logger.warn("acceptance", "Tests failed but no specific AC failures detected", {
+    // All parsed AC failures are overridden — treat as success even with non-zero exit
+    if (failedACs.length > 0 && actualFailures.length === 0) {
+      logger.info("acceptance", "All failed ACs are overridden — treating as pass");
+      return { action: "continue" };
+    }
+
+    // Non-zero exit but no AC failures parsed at all — test crashed (syntax error, import failure, etc.)
+    if (failedACs.length === 0 && exitCode !== 0) {
+      logger.error("acceptance", "Tests errored with no AC failures parsed", {
+        exitCode,
         output,
       });
-      return { action: "continue" }; // Don't block on unparseable failures
+
+      ctx.acceptanceFailures = {
+        failedACs: ["AC-ERROR"],
+        testOutput: output,
+      };
+
+      return {
+        action: "fail",
+        reason: `Acceptance tests errored (exit code ${exitCode}): syntax error, import failure, or unhandled exception`,
+      };
     }
 
     // If we have actual failures, report them

package/src/prd/schema.ts

@@ -140,10 +140,14 @@ function validateStory(raw: unknown, index: number, allIds: Set<string>): UserSt
   }
 
   // testStrategy — accept from routing.testStrategy or top-level testStrategy
+  // Also map legacy/LLM-hallucinated aliases: tdd-lite → tdd-simple
   const rawTestStrategy = routing.testStrategy ?? s.testStrategy;
+  const STRATEGY_ALIASES: Record<string, TestStrategy> = { "tdd-lite": "three-session-tdd-lite" };
+  const normalizedStrategy =
+    typeof rawTestStrategy === "string" ? (STRATEGY_ALIASES[rawTestStrategy] ?? rawTestStrategy) : rawTestStrategy;
   const testStrategy: TestStrategy =
-    rawTestStrategy !== undefined && (VALID_TEST_STRATEGIES as unknown[]).includes(rawTestStrategy)
-      ? (rawTestStrategy as TestStrategy)
+    normalizedStrategy !== undefined && (VALID_TEST_STRATEGIES as unknown[]).includes(normalizedStrategy)
+      ? (normalizedStrategy as TestStrategy)
       : "tdd-simple";
 
   // dependencies