code-audit

name	code-audit
description	Batch audit of production files against CQ1-CQ29 quality gates and CAP1-CAP19 anti-patterns. Tiered output (A/B/C/D), critical gate enforcement, evidence-backed scoring, cross-file pattern analysis, and prioritized execution plan. Flags: zuvo:code-audit all | [path] | [file] | --deep | --quick | --services | --controllers
codesift_tools	{"always":["analyze_project","index_status","index_folder","index_file","plan_turn","get_file_tree","search_text","search_symbols","get_symbol","get_symbols","get_file_outline","audit_scan","find_dead_code","search_patterns","find_clones","trace_call_chain","scan_secrets"],"by_stack":{"typescript":["get_type_info","resolve_constant_value"],"javascript":[],"python":["python_audit","analyze_async_correctness","resolve_constant_value"],"php":["php_project_audit","php_security_scan","resolve_php_namespace"],"kotlin":["analyze_sealed_hierarchy","find_extension_functions","trace_flow_chain","trace_suspend_chain","trace_compose_tree","analyze_compose_recomposition","trace_hilt_graph","trace_room_schema","analyze_kmp_declarations","extract_kotlin_serialization_contract"],"nestjs":["nest_audit"],"nextjs":["framework_audit","nextjs_route_map"],"astro":["astro_audit","astro_actions_audit","astro_hydration_audit","astro_middleware","astro_sessions","astro_image_audit","astro_svg_components"],"hono":["analyze_hono_app","audit_hono_security"],"express":[],"fastify":[],"react":["react_quickstart","analyze_hooks","analyze_renders","analyze_context_graph","audit_compiler_readiness","trace_component_tree"],"django":["analyze_django_settings","effective_django_view_security","taint_trace"],"fastapi":["trace_fastapi_depends","get_pydantic_models"],"flask":["find_framework_wiring"],"jest":[],"yii":["resolve_php_service","trace_php_event","find_php_views"],"prisma":["analyze_prisma_schema"],"sql":["sql_audit"],"postgres":["migration_lint"]}}

zuvo:code-audit — Production Code Quality Triage

Systematic evaluation of production source files through the CQ1-CQ29 binary checklist and CAP anti-pattern catalog. Every file receives a tier classification based on its score, critical gate status, and detected anti-patterns. The output is a prioritized report with actionable fix plans.

When to use: Periodic health checks, before major releases, after adding many production files, when onboarding a new codebase, when code quality feels inconsistent. Out of scope: Single-file code review (use zuvo:review), refactoring (use zuvo:refactor), test quality assessment (use zuvo:test-audit), feature development (use zuvo:build).

Argument Parsing

Argument	Effect
all	Audit every production file in the project
[path]	Audit production files under a specific directory
[file]	Audit a single file with full evidence (forces deep mode)
--deep	Collect per-gate evidence and fix recommendations for every file
--quick	Binary pass/fail only, skip evidence gathering
--services	Restrict scope to service and business logic files
--controllers	Restrict scope to controller, handler, and route files

Default behavior: all --quick

Mode	Scope	Depth	Batch Size	Notes
all	Entire project	Standard	6 files/batch	Default
[path]	Directory tree	Standard	6 files/batch	Scoped
[file]	One file	Deep (full evidence)	1	Single-file deep dive
--deep	Any scope	Full evidence	6 files/batch	Slower, thorough
--quick	Any scope	Binary only	10 files/batch	Fast triage
--services	Service files	Standard	6	Filter by file type
--controllers	Controller files	Standard	6	Filter by file type

Mandatory File Loading

PHASE 0 — Bootstrap (always, before reading any input)

  1. ../../shared/includes/codesift-setup.md      -- [READ | MISSING -> STOP]
  2. ../../shared/includes/no-pause-protocol.md   -- [READ | MISSING -> WARN] (HARD: no mid-loop pauses across files)

These files are loaded before reading the audit target files. The no-pause protocol is mandatory for any multi-file audit run.

PHASE 0.5 — Classify (read target files, determine domain)

After CodeSift setup, read the target file(s). Classify the primary domain:

• data: touches DB queries, transactions, ORMs, migrations
• async: touches promises, streams, workers, event emitters
• security: touches auth, input validation, secrets, crypto
• general: none of the above (or mixed)

Print: [CLASSIFIED] Domain: {data|async|security|general}

PHASE 1 — Conditional Load (based on domain)

