> 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/sessions/phase23-session08-validation-and-documentation/spec.md). # Session Specification **Session ID**: `phase23-session08-validation-and-documentation` **Phase**: 23 - Legion I - Scanner Camps **Status**: Not Started **Created**: 2026-07-05 **Base Commit**: `ba6c30994180c399dd3d68607812867fbe7b001c` **Package**: apps/web **Package Stack**: TypeScript *** ## 1. Session Overview This session closes Phase 23 by proving the scanner camp implementation as a coherent shipped slice. Sessions 01-07 already added pure camp reconciliation, ranking selectors, projection folding, persistence guards, Quest Board focus and Banish, battlefield rendering, and scanner lifecycle states. Session 08 does not add a new feature; it runs the focused validation commands, audits the honesty and privacy boundaries, fixes only in-scope regressions if the checks expose them, and then updates stable documentation after evidence passes. It is next because the analyzer reports Phase 23 in progress with Sessions 01-07 complete and only Session 08 unfinished. The session depends on the validated store, Quest Board, battlefield, and scanner-state work from Sessions 04-07, and it prepares the phase for the formal `validate` and `updateprd` workflow steps. The closeout must preserve the phase guardrails: no new protocol event, no new storage key, no hosted dependency, no trusted-erasure claim, no fake enemy camps, no Banish reward, no replay or mock-mode progress, and no raw issue text or sensitive developer data copied into projection state. *** ## 2. Objectives 1. Prove the focused Legion I test, typecheck, and formatting gates pass for the implemented `apps/web` scanner camp slice. 2. Audit privacy, security, persistence, replay, reconnect, mock mode, Banish, and reduced-motion behavior against the Phase 23 exit criteria. 3. Capture a phase-exit evidence matrix that maps each shipped behavior to tests, inspections, and residual no-claim boundaries. 4. Update stable docs and game-design ledgers after validation evidence exists, without marking workflow completion before `updateprd`. *** ## 3. Prerequisites ### Required Sessions * [x] `phase23-session04-store-persistence-boundaries` - proves camp projection persistence stays in `localStorage["factionos-game-v1"]`, and replay/mock traffic cannot persist synthetic camp progress. * [x] `phase23-session05-quest-board-camp-focus` - provides camp inspection and dry Banish through existing Quest Board issue dismissal paths. * [x] `phase23-session06-battlefield-camp-layer` - renders accessible ranked camps on the battlefield with reduced-motion equivalents and product-facing copy. * [x] `phase23-session07-scanner-and-golden-age-states` - adds Dispatch Scouts, scan-not-run, scan-failed, Golden Age, mock drill, and zero-hero scanner-state presentation. ### Required Tools Or Knowledge * Node 26.2.0 or newer and npm 11.16.0. * Vitest, TypeScript `tsc`, and Biome through npm workspace scripts. * Phase 23 code anchors: `apps/web/src/lib/legionCamps.ts`, `apps/web/src/lib/gameProjection.ts`, `apps/web/src/lib/battlefieldScannerState.ts`, `apps/web/src/components/battlefield/CampLayer.tsx`, `apps/web/src/components/battlefield/ScannerStateLayer.tsx`, `apps/web/src/components/battlefield/Battlefield.tsx`, `apps/web/src/components/QuestBoard.tsx`, and `apps/web/src/lib/questBoardActions.ts`. * Phase 23 focused tests: `apps/web/tests/legionCamps.test.ts`, `apps/web/tests/gameProjection.test.ts`, `apps/web/tests/gameProjectionStore.test.ts`, `apps/web/tests/Battlefield.test.tsx`, `apps/web/tests/QuestBoard.test.tsx`, `apps/web/tests/questBoardActions.test.ts`, and `apps/web/tests/SettingsScan.test.tsx`. ### Environment Requirements * Commands run from the repository root. * Root workspace dependencies installed. * No Cloudflare, hosted identity, production-hosted validation, provider credentials, database, migration, or external dashboard access is required. *** ## 4. Scope ### In Scope (MVP) * Run the repo-supported focused Phase 23 web test command: `npm test -- apps/web/tests/legionCamps.test.ts apps/web/tests/gameProjection.test.ts apps/web/tests/gameProjectionStore.test.ts apps/web/tests/Battlefield.test.tsx apps/web/tests/QuestBoard.test.tsx apps/web/tests/questBoardActions.test.ts apps/web/tests/SettingsScan.test.tsx`. * Run `npm --workspace @factionos/web run typecheck`. * Run `npm run format:check`. * Run broader tests only if validation fixes touch shared store, Quest Board, or battlefield behavior outside the listed focused files. * Audit that projection state stores only safe issue ids, relative sector labels, HP, tier, counters, and timestamps. * Audit that projection state does not store raw issue messages, suggested prompts, mission prompts, transcripts, replay entries, event bodies, terminal output, provider payloads, file contents, absolute paths, environment values, or secrets. * Verify the existing projection storage key remains `localStorage["factionos-game-v1"]`, with no new storage key or hosted dependency. * Verify camp inspection opens real Quest Board issue sets and Banish uses the existing dry issue dismissal path without rewards. * Verify replay, reconnect, mock mode, and Banish cannot create progress, rewards, camp kills, or persisted synthetic camps. * Verify reduced-motion mode presents complete static equivalents for camp and scanner-state information. * Fix validation regressions only when they are inside Phase 23's planned `apps/web` scope. * Update shipped docs and game-design ledgers only after validation evidence passes. ### Out Of Scope (Deferred) * New game features, live combat playback, camp damage, strike animations, XP, loot, achievements, banners, bosses, seasons, audio requirements, War Tide, Dawn Report changes, or public-demo synthetic fronts - Reason: later phases own these mechanics. * New protocol events, server routes, storage keys, hosted state, hosted identity, or production-hosted validation - Reason: Phase 23 is a web projection, Quest Board, and battlefield slice using existing events. * Trusted unified erasure claims - Reason: projection erasure remains browser-local only and cumulative trusted erasure stays no-claim. * Recording aspirational behavior as shipped before validation - Reason: docs updates must be backed by command output, tests, and source inspection. * Formal mobile/WCAG certification or legal/privacy owner approval - Reason: existing release posture keeps those as no-claim until owner evidence exists. *** ## 5. Technical Approach ### Architecture Use validation-first closeout. Start with the prescribed focused Vitest command, web typecheck, and root formatting check. If those pass without code changes, capture their outputs in `implementation-notes.md` and use source inspection plus existing tests to fill a phase-exit audit matrix. If a focused check fails because of an in-scope Phase 23 regression, fix the smallest affected `apps/web` file, rerun the focused check, and broaden tests only for the behavior that was touched. Create `phase-exit-audit.md` as the phase-local evidence ledger. It should map each Phase 23 exit criterion to the command, test file, or code inspection that proves it. The matrix must explicitly cover the fun audit: one-second glance classification, camp source inspection, replay/reconnect/mock/Banish honesty, event-free calm state, and reduced-motion parity. Update docs after evidence exists. The stable web docs should describe the shipped scanner camp layer, dry Banish, Dispatch Scouts, Golden Age, storage, and no-claim boundaries. The game-design ledgers should move Legion I from pending to implemented with evidence links. Spec-system state completion, phase archive movement, version bumping, commit, and push remain the responsibility of the later `updateprd` command after workflow validation passes. ### Design Patterns * Evidence-led documentation: stable docs change only where tests or source inspection prove behavior. * Narrow regression repair: fix only Phase 23 `apps/web` files when validation exposes an in-scope regression. * Single projection authority: all camp truth remains in `gameProjection.ts` and derived selectors; no parallel camp state or persistence path. * No-overclaim closeout: docs keep hosted, production, legal, certification, and trusted-erasure claims unavailable unless a scoped future phase proves them. * Product-surface discipline: scanner camp docs and UI references describe product behavior, not diagnostics or implementation debug surfaces. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase23-session08-validation-and-documentation/implementation-notes.md` | Record command outputs, regression decisions, documentation updates, and closeout notes. | \~180 | | `.spec_system/specs/phase23-session08-validation-and-documentation/phase-exit-audit.md` | Map Phase 23 exit criteria, fun audit, privacy/security checks, and no-claim boundaries to evidence. | \~220 | ### Files To Modify | File | Changes | Est. Lines | | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/web/README_web.md` | Document shipped scanner camp, Dispatch Scouts, Golden Age, dry Banish, and projection storage boundaries after validation. | \~45 | | `docs/battlefield.md` | Add current battlefield camp layer, scanner-state, inspection, Banish, and reduced-motion behavior. | \~45 | | `docs/privacy-and-security.md` | Record aggregate-only camp projection data, excluded raw data categories, browser-local storage, and trusted-erasure no-claim wording. | \~35 | | `docs/ARCHITECTURE.md` | Align the architecture/data-flow summary with scanner camp reconciliation through `suggestion_update` and `GameProjection`. | \~30 | | `docs/game-design/14-implemented-phases.md` | Add Phase 23 implementation evidence after validation passes. | \~40 | | `docs/game-design/15-phases-yet-to-be-implemented.md` | Remove Legion I from the remaining-phase table and update dependency notes for later phases. | \~35 | | `docs/game-design/11-open-questions-and-change-log.md` | Add a Phase 23 closeout change-log entry with no-overclaim boundaries. | \~25 | | `.spec_system/PRD/PRD.md` | Reconcile Phase 23 status wording after validation evidence, without replacing `updateprd` completion bookkeeping. | \~20 | ### Conditional Files To Modify | File | Changes | Est. Lines | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/web/src/lib/legionCamps.ts` | Apply in-scope fixes only if focused validation exposes camp coalescing, ranking, or safe-label regressions. | \~30 | | `apps/web/src/lib/gameProjection.ts` | Apply in-scope fixes only if validation exposes projection folding, storage, replay, mock, or failed-scan regressions. | \~30 | | `apps/web/src/components/battlefield/Battlefield.tsx` | Apply in-scope fixes only if validation exposes camp interaction, scanner state, or reduced-motion regressions. | \~40 | | `apps/web/src/components/battlefield/CampLayer.tsx` | Apply in-scope fixes only if validation exposes camp marker accessibility, Banish, or reduced-motion regressions. | \~40 | | `apps/web/src/components/battlefield/ScannerStateLayer.tsx` | Apply in-scope fixes only if validation exposes Dispatch Scouts, Golden Age, failed-scan, drill, or zero-hero regressions. | \~40 | | `apps/web/src/components/QuestBoard.tsx` | Apply in-scope fixes only if validation exposes camp focus or dry Banish regressions. | \~30 | | `apps/web/src/lib/questBoardActions.ts` | Apply in-scope fixes only if validation exposes Banish issue-id or route handling regressions. | \~20 | | `apps/web/tests/*` | Add or update focused regressions for any in-scope fix required by validation. | \~80 | *** ## 7. Success Criteria ### Functional Requirements * [ ] A real scanner snapshot with codebase issues creates visible battlefield camps through normal `suggestion_update` and projection folding. * [ ] Every rendered camp maps to at least one real current issue id and opens the related Quest Board issue set. * [ ] Large issue sets coalesce into a bounded set of readable sector camps with compact, relative, safe labels. * [ ] Visible copy frames fronts, sectors, and current camp counts instead of an overwhelming total debt number. * [ ] Entrenched camps are quieter but remain inspectable and do not create bosses, rewards, Dawn Report behavior, or progress. * [ ] Banish dismisses real issues through existing Quest Board actions and gives no game reward. * [ ] One-hero and two-hero rosters show a small prioritized camp set instead of the full census. * [ ] A clean scan shows Golden Age; a not-yet-scanned state does not masquerade as Golden Age. * [ ] Reduced-motion mode has complete static equivalents. * [ ] Replay cannot mutate or persist camp progress. * [ ] Mock mode can show camps in memory but cannot persist them. * [ ] No new protocol event, storage key, hosted dependency, or trusted-erasure claim is introduced. * [ ] No camp projection stores raw issue text, prompts, transcripts, terminal output, provider payloads, file contents, absolute paths, environment values, or secrets. ### Testing Requirements * [ ] Focused Phase 23 web test command passes. * [ ] `npm --workspace @factionos/web run typecheck` passes. * [ ] `npm run format:check` passes. * [ ] Broader tests are run and pass if in-scope validation fixes touch shared store, Quest Board, or battlefield behavior outside the listed focused files. * [ ] Validation output and any residual external failures are recorded in `implementation-notes.md`. ### Non-Functional Requirements * [ ] `GameProjection` remains the only derived game-state authority for camps. * [ ] Projection storage remains `localStorage["factionos-game-v1"]` only. * [ ] Documentation describes shipped behavior only and preserves hosted, production, certification, legal, and trusted-erasure no-claim boundaries. * [ ] The phase-exit audit records the glance, source, honesty, silence, and reduced-motion fun checks. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code and docs follow project conventions. * [ ] Primary user-facing surfaces contain product-facing copy only. *** ## 8. Implementation Notes ### Working Assumptions * Package context is `apps/web`: the analyzer reports Session 08 with package `apps/web`, the Phase 23 PRD scopes the phase to the web cockpit game layer, and all validation anchors are web package code, tests, and docs. * Documentation updates can proceed after local validation commands pass: the Session 08 stub explicitly requires shipped docs and game ledgers after validation, while `updateprd` remains responsible for formal workflow completion, version bumping, commit, push, and phase archive movement. ### Conflict Resolutions * Master PRD table vs. analyzer and Phase 23 PRD: `.spec_system/PRD/PRD.md` still lists Phase 23 as Not Started, while the analyzer, state tracking, and `.spec_system/PRD/phase_23/PRD_phase_23.md` show Phase 23 in progress with 7 of 8 sessions complete. The analyzer and Phase 23 PRD win for session selection because `plansession` treats analyzer JSON as authoritative state. Reconciliation of stable PRD wording is part of this session's docs scope. * Stub command vs. package scripts: the Session 08 stub names a workspace test command, but `apps/web/package.json` has no `test` script and the repo's validated pattern is root Vitest with explicit test paths. The plan uses `npm test -- apps/web/tests/...` so implementation can run the focused files without changing package scripts. * Game-design pending backlog vs. live implementation evidence: `docs/game-design/15-phases-yet-to-be-implemented.md` still lists Legion I as pending, while Phase 23 session artifacts show Legion I is 7/8 complete. The live specs, tests, and Phase 23 PRD win for planning; the ledger will be updated only after Session 08 validation evidence exists. ### Key Considerations * Documentation must not claim full trusted erasure, production-hosted validation, formal certification, hosted identity, or legal/privacy approval. * Banish is deliberately dry: it can dismiss real Quest Board issues but cannot grant progress, rewards, camp kills, XP, loot, banners, or achievements. * Quest Board may display richer issue cards because it owns those cards; projection state must remain aggregate and safe. * Validation fixes, if needed, must stay inside the Phase 23 web scope unless a failure proves an already-documented external blocker. ### Potential Challenges * Existing broad docs may lag live implementation: mitigate by anchoring each docs update to focused tests, source inspection, or the phase-exit audit. * Focused validation may expose unrelated pre-existing failures: mitigate by rerunning targeted commands, isolating failure scope, and recording external or out-of-scope failures precisely. * Conditional code fixes could broaden test obligations: mitigate by running broader store, Quest Board, or battlefield tests whenever a fix touches shared behavior outside the focused list. ### Relevant Considerations * \[P08] **Full trusted erasure remains no-claim**: Phase 23 must preserve browser-local projection boundaries and avoid broader erasure claims. * \[P22-apps/web] **Derived projection storage is narrow**: `factionos-game-v1` may hold bounded aggregate refs only and must stay out of UI/logs/exports. * \[P22-apps/web] **Game projection is the single derived authority**: camp presentation reads projection selectors instead of creating parallel state. * \[P18-apps/server] **Quest Board state is durable local evidence**: issue dismissal and scanner snapshots remain local evidence with manual deletion, not trusted-erasure proof. * \[P20] **Broad privacy gates are release-critical**: raw commands, terminal output, diffs, file contents, provider payloads, secrets, broad paths, and process internals stay out of broad surfaces. * \[P03] **Stable docs are the current contract**: update stable docs and game ledgers with validated behavior instead of relying on stale pending backlog text. ### Behavioral Quality Focus Checklist active: Yes for validation and any in-scope code fixes. Top behavioral risks for this session: * Validation could pass tests while docs overclaim storage, erasure, hosted, or reward behavior. * A repair to Banish, replay, mock mode, or projection folding could introduce duplicate-trigger, persistence, or rollback regressions. * Scanner and camp UI claims could drift from reduced-motion or source inspection behavior. *** ## 9. Testing Strategy ### Unit Tests * Run the focused Legion I Vitest command covering camp reconciliation, projection folding, store persistence, Battlefield UI, Quest Board UI, Quest Board actions, and Settings scan behavior. * Add or update tests only if validation requires an in-scope code fix. ### Integration Tests * Run broader store, Quest Board, or battlefield tests if a fix touches shared state, shared actions, or component behavior outside the focused files. * Use `npm --workspace @factionos/web run typecheck` to catch contract drift. ### Runtime Verification * Perform source inspections for privacy, storage, replay, reconnect, mock mode, dry Banish, reduced-motion parity, and no new protocol/storage/hosted boundaries. * Record command outputs and inspection conclusions in `implementation-notes.md` and `phase-exit-audit.md`. ### Edge Cases * Scanner failed after existing camps are visible. * Clean scan after a real canonical snapshot. * Not-yet-scanned board with no camps. * One-hero, two-hero, and zero-hero rosters. * Large issue sets with sector coalescing and Borderlands fallback. * Replayed, reconnected, or mock-mode snapshots. * Banish while actions are pending or issue ids are invalid. * Reduced-motion state with no motion-only meaning. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase23-session04-store-persistence-boundaries`, `phase23-session05-quest-board-camp-focus`, `phase23-session06-battlefield-camp-layer`, and `phase23-session07-scanner-and-golden-age-states` * Depended by: Phase Transition `audit` after Session 08 validates and `updateprd` marks Phase 23 complete. *** ## Next Steps Run the `implement` workflow step to begin implementation. --- # 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/sessions/phase23-session08-validation-and-documentation/spec.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.