@nathapp/nax 0.22.4 → 0.23.0

package/docs/tdd/strategies.md

@@ -0,0 +1,97 @@
+# TDD Strategies
+
+nax supports three test strategies, selectable via `config.tdd.strategy` or per-story override.
+
+## Strategy Comparison
+
+| Aspect | `three-session-tdd` | `three-session-tdd-lite` | `test-after` |
+|---|---|---|---|
+| **Sessions** | 3 separate sessions | 3 separate sessions | 1 session |
+| **Session 1 (Test Writer)** | Strict isolation — tests only, NO src/ reads, NO stubs | Relaxed — can read src/, create stubs in src/ | ❌ No dedicated test writer |
+| **Session 2 (Implementer)** | Implements against pre-written tests | Same | Implements + writes tests |
+| **Session 3 (Verifier)** | Verifies isolation wasn't violated | Same | ❌ No verifier |
+| **Isolation check** | ✅ Full isolation enforcement | ✅ Full isolation enforcement | ❌ None |
+| **Isolation-violation fallback** | Triggers lite-mode retry | N/A (already lite) | N/A |
+| **Rectification gate** | Checks implementer isolation | ⚡ Skips `verifyImplementerIsolation` | Standard |
+
+---
+
+## When Each Strategy Is Used
+
+Controlled by `config.tdd.strategy`:
+
+| Config value | Behaviour |
+|---|---|
+| `"strict"` | Always `three-session-tdd` |
+| `"lite"` | Always `three-session-tdd-lite` |
+| `"off"` | Always `test-after` |
+| `"auto"` | LLM/keyword router decides (see routing rules below) |
+
+### Auto-Routing Rules (FEAT-013)
+
+`test-after` is **deprecated** from auto mode. Default fallback is now `three-session-tdd-lite`.
+
+| Condition | Strategy |
+|---|---|
+| Security / auth logic | `three-session-tdd` |
+| Public API / complex / expert | `three-session-tdd` |
+| UI / layout / CLI / integration / polyglot tags | `three-session-tdd-lite` |
+| Simple / medium (default) | `three-session-tdd-lite` |
+
+---
+
+## Session Detail
+
+### `three-session-tdd` — Full Mode
+
+1. **Test Writer** — writes failing tests only. Cannot read src/ files or create any source stubs. Strict isolation enforced by post-session diff check.
+2. **Implementer** — makes all failing tests pass. Works against the test-writer's output.
+3. **Verifier** — confirms isolation: tests were written before implementation, no cheating.
+
+If the test writer violates isolation (touches src/), the orchestrator flags it as `isolation-violation` and schedules a lite-mode retry on the next attempt.
+
+### `three-session-tdd-lite` — Lite Mode
+
+Same 3-session flow, but the test writer prompt is relaxed:
+- **Can read** existing src/ files (needed when importing existing types/interfaces).
+- **Can create minimal stubs** in src/ (empty exports, no logic) to make imports resolve.
+- Implementer isolation check (`verifyImplementerIsolation`) is **skipped** in the rectification gate.
+
+Best for: existing codebases where greenfield isolation is impractical, or stories that modify existing modules.
+
+### `test-after` — Single Session
+
+One Claude Code session writes tests and implements the feature together. No structured TDD flow.
+
+- Higher failure rate observed in practice — Claude tends to write tests that are trivially passing or implementation-first.
+- Use only when `tdd.strategy: "off"` or explicitly set per-story.
+
+---
+
+## Per-Story Override
+
+Add `testStrategy` to a story in `prd.json` to override routing:
+
+```json
+{
+  "userStories": [
+    {
+      "id": "US-001",
+      "testStrategy": "three-session-tdd-lite",
+      ...
+    }
+  ]
+}
+```
+
+Supported values: `"test-after"`, `"three-session-tdd"`, `"three-session-tdd-lite"`.
+
+---
+
+## Known Issues
+
+- **BUG-045:** LLM batch routing bypasses `config.tdd.strategy`. `buildBatchPrompt()` only offers `test-after` and `three-session-tdd` to the LLM — no `three-session-tdd-lite`. The cache hit path returns the LLM decision directly without calling `determineTestStrategy()`, so `tdd.strategy: "lite"` is silently ignored for batch-routed stories. Fix: post-process batch decisions through `determineTestStrategy()`. See `src/routing/strategies/llm.ts:routeBatch()`.
+
+---
+
+*Last updated: 2026-03-07*

