zfxaction26_2/TASKS.md

Reactor Maintenance Tasks

This backlog tracks what must change so the implementation matches docs/design.md, docs/UX.md, and docs/CAMPAIGN.md.

Audit Snapshot

• Current simulation tests pass: 54/54 in tests/ReactorMaintenance.Simulation.Tests.
• Godot has a usable UX scaffold and grid renderer; the full pulse playback, terminal-gated layer controls, and campaign content pass remain in later tasks.
• Existing campaign data is the older placeholder set. These levels and manifest entries must be replaced by the tutorial plus six-group campaign from docs/CAMPAIGN.md.
• Unrelated Godot metadata or generated .uid files are not part of this backlog unless a later implementation task intentionally touches them.

P0 Simulation Contract

• Rename the public environment tick model from turn-based AdvanceTurn/EndTurn semantics to Pulse semantics.
  • One accepted LengthyAction triggers exactly one Pulse.
  • One Pulse contains a fixed balance-defined number of deterministic Steps.
  • The fixed step count must not vary by action type, forecast result, or danger level.
  • Keep isolated step or pulse advancement available only for tests, editor tooling, or debug use.
• Remove player-facing wait/fast-forward behavior from normal gameplay.
  • MoveRobot, selection, inspection, and terminal layer viewing remain QuickActions.
  • InteractProp, InteractLeak, ApplyHeatShield, and accepted powered-prop no-op interactions are LengthyActions.
  • ActivateReactor wins when ReactorReadiness is true and must not require a separate wait.
• Add IsolationValveProp as a first-class prop.
  • Store carrier binding and Open/Closed state.
  • Block intentional underground propagation across the authored branch boundary.
  • Preserve downstream starvation/readiness consequences for consumers and reactor feed.
  • Add editor placement, validation, serialization, and rendering support.
• Add SprinklerControlProp and wall-mounted SprinklerValve.
  • A SprinklerControlProp links to exactly one SprinklerValve.
  • The valve is wall-mounted, not directly interactive, and has exactly one outlet/access floor face.
  • Discharge creates Water only while linked control is Enabled and the water branch is fed.
  • Discharge applies deterministic local water pressure debt.
  • Add editor placement/linking, validation, serialization, and rendering support.
• Rework surface water into Water.
  • Rename code-facing concepts where practical; otherwise make names and UI text consistently mean water, not a generic hazard.
  • water pipe failures should inject Water, not a damaging liquid.
  • Water alone must not cause UnsafeEntryLoss.
• Update leak injection.
  • Leaks inject only when the underground leak cell has positive amount and positive pressure/voltage after propagation.
  • Isolating a leak stops fresh injection without repairing the underlying fault.
  • Repair restores structural integrity and stops future injection but does not clean existing surface values.
• Implement the approved surface interaction order.
  • Resolve leak/sprinkler injection per Step.
  • Resolve water mitigation before ignition and electrical spread.
  • Implement Dilute, Quench, value-based Evaporate, wet-electric Conduct, and Ignite.
  • Preserve deterministic same-cell and adjacent-cell delta accumulation.
  • Closed powered doors and remedy blocks must gate only the interactions they explicitly block.
• Implement value-based evaporation.
  • Add balance values for ambient evaporation, heat-driven evaporation, and evaporation cooling.
  • Hot cells should evaporate Water faster than cold cells.
  • Evaporation happens during useful action pulses; there is no campaign wait command.
• Implement Unsafe as derived movement safety.
  • Unsafe is recalculated after authored setup and after each Pulse.
  • Unsafe is caused by unsafe Heat, unsafe LeakedElectricity, or the wet-electric unsafe rule.
  • LeakedFuel alone and Water alone are not Unsafe.
  • UnsafeEntryLoss happens only when MoveRobot enters an Unsafe destination without applicable protection.
  • A Pulse must not kill a stationary robot just because the current cell becomes Unsafe.
