| name | code-cleanup-helper |
| description | 以跨平台、read-only 審計器掃描 codebase、prompt、SKILL.md 與 repository，建立 Python 依賴圖並找循環依賴、分層違規、責任熱點、重複函式、過長函式／檔案、命名漂移、私公版 sync、本地 release readiness、broken links、skill metadata 與隱私外洩。使用者要求「清理 code 前先盤點」「分析架構」「依賴圖」「找重複」「重構前審計」「skill 太長」「audit repo」「私公版 diff」「版本對齊」「release 前盤點」「規則漂移」等診斷時使用；也在 run-benchmark-driven-rd 需要可重現的 repository baseline 或 promotion evidence 時作為 read-only evaluator 使用。 |
Code Cleanup Helper
以可重複執行的 Python 審計取代臨時 Bash 指令。支援 Windows、macOS、Linux；所有檔案以 UTF-8 讀取。
硬規則
- Audit 引擎永遠 read-only。
- 單獨診斷時先報告，再等使用者明確授權修復範圍。
- 被 R&D 或其他 orchestrator 於使用者已明確要求修改的工作中調用時，只回傳證據，不新增第二次確認；後續修改權限與範圍仍由 orchestrator 和原始請求決定。
- 未能執行的維度標
NOT_CHECKED，不包裝成通過。
- 不改
.git/、測試／CI、license、package metadata，除非使用者明確把它們放進修復範圍。
- 不 commit、push、force reset、publish release。
路由
| 使用者意圖 | Mode | 讀取 |
|---|
| 重複、命名、架構、依賴、模組、函式／檔案太長 | A | references/mode-a.md |
| sync、release、link、drift、handoff | B | references/mode-b.md |
| 完整健檢 | A+B | 兩份都讀 |
| 要設定例外／機器報告 | 任一 | references/config-and-report.md |
| R&D baseline／promotion gate | 依任務 | references/rd-integration.md |
標準流程
- 解析目標絕對路徑；確認存在，不猜 repo。
- 執行審計器。Windows 先設
PYTHONUTF8=1。
- 讀 JSON 證據或人類摘要；需要 semantic 判斷時再讀相關檔案。
- 回報 FAIL、REVIEW、NOT_CHECKED、影響與最小修復順序。
REVIEW 是提醒人工判斷，不是阻擋。
- 單獨診斷請求要停下等待修復授權；若原始請求已明確授權 R&D／實作變更，將報告交回 orchestrator，不要求重複確認。
- 修完重跑相同 audit；不能只靠肉眼說完成。
$env:PYTHONUTF8='1'
python scripts/audit.py <target> --mode all
python scripts/audit.py <target> --mode all --format json
python scripts/audit.py <target> --mode architecture --format json
只有 CI 或使用者要求 fail-fast 時加 --strict。預設 exit 0 只代表 audit 成功跑完。
專用檢查器
python scripts/check_links.py <target>
python scripts/check_drift.py <target>
python scripts/check_sync.py <target>
python scripts/self_test.py
報告格式
用短表格輸出：
只列最高優先的 3–10 筆；完整清單留在 JSON。結尾必須是單一 next action，例如「回『修 P0』後我才修改」。
判讀邊界
- Exact duplicate、Python import cycle、設定式 layer violation、broken link、ID range、sync diff 可由 script 判定。
- 超過 severe 門檻才是
FAIL；warning 至 severe 之間是 REVIEW。不要為了消除提醒而機械式拆函式。
- 例外必須含 path、function name、max lines、理由、到期日；例外仍顯示為
REVIEW，不會隱藏技術債。
- Semantic duplicate、架構是否值得抽象、公開文件是否講清楚，必須由 agent 讀上下文判斷。
- 動態 import、執行期 service lookup、跨語言呼叫與資料流責任不在 Python AST 圖內；未另查不得宣稱完整架構通過。
- PASS 數量不等於架構最優。若理應存在的依賴邊沒有出現在圖上，先把它當量測失敗；用
required_dependencies 加正／負 fixture，修解析器後才繼續產品重構。
- 平台／API／法律等時效事實不靠本地 regex 宣稱正確；需要時另查權威來源。
- Cleanup 的 release 檢查只證明本地 repo metadata；外部發布目標、登入、scope、sudo／2FA 與發布後 API 驗證由 R&D external-change gate 負責。
維護
- 新的 deterministic 檢查先加到
scripts/audit_core.py，再補 self_test.py；量測本身沒有對應 fixture 時不得拿來阻擋重構。
- 子目錄可直接執行的 Python script 常用 bare sibling import；解析時先保留真正 top-level absolute import，再 fallback 到同目錄 module。兩種情境都必須有 fixture，避免修一邊壞另一邊。
- Cleanup 也必須檢查「檢查器的計分與輸出合約」：新增／移除 gate 後，分數分母必須由實際 max points 計算；宣稱 JSON 的 CLI 只能輸出一份可解析文件。任何會製造假滿分、吞掉失敗或污染 JSON 的問題都先修量尺、補回歸測試，再繼續產品開發。
- 專案特有事實放目標 repo 的
audit.config.json，不要 hardcode 到通用引擎。
agents/openai.yaml 改動後重新跑 skill-creator 的 quick_validate.py。
