chore-runner

Purpose

Execute a repository chore using the canonical gz chores workflow.

Inputs

• chore_slug: Chore identifier from the chores registry (uv run gz chores list).
• lane: The configured lane reported by gz chores show (lite, medium, or heavy).

Outputs

• Updated repository files (as defined by the chore).
• Green validation run for the configured lane.
• Execution log in .gzkit/chores/{slug}/proofs/CHORE-LOG.md.

Procedure

1. Discover chores and choose a slug. gz chores status shows which chores are due or overdue without running any, loudest band first (GHI #936):

   uv run gz chores status
   uv run gz chores list
   

2. Inspect the chore details and confirm the lane:

   uv run gz chores show <chore_slug>
   

3. Review the acceptance criteria:

   uv run gz chores plan <chore_slug>
   

4. Dry-run criteria to assess current state:

   uv run gz chores advise <chore_slug>
   

5. If criteria fail, read the CHORE.md workflow and implement fixes:

   • Read .gzkit/chores/<chore_slug>/CHORE.md for the remediation procedure. It is the authoring source; src/gzkit/chores/<chore_slug>/ is the copy sync generates from it (.gzkit/rules/chores.md § Two-Surface Layout). Where the project carries no copy, uv run gz chores show <chore_slug> prints the packaged one
   • Apply fixes surgically — minimal diffs, preserve behavior
   • Iterate: fix, validate, repeat

6. Validate (lane-appropriate):

   # Lite lane (default)
   uv run ruff check . --fix && uv run ruff format .
   uv run ty check . --exclude features
   uv run gz test
   
   # Heavy lane (adds gates)
   uv run gz check --full
   

7. Execute the chore to log the result:

   uv run gz chores run <chore_slug>
   

8. If the chore surfaced a finding that warrants tracking as a GHI, propose one using the chore's eval-feedback output:

   uv run gz chores propose-ghi <chore_slug>
   

9. Audit the logged result:

   uv run gz chores audit --slug <chore_slug>
   

Failure Modes

• Unknown slug: gz chores show <slug> emits BLOCKERS.
• Lane mismatch: Chore expects Heavy actions; do not proceed without meeting gate requirements.
• Criteria fail: Fix issues per CHORE.md workflow and rerun gz chores advise.
• Missing acceptance.json: Registry loader fails closed with BLOCKERS.

Acceptance Rules

• Uses uv run gz chores ... commands (no ad-hoc variants).
• Does not introduce new dependencies.
• Leaves the repo in a validated state for the configured lane.
• Evidence is saved to .gzkit/chores/{slug}/proofs/.

Common Rationalizations

These thoughts mean STOP — you are about to ship a chore that broke its own discipline:

Thought	Reality
"advise looks fine, I'll skip plan and run directly"	The 5-step sequence (show → plan → advise → execute → audit) exists because chores accumulate scope creep when steps merge. Each step is a fail-closed gate.
"I'll add a new dependency — it'll make the fix cleaner"	Acceptance rule: chores do not introduce dependencies. A "cleaner" fix that bloats the dependency surface is a worse fix.
"The chore is lite lane but I need to touch heavy-lane gates"	Lane is set in the chore config, not in the moment. If the work is heavier, fix the chore definition first; do not silently escalate.
"I'll run the chore without reading CHORE.md"	The remediation procedure lives in CHORE.md. Running blind produces ad-hoc fixes that don't match the chore's contract.
"advise passed, no need to run audit"	gz chores audit is what records the proof. Skipping it leaves the chore unverified in the registry.
"The diff is bigger than the chore says — that's fine, I'm fixing adjacent rot"	Adjacent rot is its own chore. Large diffs in a small chore mean two chores are colliding; split them.
"Validation failed but the change is minor — ship it"	Lane validation is the chore's stop-light. Failed lint/typecheck/tests means the chore violated its acceptance rule. Fix or revert.
"A # noqa gets this criterion green"	Suppression turns the exit code green and repairs nothing (.gzkit/rules/chores.md § Suppression is not a repair). Fix the cause, or report the finding open with its recommended repair.

Red Flags

• Skipping any of the 5 steps (show, plan, advise, execute, audit)
• Modifying files outside the chore's declared scope
• Adding dependencies, scripts, or config keys not part of the chore contract
• Running gz chores run before validation passes
• No proof file written to .gzkit/chores/{slug}/proofs/
• Mixing two chores in one execution (collision)
• Ad-hoc command variants instead of uv run gz chores ...
• Suppression markers added by the run (# noqa, # type: ignore, # nosec) — no check sees these, so review the diff