@nathapp/nax 0.18.1

package/docs/20260218-adr003-port-plan.md

@@ -0,0 +1,151 @@
+# Fix Plan: ADR-003 Robust Orchestration Feedback Loop — Port to @nathapp/nax
+**Date:** 2026-02-18
+**Branch:** feat/adr-003-verification
+
+## Background
+ADR-003 was prototyped in @arvorco/relentless but the real product is @nathapp/nax v0.5.0.
+This plan ports the safety infrastructure, adapting to nax's existing architecture.
+
+## Phase 1: Config Schema Updates
+### Fix 1: Per-tier attempt config (replaces flat maxAttempts)
+**File:** `src/config/schema.ts`
+**Impact:** Root cause of 20-iteration stall — same model retried endlessly
+**Change:**
+- Replace `tierOrder: z.array(ModelTierSchema)` (string[]) with `tierOrder: z.array(z.object({ tier: z.string().min(1), attempts: z.number().int().min(1).max(20) }))`
+- Remove `maxAttempts` from escalation config (calculated from sum of tier attempts)
+- Keep `maxIterations` as a hard safety cap, default to sum of tier attempts
+- Add `verificationTimeoutSeconds` to execution config (default 300, min 1, max 3600)
+- Add `sessionTimeoutSeconds` to execution config (rename from any existing timeout if present)
+
+### Fix 2: Quality config extensions
+**File:** `src/config/schema.ts`
+**Impact:** Enables all verification features
+**Change:**
+- Extend existing `QualityConfig` with:
+  - `forceExit: z.boolean().default(false)`
+  - `detectOpenHandles: z.boolean().default(true)`
+  - `detectOpenHandlesRetries: z.number().int().min(0).max(5).default(1)`
+  - `gracePeriodMs: z.number().int().min(500).max(30000).default(5000)`
+  - `drainTimeoutMs: z.number().int().min(0).max(10000).default(2000)`
+  - `shell: z.string().default("/bin/sh")`
+  - `stripEnvVars: z.array(z.string()).default(["CLAUDECODE", "REPL_ID", "AGENT"])`
+  - `environmentalEscalationDivisor: z.number().min(1).max(10).default(2)`
+- Update `DEFAULT_CONFIG` with new defaults
+- Update `NaxConfig` interface
+
+**Commit:** `feat(config): add ADR-003 tier-aware escalation and quality verification config`
+
+## Phase 2: Verification Module (new file)
+### Fix 3: Create verification.ts
+**File:** `src/execution/verification.ts` (NEW)
+**Impact:** Core safety infrastructure — prevents zombie processes and stall loops
+**Change:**
+- Port from Relentless `src/execution/verification.ts`, adapting imports to nax:
+  - `verifyAssets()` — pre-flight file check
+  - `executeWithTimeout()` — hard timeout with process group kill (SIGTERM→grace→SIGKILL)
+  - `drainWithDeadline()` — Bun stream workaround
+  - `parseTestOutput()` — detect pass/fail counts from output
+  - `getEnvironmentalEscalationThreshold()` — early escalation for env failures
+  - `normalizeEnvironment()` — strip AI env vars
+  - `buildTestCommand()` — append --detectOpenHandles/--forceExit based on retry state
+  - `runVerification()` — integrated flow combining all above
+- Export from `src/execution/index.ts`
+
+**Commit:** `feat(execution): add ADR-003 verification module with timeout, process group kill, and smart exit-code analysis`
+
+## Phase 3: PRD Types Update
+### Fix 4: Add blocked status
+**File:** `src/prd/types.ts` (or wherever story status is defined)
+**Impact:** Enables skip-and-continue for blocked stories
+**Change:**
+- Add `"blocked"` to story status union type
+- Add `isStalled()` helper — returns true when all remaining stories are blocked or depend on blocked
+- Add `markStoryAsBlocked()` helper
+
+**Commit:** `feat(prd): add blocked status and stall detection helpers`
+
+## Phase 4: Runner Integration
+### Fix 5: Wire tier-aware escalation into runner loop
+**File:** `src/execution/runner.ts`
+**Impact:** Replaces flat iteration loop with tier-aware escalation
+**Change:**
+- Track `currentTierIndex` and `iterationWithinTier` per story
+- Escalate when `iterationWithinTier >= currentTier.attempts`
+- Use config `tierOrder` (new object format) instead of string array
+- Calculate max iterations from sum of all tier attempts (replace hardcoded `config.execution.maxIterations`)
+- Update `escalateTier()` call to use new tier config format
+
+### Fix 6: Wire runVerification() post-agent
+**File:** `src/execution/runner.ts`
+**Impact:** Adds test verification after each agent iteration
+**Change:**
+- After agent completes, call `runVerification()` if `config.quality.commands.test` is set
+- Pass quality config (forceExit, detectOpenHandles, etc.) through
+- Track `timeoutRetryCount` per story for diagnostic retry escalation
+- On ENVIRONMENTAL_FAILURE: append diagnostic context to story progress
+- On TIMEOUT: don't count toward tier escalation
+- On ASSET_CHECK_FAILED: append missing file list to progress
+
+### Fix 7: Wire stall detection
+**File:** `src/execution/runner.ts`
+**Impact:** Prevents infinite loops when all stories are blocked
+**Change:**
+- After each iteration, check `isStalled()`
+- If stalled, generate human halt summary and break loop
+- Mark dependent stories as blocked when their dependencies fail
+
+**Commit:** `feat(execution): wire ADR-003 tier escalation, verification, and stall detection into runner`
+
+## Phase 5: Escalation Module Update
+### Fix 8: Update escalation for new tier format
+**File:** `src/execution/escalation.ts`
+**Impact:** Existing escalation logic works with string[], needs to handle object[]
+**Change:**
+- Update `escalateTier()` to accept `{tier, attempts}[]` format
+- Remove hardcoded fallback switch statement (no backward compat needed)
+
+**Commit:** `refactor(execution): update escalation for ADR-003 tier config format`
+
+## Phase 6: Tests
+### Fix 9: Add verification tests
+**File:** `test/execution/verification.test.ts` (NEW)
+**Tests:**
+- `verifyAssets()` — missing files, empty list, all present
+- `executeWithTimeout()` — success, timeout, SIGTERM/SIGKILL, process cleanup
+- `parseTestOutput()` — bun/jest formats, environmental failure detection
+- `normalizeEnvironment()` — strips AI vars, preserves others
+- `buildTestCommand()` — forceExit, detectOpenHandles, retry cap, pipe insertion
+- `runVerification()` — integrated flow, US-001 scenario
+
+### Fix 10: Update config tests
+**File:** `test/config/schema.test.ts` (existing)
+**Tests:**
+- New tierOrder format validation (object[], reject string[])
+- Quality config extensions
+- verificationTimeoutSeconds bounds
+
+### Fix 11: Update escalation tests
+**File:** `test/execution/escalation.test.ts` (existing or new)
+**Tests:**
+- New tier format escalation
+- Edge cases (single tier, unknown tier)
+
+**Commit:** `test: add ADR-003 verification, config, and escalation tests`
+
+## Test Strategy
+- Mode: test-after
+- Test-after targets: verification.ts, schema.ts, escalation.ts, runner.ts integration
+- Run: `bun test`
+
+## Breaking Changes
+- `escalation.tierOrder` changes from `string[]` to `{tier, attempts}[]` — [BREAKING but no published consumers]
+- `escalation.maxAttempts` removed — [BREAKING but no published consumers]
+- William confirmed: "Remove backward compatibility — no published version yet"
+
+## Commits Summary
+1. `feat(config): add ADR-003 tier-aware escalation and quality verification config`
+2. `feat(execution): add ADR-003 verification module`
+3. `feat(prd): add blocked status and stall detection helpers`
+4. `feat(execution): wire ADR-003 into runner loop`
+5. `refactor(execution): update escalation for ADR-003 tier config format`
+6. `test: add ADR-003 verification, config, and escalation tests`

