> 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/phases/phase_01/prd_phase_01.md). # PRD Phase 01: Core Runtime Hardening **Status**: Complete **Sessions**: 7 **Estimated Duration**: 7-14 days **Progress**: 7/7 sessions (100%) *** ## Overview Phase 01 hardens the local runtime foundation before broader product-surface work begins. It reconciles the current hook, CLI, REST, WebSocket, protocol, archive, export, and LLM behavior against the recovered original contract in `EXAMPLES/`, then turns that reconciliation into tested current source and stable documentation. This phase does not chase historical parity blindly. Each session must preserve the local-first boundary, keep optional services optional, and convert direct `EXAMPLES/` evidence into current implementation, tests, and docs. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | ---------------------------------------------- | -------- | ---------- | ---------------- | | 01 | Event Ingest Contract Reconciliation | Complete | \~18-22 | 2026-05-29 04:32 | | 02 | Hook Runtime Safety | Complete | \~16-20 | 2026-05-29 | | 03 | CLI Lifecycle Parity | Complete | \~16-22 | 2026-05-29 04:24 | | 04 | Server Routes and Authorization Boundaries | Complete | \~18-24 | 2026-05-29 | | 05 | WebSocket Hydration and Archive Export Privacy | Complete | \~18-24 | 2026-05-29 | | 06 | LLM Fallback and Scan Privacy | Complete | \~16-22 | 2026-05-29 | | 07 | Runtime Contract Documentation | Complete | \~12-18 | 2026-05-29 | *** ## Completed Sessions 1. Event Ingest Contract Reconciliation - 2026-05-29 2. Hook Runtime Safety - 2026-05-29 3. CLI Lifecycle Parity - 2026-05-29 4. Server Routes and Authorization Boundaries - 2026-05-29 5. WebSocket Hydration and Archive Export Privacy - 2026-05-29 6. LLM Fallback and Scan Privacy - 2026-05-29 7. Runtime Contract Documentation - 2026-05-29 *** ## Upcoming Sessions None. Phase 01 session work is complete. *** ## Objectives 1. Tighten hook, CLI, server, protocol, archive, export, and LLM fallback behavior. 2. Close gaps between documented event compatibility and implemented event ingest. 3. Strengthen tests around setup, hook safety, server routes, WebSocket hydration, and local storage. 4. Maintain reproducible npm workspace behavior and current package-lock discipline. 5. Establish stable docs that replace `EXAMPLES/` inventories as the implemented API and event contract. *** ## Prerequisites * Phase 00 completed. * `EXAMPLES/` remains available locally as ignored source-intake evidence. * `docs/api/event-api-hook-contracts.md` remains the current contract baseline. * Existing user changes in docs and `.spec_system/` are preserved. *** ## Technical Considerations ### Architecture Protocol changes lead cross-package runtime work. Server, hooks, CLI, web, and docs should follow typed contract updates instead of duplicating event shapes. Runtime behavior must continue to degrade cleanly without API keys, adapters, Cloudflare credentials, hosted services, or non-loopback exposure. ### Technologies * npm workspaces with Node 20 or newer * Express 4 and `ws` in `apps/server` * dependency-light Node hook handlers in `apps/hooks` * Node built-ins in `apps/cli` * TypeScript protocol contracts in `packages/protocol` * Vitest and existing workspace test projects * Biome format and lint commands ### Risks * Historical source drift: compare direct `EXAMPLES/` files to current source before implementation. * Prompt and path privacy: add redaction and transfer boundaries before expanding exports or sharing. * Hook latency: keep hook handlers silent and fast when the server is unavailable. * Route parity confusion: unsupported historical routes must fail clearly instead of implying support. * Cross-package churn: split changes by protocol, server, hooks, CLI, web, and docs ownership. ### Relevant Considerations * \[P00] **Historical artifacts quarantined**: keep `EXAMPLES/` as evidence, not shippable runtime content. * \[P00-apps/hooks+apps/cli] **Atomic-write gap**: audit user-owned settings writes during CLI and hook hardening. * \[P00-apps/server] **Scanner ignore posture**: keep scans focused on current source unless explicitly inventorying old artifacts. * \[P00] **Prompt and path privacy**: test redaction before broader export, replay, adapter, or hosted flows. * \[P00-apps/server+packages/protocol] **Typed surface exceeds implementation**: preserve clear unsupported behavior and prioritize workflow value. * \[P00] **Local-first boundary**: optional services must not become prerequisites. * \[P00-packages/protocol] **Protocol leads cross-package work**: update shared event and domain types before wiring runtime behavior. *** ## EXAMPLES Implementation Sources | Source | Required Feature Scope | Completion Tests | Stable Documentation Owner | | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `EXAMPLES/findings/api-routes.txt` | REST route inventory, unsupported-route decisions, capability responses, route parity gaps | Server route tests for shipped, hardened, and explicit 501 behavior | `docs/api/README_api.md`, `docs/api/event-api-hook-contracts.md`, `apps/server/README_server.md` | | `EXAMPLES/findings/websocket-events.txt` | WebSocket event inventory, hydration, client messages, lifecycle fanout, replay/export implications | WebSocket hydration, client-message, fanout, and event-shape tests | `docs/api/event-api-hook-contracts.md`, `packages/protocol/README_protocol.md` | | `EXAMPLES/findings/claude-hook-contract.md` | Claude hook names, payload expectations, failure behavior, prompt/tool/permission mapping | Hook fixture tests and `/event` ingest tests for supported hooks and opaque fallback | `apps/hooks/README_hooks.md`, `docs/api/event-api-hook-contracts.md` | | `EXAMPLES/findings/architecture.md` | Historical runtime module map, plugin layer, LLM engines, listener model, and current-source deltas | Phase validation checklist confirming retained runtime modules are implemented, deferred, or explicitly out of phase | `docs/ARCHITECTURE.md`, `docs/api/event-api-hook-contracts.md` | | `EXAMPLES/findings/BUILD_LINKS.md` | Traceability from findings to current implementation surfaces | Contract coverage checklist in session validation | `docs/legacy-consolidation.md`, `docs/api/event-api-hook-contracts.md` | | `EXAMPLES/findings/llm-prompts/` | Original LLM planning, analysis, idle suggestion, transcript mining, and auto-improvement prompt behavior | LLM route tests for deterministic fallback, bounded inputs, and provider-transfer boundaries | `apps/server/README_server.md`, `docs/privacy-and-security.md` | | `EXAMPLES/1st-pass-artifacts/agent-templates.json` | Original agent-template affordances that influence LLM planning and later orchestration scope | Documentation or tests that mark templates as deferred when not implemented in Phase 01 | `docs/legacy-consolidation.md`, `docs/api/event-api-hook-contracts.md` | | `EXAMPLES/1st-pass-artifacts/hooks-config.json` | Original hook registration map and install expectations | CLI installer and uninstall tests for managed hook entries | `apps/hooks/README_hooks.md`, `apps/cli/README_cli.md` | | `EXAMPLES/1st-pass-artifacts/hooks-bundle/` | Original hook handlers, listener helpers, payload builders, and guard behavior | Hook script unit or fixture tests for latency, silence, diagnostics, and payload shape | `apps/hooks/README_hooks.md` | | `EXAMPLES/1st-pass-artifacts/openclaw-SKILL.md` | Non-Claude event cookbook and type-based event compatibility | `/event` compatibility tests for type-only or adapted payloads | `docs/api/event-api-hook-contracts.md`, `docs/api/README_api.md` | | `EXAMPLES/1st-pass-artifacts/ws-listener.js` | Listener bridge behavior for terminal or hook relay flows | Listener lifecycle and failure-mode tests | `apps/hooks/README_hooks.md`, `apps/cli/README_cli.md` | | `EXAMPLES/1st-pass-artifacts/spawn-listeners.sh` | Original process scan and listener spawn helper behavior | Listener spawn tests or explicit current-source disposition for retained or rejected scan behavior | `apps/hooks/README_hooks.md`, `apps/cli/README_cli.md` | | `EXAMPLES/1st-pass-artifacts/bundled-README.md` | Original CLI and local launch affordances | CLI command tests for init, status, doctor, open, stop, uninstall, port, and workspace behavior | `README.md`, `apps/cli/README_cli.md` | | `EXAMPLES/1st-pass-artifacts/bundled-package.json` | Original package bin, files, scripts, dependency, and Node engine expectations | Package metadata checks and docs for current workspace equivalents | `README.md`, `apps/cli/README_cli.md` | | `EXAMPLES/package-0.4.1/bin/agentcraft.js` | Original executable entry behavior and command dispatch | CLI bin smoke tests and package manifest checks | `apps/cli/README_cli.md`, `README.md` | | `EXAMPLES/package-0.4.1/lib/cli.js` | Original CLI command surface and user-facing command semantics | CLI command integration tests with mocked process and filesystem | `apps/cli/README_cli.md` | | `EXAMPLES/package-0.4.1/lib/installer.js` | Original hook installer, backup, merge, and uninstall behavior | Filesystem fixture tests for install, backup, merge, uninstall, and atomic writes | `apps/cli/README_cli.md`, `apps/hooks/README_hooks.md` | | `EXAMPLES/package-0.4.1/lib/launcher.js` | Original local launch, daemon, browser open, PID, port, and workspace behavior | Launcher tests for process state, port handling, PID files, and status output | `apps/cli/README_cli.md`, `README.md` | | `EXAMPLES/package-0.4.1/lib/config.js` | Original local config directory, auth token, PID, server env, and project-dir persistence behavior | Config fixture tests for atomic writes, secret handling, PID lifecycle, and workspace recording | `apps/cli/README_cli.md`, `docs/privacy-and-security.md` | *** ## Success Criteria Phase complete when: * [x] All 7 sessions completed. * [x] Session 02 validated and marked complete. * [x] Hook ingest accepts documented current payloads and handles historical compatibility paths deliberately. * [x] CLI setup and lifecycle commands are tested against current workspace behavior. * [x] Server routes, WebSocket hydration, exports, archive behavior, and unsupported routes have focused tests. * [x] LLM fallback and scan routes preserve local-first privacy boundaries and deterministic no-key behavior. * [x] Stable docs identify shipped, stubbed, planned, unsupported, and obsolete API/event behavior without relying on `EXAMPLES/` as user docs. *** ## Dependencies ### Depends On * Phase 00: Source of Truth and Cleanup Plan ### Enables * Phase 02: Product Surface and 2D Battlefield Completion --- # 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/phases/phase_01/prd_phase_01.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.