@nathapp/nax 0.18.1

package/nax/features/precheck/progress.txt

@@ -0,0 +1,15 @@
+[2026-02-27T11:20:44.967Z] US-001 — FAILED — Precheck types and check implementations — All tiers exhausted
+[2026-02-27T11:22:41.995Z] US-005 — FAILED — Config-driven review commands replacing hardcoded lint — All tiers exhausted
+[2026-02-27T11:24:08.156Z] US-006 — FAILED — PRD auto-default and router tags fix — All tiers exhausted
+[2026-02-27T12:12:00.514Z] US-001 — FAILED — Precheck types and check implementations — All tiers exhausted
+[2026-02-27T15:30:00.000Z] US-003 — PASSED — CLI nax precheck command with --json flag — Implementation complete
+
+Implementation summary:
+- Created src/commands/precheck.ts with precheckCommand()
+- Registered command in bin/nax.ts with -f, -d, and --json flags
+- Uses resolveProject() for directory resolution (same as status/logs)
+- Calls runPrecheck() orchestrator from US-002
+- Returns proper exit codes: 0=pass, 1=blocker, 2=invalid PRD
+- 7 integration tests in test/integration/cli-precheck.test.ts
+- All acceptance criteria verified
+[2026-02-27T14:00:33.162Z] US-003 — FAILED — CLI nax precheck command with --json flag — All tiers exhausted

package/nax/features/structured-logging/prd.json

