Code Quality Gate

---
name: code-quality-gate
description: >-
  Build, test, format, and lint requirements that must pass before
  code review. Load when checking implementation completeness or
  running the quality gate.
compatibility:
  - claude-code
  - github-copilot
  - opencode
reads:
  - docs/testing-principles.md
  - docs/architecture-principles.md
metadata:
  version: "1.0"
  author: team
---

## Quality Gate

Before invoking reviewers, all checks must pass. Run `make ci` to execute the full pipeline.

### Required Checks

| Check | Command | What It Verifies |
|---|---|---|
| Tidy | `make tidy-check` | `go.mod` and `go.sum` carry no drift; fails instead of rewriting |
| Format | `make fmt-check` | Every file is formatted; fails instead of rewriting |
| Vet | `go vet ./...` | Common mistakes caught |
| Lint | `make lint` | golangci-lint rules pass |
| Deps | `make deps-check` | No prohibited dependencies |
| Test | `go test ./...` | All tests pass |
| Build | `make build` | Binary compiles |
| Handoff log | `python3 scripts/handoff.py validate` | Every record in `.scratch/handoff.jsonl` parses and passes its schema — a raw write that corrupted the log fails here, on every tool. A failure appends a `build-failure` with `failed_check: "handoff-log"`. Absent log (no pipeline work yet): the check passes vacuously. |
| Autofix audit | `python3 scripts/handoff.py audit-autofix` (procedure below) | Every `design-doc-autofix` and `prd-autofix` record stays within bounds; every uncommitted change to a design-doc path is covered by a `design-doc-autofix` or `design-block` record since last commit. |
| Design-doc sync | `python3 scripts/grading.py contracts-sync --feature <req_id>` | The slice's requirement id appears in `docs/prd.md` and `docs/system-design.md` — the Contracts table names its implementer. Vacuous without the design brief. |

### Autofix Audit Procedure

Run this before declaring the gate passed, before appending `build-pass`:

```bash
python3 scripts/handoff.py audit-autofix
```

The command executes the audit mechanically; the protocol's prose home is `handoff-routing` § Root-Applied Autofix on Doc Paths. The audit is log-global — a record under any slice is audited. Step 1 re-validates every autofix record not superseded by its own slice's latest owning-expert record — a `design-doc-autofix` by a later `design-block`, a `prd-autofix` by a later `prd-entry`. The checks: eligible path per record type, eligible category, the 5-line/200-char caps, no heading/anchor/REQ-ID/code-fence/link-target change, `new_content` byte-identical to `source_finding.fix`. Step 2 confirms every uncommitted design-doc change is covered by a `design-doc-autofix` or `design-block` record newer than the last commit. The scan is design-doc-scoped by decision — `docs/prd.md` has its own `prd-autofix` trail and stays outside it. A `prd-entry` carrying `scope_overrides` covers the non-goal ADR its change records; `docs/adr/README.md` is covered whenever every other dirty ADR path is. The design-block append runs this coverage check itself, so an uncovered path here means a design-doc edit no record claims.

Exit 0 declares the autofix-audit check green; record the outcome alongside the other quality-gate results. On a non-zero exit do NOT declare gate-pass. Append a `build-failure` record with `failed_check: "autofix-audit"`, its `error_output` carrying the command's stderr. Set `abort_reason` by the failing record type: `"design-mismatch"` for a `design-doc-autofix` failure or an uncovered design-doc edit; `"prd-mismatch"` for a `prd-autofix` failure. When both classes fail, abort `"design-mismatch"` first — the re-run surfaces the PRD failures. Build-Failure Recovery's abort short-circuit routes the record to the owning expert, who reverts or correctly re-applies the change under its own doc ownership. It then appends its superseding record — a `design-block` with `supersedes_record_at`, or a `prd-entry` — the substantive record that closes its dispatch and restarts the gate. Records at or before that superseding record are superseded on the re-run; the supersession is what terminates the audit loop. Never author a `review-feedback` record — its schema admits reviewer authors only.

