@nathapp/nax 0.18.1

package/docs/20260303-v010-implementation-plan.md

@@ -0,0 +1,165 @@
+# v0.10 Implementation Plan
+
+**Date:** 2026-03-03  
+**Branch:** `feat/v0.10-plugins`  
+**Base:** v0.9.3 (master, `d4562b2`)  
+
+## Test Strategy
+- Mode: hybrid
+- TDD targets: plugin types, plugin loader/validator, merger utility, optimizer interface
+- Test-after targets: pipeline integration, CLI commands, config schema updates
+
+## Phase 1: Plugin System Foundation (Types + Loader + Registry)
+
+### 1a: Plugin types and extension interfaces
+**Files:**
+- `src/plugins/types.ts` — `NaxPlugin`, `PluginType`, `PluginExtensions`, `IPromptOptimizer`, `IReviewPlugin`, `IContextProvider`, `IReporter` + event types
+- `src/plugins/index.ts` — public exports
+
+**Change:** Define all interfaces. `RoutingStrategy` and `AgentAdapter` already exist — reference them, don't duplicate.
+
+### 1b: Plugin validator
+**File:** `src/plugins/validator.ts`
+**Change:** `validatePlugin(module: unknown): NaxPlugin | null` — runtime type checks (name string, version string, provides array, matching extensions). Returns null + logs warning on invalid.
+
+### 1c: Plugin loader
+**File:** `src/plugins/loader.ts`
+**Change:** `loadPlugins(globalDir, projectDir, configPlugins)` — scan directories, import modules, validate, call setup(), return registry. Directory auto-discovery + explicit config modules.
+
+### 1d: Plugin registry
+**File:** `src/plugins/registry.ts`
+**Change:** `PluginRegistry` class with typed getters (`getOptimizers()`, `getRouters()`, etc.) and `teardownAll()`.
+
+### Tests:
+- `test/plugins/validator.test.ts` — valid/invalid plugin shapes
+- `test/plugins/loader.test.ts` — directory scan, module loading, validation
+- `test/plugins/registry.test.ts` — registration, getters, teardown
+
+**Commit:** `feat(plugins): add plugin system foundation (types, loader, registry)`
+
+## Phase 2: Config Layering (Global + Project + Deep Merge)
+
+### 2a: Config paths resolver
+**File:** `src/config/paths.ts`
+**Change:** `globalConfigDir()` → `~/.nax/`, `projectConfigDir(dir?)` → `<cwd>/nax/`. Handle XDG_CONFIG_HOME if set.
+
+### 2b: Deep merge utility
+**File:** `src/config/merger.ts`
+**Change:** `mergeConfigs(base, override)` — recursive object merge, arrays replace, `null` removes keys. Special handling: hooks and constitution concatenate via `skipGlobal` check.
+
+### 2c: Update loadConfig()
+**File:** `src/config/loader.ts` (modify existing)
+**Change:** Load global → project → merge → apply CLI flags. Update existing `loadConfig()` signature.
+
+### 2d: Zod schema updates
+**File:** `src/config/schema.ts` (modify existing)
+**Change:** Add `HooksConfig` (`skipGlobal`, `dir`), `ConstitutionConfig` (`path`, `skipGlobal`), `OptimizerConfig` (`enabled`, `strategy`, `strategies`), `PluginConfigEntry` (`module`, `config`), `plugins` array to root schema.
+
+### 2e: `nax init --global`
+**File:** `src/commands/init.ts` (modify existing)
+**Change:** Add `--global` flag. Creates `~/.nax/config.json` (with commented examples), `~/.nax/constitution.md`, `~/.nax/hooks/`.
+
+### 2f: Hook concatenation
+**File:** `src/hooks/loader.ts` (modify existing)
+**Change:** Load hooks from global dir first, then project dir. Both fire independently. Respect `skipGlobal`.
+
+### 2g: Constitution concatenation
+**File:** `src/constitution/loader.ts` (modify existing)
+**Change:** Prepend global constitution to project constitution with `---` separator. Respect `skipGlobal`.
+
+### Tests:
+- `test/config/merger.test.ts` — deep merge, null removal, array replace
+- `test/config/paths.test.ts` — path resolution
+- `test/config/loader.test.ts` — global+project merge integration
+- Update existing hook/constitution tests for concatenation
+
+**Commit:** `feat(config): add global config layering with deep merge`
+
+## Phase 3: Prompt Optimizer
+
+### 3a: Optimizer types + NoopOptimizer
+**Files:**
+- `src/optimizer/types.ts` — `IPromptOptimizer`, `PromptOptimizerInput`, `PromptOptimizerResult`
+- `src/optimizer/noop.optimizer.ts` — passthrough, zero savings
+- `src/optimizer/index.ts` — exports + `resolveOptimizer()` factory
+
+### 3b: RuleBasedOptimizer
+**File:** `src/optimizer/rule-based.optimizer.ts`
+**Rules:** `stripWhitespace`, `compactCriteria`, `deduplicateContext`, `maxPromptTokens`
+
+### 3c: Optimizer pipeline stage
+**File:** `src/pipeline/stages/optimizer.ts`
+**Change:** New stage between prompt and execution. Uses `resolveOptimizer()` which checks plugin registry first, then built-in strategy.
+
+### 3d: Wire optimizer stage into pipeline
+**File:** `src/pipeline/stages/index.ts` (modify)
+**Change:** Insert `optimizerStage` after `promptStage` in `defaultPipeline`.
+
+### Tests:
+- `test/optimizer/noop.test.ts`
+- `test/optimizer/rule-based.test.ts` — each rule individually + combined
+- `test/optimizer/stage.test.ts` — pipeline integration
+
+**Commit:** `feat(optimizer): add prompt optimization stage with rule-based optimizer`
+
+## Phase 4: Pipeline Integration + CLI
+
+### 4a: Add PluginRegistry to PipelineContext
+**File:** `src/pipeline/types.ts` (modify)
+**Change:** Add `plugins?: PluginRegistry` field.
+
+### 4b: Initialize plugins in runner
+**File:** `src/pipeline/runner.ts` (modify)
+**Change:** Load plugins at run start, pass registry to context, teardown at run end.
+
+### 4c: Wire plugin routers into routing chain
+**File:** `src/routing/chain.ts` or `src/routing/builder.ts` (modify)
+**Change:** Prepend plugin routers before built-in strategies.
+
+### 4d: Wire plugin reviewers into review stage
+**File:** `src/pipeline/stages/review.ts` (modify)
+**Change:** Run plugin reviewers after built-in checks.
+
+### 4e: Wire context providers into context stage
+**File:** `src/pipeline/stages/context.ts` (modify)
+**Change:** Append provider content after built context, within token budget.
+
+### 4f: Wire reporters into runner
+**File:** `src/pipeline/runner.ts` (modify)
+**Change:** Emit `onRunStart`, `onStoryComplete`, `onRunEnd` to all reporters.
+
+### 4g: `nax plugins list` CLI
+**File:** `src/commands/plugins.ts` (new)
+**Change:** Show loaded plugins with name, version, provides, source (global/project/config).
+
+### Tests:
+- Update existing pipeline/runner tests for plugin initialization
+- `test/commands/plugins.test.ts` — CLI output
+
+**Commit:** `feat(pipeline): integrate plugin system into pipeline + add plugins CLI`
+
+## Phase 5: Final Verification + Version Bump
+
+1. Run full test suite: `bun test`
+2. Run typecheck: `tsc --noEmit`
+3. Run lint: `eslint src/`
+4. Bump version to `0.10.0` in package.json
+5. Update CHANGELOG.md
+
+**Commit:** `chore: bump version to v0.10.0`
+
+---
+
+## Execution Plan
+
+| Phase | Target | Estimated Duration | Strategy |
+|:------|:-------|:------------------|:---------|
+| 1 | Mac01 (claude-monitor) | ~15 min | test-first for types + loader |
+| 2 | Mac01 (claude-monitor) | ~15 min | test-first for merger, test-after for wiring |
+| 3 | Mac01 (claude-monitor) | ~10 min | test-first for optimizers |
+| 4 | Mac01 (claude-monitor) | ~15 min | test-after for pipeline wiring |
+| 5 | Mac01 (claude-monitor) | ~5 min | verification only |
+
+All phases run sequentially on Mac01 via `claude-run.sh --phases`.
+
+**Branch strategy:** Single feature branch `feat/v0.10-plugins`, one commit per phase, squash merge to master.

