@nathapp/nax 0.49.3 → 0.50.0

package/dist/nax.js

@@ -3256,29 +3256,30 @@ function resolveTestStrategy(raw) {
 }
 var VALID_TEST_STRATEGIES, COMPLEXITY_GUIDE = `## 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
+- simple: \u226450 LOC, single-file change, purely additive, no new dependencies \u2192 tdd-simple
+- medium: 50\u2013200 LOC, 2\u20135 files, standard patterns, clear requirements \u2192 three-session-tdd-lite
 - 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
+- expert: 500+ LOC, architectural changes, cross-cutting concerns, high risk \u2192 three-session-tdd
 
 ### Security Override
 
 Security-critical functions (authentication, cryptography, tokens, sessions, credentials,
-password hashing, access control) must be classified at MINIMUM "medium" complexity
-regardless of LOC count. These require at minimum "tdd-simple" test strategy.`, TEST_STRATEGY_GUIDE = `## Test Strategy Guide
-
-- test-after: Simple changes with well-understood behavior. Write tests after implementation in a single session.
-- tdd-simple: Medium complexity. Write failing tests first, then implement to pass them \u2014 all in one session.
-- three-session-tdd: Complex stories. 3 sessions: (1) test-writer writes failing tests \u2014 no src/ changes allowed, (2) implementer makes them pass without modifying test files, (3) verifier confirms correctness.
-- three-session-tdd-lite: Expert/high-risk stories. 3 sessions: (1) test-writer writes failing tests and may create minimal src/ stubs for imports, (2) implementer makes tests pass and may add missing coverage or replace stubs, (3) verifier confirms correctness.`, GROUPING_RULES = `## Grouping Rules
-
+password hashing, access control) must use three-session-tdd regardless of complexity.`, TEST_STRATEGY_GUIDE = `## Test Strategy Guide
+
+- tdd-simple: Simple stories (\u226450 LOC). Write failing tests first, then implement to pass them \u2014 all in one session.
+- three-session-tdd-lite: Medium stories, or complex stories involving UI/CLI/integration. 3 sessions: (1) test-writer writes failing tests and may create minimal src/ stubs for imports, (2) implementer makes tests pass and may replace stubs, (3) verifier confirms correctness.
+- three-session-tdd: Complex/expert stories or security-critical code. 3 sessions with strict isolation: (1) test-writer writes failing tests \u2014 no src/ changes allowed, (2) implementer makes them pass without modifying test files, (3) verifier confirms correctness.
+- test-after: Only when explicitly configured (tddStrategy: "off"). Write tests after implementation. Not auto-assigned.`, GROUPING_RULES = `## Story Rules
+
+- Every story must produce code changes verifiable by tests or review.
+- NEVER create stories for analysis, planning, documentation, or migration plans.
+  Your analysis belongs in the "analysis" field, not in a story.
+- NEVER create stories whose primary purpose is writing tests, achieving coverage
+  targets, or running validation/regression suites. Each story's testStrategy
+  handles test creation as part of implementation. Testing is a built-in pipeline
+  stage, not a user story. No exceptions.
 - Combine small, related tasks into a single "simple" or "medium" story.
-- Do NOT create separate stories for every single file or function unless complex.
-- Do NOT create standalone stories purely for test coverage or testing.
-  Each story's testStrategy already handles testing (tdd-simple writes tests first,
-  three-session-tdd uses separate test-writer session, test-after writes tests after).
-  Only create a dedicated test story for unique integration/E2E test logic that spans
-  multiple stories and cannot be covered by individual story test strategies.
+  Do NOT create separate stories for every single file or function unless complex.
 - Aim for coherent units of value. Maximum recommended stories: 10-15 per feature.`;
 var init_test_strategy = __esm(() => {
   VALID_TEST_STRATEGIES = [
@@ -3667,6 +3668,16 @@ function buildAllowedEnv(options) {
 async function executeOnce(binary, options, pidRegistry) {
   const cmd = _runOnceDeps.buildCmd(binary, options);
   const startTime = Date.now();
+  if (options.sessionRole || options.acpSessionName || options.keepSessionOpen) {
+    const logger2 = getLogger();
+    logger2.debug("agent", "CLI mode: session options received (unused)", {
+      sessionRole: options.sessionRole,
+      acpSessionName: options.acpSessionName,
+      keepSessionOpen: options.keepSessionOpen,
+      featureName: options.featureName,
+      storyId: options.storyId
+    });
+  }
   const proc = Bun.spawn(cmd, {
     cwd: options.workdir,
     stdout: "pipe",
@@ -18734,6 +18745,17 @@ IMPORTANT: Output raw TypeScript code only. Do NOT use markdown code fences (\`\
     config: options.config
   });
   const testCode = extractTestCode(rawOutput);
+  if (!testCode) {
+    logger.warn("acceptance", "LLM returned non-code output for acceptance tests \u2014 falling back to skeleton", {
+      outputPreview: rawOutput.slice(0, 200)
+    });
+    const skeletonCriteria = refinedCriteria.map((c, i) => ({
+      id: `AC-${i + 1}`,
+      text: c.refined,
+      lineNumber: i + 1
+    }));
+    return { testCode: generateSkeletonTests(options.featureName, skeletonCriteria), criteria: skeletonCriteria };
+  }
   const refinedJsonContent = JSON.stringify(refinedCriteria.map((c, i) => ({
     acId: `AC-${i + 1}`,
     original: c.original,
@@ -18860,6 +18882,15 @@ async function generateAcceptanceTests(adapter, options) {
       config: options.config
     });
     const testCode = extractTestCode(output);
+    if (!testCode) {
+      logger.warn("acceptance", "LLM returned non-code output for acceptance tests \u2014 falling back to skeleton", {
+        outputPreview: output.slice(0, 200)
+      });
+      return {
+        testCode: generateSkeletonTests(options.featureName, criteria),
+        criteria
+      };
+    }
     return {
       testCode,
       criteria
@@ -18873,15 +18904,30 @@ async function generateAcceptanceTests(adapter, options) {
   }
 }
 function extractTestCode(output) {
+  let code;
   const fenceMatch = output.match(/```(?:typescript|ts)?\s*([\s\S]*?)\s*```/);
   if (fenceMatch) {
-    return fenceMatch[1].trim();
+    code = fenceMatch[1].trim();
+  }
+  if (!code) {
+    const importMatch = output.match(/import\s+{[\s\S]+/);
+    if (importMatch) {
+      code = importMatch[0].trim();
+    }
   }
-  const importMatch = output.match(/import\s+{[\s\S]+/);
-  if (importMatch) {
-    return importMatch[0].trim();
+  if (!code) {
+    const describeMatch = output.match(/describe\s*\([\s\S]+/);
+    if (describeMatch) {
+      code = describeMatch[0].trim();
+    }
+  }
+  if (!code)
+    return null;
+  const hasTestKeyword = /\b(?:describe|test|it|expect)\s*\(/.test(code);
+  if (!hasTestKeyword) {
+    return null;
   }
-  return output.trim();
+  return code;
 }
 function generateSkeletonTests(featureName, criteria) {
   const tests = criteria.map((ac) => {
@@ -19276,7 +19322,6 @@ class SpawnAcpClient {
   model;
   cwd;
   timeoutSeconds;
-  permissionMode;
   env;
   pidRegistry;
   constructor(cmdStr, cwd, timeoutSeconds, pidRegistry) {
@@ -19290,7 +19335,6 @@ class SpawnAcpClient {
     this.agentName = lastToken;
     this.cwd = cwd || process.cwd();
     this.timeoutSeconds = timeoutSeconds || 1800;
-    this.permissionMode = "approve-reads";
     this.env = buildAllowedEnv2();
     this.pidRegistry = pidRegistry;
   }
@@ -19432,7 +19476,13 @@ async function closeAcpSession(session) {
 function acpSessionsPath(workdir, featureName) {
   return join3(workdir, "nax", "features", featureName, "acp-sessions.json");
 }
-async function saveAcpSession(workdir, featureName, storyId, sessionName) {
+function sidecarSessionName(entry) {
+  return typeof entry === "string" ? entry : entry.sessionName;
+}
+function sidecarAgentName(entry) {
+  return typeof entry === "string" ? "claude" : entry.agentName;
+}
+async function saveAcpSession(workdir, featureName, storyId, sessionName, agentName = "claude") {
   try {
     const path = acpSessionsPath(workdir, featureName);
     let data = {};
@@ -19440,7 +19490,7 @@ async function saveAcpSession(workdir, featureName, storyId, sessionName) {
       const existing = await Bun.file(path).text();
       data = JSON.parse(existing);
     } catch {}
-    data[storyId] = sessionName;
+    data[storyId] = { sessionName, agentName };
     await Bun.write(path, JSON.stringify(data, null, 2));
   } catch (err) {
     getSafeLogger()?.warn("acp-adapter", "Failed to save session to sidecar", { error: String(err) });
@@ -19467,7 +19517,8 @@ async function readAcpSession(workdir, featureName, storyId) {
     const path = acpSessionsPath(workdir, featureName);
     const existing = await Bun.file(path).text();
     const data = JSON.parse(existing);
-    return data[storyId] ?? null;
+    const entry = data[storyId];
+    return entry ? sidecarSessionName(entry) : null;
   } catch {
     return null;
   }
@@ -19486,24 +19537,34 @@ async function sweepFeatureSessions(workdir, featureName) {
     return;
   const logger = getSafeLogger();
   logger?.info("acp-adapter", `[sweep] Closing ${entries.length} open sessions for feature: ${featureName}`);
-  const cmdStr = "acpx claude";
-  const client = _acpAdapterDeps.createClient(cmdStr, workdir);
-  try {
-    await client.start();
-    for (const [, sessionName] of entries) {
-      try {
-        if (client.loadSession) {
-          const session = await client.loadSession(sessionName, "claude", "approve-reads");
-          if (session) {
-            await session.close().catch(() => {});
+  const byAgent = new Map;
+  for (const [, entry] of entries) {
+    const agent = sidecarAgentName(entry);
+    const name = sidecarSessionName(entry);
+    if (!byAgent.has(agent))
+      byAgent.set(agent, []);
+    byAgent.get(agent)?.push(name);
+  }
+  for (const [agentName, sessionNames] of byAgent) {
+    const cmdStr = `acpx ${agentName}`;
+    const client = _acpAdapterDeps.createClient(cmdStr, workdir);
+    try {
+      await client.start();
+      for (const sessionName of sessionNames) {
+        try {
+          if (client.loadSession) {
+            const session = await client.loadSession(sessionName, agentName, "approve-reads");
+            if (session) {
+              await session.close().catch(() => {});
+            }
           }
+        } catch (err) {
+          logger?.warn("acp-adapter", `[sweep] Failed to close session ${sessionName}`, { error: String(err) });
         }
-      } catch (err) {
-        logger?.warn("acp-adapter", `[sweep] Failed to close session ${sessionName}`, { error: String(err) });
       }
+    } finally {
+      await client.close().catch(() => {});
     }
-  } finally {
-    await client.close().catch(() => {});
   }
   try {
     await Bun.write(path, JSON.stringify({}, null, 2));
@@ -19644,7 +19705,7 @@ class AcpAgentAdapter {
     });
     const session = await ensureAcpSession(client, sessionName, this.name, permissionMode);
     if (options.featureName && options.storyId) {
-      await saveAcpSession(options.workdir, options.featureName, options.storyId, sessionName);
+      await saveAcpSession(options.workdir, options.featureName, options.storyId, sessionName, this.name);
     }
     let lastResponse = null;
     let timedOut = false;
@@ -19702,13 +19763,15 @@ class AcpAgentAdapter {
       }
       runState.succeeded = !timedOut && lastResponse?.stopReason === "end_turn";
     } finally {
-      if (runState.succeeded) {
+      if (runState.succeeded && !options.keepSessionOpen) {
         await closeAcpSession(session);
         if (options.featureName && options.storyId) {
           await clearAcpSession(options.workdir, options.featureName, options.storyId);
         }
-      } else {
+      } else if (!runState.succeeded) {
         getSafeLogger()?.info("acp-adapter", "Keeping session open for retry", { sessionName });
+      } else {
+        getSafeLogger()?.debug("acp-adapter", "Keeping session open (keepSessionOpen=true)", { sessionName });
       }
       await client.close().catch(() => {});
     }
@@ -20336,7 +20399,8 @@ function applyDecomposition(prd, result) {
   const originalIndex = prd.userStories.findIndex((s) => s.id === parentStoryId);
   if (originalIndex === -1)
     return;
-  prd.userStories[originalIndex].status = "decomposed";
+  const parentStory = prd.userStories[originalIndex];
+  parentStory.status = "decomposed";
   const newStories = subStories.map((sub) => ({
     id: sub.id,
     title: sub.title,
@@ -20348,7 +20412,8 @@ function applyDecomposition(prd, result) {
     passes: false,
     escalations: [],
     attempts: 0,
-    parentStoryId: sub.parentStoryId
+    parentStoryId: sub.parentStoryId,
+    ...parentStory.workdir !== undefined && { workdir: parentStory.workdir }
   }));
   prd.userStories.splice(originalIndex + 1, 0, ...newStories);
 }
@@ -20726,6 +20791,18 @@ function mergePackageConfig(root, packageOverride) {
       ...packageOverride.review,
       commands: {
         ...root.review.commands,
+        ...packageOverride.quality?.commands?.lint !== undefined && {
+          lint: packageOverride.quality.commands.lint
+        },
+        ...packageOverride.quality?.commands?.lintFix !== undefined && {
+          lintFix: packageOverride.quality.commands.lintFix
+        },
+        ...packageOverride.quality?.commands?.typecheck !== undefined && {
+          typecheck: packageOverride.quality.commands.typecheck
+        },
+        ...packageOverride.quality?.commands?.test !== undefined && {
+          test: packageOverride.quality.commands.test
+        },
         ...packageOverride.review?.commands
       }
     },
@@ -22216,7 +22293,7 @@ function markStoryPassed(prd, storyId) {
     story.status = "passed";
   }
 }
-function markStoryFailed(prd, storyId, failureCategory) {
+function markStoryFailed(prd, storyId, failureCategory, failureStage) {
   const story = prd.userStories.find((s) => s.id === storyId);
   if (story) {
     story.status = "failed";
@@ -22224,6 +22301,9 @@ function markStoryFailed(prd, storyId, failureCategory) {
     if (failureCategory !== undefined) {
       story.failureCategory = failureCategory;
     }
+    if (failureStage !== undefined) {
+      story.failureStage = failureStage;
+    }
   }
 }
 function markStorySkipped(prd, storyId) {
@@ -22250,7 +22330,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@nathapp/nax",
-    version: "0.49.3",
+    version: "0.50.0",
     description: "AI Coding Agent Orchestrator \u2014 loops until done",
     type: "module",
     bin: {
@@ -22323,8 +22403,8 @@ var init_version = __esm(() => {
   NAX_VERSION = package_default.version;
   NAX_COMMIT = (() => {
     try {
-      if (/^[0-9a-f]{6,10}$/.test("30ff375"))
-        return "30ff375";
+      if (/^[0-9a-f]{6,10}$/.test("0eeefb4"))
+        return "0eeefb4";
     } catch {}
     try {
       const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
@@ -23309,6 +23389,7 @@ class WebhookInteractionPlugin {
   server = null;
   serverStartPromise = null;
   pendingResponses = new Map;
+  receiveCallbacks = new Map;
   async init(config2) {
     const cfg = WebhookConfigSchema.parse(config2);
     this.config = {
@@ -23358,27 +23439,39 @@ class WebhookInteractionPlugin {
   }
   async receive(requestId, timeout = 60000) {
     await this.startServer();
-    const startTime = Date.now();
-    let backoffMs = 100;
-    const maxBackoffMs = 2000;
-    while (Date.now() - startTime < timeout) {
-      const response = this.pendingResponses.get(requestId);
-      if (response) {
-        this.pendingResponses.delete(requestId);
-        return response;
-      }
-      await _webhookPluginDeps.sleep(backoffMs);
-      backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
+    const early = this.pendingResponses.get(requestId);
+    if (early) {
+      this.pendingResponses.delete(requestId);
+      return early;
     }
-    return {
-      requestId,
-      action: "skip",
-      respondedBy: "timeout",
-      respondedAt: Date.now()
-    };
+    return new Promise((resolve7) => {
+      const timer = setTimeout(() => {
+        this.receiveCallbacks.delete(requestId);
+        resolve7({
+          requestId,
+          action: "skip",
+          respondedBy: "timeout",
+          respondedAt: Date.now()
+        });
+      }, timeout);
+      this.receiveCallbacks.set(requestId, (response) => {
+        clearTimeout(timer);
+        this.receiveCallbacks.delete(requestId);
+        resolve7(response);
+      });
+    });
   }
   async cancel(requestId) {
     this.pendingResponses.delete(requestId);
+    this.receiveCallbacks.delete(requestId);
+  }
+  deliverResponse(requestId, response) {
+    const cb = this.receiveCallbacks.get(requestId);
+    if (cb) {
+      cb(response);
+    } else {
+      this.pendingResponses.set(requestId, response);
+    }
   }
   async startServer() {
     if (this.server)
@@ -23431,7 +23524,7 @@ class WebhookInteractionPlugin {
       try {
         const parsed = JSON.parse(body);
         const response = InteractionResponseSchema.parse(parsed);
-        this.pendingResponses.set(requestId, response);
+        this.deliverResponse(requestId, response);
       } catch {
         return new Response("Bad Request: Invalid response format", { status: 400 });
       }
@@ -23439,7 +23532,7 @@ class WebhookInteractionPlugin {
       try {
         const parsed = await req.json();
         const response = InteractionResponseSchema.parse(parsed);
-        this.pendingResponses.set(requestId, response);
+        this.deliverResponse(requestId, response);
       } catch {
         return new Response("Bad Request: Invalid response format", { status: 400 });
       }
@@ -23466,12 +23559,9 @@ class WebhookInteractionPlugin {
     }
   }
 }
-var _webhookPluginDeps, WebhookConfigSchema, InteractionResponseSchema;
+var 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(),
@@ -24706,6 +24796,9 @@ ${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})
@@ -24716,7 +24809,7 @@ ${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.`;
+Commit your fixes when done.${scopeConstraint}`;
 }
 async function runAgentRectification(ctx) {
   const logger = getLogger();
@@ -24743,9 +24836,10 @@ async function runAgentRectification(ctx) {
     const prompt = buildReviewRectificationPrompt(failedChecks, ctx.story);
     const modelTier = ctx.story.routing?.modelTier ?? ctx.config.autoMode.escalation.tierOrder[0]?.tier ?? "balanced";
     const modelDef = resolveModel(ctx.config.models[modelTier]);
+    const rectificationWorkdir = ctx.story.workdir ? join18(ctx.workdir, ctx.story.workdir) : ctx.workdir;
     await agent.run({
       prompt,
-      workdir: ctx.workdir,
+      workdir: rectificationWorkdir,
       modelTier,
       modelDef,
       timeoutSeconds: ctx.config.execution.sessionTimeoutSeconds,
@@ -25299,6 +25393,32 @@ var init_elements = __esm(() => {
   init_logger2();
 });
 
+// src/context/parent-context.ts
+function getParentOutputFiles(story, allStories) {
+  if (!story.dependencies || story.dependencies.length === 0)
+    return [];
+  const parentFiles = [];
+  for (const depId of story.dependencies) {
+    const parent = allStories.find((s) => s.id === depId);
+    if (parent?.outputFiles) {
+      parentFiles.push(...parent.outputFiles);
+    }
+  }
+  const unique = [...new Set(parentFiles)];
+  return unique.filter((f) => !NOISE_PATTERNS.some((p) => p.test(f))).slice(0, MAX_PARENT_FILES);
+}
+var MAX_PARENT_FILES = 10, NOISE_PATTERNS;
+var init_parent_context = __esm(() => {
+  NOISE_PATTERNS = [
+    /\.test\.(ts|js|tsx|jsx)$/,
+    /\.spec\.(ts|js|tsx|jsx)$/,
+    /package-lock\.json$/,
+    /bun\.lockb?$/,
+    /\.gitignore$/,
+    /^nax\//
+  ];
+});
+
 // src/context/test-scanner.ts
 import path6 from "path";
 var {Glob } = globalThis.Bun;
@@ -25646,6 +25766,18 @@ async function buildContext(storyContext, budget) {
     }
   }
   elements.push(createStoryContext(currentStory, 80));
+  if (prd.analysis) {
+    const analysisContent = `The following analysis was performed during the planning phase. Use it to understand the codebase context before implementing:
+
+${prd.analysis}`;
+    elements.push({
+      type: "planning-analysis",
+      label: "Planning Analysis",
+      content: analysisContent,
+      priority: 88,
+      tokens: estimateTokens(analysisContent)
+    });
+  }
   addDependencyElements(elements, currentStory, prd);
   await addTestCoverageElement(elements, storyContext, currentStory);
   await addFileElements(elements, storyContext, currentStory);
@@ -25706,6 +25838,15 @@ async function addFileElements(elements, storyContext, story) {
   if (fileInjection !== "keyword")
     return;
   let contextFiles = getContextFiles(story);
+  const parentFiles = getParentOutputFiles(story, storyContext.prd?.userStories ?? []);
+  if (parentFiles.length > 0) {
+    const logger = getLogger();
+    logger.info("context", "Injecting parent output files for context chaining", {
+      storyId: story.id,
+      parentFiles
+    });
+    contextFiles = [...new Set([...contextFiles, ...parentFiles])];
+  }
   if (contextFiles.length === 0 && storyContext.config?.context?.autoDetect?.enabled !== false && storyContext.workdir) {
     const autoDetectConfig = storyContext.config?.context?.autoDetect;
     try {
@@ -25773,6 +25914,7 @@ var init_builder3 = __esm(() => {
   init_prd();
   init_auto_detect();
   init_elements();
+  init_parent_context();
   init_test_scanner();
   init_elements();
   _deps5 = {
@@ -26037,13 +26179,13 @@ function isSourceFile(filePath) {
   return SRC_PATTERNS.some((pattern) => pattern.test(filePath));
 }
 async function getChangedFiles2(workdir, fromRef = "HEAD") {
-  const proc = Bun.spawn(["git", "diff", "--name-only", fromRef], {
+  const proc = _isolationDeps.spawn(["git", "diff", "--name-only", fromRef], {
     cwd: workdir,
     stdout: "pipe",
     stderr: "pipe"
   });
+  const output = await Bun.readableStreamToText(proc.stdout);
   await proc.exited;
-  const output = await new Response(proc.stdout).text();
   return output.trim().split(`
 `).filter(Boolean);
 }
@@ -26090,8 +26232,9 @@ async function verifyImplementerIsolation(workdir, beforeRef) {
     description: "Implementer should not modify test files"
   };
 }
-var TEST_PATTERNS, SRC_PATTERNS;
+var _isolationDeps, TEST_PATTERNS, SRC_PATTERNS;
 var init_isolation = __esm(() => {
+  _isolationDeps = { spawn: Bun.spawn };
   TEST_PATTERNS = [/^test\//, /^tests\//, /^__tests__\//, /\.spec\.\w+$/, /\.test\.\w+$/, /\.e2e-spec\.\w+$/];
   SRC_PATTERNS = [/^src\//, /^lib\//, /^packages\//];
 });
@@ -26241,6 +26384,22 @@ async function autoCommitIfDirty(workdir, stage, role, storyId) {
     await commitProc.exited;
   } catch {}
 }
+async function captureOutputFiles(workdir, baseRef, scopePrefix) {
+  if (!baseRef)
+    return [];
+  try {
+    const args = ["diff", "--name-only", `${baseRef}..HEAD`];
+    if (scopePrefix)
+      args.push("--", `${scopePrefix}/`);
+    const proc = _gitDeps.spawn(["git", ...args], { cwd: workdir, stdout: "pipe", stderr: "pipe" });
+    const output = await new Response(proc.stdout).text();
+    await proc.exited;
+    return output.trim().split(`
+`).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
 var _gitDeps, GIT_TIMEOUT_MS = 1e4;
 var init_git = __esm(() => {
   init_logger2();
@@ -26289,7 +26448,7 @@ async function executeWithTimeout(command, timeoutSeconds, env2, options) {
   const shell = options?.shell ?? "/bin/sh";
   const gracePeriodMs = options?.gracePeriodMs ?? 5000;
   const drainTimeoutMs = options?.drainTimeoutMs ?? 2000;
-  const proc = Bun.spawn([shell, "-c", command], {
+  const proc = _executorDeps.spawn([shell, "-c", command], {
     stdout: "pipe",
     stderr: "pipe",
     env: env2 || normalizeEnvironment(process.env),
@@ -26383,8 +26542,9 @@ function buildTestCommand(baseCommand, options) {
   }
   return command;
 }
-var DEFAULT_STRIP_ENV_VARS;
+var _executorDeps, DEFAULT_STRIP_ENV_VARS;
 var init_executor = __esm(() => {
+  _executorDeps = { spawn: Bun.spawn };
   DEFAULT_STRIP_ENV_VARS = ["CLAUDECODE", "REPL_ID", "AGENT"];
 });
 
@@ -26684,15 +26844,15 @@ var init_verification = __esm(() => {
 // src/tdd/cleanup.ts
 async function getPgid(pid) {
   try {
-    const proc = Bun.spawn(["ps", "-o", "pgid=", "-p", String(pid)], {
+    const proc = _cleanupDeps.spawn(["ps", "-o", "pgid=", "-p", String(pid)], {
       stdout: "pipe",
       stderr: "pipe"
     });
+    const output = await Bun.readableStreamToText(proc.stdout);
     const exitCode = await proc.exited;
     if (exitCode !== 0) {
       return null;
     }
-    const output = await new Response(proc.stdout).text();
     const pgid = Number.parseInt(output.trim(), 10);
     return Number.isNaN(pgid) ? null : pgid;
   } catch {
@@ -26706,7 +26866,7 @@ async function cleanupProcessTree(pid, gracePeriodMs = 3000) {
       return;
     }
     try {
-      process.kill(-pgid, "SIGTERM");
+      _cleanupDeps.kill(-pgid, "SIGTERM");
     } catch (error48) {
       const err = error48;
       if (err.code !== "ESRCH") {
@@ -26714,11 +26874,11 @@ async function cleanupProcessTree(pid, gracePeriodMs = 3000) {
       }
       return;
     }
-    await Bun.sleep(gracePeriodMs);
+    await _cleanupDeps.sleep(gracePeriodMs);
     const pgidAfterWait = await getPgid(pid);
     if (pgidAfterWait && pgidAfterWait === pgid) {
       try {
-        process.kill(-pgid, "SIGKILL");
+        _cleanupDeps.kill(-pgid, "SIGKILL");
       } catch {}
     }
   } catch (error48) {
@@ -26729,8 +26889,14 @@ async function cleanupProcessTree(pid, gracePeriodMs = 3000) {
     });
   }
 }
+var _cleanupDeps;
 var init_cleanup = __esm(() => {
   init_logger2();
+  _cleanupDeps = {
+    spawn: Bun.spawn,
+    sleep: Bun.sleep,
+    kill: process.kill.bind(process)
+  };
 });
 
 // src/tdd/prompts.ts
@@ -26753,10 +26919,12 @@ async function runFullSuiteGate(story, config2, workdir, agent, implementerTier,
     storyId: story.id,
     timeout: fullSuiteTimeout
   });
-  const fullSuiteResult = await executeWithTimeout(testCmd, fullSuiteTimeout, undefined, { cwd: workdir });
+  const fullSuiteResult = await _rectificationGateDeps.executeWithTimeout(testCmd, fullSuiteTimeout, undefined, {
+    cwd: workdir
+  });
   const fullSuitePassed = fullSuiteResult.success && fullSuiteResult.exitCode === 0;
   if (!fullSuitePassed && fullSuiteResult.output) {
-    const testSummary = parseBunTestOutput(fullSuiteResult.output);
+    const testSummary = _rectificationGateDeps.parseBunTestOutput(fullSuiteResult.output);
     if (testSummary.failed > 0) {
       return await runRectificationLoop(story, config2, workdir, agent, implementerTier, contextMarkdown, lite, logger, testSummary, rectificationConfig, testCmd, fullSuiteTimeout, featureName);
     }
@@ -26797,8 +26965,14 @@ async function runRectificationLoop(story, config2, workdir, agent, implementerT
     failedTests: testSummary.failed,
     passedTests: testSummary.passed
   });
-  while (shouldRetryRectification(rectificationState, rectificationConfig)) {
+  const rectificationSessionName = buildSessionName(workdir, featureName, story.id, "implementer");
+  logger.debug("tdd", "Rectification session name (shared across all attempts)", {
+    storyId: story.id,
+    sessionName: rectificationSessionName
+  });
+  while (_rectificationGateDeps.shouldRetryRectification(rectificationState, rectificationConfig)) {
     rectificationState.attempt++;
+    const isLastAttempt = rectificationState.attempt >= rectificationConfig.maxRetries;
     logger.info("tdd", `-> Implementer rectification attempt ${rectificationState.attempt}/${rectificationConfig.maxRetries}`, { storyId: story.id, currentFailures: rectificationState.currentFailures });
     const rectificationPrompt = buildImplementerRectificationPrompt(testSummary.failures, story, contextMarkdown, rectificationConfig);
     const rectifyBeforeRef = await captureGitRef(workdir) ?? "HEAD";
@@ -26814,7 +26988,9 @@ async function runRectificationLoop(story, config2, workdir, agent, implementerT
       maxInteractionTurns: config2.agent?.maxInteractionTurns,
       featureName,
       storyId: story.id,
-      sessionRole: "implementer"
+      sessionRole: "implementer",
+      acpSessionName: rectificationSessionName,
+      keepSessionOpen: !isLastAttempt
     });
     if (!rectifyResult.success && rectifyResult.pid) {
       await cleanupProcessTree(rectifyResult.pid);
@@ -26842,7 +27018,9 @@ async function runRectificationLoop(story, config2, workdir, agent, implementerT
       });
       break;
     }
-    const retryFullSuite = await executeWithTimeout(testCmd, fullSuiteTimeout, undefined, { cwd: workdir });
+    const retryFullSuite = await _rectificationGateDeps.executeWithTimeout(testCmd, fullSuiteTimeout, undefined, {
+      cwd: workdir
+    });
     const retrySuitePassed = retryFullSuite.success && retryFullSuite.exitCode === 0;
     if (retrySuitePassed) {
       logger.info("tdd", "Full suite gate passed after rectification!", {
@@ -26852,7 +27030,7 @@ async function runRectificationLoop(story, config2, workdir, agent, implementerT
       return true;
     }
     if (retryFullSuite.output) {
-      const newTestSummary = parseBunTestOutput(retryFullSuite.output);
+      const newTestSummary = _rectificationGateDeps.parseBunTestOutput(retryFullSuite.output);
       rectificationState.currentFailures = newTestSummary.failed;
       testSummary.failures = newTestSummary.failures;
       testSummary.failed = newTestSummary.failed;
@@ -26864,7 +27042,9 @@ async function runRectificationLoop(story, config2, workdir, agent, implementerT
       remainingFailures: rectificationState.currentFailures
     });
   }
-  const finalFullSuite = await executeWithTimeout(testCmd, fullSuiteTimeout, undefined, { cwd: workdir });
+  const finalFullSuite = await _rectificationGateDeps.executeWithTimeout(testCmd, fullSuiteTimeout, undefined, {
+    cwd: workdir
+  });
   const finalSuitePassed = finalFullSuite.success && finalFullSuite.exitCode === 0;
   if (!finalSuitePassed) {
     logger.warn("tdd", "[WARN] Full suite gate failed after rectification exhausted", {
@@ -26877,13 +27057,20 @@ async function runRectificationLoop(story, config2, workdir, agent, implementerT
   logger.info("tdd", "Full suite gate passed", { storyId: story.id });
   return true;
 }
+var _rectificationGateDeps;
 var init_rectification_gate = __esm(() => {
+  init_adapter2();
   init_config();
   init_git();
   init_verification();
   init_cleanup();
   init_isolation();
   init_prompts();
+  _rectificationGateDeps = {
+    executeWithTimeout,
+    parseBunTestOutput,
+    shouldRetryRectification
+  };
 });
 
 // src/prompts/sections/conventions.ts
@@ -27373,7 +27560,7 @@ ${tail}`;
 async function rollbackToRef(workdir, ref) {
   const logger = getLogger();
   logger.warn("tdd", "Rolling back git changes", { ref });
-  const resetProc = Bun.spawn(["git", "reset", "--hard", ref], {
+  const resetProc = _sessionRunnerDeps.spawn(["git", "reset", "--hard", ref], {
     cwd: workdir,
     stdout: "pipe",
     stderr: "pipe"
@@ -27384,7 +27571,7 @@ async function rollbackToRef(workdir, ref) {
     logger.error("tdd", "Failed to rollback git changes", { ref, stderr });
     throw new Error(`Git rollback failed: ${stderr}`);
   }
-  const cleanProc = Bun.spawn(["git", "clean", "-fd"], {
+  const cleanProc = _sessionRunnerDeps.spawn(["git", "clean", "-fd"], {
     cwd: workdir,
     stdout: "pipe",
     stderr: "pipe"
@@ -27399,19 +27586,24 @@ async function rollbackToRef(workdir, ref) {
 async function runTddSession(role, agent, story, config2, workdir, modelTier, beforeRef, contextMarkdown, lite = false, skipIsolation = false, constitution, featureName) {
   const startTime = Date.now();
   let prompt;
-  switch (role) {
-    case "test-writer":
-      prompt = await PromptBuilder.for("test-writer", { isolation: lite ? "lite" : "strict" }).withLoader(workdir, config2).story(story).context(contextMarkdown).constitution(constitution).testCommand(config2.quality?.commands?.test).build();
-      break;
-    case "implementer":
-      prompt = await PromptBuilder.for("implementer", { variant: lite ? "lite" : "standard" }).withLoader(workdir, config2).story(story).context(contextMarkdown).constitution(constitution).testCommand(config2.quality?.commands?.test).build();
-      break;
-    case "verifier":
-      prompt = await PromptBuilder.for("verifier").withLoader(workdir, config2).story(story).context(contextMarkdown).constitution(constitution).testCommand(config2.quality?.commands?.test).build();
-      break;
+  if (_sessionRunnerDeps.buildPrompt) {
+    prompt = await _sessionRunnerDeps.buildPrompt(role, config2, story, workdir, contextMarkdown, lite, constitution);
+  } else {
+    switch (role) {
+      case "test-writer":
+        prompt = await PromptBuilder.for("test-writer", { isolation: lite ? "lite" : "strict" }).withLoader(workdir, config2).story(story).context(contextMarkdown).constitution(constitution).testCommand(config2.quality?.commands?.test).build();
+        break;
+      case "implementer":
+        prompt = await PromptBuilder.for("implementer", { variant: lite ? "lite" : "standard" }).withLoader(workdir, config2).story(story).context(contextMarkdown).constitution(constitution).testCommand(config2.quality?.commands?.test).build();
+        break;
+      case "verifier":
+        prompt = await PromptBuilder.for("verifier").withLoader(workdir, config2).story(story).context(contextMarkdown).constitution(constitution).testCommand(config2.quality?.commands?.test).build();
+        break;
+    }
   }
   const logger = getLogger();
   logger.info("tdd", `-> Session: ${role}`, { role, storyId: story.id, lite });
+  const keepSessionOpen = role === "implementer" && (config2.execution.rectification?.enabled ?? false);
   const result = await agent.run({
     prompt,
     workdir,
@@ -27424,10 +27616,11 @@ async function runTddSession(role, agent, story, config2, workdir, modelTier, be
     maxInteractionTurns: config2.agent?.maxInteractionTurns,
     featureName,
     storyId: story.id,
-    sessionRole: role
+    sessionRole: role,
+    keepSessionOpen
   });
   if (!result.success && result.pid) {
-    await cleanupProcessTree(result.pid);
+    await _sessionRunnerDeps.cleanupProcessTree(result.pid);
   }
   if (result.success) {
     logger.info("tdd", `Session complete: ${role}`, {
@@ -27449,12 +27642,12 @@ async function runTddSession(role, agent, story, config2, workdir, modelTier, be
   if (!skipIsolation) {
     if (role === "test-writer") {
       const allowedPaths = config2.tdd.testWriterAllowedPaths ?? ["src/index.ts", "src/**/index.ts"];
-      isolation = await verifyTestWriterIsolation(workdir, beforeRef, allowedPaths);
+      isolation = await _sessionRunnerDeps.verifyTestWriterIsolation(workdir, beforeRef, allowedPaths);
     } else if (role === "implementer" || role === "verifier") {
-      isolation = await verifyImplementerIsolation(workdir, beforeRef);
+      isolation = await _sessionRunnerDeps.verifyImplementerIsolation(workdir, beforeRef);
     }
   }
-  const filesChanged = await getChangedFiles2(workdir, beforeRef);
+  const filesChanged = await _sessionRunnerDeps.getChangedFiles(workdir, beforeRef);
   const durationMs = Date.now() - startTime;
   if (isolation && !isolation.passed) {
     logger.error("tdd", "Isolation violated", {
@@ -27497,10 +27690,18 @@ var init_session_runner = __esm(() => {
   init_logger2();
   init_prompts2();
   init_git();
+  init_git();
   init_cleanup();
   init_isolation();
   _sessionRunnerDeps = {
-    autoCommitIfDirty
+    autoCommitIfDirty,
+    spawn: Bun.spawn,
+    getChangedFiles: getChangedFiles2,
+    verifyTestWriterIsolation,
+    verifyImplementerIsolation,
+    captureGitRef,
+    cleanupProcessTree,
+    buildPrompt: null
   };
 });
 
@@ -28981,7 +29182,7 @@ class AcceptanceStrategy {
     }
     const start = Date.now();
     const timeoutMs = ctx.timeoutSeconds * 1000;
-    const proc = Bun.spawn(["bun", "test", testPath], {
+    const proc = _acceptanceDeps.spawn(["bun", "test", testPath], {
       cwd: ctx.workdir,
       stdout: "pipe",
       stderr: "pipe"
@@ -29049,8 +29250,10 @@ ${stderr}`;
     });
   }
 }
+var _acceptanceDeps;
 var init_acceptance3 = __esm(() => {
   init_logger2();
+  _acceptanceDeps = { spawn: Bun.spawn };
 });
 
 // src/verification/strategies/regression.ts
@@ -33047,7 +33250,7 @@ async function executeParallel(stories, prdPath, projectRoot, config2, hooks, pl
           worktreePath
         });
       } catch (error48) {
-        markStoryFailed(currentPrd, story.id);
+        markStoryFailed(currentPrd, story.id, undefined, undefined);
         logger?.error("parallel", "Failed to create worktree", {
           storyId: story.id,
           error: errorMessage(error48)
@@ -33075,7 +33278,7 @@ async function executeParallel(stories, prdPath, projectRoot, config2, hooks, pl
             retryCount: mergeResult.retryCount
           });
         } else {
-          markStoryFailed(currentPrd, mergeResult.storyId);
+          markStoryFailed(currentPrd, mergeResult.storyId, undefined, undefined);
           batchResult.mergeConflicts.push({
             storyId: mergeResult.storyId,
             conflictFiles: mergeResult.conflictFiles || [],
@@ -33093,7 +33296,7 @@ async function executeParallel(stories, prdPath, projectRoot, config2, hooks, pl
       }
     }
     for (const { story, error: error48 } of batchResult.failed) {
-      markStoryFailed(currentPrd, story.id);
+      markStoryFailed(currentPrd, story.id, undefined, undefined);
       logger?.error("parallel", "Cleaning up failed story worktree", {
         storyId: story.id,
         error: error48
@@ -34030,7 +34233,7 @@ async function handleNoTierAvailable(ctx, failureCategory) {
     return { outcome: "paused", prdDirty: true, prd: pausedPrd };
   }
   const failedPrd = { ...ctx.prd };
-  markStoryFailed(failedPrd, ctx.story.id, failureCategory);
+  markStoryFailed(failedPrd, ctx.story.id, failureCategory, undefined);
   await savePRD(failedPrd, ctx.prdPath);
   logger?.error("execution", "Story failed - execution failed", {
     storyId: ctx.story.id
@@ -34070,7 +34273,7 @@ async function handleMaxAttemptsReached(ctx, failureCategory) {
     return { outcome: "paused", prdDirty: true, prd: pausedPrd };
   }
   const failedPrd = { ...ctx.prd };
-  markStoryFailed(failedPrd, ctx.story.id, failureCategory);
+  markStoryFailed(failedPrd, ctx.story.id, failureCategory, undefined);
   await savePRD(failedPrd, ctx.prdPath);
   logger?.error("execution", "Story failed - max attempts reached", {
     storyId: ctx.story.id,
@@ -34235,6 +34438,17 @@ var init_escalation = __esm(() => {
 });
 
 // src/execution/pipeline-result-handler.ts
+function filterOutputFiles(files) {
+  const NOISE = [
+    /\.test\.(ts|js|tsx|jsx)$/,
+    /\.spec\.(ts|js|tsx|jsx)$/,
+    /package-lock\.json$/,
+    /bun\.lock(b?)$/,
+    /\.gitignore$/,
+    /^nax\//
+  ];
+  return files.filter((f) => !NOISE.some((p) => p.test(f))).slice(0, 15);
+}
 async function handlePipelineSuccess(ctx, pipelineResult) {
   const logger = getSafeLogger();
   const costDelta = pipelineResult.context.agentResult?.estimatedCost || 0;
@@ -34263,6 +34477,17 @@ async function handlePipelineSuccess(ctx, pipelineResult) {
       testStrategy: ctx.routing.testStrategy
     });
   }
+  if (ctx.storyGitRef) {
+    for (const completedStory of ctx.storiesToExecute) {
+      try {
+        const rawFiles = await captureOutputFiles(ctx.workdir, ctx.storyGitRef, completedStory.workdir);
+        const filtered = filterOutputFiles(rawFiles);
+        if (filtered.length > 0) {
+          completedStory.outputFiles = filtered;
+        }
+      } catch {}
+    }
+  }
   const updatedCounts = countStories(prd);
   logger?.info("progress", "Progress update", {
     totalStories: updatedCounts.total,
@@ -34299,7 +34524,7 @@ async function handlePipelineFailure(ctx, pipelineResult) {
       prdDirty = true;
       break;
     case "fail":
-      markStoryFailed(prd, ctx.story.id, pipelineResult.context.tddFailureCategory);
+      markStoryFailed(prd, ctx.story.id, pipelineResult.context.tddFailureCategory, pipelineResult.stoppedAtStage);
       await savePRD(prd, ctx.prdPath);
       prdDirty = true;
       logger?.error("pipeline", "Story failed", { storyId: ctx.story.id, reason: pipelineResult.reason });
@@ -34353,6 +34578,7 @@ var init_pipeline_result_handler = __esm(() => {
   init_logger2();
   init_event_bus();
   init_prd();
+  init_git();
   init_escalation();
   init_progress();
 });
@@ -35007,25 +35233,44 @@ var init_precheck_runner = __esm(() => {
 var exports_run_initialization = {};
 __export(exports_run_initialization, {
   logActiveProtocol: () => logActiveProtocol,
-  initializeRun: () => initializeRun
+  initializeRun: () => initializeRun,
+  _reconcileDeps: () => _reconcileDeps
 });
-async function reconcileState(prd, prdPath, workdir) {
+import { join as join51 } from "path";
+async function reconcileState(prd, prdPath, workdir, config2) {
   const logger = getSafeLogger();
   let reconciledCount = 0;
   let modified = false;
   for (const story of prd.userStories) {
-    if (story.status === "failed") {
-      const hasCommits = await hasCommitsForStory(workdir, story.id);
-      if (hasCommits) {
-        logger?.warn("reconciliation", "Failed story has commits in git history, marking as passed", {
-          storyId: story.id,
-          title: story.title
-        });
-        markStoryPassed(prd, story.id);
-        reconciledCount++;
-        modified = true;
+    if (story.status !== "failed")
+      continue;
+    const hasCommits = await _reconcileDeps.hasCommitsForStory(workdir, story.id);
+    if (!hasCommits)
+      continue;
+    if (story.failureStage === "review" || story.failureStage === "autofix") {
+      const effectiveWorkdir = story.workdir ? join51(workdir, story.workdir) : workdir;
+      try {
+        const reviewResult = await _reconcileDeps.runReview(config2.review, effectiveWorkdir, config2.execution);
+        if (!reviewResult.success) {
+          logger?.warn("reconciliation", "Review still fails \u2014 not reconciling story", {
+            storyId: story.id,
+            failureReason: reviewResult.failureReason
+          });
+          continue;
+        }
+        logger?.info("reconciliation", "Review now passes \u2014 reconciling story", { storyId: story.id });
+      } catch {
+        logger?.warn("reconciliation", "Review check errored \u2014 not reconciling story", { storyId: story.id });
+        continue;
       }
     }
+    logger?.warn("reconciliation", "Failed story has commits in git history, marking as passed", {
+      storyId: story.id,
+      title: story.title
+    });
+    markStoryPassed(prd, story.id);
+    reconciledCount++;
+    modified = true;
   }
   if (reconciledCount > 0) {
     logger?.info("reconciliation", `Reconciled ${reconciledCount} failed stories from git history`);
@@ -35075,7 +35320,7 @@ async function initializeRun(ctx) {
   const logger = getSafeLogger();
   await checkAgentInstalled(ctx.config, ctx.dryRun, ctx.agentGetFn);
   let prd = await loadPRD(ctx.prdPath);
-  prd = await reconcileState(prd, ctx.prdPath, ctx.workdir);
+  prd = await reconcileState(prd, ctx.prdPath, ctx.workdir, ctx.config);
   const counts = countStories(prd);
   validateStoryCount(counts, ctx.config);
   logger?.info("execution", "Run initialization complete", {
@@ -35085,11 +35330,17 @@ async function initializeRun(ctx) {
   });
   return { prd, storyCounts: counts };
 }
+var _reconcileDeps;
 var init_run_initialization = __esm(() => {
   init_errors3();
   init_logger2();
   init_prd();
+  init_runner2();
   init_git();
+  _reconcileDeps = {
+    hasCommitsForStory: (workdir, storyId) => hasCommitsForStory(workdir, storyId),
+    runReview: (reviewConfig, workdir, executionConfig) => runReview(reviewConfig, workdir, executionConfig)
+  };
 });
 
 // src/execution/lifecycle/run-setup.ts
@@ -66131,7 +66382,7 @@ var require_jsx_dev_runtime = __commonJS((exports, module) => {
 init_source();
 import { existsSync as existsSync34, mkdirSync as mkdirSync6 } from "fs";
 import { homedir as homedir10 } from "os";
-import { join as join51 } from "path";
+import { join as join52 } from "path";
 
 // node_modules/commander/esm.mjs
 var import__ = __toESM(require_commander(), 1);
@@ -67557,14 +67808,48 @@ For each user story, set the "workdir" field to the relevant package path (e.g.
       "workdir": "string \u2014 optional, relative path to package (e.g. \\"packages/api\\"). Omit for root-level stories.",` : "";
   return `You are a senior software architect generating a product requirements document (PRD) as JSON.
 
+## Step 1: Understand the Spec
+
+Read the spec carefully. Identify the goal, scope, constraints, and what "done" looks like.
+
 ## Spec
 
 ${specContent}
 
+## Step 2: Analyze
+
+Examine the codebase context below.
+
+If the codebase has existing code (refactoring, enhancement, bug fix):
+- Which existing files need modification?
+- Which files import from or depend on them?
+- What tests cover the affected code?
+- What are the risks (breaking changes, backward compatibility)?
+- What is the migration path?
+
+If this is a greenfield project (empty or minimal codebase):
+- What is the target architecture?
+- What are the key technical decisions (framework, patterns, conventions)?
+- What should be built first (dependency order)?
+
+Record ALL findings in the "analysis" field of the output JSON. This analysis is provided to every implementation agent as context \u2014 be thorough.
+
 ## Codebase Context
 
 ${codebaseContext}${monorepoHint}
 
+## Step 3: Generate Implementation Stories
+
+Based on your Step 2 analysis, create stories that produce CODE CHANGES.
+
+${GROUPING_RULES}
+
+For each story, set "contextFiles" to the key source files the agent should read before implementing (max 5 per story). Use your Step 2 analysis to identify the most relevant files. Leave empty for greenfield stories with no existing files to reference.
+
+${COMPLEXITY_GUIDE}
+
+${TEST_STRATEGY_GUIDE}
+
 ## Output Schema
 
 Generate a JSON object with this exact structure (no markdown, no explanation \u2014 JSON only):
@@ -67572,6 +67857,7 @@ Generate a JSON object with this exact structure (no markdown, no explanation \u
 {
   "project": "string \u2014 project name",
   "feature": "string \u2014 feature name",
+  "analysis": "string \u2014 your Step 2 analysis: key files, impact areas, risks, architecture decisions, migration notes. All implementation agents will receive this.",
   "branchName": "string \u2014 git branch (e.g. feat/my-feature)",
   "createdAt": "ISO 8601 timestamp",
   "updatedAt": "ISO 8601 timestamp",
@@ -67581,13 +67867,14 @@ Generate a JSON object with this exact structure (no markdown, no explanation \u
       "title": "string \u2014 concise story title",
       "description": "string \u2014 detailed description of the story",
       "acceptanceCriteria": ["string \u2014 each AC line"],
+      "contextFiles": ["string \u2014 key source files the agent should read (max 5, relative paths)"],
       "tags": ["string \u2014 routing tags, e.g. feature, security, api"],
       "dependencies": ["string \u2014 story IDs this story depends on"],${workdirField}
       "status": "pending",
       "passes": false,
       "routing": {
         "complexity": "simple | medium | complex | expert",
-        "testStrategy": "test-after | tdd-simple | three-session-tdd | three-session-tdd-lite",
+        "testStrategy": "tdd-simple | three-session-tdd-lite | three-session-tdd | test-after",
         "reasoning": "string \u2014 brief classification rationale"
       },
       "escalations": [],
@@ -67596,12 +67883,6 @@ Generate a JSON object with this exact structure (no markdown, no explanation \u
   ]
 }
 
-${COMPLEXITY_GUIDE}
-
-${TEST_STRATEGY_GUIDE}
-
-${GROUPING_RULES}
-
 ${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."}`;
 }
@@ -68243,6 +68524,45 @@ class PipelineEventEmitter {
 init_stages();
 init_prd();
 
+// src/cli/prompts-shared.ts
+function buildFrontmatter(story, ctx, role) {
+  const lines = [];
+  lines.push(`storyId: ${story.id}`);
+  lines.push(`title: "${story.title}"`);
+  lines.push(`testStrategy: ${ctx.routing.testStrategy}`);
+  lines.push(`modelTier: ${ctx.routing.modelTier}`);
+  if (role) {
+    lines.push(`role: ${role}`);
+  }
+  const builtContext = ctx.builtContext;
+  const contextTokens = builtContext?.totalTokens ?? 0;
+  const promptTokens = ctx.prompt ? Math.ceil(ctx.prompt.length / 3) : 0;
+  lines.push(`contextTokens: ${contextTokens}`);
+  lines.push(`promptTokens: ${promptTokens}`);
+  if (story.dependencies && story.dependencies.length > 0) {
+    lines.push(`dependencies: [${story.dependencies.join(", ")}]`);
+  }
+  lines.push("contextElements:");
+  if (builtContext) {
+    for (const element of builtContext.elements) {
+      lines.push(`  - type: ${element.type}`);
+      if (element.storyId) {
+        lines.push(`    storyId: ${element.storyId}`);
+      }
+      if (element.filePath) {
+        lines.push(`    filePath: ${element.filePath}`);
+      }
+      lines.push(`    tokens: ${element.tokens}`);
+    }
+  }
+  if (builtContext?.truncated) {
+    lines.push("truncated: true");
+  }
+  return `${lines.join(`
+`)}
+`;
+}
+
 // src/cli/prompts-tdd.ts
 init_prompts2();
 import { join as join28 } from "path";
@@ -68388,43 +68708,6 @@ ${"=".repeat(80)}`);
   });
   return processedStories;
 }
-function buildFrontmatter(story, ctx, role) {
-  const lines = [];
-  lines.push(`storyId: ${story.id}`);
-  lines.push(`title: "${story.title}"`);
-  lines.push(`testStrategy: ${ctx.routing.testStrategy}`);
-  lines.push(`modelTier: ${ctx.routing.modelTier}`);
-  if (role) {
-    lines.push(`role: ${role}`);
-  }
-  const builtContext = ctx.builtContext;
-  const contextTokens = builtContext?.totalTokens ?? 0;
-  const promptTokens = ctx.prompt ? Math.ceil(ctx.prompt.length / 3) : 0;
-  lines.push(`contextTokens: ${contextTokens}`);
-  lines.push(`promptTokens: ${promptTokens}`);
-  if (story.dependencies && story.dependencies.length > 0) {
-    lines.push(`dependencies: [${story.dependencies.join(", ")}]`);
-  }
-  lines.push("contextElements:");
-  if (builtContext) {
-    for (const element of builtContext.elements) {
-      lines.push(`  - type: ${element.type}`);
-      if (element.storyId) {
-        lines.push(`    storyId: ${element.storyId}`);
-      }
-      if (element.filePath) {
-        lines.push(`    filePath: ${element.filePath}`);
-      }
-      lines.push(`    tokens: ${element.tokens}`);
-    }
-  }
-  if (builtContext?.truncated) {
-    lines.push("truncated: true");
-  }
-  return `${lines.join(`
-`)}
-`;
-}
 // src/cli/prompts-init.ts
 import { existsSync as existsSync19, mkdirSync as mkdirSync4 } from "fs";
 import { join as join30 } from "path";
@@ -77916,15 +78199,15 @@ Next: nax generate --package ${options.package}`));
     }
     return;
   }
-  const naxDir = join51(workdir, "nax");
+  const naxDir = join52(workdir, "nax");
   if (existsSync34(naxDir) && !options.force) {
     console.log(source_default.yellow("nax already initialized. Use --force to overwrite."));
     return;
   }
-  mkdirSync6(join51(naxDir, "features"), { recursive: true });
-  mkdirSync6(join51(naxDir, "hooks"), { recursive: true });
-  await Bun.write(join51(naxDir, "config.json"), JSON.stringify(DEFAULT_CONFIG, null, 2));
-  await Bun.write(join51(naxDir, "hooks.json"), JSON.stringify({
+  mkdirSync6(join52(naxDir, "features"), { recursive: true });
+  mkdirSync6(join52(naxDir, "hooks"), { recursive: true });
+  await Bun.write(join52(naxDir, "config.json"), JSON.stringify(DEFAULT_CONFIG, null, 2));
+  await Bun.write(join52(naxDir, "hooks.json"), JSON.stringify({
     hooks: {
       "on-start": { command: 'echo "nax started: $NAX_FEATURE"', enabled: false },
       "on-complete": { command: 'echo "nax complete: $NAX_FEATURE"', enabled: false },
@@ -77932,12 +78215,12 @@ Next: nax generate --package ${options.package}`));
       "on-error": { command: 'echo "nax error: $NAX_REASON"', enabled: false }
     }
   }, null, 2));
-  await Bun.write(join51(naxDir, ".gitignore"), `# nax temp files
+  await Bun.write(join52(naxDir, ".gitignore"), `# nax temp files
 *.tmp
 .paused.json
 .nax-verifier-verdict.json
 `);
-  await Bun.write(join51(naxDir, "context.md"), `# Project Context
+  await Bun.write(join52(naxDir, "context.md"), `# Project Context
 
 This document defines coding standards, architectural decisions, and forbidden patterns for this project.
 Run \`nax generate\` to regenerate agent config files (CLAUDE.md, AGENTS.md, .cursorrules, etc.) from this file.
@@ -78063,8 +78346,8 @@ program2.command("run").description("Run the orchestration loop for a feature").
     console.error(source_default.red("nax not initialized. Run: nax init"));
     process.exit(1);
   }
-  const featureDir = join51(naxDir, "features", options.feature);
-  const prdPath = join51(featureDir, "prd.json");
+  const featureDir = join52(naxDir, "features", options.feature);
+  const prdPath = join52(featureDir, "prd.json");
   if (options.plan && options.from) {
     if (existsSync34(prdPath) && !options.force) {
       console.error(source_default.red(`Error: prd.json already exists for feature "${options.feature}".`));
@@ -78086,10 +78369,10 @@ program2.command("run").description("Run the orchestration loop for a feature").
       }
     }
     try {
-      const planLogDir = join51(featureDir, "plan");
+      const planLogDir = join52(featureDir, "plan");
       mkdirSync6(planLogDir, { recursive: true });
       const planLogId = new Date().toISOString().replace(/:/g, "-").replace(/\..+/, "");
-      const planLogPath = join51(planLogDir, `${planLogId}.jsonl`);
+      const planLogPath = join52(planLogDir, `${planLogId}.jsonl`);
       initLogger({ level: "info", filePath: planLogPath, useChalk: false, headless: true });
       console.log(source_default.dim(`   [Plan log: ${planLogPath}]`));
       console.log(source_default.dim("   [Planning phase: generating PRD from spec]"));
@@ -78127,10 +78410,10 @@ program2.command("run").description("Run the orchestration loop for a feature").
     process.exit(1);
   }
   resetLogger();
-  const runsDir = join51(featureDir, "runs");
+  const runsDir = join52(featureDir, "runs");
   mkdirSync6(runsDir, { recursive: true });
   const runId = new Date().toISOString().replace(/:/g, "-").replace(/\..+/, "");
-  const logFilePath = join51(runsDir, `${runId}.jsonl`);
+  const logFilePath = join52(runsDir, `${runId}.jsonl`);
   const isTTY = process.stdout.isTTY ?? false;
   const headlessFlag = options.headless ?? false;
   const headlessEnv = process.env.NAX_HEADLESS === "1";
@@ -78146,7 +78429,7 @@ program2.command("run").description("Run the orchestration loop for a feature").
     config2.autoMode.defaultAgent = options.agent;
   }
   config2.execution.maxIterations = Number.parseInt(options.maxIterations, 10);
-  const globalNaxDir = join51(homedir10(), ".nax");
+  const globalNaxDir = join52(homedir10(), ".nax");
   const hooks = await loadHooksConfig(naxDir, globalNaxDir);
   const eventEmitter = new PipelineEventEmitter;
   let tuiInstance;
@@ -78169,7 +78452,7 @@ program2.command("run").description("Run the orchestration loop for a feature").
   } else {
     console.log(source_default.dim("   [Headless mode \u2014 pipe output]"));
   }
-  const statusFilePath = join51(workdir, "nax", "status.json");
+  const statusFilePath = join52(workdir, "nax", "status.json");
   let parallel;
   if (options.parallel !== undefined) {
     parallel = Number.parseInt(options.parallel, 10);
@@ -78195,7 +78478,7 @@ program2.command("run").description("Run the orchestration loop for a feature").
     headless: useHeadless,
     skipPrecheck: options.skipPrecheck ?? false
   });
-  const latestSymlink = join51(runsDir, "latest.jsonl");
+  const latestSymlink = join52(runsDir, "latest.jsonl");
   try {
     if (existsSync34(latestSymlink)) {
       Bun.spawnSync(["rm", latestSymlink]);
@@ -78233,9 +78516,9 @@ features.command("create <name>").description("Create a new feature").option("-d
     console.error(source_default.red("nax not initialized. Run: nax init"));
     process.exit(1);
   }
-  const featureDir = join51(naxDir, "features", name);
+  const featureDir = join52(naxDir, "features", name);
   mkdirSync6(featureDir, { recursive: true });
-  await Bun.write(join51(featureDir, "spec.md"), `# Feature: ${name}
+  await Bun.write(join52(featureDir, "spec.md"), `# Feature: ${name}
 
 ## Overview
 
@@ -78243,7 +78526,7 @@ features.command("create <name>").description("Create a new feature").option("-d
 
 ## Acceptance Criteria
 `);
-  await Bun.write(join51(featureDir, "plan.md"), `# Plan: ${name}
+  await Bun.write(join52(featureDir, "plan.md"), `# Plan: ${name}
 
 ## Architecture
 
@@ -78251,7 +78534,7 @@ features.command("create <name>").description("Create a new feature").option("-d
 
 ## Dependencies
 `);
-  await Bun.write(join51(featureDir, "tasks.md"), `# Tasks: ${name}
+  await Bun.write(join52(featureDir, "tasks.md"), `# Tasks: ${name}
 
 ## US-001: [Title]
 
@@ -78260,7 +78543,7 @@ features.command("create <name>").description("Create a new feature").option("-d
 ### Acceptance Criteria
 - [ ] Criterion 1
 `);
-  await Bun.write(join51(featureDir, "progress.txt"), `# Progress: ${name}
+  await Bun.write(join52(featureDir, "progress.txt"), `# Progress: ${name}
 
 Created: ${new Date().toISOString()}
 
@@ -78288,7 +78571,7 @@ features.command("list").description("List all features").option("-d, --dir <pat
     console.error(source_default.red("nax not initialized."));
     process.exit(1);
   }
-  const featuresDir = join51(naxDir, "features");
+  const featuresDir = join52(naxDir, "features");
   if (!existsSync34(featuresDir)) {
     console.log(source_default.dim("No features yet."));
     return;
@@ -78303,7 +78586,7 @@ features.command("list").description("List all features").option("-d, --dir <pat
 Features:
 `));
   for (const name of entries) {
-    const prdPath = join51(featuresDir, name, "prd.json");
+    const prdPath = join52(featuresDir, name, "prd.json");
     if (existsSync34(prdPath)) {
       const prd = await loadPRD(prdPath);
       const c = countStories(prd);
@@ -78334,10 +78617,10 @@ Use: nax plan -f <feature> --from <spec>`));
     process.exit(1);
   }
   const config2 = await loadConfig(workdir);
-  const featureLogDir = join51(naxDir, "features", options.feature, "plan");
+  const featureLogDir = join52(naxDir, "features", options.feature, "plan");
   mkdirSync6(featureLogDir, { recursive: true });
   const planLogId = new Date().toISOString().replace(/:/g, "-").replace(/\..+/, "");
-  const planLogPath = join51(featureLogDir, `${planLogId}.jsonl`);
+  const planLogPath = join52(featureLogDir, `${planLogId}.jsonl`);
   initLogger({ level: "info", filePath: planLogPath, useChalk: false, headless: true });
   console.log(source_default.dim(`   [Plan log: ${planLogPath}]`));
   try {
@@ -78374,7 +78657,7 @@ program2.command("analyze").description("(deprecated) Parse spec.md into prd.jso
     console.error(source_default.red("nax not initialized. Run: nax init"));
     process.exit(1);
   }
-  const featureDir = join51(naxDir, "features", options.feature);
+  const featureDir = join52(naxDir, "features", options.feature);
   if (!existsSync34(featureDir)) {
     console.error(source_default.red(`Feature "${options.feature}" not found.`));
     process.exit(1);
@@ -78390,7 +78673,7 @@ program2.command("analyze").description("(deprecated) Parse spec.md into prd.jso
       specPath: options.from,
       reclassify: options.reclassify
     });
-    const prdPath = join51(featureDir, "prd.json");
+    const prdPath = join52(featureDir, "prd.json");
     await Bun.write(prdPath, JSON.stringify(prd, null, 2));
     const c = countStories(prd);
     console.log(source_default.green(`