@nathapp/nax 0.57.2 → 0.57.3

package/dist/nax.js

@@ -3044,16 +3044,6 @@ var init_logger = __esm(() => {
 });
 
 // src/logger/index.ts
-var exports_logger = {};
-__export(exports_logger, {
-  resetLogger: () => resetLogger,
-  initLogger: () => initLogger,
-  getSafeLogger: () => getSafeLogger,
-  getLogger: () => getLogger,
-  formatJsonl: () => formatJsonl,
-  formatConsole: () => formatConsole,
-  Logger: () => Logger
-});
 var init_logger2 = __esm(() => {
   init_logger();
   init_formatters();
@@ -3304,6 +3294,55 @@ var init_test_strategy = __esm(() => {
 
 // src/agents/shared/decompose.ts
 function buildDecomposePrompt(options) {
+  if (options.targetStory) {
+    return buildPlanModeDecomposePrompt(options);
+  }
+  return buildSpecDecomposePrompt(options);
+}
+function buildPlanModeDecomposePrompt(options) {
+  const targetStory = options.targetStory;
+  const siblings = options.siblings ?? [];
+  const siblingsSummary = siblings.length > 0 ? `
+## Sibling Stories
+
+${siblings.map((s) => `- ${s.id}: ${s.title}`).join(`
+`)}
+` : "";
+  return `You are a senior software architect decomposing a complex user story into smaller, implementable sub-stories.
+
+## Target Story
+
+${JSON.stringify(targetStory, null, 2)}${siblingsSummary}
+## Codebase Context
+
+${options.codebaseContext}
+
+${COMPLEXITY_GUIDE}
+
+${TEST_STRATEGY_GUIDE}
+
+${GROUPING_RULES}
+
+## Output
+
+Return a JSON array of sub-stories (no markdown code fences, no explanation \u2014 JSON array only):
+
+[{
+  "id": "string \u2014 e.g. ${targetStory.id}-A",
+  "title": "string",
+  "description": "string",
+  "acceptanceCriteria": ["string \u2014 behavioral, testable criteria"],
+  "contextFiles": ["string \u2014 required, non-empty list of key source files"],
+  "tags": ["string"],
+  "dependencies": ["string"],
+  "complexity": "simple | medium | complex | expert",
+  "reasoning": "string",
+  "estimatedLOC": 0,
+  "risks": ["string"],
+  "testStrategy": "no-test | tdd-simple | three-session-tdd-lite | three-session-tdd | test-after"
+}]`;
+}
+function buildSpecDecomposePrompt(options) {
   return `You are a requirements analyst. Break down the following feature specification into user stories and classify each story's complexity.
 
 CODEBASE CONTEXT:
@@ -3614,9 +3653,11 @@ class SpawnAcpSession {
     try {
       proc.stdin?.write(text);
       proc.stdin?.end();
-      const exitCode = await proc.exited;
-      const stdout = await new Response(proc.stdout).text();
-      const stderr = await new Response(proc.stderr).text();
+      const [exitCode, stdout, stderr] = await Promise.all([
+        proc.exited,
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text()
+      ]);
       if (exitCode !== 0) {
         getSafeLogger()?.warn("acp-adapter", `Session prompt exited with code ${exitCode}`, {
           exitCode,
@@ -3646,6 +3687,21 @@ class SpawnAcpSession {
       await this.pidRegistry?.unregister(processPid);
     }
   }
+  async trackedSpawn(cmd, opts) {
+    const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe", ...opts });
+    const pid = proc.pid;
+    await this.pidRegistry?.register(pid);
+    try {
+      const [exitCode, stdout, stderr] = await Promise.all([
+        proc.exited,
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text()
+      ]);
+      return { exitCode, stdout, stderr };
+    } finally {
+      await this.pidRegistry?.unregister(pid);
+    }
+  }
   async close(options) {
     if (this.activeProc) {
       try {
@@ -3656,10 +3712,8 @@ class SpawnAcpSession {
     }
     const cmd = ["acpx", "--cwd", this.cwd, this.agentName, "sessions", "close", this.sessionName];
     getSafeLogger()?.debug("acp-adapter", `Closing session: ${this.sessionName}`);
-    const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
-    const exitCode = await proc.exited;
+    const { exitCode, stderr } = await this.trackedSpawn(cmd);
     if (exitCode !== 0) {
-      const stderr = await new Response(proc.stderr).text();
       getSafeLogger()?.warn("acp-adapter", "Failed to close session", {
         sessionName: this.sessionName,
         stderr: stderr.slice(0, 200)
@@ -3667,8 +3721,7 @@ class SpawnAcpSession {
     }
     if (options?.forceTerminate) {
       try {
-        const stopProc = _spawnClientDeps.spawn(["acpx", this.agentName, "stop"], { stdout: "pipe", stderr: "pipe" });
-        await stopProc.exited;
+        await this.trackedSpawn(["acpx", this.agentName, "stop"]);
       } catch (err) {
         getSafeLogger()?.debug("acp-adapter", "acpx stop failed (swallowed)", { cause: String(err) });
       }
@@ -3683,8 +3736,7 @@ class SpawnAcpSession {
     }
     const cmd = ["acpx", this.agentName, "cancel"];
     getSafeLogger()?.debug("acp-adapter", `Cancelling active prompt: ${this.sessionName}`);
-    const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
-    await proc.exited;
+    await this.trackedSpawn(cmd);
   }
 }
 
@@ -3710,14 +3762,27 @@ class SpawnAcpClient {
     this.pidRegistry = pidRegistry;
   }
   async start() {}
+  async trackedSpawn(cmd) {
+    const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
+    const pid = proc.pid;
+    await this.pidRegistry?.register(pid);
+    try {
+      const [exitCode, stdout, stderr] = await Promise.all([
+        proc.exited,
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text()
+      ]);
+      return { exitCode, stdout, stderr };
+    } finally {
+      await this.pidRegistry?.unregister(pid);
+    }
+  }
   async createSession(opts) {
     const sessionName = opts.sessionName || `nax-${Date.now()}`;
     const cmd = ["acpx", "--cwd", this.cwd, opts.agentName, "sessions", "ensure", "--name", sessionName];
     getSafeLogger()?.debug("acp-adapter", `Ensuring session: ${sessionName}`);
-    const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
-    const exitCode = await proc.exited;
+    const { exitCode, stderr } = await this.trackedSpawn(cmd);
     if (exitCode !== 0) {
-      const stderr = await new Response(proc.stderr).text();
       throw new Error(`[acp-adapter] Failed to create session: ${stderr || `exit code ${exitCode}`}`);
     }
     return new SpawnAcpSession({
@@ -3733,8 +3798,7 @@ class SpawnAcpClient {
   }
   async loadSession(sessionName, agentName, permissionMode) {
     const cmd = ["acpx", "--cwd", this.cwd, agentName, "sessions", "ensure", "--name", sessionName];
-    const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
-    const exitCode = await proc.exited;
+    const { exitCode } = await this.trackedSpawn(cmd);
     if (exitCode !== 0) {
       return null;
     }
@@ -18082,6 +18146,7 @@ var init_schemas3 = __esm(() => {
     command: exports_external.string().optional(),
     model: exports_external.enum(["fast", "balanced", "powerful"]).default("fast"),
     refinement: exports_external.boolean().default(true),
+    refinementConcurrency: exports_external.number().int().min(1).max(10).default(3),
     redGate: exports_external.boolean().default(true),
     testStrategy: exports_external.enum(["unit", "component", "cli", "e2e", "snapshot"]).optional(),
     testFramework: exports_external.string().min(1, "acceptance.testFramework must be non-empty").optional(),
@@ -18285,8 +18350,6 @@ var init_schemas3 = __esm(() => {
         maxRectificationAttempts: 3
       },
       contextProviderTokenBudget: 2000,
-      lintCommand: null,
-      typecheckCommand: null,
       dangerouslySkipPermissions: true,
       permissionProfile: "unrestricted",
       smartTestRunner: true
@@ -18392,6 +18455,7 @@ var init_schemas3 = __esm(() => {
       testPath: ".nax-acceptance.test.ts",
       model: "fast",
       refinement: true,
+      refinementConcurrency: 3,
       redGate: true,
       timeoutMs: 1800000,
       fix: {
@@ -18641,7 +18705,7 @@ async function readAcpSession(workdir, featureName, storyId) {
     return null;
   }
 }
-async function sweepFeatureSessions(workdir, featureName) {
+async function sweepFeatureSessions(workdir, featureName, pidRegistry) {
   const path = acpSessionsPath(workdir, featureName);
   let sessions;
   try {
@@ -18665,7 +18729,7 @@ async function sweepFeatureSessions(workdir, featureName) {
   }
   for (const [agentName, sessionNames] of byAgent) {
     const cmdStr = `acpx ${agentName}`;
-    const client = _acpAdapterDeps.createClient(cmdStr, workdir);
+    const client = _acpAdapterDeps.createClient(cmdStr, workdir, undefined, pidRegistry);
     try {
       await client.start();
       for (const sessionName of sessionNames) {
@@ -18690,7 +18754,7 @@ async function sweepFeatureSessions(workdir, featureName) {
     logger?.warn("acp-adapter", "[sweep] Failed to clear sidecar after sweep", { error: String(err) });
   }
 }
-async function sweepStaleFeatureSessions(workdir, featureName, maxAgeMs = MAX_SESSION_AGE_MS) {
+async function sweepStaleFeatureSessions(workdir, featureName, maxAgeMs = MAX_SESSION_AGE_MS, pidRegistry) {
   const path = acpSessionsPath(workdir, featureName);
   const file3 = Bun.file(path);
   if (!await file3.exists())
@@ -18702,7 +18766,7 @@ async function sweepStaleFeatureSessions(workdir, featureName, maxAgeMs = MAX_SE
     featureName,
     ageMs
   });
-  await sweepFeatureSessions(workdir, featureName);
+  await sweepFeatureSessions(workdir, featureName, pidRegistry);
 }
 function extractOutput(response) {
   if (!response)
@@ -19202,7 +19266,9 @@ class AcpAgentAdapter {
         jsonMode: true,
         config: options.config,
         workdir: options.workdir,
-        sessionRole: "decompose"
+        featureName: options.featureName,
+        storyId: options.storyId,
+        sessionRole: options.sessionRole ?? "decompose"
       });
       output = completeResult.output;
     } catch (err) {
@@ -20040,17 +20106,27 @@ class ClaudeCodeAdapter {
       cmd.splice(cmd.length - 2, 0, "--dangerously-skip-permissions");
     }
     const pidRegistry = this.getPidRegistry(options.workdir);
+    const env2 = this.buildAllowedEnv({
+      workdir: options.workdir,
+      modelDef,
+      prompt: "",
+      modelTier: options.modelTier || "balanced",
+      timeoutSeconds: 600
+    });
+    if (options.featureName) {
+      env2.NAX_FEATURE_NAME = options.featureName;
+    }
+    if (options.storyId) {
+      env2.NAX_STORY_ID = options.storyId;
+    }
+    if (options.sessionRole) {
+      env2.NAX_SESSION_ROLE = options.sessionRole;
+    }
     const proc = _decomposeDeps.spawn(cmd, {
       cwd: options.workdir,
       stdout: "pipe",
       stderr: "inherit",
-      env: this.buildAllowedEnv({
-        workdir: options.workdir,
-        modelDef,
-        prompt: "",
-        modelTier: options.modelTier || "balanced",
-        timeoutSeconds: 600
-      })
+      env: env2
     });
     await pidRegistry.register(proc.pid);
     const DECOMPOSE_TIMEOUT_MS = 300000;
@@ -21188,6 +21264,9 @@ function skeletonImportLine(testFramework) {
   }
   return `import { describe, test, expect } from "bun:test";`;
 }
+function hasLikelyTestContent(content) {
+  return /\b(?:describe|test|it|expect)\s*\(/.test(content) || /func\s+Test\w+\s*\(/.test(content) || /def\s+test_\w+/.test(content) || /#\[test\]/.test(content);
+}
 function acceptanceTestFilename(language) {
   switch (language?.toLowerCase()) {
     case "go":
@@ -21291,36 +21370,80 @@ Rules:
   });
   if (!testCode) {
     const targetPath = join6(options.workdir, ".nax", "features", options.featureName, resolveAcceptanceTestFile(options.language, options.config?.acceptance?.testPath));
+    const backupPath = `${targetPath}.llm-recovery.bak`;
     let recoveryFailed = false;
-    logger.debug("acceptance", "BUG-076 recovery: checking for agent-written file", { targetPath });
+    logger.debug("acceptance", "BUG-076 recovery: checking for agent-written file", {
+      targetPath,
+      backupPath,
+      featureName: options.featureName,
+      workdir: options.workdir
+    });
     try {
       const existing = await Bun.file(targetPath).text();
       const recovered = extractTestCode(existing);
+      const likelyTestContent = hasLikelyTestContent(existing);
       logger.debug("acceptance", "BUG-076 recovery: file check result", {
         fileSize: existing.length,
         extractedCode: recovered !== null,
+        likelyTestContent,
         filePreview: existing.slice(0, 300)
       });
       if (recovered) {
         logger.info("acceptance", "Acceptance test written directly by agent \u2014 using existing file", { targetPath });
         testCode = recovered;
+      } else if (existing.trim().length > 0 && likelyTestContent) {
+        let backupCreated = false;
+        try {
+          await _generatorPRDDeps.backupFile(backupPath, existing);
+          backupCreated = true;
+        } catch (backupError) {
+          logger.warn("acceptance", "BUG-076: failed to create recovery backup; preserving file anyway", {
+            targetPath,
+            backupPath,
+            backupError: backupError instanceof Error ? backupError.message : String(backupError)
+          });
+        }
+        logger.warn("acceptance", "BUG-076: preserving agent-written file with backup (heuristic recovery)", {
+          targetPath,
+          backupPath,
+          backupCreated,
+          reason: "extractTestCode returned null"
+        });
+        testCode = existing;
       } else {
+        if (existing.trim().length > 0) {
+          try {
+            await _generatorPRDDeps.backupFile(backupPath, existing);
+          } catch (backupError) {
+            logger.warn("acceptance", "BUG-076: failed to create fallback backup for unrecognized file", {
+              targetPath,
+              backupPath,
+              backupError: backupError instanceof Error ? backupError.message : String(backupError)
+            });
+          }
+        }
         recoveryFailed = true;
-        logger.error("acceptance", "BUG-076: ACP adapter wrote file but no code extractable \u2014 falling back to skeleton", {
+        logger.error("acceptance", "BUG-076: agent-written file not recognized as test code \u2014 falling back to skeleton", {
           targetPath,
+          backupPath,
+          fileSize: existing.length,
           filePreview: existing.slice(0, 300)
         });
       }
-    } catch {
+    } catch (error48) {
       recoveryFailed = true;
-      logger.debug("acceptance", "BUG-076 recovery: no file written by agent, falling back to skeleton", {
+      logger.debug("acceptance", "BUG-076 recovery: failed to read agent-written file, falling back to skeleton", {
         targetPath,
+        backupPath,
+        error: error48 instanceof Error ? error48.message : String(error48),
         rawOutputPreview: rawOutput.slice(0, 500)
       });
     }
     if (recoveryFailed) {
-      logger.error("acceptance", "BUG-076: LLM returned non-code output and no file was written by agent \u2014 falling back to skeleton", {
-        rawOutputPreview: rawOutput.slice(0, 500)
+      logger.error("acceptance", "BUG-076: LLM returned non-code output and recovery could not produce runnable tests \u2014 falling back to skeleton", {
+        rawOutputPreview: rawOutput.slice(0, 500),
+        targetPath,
+        backupPath
       });
     }
   }
@@ -21586,6 +21709,9 @@ var init_generator = __esm(() => {
     },
     writeFile: async (path, content) => {
       await Bun.write(path, content);
+    },
+    backupFile: async (path, content) => {
+      await Bun.write(path, content);
     }
   };
 });
@@ -22342,7 +22468,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@nathapp/nax",
-    version: "0.57.2",
+    version: "0.57.3",
     description: "AI Coding Agent Orchestrator \u2014 loops until done",
     type: "module",
     bin: {
@@ -22421,8 +22547,8 @@ var init_version = __esm(() => {
   NAX_VERSION = package_default.version;
   NAX_COMMIT = (() => {
     try {
-      if (/^[0-9a-f]{6,10}$/.test("2ffb62ec"))
-        return "2ffb62ec";
+      if (/^[0-9a-f]{6,10}$/.test("166deae0"))
+        return "166deae0";
     } catch {}
     try {
       const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
@@ -25043,7 +25169,7 @@ var init_version_detection = __esm(() => {
 // src/precheck/checks-agents.ts
 async function checkMultiAgentHealth() {
   try {
-    const versions2 = await getAgentVersions();
+    const versions2 = await _checkAgentsDeps.getAgentVersions();
     const installed = versions2.filter((v) => v.installed);
     const notInstalled = versions2.filter((v) => !v.installed);
     const lines = [];
@@ -25080,8 +25206,12 @@ Available but not installed (${notInstalled.length}):`);
     };
   }
 }
+var _checkAgentsDeps;
 var init_checks_agents = __esm(() => {
   init_version_detection();
+  _checkAgentsDeps = {
+    getAgentVersions
+  };
 });
 
 // src/precheck/checks.ts
@@ -26252,9 +26382,12 @@ ${stderr}` };
         const agent = (ctx.agentGetFn ?? _acceptanceSetupDeps.getAgent)(ctx.config.autoMode.defaultAgent);
         let allRefinedCriteria;
         if (ctx.config.acceptance.refinement) {
-          allRefinedCriteria = [];
-          for (const story of nonFixStories) {
-            const storyRefined = await _acceptanceSetupDeps.refine(story.acceptanceCriteria, {
+          const maxConcurrency = ctx.config.acceptance.refinementConcurrency ?? 3;
+          const results = new Array(nonFixStories.length);
+          const executing = new Set;
+          for (let i = 0;i < nonFixStories.length; i++) {
+            const story = nonFixStories[i];
+            const task = _acceptanceSetupDeps.refine(story.acceptanceCriteria, {
               storyId: story.id,
               featureName: ctx.prd.feature,
               workdir: ctx.workdir,
@@ -26262,9 +26395,18 @@ ${stderr}` };
               config: ctx.config,
               testStrategy: ctx.config.acceptance.testStrategy,
               testFramework: ctx.config.acceptance.testFramework
