@nathapp/nax 0.49.6 → 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 = [
@@ -18744,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,
@@ -18870,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
@@ -18883,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) => {
@@ -20363,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,
@@ -20375,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);
 }
@@ -22255,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";
@@ -22263,6 +22301,9 @@ function markStoryFailed(prd, storyId, failureCategory) {
     if (failureCategory !== undefined) {
       story.failureCategory = failureCategory;
     }
+    if (failureStage !== undefined) {
+      story.failureStage = failureStage;
+    }
   }
 }
 function markStorySkipped(prd, storyId) {
@@ -22289,7 +22330,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@nathapp/nax",
-    version: "0.49.6",
+    version: "0.50.0",
     description: "AI Coding Agent Orchestrator \u2014 loops until done",
     type: "module",
     bin: {
@@ -22362,8 +22403,8 @@ var init_version = __esm(() => {
   NAX_VERSION = package_default.version;
   NAX_COMMIT = (() => {
     try {
-      if (/^[0-9a-f]{6,10}$/.test("a1f7e2d"))
-        return "a1f7e2d";
+      if (/^[0-9a-f]{6,10}$/.test("0eeefb4"))
+        return "0eeefb4";
     } catch {}
     try {
       const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
@@ -24755,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})
@@ -24765,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();
@@ -24792,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,
@@ -25348,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;
@@ -25695,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);
@@ -25755,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 {
@@ -25822,6 +25914,7 @@ var init_builder3 = __esm(() => {
   init_prd();
   init_auto_detect();
   init_elements();
+  init_parent_context();
   init_test_scanner();
   init_elements();
   _deps5 = {
@@ -26291,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();
@@ -33141,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)
@@ -33169,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 || [],
@@ -33187,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
@@ -34124,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
@@ -34164,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,
@@ -34329,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;
@@ -34357,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,
@@ -34393,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 });
@@ -34447,6 +34578,7 @@ var init_pipeline_result_handler = __esm(() => {
   init_logger2();
   init_event_bus();
   init_prd();
+  init_git();
   init_escalation();
   init_progress();
 });
@@ -35101,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`);
@@ -35169,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", {
@@ -35179,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
@@ -66225,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);
@@ -67651,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):
@@ -67666,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",
@@ -67675,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": [],
@@ -67690,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."}`;
 }
@@ -78012,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 },
@@ -78028,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.
@@ -78159,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}".`));
@@ -78182,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]"));
@@ -78223,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";
@@ -78242,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;
@@ -78265,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);
@@ -78291,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]);
@@ -78329,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
 
@@ -78339,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
 
@@ -78347,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]
 
@@ -78356,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()}
 
@@ -78384,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;
@@ -78399,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);
@@ -78430,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 {
@@ -78470,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);
@@ -78486,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(`