@nathapp/nax 0.18.2 → 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/.gitlab-ci.yml

@@ -15,9 +15,11 @@ stages:
 # --- Stage: Test ---
 test:
   stage: test
-  image: nathapp/node-bun:22.21.0-1.3.9-alpine
+  image: 
+    name: nathapp/node-bun:22.21.0-1.3.9-alpine
+    pull_policy: if-not-present
   before_script:
-    - apk add --no-cache git python3 make g++
+    - apk add --no-cache git python3 make g++ 
     - git config --global safe.directory '*'
     - git config --global user.name "CI Runner"
     - git config --global user.email "ci@nathapp.io"
@@ -32,7 +34,7 @@ test:
     - bun install --frozen-lockfile --ignore-scripts
     - bun run typecheck
     - bun run lint
-    - NAX_SKIP_PRECHECK=1 bun test test/ --timeout=60000
+    - bun run test:unit
   rules:
     - if: '$CI_COMMIT_MESSAGE =~ /release-by-bot/ || $CI_COMMIT_TAG'
       when: never
@@ -43,7 +45,9 @@ test:
 # --- Stage: Release ---
 release:
   stage: release
-  image: nathapp/node-bun:22.21.0-1.3.9-alpine
+  image: 
+    name: nathapp/node-bun:22.21.0-1.3.9-alpine
+    pull_policy: if-not-present
   cache:
     key:
       files:
@@ -80,7 +84,9 @@ release:
 # --- Stage: Notify ---
 notify:
   stage: notify
-  image: registry-intl.cn-hongkong.aliyuncs.com/gkci/node:22.14.0-alpine-ci
+  image: 
+    name: registry-intl.cn-hongkong.aliyuncs.com/gkci/node:22.14.0-alpine-ci
+    pull_policy: if-not-present
   needs: [release]
   script:
     - VERSION=$(node -e "console.log(require('./package.json').version)")

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/bun.lock

@@ -18,7 +18,7 @@
       },
       "devDependencies": {
         "@biomejs/biome": "^1.9.4",
-        "@types/bun": "^1.2.4",
+        "@types/bun": "^1.3.8",
         "react-devtools-core": "^7.0.1",
         "typescript": "^5.7.3",
       },

package/bunfig.toml

@@ -8,4 +8,5 @@ timeout = 30000
 # Exclude nax dogfood feature directories (contain acceptance tests from nax runs, not source tests)
 exclude = ["nax/**"]
 
-# Note: E2E tests may override this with longer timeouts using test options
+[test]
+concurrent = 1

package/docker-compose.test.yml

@@ -0,0 +1,15 @@
+version: "3.9"
+services:
+  app:
+    image: nathapp/bun:1.3.8-ci
+    working_dir: /app
+    volumes:
+      - .:/app
+    command: >
+      sh -c "
+        bun install &&
+        bun run test:unit
+      "    
+    environment:
+      - NAX_SKIP_PRECHECK=1
+      - CI=true

package/docs/ROADMAP.md

@@ -50,18 +50,18 @@
 
 ---
 
-## v0.18.2 — Smart Test Runner + Bun PTY Migration
+## v0.18.2 — Smart Test Runner + Routing Fix ✅
 
-**Theme:** Scope verify to changed files only + remove node-pty native addon
-**Status:** 🔲 Planned
+**Theme:** Scope verify to changed files only + fix routing override
+**Status:** ✅ Shipped (2026-03-03)
 
 ### Smart Test Runner