Include	data	async	security	general
../../rules/cq-checklist.md	Full	Full	Full	Full
../../shared/includes/env-compat.md	Full	Full	Full	Full
../../rules/cq-patterns.md	CQ6,7,9,16,17 focus	CQ15,17 focus	CQ4,5 focus	Full
../../rules/security.md	SKIP	SKIP	Full	SKIP
../../rules/file-limits.md	SKIP	SKIP	SKIP	Full

Print loaded files:

PHASE 1 — LOADED:
  [list with READ/SKIP status per file]

DEFERRED — Load at completion

  ../../shared/includes/run-logger.md        -- [READ at final step]
  ../../shared/includes/retrospective.md        -- [READ at final step]

If PHASE 0 file missing: STOP. The plugin installation is incomplete.

Environment Compatibility

Read ../../shared/includes/env-compat.md for agent dispatch patterns, path resolution, and progress tracking across Claude Code, Codex, and Cursor.

MANDATORY TOOL CALLS — Audit Validity Gate

This audit is INVALID if any tool below is skipped when its trigger condition holds. "DEFERRED", "N/A", "no diff vs prior audit", "--quick mode" are NOT valid reasons. The presence of trigger artifacts (a code file list, language detection, dep manifest) is what dictates the call — never delta or risk.

Required tool list

Tool	Trigger	Reason	Skip allowed?
audit_scan	Always (any project with code files)	COMPOUND replacement for find_dead_code+search_patterns+find_clones+analyze_complexity+analyze_hotspots — primary CQ engine	NO
find_dead_code	Always	CQ13 unused exports across symbol graph (kept as fallback if audit_scan unavailable)	NO when audit_scan also unavailable
search_patterns(empty-catch)	Always	CQ8 empty-catch detection — TOOL-VERIFIED gate, only authoritative source	NO
find_clones	Always	CQ14 duplication ≥0.7 similarity — TOOL-VERIFIED gate	NO
scan_secrets	Always	CAP5 hardcoded secret pre-scan — every audit, every project	NO
trace_call_chain	--deep mode OR finding cites a function with cross-file impact	CQ4 ownership trace; required to verify "this is internal" claims	NO when --deep
Stack-specific (nest_audit/framework_audit/python_audit/php_project_audit/etc.)	Framework/language detected	Stack-specific CQ patterns no generic scan reproduces	NO when language/framework matches

Forbidden escape hatches

Value	Forbidden when	Required value instead
audit_scan: DEFERRED	EVER	audit_scan: <findings_count>
scan_secrets: skipped (CAP5 covered manually)	EVER	scan_secrets: <count>
find_clones: N/A (--quick mode)	EVER	find_clones: <cluster_count>
codesift: unavailable	mcp__codesift__* was in deferred-tools session-start banner	codesift: deferred-not-preloaded (FAILURE: skill required preload)
retrospective: skipped	EVER	retrospective: appended (retros.log + retros.md)

Required POSTAMBLE — retrospective + verify-audit gates

After the audit report is written, the audit is NOT complete until:

1. zuvo/audits/code-quality-audit-<date>.md (or zuvo/audits/code-audit-<date>.md) is on disk — at the project root (zuvo/ resolves via git rev-parse --show-toplevel; override $ZUVO_OUTPUT_DIR. See ../../shared/includes/report-output-location.md).
2. ~/.zuvo/append-runlog is called with the Run line — this triggers BOTH:
   • retro-gate: requires a matching RETRO: entry in ~/.zuvo/retros.log for skill=code-audit project=<this>. If missing → exit 2, runs.log NOT appended.
   • audit-content gate: runs ~/.zuvo/verify-audit on the report. Every Tier D/C finding (and every Tier B critical-gate-near-miss) must contain at least one path/to/file.ext:LINE citation that resolves in the current tree. Findings without citations get rejected. If rejected → fix the report (add file:line per finding), re-run append-runlog.
3. Print RETRO_APPENDED: retros.log=YES retros.md=YES (verified) and confirm exit 0 from append-runlog.

If you reach the Run line and stop without calling append-runlog: the audit is INVALID regardless of finding count. The Validity Gate's gate_status flips to FAIL — postamble incomplete and the verdict overrides to INCOMPLETE.

Mandatory acknowledgment (REQUIRED — print verbatim before Phase 0)

Mandatory-tools-acknowledgment: I will run audit_scan + scan_secrets + search_patterns(empty-catch) + find_clones + find_dead_code + trace_call_chain (in --deep mode or for cross-file impact verification) + stack-specific tools (nest_audit/framework_audit/python_audit/etc. when detected) in this audit. Each finding will cite a `path/to/file.ext:LINE` resolving in the current tree.

