> 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/docs/game-design/15-phases-yet-to-be-implemented.md). # Phases Yet To Be Implemented - The War Effort **Project:** FactionOS - The War Effort **Document role:** Pending implementation phase backlog **Source snapshot:** This document started as a mirror of `13-implementation-phase-outline.md`. It now tracks only game-design phases that remain unimplemented after design Phases 1, 2, and 3 shipped as spec-system Phases 22, 23, and 24. **Latest verification:** 2026-07-08. Design Phase 3 moved out of this pending backlog after spec-system Phase 24 Session 09 recorded implementation-evidence PASS in `.spec_system/specs/phase24-session09-validation-and-documentation/phase-exit-audit.md`. Session 09 ran the focused Phase 24 web tests (17 files / 238 tests), root tests (3395 passed, 1 skipped, 0 failed), web and workspace typechecks, root format and lint checks, generated asset catalog tests, generated source-path runtime scans, and phase-exit audit. Code review, validation, and `updateprd` closeout are resolved; `.spec_system/state.json` has no active session and marks Phase 24 complete. This backlog now starts at design Phase 4. **Sizing unit:** one phase is approximately one \~800k-token agentic context window of work (design reading + code + tests + doc updates inside a single session), so each phase is deliberately one coherent vertical slice with a small, stable file surface - not a grab bag. This document sequences the *entire* design package (docs 01-12) into buildable phases. It refines the fun-ordered build order in `08-production-roadmap-and-phase-a-spec.md` (Phases A-F) into session-sized units. Section references use the package-wide numbering. ## Implemented Prerequisites Design Phase 1 - Projection Foundation is no longer pending. It shipped as spec-system Phase 22 on 2026-07-05 and is recorded in `14-implemented-phases.md`. Future game-design phases must build on that single `gameProjection.ts` authority instead of creating another game state source. Design Phase 2 - Legion I: Scanner Camps is no longer pending. It shipped as spec-system Phase 23 on 2026-07-05 with implementation evidence in `.spec_system/specs/phase23-session08-validation-and-documentation/phase-exit-audit.md`. Future phases must build on the shipped scanner camp baseline: real `suggestion_update` snapshots reconcile into aggregate camps, camp inspection opens the real Quest Board issue set, dry Banish grants no reward or progress, and replay/mock/hosted/trusted-erasure boundaries remain no-claim unless a later scoped phase proves otherwise. Design Phase 3 - Legion II: Live Tier And Combat Playback is no longer pending. It completed as spec-system Phase 24 on 2026-07-08 with implementation evidence in `.spec_system/specs/phase24-session09-validation-and-documentation/phase-exit-audit.md`. Future phases must build on the shipped live tier baseline: Quest Board accept/assign pending links, `mission_start` binding, combat playback, verified burn-downs, live skirmishers/rams/gremlins/wraiths/siege, scrying, alert focus, world cues, reduced-motion parity, typed generated-asset references, aggregate-only projection storage, replay/reconnect/mock guards, and the shared `test_pass` protocol event used to clear skirmishers honestly. Aside from `test_pass`, Phase 24 added no new protocol surface; it also added no server route, storage key, hosted dependency, reward path, public-demo synthetic front, or trusted-erasure claim. ## Implemented Phase 3 Session Handoff These Phase 24 sessions are implemented prerequisites for every remaining game-design phase. Future planning should cite these artifacts instead of reopening Phase 3 scope. | Session | Shipped baseline future phases inherit | Artifact | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | 01 - Pure Strike And Combo Model | Pure strike classification, combo merging, stage-prop milestones, SFX rate-limit helpers, and bounded labels in `combatPlayback.ts`. | `.spec_system/specs/phase24-session01-pure-strike-and-combo-model/IMPLEMENTATION_SUMMARY.md` | | 02 - Camp Mission Linkage | Quest Board accept/assign pending links, `mission_start` camp binding, joint-assault selector, and accept-as-dispatch-not-resolution behavior. | `.spec_system/specs/phase24-session02-camp-mission-linkage/IMPLEMENTATION_SUMMARY.md` | | 03 - Live Enemy Presentation | `liveLegion.ts`, `LiveLegionLayer.tsx`, live enemy caps/labels/static twins, wraith hero selection, and `test_pass` protocol clearing. | `.spec_system/specs/phase24-session03-live-enemy-presentation/IMPLEMENTATION_SUMMARY.md` | | 04 - Combat Playback Effects Layer | `CombatPlaybackLayer.tsx` and `combatPlaybackEffects.ts` for linked strikes, counterattacks, combos, stage props, HP display, and verified-only burn-down. | `.spec_system/specs/phase24-session04-combat-playback-effects-layer/IMPLEMENTATION_SUMMARY.md` | | 05 - Scrying And Alert Focus | Silent active hero channeling posture and exactly one projection-owned `alertFocus` treatment. | `.spec_system/specs/phase24-session05-scrying-and-alert-focus/IMPLEMENTATION_SUMMARY.md` | | 06 - World Cues And Bark Reuse | Six world cues through existing opt-in audio runtime and synth fallback, plus hero bark reuse for actor moments. | `.spec_system/specs/phase24-session06-world-cues-and-bark-reuse/IMPLEMENTATION_SUMMARY.md` | | 07 - Honesty And Persistence Boundaries | Prompt-bearing pending links remain runtime-only; persisted `factionos-game-v1` stays aggregate-only; replay/reconnect/mock/storage/erasure regressions are covered. | `.spec_system/specs/phase24-session07-honesty-and-persistence-boundaries/IMPLEMENTATION_SUMMARY.md` | | 08 - Generated Asset Implementation Handoff | Phase 3 generated sheets are typed app references and media catalog records with fallback labels and no direct runtime load from `assets/generated/game-design/`. | `.spec_system/specs/phase24-session08-generated-asset-implementation-handoff/IMPLEMENTATION_SUMMARY.md` | | 09 - Validation And Documentation | Final 17-file/238-test focused validation, root tests, typechecks, format/lint, generated asset checks, phase-exit audit, stable docs, PRD/state closeout, and archive. | `.spec_system/specs/phase24-session09-validation-and-documentation/IMPLEMENTATION_SUMMARY.md` | ## Grounding notes (sixth pass - code-verified 2026-07-08) Facts checked directly against the codebase that shape the phasing: * **All 21 protocol events the design leans on exist** in `packages/protocol/src/events.ts` (780 lines). Twenty existed before Phase 24; Session 03 added the shared `test_pass` event so skirmisher pass-clearing is explicit instead of timer-inferred. Verified by grep: `test_failure`, `test_pass`, `build_error`, `build_fix`, `ts_errors`, `lint_error`, `loop_update`, `task_stalled`, `task_near_stall`, `task_verification`, `plan_verification_complete`, `suggestion_update`, `hero_evidence_update`, `file_intent_declare`, `warroom_pending_catchup`, `scroll_collected`, `achievement_unlocked`, `awaiting_input`, `plan_budget_warning`, `plan_budget_exhausted`, `subagent_lineage_update`. * **The projection authority now exists.** `apps/web/src/lib/gameProjection.ts` is 2,231 lines and `apps/web/src/store/useGameStore.ts` is 4,101 lines. The store folds projection state through one event-apply path and exports `selectGameProjection`, `selectGameAlertFocus`, and `selectGameLegion`. Future phases add reducer cases or presentation layers on top of that authority; they must not create another game state source. * **Phase 3 implementation evidence is recorded.** Phase 22 landed pure reducer substrate for skirmishers, rams, gremlins, wraiths, siege pressure, `pendingLinks`, and `campLinks` in `gameProjection.ts`. Phase 24 then added the pure `combatPlayback.ts` strike/combo/rate model, Quest Board accept/assign pending-link recording, `mission_start` binding, joint-assault selection, live enemy presentation, `test_pass` skirmisher clearing, combat playback effects, scrying posture, alert focus, world cues, persistence honesty, and generated asset implementation references. Session 09 records Phase 3 exit evidence in `phase-exit-audit.md`; code review, validation, and `updateprd` closeout are resolved. * **The Phase 24 battlefield layer stack is now real:** `Battlefield.tsx` is 894 lines and mounts `CampLayer`, `ScannerStateLayer`, `LiveLegionLayer`, `CombatPlaybackLayer`, `ScryingAndAlertFocusLayer`, and `RemoteParticipantOverlay` beside the existing `achievementCelebration.ts` effect helper. Future phases should add side modules/layers instead of inflating the board root. * **The linkage mechanism is now wired:** `SuggestionAcceptRestResponse` is imported and type-guarded in `apps/web/src/lib/questBoardActions.ts`, and Phase 24 Session 02 records real camp, hero, and prompt data into projection-owned pending links before `mission_start` binds `campLinks`. * **Replay honesty substrate is wired:** `replayingSinceMs` lives in `useGameStore.ts`, `dispatchReplayEntries` lives in `apps/web/src/lib/replayLink.ts`, and Phase 22 regressions prove replay traffic does not change persisted projection progress numbers. * **Generated Phase 3 assets are implementation references, not runtime media:** `generatedPhase3Assets.ts`, `mediaCatalog.ts`, and the Session 08 tests pin the live-enemy, strike-vocabulary, and reduced-motion static-badge sheets. Runtime components expose typed asset/fallback metadata but do not load generated source paths directly. * **The mock substrate is `apps/server/src/managers/mockEventGenerator.ts`** plus the `mockEnabled` dev knob in `useSettingsStore.ts` - War Games (Phase 12) is a reframe of a shipped module, not new simulation. Caveat: mock events are indistinguishable on the wire, so the progress-inert guard keys off `mockEnabled`; Phase 22 already prevents mock-enabled projection writes while allowing in-memory folding. * **`apps/server/src/lib/names.ts` already generates faction-themed names** * the Named Nemeses table (Phase 8) mirrors an existing pattern rather than inventing one. * **Heroes record their working directory** (`packages/protocol/src/heroes.ts`) * the multi-front model (Phase 7) has its data already. * **Scanner stack confirmed:** `codebaseScanOrchestrator.ts`, `codebaseIssueScanners.ts`, `projectScanEngine.ts`, `onDemandAnalysisEngine.ts` in `apps/server/src/lib/` feed `suggestionManager.ts` - camps and Dispatch Scouts sit on live plumbing. * **`channelCommandManager.ts` exists** in `apps/server/src/managers/` - the Emissary (Phase 4) frames a shipped intake path. * **SFX manifest shape:** `sfxAssets.ts` keys `SFX_FILES` by `FactionId x BarkKind` with synth fallback via `voiceSynth.ts`. World cues (Phase 3) extend this manifest with a faction-agnostic bucket. * **Complexity tiers (`quick/routine/heavy/epic`) and specialization confidence (`low/medium/high` + generalist) verified** in `missionComplexity.ts` / `heroSpecialization.ts` - the XP and Class Advantage formulas (Phase 5) compose verified vocabulary. * **Test convention:** 150 test files in `apps/web/tests/` following a pure-lib test + component test split; every phase adds both kinds. ## Ground rules for every phase 1. **Shippable and fun at the end.** Each phase lands behind nothing - it ships, it demos, and its slice passes its own glance/honesty checks. 2. **The projection is never bypassed.** All game state flows through `gameProjection.ts` (section 15/section 15A); phases add reducer cases, never new state authorities. 3. **Reduced-motion twins ship with the motion**, never retrofitted (section 5B). 4. **Fun Laws audited per phase** - especially Law 1 (no fake fire) and Law 4 (never reward waste); each phase's exit includes a quick section 9 pass. 5. **Docs updated in the same window.** The phase's session updates the owning design doc(s) and the section 16 change log before it ends. 6. **Check generated assets before making art.** `manifest.md` tracks production-generated assets already present under `assets/generated/game-design/`. Promotion still requires consuming paths, fallbacks, accessibility, cache/mirror behavior, and provenance records in the implementing phase. ## Remaining Phase Table (dependency order) | # | Phase | Design sections | Depends on | | -- | ----------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | 4 | Verbs & Ceremony | section 3A, section 14.5, section 11 (Town Crier) | implemented Phase 3 / spec-system Phase 24 evidence | | 5 | Banners, XP & Class Advantage | section 6, section 6A, section 9, Battle Report (section 4) | implemented Phase 3 / spec-system Phase 24 evidence | | 6 | Stakes & The Return Loop | section 4 (War Tide), section 4B, Dawn Report (section 4, section 16), First Ten Minutes (section 4) | 5 | | 7 | The Living Map | section 5, section 7A, section 14.3 | implemented Phase 3 / spec-system Phase 24 evidence | | 8 | Loot & Legends | section 7, section 6 (quirks, Hall of Banners), section 10 (Nemeses) | 5 | | 9 | Bosses & Dynamic Audio | section 10, section 11 | 7, 8 | | 10 | The Alliance War | section 8, section 16 (redaction question) | 5 | | 11 | Seasons & Saga | section 4 (War Loop), section 7A (saga pages) | 7, 8 | | 12 | War Games, Demo & Hardening | section 5B (synthetic front), section 13A criteria re-run, section 16 tuning | all | ## Generated Asset Handoff Use `manifest.md` for asset IDs, dimensions, source files, and runtime posture. Phase 3 generated sheets are now implementation references recorded in `14-implemented-phases.md`, `docs/media/media-assets.md`, and the Phase 24 Session 09 audit. The paths below are reminders for future phase owners so existing assets are not missed: | Phase | Already-present generated assets | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 4 - Verbs & Ceremony | `assets/generated/game-design/phase04/town-crier/town-crier-toast-chrome-sheet.png`, `assets/generated/game-design/phase04/command-ceremony/command-ceremony-props-sheet.png`, `assets/generated/game-design/phase05/banners-regalia/banners-regalia-sheet.png`, `assets/generated/game-design/phase05/class-icons/class-icons-and-flares-sheet.png`, `assets/generated/game-design/phase08/loot/loot-roll-visuals-sheet.png` | | 5 - Banners, XP & Class Advantage | `assets/generated/game-design/phase05/banners-regalia/banners-regalia-sheet.png`, `assets/generated/game-design/phase05/class-icons/class-icons-and-flares-sheet.png`, `assets/generated/game-design/phase06/battle-report/battle-report-frame.png` | | 6 - Stakes & The Return Loop | `assets/generated/game-design/phase06/war-council/war-council-objective-board.png`, `assets/generated/game-design/phase06/war-tide/war-tide-meter-sheet.png`, `assets/generated/game-design/phase06/dawn-report/dawn-report-recap-backdrop.png`, `assets/generated/game-design/phase06/onboarding/first-ten-minutes-onboarding-sheet.png` | | 7 - The Living Map | `assets/generated/game-design/phase07/territory-map/territory-map-base.png`, `assets/generated/game-design/phase07/home-sector/home-sector-building-dressings.png` | | 8 - Loot & Legends | `assets/generated/game-design/phase08/loot/loot-roll-visuals-sheet.png`, `assets/generated/game-design/phase08/tomes/tome-expansion-art-sheet.png`, `assets/generated/game-design/phase08/relics/relic-set-art-sheet.png`, `assets/generated/game-design/phase08/hall-of-banners/hall-of-banners-gallery-backdrop.png`, `assets/generated/game-design/phase08/hero-quirks/hero-quirks-palette-sheet.png`, `assets/generated/game-design/phase08/nemesis/nemesis-presentation-sheet.png` | | 9 - Bosses & Dynamic Audio | `assets/generated/game-design/phase09/bosses/blight-titan-standee.png`, `assets/generated/game-design/phase09/bosses/blight-titan-standee-chroma-source.png`, `assets/generated/game-design/phase09/siege/siege-set-piece-static.png` | | 10 - The Alliance War | `assets/generated/game-design/phase10/alliance-war/alliance-war-visuals-sheet.png`, `assets/generated/game-design/phase09/bosses/null-sovereign-world-boss-standee.png`, `assets/generated/game-design/phase09/bosses/null-sovereign-world-boss-standee-chroma-source.png`, `assets/generated/game-design/phase05/banners-regalia/banners-regalia-sheet.png` | | 11 - Seasons & Saga | `assets/generated/game-design/phase11/seasons-saga/seasons-saga-visuals-sheet.png`, `assets/generated/game-design/phase08/hall-of-banners/hall-of-banners-gallery-backdrop.png`, `assets/generated/game-design/phase08/relics/relic-set-art-sheet.png`, `assets/generated/game-design/phase09/bosses/blight-titan-standee.png` | | 12 - War Games, Demo & Hardening | `assets/generated/game-design/phase12/war-games/war-games-demo-presentation-sheet.png` | ## Remaining Asset And Content Handoff Generated sheets close source-art gaps only. Each future phase still owns the runtime slicing, DOM/data binding, labels, static twins, catalog records, provenance, cache/mirror posture, and tests needed by its consuming surface. | Phase | Remaining asset and content work | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 4 - Verbs & Ceremony | Runtime Town Crier wiring for toast copy, priority distinction, icons, visible non-audio equivalents, and accessibility labels; command-prop slicing and labels for war-table plans, gates, contracts, missives, scouts, approval/denial seals, flags, scrolls, and route markers; full verb ceremony cue pack; lobster click-line promotion decision. | | 5 - Banners, XP & Class Advantage | Runtime slicing and mapping for banners, pennants, seals, trophy pins, class medallions, trims, and flares; class bark modality and cue production; Battle Report DOM/data wiring for territory delta, banners, MVP, efficiency grade, and declared-vs-achieved ledger; title catalog v1 with trigger rules and display strings. | | 6 - Stakes & The Return Loop | War Council picker/data implementation, objective copy, completion lines, reroll copy, Battle Report ledger strings, and objective-type icons; War Tide runtime slicing, state binding, signed-chip formatting, and labels; Dawn Report synthetic beat vocabulary and copy; first-ten-minutes onboarding copy, state gates, and CTAs; report, council, dawn, and objective-complete audio. | | 7 - The Living Map | Live sector grid semantics, fog pushback, re-fog, corruption overlays, small-repo deepening, monorepo aggregation, multi-front tabs, patrol routes, and legibility tuning; home-sector building levels, faction upgrade variants, resource counts, and state-specific smoke. | | 8 - Loot & Legends | Tome expansion catalog with names, descriptions, trigger hints, rarity tiers, unlock copy, and lore pages; relic catalog with names, rarity, source rules, display labels, aura mapping, and boss/nemesis variants; loot roll slicing and rarity mapping; hero quirk deterministic seed mapping; Hall of Banners final quote templates, class/title display, and saga stat badges; nemesis name table, Dawn Report mention templates, slain-state strings, and title/relic tie-ins. | | 9 - Bosses & Dynamic Audio | Boss standee runtime promotion through catalog/provenance gates; siege set-piece state binding and optional animated treatment with the static image as reduced-motion twin; dynamic music stems and stingers for idle, active, siege, flare, boss, report, council, dawn, victory, and kill beats. | | 10 - The Alliance War | Alliance War visual slicing, alliance-state binding, shared-front markers, shared boss HP display, faction league emblems, cooperative contract flags, accessibility labels, and the exact redacted fields allowed for shared score/state visuals. | | 11 - Seasons & Saga | Saga chronicle templates, season start/end copy, illuminated page text, slain-nemesis entries, Golden Age entries, veteran retirement lines, season rollover and snapshot labels, re-fog presentation, and season/saga audio stingers. | | 12 - War Games, Demo & Hardening | Scripted 60-second synthetic-front scenario data, demo banner/state labels, progress-inert markings, staged hero/camp fixtures, public-demo media/cache parity, accessibility labels, final asset fatigue sweep, and tuning copy. | | Every future phase | Alt text, caption strings, visible-equivalent labels, reduced-motion labels, failed-media copy, source-inspection copy, source/rights/credits records, privacy review, and tests aligned with the owning surface. | Phases 4-5 can run in either order after implemented Phase 3 evidence; 7, 8, and 10 are parallelizable after their dependencies; 12 is always last. ## Phase 4 - Verbs & Ceremony **Goal:** every one of the \~13 player verbs feels *senior* - thick, chunky, physical (section 3A). * Ceremony pass over the full verb table: summon banner-raise, rally horn, counsel flare-douse, wax-seal plan decisions, portcullis gates, muster flag (with section 6A affinity flare hook point), tavern contracts, honorable discharge, Banners Unite, Warchief's decree, **Receive the Emissary** (inbound channel commands), Dispatch Scouts. * `collect_scroll` polish budget - the one pure-game click gets arcs, rarity beams, shelf-fill (section 3A rule 2). * Flare ceremony budget (section 14.5) wired to `flareCeremony` state. * Toast -> **Town Crier** framing; work toasts stay visually senior (section 11). **Code anchors.** No new state - this phase touches the verb surfaces: `PlanWorkpad.tsx`, `PermissionModal.tsx`, `QuestBoard.tsx`, `NoticeBoard.tsx`, `HeroRoster.tsx`, `WarRoomPanel.tsx`, `ScrollShelf.tsx`, `ToastTray` - ceremony hooks only, logic untouched. Emissary reads the shipped channel intake (`apps/server/src/managers/channelCommandManager.ts` surfaces, `channelCommandValidation.ts`) through the existing orchestration store slices. Audio ceremonies route through `useVoiceBarks` / `useFactionVoiceLine` / `audioRuntime.ts`, inheriting opt-in, rate-limit, and fallback posture (section 12A). **Exit:** dogfood self-report - each verb used once feels distinct with eyes closed (audio) and motion off (static twins). ## Phase 5 - Banners, XP & Class Advantage **Goal:** progression turns on; sessions produce visible growth. * XP formula (complexity x verification x swift x class-advantage, section 6/section 6A/section 9), levels, titles pipeline via the achievements engine. * Swift Command timing capture; banner planting on verified completion; banner/trophy regalia (`hero_evidence_update`). * **Class Advantage** derivation (heroSpecialization x quest tags), affinity flare + XP bonus + class barks; advantage-never-gate guard. * **Battle Report v1**: SessionRollup reskin - territory delta, banners, MVP, efficiency grade (self-relative, section 9). **Code anchors.** New: `apps/web/src/lib/classAdvantage.ts` (pure fn over `heroSpecialization.ts` roles x `missionTags.ts` tags x quest source - all verified vocabulary). Touched: `gameProjection.ts` (XP/banner/swift cases composing `missionComplexity.ts` tiers and `plan_verification_complete`/`task_verification` events), `SessionRollup.tsx` (reskin; its `sessionStats()` is the stats card), `HeroDetailDrawer.tsx` + `HeroCard.tsx` (level/title display). Titles trigger client-side in the projection but display mirrors the achievements gallery grouping patterns (`AchievementsGallery.tsx` + its two test files). **Exit:** a normal work session ends with a Battle Report a player wants to screenshot; anti-Goodhart checks (section 9.1-9.5) verified by test. ## Phase 6 - Stakes & The Return Loop **Goal:** sessions get a beginning, middle, and end; absence is narrated. * **War Council** (section 4B): deterministic objective picker, one re-roll, ceremony on completion, declared-vs-achieved ledger opening the Battle Report. * **War Tide meter** (section 4): trailing-window gains/losses, three-state read, signed-chip static twin. * **Dawn Report** (section 4/section 16): snapshot-diff composer + recap-event vocabulary, sequenced through `dispatchReplayEntries`; ends focused on the top `alertFocus`. * **First Ten Minutes** scripted onboarding (section 4): oath framing, first banner, the single-camp reveal withhold. **Code anchors.** New: `apps/web/src/lib/warCouncil.ts` (deterministic picker over projection + Quest Board model), `apps/web/src/lib/dawnReport.ts` (persisted-projection vs fresh-hydration diff -> synthetic recap entries). The sequencer is **reused verbatim**: `dispatchReplayEntries` in `replayLink.ts` (536 lines) already does cadence-scaled dispatch with gap capping and the replaying-flag guard (section 16, code-verified third pass). Touched: `gameProjection.ts` (`warTide`, `council` fields), `SessionRollup.tsx` (ledger opening), onboarding touches `FactionPicker.tsx` + `App.tsx` first-run path only. **Exit:** cold-open after 12 hours away -> the \~20s recap answers "what happened, are we winning, what needs me" without reading any feed. ## Phase 7 - The Living Map **Goal:** the board becomes a persistent territory of the actual repo. * Sector model: directory hashing into the capped grid, small-repo deepening / monorepo Borderlands aggregation (section 14.3). * Fog push on mission touch, slow re-fog, corruption on new findings; frontline-delta framing (section 5). * Building levels from cumulative output; **essence economy** live: income + burst decay, automatic tithe, capped cosmetic treasury (section 7A). * Patrol routes for recurring loops (`loop_update`); multi-front tabs for multi-project play (section 5). **Code anchors.** New: `apps/web/src/lib/territory.ts` (sector hashing + fog math; path aggregation borrows the file-path bucketing already proven in `missionHeatmap.ts`), sector/fog DOM layer beside `CampLayer.tsx`. Touched: `gameProjection.ts` (`sectors`, `essence`, `buildings` cases), `battlefield2d.ts` (grid helpers only if needed - clamp model stays). Multi-front grouping keys off the hero's recorded working directory (`packages/protocol/src/heroes.ts` - verified field). Essence/burst decay composes the `toolUsage.ts` taxonomy (filesystem/shell/search/web/ planning/MCP classes already shipped). **Exit:** two weeks of normal use produces a map that visibly belongs to *this* repo and *this* player; essence has no dead numbers. ## Phase 8 - Loot & Legends **Goal:** the collection/retention backbone plus enemy drama. * Loot rolls on mission complete (celebration choreography, honest odds, section 7); tome expansion packs; relics with keep display + cosmetic auras. * Hero quirks (deterministic from session id) and the **Hall of Banners** enshrinement flow (section 6). * **Named Nemeses** (section 10): promotion rules over existing camp-scar / skirmisher / wraith state, deterministic name table, Dawn Report mentions, relic + "Bane of " title on verified kill. **Code anchors.** Tome expansion extends the trigger map in `packages/protocol/src/scrolls.ts` + `apps/server/src/managers/scrolls.ts` (the one phase with protocol-adjacent server work; collection/idempotency flows already tested). New: `apps/web/src/lib/nemesisNames.ts` - a client-side deterministic table mirroring the faction-name pattern that already exists in `apps/server/src/lib/names.ts`. Quirks seed from the hero's `sessionId` (verified stable field). Hall of Banners is a new gallery component following the `AchievementsGallery.tsx` grouping/ collapse conventions. Touched: `gameProjection.ts` (`nemeses`, relic triggers), `HeroDetailDrawer.tsx` (regalia). **Exit:** a recurring failure gets named within a week of dogfooding, and its kill is the best moment of that week (self-report). ## Phase 9 - Bosses & Dynamic Audio **Goal:** peak-fun punctuation and a soundtrack that knows the war state. * **Blight Titan** weekly boss from the entrenched-camp pool; **Siege** set piece from stall escalations (section 10). * Boss standee art through the media pipeline + provenance gates (section 11). * Dynamic music layering: calm/idle mix, percussion per active hero, horns on flares/sieges (section 11); world SFX recorded cues replace synth fallbacks as they land. **Code anchors.** Titan/Siege are projection derivations over fields that already exist by this phase (`entrenchedScans` pool, `siege` level) - new rendering in the effects/camp layers, no new data. Boss art enters via `mediaCatalog.ts` + the provenance gates (the only new-art path the design permits, section 5B). Music layering extends `backgroundMusic.ts` / `useBackgroundMusic.ts` (12-track playlist, opt-in/resume posture verified section 12A); layer selection reads projection state, not raw events. **Exit:** boss weeks feel different from normal weeks with the sound off *and* with the screen off. ## Phase 10 - The Alliance War **Goal:** multiplayer meaning over the shipped War Room. * Allied standees on the shared front (redacted federation); Banners Unite ceremony (section 8). * **World Boss**: campaign task queue as shared HP bar, loot-for-all on kill (section 8). * Seasonal **faction league** over FactionStandings across rooms; tavern framing for Notice Board contracts (section 8). * Resolve the section 16 redaction question: exactly what score/state is shareable. **Code anchors.** The room/presence/federation stack is fully shipped: `apps/warroom/` worker, `warRoomClient.ts`, `warRoomFederation.ts`, `warRoomPresence.ts`, `useWarRoomStore.ts`, `RemoteParticipantOverlay.tsx` (allied markers already render on the board). World Boss HP reads campaign/queue state from `packages/protocol/src/taskQueue.ts` + `planCampaignManager.ts` surfaces. League aggregates `factionStandings.ts` outputs across the room's safe outbound frames - any new shared fields must pass the same validation posture as existing frames (`packages/protocol/src/warroom.ts`). Redaction answer must respect `sessionPrivacy.ts` / `llmPrivacy.ts` boundaries. **Exit:** two cockpits in one room both read the same war truthfully, and nothing leaks beyond the existing federation redaction posture. ## Phase 11 - Seasons & Saga **Goal:** the long game - prestige without loss. * Season rollover: chronicle entry, veteran retirement to the Hall, re-fog with Legion strength scaled to the current issue census (section 4). * Saga chronicle surface; illuminated saga pages as the treasury's flagship sink (section 7A); slain nemeses auto-enter the saga (section 16). * Golden Age celebration state for clean-repo seasons (section 5B). **Code anchors.** Season state is the projection's `season` field plus a rollover reducer case; the chronicle is a new gallery-style component (same conventions as Phase 8's Hall). Cross-device season persistence is the moment to ride `hostedPersistence.ts` (client lib + server lib both exist) beyond localStorage - the section 15A posture explicitly deferred this until a phase needed it; this is that phase. Treasury spend actions are client-local cosmetics in the projection (no protocol change). **Exit:** a season ends and the player keeps everything that mattered, loses nothing real, and wants to see the next map. ## Phase 12 - War Games, Demo & Hardening **Goal:** the game is visible pre-install, and the whole package holds up. * **War Games** synthetic front for the public demo (mock-generator substrate, section 5B) - clearly bannered, progress-inert (mirrors section 14.9). * Full section 13A acceptance re-run across all shipped phases; perf/fatigue tuning sweep of every rate limiter and cap. * Burn down the section 16 tuning questions that required playtest data: essence rates, affinity bonus size, council heuristics, tide window, nemesis name table. **Code anchors.** The engine is `apps/server/src/managers/mockEventGenerator.ts` (shipped) driven by the `mockEnabled` knob in `useSettingsStore.ts`. Grounding caveat (verified): mock events are **indistinguishable on the wire**, so the progress-inert guard keys off the client's `mockEnabled` setting - when set, the projection folds for spectacle but persistence is disabled (same shape as the `isReplaying` no-accumulate guard). Demo parity follows the existing static-demo pattern the docs cite (section 5B). The tuning sweep touches only constants in `gameProjection.ts` / `legionCamps.ts` / `warCouncil.ts` - by design, every tunable landed in pure modules with focused tests. **Exit:** a stranger opening the public demo understands the fantasy in 60 seconds; a two-hour real session produces zero mute-the-tab impulses. *** *Update log:* * 2026-07-03 - Initial phase outline: 12 session-sized phases covering the full design package, refining doc 08's fun-ordered Phases A-F into \~800k-token implementation windows with dependencies and exit criteria. * 2026-07-03 (second pass, code-grounded) - Verified the plan against the codebase: all 20 design-cited events confirmed in `events.ts`; added the Grounding Notes index (module sizes, verified symbols, test conventions) and per-phase **Code anchors** blocks naming new modules, touched files, and shipped patterns to mirror. Material findings folded in: projection must live in `apps/web/src/lib/` (the store was 3,640 lines at that pass); `achievementCelebration.ts` is the board-effects pattern; the mock substrate is `mockEventGenerator.ts` + `mockEnabled` and the War Games progress-inert guard must key off the setting (mock events are wire-indistinguishable); `names.ts` grounds the nemesis name table; heroes' recorded working directory grounds multi-front; Phase 11 is where `hostedPersistence.ts` graduates the projection beyond localStorage. * 2026-07-05 (Phase 22 closeout sync) - Removed design Phase 1 from the pending backlog because it shipped as spec-system Phase 22. At that time, the remaining backlog started at Phase 2 and depended on the implemented projection authority in `apps/web/src/lib/gameProjection.ts`. Code-grounding was refreshed: `gameProjection.ts` is 2,088 lines, `useGameStore.ts` is 3,806 lines, `apps/web/src/lib/` has 68 files, and `apps/web/tests/` has 138 files. Phase 22 also proved replay no-progress, mock no-persist, browser-local erasure for `localStorage["factionos-game-v1"]`, and the no-claim boundary for rendering, hosted persistence, new protocol events, camp execution, and trusted unified erasure. * 2026-07-05 (Phase 23 closeout sync) - Removed design Phase 2 from the pending backlog because Legion I shipped as spec-system Phase 23. The remaining backlog now starts at Phase 3 and depends on the implemented scanner camp baseline: `suggestion_update` camp reconciliation, Battlefield camp rendering, Quest Board inspection, dry Banish, Dispatch Scouts, Golden Age, reduced-motion parity, replay no-progress, mock no-persist, aggregate-only projection storage, and no new protocol, hosted, reward, public-demo synthetic, or trusted-erasure claims. Session 08 implementation evidence lives in `.spec_system/specs/phase23-session08-validation-and-documentation/phase-exit-audit.md`. * 2026-07-08 (Phase 24 phasebuild sync) - Design Phase 3 was phasebuilt as spec-system Phase 24 with nine sessions (pure strike/combo model, camp-mission linkage, live enemy presentation, combat playback effects layer, scrying and alert focus, world cues and bark reuse, honesty and persistence boundaries, generated asset implementation, validation and documentation). Code anchors were re-verified at phasebuild: the reducer already folded all live-enemy events and held `pendingLinks`/`campLinks` substrate, but the accept/assign pending-link gap, effects layer, scrying posture, world-cue bucket, and Phase 3 generated-asset implementation handoff still needed session work. At that time, Phase 3 stayed in this backlog until Phase 24 sessions recorded validation evidence. * 2026-07-08 (Phase 24 progress sync) - Rechecked the spec analyzer, Phase 24 PRD, and Phase 24 session specs. Official workflow state at that pass was `current_phase: 24`, current session `phase24-session03-live-enemy-presentation`, and completed sessions through Session 02. Session 01 validated the pure `combatPlayback.ts` model; Session 02 validated camp-mission linkage and closed the pending-link gap; Session 03 implementation notes and checklist show live-enemy presentation code and tests complete, including `test_pass` skirmisher clearing. This entry was superseded by the Session 09 closeout sync below. * 2026-07-08 (Phase 24 closeout sync) - Removed design Phase 3 from the pending backlog after Session 09 recorded implementation-evidence PASS in `.spec_system/specs/phase24-session09-validation-and-documentation/phase-exit-audit.md`. The focused Phase 24 validation command passed 17 files / 238 tests; root tests passed 3395 with 1 skipped and 0 failed; web and workspace typechecks, root format, root lint, generated asset catalog tests, and generated source-path runtime scans also passed. The remaining game-design backlog now starts at Phase 4 and depends on the implemented Phase 3 / spec-system Phase 24 evidence baseline, including the explicit `test_pass` protocol event and typed generated Phase 3 asset references. Code review, validation, and `updateprd` closeout are resolved. --- # 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/docs/game-design/15-phases-yet-to-be-implemented.md?ask=&goal= ``` `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.