@nathapp/nax 0.25.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

@@ -135,7 +135,17 @@
 
 ---
 
-## v0.25.0 — Trigger Completion
+## v0.26.0 — Routing Persistence ✅ Shipped (2026-03-08)
+
+- **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
@@ -239,6 +249,8 @@
 
 | 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) |

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

package/nax/status.json

@@ -1,27 +1,36 @@
 {
   "version": 1,
   "run": {
-    "id": "run-2026-03-07T13-49-17-400Z",
-    "feature": "trigger-completion",
-    "startedAt": "2026-03-07T13:49:17.400Z",
-    "status": "completed",
+    "id": "run-2026-03-07T16-14-49-336Z",
+    "feature": "routing-persistence",
+    "startedAt": "2026-03-07T16:14:49.336Z",
+    "status": "running",
     "dryRun": false,
-    "pid": 97007
+    "pid": 3412
   },
   "progress": {
-    "total": 6,
-    "passed": 6,
+    "total": 4,
+    "passed": 1,
     "failed": 0,
     "paused": 0,
     "blocked": 0,
-    "pending": 0
+    "pending": 3
   },
   "cost": {
-    "spent": 3.85387425,
+    "spent": 0.52230675,
     "limit": 8
   },
-  "current": null,
-  "iterations": 7,
-  "updatedAt": "2026-03-07T14:58:57.404Z",
-  "durationMs": 4180004
+  "current": {
+    "storyId": "RRP-002",
+    "title": "Add initialComplexity to StoryRouting and StoryMetrics for accurate reporting",
+    "complexity": "medium",
+    "tddStrategy": "test-after",
+    "model": "balanced",
+    "attempt": 1,
+    "phase": "routing"
+  },
+  "iterations": 2,
+  "updatedAt": "2026-03-07T16:45:19.261Z",
+  "durationMs": 1829925,
+  "lastHeartbeat": "2026-03-07T16:45:19.261Z"
 }

package/package.json

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

package/src/execution/iteration-runner.ts