+            }).then((refined) => {
+              results[i] = refined;
+            }).finally(() => {
+              executing.delete(task);
             });
-            allRefinedCriteria = allRefinedCriteria.concat(storyRefined);
+            executing.add(task);
+            if (executing.size >= maxConcurrency) {
+              await Promise.race(executing);
+            }
           }
+          await Promise.all(executing);
+          allRefinedCriteria = results.flat();
         } else {
           allRefinedCriteria = nonFixStories.flatMap((story) => story.acceptanceCriteria.map((c) => ({
             original: c,
@@ -26593,6 +26735,93 @@ var init_event_bus = __esm(() => {
   pipelineEventBus = new PipelineEventBus;
 });
 
+// src/pipeline/stages/autofix-prompts.ts
+function formatCheckErrors(checks3) {
+  return checks3.map((c) => `## ${c.check} errors (exit code ${c.exitCode})
+\`\`\`
+${c.output}
+\`\`\``).join(`
+
+`);
+}
+function buildSemanticRectificationPrompt(semanticChecks, story, scopeConstraint) {
+  const errors3 = formatCheckErrors(semanticChecks);
+  const acList = story.acceptanceCriteria.map((ac, i) => `${i + 1}. ${ac}`).join(`
+`);
+  return `You are fixing acceptance criteria compliance issues found during semantic review.
+
+Story: ${story.title} (${story.id})
+
+### Acceptance Criteria
+${acList}
+
+### Semantic Review Findings
+${errors3}
+
+**Important:** The semantic reviewer only analyzed the git diff and may have flagged false positives (e.g., claiming a key or function is "missing" when it already exists in the codebase). Before making any changes:
+1. Read the relevant files to verify each finding is a real issue
+2. Only fix findings that are actually valid problems
+3. Do NOT add keys, functions, or imports that already exist \u2014 check first
+
+Do NOT change test files or test behavior.
+Do NOT add new features \u2014 only fix valid issues.
+Commit your fixes when done.${scopeConstraint}`;
+}
+function buildMechanicalRectificationPrompt(mechanicalChecks, story, scopeConstraint) {
+  const errors3 = formatCheckErrors(mechanicalChecks);
+  return `You are fixing lint/typecheck errors from a code review.
+
+Story: ${story.title} (${story.id})
+
+The following quality checks failed after implementation:
+
+${errors3}
+
+Fix ALL errors listed above. Do NOT change test files or test behavior.
+Do NOT add new features \u2014 only fix the quality check errors.
+Commit your fixes when done.${scopeConstraint}`;
+}
+function buildReviewRectificationPrompt(failedChecks, story) {
+  const scopeConstraint = story.workdir ? `
+
+IMPORTANT: Only modify files within \`${story.workdir}/\`. Do NOT touch files outside this directory.` : "";
+  const semanticChecks = failedChecks.filter((c) => c.check === "semantic");
+  const mechanicalChecks = failedChecks.filter((c) => c.check !== "semantic");
+  if (semanticChecks.length > 0 && mechanicalChecks.length === 0) {
+    return buildSemanticRectificationPrompt(semanticChecks, story, scopeConstraint);
+  }
+  if (mechanicalChecks.length > 0 && semanticChecks.length === 0) {
+    return buildMechanicalRectificationPrompt(mechanicalChecks, story, scopeConstraint);
+  }
+  const mechanicalSection = formatCheckErrors(mechanicalChecks);
+  const semanticSection = formatCheckErrors(semanticChecks);
+  const acList = story.acceptanceCriteria.map((ac, i) => `${i + 1}. ${ac}`).join(`
+`);
+  return `You are fixing issues from a code review.
+
+Story: ${story.title} (${story.id})
+
+## Lint/Typecheck Errors
+
+${mechanicalSection}
+
+Fix ALL lint/typecheck errors listed above.
+
+## Semantic Review Findings (AC Compliance)
+
+### Acceptance Criteria
+${acList}
+
+### Findings
+${semanticSection}
+
+**Important:** The semantic reviewer may have flagged false positives. Before making changes for semantic findings, read the relevant files to verify each finding is a real issue. Do NOT add keys, functions, or imports that already exist.
+
+Do NOT change test files or test behavior.
+Do NOT add new features \u2014 only fix the identified issues.
+Commit your fixes when done.${scopeConstraint}`;
+}
+
 // src/utils/git.ts
 async function gitWithTimeout(args, workdir) {
   const proc = _gitDeps.spawn(["git", ...args], {
@@ -26853,7 +27082,7 @@ ${stat}
   return `${statPreamble}${truncated}
 ... (truncated at ${DIFF_CAP_BYTES} bytes, showing ${visibleFiles}/${totalFiles} files)`;
 }
-function buildPrompt(story, semanticConfig, diff) {
+function buildPrompt(story, semanticConfig, diff, stat) {
   const acList = story.acceptanceCriteria.map((ac, i) => `${i + 1}. ${ac}`).join(`
 `);
   const customRulesSection = semanticConfig.rules.length > 0 ? `
@@ -26861,7 +27090,7 @@ function buildPrompt(story, semanticConfig, diff) {
 ${semanticConfig.rules.map((r, i) => `${i + 1}. ${r}`).join(`
 `)}
 ` : "";
-  return `You are a semantic code reviewer. Your job is to verify that the implementation satisfies the story's acceptance criteria (ACs). You are NOT a linter or style checker \u2014 lint, typecheck, and convention checks are handled separately.
+  return `You are a semantic code reviewer with access to the repository files. Your job is to verify that the implementation satisfies the story's acceptance criteria (ACs). You are NOT a linter or style checker \u2014 lint, typecheck, and convention checks are handled separately.
 
 ## Story: ${story.title}
 
@@ -26878,20 +27107,28 @@ ${diff}\`\`\`
 
 ## Instructions
 
-For each acceptance criterion, verify the diff implements it correctly. Flag issues only when:
-1. An AC is not implemented or partially implemented
+For each acceptance criterion, verify the diff implements it correctly.
+
+**Before reporting any finding as "error", you MUST verify it using your tools:**
+- If you suspect a key, function, import, or variable is missing, READ the relevant file to confirm before flagging.
+- If you suspect a code path is not wired in, GREP for its usage to confirm.
+- Do NOT flag something as missing based solely on its absence from the diff \u2014 it may already exist in the codebase. Check the actual file first.
+- If you cannot verify a claim even after checking, use "unverifiable" severity instead of "error".
+
+Flag issues only when you have confirmed:
+1. An AC is not implemented or partially implemented (verified by reading the actual files)
 2. The implementation contradicts what the AC specifies
 3. New code has dead paths that will never execute (stubs, noops, unreachable branches)
-4. New code is not wired into callers/exports (written but never used)
+4. New code is not wired into callers/exports (verified by grepping for usage)
 
 Do NOT flag: style issues, naming conventions, import ordering, file length, or anything lint handles.
 
-Respond in JSON format:
+Respond with JSON only \u2014 no explanation text before or after:
 {
   "passed": boolean,
   "findings": [
     {
-      "severity": "error" | "warn" | "info",
+      "severity": "error" | "warn" | "info" | "unverifiable",
       "file": "path/to/file",
       "line": 42,
       "issue": "description of the issue",
@@ -26929,10 +27166,15 @@ function formatFindings(findings) {
 function normalizeSeverity(sev) {
   if (sev === "warn")
     return "warning";
+  if (sev === "unverifiable")
+    return "info";
   if (sev === "critical" || sev === "error" || sev === "warning" || sev === "info" || sev === "low")
     return sev;
   return "info";
 }
+function isBlockingSeverity(sev) {
+  return sev !== "unverifiable";
+}
 function toReviewFindings(findings) {
   return findings.map((f) => ({
     ruleId: "semantic",
@@ -26975,10 +27217,11 @@ async function runSemanticReview(workdir, storyGitRef, story, semanticConfig, mo
     modelTier: semanticConfig.modelTier,
     configProvided: !!naxConfig
   });
-  const rawDiff = await collectDiff(workdir, effectiveRef, semanticConfig.excludePatterns);
-  const needsTruncation = rawDiff.length > DIFF_CAP_BYTES;
-  const stat = needsTruncation ? await collectDiffStat(workdir, effectiveRef) : undefined;
-  const diff = truncateDiff(rawDiff, stat);
+  const [rawDiff, stat] = await Promise.all([
+    collectDiff(workdir, effectiveRef, semanticConfig.excludePatterns),
+    collectDiffStat(workdir, effectiveRef)
+  ]);
+  const diff = truncateDiff(rawDiff, rawDiff.length > DIFF_CAP_BYTES ? stat : undefined);
   if (!diff) {
     return {
       check: "semantic",
@@ -27003,7 +27246,7 @@ async function runSemanticReview(workdir, storyGitRef, story, semanticConfig, mo
       durationMs: Date.now() - startTime
     };
   }
-  const prompt = buildPrompt(story, semanticConfig, diff);
+  const prompt = buildPrompt(story, semanticConfig, diff, stat || undefined);
   const reviewDebateEnabled = naxConfig?.debate?.enabled && naxConfig?.debate?.stages?.review?.enabled;
   if (reviewDebateEnabled) {
     const reviewStageConfig = naxConfig?.debate?.stages.review;
@@ -27042,10 +27285,11 @@ async function runSemanticReview(workdir, storyGitRef, story, semanticConfig, mo
         deduped.push(f);
       }
     }
+    const debateBlocking = deduped.filter((f) => isBlockingSeverity(f.severity));
     const durationMs2 = Date.now() - startTime;
     if (!majorityPassed) {
-      if (deduped.length > 0) {
-        logger?.warn("review", `Semantic review failed (debate): ${deduped.length} findings`, {
+      if (debateBlocking.length > 0) {
+        logger?.warn("review", `Semantic review failed (debate): ${debateBlocking.length} findings`, {
           storyId: story.id,
           durationMs: durationMs2
         });
@@ -27056,17 +27300,21 @@ async function runSemanticReview(workdir, storyGitRef, story, semanticConfig, mo
           exitCode: 1,
           output: `Semantic review failed:
 
-${formatFindings(deduped)}`,
+${formatFindings(debateBlocking)}`,
           durationMs: durationMs2,
-          findings: toReviewFindings(deduped)
+          findings: toReviewFindings(debateBlocking)
         };
       }
+      logger?.info("review", "Semantic review passed (debate, all findings non-blocking)", {
+        storyId: story.id,
+        durationMs: durationMs2
+      });
       return {
         check: "semantic",
-        success: false,
+        success: true,
         command: "",
-        exitCode: 1,
-        output: "Semantic review failed (debate, no findings)",
+        exitCode: 0,
+        output: "Semantic review passed (debate, all findings were unverifiable or informational)",
         durationMs: durationMs2
       };
     }
@@ -27127,15 +27375,23 @@ ${formatFindings(deduped)}`,
       durationMs: Date.now() - startTime
     };
   }
-  if (!parsed.passed && parsed.findings.length > 0) {
+  const blockingFindings = parsed.findings.filter((f) => isBlockingSeverity(f.severity));
+  const nonBlockingFindings = parsed.findings.filter((f) => !isBlockingSeverity(f.severity));
+  if (nonBlockingFindings.length > 0) {
+    logger?.debug("review", `Semantic review: ${nonBlockingFindings.length} non-blocking findings (unverifiable/info)`, {
+      storyId: story.id,
+      findings: nonBlockingFindings.map((f) => ({ severity: f.severity, file: f.file, issue: f.issue }))
+    });
+  }
+  if (!parsed.passed && blockingFindings.length > 0) {
     const durationMs2 = Date.now() - startTime;
-    logger?.warn("review", `Semantic review failed: ${parsed.findings.length} findings`, {
+    logger?.warn("review", `Semantic review failed: ${blockingFindings.length} findings`, {
       storyId: story.id,
       durationMs: durationMs2
     });
     logger?.debug("review", "Semantic review findings", {
       storyId: story.id,
-      findings: parsed.findings.map((f) => ({
+      findings: blockingFindings.map((f) => ({
         severity: f.severity,
         file: f.file,
         line: f.line,
@@ -27145,7 +27401,7 @@ ${formatFindings(deduped)}`,
     });
     const output = `Semantic review failed:
 
-${formatFindings(parsed.findings)}`;
+${formatFindings(blockingFindings)}`;
     return {
       check: "semantic",
       success: false,
@@ -27153,7 +27409,19 @@ ${formatFindings(parsed.findings)}`;
       exitCode: 1,
       output,
       durationMs: durationMs2,
-      findings: toReviewFindings(parsed.findings)
+      findings: toReviewFindings(blockingFindings)
+    };
+  }
+  if (!parsed.passed && blockingFindings.length === 0) {
+    const durationMs2 = Date.now() - startTime;
+    logger?.info("review", "Semantic review passed (all findings non-blocking)", { storyId: story.id, durationMs: durationMs2 });
+    return {
+      check: "semantic",
+      success: true,
+      command: "",
+      exitCode: 0,
+      output: "Semantic review passed (all findings were unverifiable or informational)",
+      durationMs: durationMs2
     };
   }
   const durationMs = Date.now() - startTime;
@@ -27560,28 +27828,6 @@ async function recheckReview(ctx) {
 function collectFailedChecks(ctx) {
   return (ctx.reviewResult?.checks ?? []).filter((c) => !c.success);
 }
-function buildReviewRectificationPrompt(failedChecks, story) {
-  const errors3 = failedChecks.map((c) => `## ${c.check} errors (exit code ${c.exitCode})
-\`\`\`
-${c.output}
-\`\`\``).join(`
-
-`);
-  const scopeConstraint = story.workdir ? `
-
-IMPORTANT: Only modify files within \`${story.workdir}/\`. Do NOT touch files outside this directory.` : "";
-  return `You are fixing lint/typecheck errors from a code review.
-
-Story: ${story.title} (${story.id})
-
-The following quality checks failed after implementation:
-
-${errors3}
-
-Fix ALL errors listed above. Do NOT change test files or test behavior.
-Do NOT add new features \u2014 only fix the quality check errors.
-Commit your fixes when done.${scopeConstraint}`;
-}
 function buildAutofixEscalationPreamble(attempt, maxAttempts, rethinkAtAttempt, urgencyAtAttempt) {
   return buildProgressivePromptPreamble({
     attempt,
@@ -29164,35 +29410,12 @@ async function isGreenfieldStory(story, workdir, testPattern = "**/*.{test,spec}
 }
 var init_greenfield = () => {};
 // src/verification/executor.ts
-async function drainWithDeadline(proc, deadlineMs) {
-  const EMPTY = Symbol("timeout");
-  const race = (p) => {
-    let timerId;
-    const timeoutPromise = new Promise((r) => {
-      timerId = setTimeout(() => r(EMPTY), deadlineMs);
-    });
-    return Promise.race([p, timeoutPromise]).finally(() => clearTimeout(timerId));
-  };
-  let out = "";
-  try {
-    const stdout = race(new Response(proc.stdout).text());
-    const stderr = race(new Response(proc.stderr).text());
-    const [o, e] = await Promise.all([stdout, stderr]);
-    if (o !== EMPTY)
-      out += o;
-    if (e !== EMPTY)
-      out += (out ? `
-` : "") + e;
-  } catch (error48) {
-    const isExpectedStreamError = error48 instanceof TypeError || error48 instanceof Error && /abort|cancel|close|destroy|locked/i.test(error48.message);
-    if (!isExpectedStreamError) {
-      const { getSafeLogger: getSafeLogger4 } = await Promise.resolve().then(() => (init_logger2(), exports_logger));
-      getSafeLogger4()?.debug("executor", "Unexpected error draining process output", {
-        error: errorMessage(error48)
-      });
-    }
-  }
-  return out;
+function raceWithDeadline(p, deadlineMs) {
+  const timer = { id: undefined };
+  const timeoutP = new Promise((r) => {
+    timer.id = setTimeout(() => r(DRAIN_TIMEOUT), deadlineMs);
+  });
+  return Promise.race([p, timeoutP]).finally(() => clearTimeout(timer.id));
 }
 function normalizeEnvironment(env2, stripVars) {
   const normalized = { ...env2 };
@@ -29212,6 +29435,8 @@ async function executeWithTimeout(command, timeoutSeconds, env2, options) {
     env: env2 || normalizeEnvironment(process.env),
     cwd: options?.cwd
   });
+  const stdoutPromise = new Response(proc.stdout).text().catch(() => "");
+  const stderrPromise = new Response(proc.stderr).text().catch(() => "");
   const timeoutMs = timeoutSeconds * 1000;
   let timedOut = false;
   const timer = { id: undefined };
@@ -29229,20 +29454,25 @@ async function executeWithTimeout(command, timeoutSeconds, env2, options) {
     killProcessGroup(pid, "SIGTERM");
     await Bun.sleep(gracePeriodMs);
     killProcessGroup(pid, "SIGKILL");
-    const partialOutput = await drainWithDeadline(proc, drainTimeoutMs);
+    const [out, err] = await Promise.all([
+      raceWithDeadline(stdoutPromise, drainTimeoutMs),
+      raceWithDeadline(stderrPromise, drainTimeoutMs)
+    ]);
+    const parts = [out !== DRAIN_TIMEOUT ? out : "", err !== DRAIN_TIMEOUT ? err : ""].filter(Boolean);
+    const partialOutput = parts.join(`
+`) || undefined;
     return {
       success: false,
       timeout: true,
       killed: true,
       childProcessesKilled: true,
-      output: partialOutput || undefined,
+      output: partialOutput,
       error: `EXECUTION_TIMEOUT: Verification process exceeded ${timeoutSeconds}s. Process group (PID ${pid}) killed.`,
       countsTowardEscalation: false
     };
   }
-  const exitCode = raceResult;
-  const stdout = await new Response(proc.stdout).text();
-  const stderr = await new Response(proc.stderr).text();
+  const exitCode = typeof raceResult === "number" ? raceResult : 0;
+  const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
   const output = `${stdout}
 ${stderr}`;
   return {
@@ -29288,10 +29518,11 @@ function buildTestCommand(baseCommand, options) {
   }
   return command;
 }
-var _executorDeps, DEFAULT_STRIP_ENV_VARS;
+var _executorDeps, DRAIN_TIMEOUT, DEFAULT_STRIP_ENV_VARS;
 var init_executor = __esm(() => {
   init_bun_deps();
   _executorDeps = { spawn };
+  DRAIN_TIMEOUT = Symbol("drain-timeout");
   DEFAULT_STRIP_ENV_VARS = ["CLAUDECODE", "REPL_ID", "AGENT"];
 });
 
@@ -34435,12 +34666,12 @@ function createSignalHandler(ctx) {
       hardDeadline.unref();
     const logger = getSafeLogger();
     logger?.error("crash-recovery", `Received ${signal}, shutting down...`, { signal });
-    if (ctx.pidRegistry) {
-      await ctx.pidRegistry.killAll();
-    }
     if (ctx.onShutdown) {
       await ctx.onShutdown().catch(() => {});
     }
+    if (ctx.pidRegistry) {
+      await ctx.pidRegistry.killAll();
+    }
     ctx.emitError?.(signal.toLowerCase());
     await writeFatalLog(ctx.jsonlFilePath, signal);
     await writeRunComplete(ctx, signal.toLowerCase());
@@ -34460,12 +34691,12 @@ ${error48.stack ?? ""}
       error: error48.message,
       stack: error48.stack
     });
-    if (ctx.pidRegistry) {
-      await ctx.pidRegistry.killAll();
-    }
     if (ctx.onShutdown) {
       await ctx.onShutdown().catch(() => {});
     }
+    if (ctx.pidRegistry) {
+      await ctx.pidRegistry.killAll();
+    }
     ctx.emitError?.("uncaughtException");
     await writeFatalLog(ctx.jsonlFilePath, "uncaughtException", error48);
     await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), "uncaughtException", ctx.featureDir);
@@ -34484,12 +34715,12 @@ ${error48.stack ?? ""}
       error: error48.message,
       stack: error48.stack
     });
-    if (ctx.pidRegistry) {
-      await ctx.pidRegistry.killAll();
-    }
     if (ctx.onShutdown) {
       await ctx.onShutdown().catch(() => {});
     }
+    if (ctx.pidRegistry) {
+      await ctx.pidRegistry.killAll();
+    }
     ctx.emitError?.("unhandledRejection");
     await writeFatalLog(ctx.jsonlFilePath, "unhandledRejection", error48);
     await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), "unhandledRejection", ctx.featureDir);
