Gz Adr Closeout Ceremony

---
name: gz-adr-closeout-ceremony
persona: pipeline-orchestrator
description: Use to run an ADR's closeout ceremony through to the operator's attestation.
category: adr-audit
compatibility: GovZero v6 framework; provides runbook walkthrough for human ADR attestation
metadata:
  skill-version: "7.21.1"
  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-10-17
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`).

**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).

## 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` (state model in `src/gzkit/commands/ceremony_state.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:

```bash
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:

```bash
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:

```bash
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.

**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 unittest-parallel -t . -s tests --buffer`, `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, 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 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). 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:

```bash
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:

```bash
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:

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

### Step 7: GitHub Issues

When the CLI presents CLI Step 8, review the ADR's open issues and close each one that the closeout resolves:

```bash
gh issue list --search "ADR-X.Y.Z" --state open
```

**GHI closure discipline (cross-reference):** Close each issue through
`ghi-close`, one GHI, one disposition, one comment. Its dead-letter doctrine
binds here: 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.

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 two release steps, and both hand over

For non-Foundation releases the ceremony's release work ends at the version bump. The entry, the changelog and the publication belong to the `gz-patch-release` skill (operator ruling 2026-10-11; `.gzkit/rules/changelog-release-notes.md`, release-notes rule 3):

```text
Steps 9 and 10: run gz-patch-release from its "Hand-over from closeout" section. Write no entry here.
```

After each step, advance via `--next`.

**The sync-before-release order depends on the bump filing its own evidence (GHI #739).** `audit_version_release` runs inside the sync and fails a declared version with no matching `vX.Y.Z` tag, so `gz closeout` writes `docs/releases/RELEASE-v{version}.md` at bump time as accepted in-flight evidence. If that manifest is missing, the sync refuses on a `version_release` violation — write it rather than reordering the ceremony (a tag created before the bump commit points at a tree lacking the bump).

### 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.

```bash
uv run gz git-sync --apply   # Sync 1 — closeout artifacts
uv run gz git-sync --apply   # Sync 2 — residue check; commonly a no-op
```

**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; bare (non-ARB) commands do not satisfy this requirement. The canonical invocations are locked by `CANONICAL_STEP_COMMANDS` in `src/gzkit/canonical_steps.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 unittest-parallel -t . -s tests --buffer` | 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. The `CeremonyState` model in `src/gzkit/commands/ceremony_state.py` is the authority for its fields; read the current step with `--ceremony-status` rather than from the file.

**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.

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 — even in auto mode — and keep the evidence-gathering ARB checks out of the per-demo sequence (Step 4).
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, each through `ghi-close`.** 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.

---

## ADR Folder Structure (Canonical)

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

---

## References

- Ceremony code: `src/gzkit/commands/closeout_ceremony.py`
- Ceremony state model: `src/gzkit/commands/ceremony_state.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`