@nathapp/nax 0.44.0 → 0.46.0

package/src/agents/{version-detection.ts → shared/version-detection.ts}

@@ -5,8 +5,8 @@
  * by running `<agent> --version` and parsing the output.
  */
 
-import { getInstalledAgents } from "./registry";
-import type { AgentAdapter } from "./types";
+import { getInstalledAgents } from "../registry";
+import type { AgentAdapter } from "../types";
 
 /**
  * Information about an installed agent including its version
@@ -90,7 +90,7 @@ export async function getAgentVersions(): Promise<AgentVersionInfo[]> {
   const agentsByName = new Map(agents.map((a) => [a.name, a]));
 
   // Import ALL_AGENTS to include non-installed ones
-  const { ALL_AGENTS } = await import("./registry");
+  const { ALL_AGENTS } = await import("../registry");
 
   const versions = await Promise.all(
     ALL_AGENTS.map(async (agent: AgentAdapter): Promise<AgentVersionInfo> => {

package/src/agents/types.ts

@@ -18,7 +18,7 @@ export type {
   DecomposedStory,
   PtyHandle,
   InteractiveRunOptions,
-} from "./types-extended";
+} from "./shared/types-extended";
 
 /**
  * Agent execution result returned after running a coding agent.
@@ -165,10 +165,12 @@ export interface AgentAdapter {
   buildCommand(options: AgentRunOptions): string[];
 
   /** Run the agent in plan mode to generate a feature specification. */
-  plan(options: import("./types-extended").PlanOptions): Promise<import("./types-extended").PlanResult>;
+  plan(options: import("./shared/types-extended").PlanOptions): Promise<import("./shared/types-extended").PlanResult>;
 
   /** Run the agent in decompose mode to break spec into classified stories. */
-  decompose(options: import("./types-extended").DecomposeOptions): Promise<import("./types-extended").DecomposeResult>;
+  decompose(
+    options: import("./shared/types-extended").DecomposeOptions,
+  ): Promise<import("./shared/types-extended").DecomposeResult>;
 
   /**
    * Run a one-shot LLM call and return the plain text response.
@@ -181,5 +183,7 @@ export interface AgentAdapter {
    * This method is optional — only implemented by agents that support
    * interactive terminal sessions (e.g., Claude Code).
    */
-  runInteractive?(options: import("./types-extended").InteractiveRunOptions): import("./types-extended").PtyHandle;
+  runInteractive?(
+    options: import("./shared/types-extended").InteractiveRunOptions,
+  ): import("./shared/types-extended").PtyHandle;
 }

package/src/cli/agents.ts

@@ -5,7 +5,7 @@
  */
 
 import { ALL_AGENTS } from "../agents/registry";