-- [ ] After agent implementation, run `git diff --name-only` to get changed source files
-- [ ] Map source → test files by naming convention (`src/foo/bar.ts` → `test/unit/foo/bar.test.ts`)
-- [ ] Run only related tests for verify (instead of full suite)
-- [ ] Fallback to full suite when mapping yields no test files
-- [ ] Config flag `execution.smartTestRunner: true` (default: true) to opt out
-- [ ] Result: verify drops from ~125s to ~10-20s for typical single-file fixes
+- [x] ~~After agent implementation, run `git diff --name-only` to get changed source files~~
+- [x] ~~Map source → test files by naming convention (`src/foo/bar.ts` → `test/unit/foo/bar.test.ts`)~~
+- [x] ~~Run only related tests for verify (instead of full suite)~~
+- [x] ~~Fallback to full suite when mapping yields no test files~~
+- [x] ~~Config flag `execution.smartTestRunner: true` (default: true) to opt out~~
+- [x] ~~Result: verify drops from ~125s to ~10-20s for typical single-file fixes~~
 
 ### Bun PTY Migration (BUN-001)
 - [ ] Replace `node-pty` (native addon, requires python/make/g++ to build) with `Bun.Terminal` API (v1.3.5+)
@@ -80,12 +80,68 @@
 
 ---
 
-## v0.19.0 — Central Run Registry
+## v0.18.3 — Execution Reliability ✅
+
+**Theme:** Fix execution pipeline bugs (escalation, routing, review), structured failure context, and Smart Runner enhancement
+**Status:** ✅ Shipped (2026-03-04)
+**Spec:** [docs/specs/verification-architecture-v2.md](specs/verification-architecture-v2.md) (Phase 1)
+
+### Bugfixes — Completed
+- [x] **BUG-026:** Regression gate timeout → accept scoped pass + warn (not escalate). Config: `regressionGate.acceptOnTimeout: true`.
+- [x] **BUG-028:** Routing cache ignores escalation tier — `clearCacheForStory(storyId)` in `llm.ts`, called on tier escalation in both `preIterationTierCheck()` and `handleTierEscalation()`.
+
+### Structured Failure Context — Completed
+- [x] **SFC-001:** `StructuredFailure` type with `TestFailureContext[]` + `priorFailures?: StructuredFailure[]` on `UserStory`. Populated on verify, regression, rectification, and escalation failures.
+- [x] **SFC-002:** Format `priorFailures` into agent prompt at priority 95 via `createPriorFailuresContext()` in `context/builder.ts`.
+
+### Bugfixes — Completed (Round 2)
+- [x] **BUG-029:** Escalation resets story to `pending` → bypasses BUG-022 retry priority. After escalation, `getNextStory()` picks the next pending story instead of retrying the escalated one. **Location:** `src/prd/index.ts:getNextStory()`. **Fix:** Recognize escalated-pending stories in Priority 1 (e.g. check `story.routing.modelTier` changed, or use `"retry-pending"` status).
+- [x] **BUG-030:** Review lint/typecheck failure → hard `"fail"`, no rectification or retry. `review.ts:92` returns `{ action: "fail" }` → `markStoryFailed()` permanently. Lint errors are auto-fixable but story is killed with zero retry. **Fix:** Return `"escalate"` for lint/typecheck failures (or add review-rectification loop). Reserve `"fail"` for plugin reviewer rejection only.
+- [x] **BUG-032:** Routing stage overrides escalated `modelTier` with complexity-derived tier. `routing.ts:43` always runs `complexityToModelTier()` even when `story.routing.modelTier` was set by escalation → escalated tier silently ignored. BUG-013 fix (`applyCachedRouting`) runs too late. **Fix:** Skip `complexityToModelTier()` when `story.routing.modelTier` is explicitly set.
+
+### STR-007: Smart Test Runner Enhancement — Completed
+- [x] Configurable `testFilePatterns` in config (default: `test/**/*.test.ts`)
+- [x] `testFileFallback` config option: `"import-grep"` | `"full-suite"` (default: `"import-grep"`)
+- [x] 3-pass test discovery: path-convention → import-grep (grep test files for changed module name) → full-suite
+- [x] Config schema update: `execution.smartTestRunner` becomes object `{ enabled, testFilePatterns, fallback }` (backward compat: boolean coerced)
+
+---
+
+## v0.18.4 — Routing Stability ✅
 
