> 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-session01-protocol-suggestion-contract-parity/implementation-notes.md). # Implementation Notes **Session ID**: `phase18-session01-protocol-suggestion-contract-parity` **Package**: packages/protocol **Started**: 2026-06-09 22:50 **Last Updated**: 2026-06-09 23:27 *** ## Session Progress | Metric | Value | | ------------------- | --------- | | Tasks Completed | 23 / 23 | | Estimated Remaining | 0 minutes | | Blockers | 0 | *** ## Task Log ### 2026-06-09 - Session Start **Environment verified**: * [x] Prerequisites confirmed with `.spec_system/scripts/check-prereqs.sh --json --env --package packages/protocol` * [x] Tools available with `.spec_system/scripts/check-prereqs.sh --json --tools "node,npm"` * [x] Directory structure ready * [x] `.nvmrc` resolves to Node 26.2.0; package commands were run with `nvm use --silent 26.2.0` *** ### Task T001 - Verify prerequisites, Appendix A inventory, and exclusions **Started**: 2026-06-09 22:49 **Completed**: 2026-06-09 22:51 **Duration**: 2 minutes **Notes**: * Confirmed active package `packages/protocol`, Phase 17 completion, Phase 18 Session 01 scope, Appendix A evidence rows, and exclusions for telemetry, entitlement gates, server runtime, web UI, and codebase-issue accept parity. * Ran baseline focused protocol tests before implementation. **Files Changed**: * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/tasks.md` - marked T001 complete. * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/implementation-notes.md` - recorded setup evidence. **BQC Fixes**: * N/A - evidence review only. *** ### Task T002 - Verify protocol layout, exports, validators, and current events **Started**: 2026-06-09 22:51 **Completed**: 2026-06-09 22:52 **Duration**: 1 minute **Notes**: * Reviewed `packages/protocol/src`, `packages/protocol/tests`, `src/index.ts`, `notices.ts`, and the current `idle_suggestion` / `quest_board` definitions in `events.ts`. **Files Changed**: * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/tasks.md` - marked T002 complete. * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/implementation-notes.md` - recorded package pattern evidence. **BQC Fixes**: * N/A - evidence review only. *** ### Task T003 - Create suggestion contract test scaffold **Started**: 2026-06-09 22:52 **Completed**: 2026-06-09 22:53 **Duration**: 1 minute **Notes**: * Created the focused suggestion test file scaffold for card, guard, helper, and snapshot coverage. **Files Changed**: * `packages/protocol/tests/suggestions.test.ts` - added the scaffold that was later replaced with full assertions. * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/tasks.md` - marked T003 complete. **BQC Fixes**: * N/A - test scaffold only. *** ### Task T004 - Define suggestion vocabularies **Started**: 2026-06-09 22:53 **Completed**: 2026-06-09 22:58 **Duration**: 5 minutes **Notes**: * Added exported `as const` vocabularies for issue types, severities, analysis item types, project scan categories, efforts, follow-up categories, priorities, scan statuses, scan scopes, scan modes, and accept actions. * Encoded the Appendix A TODO-family correction as lower-case `todo`, `fixme`, `hack`, `xxx`, and `bug` values. **Files Changed**: * `packages/protocol/src/suggestions.ts` - added canonical suggestion vocabularies and union types. **BQC Fixes**: * Contract alignment: enum values are explicit and shared. *** ### Task T005 - Define parity constants **Started**: 2026-06-09 22:58 **Completed**: 2026-06-09 22:59 **Duration**: 1 minute **Notes**: * Added caps for project scan items, issues per category, dismissed IDs, analysis freshness, project scan freshness, codebase scan freshness, and bounded string lengths. **Files Changed**: * `packages/protocol/src/suggestions.ts` - added parity caps, freshness windows, and bounds. **BQC Fixes**: * Failure path completeness: parsers can reject oversized payloads. *** ### Task T006 - Define idle, issue, summary, and follow-up interfaces **Started**: 2026-06-09 22:59 **Completed**: 2026-06-09 23:00 **Duration**: 1 minute **Notes**: * Added typed idle suggestion, codebase issue, session summary, and follow-up task interfaces, including `suggestedAgentType` and accept prompts. **Files Changed**: * `packages/protocol/src/suggestions.ts` - added core card interfaces. **BQC Fixes**: * Contract alignment: display and action fields are present in shared types. *** ### Task T007 - Define analysis and project scan interfaces **Started**: 2026-06-09 23:00 **Completed**: 2026-06-09 23:01 **Duration**: 1 minute **Notes**: * Added analysis result and project scan contracts with generated-at and fresh-until metadata. **Files Changed**: * `packages/protocol/src/suggestions.ts` - added analysis and project scan interfaces. **BQC Fixes**: * State freshness on re-entry: freshness metadata is shared in the contract. *** ### Task T008 - Define snapshot, scan, and summary contracts **Started**: 2026-06-09 23:01 **Completed**: 2026-06-09 23:02 **Duration**: 1 minute **Notes**: * Added `SuggestionSnapshot`, scan trigger/status contracts, summary counts, and severity buckets. **Files Changed**: * `packages/protocol/src/suggestions.ts` - added snapshot, scan, and summary contracts. **BQC Fixes**: * Contract alignment: all snapshot sources are represented in one shared shape. *** ### Task T009 - Define accept and dismiss contracts **Started**: 2026-06-09 23:02 **Completed**: 2026-06-09 23:03 **Duration**: 1 minute **Notes**: * Added accept request/response contracts with `send_prompt` and `prompt_sent` discriminants, plus suggestion and issue dismiss contracts. **Files Changed**: * `packages/protocol/src/suggestions.ts` - added accept/dismiss contract types. * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/tasks.md` - marked T004 through T009 complete. **BQC Fixes**: * Contract alignment: accept results are a discriminated union. *** ### Task T010 - Add fail-closed vocabulary guards and parsers **Started**: 2026-06-09 23:03 **Completed**: 2026-06-09 23:06 **Duration**: 3 minutes **Notes**: * Added `is*` guards and `parse*` helpers for all suggestion vocabularies using `invalid_suggestion_value` results. **Files Changed**: * `packages/protocol/src/suggestions.ts` - added vocabulary guards and parsers. **BQC Fixes**: * Trust boundary enforcement: unknown enum values fail closed. * Error information boundaries: validation errors expose stable field messages only. *** ### Task T011 - Add bounded normalization helpers and path rejection **Started**: 2026-06-09 23:06 **Completed**: 2026-06-09 23:07 **Duration**: 1 minute **Notes**: * Added bounded helpers for IDs, titles, text, prompts, categories, timestamps, line numbers, card arrays, dismissed IDs, codebase issue arrays, and repo-relative file paths. * File paths reject absolute paths, traversal segments, Windows absolute paths, backslashes, URL-like values, empty segments, current segments, parent segments, and NUL bytes. **Files Changed**: * `packages/protocol/src/suggestions.ts` - added normalization and path safety helpers. **BQC Fixes**: * Trust boundary enforcement: unsafe file paths are rejected. * Failure path completeness: malformed fields return explicit validation errors. *** ### Task T012 - Add snapshot parser and freshness predicates **Started**: 2026-06-09 23:07 **Completed**: 2026-06-09 23:08 **Duration**: 1 minute **Notes**: * Added card parsers, full snapshot parsing, and deterministic freshness helpers with explicit `now` arguments. **Files Changed**: * `packages/protocol/src/suggestions.ts` - added card parsers, snapshot parser, and freshness helpers. * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/tasks.md` - marked T010 through T012 complete. **BQC Fixes**: * State freshness on re-entry: freshness checks avoid hidden wall-clock behavior. * Contract alignment: snapshots validate every nested source before producing typed output. *** ### Task T013 - Add suggestion update event and retire quest\_board **Started**: 2026-06-09 23:08 **Completed**: 2026-06-09 23:10 **Duration**: 2 minutes **Notes**: * Added `SuggestionUpdateEvent` as a top-level snapshot event, kept `IdleSuggestionEvent` unchanged, and documented `QuestBoardEvent` as retired and excluded from `ServerEvent`. **Files Changed**: * `packages/protocol/src/events.ts` - added `suggestion_update`, froze `idle_suggestion`, and retired `quest_board` from the active union. * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/tasks.md` - marked T013 complete. **BQC Fixes**: * Contract alignment: new emitters can use the typed snapshot event, not the retired legacy event. *** ### Task T014 - Export suggestions and add REST aliases **Started**: 2026-06-09 23:10 **Completed**: 2026-06-09 23:12 **Duration**: 2 minutes **Notes**: * Exported `suggestions.ts`, added the `suggestions` REST family, and aliased accept, dismiss, scan trigger/status, and summary contracts. **Files Changed**: * `packages/protocol/src/index.ts` - exported the suggestions module. * `packages/protocol/src/rest.ts` - added REST family and aliases. * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/tasks.md` - marked T014 complete. **BQC Fixes**: * Contract alignment: REST aliases point to protocol-owned suggestion contracts. *** ### Task T015 - Add card-shape and vocabulary tests **Started**: 2026-06-09 23:12 **Completed**: 2026-06-09 23:13 **Duration**: 1 minute **Notes**: * Added card fixtures and vocabulary assertions for all suggestion card sources. **Files Changed**: * `packages/protocol/tests/suggestions.test.ts` - added card-shape and vocabulary tests. **BQC Fixes**: * Contract alignment: tests pin shared vocabularies to the Phase 18 inventory. *** ### Task T016 - Add guard and parser failure tests **Started**: 2026-06-09 23:13 **Completed**: 2026-06-09 23:14 **Duration**: 1 minute **Notes**: * Added negative parser coverage for unknown issue types, severities, analysis types, project categories, efforts, priorities, scan statuses, and follow-up categories. **Files Changed**: * `packages/protocol/tests/suggestions.test.ts` - added fail-closed parser tests. **BQC Fixes**: * Trust boundary enforcement: tests prove unknown enum values are rejected. *** ### Task T017 - Add helper and snapshot tests **Started**: 2026-06-09 23:14 **Completed**: 2026-06-09 23:14 **Duration**: 1 minute **Notes**: * Added tests for length bounds, project item caps, issue caps, dismissed-ID FIFO, path rejection, freshness windows, full snapshots, and malformed snapshots. **Files Changed**: * `packages/protocol/tests/suggestions.test.ts` - added helper, freshness, and snapshot tests. * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/tasks.md` - marked T015 through T017 complete. **BQC Fixes**: * State freshness on re-entry: tests pin explicit `now` decisions. * Trust boundary enforcement: path tests cover absolute, traversal, and URL-like inputs. *** ### Task T018 - Update event tests for suggestion\_update and quest\_board retirement **Started**: 2026-06-09 23:14 **Completed**: 2026-06-09 23:16 **Duration**: 2 minutes **Notes**: * Added tests for typed `suggestion_update`, unchanged `idle_suggestion`, and retired `quest_board` union membership. **Files Changed**: * `packages/protocol/tests/events.test.ts` - added suggestion event and retirement tests. * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/tasks.md` - marked T018 complete. **BQC Fixes**: * Contract alignment: tests distinguish active and retired events. *** ### Task T019 - Update REST contract tests **Started**: 2026-06-09 23:16 **Completed**: 2026-06-09 23:18 **Duration**: 2 minutes **Notes**: * Added REST tests for accept branches, suggestion dismiss, issue dismiss, scan trigger/status, summary counts, and severity buckets. **Files Changed**: * `packages/protocol/tests/rest.test.ts` - added suggestion REST alias tests. * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/tasks.md` - marked T019 complete. **BQC Fixes**: * Contract alignment: tests cover both accept response actions and route aliases. *** ### Task T020 - Update protocol README **Started**: 2026-06-09 23:18 **Completed**: 2026-06-09 23:20 **Duration**: 2 minutes **Notes**: * Documented Quest Board contract ownership, `suggestion_update` as canonical, `idle_suggestion` compatibility, `quest_board` retirement, downstream session order, and local-first privacy boundaries. **Files Changed**: * `packages/protocol/README_protocol.md` - added Phase 18 Quest Board suggestion ownership notes. * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/tasks.md` - marked T020 complete. **BQC Fixes**: * Error information boundaries: docs keep telemetry, entitlement, hosted identity, and broad path exposure outside this protocol contract. *** ### Task T021 - Run focused Vitest coverage **Started**: 2026-06-09 23:20 **Completed**: 2026-06-09 23:22 **Duration**: 2 minutes **Notes**: * Ran `npx vitest run packages/protocol/tests/suggestions.test.ts packages/protocol/tests/events.test.ts packages/protocol/tests/rest.test.ts` with Node 26.2.0. * Result: 3 files passed, 28 tests passed. **Files Changed**: * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/tasks.md` - marked T021 complete. * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/implementation-notes.md` - recorded test evidence. **BQC Fixes**: * N/A - verification task. *** ### Task T022 - Run protocol package typecheck **Started**: 2026-06-09 23:22 **Completed**: 2026-06-09 23:23 **Duration**: 1 minute **Notes**: * Ran `npm --workspace packages/protocol run typecheck` with Node 26.2.0. * Result: `tsc --noEmit` passed. **Files Changed**: * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/tasks.md` - marked T022 complete. * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/implementation-notes.md` - recorded typecheck evidence. **BQC Fixes**: * N/A - verification task. *** ### Task T023 - Validate ASCII, LF, and final evidence **Started**: 2026-06-09 23:23 **Completed**: 2026-06-09 23:27 **Duration**: 4 minutes **Notes**: * Ran `npx biome format --write` on touched protocol TypeScript files; Biome formatted 7 files and fixed 2 files. * Reran focused tests after formatting: 3 files passed, 28 tests passed. * Reran `npm --workspace packages/protocol run typecheck`; result: `tsc --noEmit` passed. * Validated ASCII and LF for all touched files; result: ASCII ok, LF ok. * Ran `git diff --check`; result: clean. **Files Changed**: * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/tasks.md` - marked T023 and the completion checklist complete. * `.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/implementation-notes.md` - recorded final validation evidence. **BQC Fixes**: * N/A - verification task. *** ## Verification Summary | Check | Result | | ---------------------- | ------------------------- | | Focused protocol tests | Passed: 3 files, 28 tests | | Protocol typecheck | Passed: `tsc --noEmit` | | ASCII validation | Passed | | LF validation | Passed | | `git diff --check` | Passed | | Blockers | 0 | *** ## Refactor Watch `packages/protocol/src/suggestions.ts` is the single exported protocol owner requested by this session and now contains contracts plus validators. If later Phase 18 server or web sessions add more runtime-specific helpers, split internal parser/normalizer implementation into smaller protocol modules while keeping the public exports stable. *** ## Validation Evidence **Completed**: 2026-06-09 * `vitest.config.ts` was updated to disable Vite env-file discovery during tests so ignored developer-local env files such as `.env.local` and `apps/web/.env.local` do not change deterministic web test defaults. * `npm test -- --project web` passed: 103 files, 1796 tests. * `npm --workspace packages/protocol run typecheck` passed. * `npx vitest run packages/protocol/tests/suggestions.test.ts packages/protocol/tests/events.test.ts packages/protocol/tests/rest.test.ts` passed: 3 files, 28 tests. * `npm run format:check` passed: 607 files checked. * `npm run lint` passed: 609 files checked. * `npm run typecheck --workspaces --if-present` passed. * `npm test` passed: 197 files passed, 1 skipped; 2532 tests passed, 1 skipped. * `npm run security:secrets` passed: 1529 tracked text files checked. * Deliverable files plus `vitest.config.ts` were checked for ASCII-only content and LF endings. * `git diff --check` passed. *** --- # 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-session01-protocol-suggestion-contract-parity/implementation-notes.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.