@nathapp/nax 0.20.0 → 0.22.0

package/docs/adr/ADR-005-implementation-plan.md

@@ -0,0 +1,655 @@
+# ADR-005: Implementation Plan
+
+**Parent:** ADR-005-pipeline-re-architecture.md  
+**Date:** 2026-03-06  
+**Target Version:** v0.22.0  
+
+---
+
+## Overview
+
+4 phases, each independently shippable. Each phase must pass the full test suite (2083+ tests) before proceeding.
+
+| Phase | Name | Scope | Est. Stories |
+|-------|------|-------|-------------|
+| 0 | Test Suite Cleanup | Reorganize, split, align test files | 4 |
+| 1 | Event Bus + Verification Orchestrator | Foundation — no behavior change | 6 |
+| 2 | New Pipeline Stages | Add rectify, autofix, regression stages + retry action | 5 |
+| 3 | Subscriber Consolidation | Wire hooks/reporters/interaction to event bus | 4 |
+| 4 | Executor Simplification | Remove ad-hoc code, delete deprecated files | 4 |
+
+**Total:** 23 stories
+
+---
+
+## Phase 0: Test Preparation (Prerequisite)
+
+**Goal:** Prepare the test suite for the re-architecture. Don't clean up tests that will be deleted — tag them and let them die with their source code. Focus on structure and clarity.
+
+**Approach by layer:**
+
+| Layer | Action | Why |
+|-------|--------|-----|
+| Tests for code being deleted (~11 files) | Tag `// RE-ARCH: delete-with-source` | Don't waste effort cleaning code that dies in Phase 4 |
+| Tests for stable code (~90 files) | Keep, move to correct paths | Config, routing, CLI, context, PRD, etc. — unaffected by re-arch |
+| Integration tests for re-arch behavior (~15 files) | Tag `// RE-ARCH: rewrite` — keep assertions, rewrite setup when source changes | The *behavior* is valid, the *internals* will change |
+| Monster files (42 files >400 lines) | Split by describe block | Smaller files are easier to keep/delete/rewrite per-block |
+| New architecture code | Write fresh tests per phase | Orchestrator, event bus, subscribers, new stages |
+
+### US-P0-001: Organize Folder Structure
+
+Move stray tests into `unit/` or `integration/` subdirectories. No logic changes.
+
+**Stray tests to move:**
+
+| Current path | New path |
+|-------------|----------|
+| `test/context/prior-failures.test.ts` | `test/unit/context/prior-failures.test.ts` |
+| `test/execution/pid-registry.test.ts` | `test/unit/execution/pid-registry.test.ts` |
+| `test/execution/structured-failure.test.ts` | `test/unit/execution/structured-failure.test.ts` |
+| `test/acceptance/cm-003-default-view.test.ts` | `test/e2e/cm-003-default-view.test.ts` |
+| `test/ui/*.test.ts` (4 files) | `test/unit/ui/*.test.ts` |
+| `test/integration/e2e.test.ts` | `test/e2e/plan-analyze-run.test.ts` |
+
+**Integration subdirectories:** Group 61 flat files into `cli/`, `config/`, `context/`, `execution/`, `pipeline/`, `review/`, `tdd/`, `verification/`, `interaction/`, `routing/`.
+
+**Resolve 5 duplicate filenames** with module prefix.
+
+**Gate:** All 2083+ tests pass after moves.
+
+### US-P0-002: Split Monster Test Files
+
+Split 42 files >400 lines by `describe` block. Target <400 lines each.
+
+**Priority targets (>800 lines, 6 files):**
+
+| File | Lines | Split into |
+|------|-------|-----------|
+| `tdd-orchestrator.test.ts` | 1762 | core, lite-mode, verdict, prompts |
+| `context.test.ts` | 1725 | builder, elements, tokens |
+| `runner.test.ts` | 1679 | batching, escalation, queue |
+| `routing.test.ts` | 1039 | classify, strategy-chain, keywords |
+| `plugin-routing.test.ts` | 921 | chain, integration |
+| `e2e.test.ts` | 896 | split by workflow |
+
+**Secondary (400-800 lines, 36 files):** Split by describe block.
+
+**Rule:** One top-level `describe` per file. Shared fixtures in `test/helpers/`.
+
+**Gate:** Same test count, all pass.
+
+### US-P0-003: Tag Tests for Re-Architecture Impact
+
+Add comment header to every test file indicating its re-arch fate:
+
+```ts
+// RE-ARCH: keep              — stable code, unaffected
+// RE-ARCH: rewrite           — behavior valid, internals will change
+// RE-ARCH: delete-with-source — source file being deleted in Phase 4
+```
+
+**Files tagged `delete-with-source`:**
+
+| Test file | Source file being deleted |
+|-----------|-------------------------|
+| `test/unit/execution/post-verify.test.ts` | `src/execution/post-verify.ts` |
+| `test/unit/execution/post-verify-regression.test.ts` | `src/execution/post-verify.ts` |
+| `test/unit/execution/lifecycle/run-regression.test.ts` | (rewriting to thin wrapper) |
+| `test/integration/rectification-flow.test.ts` | `src/execution/post-verify-rectification.ts` |
+
+**Files tagged `rewrite`:**
+
+| Test file | Reason |
+|-----------|--------|
+| `test/integration/pipeline.test.ts` | New stage order, new stages |
+| `test/integration/verify-stage.test.ts` | Verify delegates to orchestrator |
+| `test/integration/hooks.test.ts` | Hooks move to event bus subscriber |
+| `test/integration/interaction-chain-pipeline.test.ts` | Triggers move to subscriber |
+| `test/integration/reporter-lifecycle.test.ts` | Reporters move to subscriber |
+
+**Gate:** Every test file has a RE-ARCH tag.
+
+### US-P0-004: Coverage Gap Analysis
+
+Document which new files need tests (checklist for Phases 1-4):
+
+| New file (Phase) | Test file needed |
+|-----------------|-----------------|
+| `src/verification/orchestrator.ts` (P1) | `test/unit/verification/orchestrator.test.ts` |
+| `src/verification/strategies/scoped.ts` (P1) | `test/unit/verification/strategies/scoped.test.ts` |
+| `src/verification/strategies/regression.ts` (P1) | `test/unit/verification/strategies/regression.test.ts` |
+| `src/verification/strategies/acceptance.ts` (P1) | `test/unit/verification/strategies/acceptance.test.ts` |
+| `src/pipeline/event-bus.ts` (P1) | `test/unit/pipeline/event-bus.test.ts` |
+| `src/pipeline/stages/rectify.ts` (P2) | `test/unit/pipeline/stages/rectify.test.ts` |
+| `src/pipeline/stages/autofix.ts` (P2) | `test/unit/pipeline/stages/autofix.test.ts` |
+| `src/pipeline/stages/regression.ts` (P2) | `test/unit/pipeline/stages/regression.test.ts` |
+| `src/review/orchestrator.ts` (P2) | `test/unit/review/orchestrator.test.ts` |
+| `src/pipeline/subscribers/hooks.ts` (P3) | `test/unit/pipeline/subscribers/hooks.test.ts` |
+| `src/pipeline/subscribers/reporters.ts` (P3) | `test/unit/pipeline/subscribers/reporters.test.ts` |
+| `src/pipeline/subscribers/interaction.ts` (P3) | `test/unit/pipeline/subscribers/interaction.test.ts` |
+
+Document which integration behaviors must be preserved (extracted from `rewrite`-tagged tests):
+- Verify fail → rectify → retry → pass
+- Review fail → autofix → retry → pass
+- Escalation exhausted → human-review trigger fires
+- Story complete → hook fires + reporter receives event
+- Full pipeline flow: routing → execution → verify → review → completion
+
+**Gate:** Coverage gap doc written, referenced by Phase 1-4 stories.
+
+### Phase 0 Gate
+- [ ] All 2083+ tests pass
+- [ ] Zero test files outside `test/unit/`, `test/integration/`, `test/e2e/`, `test/helpers/`
+- [ ] Zero duplicate filenames
+- [ ] Zero test files > 400 lines
+- [ ] Integration tests in subdirectories
+- [ ] Every test file has `RE-ARCH` tag
+- [ ] Coverage gap doc complete
+
+---
+
+## Phase 1: Foundation (Event Bus + Verification Orchestrator)
+
+**Goal:** Build the new infrastructure without changing any existing behavior. All existing code paths continue to work. New code is tested independently.
+
+### US-P1-001: Verification Orchestrator Types
+
+**Create:** `src/verification/types.ts` (update existing)
+
+- Define unified `VerifyResult` with `success`, `status`, `passCount`, `failCount`, `totalCount`, `failures[]`, `rawOutput`, `durationMs`
+- Define `VerifyContext` (config, workdir, storyId, testCommand, timeout, smartRunnerConfig, etc.)
+- Define `StructuredTestFailure` (file, testName, error, stackTrace)
+- Define strategy enum: `scoped | regression | deferred-regression | acceptance`
+
+**Tests:** Unit tests for type guards and result builders  
+**Files:** `src/verification/types.ts`, `test/unit/verification/types.test.ts`  
+**Risk:** Low — additive only
+
+### US-P1-002: Verification Orchestrator — Scoped Strategy
+
+**Create:** `src/verification/strategies/scoped.ts`
+
+- Extract smart-runner logic from `src/pipeline/stages/verify.ts` (lines 40-164)
+- Accept `VerifyContext`, return `VerifyResult`
+- Use existing `smart-runner.ts` for test file discovery
+- Use existing `executor.ts` for test execution
+- Use existing `parser.ts` for output parsing
+- **Must produce identical results** to current verify stage
+
+**Tests:** Port `test/unit/pipeline/stages/verify.test.ts` and `test/unit/pipeline/verify-smart-runner.test.ts` assertions  
+**Files:** `src/verification/strategies/scoped.ts`, `test/unit/verification/strategies/scoped.test.ts`  
+**Deps:** US-P1-001
+
+### US-P1-003: Verification Orchestrator — Regression Strategy
+
+**Create:** `src/verification/strategies/regression.ts`
+
+- Extract full-suite logic from `src/execution/post-verify.ts` (lines 130-190)
+- Extract full-suite logic from `src/execution/lifecycle/run-regression.ts` (lines 125-185)
+- Single function: accept `VerifyContext`, return `VerifyResult`
+- Support both inline (per-story) and deferred (end-of-run) modes via context flag
+
+**Tests:** Port `test/unit/execution/post-verify-regression.test.ts` and `test/unit/execution/lifecycle/run-regression.test.ts` assertions  
+**Files:** `src/verification/strategies/regression.ts`, `test/unit/verification/strategies/regression.test.ts`  
+**Deps:** US-P1-001
+
+### US-P1-004: Verification Orchestrator — Acceptance Strategy
+
+**Create:** `src/verification/strategies/acceptance.ts`
+
+- Extract AC test logic from `src/pipeline/stages/acceptance.ts` (lines 50-100)
+- Extract AC test logic from `src/execution/lifecycle/acceptance-loop.ts` (lines 80-120)
+- Accept `VerifyContext` (with specPath for AC patterns), return `VerifyResult`
+
+**Tests:** Port `test/unit/acceptance.test.ts` and `test/integration/pipeline-acceptance.test.ts` assertions  
+**Files:** `src/verification/strategies/acceptance.ts`, `test/unit/verification/strategies/acceptance.test.ts`  
+**Deps:** US-P1-001
+
+### US-P1-005: Verification Orchestrator — Entry Point + Rectification
+
+**Create:** `src/verification/orchestrator.ts`
+
+- Orchestrator class with `verifyScoped()`, `verifyRegression()`, `verifyDeferredRegression()`, `verifyAcceptance()`
+- Each method delegates to the corresponding strategy
+- Integrate shared rectification loop from `src/verification/rectification.ts`
+- Consistent structured logging: `[verify:<strategy>]` prefix with `{storyId, passCount, failCount, totalCount}`
+- Output preview always uses tail (last 20 lines), never head
+
+**Tests:** Integration tests verifying orchestrator delegates correctly and returns unified `VerifyResult`  
+**Files:** `src/verification/orchestrator.ts`, `test/integration/verification-orchestrator.test.ts`  
+**Deps:** US-P1-002, US-P1-003, US-P1-004
+
+### US-P1-006: Pipeline Event Bus
+
+**Update:** `src/pipeline/events.ts` → `src/pipeline/event-bus.ts`
+
+- Extend existing `PipelineEventEmitter` (already has `stage:enter`, `stage:exit`, `story:start`, `story:complete`, `story:escalate`, `run:complete`)
+- Add new events:
+  - `story:fail(story, reason)`
+  - `story:skip(story, reason)`
+  - `verify:start(strategy, storyId)`
+  - `verify:result(result: VerifyResult)`
+  - `rectify:attempt(attempt, maxAttempts, remainingFailures)`
+  - `review:start(checks[])`
+  - `review:result(result: ReviewResult)`
+  - `autofix:attempt(fixType, command)`
+  - `run:start(feature, totalStories)`
+  - `run:pause(reason)`
+  - `run:error(error)`
+  - `escalation:tier-change(from, to, storyId)`
+  - `escalation:exhausted(storyId, attempts)`
+  - `interaction:request(trigger, request)`
+  - `interaction:response(trigger, response)`
+- Keep backward compat: existing event signatures unchanged
+- Keep old `events.ts` as re-export shim during migration
+
+**Tests:** Unit tests for event emission and type safety  
+**Files:** `src/pipeline/event-bus.ts`, `test/unit/pipeline/event-bus.test.ts`  
+**Deps:** None (can parallel with US-P1-001–005)
+
+### Phase 1 Gate
+- [ ] All 2083+ existing tests pass
+- [ ] New orchestrator tests pass
+- [ ] Event bus tests pass
+- [ ] No existing code modified (only new files added)
+
+---
+
+## Phase 2: New Pipeline Stages
+
+**Goal:** Add new stages and retry action. Existing stages gradually delegate to orchestrator. Pipeline becomes the single execution path.
+
+### US-P2-001: Pipeline Runner — `retry` Action
+
+**Update:** `src/pipeline/runner.ts`
+
+- Add `retry` to `StageAction` type in `src/pipeline/types.ts`
+- Handle `retry` in pipeline runner: find target stage index, reset loop counter
+- Add `MAX_STAGE_RETRIES` guard (default: 5, configurable)
+- Track retry count per stage to prevent infinite loops
+
+**Tests:** Unit tests: retry from verify, retry from review, max retry exceeded  
+**Files:** `src/pipeline/runner.ts`, `src/pipeline/types.ts`, `test/unit/pipeline/runner-retry.test.ts`  
+**Deps:** Phase 1 complete
+
+### US-P2-002: `rectify` Stage
+
+**Create:** `src/pipeline/stages/rectify.ts`
+
+- Enabled only when `ctx.verifyResult?.success === false`
+- Calls `VerificationOrchestrator.rectify()` — shared rectification loop
+- On fix: return `{ action: "retry", fromStage: "verify" }`
+- On exhausted: return `{ action: "escalate" }`
+- Emits `rectify:attempt` events via event bus
+
+**Tests:** Unit tests: rectify succeeds → retry, rectify exhausted → escalate, rectify skipped when verify passed  
+**Files:** `src/pipeline/stages/rectify.ts`, `test/unit/pipeline/stages/rectify.test.ts`  
+**Deps:** US-P2-001, Phase 1
+
+### US-P2-003: `autofix` Stage
+
+**Create:** `src/pipeline/stages/autofix.ts`
+
+- Enabled only when `ctx.reviewResult?.passed === false`
+- Step 1: If lint failed + `quality.commands.lintFix` configured → run command (no agent)
+- Step 2: If format failed + `quality.commands.formatFix` configured → run command (no agent)
+- Step 3: If typecheck failed → spawn short agent session with error output (fast tier, 60s timeout)
+- On fix: return `{ action: "retry", fromStage: "review" }`
+- On exhausted: return `{ action: "escalate" }`
+- Emits `autofix:attempt` events
+
+**Config additions:**
+```ts
+quality.commands.lintFix?: string    // e.g., "biome check --fix"
+quality.commands.formatFix?: string  // e.g., "biome format --write"
+quality.autofix.enabled?: boolean    // default: true
+quality.autofix.maxAttempts?: number // default: 2
+```
+
+**Tests:** Unit tests: lint auto-fixed, typecheck auto-fixed, autofix disabled, max attempts  
+**Files:** `src/pipeline/stages/autofix.ts`, `test/unit/pipeline/stages/autofix.test.ts`  
+**Config:** Update `src/config/schema.ts` with new fields  
+**Deps:** US-P2-001, Phase 1
+
+### US-P2-004: `regression` Stage
+
+**Create:** `src/pipeline/stages/regression.ts`
+
+- Enabled only when `regressionGate.mode === "inline"` AND verify passed
+- Calls `VerificationOrchestrator.verifyRegression()`
+- On pass: return `{ action: "continue" }`
+- On fail: attempt rectification internally (reuse rectify logic)
+  - If rectification fixes it: return `{ action: "continue" }`
+  - If exhausted: return `{ action: "escalate" }`
+- Emits `verify:start("regression")` and `verify:result` events
+
+**Tests:** Port from `test/unit/execution/post-verify-regression.test.ts`  
+**Files:** `src/pipeline/stages/regression.ts`, `test/unit/pipeline/stages/regression.test.ts`  
+**Deps:** Phase 1
+
+### US-P2-005: Wire New Stages into Pipeline + Update `verify`/`review` Stages
+
+**Update:** `src/pipeline/stages/index.ts`
+
+- New default pipeline order:
+  ```ts
+  [queueCheck, routing, constitution, context, prompt, optimizer,
+   execution, verify, rectify, review, autofix, regression, completion]
+  ```
+- Remove `acceptance` from per-story pipeline
+- Create `postRunPipeline`:
+  ```ts
+  [deferredRegression, acceptance]
+  ```
+
+**Update:** `src/pipeline/stages/verify.ts`
+- Delegate to `VerificationOrchestrator.verifyScoped()`
+- Store `VerifyResult` in `ctx.verifyResult` (new context field)
+- Emit `verify:start` and `verify:result` events
+- On failure: return `{ action: "continue" }` (let rectify stage handle it)
+
+**Update:** `src/pipeline/stages/review.ts`
+- Delegate to `ReviewOrchestrator` (or keep existing logic)
+- Store `ReviewResult` in `ctx.reviewResult`
+- Emit `review:start` and `review:result` events
+- On failure: return `{ action: "continue" }` (let autofix stage handle it)
+
+**Update:** `src/pipeline/types.ts`
+- Add `verifyResult?: VerifyResult` to `PipelineContext`
+
+**Tests:** Full integration test of new pipeline flow: execution → verify → rectify → review → autofix → regression → completion  
+**Files:** Multiple stage files, `test/integration/pipeline-new-flow.test.ts`  
+**Deps:** US-P2-001–004
+
+### Phase 2 Gate
+- [ ] All existing tests pass (some may need assertion updates for new stage order)
+- [ ] New stage tests pass
+- [ ] Pipeline retry action works correctly
+- [ ] End-to-end: verify fail → rectify → retry → verify pass → continue
+- [ ] End-to-end: review fail → autofix → retry → review pass → continue
+
+---
+
+## Phase 3: Subscriber Consolidation
+
+**Goal:** Replace all scattered `fireHook()`, `getReporters()`, and `executeTrigger()` calls with event bus subscribers.
+
+### US-P3-001: Hooks Subscriber
+
+**Create:** `src/pipeline/subscribers/hooks.ts`
+
+- `wireHooks(bus, hooks, workdir)` function
+- Maps pipeline events to hook events:
+
+| Pipeline Event | Hook Event | Current call sites to remove |
+|---------------|------------|----------------------------|
+| `run:start` | `on-start` | `run-setup.ts:182` |
+| `story:start` | `on-story-start` | `sequential-executor.ts:120,204` |
+| `story:complete` | `on-story-complete` | `completion.ts:73`, `pipeline-result-handler.ts:160` |
+| `story:fail` | `on-story-fail` | `tier-outcome.ts:46,73,117,145` |
+| `run:pause` | `on-pause` | `sequential-executor.ts:229,365`, `tier-escalation.ts:150` |
+| `run:complete` | `on-complete` | `parallel-executor.ts:161` |
+| `run:error` | `on-error` | various catch blocks |
+
+- All `fireHook()` calls fire-and-forget (errors logged, never block pipeline)
+
+**Tests:** Unit tests: each event fires correct hook, error in hook doesn't block pipeline  
+**Files:** `src/pipeline/subscribers/hooks.ts`, `test/unit/pipeline/subscribers/hooks.test.ts`  
+**Deps:** Phase 2
+
+### US-P3-002: Reporter Subscriber
+
+**Create:** `src/pipeline/subscribers/reporters.ts`
+
+- `wireReporters(bus, pluginRegistry)` function
+- Maps pipeline events to reporter methods:
+
+| Pipeline Event | Reporter Method | Current call sites to remove |
+|---------------|----------------|----------------------------|
+| `run:start` | `onRunStart()` | `run-initialization.ts` (implicit) |
+| `story:complete` | `onStoryComplete()` | `pipeline-result-handler.ts:94,145`, `lifecycle/story-hooks.ts:38` |
+| `run:complete` | `onRunEnd()` | `run-cleanup.ts:40`, `pipeline-result-handler.ts:369` |
+
+- Fire-and-forget with error logging
+
+**Tests:** Unit tests: reporter methods called with correct event data  
+**Files:** `src/pipeline/subscribers/reporters.ts`, `test/unit/pipeline/subscribers/reporters.test.ts`  
+**Deps:** Phase 2
+
+### US-P3-003: Interaction Subscriber
+
+**Create:** `src/pipeline/subscribers/interaction.ts`
+
+- `wireInteraction(bus, interactionChain, config)` function
+- Maps pipeline events to triggers:
+
+| Pipeline Event | Trigger | Current call site to remove |
+|---------------|---------|---------------------------|
+| `escalation:exhausted` | `human-review` | `pipeline-result-handler.ts:222` |
+| `escalation:exhausted` | `max-retries` | `pipeline-result-handler.ts` |
+| `review:result` (security fail) | `security-review` | not yet wired |
+| `verify:result` (conflict) | `merge-conflict` | not yet wired |
+| `run:complete` (pre-merge) | `pre-merge` | not yet wired |
+| `story:start` (ambiguous) | `story-ambiguity` | not yet wired |
+| `review:result` (gate) | `review-gate` | not yet wired |
+
+- `cost-exceeded` and `cost-warning` → emit from executor when cost check runs
+
+**Tests:** Unit tests: triggers fire on correct events, disabled triggers don't fire  
+**Files:** `src/pipeline/subscribers/interaction.ts`, `test/unit/pipeline/subscribers/interaction.test.ts`  
+**Deps:** Phase 2
+
+### US-P3-004: Wire Subscribers at Startup
+
+**Update:** `src/execution/sequential-executor.ts`
+
+- At loop start: create event bus, call `wireHooks()`, `wireReporters()`, `wireInteraction()`
+- Pass event bus to `runPipeline()` (already accepts `eventEmitter` param)
+- **Remove** all direct `fireHook()` calls from sequential-executor
+- **Remove** all direct `getReporters()` calls from pipeline-result-handler
+- **Remove** all direct `executeTrigger()` calls from pipeline-result-handler
+
+**Update:** `src/execution/parallel-executor.ts`
+- Same: wire subscribers, remove direct calls
+
+**Update:** `src/pipeline/stages/completion.ts`
+- Remove direct `fireHook("on-story-complete")` — now fires from subscriber
+- Instead: emit `story:complete` event
+
+**Update:** `src/execution/escalation/tier-outcome.ts`
+- Remove 4x `fireHook()` calls — now fires from subscriber
+- Instead: emit `story:fail` event from escalation handler
+
+**Tests:** Integration tests verifying hooks/reporters/triggers fire correctly via event bus  
+**Files:** Multiple files updated, `test/integration/subscriber-wiring.test.ts`  
+**Deps:** US-P3-001–003
+
+### Phase 3 Gate
+- [ ] All existing tests pass
+- [ ] Zero direct `fireHook()` calls remain in pipeline stages
+- [ ] Zero direct `fireHook()` calls remain in execution/ (except lifecycle setup/cleanup if needed)
+- [ ] Zero direct `getReporters()` calls remain in pipeline-result-handler
+- [ ] Zero direct `executeTrigger()` calls remain in pipeline-result-handler
+- [ ] All hooks fire correctly via event bus
+- [ ] All reporters receive events via event bus
+
+---
+
+## Phase 4: Executor Simplification
+
+**Goal:** Remove all ad-hoc orchestration code. Delete deprecated files. Simplify executor to ~80-100 lines.
+
+### US-P4-001: Remove Routing Duplication
+
+**Update:** `src/execution/sequential-executor.ts`
+
+- Remove `routeTask()` call (lines ~170-200)
+- Remove `applyCachedRouting()` call
+- Pipeline `routing` stage is now the single source of routing
+- Executor reads routing result from `pipelineResult.context.routing`
+
+**Tests:** Verify routing works correctly via pipeline stage only  
+**Files:** `src/execution/sequential-executor.ts`  
+**Deps:** Phase 3
+
+### US-P4-002: Remove Post-Verify from Result Handler
+
+**Update:** `src/execution/pipeline-result-handler.ts`
+
+- Remove `runPostAgentVerification()` call from `handlePipelineSuccess()`
+- Pipeline `regression` stage now handles this
+- `handlePipelineSuccess()` reduces to: collect metrics, update PRD, log progress
+- `handlePipelineFailure()` reduces to: check escalation budget, update story status
+
+**Tests:** Port `test/unit/execution/post-verify.test.ts` assertions to regression stage tests  
+**Files:** `src/execution/pipeline-result-handler.ts`  
+**Deps:** Phase 3
+
+### US-P4-003: Simplify Executor Loop
+
+**Update:** `src/execution/sequential-executor.ts`
+
+- Remove `preIterationTierCheck()` — escalation now handled by pipeline stages returning `escalate`
+- Remove story-level hook calls — handled by subscribers
+- Remove cost check logic — emit to event bus, interaction subscriber handles it
+- Simplified loop:
+  ```ts
+  for (let i = 0; i < maxIterations; i++) {
+    const story = getNextStory(prd)
+    if (!story) break
+    
+    bus.emit("story:start", story, routing)
+    const result = await runPipeline(defaultPipeline, pipelineContext, bus)
+    
+    switch (result.finalAction) {
+      case "complete": storiesCompleted++; break
+      case "escalate": bumpTier(story); break
+      case "fail": markFailed(story); break
+      case "pause": bus.emit("run:pause", result.reason); return
+      case "skip": break
+    }
+  }
+  
+  await runPipeline(postRunPipeline, postRunContext, bus)
+  bus.emit("run:complete", buildSummary())
+  ```
+
+**Tests:** Full integration test of simplified executor  
+**Files:** `src/execution/sequential-executor.ts`  
+**Deps:** US-P4-001, US-P4-002
+
+### US-P4-004: Delete Deprecated Files + Cleanup
+
+**Delete:**
+
+| File | Lines | Replaced by |
+|------|-------|------------|
+| `src/execution/post-verify.ts` | 193 | `src/pipeline/stages/regression.ts` |
+| `src/execution/post-verify-rectification.ts` | 190 | `src/pipeline/stages/rectify.ts` |
+| `src/execution/verification.ts` | 72 | `src/verification/orchestrator.ts` |
+| `src/execution/rectification.ts` | 13 | `src/verification/orchestrator.ts` |
+| `src/verification/gate.ts` | 208 | `src/verification/orchestrator.ts` |
+| `src/execution/lifecycle/story-hooks.ts` | 38 | `src/pipeline/subscribers/reporters.ts` |
+
+**Update test files:**
+
+| Test file | Action |
+|-----------|--------|
+| `test/unit/execution/post-verify.test.ts` | Delete (replaced by regression stage tests) |
+| `test/unit/execution/post-verify-regression.test.ts` | Delete (replaced by regression strategy tests) |
+| `test/unit/execution/lifecycle/run-regression.test.ts` | Update to test thin wrapper |
+| `test/integration/rectification-flow.test.ts` | Update to use orchestrator |
+| `test/integration/verify-stage.test.ts` | Update to verify orchestrator delegation |
+
+**Cleanup:**
+- Remove all `@deprecated` shim re-exports from `src/execution/index.ts`
+- Remove unused imports across codebase
+- Run `biome check --fix` for final cleanup
+
+**Tests:** Full test suite must pass with zero skipped tests  
+**Files:** Multiple deletions and updates  
+**Deps:** US-P4-001–003
+
+### Phase 4 Gate
+- [ ] All tests pass
+- [ ] Zero deprecated shim files remain
+- [ ] `sequential-executor.ts` < 120 lines
+- [ ] `pipeline-result-handler.ts` < 200 lines
+- [ ] No direct `fireHook()` in stages or executors
+- [ ] No direct `getReporters()` in result handlers
+- [ ] No direct `executeTrigger()` in result handlers
+- [ ] `bun run typecheck` clean
+- [ ] `bun run lint` clean
+
+---
+
+## Summary: File Changes
+
+### New Files (12)
+
+| File | Phase |
+|------|-------|
+| `src/verification/strategies/scoped.ts` | 1 |
+| `src/verification/strategies/regression.ts` | 1 |
+| `src/verification/strategies/acceptance.ts` | 1 |
+| `src/verification/orchestrator.ts` | 1 |
+| `src/pipeline/event-bus.ts` | 1 |
+| `src/pipeline/stages/rectify.ts` | 2 |
+| `src/pipeline/stages/autofix.ts` | 2 |
+| `src/pipeline/stages/regression.ts` | 2 |
+| `src/pipeline/subscribers/hooks.ts` | 3 |
+| `src/pipeline/subscribers/reporters.ts` | 3 |
+| `src/pipeline/subscribers/interaction.ts` | 3 |
+| `src/review/orchestrator.ts` | 2 |
+
+### Modified Files (Key)
+
+| File | Phase | Change |
+|------|-------|--------|
+| `src/verification/types.ts` | 1 | Add VerifyResult, VerifyContext |
+| `src/pipeline/types.ts` | 2 | Add retry action, verifyResult to context |
+| `src/pipeline/runner.ts` | 2 | Handle retry action |
+| `src/pipeline/stages/index.ts` | 2 | New stage order |
+| `src/pipeline/stages/verify.ts` | 2 | Delegate to orchestrator |
+| `src/pipeline/stages/review.ts` | 2 | Delegate to orchestrator |
+| `src/config/schema.ts` | 2 | Add lintFix, formatFix, autofix config |
+| `src/execution/sequential-executor.ts` | 3-4 | Wire subscribers, simplify loop |
+| `src/execution/pipeline-result-handler.ts` | 4 | Remove post-verify, simplify |
+| `src/execution/escalation/tier-outcome.ts` | 3 | Remove fireHook calls |
+| `src/pipeline/stages/completion.ts` | 3 | Remove fireHook, emit event |
+
+### Deleted Files (6)
+
+| File | Phase | Lines removed |
+|------|-------|--------------|
+| `src/execution/post-verify.ts` | 4 | 193 |
+| `src/execution/post-verify-rectification.ts` | 4 | 190 |
+| `src/execution/verification.ts` | 4 | 72 |
+| `src/execution/rectification.ts` | 4 | 13 |
+| `src/verification/gate.ts` | 4 | 208 |
+| `src/execution/lifecycle/story-hooks.ts` | 4 | 38 |
+
+**Net:** +12 files, -6 files, ~714 lines deleted from deprecated code
+
+---
+
+## Risk Mitigation
+
+| Risk | Mitigation |
+|------|-----------|
+| Regression from large refactor | Each phase independently testable; full suite gate between phases |
+| Retry infinite loops | `MAX_STAGE_RETRIES` hard cap (default: 5) |
+| Event bus debugging difficulty | Structured logging on all event emissions; `debug` log level shows all events |
+| Backward compatibility | Phase 1 is additive only; deprecated shims kept until Phase 4 |
+| Test file updates | Track which tests need updating per phase; never delete a test without replacement |
+| TDD verdict.ts integration | Phase 2 — update verdict.ts to call orchestrator; test TDD flow end-to-end |
+
+---
+
+## Implementation Order Within Each Phase
+
+Phase 1: P1-001 → P1-002 → P1-003 → P1-004 → P1-005 (sequential, each builds on types)  
+Phase 1: P1-006 can run in parallel with P1-001–005  
+Phase 2: P2-001 first (retry action), then P2-002–004 in parallel, then P2-005 last (wiring)  
+Phase 3: P3-001–003 in parallel (independent subscribers), then P3-004 (wiring)  
+Phase 4: P4-001 → P4-002 → P4-003 → P4-004 (sequential, each simplifies more)