@nathapp/nax 0.28.0 → 0.30.0

package/docs/specs/trigger-completion.md

@@ -1,145 +0,0 @@
-# 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/docs/specs/verification-architecture-v2.md

@@ -1,343 +0,0 @@
-# Verification Architecture v2
-
-**Status:** Proposal
-**Target:** v0.19.0
-**Author:** Nax Dev
-**Date:** 2026-03-04
-**Fixes:** BUG-026, BUG-028, plus architectural debt in verification pipeline
-
----
-
-## 1. Problems with Current Architecture
-
-### 1.1 Triple Test Execution (Waste)
-
-Current per-story flow runs tests up to 3 times:
-
-```
-Pipeline verify stage     → scoped tests (Smart Test Runner)
-Pipeline review stage     → test command (if review.commands.test configured)
-Post-verify               → scoped tests AGAIN + full regression gate
-```
-
-On Mac01 with ~2000 tests, this means:
-- Scoped: ~10-20s × 2 (duplicate) = 20-40s wasted
-- Full regression: ~125s per story
-- Total: ~150s+ of test execution per story
-
-### 1.2 Regression Gate Per Story (BUG-026)
-
-The regression gate runs a **full test suite after every story**. Problems:
-- **Timeout:** Full suite frequently times out on Mac01 (~125s)
-- **False escalation:** Timeout is treated as story failure → bumps `story.attempts` → triggers tier escalation
-- **Wasted compute:** Agent's implementation was correct (scoped tests passed), but full suite timeout causes a complete redo at a higher (more expensive) tier
-- **Cascading waste:** N stories × 1 full suite each = N full suite runs. Most are redundant.
-
-### 1.3 Escalation Context Loss
-
-When a story fails and escalates to a higher tier, the error context passed is:
-
-```
-priorErrors: ["Attempt 1 failed with model tier: fast"]
-```
-
-The actual test output — which tests failed, error messages, stack traces — is **discarded**. The escalated agent gets a vague hint instead of actionable failure context.
-
-| Stage | Context Available | What's Stored in priorErrors |
-|-------|-------------------|------------------------------|
-| Rectification loop | Full `TestFailure[]` with file, testName, error, stackTrace | *(used internally, then discarded)* |
-| Post-verify failure | `verificationResult.error` (summary string) | Generic: `"Verification failed: TEST_FAILURE"` |
-| Regression gate failure | Full test output | Generic: `"REGRESSION: full-suite regression detected"` |
-| Tier escalation | Nothing new | `"Attempt N failed with model tier: X"` |
-
-Result: `fast → balanced → powerful` escalation chain has **zero actionable context** about what actually failed.
-
-### 1.4 Routing Cache Ignores Escalation Tier (BUG-028)
-
-LLM routing cache is keyed by `story.id` only. When escalation updates `story.routing.modelTier` from `balanced` → `powerful`, the next iteration hits the cache and returns the old `balanced` routing decision, overriding the escalation.
-
----
-
-## 2. Proposed Architecture
-
-### 2.1 Verification Flow (Simplified)
-
-```
-Pipeline per-story:
-  1. Agent execution
-  2. Scoped verify (Smart Test Runner)        ← ONLY test run per story
-  3. Scoped rectification (if verify fails)   ← has full test failure context
-  4. Review (typecheck + lint only)            ← NO test re-run
-  5. Story marked "passed" or escalated
-
-Run-end (after all stories pass):
-  6. Deferred regression gate (full suite)     ← ONE full suite run total
-  7. Targeted regression rectification         ← per-story, with failure context
-  8. Run marked complete or stalled
-```
-
-**Key changes:**
-- **Remove duplicate test runs** — pipeline verify is the single source of truth
-- **Review stage runs typecheck + lint only** — no test command
-- **Remove post-verify scoped re-test** — pipeline verify already did this
-- **Move regression gate to run-end** — one full suite run instead of N
-- **Targeted regression rectification** — map failing tests back to responsible stories
-
-### 2.2 Deferred Regression Gate
-
-Instead of running the full suite after every story, run it **once** after all stories complete.
-
-```typescript
-// New: src/execution/lifecycle/run-regression.ts
-
-interface DeferredRegressionOptions {
-  config: NaxConfig;
-  workdir: string;
-  prd: PRD;
-  prdPath: string;
-  allStoryMetrics: StoryMetrics[];
-}
-
-interface DeferredRegressionResult {
-  passed: boolean;
-  failedTests?: TestFailure[];
-  storyMapping?: Map<string, TestFailure[]>; // storyId → failures caused by that story
-}
-```
-
-**Failure handling:**
-1. Run full suite
-2. Parse failures into `TestFailure[]`
-3. For each failing test, use reverse Smart Test Runner mapping:
-   - `test/unit/foo/bar.test.ts` → `src/foo/bar.ts` → which story touched this file? (from git log per story)
-4. Group failures by responsible story
-5. Attempt targeted rectification per story (agent gets FULL failure context)
-6. Re-run full suite to confirm fix
-7. If still failing → mark responsible stories as failed
-
-**Config:**
-
-```jsonc
-{
-  "execution": {
-    "regressionGate": {
-      "enabled": true,
-      "mode": "deferred",        // "deferred" | "per-story" | "disabled"
-      "timeoutSeconds": 300,
-      "maxRectificationAttempts": 2
-    }
-  }
-}
-```
-
-### 2.3 Structured Failure Context for Escalation
-
-Replace vague `priorErrors` strings with structured failure data.
-
-**New PRD field:** `priorFailures` (alongside existing `priorErrors` for backward compat)
-
-```typescript
-// In src/prd/types.ts
-
-interface StructuredFailure {
-  /** Which attempt this failure occurred on */
-  attempt: number;
-  /** Model tier that was used */
-  modelTier: string;
-  /** What stage failed */
-  stage: "verify" | "review" | "regression" | "rectification" | "agent-session";
-  /** Human-readable summary */
-  summary: string;
-  /** Structured test failures (if applicable) */
-  testFailures?: TestFailureContext[];
-  /** Timestamp */
-  timestamp: string;
-}
-
-interface TestFailureContext {
-  file: string;
-  testName: string;
-  error: string;
-  /** First 5 lines of stack trace */
-  stackTrace: string[];
-}
-```
-
-**How it flows through escalation:**
-
-```
-fast attempt 1 → verify fails
-  → priorFailures: [{
-      attempt: 1,
-      modelTier: "fast",
-      stage: "verify",
-      summary: "3 tests failed in src/routing/router.ts",
-      testFailures: [
-        { file: "test/unit/routing/router.test.ts",
-          testName: "should route to balanced",
-          error: "Expected 'balanced' got 'fast'",
-          stackTrace: [...] },
-        ...
-      ]
-    }]
-
-balanced attempt 1 → agent gets FULL context of what fast couldn't fix
-```
-
-**Context injection** (`context/builder.ts`):
-
-Format `priorFailures` into actionable markdown for the agent prompt:
-
-```markdown
-## Prior Attempt 1 (fast, verify)
-3 tests failed in src/routing/router.ts
-
-### Test Failures:
-- **test/unit/routing/router.test.ts** > should route to balanced
-  Error: Expected 'balanced' got 'fast'
-  Stack: at Router.route (src/routing/router.ts:42)
-```
-
-### 2.4 BUG-028 Fix: Cache Invalidation on Escalation
-
-Add `clearCacheForStory(storyId)` to `src/routing/strategies/llm.ts`.
-
-Call it in `tier-escalation.ts` when updating `story.routing.modelTier`.
-
----
-
-## 3. Migration Plan
-
-### Phase 1: v0.18.3 — Minimal Fixes (no architecture change)
-
-1. **BUG-026 quick fix:** Regression gate timeout → accept scoped pass + warn (not escalate)
-2. **BUG-028 fix:** `clearCacheForStory()` on escalation
-3. **Store structured failures:** Start populating `priorFailures` alongside `priorErrors` (backward compat)
-
-### Phase 2: v0.19.0 — Architecture v2
-
-1. **Remove post-verify duplicate test run** — pipeline verify is authoritative
-2. **Review stage: typecheck + lint only** — remove test command from review
-3. **Deferred regression gate** — run-end full suite with targeted rectification
-4. **Reverse Smart Test Runner mapping** — failing test → source file → responsible story
-5. **Full structured failure context** — `priorFailures` injected into agent prompts
-6. **Config:** `regressionGate.mode: "deferred"` (default)
-
-### Phase 3: Future
-
-- **Incremental regression:** Only run tests related to ALL changed files across all stories (union of Smart Test Runner scopes)
-- **Test impact analysis:** AST-based dependency graph for more precise test scoping
-- **Parallel story regression:** Run rectification for multiple stories concurrently
-
----
-
-## 4. Files Affected
-
-### Phase 1 (v0.18.3)
-
-| File | Change |
-|------|--------|
-| `src/execution/post-verify.ts` | Regression gate timeout → accept + warn |
-| `src/routing/strategies/llm.ts` | Add `clearCacheForStory()` export |
-| `src/execution/escalation/tier-escalation.ts` | Call `clearCacheForStory()` on escalation |
-| `src/execution/post-verify-rectification.ts` | Store `StructuredFailure` in `priorFailures` |
-| `src/prd/types.ts` | Add `priorFailures?: StructuredFailure[]` to `UserStory` |
-
-### Phase 2 (v0.19.0)
-
-| File | Change |
-|------|--------|
-| `src/pipeline/stages/review.ts` | Remove test command execution |
-| `src/execution/post-verify.ts` | Remove scoped re-test, keep regression call only |
-| `src/execution/lifecycle/run-regression.ts` | **New:** Deferred regression gate + targeted rectification |
-| `src/execution/lifecycle/run-completion.ts` | Call deferred regression before final metrics |
-| `src/verification/smart-runner.ts` | Add reverse mapping: test file → source file → story |
-| `src/context/builder.ts` | Format `priorFailures` into agent prompt |
-| `src/config/schemas.ts` | Add `regressionGate.mode` enum |
-
----
-
-## 5. Test Plan
-
-### Phase 1 Tests
-- Regression gate timeout returns "passed" with warning (not "failed")
-- `clearCacheForStory()` removes cached decision; next route() re-evaluates
-- `priorFailures` populated with structured `TestFailureContext` on verify failure
-- Backward compat: `priorErrors` still populated alongside `priorFailures`
-
-### Phase 2 Tests
-- Pipeline verify is single test execution (no duplicate)
-- Review stage skips test command
-- Deferred regression runs once at run-end
-- Reverse mapping correctly identifies responsible story
-- Targeted rectification receives full failure context
-- Escalated agent prompt includes formatted `priorFailures`
-- Config `regressionGate.mode: "per-story"` preserves current behavior
-
----
-
-## 6. Historical Context (Why It's Like This)
-
-### Why post-verify exists separately from pipeline verify
-
-The pipeline (`src/pipeline/pipeline.ts`) runs stages in sequence: routing → context → prompt → execution → **verify** → review → completion. This was the original single verification point.
-
-Later, **post-agent verification** was added in `src/execution/pipeline-result-handler.ts` → `handlePipelineSuccess()` → `runPostAgentVerification()`. This was meant to handle:
-- **Scoped verification** with git-diff-based test file detection (before Smart Test Runner existed in the pipeline)
-- **Rectification** — retry loop with agent when tests fail
-- **Regression gate** (BUG-009 fix) — full suite after scoped pass
-
-When Smart Test Runner was added to the **pipeline verify stage** (v0.18.2), it duplicated the scoped test logic that post-verify already had. Nobody removed the post-verify scoped test.
-
-### Current code flow with exact locations
-
-```
-sequential-executor.ts:170  → pipelineRunner.run(story)
-  pipeline.ts:execute()     → runs stages in order:
-    verify.ts:execute()     → Smart Test Runner scoped tests    [TEST RUN #1]
-    review.ts:execute()     → runReview() which may run tests   [TEST RUN #2 if review.commands.test set]
-
-pipeline-result-handler.ts:76  → runPostAgentVerification()
-  post-verify.ts:85            → runVerification(scopedCommand) [TEST RUN #3 — duplicate of #1]
-  post-verify.ts:118           → runRegressionGate()
-    post-verify.ts:180         → runVerification(fullSuite)     [TEST RUN #4 — full suite]
-```
-
-### Review stage test command
-
-`review.ts` calls `runReview()` from `src/review/index.ts` which runs `config.review.commands.test` if configured. In default config, `review.commands` includes `test`, `typecheck`, and `lint`. So yes — review runs tests by default, creating the triple-test problem.
-
-### Decision rationale
-
-**Why deferred regression (Option C) over per-story (A) or disabled (B):**
-- **Option A (keep per-story):** 125s timeout per story is the root cause of BUG-026. Even with timeout-acceptance, it's wasteful.
-- **Option B (disable entirely):** Too risky — cross-story regressions are real (BUG-009 was filed for this exact reason).
-- **Option C (deferred):** One full suite run at the end. If it fails, we can trace back to responsible stories via reverse file mapping. Best balance of safety vs speed.
-
-**Why cache invalidation (Option C for BUG-028) over cache key change (A) or bypass (B):**
-- **Option A (include tier in key):** Works but creates multiple cache entries per story. If story is re-routed 3 times, 3 entries exist. Cache eviction becomes unpredictable.
-- **Option B (bypass when routing set):** Almost all stories have `story.routing` set after first pass, so cache would rarely be used at all — defeats the purpose.
-- **Option C (clear on escalation):** Surgical — one `delete()` call at the exact moment routing changes. Cache works normally for non-escalated stories.
-
-## 7. Edge Cases
-
-### Partial completion (stalled run)
-
-If only 3 of 5 stories pass and nax stalls (remaining stories failed/paused):
-- Deferred regression still runs on the 3 passed stories
-- If regression fails, only the passed stories are candidates for rectification
-- Failed/paused stories are untouched
-
-### Stories that touch the same files
-
-If story A and story B both modify `src/utils/parser.ts`:
-- Reverse mapping may attribute the same failing test to both stories
-- Rectification should try the **last story that touched the file** first (git log order)
-- If that doesn't fix it, try the other story
-
-### No test mapping possible
-
-If a failing test can't be mapped to any story's changed files:
-- Log warning: "Unmapped regression — cannot attribute to a specific story"
-- Mark ALL passed stories as needing re-verification
-- This is the worst case but should be rare with good test naming conventions

