> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_24/prd_phase_24.md).

# PRD Phase 24: Legion II - Live Tier And Combat Playback

**Status**: Complete **Sessions**: 9 (expanded estimate) **Estimated Duration**: 5-9 days

**Progress**: 9/9 sessions (100%)

***

## Overview

Phase 24 makes the running mission watchable: the live tool-event stream of a linked mission plays back as the battle on the `apps/web` battlefield. It is game-design Phase 3 (Legion II - Live Tier and Combat Playback) mapped onto the active spec-system sequence after Phase 23.

The phase renders the live enemy tier that the projection already folds - skirmishers from `test_failure`, the ram from `build_error`/`build_fix`, gremlin pressure from `ts_errors`/`lint_error`, stacked wraiths from hero errors, and siege state from stall escalations - and adds the camp-to-mission linkage that turns real tool events into visible strikes on linked camps. Quest Board accept and assign successes record pending links from real camp, hero, and verbatim prompt data; `mission_start` binds them into `campLinks`; linked missions render strike playback with combo merging, stage props for long sieges, counterattack flashes, and a verified-kill burn-down that only fires on `task_verification`. Scrying posture makes silent-but-active heroes legible, the single `alertFocus` pulse keeps the board readable, and six faction-agnostic world cues route through the existing synth fallback with rate limiting.

Phase 24 also includes a dedicated generated-asset implementation pass for the Phase 3 production sheets already present under `assets/generated/game-design/phase03/`: live enemy/effect treatments, strike vocabulary, and reduced-motion static badges. Those assets must not remain manifest-only reminders. They need direct app/catalog references, typed fallback labels, implementation hooks, and tests before final phase closeout.

The phase does not add XP, loot, banners, titles, levels, Battle Report changes, War Council, Dawn Report, War Tide, essence, territory, sectors as persistent map state, seasons, nemess promotion, bosses, dynamic music layering, multiplayer changes, public-demo synthetic fronts, new protocol events, new server routes, new storage keys, hosted state, or trusted-erasure claims.

Source status: phasebuilt from the game-design backlog. Source scope: web cockpit game layer (`apps/web`). Source goal: the running mission becomes watchable - the fight is the stream.

At the end of the phase, a viewer watching beside a live session should be able to narrate what the agent is doing from board motion alone, a real failing test should spawn its skirmisher within five seconds, a 45-minute mission should read as escalation instead of strobe, and every rendered element should inspect through to its real source.

Session 09 recorded phase-exit implementation evidence on 2026-07-08 in `.spec_system/specs/phase24-session09-validation-and-documentation/phase-exit-audit.md`. The focused Phase 24 test command passed 17 files / 238 tests; root tests passed 3395 tests with 1 skipped and 0 failed; web and workspace typechecks, root format check, root lint check, generated asset catalog tests, and generated source-path runtime scans also passed. Code review and validation are resolved, and `updateprd` marked Session 09 and Phase 24 complete.

***

## Phase-Wide Source Context

Design sections: section 3 (live tier), section 5A (combat resolution), section 13A (buildable Phase A spec and acceptance criteria), section 14.1 (dead air / scrying), section 14.4 (juice fatigue / combo merging), section 14.6 (single alert pulse), section 14.8 (wraith stacking), section 14.9 (replay honesty), all in `docs/game-design/`.

Available foundation (code-verified 2026-07-08):

* `gameProjection.ts` (2,159 lines) already folds `test_failure`, `build_error`, `build_fix`, `ts_errors`, `lint_error`, `task_near_stall`, `task_stalled`, `task_escalation`, and `tool_result` into pure reducer records for `skirmishers`, `ram`, `gremlins`, `wraiths` (per-hero, stacked), and `siege`. Phase 24 renders this state; it must not recreate the records.
* `pendingLinks` and `campLinks` exist in the projection contract with `mission_start` binding logic, but nothing records a pending link today: `questBoardActions.ts` and `useGameStore.ts` contain no pending-link calls.
* `SuggestionAcceptRestResponse` is imported and type-guarded in `apps/web/src/lib/questBoardActions.ts` and returns the verbatim dispatched prompt - the section 5A linkage mechanism is implementable as designed with zero protocol change.
* The store exposes `selectGameProjection`, `selectGameAlertFocus`, and `selectGameLegion`; the alert-focus priority ladder (flare > gate > siege > ram > skirmisher > newCamp) is already computed in the projection.
* Board-internal layer pattern is shipped: `CampLayer.tsx` and `ScannerStateLayer.tsx` are thin, selector-fed, native-control, reduced-motion-aware layers beside `Battlefield.tsx` (740 lines).
* The board-effects pattern is `achievementCelebration.ts` with `CELEBRATION_MAX_CONCURRENT` concurrency capping and timer cleanup.
* SFX manifest: `sfxAssets.ts` keys `SFX_FILES` by faction and `BarkKind` with oscillator-synth fallback in `voiceSynth.ts` and rate limiting in `audioRuntime.ts`; barks route through `useVoiceBarks` / `useFactionVoiceLine` with opt-in posture.
* `replayingSinceMs` and mock-mode persistence guards are shipped and tested; Phase 22/23 regressions prove replay and drill traffic cannot mint durable progress.

