# Project Plan — Spatial Zoning & PoE2 Encounter Life-Cycle

## Objectives
1. Eliminate all hostile monster spawning in Hideouts (`zone_player_hideout`) and Sanctuaries (`zone_boundless_sanctuary`).
2. Retain immortal stationary Target Dummy (`dummy_primal_shrine`) in safe havens with telemetry.
3. Enforce authoritative server validation (`can_spawn_hostile_monsters`, `validate_monster_spawn`).
4. Engineer tactical monster pack spawning, procedural affixes (T1-T15), dynamic ambush triggers in wilderness and map device instances.
5. Implement PoE2 combat telegraphing, dodge roll (Huyễn Ảnh Bộ) i-frames (0.25s), stagger, and leashing back to spawn.
6. Verify 100% pass on automated unit/E2E test suite and strict code/doc hygiene.

## Phases
1. **Phase 0: Survey & Discovery**
   - Explorer 1 (Server & Zoning): Investigate `server/world/zone_engine.py`, safe haven rules, entity lifecycle, teleportation.
   - Explorer 2 (Client & Combat): Investigate `client/webapp/js/engine/monster_system.js`, telegraphing, i-frames, target dummy.
   - Explorer 3 / Spec Miner (Specs & Tests): Investigate `docs/standards/POE2_GAMEPLAY_AND_ZONE_ARCHITECTURE.md`, existing tests `tests/unit/test_zone_monster_spawning_rules.py`, hygiene rules.
2. **Phase 1: Architecture & Decomposition**
   - Synthesize survey findings into `PROJECT.md` at root.
   - Map out Feature Inventory, Interface Contracts, Milestones.
3. **Phase 2: Execution (Dual Track)**
   - E2E Testing Track Orchestrator / Test Writer.
   - Implementation Milestones:
     - Milestone 1: Server Zone Gating & Safe Haven Purity (can_spawn_hostile_monsters, target dummy validation).
     - Milestone 2: Client Monster System & Transition Purification (flushing, dummy rendering, no residual entities).
     - Milestone 3: Wilderness Pack Spawning & Ambush Logic (pack leaders, affixes, encounter density).
     - Milestone 4: Visceral Telegraphing, Dodge Roll i-Frames & Leashing (cones/rings, 0.25s i-frame, poise break).
4. **Phase 3: Final Integration & Adversarial Hardening**
   - 100% E2E test pass across all tiers.
   - Tier 5 adversarial testing & edge-case stress testing.
5. **Phase 4: Final Forensic Audit & Code Hygiene Verification**
   - `python tools/lint/check_code_and_doc_hygiene.py --strict`.
   - Complete handoff and report to parent.