wave-audit

name	wave-audit
description	3-wave parallel audit — Wave 1 discovery (4 agents), Wave 2 verification (4 agents), Wave 3 cross-optimization (1 synthesizer). Each wave runs agents in parallel. Combines security review, runtime analysis, quality check, and constructor pattern into one unified workflow with evidence grading and Go/No-Go verdict.

/wave-audit — 3-Wave Parallel Audit

When to use

• Comprehensive code review: security, runtime analysis, quality, and Constructor Pattern in one 3-wave parallel workflow.
• Before merging a significant branch or shipping a milestone (95%+ finding coverage via cross-verification).
• After /dev-guard commit approvals when you need a deeper, cross-dependency audit sweep.

Один аудитор находит 60%. Два параллельных — 80%. Три волны с перекрёстной проверкой — 95%+. Доказано экспериментом 2026-03-24: ни один подход в изоляции не покрыл все findings.

Команды

• /wave-audit → полный review (3 волны, все фокусы)
• /wave-audit review [focus] → выборочный review
• /wave-audit lite → быстрый режим (2 агента Wave 1, без Wave 2, упрощённый Wave 3)
• /wave-audit diff → инкрементальный (только изменённые файлы + их зависимости)
• /wave-audit apply → применить фиксы в worktree (после approve)

focus: security | runtime | quality | structure | all (default: all)

---

Anti-Hallucination Protocol

AI галлюцинирует. Это не баг, это свойство. Skill ОБЯЗАН это компенсировать.

Правило CODE_QUOTE

Каждый finding ОБЯЗАН содержать дословную цитату кода (3-7 строк), НЕ описание.

BAD:  "Функция не верифицирует JWT подпись"
GOOD: "apple.ts:72-74: `const decoded = jwt.decode(idToken, { complete: true });`
       — jwt.decode() НЕ верифицирует подпись, нужен jwt.verify()"

Если агент НЕ может процитировать код — finding отклоняется как unverified.

Правило VERIFY_CMD

Каждый finding ОБЯЗАН содержать команду верификации — как подтвердить без чтения кода:

verify: grep -n "jwt.decode" apps/api/src/external/oauth/apple.ts
verify: wc -l apps/api/src/services/auth.service.ts  # expect >200
verify: grep -rn "new AuthService" apps/api/src/  # count instantiations

Правило COVERAGE_LOG

Каждый агент Wave 1 ОБЯЗАН в конце отчёта указать:

FILES_READ: [список файлов которые реально открыл через Read tool]
FILES_TOTAL: [общее число source files]
COVERAGE: N% (read/total)
NOT_CHECKED: [список файлов/модулей которые НЕ проверял]

Правило SEVERITY_CALIBRATION

Перед назначением severity, агент ОБЯЗАН ответить на вопрос:

• CRITICAL: "Можно ли эксплуатировать прямо сейчас без аутентификации?" Если нет → max HIGH.
• HIGH: "Приведёт ли это к потере данных или компрометации в production?" Если нет → max MEDIUM.
• MEDIUM: "Заметит ли это пользователь?" Если нет → LOW.

---

Phase 0 — Baseline Snapshot

Выполняет lead (не агент). Обязательно ДО запуска Wave 1.

1. Проверить что это git-репозиторий
2. Определить реальный стек (НЕ из memory — читать package.json / pubspec.yaml / go.mod / Cargo.toml)
3. Снять baseline:
   • git log --oneline -5 — последние коммиты
   • git status --short — текущее состояние
   • git diff --stat — незакоммиченные изменения
4. Определить и запустить CI-проверки стека:
   • JS/TS: npm run lint, npm run build, npm test (или turbo/nx аналоги)
   • Flutter: flutter analyze, flutter test
   • Go: go vet ./..., go build ./..., go test ./...
   • Python: ruff check ., pytest
   • Rust: cargo clippy, cargo build, cargo test
5. Зафиксировать baseline-метрики:

   BASELINE:
   - lint: PASS/FAIL (N warnings, M errors)
   - build: PASS/FAIL
   - tests: PASS/FAIL (N passed, M failed, K skipped)
   - stack: [detected stack]
   - files: [total source files count]
   

---

Wave 1 — Discovery (4 параллельных агента)

Создать TeamCreate, запустить 4 агента ОДНИМ сообщением (параллельно). Каждый агент работает независимо, НЕ знает о findings других.

Agent: w1-security

