audit

What this skill does

# Audit

Multi-level code review. Dispatcher — Opus 4.8 (thinking-tier). Workers — Sonnet 4.6.

This skill exercises **Layer 3 (Orchestrator)** and **Layer 9 (Security)**. After the review prints, a **fix gate** asks the user whether to apply the findings — on `Yes`, audit auto-invokes `/hyperflow:scope` with the findings as the spec, which then chains to `/hyperflow:dispatch`.

## Iron Rules

**Failure recovery (DOCTRINE rule 14).** Worker errors, malformed output, NEEDS_REVISION verdicts, and gate failures in every Step follow the canonical policy in [`skills/hyperflow/failure-recovery.md`](../hyperflow/failure-recovery.md). Audit-specific exception: a failed Reviewer at L1/L2 escalates to an L3+ Reviewer at the same severity level rather than aborting — audit exists to catch issues, so a Reviewer failure is best resolved by a more thorough Reviewer, not by stopping the chain.

## Per-Step Agent Map (DOCTRINE rule 12)

| Step | Sub-phase | Worker tier | Thinking tier | Notes |
|---|---|---|---|---|
| 1 — Resolve scope | — | — | — | Mechanical decision (exempt) |
| 2 — Gather context | 2a — Surface mapping | Searcher × 2 (glob + import-graph) | Sonnet Reviewer | Parallel |
| 2 — Gather context | 2b — Semantic indexing | Searcher × 2 (type-system + symbol-graph) | Sonnet Reviewer | Parallel |
| 2 — Gather context | 2c — Convention scan | Searcher × 1 (test patterns + lint config) | Sonnet Reviewer | Justified single-angle |
| 2 — Gather context | 2d — Aggregate coverage gate | — | **Reviewer** (Opus) verifies aggregate coverage | Thinking-tier coverage gate |
| 3 — Review | 3a — L1+L2 (syntax/format/naming) | — | **Reviewer** (Opus) × 2 (different file groups) + Sonnet Reviewer aggregates verdicts | Parallel Opus pair; justified single-tier (Opus are the workers at L1-L2) |
| 3 — Review | 3b — L3 (integration/security) | — | **Reviewer** (Opus) × 2 (integration + security) + Sonnet Reviewer aggregates verdicts | Parallel Opus pair; justified single-tier (L3 requires thinking-tier) |
| 3 — Review | 3c — L4+L5 (perf/scale/a11y/UX) | — | **Reviewer** (Opus) × 2 (perf/scale + a11y/UX) + Sonnet Reviewer aggregates verdicts | Parallel Opus pair; justified single-tier (L4-L5 requires thinking-tier) |
| 4 — Findings synthesis | 4a — Critical findings | Writer × 2 (evidence probe + impact analysis) | Sonnet Reviewer | Parallel |
| 4 — Findings synthesis | 4b — Important findings | Writer × 2 (root-cause probe + fix-path analysis) | Sonnet Reviewer | Parallel |
| 4 — Findings synthesis | 4c — Suggestions + observations | Writer × 2 (pattern analysis + praise identification) | Sonnet Reviewer | Parallel |
| 4 — Findings synthesis | 4d — Memory feedback | Writer × 1 (anti-pattern curation) | Sonnet Reviewer (dedup + compaction validation) | Atomic Worker→Reviewer; runs after 4a/4b/4c complete; with compaction pass when triggered |
| 5 — Severity reconciliation | — | — | Sonnet Reviewer reconciles severity labels from Step 3 sub-phases | Atomic-exempt per DOCTRINE 12.2.8 — reads existing Step 3 labels; no Workers needed |
| 6 — Fix gate | — | — | — | `AskUserQuestion` only (exempt — structural gate) |

## Approval Gates

| Gate | When | Format |
|---|---|---|
| Fix gate | Step 6, after NEEDS_FIX or PASS-with-suggestions | `AskUserQuestion` — fix all / criticals only / no |
| Hard halt | Any `SECURITY_VIOLATION` from the reviewer | Stop, surface the finding; no fix gate |

## Inputs

- **Target** — file path, line range, commit SHA, branch, or PR number provided by the user
- **Default (no target)** — `git diff HEAD` + `git diff --staged`
- **Level flag** — `--level 1` through `--level 5` (default — L2)

## Review Levels

Adapted from [review-levels.md](references/review-levels.md):

