@nathapp/nax 0.18.3 → 0.18.4

package/.claude/rules/01-project-conventions.md

@@ -0,0 +1,34 @@
+# Project Conventions
+
+## Language & Runtime
+
+- **Bun-native only.** Use `Bun.file()`, `Bun.write()`, `Bun.spawn()`, `Bun.sleep()`. Never use Node.js equivalents (`fs.readFile`, `child_process.spawn`, `setTimeout` for delays).
+- TypeScript strict mode. No `any` unless unavoidable (document why).
+- Target: Bun 1.3.7+.
+
+## File Size
+
+- **400-line hard limit** for all source and test files.
+- If a file approaches 400 lines, split it before adding more code.
+- Split by logical concern (one function/class per file when possible).
+
+## Module Structure
+
+- Every directory with 2+ exports gets a barrel `index.ts`.
+- Types go in `types.ts` per module directory.
+- Import from barrels (`src/routing`), **never from internal paths** (`src/routing/router`). This prevents singleton fragmentation in Bun's module registry.
+
+## Logging
+
+- Use the project logger (`src/logger`). Never use `console.log` / `console.error` in source code.
+- Log format: no emojis. Use `[OK]`, `[WARN]`, `[FAIL]`, `->`. Machine-parseable.
+
+## Commits
+
+- Conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`.
+- Atomic — one logical change per commit.
+- Never include `[run-release]` unless explicitly told to.
+
+## Formatting
+
+- Biome handles formatting and linting. Run `bun run lint` before committing.

package/.claude/rules/02-test-architecture.md

@@ -0,0 +1,39 @@
+# Test Architecture
+
+## Directory Structure
+
+Tests **must** mirror the `src/` directory structure:
+
+```
+src/routing/strategies/foo.ts    → test/unit/routing/strategies/foo.test.ts
+src/execution/runner.ts          → test/unit/execution/runner.test.ts
+src/pipeline/stages/verify.ts   → test/unit/pipeline/stages/verify.test.ts
+src/verification/smart-runner.ts → test/unit/verification/smart-runner.test.ts
+```
+
+## Test Categories
+
+| Category | Location | Purpose |
+|:---|:---|:---|
+| Unit | `test/unit/<mirror-of-src>/` | Test individual functions/classes in isolation |
+| Integration | `test/integration/<feature>.test.ts` | Test multiple modules working together |
+| UI | `test/ui/` | TUI component tests |
+
+## Placement Rules
+
+1. **Never create test files in `test/` root.** Always place in the appropriate subdirectory.
+2. **Never create standalone bug-fix test files** like `test/execution/post-verify-bug026.test.ts`. Add tests to the existing relevant test file instead. If the relevant file would exceed 400 lines, split the file by describe block — not by bug number.
+3. **Never create `TEST_COVERAGE_*.md` or documentation files in `test/`.** Put docs in `docs/`.
+4. **Unit test directories must exist under `test/unit/`**, mirroring `src/`. Do not create top-level test directories like `test/execution/` or `test/context/` — use `test/unit/execution/` and `test/unit/context/`.
+
+## File Naming
+
+- Test files: `<source-file-name>.test.ts` — must match the source file name exactly.
+- One test file per source file (for unit tests).
+- If a test file needs splitting, split by describe block into `<module>-<concern>.test.ts`.
+
+## Temp Files & Fixtures
+
+- Use `mkdtempSync(join(tmpdir(), "nax-test-"))` for temporary directories.
+- Clean up in `afterAll()` — never leave files in `test/tmp/`.
+- Integration tests needing git: always `git init` + `git add .` + `git commit` in the temp fixture before testing.

package/.claude/rules/03-test-writing.md

@@ -0,0 +1,58 @@
+# Test Writing Rules
+
+## Mocking
+
+### Never use `mock.module()`
+
+`mock.module()` in Bun 1.x is **globally scoped and leaks between test files**. It poisons the ESM module registry for the entire test run. `mock.restore()` does NOT undo `mock.module()` overrides.
+
+**Instead, use dependency injection:**
+
+```typescript
+// In source file: export a swappable deps object
+export const _deps = {
+  readConfig: () => loadConfig(),
+  runCommand: (cmd: string) => Bun.spawn(cmd.split(" ")),
+};
+
+// In test file: override _deps directly
+import { _deps } from "src/mymodule";
+
+beforeEach(() => {
+  _deps.readConfig = mock(() => fakeConfig);
+});
+
+afterEach(() => {
+  mock.restore(); // restores mock() spies (NOT mock.module)
+  _deps.readConfig = originalReadConfig;
+});
+```
+
+### General Mocking Rules
+
+- Always call `mock.restore()` in `afterEach()`.
+- Use `mock()` (function-level) freely — it's properly scoped.
+- Never rely on test file execution order. Each file must be independently runnable.
+- Store original function references before overriding `_deps` and restore in `afterEach`.
+
+## CI Compatibility
+
+- Tests requiring the `claude` binary: guard with `const skipInCI = process.env.CI ? test.skip : test;`
+- Tests requiring specific OS features: guard with platform checks.
+- Never send real signals (`process.kill`) — mock `process.on()` instead.
+
+## Spawning & Subprocesses
+
+- Never spawn full `nax` processes in tests — prechecks fail in temp dirs.
+- Wrap `Bun.spawn()` in try/catch — throws `ENOENT` for missing binaries (not a failed exit code).
+
+## Test Structure
+
+- One `describe()` block per source function or class being tested.
+- Keep test files under 400 lines. Split by `describe()` block if needed.
+- Use `test/helpers/` for shared mock factories and fixtures. Don't copy-paste mocking setup between files.
+
+## Imports
+
+- **Import from barrels** (`src/routing`), not internal paths (`src/routing/router`).
+- This matches the project convention and prevents Bun singleton fragmentation where the same module loaded via two different paths creates two separate instances.

package/.claude/rules/04-forbidden-patterns.md

@@ -0,0 +1,29 @@
+# Forbidden Patterns
+
+These patterns are **banned** from the nax codebase. Violations must be caught during implementation, not after.
+
+## Source Code
+
+| ❌ Forbidden | ✅ Use Instead | Why |
+|:---|:---|:---|
+| `mock.module()` | Dependency injection (`_deps` pattern) | Leaks globally in Bun 1.x, poisons other test files |
+| `console.log` / `console.error` in src/ | Project logger (`src/logger`) | Unstructured output breaks test capture and log parsing |
+| `fs.readFileSync` / `fs.writeFileSync` | `Bun.file()` / `Bun.write()` | Bun-native project — no Node.js file APIs |
+| `child_process.spawn` / `child_process.exec` | `Bun.spawn()` / `Bun.spawnSync()` | Bun-native project — no Node.js process APIs |
+| `setTimeout` / `setInterval` for delays | `Bun.sleep()` | Bun-native equivalent |
+| Hardcoded timeouts in logic | Config values from schema | Hardcoded values can't be tuned per-environment |
+| `import from "src/module/internal-file"` | `import from "src/module"` (barrel) | Prevents singleton fragmentation (BUG-035) |
+| Files > 400 lines | Split by concern | Unmaintainable; violates project convention |
+
+## Test Files
+
+| ❌ Forbidden | ✅ Use Instead | Why |
+|:---|:---|:---|
+| Test files in `test/` root | `test/unit/`, `test/integration/`, etc. | Orphaned files with no clear ownership |
+| Standalone bug-fix test files (`*-bug026.test.ts`) | Add to existing relevant test file | Fragments test coverage, creates ownership confusion |
+| `TEST_COVERAGE_*.md` in test/ | `docs/` directory | Test dir is for test code only |
+| `rm -rf` in test cleanup | `mkdtempSync` + OS temp dir | Accidental deletion risk |
+| Tests depending on alphabetical file execution order | Independent, self-contained test files | Cross-file coupling causes phantom failures |
+| Copy-pasted mock setup across files | `test/helpers/` shared factories | DRY; single place to update when interfaces change |
+| Spawning full `nax` process in tests | Mock the relevant module | Prechecks fail in temp dirs; slow; flaky |
+| Real signal sending (`process.kill`) | Mock `process.on()` | Can kill the test runner |

package/.githooks/pre-commit

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# nax pre-commit hook — runs typecheck + lint
+# Install: git config core.hooksPath .githooks
+
+set -e
+
+echo "[pre-commit] Running typecheck..."
+bun run typecheck
+
+echo "[pre-commit] Running lint..."
+bun run lint
+
+echo "[pre-commit] OK"

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.18.4] - 2026-03-04
+
+### Fixed
+- **BUG-031:** Keyword classifier no longer drifts across retries — `description` excluded from complexity/strategy classification (only `title`, `acceptanceCriteria`, `tags` used). Prevents prior error context from upgrading story complexity mid-run.
+- **BUG-033:** LLM routing now retries on timeout/transient failure. New config: `routing.llm.retries` (default: 1), `routing.llm.retryDelayMs` (default: 1000ms). Default timeout raised from 15s to 30s.
+
+### Added
+- Pre-commit hook (`.githooks/pre-commit`) — runs `typecheck` + `lint` before every commit. Install with: `git config core.hooksPath .githooks`
+
 ## [0.10.0] - 2026-02-23
 
 ### Added

package/CLAUDE.md

@@ -1,10 +1,9 @@
 # nax — AI Coding Agent Orchestrator
 
-Bun + TypeScript CLI that orchestrates AI coding agents with model routing, three-session TDD, and lifecycle hooks.
+Bun + TypeScript CLI that orchestrates AI coding agents with model routing, TDD strategies, and lifecycle hooks.
 
 ## Git Identity
 
-Always set before committing:
 ```bash
 git config user.name "subrina.tai"
 git config user.email "subrina8080@outlook.com"