package/nax/features/diagnose/acceptance.test.ts

@@ -97,7 +97,9 @@ async function createStatusFile(
 		...overrides,
 	};
 
-	await Bun.write(join(dir, ".nax-status.json"), JSON.stringify(status, null, 2));
+	// Ensure nax directory exists
+	mkdirSync(join(dir, "nax"), { recursive: true });
+	await Bun.write(join(dir, "nax", "status.json"), JSON.stringify(status, null, 2));
 }
 
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.22.4",
-  "description": "AI Coding Agent Orchestrator \u2014 loops until done",
+  "version": "0.23.0",
+  "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {
     "nax": "./bin/nax.ts"
@@ -9,7 +9,7 @@
   "scripts": {
     "prepare": "git config core.hooksPath .githooks",
     "dev": "bun run bin/nax.ts",
-    "build": "bun build bin/nax.ts --outdir dist --target bun",
+    "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/",
     "test": "NAX_SKIP_PRECHECK=1 bun test test/ --timeout=60000",
@@ -44,4 +44,4 @@
     "tdd",
     "coding"
   ]
-}
+}

package/src/cli/diagnose.ts

@@ -86,7 +86,7 @@ function isProcessAlive(pid: number): boolean {
 }
 
 async function loadStatusFile(workdir: string): Promise<NaxStatusFile | null> {
-  const statusPath = join(workdir, ".nax-status.json");
+  const statusPath = join(workdir, "nax", "status.json");
   if (!existsSync(statusPath)) return null;
   try {
     return (await Bun.file(statusPath).json()) as NaxStatusFile;

package/src/cli/status-features.ts

@@ -41,14 +41,11 @@ interface FeatureSummary {
   };
 }
 
-/** Check if a process is alive via PID check */
+/** Check if a process is alive via POSIX signal 0 (portable, no subprocess) */
 function isPidAlive(pid: number): boolean {
   try {
-    const result = Bun.spawnSync(["ps", "-p", String(pid)], {
-      stdout: "ignore",
-      stderr: "ignore",
-    });
-    return result.exitCode === 0;
+    process.kill(pid, 0);
+    return true;
   } catch {
     return false;
   }
@@ -69,6 +66,21 @@ async function loadStatusFile(featureDir: string): Promise<NaxStatusFile | null>
   }
 }
 
