zfxaction26_2/TASKS.md

# Reactor Maintenance Tasks

This backlog tracks procedural level generation, reusable exhaustive solving, Godot random play, and Godot-assisted campaign authoring automation.

## Audit Snapshot

- Current simulation tests pass: `60/60` in `tests/ReactorMaintenance.Simulation.Tests`.
- Godot level play includes pulse step playback, terminal-gated layer controls, campaign loading, and in-game level editing with JSON save.
- Campaign data follows the tutorial plus six-group campaign from `docs/CAMPAIGN.md`.
- The next implementation replaces the placeholder random-level flow with seed-driven generation and reusable solver analysis.
- Win2D is not part of this backlog.

## P0 Generator Contract

- [ ] Add a parameterized `LevelGenerationRequest`.
  - Include `Seed`, display name, optional max dimensions, `SolverDepthLimit`, target complexity, and `MaxAttempts`.
  - Require `InvolvedSystems` to contain at least one of `Fuel`, `Water`, or `Electricity`.
  - Specify exact available consumer counts per involved carrier.
  - Specify exact required consumer counts per involved carrier.
  - Specify the exact carrier set directly connected to the reactor control.
  - Reject impossible specs before generation, including required consumers greater than available consumers.
- [ ] Add a player-facing seed profile expander.
  - Use the seed to choose involved systems.
  - Use the seed to choose available consumer counts.
  - Use the seed to choose required consumers as none, some, or all of the placed consumers.
  - Use the seed to choose how many involved systems directly connect to the reactor.
  - Expand to a concrete `LevelGenerationRequest` so random play and authoring use one generator path.
- [ ] Generate levels without fixed archetypes.
  - Compose generated content from the requested systems, consumers, reactor connectivity, and difficulty target.
  - Avoid named campaign-group archetypes as public generation modes.
  - Let multi-system hazards emerge from generated overlapping fuel, water, electricity, heat, leak, sprinkler, and powered-prop placements.
- [ ] Grow levels organically from the reactor.
  - Start the generated graph at the `ReactorControlProp`.
  - Grow carrier networks, branches, rooms, corridors, access routes, and player decision points outward from the reactor graph.
  - Place surrounding walls after gameplay geometry exists.
  - Calculate the occupied bounding box after generation.
  - Offset all coordinates into positive level space before creating final arrays.
  - Preserve valid wall geometry for doors, wall electricity leaks, and wall-mounted sprinkler valves.
- [ ] Generate structural-integrity and pressure interactions.
  - Author weakened underground segments with controlled pressure or voltage exposure.
  - Generate pressure-fed and voltage-fed leaks that can be isolated, repaired, or allowed to worsen.
  - Generate hazards that restrict movement through `Unsafe` heat, electricity, or wet-electric combinations.
  - Include pressure tradeoffs from sprinkler discharge and consumer/reactor starvation.
  - Ensure generated hazards are reachable, readable, and tied to player choices.

## P0 Reusable Solver

- [ ] Add a reusable `LevelSolver` in the simulation project.
  - Accept a `LevelState` and `SolverRequest`.
  - Return a `SolverReport` with terminal counts, complexity metrics, diagnostics, and representative traces.
  - Keep the solver independent from Godot so generator, editor, tests, and future tools can share it.
- [ ] Define solver choices as reachable lengthy actions.
  - Collapse quick movement into safe reachability from the current robot position.
  - Enumerate all reachable prop interactions, leak repairs, remedy uses, heat shield uses, and reactor activation attempts.
  - Exclude inspection, selection, terminal viewing, and individual quick movement branches from primary metrics.
  - Sort canonical choices deterministically before evaluation.
- [ ] Evaluate every bounded branch.
  - Explore all possible choice permutations to the configured lengthy-action depth limit.
  - Count `Win`, `Lose`, and `Inconclusive` leaves.
  - Mark branches inconclusive when the depth limit or timeout is reached before terminal outcome.
  - Treat no-choice non-ready states as losing dead ends.
  - Preserve exact branch counts while using transposition caching to avoid duplicate expansion work.
- [ ] Add solver complexity metrics.
  - Report min and max player choices to win.
  - Report min and max player choices to loss.
  - Report max and average available choices per decision state.
  - Report lose/win ratio across all bounded permutations.
  - Report inconclusive ratio.
  - Report explored node count and cache hit count.
  - Provide representative shortest winning and losing traces.
- [ ] Parallelize branch evaluation.
  - Issue all canonical choices from a state in parallel when budget allows.
  - Wait for all choice evaluations from that state.
  - Aggregate results in canonical order for deterministic diagnostics.
  - Use ThreadPool or TPL work stealing for nested parallel branch work.
  - Respect max parallelism, timeout, and cancellation.
- [ ] Keep solver performance and memory usage controlled.
  - Clone level states only at branch boundaries.
  - Add per-thread reusable buffers or `LevelState` clone pools where practical.
  - Avoid retaining full state graphs when only metrics are needed.
  - Keep only bounded representative traces.
  - Evaluate whether `record struct` or other value-oriented refactors reduce heap pressure without harming maintainability.
  - Add allocation or stress tests for representative generated levels.

## P1 Generation Acceptance And Difficulty

- [ ] Validate every generated candidate.
  - Run `LevelValidator`.
  - Run bounded solver analysis.
  - Reject candidates with validation errors.
  - Reject candidates with no winning branch.
  - Reject candidates whose required systems, consumer counts, or reactor-connected carrier set do not exactly match the request.
  - Reject candidates whose hazards cannot affect movement or meaningful decisions.