• Implement powered prop behavior.
  • DoorProp and AllSeeingEyeTerminal require positive local electricity amount and voltage for their interactions to take effect.
  • Interacting with an unpowered PoweredProp is accepted as a LengthyAction, changes no prop state, reveals no terminal information, and still triggers one Pulse.
  • Powered doors keep their last physical open/closed state when power is lost.
• Gate all-seeing-eye information.
  • Underground topology, numeric underground values, and Forecast output are visible only while the robot is at an active and powered AllSeeingEyeTerminal.
  • Terminal access is local and does not persist after the robot leaves.
  • Forecasts are systemic simulations over copied state, never authored level prose.
• Update ReactorReadiness checks as the invariant source of victory.
  • Every network present beneath ReactorControlProp must have positive amount and intensity.
  • Required per-carrier consumer counts must be Enabled and Producing.
  • Missing readiness blocks Ready but does not directly cause Lost.

P0 Simulation Tests

• Update existing tests so their names and assertions use Pulse, Step, Water, Unsafe, and ReactorReadiness terminology.
• Add tests for fixed pulse length.
  • Every accepted LengthyAction advances one Pulse.
  • Each pulse resolves the configured number of Steps.
  • MoveRobot and inspection-like calls do not resolve a pulse.
• Add tests for no normal wait/fast-forward dependency.
  • Player-facing session/action APIs should not require EndTurn to reach readiness after a lengthy action.
  • Debug/test-only pulse advancement, if retained, must be clearly named and excluded from campaign UI.
• Add tests for IsolationValveProp.
  • Open valve allows branch propagation.
  • Closed valve isolates damaged branches and can starve downstream consumers/reactor feed.
  • Toggling a valve triggers exactly one Pulse.
• Add tests for SprinklerControlProp and SprinklerValve.
  • Valve discharge requires a linked enabled control and fed water branch.
  • Direct valve interaction is invalid or unavailable.
  • Discharge creates Water at the authored outlet and applies pressure debt.
  • Disabling the linked control or isolating the sprinkler branch stops fresh discharge.
• Add tests for updated leak injection.
  • Fed fuel, water, and electricity leaks inject to the correct access face.
  • Isolated leaks stop new surface injection.
  • Repairs restore structural integrity without cleaning existing surface values.
• Add tests for surface interactions.
  • Water dilutes LeakedFuel.
  • Water quenches Heat.
  • Evaporation removes water and cools heat according to balance values.
  • Wet cells conduct electricity faster than dry cells.
  • Fuel plus electricity or heat can ignite and create heat while consuming fuel.
  • Closed doors block designed surface propagation paths.
• Add tests for Unsafe.
  • Moving into unsafe heat loses without active heat protection.
  • Moving into unsafe electricity loses.
  • Moving into wet-electric unsafe cells loses.
  • Moving into fuel-only or sprinkler-water-only cells does not lose.
  • A pulse that makes the robot's current cell unsafe does not immediately lose.
• Add tests for powered props.
  • Powered door toggles and blocks/unblocks surface propagation.
  • Unpowered door interaction changes no door state but still triggers a pulse.
  • Powered terminal interaction enables local visibility and forecasts.
  • Unpowered terminal interaction reveals nothing and still triggers a pulse.
  • Leaving the terminal removes underground/forecast visibility.
• Add tests for campaign authoring invariants.
  • Every campaign level loads and validates.
  • Tutorial is solvable with exactly one LengthyAction before ActivateReactor.
  • Every non-tutorial level has at least two valid first LengthyAction choices.
  • No campaign level requires a wait/fast-forward command.
  • No level before 3-2 requires underground visibility to understand the intended first decisions.
  • Campaign manifest order matches docs/CAMPAIGN.md.

P1 Editor, Schema, And Level Data

• Bump the level schema version when adding new prop/link/outlet state.
• Update serialization round trips for new fields.
  • IsolationValveProp carrier and open/closed state.
  • SprinklerControlProp enabled/disabled state and linked valve id or position.
  • SprinklerValve wall position, outlet/access face, linked control, and water connection.
  • Powered terminal active state if it becomes serialized runtime state.
