@nathapp/nax 0.22.4 → 0.24.0

package/bin/nax.ts

@@ -62,6 +62,7 @@ import { generateCommand } from "../src/cli/generate";
 import { diagnose } from "../src/commands/diagnose";
 import { logsCommand } from "../src/commands/logs";
 import { precheckCommand } from "../src/commands/precheck";
+import { runsCommand } from "../src/commands/runs";
 import { unlockCommand } from "../src/commands/unlock";
 import { DEFAULT_CONFIG, findProjectDir, loadConfig, validateDirectory } from "../src/config";
 import { run } from "../src/execution";
@@ -685,7 +686,7 @@ program
   .option("-s, --story <id>", "Filter to specific story")
   .option("--level <level>", "Filter by log level (debug|info|warn|error)")
   .option("-l, --list", "List all runs in table format", false)
-  .option("-r, --run <timestamp>", "Select specific run by timestamp")
+  .option("-r, --run <runId>", "Select run by run ID from central registry (global)")
   .option("-j, --json", "Output raw JSONL", false)
   .action(async (options) => {
     let workdir: string;
@@ -773,7 +774,24 @@ program
   });
 
 // ── runs ─────────────────────────────────────────────
-const runs = program.command("runs").description("Manage and view run history");
+const runs = program
+  .command("runs")
+  .description("Show all registered runs from the central registry (~/.nax/runs/)")
+  .option("--project <name>", "Filter by project name")
+  .option("--last <N>", "Limit to N most recent runs (default: 20)")
+  .option("--status <status>", "Filter by status (running|completed|failed|crashed)")
+  .action(async (options) => {
+    try {
+      await runsCommand({
+        project: options.project,
+        last: options.last !== undefined ? Number.parseInt(options.last, 10) : undefined,
+        status: options.status,
+      });
+    } catch (err) {
+      console.error(chalk.red(`Error: ${(err as Error).message}`));
+      process.exit(1);
+    }
+  });
 
 runs
   .command("list")

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/central-run-registry/prd.json

