@nathapp/nax 0.18.1

package/docs/20260219-review-bug20-22-fixes.md

@@ -0,0 +1,135 @@
+# Post-Fix Code Review: BUG-20, BUG-21, BUG-22
+
+**Date:** 2026-02-19
+**Reviewer:** Subrina (AI)
+**Scope:** `fix/bug-20-22-tdd-orchestrator` branch (3 commits, 7 files)
+**Depth:** Standard (post-fix verification)
+**Files:** 7 (lib: ~170 LOC added, test: ~470 LOC added)
+**Baseline:** 21 new tests, 67 assertions — all passing
+
+---
+
+## Overall Grade: B+ (82/100)
+
+Solid bug fixes with good test coverage and clean separation. The `cleanup.ts` module is well-structured with proper JSDoc and graceful error handling. The orchestrator changes address the root causes correctly. However, there are a few issues around race conditions, missing type narrowing, and a potential security concern in the BUG-22 fix that should be addressed before merge.
+
+---
+
+## Scoring
+
+| Dimension | Score | Notes |
+|:---|:---|:---|
+| Security | 16/20 | `executeWithTimeout` called with config-derived command — acceptable but no sanitization |
+| Reliability | 15/20 | SIGTERM→SIGKILL race window; no PGID validation; `reviewReason` type narrowing |
+| API Design | 18/20 | Clean module boundary; `pid` optional on `AgentResult` is correct |
+| Code Quality | 17/20 | Good JSDoc; test mocking pattern is verbose but thorough |
+| Best Practices | 16/20 | Bun.sleep mock in tests is fragile; `@ts-ignore` used for mocking |
+
+---
+
+## Findings
+
+### 🟡 MEDIUM
+
+#### BUG-1: Race condition in SIGTERM→SIGKILL cleanup
+**Severity:** MEDIUM | **Category:** Bug
+```typescript
+// src/tdd/cleanup.ts:73-76
+process.kill(-pgid, "SIGTERM");
+await Bun.sleep(3000);  // ← Fixed 3s delay
+process.kill(-pgid, "SIGKILL");
+```
+**Risk:** If the process group exits cleanly in <3s and the PGID is reassigned to a new process group (unlikely but possible on busy systems), SIGKILL hits the wrong group. Also, 3s is hardcoded with no configurability.
+**Fix:** Check if processes still exist before SIGKILL:
+```typescript
+const stillAlive = await getPgid(pid);
+if (stillAlive === pgid) {
+  process.kill(-pgid, "SIGKILL");
+}
+```
+
+#### BUG-2: BUG-22 post-verification runs `bun test` without workdir context
+**Severity:** MEDIUM | **Category:** Bug
+```typescript
+// src/tdd/orchestrator.ts:430-432
+const testCmd = config.quality?.commands?.test ?? "bun test";
+const timeoutSeconds = config.quality?.verificationTimeoutSeconds ?? 120;
+const postVerify = await executeWithTimeout(testCmd, timeoutSeconds);
+```
+**Risk:** `executeWithTimeout` may not inherit the correct working directory. If the orchestrator's cwd differs from the project workdir, post-verification runs tests against the wrong codebase or fails with "no tests found."
+**Fix:** Pass `workdir` to `executeWithTimeout`:
+```typescript
+const postVerify = await executeWithTimeout(testCmd, timeoutSeconds, { cwd: workdir });
+```
+*(Verify `executeWithTimeout` accepts cwd option — if not, needs a small change.)*
+
+#### ENH-1: `reviewReason` type could be `undefined | string` but is set via `let`
+**Severity:** MEDIUM | **Category:** Type Safety
+```typescript
+// src/tdd/orchestrator.ts:441
+reviewReason = undefined;  // ← assignment to undefined in success path
+```
+**Risk:** The `reviewReason` variable is declared with `let` higher up. The `undefined` assignment works but the type should be explicit to avoid accidental string checks downstream.
+**Fix:** Declare as `let reviewReason: string | undefined;` if not already.
+
+### 🟢 LOW
+
+#### STYLE-1: `@ts-ignore` comments in tests instead of proper typing
+**Severity:** LOW | **Category:** Style
+```typescript
+// test/tdd-cleanup.test.ts:24
+// @ts-ignore — mocking global
+Bun.spawn = mock((cmd: string[], spawnOpts?: any) => {
+```
+**Risk:** If `Bun.spawn` signature changes, tests won't catch the type mismatch at compile time.
+**Fix:** Consider a wrapper function pattern:
+```typescript
+const mockSpawn = mock((...args: Parameters<typeof Bun.spawn>) => { ... });
+Object.defineProperty(Bun, 'spawn', { value: mockSpawn, writable: true });
+```
+
+#### STYLE-2: Verbose mock setup repeated across tests
+**Severity:** LOW | **Category:** Style
+The `Bun.spawn` mock setup for git commands is duplicated across `tdd-cleanup.test.ts` and `tdd-orchestrator.test.ts` with slightly different patterns.
+**Fix:** Extract a `createGitMock()` helper into a shared test utility (e.g., `test/helpers/git-mock.ts`).
+
+#### ENH-2: `cleanupProcessTree` hardcoded 3s grace period
+**Severity:** LOW | **Category:** Enhancement
+```typescript
+await Bun.sleep(3000);
+```
+**Fix:** Accept optional `gracePeriodMs` parameter with 3000 default:
+```typescript
+export async function cleanupProcessTree(pid: number, gracePeriodMs = 3000): Promise<void> {
+```
+
+#### PERF-1: BUG-20 test file detection uses regex on every file per session
+**Severity:** LOW | **Category:** Performance
+```typescript
+const testFilePatterns = /\.(test|spec)\.(ts|js|tsx|jsx)$/;
+const testFilesCreated = session1.filesChanged.filter((f) => testFilePatterns.test(f));
+```
+**Risk:** Negligible perf impact (typically <50 files), but the regex is recompiled each call.
+**Fix:** Move `testFilePatterns` to module scope as a constant. Minor.
+
+---
+
+## Priority Fix Order
+
+| Priority | ID | Effort | Description |
+|:---|:---|:---|:---|
+| P1 | BUG-2 | S | Pass workdir to post-TDD verification `executeWithTimeout` |
+| P2 | BUG-1 | S | Verify process still alive before SIGKILL |
+| P3 | ENH-1 | S | Explicit type for `reviewReason` |
+| P3 | ENH-2 | S | Configurable grace period in `cleanupProcessTree` |
+| P4 | STYLE-1 | M | Replace `@ts-ignore` with proper mock typing |
+| P4 | STYLE-2 | M | Extract shared git mock helper |
+| P5 | PERF-1 | S | Move test file regex to module scope |
+
+---
+
+## Verdict
+
+**Ship with P1 fix.** BUG-2 (missing workdir in post-verification) is the only functional risk. The SIGKILL race (BUG-1) is theoretical on macOS but worth a quick fix. Everything else is polish.
+
+The test coverage is thorough — 21 tests covering happy path, failure modes, isolation violations, dry-run, and all 3 bug-specific scenarios. The `cleanup.ts` module is clean, well-documented, and properly handles edge cases (dead processes, ESRCH, unexpected errors).

