> 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_18/session_01_protocol_suggestion_contract_parity.md).

# Session 01: Protocol Suggestion Contract Parity

**Session ID**: `phase18-session01-protocol-suggestion-contract-parity` **Package**: packages/protocol **Status**: Complete **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Define the canonical typed Quest Board contracts in `packages/protocol` so every later server and web session builds on shared shapes instead of ad hoc strings.

***

## Scope

### In Scope (MVP)

* Typed idle suggestion shape: id, session/hero linkage, title, text, category, priority, created-at timestamp
* Typed codebase issue shape: id, type (todo-family, git\_status, lint, build, test), severity, file path, line, message/title, suggested prompt, suggested agent type
* Typed on-demand analysis result: item types (potential\_bug, error\_handling, code\_style, refactoring, performance, feature\_idea, enhancement), validated priority, generated-at, freshness metadata
* Typed project scan result: title, description, prompt, category (architecture, dependencies, performance, security, testing, feature\_idea), effort (small, medium, large), priority, capped at 4 items
* Typed session summary with follow-up tasks and categories (test, documentation, refactor, validation)
* `suggestion_update` snapshot event carrying idle suggestions, codebase issues, session summaries, analysis result, project scan, and scan status
* Accept/dismiss request and response shapes, including hero-routed accept (`send_prompt`) versus broadcast (`prompt_sent`) results
* Scan trigger/status and summary (counts plus severity buckets) shapes
* Reconcile existing `idle_suggestion` (string) and unused `quest_board` events: keep `idle_suggestion` as a compatibility emission, implement or formally retire `quest_board`
* Protocol unit tests and exported type/schema coverage

### Out of Scope

* Server manager, routes, engines, or web store changes
* Telemetry and entitlement shapes (excluded for this phase)

***

## Prerequisites

* [x] Phase 17 complete; protocol package test suite green
* [x] Parity audit reviewed for the full card-shape inventory

***

## Deliverables

1. New suggestion/quest contract module in `packages/protocol` with schemas and types for all card sources and the snapshot event
2. Accept/dismiss, scan-status, and summary request/response contracts
3. Documented compatibility decision for `idle_suggestion` and `quest_board`
4. Protocol tests covering parsing, validation, and rejection of malformed payloads

***

## Success Criteria

* [x] All shapes named in the parity audit card-metadata rows exist as exported protocol types with runtime validation
* [x] `suggestion_update` snapshot schema validates a full mixed-source fixture
* [x] Existing protocol consumers compile unchanged (compat aliases where needed)
* [x] Protocol test suite passes with new coverage included

***

## Historical Evidence (EXAMPLES References)

Preserved from the 2026-06-07 parity audit (full audit in `PRD_phase_18.md` Appendix A). Evidence only; never import, copy, or transform historical code.

* `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` - snapshot state fields `idleSuggestions`, `codebaseIssues`, `sessionSummaries`, `analysisResult`, `projectScan`; `setIdleSuggestions` with `MAX_SUGGESTIONS_PER_SESSION=1`; suggestion IDs, session IDs, created-at timestamps; `getSummary` (counts plus severity buckets); `getCurrentState` / `emitUpdate` snapshot shape; `acceptQuest` returning `sourceType:"quest_board"` (latent in EXAMPLES; excluded from parity).
* `EXAMPLES/package-0.4.1/server/dist/codebaseScanEngine.js:1` - issue card shape from `parseTodoOutput`, `scanGitStatus`, `scanLint`, `scanBuild`, `scanTests`: type, severity, file path, line, title/message, suggested prompt, and per-card `suggestedAgentType` (for example `general-purpose`, `Bash`).
* `EXAMPLES/package-0.4.1/server/dist/onDemandAnalysisEngine.js:1` - analysis item shape via `parseAnalysisResponse`; `validateType` over `potential_bug|error_handling|code_style|refactoring|performance| feature_idea|enhancement`; `validatePriority`.
* `EXAMPLES/package-0.4.1/server/dist/projectScanEngine.js:1` - project scan item shape via `parseProjectScanResponse` / `parseSurveyResponse`: `title`, `description`, `prompt`, `category` (`architecture|dependencies|performance|security|testing|feature_idea`), `effort` (`small|medium|large`), `priority`; capped at 4 items (`validateCategory`, `validateEffort`).
* `EXAMPLES/package-0.4.1/server/dist/sessionSummaryEngine.js:1` - follow-up task categories `test`, `documentation`, `refactor`, `validation`.
* `EXAMPLES/package-0.4.1/server/dist/index.js:1` - accept response contract: `action:"send_prompt"` with `endpoint:/internal-heroes/{heroId}/prompt` versus broadcast `user_prompt` returning `action:"prompt_sent"`.
* `EXAMPLES/findings/websocket-events.txt:53` and `EXAMPLES/findings/websocket-events.txt:139` - `suggestion_update` snapshot event evidence (idle suggestions, codebase issues, session summaries, analysis result, project scan).
* `EXAMPLES/findings/api-routes.txt:149` through `EXAMPLES/findings/api-routes.txt:158` - historical `/suggestions/*` route family shapes, including `GET /suggestions/summary` at `EXAMPLES/findings/api-routes.txt:158`.
* `EXAMPLES/package-0.4.1/frontend/dist/assets/index-CuYaJ5lV.js:2` - client consumption of `suggestion_update`.

## Current-Code Touchpoints (Audit Snapshot 2026-06-07)

* `packages/protocol/src/events.ts:380` - existing string `idle_suggestion` event to keep as a compatibility emission.
* `packages/protocol/src/events.ts:386` - unused `quest_board` event to implement or formally retire.
* `apps/web/src/store/useGameStore.ts:216` - current `{ heroId, text }` suggestion shape being replaced.


---

# 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_18/session_01_protocol_suggestion_contract_parity.md?ask=<question>&goal=<endgoal>
```

`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.