@nathapp/nax 0.24.0 → 0.26.0

package/CLAUDE.md

@@ -1,6 +1,16 @@
 # nax — AI Coding Agent Orchestrator
 
-Bun + TypeScript CLI that orchestrates AI coding agents with model routing, TDD strategies, and lifecycle hooks.
+Bun + TypeScript CLI that orchestrates AI coding agents (Claude Code) with model-tier routing, TDD strategies, plugin hooks, and a Central Run Registry.
+
+## Tech Stack
+
+| Layer | Choice |
+|:------|:-------|
+| Runtime | **Bun 1.3.7+** — Bun-native APIs only, no Node.js equivalents |
+| Language | **TypeScript strict** — no `any` without explicit justification |
+| Test | **`bun:test`** — describe/test/expect |
+| Lint/Format | **Biome** (`bun run lint`) |
+| Build | `bun run build` |
 
 ## Git Identity
 
@@ -11,14 +21,21 @@ git config user.email "subrina8080@outlook.com"
 
 ## Commands
 
-```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
-```
+| Command | Purpose |
+|:--------|:--------|
+| `bun run typecheck` | tsc --noEmit |
+| `bun run lint` | Biome |
+| `bun test test/unit/foo.test.ts` | Targeted test during iteration |
+| `NAX_SKIP_PRECHECK=1 bun test test/ --timeout=60000 --bail` | Full suite |
+
+nax runs lint, typecheck, and tests automatically via the pipeline. Run these manually only when working outside a nax session.
+
+## Engineering Persona
+
+- **Senior Engineer mindset**: check edge cases, null/undefined, race conditions, and error states.
+- **TDD first**: write or update tests before implementation when the story calls for it.
+- **Stuck rule**: if the same test fails 2+ iterations, stop, summarise failed attempts, reassess approach.
+- **Never push to remote** — the human reviews and pushes.
 
 ## Architecture
 
@@ -33,67 +50,64 @@ Runner.run()  [src/execution/runner.ts — thin orchestrator only]
   → registry.teardownAll()
 ```
 
-### Key Directories
+### Key Source Directories
 
 | Directory | Purpose |
-|:---|:---|
-| `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/execution/` | Runner loop, agent adapters, escalation, lifecycle hooks |
+| `src/execution/escalation/` | Tier escalation on repeated failures |
+| `src/pipeline/stages/` | One file per pipeline stage |
+| `src/pipeline/subscribers/` | Event-driven hooks (interaction, hooks.ts) |
+| `src/routing/` | Model-tier routing — keyword, LLM, plugin chain |
+| `src/routing/strategies/` | keyword.ts, llm.ts, llm-prompts.ts |
+| `src/interaction/` | Interaction triggers + plugins (Auto, Telegram, Webhook) |
 | `src/plugins/` | Plugin system — loader, registry, validator |
-| `src/config/` | Config schema, loader (layered global + project) |
+| `src/verification/` | Test execution, smart runner, scoped runner |
+| `src/metrics/` | StoryMetrics, aggregator, tracker |
+| `src/config/` | Config schema + layered loader (global → project) |
 | `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) |
+| `src/cli/` + `src/commands/` | CLI commands — check both locations |
+| `src/prd/` | PRD types, loader, story state machine |
+| `src/hooks/` | Lifecycle hook wiring |
+| `src/constitution/` | Constitution loader + injection |
+| `src/analyze/` | `nax analyze` — story classifier |
 
-### Plugin System (4 extension points)
+### Plugin Extension Points
 
-| Extension | Interface | Integration Point |
-|:---|:---|:---|
-| 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 |
+| Interface | Loaded By | Purpose |
+|:----------|:----------|:--------|
+| `IContextProvider` | `context.ts` stage | Inject context into agent prompts |
+| `IReviewer` | Review stage | Post-verify quality checks |
+| `IReporter` | Runner | onRunStart / onStoryComplete / onRunEnd events |
+| `IRoutingStrategy` | Router chain | Override model-tier routing |
 
 ### Config
 
 - Global: `~/.nax/config.json` → Project: `<workdir>/nax/config.json`
-- Schema: `src/config/schema.ts` — no hardcoded flags or credentials
+- Schema: `src/config/schema.ts` — no hardcoded flags or credentials anywhere
 
-## Design Principles
+## Workflow Protocol
 
