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 upgrade`	Surface-only refresh of `.gzkit/<surface>/` from the installed wheel
`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 knowledge`	Generate/refresh OKF knowledge bundle
`gz knowledge generate`	Emit the OKF knowledge bundle
`gz knowledge refresh`	Re-generate the bundle idempotently from current sources
`gz context`	Render focused-context Markdown payload (ADR + OBPIs + covering tests + governance) for one ADR
`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 demote`	Demote a feature/foundation ADR back to pool (inverse of promote)
`gz adr evaluate`	Evaluate ADR/OBPI quality (deterministic scoring with verdict)
`gz adr audit-check`	Verify OBPI completeness/evidence for one ADR
`gz adr fidelity`	Run ADR Fidelity Assertions against the running system
`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 acceptance`	Execute obligation proof and retain independent review closure
`gz obpi adversary-workspace`	Materialize the Step-4b adversary's disposable writable checkout
`gz obpi present-evidence`	Generate Step-4a proof input and report pending independent closure
`gz obpi pipeline`	Launch the OBPI pipeline runtime surface
`gz obpi dispatch`	Record a Stage-2 subagent dispatch, or declare a single-driver run
`gz obpi validate`	Validate OBPI brief(s) for authored, scaffold, and completion readiness
`gz obpi sync`	Fail-closed reconciliation for one OBPI (receipt + ADR table)
`gz obpi brief-drift`	Check an OBPI brief against project state across five drift dimensions
`gz obpi emit-receipt`	Emit completed/validated receipt for one OBPI
`gz obpi repudiate`	Repudiate a fraudulent or erroneous OBPI completion without retiring the OBPI
`gz obpi supersede`	Supersede one OBPI by another
`gz obpi block`	Record that an OBPI is waiting on an operator ruling
`gz obpi unblock`	Record the operator ruling that releases a blocked 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 ledger correct`	Append a corrective action against a prior ledger row
`gz ledger corrections`	List every ledger row currently under a correction
`gz ledger merge-driver`	Reconcile a conflicted append-only JSONL file (invoked by git)
`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 status`	Report every chore's staleness band without running it; announces, never gates
`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 mx enter`	Open the Maintenance Hangar (MX) mode
`gz mx exit`	Close the Maintenance Hangar — hard gate (re-run every guard at full strength)
`gz permitted-entry`	Airlock permitted-entry door — ad-hoc reconnaissance, light repair at most
`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 ontology sense`	Sweep the current structural shape and surface STRUCTURAL seams
`gz ontology trace`	Walk one node's vertical lineage + lateral proof with edge provenance
`gz ontology resense`	Diff the current shape versus the last sweep (the airlock re-sense gate)
`gz ontology seams`	Fast contacts-only STRUCTURAL seam check
`gz ontology reach`	Return one node's downstream blast-radius (transitive dependents)
`gz airlock in`	Run the airlock-IN preflight membrane for a target OBPI (diagnostic-only)
`gz airlock out`	Run the airlock-OUT exit drift-diff for a target OBPI (diagnostic-only)
`gz handoff list`	List session handoffs newest-first, optionally scoped by ADR
`gz handoff resume`	Report the newest handoff for an ADR, its staleness, and first next step
`gz handoff create`	Author a handoff, fail-closed through the validation gate
`gz handoff rulings`	Read the append-only settled-ruling corpus carried across sessions
`gz handoff decide`	Book the operator's transit decision on a resumed handoff (advisory record; it gates nothing)
`gz handoff authorize`	Deprecated alias for `gz handoff decide`
`gz handoff archive`	Move handoffs older than a threshold into `.gzkit/handoffs/archive/` (move-not-delete)
`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 task fanout`	Show TASK fan-out for a REQ-ID
`gz task envelope diagnose`	Show per-channel TASK declarations side-by-side for an OBPI
`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 smoke`	Run the smoke/BVT tier against its declared time budget
`gz test`	Run unit tests
`gz typecheck`	Run static type checks
`gz validate`	Validate governance artifacts
`gz governance render`	Render a governance surface (AGENTS.md) from the constitutional invariant registry
`gz complexity distill`	Run a complexity distillation pass and emit a distilled-characteristics document
`gz complexity advise`	Run the trigger-time complexity advisor against a file or directory and emit AdvisorDiagnosis output
`gz complexity guide`	Surface authoring-time complexity hints for functions approaching the warn threshold (advise-band only, never blocks)
`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 test-shape`	Advisory inventory of test-shape debt (tautological + output assertions)
`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 red`	Witness a test failing without the code it covers (by REQ or by commit)
`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
`gz arb archive`	Move aged, uncited receipts into `artifacts/receipts/archive/`

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 sync, 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
gz report publish — retain a big-picture assessment and ledger provenance.