Git Repository Organizer
將每個結論建立在最新的 Git 快照之上。將參照、已簽出的目錄、未提交的檔案以及託管的遠端視為獨立的狀態層。
選擇操作模式
根據請求推斷授權的最嚴格模式：
- 分析：檢查並報告，但不修改參照、索引或工作樹內容。當需要當前遠端真實狀態時，使用
git ls-remote；不要僅為了分析而 fetch、merge、pull、commit、rebase、delete、push、建立追蹤分支或切換工作樹。 - 重新整理：擷取遠端追蹤參照，然後報告。不要僅因為擷取了參照就合併分支。
- 提交：僅在指定的工作樹中整理並提交變更。
- 整合：僅透過一個乾淨的整合工作樹來 merge、rebase 或 cherry-pick 指定的分支。
- 清理：僅移除根據決策矩陣證明為安全的分支或工作樹。
- 同步：在重新整理並重新檢查後，僅對指定的參照進行 push 或 fast-forward。
如果「整理」或「同步」未明確授權變異，請先盤點並提出確切的提議操作。在刪除遠端參照、強制推送、改寫共享歷史、捨棄變更或強制移除工作樹之前，需要明確的使用者確認。
建立當前快照
- 定位真正的儲存庫和共同的 Git 目錄。永遠不要假設提示的工作目錄就是儲存庫根目錄。
- 在操作前，先閱讀專案說明文件，例如
AGENTS.md。 - 在分析模式下，驗證即時遠端分支頂點，但不更新遠端追蹤參照：
git ls-remote --symref --heads REMOTE
明確說明本機的遠端追蹤參照仍保持快取且未變動。在重新整理模式下，或在明確請求的遠端變異之前，立即執行：
git fetch --all --prune --no-tags
預設使用 --no-tags。擷取分支和擷取標籤是分開的操作；永遠不要自動覆蓋衝突的本機標籤。
擷取僅更新遠端追蹤參照。在重新整理模式下，就此打住，並將每個本機分支與其遠端對應分支進行比較，但不要整合任一方：
- 永遠不要僅為了讓稽核看起來最新而進行 merge 或 pull。本機分支可能合理地處於 ahead、behind 或 diverged 狀態；報告該狀態。
- 永遠不要僅為了分析而對骯髒的工作樹進行 commit、stash、snapshot、switch、reset 或其他操作。記錄骯髒狀態並將其視為變異阻塞器。
- 遠端已被刪除 (
upstream gone) 或從未被推送的本機分支，僅為本機分支；在報告中明確指出。 - 僅當使用者明確要求變異時，才進入同步或整合模式。在執行前立即重新執行稽核，在擁有該分支的工作樹中操作，並套用決策矩陣。
- 執行內建的唯讀稽核：
python3 scripts/audit_git_state.py --repo /absolute/path --format markdown
python3 scripts/audit_git_state.py --repo /absolute/path --base main --format json
腳本路徑相對於此技能目錄，而非目標儲存庫。
- 檢查每個可能被保留、整合或刪除的分支的獨有提交和變更檔案：
git log --left-right --cherry-pick --oneline BASE...BRANCH
git diff --stat BASE...BRANCH
git diff --name-status BASE...BRANCH
在描述分支功能之前，請先閱讀具代表性的 diff。不要從分支名稱推斷功能。
- 在清理前，分類每個分離的工作樹：
git merge-base --is-ancestor HEAD BASE && echo "HEAD already in BASE"
同時檢查本機基底和遠端基底（例如 main 和 github/main）。一個乾淨的分離 HEAD，且是遠端基底的祖先，表示已合併 — 它不需要重新整合，也不需要復原分支；它很可能是驗證腳本留下的產物，可以在確認後安全移除。一個不是祖先的分離 HEAD 可能持有獨有的提交；在移除前，即使工作樹看起來很乾淨，也要在 HEAD 處建立一個復原分支。在強制移除前，檢查未追蹤檔案，並將產生的工件（測試輸出、建置目錄）與手寫工作分開。
-
保持輸出與決策成比例。將 JSON 稽核結果和大量的參照/工作樹/diff 清單寫入暫存檔案，僅讀取摘要。僅針對整合或刪除候選者的分支進行深度 diff；不要在大型儲存庫中將每個分支的日誌和完整 diff 都塞入上下文。
-
在最終報告前以及每次變異前，立即重新執行稽核。儲存庫可能在分析期間發生變化；在結果中包含快照時間和頂點 hash。同時留意並發活動：自上一張快照以來，由其他行程建立或刪除的參照、工作樹或遠端分支（例如一個合併候選分支）會改變計劃；應重新呈現計劃，而不是對過時的目標採取行動。
保持狀態模型精確
- 儲存庫的正常簽出是主要工作樹。它會出現在
git worktree list中，但不是一個外部連結的工作樹。 - 在另一個路徑下簽出的分支是外部連結工作樹。
- 分離的工作樹有一個簽出的提交，但沒有分支。將骯髒的分離工作樹視為可復原的工作，而不是垃圾。始終檢查其 HEAD 是否為基底（本機和遠端）的祖先：如果是且工作樹是乾淨的，則它已合併，不需要重新整合；如果不是，則其提交在移除後可能會變得無法到達，需要先建立一個復原分支。
- 分支參照和工作樹是不同的物件。移除一個乾淨的連結工作樹不會刪除其分支；刪除一個分支不會安全地處理骯髒的工作樹。
- 遠端 HEAD 是一個符號性的預設分支指標，而不是另一個遠端分支。
- 遠端追蹤參照是對遠端狀態的本機觀察。擷取它不等於 pulling 或 merging。
- 除非使用者要求建立本機追蹤分支，否則不要為每個遠端分支建立本機分支。
向使用者解釋狀態時，請明確這些事實：
- 一個分支參照同一時間最多只能被一個工作樹簽出（0 或 1）；Git 會拒絕同一個分支的第二次簽出。
- 移除一個工作樹只會刪除其目錄和註冊資訊。分支參照和提交會保留在共享儲存庫中；該分支只是變成了未簽出的狀態，之後可以再次簽出。
- 移除一個工作樹只會遺失未提交的工作（已暫存、未暫存、未追蹤或衝突的檔案）。「乾淨」表示遺失風險為零，並不表示該分支已合併。
- 分離的工作樹不佔用任何分支。其 HEAD 直接指向一個提交，因此永遠不會導致另一個工作樹獲得或遺失分支。
- 分支並非「在」主要工作樹「內部」；未簽出的分支以參照形式存在，可以隨時切換過去。
定義明確可刪除的分支
只有當分支的內容已完全合併到預期的基底分支（通常是 main）時，該分支才是明確可刪除的：
- 透過祖先關係：分支頂點是基底的祖先 (
git merge-base --is-ancestor BRANCH BASE)，因此它沒有分支獨有的提交。 - 透過修補程式等效性：每個分支獨有的提交在基底中都有一個修補程式 ID 等效的提交 (
git cherry BASE BRANCH顯示沒有+條目)，並使用git patch-id驗證，絕不透過提交主旨。
任何包含獨有提交或獨有修補程式的分支都不是明確可刪除的，即使其工作看起來冗餘、其名稱類似於已合併的分支，或其頂點由標籤保留。被標籤歸檔的分支只有在明確確認後才可能被刪除，而不受此規則約束。
一個分支也可能是被取代的：它實現的功能已由基底中進化或替代的實作提供。逐提交、逐檔案驗證基底是否涵蓋了相同的意圖和檔案，並且分支中剩餘的行是過時的殘留物而非缺少的功能。被取代的分支不受此規則約束而成為明確可刪除的；使用標籤歸檔確切的頂點，提供比較證據，並僅在使用者明確確認後才刪除。
對於遠端分支，合併內容的證據必須針對遠端基底成立；僅合併到未推送的本機基底中的內容不符合資格。在刪除之前，務必套用 references/decision-matrix.md 中的刪除閘門。
使用固定的分支矩陣進行報告
對於每個標準分支名稱，報告：
| 欄位 | 必要意義 |
|---|---|
| Local | refs/heads 是否包含該分支 |
| Remote | 每個同名的遠端參照，而不僅僅是上游 |
| Sync | 相對於其設定的 upstream 的 Ahead/Behind 或 diverged |
| Base relation | 基底獨有和分支獨有的提交、祖先關係和修補程式等效證據 |
| Checkout | 未簽出、主要工作樹、外部連結工作樹或分離 |
| Worktree state | 已暫存、未暫存、未追蹤和衝突 |
| Function | 由提交和 diff 證明的功能或修復 |
| Recommendation | Keep, commit, integrate, archive, delete, 或 investigate; 僅對內容已完全合併到基底中的明確可刪除分支使用 "delete" |
分別列出分離的和可修剪的工作樹，每個都附有其 HEAD hash、該 HEAD 是否為本機和遠端基底的祖先、乾淨/骯髒狀態、未追蹤的工件以及建議（安全移除 / 先復原分支 / 保留）。以分為「現在安全」、「需要確認」和「被未提交或獨有工作阻塞」的排序動作結束。當使用者想要只查看本機的視圖，或請求涉及清理/刪除決策時，請始終在報告中包含下方彩色的本機儲存庫圖；不要等待明確的 "畫圖" 請求。
畫出本機的程式庫圖
在明確請求（如 "畫出本機的程式庫圖", "本地 Git 狀態的圖", "只展示本地分支", 或 "本地優先視圖"）時觸發，並在每個以清理為導向的報告中自動包含。產生一個本機優先的分支圖：
- 在繪製前立即重新執行稽核；在圖上標記快照時間和頂點 hash。
- 範圍僅限於本機分支 (
refs/heads/*)。不要渲染僅存於遠端的分支。 - 標記每個同時有同名遠端分支的分支為 也有遠端分支；否則標記為 無遠端分支，並區分從未推送和推送後被刪除 (
upstream gone)。 - 按性質分組分支：長期/主要（保留）、臨時（確認後歸檔/刪除）和有實際工作（保留並決定整合）。
- 將工作樹狀態附加到每個分支：未簽出、主要工作樹或連結工作樹（及其路徑），以及乾淨/骯髒狀態。
- 附加清理證據：獨有提交/修補程式、上游狀態（包括 ahead/behind）、骯髒檔案和 stash。
- 如果在工作階段期間另一個行程建立了一個合併候選或驗證參照，將這些分支放在它們自己的待處理組中；報告它們，但在外部行程解決之前不要修改它們。
- 在 Worktree 子圖中繪製每個分離的工作樹，即使它沒有分支：將其標記為
detached <path> → HEAD <hash>，附上乾淨/骯髒狀態以及祖先判定（✔ HEAD 已在 base 中，已合入或✘ 未合入，需恢復分支）。它沒有分支邊。 - 渲染一個 Mermaid 流程圖，每個組有一個子圖，再加上一個單獨的工作樹子圖；將每個已簽出的分支連接到其工作樹。
模板：
flowchart TB
subgraph LOCAL["本機分支 refs/heads/*"]
subgraph KEEP["長期/主要 —— 保留"]
A["main（ahead 25 · behind 4）<br/>✔ 也有遠端分支<br/>primary worktree · 乾淨"]
B["dev<br/>✔ 也有遠端分支 · 未簽出<br/>祖先，已完全合入 main"]
end
subgraph TEMP["臨時性 —— 確認後歸檔/刪除"]
C["branch-c（N 個獨有提交）<br/>✘ 無遠端分支（upstream gone）<br/>linked worktree · 髒"]
end
subgraph WORK["有實際工作 —— 保留並決定是否合入"]
D["branch-d（N 個獨有提交）<br/>✘ 無遠端分支（從未推送）<br/>linked worktree · 乾淨"]
end
subgraph PENDING["在途/外部驗證 —— 不動"]
E["merge-candidate-x（外部建立）<br/>✔ 也有遠端分支 · linked worktree · 乾淨"]
end
end
subgraph WT["Worktree"]
W1["primary /path/to/repo → main · 乾淨"]
W2["linked /path/to/wt1 → branch-d · 乾淨"]
W3["linked /path/to/wt2 → branch-c · 髒"]
W4["linked /path/to/wt3 → merge-candidate-x · 乾淨"]
W5["detached /path/to/wt4 → HEAD abc1234 · 乾淨<br/>✔ HEAD 已在 base 中（已合入）"]
W6["detached /path/to/wt5 → HEAD def5678 · 髒<br/>✘ 未合入（需恢復分支）"]
end
A --> W1
B -- "祖先" --> A
D --> W2
C --> W3
E --> W4
style LOCAL fill:#e3f2fd,stroke:#1e88e5
style KEEP fill:#e8f5e9,stroke:#4c8c4c
style TEMP fill:#fff8e1,stroke:#f9a825
style WORK fill:#e8eaf6,stroke:#3949ab
style PENDING fill:#fff3e0,stroke:#fb8c00
style WT fill:#f3e5f5,stroke:#8e24aa
style A fill:#fce4ec,stroke:#d81b60
整理本機提交
僅在擁有變更的工作樹內操作。
- 檢查已暫存、未暫存、未追蹤、忽略、已產生、大型和類似機密的檔案。
- 將產生的輸出、快取、螢幕截圖、本機日誌和憑證與產品變更分開。對於鎖定檔案，將純格式的重新序列化（例如 pnpm 版本的引號樣式變更）與真實的依賴項變更分開；在還原或提交前，使用依賴項 diff 進行驗證。
- 按行為分組提交，而不只是按目錄。當一個檔案包含多個關注點時，使用修補程式暫存：
git add -p
git diff --cached --check
git diff --cached --stat
git diff --cached
- 在每個邏輯提交之前執行有針對性的驗證，在整合之前執行更廣泛的驗證。
- 使用 Conventional Commits 訊息。切勿在混合或不熟悉的工作樹上盲目使用
git add -A。 - 每次提交後重新檢查狀態，並確切說明還有哪些未提交。
安全地整合分支
在進行 merge、rebase、cherry-pick、刪除、工作樹移除或類似強制操作之前，請閱讀 references/decision-matrix.md。
在整合之前和之後，始終與基底進行比較。保持整合工作樹潔淨；將變數儲存在基底之外。如果合併引入了回歸，使用 git revert 而非 git reset，以保留歷史。
套用決策矩陣
管理狀態和工作流程的完整規則集位於 references/decision-matrix.md。在執行任何變異操作之前，請查閱該文件。
決定性：原子、可重現、自我修正
成功意味著儲存庫達到了請求的狀態。在每一步之後報告差異。如果一個步驟失敗（例如合併衝突），則在該點停止、報告、等待使用者輸入，然後在解決後重新驗證整個計劃。失敗的操作不會留下中間狀態。