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:

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.

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:

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, review the ADR's open issues and close each one that the closeout resolves:

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):

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.

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