feat: gamemaster

2026-05-03 07:59:03 +02:00
parent a7cee15115
commit 3e2622757e
229 changed files with 41521 additions and 1098 deletions
@@ -0,0 +1,62 @@
+# Stage 01 — Architecture sync
+
+This decision record captures the non-obvious choice from
+[`../PLAN.md` Stage 01](../PLAN.md#stage-01-update-architecturemd):
+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](../PLAN.md)
+- [`../../ARCHITECTURE.md` §7 Game Lobby](../../ARCHITECTURE.md)
+- [`../../ARCHITECTURE.md` §8 Game Master](../../ARCHITECTURE.md)
+- [`../README.md`](../README.md) — `player_turn_stats[]` description.