gz-adr-audit

name	gz-adr-audit
persona	pipeline-orchestrator
description	Gate-5 audit templates and procedure for ADR verification. GovZero v6 skill.
category	adr-audit
compatibility	GovZero v6 framework; provides audit procedure for COMPLETED→VALIDATED ADR transition
metadata	{"skill-version":"6.13.0","govzero-framework-version":"v6","govzero-author":"GovZero governance team","govzero-spec-references":"docs/governance/GovZero/charter.md, docs/governance/GovZero/audit-protocol.md","govzero-gates-covered":"Gate 5 (Human Attestation)","govzero_layer":"Layer 2 - Ledger Consumption","trust_model":"Trusts Layer 1 ledger proof for mechanical checks; re-verifies the ADR thesis via the bound fidelity gate (ADR-0.0.73) — gz adr fidelity RUNS the Decision's assertions against the running system"}
gz_command	audit
invocation	uv run gz audit <adr-id>
lifecycle_state	active
owner	gzkit-governance
last_reviewed	"2026-07-26T00:00:00.000Z"
model	opus

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:

Persona	Function in this ceremony	Invoked at
spec-reviewer	Independent requirement-tracing against ledger proof; verifies each OBPI's claimed REQ coverage holds against a fresh read of brief and tests	Steps 1–2 (Verify Ledger Proof, Reproduce Key Evidence)
quality-reviewer	Independent assessment of the ADR package's structural coherence: do the OBPIs cohere into the ADR's claimed capability, or is the integration brittle?	After Step 2, before Step 3
narrator	Frames the Step 4 audit documentation (AUDIT.md) in operator-value terms; the Step 3 fidelity gate is now bound and runs itself — no prose value-demonstration to compose	Step 4 (Document)

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

Thought	Reality
"All OBPIs passed individually, the ADR is obviously complete"	Individual OBPI completion doesn't prove ADR-level integration. The audit verifies the whole.
"Tests pass and coverage is met, the audit is done"	That's verification, not fidelity. Step 3 (Fidelity Gate) runs the ADR's thesis against the running system, not just its tests.
"The closeout ceremony already covered this"	Audit and closeout invoke the same bound fidelity gate; running one satisfies the other's fidelity step. Mechanical checks (Step 1-2) are still independent.
"Ledger entries exist from a previous audit, I can skip re-verification"	Check staleness. Entries older than 7 days or predating code changes require fresh verification.
"This is a Foundation ADR, the audit can be lighter"	Foundation ADRs still require value demonstration. The feature must be shown working.

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

6. Remediate

For each shortfall:

• Severity (blocking/non-blocking)
• Proposed fix
• Effort estimate

Implement fixes, re-validate, update AUDIT.md.

7. Mark VALIDATED

When all shortfalls resolved:

• Sign attestation in AUDIT.md: agent signs (human already attested at OBPI completion)
• Update ADR: Status: Validated

8. Emit Validation Receipt (agent-relayed via audit-begin/audit-end)

After a successful audit the agent emits the validated receipt. The operator's verbatim audit acceptance, relayed via the --evidence-json attestation_text field, IS the Gate-5 attestation — there is no TTY ATTEST gate. The gz adr audit-begin / gz adr audit-end pair brackets the audit ceremony as a distinct operator moment. Steps:

1. Open the ceremony. uv run gz adr audit-begin <adr-id> — writes the per-ADR co-presence marker at .claude/plans/.pipeline-active-<adr-id>.json. The marker is written by the gzkit CLI itself, not by hand; the slash-command entry-point chain (operator typed /gz-adr-audit → skill ran audit-begin) is the legitimate co-presence proof the runtime accepts.

2. Operator verbal attestation. Wait for the operator's verbal ack — accept audit or verify audit. This is the ADR audit-validation acceptance, not OBPI Gate-5 closeout (which already happened on each linked OBPI; by the time /gz-adr-audit runs, every linked OBPI is attested_completed in the ledger). The audit ceremony is a distinct operator moment — accepting the audit's verification of the integrated ADR (ledger proof complete, value demonstration ran, no shortfalls remain) — and wants its own phrasing so the ledger's attestation_text field is self-documenting. The verbal ack IS the Gate-5 human-attestation event; the agent relays it into the ledger receipt.

3. Emit the receipt.

   uv run gz adr emit-receipt <adr-id> --event validated \
     --attestor "<Operator Name>" \
     --evidence-json '{"gate":5,"tests_passed":true,"tests_count":...,
                       "scope":"<adr-id>","date":"<YYYY-MM-DD>",
                       "attestation_text":"<operator verbatim ack> — <agent enrichment>"}'
   

   The receipt records evidence.attestation_type=operator-verbatim-conversational from the attestation_text field — the operator's verbatim acceptance is the Gate-5 attestation.

4. Close the ceremony. uv run gz adr audit-end <adr-id> — removes the marker. Marker hygiene matters: leaving it behind would let a second emit succeed without a fresh operator invocation, defeating the co-presence proof.