@@ -66,6 +66,7 @@ export async function runIteration(
     stories: storiesToExecute,
     routing,
     workdir: ctx.workdir,
+    prdPath: ctx.prdPath,
     featureDir: ctx.featureDir,
     hooks: ctx.hooks,
     plugins: ctx.pluginRegistry,

package/src/metrics/aggregator.ts

@@ -110,7 +110,8 @@ export function calculateAggregateMetrics(runs: RunMetrics[]): AggregateMetrics
   >();
 
   for (const story of allStories) {
-    const complexity = story.complexity;
+    // Use initialComplexity (first-classify prediction) when available; fall back to complexity
+    const complexity = story.initialComplexity ?? story.complexity;
     const existing = complexityStats.get(complexity) || {
       predicted: 0,
       tierCounts: new Map<string, number>(),

package/src/metrics/tracker.ts

@@ -58,9 +58,14 @@ export function collectStoryMetrics(ctx: PipelineContext, storyStartTime: string
   const modelDef = modelEntry ? resolveModel(modelEntry) : null;
   const modelUsed = modelDef?.model || routing.modelTier;
 
+  // initialComplexity: prefer story.routing.initialComplexity (first classify),
+  // fall back to routing.complexity for backward compat
+  const initialComplexity = story.routing?.initialComplexity ?? routing.complexity;
+
   return {
     storyId: story.id,
     complexity: routing.complexity,
+    initialComplexity,
     modelTier: routing.modelTier,
     modelUsed,
     attempts,
@@ -108,20 +113,27 @@ export function collectBatchMetrics(ctx: PipelineContext, storyStartTime: string
   const modelDef = modelEntry ? resolveModel(modelEntry) : null;
   const modelUsed = modelDef?.model || routing.modelTier;
 
-  return stories.map((story) => ({
-    storyId: story.id,
-    complexity: routing.complexity,
-    modelTier: routing.modelTier,
-    modelUsed,
-    attempts: 1, // batch stories don't escalate individually
-    finalTier: routing.modelTier,
-    success: true, // if batch succeeded, all stories succeeded
-    cost: costPerStory,
-    durationMs: durationPerStory,
-    firstPassSuccess: true, // batch = first pass success
-    startedAt: storyStartTime,
-    completedAt: new Date().toISOString(),
-  }));
+  return stories.map((story) => {
+    // initialComplexity: prefer story.routing.initialComplexity (if individual routing exists),
+    // fall back to shared routing.complexity (batch stories classified together)
+    const initialComplexity = story.routing?.initialComplexity ?? routing.complexity;
+
+    return {
+      storyId: story.id,
+      complexity: routing.complexity,
+      initialComplexity,
+      modelTier: routing.modelTier,
+      modelUsed,
+      attempts: 1, // batch stories don't escalate individually
+      finalTier: routing.modelTier,
+      success: true, // if batch succeeded, all stories succeeded
+      cost: costPerStory,
+      durationMs: durationPerStory,
+      firstPassSuccess: true, // batch = first pass success
+      startedAt: storyStartTime,
+      completedAt: new Date().toISOString(),
+    };
+  });
 }
 
 /**

package/src/metrics/types.ts

@@ -12,6 +12,8 @@ export interface StoryMetrics {
   storyId: string;
   /** Classified complexity */
   complexity: string;
+  /** Initial complexity from first classification — preserved across escalations */
+  initialComplexity?: string;
   /** Initial model tier */
   modelTier: string;
   /** Actual model used (e.g., "claude-sonnet-4.5") */

package/src/pipeline/stages/routing.ts

@@ -2,15 +2,18 @@
  * Routing Stage
  *
  * Classifies story complexity and determines model tier + test strategy.
- * Uses cached complexity/testStrategy/modelTier from story if available.
+ * Uses cached complexity/testStrategy/modelTier from story if contentHash matches.
  * modelTier: uses escalated tier if explicitly set (BUG-032), otherwise derives from config.
  *
+ * RRP-003: contentHash staleness detection — if story.routing.contentHash is missing or
+ * does not match the current story content, treats cached routing as a miss and re-classifies.
+ *
  * @returns
  * - `continue`: Routing determined, proceed to next stage
  *
  * @example
  * ```ts
- * // Story has cached routing with complexity
+ * // Story has cached routing with matching contentHash
  * await routingStage.execute(ctx);
  * // ctx.routing: { complexity: "simple", modelTier: "fast", testStrategy: "test-after", reasoning: "..." }
  * // modelTier is derived from current config.autoMode.complexityRouting
@@ -19,7 +22,8 @@
 
 import { isGreenfieldStory } from "../../context/greenfield";
 import { getLogger } from "../../logger";
-import { complexityToModelTier, routeStory } from "../../routing";
+import { savePRD } from "../../prd";
+import { complexityToModelTier, computeStoryContentHash, routeStory } from "../../routing";
 import { clearCache, routeBatch } from "../../routing/strategies/llm";
 import type { PipelineContext, PipelineStage, RoutingResult, StageResult } from "../types";
 
@@ -30,11 +34,25 @@ export const routingStage: PipelineStage = {
   async execute(ctx: PipelineContext): Promise<StageResult> {
     const logger = getLogger();
 
-    // If story has cached routing, use cached values (escalated modelTier takes priority)
-    // Otherwise, perform fresh classification
+    // Staleness detection (RRP-003):
+    // - story.routing absent                   → cache miss (no prior routing)
+    // - story.routing + no contentHash         → legacy cache hit (manual / pre-RRP-003 routing, honor as-is)
+    // - story.routing + contentHash matches    → cache hit
+    // - story.routing + contentHash mismatches → cache miss (stale, re-classify)
+    const hasExistingRouting = ctx.story.routing !== undefined;
+    const hasContentHash = ctx.story.routing?.contentHash !== undefined;
+    let currentHash: string | undefined;
+    let hashMatch = false;
+    if (hasContentHash) {
+      currentHash = _routingDeps.computeStoryContentHash(ctx.story);
+      hashMatch = ctx.story.routing?.contentHash === currentHash;
+    }
+    const isCacheHit = hasExistingRouting && (!hasContentHash || hashMatch);
+
     let routing: { complexity: string; testStrategy: string; modelTier: string; reasoning?: string };
-    if (ctx.story.routing) {
-      // Use cached complexity/testStrategy/modelTier
+
+    if (isCacheHit) {
+      // Cache hit: legacy routing (no contentHash) or matching contentHash — use cached values
       routing = await _routingDeps.routeStory(ctx.story, { config: ctx.config }, ctx.workdir, ctx.plugins);
       // Override with cached values only when they are actually set
       if (ctx.story.routing?.complexity) routing.complexity = ctx.story.routing.complexity;
@@ -50,8 +68,22 @@ export const routingStage: PipelineStage = {
         );
       }
     } else {
-      // Fresh classification
+      // Cache miss: no routing, or contentHash present but mismatched — fresh classification
       routing = await _routingDeps.routeStory(ctx.story, { config: ctx.config }, ctx.workdir, ctx.plugins);
+      // currentHash already computed if a mismatch was detected; compute now if starting fresh
+      currentHash = currentHash ?? _routingDeps.computeStoryContentHash(ctx.story);
+      ctx.story.routing = {
+        ...(ctx.story.routing ?? {}),
+        complexity: routing.complexity as import("../../config").Complexity,
+        initialComplexity:
+          ctx.story.routing?.initialComplexity ?? (routing.complexity as import("../../config").Complexity),
+        testStrategy: routing.testStrategy as import("../../config").TestStrategy,
+        reasoning: routing.reasoning ?? "",
+        contentHash: currentHash,
+      };
+      if (ctx.prdPath) {
+        await _routingDeps.savePRD(ctx.prd, ctx.prdPath);
+      }
     }
 
     // BUG-010: Greenfield detection — force test-after if no test files exist
@@ -97,4 +129,6 @@ export const _routingDeps = {
   complexityToModelTier,
   isGreenfieldStory,
   clearCache,
+  savePRD,
+  computeStoryContentHash,
 };

package/src/pipeline/types.ts

@@ -65,6 +65,8 @@ export interface PipelineContext {
   routing: RoutingResult;
   /** Working directory (project root) */
   workdir: string;
+  /** Absolute path to the prd.json file (used by routing stage to persist initial classification) */
+  prdPath?: string;
   /** Feature directory (optional, e.g., nax/features/my-feature/) */
   featureDir?: string;
   /** Hooks configuration */

package/src/prd/types.ts

@@ -45,6 +45,10 @@ export interface StructuredFailure {
 /** Routing metadata per story */
 export interface StoryRouting {
   complexity: Complexity;
+  /** Initial complexity from first classification — written once, never overwritten by escalation */
+  initialComplexity?: Complexity;
+  /** Content hash of story fields at time of routing — used to detect stale cached routing (RRP-003) */
+  contentHash?: string;
   /** Model tier (derived at runtime from config, not persisted) */
   modelTier?: ModelTier;
   testStrategy: TestStrategy;

package/src/routing/content-hash.ts

@@ -0,0 +1,25 @@
+/**
+ * Story Content Hash
+ *
+ * Computes a deterministic hash of the story content fields used for routing.
+ * Used by the routing stage (RRP-003) to detect stale cached routing.
+ */
+
+import type { UserStory } from "../prd/types";
+
+/**
+ * Compute a deterministic hash of the story content fields used for routing.
+ * Hash input: title + "\0" + description + "\0" + acceptanceCriteria.join("") + "\0" + tags.join("")
+ *
+ * Null-byte separators between fields prevent cross-field collisions.
+ *
+ * @param story - The user story to hash
+ * @returns A hex string content hash
+ */
+export function computeStoryContentHash(story: UserStory): string {
+  const input = `${story.title}\0${story.description}\0${story.acceptanceCriteria.join("")}\0${story.tags.join("")}`;
+
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(input);
+  return hasher.digest("hex");
+}

package/src/routing/index.ts

@@ -15,3 +15,6 @@ export { keywordStrategy, llmStrategy, manualStrategy } from "./strategies";
 // Custom strategy loader
 export { loadCustomStrategy } from "./loader";
 export { tryLlmBatchRoute } from "./batch-route";
+
+// Content hash for staleness detection (RRP-003)
+export { computeStoryContentHash } from "./content-hash";