thebpandey/session-cleanup

工作階段清理

先稽核，再刪除，且僅在檢查目標後執行。目標是讓擁有者能安心離開工作階段，知道沒有程式在執行、沒有資料遺失、也沒有任何過時的遺留物。遺漏一個遺留物代價很小；刪除一個未推送的提交則不然。如有疑慮，發現結果應歸入 ASK，絕不歸入 AUTO-CLEAN。

適用於任何 Git 儲存庫。Lanes 工具、beads 和 Vercel 相關部分僅在它們存在時啟用；否則會靜默跳過。

第一階段：稽核（唯讀）

從儲存庫（任何工作樹）執行內建的稽核腳本。請根據您的作業系統使用對應的腳本；技能資料夾可能位於 ~/.claude/skills/、~/.codex/skills/ 或 ~/.agents/skills/：

# Linux 和 macOS
bash <skill-dir>/scripts/audit.sh                 # 離線時加上 --no-fetch

# Windows（PowerShell 5.1 或 7）
powershell -NoProfile -ExecutionPolicy Bypass -File <skill-dir>\scripts\audit.ps1   # 離線時加上 -NoFetch

兩者都會輸出每個區域的章節（CONTEXT、WORKING_TREE、SYNC、WORKTREES、BRANCHES、STASHES、LANES、PROCESSES、ARTIFACTS、TRACKER、DEPLOY、SESSION_LOG）。腳本唯一的寫入動作是單純的 git fetch（從不使用 --prune）。它絕不會讀取 .env 檔案或印出程序環境變數。

如何判斷「此次工作階段」（這對每個分類都很重要）：

• 程序： owner=this_session 表示此工作階段（或它所啟動的項目）啟動了該程序。在 Linux 上，這可透過繼承的 CLAUDE_CODE_SESSION_ID 證明，該變數在 nohup 後仍會保留。macOS 和 Windows 會隱藏其他程序的環境變數，因此在那裡這意味著「Claude 程序的後代」（CLAUDE_PID）；一個被分離並重新父化的程序則會顯示為 started_during_session，除非您能在本次對話中追蹤到它，否則屬於 ASK。owner=harness_do_not_kill 是 Claude Code 自己的 MCP 伺服器和外掛：絕不要碰這些。other_session_or_user 是其他人的。
• 檔案、分支、stash： this_session / pre_session 會將時間戳記與 session_start（本次工作階段轉錄中的第一個時間戳記）進行比較。時間戳記只是一個提示，而非證明：在工作階段時間窗內建立的項目可能來自並行的工作階段。只有當時間戳記顯示為此次工作階段且您能在本次對話中追蹤到它（您確實執行了建立它的命令）時，才將其視為此次工作階段的項目。否則屬於 ASK。

在 Claude Code 之外（例如在 Codex 中）沒有 CLAUDE_CODE_SESSION_ID 或 CLAUDE_PID，因此 session_id 為 unknown，所有項目都被標記為 pre_session，且程序僅透過 in_repo 進行比對。如果您知道工作階段的開始時間，請傳入 --since <ISO 時間>（Windows 上為 -Since），否則除非您能在本次對話中將檔案和程序追蹤到某個命令，否則都視為 ASK。

接著，盡可能在並行情況下補足腳本無法看到的缺口：

1. 您自己的背景工作。 列出您在此對話中啟動且仍在執行的背景 Bash 任務、Monitors、子代理和排程喚醒。使用啟動它們的工具停止已完成或閒置的任務（TaskStop、Monitor stop 等）。
2. 請求遺留物。 掃描對話，尋找任何擁有者要求稍後刪除或僅暫時保留的事項（如上傳資料夾、偵錯旗標、測試帳戶、暫存檔案）。檢查這些項目是否仍然存在。
3. 部署狀態（僅在 DEPLOY 顯示平台時執行）。取得最新正式部署的提交 SHA，並與 main_tip 進行比較。對於 Vercel：使用 vercel ls --prod 找出最新的正式部署，然後使用 vercel inspect <url>（或 Vercel MCP / 儀表板）取得其 Git 提交。如果您無法取得 SHA，請回報「deploy: unverified」並說明原因。切勿僅從時間戳記推斷相符。
4. 儲存庫外部的任何項目（另一個儲存庫的工作樹、全域安裝）。僅回報；不要修改。

