(pre-development) Stars! PBeM service on Kubernetes
Define Stage 4 acceptance criteria and risk controls
+56
-4
+56
-4
doc/total-host.codex.md
+56
-4
doc/total-host.codex.md
···
1
-
# total-host.codex: Stage 1 + Stage 2 + Stage 3 Product Requirements
1
+
# total-host.codex: Stage 1 + Stage 2 + Stage 3 + Stage 4 Product Requirements
2
2
3
-
This document contains Stage 1 through Stage 3 of a staged product specification for TotalHost-compatible host behavior.
3
+
This document contains Stage 1 through Stage 4 of a staged product specification for TotalHost-compatible host behavior.
4
4
5
-
Stage 1 defines domain behavior and invariants. Stage 2 defines capability inventory, prioritization, and the first usable release boundary. Stage 3 defines architecture-level product contracts and boundary requirements.
5
+
Stage 1 defines domain behavior and invariants. Stage 2 defines capability inventory, prioritization, and the first usable release boundary. Stage 3 defines architecture-level product contracts and boundary requirements. Stage 4 defines acceptance criteria and risk requirements for MVP validation.
6
6
7
7
It intentionally avoids implementation structure, crate boundaries, and execution planning.
8
8
···
241
241
- consistency and security boundary rules that protect Stage 1 invariants
242
242
- architecture contracts that can be mapped to implementation in later stages
243
243
244
+
## Stage 4 Goal
245
+
246
+
Define objective, testable acceptance criteria for MVP behavior and capture major product risks with required controls.
247
+
248
+
## Stage 4 Acceptance Criteria
249
+
250
+
### A) Setup and Lifecycle Progression
251
+
252
+
- `AC-001` A game initialized with valid setup artifacts can transition from `setup` to `accepting-submissions` without manual artifact correction. Maps to: `LIF-02`, `ART-01`, `CAP-101`.
253
+
- `AC-002` A game cannot transition to active play when required setup artifacts fail validation, and rejection diagnostics are visible to operators. Maps to: `LIF-02`, `VAL-01`, `VAL-05`, `CAP-102`.
254
+
- `AC-003` Lifecycle transitions are externally visible in correct order (`accepting-submissions` -> `generation-locked` -> `generating` -> `distribution`) for a successful turn. Maps to: `LIF-01`, `LIF-04`, `LIF-06`, `ARC-002`, `CNS-001`.
255
+
256
+
### B) Submission, Validation, and Lock Behavior
257
+
258
+
- `AC-101` A player can submit and replace `.x` orders for the current open turn; only the final validated submission is effective at lock. Maps to: `LIF-03`, `OWN-03`, `OWN-04`, `CAP-001`, `CAP-002`.
259
+
- `AC-102` Submission attempts with wrong game identity, wrong player identity, stale turn, or locked turn are rejected with stable reason codes. Maps to: `VAL-02`, `VAL-03`, `VAL-04`, `VAL-05`, `IFC-002`.
260
+
- `AC-103` Equivalent retry submission patterns produce deterministic lock outcomes. Maps to: `INV-03`, `CNS-004`.
261
+
262
+
### C) Generation Success and Failure Handling
263
+
264
+
- `AC-201` On successful generation, turn number increments exactly once and new authoritative state is bound with player outputs. Maps to: `LIF-06`, `INV-01`, `CNS-002`, `CAP-003`.
265
+
- `AC-202` On generation failure, prior authoritative state remains intact and the game enters a recoverable failure condition with diagnostics. Maps to: `LIF-07`, `INV-05`, `CNS-003`, `CAP-004`.
266
+
- `AC-203` Pause/delay controls prevent unintended turn advancement while preserving accepted submissions. Maps to: `LIF-08`, `CAP-005`.
267
+
268
+
### D) Distribution, Isolation, and Access Control
269
+
270
+
- `AC-301` Each player receives only their own `.m` and `.h` outputs for the generated turn. Maps to: `DST-01`, `INV-04`, `CAP-201`, `SEC-001`.
271
+
- `AC-302` Host-authoritative artifacts are not exposed through player-facing interfaces. Maps to: `DST-02`, `SEC-002`.
272
+
- `AC-303` Distribution progress and failures are visible per player with explicit states. Maps to: `DST-03`, `CAP-202`, `IFC-005`.
273
+
274
+
### E) Observability and Traceability Validation
275
+
276
+
- `AC-401` Core lifecycle actions emit OpenTelemetry traces with correlation identifiers sufficient to reconstruct one full turn flow. Maps to: `OBS-01`, `OBS-02`, `OBS-05`.
277
+
- `AC-402` Requirement IDs used in acceptance criteria are traceable to implementation and verification evidence in machine-readable form. Maps to: `TRC-01`, `TRC-02`, `TRC-03`, `TRC-04`, `TRC-05`.
278
+
- `AC-403` Provisional trace semantic mappings can be related to emerging ATProto lexicon terms without renaming requirement IDs. Maps to: `OBS-03`, `OBS-04`.
279
+
280
+
## Stage 4 Risk Register and Required Controls
281
+
282
+
- `RSK-001` **Submission race conditions near lock** may cause non-deterministic outcomes. Required control: deterministic lock semantics and idempotent replacement behavior. Maps to: `OWN-04`, `INV-03`, `CNS-004`.
283
+
- `RSK-002` **State corruption during failed generation** may block campaigns. Required control: non-destructive failure handling and recoverable state transitions. Maps to: `LIF-07`, `INV-05`, `CNS-003`, `CAP-004`.
284
+
- `RSK-003` **Player data leakage** may occur through distribution or diagnostics. Required control: strict player isolation and host artifact access boundaries. Maps to: `INV-04`, `DST-02`, `SEC-001`, `SEC-002`.
285
+
- `RSK-004` **Operational blind spots** may delay incident response. Required control: auditable events, correlated OTel traces, and operator diagnostics. Maps to: `NFR-01`, `NFR-02`, `OBS-01`, `OBS-02`, `CAP-302`.
286
+
- `RSK-005` **Traceability drift** may undermine confidence in requirement coverage. Required control: machine-readable trace reports integrated into normal validation workflows. Maps to: `TRC-02`, `TRC-04`, `TRC-05`.
287
+
288
+
## Stage 4 Deliverables
289
+
290
+
Stage 4 is complete when this document provides:
291
+
292
+
- a testable acceptance criteria set covering all Stage 2 `MVP` capabilities
293
+
- explicit requirement mapping from acceptance checks to normative requirement IDs
294
+
- a risk register with required controls tied to existing requirement IDs
295
+
- clear readiness input for Stage 5 implementation planning
296
+
244
297
## Deferred to Later Stages
245
298
246
299
- traceability implementation design (annotation format, report shape, CI policy)
247
300
- ATProto lexicon definition details and exact telemetry field mapping
248
301
- implementation plan, task breakdown, and execution order
249
-
- detailed acceptance test matrix and risk mitigation plan
250
302
251
303
## References
252
304