@@ -38446,7 +38677,7 @@ async function setupRun(options) {
     },
     onShutdown: async () => {
       const { sweepFeatureSessions: sweepFeatureSessions2 } = await Promise.resolve().then(() => (init_adapter(), exports_adapter));
-      await sweepFeatureSessions2(workdir, feature).catch(() => {});
+      await sweepFeatureSessions2(workdir, feature, pidRegistry).catch(() => {});
     }
   });
   let prd = await loadPRD(prdPath);
@@ -38469,7 +38700,7 @@ async function setupRun(options) {
     logger?.warn("precheck", "Precheck validations skipped (--skip-precheck)");
   }
   const { sweepStaleFeatureSessions: sweepStaleFeatureSessions2 } = await Promise.resolve().then(() => (init_adapter(), exports_adapter));
-  await sweepStaleFeatureSessions2(workdir, feature).catch(() => {});
+  await sweepStaleFeatureSessions2(workdir, feature, undefined, pidRegistry).catch(() => {});
   const lockAcquired = await acquireLock(workdir);
   if (!lockAcquired) {
     logger?.error("execution", "Another nax process is already running in this directory");
@@ -69988,6 +70219,7 @@ async function generateAcceptanceTestsForFeature(specContent, featureName, featu
 }
 // src/cli/plan.ts
 init_registry();
+init_decompose();
 import { existsSync as existsSync15 } from "fs";
 import { join as join13 } from "path";
 import { createInterface as createInterface2 } from "readline";
@@ -70534,6 +70766,48 @@ init_bridge_builder();
 init_init();
 init_logger2();
 
+// src/prd/decompose-mapper.ts
+init_errors();
+function mapDecomposedStoriesToUserStories(stories, parentStoryId) {
+  return stories.map((story, entryIndex) => {
+    if (!story.id) {
+      throw new NaxError(`Entry at index ${entryIndex} is missing required field: id`, "DECOMPOSE_VALIDATION_FAILED", {
+        stage: "decompose-mapper",
+        entryIndex,
+        parentStoryId
+      });
+    }
+    if (!story.contextFiles || story.contextFiles.length === 0) {
+      throw new NaxError(`Entry ${entryIndex} (${story.id}) has empty contextFiles`, "DECOMPOSE_VALIDATION_FAILED", {
+        stage: "decompose-mapper",
+        entryIndex,
+        storyId: story.id,
+        parentStoryId
+      });
+    }
+    return {
+      id: story.id,
+      title: story.title,
+      description: story.description,
+      acceptanceCriteria: story.acceptanceCriteria,
+      tags: story.tags,
+      dependencies: story.dependencies,
+      contextFiles: story.contextFiles,
+      status: "pending",
+      passes: false,
+      escalations: [],
+      attempts: 0,
+      parentStoryId,
+      routing: {
+        complexity: story.complexity,
+        testStrategy: story.testStrategy ?? "test-after",
+        reasoning: story.reasoning,
+        modelTier: "balanced"
+      }
+    };
+  });
+}
+
 // src/prd/schema.ts
 init_test_strategy();
 var VALID_COMPLEXITY = ["simple", "medium", "complex", "expert"];
@@ -70825,26 +71099,45 @@ async function planCommand(workdir, config2, options) {
         timeoutSeconds
       });
       const pidRegistry = new PidRegistry(workdir);
