> 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/specs/phase24-session09-validation-and-documentation/spec.md). # Session Specification **Session ID**: `phase24-session09-validation-and-documentation` **Phase**: 24 - Legion II - Live Tier And Combat Playback **Status**: Not Started **Created**: 2026-07-08 **Base Commit**: 54fa6ae3b2e57d16f9fd4dd646d77458667fd44e **Package**: apps/web **Package Stack**: TypeScript *** ## 1. Session Overview This session closes Phase 24 by validating the live tier and combat playback slice that Sessions 01-08 shipped. The work is verification-first: run focused Phase 24 tests, typecheck, format gates, asset evidence checks, and phase acceptance audits before updating docs. It is next because the analyzer reports Sessions 01-08 complete and Session 09 as the only unfinished candidate. The phase PRD assigns this session the eight section 13A acceptance criteria, Fun Law and privacy audits, stable docs, game-design ledgers, generated-asset evidence, and final implementation notes. The session should leave implementation evidence ready for `creview`, then `validate`, then `updateprd`. It may apply narrow in-scope fixes if validation finds a real regression, but it must not add new Phase 24 features or broaden product claims. *** ## 2. Objectives 1. Run focused Phase 24 validation gates and capture exact evidence for tests, typecheck, formatting, asset references, and workflow visibility. 2. Create a phase-exit audit proving the eight section 13A criteria, Fun Law checks, generated-asset implementation posture, and no-overclaim boundaries. 3. Reconcile stable web, battlefield, media, privacy, architecture, PRD, and game-design docs with source-backed Phase 24 evidence. 4. Preserve local-first, aggregate-only, replay/mock-inert, no-new-protocol, no-new-storage-key, no-hosted-claim, and no-trusted-erasure boundaries. *** ## 3. Prerequisites ### Required Sessions * [x] `phase24-session06-world-cues-and-bark-reuse` - Provides world cue and bark reuse validation evidence. * [x] `phase24-session07-honesty-and-persistence-boundaries` - Provides replay, reconnect, mock, storage, and privacy boundary evidence. * [x] `phase24-session08-generated-asset-implementation-handoff` - Provides Phase 3 asset map, catalog, fallback, and docs evidence. ### Required Tools Or Knowledge * Node 26.2.0+ and npm 11.16.0 through the workspace toolchain. * Vitest, TypeScript, and Biome through npm scripts. * Git, shell, `rg`, `file`, and Perl for evidence and ASCII/LF checks. * Current Phase 24 PRD, Session 01-08 validation artifacts, and game-design docs. ### Environment Requirements * Repository dependencies are installed locally. * No hosted credentials, provider API keys, Cloudflare access, or third-party dashboard action is required. * Validation remains local browser/workspace evidence and must not be documented as formal WCAG, mobile certification, production-hosted validation, hosted identity proof, or trusted unified erasure. *** ## 4. Scope ### In Scope (MVP) * A web operator can trust the Phase 24 closeout - run focused Phase 24 tests, web typecheck, root format check, asset evidence checks, and spec-system visibility checks with exact output recorded. * A reviewer can audit section 13A criteria - create `phase-exit-audit.md` covering glance, cause, kill-latency, silence, honesty, fatigue, reduced-motion parity, generated-asset implementation evidence, and Fun Law 1 inspect-through proof. * A reviewer can audit Fun Laws and no-overclaim boundaries - record no fake fire, no rewarded waste, replay/mock/reconnect honesty, storage privacy, no new protocol event, no server route, no storage key, no hosted dependency, and no trusted-erasure claim. * Stable documentation reflects source-backed Phase 24 status - update battlefield, web, media, privacy, architecture, game-design ledgers, change log, master PRD, and Phase 24 PRD after validation evidence exists. * Session artifacts preserve implementation evidence - update `implementation-notes.md` with commands, changed docs, residual boundaries, and any in-scope fix decisions. ### Out Of Scope (Deferred) * New game features, tuning passes, UI redesign, reward logic, XP, loot, banners, Battle Report, War Council, Dawn Report, War Tide, public-demo synthetic fronts, or dynamic music - Reason: Phase 24 Session 09 is validation and documentation only. * Hosted identity, hosted storage, analytics capture, production-hosted validation, remote execution, or trusted unified erasure - Reason: these remain no-claim boundaries unless a future scoped phase proves them. * New protocol events, server routes, dependencies, or browser storage keys - Reason: Phase 24 guardrails require existing event paths and `factionos-game-v1`. *** ## 5. Technical Approach ### Architecture Use the completed Phase 24 implementation as the evidence source. The audit should point to the existing `apps/web` modules and tests: projection state in `gameProjection.ts`, combat helpers in `combatPlayback.ts` and `combatPlaybackEffects.ts`, live enemy presentation in `liveLegion.ts` and `LiveLegionLayer.tsx`, scrying and alert focus in `scryingAndAlertFocus.ts` and `ScryingAndAlertFocusLayer.tsx`, world cue derivation in `worldCues.ts` and `useWorldCues.tsx`, generated asset posture in `generatedPhase3Assets.ts` and `mediaCatalog.ts`, and product integration through `Battlefield.tsx`. Documentation updates should follow the Phase 23 closeout pattern: record evidence first, then update stable docs and ledgers with explicit residual boundaries. Do not mark workflow completion in docs as a substitute for `validate` and `updateprd`; if completion wording is needed before those commands, say implementation evidence is recorded and workflow closeout is pending. ### Design Patterns * Evidence-first closeout: Run validation and create the audit before updating docs so documentation is grounded in commands and artifacts. * Projection-owned honesty: Read existing projection, store, replay, mock, and erasure tests instead of inventing a parallel game authority. * Product-surface documentation: Describe shipped user-visible behavior and boundaries, not debug internals or aspirational claims. * Conditional repair: Apply narrow code/test fixes only when a required validation gate fails and the fix is inside Session 09 scope. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------- | | `.spec_system/specs/phase24-session09-validation-and-documentation/phase-exit-audit.md` | Phase 24 acceptance, Fun Law, asset, privacy, and boundary evidence matrix. | \~220 | | `.spec_system/specs/phase24-session09-validation-and-documentation/implementation-notes.md` | Task-by-task command evidence, docs changes, no-claim boundaries, and handoff notes. | \~360 | ### Files To Modify | File | Changes | Est. Lines | | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/web/README_web.md` | Document shipped live tier, combat playback, audio posture, generated asset fallbacks, and no-overclaim boundaries. | \~30 | | `docs/battlefield.md` | Add Phase 24 live enemy, combat playback, scrying, alert focus, reduced-motion, and inspect-through behavior. | \~45 | | `docs/media-assets.md` | Record Phase 3 generated asset implementation references, catalog posture, fallback labels, and runtime no-direct-load boundary. | \~25 | | `docs/privacy-and-security.md` | Update projection/privacy boundary for pending links, camp links, world cues, asset references, replay/mock no-persist, and browser-local erasure no-claim wording. | \~35 | | `docs/ARCHITECTURE.md` | Update game projection and battlefield data flow architecture for live tier and combat playback. | \~35 | | `docs/game-design/14-implemented-phases.md` | Move game-design Phase 3 into the implemented ledger after validation evidence exists. | \~55 | | `docs/game-design/15-phases-yet-to-be-implemented.md` | Remove Phase 3 from pending backlog, refresh grounding, and make later phases depend on implemented Phase 3. | \~70 | | `docs/game-design/11-open-questions-and-change-log.md` | Add Phase 24 closeout entry with validation evidence and residual no-claim boundaries. | \~30 | | `.spec_system/PRD/PRD.md` | Update master PRD progress wording for Phase 24 evidence without replacing workflow closeout. | \~35 | | `.spec_system/PRD/phase_24/PRD_phase_24.md` | Record Session 09 evidence posture and Phase 24 closeout status for the later `updateprd` command. | \~35 | | `.spec_system/specs/phase24-session09-validation-and-documentation/tasks.md` | Track completed tasks during implementation. | \~20 | *** ## 7. Success Criteria ### Functional Requirements * [ ] All eight section 13A criteria have PASS or source-backed evidence in `phase-exit-audit.md`. * [ ] Glance, cause, kill-latency, silence, honesty, fatigue, reduced-motion, generated-asset, and Fun Law 1 inspect-through evidence is tied to commands, tests, source files, or prior session artifacts. * [ ] Docs move game-design Phase 3 / spec-system Phase 24 out of pending status only after validation evidence exists. * [ ] Docs preserve no-overclaim wording for hosted, production, certification, remote, public-demo synthetic, rewards, new protocol, storage, and trusted-erasure boundaries. ### Testing Requirements * [ ] Focused Phase 24 web tests run and pass, or failures are triaged with in-scope fixes and matching tests. * [ ] `npm --workspace @factionos/web run typecheck` passes. * [ ] `npm run format:check` passes. * [ ] Broader `npm test` runs if validation fixes touch shared behavior outside the focused files. ### Non-Functional Requirements * [ ] Phase 24 remains local-first and browser-local, with `localStorage["factionos-game-v1"]` as the only game projection storage key. * [ ] Replay, reconnect, and mock traffic cannot mint persisted kills, links-as-progress, cues, counters, or storage changes. * [ ] Generated assets are referenced through typed app/catalog records and fallbacks, not direct runtime discovery from `assets/generated/game-design/`. * [ ] Documentation is source-backed and avoids certification, hosted-health, hosted-identity, public-demo, or trusted-erasure overclaims. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Primary user-facing surfaces contain product-facing copy only. *** ## 8. Implementation Notes ### Working Assumptions * Phase 24 Session 09 should use `apps/web` as the package context: The analyzer candidate stub lists `apps/web`, all Phase 24 implementation anchors are web files, and no server or protocol work is in scope. Planning can proceed without user arbitration because the monorepo package is explicit. * Section 13A dogfood criteria can be closed with automated proxies plus source-backed audit evidence: The Phase 24 PRD calls out automated proxies for fatigue and latency, and prior sessions already added focused tests for the underlying behaviors. Planning can proceed because no external playtest or hosted environment is required by the stub. ### Conflict Resolutions * Game-design docs `14-implemented-phases.md` and `15-phases-yet-to-be-implemented.md` contain stale Phase 24 progress, while the analyzer and Phase 24 PRD report Sessions 01-08 complete and Session 09 ready. Chosen interpretation: trust analyzer JSON and the phase PRD for workflow state; update stale docs during this session after validation evidence exists. ### Key Considerations * Preserve the Phase 24 rule that the fight is the stream: no visual, audio, kill, or source-inspection claim without real event or typed fallback evidence. * Keep `updateprd` as the workflow step that formally marks the session and phase complete. * Record any validation repair clearly, with before/after evidence and a matching test. ### Potential Challenges * Focused validation command may be long: Use the exact Phase 24 test anchors and record per-file pass/fail output. * Docs could overstate phase completion before workflow closeout: Use evidence-recorded wording until `validate` and `updateprd` run. * Existing docs may contain stale earlier progress snippets: Replace them with analyzer-backed 2026-07-08 facts and cite phase artifacts. ### Relevant Considerations * \[P23-apps/web] **Scanner camps are projection-owned**: Session 09 must verify live tier and combat playback read existing projection/camp selectors without adding parallel state. * \[P22-apps/web] **Do not persist replay or drill progress**: Replay, reconnect, and mock evidence is central to the Phase 24 honesty criterion. * \[P23-apps/web] **Storage inventory regressions**: The closeout must preserve `factionos-game-v1` as the single game projection storage key. * \[P07] **Redaction is boundary-specific**: Docs and evidence must keep raw prompts, outputs, file contents, provider payloads, secrets, and broad absolute paths out of normal product surfaces. * \[P20] **Release evidence is the execution claim source**: Phase 24 claims should be backed by command output, focused tests, artifacts, or source inspection. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Documentation could claim behaviors not backed by validation evidence. * Conditional validation fixes could accidentally add new state, protocol, storage, or reward behavior outside closeout scope. * User-facing docs could expose implementation-sensitive details or imply hosted/certification/trusted-erasure guarantees. *** ## 9. Testing Strategy ### Unit Tests * Focused pure tests for combat playback, projection, generated assets, live legion, scrying/alert focus, world cues, media catalog, and store persistence. ### Integration Tests * Battlefield, live legion, combat playback layer, scrying/alert focus layer, Quest Board, and world cue hook tests that verify visible product behavior, reduced-motion parity, duplicate guards, and no generated path leakage. ### Runtime Verification * Run web typecheck, root format check, asset path evidence checks, spec-system analyzer visibility, and git diff visibility. ### Edge Cases * Failed focused gate requiring narrow repair. * Stale docs that disagree with analyzer state. * Replay/mock/reconnect evidence that must prove no persisted progress. * Reduced-motion criteria requiring static equivalent evidence. * Generated asset paths present in repository but not runtime-loaded directly. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase24-session06-world-cues-and-bark-reuse`, `phase24-session07-honesty-and-persistence-boundaries`, `phase24-session08-generated-asset-implementation-handoff`. * Depended by: Phase 24 `validate`, `updateprd`, and later game-design phases 4-12. *** ## 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/specs/phase24-session09-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.