@nathapp/nax 0.20.0 → 0.22.0

package/memory/topic/feat-013-test-after-deprecation.md

@@ -0,0 +1,22 @@
+# FEAT-013 — Deprecate test-after from auto routing
+
+## Decision
+Remove `test-after` as the default fallback in `auto` mode.
+Change simple/medium stories to route to `three-session-tdd-lite` instead.
+
+## Why
+- `test-after` has high test failure rate — tests rubber-stamp implementation rather than driving design
+- Failed test-after stories escalate to powerful tier anyway → costs more in the end
+- `three-session-tdd-lite` = better quality at moderate cost increase
+
+## New auto routing decision tree
+```
+security/public-api keywords  → three-session-tdd
+complex/expert complexity     → three-session-tdd (or lite if ui/cli tags)
+simple/medium (default)       → three-session-tdd-lite  ← was test-after
+```
+
+## Backward compatibility
+- `tddStrategy: "off"` in config still routes to `test-after` (explicit opt-in)
+- `tddStrategy: "strict"` → three-session-tdd (unchanged)
+- `tddStrategy: "lite"` → three-session-tdd-lite (unchanged)

package/nax/config.json

@@ -60,7 +60,7 @@
     "iterationDelayMs": 2000,
     "costLimit": 8.0,
     "sessionTimeoutSeconds": 7200,
-    "verificationTimeoutSeconds": 300,
+    "verificationTimeoutSeconds": 600,
     "maxStoriesPerFeature": 15,
     "rectification": {
       "enabled": true,
@@ -70,8 +70,11 @@
       "abortOnIncreasingFailures": true
     },
     "regressionGate": {
-      "enabled": false,
-      "timeoutSeconds": 300
+      "enabled": true,
+      "mode": "deferred",
+      "timeoutSeconds": 600,
+      "acceptOnTimeout": true,
+      "maxRectificationAttempts": 2
     }
   },
   "quality": {
@@ -147,4 +150,4 @@
       "scopeToStory": true
     }
   }
-}
+}

package/nax/features/bug-039-medium/prd.json

@@ -0,0 +1,45 @@
+{
+  "project": "nax",
+  "feature": "bug-039-medium",
+  "branchName": "fix/bug-039-process-cleanup-medium",
+  "createdAt": "2026-03-06T04:51:00.000Z",
+  "updatedAt": "2026-03-06T04:51:00.000Z",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "runOnce() SIGKILL follow-up after grace period",
+      "description": "In src/agents/claude.ts:runOnce(), the timeout handler only sends SIGTERM but never follows up with SIGKILL. Claude may ignore SIGTERM and run indefinitely. Add a SIGKILL after a 5-second grace period, mirroring the pattern in src/verification/executor.ts:executeWithTimeout(). Also move pidRegistry.unregister(processPid) into a finally block so it is always called even if the timeout path throws an exception.",
+      "acceptanceCriteria": [
+        "When runOnce() times out, SIGTERM is sent first",
+        "After 5 seconds grace period, SIGKILL is sent to ensure the process is dead",
+        "pidRegistry.unregister(processPid) is called in a finally block — always runs regardless of success or exception path",
+        "Existing runOnce() tests still pass",
+        "New test: timeout path always unregisters PID even if SIGTERM/SIGKILL throws"
+      ],
+      "tags": ["bug", "process", "cleanup"],
+      "dependencies": [],
+      "status": "pending",
+      "passes": false,
+      "escalations": [],
+      "attempts": 0
+    },
+    {
+      "id": "US-002",
+      "title": "LLM routing stream drain fix on timeout",
+      "description": "In src/routing/strategies/llm.ts:callLlmOnce(), when the timeout fires, proc.kill() is called but the stdout/stderr ReadableStreams from the Bun.spawn() are never cancelled or drained. This can cause proc.exited to hang indefinitely because Bun's piped streams may block exit. Fix: before calling proc.kill(), cancel both streams with proc.stdout.cancel() and proc.stderr.cancel() wrapped in try/catch. This ensures proc.exited resolves promptly after kill.",
+      "acceptanceCriteria": [
+        "On LLM timeout, proc.stdout and proc.stderr are cancelled before proc.kill()",
+        "proc.exited resolves promptly after timeout kill (does not hang)",
+        "clearTimeout(timeoutId) still called in both success and error paths",
+        "Existing LLM routing tests still pass",
+        "New test: timeout path resolves without hanging (use fake timers or short timeout)"
+      ],
+      "tags": ["bug", "process", "cleanup", "llm"],
+      "dependencies": [],
+      "status": "pending",
+      "passes": false,
+      "escalations": [],
+      "attempts": 0
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {
@@ -44,4 +44,4 @@
     "tdd",
     "coding"
   ]
-}
+}

