gz chores¶
Discover, plan, execute, and audit repository chores using the two-surface chores layout introduced by ADR-0.0.21.
Synopsis¶
Description¶
gz chores is the operator surface for gzkit's chore system. Chores are
declarative maintenance, refactoring, or quality work items packaged as
self-contained directories. Each chore ships a CHORE.md (procedure),
acceptance.json (machine-readable criteria), and README.md (human summary).
Two-surface resolution. Chores resolve project-first → package-fallback:
<project_root>/.gzkit/chores/<slug>/ is consulted before the canonical package
resource at importlib.resources.files("gzkit.chores"). The same order applies
to the registry.json file. Use gz chores list --explain to see which
surface answers each slug. proofs/ directories are project-local only;
canonical templates do not ship execution evidence.
Subcommands¶
list¶
Enumerate declared chores from the registry.
--explain prints one row per chore with its resolution source: project,
package, or missing.
show¶
Display the CHORE.md for one chore.
plan¶
Show plan details for one chore.
advise¶
Dry-run criteria and report status without mutating disk.
run¶
Execute one chore by slug. Validates acceptance criteria and writes a dated
log to .gzkit/chores/<slug>/proofs/CHORE-LOG.md.
status¶
Report every registered chore's staleness band — overdue, due,
unmeasured, paused or current — from its class declaration and its
passing run blocks (or its declared scan record), without running any chore. Staleness announces and never
gates: every band exits 0. See gz chores status.
audit¶
Audit log presence across all chores.
doctor¶
Repair canonical chore slugs inside .gzkit/chores/<slug>/ from the package
copy. A slug whose directory is absent is re-scaffolded; a slug missing a
definition file (CHORE.md, acceptance.json, README.md) or carrying an
unparseable acceptance.json has every definition file that differs from the
package rewritten, surviving edits included; a complete slug is left alone even
when it differs. Never modifies
proofs/ content (REQ-0.0.21-09-05). Never modifies project-local-only slugs
that are absent from canonical (REQ-0.0.21-09-06).
--dry-run produces the full summary without modifying any file.
--json emits one record per slug to stdout with slug, before_status,
and after_status fields.
propose-ghi¶
File GitHub issues for unfiled cluster proposal records found in a chore's
proofs/ directory.
Reads proposal-*.json files from .gzkit/chores/<slug>/proofs/. In TTY
mode, prompts PROPOSE/skip for each unfiled record and calls gh issue create
on confirmation. In headless mode, marks records advisory=true without filing.
Already-filed records (where filed: true) are skipped on re-run. Requires
gh CLI available in $PATH for issue creation.
TTY gating. The command detects sys.stdin.isatty() and sys.stdout.isatty()
before prompting. Non-interactive (CI) environments receive advisory-only output
and no GHI is created.
Example:
# File proposals from the eval-feedback-cluster chore
uv run gz chores propose-ghi eval-feedback-cluster
Options¶
| Flag | Applies To | Description |
|---|---|---|
--explain |
list | Label each row with resolution source (project/package/missing) |
--json |
status, doctor | Output as JSON to stdout |
--dry-run |
doctor | Report-only; no file changes |
--all |
audit | Audit every registered chore |
--quiet, -q |
global | Suppress non-error output |
--verbose, -v |
global | Enable verbose output |
--debug |
global | Enable debug mode with full tracebacks |
--help, -h |
global | Show help and exit |
Exit Codes¶
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | User/config error (missing slug, malformed acceptance.json, etc.) |
| 2 | System/IO error |
| 3 | Policy breach (acceptance criterion failed; layout violation; missing canonical chore not waived) |
Examples¶
# Discover what's available, with resolution source
uv run gz chores list --explain
# Inspect a chore before running it
uv run gz chores show coverage-40pct
# Dry-run criteria
uv run gz chores advise coverage-40pct
# Execute the chore (writes evidence to .gzkit/chores/coverage-40pct/proofs/)
uv run gz chores run coverage-40pct
# Which chores are due or overdue, without running any
uv run gz chores status
# Audit log presence across the registry
uv run gz chores audit --all
# Repair a missing canonical scaffold
uv run gz chores doctor
# Health-check without writing files
uv run gz chores doctor --dry-run
# Machine-readable doctor output
uv run gz chores doctor --json
# File GHI proposals from the eval-feedback-cluster chore (TTY mode)
uv run gz chores propose-ghi eval-feedback-cluster
Files¶
| Path | Role |
|---|---|
.gzkit/chores/<slug>/ |
Canonical chore source (edit here); also project-local chores (created by gz init and gz chores doctor) |
.gzkit/chores/registry.json |
Canonical chore registry |
src/gzkit/chores/<slug>/ |
Distribution copy generated by gz agent sync control-surfaces (shipped in wheel) |
src/gzkit/chores/registry.json |
Distribution registry, filtered to canonical-class chores |
.gzkit/chores/<slug>/proofs/ |
Project-local execution evidence (never canonical) |
importlib.resources.files("gzkit.chores") |
Package resource fallback used when the project-local path is absent |
data/chores_layout_waivers.json |
Explicit waiver list for gz validate --chores-layout |
Related¶
gz validate --chores-layout— fail-closed (exit 3) on strayCHORE.mdoracceptance.jsonoutside the canonical roots.gz-chore-runner— guided workflow for end-to-end chore execution.- ADR-0.0.21 —
docs/design/adr/foundation/ADR-0.0.21-chores-as-gzkit-surface/ - Rule —
.gzkit/rules/chores.md - Agent contract —
src/gzkit/chores/README.md