From 378b00daacac6f0310602ce30884781a48a9a840 Mon Sep 17 00:00:00 2001 From: Nic Date: Wed, 15 Jul 2026 07:34:17 +0200 Subject: [PATCH 1/3] docs(vision): define the civilization frontier Lock the long-horizon relationship between autonomous societies, irreversible history, non-linear travel, and playable campaigns so later milestone specs can grow without turning Sector Zero into a dashboard-first sim. --- docs/ROADMAP.md | 9 +- ...2026-07-15-civilization-frontier-design.md | 610 ++++++++++++++++++ 2 files changed, 618 insertions(+), 1 deletion(-) create mode 100644 docs/superpowers/specs/2026-07-15-civilization-frontier-design.md diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 4718736..d5d13e4 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,6 +1,6 @@ # Sector Zero — Master Roadmap -**Updated 2026-07-13** (Fable planning session — decisions recorded with the user). +**Updated 2026-07-15** (active course unchanged; long-horizon vision links added). This is the single entry point. Every other doc is either DONE, absorbed here, or linked below with its authority noted. @@ -107,6 +107,13 @@ after the sandbox core proves fun. **Spec status: ready in colony spec, sequence economy reference; unbuilt remainders absorbed into M5. - `audits/2026-07-12-full-game-audit.md` — deferred PERF/POLISH backlog (pull from it during any nearby work). +- `superpowers/specs/2026-07-14-living-galaxy-vision-design.md` — approved long-horizon + direction for generations, Great Houses, galactic time, Fold eras, and world + continuity. It does not reorder M1–M6. +- `superpowers/specs/2026-07-15-civilization-frontier-design.md` — approved skeleton for + political authority, autonomous colonies, recontact/exile, bounded governor + decisions, and the eventual non-linear logistics frontier. It decomposes into future + focused specs and does not authorize an immediate star-map rewrite. ## Execution model diff --git a/docs/superpowers/specs/2026-07-15-civilization-frontier-design.md b/docs/superpowers/specs/2026-07-15-civilization-frontier-design.md new file mode 100644 index 0000000..06766fc --- /dev/null +++ b/docs/superpowers/specs/2026-07-15-civilization-frontier-design.md @@ -0,0 +1,610 @@ +# Sector Zero — Civilization Frontier Skeleton + +**Date:** 2026-07-15 +**Status:** APPROVED DIRECTION — records the long-horizon skeleton; exact systems remain +separately specced before implementation +**Planning horizon:** M3–M6 foundations, then post-M6 civilization and frontier eras +**Authority:** Extends `docs/ROADMAP.md` and +`2026-07-14-living-galaxy-vision-design.md`. It does not reorder M1–M6 or authorize an +immediate star-map rewrite. + +## 1. Purpose + +Sector Zero needs one connected structure for the systems discussed after the Living +Galaxy vision: + +- the captain can acquire and lose real political power; +- colonies, towns, Houses, and fleets continue acting while the captain travels; +- absence may produce prosperity, rebellion, forgotten history, extinction, or exile; +- the existing space-battle campaign map eventually becomes a non-linear traversable + galaxy; +- colonies, outposts, relays, allies, and fleets create the logistics needed to push + that frontier; +- battles and multi-mode campaigns remain the player's primary means of changing + history; +- simulated decisions are causal, irreversible, and specific to the save rather than + repeated event cards; +- bounded game intelligence may select from authored outcomes, while language models + remain optional and subordinate to saved world truth. + +This is a skeleton for future focused specs. It defines boundaries, relationships, and +invariants so later work does not accidentally produce a detached grand-strategy game, +an infinite menu simulator, or a generic procedural mission board. + +## 2. Revised north-star relationship — DECIDED + +> **The simulation creates campaigns. Campaigns reshape the simulation.** + +The systemic sandbox and the playable campaign are reciprocal layers: + +1. People, settlements, Houses, fleets, hazards, and enemies create needs and conflict. +2. Significant conflict becomes a campaign, expedition, crisis, or political decision. +3. The captain commits through an existing mode or a bounded command decision. +4. Success, failure, compromise, and absence create durable historical facts. +5. Those facts change the world actors, routes, threats, beliefs, and later campaigns. + +The simulation is the source of context and consequence. Space combat, boarding, +first-person exploration, ground-run, turret combat, negotiation, and multi-phase +missions are how the player enters that context. Neither layer is a disposable wrapper +for the other. + +The current roadmap statement that “the colony/region sim is the game; the campaign is +the on-ramp” remains useful for protecting systemic depth, but it must not be +interpreted to mean that late Sector Zero becomes primarily dashboard management. A +future roadmap refresh should use the reciprocal wording once the implementation order +is ready to change. + +## 3. Political authority and the captain — DECIDED + +### 3.1 Hybrid control + +The captain can gain substantial authority without receiving permanent remote-control +ownership of a society. + +Possible sources include: + +- founding or patronizing a settlement or House; +- election to a town, planetary, House, fleet, or interstellar office; +- appointment, treaty, emergency mandate, inheritance, or acclamation; +- conquest, coercion, coup, or control of strategically necessary infrastructure; +- personal followings, military loyalty, religious significance, or historical myth. + +Each authority grant has a source, scope, jurisdiction, powers, limits, supporters, +opponents, start date, review or succession rules, and legitimacy. “The captain owns +this colony” is not a sufficient long-term political model. + +### 3.2 Layers of agency + +The captain may act through several layers: + +1. **Influence:** suggest, persuade, mediate, gather a bloc, endorse, condemn, or trade + support. +2. **Office:** vote, appoint, negotiate policy, allocate authorized resources, resolve + disputes, and issue decisions within a charter. +3. **Command:** give lawful military, emergency, or executive orders within the granted + mandate. +4. **Coercion:** force a decision through political pressure, emergency powers, + violence, seizure, or conquest. + +The interface must show which layer authorizes an action. Coercion is playable, not +forbidden, but it creates fear, precedent, resistance, defections, rivals, and possible +rebellion. + +### 3.3 The captain's House + +The captain may become a founder, patron, regent, elected leader, military protector, +or sacred ancestor of a House. The House remains an autonomous institution: + +- successors and councils interpret the captain's original purpose; +- members form factions and competing interests; +- cadet branches may split, reconcile, or fight; +- followers may remove the captain from formal leadership while retaining the name; +- a House may honor the captain symbolically while rejecting their current orders. + +This hybrid grants meaningful influence without reducing every House to a player-owned +faction. + +## 4. Delegated rule and bounded governor intelligence — DECIDED + +### 4.1 Departure guidance + +Before leaving, the captain can set: + +- leadership and succession arrangements; +- high-level doctrine and resource priorities; +- construction, defense, diplomacy, exploration, and trade goals; +- reserve thresholds and acceptable risk; +- emergency authority and communication rules; +- protected people, relationships, institutions, or populations; +- preferences, standing orders, and constitutional red lines. + +The three directive strengths are: + +1. **Preference:** guidance a leader weighs against local priorities. +2. **Standing order:** binding within the captain's current legal authority. +3. **Constitutional red line:** a foundational prohibition or protected right. + +No directive is a metaphysical lock. A governor may violate even a red line during a +crisis, coup, ideological break, or act of desperation. The violation is recorded as an +illegal and consequential choice, not silently accepted as compliance. + +### 4.2 Authored choice space, simulated choice + +Colonies never ask an unconstrained model to invent what happens. The system follows a +bounded decision contract: + +1. Detect a situation from saved facts: famine, election, raid, succession, strike, + migration, epidemic, technological dispute, or another authored situation family. +2. Produce only authored actions whose preconditions are currently true. +3. Score those actions from the leader's personality, doctrine, loyalties, ambitions, + fears, corruption, relationships, knowledge, authority, and the captain's orders. +4. Select one action through deterministic game intelligence and a saved seed. +5. Resolve it through authored mechanical outcomes and persist the decision, causes, + participants, consequences, and provenance. +6. Add the significant result to reports, local memory, and the historical chronicle. + +A food crisis might permit rationing, imports, seizure of a House reserve, evacuation, +concealment, price controls, or a request for fleet aid. Which actions exist depends on +the world. Which action is chosen depends on the actual leader and institutions. + +### 4.3 Language-model boundary + +The baseline system does not require a hosted or downloaded language model. Utility +scoring, authored actions, and deterministic resolution must produce a complete game. + +An optional local model may later: + +- summarize the facts considered by a governor; +- draft speeches, petitions, reports, propaganda, and competing interpretations; +- rank an already valid action set for non-authoritative evaluation or player-facing + advice; +- give different actors distinct ways to explain the same saved decision. + +It may not invent an action ID, create or delete a person, transfer resources, declare +a death, change territory, fabricate evidence, or write directly to authoritative +state. Structured output is validated and failure falls back to authored text. The +deterministic game selector alone chooses authoritative mechanical actions; model +ranking cannot alter that result. A future experimental branch may evaluate model +recommendations, but it must not write them into canonical saves unless a later focused +spec replaces this rule with an equally reproducible, crash-safe contract. + +## 5. Absence, neglect, and loss of power — DECIDED + +### 5.1 Drift before rupture + +Control is never lost through one hidden roll. Absence produces a visible causal chain: + +1. delayed decisions, policy reinterpretation, and local improvisation; +2. declining legitimacy, missed obligations, or conflict between captain and leader; +3. organized opposition, election challenges, disobedience, or a succession dispute; +4. removal, secession, coup, rebellion, House fracture, or total loss of authority. + +A competent delegated government may maintain or improve a colony. Neglect is not an +automatic punishment meter; it creates room for other people to govern. + +### 5.2 Total rebellion is a valid world state + +Every colony, House, fleet, and former follower may eventually reject the captain. +Possible causes include tyranny, abandonment, incompatible ideology, propaganda, +religious change, perceived immortality, military failure, technological disaster, or +the belief that the captain is an existential threat. + +The captain may lose offices, property, treasury access, relay access, fleet command, +crew loyalty, legal identity, historical legitimacy, and every major ally. This is not +a conventional game-over. + +### 5.3 Minimum-agency invariant + +The game does not guarantee restoration, ownership, or friendship. It guarantees a +playable next action. + +An exiled captain can attempt to: + +- escape, hide, salvage, steal, trade, or surrender; +- contact isolated loyalists or create a new following; +- ally with outsiders, dissidents, rival Houses, or former enemies; +- negotiate recognition or accept a colony's independence; +- expose evidence, support a claimant, or repair severed infrastructure; +- build a mobile force, insurgency, or new settlement; +- wage reconquest and accept the permanent consequences; +- enter deep stasis if a secure refuge can be obtained. + +The captain may lose the Vanguard or normal fleet access, but the resulting capture, +escape, wreck, or exile path must preserve agency rather than trapping the save in a +non-interactive screen. + +## 6. Irreversible evolution and historical truth — DECIDED + +### 6.1 No return to a prior state + +Things only evolve. Recovery, reconciliation, reconstruction, and restoration are new +historical states, not rollback operations. + +- A rebuilt town contains survivors, successors, memorials, scars, and new ownership. +- A restored House has changed claims, leaders, debts, and internal factions. +- A re-elected captain returns under a new mandate and after a remembered absence. +- A reopened route inherits the war, disaster, or expedition that closed it. + +The save may reconstruct similar capabilities, but it never deletes the causal chain +that led there. + +### 6.2 Objective history and local knowledge + +The simulation retains immutable historical facts needed for causal consistency. Each +society separately holds fallible knowledge of those facts. + +Local knowledge can be: + +- recorded, taught, mythologized, censored, forged, fragmented, or destroyed; +- preserved by a family, archive, monument, ritual, machine, or oral tradition; +- lost through relay failure, archive destruction, regression, war, migration, or + centuries of isolation; +- rejected even when the captain presents evidence. + +Some historical knowledge is permanently unrecoverable to the local society. The +player's chronicle may know that something happened without providing a universally +accepted proof item. Artifacts can become sacred relics, suspected forgeries, weapons, +or evidence that the captain should be feared. + +### 6.3 Causal uniqueness + +The same authored situation family may occur in several places, but it must instantiate +from different causes, actors, beliefs, geography, assets, and history. + +Each significant situation receives a causal signature containing at least: + +- situation family and triggering fact; +- originating actors, relationships, and location; +- era, local culture, authority structure, and known history; +- contested resource, goal, route, person, or institution; +- related prior event or explicit absence of one. + +The presentation system tracks recent motifs and resolved signatures to suppress +accidental near-duplicates. Repetition remains valid when it is itself causal: an +inherited feud, copied doctrine, recurring disaster, ideological movement, or enemy +deliberately repeating a known tactic. + +The requirement is not that two famines can never happen. It is that two famines do not +produce interchangeable people, choices, quests, and consequences. + +## 7. Recontact arcs — DECIDED + +Returning after long absence may reveal a colony that is: + +- loyal but desperate, with only a small group preserving the captain's claim; +- independent and demonstrably better governed; +- divided between restorationists, separatists, opportunists, and neutral civilians; +- hostile because the captain is remembered as a conqueror or existential threat; +- disconnected after a relay, archive, environmental, or technological disaster; +- culturally transformed and uncertain whether the captain ever existed; +- extinct, ruined, evacuated, or continued through descendants elsewhere. + +Recontact generates a bounded campaign from actual history. Possible responses include +diplomacy, elections, archaeology, relay repair, aid, recognition of independence, +support for a faction, evacuation, infiltration, coercion, or war. Reclamation is one +option, never the assumed objective. + +Quest generation must identify why this colony reached its state, who currently has +stakes in it, what evidence and infrastructure survived, and which responses remain +possible. A generic “restore control” chain is insufficient. + +## 8. Captain myth and cultural interpretation — DECIDED DIRECTION + +There is no universal captain-reputation score. Different cultures and actors may +simultaneously understand the same captain as: + +- founder, liberator, patron, or guardian; +- absentee ruler, tyrant, invader, or destroyer; +- deathless wanderer, sleeping king, abandoned god, demon, or prophecy; +- fabricated ancestor, disputed historical figure, or irrelevant footnote. + +Interpretation derives from experienced events, local knowledge, education, +propaganda, religion, generational identity, and current political need. A culture may +change its interpretation without changing the objective facts that inspired it. + +The captain can influence a myth through deeds, institutions, testimony, monuments, +and force, but cannot set a galaxy-wide narrative from a menu. + +## 9. Stasis and galactic time — DECIDED DIRECTION + +### 9.1 Transit stasis + +Transit stasis supports ordinary long-distance travel: + +- it is bound to a destination and route; +- expected captain and galactic elapsed time are previewed; +- route threats and forecast confidence are visible; +- the ship may wake the captain for a significant interruption; +- arrival is expected unless a telegraphed travel failure changes the journey. + +### 9.2 Deep stasis + +Deep stasis is a strategic disappearance: + +- it requires a secure ship, hidden facility, ancient installation, or allied refuge; +- it may last decades, centuries, or millennia; +- the player cannot precisely select the future political state; +- risk, likely duration range, refuge security, and forecast confidence are shown; +- waking produces a full historical catch-up and possible recontact campaign. + +Deep stasis cannot be a universal “skip until the problem goes away” button. Securing +the refuge, surviving discovery, maintaining the system, and accepting irreversibility +are part of the commitment. + +Both forms use the same deterministic interval-advancement foundation described in the +Living Galaxy vision, with different commitment and interruption rules. + +## 10. The star map becomes the galaxy — DECIDED DIRECTION + +### 10.1 Migration from the current campaign map + +The current star map is a fixed arc of eight world nodes with a fixed list of levels. +It should eventually become the actual navigation layer rather than coexist with a +separate long-term galaxy screen. + +- the Vanguard or current vessel has a persistent node or in-transit location; +- W1–W8 remain the authored first corridor and retain their story content; +- later map data is a seeded graph of systems, belts, nebulae, worlds, stations, + anomalies, corridors, and chokepoints; +- important authored locations coexist with discovered and systemic nodes; +- choosing a destination commits time, logistics, and risk rather than selecting a + disconnected level. + +The opening route may remain more constrained while core systems are introduced. The +long-term graph is non-linear and expands through discovery, logistics, politics, and +play rather than a permanent world-number ladder. + +### 10.2 Galaxy intel states + +The M1 region-map pattern repeats at galactic scale: + +1. **Unknown:** no actionable knowledge. +2. **Signal:** a rumor, trace, coordinate fragment, distress call, or anomalous reading. +3. **Charted:** position and partial route information are known. +4. **Reachable:** current logistics and route conditions permit a travel commitment. +5. **Contested:** travel is possible, but a military, political, environmental, or + anomalous threat controls the route or destination. +6. **Secured:** the captain or another actor has established a currently reliable path. +7. **Disrupted or lost:** a formerly useful route has changed and must be reassessed. + +Knowledge and access are separate. Discovering a planet does not make it reachable; +securing a route does not make it permanently safe. + +## 11. Logistics frontier — DECIDED + +### 11.1 Resources enable expeditions, not map purchases + +Players do not spend a resource bar to reveal a planet. Expansion requires three +conditions: + +1. **Knowledge:** a signal or charted destination exists. +2. **Reach:** current ships, fuel, supply, repair, communication, and navigation can + attempt the route. +3. **Commitment:** the captain launches or delegates an expedition and accepts its + travel campaign. + +### 11.2 Sources of frontier reach + +Permanent colonies provide the deepest and most stable reach, but they are not the only +source. + +- **Colonies:** sensors, research, fuel, shipyards, supplies, population, defenses, + diplomacy, and durable communications. +- **Outposts and relays:** narrower sensing, refueling, repair, warning, staging, and + communication coverage. +- **Mobile fleets:** temporary fuel, repair, escort, scouting, and force projection at + higher upkeep and risk. +- **Allies and treaties:** borrowed ports, charts, escorts, markets, and passage rights + that can be revoked. +- **Captured or ancient infrastructure:** powerful but uncertain capabilities requiring + exploration, repair, occupation, or defense. +- **Salvage and hidden depots:** weak but essential paths for fugitives and exiled + captains. + +This prevents total rebellion from becoming a galaxy-exploration softlock while still +making civilization building the strongest expansion engine. + +### 11.3 Building-to-frontier effects + +Later structures may contribute: + +- observatories and sensor arrays: discover or clarify signals; +- navigation archives and research institutions: decode anomalous routes; +- refineries and supply infrastructure: increase practical range and endurance; +- shipyards and fleet yards: repair, refit, and support escorts; +- relay stations: improve communication, reports, forecasts, and interruption warning; +- military installations: challenge blockades and keep routes secured; +- trade and diplomatic institutions: establish access without conquest. + +Exact buildings and balance belong in later milestone specs. + +## 12. Threat and hostile travel — DECIDED DIRECTION + +Threat is not a single enemy-level number. Every node and route may expose several +dimensions: + +- **military:** patrols, fleets, blockades, raiders, fortresses, and bosses; +- **political:** denied passage, sanctions, disputed claims, arrest risk, and hostile + populations; +- **environmental:** storms, radiation, gravity, debris, heat, cold, and supply loss; +- **logistical:** distance, fuel, repair scarcity, crew endurance, and communication + gaps; +- **anomalous:** temporal instability, false signals, mutation, Fold effects, and + uncertain physics. + +The map presents an overall threat band plus known contributors and confidence. Unknown +does not mean randomly lethal; it means the player is shown the limits of current +knowledge. + +Travel responses may include fighting through, scouting, escorting, negotiating, +paying, repairing, researching, waiting, detouring, infiltrating, or abandoning the +attempt. Bosses and major fleets can guard routes or objectives, but not every system +requires a mandatory boss. + +Routes evolve through control and history. A cleared boss remains dead. A successor, +House, syndicate, fleet, disaster, or new culture may later make the corridor dangerous +for a different recorded reason. + +## 13. Travel campaigns and existing game modes — DECIDED + +A significant journey may be a multi-mission campaign rather than one loading screen. +Its phases are selected from actual route threats: + +- vertical shooter or turret defense against fleets and interceptions; +- boarding to capture a relay, rescue a navigator, or disable a blockade; +- first-person investigation, diplomacy, sabotage, or exploration; +- ground-run traversal across a hostile world or damaged installation; +- command decisions about formation, retreat, priorities, and acceptable losses; +- a multi-phase boss or decisive battle at the chokepoint. + +A strategic campaign record needs: + +- stable ID, origin, participants, theater, and cause; +- competing objectives, stakes, allies, enemies, and neutral populations; +- controlled nodes, routes, assets, supply, and time pressure; +- current phase, available interventions, delegated actions, and offscreen plans; +- completed missions, losses, compromises, and resulting historical facts. + +Not every travel commitment becomes a long chain. Routine travel on a secured corridor +may resolve cleanly. Interruptions are significant consequences of actual threat, not +constant random content. + +## 14. Dashboard and communication — DECIDED DIRECTION + +The existing React Colony Planner is the foundation for a later governance dashboard. +It should report and forecast, not provide instantaneous omnipotence. + +Long-horizon surfaces may include: + +- **Overview:** resources, construction, population, threats, and shipments; +- **Government:** captain's offices, authority, mandate, leaders, succession, elections, + policies, directives, and emergency powers; +- **People and Houses:** followers, rivals, blocs, Houses, standing, loyalty, and current + disputes; +- **Campaigns:** wars, expeditions, crises, route threats, fronts, and available + interventions; +- **Communications:** relay path, message delay, order arrival, stale instructions, and + missing contact; +- **Chronicle:** ranked changes since the captain's last reliable report or visit. + +The dashboard distinguishes current knowledge, forecast, delayed report, rumor, and +confirmed historical fact. A remote order may arrive after circumstances change and be +interpreted by local leadership under its granted authority. + +## 15. Data and determinism skeleton — APPROVED ARCHITECTURAL DIRECTION + +Future focused specs should preserve boundaries between: + +- `AuthorityGrant`: who can do what, where, why, and until when; +- `Directive`: preference, standing order, or red line with issuer and scope; +- `GovernanceDecision`: situation, valid candidates, selector, chosen action, and + result; +- `HistoricalFact`: immutable causal event required for world consistency; +- `BeliefRecord`: an actor or culture's fallible knowledge and interpretation; +- `StrategicActor`: House, faction, syndicate, government, fleet, or polity; +- `GalaxyNode` and `Route`: knowledge, location, capabilities, control, threat, and + history; +- `TravelCommitment`: route, clocks, logistics, risks, interruptions, and outcome; +- `Campaign`: theater, participants, objectives, phases, interventions, and history. + +The same saved state, elapsed interval, selector policy, and seed must produce the same +authoritative result. Decisions are committed once and never rerolled on reload. Local +belief may change; objective event provenance does not. + +## 16. Fairness and continuity invariants — DECIDED + +- Every loss of authority follows a visible causal chain. +- Total rebellion and exile preserve at least one playable next action. +- No colony, ally, or permanent base is absolutely required for galaxy continuation. +- Recovery creates a new state and never erases prior consequences. +- Historical knowledge can be lost without corrupting authoritative simulation facts. +- Critical continuation does not depend on one NPC, one archive, or one friendly polity. +- A threat preview states known risk and uncertainty before commitment. +- Secured routes may change, but not through an unexplained offscreen rewrite. +- A governor may violate the captain's orders, and that violation is recorded and + contestable. +- Optional model failure cannot block, corrupt, or reroll world progression. +- Significant campaigns resolve through playable or explicitly delegated actions, not + a hidden instant galaxy roll. + +## 17. Relationship to the active roadmap + +This skeleton influences foundations without pulling the galaxy rewrite forward: + +- **M1 Region:** proves seeded graphs, intel progression, route costs, survey, travel, + POIs, founding, and explicit threat/mode presentation at planetary scale. +- **M2 Look:** improves the assets used when systemic conflicts become playable + missions; it remains an independent art lane. +- **M3 Hubs:** establishes named leaders, Town Hall decisions, relationships, roles, + institutions, and the first expanded Planner information architecture. +- **M4 Decay:** proves telegraphed drift, autonomous local decisions, causal crisis + chains, irreversible scars, and syndicates as world actors. +- **M5 RPG legs:** adds delegation, diplomacy, governance, navigation, engineering, and + command capabilities where consistent with the approved skill trees. +- **M6 Galaxy:** may introduce a data-driven galaxy graph, persistent current location, + multi-colony comparison, routes, coarse distant simulation, and the first campaign + records. It does not need to deliver the complete infinite frontier. +- **Post-M6:** expands frontier reach, generations, Great Houses, recontact, political + loss, exile, deep stasis, cultural myth, and dynamic interstellar campaigns in proven + slices. + +## 18. Future spec decomposition + +Do not implement this document as one monolith. Expected focused designs include: + +1. governance, authority grants, directives, and bounded governor decisions; +2. immutable history, local belief, causal uniqueness, and recontact generation; +3. data-driven galaxy nodes, routes, intel, threat, and frontier reach; +4. travel commitments, transit stasis, interruptions, and deep stasis; +5. strategic campaign records and multi-mode mission generation; +6. expanded Planner/governance/campaign dashboard; +7. optional local-language-model evaluation after the deterministic system is fun. + +Each slice requires its own implementation plan, migration design, deterministic tests, +DevPanel fixtures, and player-facing acceptance criteria. + +## 19. Open-decision ledger + +1. What exact authority types, election terms, succession rules, and jurisdictions ship + in the first governance slice? +2. Which leader traits and utility weights are legible to the player, and which remain + inferred through behavior? +3. What exact causal-signature and motif rules suppress accidental repetition without + suppressing legitimate recurring crises? +4. What conditions permit the captain to lose the Vanguard, and what minimum-agency + escape states replace it? +5. How are deep-stasis duration, discovery risk, equipment failure, and wake conditions + selected and previewed? +6. Which existing W1–W8 transitions become branches first, and when does the authored + corridor stop being linear? +7. What are the exact galaxy threat bands, confidence rules, and route-capability + calculations? +8. Which colony, outpost, relay, fleet, ally, and salvage capabilities contribute to + frontier reach in the first galaxy slice? +9. How much fleet command occurs before a battle, and which role does the captain + personally play during the battle? +10. How are long campaigns compressed, delegated, paused, lost, or resumed without + becoming mission spam? +11. What is the first post-M6 vertical slice that proves one absence-and-recontact arc + feels unique and consequential? + +## 20. Explicit non-goals + +- Do not replace the active W1–W8 campaign or star map during M1 merely because a future + galaxy graph is approved. +- Do not turn Sector Zero into a dashboard-first grand-strategy game. +- Do not require a hosted API, paid service, WebGPU device, or downloaded language model + for authoritative simulation. +- Do not allow an unconstrained model to invent or mutate saved world facts. +- Do not make colonies the only possible source of frontier reach. +- Do not make resources directly purchase planet discovery. +- Do not make every route interruption a random battle or every system end in a boss. +- Do not restore a polity, person, route, House, or reputation by deleting its history. +- Do not guarantee that the captain can reclaim lost authority. +- Do not reduce all cultural interpretations to one captain-reputation number. +- Do not replicate an event package elsewhere with interchangeable names and outcomes. +- Do not make governor disobedience an unexplained random betrayal. +- Do not trigger total rebellion, capture, permanent exile, or loss of the Vanguard + through one hidden offscreen roll. +- Do not simulate the entire galaxy at frame-level or individual daily fidelity. +- Do not allow long-horizon systems to block M1–M5 playable slices. From 2cc08d7f66280519a7e82761474950043b743eee Mon Sep 17 00:00:00 2001 From: Nic Date: Thu, 16 Jul 2026 08:52:08 +0200 Subject: [PATCH 2/3] docs(vision): replace the level ladder with the Atlas Move a minimal continuous-coordinate galaxy substrate ahead of later systemic milestones so hubs, crises, operations, and travel grow from stable locations instead of numeric world gates. Preserve existing playable content as located operations and define a crash-safe, deterministic G0 vertical slice. --- docs/ROADMAP.md | 101 ++- ...2026-07-15-civilization-frontier-design.md | 99 +-- ...26-07-16-continuous-galaxy-atlas-design.md | 655 ++++++++++++++++++ 3 files changed, 778 insertions(+), 77 deletions(-) create mode 100644 docs/superpowers/specs/2026-07-16-continuous-galaxy-atlas-design.md diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index d5d13e4..de7a277 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,16 +1,17 @@ # Sector Zero — Master Roadmap -**Updated 2026-07-15** (active course unchanged; long-horizon vision links added). +**Updated 2026-07-16** (continuous-galaxy reframe and G0 Atlas inserted). This is the single entry point. Every other doc is either DONE, absorbed here, or linked below with its authority noted. ## North star (DECIDED 2026-07-13) -**Systemic sandbox — Dwarf-Fortress-ward.** Depth over breadth: the colony/region sim is -the game; the campaign is the on-ramp and the source of ticks/resources. The 2026-04-20 -colony spec's "Deep Sim future-proofing" (entity IDs everywhere, serializable everything) -is now the point, not an insurance policy. Prefer systems that generate stories over -authored content; authored content exists to seed systems. +**Systemic sandbox — Dwarf-Fortress-ward.** Depth over breadth. The simulation creates +campaigns; playable campaigns reshape the simulation. Colony, region, travel, combat, +exploration, politics, and history are reciprocal layers rather than separate games. +The 2026-04-20 colony spec's "Deep Sim future-proofing" (entity IDs everywhere, +serializable everything) is now the point, not an insurance policy. Prefer systems that +generate stories; authored content seeds places, people, mysteries, and consequences. ## Decisions of record (2026-07-13) @@ -28,7 +29,28 @@ authored content; authored content exists to seed systems. 4. Cargo v1 abstract (physical holds later); travel costs a cycle; first colony gets warnings/protection while learning (from the stakes discussion + OW draft Q1/Q2). -## What is DONE (verified in code, 2026-07-13) +## Decisions of record (2026-07-16 — continuous galaxy) + +1. **Numbered worlds are retired from the new progression model.** Current W1–W8 + missions, bosses, side quests, planet sorties, and special missions remain valuable + authored content, but migrate into named operations attached to physical locations. +2. **The galaxy is continuous projected space, not a node ladder.** The Atlas supports + galaxy, sector, system, and planetary-region zoom. Players may follow known signals + or plot blind expeditions to arbitrary coordinates. +3. **Generate detail through contact.** Seeded spatial cells make coordinates stable; + distant space remains coarse until observation, travel, ownership, or causality + requires deeper simulation. +4. **Progression comes from unified operations.** Story pressure, contracts, battles, + colony needs, exploration, and reliable work use one located operation contract and + can yield material, knowledge, access, power, or historical consequences. +5. **G0 Atlas moves ahead of M3–M5.** The minimal coordinate, signal, operation, route, + and travel substrate lands before hubs and decay build more dependencies on numeric + world IDs. M2 art continues in parallel. +6. **The canonical galaxy starts fresh.** Development-era numbered-progression saves do + not fabricate galactic history. A later importer may preserve harmless Codex, + Bestiary, or cosmetic accomplishments. + +## What is DONE (verified in code, 2026-07-16) | Area | State | |---|---| @@ -42,33 +64,41 @@ authored content; authored content exists to seed systems. | Animated NPC billboards + quartermaster (own sprite + 2-frame walk) | Live (deployed) | | Asset pipeline: Codex image_gen + BiRefNet + style guide — proven on character, poses, wall texture | Operational, $0 | | Ashfall explore zone + Kepler black-box sidequest | Live — these are the POI/quest-reward pattern precursors for M1 | +| **M1 The Region**: Ashfall seeded graph, DOM map, intel, travel, POIs, cargo, survey/found, site economy | Live (PR #9) | +| **M2 first shooter tranche**: Swarm, Bomber, Gunner, Drone regeneration + matched review evidence | Live (PR #12) | ## The course -### M1 — OW-1/2: The Region (leave the base) — NEXT -Per-planet region node graph (Ashfall vertical slice) + region-map screen (React/DOM per -spec §I) + pad-gated travel that **costs a cycle** + `poiDispatcher` with 3 procgen POI -templates (fp ruin / boarding wreck / groundRun canyon — build on `ashfallForwardCamp.ts`'s -explore-zone shape and Kepler's one-time-reward pattern) + POI cargo → colony routing -(missionDelivery.ts already does routing) + **survey → found**: site stats from seed, -founding costs real resources (retire the free 500-metal grant), site stats modulate -production. Spec source: colony spec §F (929-1028) + OW draft §2-3. **Spec status: ready.** +### M1 — OW-1/2: The Region (leave the base) — DONE +Ashfall proves the small-scale pattern the Atlas will extend: a seeded deterministic +graph, progressive intel, React/DOM selection, cycle-cost travel, multi-mode POIs, +cargo routing, surveying, resource-cost founding, and site-modulated economy. ### M2 — The Look (parallel track, asset-lane) DOOM Phase 1-2 regen at scale via the proven pipeline, in visibility order: 13 shooter enemies → 8 bosses → FP/boarding billboards (8-yaw via TRELLIS.2→headless Blender + the engine yaw-selector enabler, spec 2026-07-05 §5.4) → hub interior tilesets/props (feeds -M3) → backgrounds. Style LoRA once ~30 accepted. Runs alongside M1 — different lane, -no file conflicts. **Spec status: ready** (pipeline doc + style guide). - -### M3 — Phase 3: Hubs (places worth entering) +M3) → backgrounds. Style LoRA once ~30 accepted. Runs alongside systemic work — +different lane, no file conflicts. **Spec status: ready** (pipeline doc + style guide). + +### G0 — The Atlas (continuous-galaxy substrate) — NEXT SYSTEMIC SLICE +Fresh canonical galaxy run + persistent vessel coordinate + continuous local-sector map +with galaxy/sector/system/region zoom model + seeded spatial cells + known signals and +blind-coordinate plotting + atlas knowledge/confidence + pure route preview + abstract +supply/time commitment + bounded caused interruption + unified located operations. +Prove the loop with Ashfall, Kepler, one shooter interception, one unresolved signal, +and one deterministic blind discovery. Hybrid UI: Canvas 2D spatial field with +focusable React/DOM controls and route panels. **Spec status: approved design in +`2026-07-16-continuous-galaxy-atlas-design.md`; implementation plan next after review.** + +### M3 — Phase 3: Hubs (places worth entering, now located) Cantina, Marketplace, Town Hall hand-authored interiors + interior NPCs w/ schedules + -faction dialog depth + **bulletin board v1**: procgen quests from the spec's §F Quest +faction dialog depth + **bulletin board v1**: operations from the spec's §F Quest types (typed, unused, waiting in colonyTypes.ts 454-466; cycleProcessor step8 stub exists). Marketplace generalizes `marketContext`. **Spec status: ready** (colony spec Phase 3 + §F). -### M4 — The Decay Arc & Emergent Antagonists (NEEDS SPEC — biggest new design) +### M4 — The Decay Arc & Emergent Antagonists The user's stakes decision, formalized. Colony health drives a staged arc over many cycles: 1. **Crime** (absorbs old 5b: witnesses, bounties, guards, silencing) — reducer stubs exist (`npcKilled`/`witnessed`, step9_bountyDecay). @@ -79,18 +109,21 @@ The user's stakes decision, formalized. Colony health drives a staged arc over m acts on the world: claims POIs, raids other colonies, **intercepts your mission rewards/fleet (turret/escort engine reuse from spec Phase 7b), steals stockpiles**. Counterplay at every stage (guards/barracks, defense missions, raid their POI base). -Absorbs spec Phases 5b + 8 and the interception half of 7b. **Spec status: TO WRITE — -this is the first candidate for a dedicated design doc + plan.** +Absorbs spec Phases 5b + 8 and the interception half of 7b. Syndicates and crises create +located Atlas operations rather than abstract mission-menu entries. **Spec status: +approved in `2026-07-13-decay-arc-emergent-antagonists-design.md`; plan after G0/M3 +foundations are ready.** ### M5 — RPG legs Non-combat XP sources wired (survey/found/trade/quest); Engineering + Piloting skill trees built (specced in 2026-04-05 plans, unbuilt); reward-economy Stage 2 (ships/Hangar) when it earns its place; levels 31-50 later. **Spec status: ready** (2026-04-05 docs). -### M6 — Milestone D (galaxy scale) — horizon -Multi-colony (cap 4) + galaxy map, campaign buffs from colony roster, emergent missions, -Colony Planner React dashboard end-state (spec §I mockup), authored questlines. Sequenced -after the sandbox core proves fun. **Spec status: ready in colony spec, sequence later.** +### M6 — The Living Galaxy expands — horizon +Multi-colony comparison + coarse distant simulation + strategic actors + campaign +records + broader frontier reach + Colony Planner/governance dashboard. The Atlas and +persistent current location already exist from G0; M6 deepens their scale instead of +introducing the first galaxy map. **Spec status: skeleton approved; focused specs later.** ## Doc authority map @@ -109,15 +142,17 @@ after the sandbox core proves fun. **Spec status: ready in colony spec, sequence during any nearby work). - `superpowers/specs/2026-07-14-living-galaxy-vision-design.md` — approved long-horizon direction for generations, Great Houses, galactic time, Fold eras, and world - continuity. It does not reorder M1–M6. + continuity. - `superpowers/specs/2026-07-15-civilization-frontier-design.md` — approved skeleton for political authority, autonomous colonies, recontact/exile, bounded governor - decisions, and the eventual non-linear logistics frontier. It decomposes into future - focused specs and does not authorize an immediate star-map rewrite. + decisions, and the continuing logistics frontier. +- `superpowers/specs/2026-07-16-continuous-galaxy-atlas-design.md` — authoritative + replacement for numbered world progression: continuous coordinates, hierarchical + Atlas, unified operations, travel commitment, simulation fidelity, and G0 scope. ## Execution model -Specs written decision-complete while Fable access lasts (M4's decay-arc spec is the -priority); implementation runs subagent-driven per slice with independent gate -verification (`tsc` + colony/engine/sprites tests + build + prod-build browser smoke) — +Specs are written and independently reviewed before implementation. Implementation runs +subagent-driven per slice with independent gate verification (`tsc` + +colony/engine/sprites tests + build + prod-build browser smoke) — the pattern that shipped everything above. diff --git a/docs/superpowers/specs/2026-07-15-civilization-frontier-design.md b/docs/superpowers/specs/2026-07-15-civilization-frontier-design.md index 06766fc..30e4984 100644 --- a/docs/superpowers/specs/2026-07-15-civilization-frontier-design.md +++ b/docs/superpowers/specs/2026-07-15-civilization-frontier-design.md @@ -3,10 +3,12 @@ **Date:** 2026-07-15 **Status:** APPROVED DIRECTION — records the long-horizon skeleton; exact systems remain separately specced before implementation -**Planning horizon:** M3–M6 foundations, then post-M6 civilization and frontier eras +**Planning horizon:** G0 Atlas foundation, M3–M6 systemic growth, then continuing +civilization and frontier eras **Authority:** Extends `docs/ROADMAP.md` and -`2026-07-14-living-galaxy-vision-design.md`. It does not reorder M1–M6 or authorize an -immediate star-map rewrite. +`2026-07-14-living-galaxy-vision-design.md`. The approved +`2026-07-16-continuous-galaxy-atlas-design.md` supersedes this document's original +navigation model and moves the minimal galaxy substrate forward as G0. ## 1. Purpose @@ -16,8 +18,8 @@ Galaxy vision: - the captain can acquire and lose real political power; - colonies, towns, Houses, and fleets continue acting while the captain travels; - absence may produce prosperity, rebellion, forgotten history, extinction, or exile; -- the existing space-battle campaign map eventually becomes a non-linear traversable - galaxy; +- the existing mission content migrates from a numbered campaign wrapper into a + continuous, coordinate-based traversable galaxy; - colonies, outposts, relays, allies, and fleets create the logistics needed to push that frontier; - battles and multi-mode campaigns remain the player's primary means of changing @@ -334,38 +336,42 @@ are part of the commitment. Both forms use the same deterministic interval-advancement foundation described in the Living Galaxy vision, with different commitment and interruption rules. -## 10. The star map becomes the galaxy — DECIDED DIRECTION +## 10. The star map becomes the galaxy — SUPERSEDED AND REVISED 2026-07-16 ### 10.1 Migration from the current campaign map -The current star map is a fixed arc of eight world nodes with a fixed list of levels. -It should eventually become the actual navigation layer rather than coexist with a -separate long-term galaxy screen. - -- the Vanguard or current vessel has a persistent node or in-transit location; -- W1–W8 remain the authored first corridor and retain their story content; -- later map data is a seeded graph of systems, belts, nebulae, worlds, stations, - anomalies, corridors, and chokepoints; -- important authored locations coexist with discovered and systemic nodes; -- choosing a destination commits time, logistics, and risk rather than selecting a +The current star map is a fixed arc of eight world nodes with fixed level lists. That +wrapper is an implementation artifact and does not remain the structure of the new +galaxy. + +- the Vanguard or current vessel has a persistent coordinate or in-transit position; +- the player navigates continuous projected galactic space through galaxy, sector, + system, and planetary-region zoom levels; +- seeded spatial cells create stable systems, belts, nebulae, worlds, stations, + anomalies, threat volumes, and signals on contact; +- important authored locations coexist with discovered and systemic contacts; +- existing levels, bosses, side quests, planet missions, and special missions survive + as named operations attached to physical locations, not as W1–W8 gates; +- choosing a coordinate commits time, logistics, and risk rather than selecting a disconnected level. -The opening route may remain more constrained while core systems are introduced. The -long-term graph is non-linear and expands through discovery, logistics, politics, and -play rather than a permanent world-number ladder. +A short authored prologue may introduce the Vanguard, crew, apparent alien threat, and +first Tear event. After it, the numbered ladder disappears. The canonical design and G0 +vertical slice are specified in `2026-07-16-continuous-galaxy-atlas-design.md`. ### 10.2 Galaxy intel states -The M1 region-map pattern repeats at galactic scale: +The M1 region-map knowledge pattern repeats at galactic scale: 1. **Unknown:** no actionable knowledge. 2. **Signal:** a rumor, trace, coordinate fragment, distress call, or anomalous reading. 3. **Charted:** position and partial route information are known. -4. **Reachable:** current logistics and route conditions permit a travel commitment. -5. **Contested:** travel is possible, but a military, political, environmental, or - anomalous threat controls the route or destination. -6. **Secured:** the captain or another actor has established a currently reliable path. -7. **Disrupted or lost:** a formerly useful route has changed and must be reassessed. +4. **Visited:** the captain or a trusted source has directly resolved the contact. +5. **Lost contact:** a formerly observed subject has become stale or unreachable enough + that its current condition is unknown. + +Reachable, contested, secured, and disrupted are separate current access assessments. +A charted coordinate can move between them without being forgotten. Knowledge and access are separate. Discovering a planet does not make it reachable; securing a route does not make it permanently safe. @@ -529,21 +535,26 @@ belief may change; objective event provenance does not. ## 17. Relationship to the active roadmap -This skeleton influences foundations without pulling the galaxy rewrite forward: +This skeleton now relies on an early minimal galaxy substrate while keeping the deep +civilization systems incremental: - **M1 Region:** proves seeded graphs, intel progression, route costs, survey, travel, POIs, founding, and explicit threat/mode presentation at planetary scale. - **M2 Look:** improves the assets used when systemic conflicts become playable missions; it remains an independent art lane. +- **G0 Atlas:** introduces continuous coordinates, seeded spatial cells, persistent + vessel location, signals, unified operations, route commitment, and a small local + sector before later systems depend on numbered world IDs. - **M3 Hubs:** establishes named leaders, Town Hall decisions, relationships, roles, - institutions, and the first expanded Planner information architecture. + institutions, and the first expanded Planner information architecture at persistent + galactic locations. - **M4 Decay:** proves telegraphed drift, autonomous local decisions, causal crisis chains, irreversible scars, and syndicates as world actors. - **M5 RPG legs:** adds delegation, diplomacy, governance, navigation, engineering, and command capabilities where consistent with the approved skill trees. -- **M6 Galaxy:** may introduce a data-driven galaxy graph, persistent current location, - multi-colony comparison, routes, coarse distant simulation, and the first campaign - records. It does not need to deliver the complete infinite frontier. +- **M6 Living Galaxy:** expands the atlas into multi-colony comparison, coarse distant + simulation, strategic actors, campaign records, and broader frontier reach. It no + longer introduces the first galaxy map. - **Post-M6:** expands frontier reach, generations, Great Houses, recontact, political loss, exile, deep stasis, cultural myth, and dynamic interstellar campaigns in proven slices. @@ -554,7 +565,8 @@ Do not implement this document as one monolith. Expected focused designs include 1. governance, authority grants, directives, and bounded governor decisions; 2. immutable history, local belief, causal uniqueness, and recontact generation; -3. data-driven galaxy nodes, routes, intel, threat, and frontier reach; +3. continuous galaxy coordinates, atlas intel, threat, and frontier reach — G0 design + now recorded in `2026-07-16-continuous-galaxy-atlas-design.md`; 4. travel commitments, transit stasis, interruptions, and deep stasis; 5. strategic campaign records and multi-mode mission generation; 6. expanded Planner/governance/campaign dashboard; @@ -575,23 +587,21 @@ DevPanel fixtures, and player-facing acceptance criteria. escape states replace it? 5. How are deep-stasis duration, discovery risk, equipment failure, and wake conditions selected and previewed? -6. Which existing W1–W8 transitions become branches first, and when does the authored - corridor stop being linear? -7. What are the exact galaxy threat bands, confidence rules, and route-capability - calculations? -8. Which colony, outpost, relay, fleet, ally, and salvage capabilities contribute to - frontier reach in the first galaxy slice? -9. How much fleet command occurs before a battle, and which role does the captain +6. What are the exact post-G0 threat and route-capability calculations? +7. Which colony, outpost, relay, fleet, ally, and salvage capabilities expand frontier + reach after G0? +8. How much fleet command occurs before a battle, and which role does the captain personally play during the battle? -10. How are long campaigns compressed, delegated, paused, lost, or resumed without - becoming mission spam? -11. What is the first post-M6 vertical slice that proves one absence-and-recontact arc +9. How are long campaigns compressed, delegated, paused, lost, or resumed without + becoming mission spam? +10. What is the first post-M6 vertical slice that proves one absence-and-recontact arc feels unique and consequential? ## 20. Explicit non-goals -- Do not replace the active W1–W8 campaign or star map during M1 merely because a future - galaxy graph is approved. +- Do not expose numbered worlds as the canonical structure of the new galaxy. +- Do not discard proven missions, modes, bosses, or story material merely because their + old progression wrapper is retired; adapt them into located operations. - Do not turn Sector Zero into a dashboard-first grand-strategy game. - Do not require a hosted API, paid service, WebGPU device, or downloaded language model for authoritative simulation. @@ -607,4 +617,5 @@ DevPanel fixtures, and player-facing acceptance criteria. - Do not trigger total rebellion, capture, permanent exile, or loss of the Vanguard through one hidden offscreen roll. - Do not simulate the entire galaxy at frame-level or individual daily fidelity. -- Do not allow long-horizon systems to block M1–M5 playable slices. +- Do not make G0 implement generations, Houses, deep stasis, or the complete living + galaxy before its local exploration loop is fun. diff --git a/docs/superpowers/specs/2026-07-16-continuous-galaxy-atlas-design.md b/docs/superpowers/specs/2026-07-16-continuous-galaxy-atlas-design.md new file mode 100644 index 0000000..1730af0 --- /dev/null +++ b/docs/superpowers/specs/2026-07-16-continuous-galaxy-atlas-design.md @@ -0,0 +1,655 @@ +# Sector Zero — Continuous Galaxy Atlas + +**Date:** 2026-07-16 +**Status:** APPROVED DESIGN — ready for implementation planning after user review +**Milestone:** G0 — The Atlas +**Authority:** Extends `docs/ROADMAP.md` and supersedes the numbered-corridor and seeded +node-graph assumptions in §10–§13 of +`2026-07-15-civilization-frontier-design.md`. The Living Galaxy and Civilization +Frontier documents remain authoritative for long-horizon time, government, history, +and continuity. + +## 1. Purpose + +Sector Zero's current star map is a fixed canvas arc of eight numbered worlds. Levels, +bosses, planets, side quests, and one special mission are unlocked through that ladder. +This structure shipped useful content, but it cannot support the approved game: + +- exploration across a galaxy large enough to outgrow authored bounds; +- a captain with a persistent physical location; +- colonies, fleets, Houses, and enemies acting across distance and generations; +- travel whose time, supply, intelligence, and threats matter; +- missions created by world state and returning consequences to it; +- free discovery rather than choosing the next numbered encounter. + +G0 replaces the progression wrapper, not the playable work. Existing modes, missions, +bosses, side objectives, planets, regions, art, and story material become operations at +physical locations in a continuous Atlas. + +G0 is a small systemic proof. It does not build the entire simulated galaxy. + +## 2. Decisions of record + +1. **Numbered worlds are legacy content identifiers, not the new progression model.** + W1–W8 do not appear as the canonical structure of a new galaxy run. +2. **The Atlas represents continuous projected galactic space.** The player may follow + a known contact or select an arbitrary coordinate. +3. **Navigation is two-dimensional for gameplay.** Depth, elevation, and unusual + topology are route or anomaly properties, not a third free-navigation axis. +4. **Coordinates are deterministic and stable.** The same galaxy seed and coordinate + always identify the same latent space. Viewport, visit order, reload, and frame timing + cannot change generation. +5. **Detail is promoted through contact and causality.** Distant space remains cheap and + coarse until observation, travel, ownership, or an active relationship requires more + detail. +6. **All playable work uses a unified operation contract.** Story missions, side quests, + battles, planet sorties, POIs, contracts, and crises differ by cause and consequence, + not by living in separate progression systems. +7. **Travel commits time and abstract supply.** G0 uses one `supply` pool; fuel, food, + parts, and fleet logistics remain later decompositions. +8. **Threat is multidimensional and knowledge-limited.** The five dimensions are + military, political, environmental, logistical, and anomalous. Each uses `low`, + `moderate`, `high`, `severe`, or `unknown`, plus intelligence confidence of `low`, + `medium`, or `high`. +9. **The canonical galaxy starts fresh.** Existing numbered-progression saves do not + become fabricated history. Optional legacy import may later preserve Codex, + Bestiary, and cosmetic accomplishments only. +10. **M2 art continues in parallel.** G0 is the next systemic milestone before M3 hubs + and M4 decay add more dependencies on numeric world IDs. + +## 3. Player experience + +After a short authored prologue, the captain opens a local Atlas rather than a world +ladder. The prologue establishes the Vanguard, core crew, apparent alien enemy, and +first Tear event. It contains two required operations and one optional lead. After the +player completes it once, later fresh runs may skip it from the start screen. + +The local Atlas initially shows: + +- the Vanguard's current coordinate; +- Ashfall as a charted planetary contact with its existing region layer; +- the Kepler wreck as a known special-operation contact; +- a hostile picket producing a shooter interception; +- one unresolved signal with incomplete intelligence; +- uncharted coordinate space inside current sensor and travel range. + +The player can: + +1. inspect a known contact or select any coordinate; +2. compare distance, elapsed cycles, supply cost, threats, and confidence; +3. commit the expedition; +4. advance world time and resolve any caused interruption; +5. arrive at a persistent contact or mapped empty region; +6. launch a located operation where one exists; +7. receive material, knowledge, access, power, or historical consequences; +8. return to the Atlas and choose again. + +The player is never required to complete an operation merely because they reached its +location. Arrival and mission acceptance are distinct commitments. + +## 4. Spatial model + +### 4.1 Hierarchical Atlas + +The long-term interface supports four conceptual zoom levels: + +1. **Galaxy:** macro regions, civilization scale, long-range expeditions, Fold pressure, + migration, and large strategic changes. +2. **Sector:** continuous coordinates, signals, system contacts, range, borders, threat + volumes, and route plotting. +3. **System:** stars, worlds, stations, fleets, anomalies, orbital positions, and local + operations. +4. **Region:** the existing M1 pattern for landing sites, POIs, surveys, colonies, and + ground travel. + +G0 implements a functional sector view and the transitions into existing system/contact +content and the Ashfall region screen. Galaxy view may be a non-interactive framing +preview in G0. A complete macro simulation is deferred. + +### 4.2 Coordinate representation + +Authoritative positions use integer fixed-point values, not binary floating-point +world coordinates: + +```ts +interface GalaxyCoordinate { + sectorX: number; + sectorY: number; + localX: number; // integer units within sector + localY: number; +} +``` + +G0 defines one bounded local sector. Later sectors extend the same address space without +changing saved coordinates. Screen pixels, pan, and zoom are projections of +`GalaxyCoordinate`; they are never authoritative positions. + +"Arbitrary coordinate" does not mean infinite floating-point rerolls. Pointer and form +input normalize to integer local units, and latent content belongs to a fixed spatial +cell. Repeated plots inside the same cell resolve the same underlying facts and expand +the same mapped envelope. Coordinates must be validated as safe integers before use. + +### 4.3 Seeded spatial cells + +Every galaxy run persists one complete generation identity: + +```ts +interface AtlasGenerationIdentity { + galaxySeed: string; + generationVersion: number; + authoredAnchorRegistryVersion: number; +} +``` + +Pure generation derives a cell seed from: + +- galaxy seed and generation-version identifier; +- sector and cell coordinates; +- authored-anchor registry version. + +The three values above are an indivisible input tuple. A saved run always reloads its +persisted tuple; it never substitutes the application's newest anchor registry version. +If the application cannot load that registry version, it must require an explicit +migration or keep the run unavailable with a recoverable explanation. + +Cells begin as latent deterministic facts. They may contain empty space, a stellar or +planetary contact, a hazard field, a ruin, an anomaly, a signal source, or an authored +anchor. Generated content receives stable IDs derived from seed and coordinate. + +An authored anchor reserves a coordinate before procedural generation. A generator may +not overwrite or relocate it. Adding a future authored anchor requires an explicit +generation-identity migration or a previously reserved coordinate. + +### 4.4 Detail promotion + +The save stores materialized facts, discoveries, player-caused changes, and generation +version. It does not store every possible star. + +Detail promotes through these steps: + +1. **Latent:** seed and coordinate only. +2. **Observed:** signal type, approximate coordinate, and low-confidence traits. +3. **Charted:** stable contact identity and resolved coordinate. +4. **Visited:** local data and operation sources materialize. +5. **Causally active:** people, assets, history, and simulation records persist as + required by actual relationships. + +Promotion never rerolls or contradicts previously saved facts. + +## 5. Atlas knowledge + +Authoritative reality and captain knowledge are separate. + +Each signal, contact, route sample, and threat observation records: + +- subject ID or coordinate envelope; +- knowledge state: `unknown`, `signal`, `charted`, `visited`, or `lost_contact`; +- observed properties and confidence; +- source: sensor, report, rumor, archive, ally, direct visit, or other authored source; +- observation time and optional expiry/staleness rule; +- provenance needed to reproduce or dispute the information. + +`Reachable`, `contested`, and `secured` are current access assessments, not knowledge +states. The same charted coordinate may become unreachable, politically denied, +contested, secured, or disrupted without being forgotten. + +The UI distinguishes: + +- confirmed direct knowledge; +- delayed reports; +- forecasts; +- rumors or disputed claims; +- unknown contributors. + +Unknown does not silently mean lethal. The commitment screen must state that confidence +is insufficient and show the scope of uncertainty. + +## 6. Exploration loop + +### 6.1 Lead-driven exploration + +Signals arise from sensors, rumors, archives, characters, distress calls, Fold echoes, +colonies, and operation outcomes. The captain may improve them through scanning, +research, questioning, triangulation, probes, or direct travel. + +Better intelligence may improve coordinate precision, reveal threats, expose a time +window, identify an issuer, or show that a lead is false or displaced. + +### 6.2 Blind-coordinate exploration + +The player may plot to any coordinate inside current travel capability even without a +signal. Blind expeditions have poor confidence and may reach space without a major +contact. They still produce at least one durable gain: + +- mapped coordinate coverage; +- route and hazard knowledge; +- improved nearby sensor leads; +- a stable negative survey fact; +- salvage or minor material only when causally present. + +Blind travel does not guarantee a theme-park encounter. It also does not erase the +player's time with a completely unrecorded null result. + +### 6.3 Discovery persistence + +A discovered empty location remains mapped empty until a later historical cause changes +it. A found wreck remains the same wreck. A destroyed fleet remains destroyed. New +danger may enter later only through a recorded actor, event, migration, disaster, or +anomaly. + +## 7. Route planning and travel + +### 7.1 Route preview + +The route planner is pure. Given saved world state, starting coordinate, destination, +ship capability, and policy, it returns: + +- stable route-plan ID and ordered legs; +- distance and elapsed world cycles; +- abstract supply cost and projected reserve; +- known threat bands per dimension; +- overall risk presentation and confidence; +- known ports, relays, allies, or repair opportunities; +- forecasted changes likely to occur before return; +- reasons the route is blocked or unsupported. + +G0 offers direct travel and any clearly available authored relay path. Later search may +consider fleets, treaties, infrastructure, and dynamic detours. + +### 7.2 Commitment + +`TravelCommitment` is a journaled state machine with states `committed`, `advancing`, +`interrupted`, `arrived`, `diverted`, and `resolved`. Each record contains its stable +transaction ID, immutable route inputs, next leg index, applied checkpoint IDs, and the +authoritative cost/time snapshot. + +Committing a route: + +1. revalidates the preview against current authoritative state; +2. blocks with an updated explanation if the preview is stale or resources changed; +3. uses one pure reducer transition to atomically create the commitment, deduct supply, + record the elapsed-time obligation, and update the vessel to `in_transit` in the same + returned save value; +4. advances world cycles through the existing cycle-advancement boundary; +5. records every completed leg or interruption under a deterministic checkpoint ID; +6. resolves scheduled route legs and caused interruptions; +7. records arrival or a consequential diverted state. + +Repeating the initial transition with the same transaction ID is a no-op. Resuming from +any later state applies only missing checkpoint IDs. Reloading, double-confirming, or +replaying a partially advanced commitment cannot duplicate cost, skip time, or reroll a +committed interruption. + +### 7.3 Threat + +Every route and destination can contribute: + +- **military:** patrols, raiders, fleets, blockades, fortresses; +- **political:** denied passage, sanctions, warrants, disputed claims; +- **environmental:** storms, radiation, debris, gravity, temperature; +- **logistical:** range, supply, repair scarcity, endurance, communication gaps; +- **anomalous:** temporal instability, false signals, mutation, Fold effects. + +G0 uses qualitative bands and confidence, not precise success percentages. A band is an +assessment of exposure, not a predetermined outcome. + +### 7.4 Interruptions and retreat + +Routine travel through known safe space resolves cleanly. An interruption requires an +actual saved or generated cause along the route. It may launch an existing mode, offer +a command decision, divert the route, impose loss, or allow retreat. + +Failure may damage, strand, capture, or displace the captain, but must leave a playable +next action. G0 implements one military interruption path and one safe arrival path. +Generational stasis, deep stasis, and exile continuations remain later slices. + +## 8. Unified operations + +### 8.1 Operation contract + +Every operation has: + +```ts +interface Operation { + id: string; + source: "story" | "character" | "board" | "systemic" | "exploration" | "reliable_work"; + location: GalaxyCoordinate; + contactId: string | null; + issuerId: string | null; + causeFactIds: string[]; + objective: OperationObjective; + modifiers: OperationModifier[]; + phases: OperationPhase[]; + knownThreat: ThreatAssessment; + costs: OperationCosts; + rewards: OperationRewards; + availability: OperationAvailability; + state: "available" | "accepted" | "active" | "complete" | "failed" | "expired"; +} +``` + +The exact TypeScript decomposition may use smaller referenced records, but these facts +and boundaries must remain explicit. + +An operation has a stable place, cause, participants, constraints, costs, and outcome. +Mode is selected by what physically happens. + +### 8.2 Existing content adapters + +G0 adapts without rewriting gameplay engines: + +- a vertical-shooter level becomes a patrol or interception phase; +- Kepler Black Box becomes a located named wreck operation; +- Ashfall exposes its planet mission, region map, and POIs from its system contact; +- an existing side-quest condition becomes an optional operation modifier; +- existing one-time rewards remain one-time facts; +- mission delivery continues routing cargo through `missionDelivery.ts`. + +Legacy `world` and `level` fields may remain inside adapter payloads until engines are +refactored. An `OperationLaunchContext` authorizes launch from the canonical operation +state. Adapters may not consult legacy `levels`, `currentWorld`, planet-completion, +special-mission unlock, or side-quest unlock fields as availability gates. + +### 8.3 Repeatable work and unique history + +Reliable ports and settlements may offer modest recovery work so poverty or exile does +not soft-lock play. Reward scale derives from actual distance, demand, danger, and +relationships, not world number. + +Named discoveries, deaths, political decisions, boss defeats, evidence, and story +revelations resolve once. Replaying an engine scenario may instantiate new work, but it +cannot repeat or erase the original historical fact. + +## 9. Progression outputs + +Operations and exploration may advance five positions: + +1. **Material:** supply, credits, cargo, repairs, salvage, rare components. +2. **Knowledge:** coordinates, threat confidence, history, evidence, navigation data. +3. **Access:** safe passage, allies, relays, ports, political permission, secured space. +4. **Power:** XP, crew growth, ship capability, institutions, fleets, authority. +5. **History:** consequences, relationships, claims, enemies, obligations, cultural + interpretation. + +G0 implements material, knowledge, and one access effect. Existing pilot XP and standing +may pass through adapters where already supported. Deep political and generational +outputs remain later. + +Resources never directly purchase planet revelation. Knowledge identifies a +possibility, capability makes travel possible, and commitment attempts it. + +## 10. Living simulation fidelity + +The Atlas must scale without pretending to run every person at frame fidelity: + +1. **Active scene:** current gameplay engine. +2. **Current theater:** local vessels, operations, tactical clocks, and nearby actors. +3. **Connected actors:** colonies, fleets, leaders, relationships, directives, and + active crises processed at event boundaries. +4. **Distant known:** coarse population, power, economy, war, migration, and major event + summaries. +5. **Latent space:** seed, coordinates, and macro fields only. + +Relevance may outrank distance. A distant colony in civil war can receive more detail +than a quiet neighboring system. + +G0 implements active scene, current theater, and latent/observed Atlas facts. It must +define serializable seams for later layers but does not simulate generations or distant +civilizations. + +## 11. G0 vertical slice + +### 11.1 Included content + +One deterministic local sector contains: + +- one Vanguard starting coordinate; +- Ashfall as one authored planet/system contact; +- Kepler as one authored wreck contact; +- one authored hostile-picket contact; +- one unresolved signal; +- one deterministic blind-coordinate result; +- one optional relay route if the chosen starting layout can support it clearly. + +The slice reuses at least three playable contexts: shooter interception, Kepler +first-person retrieval, and Ashfall region/POI or planet play. + +### 11.2 Included systems + +- fresh galaxy-run creation and explicit entry; +- stable galaxy seed and generation version; +- persistent current or in-transit vessel location; +- sector pan, zoom, pointer, touch, and keyboard navigation; +- focusable contact list and coordinate selection outside the canvas; +- known contact and blind-coordinate selection; +- signal/contact intel and confidence; +- pure route preview; +- one abstract supply pool; +- one-to-three-cycle local travel commitments; +- one safe travel resolution and one caused military interruption; +- operation adapters for the selected existing content; +- material, knowledge, and one route/access consequence; +- SaveData defaults, field-by-field migration, and DevPanel fixtures. + +### 11.3 Explicitly deferred + +- whole-galaxy generation and a fully interactive galaxy-scale view; +- authored prologue implementation, completion tracking, and skip flow; G0 begins from + a deterministic post-prologue fixture while preserving the approved opening design; +- three-dimensional free navigation; +- generations, Great Houses, religions, cultural captain myths, and succession; +- distant political simulation and autonomous governors; +- fleet organizations and mass battles; +- fuel/food/parts decomposition; +- transit-stasis subjective-time simulation and deep stasis; +- procedural civilizations; +- complete conversion of every legacy level, boss, planet, and quest; +- final art pass for the Atlas. + +## 12. Architecture + +### 12.1 Pure modules + +Recommended boundaries: + +- `engine/galaxy/coordinates.ts`: fixed-point coordinate helpers and projection-neutral + distance; +- `engine/galaxy/atlas.ts`: cell seeds, authored anchors, materialization, knowledge; +- `engine/galaxy/routePlanner.ts`: pure route preview and block reasons; +- `engine/galaxy/travelResolver.ts`: idempotent commitments and travel outcomes; +- `engine/operations/operationCatalog.ts`: located operation definitions and legacy + adapters; +- `engine/operations/operationOutcome.ts`: normalized rewards and historical facts. + +Names may change during planning, but coordinate generation, route calculation, travel +mutation, operation definition, and UI must remain separate responsibilities. + +No pure module touches `window`, `document`, Canvas, WebGL, wall-clock time, or +unseeded randomness. + +### 12.2 UI + +`GalaxyAtlasScreen` is a hybrid React surface: + +- Canvas 2D renders the spatial field, stars, contacts, threat volumes, routes, and + large-scale pan/zoom affordances; +- React/DOM renders the contact list, filters, selected-coordinate details, route + comparison, commitment controls, warnings, and accessible status; +- Canvas is initialized only inside a component effect or event after mount; +- every selectable contact has a focusable DOM equivalent; +- arbitrary-coordinate selection has keyboard and form controls, not pointer-only input; +- selection state is shared, so Canvas click, touch, keyboard focus, and DOM activation + all update the same target. + +The current gameplay canvas remains the mission renderer. The Atlas screen may own its +own mounted Canvas 2D element while gameplay is inactive. + +### 12.3 Save boundary + +The existing save adds a nullable, field-migrated `galaxyRun` domain and an explicit +active-experience selector. Old saves migrate `galaxyRun` to `null` with `??` fallback. +Legacy top-level progression remains preserved for the legacy experience but is not +authoritative while a galaxy run is active. + +`GalaxyRunState` owns its own progression namespace: supply, resources, pilot state, +operation states, Atlas knowledge, current location, contacts, and historical facts. +Starting the canonical galaxy constructs that entire namespace from one explicit +factory using only generation identity and an allowlisted import payload. It never +reads legacy resources, upgrades, world unlocks, completion arrays, colonies, factions, +or story decisions. + +Existing engines receive a transient compatibility projection created from +`GalaxyRunState`, not the preserved legacy progression fields. After play, the operation +adapter merges only allowlisted result deltas back into `GalaxyRunState`. It may not +write legacy history while the galaxy experience is active. + +Any future legacy import is opt-in, allowlisted, and copy-only. It may include Codex, +Bestiary, and cosmetics. It may not import resources, upgrades, world unlocks, mission +completion, colony state, factions, or story decisions. + +## 13. Data flow + +### 13.1 Atlas selection + +1. UI requests visible cell facts from the pure Atlas using seed, version, and viewport + cell coordinates. +2. Atlas combines authored anchors, saved materializations, and latent generation. +3. UI projects returned coordinates to pixels. +4. Selecting Canvas or DOM content produces the same `AtlasTarget`. +5. Route planner previews from saved vessel state without mutation. + +### 13.2 Travel + +1. Player confirms a displayed route plan. +2. Resolver re-plans from current state and compares the plan identity and inputs. +3. If valid, one reducer transition journals the transaction, supply deduction, + elapsed-time obligation, and in-transit location atomically. +4. Later resolver transitions advance only unapplied leg checkpoint IDs. +5. A caused interruption launches an operation phase; otherwise arrival materializes + and records the destination knowledge. +6. Completion or retreat resolves through normalized operation outcome handling. + +### 13.3 Operation outcome + +1. Existing engine reports its typed result. +2. Adapter translates it into material, knowledge, access, XP/standing, and fact deltas. +3. Validator rejects unknown IDs or impossible duplicate unique rewards. +4. Reducers commit the outcome once. +5. Atlas knowledge, world history, and available operations refresh from saved truth. + +## 14. Error and continuity handling + +- **Stale preview:** do not commit; show exactly which cost, route, threat, or capability + changed and present the refreshed preview. +- **Insufficient supply:** block before mutation and keep the selected target. +- **Missing authored adapter:** keep the contact visible, mark the operation unavailable, + and return safely to the Atlas; never crash the save. +- **Generation mismatch:** saved materialized facts outrank regenerated latent output. + Unknown future versions require an explicit migration, not silent reroll. +- **Interrupted reload:** resume the saved `TravelCommitment` by transaction ID. +- **Double confirmation or partial travel replay:** the commitment reducer and leg + checkpoint IDs no-op already applied work. +- **Duplicate completion:** unique rewards and facts no-op with a recorded validation + result; costs and rewards are never applied twice. +- **Unknown threat:** communicate uncertainty and allow the player to reconsider; do not + substitute an undisclosed fatal roll. +- **No major blind discovery:** persist mapped coverage and a negative survey fact. +- **Unreachable destination:** explain range, supply, political, or route cause and show + currently known ways to improve reach. +- **Legacy save:** offer a clearly labeled new galaxy run; do not auto-delete the old + save or silently blend histories. +- **Compatibility projection:** reject any adapter result outside its allowlisted galaxy + outcome fields rather than leaking it into preserved legacy progression. + +## 15. Acceptance criteria + +### 15.1 Determinism + +- Same complete generation identity and coordinate produce identical latent + cell/contact facts across reload and visit order. +- Updating the application's default anchor registry cannot change an unmigrated saved + run's latent results. +- Repeated blind plots inside one spatial cell cannot farm new procedural contacts. +- Different seeds produce meaningfully different uncharted results without moving + authored anchors. +- Pan, zoom, display size, FPS, and input method cannot affect generation. +- A materialized discovery survives generator changes and reload. + +### 15.2 Navigation and travel + +- Player can select every authored contact through pointer, touch, keyboard, and DOM. +- Player can enter and select an arbitrary in-range coordinate without a signal. +- Keyboard arrows pan, keyboard zoom controls change scale, and focus remains on a + meaningful DOM control after either action. +- Touch drag and pinch, or equivalently labeled touch controls, pan and zoom without + requiring mouse emulation or accidentally committing a selection. +- A player can select a contact, inspect the full route preview, commit travel, and + reach arrival using focusable DOM controls without interacting with Canvas. +- Route preview names distance, cycles, supply, five threat dimensions, confidence, and + every block reason. +- Committing deducts supply and advances time exactly once. +- Double-confirming one transaction deducts and journals it once. +- Simulated reload from every commitment state resumes only unapplied checkpoints and + never rerolls or duplicates cost, time, interruption, or arrival. +- Safe route arrives; hostile route launches the caused shooter interruption. + +### 15.3 Operations and progression + +- Ashfall, Kepler, and hostile picket launch from physical Atlas contacts. +- Ashfall, Kepler, and hostile picket launch from a fresh galaxy run while the engine + compatibility projection's legacy `levels`, planet completion, special-mission + unlocks, and side-quest unlocks are empty or locked, regardless of preserved legacy + save values. +- At least one existing side-quest condition functions as an operation modifier without + depending on its old world-level availability gate. +- POI/planet cargo still routes through `missionDelivery.ts`. +- Unique Kepler story reward remains one-time. +- One operation produces material, one produces knowledge, and one changes an access or + route fact. +- No G0 UI presents W1–W8 as progression. + +### 15.4 Save, static export, and regression + +- `galaxyRun` has a field-by-field migration default and migration tests. +- A legacy save remains readable and can start a clean galaxy run explicitly. +- With import disabled, two legacy saves containing different resources, upgrades, + unlocks, completions, colonies, factions, and story choices produce identical galaxy + defaults for the same generation identity. +- Galaxy operation play mutates only the galaxy namespace; preserved legacy progression + is byte-for-byte unchanged. +- New modules are safe during `next build` evaluation with no browser global access at + module scope. +- Existing gameplay render output remains unchanged until launched through an adapter. +- DevPanel provides fixed seeds for starting Atlas, known route, hostile route, blind + discovery, insufficient supply, and in-transit reload. +- TypeScript, colony tests, engine tests, sprite tests, static build, DevPanel build, and + browser playtests pass before merge. + +## 16. Roadmap effect + +- **M1** is complete and proves the region-scale knowledge/travel pattern. +- **M2** continues as an independent art lane. +- **G0** becomes the next systemic implementation slice. +- **M3** hubs attach operations, people, markets, and government to Atlas contacts. +- **M4** decay emits located crises, raiders, syndicates, and interventions. +- **M5** navigation, engineering, command, and diplomacy gain real route contexts. +- **M6** expands coarse distant simulation, multi-colony comparison, strategic actors, + campaigns, and frontier reach rather than introducing the first galaxy map. + +## 17. Non-goals and guardrails + +- Do not recreate W1–W8 with different labels or eight sector gates. +- Do not discard proven content solely because its wrapper changes. +- Do not require a colony to continue exploring; fleets, allies, relays, salvage, and + hidden infrastructure remain future alternate reach sources. +- Do not make blind travel secretly guarantee a bespoke encounter. +- Do not make arbitrary coordinates pointer-only. +- Do not render every possible star as a DOM node. +- Do not use unseeded `Math.random`, `Date.now`, or module-scope browser objects. +- Do not charge a route before revalidation or resolve a commitment twice. +- Do not expose precise threat probabilities when the captain has qualitative or stale + intelligence. +- Do not turn every journey into a battle. +- Do not implement generations, Houses, deep stasis, or full galactic politics in G0. +- Do not translate legacy level completion into invented canonical history. +- Do not make the Atlas a dashboard replacement for playable operations. From 3ed8c1f3813cda4b68a6ce2892b654822da2c929 Mon Sep 17 00:00:00 2001 From: Nic Date: Thu, 16 Jul 2026 09:49:30 +0200 Subject: [PATCH 3/3] docs(plan): map G0 Atlas implementation --- .../2026-07-16-g0-continuous-galaxy-atlas.md | 1071 +++++++++++++++++ 1 file changed, 1071 insertions(+) create mode 100644 docs/superpowers/plans/2026-07-16-g0-continuous-galaxy-atlas.md diff --git a/docs/superpowers/plans/2026-07-16-g0-continuous-galaxy-atlas.md b/docs/superpowers/plans/2026-07-16-g0-continuous-galaxy-atlas.md new file mode 100644 index 0000000..5509706 --- /dev/null +++ b/docs/superpowers/plans/2026-07-16-g0-continuous-galaxy-atlas.md @@ -0,0 +1,1071 @@ +# G0 Continuous Galaxy Atlas Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Ship a fresh, deterministic G0 galaxy run in which the captain can explore a continuous local sector, commit idempotent supply-and-time travel, and launch the existing hostile-picket shooter, Kepler, and Ashfall content as located operations without changing preserved legacy progression. + +**Architecture:** Add a nullable `GalaxyRunState` namespace beside the legacy save, then keep coordinates, Atlas generation, route planning, travel mutation, operation adapters, and UI projection in separate pure modules. Existing engines receive a transient allowlisted `SaveData` projection built only from `GalaxyRunState`; their results merge back only into the galaxy namespace. `GalaxyAtlasScreen` owns a mount-time Canvas 2D field plus equivalent focusable DOM controls, while `Game.tsx` remains a thin surface/engine orchestrator. + +**Tech Stack:** Next.js 15 static export, React 19, strict TypeScript, Canvas 2D, existing shooter/first-person/planet/colony engines, Node `tsx --test` flat test files. + +--- + +## Authority and fixed decisions + +- Implement only G0 from `docs/superpowers/specs/2026-07-16-continuous-galaxy-atlas-design.md`; generations, Houses, deep stasis, autonomous politics, full galaxy simulation, and final Atlas art remain deferred. +- Preserve the existing W1-W8 campaign and its save fields as a selectable legacy experience. No G0 screen presents W1-W8 as canonical progression. +- A fresh galaxy run never reads legacy credits, XP, upgrades, unlocks, completions, colonies, factions, or story state. `activeExperience` is a selector, not a migration of history. +- The deterministic post-prologue G0 factory owns a new Ashfall Primary at the existing `ashfall-forward-camp` anchor. This is a fresh galaxy asset, not an import; it is required to expose the already-approved M1 region/POI loop and route cargo through `missionDelivery.ts`. +- Travel uses one abstract supply pool. The preview is pure; the saved commitment is journaled and idempotent. Each leg advances its promised cycle once through the existing colony cycle boundary. +- Existing gameplay constructors and framebuffer behavior remain unchanged. Launch adapters provide context; renderers and engines do not learn Atlas rules. +- No module touches `window`, `document`, Canvas, WebGL, wall-clock time, or unseeded randomness at module scope. +- No new raster assets or sprite registrations are part of G0. +- Execute runtime work only after this docs branch lands on `main`, on a fresh + `feat/g0-galaxy-atlas` branch in its own worktree. Do not implement G0 on the docs PR + branch and do not merge the implementation PR without explicit approval. + +## File structure + +### New engine domain + +| File | Responsibility | +|---|---| +| `game/app/components/engine/galaxy/galaxyTypes.ts` | Serializable galaxy, Atlas, knowledge, threat, route, vessel, and travel contracts. | +| `game/app/components/engine/galaxy/coordinates.ts` | Safe-integer validation, cell addressing, stable IDs, distance, and projection-neutral coordinate helpers. | +| `game/app/components/engine/galaxy/authoredAnchors.ts` | Versioned G0 anchor registry: Vanguard, Ashfall, Kepler, hostile picket, and unresolved signal. | +| `game/app/components/engine/galaxy/atlas.ts` | Pure cell seeding, latent facts, authored reservation, materialization, knowledge promotion, and blind survey results. | +| `game/app/components/engine/galaxy/galaxyRun.ts` | Fresh-run factory, field-by-field nested migration, experience selection, and deterministic transaction ordinals. | +| `game/app/components/engine/galaxy/galaxyProjection.ts` | Transient legacy-engine projection, allowlisted merge, and galaxy-only world-cycle advancement. | +| `game/app/components/engine/galaxy/routePlanner.ts` | Pure direct/relay route preview, supply/time cost, threat bands, confidence, and block reasons. | +| `game/app/components/engine/galaxy/travelResolver.ts` | Journaled commitment reducer, checkpoint replay protection, arrival/diversion/interruption, and resume. | +| `game/app/components/engine/galaxy/experienceFlow.ts` | Pure begin/resume, surface routing, and legacy-snapshot helpers used by `Game.tsx`. | + +### New operation domain + +| File | Responsibility | +|---|---| +| `game/app/components/engine/operations/operationTypes.ts` | Located operation, launch payload, modifier, typed engine result, normalized outcome, and validation contracts. | +| `game/app/components/engine/operations/operationCatalog.ts` | G0 operation definitions and availability from galaxy truth only. | +| `game/app/components/engine/operations/operationAdapters.ts` | Convert an authorized operation into an existing engine state; wrap Ashfall region/POI calls through the projection boundary. | +| `game/app/components/engine/operations/operationOutcome.ts` | Idempotently fold material, knowledge, access, pilot, cargo, and unique history facts into `GalaxyRunState`. | + +### New React surface + +| File | Responsibility | +|---|---| +| `game/app/components/galaxy/atlasViewport.ts` | Pure pan/zoom, world-to-screen projection, hit selection, coordinate normalization, and keyboard/touch control math. | +| `game/app/components/galaxy/GalaxyAtlasScreen.tsx` | Canvas field plus DOM contact list, coordinate form, route panel, warnings, commitment, operation, and Ashfall-region controls. | +| `game/app/components/galaxy/GalaxyExperienceGate.tsx` | Explicit `BEGIN/CONTINUE GALAXY` and `LEGACY CAMPAIGN` entry controls. | +| `game/app/components/galaxy/devFixtures.ts` | Fixed Atlas, safe route, hostile route, blind result, insufficient supply, and interrupted-reload fixtures. | +| `game/app/components/galaxy/index.ts` | Public UI exports only. | + +### Existing integration files + +| File | Change | +|---|---| +| `game/app/components/engine/types.ts:1066` | Add `ExperienceMode`, `activeExperience`, and nullable `galaxyRun`; do not move legacy fields. | +| `game/app/components/engine/save.ts:36-129` | Fresh defaults and explicit `??` migration calls for the two new fields. | +| `game/app/components/Game.tsx:88-2241` | Wire the experience gate, Atlas surface, travel/operation callbacks, galaxy completion path, and projected Ashfall region flow. | +| `game/app/components/DevPanel.tsx:1-260` | Add fixed `GALAXY SEEDS` buttons. | +| `game/app/components/colony/shared/missionDelivery.ts` | No behavior rewrite; call its existing explicit destination path from the galaxy adapter. | +| `game/tests/colony/fixtures.ts` and direct `SaveData` literals | Add `activeExperience: "legacy"` and `galaxyRun: null`. | + +## Core contracts to implement + +Use these shapes as the serialization boundary. Smaller helper types may be added, but fields must not be removed or replaced by legacy aliases. + +```ts +export type ExperienceMode = "legacy" | "galaxy"; +export type KnowledgeState = "unknown" | "signal" | "charted" | "visited" | "lost_contact"; +export type AtlasViewLevel = "galaxy" | "sector" | "system" | "region"; +export type ThreatDimension = "military" | "political" | "environmental" | "logistical" | "anomalous"; +export type ThreatBand = "low" | "moderate" | "high" | "severe" | "unknown"; + +export interface GalaxyCoordinate { + sectorX: number; + sectorY: number; + localX: number; + localY: number; +} + +export interface AtlasGenerationIdentity { + galaxySeed: string; + generationVersion: number; + authoredAnchorRegistryVersion: number; +} + +export type KnowledgeSource = "sensor" | "report" | "rumor" | "archive" | "ally" | "direct_visit" | "authored"; +export type KnowledgeConfidence = "low" | "medium" | "high"; + +export interface AtlasCellFact { + id: string; + cellKey: string; + coordinate: GalaxyCoordinate; + kind: "empty" | "stellar_contact" | "hazard" | "ruin" | "anomaly" | "signal"; + contactId: string | null; + stableSeed: number; + authored: boolean; +} + +export interface AtlasKnowledgeRecord { + id: string; + subjectId: string; + state: KnowledgeState; + observedProperties: Record; + confidence: KnowledgeConfidence; + source: KnowledgeSource; + observedCycle: number; + expiresCycle: number | null; +} + +export interface AccessFact { + id: string; + subjectId: string; + assessment: "reachable" | "contested" | "secured" | "denied" | "disrupted"; + causeFactIds: string[]; + cycle: number; +} + +export interface ThreatObservation { + id: string; + subjectId: string; + dimension: ThreatDimension; + band: ThreatBand; + confidence: KnowledgeConfidence; + source: KnowledgeSource; + observedCycle: number; +} + +export interface RouteLeg { + id: string; + from: GalaxyCoordinate; + to: GalaxyCoordinate; + distanceUnits: number; + cycles: number; + supplyCost: number; + interruptionCauseId: string | null; +} + +export interface GalaxyResources { + supply: number; + credits: number; + materials: MaterialId[]; +} + +export interface GalaxyShipState { + upgrades: ShipUpgrades; + unlockedEnhancements: EnhancementId[]; + equippedWeaponType: WeaponType; + consumableInventory: Partial>; + equippedConsumables: ConsumableId[]; +} + +export interface GalaxyPilotState { + xp: number; + level: number; + skillPoints: number; + allocatedSkills: SkillNodeId[]; + bestiary: Partial>; +} + +export interface GalaxyVesselState { + status: "stationary" | "in_transit" | "stranded"; + coordinate: GalaxyCoordinate; + contactId: string | null; + transitTransactionId: string | null; +} + +export interface GalaxyAtlasState { + materializedFacts: Record; + knowledge: Record; + mappedCellKeys: string[]; + accessFacts: AccessFact[]; + threatObservations: ThreatObservation[]; +} + +export interface GalaxyOperationRecord { + state: "available" | "accepted" | "active" | "complete" | "failed" | "expired"; + acceptedCycle: number | null; + resolvedCycle: number | null; + completionIds: string[]; +} + +export interface GalaxyCodexState { + unlocked: string[]; + viewed: string[]; +} + +export interface HistoricalFact { + id: string; + kind: string; + subjectId: string; + cycle: number; + causeFactIds: string[]; +} + +export interface TravelCommitment { + transactionId: string; + state: "committed" | "advancing" | "interrupted" | "arrived" | "diverted" | "resolved"; + routePlanId: string; + origin: GalaxyCoordinate; + destination: GalaxyCoordinate; + targetId: string | null; + legs: RouteLeg[]; + nextLegIndex: number; + appliedCheckpointIds: string[]; + supplyCost: number; + elapsedCycles: number; + interruptionOperationId: string | null; +} + +export interface GalaxyRunState { + identity: AtlasGenerationIdentity; + worldCycle: number; + nextTransactionOrdinal: number; + resources: GalaxyResources; + ship: GalaxyShipState; + pilot: GalaxyPilotState; + codex: GalaxyCodexState; + storyItems: StoryItemId[]; + vessel: GalaxyVesselState; + atlas: GalaxyAtlasState; + operations: Record; + activeTravel: TravelCommitment | null; + colonies: ColonyState[]; + planets: PlanetState[]; + factionStandings: FactionStanding[]; + historyFacts: HistoricalFact[]; + appliedOutcomeIds: string[]; +} +``` + +All records above are serializable and contain no runtime object handles. Story items live only in `GalaxyRunState.storyItems`, Codex entries only +in `GalaxyRunState.codex`, Bestiary entries only in `GalaxyRunState.pilot.bestiary`, and +access/threat facts only in `GalaxyRunState.atlas`. Projection code may copy them into a +transient engine-shaped save but may never read or write their legacy counterparts. + +The G0 constants live in data modules, not React: + +```ts +export const G0_GENERATION_IDENTITY = { + galaxySeed: "sector-zero-g0", + generationVersion: 1, + authoredAnchorRegistryVersion: 1, +} as const; + +export const G0_SECTOR_BOUNDS = { min: 0, max: 4095, cellSize: 256 } as const; +``` + +## G0 content and economy table + +These are version-1 data constants. Changing a coordinate, formula, anchor, cause, +operation payload, cost, or reward requires a generation/content version migration and +updated determinism tests; it is not an implementation-time balance choice. + +### Anchors and starting capability + +| ID | Coordinate `(sectorX, sectorY, localX, localY)` | Initial knowledge | Threat summary | Cause fact | +|---|---|---|---|---| +| `contact:vanguard` | `(0, 0, 512, 512)` | `visited`, high confidence | all dimensions `low` | `fact:vanguard-operational` | +| `contact:ashfall` | `(0, 0, 1024, 512)` | `charted`, high confidence | environmental `moderate`; others `low` | `fact:ashfall-distress` | +| `contact:hostile-picket` | `(0, 0, 1280, 1024)` | `charted`, medium confidence | military `high`, logistical `moderate`; others `low` | `fact:picket-patrol-active` | +| `contact:kepler` | `(0, 0, 2048, 1024)` | `charted`, medium confidence | environmental `moderate`, anomalous `moderate`; others `low` | `fact:kepler-recorder-signal` | +| `signal:unresolved-g0` | `(0, 0, 2816, 1792)` | `signal`, low confidence | anomalous `moderate`; every other dimension `unknown` | `fact:unresolved-signal` | + +`BLIND_FIXTURE_COORDINATE` is `(0, 0, 1792, 1792)` and is not an authored anchor. +Registry version 1 contains no relay ID or coordinate reservation. Adding one later +requires an explicit authored-registry migration; G0 route planning considers direct +legs only. + +The fresh run starts at Vanguard with: + +```ts +export const G0_STARTING_SUPPLY = 12; +export const G0_MAX_LEG_DISTANCE = 2048; +export const G0_CYCLE_DISTANCE = 768; +export const G0_SUPPLY_DISTANCE = 384; +``` + +Ship upgrades are `DEFAULT_UPGRADES`; enhancements, consumables, materials, credits, +story items, Codex, Bestiary, and legacy completions start empty. Route math is exact: + +The galaxy-owned bootstrap colony is exactly `id: "galaxy:ashfall-primary"`, +`name: "Ashfall Primary"`, at `ashfall-forward-camp`, with +`{ food: 0, water: 0, metal: 0, credits: 0 }`; its planet/region seed is 4107 and its +faction standings come from `defaultFactionStandings()`. No legacy colony is copied. + +```ts +distanceUnits = Math.round(Math.hypot(deltaX, deltaY)); +elapsedCycles = Math.max(1, Math.min(3, Math.ceil(distanceUnits / G0_CYCLE_DISTANCE))); +supplyCost = Math.ceil(distanceUnits / G0_SUPPLY_DISTANCE); +``` + +G0 version 1 plans direct legs only. A destination is blocked when its direct leg is +over `G0_MAX_LEG_DISTANCE` or current supply is below `supplyCost`. Therefore Vanguard +to Ashfall is 512 units / 1 cycle / 2 supply; Vanguard to hostile picket is 923 / 2 / 3; +Vanguard to Kepler is 1,619 / 3 / 5; the blind fixture is 1,810 / 3 / 5; and the +unresolved signal is initially out of range. Tests assert these exact values. + +### Operations + +| Operation | Existing engine payload | Operation cost | Success reward | Failure/retreat | +|---|---|---:|---|---| +| `op:hostile-picket` | `createGameState(1, 1, ...)` | 0 supply (travel already paid) | `+2 supply`, `+100 XP`, `access:picket-cleared`, knowledge/history; Quick Draw adds `+200 credits` only when met; resolves the interruption as `cleared` | no reward/access; `failed` strands at the picket with emergency retreat available; `retreated` returns to origin | +| `op:kepler-black-box` | `createSpecialMissionGameState("kepler-black-box", ...)` | 0 | `+200 credits`, `+100 XP`, one black-box story item/fact, upgraded Kepler knowledge | no unique reward; travel remains resolved at Kepler | +| `op:ashfall-sortie` | `createPlanetGameState("ashfall", ...)` | 0 | `+75 XP`, upgraded Ashfall knowledge, existing desert mission payload delivered to galaxy-owned Ashfall Primary through `mission_delivery` | no reward; travel remains resolved at Ashfall | + +The hostile picket also carries Quick Draw (`q-reyes-1-1`) as a 3,600-frame optional +time-attack modifier with its existing 200-credit reward. Its old `unlockAfter` and +`targetLevel` are ignored as gates; its condition/reward presentation is adapted into the operation. Operation completion costs +one additional world cycle after travel. Unique rewards and access facts use the +operation completion ID and apply once. + +Hostile interruption closure is exact: + +- `cleared`: operation completion advances its one cycle, the commitment returns to + `advancing`, and remaining route checkpoints resume without new supply cost; +- `failed`: operation completion advances its one cycle, the commitment becomes + `diverted`, and the vessel becomes `stranded` at `(0, 0, 1280, 1024)` with the same + transaction ID; no access/reward is granted; +- `retreated`: operation completion advances its one cycle, the commitment becomes + `resolved`, and the vessel becomes `stationary` at the saved origin with null transit + ID; +- from the `failed` stranded state, `emergencyRetreat` is always available even at zero + supply. It advances exactly one additional galaxy cycle, returns to the saved origin, + clears the transit ID, and journals `${transactionId}:emergency-retreat` so reload or + double activation is a no-op. + +--- + +### Task 1: Fixed-point coordinates and stable identity helpers + +**Files:** +- Create: `game/app/components/engine/galaxy/galaxyTypes.ts` +- Create: `game/app/components/engine/galaxy/coordinates.ts` +- Create: `game/tests/engine/galaxyCoordinates.test.ts` + +- [ ] **Step 1: Write the failing coordinate tests** + +```ts +test("coordinates reject unsafe or fractional authority values", () => { + assert.equal(validateCoordinate({ sectorX: 0, sectorY: 0, localX: 12.5, localY: 2 }).ok, false); + assert.equal(validateCoordinate({ sectorX: 0, sectorY: 0, localX: Number.MAX_SAFE_INTEGER + 1, localY: 2 }).ok, false); +}); + +test("cell identity is stable within one cell", () => { + assert.equal(cellKey(coord(0, 0, 513, 770)), "0:0:2:3"); + assert.equal(cellKey(coord(0, 0, 700, 900)), "0:0:2:3"); +}); +``` + +- [ ] **Step 2: Run `npx tsx --test tests/engine/galaxyCoordinates.test.ts` from `game/`** + +Expected: FAIL because `engine/galaxy/coordinates` does not exist. + +- [ ] **Step 3: Implement `coord`, `validateCoordinate`, `coordinateKey`, `cellAddress`, `cellKey`, `sameCoordinate`, `distanceUnits`, and `stableHash`** + +Use only safe integers for saved coordinates. `stableHash` is an explicit unsigned FNV-1a-style hash using `Math.imul`; never use `Math.random` or object iteration order. + +- [ ] **Step 4: Rerun the focused test** + +Expected: PASS with both invalid-coordinate and same-cell assertions. + +- [ ] **Step 5: Run `npx tsc --noEmit`** + +Expected: exit 0. + +- [ ] **Step 6: Commit** + +```bash +git add game/app/components/engine/galaxy game/tests/engine/galaxyCoordinates.test.ts +git commit -m "feat(galaxy): add fixed-point coordinate contracts" +``` + +### Task 2: Versioned authored anchors and deterministic Atlas cells + +**Files:** +- Create: `game/app/components/engine/galaxy/authoredAnchors.ts` +- Create: `game/app/components/engine/galaxy/atlas.ts` +- Create: `game/tests/engine/galaxyAtlas.test.ts` + +- [ ] **Step 1: Write failing tests for the complete generation tuple** + +```ts +test("same complete generation identity and coordinate produce identical facts", () => { + assert.deepEqual(resolveCell(G0_GENERATION_IDENTITY, coord(0, 0, 1024, 768)), + resolveCell(G0_GENERATION_IDENTITY, coord(0, 0, 1024, 768))); +}); + +test("saved registry version controls latent output", () => { + const v1 = { ...G0_GENERATION_IDENTITY, authoredAnchorRegistryVersion: 1 }; + assert.deepEqual(resolveCell(v1, BLIND_FIXTURE_COORDINATE), resolveCell(v1, BLIND_FIXTURE_COORDINATE)); + assert.deepEqual(resolveCell({ ...v1, authoredAnchorRegistryVersion: 999 }, BLIND_FIXTURE_COORDINATE), + { ok: false, reason: "unsupported_registry_version" }); +}); + +test("unknown generation or registry versions remain unavailable", () => { + assert.equal(getGenerationAvailability({ ...G0_GENERATION_IDENTITY, generationVersion: 999 }).status, "unavailable"); + assert.equal(getGenerationAvailability({ ...G0_GENERATION_IDENTITY, authoredAnchorRegistryVersion: 999 }).status, "unavailable"); +}); +``` + +- [ ] **Step 2: Add failing tests for anchor reservation, blind-cell stability, different seeds, and materialized-fact precedence** + +Assert Vanguard, Ashfall, Kepler, picket, and unresolved-signal IDs never move between seeds; assert registry version 1 contains no relay; repeated plots in one cell return one fact ID; changing only `galaxySeed` changes a non-anchor cell; and `materializeCell(savedFact, regeneratedFact)` returns the saved fact. + +- [ ] **Step 3: Run `npx tsx --test tests/engine/galaxyAtlas.test.ts`** + +Expected: FAIL for missing anchor/Atlas modules. + +- [ ] **Step 4: Implement registry version 1 and pure cell resolution** + +Registry order is explicit. Dispatch both `generationVersion` and `authoredAnchorRegistryVersion` through supported-version tables before resolving anything. Public `resolveCell` returns `{ ok: false, reason: "unsupported_generation_version" | "unsupported_registry_version" }` after that check; it does not throw. Resolve an authored reservation before hashing a procedural cell. Procedural kinds are selected from a fixed table (`empty`, `stellar_contact`, `hazard`, `ruin`, `anomaly`, `signal`) and receive IDs from the complete generation tuple plus cell address. Unknown versions never fall through to current generation code. + +- [ ] **Step 5: Implement knowledge promotion without rerolls** + +`observeFact`, `chartFact`, `visitFact`, and `recordNegativeSurvey` return new `GalaxyAtlasState` values, preserve provenance/confidence/cycle, and reject backward promotion unless the explicit state is `lost_contact`. + +- [ ] **Step 6: Rerun the focused test and `npx tsc --noEmit`** + +Expected: both exit 0. + +- [ ] **Step 7: Commit** + +```bash +git add game/app/components/engine/galaxy game/tests/engine/galaxyAtlas.test.ts +git commit -m "feat(galaxy): generate stable Atlas cells and anchors" +``` + +### Task 3: Fresh galaxy namespace and field-by-field save migration + +**Files:** +- Create: `game/app/components/engine/galaxy/galaxyRun.ts` +- Create: `game/tests/engine/galaxySave.test.ts` +- Modify: `game/app/components/engine/types.ts:1066-1107` +- Modify: `game/app/components/engine/save.ts:36-129` +- Modify: `game/tests/colony/fixtures.ts:5-25` +- Modify: `game/tests/colony/advanceWorldCycle.test.ts:6-22` +- Modify: all remaining direct `SaveData` literals reported by TypeScript + +- [ ] **Step 1: Write the failing migration/default test** + +```ts +test("legacy saves default to an isolated legacy experience", () => { + const migrated = migrateSave({ credits: 999, colonies: [{ id: "legacy" }] }); + assert.equal(migrated.activeExperience, "legacy"); + assert.equal(migrated.galaxyRun, null); +}); +``` + +- [ ] **Step 2: Write the failing fresh-run isolation test** + +Create two migrated legacy saves with deliberately different credits, XP, upgrades, levels, completions, colonies, factions, and story items. Call `startFreshGalaxy` with the same identity and assert the two resulting `galaxyRun` objects are deeply equal while every legacy field in each parent save is unchanged. + +- [ ] **Step 3: Run `npx tsx --test tests/engine/galaxySave.test.ts`** + +Expected: FAIL for missing `galaxyRun` fields/factory. + +- [ ] **Step 4: Implement the fresh factory** + +The factory initializes supply, ship/pilot defaults, visited Vanguard knowledge, charted G0 contacts, operation states, no legacy completions, and a galaxy-owned Ashfall Primary created from `createPlanetRegionState("ashfall", ASHFALL_REGION_SEED)` plus the existing colony founding reducer. The initial vessel location is the Vanguard anchor. + +- [ ] **Step 5: Implement nested migration field by field** + +`migrateGalaxyRun` validates the complete identity, coordinate integers, enum members, arrays, maps, checkpoint IDs, colony/planet arrays, and every scalar with `??` fallbacks. It preserves unsupported saved generation and registry versions; `getGalaxyRunAvailability` checks both and returns a typed recoverable-unavailable result for the UI. It never drops the run or silently substitutes current generation code or the newest registry. + +- [ ] **Step 6: Add `activeExperience` and `galaxyRun` to every test fixture** + +Use `activeExperience: "legacy", galaxyRun: null`; do not use `as SaveData` to hide missing fields. + +- [ ] **Step 7: Run the focused test, `yarn colony:test`, and `npx tsc --noEmit`** + +Expected: all exit 0. + +- [ ] **Step 8: Commit** + +```bash +git add game/app/components/engine/types.ts game/app/components/engine/save.ts game/app/components/engine/galaxy/galaxyRun.ts game/tests +git commit -m "feat(save): add isolated galaxy run namespace" +``` + +### Task 4: Pure route previews with supply, time, threat, and confidence + +**Files:** +- Create: `game/app/components/engine/galaxy/routePlanner.ts` +- Create: `game/tests/engine/galaxyRoutePlanner.test.ts` + +- [ ] **Step 1: Write failing safe, hostile, blind, and blocked route tests** + +```ts +test("preview exposes all five threat dimensions", () => { + const plan = planRoute(runAtVanguard(), { kind: "contact", contactId: "contact:ashfall" }); + assert.equal(plan.ok, true); + if (!plan.ok) return; + assert.deepEqual(Object.keys(plan.plan.threat.dimensions).sort(), + ["anomalous", "environmental", "logistical", "military", "political"]); +}); + +test("insufficient supply blocks without mutation", () => { + const run = runAtVanguard({ supply: 0 }); + const before = structuredClone(run); + const result = planRoute(run, { kind: "contact", contactId: "contact:kepler" }); + assert.equal(result.ok, false); + assert.match(result.reasons.join(" "), /supply/i); + assert.deepEqual(run, before); +}); + +test("G0 route economy matches the versioned content table", () => { + assert.deepEqual(costTo("contact:ashfall"), { distanceUnits: 512, elapsedCycles: 1, supplyCost: 2 }); + assert.deepEqual(costTo("contact:hostile-picket"), { distanceUnits: 923, elapsedCycles: 2, supplyCost: 3 }); + assert.deepEqual(costTo("contact:kepler"), { distanceUnits: 1619, elapsedCycles: 3, supplyCost: 5 }); + assert.equal(planTo("signal:unresolved-g0").ok, false); +}); +``` + +- [ ] **Step 2: Run `npx tsx --test tests/engine/galaxyRoutePlanner.test.ts`** + +Expected: FAIL because `routePlanner` is missing. + +- [ ] **Step 3: Implement route-plan identity and direct/relay legs** + +The plan ID hashes immutable origin, destination, target, capability, policy, identity, ordered legs, cost, and cycle snapshot. Implement the exact version-1 direct-route range, cycle, and supply formulas from the G0 content/economy table; do not add a relay candidate in version 1. The preview also returns known ports/repair opportunities and forecasted world changes as explicit arrays, even when both are empty in G0. + +- [ ] **Step 4: Implement qualitative threat aggregation** + +Each dimension carries `band`, `confidence`, `sources`, and `unknownContributors`. Never emit a numeric success probability. Unknown blind targets state the uncertainty instead of becoming secretly lethal. + +- [ ] **Step 5: Rerun focused tests and `npx tsc --noEmit`** + +Expected: exit 0. + +- [ ] **Step 6: Commit** + +```bash +git add game/app/components/engine/galaxy/routePlanner.ts game/tests/engine/galaxyRoutePlanner.test.ts +git commit -m "feat(galaxy): preview supply-bound Atlas routes" +``` + +### Task 5: Allowlisted engine projection and galaxy-only cycle advancement + +**Files:** +- Create: `game/app/components/engine/galaxy/galaxyProjection.ts` +- Create: `game/tests/engine/galaxyProjection.test.ts` + +- [ ] **Step 1: Write the failing locked-projection test** + +```ts +test("engine projection cannot inherit legacy availability", () => { + const parent = legacyRichSaveWithFreshGalaxy(); + const projected = projectGalaxyRunToLegacySave(parent); + assert.deepEqual(projected.levels, {}); + assert.deepEqual(projected.completedPlanets, []); + assert.deepEqual(projected.unlockedSpecialMissions, []); + assert.deepEqual(projected.activeQuests, []); + assert.deepEqual(projected.colonies, parent.galaxyRun?.colonies); +}); +``` + +- [ ] **Step 2: Write the failing no-leakage test** + +Snapshot every legacy progression field, advance two galaxy cycles, and assert the snapshot is byte-for-byte equal afterward while `galaxyRun.worldCycle` and galaxy colony `lastCycleProcessed` advance exactly twice. The transient projection maps `worldCycle` to its `missionsSinceStart` field; no second galaxy counter is introduced. + +- [ ] **Step 3: Run `npx tsx --test tests/engine/galaxyProjection.test.ts`** + +Expected: FAIL for missing projection APIs. + +- [ ] **Step 4: Implement `projectGalaxyRunToLegacySave`** + +Construct every `SaveData` field explicitly. Source ship, pilot, story, Atlas-owned colonies/planets/factions, and world-cycle counters only from `GalaxyRunState`; hard-code legacy availability arrays/maps empty. + +The transient object explicitly uses `activeExperience: "legacy"` and +`galaxyRun: null` so existing engine helpers see a non-recursive compatibility save. It +is never passed to `saveSave`; only the canonical parent save can be persisted. + +- [ ] **Step 5: Implement `mergeProjectionIntoGalaxy` and `advanceGalaxyWorldCycles`** + +Allow only colonies, planets, faction standings, pilot XP/level/skills, ship inventory/equipment, Bestiary/Codex entries explicitly earned by the operation, and the projected cycle counter. Reject an unknown delta key. Call existing `advanceWorldCycle` on the transient projection once per promised cycle. + +- [ ] **Step 6: Rerun focused tests, `yarn colony:test`, and `npx tsc --noEmit`** + +Expected: all exit 0. + +- [ ] **Step 7: Commit** + +```bash +git add game/app/components/engine/galaxy/galaxyProjection.ts game/tests/engine/galaxyProjection.test.ts +git commit -m "feat(galaxy): isolate legacy engine projections" +``` + +### Task 6: Idempotent journaled travel commitments + +**Files:** +- Create: `game/app/components/engine/galaxy/travelResolver.ts` +- Create: `game/tests/engine/galaxyTravelResolver.test.ts` + +- [ ] **Step 1: Write the failing initial-commit idempotency test** + +Commit one preview twice with `travel::` and assert one commitment, one supply deduction, one ordinal increment, and no duplicate checkpoint. + +- [ ] **Step 2: Write the failing reload matrix** + +For saved states `committed`, `advancing`, `interrupted`, `arrived`, `diverted`, and `resolved`, serialize through `migrateSave`, resume, and assert only missing checkpoint IDs apply. Supply, elapsed cycles, interruption ID, and arrival never reroll or duplicate. + +- [ ] **Step 3: Write failing safe-arrival and hostile-interruption tests** + +The Ashfall route reaches `arrived`; the picket route stops at `interrupted` with `op:hostile-picket`; both leave a playable `resolve`, `launch`, `retreat`, or `return` action. + +- [ ] **Step 4: Write failing interruption-closure tests** + +`resolveTravelInterruption` with `cleared` resumes the saved route and can arrive; +`failed` sets commitment `diverted` and vessel `stranded` at the exact hostile-picket +coordinate; `retreated` restores the origin and resolves the commitment. Assert +`emergencyRetreat` from `failed` costs zero supply, advances one cycle, restores the +origin, resolves the commitment, and no-ops on double activation/reload. Each outcome +updates vessel status/location once. + +- [ ] **Step 5: Write the failing blind-arrival test** + +Commit and resolve travel to `BLIND_FIXTURE_COORDINATE`. Assert arrival materializes the +stable cell fact and `mappedCellKeys`. `empty` persists a negative-survey record; +`stellar_contact` and `ruin` persist `visited` direct-visit knowledge; `hazard` and +`anomaly` persist `visited` direct-visit knowledge with their observed kind; `signal` +persists signal knowledge at the exact coordinate with direct-visit provenance. Table- +drive all six generator kinds. Reload and repeat without rerolling or adding a second +fact or knowledge record. + +- [ ] **Step 6: Run `npx tsx --test tests/engine/galaxyTravelResolver.test.ts`** + +Expected: FAIL because `travelResolver` is missing. + +- [ ] **Step 7: Implement `commitTravel`** + +Re-plan from current state and reject a stale plan before mutation. In one returned save value, record the commitment, deduct supply, set vessel `in_transit`, and increment the saved transaction ordinal. Reusing the same transaction ID returns the identical save object. + +- [ ] **Step 8: Implement `advanceTravelCheckpoint` and `resumeTravelToBoundary`** + +Checkpoint IDs are `${transactionId}:leg:${index}`. Before applying a leg, check `appliedCheckpointIds`; after applying its exact cycles through `advanceGalaxyWorldCycles`, journal the ID and either advance, interrupt for a recorded cause, or arrive. Arrival resolves/materializes the destination cell, records mapped coverage or observed contact/hazard knowledge, and never rerolls a saved fact. + +Use the Task 6 blind-arrival mapping for every procedural kind: empty, stellar contact, +hazard, ruin, anomaly, and signal. No successful arrival may omit both a materialized +fact and a knowledge/negative-survey record. + +- [ ] **Step 9: Implement `resolveTravelInterruption`** + +Accept only the active interruption operation and a typed `cleared`, `failed`, or +`retreated` result. Journal `${transactionId}:interruption:`, update vessel and +commitment atomically using the exact closure table above, and either resume, strand at +the picket, or return to origin. Implement `emergencyRetreat` as a separate zero-supply, +one-cycle, idempotent transition from the failed stranded state. Existing interruption +checkpoint IDs make repeated operation callbacks and reloads no-ops. + +- [ ] **Step 10: Rerun focused tests and `npx tsc --noEmit`** + +Expected: exit 0. + +- [ ] **Step 11: Commit** + +```bash +git add game/app/components/engine/galaxy/travelResolver.ts game/tests/engine/galaxyTravelResolver.test.ts +git commit -m "feat(galaxy): journal idempotent travel commitments" +``` + +### Task 7: Unified located operation catalog and engine launch adapters + +**Files:** +- Create: `game/app/components/engine/operations/operationTypes.ts` +- Create: `game/app/components/engine/operations/operationCatalog.ts` +- Create: `game/app/components/engine/operations/operationAdapters.ts` +- Create: `game/tests/engine/galaxyOperations.test.ts` + +- [ ] **Step 1: Write failing catalog tests** + +Assert the fresh run contains stable located definitions for `op:hostile-picket`, `op:kepler-black-box`, and `op:ashfall-sortie`; each has source, coordinate, contact, cause facts, objective, modifiers, phases, threat, costs, rewards, availability, and state. + +Assert the exact coordinates, cause IDs, `world 1 / level 1` shooter payload, zero +operation supply costs, success rewards, Quick Draw modifier, and failure/retreat +effects from the G0 content/economy table. + +- [ ] **Step 2: Write the failing legacy-gate bypass test** + +Use a projection with empty `levels`, `completedPlanets`, `unlockedSpecialMissions`, and quest arrays. Authorize each operation from its Atlas contact and assert the adapters still create shooter, first-person Kepler, and Ashfall planet `GameState` values. + +- [ ] **Step 3: Write the failing modifier test** + +Assert the hostile picket carries the existing Quick Draw time-attack condition by stable quest ID, but operation availability never calls `getAvailableQuests` or consults `unlockAfter`. + +- [ ] **Step 4: Run `npx tsx --test tests/engine/galaxyOperations.test.ts`** + +Expected: FAIL for missing operation modules. + +- [ ] **Step 5: Implement the catalog and availability reducer** + +Availability reads current vessel/contact location, operation state, access facts, active travel, and unique history only. A missing adapter returns `unavailable` with recoverable copy. + +- [ ] **Step 6: Implement engine adapters without changing constructors** + +`op:hostile-picket` calls `createGameState` with its internal legacy payload, Kepler calls `createSpecialMissionGameState`, and Ashfall calls `createPlanetGameState`. The returned `OperationLaunchContext` records operation ID and adapter kind; the payload's world/level fields are not availability authority. + +Pass Kepler's `blackBoxRecovered` constructor argument only from +`GalaxyRunState.storyItems.includes("kepler-black-box")`; never read the legacy +projection's story/completion fields for this decision. + +- [ ] **Step 7: Rerun focused tests, `yarn engine:test`, and `npx tsc --noEmit`** + +Expected: all exit 0. + +- [ ] **Step 8: Commit** + +```bash +git add game/app/components/engine/operations game/tests/engine/galaxyOperations.test.ts +git commit -m "feat(operations): launch located G0 encounters" +``` + +### Task 8: Normalized, one-time operation outcomes + +**Files:** +- Create: `game/app/components/engine/operations/operationOutcome.ts` +- Create: `game/tests/engine/galaxyOperationOutcome.test.ts` +- Modify: `game/app/components/colony/shared/missionDelivery.ts` only if a type export is required; preserve existing behavior + +- [ ] **Step 1: Write the failing idempotent completion test** + +Apply one `completionId` twice and assert operation state, supply/material, knowledge, access facts, history facts, pilot results, and cycles apply once. + +- [ ] **Step 2: Write the failing Kepler uniqueness test** + +Completing Kepler with the black box records one galaxy history fact and one story item. Replaying the engine may complete work but cannot duplicate the unique reward. + +- [ ] **Step 3: Write the failing Ashfall cargo test** + +Project the galaxy run, call the existing `applyMissionDelivery(..., "ashfall")` or `applyExplicitMissionDelivery`, merge through the allowlist, and assert the galaxy-owned Ashfall colony receives the payload while legacy colonies/resources remain unchanged. Assert the emitted event reason remains `mission_delivery`. + +- [ ] **Step 4: Write the failing access consequence test** + +Completing the picket records one access fact that lowers/removes its military route cause; failing or retreating records history without falsely securing the route. + +For an operation launched by an active interruption, outcome folding must also call +`resolveTravelInterruption` with the typed result. Success resumes/arrives; failure +diverts/strands; retreat returns to the saved origin. The operation and travel outcome +share one completion ID so a repeated callback cannot resolve either side twice. + +- [ ] **Step 5: Run `npx tsx --test tests/engine/galaxyOperationOutcome.test.ts`** + +Expected: FAIL because outcome folding is missing. + +- [ ] **Step 6: Implement validation and folding** + +Reject unknown operation IDs, cause facts, contacts, reward fields, or duplicate unique facts before mutation. Tick one operation-completion world cycle separately from travel, then merge the normalized allowlist into `GalaxyRunState`. + +- [ ] **Step 7: Rerun focused tests, `yarn colony:test`, `yarn engine:test`, and `npx tsc --noEmit`** + +Expected: all exit 0. + +- [ ] **Step 8: Commit** + +```bash +git add game/app/components/engine/operations/operationOutcome.ts game/tests/engine/galaxyOperationOutcome.test.ts game/app/components/colony/shared/missionDelivery.ts +git commit -m "feat(operations): fold G0 outcomes into galaxy history" +``` + +### Task 9: Projected Ashfall region and POI adapters + +**Files:** +- Modify: `game/app/components/engine/operations/operationAdapters.ts` +- Create: `game/tests/colony/galaxyRegionAdapter.test.ts` + +- [ ] **Step 1: Write failing projected-region tests** + +Assert `openGalaxyRegion(save, "contact:ashfall")` returns the galaxy-owned origin colony and a projected save accepted by `RegionMapScreen`; a non-Ashfall or non-visited contact is rejected. + +- [ ] **Step 2: Write failing survey/found/POI tests** + +Wrap `startRegionExpedition`, `foundOutpost`, `preparePoiCompletion`, and `resolvePoiCompletion`. Assert survey and POI travel cycles update only `galaxyRun`, found outposts deduct galaxy-colony resources, POI cargo uses `mission_delivery`, and legacy colony/planet arrays remain byte-for-byte unchanged. + +- [ ] **Step 3: Run `npx tsx --test tests/colony/galaxyRegionAdapter.test.ts`** + +Expected: FAIL for missing projected region APIs. + +- [ ] **Step 4: Implement the wrappers** + +Every call follows `canonical save -> project -> existing pure M1 function -> validate -> allowlisted merge -> canonical save`. Never persist a projected save. Preserve existing POI replay and one-time reward rules. + +- [ ] **Step 5: Rerun focused tests, `yarn colony:test`, and `npx tsc --noEmit`** + +Expected: all exit 0. + +- [ ] **Step 6: Commit** + +```bash +git add game/app/components/engine/operations/operationAdapters.ts game/tests/colony/galaxyRegionAdapter.test.ts +git commit -m "feat(galaxy): expose Ashfall through projected region adapters" +``` + +### Task 10: Pure Atlas viewport and input equivalence + +**Files:** +- Create: `game/app/components/galaxy/atlasViewport.ts` +- Create: `game/tests/engine/galaxyAtlasViewport.test.ts` + +- [ ] **Step 1: Write failing projection and clamp tests** + +Assert world-to-screen and screen-to-world round-trip at multiple viewport sizes, pan clamps to G0 bounds, zoom clamps to named min/max, and no projection output changes cell identity. Assert the zoom/view reducer exposes the four conceptual levels, with galaxy as a non-interactive frame in G0, sector as the functional field, system as the selected-contact detail, and region as the explicit Ashfall handoff. + +- [ ] **Step 2: Write failing input-equivalence tests** + +Assert pointer hit, touch hit, DOM contact activation, keyboard contact navigation, and arbitrary-coordinate form normalization produce the same `AtlasTarget`. Assert arrow pan and labeled touch-pan controls call the same reducer. + +- [ ] **Step 3: Run `npx tsx --test tests/engine/galaxyAtlasViewport.test.ts`** + +Expected: FAIL because the viewport module is missing. + +- [ ] **Step 4: Implement the pure viewport reducer** + +State is `{ viewLevel, center, zoom, selectedTargetId }`. Actions are `set-view`, `pan`, `zoom`, `select-contact`, and `select-coordinate`; touch pinch is converted to the same `zoom` action and never commits a target. Generation APIs never receive display size, FPS, input method, pan, or zoom. + +- [ ] **Step 5: Rerun focused tests and `npx tsc --noEmit`** + +Expected: exit 0. + +- [ ] **Step 6: Commit** + +```bash +git add game/app/components/galaxy/atlasViewport.ts game/tests/engine/galaxyAtlasViewport.test.ts +git commit -m "feat(atlas): add input-neutral viewport controls" +``` + +### Task 11: Hybrid Canvas/DOM Galaxy Atlas screen + +**Files:** +- Create: `game/app/components/galaxy/GalaxyAtlasScreen.tsx` +- Create: `game/app/components/galaxy/GalaxyExperienceGate.tsx` +- Create: `game/app/components/galaxy/index.ts` +- Create: `game/tests/engine/galaxyAtlasScreen.test.ts` + +- [ ] **Step 1: Write the failing SSR surface test** + +```ts +test("Atlas has a DOM-complete travel path", () => { + const html = renderToStaticMarkup(React.createElement(GalaxyAtlasScreen, propsForKnownRoute())); + assert.match(html, /role="listbox"/); + assert.match(html, /ASHFALL/); + assert.match(html, /DISTANCE[\s\S]*CYCLES[\s\S]*SUPPLY/); + for (const label of ["MILITARY", "POLITICAL", "ENVIRONMENTAL", "LOGISTICAL", "ANOMALOUS"]) assert.match(html, new RegExp(label)); + assert.match(html, /PLOT COORDINATE/); + assert.match(html, /COMMIT TRAVEL/); + assert.doesNotMatch(html, /W1|WORLD 1|NEXT LEVEL/); +}); +``` + +- [ ] **Step 2: Add failing SSR tests for entry, block, uncertainty, interruption, and no-run states** + +Assert focusable `BEGIN GALAXY` and `LEGACY CAMPAIGN`; every contact has a DOM button; insufficient supply names the reason and disables commit; blind preview names unknown confidence; interrupted travel exposes launch/retreat; unsupported generation shows recoverable copy. + +- [ ] **Step 3: Run `npx tsx --test tests/engine/galaxyAtlasScreen.test.ts`** + +Expected: FAIL because the React components are missing. + +- [ ] **Step 4: Implement the DOM surface first** + +Use one selected target shared by the contact list, coordinate form, route panel, and callbacks. Provide focusable arrow-pan buttons, `+/-` zoom, coordinate number inputs, route warnings, status live region, and operation/Ashfall controls. + +Render a DOM breadcrumb/control row for `GALAXY / SECTOR / SYSTEM / REGION`. Galaxy is a labeled non-interactive framing preview in G0; sector is the navigable field; system is the selected contact/operation panel; region invokes the existing Ashfall screen when available. + +- [ ] **Step 5: Add Canvas 2D drawing inside `useEffect`** + +Acquire `canvas.getContext("2d")` after mount. Render field, contacts, route, threat volumes, and selection from pure projection data. Pointer/touch handlers dispatch viewport actions; touch drag/pinch never triggers commit. No Canvas item is the sole selectable representation. + +- [ ] **Step 6: Add focus restoration** + +After pan/zoom keep focus on the initiating DOM control; after target changes focus its details heading; on close return focus to the invoking control. + +- [ ] **Step 7: Rerun focused tests and `npx tsc --noEmit`** + +Expected: exit 0. + +- [ ] **Step 8: Commit** + +```bash +git add game/app/components/galaxy game/tests/engine/galaxyAtlasScreen.test.ts +git commit -m "feat(atlas): add accessible hybrid galaxy screen" +``` + +### Task 12: Deterministic DevPanel galaxy fixtures + +**Files:** +- Create: `game/app/components/galaxy/devFixtures.ts` +- Create: `game/tests/engine/galaxyDevFixtures.test.ts` +- Modify: `game/app/components/DevPanel.tsx:1-260` + +- [ ] **Step 1: Write failing fixture tests** + +Assert six fixed fixtures exist: `atlas-start`, `known-route`, `hostile-route`, `blind-discovery`, `insufficient-supply`, and `in-transit-reload`. Applying the same fixture twice produces equal galaxy state and never mutates legacy fields. + +- [ ] **Step 2: Run `npx tsx --test tests/engine/galaxyDevFixtures.test.ts`** + +Expected: FAIL because `devFixtures` is missing. + +- [ ] **Step 3: Implement fixtures from the public reducers** + +Do not hand-edit internal checkpoint arrays except the explicit `in-transit-reload` snapshot, which must be produced by `commitTravel` plus exactly one checkpoint transition. + +- [ ] **Step 4: Add `GALAXY SEEDS` buttons to DevPanel** + +Buttons emit `seed-galaxy:` and appear automatically in DevPanel-enabled builds. + +- [ ] **Step 5: Rerun focused tests and `npx tsc --noEmit`** + +Expected: exit 0. + +- [ ] **Step 6: Commit** + +```bash +git add game/app/components/galaxy/devFixtures.ts game/app/components/DevPanel.tsx game/tests/engine/galaxyDevFixtures.test.ts +git commit -m "feat(devtools): add deterministic Atlas fixtures" +``` + +### Task 13: Game orchestration and experience separation + +**Files:** +- Modify: `game/app/components/Game.tsx:88-2241` +- Create: `game/app/components/engine/galaxy/experienceFlow.ts` +- Create: `game/tests/engine/galaxyExperienceFlow.test.ts` +- Modify: `game/app/components/engine/cockpit.ts:15-167` only if type/action naming is needed; do not rewrite cockpit rendering + +- [ ] **Step 1: Write failing pure experience-flow tests** + +Implement/test `beginGalaxyExperience`, `mapSurfaceForExperience`, `returnSurfaceForOperation`, and `legacyProgressionSnapshot` in `engine/galaxy/experienceFlow.ts`. Assert begin creates or resumes the galaxy, legacy opens the old star map, galaxy opens the Atlas, and an operation completion returns to Atlas without changing the legacy snapshot. Tests never import the full client `Game.tsx` component. + +- [ ] **Step 2: Run `npx tsx --test tests/engine/galaxyExperienceFlow.test.ts`** + +Expected: FAIL for missing flow helpers. + +- [ ] **Step 3: Add explicit experience entry** + +Mount `GalaxyExperienceGate` on the start screen. `LEGACY CAMPAIGN` preserves the current intro/cockpit flow. `BEGIN/CONTINUE GALAXY` persists the new selector/run and opens the Atlas directly; it never deletes legacy data. + +- [ ] **Step 4: Route the cockpit STAR MAP hotspot by `activeExperience`** + +Legacy keeps `showMap` and `drawStarMap`. Galaxy mounts `GalaxyAtlasScreen` and never starts the old star-map rAF loop. + +- [ ] **Step 5: Wire Atlas selection and travel** + +Preview remains derived. Confirm creates a deterministic transaction ID from the saved ordinal, commits, resumes to arrival/interruption, persists once per canonical returned state, and keeps the selected target on a block. + +- [ ] **Step 6: Wire operation launch/restart/completion** + +Track `activeOperationId` separately from legacy planet/special IDs. Launch the adapter state, restart through the same adapter, intercept `LEVEL_COMPLETE` before legacy `nextLevel`, fold one normalized outcome, and return to Atlas. GAME_OVER offers retry/retreat/Atlas and never fabricates completion. + +When the active operation is the saved travel interruption, pass its completion, +failure, or retreat into `resolveTravelInterruption` before returning to the Atlas. A +cleared picket resumes/arrives, a failure exposes the deterministic diverted/stranded +state with an always-enabled `EMERGENCY RETREAT` DOM action, and retreat restores the +route origin; no path leaves an orphaned active travel. The emergency action calls only +the zero-supply, one-cycle `emergencyRetreat` reducer and remains safe after reload. + +- [ ] **Step 7: Wire Ashfall region/POI projection** + +Pass the projected save into `RegionMapScreen`/`PoiOutcomeScreen`; call only the Task 9 wrappers for mutations; persist only the returned canonical parent save. On galaxy POI completion, return to the Atlas or projected Ashfall region instead of writing top-level colony state. + +- [ ] **Step 8: Wire DevPanel fixtures** + +Handle `seed-galaxy:` by applying the fixture, clearing active engine/POI UI, and opening the Atlas. + +- [ ] **Step 9: Audit all surface guards** + +Add `showGalaxyAtlas` to game-loop, non-playing draw-loop, grade-menu, keyboard Escape, mute-button, pointer/touch, pause, and cleanup conditions so no hidden rAF or canvas handler remains active behind the DOM Atlas. + +- [ ] **Step 10: Run focused tests, `yarn colony:test`, `yarn engine:test`, and `npx tsc --noEmit`** + +Expected: all exit 0. + +- [ ] **Step 11: Commit** + +```bash +git add game/app/components/Game.tsx game/app/components/engine/cockpit.ts game/app/components/engine/galaxy/experienceFlow.ts game/tests/engine/galaxyExperienceFlow.test.ts +git commit -m "feat(game): make the Atlas the galaxy-run mission surface" +``` + +### Task 14: Full gates, production playtest, review, and PR update + +**Files:** +- Modify: `docs/ROADMAP.md` only after all G0 acceptance checks pass +- Create: `docs/playtests/2026-07-16-g0-atlas.md` +- Modify runtime files only through a failing regression test if verification exposes a defect + +- [ ] **Step 1: Run static/type/test gates individually from `game/`** + +```bash +npx tsc --noEmit +yarn colony:test +yarn engine:test +yarn sprites:test +yarn build +NEXT_PUBLIC_DEVTOOLS=1 yarn build +``` + +Record exact test counts and exit status. Any failure blocks completion. + +- [ ] **Step 2: Prove static-export safety** + +Search new modules for module-scope `window`, `document`, `performance`, `Date.now`, `Math.random`, WebGL, and Canvas context acquisition. Confirm the default and DevPanel builds both finish without module-evaluation errors. + +- [ ] **Step 3: Start the production-like test environment** + +From `game/`, run `NEXT_PUBLIC_DEVTOOLS=1 yarn build`, then from another shell run `npx serve out -l 3000`. Use a fresh browser storage profile at 480x854 and a desktop viewport. + +- [ ] **Step 4: Playtest explicit entry and navigation** + +Verify legacy campaign still opens W1-W8. Launch and complete one legacy mission through +the normal `nextLevel`/return-to-cockpit path, then reload and confirm its stars, score, +and unlock state persist. Begin a new galaxy; pointer, touch, DOM, and keyboard select +the same contacts; arrows/buttons pan; +/- and touch controls zoom; coordinate form +selects a blind target; focus remains meaningful. + +- [ ] **Step 5: Playtest travel correctness** + +Use `KNOWN ROUTE`, `HOSTILE ROUTE`, `BLIND DISCOVERY`, `INSUFFICIENT SUPPLY`, and +`IN-TRANSIT RELOAD`. Confirm full preview copy, exact supply/cycles, no double-confirm +charge, safe arrival, caused picket interruption, reload resume, and every interruption +closure: cleared resumes/arrives, failure diverts/strands playably, retreat returns to +origin. From the failed stranded screen, activate `EMERGENCY RETREAT` at zero supply and +confirm one cycle plus a return to the saved origin; repeat after reload and confirm no +second tick. Commit the blind route and confirm it persists one materialized fact plus mapped +coverage/negative survey or observed knowledge across reload without reroll. + +- [ ] **Step 6: Playtest the three adapted contexts** + +Complete the hostile shooter, Kepler retrieval, and Ashfall planet/region/POI path. Confirm material, knowledge, and access outputs; Kepler uniqueness; POI `mission_delivery`; colony result persistence; and no legacy completion/unlock/resource changes. + +- [ ] **Step 7: Record browser evidence** + +In `docs/playtests/2026-07-16-g0-atlas.md`, record build SHA, commands/counts, browser/viewport, fixture-by-fixture observations, reload/double-confirm evidence, console errors, and any deferred visual issues. + +- [ ] **Step 8: Update the roadmap only if verified** + +Change G0 from `NEXT SYSTEMIC SLICE` to `DONE` and list the verified runtime proof. If any acceptance path is missing, leave G0 in progress and state the exact gap. + +- [ ] **Step 9: Run the final scope audit** + +```bash +git diff --check origin/main...HEAD +git status --short --branch +git diff --name-status origin/main...HEAD +git log --oneline origin/main..HEAD +``` + +Confirm no sprite, sprite-registration, asset-script, WebGL renderer, or unrelated balance files changed. + +- [ ] **Step 10: Commit verification documentation** + +```bash +git add docs/ROADMAP.md docs/playtests/2026-07-16-g0-atlas.md +git commit -m "docs(galaxy): record G0 Atlas verification" +``` + +- [ ] **Step 11: Request independent code review and fix blockers test-first** + +Use `superpowers:requesting-code-review` against the spec and this plan. Any real defect gets a failing regression test before the fix; rerun affected focused tests and every final gate. + +- [ ] **Step 12: Push and update the draft PR** + +Push the implementation branch and update the PR body with task commits, exact verification counts, playtest matrix, screenshots, legacy-isolation evidence, and residual risks. Do not merge without explicit user approval and green CI.