gz state

Overview

Read the artifact graph the ledger derives: every PRD, ADR and OBPI with its type, parent and attestation. gz state is a Layer 3 view of the ledger, so cite it for an artifact's relationships, and read completion from the ledger through gz obpi status or gz adr status.

• With no flag it prints the Artifact State table (ID, Type, Parent, Attested). --full folds long IDs instead of truncating them.
• --json prints the whole graph, including ADR lifecycle fields (lifecycle_status, closeout_phase, attestation_term) and, for an OBPI with TASKs, a task_summary with counts by status.
• --blocked keeps only unattested artifacts. That is every pool ADR and pending OBPI, not only work that is blocked.
• --ready keeps only unattested ADRs whose lane-required gates are satisfied, that is, ADRs ready for attestation.
• Withdrawn OBPIs are hidden, and removed from their parent's children; --include-withdrawn shows them.

--repair is the one mode that writes. It ignores the query flags, has no dry run, and makes two repairs from the ledger:

• It sets each OBPI brief's frontmatter status: Completed when the ledger records completion, Abandoned when it records withdrawal, unchanged otherwise. A terminal brief is never overwritten.
• It repairs the pipeline marker files of the run in flight that was launched last, and is the only command that does. With one of the run's two files on disk it restores the missing one as a copy; with neither it rebuilds both from the run's pipeline_launched and pipeline_stage_transition events. It overwrites no marker file. With neither file on disk it declines a run whose last recorded boundary is past the stale bound; with one file on disk the stale bound does not apply and the copy is restored. It declines an older run while a later one is in flight. The manpage docs/user/manpages/state.md states the whole contract.

Workflow

1. Query: uv run gz state, or --json, --blocked, --ready, --include-withdrawn as the question needs. Add --full when IDs are quoted as evidence.
2. Before --repair, tell the operator that it edits brief files and may write pipeline marker files under .claude/plans/. Run it, then report its State Repair Results table, or All frontmatter is aligned with ledger state. No changes., and each Restored pipeline marker file, Rebuilt pipeline marker and Pipeline marker not rebuilt line it prints, the last with its reason. With --json these are the markers object: rebuilt, restored and declined. Include the changed brief files in the commit.

Example

uv run gz state --ready
uv run gz state --json
uv run gz state --repair