• Update LevelEditor tools.
  • Add isolation valve placement.
  • Add sprinkler control placement.
  • Add wall-mounted sprinkler valve placement and outlet/access cycling.
  • Keep electricity leak wall access cycling.
  • Prevent invalid prop placement on walls except designed wall-mounted sprinkler valves.
• Update LevelValidator.
  • Validate powered doors have valid geometry and local electricity.
  • Validate terminal power requirements where needed.
  • Validate wall-mounted sprinkler valve geometry, outlet/access face, water connection, and exactly one linked control.
  • Validate isolation valves sit on exactly one matching underground carrier.
  • Warn on initially unready reactors, initially starved required consumers, unused supplies, and sprinkler valves with no useful suppression or pressure tradeoff.
• Replace placeholder campaign files.
  • Create tutorial plus Groups 1-6 from docs/CAMPAIGN.md.
  • Update default_campaign_manifest.json to the final order.
  • Remove or demote old placeholder levels so they are not presented as campaign content.
  • Add stable ids and short flavor text for every authored level.
• Add test/build helpers for level construction.
  • Prefer shared builders for linear networks, forks, leaks, wall electricity faces, doors, controls, consumers, and reactors.
  • Avoid duplicating low-level array setup across tests.

P1 Godot UX Integration

• Remove player-facing End Turn from the normal action bar.
  • Replace it with contextual LengthyAction commands and ActivateReactor when ready.
  • Keep any debug pulse control behind an explicit development-only path.
• Update GameSession API names and events to match pulse semantics.
  • Use PulseAdvanced or equivalent instead of TurnAdvanced.
  • Ensure accepted no-op powered-prop interactions still notify pulse playback.
  • Ensure refused invalid actions do not mutate state or trigger pulse playback.
• Animate Pulse playback as a short cascade of Steps.
  • Show leak growth, sprinkler discharge, evaporation, quenching, ignition, wet conduction, and readiness updates.
  • Disable conflicting inputs during playback.
  • End playback on the final post-pulse decision state.
• Gate underground layer controls and forecasts.
  • Hide or disable layer toggles unless the robot is at an active and powered AllSeeingEyeTerminal.
  • Show why terminal access is unavailable when unpowered or away from the terminal.
  • Use Pulse +N wording in forecast UI.
• Update grid rendering and inspector text.
  • Render Water separately from underground water.
  • Render Unsafe cells with a distinct movement warning treatment.
  • Render isolation valve state, sprinkler control state, wall-mounted sprinkler outlet, powered door state, and powered terminal state.
  • Inspector should display visible surface values, prop state, consumer per-carrier state, and underground values only when terminal access allows it.
• Update action affordances.
  • Movement remains direct and quick.
  • Prop interactions should explain unavailable power, invalid position, missing remedy, depleted supply, and reactor-not-ready causes.
  • Disabled actions remain inspectable so players can understand why an action is unavailable.

P2 Polish And Release Tasks

• Add concise pulse-result feedback for major outcomes: isolated leak, restored pressure, downstream starvation, reactor ready, wet-electric risk, and terminal heat danger.
• Add campaign completion flow for the final Group 6 level.
• Add loading and malformed-level error states for campaign level loading.
• Verify Win2D editor export and Godot loader compatibility for the new schema.
• Revisit art labels/icons for Water, Unsafe, powered props, and sprinkler controls after mechanics are implemented.

Verification Rules

• After each implementation iteration, run the focused simulation tests that cover the changed system.
• Run full dotnet test before committing simulation or serializer changes.
• For code changes on Windows, run the repo-required CRLF normalization and cleanup steps after implementation.
• For documentation-only iterations, no cleanup pass is required.
• Keep documentation aligned whenever code changes terminology or behavior.
• Commit each completed iteration with a brief summary.