> 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_23/prd_phase_23.md). # PRD Phase 23: Legion I - Scanner Camps **Status**: Complete **Sessions**: 8 (initial estimate) **Estimated Duration**: 4-8 days **Progress**: 8/8 sessions (100%) *** ## Overview Phase 23 makes scanner findings visible as honest enemy camps on the `apps/web` battlefield. Current Quest Board scanner issue snapshots become aggregate Null Legion Blight camps through the existing `suggestion_update` event and the existing `GameProjection` authority. The phase adds camp coalescing, Champion Mode ranking, projection folding, persistence regression coverage, Quest Board inspection and Banish, a battlefield camp layer, Dispatch Scouts and Golden Age states, and final validation. The phase does not add a second game-state authority, new protocol events, new storage keys, hosted state, trusted-erasure claims, live combat playback, XP, loot, achievements, camp damage, bosses, seasons, audio requirements, or public demo synthetic fronts. Source status: complete. Source scope: web cockpit game layer. Source goal: make scanner findings visible as honest enemy camps on the battlefield. At the end of the phase, a player should be able to glance at the battlefield, see where technical debt is concentrated, open each camp into the real issues behind it, dismiss unwanted debt through a deliberately dry Banish action, and see an explicit Golden Age treatment when the scanner finds nothing. *** ## Phase-Wide Source Context The previous foundation work already established the game projection as one browser-local, versioned, derived aggregate. Game-design Phase 2 extends that authority; it does not create a parallel game state, event log, persistence key, or hosted state path. Available foundation: * `GameProjection` already exists and is folded through the normal web event apply path. * The web store already exposes projection selectors for the projection, Legion state, and alert focus. * Projection persistence already uses `localStorage["factionos-game-v1"]` with replay, mock-mode, and browser-local erasure safeguards. * `suggestion_update` already reaches the projection path but currently leaves `legion.camps` unchanged. This phase replaces that no-op with camp reconciliation. * Quest Board scanners, scan triggers, scan status, scan root selection, ignore patterns, safe file labels, codebase issue cards, issue dismissal, and quest actions already exist. * Manual, daily, and triggered scan outcomes all reach the same Quest Board snapshot path. Manual scan starts get Dispatch Scouts presentation; scanner completion outcomes reconcile camps through `suggestion_update`. * The battlefield is a 2D, 16:9 DOM/CSS board. Hero tokens are native buttons, empty terrain clears selection, reduced-motion settings are available, and visible hero selection is already capped at 12 and prioritized. The enemy layer is the Null Legion. Scanner findings become Blight camps: visible manifestations of broken, unfinished, or rotting work in the actual repository. The scanner layer is the slow strategic tempo of the Legion. It is different from later live enemies driven by test, build, lint, mission, or tool events. The core rule is honesty. Every rendered camp must trace to real current issue data, and every visible game element from this phase must inspect through to its real source. No fake danger, no fake progress, no grindable click, and no urgency that is not backed by work state. *** ## Phase-Wide Guardrails * Do not add live combat playback, strike animations, camp damage from mission events, XP, loot, Battle Report changes, War Council objectives, Dawn Report recap, seasons, nemeses, bosses, or dynamic audio. * Do not add live skirmishers, rams, gremlins, wraiths, siege engines, essence, War Tide, class advantage, target-flag muster ceremony, camp burn-down, relics, title progress, Hall of Banners changes, territory clearing, building levels, multi-front tabs, or public-demo synthetic fronts. * Do not add new protocol events. Use the existing `suggestion_update` snapshot and existing Quest Board actions. * Do not create a second game-state authority. Camp state must fold into `GameProjection`. * Do not fabricate enemy camps for clean repositories. A clean scan is a positive Golden Age state, not fake danger. * Do not reward Banish with progress, XP, loot, banners, achievements, or camp kill credit. * Do not turn scan errors, disabled scan gating, provider health, ignore-pattern validation, reset controls, or diagnostics into game rules. Those remain utility/admin state. * Do not implement the new-player first-ten-minutes reveal pacing or the return loop recap. If those surfaces are touched, keep their existing behavior and do not block game-design Phase 2 camps behind a later onboarding rule. *** ## Phase Requirement Coverage Inventory * Scanner findings become Blight camps through `suggestion_update` reconciliation in Session 03, using the pure coalescing logic from Session 01. * Camps coalesce by safe repository sector, use HP from severity weights, tier into camp/fort/citadel, and keep entrenchment counters in Session 01. * Sector count stays readable for tiny and giant repositories through deeper safe splitting, workspace grouping, and a bounded `Borderlands` fallback in Session 01. * Champion Mode is handled in Session 02 and rendered in Session 06: one-hero and two-hero boards show a small prioritized camp set and singular champion language, while the full issue census remains in Quest Board. * Camp inspection and Banish are handled in Session 05 through existing Quest Board cards and dismissal actions, with no rewards or new server route. * The battlefield camp layer is handled in Session 06: accessible camp buttons, stable placement, CSS-only markers, camp/fort/citadel readability, HP and issue chips, reduced-motion static equivalents, and board-internal ordering below hero tokens. * Entrenched camps are made quieter in Sessions 01, 02, and 06: counters remain the source of truth, ranking lowers stale camps, and rendering mutes or edge-places them without creating bosses, rewards, or Dawn Report behavior. * Dispatch Scouts, scan-not-run, scan-failed, clean-scan, and Golden Age states are handled in Session 07 without moving scan configuration into the battlefield. * Replay, reconnect, mock mode, browser-local persistence, local erasure, aggregate-only projection data, and no hosted or trusted-erasure claims are verified in Sessions 04 and 08. * Final proof is handled in Session 08: focused tests, typecheck, formatting, fun audit, privacy audit, exit criteria, and documentation updates after validation. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | ---------------------------------- | -------- | ---------- | ---------- | | 01 | Pure Camp Reconciliation | Complete | \~18 | 2026-07-05 | | 02 | Ranking And Presentation Selectors | Complete | \~15 | 2026-07-05 | | 03 | Projection Folding | Complete | \~20 | 2026-07-05 | | 04 | Store Persistence Boundaries | Complete | \~14 | 2026-07-05 | | 05 | Quest Board Camp Focus | Complete | \~18 | 2026-07-05 | | 06 | Battlefield Camp Layer | Complete | \~22 | 2026-07-05 | | 07 | Scanner And Golden Age States | Complete | \~18 | 2026-07-05 | | 08 | Validation And Documentation | Complete | \~16 | 2026-07-05 | *** ## Completed Sessions * Session 01: Pure Camp Reconciliation - Completed 2026-07-05. * Session 02: Ranking And Presentation Selectors - Completed 2026-07-05. * Session 03: Projection Folding - Completed 2026-07-05. * Session 04: Store Persistence Boundaries - Completed 2026-07-05. * Session 05: Quest Board Camp Focus - Completed 2026-07-05. * Session 06: Battlefield Camp Layer - Completed 2026-07-05. * Session 07: Scanner And Golden Age States - Completed 2026-07-05. * Session 08: Validation And Documentation - Completed 2026-07-05. *** ## Upcoming Sessions * None - phase complete. *** ## Session Dependency Split | Session | Title | Depends On | | ------- | ---------------------------------- | -------------- | | 01 | Pure Camp Reconciliation | None | | 02 | Ranking And Presentation Selectors | 01 | | 03 | Projection Folding | 01 | | 04 | Store Persistence Boundaries | 03 | | 05 | Quest Board Camp Focus | 03 | | 06 | Battlefield Camp Layer | 02, 03, 05 | | 07 | Scanner And Golden Age States | 06 | | 08 | Validation And Documentation | 04, 05, 06, 07 | *** ## Objectives 1. Convert current scanner issue snapshots into stable, safe, aggregate Blight camps in the existing `GameProjection`. 2. Render readable and accessible battlefield camps that inspect into real Quest Board issue cards and support dry Banish through existing dismissal actions. 3. Preserve the Phase 22 honesty, replay, mock, persistence, local-erasure, privacy, protocol, and no-claim boundaries while adding scan and clean-state presentation. *** ## Prerequisites * Phase 22 completed: Projection Foundation. * Existing Quest Board scanner snapshots, scan status, issue cards, and dismiss actions remain available. * Existing `apps/web` projection persistence uses `localStorage["factionos-game-v1"]` with replay, mock-mode, reset, and browser-local erasure safeguards. *** ## Planning Assumptions And Resolutions ### Working Assumptions * The supplied Legion I session plan is the source-backed next phase: the user invoked phasebuild with that file, and the game-design backlog defines Legion I - Scanner Camps as the next dependency after the shipped projection foundation. * Spec-system Phase 23 maps to game-design Phase 2: the master PRD already records that design Phase 1 shipped as spec-system Phase 22, and the game backlog says Legion I depends on the implemented projection foundation. * The primary package is `apps/web`: the supplied plan scopes the work to the web cockpit game layer, and all primary code anchors are web library, store, battlefield, Quest Board, settings, and test files. * Existing Quest Board and scanner contracts are sufficient for planning: the plan requires no new protocol event or server route and falls back when hero-to-sector or audio hooks are unavailable. * `CodebaseIssue` exposes stable issue ids, severity, and either `filePath` or a safe file label sufficient for relative sector derivation. * Existing scan status, scan trigger state, Quest Board issue cards, and dismiss actions are accessible from the web cockpit without new protocol events or server routes. * The existing mock-mode persistence guard remains the authoritative mechanism that prevents drill camps from persisting. ### Open Questions * The exact mapping from selected hero active context to a sector may not exist yet; if unavailable, ranking should use the documented fallback order. * A safe, rate-limited audio hook may or may not already exist; this phase should skip audio unless that hook is already available. * The exact shipped documentation and game phase ledgers to update should be confirmed from the repo during Session 08 after validation passes. ### Conflict Resolutions * Master PRD and state tracking stopped at completed Phase 22, while the supplied plan and game-design backlog define the next phase. The chosen interpretation is to create Phase 23 from the explicit Legion I source and reconcile master PRD plus state tracking in this run. * Phase 22 intentionally made `suggestion_update` a no-op for camps, while Legion I requires camp reconciliation. The chosen interpretation is that Phase 23 replaces the no-op with snapshot reconciliation only, preserving no rewards, no camp damage, no mission links, no new storage, and no protocol expansion. *** ## Technical Considerations ### Architecture The existing `GameProjection` remains the only derived game-state authority. Camp state folds through normal web event application and stores only bounded aggregate fields: issue ids, safe relative sector labels, HP, tier, entrenchment counters, scar percentage, cells, and timestamps. Quest Board continues to own rich issue details and scanner actions. ### Technologies * `apps/web/src/lib/gameProjection.ts` * `apps/web/src/lib/legionCamps.ts` * `apps/web/src/store/useGameStore.ts` * `apps/web/src/components/battlefield/Battlefield.tsx` * `apps/web/src/components/battlefield/CampLayer.tsx` * Existing Quest Board scanner and dismiss action modules * Vitest and React Testing Library ### Risks * Fake urgency or fake progress: mitigate by requiring every camp to map to real current issue ids and by forbidding rewards, XP, loot, kills, damage, or achievements. * Projection privacy leak: mitigate by storing only aggregate ids and safe relative labels, never raw issue messages, prompts, transcripts, event bodies, terminal output, provider payloads, file contents, absolute paths, environment values, or secrets. * Replay or mock persistence drift: mitigate with reducer and store tests that prove replayed snapshots do not mutate camps and mock camps do not persist. * Battlefield clutter or occlusion: mitigate with Champion Mode ranking, stable sector placement, reduced-motion static equivalents, and component tests across common desktop and mobile board sizes. ### Relevant Considerations * \[P22-apps/web] **Game projection is the single derived authority**: Camp reconciliation and presentation must read and fold through `gameProjection.ts` selectors instead of creating parallel state. * \[P22-apps/web] **Derived projection storage is narrow**: Camp persistence must stay inside the existing `factionos-game-v1` aggregate boundary and reuse reset/browser-local erasure behavior. * \[P22-apps/web] **Do not add parallel game authorities**: Battlefield and Quest Board work must avoid copied camp, progress, or enemy state outside the projection and existing issue cards. * \[P22-apps/web] **Do not persist replay or drill progress**: Replay, reconnect, mock mode, and scanner snapshots must not mint durable progress, rewards, kills, titles, essence, banners, or War Tide. * \[P18-apps/server] **Quest Board state is durable local evidence**: Banish and inspection must use existing Quest Board issue ids, cards, and dismissal semantics without broadening trusted-erasure claims. * \[P07] **Redaction is boundary-specific**: New projection, UI, tests, docs, and evidence must keep raw commands, terminal output, file contents, provider payloads, secrets, and broad absolute paths out of broad surfaces. *** ## Success Criteria Phase complete when: * [ ] All 8 sessions completed. * [ ] Real scanner snapshots with codebase issues create visible battlefield camps through the normal event flow. * [ ] Every rendered camp maps to at least one real current issue id and opens the matching Quest Board issue set. * [ ] Large issue sets coalesce into bounded, readable sector camps with safe relative labels. * [ ] Banish dismisses real issues through existing Quest Board actions and grants no progress, reward, or kill credit. * [ ] One-hero and two-hero boards show a small prioritized camp set, not the full issue census. * [ ] Clean scans show Golden Age rather than fake enemies, and not-yet-scanned state does not masquerade as clean. * [ ] Reduced-motion mode has complete static equivalents. * [ ] Replay and mock mode cannot persist synthetic camp progress. * [ ] No new protocol event, storage key, hosted dependency, or trusted-erasure claim is introduced. * [ ] Focused tests, web typecheck, and formatting checks pass. *** ## Dependencies ### Depends On * Phase 22: Projection Foundation. ### Enables * Phase 24: Legion II - Live Tier And Combat Playback. --- # 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_23/prd_phase_23.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.