package/docs/20260219-routing-baseline-keyword.md

@@ -0,0 +1,63 @@
+# Keyword Routing Baseline — Config-Loader Dogfood
+
+> Recorded from Run D + Run D2 (2026-02-19) for comparison with LLM routing.
+
+## Run D (US-001 to US-007)
+
+| Story | Title | Classified | Model | Test Strategy | Routing Reason | Cost | Status |
+|:---|:---|:---|:---|:---|:---|:---|:---|
+| US-001 | Define core types and error handling | simple | balanced | test-after | simple task (medium) | ~$0.08 | ✅ |
+| US-002 | Implement environment variable interpolation | medium | balanced | test-after | simple task (medium) | ~$0.08 | ✅ |
+| US-003 | Implement deep merge utility | medium | balanced | test-after | simple task (medium) | ~$0.08 | ✅ |
+| US-004 | Implement config file discovery | simple | balanced | test-after | simple task (medium) | ~$0.08 | ✅ |
+| US-005 | Implement synchronous config loader | medium | balanced | test-after | simple task (medium) | ~$0.10 | ✅ |
+| US-006 | Implement async config loader | medium | balanced | test-after | simple task (medium) | ~$0.10 | ✅ |
+| US-007 | Implement config file watcher | complex | powerful | three-session-tdd | complexity:expert | — | ❌ TDD failure (BUG-20) |
+
+**Run D total: $0.65, 6/9 passed, 174 tests, 9.8 min**
+
+## Run D2 (US-007 to US-009, resumed)
+
+| Story | Title | Classified | Model | Test Strategy | Routing Reason | Cost | Status |
+|:---|:---|:---|:---|:---|:---|:---|:---|
+| US-007 | Implement config file watcher | complex | powerful | three-session-tdd | complexity:expert | $1.74 | ✅ |
+| US-008 (attempt 1) | Export public API and create barrel exports | simple | powerful | three-session-tdd | public-api, complexity:complex | $1.26 | ✅ but ASSET_CHECK failed |
+| US-008 (attempt 2) | Export public API and create barrel exports | simple | powerful | three-session-tdd | public-api, complexity:complex | $1.21 | ✅ |
+| US-009 | Comprehensive integration tests and documentation | medium | powerful | three-session-tdd | complexity:complex | $4.95 | ⏸ Human review (verifier issues) |
+
+**Run D2 total: $4.20 (completed) + $4.95 (US-009 paused) = ~$9.15, 41.4 min**
+
+## Misroute Analysis
+
+| Story | Keyword Route | Ideal Route | Wasted Cost |
+|:---|:---|:---|:---|
+| US-008 | powerful + three-session-tdd ($2.47 over 2 attempts) | fast + test-after (~$0.10) | **~$2.37** |
+| US-009 | powerful + three-session-tdd ($4.95) | balanced + test-after (~$0.20) | **~$4.75** |
+
+**Total misroute waste: ~$7.12** (77% of Run D2 spend)
+
+### Why Keyword Routing Failed
+
+**US-008:** Title "Export **public API** and create barrel exports" matches `PUBLIC_API_KEYWORDS` → forces TDD. But this is just creating `index.ts` barrel files — no logic, no contracts, no breaking changes. A 2-minute task got 3-session TDD with Opus.
+
+**US-009:** "Comprehensive **integration tests** and documentation" — classified as medium by AC count, but routing reason says `complexity:complex`. The word "comprehensive" + AC count likely pushed it. Also got TDD despite the story literally being "write tests" — TDD for writing tests is circular.
+
+### Expected LLM Routing (to validate later)
+
+| Story | Expected LLM Route | Expected Cost |
+|:---|:---|:---|
+| US-001 | fast / test-after | ~$0.05 |
+| US-002 | fast / test-after | ~$0.05 |
+| US-003 | fast / test-after | ~$0.05 |
+| US-004 | fast / test-after | ~$0.05 |
+| US-005 | balanced / test-after | ~$0.10 |
+| US-006 | balanced / test-after | ~$0.10 |
+| US-007 | powerful / three-session-tdd | ~$1.50 |
+| US-008 | fast / test-after | ~$0.05 |
+| US-009 | balanced / test-after | ~$0.15 |
+
+**Expected total with LLM routing: ~$2.10** vs actual $9.80 (Run D + D2)
+
+---
+
+*Recorded 2026-02-19 for A/B comparison with v0.8 LLM routing.*