package/docs/20260218-review-adr003-verification.md

@@ -0,0 +1,175 @@
+# Deep Code Review: @nathapp/nax — ADR-003 Verification Port
+
+**Date:** 2025-06-18
+**Reviewer:** Subrina (AI)
+**Branch:** `feat/adr-003-verification` vs `master`
+**Scope:** +1,352 / -5,529 lines across 47 files (net -4,177 — major TUI removal + verification addition)
+**Tests:** 103 pass, 0 fail (7 test files)
+
+---
+
+## Overall Grade: B+ (82/100)
+
+Solid implementation of ADR-003 with well-structured verification module, good config extensibility, and proper process management (zombie prevention, Bun stream workaround). The TUI removal is clean. Main concerns: runner.ts growing too large, a few logic gaps in the verification→runner wiring, and some missing edge case handling.
+
+| Dimension | Score | Notes |
+|:---|:---|:---|
+| **Security** | 17/20 | Good env normalization, process group kill. Minor: shell injection surface |
+| **Reliability** | 16/20 | Timeout/zombie prevention solid. Some edge cases in verification wiring |
+| **API Design** | 17/20 | Clean interfaces, extensible tiers, good separation of concerns |
+| **Code Quality** | 15/20 | verification.ts excellent. runner.ts too large (350+ lines). Some duplication |
+| **Best Practices** | 17/20 | Config-driven, well-documented JSDoc, Zod validation |
+
+---
+
+## Findings
+
+### 🔴 CRITICAL
+
+_None._
+
+### 🟡 HIGH
+
+#### BUG-1: Verification passes story through pipeline, then reverts on verification failure — double state mutation
+**Severity:** HIGH | **Category:** Bug
+```typescript
+// runner.ts ~L213: Pipeline marks story as "passed" in completionStage
+if (pipelineResult.success) {
+  // ...
+  // L225: Then verification runs AFTER and may revert:
+  prd.userStories = prd.userStories.map(s =>
+    s.id === story.id
+      ? { ...s, status: "pending" as const, passes: false }
+      : s
+  );
+```
+**Risk:** The pipeline's `completionStage` already marks the story as `passed` and saves the PRD. Then verification fails and reverts it. This creates a race condition if anything reads the PRD between those two saves. More importantly, `storiesCompleted` is incremented based on `verificationPassed` but the pipeline already fired `on-story-pass` hooks in the completion stage — so hooks see a story as passed that later fails verification.
+**Fix:** Either (a) skip the completion stage when `quality.commands.test` is configured (verify first, then complete), or (b) run verification BEFORE the completion stage by adding it as a pipeline stage.
+
+#### BUG-2: `parseTestOutput` regex may misparse multi-test-suite output
+**Severity:** HIGH | **Category:** Bug
+```typescript
+// verification.ts: Only matches FIRST occurrence
+const patterns = [
+  /(\d+)\s+pass(?:ed)?(?:,\s+|\s+)(\d+)\s+fail/i,
+  // ...
+];
+// If output has "5 pass, 0 fail" from one suite followed by "3 pass, 2 fail" from another,
+// only the first match (5 pass, 0 fail) is captured — misses the actual failures.
+```
+**Risk:** False ENVIRONMENTAL_FAILURE classification when only the first suite output matches. The orchestrator would treat it as "all tests pass but exit != 0" when in reality some tests failed.
+**Fix:** Match ALL occurrences and sum pass/fail counts, or match only the final summary line (most frameworks print a total summary last).
+
+### 🟡 MEDIUM
+
+#### ENH-1: runner.ts is 350+ lines and growing — verification wiring should be extracted
+**Severity:** MEDIUM | **Category:** Enhancement
+**Risk:** Maintenance burden. The runner now handles pipeline orchestration, verification, stall detection, acceptance retries, and metrics. Single Responsibility violated.
+**Fix:** Extract verification wiring into a `postAgentVerification()` function in a separate module (e.g., `src/execution/verify-runner.ts`).
+
+#### BUG-3: `executeWithTimeout` — `proc.exited` resolved value discarded, re-awaited
+**Severity:** MEDIUM | **Category:** Bug
+```typescript
+// verification.ts L148-150
+await Promise.race([processPromise, timeoutPromise]);
+// ...
+const exitCode = await proc.exited; // ← awaits again (works but wasteful)
+```
+**Risk:** No functional bug — `proc.exited` returns the same promise. But the first `await` result is discarded, and the second `await` is redundant. Minor clarity issue.
+**Fix:** `const exitCode = await processPromise;` after the race confirms no timeout.
+
+#### SEC-1: Shell command passed as string to `Bun.spawn([shell, "-c", command])`
+**Severity:** MEDIUM | **Category:** Security
+```typescript
+const proc = Bun.spawn([shell, "-c", command], { ... });
+```
+**Risk:** If `command` is ever constructed from user/PRD input (e.g., a story-specific test command), this is a shell injection vector. Currently `command` comes from `config.quality.commands.test` which is operator-controlled, so low practical risk.
+**Fix:** Document this as `@design` — the command is config-driven, not user-driven. Add a note in schema.ts JSDoc.
+
+#### TYPE-1: `getNextStory` doesn't filter `blocked` in all paths
+**Severity:** MEDIUM | **Category:** Type Safety
+```typescript
+// prd/index.ts: getNextStory filters blocked correctly
+s.status !== "blocked" && s.status !== "failed"
+// But runner.ts batch plan filters differently:
+storiesToExecute = batch.stories.filter(s => !s.passes && s.status !== "skipped");
+// Missing: && s.status !== "blocked" && s.status !== "failed"
+```
+**Risk:** Batch execution could pick up blocked/failed stories from a stale batch plan.
+**Fix:** Add `s.status !== "blocked" && s.status !== "failed"` to the batch story filter.
+
+#### PERF-1: `dynamic import()` inside hot loop
+**Severity:** MEDIUM | **Category:** Performance
+```typescript
+// runner.ts ~L253
+const analysis = await import("./verification").then(m =>
+  m.parseTestOutput(verificationResult.output!, 0)
+);
+```
+**Risk:** Dynamic import on every successful verification. The module is already imported at the top of the file (`import { runVerification } from "./verification"`).
+**Fix:** Use the already-imported module: `import { runVerification, parseTestOutput } from "./verification"` and call directly.
+
+### 🟢 LOW
+
+#### STYLE-1: `environmentalEscalationDivisor` defined in config but never used in runner
+**Severity:** LOW | **Category:** Style / Dead Config
+The config field `quality.environmentalEscalationDivisor` is validated and defaulted in schema.ts, and `getEnvironmentalEscalationThreshold()` accepts a divisor parameter, but the runner never calls `getEnvironmentalEscalationThreshold()`. Environmental failures just increment attempts like normal failures.
+**Fix:** Wire up the early escalation logic in the runner, or remove the config field until it's needed.
+
+#### STYLE-2: `isComplete` doesn't account for `blocked` status
+**Severity:** LOW | **Category:** Style
+```typescript
+export function isComplete(prd: PRD): boolean {
+  return prd.userStories.every(s => s.passes || s.status === "passed" || s.status === "skipped");
+}
+```
+A PRD with all stories blocked will never be "complete" (correct) but also won't trigger stall detection until the `isStalled` check runs. This is fine — just document that `isComplete` means "all pass/skip" not "no more work possible".
+
+#### ENH-2: Missing test for `runVerification()` integration
+**Severity:** LOW | **Category:** Enhancement
+The verification module has unit tests for individual functions, but no test covers the full `runVerification()` flow (asset check → build command → normalize env → execute → analyze). Consider a focused integration test.
+
+#### STYLE-3: TUI deletion is clean but leaves orphaned type in `pipeline/types.ts`
+**Severity:** LOW | **Category:** Style
+```typescript
+// pipeline/types.ts still references StageAction which had 'cost' removed
+// Check if any StageAction-related types have dangling references
+```
+
+---
+
+## Priority Fix Order
+
+| Priority | ID | Effort | Description |
+|:---|:---|:---|:---|
+| P0 | BUG-1 | M | Verification runs after completion stage — double state mutation + stale hooks |
+| P0 | BUG-2 | S | parseTestOutput only matches first regex occurrence — may miss failures |
+| P1 | TYPE-1 | S | Batch story filter missing blocked/failed status check |
+| P1 | PERF-1 | S | Dynamic import of already-imported module in hot path |
+| P2 | ENH-1 | M | Extract verification wiring from runner.ts |
+| P2 | STYLE-1 | S | Wire up environmentalEscalationDivisor or remove |
+| P3 | BUG-3 | S | Redundant proc.exited await |
+| P3 | SEC-1 | S | Document shell command as @design (config-driven) |
+| P3 | ENH-2 | M | Integration test for runVerification() |
+| P3 | STYLE-2 | S | Document isComplete semantics |
+
+---
+
+## Summary
+
+The ADR-003 port is **well-aligned with everything discussed today**. All key decisions are implemented:
+
+✅ Per-tier `TierConfig[]` with configurable attempts
+✅ Extensible tier names (`z.string()` not enum)
+✅ Separate `verificationTimeoutSeconds` vs `sessionTimeoutSeconds`
+✅ TIMEOUT doesn't count toward escalation (`countsTowardEscalation: false`)
+✅ Process group kill (`process.kill(-pid)`) + SIGTERM→grace→SIGKILL
+✅ `drainWithDeadline()` Bun stream workaround
+✅ `buildTestCommand()` with --detectOpenHandles escalation + --forceExit fallback
+✅ All config values extracted (zero hardcoded)
+✅ `blocked` status + `isStalled()` + `generateHumanHaltSummary()`
+✅ Environment normalization (strip AI-optimized vars)
+✅ Backward compat removed (no `maxAttempts`, no string-array `tierOrder`)
+✅ TUI cleanly removed
+
+The P0 items (BUG-1 double state mutation, BUG-2 regex parsing) should be addressed before dogfooding. Everything else can be iterative.

