Gz Adr Audit

gz-adr-audit

Execute reproducible ADR verification to move from COMPLETED → 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-reconcile, 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

ADR_DIR=docs/design/adr/adr-x.y.x/ADR-x.y.z-slug
mkdir -p "${ADR_DIR}/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 (Demonstrate Value) — no re-verification needed
• Trust Layer 1 proof from obpi-audit
• Record "Ledger proof verified" in audit notes

If ledger is incomplete or missing:

• Run: uv run gz audit <adr-id>
• This will audit all briefs and write ledger entries
• Return to Step 2 after reconciliation

Force re-verification (optional):

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

uv run -m unittest -q > "${ADR_DIR}/audit/proofs/unittest.txt" 2>&1
uv run mkdocs build -q > "${ADR_DIR}/audit/proofs/mkdocs.txt" 2>&1
uv run gz gates --adr <adr-id> > "${ADR_DIR}/audit/proofs/gates.txt" 2>&1

Record ✓/✗/⚠ outcomes for each check.

3. Demonstrate Value (MANDATORY)

An audit that only verifies mechanical checks (tests pass, coverage met) without demonstrating what the ADR delivers is incomplete.

This step shows the ADR's achieved capabilities through live commands. It answers: "What can the operator do now that they couldn't before?"

Procedure:

1. Summarize the ADR's delivered capabilities — 3-5 bullet points of what the ADR enables
2. Run product surface commands that exercise each capability:
   • Use gz CLI commands, not ad-hoc scripts
   • Show actual output (not "tests pass" — show the feature working)
   • For foundation/0.0.x ADRs with no CLI surface: show the tool/library in action via its integration point
3. Include a "Feature Demonstration" section in audit/AUDIT.md with:
   • Each capability named
   • The command run and representative output
   • A value summary explaining why this matters

Examples of good demonstrations:

• Reconciliation ADR → run uv run gz adr status ADR-<x.y.z>, show the warnings panel
• Adapter ADR → run the ingest command, show data flowing through
• Schema ADR → show validation catching bad input

Examples of BAD audits (what this step prevents):

• "121 tests pass, coverage 47%, lint clean" — this is verification, not demonstration
• Alignment check saying "ALIGNED" without showing the feature running
• Audit that could apply to any ADR because it never mentions this ADR's specific capabilities

Relationship to closeout ceremony: If a full closeout ceremony (/gz-adr-closeout-ceremony) is being run, its Step 4 (Runbook Walkthrough) satisfies this requirement. If the audit is standalone (no ceremony), this step is mandatory and cannot be skipped.

4. Document

Populate audit/AUDIT.md with:

• Feature Demonstration section (from Step 3 — capabilities, commands, output, value)
• 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

After a successful audit, emit a validation receipt to the ADR ledger for temporal anchoring:

# Emit "validated" receipt (after Gate 5 attestation)
uv run gz adr emit-receipt <adr-id> --event validated \
  --attestor "agent:<model-id>" \
  --evidence '{"gate": 5, "tests_passed": true, "coverage_pct": 48.5}'

# Emit "completed" receipt (when marking ADR as Completed, pre-validation)
uv run gz adr emit-receipt <adr-id> --event completed \
  --attestor "human:<name>" \
  --evidence '{"briefs_completed": 6}'

Rules:

• Audit fails → no receipt. Only emit after all shortfalls are resolved.
• Idempotent: Running twice produces two ledger entries (audit trail preserved).
• Git unavailable: Command warns but returns exit code 0 (doesn't fail the audit).

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:

Validation Commands

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 (Demonstrate Value) and jumps straight to documentation

Relationship to Closeout Ceremony

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

If both are run: The closeout ceremony's Step 4 (Runbook Walkthrough) satisfies the audit's Step 3 (Demonstrate Value). No duplication needed.

If only audit is run: Step 3 is mandatory. The agent must demonstrate value, not just verify mechanics.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.