package/docs/20260220-plan-structured-logging-p1.md

@@ -0,0 +1,80 @@
+# Fix Plan: nax v0.8 Structured Logging — Phase 1
+**Date:** 2026-02-20
+**Branch:** `feat/v0.8-structured-logging`
+
+## Scope
+Phase 1: Logger core, CLI flags, JSONL file output, debug mode.
+Covers AC-1, AC-2, AC-3, AC-4, AC-5, AC-8.
+Does NOT touch existing console.log calls (Phase 2).
+
+## Phase 1A: Logger Core
+**Commit:** `feat(logger): implement structured Logger with level gating and JSONL output`
+
+### File: `src/logger/index.ts` (NEW)
+Export barrel.
+
+### File: `src/logger/logger.ts` (NEW)
+- `Logger` class with `error`, `warn`, `info`, `debug` methods
+- Each method signature: `(stage: string, message: string, data?: Record<string, unknown>)`
+- `withStory(storyId: string)` returns a `StoryLogger` with storyId auto-injected
+- Constructor: `{ level: LogLevel, filePath?: string, useChalk?: boolean }`
+- Console output: chalk-formatted, filtered by level
+- File output: JSON Lines, all levels written regardless of console level
+- Singleton pattern: `getLogger()` / `initLogger(opts)`
+
+### File: `src/logger/types.ts` (NEW)
+- `LogLevel` type: `"error" | "warn" | "info" | "debug"`
+- `LogEntry` interface: `{ timestamp, level, stage, storyId?, message, data? }`
+- `LoggerOptions` interface
+
+### File: `src/logger/formatters.ts` (NEW)
+- `formatConsole(entry: LogEntry): string` — chalk-formatted human-readable
+- `formatJsonl(entry: LogEntry): string` — JSON.stringify one-liner
+
+## Phase 1B: CLI Integration
+**Commit:** `feat(cli): add --verbose, --quiet, --silent flags and run directory`
+
+### File: `bin/nax.ts`
+- Add `--verbose` flag → sets log level to `debug`
+- Add `--quiet` flag → sets log level to `warn`
+- Add `--silent` flag → sets log level to `error`
+- Add `NAX_LOG_LEVEL` env var support (overrides flags)
+- Create run directory: `nax/features/<name>/runs/`
+- Generate run ID: ISO timestamp `YYYY-MM-DDTHH-mm-ssZ`
+- Pass `filePath` to logger init: `nax/features/<name>/runs/<run-id>.jsonl`
+- After run, create/update `latest.jsonl` symlink
+
+### File: `src/config/schema.ts`
+- Add `logging` section to NaxConfig: `{ level: LogLevel, verbose: boolean }`
+
+## Phase 1C: Stage Events
+**Commit:** `feat(logger): emit structured stage lifecycle events`
+
+### File: `src/execution/runner.ts`
+- Add logger calls at key lifecycle points (alongside existing console.log, not replacing):
+  - `run.start`, `iteration.start`, `context.built`
+  - `agent.start`, `agent.complete`
+  - `story.complete`, `run.complete`
+- These write to JSONL file even at `info` level
+
+### File: `src/pipeline/stages/routing.ts`
+- Add logger call for routing decision
+
+## Phase 1D: Tests
+**Commit:** `test(logger): add unit tests for Logger, formatters, and JSONL output`
+
+### Test targets:
+- `test/logger.test.ts` — Logger class, level gating, withStory, file output
+- `test/formatters.test.ts` — console and JSONL formatters
+- Verify: JSONL lines are valid JSON with required fields
+- Verify: level gating (debug hidden at info level, etc.)
+- Verify: file always gets all levels regardless of console setting
+
+## Test Strategy
+- Mode: test-after (implementing against spec)
+- Run: `bun test`
+
+## Notes
+- Do NOT replace any existing `console.log` calls (Phase 2)
+- Logger runs alongside existing output in Phase 1
+- Console formatter should closely match current chalk output style

