---
applyTo: "docs/design/adr/**"
---
<!-- Generated by gz agent sync — do not edit -->

# ADR Audit (gzkit)

Purpose: verify ADR completion claims using reproducible evidence.

## Audit sequence

1. Verify linked OBPI evidence:

```bash
uv run gz adr audit-check ADR-<X.Y.Z>
```

2. Run quality checks:

```bash
uv run gz lint
uv run gz test
uv run gz typecheck
uv run mkdocs build --strict
```

3. Run closeout/audit lifecycle in order:

```bash
uv run gz closeout ADR-<X.Y.Z> --dry-run
uv run gz attest ADR-<X.Y.Z> --status completed
uv run gz audit ADR-<X.Y.Z>
```

4. Emit audit receipt:

```bash
uv run gz adr emit-receipt ADR-<X.Y.Z> --event validated --attestor "<Human Name>" --evidence-json '{"scope":"ADR-<X.Y.Z>","date":"YYYY-MM-DD"}'
```

## Rules

- Do not run `gz audit` before attestation.
- If audit-check fails, diagnose whether the flagged REQ is (a) genuinely uncovered — author a REQ-derived test and decorate with `@covers(REQ-X.Y.Z-NN-MM)` — or (b) covered by a test whose assertion drifted from REQ semantics — re-derive the assertion per `.gzkit/rules/tests.md` § "Tests assert semantics, not strings" (Invariant 6f). Never backfill a cosmetic `@covers` decorator to silence audit-check without re-deriving the assertion.
- Keep `docs/user/runbook.md` and `docs/governance/governance_runbook.md` aligned with runtime behavior.

## Legitimate-authoring exemptions (covers-backfill heuristic)

The same-commit-window backfill heuristic exempts five structurally distinct shapes from the cosmetic-backfill anti-pattern. Each exemption preserves the GHI #272/#309 protection against decorators silencing audit-check without re-derived semantics; if the receipt is anchored to the same commit as the decorator AND the file/block was created in the same commit, the exemption is suppressed (the GHI #309 triple still flags).

| Shape | Source | Source-side annotation | Receipt-coupled flag? |
|-------|--------|------------------------|------------------------|
| Same-commit FILE creation | GHI #382 | none — file went 0→N lines in intro commit | suppressed (still flags) |
| Same-commit BLOCK creation | GHI #466 Component B | none — function `def` line shares decorator's intro SHA | suppressed (still flags) |
| Inline regression-invariant overlay marker | GHI #466 Component A | `# audit-exempt: regression-invariant-overlay <reason>` on decorator line; reason text required | NOT suppressed (operator attestation by design) |
| `Ceremony:` trailer | GHI #386 | trailer in `_EXEMPT_CEREMONIES` (e.g. `Ceremony: gz-git-sync`) | n/a (trailer governs) |
| Subject-suffix marker | GHI #390 | parenthesized suffix at end of subject (e.g. `(gz git-sync)`) | n/a (subject governs) |

**When to use the inline marker (Component A):** A new `@covers(REQ-X)` decorator is being added to an existing test whose assertion structurally IS the REQ being claimed — typical case is a regression-invariant REQ pointing at a test that already enforces the prior invariant (e.g. byte-parity tests covering a "no regression of OBPI-N" REQ). The marker is the operator's explicit attestation that the overlay is legitimate, not cosmetic backfill. Reason text is mechanically required so the exemption can't be a one-token escape hatch — keep it terse but informative (typical form: pointer to the OBPI/REQ relationship). Do NOT use the marker when the right move is to author a new REQ-derived assertion; the marker is reserved for the genuine overlay shape.
