oc-code-auditor

# Code Auditor

**On first invocation, read `references/orchestrator.md` and follow its welcome protocol.**

Tri-agent code quality system: Auditor finds problems → Fixer proposes remediations →
Verifier confirms the fixes actually solve the findings (not just cosmetic reshuffles).

The Auditor-only mode (`/oc-audit`) runs a one-pass sweep and produces a findings report.
The full harness (`/oc-audit fix-all`) chains all three agents for find → fix → verify.

## /oc-audit — Command Reference

```
CODE AUDITOR COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  SWEEP MODES
  /oc-audit full            Full codebase sweep — all categories
  /oc-audit security        Security-focused (auth, injection, secrets, CORS)
  /oc-audit perf            Performance (N+1, bundle, caching, queries)
  /oc-audit quality         Code quality (dead code, complexity, patterns)
  /oc-audit ux              UX/accessibility (a11y, states, consistency, responsive)
  /oc-audit pre-deploy      Pre-deployment gate (security + perf + config)
  /oc-audit file [path]     Audit specific file(s)
  /oc-audit diff            Audit git diff or staged changes

  TRI-AGENT HARNESS
  /oc-audit fix-all         Run full Auditor → Fixer → Verifier loop
  /oc-audit fix <id>        Fix a single finding with verification
  /oc-audit verify          Re-run Verifier on previous fixes

  BOOTSTRAP
  /oc-audit test-bootstrap  Generate test suite for untested codebase

  UTILITIES
  /oc-audit report          Regenerate findings report from last audit
  /checkpoint            Show checkpoint status

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Type any command to begin. /oc-audit to see this again.
```

---

## Tri-Agent Architecture

```
CODEBASE
    │
    ▼
┌──────────┐
│ AUDITOR  │  Sweeps for problems
│          │  Output: findings report with severity + location
└────┬─────┘
     │
     ▼ (findings)
┌──────────┐
│  FIXER   │  Proposes concrete code changes per finding
│          │  Output: diffs/patches per finding
└────┬─────┘
     │
     ▼ (fixes)
┌──────────┐
│ VERIFIER │  Confirms each fix addresses the finding
│          │  Cannot see Fixer's reasoning — only the diff and original finding
│          │  Output: verified/rejected per fix
└──────────┘
```

### Why Three Agents?

1. **Auditor bias**: A single agent that finds AND fixes tends to minimize findings
   it can't easily fix, and over-report findings it already knows the fix for.
   Separating Auditor from Fixer keeps the audit honest.

2. **Fix theater**: When asked to "fix this code," LLMs commonly restructure the
   code cosmetically without actually solving the underlying problem. A separate
   Verifier that re-reads the original finding and the diff catches this — it asks
   "does this diff actually prevent the vulnerability / fix the bug / solve the
   performance issue?" without being influenced by the Fixer's explanation.

3. **Scope creep**: A fixer will "improve" adjacent code while fixing a finding,
   introducing unreviewed changes. The Verifier flags scope creep: "This diff
   changes 40 lines but the finding was about 3 lines. The extra changes need
   their own review."

---

## Phase 1: Auditor Agent

The Auditor sweeps the codebase and produces findings. This is a read-only agent —
it never modifies code.

### Category Sweeps

Run each applicable category. Skip categories that don't apply (e.g., skip UX for
a pure API project).

#### 1a. Security Sweep

Read `references/security-checklist.md` for the full checklist.

| Check | Severity |
|---|---|
| Hardcoded secrets (API keys, tokens, passwords in source) | CRITICAL |
| SQL injection (string concatenation in queries) | CRITICAL |
| Auth bypass (missing middleware on protected routes) | CRITICAL |
| XSS vectors (unescaped user input in HTML/JSX) | HIGH |
| CORS misconfiguration (wildcard with credentials) | HIGH |
| Missing rate limiting on auth endpoints | HIGH |
| Vulnerable dependencies (known CVEs) | MEDIUM-HIGH |
| Missing input validation | MEDIUM |

#### 1b. Performance Sweep

| Check | Severity |
|---|---|
| N+1 queries (DB call inside loop) | HIGH |
| Missing indexes (frequent WHERE columns, no index) | MEDIUM |
| Bundle bloat (importing entire library for one function) | MEDIUM |
| Synchronous blocking in async context | HIGH |
| Unbounded list queries (no pagination) | MEDIUM |

#### 1c. Code Quality Sweep

| Check | Severity |
|---|---|
| Dead code (unused exports, unreachable branches) | LOW |
| Complexity hotspots (functions > 50 lines, cyclomatic > 10) | MEDIUM |
| Missing error handling (bare catch, swallowed errors) | MEDIUM |
| Type safety gaps (`any` types, missing null checks) | MEDIUM |
| Duplication (copy-pasted logic) | MEDIUM |
| TODO/FIXME/HACK markers | LOW |

#### 1d. Configuration & DevOps Sweep

| Check | Severity |
|---|---|
| Missing .env.example | MEDIUM |
| No .gitignore or missing entries | HIGH |
| No type checking (TS without strict mode) | MEDIUM |
| Missing CI/CD | MEDIUM |
| Stale dependencies | LOW |

#### 1e. UX & Accessibility Sweep

Read `references/ux-audit-checklist.md` for the full checklist.

| Check | Severity |
|---|---|
| Color contrast below 4.5:1 | HIGH |
| Missing form labels | HIGH |
| Div buttons (non-semantic click handlers) | MEDIUM |
| Missing keyboard navigation | HIGH |
| Missing loading/empty/error states | MEDIUM |
| Hardcoded colors/spacing (not using tokens) | MEDIUM |
| Non-responsive components | MEDIUM |

#### 1f. AI-App Safety Sweep (only when an LLM is in the loop)

**Phase: AI app?** Run this sweep when the codebase calls an LLM (Anthropic /
OpenAI SDK, `messages.create`, a chat/agent loop) or exposes tools/MCP to a
model. Skip it entirely for non-AI apps. Read
`references/ai-safety-rules.md` for the full rule pack; the fast pre-screen
tripwires live in `references/ai-safety-signatures.json`.

Two surfaces, both keyed back to the rule pack:

| Check | Rule | Severity |
|---|---|---|
| Untrusted content (user/RAG/tool output) concatenat