gz-adr-closeout-ceremony

name	gz-adr-closeout-ceremony
persona	pipeline-orchestrator
description	Execute the ADR closeout ceremony protocol for human attestation. GovZero v6 skill.
category	adr-audit
compatibility	GovZero v6 framework; provides runbook walkthrough for human ADR attestation
metadata	{"skill-version":"7.16.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"}
lifecycle_state	active
owner	gzkit-governance
last_reviewed	"2026-07-26T00:00:00.000Z"
model	opus

gz-adr-closeout-ceremony

Execute the ADR closeout ceremony by driving the CLI state machine.

Authority: docs/governance/GovZero/audit-protocol.md

---

The Ceremony Contract

THE CEREMONY IS NOT COMPLETE UNTIL THE HUMAN ATTESTS AND THE REPO IS SYNCED.

Running walkthrough commands is not completion. Passing quality checks is not completion. Printing a summary is not completion. The ceremony exists to produce a human attestation decision backed by structured evidence, then persist that decision to the ledger and sync it.

Violating the spirit of this contract is violating it.

Rationalization Prevention

These thoughts mean STOP — you are about to break the ceremony:

Thought	Reality
"All checks passed, the ADR is done"	Checks passing is evidence. The human decides. You do not.
"Let me summarize the walkthrough results"	Present them in the evidence template. Do not interpret them.
"The human acknowledged each step, so they've attested"	Acknowledgment is not attestation. Wait for the explicit --attest decision.
"I'll skip the walkthrough since OBPIs already passed"	The walkthrough is the human's verification surface. You do not skip it for them.
"The CLI errored, I'll work around it"	CLI errors are signals. Diagnose the cause. Do not reimplement step logic.
"I can close the issues and sync later"	Later means never. The ceremony runs to completion NOW.
"The human said 'looks good'"	"Looks good" is not an attestation value. Ask for Completed, Completed-Partial, or Dropped.

---

Persona

Active driver: pipeline-orchestrator — read .gzkit/personas/pipeline-orchestrator.md and adopt its behavioral identity before executing this skill. Closeout is a sequenced ceremony (read evidence → present → attest → persist); the ceremony-as-checkbox anti-trait — "treating the attestation ceremony as a formality to rush through rather than a genuine decision point" — is literally what this skill exists to prevent. Present evidence; do not interpret it. The human decides. You do not.

Persona Dispatch

Closeout is read-only ceremony work — the driver synthesizes attestation evidence from three independent subagent reads. Dispatch each as a fresh-context subagent so the driver isn't scoring its own scoring (the optimistic-bias failure mode spec-reviewer's anti-traits name):

Persona	Function in this ceremony	Invoked at
spec-reviewer	Independent re-verification of each OBPI's claimed REQ coverage against brief and tests, against ledger proof	Before assembling the evidence packet (after CLI walkthrough, before human attestation step)
quality-reviewer	Independent assessment of the ADR-package structural coherence: do the closed OBPIs form a coherent capability, or is there integration drift?	Before assembling the evidence packet
narrator	Composes the evidence packet in operator-value framing — what the operator gains, not what the agent did; what decision the human is being asked to make, with precise citations	When rendering the attestation surface to the human

Personas not dispatched: implementer (no code written — closeout reads completed work; if it surfaces a defect, file a GHI via /ghi-author).

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.

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

Trust Model

Layer 2 — Ledger Consumption: This skill orchestrates human attestation using ledger proof.

• Reads: Ledger entries, audit reports, ADR/OBPI files
• Writes: Attestation records, status updates via CLI commands
• Does NOT re-execute (CLI layer): The ledger-consumption layer trusts Layer-1 proof and never re-runs receipts. Independent re-verification is performed by the spec-reviewer persona-dispatch step (§ Persona Dispatch above), not by the CLI.
• Requires: Human attestation before finalizing

---

When to Use

• Human invokes "ADR closeout ceremony" (or equivalent: "begin closeout", "closeout ADR-X.Y.Z")
• Human is ready to witness and attest to ADR completion
• All OBPIs are believed to be complete

