> 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/phase18-session11-validation-documentation-and-handoff/spec.md). # Session Specification **Session ID**: `phase18-session11-validation-documentation-and-handoff` **Phase**: 18 - Quest Board Suggestion Parity **Status**: Implementation Complete **Created**: 2026-06-10 **Package**: Cross-package (`packages/protocol`, `apps/server`, `apps/web`, `docs`, `.spec_system`) **Package Stack**: TypeScript, React/Vite, Node/Express, Vitest, Biome, Markdown docs *** ## 1. Session Overview This session closes Phase 18 by validating the full Quest Board parity stack and moving the shipped behavior into stable documentation and closeout records. Sessions 01 through 10 shipped the shared contracts, server-owned suggestion manager, persistence, routes, WebSocket snapshots, idle and summary engines, codebase scanners, scan orchestration, analysis and project scan engines, typed web cards, card actions, and keyboard shortcuts. The remaining work is cross-package and evidence-led. It should prove the Quest Board works end to end from generation and scan inputs through server state, WebSocket hydration, web rendering, actions, persistence, and restart behavior. It should also reconcile the stable docs, privacy inventory, unsupported-route posture, prompt documentation, Appendix A parity inventory, phase tracker, master PRD progress, and handoff notes in one pass. This session must not add new Quest Board features beyond the Phase 18 charter. Any gaps found during validation should be fixed only if they are direct regressions against shipped scope; larger improvements, hosted telemetry, entitlement gates, issue-accept behavior, or executor integrations should be recorded as follow-up work instead. *** ## 2. Objectives 1. Validate protocol, server, and web Quest Board behavior end to end with focused package tests, full workspace gates, and safe summarized manual evidence. 2. Update stable docs so API, architecture, package README, keyboard shortcut, prompt, and privacy records match the shipped Quest Board system. 3. Reconcile final route support and Appendix A parity status so shipped, deliberately excluded, and follow-up rows are auditable. 4. Close Phase 18 planning records with tracker, PRD, security, validation, and handoff artifacts ready for `validate` and `updateprd`. *** ## 3. Prerequisites ### Required Sessions * [x] `phase18-session01-protocol-suggestion-contract-parity` - provides the canonical suggestion, issue, analysis, project scan, summary, snapshot, REST, and event contracts. * [x] `phase18-session02-server-suggestion-manager-and-persistence` - provides server-owned Quest Board state, dismissed-ID persistence, freshness windows, summary counts, and shutdown flush behavior. * [x] `phase18-session03-suggestion-routes-and-websocket-parity` - provides accept, dismiss, issue-dismiss, summary, WebSocket broadcast, and connect-time hydrate behavior. * [x] `phase18-session04-idle-lifecycle-engine-parity` - provides hero-idle generation, transcript context, modified-file awareness, cooldown, in-flight guards, timeouts, and fallback suggestions. * [x] `phase18-session05-session-summary-engine-and-noise-filtering` - provides follow-up summaries and analysis noise filtering. * [x] `phase18-session06-codebase-issue-scanners` - provides TODO-family, git status, lint, build/typecheck, and test failure scanners. * [x] `phase18-session07-scan-orchestration-and-quest-ignore-patterns` - provides full, diff, and daily scan orchestration plus ignore patterns. * [x] `phase18-session08-on-demand-analysis-and-project-scan-engines` - provides on-demand analysis and project scan engines, trigger routes, status routes, freshness behavior, and startup staleness wiring. * [x] `phase18-session09-web-quest-board-typed-cards` - provides typed web card normalization, snapshot handling, summary display, and card rendering. * [x] `phase18-session10-quest-actions-and-keyboard-shortcuts` - provides accept, dismiss, assign, scan triggers, feedback, and `1`/`2`/`3`/`Alt+X`/ `Alt+R` keyboard behavior. ### Required Tools/Knowledge * Node 26.2.0 or newer with npm 11.16.0. * Root npm workspace scripts, package-local typecheck scripts, Vitest projects, and Biome format/lint gates. * Temporary `FACTIONOS_HOME` and local server validation patterns. * Existing Quest Board source, tests, and docs in `packages/protocol`, `apps/server`, `apps/web`, `docs`, and `.spec_system`. ### 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 safe summarized validation evidence; do not record raw prompts, command bodies, file contents, terminal output, secrets, broad absolute paths, or raw persisted suggestion payloads. * Do not require Cloudflare credentials, hosted analytics, hosted identity, public replay hosting, remote execution, Docker execution, entitlement systems, or trusted unified erasure evidence. *** ## 4. Scope ### In Scope (MVP) * Operators have validation evidence for hero-idle generation through `suggestion_update` snapshot hydration to rendered typed Quest Board cards. * Operators have validation evidence for accept, dismiss, issue-dismiss, assignment, bulk dismiss, and keyboard shortcut behavior with duplicate trigger prevention and failure feedback. * Operators have validation evidence that dismissed IDs and persisted Quest Board state survive server restart through `suggestions.json`. * Operators have validation evidence for full, diff, and stale-startup codebase scans, ignore patterns, on-demand analysis, project scan, status routes, freshness windows, and deterministic fallback behavior. * Stable API docs describe the shipped `/suggestions/*`, `/issues/*`, summary, scan, analysis, project-scan, status, and WebSocket snapshot contracts. * Stable architecture and package README docs describe the protocol contracts, manager ownership, engine boundaries, scan privacy, web card model, action flows, and keyboard shortcuts. * The idle-suggestion prompt documentation matches the implemented runtime behavior instead of stale mission-complete or non-shipped shortcut claims. * Privacy and security docs include `suggestions.json` as a local data surface containing file paths and code-derived text, with a manual deletion path and explicit trusted-erasure no-claim coverage. * `apps/server/src/lib/unsupportedRoutes.ts` reflects only genuinely unshipped historical routes, with deliberate exclusions documented. * Appendix A parity rows in `.spec_system/PRD/phase_18/PRD_phase_18.md` are marked shipped, deliberately excluded, or follow-up with source-backed rationale. * Phase tracker, master PRD progress, implementation notes, security report, validation report, and handoff summary are updated together. ### Out of Scope (Deferred) * New Quest Board features discovered during validation - *Reason: record them as follow-up work unless they are direct regressions against Phase 18 scope.* * Accepting codebase issues as executable quests - *Reason: the historical `acceptQuest` path was latent and is explicitly excluded from this phase.* * Historical suggestion telemetry and entitlement gating - *Reason: analytics and hosted entitlement systems are excluded by local-first guardrails.* * Real file, git, terminal, remote, Docker, or queue executors - *Reason: real executors require a separate threat model and remain out of scope.* * Hosted identity, hosted storage, public replay hosting, push delivery, production-hosted validation, formal certification, or trusted unified erasure claims - *Reason: current security posture keeps these as no-claim boundaries without dedicated evidence.* *** ## 5. Technical Approach ### Architecture Treat this as a validation and documentation closeout over an already-shipped cross-package runtime. Start by building a coverage matrix from the Phase 18 PRD, the Session 11 stub, Sessions 01-10 validation records, stable docs, and current source tests. Use that matrix to drive both validation evidence and docs updates so every shipped route, event, manager behavior, engine, card source, action, and keyboard shortcut is traceable. Validation should combine focused package tests with broad gates. Focused tests prove contracts and behavior at the owning package boundary; broad root format, lint, typecheck, and test gates prove no cross-package drift was introduced by docs or reconciliation changes. Manual evidence should be safe and summarized, using temporary local state and redacted outputs where runtime checks are useful. Docs should be updated at the stable ownership boundary rather than duplicated in one long record: protocol contract notes in `packages/protocol`, server manager and engine behavior in `apps/server`, cockpit and shortcuts in `apps/web`, external contract details in `docs/api`, architecture in `docs/ARCHITECTURE.md`, privacy and local data inventory in `docs/privacy-and-security.md`, and phase closeout in `.spec_system`. ### Design Patterns * Coverage matrix: keeps Appendix A parity rows, docs targets, and validation checks from drifting apart. * Manager-owned state: treats `SuggestionManager` as the source of truth for persistence, freshness, dismissed IDs, and emitted snapshots. * Contract-first validation: checks `packages/protocol` before server and web assumptions. * Safe evidence: records statuses, counts, route names, file names, and redacted summaries instead of sensitive local payloads. ### Technology Stack * TypeScript packages: `packages/protocol`, `apps/server`, `apps/web`. * React 19, Vite, Zustand, and Vitest in `apps/web`. * Node/Express and Vitest in `apps/server`. * Biome for format and lint gates. * Markdown docs and `.spec_system` closeout artifacts. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase18-session11-validation-documentation-and-handoff/phase18-validation-record.md` | End-to-end validation matrix, commands, results, and blockers | \~180 | | `.spec_system/specs/phase18-session11-validation-documentation-and-handoff/phase18-docs-handoff.md` | Stable docs ownership matrix, update checklist, and closeout handoff | \~140 | | `.spec_system/specs/phase18-session11-validation-documentation-and-handoff/security-compliance.md` | Session security, privacy, GDPR, and no-claim evidence | \~120 | | `.spec_system/specs/phase18-session11-validation-documentation-and-handoff/implementation-notes.md` | Implementation notes and decisions recorded during closeout | \~120 | | `.spec_system/specs/phase18-session11-validation-documentation-and-handoff/validation.md` | Final validation report for the validate workflow | \~140 | | `.spec_system/specs/phase18-session11-validation-documentation-and-handoff/IMPLEMENTATION_SUMMARY.md` | Human-readable session summary and next-step handoff | \~90 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------- | | `docs/api/README_api.md` | Document shipped `/suggestions/*`, `/issues/*`, status, summary, and WebSocket contracts | \~80 | | `docs/ARCHITECTURE.md` | Add Quest Board runtime flow, source-of-truth, persistence, and engine boundaries | \~50 | | `docs/privacy-and-security.md` | Add `suggestions.json`, local data inventory, deletion path, transfer/no-claim notes | \~60 | | `docs/README_docs.md` | Route readers to current Quest Board API, architecture, privacy, and package docs | \~25 | | `packages/protocol/README_protocol.md` | Finalize Quest Board contract ownership and event guidance | \~25 | | `apps/server/README_server.md` | Document SuggestionManager, engines, scans, persistence, and local privacy boundaries | \~70 | | `apps/web/README_web.md` | Document typed cards, actions, scan triggers, feedback states, and shortcuts | \~70 | | `apps/server/src/llm/prompts/idle-suggestion-engine.md` | Reconcile prompt doc with actual hero-idle runtime behavior | \~60 | | `apps/server/src/lib/unsupportedRoutes.ts` | Reconcile remaining unsupported historical routes and exclusions | \~20 | | `.spec_system/PRD/phase_18/PRD_phase_18.md` | Mark Session 11 closeout and Appendix A parity status during implementation | \~90 | | `.spec_system/PRD/PRD.md` | Update Phase 18 progress summary after closeout | \~25 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Full protocol, server, and web Quest Board gates are run and results recorded with exact pass/fail or blocker status. * [ ] Hero-idle generation, snapshot hydration, typed web card rendering, and action feedback are evidenced without leaking sensitive payloads. * [ ] Accept, dismiss, issue-dismiss, assignment, bulk dismiss, and keyboard shortcuts are validated with duplicate-trigger and failure-path coverage. * [ ] `suggestions.json` persistence, restart behavior, dismissed IDs, and manual deletion path are documented and evidenced. * [ ] Scan, analysis, project scan, status, freshness, fallback, and ignore pattern behavior are evidenced. * [ ] Stable API, architecture, protocol, server, web, prompt, docs index, and privacy documentation match shipped behavior. * [ ] `unsupportedRoutes.ts` lists only genuinely unshipped or deliberately excluded historical behavior. * [ ] Appendix A parity inventory records shipped, deliberately excluded, or follow-up status for every Phase 18 audit row. ### Testing Requirements * [ ] Focused protocol tests for suggestion contracts and events pass. * [ ] Focused server tests for manager, routes, WebSocket, engines, scanners, orchestration, and unsupported routes pass. * [ ] Focused web tests for Quest Board normalization, store, component, action client, and keyboard shortcuts pass. * [ ] Root format, lint, workspace typecheck, and test gates pass or blockers are recorded precisely. * [ ] ASCII, LF, and secret scan checks are recorded after new artifacts are staged or otherwise ready for validation. ### Non-Functional Requirements * [ ] Local-first and disabled-hosted-service boundaries remain explicit. * [ ] No new raw prompt, transcript, command, file content, secret, broad path, analytics, hosted identity, or trusted-erasure claim is introduced. * [ ] Validation evidence is reproducible and safe to keep in the repository. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Documentation routes and claims are internally consistent. *** ## 8. Implementation Notes ### Key Considerations * The session is cross-cutting because the closeout spans protocol, server, web, docs, privacy, and `.spec_system` records. * The Session 11 stub is validation and documentation scope; new feature work should be limited to direct fixes required for declared success criteria. * `EXAMPLES/` remains traceability evidence only and must not be imported, copied, transformed, or promoted. * Validation records should summarize commands and outcomes without raw local sensitive data. ### Potential Challenges * Full root gates may be slow: run focused gates first and record precise blockers if a broad gate fails outside Phase 18 scope. * Manual end-to-end flows may require local state setup: use temporary `FACTIONOS_HOME` and record redacted summaries rather than raw payloads. * Docs drift can return quickly: update route docs, package docs, privacy inventory, and Appendix A in the same implementation pass. ### Relevant Considerations * \[P08] **Full trusted erasure remains no-claim**: `suggestions.json` expands the local data inventory and must be documented as manual-deletion only. * \[P01-apps/server] **Anthropic transfer is two-level opt-in**: validation and docs must keep provider transfer disabled unless both credentials and explicit opt-in are present. * \[P03-apps/server] **Local server boundary must stay conservative**: `/suggestions/*` docs and validation must preserve validation, rate limits, body-size caps, and compact errors. * \[P07] **Redaction is boundary-specific**: scan outputs, suggestions, and validation evidence must avoid raw prompts, secrets, command bodies, and broad absolute paths. * \[P03] **Stable docs are the current contract**: closeout must update stable docs rather than leaving behavior only in specs or historical evidence. * \[P17] **Closeout artifacts belong together**: phase tracker, stable docs, validation evidence, security posture, and handoff notes should land in the same pass. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Validation misses a shipped path and docs overstate parity. * Sensitive local data is copied into evidence while proving persistence or scan behavior. * Route or shortcut docs imply telemetry, entitlement, executor, hosted, or trusted-erasure behavior that remains excluded. *** ## 9. Testing Strategy ### Unit Tests * Focused protocol suggestion contract and event tests. * Focused server manager, routes, WebSocket, engine, scanner, orchestration, and unsupported route tests. * Focused web Quest Board action, store, component, normalization, and keyboard shortcut tests. ### Integration Tests * Server route and WebSocket snapshot hydration tests for accept, dismiss, summary, status, and mutation broadcasts. * Restart-persistence validation using temporary local FactionOS state. * Root workspace format, lint, typecheck, and test gates. ### Manual Testing * Redacted hero-idle to card rendering flow. * Redacted accept, dismiss, assign, bulk dismiss, and shortcut flows. * Redacted scan, analysis, and project scan trigger/status flows. * Documentation link and route spot checks. ### Edge Cases * Missing or stale `suggestions.json`. * Corrupt persisted suggestion file. * Provider unavailable or transfer not opted in. * Offline local server from the web cockpit. * Duplicate action triggers while pending. * Malformed snapshot entries. * Scan roots outside approved paths or filesystem root. *** ## 10. Dependencies ### External Libraries * None new. ### Other Sessions * **Depends on**: Phase 18 Sessions 01-10. * **Depended by**: `validate`, then `updateprd`; after Phase 18 is complete, phase transition should begin at `audit`. *** ## 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/phase18-session11-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.