-**Theme:** Unified run tracking across worktrees + dashboard integration
+**Theme:** Fix routing classifier consistency and LLM routing reliability
+**Status:** ✅ Shipped (2026-03-04)
+
+### Bugfixes
+- [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.
+
+---
+
+## v0.19.0 — Verification Architecture v2
+
+**Theme:** Eliminate duplicate test runs, deferred regression gate, structured escalation context
 **Status:** 🔲 Planned
+**Spec:** [docs/specs/verification-architecture-v2.md](specs/verification-architecture-v2.md) (Phase 2)
 
-- [ ] **Central Run Registry** — `~/.nax/runs/<project>-<feature>-<runId>/` with status.json + events.jsonl symlink. Dashboard reads from registry.
+### Remove Duplicate Test Execution
+- [ ] Pipeline verify stage is the single test execution point (Smart Test Runner)
+- [ ] Remove scoped re-test in `post-verify.ts` (duplicate of pipeline verify)
+- [ ] Review stage runs typecheck + lint only — remove `review.commands.test` execution
+
+### Deferred Regression Gate
+- [ ] New `src/execution/lifecycle/run-regression.ts` — run full suite once at run-end (not per-story)
+- [ ] Reverse Smart Test Runner mapping: failing test → source file → responsible story
+- [ ] Targeted rectification per responsible story with full failure context
+- [ ] Config: `execution.regressionGate.mode: "deferred" | "per-story" | "disabled"` (default `"deferred"`)
+- [ ] Call deferred regression in `run-completion.ts` before final metrics
+
+### Full Structured Failure Context
+- [ ] `priorFailures` injected into escalated agent prompts via `context/builder.ts`
+- [ ] Reverse file mapping for regression attribution
+
+### Central Run Registry (carried forward)
+- [ ] `~/.nax/runs/<project>-<feature>-<runId>/` with status.json + events.jsonl symlink
 
 ---
 
@@ -94,6 +150,9 @@
 | 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 |
 | v0.17.0 | Config Management | 2026-03-02 | CM-001 --explain, CM-002 --diff, CM-003 default view |
 | v0.16.4 | Bugfixes: Routing + Env Allowlist | 2026-03-02 | BUG-012/013/014 |
@@ -128,7 +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~~
-- [ ] **BUG-015:** `loadConstitution()` leaks global `~/.nax/constitution.md` into unit tests
+- [x] ~~**BUG-015:** `loadConstitution()` leaks global `~/.nax/constitution.md` into unit tests — fixed via `skipGlobal: true` in all unit tests~~
+- [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~~
@@ -139,12 +200,20 @@
 - [x] ~~**BUG-023:** Agent failure silent — no exitCode/stderr in JSONL → fixed in v0.18.0~~
 - [x] ~~**BUG-025:** `needsHumanReview` not triggering interactive plugin → fixed in v0.18.0~~
 
+- [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).
+- [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.
+- [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~~
 - [x] ~~Constitution file support~~
 - [x] ~~Per-story testStrategy override — v0.18.1~~
 - [x] ~~Smart Test Runner — v0.18.2~~
 - [x] ~~Central Run Registry — v0.19.0~~
+- [ ] **BUN-001:** Bun PTY Migration — replace `node-pty` with `Bun.Terminal` API
+- [ ] **CI-001:** CI Memory Optimization — parallel test sharding for 1GB runners
 - [ ] Cost tracking dashboard
 - [ ] npm publish setup
 - [ ] `nax diagnose --ai` flag (LLM-assisted, future TBD)
@@ -160,4 +229,4 @@ Sequential canary → stable: `v0.12.0-canary.0` → `canary.N` → `v0.12.0`
 Canary: `npm publish --tag canary`
 Stable: `npm publish` (latest)
 
-*Last updated: 2026-03-03 (v0.18.0 shipped — all 9 bugs fixed)*
+*Last updated: 2026-03-04 (v0.18.3 shipped; v0.18.4: BUG-031/033; v0.19.0: Verification Architecture v2)*