> 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/implementation_summary.md). # Implementation Summary **Session ID**: `phase18-session08-on-demand-analysis-and-project-scan-engines` **Package**: apps/server **Completed**: 2026-06-10 **Duration**: 15 minutes *** ## Overview Implemented the remaining server-side Quest Board analysis and project scan engines for Phase 18 session 08. The server now supports manager-owned on-demand analysis and project-level strategic scans, with root and `/api` trigger/status routes, fresh-cache returns, single-flight conflict handling, fallback outputs, bounded provider timeouts, startup stale project scanning, and unsupported-route reconciliation. *** ## Deliverables ### Files Created | File | Purpose | | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | | `apps/server/src/lib/onDemandAnalysisEngine.ts` | Analysis file selection, provider/fallback execution, parsing, freshness, status, persistence, and cleanup | | `apps/server/src/lib/projectScanEngine.ts` | Project scan orchestration, parser/fallback, freshness, startup stale scan, status, persistence, and cleanup | | `apps/server/src/llm/prompts/project-scan.md` | Maintained auditable project scan system prompt | | `apps/server/tests/onDemandAnalysisEngine.test.ts` | Analysis selection, parsing, filtering, freshness, fallback, status, and single-flight coverage | | `apps/server/tests/projectScanEngine.test.ts` | Project scan parsing, fallback, freshness, status, startup, and single-flight coverage | | `.spec_system/specs/phase18-session08-on-demand-analysis-and-project-scan-engines/IMPLEMENTATION_SUMMARY.md` | Session completion summary | ### Files Modified | File | Changes | | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `apps/server/src/routes/suggestions.ts` | Added analyze and project-scan trigger/status routes with validation, cache responses, conflict handling, and compact errors | | `apps/server/src/server.ts` | Instantiated engines, scheduled stale project scans, exposed handles, and destroyed engines on shutdown | | `apps/server/src/lib/llmClient.ts` | Added per-call timeout support, project scan model default, and schema-valid analysis/project fallbacks | | `apps/server/src/llm/prompts/index.ts` | Exported `projectScanEngine` prompt | | `apps/server/src/lib/unsupportedRoutes.ts` | Removed shipped analyze/project-scan route prefixes from planned unsupported classification | | `apps/server/tests/suggestionRoutes.test.ts` | Added analyze/project route, cached response, validation, and conflict coverage | | `apps/server/tests/unsupportedRoutes.test.ts` | Updated shipped route classification expectations | | `apps/server/README_server.md` | Documented analyze/project routes, freshness windows, startup behavior, fallback, and privacy limits | | `.spec_system/specs/phase18-session08-on-demand-analysis-and-project-scan-engines/tasks.md` | Marked all implementation tasks complete | | `.spec_system/specs/phase18-session08-on-demand-analysis-and-project-scan-engines/implementation-notes.md` | Added task log and verification evidence | *** ## Technical Decisions 1. **Server-only engine boundaries**: analysis and project scan orchestration live in `apps/server/src/lib`, using `SuggestionManager` for all stored state and snapshot broadcasts. 2. **Cache-first triggers**: fresh analysis results return for 30 minutes and fresh project scans return for 24 hours unless forced. 3. **Compact privacy-safe fallbacks**: malformed, empty, unavailable, or timed out provider output resolves to schema-valid local results without exposing raw prompts, absolute paths, provider payloads, or command output. 4. **Shared scan status compatibility**: new engines use the existing manager-owned `scanStatus` field with explicit `analysis` and `project` scopes. *** ## Test Results | Command | Result | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | `npx biome format --write ...` | Passed, formatted touched source/test files | | `npx biome lint ...` | Passed | | `npm --workspace apps/server run typecheck` | Passed | | `npm test -- apps/server/tests/onDemandAnalysisEngine.test.ts apps/server/tests/projectScanEngine.test.ts apps/server/tests/suggestionRoutes.test.ts apps/server/tests/unsupportedRoutes.test.ts` | Passed: 30 tests | | ASCII/LF scan over touched files | Passed | *** ## Future Considerations Items for future sessions: 1. Render typed analysis and project scan cards in the web Quest Board. 2. Add UI trigger controls and keyboard shortcuts for analyze/project scans. 3. Validate full WebSocket `suggestion_update` behavior during manual browser QA. *** ## Session Statistics * **Tasks**: 24 completed * **Files Created**: 6 * **Files Modified**: 10 * **Tests Added**: 2 test files, plus route and unsupported-route coverage * **Blockers**: 0 --- # 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/implementation_summary.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.