> 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-notes.md). # Implementation Notes **Session ID**: `phase18-session08-on-demand-analysis-and-project-scan-engines` **Package**: apps/server **Started**: 2026-06-10 09:28 **Last Updated**: 2026-06-10 09:41 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 24 / 24 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ## Task Log ### 2026-06-10 - Session Start **Environment verified**: * [x] Prerequisites confirmed * [x] Tools available * [x] Directory structure ready *** ### Task T001 - Verify manager analysis/project storage prerequisites **Started**: 2026-06-10 09:26 **Completed**: 2026-06-10 09:28 **Duration**: 2 minutes **Notes**: * Confirmed `SuggestionManager` owns `analysisResult`, `projectScan`, scan status, freshness helpers, local persistence, validation, and canonical `suggestion_update` emission. * Confirmed `setAnalysisResult` applies `filterAnalysisResult` before storage and `setProjectScan` validates with protocol parsing. **Files Changed**: * None - verification task only. **BQC Fixes**: * N/A - verification task only. ### Task T002 - Verify lower-level LLM analyze and privacy requirements **Started**: 2026-06-10 09:26 **Completed**: 2026-06-10 09:28 **Duration**: 2 minutes **Notes**: * Confirmed `/llm/analyze` remains a caller-provided lower-level utility that emits only compatibility mission events and does not persist Quest Board state. * Confirmed provider transfer remains gated by `ANTHROPIC_API_KEY` plus `FACTIONOS_ALLOW_LLM_PROVIDER_TRANSFER=true`, with path and text sanitizers already available. **Files Changed**: * None - verification task only. **BQC Fixes**: * N/A - verification task only. ### Task T003 - Verify suggestion route, server lifecycle, and unsupported route integration points **Started**: 2026-06-10 09:26 **Completed**: 2026-06-10 09:28 **Duration**: 2 minutes **Notes**: * Confirmed `suggestionRouter` is mounted under both root and `/api` and already handles codebase scan status/trigger routes with compact validation and conflict responses. * Confirmed `server.ts` instantiates codebase scan lifecycle work, schedules stale startup work, and destroys lifecycle coordinators during shutdown. * Confirmed `unsupportedRoutes.ts` currently classifies `/suggestions/analyze` and `/suggestions/project-scan` as planned unsupported routes. **Files Changed**: * None - verification task only. **BQC Fixes**: * N/A - verification task only. ### Task T004 - Create analysis file-selection helpers **Started**: 2026-06-10 09:28 **Completed**: 2026-06-10 09:29 **Duration**: 1 minute **Notes**: * Added recent git history selection, working-tree fallback, deterministic repository fallback, dependency/lockfile exclusion, code-extension filtering, bounded file reads, deterministic ordering, and a 10-file cap. * Selection uses approved scan roots and stores only safe relative paths. **Files Changed**: * `apps/server/src/lib/onDemandAnalysisEngine.ts` - added selection helpers and git runner boundary. **BQC Fixes**: * Trust boundary enforcement: selected paths are normalized as safe relative paths and verified under the approved root before file reads. * External dependency resilience: git commands use timeout and output bounds. ### Task T006 - Define analysis orchestrator lifecycle **Started**: 2026-06-10 09:28 **Completed**: 2026-06-10 09:29 **Duration**: 1 minute **Notes**: * Added `OnDemandAnalysisEngine` with single-flight state, freshness-aware cache returns, manager-owned scan status transitions, compact failure status, and shutdown cleanup. * Added injectable git/provider boundaries for focused unit tests. **Files Changed**: * `apps/server/src/lib/onDemandAnalysisEngine.ts` - added engine lifecycle, status transitions, and cleanup behavior. **BQC Fixes**: * Duplicate action prevention: duplicate triggers throw `AnalysisInFlightError` while a run is active. * State freshness on re-entry: fresh manager-owned analysis results return without rerunning provider work unless forced. * Failure path completeness: analysis failures set compact failed status instead of leaving `running` state. ### Task T005 - Create project scan prompt and parser helpers **Started**: 2026-06-10 09:29 **Completed**: 2026-06-10 09:31 **Duration**: 2 minutes **Notes**: * Added project scan parser helpers that accept arrays or `items` objects, validate category, effort, priority, title, description, and prompt through protocol parsers, and cap output to four items. * Added deterministic fallback project scan items for malformed, empty, or too-small provider output. **Files Changed**: * `apps/server/src/lib/projectScanEngine.ts` - added project scan parser, prompt assembly, and fallback helpers. **BQC Fixes**: * Contract alignment: provider output is normalized through protocol `ProjectScanItem` and `ProjectScan` parsers before storage. * Failure path completeness: invalid or too-small provider output falls back to schema-valid local project scan items. ### Task T007 - Define project scan orchestrator lifecycle **Started**: 2026-06-10 09:29 **Completed**: 2026-06-10 09:31 **Duration**: 2 minutes **Notes**: * Added `ProjectScanEngine` with single-flight protection, project freshness cache returns, manager-owned status transitions, non-blocking stale startup scheduling, compact failure state, and shutdown cleanup. **Files Changed**: * `apps/server/src/lib/projectScanEngine.ts` - added project scan lifecycle, stale startup timer, status, and cleanup behavior. **BQC Fixes**: * Duplicate action prevention: duplicate project scan triggers throw `ProjectScanInFlightError`. * Resource cleanup: `destroy()` clears pending startup timers and recovers a running project status to failed on shutdown. * State freshness on re-entry: fresh manager-owned project scans return without provider work unless forced. ### Task T008 - Add maintained project scan system prompt **Started**: 2026-06-10 09:30 **Completed**: 2026-06-10 09:31 **Duration**: 1 minute **Notes**: * Added a source-controlled project scan prompt with strict JSON schema rules and privacy boundaries. * Exported `projectScanEngine` through the maintained prompt index. **Files Changed**: * `apps/server/src/llm/prompts/project-scan.md` - added maintained project scan prompt. * `apps/server/src/llm/prompts/index.ts` - exported `projectScanEngine`. **BQC Fixes**: * Error information boundaries: prompt explicitly forbids secrets, absolute paths, raw prompts, command bodies, terminal output, and provider payloads. ### Task T009 - Extend llmClient for analysis/project timeout support **Started**: 2026-06-10 09:30 **Completed**: 2026-06-10 09:31 **Duration**: 1 minute **Notes**: * Added optional per-call timeout support without changing existing default timeout behavior. * Added `projectScanEngine` model selection and deterministic fallback payloads for analysis/project engines. **Files Changed**: * `apps/server/src/lib/llmClient.ts` - added `timeoutMs`, project scan model default, and schema-valid canned fallbacks. **BQC Fixes**: * External dependency resilience: long-running engines can request bounded provider timeouts and still fall back locally. * Contract alignment: canned analysis/project outputs now match the protocol-oriented parser shapes. ### Tasks T010-T012 - Implement on-demand analysis execution, parsing, and persistence **Started**: 2026-06-10 09:29 **Completed**: 2026-06-10 09:33 **Duration**: 4 minutes **Notes**: * Added sanitized analysis prompt assembly from bounded selected files. * Added provider/fallback execution through `llmClient`, protocol item normalization, enum alias handling, output caps, noise filtering, schema-valid fallback results, manager persistence, scan status transitions, cached result handling, and canonical suggestion broadcasts. **Files Changed**: * `apps/server/src/lib/onDemandAnalysisEngine.ts` - implemented analysis execution, parsing, filtering, fallback, persistence, status, and broadcasts. * `apps/server/src/lib/llmClient.ts` - added schema-valid analysis fallback output. **BQC Fixes**: * Trust boundary enforcement: provider output is parsed into protocol `AnalysisItem` entries before storage. * Error information boundaries: route and status failures use compact messages and sanitized paths only. * Concurrency safety: single-flight promise prevents concurrent analysis manager writes. ### Tasks T013-T015 - Implement project scan execution, parsing, and persistence **Started**: 2026-06-10 09:30 **Completed**: 2026-06-10 09:33 **Duration**: 3 minutes **Notes**: * Added sanitized project prompt assembly from package and directory signals. * Added provider/fallback execution through `llmClient`, 2-4 item validation, manager persistence, scan status transitions, cached result handling, canonical broadcasts, and stale startup scan scheduling. **Files Changed**: * `apps/server/src/lib/projectScanEngine.ts` - implemented project scan execution, parsing, fallback, persistence, status, and startup scheduling. * `apps/server/src/lib/llmClient.ts` - added schema-valid project scan fallback output. **BQC Fixes**: * Contract alignment: project scan output is parsed through protocol `ProjectScanItem` and `ProjectScan` contracts. * Resource cleanup: startup timer is cleared on destroy; shutdown converts active project status to failed. * Concurrency safety: single-flight promise prevents concurrent project scan manager writes. ### Tasks T016-T017 - Add analysis and project scan routes **Started**: 2026-06-10 09:32 **Completed**: 2026-06-10 09:33 **Duration**: 1 minute **Notes**: * Added root and `/api` analyze/project trigger and status handlers through the existing mounted suggestion router. * Added schema validation for scope, force, and root strings, cache-aware responses, explicit 409 conflicts, and compact failure mapping. **Files Changed**: * `apps/server/src/routes/suggestions.ts` - added analysis and project scan handlers and request parsing helpers. **BQC Fixes**: * Duplicate action prevention: duplicate engine triggers map to 409 conflict responses. * Failure path completeness: failed engine runs map to compact route failures instead of hanging. * Error information boundaries: invalid requests return field-level details without echoing request bodies. ### Task T018 - Wire analysis and project scan engines into server lifecycle **Started**: 2026-06-10 09:32 **Completed**: 2026-06-10 09:33 **Duration**: 1 minute **Notes**: * Instantiated analysis and project scan engines with server-owned manager, broadcaster, root, and logger dependencies. * Scheduled stale project scans alongside existing codebase startup scans and destroyed both new engines during shutdown. **Files Changed**: * `apps/server/src/server.ts` - added engine options, handles, route dependencies, startup scheduling, and shutdown cleanup. **BQC Fixes**: * Resource cleanup: server shutdown calls `projectScan.destroy()` and `analysis.destroy()` before manager teardown. * State freshness on re-entry: project startup scheduling only runs when cached project scan state is stale. ### Task T019 - De-list shipped routes from unsupported classification **Started**: 2026-06-10 09:32 **Completed**: 2026-06-10 09:33 **Duration**: 1 minute **Notes**: * Removed analyze/project-scan planned prefixes from unsupported route classification while leaving unrelated planned families unchanged. **Files Changed**: * `apps/server/src/lib/unsupportedRoutes.ts` - removed planned suggestion engine prefix block. **BQC Fixes**: * Contract alignment: shipped handlers and unsupported-route classification now agree. ### Task T020 - Document analyze/project route behavior and privacy **Started**: 2026-06-10 09:33 **Completed**: 2026-06-10 09:33 **Duration**: 1 minute **Notes**: * Documented analyze/project endpoints, freshness windows, cached responses, startup behavior, duplicate trigger behavior, fallback behavior, and local-only privacy limits. **Files Changed**: * `apps/server/README_server.md` - updated REST endpoint table and Quest Board manager section. **BQC Fixes**: * Contract alignment: server README now matches the shipped route set and freshness behavior. ### Task T021 - Write analysis engine tests **Started**: 2026-06-10 09:35 **Completed**: 2026-06-10 09:40 **Duration**: 5 minutes **Notes**: * Added tests for git file selection, dependency/lockfile exclusion, working-tree and deterministic fallback behavior, protocol parsing, noise filtering, manager persistence, status reporting, fresh cache handling, and single-flight duplicate protection. **Files Changed**: * `apps/server/tests/onDemandAnalysisEngine.test.ts` - added focused analysis engine coverage. **BQC Fixes**: * Contract alignment: tests assert provider output normalizes into protocol analysis item fields. * Duplicate action prevention: tests assert duplicate analysis runs throw `AnalysisInFlightError`. ### Task T022 - Write project scan engine tests **Started**: 2026-06-10 09:35 **Completed**: 2026-06-10 09:40 **Duration**: 5 minutes **Notes**: * Added tests for project scan parsing, category/effort/priority alias validation, caps, fallback behavior, manager persistence, status reporting, fresh cache handling, single-flight duplicate protection, and startup stale scan scheduling. **Files Changed**: * `apps/server/tests/projectScanEngine.test.ts` - added focused project scan engine coverage. **BQC Fixes**: * Resource cleanup: tests destroy engines and verify timer-driven startup behavior with fake timers. * Duplicate action prevention: tests assert duplicate project scans throw `ProjectScanInFlightError`. ### Task T023 - Write route and unsupported-route tests **Started**: 2026-06-10 09:36 **Completed**: 2026-06-10 09:40 **Duration**: 4 minutes **Notes**: * Extended suggestion route tests for analysis/project trigger and status routes under root and `/api`, cached responses, validation redaction, and duplicate in-flight conflicts. * Updated unsupported-route tests so shipped analyze/project-scan prefixes no longer claim planned unsupported status. **Files Changed**: * `apps/server/tests/suggestionRoutes.test.ts` - added analyze/project route coverage. * `apps/server/tests/unsupportedRoutes.test.ts` - updated shipped-route classification expectations. **BQC Fixes**: * Error information boundaries: tests assert invalid analyze/project request bodies do not echo unsafe prompt or token values. * Contract alignment: tests assert root and `/api` route behavior matches shipped route classification. ### Task T024 - Run verification and update evidence **Started**: 2026-06-10 09:39 **Completed**: 2026-06-10 09:41 **Duration**: 2 minutes **Notes**: * Ran focused server typecheck and test suite after implementation and again after formatting. * Ran Biome format/lint on touched source and test files. * Ran ASCII and CRLF checks across touched source, tests, docs, prompt, and spec artifacts. **Files Changed**: * `.spec_system/specs/phase18-session08-on-demand-analysis-and-project-scan-engines/implementation-notes.md` - added verification evidence. * `.spec_system/specs/phase18-session08-on-demand-analysis-and-project-scan-engines/tasks.md` - marked completion checklist. * `.spec_system/specs/phase18-session08-on-demand-analysis-and-project-scan-engines/IMPLEMENTATION_SUMMARY.md` - added session summary. **BQC Fixes**: * N/A - verification task only. ## Verification Evidence * `npx biome format --write apps/server/src/lib/onDemandAnalysisEngine.ts apps/server/src/lib/projectScanEngine.ts apps/server/src/lib/llmClient.ts apps/server/src/llm/prompts/index.ts apps/server/src/routes/suggestions.ts apps/server/src/server.ts apps/server/src/lib/unsupportedRoutes.ts 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. * `npx biome lint apps/server/src/lib/onDemandAnalysisEngine.ts apps/server/src/lib/projectScanEngine.ts apps/server/src/lib/llmClient.ts apps/server/src/llm/prompts/index.ts apps/server/src/routes/suggestions.ts apps/server/src/server.ts apps/server/src/lib/unsupportedRoutes.ts 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. * `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 across touched source, tests, docs, prompt, and session artifacts - passed. *** ## Session Complete Session implementation complete. Tasks: 24/24 (100%) BQC: fixes and checks applied across 17 application-code tasks. Next workflow step: `validate`. *** --- # 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-notes.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.