disk-hygiene and repo-hygiene: default to a deep, justified inventory instead of category skips

[kyle-sexton]

What happened

The operating procedure for a machine cleanup is: always produce a recursive listing (name, extension, size, mtime, owner, producer attribution) and require a written justification for every KEEP. "Tool-managed" or "OS-owned" alone is not a reason to keep something.

The default passes of /disk-hygiene:clean and /repo-hygiene:clean do not work that way. On one machine they missed about 4.8 GB of real cruft that a deep pass found:

• 3.4 GB of superseded Codex, Claude Code and cursor-agent binaries (old versions left beside the current one)
• 476 MB of uninstalled plugin cache versions
• 94 MB (about 5,000 items) of test-harness leftovers in /tmp
• orphaned ~/.claude/projects/-tmp-* transcripts
• broken mise trusted-config symlinks

Evidence (checked against origin/main)

• plugins/disk-hygiene/skills/clean/SKILL.md:188-190 starts a large root with a bounded --max-depth 1 pass and fans out only "per subtree that the evidence justifies".
• SKILL.md:71 excludes OS-owned, hidden and system entries from selection. Nothing requires a per-entry reason for the exclusion, so "OS-owned" or "tool-managed" ends the inquiry.
• The decision procedure at SKILL.md:266-281 keeps anything uncertain and treats name-only or age-only signals as Low. That is right for deletion, but it produces no inventory of what was kept and why.
• plugins/repo-hygiene has no machine-level listing at all.

Expected behavior

For an attended whole-machine pass, the default is a deep inventory in which every entry gets a disposition and every KEEP names a reason (who produced it, what is using it, why it must stay). A blanket "managed by tool X" is rejected unless the skill can show X still references the entry. Superseded versions of versioned installs (keep the newest and the running one) and uninstalled plugin cache versions are named categories.

Suggested direction

• A --deep mode (or a deep default when the target is a whole home directory) that emits the recursive listing with the columns above and fails the report if any KEEP has an empty or category-only reason.
• Producer attribution rules for the categories found here: versioned binary directories, plugin cache versus installed plugins, /tmp by producer prefix, transcript directories whose source path no longer exists, dangling symlinks.
• Related: disk-hygiene: whole-machine audit driven by an orchestrator and subagents (no model-invocable audit, 250k cap needs manual splitting, guard and output gaps) #5214 (orchestrated whole-machine audit), disk-hygiene: add a gated managed-state lane with a bundled owner registry #4006 (managed-state lane), disk-hygiene:clean — ceremony does not scale to stakes: audit of a real --execute run (13 live findings) #3347. None asks for depth-by-default plus a justification per KEEP, so this is filed separately.

[kyle-sexton]

Owner decision (2026-09-30): Do this in the repo as a read-only, report-only change. No deletion path is touched.

1. Add an attended deep-inventory mode to plugins/disk-hygiene/skills/clean. It is the default when the target is a whole home directory, and can be forced with --deep. It emits the recursive listing with name, ext, size, mtime, owner, producer, disposition, and reason.
2. Add a deterministic report validator. It fails the report if any KEEP has an empty or category-only reason ("tool-managed", "OS-owned"), unless the engine can show the named tool still references the entry.
3. Add producer-attribution rules as named categories: superseded versioned binary dirs (keep newest and running), uninstalled plugin cache versions (reuse the unreferenced-cache-version logic from claude-ops audit-install-state, feat(claude-ops): report unreferenced plugin cache versions in audit-install-state #5420), /tmp by producer prefix, ~/.claude/projects transcript dirs whose source path is gone, and dangling symlinks.
4. Add tests for the validator and for each category.
5. Keep existing deletion safety unchanged: --execute, the low-signal keep rule at SKILL.md:266-281, and the confirmation gates stay as they are. Deep inventory must not lower any deletion threshold. Anything that actually deletes the 4.8 GB stays owner-confirmed, elevated or destructive, through the existing gated flow.
6. Coordinate with disk-hygiene: whole-machine audit driven by an orchestrator and subagents (no model-invocable audit, 250k cap needs manual splitting, guard and output gaps) #5214 (orchestrated audit) and disk-hygiene: add a gated managed-state lane with a bundled owner registry #4006 (managed-state lane) so the listing schema is shared; do not fold them in.
7. repo-hygiene has no machine-level listing, so scope that half as a pointer to disk-hygiene deep mode, not a new scanner.
8. Open as a draft PR with a Closes #5221 line. The gh GraphQL rate limit can run out; use gh api (REST) then.

Approved by the owner with all consensus recommendations on 2026-09-30 (three read-only researchers, majority or judge).

Next: labeled agent-ready; the work loop picks it up and opens a draft PR.