@nathapp/nax 0.49.6 → 0.50.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.49.6",
+  "version": "0.50.1",
   "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
     "build": "bun build bin/nax.ts --outdir dist --target bun --define \"GIT_COMMIT=\\\"$(git rev-parse --short HEAD)\\\"\"",
     "typecheck": "bun x tsc --noEmit",
     "lint": "bun x biome check src/ bin/",
+    "release": "bun scripts/release.ts",
     "test": "CI=1 NAX_SKIP_PRECHECK=1 bun test test/ --timeout=60000",
     "test:watch": "CI=1 bun test --watch",
     "test:unit": "CI=1 NAX_SKIP_PRECHECK=1 bun test ./test/unit/ --timeout=60000",

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/config-descriptions.ts

@@ -209,4 +209,10 @@ export const FIELD_DESCRIPTIONS: Record<string, string> = {
   "agent.protocol": "Protocol for agent communication: 'acp' | 'cli' (default: 'acp')",
   "agent.maxInteractionTurns":
     "Max turns in multi-turn interaction loop when interactionBridge is active (default: 10)",
+  // Testing
+  testing: "Hermetic test enforcement configuration (ENH-010)",
+  "testing.hermetic":
+    "Inject hermetic test requirement into prompts — never call real external services in tests (default: true)",
+  "testing.externalBoundaries": "Project-specific CLI tools/clients to mock (e.g. ['claude', 'acpx', 'redis'])",
+  "testing.mockGuidance": "Project-specific mocking guidance injected verbatim into the prompt",
 };

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/defaults.ts

@@ -211,4 +211,7 @@ export const DEFAULT_CONFIG: NaxConfig = {
     maxRetries: 2,
     model: "balanced",
   },
+  testing: {
+    hermetic: true,
+  },
 };

package/src/config/runtime-types.ts

@@ -430,6 +430,25 @@ export interface DecomposeConfig {
   model: ModelTier;
 }
 