---

CodeSift Integration

Use the deterministic preload helper FIRST. Before issuing any ToolSearch, run:

~/.zuvo/compute-preload code-audit "$PWD"

Copy the printed [CodeSift matching trace] block verbatim and issue the printed ToolSearch(query="select:...") line without modification. Math gate: [CodeSift loaded] tools=N must equal [Expected after load] tools=N from the helper. If they differ → [PRELOAD MATH MISMATCH] and abort before Phase 1.

CodeSift setup completed in PHASE 0. Use CodeSift tools for all discovery and analysis when available. If not found, fall back to Grep/Read/Glob and inform the user once.

After editing any file: index_file(path="/absolute/path/to/file")

CodeSift-Accelerated Discovery

When CodeSift is available, run these checks before the manual CQ evaluation to pre-populate deterministic findings:

1. find_dead_code(repo, file_pattern=SCOPE) -- Pre-populate CQ13 (unused exports). Mark as TOOL_VERIFIED.
2. search_patterns(repo, "empty-catch") -- Pre-populate CQ8 (swallowed errors). Mark as TOOL_VERIFIED.
3. find_clones(repo, min_similarity=0.8) -- Pre-populate CQ14 (duplicated logic blocks >10 lines). Mark as TOOL_VERIFIED.

TOOL_VERIFIED findings have deterministic HIGH confidence and bypass the confidence gate. They go directly to the report.

Manual CQ1-CQ29 evaluation still runs for all 29 gates. CodeSift pre-scan accelerates 3 of 29 checks.

Degraded Mode (CodeSift unavailable)

