@nathapp/nax 0.18.1

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

@@ -0,0 +1,412 @@
+/**
+ * Acceptance Test: nax diagnose CLI
+ *
+ * Validates that the nax diagnose command meets all acceptance criteria.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { diagnoseCommand } from "../../../src/cli/diagnose";
+import type { PRD } from "../../../src/prd";
+import { savePRD } from "../../../src/prd";
+import type { NaxStatusFile } from "../../../src/execution/status-file";
+
+// Test fixture directory
+let testDir: string;
+
+beforeEach(() => {
+	// Create unique test directory
+	testDir = join(tmpdir(), `nax-diagnose-acceptance-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+	mkdirSync(testDir, { recursive: true });
+	mkdirSync(join(testDir, "nax", "features"), { recursive: true });
+});
+
+afterEach(() => {
+	// Clean up test directory
+	if (existsSync(testDir)) {
+		rmSync(testDir, { recursive: true, force: true });
+	}
+});
+
+/**
+ * Create a minimal PRD fixture
+ */
+function createPRD(feature: string, stories: Array<Partial<PRD["userStories"][0]>>): PRD {
+	return {
+		project: "test-project",
+		feature,
+		branchName: "feature/test",
+		createdAt: "2026-01-01T00:00:00Z",
+		updatedAt: "2026-01-01T00:00:00Z",
+		userStories: stories.map((s, i) => ({
+			id: s.id ?? `US-${String(i + 1).padStart(3, "0")}`,
+			title: s.title ?? "Test Story",
+			description: s.description ?? "Test description",
+			acceptanceCriteria: s.acceptanceCriteria ?? [],
+			tags: s.tags ?? [],
+			dependencies: s.dependencies ?? [],
+			status: s.status ?? "pending",
+			passes: s.passes ?? false,
+			escalations: s.escalations ?? [],
+			attempts: s.attempts ?? 0,
+			priorErrors: s.priorErrors ?? [],
+			...s,
+		})),
+	};
+}
+
+/**
+ * Create a status.json fixture
+ */
+async function createStatusFile(
+	dir: string,
+	feature: string,
+	overrides: Partial<NaxStatusFile> = {},
+): Promise<void> {
+	const status: NaxStatusFile = {
+		version: 1,
+		run: {
+			id: "run-001",
+			feature,
+			startedAt: "2026-01-01T10:00:00Z",
+			status: "running",
+			dryRun: false,
+			pid: process.pid,
+			...overrides.run,
+		},
+		progress: {
+			total: 3,
+			passed: 1,
+			failed: 1,
+			paused: 0,
+			blocked: 0,
+			pending: 1,
+			...overrides.progress,
+		},
+		cost: {
+			spent: 0.05,
+			limit: null,
+			...overrides.cost,
+		},
+		current: null,
+		iterations: 1,
+		updatedAt: "2026-01-01T10:30:00Z",
+		durationMs: 1800000,
+		...overrides,
+	};
+
+	await Bun.write(join(dir, ".nax-status.json"), JSON.stringify(status, null, 2));
+}
+
+/**
+ * Create a lock file fixture
+ */
+async function createLockFile(dir: string, pid: number): Promise<void> {
+	await Bun.write(
+		join(dir, "nax.lock"),
+		JSON.stringify({
+			pid,
+			timestamp: Date.now(),
+		}),
+	);
+}
+
+// ============================================================================
+// AC1: Basic diagnosis with all 5 sections
+// ============================================================================
+
+describe("AC1: nax diagnose reads last run and prints all 5 sections", () => {
+	test("prints Run Summary, Story Breakdown, Failure Analysis, Lock Check, Recommendations", async () => {
+		const feature = "test-feature";
+		const featureDir = join(testDir, "nax", "features", feature);
+		mkdirSync(featureDir, { recursive: true });
+
+		const prd = createPRD(feature, [
+			{ id: "US-001", title: "Passed Story", status: "passed", passes: true, attempts: 1 },
+			{
+				id: "US-002",
+				title: "Failed Story",
+				status: "failed",
+				passes: false,
+				attempts: 3,
+				priorErrors: ["tests-failing", "tests-failing"],
+			},
+			{ id: "US-003", title: "Pending Story", status: "pending", passes: false, attempts: 0 },
+		]);
+
+		await savePRD(prd, join(featureDir, "prd.json"));
+		await createStatusFile(testDir, feature);
+
+		let output = "";
+		const originalLog = console.log;
+		console.log = (...args: unknown[]) => {
+			output += args.join(" ") + "\n";
+		};
+
+		try {
+			await diagnoseCommand({ feature, workdir: testDir, verbose: true });
+
+			// Verify all sections present
+			expect(output).toContain("Diagnosis Report");
+			expect(output).toContain("Run Summary");
+			expect(output).toContain("Story Breakdown");
+			expect(output).toContain("Failure Analysis");
+			expect(output).toContain("Lock Check");
+			expect(output).toContain("Recommendations");
+
+			// Verify counts
+			expect(output).toContain("Passed:      1");
+			expect(output).toContain("Failed:      1");
+			expect(output).toContain("Pending:     1");
+		} finally {
+			console.log = originalLog;
+		}
+	});
+});
+
+// ============================================================================
+// AC2: Pattern classification for failed stories
+// ============================================================================
+
+describe("AC2: Each failed story shows pattern classification", () => {
+	test("classifies all failure patterns correctly", async () => {
+		const feature = "patterns-feature";
+		const featureDir = join(testDir, "nax", "features", feature);
+		mkdirSync(featureDir, { recursive: true });
+
+		const prd = createPRD(feature, [
+			{
+				id: "US-001",
+				title: "Greenfield Story",
+				status: "failed",
+				failureCategory: "greenfield-no-tests",
+				attempts: 1,
+			},
+			{
+				id: "US-002",
+				title: "Test Mismatch",
+				status: "failed",
+				priorErrors: ["tests-failing", "tests-failing"],
+				attempts: 2,
+			},
+			{
+				id: "US-003",
+				title: "Isolation Violation",
+				status: "failed",
+				failureCategory: "isolation-violation",
+				attempts: 1,
+			},
+		]);
+
+		await savePRD(prd, join(featureDir, "prd.json"));
+
+		let output = "";
+		const originalLog = console.log;
+		console.log = (...args: unknown[]) => {
+			output += args.join(" ") + "\n";
+		};
+
+		try {
+			await diagnoseCommand({ feature, workdir: testDir });
+
+			expect(output).toContain("GREENFIELD_TDD");
+			expect(output).toContain("TEST_MISMATCH");
+			expect(output).toContain("ISOLATION_VIOLATION");
+		} finally {
+			console.log = originalLog;
+		}
+	});
+});
+
+// ============================================================================
+// AC3: Stale lock detection
+// ============================================================================
+
+describe("AC3: Stale nax.lock detection", () => {
+	test("detects stale lock and shows fix command", async () => {
+		const feature = "locked-feature";
+		const featureDir = join(testDir, "nax", "features", feature);
+		mkdirSync(featureDir, { recursive: true });
+
+		const prd = createPRD(feature, [{ id: "US-001", title: "Test Story", status: "pending" }]);
+		await savePRD(prd, join(featureDir, "prd.json"));
+		await createLockFile(testDir, 999999); // Dead PID
+
+		let output = "";
+		const originalLog = console.log;
+		console.log = (...args: unknown[]) => {
+			output += args.join(" ") + "\n";
+		};
+
+		try {
+			await diagnoseCommand({ feature, workdir: testDir });
+
+			expect(output).toContain("Stale lock detected");
+			expect(output).toContain("rm nax.lock");
+		} finally {
+			console.log = originalLog;
+		}
+	});
+});
+
+// ============================================================================
+// AC4: JSON output mode
+// ============================================================================
+
+describe("AC4: --json flag outputs machine-readable JSON", () => {
+	test("outputs valid JSON with all report fields", async () => {
+		const feature = "json-feature";
+		const featureDir = join(testDir, "nax", "features", feature);
+		mkdirSync(featureDir, { recursive: true });
+
+		const prd = createPRD(feature, [
+			{ id: "US-001", title: "Passed Story", status: "passed", passes: true },
+			{ id: "US-002", title: "Failed Story", status: "failed", attempts: 2 },
+		]);
+
+		await savePRD(prd, join(featureDir, "prd.json"));
+
+		let output = "";
+		const originalLog = console.log;
+		console.log = (...args: unknown[]) => {
+			output += args.join(" ") + "\n";
+		};
+
+		try {
+			await diagnoseCommand({ feature, workdir: testDir, json: true });
+
+			const report = JSON.parse(output);
+
+			expect(report).toHaveProperty("runSummary");
+			expect(report).toHaveProperty("storyBreakdown");
+			expect(report).toHaveProperty("failureAnalysis");
+			expect(report).toHaveProperty("lockCheck");
+			expect(report).toHaveProperty("recommendations");
+			expect(report).toHaveProperty("dataSources");
+
+			expect(report.runSummary.storiesPassed).toBe(1);
+			expect(report.runSummary.storiesFailed).toBe(1);
+		} finally {
+			console.log = originalLog;
+		}
+	});
+});
+
+// ============================================================================
+// AC5: Graceful degradation when events.jsonl missing
+// ============================================================================
+
+describe("AC5: Works gracefully when events.jsonl missing", () => {
+	test("uses PRD + git log only and prints note", async () => {
+		const feature = "no-events-feature";
+		const featureDir = join(testDir, "nax", "features", feature);
+		mkdirSync(featureDir, { recursive: true });
+
+		const prd = createPRD(feature, [{ id: "US-001", title: "Test Story", status: "passed", passes: true }]);
+		await savePRD(prd, join(featureDir, "prd.json"));
+
+		let output = "";
+		const originalLog = console.log;
+		console.log = (...args: unknown[]) => {
+			output += args.join(" ") + "\n";
+		};
+
+		try {
+			await diagnoseCommand({ feature, workdir: testDir });
+
+			expect(output).toContain("Diagnosis Report");
+			expect(output).toContain("events.jsonl not found");
+		} finally {
+			console.log = originalLog;
+		}
+	});
+});
+
+// ============================================================================
+// AC6: -f and -d flags for targeting
+// ============================================================================
+
+describe("AC6: -f <feature> and -d <workdir> flags work", () => {
+	test("diagnoses specific feature with -f flag", async () => {
+		const feature = "specific-feature";
+		const featureDir = join(testDir, "nax", "features", feature);
+		mkdirSync(featureDir, { recursive: true });
+
+		const prd = createPRD(feature, [{ id: "US-001", title: "Specific Story", status: "passed", passes: true }]);
+		await savePRD(prd, join(featureDir, "prd.json"));
+
+		let output = "";
+		const originalLog = console.log;
+		console.log = (...args: unknown[]) => {
+			output += args.join(" ") + "\n";
+		};
+
+		try {
+			await diagnoseCommand({ feature, workdir: testDir, verbose: true });
+
+			expect(output).toContain(feature);
+			expect(output).toContain("Specific Story");
+		} finally {
+			console.log = originalLog;
+		}
+	});
+});
+
+// ============================================================================
+// AC7: AUTO_RECOVERED shown as INFO not ERROR
+// ============================================================================
+
+describe("AC7: AUTO_RECOVERED stories shown as INFO", () => {
+	test("displays AUTO_RECOVERED with INFO level, not ERROR", async () => {
+		const feature = "recovered-feature";
+		const featureDir = join(testDir, "nax", "features", feature);
+		mkdirSync(featureDir, { recursive: true });
+
+		const prd = createPRD(feature, [
+			{
+				id: "US-001",
+				title: "Recovered Story",
+				status: "passed",
+				passes: true,
+				priorErrors: ["greenfield-no-tests"],
+				attempts: 2,
+			},
+		]);
+
+		await savePRD(prd, join(featureDir, "prd.json"));
+
+		let output = "";
+		const originalLog = console.log;
+		console.log = (...args: unknown[]) => {
+			output += args.join(" ") + "\n";
+		};
+
+		try {
+			await diagnoseCommand({ feature, workdir: testDir });
+
+			expect(output).toContain("INFO");
+			expect(output).toContain("AUTO_RECOVERED");
+			expect(output).not.toContain("ERROR US-001");
+		} finally {
+			console.log = originalLog;
+		}
+	});
+});
+
+// ============================================================================
+// AC8: TypeScript compiles cleanly
+// ============================================================================
+
+describe("AC8: TypeScript compiles cleanly", () => {
+	test("bun x tsc --noEmit passes", async () => {
+		const result = Bun.spawnSync(["bun", "x", "tsc", "--noEmit"], {
+			cwd: join(__dirname, "../../.."),
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+
+		expect(result.exitCode).toBe(0);
+	}, 60000);
+});

package/nax/features/diagnose/prd.json

@@ -0,0 +1,41 @@
+{
+  "project": "nax",
+  "feature": "diagnose",
+  "branchName": "feat/v0.14.1-diagnose-cli",
+  "createdAt": "2026-02-28T12:00:00Z",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "nax diagnose CLI \u2014 pure pattern-matching diagnosis",
+      "description": "Implement the `nax diagnose` command that reads existing run artifacts (events.jsonl from ~/.nax/events/<project>/, status.json from <workdir>/.nax-status.json, PRD from nax/features/<feature>/prd.json, nax.lock from <workdir>/nax.lock, git log) and produces a structured human-readable diagnosis report. No LLM calls. No agent. Purely deterministic pattern matching.\n\nCOMMAND SIGNATURE:\n  nax diagnose [-f <feature>] [-d <workdir>] [--json] [--verbose]\n\nOUTPUT SECTIONS:\n1. Run Summary \u2014 feature, last run time, status (complete/stalled/failed), stories passed/failed/pending, cost, commits produced\n2. Story Breakdown \u2014 per-story: status, attempts, tier, strategy, pattern detected\n3. Failure Analysis \u2014 for each failed story: pattern name, symptom description, fix suggestion\n4. Lock Check \u2014 is nax.lock present? Is PID alive (process.kill(pid, 0))? Show fix command if stale.\n5. Recommendations \u2014 ordered list of next actions\n\nFAILURE PATTERNS TO DETECT (match in order):\n- GREENFIELD_TDD: failureCategory === greenfield-no-tests in priorErrors or events\n- TEST_MISMATCH: 2+ consecutive tests-failing escalation events for same story\n- ENVIRONMENTAL: precheck-failed event OR blocker in status.json\n- RATE_LIMITED: rateLimited: true in agent session failure events\n- ISOLATION_VIOLATION: failureCategory === isolation-violation\n- MAX_TIERS_EXHAUSTED: story has priorErrors for all configured tiers AND status is failed/paused\n- SESSION_CRASH: session-failure category + no commits for that story in git log\n- STALLED: isStalled flag in status.json OR all pending stories blocked by dependencies\n- LOCK_STALE: nax.lock present + PID not alive\n- AUTO_RECOVERED: story had greenfield-no-tests but status is passed (S5 worked)\n- UNKNOWN: no pattern matched\n\nGRACEFUL DEGRADATION: If events.jsonl is missing, fall back to PRD priorErrors + git log only. Never crash \u2014 always produce partial output with a note about missing data.\n\nFILES TO CREATE:\n- src/cli/diagnose.ts \u2014 main implementation (read artifacts, pattern match, format output)\n- src/commands/diagnose.ts \u2014 thin commander wrapper registering the command\n- Register in bin/nax.ts \u2014 add diagnose command import\n- test/integration/cli-diagnose.test.ts \u2014 integration tests covering all ACs",
+      "acceptanceCriteria": [
+        "AC1: `nax diagnose` reads the last run for the current directory feature and prints human-readable output with all 5 sections (Run Summary, Story Breakdown, Failure Analysis, Lock Check, Recommendations)",
+        "AC2: Each failed story shows a pattern classification from the known patterns list, or UNKNOWN if no match",
+        "AC3: Stale nax.lock (lock present + PID dead) is detected and a fix command shown: rm nax.lock",
+        "AC4: `--json` flag outputs machine-readable JSON containing the same data as human output",
+        "AC5: Works gracefully when events.jsonl is missing \u2014 uses PRD + git log only, prints a note about missing events",
+        "AC6: `-f <feature>` targets a specific feature; `-d <workdir>` sets working directory",
+        "AC7: AUTO_RECOVERED stories (S5 switched strategy, story passed) are shown as INFO not ERROR",
+        "AC8: TypeScript compiles cleanly (bun x tsc --noEmit)"
+      ],
+      "dependencies": [],
+      "tags": [
+        "cli",
+        "medium"
+      ],
+      "status": "passed",
+      "passes": true,
+      "attempts": 1,
+      "escalations": [],
+      "priorErrors": [
+        "Manual accept: verified 8/8 AC tests pass on VPS. Mac01 Bun env issue with git detection in temp dirs during verification."
+      ],
+      "storyPoints": 1
+    }
+  ],
+  "analyzeConfig": {
+    "maxStories": 5,
+    "granularity": "medium"
+  },
+  "updatedAt": "2026-02-28T06:18:08Z"
+}