+/** Hermetic test enforcement configuration (ENH-010) */
+export interface TestingConfig {
+  /**
+   * When true (default), nax injects a hermetic test requirement into all code-writing prompts.
+   * Instructs the AI to mock all I/O boundaries and never call real external services in tests.
+   */
+  hermetic: boolean;
+  /**
+   * Project-specific external boundaries to mock (e.g. ["claude", "acpx", "redis", "grpc"]).
+   * Injected into the hermetic requirement section so the AI knows which project tools to mock.
+   */
+  externalBoundaries?: string[];
+  /**
+   * Project-specific mocking guidance injected verbatim into the prompt.
+   * E.g. "Use injectable deps for CLI spawning, ioredis-mock for Redis"
+   */
+  mockGuidance?: string;
+}
+
 /** Full nax configuration */
 export interface NaxConfig {
   /** Schema version */
@@ -476,6 +495,8 @@ export interface NaxConfig {
   decompose?: DecomposeConfig;
   /** Agent protocol settings (ACP-003) */
   agent?: AgentConfig;
+  /** Hermetic test enforcement settings (ENH-010) */
+  testing?: TestingConfig;
   /** Generate settings */
   generate?: GenerateConfig;
 }

package/src/config/schemas.ts

@@ -362,6 +362,28 @@ export const PromptsConfigSchema = z.object({
     .optional(),
 });
 
+const TestingConfigSchema = z.object({
+  /**
+   * When true (default), nax injects a hermetic test requirement into all code-writing prompts.
+   * Instructs the AI to mock all I/O boundaries (HTTP, CLI spawning, databases, etc.)
+   * and never invoke real external processes or services during test execution.
+   * Set to false only if your project requires real integration calls in tests.
+   */
+  hermetic: z.boolean().default(true),
+  /**
+   * Project-specific external boundaries the AI should watch for and mock.
+   * E.g. ["claude", "acpx", "redis", "grpc"] — any CLI tools, clients, or services
+   * the project uses that should never be called from tests.
+   */
+  externalBoundaries: z.array(z.string()).optional(),
+  /**
+   * Project-specific guidance on how to mock external dependencies.
+   * Injected verbatim into the hermetic requirement section of the prompt.
+   * E.g. "Use injectable deps for CLI spawning, ioredis-mock for Redis"
+   */
+  mockGuidance: z.string().optional(),
+});
+
 const DecomposeConfigSchema = z.object({
   trigger: z.enum(["auto", "confirm", "disabled"]).default("auto"),
   maxAcceptanceCriteria: z.number().int().min(1).default(6),
@@ -395,6 +417,7 @@ export const NaxConfigSchema = z
     precheck: PrecheckConfigSchema.optional(),
     prompts: PromptsConfigSchema.optional(),
     decompose: DecomposeConfigSchema.optional(),
+    testing: TestingConfigSchema.optional(),
   })
   .refine((data) => data.version === 1, {
     message: "Invalid version: expected 1",

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/config/types.ts

@@ -51,6 +51,7 @@ export type {
   StorySizeGateConfig,
   TddConfig,
   TestCoverageConfig,
+  TestingConfig,
   AdaptiveRoutingConfig,
   AgentConfig,
 } from "./runtime-types";

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,23 +21,29 @@ 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
-  const newStories = subStories.map((sub): UserStory & { parentStoryId: string } => ({
-    id: sub.id,
-    title: sub.title,
-    description: sub.description,
-    acceptanceCriteria: sub.acceptanceCriteria,
-    tags: sub.tags,
-    dependencies: sub.dependencies,
-    status: "pending",
-    passes: false,
-    escalations: [],
-    attempts: 0,
-    parentStoryId: sub.parentStoryId,
-  }));
+  // ENH-008: Inherit workdir from parent so sub-stories run in the same package scope
+  const newStories = subStories.map(
+    (sub): UserStory => ({
+      id: sub.id,
+      title: sub.title,
+      description: sub.description,
+      acceptanceCriteria: sub.acceptanceCriteria,
+      tags: sub.tags,
+      dependencies: sub.dependencies,
+      status: "pending",
+      passes: false,
+      escalations: [],
+      attempts: 0,
+      parentStoryId: sub.parentStoryId,
+      ...(parentStory.workdir !== undefined && { workdir: parentStory.workdir }),
+    }),
+  );
 
   // Insert substories immediately after the original story
   prd.userStories.splice(originalIndex + 1, 0, ...newStories);

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/iteration-runner.ts

@@ -27,6 +27,8 @@ export interface IterationResult {
   prdDirty: boolean;
   finalAction?: string;
   reason?: string;
+  /** Set when finalAction === "decomposed" — number of sub-stories created */
+  subStoryCount?: number;
 }
 
 export async function runIteration(
@@ -146,6 +148,7 @@ export async function runIteration(
     prdDirty: r.prdDirty,
     finalAction: pipelineResult.finalAction,
     reason: pipelineResult.reason,
+    subStoryCount: pipelineResult.subStoryCount,
   };
 }
 

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

@@ -15,6 +15,7 @@ import { getSafeLogger } from "../../logger";
 import type { StoryMetrics } from "../../metrics";
 import { saveRunMetrics } from "../../metrics";
 import { pipelineEventBus } from "../../pipeline/event-bus";
+import type { AgentGetFn } from "../../pipeline/types";
 import { countStories, isComplete, isStalled } from "../../prd";
 import type { PRD } from "../../prd";
 import type { StatusWriter } from "../status-writer";
@@ -45,6 +46,8 @@ export interface RunCompletionOptions {
   hooksConfig?: HooksConfig;
   /** Whether the run used sequential (non-parallel) execution. Defaults to true. */
   isSequential?: boolean;
+  /** Protocol-aware agent resolver (ACP wiring). Falls back to static getAgent when absent. */
+  agentGetFn?: AgentGetFn;
 }
 
 export interface RunCompletionResult {
@@ -120,6 +123,7 @@ export async function handleRunCompletion(options: RunCompletionOptions): Promis
         config,
         prd,
         workdir,
+        agentGetFn: options.agentGetFn,
       });
 
       logger?.info("regression", "Deferred regression gate completed", {