---
name: gz-check
persona: main-session
description: Run full quality checks in one pass. Use for pre-merge or pre-attestation quality verification.
category: code-quality
lifecycle_state: active
owner: gzkit-governance
last_reviewed: 2026-04-12
model: haiku
metadata:
  skill-version: "1.4.0"
---

# gz check

## Overview

Unified quality gate for all code verification. Replaces the individual
`/lint`, `/test`, `/format`, `/gz-typecheck`, and `/gz-arb` skills.

## Individual Commands

| Command | Purpose |
|---------|---------|
| `uv run gz lint` | Ruff linting + PyMarkdown |
| `uv run gz format` | Ruff auto-formatting |
| `uv run gz typecheck` | Static type checks (ty) |
| `uv run gz test --obpi OBPI-X.Y.Z-NN` | Tests covering one OBPI's REQs (pipeline Stage 3) |
| `uv run gz test` | Full unittest suite |
| `uv run gz test --bdd` | Unit tests + behave (ADR closeout / Heavy-lane) |
| `uv run gz check` | All of the above in one pass |

## When to Use

- **Quick fix-up:** Run individual commands (`gz lint`, `gz format`) after small edits
- **Pre-merge / pre-attestation:** Run `gz check` for the full suite
- **Before `gz git-sync --apply`:** Run `gz check` first
- **Before Gate 2 / Gate 3 verification:** Full suite required
- **Before closeout and attestation workflows:** Full suite required

## Workflow

1. Run `uv run gz check` with the required options.
2. Summarize results, including evidence and any follow-up gates.
3. **Claude surface check** (Claude Code only): After quality gates pass,
   validate Claude-specific surfaces are healthy. If issues found, invoke
   `@claude-code-guide` to diagnose against current Anthropic documentation.

## Claude Surface Check

When running in Claude Code as a pre-merge or pre-attestation check, run the
following — each item is a concrete tool invocation, not a prose claim:

1. **No hook errors at session start** — review the session start banner for
   hook failures. If any appear, invoke `@claude-code-guide` to diagnose
   against current Anthropic documentation. Do not proceed to attestation
   while hook errors are unresolved.
2. **Generated surfaces match canonical source** — run
   `uv run gz validate --surfaces`. Exit code 0 means `.claude/skills/`
   mirrors `.gzkit/skills/` and `.claude/rules/` mirrors `.gzkit/rules/`.
   Non-zero exit means run `uv run gz agent sync control-surfaces` and
   re-validate.
3. **CLAUDE.md is under budget** — read `CLAUDE.md` with the Read tool and
   check that the final line number reported is ≤ 200. Read returns
   numbered lines so the count is observable without invoking `wc`. If
   over budget, trim before attestation (200-line ceiling for optimal
   adherence).

## Full Quality Evidence Sequence

When deterministic receipts are needed (e.g., for audit evidence):

```bash
uv run gz lint
uv run gz typecheck
uv run gz test --bdd    # full suite including behave — pre-attestation
uv run gz check
```

## Validation

- Verify command output reflects the requested scope.
- If governance state changed, confirm with `uv run gz status` or `uv run gz state`.

## Example

```bash
# Full quality check (preferred)
uv run gz check

# Individual checks when iterating
uv run gz lint
uv run gz format
uv run gz typecheck
uv run gz test

# If Claude surface issues found, diagnose:
@claude-code-guide look at .claude/settings.json — are all hook
references valid? Any deprecated patterns?
```

## Common Rationalizations

These thoughts mean STOP — you are about to skip the gate that catches drift:

| Thought | Reality |
|---------|---------|
| "I only changed one file — `gz lint` is enough" | `gz check` is the unified gate for a reason: lint passes can hide type or test regressions. Pre-merge always runs the full suite. |
| "Tests pass locally, no need to typecheck" | `ty` catches signature drift that unittest can't. The two checks are complementary, not redundant. |
| "Hook errors at session start are cosmetic" | The Claude surface check is part of `gz check` precisely because hook errors mean an agent is operating against stale governance. Resolve before attestation. |
| "The mirrors look fine, skip the surface check" | Canon/derived drift is silent until it isn't. The mirror parity check is cheap; the bug it prevents is expensive. |
| "I'll run the individual commands instead of `gz check`" | Individual commands skip the Claude surface check and the deterministic ordering. Use them for iterative fix-up, not for pre-merge or pre-attestation. |
| "Coverage is close to 40% — round up" | The coverage floor is fail-closed at 40.00%. Rounding rationalizes a regression. |
| "PyMarkdown warnings are noise" | PyMarkdown is part of `gz lint` because docs are first-class deliverables under the Gate 5 Runbook-Code Covenant. Fix or document the exception. |

## Red Flags

- Closing a brief or attestation without running `gz check`
- Running `gz lint` but not `gz typecheck` or `gz test` before merge
- Hook errors in session-start output that were never resolved
- `.claude/skills/` divergent from `.gzkit/skills/` (sync not run)
- CLAUDE.md over 200 lines (budget exceeded, adherence drops)
- Coverage dropped below 40% but the brief was marked complete
- Skipping the full sequence "because nothing meaningful changed"

## References

- Command implementation: `src/gzkit/cli.py`
- User docs: `docs/user/manpages/index.md`
