codebase-audit

# Codebase Audit — Adaptive Deep Analysis

A comprehensive codebase audit that adapts its agent configuration to the project's tech stack. Each agent uses the highest-tier model for maximum thoroughness. Findings are verified before compilation, then compiled into a unified report sorted by severity with a phased repair roadmap.

## Core Principles

1. **Highest-tier model** — All audit agents MUST use the highest-capability model available in the current environment (e.g. `fable`; `opus` acceptable as fallback). Never use lightweight tiers (haiku) for audit agents. If the highest tier is unavailable, fall back one tier and note the downgrade in the report header.
2. **Depth over breadth** — Fewer agents with broader scope and deeper analysis beats many shallow agents. Each agent should trace issues across file boundaries.
3. **Adaptive** — Agent count and focus areas vary by project type. Don't waste an agent on "frontend rendering" for a backend-only project.
4. **Verify before report** — No Critical/High finding enters the report unverified. LLM audit agents misreport intentional patterns (deliberate fallbacks, feature gates) as defects; Phase 1.5 exists to catch that.

## When to Use

- User asks to audit/review/analyze an entire codebase
- User wants to find hidden bugs, silent degradation, or design inconsistencies
- User asks about technical debt, architecture health, or "what's broken"
- Before a major refactor or after inheriting an unfamiliar codebase
- Periodic health check (monthly/quarterly) — see Phase 3 for baseline diffing

## Workflow

### Phase 0: Tech Stack Detection & Deterministic Scans

Detect the project's tech stack to determine the agent configuration:

```
Detection checklist:
- package.json / tsconfig.json → TypeScript/JavaScript (React, Next.js, Vue, etc.)
- pyproject.toml / requirements.txt / setup.py → Python (FastAPI, Django, Pydantic, etc.)
- Cargo.toml → Rust (serde, axum, actix, etc.)
- go.mod → Go (gin, echo, gorm, etc.)
- Multiple stacks → Full-stack project (frontend + backend)
- Async runtime signals: Cargo.toml contains tokio/async-std, go.mod present,
  asyncio imports → enable the Concurrency & Async Hygiene section for the
  Data Integrity agent (see agent-prompts.md)
```

After stack detection, run the matching dependency audit from the target project root, never from the assistant's incidental current working directory. If the user supplied an explicit target path, use it as `{TARGET_DIR}` before invoking the tool. For Python projects, run each matching audit input that exists and feed all outputs to the security agent (deterministic, zero LLM cost):

```
- Rust → cd "{TARGET_DIR}" && cargo audit
- Node → cd "{TARGET_DIR}" && npm audit
- Python project metadata (`pyproject.toml` / `setup.py`) → cd "{TARGET_DIR}" && pip-audit .
- Python requirements (`requirements.txt`) → cd "{TARGET_DIR}" && pip-audit -r requirements.txt
- Python environment fallback (no project files found) → cd "{TARGET_DIR}" && pip-audit .
- Go → cd "{TARGET_DIR}" && govulncheck ./...
```

Feed the raw output to the Error Handling & Security agent (frontend-only: to Agent 2) for classification: Critical = RCE-grade CVE with PoC on a reachable path; High = known vuln on a reachable path. If the tool is unavailable, the report MUST state "依赖审计降级跳过" — never omit silently.

### Phase 1: Launch Agents (Adaptive)

Based on the detected stack, choose the appropriate agent configuration below. Launch ALL agents in a SINGLE message, each with the model tier defined in Core Principles #1.

Read `references/agent-prompts.md` for complete prompt templates. Every prompt MUST be self-contained: target path, stack info, and the Unified Output Contract (defined at the top of agent-prompts.md) — sub-agents cannot see this file.

Before launching, verify every agent Type against the available subagent registry. If a type is not registered, STOP and report the missing type — do NOT substitute a similar one.

---

#### Full-Stack Projects (5 agents)

When both frontend and backend exist (e.g., React + FastAPI, Next.js + Go).

| # | Agent | Type | Scope (merged dimensions) |
|---|-------|------|---------------------------|
| 1 | **Frontend-Backend Contract** | `senior-code-reviewer` | Type consistency (field names, types, missing fields) + Rendering pipeline (layout/block/card routing completeness, dead slots, unrendered fields) + Serialization boundaries (models that silently drop fields). This agent reads BOTH sides and traces data across the API boundary. |
| 2 | **Data Integrity & Flow** | `senior-code-reviewer` | Data pipeline end-to-end: from input through every transformation layer to output. Covers: field resolver filters, serialization/deserialization, model_validate/model_dump, cache read/write symmetry, registry key-set alignment (sole owner — Agent 4 must not re-check). Also covers: declaration-execution gaps (registered but unwired handlers, enum without config), and Concurrency & Async Hygiene when an async runtime is detected. |
| 3 | **Error Handling & Security** | `security-auditor` | Exception patterns (bare except, debug-level errors, warning+fallback), security (hardcoded secrets, injection, unsafe deserialization), silent degradation (error paths that produce user-visible wrong output instead of failing), classification of Phase 0 dependency-audit output. |
| 4 | **Architecture & Code Quality** | `code-archaeologist` | Layer violations, circular dependencies, god objects (files >800 lines), code duplication (parallel systems, scattered mapping tables), extension cost analysis (how many files to add a new type), DI pattern consistency, test quality (coverage gaps, weakened assertions, skip markers, stale tests). |
| 5 | **Config & Persistence** | `code-archaeologist` | Config completeness (template/schema vs code expectations, conflicting defaults), cache key completeness (missing code version dimension), DB schema consistency, temp file cleanup, state persistence across res