Проведи security review проекта [path].
Стек: [из baseline]. НЕ применяй фиксы.

Phase 1 — Risk Classification:
- HIGH: auth, crypto, network, memory, deserialization, FFI
- MEDIUM: input validation, error handling, config, logging, API
- LOW: docs, tests, formatting

Phase 2 — Vulnerability Checklist:
- [ ] Input validation — все входные данные валидируются?
- [ ] Auth/authz bypass — можно обойти?
- [ ] Race condition — shared state без lock? TOCTOU?
- [ ] Injection — SQL, command, path traversal, SSTI?
- [ ] Secrets — hardcoded keys, tokens в логах?
- [ ] Deserialization — untrusted input в unmarshal/decode?
- [ ] Resource exhaustion — unbounded allocations, missing timeouts?
- [ ] Crypto — правильные алгоритмы? верификация подписей?

Phase 3 — Supply Chain:
Для КАЖДОЙ зависимости: maintainers, activity, CVE, transitive deps, dead deps.

Каждый finding ОБЯЗАН содержать:
1. severity (CRITICAL/HIGH/MEDIUM/LOW) — пройди SEVERITY_CALIBRATION
2. файл:строка
3. CODE_QUOTE (3-7 строк дословно)
4. attack scenario
5. VERIFY_CMD (команда для подтверждения)
6. [E1-E6] evidence grade

В конце — COVERAGE_LOG: какие файлы читал, какие нет.
Отдай как structured list.

Agent: w1-runtime

Проведи runtime/performance review проекта [path].
Стек: [из baseline]. НЕ применяй фиксы.

Checklist:
- [ ] N+1 queries — ORM/DB calls в циклах или per-item resolvers
- [ ] Data joins — merge по индексу вместо ключа? silent corruption?
- [ ] Cache invalidation — JSON.parse теряет типы? stale data?
- [ ] Hot paths — какие функции на критическом пути?
- [ ] Allocations — per-request instantiation? можно singleton?
- [ ] I/O — sync operations на async path? blocking calls?
- [ ] Complexity — O(n²) или хуже в hot loops?
- [ ] Renders/rebuilds — лишние re-renders в UI? missing memo?
- [ ] Timeouts — есть ли на внешних API calls? unbounded waits?
- [ ] Connection pools — DB/Redis connections managed?

Каждый finding ОБЯЗАН содержать:
1. severity — пройди SEVERITY_CALIBRATION
2. файл:строка
3. CODE_QUOTE (3-7 строк дословно)
4. impact estimate (latency/memory/throughput)
5. VERIFY_CMD
6. [E1-E6] evidence grade

В конце — COVERAGE_LOG.

Agent: w1-quality

Проведи quality review проекта [path].
Стек: [из baseline]. НЕ применяй фиксы.

Checklist:
- [ ] DRY — дублированный код? одинаковая логика в разных файлах?
- [ ] SRP — файл делает больше одного? mixed responsibilities?
- [ ] Naming — нечитаемые имена? inconsistent conventions?
- [ ] Dead code — unreachable branches? unused exports/imports?
- [ ] Edge cases — null/undefined handling? empty arrays? boundary values?
- [ ] Error handling — consistent pattern? fail open vs fail closed?
- [ ] Error messages — информативные? не leakают internal details?
- [ ] Type safety — any/unknown? missing generics? loose types?
- [ ] API boundaries — чёткие контракты между модулями?

Каждый finding ОБЯЗАН содержать:
1. severity — пройди SEVERITY_CALIBRATION
2. файл:строка
3. CODE_QUOTE (3-7 строк дословно)
4. impact
5. VERIFY_CMD
6. [E1-E6] evidence grade

В конце — COVERAGE_LOG.

Agent: w1-structure

Проведи structural review проекта [path].
Стек: [из baseline]. НЕ применяй фиксы.

Constructor Pattern Checklist:
- [ ] Файлы >200 строк — перечисли ВСЕ с точным LOC
- [ ] Функции >30 строк — перечисли ВСЕ с точным LOC
- [ ] 1 файл = 1 класс = 1 ответственность — нарушения?
- [ ] Types/interfaces определены ДО реализации?
- [ ] SSOT — типы, enum, routes, configs дублируются?

CI/Pipeline Check:
- [ ] Все команды из CI (lint/build/test) проходят?
- [ ] Есть ли пустые stubs/packages ломающие pipeline?
- [ ] Lock-файлы актуальны?