package/docs/tdd/strategies.md

@@ -1,97 +0,0 @@
-# TDD Strategies
-
-nax supports three test strategies, selectable via `config.tdd.strategy` or per-story override.
-
-## Strategy Comparison
-
-| Aspect | `three-session-tdd` | `three-session-tdd-lite` | `test-after` |
-|---|---|---|---|
-| **Sessions** | 3 separate sessions | 3 separate sessions | 1 session |
-| **Session 1 (Test Writer)** | Strict isolation — tests only, NO src/ reads, NO stubs | Relaxed — can read src/, create stubs in src/ | ❌ No dedicated test writer |
-| **Session 2 (Implementer)** | Implements against pre-written tests | Same | Implements + writes tests |
-| **Session 3 (Verifier)** | Verifies isolation wasn't violated | Same | ❌ No verifier |
-| **Isolation check** | ✅ Full isolation enforcement | ✅ Full isolation enforcement | ❌ None |
-| **Isolation-violation fallback** | Triggers lite-mode retry | N/A (already lite) | N/A |
-| **Rectification gate** | Checks implementer isolation | ⚡ Skips `verifyImplementerIsolation` | Standard |
-
----
-
-## When Each Strategy Is Used
-
-Controlled by `config.tdd.strategy`:
-
-| Config value | Behaviour |
-|---|---|
-| `"strict"` | Always `three-session-tdd` |
-| `"lite"` | Always `three-session-tdd-lite` |
-| `"off"` | Always `test-after` |
-| `"auto"` | LLM/keyword router decides (see routing rules below) |
-
-### Auto-Routing Rules (FEAT-013)
-
-`test-after` is **deprecated** from auto mode. Default fallback is now `three-session-tdd-lite`.
-
-| Condition | Strategy |
-|---|---|
-| Security / auth logic | `three-session-tdd` |
-| Public API / complex / expert | `three-session-tdd` |
-| UI / layout / CLI / integration / polyglot tags | `three-session-tdd-lite` |
-| Simple / medium (default) | `three-session-tdd-lite` |
-
----
-
-## Session Detail
-
-### `three-session-tdd` — Full Mode
-
-1. **Test Writer** — writes failing tests only. Cannot read src/ files or create any source stubs. Strict isolation enforced by post-session diff check.
-2. **Implementer** — makes all failing tests pass. Works against the test-writer's output.
-3. **Verifier** — confirms isolation: tests were written before implementation, no cheating.
-
-If the test writer violates isolation (touches src/), the orchestrator flags it as `isolation-violation` and schedules a lite-mode retry on the next attempt.
-
-### `three-session-tdd-lite` — Lite Mode
-
-Same 3-session flow, but the test writer prompt is relaxed:
-- **Can read** existing src/ files (needed when importing existing types/interfaces).
-- **Can create minimal stubs** in src/ (empty exports, no logic) to make imports resolve.
-- Implementer isolation check (`verifyImplementerIsolation`) is **skipped** in the rectification gate.
-
-Best for: existing codebases where greenfield isolation is impractical, or stories that modify existing modules.
-
-### `test-after` — Single Session
-
-One Claude Code session writes tests and implements the feature together. No structured TDD flow.
-
-- Higher failure rate observed in practice — Claude tends to write tests that are trivially passing or implementation-first.
-- Use only when `tdd.strategy: "off"` or explicitly set per-story.
-
----
-
-## Per-Story Override
-
-Add `testStrategy` to a story in `prd.json` to override routing:
-
-```json
-{
-  "userStories": [
-    {
-      "id": "US-001",
-      "testStrategy": "three-session-tdd-lite",
-      ...
-    }
-  ]
-}
-```
-
-Supported values: `"test-after"`, `"three-session-tdd"`, `"three-session-tdd-lite"`.
-
----
-
-## Known Issues
-
-- **BUG-045:** LLM batch routing bypasses `config.tdd.strategy`. `buildBatchPrompt()` only offers `test-after` and `three-session-tdd` to the LLM — no `three-session-tdd-lite`. The cache hit path returns the LLM decision directly without calling `determineTestStrategy()`, so `tdd.strategy: "lite"` is silently ignored for batch-routed stories. Fix: post-process batch decisions through `determineTestStrategy()`. See `src/routing/strategies/llm.ts:routeBatch()`.
-
----
-
-*Last updated: 2026-03-07*