@nathapp/nax 0.41.0 → 0.42.1

package/dist/nax.js

@@ -18253,7 +18253,7 @@ class ClaudeCodeAdapter {
             const backoffMs = 2 ** attempt * 1000;
             const logger = getLogger();
             logger.warn("agent", "Rate limited, retrying", { backoffSeconds: backoffMs / 1000, attempt, maxRetries });
-            await Bun.sleep(backoffMs);
+            await _claudeAdapterDeps.sleep(backoffMs);
             continue;
           }
           return result;
@@ -18269,7 +18269,7 @@ class ClaudeCodeAdapter {
               attempt,
               maxRetries
             });
-            await Bun.sleep(backoffMs);
+            await _claudeAdapterDeps.sleep(backoffMs);
             continue;
           }
           throw lastError;
@@ -18349,7 +18349,7 @@ class ClaudeCodeAdapter {
     return runInteractiveMode(this.binary, options, pidRegistry);
   }
 }
-var _decomposeDeps;
+var _decomposeDeps, _claudeAdapterDeps;
 var init_claude = __esm(() => {
   init_pid_registry();
   init_logger2();
@@ -18362,6 +18362,9 @@ var init_claude = __esm(() => {
       return Bun.spawn(cmd, opts);
     }
   };
+  _claudeAdapterDeps = {
+    sleep: (ms) => Bun.sleep(ms)
+  };
 });
 
 // src/utils/errors.ts
@@ -19401,7 +19404,7 @@ class AcpAgentAdapter {
           break;
         }
       }