+      let planError = null;
       try {
-        await adapter.plan({
-          prompt,
-          workdir,
-          interactive: false,
-          timeoutSeconds,
-          config: config2,
-          modelTier: config2?.plan?.model ?? "balanced",
-          dangerouslySkipPermissions: resolvePermissions(config2, "plan").skipPermissions,
-          maxInteractionTurns: config2?.agent?.maxInteractionTurns,
-          featureName: options.feature,
-          pidRegistry,
-          sessionRole: "plan"
-        });
+        try {
+          await adapter.plan({
+            prompt,
+            workdir,
+            interactive: false,
+            timeoutSeconds,
+            config: config2,
+            modelTier: config2?.plan?.model ?? "balanced",
+            dangerouslySkipPermissions: resolvePermissions(config2, "plan").skipPermissions,
+            maxInteractionTurns: config2?.agent?.maxInteractionTurns,
+            featureName: options.feature,
+            pidRegistry,
+            sessionRole: "plan"
+          });
+        } catch (err) {
+          planError = err instanceof Error ? err : new Error(String(err));
+          logger?.warn("plan", "ACP auto planning did not complete cleanly; checking for written PRD", {
+            error: planError.message,
+            outputPath
+          });
+        }
       } finally {
         await pidRegistry.killAll().catch(() => {});
       }
       if (!_planDeps.existsSync(outputPath)) {
+        if (planError) {
+          throw new Error(`[plan] ACP planning failed and no PRD was written: ${planError.message}`, {
+            cause: planError
+          });
+        }
         throw new Error(`[plan] ACP agent did not write PRD to ${outputPath}. Check agent logs for errors.`);
       }
