Audit

Audit

Multi-level code review. All agents inherit the session model. Reviewers bold-labeled; Workers plain.

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:plan 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. 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)

Approval Gates

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:

Security scan (hardcoded secrets, injection, path traversal, XSS, missing validation) is mandatory at L3+. See 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).

Targets accepted: a path/glob, an explicit file list, or a git range <base>..<head>. The range form is how a two-session handoff review runs — /hyperflow:handoff review <slug> reads the build's COMPLETION.md diff range and invokes audit as Skill audit "<base>..<head> level=<n>", so the review covers exactly the second session's commits (git diff <base>..<head>). See ../hyperflow/session-handoff.md.

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 a standalone aggregate coverage gate. The Searchers also record which surfaces the diff touches (frontend / api / db / devops / mobile / data-ml / security) — this drives the domain-specialist selection in Step 3 (../../agents/README.md).

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 **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 **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 **Reviewer** — 2c convention scan coverage check. Verdict as above.

Step 2d — Aggregate coverage gate

After 2a + 2b + 2c complete, dispatch **Reviewer** — 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 sub-phase aggregator Reviewer before the next batch fires. Active sub-phases scale with --level: L1-L2 runs only 3a; L3 adds 3b; L4-L5 add 3c.

Specialist selection. Step 2 detects which surfaces the diff touches (frontend, api, db, devops, mobile, data/ml, …). Step 3 dispatches each Reviewer as the matching domain specialist (../../agents/README.md) — its charter + strict checklist injected, and (audit is a gated flow) its web-research-first pass run for current best-practice / CVE currency. When the target has a spec/task file, its Brain-decided Specialists roster seeds the selection.

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

Dispatch two Reviewer agents in parallel over different file groups (split by directory or feature boundary), each as the domain specialist matching that group's surface (frontend-reviewer / backend-reviewer / api-reviewer / database-reviewer / devops-reviewer / mobile / data-ml-reviewer):

• Reviewer (domain specialist) — L1+L2 review, file group A (syntax errors, obvious bugs, formatting, naming conventions)
• Reviewer (domain specialist) — L1+L2 review, file group B (same checklist, different file group)

Then dispatch **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 — as the security specialists:

• Reviewer (backend-reviewer or api-reviewer) — L3 integration risks (cross-file consistency, API contract mismatches, race conditions, edge cases)
• Reviewer (security-reviewer + vulnerability-reviewer) — L3 security scan (hardcoded secrets, injection, path traversal, XSS, missing validation, known-CVE exposure — per security.md, web-research-first on current advisories)

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

Then dispatch **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 — as the matching specialists:

• Reviewer (performance-reviewer) — L4+L5 performance and scalability (algorithmic complexity, memory, bundle size, adversarial load)
• Reviewer (accessibility-reviewer) — L4+L5 accessibility and UX (WCAG compliance, keyboard nav, screen-reader semantics, interaction design)

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

The Reviewer uses the reviewer-prompt.md template with the diff, level definition, and any applicable spec. Each sub-phase produces structured [Critical] / [Important] / [Suggestions] / [Praise] findings that feed into Step 4.

Step 4 — Findings synthesis

Write the full structured audit to .hyperflow/audits/<YYYY-MM-DD-HHmm>-<scope-slug>.md. Sub-phases 4a, 4b, 4c run in parallel (P1), each authoring a section of the audit file. The audit file also receives a memory-append section per memory-system.md.

Step 4a — Critical findings

Dispatch two Writer agents in parallel:

• Writer — evidence probe (trace each Critical finding back to the diff line; confirm reproducibility)
• Writer — impact analysis (articulate user-visible / system-level consequence for each Critical finding)

Then dispatch **Reviewer** — 4a critical findings review to verify each Critical entry has a confirmed fix path and no false positives. Verdict ∈ {PASS, NEEDS_REVISION, ESCALATE}.

Step 4b — Important findings

Dispatch two Writer agents in parallel:

