> 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/phases/phase_03/orchestration_gap_matrix.md). # Phase 03 Orchestration Gap Matrix This matrix routes Phase 03 local orchestration work from current source state to acceptance criteria and owning follow-up sessions. It is requirements source material, not an implementation changelog. Session 01 owns this matrix and the safety baseline. Sessions 02 through 07 own runtime implementation, UI implementation, diagnostics, validation, and documentation closeout. ## Matrix Schema | Column | Required content | | -------------------- | ------------------------------------------------------------------------------ | | Surface | Orchestration area, route family, event family, package boundary, or deferral. | | Current source | Current source, tests, stable docs, or session stub paths used as evidence. | | Current state | One status value from the vocabulary below. | | Phase 03 requirement | Required local-first behavior or documented boundary for this phase. | | Acceptance notes | Observable checks a later session can validate. | | Owner session | Phase 03 session responsible for implementation, validation, or deferral. | | Safety boundary | Privacy, permission, local-first, deferral, or exclusion note. | ## Status Values | Status | Use | | ---------------- | ----------------------------------------------------------------------------------- | | Shipped | Current source implements the behavior and stable docs can claim it. | | Tested-shipped | Current source implements the behavior and focused tests cover the contract. | | Typed-only | Shared protocol types exist but no current runtime producer or handler is wired. | | Planned | Phase 03 or a later PRD accepts the behavior, but current runtime does not ship it. | | Unsupported | Current runtime intentionally does not support the behavior. | | Stubbed | Current source exposes a placeholder or compatibility status only. | | Separate-surface | Behavior belongs to another runtime surface, such as the Cloudflare Worker. | | Deferred | Planned after Phase 03 or outside the current local orchestration MVP. | | Excluded | Not in scope unless a future PRD changes the decision. | | Evidence-only | Historical or quarantined source that can support traceability only. | ## Owner Session Routing Model | Session | Owner scope | | ---------- | ------------------------------------------------------------------------------------- | | Session 01 | Requirements baseline, gap matrix, PRD/docs alignment, security and privacy baseline. | | Session 02 | Task queue and agent template protocol/server contracts. | | Session 03 | Subagent lineage and mission graph runtime. | | Session 04 | Guarded local action contracts and runtime. | | Session 05 | Web cockpit orchestration controls. | | Session 06 | CLI diagnostics, hook/listener diagnostics, and bounded local recovery controls. | | Session 07 | Quality gates, docs closeout, security closeout, and remaining-gap handoff. | ## Source Policy * Prefer current source, tests, and stable docs over historical extraction files. * Treat `packages/protocol` as the lead owner for shared queue, template, lineage, guarded-action, event, and WebSocket shapes. * Keep current docs honest about shipped behavior. Do not describe typed-only, planned, unsupported, stubbed, separate-surface, deferred, excluded, or evidence-only behavior as shipped. * Cite historical paths only for traceability. Do not copy raw prompts, command bodies, terminal output, token-like values, OAuth IDs, probe output, sensitive local paths, bundled code, or media from `EXAMPLES/`. * Preserve the local-first default. New Phase 03 data paths must inherit local auth, Origin, CORS, rate-limit, body-size, validation, redaction, and explicit failure behavior where applicable. ## Phase 03 Matrix ### Session 02 - Task Queue And Agent Template Contracts | Surface | Current source | Current state | Phase 03 requirement | Acceptance notes | Owner session | Safety boundary | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Task queue route family | `apps/server/src/lib/unsupportedRoutes.ts`, `docs/api/event-api-hook-contracts.md`, `.spec_system/PRD/phase_03/session_02_task_queue_and_agent_template_contracts.md` | Planned | Convert the approved local task queue subset from 501 planned-route classification into validated local contracts. | Queue create, list, update, reject, and unavailable paths use compact validation, auth, rate-limit, and deterministic failure responses; unapproved paths remain 501 with route family metadata. | Session 02 | Queue state is local only and must not execute terminal commands, create hosted queues, or imply remote workers. | | Task queue WebSocket events | `packages/protocol/src/events.ts`, `docs/api/event-api-hook-contracts.md` | Typed-only | Define the minimal queue update frames needed by server and web without claiming historical event parity. | Runtime producers and tests exist before docs mark queue frames shipped; payloads expose counts and bounded metadata only. | Session 02 | Do not include raw prompts, command bodies, terminal output, transcripts, tokens, or absolute paths in broad queue frames. | | Agent template contracts | `apps/server/src/lib/unsupportedRoutes.ts`, `EXAMPLES/1st-pass-artifacts/*`, `.spec_system/PRD/phase_03/session_02_task_queue_and_agent_template_contracts.md` | Planned and evidence-only | Promote approved agent template shapes through protocol before server, hook, CLI, or web consumption. | Template schema validates names, roles, constraints, defaults, and rejection errors; docs distinguish current contracts from historical template evidence. | Session 02 | Historical templates are traceability evidence only; do not copy old prompt bodies, bundled code, local paths, or media into stable docs or runtime code. | | Queue-to-plan relationship | `packages/protocol/src/plans.ts`, `packages/protocol/src/events.ts`, `apps/web/README_web.md` | Shipped plans, typed-only task queue | Align queue entries with existing plan and mission concepts without duplicating plan state. | Queue entries reference mission, hero, plan, or template IDs through explicit optional fields; missing references degrade to unavailable or rejected states. | Session 02 | Queue metadata must remain bounded and redacted at export, archive, replay, adapter, and future WebSocket boundaries. | | Unsupported queue-adjacent historical routes | `apps/server/src/lib/unsupportedRoutes.ts`, `docs/api/README_api.md` | Planned or unsupported | Keep broad historical queue, sessions, suggestions, usage, skills, and issue routes explicit until a later session implements a scoped subset. | Unsupported routes continue returning `not_implemented` with family, status, docs, and redacted path only. | Session 02 | No hosted task marketplace, inbound issue ingestion, analytics usage tracking, or remote execution is introduced in Phase 03 MVP. | ### Session 03 - Subagent Lineage And Mission Graph Runtime | Surface | Current source | Current state | Phase 03 requirement | Acceptance notes | Owner session | Safety boundary | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Subagent spawn and completion hooks | `apps/hooks/hooks.json`, `apps/hooks/src/factionos-subagent-spawn.js`, `apps/hooks/src/factionos-subagent-complete.js`, `packages/protocol/src/ingest.ts` | Shipped as opaque | Promote approved subagent lifecycle metadata into typed protocol and server behavior where current hook data supports it. | Spawn and completion payloads produce typed lineage updates when IDs are available; opaque fallback remains for missing or unsupported fields. | Session 03 | Do not spawn, stop, or remote-control subagents from FactionOS controls in this session. | | Mission graph state | `packages/protocol/src/missions.ts`, `apps/server/src/managers/missionManager.ts`, `.spec_system/PRD/phase_03/session_03_subagent_lineage_and_mission_graph_runtime.md` | Planned | Add parent-child mission relationships and lineage snapshots without replacing current hero/mission lifecycle. | Mission graph state can represent parent mission, child mission, subagent id, start, completion, and degraded unknown states. | Session 03 | Missing, malformed, oversized, or historical lineage values must degrade without crashes or raw transcript/path leakage. | | Opaque mission\_event compatibility | `apps/server/src/routes/event.ts`, `docs/api/event-api-hook-contracts.md` | Shipped as opaque | Preserve current bounded `mission_event` compatibility while introducing typed lineage only for approved cases. | Unknown named events and unsupported subagent variants still produce bounded opaque frames or no state changes according to current contract. | Session 03 | Do not copy raw historical payload cookbooks into docs or expose opaque raw payloads in replay, export, adapter, or archive surfaces. | | Subagent transcript-derived identifiers | `apps/hooks/src/_lib.js`, `apps/hooks/src/factionos-hero-active.js`, `apps/hooks/src/factionos-bash-command.js`, `apps/hooks/src/factionos-file-access.js`, `apps/hooks/src/factionos-permission-request.js` | Partial | Define how transcript-derived subagent identifiers can link hooks to lineage without exposing transcript paths. | Tests cover absent transcript paths, malformed paths, duplicate IDs, and safe identifier truncation or rejection. | Session 03 | Transcript paths and terminal-local identifiers are sensitive and must stay redacted in broad docs, diagnostics, exports, replay, and adapter payloads. | | Mission graph replay and export behavior | `docs/privacy-and-security.md`, `apps/server/src/lib/sessionPrivacy.ts`, `apps/web/src/lib/replayLink.ts` | Planned | Ensure lineage events inherit archive, export, replay-share, and WebSocket redaction before UI controls consume them. | New lineage fields are represented in redaction tests or documented as omitted from export/replay where needed. | Session 03 | No hosted graph persistence, War Room graph sync, or public lineage sharing is introduced in Phase 03 Session 03. | ### Session 04 - Guarded Local Action Runtime | Surface | Current source | Current state | Phase 03 requirement | Acceptance notes | Owner session | Safety boundary | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------ | | Guarded action lifecycle contracts | `.spec_system/PRD/phase_03/session_04_guarded_local_action_runtime.md`, `packages/protocol/src/events.ts`, `docs/api/event-api-hook-contracts.md` | Planned | Define action proposal, approval, rejection, expiration, execution-result, unavailable, and failed contracts before any mutating action executes. | Protocol, server, and tests cover duplicate approvals, expired actions, unavailable dependencies, and compact failure envelopes. | Session 04 | No hidden automatic remote command execution; every mutating action needs explicit state and permission boundaries. | | File action proposals | `apps/server/src/lib/unsupportedRoutes.ts`, `packages/protocol/src/events.ts`, `apps/hooks/src/factionos-file-access.js` | Planned with current observability | Convert only approved file-operation route families into guarded local proposals or explicit unavailable responses. | Read/write/edit proposal payloads validate target, operation, requester, and redacted preview; unapproved file routes stay 501 planned. | Session 04 | File contents and broad absolute paths must not be exposed in docs, errors, adapter payloads, replay links, or exports. | | Git action proposals | `apps/hooks/src/factionos-git-guard.js`, `apps/server/src/lib/unsupportedRoutes.ts`, `docs/api/event-api-hook-contracts.md` | Planned with current hook guard | Define guarded git proposal behavior separately from the current observing or restricted hook guard. | Dangerous commands are rejected or require explicit approval according to local policy; responses redact command bodies and preserve restricted-mode behavior. | Session 04 | No force push, history rewrite, branch deletion, or shell execution is hidden behind a passive observability event. | | Terminal and internal-hero commands | `apps/server/src/lib/unsupportedRoutes.ts`, `apps/hooks/src/factionos-bash-command.js`, `docs/api/README_api.md` | Planned with current observability | Keep bash command ingest as observability until a guarded terminal action contract exists. | Terminal route families either implement approved proposal states or continue returning planned 501 responses; tests cover no raw command leakage. | Session 04 | Terminal output, command bodies, prompt text, and transcript snippets remain sensitive developer data. | | Remote access and Docker/container routes | `apps/server/src/lib/unsupportedRoutes.ts`, `.spec_system/PRD/phase_03/session_04_guarded_local_action_runtime.md`, `.spec_system/PRD/PRD.md` | Deferred or excluded | Preserve explicit deferral for remote-access and container isolation routes unless a later PRD adds a separate permission and isolation model. | `/remote-access/*`, `/detect-ides`, and `/container/*` remain deterministic 501 planned/deferred responses in Phase 03 MVP. | Session 04 | Phase 03 local orchestration must not imply broad remote execution, tunnels, Docker isolation, or remote device control. | | Permission and plan approval bridge | `apps/server/src/routes/permission.ts`, `apps/server/src/ws/handlers.ts`, `apps/web/README_web.md` | Tested-shipped for current approvals | Reuse duplicate-response and pending-state lessons for guarded action decisions without overloading current plan/permission contracts. | New guarded action approval states have explicit request IDs, expiry, requester, result, and duplicate guards; current plan/permission behavior remains compatible. | Session 04 | Approval responses must reveal only stable, intentional error details and must not echo raw payloads. | ### Session 05 - Web Orchestration Cockpit Controls | Surface | Current source | Current state | Phase 03 requirement | Acceptance notes | Owner session | Safety boundary | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------- | | Queue and template cockpit controls | `apps/web/README_web.md`, `.spec_system/PRD/phase_03/session_05_web_orchestration_cockpit_controls.md` | Planned | Add local cockpit controls for queue inspection, template selection, unavailable states, and validated local errors after Session 02 contracts exist. | Controls expose loading, empty, disconnected, unavailable, failed, accepted, and rejected states with accessible names and no blank panels. | Session 05 | UI must not imply hosted queues, shared queues, analytics dashboards, inbound chat commands, or public replay hosting. | | Subagent lineage cockpit controls | `apps/web/README_web.md`, `.spec_system/PRD/phase_03/session_05_web_orchestration_cockpit_controls.md` | Planned | Show parent-child mission lineage and subagent status only after Session 03 runtime frames exist. | Selected hero, mission, queue, and lineage context remains synchronized across roster, mission detail, and new orchestration surfaces. | Session 05 | Lineage UI must redact transcript-derived identifiers and degrade when lineage data is missing or unavailable. | | Guarded action decision controls | `apps/web/README_web.md`, `docs/api/README_api.md`, `.spec_system/PRD/phase_03/session_05_web_orchestration_cockpit_controls.md` | Planned | Surface guarded action proposals with pending, accepted, rejected, expired, unavailable, and failed states after Session 04 contracts exist. | Duplicate clicks are disabled or ignored, decisions are keyboard reachable, and failures use bounded copy. | Session 05 | Browser controls are local runtime controls only and must not imply remote execution or hosted approval. | ### Session 06 - CLI Diagnostics And Recovery Controls | Surface | Current source | Current state | Phase 03 requirement | Acceptance notes | Owner session | Safety boundary | | ------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------- | | CLI orchestration diagnostics | `apps/cli/README_cli.md`, `.spec_system/PRD/phase_03/session_06_cli_diagnostics_and_recovery_controls.md` | Planned | Extend status and doctor output for queue, template, lineage, guarded-action, listener, hook, and spool posture after Sessions 02-04 define state. | CLI reports healthy, missing, stale, malformed, unavailable server, unavailable listener, and recovery states without raw payloads. | Session 06 | Diagnostics must avoid raw prompts, command bodies, terminal output, file contents, tokens, and spool entry data. | | Hook and listener orchestration diagnostics | `apps/hooks/README_hooks.md`, `apps/hooks/src/ws-listener.js`, `apps/hooks/src/_lib.js` | Shipped base diagnostics, planned orchestration detail | Improve hook/listener diagnostics for orchestration events without changing quiet failure behavior. | Logs record handler names, event kinds, durations, counts, status codes, safe IDs, and malformed-state summaries only. | Session 06 | Hook handlers must remain timeout-bounded, silent in normal operation, and safe when the local server is down. | | Bounded local recovery controls | `apps/cli/README_cli.md`, `.spec_system/PRD/phase_03/session_06_cli_diagnostics_and_recovery_controls.md` | Planned | Add only approved local reset/recovery controls for stale Phase 03 state after state files and contracts exist. | Malformed queue/action/lineage state can be reported or reset without deleting unrelated archives, memory, browser settings, or workspace files. | Session 06 | Unified erasure remains Phase 08; recovery controls must be narrow and auditable. | ### Session 07 - Orchestration Validation And Documentation Closeout | Surface | Current source | Current state | Phase 03 requirement | Acceptance notes | Owner session | Safety boundary | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------- | | Phase 03 quality gates | `.spec_system/PRD/phase_03/session_07_orchestration_validation_and_documentation_closeout.md`, `.spec_system/CONVENTIONS.md`, `package.json` | Tested-shipped | Run focused and repo-wide quality gates appropriate to Sessions 02-06 changes. | Session 07 records protocol/server/hook/CLI/web tests, browser evidence, root gates, ASCII/LF, and `git diff --check` in the closeout artifacts. | Session 07 | Failed checks require reproducible notes and cannot be hidden behind a completed-session claim. | | Stable docs closeout | `docs/ARCHITECTURE.md`, `docs/api/README_api.md`, `docs/api/event-api-hook-contracts.md`, package READMEs, PRD, UX PRD | Shipped | Update stable docs to describe only shipped Phase 03 behavior and retain deferred later-phase boundaries. | Docs distinguish shipped, tested-shipped, typed-only, planned, unsupported, stubbed, separate-surface, deferred, excluded, and evidence-only behavior. | Session 07 | Do not overstate hosted, Worker federation, analytics, media, collaboration, or release-decommission scope. | | Security and privacy closeout | `.spec_system/SECURITY-COMPLIANCE.md`, `docs/privacy-and-security.md`, session security reports | Shipped | Re-audit orchestration surfaces for external transfer, redaction, local state, diagnostics, replay, exports, adapters, and erasure gaps. | Security closeout confirms no new external transfer, credential, hosted dependency, or raw-data exposure and carries unified erasure forward. | Session 07 | Any future external transfer, credential, hosted dependency, or raw-data exposure must be explicit and reviewed. | ## Boundary Rows | Surface | Current source | Current state | Phase 03 requirement | Acceptance notes | Owner session | Safety boundary | | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------- | | War Room web-to-Worker federation | `apps/warroom/README_warroom.md`, `apps/web/README_web.md`, `docs/api/README_api.md` | Separate-surface and deferred | Keep Phase 03 local orchestration separate from Worker room federation. | Local docs and UI copy continue to mark the web panel as stubbed or separate-surface until Phase 05. | Session 01 and Session 07 | Phase 05 owns room creation, join, approval, reconnect, catch-up, sender exclusion, and participant trust boundaries. | | Hosted services, analytics, and public sharing | `docs/privacy-and-security.md`, `docs/hosted-services.md`, `.spec_system/PRD/PRD.md` | Deferred | Do not add hosted auth, hosted persistence, analytics, public replay hosting, public sharing, or production hosted validation in Phase 03. | Phase 03 docs preserve local-only defaults and note later hosted-service guardrails. | Session 01 and Session 07 | External transfers need opt-in, consent, authorization, scrubbing, and tests in later phases. | | Inbound chat and webhook commands | `apps/adapters/README_adapters.md`, `apps/server/src/lib/unsupportedRoutes.ts`, `docs/privacy-and-security.md` | Deferred | Preserve outbound-only adapters and keep inbound webhook/chat command routes unsupported until a new permission and audit model exists. | Adapter docs and unsupported route responses do not imply inbound command support. | Session 01 and Session 07 | Inbound commands are a separate trust boundary and must not be introduced through queue or guarded-action work. | | Historical orchestration evidence | `EXAMPLES/findings/`, `EXAMPLES/1st-pass-artifacts/`, `docs/legacy-consolidation.md` | Evidence-only | Use historical route, event, hook, template, Docker, and package evidence only for traceability and explicit disposition. | Stable docs cite conclusions and paths only; no raw historical prompts, paths, tokens, command output, bundled code, or media are copied. | Session 01 and Session 07 | Phase 08 owns deletion and final decommission gates. | | Docker isolation and container routes | `apps/server/src/lib/unsupportedRoutes.ts`, `.spec_system/PRD/phase_03/PRD_phase_03.md` | Deferred or excluded | Keep Docker/container isolation out of the Phase 03 MVP unless a later PRD explicitly adds isolation requirements. | Container route families remain explicit planned/deferred 501 responses. | Session 01 and Session 07 | Container execution changes require a separate threat model and validation plan. | --- # 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/phases/phase_03/orchestration_gap_matrix.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.