feat: initial commit with M1-M4 implementation

docs/specs/2026-05-09-tactical-ai-design.md

@@ -0,0 +1,44 @@
+# Design: Tactical AI and Goalie (M4)
+
+## Goal
+Implement a "smart" goalie that covers angles and a zone-based tactical system for players to make the game feel more professional and less like a simple "chase the puck" simulation.
+
+## Architecture
+The system extends the existing steering-based movement. Instead of a simple target, the target is now determined by a combination of the player's role and the current game zone.
+
+### 1. Goalie AI (The Interceptor)
+The goalie's primary objective is to block the path between the puck and the goal center.
+- **Anchor Point**: The center of the goalie's own goal.
+- **Positioning Logic**:
+    - Calculate the vector from the goal center to the puck.
+    - The goalie attempts to stay on this vector, effectively "cutting off the angle".
+    - **Constraint**: The goalie is restricted to a small semi-circle (radius ~100-150px) around the goal center to prevent them from wandering into the midfield.
+    - **Idle State**: When the puck is far away, the goalie returns to the center of the goal.
+- **Movement**: Uses the existing steering physics for smooth transitions.
+
+### 2. Zone-Based Tactics
+The field is divided into three zones for each team: **Defensive**, **Middle**, and **Offensive**.
+
+| Role | Defensive Zone | Middle Zone | Offensive Zone |
+| :--- | :--- | :--- | :--- |
+| **Striker** | Return to Middle/Offensive | Support attack | Aggressively pursue puck |
+| **Defender** | Aggressively pursue puck | Maintain position/Support | Stay back (Insurance) |
+| **Goalie** | Intercept puck | Stay in goal area | Stay in goal area |
+
+### 3. Technical Details
+- **Constants**: Define `WorldZoneWidth` (1/3 of field width) and `GoalieRadius` to avoid magic numbers.
+- **Role Update**: Add `RoleGoalie` to `PlayerRole` enum.
+- **Logic Flow**: `Puck Position` $\rightarrow$ `Zone Detection` $\rightarrow$ `Role-based Target Calculation` $\rightarrow$ `Steering` $\rightarrow$ `Movement`.
+
+## File Changes
+- `internal/entities/player.go`: Add `RoleGoalie`.
+- `internal/game/world.go`: 
+    - Add zone and goal constants.
+    - Implement `updateGoalieAI`.
+    - Refactor `updatePlayerAI` to use zone-based logic.
+- `internal/game/world_test.go`: Add tests for goalie positioning and zone transitions.
+
+## Edge Cases
+- **Puck behind goal**: Goalie resets to center.
+- **Crowding**: Existing anti-clumping logic prevents players from stacking on top of the goalie.
+- **Jitter**: Implement a small distance threshold before updating the target to prevent micro-oscillations.