git-smart-commit

Git Smart Commit — 智慧拆分提交

將目前所有 staged / unstaged 變更，依功能邏輯分群後，逐批 git add + git commit。

When NOT to Use

• 只有單一檔案、單一目的且預期只需要 1 個 commit。
• 目前在 merge/rebase 衝突中，尚未完成衝突解決。
• 使用者要求「只生成一筆 commit」或「僅提供訊息模板」。

Public options and execution guard

--scope <path> limits collection; --type <type> forces the reviewed conventional type; --ai-co-author opts into the approved trailer. Before proposing or running commits, read rules/execution-policy.md, preserve its manual/automatic boundary, require code precommit success, and treat plans as unexecuted.

流程 — SSOT: rules/execution-policy.md owns commit/review safety; this skill owns grouping evidence

1. 收集摘要並閱讀相關變更

從 consumer 專案根目錄或子目錄執行唯讀收集器：

node "$SKILL_DIR/scripts/collect-changes.js" [--scope <path>]

$SKILL_DIR 是已安裝技能目錄。收集器原始碼見 scripts/collect-changes.js。--scope 是 repo-relative literal path；它限制檔案清單，但仍會回報範圍外的 staged 內容。收集器只讀取 Git 狀態與統計，不輸出 diff 或檔案內容，也不執行 hooks。

摘要提供 repoRoot、起始 head、files、safety 與 hooks；hook 資訊不代表已執行或通過。解讀欄位或處理收集失敗時，閱讀 collector contract。

若收集器不存在、退出非零、JSON 無效或輸出不完整，回報摘要未完成並停止提交流程，不推斷「沒有變更」或「沒有 hook」。若 files 沒有範圍內變更，先檢查 safety，尤其範圍外 staged；確認沒有待處理安全狀態後，再回報目前範圍無需提交。

摘要只用來選出待檢查的功能群。將 shell 工作目錄切換到輸出中的 repoRoot，再逐路徑閱讀該群的 staged 與 unstaged diff；新增的未追蹤檔案要閱讀檔案內容。使用 literal pathspec，rename 要同時檢查新舊路徑：

git --literal-pathspecs diff -- <path>
git --literal-pathspecs diff --cached -- <path>

逐組檢查並控制輸出量，不先讀取整個 worktree 的完整 diff。收集器會拒絕前後觀察到的 HEAD、status 或行數統計變動，但摘要不是原子快照，也不能證明內容未變。若來源在檢查期間改變，重新收集摘要、檢查受影響內容並重擬計畫；提交前仍須核對實際 staged diff。

2. 分析並分群

依變更意圖、功能關聯和依賴關係分組。目錄可協助定位，不能單獨決定 commit 邊界；同一功能跨 Controller、Service、Model、View、測試或文件時，應一起評估。

分群規則

• 同一功能的 Domain 與 Infrastructure 實作，以及對應測試，通常放在同一組。
• MVC 功能可將相關的 Controller、Model、View 和測試放在同一組。
• Migration 僅在能獨立理解和驗證時拆成單獨 commit；必要的程式相依不得拆散。
• 少量變更依實際關聯併入最相關的功能群，不以檔案數量或路徑強行合併。
• 新增功能使用 feat；修正或重構使用 fix / refactor / style；刪除或環境設定使用 chore；文件更新使用 docs。