galaxy-game/gamemaster/docs/stage01-architecture-sync.md

Stage 01 — Architecture sync

This decision record captures the non-obvious choice from ../PLAN.md Stage 01: the drop of ships_built from every architectural mention of player_turn_stats.

Context

Before Stage 01, ARCHITECTURE.md and lobby/README.md described player_turn_stats as carrying {user_id, planets, population, ships_built}, and the Race Name Directory capability rule was wired in prose as if ships_built could affect the outcome. In practice, the formal capability rule was already max_planets > initial_planets AND max_population > initial_population — ships_built was named in the stats payload but never referenced by the rule.

Decision

player_turn_stats carries {user_id, planets, population} only. ships_built is removed from:

• ARCHITECTURE.md §8 Game Master — runtime_snapshot_update payload description.
• ARCHITECTURE.md §7 Game Lobby — per-member aggregate description (current and running-max of planets and population).
• gamemaster/README.md — already aligned at the stage-02 README freeze.

The capability rule wording is unchanged because it was already planets/population-only; only the surrounding prose mentioning the unused field was inaccurate.

This is a documentation-only change. No runtime behaviour, wire format, schema, or test fixture is affected.

Why

ships_built was unused. Naming it in the contract obliged every producer (GM) and consumer (Lobby aggregator) to populate and forward a field with no consumer. Dropping it now — before any GM code lands — keeps the contract minimal and avoids future drift between "what the spec lists" and "what the code uses". lobby/README.md and the lobby aggregate code are aligned in Stage 03 of the same plan.

Alternatives considered

• Keep ships_built in the contract for future use. Rejected: no concrete plan exists for a ships_built-driven capability or stat surface; speculative fields rot.
• Add ships_built only as an opaque stat without changing the capability rule. Rejected: the runtime cost of carrying it is negligible, but the documentation burden of explaining why an unused field is in the payload is not.

References

• ../PLAN.md Stage 01
• ../../ARCHITECTURE.md §7 Game Lobby
• ../../ARCHITECTURE.md §8 Game Master
• ../README.md — player_turn_stats[] description.