@@ -0,0 +1,199 @@
+{
+  "project": "nax",
+  "feature": "structured-logging",
+  "branchName": "feat/structured-logging",
+  "createdAt": "2026-02-27T05:50:00Z",
+  "updatedAt": "2026-02-27T08:42:37.832Z",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Project resolver with CWD and -d flag support",
+      "description": "Create src/commands/common.ts with resolveProject(options) function. Resolution order: 1) -d flag path, 2) CWD if it contains nax/ directory, 3) Error with helpful message. Validate: nax/ exists, nax/config.json exists. If -f flag given, validate nax/features/<name>/ exists. Return resolved {projectDir, configPath, featureDir?}. This is shared by status, logs, and future CLI commands.",
+      "acceptanceCriteria": [
+        "resolveProject() returns projectDir when CWD has nax/ directory",
+        "resolveProject({dir:\"/path\"}) uses explicit directory",
+        "Throws descriptive error when no nax/ directory found",
+        "Validates nax/config.json exists in resolved directory",
+        "When feature specified, validates nax/features/<name>/ exists",
+        "Error message lists available features when feature not found",
+        "Works with both relative and absolute -d paths"
+      ],
+      "dependencies": [],
+      "tags": [
+        "cli",
+        "resolver"
+      ],
+      "status": "passed",
+      "attempts": 2,
+      "priorErrors": [
+        "Attempt 1 failed with model tier: balanced",
+        "Attempt 2 failed with model tier: balanced"
+      ],
+      "escalations": []
+    },
+    {
+      "id": "US-002",
+      "title": "Human-friendly logging formatter with verbosity levels",
+      "description": "Create src/logging/formatter.ts and src/logging/types.ts. Transform JSONL entries into human-readable output with emoji indicators. Support 4 modes: quiet, normal, verbose, json. Include run header, story progress with tree-style output, stage results with emoji, retry indicators, run summary footer.",
+      "acceptanceCriteria": [
+        "formatLogEntry renders story start with title, complexity, tier",
+        "formatLogEntry renders stage results with appropriate emoji",
+        "formatRunSummary renders pass/fail/duration/cost stats",
+        "quiet mode only shows pass/fail + summary",
+        "verbose mode includes routing, tokens, context files",
+        "json mode passes through raw JSONL",
+        "Timestamps formatted in local timezone HH:MM:SS"
+      ],
+      "dependencies": [],
+      "tags": [
+        "logging",
+        "formatter"
+      ],
+      "status": "passed",
+      "attempts": 0,
+      "priorErrors": [],
+      "escalations": []
+    },
+    {
+      "id": "US-003",
+      "title": "status.json writer for live run state",
+      "description": "Create src/logging/status-writer.ts. Maintain status.json at nax/features/<feature>/status.json during runs. Write on: run start (runId, feature, totalStories, pid), story start (currentStory), story complete (status/duration/cost/commit), run end (completed/failed + totals). Atomic writes via tmp+rename.",
+      "acceptanceCriteria": [
+        "status.json created at run start with runId, feature, startedAt, pid, status=running",
+        "Updates currentStory on story begin",
+        "Updates story entry on completion",
+        "Updates totals after each story",
+        "Status changes to completed/failed at run end",
+        "Atomic writes prevent corruption",
+        "PID included for crash detection"
+      ],
+      "dependencies": [],
+      "tags": [
+        "logging",
+        "state"
+      ],
+      "status": "passed",
+      "attempts": 1,
+      "priorErrors": [
+        "Attempt 1 failed with model tier: balanced"
+      ],
+      "escalations": [],
+      "passes": true
+    },
+    {
+      "id": "US-004",
+      "title": "nax status command with active run detection",
+      "description": "Create src/commands/status.ts, register in CLI. Uses resolveProject(). Show feature table (done/failed/pending, last run, cost). Detect active run via status.json+PID. Detect crash via status.json+dead PID. Support -f for single feature.",
+      "acceptanceCriteria": [
+        "Shows table of all features with counts and last run",
+        "Detailed single-feature view with story table",
+        "Active run detected via PID alive check",
+        "Crashed run shows warning with recovery hints",
+        "No status.json shows No runs yet",
+        "Uses resolveProject() for resolution",
+        "Registered as CLI subcommand"
+      ],
+      "dependencies": [
+        "US-001",
+        "US-003"
+      ],
+      "tags": [
+        "cli",
+        "status"
+      ],
+      "status": "passed",
+      "attempts": 0,
+      "priorErrors": [],
+      "escalations": [],
+      "passes": true
+    },
+    {
+      "id": "US-005",
+      "title": "nax logs command with filtering and follow mode",
+      "description": "Create src/commands/logs.ts, register in CLI. Uses resolveProject(). Supports: default (latest run formatted), --follow (tail -f), --story (filter), --level (filter), --list (run table), --run (specific run), --json (raw). Uses formatter from US-002.",
+      "acceptanceCriteria": [
+        "Shows latest run logs formatted",
+        "--follow streams new entries real-time",
+        "--story filters to one story",
+        "--level filters by severity",
+        "--list shows runs table",
+        "--run selects specific run",
+        "--json outputs raw JSONL",
+        "Filters combinable",
+        "Uses resolveProject()"
+      ],
+      "dependencies": [
+        "US-001",
+        "US-002"
+      ],
+      "tags": [
+        "cli",
+        "logs"
+      ],
+      "status": "passed",
+      "attempts": 1,
+      "priorErrors": [],
+      "escalations": [],
+      "passes": true
+    },
+    {
+      "id": "US-006",
+      "title": "Integrate formatter into headless runner",
+      "description": "Modify src/execution/runner.ts to use formatter for headless stdout instead of raw JSONL. Default=normal. Add --quiet/--verbose/--json flags to nax run. Wire status-writer into run loop. JSONL still written to disk. Integrate status.json updates at lifecycle points.",
+      "acceptanceCriteria": [
+        "Headless stdout shows formatted output by default",
+        "JSONL still written to disk (unchanged)",
+        "--json flag restores raw JSONL stdout",
+        "--quiet and --verbose flags work",
+        "status.json written throughout lifecycle",
+        "Run header with version, feature, count, path",
+        "Run footer with summary stats"
+      ],
+      "dependencies": [
+        "US-002",
+        "US-003"
+      ],
+      "tags": [
+        "runner",
+        "integration"
+      ],
+      "status": "passed",
+      "attempts": 0,
+      "priorErrors": [],
+      "escalations": [],
+      "passes": true
+    },
+    {
+      "id": "US-007",
+      "title": "Crash recovery with signal handlers heartbeat and exit summary",
+      "description": "Add SIGTERM/SIGINT/SIGHUP handlers and uncaught exception handlers. On signal: write fatal JSONL + update status.json to crashed + exit. During agent execution: heartbeat every 60s. On normal exit: write exit summary entry.",
+      "acceptanceCriteria": [
+        "Signal handlers write fatal log with signal name",
+        "Signal handlers update status.json to crashed",
+        "Uncaught exceptions write fatal log with stack",
+        "Heartbeat every 60s during agent execution",
+        "Normal exit writes summary entry",
+        "Signal handlers exit cleanly",
+        "Heartbeat timer cleaned up on story completion"
+      ],
+      "dependencies": [
+        "US-003"
+      ],
+      "tags": [
+        "crash-recovery",
+        "signals"
+      ],
+      "status": "passed",
+      "attempts": 1,
+      "priorErrors": [
+        "Attempt 1 failed with model tier: balanced"
+      ],
+      "escalations": [],
+      "passes": true
+    }
+  ],
+  "analyzeConfig": {
+    "maxStories": 15,
+    "granularity": "medium"
+  }
+}

