gz-adr-audit

gz-adr-audit

Execute reproducible ADR verification to move from COMPLETED → VALIDATED.

Persona

Active driver: pipeline-orchestrator — read .gzkit/personas/pipeline-orchestrator.md and adopt its behavioral identity before executing this skill. The audit is a sequenced ceremony (verify proof → reproduce → demonstrate value); step-discipline and ceremony-completion are not rules to follow — they are who you are while running it.

Persona Dispatch

The audit is read-only judgment work — a single driver scoring its own findings is the optimistic-bias failure mode spec-reviewer's anti-traits literally name. Dispatch the following personas as independent subagents to produce the evidence the driver synthesizes:

Personas not dispatched: implementer (no code written in this ceremony — if audit reveals a defect requiring code, file a GHI via /ghi-author and route to a fresh OBPI brief, never spawn an implementer inside the audit).

The mechanical attestation that these dispatches occurred is governed by ADR-pool.obpi-pipeline-dispatch-attestation Target Scopes #5/#6 (Pool / HEAVY — awaiting promotion). This skill body declares the T1 contract; the pool ADR's promotion will bind T2 receipts (gz validate --pipeline-review-receipts, persona_adopted ledger events).

Persona doctrine reference: ADR-0.0.11-persona-driven-agent-identity-frames (Validated).

Common Rationalizations

Red Flags

• AUDIT.md contains only mechanical checkmarks without a Feature Demonstration section
• Agent marks ADR as VALIDATED without running uv run gz adr report to confirm lifecycle change
• Audit proofs directory is empty or contains only pass/fail text without actual command output
• Value demonstration uses generic language that could apply to any ADR
• Validation receipt emitted before all shortfalls are resolved

Two-phase workflow: See AGENTS.md § Two-Phase ADR Workflow

Layer 2 Trust Model

This is a Layer 2 tool — it consumes proof from the ledger rather than re-running verification commands.

Trust Chain:

1. Layer 1 tools (gz-obpi-sync, gz adr audit-check) run tests, check coverage, validate evidence
2. Layer 1 writes proof to logs/obpi-audit.jsonl with status entries
3. This tool reads proof — if all briefs show PASS/Completed, skip re-verification
4. Gate 5 attests to the presence of proof, not re-execution

Why trust the ledger?

• Re-running tests in Layer 2 duplicates Layer 1 work
• Gate 5's job is to verify proof exists, not regenerate proof
• Human attestation observes artifacts, not re-executes them

When to force re-verification:

• If ledger entries are older than 7 days (staleness threshold)
• If you suspect ledger corruption or tampering
• If Layer 1 tools have been updated since last audit

In these cases, run uv run gz audit <adr-id> first to regenerate ledger proof.

Assets

• assets/AUDIT_PLAN.template.md — Plan scaffold (scope, checks, risk focus)
• assets/AUDIT.template.md — Annotation shell (✓/✗/⚠, summary, attestation)

Audit Procedure

Prerequisite: ADR is COMPLETED (all briefs done, tests/coverage/docs pass).

1. Plan

Each Bash invocation starts a fresh shell, so do NOT export shell variables across calls. Inline the full ADR directory path in every command so each Bash call is self-contained. Substitute the real ADR directory (e.g. docs/design/adr/adr-0.0.x/ADR-0.0.16-foo-slug) for the placeholder below.

mkdir -p docs/design/adr/adr-x.y.x/ADR-x.y.z-slug/audit/proofs