When NOT to Use

• For individual OBPI completion — use gz-obpi-pipeline instead
• When OBPIs are still in progress — complete them first
• For audit-only checks without ceremony — use gz adr audit-check

---

Architecture

The ceremony is driven by src/gzkit/commands/closeout_ceremony.py, which provides:

• Step sequencing — deterministic step ordering via CeremonyStep enum
• Foundation skip — FOUNDATION_SKIP_STEPS automatically skips RELEASE_NOTES and RELEASE steps for 0.0.x ADRs
• State persistence — ceremony state saved in .gzkit/ceremonies/<ADR-ID>.json
• Walkthrough discovery — commands extracted from OBPI briefs and command docs
• Turn locks — prevents step skipping

The agent MUST drive the ceremony through CLI commands, not by reimplementing step logic in prose. The CLI handles all conditional logic (Foundation skips, lane-specific steps, step ordering). The agent's role is to:

1. Run the CLI command for each step
2. Present the output using the evidence template
3. Wait for human acknowledgment
4. Advance via CLI

---

Procedure

Step 1: Initialize

When the human says "ADR closeout ceremony" (or equivalent), start the ceremony:

uv run gz closeout ADR-X.Y.Z --ceremony

This initializes the ceremony state machine and outputs the Step 2 summary. Present the output to the human. Do not interpret or claim outcomes.

If resuming an interrupted ceremony: The same command resumes from the last completed step. Check the current state first:

uv run gz closeout ADR-X.Y.Z --ceremony --ceremony-status

Abort if: ADR not found, no OBPIs exist, or ceremony state is corrupt (see Error Recovery).

Step 2: Advance Through Steps

After the human acknowledges each step, advance:

uv run gz closeout ADR-X.Y.Z --ceremony --next

The CLI outputs the content for the next step. Present it and wait for acknowledgment.

Repeat this cycle for each step. The CLI handles:

• Which step comes next
• Skipping Foundation-excluded steps (RELEASE_NOTES, RELEASE for 0.0.x)
• What content to present at each step

Step 3: Docs Alignment Check

When the CLI presents the docs alignment checklist (CLI Step 3), the human confirms documentation parity. Advance via --next after acknowledgment.

If the human identifies doc gaps: Do not advance. Fix the documentation, run uv run mkdocs build --strict to verify, then re-present the checklist. Only advance after the human confirms parity.

Step 4: Walkthrough Execution