@@ -0,0 +1,105 @@
+{
+  "project": "nax",
+  "branchName": "feat/central-run-registry",
+  "feature": "central-run-registry",
+  "version": "0.24.0",
+  "description": "Global run index across all projects. Events file writer for machine-readable lifecycle events, registry subscriber that indexes every run to ~/.nax/runs/, nax runs CLI for cross-project run history, and nax logs --run <runId> for global log resolution.",
+  "userStories": [
+    {
+      "id": "CRR-000",
+      "title": "Events file writer subscriber",
+      "description": "New subscriber: src/pipeline/subscribers/events-writer.ts \u2014 wireEventsWriter(bus, project, feature, runId, workdir). Listens to run:started, story:started, story:completed, story:failed, run:completed, run:paused. Writes one JSON line per event to ~/.nax/events/<project>/events.jsonl (append mode). Each line: {\"ts\": ISO8601, \"event\": string, \"runId\": string, \"feature\": string, \"project\": string, \"storyId\"?: string, \"data\"?: object}. The run:completed event writes an 'on-complete' entry \u2014 the machine-readable signal that nax exited gracefully (fixes watchdog false crash reports). Best-effort: wrap all writes in try/catch, log warnings on failure, never throw or block the pipeline. Create ~/.nax/events/<project>/ on first write via mkdir recursive. Derive project name from path.basename(workdir). Wire in sequential-executor.ts alongside existing wireHooks/wireReporters/wireInteraction calls. Return UnsubscribeFn matching existing subscriber pattern.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "After a run, ~/.nax/events/<project>/events.jsonl exists with JSONL entries",
+        "Each line is valid JSON with ts, event, runId, feature, project fields",
+        "run:completed produces an entry with event=on-complete",
+        "story:started/completed/failed events include storyId",
+        "Write failure does not crash or block the nax run",
+        "Directory is created automatically on first write",
+        "wireEventsWriter is called in sequential-executor.ts",
+        "Returns UnsubscribeFn consistent with wireHooks/wireReporters pattern"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 2
+    },
+    {
+      "id": "CRR-001",
+      "title": "Registry writer subscriber",
+      "description": "New subscriber: src/pipeline/subscribers/registry.ts \u2014 wireRegistry(bus, project, feature, runId, workdir). Listens to run:started. On event, creates ~/.nax/runs/<project>-<feature>-<runId>/meta.json with fields: {runId, project, feature, workdir, statusPath: join(workdir, 'nax/features', feature, 'status.json'), eventsDir: join(workdir, 'nax/features', feature, 'runs'), registeredAt: ISO8601}. meta.json schema exported as MetaJson interface. Written once, never updated. Best-effort: try/catch + warn log, never throw/block. Create ~/.nax/runs/ directory on first call via mkdir recursive. Derive project from path.basename(workdir). Wire in sequential-executor.ts alongside wireEventsWriter. Return UnsubscribeFn.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "After run start, ~/.nax/runs/<project>-<feature>-<runId>/meta.json exists",
+        "meta.json contains runId, project, feature, workdir, statusPath, eventsDir, registeredAt",
+        "statusPath points to <workdir>/nax/features/<feature>/status.json",
+        "eventsDir points to <workdir>/nax/features/<feature>/runs",
+        "MetaJson interface is exported from the module",
+        "Write failure does not crash or block the nax run",
+        "wireRegistry is called in sequential-executor.ts"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 2
+    },
+    {
+      "id": "CRR-002",
+      "title": "nax runs CLI command",
+      "description": "New command: src/commands/runs.ts \u2014 runsCommand(options). Reads all ~/.nax/runs/*/meta.json, resolves each statusPath to read the live NaxStatusFile for current state. Displays a table sorted by registeredAt desc. Columns: RUN ID, PROJECT, FEATURE, STATUS, STORIES (passed/total), DURATION, DATE. Default limit: 20. Options: --project <name> (filter), --last <N> (limit), --status <running|completed|failed|crashed> (filter). If statusPath missing, show status as '[unavailable]'. Register in src/commands/index.ts and wire in bin/nax.ts CLI arg parser (match pattern of existing diagnose/logs/status commands). Use chalk for colored output. Green for completed, red for failed, yellow for running, dim for unavailable.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "nax runs displays a table of all registered runs sorted newest-first",
+        "nax runs --project <name> filters by project name",
+        "nax runs --last <N> limits output to N runs",
+        "nax runs --status <status> filters by run status",
+        "Runs with missing statusPath show '[unavailable]' status gracefully",
+        "Empty registry shows 'No runs found' message",
+        "Command is registered in CLI help output and bin/nax.ts"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [
+        "CRR-001"
+      ],
+      "tags": [],
+      "storyPoints": 3
+    },
+    {
+      "id": "CRR-003",
+      "title": "nax logs --run <runId> global resolution",
+      "description": "Enhance src/commands/logs.ts logsCommand: when --run <runId> is provided, scan ~/.nax/runs/*/meta.json for matching runId (exact or prefix match). Read eventsDir from meta.json, locate the JSONL log file in that directory (newest .jsonl file), then display using existing displayLogs/followLogs functions. Falls back to current behavior (local feature context) when --run is not specified. If runId not found in registry, throw error Run not found in registry: <runId>. If eventsDir or log file missing, show unavailable message. Update LogsOptions interface to accept run?: string. Update bin/nax.ts to pass --run option through.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "nax logs --run <runId> displays logs from the matching run regardless of cwd",
+        "Resolution uses ~/.nax/runs/*/meta.json to find eventsDir path",
+        "Unknown runId shows clear error message",
+        "Missing log files show unavailable message",
+        "Without --run flag, existing local behavior is unchanged",
+        "Partial runId matching works (prefix match on runId field)"
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [
+        "CRR-001"
+      ],
+      "tags": [],
+      "storyPoints": 2
+    }
+  ]
+}

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,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.22.4",
+  "version": "0.24.0",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {
@@ -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/commands/index.ts

@@ -5,4 +5,5 @@
 export { resolveProject, type ResolveProjectOptions, type ResolvedProject } from "./common";
 export { logsCommand, type LogsOptions } from "./logs";
 export { precheckCommand, type PrecheckOptions } from "./precheck";
+export { runsCommand, type RunsOptions } from "./runs";
 export { unlockCommand, type UnlockOptions } from "./unlock";

package/src/commands/logs.ts

@@ -6,13 +6,23 @@
  */
 
 import { existsSync, readdirSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import chalk from "chalk";
 import type { LogEntry, LogLevel } from "../logger/types";
 import { type FormattedEntry, formatLogEntry, formatRunSummary } from "../logging/formatter";
 import type { RunSummary, VerbosityMode } from "../logging/types";
+import type { MetaJson } from "../pipeline/subscribers/registry";
 import { type ResolveProjectOptions, resolveProject } from "./common";
 
+/**
+ * Swappable dependencies for testing (project convention: _deps over mock.module).
+ */
+export const _deps = {
+  getRunsDir: () => process.env.NAX_RUNS_DIR ?? join(homedir(), ".nax", "runs"),
+};
+
 /**
  * Options for logs command
  */
@@ -43,12 +53,84 @@ const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
   error: 3,
 };
 
+/**
+ * Resolve log file path for a runId from the central registry (~/.nax/runs/).
+ *
+ * Scans all ~/.nax/runs/*\/meta.json entries for an exact or prefix match on runId.
+ * Returns the path to the matching run's JSONL file, or null if eventsDir/file is unavailable.
+ * Throws if the runId is not found in the registry at all.
+ *
+ * @param runId - Full or prefix run ID to look up
+ * @returns Absolute path to the JSONL log file, or null if unavailable
+ */
+async function resolveRunFileFromRegistry(runId: string): Promise<string | null> {
+  const runsDir = _deps.getRunsDir();
+
+  let entries: string[];
+  try {
+    entries = await readdir(runsDir);
+  } catch {
+    throw new Error(`Run not found in registry: ${runId}`);
+  }
+
+  let matched: MetaJson | null = null;
+  for (const entry of entries) {
+    const metaPath = join(runsDir, entry, "meta.json");
+    try {
+      const meta: MetaJson = await Bun.file(metaPath).json();
+      if (meta.runId === runId || meta.runId.startsWith(runId)) {
+        matched = meta;
+        break;
+      }
+    } catch {
+      // skip unreadable meta.json entries
+    }
+  }
+
+  if (!matched) {
+    throw new Error(`Run not found in registry: ${runId}`);
+  }
+
+  if (!existsSync(matched.eventsDir)) {
+    console.log(`Log directory unavailable for run: ${runId}`);
+    return null;
+  }
+
+  const files = readdirSync(matched.eventsDir)
+    .filter((f) => f.endsWith(".jsonl") && f !== "latest.jsonl")
+    .sort()
+    .reverse();
+
+  if (files.length === 0) {
+    console.log(`No log files found for run: ${runId}`);
+    return null;
+  }
+
+  // Look for the specific run file by runId, fall back to newest
+  const specificFile = files.find((f) => f === `${matched.runId}.jsonl`);
+  return join(matched.eventsDir, specificFile ?? files[0]);
+}
+
 /**
  * Display logs with filtering and formatting
  *
  * @param options - Command options
  */
 export async function logsCommand(options: LogsOptions): Promise<void> {
+  // When --run <runId> is provided, resolve via central registry
+  if (options.run) {
+    const runFile = await resolveRunFileFromRegistry(options.run);
+    if (!runFile) {
+      return;
+    }
+    if (options.follow) {
+      await followLogs(runFile, options);
+    } else {
+      await displayLogs(runFile, options);
+    }
+    return;
+  }
+
   // Resolve project directory
   const resolved = resolveProject({ dir: options.dir });
   const naxDir = join(resolved.projectDir, "nax");
@@ -77,8 +159,8 @@ export async function logsCommand(options: LogsOptions): Promise<void> {
     return;
   }
 
-  // Determine which run to display
-  const runFile = await selectRunFile(runsDir, options.run);
+  // Determine which run to display (latest by default — --run handled above via registry)
+  const runFile = await selectRunFile(runsDir);
 
   if (!runFile) {
     throw new Error("No runs found for this feature");
@@ -95,9 +177,9 @@ export async function logsCommand(options: LogsOptions): Promise<void> {
 }
 
 /**
- * Select which run file to display
+ * Select which run file to display (always returns the latest run)
  */
-async function selectRunFile(runsDir: string, runTimestamp?: string): Promise<string | null> {
+async function selectRunFile(runsDir: string): Promise<string | null> {
   const files = readdirSync(runsDir)
     .filter((f) => f.endsWith(".jsonl") && f !== "latest.jsonl")
     .sort()
@@ -107,19 +189,7 @@ async function selectRunFile(runsDir: string, runTimestamp?: string): Promise<st
     return null;
   }
 
-  // If no specific run requested, use latest
-  if (!runTimestamp) {
-    return join(runsDir, files[0]);
-  }
-
-  // Find matching run by partial timestamp
-  const matchingFile = files.find((f) => f.startsWith(runTimestamp));
-
-  if (!matchingFile) {
-    throw new Error(`Run not found: ${runTimestamp}`);
-  }
-
-  return join(runsDir, matchingFile);
+  return join(runsDir, files[0]);
 }
 
 /**