+      if (planError) {
+        logger?.warn("plan", "Proceeding with PRD written by ACP despite incomplete terminal response", {
+          outputPath
+        });
+      }
       rawResponse = await _planDeps.readFile(outputPath);
     } else {
       const timeoutMs = (config2?.plan?.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS2) * 1000;
@@ -70893,20 +71186,30 @@ async function planCommand(workdir, config2, options) {
       timeoutSeconds
     });
     const planStartTime = Date.now();
+    let planError = null;
     try {
-      await adapter.plan({
-        prompt,
-        workdir,
-        interactive: true,
-        timeoutSeconds,
-        interactionBridge,
-        config: config2,
-        modelTier: resolvedModel,
-        dangerouslySkipPermissions: resolvedPerm.skipPermissions,
-        maxInteractionTurns: config2?.agent?.maxInteractionTurns,
-        featureName: options.feature,
-        pidRegistry
-      });
+      try {
+        await adapter.plan({
+          prompt,
+          workdir,
+          interactive: true,
+          timeoutSeconds,
+          interactionBridge,
+          config: config2,
+          modelTier: resolvedModel,
+          dangerouslySkipPermissions: resolvedPerm.skipPermissions,
+          maxInteractionTurns: config2?.agent?.maxInteractionTurns,
+          featureName: options.feature,
+          pidRegistry,
+          sessionRole: "plan"
+        });
+      } catch (err) {
+        planError = err instanceof Error ? err : new Error(String(err));
+        logger?.warn("plan", "Interactive planning did not complete cleanly; checking for written PRD", {
+          error: planError.message,
+          outputPath
+        });
+      }
     } finally {
       await pidRegistry.killAll().catch(() => {});
       if (interactionChain)
@@ -70914,8 +71217,16 @@ async function planCommand(workdir, config2, options) {
       logger?.info("plan", "Interactive session ended", { durationMs: Date.now() - planStartTime });
     }
     if (!_planDeps.existsSync(outputPath)) {
+      if (planError) {
+        throw new Error(`[plan] Planning failed and no PRD was written: ${planError.message}`, { cause: planError });
+      }
       throw new Error(`[plan] Agent did not write PRD to ${outputPath}. Check agent logs for errors.`);
     }
+    if (planError) {
+      logger?.warn("plan", "Proceeding with PRD written by agent despite incomplete terminal response", {
+        outputPath
+      });
+    }
     return _planDeps.readFile(outputPath);
   }
   const finalPrd = validatePlanOutput(rawResponse, options.feature, branchName);
