> 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-session05-cli-notice-commands/spec.md). # Session Specification **Session ID**: `phase17-session05-cli-notice-commands` **Phase**: 17 - Notice Board Coordination Parity **Status**: Completed **Created**: 2026-06-05 **Package**: apps/cli **Package Stack**: JavaScript *** ## 1. Session Overview This session adds first-party `factionos notice` commands to the JavaScript CLI so local agents can post, list, resolve, and read bounded Notice Board context without relying on quarantined historical skill scripts. Sessions 01 through 03 restored the Notice Board protocol, persistence, canonical REST routes, and WebSocket events. Session 04 made the cockpit consume those events, so CLI posts can now become visible coordination messages in the running local app. The work is intentionally narrow: add a `notice` command group, route it through the existing CLI dispatcher, implement a small Notice Board HTTP client, format compact terminal output, and cover the behavior with fake server tests. The CLI must use `FACTIONOS_SERVER_URL` with the default loopback fallback, pass `FACTIONOS_AUTH_TOKEN` only as an authorization header when configured, derive session and author identity from safe local settings or environment values, and print clear user-facing errors for invalid input or server failures. Notice Board messages are explicit coordination updates, not raw telemetry. The CLI must not log or print raw tokens, prompts, command bodies, terminal output, file contents, absolute paths, diagnostics, backups, or quarantined historical material while implementing these command paths. *** ## 2. Objectives 1. Add `factionos notice` command dispatch and help text to the existing CLI entry point. 2. Implement post, list, type-filtered list, resolve, and context commands against the canonical `/notice-board` route family. 3. Resolve server URL, auth token, session id, and author display name using current CLI conventions and privacy-safe fallbacks. 4. Add focused CLI tests for command success paths, output formatting, auth headers, empty board behavior, and failure handling. *** ## 3. Prerequisites ### Required Sessions * [x] `phase17-session01-protocol-notice-contract-parity` - provides the recovered Notice Board type, priority, author, target, related-file, and compatibility aliases. * [x] `phase17-session02-server-notice-manager-persistence-and-context` - provides persistent active-room storage, filtering, resolution, and bounded context lookup. * [x] `phase17-session03-server-routes-and-websocket-parity` - provides canonical `/notice-board`, `/notice-board/context`, and resolve routes plus auth-aware server boundaries. * [x] `phase17-session04-web-store-and-cockpit-notice-board` - provides the cockpit consumer that displays CLI-created notices in real mode. ### Required Tools/Knowledge * Node 26.2.0 or newer with npm workspaces. * JavaScript CLI command modules under `apps/cli/src/commands`. * Existing CLI local file helpers in `apps/cli/src/lib/localFiles.js`. * Existing CLI logging redaction in `apps/cli/src/lib/logging.js`. * Node HTTP/HTTPS request patterns and Vitest fake-server tests. ### 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. * Use fake HTTP servers in tests; do not require a live local FactionOS server. *** ## 4. Scope ### In Scope (MVP) * Agents can run `factionos notice post ` to create canonical Notice Board posts with `authorType: "agent"`. * Agents can run `factionos notice list` to fetch unresolved notices from `/notice-board?limit=20`. * Agents can run `factionos notice list --type ` with recovered notice type validation. * Agents can run `factionos notice resolve ` to call `/notice-board/:id/resolve`. * Agents can run `factionos notice context --session ` to fetch bounded `/notice-board/context` output. * CLI requests use `FACTIONOS_SERVER_URL` with fallback `http://localhost:2468`. * CLI requests include `Authorization: Bearer ` only when `FACTIONOS_AUTH_TOKEN` is configured. * CLI posts derive `authorSessionId` from `FACTIONOS_SESSION_ID`, provider session environment values, or `unknown`. * CLI posts derive `authorName` from configured local hero/session display settings where available, falling back to `Agent-`. * CLI list/context calls pass `forSession` or `sessionId` when a usable session id is available. * CLI output prints unresolved notices with timestamp, type, author, content, priority, and the first three related files. * Empty lists print `No active notices on the board.` * Errors are useful for invalid type, missing message, missing notice id, unreachable server, unauthorized server, and malformed responses. * Focused CLI tests cover post, list, type-filtered list, resolve, context, auth header, empty board, output formatting, and error output. ### Out of Scope (Deferred) * Hook output integration - Reason: Session 06 owns hook context and provider skill parity. * Server route implementation - Reason: Session 03 completed canonical routes. * Web UI rendering - Reason: Session 04 completed cockpit Notice Board rendering. * Worker relay implementation - Reason: Session 07 owns Worker relay and catch-up. * Local War Room bridge convergence - Reason: Session 08 owns local/remote room convergence. * Automatic mission lifecycle posts - Reason: Session 09 owns automatic status and completion posts. *** ## 5. Technical Approach ### Architecture Add `apps/cli/src/lib/noticeClient.js` as a small testable helper for Notice Board request construction, server URL resolution, auth headers, session and author metadata, JSON parsing, timeout handling, error mapping, and terminal formatting primitives. This keeps HTTP and privacy-sensitive formatting logic out of the command dispatcher. Add `apps/cli/src/commands/notice.js` with a `runNotice(flags)` entry point that reads positional arguments from `flags._`, validates the requested subcommand, invokes the helper, and prints compact terminal output. Wire this through `apps/cli/src/index.js` alongside the existing `status`, `doctor`, `erase`, and lifecycle commands. Tests should use a local fake HTTP server inside `apps/cli/tests` to verify request method, path, query string, body, and auth headers. The fake server also covers non-2xx, invalid JSON, unauthorized, unreachable, empty, and malformed response cases without requiring a live FactionOS runtime. ### Design Patterns * Command module per top-level CLI command: keep `notice` aligned with existing `apps/cli/src/commands` structure. * Small HTTP client helper: isolate network behavior, timeout handling, and malformed response mapping. * Compatibility-aware output formatter: accept canonical `messages` and compatibility `notices` shapes where useful. * Privacy-preserving diagnostics: print posture and concise error labels, not raw tokens, broad paths, URLs with credentials, request bodies, or stack traces. * Fake-server tests: prove HTTP contract behavior deterministically without live local services. ### Technology Stack * JavaScript ESM in `apps/cli`. * Node `http` and `https` modules for local and configured server requests. * Existing `apps/cli/src/lib/localFiles.js` helpers for local state and server URL fallback behavior. * Existing CLI logging redaction from `apps/cli/src/lib/logging.js`. * Vitest through the root workspace configuration. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | --------------------------------------- | ----------------------------------------------------------------------------- | ---------- | | `apps/cli/src/lib/noticeClient.js` | Notice Board HTTP client, metadata resolution, validation, and output helpers | \~260 | | `apps/cli/src/commands/notice.js` | `factionos notice` command group implementation | \~190 | | `apps/cli/tests/noticeCommands.test.js` | Fake-server CLI command coverage for success and failure paths | \~320 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------ | -------------------------------------------------------------------------------------- | ---------- | | `apps/cli/src/index.js` | Add notice command import, dispatch, help text, and examples | \~30 | | `apps/cli/README_cli.md` | Document notice commands, environment variables, output behavior, and privacy boundary | \~60 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `factionos notice post status "Working on X"` posts an agent notice to `POST /notice-board`. * [ ] `factionos notice list` calls `GET /notice-board?limit=20` and displays unresolved active notices. * [ ] `factionos notice list --type review` validates `review` and filters the list route by workflow type. * [ ] `factionos notice resolve ` posts to `/notice-board//resolve`. * [ ] `factionos notice context --session ` prints bounded Notice Board context from the context route. * [ ] Empty list responses print `No active notices on the board.` * [ ] Notice list output includes timestamp, type, author, content, priority, and up to three related files. * [ ] Requests use `FACTIONOS_AUTH_TOKEN` as a bearer header when configured. * [ ] Invalid type, missing message, missing notice id, unreachable server, unauthorized server, and malformed responses produce clear CLI errors. ### Testing Requirements * [ ] CLI command tests written and passing for post, list, type-filtered list, resolve, context, auth header, empty board, and error output. * [ ] Fake-server tests assert method, path, query string, request body, and authorization header. * [ ] Focused CLI tests run successfully. * [ ] ASCII and LF validation passes for new session files. ### Non-Functional Requirements * [ ] CLI output does not expose raw prompts, transcripts, terminal output, command bodies, file contents, secrets, absolute paths, logs, diagnostics, backups, or quarantined historical content. * [ ] Server failures and malformed responses are bounded and do not print raw response bodies that could contain sensitive data. * [ ] The command remains local-first and does not imply hosted identity, public collaboration safety, production auditability, trusted erasure, or real executor behavior. * [ ] Network calls have bounded timeouts and deterministic failure labels. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. *** ## 8. Implementation Notes ### Key Considerations * The CLI package is JavaScript ESM and currently dispatches top-level commands from `apps/cli/src/index.js`. * `parseFlags` already preserves positional arguments in `flags._`, which can carry the `notice` subcommand and its remaining arguments after dispatch. * The server route contract expects canonical posts to use `type` and `content`; compatibility `body` can be included only if useful for older shapes, but the canonical fields should lead. * The command should prefer fake-server tests over live runtime assumptions so the suite stays deterministic. ### Potential Challenges * Positional message parsing: Treat all remaining positional words after the notice type as the message to preserve quoted and unquoted usage. * Session identity availability: Fall back to `unknown` when no provider session id is available and keep author fallback deterministic. * Error body sensitivity: Map status codes and compact error labels without printing raw response payloads. * Auth header tests: Ensure token values appear only in captured request headers inside tests, not in user-facing output or logs. ### Relevant Considerations * \[P07] **Redaction is boundary-specific**: CLI request, output, error, and log paths need explicit minimization at this new boundary. * \[P03-apps/server] **Local server boundary must stay conservative**: Respect optional auth, request validation, bounded payloads, and unavailable states. * \[P03] **Do not log raw CLI args or local paths**: Notice command errors must avoid printing raw args, tokens, broad paths, URLs with credentials, or stack details. * \[P03] **Vitest projects**: Use focused CLI test runs before broader phase validation. * \[P03] **Stable docs are the current contract**: Document the supported CLI Notice Board behavior in package docs rather than depending on `EXAMPLES/`. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Duplicate or malformed state-mutating notice posts and resolves could create confusing coordination records. * Network, auth, timeout, and malformed response failures could be unclear or leak sensitive details. * Terminal output could accidentally expose raw tokens, broad local paths, or unsafe response payloads. *** ## 9. Testing Strategy ### Unit Tests * Test notice type validation, positional message parsing, session id fallback, author fallback, URL/query construction, and compact notice formatting. * Test empty board formatting and related-file truncation to three entries. ### Integration Tests * Use a fake HTTP server to verify `post`, `list`, `list --type`, `resolve`, `context`, auth header propagation, and malformed response handling. * Verify method, path, query string, and JSON body for each command. ### Manual Testing * With a local server running, run: * `factionos notice post status "Working on CLI notice commands"` * `factionos notice list` * `factionos notice list --type status` * `factionos notice context --session ` * `factionos notice resolve ` ### Edge Cases * Missing subcommand, invalid subcommand, invalid notice type, missing message, missing notice id, missing `--session`, empty board response, unauthorized server, unreachable server, timeout, invalid JSON, malformed success shape, notices without timestamps, notices without authors, and notices with more than three related files. *** ## 10. Dependencies ### External Libraries * No new runtime dependency is planned. ### Internal Dependencies * `apps/cli/src/lib/localFiles.js` for local FactionOS home and server URL fallback behavior. * `apps/cli/src/lib/logging.js` for redacted command-level error capture. * Canonical Notice Board server routes from Session 03. ### Other Sessions * **Depends on**: `phase17-session01-protocol-notice-contract-parity`, `phase17-session02-server-notice-manager-persistence-and-context`, `phase17-session03-server-routes-and-websocket-parity`, `phase17-session04-web-store-and-cockpit-notice-board` * **Depended by**: `phase17-session06-hook-context-and-provider-skill-parity`, `phase17-session10-validation-documentation-and-handoff` *** ## 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-session05-cli-notice-commands/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.