a3-polish

name	A3 — Polish
description	Code/content quality. Dead code, hardcoded values, leftover TODOs, weak error handling, security holes, performance traps, standards violations. Enforces the Double Gate — blocks until A1 is at zero findings.
argument-hint	<group-number> [feature-name]

A3 — Polish (Code / Content Quality)

The quality check, and the most mode-divergent lens: in code projects it means code quality; in content/process projects it means content and process quality. A3 scans for issues that compile and pass requirements but are nonetheless bad: dead code, hardcoded values, leftover TODO/FIXME, unhandled edge cases, weak error handling, security holes, performance traps, and violations of naming/formatting/dependency standards.

The Double Gate (enforced here)

Before anything else, read the A1 report for this scope and parse its finding count:

• > 0 findings → BLOCK: "A1 has N unresolved findings — fix A1 first."
• No A1 report exists → BLOCK: "No A1 report found."
• Only == 0 → A3 proceeds.

There is no override flag for this gate. You do not polish code that has drifted from its own design.

Inputs

• The constitution (the code/content standards — required) · all files in scope · the micro specs for context
• The A1 report (for the gate) and the prior A2 report · the project mode

Process

1. Enforce the Double Gate (above).
2. Scan each file against the mode-specific checklist (exhaustive pass, then a review for false positives):
   • Code mode: code quality (TODO/FIXME, dead code, hardcoded values, unused imports), edge cases (boundaries, empty states, null handling, concurrency), error handling (graceful failure, meaningful messages, recovery), security (injection, credential exposure, auth gaps, OWASP Top 10), performance (N+1 queries, needless re-renders, unindexed lookups, leaks), and standards compliance (naming, import order, style, forbidden deps).
   • Content/process mode: style consistency, structural quality (well-formed templates, required sections, logical flow), completeness (every stage has a command, every artifact a schema, every gate defined), cross-reference validity, and quality-gate clarity (measurable criteria, no vague "good enough").
3. Threat Cartography (below).
4. Residue Sweep (below).
5. Write the report to audits/{scope}-a3.md: per-category findings with reasoning traces, the Threat Cartography map, and a verdict.

Threat Cartography

Produce a map (not findings) of every error-handling construct in scope — every catch block, every Result match arm, every unwrap_or/.ok(), every custom handler/panic hook (content mode: every validation gate, fallback, default, silent-skip). Each TC-{NNN} entry records: file/lines, construct type, errors caught, silent errors (caught but never propagated, logged, or acted on), blast radius (module / feature / system), and an assessment. When an entry reveals genuine risk — a silent swallow with high blast radius, or undocumented suppression — promote it to a full finding. Summarize: handlers classified, silent swallows found, promotions, highest blast radius.

Residue Sweep

Scan for machine-generated-code smells (placeholder code, fabricated examples, copy-paste duplication, inconsistent abstraction, etc.). Each detected pattern becomes a finding R-{NN}: {category}. Applies to code and to prose/templates alike.

Precision

Not "improve this" — "rename X to Y at line Z" or "add a null check at line N." Shared finding format, zero-tolerance loop, and conviction: see docs/the-audit-system.md.

Natural language triggers

- "a3 audit group 1"
- "polish audit"
- "code quality check"