Worktrees accumulate unreaped: 115 of 142 were clean and disposable, across 6 roots including one the convention forbids

[kyle-sexton]

Summary

Worktrees accumulate without bound across this fleet and nothing reaps them. A
hygiene pass today found 142 linked worktrees across 6 different roots,
of which 115 were clean and disposable — no tracked changes, no untracked
files, not locked. They had simply never been removed. Only 27 held real
uncommitted state.

Nothing in the current tooling classifies a clean-but-stale worktree as
reclaimable, so they are invisible to every audit and survive indefinitely.

The measured state before cleanup

Root	Registrations
<ghq>/melodic-software/claude-code-plugins/.claude/worktrees	55
<ghq>/melodic-software (siblings)	58 (incl. 11 canonical)
~/.claude/plugins/data/source-control-melodic-software/worktrees	37
~/.claude-loop-worktrees	38
C:/tmp	6
~/.codex/worktrees/*	2
system temp / dead-session scratchpad	2

After removing every clean one: 11 canonical + 27 linked remain, all 27 holding
uncommitted work or locked.

Defect 1: no disposability lane

repo-fleet-hygiene:audit classifies worktrees as merged-worktree,
prunable-worktree, missing-worktree, worktree-admin-mismatch, or
locked-worktree. There is no category for clean worktree, branch not
merged — which was the state of most of the 115.

That gap matters because worktree disposability is independent of merge state.
Removing a clean worktree destroys nothing: the branch ref and every commit live
in the canonical repository. The only thing a worktree uniquely holds is
uncommitted work. So the correct predicate is:

disposable  <=>  no tracked changes AND no untracked files AND not locked

Merge status is irrelevant. During this pass I initially gated removal on "the
branch is also deletable" and consequently removed only 55 of 115 — the same
conservatism the audit's taxonomy encodes.

Requested: a reclaimable-worktree finding for any clean, unlocked linked
worktree, with age or last-commit recency as the ranking signal rather than merge
state.

Defect 2: git stash list in a linked worktree reports the whole repository

A trap worth encoding in whichever helper computes worktree state. refs/stash
is shared per repository, so git stash list run inside a linked worktree
returns the canonical repo's entire stash list, not that worktree's. It reads
non-zero for every worktree of any repo that has ever stashed.

I gated removal on stash == 0 and it silently excluded 113 of 115 candidates.
Stashes survive worktree removal, so stash count must not be part of a
disposability predicate. Any shared worktree helper should either not expose it
per-worktree or name it repo_stash_count.

Defect 3: six roots, one of which the documented convention forbids

The documented policy (user-scope doc ghq-layout-sibling-pr-worktrees.md) is a
sibling layout, <canonical>-pr-<number>, and it explicitly rules out
.claude/worktrees/ inside the repo when the canonical checkout is a ghq tree.
Yet 55 registrations were in exactly that forbidden location, nested inside
claude-code-plugins' own working tree, and three more roots exist that the doc
does not mention at all.

Naming is equally scattered. Observed schemes among siblings alone:

• standards-pr-223 (the documented form — 1 of 23)
• ci-workflows-pr281 (no separator before the number)
• claude-code-plugins-issue-1017 (issue, not PR)
• claude-code-plugins-1211 (bare number)
• claude-code-plugins-1285-argparse (number plus slug)
• medley-plugin-user-scope (no number at all)

and elsewhere worktree-agent-<17-hex>, ccp-1269, 609, 848-sigfix,
drive-1503-v2, wip/lane-snapshot/<slug>.

Requested: one resolver that every worktree-creating skill calls, so location and
naming cannot drift per caller, plus a check that fails when a registration
appears outside the sanctioned roots.

Defect 4: removal leaves shells behind when workspace symlinks exist

git worktree remove succeeded but left a directory tree behind for a medley
worktree, because npm workspace symlinks under
.claude/skills/*/extraction/node_modules/@melodic/ were not created by git and
are not removed by it. The links dangled (their targets were inside the removed
tree), so find -type f reported zero files while rmdir refused with
"Directory not empty" — the residue is symlinks, which neither predicate sees.

Worth handling in whichever skill wraps worktree removal: after a successful
git worktree remove, if the path still exists, report it, and check for
non-directory non-file entries rather than assuming "no files" means empty.

Impact

Beyond disk, the accumulation actively blocks hygiene: an attached branch cannot
be deleted, so 115 stale worktrees were pinning branches that were otherwise
provably merged. Cleanup had to run worktree-removal before branch-deletion for
55 branches in this pass.

Environment

• 11 canonical checkouts, melodic-software org, ghq layout on D:/repos
• Git 2.54.0.windows.1, Claude Code on Windows 11 Pro 10.0.26200
• Observed 2026-07-29

[kyle-sexton]

Follow-up from a plugin-quality:audit pass on repo-fleet-hygiene:audit 0.7.0. Adding one
structural fact rather than opening a duplicate, since this issue already covers the missing
disposability lane.

The reclaimable-worktree lane is not just unimplemented — as the collector is currently built it is
unproducible.

audit-fleet.sh routes every git call through a fail-closed probe allowlist (git_probe_allowed,
roughly lines 52–117). That allowlist admits the commands the audit needs for its existing findings —
worktree list --porcelain, for-each-ref, rev-parse, merge-base, remote get-url, and so on. It
does not admit status, diff, or ls-files.

Worktree disposability is defined by exactly the state those three commands report: whether the tree has
tracked modifications and whether it has untracked files. So the collector cannot observe disposability
at all with its current allowlist — the lane cannot be added as a reporting change, and any
implementation forces a decision:

• Widen the allowlist with read-only disposability probes (status --porcelain,
  status --porcelain --untracked-files=normal), and accept that the plugin's security review needs
  re-running because the allowlist is the security boundary; or
• Declare disposability explicitly out of scope in the skill body — not only in the changelog — so a
  consumer knows the audit will never surface it and does not read "no worktree findings" as "no
  reclaimable worktrees".

The choice matters because the gap is large in practice. On the fleet that prompted this issue, 115 of
142 linked worktrees were clean and disposable and none of them appeared in any audit finding, before
or after cleanup. The audit reported high=1 at a point when 27 linked worktrees remained, all of which
genuinely held uncommitted work — so the post-cleanup report was accurate, but only because the cleanup
had already been done by hand.

Two traps for whoever implements it, both hit during that cleanup:

1. Do not include stash count in a disposability predicate. refs/stash is shared per repository, so
   git stash list inside a linked worktree returns the canonical repo's entire stash list. A
   stash == 0 condition silently excluded 113 of 115 candidates in my first attempt. Stashes survive
   worktree removal.
2. find <dir> -type f is not an emptiness test. After git worktree remove succeeded, one
   directory remained because dangling npm workspace symlinks under
   .claude/skills/*/extraction/node_modules/@melodic/ were not git-created and are not git-removed.
   -type f returned 0 while rmdir refused with Directory not empty. Use
   find <dir> -mindepth 1 ! -type d.

[kyle-sexton]

Cursor worker claimed #1776 for the reclaimable-worktree peel. Branch: cursor/reclaimable-worktree-1776-d116.