> 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-session06-codebase-issue-scanners/implementation-notes.md). # Implementation Notes **Session ID**: `phase18-session06-codebase-issue-scanners` **Package**: apps/server **Started**: 2026-06-10 01:41 **Last Updated**: 2026-06-10 01:52 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 23 / 23 | | 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 * [x] Package context resolved to `apps/server` *** ### Task T001 - Verify Session 05 summary, noise-filter, and manager issue APIs **Started**: 2026-06-10 01:41 **Completed**: 2026-06-10 01:41 **Duration**: 1 minute **Notes**: * Confirmed `SuggestionManager` owns codebase issues and exposes `addCodebaseIssue`, `getIssuesByType`, `getIssuesBySeverity`, dismissal, summary, snapshot, and persistence APIs. * Confirmed manager ingestion normalizes via `parseCodebaseIssue`, dedupes by `type:filePath:line`, caps through `capSuggestionCodebaseIssuesByType`, and already coexists with session summaries and analysis filtering. **Files Changed**: * `.spec_system/specs/phase18-session06-codebase-issue-scanners/implementation-notes.md` - recorded setup verification. *** ### Task T002 - Verify approved scan-root and safe relative-path rules **Started**: 2026-06-10 01:41 **Completed**: 2026-06-10 01:41 **Duration**: 1 minute **Notes**: * Confirmed `resolveApprovedScanRoot` approves the current working directory plus `FACTIONOS_SCAN_ROOTS`, rejects missing, non-directory, filesystem-root, and unapproved roots, and returns compact failure reasons. * Confirmed existing privacy helpers redact absolute paths and sanitize transferred text. **Files Changed**: * `.spec_system/specs/phase18-session06-codebase-issue-scanners/implementation-notes.md` - recorded setup verification. *** ### Task T003 - Verify protocol issue enums, severity values, validation, and caps **Started**: 2026-06-10 01:41 **Completed**: 2026-06-10 01:41 **Duration**: 1 minute **Notes**: * Confirmed protocol issue types include `todo`, `fixme`, `hack`, `xxx`, `bug`, `git_status`, `lint`, `build`, and `test`. * Confirmed severities are `info`, `warning`, and `error`, relative path validation rejects unsafe paths, and `SUGGESTION_ISSUES_PER_CATEGORY_CAP` is 50. **Files Changed**: * `.spec_system/specs/phase18-session06-codebase-issue-scanners/implementation-notes.md` - recorded setup verification. *** ### Task T004 - Create scanner option, result, cap, logger, and command-runner types **Started**: 2026-06-10 01:41 **Completed**: 2026-06-10 01:47 **Duration**: 6 minutes **Notes**: * Added scanner option, result, cap report, failure, logger, command spec, command output, and injectable command-runner types. * Added default scanner flags with `todos`, `gitStatus`, `lint`, `build`, and `tests` all disabled by default. * Added a bounded `execFile`-based default command runner with timeout, max-output, missing-command, and truncation metadata. **Files Changed**: * `apps/server/src/lib/codebaseIssueScanners.ts` - added scanner boundary types and default-off option helpers. **BQC Fixes**: * External dependency resilience: command execution is injectable and bounded by timeout and max-output values. * Failure path completeness: command failures are represented as compact scanner failures instead of raw logs. *** ### Task T005 - Create codebase issue scanner fixtures **Started**: 2026-06-10 01:41 **Completed**: 2026-06-10 01:47 **Duration**: 6 minutes **Notes**: * Added marker fixture source strings for accepted TODO-family comments and rejected false positives. * Added text fixtures for git status, lint, build/typecheck, and test-runner output. **Files Changed**: * `apps/server/tests/fixtures/codebase-issue-scanners/marker-fixtures.ts` - added marker source fixtures. * `apps/server/tests/fixtures/codebase-issue-scanners/git-status.txt` - added git status fixture output. * `apps/server/tests/fixtures/codebase-issue-scanners/lint-output.txt` - added lint fixture output. * `apps/server/tests/fixtures/codebase-issue-scanners/build-output.txt` - added build/typecheck fixture output. * `apps/server/tests/fixtures/codebase-issue-scanners/test-output.txt` - added test failure fixture output. *** ### Task T006 - Create safe codebase issue factory **Started**: 2026-06-10 01:47 **Completed**: 2026-06-10 01:47 **Duration**: 1 minute **Notes**: * Added `createCodebaseIssue` to normalize safe relative paths, compact and redact text fields, generate safe deterministic IDs, and validate through `parseCodebaseIssue`. * The factory accepts only bounded issue fields and never stores scanned file contents or raw command output. **Files Changed**: * `apps/server/src/lib/codebaseIssueScanners.ts` - added issue factory and path/text normalization helpers. **BQC Fixes**: * Trust boundary enforcement: issue construction validates through the protocol parser before results are returned or ingested. * Error information boundaries: issue messages and prompts are compacted and redacted. *** ### Task T007 - Create TODO-family marker parsing and false-positive filters **Started**: 2026-06-10 01:47 **Completed**: 2026-06-10 01:47 **Duration**: 1 minute **Notes**: * Added pure marker parsing for TODO, FIXME, HACK, XXX, and BUG comments. * Rejected embedded identifiers, string-literal markers, likely unbalanced string markers, and empty marker messages before issue creation. **Files Changed**: * `apps/server/src/lib/codebaseIssueScanners.ts` - added marker parsing and comment extraction helpers. **BQC Fixes**: * Contract alignment: marker type and severity mapping match protocol issue enums. *** ### Task T008 - Create approved-root file scan adapter **Started**: 2026-06-10 01:47 **Completed**: 2026-06-10 01:47 **Duration**: 1 minute **Notes**: * Added approved-root source loading that walks only under the resolved scan root, skips ignored directories and file patterns, caps files and bytes, and sorts by safe relative path. * Added explicit `loaded`, `empty`, and `error` result states with compact scan failures. **Files Changed**: * `apps/server/src/lib/codebaseIssueScanners.ts` - added approved-root file loading adapter. **BQC Fixes**: * Resource cleanup: file reads are synchronous scoped reads with no retained handles. * Failure path completeness: unreadable scans return compact failures. *** ### Task T009 - Create pure command-output parsers **Started**: 2026-06-10 01:47 **Completed**: 2026-06-10 01:47 **Duration**: 1 minute **Notes**: * Added pure parsers for porcelain git status, lint diagnostics, TypeScript build/typecheck diagnostics, and Vitest-style test failures. * Parsers extract bounded file, line, title, message, prompt, severity, and agent fields while discarding full raw logs. **Files Changed**: * `apps/server/src/lib/codebaseIssueScanners.ts` - added command-output parsers and diagnostic parsing helpers. **BQC Fixes**: * Error information boundaries: parser output excludes absolute paths, secrets, and full command logs. *** ### Task T010 - Implement TODO-family scanning **Started**: 2026-06-10 01:47 **Completed**: 2026-06-10 01:50 **Duration**: 3 minutes **Notes**: * Added approved-root TODO-family scanning over bounded source files with TODO mapped to `info` and FIXME, HACK, XXX, and BUG mapped to `warning`. * Applied per-type caps before returning scanner output. **Files Changed**: * `apps/server/src/lib/codebaseIssueScanners.ts` - added TODO-family scanner. **BQC Fixes**: * Contract alignment: scanner issues are protocol-validated and sorted deterministically. *** ### Task T011 - Implement git status scanner **Started**: 2026-06-10 01:47 **Completed**: 2026-06-10 01:50 **Duration**: 3 minutes **Notes**: * Added git status parser and command-backed scanner using injected command execution. * Added timeout, missing-command, truncated-output, and unparseable nonzero-exit failure mapping. **Files Changed**: * `apps/server/src/lib/codebaseIssueScanners.ts` - added git status parser and scanner execution path. **BQC Fixes**: * External dependency resilience: command-backed scans use timeouts, bounded output, and caller-visible failures. *** ### Task T012 - Implement lint scanner **Started**: 2026-06-10 01:47 **Completed**: 2026-06-10 01:50 **Duration**: 3 minutes **Notes**: * Added lint diagnostic parsing for file, line, severity, and bounded message fields. * Lint scanner uses the shared command-backed execution path and compact nonzero-exit handling. **Files Changed**: * `apps/server/src/lib/codebaseIssueScanners.ts` - added lint parser and scanner execution path. **BQC Fixes**: * Error information boundaries: raw lint logs are discarded after extracting bounded issue fields. *** ### Task T013 - Implement build/typecheck scanner **Started**: 2026-06-10 01:47 **Completed**: 2026-06-10 01:50 **Duration**: 3 minutes **Notes**: * Added build/typecheck diagnostic parsing for TypeScript parenthesized and colon-style diagnostics. * Build scanner uses the shared timeout, max-output, truncation, and nonzero-exit handling. **Files Changed**: * `apps/server/src/lib/codebaseIssueScanners.ts` - added build/typecheck parser and scanner execution path. **BQC Fixes**: * Failure path completeness: unparseable command failures surface as compact scanner failures. *** ### Task T014 - Implement test-failure scanner **Started**: 2026-06-10 01:47 **Completed**: 2026-06-10 01:50 **Duration**: 3 minutes **Notes**: * Added Vitest/Jest-style test failure parsing for failed test files and bounded failure messages. * Test scanner uses the shared command-backed execution path and compact failure mapping. **Files Changed**: * `apps/server/src/lib/codebaseIssueScanners.ts` - added test-output parser and scanner execution path. **BQC Fixes**: * Error information boundaries: test output is reduced to file path and compact failure title/message. *** ### Task T015 - Implement aggregate scan runner **Started**: 2026-06-10 01:47 **Completed**: 2026-06-10 01:50 **Duration**: 3 minutes **Notes**: * Added `scanCodebaseIssues` aggregate runner that returns immediately with no scans or commands when every scanner option is disabled. * Enabled scanners share approved-root validation, deterministic ordering, cap reporting, compact failures, and optional compact logging. **Files Changed**: * `apps/server/src/lib/codebaseIssueScanners.ts` - added aggregate scan runner. **BQC Fixes**: * State freshness on re-entry: each scan builds a fresh result object and does not reuse prior scanner state. * Failure path completeness: rejected roots and capped issues are returned explicitly. *** ### Task T016 - Implement manager ingestion helper **Started**: 2026-06-10 01:47 **Completed**: 2026-06-10 01:50 **Duration**: 3 minutes **Notes**: * Added `ingestCodebaseIssues` and `scanAndIngestCodebaseIssues` helpers that write only through `SuggestionManager.addCodebaseIssue`. * Ingestion reports attempted, added, existing, and stored issues using the manager dedupe key behavior. **Files Changed**: * `apps/server/src/lib/codebaseIssueScanners.ts` - added manager ingestion helpers. **BQC Fixes**: * Duplicate action prevention: ingestion relies on manager-owned in-flight mutation and dedupe behavior instead of writing state directly. *** ### Task T019 - Write marker scanner tests **Started**: 2026-06-10 01:50 **Completed**: 2026-06-10 01:51 **Duration**: 1 minute **Notes**: * Added tests for accepted TODO-family markers, severity mapping, false positives, empty marker messages, safe relative paths, and deterministic ordering. * Focused scanner test run passed. **Files Changed**: * `apps/server/tests/codebaseIssueScanners.test.ts` - added marker scanner coverage. *** ### Task T020 - Write command parser tests **Started**: 2026-06-10 01:50 **Completed**: 2026-06-10 01:51 **Duration**: 1 minute **Notes**: * Added parser coverage for git status, lint, build/typecheck, and test fixture outputs. * Added command-backed failure coverage for timeout, missing command, truncated output, and unparseable nonzero output. **Files Changed**: * `apps/server/tests/codebaseIssueScanners.test.ts` - added command parser and failure mapping coverage. *** ### Task T021 - Write default-off, enablement, root, and cap tests **Started**: 2026-06-10 01:50 **Completed**: 2026-06-10 01:51 **Duration**: 1 minute **Notes**: * Added default-off coverage proving no root validation, filesystem scan, or command call runs when all scanner options are disabled. * Added explicit-enable, rejected-root, approved-root, per-category cap, and capped-count tests. **Files Changed**: * `apps/server/tests/codebaseIssueScanners.test.ts` - added aggregate scanner behavior coverage. *** ### Task T022 - Write manager ingestion tests **Started**: 2026-06-10 01:50 **Completed**: 2026-06-10 01:51 **Duration**: 1 minute **Notes**: * Added tests proving scanner issues ingest through `SuggestionManager.addCodebaseIssue`, manager dedupe collapses repeated type/path/line entries, and stored issue text is redacted and path-safe. **Files Changed**: * `apps/server/tests/codebaseIssueScanners.test.ts` - added manager ingestion coverage. **BQC Fixes**: * Duplicate action prevention: tests verify duplicate scanner issues do not create duplicate manager state. * Error information boundaries: tests verify secret/path redaction before persistence. *** ### Task T017 - Document scanner behavior and route ownership **Started**: 2026-06-10 01:51 **Completed**: 2026-06-10 01:52 **Duration**: 1 minute **Notes**: * Documented the default-off scanner layer, approved-root boundary, minimized issue output, no provider transfer, manager-only ingestion, and later Session 07 route ownership. **Files Changed**: * `apps/server/README_server.md` - added Quest Board scanner documentation. *** ### Task T018 - Verify planned scan and analysis routes remain unsupported **Started**: 2026-06-10 01:51 **Completed**: 2026-06-10 01:52 **Duration**: 1 minute **Notes**: * Confirmed unsupported route classification already keeps suggestion analyze, scan, and project-scan routes planned. * Added direct `/api/suggestions/scan` route coverage and reran the unsupported route test file successfully. **Files Changed**: * `apps/server/tests/unsupportedRoutes.test.ts` - added direct `/api/suggestions/scan` planned unsupported coverage. **BQC Fixes**: * Contract alignment: planned scan route coverage confirms Session 06 did not ship orchestration routes. *** ### Task T023 - Run focused tests, typecheck, and ASCII/LF validation **Started**: 2026-06-10 01:52 **Completed**: 2026-06-10 01:52 **Duration**: 1 minute **Notes**: * Ran focused scanner and unsupported route tests after formatting. * Ran server package typecheck. * Ran ASCII and CRLF validation across touched session artifacts, scanner source, tests, fixtures, and documentation. **Files Changed**: * `.spec_system/specs/phase18-session06-codebase-issue-scanners/tasks.md` - marked final task and completion checklist done. * `.spec_system/specs/phase18-session06-codebase-issue-scanners/implementation-notes.md` - recorded final validation results. *** ## Validation Commands * `npx biome format --write apps/server/src/lib/codebaseIssueScanners.ts apps/server/tests/codebaseIssueScanners.test.ts apps/server/tests/fixtures/codebase-issue-scanners/marker-fixtures.ts apps/server/tests/unsupportedRoutes.test.ts apps/server/README_server.md` * `npm test -- apps/server/tests/codebaseIssueScanners.test.ts apps/server/tests/unsupportedRoutes.test.ts` * `npm --workspace apps/server run typecheck` * `LC_ALL=C rg -n --pcre2 '[^\x00-\x7F]' ` and `rg -n $'\r' ` ## Session Summary * Added default-off server codebase issue scanners for TODO-family comments, git status, lint, build/typecheck, and test failures. * Added safe issue creation, approved-root scanning, bounded command execution, compact failure/cap reports, and manager-only ingestion through `SuggestionManager.addCodebaseIssue`. * Added scanner fixtures and focused Vitest coverage for parser behavior, privacy boundaries, caps, root approval, failure paths, and manager dedupe. * Documented scanner privacy and route ownership boundaries, and confirmed suggestion scan/analyze routes remain planned unsupported until Session 07. *** --- # 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-session06-codebase-issue-scanners/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.