# Generation 3 Master Plan — FreeExile Modern ARPG Overhaul

## Overview
Succession generation 3 project execution covering M1 (UX/UI & Controls Remediation), M2 (Character Animation & Combat Feel), M3 (PoE2 Skill VFX & Telegraphs), M4 (Skill Catalog & Object Pooling), and M5 (100% E2E Pass, Tier 5 Adversarial Hardening & 120 FPS Optimization).

---

## Phase 1: Milestone 1 Remediation & Gate Verification
- **Step 1.1**: Dispatch `worker_m1_2_gen3` (`teamwork_preview_worker`)
  - Target: Apply verified patches from Fix Explorers 1, 2, and 3.
  - Deliverables: Clean listener setup, W-key resolution, `TEST_INFRA.md` & `registerSlot` contract alignment, NaN guards, static gradient caching, zero-cooldown handling.
  - Verification: 25/25 unit tests pass, M1 E2E tests pass, hygiene lint clean.
- **Step 1.2**: Dispatch M1 Iteration 2 Gate
  - `reviewer_m1_1_gen3` & `reviewer_m1_2_gen3` (`teamwork_preview_reviewer`)
  - `challenger_m1_1_gen3` & `challenger_m1_2_gen3` (`teamwork_preview_challenger`)
  - `auditor_m1_1_gen3` (`teamwork_preview_auditor`)
- **Step 1.3**: Gate Evaluation & M1 Close-out
  - Check strict AND criteria: all tests pass, reviewers approve, challengers approve, auditor CLEAN.
  - Update `PROJECT.md` Milestone 1 status -> `DONE`.

---

## Phase 2: Milestone 2 — Character Animation & Combat Feel Engine
- **Scope**:
  * 5-Phase Kinetic State Machine (`animation_engine.js`): Idle, Run, Wind-up, Hit-stop, Recovery.
  * 4 Weapon Archetype Swing Motions (`weapon_swing_catalog.js`, `weapon_swing_renderer.js`): Slash, Thrust, Slam, Bolt.
  * Micro Hit-stop (2-4 frames / 33-66ms) & Directional Camera Shake (`combat_feel_engine.js`).
  * Static Ring Buffer Damage Number Pool (64 slots, pop-in scale 1.6 -> 1.0).
  * Huyễn Ảnh Bộ Evasion (250ms i-frame, 3-charge pool, tinted ghost trails).
- **Step 2.1**: Dispatch 3 Explorers (`explorer_m2_1_gen3`, `explorer_m2_2_gen3`, `explorer_m2_3_gen3`).
- **Step 2.2**: Dispatch Worker `worker_m2_1_gen3`.
- **Step 2.3**: Dispatch M2 Gate (2 Reviewers, 2 Challengers, 1 Auditor).
- **Step 2.4**: Gate Evaluation -> Mark M2 `DONE`.

---

## Phase 3: Milestone 3 — PoE2 Hybrid Skill VFX Engine & Visual Telegraphs
- **Scope**:
  * 4-Stage Multiphase VFX Pipeline (`vfx_renderer.js`): Charge -> Trajectory -> Impact -> Lingering ground decals.
  * 5 Elemental Presets (`vfx_presets_catalog.js`): Fractal Lightning, Metallic Blood, Sub-Zero Ice, Toxic Smoke, Earthen Fissures.
  * Ground Telegraph Decals (`telegraph_renderer.js`): Cones, circles, rectangular beams with wind-up progress.
  * Directional screen shake matrix & camera flash.
- **Step 3.1**: Dispatch Explorers.
- **Step 3.2**: Dispatch Worker.
- **Step 3.3**: Dispatch M3 Gate (Reviewers, Challengers, Auditor).
- **Step 3.4**: Gate Evaluation -> Mark M3 `DONE`.

---

## Phase 4: Milestone 4 — Comprehensive Skill Asset Catalog & Object Pooling
- **Scope**:
  * Complete metadata for 10 Canonical Skills + Primary Strike + Dodge (`skill_catalog.js`).
  * Static Object Pools (`vfx_pool.js`): 512 particles, 64 projectiles with O(1) recycling.
  * Decoupled combat execution (`combat_skills.js`).
- **Step 4.1**: Dispatch Explorers.
- **Step 4.2**: Dispatch Worker.
- **Step 4.3**: Dispatch M4 Gate.
- **Step 4.4**: Gate Evaluation -> Mark M4 `DONE`.

---

## Phase 5: Milestone 5 — Final E2E Pass, Adversarial Hardening & 120 FPS
- **Step 5.1**: Phase 1 — Pass 100% of E2E Test Suite (`test_poe2_ui_animation_vfx_e2e.py`, all 42 tests passing).
- **Step 5.2**: Phase 2 — Tier 5 Adversarial Coverage Hardening (Challengers find gaps -> Worker patches -> Reviewers verify).
- **Step 5.3**: 120 FPS Frame Budget Telemetry verification (<= 8.33ms per frame) & Zero Memory Leaks.
- **Step 5.4**: Strict Hygiene Lint (`check_code_and_doc_hygiene.py --strict`).
- **Step 5.5**: Final Synthesis & Victory Report to Sentinel.