Skip to content

gz-arb(1) — ARB self-reporting middleware

NAME

gz arb — wrap QA commands and emit schema-validated receipts

SYNOPSIS

Text Only
gz arb ruff [--fix] [--soft-fail] [PATHS...]
gz arb step --name NAME [--soft-fail] -- COMMAND [ARGS...]
gz arb ty COMMAND [ARGS...]
gz arb typecheck
gz arb coverage COMMAND [ARGS...]
gz arb validate [--limit N] [--json]
gz arb advise [--limit N] [--json]
gz arb patterns [--limit N] [--compact] [--json]

DESCRIPTION

The arb command group wraps QA commands (ruff, ty, unittest, coverage) and emits schema-validated JSON receipts to artifacts/receipts/. These receipts are the canonical attestation evidence cited in Heavy-lane OBPI closeout claims.

ARB's purpose is to reduce the rate of agent-authored defects (first-pass failures) by aggregating recurring lint patterns into actionable guardrail recommendations — not to generate workflow noise.

VERBS

ruff

Run ruff check via ARB and emit a lint receipt.

Text Only
gz arb ruff [--fix] [--soft-fail] [PATHS...]

Options:

  • --fix — Apply ruff auto-fixes
  • --soft-fail — Emit receipt but always return exit 0 (measurement-only mode)

Example:

Bash
gz arb ruff src/gzkit

step

Wrap an arbitrary command and emit a step receipt.

Text Only
gz arb step --name NAME [--soft-fail] -- COMMAND [ARGS...]

Example:

Bash
gz arb step --name unittest -- uv run unittest-parallel -t . -s tests --buffer

ty, coverage

Dedicated wrappers for common step invocations.

Bash
gz arb ty check .
gz arb coverage

typecheck

Canonical Heavy-lane type-check receipt producer. Wraps the exact command gz typecheck runs (uv run ty check . --exclude features/**) so ARB receipts cannot diverge from the governance gate's scope. Use this for attestation evidence rather than gz arb ty check <custom-scope>.

Both this verb and the gate READ CANONICAL_STEP_COMMANDS["typecheck"] rather than spelling the command, so they cannot drift apart — the GHI #199 failure. The scope covers the whole tree except features/, which is excluded because behave step functions annotate context attributes that ty rejects by design. It was src-only until 2026-08-08; widening it brought scripts/ under the gate, including the SessionStart orientation hook that runs before every agent's first response.

Bash
gz arb typecheck

See GHI #199 for the class-of-failure this closes.

validate

Validate recent receipts against gzkit.arb.lint_receipt.v1 / gzkit.arb.step_receipt.v1.

Text Only
gz arb validate [--limit N] [--json]

advise

Summarize recent lint receipts into guardrail tuning recommendations.

Text Only
gz arb advise [--limit N] [--json]

patterns

Extract recurring anti-patterns from receipts as Markdown, compact summary, or JSON.

Text Only
gz arb patterns [--limit N] [--compact] [--json]

EXIT CODES

Code Meaning
0 Command succeeded; receipt created
1 Command failed; receipt created with findings
2 ARB internal error (receipt directory, config, invalid step)

RECEIPTS

Receipts are written to the directory resolved by:

  1. GZKIT_ARB_RECEIPTS_ROOT environment variable (absolute path, used by tests)
  2. arb.receipts_root from .gzkit.json (default: artifacts/receipts)

Each receipt is a JSON file named by run_id. Schemas live under data/schemas/:

  • arb_lint_receipt.schema.json ($id: gzkit.arb.lint_receipt.schema.json)
  • arb_step_receipt.schema.json ($id: gzkit.arb.step_receipt.schema.json)

SEE ALSO

  • gz check — full quality pass (lint, typecheck, test, drift)
  • gz drift — spec-test-code drift scanner
  • AGENTS.md § Attestation — binding rule contract (em-dash pattern, canonical invocations, lane behavior, receipt-ID discipline)
  • docs/governance/arb-middleware.md — ARB middleware deep-dive (core concept, command surface, receipt schema, exit codes, rationale)

HISTORY

Absorbed from airlineops/src/opsdev/arb/ under OBPI-0.25.0-33 (2026-04-14), which closed a governance vacuum where the former .gzkit/rules/arb.md documented a fully-working gz arb surface that did not exist in gzkit. See the ADR-0.25.0 closeout record for the forensic trace. The .gzkit/rules/arb.md file was merged into .gzkit/rules/attestation-enrichment.md on 2026-04-21 under Phase 1 of the control-surface consolidation. On 2026-04-23, attestation-enrichment.md itself was folded under ADR-0.0.20 OBPI-03: binding content (em-dash pattern, canonical invocations, lane behavior) moved to AGENTS.md § Attestation, and middleware deep-dive moved to docs/governance/arb-middleware.md.