gz-tidy
Use for repository hygiene; reports governance maintenance findings and regenerates surfaces with --fix.
SKILL.md.claude/skills/gz-tidy/SKILL.md
GitHubgz tidy
Overview
gz tidy prints a maintenance report and, with --fix, regenerates the
control surfaces. It deletes nothing. The handler is tidy in
src/gzkit/commands/tidy.py; the report has four sections:
- Validation issues from
validate_all(src/gzkit/validate.py): the manifest, the ledger, every ADR and OBPI document the manifest lists against its schema, the control surfaces including sync parity (a generated file that differs from what sync would write), the instruction audit and the persona files. Each line prints the issue type and message, not the file. - Orphaned OBPIs: ledger OBPIs whose parent ADR is absent from the ledger graph.
- Settings vault: printed when the snapshots of
.claude/settings.local.jsonare drifted, absent or recoverable (vault_statusinsrc/gzkit/settings_vault.py, GHI #1072). The message says what to do. - ADRs pending attestation: every ADR in the ledger graph with no attestation event, pool ADRs included — an inventory, not a defect list, and never gating.
A finding in any of the first three sections is a policy breach: the run
prints ✗ Maintenance breaches found. and exits 3 (GHI #1124). It exits 0 with
✓ All checks passed. Project is tidy. only when none of them has a finding,
and 1 when the project is not initialized or --fix is refused or fails
(below). Until GHI #1125 retires the validate_all fork, its [header] lines
alone keep the run at exit 3.
Flags:
--checkis the report-only mode: the parser refuses it together with--fix(exit 2). A bare run is also report-only unless--fixis given.--fix, after the report, runs the guarded syncgz agent sync control-surfacesuses: it refuses with exit 1, writing no mirror, when canonical skills fail the sync preflight (refuse_on_sync_blockers, GHI #1100); otherwisesync_allregenerates the surfaces and appends anagent_sync_completedledger event, and the post-sync skill audit exits 1 on a blocking parity error. It repairs control-surface drift only, never documents, orphans, the vault or attestations, and unlikegz agent sync control-surfacesit lists neither the updated paths nor stale mirror-only paths. After a successful sync the run re-validates, and the exit status judges that tree, so a drift the sync repaired no longer counts.--dry-runchanges only--fix, to a single "would sync control surfaces" line with no path list. Alone it has no effect.
Workflow
- Run
uv run gz tidy > <file> 2>&1and read the file; the report is long. - Act on each section:
[surface] Generated surface is out of sync: preview withuv run gz agent sync control-surfaces --dry-run, then sync with that command oruv run gz tidy --fix. Sync overwrites a hand edit to a generated file, so move any intended change into canon first.[header]/[frontmatter]lines name no file, and raw-schema-check the historical OBPI corpus thatgz validate --documentsdeliberately skips (GHI #500). Runuv run gz validate --documentsand the version-awareuv run gz validate --briefsfor findings that name the file, and act on those.- Orphaned OBPIs, a vault notice, and the pending-attestation list are reported for the operator; tidy repairs none of them.
- Report what each section held, what was synced, and what remains open.
Claude Surface Validation
In Claude Code, after the report:
- Hook health:
.claude/hooks/*.pyand the hook wiring in.claude/settings.jsonare generated — the scripts bysetup_claude_hooksinsrc/gzkit/hooks/claude.py, the settings bysync_claude_settingsinsrc/gzkit/sync_surfaces.py, which keeps user-added phases and keys. A hand edit shows as a[surface]sync-parity issue. If a hook errored at session start, dispatch theclaude-code-guidesubagent with the failing hook and the error to diagnose it against current Claude Code documentation. The repair belongs in the generator and reaches the tree through sync; never edit the generated file. - Instructions budget: run
uv run gz validate --instructions-files-budget. It is an explicit-tier scope, so neithergz tidynor a baregz validateruns it. The per-file budgets forAGENTS.md,CLAUDE.mdand.claude/rules/*.mdlive indata/instructions_files_budget.json. Trim a file over budget with thegz-context-dietskill. - Skill mirror parity: run
uv run gz skill audit. It checks canonical.gzkit/skills/and the Codex and Claude skill mirrors, each when its vendor is enabled in.gzkit.json§vendors(audit_skillsinsrc/gzkit/skills_audit.py).gz agent sync control-surfacesclears mirror drift.
Example
# Read-only report (identical to --check)
uv run gz tidy > tidy.log 2>&1
# Preview, then apply, the control-surface sync
uv run gz tidy --fix --dry-run
uv run gz tidy --fix
# Actionable, file-named document findings
uv run gz validate --documents
Common Rationalizations
These thoughts mean STOP — you are about to leave drift in place:
| Thought | Reality |
|---|---|
| "Tidy exited 0, so the project is tidy" | Tidy exits 0 whatever it reports. Only the printed sections say what it found. |
"--check is the safe mode" |
--check does nothing a bare run does not; both are read-only. The choice is between reporting and --fix. |
"--fix fixed everything tidy reported" |
--fix only regenerates control surfaces. Document, orphan, vault and attestation findings stay until someone acts on them. |
| "The mirrors look fine — sync isn't needed" | A [surface] issue is the sync-parity check saying they are not. "Looks fine" is not a verification. |
| "CLAUDE.md is over budget but it's all useful content" | The budget in data/instructions_files_budget.json exists because adherence drops past it. Relocate the narrative through gz-context-diet. |
| "Hook errors at startup are pre-existing — not my problem" | Pre-existing failures are still failures. Diagnose, repair the generator, sync. |
Red Flags
- Reading tidy's exit code instead of its output
- Hand-editing a file under
.claude/hooks/or.claude/settings.jsoninstead of its generator - Acting on a
[header]line from tidy without the file-namedgz validatefinding behind it - An instructions file over its budget (
gz validate --instructions-files-budget) with no relocation plan - Hook errors observed but never resolved
- Skill mirrors not regenerated after a skill edit