-import { getAgentVersion } from "../agents/version-detection";
+import { getAgentVersion } from "../agents/shared/version-detection";
 import type { NaxConfig } from "../config/schema";
 
 /**

package/src/cli/plan.ts

@@ -16,6 +16,7 @@ import { scanCodebase } from "../analyze/scanner";
 import type { CodebaseScan } from "../analyze/types";
 import type { NaxConfig } from "../config";
 import { resolvePermissions } from "../config/permissions";
+import { COMPLEXITY_GUIDE, GROUPING_RULES, TEST_STRATEGY_GUIDE } from "../config/test-strategy";
 import { PidRegistry } from "../execution/pid-registry";
 import { getLogger } from "../logger";
 import { validatePlanOutput } from "../prd/schema";
@@ -320,19 +321,11 @@ Generate a JSON object with this exact structure (no markdown, no explanation
   ]
 }
 
-## Complexity Classification Guide
+${COMPLEXITY_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
-- 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
+${TEST_STRATEGY_GUIDE}
 
-## Test Strategy Guide
-
-- test-after: Simple changes with well-understood behavior. Write tests after implementation.
-- tdd-simple: Medium complexity. Write key tests first, implement, then fill coverage.
-- three-session-tdd: Complex stories. Full TDD cycle with separate test-writer and implementer sessions.
-- three-session-tdd-lite: Expert/high-risk stories. Full TDD with additional verifier session.
+${GROUPING_RULES}
 
 ${
   outputFilePath

package/src/config/test-strategy.ts

@@ -0,0 +1,70 @@
+/**
+ * Test Strategy — Single Source of Truth
+ *
+ * Defines all valid test strategies, the normalizer, and shared prompt
+ * fragments used by plan.ts and claude-decompose.ts.
+ */
+
+import type { TestStrategy } from "./schema-types";
+
+// ─── Re-export type ───────────────────────────────────────────────────────────
+
+export type { TestStrategy };
+
+// ─── Valid values ─────────────────────────────────────────────────────────────
+
+export const VALID_TEST_STRATEGIES: readonly TestStrategy[] = [
+  "test-after",
+  "tdd-simple",
+  "three-session-tdd",
+  "three-session-tdd-lite",
+];
+
+// ─── Resolver ────────────────────────────────────────────────────────────────
+
+/**
+ * Validate and normalize a test strategy string.
+ * Returns a valid TestStrategy or falls back to "test-after".
+ */
+export function resolveTestStrategy(raw: string | undefined): TestStrategy {
+  if (!raw) return "test-after";
+  if (VALID_TEST_STRATEGIES.includes(raw as TestStrategy)) return raw as TestStrategy;
+  // Map legacy/typo values
+  if (raw === "tdd") return "tdd-simple";
+  if (raw === "three-session") return "three-session-tdd";
+  if (raw === "tdd-lite") return "three-session-tdd-lite";
+  return "test-after"; // safe fallback
+}
+
+// ─── Prompt fragments (shared by plan.ts and claude-decompose.ts) ────────────
+
+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
+- 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
+
+### 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.`;
+
+export const TEST_STRATEGY_GUIDE = `## Test Strategy Guide
+
+- test-after: Simple changes with well-understood behavior. Write tests after implementation.
+- tdd-simple: Medium complexity. Write key tests first, implement, then fill coverage.
+- three-session-tdd: Complex stories. Full TDD cycle with separate test-writer and implementer sessions.
+- three-session-tdd-lite: Expert/high-risk stories. Full TDD with additional verifier session.`;
+
+export const GROUPING_RULES = `## Grouping Rules
+
+- 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.
+- Aim for coherent units of value. Maximum recommended stories: 10-15 per feature.`;

package/src/execution/lifecycle/acceptance-loop.ts

@@ -143,6 +143,7 @@ async function executeFixStory(
     hooks: ctx.hooks,
     plugins: ctx.pluginRegistry,
     storyStartTime: new Date().toISOString(),
+    agentGetFn: ctx.agentGetFn,
   };
   const result = await runPipeline(defaultPipeline, fixContext, ctx.eventEmitter);
   logger?.info("acceptance", `Fix story ${story.id} ${result.success ? "passed" : "failed"}`);
@@ -189,6 +190,7 @@ export async function runAcceptanceLoop(ctx: AcceptanceLoopContext): Promise<Acc
       featureDir: ctx.featureDir,
       hooks: ctx.hooks,
       plugins: ctx.pluginRegistry,
+      agentGetFn: ctx.agentGetFn,
     };
 
     const { acceptanceStage } = await import("../../pipeline/stages/acceptance");

package/src/execution/parallel-coordinator.ts

@@ -8,7 +8,7 @@ import type { NaxConfig } from "../config";
 import type { LoadedHooksConfig } from "../hooks";
 import { getSafeLogger } from "../logger";
 import type { PipelineEventEmitter } from "../pipeline/events";
-import type { PipelineContext } from "../pipeline/types";
+import type { AgentGetFn } from "../pipeline/types";
 import type { PluginRegistry } from "../plugins/registry";
 import type { PRD, UserStory } from "../prd";
 import { markStoryFailed, markStoryPassed, savePRD } from "../prd";
