> 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/phases/phase_18/session_06_codebase_issue_scanners.md).

# Session 06: Codebase Issue Scanners

**Session ID**: `phase18-session06-codebase-issue-scanners` **Package**: apps/server **Status**: Complete **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Implement the five codebase issue scanners (TODO-family comments, git status, lint, build, tests) producing typed, capped, quality-filtered Quest Board issues through the SuggestionManager.

***

## Scope

### In Scope (MVP)

* Comment scanner matching five markers (TODO, FIXME, HACK, XXX, BUG) with severity mapping (FIXME/BUG and HACK/XXX warning, TODO info)
* Quality filters: reject markers embedded in identifiers or unbalanced quotes/strings (false-positive filter) and empty-message markers
* Git status scanner surfacing dirty working-tree state as issues
* Lint scanner, build/TypeScript error scanner, and test-failure scanner mapping tool output to typed issues
* All five scanners default OFF and enabled explicitly via options
* Per-category issue cap (50) with capped counts logged, not silent
* Each issue carries type, severity, file path, line, title/message, suggested prompt, and suggested agent type
* Issues stored via manager incremental APIs with dedupe by type+filePath+line
* Scan roots restricted to `llmPrivacy`-approved paths; scanner output minimized (no raw file contents beyond the matched line context)
* Unit tests with fixture files and command output for each scanner and filter

### Out of Scope

* Full/diff/daily scan orchestration, status routes, and ignore patterns (Session 07)
* LLM-based analysis of file contents (Session 08)

***

## Prerequisites

* [x] Session 02 incremental issue APIs available
* [x] Existing codebase walker and scan-root privacy rules reviewed

***

## Deliverables

1. Five scanner modules with default-off options and severity mapping
2. False-positive and empty-message quality filters
3. Typed issues with suggested prompt and suggested agent type stored via the manager
4. Fixture-backed unit tests per scanner

***

## Success Criteria

* [x] Marker scan on a fixture tree yields correctly typed, capped, and filtered issues
* [x] Identifier-embedded and empty markers are rejected by tests
* [x] No scanner runs unless explicitly enabled in options
* [x] Server test suite passes with new coverage included

***

## Historical Evidence (EXAMPLES References)

Preserved from the 2026-06-07 parity audit (full audit in `PRD_phase_18.md` Appendix A). Evidence only; never import, copy, or transform historical code.

* `EXAMPLES/package-0.4.1/server/dist/codebaseScanEngine.js:1` - the scanner evidence:
  * Comment scan: `scanTodos`, `scanTodosInFiles`, `parseTodoOutput` matching five markers (TODO, FIXME, HACK, XXX, BUG) with severity mapping FIXME/BUG -> warning, HACK/XXX -> warning, TODO -> info.
  * Quality filters: `isLikelyFalsePositive` (rejects markers embedded in identifiers or inside unbalanced quotes/strings) and `isEmptyMessage`.
  * Cap: `maxIssuesPerCategory=50`.
  * Other scanners: `scanGitStatus` (dirty working tree), `scanLint`, `scanBuild` (build/TypeScript errors), `scanTests` (test failures).
  * All five scanner options default to `false` in the default options object and must be explicitly enabled.
  * Per-issue `suggestedAgentType` (for example `general-purpose`, `Bash`) set in `parseTodoOutput`, `scanGitStatus`, `scanLint`, `scanBuild`, and `scanTests` - the agent type best suited to fix the issue, used when spawning the fix.
* `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` - `addCodebaseIssue` dedupe key (`type`+`filePath`+`line`) that this session's scanners must feed.

## Current-Code Touchpoints (Audit Snapshot 2026-06-07)

* `apps/server/src/lib/codebaseWalker.ts:135` and `apps/server/src/routes/llm.ts:119` - current scan walks recent files and sends snippets to the LLM; it does not categorize TODO/FIXME into Quest Board issues.
* `apps/server/src/lib/codebaseWalker.ts:84` - fixed ignored directories today (configurable ignore patterns land in Session 07).
* `apps/server/src/lib/llmPrivacy.ts:89` - scan-root privacy approval that every scanner in this session must respect.


---

# 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/phases/phase_18/session_06_codebase_issue_scanners.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.