Codebase Audit

Overview

AutoAudit analyzes your trace graph (nodes, edges, augmentations, epistemic enrichment, modules, and atlas) to produce structured findings and optional LLM-generated reports. It is a finalize pipeline stage (stage 14 of 15, running in finalize wave 2 after deep enrichment), so it runs automatically when the project's finalize group is set to auto — and you can also re-trigger it on demand via the dashboard Audit panel, the MCP prep_audit tool, or the REST stage-run endpoint.

AutoAudit V2 transforms SourcePrep from a "passive observer" into an "active taskmaster". Findings are categorized into flat tabs (Architecture, Quality, Coverage, Tech Debt), prioritized, and include concrete actionable items. You can select findings and click "Copy AI Command" to instantly hand off the context assembly to your AI via MCP.

Quick Start

CLI

Audits are triggered via the MCP prep_audit tool, the REST API, or the dashboard's Audit panel — not a direct CLI command. To read findings from the most recent run from a terminal, use prep opportunities:

# List actionable findings from the latest audit
prep opportunities

# Filter by minimum priority
prep opportunities --priority P1

# Export as SARIF for CI ingestion
prep opportunities --format sarif

# Pipe a high-priority subset to an AI agent prompt
prep opportunities --priority P0 --format ai_prompt

What a PR-sanity audit looks like when an agent calls prep_audit mid-review.

MCP Tool

One MCP tool, prep_audit, exposes all audit functionality across Cursor, Windsurf, Claude Code, and any MCP-compatible editor. The behavior is selected via the action parameter:

Findings can also be passed in via the findings parameter to enrich external lint output (ruff, eslint, semgrep, SARIF) with structural context — see the Audit Enrichment guide.

REST API

Built-in Analyzers

AutoAudit ships with 11 analyzers. Each reads the trace graph and produces structured findings — no LLM, no side effects.

Generated Reports

When you run an audit with synthesize: true (via the MCPprep_audit tool or the REST API), an LLM generates 5 markdown documents from the findings:

• AUDIT_SUMMARY — Health grade (A–F), critical findings, top recommendations
• ARCHITECTURE_ANALYSIS — Module dependency flow, bottlenecks, boundary violations
• GAP_ANALYSIS — Misplaced concerns, duplicated logic, missing abstractions
• COMPONENT_INVENTORY — Every file with purpose, module, summary, in-degree
• TECH_DEBT_REPORT — Debt items by module with remediation roadmap

Output Location

All audit output is stored inside the project's index directory:

# Standalone mode (default):
~/.local/share/sourceprep/projects/{project-id}/audit/
  ├── findings.json            # Raw structured findings
  ├── audit_manifest.json      # Run metadata (timestamps, counts)
  ├── AUDIT_SUMMARY.md         # LLM-generated (if synthesized)
  ├── ARCHITECTURE_ANALYSIS.md
  ├── GAP_ANALYSIS.md
  ├── COMPONENT_INVENTORY.md
  └── TECH_DEBT_REPORT.md

# Embedded mode:
/path/to/project/.sourceprep/audit/
  └── (same files)

These files are served via the audit REST API (GET /projects/{id}/audit/reports, GET /projects/{id}/audit/report/{name}) and through the MCPprep_audit tool with action report, so your AI tools can retrieve them by name. (In embedded mode the .sourceprep/audit/ directory is excluded from the walker, so reports are not surfaced via prep_search.)

Settings

Audit behavior is configurable via the audit_config section inui_config.json (edit the file directly; thresholds are read at audit-run time):

Pipeline Connection

AutoAudit is a finalize pipeline stage. The connection:

1. The enrichment pipeline runs to completion and produces trace_nodes, trace_augmented, trace_epistemic, trace_modules, and atlas.json.
2. You trigger an audit (via the MCP prep_audit tool, the REST stage-run endpoint, or the dashboard Audit panel) when you want insights. The audit reads all that data and produces findings + reports.
3. If the per-project auto_config.finalize is set to auto, the audit stage runs automatically (Tier 1 + Tier 2) when deep enrichment completes, as part of the finalize group.
4. Audit reports are served via the audit REST API (GET /projects/{id}/audit/reports, GET /projects/{id}/audit/report/{name}) and through the MCP prep_audit tool with action report, so your AI tools can retrieve them by name.