> 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/prd/prd_phases-00-12.md). # FactionOS Product Requirements This is the canonical product requirements source for FactionOS. The stable docs-facing entry point `docs/PRD.md` is a symlink to this file. FactionOS is a local-first observability and orchestration surface for AI coding command-line tools. It turns local agent sessions, prompts, tool calls, plans, approvals, file touches, summaries, outcomes, and optional collaboration signals into a real-time browser cockpit. ## Status Vocabulary Use this vocabulary in PRD, UX PRD, phase plans, and session specs. | Status | Meaning | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Shipped | Implemented in current source and represented by stable docs or tests. | | Phase 02 | Completed browser-facing product-surface work. | | Phase 03 | Completed local orchestration work. | | Phase 04 | Completed media catalog and audio/visual pipeline implementation and closeout. | | Phase 05 | Completed optional War Room Worker integration; phase archived after `validate` and `updateprd`. | | Phase 06 | Completed collaboration, isolation, mobile, accessibility, and validation closeout. | | Phase 07 | Completed hosted services and analytics guardrails; phase validated and closed out. Trusted erasure, production-hosted validation, certification, and decommission were routed to Phase 08 release hardening. | | Phase 08 | Release hardening implementation closeout complete and validated. Local-first gates passed, while hosted identity, production-hosted deployment, formal certification, broad media readiness, and full trusted unified erasure remain no-claim unless the Phase 08 release-candidate record says otherwise. | | Phase 09 | Complete Codex provider-neutral foundation. | | Phase 10 | Complete Codex product integration. | | Phase 11 | Complete Codex hardening and validation. | | Phase 12 | Complete Codex packaging and release readiness. | | Deferred | Planned for a later phase or backlog item, not owned by the current phase. | | Excluded | Deliberately out of scope unless a later PRD changes the decision. | | Evidence only | Historical traceability material, not product authority or release content. | ## Product Surface Boundaries ### Shipped Local Runtime Phase 01 completed the local runtime baseline. The shipped core includes: * A loopback-first Node 20 Express and WebSocket server. * REST endpoints for health, event ingest, heroes, missions, notices, scrolls, achievements, quests, permission responses, plan approval, War Room status, session export, LLM fallbacks, codebase scan, and redacted memory. * WebSocket hydration for connection, roster, notices, scrolls, and achievements, plus schema-validated client messages. * Claude Code hook handlers and CLI lifecycle commands for local setup, status, doctor, start/open/stop, and uninstall. * Shared TypeScript protocol contracts for event, REST, hero, mission, notice, achievement, scroll, faction, plan, and War Room shapes. * Optional outbound adapters for Discord, Telegram, and generic HTTPS webhooks. * Optional Cloudflare Worker and Durable Object backend for War Room rooms. * Deterministic LLM fallback behavior unless provider transfer is explicitly enabled at both configuration levels. ### Shipped Browser Surface The current web cockpit includes: * Asset-driven 2D battlefield with DOM hero buttons, state rings, selection, achievement bursts, fallback rendering, and reduced-motion support. * Live roster, mission log, hero detail, mission detail, mission timeline, permission modal, plan workpad, settings drawer, notice board, toast tray, scroll shelf, quest board, and optional Worker-backed War Room panel. * Command palette, keyboard shortcut help, mission heatmap, faction standings, hero leaderboard, tool usage overlay, mission complexity overlay, trophy room, replay scrubber, share-replay links, local export trigger, browser notifications, audio preference, theme preference, and scan-root UX. * Browser localStorage for faction, settings, replay snapshots, stable client identity, and local auth token hints. ### Shipped Public Demo The public demo is a standalone static artifact under `public-demo/`. It uses synthetic data, local demo media, CDN browser dependencies, and inline code. It does not connect to the local server and must not import workspace packages. ## Phase 02 Product Objective Phase 02 turns the Phase 01 local runtime into a coherent browser-facing product surface. It owns requirements reconciliation, cockpit shell cohesion, hero and mission workflow completion, battlefield interaction polish, asset and public-demo parity, settings/replay/notification/scan UX polish, and product surface validation. Detailed Phase 02 planning lives in: * `.spec_system/archive/phases/phase_02/PRD_phase_02.md` * `.spec_system/archive/phases/phase_02/product_surface_gap_matrix.md` ## Phase 02 Status Map | Product area | Current status | Phase 02 requirement status | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | | Cockpit shell and navigation | Shipped and Phase 02 validated | Shipped in Phase 02 | | Hero roster and detail | Shipped and Phase 02 validated | Shipped in Phase 02 | | Mission log, detail, timeline, and tags | Shipped and Phase 02 validated | Shipped in Phase 02 | | Permission and plan context | Shipped and Phase 02 validated | Shipped in Phase 02 | | 2D battlefield | Shipped and browser-validated | Shipped in Phase 02 | | Battlefield asset parity | Shipped assets and parity-validated | Shipped in Phase 02 | | Public demo parity | Shipped static demo and browser-validated | Shipped in Phase 02 | | Settings, replay, notifications, scan UX | Shipped with local privacy boundaries | Shipped in Phase 02 | | War Room web federation | Optional Worker-backed lifecycle, diagnostics, approval, reconnect, catch-up, and redacted federation implemented in Phase 05 | Phase 05 complete | | Media catalog and audio pipeline | Phase 04 media catalog, gates, synthetic app audio, and public-demo media parity are implemented; conditional media blockers remain | Phase 04 implemented | | Agent orchestration | Runtime observability shipped | Deferred to Phase 03 | | Mobile collaboration | Phase 06 collaboration, isolation, mobile, and accessibility closeout evidence is recorded | Phase 06 complete | | Hosted services and analytics | Phase 07 hosted services and analytics guardrails complete and validated; analytics capture remains disabled by default | Deferred to Phase 07 | | Release cleanup and legacy deletion | Gates documented | Deferred to Phase 08 | | Historical `EXAMPLES/` content | Evidence only | Excluded from runtime promotion | ## Phase 03 Product Objective Phase 03 turns the shipped observability runtime into a local-first orchestration layer. It owns requirements reconciliation for orchestration, task queue and agent template contracts, subagent lineage, guarded local action runtime, web cockpit orchestration controls, CLI diagnostics, and validation. Archived Phase 03 planning lives in: * `.spec_system/archive/phases/phase_03/PRD_phase_03.md` * `.spec_system/archive/phases/phase_03/orchestration_gap_matrix.md` ## Phase 03 Status Map | Product area | Current status | Phase 03 requirement status | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | Task queue and agent templates | Local non-executing queue routes, compact WebSocket frames, and source-owned templates are shipped and tested | Phase 03 Session 02 complete | | Subagent lifecycle and lineage | Typed local lineage graph, bounded hook metadata, and mission graph frames are shipped | Phase 03 Session 03 | | Spawn, resume, stop, fork, and handoff controls | Guarded proposal and decision states are shipped; real executors remain unavailable or deferred | Phase 03 Sessions 04-05 complete for local proposal UX | | File, git, and terminal action proposals | Local guarded action runtime is shipped with bounded proposals, explicit unavailable states, and compact decision handling | Phase 03 Session 04 | | Web orchestration controls | Local cockpit controls for queue, templates, lineage, mission graph, and guarded actions are shipped and browser-smoke validated | Phase 03 Session 05 complete | | CLI orchestration diagnostics | Status, doctor, compact diagnostics, and narrow recovery are shipped and tested | Phase 03 Session 06 complete | | War Room web federation | Optional Worker-backed lifecycle, diagnostics, approval, reconnect, catch-up, and redacted federation implemented in Phase 05 | Phase 05 complete | | Media catalog and audio pipeline | Phase 04 media catalog, gates, synthetic app audio, and public-demo media parity are implemented; conditional media blockers remain | Phase 04 implemented | | Hosted services and analytics | Phase 07 hosted services and analytics guardrails complete and validated; analytics capture remains disabled by default | Deferred to Phase 07 | | Release cleanup and legacy deletion | Gates documented | Deferred to Phase 08 | | Inbound chat or webhook commands | Outbound adapters shipped; inbound commands unsupported | Deferred until a permission and audit model exists | | Docker isolation and remote execution | Historical route families only; not current local runtime behavior | Deferred or excluded from Phase 03 MVP | ## Phase 04 Product Objective Phase 04 turns the current limited, documented media set into a cataloged and validated audio/visual pipeline. It owns requirements reconciliation for media provenance, typed catalog records, first-draft generated asset capture, visual promotion tooling, browser audio behavior, public demo media parity, and media accessibility/privacy/performance gates. Detailed Phase 04 planning lives in: * `.spec_system/archive/phases/phase_04/PRD_phase_04.md` * `.spec_system/archive/phases/phase_04/media_gap_matrix.md` ## Phase 04 Status Map | Product area | Current status | Phase 04 requirement status | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | | Media requirements and provenance baseline | Tracked media docs and quarantine rules exist; Session 01 complete | Phase 04 Session 01 complete | | Typed media catalog records | Contracts, fixtures, validation helpers, and docs are complete | Phase 04 Session 02 complete | | Draft generated asset capture | Redacted briefs, draft manifest records, provider/tool provenance, rights/cost notes, and non-runtime blockers are recorded | Phase 04 Session 03 complete | | Visual promotion tooling and budgets | Battlefield parity and media checks exist; broader catalog promotion tooling and budgets are complete | Phase 04 Session 04 complete | | Browser audio runtime and controls | Opt-in synthetic browser audio runtime, settings, and visible-equivalent controls are shipped and validated | Phase 04 Session 05 complete | | Public demo media parity and offline loading | Demo uses conditional local speech/music, cached approved visual media, lazy music, and validated offline shell behavior | Phase 04 Session 06 complete | | Media accessibility, privacy, and performance gates | Root media release gate and browser evidence checks are shipped and validated | Phase 04 Session 07 complete | | Media validation and documentation closeout | Media, browser, repository quality, docs, security, and handoff evidence are complete | Phase 04 Session 08 complete | | War Room web federation | Optional Worker-backed lifecycle, diagnostics, approval, reconnect, catch-up, and redacted federation implemented in Phase 05 | Phase 05 complete | | Collaboration, isolation, and mobile | Phase 06 collaboration, isolation, mobile, and accessibility closeout evidence is recorded | Phase 06 complete | | Hosted services and analytics | Phase 07 hosted services and analytics guardrails complete and validated; analytics capture remains disabled by default | Deferred to Phase 07 | | Release cleanup and legacy deletion | Gates documented | Deferred to Phase 08 | ## Phase 04 Media Baseline Requirements Session 01 defined the media gap matrix and provenance baseline. Phase 04 sessions used that matrix before adding catalog records, generated draft evidence, promotion scripts, browser audio behavior, public demo cache changes, accessibility gates, and validation closeout evidence. * Current approved battlefield runtime media remains the six optimized WebP files mirrored between `apps/web/public/battlefield/` and `public-demo/assets/battlefield/`, with generated PNG references under `assets/battlefield-2d/reference/`. * Current tracked portraits, brand media, showcase media, public demo speech, and public demo music are not automatically release-complete. Catalog, provenance, attribution, metadata, size, fallback, accessibility, and privacy fields must be completed before expansion or broader promotion. * Draft generated media may use local fal.ai and ElevenLabs credentials from `.env.local`, but secret values, raw command bodies, provider account IDs, sensitive prompt context, and `EXAMPLES/` files must not be committed, logged, or used as direct generation inputs. * Full app audio remains synthetic Web Audio only. File-backed voice lines, SFX, alerts, celebration audio, and music are not shipped in the full app and need later catalog, promotion, accessibility, privacy, and performance review before use. * Public demo media must stay local to the standalone artifact. The demo may mirror product meaning and owned media, but it must not import workspace packages or depend on local server paths. * Historical media under `EXAMPLES/` remains evidence only. It may inform standards, taxonomy, and gap notes by path and conclusion, but runtime code, public demo code, docs, generation prompts, and release artifacts must not copy, transform, import, or ship it directly. * Unknown provenance, unclear rights, missing attribution, unoptimized files, unstripped metadata, unsupported browser formats, oversized payloads, missing fallbacks, missing captions or visible equivalents, and sensitive path or prompt exposure are release blockers. ## Phase 04 Closeout Evidence Session 08 implementation recorded: * Media gates: `npm run media:gates:check`, `npm run media:check`, `npm run media:visual:check`, `npm run media:demo:check`, `npm run media:drafts:check`, and `npm run battlefield:check`. * Browser evidence: app desktop/mobile and public-demo desktop/mobile Playwright projects for media loading, fallback states, reduced motion, visible audio equivalents, service-worker/offline behavior, and browser guards. * Repository gates: formatting, linting, workspace typecheck, full Vitest, workspace build, secret scan, whitespace, ASCII/LF, and quarantine checks. The only release-ready media catalog records are `media.battlefield.background` and `media.battlefield.heroStandees`. Portraits, brand, showcase, public-demo speech, public-demo music, generated references, generated drafts, unknown-provenance rows, and historical intake stay conditional, planned, prototype-only, rejected, unknown, or deferred until later reviewed promotion work closes their blockers. ## Phase 05 Product Objective Phase 05 wires the optional Cloudflare Worker and Durable Object War Room backend into the web cockpit. It owns requirements reconciliation for room federation, participant trust, Worker/client contracts, web room lifecycle, leader approval, presence, reconnect, bounded catch-up, redacted cockpit event federation, deployment diagnostics, and validation. Phase 05 must keep core FactionOS local-first. The local server remains the loopback runtime and `/warroom` compatibility/status stub. The Worker remains the optional room relay. War Room federation must not transfer file contents, full prompts, command bodies, terminal output, transcripts, secret values, broad absolute paths, exports, replay buffers, media drafts, or scan payloads. Detailed Phase 05 planning now lives in the archived phase record: * `.spec_system/archive/phases/phase_05/PRD_phase_05.md` * `.spec_system/archive/phases/phase_05/war_room_requirements_trust_baseline.md` * `.spec_system/archive/phases/phase_05/war_room_payload_redaction_baseline.md` * `.spec_system/archive/phases/phase_05/war_room_requirement_routing_matrix.md` ## Phase 05 Status Map | Product area | Current status | Phase 05 requirement status | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | | War Room requirements and trust baseline | Initial Worker/web/protocol/deployment baseline exists and is fulfilled by Sessions 02-07 | Phase 05 Session 01 complete | | Worker API and client contract | Worker room create, join, approve, socket, sender-excluded broadcast, and bounded catch-up primitives are shipped | Phase 05 Session 02 complete | | Web room lifecycle | Web panel is a local-first Worker lifecycle surface with bounded persistence and local-only fallback | Phase 05 Session 03 complete | | Join approval, presence, reconnect, and catch-up UX | Leader approval, roster presence, reconnect, catch-up, and leave UX are shipped and validated | Phase 05 Session 04 complete | | Redacted federation and cockpit integration | Local cockpit state is federated through the Worker with redacted remote context and overlays | Phase 05 Session 05 complete | | Deployment environment and diagnostics | Worker custom domain, health endpoints, rate-limit notes, and deploy workflow are documented | Phase 05 Session 06 complete | | War Room validation and documentation closeout | Focused Worker/protocol/web tests, desktop/mobile browser evidence, repository gates, security closeout, docs sync, and archive handoff are recorded | Phase 05 Session 07 complete | | Collaboration, isolation, and mobile | Phase 06 collaboration, isolation, mobile, and accessibility closeout evidence is recorded | Phase 06 complete | | Hosted services and analytics | Phase 07 hosted services and analytics guardrails complete and validated; analytics capture remains disabled by default | Deferred to Phase 07 | | Release cleanup and legacy deletion | Gates documented | Deferred to Phase 08 | ## Phase 05 War Room Baseline Requirements * The shipped Worker backend, initial disabled web panel, local `/warroom` status stub, typed protocol scaffolding, deployment docs, and ADR were the source-backed baseline for Phase 05. The current web panel now uses the optional Worker for local-first room lifecycle, diagnostics, approval, presence, reconnect, bounded catch-up, and redacted federation when a Worker URL is configured. * Room lifecycle vocabulary must cover local-only, unavailable, create, join, pending, approved, rejected, connected, reconnecting, caught-up, disconnected, and left states. * Participant identity is an untrusted browser hint until Worker/client contracts add stronger authority. Leader approval must be enforced at the Worker boundary, and stale or duplicate join, approval, rejection, connect, reconnect, disconnect, and leave actions must be deterministic. * The local server must remain a compatibility/status stub for `/warroom` and must not proxy Worker room traffic without a future threat model. * Worker payloads must be explicit allowlists. Unknown socket events and unknown fields must not enter persistence, catch-up, diagnostics, or browser state after Phase 05 hardening. * Cloudflare Worker federation is optional external transfer. Core cockpit use must still work with no Worker URL, no Cloudflare credentials, no hosted auth, no hosted storage, no analytics, no public replay hosting, and no media provider credentials. ## Phase 06 Product Objective Phase 06 turns the optional Worker-backed War Room and shipped local orchestration surfaces into a safer collaboration-ready cockpit. It owns requirements reconciliation for collaboration, participant authority, shared collaboration event contracts, collaborative cockpit UX, isolation boundaries, sandbox diagnostics, mobile layout, accessibility validation, and closeout. Phase 06 must preserve the local-first posture from Phases 01-05. The Worker remains optional external transfer, the local server remains the loopback runtime and `/warroom` compatibility/status stub, and current execution surfaces remain non-executing unless a separately approved threat model adds authorization, audit, redaction, tests, and docs. Detailed Phase 06 planning lives in: * `.spec_system/archive/phases/phase_06/PRD_phase_06.md` * `.spec_system/archive/phases/phase_06/collaboration_isolation_safety_baseline.md` * `.spec_system/archive/phases/phase_06/phase06_requirement_routing_matrix.md` * `.spec_system/archive/phases/phase_06/mobile_accessibility_acceptance_checklist.md` ## Phase 06 Status Map | Product area | Current status | Phase 06 requirement status | | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | | Collaboration requirements and safety baseline | Source-backed baseline artifacts created and validated | Phase 06 Session 01 complete | | Room authority and participant identity contracts | Room-local Worker-issued authority, role, revision, idempotency, stale-decision, duplicate-decision, and proof-limit contracts are shipped and tested | Phase 06 Session 02 complete | | Shared collaboration event contracts | Safe collaboration frame families, blocked-field checks, sender exclusion, bounded catch-up, and browser revalidation are shipped and tested | Phase 06 Session 03 complete | | Collaborative cockpit UX and remote context | Expanded lifecycle, authority, role, reconnect, leave/reset, remote-context, and safe-copy UX is shipped and browser-validated | Phase 06 Session 04 complete | | Isolation boundary and sandbox diagnostics | Compact local diagnostics, deterministic unsupported-route envelopes, and non-executing guarded-action posture are shipped and tested | Phase 06 Session 05 complete | | Mobile cockpit and accessibility hardening | Desktop/mobile browser evidence covers reachability, focus, pointer, screen-reader labels, reduced motion, text fit, and no-overlap behavior; formal certification remains deferred | Phase 06 Session 06 complete | | Collaboration, isolation, and mobile validation closeout | Focused tests, app desktop/mobile Playwright evidence, repository gates, security review, docs sync, and Phase 07/08 handoff are recorded | Phase 06 Session 07 complete | | Hosted services and analytics | Phase 07 hosted services and analytics guardrails complete and validated; analytics capture remains disabled by default | Deferred to Phase 07 | | Release cleanup and legacy deletion | Gates documented | Deferred to Phase 08 | ## Product Requirements Outline The remaining sections define the product requirements that current and future phase sessions must preserve and refine: 1. Local-first and privacy requirements. 2. Cockpit shell and navigation requirements. 3. Hero and mission workflow requirements. 4. Battlefield and asset requirements. 5. Settings, replay, notification, export, and scan UX requirements. 6. Public demo requirements. 7. Agent orchestration requirements. 8. Collaboration, isolation, and mobile requirements. 9. Historical-source and asset-provenance requirements. 10. Deferred and excluded requirements. ## Local-First And Privacy Requirements * Core FactionOS must work without a hosted account, hosted storage, analytics, Cloudflare, Anthropic, Discord, Telegram, or generic webhooks. * Optional services must be disabled unless configured and must degrade cleanly when unavailable. * Browser-facing flows must treat prompts, local paths, command previews, terminal output, local archive entries, replay buffers, exports, adapter payloads, LLM inputs, and scan roots as sensitive developer data. * User-facing errors must avoid exposing raw prompts, command bodies, tokens, absolute paths, stack traces, provider errors, or raw request bodies. ## Cockpit Shell And Navigation Requirements Phase 02 must make the browser cockpit feel like one coherent product surface instead of a collection of independent panels. * The shell must keep the battlefield, mission log, notice board, roster, scroll shelf, quest board, and War Room panel reachable on supported desktop and mobile browser widths. * The top command area must clearly expose connection state, global overlays, settings, keyboard help, command palette, and any current local-server boundary state. * Navigation between overlays must preserve current context unless the user explicitly resets state. * Empty, disconnected, loading, and fallback states must be visible and actionable. The UI must not leave blank panels when the local server is down or a feature is stubbed. * The War Room panel must clearly mark Worker federation as optional external transfer and must preserve local-only, unavailable, and redacted states without implying hosted identity, hosted storage, analytics, public replay hosting, remote execution, or trusted erasure. ## Hero And Mission Workflow Requirements Phase 02 must keep the live agent workflow understandable from both roster and mission perspectives. * Hero roster cards must expose hero state, faction, active mission, recent activity, specialization, efficiency, and selection affordances without relying on color alone. * Hero detail must summarize current state, active mission, metrics, recent mission history, achievements, specialization, efficiency, tool usage, and complexity in a way that supports quick triage. * Mission log must support search, state filters, inferred tags, click-through to detail, and clear active/completed/error state treatment. * Mission detail must show prompt summary, lifecycle timestamps, tool usage, duration, token/cost metrics where available, and redacted text surfaces. * Permission and plan workflows must show who requested action, why, what will happen, and whether a decision is pending, accepted, rejected, expired, or unavailable. * Duplicate permission and plan responses must not create duplicate state changes. The UI must align with the Phase 01 WebSocket duplicate-response guard. ## Battlefield And Asset Requirements Phase 02 must preserve the approved asset-driven 2D battlefield and polish the state and interaction contract. * The battlefield must use app-owned runtime assets from `apps/web/public/battlefield/` and mirror approved copies to `public-demo/assets/battlefield/` when parity changes are made. * The battlefield must keep hero tokens as native interactive controls with accessible names, selected state, and keyboard/pointer reachability. * Hero position mapping must remain clamped and resilient to missing or non-finite coordinates. * Selected hero state must stay synchronized with roster and hero detail context. * Failed background or hero image loads must have visible fallback treatment. * Awaiting input, active, verifying, error, spawning, dismissed, selected, and idle states must remain visibly distinct through labels, rings, glow, or static state marks. * Achievement celebrations must be bounded and must clean up timers. Reduced motion must preserve state meaning without requiring animation. * `docs/media-assets.md` remains the asset-provenance source. New or changed media must be owned or generated, optimized, measured, documented, and smoke tested before release. ## Settings, Replay, Notifications, Export, And Scan Requirements Phase 02 must make local browser controls and failure paths clear. * Settings must expose active faction, theme, audio, reduced motion, severity filters, browser notifications, scan root, replay panel access, reset flows, and any local auth token affordance that is implemented. * Settings stored in localStorage must recover cleanly from malformed or unavailable storage. * Browser notifications must remain opt-in and must reflect browser permission states: unsupported, default, denied, and granted. * Notification test actions must provide visible feedback when delivery is blocked, unsupported, throttled, or denied. * Replay buffers and share-replay links must redact sensitive fields, cap payload size, avoid replay feedback loops, and preserve a local-only posture. * Export actions must use the local server export route and inherit Phase 01 export redaction and privacy headers. * Codebase scan UX must explain allowlist and invalid-root failures without showing sensitive absolute paths in broad user-facing output. ## Public Demo Requirements The public demo is a product showcase, not a second app build. * `public-demo/` must stay no-build and static-host compatible. * The demo may mirror product vocabulary, data-shape discipline, selected helpers, and copied owned assets, but it must not import workspace packages. * The demo must use synthetic data only. It must not connect to the local server, local hooks, LLM endpoints, real sessions, or War Room federation. * Public demo battlefield behavior and assets must remain visibly aligned with the full app when Phase 02 changes the battlefield. * Public demo service worker cache versions and precache lists must be updated when shell or precached asset paths change. * Public demo media is local to the artifact and must have provenance recorded in stable docs before release. ## Agent Orchestration Requirements Phase 03 must turn planned orchestration into local-first, permission-aware workflows without broadening the product into hosted collaboration. * Task queues and agent templates must use shared protocol contracts before server, web, hook, or CLI packages consume them. * The Phase 03 orchestration gap matrix is the source-backed routing record for current shipped, tested-shipped, typed-only, planned, unsupported, stubbed, separate-surface, deferred, excluded, and evidence-only behavior. * Subagent lifecycle events must preserve parent-child mission lineage where current hook data supports it, and must degrade safely when IDs are missing or malformed. * Spawn, resume, stop, fork, handoff, file, git, and terminal actions must be explicit proposals or approved local actions with pending, accepted, rejected, expired, failed, and unavailable states. * Orchestration routes and WebSocket frames must inherit local server auth, Origin, CORS, rate-limit, body-size, and compact validation behavior. * Browser and CLI surfaces must avoid exposing raw prompts, command bodies, terminal output, transcripts, tokens, or broad absolute paths. * CLI orchestration diagnostics must report health, stale state, malformed state, listener/hook posture, queue/action posture, and recovery outcomes without printing raw local payloads or broad state file contents. * Phase 03 must not present War Room federation, inbound chat commands, hosted queues, hosted persistence, public sharing, analytics, or remote execution as shipped behavior. * Phase 03 must keep adapters outbound-only, keep Worker federation separate, and keep Docker/container isolation deferred unless a later PRD adds a separate threat model and validation plan. ## Collaboration, Isolation, And Mobile Requirements Phase 06 must expand collaboration, isolation, and mobile readiness without turning FactionOS into a hosted service dependency. Session 01 records the current baseline in `.spec_system/archive/phases/phase_06/collaboration_isolation_safety_baseline.md`, routes requirements through `.spec_system/archive/phases/phase_06/phase06_requirement_routing_matrix.md`, and defines mobile/accessibility acceptance in `.spec_system/archive/phases/phase_06/mobile_accessibility_acceptance_checklist.md`. Later sessions must update those artifacts only with source-backed evidence. * Collaboration must remain optional and must degrade cleanly with no Worker URL, no Cloudflare credentials, no hosted account, no hosted storage, no analytics, no public replay hosting, and no provider credentials. * Room, leader, participant, approval, reconnect, disconnect, leave, and duplicate-action authority must be deterministic before broader collaboration claims. * Participant display names, colors, and roles are not account proof unless a later hosted-services phase adds explicit identity lifecycle, authorization, audit, and validation. * Shared collaboration events must be compact, typed, allowlisted, redacted, sender-aware, and bounded for catch-up. They must not transfer prompts, file contents, command bodies, terminal output, transcripts, secrets, broad paths, exports, replay buffers, scan payloads, media drafts, diagnostics, logs, backups, or quarantined historical content. * Remote collaboration context must stay visually separate from local hero, mission, queue, guarded-action, replay, export, notification, settings, and adapter source-of-truth state. * Isolation work must define threat models, capability posture, unavailable states, diagnostics, consent, audit, and redaction before real file, git, terminal, Docker, remote, or hosted executors are shipped. * Mobile cockpit work must keep battlefield, mission list, roster, settings, local orchestration, War Room, and critical controls reachable on supported mobile browser widths without overlapping text or controls. * Accessibility work must preserve accessible names, visible focus states, dialog semantics, keyboard and pointer paths, screen-reader labels, reduced motion, and visible error states for changed surfaces. * Room leave/reset, diagnostics cleanup, browser storage reset, and narrow recovery flows are not trusted unified erasure. Phase 08 records scoped erasure evidence; full trusted unified erasure remains no-claim. Phase 06 closeout evidence is recorded in `.spec_system/archive/sessions/phase06-session07-collaboration-isolation-and-mobile-validation-closeout/`. The retained app desktop/mobile browser evidence is local Playwright evidence with local server and mocked or same-origin Worker paths. It does not replace hosted identity review, production-hosted validation, mobile or WCAG certification, analytics consent review, public replay safety, real executor threat modeling, or trusted unified erasure. Phase 07 owns hosted services and analytics guardrails; Phase 08 records release-hardening evidence while keeping unproven production-hosted, certification, and full trusted-erasure claims no-claim. ## Phase 07 Product Objective Phase 07 turns deferred hosted services and analytics into explicit guardrails before FactionOS can make any account-backed, hosted-storage, analytics, public replay, push, remote-access, or hosted diagnostic claim. It owns requirements reconciliation, hosted configuration and client exposure boundaries, hosted identity and authorization guardrails, hosted persistence and public replay boundaries, analytics consent and payload controls, push and remote-access guardrails, operator diagnostics, validation, and documentation closeout. Phase 07 must preserve local-first operation. Core server, web, hooks, CLI, adapters, public demo, and War Room fallback workflows must keep working without Supabase, Umami, hosted auth, hosted storage, analytics, push, Cloudflare credentials, public replay hosting, remote tunnels, or provider credentials. Trusted unified erasure, production-hosted validation, release hardening, mobile certification, WCAG certification, and legacy decommission are routed to Phase 08 release-hardening evidence and remain no-claim where not proven. Detailed Phase 07 planning lives in: * `.spec_system/archive/phases/phase_07/PRD_phase_07.md` * `.spec_system/archive/phases/phase_07/hosted_services_requirements_privacy_baseline.md` * `.spec_system/archive/phases/phase_07/phase07_requirement_routing_matrix.md` * `.spec_system/archive/phases/phase_07/hosted_payload_privacy_blocklist.md` * `.spec_system/archive/phases/phase_07/analytics_consent_payload_controls.md` ## Phase 07 Status Map | Product area | Current status | Phase 07 requirement status | | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------- | | Hosted services requirements and privacy baseline | Baseline artifacts created and validated | Phase 07 Session 01 complete | | Hosted configuration and client exposure boundaries | Source-backed contracts, diagnostics, browser helpers, and docs are complete | Phase 07 Session 02 complete | | Hosted identity and authorization guardrails | Complete and validated | Phase 07 Session 03 complete | | Hosted persistence and public replay boundaries | Complete and validated | Phase 07 Session 04 complete | | Analytics consent and payload controls | Complete and validated | Phase 07 Session 05 complete | | Push, remote access, and operator diagnostics guardrails | Complete and validated | Phase 07 Session 06 complete | | Hosted guardrails validation and documentation closeout | Complete and validated | Phase 07 Session 07 complete | | Release hardening, trusted erasure, certification, and legacy decommission | Deferred | Phase 08 | Session 01 through Session 07 implementations create the Phase 07 hosted-services requirements and privacy baseline, requirement routing matrix, hosted payload privacy blocklist, hosted config vocabulary, hosted identity guardrail contracts, redacted diagnostics posture, browser-safe public config helpers, hosted persistence and public replay guardrails, analytics consent and payload controls, push/remote-access/operator-diagnostics guardrails, passive settings copy, docs/env alignment, and the validation and documentation closeout. These artifacts define variable categories, local-first fallback, blocked hosted payload categories, and Phase 08 deferrals. Session 07 validated the guardrails end to end (20 focused test files / 183 tests, full suite 2186 passed / 1 skipped, format/lint/typecheck/build/secret-scan all green) and confirmed requirement closure for P07-R001 through R025. Phase 07 does not ship hosted auth, hosted storage, analytics capture, public replay hosting, push delivery, remote access, production-hosted validation, trusted erasure, certification, release hardening, or legacy decommission; those claims require Phase 08 release-hardening evidence and remain no-claim where not proven. ## Phase 08 Product Objective Phase 08 turns the completed local-first runtime, collaboration, media, hosted-service guardrail, and documentation work into release-grade evidence. It records or gates trusted unified erasure, hosted identity claim boundaries, production-hosted validation, release-candidate hardening, mobile and accessibility certification evidence, legacy evidence decommission, media gate revalidation, and final documentation closeout. Phase 08 must preserve local-first operation. Core server, web, hooks, CLI, adapters, public demo, and War Room fallback workflows must keep working without Supabase, Umami, hosted auth, hosted storage, analytics, push, Cloudflare credentials, public replay hosting, remote tunnels, provider credentials, or real executors. Hosted identity, hosted storage, analytics, public replay, push, remote access, trusted erasure, certification, and production deployment claims require source, tests, docs, and validation evidence before release copy may describe them as active or complete. Detailed Phase 08 planning lives in: * `.spec_system/archive/phases/phase_08/PRD_phase_08.md` * `.spec_system/archive/phases/phase_08/release_requirements_risk_baseline.md` * `.spec_system/archive/phases/phase_08/phase08_requirement_routing_matrix.md` * `.spec_system/archive/phases/phase_08/phase08_release_risk_matrix.md` * `.spec_system/archive/phases/phase_08/decommission_approval_matrix.md` Session 01 creates the Phase 08 baseline artifacts only. Those artifacts define claim gates, requirement ownership, risk ownership, and candidate-only decommission inputs. They do not close trusted erasure, hosted identity, production-hosted validation, certification, media promotion, release hardening, or legacy deletion claims; Sessions 02 through 08 own those evidence gates. ## Phase 08 Status Map | Product area | Current status | Phase 08 requirement status | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | Release requirements and risk baseline | Complete baseline; final closeout references release-candidate record | Phase 08 Session 01 complete | | Unified erasure contract and inventory | Complete inventory and unsupported-claim contract evidence; not a full trusted-erasure claim | Phase 08 Session 02 complete | | Local erasure runtime and controls | Complete local/browser erasure controls and tests; scoped to local/browser boundaries | Phase 08 Session 03 complete | | War Room and hosted identity release gate | Complete Worker room-state and hosted identity no-claim evidence; room authority is not hosted account identity | Phase 08 Session 04 complete | | Production-hosted validation and deploy smoke | No-network smoke evidence complete; live deployed public demo, Worker, and app-shell claims remain blocked/no-claim in S0808 | Phase 08 Session 05 plus S0808 closeout | | Mobile and accessibility certification evidence | Complete and validated | Phase 08 Session 06 | | Legacy evidence decommission and media release gate | Complete and validated | Phase 08 Session 07 complete | | Release candidate validation and documentation closeout | Complete and validated; local install, quality, test, build, media, focused Phase 08, and local browser Playwright gates recorded; docs sync and release handoff complete | Phase 08 Session 08 complete | ## Phase 08 Release-Candidate Evidence Session 08 records the final Phase 08 release-candidate evidence in `.spec_system/archive/phases/phase_08/release_candidate_validation_record.md`. Current local-first evidence includes install, format, lint, workspace typecheck, full Vitest, workspace build, media gates, focused Phase 08 Vitest checks, app desktop/mobile Playwright, and public-demo desktop/mobile Playwright. This evidence does not authorize overclaims. Live hosted smoke currently blocks production-hosted public demo and Worker claims, the optional production app shell is unavailable, hosted identity remains no-claim, formal WCAG/mobile certification remains no-claim, broad media readiness remains limited to approved battlefield runtime records, and full trusted unified erasure remains bounded by the explicit local/browser/Worker evidence in the Phase 08 records. ## Phase 09 Product Objective Phase 09 turns the Claude-centered hook and ingest foundation into a provider-neutral base that can accept OpenAI Codex CLI events without changing current Claude Code behavior. It owns shared protocol naming, Codex-safe event types, hook runtime normalization, and the first Codex hook map and handlers. Phase 09 must preserve local-first and privacy-safe boundaries. Hook handlers may post bounded event summaries only. Raw prompts, patch bodies, command output, transcript contents, MCP arguments, absolute paths, token-like values, and provider credentials must not be emitted. Detailed Phase 09 planning lives in: * `.spec_system/archive/phases/phase_09/PRD_phase_09.md` ## Phase 09 Status Map | Product area | Current status | Phase 09 requirement status | | ------------------------------------------ | ---------------------- | ---------------------------- | | Contracts and naming baseline | Complete and validated | Phase 09 Session 01 complete | | Hook runtime normalization | Complete and validated | Phase 09 Session 02 complete | | Codex hook map and Codex-specific handlers | Complete and validated | Phase 09 Session 03 complete | Session 01 through Session 03 complete the Phase 09 provider-neutral foundation and add the first Codex hook map plus Codex-specific handler coverage. The resulting artifacts keep Claude compatibility stable while documenting the remaining installer, product-surface, and hardening work for Phases 10 through 12. ## Phase 10 Product Objective Phase 10 wires the provider-neutral Codex foundation into the product surface. It owns CLI provider selection, safe Codex hook installation and uninstall, Codex diagnostics, server lifecycle ingest, and web labels and filtering. Phase 10 must keep installer behavior reversible and respectful of user-owned Codex configuration. FactionOS may merge managed hooks, create backups, and remove its own managed hooks, but it must not mutate Codex auth, provider, telemetry, model, profile, or OpenAI API settings. Detailed Phase 10 planning lives in: * `.spec_system/archive/phases/phase_10/PRD_phase_10.md` ## Phase 10 Status Map | Product area | Current status | Phase 10 requirement status | | ---------------------------------------------- | ------------------------------------------ | ------------------------------------------ | | CLI provider selection and installer split | Phase 10 Session 01 complete | Phase 10 Session 01 complete | | Codex hook install, uninstall, and diagnostics | Phase 10 Session 02 complete | Phase 10 Session 02 complete | | Server ingest Codex lifecycle | Phase 10 Session 03 complete | Phase 10 Session 03 complete | | Web Codex awareness | Phase 10 Session 04 complete and validated | Phase 10 Session 04 complete and validated | ## Phase 11 Product Objective Phase 11 hardens the Codex integration through documentation, source-backed fixtures, focused automated coverage, and an end-to-end Codex validation pass. It turns the product integration from technically wired to release-trustworthy. Phase 11 should fix only integration blockers discovered during validation. Broader product improvements, unrelated refactors, hosted behavior, and external telemetry remain out of scope. Detailed Phase 11 planning lives in: * `.spec_system/archive/phases/phase_11/PRD_phase_11.md` ## Phase 11 Status Map | Product area | Current status | Phase 11 requirement status | | ------------------------------------------- | ------------------------------------------ | ------------------------------------------ | | Documentation and privacy sync | Phase 11 Session 01 complete | Phase 11 Session 01 complete | | Test fixture hardening | Phase 11 Session 02 complete | Phase 11 Session 02 complete | | End-to-end validation and integration fixes | Phase 11 Session 03 complete and validated | Phase 11 Session 03 complete and validated | ## Phase 12 Product Objective Phase 12 completes Codex integration by resolving plugin packaging and release readiness. It determines whether FactionOS should ship as a Codex plugin in addition to direct user-level hooks, then prepares final release evidence, changelog or release notes, and known limitations. Plugin packaging must not become a blocker for direct Codex hook support. If direct user-level hooks are the supported path, this phase documents that decision and closes the release without unnecessary packaging work. Detailed Phase 12 planning lives in: * `.spec_system/archive/phases/phase_12/PRD_phase_12.md` ## Phase 12 Status Map | Product area | Current status | Phase 12 requirement status | | -------------------------------------- | ------------------------------------------------ | ------------------------------------------ | | Codex plugin packaging | Phase 12 Session 01 complete; packaging deferred | Phase 12 Session 01 complete | | Release closeout and rollout readiness | Phase 12 Session 02 complete and validated | Phase 12 Session 02 complete and validated | ## Historical-Source And Asset-Provenance Requirements * `EXAMPLES/`, copied historical bundles, extraction reports, old findings, and `docs/PROGRESS.md` are evidence only. * Requirements may cite historical paths for traceability, standards, or rejected/deferred gap notes. * Requirements must not copy raw historical prompts, probe output, token values, OAuth IDs, sensitive local paths, old bundled code, or quarantined media into stable docs. * Runtime code and public demo code must not import, copy, transform, or ship `EXAMPLES/` files. * Release cleanup and deletion approvals remain governed by Phase 08 evidence and the release-candidate record. ## Deferred And Excluded Requirements * Earlier Phase 03 work did not ship web War Room federation. Current source implements the Phase 05 optional Worker integration, while hosted identity, shared queues, inbound commands, analytics, remote execution, public replay hosting, and trusted erasure remain deferred. * Phase 03 must not introduce hosted auth, hosted storage, analytics, public replay sharing, hosted replay storage, or production database requirements. * Phase 03 must not promote `EXAMPLES/` files into runtime code, media, product copy, generated assets, or release content. * Phase 03 must not delete `EXAMPLES/`, `docs/PROGRESS.md`, or other historical inputs. Final decommission gates remain governed by Phase 08 evidence and the release-candidate record. ## Phases | Phase | Name | Sessions | Status | | ----- | --------------------------------------------- | -------- | -------- | | 00 | Source of Truth and Cleanup Plan | 0 | Complete | | 01 | Core Runtime Hardening | 7 | Complete | | 02 | Product Surface and 2D Battlefield Completion | 7 | Complete | | 03 | Agent Orchestration | 7 | Complete | | 04 | Media Catalog and Audio/Visual Pipeline | 8 | Complete | | 05 | War Room Worker Integration | 7 | Complete | | 06 | Collaboration, Isolation, and Mobile | 7 | Complete | | 07 | Hosted Services and Analytics Guardrails | 7 | Complete | | 08 | Release Hardening and Legacy Decommission | 8 | Complete | | 09 | Codex Provider-Neutral Foundation | 3 | Complete | | 10 | Codex Product Integration | 4 | Complete | | 11 | Codex Hardening and Validation | 3 | Complete | | 12 | Codex Packaging and Release Readiness | 2 | Complete | --- # 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/prd/prd_phases-00-12.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.