• Writer — root-cause probe (trace each Important finding to its origin; confirm it's not a symptom of a Critical)
• Writer — fix-path analysis (propose the recommended change per finding, with file:line anchors)

Then dispatch **Reviewer** — 4b important findings review. Verdict as above.

Step 4c — Suggestions, observations, and memory append

Dispatch two Writer agents in parallel:

• Writer — pattern analysis (identify Suggestion-level improvements; extract reusable patterns for memory)
• Writer — praise identification (flag genuinely well-done decisions; append durable patterns to .hyperflow/memory/learnings.md per memory-system.md)

Then dispatch **Reviewer** — 4c suggestions + memory dedup check to ensure no duplicate memory entries land and no Suggestions are mis-classified as Important. Verdict as above.

Step 4d — Memory feedback (runs after 4a/4b/4c complete)

After the audit file is written, curate recurring problem patterns into .hyperflow/memory/anti-patterns.md so future audit runs and workers benefit from accumulated findings. This is an atomic Worker→Reviewer pair.

Dispatch one Writer agent:

• Writer — anti-pattern curation (read .hyperflow/memory/anti-patterns.md if it exists; extract up to 3 new entries from the [Critical] and [Important] findings produced in 4a/4b; append or update the file)

Curation rules the Writer must follow:

• Only [Critical] and [Important] findings are eligible — Suggestions and Praise are excluded.
• Before writing, read the existing anti-patterns.md. If a matching pattern already exists, increment its frequency counter and update last seen. Do not create a duplicate entry.
• Limit: max 3 new pattern entries per audit run. When more than 3 eligible findings exist, prioritize by breadth — multi-file findings before single-file findings.
• Append entries in this format:

## <pattern category> (e.g. Error handling, Naming, Dead code)
- <description> — first observed in audit <YYYY-MM-DD>, frequency: <count>, last seen: <YYYY-MM-DD>
  Recommendation: <what workers should do to avoid this>

• Tag anti-patterns.md as #hot in the session memory index so workers load it at session start alongside other hot-tier files.

Compaction pass (runs after the Writer appends new entries, not before):

New findings always land first. After the append, the Writer checks whether compaction is needed. Compaction is triggered when ANY of the following is true:

• Total entry count in anti-patterns.md exceeds 50.
• Any entry has last seen more than 6 months ago AND frequency == 1 (stale singleton — never reinforced).
• File line count meets or exceeds the memory.compactionThreshold (default 300, from ~/.hyperflow/config.json).

When triggered, the Writer runs these actions in order:

1. Merge duplicates. Entries in the same category with similar wording are merged into one. Combined frequency = sum of the merged entries; last seen = most recent of the merged entries. Wording is taken from the higher-frequency entry.
2. Archive stale singletons. Entries where frequency == 1 AND last seen is older than 6 months move to .hyperflow/memory/archive/YYYY-MM.md (month derived from the entry's last seen date), tagged with their source so they remain retrievable. This is the same shared monthly archive convention used by /hyperflow:cache compact — see skills/cache/references/compaction.md.
3. Cap at 50 entries. If the file still exceeds 50 entries after merge and archive, evict the lowest-frequency entries. Tiebreak: oldest last seen is evicted first. Never evict entries derived from [Critical] findings — the highest-severity patterns are exactly the ones that must keep surfacing; if eviction is needed and only Critical-sourced entries remain over the cap, leave the file over-cap and note it for the next compaction. Evicted entries move to the same shared monthly archive.
4. Hot-tier is already wired. anti-patterns.md is permanently hot-tier (see memory-system.md). The post-compaction file is injected automatically at the next session start. No manual hot-tier refresh is needed.

If compaction was triggered but none of the three actions has anything eligible to do (e.g. the line-count threshold tripped on a verbose but already-deduped ≤50-entry file), the Writer skips the rewrite — no no-op compaction dispatch. If compaction was not triggered at all, the Writer skips this block entirely and proceeds to the Reviewer.

Then dispatch **Reviewer** — 4d anti-pattern dedup and compaction check to verify: no duplicate entries landed, frequency counters are accurate, only Critical/Important findings were promoted, the new-entry count does not exceed 3, and — when compaction ran — no critical entries were dropped without archiving and the archive sidecar was written correctly. Verdict ∈ {PASS, NEEDS_REVISION}. On NEEDS_REVISION, the Writer re-reads the file and corrects the specific violation (max 1 retry before surfacing inline).