+/** Load project-level status.json (if it exists) */
+async function loadProjectStatusFile(projectDir: string): Promise<NaxStatusFile | null> {
+  const statusPath = join(projectDir, "nax", "status.json");
+  if (!existsSync(statusPath)) {
+    return null;
+  }
+
+  try {
+    const content = Bun.file(statusPath);
+    return (await content.json()) as NaxStatusFile;
+  } catch {
+    return null;
+  }
+}
+
 /** Get feature summary from prd.json and optional status.json */
 async function getFeatureSummary(featureName: string, featureDir: string): Promise<FeatureSummary> {
   const prdPath = join(featureDir, "prd.json");
@@ -154,10 +166,46 @@ async function displayAllFeatures(projectDir: string): Promise<void> {
     return;
   }
 
+  // Load project-level status if available (current run info)
+  const projectStatus = await loadProjectStatusFile(projectDir);
+
+  // Display current run info if available
+  if (projectStatus) {
+    const pidAlive = isPidAlive(projectStatus.run.pid);
+
+    if (projectStatus.run.status === "running" && pidAlive) {
+      console.log(chalk.yellow("⚡ Currently Running:\n"));
+      console.log(chalk.dim(`   Feature:    ${projectStatus.run.feature}`));
+      console.log(chalk.dim(`   Run ID:     ${projectStatus.run.id}`));
+      console.log(chalk.dim(`   Started:    ${projectStatus.run.startedAt}`));
+      console.log(chalk.dim(`   Progress:   ${projectStatus.progress.passed}/${projectStatus.progress.total} stories`));
+      console.log(chalk.dim(`   Cost:       $${projectStatus.cost.spent.toFixed(4)}`));
+
+      if (projectStatus.current) {
+        console.log(chalk.dim(`   Current:    ${projectStatus.current.storyId} - ${projectStatus.current.title}`));
+      }
+
+      console.log();
+    } else if ((projectStatus.run.status === "running" && !pidAlive) || projectStatus.run.status === "crashed") {
+      console.log(chalk.red("💥 Crashed Run Detected:\n"));
+      console.log(chalk.dim(`   Feature:    ${projectStatus.run.feature}`));
+      console.log(chalk.dim(`   Run ID:     ${projectStatus.run.id}`));
+      console.log(chalk.dim(`   PID:        ${projectStatus.run.pid} (dead)`));
+      console.log(chalk.dim(`   Started:    ${projectStatus.run.startedAt}`));
+      if (projectStatus.run.crashedAt) {
+        console.log(chalk.dim(`   Crashed:    ${projectStatus.run.crashedAt}`));
+      }
+      if (projectStatus.run.crashSignal) {
+        console.log(chalk.dim(`   Signal:     ${projectStatus.run.crashSignal}`));
+      }
+      console.log();
+    }
+  }
+
   // Load summaries for all features
   const summaries = await Promise.all(features.map((name) => getFeatureSummary(name, join(featuresDir, name))));
 
-  console.log(chalk.bold("\n📊 Features\n"));
+  console.log(chalk.bold("📊 Features\n"));
 
   // Print table header
   const header = `  ${"Feature".padEnd(25)} ${"Done".padEnd(6)} ${"Failed".padEnd(8)} ${"Pending".padEnd(9)} ${"Last Run".padEnd(22)} ${"Cost".padEnd(10)} Status`;

package/src/config/schemas.ts

@@ -117,6 +117,9 @@ const QualityConfigSchema = z.object({
     typecheck: z.string().optional(),
     lint: z.string().optional(),
     test: z.string().optional(),
+    testScoped: z.string().optional(),
+    lintFix: z.string().optional(),
+    formatFix: z.string().optional(),
   }),
   forceExit: z.boolean().default(false),
   detectOpenHandles: z.boolean().default(true),

package/src/execution/crash-recovery.ts

@@ -27,6 +27,8 @@ export interface CrashRecoveryContext {
   // BUG-017: Additional context for run.complete event on SIGTERM
   runId?: string;
   feature?: string;
+  // SFC-002: Feature directory for writing feature-level status on crash
+  featureDir?: string;
   getStartTime?: () => number;
   getTotalStories?: () => number;
   getStoriesCompleted?: () => number;
@@ -115,13 +117,14 @@ async function writeRunComplete(ctx: CrashRecoveryContext, exitReason: string):
 }
 
 /**
- * Update status.json to "crashed" state
+ * Update status.json to "crashed" state (both project-level and feature-level)
  */
 async function updateStatusToCrashed(
   statusWriter: StatusWriter,
   totalCost: number,
   iterations: number,
   signal: string,
+  featureDir?: string,
 ): Promise<void> {
   try {
     statusWriter.setRunStatus("crashed");
@@ -129,6 +132,14 @@ async function updateStatusToCrashed(
       crashedAt: new Date().toISOString(),
       crashSignal: signal,
     });
+
+    // Write feature-level status (SFC-002)
+    if (featureDir) {
+      await statusWriter.writeFeatureStatus(featureDir, totalCost, iterations, {
+        crashedAt: new Date().toISOString(),
+        crashSignal: signal,
+      });
+    }
   } catch (err) {
     console.error("[crash-recovery] Failed to update status.json:", err);
   }
@@ -166,8 +177,8 @@ export function installCrashHandlers(ctx: CrashRecoveryContext): () => void {
     // Write run.complete event (BUG-017)
     await writeRunComplete(ctx, signal.toLowerCase());
 
-    // Update status.json to crashed
-    await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), signal);
+    // Update status.json to crashed (SFC-002: include feature-level status)
+    await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), signal, ctx.featureDir);
 
     // Stop heartbeat
     stopHeartbeat();
@@ -201,8 +212,14 @@ export function installCrashHandlers(ctx: CrashRecoveryContext): () => void {
     // Write fatal log with stack trace
     await writeFatalLog(ctx.jsonlFilePath, "uncaughtException", error);
 
-    // Update status.json to crashed
-    await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), "uncaughtException");
+    // Update status.json to crashed (SFC-002: include feature-level status)
+    await updateStatusToCrashed(
+      ctx.statusWriter,
+      ctx.getTotalCost(),
+      ctx.getIterations(),
+      "uncaughtException",
+      ctx.featureDir,
+    );
 
     // Stop heartbeat
     stopHeartbeat();
