dostulata/initiative
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implement the 012-turn-navigation feature that adds a RetreatTurn domain operation and relocates turn controls to a navigation bar at the top of the encounter tracker

Browse Source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Lukas
2026-03-05 23:11:11 +01:00
parent a0d85a07e3
commit 7d440677be
19 changed files with 946 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
specs/012-turn-navigation/checklists/requirements.md Normal file
View File

@@ -0,0 +1,34 @@
# Specification Quality Checklist: Turn Navigation
**Purpose**: Validate specification completeness and quality before proceeding to planning
**Created**: 2026-03-05
**Feature**: [spec.md](../spec.md)
## Content Quality
- [x] No implementation details (languages, frameworks, APIs)
- [x] Focused on user value and business needs
- [x] Written for non-technical stakeholders
- [x] All mandatory sections completed
## Requirement Completeness
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Requirements are testable and unambiguous
- [x] Success criteria are measurable
- [x] Success criteria are technology-agnostic (no implementation details)
- [x] All acceptance scenarios are defined
- [x] Edge cases are identified
- [x] Scope is clearly bounded
- [x] Dependencies and assumptions identified
## Feature Readiness
- [x] All functional requirements have clear acceptance criteria
- [x] User scenarios cover primary flows
- [x] Feature meets measurable outcomes defined in Success Criteria
- [x] No implementation details leak into specification
## Notes
- All items pass. Spec is ready for `/speckit.clarify` or `/speckit.plan`.

55
specs/012-turn-navigation/contracts/domain-api.md Normal file
View File

@@ -0,0 +1,55 @@
# Domain API Contract: Turn Navigation
## retreatTurn(encounter: Encounter): RetreatTurnSuccess | DomainError
### Input
- `encounter`: Encounter (combatants, activeIndex, roundNumber)
### Success Output
```
{
encounter: Encounter // Updated state
events: DomainEvent[] // TurnRetreated, optionally RoundRetreated
}
```
### Error Cases
| Condition | Error Code | Message |
|-----------|------------|---------|
| combatants.length === 0 | `invalid-encounter` | Cannot retreat turn on an encounter with no combatants |
| roundNumber === 1 && activeIndex === 0 | `no-previous-turn` | Cannot retreat before the start of the encounter |
### Event Contracts
**TurnRetreated** (always emitted on success):
```
{
type: "TurnRetreated"
previousCombatantId: CombatantId // Was active before retreat
newCombatantId: CombatantId // Now active after retreat
roundNumber: number // Round number after retreat
}
```
**RoundRetreated** (emitted when crossing round boundary):
```
{
type: "RoundRetreated"
newRoundNumber: number // Decremented round number
}
```
**Emission order**: TurnRetreated first, then RoundRetreated (when applicable).
## UI Contract: TurnNavigation Component
### Props
- `encounter`: Encounter (current state)
- `onAdvanceTurn`: () => void
- `onRetreatTurn`: () => void
### Behavior
- Previous Turn button: calls onRetreatTurn; disabled when roundNumber === 1 && activeIndex === 0, or combatants.length === 0
- Next Turn button: calls onAdvanceTurn; disabled when combatants.length === 0
- Displays: round number and active combatant name

58
specs/012-turn-navigation/data-model.md Normal file
View File