package/docs/20260219-fix-plan-bug16-19.md

@@ -0,0 +1,79 @@
+# Fix Plan: BUG-16 to BUG-19 (Dogfood Run C)
+**Date:** 2026-02-19
+**Branch:** fix/bug-16-19-routing-escalation
+**Repo:** nax (on Mac01)
+
+## Phase 1: BUG-19 — Fix complexity→tier routing mismatch
+
+### Fix 1: Re-derive modelTier after overriding cached complexity
+**File:** `src/execution/runner.ts` (lines ~195-204 and ~218-225)
+**Root Cause:** `routeTask()` derives `modelTier` from keyword-classified complexity (e.g. "medium" for 5 ACs), then cached `story.routing.complexity` ("simple") overwrites display but NOT modelTier.
+**Change:**
+After `routing.complexity = story.routing.complexity`, add:
+```typescript
+routing.modelTier = config.autoMode.complexityRouting[routing.complexity] ?? "balanced";
+```
+Apply in BOTH places where cached routing overrides happen (batch mode ~line 203 and single-story mode ~line 225).
+
+### Fix 2: Export complexityToModelTier or inline the mapping
+**File:** `src/routing/router.ts`
+**Change:** Just inline `config.autoMode.complexityRouting[complexity]` in runner.ts (simpler, no new export needed).
+
+**Commit:** `fix: re-derive modelTier from cached complexity (BUG-19)`
+
+## Phase 2: BUG-17 + BUG-16 — Fix escalation and per-story capping
+
+### Fix 3: Add pre-iteration tier escalation check
+**File:** `src/execution/runner.ts`
+**Root Cause:** Escalation only happens in `case "escalate"` handler, but post-verify failures (ASSET_CHECK) revert story to pending without returning "escalate". Story loops at same tier forever.
+**Change:** At the start of each iteration, BEFORE spawning the agent, check if `story.attempts` has exceeded the current tier budget. If so, escalate `story.routing.modelTier` in the PRD and save. After all tiers exhausted, mark story as FAILED instead of retrying.
+
+Key logic:
+- Get currentTier from story.routing.modelTier (or first tier in tierOrder)
+- Get tierCfg via getTierConfig(currentTier, tierOrder)
+- If story.attempts >= tierCfg.attempts → escalate to next tier
+- If no next tier → markStoryFailed, fireHook on-story-fail, continue to next story
+- This also fixes BUG-16 because stories can no longer loop indefinitely
+
+**Commit:** `fix: pre-iteration tier escalation and per-story failure cap (BUG-16, BUG-17)`
+
+## Phase 3: BUG-18 — Surface ASSET_CHECK errors prominently in prompt
+
+### Fix 4: Format ASSET_CHECK errors as mandatory instructions
+**File:** `src/pipeline/stages/prompt.ts` (or wherever the agent prompt is built)
+**Root Cause:** ASSET_CHECK errors in story.priorErrors are shown as generic "Prior Errors" — agent ignores them.
+**Change:** Parse priorErrors for entries starting with `ASSET_CHECK_FAILED:`. Extract missing file names and format as:
+```
+MANDATORY: You MUST create these files (previous attempts failed because they were missing):
+- src/finder.ts
+- test/finder.test.ts
+Do NOT use alternative filenames. These exact paths are required.
+```
+Place this BEFORE the story description in the prompt.
+
+**Commit:** `fix: surface ASSET_CHECK errors as mandatory instructions in prompt (BUG-18)`
+
+## Phase 4: Tests
+
+### Test 5: Add routing tests
+**File:** `test/routing.test.ts` (new)
+- Test classifyComplexity with various AC counts (4, 5, 9 ACs)
+- Test complexityToModelTier mapping respects config
+- Test that cached routing complexity correctly re-derives modelTier
+
+### Test 6: Add escalation integration tests
+**File:** `test/runner.test.ts` (append)
+- Test pre-iteration escalation: story with attempts >= tier budget escalates before agent spawn
+- Test all-tiers-exhausted: story marked FAILED, not retried
+- Test ASSET_CHECK failure increments attempts and triggers escalation
+
+### Test 7: Add prompt formatting test
+**File:** `test/prompt.test.ts` (new or append)
+- Test ASSET_CHECK priorErrors rendered as mandatory file creation instructions
+- Test non-ASSET_CHECK priorErrors rendered normally
+
+**Commit:** `test: add tests for BUG-16 to BUG-19 fixes`
+
+## Test Strategy
+- Mode: test-after
+- Run: `bun test` after each phase