When the CLI presents walkthrough commands (CLI Steps 4-5), run them one at a time. The CLI enforces this cadence at Step 5 EXECUTE: each --next advances walkthrough_index by one and the renderer presents exactly one demo command per turn (GHI #260).

• Run ONE command, show output, STOP and WAIT for acknowledgment
• Advance with --next after the human acknowledges — the CLI then presents the next demo
• The ceremony only moves to Step 6 ATTESTATION after the final demo has been presented and acknowledged

Auto-mode override. Auto mode's "prefer action over planning, minimize interruptions" framing does NOT apply inside the walkthrough. Step 5 is an operator-paced observation surface — do not batch demo commands into parallel tool calls to save turns. Rule #5 in § Ceremony Rules below overrides the auto-mode batching default.

Evidence-gathering ARB checks are separate from the demos. The Evidence Summary Template (§ below) lists the canonical ARB-wrapped invocations (uv run gz arb ruff, uv run gz arb step --name unittest -- uv run -m unittest -q, uv run gz arb typecheck, uv run gz arb step --name mkdocs -- uv run mkdocs build --strict) as evidence-template population — these are not discovered demo commands and must NOT be interleaved with the per-demo --next loop. Run them when gathering evidence for the Step 6 attestation prompt (either right before the prompt or during pre-ceremony preparation), never mixed into the Step 5 one-at-a-time sequence. Heavy-lane ceremony fail-closes on missing receipt IDs per AGENTS.md § Attestation § Lane behavior, so bare (non-ARB) invocations do not satisfy the evidence requirement.

Bound fidelity gate at the EXECUTE→ATTESTATION edge (ADR-0.0.73, OBPI-0.0.73-04). When the final demo is acknowledged and --next advances from Step 5 EXECUTE to Step 6 ATTESTATION, the CLI automatically runs the bound fidelity gate — the SAME standalone gate the audit ceremony invokes (one gate, two consumers — assert_fidelity_for_ceremony). It parses the ADR Decision's ## Fidelity Assertions block and RUNS each assertion against the running system. This is the bound replacement for the old prose 'Demonstrate Value' step — you do not narrate value; the gate exercises the ADR's thesis. A failed assertion blocks the transition (PolicyBreachError). An ADR with no ## Fidelity Assertions block is flagged with a warning but does not hard-block in-flight (graceful migration, OBPI-0.0.73-04); author a block before closeout, since presence is enforced at ADR closeout per ADR-0.0.73 Boundary Invariant #4.

If a walkthrough command fails: See Error Recovery. Do not skip it. Do not advance past it. Fix it or escalate.

Step 5: Attestation

When the CLI presents the attestation prompt (CLI Step 6), present the Evidence Summary (see template below), then wait for the human's decision:

uv run gz closeout ADR-X.Y.Z --ceremony --attest "Completed"

Valid attestations:

• "Completed" — ADR work is finished; all claims verified
• "Completed - Partial: [reason]" — Subset accepted, remainder deferred
• "Dropped - [reason]" — ADR rejected; does not advance

Human requests corrections: This is a rejection. Record the feedback, identify which ceremony steps need re-execution, and return to the appropriate step. Do NOT record a partial attestation when the human wants fixes. See Rejection Loop-Back below.

Step 6: Closeout Pipeline

When the CLI presents CLI Step 7, run the closeout pipeline:

uv run gz closeout ADR-X.Y.Z

This handles quality gates, attestation recording, version bump, and closeout form. After it completes, advance the ceremony:

uv run gz closeout ADR-X.Y.Z --ceremony --next

Step 7: GitHub Issues

When the CLI presents CLI Step 8, close related issues:

gh issue list --search "ADR-X.Y.Z" --state open
gh issue close <number> --comment "Resolved by ADR-X.Y.Z closeout."

Then advance via --next.

Step 8: Release Steps (CLI-Driven)

The CLI automatically handles Foundation vs non-Foundation:

• Foundation (0.0.x): Steps 9-10 are skipped automatically by FOUNDATION_SKIP_STEPS
• Non-Foundation: The CLI presents RELEASE_NOTES and GitHub Release steps

For non-Foundation releases:

# Step 9: Update RELEASE_NOTES.md (agent edits the file)
# Step 10: Sync and create GitHub release
uv run gz git-sync --apply
gh release create vX.Y.Z --title "vX.Y.Z" --notes-file RELEASE_NOTES.md

After each step, advance via --next.

Step 9: Completion (Two-Sync Pattern)

When the CLI outputs the ceremony completion summary (CLI Step 11), present it to the human, then run the two-sync pattern to commit the closeout cleanly. This mirrors gz-obpi-pipeline's Stage 5 — every governance artifact must land in two reviewable commits.

# Sync 1 — closeout artifacts: ceremony state, attestation receipt, ADR audit
# updates, GHI close comments, release notes (if applicable).
uv run gz git-sync --apply

# Sync 2 — capture any residual artifacts from post-closeout hooks or
# per-OBPI reconciliation sweeps. The closeout pipeline emits derived-state
# reconciliation atomically with the attestation ledger event, so sync 2 is
# commonly a no-op. Run it anyway — it is the mechanical check that the
# working tree is truly clean after closeout.
uv run gz git-sync --apply

GHI closure discipline (cross-reference): When GHI close comments are committed as part of closeout (sync 1 above), apply ghi-close v2.4.0's dead-letter doctrine: every GHI close MUST cite a real, registered destination (commit SHA, ADR ID in gz adr report, OBPI brief ID, or higher-numbered open GHI). A close comment pointing to an unregistered ADR draft or a vague "route to the team" is a dead-letter and is forbidden. If no destination exists at closeout time, leave the GHI open with a blocker comment and note it in the closeout summary. See .gzkit/skills/ghi-close/SKILL.md § Doctrine — NEVER, EVER, EVER dead-letter a GHI for the binding rule.

Why two syncs:

1. The first sync makes the human attestation, receipt, and walkthrough evidence durable before any derived state is rebuilt.
2. The second sync is the mechanical check that no post-closeout hook, per-OBPI gz obpi sync sweep, or derived-state refresh left uncommitted artifacts. In the common case sync 2 is a no-op because the closeout pipeline emits derived-state reconciliation atomically with the attestation event; sync 2 exists to catch the exceptional case where it did not.

If sync 1 fails, the ceremony is paused — fix the failing gate, re-run sync 1. Never skip sync 2: skipping it risks leaving a derived-view artifact uncommitted, which is the same failure family as #129 (canon green, derived view stale).

The ceremony is done.

Fallback / Degraded Mode

If gz git-sync is unavailable (network failure, gh outage, dirty submodule):

1. Stop the ceremony at the failed sync. Do not advance.
2. Capture the exact error output and the ceremony state file path (.gzkit/ceremonies/<ADR-ID>.json).
3. Hand off to the human with a one-line summary plus the resume command: uv run gz closeout ADR-X.Y.Z --ceremony (re-attaches to the persisted state).
4. Do not manually commit closeout artifacts or hand-edit the ledger as a workaround. The ceremony resumes cleanly once sync is restored.

---

Evidence Summary Template

Present this template at Step 5, before requesting attestation. Every field is mandatory. The human cannot make an informed attestation decision without structured evidence.

## ADR Closeout Evidence: ADR-X.Y.Z

**1. ADR Intent**

<What was this ADR's purpose? 1-2 sentences from the ADR document.>

**2. OBPI Completion Status**

| OBPI | Status | Attestor | Date |
|------|--------|----------|------|
| OBPI-X.Y.Z-01 | Completed | <name> | <date> |
| OBPI-X.Y.Z-02 | Completed | <name> | <date> |

**3a. Product Demos — the yielded product**

The ADR's outcome, demonstrated. Every row is a concrete invocation that exercises the capability the ADR delivered — actual diagnosis runs against real files, the `--json` form, auto-chain trigger output, intrinsic-attestation paths, etc. `--help` is the weakest possible product demonstration; reach for it only when no richer demo exists. Brief-side `## Demo` / `## Examples` sections feed this table directly through the walkthrough discovery (GHI #427).

| Demo Command | Result | Notes |
|--------------|--------|-------|
| `uv run gz <verb> <real-args>` | <observed outcome> | <one-line operator-value framing> |
| `uv run gz <verb> <real-args> --json` | <observed outcome> | <one-line operator-value framing> |
| <brief-specific demo> | <observed outcome> | <one-line operator-value framing> |

**3b. Quality Evidence — construction housekeeping**

Cite canonical ARB-wrapped invocations with receipt IDs. These prove the codebase is healthy; they are not the ADR's product. Heavy-lane attestation fail-closes on missing receipt IDs per `AGENTS.md` § Attestation § Lane behavior; bare (non-ARB) commands do not satisfy this requirement. The canonical invocations are locked by `CANONICAL_STEP_COMMANDS` in `src/gzkit/arb/validator.py`.

| Command | Result | Receipt ID | REQ Bindings | Notes |
|---------|--------|------------|--------------|-------|
| `uv run gz arb ruff` | Pass | `arb-ruff-...` | REQ-X.Y.Z-NN-MM | <summary> |
| `uv run gz arb step --name unittest -- uv run -m unittest -q` | Pass | `arb-step-unittest-...` | REQ-X.Y.Z-NN-MM | <N> unit tests |
| `uv run behave features` | Pass | n/a (no canonical ARB wrapper) | n/a | <M> behave scenarios (closeout = full suite) |
| `uv run gz arb typecheck` | Pass | `arb-step-typecheck-...` | REQ-X.Y.Z-NN-MM | <summary> |
| `uv run gz validate --documents` | Pass | n/a | n/a | <summary> |
| `uv run gz arb step --name mkdocs -- uv run mkdocs build --strict` | Pass | `arb-step-mkdocs-...` | REQ-X.Y.Z-NN-MM | <summary> |

**4. Documentation Alignment**

- [ ] Runbook updated
- [ ] Command docs current
- [ ] ADR document reflects final state

**5. Open Issues**

| Issue | Status | Disposition |
|-------|--------|-------------|
| #<N> | Open/Closed | Resolved by closeout / Deferred to ADR-X.Y.Z |

**6. Awaiting attestation.** Provide: "Completed", "Completed - Partial: [reason]", or "Dropped - [reason]".

---

Error Recovery

Failure Point	Action	Retry Limit
--ceremony init fails (ADR not found)	Verify ADR path exists, check gz adr status, report to human	0 — fix config
--next fails (step logic error)	Check --ceremony-status for current step. Report CLI error to human. Do not reimplement step logic.	1 — retry after status check
Walkthrough command fails (non-zero exit)	Show the error output to the human. Diagnose: is it a code bug, config issue, or environment problem? Fix if possible, re-run the command.	2 — fix and retry, then escalate to human
Walkthrough command produces unexpected output	Present output as-is to the human. Do not interpret. Let the human decide if it's acceptable.	0 — human decides
gz closeout ADR-X.Y.Z pipeline fails	Show error. Check if quality gates failed (gz lint, gz test). Fix failing gates, re-run.	2 — fix gates, then escalate
gh issue close fails	Verify issue exists and is open (gh issue view <N>). Retry with correct number.	1
gz git-sync fails	Do not proceed past the sync step. Diagnose: lint failures, test failures, merge conflicts. Fix and re-sync.	2 — fix and retry, then escalate
Ceremony state corrupt	--ceremony-status shows inconsistent state. Re-initialize: gz closeout ADR-X.Y.Z --ceremony (resumes from last completed step).	1 — re-init
Human is unresponsive at attestation	Do nothing. Wait. Do not infer attestation from silence.	0 — wait indefinitely

On any unrecoverable failure: Report the failure clearly to the human with the exact error output. Do not attempt to work around the CLI. The ceremony is paused — state is persisted in .gzkit/ceremonies/ and can be resumed in a new session.

---

Rejection Loop-Back

When the human requests corrections instead of attesting:

1. Record the feedback — note exactly what the human wants fixed
2. Identify the scope — is it a code fix (return to OBPI pipeline), a doc fix (fixable in ceremony), or an evidence gap (re-run walkthrough)?
3. Execute the fix:
   • Code fix needed: The ceremony cannot fix code. Advise the human to re-open the relevant OBPI via gz-obpi-pipeline --from=verify. Pause the ceremony.
   • Doc fix needed: Fix the documentation, run uv run mkdocs build --strict, re-present the docs alignment step.
   • Evidence gap: Re-run the relevant walkthrough commands, update the evidence template, re-present to the human.
4. Re-present attestation — after fixes, present the updated Evidence Summary Template and wait for the human's decision again.
5. Bound the loop — if the human rejects a third time, escalate: "Three correction cycles completed. Should we continue fixing, defer this ADR, or drop it?"

---

Ceremony State

State is persisted at .gzkit/ceremonies/<ADR-ID>.json by the CLI. Structure:

Field	Purpose
adr_id	ADR being closed out
current_step	CeremonyStep enum value
completed_steps	List of steps already finished
started_at	Ceremony initialization timestamp
updated_at	Last step advancement timestamp
attestation	Human's attestation text (null until Step 5)
walkthrough_results	Command → exit code + output summary

Resumption: gz closeout ADR-X.Y.Z --ceremony checks for existing state and resumes from the last completed step. The agent does not need to re-run completed steps.

Concurrent ceremonies: Each ADR has its own state file. Multiple ADR ceremonies can run in separate sessions without interference.

---

CLI Reference

See references/cli-reference.md for the full command table.

---

Ceremony Rules

One-sided directives. Each row states the required behavior and names the failure shape it prevents (GHI #227: halved from 20 mirror-pair rows).

1. Drive the ceremony through CLI commands (--ceremony, --next, --attest). The CLI state machine is authoritative — never reimplement step logic in prose, ad-hoc Python, raw SQL, or heredoc code, and never manually skip or add steps (the CLI handles Foundation skips and ordering).
2. Present CLI output without interpreting or concluding. Evidence is presented; outcomes are not claimed. Passing checks are evidence, not a verdict.
3. Use the Evidence Summary Template before requesting attestation. Every field populated; no freeform substitution.
4. Use only runbook/manpage-documented gzkit commands for the walkthrough — no undocumented flags, no improvised invocations.
5. Run walkthrough commands one at a time and wait for acknowledgment between each. The CLI enforces this at Step 5 EXECUTE by rendering exactly one demo per --next via walkthrough_index (GHI #260) — do not batch demos into parallel tool calls even in auto mode, and do not interleave the evidence-gathering ARB checks (lint/typecheck/tests/mkdocs) with the per-demo sequence; those belong to the Step 6 Evidence Summary and must be run separately from the demos.
6. Wait for explicit human attestation. Silence, "ok", or "looks good" is not attestation; ask "Completed, Completed-Partial, or Dropped?" and never auto-close based on passing checks.
7. Record attestation only through uv run gz closeout ADR-X.Y.Z. Never hand-edit the ledger, never substitute "Completed - Partial" for what the human intended as a rejection (follow the Rejection Loop-Back procedure).
8. Stop on any failed walkthrough command. Fix the root cause or escalate; do not advance, and do not work around CLI errors by reimplementing the step in prose.
9. Review and close related GitHub Issues after attestation. Unlinked closure leaves evidence orphaned.
10. Run uv run gz git-sync --apply before gh release create (non-Foundation) and after ceremony completion. An unsynced attestation is a dangling ceremony.

---

Anti-Patterns

The Premature Close

The agent runs walkthrough commands, they all pass, and the agent says "ADR-X.Y.Z is complete." No — the agent does not decide completion. The human attests. Passing checks are evidence, not a verdict.

The Silent Attestation

The human says "ok" or "looks good" after reviewing walkthrough output. The agent records --attest "Completed". No — vague acknowledgment is not attestation. Ask explicitly: "What attestation would you like to record? Completed, Completed-Partial, or Dropped?"

The Skipped Walkthrough

OBPIs all passed their pipelines, so the agent skips the walkthrough to "save time." No — the walkthrough is the human's ADR-level verification surface. Individual OBPI attestations do not substitute for ADR-level review.

The Workaround

A CLI command errors and the agent reimplements the step in prose or with ad-hoc code. No — CLI errors are diagnostic signals. Fix the root cause or escalate. The ceremony state is persisted and can resume after fixes.

The Dangling Ceremony

The agent completes attestation but does not sync the repo. The attestation exists in local state but is not committed. This is the closeout equivalent of the pipeline's "Premature Summary" — the governance action happened but was never persisted.

---

ADR Folder Structure (Canonical)

See references/folder-structure.md for the expected directory layout.

---

References

• Ceremony code: src/gzkit/commands/closeout_ceremony.py
• Step renderers: src/gzkit/commands/ceremony_steps.py
• Audit protocol: docs/governance/GovZero/audit-protocol.md
• Gate definitions: docs/governance/GovZero/charter.md
• Release tag rule: docs/governance/GovZero/adr-lifecycle.md
• Runbook: docs/user/operator_runbook.md
• Pipeline skill (behavioral reference): .gzkit/skills/gz-obpi-pipeline/SKILL.md