> 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/spec.md). # Session Specification **Session ID**: `phase18-session06-codebase-issue-scanners` **Phase**: 18 - Quest Board Suggestion Parity **Status**: Complete **Created**: 2026-06-10 **Package**: apps/server **Package Stack**: TypeScript *** ## 1. Session Overview This session adds the server-side codebase issue scanner layer for the Phase 18 Quest Board. Sessions 01-05 already delivered shared suggestion contracts, server-owned persistence, routes and WebSocket snapshots, automatic idle generation, session follow-ups, and analysis noise filtering. The next gap is turning local codebase signals into typed `CodebaseIssue` cards owned by the `SuggestionManager`. The scanners stay server-local and default off. They produce issues only when an explicit caller enables a scanner option, and they write through the existing manager API so dedupe, caps, persistence, dismissal, and snapshots do not drift. This session creates scanner logic and tests only; orchestration, status routes, ignore-pattern configuration, and web rendering remain owned by later sessions. The implementation must preserve the local-first trust boundary. Scan roots must use the existing `llmPrivacy` approval rules, scanner output must be minimized to safe relative paths plus bounded messages, and command-output parsing must avoid storing raw full logs, secrets, absolute paths, or file contents. *** ## 2. Objectives 1. Implement default-off scanners for TODO-family comments, git status, lint, build/typecheck output, and test failures. 2. Normalize scanner findings into protocol-valid `CodebaseIssue` objects with type, severity, path, line, title, message, suggested prompt, and suggested agent type. 3. Store issues through `SuggestionManager.addCodebaseIssue` with deterministic dedupe by type, file path, and line. 4. Enforce scan-root approval, per-category caps, deterministic ordering, and compact cap/failure reporting. 5. Cover marker parsing, false-positive filtering, command-output parsing, default-off behavior, manager ingestion, and privacy boundaries with focused Vitest tests. *** ## 3. Prerequisites ### Required Sessions * [x] `phase18-session01-protocol-suggestion-contract-parity` - provides `CodebaseIssue`, issue type and severity enums, caps, path validation, and summary contracts. * [x] `phase18-session02-server-suggestion-manager-and-persistence` - provides server-owned persisted Quest Board state and `SuggestionManager.addCodebaseIssue`. * [x] `phase18-session03-suggestion-routes-and-websocket-parity` - provides canonical suggestion snapshots and issue dismissal behavior. * [x] `phase18-session04-idle-lifecycle-engine-parity` - establishes privacy-bounded context and fallback patterns reused by server engines. * [x] `phase18-session05-session-summary-engine-and-noise-filtering` - provides the latest manager filtering pattern and confirms session summary state coexists with codebase issue state. ### Required Tools/Knowledge * Node 26.2.0 or newer with npm workspaces. * TypeScript server package conventions and Vitest tests. * Existing `SuggestionManager`, `codebaseWalker`, `llmPrivacy`, protocol issue parsers, and package-local logging conventions. * Phase 18 PRD Appendix A as traceability evidence only; do not import, copy, or transform historical code. ### Environment Requirements * Work from the repository root. * Use package-relative monorepo paths from the repo root. * Keep all generated and edited files ASCII-only with Unix LF line endings. *** ## 4. Scope ### In Scope (MVP) * Server exposes a reusable codebase scanner module with explicit enable flags for `todos`, `gitStatus`, `lint`, `build`, and `tests`, all defaulting to disabled. * Comment scanning matches TODO, FIXME, HACK, XXX, and BUG markers, maps TODO to `info`, FIXME/BUG to `warning`, and HACK/XXX to `warning`. * Comment scanning rejects markers embedded in identifiers, markers inside likely unbalanced string literals, and markers with empty messages. * Git status scanning converts dirty working-tree entries into bounded typed issues. * Lint, build/typecheck, and test scanners parse bounded command output into typed issues without storing raw full logs. * Command-backed scanners use injected command execution with timeout, bounded output, nonzero-exit handling, and compact error mapping. * Every scanner uses approved scan roots from `resolveApprovedScanRoot` and stores safe relative paths only. * Per-category caps of 50 issues are enforced before manager ingestion, and capped counts are returned and logged compactly instead of being silent. * Issues include type, severity, file path, optional line, title, message, suggested prompt, suggested agent type, and created-at timestamp. * Scanner output is stored through `SuggestionManager.addCodebaseIssue`; no scanner writes suggestion state directly. * Unit tests cover fixture source files and fixture command outputs for every scanner and filter path. ### Out of Scope (Deferred) * Full, diff, daily, and stale-scan orchestration - *Reason: Session 07 owns orchestration and scan status.* * Quest ignore patterns and `.agentcraftignore` support - *Reason: Session 07 owns configurable ignore behavior.* * `/suggestions/scan` routes and route status handlers - *Reason: Session 07 owns route wiring.* * On-demand analysis and project scan engines - *Reason: Session 08 owns LLM-backed analysis and project scan behavior.* * Web rendering of typed Quest Board cards - *Reason: Session 09 owns web display.* * Quest actions and keyboard shortcuts - *Reason: Session 10 owns interactions.* * Historical telemetry and entitlement gates - *Reason: Phase 18 explicitly excludes analytics capture and entitlement gating.* *** ## 5. Technical Approach ### Architecture Create `apps/server/src/lib/codebaseIssueScanners.ts` as the scanner boundary. It should define scanner options, result summaries, cap metadata, command runner interfaces, safe issue factories, pure marker filters, pure command-output parsers, and a scanner entry point that can either return issues or ingest them into `SuggestionManager`. Reuse `apps/server/src/lib/codebaseWalker.ts` for bounded source walking where possible, but do not depend on its file-content truncation for privacy. The comment scanner should read only approved source files, inspect line-level content, and keep the stored issue message limited to the marker message and a safe relative path. Use deterministic ordering by type, file path, and line so tests and snapshots are stable. Command-backed scanners should use an injectable command runner. Production defaults may execute bounded local commands from an approved root, but tests must be able to provide fixture output without invoking git, npm, lint, build, or test tools. Each command parser should accept stdout, stderr, exit code, and command metadata, then return typed issues or compact failure summaries. ### Design Patterns * Default-off scanner options: no local command or filesystem scan runs unless explicitly enabled. * Pure parser functions before side effects: command and marker parsing stay deterministic and fixture-testable. * Manager-owned state: issues enter Quest Board state only through `SuggestionManager.addCodebaseIssue`. * Bounded external calls: command execution has timeout, max-output, and explicit nonzero-exit mapping. * Privacy-first normalization: absolute paths, full logs, and file contents are not persisted or emitted. ### Technology Stack * TypeScript in `apps/server`. * Existing Node `fs`, `path`, and `child_process` APIs; no new dependencies. * Existing `@factionos/protocol` suggestion issue validators and caps. * Existing `llmPrivacy` approved scan-root helpers. * Vitest server tests with temporary directories and fixture command output. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/server/src/lib/codebaseIssueScanners.ts` | Default-off scanner options, safe issue factories, comment marker scanner, command output parsers, command-runner boundary, caps, and manager ingestion | \~520 | | `apps/server/tests/codebaseIssueScanners.test.ts` | Unit tests for scanner options, marker parsing, false positives, command output parsing, caps, privacy, and manager ingestion | \~520 | | `apps/server/tests/fixtures/codebase-issue-scanners/marker-fixtures.ts` | Source fixture with accepted and rejected TODO-family markers | \~80 | | `apps/server/tests/fixtures/codebase-issue-scanners/git-status.txt` | Fixture output for dirty git status parsing | \~20 | | `apps/server/tests/fixtures/codebase-issue-scanners/lint-output.txt` | Fixture output for lint issue parsing | \~40 | | `apps/server/tests/fixtures/codebase-issue-scanners/build-output.txt` | Fixture output for build/typecheck issue parsing | \~40 | | `apps/server/tests/fixtures/codebase-issue-scanners/test-output.txt` | Fixture output for test failure parsing | \~40 | ### Files to Modify | File | Changes | Est. Lines | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------- | | `apps/server/README_server.md` | Document default-off scanner layer, privacy boundaries, and later Session 07 route/orchestration ownership | \~35 | | `apps/server/tests/suggestionManager.test.ts` | Extend issue cap and dedupe coverage if the scanner needs additional manager assertions | \~40 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Scanner options default to all scanners disabled and produce no issues or command invocations unless explicitly enabled. * [ ] TODO, FIXME, HACK, XXX, and BUG markers become typed issues with the required severity mapping. * [ ] Identifier-embedded markers, likely string-literal false positives, and empty marker messages are rejected. * [ ] Git status, lint, build/typecheck, and test fixture output map to typed issues with bounded messages and suggested prompts. * [ ] Scan roots must be approved by `llmPrivacy`; rejected roots produce compact failures without scanning. * [ ] Per-category issue caps stop at 50 and report capped counts. * [ ] Manager ingestion dedupes by issue type, file path, and line through `SuggestionManager.addCodebaseIssue`. ### Testing Requirements * [ ] Unit tests written and passing for marker scanning and false-positive filtering. * [ ] Unit tests written and passing for git, lint, build/typecheck, and test output parsers. * [ ] Unit tests written and passing for default-off behavior, scan-root approval, caps, and manager ingestion. * [ ] Focused server tests pass for scanner and manager coverage. ### Non-Functional Requirements * [ ] Scanner output stores safe relative paths only; no raw absolute paths, secrets, full command logs, file contents, prompts, or transcript content are persisted. * [ ] Command-backed scanners use timeouts, bounded output, and explicit failure mapping. * [ ] No new runtime dependency is introduced. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `npm --workspace apps/server run typecheck` passes. *** ## 8. Implementation Notes ### Key Considerations * Session 06 should not add or enable `/suggestions/scan` routes. Route and orchestration ownership belongs to Session 07. * Do not bypass protocol parsing. Construct candidate issues and pass them through `parseCodebaseIssue` or manager normalization before they can be returned or stored. * Avoid raw command-output persistence. Parsers should extract bounded file, line, title, and message fields and discard the rest. * Keep cap metadata visible in the scanner result so large repositories do not silently drop findings. ### Potential Challenges * Command output varies by tool: Keep parsers conservative and fixture-backed; unmapped output should produce compact scanner failures rather than noisy generic issues. * False-positive TODO markers are easy to overfit: Cover embedded identifiers, empty markers, and quoted text, but avoid trying to parse every language grammar in this session. * Large repos can be noisy: Enforce default-off options, per-category caps, deterministic ordering, and approved roots. ### Relevant Considerations * \[P17-apps/server] **Manager-owned persistence and cleanup**: Scanners feed `SuggestionManager`; they do not own persistence or snapshot emission. * \[P03-apps/server] **Local server boundary must stay conservative**: Scanner roots, command execution, output size, and failures must be bounded. * \[P07] **Redaction is boundary-specific**: Scanner output must minimize paths and logs before storage. * \[P01-apps/server] **Anthropic transfer is two-level opt-in**: This session does not call providers; later analysis engines must keep the existing LLM boundary. * \[P03] **Stable docs are the current contract**: `EXAMPLES/` is evidence only; no historical code is imported. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Default-off scanners accidentally executing local commands. * Scanner output leaking absolute paths, secrets, or raw command logs. * Large scans producing unbounded or nondeterministic Quest Board state. *** ## 9. Testing Strategy ### Unit Tests * Test marker scanner acceptance for TODO, FIXME, HACK, XXX, and BUG with expected severity, type, line, message, suggested prompt, and agent type. * Test false-positive rejection for embedded identifiers, likely string literal matches, and empty marker messages. * Test git status, lint, build/typecheck, and test parsers using fixture command output. * Test default-off options and injected command runner call counts. * Test scan-root rejection and approved-root relative path output. * Test per-category cap reporting. ### Integration Tests * Test manager ingestion with `SuggestionManager.addCodebaseIssue`, including dedupe by type, file path, and line. * Extend existing manager tests only if scanner behavior needs extra assertions beyond the scanner test file. ### Manual Testing * Run a focused scanner test file: `npx vitest run apps/server/tests/codebaseIssueScanners.test.ts`. * Run server typecheck: `npm --workspace apps/server run typecheck`. * Run ASCII/LF validation for the new session artifacts and touched server files. ### Edge Cases * Empty scan root or unapproved scan root. * Root with no enabled scanner options. * Marker at beginning of line, after a comment prefix, and after code. * Marker embedded in an identifier such as `methodTODOValue`. * Marker text with no actionable message. * Command timeout, missing command, nonzero exit, stdout-only output, stderr-only output, and oversized output. * Duplicate issues from repeated scanner runs. *** ## 10. Dependencies ### External Libraries * None. ### Other Sessions * **Depends on**: Sessions 01-05 in Phase 18. * **Depended by**: Session 07 scan orchestration and ignore patterns, Session 09 typed web cards, and Session 11 validation documentation. *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # 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/spec.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.