merge-worktree

合并工作树

分支收尾安全模式改编自采用 MIT 许可证的 finishing-a-development-branch 工作流。确切的固定版本和关联关系记录在 sources.json 中。

使用合并提交集成一个已注册的 Git 工作树。此技能负责集成和清理工作树；实现工作流必须将任务交接给它，而不是自行合并。

确认授权

根据请求和仓库确定以下输入：

• 源工作树路径和分支；
• 目标分支，以及该工作分支的分叉基点；
• 集成模式：本地或 GitHub PR；
• 对于 PR 模式，操作：仅创建或检查通过后合并；以及
• 清理选项：仅在明确请求 --clean-up 时启用，否则在成功集成后询问。

仅在仓库默认分支明确无误时才使用它。如果授权信息不完整，请提供以下选项：本地合并、创建 PR 但不合并、创建 PR 并在检查通过后合并，或保持分支不变。创建 PR 绝不代表获准合并。执行本地合并绝不代表获准推送。

来自 orchestrate-implementation 的候选项交接

当源是编排器候选项时，仅接受由父级拥有且已注册的候选工作树和分支。交接必须列明固定的候选基点/头部、确切的审查范围、已组装的泳道提交、重点验证、候选项审查证据（要求时提供新鲜的独立审查；或在允许的仅低风险工作中提供父级检查），以及授权状态。不得以已删除的工作者路径、目标分支当前的 HEAD 或工作者报告的 SHA 代替候选树。候选项交接不授予推送、合并 PR、部署或发布权限。只要相关内容和环境仍然匹配，可复用交接中的验证证据；但仍须重新验证实际集成提交、引用和制品身份。

预检

1. 运行 git worktree list --porcelain。要求源是已注册且未处于分离状态的工作树。
2. 确认源分支和目标分支是同一仓库中的不同分支，且没有正在进行的合并、变基或摘取提交操作。
3. 要求源分支至少包含一个目标分支无法到达的提交。如果它已经集成，请报告并跳过合并。
4. 查找检出目标分支的任何工作树。更新前要求它处于干净状态。
5. 检查源差异和提交。发现无关更改、疑似密钥或归属不明确时，停止操作。
6. 阅读仓库说明，并从源工作树运行最小范围的相关验证；或者接受已验证的证据，前提是其相关代码、测试、输入和环境仍与确切的源内容匹配；记录复用了哪些证据。
7. 如果源包含预期中的未提交更改，仅暂存这些文件并创建简洁的提交。除非收到请求，否则不要修改现有提交。
8. 对于 PR 模式，获取所选远程并执行清理；若认证失败，或目标状态存在歧义/分歧，则停止。对于本地模式，仅在用户要求基于远程跟踪目标进行集成时才获取远程。

绝不强制推送，也不要猜测目标分支。

本地集成

在候选合并通过之前，保持目标引用不变：

1. 记录当前目标 SHA。
2. 在该 SHA 创建临时集成分支和已注册的同级工作树。
3. 在集成工作树中，运行 git merge --no-ff <source-branch>，并附上简洁的说明。
4. 如果出现冲突，追溯双方的意图，并有针对性地解决每个文件。不要整批选择 ours 或 theirs。对于冲突的生成文件，使用其所属工具重新生成，而不是手动编辑。
5. 运行相关检查——如果集成后的内容与已验证内容相同，且相关输入和环境未变，则可复用仍然适用的已验证证据——并要求集成工作树保持干净且无冲突。务必重新验证实际合并提交、引用和制品身份。
6. 确认目标仍等于记录的 SHA。如果目标已变动，则停止，并保留已验证的集成工作树。
7. 将目标快进到已验证的集成提交。如果目标已检出，则在该干净工作树中更新它。否则，只有在分支引用的旧值仍与记录的 SHA 一致时，才更新该引用。
8. 验证目标现在指向集成提交。
9. 使用 git worktree remove 移除临时工作树，仅删除已知的临时分支，然后运行 git worktree prune。

本地模式下不要推送。集成清理时，绝不使用 rm -rf、强制移除工作树或强制更新。

GitHub PR 集成

在依赖快速变化的语法之前，先运行 gh --help 和相关的 gh pr 帮助。然后：

1. 验证 gh auth status、所选 GitHub 远程仓库和当前目标分支。
2. 正常推送源分支，并设置上游跟踪。
3. 复用该分支上未关闭的 PR，或创建一个以所选分支为目标分支的 PR。根据提交和验证证据拟定标题和正文。
4. 报告 PR URL。

对于仅开放 PR，到此为止。不要无限期等待检查，不要合并、启用自动合并或清理源工作树。

对于检查通过后合并，必须先获得明确授权，然后：

1. 如果 GitHub 报告存在冲突，则在本地使用 --no-ff 将当前目标分支合并到源分支，谨慎解决冲突，重新运行验证，然后正常推送。
2. 等待必需的检查。若检查失败或超时，则停止；绝不绕过分支保护。
3. 使用仓库允许的合并提交机制合并。如果策略要求使用队列或自动合并，则按该策略操作，不要绕过。
4. 验证 PR 已合并，且远程目标分支包含生成的提交，然后再清理。

源工作树清理

仅在本地集成成功或确认 PR 已合并后：

• 若收到明确的 --clean-up 请求，则移除源工作树。
• 否则，询问是否移除。
• 验证工作树干净，且其提交可从已集成的目标分支访问。
• 运行 git worktree remove <path>，然后运行 git worktree prune。
• 除非另有请求，否则不要删除本地或远程分支。

如果用户要求丢弃工作，先列出分支、路径、未提交文件以及将变得无法访问的提交。删除独有工作前，必须要求用户提供准确确认 discard。绝不要通过强制移除脏工作树来掩盖问题。

报告

报告收到的授权、模式、源、目标、合并提交或 PR URL、运行的检查、是否有内容被推送或在远程合并，以及是否移除了任一工作树。如果停止，则指出未通过的关卡，并保留可恢复状态。