package/src/agents/claude.ts

@@ -36,6 +36,24 @@ const MAX_AGENT_OUTPUT_CHARS = 5000;
  */
 const MAX_AGENT_STDERR_CHARS = 1000;
 
+/**
+ * Grace period in ms between SIGTERM and SIGKILL on timeout.
+ * Mirrors the pattern in src/verification/executor.ts:executeWithTimeout().
+ */
+const SIGKILL_GRACE_PERIOD_MS = 5000;
+
+/**
+ * Injectable dependencies for runOnce() — allows tests to verify
+ * that PID cleanup (unregister) always runs even if kill() throws.
+ *
+ * @internal
+ */
+export const _runOnceDeps = {
+  killProc(proc: { kill(signal?: number | NodeJS.Signals): void }, signal: NodeJS.Signals): void {
+    proc.kill(signal);
+  },
+};
+
 /**
  * Claude Code agent adapter implementation.
  *
@@ -183,25 +201,69 @@ export class ClaudeCodeAdapter implements AgentAdapter {
     let timedOut = false;
     const timeoutId = setTimeout(() => {
       timedOut = true;
-      proc.kill("SIGTERM");
+      try {
+        _runOnceDeps.killProc(proc, "SIGTERM" as NodeJS.Signals);
+      } catch {
+        /* already exited */
+      }
+      setTimeout(() => {
+        try {
+          _runOnceDeps.killProc(proc, "SIGKILL" as NodeJS.Signals);
+        } catch {
+          /* already exited */
+        }
+      }, SIGKILL_GRACE_PERIOD_MS);
     }, options.timeoutSeconds * 1000);
 
-    const exitCode = await proc.exited;
-    clearTimeout(timeoutId);
-
-    await pidRegistry.unregister(processPid);
+    let exitCode: number;
+    try {
+      // Hard deadline: if proc.exited doesn't resolve after kill signals are sent
+      // (Bun subprocess edge case on some environments), fall back to -1 so the
+      // caller can move on. timedOut flag ensures the result is still marked 124.
+      const hardDeadlineMs = options.timeoutSeconds * 1000 + SIGKILL_GRACE_PERIOD_MS + 3000;
+      exitCode = await Promise.race([
+        proc.exited,
+        new Promise<number>((resolve) => setTimeout(() => resolve(-1), hardDeadlineMs)),
+      ]);
+
+      // If hard deadline fired, the subprocess may still be alive (Bun SIGKILL edge case).
+      // Force-kill via OS-level signal so that the stdout pipe closes and we don't block.
+      if (exitCode === -1) {
+        try {
+          process.kill(processPid, "SIGKILL");
+        } catch {
+          /* already gone */
+        }
+        // Note: process.kill(-pid) (process group) only works if the child called
+        // setpgid/setsid. Bun does not do this, so this will silently throw ESRCH.
+        // Left here as a best-effort safety net for environments that do set a pgid.
+        try {
+          process.kill(-processPid, "SIGKILL");
+        } catch {
+          /* no process group — expected in most environments */
+        }
+      }
+    } finally {
+      clearTimeout(timeoutId);
+      await pidRegistry.unregister(processPid);
+    }
 
