initiative/specs/001-advance-turn/spec.md

Feature Specification: Advance Turn

Feature Branch: 001-advance-turn Created: 2026-03-03 Status: Draft Input: Walking-skeleton domain feature — deterministic turn advancement

User Scenarios & Testing (mandatory)

User Story 1 - Advance Turn (Priority: P1)

A game master running an encounter advances the turn to the next combatant in initiative order. When the last combatant in the round finishes, the round number increments and play wraps to the first combatant.

Why this priority: This is the irreducible core of an initiative tracker. Without turn advancement, no other feature has meaning.

Independent Test: Can be fully tested as a pure state transition with no I/O, persistence, or UI. Given an Encounter value and an AdvanceTurn action, assert the resulting Encounter value and emitted domain events.

Acceptance Scenarios:

1. Given an encounter with combatants [A, B, C], activeIndex 0, roundNumber 1, When AdvanceTurn, Then activeIndex is 1, roundNumber is 1, and a TurnAdvanced event is emitted with previousCombatantId A, newCombatantId B, roundNumber 1.

2. Given an encounter with combatants [A, B, C], activeIndex 1, roundNumber 1, When AdvanceTurn, Then activeIndex is 2, roundNumber is 1, and a TurnAdvanced event is emitted with previousCombatantId B, newCombatantId C, roundNumber 1.

3. Given an encounter with combatants [A, B, C], activeIndex 2, roundNumber 1, When AdvanceTurn, Then activeIndex is 0, roundNumber is 2, and events are emitted in order: TurnAdvanced (previousCombatantId C, newCombatantId A, roundNumber 2) then RoundAdvanced (newRoundNumber 2).

4. Given an encounter with combatants [A, B, C], activeIndex 2, roundNumber 5, When AdvanceTurn, Then activeIndex is 0, roundNumber is 6, and events are emitted in order: TurnAdvanced then RoundAdvanced (verifies round increment is not hardcoded to 2).

5. Given an encounter with a single combatant [A], activeIndex 0, roundNumber 1, When AdvanceTurn, Then activeIndex is 0, roundNumber is 2, and events are emitted in order: TurnAdvanced (previousCombatantId A, newCombatantId A, roundNumber 2) then RoundAdvanced (newRoundNumber 2).

6. Given an encounter with combatants [A, B], activeIndex 0, roundNumber 1, When AdvanceTurn is applied twice in sequence, Then after the first: activeIndex 1, roundNumber 1; after the second: activeIndex 0, roundNumber 2.

7. Given an encounter with an empty combatant list, When AdvanceTurn, Then the operation MUST fail with an invalid-encounter error. No events are emitted. State is unchanged.

8. Given an encounter with combatants [A, B, C], activeIndex 0, roundNumber 1, When AdvanceTurn is applied three times, Then the encounter completes a full round cycle: activeIndex returns to 0 and roundNumber is 2.

---

Edge Cases

• Empty combatant list: valid aggregate state, but AdvanceTurn MUST return a DomainError (no state change, no events).
• Single combatant: every advance wraps and increments the round.
• Large round numbers: no overflow or special-case behavior; round increments uniformly.

Clarifications

Session 2026-03-03

• Q: Should an encounter with zero combatants be a valid aggregate state? → A: Yes. Empty encounter is valid; AdvanceTurn returns DomainError.
• Q: What is activeIndex when combatants list is empty? → A: activeIndex MUST be 0.
• Q: Does this change any non-empty encounter behavior? → A: No. All existing acceptance scenarios and event contracts remain unchanged.

Domain Model (mandatory)

Key Entities

• Combatant: An identified participant in the encounter. For this feature, a combatant is an opaque identity (e.g., a name or id). The MVP baseline does not include HP, conditions, or stats.
• Encounter: The aggregate root. Contains an ordered list of combatants (pre-sorted by initiative), an activeIndex pointing to the current combatant, and a roundNumber (positive integer, starting at 1).

Domain Events

• TurnAdvanced: Emitted on every successful AdvanceTurn. Carries: previousCombatantId, newCombatantId, roundNumber.
• RoundAdvanced: Emitted when activeIndex wraps past the last combatant. Carries: newRoundNumber.

When a round boundary is crossed, both TurnAdvanced and RoundAdvanced MUST be emitted in that order (TurnAdvanced first). This emission order is part of the observable domain contract and MUST be verified by tests.

Invariants

• INV-1: An encounter MAY have zero combatants (an empty encounter is a valid aggregate state). AdvanceTurn on an empty encounter MUST return a DomainError with no state change and no events.
• INV-2: If combatants.length > 0, activeIndex MUST satisfy 0 <= activeIndex < combatants.length. If combatants.length == 0, activeIndex MUST be 0.
• INV-3: roundNumber MUST be a positive integer (>= 1) and MUST only increase (never decrease or reset).
• INV-4: AdvanceTurn MUST be a pure function of the current encounter state. Given identical input, output MUST be identical.
• INV-5: Every successful AdvanceTurn MUST emit at least one domain event (TurnAdvanced). No silent state changes.

Requirements (mandatory)

Functional Requirements

• FR-001: The domain MUST expose an AdvanceTurn operation that accepts an Encounter and returns the next Encounter state plus emitted domain events.
• FR-002: AdvanceTurn MUST increment activeIndex by 1, wrapping to 0 when past the last combatant.
• FR-003: When activeIndex wraps to 0, roundNumber MUST increment by 1.
• FR-004: AdvanceTurn on an empty encounter MUST return an error without modifying state or emitting events.
• FR-005: Domain events MUST be returned as values from the operation, not dispatched via side effects.

Out of Scope (MVP baseline does not include)

• Initiative rolling or combatant ordering logic
• Hit points, damage, conditions, or status effects
• Adding or removing combatants mid-encounter
• Persistence, serialization, or storage
• UI, CLI, or any adapter layer
• Agent behavior or suggestions

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: All 8 acceptance scenarios pass as deterministic, pure-function tests with no I/O dependencies.
• SC-002: Invariants INV-1 through INV-5 are verified by tests.
• SC-003: The domain module has zero imports from application, adapter, or agent layers (layer boundary compliance).