repo-hygiene: add an opt-in .work/ tidy mode

[kyle-sexton]

What happened

A whole-machine cleanup reviewed 11 .work/ items across repos. Eight belonged to PRs that had already merged or issues that had already closed. Nothing in repo-hygiene looks at .work/, so they stay until someone attributes each one by hand.

Proposal

An opt-in mode of /repo-hygiene:clean (off by default) that tidies .work/:

1. Inventory every entry under .work/ (name, size, mtime).
2. Attribute each to its PR or issue (from the name, a marker file, or the branch that produced it) and report that PR or issue's state.
3. Once the PR merges or the issue closes, delete the entry or consolidate it into a uniform layout (for example .work/<issue-or-pr>/<artifact>), behind the usual confirmation gate.
4. Entries that cannot be attributed are listed and never deleted.

Why opt-in

.work/ is the gitignored place agents put backups and scratch, so an entry may be the only copy of something. The mode has to be requested, list what it would remove first, and leave unattributed entries alone.

Evidence

git grep -F ".work/" origin/main -- plugins/repo-hygiene returns nothing, so the skill has no notion of the directory. The batch forms (#994) cover caches, build output and git only.

[kyle-sexton]

Problem

.work directories (one under home, one per repo) accumulate handoffs, topic slices and scratch. session-flow defines their layout but no plugin cleans or normalizes them. disk-hygiene deliberately hints scratch* at low confidence only (baseline-policy.json, scratch-artifact), and repo-hygiene covers caches, build output and git, not .work.

Skills also drop scratch into .work with no lifecycle. In one session, /discovery:research run inline wrote its artifact to ~/.work/local-otel-claude-code, so other plugins' output lands in .work with nothing owning its cleanup.

Evidence

• session-flow 0.38.26 owns the convention: reference/topic-docs.md:21-22 (handoffs in <memory_dir>/handoffs/, default .work/handoffs/; workflow-checklist.md in .work/<slug>/); memory root default .work at reference/structure.md:486 (MEMORY_ROOT="${MEMORY_ROOT:-.work}").
• The only deletion in session-flow is the observer data under ${CLAUDE_PLUGIN_DATA}/session-flow-observer/, "deleted after the analysis run consumes them" (reference/topic-docs.md:33). No skill prunes .work.
• work-items: mirror .work topic-slice trees out to tracker issues #3555 (closed) mirrored .work topic-slice trees to tracker issues, which is the tracker link needed for in-flight detection.

Expected

An opt-in action (nothing runs unless invoked), for example /session-flow:tidy-work:

1. Inventory .work in the current repo and in home: per item, age, size, kind (handoff, checklist, slice, scratch, unknown).
2. In-flight detection: linked open issue or PR (from topic frontmatter or handoff), modified within N days, referenced by a later handoff or an unfinished checklist stage.
3. Actions: report, normalize (move to the standard layout, no deletion), clean (remove items that are not in flight, after listing the exact paths and one confirmation).
4. Anything unknown stays and is reported.

Proposed direction

Read-only report first (reuses the existing frontmatter and ledger parsers in scripts/save_point.py), clean second behind the shared confirmation pattern. It should call disk-hygiene's protection list rather than duplicating it if both are installed.

Related: #3555, #4295 (closed, handoff fallback path), #4228.

🤖 Generated with Claude Code

https://claude.ai/code/session_01K3VkbjLqtYZ6JtsQaDKP4v