> 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/phase17-session10-validation-documentation-and-handoff/spec.md). # Session Specification **Session ID**: `phase17-session10-validation-documentation-and-handoff` **Phase**: 17 - Notice Board Coordination Parity **Status**: Completed **Validated**: 2026-06-06 **Created**: 2026-06-06 **Package**: Cross-package (`docs`, `apps/server`, `apps/web`, `apps/cli`, `apps/hooks`, `apps/warroom`, `packages/protocol`) **Package Stack**: Markdown docs, npm workspaces, TypeScript/JavaScript validation, Vitest, local Express/WebSocket runtime *** ## 1. Session Overview This session closes the Phase 17 Notice Board port by validating the complete coordination path and moving the recovered behavior into durable documentation. Sessions 01 through 09 restored the protocol contracts, persistent manager, canonical routes, WebSocket events, web cockpit surface, CLI commands, hook context, War Room relay and catch-up, local bridge convergence, room notice conversion, and automatic mission lifecycle posts. The remaining work is to prove the port behaves end to end and make the stable docs match the shipped system. The session is cross-package but documentation- and evidence-led. It should update the stable docs that users and future agents rely on, then record focused validation for canonical routes, compatibility routes, CLI commands, hook context, War Room relay, room notice conversion, automatic posts, persistence, pruning, targeting, related-file safety, and sensitive payload exclusions. It must not introduce new Notice Board features beyond the Phase 17 charter. The key closeout requirement is that the temporary Notice Board ongoing-project thread is no longer needed. The phase PRD already absorbs that charter, and this session should prove that no source evidence, requirements, acceptance checks, privacy boundary, route list, command list, or session split details remain exclusive to the former note. *** ## 2. Objectives 1. Update stable Notice Board documentation across API, server, web, CLI, hooks, War Room, architecture, and privacy docs. 2. Validate canonical and compatibility Notice Board behavior end to end with real-mode local server evidence and focused package tests. 3. Record security and privacy closeout evidence proving Notice Board payloads remain explicit coordination messages, not raw event logs. 4. Produce phase handoff evidence showing the former ongoing-project Notice Board note can stay removed or archived without losing durable project knowledge. *** ## 3. Prerequisites ### Required Sessions * [x] `phase17-session01-protocol-notice-contract-parity` - provides canonical Notice Board types, aliases, validators, REST contracts, and event contracts. * [x] `phase17-session02-server-notice-manager-persistence-and-context` - provides persistence, room filtering, context lookup, targeting, pruning, expiration, resolution, and automatic-post dedupe. * [x] `phase17-session03-server-routes-and-websocket-parity` - provides canonical REST routes, compatibility routes, WebSocket hydrate/message/resolve events, and `post_notice` compatibility handling. * [x] `phase17-session04-web-store-and-cockpit-notice-board` - provides web store normalization, cockpit rendering, target visibility, resolve handling, and empty/offline/disconnected states. * [x] `phase17-session05-cli-notice-commands` - provides `factionos notice` post, list, filtered list, context, and resolve commands. * [x] `phase17-session06-hook-context-and-provider-skill-parity` - provides bounded prompt-start Notice Board context lookup and provider-specific output behavior. * [x] `phase17-session07-war-room-worker-relay-and-catchup` - provides Worker notice relay, resolution relay, and bounded catch-up contracts. * [x] `phase17-session08-local-war-room-bridge-and-room-notice-convergence` - provides local-to-Worker relay, remote ingest, catch-up hydration, and room notice conversion. * [x] `phase17-session09-automatic-mission-lifecycle-posts` - provides automatic `status` and `completion` notices for real mission lifecycle paths. ### Required Tools/Knowledge * Node 26.2.0 or newer with npm 11.16.0. * Existing npm workspace scripts, root Vitest config, and package test files. * Local server route, WebSocket, CLI, hook, Worker, and web Notice Board behavior from Sessions 01 through 09. * Stable docs routing from `docs/README_docs.md`, package README files, and `docs/api/README_api.md`. ### Environment Requirements * Work from the repository root. * Use package-relative monorepo paths from the repo root. * Keep all generated and edited files ASCII-only with Unix LF line endings. * Manual validation must use temporary `FACTIONOS_HOME` state and `FACTIONOS_MOCK=false`; no Cloudflare credentials, hosted identity, hosted storage, analytics, public replay, remote execution, Docker execution, or trusted erasure environment is required. *** ## 4. Scope ### In Scope (MVP) * Stable docs describe Notice Board purpose as explicit coordination, not an automatic raw event log. * Stable docs document the privacy boundary: notice messages may be shared, but raw prompts, transcripts, terminal output, file contents, secrets, commands, absolute paths, logs, exports, replay buffers, scans, media drafts, diagnostics, backups, and quarantined historical content must not be shared. * API docs document canonical routes: `GET /notice-board`, `GET /notice-board/context`, `POST /notice-board`, and `POST /notice-board/:id/resolve`. * API docs document compatibility routes: `GET /notices` and `POST /notice`. * CLI docs document `factionos notice post `, `factionos notice list`, `factionos notice list --type `, `factionos notice resolve `, and `factionos notice context --session `. * Hook docs document bounded context lookup, provider-specific output behavior, safe empty context behavior, and failure-to-no-context behavior. * War Room docs document notice relay, resolution relay, catch-up, room notice conversion, and optional external transfer limits. * Web docs document cockpit Notice Board hydrate/message/resolve behavior, targeting, empty/error/offline/disconnected states, and convergence with War Room room notices. * Validation proves `FACTIONOS_MOCK=false` manual post, hydrate, resolve, targeting, persistence, War Room catch-up, room notice conversion, automatic `status`, and automatic `completion` behavior. * Validation proves persisted notices survive server restart under `FACTIONOS_HOME`. * Validation proves non-critical stale notices prune and critical notices remain. * Validation proves related files display only safe relative paths. * Validation proves `/notice`, `/notices`, and `post_notice` compatibility paths still work. * Validation proves `warroom_room_notice` input creates a sanitized `announcement` notice. * Validation proves no Notice Board path shares raw prompts, transcripts, terminal output, file contents, secrets, or absolute local paths. * Phase closeout artifacts record focused tests, broader gates, docs coverage, security posture, and ongoing-project note disposition. ### Out of Scope (Deferred) * New Notice Board features not recovered from `EXAMPLES/` - Reason: Phase 17 is a parity and closeout phase. * Hosted account identity, hosted storage, analytics capture, public replay, remote execution, Docker execution, or trusted unified erasure claims - Reason: these remain explicit no-claims in current security posture. * Formal mobile/accessibility certification - Reason: this session validates Notice Board behavior and docs, not formal certification. * Live Cloudflare deploy or production-hosted smoke - Reason: Worker relay validation can use focused tests and local evidence without credentials. *** ## 5. Technical Approach ### Architecture Treat this session as a docs and evidence closeout over the already-implemented cross-package Notice Board runtime. First build a coverage matrix from the Phase 17 PRD, Session 10 stub, completed session artifacts, stable docs, and source tests. Then update stable docs at the owning boundary rather than duplicating everything in one place: API contracts in `docs/api/README_api.md`, server behavior in `apps/server/README_server.md`, cockpit behavior in `apps/web/README_web.md`, CLI behavior in `apps/cli/README_cli.md`, hook behavior in `apps/hooks/README_hooks.md`, Worker relay behavior in `apps/warroom/README_warroom.md`, and cross-cutting privacy or architecture claims in `docs/privacy-and-security.md`, `docs/ARCHITECTURE.md`, and `docs/README_docs.md`. Validation should combine real-mode local exercises with focused tests that already own detailed behavior. The manual evidence should use a temporary `FACTIONOS_HOME`, `FACTIONOS_MOCK=false`, HTTP requests, CLI commands where practical, and WebSocket hydration checks where practical. Focused Vitest runs should cover protocol contracts, server manager/routes/WebSocket/bridge/event ingest, web store/component convergence, CLI notice commands, hook context, and Worker relay. All evidence must be summarized without copying raw prompts, command bodies, terminal output, file contents, tokens, broad absolute paths, local logs, exports, replay buffers, scans, diagnostics, backups, or quarantined historical material. Record command names, statuses, counts, safe notice ids, safe relative paths, and blocker notes only. ### Design Patterns * Stable docs as contract: update the docs that future users and agents read first, and leave archived PRDs as traceability evidence only. * Evidence matrix: map each Phase 17 acceptance check to docs coverage, focused tests, manual validation, or recorded blocker. * Claim-scoped closeout: record what was validated locally and avoid upgrading hosted, production, certification, or trusted-erasure claims. * Boundary-owned documentation: keep API, server, web, CLI, hook, Worker, architecture, and privacy language near the owning surface. * Redacted validation notes: record safe summaries, not raw payload dumps. ### Technology Stack * Markdown stable docs and spec evidence. * Node 26.2.0+ and npm 11.16.0 workspaces. * TypeScript packages: `packages/protocol`, `apps/server`, `apps/web`, `apps/warroom`. * JavaScript packages: `apps/cli`, `apps/hooks`. * Vitest for focused package tests. * Local Express and WebSocket server for real-mode validation. * No new runtime dependencies. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase17-session10-validation-documentation-and-handoff/phase17-validation-record.md` | Acceptance matrix and validation evidence for canonical routes, compatibility paths, CLI, hooks, War Room relay, persistence, pruning, related-file safety, automatic posts, focused tests, and broad gates | \~260 | | `.spec_system/specs/phase17-session10-validation-documentation-and-handoff/phase17-docs-handoff.md` | Stable docs inventory, updated-doc coverage matrix, former ongoing-project note disposition, and phase handoff notes | \~180 | | `.spec_system/specs/phase17-session10-validation-documentation-and-handoff/security-compliance.md` | Session security and GDPR posture for Notice Board documentation and validation closeout | \~160 | ### Files to Modify | File | Changes | Est. Lines | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `docs/api/README_api.md` | Add canonical Notice Board route family, context query behavior, resolve route, WebSocket event notes, and compatibility route wording | \~90 | | `apps/server/README_server.md` | Add server Notice Board manager, persistence, room scoping, pruning, context, canonical route, compatibility, and automatic post behavior | \~100 | | `apps/web/README_web.md` | Add cockpit Notice Board hydrate/message/resolve, targeting, empty/offline/disconnected states, and room-notice convergence notes | \~70 | | `apps/cli/README_cli.md` | Verify and refine Notice Board command, auth, output, and privacy wording | \~40 | | `apps/hooks/README_hooks.md` | Verify and refine bounded context lookup, provider output, empty context, and failure behavior | \~40 | | `apps/warroom/README_warroom.md` | Verify and refine relay, resolution, catch-up, room notice conversion, and optional transfer boundary wording | \~50 | | `docs/privacy-and-security.md` | Clarify Notice Board data inventory, allowed coordination data, blocked payload categories, and transfer boundary | \~70 | | `docs/ARCHITECTURE.md` | Add Notice Board runtime flow, storage, and Worker relay architecture summary | \~80 | | `docs/README_docs.md` | Route future Notice Board readers to current stable docs and note the former ongoing-project file disposition | \~50 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Stable docs fully describe the implemented Notice Board system and its owning packages. * [ ] Canonical REST routes and compatibility routes are documented with inputs, outputs, filters, and privacy boundaries. * [ ] WebSocket hydrate/message/resolve and client `post_notice` compatibility are documented. * [ ] CLI commands and hook context behavior are documented with bounded failure behavior. * [ ] War Room relay, resolution relay, catch-up, and room notice conversion are documented as optional external transfer for safe coordination notices only. * [ ] Manual real-mode evidence proves post, list, context, resolve, targeting, persistence after restart, pruning, related-file safety, compatibility, room-notice conversion, automatic status, automatic completion, and sensitive payload exclusion. * [ ] Focused tests cover protocol, server, web, CLI, hooks, and Worker Notice Board behavior. * [ ] The former ongoing-project Notice Board note can remain absent or archived without losing source evidence, requirements, acceptance checks, route lists, command lists, privacy boundaries, or session split details. ### Testing Requirements * [ ] Focused protocol tests pass. * [ ] Focused server Notice Board, WebSocket, bridge, route, and lifecycle tests pass. * [ ] Focused web Notice Board and War Room convergence tests pass. * [ ] Focused CLI and hook Notice Board tests pass. * [ ] Focused Worker Notice Board relay tests pass. * [ ] Root format, lint, typecheck, and test gates pass or blockers are recorded with precise scope. * [ ] Manual validation evidence is recorded without raw sensitive payloads. ### Non-Functional Requirements * [ ] Documentation avoids hosted identity, hosted storage, analytics, public replay, remote execution, Docker execution, production auditability, formal certification, or trusted erasure overclaims. * [ ] Evidence records only safe summaries, counts, statuses, relative paths, and sanitized ids. * [ ] All edited and created files are ASCII-only with Unix LF endings. * [ ] The session remains within 24 tasks and a 3-4 hour implementation window. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Markdown follows existing docs style. * [ ] Code follows project conventions if any validation helper edits become necessary. * [ ] No new runtime dependencies. *** ## 8. Implementation Notes ### Key Considerations * The analyzer selected Session 10 because Phase 17 has sessions 1-9 completed and this is the only unfinished candidate. * This is a cross-package session; do not force a single package path. * The current `docs/ongoing-projects/notice-board-coordination-recovery.md` file is already absent. The handoff should verify that absence remains safe because Phase 17 PRD/session artifacts and stable docs now own the content. * `docs/api/README_api.md` currently lists legacy `/notice` and `/notices` entries but needs canonical `/notice-board` coverage. * Prefer existing tests over adding new test harness code unless a validation gap is found during implementation. ### Potential Challenges * Manual server validation can be slow or port-sensitive: use a temporary port, temporary `FACTIONOS_HOME`, and record blockers if an existing process owns the default port. * Pruning behavior depends on timers and thresholds: prefer focused tests for exact pruning evidence and use manual evidence only for persisted restart behavior when faster. * WebSocket hydration evidence can be noisy: record safe event type counts and accepted ids rather than raw frames. * Broad root gates may uncover unrelated failures: record precise blockers and avoid changing unrelated code during a docs closeout unless required to make the phase truthful. ### Relevant Considerations * \[P03] **Stable docs are the current contract**: This session updates stable docs and treats archived PRDs and `EXAMPLES/` as traceability only. * \[P07] **Redaction is boundary-specific**: Notice Board docs and evidence must restate blocked payload categories at API, CLI, hook, web, Worker, and privacy boundaries. * \[P03-apps/server] **Local server boundary must stay conservative**: Route docs and validation must preserve local auth, CORS, WS origin, validation, rate limit, and body-size assumptions. * \[P06-apps/warroom+apps/web] **War Room federation is optional and redacted**: Relay docs must not imply hosted identity, public collaboration safety, production auditability, certification, or trusted erasure. * \[P08] **Release evidence is claim-scoped**: Local Notice Board validation is not production-hosted validation or formal certification. ### Behavioral Quality Focus Checklist active: No This session is documentation and validation closeout. It should not add new application behavior. If implementation discovers a product defect, record it as a blocker unless it is narrow, required for truthful closeout, and safe to fix inside this session. *** ## 9. Testing Strategy ### Unit Tests * Run focused protocol tests for Notice Board contracts, REST types, and Worker relay frame validation. * Run focused server tests for manager persistence/pruning, canonical routes, WebSocket hydrate/message/resolve, War Room bridge, event ingest, and mission lifecycle automatic posts. * Run focused web tests for Notice Board normalization, component behavior, and War Room convergence. * Run focused CLI and hook tests for notice commands and prompt context. * Run focused Worker tests for Notice Board relay and catch-up. ### Integration Tests * Use temporary local server state with `FACTIONOS_MOCK=false` to validate manual post, list, context, resolve, targeting, persistence after restart, related-file safety, compatibility routes, `post_notice`, room notice conversion, automatic status, automatic completion, and sensitive payload exclusion. * Run root quality gates appropriate for final phase validation: `npm run format:check`, `npm run lint`, `npm run typecheck --workspaces --if-present`, and `npm test`. ### Manual Testing * Start the local server on a temporary loopback port with a temporary `FACTIONOS_HOME`. * Exercise canonical and compatibility Notice Board HTTP paths with safe sample messages. * Connect a WebSocket client to verify hydrate/message/resolve event types and counts without recording raw payload dumps. * Exercise CLI notice commands against the temporary server where practical. * Record all evidence in `phase17-validation-record.md`. ### Edge Cases * Empty board, targeted board, include-resolved board, and resolved-only visibility. * Invalid type, invalid filters, unsafe related files, overly long content, and unsupported payload shapes. * Server restart with persisted notices. * Stale non-critical notices and critical notice retention. * Disconnected Worker relay and local-only fallback. * Missing session id or unreachable server for hook context. * Sensitive payload markers, token-like strings, absolute paths, command bodies, transcripts, and file contents. *** ## 10. Dependencies ### External Libraries * None new. ### Other Sessions * **Depends on**: Sessions 01-09 of Phase 17. * **Depended by**: `implement`, `validate`, `updateprd`, then Phase 17 transition work (`audit`, `pipeline`, `infra`, `carryforward`, `documents`). *** ## 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/phase17-session10-validation-documentation-and-handoff/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.