Dependency Health:
- [ ] Unused dependencies (installed but never imported)
- [ ] Outdated deps (major version behind)
- [ ] Conflicting deps (multiple packages для одной задачи)

Каждый finding ОБЯЗАН содержать:
1. severity — пройди SEVERITY_CALIBRATION
2. файл:строка
3. CODE_QUOTE или точные числа (LOC count)
4. VERIFY_CMD (например: `wc -l file.ts`)
5. [E1-E6] evidence grade

В конце — COVERAGE_LOG.

Сбор результатов Wave 1

Lead собирает findings от всех 4 агентов в единый список. Формат: W1-{agent}-{N}: [severity] description [evidence grade]

---

Wave 2 — Verification (4 параллельных агента)

Запустить 4 агента ОДНИМ сообщением, передав КАЖДОМУ полный список findings из Wave 1.

Agent: w2-false-positive-filter

Получи ВСЕ findings из Wave 1: [список]
Проект: [path], стек: [стек].

Для КАЖДОГО finding:
1. Прочитай код по указанному файлу:строке
2. Это РЕАЛЬНАЯ проблема или false positive?
3. Если false positive — ПОЧЕМУ (например: "anon key публичный by design Supabase")
4. Если реальная — подтверди severity или скорректируй

Output:
- CONFIRMED: [finding ID] — [подтверждённый severity]
- DOWNGRADED: [finding ID] — [новый severity] — [причина]
- REJECTED: [finding ID] — [причина]

Agent: w2-gap-hunter

Получи ВСЕ findings из Wave 1: [список]
Проект: [path], стек: [стек].

Задача: найти то, что Wave 1 ПРОПУСТИЛА.

1. Variant analysis: каждый найденный баг = КЛАСС. Проверь аналогичные места:
   - Exact: тот же код в другом файле
   - Structural: тот же паттерн в другом модуле
   - Semantic: та же логическая ошибка с другим синтаксисом

2. Пробелы в покрытии:
   - Какие файлы/модули Wave 1 не проверяла?
   - Есть ли critical paths без findings? (подозрительно — или чисто, или пропущено)

3. Cross-domain gaps:
   - Security нашёл auth issue — runtime проверил performance auth flow?
   - Runtime нашёл N+1 — quality проверил error handling в том же resolver?

Output: список ДОПОЛНИТЕЛЬНЫХ findings с severity + файл:строка + [E1-E6].

Agent: w2-fix-impact

Получи ВСЕ findings из Wave 1: [список]
Проект: [path], стек: [стек].

Для каждого finding с предложенным фиксом:
1. Какие файлы затронет фикс? (blast radius)
2. Может ли фикс сломать существующий функционал?
3. Нужна ли миграция данных/токенов/состояния?
4. Зависит ли фикс от других фиксов? (порядок применения)
5. Estimated complexity: trivial / moderate / significant

Output:
- [finding ID]: blast_radius=[N files], breaks=[что может сломать], deps=[зависит от], complexity=[level]

Agent: w2-architecture-guard

Получи ВСЕ findings из Wave 1: [список]
Проект: [path], стек: [стек].

Для каждого предложенного фикса проверь:
1. Не нарушает ли Constructor Pattern? (файл останется <200? функция <30?)
2. Не создаёт ли новое дублирование? (SSOT)
3. Не вводит ли запрещённые паттерны? (миксины, DI-контейнеры, абстрактные фабрики)
4. Сохраняет ли API boundaries между модулями?
5. Совместим ли с текущей архитектурой проекта?

Если фикс нарушает архитектуру — предложи АЛЬТЕРНАТИВНЫЙ фикс.

Output:
- [finding ID]: architecture_safe=YES/NO, conflict=[описание], alternative=[если NO]

Сбор результатов Wave 2

Lead объединяет:

• Confirmed/rejected/downgraded findings
• New findings от gap-hunter
• Impact analysis
• Architecture conflicts

---

Wave 3 — Cross-Optimization (1 синтезатор)

Один агент получает ВСЕ данные из Wave 1 + Wave 2.

Agent: w3-synthesizer

Получи ВСЕ данные:
- Wave 1 findings: [список]
- Wave 2 verifications: [confirmed/rejected/downgraded]
- Wave 2 new findings: [от gap-hunter]
- Wave 2 impact analysis: [blast radius, deps]
- Wave 2 architecture conflicts: [список]
Проект: [path], стек: [стек], baseline: [метрики].

Задачи:

1. CROSS-DOMAIN ANALYSIS
   Найди пересечения: security fix ломает performance?
   Runtime optimization создаёт security hole?
   Два фикса трогают один файл — порядок?

2. OPTIMAL SOLUTIONS
   Для каждой группы связанных findings — найди ОДНО решение вместо N патчей.
   Пример: 3 HTTP клиента с дублированным error handling → один base client.
   Пример: N+1 + cache issue в одном resolver → DataLoader + cache fix вместе.

3. PRIORITY MATRIX
   Ранжируй ВСЕ confirmed findings по формуле:
   score = severity_weight × (1 / fix_complexity) × blast_radius_factor
   severity: CRITICAL=10, HIGH=7, MEDIUM=4, LOW=1
   complexity: trivial=1, moderate=0.5, significant=0.3
   blast_radius: 1-3 files=1.0, 4-10=0.8, 10+=0.5

4. EVIDENCE GRADES
   Каждый finding — [E1]-[E6] с обоснованием.

5. GO/NO-GO VERDICT
   - GO: нет CRITICAL, все HIGH имеют простой фикс
   - GO with constraints: есть CRITICAL но workaround возможен
   - NO-GO: CRITICAL без workaround, или >3 HIGH без фиксов

6. APPLY PLAN (если GO/GO with constraints)
   Порядок фиксов: low-risk → medium-risk → high-risk.
   Каждый фикс = отдельный checkpoint commit.
   После каждого — re-run baseline checks.

---

Формат итогового отчёта

=== WAVE AUDIT REPORT ===
Project: [name] | Stack: [detected] | Date: [date]

## Baseline
| Check | Status | Details |
|-------|--------|---------|
| lint  | PASS/FAIL | N warnings, M errors |
| build | PASS/FAIL | ... |
| tests | PASS/FAIL | N passed, M failed |

## Wave 1 — Discovery
### Security (w1-security): N findings
### Runtime (w1-runtime): N findings
### Quality (w1-quality): N findings
### Structure (w1-structure): N findings
Total: N findings

## Wave 2 — Verification
### Confirmed: N | Rejected: N | Downgraded: N
### New findings (gap-hunter): N
### Architecture conflicts: N
### High-risk fixes: [list]

## Wave 3 — Optimized Results

### Priority Matrix
| # | Severity | Finding | Fix | Complexity | Blast | Score | [E] |
|---|----------|---------|-----|------------|-------|-------|-----|
| 1 | CRITICAL | ...     | ... | trivial    | 2     | 10.0  | E1  |

### Optimal Solutions (grouped)
- Group A: [related findings] → [one fix]
- Group B: [related findings] → [one fix]

### Cross-Domain Conflicts
- [conflict description + resolution]

## Verdict: GO / GO with constraints / NO-GO
Reason: [explanation]

