canina/docs/audit/phase3-execution-plan.md

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

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.