disk-hygiene:clean misses underscore-prefixed temp dirs and unowned agent-session files at a home-directory root

[kyle-sexton]

---

type: bug-report
date: 2026-07-17T19:13:47Z
slug: disk-hygiene-misses-home-droppings
severity: low
fix-location: plugins/disk-hygiene/skills/clean/reference/baseline-policy.json

Bug: disk-hygiene:clean misses underscore-prefixed temp dirs and unowned agent-session files at a home-directory root

Severity: low
Suggested fix location: plugins/disk-hygiene/skills/clean/reference/baseline-policy.json (hint list) and plugins/disk-hygiene/skills/clean/SKILL.md §2 (evidence/triage guidance)
Reported by: kyle.sexton@melodicsoftware.com (Claude Code session c1d8eb12)
Reported at: 2026-07-17T19:13:47Z

Steps to reproduce

1. In a home directory (C:\Users\<user>), have the following agent-session droppings present:
   • tmp_comment_hygiene\ — directory of shell scripts left by a comment-hygiene scan session (underscore-prefixed temp dir)
   • melo-lap-001-*.json — five runner-controller status snapshots left by a canary-rollout session
   • org_usage.json — a one-off org usage export
2. Run /disk-hygiene:clean targeting the home directory.
3. Review the audit report.

Expected behavior

All seven entries surface as findings (at least Low/Medium tier) for ownership triage — they are loose, unowned, session-generated artifacts sitting at the target root, squarely the "clean up my home directory" use case the skill's description claims.

Actual behavior

None of them appear in the report. (Miss reported by the user from a prior run; not re-executed during this capture — see Notes.)

Severity justification

Dev-tooling drift only: missed reclaim of a few KB of junk, no data loss, no blocked workflow — but it silently undercuts the skill's core "home directory audit" promise.

Notes

Root-cause analysis from reading the installed skill (v0.1.x, marketplace melodic-software/claude-code-plugins):

1. Hint glob misses the underscore variant. baseline-policy.json ships tmp-* (common-temp-directory) but not tmp_*. tmp_comment_hygiene therefore carries no hint annotation in the snapshot. Agents and humans both emit underscore-prefixed temp names; the hyphen-only glob is an arbitrary half of the convention.
2. No hint class for agent-leaked session-state files. The policy already has precedent for agent-leftover hints (temp_git_*, .pulumi-write-test-*, .claude.json.tmp.*), but nothing catches loose status-snapshot/export JSON files an agent session writes to the target root (melo-lap-001-*.json, org_usage.json). A generic glob is admittedly hard; an alternative is a positional heuristic rather than a name heuristic (next point).
3. SKILL.md leaves "suspicious" undefined. The engine snapshots every entry (hints only annotate — hygiene.py appends all walked paths with a possibly-empty hints list), so the data was available; §2 says to inspect "each hinted or suspicious entry" but gives the model no criteria for suspicious. Suggested guidance: at a user-home target, any loose root-level file not in protected_exact_names and not part of a recognizable app/config convention warrants ownership triage.

Fix direction (for the fixer to decide): add tmp_*-style hint(s) to the baseline policy, and/or define the "suspicious" criteria in SKILL.md §2 so unhinted root-level strays get triaged instead of skipped.

Deferred related item (prevention, separate concern — candidate for the guardrails plugin): the litter's root cause is Claude Code sessions writing temp files to the home directory / cwd instead of the session scratchpad directory. A PreToolUse guard or standing rule ("never write temp files to ~") would stop recurrence at the source. Trigger to revisit: next time home-directory droppings from an agent session are found.

(unknown — needs reporter confirmation): exact invocation of the original run (target argument, flags, whether a policy overlay was active) — the miss is reported from the user's observation of the leftover files, and the structural gaps above hold regardless.

---

Generated by /bug-report:write (--file mode). To file it as a work item in a GitHub repo:
gh issue create --body-file <this report path> (let gh prompt for the title),
or use an available tracker MCP tool.

[kyle-sexton]

Concrete additional case from a live home-root audit: Claude Code's own atomic-write staging files
named .claude.json.tmp.<pid>.<hash> are left orphaned at the home root when a .claude.json write
is interrupted (found 2 this session, ~74 KB each, both older than the live .claude.json, owning
pids dead). These are high-confidence disposable (failed-write staging, owner absent, a durable newer
consumer exists) but no baseline hint matches them, so the scan would miss them — same class as the
underscore-prefixed temp dirs and unowned agent-session files this issue already tracks.

Worth a baseline hint for *.tmp.<pid>.<hash> atomic-write leftovers (high ceiling when the owning
pid is absent and a newer canonical file exists).

[kyle-sexton]