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 → run the fidelity gate); 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).

This ceremony has no artifact channel for these dispatches — they are unattested and undisclosed (GHI #770's named residual), and the receipt machinery that would record them is not yet authored (GHI #846; ADR-pool.obpi-pipeline-dispatch-attestation is Superseded into ADR-0.0.73, which delivered no receipts). Treat the mandate as binding on you, not as something a gate will catch.

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 run the same fidelity gate. The thesis is held against the running system.

Red Flags

• AUDIT.md contains only mechanical checkmarks without a Fidelity Gate 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
• Fidelity assertions so generic they could apply to any ADR
• Validation receipt emitted before all shortfalls are resolved

---

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, the OBPI pipeline) run tests, check coverage, validate evidence
2. Layer 1 writes proof to the ledger as OBPI completion and receipt events
3. This tool reads proof (gz adr audit-check) — 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/foundation/ADR-0.0.16-foo-slug) for the placeholder below.

mkdir -p docs/design/adr/<kind>/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 the Layer 1 proof the ledger carries
• 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 § Red-Green-Refactor (Tests assert semantics, not strings). 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:

Inline the full ADR directory path, as in Step 1:

uv run gz test > docs/design/adr/<kind>/ADR-x.y.z-slug/audit/proofs/unittest.txt 2>&1
uv run mkdocs build --strict > docs/design/adr/<kind>/ADR-x.y.z-slug/audit/proofs/mkdocs.txt 2>&1
uv run gz closeout <adr-id> --dry-run > docs/design/adr/<kind>/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.

This step is a bound, runnable gate, not prose: 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 committed tree — a detached worktree at HEAD, so uncommitted files cannot satisfy it and its commands cannot write to the live checkout; no buildable worktree fails closed (GHI #1156) — 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 or failing fidelity assertions (the thesis never held against the running system)
• 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:

• Complete AUDIT.md; the operator's acceptance in Step 8 is the attestation — the agent does not sign for them
• The ADR's lifecycle moves through the Step 8 receipt, never by hand-editing its status

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, fidelity gate 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 "g0" \
     --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.

Rules:

• Audit fails → no receipt. Only emit after all shortfalls are resolved.
• Attestor field is g0 — never the operator's real name and never their personal email (AGENTS.md § Execution Rules, Operator PII). 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).

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 gz test	L1
Docs build	uv run mkdocs build --strict	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	uv run gz covers <adr-id>	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 "g0" --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
• Fidelity gate passed — the ADR's assertions ran against the running system
• No unresolved ✗ failures
• Code matches documentation
• Examples are executable
• Validation receipt emitted to ledger
• Operator's audit acceptance relayed verbatim in the receipt
• Lifecycle verified — uv run gz adr report <adr-id> shows Validated

---

Failure Modes

• Mechanical-only audit — tests pass and coverage met but the ADR's thesis is never held against the running system. 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.