> 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-session03-suggestion-routes-and-websocket-parity/tasks.md).

# Task Checklist

**Session ID**: `phase18-session03-suggestion-routes-and-websocket-parity` **Total Tasks**: 22 **Estimated Duration**: 3-4 hours **Created**: 2026-06-10

***

## 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     | 5      | 5      | 0         |
| Implementation | 10     | 10     | 0         |
| Testing        | 4      | 4      | 0         |
| **Total**      | **22** | **22** | **0**     |

***

## Setup (3 tasks)

Initial configuration and environment preparation.

* [x] T001 \[S1803] Verify Session 01/02 artifacts, route conventions, and current Quest Board server notes (`apps/server/README_server.md`)
* [x] T002 \[S1803] Verify SuggestionManager accept, dismiss, issue dismiss, summary, and snapshot APIs for route prerequisites (`apps/server/src/managers/suggestionManager.ts`)
* [x] T003 \[S1803] Verify current WebSocket hydration order and strict test expectations before adding suggestion hydrate (`apps/server/tests/websocket.test.ts`)

***

## Foundation (5 tasks)

Core structures and base implementations.

* [x] T004 \[S1803] \[P] Create the suggestion broadcast helper for canonical `suggestion_update` and compatibility `idle_suggestion` emission with types matching declared contracts and no raw payload leakage (`apps/server/src/lib/suggestionBroadcast.ts`)
* [x] T005 \[S1803] \[P] Create the suggestion REST router skeleton and route-local validation helpers with schema-validated input and explicit error mapping (`apps/server/src/routes/suggestions.ts`)
* [x] T006 \[S1803] Extend the WebSocket handler context with SuggestionManager and a suggestion hydrate helper with explicit empty-state handling (`apps/server/src/ws/handlers.ts`)
* [x] T007 \[S1803] Mount the suggestion router under root and `/api` route chains with existing auth, rate-limit, CORS, and body-size middleware boundaries (`apps/server/src/server.ts`)
* [x] T008 \[S1803] Refine unsupported-route classification so only unshipped suggestion engine routes remain planned (`apps/server/src/lib/unsupportedRoutes.ts`)

***

## Implementation (10 tasks)

Main feature implementation.

* [x] T009 \[S1803] Implement `GET /suggestions/summary` from `SuggestionManager.getSummary` with deterministic response shape and explicit error mapping (`apps/server/src/routes/suggestions.ts`)
* [x] T010 \[S1803] Implement `POST /suggestions/:suggestionId/dismiss` with duplicate-trigger prevention while in-flight and post-mutation broadcast (`apps/server/src/routes/suggestions.ts`)
* [x] T011 \[S1803] Implement `POST /issues/:issueId/dismiss` with duplicate-trigger prevention while in-flight and post-mutation broadcast (`apps/server/src/routes/suggestions.ts`)
* [x] T012 \[S1803] Implement accept-route path/body parsing and manager accept transition with schema-validated input and rollback-free not-found handling (`apps/server/src/routes/suggestions.ts`)
* [x] T013 \[S1803] Implement the internal-hero accept branch by verifying the target hero and returning the historical prompt endpoint without executing commands (`apps/server/src/routes/suggestions.ts`)
* [x] T014 \[S1803] Implement the fallback `prompt_sent` branch with a user-prompt compatibility intent and failure-path handling (`apps/server/src/routes/suggestions.ts`)
* [x] T015 \[S1803] Wire every accept, dismiss, and issue-dismiss mutation through the shared broadcast helper so snapshots and compatibility frames cannot drift (`apps/server/src/routes/suggestions.ts`)
* [x] T016 \[S1803] Add `suggestion_update` hydrate on WebSocket connect with deterministic ordering and no client-message vocabulary changes (`apps/server/src/ws/handlers.ts`)
* [x] T017 \[S1803] Update server README route tables and Quest Board notes to reflect shipped Session 03 routes without claiming scan engines (`apps/server/README_server.md`)
* [x] T018 \[S1803] Update unsupported-route tests for shipped suggestion paths and still-planned scan/analyze/project-scan paths (`apps/server/tests/unsupportedRoutes.test.ts`)

***

## Testing (4 tasks)

Verification and quality assurance.

* [x] T019 \[S1803] \[P] Add route integration tests for accept branches, suggestion dismiss, issue dismiss, summary, validation errors, and `/api` prefix behavior (`apps/server/tests/suggestionRoutes.test.ts`)
* [x] T020 \[S1803] \[P] Add WebSocket tests for `suggestion_update` hydrate, mutation broadcasts, `idle_suggestion` compatibility frames, and dismissed item absence (`apps/server/tests/suggestionWebsocket.test.ts`)
* [x] T021 \[S1803] Run focused server Vitest files and server typecheck, fixing failures in the server package (`apps/server/package.json`)
* [x] T022 \[S1803] Validate ASCII encoding and Unix LF line endings for new session artifacts and touched server files (`.spec_system/specs/phase18-session03-suggestion-routes-and-websocket-parity/tasks.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 the validate workflow step

***

## 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-session03-suggestion-routes-and-websocket-parity/tasks.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.