Build seamless game loop prototype

public/docs/gap-analysis.md

@@ -0,0 +1,305 @@
+# Gap Analysis — EVE-Inspired Multiplayer Prototype GDD
+
+**Date:** 2026-05-24  
+**Last Updated:** 2026-05-25 (Session 7)  
+**Scope:** Full cross-reference of design documentation vs. interactive demos vs. roadmap readiness
+
+---
+
+## Session 7 Progress (2026-05-25)
+
+Comprehensive fresh gap analysis identified 20 missing specs. The 3 critical blockers for Phase 0 have been addressed:
+
+| Gap | Resolution |
+|---|---|
+| **Galaxy Generation Spec** (Critical #1) | Added "Galaxy Generation" sub-tab to Backend → Galaxy Simulation. Concrete parameters: 4 regions, ~50 systems (MVP), Poisson disk placement, MST + random edges stargate topology, starter system template, faction territory seeding, station/belt placement rules, full pseudocode. Deterministic seeded RNG. |
+| **Ship Acquisition Flow** (Critical #2) | Added "🚀 Acquisition" tab to Ships page. Free Rookie Frigate on spawn and death respawn. 5 acquisition methods (free grant, NPC market, player market, manufacturing, LP store). NPC ship pricing table. Ship switching flow (dock → hangar → select → activate). Hangar storage model. Backend schema changes (storage_location, is_rookie, switch_ship reducer). |
+| **Warp & Travel Mechanics** (Critical #3) | Added "🚀 Travel & Warp" tab to Gameplay page. 3 travel modes (sub-warp, warp, gate jump) with speeds. Warp sequence (align → accelerate → cruise → exit). Warp speeds by ship class (3.0–6.0 AU/s). Stargate mechanics (2.5km activation, 5s jump cooldown, 30s gate cloak). Gate guns by security level. Docking/undocking with invulnerability. Autopilot vs manual piloting. Warp disruption. Backend state columns (travel_mode, gate_cloak_until, weapons_timer_until, etc.). |
+
+### Remaining 17 Gaps (from 20-item analysis)
+
+| Priority | Gap | Status |
+|---|---|---|
+| 🟠 Important | Mining Mechanics Detail (cycle time, yield, depletion) | Not started |
+| 🟠 Important | Module Activation & Cycle System | Not started |
+| 🟠 Important | Damage Types & Resistances | Not started |
+| 🟠 Important | Stargate Mechanics | **Resolved** — covered in Travel & Warp tab |
+| 🟠 Important | Multiplayer Combat (Phase 13) | Not started |
+| 🟠 Important | Scanning / Exploration System | Not started |
+| 🟠 Important | Fleet System | Not started |
+| 🟡 Nice-to-have | Contract system | Not started |
+| 🟡 Nice-to-have | Cloaking/stealth | Not started |
+| 🟡 Nice-to-have | Server admin/GM tools | Not started |
+| 🟡 Nice-to-have | Settings/preferences panel | Not started |
+| 🟡 Nice-to-have | Performance targets | Not started |
+| 🟡 Nice-to-have | Galaxy Generation demo | **Resolved** — Interactive Galaxy Generation demo created. Validates seeded RNG, region/constellation/system placement, MST stargate topology, station/belt seeding, security distribution, connectivity check, route finding. 12th demo. |
+| 🟡 Nice-to-have | Direct player-to-player trade | Not started |
+| 🟡 Nice-to-have | Death/respawn full UX flow | Partially addressed (respawn mechanism defined in Ship Acquisition) |
+| 🟡 Nice-to-have | Corp backend tables missing from master list | Not started |
+| 🟡 Nice-to-have | Progression demo XP curve mismatch | Not started |
+
+---
+
+## Session 6 Progress (2026-05-24)
+
+All remaining gap analysis items have been addressed:
+
+| Gap | Resolution |
+|---|---|
+| **Era 1 System Map demo** | Added to demo gallery as a known-needed demo. Listed in demo gallery header note. Implementation is Phase 1 scope (after movement model is built). |
+| **Missing backend tables (factions, regions, constellations)** | Added `regions`, `constellations`, and `factions` to Backend → Tables tab with full field descriptions. `systems` table now has `constellation_id` FK. |
+| **Debug Panel spec** | Expanded from 4 bullet points to 8 items in Gameplay → Screen Specifications. Added: SpacetimeDB table row counts, Agent tick scheduler status, Force-spawn controls (dev mode), Game time display. |
+| **Tutorial / Onboarding spec** | Already resolved in Session 5 (OV-05). 5-mission guided sequence, tutorial principles, Zora as guide, skip mechanics, stuck-player detection. |
+| **Error handling / Reconnection spec** | Added to Architecture → ARCH-4. 7 disconnection scenarios, reconnection flow with exponential backoff, anti-exploit (combat logging) rules. |
+| **Session persistence / Save-Load spec** | Added to Architecture → ARCH-5. No save button, no localStorage. SpacetimeDB is continuous persistence. Full table-by-table persistence guarantee. |
+| **Sound / Audio design spec** | Added to Architecture → ARCH-6. 6 audio categories, 6 volume sliders, spatial audio rules, Phase 7 scope. |
+| **Localization / i18n decision** | Added to Architecture → ARCH-7. MVP English-only with day-one i18n architecture (string keys, Intl formatters, RTL-ready CSS). |
+| **Accessibility spec** | Added to Architecture → ARCH-8. 8 accessibility areas with requirements and implementation details. Gate 4 acceptance tests. |
+| **Corporations & Territory spec** | Added as new tab to Social page (SOC-CORP). Full spec: corp lifecycle, 5 roles, wallet/tax system, territory & sovereignty (3 structure tiers), 6 new backend tables, 11 new reducers. Phase 14 scope. |
+
+---
+
+## Session 5 Progress (2026-05-24)
+
+The following gaps have been addressed based on a full 15-point critique review:
+
+| Gap | Resolution |
+|---|---|
+| **Economy first-30-minutes walkthrough** | Added "First 30 Minutes" tab to Economy page (ECON-30). 14-step walkthrough from spawn to loop-set, emphasizing price discovery as the aha moment. |
+| **Power allocation failure modes** | Added GP-FAIL section to Gameplay → Core Loop tab. Per-subsystem failure table (Weapons→no firing, Shields→no recharge, Engines→immobile, Aux→no specials). Reroute timing (1.5–3s). |
+| **Flight Mode HUD cognitive load** | Added Red Alert mode to GP-FAIL. When shields <25% and taking armor damage, non-essential HUD elements collapse. Combat HUD expands. Cannot be disabled. |
+| **Roadmap integration gates** | Added 6 integration gates to Roadmap page (Gate 1–6). Each gate covers a phase group and defines a focused playtest. |
+| **Gap analysis partial resolutions** | (a) Bounty is now sector-specific (petty=system-local, standard=regional, dangerous+=galaxy-wide). (b) AI module examples added to both fitting examples in Ships page. (c) Onboarding/tutorial section added to Overview → OV-05 with 5-mission guided sequence. |
+| **Zora phased delivery** | Added phased delivery milestones table to Ship AI → Implementation Tiers section. Maps Zora features to roadmap phases (Phase 0 stub → Phase 7 Tier 0 complete → Phase 12 Tier 1 → Phase 15+ Tier 2). Full design kept intact. |
+| **Faucet/sink untestable in Era 1** | Added Balancing Agent system (new tab: Gameplay → Balancing Agent). Monitors 5 metrics (ISK velocity, price index, death rate, faucet/sink ratio, engagement). Controls 4 levers (NPC spawn rate, difficulty tier, ISK faucet multiplier, world event frequency). New tables: balance_metrics, balance_levers, balance_audit. |
+| **ER diagram** | Added ER Diagram tab to Backend page. 5 clusters (Player, Economy, World, Social, Ship AI) with all 50+ tables, PKs, FKs, and cross-cluster flow descriptions. |
+| **Chinese characters** | Fixed: "PvP主力" → "PvP main combat ships" in Insurance table. |
+| **Currency naming** | Added ISK temporary placeholder note to Economy → Flow Overview tab. All ISK references are subject to renaming. |
+| **Security level 0.0 gap** | Fixed: Security 0.0 is explicitly null-sec. Added clarification to Gameplay → Security Levels intro text. |
+| **Architecture page localStorage** | Fixed: Architecture overview now states "There is no localStorage — persistence is always through SpacetimeDB, even in single-player Era 1." |
+| **No respec mentioned** | Added respec mechanics to Social → Progression tab (SOC-RESPEC). 20% XP penalty, 7-day cooldown, full or single-skill respec, requires Neural Remapping facility. |
+| **Roadmap localStorage** | Fixed: Phase 0 goal now mentions "local SpacetimeDB instance". Phase 7 doneWhen says "SpacetimeDB persists all state — no localStorage". Era 1 subtitle reflects SpacetimeDB-from-day-1. |
+| **World events missing lightweight Era 1 version** | Phase 7 doneWhen now includes "Lightweight exploration events spawn in visited systems." Integration Gate 4 validates exploration events as part of Era 1 completion. |
+
+---
+
+## Session 4 Progress (2026-05-24)
+
+The following gaps have been addressed:
+
+| Gap | Resolution |
+|---|---|
+| **HUD ambiguity resolved** | Decision documented in Overview → OV-04 "HUD & View Mode Architecture": game uses two view modes — Flight Mode (diegetic overlays on 3D viewport when undocked) and Station Mode (traditional panel UI when docked). Map Mode is shared. Demo gallery updated: gamehud now labeled "Game HUD (Flight Mode)", starmap labeled "Star Map (Era 2 Galaxy Map)". Transition rules specified (undock, dock, open map, combat ambush). |
+| **Starmap demo labeled correctly** | Demo gallery entry renamed from "Star Map" to "Star Map (Era 2 Galaxy Map)" with explicit validates/limitations noting it covers the Era 2 Galaxy Map, NOT the Era 1 System Map. Era 1 System Map still needs a separate demo. |
+| **Mission system spec** | Full spec added to Gameplay → Missions tab: 6 mission types (Kill/Courier/Mining/Survey/Escort/Trade), NPC agent interaction flow (6 steps), standing mechanics (6 tiers from Hostile to Inner Circle), reward scaling table (4 levels), Loyalty Points secondary currency, 6 new backend tables (npc_agents, mission_templates, active_missions, player_standing, player_loyalty_points, mission_offers), mission-related reducers. |
+| **World event UX spec** | Full spec added to Gameplay → World Events UX tab: 3 notification tiers (Critical/Nearby/Background) with Flight Mode and Station Mode behavior, Event Detail Panel layout (7 sections), event map integration (System Map Era 1 + Galaxy Map Era 2), contribution tracking with anti-AFK, 3 reward tiers (Bronze/Silver/Gold), Galaxy Story Log with search/export. |
+| **Economy spec brought to Market demo level** | New "Market Surface" section added to Economy → Flow Overview tab: order book & depth with bid/ask spread, candlestick price history charts, contract specifications, margin accounts & long/short positions (Era 2), commodity ticker, station-filtered view. Acknowledges the Market demo implements all of these. |
+| **Manufacturing depth expanded** | Manufacturing tab expanded from 2 cards to 4 sections: Full Production Chain (5-tier chain: Ore → Mineral → Component → Module → Ship), Blueprint Research with ME/TE levels and cost/time curves, Production Queues with concurrent job limits by skill, Station Facility tiers, BPC copies, and Invention (post-MVP T2). |
+| **Backend tables for missions** | Added 6 new mission-related tables to Backend → Tables tab: npc_agents, mission_templates, active_missions, player_standing, player_loyalty_points, mission_offers. Total tables now 44. |
+
+---
+
+## Session 3 Progress (2026-05-24)
+
+The following gaps have been addressed:
+
+| Gap | Resolution |
+|---|---|
+| **NPC price adjustment algorithm** | Full spec added to Economy → NPC Pricing tab: demand pressure algorithm with EMA, price formula (base × regional × demand × station type), worked tick-by-tick example, regional price seed table with 6 regions, anti-arbitrage safeguards, 3 new backend tables (`station_commodity_demand`, `commodity_price_params`, `regional_price_seeds`), `market_price_adjust` agent updated. |
+| **Chat/comms prototype** | New interactive demo (`js/demos/chat.js`): 4 channels (Local/Trade/Private/Fleet), light-speed delay simulation with formula `2 × √(jumps)`, pre-seeded message corpus, pilot proximity sidebar with delay map, NPC auto-responses in local channel. Registered in sidebar, loader, app, and demo gallery. |
+| **Zora Tier 0 demo** | New interactive demo (`js/demos/zora.js`): deterministic template engine with 15 event triggers × 5 soul depths, module gating logic (6 modules), personality axes sliders, response history. Validates the soul depth progression from raw status codes to full personality. Registered in sidebar, loader, app, and demo gallery. |
+| **Backend tables for NPC pricing** | Added `station_commodity_demand`, `commodity_price_params`, `regional_price_seeds` to Backend → Tables tab. |
+| **Agent updated for NPC pricing** | Updated `market_price_adjust` agent interval from 900s to 300s, added cross-reference to Economy → NPC Pricing tab. |
+
+---
+
+## Session 2 Progress (2026-05-24)
+
+The following gaps from the original analysis have been addressed:
+
+| Gap | Resolution |
+|---|---|
+| **Currency naming** | Standardized to "ISK" with symbol `₢`. Removed all "credits" references. Updated overview, ships, roadmap. |
+| **Chat scope ambiguity** | Core loop Step 8 now explicitly states "Requires multiplayer — ships in Phase 11 (Era 2)." Summary paragraph clarified Steps 1–7 as Era 1. |
+| **Security level system** | Full spec added to Gameplay → Security Levels tab: 4 security bands (+1.0 to −1.0), player security status (−10 to +5), CONCORD response tiers, PvP rules per band, backend schema changes. |
+| **NPC pirate AI behavior** | Full spec added to Gameplay → NPC Pirates tab: spawning rules, location-based triggers, difficulty tiers by security band, 4 behavior templates (orbit kiter, brawler, shield tank, EWAR support), state machine (idle→aggro→combat→flee→dead), new backend tables + agents. |
+| **CONCORD response model** | Full spec added to Gameplay → CONCORD tab: response time by system sec (3s–15s), CONCORD force scaling, 6-step response pipeline, anti-exploit rules, suspect vs. criminal flag system, weapons timer. |
+| **Insurance system** | Full spec added to Gameplay → Insurance tab: 4 coverage tiers (None/Basic/Standard/Platinum), premium/payout structure, ISK faucet/sink analysis, anti-abuse rules, new backend tables + reducers. |
+| **Missing backend tables** | Added 13 new tables to Backend → Tables tab: `ship_types`, `modules_catalog`, `ship_fittings`, `npc_entities`, `npc_class_templates`, `loot_tables`, `blueprints`, `manufacturing_jobs`, `skills_catalog`, `chat_channels`, `insurance_policies`, `ship_type_base_values`. |
+| **Missing agents** | Added `pirate_spawn`, `pirate_combat_tick`, `pirate_loot_drop`, `concord_response`, `security_status_tick` agents to catalog. |
+| **AI Crew vs Zora confusion** | Added clarifying callout to Ships → AI Crew tab explaining the two systems are separate. |
+| **Economy faucet/sink completeness** | Added Insurance Payout as explicit faucet and Insurance Premiums as explicit sink with cross-reference to the new spec. |
+
+---
+
+## Executive Summary
+
+The GDD is remarkably thorough — 12 design pages, 9 interactive demos, a 16-phase roadmap, and a detailed backend schema. The documentation quality is high and internally consistent. However, several substantive gaps exist between **what is specified**, **what is prototyped**, and **what is ready for Phase 0 implementation**. These gaps fall into four categories:
+
+1. **Specified but not prototyped** — features with design detail but no interactive demo
+2. **Prototyped but not fully specified** — demos that go beyond or diverge from the spec
+3. **Cross-reference inconsistencies** — details that conflict between pages
+4. **Missing specifications** — systems implied by the roadmap but not yet designed
+
+---
+
+## 1. Specified but Not Prototyped
+
+These features have meaningful design documentation but no interactive demo to validate UX feel.
+
+| Feature | Spec Location | Gap Description | Risk |
+|---|---|---|---|
+| **Chat & Comms** | Social → Chat & Comms | ~~No chat demo exists.~~ Range-based propagation, light-speed delay, local/system channels are all specified but untested for UX feel. | **Resolved** — Chat & Comms demo created. Validates delay mechanics, channel switching, and pilot proximity. |
+| **Galaxy Map** | Overview → Era 2 Screens | ~~The starmap demo shows a *system* map (single system scale). The *galaxy* map (region/constellation/system hierarchy with faction overlay, world event icons, migration routes) has no demo.~~ **Resolved:** Demo gallery now labels starmap as Era 2 Galaxy Map. The remaining gap is a separate Era 1 System Map demo. | **Partially Resolved** — Era 1 System Map still needs a demo. |
+| **World Events** | Gameplay → Dynamic Galaxy / World Events UX | ~~No demo for world event spawning, propagation, participation, or the story log.~~ Full player-facing UX spec added to Gameplay → World Events UX tab: notification tiers, event detail panel, map integration, contribution tracking, reward tiers, story log. No interactive demo yet. | **Spec Resolved** — UX fully designed. Demo is nice-to-have, not blocking. |
+| **NPC Economy Sim** | Economy → NPC Pricing | ~~The market demo shows a contract exchange with fixed seed data.~~ NPC pricing algorithm now fully specified with demand pressure model, regional seeds, and anti-arbitrage safeguards. No demo for full NPC supply/demand simulation over time yet. | **Spec Resolved** — Algorithm documented. Demo for full multi-station simulation is nice-to-have, not blocking. |
+| **Manufacturing** | Economy → Manufacturing | ~~The refining demo covers ore → mineral but stops there. No demo for manufacturing jobs, blueprint research, production queues, or the mineral → module → ship chain.~~ Manufacturing tab expanded with full production chain (5 tiers), ME/TE research with cost curves, production queues, station facility levels, BPC copies, and invention. No demo yet. | **Spec Resolved** — Full manufacturing chain specified. Demo is Phase 5 scope. |
+| **Ship AI (Zora)** | Ship AI (entire page) | ~~No demo at all.~~ Zora Tier 0 demo created validating deterministic template engine. Tier 1 (LLM-assisted) and Tier 2 (full agent) still unvalidated. | **Partially Resolved** — Tier 0 demo validates soul depth + module gating + personality axes. Higher tiers are post-MVP. |
+| **Corporations & Territory** | ~~Mentioned in roadmap but zero design detail anywhere.~~ **Resolved:** Full spec added to Social → Corporations tab. Corp lifecycle, roles, wallet/tax, territory & sovereignty, 6 new backend tables, 11 new reducers. Phase 14 scope. |
+| **Debug Panel** | ~~Listed as an Era 1 screen with minimal spec.~~ **Resolved:** Expanded to 8 items including SpacetimeDB row counts, agent scheduler status, force-spawn controls, game time display. Utility panel — no demo needed. |
+| **Waypoints & Bookmarks** | Fully specified with backend tables, but no demo. The starmap demo doesn't integrate waypoint creation or route planning. | **Medium** — Navigation UX demo deferred to Phase 1 when System Map is built. Spec is complete. |
+
+---
+
+## 2. Prototyped but Not Fully Specified (Demo Divergences)
+
+These demos contain features or behaviors not reflected in the design docs.
+
+| Demo | Divergence | Impact |
+|---|---|---|
+| **Market** | ~~The market demo implements a full *contract/commodities exchange* with bid/ask spread, price history charts, long/short positions, and margin accounts. The Economy page describes a simpler "order book, price per unit, place sell order from inventory" model. The demo is significantly more ambitious than the spec.~~ **Resolved:** Economy → Flow Overview tab now has a full "Market Surface" section covering order book depth, candlestick charts, contract specs, margin accounts, commodity ticker, and station-filtered view. Spec now matches the demo. | **Resolved** — Economy spec updated to match Market demo's feature set. |
+| **Market** | Uses `₢` symbol for ISK in some places. The Overview page uses "ISK" and "credits" interchangeably. No canonical symbol defined. | **Inconsistency** — minor but should be standardized. |
+| **Combat** | The combat demo implements 3D projectile rendering with beam/bolt types, subsystem damage, and multiple damage types (EM, thermal, kinetic, explosive). The spec mentions "generic damage" as a demo limitation but the actual demo goes further. | **Positive divergence** — spec should acknowledge what the demo actually validates. |
+| **Combat** | Demo uses 4 power subsystems (Weapons/Shields/Engines/Aux). The spec consistently uses the same 4. This is consistent — no gap. | ✓ Aligned |
+| **Game HUD** | ~~The gamehud demo renders a full 3D space scene with diegetic HUD overlays. This is more immersive than the "UI panels" model described in the Overview. The spec should clarify whether the final game uses diegetic overlays or traditional panel layout.~~ **Resolved:** Overview → OV-04 "HUD & View Mode Architecture" documents the decision: Flight Mode uses diegetic overlays (gamehud demo), Station Mode uses traditional panels (market/fitting/refining demos). Hybrid approach. | **Resolved** — HUD ambiguity resolved with two-view-mode architecture. |
+| **Progression** | The progression demo uses a flat XP curve, but the Social page specifies an exponential curve (100 → 500 → 2,000 → 8,000 → 32,000). The demo's "limitations" callout acknowledges this but it means the demo doesn't validate the actual intended feel. | **Known limitation** — should be tracked for Phase 7. |
+
+---
+
+## 3. Cross-Reference Inconsistencies
+
+Details that conflict or are unclear across pages.
+
+| Area | Inconsistency | Pages Involved | Resolution Needed |
+|---|---|---|---|
+| **Currency name** | ~~"ISK", "credits", and `₢` used interchangeably~~ | Overview, Economy, Market Demo | ✅ **Resolved:** Standardized to "ISK" with symbol `₢`. All "credits" references replaced. |
+| **Ship AI module slot type** | The Ships page says "AI module slot type added to fitting schema" in Phase 4 done-when. The Ship AI page says AI modules occupy "medium or low, depending on the module." The Ships page doesn't have a dedicated AI slot column in the ship classes table. | Ships, Ship AI, Roadmap | The slot allocation model is clear in Ship AI (medium for comms/tactical/nav, low for economic/memory). The Ships page should reflect this in the fitting section or acknowledge the overlap. |
+| **Ship AI Tier 0 timeline** | The Roadmap says "Tier 0 Zora" ships in Phase 7. The Ship AI page says Tier 0 = deterministic, no LLM. But Phase 7 also says "bare-bones soul state vector in SpacetimeDB." The Ship AI page's implementation tiers section says Tier 0 is "MVP launch." These are consistent but the overlap between Phase 7 and "MVP" should be explicit. | Roadmap, Ship AI | Clarify: is Phase 7 the Tier 0 launch, or does Tier 0 come later? The current text is consistent but could be more explicit. |
+| **Galaxy map vs star system map** | ~~The Overview distinguishes between "3D Star-System Map" (Era 1, single system) and "Galaxy Map" (Era 2, multi-system). The starmap demo renders a multi-system galaxy view with warp routes. This is the Era 2 galaxy map, not the Era 1 system map.~~ **Resolved:** Demo gallery now labels starmap as "Star Map (Era 2 Galaxy Map)". Overview → OV-04 explicitly notes Era 1 System Map as needed. | **Partially Resolved** — Labeling fixed. Era 1 System Map demo still needed. |
+| **Fitting affects combat** | The Ships page says "Fitting affects combat and mining stats" as Phase 4 done-when. The combat demo and fitting demo are independent — fitting changes don't carry over to combat. | Ships, Demo Gallery | Expected for demos; flagged for implementation planning. |
+| **Information diffusion model** | The Economy page has a detailed diffusion model with specific propagation times (2 min adjacent, 5 min hub, 15 min region, 30 min galaxy). The Backend page's `propagate_market_data` reducer mentions "1 system per 2 minutes per jump" which is consistent. No gap, but the propagation pipeline has no demo. | Economy, Backend | Not a gap per se, but the diffusion pipeline is complex and unvalidated. |
+| **Era 2 screens vs social features** | ~~Chat listed as core loop step but is Phase 11 (Era 2)~~ | Overview, Roadmap, Gameplay | ✅ **Resolved:** Gameplay page now explicitly states Steps 1–7 are Era 1, Step 8 requires multiplayer. |
+| **Kill feed visibility** | Social page says "galaxy-wide feed." Bounty tiers have visibility ranges (system-local, regional, galaxy-wide). The kill feed demo shows all events everywhere. | Social, Bounty Demo | Kill feed should probably follow the same visibility tiering as bounties, or be explicitly always-galaxy-wide. |
+| **AI crew vs Ship AI (Zora)** | ~~Two different AI systems with confusing shared terminology~~ | Ships → Crew, Ship AI | ✅ **Resolved:** Added clarifying callout to Ships → AI Crew tab explaining the two systems are separate. Future expansion may connect them post-MVP. |
+| **NPC pirate spawning** | ~~No spec for pirate spawning, AI behavior, difficulty curves~~ | Gameplay, Agents, Combat Demo | ✅ **Resolved:** Full spec added to Gameplay → NPC Pirates tab. New agents added: `pirate_spawn`, `pirate_combat_tick`, `pirate_loot_drop`. |
+
+---
+
+## 4. Missing Specifications
+
+Systems implied by the roadmap or cross-referenced but not yet designed.
+
+| Missing Spec | Referenced By | Impact |
+|---|---|---|
+| **Pirate / NPC AI behavior model** | ~~Gameplay (PvE Content), Roadmap Phase 3~~ | ✅ **Resolved:** Full spec added to Gameplay → NPC Pirates tab. |
+| **Security level system** | ~~Gameplay (high-sec/low-sec/null-sec mentioned), Ships (security status mentioned), Social (high-sec attacks trigger CONCORD)~~ | ✅ **Resolved:** Full spec added to Gameplay → Security Levels tab. |
+| **CONCORD / law enforcement** | ~~Social (piracy lowers security status), Gameplay (high-sec attacks trigger CONCORD response)~~ | ✅ **Resolved:** Full spec added to Gameplay → CONCORD tab. |
+| **Insurance system** | ~~Economy (faucet: insurance payout), Ships (ship destruction section), Social (insurance premium sink)~~ | ✅ **Resolved:** Full spec added to Gameplay → Insurance tab. |
+| **Mission system** | ~~Economy (faucet: mission rewards), Agents (npc_mission_refresh agent)~~ | ✅ **Resolved:** Full spec added to Gameplay → Missions tab. 6 mission types, agent interaction, standing, rewards, LP, backend tables. |
+| **Tutorial / onboarding** | ~~Roadmap Phase 15, Overview OV-05~~ | ✅ **Resolved:** Full 5-mission tutorial spec in Overview → OV-05. Zora as guide. Skip allowed. Stuck detection. |
+| **Error handling / reconnection** | ~~Roadmap Phase 15~~ | ✅ **Resolved:** Architecture → ARCH-4. 7 disconnection scenarios, reconnection flow with exponential backoff, anti-exploit rules. |
+| **Session persistence / save-load** | ~~Roadmap Phase 7~~ | ✅ **Resolved:** Architecture → ARCH-5. No save button, no localStorage. SpacetimeDB is continuous persistence. Full table-by-table persistence guarantee. |
+| **Sound / audio design** | ~~Ship AI Voice Synthesizer only~~ | ✅ **Resolved:** Architecture → ARCH-6. 6 audio categories, 6 volume sliders, spatial audio rules. |
+| **Localization / i18n** | ~~Not mentioned~~ | ✅ **Resolved:** Architecture → ARCH-7. MVP English-only with day-one i18n architecture. |
+| **Accessibility** | ~~Not mentioned~~ | ✅ **Resolved:** Architecture → ARCH-8. 8 accessibility areas, Gate 4 acceptance tests. |
+
+---
+
+## 5. Backend Schema Gaps
+
+The Backend page lists 44 tables. Cross-referencing with the design docs reveals:
+
+| Missing Table | Referenced By | Note |
+|---|---|---|
+| `blueprints` | ~~Economy (Manufacturing)~~ | ✅ **Added** to Backend → Tables tab. |
+| `manufacturing_jobs` | ~~Economy (Manufacturing), Agents (`production_cycle`)~~ | ✅ **Added** to Backend → Tables tab. |
+| `ship_fittings` | ~~Ships (Fitting System)~~ | ✅ **Added** to Backend → Tables tab. |
+| `modules_catalog` | ~~Ships (Fitting System)~~ | ✅ **Added** to Backend → Tables tab. |
+| `ship_types` | ~~Ships (Ship Classes)~~ | ✅ **Added** to Backend → Tables tab. |
+| `factions` | ~~Backend (Galaxy Simulation) lists it, not in Tables tab~~ | ✅ **Added** to Backend → Tables tab with full field descriptions. |
+| `skills_catalog` | ~~Social (XP & Skills)~~ | ✅ **Added** to Backend → Tables tab. |
+| `npc_entities` | ~~Gameplay (PvE), Agents (enemy_regen, aggro_scan)~~ | ✅ **Added** to Backend → Tables tab + NPC Pirates spec. |
+| `loot_tables` | ~~Gameplay (combat drops)~~ | ✅ **Added** to Backend → Tables tab + NPC Pirates spec. |
+| `regions` / `constellations` | ~~Backend (Galaxy Simulation) lists them, not in Tables tab~~ | ✅ **Added** to Backend → Tables tab. `systems` now has `constellation_id` FK. |
+| `corporations` | ~~Roadmap Phase 14 — not designed~~ | ✅ **Specified** in Social → Corporations tab. 6 new tables added. Phase 14 scope. |
+| `chat_channels` | ~~Social (Chat)~~ | ✅ **Added** to Backend → Tables tab. |
+
+---
+
+## 6. Roadmap Readiness Assessment
+
+Assessing whether each Phase has enough specification to begin implementation.
+
+| Phase | Title | Spec Readiness | Blockers |
+|---|---|---|---|
+| **0** | Local Skeleton | ✅ Ready | None. Tech stack is specified. File structure is defined. |
+| **1** | Movement & Commands | ✅ Ready | Movement model is fully specified in Backend → Movement Model. |
+| **2** | Mining & Inventory | ✅ Ready | Mining cycle, inventory panel, and fake-backend data models exist. |
+| **3** | Combat — FTL Power Allocation | ✅ Ready | ~~NPC pirate AI behavior was missing.~~ **Resolved:** NPC Pirates, Security Levels, CONCORD, and Insurance specs added to Gameplay page. |
+| **4** | Ship Fitting | ✅ Ready | ~~`ship_types`, `modules_catalog`, and `ship_fittings` tables were missing.~~ **Resolved:** All three added to Backend → Tables tab. |
+| **5** | Refining & Manufacturing | ✅ Ready | ~~Refining is well-specified. Manufacturing is described but `blueprints` and `manufacturing_jobs` tables were missing.~~ **Resolved:** Both tables added to Backend → Tables tab. |
+| **6** | NPC Economy Sim | ✅ Ready | ~~Economy philosophy is clear, but NPC price adjustment logic, regional price seeding, and the full diffusion pipeline lack implementation detail beyond pseudocode.~~ **Resolved:** NPC pricing algorithm fully specified. Regional price seeds documented. Demand pressure model defined. Backend tables added. |
+| **7** | Single-Player Polish | ✅ Ready | Tutorial/onboarding (OV-05), error handling (ARCH-4), persistence (ARCH-5), audio (ARCH-6), accessibility (ARCH-8) all fully specified. Tier 0 Zora demo exists. Mission system fully specified. |
+| **8–15** | Era 2 | ✅ Ready | Era 2 depends on SpacetimeDB integration. Chat demo exists. World event UX fully specified. Corporations and territory fully specified (SOC-CORP). Multiplayer combat needs spec work (Phase 13 scope). |
+
+---
+
+## 7. Priority Recommendations
+
+### Immediate (before starting Phase 0)
+
+1. ~~**Standardize currency naming**~~ ✅ **Done.** ISK + ₢ symbol.
+2. ~~**Clarify core loop scope**~~ ✅ **Done.** Steps 1–7 = Era 1, Step 8 = Era 2.
+3. ~~**Create `ship_types` and `modules_catalog` table specs**~~ ✅ **Done.** Added to Backend → Tables tab.
+
+### Before Phase 3 (Combat)
+
+4. ~~**Specify NPC pirate AI behavior**~~ ✅ **Done.** Gameplay → NPC Pirates tab.
+5. ~~**Define security level system**~~ ✅ **Done.** Gameplay → Security Levels tab.
+6. ~~**Specify CONCORD response model**~~ ✅ **Done.** Gameplay → CONCORD tab.
+
+### Before Phase 6 (Economy)
+
+7. ~~**Detail NPC price adjustment algorithm**~~ ✅ **Done.** Economy → NPC Pricing tab with full algorithm, regional seeds, anti-arbitrage safeguards, backend tables.
+8. ~~**Create a chat prototype**~~ ✅ **Done.** Chat & Comms demo validates range-based propagation, light-speed delay, channel switching.
+
+### Before Era 2
+
+9. ~~**Design the Galaxy Map**~~ ✅ **Done.** Era 2 Galaxy Map demo exists. Era 1 System Map is Phase 1 implementation scope.
+10. ~~**World event UX prototype**~~ ✅ **Done.** Full UX spec added to Gameplay → World Events UX tab.
+11. ~~**Clarify AI Crew vs Zora relationship**~~ ✅ **Done.** Added clarifying callout to Ships → AI Crew tab.
+12. ~~**Corporations & Territory spec**~~ ✅ **Done.** Full spec added to Social → Corporations tab. 6 new tables, 11 new reducers, 3 structure tiers, sovereignty mechanics. Phase 14 scope.
+
+### Ongoing
+
+12. ~~**Add missing backend tables**~~ ✅ **Done.** All tables added to Backend → Tables tab including regions, constellations, factions.
+13. ~~**Create a Zora Tier 0 demo**~~ ✅ **Done.** Deterministic template engine with 15 events × 5 soul depths, module gating, personality axes. Validates soul depth progression and module tradeoffs.
+14. ~~**Error handling & reconnection spec**~~ ✅ **Done.** Architecture → ARCH-4.
+15. ~~**Session persistence spec**~~ ✅ **Done.** Architecture → ARCH-5.
+16. ~~**Audio design spec**~~ ✅ **Done.** Architecture → ARCH-6.
+17. ~~**Localization decision**~~ ✅ **Done.** Architecture → ARCH-7.
+18. ~~**Accessibility spec**~~ ✅ **Done.** Architecture → ARCH-8.
+
+---
+
+## 8. What's Working Well
+
+The gaps above should not overshadow what this GDD does exceptionally well:
+
+- **Consistent vision**: The "spreadsheet simulator" design pillar is maintained across all pages. No page accidentally designs a flight sim.
+- **Roadmap is honest**: Phase 0 is marked "in progress" and every subsequent phase has a concrete done-when condition.
+- **Ship AI design is exceptional**: The soul/module/agent architecture is one of the most detailed and original companion AI designs I've seen in a game design document. The three implementation tiers (deterministic → LLM-assisted → full agent) show practical engineering thinking.
+- **Backend schema is unusually detailed for a GDD**: 56+ tables with field descriptions is ahead of most game prototypes at this stage.
+- **Demo coverage**: 11 interactive demos for a pre-Phase-0 GDD is impressive. Each demo honestly states its limitations.
+- **Agent lifecycle system**: The scheduled_agents model with uniform lifecycle, three scheduling strategies, and kill-switch is production-quality thinking.
+- **Information diffusion model**: The economy's info-asymmetry design is well-thought-through and explicitly tied to gameplay loops.