-    const stdout = await new Response(proc.stdout).text();
-    const stderr = await new Response(proc.stderr).text();
+    // Use a deadline on stdout read — if the subprocess pipe is still open
+    // (e.g. hard-deadline fired but process didn't fully die), don't block forever.
+    const stdout = await Promise.race([
+      new Response(proc.stdout).text(),
+      new Promise<string>((resolve) => setTimeout(() => resolve(""), 5000)),
+    ]);
+    const stderr = proc.stderr ? await new Response(proc.stderr).text() : "";
     const durationMs = Date.now() - startTime;
 
+    // Claude Code emits rate limit messages as part of its output.
+    const fullOutput = stdout + stderr;
     const rateLimited =
-      stderr.includes("rate limit") ||
-      stderr.includes("429") ||
-      stdout.includes("rate limit") ||
-      stdout.includes("Too many requests");
+      fullOutput.toLowerCase().includes("rate limit") ||
+      fullOutput.includes("429") ||
+      fullOutput.toLowerCase().includes("too many requests");
 
-    const fullOutput = stdout + stderr;
     let costEstimate = estimateCostFromOutput(options.modelTier, fullOutput);
     const logger = getLogger();
     if (!costEstimate) {
@@ -267,11 +329,43 @@ export class ClaudeCodeAdapter implements AgentAdapter {
 
     await pidRegistry.register(proc.pid);
 
-    const exitCode = await proc.exited;
+    // BUG-039: Hard timeout for decompose — prevents infinite hang if claude hangs
+    const DECOMPOSE_TIMEOUT_MS = 300_000; // 5 minutes
+    let timedOut = false;
+    const decomposeTimerId = setTimeout(() => {
+      timedOut = true;
+      try {
+        proc.kill("SIGTERM");
+      } catch {
+        /* already exited */
+      }
+      setTimeout(() => {
+        try {
+          proc.kill("SIGKILL");
+        } catch {
+          /* already exited */
+        }
+      }, 5000);
+    }, DECOMPOSE_TIMEOUT_MS);
+
+    let exitCode: number;
+    try {
+      exitCode = await proc.exited;
+    } finally {
+      clearTimeout(decomposeTimerId);
+      await pidRegistry.unregister(proc.pid);
+    }
 
-    await pidRegistry.unregister(proc.pid);
+    if (timedOut) {
+      throw new Error(`Decompose timed out after ${DECOMPOSE_TIMEOUT_MS / 1000}s`);
+    }
 
-    const stdout = await new Response(proc.stdout).text();
+    // Use a deadline on stdout read — if the subprocess pipe is still open
+    // (e.g. hard-deadline fired but process didn't fully die), don't block forever.
+    const stdout = await Promise.race([
+      new Response(proc.stdout).text(),
+      new Promise<string>((resolve) => setTimeout(() => resolve(""), 5000)),
+    ]);
     const stderr = await new Response(proc.stderr).text();
 
     if (exitCode !== 0) {

package/src/config/types.ts

@@ -140,6 +140,17 @@ export interface QualityConfig {
     typecheck?: string;
     lint?: string;
     test?: string;
+    /** Auto-fix lint errors (e.g., "biome check --fix") */
+    lintFix?: string;
+    /** Auto-fix formatting (e.g., "biome format --write") */
+    formatFix?: string;
+  };
+  /** Auto-fix configuration (Phase 2) */
+  autofix?: {
+    /** Whether to auto-fix lint/format errors before escalating (default: true) */
+    enabled?: boolean;
+    /** Max auto-fix attempts (default: 2) */
+    maxAttempts?: number;
   };
   /** Append --forceExit to test command to prevent open handle hangs (default: false) */
   forceExit: boolean;

package/src/context/builder.ts

@@ -232,13 +232,21 @@ async function addFileElements(
         continue;
       }
       if (file.size > MAX_FILE_SIZE_BYTES) {
+        // FEAT-011: File too large to inline — pass path-only so agent can read it if needed
         const logger = getLogger();
-        logger.warn("context", "File too large", {
+        logger.warn("context", "File too large for inline — using path-only", {
           filePath: relativeFilePath,
           sizeKB: Math.round(file.size / 1024),
           maxKB: 10,
           storyId: story.id,
         });
+        elements.push(
+          createFileContext(
+            relativeFilePath,
+            `_File too large to inline (${Math.round(file.size / 1024)}KB). Path: \`${relativeFilePath}\` — read it directly if needed._`,
+            5,
+          ),
+        );
         continue;
       }
       const content = await file.text();

package/src/execution/dry-run.ts

@@ -0,0 +1,81 @@
+/**
+ * Dry Run Handler (ADR-005, Phase 4)
+ *
+ * Extracted from pipeline-result-handler.ts to slim that file below 200 lines.
+ */
+
+import { getSafeLogger } from "../logger";
+import { pipelineEventBus } from "../pipeline/event-bus";
+import type { PluginRegistry } from "../plugins";
+import { markStoryPassed, savePRD } from "../prd";
+import type { PRD, UserStory } from "../prd/types";
+import type { routeTask } from "../routing";
+import type { StatusWriter } from "./status-writer";
+
+export interface DryRunContext {
+  prd: PRD;
+  prdPath: string;
+  storiesToExecute: UserStory[];
+  routing: ReturnType<typeof routeTask>;
+  statusWriter: StatusWriter;
+  pluginRegistry: PluginRegistry;
+  runId: string;
+  totalCost: number;
+  iterations: number;
+}
+
+export interface DryRunResult {
+  storiesCompletedDelta: number;
+  prdDirty: boolean;
+}
+
+/** Handle dry-run iteration: log what would happen, mark stories passed. */
+export async function handleDryRun(ctx: DryRunContext): Promise<DryRunResult> {
+  const logger = getSafeLogger();
+
+  ctx.statusWriter.setPrd(ctx.prd);
+  ctx.statusWriter.setCurrentStory({
+    storyId: ctx.storiesToExecute[0].id,
+    title: ctx.storiesToExecute[0].title,
+    complexity: ctx.routing.complexity,
+    tddStrategy: ctx.routing.testStrategy,
+    model: ctx.routing.modelTier,
+    attempt: (ctx.storiesToExecute[0].attempts ?? 0) + 1,
+    phase: "routing",
+  });
+  await ctx.statusWriter.update(ctx.totalCost, ctx.iterations);
+
+  for (const s of ctx.storiesToExecute) {
+    logger?.info("execution", "[DRY RUN] Would execute agent here", {
+      storyId: s.id,
+      storyTitle: s.title,
+      modelTier: ctx.routing.modelTier,
+      complexity: ctx.routing.complexity,
+      testStrategy: ctx.routing.testStrategy,
+    });
+  }
+
+  for (const s of ctx.storiesToExecute) {
+    markStoryPassed(ctx.prd, s.id);
+  }
+  await savePRD(ctx.prd, ctx.prdPath);
+
+  for (const s of ctx.storiesToExecute) {
+    pipelineEventBus.emit({
+      type: "story:completed",
+      storyId: s.id,
+      story: s,
+      passed: true,
+      durationMs: 0,
+      cost: 0,
+      modelTier: ctx.routing.modelTier,
+      testStrategy: ctx.routing.testStrategy,
+    });
+  }
+
+  ctx.statusWriter.setPrd(ctx.prd);
+  ctx.statusWriter.setCurrentStory(null);
+  await ctx.statusWriter.update(ctx.totalCost, ctx.iterations);
+
+  return { storiesCompletedDelta: ctx.storiesToExecute.length, prdDirty: true };
+}

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

@@ -3,13 +3,14 @@
  *
  * Extracted from tier-escalation.ts: handles outcomes when escalation
  * is not possible (no tier available or max attempts reached).
+ *
+ * Phase 3 (ADR-005): Replaced direct fireHook() calls with event bus emissions.
  */
 
-import { fireHook } from "../../hooks";
 import { getSafeLogger } from "../../logger";
+import { pipelineEventBus } from "../../pipeline/event-bus";
 import { markStoryFailed, markStoryPaused, savePRD } from "../../prd";
 import type { FailureCategory } from "../../tdd/types";
-import { hookCtx } from "../helpers";
 import { appendProgress } from "../progress";
 import type { EscalationHandlerContext, EscalationHandlerResult } from "./tier-escalation";
 import { resolveMaxAttemptsOutcome } from "./tier-escalation";
@@ -43,16 +44,12 @@ export async function handleNoTierAvailable(
       );
     }
 
-    await fireHook(
-      ctx.hooks,
-      "on-pause",
-      hookCtx(ctx.feature, {
-        storyId: ctx.story.id,
-        reason: `Execution stopped (${failureCategory ?? "unknown"} requires human review)`,
-        cost: ctx.totalCost,
-      }),
-      ctx.workdir,
-    );
+    pipelineEventBus.emit({
+      type: "story:paused",
+      storyId: ctx.story.id,
+      reason: `Execution stopped (${failureCategory ?? "unknown"} requires human review)`,
+      cost: ctx.totalCost,
+    });
 
     return { outcome: "paused", prdDirty: true, prd: pausedPrd };
   }
@@ -70,17 +67,13 @@ export async function handleNoTierAvailable(
     await appendProgress(ctx.featureDir, ctx.story.id, "failed", `${ctx.story.title} — Execution failed`);
   }
 
-  await fireHook(
-    ctx.hooks,
-    "on-story-fail",
-    hookCtx(ctx.feature, {
-      storyId: ctx.story.id,
-      status: "failed",
-      reason: "Execution failed",
-      cost: ctx.totalCost,
-    }),
-    ctx.workdir,
-  );
+  pipelineEventBus.emit({
+    type: "story:failed",
+    storyId: ctx.story.id,
+    story: ctx.story,
+    reason: "Execution failed",
+    countsTowardEscalation: true,
+  });
 
   return { outcome: "failed", prdDirty: true, prd: failedPrd };
 }
@@ -114,16 +107,12 @@ export async function handleMaxAttemptsReached(
       );
     }
 
-    await fireHook(
-      ctx.hooks,
-      "on-pause",
-      hookCtx(ctx.feature, {
-        storyId: ctx.story.id,
-        reason: `Max attempts reached (${failureCategory ?? "unknown"} requires human review)`,
-        cost: ctx.totalCost,
-      }),
-      ctx.workdir,
-    );
+    pipelineEventBus.emit({
+      type: "story:paused",
+      storyId: ctx.story.id,
+      reason: `Max attempts reached (${failureCategory ?? "unknown"} requires human review)`,
+      cost: ctx.totalCost,
+    });
 
     return { outcome: "paused", prdDirty: true, prd: pausedPrd };
   }
