@nathapp/nax 0.18.1

package/docs/20260221-fix-plan-routing-mode.md

@@ -0,0 +1,125 @@
+# Fix Plan: Configurable LLM Routing Mode
+
+**Date:** 2026-02-21
+**Branch:** `feat/v0.9-routing-mode`
+**Issue:** #2
+**Base:** `master` (`b459e9f`)
+
+## Context
+
+Current `batchMode: boolean` is a binary on/off. Issue #2 replaces it with
+`mode: "one-shot" | "per-story" | "hybrid"` for fine-grained control.
+
+**Mode semantics:**
+- `one-shot`: batch-route ALL pending stories once at run start. If a story
+  is missing from cache at execution time, use keyword fallback (no new LLM call).
+  Minimises Claude sessions spawned (1 total). Eliminates hook noise.
+- `per-story`: route each story individually just before execution.
+  Current behaviour when `batchMode: false`. Max LLM calls = N stories.
+- `hybrid` (DEFAULT): batch-route upfront like one-shot, but on story
+  retry/failure, re-route that story individually. Best quality + cost balance.
+
+**Problem solved:** With LLM routing, Run H spawned 9+ separate Claude sessions
+for routing (one per story) causing hook noise and extra cost. One-shot or hybrid
+reduces this to 1 batch call.
+
+## Phase 1: Config Schema
+
+### Fix 1.1: Replace batchMode with mode enum
+**File:** `src/config/schema.ts`
+**Change:**
+- In `LlmRoutingConfig` interface: remove `batchMode?: boolean`, add `mode?: "one-shot" | "per-story" | "hybrid"`
+- In Zod schema: replace `batchMode: z.boolean().optional()` with
+  `mode: z.enum(["one-shot", "per-story", "hybrid"]).optional()`
+- Default value: `"hybrid"` (applied in defaults/config resolver)
+
+### Fix 1.2: Update config defaults
+**File:** `src/config/defaults.ts` (or wherever defaults are set)
+**Change:** Set `routing.llm.mode` default to `"hybrid"`.
+
+### Fix 1.3: Backward compat shim
+**File:** `src/config/resolver.ts` (or schema.ts transform)
+**Change:** If old `batchMode: true` is present, map to `mode: "one-shot"`.
+  If `batchMode: false`, map to `mode: "per-story"`. Log deprecation warning.
+
+**Commit:** `feat(config): replace routing.llm.batchMode with routing.llm.mode enum`
+
+## Phase 2: LLM Strategy — One-Shot Strict Cache
+
+### Fix 2.1: Add one-shot cache-miss behaviour
+**File:** `src/routing/strategies/llm.ts`
+**Change:** In `llmStrategy.route()` (the per-story routing call), check if mode
+is `one-shot`. If so and the story is NOT in cache → return keyword fallback
+result immediately without making a new LLM call.
+
+```typescript
+// In llmStrategy.route()
+if (config.routing.llm?.mode === "one-shot" && cachedDecisions.has(story.id)) {
+  return cachedDecisions.get(story.id)!;
+}
+if (config.routing.llm?.mode === "one-shot") {
+  // Cache miss in one-shot mode — fall back to keyword, no new LLM call
+  return keywordStrategy.route(context);
+}
+```
+
+### Fix 2.2: Export mode helper
+**File:** `src/routing/strategies/llm.ts`
+**Change:** Add `getCacheSize(): number` export for test verification.
+
+**Commit:** `feat(routing): one-shot mode skips per-story LLM calls on cache miss`
+
+## Phase 3: Runner — Wire Mode to Batch Trigger
+
+### Fix 3.1: Update tryLlmBatchRoute guard
+**File:** `src/execution/runner.ts`
+**Change:** Replace the `batchMode` guard with mode check:
+```typescript
+// OLD:
+if (config.routing.strategy !== "llm" || !config.routing.llm?.batchMode ...) return;
+// NEW:
+const mode = config.routing.llm?.mode ?? "hybrid";
+if (config.routing.strategy !== "llm" || mode === "per-story" ...) return;
+```
+
+### Fix 3.2: Hybrid re-route on failure
+**File:** `src/execution/runner.ts`
+**Change:** In story retry logic, when mode is `hybrid` and story failed:
+- Call `llmRouteBatch([story], ...)` to re-route just that story
+- This invalidates and refreshes its cache entry before the next attempt
+Look for where stories are retried (error handling after agent run) and inject the re-route call.
+
+### Fix 3.3: Log mode at run start
+**File:** `src/execution/runner.ts`
+**Change:** In the run-start logging block, include `routingMode` in the log entry.
+
+**Commit:** `feat(runner): wire routing mode to batch trigger and hybrid re-route`
+
+## Phase 4: Tests
+
+### Fix 4.1: Config schema tests
+**Change:** Test `mode` enum is accepted (`one-shot`, `per-story`, `hybrid`).
+Test backward compat: `batchMode: true` → `mode: "one-shot"`.
+Test default is `"hybrid"`.
+
+### Fix 4.2: LLM strategy tests
+**Change:** Test one-shot mode: after `routeBatch()`, a cache-miss story returns
+keyword fallback without making another LLM call.
+Test per-story mode: each story triggers individual LLM call.
+Test hybrid: upfront batch + per-story call on cache miss.
+
+### Fix 4.3: Runner integration tests (if any)
+**Change:** Verify `tryLlmBatchRoute` is called on `one-shot`/`hybrid` but not `per-story`.
+
+**Commit:** `test: add tests for routing mode config and one-shot/hybrid behaviour`
+
+## Test Strategy
+- Mode: test-after
+- Run `bun test` after each phase
+- Backward compat: existing configs with `batchMode: true` must still work
+
+## Commits
+1. `feat(config): replace routing.llm.batchMode with routing.llm.mode enum`
+2. `feat(routing): one-shot mode skips per-story LLM calls on cache miss`
+3. `feat(runner): wire routing mode to batch trigger and hybrid re-route`
+4. `test: add tests for routing mode config and one-shot/hybrid behaviour`

