> 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-session08-on-demand-analysis-and-project-scan-engines/tasks.md).

# Task Checklist

**Session ID**: `phase18-session08-on-demand-analysis-and-project-scan-engines` **Total Tasks**: 24 **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     | 6      | 6      | 0         |
| Implementation | 11     | 11     | 0         |
| Testing        | 4      | 4      | 0         |
| **Total**      | **24** | **24** | **0**     |

***

## Setup (3 tasks)

Initial configuration and environment preparation.

* [x] T001 \[S1808] Verify manager analysis/project storage, freshness helpers, scan status scopes, and snapshot emission prerequisites (`apps/server/src/managers/suggestionManager.ts`)
* [x] T002 \[S1808] Verify current `/llm/analyze`, LLM privacy, scan-root approval, and coexistence requirements before adding Quest Board persistence routes (`apps/server/src/routes/llm.ts`)
* [x] T003 \[S1808] Verify suggestion route, server lifecycle, and unsupported-route integration points before adding analysis/project handlers (`apps/server/src/routes/suggestions.ts`)

***

## Foundation (6 tasks)

Core structures and base implementations.

* [x] T004 \[S1808] \[P] Create analysis file-selection helpers for recent git history, working-tree fallback, code-extension filtering, dependency and lockfile exclusion, deterministic ordering, and 10-file cap (`apps/server/src/lib/onDemandAnalysisEngine.ts`)
* [x] T005 \[S1808] \[P] Create project scan prompt and parser helpers for 2-4 strategic items with protocol category, effort, priority, title, description, and prompt validation (`apps/server/src/lib/projectScanEngine.ts`)
* [x] T006 \[S1808] Define analysis orchestrator types, single-flight state, freshness decisions, status transitions, and cleanup behavior for scoped lifecycle work (`apps/server/src/lib/onDemandAnalysisEngine.ts`)
* [x] T007 \[S1808] Define project scan orchestrator types, single-flight state, freshness decisions, startup stale-scan timer, status transitions, and cleanup behavior (`apps/server/src/lib/projectScanEngine.ts`)
* [x] T008 \[S1808] \[P] Add the maintained project scan system prompt and export it through the prompt index with model selection support (`apps/server/src/llm/prompts/project-scan.md`)
* [x] T009 \[S1808] Extend `llmClient` call options for bounded long-running analysis/project timeouts while preserving provider opt-in, sanitization, and deterministic fallback (`apps/server/src/lib/llmClient.ts`)

***

## Implementation (11 tasks)

Main feature implementation.

* [x] T010 \[S1808] Implement on-demand analysis prompt assembly and provider/fallback execution through `llmClient` with timeout, fallback, and failure-path handling (`apps/server/src/lib/onDemandAnalysisEngine.ts`)
* [x] T011 \[S1808] Implement analysis response normalization into protocol `AnalysisItem` entries with exhaustive enum handling, noise filtering, caps, and compact validation failures (`apps/server/src/lib/onDemandAnalysisEngine.ts`)
* [x] T012 \[S1808] Persist analysis results through `SuggestionManager.setAnalysisResult`, update analysis scan status, return fresh cached results, and emit canonical suggestion updates with duplicate-trigger prevention while in-flight (`apps/server/src/lib/onDemandAnalysisEngine.ts`)
* [x] T013 \[S1808] Implement project scan prompt assembly and provider/fallback execution through `llmClient` with timeout, fallback, and failure-path handling (`apps/server/src/lib/projectScanEngine.ts`)
* [x] T014 \[S1808] Implement project scan response normalization into protocol `ProjectScanItem` entries with exhaustive enum handling, 2-4 item cap, and compact validation failures (`apps/server/src/lib/projectScanEngine.ts`)
* [x] T015 \[S1808] Persist project scan results through `SuggestionManager.setProjectScan`, update project scan status, return fresh cached results, and emit canonical suggestion updates with duplicate-trigger prevention while in-flight (`apps/server/src/lib/projectScanEngine.ts`)
* [x] T016 \[S1808] Add `POST /suggestions/analyze` and `GET /suggestions/analyze/status` handlers with schema-validated input, cache-aware responses, duplicate-trigger conflict handling, and explicit error mapping (`apps/server/src/routes/suggestions.ts`)
* [x] T017 \[S1808] Add `POST /suggestions/project-scan` and `GET /suggestions/project-scan/status` handlers with schema-validated input, cache-aware responses, duplicate-trigger conflict handling, and explicit error mapping (`apps/server/src/routes/suggestions.ts`)
* [x] T018 \[S1808] Wire analysis and project scan engines into server startup/shutdown, including non-blocking stale project scan scheduling and cleanup on shutdown (`apps/server/src/server.ts`)
* [x] T019 \[S1808] De-list shipped analyze/project routes from unsupported route classification while leaving unrelated planned routes intact (`apps/server/src/lib/unsupportedRoutes.ts`)
* [x] T020 \[S1808] Document analyze/project route behavior, freshness windows, startup scanning, cached responses, and local-only privacy limits (`apps/server/README_server.md`)

***

## Testing (4 tasks)

Verification and quality assurance.

* [x] T021 \[S1808] \[P] Write analysis engine tests for git file selection, parsing, validation, noise filtering, freshness, fallback, status reporting, and single-flight behavior (`apps/server/tests/onDemandAnalysisEngine.test.ts`)
* [x] T022 \[S1808] \[P] Write project scan engine tests for parsing, category/effort validation, freshness, fallback, startup stale-scan scheduling, status reporting, and single-flight behavior (`apps/server/tests/projectScanEngine.test.ts`)
* [x] T023 \[S1808] Write route and unsupported-route tests for analyze/project validation, cached responses, duplicate in-flight handling, status responses, root plus `/api` mounting, and shipped route classification (`apps/server/tests/suggestionRoutes.test.ts`)
* [x] T024 \[S1808] Run focused server tests, server typecheck, route no-echo checks, ASCII/LF validation, then update implementation notes with evidence (`apps/server/tests/suggestionRoutes.test.ts`)

***

## 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-session08-on-demand-analysis-and-project-scan-engines/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.