Menu
Gate-5 audit templates and procedure for ADR verification. GovZero v6 skill.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Validate and stage a candidate rendition from the corpus via gz content compose. Use when the agent has made compression decisions (drop/combine/rewrite of compressible corpus entries toward the declared setpoint) and wants the tool to validate invariant-floor compliance, compute byte evidence, write the candidate artifact, and emit a ledger event.
Enter and exit the MX Maintenance Hangar — operator's interface to gz mx. Use when entering the hangar to perform governance repair, checking hangar status mid-session, or cleanly exiting when repair is complete. Operator operates the skill; the skill invokes gz mx; nobody shells out.
Create and resume session handoff documents for agent context preservation across engineering sessions.
Create and resume session handoff documents for agent context preservation across engineering sessions.
Collaborative design dialogue that produces GovZero ADR artifacts. Use when exploring a new feature, capability, or architectural change before implementation — replaces superpowers brainstorming for this project. Triggers on "design X", "let's design", "brainstorm X", "I want to build X", "gz-design".
Cross the airlock membrane — the entry/exit gate every unit of work passes through (ADR-0.33.0). Use to inspect a target's seam-map before touching it (`gz airlock in`), account for what a transit disturbed (`gz airlock out`), or make a governed ad-hoc reconnaissance entry with light repair at most (`gz permitted-entry`). Diagnostic-only for now — a staged posture, not the declared end state; never writes L1 canon.
| 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 |
Execute reproducible ADR verification to move from COMPLETED → VALIDATED.
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.
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).
| 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. |
uv run gz adr report to confirm lifecycle changeTwo-phase workflow: See AGENTS.md § Two-Phase ADR Workflow
This is a Layer 2 tool — it consumes proof from the ledger rather than re-running verification commands.
Trust Chain:
gz-obpi-sync, gz adr audit-check) run tests, check coverage, validate evidencelogs/obpi-audit.jsonl with status entriesWhy trust the ledger?
When to force re-verification:
In these cases, run uv run gz audit <adr-id> first to regenerate ledger proof.
assets/AUDIT_PLAN.template.md — Plan scaffold (scope, checks, risk focus)assets/AUDIT.template.md — Annotation shell (✓/✗/⚠, summary, attestation)Prerequisite: ADR is COMPLETED (all briefs done, tests/coverage/docs pass).
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
audit/AUDIT_PLAN.md with checks for each claimuv run gz cli audit for governance issuesdocs/design/audit/** remains historical only; new audits live under the ADR folder.Before running any commands, check ledger proof:
uv run gz adr audit-check <adr-id>
If ledger is complete (all briefs PASS):
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:
.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..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.
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.
Populate audit/AUDIT.md with:
Review for:
For each shortfall:
Implement fixes, re-validate, update AUDIT.md.
When all shortfalls resolved:
AUDIT.md: agent signs (human already attested at OBPI completion)Status: ValidatedAfter 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:
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.
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.
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.
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.
Verify lifecycle. uv run gz adr report <adr-id> — confirm
the Lifecycle column shows Validated before declaring success.
Rules:
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.audit-begin with audit-end.
If the emit fails for any reason, still run audit-end so the
next ceremony starts clean.gz adr audit-begin CLI
verb — hand-fabricating the marker file bypasses the ceremony
entry-point.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.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 |
| 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:
gz closeout, gz attest, or gz audit/gz-adr-closeout-ceremony)COMPLETED (Phase 1):
VALIDATED (Phase 2):
uv run gz adr report <adr-id> shows Validatedgz-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.