synthesize

Synthesis 技能

VCS 提供方

此技能通过 Exarchos MCP 操作（create_pr、merge_pr、list_prs、check_ci 等）执行 VCS 操作。 这些操作会自动检测并路由到正确的 VCS 提供方（GitHub、GitLab、Azure DevOps）。 无需使用 gh/glab/az 命令——MCP 服务会处理提供方的分发。

不要与集成合并混淆。 此技能会调用 merge_pr，通过 VCS 提供方向 main 合并面向用户的 PR——这是远程操作。上游同级技能是 serialize_merge（@skills/merge-orchestrator/SKILL.md）：集成合并路径会持有单写者租约，并在 delegate → merge-pending → delegate HSM 循环期间，将子 Agent 工作树分支通过本地 git merge 合并到集成分支（原始的 merge_orchestrate 是该组合式执行器／非集成路径）。Synthesize 绝不会调用 serialize_merge 或 merge_orchestrate；merge-pending 绝不会调用 merge_pr。

概述

审查阶段完成后提交堆叠式 PR。组合操作 prepare_synthesis 会将就绪检查、堆栈验证、测试验证和质量信号分析整合到一次调用中，从而消除历史上导致 Synthesis 失败的多脚本协调。

前置条件：

• 所有委派任务均已完成，且审查通过（规格审查和质量审查）
• 集成分支已在委派阶段创建
• 任务分支已存在并推送到远程

如果任一审查尚未完成或未通过，请勿继续——先返回 review。

入口： 通常在功能／调试／重构工作流的 review 阶段进入 Synthesis。也可以通过选择加入路径从 oneshot 工作流进入：当用户在 plan 或 implementing 期间表示“为此创建 PR”时，会追加 request_synthesize 事件，然后 finalize_oneshot 会解析选择状态并将工作流转换到 synthesize。有关选择加入机制和 synthesisPolicy 语义，请参阅 @skills/oneshot/SKILL.md。

触发条件

在以下情况下激活此技能：

• 用户运行 synthesize 命令
• 所有审查均已成功通过
• 准备好提交 PR
• finalize_oneshot 将 Oneshot 工作流解析为 synthesize

流程

操作手册： 按照 synthesis-flow 操作手册执行： exarchos_orchestrate({ action: "runbook", id: "synthesis-flow" }) 如果操作手册不可用，请使用 describe 获取操作架构：exarchos_orchestrate({ action: "describe", actions: ["prepare_synthesis"] })

步骤 1：验证就绪状态

调用 prepare_synthesis 组合操作，在单次操作中验证所有前置条件：

exarchos:exarchos_orchestrate({
  action: "prepare_synthesis",
  featureId: "<id>",
  repoRoot: "<absolute path of the repo under synthesis>"
})

必须提供 repoRoot。所有四项就绪检查（测试套件、类型检查、技术栈、变更文件）都会以此路径作为工作目录运行 shell 命令，因此它指定了本次判定所针对的代码树。此检查不会回退到启动服务时所在的目录——如果省略该参数，调用会被拒绝，而不会针对错误的代码库给出判定。在堆叠式综合期间，请传入集成工作树的绝对路径。

此操作会执行：

• 阶段就绪状态——确认工作流处于正确阶段且所有审查均已完成
• 堆栈完整性——检测分支是否已分叉、任务分支是否缺失或父级链条是否损坏，并自动重建
• 测试验证——从堆栈顶端运行 npm run test:run && npm run typecheck
• 基准回归——如果 state.verification.hasBenchmarks 为 true，则检查性能回归
• 质量信号——查询 code_quality 视图以查找回归和可执行的提示
• 文档就绪状态——变更过的文档表面必须有对应的文档更新（未触及文档表面时会自动豁免）
• 关卡事件——自动为每项检查（测试、基准、CodeRabbit）发送 gate.executed 事件

如需查看组合操作所执行的各项检查的完整说明，请参阅 references/synthesis-steps.md。

**成功时：**所有检查均已通过。响应中会包含就绪状态摘要及需向用户展示的质量提示。继续执行步骤 2。

