space-game/worksheet.md

Pre-Commit Review Worksheet

This worksheet covers the uncommitted work from the long session after 0bb72be.

1. World Bootstrap, Scenario, And Generation

• Confirm the backend now starts from the empty scenario and still wires auth/player-state services correctly. Review: Program.cs, Program.cs, Program.cs, Program.cs
• Confirm the world-build pipeline is now split into explicit phases instead of a single muddy bootstrap path. Review: WorldBuilder.cs, WorldTopologyBuilder.cs, ScenarioValidationService.cs, ScenarioContentBuilder.cs, WorldRuntimeAssembler.cs
• Confirm known systems are generation input now, not hardcoded forced inclusions. Review: WorldGenerationOptions.cs, SystemGenerationService.cs, SystemGenerationService.cs, StaticDataProvider.cs

2. Static Data Canonicalization And Ship Model Cleanup

• Confirm static data now loads the promoted shared/data files with enum-string deserialization. Review: StaticDataProvider.cs, StaticDataProvider.cs, StaticDataProvider.cs
• Confirm ShipDefinition is now using the X4 domain model directly. Review: WorldDefinitions.cs, WorldDefinitions.cs, WorldDefinitions.cs
• Confirm the old compatibility baggage is gone or reduced. Review: WorldDefinitions.cs, WorldDefinitions.cs, WorldDefinitions.cs
• Confirm ship classification and movement capability checks now use explicit helpers instead of fake capability bags or fake role taxonomies. Review: KnownShipTaxonomy.cs, SimulationRuntimeSupport.cs, SimulationRuntimeSupport.cs, SimulationRuntimeSupport.cs

3. Auth, Versioning, And Player-State Separation

• Confirm local auth is wired with JWT access/refresh and no longer depends on the old single-player world-owned faction state. Review: AuthService.cs, AuthService.cs, PostgresAuthRepository.cs, HttpContextPlayerIdentityResolver.cs
• Confirm forgot/reset password is wired through the delivery seam rather than hardcoded email behavior. Review: AuthService.cs, AuthService.cs, IPasswordResetDelivery.cs, DevPasswordResetDelivery.cs
• Confirm dev accounts and roles are seeded only through the dev seeder. Review: DevAuthSeeder.cs, Program.cs, Program.cs
• Confirm version reporting exists and is reviewable during local backend restarts. Review: AppVersionService.cs, GetVersionHandler.cs
• Confirm player state is no longer owned by SimulationWorld and now lives behind a store/projection boundary. Review: IPlayerStateStore.cs, PlayerStateStore.cs, PlayerFactionProjectionService.cs, WorldService.cs

4. GM / Dev Loop

• Confirm the GM account can mutate an empty world without requiring a fake player scenario. Review: WorldService.cs, WorldService.cs, WorldService.cs
• Confirm direct ship control now works for GM as well as player-owned ships. Review: WorldService.cs, WorldService.cs, WorldService.cs
• Confirm Mine Resource validation is enforced at enqueue time and uses the richer cargo model. Review: WorldService.cs, WorldService.cs, WorldService.cs

5. Viewer Auth, Landing, And Dev UX

• Confirm the viewer is gated behind auth and boots into the landing page until a session exists. Review: App.vue, AuthLandingPage.vue, AuthSessionPanel.vue
• Confirm auth session persistence and GM access checks are centralized. Review: authStore.ts, authStore.ts, authStore.ts
• Confirm the new viewer shell includes the entity list, inspector, and right-click order context menu. Review: App.vue, App.vue, App.vue, viewerScene.ts, viewerOrderContextMenu.ts
• Confirm the inspector now mixes read-only state with actionable ship controls. Review: ViewerEntityInspectorPanel.vue, ViewerEntityInspectorPanel.vue, ViewerEntityInspectorPanel.vue, ViewerEntityInspectorPanel.vue
• Confirm the right-click menu respects GM access and issues direct orders rather than changing behaviors. Review: ViewerShipOrderContextMenu.vue, ViewerShipOrderContextMenu.vue, ViewerShipOrderContextMenu.vue
• Confirm the GM window supports faction, ship, and station spawning. Review: api.ts, api.ts, api.ts, GmOpsWindow.vue, GmOpsWindow.vue

6. Ship Orders, Behaviors, Catalog, And AI Refactor

• Confirm the automation catalog is now the central behavior/order vocabulary and is exposed to the viewer. Review: ShipAutomationCatalog.cs, GetShipAutomationCatalogHandler.cs
• Confirm the queue-backed model is now the main AI path: emergency plan, sync managed behavior orders, build order plan, then only fallback to idle/blocked behavior plans. Review: ShipAiService.cs, ShipAiService.cs, ShipAiService.cs, ShipAiService.Planning.Behaviors.cs
• Confirm the old parallel Build*BehaviorPlan(...) path is gone for migrated behaviors. Review: ShipAiService.BehaviorQueue.cs, ShipAiService.BehaviorQueue.cs, ShipAiService.Planning.Orders.cs
• Confirm the internal managed behavior orders were introduced intentionally and are cataloged. Review: SimulationKinds.cs, SimulationKinds.cs, SimulationKinds.cs, ShipAutomationCatalog.cs
• Confirm ShipAiService was split and moved to Ships/AI without changing the external orchestration contract. Review: ShipAiService.cs, ShipAiService.BehaviorQueue.cs, ShipAiService.Planning.Orders.cs

