codebase-audit

# Codebase Audit — Adaptive Deep Analysis

Comprehensive codebase audit that adapts its agent configuration to the project's tech stack, forces structured findings, adversarially verifies Critical/High findings before they enter the report, diffs against the previous audit's ledger (resolved / still-open / new), and outputs a severity-sorted report plus a phased repair roadmap.

## Core Principles

1. **READ-ONLY** — Audit agents must never create, modify, or delete files in the target. Every agent prompt starts with the read-only preamble in `references/agent-prompts.md`.
2. **Inherit the session model** — Omit the `model` param on all agents so they inherit the session model (usually the strongest available). Only override *upward* if the session model is clearly weak for cross-file reasoning. Never hardcode a specific model name in this skill.
3. **Depth over breadth** — Fewer agents with broader merged scopes beat many shallow agents. Each agent traces issues across file boundaries.
4. **Adaptive** — Agent count and dimensions vary by stack and mode.
5. **Verified findings** — Critical/High findings must survive an adversarial verify pass. Medium findings pass through but are labeled `unverified` in the report.

## Operating Contract

- Direct actions: read-only inspection, local dependency audits, report writing under the target, and ledger updates under `<target>/.audit/` after the user invokes this skill.
- Escalate before: editing audited project source files, dependency manifests, `.gitignore`, CI config, remote issues, PR state, or anything outside the requested audit/report scope.
- Evidence-backed pushback: challenge "all clear" or "resolved" only with file evidence, dependency-audit output, verifier results, or ledger spot-checks.
- Feedback loop: promote repeated misses into prompt updates, ledger matching rules, or fixture eval cases rather than leaving them as session-only notes.

## Gotchas

- Dependency-audit commands must run from `{TARGET_DIR}`, not the assistant's incidental cwd.
- Finder agents must not read `evals/expected-findings.json` or eval README files when auditing the planted-bug fixture.
- A previous ledger miss is not proof that a finding was resolved; spot-check the file before marking an old finding `resolved`.

## Modes

| Mode | Trigger | Agents | Verify pass | Ledger |
|------|---------|--------|-------------|--------|
| **full** (default) | plain invocation, "全面审查" | 3–5 by stack (+ optional dims) | yes | yes |
| **quick** | "quick" in args, "快速体检" | 2 (Silent Degradation & Security; Data Integrity & Registry) | no — all findings labeled `unverified` | yes |

**Optional dimensions** (full mode only, enable when user asks or the repo obviously needs them):
- `tests` — test quality: assertion strength, skip markers, coverage of critical paths (Agent 6)
- `concurrency` — races, blocking calls in async, leaked tasks/goroutines (Agent 7)

## Workflow

### Phase 0: Detect & Prepare

1. **Stack detection**: `package.json`/`tsconfig.json` → TS/JS; `pyproject.toml`/`requirements.txt` → Python; `Cargo.toml` → Rust; `go.mod` → Go; multiple → full-stack.
2. **Size estimate**: `tokei <target>` (fallback: `find <target> -name '*.<ext>' | xargs wc -l`), excluding vendored/generated code. If effective size ≥ 400K LOC, split each agent's scope by top-level directory and note the split in the report.
3. **Exclusions** (always, in every agent prompt): `node_modules/`, `vendor/`, `target/`, `dist/`, `build/`, `.git/`, lockfiles, generated code.
4. **Ledger**: read `<target>/.audit/findings.json` if it exists — this is the previous audit baseline (format: `references/ledger-format.md`).
5. **Deterministic dependency audit**: from `{TARGET_DIR}` (never the assistant's incidental cwd), run each matching tool and feed raw output to the Error Handling & Security prompt:
   - Rust: `cargo audit`
   - Node: `npm audit`
   - Python metadata (`pyproject.toml` / `setup.py`): `pip-audit .`
   - Python requirements (`requirements.txt`): `pip-audit -r requirements.txt`
   - Python fallback with no project files: `pip-audit .`
   - Go: `govulncheck ./...`
   If a required tool is unavailable, the report must state `依赖审计降级跳过: <tool>`; never omit the degradation silently.

### Phase 1: Assemble Dimensions

Pick the configuration by detected stack. Full prompt templates in `references/agent-prompts.md`; prepend the read-only preamble and inject `{TARGET_DIR}` / `{STACK_INFO}` into each.

**Full-Stack (5 agents)** — frontend + backend both present:

| # | Dimension | Scope (merged) |
|---|-----------|----------------|
| 1 | Frontend-Backend Contract | Type consistency + rendering pipeline + serialization boundaries. Reads BOTH sides. |
| 2 | Data Integrity & Flow | End-to-end pipeline tracing, field dropping, declaration-execution gaps, registry coverage alignment. |
| 3 | Error Handling & Security | Silent degradation, exception patterns, secrets, injection, unsafe deserialization. |
| 4 | Architecture & Code Quality | Layer violations, god objects, duplication/drift, extension cost, registry cross-reference. |
| 5 | Config & Persistence | Config completeness, cache key/integrity, DB schema, temp files, state persistence. |

**Backend-Only (4 agents)**: replace #1 with "API Contract & Data Integrity" (which absorbs #2's data-flow/registry scope — do NOT also dispatch #2); keep #3–#5.
**Frontend-Only (3 agents)**: Component Architecture & Rendering; Error Handling & Code Quality; Config & Build.
**Quick mode (2 agents)**: Silent Degradation & Security (= #3); Data Integrity & Registry (= #2 core).

Fallback-path agent types (when using the Agent tool instead of Workflow): agent availability is environment-specific — check the subagent registry visible in the current session and use only type names that appear there. Never invent aliases (there is no generic `reviewer` type). If no specialized type matches, use `general-purpose` (or the environment's default catch-all) for every dimensi