package/docs/20260220-plan-structured-logging-p2.md

@@ -0,0 +1,37 @@
+# Fix Plan: nax v0.8 Structured Logging — Phase 2
+**Date:** 2026-02-20
+**Covers:** AC-6 (runs list/show), AC-7 (per-story metrics), AC-9 (console.log migration)
+
+## Migration Rules
+1. Import `getLogger` from `../logger` (adjust path as needed)
+2. Get logger instance: `const logger = getLogger()`
+3. Replace `console.log(chalk.X(...))` → `logger.info(stage, message, data?)`
+4. Replace `console.warn(...)` → `logger.warn(stage, message, data?)`
+5. Replace `console.error(...)` → `logger.error(stage, message, data?)`
+6. Replace verbose/debug output → `logger.debug(stage, message, data?)`
+7. `stage` should be the module/concern: "routing", "context", "agent", "tdd", "pipeline", "config", "cli", etc.
+8. Keep chalk formatting in the logger's console formatter — do NOT use chalk in the migrated calls
+9. For `data` objects, include structured fields (storyId, cost, duration, etc.) not string interpolation
+10. Do NOT change test files — only src/ files
+
+## Phase 2A: Core execution pipeline (highest impact)
+**Files:** src/execution/runner.ts, src/execution/helpers.ts, src/execution/post-verify.ts, src/execution/queue-handler.ts
+**Commit:** `refactor(execution): migrate console.log to structured logger`
+
+## Phase 2B: Pipeline stages
+**Files:** src/pipeline/runner.ts, src/pipeline/events.ts, src/pipeline/stages/*.ts (acceptance, completion, constitution, execution, prompt, review, routing, verification)
+**Commit:** `refactor(pipeline): migrate console.log to structured logger`
+
+## Phase 2C: Agents, routing, context, config
+**Files:** src/agents/claude.ts, src/agents/cost.ts, src/agents/validation.ts, src/routing/strategies/*.ts, src/context/builder.ts, src/config/loader.ts, src/analyze/*.ts
+**Commit:** `refactor(agents): migrate console.log to structured logger`
+
+## Phase 2D: CLI, TDD, hooks, metrics + runs list/show commands
+**Files:** src/cli/*.ts, src/tdd/*.ts, src/hooks/*.ts, src/metrics/*.ts, src/review/*.ts, src/acceptance/*.ts
+**Also:** Implement `nax runs list -f <feature>` and `nax runs show <run-id> -f <feature>` commands in bin/nax.ts
+**Also:** Add per-story metrics summary table to run.complete event
+**Commit:** `feat(cli): add nax runs commands and migrate remaining console.log`
+
+## Verification
+After all phases: `grep -rn "console\.\(log\|warn\|error\)" src/ | grep -v "logger\.ts\|formatters\.ts" | wc -l` should be 0
+Run: `bun test` — all tests must pass

package/docs/20260220-review-llm-routing.md

@@ -0,0 +1,180 @@
+# Code Review: nax v0.8 LLM-Enhanced Routing
+
+**Date:** 2026-02-20
+**Reviewer:** Subrina (AI)
+**Branch:** `feat/v0.8-llm-routing` (7 commits, LLM routing scope)
+**Files:** 12 changed (src: ~450 LOC, test: ~700 LOC)
+**Baseline:** 633 pass, 0 fail, 2 skip
+
+---
+
+## Overall Grade: B+ (83/100)
+
+Solid implementation of LLM-based routing with good test coverage (532-line test file), clean separation from keyword strategy, proper fallback chain, and batch mode support. Two notable issues: a **process leak on timeout** (P1) and **duplicate batch routing code** (P2). The async strategy refactor is clean and non-breaking.
+
+| Dimension | Score | Notes |
+|:---|:---|:---|
+| Security | 16/20 | Process leak on timeout; prompt injection surface (low risk — internal tool) |
+| Reliability | 15/20 | Timeout doesn't kill process; no retry on transient failures |
+| API Design | 18/20 | Clean strategy interface, good batch/cache separation |
+| Code Quality | 17/20 | Well-documented, good JSDoc. Some duplication in runner.ts |
+| Best Practices | 17/20 | Proper fallback chain, zod validation, backward compat via `routeTask` |
+
+---
+
+## Findings
+
+### 🔴 CRITICAL
+
+*(none)*
+
+### 🟠 HIGH
+
+#### BUG-1: Process leak on LLM timeout
+**Severity:** HIGH | **Category:** Memory/Resource
+**File:** `src/routing/strategies/llm.ts:131-149`
+
+```typescript
+const timeoutPromise = new Promise<never>((_, reject) => {
+  setTimeout(() => reject(new Error(`LLM call timeout after ${timeoutMs}ms`)), timeoutMs);
+});
+// ...
+return await Promise.race([outputPromise, timeoutPromise]);
+```
+
+When the timeout fires, `Promise.race` rejects but the spawned `claude` process continues running. There's no `proc.kill()` on timeout. This leaks a process that could run for minutes.
+
+**Risk:** Orphaned `claude` processes accumulating on Mac01, consuming memory and API credits.
+
+**Fix:**
+```typescript
+const controller = new AbortController();
+const timeoutId = setTimeout(() => {
+  proc.kill();
+  controller.abort();
+}, timeoutMs);
+
+try {
+  const output = await outputPromise;
+  clearTimeout(timeoutId);
+  return output;
+} catch (err) {
+  proc.kill();
+  clearTimeout(timeoutId);
+  throw err;
+}
+```
+
+#### BUG-2: `setTimeout` in `timeoutPromise` is never cleared on success
+**Severity:** HIGH | **Category:** Bug
+**File:** `src/routing/strategies/llm.ts:135`
+
+Even when the LLM responds quickly, the `setTimeout` callback still fires after `timeoutMs`, creating a rejected promise with no handler (unhandled rejection in some runtimes). In Bun this is silently swallowed, but it's undefined behavior.
+
+**Fix:** Use `clearTimeout` pattern (see BUG-1 fix above).
+
+---
+
+### 🟡 MEDIUM
+
+#### ENH-1: Duplicate batch routing logic in `runner.ts`
+**Severity:** MEDIUM | **Category:** Enhancement
+**File:** `src/execution/runner.ts:140-154` and `src/execution/runner.ts:183-193`
+
+The LLM batch routing block (check strategy, call `llmRouteBatch`, catch and warn) is duplicated verbatim for initial routing and re-routing after dependency resolution. Extract to a helper.
+
+**Fix:**
+```typescript
+async function tryBatchRoute(config: NaxConfig, stories: UserStory[]): Promise<void> {
+  if (config.routing.strategy !== "llm" || !config.routing.llm?.batchMode || stories.length === 0) return;
+  try {
+    console.log(chalk.dim(`   LLM batch routing: routing ${stories.length} stories...`));
+    await llmRouteBatch(stories, { config });
+  } catch (err) {
+    console.warn(chalk.yellow(`   LLM batch routing failed: ${(err as Error).message}`));
+  }
+}
+```
+
+#### ENH-2: Duplicate cached-routing override blocks in `runner.ts`
+**Severity:** MEDIUM | **Category:** Enhancement
+**File:** `src/execution/runner.ts:228-237` and `src/execution/runner.ts:258-267`
+
+The `if (story.routing)` override block (complexity + modelTier + testStrategy) is duplicated for batch vs single-story paths. Same fix: extract helper.
+
+#### PERF-1: `buildStrategyChain` called per-story in `routeStory`
+**Severity:** MEDIUM | **Category:** Performance
+**File:** `src/routing/router.ts`
+
+```typescript
+export async function routeStory(...): Promise<RoutingDecision> {
+  const chain = await buildStrategyChain(context.config, workdir);
+  return await chain.route(story, context);
+}
+```
+
+The chain is rebuilt for every story call from the pipeline routing stage. For keyword/manual strategies this is cheap, but `buildStrategyChain` could load a custom strategy file each time. Consider caching the chain per-run.
+
+**Risk:** Low for current usage (pipeline already uses batch routing for LLM). But `routeStory` is the public API.
+
+#### TYPE-1: `parseBatchResponse` re-serializes then re-parses each entry
+**Severity:** MEDIUM | **Category:** Performance/Style
+**File:** `src/routing/strategies/llm.ts:239`
+
+```typescript
+const decision = parseRoutingResponse(JSON.stringify(entry), story, config);
+```
+
+Each batch entry is `JSON.stringify`'d then immediately `JSON.parse`'d inside `parseRoutingResponse`. This works but is wasteful. Consider extracting validation into a shared function that accepts an object.
+
+---
+
+### 🟢 LOW
+
+#### ENH-3: `maxInputTokens` config field is unused
+**Severity:** LOW | **Category:** Enhancement
+**File:** `src/config/schema.ts` (LlmRoutingConfig)
+
+`maxInputTokens` is defined in the schema and has a default of 2000, but nothing in `llm.ts` reads or enforces it. Either implement truncation of story context or remove the field to avoid config confusion.
+
+#### STYLE-1: `console.log`/`console.warn` for routing logs
+**Severity:** LOW | **Category:** Style
+**File:** `src/routing/strategies/llm.ts` (multiple)
+
+Uses raw `console.log`/`console.warn` with `[routing]` prefix. This will be addressed by the v0.8 structured logging feature, so noting for tracking only.
+
+#### ENH-4: No validation that `strategy: "llm"` has `routing.llm` config
+**Severity:** LOW | **Category:** Enhancement
+**File:** `src/config/schema.ts`
+
+When `strategy` is `"llm"`, there's a zod refinement for `customStrategyPath` on `"custom"` but no refinement requiring `llm` config when `strategy` is `"llm"`. The runtime handles it gracefully (falls through to keyword), but a config validation error would be more user-friendly.
+
+#### STYLE-2: Adaptive strategy now has unnecessary null guards
+**Severity:** LOW | **Category:** Style
+**File:** `src/routing/strategies/adaptive.ts:170,193`
+
+```typescript
+const decision = await keywordStrategy.route(story, context);
+if (!decision) return null;  // keyword never returns null
+```
+
+The keyword strategy **never** returns null (it always produces a decision). The null guard is defensive but misleading — it suggests keyword might return null when it can't.
+
+---
+
+## Priority Fix Order
+
+| Priority | ID | Effort | Description |
+|:---|:---|:---|:---|
+| P1 | BUG-1 + BUG-2 | S | Kill process on timeout, clear setTimeout on success |
+| P2 | ENH-1 + ENH-2 | S | Extract duplicate batch routing + override helpers in runner.ts |
+| P3 | TYPE-1 | S | Avoid re-serializing batch entries for validation |
+| P4 | PERF-1 | M | Cache strategy chain per-run (optional) |
+| P5 | ENH-3 | S | Remove or implement `maxInputTokens` |
+| — | ENH-4, STYLE-1, STYLE-2 | S | Low priority / deferred to structured logging |
+
+---
+
+## Verdict
+
+**Ship after P1 fix.** The process leak on timeout is the only blocker — it could accumulate orphaned `claude` processes costing real API credits. P2-P5 are quality improvements that can land in a follow-up.

package/docs/20260220-review-post-fix-llm-routing.md

@@ -0,0 +1,70 @@
+Code Review Report — Post-fix LLM routing
+Date: 2026-02-20
+Branch: feat/v0.8-llm-routing
+Commit: a70d4f61d29ce1e528fd1e3d82ec9987b4737a79
+
+Summary
+- Reviewed only the latest commit (the P1–P5 fix commit).
+- Verified code changes for P1, P2, P3, P5 and test mock updates in the diff between HEAD~1 and HEAD.
+- Could not complete test run: 'bun test' appeared to hang in this environment within the allotted time. (See note at the end.)
+
+What I accomplished / found
+1) P1 (BUG-1+2): callLlm timeout, process kill and clearTimeout
+- Changes made in src/routing/strategies/llm.ts:
+  - Introduced timeoutId variable, setTimeout now kills the spawned process (proc.kill()) and rejects on timeout.
+  - Promise.race is wrapped in try/catch and both success and error paths clearTimeout(timeoutId) and ensure proc.kill() is called on the error path.
+- Assessment: Good improvements. This addresses the resource leak (leftover child) on timeout and ensures the timer is cleared on both success and failure.
+- Notes / minor suggestions:
+  - clearTimeout is called with timeoutId which is possibly undefined in the narrow window before setTimeout assigned it; that's safe because clearTimeout(undefined) is benign in Node.
+  - proc.kill() is invoked both inside the timeout handler and again in catch — double-kill is usually safe but could be redundant; acceptable.
+  - If proc.exited already resolved, kill() is a no-op. No dangling promises observed in this snippet.
+
+2) P2 (ENH-1+2): tryLlmBatchRoute and applyCachedRouting
+- Changes made in src/execution/runner.ts:
+  - Extracted the LLM batch routing logic into tryLlmBatchRoute that logs and swallows errors and returns early when not applicable.
+  - Extracted cached-routing override into applyCachedRouting(routing, story, config) and replaced inline blocks with the helper.
+- Assessment: Behavior preserved. The helpers are straightforward extractions with identical logic (I compared the code before/after in the diff). applyCachedRouting reproduces the previous override logic for complexity -> modelTier mapping and testStrategy.
+- Minor suggestion: applyCachedRouting accepts routing produced by routeTask; that function's return type is used via ReturnType<> which is OK. Consider adding a narrow explicit type alias for clarity in future.
+
+3) P3 (TYPE-1): validateRoutingDecision and stripCodeFences
+- Changes made in src/routing/strategies/llm.ts:
+  - Extracted validateRoutingDecision(parsed, config) which validates parsed object fields and returns typed RoutingDecision.
+  - Extracted stripCodeFences(text) to remove markdown/json code fences.
+  - parseRoutingResponse now strips fences, JSON.parse once, and validates via validateRoutingDecision.
+  - parseBatchResponse uses validateRoutingDecision(entry, config) directly instead of re-serializing entry->string->parse again.
+- Assessment: Correct and type-safer.
+  - validateRoutingDecision uses type assertions (as Complexity/TestStrategy/ModelTier) before returning typed fields — appropriate.
+  - Using direct validation on batch entries avoids unnecessary serialization/parsing and fixes the prior issue where batch entries were re-serialized.
+- Minor caution: validateRoutingDecision checks `if (!parsed.complexity || !parsed.modelTier || ...)` — if any field is present but falsy (empty string) it will still be caught; that likely matches intended validation.
+
+4) P5 (ENH-3): Removed maxInputTokens from config schema
+- Changes made in src/config/schema.ts: removed maxInputTokens from LlmRoutingConfig interface, schema and DEFAULT_CONFIG.
+- Assessment: Removal in the three spots shown in diff is correct. I searched the diff for remaining references and did not see other references in the commit diff. (A full repo-wide search was not performed in this review scope.)
+
+5) Test mocks: mock spawn kill handlers
+- Changes made in test/routing/llm-strategy.test.ts: added kill: () => {} to all 9 mock spawn objects.
+- Assessment: Matches the code changes in callLlm that call proc.kill() on timeout and in catch — tests needed mocks to provide a kill function to avoid runtime errors. Good.
+
+Tests
+- I attempted to run tests with `bun test` but the runner in this environment did not complete within the quick-review time window (process appeared to hang). I aborted attempts to repeatedly poll.
+- Because tests did not finish here, I could not validate runtime behavior across the suite. Local/CI test run is recommended.
+
+Grade (per requested areas)
+- P1 (BUG-1+2): PASS — timeout handling and process cleanup implemented; no obvious resource leaks or dangling timers.
+- P2 (ENH-1+2): PASS — helpers extracted; logic preserved.
+- P3 (TYPE-1): PASS — validation and fence-stripping extracted; batch entry validation fixed to avoid re-serialization.
+- P5 (ENH-3): PASS (within commit diff) — removed config field; no remaining references in diff.
+- Test mocks: PASS — all mocked spawns in the tested file now include kill() handler.
+
+Recommendations / Follow-ups
+- Run the full test suite in CI or locally to confirm all tests pass. The new timeout/process kill behavior and the added kill mocks should make tests stable, but I couldn't confirm here.
+- Optional: avoid double-kill redundancy by checking proc.killed/exited state before calling kill() if platform provides it — not required.
+- Optional: add unit tests for validateRoutingDecision and stripCodeFences to assert correct behavior on edge cases (fenced JSON, invalid fields, batch entries).
+
+Note about test run
+- The environment's `bun test` invocation did not complete in this review session; please run tests in CI or locally and paste the last 20 lines of output if you want me to re-check test failures (if any).
+
+Artifacts
+- Saved report at: docs/20260220-review-post-fix-llm-routing.md
+
+End of report.

package/docs/20260221-fix-plan-relevantfiles-split.md

@@ -0,0 +1,101 @@
+# Fix Plan: Split relevantFiles into contextFiles + expectedFiles
+
+**Date:** 2026-02-21
+**Branch:** `feat/v0.9-relevantfiles-split`
+**Issue:** #1
+**Base:** `master` (`b459e9f`)
+
+## Context
+
+`relevantFiles` conflates two purposes:
+1. **Context injection** — files loaded into agent prompt before execution
+2. **Asset verification** — files that must exist after execution (pre-flight gate)
+
+This causes false negatives: LLM-predicted filenames fail asset check even when code is correct and tests pass. Observed in dogfood Runs F and H.
+
+## Phase 1: Type Changes + Resolver Functions
+
+### Fix 1.1: Add new fields to UserStory type
+**File:** `src/prd/types.ts`
+**Change:** Add `contextFiles?: string[]` and `expectedFiles?: string[]` to `UserStory` interface. Keep `relevantFiles?: string[]` as deprecated.
+
+### Fix 1.2: Add resolver functions
+**File:** `src/prd/types.ts` (or new `src/prd/helpers.ts`)
+**Change:** Create two helper functions:
+```typescript
+export function getContextFiles(story: UserStory): string[] {
+  return story.contextFiles ?? story.relevantFiles ?? [];
+}
+export function getExpectedFiles(story: UserStory): string[] {
+  return story.expectedFiles ?? [];
+}
+```
+**Key:** `getExpectedFiles` does NOT fall back to `relevantFiles`. Asset check is opt-in only.
+
+### Fix 1.3: Export helpers from prd index
+**File:** `src/prd/index.ts`
+**Change:** Export `getContextFiles` and `getExpectedFiles`.
+
+**Commit:** `refactor(prd): add contextFiles + expectedFiles types and resolvers`
+
+## Phase 2: Wire Context Builder
+
+### Fix 2.1: Use getContextFiles in context builder
+**File:** `src/context/builder.ts`
+**Change:** Replace `currentStory.relevantFiles` with `getContextFiles(currentStory)` at line ~296. Import from prd.
+
+**Commit:** `refactor(context): use getContextFiles for prompt injection`
+
+## Phase 3: Wire Verification
+
+### Fix 3.1: Use getExpectedFiles in post-verify
+**File:** `src/execution/post-verify.ts`
+**Change:** Replace `story.relevantFiles` (line ~73) with `getExpectedFiles(story)`. Import from prd.
+
+### Fix 3.2: Update verification function signature
+**File:** `src/execution/verification.ts`
+**Change:** Rename parameter `relevantFiles` to `expectedFiles` in `runVerification()` and `verifyAssets()` for clarity.
+
+**Commit:** `refactor(verification): use getExpectedFiles for asset check (opt-in only)`
+
+## Phase 4: Wire Analyze + Decompose Output
+
+### Fix 4.1: Update classifier output
+**File:** `src/analyze/classifier.ts`
+**Change:** Map LLM output `relevantFiles` -> `contextFiles` in parsed result.
+
+### Fix 4.2: Update analyze types
+**File:** `src/analyze/types.ts`
+**Change:** Add `contextFiles` field alongside `relevantFiles`.
+
+### Fix 4.3: Update decompose prompt
+**File:** `src/agents/claude.ts`
+**Change:** In decompose prompt (~line 455), rename field 8 from `relevantFiles` to `contextFiles`.
+
+### Fix 4.4: Update CLI analyze output
+**File:** `src/cli/analyze.ts`
+**Change:** Map `relevantFiles` -> `contextFiles` in feature creation output.
+
+### Fix 4.5: Update acceptance fix-generator
+**File:** `src/acceptance/fix-generator.ts`
+**Change:** Replace `relevantFiles: []` with `contextFiles: []`.
+
+**Commit:** `refactor(analyze): output contextFiles instead of relevantFiles`
+
+## Phase 5: Tests
+
+### Fix 5.1: Update verification tests
+**Change:** Add test: story with `relevantFiles` but no `expectedFiles` -> asset check PASSES. Add test: story with `expectedFiles` set -> asset check verifies those files.
+
+### Fix 5.2: Update context builder tests
+**Change:** Test `contextFiles` used when present. Test `relevantFiles` fallback. Test empty when neither set.
+
+### Fix 5.3: Update classifier/analyze tests
+**Change:** Verify output uses `contextFiles` field.
+
+**Commit:** `test: update tests for contextFiles/expectedFiles split`
+
+## Test Strategy
+- Mode: test-after
+- Run `bun test` after each phase
+- All existing test files should continue passing (backward compat)