package/docs/20260219-fix-plan-bug20-22.md

@@ -0,0 +1,114 @@
+# Fix Plan: BUG-20, BUG-21, BUG-22 — TDD Orchestrator Fixes
+**Date:** 2026-02-19
+**Branch:** `fix/bug-20-22-tdd-orchestrator`
+**Base:** `fix/bug-16-19-routing-escalation` (has prior fixes)
+
+## Phase 1: BUG-22 — Post-TDD test verification (false positive fix)
+
+### Fix: Add independent test run after all 3 TDD sessions complete
+
+**File:** `src/tdd/orchestrator.ts`
+**Impact:** Without fix, verifier sessions that fix issues are treated as failures, causing false pauses.
+
+**Change:**
+After all 3 sessions complete (line ~387), before checking `sessions.every(s => s.success)`:
+1. Run the project's test command (`config.quality.commands.test`) independently via `executeWithTimeout()`
+2. If tests pass → override `allSuccessful = true` regardless of individual session exit codes
+3. If tests fail → keep existing behavior (flag for human review)
+4. Log: `[tdd] Post-TDD verification: X tests pass` or `[tdd] Post-TDD verification failed, flagging for review`
+
+```typescript
+// After sessions complete, verify final state independently
+const testCmd = config.quality?.commands?.test ?? "bun test";
+const postVerify = await executeWithTimeout(testCmd, config.quality?.verificationTimeoutSeconds ?? 120);
+const testsActuallyPass = postVerify.success && postVerify.exitCode === 0;
+
+if (testsActuallyPass && !allSuccessful) {
+  console.log(chalk.dim("   ℹ️  Sessions had non-zero exits but tests pass — treating as success"));
+  allSuccessful = true;
+  needsHumanReview = false;
+  reviewReason = undefined;
+}
+```
+
+**Import needed:** `executeWithTimeout` from `../execution/verification`
+
+## Phase 2: BUG-20 — Detect empty test-writer sessions
+
+### Fix: Check that test-writer session actually created test files
+
+**File:** `src/tdd/orchestrator.ts`
+**Impact:** Without fix, test-writer sessions that create no test files (e.g., create `requirements.md` instead) pass isolation check vacuously.
+
+**Change:**
+After Session 1 (test-writer) isolation check passes, add a file creation check:
+1. Get `session1.filesChanged` (already tracked)
+2. Filter for files matching test patterns: `*.test.ts`, `*.spec.ts`, `test/**/*`
+3. If zero test files created → fail with reason "Test writer created no test files"
+
+```typescript
+// After session1 isolation passes
+const testFilePatterns = /\.(test|spec)\.(ts|js|tsx|jsx)$/;
+const testFilesCreated = session1.filesChanged.filter(f => testFilePatterns.test(f));
+if (testFilesCreated.length === 0) {
+  needsHumanReview = true;
+  reviewReason = "Test writer session created no test files";
+  console.log(chalk.yellow(`\n⚠️  ${reviewReason}`));
+  // Return early — no point running implementer without tests
+  return { success: false, sessions: [session1], needsHumanReview, reviewReason, totalCost: session1.estimatedCost };
+}
+```
+
+## Phase 3: BUG-21 — Process tree cleanup after agent failure
+
+### Fix: Kill process tree when TDD session agent exits non-zero
+
+**File:** `src/tdd/orchestrator.ts` (in `runTddSession()`)
+**Impact:** Without fix, Claude Code child processes (like `bun test | tail -5`) become zombies at 100% CPU.
+
+**Change:**
+In `runTddSession()`, after `agent.runSession()` returns (especially on failure), add process tree cleanup:
+
+```typescript
+// After agent.runSession() returns
+const result = await agent.runSession(/* ... */);
+
+// Clean up any orphaned child processes from the agent
+if (!result.success && result.pid) {
+  await cleanupProcessTree(result.pid);
+}
+```
+
+Add utility function (can be in orchestrator or a new `src/tdd/cleanup.ts`):
+
+```typescript
+async function cleanupProcessTree(pid: number): Promise<void> {
+  try {
+    // Find all child processes
+    const pgid = await getPgid(pid);
+    if (pgid) {
+      process.kill(-pgid, "SIGTERM");
+      await new Promise(r => setTimeout(r, 3000));
+      try { process.kill(-pgid, "SIGKILL"); } catch {}
+    }
+  } catch {
+    // Process already dead — that's fine
+  }
+}
+```
+
+**Note:** Check if `AgentAdapter.runSession()` exposes the child PID. If not, need to also modify `src/agents/claude-adapter.ts` to return `pid` in the result.
+
+## Test Strategy
+- Mode: test-after
+- Run existing tests after each phase to verify no regressions
+- Add unit tests for BUG-20 (test file detection) and BUG-22 (post-TDD verify override)
+- BUG-21 is harder to unit test (process management) — verify manually
+
+## Commits
+- Phase 1: `fix: post-TDD test verification to prevent false positive pauses (BUG-22)`
+- Phase 2: `fix: detect empty test-writer sessions in TDD orchestrator (BUG-20)`
+- Phase 3: `fix: cleanup orphaned child processes after TDD session failure (BUG-21)`
+
+---
+*Created 2026-02-19*