-- **`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.
+1. **Explore first**: use `grep`, `cat`, and solograph MCP to understand context before writing code.
+2. **Plan complex tasks**: for multi-file changes, write a short plan before implementing.
+3. **Implement in small chunks**: one logical concern per commit.
 
-## Rules
+## Code Intelligence (Solograph MCP)
 
-Detailed coding standards, test architecture, and forbidden patterns are in `.claude/rules/`. Claude Code loads these automatically.
+Use **solograph** MCP tools on-demand — do not use `web_search` or `kb_search`.
 
+| Tool | When |
+|:-----|:-----|
+| `project_code_search` | Find existing patterns before writing new code |
+| `codegraph_explain` | Architecture overview before tackling unfamiliar areas |
+| `codegraph_query` | Dependency/impact analysis (Cypher) |
+| `project_code_reindex` | After creating or deleting source files |
 
-## Code Intelligence (Solograph MCP)
+## Coding Standards & Forbidden Patterns
+
+Full rules in `.claude/rules/` (loaded automatically):
 
-Use **solograph** MCP tools on-demand for code understanding. Do not use web_search, kb_search, or source_* tools.
-
-| Tool | When to use |
-|:-----|:------------|
-| `project_code_search` | Find existing patterns, symbols, or implementations before writing new code |
-| `codegraph_explain` | Get architecture overview of nax before tackling unfamiliar areas |
-| `codegraph_query` | Cypher queries — dependency analysis, impact analysis, hub files |
-| `codegraph_stats` | Quick graph stats (file/symbol counts) |
-| `codegraph_shared` | Find packages shared across projects |
-| `session_search` | Search prior Claude Code session history for relevant context |
-| `project_info` | Project registry info |
-| `project_code_reindex` | Reindex after creating or deleting source files, or major refactors |
-
-Single source of truth: VPS solograph instance (Mac01 tunnels to VPS — same data either way).
-## IMPORTANT
-
-- 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.
+- `01-project-conventions.md` — Bun-native APIs, 400-line limit, barrel imports, logging, commits
+- `02-test-architecture.md` — directory mirroring, placement rules, file naming
+- `03-test-writing.md` — `_deps` injection pattern, mock discipline, CI guards
+- `04-forbidden-patterns.md` — banned APIs and test anti-patterns with alternatives

package/docs/ROADMAP.md

@@ -118,34 +118,60 @@
 
 ---
 
-## v0.23.0 — Status File Consolidation
+## v0.23.0 — Status File Consolidation ✅
 
 **Theme:** Auto-write status.json to well-known paths, align readers, remove dead options
-**Status:** 🔄 In Progress (self-dev running, SFC-001 ✅)
+**Status:** ✅ Shipped (2026-03-07)
 **Spec:** [docs/specs/status-file-consolidation.md](specs/status-file-consolidation.md)
 **Pre-requisite for:** v0.24.0 (Central Run Registry)
 
 ### Stories
 - [x] ~~**SFC-001:** Auto-write project-level status — remove `--status-file` flag, always write to `<workdir>/nax/status.json`~~
-- [ ] **BUG-043:** Fix scoped test command construction + add `testScoped` config with `{{files}}` template
-- [ ] **BUG-044:** Log scoped and full-suite test commands at info level in verify stage
-- [ ] **SFC-002:** Write feature-level status on run end — copy final snapshot to `<workdir>/nax/features/<feature>/status.json`
-- [ ] **SFC-003:** Align status readers — `nax status` + `nax diagnose` read from correct paths
-- [ ] **SFC-004:** Clean up dead code — remove `--status-file` option, `.nax-status.json` references
+- [x] ~~**BUG-043:** Fix scoped test command construction + add `testScoped` config with `{{files}}` template~~
+- [x] ~~**BUG-044:** Log scoped and full-suite test commands at info level in verify stage~~
+- [x] ~~**SFC-002:** Write feature-level status on run end — copy final snapshot to `<workdir>/nax/features/<feature>/status.json`~~
+- [x] ~~**SFC-003:** Align status readers — `nax status` + `nax diagnose` read from correct paths~~
+- [x] ~~**SFC-004:** Clean up dead code — remove `--status-file` option, `.nax-status.json` references~~
 
 ---
 
-## v0.24.0 — Central Run Registry
+## v0.26.0 — Routing Persistence ✅ Shipped (2026-03-08)
 
-**Theme:** Global run index across all projects — single source of truth for all nax run history
+- **RRP-001:** Persist initial routing classification to `prd.json` on first classification
+- **RRP-002:** Add `initialComplexity` to `StoryRouting` and `StoryMetrics` for accurate reporting
+- **RRP-003:** Add `contentHash` to `StoryRouting` for staleness detection — stale cached routing is re-classified
+- **RRP-004:** Unit tests for routing persistence, idempotence, staleness, content hash, metrics
+- **BUG-052:** Replace `console.warn` with structured JSONL logger in `review/runner.ts` and `optimizer/index.ts`
+
+---
+
+## v0.25.0 — Trigger Completion ✅ Shipped (2026-03-07)
+
+**Theme:** Wire all 8 unwired interaction triggers, 3 missing hook events, and add plugin integration tests
 **Status:** 🔲 Planned
+**Spec:** [docs/specs/trigger-completion.md](specs/trigger-completion.md)
+
+### Stories
+- [ ] **TC-001:** Wire `cost-exceeded` + `cost-warning` triggers — fire at 80%/100% of cost limit in sequential-executor.ts
+- [ ] **TC-002:** Wire `max-retries` trigger — fire on permanent story failure via `story:failed` event in wireInteraction
+- [ ] **TC-003:** Wire `security-review`, `merge-conflict`, `pre-merge` triggers — review rejection, git conflict detection, pre-completion gate
+- [ ] **TC-004:** Wire `story-ambiguity` + `review-gate` triggers — ambiguity keyword detection, per-story human checkpoint
+- [ ] **TC-005:** Wire missing hook events — `on-resume`, `on-session-end`, `on-error` to pipeline events
+- [ ] **TC-006:** Auto plugin + Telegram + Webhook integration tests — mock LLM/network, cover approve/reject/HMAC flows
+
+---
+
+## v0.24.0 — Central Run Registry ✅
+
+**Theme:** Global run index across all projects — single source of truth for all nax run history
+**Status:** ✅ Shipped (2026-03-07)
 **Spec:** [docs/specs/central-run-registry.md](specs/central-run-registry.md)
 
 ### Stories
-- [ ] **CRR-000:** `src/pipeline/subscribers/events-writer.ts` — `wireEventsWriter()`, writes lifecycle events to `~/.nax/events/<project>/events.jsonl` (machine-readable completion signal for watchdog/CI)
-- [ ] **CRR-001:** `src/pipeline/subscribers/registry.ts` — `wireRegistry()` subscriber, listens to `run:started`, writes `~/.nax/runs/<project>-<feature>-<runId>/meta.json` (path pointers only — no data duplication, no symlinks)
-- [ ] **CRR-002:** `src/commands/runs.ts` — `nax runs` CLI, reads `meta.json` → resolves live `status.json` from `statusPath`, displays table (project, feature, status, stories, duration, date). Filters: `--project`, `--last`, `--status`
-- [ ] **CRR-003:** `nax logs --run <runId>` — resolve run from global registry via `eventsDir`, stream logs from any directory
+- [x] ~~**CRR-000:** `src/pipeline/subscribers/events-writer.ts` — `wireEventsWriter()`, writes lifecycle events to `~/.nax/events/<project>/events.jsonl` (machine-readable completion signal for watchdog/CI)~~
+- [x] ~~**CRR-001:** `src/pipeline/subscribers/registry.ts` — `wireRegistry()` subscriber, listens to `run:started`, writes `~/.nax/runs/<project>-<feature>-<runId>/meta.json` (path pointers only — no data duplication, no symlinks)~~
+- [x] ~~**CRR-002:** `src/commands/runs.ts` — `nax runs` CLI, reads `meta.json` → resolves live `status.json` from `statusPath`, displays table (project, feature, status, stories, duration, date). Filters: `--project`, `--last`, `--status`~~
+- [x] ~~**CRR-003:** `nax logs --run <runId>` — resolve run from global registry via `eventsDir`, stream logs from any directory~~
 
 ---
 
@@ -223,6 +249,10 @@
 
 | Version | Theme | Date | Details |
 |:---|:---|:---|:---|
+| v0.26.0 | Routing Persistence | 2026-03-08 | RRP-001–004: persist initial routing, initialComplexity, contentHash staleness detection, unit tests; BUG-052: structured logger in review/optimizer |
+| v0.25.0 | Trigger Completion | 2026-03-07 | TC-001–004: run.complete event, crash recovery, headless formatter, trigger completion |
+| v0.24.0 | Central Run Registry | 2026-03-07 | CRR-000–003: events writer, registry, nax runs CLI, nax logs --run global resolution |
+| v0.23.0 | Status File Consolidation | 2026-03-07 | SFC-001–004: auto-write status.json, feature-level status, align readers, remove dead code; BUG-043/044: testScoped config + command logging |
 | v0.18.1 | Type Safety + CI Pipeline | 2026-03-03 | 60 TS errors + 12 lint errors fixed, GitLab CI green (1952/56/0) |
 | v0.22.2 | Routing Stability + SFC-001 | 2026-03-07 | BUG-040 floating outputPromise crash on LLM timeout retry; SFC-001 auto-write status.json |
 | v0.22.1 | Pipeline Re-Architecture | 2026-03-07 | VerificationOrchestrator, EventBus, new stages (rectify/autofix/regression/deferred-regression), post-run SSOT. 2264 pass |
@@ -287,8 +317,8 @@
 
 - [x] ~~**BUG-037:** Test output summary (verify stage) captures precheck boilerplate instead of actual `bun test` failure. Fixed: `.slice(-20)` tail — shipped in v0.22.1 (re-arch phase 2).~~
 - [x] ~~**BUG-038:** `smart-runner` over-matching when global defaults change. Fixed by FEAT-010 (v0.21.0) — per-attempt `storyGitRef` baseRef tracking; `git diff <baseRef>..HEAD` prevents cross-story file pollution.~~
-- [ ] **BUG-043:** Scoped test command appends files instead of replacing path — `runners.ts:scoped()` concatenates `scopedTestPaths` to full-suite command, resulting in `bun test test/ --timeout=60000 /path/to/file.ts` (runs everything). Fix: use `testScoped` config with `{{files}}` template, fall back to `buildSmartTestCommand()` heuristic. **Location:** `src/verification/runners.ts:scoped()`
-- [ ] **BUG-044:** Scoped/full-suite test commands not logged — no visibility into what command was actually executed during verify stage. Fix: log at info level before execution.
+- [x] ~~**BUG-043:** Scoped test command appends files instead of replacing path — `runners.ts:scoped()` concatenates `scopedTestPaths` to full-suite command, resulting in `bun test test/ --timeout=60000 /path/to/file.ts` (runs everything). Fix: use `testScoped` config with `{{files}}` template, fall back to `buildSmartTestCommand()` heuristic. **Location:** `src/verification/runners.ts:scoped()`
+- [x] ~~**BUG-044:** Scoped/full-suite test commands not logged — no visibility into what command was actually executed during verify stage. Fix: log at info level before execution.
 
 ### Features
 - [x] ~~`nax unlock` command~~

package/docs/specs/trigger-completion.md

@@ -0,0 +1,145 @@
+# Trigger Completion — Spec
+
+**Version:** v0.25.0
+**Status:** Planned
+
+---
+
+## Problem
+
+8 of 9 interaction trigger helpers (`checkCostExceeded`, `checkCostWarning`, `checkMaxRetries`, `checkSecurityReview`, `checkMergeConflict`, `checkPreMerge`, `checkStoryAmbiguity`, `checkReviewGate`) are implemented in `src/interaction/triggers.ts` and exported but **never called** from the pipeline.
+
+Only `human-review` is wired (via `wireInteraction` subscriber on `human-review:requested` event).
+
+Additionally, 3 hook events (`on-resume`, `on-session-end`, `on-error`) are defined in `HookEvent` but not wired to any pipeline event.
+
+---
+
+## Goal
+
+Wire all 8 remaining triggers to the correct pipeline decision points. Add 3 missing hook events. Add E2E/integration test coverage for the Telegram and auto plugins.
+
+---
+
+## Stories
+
+### TC-001: Wire `cost-exceeded` and `cost-warning` triggers
+
+**Location:** `src/execution/sequential-executor.ts`
+
+Currently at line 93, when `totalCost >= config.execution.costLimit`, the run exits with `"cost-limit"` — no interaction trigger is fired.
+
+**Fix:**
+- Before exiting on cost limit: call `checkCostExceeded({featureName, cost, limit}, config, interactionChain)`. If trigger returns `abort` or chain not available → exit as today. Pass `interactionChain` into `executeSequential` ctx (already present in `SequentialExecutionContext`).
+- Add a `cost-warning` threshold check: when `totalCost >= costLimit * 0.8` (configurable via `interaction.triggers.cost-warning.threshold`, default 0.8), fire `checkCostWarning`. Fire only once per run (track with a boolean flag). Fallback: `continue`.
+- Emit new `run:paused` event if trigger response is `escalate` (pause for human decision).
+- Add `CostExceededEvent` and `CostWarningEvent` to `PipelineEventBus` (or reuse `run:paused` with a `reason` field — preferred, avoids new event types).
+
+**Acceptance criteria:**
+- When cost hits 80% of limit, `cost-warning` trigger fires once and run continues (default fallback)
+- When cost hits 100% of limit, `cost-exceeded` trigger fires; abort kills the run, skip/continue allows proceeding past limit
+- When no interaction plugin is configured, behavior is identical to today (no-op)
+- Tests: unit test both thresholds with mock chain
+
+---
+
+### TC-002: Wire `max-retries` trigger
+
+**Location:** `src/execution/sequential-executor.ts` or `src/pipeline/pipeline-result-handler.ts`
+
+Currently when a story exhausts all tier escalations and is marked failed permanently (`markStoryFailed`), no trigger fires (except `human-review` which fires on `human-review:requested` event for a different condition).
+
+**Fix:**
+- In the story failure path (after all escalations exhausted), call `checkMaxRetries({featureName, storyId, iteration}, config, interactionChain)`.
+- Response `skip` = proceed (today's behavior), `abort` = halt entire run, `escalate` = retry story from scratch at top tier.
+- Wire via `story:failed` event in `wireInteraction` subscriber (add alongside `human-review:requested`).
+
+**Acceptance criteria:**
+- `max-retries` trigger fires when a story is permanently failed
+- `abort` response halts the run with exit reason `"interaction-abort"`
+- `skip` response is silent (today's behavior)
+- Tests: unit test with mock chain for all three fallbacks
+
+---
+
+### TC-003: Wire `security-review`, `merge-conflict`, `pre-merge` triggers
+
+**Location:** `src/pipeline/stages/review.ts` and `src/pipeline/stages/completion.ts` (post-story)
+
+- **`security-review`**: Fire after plugin reviewer (e.g. semgrep) rejects a story in `review.ts`. Currently returns `{ action: "fail" }`. Before failing permanently, call `checkSecurityReview`. Response `abort` = fail (today), `escalate` = retry with security context injected.
+- **`merge-conflict`**: Fire when git operations detect a merge conflict during story commit. Currently no merge-conflict detection exists — add detection in `src/execution/git.ts` (catch `CONFLICT` in git merge/rebase output) and call `checkMergeConflict`.
+- **`pre-merge`**: Fire after all stories pass but before the run is marked complete. Call `checkPreMerge({featureName, totalStories, cost}, config, interactionChain)` in `sequential-executor.ts` final block. Response `abort` = halt, `continue` = complete normally.
+
+**Acceptance criteria:**
+- `security-review` trigger fires when plugin reviewer rejects (not when lint/typecheck fails)
+- `merge-conflict` trigger fires when git detects CONFLICT markers
+- `pre-merge` trigger fires once after all stories pass, before run:completed
+- Tests: unit tests for each trigger point with mock chain
+
+---
+
+### TC-004: Wire `story-ambiguity` and `review-gate` triggers
+
+**Location:** `src/pipeline/stages/execution.ts`
+
+- **`story-ambiguity`**: Fire when agent session returns ambiguous/clarification-needed signal. Currently the agent exit codes and output are parsed in `execution.ts` — add a detection heuristic (e.g. agent output contains "unclear" / "ambiguous" / "need clarification" keywords, or a new `needsClarification` flag in agent result). Call `checkStoryAmbiguity` before escalating.
+- **`review-gate`**: Fire after `story:completed` as a human checkpoint gate (configurable, disabled by default). Wire via new `review-gate:requested` event emitted in completion stage when `interaction.triggers.review-gate.enabled = true`.
+
+**Acceptance criteria:**
+- `story-ambiguity` trigger fires when agent signals ambiguity (keyword detection)
+- `review-gate` trigger fires after each story passes when enabled
+- Both default to disabled in config (opt-in)
+- Tests: unit tests for ambiguity detection heuristic + trigger dispatch
+
+---
+
+### TC-005: Wire missing hook events (`on-resume`, `on-session-end`, `on-error`)
+
+**Location:** `src/pipeline/subscribers/hooks.ts`
+
+Three hook events are defined in `HookEvent` but never wired to pipeline events:
+
+- **`on-resume`**: Fire when a paused run resumes. Add `run:resumed` event to `PipelineEventBus`, emit it in `sequential-executor.ts` when resuming from pause state. Wire in `wireHooks`.
+- **`on-session-end`**: Fire when an individual agent session ends (pass or fail). Map to `story:completed` + `story:failed`. Wire in `wireHooks` on both events.
+- **`on-error`**: Fire on unhandled errors / crash. Emit in `crash-recovery.ts` crash handler. Wire in `wireHooks`.
+
+**Acceptance criteria:**
+- `on-resume` hook fires when a paused run is continued
+- `on-session-end` hook fires after every agent session (pass or fail)
+- `on-error` hook fires in crash handler before exit
+- Tests: extend existing `hooks.test.ts` with the three new events
+
+---
+
+### TC-006: Auto plugin integration tests
+
+**Location:** `test/integration/interaction/`
+
+The `AutoInteractionPlugin` (LLM-based) has zero test coverage. The Telegram and Webhook plugins have init/config tests but no send/receive flow tests.
+
+**Fix:**
+- `auto.test.ts` — mock the LLM call (`_deps` pattern), test: approve decision, reject decision, confidence below threshold falls back, `security-review` is never auto-approved.
+- Extend `interaction-plugins.test.ts` with Telegram send flow (mock `fetch`, verify message format + inline keyboard structure).
+- Extend with Webhook send flow (mock HTTP server, verify HMAC signature validation).
+
+**Acceptance criteria:**
+- Auto plugin: LLM approve/reject/confidence-fallback/security-review-block all covered
+- Telegram: message send format and inline keyboard structure verified
+- Webhook: HMAC verification tested (valid + tampered signatures)
+- All tests are unit/mock — no real network calls
+
+---
+
+## Out of Scope
+
+- Full E2E test with real Telegram bot (requires live credentials)
+- New trigger types beyond the 9 already defined
+- Interaction state persistence (pause/resume full flow) — separate feature
+
+---
+
+## Notes
+
+- All trigger calls must be best-effort guarded: if `interactionChain` is null/undefined, skip silently (today's behavior)
+- `interactionChain` is already threaded through `SequentialExecutionContext` — no new context changes needed for most stories
+- Config `interaction.triggers.<name>.enabled` must be `true` for any trigger to fire (`isTriggerEnabled` handles this)

package/nax/features/routing-persistence/prd.json

@@ -0,0 +1,104 @@
+{
+  "project": "nax-routing-persistence",
+  "branchName": "feat/routing-persistence",
+  "feature": "routing-persistence",
+  "userStories": [
+    {
+      "id": "RRP-001",
+      "title": "Persist initial routing to prd.json on first classification",
+      "description": "Currently, when nax run classifies a story for the first time (no prior nax analyze, story.routing is undefined), the result lives only in ctx.routing (in-memory). If the run crashes and resumes, the routing stage re-classifies fresh — LLM may return different complexity/testStrategy, causing silent inconsistency mid-feature. Fix: after fresh classification in routing.ts, write the result back to prd.json via savePRD so story.routing is populated from the very first iteration.",
+      "acceptanceCriteria": [
+        "When story.routing is undefined before routing stage, after classification story.routing is written to prd.json",
+        "Subsequent iterations (or resume after crash) use the persisted story.routing — no re-classification",
+        "Escalation still overwrites modelTier and testStrategy as before — only initialComplexity is protected",
+        "savePRD is called once per story on first classification (not on every iteration if already persisted)",
+        "Unit tests verify prd.json is updated after first routing stage execution"
+      ],
+      "complexity": "medium",
+      "status": "passed",
+      "tags": [],
+      "dependencies": [],
+      "escalations": [],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "storyPoints": 1,
+      "passes": true
+    },
+    {
+      "id": "RRP-002",
+      "title": "Add initialComplexity to StoryRouting and StoryMetrics for accurate reporting",
+      "description": "StoryMetrics.complexity currently captures ctx.routing.complexity at completion time — which may reflect a post-escalation re-classification, not the original prediction. Add story.routing.initialComplexity (written once at first classify, never overwritten) and StoryMetrics.initialComplexity. Update metrics/aggregator.ts complexityAccuracy to compare initialComplexity vs finalTier instead of current complexity vs finalTier.",
+      "acceptanceCriteria": [
+        "StoryRouting interface gains initialComplexity?: Complexity field",
+        "Routing stage writes initialComplexity when story.routing is first created (RRP-001 path)",
+        "Escalation path never overwrites initialComplexity — only modelTier and testStrategy change",
+        "StoryMetrics gains initialComplexity?: string field",
+        "collectStoryMetrics() reads initialComplexity from story.routing.initialComplexity (falls back to routing.complexity for backward compat)",
+        "metrics/aggregator.ts complexityAccuracy uses initialComplexity for predicted vs finalTier comparison",
+        "Unit tests verify initialComplexity is set on first classify and unchanged after escalation"
+      ],
+      "complexity": "medium",
+      "status": "pending",
+      "tags": [],
+      "dependencies": [
+        "RRP-001"
+      ],
+      "escalations": [],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "storyPoints": 1
+    },
+    {
+      "id": "RRP-003",
+      "title": "Add contentHash to StoryRouting for staleness detection (BUG-048)",
+      "description": "When nax analyze is run, it writes story.routing to prd.json. If the story is subsequently edited (more ACs, changed tags, updated description), nax run blindly trusts the existing routing — wrong complexity, wrong testStrategy. Fix: add story.routing.contentHash — a hash of title+description+acceptanceCriteria.join()+tags.join() written at classify time. Routing stage recomputes hash on each run; if mismatch, treat as cache miss and re-classify.",
+      "acceptanceCriteria": [
+        "StoryRouting interface gains contentHash?: string field",
+        "A helper function computeStoryContentHash(story: UserStory): string computes a hash of title+description+ACs+tags",
+        "Routing stage: if story.routing exists but contentHash is missing or mismatches current story content, re-classify (treat as cache miss)",
+        "Routing stage: after classification, write contentHash to story.routing",
+        "If story content unchanged, routing stage uses cached routing as before — no regression",
+        "Unit tests cover: hash match uses cache; hash mismatch re-classifies; missing hash re-classifies"
+      ],
+      "complexity": "medium",
+      "status": "pending",
+      "tags": [],
+      "dependencies": [
+        "RRP-001"
+      ],
+      "escalations": [],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "storyPoints": 1
+    },
+    {
+      "id": "RRP-004",
+      "title": "Integration tests: routing persistence across simulated crash-resume and staleness",
+      "description": "Write integration tests that verify routing persistence end-to-end: (1) first run classifies and persists story.routing to prd.json, (2) second run uses persisted routing without re-classifying, (3) escalation preserves initialComplexity, (4) story content change triggers re-classification via contentHash mismatch.",
+      "acceptanceCriteria": [
+        "Integration test: routing stage with story.routing=undefined writes story.routing to prd.json after classification",
+        "Integration test: routing stage re-run with same prd.json uses cached routing — no LLM call made",
+        "Integration test: escalation updates modelTier in prd.json but initialComplexity remains unchanged",
+        "Integration test: edit story content after routing — hash mismatch detected — routing stage re-classifies",
+        "Integration test: story.routing with matching contentHash — no re-classification (cache hit confirmed)"
+      ],
+      "complexity": "medium",
+      "status": "pending",
+      "tags": [],
+      "dependencies": [
+        "RRP-001",
+        "RRP-002",
+        "RRP-003"
+      ],
+      "escalations": [],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "storyPoints": 1
+    }
+  ],
+  "updatedAt": "2026-03-07T16:32:39.496Z"
+}

package/nax/features/routing-persistence/progress.txt

@@ -0,0 +1 @@
+[2026-03-07T16:32:39.495Z] RRP-001 — PASSED — Persist initial routing to prd.json on first classification — Cost: $0.5223