@@ -12,148 +11,72 @@ git config user.email "subrina8080@outlook.com"
 
 ## Commands
 
-- Test: `bun test`
-- Typecheck: `bun run typecheck`
-- Lint: `bun run lint`
-- Dev: `bun run dev`
-- Build: `bun run build`
-- Run before commit: `bun test && bun run typecheck`
-
-## Code Style
-
-- Bun-native APIs only (Bun.file, Bun.write, Bun.spawn, Bun.sleep) — no Node.js equivalents
-- Functional style for pure logic; classes only for stateful adapters (e.g., ClaudeCodeAdapter)
-- Types in `types.ts` per module, barrel exports via `index.ts`
-- Max ~400 lines per file — split if larger
-- Biome for formatting/linting
-
-## Testing
-
-- Framework: `bun:test` (describe/test/expect)
-- Unit tests: `test/unit/<module>.test.ts`
-- Integration tests: `test/integration/<feature>.test.ts`
-- Routing tests: `test/routing/<router>.test.ts`
-- UI tests: `test/ui/` (TUI testing, rarely needed)
-- All routing, classification, and isolation logic must have unit tests
+```bash
+bun test                          # Full test suite
+bun test test/unit/foo.test.ts    # Specific file
+bun run typecheck                 # tsc --noEmit
+bun run lint                      # Biome
+bun run build                     # Production build
+bun test && bun run typecheck     # Pre-commit check
+```
 
 ## Architecture
 