@@ -0,0 +1,58 @@
# Data Model: Turn Navigation
## Existing Entities (unchanged)
### Encounter
- `combatants`: readonly array of Combatant
- `activeIndex`: number (0-based index into combatants)
- `roundNumber`: positive integer (>= 1)
### Combatant
- `id`: CombatantId (branded string)
- `name`: string
- `initiative?`: number
- `maxHp?`: number
- `currentHp?`: number
## New Domain Events
### TurnRetreated
Emitted on every successful RetreatTurn operation.
| Field | Type | Description |
|-------|------|-------------|
| type | `"TurnRetreated"` (literal) | Discriminant for event union |
| previousCombatantId | CombatantId | The combatant whose turn was active before retreat |
| newCombatantId | CombatantId | The combatant who is now active after retreat |
| roundNumber | number | The round number after the retreat |
### RoundRetreated
Emitted when RetreatTurn crosses a round boundary (activeIndex wraps from 0 to last combatant).
| Field | Type | Description |
|-------|------|-------------|
| type | `"RoundRetreated"` (literal) | Discriminant for event union |
| newRoundNumber | number | The round number after decrementing |
## State Transitions
### RetreatTurn
**Input**: Encounter
**Output**: `{ encounter: Encounter, events: DomainEvent[] }` | `DomainError`
**Rules**:
1. If `combatants.length === 0` -> DomainError("invalid-encounter")
2. If `roundNumber === 1 && activeIndex === 0` -> DomainError("no-previous-turn")
3. If `activeIndex > 0`: newIndex = activeIndex - 1, roundNumber unchanged
4. If `activeIndex === 0`: newIndex = combatants.length - 1, roundNumber - 1
**Events emitted**:
- Always: TurnRetreated
- On round boundary crossing (rule 4): TurnRetreated then RoundRetreated (order matters)
## Validation Rules
- RetreatTurn MUST NOT produce roundNumber < 1
- RetreatTurn MUST NOT produce activeIndex < 0 or >= combatants.length
- RetreatTurn is a pure function: identical input produces identical output

76
specs/012-turn-navigation/plan.md Normal file
View File

