Skip to content

gz closeout

Initiate closeout mode for an ADR and record closeout_initiated in the ledger.

Usage

Bash
gz closeout <ADR-ID> [--json] [--dry-run]
                     [--ceremony [--next | --ceremony-status | --attest TEXT | --pause | --restart]]

Runtime Behavior

gz closeout is fail-closed on linked OBPI runtime proof. Pool ADRs (ADR-pool.*) are blocked from closeout until promoted out of pool.

A feature/minor closeout is a release, so it is refused while an MX maintenance hangar is open (ADR-0.0.74): if .gzkit/mx.json is present, the executing path exits 3 with Closeout refused: an MX maintenance hangar is open; exit it (gz mx exit) before releasing. Exit the hangar first; --dry-run is unaffected.

The ADR's lifecycle transition starts from its actual state (the latest recorded lifecycle_transition, else its frontmatter status:) and goes through the lifecycle state machine, so an illegal pair is refused before anything is written (GHI #1014). An Accepted ADR ends Completed, or Deprecated when the attestation is Dropped. An ADR still Proposed whose OBPI work began before work start recorded Accepted first catches up Proposed -> Accepted, citing the child OBPI that shows the work; without that evidence, or from Draft, closeout exits 1 with Closeout refused: <ADR> is '<state>', which cannot reach its closeout state. The 62 Proposed -> Completed rows written before this fix remain in the ledger as dated records.

Output includes:

  • Gate 1 ADR path
  • OBPI completion summary
  • Product proof status table (per-OBPI documentation proof)
  • Closeout blockers when any linked OBPI is not closeout-ready
  • Generated ADR-CLOSEOUT-FORM.md path inside the ADR package
  • Linked OBPI evidence paths
  • Verification command set for the ADR lane
  • Canonical attestation choices
  • Heavy-lane Gate 4 command (always required for heavy lane)

If any linked OBPI still has missing proof, canonical drift, or missing required human-attestation evidence, gz closeout prints BLOCKERS: and exits 1 without writing closeout_initiated.

Version bump and in-flight release manifest

When the ADR's semver exceeds the declared project version, gz closeout bumps pyproject.toml, src/gzkit/__init__.py, and the README badge, and writes an in-flight release manifest at docs/releases/RELEASE-v{version}.md.

The manifest is not bookkeeping — it is the evidence audit_version_release accepts in place of a v{version} git tag. That audit runs inside gz test, and the ceremony's Step 10 runs gz git-sync --apply --lint --test before gh release create makes the tag, so without the manifest the bump would make the ceremony's own next mandated step unrunnable (GHI #739). gz patch release writes the equivalent PATCH-v{version}.md; both prefixes are accepted.

An existing manifest for the same version is never overwritten.

Product Proof Gate

After OBPI completion checks pass, gz closeout validates that each OBPI has at least one form of operator-facing documentation proof:

Proof Type Detection Method
runbook OBPI ID or slug keywords found in docs/user/runbook.md
command_doc Command doc file from OBPI allowed paths exists with >100 chars
docstring Public function/class in source files from allowed paths has docstring

At least one proof type must exist per OBPI. If any OBPI has MISSING proof, closeout exits 1 with a table showing which OBPIs lack proof.

Defense Brief

After product proof passes, gz closeout computes a Defense Brief section that is included in both the --dry-run preview and the final ADR-CLOSEOUT-FORM.md. The Defense Brief contains:

Section Content
Closing Arguments Per-OBPI closing argument text extracted from each brief
Product Proof Per-OBPI proof type and status table
Reviewer Assessment Per-OBPI reviewer verdict from REVIEW-*.md artifacts

The Defense Brief transforms the closeout form from a checklist into a defense presentation where the completing agent's evidence is laid out for human judgment.

When closeout succeeds without --dry-run, gz closeout creates or refreshes ADR-CLOSEOUT-FORM.md beside the ADR file with the current evidence inventory, Defense Brief, and Gate 5 attestation command.

--json adds:

  • allowed
  • blockers
  • obpi_summary
  • obpi_rows
  • next_steps

It still does not interpret the verification command outcomes themselves.

Canonical Attestation Choices

  • Completed
  • Completed — Partial: [reason]
  • Dropped — [reason]

Options

Option Description
--json Emit machine-readable closeout payload
--dry-run Show payload without writing ledger event
--ceremony Run the interactive closeout ceremony with deterministic step sequencing
--next Advance the ceremony to the next step (requires --ceremony)
--ceremony-status Show the current ceremony step (requires --ceremony)
--attest TEXT Record the operator's Gate-5 attestation at step 6 (e.g. --attest "Completed")
--pause Pause the ceremony to revise-and-resubmit (preserves state for later resumption)
--restart Restart the ceremony from step 1 as a fresh attempt (discards prior in-flight ceremony state)

Ceremony Sub-Flags

The --ceremony flag opens the interactive Gate-5 attestation ceremony. The companion sub-flags (--next, --ceremony-status, --attest, --pause, --restart) drive the ceremony state machine:

  • --ceremony --next advances one step.
  • --ceremony --ceremony-status reports the active step without mutating state.
  • --ceremony --attest "Completed" records the canonical attestation at step 6.
  • --ceremony --pause checkpoints the ceremony for revise-and-resubmit cycles.
  • --ceremony --restart discards in-flight ceremony state and starts over.

Example

Bash
uv run gz closeout ADR-0.10.0 --dry-run
Text Only
Dry run blocked: ADR-0.10.0-obpi-runtime-surface
  Gate 1 (ADR): docs/design/adr/pre-release/ADR-0.10.0-obpi-runtime-surface/ADR-0.10.0-obpi-runtime-surface.md
  OBPI Completion: 2/3 complete
BLOCKERS:
- OBPI-0.10.0-03-obpi-proof-and-lifecycle-integration: ledger proof of completion is missing
Next steps:
  - uv run gz adr status ADR-0.10.0-obpi-runtime-surface
  - uv run gz adr audit-check ADR-0.10.0-obpi-runtime-surface
  - uv run gz obpi sync OBPI-0.10.0-03-obpi-proof-and-lifecycle-integration