> 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/phase07-session07-hosted-guardrails-validation-and-documentation-closeout/spec.md). # Session Specification **Session ID**: `phase07-session07-hosted-guardrails-validation-and-documentation-closeout` **Phase**: 07 - Hosted Services and Analytics Guardrails **Status**: Not Started **Created**: 2026-05-30 **Package**: Cross-package (`packages/protocol`, `apps/server`, `apps/web`, `apps/warroom`, `apps/cli`, `apps/hooks`; docs, env examples, spec-system) **Package Stack**: TypeScript (protocol/server/web/warroom), JavaScript (cli/hooks), Markdown docs *** ## 1. Session Overview This session is the Phase 07 validation and documentation closeout. Sessions 01 through 06 turned the deferred hosted-service and analytics surfaces into source-backed guardrails: requirements and privacy baseline, hosted configuration and client exposure boundaries, hosted identity and authorization guardrails, hosted persistence and public replay boundaries, analytics consent and payload controls, and push/remote-access/operator-diagnostics guardrails. Each of those sessions is already locally validated. This session proves the guardrails hold together end to end, closes documentation and security-posture gaps, and records what remains deferred to Phase 08. The work is verification and documentation, not new feature code. It runs the focused protocol, server, web, Worker, CLI, browser, formatting, linting, typecheck, test, build, secret-scan, ASCII/LF, whitespace, and hosted-payload privacy checks relevant to Phase 07; confirms the disabled-default, local-only-fallback, public-versus-secret-config, hosted-identity wording, hosted-storage and public-replay disabled states, analytics consent/payload controls, push and remote-access unavailable states, and compact diagnostics all behave as documented; and confirms no Phase 07 surface leaks prompts, file contents, command bodies, terminal output, transcripts, tokens, broad paths, exports, replay buffers, scan payloads, media drafts, diagnostics, logs, backups, account ids, zone ids, tunnel tokens, or quarantined historical content. It then synchronizes the stable docs (master PRD, UX PRD, phase PRD, architecture, API, privacy/security, hosted-services, deployment, environments, release, package README files, and the security-compliance posture) with the shipped Phase 07 guardrails, and writes the validation evidence, security and compliance review, implementation summary, residual-risk record, and Phase 08 handoff notes for trusted erasure, production-hosted validation, release hardening, certification, and legacy decommission. Completing it marks Phase 07 complete and clears the path to Phase 08. *** ## 2. Objectives 1. Run and record the focused Phase 07 validation command set (protocol, server, web, Worker, CLI, browser, format, lint, typecheck, test, build, secret scan, ASCII/LF, whitespace, hosted-payload privacy) with retained evidence paths. 2. Confirm all 25 Phase 07 routing requirements (P07-R001 through P07-R025) are closed by a validated session or explicitly deferred to Phase 08, with no sensitive-payload leak across any Phase 07 surface. 3. Synchronize master PRD, UX PRD, phase PRD, architecture, API, privacy/security, hosted-services, deployment, environments, release, package README, and security-compliance docs with the shipped guardrails. 4. Record the Phase 07 security and compliance review, implementation summary, residual risks, and Phase 08 handoff notes for trusted erasure, production-hosted validation, release hardening, certification, and legacy decommission. *** ## 3. Prerequisites ### Required Sessions * [x] `phase07-session01-hosted-services-requirements-and-privacy-baseline` - requirements, privacy baseline, routing matrix, payload blocklist * [x] `phase07-session02-hosted-configuration-and-client-exposure-boundaries` - public/secret/deploy config boundaries and diagnostics * [x] `phase07-session03-hosted-identity-and-authorization-guardrails` - planned-state identity contracts and diagnostics * [x] `phase07-session04-hosted-persistence-and-public-replay-boundaries` - hosted storage and public replay disabled states * [x] `phase07-session05-analytics-consent-and-payload-controls` - disabled-default analytics, consent, payload scrubbing * [x] `phase07-session06-push-remote-access-and-operator-diagnostics-guardrails` - push/remote/tunnel/diagnostics guardrails ### Required Tools/Knowledge * npm workspace scripts (`format:check`, `lint`, `typecheck`, `test`, `build`, `security:secrets`) * Vitest focused runs, Biome, `tsc` package typechecks * ASCII/LF, whitespace (`git diff --check`), and hosted-payload privacy review method ### Environment Requirements * Node 20+ with workspace dependencies installed * No hosted accounts, hosted storage, analytics, Cloudflare, tunnel, push, or provider credentials required; core local workflows must validate without them * Synthetic-only test records for any secret/account/zone/tunnel/path/prompt/command/room/log/backup/replay leak check *** ## 4. Scope ### In Scope (MVP) * Operator can run a focused Phase 07 validation command set and read recorded pass/fail evidence - run protocol/server/web/Worker/CLI/browser focused tests plus format, lint, typecheck, build, secret scan, ASCII/LF, and whitespace gates; capture results in implementation-notes.md. * Operator can confirm Phase 07 guardrail behavior end to end - verify disabled defaults, local-only fallback, public-versus-secret config separation, hosted-identity wording, hosted-storage and public-replay disabled states, analytics consent and payload controls, push and remote-access unavailable states, and compact diagnostics against their validated sessions. * Reviewer can confirm no Phase 07 surface leaks sensitive payloads - verify the hosted-payload blocklist holds across analytics, hosted storage, public replay, push, diagnostics, remote access, Worker, exports, archives, logs, and backups using synthetic probes. * Reader can trace every Phase 07 routing requirement to a validated session or a Phase 08 deferral - audit P07-R001 through P07-R025 against the routing matrix and record closure. * Reader can find current Phase 07 posture in stable docs - update master PRD, UX PRD, phase PRD, architecture, API, privacy/security, hosted-services, deployment, environments, release, package README, and security-compliance docs. * Reader can find the Phase 08 handoff - record residual risks and deferrals for trusted erasure, production-hosted validation, release hardening, mobile/WCAG certification, and legacy decommission. ### Out of Scope (Deferred) * Production-hosted release validation - *Reason: Phase 08 owns it unless a later PRD changes ownership.* * Trusted unified erasure, release decommission, mobile certification, WCAG certification, production account audits, public replay release gates - *Reason: explicitly Phase 08 work.* * Real file, git, terminal, Docker, remote, hosted, or Worker executors - *Reason: requires a separate threat model, authorization, audit, tests, and docs.* *** ## 5. Technical Approach ### Architecture This is a validation and documentation session over already-merged Phase 07 work. It introduces no new runtime code and no new hosted surface. It treats the six validated session reports, the routing matrix, and the hosted-payload blocklist as the source of truth, runs the focused command set against the current tree, and reconciles the stable docs and security posture with the recorded evidence. Documentation is updated only after the gate stack passes, so docs follow evidence rather than intent. ### Design Patterns * Evidence-before-docs: run and record the gate stack first; update stable docs and PRDs from recorded results. * Requirement-closure audit: walk P07-R001 through P07-R025 against the routing matrix; mark each closed-by-session or deferred-to-Phase-08. * Honest deferral wording: keep erasure, hosted validation, certification, and decommission language narrow; local validation is not hosted-release proof. * Synthetic-only leak probes: use fabricated secret/account/zone/tunnel/path/prompt/command/room/log/backup/replay values for every privacy check. ### Technology Stack * Vitest 4.1.7 focused runs; Biome 2.4.16 format/lint; `tsc` package typechecks * npm workspace scripts: `format:check`, `lint`, `typecheck`, `test`, `build`, `security:secrets` * `git diff --check` for whitespace; ASCII/LF scan over changed files * Markdown stable docs and spec-system artifacts *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase07-session07-hosted-guardrails-validation-and-documentation-closeout/implementation-notes.md` | Closeout command set, recorded results, evidence paths, requirement-closure audit | \~200 | | `.spec_system/specs/phase07-session07-hosted-guardrails-validation-and-documentation-closeout/validation.md` | Final Phase 07 validation report with command evidence and residual risks | \~240 | | `.spec_system/specs/phase07-session07-hosted-guardrails-validation-and-documentation-closeout/security-compliance.md` | Phase 07 security and GDPR/compliance review across hosted surfaces | \~200 | | `.spec_system/specs/phase07-session07-hosted-guardrails-validation-and-documentation-closeout/IMPLEMENTATION_SUMMARY.md` | Closeout summary, statistics, and Phase 08 handoff | \~140 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------- | --------------------------------------------------------------------- | ---------- | | `.spec_system/PRD/PRD.md` | Mark Phase 07 complete; state Phase 08 deferrals | \~25 | | `.spec_system/PRD/PRD_UX.md` | Scoped-evidence and non-certification wording for hosted/analytics UX | \~20 | | `.spec_system/PRD/phase_07/PRD_phase_07.md` | Progress tracker to 7/7; Session 07 closeout evidence | \~25 | | `.spec_system/SECURITY-COMPLIANCE.md` | Phase 07 residual-risk and carryforward posture | \~30 | | `docs/ARCHITECTURE.md` | Phase 07 guardrail closeout notes | \~15 | | `docs/api/README_api.md` | Diagnostics route and hosted posture closeout notes | \~15 | | `docs/privacy-and-security.md` | Hosted/analytics/push/remote/diagnostics posture and deferrals | \~20 | | `docs/hosted-services.md` | Shipped guardrails and Phase 08 deferrals | \~20 | | `docs/environments.md` | Public/secret/deploy variable boundary closeout | \~15 | | `docs/deployment.md` | Hosted-service deployment posture and deferrals | \~15 | | `docs/release.md` | Phase 07 closeout and remaining release gates | \~15 | | `packages/protocol/README_protocol.md` | Contract ownership closeout notes | \~10 | | `apps/server/README_server.md` | Diagnostics route and redaction closeout notes | \~10 | | `apps/web/README_web.md` | Hosted/analytics/notification posture closeout notes | \~10 | | `apps/cli/README_cli.md` | Loopback diagnostics closeout notes | \~10 | | `apps/warroom/README_warroom.md` | Room-relay-not-hosted-identity closeout note | \~10 | | `.spec_system/state.json` | Session/history state updates | \~5 | *** ## 7. Success Criteria ### Functional Requirements * [ ] The focused Phase 07 validation command set runs and all results are recorded with evidence paths. * [ ] All 25 Phase 07 routing requirements (P07-R001 through P07-R025) are mapped to a validated session or an explicit Phase 08 deferral. * [ ] Disabled-default, local-only fallback, public/secret config separation, hosted identity wording, hosted-storage and public-replay disabled states, analytics consent/payload controls, push and remote-access unavailable states, and compact diagnostics are confirmed against their validated sessions. * [ ] No Phase 07 surface leaks any blocklisted sensitive-payload category under synthetic probes. * [ ] Stable docs and PRDs describe shipped Phase 07 guardrails and remaining Phase 08 risks. ### Testing Requirements * [ ] Focused protocol, server, web, Worker, CLI, and browser tests run and recorded. * [ ] Repo `format:check`, `lint`, `typecheck`, `test`, and `build` recorded. * [ ] `security:secrets`, ASCII/LF, and `git diff --check` whitespace gates recorded. ### Non-Functional Requirements * [ ] Core local workflows validate without hosted accounts, analytics, Cloudflare, tunnel, push, or provider credentials. * [ ] All privacy checks use synthetic-only records; no raw secret/account/zone/tunnel/path/prompt/command/room/log/backup/replay value is read, printed, or committed. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code and docs follow project conventions *** ## 8. Implementation Notes ### Key Considerations * Run the gate stack before touching docs; update PRDs and stable docs from recorded evidence only. * Keep deletion/erasure wording narrow: Phase 07 makes no trusted-erasure claim. * Distinguish account proof from room-local Worker authority everywhere identity is mentioned. * Use focused Vitest runs first, then the full `npm test` pass for the phase gate. * Run the secret scan after staging new closeout artifacts, since it is tracked-file based. ### Potential Challenges * Doc drift across many stable files: use the docs+README synchronization map drafted in Foundation to avoid missed surfaces. * Requirement-closure gaps: if any P07-R0xx requirement is neither validated nor cleanly deferred, record it as a residual risk rather than overclaiming closure. * Full-suite flakiness vs. focused runs: prefer focused runs for evidence, reconcile any full-suite delta explicitly. ### Relevant Considerations * \[P06] **Unified erasure still missing**: closeout must not claim trusted deletion for Worker storage, browser hints, archives, memory, settings, replay, exports, diagnostics, logs, backups, or future hosted/account data; record it as Phase 08 work. * \[P00] **Hosted services are optional**: confirm core local workflows validate without hosted accounts or public client tokens. * \[P05] **Redaction is boundary-specific**: re-verify analytics, hosted storage, public replay, push, diagnostics, Worker, export, archive, backup, and log minimization at each boundary. * \[P03] **Local-first boundary is architectural**: confirm clean degradation when hosted services and credentials are absent. * \[P06] **Phase complete is not release complete**: closeout docs must say what local validation is not (hosted identity, production-hosted validation, certification, trusted erasure). * \[P03] **Stable docs are the current contract**: update README, docs/api, architecture, privacy, deployment, environments, and release docs as current truth. ### Behavioral Quality Focus Checklist active: No (N/A - this session produces validation evidence and documentation, not application code; no new runtime behavior is introduced). *** ## 9. Testing Strategy ### Unit Tests * Re-run focused protocol, server, web, and CLI hosted-guardrail test files; record file/test counts and pass/fail. ### Integration Tests * Run the repo `npm test` pass and the `format:check`, `lint`, `typecheck`, and `build` gates; reconcile any delta against focused runs. ### Manual Testing * Spot-check disabled-default, local-only fallback, public/secret config, hosted identity wording, hosted-storage/public-replay disabled, analytics consent/payload, push/remote unavailable, and compact diagnostics behavior against the six validated session reports. ### Edge Cases * A requirement that is neither validated nor cleanly deferred (record as residual risk). * A stable doc that still implies an active hosted/account/analytics capability (correct wording). * A synthetic leak probe that surfaces a blocklisted category at any boundary (fail closed and record). *** ## 10. Dependencies ### External Libraries * Vitest: ^4.1.7 * Biome: ^2.4.16 * TypeScript `tsc`: per-package ### Other Sessions * **Depends on**: `phase07-session01` through `phase07-session06` * **Depended by**: Phase 08 (Release Hardening and Legacy Decommission) *** ## Next Steps Run `/implement` 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/phase07-session07-hosted-guardrails-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.