package/nax/features/orchestration-fixes/prd.json

@@ -0,0 +1,89 @@
+{
+  "project": "nax",
+  "branchName": "feat/v0.18.0-orchestration-fixes",
+  "feature": "orchestration-fixes",
+  "userStories": [
+    {
+      "id": "BUG-021",
+      "title": "Fix misleading Task classified log",
+      "description": "The 'Task classified' log in routing.ts currently logs the raw LLM output even after config/cache overrides are applied. This makes it look like overrides are ignored when they aren't.\n\nFix: Ensure the log reflects the final routing state (ctx.routing) after all overrides and greenfield detection are finished.\n\nAcceptance criteria:\n1. Log shows final testStrategy/complexity/modelTier after all overrides\n2. Existing tests pass",
+      "complexity": "simple",
+      "status": "passed",
+      "attempts": 0,
+      "priorErrors": [
+        "Attempt 1 failed with model tier: fast"
+      ],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "acceptanceCriteria": [],
+      "storyPoints": 1,
+      "routing": {
+        "complexity": "simple",
+        "modelTier": "balanced",
+        "testStrategy": "three-session-tdd-lite",
+        "reasoning": "three-session-tdd-lite: strategy:lite"
+      }
+    },
+    {
+      "id": "BUG-022",
+      "title": "Fix story interleaving in getNextStory()",
+      "description": "When a story fails and escalates, getNextStory() currently round-robins to the next pending story. This wastes iterations by jumping between unrelated tasks.\n\nFix: Update getNextStory() in src/execution/sequential-executor.ts to prioritize retrying the current story until max attempts are reached before moving to the next story.\n\nAcceptance criteria:\n1. If current story is failed but has attempts remaining, it is picked again for retry\n2. Run order: S1-I1 -> S1-I2 (retry) -> S2-I1 (if S1 complete/failed out)\n3. Unit test for getNextStory() behavior",
+      "complexity": "simple",
+      "status": "passed",
+      "attempts": 0,
+      "priorErrors": [
+        "Attempt 1 failed with model tier: fast"
+      ],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "acceptanceCriteria": [],
+      "storyPoints": 1,
+      "routing": {
+        "complexity": "simple",
+        "modelTier": "balanced",
+        "testStrategy": "three-session-tdd-lite",
+        "reasoning": "three-session-tdd-lite: strategy:lite"
+      }
+    },
+    {
+      "id": "BUG-023",
+      "title": "Log exitCode/stderr on agent failure",
+      "description": "Agent session failures currently log 'rateLimited' but hide the actual exit code and stderr. This makes diagnosing silent failures (like 401, 500, or process crashes) difficult.\n\nFix: Audit src/agents/adapters/claude.ts and src/pipeline/stages/execution.ts. Ensure the 'Agent session failed' event includes exitCode and the tail of stderr in its data payload.\n\nAcceptance criteria:\n1. agent.complete event includes exitCode and stderr tail on failure\n2. Logs are machine-readable and don't break JSONL format",
+      "complexity": "simple",
+      "status": "passed",
+      "attempts": 0,
+      "priorErrors": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "acceptanceCriteria": [],
+      "storyPoints": 1
+    },
+    {
+      "id": "BUG-025",
+      "title": "Integrate Interaction Chain into Runner Loop",
+      "description": "The Interaction system is initialized but never called from the core orchestrator. This is a major integration task.\n\nFix:\n1. Add 'human-review' to TriggerName in src/interaction/types.ts and metadata in TRIGGER_METADATA\n2. Pass interactionChain from runner.ts -> executeSequential -> Pipeline\n3. Inject 'interaction' into PipelineContext\n4. Call executeTrigger('human-review', ...) when a story reaches max retries or a critical failure occurs\n5. Verify other triggers (security-review, story-ambiguity) are called at relevant pipeline stages\n\nAcceptance criteria:\n1. interactionChain is accessible in PipelineContext\n2. Story reaching max retries triggers a 'human-review' interaction request\n3. Test with CLI interaction plugin (non-headless)",
+      "complexity": "medium",
+      "status": "failed",
+      "attempts": 1,
+      "priorErrors": [
+        "Attempt 1 failed with model tier: balanced"
+      ],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "acceptanceCriteria": [],
+      "storyPoints": 1,
+      "routing": {
+        "complexity": "complex",
+        "modelTier": "powerful",
+        "testStrategy": "three-session-tdd-lite",
+        "reasoning": "three-session-tdd-lite: security-critical, strategy:lite"
+      },
+      "failureCategory": "session-failure"
+    }
+  ],
+  "updatedAt": "2026-03-02T16:29:51.415Z"
+}

package/nax/features/orchestration-fixes/progress.txt

@@ -0,0 +1 @@
+[2026-03-02T16:29:51.415Z] BUG-025 — FAILED — Integrate Interaction Chain into Runner Loop — Execution failed