> 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/phase05-session01-war-room-requirements-and-trust-baseline/spec.md). # Session Specification **Session ID**: `phase05-session01-war-room-requirements-and-trust-baseline` **Phase**: 05 - War Room Worker Integration **Status**: Not Started **Created**: 2026-05-29 **Package**: Cross-cutting **Package Stack**: Cloudflare Worker TypeScript, React/Vite TypeScript, shared TypeScript protocol, Express local-server stub, Markdown docs *** ## 1. Session Overview This session creates the source-backed War Room requirements, participant trust model, lifecycle vocabulary, federation redaction baseline, and session routing matrix for Phase 05 before any broad Worker or web integration work begins. The current repository already has a deployed optional Cloudflare Worker backend, a disabled web War Room stub, shared protocol shapes, a local server `/warroom` status stub, deployment docs, and Worker tests. This session reconciles those sources into one contract that later implementation sessions can follow. The work is intentionally documentation-first and cross-cutting. It defines the room states from create and join through reconnect, catch-up, unavailable, disconnect, and leave; identifies leader authority and participant roles; records spoofing and approval constraints; and makes explicit which payloads may cross the Worker boundary. It also assigns every Phase 05 gap to a later session so Worker hardening, web lifecycle state, approval UX, federation events, deployment diagnostics, and closeout validation have stable ownership. The session must preserve FactionOS' local-first posture. Core cockpit use must keep working without Cloudflare credentials, hosted accounts, hosted storage, analytics, public replay hosting, inbound commands, real executors, media promotion, mobile certification, or unified erasure. War Room federation is optional external transfer and may only move compact, allowlisted, redacted collaboration state. *** ## 2. Objectives 1. Create a source-backed War Room requirements and trust baseline from Worker, web, protocol, server, docs, tests, ADR, deployment, and PRD sources. 2. Define explicit room lifecycle, participant identity, leader authority, approval, rejection, role, reconnect, catch-up, unavailable, disconnect, and leave semantics. 3. Define a Worker federation payload allowlist and non-transferable data baseline that blocks sensitive local developer data by default. 4. Create a requirement-to-session routing matrix that assigns every Phase 05 War Room gap to Sessions 02 through 07 or an explicit later-phase deferral. *** ## 3. Prerequisites ### Required Sessions * [x] `phase04-session08-media-validation-and-documentation-closeout` - provides Phase 04 closeout, current security posture, media/privacy carryforward, and Phase 05 handoff. * [x] `phase03-session07-orchestration-validation-and-documentation-closeout` - provides local orchestration boundaries, redaction lessons, diagnostics posture, and Worker separation constraints. * [x] `phase02-session07-product-surface-validation-and-documentation-closeout` - provides current product shell, accessibility, responsive, and honest stub wording baselines. ### Required Tools/Knowledge * Node 20+, npm workspaces, Biome, Vitest, TypeScript, Wrangler project knowledge, and Cloudflare Worker/Durable Object concepts. * Current code paths: `apps/warroom/src/index.ts`, `apps/warroom/tests/`, `apps/web/src/components/WarRoomPanel.tsx`, `apps/web/src/lib/cockpitShell.ts`, `packages/protocol/src/warroom.ts`, `packages/protocol/src/events.ts`, `apps/server/src/routes/heroes.ts`, and `apps/server/src/lib/unsupportedRoutes.ts`. * Current docs: `.spec_system/PRD/PRD.md`, `.spec_system/PRD/PRD_UX.md`, `.spec_system/PRD/phase_05/PRD_phase_05.md`, `docs/ARCHITECTURE.md`, `docs/api/event-api-hook-contracts.md`, `docs/privacy-and-security.md`, `docs/deployment.md`, `docs/hosted-services.md`, `docs/adr/0002-cloudflare-worker-war-room.md`, `apps/warroom/README_warroom.md`, `apps/web/README_web.md`, `apps/server/README_server.md`, and `packages/protocol/README_protocol.md`. ### Environment Requirements * Local checkout of the FactionOS monorepo with Phase 05 session stubs available. * No Cloudflare credentials, Worker deployment, hosted database, hosted auth, analytics account, media provider key, or external transfer is required. * Stable docs are treated as the current contract; archived PRDs and `EXAMPLES/` remain traceability evidence only. *** ## 4. Scope ### In Scope (MVP) * Maintainers can identify the current Worker, web, protocol, server, deployment, and test evidence for War Room federation - create a source-backed requirements and trust baseline. * Implementers can use one lifecycle vocabulary for create, join, pending, approved, rejected, connected, reconnecting, caught-up, disconnected, unavailable, and left states - define state transitions and visible behavior. * Leaders, members, observers, pending participants, rejected participants, and local users have clear trust and authorization boundaries - define authority, duplicate action, stale approval, spoofing, and role constraints. * Worker federation has explicit payload rules - define allowlisted compact collaboration events and block prompts, file contents, command bodies, terminal output, transcripts, secret values, broad paths, exports, replay buffers, media drafts, and scan payloads. * Later sessions have stable ownership - create a routing matrix for Worker contract hardening, web lifecycle store, approval/presence/reconnect UX, redacted federation, deployment diagnostics, validation, and deferred Phase 06-08 work. * Stable docs distinguish shipped Worker backend, current web stub, local server compatibility stub, optional Cloudflare deployment, and deferred hosted surfaces. ### Out of Scope (Deferred) * Replacing the web War Room stub with working create/join controls - *Reason: Session 03 owns web lifecycle state and UI implementation after Worker contracts are hardened.* * Changing Worker route behavior beyond documentation or narrowly required baseline wording - *Reason: Session 02 owns Worker API hardening, schemas, errors, and tests.* * Federating mission, hero, replay, export, media, scan, prompt, transcript, command, terminal, or file data - *Reason: Session 05 owns redacted event implementation after the baseline is accepted.* * Adding hosted auth, hosted storage, analytics, public replay hosting, inbound commands, real executors, Docker isolation, remote command execution, media promotion, mobile certification, or unified erasure - *Reason: later phases own these surfaces and require separate threat models, consent, tests, and docs.* * Claiming trusted deletion for browser hints, Worker room data, logs, archives, exports, backups, or future hosted records - *Reason: Phase 08 owns unified erasure.* *** ## 5. Technical Approach ### Architecture The session uses a documentation-as-contract approach. Current source files, tests, package README files, stable docs, ADRs, and Phase 05 PRD stubs are treated as evidence. The output baseline documents become the handoff artifacts for later protocol, Worker, web, deployment, and validation sessions. Protocol ownership should lead shared shape changes in later sessions. `packages/protocol` remains the source of truth for room, participant, event, REST, WebSocket, and redaction shapes before `apps/warroom` or `apps/web` consume them. The Cloudflare Worker remains the only room relay. The local Express server keeps `/warroom` as a compatibility/status stub and must not proxy room traffic without a future threat model. The web cockpit owns optional Worker configuration, local participant hints, room lifecycle controls, visible fallback states, participant overlays, and local-only behavior. Worker federation is external transfer and must degrade cleanly when the Worker URL is missing, Cloudflare is unavailable, rate limits are reached, sockets fail, or participant state becomes stale. ### Design Patterns * Protocol-led contracts: shared War Room shapes should be defined once before package-specific implementation. * Local-first optional federation: Cloudflare improves collaboration but must not be required for core cockpit use. * Boundary-specific redaction: Worker payloads, catch-up frames, browser overlays, replay/export adjacency, diagnostics, logs, and docs each need explicit minimization. * Deterministic ownership routing: every requirement should name the implementation session that owns it or a later-phase deferral. * Honest capability wording: docs and UI copy must distinguish shipped Worker backend, current web stub, local server stub, and planned federation. ### Technology Stack * TypeScript contracts in `packages/protocol`. * Cloudflare Worker, Durable Objects, WebSocket, Wrangler, and Worker tests in `apps/warroom`. * React 18, Vite, TypeScript, Tailwind, Zustand, browser `fetch`, browser `WebSocket`, and optional bounded `localStorage` hints in `apps/web`. * Express local-server route metadata in `apps/server`. * Markdown PRD, docs, README, trust baseline, routing matrix, and redaction baseline artifacts. * Validation tools: `rg`, `npm run format:check`, `npm run lint`, workspace typecheck where needed, `git diff --check`, and ASCII/LF scans. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/PRD/phase_05/war_room_requirements_trust_baseline.md` | Source-backed War Room lifecycle, participant trust, authority, spoofing, local-first, and Worker boundary baseline | \~180 | | `.spec_system/PRD/phase_05/war_room_requirement_routing_matrix.md` | Requirement-to-session routing matrix for Sessions 02-07 and later-phase deferrals | \~140 | | `.spec_system/PRD/phase_05/war_room_payload_redaction_baseline.md` | Federation allowlist, non-transferable data categories, catch-up minimization, and replay/export/log adjacency rules | \~140 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/PRD/PRD.md` | Link Phase 05 baseline artifacts and clarify trust, lifecycle, and redaction contract | \~30 | | `.spec_system/PRD/PRD_UX.md` | Add lifecycle state and unavailable/local-only UX requirements for War Room surfaces | \~30 | | `.spec_system/PRD/phase_05/PRD_phase_05.md` | Link Session 01 outputs and align later-session ownership with the routing matrix | \~35 | | `docs/ARCHITECTURE.md` | Clarify Worker relay separation, protocol-led shape ownership, local-server stub, and optional federation data flow | \~30 | | `docs/api/event-api-hook-contracts.md` | Clarify local `/warroom` stub, Worker route vocabulary, typed-only gaps, and planned deterministic errors | \~35 | | `docs/privacy-and-security.md` | Record Worker federation transfer boundaries, non-transferable data, Durable Object data posture, and unified-erasure deferral | \~35 | | `docs/deployment.md` | Clarify optional Worker deployment, health checks, custom-domain status, rate-limit/WAF posture, and non-required Cloudflare credentials | \~25 | | `docs/hosted-services.md` | Keep Cloudflare Worker optional and separate from hosted auth, hosted storage, analytics, and public replay surfaces | \~20 | | `apps/warroom/README_warroom.md` | Clarify lifecycle/trust baseline, caps, sender exclusion, catch-up, and blocked payload categories | \~30 | | `apps/web/README_web.md` | Clarify current stub wording, planned Phase 05 lifecycle states, local-only fallback, and accessibility expectations | \~25 | | `apps/server/README_server.md` | Preserve `/warroom` as local compatibility/status stub and not a Worker proxy | \~15 | | `packages/protocol/README_protocol.md` | Clarify protocol ownership for future War Room contracts and current typed-only gaps | \~20 | *** ## 7. Success Criteria ### Functional Requirements * [ ] War Room requirements and trust baseline exists and cites current Worker, web, protocol, local-server, docs, ADR, deployment, and test evidence. * [ ] Room lifecycle states cover create, join, pending, approved, rejected, connected, reconnecting, caught-up, disconnected, unavailable, and left behavior. * [ ] Participant identity, leader authority, approval, rejection, observer/member roles, stale approval, duplicate action, and spoofing constraints are explicit. * [ ] Payload redaction baseline blocks prompts, file contents, command bodies, terminal output, transcripts, secrets, broad paths, exports, replay buffers, media drafts, and scan payloads from Worker federation. * [ ] Requirement routing matrix assigns each Phase 05 War Room gap to a later session or explicit Phase 06-08 deferral. * [ ] Stable docs and package README files distinguish shipped Worker backend, current web stub, local server stub, optional Cloudflare deployment, and deferred hosted surfaces. ### Testing Requirements * [ ] Documentation path and link references reviewed for changed files. * [ ] Consistency scan completed for War Room state names, blocked payload categories, optional Cloudflare wording, and local-server stub wording. * [ ] No app tests are required unless implementation changes code; if code changes are needed, focused package tests are run. * [ ] ASCII/LF checks completed for all session outputs and touched docs. * [ ] `git diff --check` completed. ### Non-Functional Requirements * [ ] Core FactionOS operation remains local-first and does not require Cloudflare, hosted auth, hosted storage, analytics, public replay hosting, media providers, or external transfer. * [ ] Worker federation is documented as optional external transfer with compact allowlisted payloads only. * [ ] Later hosted collaboration, mobile certification, unified erasure, analytics, and release decommission work remain explicitly deferred. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code and docs follow project conventions. *** ## 8. Implementation Notes ### Key Considerations * Session 01 is a requirements and documentation baseline, not the web/Worker implementation session. * The baseline should route every requirement to the smallest later session that owns it. * Worker federation remains separate from the local server; local `/warroom` must stay a compatibility/status stub. * Redaction must be described as boundary-specific, not a broad guarantee that local exports, replay buffers, archives, diagnostics, or future hosted surfaces are share-safe. * Stable docs are the current contract; archived PRDs and `EXAMPLES/` are evidence only. ### Potential Challenges * Scope bleed into Worker API hardening: record schemas, errors, and gaps, but leave route behavior changes for Session 02 unless a narrow docs correction is needed. * Scope bleed into web UI implementation: define states and UX requirements, but leave controls, store, WebSocket client, and component implementation for Sessions 03 and 04. * Privacy ambiguity: mark uncertain payloads as blocked by default until Session 05 implements allowlisted federation events. * Stale shipped claims: update docs that still describe web federation as merely pending or planned so they point to the new baseline without claiming runtime support early. * Cross-package drift: keep protocol ownership explicit so Worker and web do not duplicate shared contracts in later sessions. ### Relevant Considerations * \[P03-apps/warroom+apps/web] **War Room federation is still separate**: define signed room, participant trust, reconnect, catch-up, and sender-exclusion controls before claiming web federation. * \[P03] **Redaction is boundary-specific**: Worker payloads, room catch-up, browser overlays, replay, export, logs, and diagnostics need explicit minimization. * \[P03-apps/server] **Local server boundary must stay conservative**: keep loopback defaults, auth, Origin, CORS, validation, rate limits, and explicit Worker separation. * \[P00] **Hosted services are optional**: core local workflows must work without Cloudflare, hosted accounts, hosted storage, analytics, or public client tokens. * \[P03-packages/protocol] **Protocol leads cross-package work**: shared room and event contracts should be updated before Worker or web code depends on them. * \[P02-apps/web] **Responsive and accessibility debt**: War Room controls need mobile, focus return, dialog semantics, reduced motion, contrast, and browser validation. * \[P03] **Unified erasure still missing**: do not claim trusted deletion for room identity, browser hints, local state, logs, archives, exports, backups, or future hosted data. * \[P04] **Asset provenance gate remains active**: War Room UI and demos must not promote conditional media, generated drafts, or quarantined historical intake. *** ## 9. Testing Strategy ### Unit Tests * No application unit tests are expected because this session produces planning and documentation artifacts only. * If implementation reveals a narrow code wording or route-metadata fix, run the focused package test for that package before completing the task. ### Integration Tests * Run `npm run format:check` and `npm run lint` if code/config paths are touched. * Run focused package typecheck or tests only if TypeScript, React, Worker, or server code changes are made. * Run `git diff --check` for whitespace validation. ### Manual Testing * Review changed docs and README files for consistent War Room lifecycle names, trust vocabulary, local-first wording, and blocked payload categories. * Verify links to baseline artifacts and existing docs resolve from the repository root. * Confirm docs do not imply web-to-Worker federation, hosted auth, hosted storage, analytics, public replay hosting, inbound commands, real executors, media promotion, mobile certification, or unified erasure are shipped by this session. ### Edge Cases * Worker URL missing, Worker down, Cloudflare unavailable, rate-limited request, socket upgrade failure, room not found, full room, stale approval, duplicate approval, rejected join, reconnect catch-up, and participant leaving. * Prompt, file, command, terminal, transcript, secret, broad path, export, replay, media draft, and scan payloads must remain non-transferable by default. * Browser storage corruption, local-only mode, malformed room code, unsupported local server Worker routes, and future hosted surfaces must not create hidden data transfer claims. *** ## 10. Dependencies ### External Libraries * None added by this session. ### Other Sessions * **Depends on**: Phase 04 closeout, Phase 03 orchestration closeout, Phase 02 product surface closeout. * **Depended by**: `phase05-session02-worker-api-hardening-and-client-contract`, `phase05-session03-web-room-lifecycle-and-state-store`, `phase05-session04-join-approval-presence-and-reconnect-ux`, `phase05-session05-federation-event-redaction-and-cockpit-integration`, `phase05-session06-deployment-environment-and-diagnostics`, `phase05-session07-war-room-validation-and-documentation-closeout`. *** ## 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/phase05-session01-war-room-requirements-and-trust-baseline/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.