@nathapp/nax 0.28.0 → 0.29.0

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

@@ -1,135 +0,0 @@
-# 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

@@ -1,63 +0,0 @@
-# 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

@@ -1,80 +0,0 @@
-# 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

@@ -1,37 +0,0 @@
-# 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

@@ -1,180 +0,0 @@
-# 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

@@ -1,70 +0,0 @@
-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

@@ -1,101 +0,0 @@
-# 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)