Add worktree cleanup audit integrity and missing-preserved-worktree detection #404

New Issue

2026-07-07T09:42:51-05:00

jcwalker3 commented

2026-07-07 09:42:51 -05:00

Context:
A branches/ cleanup run removed 68 clean stale worktrees and preserved active/dirty/claim-linked worktrees. The cleanup reduced:

branches/ directories from 127 to 58,
registered branches/ worktrees from 126 to 56,
total repo worktrees from about 140 to 70.

The run reported a serious anomaly: two worktrees classified as “preserve” at audit start were missing at the end and were not listed in the removal log:

branches/review-pr382-feat-issue-295-already-landed-classification
branches/merge-simulation-pr382

Problem:
Cleanup reports can end with a mismatch between preserved classifications, removed-worktree logs, and final filesystem/worktree state. If a dirty or PR-linked worktree disappears without an explicit removal record, the operator cannot tell whether it was removed by mistake, removed by another session, renamed, pruned, or misclassified.

Required behavior:
Worktree cleanup must have auditable before/after identity for every initial branches/ directory and every registered worktree. Anything classified as preserved must either still exist at the end or have a recorded, explained state transition.

Acceptance criteria:

Cleanup captures a before snapshot of:
- find branches -maxdepth 1 -mindepth 1 -type d,
- git worktree list --porcelain,
- clean/dirty status for each worktree,
- active PR/claim/lease linkage.
Cleanup captures an after snapshot of the same data.
Every initial path must have exactly one final disposition:
- removed intentionally,
- preserved and still exists,
- preserved but missing with explanation,
- not a registered worktree,
- unsafe/unknown.
Removal log must include every path removed, method used, timestamp/order, and pre-removal proof.
A path classified as active PR, dirty, claim/lease, or unsafe/unknown cannot disappear without triggering a hard failure.
Cleanup fails closed if final counts do not reconcile.
Cleanup detects concurrent removal or mutation by another session.
Cleanup report must include a reconciliation table:
- initial count,
- removed count,
- preserved count,
- missing-unexplained count,
- final count.
Tests cover:
- preserved worktree remains,
- preserved worktree disappears mid-cleanup,
- dirty worktree disappears,
- active PR worktree disappears,
- orphan dir remains,
- removal log omits a removed path,
- concurrent cleanup race,
- final count mismatch.
Documentation updates the branches cleanup workflow.

Non-goals:

Do not auto-delete dirty worktrees.
Do not auto-delete PR-linked worktrees.
Do not use rm -rf for registered worktrees.
Do not treat missing preserved worktrees as success without explanation.

Context: A branches/ cleanup run removed 68 clean stale worktrees and preserved active/dirty/claim-linked worktrees. The cleanup reduced: * `branches/` directories from 127 to 58, * registered `branches/` worktrees from 126 to 56, * total repo worktrees from about 140 to 70. The run reported a serious anomaly: two worktrees classified as “preserve” at audit start were missing at the end and were not listed in the removal log: 1. `branches/review-pr382-feat-issue-295-already-landed-classification` 2. `branches/merge-simulation-pr382` Problem: Cleanup reports can end with a mismatch between preserved classifications, removed-worktree logs, and final filesystem/worktree state. If a dirty or PR-linked worktree disappears without an explicit removal record, the operator cannot tell whether it was removed by mistake, removed by another session, renamed, pruned, or misclassified. Required behavior: Worktree cleanup must have auditable before/after identity for every initial `branches/` directory and every registered worktree. Anything classified as preserved must either still exist at the end or have a recorded, explained state transition. Acceptance criteria: 1. Cleanup captures a before snapshot of: * `find branches -maxdepth 1 -mindepth 1 -type d`, * `git worktree list --porcelain`, * clean/dirty status for each worktree, * active PR/claim/lease linkage. 2. Cleanup captures an after snapshot of the same data. 3. Every initial path must have exactly one final disposition: * removed intentionally, * preserved and still exists, * preserved but missing with explanation, * not a registered worktree, * unsafe/unknown. 4. Removal log must include every path removed, method used, timestamp/order, and pre-removal proof. 5. A path classified as active PR, dirty, claim/lease, or unsafe/unknown cannot disappear without triggering a hard failure. 6. Cleanup fails closed if final counts do not reconcile. 7. Cleanup detects concurrent removal or mutation by another session. 8. Cleanup report must include a reconciliation table: * initial count, * removed count, * preserved count, * missing-unexplained count, * final count. 9. Tests cover: * preserved worktree remains, * preserved worktree disappears mid-cleanup, * dirty worktree disappears, * active PR worktree disappears, * orphan dir remains, * removal log omits a removed path, * concurrent cleanup race, * final count mismatch. 10. Documentation updates the branches cleanup workflow. Non-goals: * Do not auto-delete dirty worktrees. * Do not auto-delete PR-linked worktrees. * Do not use `rm -rf` for registered worktrees. * Do not treat missing preserved worktrees as success without explanation.

jcwalker3 added the status:in-progress label 2026-07-07 10:48:02 -05:00

jcwalker3 commented

2026-07-07 10:48:11 -05:00

Issue claim heartbeat

kind: claim
issue: Add worktree cleanup audit integrity and missing-preserved-worktree detection (#404)
branch: feat/issue-404-worktree-cleanup-audit
phase: claimed
profile: prgs-author
pr: none
blocker: none
next_action: create worktree and begin implementation

**Issue claim heartbeat** - kind: claim - issue: #404 - branch: feat/issue-404-worktree-cleanup-audit - phase: claimed - profile: prgs-author - pr: none - blocker: none - next_action: create worktree and begin implementation

jcwalker3 referenced this issue from a commit

2026-07-07 10:50:38 -05:00

feat: add worktree cleanup audit integrity (Closes #404)

jcwalker3 referenced a pull request that will close this issue

2026-07-07 10:50:42 -05:00

feat: add worktree cleanup audit integrity (Closes #404) #417

jcwalker3 referenced this issue

2026-07-07 10:56:05 -05:00

Keep audit and reconciliation tasks read-only unless cleanup is explicitly authorized #419

jcwalker3 referenced this issue

2026-07-07 12:20:59 -05:00

Tracker: MCP Control Plane web UI #425