> 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/phase03-session01-orchestration-requirements-and-safety-baseline/spec.md). # Session Specification **Session ID**: `phase03-session01-orchestration-requirements-and-safety-baseline` **Phase**: 03 - Agent Orchestration **Status**: Completed **Created**: 2026-05-29 **Package**: Cross-cutting **Package Stack**: npm workspace documentation, TypeScript protocol planning, JavaScript hook and CLI planning *** ## 1. Session Overview This session creates the source-backed requirements and safety baseline for Phase 03 before any orchestration runtime is implemented. It reconciles the shipped local observability runtime with the planned task queue, agent template, subagent lineage, guarded action, web control, and CLI diagnostic work. The work is intentionally documentation-first and cross-cutting. It gives later Phase 03 sessions a single routing matrix that identifies which session owns each orchestration gap, what current source proves, what acceptance criteria apply, and which capabilities remain deferred or excluded. The session also preserves the local-first privacy posture from Phases 01 and 02. Prompts, paths, commands, transcripts, terminal output, local state, replay data, exports, adapters, War Room surfaces, hosted services, and historical artifacts must remain bounded and clearly classified before queue, action, lineage, or cockpit controls are added. *** ## 2. Objectives 1. Create a source-backed Phase 03 orchestration gap matrix with current source evidence, owner sessions, acceptance notes, and deferral boundaries. 2. Define Phase 03 ownership for task queues, agent templates, subagent lineage, guarded local actions, web controls, and CLI diagnostics. 3. Align PRD, UX PRD, architecture, API, event/hook, legacy, package README, and privacy docs around current-versus-planned orchestration behavior. 4. Capture a security and privacy baseline that keeps orchestration local-first, permission-aware, redacted, and separate from hosted collaboration or remote command execution. *** ## 3. Prerequisites ### Required Sessions * [x] `phase02-session07-product-surface-validation-and-documentation-closeout` - provides current browser closeout, documentation handoff, quality gate expectations, and later-phase boundaries. * [x] `phase01-session07-runtime-contract-documentation` - provides stable local runtime API, event, hook, WebSocket, and privacy contracts for Phase 03 planning. ### Required Tools/Knowledge * Node 20+, npm workspaces, Biome, Vitest, and package-local typecheck conventions. * Current stable docs: `docs/ARCHITECTURE.md`, `docs/api/README_api.md`, `docs/api/event-api-hook-contracts.md`, package README files, `docs/privacy-and-security.md`, and `docs/legacy-consolidation.md`. * Spec system sources: `.spec_system/PRD/PRD.md`, `.spec_system/PRD/PRD_UX.md`, `.spec_system/PRD/phase_03/PRD_phase_03.md`, `.spec_system/CONSIDERATIONS.md`, `.spec_system/CONVENTIONS.md`, and `.spec_system/SECURITY-COMPLIANCE.md`. ### Environment Requirements * Local checkout of the FactionOS monorepo with Phase 03 session stubs available. * No hosted service credentials are required. * `EXAMPLES/` may be used only as evidence if needed; do not copy raw historical prompts, probes, tokens, paths, bundled code, or media into stable docs. *** ## 4. Scope ### In Scope (MVP) * Maintainers can inventory current shipped, typed-only, planned, unsupported, stubbed, separate-surface, deferred, and excluded orchestration behavior - create a matrix with current source anchors and status values. * Maintainers can route each Phase 03 orchestration gap to an owner session - include task queues, templates, lineage, guarded actions, web controls, CLI diagnostics, validation, and documentation closeout. * Maintainers can distinguish local orchestration from War Room federation, hosted collaboration, inbound chat commands, public sharing, analytics, Docker isolation, and remote execution - update PRD and stable docs with explicit boundaries. * Implementers can preserve privacy constraints for prompts, paths, commands, terminal output, transcripts, local state, replay, exports, adapters, and future external transfers - capture a security baseline before implementation sessions. ### Out of Scope (Deferred) * Queue runtime, action execution, web controls, CLI commands, or protocol implementation - *Reason: Sessions 02 through 06 own implementation after this baseline exists.* * War Room web-to-Worker federation - *Reason: Phase 05 owns Worker integration and participant trust boundaries.* * Hosted collaboration, hosted persistence, analytics, public replay hosting, inbound chat commands, or broad remote execution - *Reason: later phases own these surfaces and require separate consent, authorization, and privacy models.* * Docker or container isolation routes - *Reason: not part of the Phase 03 MVP unless a later PRD explicitly adds them.* * Historical source or media promotion into runtime code - *Reason: `EXAMPLES/` remains evidence only until Phase 08 release gates approve deletion or promotion decisions.* *** ## 5. Technical Approach ### Architecture The session uses a documentation-as-contract approach. Current source, tests, package README files, API docs, and existing PRD wording are treated as evidence, then consolidated into a Phase 03 orchestration gap matrix. The matrix becomes routing source material for later sessions, while stable docs keep user-facing current behavior honest. Protocol remains the lead owner for shared queue, template, lineage, guarded-action, event, and WebSocket shapes. Server, hooks, CLI, web, adapters, and Worker docs should describe their current boundary and the Phase 03 handoff without duplicating protocol contracts or claiming future support as shipped. ### Design Patterns * Protocol-first planning: shared contracts are defined in `packages/protocol` before server, hook, CLI, or web packages consume them. * Evidence-only historical intake: historical files can support traceability, but stable docs must capture conclusions and not raw sensitive content. * Explicit capability status: planned and unsupported orchestration route families stay deterministic and documented rather than appearing as accidental gaps. * Local-first privacy baseline: every future orchestration data path starts from loopback defaults, auth/origin/rate-limit inheritance, redaction, and no external transfer unless explicitly configured. ### Technology Stack * Markdown for PRD, docs, README, and matrix deliverables. * npm workspace with Node 20+ baseline. * TypeScript packages: `packages/protocol`, `apps/server`, `apps/web`, `apps/adapters`, `apps/warroom`. * JavaScript packages: `apps/cli`, `apps/hooks`. * Validation tools: Biome formatting check, repo diff checks, focused path/link review, and privacy-sensitive copy review. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/PRD/phase_03/orchestration_gap_matrix.md` | Source-backed Phase 03 orchestration matrix with current state, owner sessions, acceptance notes, and deferral boundaries | \~220 | | `.spec_system/specs/phase03-session01-orchestration-requirements-and-safety-baseline/implementation-notes.md` | Session implementation record and evidence summary | \~80 | | `.spec_system/specs/phase03-session01-orchestration-requirements-and-safety-baseline/security-compliance.md` | Session-specific security and privacy baseline notes | \~80 | ### Files to Modify | File | Changes | Est. Lines | | -------------------------------------- | -------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/PRD/PRD.md` | Refine Phase 03 orchestration requirements, ownership, and exclusions | \~40 | | `.spec_system/PRD/PRD_UX.md` | Add Phase 03 UX expectations for orchestration controls and non-goals | \~35 | | `docs/ARCHITECTURE.md` | Clarify current versus planned orchestration architecture and data boundaries | \~35 | | `docs/api/README_api.md` | Clarify planned orchestration route families and current unsupported behavior | \~35 | | `docs/api/event-api-hook-contracts.md` | Route typed-only, opaque, planned, unsupported, and separate-surface orchestration contracts | \~50 | | `docs/legacy-consolidation.md` | Capture Phase 03 historical-source ownership and decommission boundaries | \~35 | | `docs/privacy-and-security.md` | Add orchestration-specific data and transfer risks without claiming new shipped flows | \~35 | | `.spec_system/SECURITY-COMPLIANCE.md` | Record the Phase 03 planning baseline with no new open findings unless discovered | \~25 | | `packages/protocol/README_protocol.md` | Clarify protocol ownership for Phase 03 contracts | \~20 | | `apps/server/README_server.md` | Clarify local orchestration route boundary and inherited server protections | \~20 | | `apps/hooks/README_hooks.md` | Clarify subagent and guarded-action hook planning boundaries | \~20 | | `apps/cli/README_cli.md` | Clarify Phase 03 diagnostics and recovery planning boundaries | \~20 | | `apps/web/README_web.md` | Clarify planned orchestration cockpit controls and deferred collaboration claims | \~20 | | `apps/adapters/README_adapters.md` | Preserve outbound-only adapter boundary for future orchestration events | \~15 | | `apps/warroom/README_warroom.md` | Preserve Worker separate-surface boundary for Phase 03 local orchestration | \~15 | *** ## 7. Success Criteria ### Functional Requirements * [x] Phase 03 orchestration gap matrix exists and routes every Phase 03 stub area to an owner session. * [x] Matrix rows distinguish current shipped, typed-only, planned, unsupported, stubbed, separate-surface, deferred, excluded, and evidence-only behavior. * [x] PRD and UX PRD separate local orchestration from War Room federation, hosted collaboration, inbound chat commands, public sharing, analytics, Docker isolation, and remote execution. * [x] Stable docs and package READMEs describe current behavior without implying implementation of later Phase 03 sessions. * [x] Security and privacy baseline is explicit for prompts, paths, commands, terminal output, transcripts, local state, replay, exports, adapters, and future external transfer. ### Testing Requirements * [x] Documentation path and link references reviewed for changed files. * [x] Privacy-sensitive copy review completed for raw prompts, tokens, OAuth IDs, probe output, command bodies, raw local paths, and historical excerpts. * [x] ASCII/LF checks completed for all session outputs. * [x] `git diff --check` completed. * [x] Implementation notes record commands run, files changed, and any blocked validation. ### Non-Functional Requirements * [x] Local-first operation remains the default and no hosted service becomes required. * [x] No new runtime dependency, network transfer, credential requirement, or production database requirement is introduced. * [x] Historical evidence is summarized by conclusion and path only, not copied into stable docs as raw content. ### 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 planning and documentation baseline, not runtime implementation. * The gap matrix should mirror the useful structure of the Phase 02 product surface matrix while using Phase 03 orchestration-specific status values. * Current source and tests outrank historical extraction files. Historical paths may be cited for traceability only. * Package README updates should be concise and should point to the matrix or stable docs instead of duplicating large route or event tables. ### Potential Challenges * Scope bleed into implementation: keep queue, action, lineage, web, and CLI work as documented ownership and acceptance criteria only. * Historical parity pressure: classify historical route and event claims as evidence, planned, unsupported, obsolete, or deferred instead of implying shipped behavior. * Privacy drift: keep any examples abstract and avoid raw prompts, command bodies, local absolute paths, terminal output, tokens, provider errors, or copied historical payloads. * Cross-package duplication: write shared contract ownership once in protocol and route package docs to that source. ### Relevant Considerations * \[P01] **Redaction is boundary-specific**: Phase 03 planning must assign redaction requirements to every future orchestration data boundary before implementation. * \[P01-apps/server] **Local server boundary must stay conservative**: future orchestration routes and WebSocket frames must inherit auth, origin, CORS, rate-limit, body-size, and validation defaults. * \[P01-packages/protocol] **Protocol leads cross-package work**: queue, template, lineage, and guarded-action shapes should start in protocol before package wiring. * \[P01-apps/warroom+apps/web] **War Room is not wired into the web runtime yet**: Phase 03 local orchestration must not imply Worker federation. * \[P01] **Unified erasure still missing**: any Phase 03 state should be easy to include in later trusted reset and erasure workflows. * \[P00-apps/adapters] **Chat adapters are outbound only**: future orchestration events must not open inbound command paths without a new permission and audit model. *** ## 9. Testing Strategy ### Unit Tests * No application unit tests are expected because this session produces documentation and planning artifacts only. ### Integration Tests * Run `git diff --check` for whitespace validation. * Run a focused docs path/link review for changed Markdown references. * If docs tooling is available in the repo, run the relevant docs check; otherwise record manual validation in implementation notes. ### Manual Testing * Review the matrix against all seven Phase 03 stubs to confirm each future session has clear ownership and acceptance criteria. * Review changed docs for current-versus-planned wording and local-first privacy posture. * Review package README changes for concise package ownership without duplicated contract drift. ### Edge Cases * Historical route, event, hook, or template evidence appears to imply runtime support; classify it without copying raw sensitive content. * A capability belongs to War Room Worker federation, hosted services, inbound chat, analytics, Docker isolation, or release decommission; defer it explicitly. * Existing docs already contain future-oriented terms; rewrite them to separate current behavior from planned Phase 03 work. *** ## 10. Dependencies ### External Libraries * None. ### Other Sessions * **Depends on**: `phase01-session07-runtime-contract-documentation`, `phase02-session07-product-surface-validation-and-documentation-closeout` * **Depended by**: `phase03-session02-task-queue-and-agent-template-contracts`, `phase03-session03-subagent-lineage-and-mission-graph-runtime`, `phase03-session04-guarded-local-action-runtime`, `phase03-session05-web-orchestration-cockpit-controls`, `phase03-session06-cli-diagnostics-and-recovery-controls`, `phase03-session07-orchestration-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/phase03-session01-orchestration-requirements-and-safety-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.