-### Execution Flow
-
 ```
-Runner.run()  [src/execution/runner.ts]
-  -> loadPlugins()  [src/plugins/loader.ts]
-  -> for each story:
-    -> Pipeline.execute()  [src/pipeline/pipeline.ts]
-      -> stages: queueCheck -> routing -> constitution -> context -> prompt -> execution -> verify -> review -> completion
-      -> context stage injects plugin context providers  [src/pipeline/stages/context.ts]
-      -> routing stage checks plugin routers first  [src/routing/chain.ts]
-    -> Reporter.emit()  [src/plugins/registry.ts]
-  -> registry.teardownAll()
+Runner.run()  [src/execution/runner.ts — thin orchestrator only]
+  → loadPlugins()
+  → for each story:
+    → Pipeline.execute()  [src/pipeline/pipeline.ts]
+      → stages: queueCheck → routing → constitution → context → prompt
+               → execution → verify → review → completion
+    → Reporter.emit()
+  → registry.teardownAll()
 ```
 
 ### Key Directories
 
 | Directory | Purpose |
 |:---|:---|
-| `src/execution/` | Runner loop, agent adapters (Claude Code), TDD strategies |
-| `src/execution/lifecycle/` | (v0.15.0) Lifecycle hooks, startup/teardown orchestration |
-| `src/execution/escalation/` | (v0.15.0) Acceptance-loop escalation logic (when agent fails repeatedly) |
-| `src/execution/acceptance/` | (v0.15.0) Acceptance-loop iteration logic |
-| `src/pipeline/stages/` | Pipeline stages (routing, context, prompt, execution, review, etc.) |
-| `src/routing/` | Model routing — tier classification, router chain, plugin routers |
-| `src/plugins/` | Plugin system — loader, registry, validator, types |
+| `src/execution/` | Runner loop, agent adapters, TDD strategies |
+| `src/execution/lifecycle/` | Lifecycle hooks, startup/teardown |
+| `src/execution/escalation/` | Escalation logic on repeated failures |
+| `src/execution/acceptance/` | Acceptance-loop iteration |
+| `src/pipeline/stages/` | Pipeline stages |
+| `src/routing/` | Model routing — tier classification, router chain |
+| `src/plugins/` | Plugin system — loader, registry, validator |
 | `src/config/` | Config schema, loader (layered global + project) |
-| `src/verification/` | (planned) Unified test execution, typecheck, lint, acceptance checks |
-| `src/agents/adapters/` | Agent integrations (Claude Code, future: Devin, Aider, etc.) |
-| `src/cli/` | CLI commands |
-| `examples/plugins/` | Sample plugins (console-reporter) |
+| `src/agents/adapters/` | Agent integrations (Claude Code) |
+| `src/cli/` + `src/commands/` | CLI commands (check both locations) |
+| `src/verification/` | Test execution, smart test runner |
+| `src/review/` | Post-verify review (typecheck, lint, plugin reviewers) |
 