@@ -108,6 +108,7 @@ export async function executeParallel(
   featureDir: string | undefined,
   parallel: number,
   eventEmitter?: PipelineEventEmitter,
+  agentGetFn?: AgentGetFn,
 ): Promise<{
   storiesCompleted: number;
   totalCost: number;
@@ -152,6 +153,7 @@ export async function executeParallel(
       hooks,
       plugins,
       storyStartTime: new Date().toISOString(),
+      agentGetFn,
     };
 
     // Create worktrees for all stories in batch

package/src/execution/parallel-executor.ts

@@ -17,6 +17,7 @@ import { fireHook } from "../hooks";
 import { getSafeLogger } from "../logger";
 import type { StoryMetrics } from "../metrics";
 import type { PipelineEventEmitter } from "../pipeline/events";
+import type { AgentGetFn } from "../pipeline/types";
 import type { PluginRegistry } from "../plugins/registry";
 import type { PRD } from "../prd";
 import { countStories, isComplete } from "../prd";
@@ -57,6 +58,7 @@ export interface ParallelExecutorOptions {
   pluginRegistry: PluginRegistry;
   formatterMode: "quiet" | "normal" | "verbose" | "json";
   headless: boolean;
+  agentGetFn?: AgentGetFn;
 }
 
 export interface RectificationStats {
@@ -158,6 +160,7 @@ export async function runParallelExecution(
       featureDir,
       parallelCount,
       eventEmitter,
+      options.agentGetFn,
     );
 
     const batchDurationMs = Date.now() - batchStartMs;

package/src/execution/runner-execution.ts

@@ -129,10 +129,24 @@ export async function runExecutionPhase(
   clearLlmCache();
 
   // PERF-1: Precompute batch plan once from ready stories
-  const batchPlan = options.useBatch ? precomputeBatchPlan(getAllReadyStories(prd), 4) : [];
+  const readyStories = getAllReadyStories(prd);
+
+  // BUG-068: debug log to diagnose unexpected storyCount in batch routing
+  logger?.debug("routing", "Ready stories for batch routing", {
+    readyCount: readyStories.length,
+    readyIds: readyStories.map((s) => s.id),
+    allStories: prd.userStories.map((s) => ({
+      id: s.id,
+      status: s.status,
+      passes: s.passes,
+      deps: s.dependencies,
+    })),
+  });
+
+  const batchPlan = options.useBatch ? precomputeBatchPlan(readyStories, 4) : [];
 
   if (options.useBatch) {
-    await tryLlmBatchRoute(options.config, getAllReadyStories(prd), "routing");
+    await tryLlmBatchRoute(options.config, readyStories, "routing");
   }
 
   // Parallel Execution Path (when --parallel is set)

package/src/execution/story-context.ts

@@ -175,6 +175,12 @@ export async function buildStoryContextFull(
 export function getAllReadyStories(prd: PRD): UserStory[] {
   const completedIds = new Set(prd.userStories.filter((s) => s.passes || s.status === "skipped").map((s) => s.id));
 
+  const logger = getSafeLogger();
+  logger?.debug("routing", "getAllReadyStories: completed set", {
+    completedIds: [...completedIds],
+    totalStories: prd.userStories.length,
+  });
+
   return prd.userStories.filter(
     (s) =>
       !s.passes &&

package/src/pipeline/stages/acceptance.ts

@@ -27,6 +27,7 @@
 import path from "node:path";
 import { getLogger } from "../../logger";
 import { countStories } from "../../prd";
+import { logTestOutput } from "../../utils/log-test-output";
 import type { PipelineContext, PipelineStage, StageResult } from "../types";
 
 /**
@@ -163,10 +164,8 @@ export const acceptanceStage: PipelineStage = {
 
     // Non-zero exit but no AC failures parsed at all — test crashed (syntax error, import failure, etc.)
     if (failedACs.length === 0 && exitCode !== 0) {
-      logger.error("acceptance", "Tests errored with no AC failures parsed", {
-        exitCode,
-        output,
-      });
+      logger.error("acceptance", "Tests errored with no AC failures parsed", { exitCode });
+      logTestOutput(logger, "acceptance", output);
 
       ctx.acceptanceFailures = {
         failedACs: ["AC-ERROR"],
@@ -190,10 +189,8 @@ export const acceptanceStage: PipelineStage = {
         });
       }
 
-      logger.error("acceptance", "Acceptance tests failed", {
-        failedACs: actualFailures,
-        output,
-      });
+      logger.error("acceptance", "Acceptance tests failed", { failedACs: actualFailures });
+      logTestOutput(logger, "acceptance", output);
 
       // Store failed ACs and test output in context for fix generation
       ctx.acceptanceFailures = {

package/src/pipeline/stages/regression.ts

@@ -14,6 +14,7 @@
  */
 
 import { getLogger } from "../../logger";
+import { logTestOutput } from "../../utils/log-test-output";
 import { verificationOrchestrator } from "../../verification/orchestrator";
 import type { VerifyContext } from "../../verification/orchestrator-types";
 import { pipelineEventBus } from "../event-bus";
@@ -71,6 +72,7 @@ export const regressionStage: PipelineStage = {
       storyId: ctx.story.id,
       failCount: result.failCount,
     });
+    logTestOutput(logger, "regression", result.rawOutput, { storyId: ctx.story.id });
 
     pipelineEventBus.emit({
       type: "regression:detected",

package/src/pipeline/stages/verify.ts

@@ -11,6 +11,7 @@
 
 import type { SmartTestRunnerConfig } from "../../config/types";
 import { getLogger } from "../../logger";
+import { logTestOutput } from "../../utils/log-test-output";
 import { detectRuntimeCrash } from "../../verification/crash-detector";
 import type { VerifyStatus } from "../../verification/orchestrator-types";
 import { regression } from "../../verification/runners";
@@ -173,16 +174,10 @@ export const verifyStage: PipelineStage = {
         });
       }
 
-      // Log first few lines of output for context
-      // BUG-037: Changed from .slice(0, 10) to .slice(-20) to show failures, not prechecks
-      if (result.output && result.status !== "TIMEOUT") {
-        const outputLines = result.output.split("\n").slice(-20);
-        if (outputLines.length > 0) {
-          logger.debug("verify", "Test output preview", {
-            storyId: ctx.story.id,
-            output: outputLines.join("\n"),
-          });
-        }
+      // Log tail of output at debug level for context (ENH-001)
+      // BUG-037: Use .slice(-20) to show failures, not prechecks
+      if (result.status !== "TIMEOUT") {
+        logTestOutput(logger, "verify", result.output, { storyId: ctx.story.id });
       }
 
       return {

package/src/prd/schema.ts

@@ -5,6 +5,7 @@
  */
 
 import type { Complexity, TestStrategy } from "../config";
+import { resolveTestStrategy } from "../config/test-strategy";
 import type { PRD, UserStory } from "./types";
 import { validateStoryId } from "./validate";
 
@@ -13,12 +14,6 @@ import { validateStoryId } from "./validate";
 // ---------------------------------------------------------------------------
 
 const VALID_COMPLEXITY: Complexity[] = ["simple", "medium", "complex", "expert"];
-const VALID_TEST_STRATEGIES: TestStrategy[] = [
-  "test-after",
-  "tdd-simple",
-  "three-session-tdd",
-  "three-session-tdd-lite",
-];
 
 /** Pattern matching ST001 → ST-001 style IDs (prefix letters + digits, no separator) */
 const STORY_ID_NO_SEPARATOR = /^([A-Za-z]+)(\d+)$/;
@@ -140,15 +135,10 @@ function validateStory(raw: unknown, index: number, allIds: Set<string>): UserSt
   }
 
   // testStrategy — accept from routing.testStrategy or top-level testStrategy
-  // Also map legacy/LLM-hallucinated aliases: tdd-lite → tdd-simple
   const rawTestStrategy = routing.testStrategy ?? s.testStrategy;
-  const STRATEGY_ALIASES: Record<string, TestStrategy> = { "tdd-lite": "three-session-tdd-lite" };
-  const normalizedStrategy =
-    typeof rawTestStrategy === "string" ? (STRATEGY_ALIASES[rawTestStrategy] ?? rawTestStrategy) : rawTestStrategy;
-  const testStrategy: TestStrategy =
-    normalizedStrategy !== undefined && (VALID_TEST_STRATEGIES as unknown[]).includes(normalizedStrategy)
-      ? (normalizedStrategy as TestStrategy)
-      : "tdd-simple";
+  const testStrategy: TestStrategy = resolveTestStrategy(
+    typeof rawTestStrategy === "string" ? rawTestStrategy : undefined,
+  );
 
   // dependencies
   const rawDeps = s.dependencies;

package/src/precheck/checks-agents.ts

@@ -5,7 +5,7 @@
  * and checks health status for each configured agent.
  */
 
-import { getAgentVersions } from "../agents/version-detection";
+import { getAgentVersions } from "../agents/shared/version-detection";
 import type { Check } from "./types";
 
 /**

package/src/utils/log-test-output.ts

@@ -0,0 +1,25 @@
+import type { Logger } from "../logger";
+
+/**
+ * Log test output consistently across all pipeline stages.
+ *
+ * Summary (exitCode, storyId) is logged at the caller's level (error/warn).
+ * Raw output is logged at debug level only — last `tailLines` lines.
+ *
+ * `storyId` is optional: works for per-story verify/acceptance AND for
+ * deferred runs (deferred acceptance, deferred regression) with no story context.
+ */
+export function logTestOutput(
+  logger: Logger | null | undefined,
+  stage: string,
+  output: string | undefined,
+  opts: { storyId?: string; tailLines?: number } = {},
+): void {
+  if (!logger || !output) return;
+  const tailLines = opts.tailLines ?? 20;
+  const lines = output.split("\n").slice(-tailLines).join("\n");
+  logger.debug(stage, "Test output (tail)", {
+    ...(opts.storyId !== undefined && { storyId: opts.storyId }),
+    output: lines,
+  });
+}