- [ ] Add difficulty target filtering.
  - Filter by minimum and maximum choices to win.
  - Filter by maximum and average available choices.
  - Filter by lose/win ratio range.
  - Filter by maximum inconclusive ratio.
  - Filter by required first-choice variety.
  - Make defaults suitable for random play and configurable for campaign authoring.
- [ ] Support campaign progression targets.
  - Early targets use fewer involved systems, lower available-choice counts, and low lose/win ratios.
  - Mid targets increase first-choice variety and introduce more losing branches.
  - Late targets allow more systems, more branching, higher lose/win ratio, and lower inconclusive tolerance.
  - Make target definitions data-driven enough for campaign automation scripts or Godot UI.
- [ ] Add diagnostics for rejected candidates.
  - Report invalid spec reasons.
  - Report validation errors and warnings.
  - Report solver failure reasons.
  - Report mismatch against requested systems, consumers, reactor feeds, and complexity target.
  - Keep diagnostics concise enough for Godot UI and detailed enough for tests.

## P1 Godot Random Play And Authoring Automation

- [ ] Replace placeholder random-level flow.
  - Generate a level from a player seed profile.
  - Save generated JSON under `user://generated/`.
  - Load generated levels through `LevelStateLoader`.
  - Retry the same generated level from the saved JSON.
  - Complete random levels by returning to generation or regenerating from a new seed.
- [ ] Add authoring controls to `GenerationScreen`.
  - Toggle involved systems.
  - Set available consumers per carrier.
  - Set required consumers per carrier.
  - Toggle reactor-connected carriers.
  - Set seed, max attempts, solver depth limit, and target complexity.
  - Generate, regenerate, analyze, save JSON, begin play, and return to menu.
- [ ] Surface solver metrics in Godot.
  - Show win, lose, and inconclusive counts.
  - Show min and max choices to win.
  - Show max and average available choices.
  - Show lose/win ratio and inconclusive ratio.
  - Show concise representative trace summaries for authoring review.
- [ ] Reuse generated JSON in Godot editor mode.
  - Open generated levels in `LevelScreen`.
  - Allow normal edit-mode changes.
  - Validate and save back to the generated JSON path.
  - Preserve generated metadata needed for retry and review.
- [ ] Keep Godot generation responsive.
  - Run generation and solver analysis off the main UI path.
  - Show progress, cancellation, and failure diagnostics.
  - Prevent starting a stale or failed generated candidate.

## P1 Tests

- [ ] Add generator determinism tests.
  - Same request and seed serialize to identical JSON.
  - Different seeds produce meaningfully different layouts for the same request.
  - Player seed profile expansion is deterministic.
- [ ] Add generation spec-compliance tests.
  - Generated involved systems match the request exactly.
  - Available consumer counts match the request exactly.
  - Required consumer counts match the request exactly.
  - Reactor-connected carriers match the request exactly.
  - Organic bounding and coordinate offset produce valid positive coordinates and correct array sizes.
- [ ] Add generated hazard tests.
  - Generated pressure-fed leaks inject only when fed.
  - Structural-integrity hazards can create or worsen leaks under generated pressure or voltage.
  - Generated hazards can restrict movement through `Unsafe` rules.
  - Generated sprinkler pressure debt can affect consumer or reactor service.
- [ ] Add solver correctness tests.
  - Known tiny levels report expected win, lose, and inconclusive counts.
  - Depth-limited branches become inconclusive.
  - No-choice non-ready states count as losing dead ends.
  - Canonical action ordering produces stable diagnostics.
  - Parallel and single-threaded solver runs produce identical reports.
- [ ] Add solver performance tests.
  - Branch-heavy generated samples finish within the configured timeout.
  - Representative solving does not retain unbounded traces.
  - Clone or pooling behavior does not leak mutable state across branches.
- [ ] Add Godot integration coverage where practical.
  - Generated JSON loads through `LevelStateLoader`.
  - Generated JSON saves through the existing level save path.
  - `FrontendSession` can point random mode at generated JSON.

## P2 Documentation And Tooling

- [ ] Update `docs/design.md`.
  - Document procedural generation inputs.
  - Document solver outcomes and metrics.
  - Document generated structural-integrity and pressure-hazard expectations.
  - Document random play seed behavior.
- [ ] Update `docs/UX.md`.
  - Replace placeholder random-level wording.
  - Describe generation controls, authoring controls, metrics display, progress, cancellation, and failure states.
  - Describe generated JSON editing and save-back flow.
- [ ] Add authoring guidance.
  - Explain how generated levels can be promoted into campaign candidates.
  - Explain how increasing choices and lose/win ratio supports campaign progression.
  - Explain recommended solver depth and target complexity ranges.
- [ ] Keep task status current.
  - Check off items as implementation lands.
  - Remove outdated task text instead of adding past-tense prose.
  - Keep verification commands aligned with repo instructions.

## Verification Rules

- [ ] Run focused solver and generator tests after solver or generation changes.
- [ ] Run full `dotnet test` before committing simulation, serializer, or generated-data changes.
- [ ] Run `dotnet build ReactorMaintenance.slnx --no-restore` and `dotnet test ReactorMaintenance.slnx --no-restore` sequentially.
- [ ] For code changes on Windows, run `python D:\Code\crlf.py` for recognized touched files.
- [ ] For code changes on Windows, run `jb cleanupcode --verbosity:ERROR ReactorMaintenance.slnx`.
- [ ] For documentation-only iterations, no cleanup pass is required.
- [ ] Commit each completed iteration with a brief summary.