@@ -71142,58 +71453,6 @@ Generate a JSON object with this exact structure (no markdown, no explanation \u
 ${outputFilePath ? `Write the PRD JSON directly to this file path: ${outputFilePath}
 Do NOT output the JSON to the conversation. Write the file, then reply with a brief confirmation.` : "Output ONLY the JSON object. Do not wrap in markdown code blocks."}`;
 }
-function buildDecomposePrompt2(targetStory, siblings, codebaseContext) {
-  const siblingsSummary = siblings.length > 0 ? `
-## Sibling Stories
-
-${siblings.map((s) => `- ${s.id}: ${s.title}`).join(`
-`)}
-` : "";
-  return `You are a senior software architect decomposing a complex user story into smaller, implementable sub-stories.
-
-## Target Story
-
-${JSON.stringify(targetStory, null, 2)}${siblingsSummary}
-## Codebase Context
-
-${codebaseContext}
-
-${COMPLEXITY_GUIDE}
-
-${TEST_STRATEGY_GUIDE}
-
-${GROUPING_RULES}
-
-${getAcQualityRules()}
-
-## Output
-
-Return JSON with this exact structure (no markdown, no explanation \u2014 JSON only):
-
-{
-  "subStories": [
-    {
-      "id": "string \u2014 e.g. ${targetStory.id}-A",
-      "title": "string",
-      "description": "string",
-      "acceptanceCriteria": ["string \u2014 behavioral, testable criteria"],
-      "contextFiles": ["string \u2014 required, non-empty list of key source files"],
-      "tags": ["string"],
-      "dependencies": ["string"],
-      "status": "pending",
-      "passes": false,
-      "routing": {
-        "complexity": "simple | medium | complex | expert",
-        "testStrategy": "no-test | tdd-simple | three-session-tdd-lite | three-session-tdd | test-after",
-        "modelTier": "fast | balanced | powerful",
-        "reasoning": "string"
-      },
-      "escalations": [],
-      "attempts": 0
-    }
-  ]
-}`;
-}
 async function planDecomposeCommand(workdir, config2, options) {
   const prdPath = join13(workdir, ".nax", "features", options.feature, "prd.json");
   if (!_planDeps.existsSync(prdPath)) {
@@ -71220,31 +71479,34 @@ async function planDecomposeCommand(workdir, config2, options) {
   const scan = await _planDeps.scanCodebase(workdir);
   const codebaseContext = buildCodebaseContext2(scan);
   const siblings = prd.userStories.filter((s) => s.id !== options.storyId);
-  const prompt = buildDecomposePrompt2(targetStory, siblings, codebaseContext);
   const agentName = config2?.autoMode?.defaultAgent ?? "claude";
   const adapter = _planDeps.getAgent(agentName, config2);
   if (!adapter)
     throw new Error(`[decompose] No agent adapter found for '${agentName}'`);
-  let decomposeModel;
-  try {
-    const planTier = config2?.plan?.model ?? "balanced";
-    const { resolveModelForAgent: resolveModelForAgent2 } = await Promise.resolve().then(() => (init_schema(), exports_schema));
-    if (config2?.models) {
-      const defaultAgent = config2.autoMode?.defaultAgent ?? "claude";
-      decomposeModel = resolveModelForAgent2(config2.models, defaultAgent, planTier, defaultAgent).model;
-    }
-  } catch {}
-  const stages = config2?.debate?.stages;
-  const debateEnabled = config2?.debate?.enabled && stages?.decompose?.enabled;
-  let rawResponse;
   const timeoutSeconds = config2?.plan?.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS2;
-  const timeoutMs = timeoutSeconds * 1000;
-  if (debateEnabled) {
-    const stageConfig = stages?.decompose;
+  const maxAcCount = config2?.precheck?.storySizeGate?.maxAcCount ?? Number.POSITIVE_INFINITY;
+  if (typeof adapter.decompose !== "function") {
+    throw new NaxError(`Agent "${agentName}" does not support decompose() required by plan --decompose`, "DECOMPOSE_NOT_SUPPORTED", { stage: "decompose", agent: agentName, storyId: options.storyId });
+  }
+  const debateStages = config2?.debate?.stages;
+  const debateDecompEnabled = config2?.debate?.enabled && debateStages?.decompose?.enabled;
+  let decompStories;
+  if (debateDecompEnabled) {
+    const decomposeStageConfig = debateStages.decompose;
+    const prompt = buildDecomposePrompt({
+      specContent: "",
+      codebaseContext,
+      workdir,
+      targetStory,
+      siblings,
+      featureName: options.feature,
+      storyId: options.storyId,
+      config: config2
+    });
     const debateSession = _planDeps.createDebateSession({
       storyId: options.storyId,
       stage: "decompose",
-      stageConfig,
+      stageConfig: decomposeStageConfig,
       config: config2,
       workdir,
       featureName: options.feature,
@@ -71252,52 +71514,24 @@ async function planDecomposeCommand(workdir, config2, options) {
     });
     const debateResult = await debateSession.run(prompt);
     if (debateResult.outcome !== "failed" && debateResult.output) {
-      rawResponse = debateResult.output;
-    } else {
-      const completeResult = await adapter.complete(prompt, {
-        model: decomposeModel,
-        jsonMode: true,
-        workdir,
-        sessionRole: "decompose",
-        featureName: options.feature,
-        storyId: options.storyId,
-        timeoutMs
-      });
-      rawResponse = typeof completeResult === "string" ? completeResult : completeResult.output;
+      decompStories = parseDecomposeOutput(debateResult.output);
     }
-  } else {
-    const completeResult = await adapter.complete(prompt, {
-      model: decomposeModel,
-      jsonMode: true,
+  }
+  if (!decompStories) {
+    const result = await adapter.decompose({
+      specContent: "",
+      codebaseContext,
       workdir,
-      sessionRole: "decompose",
+      targetStory,
+      siblings,
       featureName: options.feature,
       storyId: options.storyId,
-      timeoutMs
+      config: config2
     });
-    rawResponse = typeof completeResult === "string" ? completeResult : completeResult.output;
-  }
-  const jsonMatch = rawResponse.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
-  const cleanedResponse = jsonMatch ? jsonMatch[1] : rawResponse;
-  let parsed;
-  try {
-    parsed = JSON.parse(cleanedResponse.trim());
-  } catch (err) {
-    throw new NaxError(`Failed to parse decompose response as JSON: ${err.message}
-
-Response (first 500 chars):
-${rawResponse.slice(0, 500)}`, "DECOMPOSE_PARSE_FAILED", { stage: "decompose", storyId: options.storyId });
+    decompStories = result.stories;
   }
-  const subStories = parsed.subStories;
-  const maxAcCount = config2?.precheck?.storySizeGate?.maxAcCount ?? Number.POSITIVE_INFINITY;
-  for (const sub of subStories) {
-    if (!sub.contextFiles || sub.contextFiles.length === 0) {
-      throw new NaxError(`Sub-story "${sub.id}" has empty contextFiles`, "DECOMPOSE_VALIDATION_FAILED", {
-        stage: "decompose",
-        storyId: sub.id
-      });
-    }
-    if (!sub.routing?.complexity || !sub.routing?.testStrategy || !sub.routing?.modelTier) {
+  for (const sub of decompStories) {
+    if (!sub.complexity || !sub.testStrategy) {
       throw new NaxError(`Sub-story "${sub.id}" is missing required routing fields`, "DECOMPOSE_VALIDATION_FAILED", {
         stage: "decompose",
         storyId: sub.id
@@ -71307,8 +71541,8 @@ ${rawResponse.slice(0, 500)}`, "DECOMPOSE_PARSE_FAILED", { stage: "decompose", s
       throw new NaxError(`Sub-story "${sub.id}" has ${sub.acceptanceCriteria.length} ACs, exceeds maxAcCount of ${maxAcCount}`, "DECOMPOSE_VALIDATION_FAILED", { stage: "decompose", storyId: sub.id });
     }
   }
