gz-arb
Use to wrap QA commands in ARB receipts for attestation evidence or to audit lint patterns from receipts.
SKILL.md.claude/skills/gz-arb/SKILL.md
GitHubgz arb
Overview
Agent Self-Reporting middleware: wrap QA commands (ruff, ty, unittest, coverage) and emit schema-validated JSON receipts to artifacts/receipts/. These receipts are the canonical attestation evidence cited in Heavy-lane OBPI closeout claims per AGENTS.md § Attestation.
When to Use
- Producing Heavy-lane attestation evidence (receipt IDs for lint, typecheck, tests, coverage)
- Debugging a failing QA step and needing a deterministic receipt artifact
- Summarizing recurring advice from recent lint runs to tune agent guardrails
- Auditing QA compliance across an ADR or release cycle
Workflow
Wrap the QA step via ARB — pick the appropriate verb. For any claim category in the canonical list below (the list's home since 2026-09-17), use the canonical invocation from that table; those commands are locked by
CANONICAL_STEP_COMMANDSand divergence is flagged bygz arb validateas non-canonical provenance (GHI #199).uv run gz arb ruff <paths>— ruff lint (canonical for lint claims)uv run gz arb typecheck— wrapsty check . --exclude features/**, the same target asgz typecheckandgz closeout(canonical for type-check claims). Do not restate the scope from memory: the verb and the gate both READCANONICAL_STEP_COMMANDS["typecheck"], so the table is the answer whenever this line disagrees with it.uv run gz arb step --name unittest -- uv run unittest-parallel -t . -s tests --buffer— canonical for tests-pass claimsuv run gz arb coverage— canonical for coverage-floor claimsuv run gz arb step --name mkdocs -- uv run mkdocs build --strict— canonical for docs-build-clean claims
The canonical invocations apply to
uv run gz obpi complete,uv run gz adr emit-receipt, anygzCLI attestation string, andgit commit -mmessages. Worked example of an enriched attestation:docs/governance/agent-contract-rationale.md#attestation--worked-example.uv run gz arb step --name <name> -- <command>— any step not named in the canonical table (diagnostic or bespoke QA only; not valid attestation provenance)uv run gz arb ty— rawuv run ty checkpassthrough; not an alias ofgz arb typecheck(which wraps the canonical scope with the ARB schema). Usegz arb tywhen you need the rawtyoutput without ARB receipt emission, or to pass customtyflags directly.
Validate the emitted receipts —
uv run gz arb validate --limit 20Summarize recent receipts —
uv run gz arb advise --limit 20Extract recurring patterns (optional) —
uv run gz arb patternsCite receipt IDs in the attestation per
AGENTS.md§ AttestationBound the store (periodic, after harvesting) —
uv run gz arb archive --older-than 30d --dry-run, then without--dry-runto relocate. Move-not-delete: aged receipts go toartifacts/receipts/archive/, and a receipt whose id is cited in the ledger is never moved, because a citation must keep resolving. Run it AFTER steps 3–4, so the harvest verbs have already read what they were going to read. There is nopurgeverb by design (GHI #594).
Example
# Produce full attestation evidence for Heavy-lane closeout.
# Each invocation below is the canonical form. This skill is the home of the
# list since 2026-09-17; AGENTS.md § Attestation points here. Receipt name
# prefixes: arb-ruff-, arb-step-typecheck-, arb-step-unittest-,
# arb-step-coverage-, arb-step-mkdocs-.
uv run gz arb ruff src tests
uv run gz arb typecheck
uv run gz arb step --name unittest -- uv run unittest-parallel -t . -s tests --buffer
uv run gz arb coverage
uv run gz arb step --name mkdocs -- uv run mkdocs build --strict
uv run gz arb validate --limit 10
uv run gz arb advise --limit 10
Output Contract
gz arb ruff/step/ty/coverage— exit 0 on success, 1 on command failure, 2 on ARB internal error; receipt always emitted toartifacts/receipts/<run_id>.jsongz arb validate— human text by default;--jsonfor machine-readablegz arb advise— human text;--jsonfor machine-readablegz arb patterns— Markdown report by default;--compactfor one-liner;--jsonfor machine-readablegz arb archive— human summary of the plan/result buckets;--jsonfor machine-readable;--dry-runclassifies without moving
Validation
- Confirm receipts appear under
artifacts/receipts/after each wrapped run. - Run
uv run gz arb validateand confirminvalid=0before citing receipt IDs in attestations.
References
- Binding rule:
AGENTS.md§ Attestation (em-dash pattern + canonical invocations + lane behavior + receipt-ID discipline) - Deep-dive:
docs/governance/arb-middleware.md(core concept, command surface, receipt schema, exit codes, rationale) - Command docs:
docs/user/manpages/arb.md - Manpage:
docs/user/manpages/arb.md - Absorption record: OBPI-0.25.0-33 under ADR-0.25.0