-### Plugin System
-
-Plugins extend nax via 4 extension points:
+### Plugin System (4 extension points)
 
 | Extension | Interface | Integration Point |
 |:---|:---|:---|
-| **Context Provider** | `IContextProvider` | `src/pipeline/stages/context.ts` — injects context into agent prompts before execution |
-| **Reviewer** | `IReviewer` | Pipeline review stage — runs after built-in checks (typecheck/lint/test) |
-| **Reporter** | `IReporter` | `src/execution/runner.ts` — receives onRunStart/onStoryComplete/onRunEnd events |
-| **Router** | `IRoutingStrategy` | `src/routing/chain.ts` — overrides model routing for specific stories |
-
-Plugin loading order: global (`~/.nax/plugins/`) -> project (`<workdir>/nax/plugins/`) -> config (`plugins[]` in config.json).
+| Context Provider | `IContextProvider` | `context.ts` stage — injects into prompts |
+| Reviewer | `IReviewer` | Review stage — after built-in checks |
+| Reporter | `IReporter` | Runner — onRunStart/onStoryComplete/onRunEnd |
+| Router | `IRoutingStrategy` | Router chain — overrides model routing |
 
 ### Config
 
-- Global: `~/.nax/config.json`
-- Project: `<workdir>/nax/config.json`
-- Key settings: `execution.contextProviderTokenBudget` (default: 2000), `plugins[]` array
-
-## Target Architecture (v0.15.0+)
-
-### File Size Hard Limit
-
-**400 lines maximum per file.** If you are about to exceed it, STOP and split first.
-
-### execution/ Module Re-architecture Goal
-
-Keep `runner.ts` as a **thin orchestrator only**. Extract:
+- Global: `~/.nax/config.json` → Project: `<workdir>/nax/config.json`
+- Schema: `src/config/schema.ts` — no hardcoded flags or credentials
 
-- `sequential-executor.ts` — single-story execution loop
-- `parallel-runner.ts` — parallel story execution (future)
-- `acceptance-loop.ts` — retry/escalation logic for failed stories
-- `reporter-notifier.ts` — plugin event emission (onRunStart, onStoryComplete, onRunEnd)
-- `lifecycle/` subdir — startup, teardown, cleanup handlers
-- `escalation/` subdir — escalation strategies when acceptance loop fails
+## Design Principles
 
-**Never add new concerns to `runner.ts`** — new logic goes into a focused sub-module.
-
-### verification/ Unified Layer (Planned)
-
-Do not duplicate test execution logic across pipeline stages. When building new verification features (typecheck, lint, test, acceptance checks), put the logic in `src/verification/` and call from pipeline stages. This prevents scattered test invocations and ensures consistent test result parsing.
-
-### Plugin Extension Points
-
-When adding new agent integrations (e.g., Devin, Aider, Cursor):
-
-1. Add adapter class to `src/agents/adapters/<name>.ts`
-2. Register in `src/agents/adapters/index.ts`
-3. Do NOT inline agent logic in `runner.ts` or `claude.ts`
-
-### Logging Style
-
-- No emojis in log messages
-- Use `[OK]`, `[WARN]`, `[FAIL]`, `->` instead
-- Keep logs machine-parseable
-
-### Configuration
-
-- No hardcoded flags or credentials
-- Always read from config schema (`src/config/schema.ts`)
-- Validate config at startup
-
-### Closure Passing for Long-Lived Handlers
-
-Pass **closures, not values** to long-lived handlers (crash handlers, heartbeat timers). This ensures handlers always reference the latest state, not stale snapshots.
-
-```typescript
-// WRONG: Captures stale value
-const handler = () => cleanup(currentStory)
-
-// CORRECT: Closure references latest state
-const handler = () => cleanup(() => getCurrentStory())
-```
+- **`runner.ts` is a thin orchestrator.** Never add new concerns — extract into focused sub-modules.
+- **`src/verification/` is the single test execution layer.** Don't duplicate test invocation in pipeline stages.
+- **Closures over values** for long-lived handlers (crash handlers, timers) — prevents stale state capture.
+- **New agent adapters** go in `src/agents/adapters/<name>.ts` — never inline in runner or existing adapters.
 
-## Testing Constraints (CRITICAL)
+## Rules
 
-- **Never spawn full `nax` processes in tests.** nax has prechecks (git-repo-exists, dependencies-installed) that fail in temp directories. Write unit tests with mocks instead.
-- **Integration tests that need git:** Always `git init` + `git add` + `git commit` in the test fixture before running any code that triggers nax precheck validation.
-- **Test files for crash/signal handling:** Use process-level mocks (e.g., mock `process.on('SIGTERM', ...)`) — do not send real signals in tests.
-- **Context files:** If a test needs specific context files, create them in the test fixture directory — don't rely on auto-detection from the real workspace.
+Detailed coding standards, test architecture, and forbidden patterns are in `.claude/rules/`. Claude Code loads these automatically.
 
 ## IMPORTANT
 