### Design-Doc Sync Procedure

Run `python3 scripts/grading.py contracts-sync --feature <req_id>` with the other checks. Exit 0 declares the design-doc sync green; record `contracts-sync` in `gate_checks_run`. On a non-zero exit do NOT declare gate-pass and do not edit `docs/system-design.md` — the design doc has its own writers. Append a `build-failure` with `failed_check: "contracts-sync"` and `abort_reason: "design-mismatch"`, its `error_output` carrying the command's stderr. Build-Failure Recovery's abort short-circuit routes it to the `system-design-expert`, whose superseding `design-block` places the requirement in the design doc and restarts the gate.

### Optional Checks

| Check | Command | When Required |
|---|---|---|
| Race detector | `go test -race ./...` | When concurrency is involved (requires gcc) |
| Container build | `make podman-build` | When project uses containers |

## IDE Static Analysis (optional)

When an IDE semantic oracle is available, run its static-analysis pre-check on the diff before declaring the gate passed: inspection **errors** fail the gate (treat like a compile error); **warnings** seed self-review findings. Accelerator only — `make ci` stays authoritative, and a client without an oracle relies on the checks above. Procedure, error/warning classification, and the stale-index caveat live in the `goland` skill. Report this pre-check honestly: claim it only if the GoLand MCP tool `get_file_problems` actually ran this run (see `goland` § Report only checks you actually ran). An un-run pre-check is reported as "not run / IDE not consulted", never as clean.

## Completion Criteria

A feature is complete when:

- [ ] All TDD cycles finished
- [ ] Self-review pass complete (see `tdd-workflow` § Self-Review Pass — a clause walk, not a record)
- [ ] All tests pass (`go test ./...`)
- [ ] IDE static-analysis pre-check clean on touched files — check this box only if the GoLand MCP tool `get_file_problems` actually ran this run; otherwise mark it "n/a (IDE not consulted)" (see "IDE Static Analysis" above)
- [ ] Format check passes (`make fmt-check`)
- [ ] Module files tidy (`make tidy-check`)
- [ ] Vet passes (`go vet ./...`)
- [ ] Project builds (`make build`)
- [ ] Lint passes (`make lint`)
- [ ] Dependency policy passes (`make deps-check`)
- [ ] Handoff log validates (`python3 scripts/handoff.py validate`; skip when `.scratch/handoff.jsonl` does not exist)
- [ ] `build-pass` carries `gate_checks_run` naming the check verbs that ran (schema-required, min one item) — the evidence the reviewer fan-out gates on
- [ ] Review plan emitted after `build-pass` — automatic: the append runs the engine; verify its `review-plan: appended …` line, and on an engine warning run `python3 scripts/grading.py review-plan --feature <req_id>` by hand. See `review-workflow` § Risk-Proportional Roster
- [ ] Autofix audit passes (see "Autofix Audit Procedure" above)
- [ ] Design-doc sync passes (`contracts-sync`; presence is the floor — the right Contracts rows stay reviewer judgment)
- [ ] Config example reflects any new/changed config fields (if applicable)
- [ ] Every reviewer in the active pass's roster holds a latest `approved` (`route-spec` § Gate 5); the plan names that roster, and the full floor plus declared extras is the fail-closed default
- [ ] No pending escalations (or human approved)

## Stop at done

Once every box above is checked, stop. Polish past the bar — extra refactors, additional tests for the same behavior, prose tightening on a passing PR — spends tokens without raising quality and is explicitly out of scope. The nine-clause bar is defined across `.claude/skills/tdd-workflow/tdd-principles.md`, `docs/testing-principles.md`, `docs/architecture-principles.md`, and `docs/security-principles.md`, with the canonical slug list in the `review-workflow` skill's `reference.md` § Quality-Bar Clause Mapping; if the diff meets the nine clauses, the work is done.