@nathapp/nax 0.49.6 → 0.50.0

package/package.json

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

package/src/acceptance/generator.ts

@@ -114,6 +114,18 @@ IMPORTANT: Output raw TypeScript code only. Do NOT use markdown code fences (\`\
   });
   const testCode = extractTestCode(rawOutput);
 
+  if (!testCode) {
+    logger.warn("acceptance", "LLM returned non-code output for acceptance tests — falling back to skeleton", {
+      outputPreview: rawOutput.slice(0, 200),
+    });
+    const skeletonCriteria: AcceptanceCriterion[] = 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}`,
@@ -306,6 +318,16 @@ export async function generateAcceptanceTests(
     // Extract test code from output
     const testCode = extractTestCode(output);
 
+    if (!testCode) {
+      logger.warn("acceptance", "LLM returned non-code output for acceptance tests — falling back to skeleton", {
+        outputPreview: output.slice(0, 200),
+      });
+      return {
+        testCode: generateSkeletonTests(options.featureName, criteria),
+        criteria,
+      };
+    }
+
     return {
       testCode,
       criteria,
@@ -328,21 +350,40 @@ export async function generateAcceptanceTests(
  * @param output - Agent stdout
  * @returns Extracted test code
  */
-function extractTestCode(output: string): string {
+function extractTestCode(output: string): string | null {
+  let code: string | undefined;
+
   // Try to extract from markdown code fence
   const fenceMatch = output.match(/```(?:typescript|ts)?\s*([\s\S]*?)\s*```/);
   if (fenceMatch) {
-    return fenceMatch[1].trim();
+    code = fenceMatch[1].trim();
   }
 
   // If no fence, try to find import statement and take everything from there
-  const importMatch = output.match(/import\s+{[\s\S]+/);
-  if (importMatch) {
-    return importMatch[0].trim();
+  if (!code) {
+    const importMatch = output.match(/import\s+{[\s\S]+/);
+    if (importMatch) {
+      code = importMatch[0].trim();
+    }
+  }
+
+  // If no fence and no import, try to find describe() block
+  if (!code) {
+    const describeMatch = output.match(/describe\s*\([\s\S]+/);
+    if (describeMatch) {
+      code = describeMatch[0].trim();
+    }
+  }
+
+  if (!code) return null;
+
+  // Validate: extracted code must contain at least one test-like keyword
+  const hasTestKeyword = /\b(?:describe|test|it|expect)\s*\(/.test(code);
+  if (!hasTestKeyword) {
+    return null;
   }
 
-  // Fall back to full output
-  return output.trim();
+  return code;
 }
 
 /**

package/src/cli/plan.ts

@@ -395,15 +395,18 @@ function buildCodebaseContext(scan: CodebaseScan): string {
 /**
  * Build the full planning prompt sent to the LLM.
  *
+ * Structured as 3 explicit steps (ENH-006):
+ *   Step 1: Understand the spec
+ *   Step 2: Analyze codebase (existing) or architecture decisions (greenfield)
+ *   Step 3: Generate implementation stories from analysis
+ *
  * Includes:
- * - Spec content
- * - Codebase context
- * - Output schema (exact prd.json JSON structure)
- * - Complexity classification guide
- * - Test strategy guide
+ * - Spec content + codebase context
+ * - Output schema with analysis + contextFiles fields
+ * - Complexity + test strategy guides
  * - MW-007: Monorepo hint and package list when packages are detected
  */
-function buildPlanningPrompt(
+export function buildPlanningPrompt(
   specContent: string,
   codebaseContext: string,
   outputFilePath?: string,
@@ -423,14 +426,48 @@ function buildPlanningPrompt(
 
   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 — 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 — JSON only):
@@ -438,6 +475,7 @@ Generate a JSON object with this exact structure (no markdown, no explanation
 {
   "project": "string — project name",
   "feature": "string — feature name",
+  "analysis": "string — your Step 2 analysis: key files, impact areas, risks, architecture decisions, migration notes. All implementation agents will receive this.",
   "branchName": "string — git branch (e.g. feat/my-feature)",
   "createdAt": "ISO 8601 timestamp",
   "updatedAt": "ISO 8601 timestamp",
@@ -447,13 +485,14 @@ Generate a JSON object with this exact structure (no markdown, no explanation
       "title": "string — concise story title",
       "description": "string — detailed description of the story",
       "acceptanceCriteria": ["string — each AC line"],
+      "contextFiles": ["string — key source files the agent should read (max 5, relative paths)"],
       "tags": ["string — routing tags, e.g. feature, security, api"],
       "dependencies": ["string — 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 — brief classification rationale"
       },
       "escalations": [],
@@ -462,12 +501,6 @@ Generate a JSON object with this exact structure (no markdown, no explanation
   ]
 }
 
-${COMPLEXITY_GUIDE}
-
-${TEST_STRATEGY_GUIDE}
-
-${GROUPING_RULES}
-
 ${
   outputFilePath
     ? `Write the PRD JSON directly to this file path: ${outputFilePath}\nDo NOT output the JSON to the conversation. Write the file, then reply with a brief confirmation.`

package/src/config/test-strategy.ts

@@ -40,31 +40,32 @@ export function resolveTestStrategy(raw: string | undefined): TestStrategy {
 
 export const COMPLEXITY_GUIDE = `## Complexity Classification Guide
 
-- simple: ≤50 LOC, single-file change, purely additive, no new dependencies → test-after
-- medium: 50–200 LOC, 2–5 files, standard patterns, clear requirements → tdd-simple
+- simple: ≤50 LOC, single-file change, purely additive, no new dependencies → tdd-simple
+- medium: 50–200 LOC, 2–5 files, standard patterns, clear requirements → three-session-tdd-lite
 - complex: 200–500 LOC, multiple modules, new abstractions or integrations → three-session-tdd
-- expert: 500+ LOC, architectural changes, cross-cutting concerns, high risk → three-session-tdd-lite
+- expert: 500+ LOC, architectural changes, cross-cutting concerns, high risk → 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.`;
+password hashing, access control) must use three-session-tdd regardless of complexity.`;
 
 export const 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 — all in one session.
-- three-session-tdd: Complex stories. 3 sessions: (1) test-writer writes failing tests — 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.`;
+- tdd-simple: Simple stories (≤50 LOC). Write failing tests first, then implement to pass them — 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 — 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.`;
 
-export const GROUPING_RULES = `## Grouping Rules
+export const 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.`;

package/src/context/builder.ts

@@ -21,6 +21,7 @@ import {
   createStoryContext,
   createTestCoverageContext,
 } from "./elements";
+import { getParentOutputFiles } from "./parent-context";
 import { generateTestCoverageSummary } from "./test-scanner";
 import type { BuiltContext, ContextBudget, ContextElement, StoryContext } from "./types";
 
@@ -115,6 +116,18 @@ export async function buildContext(storyContext: StoryContext, budget: ContextBu
   // Add current story (high priority)
   elements.push(createStoryContext(currentStory, 80));
 
+  // ENH-006: Inject planning analysis from prd.analysis (priority 88 — above story, below errors)
+  if (prd.analysis) {
+    const analysisContent = `The following analysis was performed during the planning phase. Use it to understand the codebase context before implementing:\n\n${prd.analysis}`;
+    elements.push({
+      type: "planning-analysis",
+      label: "Planning Analysis",
+      content: analysisContent,
+      priority: 88,
+      tokens: estimateTokens(analysisContent),
+    });
+  }
+
   // Add dependency stories (medium priority)
   addDependencyElements(elements, currentStory, prd);
 
@@ -199,6 +212,18 @@ async function addFileElements(
 
   let contextFiles = getContextFiles(story);
 
+  // ENH-005: Inject parent output files for context chaining
+  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,
+    });
+    // Merge with existing contextFiles (don't replace — parent files are supplementary)
+    contextFiles = [...new Set([...contextFiles, ...parentFiles])];
+  }
+
   // Auto-detect contextFiles if empty and enabled (BUG-006)
   if (
     contextFiles.length === 0 &&

package/src/context/parent-context.ts

@@ -0,0 +1,39 @@
+/**
+ * Parent output file resolution for context chaining (ENH-005).
+ *
+ * When a story has dependencies, its parent stories' outputFiles are injected
+ * as additional contextFiles so agents have targeted context from prior work.
+ */
+
+import type { UserStory } from "../prd/types";
+
+const MAX_PARENT_FILES = 10;
+
+const NOISE_PATTERNS = [
+  /\.test\.(ts|js|tsx|jsx)$/,
+  /\.spec\.(ts|js|tsx|jsx)$/,
+  /package-lock\.json$/,
+  /bun\.lockb?$/,
+  /\.gitignore$/,
+  /^nax\//,
+];
+
+/**
+ * Get output files from direct parent stories (dependencies[]).
+ * Only direct parents — no transitive resolution (keep simple, extend later).
+ * Returns deduped list, filtered of noise, capped at MAX_PARENT_FILES.
+ */
+export function getParentOutputFiles(story: UserStory, allStories: UserStory[]): string[] {
+  if (!story.dependencies || story.dependencies.length === 0) return [];
+
+  const parentFiles: string[] = [];
+  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);
+}

package/src/decompose/apply.ts

@@ -21,10 +21,13 @@ export function applyDecomposition(prd: PRD, result: DecomposeResult): void {
   const originalIndex = prd.userStories.findIndex((s) => s.id === parentStoryId);
   if (originalIndex === -1) return;
 
+  const parentStory = prd.userStories[originalIndex];
+
   // Mark original story as decomposed
-  prd.userStories[originalIndex].status = "decomposed";
+  parentStory.status = "decomposed";
 
   // Convert substories to UserStory format with parentStoryId attached
+  // ENH-008: Inherit workdir from parent so sub-stories run in the same package scope
   const newStories = subStories.map((sub): UserStory & { parentStoryId: string } => ({
     id: sub.id,
     title: sub.title,
@@ -37,6 +40,7 @@ export function applyDecomposition(prd: PRD, result: DecomposeResult): void {
     escalations: [],
     attempts: 0,
     parentStoryId: sub.parentStoryId,
+    ...(parentStory.workdir !== undefined && { workdir: parentStory.workdir }),
   }));
 
   // Insert substories immediately after the original story

package/src/execution/escalation/tier-escalation.ts

@@ -150,7 +150,7 @@ export async function preIterationTierCheck(
   });
 
   const failedPrd = { ...prd };
-  markStoryFailed(failedPrd, story.id);
+  markStoryFailed(failedPrd, story.id, undefined, undefined);
   await savePRD(failedPrd, prdPath);
 
   if (featureDir) {

package/src/execution/escalation/tier-outcome.ts

@@ -56,7 +56,7 @@ export async function handleNoTierAvailable(
 
   // Outcome is "fail"
   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", {
@@ -119,7 +119,7 @@ export async function handleMaxAttemptsReached(
 
   // Outcome is "fail"
   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", {

package/src/execution/lifecycle/run-initialization.ts

@@ -8,6 +8,7 @@
  * 4. Initial PRD analysis
  */
 
+import { join } from "node:path";
 import chalk from "chalk";
 import type { NaxConfig } from "../../config";
 import { AgentNotFoundError, AgentNotInstalledError, StoryLimitExceededError } from "../../errors";
@@ -15,8 +16,20 @@ import { getSafeLogger } from "../../logger";
 import type { AgentGetFn } from "../../pipeline/types";
 import { countStories, loadPRD, markStoryPassed, savePRD } from "../../prd";
 import type { PRD } from "../../prd/types";
+import { runReview } from "../../review/runner";
+import type { ReviewConfig } from "../../review/types";
 import { hasCommitsForStory } from "../../utils/git";
 
+/**
+ * Injectable dependencies for reconcileState — allows tests to mock
+ * hasCommitsForStory and runReview without mock.module().
+ */
+export const _reconcileDeps = {
+  hasCommitsForStory: (workdir: string, storyId: string) => hasCommitsForStory(workdir, storyId),
+  runReview: (reviewConfig: ReviewConfig, workdir: string, executionConfig: NaxConfig["execution"]) =>
+    runReview(reviewConfig, workdir, executionConfig),
+};
+
 export interface InitializationContext {
   config: NaxConfig;
   prdPath: string;
@@ -43,26 +56,47 @@ export interface InitializationResult {
  * Reconcile PRD state with git history
  *
  * Checks if failed stories have commits in git history and marks them as passed.
- * This handles the case where TDD failed but agent already committed code.
+ * For stories that failed at review/autofix stage, re-runs the review before
+ * reconciling to ensure the code quality issues were actually fixed.
  */
-async function reconcileState(prd: PRD, prdPath: string, workdir: string): Promise<PRD> {
+async function reconcileState(prd: PRD, prdPath: string, workdir: string, config: NaxConfig): Promise<PRD> {
   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;
+
+    // Gate: re-run review for stories that failed at review/autofix stage
+    if (story.failureStage === "review" || story.failureStage === "autofix") {
+      const effectiveWorkdir = story.workdir ? join(workdir, story.workdir) : workdir;
+      try {
+        const reviewResult = await _reconcileDeps.runReview(config.review, effectiveWorkdir, config.execution);
+        if (!reviewResult.success) {
+          logger?.warn("reconciliation", "Review still fails — not reconciling story", {
+            storyId: story.id,
+            failureReason: reviewResult.failureReason,
+          });
+          continue;
+        }
+        logger?.info("reconciliation", "Review now passes — reconciling story", { storyId: story.id });
+      } catch {
+        // Non-fatal: if review check errors, skip reconciliation for this story
+        logger?.warn("reconciliation", "Review check errored — 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) {
@@ -137,7 +171,7 @@ export async function initializeRun(ctx: InitializationContext): Promise<Initial
 
   // Load and reconcile PRD
   let prd = await loadPRD(ctx.prdPath);
-  prd = await reconcileState(prd, ctx.prdPath, ctx.workdir);
+  prd = await reconcileState(prd, ctx.prdPath, ctx.workdir, ctx.config);
 
   // Validate story counts
   const counts = countStories(prd);

package/src/execution/parallel-coordinator.ts

@@ -171,7 +171,7 @@ export async function executeParallel(
           worktreePath,
         });
       } catch (error) {
-        markStoryFailed(currentPrd, story.id);
+        markStoryFailed(currentPrd, story.id, undefined, undefined);
         logger?.error("parallel", "Failed to create worktree", {
           storyId: story.id,
           error: errorMessage(error),
@@ -218,7 +218,7 @@ export async function executeParallel(
           });
         } else {
           // Merge conflict — mark story as failed
-          markStoryFailed(currentPrd, mergeResult.storyId);
+          markStoryFailed(currentPrd, mergeResult.storyId, undefined, undefined);
           batchResult.mergeConflicts.push({
             storyId: mergeResult.storyId,
             conflictFiles: mergeResult.conflictFiles || [],
@@ -241,7 +241,7 @@ export async function executeParallel(
 
     // Mark failed stories in PRD and clean up their worktrees
     for (const { story, error } of batchResult.failed) {
-      markStoryFailed(currentPrd, story.id);
+      markStoryFailed(currentPrd, story.id, undefined, undefined);
 
       logger?.error("parallel", "Cleaning up failed story worktree", {
         storyId: story.id,

package/src/execution/pipeline-result-handler.ts

@@ -17,9 +17,23 @@ import type { PluginRegistry } from "../plugins";
 import { countStories, markStoryFailed, markStoryPaused, savePRD } from "../prd";
 import type { PRD, UserStory } from "../prd/types";
 import type { routeTask } from "../routing";
+import { captureOutputFiles } from "../utils/git";
 import { handleTierEscalation } from "./escalation";
 import { appendProgress } from "./progress";
 
+/** Filter noise from output files (test files, lock files, nax runtime files) */
+function filterOutputFiles(files: string[]): string[] {
+  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);
+}
+
 export interface PipelineHandlerContext {
   config: NaxConfig;
   prd: PRD;
@@ -84,6 +98,21 @@ export async function handlePipelineSuccess(
     });
   }
 
+  // ENH-005: Capture output files for context chaining
+  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 {
+        // Non-fatal — context chaining is best-effort
+      }
+    }
+  }
+
   const updatedCounts = countStories(prd);
   logger?.info("progress", "Progress update", {
     totalStories: updatedCounts.total,
@@ -135,7 +164,7 @@ export async function handlePipelineFailure(
       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 });

package/src/pipeline/stages/autofix.ts

@@ -166,6 +166,11 @@ export function buildReviewRectificationPrompt(failedChecks: ReviewCheckResult[]
     .map((c) => `## ${c.check} errors (exit code ${c.exitCode})\n\`\`\`\n${c.output}\n\`\`\``)
     .join("\n\n");
 
+  // ENH-008: Scope constraint for monorepo stories — prevent out-of-package changes
+  const scopeConstraint = story.workdir
+    ? `\n\nIMPORTANT: 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})
@@ -176,7 +181,7 @@ ${errors}
 
 Fix ALL errors listed above. Do NOT change test files or test behavior.
 Do NOT add new features — only fix the quality check errors.
-Commit your fixes when done.`;
+Commit your fixes when done.${scopeConstraint}`;
 }
 
 async function runAgentRectification(ctx: PipelineContext): Promise<boolean> {
@@ -211,9 +216,12 @@ async function runAgentRectification(ctx: PipelineContext): Promise<boolean> {
     const modelTier = ctx.story.routing?.modelTier ?? ctx.config.autoMode.escalation.tierOrder[0]?.tier ?? "balanced";
     const modelDef = resolveModel(ctx.config.models[modelTier]);
 
+    // ENH-008: Scope agent to story.workdir for monorepo — prevents out-of-package changes
+    const rectificationWorkdir = ctx.story.workdir ? join(ctx.workdir, ctx.story.workdir) : ctx.workdir;
+
     await agent.run({
       prompt,
-      workdir: ctx.workdir,
+      workdir: rectificationWorkdir,
       modelTier,
       modelDef,
       timeoutSeconds: ctx.config.execution.sessionTimeoutSeconds,

package/src/prd/index.ts

@@ -168,7 +168,12 @@ export function markStoryPassed(prd: PRD, storyId: string): void {
 }
 
 /** Mark a story as failed */
-export function markStoryFailed(prd: PRD, storyId: string, failureCategory?: FailureCategory): void {
+export function markStoryFailed(
+  prd: PRD,
+  storyId: string,
+  failureCategory?: FailureCategory,
+  failureStage?: string,
+): void {
   const story = prd.userStories.find((s) => s.id === storyId);
   if (story) {
     story.status = "failed";
@@ -176,6 +181,9 @@ export function markStoryFailed(prd: PRD, storyId: string, failureCategory?: Fai
     if (failureCategory !== undefined) {
       story.failureCategory = failureCategory;
     }
+    if (failureStage !== undefined) {
+      story.failureStage = failureStage;
+    }
   }
 }
 

package/src/prd/types.ts

@@ -125,6 +125,8 @@ export interface UserStory {
   customContext?: string[];
   /** Category of the last failure (set when story is marked failed) */
   failureCategory?: FailureCategory;
+  /** Pipeline stage where this story last failed (set by markStoryFailed) */
+  failureStage?: string;
   /** Worktree path for parallel execution (set when --parallel is used) */
   worktreePath?: string;
   /**
@@ -133,6 +135,8 @@ export interface UserStory {
    * @example "packages/api"
    */
   workdir?: string;
+  /** Files created/modified by this story (auto-captured after completion, used by dependent stories) */
+  outputFiles?: string[];
 }
 
 // ============================================================================
@@ -236,6 +240,8 @@ export interface PRD {
   project: string;
   /** Feature name */
   feature: string;
+  /** Codebase analysis from planning phase — injected into all story contexts (ENH-006) */
+  analysis?: string;
   /** Git branch name */
   branchName: string;
   /** Creation timestamp */