feat: add session-owned worktree cleanup audit and TTL enforcement (Closes #401) #492

2026-07-08T01:40:52-05:00

jcwalker3 commented

2026-07-08 01:40:52 -05:00

Summary

Closes #401.

Adds session-owned worktree cleanup audit and TTL enforcement for the branches/ directory. The implementation classifies worktrees conservatively, exposes a read-only MCP audit tool, and documents cleanup proof requirements in the author and reviewer workflows.

Changes

worktree_cleanup_audit.py — metadata, TTL, classification, removal assessment, git helper, and audit report helpers
gitea_mcp_server.py — new read-only gitea_audit_worktree_cleanup MCP tool
tests/test_worktree_cleanup_audit.py — coverage for metadata, TTL, preservation/removal classification, removal proof, shell helpers, and audit reporting
skills/llm-project-workflow/workflows/work-issue.md — session-owned worktree cleanup and TTL policy
skills/llm-project-workflow/workflows/review-merge-pr.md — cleanup proof requirements for review/baseline/merge-simulation worktrees

Validation

/Users/jasonwalker/Development/Gitea-Tools/venv/bin/python -m py_compile worktree_cleanup_audit.py gitea_mcp_server.py
# exit 0

/Users/jasonwalker/Development/Gitea-Tools/venv/bin/python -m pytest tests/test_worktree_cleanup_audit.py tests/test_worktrees.py tests/test_reviewer_worktree.py tests/test_reviewer_worktree_ownership.py -q
# 67 passed, 13 subtests passed

/Users/jasonwalker/Development/Gitea-Tools/venv/bin/python -m pytest tests/ -q
# 1626 passed, 6 skipped, 23 subtests passed

git diff --check prgs/master...HEAD
# exit 0

Secret/artifact scans over the branch diff returned no matches.

Risk

Moderate. This adds a read-only audit tool plus cleanup classification logic. Removal remains gated by explicit proof and the new MCP tool deletes nothing.

Worktree

Implementation worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-401-worktree-cleanup-ttl
Lock worktree used for adopted branch gate: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-401-lock-base
Branch: feat/issue-401-worktree-cleanup-ttl
Commit: 87b1c79431d4b0b17842c79ab652cb48a29a8325

LLM Handoff Metadata

LLM-Agent-SHA: llm-e38930bbc808
LLM-Role: implementer
Authenticated-Gitea-User: jcwalker3
MCP-Profile: prgs-author
Branch: feat/issue-401-worktree-cleanup-ttl
Worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-401-worktree-cleanup-ttl
Self-review allowed: no

## Summary Closes #401. Adds session-owned worktree cleanup audit and TTL enforcement for the `branches/` directory. The implementation classifies worktrees conservatively, exposes a read-only MCP audit tool, and documents cleanup proof requirements in the author and reviewer workflows. ## Changes - `worktree_cleanup_audit.py` — metadata, TTL, classification, removal assessment, git helper, and audit report helpers - `gitea_mcp_server.py` — new read-only `gitea_audit_worktree_cleanup` MCP tool - `tests/test_worktree_cleanup_audit.py` — coverage for metadata, TTL, preservation/removal classification, removal proof, shell helpers, and audit reporting - `skills/llm-project-workflow/workflows/work-issue.md` — session-owned worktree cleanup and TTL policy - `skills/llm-project-workflow/workflows/review-merge-pr.md` — cleanup proof requirements for review/baseline/merge-simulation worktrees ## Validation ```bash /Users/jasonwalker/Development/Gitea-Tools/venv/bin/python -m py_compile worktree_cleanup_audit.py gitea_mcp_server.py # exit 0 /Users/jasonwalker/Development/Gitea-Tools/venv/bin/python -m pytest tests/test_worktree_cleanup_audit.py tests/test_worktrees.py tests/test_reviewer_worktree.py tests/test_reviewer_worktree_ownership.py -q # 67 passed, 13 subtests passed /Users/jasonwalker/Development/Gitea-Tools/venv/bin/python -m pytest tests/ -q # 1626 passed, 6 skipped, 23 subtests passed git diff --check prgs/master...HEAD # exit 0 ``` Secret/artifact scans over the branch diff returned no matches. ## Risk Moderate. This adds a read-only audit tool plus cleanup classification logic. Removal remains gated by explicit proof and the new MCP tool deletes nothing. ## Worktree - Implementation worktree: `/Users/jasonwalker/Development/Gitea-Tools/branches/issue-401-worktree-cleanup-ttl` - Lock worktree used for adopted branch gate: `/Users/jasonwalker/Development/Gitea-Tools/branches/issue-401-lock-base` - Branch: `feat/issue-401-worktree-cleanup-ttl` - Commit: `87b1c79431d4b0b17842c79ab652cb48a29a8325` ## LLM Handoff Metadata - LLM-Agent-SHA: llm-e38930bbc808 - LLM-Role: implementer - Authenticated-Gitea-User: jcwalker3 - MCP-Profile: prgs-author - Branch: feat/issue-401-worktree-cleanup-ttl - Worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/issue-401-worktree-cleanup-ttl - Self-review allowed: no

jcwalker3 added 1 commit 2026-07-08 01:40:52 -05:00

feat: add session-owned worktree cleanup audit and TTL enforcement (Closes #401 ) cedf451a2b

Stale worktrees accumulate under branches/ when runs stop early, race a
sibling session, hit a validation failure, or lose cwd state, making later
workflow decisions harder and riskier.

Changes:
- worktree_cleanup_audit.py — ownership metadata, safety-first classifier
  (active_open_pr, active_issue_work, dirty_local_worktree,
  clean_stale_removable, detached_review_leftover, unsafe_unknown), TTL
  expiry, per-worktree removal proof, and success-completion cleanup plan.
  Only clean_stale_removable and detached_review_leftover are removable;
  dirty/PR/leased/protected/unknown worktrees are never auto-deleted.
- gitea_audit_worktree_cleanup — read-only MCP tool that classifies every
  branches/ entry, fetches live open-PR heads (fails closed if unavailable),
  and returns counts, removable candidates, and git worktree list proof.
- work-issue.md 22A + review-merge-pr.md 28 — cleanup/TTL workflow rules.
- tests/test_worktree_cleanup_audit.py — 30 cases covering all nine
  acceptance scenarios plus inference, metadata, TTL, and report accuracy.

Validation:
  /Users/jasonwalker/Development/Gitea-Tools/venv/bin/python \
    -m unittest tests.test_worktree_cleanup_audit tests.test_merged_cleanup_reconcile -q
  38 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

sysadmin commented

2026-07-08 09:57:52 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #492
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 98052-08e74502c2cd
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr492
phase: claimed
candidate_head: none
target_branch: master
target_branch_sha: none
last_activity: 2026-07-08T14:57:51Z
expires_at: 2026-07-08T16:57:51Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #492 issue: none reviewer_identity: sysadmin profile: prgs-reviewer session_id: 98052-08e74502c2cd worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr492 phase: claimed candidate_head: none target_branch: master target_branch_sha: none last_activity: 2026-07-08T14:57:51Z expires_at: 2026-07-08T16:57:51Z blocker: none

sysadmin commented

2026-07-08 09:58:02 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #492
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 98052-08e74502c2cd
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr492
phase: claimed
candidate_head: none
target_branch: master
target_branch_sha: none
last_activity: 2026-07-08T14:58:02Z
expires_at: 2026-07-08T16:58:02Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #492 issue: none reviewer_identity: sysadmin profile: prgs-reviewer session_id: 98052-08e74502c2cd worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr492 phase: claimed candidate_head: none target_branch: master target_branch_sha: none last_activity: 2026-07-08T14:58:02Z expires_at: 2026-07-08T16:58:02Z blocker: none

sysadmin approved these changes 2026-07-08 09:58:05 -05:00

sysadmin left a comment

Approved. PR #492 successfully adds session-owned worktree cleanup audit and TTL enforcement.

sysadmin commented

2026-07-08 10:09:35 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #492
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 98052-08e74502c2cd
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr492
phase: claimed
candidate_head: cedf451a2b
target_branch: master
target_branch_sha: none
last_activity: 2026-07-08T15:09:35Z
expires_at: 2026-07-08T17:09:35Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #492 issue: none reviewer_identity: sysadmin profile: prgs-reviewer session_id: 98052-08e74502c2cd worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr492 phase: claimed candidate_head: cedf451a2ba635d42ebe7d35391abe11ceb5daf8 target_branch: master target_branch_sha: none last_activity: 2026-07-08T15:09:35Z expires_at: 2026-07-08T17:09:35Z blocker: none

sysadmin commented

2026-07-08 10:10:32 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #492
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 98052-08e74502c2cd
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr492
phase: claimed
candidate_head: cedf451a2b
target_branch: master
target_branch_sha: none
last_activity: 2026-07-08T15:10:32Z
expires_at: 2026-07-08T17:10:32Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #492 issue: none reviewer_identity: sysadmin profile: prgs-reviewer session_id: 98052-08e74502c2cd worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr492 phase: claimed candidate_head: cedf451a2ba635d42ebe7d35391abe11ceb5daf8 target_branch: master target_branch_sha: none last_activity: 2026-07-08T15:10:32Z expires_at: 2026-07-08T17:10:32Z blocker: none

sysadmin commented

2026-07-08 10:11:06 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #492
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 98052-08e74502c2cd
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr492
phase: claimed
candidate_head: cedf451a2b
target_branch: master
target_branch_sha: none
last_activity: 2026-07-08T15:11:06Z
expires_at: 2026-07-08T17:11:06Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #492 issue: none reviewer_identity: sysadmin profile: prgs-reviewer session_id: 98052-08e74502c2cd worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr492 phase: claimed candidate_head: cedf451a2ba635d42ebe7d35391abe11ceb5daf8 target_branch: master target_branch_sha: none last_activity: 2026-07-08T15:11:06Z expires_at: 2026-07-08T17:11:06Z blocker: none

sysadmin merged commit 0b62d4e06a into master

2026-07-08 10:11:16 -05:00

jcwalker3 referenced this pull request

2026-07-08 10:19:55 -05:00

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

jcwalker3 referenced this pull request

2026-07-08 10:19:55 -05:00

feat: add workflow-load session boundary proof (Closes #403) #422

jcwalker3 referenced this pull request

2026-07-08 10:27:25 -05:00

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

jcwalker3 referenced this pull request