package/nax/features/unlock/prd.json

@@ -0,0 +1,36 @@
+{
+  "feature": "unlock",
+  "version": "1.0.0",
+  "project": "nax",
+  "branchName": "feat/unlock-command",
+  "description": "Implement `nax unlock` CLI command to safely release a stale execution lock (nax.lock) without requiring manual filesystem access.",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "nax unlock command releases stale lock safely",
+      "description": "Add a `nax unlock` CLI command to bin/nax.ts and implement its logic in src/commands/unlock.ts.\n\nExisting patterns to follow:\n- Look at src/commands/precheck.ts for a complete command example (imports, structure, Commander wiring)\n- Look at src/execution/lock.ts for acquireLock/releaseLock/isProcessAlive logic\n- Look at test/unit/commands/ for existing unit test examples (e.g. test/unit/commands/precheck.test.ts)\n- Tests go in: test/unit/commands/unlock.test.ts\n- Test runner: `bun test --no-coverage test/unit/commands/unlock.test.ts`\n\nThe command must:\n- Read nax.lock and verify the holding process is actually dead before removing\n- Refuse to unlock if the lock-holding process is still alive (active run)\n- Print the lock state (PID, age, alive/dead) before acting\n- Accept `--force` flag to skip the liveness check and remove unconditionally\n- Accept `-d <dir>` / `--dir <dir>` flag to target a specific project directory (defaults to cwd)\n- Exit 0 on success, non-zero on failure\n- Export an `unlockCommand` function and wire into bin/nax.ts program",
+      "acceptanceCriteria": [
+        "AC1: `nax unlock` with no lock file prints 'No lock file found' and exits 0",
+        "AC2: `nax unlock` when lock PID is alive prints error 'nax is still running (PID <n>). Use --force to override.' and exits 1 without deleting lock",
+        "AC3: `nax unlock` when lock PID is dead prints lock info (PID, age in minutes) then removes nax.lock and exits 0",
+        "AC4: `nax unlock --force` removes nax.lock unconditionally regardless of process state and exits 0",
+        "AC5: `nax unlock -d <path>` targets the specified directory (not cwd)",
+        "AC6: Unit tests in test/unit/commands/unlock.test.ts cover all four scenarios (no lock, alive, dead, force)"
+      ],
+      "complexity": "simple",
+      "status": "paused",
+      "contextFiles": [
+        "src/commands/precheck.ts",
+        "src/execution/lock.ts",
+        "bin/nax.ts"
+      ],
+      "attempts": 1,
+      "priorErrors": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 1
+    }
+  ],
+  "updatedAt": "2026-03-01T09:04:03.679Z"
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@nathapp/nax",
+  "version": "0.18.1",
+  "description": "AI Coding Agent Orchestrator \u2014 loops until done",
+  "type": "module",
+  "bin": {
+    "nax": "./bin/nax.ts"
+  },
+  "scripts": {
+    "dev": "bun run bin/nax.ts",
+    "build": "bun build bin/nax.ts --outdir dist --target bun",
+    "typecheck": "bun x tsc --noEmit",
+    "lint": "bun x biome check src/ bin/",
+    "test": "NAX_SKIP_PRECHECK=1 bun test test/ --timeout=60000",
+    "test:watch": "bun test --watch",
+    "test:unit": "bun test ./test/unit/ --timeout=60000",
+    "test:integration": "bun test ./test/integration/ --timeout=60000",
+    "test:ui": "bun test ./test/ui/ --timeout=60000"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.74.0",
+    "@types/react": "^19.2.14",
+    "chalk": "^5.6.2",
+    "commander": "^13.1.0",
+    "ink": "^6.7.0",
+    "ink-spinner": "^5.0.0",
+    "ink-testing-library": "^4.0.0",
+    "node-pty": "^1.1.0",
+    "react": "^19.2.4",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/bun": "^1.2.4",
+    "react-devtools-core": "^7.0.1",
+    "typescript": "^5.7.3"
+  },
+  "license": "MIT",
+  "author": "William Khoo",
+  "keywords": [
+    "ai",
+    "agent",
+    "orchestrator",
+    "tdd",
+    "coding"
+  ]
+}