package/docs/20260219-plan-llm-routing.md

@@ -0,0 +1,116 @@
+# Implementation Plan: LLM-Enhanced Routing (v0.8)
+
+**Date:** 2026-02-19
+**Branch:** `feat/v0.8-llm-routing`
+**Spec:** `docs/v0.8-llm-routing.md`
+
+## Test Strategy
+- Mode: test-after
+- Test-after targets: `test/routing/llm-strategy.test.ts`, `test/routing/chain.test.ts`
+
+## Phase 1: Config Schema + LLM Routing Types
+
+### Fix 1.1: Add `LlmRoutingConfig` to schema
+**File:** `src/config/schema.ts`
+**Change:** Add interface and extend `RoutingConfig`:
+```typescript
+export interface LlmRoutingConfig {
+  model?: string;           // tier for routing call (default: "fast")
+  fallbackToKeywords?: boolean; // default: true
+  maxInputTokens?: number;  // default: 2000
+  cacheDecisions?: boolean; // default: true
+  batchMode?: boolean;      // default: true
+  timeoutMs?: number;       // default: 15000
+}
+```
+Add `llm?: LlmRoutingConfig` to `RoutingConfig`.
+
+### Fix 1.2: Add defaults
+**File:** `src/config/defaults.ts`
+**Change:** Add LLM routing defaults in `DEFAULT_CONFIG.routing.llm`.
+
+### Fix 1.3: Add Zod validation
+**File:** `src/config/schema.ts` (wherever Zod schemas are)
+**Change:** Add LlmRoutingConfigSchema, wire into RoutingConfigSchema.
+
+**Commit:** `feat(config): add LLM routing config schema and defaults`
+
+## Phase 2: Make Strategy Chain Async
+
+### Fix 2.1: Update `RoutingStrategy` interface
+**File:** `src/routing/strategy.ts`
+**Change:** `route()` return type → `RoutingDecision | null | Promise<RoutingDecision | null>`
+
+### Fix 2.2: Make `StrategyChain.route()` async
+**File:** `src/routing/chain.ts`
+**Change:** `route()` → `async route()`, `await` each strategy result. Return type `Promise<RoutingDecision>`.
+
+### Fix 2.3: Update chain callers
+**File:** `src/routing/router.ts` (and any other callers)
+**Change:** Add `await` where `chain.route()` is called (should already be in async context).
+
+### Fix 2.4: Update existing tests
+**File:** `test/routing/chain.test.ts`
+**Change:** Add `await` to `chain.route()` calls. Mark test callbacks as `async`.
+
+**Commit:** `refactor(routing): make strategy chain async for LLM support`
+
+## Phase 3: Implement LLM Strategy
+
+### Fix 3.1: Implement `llmStrategy`
+**File:** `src/routing/strategies/llm.ts`
+**Change:** Full implementation:
+- `buildRoutingPrompt(story, config)` → formats the system prompt from spec
+- `buildBatchPrompt(stories, config)` → formats batch prompt for multiple stories
+- `callLlm(modelTier, prompt, config)` → spawns `claude -p "<prompt>" --model <model>` with timeout
+- `parseRoutingResponse(output)` → JSON.parse + validate fields
+- `cachedDecisions: Map<string, RoutingDecision>` module-level cache
+- `clearCache()` export for testing
+- Main `route()`: check cache → build prompt → call LLM → parse → cache → return
+- Error handling: catch all, log warn, return null (falls through to keyword)
+
+### Fix 3.2: Add batch routing function
+**File:** `src/routing/strategies/llm.ts`
+**Change:** Export `routeBatch(stories, context)` that sends all stories in one LLM call, returns `Map<string, RoutingDecision>`. Called from router before individual routing.
+
+### Fix 3.3: Wire batch routing into runner
+**File:** `src/routing/router.ts`
+**Change:** If `config.routing.strategy === "llm" && config.routing.llm?.batchMode`, call `routeBatch()` before the story loop to pre-populate the cache.
+
+### Fix 3.4: Write tests
+**File:** `test/routing/llm-strategy.test.ts` (new)
+**Change:** Tests for:
+- `buildRoutingPrompt` output format
+- `parseRoutingResponse` happy path (valid JSON)
+- `parseRoutingResponse` error paths (invalid JSON, missing fields, unknown values)
+- `route()` with mocked `Bun.spawn` returning valid JSON
+- `route()` with timeout → returns null
+- `route()` with parse error → returns null
+- Cache hit (second call returns cached decision)
+- `clearCache()` resets cache
+- Batch prompt format
+
+**Commit:** `feat(routing): implement LLM-enhanced routing with batch support`
+
+## Phase 4: Integration + Logging
+
+### Fix 4.1: Add routing log output
+**File:** `src/routing/strategies/llm.ts`
+**Change:** `console.log` with chalk for each routing decision:
+```
+[routing] LLM classified US-008 as simple/fast/test-after: "Barrel export file"
+```
+
+### Fix 4.2: Run full test suite
+**Change:** `bun test` — ensure all existing tests still pass with async chain.
+
+**Commit:** `feat(routing): add LLM routing logging and integration tests`
+
+## Breaking Changes
+None — `RoutingStrategy.route()` now accepts sync OR async return (union type). Existing sync strategies continue to work. `StrategyChain.route()` becomes async but callers already use `await`.
+
+## Commits Summary
+1. `feat(config): add LLM routing config schema and defaults`
+2. `refactor(routing): make strategy chain async for LLM support`
+3. `feat(routing): implement LLM-enhanced routing with batch support`
+4. `feat(routing): add LLM routing logging and integration tests`