sacco-codebase-audit

Codebase Audit Engine

Dispatches parallel audit agents across concern areas, collects structured findings, and produces a prioritized remediation plan.

When to Use

• Pre-production readiness review
• Post-phase quality gate (between major phase groups)
• Security audit before deployment
• Architecture review after significant changes
• Performance assessment before scaling
• Engineering quality assessment for new codebases

Audit Scopes

Select one or more scopes. Each scope runs as a parallel agent.

Scope	What It Checks
security	OWASP top 10, auth/authz, secrets exposure, injection vectors, dependency vulnerabilities
architecture	Layering violations, circular dependencies, coupling, separation of concerns, API design
performance	N+1 queries, missing indexes, unbounded collections, hot paths, memory leaks, cache strategy
engineering	Error handling, logging, testing coverage, naming, dead code, code duplication, type safety
data	Schema design, migration safety, data integrity, backup/recovery, temporal consistency
operations	Observability, health checks, graceful shutdown, configuration management, deployment safety

Finding Format

Every finding follows this exact structure:

### Finding <scope>-<number>: <title>

- **Severity:** Critical | High | Medium | Low | Info
- **File:** `path/to/file.rs:123`
- **Description:** What the problem is, with evidence.
- **Impact:** What can go wrong if this is not fixed.
- **Recommendation:** Specific fix with code example if applicable.

Severity Definitions

Severity	Definition	SLA
Critical	Data loss, security breach, or system down risk. Blocks deployment.	Fix before merge
High	Significant bug, performance degradation, or architectural violation.	Fix this sprint
Medium	Code quality issue, missing edge case, or maintainability concern.	Fix next sprint
Low	Style issue, minor optimization, or documentation gap.	Backlog
Info	Observation, suggestion, or positive callout.	Optional

Execution Protocol

1. Scope Selection

Ask the user which scopes to audit, or default to all if "full audit" is requested.

2. Agent Dispatch

Launch one agent per scope in parallel. Each agent:

• Reads all relevant files for its scope
• Produces findings in the standard format
• Numbers findings sequentially within its scope (e.g., security-1, security-2)
• Does NOT fix anything — audit only

Agent prompt template:

You are auditing this codebase for {scope} concerns.
Read all relevant files. For each issue found, produce a finding in this exact format:
[finding format from above]
Be thorough. Check every file. Do not skip edge cases.
Do not suggest fixes that introduce new problems.
Number findings as {scope}-1, {scope}-2, etc.
Return ONLY findings, no preamble.

3. Findings Collection

After all agents complete:

1. Collect all findings into a single docs/audit-report.md
2. Sort by severity (Critical first, then High, etc.)
3. Add a summary table at the top:

# Audit Report — <date>

## Summary

| Severity | Count |
|----------|-------|
| Critical | 2 |
| High | 5 |
| Medium | 8 |
| Low | 3 |
| Info | 1 |

## Critical Findings
...
## High Findings
...

4. Remediation Plan

Produce a docs/remediation-plan.md:

• Group findings by fix effort (quick wins vs. structural changes)
• Order within groups by severity
• For each finding, estimate: trivial / small / medium / large
• Mark dependencies between findings (e.g., "fix arch-3 before perf-2")

5. Verification Pass

After remediation:

• Re-run the audit for the affected scopes
• Verify each finding is addressed
• Update the audit report with resolution status

Rules

• Audit agents are READ-ONLY. They never modify code.
• Findings must reference specific file:line, not vague descriptions.
• Do not pad findings. If a scope is clean, say so.
• The user reviews findings before any remediation begins.
• Re-audit after fixes to confirm resolution.

Integration

• With sacco-phased-execution: Run between major phase groups as a quality gate
• As a milestone gate: Run before shipping, at defined project milestones
• As structured self-critique: The audit is the systematic version of reviewing your own work