Cursor rule

1---
2description: Genesis Colonies ticket workflow — GC-000 architecture enforcement
3alwaysApply: true
4---
5 
6# Genesis Colonies — Agent Rules
7 
8> Genesis Colonies bevorzugt **Konsistenz über Komfort** — erweitere kanonische Systeme, führe keine Parallel-Systeme ein.
9 
10## Before any task
11 
121. Read `docs/WORKFLOW.md` and **`docs/CORE_ARCHITECTURE.md`** (GC-000, Regeln 15–17, **19**).
132. Follow **`.cursor/rules/no-dead-code-no-bloat.mdc`** — extend Owner, remove replaced code in the same ticket.
143. Read the relevant master doc(s) for the ticket domain.
154. Work only the ticket scope (max 3–5 files). No full-project analysis.
165. Respect architecture: PJAX shell, planet scope (`get_context_planet`), single queue engine, canonical systems.
17 
18## Master docs (single source of truth)
19 
20- `docs/CORE_ARCHITECTURE.md` — **mandatory** GC-000 rules
21- `docs/AJAX_PJAX_CONTRACT.md` — PJAX, `applyActionState`, no reload
22- `docs/QUEUE_STATE_RULES.md` — finish before mutate, reschedule after cancel
23- `docs/ARCHITECTURE.md` — overview
24- `docs/PLANET_SCOPE.md` — active planet
25- `docs/PLANET_EVOLUTION.md`, `docs/ECONOMY_SYSTEM.md`, `docs/BUILDINGS_SYSTEM.md`, `docs/RESEARCH_SYSTEM.md`
26- `docs/FLEET_SYSTEM.md`, `docs/GALAXY_SYSTEM.md`, `docs/EFFECTS.md`, `docs/STATE_AJAX.md`, `docs/ROADMAP.md`
27 
28## Forbidden (GC-000)
29 
30- "Analyze the entire project" / scan all files without ticket scope
31- `location.reload()` / `location.href =` for in-game navigation (use `GC.navigateTo`, `GC.reloadCurrentPage`)
32- Frontend math for game mechanics (resources, queues, flight time, combat)
33- Module-owned game-state polling (only `/api/game-state`)
34- Session-based planet scope; homeworld hardcoding in features
35- **Parallel systems** (Regel 15): `shipyard`+`orbital_shipyard`, `fleet_state`+`fleet_movements`, `planet_session`+`active_planet_id`, `combat_v1`+`combat_v2` — only migration+alias, never two live systems
36- **Duplicate math** (Regel 16): no frontend production/fleet/combat/queue formulas — use `EffectResolver`, `fleet_calc`, `queue_engine`
37- **Wrong owner** (Regel 17): new logic must land in the Owner module from CORE_ARCHITECTURE §17, not a new parallel file
38- **Dead code / bloat** (Regel 19): no new helper beside old logic — migrate call-sites, delete unused code, `grep` old symbols before done
39- Queue mutations without `finish_due_work_once` first
40- POST actions without `{ ok, state }` + `applyActionState()` on client
41- Unrequested refactors outside the ticket
42- Implementing an Epic directly — split into GC-XXX tickets
43 
44## Required patterns
45 
46- Server authority; UI displays server data only
47- Actions: `GC.fetchGameAction` → `applyActionState(res, reason)`
48- PJAX: `GC.cleanupPage()` / `GC.registerCleanup()` on module init
49- Planet-bound logic: `get_context_planet()`
50- New queue types: follow `docs/QUEUE_STATE_RULES.md` (incl. reschedule after cancel)
51- Replacing a system: migration → alias/adapter → remove old; document owner in `CORE_ARCHITECTURE.md` §17 if new domain
52 
53## After completing a ticket
54 
55Output only:
56 
57- Root Cause
58- Changed Files
59- Tests
60- Ergebnis
61- Regel 19: replaced/removed logic, updated call-sites, dead-code search
62 
63Update master docs if architecture changed.
64 
65## Code conventions
66 
67- Logic in `game/`, thin routes in `app.py`
68- Schema changes → new `migrations/NNN_*.sql`
69- Idempotent APIs: `request_id` / `X-Request-Id`
70- Frontend: extend `GC` namespace in `static/main.js`; cleanup on PJAX
71- **Locales:** neue i18n-Keys immer in **allen** Dateien unter `locales/` nachziehen: `de`, `en`, `es`, `fr`, `pl`, `pt`, `ru`, `tr` — nicht nur de/en
72 
73## UI overlays (dropdowns, menus, popovers)
74 
75Bei jeder neuen UI-Komponente mit Dropdown, Tooltip, Modal, Popover oder Menü prüfen:
76 
77- `overflow` auf Panel-/Card-Ancestors (`.gc-panel`, `.admin-section`, scroll containers)
78- `z-index` via Tokens (`--gc-z-dropdown`, `--gc-z-popover`, …)
79- Mobile Viewport-Höhe / Flip above trigger
80- PJAX: `GC.initHudSelects()` nach Render, `GC.cleanupPage()` schließt offene Layer
81- HUD-Selects nutzen `data-gc-hud-select` + portaled `.gc-popover-layer` — keine nativen `<select>` in overflow:hidden Panels ohne dieses Pattern
82