package/src/acceptance/fix-generator.ts

@@ -0,0 +1,348 @@
+/**
+ * Fix Story Generator
+ *
+ * Generates fix stories from failed acceptance criteria.
+ * Maps failed ACs to related stories and creates targeted fix descriptions.
+ */
+
+import type { AgentAdapter } from "../agents/types";
+import type { ModelDef } from "../config/schema";
+import { getLogger } from "../logger";
+import type { PRD, UserStory } from "../prd/types";
+
+/**
+ * A fix story generated from a failed acceptance criterion.
+ *
+ * Fix stories are appended to the PRD and executed through the normal pipeline.
+ *
+ * @example
+ * ```ts
+ * const fixStory: FixStory = {
+ *   id: "US-FIX-001",
+ *   title: "Fix: AC-2 TTL expiry timing",
+ *   failedAC: "AC-2",
+ *   testOutput: "Expected undefined, got 'value'",
+ *   relatedStories: ["US-002"],
+ *   description: "Update TTL implementation to properly expire entries...",
+ * };
+ * ```
+ */
+export interface FixStory {
+  /** Story ID (e.g., "US-FIX-001") */
+  id: string;
+  /** Story title */
+  title: string;
+  /** Failed AC identifier (e.g., "AC-2") */
+  failedAC: string;
+  /** Test output showing actual vs expected */
+  testOutput: string;
+  /** Original stories that built this functionality */
+  relatedStories: string[];
+  /** LLM-generated fix description */
+  description: string;
+}
+
+/**
+ * Options for generating fix stories.
+ *
+ * @example
+ * ```ts
+ * const options: GenerateFixStoriesOptions = {
+ *   failedACs: ["AC-2", "AC-5"],
+ *   testOutput: "...",
+ *   prd: loadedPRD,
+ *   specContent: "# Feature...",
+ *   workdir: "/project",
+ *   modelDef: { provider: "anthropic", model: "claude-sonnet-4-5" },
+ * };
+ * ```
+ */
+export interface GenerateFixStoriesOptions {
+  /** Failed AC identifiers */
+  failedACs: string[];
+  /** Full test output from bun test */
+  testOutput: string;
+  /** Current PRD with all stories */
+  prd: PRD;
+  /** Original spec.md content */
+  specContent: string;
+  /** Working directory */
+  workdir: string;
+  /** Model definition for LLM call */
+  modelDef: ModelDef;
+}
+
+/**
+ * Map failed ACs to related stories.
+ *
+ * Uses heuristics to find which stories likely implemented the failed AC:
+ * 1. Stories with matching AC in acceptanceCriteria
+ * 2. Stories with similar keywords in description
+ * 3. Recently completed stories (if no better match)
+ *
+ * @param failedAC - Failed AC identifier (e.g., "AC-2")
+ * @param prd - Current PRD
+ * @returns Array of related story IDs
+ *
+ * @example
+ * ```ts
+ * const related = findRelatedStories("AC-2", prd);
+ * // Returns: ["US-002", "US-005"]
+ * ```
+ */
+export function findRelatedStories(failedAC: string, prd: PRD): string[] {
+  const relatedStoryIds: string[] = [];
+
+  // Strategy 1: Find stories with this AC in their acceptanceCriteria
+  for (const story of prd.userStories) {
+    for (const ac of story.acceptanceCriteria) {
+      if (ac.includes(failedAC)) {
+        relatedStoryIds.push(story.id);
+        break;
+      }
+    }
+  }
+
+  // If we found stories with matching AC, return those
+  if (relatedStoryIds.length > 0) {
+    return relatedStoryIds;
+  }
+
+  // Strategy 2: Return all passed stories (fallback)
+  // The LLM will figure out which code is relevant
+  const passedStories = prd.userStories.filter((s) => s.status === "passed").map((s) => s.id);
+
+  return passedStories.slice(0, 5); // Limit to 5 most recent
+}
+
+/**
+ * Build LLM prompt for generating a fix story.
+ *
+ * @param failedAC - Failed AC identifier
+ * @param acText - Original AC text from spec
+ * @param testOutput - Test failure output
+ * @param relatedStories - Related story IDs
+ * @param prd - Current PRD
+ * @returns Formatted prompt string
+ */
+export function buildFixPrompt(
+  failedAC: string,
+  acText: string,
+  testOutput: string,
+  relatedStories: string[],
+  prd: PRD,
+): string {
+  const relatedStoriesText = relatedStories
+    .map((id) => {
+      const story = prd.userStories.find((s) => s.id === id);
+      if (!story) return "";
+      return `${story.id}: ${story.title}\n  ${story.description}`;
+    })
+    .filter(Boolean)
+    .join("\n\n");
+
+  return `You are a debugging expert. A feature acceptance test has failed.
+
+FAILED ACCEPTANCE CRITERION:
+${failedAC}: ${acText}
+
+TEST FAILURE OUTPUT:
+${testOutput}
+
+RELATED STORIES (implemented this functionality):
+${relatedStoriesText}
+
+Your task: Generate a fix story description that will make the acceptance test pass.
+
+Requirements:
+1. Analyze the test failure to understand the root cause
+2. Identify what needs to change in the code
+3. Write a clear, actionable fix description (2-4 sentences)
+4. Focus on the specific issue, not general improvements
+5. Reference the relevant story IDs if needed
+
+Respond with ONLY the fix description (no JSON, no markdown, just the description text).`;
+}
+
+/**
+ * Generate fix stories from failed acceptance criteria.
+ *
+ * For each failed AC:
+ * 1. Find related stories
+ * 2. Build LLM prompt with context
+ * 3. Generate fix description
+ * 4. Create FixStory object
+ *
+ * @param adapter - Agent adapter for LLM calls
+ * @param options - Generation options
+ * @returns Array of generated fix stories
+ *
+ * @example
+ * ```ts
+ * const adapter = new ClaudeCodeAdapter();
+ * const fixStories = await generateFixStories(adapter, {
+ *   failedACs: ["AC-2", "AC-5"],
+ *   testOutput: "...",
+ *   prd: loadedPRD,
+ *   specContent: "...",
+ *   workdir: "/project",
+ *   modelDef: { provider: "anthropic", model: "claude-sonnet-4-5" },
+ * });
+ *
+ * // Append to PRD
+ * prd.userStories.push(...fixStories.map(convertToUserStory));
+ * ```
+ */
+export async function generateFixStories(
+  adapter: AgentAdapter,
+  options: GenerateFixStoriesOptions,
+): Promise<FixStory[]> {
+  const { failedACs, testOutput, prd, specContent, workdir, modelDef } = options;
+
+  const fixStories: FixStory[] = [];
+
+  // Parse spec to get AC text
+  const acTextMap = parseACTextFromSpec(specContent);
+
+  const logger = getLogger();
+  for (let i = 0; i < failedACs.length; i++) {
+    const failedAC = failedACs[i];
+    const acText = acTextMap[failedAC] || "No description available";
+
+    logger.info("acceptance", "Generating fix for failed AC", { failedAC });
+
+    // Find related stories
+    const relatedStories = findRelatedStories(failedAC, prd);
+
+    if (relatedStories.length === 0) {
+      logger.warn("acceptance", "⚠ No related stories found for failed AC — skipping", { failedAC });
+      continue;
+    }
+
+    // Build prompt
+    const prompt = buildFixPrompt(failedAC, acText, testOutput, relatedStories, prd);
+
+    try {
+      // Call agent to generate fix description
+      const cmd = [adapter.binary, "--model", modelDef.model, "--dangerously-skip-permissions", "-p", prompt];
+
+      const proc = Bun.spawn(cmd, {
+        cwd: workdir,
+        stdout: "pipe",
+        stderr: "pipe",
+        env: {
+          ...process.env,
+          ...(modelDef.env || {}),
+        },
+      });
+
+      const exitCode = await proc.exited;
+      const stdout = await new Response(proc.stdout).text();
+      const stderr = await new Response(proc.stderr).text();
+
+      if (exitCode !== 0) {
+        logger.warn("acceptance", "⚠ Agent fix generation failed", { failedAC, stderr });
+        // Use fallback description
+        fixStories.push({
+          id: `US-FIX-${String(i + 1).padStart(3, "0")}`,
+          title: `Fix: ${failedAC}`,
+          failedAC,
+          testOutput,
+          relatedStories,
+          description: `Fix the implementation to make ${failedAC} pass. Related stories: ${relatedStories.join(", ")}.`,
+        });
+        continue;
+      }
+
+      // Extract fix description
+      const fixDescription = stdout.trim();
+
+      fixStories.push({
+        id: `US-FIX-${String(i + 1).padStart(3, "0")}`,
+        title: `Fix: ${failedAC} — ${acText.slice(0, 50)}`,
+        failedAC,
+        testOutput,
+        relatedStories,
+        description: fixDescription,
+      });
+
+      logger.info("acceptance", "✓ Generated fix story", { storyId: fixStories[fixStories.length - 1].id });
+    } catch (error) {
+      logger.warn("acceptance", "⚠ Error generating fix", {
+        failedAC,
+        error: (error as Error).message,
+      });
+      // Use fallback
+      fixStories.push({
+        id: `US-FIX-${String(i + 1).padStart(3, "0")}`,
+        title: `Fix: ${failedAC}`,
+        failedAC,
+        testOutput,
+        relatedStories,
+        description: `Fix the implementation to make ${failedAC} pass. Related stories: ${relatedStories.join(", ")}.`,
+      });
+    }
+  }
+
+  return fixStories;
+}
+
+/**
+ * Parse AC text from spec.md content.
+ *
+ * Extracts AC-N lines and maps them to their text descriptions.
+ *
+ * @param specContent - Full spec.md content
+ * @returns Map of AC ID to text (e.g., { "AC-2": "set(key, value, ttl)..." })
+ *
+ * @example
+ * ```ts
+ * const spec = "- AC-1: handles empty input\n- AC-2: TTL expiry";
+ * const map = parseACTextFromSpec(spec);
+ * // Returns: { "AC-1": "handles empty input", "AC-2": "TTL expiry" }
+ * ```
+ */
+export function parseACTextFromSpec(specContent: string): Record<string, string> {
+  const map: Record<string, string> = {};
+  const lines = specContent.split("\n");
+
+  for (const line of lines) {
+    const acMatch = line.match(/^\s*-?\s*(?:\[.\])?\s*(AC-\d+):\s*(.+)$/i);
+    if (acMatch) {
+      const id = acMatch[1].toUpperCase();
+      const text = acMatch[2].trim();
+      map[id] = text;
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Convert a FixStory to a UserStory for PRD insertion.
+ *
+ * @param fixStory - Fix story to convert
+ * @returns UserStory object ready for PRD
+ *
+ * @example
+ * ```ts
+ * const fixStory: FixStory = { id: "US-FIX-001", ... };
+ * const userStory = convertFixStoryToUserStory(fixStory);
+ * prd.userStories.push(userStory);
+ * ```
+ */
+export function convertFixStoryToUserStory(fixStory: FixStory): UserStory {
+  return {
+    id: fixStory.id,
+    title: fixStory.title,
+    description: fixStory.description,
+    acceptanceCriteria: [`Fix ${fixStory.failedAC}`],
+    tags: ["fix", "acceptance-failure"],
+    dependencies: fixStory.relatedStories,
+    status: "pending",
+    passes: false,
+    escalations: [],
+    attempts: 0,
+    contextFiles: [],
+  };
+}