Dev Finish

Branch completion workflow. The goal is to make the last mile explicit: verify, inspect git state, present safe choices, then execute only what the user selects.

This skill does not implement code, write tests, or review code. Run dev-verify and dev-code-review first unless the user explicitly overrides.

Step 0 — Load baseline

执行前先加载 references/dev-baseline.md。不假设、最小代码、外科手术式改动、可验证成功标准 全程生效。

baseline 与本 skill 的关联:

• 不假设 —— 不替用户决定 merge / PR / keep / discard。
• 可验证成功标准 —— 完成分支前必须有 fresh verification evidence。
• 外科手术式改动 —— 不顺手清理未被确认的分支、stash、worktree。

Step 1 — Preflight verification

先确认:

1. dev-verify 已给出当前回合的 PASS 证据,或你现在运行等价验证。
2. dev-code-review verdict 是 READY,或用户明确接受跳过 review 的风险。
3. git status --short 已读取,知道是否有未提交改动。

如果测试或 review 未通过,停止:

不能 finish: <tests/review/status> 未通过。
下一步: 修复后重跑 dev-verify / dev-code-review。

Step 2 — Detect workspace state

运行只读命令:

bash
git status --short
git branch --show-current
git rev-parse --show-toplevel
git rev-parse --git-dir
git rev-parse --git-common-dir

判断:

• 普通 checkout:git-dir == git-common-dir
• linked worktree:git-dir != git-common-dir
• detached HEAD:git branch --show-current 为空

如果工作区有未提交改动,先问用户是否要 commit / stash / keep uncommitted。不要继续 merge / PR。

Step 3 — Determine base branch

优先探测:

bash
git merge-base HEAD main
git merge-base HEAD master
git remote -v

如果无法判断 base branch,问用户确认。不要默认推送到未知目标。

Step 4 — Present choices

普通分支输出四选一:

分支已验证。请选择:

1. 本地 merge 回 <base-branch>
2. push 当前分支并创建 PR
3. 保留当前分支,我稍后自己处理
4. 丢弃这个分支的工作

你选哪一个?

Detached HEAD 输出三选一:

当前是 detached HEAD。请选择:

1. 新建分支后 push 并创建 PR
2. 保留当前 workspace,我稍后自己处理
3. 丢弃这个 workspace 的工作

你选哪一个?

不要在同一步执行动作。等用户选择。

Step 5 — Execute selected option

Option 1: merge locally

1. 切到 base branch。
2. pull 最新 base。
3. merge feature branch。
4. 在 merge 后结果上重新运行关键验证。
5. merge 成功且验证通过后,再考虑删除分支 / 清理 worktree。

禁止在 merge 成功前删除任何东西。

Option 2: push and create PR

1. git push -u origin <branch>
2. 用仓库现有 PR 工具创建 PR。
3. PR body 必须包含 Summary 和 Test Plan。
4. 不清理 worktree,因为后续可能要处理 review。

Option 3: keep as-is

报告 branch 和 path。不要清理。

Option 4: discard

必须要求用户输入精确确认:

这会删除:
- branch: <branch>
- commits: <commit list>
- worktree: <path, if owned>

请输入 discard 确认。

没有精确 discard 就停止。

Step 6 — Worktree cleanup rules

只在用户选择 merge 后清理或 discard 后清理。

只能清理明确由项目拥有的 worktree:

• .worktrees/
• worktrees/
• ~/.config/dev-skills/worktrees/

不清理平台 / harness 拥有的 workspace。无法判断归属时保留并报告。

Hard rules

• 测试或 review 未过,不 finish。
• 不替用户选择 merge / PR / keep / discard。
• 丢弃必须有精确确认。
• 不在 merge 成功前删除 branch 或 worktree。
• PR 路径不清理 worktree。
• 无法判断 base branch 或 workspace 归属时,先问。

Multi-Agent Note

dev-finish is main-agent-controlled because it can merge, push, create PRs, keep branches, or discard work.

Sub-agents may provide verification or review evidence before this phase, but final branch decisions and destructive operations stay with the main agent and the user. Follow ../../docs/multi-agent-policy.md before relying on any delegated verifier or reviewer output.