• Read ADR prose, extract all claims
• Create audit/AUDIT_PLAN.md with checks for each claim
• Run uv run gz cli audit for governance issues
• Legacy note: docs/design/audit/** remains historical only; new audits live under the ADR folder.

2. Verify Ledger Completeness

Before running any commands, check ledger proof:

uv run gz adr audit-check <adr-id>

If ledger is complete (all briefs PASS):

• Skip to Step 3 (Fidelity Gate) — no re-verification needed
• Trust Layer 1 proof from obpi-audit
• Record "Ledger proof verified" in audit notes

If ledger is incomplete or missing:

Audit-check failure has two causes that look identical at the CLI but require opposite remediation. Diagnose before editing:

• (a) Genuinely missing coverage — no test asserts the flagged REQ's semantics. Remediation: author a REQ-derived test (per the Red→Green→Refactor rhythm in .gzkit/rules/tests.md § Red-Green-Refactor), then decorate it with @covers(REQ-X.Y.Z-NN-MM). Re-run uv run gz audit <adr-id> to write fresh ledger entries, then return to Step 2.
• (b) Coverage-shape drift — a test exists but pins an obsolete output string or asserts a shape the REQ did not mandate. Remediation: re-derive the assertion from the OBPI brief's REQ semantics per .gzkit/rules/tests.md § "Tests assert semantics, not strings" (Invariant 6f, canonical home). Backfilling a cosmetic @covers decorator without re-deriving the assertion is the forbidden anti-pattern — it silences gz adr audit-check while leaving the semantic gap intact.

After remediation, re-run uv run gz audit <adr-id> to write fresh ledger entries, then return to Step 2.

Force re-verification (optional):

If you need to regenerate proof (staleness, suspicion, etc.), run the validation commands:

Each Bash invocation starts a fresh shell — inline the full ADR directory path in every command (substitute the real path for the placeholder below):

uv run -m unittest -q > docs/design/adr/adr-x.y.x/ADR-x.y.z-slug/audit/proofs/unittest.txt 2>&1
uv run mkdocs build -q > docs/design/adr/adr-x.y.x/ADR-x.y.z-slug/audit/proofs/mkdocs.txt 2>&1
uv run gz closeout <adr-id> --dry-run > docs/design/adr/adr-x.y.x/ADR-x.y.z-slug/audit/proofs/gates.txt 2>&1

Record ✓/✗/⚠ outcomes for each check.

3. Fidelity Gate (MANDATORY — bound, replaces prose Demonstrate Value)

An audit that only verifies mechanical checks (tests pass, coverage met) without holding the ADR's thesis against the running system is incomplete.

Before ADR-0.0.73 this step was prose ("Demonstrate Value") — agent-written narrative graded by nothing, the exact theater the verification-layer audit exists to kill. It is now a bound, runnable gate: the audit ceremony invokes the SAME standalone fidelity gate the closeout ceremony invokes (one gate, two consumers — gzkit.fidelity.assert_fidelity_for_ceremony). gz audit runs it automatically; you do not narrate it.

What the gate does:

uv run gz adr fidelity <ADR-ID>

It parses the ADR Decision's ## Fidelity Assertions block and RUNS each assertion's command against the running system, comparing observed vs expected exit. A failed assertion blocks the audit (exit 3) before any validation receipt is written — a red thesis cannot record a false validated.

Absence policy (graceful migration, OBPI-0.0.73-04): an ADR that carries no ## Fidelity Assertions block is flagged with a warning (the prose 'Demonstrate Value' step is gone — absence is surfaced, not papered over with agent prose) but does not hard-block the in-flight audit. Hard presence-enforcement lives at ADR closeout (ADR-0.0.73 Boundary Invariant #4) and the new-ADR template. The back-fill of fidelity blocks onto already-VALIDATED ADRs is a separate forced sweep.

Authoring duty: if the ADR under audit has no block yet, author a ## Fidelity Assertions table (claim / command / expected-exit rows that exercise the ADR's thesis) before closeout — do not substitute prose.

Relationship to closeout ceremony: both ceremonies invoke the identical gate, so running one satisfies the other's fidelity step. There is no separate prose demonstration to write in either path.

4. Document

Populate audit/AUDIT.md with:

• Fidelity Gate section (from Step 3 — each assertion's claim, command, expected vs observed exit, pass/fail)
• Execution log (✓/✗/⚠ per check)
• Evidence index (links to proof files)
• Summary table (completeness, integrity, alignment)

5. Identify Shortfalls

Review for:

• Incomplete implementations (claimed features not shipped)
• Misalignments (code ≠ docs ≠ tests)
• Missing value demonstration (feature never shown working)
• Unexplained anomalies

Content truncated.