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: `33/33` in `tests/ReactorMaintenance.Simulation.Tests`.
- Existing tests cover older behavior. They are useful regression scaffolding, but they do not prove the latest design rules.
- The simulation has a working `SimulationEngine`, network propagation, consumers, structural integrity, leaks, reactor readiness, forecasts, serialization, editor helpers, and Godot session bridge.
- Godot currently has a usable UX scaffold and grid renderer, but it still exposes older interaction concepts such as a player-facing `EndTurn` action and always-available underground layer controls.
- Existing campaign data is the older three-level placeholder set: `coolant_restart.json`, `fuel_bleed.json`, and `black_start.json`. 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 `Step`s.
  - 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 `QuickAction`s.
  - `InteractProp`, `InteractLeak`, `ApplyHeatShield`, and accepted powered-prop no-op interactions are `LengthyAction`s.
  - `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 `CoolantSprinklerValve`.
  - A `SprinklerControlProp` links to exactly one `CoolantSprinklerValve`.
  - The valve is wall-mounted, not directly interactive, and has exactly one outlet/access floor face.
  - Discharge creates `SprinklerWater` only while linked control is `Enabled` and the coolant branch is fed.
  - Discharge applies deterministic local coolant pressure debt.
  - Add editor placement/linking, validation, serialization, and rendering support.
- [ ] Rework surface coolant into `SprinklerWater`.
  - Rename code-facing concepts where practical; otherwise make names and UI text consistently mean sprinkler water, not a generic coolant hazard.
  - `Coolant` pipe failures should inject `SprinklerWater`, not a second damaging liquid.
  - `SprinklerWater` 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 coolant 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 `SprinklerWater` 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 `SprinklerWater` 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`, `SprinklerWater`, `Unsafe`, and `ReactorReadiness` terminology.
- [ ] Add tests for fixed pulse length.
  - Every accepted `LengthyAction` advances one `Pulse`.
  - Each pulse resolves the configured number of `Step`s.
  - `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 `CoolantSprinklerValve`.
  - Valve discharge requires a linked enabled control and fed coolant branch.
  - Direct valve interaction is invalid or unavailable.
  - Discharge creates `SprinklerWater` 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, coolant, 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.
  - `SprinklerWater` dilutes `LeakedFuel`.
  - `SprinklerWater` 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.
  - `CoolantSprinklerValve` wall position, outlet/access face, linked control, and coolant 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, coolant 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 `Step`s.
  - 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 `SprinklerWater` separately from underground `Coolant`.
  - 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 `SprinklerWater`, `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.