eric861129 整併過度堆疊文件
整理目標
- 真正降低文件數量與維護成本，不要只是把舊文件搬進新的封存目錄。
- 讓每個保留文件都有明確用途、讀者、維護生命週期與唯一真實來源責任。
- 保留仍正確且具有獨特價值的內容，移除重複、失效、矛盾與沒有維護價值的內容。
- 先完成唯讀盤點與整併提案，再等待使用者核准精確操作清單。
- 預設在 commentary 或 plan 回報盤點，不要為了整理文件而再建立盤點報告、遷移紀錄或新索引文件。
先確認範圍與安全條件
- 檢查適用的專案指示、版本控制狀態、文件來源與產生流程，保留使用者的無關變更。
- 確認盤點範圍與文件類型；將第三方、建置輸出、快取與自動產生文件分開處理。
- 確認哪些文件受法規、稽核、合約、版本發佈或外部連結約束，不要將它們視為一般重複文件。
- 記錄整理前的文件數量與主要入口，但不要把這份清單寫成新的專案文件。
- 在刪除前確認版本控制或其他可恢復來源；未納入版本控制且無備份的文件必須個別取得確認。
除非使用者另有要求，只整理文件與其導覽、metadata 或連結。可以唯讀檢查程式碼、設定、測試與執行結果以判斷文件真實性，但不要順便修改產品功能、資料或架構。
建立文件清冊
先列出檔名、路徑、標題與連結關係，再只讀取需要比較的內容；不要一開始把所有文件全文載入 context。
若 Skill 目錄內有 scripts/inventory_documents.py，優先從專案根目錄執行唯讀盤點：
python <skill-directory>/scripts/inventory_documents.py <project-root> --format json
先執行 --help 確認參數。腳本只輸出 stdout，不應建立或修改專案文件；它提供路徑、標題、雜湊、Git 狀態、連結、編碼與生成線索。完全相同雜湊、檔名提示或失效連結都只是調查線索，不能取代語意比較、權威來源判斷、保存義務確認或刪除核准。若環境無法執行腳本，改以其他唯讀方式完成相同盤點，不要因此降低安全閘門。
對每份文件判斷：
- 路徑、用途、主要讀者與維護生命週期。
- 它是手寫來源、自動產生結果、外部複本，還是暫時工作產物。
- 是否被主要入口、其他文件、程式、CI、發佈流程或外部系統引用。
- 是否包含其他文件沒有的正確內容。
- 與哪些文件重複、矛盾或形成舊版／新版堆疊。
- 建議保留、整併、移除、依法保留、重新產生或等待決定。
判斷權威來源時，優先依據目前程式碼、設定、資料模型、產生流程、測試與運行證據，再考慮維護中的正式文件與 Git 歷史。不要因檔名含有 final、v2、日期較新或內容較長，就自動判定它最正確。
分類與整併規則
將每份文件歸入一個主要處置：
- 保留：已是清楚、正確且仍被維護的權威來源。
- 整併：把獨特且仍正確的內容移入指定權威文件，再移除重複來源。
- 修正後保留：責任正確，但內容、導覽或引用需要更新。
- 移除：完全重複、已失效、只有過程紀錄，或沒有明確讀者與維護責任。
- 依法或依約保留：因稽核、法規、版本或外部承諾不能刪除，並明確標示其非現行來源。
- 重新產生：屬於生成結果，應修正來源或流程後重新產生，不要手動整併生成檔。
- 等待決定：存在無法由證據解決的矛盾、外部引用或所有權問題。
遵守以下限制：
- 預設把內容收斂回現有權威文件，不要用建立新文件解決文件過多。
- 只有在沒有任何既有文件能合理承擔權威來源時，才提出一份新的 canonical document，並說明不可併入的原因。
- 不要以「全部移到 archive」代替判斷；只有確有保存義務時才封存。
- 不要在整理過程順便把大型文件拆成更多小檔，除非使用者明確要求且拆分確實改善責任邊界。
- 不要用字數、修改日期或檔名相似度單獨決定刪除；必須確認內容、引用與權威來源。
核准閘門
每次回報文件整理決策，都依下列順序輸出七個必要欄位。在任何刪除、搬移、改名或大範圍重寫前，先在目前對話提出完整整理提案；不要另存為專案報告。若尚未取得某欄位的證據，該欄明確填寫「待唯讀盤點」，不要省略欄位或用推測補值。
盤點範圍（必要）：涵蓋與排除的目錄、文件類型及生成來源
整理前後數量（必要）：目前文件數／核准後預期文件數
權威來源（必要）：每份保留文件與其唯一責任
逐路徑處置（必要）：明確路徑／保留、整併、修正、移除、依法保留、重新產生或等待決定／理由／獨特內容去向
引用修復（必要）：需更新的內部連結、導覽、metadata、CI、產生流程與已知外部引用
待決定風險（必要）：無法由現有證據解決的矛盾、保存義務、所有權或未備份內容
核准狀態（必要）：尚未核准；等待使用者確認上述精確清單
完成清單後停止，等待使用者確認。未取得精確核准前，只能進行唯讀盤點；不得先整理一部分、移動檔案、刪除文件或改寫權威來源。
核准後執行
- 先更新權威文件，納入所有已確認仍正確的獨特內容，並在同一文件內消除重複與矛盾。
- 驗證權威文件內容完整後，更新所有內部連結、導覽、metadata、CI 與產生流程引用。
- 只執行核准清單內的搬移、改名與刪除；使用明確檔案路徑，不使用寬泛路徑、萬用字元或遞迴刪除命令。
- 若專案或環境要求逐檔刪除，逐一處理；需要批次刪除時，必須已有使用者對完整清單的明確授權。
- 不要另外建立清理報告、舊檔索引、對照表或封存副本。已納入版本控制的歷史由 Git 或專案既有歷史機制保存。
- 若執行中發現未列入清單的新風險或新文件，停止該項操作並重新取得確認，不要擴大授權範圍。
驗證與收尾
- 比較整理前後的文件數量，並說明減少數量；數量下降不是犧牲必要內容的理由。
- 確認每項獨特且仍正確的內容都有明確去向。
- 搜尋已移除或改名的路徑，確認內部連結、導覽、metadata、程式與 CI 沒有殘留引用。
- 執行專案既有的文件 validator、連結檢查、文件建置或必要 smoke test。
- 檢查編碼、格式與版本控制 diff，確保沒有亂碼、無關變更或生成來源與產物不同步。
- 最終只回報保留、整併、移除、待決定的結果與驗證證據，不要再建立下一階段文件整理計畫。
當剩餘文件各自具有清楚責任、唯一真實來源不再重複、必要引用有效，且所有核准操作與驗證完成時，立即停止整理。若仍有未核准或無法安全判定的項目，明確列出並停止，不要用猜測完成清理。