> 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/tasks.md). # Task Checklist **Session ID**: `phase18-session01-protocol-suggestion-contract-parity` **Total Tasks**: 23 **Estimated Duration**: 3-4 hours **Created**: 2026-06-09 *** ## Legend * `[x]` = Completed * `[ ]` = Pending * `[P]` = Parallelizable (can run with other \[P] tasks) * `[SNNMM]` = Session reference (NN=phase number, MM=session number) * `TNNN` = Task ID *** ## Progress Summary | Category | Total | Done | Remaining | | -------------- | ------ | ------ | --------- | | Setup | 3 | 3 | 0 | | Foundation | 6 | 6 | 0 | | Implementation | 11 | 11 | 0 | | Testing | 3 | 3 | 0 | | **Total** | **23** | **23** | **0** | *** ## Setup (3 tasks) Initial configuration and evidence review. * [x] T001 \[S1801] Verify Phase 18 Session 01 prerequisites, PRD Appendix A card-shape inventory, and scope exclusions (`.spec_system/PRD/phase_18/session_01_protocol_suggestion_contract_parity.md`) * [x] T002 \[S1801] Verify protocol package layout, barrel exports, the `notices.ts` validator pattern, and existing `idle_suggestion`/`quest_board` event definitions (`packages/protocol/src/events.ts`) * [x] T003 \[S1801] \[P] Create suggestion contract test scaffold for card, guard, helper, and snapshot coverage (`packages/protocol/tests/suggestions.test.ts`) *** ## Foundation (6 tasks) Core vocabularies, constants, and card interfaces. * [x] T004 \[S1801] Define suggestion vocabularies as exported `as const` arrays - issue types, issue severities, analysis item types, project scan categories, efforts, follow-up categories, priorities, scan statuses - with exhaustive enum handling (`packages/protocol/src/suggestions.ts`) * [x] T005 \[S1801] Define parity constants - project scan 4-item cap, 50 issues per category, dismissed-ID cap 100, analysis freshness 30 minutes, project/codebase scan freshness 24 hours, bounded title/text/prompt/path lengths (`packages/protocol/src/suggestions.ts`) * [x] T006 \[S1801] Define `IdleSuggestion`, `CodebaseIssue` (with `suggestedAgentType`), and `SessionSummary` plus follow-up task interfaces with ids, session/hero linkage, and created-at timestamps, with types matching the declared Appendix A contract (`packages/protocol/src/suggestions.ts`) * [x] T007 \[S1801] Define `AnalysisResult` and `ProjectScan` interfaces with generated-at timestamps and freshness metadata (`packages/protocol/src/suggestions.ts`) * [x] T008 \[S1801] Define the `SuggestionSnapshot` shape (idle suggestions, codebase issues, session summaries, analysis result, project scan, scan status) plus scan trigger/status and summary (counts plus severity buckets) contracts (`packages/protocol/src/suggestions.ts`) * [x] T009 \[S1801] Define accept/dismiss request and response contracts - hero-routed `send_prompt` versus broadcast `prompt_sent` results, suggestion dismiss, and issue dismiss - with exhaustive action handling (`packages/protocol/src/suggestions.ts`) *** ## Implementation (11 tasks) Guards, helpers, event and REST wiring, and contract tests. * [x] T010 \[S1801] Add fail-closed guards and parsers (`is*`/`parse*`) for every vocabulary using the shared validation-result pattern, with schema-validated input and explicit error mapping (`packages/protocol/src/suggestions.ts`) * [x] T011 \[S1801] Add bounded normalization helpers for titles, text, prompts, line numbers, and capped card arrays, rejecting absolute, traversal, and URL-like file paths per the notice related-files rules (`packages/protocol/src/suggestions.ts`) * [x] T012 \[S1801] Add snapshot parser and deterministic freshness predicates (explicit `now` argument) validating the full mixed-source payload and failing closed on partial or malformed snapshots (`packages/protocol/src/suggestions.ts`) * [x] T013 \[S1801] Add the `suggestion_update` event to the event contracts and union, keep `IdleSuggestionEvent` frozen as the compatibility emission, and formally retire `QuestBoardEvent` with the decision documented in source (`packages/protocol/src/events.ts`) * [x] T014 \[S1801] Export the suggestions module from the barrel and alias accept/dismiss, scan trigger/status, and summary REST contracts (`packages/protocol/src/index.ts`, `packages/protocol/src/rest.ts`) * [x] T015 \[S1801] Add card-shape tests proving idle suggestion, codebase issue (including `suggestedAgentType`), analysis, project scan, and session summary fixtures round-trip and vocabularies match Appendix A verbatim (`packages/protocol/tests/suggestions.test.ts`) * [x] T016 \[S1801] Add guard and parser tests proving unknown types, severities, categories, efforts, priorities, statuses, and follow-up categories fail closed (`packages/protocol/tests/suggestions.test.ts`) * [x] T017 \[S1801] Add helper and snapshot tests - length and item caps, dismissed-ID FIFO at 100, path rejection (absolute, traversal, URL-like), freshness windows at/inside/outside bounds, full mixed-source snapshot fixture, malformed snapshot rejection (`packages/protocol/tests/suggestions.test.ts`) * [x] T018 \[S1801] \[P] Update event tests for `suggestion_update` payload typing, unchanged `idle_suggestion` compat shape, and `quest_board` retirement (`packages/protocol/tests/events.test.ts`) * [x] T019 \[S1801] \[P] Update REST contract tests for accept (both result actions), dismiss (suggestion and issue), scan trigger/status, and summary shapes (`packages/protocol/tests/rest.test.ts`) * [x] T020 \[S1801] Update protocol README with Quest Board contract ownership, the `quest_board` retirement decision, downstream session order, and privacy boundary notes (`packages/protocol/README_protocol.md`) *** ## Testing (3 tasks) Verification and quality assurance. * [x] T021 \[S1801] Run focused Vitest coverage for suggestion, event, and REST protocol contracts (`packages/protocol/tests/suggestions.test.ts`) * [x] T022 \[S1801] Run protocol package typecheck and resolve any compile drift across existing consumers (`packages/protocol/package.json`) * [x] T023 \[S1801] Validate ASCII and LF for touched files, then record implementation notes and validation evidence (`.spec_system/specs/phase18-session01-protocol-suggestion-contract-parity/implementation-notes.md`) *** ## Completion Checklist Before marking session complete: * [x] All tasks marked `[x]` * [x] All tests passing * [x] All files ASCII-encoded * [x] implementation-notes.md updated * [x] Ready for `/validate` *** ## 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/phase18-session01-protocol-suggestion-contract-parity/tasks.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.