> 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/phase02-session01-product-surface-requirements-reconciliation/spec.md). # Session Specification **Session ID**: `phase02-session01-product-surface-requirements-reconciliation` **Phase**: 02 - Product Surface and 2D Battlefield Completion **Status**: Not Started **Created**: 2026-05-29 **Package**: Cross-package documentation (`.spec_system/PRD`, `docs`, `README.md`, app/package README references) **Package Stack**: Markdown, npm workspace documentation, React/TypeScript source review *** ## 1. Session Overview This session reconciles the product and UX requirements with the shipped web cockpit before Phase 02 changes the browser-facing surface. Phase 01 hardened the local runtime contract; Phase 02 now needs requirements that clearly separate shipped behavior, this phase's product-surface work, and later-phase work such as War Room federation, media cataloging, hosted services, mobile collaboration, analytics, and release cleanup. The session is intentionally documentation and requirements focused. It audits stable docs, current web components, battlefield documentation, media records, public demo boundaries, and legacy-consolidation notes, then turns that audit into expanded PRD/UX requirements plus a product-surface gap matrix. Later Phase 02 implementation sessions should be able to plan shell, workflow, battlefield, settings, replay, notification, scan UX, and public demo work without rediscovering the requirements. *** ## 2. Objectives 1. Expand the product PRD into phase-aware requirements for the current browser-facing product surface. 2. Expand the UX PRD into actionable interaction, visual, motion, responsive, and accessibility requirements. 3. Create a Phase 02 web product-surface gap matrix with clear acceptance notes for remaining implementation sessions. 4. Preserve historical-source, asset-provenance, privacy, local-first, and later-phase exclusion boundaries. *** ## 3. Prerequisites ### Required Sessions * [x] `phase01-session01-event-ingest-contract-reconciliation` - event and source-intake baseline. * [x] `phase01-session02-hook-runtime-safety` - hook runtime and listener safety baseline. * [x] `phase01-session03-cli-lifecycle-parity` - CLI lifecycle and local state baseline. * [x] `phase01-session04-server-routes-and-authorization-boundaries` - local server boundary baseline. * [x] `phase01-session05-websocket-hydration-and-archive-export-privacy` - WebSocket, replay, archive, and export privacy baseline. * [x] `phase01-session06-llm-fallback-and-scan-privacy` - LLM fallback, scan, provider-transfer, and memory privacy baseline. * [x] `phase01-session07-runtime-contract-documentation` - stable Phase 01 runtime docs baseline. ### Required Tools/Knowledge * Phase 02 PRD and session stubs. * Stable docs under `docs/`, root `README.md`, and package READMEs. * Current web cockpit source under `apps/web/src/` and focused web tests. * Battlefield, media-assets, public-demo, privacy, and legacy-consolidation documentation. ### Environment Requirements * No local dev server, hosted service, API key, Cloudflare credential, or browser automation is required for this planning/reconciliation session. * Documentation output must be ASCII and LF. *** ## 4. Scope ### In Scope (MVP) * Product owner can read current product requirements from `docs/PRD.md` / `.spec_system/PRD/PRD.md` with shipped, Phase 02, deferred, and excluded boundaries. * Designer or implementer can read UX requirements from `docs/PRD_UX.md` / `.spec_system/PRD/PRD_UX.md` for cockpit, battlefield, overlays, settings, replay, notifications, scan UX, and public demo behavior. * Implementer can use a Phase 02 product-surface gap matrix to locate current source, required behavior, acceptance notes, and later-session ownership. * Maintainer can verify that `EXAMPLES/` and historical build output remain evidence only, not product authority or shippable media. * Later Phase 02 sessions can plan web cockpit, workflow, battlefield, asset/demo parity, and settings/replay/notification work from stable requirements. ### Out of Scope (Deferred) * Redesigning or implementing web components - Reason: Sessions 02 through 06 own implementation. * Creating, replacing, or promoting battlefield/media assets - Reason: Session 05 and later media phases own asset changes. * Wiring War Room Worker federation into the web app - Reason: Phase 05 owns Worker integration. * Building mobile collaboration, hosted services, analytics, or final release cleanup - Reason: later phases own those surfaces. * Deleting `EXAMPLES/`, `docs/PROGRESS.md`, or historical intake records - Reason: Phase 08 owns release decommission gates. *** ## 5. Technical Approach ### Architecture The spec system remains the requirements source of truth. `docs/PRD.md` and `docs/PRD_UX.md` are symlinked public entry points to `.spec_system/PRD/PRD.md` and `.spec_system/PRD/PRD_UX.md`, so edits should target the spec-managed files directly. The gap matrix should live beside the Phase 02 PRD in `.spec_system/PRD/phase_02/` so it can be referenced by later session specs and stable docs. The audit should use current source, tests, package READMEs, API docs, architecture docs, privacy docs, battlefield docs, media-assets docs, and public-demo docs as authority. Historical `EXAMPLES/` material may be cited only as traceability evidence and must not be promoted into product behavior, assets, copied content, or user-facing implementation guidance. ### Design Patterns * Requirements as contract: define user-facing behavior and phase boundaries before implementation. * Gap matrix as routing table: map each surface to current source, current state, Phase 02 requirement, acceptance notes, and owning follow-up session. * Local-first defaults: mark hosted, analytics, cloud, provider-transfer, and Worker behavior as optional or deferred unless current docs prove it is shipped. * Evidence-only historical handling: preserve conclusions and paths without copying raw historical content or sensitive local data. ### Technology Stack * Markdown requirements and documentation. * npm workspace documentation conventions. * React 18, Vite, TypeScript, Tailwind, Zustand source review for web cockpit requirements. * Static public demo HTML/CSS/JavaScript source review for public demo requirements. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/PRD/phase_02/product_surface_gap_matrix.md` | Phase 02 matrix for cockpit, battlefield, overlays, settings, replay, notifications, scan UX, public demo, exclusions, and acceptance notes. | \~180 | | `.spec_system/specs/phase02-session01-product-surface-requirements-reconciliation/implementation-notes.md` | Audit log, source inventory, verification commands, and readiness notes for Session 02. | \~120 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/PRD/PRD.md` | Expand product requirements from bridge text into shipped, Phase 02, deferred, and excluded requirements. | \~220 | | `.spec_system/PRD/PRD_UX.md` | Expand UX requirements for interaction, visual, motion, responsive, accessibility, and browser-facing workflows. | \~180 | | `.spec_system/PRD/phase_02/PRD_phase_02.md` | Link the gap matrix and clarify how Session 01 feeds Sessions 02 through 07. | \~30 | | `docs/README_docs.md` | Update PRD/UX and historical-source routing if expanded requirements change stable-doc expectations. | \~20 | | `README.md` | Update planning references or boundary wording if requirements expansion changes public entry points. | \~15 | | `docs/legacy-consolidation.md` | Preserve product-surface traceability and historical-source limits without granting deletion approval. | \~30 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Product requirements are specific enough to guide all remaining Phase 02 sessions. * [ ] UX requirements cover cockpit shell, hero/mission workflow, battlefield, overlays, settings, replay, notifications, scan UX, public demo, responsive behavior, accessibility, and reduced motion. * [ ] Gap matrix lists current source, current state, Phase 02 requirement, acceptance notes, owner session, and deferred/excluded boundaries for each product surface. * [ ] Phase boundaries are explicit and do not promote War Room federation, media catalog work, hosted services, mobile collaboration, analytics, or release cleanup into Phase 02. * [ ] Historical sources remain evidence only and are not described as product authority. ### Testing Requirements * [ ] Stale-claim grep checks cover shipped/planned/deferred/excluded wording and historical-source references. * [ ] Markdown link/path spot checks pass for PRD, UX PRD, gap matrix, README, docs index, and legacy-consolidation updates. * [ ] ASCII, LF, and `git diff --check` pass for touched docs. * [ ] Session 02 readiness notes identify any unresolved requirement gaps. ### Non-Functional Requirements * [ ] No raw prompts, local secrets, OAuth IDs, provider tokens, raw probe output, or sensitive local paths are copied into requirements. * [ ] Requirements preserve local-first operation without hosted auth, hosted storage, analytics, provider transfer, or Worker federation. * [ ] Asset provenance and `EXAMPLES/` quarantine rules remain release-blocking constraints for shippable media. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Markdown follows project README naming and source-of-truth conventions. *** ## 8. Implementation Notes ### Key Considerations * Current `.spec_system/PRD/PRD.md` and `.spec_system/PRD/PRD_UX.md` are bridge files; this session turns them into useful requirements sources. * `docs/PRD.md` and `docs/PRD_UX.md` are symlinks, so implementation should edit the `.spec_system/PRD/` targets and verify the docs-facing links still resolve. * Current web product surfaces already have substantial component and test coverage; the session should inventory existing behavior rather than assume gaps from historical reports. * The public demo is a no-build standalone surface and must not import workspace packages. * Product-surface requirements must preserve Phase 01 redaction, scan-root, provider-transfer, and local server boundary posture. ### Potential Challenges * Over-scoping implementation work into a requirements session: keep changes to docs, PRD, gap matrix, and verification notes. * Duplicating detailed API contracts in PRD files: link to canonical API docs where route-level detail already exists. * Accidentally treating historical `EXAMPLES/` material as product truth: use it only for traceability and rejected/deferred gap notes. * Writing requirements that imply hosted or federated behavior is available: mark optional, planned, or deferred status explicitly. ### Relevant Considerations * \[P01] **Stable docs are the current contract**: use README files, `docs/api/`, architecture, privacy, release, and legacy-consolidation docs as current truth. * \[P00-apps/web] **Responsive and accessibility debt**: product surface work should verify focus, reduced motion, contrast, and non-overlap on supported web viewports. * \[P01] **Redaction is boundary-specific**: replay, export, notification, settings, and scan UX requirements must preserve Phase 01 redaction posture. * \[P01-packages/protocol] **Protocol leads cross-package work**: shared event, REST, WebSocket, and domain shapes should stay owned by `packages/protocol`. * \[P00] **Asset provenance gate**: no battlefield or showcase media should ship from quarantined historical artifacts. * \[P01] **Local-first boundary is architectural**: optional hosted, analytics, Worker, and provider integrations must degrade cleanly when absent. *** ## 9. Testing Strategy ### Unit Tests * N/A - documentation and requirements reconciliation only. ### Integration Tests * N/A - no runtime behavior should change in this session. ### Manual Testing * Review expanded PRD/UX requirements against current web source, focused web tests, battlefield docs, media-assets docs, public-demo docs, architecture docs, privacy docs, and README entry points. * Verify links and paths for PRD, UX PRD, gap matrix, docs index, root README, and legacy-consolidation references. * Run focused grep checks for stale shipped/planned/deferred/excluded claims and historical-source promotion. ### Edge Cases * Symlinked `docs/PRD.md` and `docs/PRD_UX.md` should resolve to spec-managed targets after edits. * Requirements should not claim web War Room federation is shipped; current Worker backend and web UI stub remain separate surfaces. * Requirements should not imply unified erasure, hosted analytics, public replay sharing, media cataloging, or mobile collaboration is complete. * Scan-root UX requirements should explain allowlist failures without exposing sensitive absolute paths. *** ## 10. Dependencies ### External Libraries * None added. ### Other Sessions * **Depends on**: Phase 01 Sessions 01-07 and Phase 02 PRD/session stubs. * **Depended by**: Phase 02 Sessions 02-07. *** ## Next Steps Run the implement workflow step to begin AI-led 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/phase02-session01-product-surface-requirements-reconciliation/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.