Skip to content

Latest commit

 

History

History
89 lines (59 loc) · 3.43 KB

development-process.md

File metadata and controls

89 lines (59 loc) · 3.43 KB

Development Process

Status: active working process for the graybox phase. This document exists so implementation cadence, verification standards, and commit policy stay explicit instead of drifting between chat turns.

Working Method

Each milestone should follow the same order:

  1. inspect the current code and content shape before changing behavior
  2. update the active plan when the next milestone is clear
  3. make simulation-domain changes first when a rule or state model is involved
  4. keep the Bevy client as a consumer of simulation state, not a second rules engine
  5. run formatting, tests, and clippy before calling a milestone stable
  6. update docs and only then cut a commit

This keeps the repository deterministic-first and prevents UI work from silently redefining the game rules.

Verification Standard

A milestone is not considered stable until all of the following are true:

  • cargo fmt --all passes
  • cargo test passes for the full workspace
  • cargo clippy --workspace --all-targets -- -D warnings passes
  • cargo run -p app_headless is launch-checked for no-GPU environments
  • cargo run -p app_bevy is launch-checked as far as the current environment allows

If runtime launch is blocked by the environment, that limitation should be documented in the implementation plan and close-out.

Simulation-First Rule

When a feature touches any of these, it belongs in sim_core first:

  • placement legality
  • support rules
  • port compatibility
  • routing/network derivation
  • contamination behavior
  • objective evaluation
  • save/load semantics
  • deterministic command behavior

The client may visualize or inspect these rules, but it should not become the authoritative source for them.

Documentation Expectations

The repository should be updated alongside the code when milestone scope changes:

  • Implementation Plan: current completion state and next tasks
  • First Slice: intended prototype defaults
  • Decision Log: locked vs provisional decisions
  • README.md: brief operator-facing notes such as scenario selection or controls when they materially change

If the implementation diverges from the docs, either the code or the docs are wrong. Resolve it immediately rather than leaving it implicit.

Scenario additions need one more requirement:

  • add or update a scripted victory-path test in sim_core
  • document any new startup/scenario-selection behavior in README.md

Save/load changes need the same discipline:

  • rebuild derived state from authoritative fields on load when possible
  • add a regression test for continued deterministic behavior after load
  • reject invalid snapshots rather than silently accepting inconsistent derived data

Commit Policy

Commits should happen at stable milestone boundaries, not after every tiny edit.

Good commit boundaries:

  • a sim rule plus its tests
  • a client readability batch plus its documentation updates
  • a scenario/content expansion plus golden-path validation

Do not commit code that has not cleared the verification standard above.

Current Milestone Shape

The current graybox milestone order is:

  1. deterministic simulation foundation
  2. basic playable client shell
  3. diagnostics and connectivity readability
  4. contamination/support overlays and objective flexibility
  5. scenario breadth and internal playtest hardening

The next milestones should continue reducing playtest ambiguity before adding broad new content families.