+  const subStoriesWithParent = mapDecomposedStoriesToUserStories(decompStories, options.storyId);
   const updatedStories = prd.userStories.map((s) => s.id === options.storyId ? { ...s, status: "decomposed" } : s);
-  const subStoriesWithParent = subStories.map((s) => ({ ...s, parentStoryId: options.storyId }));
   const originalIndex = updatedStories.findIndex((s) => s.id === options.storyId);
   const finalStories = [
     ...updatedStories.slice(0, originalIndex + 1),
@@ -72987,6 +73221,8 @@ var FIELD_DESCRIPTIONS = {
   "acceptance.generateTests": "Generate acceptance tests during analyze",
   "acceptance.testPath": "Path to acceptance test file (relative to feature dir)",
   "acceptance.command": "Override command to run acceptance tests. Use {{FILE}} as placeholder for the test file path (default: 'bun test {{FILE}} --timeout=60000')",
+  "acceptance.model": "Model tier for acceptance generation/refinement LLM calls (fast | balanced | powerful). Default: fast.",
+  "acceptance.refinement": "Enable acceptance criteria refinement step before execution (default: true). Disable to skip refinement and use generated criteria as-is.",
   "acceptance.timeoutMs": "Timeout for acceptance test generation in milliseconds (default: 1800000 = 30 min)",
   context: "Context injection configuration",
   "context.fileInjection": "Mode: 'disabled' (default, MCP-aware agents pull context on-demand) | 'keyword' (legacy git-grep injection for non-MCP agents). Set context.fileInjection in config.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.57.2",
+  "version": "0.57.3",
   "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {