get-shit-done 的 execute-phase 工作流：基于波次的并行执行编排与安全门详解

本指南深入解析 get-shit-done（GSD）中负责“执行阶段内全部计划”的核心工作流 execute-phase.md：它如何在保持编排器（Orchestrator）上下文精简的前提下，将阶段内多个计划按依赖关系分组为“波次”（wave）、并行派发子代理执行，并在波次间与阶段收尾处设置一整套安全门（安全恢复门、MVP+TDD 门、合并后构建测试门、回归门、Schema 漂移门、代码库漂移门）。读完本文，你将掌握 gsd:execute-phase 的全部命令行参数、波次执行与 worktree 隔离的底层机制、各运行时的兼容回退策略，以及失败分类与断点恢复的完整链路。

一、工作流定位：编排器协调，子代理执行

execute-phase 是 GSD 规格驱动开发流程中“从计划到实现”的执行枢纽。其核心原则在 execute-phase.md 的 <core_principle> 中明确为：

Orchestrator coordinates, not executes.（编排器负责协调，不负责执行）

编排器的职责被收敛为一条固定管线：发现计划 → 分析依赖 → 分组波次 → 派生子代理 → 处理检查点 → 汇总结果。而每个子代理（gsd-executor）加载完整的执行计划上下文，独立完成自己的计划，避免上下文互相污染。

这一设计带来两个直接收益：

• 上下文精简：编排器只持有路径与元数据，而非计划全文，200K 上下文的模型下编排器仅占约 10%～15% 上下文；子代理每次都是全新上下文窗口，无轮询阻塞、无上下文泄漏。
• 职责分离：STATE.md、ROADMAP.md 等共享工件由编排器统一写入，避免多个并行代理“最后写入者胜”互相覆盖。

命令入口定义在 commands/gsd/execute-phase.md，其 frontmatter 声明了 requires: [phase, verify-work]，并开放 Read / Write / Edit / Glob / Grep / Bash / Agent / TodoWrite / AskUserQuestion 等工具权限。

二、命令入口与参数解析

gsd:execute-phase 的参数解析是工作流的第一步（parse_args 步骤），必须在加载任何上下文之前完成：

参数	含义
第一个位置参数	PHASE_ARG（阶段号，支持 3、04 及 4.1、03.1 这类小数阶段）
--wave N	WAVE_FILTER，只执行阶段中的第 N 波，用于节奏控制、配额管理或分批上线
--gaps-only	只执行 gap_closure: true 的补缺计划（配合 /gsd:plan-phase {X} --gaps 生成的缺口计划）
--cross-ai	CROSS_AI_FORCE=true，强制所有计划走跨 AI 运行时执行
--no-cross-ai	CROSS_AI_DISABLED=true，本次运行禁用跨 AI 执行，覆盖配置与计划 frontmatter
--interactive	切换为交互式执行模式（详见下文）
--auto	进入自动推进链路（阶段验证通过后自动执行 transition 工作流）
--mvp	与 ROADMAP 的 **Mode:** mvp、配置 workflow.mvp_mode 构成 MVP 模式判定链
--no-transition	由 plan-phase 自动推进链调用时使用，验证通过后仅返回完成状态、不执行 transition

关键语义在 commands/gsd/execute-phase.md 中被反复强调：文档化的 flag 只是可用行为，不是隐含激活行为——一个 flag 只有在 $ARGUMENTS 中字面出现时才视为激活，绝不因为被文档提及就推断其生效。这一点也有对应测试 execute-phase-active-flags.test.cjs 守护。

若 --wave 缺省，则保持既有行为：执行阶段内所有未完成波次。若手动调用（无 --auto），还必须先清除上次中断 --auto 链遗留的临时链标记 workflow._auto_chain_active，防止残留状态触发非预期的自动推进；此操作不触碰用户持久偏好 workflow.auto_advance。

三、运行时兼容性：Claude Code、Copilot 与其他运行时

子代理派发是运行时相关的（<runtime_compatibility> 节），不同 AI 运行时的能力差异直接决定执行策略：

• Claude Code：使用 Agent(subagent_type="gsd-executor", ...)，该调用会阻塞直到子代理完成并返回结果，语义最直接。
• Copilot：子代理派发不能可靠返回完成信号。默认退化为顺序内联执行——不再派发并行代理，而是为每个计划直接内联阅读并执行 execute-plan.md。只有当用户明确要求并行时才尝试并行派发，且必须依赖第 3 步的 spot-check 回退机制来探测完成。
• 其他运行时：若 Agent/agent 工具不可用，同样使用顺序内联执行作为回退。是否可用应在运行时实际探测，而不是根据运行时名称臆断。

配套的回退规则（Fallback rule）是一条不变量：如果派生的代理已经完成了工作（可见的提交、SUMMARY.md 已存在），但编排器始终没有收到完成信号，则基于 spot-check 视为成功并继续下一个波次/计划。绝不允许无限期阻塞等待信号——永远通过文件系统与 git 状态来验证。这一规则在 execute-phase.md 的“Completion signal fallback”小节给出了具体探测脚本：

SUMMARY_EXISTS=$(test -f "{phase_dir}/{plan_number}-{plan_padded}-SUMMARY.md" && echo "true" || echo "false")
COMMITS_FOUND=$(git log --oneline --all --grep="{phase_number}-{plan_padded}" --since="1 hour ago" | head -1)
COMMITS_SINCE_DISPATCH=$(git log "${EXPECTED_BRANCH}" --since="${DISPATCH_TS}" --oneline | head -1)

SUMMARY.md 存在且提交可查 → 视为成功继续；SUMMARY.md 缺失但日志仍在产生提交 → 继续等待；无任何活动 → 报告失败并进入失败处理。可配置的停滞监视（#3212）：每 executor.stall_detect_interval_minutes（默认 5）分钟检查一次，若在 executor.stall_threshold_minutes（默认 10）分钟内既无完成信号、也无 SUMMARY.md、也无预期分支新提交，则暂停并提供三条恢复路径：继续等待、杀掉重试、杀掉后切换内联执行。对应测试见 bug-3212-execute-phase-stall-safe-resume.test.cjs。

此外，Codex 运行时存在一个必须先验证的硬约束：spawn_agent 无法映射 Claude Code 的 isolation="worktree" 参数。因此在初始化阶段，若检测到 RUNTIME=codex 且 workflow.use_worktrees != false，直接打印 FATAL 并退出（fail closed），防止工作流以为代理已隔离、实际却直接修改主检出目录。相关行为测试见 bug-3360-codex-execute-phase-worktrees.test.cjs。

四、初始化与上下文加载

初始化（initialize 步骤）通过 SDK 查询一次性加载全部上下文：

INIT=$(gsd-sdk query init.execute-phase "${PHASE_ARG}")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
AGENT_SKILLS=$(gsd-sdk query agent-skills gsd-executor)

解析出的 JSON 字段包括：executor_model、verifier_model、commit_docs、parallelization、branching_strategy、branch_name、phase_found、phase_dir、phase_number、phase_name、phase_slug、plans、incomplete_plans、plan_count、incomplete_count、state_exists、roadmap_exists、phase_req_ids、response_language。

4.1 模型解析规则

executor_model 若为 "inherit"，则在所有 Agent() 调用中省略 model= 参数——绝不能传 model="inherit"。省略该参数会让 Claude Code 自动继承当前编排器模型；只有 executor_model 是显式模型名（如 "claude-sonnet-4-6"、"claude-opus-4-7"）时才显式传 model=。verifier_model 同理用于验证代理。若 response_language 已设置，须将其注入所有派生子代理的 prompt，保证面向用户的输出语言一致。这一继承语义由测试 bug-2516-inherit-model-execute-phase.test.cjs 覆盖。

4.2 上下文窗口自适应

读取 context_window（默认 200000）后，prompt 装配按窗口分级：

• ≥ 500000（1M 级模型）：执行器额外获得此前波次的 SUMMARY.md 与阶段 CONTEXT.md/RESEARCH.md；验证器获得全部 PLAN.md、SUMMARY.md、CONTEXT.md 与 REQUIREMENTS.md，实现跨波次感知与带历史的验证。
• < 200000（200K 以下）：子代理 prompt 做瘦身——执行器省略扩展偏差规则示例与检查点示例（按需从 executor-examples.md 加载），规划器省略扩展反模式清单与特异性示例（按需从 planner-antipatterns.md 加载）；核心规则与决策逻辑保持内联。该策略约降低执行器静态开销 40% 而不损失行为正确性。

4.3 前置校验与 fail-closed

初始化阶段有多个必须提前执行的校验：

• phase_found=false → 报错：阶段目录不存在。
• plan_count=0 → 报错：阶段内无计划。
• state_exists=false 但 .planning/ 存在 → 提供“重建或继续”选项。
• parallelization=false → 波次内计划顺序执行。
• 孤儿 worktree 清扫：[ "$USE_WORKTREES" != "false" ] && gsd-sdk query worktree.reap-orphans，清理上次崩溃会话遗留的锁定 worktree（#3707）。

4.4 子模块路径计算

若项目使用 git 子模块，worktree 隔离仅当计划触及子模块路径时才不安全（执行器提交协议无法在隔离 worktree 内正确处理子模块提交）。此前版本只要存在 .gitmodules 就无条件禁用 worktree 隔离，连累子模块项目中所有不相干的计划。现在改为一次性计算子模块路径，再按计划逐一相交判断：

if [ -f .gitmodules ]; then
  SUBMODULE_PATHS=$(git config --file .gitmodules --get-regexp '^submodule\..*\.path$' 2>/dev/null | awk '{print $2}')
else
  SUBMODULE_PATHS=""
fi

SUBMODULE_PATHS 导出到 execute_waves 步骤，在那里做出逐计划的 worktree 决策（详见 6.3 节），完整实现见 per-plan-worktree-gate.md。

五、执行前的安全与质量门

5.1 安全恢复门（safe_resume_gate）

在信任 STATE.md 或派发任何执行器之前，先从 INIT 中的活动未完成计划推导 CURRENT_PLAN_ID，再检索近期历史：

CURRENT_PLAN_ID="{phase_number}-{plan_padded}"
SUMMARY_PATH="{phase_dir}/{plan_padded}-SUMMARY.md"
PLAN_COMMITS=$(git log --oneline --grep="${CURRENT_PLAN_ID}" -30)

如果生产提交已存在但 SUMMARY.md 缺失，必须停止再派发新执行器——继续会引发重复劳动与过期的 STATE.md/ROADMAP 进度。此时提供三条恢复选项：

• 手动收尾（close out manually）：检查提交、写 SUMMARY.md，再更新 STATE/ROADMAP。
• 从头重执行（re-execute from scratch）：派发前先回滚或取代部分提交。
• 标记并跳过（mark-and-skip）：记录异常，仅在用户明确确认后继续。

这一门与 execute-plan.md 中的“原子收尾不变量”（生产代码提交 → SUMMARY 提交 → STATE/ROADMAP 更新）互为表里：任何“已有生产提交但无 SUMMARY 提交”的半完成状态，都必须由下一次 execute-phase 在派发执行器前检测出来。

5.2 MVP+TDD 门

当 MVP_MODE=true 且 TDD_MODE=true 时，在每个实现步骤开始前执行任务级门：

IS_BEHAVIOR_ADDING=$(gsd-sdk query task.is-behavior-adding "$TASK_FILE" --pick is_behavior_adding)
if [ "$IS_BEHAVIOR_ADDING" = "true" ]; then
  RED_COMMIT=$(git log --oneline --grep="^test(${PHASE_NUMBER}-${PLAN_ID}):" -- "**/*.test.*" "**/*.spec.*" "tests/" | head -1)
  if [ -z "$RED_COMMIT" ]; then
    gsd-sdk query state.update last_gate_trip "${PLAN_ID}/${TASK_ID}" || true
    echo "MVP+TDD GATE TRIPPED: missing RED commit for ${PLAN_ID}/${TASK_ID}"
    exit 1
  fi
fi

纯文档/纯配置/纯测试任务返回 is_behavior_adding=false 而豁免。MVP_MODE 通过集中式查询 phase.mvp-mode 解析，优先级链为：CLI flag → ROADMAP **Mode:** mvp → workflow.mvp_mode 配置 → false。门拦截后的停机报告格式见 execute-mvp-tdd.md，相关测试见 execute-mvp-tdd-gate.test.cjs。

5.3 阻塞反模式检查（check_blocking_antipatterns）

在所有其他工作之前（priority="first"），检查阶段目录中的 .continue-here.md：

ls ${phase_dir}/.continue-here.md 2>/dev/null || true

若存在且其 “Critical Anti-Patterns” 表中有 severity = blocking 的行，该步骤不可跳过：代理必须对每个阻塞反模式回答三个问题——① 这是什么反模式？（用自己的话描述，不得照抄交接文档）② 它如何显现？（解释导致其被记录的具体失败）③ 什么结构性机制（而非口头承认）能阻止复发？——若无法从 .continue-here.md 的上下文中回答，则停下来向用户澄清。

六、波次执行（execute_waves）

6.1 波次发现与分组

discover_and_group_plans 通过一条查询加载计划清单与波次分组：

PLAN_INDEX=$(gsd-sdk query phase-plan-index "${PHASE_NUMBER}")

解析出 phase、plans[]（含 id、wave、autonomous、objective、files_modified、task_count、has_summary）、waves（波次号 → 计划 ID 映射）、incomplete、has_checkpoints。过滤规则：跳过 has_summary: true 的计划；--gaps-only 时再跳过非 gap_closure 计划；WAVE_FILTER 设置时跳过波次不符的计划。

波次安全检查：若设置了 WAVE_FILTER 但仍有低波次未完成计划匹配当前执行模式，必须停下并告知用户先完成更早的波次——绝不允许波次 2+ 在前置波次未完成时执行。分组结果以执行计划表格呈现（波次、计划 ID、构建内容简述）。

6.2 检查点心跳（checkpoint heartbeats）

多计划阶段会累积大量子代理上下文，可能触发 Claude API SSE 层在大型 tool_result 与下一个 assistant turn 之间以 Stream idle timeout - partial response received 终止连接（Claude Code + Opus 4.7 在约 200K+ cache_read 时观测到，#2410）。为保持流活跃，每个波次与计划边界必须输出纯 assistant 文本行、无工具调用的心跳，且每行以 [checkpoint] 开头，使 /gsd:manager 的后台完成处理器可以 grep 部分转录：

[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} starting, {wave_plan_count} plan(s), {P}/{Q} plans done
[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} starting ({P}/{Q} plans done)
[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} plan {plan_id} {status} ({P}/{Q} plans done)
[checkpoint] phase {PHASE_NUMBER} wave {N}/{M} complete, {P}/{Q} plans done ({wave_success}/{wave_plan_count} ok)

{P}/{Q} 是全阶段累计的已完成/总计划数，跨波次单调递增；{status} 为 complete（成功）、failed（执行器错误）或 checkpoint（人工门返回）。波次开始心跳对单计划波次同样是强制项。

6.3 波次内文件重叠检查与逐计划 worktree 决策

文件重叠检查（派发前）：检查波次内所有计划的 files_modified 列表，若任意两个计划共享哪怕一个文件，说明存在隐式依赖，不得并行。检测用贪心哈希即可：遍历每个文件的归属计划，发现冲突则记录两个计划。命中时向用户告警并仅对本波次将 PARALLELIZATION 覆盖为 false（顺序执行），同时标注为规划缺陷，建议用户重新规划该阶段。

逐计划 worktree 决策：execute_waves 步骤 2.5 为波次内每个计划运行 per-plan-worktree-gate.md，将计划声明的 files_modified（来自 phase-plan-index JSON）与 SUBMODULE_PATHS 相交。归一化规则包括：剥离 ./ 前缀、剥离尾部 /、双向匹配（计划路径是子模块或其内部；或子模块位于计划路径内部）、以及 glob 前缀处理（vendor/**/*.c 能匹配子模块 vendor/foo）。命中交集则将 USE_WORKTREES_FOR_PLAN=false。plan_id 追加进 WAVE_WORKTREE_PLANS 累加器（当 USE_WORKTREES_FOR_PLAN != false 时）。派发分支必须以当前计划的 USE_WORKTREES_FOR_PLAN 为门控，而不是项目级 USE_WORKTREES。计划路径缺失/不可解析时，安全回退是禁用该计划的 worktree 隔离并记录原因。

6.4 派发执行器：worktree 模式与顺序模式

派发前捕获快照：EXPECTED_BASE=$(git rev-parse HEAD)、DISPATCH_TS、EXPECTED_BRANCH。worktree 模式（USE_WORKTREES_FOR_PLAN != false）下还要创建 WAVE_WORKTREE_MANIFEST 临时 JSON 文件，用于记录 {agent_id, worktree_path, branch, expected_base}——它是后续清理的单一事实来源（#3384）。

并行派发的关键纪律：波次内多个代理的 Agent() 调用必须一条消息只派一个、run_in_background: true。同时发送所有 Agent 调用会让多个 git worktree add 竞争 .git/config.lock。代理仍在各自的 worktree 创建完成后并行运行。

worktree 模式（isolation="worktree"）的 prompt 包含：