**失败时：**响应会指出未通过的检查并提供修复指导。请遵循指导——通常需要返回 review 或 delegate。

如果任何质量提示的 confidenceLevel: 'actionable'，请在继续之前向用户展示 suggestedAction。

步骤 2：编写并验证 PR 描述

为堆栈中的每个 PR 编写结构化描述，并遵循 references/pr-descriptions.md。必需的部分：摘要、变更、测试计划，以及页脚。项目可以通过 .exarchos/pr-template.md 覆盖必需部分。

标题格式：<type>: <what>（最多 72 个字符）

将 PR 正文写入临时文件：

cat > /tmp/pr-body.md <<'EOF'
## Summary
[2-3 sentences: what changed, why it matters]

## Changes
- **Component** -- Description of change

## Test Plan
[Testing approach and coverage]

---
**Results:** Tests X pass · Build 0 errors
**Design:** [doc](path)
**Related:** #issue
EOF

创建 PR 之前进行验证：

exarchos:exarchos_orchestrate({
  action: "validate_pr_body",
  bodyFile: "/tmp/pr-body.md"
})

**验证通过之前，不要调用 create_pr。**如果验证失败，请修正文案并重新验证。

步骤 3：提交并合并

使用通过验证的正文创建 PR，并启用自动合并。按堆栈中的分支顺序（从底部向上）逐个执行：

// Create PR via VCS MCP action
exarchos_orchestrate({
  action: "create_pr",
  base: "<parent-branch>",
  head: "<branch>",
  title: "<type>: <what>",
  body: "<pr-body>"
})

// Enable auto-merge
exarchos_orchestrate({
  action: "merge_pr",
  prId: "<number>",
  strategy: "squash"
})

提交后：

1. 应用基准标签——如果 verification.hasBenchmarks 为 true，则应用标签：gh pr edit <number> --add-label has-benchmarks
2. 记录 PR URL——通过 exarchos_orchestrate({ action: "list_prs", state: "open" }) 获取 URL
3. 更新状态：

exarchos:exarchos_workflow({
  action: "update", featureId: "<id>", updates: {
    "artifacts": { "pr": ["<url1>", "<url2>"] },
    "synthesis": { "mergeOrder": ["<branch1>", ...], "prUrl": ["<url1>", ...], "prFeedback": [] }
  }
})

关于合并顺序策略，请参阅 references/merge-ordering.md。

人工检查点：输出“已将堆叠 PR 加入队列：[URLs]。等待 CI／合并队列。”然后暂停并等待用户输入：“合并堆栈？（是／否／反馈）”

• “yes”——PR 合并；通过 cleanup 转入已完成状态
• “feedback”——转到 shepherd [PR_URL] 处理评论，然后返回此处
• “no”——暂停工作流；稍后使用 rehydrate 恢复

事件发出

创建 PR 并启用自动合并后，使用 stack.submitted 事件记录提交。这是对已提交内容的遥测记录——不会据此做出任何决策，check-event-emissions 也不会要求发出此事件：

exarchos:exarchos_event({ action: "append", stream: "<featureId>", event: {
  type: "stack.submitted",
  data: {
    branches: ["task-001-branch", "task-002-branch"],
    prNumbers: [101, 102]
  }
}})

在 shepherd 迭代（CI 监控循环）期间，每次评估后都要发出事件（必需——升级策略会统计这些事件，以限制循环次数）：

exarchos:exarchos_event({ action: "append", stream: "<featureId>", event: {
  type: "shepherd.iteration",
  data: {
    iteration: 1,
    prsAssessed: 2,
    fixesApplied: 0,
    status: "all-green"
  }
}})

此阶段由 check-event-emissions 检查的事件：team.spawned、team.disbanded、shepherd.iteration。

若缺少某个事件，系统会以 complete: false 的提示返回——在显式门控调用中，以及遥测中间件在提示待处理期间添加到工具结果中的 _eventHints 字段里。不会检查 stack.submitted。

合并后清理

PR 合并后，调用清理：

