# Phase 3 Master Execution Plan

- **Audit Phase**: Phase 3 — Finding Consolidation, Root-Cause Analysis, and Master Task Backlog
- **Repository HEAD**: `715873b2ecc3a72ba974bb2a2be87c5ba82bd4e7`
- **Total Implementation Waves**: 4 Waves (Wave 0 to Wave 3)
- **Total Tasks Covered**: 10 Tasks (9 Implementation + 1 Verification)

---

## Dependency & Execution Graph

```mermaid
flowchart TD
    subgraph Wave0 ["Wave 0: Security & Financial Blockers (P0)"]
        SEC001["TASK-SEC-001<br/>(JWT Secret Enforcement)"]
        SEC002["TASK-SEC-002<br/>(CSPRNG OTP & Payload Hardening)"]
        SEC003["TASK-SEC-003<br/>(Admin Settings RBAC Guard)"]
        FIN001["TASK-FIN-001<br/>(Decimal Accounting & N+1 Batching)"]
    end

    subgraph Wave1 ["Wave 1: Build Health & Core Protocol Alignment (P1)"]
        BUILD001["TASK-BUILD-001<br/>(NestJS tsc & Spec Fixes)"]
        AUTH001["TASK-AUTH-001<br/>(Storefront OTP Contract Integration)"]
    end

    subgraph Wave2 ["Wave 2: Frontend Architecture & CI Quality Gates (P2)"]
        FE001["TASK-FE-001<br/>(React Router & Type Cleanup)"]
        DEVOPS001["TASK-DEVOPS-001<br/>(GitHub Actions CI Pipeline)"]
    end

    subgraph Wave3 ["Wave 3: Documentation & E2E Verification (P3 / Verification)"]
        DOC001["TASK-DOC-001<br/>(OpenAPI swagger.yml Sync)"]
        VERIFY001["TASK-VERIFY-001<br/>(End-to-End Integration Suite)"]
    end

    %% Dependencies
    SEC002 --> AUTH001
    BUILD001 --> DEVOPS001
    AUTH001 --> VERIFY001
    SEC003 --> VERIFY001
    FIN001 --> VERIFY001
    BUILD001 --> VERIFY001
```

---

## Wave-by-Wave Execution Details

### Wave 0 — Security & Financial Blockers

- **Tasks**:
  1. `TASK-SEC-001` (Mandatory startup JWT secret check)
  2. `TASK-SEC-002` (CSPRNG OTP code generation & response payload hardening)
  3. `TASK-SEC-003` (Admin Settings RBAC guard enforcement)
  4. `TASK-FIN-001` (Decimal precision arithmetic & N+1 batching in order creation)
- **Rationale**: Wave 0 eliminates critical vulnerability vectors (JWT forgery, OTP prediction, public code exposure, admin authorization bypass) and monetary calculation bugs. Securing backend APIs is a strict prerequisite for wiring frontend clients.
- **Prerequisites**: None. Immediate execution.
- **Parallel Opportunities**: All 4 Wave 0 tasks modify distinct, non-overlapping backend modules (`jwt.strategy.ts`, `auth.service.ts`, `settings.controller.ts`, `orders.service.ts`) and can safely be executed in parallel.
- **Expected Risk**: LOW technical risk. High operational impact: missing `JWT_SECRET` in environment will halt server boot (intended security gate).
- **Validation Required**:
  - `cd backend && npm run test -- backend/src/auth/jwt.strategy.spec.ts`
  - `cd backend && npm run test -- backend/src/auth/auth.service.spec.ts`
  - `cd backend && npm run test -- backend/src/settings/settings.controller.spec.ts`
  - `cd backend && npm run test -- backend/src/orders/orders.service.spec.ts`

---

### Wave 1 — Build Health & Core Protocol Alignment

- **Tasks**:
  1. `TASK-BUILD-001` (NestJS compiler diagnostic fixes & controller spec type alignment)
  2. `TASK-AUTH-001` (Canonical auth contract & storefront SMS OTP integration)
- **Rationale**: Wave 1 restores 100% clean TypeScript compilation (`tsc --noEmit`) and unit spec execution in the backend (`TASK-BUILD-001`). It connects storefront state and modal components to the newly hardened backend SMS OTP endpoints (`TASK-AUTH-001`).
- **Prerequisites**: `TASK-SEC-002` must be completed before `TASK-AUTH-001`.
- **Parallel Opportunities**: `TASK-BUILD-001` (backend code quality/specs) and `TASK-AUTH-001` (storefront client state) target different areas and can run in parallel once Wave 0 is complete.
- **Expected Risk**: LOW to MEDIUM risk (storefront authentication UX changes).
- **Validation Required**:
  - `cd backend && npx tsc --noEmit`
  - `cd backend && npm run test`
  - `npm run test` (Storefront unit runner)

---

### Wave 2 — Frontend Architecture & CI Quality Gates

- **Tasks**:
  1. `TASK-FE-001` (Declarative React Router setup & storefront type cleanup)
  2. `TASK-DEVOPS-001` (GitHub Actions CI workflow definition)
- **Rationale**: Refactors storefront SPA from fragile state-driven view switching to declarative client routing (`react-router-dom`) with URL parameter support (`TASK-FE-001`). Commits automated CI workflow ensuring pull requests are validated before merging (`TASK-DEVOPS-001`).
- **Prerequisites**: `TASK-BUILD-001` (CI pipeline requires backend build/test to pass green).
- **Parallel Opportunities**: `TASK-FE-001` and `TASK-DEVOPS-001` can run in parallel.
- **Expected Risk**: LOW risk. Purely additive CI configuration and clean router abstraction.
- **Validation Required**:
  - `npx tsc --noEmit`
  - `npm run build`
  - `npx actionlint .github/workflows/ci.yml`

---

### Wave 3 — Documentation & Comprehensive E2E Verification

- **Tasks**:
  1. `TASK-DOC-001` (OpenAPI swagger.yml synchronization)
  2. `TASK-VERIFY-001` (End-to-End integration test suite execution across all remediated areas)
- **Rationale**: Wave 3 synchronizes `swagger.yml` with NestJS active endpoints and executes an automated E2E integration test suite validating that all 14 audit findings are 100% resolved without regressions.
- **Prerequisites**: Waves 0, 1, and 2 complete.
- **Parallel Opportunities**: `TASK-DOC-001` can run concurrently with `TASK-VERIFY-001`.
- **Expected Risk**: LOW risk. Documentation and verification script execution.
- **Validation Required**:
  - `cd backend && npm run docs:generate`
  - `cd backend && npm run test:e2e`

---

## Post-Remediation Verification Strategy

Upon completion of Wave 3, the auditor will run full repository regression checks:
1. `npx tsc --noEmit` (Root & backend)
2. `npm run test` (Backend & storefront test suites)
3. `npm run build` (Storefront Vite build & NestJS build)
4. Verification that zero open findings remain in `docs/audit/20-verified-findings-index.json`.