finishing-a-development-branch

完成开发分支

概述

核心原则： 验证测试 → 检测环境 → 呈现选项 → 执行选择 → 清理。

开始时声明： "我正在使用 finishing-a-development-branch 技能来完成这项工作。"

第 1 步：验证测试

运行项目的完整测试套件（npm test / cargo test / pytest / go test ./...）。

如果测试失败，报告失败项并停止。菜单只在测试套件全部通过后才出现：

Tests failing (<N> failures). Must fix before completing:

[Show failures]

如果测试通过： 继续第 2 步。

第 2 步：检测环境

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
# Capture now, while still inside the workspace — Step 5 changes directory
# before cleanup (Step 6) needs this value
WORKTREE_PATH=$(git rev-parse --show-toplevel)

该结果决定显示哪个菜单，以及如何清理：

状态	菜单	清理
GIT_DIR == GIT_COMMON（普通仓库）	标准 3 个选项	无需清理工作树
GIT_DIR != GIT_COMMON，具名分支	标准 3 个选项	基于来源判断（见第 6 步）
GIT_DIR != GIT_COMMON，分离 HEAD	精简 2 个选项（不含合并）	由外部管理，保留原位

第 3 步：确定基础分支

基础分支即本次工作分叉自的分支，通常记录在计划、对话内容或该分支的上游分支中。如果尚不清楚，请询问："此分支分叉自 吗？"合并前务必确认：合并到错误的基础分支，撤销成本很高。

第 4 步：呈现选项

普通仓库和具名分支的工作树：恰好呈现以下 3 个选项：

Implementation complete. What would you like to do?

1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)

Which option?

分离 HEAD：恰好呈现以下 2 个选项：

Implementation complete. You're on a detached HEAD (externally managed workspace).

1. Push as new branch and create a Pull Request
2. Keep as-is (I'll handle it later)

Which option?

按原样呈现菜单，简洁明了，且每个选项都必须来自上述列表。只有当人类伙伴明确要求放弃工作时，才会执行丢弃操作（见下文"如果人类伙伴要求放弃工作"）。等待对方作答，集成决策由对方做出。

第 5 步：执行选择

选项 1：本地合并

# Get main repo root for CWD safety
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

# Merge first — verify success before removing anything
git checkout <base-branch>
git pull
git merge <feature-branch>

# Verify tests on merged result
<test command>

如果合并后的结果测试失败：停止操作，保留工作树和分支，并进行排查。由于尚未推送，此合并仅限本地，可以恢复。

合并结果通过测试后：清理工作树（第 6 步），然后删除分支：

git branch -d <feature-branch>

选项 2：推送并创建 PR

git push -u origin <feature-branch>
# From a detached HEAD, name the new branch on the remote:
# git push origin HEAD:refs/heads/<new-branch>

随后，使用代码托管平台的工具创建针对 的拉取请求/合并请求。如有可用的 CLI 则使用 CLI，否则使用推送时大多数平台打印的创建链接。如果仓库中存在 PR 模板及约定，请遵循。最后将 URL 报告给人类伙伴。

保留工作树，因为人类伙伴会在其中根据 PR 反馈继续迭代。

选项 3：保持现状

报告："保留分支 。工作树保存在 。"

如果人类伙伴要求放弃工作

仅当对方明确要求丢弃工作时，才执行此路径。先请求确认：

This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>

Type 'discard' to confirm.

等待对方给出完全一致的确认。收到确认后：

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

然后清理工作树（第 6 步），并强制删除分支：

git branch -D <feature-branch>

第 6 步：清理工作区

适用于选项 1 和已确认的丢弃操作。 选项 2 和选项 3 始终保留工作树。两种调用方都已将目录切换到主仓库根目录。工作树的移除必须在工作树之外执行，并且使用第 2 步中、切换目录之前记录的 GIT_DIR/GIT_COMMON/WORKTREE_PATH 值。

如果 GIT_DIR == GIT_COMMON： 普通仓库，无需清理工作树。完成。

如果 WORKTREE_PATH 位于 .worktrees/ 或 worktrees/ 之下： 该工作树由 Superpowers 创建，由我们负责清理：

git worktree remove "$WORKTREE_PATH"
git worktree prune  # Self-healing: clean up any stale registrations

如果移除被拒绝（提示 contains modified or untracked files）：工作树中包含其他地方都不存在的文件，例如未提交的计划、笔记或临时工作内容。切勿自行决定使用 --force。请向人类伙伴说明风险并询问：

git -C "$WORKTREE_PATH" status --porcelain -uall

Worktree removal refused — these files were never committed:

<file list>

1. Commit them to <branch> before cleanup
2. Move them into <main repo root>
3. Delete them (unrecoverable)

Which?

按对方的选择执行，然后移除工作树。

其他情况： 宿主环境负责管理该工作区，保留原位即可。如果平台提供工作区退出工具，则使用该工具。

快速参考

选项	合并	推送	保留工作树	清理分支
1. 本地合并	是	-	-	是
2. 创建 PR	-	是	是	-
3. 保持原样	-	-	是	-
丢弃（仅限明确请求）	-	-	-	是（force）

常见托词

托词	实际情况
"本次会话早些时候测试已经通过"	对即将集成的代码树运行测试套件。绿色结果只能证明它运行时所在的那个代码树是正常的。
"他们显然想合并"	集成是你的人类伙伴的决定。展示菜单并等待。
"他们似乎已经完成这个功能了，我可以提议丢弃它"	菜单按原样即为完整。只有当你的人类伙伴明确提出要求时才执行丢弃。
"'行，删掉它'也算确认"	只有输入的 discard 这个词才能授权删除。
"PR 已经提交，所以工作树现在就是多余的了"	PR 的反馈会在该工作树中修复。在工作成果合并之前，它都会保留。
"这个其他工作树看起来已经过时，我也一并清理掉"	只清理 .worktrees/ 或 worktrees/ 下的工作树。其余的都归宿主所有。
"删除被拒绝了，--force 只是完成清理而已"	拒绝意味着文件只存在于该工作树中。--force 会永久销毁这些文件。向你的人类伙伴说明并征求意见。
"合并结果的失败大概只是偶发性不稳定"	合并结果失败时必须全部停止。在调查期间，分支和工作树保持原样。
"基础分支显然是 main"	确认分叉点或询问。合并到错误的基础分支，撤销成本很高。
"推送被拒绝了，强制推送就能解决"	推送被拒绝意味着远端已经发生变化。先调查；只有在你的人类伙伴明确要求时才执行强制推送。