• <worktree_branch_check>：首要动作是在任何 reset/checkout 之前断言 HEAD。worktree 由 Claude Code 的 isolation="worktree" 派生，使用 worktree-agent-<id> 命名空间。若 HEAD 位于受保护 ref（main/master/develop/trunk/release/*）或处于 detached 状态，HALT——不得通过 git update-ref 自行强力回卷（那会摧毁多活跃场景下的并发提交，#2924）；只有第一步断言通过后 git reset --hard 才安全（#2015）。随后用 git merge-base HEAD {EXPECTED_BASE} 校验基址并校正。
• <parallel_execution>：说明本代理是并行执行器；git commit 正常跑 hooks，不得传 --no-verify（除非编排器显式传入 workflow.worktree_skip_hooks=true）。不得修改 STATE.md/ROADMAP.md——execute-plan.md 会自动检测 worktree 模式（.git 是文件而非目录）并跳过共享文件更新，由编排器在合并后统一写入。SUMMARY.md 必须在返回前提交（先写 SUMMARY → 提交 → 之后才输出叙述），因为编排器会在代理返回后强制移除 worktree，未提交的 SUMMARY 将永久丢失（#2070）。

顺序模式（项目级 USE_WORKTREES=false，或逐计划子模块交集将其置为 false）则省略 isolation="worktree"，将 <parallel_execution> 替换为 <sequential_execution>（在主工作树上执行、正常提交、同样遵守“先写 SUMMARY 再提交”顺序）；成功标准也相应改为允许更新 STATE.md 与 ROADMAP（通过 roadmap update-plan-progress）。当波次内任一计划降到顺序模式，受影响的计划必须逐个执行以避免并发写主工作树——同波次保留 worktree 隔离的计划仍可与顺序计划并行，但两个非 worktree 计划必须串行；项目级 USE_WORKTREES=false 时全波次串行，无视 PARALLELIZATION 设置。

6.5 合并后构建与测试门（post-merge gate）

单个 worktree 内自检通过不代表合并后依然正确——并行计划对共享文件（模型、注册表、CLI 入口点）的 add/add 冲突可能静默丢代码。因此每波合并完成后执行 post-merge-gate.md：

• 构建门：解析构建命令（workflow.build_command 配置 → Xcode scheme → Makefile → Justfile → Cargo → Go → Python → npm run build），5 分钟超时。超时（124）记警告、非阻塞；失败则累计 WAVE_FAILURE_COUNT 并提供“现在修复/继续”选择。
• 测试门：同样解析测试命令（配置 → Xcode → Makefile → Justfile → package.json → Cargo → Go → pytest），5 分钟超时。超时记警告继续；失败累计计数并在后续波次显示 ⚠ Note: ${WAVE_FAILURE_COUNT} prior wave(s) had test failures。

该门补上了 Anthropic 工程研究中指出的“Generator 自评盲区”：代理可靠地报告 Self-Check: PASSED，即使合并其工作会制造失败。对应文档偏差测试见 execute-phase-step-5-5-deviation-doc.test.cjs 与 execute-phase-worktree-artifacts.test.cjs。

6.6 worktree 清理与共享工件更新

清理（步骤 5.5）：仅当波次中至少一个计划使用了 worktree 隔离时才执行。清理消费 WAVE_WORKTREE_MANIFEST（不重新创建、不截断）。优先使用有界辅助命令 gsd-sdk query worktree.cleanup-wave --manifest "$WAVE_WORKTREE_MANIFEST"，它校验分支身份、期望基址、删除差异、合并结果与 worktree 移除后再删除临时分支；若辅助命令报告阻塞则解决清单条目后重跑同一命令，不得回退到广谱 worktree 发现。清理前将编排器 CWD 钉回主 worktree 并校验分支未漂移（#3174）。清单缺失时直接 BLOCKED 退出（#3384）。

合并守卫包括：合并前检查 worktree 分支的删除差异（有删除则 BLOCKED 人工复核）；合并后删除文件数超过 5 且非 .planning/ 时自动回滚并提示 ALLOW_BULK_DELETE=1（#2384）；.planning/ 下文件若在主分支删除又被 worktree 合并复活则重新删除（#2501）；移除 worktree 前抢救未提交的 SUMMARY.md（#2070、#2838）；锁定 worktree 先 unlock 再重试，仍失败则输出手工清理命令。

跨波依赖偏离模式（如 merge: bring 09-01 + 09-02 into 09-03 base 的自定义基址更新合并）不走标准清理循环，需用 cleanup-tail 片段清理残留 worktree——它只读取当前波次清单，不触碰无关的 worktree-agent-* worktree。

共享工件更新（步骤 5.7）：当波次中任一执行器以 isolation="worktree" 运行时，该代理跳过了 STATE/ROADMAP 更新，编排器成为这些文件的唯一写入者。仅当测试通过（TEST_EXIT=0）才更新跟踪——测试失败或超时（124，视为不确定）时跳过，计划保持 in-progress，避免在集成测试失败时错误标记完成。更新后仅在实际有变更时提交：docs(phase-{N}): update tracking after wave {N}。

测试门失败处理（步骤 5.8）：合并成功但测试失败时展示失败输出并给出“现在修复（推荐）/继续”选项；累计失败数 > 1 时强烈建议先修复——跨波次叠加失败呈指数级变难诊断。修复提交规范为 fix: resolve post-merge conflicts from wave {N}。

6.7 完成报告与 spot-check

每个波次结束前必须对每个 SUMMARY.md 做 spot-check：验证 key-files.created 前 2 个文件存在于磁盘；git log --oneline --all --grep="{phase}-{plan}" 至少返回 1 条提交；检查无 ## Self-Check: FAILED 标记。任一失败则报告该计划并进入失败处理（“重试该计划？”或“继续剩余波次？”）。

七、失败分类与处理

波次执行中遇到失败，先分类再分支（#3095）：

CLASS_JSON=$(gsd-sdk query agent.classify-failure -- "$AGENT_RETURN_BODY")
CLASS=$(echo "$CLASS_JSON" | jq -r '.class')
SENTINEL=$(echo "$CLASS_JSON" | jq -r '.sentinel // empty')
RETRY_AFTER=$(echo "$CLASS_JSON" | jq -r '.retryAfterSeconds // empty')

一个分类器覆盖 Claude/Copilot/Codex/Gemini 的哨兵信号（usage limit、rate limit、429、too many requests、RESOURCE_EXHAUSTED、usage_limit_reached）：

• quota-exceeded：不提供“立即重试”。先跑第 5 步 spot-check——若 SUMMARY 缺失但提交存在，路由到安全恢复（state.verify-against-disk）而非直接重派。展示运行时哨兵、重试提示、部分提交数、SUMMARY 是否存在，提供“等待配额重置后恢复（推荐）/切换运行时或模型恢复/中止阶段并报告部分状态”三选项，配额重置后重跑 /gsd:execute-phase。
• classify-handoff-bug：错误含 classifyHandoffIfNeeded is not defined 时视为 Claude 运行时 bug 而非 GSD 问题；运行同样 spot-check，通过即视为成功。
• unknown-failure：报告失败计划并询问继续/停止，继续可能级联到依赖计划失败。

其他失败场景的处置：波次 1 失败 → 波次 2 依赖者很可能失败，用户选择尝试或跳过；全波代理失败 → 系统性问题，停止上报；检查点无法解决 → “跳过此计划？”或“中止阶段执行？”，部分进度记入 STATE.md。完整失败处理矩阵见 execute-phase.md 的 <failure_handling> 节。

八、检查点处理与交互模式

8.1 检查点（checkpoint_handling）

autonomous: false 的计划需要用户交互。自动模式（gsd-sdk query check auto-mode 判定，链标记或用户偏好任一为真）下：

• human-verify → 自动派发续接代理，{user_response} 传 "approved"，记录 ⚡ Auto-approved checkpoint。
• decision → 自动派发续接代理，{user_response} 取检查点详情的第一选项。
• human-action → 照常呈现给用户（认证门不可自动化）。

标准流程：派发代理 → 运行至检查点任务或认证门 → 返回结构化状态（已完成任务表、当前任务与阻塞点、检查点类型/详情、等待内容）→ 呈现给用户 → 用户回复 “approved”/“done”/问题描述/决策选择 → 派发全新的续接代理（而非 resume）继续。为何用新代理而非 resume：resume 依赖的内部序列化在并行工具调用下会失效，带显式状态的新代理更可靠。并行波次中的检查点：代理暂停返回时其他并行代理可能已完成，呈现检查点、派发续接、等待全部完成后进入下一波。

8.2 交互模式（--interactive）

--interactive 时切换为纯内联执行（不派生子代理），任务间设用户检查点：

1. 照常加载计划清单（discover_and_group_plans）；
2. 逐计划（忽略波次分组）呈现 Plan {id}: {name}、目标、任务数，提供 Execute / Review first / Skip / Stop 四选项；
3. “Review first” 则读取并展示完整计划文件后再次询问 Execute / Modify / Skip；
4. “Execute” 则内联阅读并遵循 execute-plan.md（不派生子代理），一次执行一个任务；
5. 每任务后短暂暂停，用户有输入则先处理反馈再继续；
6. 计划完成后展示结果、提交、创建 SUMMARY.md，呈现下一计划；
7. 全部计划后进入验证（与正常模式相同）。

收益：无子代理开销、token 消耗大幅下降；用户尽早发现错误、省去昂贵验证循环；保持 GSD 的规划/跟踪结构。最适合小阶段、bug 修复、验证缺口与学习 GSD 的场景。交互模式直接跳到 handle_branching 步骤。

九、分支处理、跨 AI 委托与部分波次执行

9.1 分支处理（handle_branching）

按 branching_strategy 分派："none" 跳过、留在当前分支；"phase" 或 "milestone" 使用 init 预计算的 branch_name。新阶段分支必须从 origin/HEAD（项目默认分支）派生，而非当前 HEAD——否则连续阶段会叠加且不推送（#2916）：

DEFAULT_BRANCH=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}

分支已存在则直接复用；否则先 git fetch origin "$DEFAULT_BRANCH"（失败且无本地副本时拒绝创建分支），随后 git checkout -b "$BRANCH_NAME" "origin/$DEFAULT_BRANCH"。所有后续提交进入该分支，合并由用户处理。

9.2 跨 AI 委托（cross_ai_delegation）

可选步骤 2.5，在计划发现之后、正常波次执行之前。激活逻辑：--no-cross-ai 直接跳过；--cross-ai 标记所有未完成计划；否则需计划 frontmatter cross_ai: true 且 配置 workflow.cross_ai_execution=true 同时满足。相关配置：workflow.cross_ai_command、workflow.cross_ai_timeout（默认 300 秒）。

对每个跨 AI 计划：从 PLAN.md 提取 <objective> 与 <tasks>，追加 PROJECT.md 上下文，组装为自包含执行 prompt；执行前检查脏工作树并告警；绝不 shell 插值 prompt，一律经 stdin 管道传递以防注入：

echo "$TASK_PROMPT" | timeout "${CROSS_AI_TIMEOUT}s" ${CROSS_AI_CMD} > "$CANDIDATE_SUMMARY" 2>"$ERROR_LOG"

成功（exit 0 且 SUMMARY 结构有效）则写入该计划的 SUMMARY.md、更新 STATE/ROADMAP、标记已处理跳过 execute_waves；失败则展示错误并给出 retry / skip（回退到正常执行器）/ abort 三选项。

9.3 部分波次执行（handle_partial_wave_execution）

使用 --wave N 后需重跑计划发现（phase-plan-index）并应用同样的“未完成”过滤。若阶段内仍有未完成计划：停止，不运行阶段验证、不标记阶段完成，呈现“继续剩余波次 / 显式运行下一波”的命令提示。若所选波次恰好是阶段最后剩余工作，则继续正常验证与收尾流程。

十、波次后的各道门

10.1 代码评审门（code_review_gate，required）

不可跳过，但仅建议、永不阻塞。workflow.code_review=false 时显示跳过说明并继续。否则调用 Skill(skill="gsd-code-review", args="${PHASE_NUMBER}")，用确定性路径（${PHASE_DIR}/${PADDED}-REVIEW.md）读取 status: frontmatter——不是 glob。状态非 clean/skipped/空时提示运行 /gsd:code-review ${PHASE_NUMBER} --fix。Skill 调用异常时显示非阻塞错误后继续。无论评审结果如何，都继续 close_parent_artifacts → regression_gate → verify_phase_goal。

10.2 关闭父工件（close_parent_artifacts）

仅对小数/抛光阶段（如 4.1、03.1）生效：定位父阶段 UAT 文件，将 ## Gaps 中 status: failed 的条目更新为 resolved；全部解决后将 UAT frontmatter status: diagnosed → resolved 并更新时间戳；引用到的 debug session 文件状态置为 resolved 并移入 .planning/debug/resolved/；最后统一提交。

10.3 回归门（regression_gate）

验证前运行先前阶段的测试套件，捕捉跨阶段回归。跳过条件：首阶段（无先前阶段）或不存在先前的 VERIFICATION.md。通过 find .planning/phases/ -name "*-VERIFICATION.md" ! -path "*${PHASE_NUMBER}*" 发现先前阶段，从中提取测试文件引用，汇总为 REGRESSION_FILES 后按“项目配置 > Makefile > 语言嗅探”顺序解析测试命令并执行。全部通过则继续验证；失败则展示“测试文件 × 阶段 × 状态”表，提供“先修复（推荐）/照常验证（回归会叠加）/中止回滚重规划”三选项（AskUserQuestion）。

10.4 Schema 漂移门（schema_drift_gate）

在验证标记成功之前运行 gsd-sdk query verify.schema-drift "${PHASE_NUMBER}"。其背景是：构建/类型检查通过可能因为 TypeScript 类型来自配置而非活数据库，产生假阳性验证。drift_detected=false 则跳过；drift_detected=true && blocking=true 时默认阻塞验证，展示已变更的 schema 文件与待推送的 ORM 及推送命令，提供“现在运行 push（推荐）/ 以 GSD_SKIP_SCHEMA_CHECK=true 绕过 / 中止调查”三选项。

10.5 代码库漂移门（codebase_drift_gate）

阶段提交后的结构漂移检测（#2003），按契约非阻塞：任何内部错误都必须落到 verify_phase_goal，此门永不使阶段失败。完整规范见 codebase-drift-gate.md：action_required=false 静默继续；directive=warn 打印 message 字段原文（列出新增目录、桶导出、迁移、路由模块）并提示 /gsd:map-codebase --paths {affected_paths}；directive=auto-remap 则加载 gsd-codebase-mapper 的技能包并派发增量重映射代理（--paths 限定范围、在文档 frontmatter 中盖章 last_mapped_commit），派发失败仅记日志。两个配置键：workflow.drift_threshold（整数，默认 3，最小漂移元素数）与 workflow.drift_action（warn 默认 / auto-remap）。

十一、阶段目标验证与收尾

11.1 验证阶段目标（verify_phase_goal）

验证的是阶段 GOAL 是否达成，而非仅任务完成。派发 gsd-verifier 子代理，prompt 中携带阶段目标（来自 ROADMAP）、需求 ID（phase_req_ids）、must_haves 与代码库的对照要求，并将 PLAN frontmatter 的需求 ID 与 REQUIREMENTS.md 交叉核对——每个 ID 都必须有出处；产物为 VERIFICATION.md。1M+ 上下文模型下，验证器还会读取 CONTEXT.md、RESEARCH.md 与先前阶段 VERIFICATION（回归检查）。验证器自身的技能包通过 gsd-sdk query agent-skills gsd-verifier 加载。

读取 VERIFICATION.md 的 status: 后按表路由：

Status	动作
passed	→ update_roadmap
human_needed	持久化人工验证项为 UAT 文件并呈现给用户；阶段保持 pending 直到重跑验证为 passed
gaps_found	呈现缺口摘要，提供 /gsd:plan-phase {phase} --gaps

human_needed 时创建 {phase_dir}/{phase_num}-HUMAN-UAT.md（UAT 模板格式，status: partial），提交 test({phase_num}): persist human verification items as UAT，向用户呈现人工测试清单；用户 “approved” 则继续更新路线图，报告问题则进入缺口闭合。gaps_found 呈现缺口报告与 VERIFICATION.md 完整路径，缺口闭合循环为：/gsd:plan-phase {X} --gaps → 创建 gap_closure: true 计划 → /gsd:execute-phase {X} --gaps-only → 验证器重跑。

11.2 更新路线图（update_roadmap）

gsd-sdk query phase.complete "${PHASE_NUMBER}" 由 CLI 统一处理：勾选阶段复选框并附完成日期、更新进度表（Status → Complete）、更新计划计数、推进 STATE.md 至下一阶段、更新 REQUIREMENTS.md 可追溯性、扫描验证债务（返回 warnings 数组）。有警告时逐一列出并说明将出现在 /gsd:progress 与 /gsd:audit-uat。随后统一提交 ROADMAP/STATE/REQUIREMENTS/VERIFICATION。

11.3 收尾步骤链

• auto_copy_learnings：features.global_learnings=true（默认关闭）时，将阶段 LEARNINGS.md 复制到全局知识库 ~/.gsd/knowledge/；复制失败不阻塞完成。
• close_phase_todos：将 frontmatter 中 resolves_phase: <当前阶段号> 的待办移入 .planning/todos/completed/ 并提交（#2433）；无匹配则静默跳过。
• update_project_md：演化 .planning/PROJECT.md 防止规划文档漂移（#956）——把本阶段验证的需求从 Active 移到 Validated 并注明 Validated in Phase {X}: {Name}，更新 ## Current State 与 Last updated: 脚注，提交 docs(phase-{X}): evolve PROJECT.md after phase completion；文件不存在则跳过。

11.4 下一步路由（offer_next）

gaps_found 时验证步骤已给出缺口闭合路径，跳过自动推进。--no-transition（由 plan-phase 自动推进链调用）时返回 ## PHASE COMPLETE 摘要后停止。自动推进判定：--auto flag 或 AUTO_MODE=true（且验证通过无缺口）→ 内联执行 transition.md（不派发 Agent，编排器上下文约 10%～15%，transition 需要阶段完成数据）。注意 不存在 /gsd-transition 命令，transition 工作流仅供内部使用，绝不建议用户使用。非自动模式则停止并呈现下一步命令，且严格区分下一阶段 CONTEXT.md 是否存在以推荐不同入口（discuss → plan → execute 的推荐起点不同）；只列出工作流实际支持的命令，不得虚构命令名。

十二、恢复机制与上下文效率

恢复（resumption）：重跑 /gsd:execute-phase {phase} 即可——discover_plans 会跳过已有 SUMMARY 的已完成计划，从第一个未完成计划继续波次执行。STATE.md 跟踪：最后完成的计划、当前波次、待处理检查点。整个生命周期与 STATE.md 生命周期规范 对齐。

上下文效率（context_efficiency）：编排器在 200K 窗口约占 10%～15%，1M+ 窗口可更多；子代理每次全新上下文（200K～1M 视模型而定），无轮询、无上下文泄漏。1M+ 模型下可考虑：直接向执行器传递更丰富的上下文（代码片段、依赖输出）而非仅文件路径；≤3 个计划且无依赖的小阶段内联执行、省去子代理派发开销；放宽 /clear 建议（5 倍窗口下上下文腐坏起始点远在后方）。

十三、源码佐证与延伸阅读

本工作流的实现与验证证据分散于仓库以下位置，供深入研读：

• 工作流主文档：get-shit-done/workflows/execute-phase.md
• 子步骤规范：per-plan-worktree-gate.md、post-merge-gate.md、codebase-drift-gate.md
• 计划级执行协议：get-shit-done/workflows/execute-plan.md（含“原子收尾不变量”与 A/B/C 三种执行模式）
• 命令定义与 flag 语义：commands/gsd/execute-phase.md
• 执行器代理契约：agents/gsd-executor.md（worktree 分支检查、路径安全等）
• 参考文档：agent-contracts.md、context-budget.md、gates.md、checkpoints.md、tdd.md、worktree-path-safety.md、execute-mvp-tdd.md
• 相关测试：execute-phase-wave.test.cjs、execute-phase-active-flags.test.cjs、execute-phase-worktree-artifacts.test.cjs、execute-phase-step-5-5-deviation-doc.test.cjs、execute-mvp-tdd-gate.test.cjs、bug-3212-execute-phase-stall-safe-resume.test.cjs、bug-3360-codex-execute-phase-worktrees.test.cjs

总而言之，execute-phase 的价值在于把“阶段执行”从一次性的 prompt 变成了有纪律的工程流水线：波次并行的吞吐、worktree 隔离的并发安全、checkpoint 心跳的流稳定性、以及验证前层层把关的六道门，共同保证了并行 AI 代理协作产出的代码在合并后依然可信、可验证、可追溯。