gz arb red¶

Witness a test failing without the code it covers — by BEHAVIOR REQ, or by commit.

Usage¶

Bash

gz arb red --req <REQ-ID> [--base <commit>] [--obpi <OBPI-ID>]
gz arb red --commit <commit>

Exactly one of --req or --commit is required.

Reconstructs the base tree in a throwaway git worktree, copies in only the test files, and runs the REQ's covering test there. The production hunks are deliberately left behind — that asymmetry is the whole experiment: the test meets the code as it was before the implementation landed.

@covers parity proves a BEHAVIOR REQ has a covering test. It never proves that test can fail. A test authored after the production code, passing on its first run, is byte-indistinguishable from a genuine RED-first test. This command is the mechanical witness the pipeline's Red-Green-Refactor instruction lacked (GHI #642).

Emits an ARB red receipt and a red_receipt_emitted ledger event. Commit mode emits its own receipt and a red_commit_receipt_emitted event (§ Receipt).

Options¶

Option	Description
`--req`	BEHAVIOR REQ id to witness
`--commit`	Commit whose production hunks to witness against its own tests (see § Commit mode)
`--base`	Commit to run the test against (default: `HEAD`, the pre-change tree)
`--obpi`	Owning OBPI id, recorded on the ledger event

Failure classes¶

The failure_class is the verdict, not decoration.

Class	Meaning	Verdict
`assertion`	The test failed on an assertion	Strong RED. The test genuinely depends on the implementation.
`error`	The test failed on an ImportError or other exception	Weak RED. It failed for the wrong reason — usually the new symbol does not exist yet. Recorded as `error`; never silently equated with an assertion RED.
`none`	The test passed with the production hunks withheld	No RED. The test cannot fail when the business logic changes (`AGENTS.md` § DO IT RIGHT Rule 6), so it witnesses nothing. Blocking.
`not-applicable`	The run could not tell; `output_tail` names the cause	Not a verdict on the test (GHI #839). Six causes: nothing was withheld; the base run executed no test; the baseline is invalid because the covering tests do not pass on the current tree; a covering test did not execute in the base graft (mismatched source/test identity); the run failed only in tests the REQ does not name (GHI #1154); or a run exceeded the hang bound and was stopped, on either tree (GHI #1179). An invalid baseline is repaired on HEAD before re-running.

Commit mode (`--commit`, GHI #927)¶

A guard added on the direct-fix route (fix(<scope>): … (GHI #N)) has no REQ, so --req has no subject there. --commit keys the witness on the commit instead: each production hunk the commit added is reverted to its parent's text, one at a time, and the test modules the same commit touched are run against the mutant through gzkit.mutation_witness (baseline, activation, bytecode isolation and failure cause all verified). Hunks that change only comments, docstrings or blank lines are skipped, and pure deletions are not mutated. So are hunks that only change a function's argument or return annotations in a module with from __future__ import annotations, unless the function carries a decorator that may read its signature. Class-field annotations (which Pydantic reads) and annotations in modules that evaluate them at definition time are still mutated.

A hunk is text, not a unit of behavior, so a fix whose hunks depend on each other (a helper and its call site, a signature and its callers) has hunks whose lone revert raises instead of asserting (GHI #1153). When a hunk's revert cannot be graded on a green baseline, each guard statement starting in it (if, for, while, with, try, match, raise, assert, return, continue, break) is replaced with pass, one at a time, and graded as its own row (unit: statement, reason guard in <hunk>). A hunk holding no guard statement, such as a signature line or a constant, makes no guard claim: it is listed with unit: declaration and stays outside the verdict.

Verdict	Meaning	Exit
`driven`	Every hunk or guard statement was `killed`: a test in the commit fails without it	0
`undriven`	A hunk or guard statement `survived`: reverting it left the commit's tests passing	1
`no-tests`	The commit changes production code and no test module	1
`inconclusive`	A hunk or guard statement could not be graded (baseline not green, the revert raised an error rather than an assertion, or its test run exceeded the hang bound) — a claim about the run, not the tests. A hung mutant is one `inconclusive` row and the sweep continues; when the commit's own tests hang on the commit's own tree the experiment is void, no hunk row is printed and the reason is stated (GHI #1179)	0
`no-production-hunks`	Nothing behavioral to witness	0

The declared test set is the commit's own test modules, deliberately: a fix that adds a guard owes a test, in the same commit, that fails without it. A historical commit whose tests no longer pass in a fresh checkout reads inconclusive, never a verdict. Every commit-mode run, whatever its verdict, writes a receipt and a red_commit_receipt_emitted ledger event, and prints the receipt id after the verdict (arb red commit=<sha12> verdict=<verdict> receipt=<run_id>), so the verdict a GHI close cites can be resolved (GHI #1152).

Examples¶

Bash

# Witness a REQ whose implementation is uncommitted in the working tree.
gz arb red --req REQ-0.33.0-01-01

# Attribute the witness to its owning OBPI.
gz arb red --req REQ-0.33.0-01-01 --obpi OBPI-0.33.0-01-airlock-data-model-and-events

# Witness against an explicit base (e.g. before the implementation commit).
gz arb red --req REQ-0.33.0-01-01 --base HEAD~1

# Witness the guards the last direct-fix commit added (no REQ needed).
gz arb red --commit HEAD

Exit Codes¶

Code	Meaning
0	A RED was witnessed (`assertion`, or the weaker `error`); receipt created
1	No covering test found, or `failure_class: none` — the test cannot fail; with `--commit`, a surviving hunk or no test module
2	ARB internal error (worktree creation failed, git unavailable)

Receipt¶

REQ mode (--req):

Schema: gzkit.arb.red_receipt.v1 (data/schemas/arb_red_receipt.schema.json)
Prefix: arb-red-<REQ-ID>-<uuid4 hex>
Ledger event: red_receipt_emitted
Read by gz validate --red-parity, a bound gz check step.

Commit mode (--commit):

Schema: gzkit.arb.red_commit_receipt.v1 (data/schemas/arb_red_commit_receipt.schema.json)
Prefix: arb-red-commit-<commit sha12>-<uuid4 hex>
Records the commit, verdict, per-hunk outcomes and reasons, test modules and exit status
Ledger event: red_commit_receipt_emitted
Cited by ghi-close step 7c when a direct fix closes; validated by gz arb validate.

Notes¶

Against a REQ whose implementation is already committed, the witness runs on the parent of the commit that introduced the covering test (base_provenance: reconstructed, GHI #849). When no tree withholds the implementation it reports not-applicable, never none (GHI #839). The covering tests also run first on the current tree, and the base run's class stands only when the named covering tests executed there and produced it (GHI #1154).

gzkit's trunk is green and pre-commit runs unittest, so a RED can never be committed to main. That is why the witness is an isolated base-tree run rather than superpowers' commit-the-failing-test.