exarchos:exarchos_workflow({
  action: "cleanup", featureId: "<id>", mergeVerified: true,
  prUrl: ["<url>", ...], mergedBranches: ["<branch>", ...]
})

然后同步：git fetch --prune 并回收 worktree。

Worktree GC 时机——在 synthesize 之后（INV-12）。 工作流进入 综合阶段后，不再需要受管的 worktree，因此此时应回收它们。请使用受管的 垃圾回收器 prune_worktrees，不要自行调用 git worktree remove： 先试运行（默认行为——报告候选项和可回收字节数，不会删除任何内容）， 然后再次调用并设置 dryRun: false 以执行操作。

exarchos:exarchos_orchestrate({ action: "prune_worktrees", repoRoot: "<repo-root>" })            // 试运行（默认）
exarchos:exarchos_orchestrate({ action: "prune_worktrees", repoRoot: "<repo-root>", dryRun: false }) // 执行

工作流停留在综合阶段后，next_actions 投影会提供同样的 prune_worktrees 试运行 选项。完整的执行流程见 @skills/cleanup/SKILL.md。

幂等性

对于“PR 已存在”的情况，create_pr 是唯一权威依据——决定是否创建 PR 前，不要预先检查 synthesis.prUrl / artifacts.pr。直接调用 create_pr：它会通过远程恢复保护机制返回此 (head, base) 对应的现有开放 PR；如果工作流已拥有一个 PR，则会以 PR_ALREADY_OWNED 拒绝。请根据此结构化响应进行分支处理，而不要预先检查。

合并后的清理与创建时的幂等性情况不同，不受 create_pr 管控：如果 PR 已经合并，请通过 action: "transition"、target: "completed" 转换到 completed（运行时会拒绝 updates.phase；规范的 transition 操作会运行 HSM 守卫并发出 workflow.transition）。此 completed 转换通常由 cleanup 通过 action: "cleanup" 负责；仅转换阶段的裸调用是手动清理的应急方案。

直接修改 Stack 分支

你可以随时直接修改 Stack 分支——编辑文件，然后暂存并修订提交（git add <files> && git commit --amend）。推送时使用带显式 SHA 的租约，绝不要使用不带参数的 --force-with-lease：

git push --force-with-lease=<ref>:<expected-sha>

不带参数的租约会以本地远程跟踪引用（可能已过时）为基准，可能覆盖并发推送。<expected-sha> 是循环上次通过 assess_stack 观察到的远程 SHA，也可以使用 git ls-remote --heads origin <ref> 实时读取。

完成输出

创建 PR 且检查通过后，报告：

## Synthesis Complete

PR: [URL]
Tests: X pass | Build: 0 errors

反模式

不要	应该
跳过审查阶段	始终先运行 review
强制推送 Stack 分支	使用普通推送
合并前删除 worktree	等待确认合并
测试失败时创建 PR	先确保审查阶段通过
手动运行就绪度脚本	使用 prepare_synthesis 复合操作

处理失败

有关测试失败、PR 检查失败、合并队列拒绝和 MCP 工具错误，请参阅 references/troubleshooting.md。

阶段转换和守卫条件

完整的转换表请参阅 @skills/checkpoint/references/phase-transitions.md。

快速参考： 从 synthesize 转换到 completed 阶段需要满足守卫条件 pr-url-exists——在同一次 set 调用中，将 synthesis.prUrl 或 artifacts.pr 与 phase 一并设置。

架构发现

使用 exarchos_workflow({ action: "describe", actions: ["update", "init"] }) 查看参数架构，使用 exarchos_workflow({ action: "describe", playbook: "feature" }) 查看阶段转换、守卫条件和剧本指南。使用 exarchos_orchestrate({ action: "describe", actions: ["prepare_synthesis"] }) 查看 orchestrate 操作的架构。

完成标准

• prepare_synthesis 就绪检查通过
• 按照 references/pr-descriptions.md 编写 PR 描述
• 创建 PR 并启用自动合并
• 向用户提供 PR 链接
• 更新状态，记录 PR URL 和合并顺序