第二階段：分類每個發現結果

AUTO-CLEAN（安全且可復原；直接執行，然後回報）：

• 完全合併到 main 的本地分支（使用 git branch -d，絕不使用 -D），排除 main、當前分支以及任何在工作樹中檢出的分支。
• 資料夾已消失的可清除 worktree 記錄（使用 git worktree prune）。
• 此儲存庫內已清理的鏈接工作樹，其分支已合併到 main 且沒有比它新的提交（使用 git worktree remove <path>，不加 --force；然後 git branch -d）。如果 lanes 工具擁有該工作樹，請改用工具腳本（見下文）。
• 其 lane 或分支已不存在且沒有任何程序開啟的暫存資料夾（open_handles=0；請在刪除前立即使用 lsof +D <dir> 重新檢查）。
• owner=this_session 且您可追蹤到本次對話、處於閒置或不再需要的程序（開發伺服器、監看程式、無頭瀏覽器）。僅透過 PID 終止程序（Linux/macOS 上使用 kill <pid>，Windows 上使用 Stop-Process -Id <pid>）。
• 過時的建置類型快取（.next/types、.next/dev/types），這些已被 gitignore 忽略。它們將在下一次建置中重新產生。
• 此次工作階段在其暫存區資料夾中的自有暫存檔案，以及儲存庫中未被追蹤的垃圾檔案（*.orig、*.rej、零散的日誌檔），這些需是 this_session 且可追蹤到您執行的命令。

ASK（可能遺失工作，或無法證明屬於此次工作階段）：

• 未合併的分支，或任何不在 main 中的提交。標記為 PATCHES_ALREADY_IN_main 的分支很可能是透過 squash 或 rebase 合併的：請說明情況，但仍需在 -D 前詢問。
• 骯髒的工作樹（dirty_files > 0）、stash、coverage/ 和 test-results/，這些可能被保留作為證據。
• other_session_or_user 或 started_during_session 的程序，以及任何您無法追蹤的程序。
• 任何 pre_session 的項目，以及任何您未建立的未追蹤檔案。

僅供報告（由擁有者決定，或僅供參考）：

• main 與 origin 之間的偏差（未推送或落後）。建議推送或拉取；不要將其作為清理的一部分來執行。
• 部署不符或「未驗證」的部署狀態。
• 沒有活躍工作的未結追蹤項目（beads in_progress、tasks.md WIP），以及任務仍處於開啟狀態的已完成工作。請說明項目名稱和您看到的內容。
• 此儲存庫外部的工作樹或資料夾，以及仍擁有唯一提交的 upstream_gone 分支。

安全規則

這些規則保護無法重新建立的工作。每一條之所以存在，是因為顯而易見的捷徑曾經毀掉過工作。

• 刪除前先檢查。 對於每個資料夾，先列出其內容和大小。對於每個分支，先顯示 git log --oneline main..<branch>。將這些證據放入報告中。
• 未經擁有者在本次對話中明確核准，絕不刪除未合併的提交、骯髒的工作樹或 stash。 對一個項目的核准不適用於下一個項目。
• 僅透過 PID 終止程序，在確認 owner=this_session 且是您啟動的之後才執行。絕不使用 pkill、killall、kill -9（首次嘗試時），或僅根據 port 來終止。
• 絕不使用裸 git stash、git reset --hard、git clean -fdx（或任何 git clean -f），或帶有萬用字元的 rm -rf。這些動作無法復原。一次刪除一個已命名的路徑。
• git branch -D、git stash drop 和 git worktree remove --force 僅在擁有者核准單一項目後執行，且需先展示將遺失的內容（提交、差異統計）。在報告中記錄分支 tip 的 SHA，以便日後還原。
• 絕不讀取、列印、移動或刪除 .env 檔案、金鑰或憑證，即使它們看起來像垃圾。僅透過路徑回報它們。
• 待在此儲存庫內。 其他應用程式的工作樹、獨立檢出或共用的 /tmp 資料夾僅供回報，不應碰觸。絕不在 /tmp 中使用萬用字元刪除。
• 絕不終止 harness_do_not_kill 程序或 Claude 程序本身。