5. Verify lifecycle. uv run gz adr report <adr-id> — confirm the Lifecycle column shows Validated before declaring success.

Rules:

• Audit fails → no receipt. Only emit after all shortfalls are resolved.
• Attestor field is the operator's name (per the operator-PII rule in CLAUDE.md § Local Agent Rules — never their personal email). Do not use agent:<model-id> — validated/attested/ accepted are human-attestation events and the ledger receipt records the operator on whose behalf the agent is relaying.
• Marker hygiene. Always pair audit-begin with audit-end. If the emit fails for any reason, still run audit-end so the next ceremony starts clean.
• Do not hand-write the marker. Use the gz adr audit-begin CLI verb — hand-fabricating the marker file bypasses the ceremony entry-point.
• Idempotent: Running twice produces two ledger entries (audit trail preserved).
• Forward note (GHI #354): the taxonomy split between an agent-emittable audit-passed receipt (the derived audit-pass fact, headless-safe) and the operator-typed validated Gate-5 receipt is tracked in GHI #354. The audit-begin/audit-end pair is the closed sub-scope of #354 that unblocks /gz-adr-audit; the per-event taxonomy split remains open for that GHI to resolve.

9. Verify Lifecycle Update

MANDATORY. After emitting the receipt, confirm the lifecycle change took effect before declaring success:

uv run gz adr report <adr-id>

The Lifecycle column MUST show Validated. If it still shows Completed, the audit is not done — investigate why the state did not propagate. Do not report success to the operator until the report command confirms the change.

Recommended evidence fields:

Field	Type	Description
gate	int	Gate number (e.g., 5)
tests_passed	bool	Whether unit tests passed
coverage_pct	float	Coverage percentage
briefs_completed	int	Number of briefs completed
shortfalls_resolved	int	Number of shortfalls fixed

---

Validation Commands

Type	Command	Layer
Ledger check	uv run gz adr audit-check <adr-id>	L2
Ledger check (JSON)	uv run gz adr audit-check <adr-id> --json	L2
ADR lifecycle summary	uv run gz adr status <adr-id> --json	L1
Unit tests	uv run -m unittest -q	L1
Docs build	uv run mkdocs build -q	L1
Governance	uv run gz cli audit	L1
Config paths	uv run gz check-config-paths	L1
Heavy gates	uv run gz closeout <adr-id> --dry-run	L1
OBPI reconcile	uv run gz audit <adr-id>	L1+L2
Coverage discovery	rg -n '@covers("ADR-' tests	L1
Open audit ceremony	uv run gz adr audit-begin <adr-id> — writes per-ADR co-presence marker.	L1
Emit receipt	uv run gz adr emit-receipt <adr-id> --event validated --attestor "<Operator Name>" --evidence-json '{...,"attestation_text":"<operator verbatim ack>"}' after operator's verbal accept audit / verify audit (NOT OBPI-closeout attest completed).	L2
Close audit ceremony	uv run gz adr audit-end <adr-id> — removes marker.	L1

Layer key: L1 = runs verification, L2 = reads ledger proof

When to run evidence checks:

• Before marking an ADR Completed/Validated
• During CI checks for a target ADR
• Before gz closeout, gz attest, or gz audit
• Before the closeout ceremony (/gz-adr-closeout-ceremony)

---

Gate Checklist

COMPLETED (Phase 1):

• All features shipped
• Unit tests pass, coverage ≥40%
• Docs complete, mkdocs builds clean
• Linting/formatting/type checks pass

VALIDATED (Phase 2):

• Audit plan created
• All checks executed with proofs
• Value demonstrated — ADR capabilities shown working with live output
• No unresolved ✗ failures
• Code matches documentation
• Examples are executable
• Validation receipt emitted to ledger
• Attestation signed (agent signs audit; human attested at OBPI completion)
• Lifecycle verified — uv run gz adr report <adr-id> shows Validated

---

Failure Modes

• Mechanical-only audit — tests pass and coverage met but the feature is never demonstrated working. The human cannot assess value from a checklist of green checkmarks alone.
• Audits drift from template structure
• No proof artifacts captured
• Shortfalls not remediated before marking VALIDATED
• Audit skips Step 3 (Fidelity Gate) and jumps straight to documentation

---

Relationship to Closeout Ceremony

gz-adr-audit and gz-adr-closeout-ceremony are complementary but independent:

Concern	gz-adr-audit	gz-adr-closeout-ceremony
Focus	Evidence verification + bound fidelity gate	Human-witnessed runbook walkthrough + bound fidelity gate
Mode	Agent-driven with human attestation	Human-driven with agent presenting
Outputs	AUDIT.md + proofs/ + ledger entries	Closeout form + attestation record
Fidelity gate	Step 3 (gz adr fidelity, bound)	EXECUTE→ATTESTATION edge (same gate, bound)

Both invoke the same bound gate (assert_fidelity_for_ceremony) — one gate, two consumers. Running either ceremony exercises the ADR's ## Fidelity Assertions against the running system; there is no separate prose value-demonstration to write or duplicate.