> 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/phase01-session07-runtime-contract-documentation/spec.md). # Session Specification **Session ID**: `phase01-session07-runtime-contract-documentation` **Phase**: 01 - Core Runtime Hardening **Status**: Completed **Created**: 2026-05-29 **Package**: Cross-package documentation (`docs`, `README.md`, package READMEs) **Package Stack**: Markdown, npm workspace documentation *** ## 1. Session Overview This session closes Phase 01 by making stable documentation match the runtime contracts hardened in Sessions 01 through 06. The implementation sessions updated API, hook, CLI, route, WebSocket, export, archive, and LLM behavior; the remaining work is to remove stale "needs hardening" wording, align package READMEs, and capture source-intake traceability without sending users back to ignored `EXAMPLES/` files as product guidance. The session is intentionally documentation-only. It does not delete historical artifacts, write Phase 02 specs, or change runtime code. Its output should give future phasebuild and manual audit work a clear map of what Phase 01 captured, what remains planned for later phases, and which stable documents own each runtime contract. *** ## 2. Objectives 1. Align stable docs with Phase 01 shipped, tested-shipped, stubbed, planned, unsupported, and obsolete runtime behavior. 2. Update CLI, hooks, server, and protocol package README references to the final Phase 01 contract. 3. Record Phase 01 traceability from direct `EXAMPLES/` sources into stable docs. 4. Preserve a concise remaining-gap list for Phase 02 and later phasebuild runs. *** ## 3. Prerequisites ### Required Sessions * [x] `phase01-session01-event-ingest-contract-reconciliation` - event and source-intake traceability baseline. * [x] `phase01-session02-hook-runtime-safety` - hook runtime and listener safety baseline. * [x] `phase01-session03-cli-lifecycle-parity` - CLI lifecycle and local state behavior. * [x] `phase01-session04-server-routes-and-authorization-boundaries` - route auth, validation, and unsupported route boundaries. * [x] `phase01-session05-websocket-hydration-and-archive-export-privacy` - WebSocket, replay, archive, and export privacy behavior. * [x] `phase01-session06-llm-fallback-and-scan-privacy` - LLM fallback, scan, provider-transfer, and memory privacy behavior. ### Required Tools/Knowledge * Current Phase 01 session validation and implementation summaries. * Stable docs in `docs/`, root `README.md`, and package READMEs. * Current npm workspace version and release gate docs. ### Environment Requirements * No hosted service, API key, Cloudflare credential, or local dev server is required. * Documentation output must be ASCII and LF. *** ## 4. Scope ### In Scope (MVP) * Stable docs describe current runtime behavior without directing users to `EXAMPLES/`. * Runtime contracts classify behavior as shipped, tested-shipped, stubbed, planned, unsupported, obsolete, or separate-surface where needed. * Package READMEs for CLI, hooks, server, and protocol point to the final Phase 01 source-backed contract. * `docs/legacy-consolidation.md` records Phase 01 session outcomes, source-intake coverage, and remaining dependencies for later phases. * `docs/ARCHITECTURE.md`, `docs/development.md`, `docs/privacy-and-security.md`, and `docs/release.md` reflect the hardened runtime boundaries. * Root `README.md` no longer lists Phase 01-completed hardening as an open gap. ### Out of Scope (Deferred) * Deleting `EXAMPLES/` or `docs/PROGRESS.md` - Reason: Phase 08 owns release cleanup gates. * Creating Phase 02 implementation specs - Reason: phasebuild runs after documents/manual audit/carryforward sequence. * Adding new runtime behavior or tests beyond docs checks - Reason: Sessions 01-06 own runtime code. * Writing new product-surface UI docs beyond runtime contract updates - Reason: Phase 02 owns product surface. *** ## 5. Technical Approach ### Architecture Stable docs remain layered: concise behavior in root/package READMEs, current runtime reference in `docs/api/README_api.md`, detailed source-backed contract in `docs/api/event-api-hook-contracts.md`, architecture and boundary posture in `docs/ARCHITECTURE.md`, privacy posture in `docs/privacy-and-security.md`, and source-intake disposition in `docs/legacy-consolidation.md`. ### Design Patterns * Documentation as contract: describe only current behavior or explicitly marked future work. * Traceability without raw intake: name `EXAMPLES/` source paths, but preserve conclusions and gaps instead of copying long historical content. * Status vocabulary reuse: keep shipped/tested/stubbed/planned/unsupported language consistent. * Release gate alignment: update known gaps and decommission gates without granting deletion approval. ### Technology Stack * Markdown stable docs. * npm workspace docs and README conventions. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | --------------------------------------------------------------------------------------------- | -------------------------------------------------- | ---------- | | `.spec_system/specs/phase01-session07-runtime-contract-documentation/implementation-notes.md` | Session documentation log and verification record. | \~180 | ### Files to Modify | File | Changes | Est. Lines | | -------------------------------------- | ------------------------------------------------------------------------------- | ---------- | | `README.md` | Update current shipped capabilities and known gaps after Phase 01. | \~40 | | `apps/cli/README_cli.md` | Confirm final CLI lifecycle, local state, and unsupported integration boundary. | \~30 | | `apps/hooks/README_hooks.md` | Confirm final hook/listener contract and safety behavior. | \~30 | | `apps/server/README_server.md` | Confirm final route, WebSocket, export/archive, and LLM privacy behavior. | \~40 | | `packages/protocol/README_protocol.md` | Confirm event/client-message ownership and Phase 01 coverage. | \~30 | | `docs/api/README_api.md` | Final concise runtime API contract pass. | \~60 | | `docs/api/event-api-hook-contracts.md` | Final detailed runtime contract pass and hardening-gap cleanup. | \~100 | | `docs/ARCHITECTURE.md` | Update optional services, security boundaries, and current gaps. | \~70 | | `docs/development.md` | Update local state, env vars, and verification guidance. | \~40 | | `docs/privacy-and-security.md` | Align controls and open risks with final Phase 01 posture. | \~40 | | `docs/legacy-consolidation.md` | Add Phase 01 source-intake traceability and remaining dependencies. | \~140 | | `docs/release.md` | Update release gates and decommission checks after Phase 01. | \~50 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Stable docs describe current runtime behavior without directing users to `EXAMPLES/`. * [ ] Docs classify behavior as shipped, tested-shipped, stubbed, planned, unsupported, obsolete, or separate-surface where needed. * [ ] Every Phase 01 session has traceability from direct `EXAMPLES/` sources to current source, tests, and docs. * [ ] Remaining gaps are specific enough for Phase 02 and later phasebuild runs. ### Testing Requirements * [ ] Documentation grep checks find no stale Phase 01 "needs hardening" claims for completed runtime boundaries. * [ ] Markdown link/path spot checks pass for touched docs. * [ ] ASCII, LF, and `git diff --check` pass. * [ ] Practical repo gates from Session 06 remain valid or focused docs checks explain why rerunning full runtime tests is unnecessary. ### Non-Functional Requirements * [ ] No raw tokens, OAuth IDs, probe outputs, prompt bodies, or sensitive local paths are copied into docs. * [ ] No historical feature is described as shipped unless current source and tests support it. * [ ] No Phase 02 product-surface scope is promoted into Phase 01 docs as current behavior. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Markdown follows project README naming and source-of-truth conventions. *** ## 8. Implementation Notes ### Key Considerations * Root README currently still says route-specific authorization, schema validation, export redaction, and retention controls remain open; some of those were completed in Phase 01 and need updating. * `docs/ARCHITECTURE.md` still describes Anthropic as used only when `ANTHROPIC_API_KEY` is set; Session 06 added a second transfer opt-in. * `docs/legacy-consolidation.md` has older "Session 04/05 were planning stubs" language that now conflicts with Phase 01 implementation sessions. * Do not delete historical artifacts; capture the disposition and leave release cleanup for Phase 08. ### Potential Challenges * Avoid over-documenting the same route inventory in multiple docs; link to canonical API contract where possible. * Preserve future scope for War Room, orchestration, media, hosted analytics, and release cleanup without implying they are shipped. * Keep all docs ASCII while touching files that may have older punctuation. ### Relevant Considerations * \[P00] **Historical artifacts quarantined**: preserve conclusions and source paths, not long copied excerpts. * \[P00] **PRD is authoritative**: keep PRD/UX PRD as future-scope authority and stable docs as current behavior. * \[P00] **Docs cleanup is phased work**: update everyday docs now; leave deletion gates to release hardening. * \[P00] **Do not chase historical parity blindly**: classify source-intake gaps instead of pretending all historical behavior is present. * \[P00] **Local-first boundary**: optional services must stay optional in docs. *** ## 9. Testing Strategy ### Unit Tests * N/A - documentation-only session. ### Integration Tests * N/A - runtime behavior was validated in Sessions 01-06 and full gates passed in Session 06. ### Manual Testing * Review touched docs for stale Phase 01 hardening claims, unsupported-as-shipped wording, and raw historical sensitive values. * Run grep checks for `needs-hardening`, `ANTHROPIC_API_KEY`, `route-specific authorization`, `export redaction`, `EXAMPLES/`, and stale Session 04/05 wording. ### Edge Cases * Historical source paths should remain traceability references, not user instructions. * War Room Worker backend is shipped as optional backend, but web panel federation remains planned. * LLM provider transfer requires two env conditions, not key-only. *** ## 10. Dependencies ### External Libraries * None added. ### Other Sessions * **Depends on**: Phase 01 Sessions 01-06. * **Depended by**: Phase transition audit, pipeline, infra, carryforward, documents, manual audit, and Phase 02 phasebuild. *** ## 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/phase01-session07-runtime-contract-documentation/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.