The live tier is the fast tempo of the Null Legion, distinct from the slow scanner-camp tempo shipped in Phase 23. The core rule remains honesty: no fight happens that is not real work happening, and no kill is credited without verification.

***

## Phase-Wide Guardrails

* Do not add XP, loot, levels, titles, banners, class advantage, Battle Report, War Council, Dawn Report, War Tide, essence, buildings, territory fog, patrol routes, multi-front tabs, nemesis promotion, bosses, seasons, Hall of Banners, alliance features, or public-demo synthetic fronts.
* Do not add new protocol events, server routes, or storage keys. All live enemies and links derive from events already folded by the projection.
* Do not create a second game-state authority. Live-enemy presentation reads projection selectors; effects layers hold only transient animation state with capped concurrency and timer cleanup.
* Camp kills require `task_verification`. Plausibly-fixing events may drain the displayed HP bar, but a camp dies only when its linked quest completes and verifies. Banish stays dry (Phase 23 boundary).
* Replay, reconnect, and mock traffic must not mint kills, links that persist as progress, or any durable counter movement. Mock drills may animate in memory but never persist.
* Wraiths stack and never multiply: one wraith per hero with a stack badge, board-wide visible cap of 3.
* Exactly one element pulses at a time - the projection's `alertFocus` - rendered by one layer, never per-component urgency.
* Every motion effect ships its reduced-motion static twin in the same session, never retrofitted.
* Generated Phase 3 sheets are production assets, but runtime code must not discover or load directly from `assets/generated/game-design/`. Promotion goes through typed app/catalog references, app-owned runtime paths if browser-serving is needed, fallback labels, accessibility text, and media gate records.
* Per-category SFX rate limits and combo merging are mandatory, not polish: a 45-minute mission must not strobe or repeat identical cues unbounded.
* Scan configuration, diagnostics, provider health, and error internals stay in utility/admin surfaces; strike and enemy tooltips may show only bounded safe labels (test path style), never raw output, prompts, file contents, absolute paths, provider payloads, or secrets.

***

## Phase Requirement Coverage Inventory

* Strike classification, combo merging windows, stage-prop milestones, and SFX rate-limit counters are built as pure helpers in Session 01.
* Camp-to-mission linkage - pending-link recording on Quest Board accept and assign success, verbatim-prompt binding on `mission_start`, expiry, and joint-assault derivation for multiple missions on one camp - is wired in Session 02.
* Live enemy presentation - skirmisher edge markers, ram at the keep gate, gremlin count chip, stacked wraith wisps, siege state - renders in Session 03 with static twins and safe labels.
* Combat playback - strikes on linked camps, counterattack flashes, combo stages, stage props, HP drain display, and verified camp kill burn-down - ships as the effects layer in Session 04, mirroring the `CELEBRATION_MAX_CONCURRENT` pattern.
* Scrying posture for silent-but-active heroes and the single `alertFocus` pulse render in Session 05.
* Six faction-agnostic world cues with synth fallback, rate limiting, and bark reuse for hero-actor moments ship in Session 06.
* Replay, reconnect, mock, persistence, and privacy boundaries for the new live-tier surfaces are regression-tested in Session 07.
* Generated Phase 3 visual sheets - live enemies/effects, strike vocabulary, and reduced-motion static badges - receive direct implementation/catalog references, typed fallbacks, tests, and docs in Session 08.
* The eight section 13A acceptance criteria - glance, cause, kill-latency, silence, honesty, fatigue, reduced-motion parity, and Fun Law 1 audit - are validated with documentation updates in Session 09.

***

## Progress Tracker

