Feature Specification: Remove Combatant

Feature Branch: 003-remove-combatant Created: 2026-03-03 Status: Draft Input: User description: "RemoveCombatant: allow removing a combatant by id from Encounter (adjust activeIndex correctly, keep roundNumber, emit CombatantRemoved, error if id not found) and wire through application + minimal UI."

User Scenarios & Testing (mandatory)

User Story 1 - Remove a Combatant from an Active Encounter (Priority: P1)

A game master is running a combat encounter and a combatant is defeated or leaves. The GM removes that combatant by clicking a remove action. The combatant disappears from the initiative order and the turn continues correctly without disruption.

Why this priority: Core functionality — removing combatants is the primary purpose of this feature and must work correctly to maintain encounter integrity.

Independent Test: Can be fully tested by adding combatants to an encounter, removing one, and verifying the combatant list, activeIndex, and roundNumber are correct.

Acceptance Scenarios:

Given an encounter with combatants [A, B, C] and activeIndex 1 (B's turn), When the GM removes combatant C (index 2, after active), Then the encounter has [A, B], activeIndex remains 1, roundNumber unchanged, and a CombatantRemoved event is emitted.
Given an encounter with combatants [A, B, C] and activeIndex 2 (C's turn), When the GM removes combatant A (index 0, before active), Then the encounter has [B, C], activeIndex becomes 1 (still C's turn), roundNumber unchanged.
Given an encounter with combatants [A, B, C] and activeIndex 1 (B's turn), When the GM removes combatant B (the active combatant), Then the encounter has [A, C], activeIndex becomes 1 (C is now active — the next combatant takes over), roundNumber unchanged.
Given an encounter with combatants [A, B, C] and activeIndex 2 (C's turn, last position), When the GM removes combatant C (active and last), Then the encounter has [A, B], activeIndex wraps to 0 (A is now active), roundNumber unchanged.
Given an encounter with combatants [A] and activeIndex 0, When the GM removes combatant A, Then the encounter has [], activeIndex is 0, roundNumber unchanged.
Given an encounter with combatants [A, B, C], When the GM attempts to remove a combatant with an ID that does not exist, Then a domain error is returned with a descriptive error code, and the encounter is unchanged.

User Story 2 - Remove Combatant via UI (Priority: P2)

A game master sees a list of combatants in the encounter UI. Each combatant has a remove action. Clicking it removes the combatant and the UI updates to reflect the new initiative order.

Why this priority: Provides the user-facing interaction for the core domain functionality. Without UI, the feature is not accessible.

Independent Test: Can be tested by rendering the encounter UI, clicking the remove action on a combatant, and verifying the combatant disappears from the list.

Acceptance Scenarios:

Given an encounter with combatants displayed in the UI, When the GM clicks the remove action on a combatant, Then that combatant is removed from the displayed list.
Given an encounter displayed in the UI, When a removal results in a domain error (ID not found), Then the removal is silently ignored and the encounter state remains unchanged.

Edge Cases

What happens when removing the only combatant? The encounter becomes empty with activeIndex 0.
What happens when removing the active combatant who is last in the list? activeIndex wraps to 0.
What happens when removing from an empty encounter? This is covered by the "ID not found" error since no combatant IDs exist.
What happens if the same ID is passed twice in sequence? The first call succeeds; the second returns an error (ID not found).

Requirements (mandatory)

Functional Requirements

FR-001: System MUST remove a combatant identified by CombatantId from the encounter's combatant list.
FR-002: System MUST return a domain error with code "combatant-not-found" when the given CombatantId does not match any combatant in the encounter.
FR-003: System MUST preserve the roundNumber unchanged after removal.
FR-004: System MUST adjust activeIndex so that the same combatant remains active after removal when the removed combatant is before the active one (activeIndex decrements by 1).
FR-005: System MUST keep activeIndex unchanged when the removed combatant is after the active one.
FR-006: System MUST advance activeIndex to the next combatant (same index position) when the active combatant is removed, allowing the next-in-line to take over.
FR-007: System MUST wrap activeIndex to 0 when the active combatant is removed and it was the last in the list.
FR-008: System MUST set activeIndex to 0 when the last remaining combatant is removed (empty encounter).
FR-009: System MUST emit exactly one CombatantRemoved event on successful removal, containing the removed combatant's ID and name.
FR-010: System MUST expose the remove-combatant operation through the application layer via a use case / port interface.
FR-011: System MUST provide a UI control for each combatant that triggers removal.

Key Entities

Encounter: The combat encounter containing an ordered list of combatants, an activeIndex, and a roundNumber.
Combatant: A participant in the encounter identified by a unique CombatantId and a name.
CombatantRemoved (event): A domain event recording the removal, carrying the removed combatant's ID and name.

Success Criteria (mandatory)

Measurable Outcomes

SC-001: Removing a combatant from any position in the initiative order preserves correct turn tracking (the intended combatant remains or becomes active).
SC-002: All six acceptance scenarios pass as automated tests.
SC-003: The round number never changes as a result of removal.
SC-004: The UI reflects combatant removal immediately after the action, with no stale state displayed.

Assumptions

ID generation and lookup is the caller's responsibility, consistent with the addCombatant pattern.
Removal does not trigger a round advance — roundNumber is always preserved.
The domain function is pure: deterministic given identical inputs, no I/O.
The CombatantRemoved event follows the same plain-data-object pattern as existing domain events.
When the active combatant is removed, the next combatant in order inherits the turn (no automatic turn advance or round increment occurs).
Error feedback for invalid removal is a silent no-op for MVP. MVP baseline does not include user-visible error messages for removal failures.

Constitution Check

Principle	Status	Evidence
I. Deterministic Domain Core	PASS	removeCombatant is a pure state transition with no I/O
II. Layered Architecture	PASS	Domain function → use case → UI adapter
III. Agent Boundary	N/A	No agent layer involved
IV. Clarification-First	PASS	All activeIndex rules fully specified; no ambiguity
V. Escalation Gates	PASS	All requirements within original spec scope
VI. MVP Baseline Language	PASS	No permanent bans; confirmation dialog excluded via MVP baseline language
VII. No Gameplay Rules	PASS	Encounter management only, no game mechanics

7.4 KiB Raw Blame History