gz-state
Use to report artifact lineage, relationships or readiness.
SKILL.md.claude/skills/gz-state/SKILL.md
GitHubgz 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 Statetable (ID, Type, Parent, Attested).--fullfolds long IDs instead of truncating them. --jsonprints the whole graph, including ADR lifecycle fields (lifecycle_status,closeout_phase,attestation_term) and, for an OBPI with TASKs, atask_summarywith counts by status.--blockedkeeps only unattested artifacts. That is every pool ADR and pending OBPI, not only work that is blocked.--readykeeps 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-withdrawnshows 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:Completedwhen the ledger records completion,Abandonedwhen 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_launchedandpipeline_stage_transitionevents. 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 manpagedocs/user/manpages/state.mdstates the whole contract.
Workflow
- Query:
uv run gz state, or--json,--blocked,--ready,--include-withdrawnas the question needs. Add--fullwhen IDs are quoted as evidence. - Before
--repair, tell the operator that it edits brief files and may write pipeline marker files under.claude/plans/. Run it, then report itsState Repair Resultstable, orAll frontmatter is aligned with ledger state. No changes., and eachRestored pipeline marker file,Rebuilt pipeline markerandPipeline marker not rebuiltline it prints, the last with its reason. With--jsonthese are themarkersobject:rebuilt,restoredanddeclined. Include the changed brief files in the commit.
Example
uv run gz state --ready
uv run gz state --json
uv run gz state --repair