| Session | Name                                   | Status   | Est. Tasks | Validated  |
| ------- | -------------------------------------- | -------- | ---------- | ---------- |
| 01      | Pure Strike And Combo Model            | Complete | 18         | 2026-07-08 |
| 02      | Camp Mission Linkage                   | Complete | 19         | 2026-07-08 |
| 03      | Live Enemy Presentation                | Complete | \~22       | 2026-07-08 |
| 04      | Combat Playback Effects Layer          | Complete | \~22       | 2026-07-08 |
| 05      | Scrying And Alert Focus                | Complete | \~14       | 2026-07-08 |
| 06      | World Cues And Bark Reuse              | Complete | \~16       | 2026-07-08 |
| 07      | Honesty And Persistence Boundaries     | Complete | \~14       | 2026-07-08 |
| 08      | Generated Asset Implementation Handoff | Complete | \~18       | 2026-07-08 |
| 09      | Validation And Documentation           | Complete | \~16       | 2026-07-08 |

***

## Completed Sessions

* Session 01: Pure Strike And Combo Model - Completed 2026-07-08. `combatPlayback.ts` pure model (strike classification, combo merging, stage props, SFX rate limits, safe labels) with 27 focused tests.
* Session 02: Camp Mission Linkage - Completed 2026-07-08. Existing accept route extended to current codebase issues (dispatch without resolution), issue cards gained accept/assign, accept/assign success records pending links with replay/mock persistence guards, `mission_start` binding proven end to end, joint-assault selector added.
* Session 03: Live Enemy Presentation - Completed 2026-07-08. `liveLegion.ts` and `LiveLegionLayer.tsx` render the folded live enemy tier with safe labels, caps, reduced-motion twins, wraith hero selection, and store-path `test_failure`/`test_pass` clearing coverage.
* Session 04: Combat Playback Effects Layer - Completed 2026-07-08. `combatPlaybackEffects.ts` and `CombatPlaybackLayer.tsx` turn linked mission `tool_use`, failed `tool_result`, and verified `task_verification` evidence into bounded strikes, counterattacks, combo/stage props, display-only HP drain, and reduced-motion kill states without creating new storage, protocol, server, reward, or projection authority.
* Session 05: Scrying And Alert Focus - Completed 2026-07-08. `scryingAndAlertFocus.ts` and `ScryingAndAlertFocusLayer.tsx` derive silent active hero channeling posture and render exactly one projection-owned alert-focus treatment with bounded labels, reduced-motion twins, shared clock cleanup, and focused component coverage.
* Session 06: World Cues And Bark Reuse - Completed 2026-07-08. Typed world cue support, synth fallback routing, pure cue derivation, transient hook orchestration, Battlefield integration, and focused runtime, adapter, hook, pure, and Battlefield tests cover six Phase 24 world cues and hero-actor bark reuse without adding recorded assets, storage, protocol, server, reward, or diagnostic UI paths.
* Session 07: Honesty And Persistence Boundaries - Completed 2026-07-08. Projection persistence now strips prompt-bearing runtime pending links before browser storage, legacy persisted raw pending links normalize away on load, and focused reducer/store/Quest Board/erasure regressions prove replay, reconnect, mock, aggregate storage, and browser-local erasure honesty.
* Session 08: Generated Asset Implementation Handoff - Completed 2026-07-08. `generatedPhase3Assets.ts`, app media catalog records, and battlefield layer metadata now pin Phase 3 generated sheets to typed app references, fallback labels, reduced-motion static posture, focused tests, and docs without runtime loading from `assets/generated/game-design/`.
* Session 09: Validation And Documentation - Completed 2026-07-08. Focused Phase 24 web tests passed 17 files / 238 tests; root tests passed 3395 tests with 1 skipped and 0 failed; web typecheck, workspace typecheck, root format check, root lint check, generated asset catalog tests, and generated source-path runtime scans passed; `phase-exit-audit.md` records PASS/source-backed evidence for all eight section 13A criteria, Fun Law 1, Fun Law 4, replay/reconnect/mock/storage/privacy boundaries, generated asset posture, and no-overclaim residuals. Code review, validation, and `updateprd` closeout are resolved.

***

## Upcoming Sessions

* None. Phase 24 session work is complete. Next workflow command: `audit`.

***

## Session Dependency Split

| Session | Title                                  | Depends On |
| ------- | -------------------------------------- | ---------- |
| 01      | Pure Strike And Combo Model            | None       |
| 02      | Camp Mission Linkage                   | None       |
| 03      | Live Enemy Presentation                | 01         |
| 04      | Combat Playback Effects Layer          | 01, 02, 03 |
| 05      | Scrying And Alert Focus                | 03         |
| 06      | World Cues And Bark Reuse              | 04         |
| 07      | Honesty And Persistence Boundaries     | 02, 04     |
| 08      | Generated Asset Implementation Handoff | 03, 04, 05 |
| 09      | Validation And Documentation           | 06, 07, 08 |