@@ -228,8 +245,14 @@ export function installCrashHandlers(ctx: CrashRecoveryContext): () => void {
     // Write fatal log
     await writeFatalLog(ctx.jsonlFilePath, "unhandledRejection", error);
 
-    // Update status.json to crashed
-    await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), "unhandledRejection");
+    // Update status.json to crashed (SFC-002: include feature-level status)
+    await updateStatusToCrashed(
+      ctx.statusWriter,
+      ctx.getTotalCost(),
+      ctx.getIterations(),
+      "unhandledRejection",
+      ctx.featureDir,
+    );
 
     // Stop heartbeat
     stopHeartbeat();

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

@@ -25,6 +25,7 @@ import { loadPlugins } from "../../plugins/loader";
 import type { PluginRegistry } from "../../plugins/registry";
 import type { PRD } from "../../prd";
 import { loadPRD } from "../../prd";
+import { NAX_BUILD_INFO, NAX_COMMIT, NAX_VERSION } from "../../version";
 import { installCrashHandlers } from "../crash-recovery";
 import { acquireLock, hookCtx, releaseLock } from "../helpers";
 import { PidRegistry } from "../pid-registry";
@@ -36,6 +37,7 @@ export interface RunSetupOptions {
   config: NaxConfig;
   hooks: LoadedHooksConfig;
   feature: string;
+  featureDir?: string;
   dryRun: boolean;
   statusFile: string;
   logFilePath?: string;
@@ -117,6 +119,7 @@ export async function setupRun(options: RunSetupOptions): Promise<RunSetupResult
     // BUG-017: Pass context for run.complete event on SIGTERM
     runId: options.runId,
     feature: options.feature,
+    featureDir: options.featureDir,
     getStartTime: () => options.startTime,
     getTotalStories: options.getTotalStories,
     getStoriesCompleted: options.getStoriesCompleted,
@@ -173,12 +176,14 @@ export async function setupRun(options: RunSetupOptions): Promise<RunSetupResult
 
     // Log run start
     const routingMode = config.routing.llm?.mode ?? "hybrid";
-    logger?.info("run.start", `Starting feature: ${feature}`, {
+    logger?.info("run.start", `Starting feature: ${feature} [nax ${NAX_BUILD_INFO}]`, {
       runId,
       feature,
       workdir,
       dryRun,
       routingMode,
+      naxVersion: NAX_VERSION,
+      naxCommit: NAX_COMMIT,
     });
 
     // Fire on-start hook

package/src/execution/runner.ts

@@ -110,6 +110,7 @@ export async function run(options: RunOptions): Promise<RunResult> {
     config,
     hooks,
     feature,
+    featureDir,
     dryRun,
     statusFile,
     logFilePath,
@@ -307,6 +308,13 @@ export async function run(options: RunOptions): Promise<RunResult> {
 
     const { durationMs, runCompletedAt, finalCounts } = completionResult;
 
+    // ── Write feature-level status (SFC-002) ────────────────────────────────
+    if (featureDir) {
+      const finalStatus = isComplete(prd) ? "completed" : "failed";
+      statusWriter.setRunStatus(finalStatus);
+      await statusWriter.writeFeatureStatus(featureDir, totalCost, iterations);
+    }
+
     // ── Output run footer in headless mode ─────────────────────────────────
     if (headless && formatterMode !== "json") {
       const { outputRunFooter } = await import("./lifecycle/headless-formatter");

package/src/execution/status-writer.ts

@@ -6,6 +6,7 @@
  * write failure counter. Provides atomic status file writes via writeStatusFile.
  */
 
+import { join } from "node:path";
 import type { NaxConfig } from "../config";
 import { getSafeLogger } from "../logger";
 import type { PRD } from "../prd";
@@ -136,4 +137,45 @@ export class StatusWriter {
       });
     }
   }
+
+  /**
+   * Write the current status snapshot to feature-level status.json file.
+   *
+   * Called on run completion, failure, or crash to persist the final state
+   * to <featureDir>/status.json. Uses the same NaxStatusFile schema as
+   * the project-level status file.
+   *
+   * No-ops if _prd has not been set.
+   * On failure, logs a warning/error but does not throw (non-fatal).
+   *
+   * @param featureDir - Feature directory (e.g., nax/features/auth-system)
+   * @param totalCost - Accumulated cost at this write point
+   * @param iterations - Loop iteration count at this write point
+   * @param overrides  - Optional partial snapshot overrides (spread last)
+   */
+  async writeFeatureStatus(
+    featureDir: string,
+    totalCost: number,
+    iterations: number,
+    overrides: Partial<RunStateSnapshot> = {},
+  ): Promise<void> {
+    if (!this._prd) return;
+    const safeLogger = getSafeLogger();
+    const featureStatusPath = join(featureDir, "status.json");
+
+    try {
+      const base = this.getSnapshot(totalCost, iterations);
+      if (!base) {
+        throw new Error("Failed to get snapshot");
+      }
+      const state: RunStateSnapshot = { ...base, ...overrides };
+      await writeStatusFile(featureStatusPath, buildStatusSnapshot(state));
+      safeLogger?.debug("status-file", "Feature status written", { path: featureStatusPath });
+    } catch (err) {
+      safeLogger?.warn("status-file", "Failed to write feature status file (non-fatal)", {
+        path: featureStatusPath,
+        error: (err as Error).message,
+      });
+    }
+  }
 }

package/src/version.ts

@@ -0,0 +1,23 @@
+/**
+ * Version and build info for nax.
+ *
+ * GIT_COMMIT is injected at build time via --define in the bun build script.
+ * When running from source (bun run dev), it falls back to "dev".
+ */
+
+import pkg from "../package.json";
+
+declare const GIT_COMMIT: string;
+
+export const NAX_VERSION: string = pkg.version;
+
+/** Short git commit hash, injected at build time. Falls back to "dev" from source. */
+export const NAX_COMMIT: string = (() => {
+  try {
+    return GIT_COMMIT ?? "dev";
+  } catch {
+    return "dev";
+  }
+})();
+
+export const NAX_BUILD_INFO = `v${NAX_VERSION} (${NAX_COMMIT})`;

package/test/e2e/plan-analyze-run.test.ts

@@ -402,6 +402,7 @@ describe("E2E: plan → analyze → run workflow", () => {
       featureDir,
       dryRun: false,
       useBatch: true, // Enable batching
+      statusFile: join(testDir, "nax", "status.json"),
       skipPrecheck: true, // Skip precheck for E2E test (no git repo in temp dir)
     });
 
@@ -479,6 +480,7 @@ describe("E2E: plan → analyze → run workflow", () => {
       feature: "simple-task",
       featureDir,
       dryRun: false,
+      statusFile: join(testDir, "nax", "status.json"),
       skipPrecheck: true, // Skip precheck for E2E test (no git repo in temp dir)
     });
 
@@ -560,6 +562,7 @@ describe("E2E: plan → analyze → run workflow", () => {
       feature: "fail-task",
       featureDir,
       dryRun: false,
+      statusFile: join(testDir, "nax", "status.json"),
       skipPrecheck: true, // Skip precheck for E2E test (no git repo in temp dir)
     });
 
@@ -623,6 +626,7 @@ describe("E2E: plan → analyze → run workflow", () => {
       feature: "rate-limit-task",
       featureDir,
       dryRun: false,
+      statusFile: join(testDir, "nax", "status.json"),
       skipPrecheck: true, // Skip precheck for E2E test (no git repo in temp dir)
     });
 
@@ -729,6 +733,7 @@ describe("E2E: plan → analyze → run workflow", () => {
       featureDir,
       dryRun: false,
       useBatch: true,
+      statusFile: join(testDir, "nax", "status.json"),
       skipPrecheck: true, // Skip precheck for E2E test (no git repo in temp dir)
     });
 

package/test/integration/cli/cli-diagnose.test.ts

@@ -102,7 +102,9 @@ async function createStatusFile(dir: string, feature: string, overrides: Partial
     ...overrides,
   };
 
-  await Bun.write(join(dir, ".nax-status.json"), JSON.stringify(status, null, 2));
+  // Ensure nax directory exists
+  mkdirSync(join(dir, "nax"), { recursive: true });
+  await Bun.write(join(dir, "nax", "status.json"), JSON.stringify(status, null, 2));
 }
 
 /**