CodeSift tool	Fallback	Lost capability
find_dead_code	Skip CQ13 pre-scan	No automated dead code detection
search_patterns("empty-catch")	Grep for catch\s*\( with empty body	Less precise pattern matching
find_clones	Skip CQ14 pre-scan	No automated clone detection
get_file_tree	find command	Slower, no symbol counts
get_file_outline	Read each file	More tokens consumed
trace_call_chain	Grep for imports	No transitive caller analysis
search_symbols	Grep for function names	Less precise results

---

Phase 0: Discovery and Classification

0.1 Locate Production Files

When CodeSift is available: get_file_tree(repo, name_pattern="*.ts") (adjust extension per stack) with path filters excluding node_modules, .next, dist, __tests__.

When unavailable:

find . \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" \) \
  ! -name "*.test.*" ! -name "*.spec.*" ! -name "test_*" ! -name "*_test.*" \
  ! -path "*/node_modules/*" ! -path "*/.next/*" ! -path "*/dist/*" ! -path "*/build/*" \
  ! -path "*/__pycache__/*" ! -path "*/migrations/*" | sort

If the file count exceeds 80 and --deep was not explicitly requested, auto-switch to --quick mode. An explicit --deep flag always takes precedence.

0.2 Prioritize by Risk

When file count is large, process in this order:

1. CRITICAL: Guards, middleware, auth files + controllers, handlers, routes (public attack surface)
2. HIGH: Services, repositories, orchestrators, external API callers (business logic and data)
3. MEDIUM: ORM entities, models, components with logic >100 lines (data handling and UI)
4. LOW: Utilities, helpers, pure functions (least risk)

0.3 Classify Each File

Assign a code type to each file. This determines which CQ gates are high-risk and which conditional gates activate.

Signal	Code Type	High-Risk CQs	Conditional Gates
*.service.*, *.repository.*	SERVICE	CQ1,3,4,8,14,16,17,18,20	CQ16 if money fields, CQ19 if external calls
*.controller.*, *.handler.*, route.*	CONTROLLER	CQ3,4,5,12,13,19	CQ19 always (API boundary)
*.guard.*, *.middleware.*, auth in name	GUARD/AUTH	CQ4,5	--
*.tsx, *.jsx (>50 lines)	REACT	CQ6,10,11,13,15	--
*.entity.*, *.model.*, schema in name	ORM/DB	CQ6,7,9,10,17,20	CQ20 if dual fields
orchestrat, workflow, pipeline in name	ORCHESTRATOR	CQ6,8,9,14,15,17,18	CQ18 if multi-store
use*.ts/use*.tsx, useState/useEffect + hook export	HOOK	CQ6,8,10,11,15,22	CQ22 always, CQ19 if fetches data
*.utils.*, *.helpers.*, lib/	PURE	CQ1,2,10,12,16	CQ16 if money functions
Calls external API (fetch, axios, http)	API-CALL	CQ3,5,8,15,17,19	CQ19 always

When a file matches multiple types, use the most specific one.

0.4 Detect Global Error Handling Infrastructure

Before batch evaluation, search for project-wide error handling. This prevents systematic overcounting of CQ8 failures.

• NestJS: @Catch() decorator, AllExceptionsFilter, APP_FILTER provider
• Express: app.use((err, req, res, next) error middleware
• Next.js: error.tsx / global-error.tsx boundary
• Fastify: setErrorHandler
• Python: @app.exception_handler, middleware with try/except

If found, note in the report header and pass as PROJECT_CONTEXT to every batch agent. Services that let errors propagate to the global handler = CQ8 PASS. Only CQ8=0 when errors are swallowed (empty catch, catch-and-return-null, catch-without-rethrow).

0.5 Semgrep Pre-Scan (optional)

If semgrep is installed and the project has .semgrep/ config:

npx semgrep --config .semgrep/ --json --quiet 2>/dev/null

Semgrep findings auto-score the matching CQ as 0 for affected files (deterministic = HIGH confidence). Exception: CQ4 findings from semgrep need dataflow verification before auto-scoring. LLM evaluation still runs full CQ1-CQ29 but skips deep analysis on CQs already flagged.

If semgrep unavailable: skip silently. This enhances the audit but does not gate it.

---

Phase 1: Batch Evaluation

Split files into batches of 6-8 (10 in --quick mode). For each batch, spawn a Task agent or process inline depending on environment (see env-compat.md).

Each Task agent dispatch:

Agent: Code Quality Auditor (per batch)
  model: "sonnet"
  type: "general-purpose"  # read-only: Read + CodeSift only, no Edit/Write (Explore lacks mcp__codesift__*)
  instructions: evaluate files against CQ1-CQ29 checklist (see Agent Prompt below)
  input: batch file list, PROJECT_CONTEXT, CODESIFT_AVAILABLE

Agent Prompt (provided to each batch agent)

You are a production code quality auditor. Evaluate each file below against the CQ1-CQ29 binary checklist.

PROJECT_CONTEXT:
[INSERT: global error handler info, or "No global error handler detected"]

RED FLAG PRE-SCAN (do this FIRST, before full checklist):
Scan for these. If any found, use TIER-D SHORT FORMAT and skip full CQ1-CQ29:
- Hardcoded secret (API key, password, token in source) -> AUTO TIER-D
- SQL string concatenation with user input -> AUTO TIER-D
- eval() / new Function() with non-literal input -> AUTO TIER-D
- dangerouslySetInnerHTML without DOMPurify -> AUTO TIER-D

TIER-D SHORT FORMAT:
### [filename]
Code type: [TYPE]
Lines: [count]
Red flags: [CAP5/CAP6/CAP7/CAP8] -> AUTO TIER-D
Details: [what was found, line number]
Tier: D

QUICK HEURISTICS (not Tier-D triggers, but predict score):
- 5+ `as any` casts -> likely score <= 10
- File > 400 lines -> likely CQ11=0
- 0 try/catch with DB/API calls -> likely CQ8=0
- parseFloat on money field -> likely CQ16=0
- await inside for/forEach loop -> likely CQ17=0

CLASSIFY the file first (SERVICE / CONTROLLER / GUARD / HOOK / REACT / ORM / ORCHESTRATOR / PURE / API-CALL).

CHECKLIST (score 1=YES, 0=NO, N/A=not applicable with justification):
CQ1:  No string/number where union/enum/branded type appropriate?
CQ2:  All public function return types explicit? No implicit any?
CQ3:  CRITICAL -- Boundary validation complete? Required fields, format/range, runtime schema?
CQ4:  CRITICAL -- Guards reinforced by query-level filtering? Guard NOT sole defense?
CQ5:  CRITICAL -- No sensitive data in logs/errors/responses?
CQ6:  CRITICAL -- No unbounded memory from external data? Pagination/streaming?
CQ7:  DB queries bounded? LIMIT/cursor present? Slim payloads?
CQ8:  CRITICAL -- Infra failures handled? Timeouts on outbound? No empty catch?
CQ9:  Multi-table mutations in transactions? FK order correct?
CQ10: Nullable values handled? No silent null propagation? No unsafe array[0]/.find()?
CQ11: Functions <= 50 lines? Single responsibility?
CQ12: No magic strings/numbers? No duplicate config keys?
CQ13: No dead code? No commented-out blocks?
CQ14: CRITICAL -- No duplicated logic (>10 lines repeated)?
CQ15: Every async awaited or fire-and-forget with .catch()? No dropped promises?
CQ16: Money uses exact arithmetic (Decimal/integer-cents)? No float for money?
CQ17: No sequential await in loops where batch/parallel works?
CQ18: Cross-system data consistency? Multi-store writes handle partial failures?
CQ19: API request AND response validated by runtime schema?
CQ20: Each data point ONE canonical source? No dual fields?
CQ21: CONDITIONAL -- No TOCTOU? State machine transitions use CAS? Mutations idempotent?
CQ22: CONDITIONAL -- All listeners/timers/subscriptions cleaned up on unmount?
CQ23: CONDITIONAL -- Cache has TTL or explicit invalidation? No stale-forever entries?
CQ24: CONDITIONAL -- API changes additive only? Breaking changes have deprecation path?
CQ25: New code follows existing project patterns? No special snowflakes?
CQ26: Structured logger with context (requestId, userId), not plain console.log?
CQ27: Log levels correct? `error` for infra failures only, not validation?
CQ28: CONDITIONAL -- Timeout hierarchy correct? client < server < DB?
CQ29: Workspace path alias (@/, ~/, #/) used for imports >=3 hops deep when alias is configured? N/A if no alias in workspace.

ANTI-PATTERNS (each found = noted, severity attached):
CAP1:  Empty catch block -- HIGH
CAP2:  Plain `console.log` in production -- MEDIUM. `console.warn`/`console.error` allowed ONLY when paired with Sentry.captureMessage/captureException on the same code path; otherwise MEDIUM.
CAP3:  `as any` / `as unknown as X` without validation -- MEDIUM (x5+ = HIGH). `as unknown as <DomainType>` after Prisma/ORM queries = HIGH (silent contract bypass).
CAP4:  @ts-ignore without justification -- MEDIUM
CAP5:  Hardcoded secret -- AUTO TIER-D
CAP6:  Unsanitized HTML reaching DOM or persistence -- AUTO TIER-D. Covers `dangerouslySetInnerHTML` without DOMPurify, `editor.commands.setContent(rawHtml)`/raw-HTML mode without pre-save sanitization, paste-as-HTML, programmatic raw HTML writes. Display-time sanitization alone is INSUFFICIENT if persistence path is unsanitized.
CAP7:  eval() / new Function() with dynamic input -- AUTO TIER-D
CAP8:  SQL string concatenation OR `$queryRaw`/`$executeRawUnsafe` against tenant tables without organizationId in WHERE -- AUTO TIER-D
CAP9:  File exceeds type limit (service <=450, controller <=300, hook <=250, component <=200, helper <=100) OR inline sub-component >=50 LOC nested in a parent component file -- HIGH (2x file limit = AUTO TIER-D)
CAP10: Function > 100 lines (2x the 50L limit) -- HIGH
CAP11: parseFloat/Number() on money field -- HIGH
CAP12: await inside for/while without batch alternative -- MEDIUM
CAP13: 7+ useState in one component, OR >=3 mutually-exclusive dialog/modal boolean flags (collapse to discriminated union `dialog: { kind: '...' } | null`), OR state mirroring URL params managed via local useState (use router query API) -- MEDIUM
CAP14: Business logic >10 lines in component body that has no DOM dependency -- MEDIUM
CAP15: API URL built without `encodeURIComponent` on dynamic path segments, OR hardcoded base URL string-concat (`` `${BASE}/api/foo/${id}` ``), OR unencoded user-controlled token in URL path/query -- HIGH. MUST use a single `buildApiUrl(path, pathParams)` helper and validate enum-typed segments against an allowlist before interpolation.
CAP16: Client auth-token plumbing race (deferred-promise wait for provider, token injected mid-flight, no readiness gate before first request), OR missing 401-> refresh-> retry-once on REST clients while tRPC has it (or vice versa), OR unsigned/dev-only tokens accepted as auth credentials in any environment -- HIGH
CAP17: `error.message` rendered directly to UI/DOM without a curated `userMessageFor(error)` mapping -- HIGH. Leaks server stack/PII; map known error types to safe messages and fall back to a generic "Something went wrong".
CAP18: `throw new Error(...)` from a service/injectable/handler -- MEDIUM. Use a typed exception class instead (BadRequestException, NotFoundException, custom DomainError); bare Error loses HTTP status mapping and can leak the original message into 5xx response bodies.
CAP19: Mutating endpoint, AI/expensive operation (LLM call, export, generation), webhook receiver, or tRPC procedure without a rate limiter (ThrottlerGuard, custom limiter, queue with concurrency cap) -- HIGH. tRPC bypassing the project-wide ThrottlerGuard = always violation.

N/A HANDLING: N/A items are excluded from both numerator and denominator. Score = passed / applicable. N/A requires justification.

STATIC CRITICAL GATE: CQ3, CQ4, CQ5, CQ6, CQ8, CQ14 -- any = 0 -> capped at Tier C.
CONDITIONAL CRITICAL GATE:
- CQ16 -> critical if file handles money (prices, costs, discounts, invoices)
- CQ19 -> critical if CONTROLLER or API-CALL type. Thin controller exception: if only returns typed service data, gate does not activate.
- CQ20 -> critical if file defines entities with dual fields
- CQ21 -> critical if concurrent mutations on same resource
- CQ22 -> critical if creates subscriptions, timers, observers
- CQ23 -> critical if uses Redis, Memcached, or in-memory cache
- CQ24 -> critical if modifies existing API endpoint signatures
- CQ28 -> critical if defines timeouts at 2+ architectural layers

CQ8 NOTE: Check PROJECT_CONTEXT. If global error handler exists, services that let errors propagate = CQ8 PASS. Only CQ8=0 when errors are swallowed.
CQ15 NOTE: `return somePromise` inside async function is NOT a missing await -- async auto-flattens. Only flag when promise is neither returned nor awaited.
CQ19 NOTE: Thin controllers that only return typed service data get gate cap = B, not C.

OUTPUT FORMAT per file:
### [filename]
Code type: [TYPE]
Lines: [count]
Red flags: [CAP5/6/7/8 = auto Tier-D; or "none"]
Score: CQ1=[0/1] CQ2=[0/1] ... CQ29=[0/1/N/A]
Anti-patterns: [CAP IDs found, or "none"]
Total: [passed]/[applicable] ([%]) -- N/A excluded
Static gate: CQ3=... CQ4=... CQ5=... CQ6=... CQ8=... CQ14=... -> [PASS/FAIL]
Conditional gate: [which activated] -> [PASS/FAIL/none]
Evidence (critical gates scored 1): [CQ=evidence pairs, file:line]
Tier: [A/B/C/D]
Top 3 issues: [brief]

TIER CLASSIFICATION:
  A (>=25/29, all active gates PASS): Production-ready
  B (22-24, all active gates PASS): Conditional pass
  C (17-21, or any critical gate FAIL with score >=17): Significant rework
  D (<17 or AUTO TIER-D red flag): Critical -- immediate fix

IMPORTANT:
- Read the FULL file before scoring
- Do red flag pre-scan first
- For CQ3: check for DTO/schema at entry point. "Validation exists somewhere" = 0.
- For CQ4: look for ownership check followed by query WITHOUT that owner in WHERE. In --deep mode for SERVICE files, read the associated controller to verify.
- For CQ11: count lines per function. Limits vary by type (see file-limits.md).
- For CQ14: list methods >20 lines. Compare pairs for structural similarity.
- For CQ16: search for parseFloat/Number() on price/cost/amount fields.
- For CQ17: search for await inside loops. Check if batch alternative exists.
- For CQ19: check both request DTO AND response shape validation.
- For CQ20: search for field_id + field_name pairs.
- Evidence REQUIRED for --deep mode (all CQs). For --quick: evidence required only for critical gates scored 1.
- GATE N/A REPORTING: N/A gates are skipped, not converted to 1.

Files to audit:
[BATCH FILE LIST]

---

Phase 2: Aggregate Results

Collect all agent outputs and build the summary report.

Summary Table

# Code Quality Audit Report

Date: [date]
Project: [name]
Files audited: [N]
Mode: [quick/deep]

## Summary by Tier

| Tier | Count | % | Action |
|------|-------|---|--------|
| A (>=25/29) | [N] | [%] | Production-ready |
| B (21-23) | [N] | [%] | Targeted fixes before merge |
| C (16-20) | [N] | [%] | Significant rework |
| D (<16 or red flag) | [N] | [%] | Critical -- immediate fix |

## Summary by Code Type

| Type | Files | Avg Score | Worst CQ | Notes |
|------|-------|-----------|----------|-------|
| SERVICE | [N] | [avg] | [most failed CQ] | |
| CONTROLLER | [N] | [avg] | | |

## Critical Gate Failures

| File | Score | Failed CQs | Impact |
|------|-------|------------|--------|

## Conditional Gate Failures

| File | Score | Failed CQs | Why Activated | Impact |
|------|-------|------------|---------------|--------|

## Red Flag Summary (Auto Tier-D)

| File | Red Flag | Details |
|------|----------|---------|

## Top Failed CQs (across all files)

| CQ | Category | Fail count | % of files | Pattern |
|----|----------|-----------|------------|---------|

## Anti-pattern Hot Spots

| Anti-pattern | Severity | Files affected | Instances |
|-------------|----------|---------------|-----------|

## Tier D -- Critical Fix Queue (worst first)
## Tier C -- Rework Queue
## Tier B -- Targeted Fix Queue
## Tier A -- Production Ready

Phase 3: Cross-File Analysis

After per-file scoring, run these cross-cutting checks:

1. Cross-file duplication -- If CQ14=0 in multiple files in the same module, check for shared duplicated logic between those files
2. Inconsistent patterns -- If some services use transactions (CQ9=1) and structurally similar ones do not (CQ9=0), flag the inconsistency
3. Validation chain gaps -- If a controller has CQ3=1 but the service it calls has CQ3=N/A ("internal"), verify the service is truly never called from another entry point
4. Money handling inconsistency -- If some files use Decimal (CQ16=1) and others use float for the same domain, flag project-wide drift

Add findings under a ## Cross-File Issues section.

Phase 3b: Adversarial Review on Audit Report (MANDATORY — do NOT skip)

After the audit report is generated, run cross-model validation to catch score inflation and gate inconsistency. Runs on ALL audits (not just --deep).

adversarial-review --mode audit --files "zuvo/audits/code-quality-audit-[date].md"

If adversarial-review is not in PATH: ~/.claude/plugins/cache/zuvo-marketplace/zuvo/*/scripts/adversarial-review.sh

Wait for complete output. Then:

• CRITICAL (FAIL gate not in verdict, severity mismatch) → fix in report before delivery
• WARNING (N/A abuse, skipped check) → append to Known Gaps section
• INFO → ignore

Phase 4: Report and Execution Plan

Save the report to: zuvo/audits/code-quality-audit-[date].md If --deep mode: also save per-file detail to zuvo/audits/code-audit-details/[filename].md

Execution Plan (appended to report)

## Recommended Execution Plan

### Goal
- Raise score from [current avg]/29 to min [target]/29
- Close all critical gate FAILs
- Add regression tests for every P0/P1 change

### Priority Order
1. P0 (production blockers): [Tier D red flags + critical gate FAILs]
2. P1 (high risk / stability): [remaining Tier C issues]
3. P2 (maintenance / readability): [Tier B gaps]

### Fix Plan (per issue)

| Priority | CQ/CAP | Where (file:line) | What to change | Tests needed | Est. |
|----------|--------|-------------------|----------------|-------------|------|

### Project-Wide Patterns
- [N] files missing input validation (CQ3) -- consider global validation pipe
- [N] files using float for money (CQ16) -- adopt Decimal project-wide

### Re-audit Expected Deltas

| CQ/CAP | Before | After | Files affected |
|--------|--------|-------|----------------|

## Completion Gate Check

Before printing the final output block, verify every item. Unfinished items = pipeline incomplete.

COMPLETION GATE CHECK [ ] Domain classified and printed: [data/async/security/general] [ ] Red flag pre-scan ran on every batch [ ] Global error handler detection ran [ ] Adversarial review ran on audit report (--mode audit) [ ] Cross-file analysis section present [ ] Report saved to zuvo/audits/ [ ] Backlog updated for deferred findings [ ] Run: line printed and appended to log

## CODE AUDIT COMPLETE

### Validity Gate (REQUIRED — print BEFORE Run line, AFTER retro append + append-runlog)

VALIDITY GATE triggers_held: code_files: yes() language: <typescript|python|php|kotlin|javascript|...> framework: <nextjs|nestjs|astro|hono|react|django|flask|...|none> mode: <quick|standard|deep> required_tool_calls: audit_scan: [ compound findings | NOT_CALLED — VIOLATES_TRIGGER] scan_secrets: [ hits | NOT_CALLED — VIOLATES_TRIGGER] search_patterns(empty-catch): [ CQ8 hits | NOT_CALLED — VIOLATES_TRIGGER] find_clones: [ clone clusters | NOT_CALLED — VIOLATES_TRIGGER] find_dead_code: [ unused exports | NOT_CALLED — VIOLATES_TRIGGER] trace_call_chain: [ chains traced | not_required (non-deep) | NOT_CALLED — VIOLATES_TRIGGER] stack_specific (nest_audit/framework_audit/python_audit/etc.): [ | not_required | NOT_CALLED — VIOLATES_TRIGGER] postamble: retros_log_appended: [yes(bytes_added=N) | NOT_APPENDED — VIOLATES_REQUIRED_POSTAMBLE] retros_md_appended: [yes(entry_count=N) | NOT_APPENDED — VIOLATES_REQUIRED_POSTAMBLE] verify_audit_pass: [yes(/ findings) | NOT_RUN | REJECTED] gate_status: [PASS | FAIL — ]

If `gate_status = FAIL`, override the VERDICT below to `INCOMPLETE` regardless of finding count, append `[VALIDITY GATE FAIL]` to the Run line NOTES column, and add a backlog item `B-code-audit-incomplete-<date>`.

The Validity Gate must be printed **AFTER** the retro append and `~/.zuvo/append-runlog` call (so postamble fields can be filled with `yes(verified)`). Printing it before guarantees `NOT_APPENDED`.

Run: <ISO-8601-Z>\tcode-audit\t<project>\t<N-critical>\t<N-total>\t<VERDICT>\t-\t<N>-dimensions\t<NOTES>\t<BRANCH>\t<SHA7>\t<INCLUDES>\t<TIER>


### Retrospective (REQUIRED — load + fill BEFORE the Run line append)

Load `../../shared/includes/retrospective.md` if not already loaded. Follow the retrospective protocol: gate check → 9 structured questions → TSV emit → markdown append to `~/.zuvo/retros.md` AND `~/.zuvo/retros.log`.

Then append the Run line via the retro-gated wrapper:

```bash
printf '%b\n' "$RUN_LINE" | ~/.zuvo/append-runlog

The wrapper:

• Verifies the matching RETRO: entry in retros.log (skill+project). Missing → exit 2, runs.log NOT appended.
• Runs ~/.zuvo/verify-audit on the audit report. Findings without path/to/file.ext:LINE citations → exit 2, audit REJECTED.
• On both pass: appends to runs.log and prints confirmation.

If the wrapper exits non-zero: do NOT manually append to runs.log. Fix the cause (add retro, add file:line citations to findings, etc.) and re-run.

VERDICT: PASS (0 critical findings), WARN (1-3 critical), FAIL (4+ critical), INCOMPLETE (Validity Gate FAIL).

## Phase 5: Backlog Persistence

Persist findings to `memory/backlog.md`:

1. Read `memory/backlog.md`. If missing, create with template.
2. Fingerprint each finding: `file|CQ-id|signature`. Dedup: existing = increment `Seen`. New = append `B-{N}`.
3. Delete resolved items (Tier A files with open items).

Full protocol: `../../shared/includes/backlog-protocol.md`.

**Which findings to persist:**
- **Tier D** (red flags, <16): ALL findings -- CRITICAL severity
- **Tier C** (critical gate FAIL or 16-20): ALL critical gate failures -- HIGH severity
- **Tier B** (21-23): only critical gate near-misses -- MEDIUM severity
- **Tier A** (>=24): do NOT persist. Delete any open backlog items for Tier A files.

## Phase 6: Next-Action Routing

After the report, propose what to do next:

| Audit Result | Suggested Action | Reason |
|--------------|-----------------|--------|
| Tier D files exist | "Fix Tier D files" | Security/critical issues first |
| CQ14=0 in 2+ files (shared duplication) | `zuvo:refactor` on shared module | Duplication across files = structural problem |
| Same CQ fails in 3+ files | "Fix [CQ] across all affected files" | Pattern fix |
| CQ18=0 (multi-store sync) | `zuvo:build` to add sync mechanism | New infrastructure needed |
| Structural issues (wrong layers, circular deps) | `zuvo:architecture review [path]` | Needs architectural view first |
| Only Tier B/C with varied issues | "Fix top 3 critical gate failures" | Highest ROI |
| All Tier A | No action needed | Everything is production-ready |

## Execution Notes

- Use **Sonnet** for all batch agents in QUICK and STANDARD modes
- Use **Opus** for DEEP mode batch agents
- Process batches sequentially in Cursor/Codex. Claude Code may parallelize with up to 6 Task agents.
- Read the project's AGENTS.md or CLAUDE.md first for stack-specific conventions
- Estimated durations: QUICK ~2 min for 50 files, DEEP ~15 min for 50 files