***

## Objectives

1. Turn the already-folded live enemy tier (skirmishers, ram, gremlins, wraiths, siege) into readable, accessible, honest battlefield presentation with reduced-motion parity.
2. Wire the section 5A camp-to-mission linkage from real Quest Board accept and assign responses so linked missions play back as deterministic combat on their camps, with verified kills only.
3. Keep long sessions watchable and honest: combo merging, stage props, SFX rate limits, scrying posture, single alert pulse, and proof that replay and mock traffic mint nothing.

***

## Prerequisites

* Phase 23 completed: Legion I - Scanner Camps.
* Phase 22 projection authority, persistence guards, and replay/mock safeguards remain in place.
* Existing Quest Board accept/assign actions and `SuggestionAcceptRestResponse` handling remain available.
* Existing bark/SFX runtime (`sfxAssets.ts`, `voiceSynth.ts`, `audioRuntime.ts`) remains available with opt-in posture.

***

## Planning Assumptions And Resolutions

### Working Assumptions

* The game-design backlog (`docs/game-design/15-phases-yet-to-be-implemented.md`) is the source-backed next phase: design Phase 3 is the only phase whose dependency (implemented Phase 2 / spec-system Phase 23) is satisfied.
* Spec-system Phase 24 maps to game-design Phase 3, continuing the recorded mapping (design Phase 1 -> spec 22, design Phase 2 -> spec 23).
* The primary package is `apps/web`; all code anchors are web library, store, battlefield, Quest Board, audio, and test files. No server or protocol work is expected.
* The Phase 22 reducer substrate for live enemies and links is authoritative; sessions render and wire it rather than re-deriving enemy state.
* Strike playback consumes `tool_use`/`tool_result`-shaped data already reaching the store event path; if a needed event field is absent, the strike degrades to a generic strike rather than inventing detail.
* The section 13A cause and fatigue tests are dogfood self-reports plus automated proxies (combo-stage tests, rate-limit tests); no external playtest infrastructure is in scope.
* The Phase 3 generated image sheets are already production-owned assets in `docs/game-design/manifest.md`; Session 08 turns them into direct implementation/catalog references without changing Phase 24's no-new-art and DOM/CSS-first runtime posture.

### Open Questions

* Whether pending links should persist across reloads or remain in-memory until bound; Session 02 should follow the existing projection persistence contract (`pendingLinks` is already part of the projection state) and its expiry rule rather than inventing a new boundary.
* The exact N per minute for each SFX rate limit and the combo-merge window duration are tuning constants; land them in pure modules with focused tests so Phase 12's tuning sweep can adjust them.
* Whether the keep gate has an existing stable DOM anchor for the ram; if not, Session 03 adds a minimal keep anchor within the board-internal layer contract.

### Conflict Resolutions

* Doc 15 lists Phase 22 substrate for live enemies while also warning Phase 3 is not implemented. Resolution: sessions treat reducer records as shipped contracts (no recreation) and scope new work to recording links, selectors, presentation, effects, audio, and validation.
* Section 13A criterion 5 requires camp kills on `task_verification`, while Phase 23 forbade camp damage from mission events. Resolution: Phase 24 is the source-backed phase that adds linked HP drain display and verified camp kills; the Banish-stays-dry and no-XP/loot/banner boundaries remain.

***

## Technical Considerations

### Architecture

`GameProjection` remains the only derived game-state authority. Live enemies and links are already projection state; Phase 24 adds pending-link recording through the existing store action path, presentation selectors, and thin board-internal DOM layers (camp layer below hero tokens, effects layer with `pointer-events: none` above them, single alert pulse on top). Effects hold only transient animation state with concurrency caps and timer cleanup.

### Technologies

* `apps/web/src/lib/gameProjection.ts` (link recording entry points, selectors)
* `apps/web/src/lib/combatPlayback.ts` (new pure strike/combo/stage model)
* `apps/web/src/lib/questBoardActions.ts` (accept/assign link recording)
* `apps/web/src/store/useGameStore.ts` (folding, selectors)
* `apps/web/src/components/battlefield/Battlefield.tsx` and new `LiveLegionLayer` / `EffectsLayer` components beside `CampLayer.tsx`
* `apps/web/src/components/battlefield/achievementCelebration.ts` (pattern)
* `apps/web/src/lib/sfxAssets.ts`, `voiceSynth.ts`, `audioRuntime.ts`
* `apps/web/src/data/mediaCatalog.ts` or a dedicated `apps/web` game-design asset map for Phase 3 generated visual references
* Vitest and React Testing Library

