用途：将当前功能分支相对于默认分支的净变更压缩为一个提交，得到适合干净 PR 的历史记录。
主要能力：通过辅助脚本先执行只读的 plan，校验 Git 工作树、已附加分支、工作区/索引是否干净、解析基准分支（origin/HEAD，其次 main、master、trunk）、确认当前分支非默认分支、合并基点、领先提交数为正以及远端状态。plan 返回 schemaVersion: 1、原始 HEAD、合并基点、基准引用、按时间顺序的提交、唯一作者、树与远端状态及回滚信息；前置条件不满足则直接退出且不改写历史。apply 阶段绑定计划的原始 HEAD、分支、合并基点、基准引用、干净状态与回滚索引，变更前重新校验，过期计划会失败；随后软重置到合并基点，确认暂存的净差异非空，再用消息文件提交。中途失败会恢复原 HEAD 与精确索引，不动工作树文件。
用法：从 SKILL.md 解析辅助脚本，将 plan 的 JSON 写到仓库外的临时路径： uv run "<skill-dir>/scripts/git-squash.py" plan --cwd <repo> --base <branch> --subject <line> > <plan.json> 再执行 apply： uv run "<skill-dir>/scripts/git-squash.py" apply --plan <plan.json> --message-file <message.txt> 可通过 --subject 指定替换提交消息的首行，通过 --base 覆盖默认分支检测。未提供 subject 时，依据净差异并参照仓库提交格式（<git-root>/.agents/commit.toml 中 [message] 的 natural 或 conventional；缺失则按 conventional）撰写主题；除当前 Git 用户外的每位计划作者追加一条 Co-authored-by 尾注。
适用场景：把大型功能分支整理为单提交以提交干净 PR。
限制：需在干净的 Git 工作树中使用；基准分支需可解析；分支不能是默认分支且需领先基准；失败后应依据诊断与当前 Git 状态处理，不要手动重放重置/回滚序列；推送需显式请求，且仅使用 git push --force-with-lease。