-- Never hardcode API keys — agents use their own auth from env
-- Agent adapters spawn external processes — always handle timeouts and cleanup
-- Conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`
-- Keep commits atomic — one logical change per commit
-- Do NOT push to remote — let the human review and push
+- Do NOT push to remote — let the human review and push.
+- Never hardcode API keys — agents use their own auth from env.
+- Agent adapters spawn external processes — always handle timeouts and cleanup.

package/docker-compose.test.yml

@@ -1,14 +1,12 @@
 version: "3.9"
 services:
   app:
-    image: oven/bun:1.3.8
+    image: nathapp/bun:1.3.8-ci
     working_dir: /app
     volumes:
       - .:/app
     command: >
       sh -c "
-        echo 'Running pre-step...' &&
-        apt-get update && apt-get install -y --no-install-recommends git &&
         bun install &&
         bun run test:unit
       "    

package/docs/ROADMAP.md

@@ -107,14 +107,14 @@
 
 ---
 
-## v0.18.4 — Routing Stability
+## v0.18.4 — Routing Stability ✅
 
 **Theme:** Fix routing classifier consistency and LLM routing reliability
-**Status:** 🔲 Planned
+**Status:** ✅ Shipped (2026-03-04)
 
 ### Bugfixes
-- [ ] **BUG-031:** Keyword fallback classifier gives inconsistent strategy across retries for same story. `priorErrors` text shifts keyword classification. **Fix:** Keyword classifier should only use original story fields; or lock `story.routing.testStrategy` once set.
-- [ ] **BUG-033:** LLM routing has no retry on timeout — single 15s attempt, then keyword fallback. **Fix:** Add `routing.llm.retries` config (default: 1) with backoff. Raise default timeout to 30s for batch routing.
+- [x] **BUG-031:** Keyword fallback classifier gives inconsistent strategy across retries for same story. `priorErrors` text shifts keyword classification. **Fix:** Keyword classifier should only use original story fields; or lock `story.routing.testStrategy` once set.
+- [x] **BUG-033:** LLM routing has no retry on timeout — single 15s attempt, then keyword fallback. **Fix:** Add `routing.llm.retries` config (default: 1) with backoff. Raise default timeout to 30s for batch routing.
 
 ---
 
@@ -150,6 +150,7 @@
 | Version | Theme | Date | Details |
 |:---|:---|:---|:---|
 | v0.18.1 | Type Safety + CI Pipeline | 2026-03-03 | 60 TS errors + 12 lint errors fixed, GitLab CI green (1952/56/0) |
+| v0.18.4 | Routing Stability | 2026-03-04 | BUG-031 keyword drift, BUG-033 LLM retry, pre-commit hook |
 | v0.18.3 | Execution Reliability + Smart Runner | 2026-03-04 | BUG-026/028/029/030/032 + SFC-001/002 + STR-007, all items complete |
 | v0.18.2 | Smart Test Runner + Routing Fix | 2026-03-03 | FIX-001 + STR-001–006, 2038 pass/11 skip/0 fail |
 | v0.18.0 | Orchestration Quality | 2026-03-03 | BUG-016/017/018/019/020/021/022/023/025 all fixed |
@@ -186,28 +187,9 @@
 - [x] ~~BUG-012: Greenfield detection ignores pre-existing test files~~
 - [x] ~~BUG-013: Escalation routing not applied in iterations~~
 - [x] ~~BUG-014: buildAllowedEnv() strips USER/LOGNAME~~
-<<<<<<< Updated upstream
 - [x] ~~**BUG-015:** `loadConstitution()` leaks global `~/.nax/constitution.md` into unit tests — fixed via `skipGlobal: true` in all unit tests~~
-=======
-- [ ] **BUG-015:** `loadConstitution()` leaks global `~/.nax/constitution.md` into unit tests
-- [ ] **BUG-027:** `runPrecheck()` always prints to stdout — pollutes test output when called programmatically.
-  - **Observed (2026-03-03):** `bun test` output starts with precheck JSON from `US-002-orchestrator.test.ts` calling `runPrecheck()`, which unconditionally calls `console.log()`. nax verify stage captures this, making every failure look like a `git-repo-exists` blocker.
-  - **Root cause:** `runPrecheck()` mixes side-effects (printing) with logic (returning result).
-  - **Fix:** Add `silent?: boolean` to `PrecheckOptions`; test callers pass `silent: true`.
-  - **Workaround (active):** `silent` option + test update shipped in v0.18.2 branch.
-  - **Target:** v0.18.2
-- [ ] **BUG-028:** Routing cache ignores escalation tier — escalated stories re-run at original tier.
-  - **Observed (2026-03-03):** STR-006 escalated to `powerful`. Router returned LLM cache hit from prior `balanced` run → agent ran as `balanced` anyway.
-  - **Root cause:** Cache key does not include requested tier. Lower-tier cache hit served for higher-tier request.
-  - **Fix:** Include `requestedTier` in cache key; only serve cache hit if cached tier >= requested tier.
-  - **Target:** v0.19.0
-- [ ] **BUG-026:** Regression gate failure triggers full story re-implementation instead of targeted rectification.
-  - **Observed (2026-03-03):** During v0.18.2 smart-runner development on Mac01, STR-001 passed scoped verification (5/5 tests green) but the full-suite regression gate timed out (exit code 132, SIGILL/Bun crash). nax treated this as a story failure and re-ran the coding agent, which rewrote already-correct code. The retry agent then produced a different (worse) implementation that failed verification.
-  - **Root cause:** Escalation logic does not distinguish between "story code is wrong" and "story code is fine but introduced a regression". Both flow through the same retry path.
-  - **Fix:** After regression gate failure, spawn a rectification agent with context of what regressed (failing test names + diff), not a full story re-implementation. Only fall back to full re-implementation if rectification also fails.
-  - **Workaround (active):** Disabled regression gate via `rectification.enabled: false` in project nax/config.json for self-dev runs. CI on VPS is the regression gate instead.
-  - **Target:** v0.19.0
->>>>>>> Stashed changes
+- [x] ~~**BUG-027:** `runPrecheck()` always prints to stdout — pollutes test output when called programmatically. Shipped in v0.18.2.~~
+- [x] ~~**BUG-028:** Routing cache ignores escalation tier — escalated stories re-run at original tier. Shipped in v0.18.3.~~
 - [x] ~~**BUG-016:** Hardcoded 120s timeout in pipeline verify stage → fixed in v0.18.0~~
 - [x] ~~**BUG-017:** run.complete not emitted on SIGTERM → fixed in v0.18.0~~
 - [x] ~~**BUG-018:** Test-writer wastes ~3min/retry when tests already exist → fixed in v0.18.0~~
@@ -220,9 +202,9 @@
 
 - [x] **BUG-029:** Escalation resets story to `pending` → bypasses BUG-022 retry priority. `handleTierEscalation()` sets `status: "pending"` after escalation, but `getNextStory()` Priority 1 only checks `status === "failed"`. Result: after BUG-026 escalated (iter 1), nax moved to BUG-028 (iter 2) instead of retrying BUG-026 immediately. **Location:** `src/prd/index.ts:getNextStory()` + `src/execution/escalation/tier-escalation.ts`. **Fix:** `getNextStory()` should also prioritize stories with `story.routing.modelTier` that changed since last attempt (escalation marker), or `handleTierEscalation` should use a distinct status like `"retry-pending"` that Priority 1 recognizes.
 - [x] **BUG-030:** Review lint failure → hard `"fail"`, no rectification or retry. `src/pipeline/stages/review.ts:92` returns `{ action: "fail" }` for all review failures including lint. In `pipeline-result-handler.ts`, `"fail"` calls `markStoryFailed()` — permanently dead. But lint errors are auto-fixable (agent can run `biome check --fix`). Contrast with verify stage which returns `"escalate"` on test failure, allowing retry. SFC-001 and SFC-002 both hit this — tests passed but 5 Biome lint errors killed the stories permanently. **Fix:** Review stage should return `"escalate"` (not `"fail"`) for lint/typecheck failures, or add a review-rectification loop (like verify has) that gives the agent one retry with the lint output as context. Reserve `"fail"` for unfixable review issues (e.g. plugin reviewer rejection).
-- [ ] **BUG-031:** Keyword fallback classifier gives inconsistent strategy across retries for same story. BUG-026 was classified as `test-after` on iter 1 (keyword fallback), but `three-session-tdd-lite` on iter 5 (same keyword fallback). The keyword classifier in `src/routing/strategies/keyword.ts:classifyComplexity()` may be influenced by `priorErrors` text added between attempts, shifting the keyword match result. **Location:** `src/routing/strategies/keyword.ts`. **Fix:** Keyword classifier should only consider the story's original title + description + acceptance criteria, not accumulated `priorErrors` or `priorFailures`. Alternatively, once a strategy is set in `story.routing.testStrategy`, the routing stage should preserve it across retries (already partially done in `routing.ts:40-41` but may not apply when LLM falls back to keyword).
+- [x] **BUG-031:** Keyword fallback classifier gives inconsistent strategy across retries for same story. BUG-026 was classified as `test-after` on iter 1 (keyword fallback), but `three-session-tdd-lite` on iter 5 (same keyword fallback). The keyword classifier in `src/routing/strategies/keyword.ts:classifyComplexity()` may be influenced by `priorErrors` text added between attempts, shifting the keyword match result. **Location:** `src/routing/strategies/keyword.ts`. **Fix:** Keyword classifier should only consider the story's original title + description + acceptance criteria, not accumulated `priorErrors` or `priorFailures`. Alternatively, once a strategy is set in `story.routing.testStrategy`, the routing stage should preserve it across retries (already partially done in `routing.ts:40-41` but may not apply when LLM falls back to keyword).
 - [x] **BUG-032:** Routing stage overrides escalated `modelTier` with complexity-derived tier. `src/pipeline/stages/routing.ts:43` always runs `complexityToModelTier(routing.complexity, config)` even when `story.routing.modelTier` was explicitly set by `handleTierEscalation()`. BUG-026 was escalated to `balanced` (logged in iteration header), but `Task classified` shows `modelTier=fast` because `complexityToModelTier("simple", config)` → `"fast"`. Related to BUG-013 (escalation routing not applied) which was marked fixed, but the fix in `applyCachedRouting()` in `pipeline-result-handler.ts:295-310` runs **after** the routing stage — too late. **Location:** `src/pipeline/stages/routing.ts:43`. **Fix:** When `story.routing.modelTier` is explicitly set (by escalation), skip `complexityToModelTier()` and use the cached tier directly. Only derive from complexity when `story.routing.modelTier` is absent.
-- [ ] **BUG-033:** LLM routing has no retry on timeout — single attempt with hardcoded 15s default. All 5 LLM routing attempts in the v0.18.3 run timed out at 15s, forcing keyword fallback every time. `src/routing/strategies/llm.ts:63` reads `llmConfig?.timeoutMs ?? 15000` but there's no retry logic — one timeout = immediate fallback. **Location:** `src/routing/strategies/llm.ts:callLlm()`. **Fix:** Add `routing.llm.retries` config (default: 1) with backoff. Also surface `routing.llm.timeoutMs` in `nax config --explain` and consider raising default to 30s for batch routing which processes multiple stories.
+- [x] **BUG-033:** LLM routing has no retry on timeout — single attempt with hardcoded 15s default. All 5 LLM routing attempts in the v0.18.3 run timed out at 15s, forcing keyword fallback every time. `src/routing/strategies/llm.ts:63` reads `llmConfig?.timeoutMs ?? 15000` but there's no retry logic — one timeout = immediate fallback. **Location:** `src/routing/strategies/llm.ts:callLlm()`. **Fix:** Add `routing.llm.retries` config (default: 1) with backoff. Also surface `routing.llm.timeoutMs` in `nax config --explain` and consider raising default to 30s for batch routing which processes multiple stories.
 
 ### Features
 - [x] ~~`nax unlock` command~~

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.18.3",
+  "version": "0.18.4",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {

package/src/config/schemas.ts

@@ -212,6 +212,8 @@ const LlmRoutingConfigSchema = z.object({
   mode: z.enum(["one-shot", "per-story", "hybrid"]).optional(),
   batchMode: z.boolean().optional(), // deprecated, for backward compat
   timeoutMs: z.number().int().positive({ message: "llm.timeoutMs must be > 0" }).optional(),
+  retries: z.number().int().min(0, { message: "llm.retries must be >= 0" }).optional(),
+  retryDelayMs: z.number().int().min(0, { message: "llm.retryDelayMs must be >= 0" }).optional(),
 });
 
 const RoutingConfigSchema = z

package/src/config/types.ts

@@ -365,8 +365,12 @@ export interface LlmRoutingConfig {
   mode?: LlmRoutingMode;
   /** @deprecated Use mode instead. Will be removed in v1.0 */
   batchMode?: boolean;
-  /** Timeout for LLM call in milliseconds (default: 15000) */
+  /** Timeout for LLM call in milliseconds (default: 30000) */
   timeoutMs?: number;
+  /** Number of retries on LLM timeout or transient failure (default: 1) */
+  retries?: number;
+  /** Delay between retries in milliseconds (default: 1000) */
+  retryDelayMs?: number;
 }
 
 /** Routing config */

package/src/execution/post-verify.ts

@@ -26,7 +26,7 @@ function buildStructuredFailure(
 ): StructuredFailure {
   const testFailures =
     verificationResult.status === "TEST_FAILURE" && verificationResult.output
-      ? parseBunTestOutput(verificationResult.output).failures.map((f) => ({
+      ? _postVerifyDeps.parseBunTestOutput(verificationResult.output).failures.map((f) => ({
           file: f.file,
           testName: f.testName,
           error: f.error,
@@ -121,9 +121,9 @@ export async function runPostAgentVerification(opts: PostVerifyOptions): Promise
   const testCommand = scopeTestCommand(config.quality.commands.test, changedTestFiles);
   const timeoutRetryCount = timeoutRetryCountMap.get(story.id) || 0;
 
-  const verificationResult = await runVerification({
+  const verificationResult = await _postVerifyDeps.runVerification({
     workingDirectory: workdir,
-    expectedFiles: getExpectedFiles(story),
+    expectedFiles: _postVerifyDeps.getExpectedFiles(story),
     command: testCommand,
     timeoutSeconds: config.execution.verificationTimeoutSeconds,
     forceExit: config.quality.forceExit,
@@ -141,7 +141,7 @@ export async function runPostAgentVerification(opts: PostVerifyOptions): Promise
   if (verificationResult.success) {
     logger?.info("verification", "Scoped verification passed");
     if (verificationResult.output) {
-      const analysis = parseTestOutput(verificationResult.output, 0);
+      const analysis = _postVerifyDeps.parseTestOutput(verificationResult.output, 0);
       if (analysis.passCount > 0) {
         logger?.debug("verification", "Scoped test results", {
           passCount: analysis.passCount,
@@ -175,7 +175,7 @@ export async function runPostAgentVerification(opts: PostVerifyOptions): Promise
       regressionVerificationResult,
       "Full-suite regression detected",
     );
-    const updatedPrd = await revertStoriesOnFailure({
+    const updatedPrd = await _postVerifyDeps.revertStoriesOnFailure({
       prd,
       prdPath,
       story,
@@ -193,7 +193,7 @@ export async function runPostAgentVerification(opts: PostVerifyOptions): Promise
   // Attempt rectification if enabled and tests failed (not timeout/env)
   const isTestFailure = verificationResult.status === "TEST_FAILURE" && verificationResult.output;
   if (rectificationEnabled && isTestFailure && verificationResult.output) {
-    const fixed = await runRectificationLoop({
+    const fixed = await _postVerifyDeps.runRectificationLoop({
       config,
       workdir,
       story,
@@ -222,7 +222,7 @@ export async function runPostAgentVerification(opts: PostVerifyOptions): Promise
   // Revert stories and save
   const diagnosticContext = verificationResult.error || `Verification failed: ${verificationResult.status}`;
   const verifyFailure = buildStructuredFailure(story, "verify", verificationResult, diagnosticContext);
-  const updatedPrd = await revertStoriesOnFailure({
+  const updatedPrd = await _postVerifyDeps.revertStoriesOnFailure({
     prd,
     prdPath,
     story,
@@ -263,9 +263,9 @@ async function runRegressionGate(
 
   logger?.info("regression-gate", "Running full-suite regression gate");
   const fullSuiteCommand = config.quality.commands.test ?? "bun test";
-  const regressionResult = await runVerification({
+  const regressionResult = await _postVerifyDeps.runVerification({
     workingDirectory: workdir,
-    expectedFiles: getExpectedFiles(story),
+    expectedFiles: _postVerifyDeps.getExpectedFiles(story),
     command: fullSuiteCommand,
     timeoutSeconds: config.execution.regressionGate.timeoutSeconds,
     forceExit: config.quality.forceExit,
@@ -297,7 +297,7 @@ async function runRegressionGate(
   // Attempt rectification on regression failures
   const isTestFailure = regressionResult.status === "TEST_FAILURE" && regressionResult.output;
   if (rectificationEnabled && isTestFailure && regressionResult.output) {
-    const fixed = await runRectificationLoop({
+    const fixed = await _postVerifyDeps.runRectificationLoop({
       config,
       workdir,
       story,
@@ -321,10 +321,12 @@ function checkEnvironmentalEscalation(
   logger: ReturnType<typeof getSafeLogger>,
 ): void {
   const currentTier = story.routing?.modelTier || config.autoMode.escalation.tierOrder[0]?.tier;
-  const tierCfg = currentTier ? getTierConfig(currentTier, config.autoMode.escalation.tierOrder) : undefined;
+  const tierCfg = currentTier
+    ? _postVerifyDeps.getTierConfig(currentTier, config.autoMode.escalation.tierOrder)
+    : undefined;
   if (!tierCfg) return;
 
-  const threshold = getEnvironmentalEscalationThreshold(
+  const threshold = _postVerifyDeps.getEnvironmentalEscalationThreshold(
     tierCfg.attempts,
     config.quality.environmentalEscalationDivisor,
   );
@@ -336,3 +338,19 @@ function checkEnvironmentalEscalation(
     });
   }
 }
+
+/**
+ * Swappable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
+ */
+export const _postVerifyDeps = {
+  parseBunTestOutput,
+  parseTestOutput,
+  runVerification,
+  getExpectedFiles,
+  savePRD,
+  revertStoriesOnFailure,
+  runRectificationLoop,
+  appendProgress,
+  getTierConfig,
+  getEnvironmentalEscalationThreshold,
+};