### Risks

* Fake combat or farmable kills: mitigate by deriving every strike from a real event on a bound mission, killing camps only on `task_verification`, and regression-testing replay/mock no-progress.
* Strike spam and audio fatigue: mitigate with pure combo-merge and rate-limit modules tested independently of the DOM, plus stage props so long fights escalate instead of looping.
* Board illegibility: mitigate with the single `alertFocus` pulse, wraith stack caps, bounded skirmisher rendering, and Champion Mode interplay already shipped in Phase 23.
* Effects-layer leaks or runaway timers: mitigate by copying the `CELEBRATION_MAX_CONCURRENT` concurrency and cleanup pattern and testing unmount cleanup.
* Privacy drift in tooltips/labels: mitigate by reusing safe-label helpers and testing that no raw output, prompts, absolute paths, or provider payloads reach rendered strings or persisted state.
* Generated assets staying forgotten or bypassing media gates: mitigate with a dedicated Session 08 that records typed app/catalog references, fallback labels, tests, and docs for the Phase 3 generated sheets.

### Relevant Considerations

* \[P23-apps/web] **Scanner camps are projection-owned**: combat playback and live-enemy layers read `gameProjection.ts` and `legionCamps.ts` selectors instead of adding parallel camp state, protocol events, routes, or keys.
* \[P23-apps/web] **Do not turn scanner camps into combat rewards**: Phase 24 adds verified camp kills as its scoped source-backed claim, but Banish, clean scans, failed scans, and mock drills still mint nothing, and no XP, loot, banners, or achievements ship this phase.
* \[P22-apps/web] **Do not persist replay or drill progress**: replay, reconnect, mock, and synthetic traffic may animate in memory but must not increment durable kills, links-as-progress, or counters.
* \[P22-apps/web] **`gameProjection.ts` owns reducer purity and guards**: new link-recording and kill logic lands as pure reducer/entry-point code with equality guards, mirroring Phase 23 lessons.
* \[P23-apps/web] **Presentation-only battlefield layers**: new layers stay thin, native-control-based, reduced-motion-aware, and selector-fed.
* \[P07] **Redaction is boundary-specific**: strike badges, tooltips, wraith and skirmisher labels, SFX metadata, tests, and docs keep raw commands, output, file contents, provider payloads, secrets, and broad absolute paths out.

***

## Success Criteria

Session 09 records implementation evidence for the criteria below. Code review, validation, and `updateprd` closeout are resolved.

Phase complete when:

* [x] Implementation evidence recorded for all 9 sessions.
* [x] Glance test: a one-second look classifies the war as calm, fighting, or needs-you, with the `alertFocus` pulse visible.
* [x] Cause test: board motion distinguishes reading, editing, and running commands for the large majority of strikes on a live linked mission.
* [x] Kill-latency test: a real failing test spawns its skirmisher within 5 seconds; a pass clears it within 5 seconds; `build_fix` kills the ram on arrival.
* [x] Silence test: ten event-free minutes still pass the glance test, show scrying/ambient state, and emit zero urgency signals.
* [x] Honesty test: replay links and reconnects change no persisted projection numbers; camp kills require `task_verification`.
* [x] Fatigue test: a 45-minute mission never repeats an identical SFX beyond its per-minute limit and strikes merge into combo stages - no strobe.
* [x] Reduced-motion parity: the above criteria pass with animations disabled using static twins.
* [x] Fun Law 1 audit: every rendered element inspects through to its real source (camp to Quest Board issues, skirmisher to test path, wraith to hero error) - no orphan fiction.
* [x] The Phase 3 generated visual assets have direct app/catalog references and implementation or typed fallback mappings: `assets/generated/game-design/phase03/live-enemies/live-enemy-effects-sheet.png`, `assets/generated/game-design/phase03/strike-vocabulary/strike-vocabulary-effects-sheet.png`, and `assets/generated/game-design/phase03/reduced-motion/reduced-motion-static-badges-sheet.png`.
* [x] No new protocol event, server route, storage key, hosted dependency, reward system, or trusted-erasure claim is introduced.
* [x] Focused tests, web typecheck, and formatting checks pass.

***

## Dependencies

### Depends On

* Phase 23: Legion I - Scanner Camps.

### Enables

* Phase 25 candidates: game-design Phase 4 (Verbs and Ceremony), Phase 5 (Banners, XP and Class Advantage), or Phase 7 (The Living Map) - all unblocked for planning after Phase 24 validation and closeout.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_24/prd_phase_24.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.