Commands¶

All command surfaces use gz [subcommand] [*] [*].

Command reference pages are operator manpages and part of Gate 3 proof.

Governance¶

Command	Description
`gz init`	Initialize gzkit in a repository
`gz prd`	Create a Product Requirements Document
`gz constitute`	Create a constitution artifact
`gz specify`	Create an implementation brief (including OBPIs)
`gz plan create`	Create an ADR
`gz plan audit`	Structural prerequisite check for plan-OBPI alignment
`gz justify`	Produce a pre-execution reasoning scaffold (8 sections)
`gz implement`	Run Gate 2 and record results
`gz gates`	Run lane-required gates
`gz status`	Show multi-ADR OBPI progress and lifecycle status
`gz state`	Show artifact graph and readiness filters
`gz adr status`	Show focused OBPI progress for one ADR
`gz adr report`	Deterministic tabular report (summary or single ADR)
`gz adr promote`	Promote a pool ADR into canonical ADR package structure
`gz adr evaluate`	Evaluate ADR/OBPI quality (deterministic scoring with verdict)
`gz adr audit-check`	Verify OBPI completeness/evidence for one ADR
`gz adr covers-check`	Verify ADR/OBPI @covers traceability in tests
`gz flags`	Display all registered feature flags with current values
`gz flag explain`	Inspect one flag: metadata, resolved value, staleness, linked ADR
`gz closeout`	Present closeout paths/commands and record closeout initiation
`gz patch release`	Run the GHI-driven patch release ceremony
`gz attest`	Record human attestation with prerequisite enforcement
`gz audit`	Run strict post-attestation audit reconciliation
`gz adr emit-receipt`	Emit completed/validated receipt with optional evidence scope
`gz obpi status`	Show focused runtime status for one OBPI
`gz obpi pipeline`	Launch the OBPI pipeline runtime surface
`gz obpi validate`	Validate OBPI brief(s) for authored, scaffold, and completion readiness
`gz obpi reconcile`	Fail-closed reconciliation for one OBPI
`gz obpi emit-receipt`	Emit completed/validated receipt for one OBPI
`gz obpi withdraw`	Record an OBPI withdrawal event
`gz obpi lock claim`	Claim an OBPI work lock
`gz obpi lock release`	Release an OBPI work lock
`gz obpi lock check`	Check if an OBPI is locked
`gz obpi lock list`	List active OBPI work locks
`gz obpi audit`	Gather evidence for OBPI brief and record in audit ledger
`gz obpi complete`	Atomically complete an OBPI (validate, write evidence, emit receipt)
`gz git-sync`	Run guarded sync ritual
`gz chores list`	List declared chores from the config registry
`gz chores plan`	Show deterministic plan details for one chore
`gz chores run`	Execute one chore and append a dated log
`gz chores audit`	Audit chore log presence for one/all chores
`gz chores doctor`	Re-scaffold missing or damaged canonical chores; preserve `proofs/`
`gz chores propose-ghi`	File GitHub issues for unfiled cluster proposal records in a chore's `proofs/`
`gz migrate-semver`	Record SemVer ID rename events
`gz register-adrs`	Register existing ADR packages and linked OBPIs into ledger
`gz personas drift`	Report persona trait adherence from behavioral proxies
`gz personas list`	Enumerate persona files from `.gzkit/personas/`
`gz roles`	List pipeline agent roles and handoff contracts
`gz task list`	List tasks for an OBPI with status
`gz task start`	Start or resume a task
`gz task complete`	Complete a task
`gz task block`	Block a task with reason
`gz task escalate`	Escalate a task with reason
`gz issue file`	Cross-repo defect/enhancement filing wrapper (provenance auto-stamp; routes to `tvproductions/gzkit`)

Validation And Maintenance¶

Command	Description
`gz check`	Run full quality checks (lint, typecheck, test) in one pass
`gz drift`	Detect spec-test-code governance drift
`gz lint`	Run code linting checks
`gz format`	Auto-format code
`gz test`	Run unit tests
`gz typecheck`	Run static type checks
`gz validate`	Validate governance artifacts
`gz skill audit`	Audit skill lifecycle metadata and mirror parity
`gz skill list`	List all discovered skills and their metadata
`gz skill new`	Create a new skill scaffold
`gz parity check`	Run deterministic parity regression checks
`gz readiness audit`	Audit agent-readiness maturity across core disciplines
`gz readiness evaluate`	Run instruction architecture eval suite with positive/negative controls
`gz check-config-paths`	Validate configured + manifest path coherence
`gz cli audit`	Validate CLI docs/manpage coverage
`gz agent sync control-surfaces`	Regenerate control surfaces
`gz covers`	Report requirement coverage from @covers annotations
`gz preflight`	Detect and clean stale markers, orphan receipts, expired locks
`gz tidy`	Run maintenance checks and cleanup
`gz interview`	Run interactive governance interviews
`gz chores advise`	Dry-run acceptance criteria for one chore
`gz chores show`	Display CHORE.md content for one chore
`gz frontmatter reconcile`	Rewrite drifted ADR/OBPI frontmatter to match ledger (ledger-wins)

ARB (Agent Self-Reporting)¶

Command	Description
`gz arb ruff`	Run ruff via ARB and emit a lint receipt
`gz arb step`	Wrap an arbitrary command and emit a step receipt
`gz arb ty`	Run `uvx ty` via ARB step wrapper
`gz arb typecheck`	Canonical Heavy-lane type-check receipt — wraps `gz typecheck` scope
`gz arb coverage`	Run `coverage` via ARB step wrapper
`gz arb validate`	Validate recent receipts against JSON schemas
`gz arb advise`	Summarize recent receipts into recommendations
`gz arb patterns`	Extract recurring anti-patterns from receipts

Operator Sequences¶

Primary daily loop (OBPI-first, pipeline-governed):

Orientation and ADR/OBPI context (gz status, gz adr status, gz obpi status)
Plan the OBPI, then execute it through uv run gz obpi pipeline (wrapper skill /gz-obpi-pipeline remains available and defers to the same shared runtime)
Present the Heavy-lane acceptance ceremony when required
Run guarded sync (gz git-sync --apply --lint --test)
Emit final OBPI completion accounting from the synced state (gz obpi emit-receipt)
Reconcile/update brief and ADR state (gz obpi reconcile, gz adr status)

ADR closeout loop (after OBPI batch completion):

ADR/OBPI reconciliation (gz adr audit-check)
Spec-test traceability reconciliation (gz adr covers-check)
Closeout presentation (gz closeout)
Human attestation (gz attest)
Post-attestation audit (gz audit)
ADR-level receipt/accounting (gz adr emit-receipt)

Global Options¶

All commands support:

--help
--version