feat: add prestige system and skill upgrades with comprehensive documentation

docs/task7/plan_upgrade_effects.md

@@ -0,0 +1,69 @@
+# Refactor Plan: upgrade-effects.ts
+
+## Current State
+- **File:** `src/lib/game/upgrade-effects.ts`
+- **Lines:** 466
+- **Target:** ≤400 lines (reduce by ~66 lines)
+
+## Proposed File Structure
+
+### 1. `src/lib/game/upgrade-effects.ts` (≈220 lines)
+**Keeps:**
+- `upgradeDefinitionsById` (cache)
+- `buildUpgradeCache` function
+- `getActiveUpgrades` function
+- `computeEffects` function (core orchestrator)
+- Evolution path dependency (`SKILL_EVOLUTION_PATHS`, `getUpgradesForSkillAtMilestone`)
+
+**Rationale:** This remains the core orchestration module that ties together evolution paths with upgrade computation.
+
+### 2. `src/lib/game/upgrade-effects.types.ts` (≈60 lines)
+**Contains:**
+- `ActiveUpgradeEffect` interface
+- `ComputedEffects` interface  
+- Re-exports for type consumers
+
+**Rationale:** Pure type definitions separated for clarity.
+
+### 3. `src/lib/game/special-effects.ts` (≈80 lines)
+**Contains:**
+- `SPECIAL_EFFECTS` constant record
+- `hasSpecial` function
+
+**Rationale:** Isolates special effect keys and the simple predicate function.
+
+### 4. `src/lib/game/dynamic-compute.ts` (≈100 lines)
+**Contains:**
+- `computeDynamicRegen` function
+- `computeDynamicClickMana` function
+- `computeDynamicDamage` function
+
+**Rationale:** Groups the three dynamic computation functions that all depend on `SPECIAL_EFFECTS` and share similar patterns.
+
+## Circular Import Risks
+
+**LOW RISK:**
+- `upgrade-effects.ts` depends on `skill-evolution` - one-way dependency.
+- New files import types from `upgrade-effects.types.ts` and `special-effects.ts`.
+- `dynamic-compute.ts` depends on `special-effects.ts` and types - safe.
+
+**MITIGATION:**
+- Keep type re-exports clean.
+- If `computeEffects` needs dynamic functions, import them from `dynamic-compute.ts`.
+
+## Extraction Order
+
+**1 → 2 → 3 → 4**
+
+1. Create `upgrade-effects.types.ts`, move type interfaces, update imports.
+2. Create `special-effects.ts`, move `SPECIAL_EFFECTS` + `hasSpecial`, update imports.
+3. Create `dynamic-compute.ts`, move the three `computeDynamic*` functions, update imports.
+4. Trim `upgrade-effects.ts` - remove moved items, update internal imports.
+
+## Import Updates Required
+
+Files importing from `upgrade-effects.ts` need updates:
+- Types → `upgrade-effects.types.ts`
+- Special effects → `special-effects.ts`
+- Dynamic compute → `dynamic-compute.ts`
+- Core functions → `upgrade-effects.ts`