-      if (turnCount >= MAX_TURNS) {
+      if (turnCount >= MAX_TURNS && options.interactionBridge) {
         getSafeLogger()?.warn("acp-adapter", "Reached max turns limit", { sessionName, maxTurns: MAX_TURNS });
       }
     } finally {
@@ -19436,34 +19439,59 @@ 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) {
-    if (options.interactive) {
-      throw new Error("[acp-adapter] plan() interactive mode is not yet supported via ACP");
-    }
     const modelDef = options.modelDef ?? { provider: "anthropic", model: "default" };
     const timeoutSeconds = options.timeoutSeconds ?? options.config?.execution?.sessionTimeoutSeconds ?? 600;
     const result = await this.run({
@@ -21807,7 +21835,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@nathapp/nax",
-    version: "0.41.0",
+    version: "0.42.1",
     description: "AI Coding Agent Orchestrator \u2014 loops until done",
     type: "module",
     bin: {
@@ -21819,11 +21847,12 @@ var init_package = __esm(() => {
       build: 'bun build bin/nax.ts --outdir dist --target bun --define "GIT_COMMIT=\\"$(git rev-parse --short HEAD)\\""',
       typecheck: "bun x tsc --noEmit",
       lint: "bun x biome check src/ bin/",
-      test: "NAX_SKIP_PRECHECK=1 bun test test/ --timeout=60000",
-      "test:watch": "bun test --watch",
-      "test:unit": "bun test ./test/unit/ --timeout=60000",
-      "test:integration": "bun test ./test/integration/ --timeout=60000",
-      "test:ui": "bun test ./test/ui/ --timeout=60000",
+      test: "CI=1 NAX_SKIP_PRECHECK=1 bun test test/ --timeout=60000",
+      "test:watch": "CI=1 bun test --watch",
+      "test:unit": "CI=1 NAX_SKIP_PRECHECK=1 bun test ./test/unit/ --timeout=60000",
+      "test:integration": "CI=1 NAX_SKIP_PRECHECK=1 bun test ./test/integration/ --timeout=60000",
+      "test:ui": "CI=1 bun test ./test/ui/ --timeout=60000",
+      "test:real": "NAX_SKIP_PRECHECK=1 bun test test/ --timeout=60000",
       "check-test-overlap": "bun run scripts/check-test-overlap.ts",
       "check-dead-tests": "bun run scripts/check-dead-tests.ts",
       "check:test-sizes": "bun run scripts/check-test-sizes.ts",
@@ -21871,8 +21900,8 @@ var init_version = __esm(() => {
   NAX_VERSION = package_default.version;
   NAX_COMMIT = (() => {
     try {
-      if (/^[0-9a-f]{6,10}$/.test("0db1c5f"))
-        return "0db1c5f";
+      if (/^[0-9a-f]{6,10}$/.test("29c340c"))
+        return "29c340c";
     } catch {}
     try {
       const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
@@ -21890,6 +21919,23 @@ var init_version = __esm(() => {
   NAX_BUILD_INFO = NAX_COMMIT === "dev" ? `v${NAX_VERSION}` : `v${NAX_VERSION} (${NAX_COMMIT})`;
 });
 
+// src/prd/validate.ts
+function validateStoryId(id) {
+  if (!id || id.length === 0) {
+    throw new Error("Story ID cannot be empty");
+  }
+  if (id.includes("..")) {
+    throw new Error("Story ID cannot contain path traversal (..)");
+  }
+  if (id.startsWith("--")) {
+    throw new Error("Story ID cannot start with git flags (--)");
+  }
+  const validPattern = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;
+  if (!validPattern.test(id)) {
+    throw new Error(`Story ID must match pattern [a-zA-Z0-9][a-zA-Z0-9._-]{0,63}. Got: ${id}`);
+  }
+}
+
 // src/errors.ts
 var NaxError, AgentNotFoundError, AgentNotInstalledError, StoryLimitExceededError, LockAcquisitionError;
 var init_errors3 = __esm(() => {
@@ -22898,7 +22944,7 @@ class WebhookInteractionPlugin {
         this.pendingResponses.delete(requestId);
         return response;
       }
-      await Bun.sleep(backoffMs);
+      await _webhookPluginDeps.sleep(backoffMs);
       backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
     }
     return {
@@ -22997,9 +23043,12 @@ class WebhookInteractionPlugin {
     }
   }
 }
-var WebhookConfigSchema, InteractionResponseSchema;
+var _webhookPluginDeps, WebhookConfigSchema, InteractionResponseSchema;
 var init_webhook = __esm(() => {
   init_zod();
+  _webhookPluginDeps = {
+    sleep: (ms) => Bun.sleep(ms)
+  };
   WebhookConfigSchema = exports_external.object({
     url: exports_external.string().url().optional(),
     callbackPort: exports_external.number().int().min(1024).max(65535).optional(),
@@ -23038,8 +23087,8 @@ class AutoInteractionPlugin {
       return;
     }
     try {
-      if (_deps2.callLlm) {
-        const decision2 = await _deps2.callLlm(request);
+      if (_deps3.callLlm) {
+        const decision2 = await _deps3.callLlm(request);
         if (decision2.confidence < (this.config.confidenceThreshold ?? 0.7)) {
           return;
         }
@@ -23068,7 +23117,7 @@ class AutoInteractionPlugin {
   }
   async callLlm(request) {
     const prompt = this.buildPrompt(request);
-    const adapter = _deps2.adapter;
+    const adapter = _deps3.adapter;
     if (!adapter) {
       throw new Error("Auto plugin requires adapter to be injected via _deps.adapter");
     }
@@ -23156,7 +23205,7 @@ Respond with ONLY this JSON (no markdown, no explanation):
     return parsed;
   }
 }
-var AutoConfigSchema, _deps2;
+var AutoConfigSchema, _deps3;
 var init_auto = __esm(() => {
   init_zod();
   init_config();
@@ -23166,7 +23215,7 @@ var init_auto = __esm(() => {
     maxCostPerDecision: exports_external.number().positive().optional(),
     naxConfig: exports_external.any().optional()
   });
-  _deps2 = {
+  _deps3 = {
     adapter: null,
     callLlm: null
   };
@@ -23529,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]);
@@ -23847,7 +23908,7 @@ async function runReview(config2, workdir, executionConfig) {
   const logger = getSafeLogger();
   const checks3 = [];
   let firstFailure;
-  const allUncommittedFiles = await _deps3.getUncommittedFiles(workdir);
+  const allUncommittedFiles = await _deps4.getUncommittedFiles(workdir);
   const NAX_RUNTIME_FILES = new Set(["nax/status.json", ".nax-verifier-verdict.json"]);
   const uncommittedFiles = allUncommittedFiles.filter((f) => !NAX_RUNTIME_FILES.has(f) && !f.match(/^nax\/features\/.+\/prd\.json$/));
   if (uncommittedFiles.length > 0) {
@@ -23887,11 +23948,11 @@ Stage and commit these files before running review.`
     failureReason: firstFailure
   };
 }
-var _reviewRunnerDeps, REVIEW_CHECK_TIMEOUT_MS = 120000, SIGKILL_GRACE_PERIOD_MS2 = 5000, _deps3;
+var _reviewRunnerDeps, REVIEW_CHECK_TIMEOUT_MS = 120000, SIGKILL_GRACE_PERIOD_MS2 = 5000, _deps4;
 var init_runner2 = __esm(() => {
   init_logger2();
   _reviewRunnerDeps = { spawn, file: Bun.file };
-  _deps3 = {
+  _deps4 = {
     getUncommittedFiles: getUncommittedFilesImpl
   };
 });
@@ -24996,7 +25057,7 @@ async function addFileElements(elements, storyContext, story) {
   if (contextFiles.length === 0 && storyContext.config?.context?.autoDetect?.enabled !== false && storyContext.workdir) {
     const autoDetectConfig = storyContext.config?.context?.autoDetect;
     try {
-      const detected = await _deps4.autoDetectContextFiles({
+      const detected = await _deps5.autoDetectContextFiles({
         workdir: storyContext.workdir,
         storyTitle: story.title,
         maxFiles: autoDetectConfig?.maxFiles ?? 5,
@@ -25054,7 +25115,7 @@ ${content}
     }
   }
 }
-var _deps4;
+var _deps5;
 var init_builder3 = __esm(() => {
   init_logger2();
   init_prd();
@@ -25062,7 +25123,7 @@ var init_builder3 = __esm(() => {
   init_elements();
   init_test_scanner();
   init_elements();
-  _deps4 = {
+  _deps5 = {
     autoDetectContextFiles
   };
 });
@@ -25544,6 +25605,30 @@ function detectMergeConflict(output) {
 async function autoCommitIfDirty(workdir, stage, role, storyId) {
   const logger = getSafeLogger();
   try {
+    const topLevelProc = _gitDeps.spawn(["git", "rev-parse", "--show-toplevel"], {
+      cwd: workdir,
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    const gitRoot = (await new Response(topLevelProc.stdout).text()).trim();
+    await topLevelProc.exited;
+    const { realpathSync: realpathSync3 } = await import("fs");
+    const realWorkdir = (() => {
+      try {
+        return realpathSync3(workdir);
+      } catch {
+        return workdir;
+      }
+    })();
+    const realGitRoot = (() => {
+      try {
+        return realpathSync3(gitRoot);
+      } catch {
+        return gitRoot;
+      }
+    })();
+    if (realWorkdir !== realGitRoot)
+      return;
     const statusProc = _gitDeps.spawn(["git", "status", "--porcelain"], {
       cwd: workdir,
       stdout: "pipe",
@@ -25929,11 +26014,15 @@ async function fullSuite(options) {
   return runVerificationCore(options);
 }
 async function regression(options) {
-  await Bun.sleep(2000);
+  await _regressionRunnerDeps.sleep(2000);
   return runVerificationCore({ ...options, expectedFiles: undefined });
 }
+var _regressionRunnerDeps;
 var init_runners = __esm(() => {
   init_executor();
+  _regressionRunnerDeps = {
+    sleep: (ms) => Bun.sleep(ms)
+  };
 });
 
 // src/verification/rectification.ts
@@ -26762,7 +26851,7 @@ async function runTddSession(role, agent, story, config2, workdir, modelTier, be
       exitCode: result.exitCode
     });
   }
-  await autoCommitIfDirty(workdir, "tdd", role, story.id);
+  await _sessionRunnerDeps.autoCommitIfDirty(workdir, "tdd", role, story.id);
   let isolation;
   if (!skipIsolation) {
     if (role === "test-writer") {
@@ -26809,6 +26898,7 @@ async function runTddSession(role, agent, story, config2, workdir, modelTier, be
     estimatedCost: result.estimatedCost
   };
 }
+var _sessionRunnerDeps;
 var init_session_runner = __esm(() => {
   init_config();
   init_logger2();
@@ -26816,6 +26906,9 @@ var init_session_runner = __esm(() => {
   init_git();
   init_cleanup();
   init_isolation();
+  _sessionRunnerDeps = {
+    autoCommitIfDirty
+  };
 });
 
 // src/tdd/verdict-reader.ts
@@ -27492,9 +27585,9 @@ Category: ${tddResult.failureCategory ?? "unknown"}`,
           const plugin = ctx.interaction?.getPrimary();
           if (!plugin)
             return;
-          const QUESTION_PATTERNS2 = [/\?/, /\bwhich\b/i, /\bshould i\b/i, /\bunclear\b/i, /\bplease clarify\b/i];
+          const QUESTION_PATTERNS = [/\?/, /\bwhich\b/i, /\bshould i\b/i, /\bunclear\b/i, /\bplease clarify\b/i];
           return {
-            detectQuestion: async (text) => QUESTION_PATTERNS2.some((p) => p.test(text)),
+            detectQuestion: async (text) => QUESTION_PATTERNS.some((p) => p.test(text)),
             onQuestionDetected: async (text) => {
               const requestId = `ix-acp-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
               await plugin.send({
@@ -29751,7 +29844,7 @@ var init_checks_config = () => {};
 async function checkAgentCLI(config2) {
   const agent = config2.execution?.agent || "claude";
   try {
-    const proc = _deps6.spawn([agent, "--version"], {
+    const proc = _deps7.spawn([agent, "--version"], {
       stdout: "pipe",
       stderr: "pipe"
     });
@@ -29772,9 +29865,9 @@ async function checkAgentCLI(config2) {
     };
   }
 }
-var _deps6;
+var _deps7;
 var init_checks_cli = __esm(() => {
-  _deps6 = {
+  _deps7 = {
     spawn: Bun.spawn
   };
 });
@@ -31363,23 +31456,6 @@ var init_headless_formatter = __esm(() => {
   init_version();
 });
 
-// src/prd/validate.ts
-function validateStoryId(id) {
-  if (!id || id.length === 0) {
-    throw new Error("Story ID cannot be empty");
-  }
-  if (id.includes("..")) {
-    throw new Error("Story ID cannot contain path traversal (..)");
-  }
-  if (id.startsWith("--")) {
-    throw new Error("Story ID cannot start with git flags (--)");
-  }
-  const validPattern = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;
-  if (!validPattern.test(id)) {
-    throw new Error(`Story ID must match pattern [a-zA-Z0-9][a-zA-Z0-9._-]{0,63}. Got: ${id}`);
-  }
-}
-
 // src/worktree/manager.ts
 var exports_manager = {};
 __export(exports_manager, {
@@ -65007,7 +65083,7 @@ import { existsSync as existsSync8 } from "fs";
 import { join as join9 } from "path";
 
 // src/analyze/scanner.ts
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync2, readdirSync } from "fs";
 import { join as join4 } from "path";
 async function scanCodebase(workdir) {
   const srcPath = join4(workdir, "src");
@@ -65036,30 +65112,23 @@ async function generateFileTree(dir, maxDepth, currentDepth = 0, prefix = "") {
   }
   const entries = [];
   try {
-    const dirEntries = Array.from(new Bun.Glob("*").scanSync({
-      cwd: dir,
-      onlyFiles: false
-    }));
+    const dirEntries = readdirSync(dir, { withFileTypes: true });
     dirEntries.sort((a, b) => {
-      const aIsDir = !a.includes(".");
-      const bIsDir = !b.includes(".");
-      if (aIsDir && !bIsDir)
+      if (a.isDirectory() && !b.isDirectory())
         return -1;
-      if (!aIsDir && bIsDir)
+      if (!a.isDirectory() && b.isDirectory())
         return 1;
-      return a.localeCompare(b);
+      return a.name.localeCompare(b.name);
     });
     for (let i = 0;i < dirEntries.length; i++) {
-      const entry = dirEntries[i];
-      const fullPath = join4(dir, entry);
+      const dirent = dirEntries[i];
       const isLast = i === dirEntries.length - 1;
       const connector = isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
       const childPrefix = isLast ? "    " : "\u2502   ";
-      const stat = await Bun.file(fullPath).stat();
-      const isDir = stat.isDirectory();
-      entries.push(`${prefix}${connector}${entry}${isDir ? "/" : ""}`);
+      const isDir = dirent.isDirectory();
+      entries.push(`${prefix}${connector}${dirent.name}${isDir ? "/" : ""}`);
       if (isDir) {
-        const subtree = await generateFileTree(fullPath, maxDepth, currentDepth + 1, prefix + childPrefix);
+        const subtree = await generateFileTree(join4(dir, dirent.name), maxDepth, currentDepth + 1, prefix + childPrefix);
         if (subtree) {
           entries.push(subtree);
         }
@@ -65473,94 +65542,259 @@ async function generateAcceptanceTestsForFeature(specContent, featureName, featu
   }
 }
 // src/cli/plan.ts
-init_claude();
+init_registry();
 import { existsSync as existsSync9 } from "fs";
 import { join as join10 } from "path";
 import { createInterface } from "readline";
-init_schema();
 init_logger2();
-var QUESTION_PATTERNS = [/\?[\s]*$/, /\bwhich\b/i, /\bshould i\b/i, /\bdo you want\b/i, /\bwould you like\b/i];
-async function detectQuestion(text) {
-  return QUESTION_PATTERNS.some((p) => p.test(text.trim()));
-}
-async function askHuman(question) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve6) => {
-    rl.question(`
-[Agent asks]: ${question}
-Your answer: `, (answer) => {
-      rl.close();
-      resolve6(answer.trim());
-    });
-  });
-}
-var SPEC_TEMPLATE = `# Feature: [title]
-
-## Problem
-Why this is needed.
-
-## Requirements
-- REQ-1: ...
-- REQ-2: ...
-
-## Acceptance Criteria
-- AC-1: ...
 
-## Technical Notes
-Architecture hints, constraints, dependencies.
+// src/prd/schema.ts
+var VALID_COMPLEXITY = ["simple", "medium", "complex", "expert"];
+var VALID_TEST_STRATEGIES = [
+  "test-after",
+  "tdd-simple",
+  "three-session-tdd",
+  "three-session-tdd-lite"
+];
+var STORY_ID_NO_SEPARATOR = /^([A-Za-z]+)(\d+)$/;
+function extractJsonFromMarkdown(text) {
+  const match = text.match(/```(?:json)?\s*\n([\s\S]*?)\n?\s*```/);
+  if (match) {
+    return match[1] ?? text;
+  }
+  return text;
+}
+function stripTrailingCommas(text) {
+  return text.replace(/,\s*([}\]])/g, "$1");
+}
+function normalizeStoryId(id) {
+  const match = id.match(STORY_ID_NO_SEPARATOR);
+  if (match) {
+    return `${match[1]}-${match[2]}`;
+  }
+  return id;
+}
+function normalizeComplexity2(raw) {
+  const lower = raw.toLowerCase();
+  if (VALID_COMPLEXITY.includes(lower)) {
+    return lower;
+  }
+  return null;
+}
+function validateStory(raw, index, allIds) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error(`[schema] story[${index}] must be an object`);
+  }
+  const s = raw;
+  const rawId = s.id;
+  if (rawId === undefined || rawId === null || rawId === "") {
+    throw new Error(`[schema] story[${index}].id is required and must be non-empty`);
+  }
+  if (typeof rawId !== "string") {
+    throw new Error(`[schema] story[${index}].id must be a string`);
+  }
+  const id = normalizeStoryId(rawId);
+  validateStoryId(id);
+  const title = s.title;
+  if (!title || typeof title !== "string" || title.trim() === "") {
+    throw new Error(`[schema] story[${index}].title is required and must be non-empty`);
+  }
+  const description = s.description;
+  if (!description || typeof description !== "string" || description.trim() === "") {
+    throw new Error(`[schema] story[${index}].description is required and must be non-empty`);
+  }
+  const ac = s.acceptanceCriteria;
+  if (!Array.isArray(ac) || ac.length === 0) {
+    throw new Error(`[schema] story[${index}].acceptanceCriteria is required and must be a non-empty array`);
+  }
+  for (let i = 0;i < ac.length; i++) {
+    if (typeof ac[i] !== "string") {
+      throw new Error(`[schema] story[${index}].acceptanceCriteria[${i}] must be a string`);
+    }
+  }
+  const routing = typeof s.routing === "object" && s.routing !== null ? s.routing : {};
+  const rawComplexity = routing.complexity ?? s.complexity;
+  if (rawComplexity === undefined || rawComplexity === null) {
+    throw new Error(`[schema] story[${index}] missing complexity. Set routing.complexity to one of: ${VALID_COMPLEXITY.join(", ")}`);
+  }
+  if (typeof rawComplexity !== "string") {
+    throw new Error(`[schema] story[${index}].routing.complexity must be a string`);
+  }
+  const complexity = normalizeComplexity2(rawComplexity);
+  if (complexity === null) {
+    throw new Error(`[schema] story[${index}].routing.complexity "${rawComplexity}" is invalid. Valid values: ${VALID_COMPLEXITY.join(", ")}`);
+  }
+  const rawTestStrategy = routing.testStrategy ?? s.testStrategy;
+  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) {
+    if (!allIds.has(dep)) {
+      throw new Error(`[schema] story[${index}].dependencies references unknown story ID "${dep}"`);
+    }
+  }
+  const rawTags = s.tags;
+  const tags = Array.isArray(rawTags) ? rawTags : [];
+  return {
+    id,
+    title: title.trim(),
+    description: description.trim(),
+    acceptanceCriteria: ac,
+    tags,
+    dependencies,
+    status: "pending",
+    passes: false,
+    attempts: 0,
+    escalations: [],
+    routing: {
+      complexity,
+      testStrategy,
+      reasoning: "validated from LLM output"
+    }
+  };
+}
+function parseRawString(text) {
+  const extracted = extractJsonFromMarkdown(text);
+  const cleaned = stripTrailingCommas(extracted);
+  try {
+    return JSON.parse(cleaned);
+  } catch (err) {
+    const parseErr = err;
+    throw new Error(`[schema] Failed to parse JSON: ${parseErr.message}`, { cause: parseErr });
+  }
+}
+function validatePlanOutput(raw, feature, branch) {
+  const parsed = typeof raw === "string" ? parseRawString(raw) : raw;
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error("[schema] PRD output must be a JSON object");
+  }
+  const obj = parsed;
+  const rawStories = obj.userStories;
+  if (!Array.isArray(rawStories) || rawStories.length === 0) {
+    throw new Error("[schema] userStories is required and must be a non-empty array");
+  }
+  const allIds = new Set;
+  for (const story of rawStories) {
+    if (typeof story === "object" && story !== null && !Array.isArray(story)) {
+      const s = story;
+      const rawId = s.id;
+      if (typeof rawId === "string" && rawId !== "") {
+        allIds.add(normalizeStoryId(rawId));
+      }
+    }
+  }
+  const userStories = rawStories.map((story, index) => validateStory(story, index, allIds));
+  const now = new Date().toISOString();
+  return {
+    project: typeof obj.project === "string" && obj.project !== "" ? obj.project : feature,
+    feature,
+    branchName: branch,
+    createdAt: typeof obj.createdAt === "string" ? obj.createdAt : now,
+    updatedAt: now,
+    userStories
+  };
+}
 
-## Out of Scope
-What this does NOT include.
-`;
-async function planCommand(prompt, workdir, config2, options = {}) {
-  const interactive = options.interactive !== false;
-  const ngentDir = join10(workdir, "nax");
-  const outputPath = join10(ngentDir, config2.plan.outputPath);
-  if (!existsSync9(ngentDir)) {
+// src/cli/plan.ts
+var _deps2 = {
+  readFile: (path) => Bun.file(path).text(),
+  writeFile: (path, content) => Bun.write(path, content).then(() => {}),
+  scanCodebase: (workdir) => scanCodebase(workdir),
+  getAgent: (name) => getAgent(name),
+  readPackageJson: (workdir) => Bun.file(join10(workdir, "package.json")).json().catch(() => null),
+  spawnSync: (cmd, opts) => {
+    const result = Bun.spawnSync(cmd, opts ? { cwd: opts.cwd } : {});
+    return { stdout: result.stdout, exitCode: result.exitCode };
+  },
+  mkdirp: (path) => Bun.spawn(["mkdir", "-p", path]).exited.then(() => {})
+};
+async function planCommand(workdir, config2, options) {
+  const naxDir = join10(workdir, "nax");
+  if (!existsSync9(naxDir)) {
     throw new Error(`nax directory not found. Run 'nax init' first in ${workdir}`);
   }
   const logger = getLogger();
-  logger.info("cli", "Scanning codebase...");
-  const scan = await scanCodebase(workdir);
+  logger?.info("plan", "Reading spec", { from: options.from });
+  const specContent = await _deps2.readFile(options.from);
+  logger?.info("plan", "Scanning codebase...");
+  const scan = await _deps2.scanCodebase(workdir);
   const codebaseContext = buildCodebaseContext2(scan);
-  const modelTier = config2.plan.model;
-  const modelEntry = config2.models[modelTier];
-  const modelDef = resolveModel(modelEntry);
-  const fullPrompt = buildPlanPrompt(prompt, SPEC_TEMPLATE);
-  const planOptions = {
-    prompt: fullPrompt,
-    workdir,
-    interactive,
-    codebaseContext,
-    inputFile: options.from,
-    modelTier,
-    modelDef,
-    config: config2,
-    interactionBridge: interactive ? { detectQuestion, onQuestionDetected: askHuman } : undefined
-  };
-  const adapter = new ClaudeCodeAdapter;
-  logger.info("cli", interactive ? "Starting interactive planning session..." : `Reading from ${options.from}...`, {
-    interactive,
-    from: options.from
-  });
-  const result = await adapter.plan(planOptions);
-  if (interactive) {
-    if (result.specContent) {
-      await Bun.write(outputPath, result.specContent);
-    } else {
-      if (!existsSync9(outputPath)) {
-        throw new Error(`Interactive planning completed but spec not found at ${outputPath}`);
-      }
-    }
+  const pkg = await _deps2.readPackageJson(workdir);
+  const projectName = detectProjectName(workdir, pkg);
+  const branchName = options.branch ?? `feat/${options.feature}`;
+  const prompt = buildPlanningPrompt(specContent, codebaseContext);
+  const agentName = config2?.autoMode?.defaultAgent ?? "claude";
+  const adapter = _deps2.getAgent(agentName);
+  if (!adapter) {
+    throw new Error(`[plan] No agent adapter found for '${agentName}'`);
+  }
+  const timeoutSeconds = config2?.execution?.sessionTimeoutSeconds ?? 600;
+  let rawResponse;
+  if (options.auto) {
+    rawResponse = await adapter.complete(prompt, { jsonMode: true });
   } else {
-    if (!result.specContent) {
-      throw new Error("Agent did not produce specification content");
+    const interactionBridge = createCliInteractionBridge();
+    logger?.info("plan", "Starting interactive planning session...", { agent: agentName });
+    try {
+      const result = await adapter.plan({
+        prompt,
+        workdir,
+        interactive: true,
+        timeoutSeconds,
+        interactionBridge
+      });
+      rawResponse = result.specContent;
+    } finally {
+      logger?.info("plan", "Interactive session ended");
     }
-    await Bun.write(outputPath, result.specContent);
   }
-  logger.info("cli", "\u2713 Specification written to output", { outputPath });
+  const finalPrd = validatePlanOutput(rawResponse, options.feature, branchName);
+  finalPrd.project = projectName;
+  const outputDir = join10(naxDir, "features", options.feature);
+  const outputPath = join10(outputDir, "prd.json");
+  await _deps2.mkdirp(outputDir);
+  await _deps2.writeFile(outputPath, JSON.stringify(finalPrd, null, 2));
+  logger?.info("plan", "[OK] PRD written", { outputPath });
   return outputPath;
 }
+function createCliInteractionBridge() {
+  return {
+    async detectQuestion(text) {
+      return text.includes("?");
+    },
+    async onQuestionDetected(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(""));
+      });
+    }
+  };
+}
+function detectProjectName(workdir, pkg) {
+  if (pkg?.name && typeof pkg.name === "string") {
+    return pkg.name;
+  }
+  const result = _deps2.spawnSync(["git", "remote", "get-url", "origin"], { cwd: workdir });
+  if (result.exitCode === 0) {
+    const url2 = result.stdout.toString().trim();
+    const match = url2.match(/\/([^/]+?)(?:\.git)?$/);
+    if (match?.[1])
+      return match[1];
+  }
+  return "unknown";
+}
 function buildCodebaseContext2(scan) {
   const sections = [];
   sections.push(`## Codebase Structure
@@ -65587,24 +65821,63 @@ function buildCodebaseContext2(scan) {
   return sections.join(`
 `);
 }
-function buildPlanPrompt(userPrompt, template) {
-  return `You are helping plan a new feature for this codebase.
+function buildPlanningPrompt(specContent, codebaseContext) {
+  return `You are a senior software architect generating a product requirements document (PRD) as JSON.
 
-Task: ${userPrompt}
+## Spec
 
-Please gather requirements and produce a structured specification following this template:
+${specContent}
 
-${template}
+## Codebase Context
 
-Ask clarifying questions as needed to ensure the spec is complete and unambiguous.
-Focus on understanding:
-- The problem being solved
-- Specific requirements and constraints
-- Acceptance criteria for success
-- Technical approach and architecture
-- What is explicitly out of scope
+${codebaseContext}
+
+## Output Schema
+
+Generate a JSON object with this exact structure (no markdown, no explanation \u2014 JSON only):
+
+{
+  "project": "string \u2014 project name",
+  "feature": "string \u2014 feature name",
+  "branchName": "string \u2014 git branch (e.g. feat/my-feature)",
+  "createdAt": "ISO 8601 timestamp",
+  "updatedAt": "ISO 8601 timestamp",
+  "userStories": [
+    {
+      "id": "string \u2014 e.g. US-001",
+      "title": "string \u2014 concise story title",
+      "description": "string \u2014 detailed description of the story",
+      "acceptanceCriteria": ["string \u2014 each AC line"],
+      "tags": ["string \u2014 routing tags, e.g. feature, security, api"],
+      "dependencies": ["string \u2014 story IDs this story depends on"],
+      "status": "pending",
+      "passes": false,
+      "routing": {
+        "complexity": "simple | medium | complex | expert",
+        "testStrategy": "test-after | tdd-simple | three-session-tdd | three-session-tdd-lite",
+        "reasoning": "string \u2014 brief classification rationale"
+      },
+      "escalations": [],
+      "attempts": 0
+    }
+  ]
+}
+
+## 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-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-lite
 
-When done, output the complete specification in markdown format.`;
+## Test Strategy Guide
+
+- test-after: Simple changes with well-understood behavior. Write tests after 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.`;
 }
 // src/cli/accept.ts
 init_config();
@@ -65753,13 +66026,13 @@ async function displayModelEfficiency(workdir) {
 }
 // src/cli/status-features.ts
 init_source();
-import { existsSync as existsSync11, readdirSync as readdirSync2 } from "fs";
+import { existsSync as existsSync11, readdirSync as readdirSync3 } from "fs";
 import { join as join13 } from "path";
 
 // src/commands/common.ts
 init_path_security2();
 init_errors3();
-import { existsSync as existsSync10, readdirSync, realpathSync as realpathSync2 } from "fs";
+import { existsSync as existsSync10, readdirSync as readdirSync2, realpathSync as realpathSync2 } from "fs";
 import { join as join11, resolve as resolve6 } from "path";
 function resolveProject(options = {}) {
   const { dir, feature } = options;
@@ -65798,7 +66071,7 @@ Expected to find: ${cwdConfigPath}`, "CONFIG_NOT_FOUND", { naxDir: cwdNaxDir, co
     const featuresDir = join11(naxDir, "features");
     featureDir = join11(featuresDir, feature);
     if (!existsSync10(featureDir)) {
-      const availableFeatures = existsSync10(featuresDir) ? readdirSync(featuresDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name) : [];
+      const availableFeatures = existsSync10(featuresDir) ? readdirSync2(featuresDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name) : [];
       const availableMsg = availableFeatures.length > 0 ? `
 
 Available features:
@@ -65910,7 +66183,7 @@ async function getFeatureSummary(featureName, featureDir) {
   }
   const runsDir = join13(featureDir, "runs");
   if (existsSync11(runsDir)) {
-    const runs = readdirSync2(runsDir, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(".jsonl") && e.name !== "latest.jsonl").map((e) => e.name).sort().reverse();
+    const runs = readdirSync3(runsDir, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(".jsonl") && e.name !== "latest.jsonl").map((e) => e.name).sort().reverse();
     if (runs.length > 0) {
       const latestRun = runs[0].replace(".jsonl", "");
       summary.lastRun = latestRun;
@@ -65924,7 +66197,7 @@ async function displayAllFeatures(projectDir) {
     console.log(source_default.dim("No features found."));
     return;
   }
-  const features = readdirSync2(featuresDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  const features = readdirSync3(featuresDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort();
   if (features.length === 0) {
     console.log(source_default.dim("No features found."));
     return;
@@ -66100,7 +66373,7 @@ async function displayFeatureStatus(options = {}) {
 // src/cli/runs.ts
 init_errors3();
 init_logger2();
-import { existsSync as existsSync12, readdirSync as readdirSync3 } from "fs";
+import { existsSync as existsSync12, readdirSync as readdirSync4 } from "fs";
 import { join as join14 } from "path";
 async function parseRunLog(logPath) {
   const logger = getLogger();
@@ -66122,7 +66395,7 @@ async function runsListCommand(options) {
     logger.info("cli", "No runs found for feature", { feature, hint: `Directory not found: ${runsDir}` });
     return;
   }
-  const files = readdirSync3(runsDir).filter((f) => f.endsWith(".jsonl"));
+  const files = readdirSync4(runsDir).filter((f) => f.endsWith(".jsonl"));
   if (files.length === 0) {
     logger.info("cli", "No runs found for feature", { feature });
     return;
@@ -66627,7 +66900,7 @@ function pad(str, width) {
 init_config();
 init_logger2();
 init_prd();
-import { existsSync as existsSync17, readdirSync as readdirSync4 } from "fs";
+import { existsSync as existsSync17, readdirSync as readdirSync5 } from "fs";
 import { join as join25 } from "path";
 
 // src/cli/diagnose-analysis.ts
@@ -66888,7 +67161,7 @@ async function diagnoseCommand(options = {}) {
       const featuresDir = join25(projectDir, "nax", "features");
       if (!existsSync17(featuresDir))
         throw new Error("No features found in project");
-      const features = readdirSync4(featuresDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+      const features = readdirSync5(featuresDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
       if (features.length === 0)
         throw new Error("No features found");
       feature = features[0];
@@ -67896,19 +68169,19 @@ import { join as join33 } from "path";
 // src/commands/logs-formatter.ts
 init_source();
 init_formatter();
-import { readdirSync as readdirSync6 } from "fs";
+import { readdirSync as readdirSync7 } from "fs";
 import { join as join32 } from "path";
 
 // src/commands/logs-reader.ts
-import { existsSync as existsSync23, readdirSync as readdirSync5 } from "fs";
+import { existsSync as existsSync23, readdirSync as readdirSync6 } from "fs";
 import { readdir as readdir3 } from "fs/promises";
 import { homedir as homedir3 } from "os";
 import { join as join31 } from "path";
-var _deps5 = {
+var _deps6 = {
   getRunsDir: () => process.env.NAX_RUNS_DIR ?? join31(homedir3(), ".nax", "runs")
 };
 async function resolveRunFileFromRegistry(runId) {
-  const runsDir = _deps5.getRunsDir();
+  const runsDir = _deps6.getRunsDir();
   let entries;
   try {
     entries = await readdir3(runsDir);
@@ -67933,7 +68206,7 @@ async function resolveRunFileFromRegistry(runId) {
     console.log(`Log directory unavailable for run: ${runId}`);
     return null;
   }
-  const files = readdirSync5(matched.eventsDir).filter((f) => f.endsWith(".jsonl") && f !== "latest.jsonl").sort().reverse();
+  const files = readdirSync6(matched.eventsDir).filter((f) => f.endsWith(".jsonl") && f !== "latest.jsonl").sort().reverse();
   if (files.length === 0) {
     console.log(`No log files found for run: ${runId}`);
     return null;
@@ -67942,7 +68215,7 @@ async function resolveRunFileFromRegistry(runId) {
   return join31(matched.eventsDir, specificFile ?? files[0]);
 }
 async function selectRunFile(runsDir) {
-  const files = readdirSync5(runsDir).filter((f) => f.endsWith(".jsonl") && f !== "latest.jsonl").sort().reverse();
+  const files = readdirSync6(runsDir).filter((f) => f.endsWith(".jsonl") && f !== "latest.jsonl").sort().reverse();
   if (files.length === 0) {
     return null;
   }
@@ -68020,7 +68293,7 @@ var LOG_LEVEL_PRIORITY2 = {
   error: 3
 };
 async function displayRunsList(runsDir) {
-  const files = readdirSync6(runsDir).filter((f) => f.endsWith(".jsonl") && f !== "latest.jsonl").sort().reverse();
+  const files = readdirSync7(runsDir).filter((f) => f.endsWith(".jsonl") && f !== "latest.jsonl").sort().reverse();
   if (files.length === 0) {
     console.log(source_default.dim("No runs found"));
     return;
@@ -68215,7 +68488,7 @@ async function precheckCommand(options) {
   }
   if (!existsSync29(prdPath)) {
     console.error(source_default.red(`Missing prd.json for feature: ${featureName}`));
-    console.error(source_default.dim(`Run: nax analyze -f ${featureName}`));
+    console.error(source_default.dim(`Run: nax plan -f ${featureName} --from spec.md --auto`));
     process.exit(EXIT_CODES.INVALID_PRD);
   }
   const config2 = await loadConfig(resolved.projectDir);
@@ -68234,7 +68507,7 @@ import { readdir as readdir4 } from "fs/promises";
 import { homedir as homedir4 } from "os";
 import { join as join35 } from "path";
 var DEFAULT_LIMIT = 20;
-var _deps7 = {
+var _deps8 = {
   getRunsDir: () => join35(homedir4(), ".nax", "runs")
 };
 function formatDuration3(ms) {
@@ -68277,7 +68550,7 @@ function pad3(str, width) {
   return str + " ".repeat(padding);
 }
 async function runsCommand(options = {}) {
-  const runsDir = _deps7.getRunsDir();
+  const runsDir = _deps8.getRunsDir();
   let entries;
   try {
     entries = await readdir4(runsDir);
@@ -76153,6 +76426,31 @@ function renderTui(props) {
 init_version();
 var program2 = new Command;
 program2.name("nax").description("AI Coding Agent Orchestrator \u2014 loops until done").version(NAX_VERSION);
+async function promptForConfirmation(question) {
+  if (!process.stdin.isTTY) {
+    return true;
+  }
+  return new Promise((resolve9) => {
+    process.stdout.write(source_default.bold(`${question} [Y/n] `));
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+    const handler = (char) => {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdin.removeListener("data", handler);
+      const answer = char.toLowerCase();
+      process.stdout.write(`
+`);
+      if (answer === "n") {
+        resolve9(false);
+      } else {
+        resolve9(true);
+      }
+    };
+    process.stdin.on("data", handler);
+  });
+}
 program2.command("init").description("Initialize nax in the current project").option("-d, --dir <path>", "Project directory", process.cwd()).option("-f, --force", "Force overwrite existing files", false).action(async (options) => {
   let workdir;
   try {
@@ -76267,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("--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);
@@ -76275,6 +76573,14 @@ program2.command("run").description("Run the orchestration loop for a feature").
     console.error(source_default.red(`Invalid directory: ${err.message}`));
     process.exit(1);
   }
+  if (options.plan && !options.from) {
+    console.error(source_default.red("Error: --plan requires --from <spec-path>"));
+    process.exit(1);
+  }
+  if (options.from && !existsSync32(options.from)) {
+    console.error(source_default.red(`Error: File not found: ${options.from} (required with --plan)`));
+    process.exit(1);
+  }
   let logLevel = "info";
   const envLevel = process.env.NAX_LOG_LEVEL?.toLowerCase();
   if (envLevel && ["error", "warn", "info", "debug"].includes(envLevel)) {
@@ -76302,6 +76608,38 @@ program2.command("run").description("Run the orchestration loop for a feature").
   }
   const featureDir = join43(naxDir, "features", options.feature);
   const prdPath = join43(featureDir, "prd.json");
+  if (options.plan && options.from) {
+    try {
+      console.log(source_default.dim("   [Planning phase: generating PRD from spec]"));
+      const generatedPrdPath = await planCommand(workdir, config2, {
+        from: options.from,
+        feature: options.feature,
+        auto: options.oneShot ?? false,
+        branch: undefined
+      });
+      const generatedPrd = await loadPRD(generatedPrdPath);
+      console.log(source_default.bold(`
+\u2500\u2500 Planning Summary \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`));
+      console.log(source_default.dim(`Feature: ${generatedPrd.feature}`));
+      console.log(source_default.dim(`Stories: ${generatedPrd.userStories.length}`));
+      console.log();
+      for (const story of generatedPrd.userStories) {
+        const complexity = story.routing?.complexity || "unknown";
+        console.log(source_default.dim(`  ${story.id}: ${story.title} [${complexity}]`));
+      }
+      console.log();
+      if (!options.headless) {
+        const confirmationResult = await promptForConfirmation("Proceed with execution?");
+        if (!confirmationResult) {
+          console.log(source_default.yellow("Execution cancelled."));
+          process.exit(0);
+        }
+      }
+    } catch (err) {
+      console.error(source_default.red(`Error during planning: ${err.message}`));
+      process.exit(1);
+    }
+  }
   if (!existsSync32(prdPath)) {
     console.error(source_default.red(`Feature "${options.feature}" not found or missing prd.json`));
     process.exit(1);
@@ -76452,7 +76790,7 @@ Created: ${new Date().toISOString()}
   console.log(source_default.dim("   \u251C\u2500\u2500 tasks.md"));
   console.log(source_default.dim("   \u2514\u2500\u2500 progress.txt"));
   console.log(source_default.dim(`
-Next: Edit spec.md and tasks.md, then: nax analyze --feature ${name}`));
+Next: Edit spec.md and tasks.md, then: nax plan -f ${name} --from spec.md --auto`));
 });
 features.command("list").description("List all features").option("-d, --dir <path>", "Project directory", process.cwd()).action(async (options) => {
   let workdir;
@@ -76472,8 +76810,8 @@ features.command("list").description("List all features").option("-d, --dir <pat
     console.log(source_default.dim("No features yet."));
     return;
   }
-  const { readdirSync: readdirSync7 } = await import("fs");
-  const entries = readdirSync7(featuresDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+  const { readdirSync: readdirSync8 } = await import("fs");
+  const entries = readdirSync8(featuresDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
   if (entries.length === 0) {
     console.log(source_default.dim("No features yet."));
     return;
@@ -76493,7 +76831,13 @@ Features:
   }
   console.log();
 });
-program2.command("plan <description>").description("Interactive planning via agent plan mode").option("--from <file>", "Non-interactive mode: read from input file").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.
+
+Use: nax plan -f <feature> --from <spec>`));
+    process.exit(1);
+  }
   let workdir;
   try {
     workdir = validateDirectory(options.dir);
@@ -76508,21 +76852,26 @@ program2.command("plan <description>").description("Interactive planning via age
   }
   const config2 = await loadConfig(workdir);
   try {
-    const specPath = await planCommand(description, workdir, config2, {
-      interactive: !options.from,
-      from: options.from
+    const prdPath = await planCommand(workdir, config2, {
+      from: options.from,
+      feature: options.feature,
+      auto: options.auto || options.oneShot,
+      branch: options.branch
     });
     console.log(source_default.green(`
-\u2705 Planning complete`));
-    console.log(source_default.dim(`   Spec: ${specPath}`));
+[OK] PRD generated`));
+    console.log(source_default.dim(`   PRD: ${prdPath}`));
     console.log(source_default.dim(`
-Next: nax analyze -f <feature-name>`));
+Next: nax run -f ${options.feature}`));
   } catch (err) {
     console.error(source_default.red(`Error: ${err.message}`));
     process.exit(1);
   }
 });
-program2.command("analyze").description("Parse spec.md into prd.json via agent decompose").requiredOption("-f, --feature <name>", "Feature name").option("-b, --branch <name>", "Branch name", "feat/<feature>").option("--from <path>", "Explicit spec path (overrides default spec.md)").option("--reclassify", "Re-classify existing prd.json without decompose", false).option("-d, --dir <path>", "Project directory", process.cwd()).action(async (options) => {
+program2.command("analyze").description("(deprecated) Parse spec.md into prd.json via agent decompose \u2014 use 'nax plan' instead").requiredOption("-f, --feature <name>", "Feature name").option("-b, --branch <name>", "Branch name", "feat/<feature>").option("--from <path>", "Explicit spec path (overrides default spec.md)").option("--reclassify", "Re-classify existing prd.json without decompose", false).option("-d, --dir <path>", "Project directory", process.cwd()).action(async (options) => {
+  const deprecationMsg = "\u26A0\uFE0F  'nax analyze' is deprecated. Use 'nax plan -f <feature> --from <spec> --auto' instead.";
+  process.stderr.write(`${source_default.yellow(deprecationMsg)}
+`);
   let workdir;
   try {
     workdir = validateDirectory(options.dir);