package/docs/20260221-review-v0.9-implementation.md

@@ -0,0 +1,379 @@
+# v0.9 Implementation Review
+
+**Date:** 2026-02-21
+**Reviewer:** code-reviewer agent (Opus 4.6)
+**Branches:** `feat/v0.9-relevantfiles-split` (Issue #1), `feat/v0.9-routing-mode` (Issue #2)
+**Test Status:** 710 pass, 2 skip, 6 fail (out of 718). All failures are pre-existing.
+
+---
+
+## Overall Grade: B+ (84/100)
+
+| Category           | Score | Max | Notes                                           |
+|--------------------|-------|-----|--------------------------------------------------|
+| Security           | 18    | 20  | No injection risks. Minor: mutation of raw config object in compat shim. |
+| Reliability        | 16    | 20  | Global config compat shim missing. Edge case with empty array fallback well-handled. |
+| API Design         | 18    | 20  | Clean resolver pattern. `LlmRoutingMode` enum well-designed. Minor JSDoc gap in `classifier.ts` bridge. |
+| Code Quality       | 16    | 20  | Good test coverage. `runner.ts` at 921 lines (exceeds 800 guideline). Mutation in `applyCachedRouting`. |
+| Best Practices     | 16    | 20  | Bun-native APIs used throughout. Immutability violated in 2 places. LLM prompt not updated in classifier. |
+
+---
+
+## Findings
+
+### CRITICAL
+
+None.
+
+### HIGH
+
+#### [HIGH-1] `applyBatchModeCompat` not applied to global config
+**File:** `/Users/subrinaai/Desktop/workspace/subrina-coder/projects/nax/repos/nax/src/config/loader.ts:99-102`
+**Branch:** `feat/v0.9-routing-mode`
+
+The backward compatibility shim `applyBatchModeCompat()` is called on `projConf` (line 111) but NOT on `globalConf` (line 100-101). If a user has `routing.llm.batchMode: true` in their global config (`~/.nax/config.json`) but no project config, the shim never runs.
+
+After `deepMerge` with defaults (which now set `mode: "hybrid"`), the `"mode" in llm` guard in `applyBatchModeCompat` would prevent mapping even if the shim were called later. But the root issue is that global-only users with `batchMode` will silently get `mode: "hybrid"` from defaults instead of the expected `mode: "one-shot"`.
+
+**Impact:** Users with global-only config using deprecated `batchMode: true` will get unexpected routing behavior. Silent behavior change with no deprecation warning.
+
+**Fix:**
+```typescript
+// In loadConfig(), after loading global config:
+const globalConf = await loadJsonFile<Record<string, unknown>>(globalConfigPath());
+if (globalConf) {
+  applyBatchModeCompat(globalConf); // <-- Add this line
+  rawConfig = deepMerge(rawConfig, globalConf);
+}
+```
+
+---
+
+#### [HIGH-2] `applyBatchModeCompat` mutates its argument
+**File:** `/Users/subrinaai/Desktop/workspace/subrina-coder/projects/nax/repos/nax/src/config/loader.ts:76-91`
+**Branch:** `feat/v0.9-routing-mode`
+
+The function mutates the `conf` object in-place (`llm.mode = ...`). While this works because the caller does not reuse the raw config, it violates the project's immutability guideline (from CLAUDE.md: "Immutable patterns -- avoid mutation"). The `deepMerge` function correctly uses spread operators; the compat shim should follow the same pattern.
+
+**Impact:** Low immediate risk (caller does not reuse), but sets a bad precedent and makes the code harder to reason about. Could cause subtle bugs if `loadConfig` is refactored to reuse partial configs.
+
+**Fix:**
+Return a new object instead of mutating, or document the intentional mutation:
+```typescript
+function applyBatchModeCompat(conf: Record<string, unknown>): Record<string, unknown> {
+  const routing = conf.routing as Record<string, unknown> | undefined;
+  const llm = routing?.llm as Record<string, unknown> | undefined;
+  if (llm && "batchMode" in llm && !("mode" in llm)) {
+    const batchMode = llm.batchMode;
+    if (typeof batchMode === "boolean") {
+      return {
+        ...conf,
+        routing: {
+          ...routing,
+          llm: {
+            ...llm,
+            mode: batchMode ? "one-shot" : "per-story",
+          },
+        },
+      };
+    }
+  }
+  return conf;
+}
+```
+
+---
+
+#### [HIGH-3] `applyCachedRouting` mutates the routing object
+**File:** `/Users/subrinaai/Desktop/workspace/subrina-coder/projects/nax/repos/nax/src/execution/runner.ts:77-86`
+**Branch:** `feat/v0.9-routing-mode` (pre-existing, but worsened by new code paths)
+
+The function directly mutates `routing.complexity`, `routing.modelTier`, and `routing.testStrategy`. This is called from the main loop and the routing object is reused as `pipelineContext.routing`. If any downstream code assumes the routing object is the original from `routeTask()`, it will get incorrect values.
+
+**Impact:** The mutation is currently "safe" because the routing object is scoped to a single iteration, but it makes the code fragile. The new hybrid re-route call at line 340 uses the `story` object (not the routing), so no immediate bug, but the pattern is error-prone.
+
+**Fix:**
+```typescript
+function applyCachedRouting(
+  routing: ReturnType<typeof routeTask>,
+  story: UserStory,
+  config: NaxConfig
+): ReturnType<typeof routeTask> {
+  if (!story.routing) return routing;
+  return {
+    ...routing,
+    ...(story.routing.complexity && {
+      complexity: story.routing.complexity,
+      modelTier: config.autoMode.complexityRouting[story.routing.complexity] ?? "balanced",
+    }),
+    ...(story.routing.testStrategy && {
+      testStrategy: story.routing.testStrategy,
+    }),
+  };
+}
+```
+
+---
+
+### MEDIUM
+
+#### [MED-1] `runner.ts` exceeds 800-line file size limit (921 lines)
+**File:** `/Users/subrinaai/Desktop/workspace/subrina-coder/projects/nax/repos/nax/src/execution/runner.ts`
+**Branch:** `feat/v0.9-routing-mode` (pre-existing, worsened by +12 lines)
+
+The file was already at 909 lines before this change. The new routing mode code adds 12 more lines (two `tryLlmBatchRoute` calls and `routingMode` variable). The CLAUDE.md guidelines state "200-400 lines typical, 800 max per file." This file is now 15% over limit.
+
+**Impact:** Reduced readability and maintainability. The acceptance retry loop (lines 669-853) alone is ~184 lines and could be extracted.
+
+**Fix:** Extract the acceptance retry loop into `src/execution/acceptance-runner.ts`. This is already identified as STYLE-1 in the project backlog.
+
+---
+
+#### [MED-2] LLM prompt in classifier still uses `relevantFiles` instead of `contextFiles`
+**File:** `/Users/subrinaai/Desktop/workspace/subrina-coder/projects/nax/repos/nax/src/analyze/classifier.ts:217`
+**Branch:** `feat/v0.9-relevantfiles-split`
+
+The LLM prompt template still instructs the model to output `"relevantFiles"` in its JSON response. The parser correctly maps `rawItem.relevantFiles` to `contextFiles`, creating an implicit bridge. However:
+1. This bridge is undocumented -- a future developer may update the prompt without updating the parser or vice versa.
+2. The raw JSON type at line 21 still declares `relevantFiles: unknown`, not `contextFiles`.
+
+**Impact:** Confusion for future maintainers. If someone updates the prompt to use `contextFiles`, the parser will break (it reads `rawItem.relevantFiles`).
+
+**Fix:** Either:
+- (a) Update the prompt to output `contextFiles` and update the parser accordingly.
+- (b) Add a code comment documenting the intentional bridge: `// BRIDGE: LLM prompt outputs "relevantFiles", mapped to contextFiles here. Update both together.`
+
+---
+
+#### [MED-3] LLM prompt in `claude.ts` agent updated but no backward compat for existing LLM outputs
+**File:** `/Users/subrinaai/Desktop/workspace/subrina-coder/projects/nax/repos/nax/src/agents/claude.ts:538-541`
+**Branch:** `feat/v0.9-relevantfiles-split`
+
+The `decompose()` method now reads `item.contextFiles` from the LLM response. If an older cached LLM response or a different LLM version outputs `relevantFiles`, the parser will set `contextFiles: []` (empty array from the `Array.isArray` fallback). The `getContextFiles()` resolver would then return `[]` instead of falling back to `relevantFiles`.
+
+**Impact:** Context injection silently breaks for any LLM response that uses the old field name. The probability is low since decompose is called interactively, but if responses are cached or replayed, context will be lost.
+
+**Fix:** Parse both fields with fallback:
+```typescript
+contextFiles: Array.isArray(item.contextFiles)
+  ? item.contextFiles
+  : Array.isArray(item.relevantFiles)
+    ? item.relevantFiles
+    : [],
+```
+
+---
+
+#### [MED-4] Module-level mutable cache (`cachedDecisions`) with no eviction policy
+**File:** `/Users/subrinaai/Desktop/workspace/subrina-coder/projects/nax/repos/nax/src/routing/strategies/llm.ts:16`
+**Branch:** `feat/v0.9-routing-mode` (pre-existing, now more relevant due to one-shot mode reliance on cache)
+
+The `cachedDecisions` Map grows without bound during a run. For one-shot mode, the cache is the primary data store -- if it is cleared unexpectedly (e.g., module reload in watch mode), all subsequent stories fall back to keyword routing.
+
+**Impact:** Memory accumulation for very large PRDs. More importantly, one-shot mode's correctness depends on cache integrity.
+
+**Fix:** Add a `maxCacheSize` guard or LRU eviction. Document the cache's role in one-shot mode.
+
+---
+
+#### [MED-5] `batchMode: false` + `mode: "one-shot"` conflict not validated
+**File:** `/Users/subrinaai/Desktop/workspace/subrina-coder/projects/nax/repos/nax/src/config/schema.ts:458-465`
+**Branch:** `feat/v0.9-routing-mode`
+
+A user can set both `batchMode: false` and `mode: "one-shot"` in their config. The compat shim only maps `batchMode` when `mode` is absent (guard: `!("mode" in llm)`), so when both are set, `mode` wins. But there is no validation warning for the contradictory combination. This can confuse users during migration.
+
+**Impact:** User confusion. `batchMode: false` semantically means "don't batch" but `mode: "one-shot"` means "batch everything once." No error or warning.
+
+**Fix:** Add a Zod `.refine()` to warn when both fields are set with contradictory values:
+```typescript
+const LlmRoutingConfigSchema = z.object({
+  // ...existing fields
+}).refine((data) => {
+  if (data.batchMode !== undefined && data.mode !== undefined) {
+    // Both set - check for contradiction
+    const implied = data.batchMode ? "one-shot" : "per-story";
+    if (implied !== data.mode) {
+      // Could log warning here
+    }
+  }
+  return true;
+});
+```
+
+---
+
+#### [MED-6] Duplicate log lines in iteration start
+**File:** `/Users/subrinaai/Desktop/workspace/subrina-coder/projects/nax/repos/nax/src/execution/runner.ts:385-403`
+**Branch:** `feat/v0.9-routing-mode` (pre-existing)
+
+Lines 385-392 log `"Starting iteration N"` with event name `"execution"`, and lines 395-403 log the same message with event name `"iteration.start"`. Both contain overlapping data. This was pre-existing but is worth noting as it inflates structured log output.
+
+**Impact:** Log noise. JSONL log files contain two near-identical entries per iteration.
+
+---
+
+### LOW
+
+#### [LOW-1] `getCacheSize()` exposed for testing only
+**File:** `/Users/subrinaai/Desktop/workspace/subrina-coder/projects/nax/repos/nax/src/routing/strategies/llm.ts:24-26`
+**Branch:** `feat/v0.9-routing-mode`
+
+The function is exported solely for testing (`/** Get the current cache size (for testing) */`). While harmless, it widens the public API surface for a test utility. Consider using Bun's test mocking or accessing the cache through the module's test exports pattern instead.
+
+**Impact:** Negligible. Minor API surface bloat.
+
+---
+
+#### [LOW-2] `fix-generator.ts` uses `contextFiles: []` instead of leaving field undefined
+**File:** `/Users/subrinaai/Desktop/workspace/subrina-coder/projects/nax/repos/nax/src/acceptance/fix-generator.ts:361`
+**Branch:** `feat/v0.9-relevantfiles-split`
+
+Setting `contextFiles: []` explicitly means `getContextFiles()` returns `[]` even if a parent process later sets `relevantFiles` on the story. This is technically correct (fix stories should not inherit context from parent stories), but the behavior depends on `[]` being truthy for `??` -- which is correct in JavaScript but could confuse developers unfamiliar with nullish coalescing semantics.
+
+**Impact:** Negligible. Behavior is correct.
+
+---
+
+#### [LOW-3] Missing JSDoc on `LlmRoutingMode` type
+**File:** `/Users/subrinaai/Desktop/workspace/subrina-coder/projects/nax/repos/nax/src/config/schema.ts:233-234`
+**Branch:** `feat/v0.9-routing-mode`
+
+The type has a one-line comment (`/** LLM routing mode */`) but no documentation of what each enum value means. The detailed documentation is on the `mode` field in `LlmRoutingConfig`, but the type itself should also document its values for consumers who import it directly.
+
+**Impact:** Minor developer experience issue.
+
+---
+
+#### [LOW-4] Test file backs up and restores global config
+**File:** `/Users/subrinaai/Desktop/workspace/subrina-coder/projects/nax/repos/nax/test/config-loader.test.ts:30-39`
+**Branch:** `feat/v0.9-routing-mode`
+
+The test manipulates the real global config at `~/.nax/config.json` using rename+restore. While the cleanup is in `afterEach`, a crash between backup and restore could leave the user's config in a broken state. Consider using a mock or environment variable to redirect the config path during tests.
+
+**Impact:** Test safety. If test runner crashes, user's global config is a backup file.
+
+---
+
+#### [LOW-5] Two empty lines between `deepMerge` and `applyBatchModeCompat`
+**File:** `/Users/subrinaai/Desktop/workspace/subrina-coder/projects/nax/repos/nax/src/config/loader.ts:73-74`
+**Branch:** `feat/v0.9-routing-mode`
+
+Minor formatting inconsistency -- double blank line where the rest of the file uses single blank lines between functions.
+
+**Impact:** Cosmetic.
+
+---
+
+## Backward Compatibility Assessment
+
+### Branch 1: `feat/v0.9-relevantfiles-split`
+
+| Scenario | Behavior | Correct? |
+|----------|----------|----------|
+| `contextFiles` set, `relevantFiles` unset | Uses `contextFiles` for context | Yes |
+| `contextFiles` unset, `relevantFiles` set | Falls back to `relevantFiles` for context | Yes |
+| Both `contextFiles` and `relevantFiles` set | Prefers `contextFiles` (nullish coalescing) | Yes |
+| Neither set | Returns empty array | Yes |
+| `expectedFiles` set | Uses for asset verification | Yes |
+| `expectedFiles` unset, `relevantFiles` set | Returns empty array (no fallback) | Yes, by design |
+| `expectedFiles: []` | Returns empty array (skips verification) | Yes |
+| LLM outputs `relevantFiles` in classify response | Mapped to `contextFiles` via bridge | Yes, but undocumented (MED-2) |
+| LLM outputs `relevantFiles` in decompose response | **Silently drops data** | No (MED-3) |
+
+### Branch 2: `feat/v0.9-routing-mode`
+
+| Scenario | Behavior | Correct? |
+|----------|----------|----------|
+| `mode: "one-shot"` | Batch upfront, keyword fallback on miss | Yes |
+| `mode: "per-story"` | Individual LLM call per story | Yes |
+| `mode: "hybrid"` | Batch upfront + re-route on escalation | Yes |
+| `mode` unset | Defaults to `"hybrid"` | Yes |
+| `batchMode: true`, `mode` unset (project config) | Maps to `mode: "one-shot"` | Yes |
+| `batchMode: false`, `mode` unset (project config) | Maps to `mode: "per-story"` | Yes |
+| `batchMode: true`, `mode: "per-story"` | `mode` wins (explicit takes precedence) | Yes |
+| `batchMode: true`, `mode` unset (global config only) | **Silently ignored, gets "hybrid"** | No (HIGH-1) |
+| `batchMode: "yes"` (invalid type) | Zod validation rejects | Yes |
+| `mode: "ultra-batch"` (invalid value) | Zod validation rejects | Yes |
+
+---
+
+## Test Coverage Assessment
+
+### Branch 1: `feat/v0.9-relevantfiles-split`
+
+| Test File | Tests Added | Coverage |
+|-----------|-------------|----------|
+| `test/prd-resolvers.test.ts` | 12 tests | Excellent: covers all fallback/precedence combinations |
+| `test/verification-asset-check.test.ts` | 9 tests | Excellent: covers opt-in semantics, legacy compat, dogfood scenarios |
+| `test/context-verification-integration.test.ts` | 6 tests | Good: end-to-end with temp files |
+| `test/context-integration.test.ts` | 3 tests added | Good: contextFiles, relevantFiles fallback, no-files |
+| `test/context.test.ts` | 3 tests added, 6 updated | Good: preference, fallback, limits |
+| `test/analyze-classifier.test.ts` | 1 updated | Adequate |
+
+**Missing coverage:**
+- No test for the `classifier.ts` bridge pattern where LLM outputs `relevantFiles` and it maps to `contextFiles`
+- No test for `claude.ts` decompose response with old `relevantFiles` field name
+
+### Branch 2: `feat/v0.9-routing-mode`
+
+| Test File | Tests Added | Coverage |
+|-----------|-------------|----------|
+| `test/config.test.ts` | 6 tests | Good: all three modes + invalid + deprecated |
+| `test/config-loader.test.ts` | 4 tests | Good: compat shim, precedence, invalid type, defaults |
+| `test/routing/llm-strategy.test.ts` | 5 tests | Good: one-shot miss, one-shot hit, per-story, hybrid, default |
+
+**Missing coverage:**
+- No test for `batchMode` in global config (HIGH-1)
+- No test for hybrid re-route in `runner.ts` (lines 339-341, 591-593) -- these are integration paths
+- No test for `batchMode: false` mapping to `mode: "per-story"` in isolation (the loader test only covers `batchMode: true`)
+
+---
+
+## Logic Correctness
+
+### `getContextFiles()` and `getExpectedFiles()` (Branch 1)
+
+The semantic split is correct and well-reasoned:
+- **contextFiles** = input to the agent (pre-execution context injection). Falls back to `relevantFiles` because existing PRDs should continue to provide context.
+- **expectedFiles** = output verification gate (post-execution asset check). Does NOT fall back because the old `relevantFiles` field was LLM-generated and unreliable for asset verification (documented in dogfood Run F findings).
+
+The `??` (nullish coalescing) operator is the correct choice here. An empty array `[]` is an explicit "no files" signal and should not trigger fallback. This is tested in `test/prd-resolvers.test.ts`.
+
+### Routing Mode Logic (Branch 2)
+
+The three-mode design is correct:
+
+1. **one-shot**: `tryLlmBatchRoute` runs at startup (line 208). On individual `route()`, cache hit returns cached decision; cache miss falls back to `keywordStrategy.route()` without an LLM call (line 380-386). This is cost-optimal for stable PRDs.
+
+2. **per-story**: `tryLlmBatchRoute` returns early when `mode === "per-story"` (line 60). Each `route()` call triggers an individual LLM call (lines 388-409). This is quality-optimal for dynamic PRDs.
+
+3. **hybrid**: `tryLlmBatchRoute` runs at startup (same as one-shot). On cache miss during `route()`, an individual LLM call is made (same as per-story). On escalation, `tryLlmBatchRoute` is called again for the escalated story (lines 339-341, 591-593). This combines upfront batching with retry precision.
+
+The `mode ?? "hybrid"` default is applied consistently in all three locations: `tryLlmBatchRoute` (line 59), `llmStrategy.route` (line 364), and `run()` (line 144).
+
+---
+
+## Priority Fix Order
+
+1. **HIGH-1**: Apply `applyBatchModeCompat` to global config -- prevents silent behavior regression for global-config-only users.
+2. **MED-3**: Add fallback for `relevantFiles` in `claude.ts` decompose parser -- prevents data loss from older LLM responses.
+3. **HIGH-2**: Refactor `applyBatchModeCompat` to return new object -- aligns with project immutability guidelines.
+4. **HIGH-3**: Refactor `applyCachedRouting` to return new object -- same rationale.
+5. **MED-2**: Document or fix the classifier bridge pattern -- prevents future maintainer confusion.
+6. **MED-5**: Add validation for contradictory `batchMode` + `mode` combinations.
+7. **MED-1**: Extract acceptance retry loop from `runner.ts` -- file size reduction.
+8. **LOW-4**: Mock global config path in tests instead of manipulating real file.
+
+---
+
+## Verdict
+
+**Approve with conditions (HIGH issues must be fixed before merge)**
+
+The v0.9 changes are well-structured with clear semantics, comprehensive test coverage, and proper backward compatibility design. The resolver function pattern (`getContextFiles`, `getExpectedFiles`) is clean and the three-mode routing enum is well-thought-out.
+
+However, three HIGH-priority issues need resolution before merge:
+1. Global config compat shim gap (HIGH-1) is a user-facing regression risk
+2. Two mutation patterns (HIGH-2, HIGH-3) violate project guidelines
+
+Once these are fixed, the changes are ready for v0.9.0 release.