---
id: chores
paths:
  - "src/gzkit/chores/**"
  - ".gzkit/chores/**"
description: Chores workflow command sequences, two-surface layout, and evidence patterns
---

<!-- rule-version: 0.5.2 -->

# Chores Workflow (gzkit)

> **Rule version:** `0.5.2` — the Lite-lane typecheck line is the canonical `uv run ty check . --exclude features` (GHI #921). Prior `0.5.1` and earlier lifted to [Rule Version History](../../docs/governance/rule-version-history.md#choresmd). Binding rules unchanged.

> **Purpose:** Enable agents to run repository chores effectively with clear,
> repeatable command sequences, aligned to gzkit guardrails and the two-surface
> layout introduced by ADR-0.0.21.

## Two-Surface Layout (ADR-0.0.21)

Chores live in two coordinated surfaces:

| Surface | Path | Role | Shipped in wheel? |
|---------|------|------|-------------------|
| Canonical (package) | `src/gzkit/chores/<slug>/` | Authoritative templates discoverable via `importlib.resources("gzkit.chores")` | Yes |
| Project overlay | `.gzkit/chores/<slug>/` | Project-local copies + execution evidence (`proofs/`) | No |

**Resolution order (project-first → package-fallback):** `gz chores` resolves
each slug from `<project_root>/.gzkit/chores/<slug>/` first; if the project-local
directory is absent or incomplete, it falls back to the package resource. The
registry file (`registry.json`) follows the same order. `gz chores list --explain`
prints one row per chore labeling the resolution source as `project`, `package`,
or `missing` (REQ-0.0.21-04-04).

`proofs/` is **always project-local, never canonical** — execution evidence is
generated at run time and written under `.gzkit/chores/<slug>/proofs/`. Canonical
templates do not ship `proofs/` content.

## Core Principles

| Principle           | Description                                     |
| ------------------- | ----------------------------------------------- |
| **Plan-first**      | Generate or refresh a chore plan before any run |
| **Lite by default** | Run `uv run gz test` (unit tier only); no `behave`, no network, no external services. Duration ceilings are a test-infra contract (see `.gzkit/rules/tests.md` § Smoke/BVT) — not an agent-introspected clock. |
| **Small diffs**     | Touch only files in scope for the chore         |
| **CLI evidence**    | Never use raw SQL for attestation               |
| **Layout discipline** | Stray `CHORE.md` or `acceptance.json` outside the two canonical roots is a defect — `gz validate --chores-layout` enforces it (REQ-0.0.21-08-04). |

## Suppression is not a repair (binding)

**A chore never discharges a finding by suppression.** Writing a suppression marker (`# noqa`, `# type: ignore`, `# ty: ignore`, `# nosec`, `# pragma: no cover`), widening a tool's ignore or exclude list, or hiding a criterion's exit status turns the exit code green and changes nothing about correctness. gzkit's attestation evidence is exit codes, so that is manufactured evidence, never a lesser repair. A finding the chore cannot fix is reported open with its recommended repair, or routed to the operator.

- **Mechanical arm.** The registry loader refuses `&&`, `||`, `|`, `<` and `>` in a criterion (`SHELL_OPERATORS_RE`), and `audit_chore_suppression` fails a registered chore whose criterion runs through a shell interpreter or passes an exit-forcing flag, or whose criterion or CHORE.md command writes markers (`ruff --add-noqa`, `ty --add-ignore`, `pyrefly suppress`). A workflow report capture ending `|| true` gates nothing and stays permitted.
- **(Advisory — a marker hand-written during a run is not detected.)** Nothing binds a chore run to the diff it leaves, so this arm has no witness; review the run's diff for suppression growth.

Rationale and the measured suppression inventory: `docs/governance/chore-class-system.md` § Suppression — the fifth posture, prohibited.

## Command Sequences

### 1. Discover Chores

```bash
uv run gz chores status                # Staleness band per chore, without running any; never gates
uv run gz chores list                  # List declared chores
uv run gz chores list --explain        # Show resolution source per chore (project/package/missing)
uv run gz chores show <chore_slug>     # Display CHORE.md for one chore
```

### 2. Plan & Advise

```bash
uv run gz chores plan <chore_slug>
uv run gz chores advise <chore_slug>
```

### 3. Apply Advice

1. **Read advice** — Identify discrete actions
2. **Create TODO list** — Exactly one item in-progress at a time
3. **Implement surgically** — Minimal diffs, preserve behavior
4. **Validate locally** — Lint, typecheck, tests
5. **Sync if green** — Commit/push after validation passes

```bash
uv run ruff check . --fix && uv run ruff format .
uv run ty check . --exclude features
uv run gz test
```

### 4. Execute and Audit

```bash
uv run gz chores run <chore_slug>      # Execute one chore by slug; logs to .gzkit/chores/<slug>/proofs/
uv run gz chores audit --all           # Audit log presence for all chores
```

### 5. Health and Layout

```bash
uv run gz chores doctor                 # Repair missing canonical files in .gzkit/chores/ from package
uv run gz chores doctor --dry-run       # Report-only; no file changes
uv run gz chores doctor --json          # One JSON record per slug (slug, before_status, after_status)
uv run gz validate --chores-layout      # Fail closed (exit 3) on stray CHORE.md or acceptance.json
```

`doctor` never touches `proofs/` content (REQ-0.0.21-09-05) and never modifies
project-local-only slugs (REQ-0.0.21-09-06).

## Evidence & Attestation

### Correct Evidence (CLI commands only)

```bash
uv run gz check
uv run behave features/<feature>.feature --tags=@schema
```

### Prohibited Evidence

- Raw SQL statements
- Direct DB queries for attestation
- Bypassing CLI interface

## Authoring a New Chore

Canonical chore packages live in `src/gzkit/chores/<slug>/` (shipped in the
wheel). Project-specific overrides go in `.gzkit/chores/<slug>/`. Each slug
directory contains:

| File | Purpose | Required |
|------|---------|----------|
| `CHORE.md` | Definition, workflow, acceptance criteria | Yes |
| `acceptance.json` | Machine-readable criteria for automation | Yes |
| `README.md` | Human-readable summary | Yes |
| `proofs/` | Project-local execution evidence (never canonical) | Yes (project-local) |

The full agent contract for authoring chores lives at
[`src/gzkit/chores/README.md`](../../src/gzkit/chores/README.md).

## Related

- ADR-0.0.21 — `docs/design/adr/foundation/ADR-0.0.21-chores-as-gzkit-surface/`
- Manpage — `docs/user/manpages/chores.md`
- Runbook — `docs/user/runbook.md` § Chores Commands
- Skill — `.gzkit/skills/gz-chore-runner/`