| L | Name | Checks |
|---|------|--------|
| 1 | Quick | Syntax, obvious bugs, formatting |
| 2 | Standard | L1 + spec compliance, naming, edge cases |
| 3 | Thorough | L2 + cross-file consistency, integration risks, security |
| 4 | Deep | L3 + architecture, scalability, accessibility |
| 5 | Exhaustive | L4 + adversarial probing, perf profiling, alternatives |

Security scan (hardcoded secrets, injection, path traversal, XSS, missing validation) is mandatory at L3+. See [security.md](references/security.md).

## Flow

### Step 1 — Resolve scope

Use the provided target or run `git diff HEAD` + `git diff --staged`. No agent dispatched (read-only git).

### Step 2 — Gather context

Sub-phases 2a, 2b, 2c run in parallel (P1). Step 2 output is the union of their worker outputs plus three sub-phase Reviewer verdicts, handed to an Opus aggregate coverage gate.

#### Step 2a — Surface mapping

Dispatch two Searcher agents in parallel:
- Searcher — glob discovery (file extensions, directory tree, entry points)
- Searcher — import-graph traversal (follow `import`/`require`/`use` chains from touched files)

Then dispatch `Sonnet Reviewer — 2a surface mapping coverage check`. Verdict ∈ {`PASS`, `NEEDS_REVISION`, `ESCALATE`}. On `NEEDS_REVISION`, re-dispatch only 2a.

#### Step 2b — Semantic indexing

Dispatch two Searcher agents in parallel:
- Searcher — type-system probe (interface/schema definitions relevant to changed symbols)
- Searcher — symbol-graph probe (callsites, usages, exported references of changed symbols)

Then dispatch `Sonnet Reviewer — 2b semantic indexing coverage check`. Verdict as above.

#### Step 2c — Convention scan

Dispatch one Searcher agent (single-angle justified — test patterns and lint config are a single orthogonal corpus with no independent axis to fan out across):
- Searcher — convention scan (existing test patterns, lint rules, naming conventions, code-style config)

Then dispatch `Sonnet Reviewer — 2c convention scan coverage check`. Verdict as above.

#### Step 2d — Aggregate coverage gate

After 2a + 2b + 2c complete, dispatch `**Reviewer** (Opus) — verifying aggregate context coverage` to confirm the combined surface covers all subsystems relevant to the diff. On coverage gap: re-dispatch the affected sub-phase (max 2 retries); surface gap to user if retries exhausted.

### Step 3 — Review

Sub-phases 3a, 3b, 3c run in parallel (P1) — each ends with a Sonnet sub-phase aggregator before the next batch fires. Active sub-phases scale with `--level`: L1-L2 runs only 3a; L3 adds 3b; L4-L5 add 3c.

#### Step 3a — L1+L2: syntax, formatting, naming

Dispatch two Reviewer agents in parallel over different file groups (split by directory or feature boundary):
- **Reviewer** (Opus) — L1+L2 review, file group A (syntax errors, obvious bugs, formatting, naming conventions)
- **Reviewer** (Opus) — L1+L2 review, file group B (same checklist, different file group)

Then dispatch `Sonnet Reviewer — 3a aggregation` to union the two verdicts and deduplicate overlapping findings. Verdict ∈ {`PASS`, `NEEDS_REVISION`, `ESCALATE`}. On `NEEDS_REVISION`, re-dispatch only 3a.

#### Step 3b — L3: integration, security (L3+ only)

Dispatch two Reviewer agents in parallel over different concern dimensions:
- **Reviewer** (Opus) — L3 integration risks (cross-file consistency, API contract mismatches, race conditions, edge cases)
- **Reviewer** (Opus) — L3 security scan (hardcoded secrets, injection, path traversal, XSS, missing validation — per [security.md](references/security.md))

If the security Reviewer emits `SECURITY_VIOLATION:` → halt immediately; skip the fix gate; surface the finding inline; user decides remediation.

Then dispatch `Sonnet Reviewer — 3b aggregation` to union the two verdicts. Verdict as above.

#### Step 3c — L4+L5: performance, scalability, accessibility, UX (L4+ only)

Dispatch two Reviewer agents in parallel:
- **Reviewer** (Opus) — L4+L5 performance and scalability (algorithmic complexity, memory, bundle size, adversarial load)
- **Reviewer** (Opus) — L4+L5 accessibility and UX (WCAG compliance, keyboard nav, screen-reader semantics, interaction design)

Then dispatch `Sonnet Reviewer — 3c aggregation` to union the two verdicts. Verdict as above.

Th