zmice 分支收尾与清理
概述
任务“做完”不等于 branch 可以安全结束。只有当变更已经验证、去向已确定、残留工作区已清理，branch / worktree 才算真正收尾。
这个技能只处理收尾判定与清理：
- 这个 branch 现在应该 merge、开 PR、继续保留，还是直接丢弃
- 关联 worktree 是否还需要保留
- 失败实验、半成品和临时分支如何安全退出
它不替代实现、审查或发布流程；它只负责把这些流程的结果变成一个干净、可追踪、可回滚的结束状态。
何时使用
在以下时点进入本技能：
- 一个功能或修复已经完成实现，准备结束开发分支
- 一个 worktree 中的实验已经得出结论，需要保留或放弃
- 多 agent 并行执行结束，准备 fan-in 之后清理各自分支
- PR 已合并、被拒绝，或决定不继续推进，需要处置残留 branch / worktree
收尾决策树
任务结果明确了吗？ ─── 否 ──→ 不收尾，先补齐验证或结论
│
是
▼
变更应该进入主线吗？ ─── 否 ──→ 丢弃或归档实验分支
│
是
▼
当前团队通过 PR 合入吗？ ─── 是 ──→ 推送 + 开/更新 PR + 等待合入
│
否
▼
直接 merge 到目标分支 → 验证目标分支状态 → 删除已完成分支
关键点：
- 先判定“是否保留”，再判定“如何合入”
- 未经验证的 branch 不能因为“差不多完成了”就进入收尾
- 未合入主线的实验分支，只有明确保留价值时才继续存在
收尾前门禁
收尾前必须确认：
- 任务范围已经冻结，没有继续顺手改的内容
- 当前 branch 的测试、lint、构建或本任务要求的验证已完成
- 审查结论已明确：可合入、待修复或放弃
- branch 的目标去向已明确：merge、PR、保留、归档或删除
- 没有未解释的脏文件、临时脚本或生成物
如果上述任一项不明确，就不要进入 cleanup 动作。
四种结束状态
1. 合入主线
适用于：功能完成、验证通过、审查通过，且应该进入目标分支。
动作：
- 确认 branch 相对目标分支的差异是预期范围
- 使用团队约定的方式 merge 或 rebase 后合入
- 在目标分支重新运行必要验证
- 删除已完成 branch
- 若 branch 绑定 worktree，清理对应 worktree
2. 提交 PR 等待合入
适用于：变更已准备好，但团队要求经由 PR 流程进入主线。
动作：
- 推送 branch 并创建或更新 PR
- 在 PR 描述中写明范围、验证证据和风险点
- branch 保持最小存活时间，只为等待审查和合入而存在
- PR 合并后删除 branch，并清理关联 worktree
3. 暂时保留
适用于：实验有价值，但当前不合入；或后续还会基于该分支继续工作。
动作：
- 记录为什么保留、保留多久、谁负责
- 标明当前状态是
paused、blocked或needs-follow-up - 清理无关临时文件，避免下次恢复时状态不明
- 定期复核，过期未恢复的分支要么合入，要么删除
保留不是默认值。没有明确后续计划的 branch，不应长期悬挂。
4. 丢弃或清理失败实验
适用于：方案被否定、实现失败、或成本明显高于价值。
动作：
- 先保留需要沉淀的结论、数据或复盘记录
- 确认 branch 上没有还要转移的变更
- 删除分支或直接移除 worktree
- 清除临时文件、缓存和不再需要的脚本
不要把“也许以后有用”的实验分支长期留着替代文档。
Worktree 收尾协议
如果 branch 通过 worktree 运行，收尾时把 branch 和 worktree 视为一个整体：
- branch 已合入或放弃后，worktree 也应同步清理
- 仅当该 worktree 仍承担后续明确任务时才保留
- 清理前先确认没有未提交变更或未转移的调试资料
- 移除 worktree 后，确保主仓库或其他工作区不再引用该路径
worktree 是隔离手段，不是长期存档机制。
多分支 / 多 Agent 场景
并行执行结束后，不要只做“合并成功”检查，还要逐个确认各分支的收尾状态：
- 哪些分支已经合入，可以删除
- 哪些分支因失败或冲突需要重做，应清理现场后重新开始
- 哪些分支暂时保留，原因和负责人是什么
- 哪些 worktree 已经没有活跃任务，应立即移除
如果一个并行批次完成后还残留大量无主分支，说明收尾协议没有真正执行。
使用 zc team 时，先运行 dry-run：
zc team shutdown <team-name> --plan
它只读取 fan-in 状态，不关闭 tmux、不删除 worktree。重点看每个 worker worktree：
clean：没有未提交变更，可以继续判断是否合入或删除dirty：仍有未提交变更，必须先转移、提交或明确丢弃ahead：分支领先目标引用，需要判断是否合入或开 PRmerged：已合入的分支可以进入删除流程unknown：状态无法判断，必须人工检查后再清理
只有每个 worktree 的去向明确后，才运行不带 --plan 的 zc team shutdown <team-name>。
最小收尾清单
- branch 的最终去向已明确
- 必要验证已完成，证据可追溯
- 需要保留的信息已转移到 PR、任务系统或文档
-
zc team shutdown <team-name> --plan没有暴露未解释的dirty/unknown - 不再需要的 branch 已删除
- 不再需要的 worktree 已移除
- 没有遗留未解释的脏文件或临时产物
与其他技能的衔接
- git-workflow-and-versioning — 定义提交、分支和 worktree 的日常纪律；本技能负责这些对象的结束状态
- parallel-agent-dispatch — 并行批次 fan-in 后，逐个分支进入收尾判定
- team-orchestration — 团队停机前，先明确每个 worker 的 branch / worktree 去向
- verification-before-completion — 收尾前的验证证据必须真实存在，不能凭感觉删除或合入分支
Red Flags
- 任务未验证完成就急着删分支
- PR 已合并但 branch / worktree 长期残留
- 失败实验既不记录结论，也不清理现场
- 用“先留着吧”替代明确的保留期限和责任人
- 多 agent fan-in 后只关心代码合并，不处理分支残留