> 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-session02-server-suggestion-manager-and-persistence/tasks.md).

# Task Checklist

**Session ID**: `phase18-session02-server-suggestion-manager-and-persistence` **Total Tasks**: 21 **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 | 8      | 8      | 0         |
| Testing        | 4      | 4      | 0         |
| **Total**      | **21** | **21** | **0**     |

***

## Setup (3 tasks)

Initial evidence review and package setup.

* [x] T001 \[S1802] Verify Phase 18 Session 02 prerequisites, Session 01 protocol exports, and explicit exclusions for routes, generators, scanners, UI, telemetry, and entitlement gates (`.spec_system/PRD/phase_18/session_02_server_suggestion_manager_and_persistence.md`)
* [x] T002 \[S1802] Verify existing server manager, persistence, broadcaster, and shutdown patterns before implementation (`apps/server/src/managers/noticeBoard.ts`)
* [x] T003 \[S1802] \[P] Create focused SuggestionManager test scaffold with temporary state directories and fake-timer cleanup (`apps/server/tests/suggestionManager.test.ts`)

***

## Foundation (6 tasks)

Core manager state, store shape, and protocol-safe helpers.

* [x] T004 \[S1802] Create `SuggestionManager` store types, options, persistence error types, constructor defaults, and cloned empty-state factory using protocol-owned suggestion types (`apps/server/src/managers/suggestionManager.ts`)
* [x] T005 \[S1802] Implement local storage path resolution for `suggestions.json` under injected `stateDir`, `FACTIONOS_HOME`, or `~/.factionos` with no raw path exposure in public errors (`apps/server/src/managers/suggestionManager.ts`)
* [x] T006 \[S1802] Implement protocol-backed normalization helpers for idle suggestions, codebase issues, summaries, analysis result, project scan, scan status, and dismissed IDs with schema-validated input and explicit error mapping (`apps/server/src/managers/suggestionManager.ts`)
* [x] T007 \[S1802] Implement snapshot cloning and `getCurrentState` using the single protocol `SuggestionSnapshot` shape with exhaustive source handling (`apps/server/src/managers/suggestionManager.ts`)
* [x] T008 \[S1802] Implement summary counts and severity buckets for active state, dismissed IDs, analysis items, project scan items, and codebase issues (`apps/server/src/managers/suggestionManager.ts`)
* [x] T009 \[S1802] Implement freshness predicates for analysis result, project scan, and codebase scan using the Session 01 protocol freshness windows and explicit clock injection (`apps/server/src/managers/suggestionManager.ts`)

***

## Implementation (8 tasks)

State mutations, persistence, emission, and lifecycle wiring.

* [x] T010 \[S1802] Implement idle suggestion create/replace/list APIs with generated IDs, session/hero linkage, created-at timestamps, per-session cap 1, deterministic ordering, and duplicate-trigger prevention while in-flight (`apps/server/src/managers/suggestionManager.ts`)
* [x] T011 \[S1802] Implement accept and dismiss APIs for idle suggestions plus issue dismiss with idempotent already-mutated behavior, capped FIFO dismissed sets, and state reset after failed mutations (`apps/server/src/managers/suggestionManager.ts`)
* [x] T012 \[S1802] Implement incremental codebase issue APIs - add with dedupe by `type` + `filePath` + `line`, query by type, query by severity, clear by type, and bounded deterministic ordering (`apps/server/src/managers/suggestionManager.ts`)
* [x] T013 \[S1802] Implement session summary, analysis result, project scan, and scan status setters with protocol validation and bounded cloned output on re-entry (`apps/server/src/managers/suggestionManager.ts`)
* [x] T014 \[S1802] Implement debounced persistence load/save/destroy with corrupt-file recovery, atomic temp-plus-rename writes, temp cleanup on write failure, and flush on scope exit for all acquired timers/resources (`apps/server/src/managers/suggestionManager.ts`)
* [x] T015 \[S1802] Implement the single `emitUpdate` path that builds and broadcasts `suggestion_update` snapshots without adding REST routes or WebSocket hydration handlers (`apps/server/src/managers/suggestionManager.ts`)
* [x] T016 \[S1802] Wire `SuggestionManager` into `createFactionOsServer` options and shutdown cleanup with test-state injection and no new `/suggestions/*` route claims (`apps/server/src/server.ts`)
* [x] T017 \[S1802] Update server README with local Quest Board manager persistence notes, manual deletion path, route deferral, and local-first/no-analytics boundaries (`apps/server/README_server.md`)

***

## Testing (4 tasks)

Verification and quality assurance.

* [x] T018 \[S1802] \[P] Write manager state tests for idle suggestion caps, accept/dismiss idempotency, dismissed-ID FIFO, codebase issue dedupe/query/clear, summary counts, and freshness boundaries (`apps/server/tests/suggestionManager.test.ts`)
* [x] T019 \[S1802] \[P] Write manager persistence tests for debounce, atomic save cleanup, restart round-trip, corrupt and malformed store recovery, and destroy flush (`apps/server/tests/suggestionManager.test.ts`)
* [x] T020 \[S1802] Write server lifecycle test proving `createFactionOsServer().stop()` flushes pending suggestion state from the injected manager state directory (`apps/server/tests/suggestionManagerLifecycle.test.ts`)
* [x] T021 \[S1802] Run focused server Vitest, server typecheck, and ASCII/LF validation for touched files, then record implementation notes and validation evidence (`.spec_system/specs/phase18-session02-server-suggestion-manager-and-persistence/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 the validate workflow step

***

## Next Steps

Run the validate workflow step to verify session completeness.


---

# 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-session02-server-suggestion-manager-and-persistence/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.