## Apply Plan
1. checkpoint: before wave-audit fixes
2. [fix #1] — [files] — low risk
3. [fix #2] — [files] — low risk
...
N. re-run baseline → compare with pre-audit

---

Apply Phase (только после approve)

1. checkpoint: commit перед началом
2. Создать worktree: git worktree add .claude/worktrees/wave-audit-fix
3. Применять фиксы в порядке из apply plan (low-risk → high-risk)
4. Каждый фикс = отдельный commit
5. Re-run baseline checks в worktree
6. Strict mode: если хуже baseline по любому критерию → STOP
7. Hand-off: показать diff, результаты, остаточные риски

---

Safety Constraints

Запрещено:

• Исправлять что-либо до завершения ВСЕХ 3 волн
• Пропускать Wave 2 ("Wave 1 всё нашла")
• Пропускать Wave 3 ("нет конфликтов") — Wave 3 ВСЕГДА
• git reset --hard, удаление файлов/веток без approve
• Менять секреты (.env, ключи, токены)
• Объединять findings без маркировки источника (W1/W2/W3)

---

Стандартный формат Finding (обязателен для ВСЕХ агентов)

Единый формат предотвращает потерю данных между волнами и упрощает дедупликацию.

ID: W{wave}-{agent}-{N}
SEVERITY: CRITICAL|HIGH|MEDIUM|LOW
CALIBRATION: [ответ на вопрос из SEVERITY_CALIBRATION]
FILE: path/to/file.ts:42-48
CODE_QUOTE: |
  const decoded = jwt.decode(idToken, { complete: true });
  // no jwt.verify() call — signature not checked
PROBLEM: [1-2 предложения]
IMPACT: [что произойдёт если не починить]
FIX: [конкретное изменение]
VERIFY_CMD: grep -n "jwt.decode" apps/api/src/external/oauth/apple.ts
EVIDENCE: [E1-E6]

Findings БЕЗ CODE_QUOTE или VERIFY_CMD → автоматически помечаются [UNVERIFIED] и понижаются на 1 severity.

---

Deduplication Protocol

4 параллельных агента Wave 1 НЕИЗБЕЖНО найдут одно и то же. Без дедупликации — отчёт раздут на 30-40%.

Lead между Wave 1 и Wave 2:

1. Собрать все findings в единый список
2. Группировать по FILE — findings на один и тот же файл:строку = кандидаты на дупликат
3. Для каждой группы:
   • Одинаковая проблема → оставить finding с лучшим CODE_QUOTE, удалить дубли, пометить [DEDUP: merged W1-security-3 + W1-quality-7]
   • Разные проблемы на одном файле → оставить оба
4. Пометить каждый finding источником: SOURCE: w1-security

Ожидаемый dedup rate: 15-25%

---

Lite Mode (/wave-audit lite)

9 агентов = дорого. Для малых проектов (<30 файлов) или быстрых проверок:

• Wave 1: 2 агента (security+runtime merged, quality+structure merged)
• Wave 2: пропуск (lead делает quick false-positive check сам)
• Wave 3: упрощённый — priority list + Go/No-Go, без cross-domain analysis

Ожидаемое покрытие: ~75% от full mode. Стоимость: ~30% от full mode.

---

Diff Mode (/wave-audit diff)

Изменил 5 файлов — зачем аудитить все 90?

1. git diff --name-only HEAD~N → список изменённых файлов
2. Для каждого изменённого файла → найти зависимости (importers, tests)
3. Scope Wave 1 агентов ТОЛЬКО на: changed files + их прямые зависимости
4. Wave 2 gap-hunter дополнительно проверяет: не пропущены ли transitive dependencies

Ожидаемое покрытие: ~90% для changed code. Стоимость: ~40% от full mode.

---

Lead Automation Protocol

Lead = bottleneck. Между волнами lead вручную собирает, форматирует, дедуплицирует, передаёт. Минимизируем ручную работу.

Между Wave 1 → Wave 2:

1. Собрать messages от 4 агентов (автоматически через team inbox)
2. Дедупликация по FILE (см. протокол выше)
3. Подсчитать coverage: объединить COVERAGE_LOG всех агентов
4. Если суммарный coverage <50% — WARN пользователю: "Агенты покрыли только N% файлов"
5. Сформировать единый список → передать в промпты Wave 2

Между Wave 2 → Wave 3:

1. Собрать verifications от 4 агентов
2. Применить решения w2-false-positive-filter (удалить REJECTED)
3. Добавить new findings от w2-gap-hunter
4. Сформировать полный пакет → передать w3-synthesizer

Если агент не ответил за 10 минут:

• Продолжить без него, пометить [AGENT_TIMEOUT: w1-runtime]
• В финальном отчёте указать неполное покрытие

---

Wave 2 Context Overflow Protection

Если Wave 1 выдала 30+ findings, Wave 2 агенты теряют фокус на последних.

Правило: MAX 20 findings per Wave 2 agent

• Если findings >20: разбить на 2 batch по приоритету
• Batch 1 (HIGH+CRITICAL) → Wave 2 агентам
• Batch 2 (MEDIUM+LOW) → Wave 2 агентам вторым проходом ИЛИ lead проверяет сам
• В отчёте пометить: BATCH_2_REVIEWED_BY: lead (менее глубокая проверка)

---

Метрика эффективности

После каждого запуска записать в отчёт:

AUDIT METRICS:
- Wave 1 findings: N (raw, before dedup)
- Wave 1 deduplicated: N (after dedup, -N%)
- Wave 1 coverage: N% (union of all agents' COVERAGE_LOGs)
- Wave 1 unverified: N (findings without CODE_QUOTE)
- Wave 2 rejected: N (false positive rate: N%)
- Wave 2 new findings: N (gap rate: N%)
- Wave 2 architecture conflicts: N
- Wave 3 groups: N (optimization rate: N%)
- Total agents: 9 (4+4+1) | lite: 3 (2+0+1)
- Total confirmed: N
- Agent timeouts: N
- Mode: full | lite | diff