當 Lanes 工具存在時

僅在 LANES 區段顯示狀態目錄時執行。否則跳過此區塊。

• 使用工具自己的腳本移除 Lane 工作樹、Lane 暫存目錄、relay 作業目錄和 lanes.tsv 列，絕不使用 rm：對於已合併的 lane，執行 bash ~/.claude/skills/lanes/lane/cleanup.sh <lane-dir> <branch>，然後執行 bash ~/.claude/skills/lanes/lane/cleanup.sh --sweep。從主要工作樹執行此操作。
• WORKTREE_MISSING 和 BRANCH_MERGED 列會經由 sweep 處理。未合併 lane 的列屬於 ASK。
• 仍在執行（沒有 rc 檔案）的 relay 作業屬於「僅供報告」；Lanes 監看程式擁有它們。
• 在 /lanes 工作階段中，主要 lane 負責整合；不要刪除其工作尚未合併到 origin/main 的 lane 分支。

沒有 Lanes 工具時，.claude/worktrees/ 下的工作樹（例如來自 Claude Code 的 EnterWorktree）遵循上述純 Git 規則。

第三階段：報告

請嚴格使用此結構。保持可快速掃讀；擁有者會在長時間工作階段結束時閱讀它。

## 工作階段清理

**已乾淨：** 工作樹、同步、工作樹、分支、stash、程序、成品、追蹤器、部署
（僅列出通過檢查的區域）

**已清理**
- `feat/login-form` 分支：已合併到 main，提交 a1b2c3d，0 個領先提交。已使用 `git branch -d` 刪除（還原：`git branch feat/login-form a1b2c3d`）。
- `python3 -m http.server 3000`（PID 170308）：由此次工作階段為預覽啟動，已閒置。已停止。
- `.next/types`（1.2M）：已被 gitignore 忽略，將在建置時重新產生。

**需您決定**
- `feat/wip` 分支：1 個提交不在 main 中（「wip: draft parser」），最後提交在 2 小時前，鏈接任務 bd-42 in_progress。
  恢復（保留它）或放棄（使用 `git branch -D feat/wip`）？
- `stash@{0}`「On main: sc test stash」，5 天前。套用或丟棄？

**僅供報告**
- main 領先 origin/main 2 個提交（未推送）。建議推送。
- 正式部署：未驗證（vercel CLI 未登入）。

**後續動作**
- 執行 `git worktree list`，預期只看到主要工作樹。
- 執行 `git status --short`，預期沒有任何輸出。

報告規則：

• 每一行「已清理」都說明它是什麼、其大小（針對檔案和資料夾）以及為何安全。對於分支，請包含 tip SHA 以便日後復原。
• 每個「需您決定」的項目都提供做出決定所需的事實（時間、提交數量、提交主題、鏈接任務）以及兩個具體選項。
• 除非稽核或本次對話中的某個命令顯示某個區域是乾淨的，否則絕不能說它是乾淨的。如果某項檢查被跳過（離線、CLI 缺失、無權限），請在「僅供報告」中說明原因。
• 後續動作始終包含至少一個驗證命令及其預期輸出。

在擁有者回答 ASK 項目後，準確執行他們核准的動作，重新執行相關的稽核區域，並報告結果。

日誌記錄

如果儲存庫有工作階段日誌資料夾（SESSION_LOG 顯示 _sessions/ 或類似名稱），請附加一個簡短的清理條目：日期、清理了什麼、等待擁有者決定什麼。僅在專案規則允許提交工作階段日誌時才提交它；請檢查 CLAUDE.md 或資料夾的忽略狀態（ignored=yes 表示不提交）。

範圍外

重構、Lint 修復、移除死碼和相依性升級。如果您注意到它們，請將其記錄為待辦事項（記憶體或追蹤器）並用一行提及。推、拉和部署也不在範圍內：建議它們，但不要執行。