7. Suggested Final Sanity Pass Before Commit

• Build backend: dotnet build apps/backend/SpaceGame.Api.csproj
• Build viewer: npm run build in apps/viewer
• Smoke test with gm/gm: create faction spawn station spawn miner verify the inspector shows direct orders above the behavior divider
• Smoke test an empty restart: /api/world returns an empty world /api/version returns current version info /api/player-faction behaves via auth/player-state store rather than a world-owned player faction

8. Pending Work (Non-Blocking For This Commit)

• Do a systematic live validation pass for all behaviors/orders now marked Supported. Focus review: ShipAutomationCatalog.cs, ShipAiService.cs
• Continue the viewer control-surface polish. Focus review: ViewerEntityInspectorPanel.vue, ViewerShipOrderContextMenu.vue, viewer.css
• Revisit the long-term ship AI execution model. The current queue-backed architecture is coherent, but it still runs through subtask plans internally. Focus review: ShipAiService.Planning.Behaviors.cs, ShipAiService.Planning.Orders.cs, ShipAiService.Execution.cs
• Revisit the celestial/orbital hierarchy model. The runtime currently has a flat celestial list with ParentNodeId, but orbital updates are still handled by special-case loops instead of a generic parent-first hierarchy pass. Desired direction: keep a flat ordered list, but compute child positions from parent-relative orbital data in one forward pass. Focus review: SpatialBuilder.cs, SpatialRuntimeModels.cs, OrbitalStateUpdater.cs, Celestial.cs
• Revisit scenario-authored ship automation. ScenarioDefinition.PatrolRoutes is too coarse; scenario ships should eventually be able to author their own default behavior and parameters directly. Open question: whether scenarios should also be allowed to author an initial order queue, not only a default behavior. Desired direction: remove top-level patrol-route bootstrap and move authored automation closer to ship formations. Focus review: ScenarioDefinition, PatrolRouteDefinition, ScenarioContentBuilder.cs, ScenarioContentBuilder.cs
• Revisit behavior composition over internal pseudo-orders. The shared queue model is in place, but some behaviors still compile to internal executable orders like mine-and-deliver-run, supply-fleet-run, and salvage-run. Desired direction: higher-level behaviors should prefer composing a small set of real basic orders rather than relying on behavior-only executable order kinds. Focus review: ShipAiService.BehaviorQueue.cs, ShipAiService.Planning.Orders.cs, SimulationKinds.cs, ShipAutomationCatalog.cs
• Revisit the procedural generation dependency on known systems. SystemGenerationService still requires at least one known system because known systems are being used both as selectable authored systems and as templates for generated systems. Desired direction: procedural generation should be able to work with UseKnownSystems = false and an empty known-system pool. Focus review: SystemGenerationService.cs, SystemGenerationService.cs, SystemGenerationService.cs
• Revisit the production/dependency graph boundary. ProductionGraphBuilder currently models ware and ship production, while module construction lives separately in ModuleRecipes. Desired direction: module construction should eventually be represented in the same dependency graph, because station AI ultimately answers the same upstream-input question for production and module building. Focus review: ProductionGraphBuilder.cs, StaticDataProvider.cs, StaticDataProvider.cs, StaticDataProvider.cs
• Revisit the ship classifier helpers in SimulationRuntimeSupport. ShipPurpose is now part of ShipDefinition, but helpers like IsMiningShip, IsTransportShip, IsConstructionShip, and IsMilitaryShip still reason mostly from ShipType. Desired direction: use ShipPurpose as the primary role signal in those helpers, and use ShipType only for refinements where needed. Focus review: ShipPurpose, ShipDefinition.Purpose, SimulationRuntimeSupport.cs
• Revisit GetTotalCargoCapacity() and AI cargo assumptions. If ships can support multiple cargo kinds, AI should use the relevant cargo capacity for the current job instead of the total capacity across unrelated bays. Example: a mining ship with a dedicated fuel bay should not treat fuel storage as mined-ore capacity. Desired direction: remove or reduce GetTotalCargoCapacity() usage in AI paths that really need per-cargo-kind reasoning. Focus review: ShipDefinition cargo helpers, SimulationRuntimeSupport.cs, ShipAiService.Planning.Orders.cs, ShipAiService.Execution.cs
• Revisit the auth/account architecture boundary. The current auth stack is custom (repository, password flow, JWT issuance, reset flow) rather than using the more conventional ASP.NET Core Identity model. Desired direction: make an explicit architectural decision later about whether to keep owning this custom stack or align with the standard .NET Identity approach before external-provider growth. Focus review: AuthService.cs, PostgresAuthRepository.cs, HttpContextPlayerIdentityResolver.cs, Program.cs
• Revisit the runtime/domain mutation boundary for ships. Ship mutations like enqueueing orders, removing direct orders, and updating default behavior should eventually live closer to a focused ship-domain service rather than being split across WorldService and PlayerFactionService. Desired direction: keep runtime ship data compact and cache-friendly, but move ship mutation logic toward data-oriented ship services operating over the ship collection, instead of drifting into an anemic app-service model. Focus review: WorldService.cs, WorldService.cs, PlayerFactionService.cs, ShipAiService.cs
• Expand GM/entity editing beyond the current bootstrap loop. Focus review: WorldService.cs, WorldService.cs, GmOpsWindow.vue