@@ -142,17 +131,13 @@ export async function handleMaxAttemptsReached(
     await appendProgress(ctx.featureDir, ctx.story.id, "failed", `${ctx.story.title} — Max attempts reached`);
   }
 
-  await fireHook(
-    ctx.hooks,
-    "on-story-fail",
-    hookCtx(ctx.feature, {
-      storyId: ctx.story.id,
-      status: "failed",
-      reason: "Max attempts reached",
-      cost: ctx.totalCost,
-    }),
-    ctx.workdir,
-  );
+  pipelineEventBus.emit({
+    type: "story:failed",
+    storyId: ctx.story.id,
+    story: ctx.story,
+    reason: "Max attempts reached",
+    countsTowardEscalation: true,
+  });
 
   return { outcome: "failed", prdDirty: true, prd: failedPrd };
 }

package/src/execution/executor-types.ts

@@ -0,0 +1,65 @@
+/**
+ * Sequential Executor Types (ADR-005, Phase 4)
+ *
+ * Extracted from sequential-executor.ts to slim it below 200 lines.
+ */
+
+import type { NaxConfig } from "../config";
+import type { LoadedHooksConfig } from "../hooks";
+import type { InteractionChain } from "../interaction/chain";
+import type { StoryMetrics } from "../metrics";
+import type { PipelineEventEmitter } from "../pipeline/events";
+import type { RoutingResult } from "../pipeline/types";
+import type { PluginRegistry } from "../plugins";
+import type { PRD, UserStory } from "../prd/types";
+import type { StoryBatch } from "./batching";
+import type { StatusWriter } from "./status-writer";
+
+export interface SequentialExecutionContext {
+  prdPath: string;
+  workdir: string;
+  config: NaxConfig;
+  hooks: LoadedHooksConfig;
+  feature: string;
+  featureDir?: string;
+  dryRun: boolean;
+  useBatch: boolean;
+  pluginRegistry: PluginRegistry;
+  eventEmitter?: PipelineEventEmitter;
+  statusWriter: StatusWriter;
+  logFilePath?: string;
+  runId: string;
+  startTime: number;
+  batchPlan: StoryBatch[];
+  interactionChain?: InteractionChain | null;
+}
+
+export interface SequentialExecutionResult {
+  prd: PRD;
+  iterations: number;
+  storiesCompleted: number;
+  totalCost: number;
+  allStoryMetrics: StoryMetrics[];
+  exitReason: "completed" | "cost-limit" | "max-iterations" | "stalled" | "no-stories";
+}
+
+/**
+ * Build a preview routing from cached story.routing or config defaults.
+ * The pipeline routing stage performs full classification and overwrites ctx.routing.
+ * This preview is used only for logging, status display, and event emission.
+ */
+export function buildPreviewRouting(story: UserStory, config: NaxConfig): RoutingResult {
+  const cached = story.routing;
+  const defaultComplexity = "medium" as const;
+  const defaultTier = "balanced" as const;
+  const defaultStrategy = "test-after" as const;
+  return {
+    complexity: (cached?.complexity as RoutingResult["complexity"]) ?? defaultComplexity,
+    modelTier:
+      (cached?.modelTier as RoutingResult["modelTier"]) ??
+      (config.autoMode.complexityRouting?.[defaultComplexity] as RoutingResult["modelTier"]) ??
+      defaultTier,
+    testStrategy: (cached?.testStrategy as RoutingResult["testStrategy"]) ?? defaultStrategy,
+    reasoning: cached ? "cached from story.routing" : "preview (pending pipeline routing stage)",
+  };
+}

package/src/execution/index.ts

@@ -5,23 +5,6 @@ export { appendProgress } from "./progress";
 export { buildSingleSessionPrompt, buildBatchPrompt } from "./prompts";
 export { groupStoriesIntoBatches, type StoryBatch } from "./batching";
 export { escalateTier, getTierConfig, calculateMaxIterations } from "./escalation";
-export {
-  verifyAssets,
-  executeWithTimeout,
-  parseTestOutput,
-  getEnvironmentalEscalationThreshold,
-  normalizeEnvironment,
-  buildTestCommand,
-  appendOpenHandlesFlag,
-  appendForceExitFlag,
-  runVerification,
-  type VerificationResult,
-  type VerificationStatus,
-  type TestOutputAnalysis,
-  type AssetVerificationResult,
-  type TimeoutExecutionResult,
-} from "./verification";
-export { runPostAgentVerification, type PostVerifyOptions, type PostVerifyResult } from "./post-verify";
 export { readQueueFile, clearQueueFile } from "./queue-handler";
 export {
   hookCtx,