@@ -0,0 +1,76 @@
# Implementation Plan: Turn Navigation
**Branch**: `012-turn-navigation` | **Date**: 2026-03-05 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/012-turn-navigation/spec.md`
## Summary
Add a RetreatTurn domain operation (inverse of AdvanceTurn) and relocate both Previous/Next Turn buttons to a new turn navigation bar at the top of the encounter tracker. The domain function is a pure state transition that decrements the active index (wrapping to the last combatant and decrementing round number when crossing a round boundary), with a guard preventing retreat before the encounter start (round 1, index 0).
## Technical Context
**Language/Version**: TypeScript 5.8 (strict mode, verbatimModuleSyntax)
**Primary Dependencies**: React 19, Vite 6, Tailwind CSS v4, shadcn/ui-style components, Lucide React (icons)
**Storage**: N/A (no storage changes -- existing localStorage persistence unchanged)
**Testing**: Vitest (pure-function domain tests + component tests)
**Target Platform**: Web browser (single-user, local-first)
**Project Type**: Web application (monorepo: domain + application + web adapter)
**Performance Goals**: Standard web app -- instant UI response (<100ms)
**Constraints**: Domain layer must remain pure (no I/O, no framework imports)
**Scale/Scope**: Single-user encounter tracker, ~5-20 combatants typical
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
| Principle | Status | Notes |
|-----------|--------|-------|
| I. Deterministic Domain Core | PASS | RetreatTurn is a pure function: same input = same output. No I/O, randomness, or clocks. |
| II. Layered Architecture | PASS | Domain (retreat-turn.ts) -> Application (retreat-turn-use-case.ts) -> Adapter (React hook + component). Dependency direction preserved. |
| III. Agent Boundary | N/A | No agent layer involved. |
| IV. Clarification-First | PASS | No ambiguities remain in spec. All edge cases resolved. |
| V. Escalation Gates | PASS | Implementation matches spec scope exactly. |
| VI. MVP Baseline Language | PASS | Assumptions use "MVP baseline does not include" phrasing. |
| VII. No Gameplay Rules | PASS | No gameplay mechanics in plan. |
## Project Structure
### Documentation (this feature)
```text
specs/012-turn-navigation/
├── plan.md # This file
├── research.md # Phase 0 output
├── data-model.md # Phase 1 output
├── quickstart.md # Phase 1 output
├── contracts/ # Phase 1 output
└── tasks.md # Phase 2 output (via /speckit.tasks)
```
### Source Code (repository root)
```text
packages/domain/src/
├── retreat-turn.ts # NEW: RetreatTurn pure function
├── events.ts # MODIFY: Add TurnRetreated + RoundRetreated events
├── types.ts # UNCHANGED
├── index.ts # MODIFY: Re-export retreatTurn
└── __tests__/
└── retreat-turn.test.ts # NEW: All acceptance scenarios
packages/application/src/
├── retreat-turn-use-case.ts # NEW: Orchestrates retreatTurn via EncounterStore
├── ports.ts # UNCHANGED
├── index.ts # MODIFY: Re-export new use case
└── ...
apps/web/src/
├── components/
│ ├── turn-navigation.tsx # NEW: Top-placed Previous/Next turn bar
│ └── action-bar.tsx # MODIFY: Remove Next Turn button
├── hooks/
│ └── use-encounter.ts # MODIFY: Add retreatTurn handler
└── App.tsx # MODIFY: Add TurnNavigation component above combatant list
```
**Structure Decision**: Follows existing monorepo layout (domain -> application -> web adapter). New files mirror the existing advance-turn pattern. The turn navigation component is a new UI component placed in the existing components directory.

49
specs/012-turn-navigation/quickstart.md Normal file
View File

@@ -0,0 +1,49 @@
# Quickstart: Turn Navigation
## Prerequisites
- Node.js 20+
- pnpm
## Setup
```bash
pnpm install
```
## Development
```bash
pnpm --filter web dev # Start dev server at localhost:5173
```
## Testing
```bash
# Run all tests
pnpm test
# Run only retreat-turn domain tests
pnpm vitest run packages/domain/src/__tests__/retreat-turn.test.ts
# Run tests in watch mode
pnpm test:watch
```
## Quality Gate
```bash
pnpm check # Must pass before every commit (knip + format + lint + typecheck + test)
```
## Key Files for This Feature
| File | Layer | Purpose |
|------|-------|---------|
| `packages/domain/src/retreat-turn.ts` | Domain | Pure RetreatTurn function |
| `packages/domain/src/events.ts` | Domain | TurnRetreated + RoundRetreated event types |
| `packages/domain/src/__tests__/retreat-turn.test.ts` | Domain | Acceptance scenario tests |
| `packages/application/src/retreat-turn-use-case.ts` | Application | Use case orchestration |
| `apps/web/src/components/turn-navigation.tsx` | Adapter | Turn nav UI component |
| `apps/web/src/components/action-bar.tsx` | Adapter | Remove Next Turn button |
| `apps/web/src/App.tsx` | Adapter | Wire up new component |

49
specs/012-turn-navigation/research.md Normal file
View File

@@ -0,0 +1,49 @@
# Research: Turn Navigation
## R1: RetreatTurn Domain Pattern
**Decision**: Implement RetreatTurn as a mirror of the existing AdvanceTurn pattern -- a pure function that accepts an Encounter and returns the updated Encounter plus domain events, or a DomainError.
**Rationale**: The existing AdvanceTurn function (`packages/domain/src/advance-turn.ts`) establishes a clear pattern: pure function, value-based error handling via DomainError, domain events returned as data. RetreatTurn is its exact inverse, so following the same pattern maintains consistency and testability.
**Alternatives considered**:
- Generic "move turn" function with direction parameter: Rejected because AdvanceTurn already exists and changing its signature would break the existing API for no benefit. Two focused functions are simpler than one parameterized function.
- Undo/redo stack: Out of scope per spec assumptions. RetreatTurn is a positional operation, not a state-history undo.
## R2: Boundary Guard (Cannot Retreat Before Start)
**Decision**: RetreatTurn returns a DomainError when `roundNumber === 1 && activeIndex === 0`. This is the earliest possible encounter state.
**Rationale**: There is no meaningful "previous turn" before the encounter starts. Allowing retreat past this point would require round 0 or negative rounds, which violates INV-3 (roundNumber >= 1). The spec explicitly requires this guard (FR-003, acceptance scenario 3).
**Alternatives considered**:
- Silently no-op: Rejected because domain operations should be explicit about failures (constitution principle I).
- Allow round 0 as "setup" round: Out of scope, would require spec amendment.
## R3: New Domain Events (TurnRetreated, RoundRetreated)
**Decision**: Introduce two new domain event types: `TurnRetreated` and `RoundRetreated`, mirroring the existing `TurnAdvanced` and `RoundAdvanced` event shapes.
**Rationale**: The existing event system uses discriminated unions with a `type` field. Retreat events should be distinct from advance events so consumers can differentiate the direction of navigation. The shapes mirror their forward counterparts for consistency.
**Alternatives considered**:
- Reuse TurnAdvanced/RoundAdvanced with a `direction` field: Rejected because it changes the existing event shape (breaking change) and complicates event consumers that only care about forward progression.
## R4: UI Placement -- Turn Navigation at Top
**Decision**: Create a new `TurnNavigation` component positioned between the header and the combatant list. Move the Next Turn button out of ActionBar into this new component. ActionBar retains only the Add Combatant form.
**Rationale**: The spec requires turn controls at the top of the tracker (FR-007). The current Next Turn button lives in ActionBar at the bottom. Splitting concerns (turn navigation vs. combatant management) improves the component structure and matches the spec's UX intent.
**Alternatives considered**:
- Keep Next Turn in ActionBar and duplicate at top: Rejected -- redundant controls create confusion.
- Move entire ActionBar to top: Rejected -- the Add Combatant form is secondary to turn navigation and should not compete for top-of-page prominence.
## R5: Disabled State for Previous Turn Button
**Decision**: The Previous Turn button renders in a disabled state (using the existing Button component's `disabled` prop) when the encounter is at round 1, activeIndex 0, or when there are no combatants.
**Rationale**: The spec requires visual indication that Previous Turn is unavailable (FR-008, FR-009). Using the existing Button disabled styling from shadcn/ui-style components ensures visual consistency.
**Alternatives considered**:
- Hide the button entirely when unavailable: Rejected -- hiding causes layout shifts and makes the control harder to discover.

106
specs/012-turn-navigation/spec.md Normal file
View File

@@ -0,0 +1,106 @@
# Feature Specification: Turn Navigation
**Feature Branch**: `012-turn-navigation`
**Created**: 2026-03-05
**Status**: Draft
**Input**: User description: "Introduce a previous Turn button and put both, the previous and the next turn buttons at the top of the tracker. Make the UI/UX modern and sleek. Easy to use."
## User Scenarios & Testing
### User Story 1 - Go Back to the Previous Turn (Priority: P1)
As a game master running a combat encounter, I want to go back to the previous combatant's turn so that I can correct mistakes (e.g., a forgotten action, an incorrectly skipped combatant) without restarting the encounter.
**Why this priority**: The ability to undo a turn advancement is the core new capability. Without it, game masters must work around mistakes manually, disrupting the flow of combat.
**Independent Test**: Can be fully tested as a pure state transition. Given an Encounter and a RetreatTurn action, assert the resulting Encounter state and emitted domain events.
**Acceptance Scenarios**:
1. **Given** an encounter with combatants [A, B, C], activeIndex 1, roundNumber 1, **When** RetreatTurn, **Then** activeIndex is 0, roundNumber is 1, and a TurnRetreated event is emitted with previousCombatantId B, newCombatantId A, roundNumber 1.
2. **Given** an encounter with combatants [A, B, C], activeIndex 0, roundNumber 2, **When** RetreatTurn, **Then** activeIndex is 2, roundNumber is 1, and events are emitted: TurnRetreated (previousCombatantId A, newCombatantId C, roundNumber 1) then RoundRetreated (newRoundNumber 1).
3. **Given** an encounter with combatants [A, B, C], activeIndex 0, roundNumber 1, **When** RetreatTurn, **Then** the operation MUST fail with an error. The encounter is at the very beginning -- there is no previous turn to return to.
4. **Given** an encounter with a single combatant [A], activeIndex 0, roundNumber 3, **When** RetreatTurn, **Then** activeIndex is 0, roundNumber is 2, and events are emitted: TurnRetreated then RoundRetreated (newRoundNumber 2).
5. **Given** an encounter with an empty combatant list, **When** RetreatTurn, **Then** the operation MUST fail with an invalid-encounter error. No events are emitted. State is unchanged.
---
### User Story 2 - Turn Navigation Controls at the Top of the Tracker (Priority: P1)
As a game master, I want the Previous Turn and Next Turn buttons placed prominently at the top of the encounter tracker so that I can quickly navigate turns without scrolling to the bottom of a long combatant list.
**Why this priority**: Relocating the turn controls to the top directly improves usability -- the most-used combat controls should be immediately visible and accessible.
**Independent Test**: Can be fully tested by loading the tracker with combatants and verifying that the turn navigation controls appear above the combatant list and function correctly.
**Acceptance Scenarios**:
1. **Given** the encounter tracker is displayed, **When** the user looks at the screen, **Then** the Previous Turn and Next Turn buttons are visible at the top of the tracker, above the combatant list.
2. **Given** the tracker has many combatants requiring scrolling, **When** the user scrolls down, **Then** the turn navigation controls remain accessible at the top (no need to scroll to find them).
3. **Given** the encounter is at round 1 with the first combatant active, **When** the user views the turn controls, **Then** the Previous Turn button is disabled (visually indicating it cannot be used).
4. **Given** the encounter has no combatants, **When** the user views the tracker, **Then** the turn navigation controls are hidden or disabled.
---
### User Story 3 - Modern, Sleek Turn Navigation Design (Priority: P2)
As a game master, I want the turn navigation controls to have a clean, modern design with clear visual hierarchy so that I can navigate combat intuitively and confidently.
**Why this priority**: A polished design enhances usability and reduces errors during the fast pace of combat. However, functionality comes first.
**Independent Test**: Can be fully tested by visually inspecting the turn navigation area and verifying it meets design criteria.
**Acceptance Scenarios**:
1. **Given** the turn navigation is displayed, **When** the user looks at the controls, **Then** the Previous and Next buttons are visually distinct with clear labels or icons indicating direction.
2. **Given** the encounter is in progress, **When** the user views the turn navigation area, **Then** the current round number and active combatant name are displayed alongside the navigation controls.
3. **Given** the Previous Turn action is not available (round 1, first combatant), **When** the user views the Previous button, **Then** the button appears in a disabled state that is visually distinct from the active state.
---
### Edge Cases
- What happens when retreating at the very start of the encounter (round 1, activeIndex 0)? The operation fails with an error; the Previous Turn button is disabled in this state.
- What happens when retreating past the round boundary? The round number decrements by 1 and activeIndex wraps to the last combatant.
- What happens with a single combatant at round 1? RetreatTurn fails because there is no previous turn. The Previous Turn button is disabled.
- What happens when retreating would bring the round number below 1? This cannot happen -- round 1, activeIndex 0 is the earliest possible state and is blocked.
## Requirements
### Functional Requirements
- **FR-001**: The system MUST provide a RetreatTurn operation that moves the active turn to the previous combatant in initiative order.
- **FR-002**: RetreatTurn MUST decrement activeIndex by 1. When activeIndex would go below 0, it MUST wrap to the last combatant and decrement roundNumber by 1.
- **FR-003**: RetreatTurn at round 1 with activeIndex 0 MUST fail with an error. This is the earliest possible encounter state.
- **FR-004**: RetreatTurn on an empty encounter MUST fail with an error without modifying state or emitting events.
- **FR-005**: RetreatTurn MUST emit a TurnRetreated domain event on success. When the round boundary is crossed (going backward), a RoundRetreated event MUST also be emitted, in order: TurnRetreated first, then RoundRetreated.
- **FR-006**: RetreatTurn MUST be a pure function of the current encounter state. Given identical input, output MUST be identical.
- **FR-007**: The Previous Turn and Next Turn buttons MUST be positioned at the top of the encounter tracker, above the combatant list.
- **FR-008**: The Previous Turn button MUST be disabled when the encounter is at its earliest state (round 1, first combatant active).
- **FR-009**: Both turn navigation buttons MUST be disabled or hidden when the encounter has no combatants.
- **FR-010**: The turn navigation area MUST display the current round number and the active combatant's name.
- **FR-011**: The turn navigation buttons MUST have clear directional indicators (icons, labels, or both) so the user can distinguish Previous from Next at a glance.
### Key Entities
- **Encounter**: Existing aggregate. Contains combatants, activeIndex, and roundNumber. RetreatTurn operates on this entity.
- **TurnRetreated (new domain event)**: Emitted when the turn is moved backward. Carries: previousCombatantId, newCombatantId, roundNumber.
- **RoundRetreated (new domain event)**: Emitted when retreating crosses a round boundary. Carries: newRoundNumber.
## Success Criteria
### Measurable Outcomes
- **SC-001**: A user can reverse a turn advancement in under 1 second using a single click on the Previous Turn button.
- **SC-002**: Turn navigation controls are visible without scrolling, regardless of the number of combatants in the encounter.
- **SC-003**: The Previous Turn button is correctly disabled at the earliest encounter state (round 1, first combatant), preventing invalid operations 100% of the time.
- **SC-004**: All RetreatTurn acceptance scenarios pass as deterministic, pure-function tests with no I/O dependencies.
- **SC-005**: Users can identify which direction each button navigates (forward or backward) within 1 second of viewing the controls.
## Assumptions
- RetreatTurn is the inverse of AdvanceTurn. It does not restore any other state (e.g., HP changes made during a combatant's turn are not undone). It only changes the active combatant and round number.
- The Next Turn button is relocated from the bottom action bar to the new top navigation area. The bottom action bar retains the "Add Combatant" form.
- The existing AdvanceTurn domain operation and its events remain unchanged.
- The MVP baseline does not include a full undo/redo stack. RetreatTurn is a simple backward step through initiative order, not a state history undo.
- The MVP baseline does not include keyboard shortcuts for Previous/Next Turn navigation.

153
specs/012-turn-navigation/tasks.md Normal file
View File

@@ -0,0 +1,153 @@
# Tasks: Turn Navigation
**Input**: Design documents from `/specs/012-turn-navigation/`
**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
## Format: `[ID] [P?] [Story] Description`
- **[P]**: Can run in parallel (different files, no dependencies)
- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
- Include exact file paths in descriptions
---
## Phase 1: Setup (Shared Infrastructure)
**Purpose**: No new project setup needed -- existing monorepo structure is in place. This phase is empty.
**Checkpoint**: Existing infrastructure is sufficient. Proceed directly to foundational work.
---
## Phase 2: Foundational (Blocking Prerequisites)
**Purpose**: Add new domain event types. These are shared by US1 (domain logic) and US2/US3 (UI).
**CRITICAL**: No user story work can begin until this phase is complete.
- [x] T001 Add TurnRetreated and RoundRetreated event interfaces to the DomainEvent union in `packages/domain/src/events.ts`
**Checkpoint**: Foundation ready -- event types defined, user story implementation can begin.
---
## Phase 3: User Story 1 - Go Back to the Previous Turn (Priority: P1) MVP
**Goal**: Implement the RetreatTurn pure domain function and its application use case so that turns can be reversed programmatically.
**Independent Test**: Call retreatTurn with various encounter states and verify correct activeIndex, roundNumber, and emitted events. All tests are pure-function assertions with no I/O.
### Implementation for User Story 1
- [x] T003 [US1] Create retreatTurn pure function in `packages/domain/src/retreat-turn.ts` implementing: decrement activeIndex, wrap to last combatant on round boundary, decrement roundNumber on wrap, error on empty encounter, error on round 1 index 0
- [x] T004 [US1] Write acceptance scenario tests for retreatTurn in `packages/domain/src/__tests__/retreat-turn.test.ts` covering all 5 spec scenarios: mid-round retreat, round-boundary retreat, start-of-encounter error, single-combatant retreat, empty-encounter error
- [x] T005 [US1] Re-export retreatTurn from domain index in `packages/domain/src/index.ts`
- [x] T006 [US1] Create retreatTurnUseCase in `packages/application/src/retreat-turn-use-case.ts` following the advanceTurnUseCase pattern (get encounter from store, call retreatTurn, save result or return error)
- [x] T007 [US1] Export retreatTurnUseCase from application index in `packages/application/src/index.ts`
- [x] T008 [US1] Run `pnpm check` to verify all tests pass, types check, and no lint/format issues
**Checkpoint**: RetreatTurn domain logic is fully functional and tested. UI work can proceed.
---
## Phase 4: User Story 2 - Turn Navigation Controls at the Top (Priority: P1)
**Goal**: Create a turn navigation bar at the top of the tracker with Previous and Next Turn buttons, relocating Next Turn from the bottom action bar.
**Independent Test**: Load the tracker with combatants, verify Previous/Next buttons appear above the combatant list, click Next to advance, click Previous to retreat, verify disabled states.
### Implementation for User Story 2
- [x] T009 [US2] Add retreatTurn handler to the encounter hook in `apps/web/src/hooks/use-encounter.ts` (mirror the existing advanceTurn handler pattern)
- [x] T010 [US2] Create TurnNavigation component in `apps/web/src/components/turn-navigation.tsx` with Previous/Next buttons, round number display, active combatant name, and disabled states (Previous disabled at round 1 index 0 or no combatants; Next disabled when no combatants)
- [x] T011 [US2] Wire TurnNavigation into App between header and combatant list in `apps/web/src/App.tsx`, passing encounter state, onAdvanceTurn, and onRetreatTurn
- [x] T012 [US2] Remove Next Turn button from ActionBar in `apps/web/src/components/action-bar.tsx` (keep only the Add Combatant form)
**Checkpoint**: Turn navigation is fully functional at the top of the tracker. Previous and Next Turn work correctly with proper disabled states.
---
## Phase 5: User Story 3 - Modern, Sleek Turn Navigation Design (Priority: P2)
**Goal**: Polish the turn navigation bar with clear visual hierarchy, directional icons, and a clean modern design consistent with the existing shadcn/ui-style components.
**Independent Test**: Visually inspect the turn navigation area -- buttons have directional icons, round/combatant info is clearly displayed, disabled state is visually distinct, layout is balanced and clean.
### Implementation for User Story 3
- [x] T014 [US3] Add directional icons (e.g., ChevronLeft, ChevronRight from Lucide React) to the Previous/Next buttons in `apps/web/src/components/turn-navigation.tsx`
- [x] T015 [US3] Style the turn navigation bar with proper spacing, border, background, and visual hierarchy consistent with existing card/action-bar styling in `apps/web/src/components/turn-navigation.tsx`
- [x] T016 [US3] Ensure disabled button state has reduced opacity and no hover effects, visually distinct from active state in `apps/web/src/components/turn-navigation.tsx`
**Checkpoint**: Turn navigation is visually polished with clear directional indicators and modern design.
---
## Phase 6: Polish & Cross-Cutting Concerns
**Purpose**: Final validation across all stories.
- [x] T018 Verify layer boundary compliance -- retreatTurn in domain has no application/adapter imports (covered by existing `layer-boundaries.test.ts`)
- [x] T019 Run full quality gate with `pnpm check` and verify clean pass
- [x] T020 Verify localStorage persistence handles retreat correctly (existing persistence should work transparently since it saves the Encounter state)
---
## Dependencies & Execution Order
### Phase Dependencies
- **Foundational (Phase 2)**: No dependencies -- can start immediately
- **User Story 1 (Phase 3)**: Depends on Phase 2 (event types must exist)
- **User Story 2 (Phase 4)**: Depends on Phase 3 (retreatTurn domain + use case must exist)
- **User Story 3 (Phase 5)**: Depends on Phase 4 (TurnNavigation component must exist to polish)
- **Polish (Phase 6)**: Depends on all user stories being complete
### User Story Dependencies
- **User Story 1 (P1)**: Can start after Foundational (Phase 2) -- pure domain work, no UI dependency
- **User Story 2 (P1)**: Depends on US1 completion -- needs retreatTurn use case to wire into the UI
- **User Story 3 (P2)**: Depends on US2 completion -- polishes the component created in US2
### Within Each User Story
- Domain function before tests (or TDD: tests first, then function)
- Domain before application use case
- Application use case before adapter/UI wiring
- UI component creation before styling polish
### Parallel Opportunities
- T014, T015, T016 can run in parallel (same file but independent style concerns -- may be done in one pass)
---
## Implementation Strategy
### MVP First (User Story 1 Only)
1. Complete Phase 2: Foundational (event types)
2. Complete Phase 3: User Story 1 (retreatTurn domain + tests + use case)
3. **STOP and VALIDATE**: All acceptance scenarios pass as pure-function tests
4. Domain logic is fully verified before any UI work
### Incremental Delivery
1. Phase 2: Foundation -> Event types defined
2. Phase 3: US1 -> RetreatTurn domain logic tested and working (MVP domain!)
3. Phase 4: US2 -> Turn navigation bar at top, Previous/Next buttons functional (MVP UI!)
4. Phase 5: US3 -> Visual polish with icons and consistent styling
5. Phase 6: Polish -> Final cross-cutting validation
---
## Notes
- [P] tasks = different files, no dependencies
- [Story] label maps task to specific user story for traceability
- US2 depends on US1 (needs the domain function); US3 depends on US2 (polishes the component)
- This feature has a linear dependency chain, limiting parallel opportunities
- Commit after each phase checkpoint
- The existing advance-turn pattern (domain -> use case -> hook -> component) serves as the reference implementation for all new code