package/docs/CLAUDE.md.bak

@@ -0,0 +1,191 @@
+# @nathapp/nax — AI Coding Agent Orchestrator
+
+Standalone CLI (Bun + TypeScript) that orchestrates AI coding agents with smart model routing, three-session TDD, and lifecycle hooks. NOT an OpenClaw skill — independent npm package.
+
+**CLI command:** `nax`
+
+## Commands
+
+```bash
+bun test              # Run all tests (bun:test)
+bun run typecheck     # TypeScript type checking (tsc --noEmit)
+bun run lint          # Biome linter (src/ bin/)
+bun run dev           # Run CLI locally
+bun run build         # Bundle for distribution
+```
+
+## Architecture
+
+```
+bin/nax.ts          # CLI entry point (commander)
+src/
+  agents/             # AgentAdapter interface + implementations (claude.ts)
+  cli/                # CLI commands (init, run, features, agents, status)
+  config/             # NaxConfig schema + layered loader + validation (global → project)
+  execution/          # Main orchestration loop (the core)
+  hooks/              # Lifecycle hooks (hooks.json → shell commands + NAX_* env)
+  pipeline/           # Pipeline orchestration utilities
+  prd/                # PRD/user-story loader, ordering, completion tracking
+  queue/              # Queue manager for multi-agent parallel execution
+  routing/            # Complexity classifier + test strategy decision tree
+  tdd/                # Three-session TDD types + file isolation checker + orchestrator
+test/                 # Bun test files (*.test.ts)
+```
+
+### Key Concepts
+
+- **Complexity Routing**: Tasks classified as simple/medium/complex/expert → mapped to model tiers (cheap/standard/premium)
+- **Three-Session TDD**: Session 1 (test-writer, only test files) → Session 2 (implementer, only source files) → Session 3 (verifier, auto-approves legitimate fixes)
+- **Isolation Enforcement**: Git diff verification between TDD sessions — test-writer can't touch source, implementer can't touch tests
+- **Hook System**: `hooks.json` maps lifecycle events (on-start, on-complete, on-pause, on-error, on-story-start, on-story-end) to shell commands
+- **Layered Config**: `~/.nax/config.json` (global) merged with `<project>/nax/config.json` (project overrides)
+
+### Pipeline Architecture (v0.3 target)
+
+The execution loop should be refactored from a monolithic `run()` into composable pipeline stages. This enables adding/removing/reordering stages without editing a 600+ line function.
+
+```typescript
+// src/pipeline/types.ts
+interface PipelineStage {
+  name: string;                                          // unique stage identifier
+  enabled: (ctx: PipelineContext) => boolean;             // skip if false
+  execute: (ctx: PipelineContext) => Promise<StageResult>; // do the work
+}
+
+interface PipelineContext {
+  config: NaxConfig;
+  prd: PRD;
+  story: UserStory;           // current story (or batch leader)
+  stories: UserStory[];       // batch (length 1 for single)
+  routing: RoutingResult;
+  workdir: string;
+  featureDir?: string;
+  hooks: HooksConfig;
+  // accumulated through stages
+  constitution?: string;
+  contextMarkdown?: string;
+  prompt?: string;
+  agentResult?: AgentResult;
+  reviewResult?: ReviewResult;
+}
+
+type StageResult =
+  | { action: 'continue' }                    // proceed to next stage
+  | { action: 'skip'; reason: string }        // skip this story
+  | { action: 'fail'; reason: string }        // mark story failed
+  | { action: 'escalate' }                    // retry with higher tier
+  | { action: 'pause'; reason: string }       // pause execution (queue command)
+```
+
+**Default pipeline stages (in order):**
+```typescript
+const defaultPipeline: PipelineStage[] = [
+  queueCheckStage,       // check for PAUSE/ABORT/SKIP commands
+  routingStage,          // classify complexity → model tier
+  constitutionStage,     // load & inject project constitution
+  contextStage,          // build file context from relevant sources
+  promptStage,           // assemble final prompt from story + context + constitution
+  executionStage,        // spawn agent session (single, batch, or TDD)
+  verifyStage,           // check agent output, tests pass
+  reviewStage,           // post-impl quality gate (typecheck/lint/test)
+  completionStage,       // mark story done, fire hooks, log progress
+];
+```
+
+**Design rules:**
+- Each stage is a separate file: `src/pipeline/stages/<name>.ts`
+- Stages communicate via `PipelineContext` — no side-channel state
+- The pipeline runner (`src/pipeline/runner.ts`) iterates stages, handles StageResult actions
+- The outer loop (load PRD → pick story → run pipeline → repeat) stays in `src/execution/runner.ts` but delegates per-story work to the pipeline
+- Hooks fire inside stages (e.g., `completionStage` fires `on-story-complete`), not in the outer loop
+- Config can override stage order or disable stages: `config.pipeline.stages`
+
+## Code Style
+
+- Bun-native APIs preferred (Bun.file, Bun.write, Bun.spawn, Bun.sleep)
+- Each module directory: `types.ts` (interfaces), implementation files, `index.ts` (barrel exports)
+- Immutable patterns — avoid mutation
+- No classes unless wrapping stateful adapters (like ClaudeCodeAdapter)
+- Functional style for pure logic (routing, classification, isolation checks)
+- Biome for formatting and linting
+
+## Testing
+
+- Test framework: `bun:test` (describe/test/expect)
+- Test files: `test/*.test.ts`
+- Test naming: `test/<module>.test.ts`
+- All routing/classification logic must have unit tests
+- Isolation checker must have unit tests
+- Run `bun test` before committing — all tests must pass
+
+## File Conventions
+
+- Max ~400 lines per file, split if larger
+- Types/interfaces in dedicated `types.ts` per module
+- Barrel exports via `index.ts` — import from module path, not deep paths
+- Config defaults co-located with schema (`DEFAULT_CONFIG` in `schema.ts`)
+
+## Current Status (v0.2.0-dev)
+
+**Tests:** 222 passing across 16 files, 504 assertions
+**Last Review:** 2026-02-17 — Grade B+ (82/100) — see `docs/20260217-post-impl-review.md`
+
+### Implemented (v0.1 → v0.2)
+- [x] Agent adapter interface + Claude Code implementation
+- [x] Config schema + layered loader + validation
+- [x] Hook lifecycle system + **command injection prevention** (SEC-1 ✅)
+- [x] Complexity-based routing + test strategy decision tree
+- [x] TDD isolation checker + three-session TDD orchestrator
+- [x] PRD loader/saver with dependency-aware ordering
+- [x] Execution runner with cost tracking
+- [x] Queue manager + **PAUSE/ABORT/SKIP commands** (v0.2 Phase 2 ✅)
+- [x] CLI: init, run, analyze, features create/list, agents, status
+- [x] **Story-scoped context extraction from PRD** (v0.2 Phase 1 ✅)
+- [x] **Explicit 3-tier escalation chain** fast→balanced→powerful (v0.2 Phase 3 ✅)
+- [x] **Story batching for simple stories** with --no-batch flag (v0.2 Phase 4 ✅)
+- [x] **Path validation + bounds checking** (SEC-2 ✅) — `src/config/path-security.ts`
+- [x] **Agent installation check + retry with exponential backoff** (BUG-1 partial ✅)
+- [x] **Atomic queue file handling** — rename-before-read pattern (BUG-2 ✅)
+- [x] **PRD size limits** — `maxStoriesPerFeature` config + validation (MEM-1 partial ✅)
+- [x] **Improved cost estimation** — structured output parsing + confidence (BUG-3 partial ✅)
+- [x] **Story dependency validation** in analyze command (BUG-6 ✅)
+- [x] **Hook timeout messages** — clear timeout vs failure distinction (BUG-5 ✅)
+
+### Remaining Issues (from review, by priority)
+
+#### P1 — Reliability
+- [ ] **MEM-1 (partial):** Lazy loading for large PRDs not implemented — only size limit validation exists. No memory pressure detection or streaming JSON parsing.
+- [ ] **PERF-1:** O(n²) batch story selection — not yet optimized with pre-computed eligible stories.
+- [ ] **BUG-3 (partial):** Cost estimation still falls back to duration-based guessing when structured output unavailable. No per-story confidence scores.
+
+#### P2 — Quality
+- [ ] **ENH-1:** JSDoc coverage ~40% — `src/agents/claude.ts` (1 JSDoc), `bin/nax.ts` (1 JSDoc) are underserved. Most exported functions in runner.ts have docs but `routeTask()`, `buildContext()`, `runThreeSessionTdd()` lack usage examples.
+- [ ] **TYPE-1:** Config loader still uses `as unknown as` double-casting (2 instances). No Zod runtime validation.
+- [ ] **BUG-4:** Batch failure still escalates only first story. No config option for batch-wide escalation.
+- [ ] **ENH-2:** No agent capability negotiation — adapters don't declare supported tiers/features.
+- [ ] **PERF-2:** PRD reloaded every iteration — no dirty flag optimization.
+- [ ] **ENH-3:** Context builder doesn't load file content — stories only, no source code context.
+
+#### P3 — Polish
+- [ ] **STYLE-1:** `runner.ts` is 901 lines (was 779, grew with fixes). Needs splitting into prompts/batching/queue-handler/escalation modules.
+- [ ] **ENH-4:** No progress bar or ETA display — only line-by-line iteration logging.
+- [ ] **TYPE-2:** `QueueCommand` still mixed string literals + object — not discriminated union.
+- [ ] **ENH-5:** No dry-run mode for three-session TDD.
+- [ ] **PERF-3:** Token estimation still uses `Math.ceil(text.length / 3)` — no improved heuristic.
+
+#### P4 — Consistency
+- [ ] **STYLE-2:** Inconsistent error handling patterns (throw vs return null vs log warning).
+- [ ] **STYLE-3:** Magic numbers not extracted as named constants.
+
+## Git
+
+- Conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`
+- Run `bun test && bun run typecheck` before committing
+- Keep commits atomic — one logical change per commit
+
+## Important
+
+- This is a Bun project — do NOT use Node.js APIs when Bun equivalents exist
+- Agent adapters spawn external processes — always handle timeouts and cleanup
+- Never hardcode API keys — agents use their own auth (e.g., Claude Code uses ANTHROPIC_API_KEY from env)
+- The execution runner has `[TODO]` markers for unimplemented agent spawning — that's the next priority

package/docs/ROADMAP.md

@@ -0,0 +1,165 @@
+# nax Roadmap
+
+> **Authoritative source** for planned and shipped versions.
+> Specs in `memory/` are detailed references. GitLab issues are supplementary.
+> Full release notes → `docs/releases/`
+
+---
+
+## Next: v0.18.0 — Orchestration Quality
+
+**Theme:** Fix execution bugs and improve orchestration reliability
+**Status:** 🔲 Planned
+
+### Bugfixes (Priority)
+- [x] ~~**BUG-016:** Hardcoded 120s timeout in verify stage → read from config~~
+- [x] ~~**BUG-017:** `run.complete` not emitted on SIGTERM → emit in crash handler~~
+- [x] ~~**BUG-018:** Test-writer spawns on every retry → skip when tests exist (`story.attempts > 0`)~~
+- [x] ~~**BUG-019:** Misleading TIMEOUT output preview → separate TIMEOUT vs TEST_FAILURE messaging~~
+- [x] ~~**BUG-020:** Missing storyId in JSONL events → audit all emitters~~
+- [x] ~~**BUG-021:** `Task classified` log shows raw LLM result, not final routing after cache/config override → log final routing only~~
+- [x] ~~**BUG-022:** Story interleaving wastes iterations — after failure, `getNextStory()` picks next pending story instead of retrying the failed one → prioritize current story retries before moving on~~
+- [x] ~~**BUG-023:** Agent failure doesn't log exitCode/stderr → add to `execution.Agent session failed` event~~
+- [x] ~~**BUG-025:** `needsHumanReview` doesn't trigger interactive plugin in headless mode → wire to interaction chain or suppress the log~~
+
+---
+
+## v0.18.1 — Type Safety + Per-Story testStrategy
+
+**Theme:** Fix all TypeScript/lint errors + fine-grained test strategy control
+**Status:** 🔲 Planned
+
+### TypeScript Fixes (60 errors across 21 files)
+- [ ] **TS-001:** Fix context module exports — add `BuiltContext`, `ContextElement`, `ContextBudget`, `StoryContext` to `context/types.ts` (13 errors)
+- [ ] **TS-002:** Fix config/command type safety — type `{}` → proper types in `config/loader.ts`, `commands/logs.ts`, `agents/claude.ts` (12 errors)
+- [ ] **TS-003:** Fix review/verification types — add `softViolations`, `warnings`, `description` to review result types (9 errors)
+- [ ] **TS-004:** Fix escalation PRD type construction — ensure escalation produces valid `PRD` objects (4 errors)
+- [ ] **TS-005:** Fix misc — Logger mock types, null checks, missing exports (`RectificationState`, `TestSummary`, `TestFailure`) (6 errors)
+
+### Lint Fixes (12 errors)
+- [ ] **LINT-001:** Run `biome check --fix` + manual review of unsafe fixes
+
+### Verify Stage Fix
+- [ ] **TEST-001:** Fix hanging "test command that throws error" test — add timeout or proper process kill
+
+### Per-Story testStrategy
+- [ ] Add optional `testStrategy` field to userStory PRD schema (`"test-after" | "three-session-tdd" | "three-session-tdd-lite"`)
+- [ ] When set, overrides global config + task classification for that story
+- [ ] Update routing stage to check `story.testStrategy` before config/LLM
+- [ ] Docs + tests
+
+### Re-enable Checks
+- [ ] Re-enable `typecheck` in `nax/config.json` review checks after TS fixes land
+
+---
+
+## v0.18.2 — Smart Test Runner + Bun PTY Migration
+
+**Theme:** Scope verify to changed files only + remove node-pty native addon
+**Status:** 🔲 Planned
+
+### 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
+
+### Bun PTY Migration (BUN-001)
+- [ ] Replace `node-pty` (native addon, requires python/make/g++ to build) with `Bun.Terminal` API (v1.3.5+)
+- [ ] Update `src/agents/claude.ts` `runInteractive()` — replace `nodePty.spawn()` with `Bun.Terminal`
+- [ ] Update `src/tui/hooks/usePty.ts` — replace `IPty` interface with Bun equivalent
+- [ ] Remove `node-pty` from `dependencies` in `package.json`
+- [ ] Remove `--ignore-scripts` workaround from `.gitlab-ci.yml`
+- [ ] Benefit: no native build, no gyp/python/gcc in CI, cleaner alpine support
+
+### CI Memory Optimization (CI-001)
+- [ ] Investigate splitting test suite into parallel jobs (unit / integration / ui) to reduce per-job peak memory
+- [ ] Evaluate `bun test --shard` when stable (currently experimental)
+- [ ] Target: make test suite pass on 1GB runners (currently requires 8GB shared runner)
+- [ ] Known constraints: 2008 tests across 125 files, ~75s on local VPS (3.8GB), OOMs even with `--smol --concurrency 1`
+- [ ] Current workaround: use `saas-linux-small-amd64` (8GB) shared runner
+
+---
+
+## v0.19.0 — Central Run Registry
+
+**Theme:** Unified run tracking across worktrees + dashboard integration
+**Status:** 🔲 Planned
+
+- [ ] **Central Run Registry** — `~/.nax/runs/<project>-<feature>-<runId>/` with status.json + events.jsonl symlink. Dashboard reads from registry.
+
+---
+
+## Shipped
+
+| Version | Theme | Date | Details |
+|:---|:---|:---|:---|
+| 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 |
+| v0.16.1 | Project Context Generator | 2026-03-01 | `nax generate`, auto-inject, multi-language |
+| v0.16.0 | Story Size Gate | 2026-03-01 | [releases/v0.16.0.md](releases/v0.16.0.md) |
+| v0.15.3 | Constitution Generator + Runner Interaction Wiring | 2026-02-28 | [releases/v0.15.3.md](releases/v0.15.3.md) |
+| v0.15.1 | Architectural Compliance + Security Hardening | 2026-02-28 | [releases/v0.15.1.md](releases/v0.15.1.md) |
+| v0.15.0 | Interactive Pipeline | 2026-02-28 | [releases/v0.15.0.md](releases/v0.15.0.md) |
+| v0.14.4 | Code Audit Cleanup (MEDIUM findings) | 2026-02-28 | [releases/v0.14.4.md](releases/v0.14.4.md) |
+| v0.14.3 | Code Audit Fixes (CRITICAL+HIGH+MEDIUM) | 2026-02-28 | [releases/v0.14.3.md](releases/v0.14.3.md) |
+| v0.14.2 | E2E Test Hang Fix | 2026-02-28 | [releases/v0.14.2.md](releases/v0.14.2.md) |
+| v0.14.1 | nax diagnose CLI | 2026-02-28 | [releases/v0.14.1.md](releases/v0.14.1.md) |
+| v0.14.0 | Failure Resilience | 2026-02-28 | [releases/v0.14.0.md](releases/v0.14.0.md) |
+| v0.13.0 | Precheck | 2026-02-27 | [releases/v0.13.0.md](releases/v0.13.0.md) |
+| v0.12.0 | Structured Logging | 2026-02-27 | [releases/v0.12.0.md](releases/v0.12.0.md) |
+| v0.11.0 and earlier | Plugin Integration, LLM Routing, Core Pipeline | 2026-02-27 | [releases/v0.11.0-and-earlier.md](releases/v0.11.0-and-earlier.md) |
+
+---
+
+## Backlog
+
+### Bugs
+- [x] ~~BUG-002: Orphan Claude processes~~
+- [x] ~~BUG-003: PRD status "done" not skipped~~
+- [x] ~~BUG-004: router.ts crashes on missing tags~~
+- [x] ~~BUG-005: Hardcoded `bun run lint` in review~~
+- [x] ~~BUG-006: Context auto-detection~~
+- [x] ~~BUG-008: E2E tests hang with infinite retry~~
+- [x] ~~BUG-009: No cross-story regression check~~
+- [x] ~~BUG-010: Greenfield TDD no test files~~
+- [x] ~~BUG-011: Escalation tier budget not enforced~~
+- [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-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~~
+- [x] ~~**BUG-019:** Misleading TIMEOUT output preview → fixed in v0.18.0~~
+- [x] ~~**BUG-020:** Missing storyId in JSONL events → fixed in v0.18.0~~
+- [x] ~~**BUG-021:** `Task classified` log shows raw LLM result, not final routing → fixed in v0.18.0~~
+- [x] ~~**BUG-022:** Story interleaving — `getNextStory()` round-robins instead of exhausting retries on current story → fixed in v0.18.0~~
+- [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~~
+
+### 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~~
+- [ ] Cost tracking dashboard
+- [ ] npm publish setup
+- [ ] `nax diagnose --ai` flag (LLM-assisted, future TBD)
+- [ ] **Auto-decompose oversized stories** — When story size gate triggers, offer via interaction chain to auto-decompose using `nax analyse`.
+- [ ] **AST-based context file detection** — replace keyword-matching with import/symbol graph analysis. Target: v0.19+
+- [ ] VitePress documentation site — full CLI reference, hosted as standalone docs (pre-publish requirement)
+
+---
+
+## Versioning
+
+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)*