102 lines
7.4 KiB
Markdown
102 lines
7.4 KiB
Markdown
# 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**:
|
|
|
|
1. **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.
|
|
2. **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.
|
|
3. **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.
|
|
4. **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.
|
|
5. **Given** an encounter with combatants [A] and activeIndex 0, **When** the GM removes combatant A, **Then** the encounter has [], activeIndex is 0, roundNumber unchanged.
|
|
6. **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**:
|
|
|
|
1. **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.
|
|
2. **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 |
|