> 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-session07-orchestration-validation-and-documentation-closeout/spec.md). # Session Specification **Session ID**: `phase03-session07-orchestration-validation-and-documentation-closeout` **Phase**: 03 - Agent Orchestration **Status**: Not Started **Created**: 2026-05-29 **Package**: Cross-cutting (`packages/protocol`, `apps/server`, `apps/hooks`, `apps/cli`, `apps/web`, docs, spec system) **Package Stack**: Node 20, TypeScript protocol/server/web, JavaScript CLI/hooks, React 18, Vite, Express, WebSocket, Vitest, Playwright, Biome, npm workspaces *** ## 1. Session Overview This session closes Phase 03 by validating the local orchestration layer end to end and aligning stable documentation with the behavior shipped in Sessions 02 through 06. The phase now has protocol-owned task queue, agent template, lineage, mission graph, guarded-action, web-control, CLI diagnostic, hook diagnostic, and server diagnostic surfaces; Session 07 turns that implementation into reproducible quality evidence and an honest documentation contract. The work is cross-cutting because Phase 03 spans `packages/protocol`, `apps/server`, `apps/hooks`, `apps/cli`, `apps/web`, stable docs, PRD files, security records, and spec-system closeout artifacts. The goal is not to add another feature. The goal is to prove the current local-first orchestration behavior, fix only validation-discovered closeout gaps, and make sure docs do not overclaim hosted collaboration, War Room federation, inbound commands, analytics, Docker isolation, remote execution, media work, or final release decommissioning. The session is next because the refreshed project analysis reports Sessions 01 through 06 complete and Session 07 as the only unfinished Phase 03 candidate. Completing this session prepares the project for `validate`, `updateprd`, and then the phase-transition commands. *** ## 2. Objectives 1. Run focused and repo-wide quality gates for Phase 03 protocol, server, hooks, CLI, web, docs, and spec artifacts. 2. Capture browser evidence for the Phase 03 web orchestration controls, including desktop and mobile smoke coverage, guard assertions, and visible unavailable or empty states. 3. Update stable docs, package README files, PRD files, UX PRD, gap matrix, security records, and considerations to reflect only shipped Phase 03 behavior and explicit deferrals. 4. Produce implementation notes, security/privacy closeout, validation report, implementation summary, and remaining-gap handoff for Phases 04 through 08. *** ## 3. Prerequisites ### Required Sessions * [x] `phase03-session01-orchestration-requirements-and-safety-baseline` - provides the Phase 03 routing matrix, safety baseline, and deferral boundaries. * [x] `phase03-session02-task-queue-and-agent-template-contracts` - provides protocol and server queue/template contracts. * [x] `phase03-session03-subagent-lineage-and-mission-graph-runtime` - provides typed lineage and mission graph runtime behavior. * [x] `phase03-session04-guarded-local-action-runtime` - provides guarded-action proposal, decision, unavailable, and duplicate-decision behavior. * [x] `phase03-session05-web-orchestration-cockpit-controls` - provides web cockpit orchestration controls and browser smoke evidence. * [x] `phase03-session06-cli-diagnostics-and-recovery-controls` - provides CLI, hook/listener, and server diagnostics plus bounded recovery behavior. ### Required Tools/Knowledge * Node 20+, npm workspaces, Biome, TypeScript, Vitest, and Playwright. * Current package README files for protocol, server, hooks, CLI, and web behavior. * Phase 03 PRD, UX PRD, orchestration gap matrix, security baseline, and previous session validation artifacts. * Local browser validation patterns in `tests/e2e/app.e2e.ts` and browser guard helpers. ### Environment Requirements * Repository dependencies are installed. * Root validation commands can run from the repository root. * Browser validation can start or reuse the local app server on configured ports. * No hosted account, hosted storage, analytics, Cloudflare Worker federation, Anthropic transfer, Discord, Telegram, generic webhook, Supabase, Docker, or database credential is required. * Historical `EXAMPLES/` content remains evidence only and must not be copied into stable docs, tests, reports, or runtime files. *** ## 4. Scope ### In Scope (MVP) * Maintainer can verify Phase 03 behavior - run focused package tests, browser smoke, root quality gates, and record exact command outcomes or explicit blockers. * User can trust stable docs - update docs and README files so queue/template, lineage/mission graph, guarded actions, web controls, CLI diagnostics, and hook/listener diagnostics are described as shipped only where they are actually implemented. * Reviewer can audit privacy posture - document local-first defaults, redaction, compact diagnostics, bounded recovery, WebSocket frame sanitization, replay/export/archive implications, and remaining erasure risks. * Future sessions have a clean handoff - update PRD, UX PRD, gap matrix, considerations, security records, implementation summary, and remaining-gap notes for Phases 04 through 08. * Browser evidence covers web orchestration controls - verify desktop and mobile cockpit access, loading/empty/error/offline or unavailable states, guard assertions, and visible local-only wording. ### Out of Scope (Deferred) * New queue, template, lineage, guarded-action, CLI recovery, hook, or web orchestration feature work - *Reason: Session 07 validates and documents existing Phase 03 behavior only.* * War Room web-to-Worker federation - *Reason: Phase 05 owns room creation, participant trust, reconnect, catch-up, sender exclusion, and federation.* * Hosted queues, hosted storage, analytics, public replay hosting, inbound chat commands, webhook commands, remote execution, or Docker/container isolation - *Reason: later phases need separate authorization, audit, scrubbing, and threat models.* * Unified erasure across archives, memory, browser state, diagnostics, replay, and release state - *Reason: Phase 08 owns trusted release hardening and decommission gates.* * Full WCAG certification or production-hosted validation - *Reason: this session runs practical local validation, not a certification program.* *** ## 5. Technical Approach ### Architecture Use existing validation infrastructure first. Focused tests already cover protocol contracts, server routes and WebSocket frames, hooks, CLI diagnostics, and web orchestration controls. Browser smoke should exercise the local app through the Playwright projects and existing browser guards before adding new test harnesses. Only add or modify tests if closeout evidence is materially missing or validation exposes a reproducible bug. Treat documentation as the current release-facing contract. Align `README.md`, package README files, `docs/api/`, architecture, privacy, legacy-consolidation, PRD, UX PRD, the Phase 03 PRD, and the orchestration gap matrix with the shipped local behavior. Keep status vocabulary explicit: shipped, tested-shipped, typed-only, planned, unsupported, stubbed, separate-surface, deferred, excluded, and evidence-only. Keep security closeout bounded. Phase 03 data paths include queue entries, template suggestions, lineage IDs, mission graph frames, guarded-action proposals, diagnostics snapshots, hook/listener logs, CLI recovery summaries, WebSocket frames, browser state, replay/export/archive paths, and docs. Reports should summarize posture and findings without copying raw prompts, command bodies, terminal output, tokens, broad absolute paths, transcript paths, raw state file contents, or raw historical artifacts. ### Design Patterns * Evidence-first closeout: capture command results, browser evidence, docs matrix decisions, and blockers before marking the phase ready. * Small corrective fixes: if validation finds a narrow issue, fix the owning file and rerun the affected gate before closeout. * Local-first boundary language: keep optional hosted and external services clearly optional or deferred. * Protocol-led documentation: describe shared queue, lineage, event, WebSocket, and guarded-action shapes from `packages/protocol` and API docs before app-specific consumers. * Deferral discipline: record later-phase work without starting Phase 04, Phase 05, Phase 06, Phase 07, or Phase 08 implementation. ### Technology Stack * TypeScript contracts and tests in `packages/protocol`. * Express, WebSocket, managers, routes, and Vitest in `apps/server`. * JavaScript hook handlers, listener runtime, and Node tests in `apps/hooks`. * JavaScript CLI commands, local file helpers, diagnostics helpers, and Node tests in `apps/cli`. * React 18, Vite, Zustand, Testing Library, and Playwright for `apps/web`. * Biome, npm workspace scripts, and root validation commands. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------- | | `.spec_system/specs/phase03-session07-orchestration-validation-and-documentation-closeout/implementation-notes.md` | Command log, browser evidence, docs matrix, blockers, fixes, and handoff notes | \~220 | | `.spec_system/specs/phase03-session07-orchestration-validation-and-documentation-closeout/security-compliance.md` | Phase 03 security, privacy, GDPR, and local-first closeout | \~160 | | `.spec_system/specs/phase03-session07-orchestration-validation-and-documentation-closeout/validation.md` | Final Session 07 validation report | \~200 | | `.spec_system/specs/phase03-session07-orchestration-validation-and-documentation-closeout/IMPLEMENTATION_SUMMARY.md` | Session summary and phase-transition handoff | \~140 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------- | | `tests/e2e/app.e2e.ts` | Extend orchestration cockpit browser evidence only if current coverage is insufficient | \~60 | | `tests/e2e/support/browserGuards.ts` | Tighten guard reporting only if validation needs clearer failure evidence | \~30 | | `README.md` | Align Phase 03 shipped behavior and local-first boundaries | \~50 | | `packages/protocol/README_protocol.md` | Confirm protocol-owned orchestration contracts and remaining deferred shapes | \~50 | | `apps/server/README_server.md` | Confirm orchestration routes, diagnostics, auth inheritance, and non-execution boundaries | \~60 | | `apps/hooks/README_hooks.md` | Confirm lineage hooks, diagnostics, quiet failure, and sensitive-data limits | \~45 | | `apps/cli/README_cli.md` | Confirm status, doctor, diagnostics, and narrow recovery behavior | \~45 | | `apps/web/README_web.md` | Confirm local orchestration cockpit controls, unavailable states, and no hosted/Worker claims | \~60 | | `docs/ARCHITECTURE.md` | Replace stale Phase 03 planning language with shipped local orchestration architecture | \~70 | | `docs/api/README_api.md` | Align API route and WebSocket contract status after Sessions 02-06 | \~70 | | `docs/api/event-api-hook-contracts.md` | Align hook/event/route classifications and diagnostics status | \~80 | | `docs/privacy-and-security.md` | Add Phase 03 privacy closeout and remaining erasure/external-transfer risks | \~70 | | `docs/legacy-consolidation.md` | Update retained orchestration value and evidence-only boundaries | \~60 | | `docs/README_docs.md` | Refresh stable-doc routing and Phase 03 closeout status | \~35 | | `.spec_system/PRD/PRD.md` | Update Phase 03 status map and remaining phase handoff | \~50 | | `.spec_system/PRD/PRD_UX.md` | Update local orchestration UX status and evidence notes | \~50 | | `.spec_system/PRD/phase_03/PRD_phase_03.md` | Mark Session 07 complete during implementation closeout, not during planning | \~35 | | `.spec_system/PRD/phase_03/orchestration_gap_matrix.md` | Update Session 07 acceptance evidence and remaining deferrals | \~60 | | `.spec_system/SECURITY-COMPLIANCE.md` | Record Phase 03 security closeout findings or clean result | \~60 | | `.spec_system/CONSIDERATIONS.md` | Carry forward relevant Phase 03 lessons and active risks | \~60 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Phase 03 focused tests pass for protocol, server, hooks, CLI, and web orchestration surfaces, or blockers are explicit and reproducible. * [ ] Root quality gates pass or have explicit blocker notes: format check, lint, workspace typecheck, Vitest, e2e browser smoke, security scans where appropriate, ASCII/LF checks, and `git diff --check`. * [ ] Browser evidence records desktop and mobile orchestration cockpit behavior with guard assertions, visible local-only boundaries, and loading/empty/error/offline or unavailable states. * [ ] Stable docs and package README files describe shipped Phase 03 behavior without overstating hosted queues, War Room federation, inbound commands, analytics, Docker isolation, remote execution, media work, or release decommission. * [ ] Security closeout records data classes, redaction posture, auth and Origin/CORS inheritance, diagnostics boundaries, recovery limits, and remaining erasure or external-transfer risks. * [ ] Implementation summary and remaining-gap handoff are ready for `validate`, `updateprd`, and phase-transition commands. ### Testing Requirements * [ ] Focused protocol, server, hooks, CLI, and web tests run with command results recorded. * [ ] Browser smoke runs for app desktop and app mobile, or an explicit environmental blocker is documented. * [ ] Static quality gates run from the repository root with exact command results. * [ ] Manual evidence review checks no blank orchestration panel, clipped controls, overlapping text, hidden unavailable state, or misleading hosted/Worker wording. ### Non-Functional Requirements * [ ] All closeout artifacts avoid raw prompts, command bodies, terminal output, file contents, tokens, broad absolute paths, transcript paths, raw state files, and raw historical material. * [ ] Local-first posture remains clear: core Phase 03 behavior works without hosted accounts, hosted persistence, analytics, provider transfer, War Room federation, inbound chat, or remote execution. * [ ] Diagnostics and recovery remain compact, local, explicit, idempotent, and narrow. * [ ] Historical `EXAMPLES/` material remains evidence only and is not promoted, copied, transformed, or deleted. ### Quality Gates * [ ] All spec-system output files are ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code and docs follow project conventions. *** ## 8. Implementation Notes ### Key Considerations * Use the refreshed analysis output as the state baseline: Sessions 01-06 are complete and Session 07 is the only remaining Phase 03 session. * The existing Session 06 artifacts already report validation PASS; this plan includes the narrow state consistency correction that restored Session 06 to `completed_sessions`. * Several stable docs still contain planning-era language for Phase 03. Session 07 should replace stale planning statements with shipped local orchestration behavior where tests and source support it. * If browser validation exposes a real bug, fix the smallest owning surface and rerun the affected focused gate before closeout. * Do not mark Phase 03 fully complete during planning. That belongs to implementation closeout after evidence is collected. ### Potential Challenges * Root quality gates may be long-running: mitigate by running focused package checks first, then root gates, and recording exact blockers. * Browser smoke may fail due to ports or stale local servers: mitigate with Playwright's existing server configuration and explicit environment notes. * Documentation can overclaim current behavior: mitigate by cross-checking each claim against source, tests, validation artifacts, and the gap matrix. * Security reports can accidentally leak sensitive local data: mitigate by summarizing failures and paths in bounded categories rather than copying raw output. * Phase handoff can drift into Phase 04 or Phase 05 implementation: mitigate by recording deferrals and stopping at documentation and validation closeout. ### Relevant Considerations * \[P01] **Stable docs are the current contract**: update stable docs, README files, PRD, UX PRD, and gap matrix to match implemented Phase 03 behavior. * \[P01-packages/protocol] **Protocol leads cross-package work**: verify shared queue, template, lineage, guarded-action, event, and WebSocket contracts are documented from protocol first. * \[P01] **Redaction is boundary-specific**: preserve queue, lineage, guarded-action, diagnostics, replay, export, adapter, archive, and future external-transfer boundaries. * \[P01-apps/server] **Local server boundary must stay conservative**: verify server docs and tests keep loopback, auth, Origin/CORS, rate-limit, validation, and explicit failure behavior. * \[P01-apps/cli+apps/hooks] **Lifecycle state is local and file-based**: keep CLI and hook/listener diagnostics and recovery docs focused on stale local state and quiet failure behavior. * \[P01] **Unified erasure still missing**: do not present Session 06 recovery as trusted erasure; carry forward the release hardening risk. * \[P02] **Honest stub wording matters for deferred surfaces**: keep War Room federation, hosted queues, inbound commands, analytics, Docker isolation, and remote execution clearly deferred or excluded. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Validation can pass commands while missing a visible blank, clipped, or misleading orchestration UI state. * Documentation can mark planned, unsupported, separate-surface, deferred, or evidence-only behavior as shipped. * Security closeout can copy raw local paths, command output, prompts, tokens, transcripts, or state payloads into reports. * Browser smoke can verify the cockpit shell but not the Phase 03 orchestration controls and unavailable states. * Remaining-gap handoff can blur into later-phase implementation instead of preserving scope. *** ## 9. Testing Strategy ### Unit Tests * Run focused protocol tests for orchestration, guarded actions, lineage, events, ingest, and REST contracts. * Run focused server tests for orchestration routes, guarded actions, diagnostics, WebSocket frames, event ingest, auth boundaries, and unsupported routes. * Run focused CLI and hook tests for lifecycle, diagnostics, guarded actions, hook payloads, hook runtime, listener runtime, and orchestration diagnostics. * Run focused web tests for the orchestration panel, store, API helpers, cockpit shell, WebSocket privacy, and related UI state helpers. ### Integration Tests * Run root `npm test` or document a reproducible blocker. * Run `npm run typecheck --workspaces --if-present`, `npm run format:check`, and `npm run lint`. * Run `npm run test:e2e -- --project=app-desktop --project=app-mobile tests/e2e/app.e2e.ts` for browser evidence. * Run `npm run battlefield:check` only if touched docs or evidence still reference app/demo asset parity. * Run `npm run security:secrets` when closeout docs or code changes may introduce sensitive strings. ### Manual Testing * Inspect Playwright screenshots for reachable orchestration controls, visible unavailable states, readable labels, no obvious overlap, no clipped controls, and no blank panels. * Review docs and README files for status vocabulary, shipped/deferred boundaries, and local-only language. * Review security and validation reports for accidental sensitive output before marking tasks complete. ### Edge Cases * Local server unavailable, auth required, WebSocket disconnected, or diagnostics route unavailable. * Empty queue, empty template list, empty mission graph, expired guarded actions, and unavailable guarded-action execution. * Malformed hook/listener state and stale local diagnostic files. * Browser localStorage with stale or malformed orchestration state. * Deferred surfaces accidentally described as shipped: War Room federation, hosted queues, inbound commands, analytics, Docker isolation, remote execution, media catalog, and release decommission. * Historical `EXAMPLES/` content accidentally promoted into current docs or runtime claims. *** ## 10. Dependencies ### External Libraries * Node 20 built-ins for CLI, hooks, and scripts. * Express 4 and `ws` 8.21.0 in `apps/server`. * React 18.3.1, Vite 6.4.2, Zustand, and Testing Library in `apps/web`. * Vitest 4.1.7, Playwright 1.60.0, and Biome 2.4.16 for validation. ### Other Sessions * **Depends on**: `phase03-session01-orchestration-requirements-and-safety-baseline`, `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`. * **Depended by**: Phase transition workflow: `validate`, `updateprd`, `audit`, `pipeline`, `infra`, `carryforward`, `documents`, and then `phasebuild` if the PRD still defines another unfinished phase. *** ## 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-session07-orchestration-validation-and-documentation-closeout/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.