Back to Details

merge-orchestrator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Merge Orchestrator Skill

Merge Orchestrator 技能

Local Git, Not Remote VCS

本地Git操作，非远程版本控制系统操作

This skill performs local 
git merge
 of a subagent's worktree branch into the integration branch, recording a rollback SHA so a 
git reset --hard
can undo the merge on any failure. It does not call the VCS provider (GitHub / GitLab / Azure DevOps) and does not require a PR id. For remote PR merging during the synthesize phase, see 
@skills/synthesis/SKILL.md
(
merge_pr
action).
The mental model and the rationale for why these are two separate concerns are documented in 
references/local-git-semantics.md
.
该技能执行子代理（subagent）工作树分支到集成分支的本地
git merge
操作，记录回滚SHA，以便在任何失败时通过
git reset --hard
撤销合并。它不会调用版本控制系统提供商（GitHub / GitLab / Azure DevOps）的接口，也不需要PR编号。若要在合成阶段执行远程PR合并，请查看
@skills/synthesis/SKILL.md
中的
merge_pr
操作。
关于这两个操作为何分为独立功能的思路和原理，记录在
references/local-git-semantics.md
中。

Overview

概述

Closes the loop between 
/delegate
(which spawns subagents into worktrees) and the integration branch that needs their work. After a delegated task completes inside a worktree, this skill:
  1. Composes preflight guards (ancestry, current-branch protection, main-worktree assertion, working-tree drift).
  2. Records pre-merge 
    HEAD
    of the integration branch as a rollback anchor.
  3. Performs a local 
    git merge
    of the source (subagent) branch into the target (integration) branch.
  4. On any failure, runs 
    git reset --hard <rollbackSha>
    and surfaces a categorized failure reason.
  5. Emits dedicated event types so the merge timeline is reconstructable from the event log alone.
Resumable: terminal phases (
completed
/ 
rolled-back
/ 
aborted
) short-circuit on re-entry without re-emitting events. Idempotent: re-dispatch with the same 
taskId
collapses via the 
next_actions
idempotency key.
该技能打通了
/delegate
（将子代理分配到工作树）与需要接收其工作成果的集成分支之间的闭环。当委托任务在工作树内完成后，该技能会执行以下步骤：
  1. 组合预检防护规则（祖先校验、当前分支保护、主工作树断言、工作树漂移检测）。
  2. 将集成分支合并前的
    HEAD
    记录为回滚锚点。
  3. 执行源分支（子代理分支）到目标分支（集成分支）的本地
    git merge
    操作。
  4. 若出现任何失败，执行
    git reset --hard <rollbackSha>
    并返回分类后的失败原因。
  5. 发送专属事件类型，以便仅通过事件日志即可重构合并时间线。
可恢复性：终端阶段（
completed
/ 
rolled-back
/ 
aborted
）在重新触发时会直接短路，不会重新发送事件。幂等性：使用相同
taskId
重新调度时，会通过
next_actions
的幂等键合并请求。

Triggers

触发条件

Activate this skill when:
  • The HSM is parked in 
    feature/merge-pending
    (entry guard fires when the most recent 
    task.completed
    carries a worktree association).
  • The 
    next_actions
    envelope surfaces a 
    merge_orchestrate
    verb with idempotency key 
    ${streamId}:merge_orchestrate:${taskId}
    .
  • The user runs 
    exarchos merge-orchestrate ...
    (CLI) or invokes 
    mcp__exarchos__exarchos_orchestrate({ action: "merge_orchestrate", ... })
    directly.
Do not activate this skill:
  • During the synthesize phase to merge a remote PR — that is 
    merge_pr
    .
  • When the workflow's 
    mergeOrchestrator.phase
    is already terminal — the resume short-circuit runs but no fresh dispatch is needed.
在以下场景激活该技能：
  • HSM处于
    feature/merge-pending
    状态（当最近的
    task.completed
    事件带有工作树关联时，进入防护规则触发）。
  • next_actions
    消息包中出现带有幂等键
    ${streamId}:merge_orchestrate:${taskId}
    的
    merge_orchestrate
    动词。
  • 用户运行
    exarchos merge-orchestrate ...
    （CLI命令）或直接调用
    mcp__exarchos__exarchos_orchestrate({ action: "merge_orchestrate", ... })
    。
请勿在以下场景激活该技能：
  • 在合成阶段合并远程PR——这属于
    merge_pr
    的功能范畴。
  • 工作流的
    mergeOrchestrator.phase
    已处于终端状态——恢复逻辑会短路，但无需重新调度。

Process

流程

Schema: discover the action's argument schema with 
mcp__exarchos__exarchos_orchestrate({ action: "describe", actions: ["merge_orchestrate"] })
. Strategy is required (no schema-level default) — pick 
squash
/ 
merge
/ 
rebase
deliberately.
Schema（ schema ）： 可通过
mcp__exarchos__exarchos_orchestrate({ action: "describe", actions: ["merge_orchestrate"] })
查看该操作的参数 schema 。合并策略为必填项（无默认值）——需明确选择
squash
/ 
merge
/ 
rebase
。

Step 1: Pick the merge strategy

步骤1：选择合并策略

StrategyLocal git operationWhen to choose
merge
git merge --no-ff --no-edit <source>
— explicit merge commit		Preserves the subagent's commit history with a visible merge boundary.
squash
git merge --squash <source>
then 
git commit
— single squash commit on target		Subagent commit history is noise; one logical change should land as one commit.
rebase
rebases an ephemeral copy of source onto target then ff-merges target — linear historyNo merge commit; integration branch stays linear. The original source ref is preserved (the rebase runs on a temporary branch that is deleted afterward), so an executor rollback only needs to reset target.
Strategy is required at the schema layer (#1127 collision check, #1109 §2 user-visible parity). There is no implicit default — operator intent is always explicit in the event log.
策略本地Git操作适用场景
merge
git merge --no-ff --no-edit <source>
— 显式合并提交		保留子代理的提交历史，带有清晰的合并边界。
squash
git merge --squash <source>
后执行 
git commit
— 在目标分支生成单个压缩提交		子代理的提交历史无意义；一个逻辑变更应作为单个提交落地。
rebase
将源分支的临时副本变基到目标分支，然后快进合并目标分支 — 线性历史无合并提交；集成分支保持线性。原始源引用会被保留（变基操作在临时分支上执行，之后会被删除），因此执行回滚只需重置目标分支。
合并策略在 schema 层为必填项（#1127冲突检查、#1109 §2用户可见一致性）。无隐式默认值——操作意图会始终明确记录在事件日志中。

Step 2: Invoke

步骤2：调用方式

Via MCP:
typescript
mcp__exarchos__exarchos_orchestrate({
  action: "merge_orchestrate",
  featureId: "<id>",
  sourceBranch: "<subagent-branch>",
  targetBranch: "<integration-branch>",
  taskId: "<task-id>",        // present when auto-dispatched from next_actions
  strategy: "squash",          // required
  dryRun: false,               // optional — preflight only, no executor invocation
  resume: false,               // optional — short-circuit on terminal phases
})
Via CLI:
bash
exarchos merge-orchestrate \
  --feature-id <id> \
  --source-branch <subagent-branch> \
  --target-branch <integration-branch> \
  --task-id <task-id> \
  --strategy squash
  # add --dry-run for preflight-only, --resume for terminal-phase short-circuit
CLI exit codes: 0 = success, 1 = invalid input, 2 = merge failed (preflight blocked or rollback executed), 3 = uncaught exception.
通过MCP调用：
typescript
mcp__exarchos__exarchos_orchestrate({
  action: "merge_orchestrate",
  featureId: "<id>",
  sourceBranch: "<subagent-branch>",
  targetBranch: "<integration-branch>",
  taskId: "<task-id>",        // 自动调度自next_actions时会携带该参数
  strategy: "squash",          // 必填
  dryRun: false,               // 可选——仅执行预检，不调用执行器
  resume: false,               // 可选——在终端阶段触发短路逻辑
})
通过CLI调用：
bash
exarchos merge-orchestrate \
  --feature-id <id> \
  --source-branch <subagent-branch> \
  --target-branch <integration-branch> \
  --task-id <task-id> \
  --strategy squash
  # 添加--dry-run仅执行预检，--resume开启终端阶段短路逻辑
CLI退出码：0 = 成功，1 = 输入无效，2 = 合并失败（预检拦截或执行回滚），3 = 未捕获异常。

Step 3: Interpret the result

步骤3：结果解读

The handler returns a 
ToolResult
whose 
data.phase
discriminates the outcome:
phase
MeaningOperator action
completed
Local merge landed; 
mergeSha
is the new HEAD of target.		None — workflow exits 
merge-pending
back to 
delegate
(HSM) and continues.
aborted
Preflight failed; no merge attempted. 
data.preflight
carries the structured guard sub-results.		Inspect 
preflight.ancestry / worktree / currentBranchProtection / drift
to identify which guard failed. Resolve the underlying condition (e.g., commit/stash drift, switch off a protected branch) and re-dispatch.
rolled-back
Merge was attempted, failed (
reason: 'merge-failed' / 'verification-failed' / 'timeout'
), and 
git reset --hard <rollbackSha>
ran. The integration branch is restored.		Inspect 
data.reason
. If 
data.rollbackError
is also present, the reset itself failed — the working tree is stranded and requires operator intervention.
For the full recovery flow per outcome, see 
references/recovery-runbook.md
.
处理器会返回一个
ToolResult
，其中
data.phase
字段用于区分结果类型：
phase
含义操作人员操作建议
completed
本地合并完成；
mergeSha
为目标分支的新HEAD。		无需操作——工作流从
merge-pending
状态退出，回到
delegate
状态（HSM）并继续执行。
aborted
预检失败；未尝试合并。
data.preflight
携带结构化的防护规则子结果。		检查
preflight.ancestry / worktree / currentBranchProtection / drift
以确定哪条防护规则失败。解决根本问题（如提交/暂存区漂移、切换出受保护分支）后重新调度。
rolled-back
尝试合并但失败（
reason: 'merge-failed' / 'verification-failed' / 'timeout'
），已执行
git reset --hard <rollbackSha>
。集成分支已恢复。		检查
data.reason
。若同时存在
data.rollbackError
，说明重置操作本身失败——工作树处于异常状态，需要操作人员介入处理。
关于每种结果的完整恢复流程，请查看
references/recovery-runbook.md
。

Step 4: Confirm event emissions

步骤4：确认事件发送

Three events are emitted directly to the workflow's event stream (stream id = 
featureId
) — not wrapped in 
gate.executed
:
Event typeWhenCarries
merge.preflight
Always (after preflight runs, before any merge attempt)Full structured guard sub-results + 
failureReasons
if 
passed: false
merge.executed
On successful local merge
mergeSha
, 
rollbackSha
, 
taskId
, source/target branches
merge.rollback
On post-merge failure followed by reset
rollbackSha
, 
reason
, 
taskId
, source/target branches
These events are auto-emitted by the handler — do not manually append them via 
mcp__exarchos__exarchos_event
during normal operation. Manual emission is only sanctioned during the documented manual-recovery flow in 
recovery-runbook.md
 when a merge has been completed out-of-band (e.g., conflict resolution) and the event log must be brought back in sync — follow that runbook's event-first sequencing.
Discover the event payload schemas via 
mcp__exarchos__exarchos_event({ action: "describe", eventTypes: ["merge.preflight", "merge.executed", "merge.rollback"] })
.
三个事件会直接发送到工作流的事件流（流ID = 
featureId
）——不会被包裹在
gate.executed
中：
事件类型发送时机携带内容
merge.preflight
始终发送（预检完成后，合并尝试前）完整的结构化防护规则子结果；若
passed: false
则携带
failureReasons
merge.executed
本地合并成功时
mergeSha
、
rollbackSha
、
taskId
、源/目标分支信息
merge.rollback
合并失败后执行回滚时
rollbackSha
、
reason
、
taskId
、源/目标分支信息
这些事件由处理器自动发送——正常操作流程中请勿通过
mcp__exarchos__exarchos_event
手动添加。仅在
recovery-runbook.md
中记录的手动恢复流程中允许手动发送：当合并操作已通过外部方式完成（如冲突解决），需要同步事件日志时，请遵循该手册中的事件优先顺序。
可通过
mcp__exarchos__exarchos_event({ action: "describe", eventTypes: ["merge.preflight", "merge.executed", "merge.rollback"] })
查看事件负载的 schema 。

Disambiguation: 
merge_orchestrate
vs 
merge_pr

区分：
merge_orchestrate
vs 
merge_pr

Two related actions, two distinct concerns:
Aspect
merge_orchestrate
(this skill)
merge_pr
(synthesis skill)
LayerLocal SDLC handoffRemote PR primitive
Phase affinity
merge-pending
(between delegate and review)
synthesize
What it mergesA subagent worktree branch into the integration branchA user-facing PR via the VCS provider API
Identifier required
sourceBranch
+ 
targetBranch
prId
Underlying operation
git merge
(local)
provider.mergePr()
(remote API)
Rollback
git reset --hard <rollbackSha>
(real, undoes the merge)		None — the VCS provider owns merge state
Events
merge.preflight
/ 
merge.executed
/ 
merge.rollback
pr.merged
If you reach for 
merge_orchestrate
thinking "I want to merge a PR," you want 
merge_pr
instead.
两个相关操作，对应不同的功能范畴：
维度
merge_orchestrate
（本技能）
merge_pr
（合成阶段技能）
层级本地SDLC交接远程PR基础操作
阶段关联
merge-pending
（委托与评审之间）
synthesize
合并对象子代理工作树分支到集成分支通过版本控制系统提供商API合并面向用户的PR
必填标识
sourceBranch
+ 
targetBranch
prId
底层操作
git merge
（本地）
provider.mergePr()
（远程API）
回滚机制
git reset --hard <rollbackSha>
（真实回滚，撤销合并）		无——版本控制系统提供商管理合并状态
事件
merge.preflight
/ 
merge.executed
/ 
merge.rollback
pr.merged
如果您想用
merge_orchestrate
来实现“合并PR”的需求，那么您应该使用
merge_pr
。

Resume Semantics

恢复语义

When invoked with 
resume: true
, the handler reads existing 
mergeOrchestrator
state. Terminal phases (
completed
/ 
rolled-back
/ 
aborted
, members of 
EXCLUDED_MERGE_PHASES
) short-circuit and return the recorded result with no new events and no executor call. Non-terminal phases (
pending
/ 
executing
) fall through to a fresh preflight + executor run, which is safe because the underlying git operations are idempotent on already-merged branches.
When invoked without 
resume
, prior state is deliberately ignored — fresh-dispatch semantics.
当以
resume: true
调用时，处理器会读取已有的
mergeOrchestrator
状态。终端阶段（
completed
/ 
rolled-back
/ 
aborted
，属于
EXCLUDED_MERGE_PHASES
）会触发短路逻辑，返回已记录的结果，不会发送新事件或调用执行器。非终端阶段（
pending
/ 
executing
）会执行完整的预检和执行器调用，这是安全的，因为底层Git操作在已合并的分支上具备幂等性。
当未携带
resume
参数调用时，会刻意忽略之前的状态——采用全新调度语义。

Dry-Run

试运行（Dry-Run）

dryRun: true
runs preflight, emits 
merge.preflight
, and short-circuits before the executor runs and before any state persistence. Returns 
{ dryRun: true, preflight, phase: 'pending' | 'aborted' }
. Useful for CI integrations that check merge readiness before the merge window opens.
dryRun: true
会执行预检，发送
merge.preflight
事件，并在执行器调用和状态持久化前触发短路逻辑。返回结果为
{ dryRun: true, preflight, phase: 'pending' | 'aborted' }
。适用于CI集成，可在合并窗口开启前检查合并就绪状态。

Anti-Patterns

反模式

Don'tDo Instead
Use this skill to merge a remote PRUse 
merge_pr
in the synthesize phase
Manually emit 
merge.preflight
/ 
merge.executed
/ 
merge.rollback
in normal flow		Let the handler auto-emit; manual emission causes duplicates (one exception: documented manual-recovery flow in 
recovery-runbook.md
)
Wrap merge events under 
gate.executed
Direct stream append with the dedicated event type — these are state transitions, not gate executions
Re-dispatch after a 
rolled-back
outcome without inspecting the reason		Read 
data.reason
and 
data.rollbackError
; address the root cause first
Omit 
--strategy
/ 
strategy:
field expecting a default		Strategy is required; supply 
squash
/ 
merge
/ 
rebase
explicitly
Invoke from a subagent worktreePreflight refuses (main-worktree assertion); invoke from the main worktree
禁止操作正确做法
使用本技能合并远程PR在合成阶段使用
merge_pr
在正常流程中手动发送
merge.preflight
/ 
merge.executed
/ 
merge.rollback
事件		由处理器自动发送；手动发送会导致重复事件（唯一例外：
recovery-runbook.md
中记录的手动恢复流程）
将合并事件包裹在
gate.executed
中		使用专属事件类型直接写入事件流——这些是状态转换事件，而非网关执行事件
在
rolled-back
结果出现后未检查原因就重新调度		查看
data.reason
和
data.rollbackError
；先解决根本问题
省略
--strategy
/ 
strategy:
参数并期望使用默认值		合并策略为必填项；需明确指定
squash
/ 
merge
/ 
rebase
从子代理工作树中调用预检会拒绝（主工作树断言）；从主工作树中调用

Phase Transitions and Guards

阶段转换与防护规则

For the full transition table, consult 
@skills/workflow-state/references/phase-transitions.md
.
Quick reference:
  • delegate
    → 
    merge-pending
    requires guard 
    merge-pending-entry
    — fires when the most recent 
    task.completed
    carries a worktree association AND 
    mergeOrchestrator.phase
    is not in 
    EXCLUDED_MERGE_PHASES
    .
  • merge-pending
    → 
    delegate
    requires guard 
    merge-pending-exit
    — fires when 
    mergeOrchestrator.phase
    enters a terminal value (
    completed
    / 
    rolled-back
    / 
    aborted
    ).
The HSM exits 
merge-pending
back to 
delegate
regardless of merge outcome — 
delegate
then re-evaluates whether more worktree-bearing tasks remain and either re-enters 
merge-pending
for the next, or transitions on to 
review
when all delegation is complete.
完整的转换表请查看
@skills/workflow-state/references/phase-transitions.md
。
快速参考：
  • delegate
    → 
    merge-pending
    需要
    merge-pending-entry
    防护规则——当最近的
    task.completed
    事件带有工作树关联，且
    mergeOrchestrator.phase
    不属于
    EXCLUDED_MERGE_PHASES
    时触发。
  • merge-pending
    → 
    delegate
    需要
    merge-pending-exit
    防护规则——当
    mergeOrchestrator.phase
    进入终端状态（
    completed
    / 
    rolled-back
    / 
    aborted
    ）时触发。
无论合并结果如何，HSM都会从
merge-pending
状态退出，回到
delegate
状态——
delegate
会重新评估是否还有带工作树的任务未完成，若有则再次进入
merge-pending
状态处理下一个任务，若所有委托任务都已完成则转换到
review
状态。

Schema Discovery

Schema 发现

For the argument schema, call 
mcp__exarchos__exarchos_orchestrate({ action: "describe", actions: ["merge_orchestrate"] })
. The full feature-workflow phase playbook (which includes 
merge-pending
) is available via 
mcp__exarchos__exarchos_workflow({ action: "describe", playbook: "feature" })
. Event payload shapes come from 
mcp__exarchos__exarchos_event({ action: "describe", eventTypes: ["merge.preflight", "merge.executed", "merge.rollback"] })
.
可通过
mcp__exarchos__exarchos_orchestrate({ action: "describe", actions: ["merge_orchestrate"] })
查看参数 schema 。包含
merge-pending
的完整功能工作流阶段手册可通过
mcp__exarchos__exarchos_workflow({ action: "describe", playbook: "feature" })
获取。事件负载结构可通过
mcp__exarchos__exarchos_event({ action: "describe", eventTypes: ["merge.preflight", "merge.executed", "merge.rollback"] })
查看。

Completion Criteria

完成标准

  • Preflight result 
    passed: true
    (or operator has decided to proceed despite a documented preflight gap)
  • mergeOrchestrator.phase === 'completed'
    in workflow state
  • merge.executed
    event present in the stream with the recorded 
    mergeSha
    and 
    rollbackSha
  • HSM has exited 
    merge-pending
    back to 
    delegate
  • Integration branch's HEAD matches the recorded 
    mergeSha
If any criterion fails, consult 
references/recovery-runbook.md
before re-dispatching.
  • 预检结果
    passed: true
    （或操作人员已决定忽略已记录的预检间隙）
  • 工作流状态中
    mergeOrchestrator.phase === 'completed'
  • 事件流中存在带有记录的
    mergeSha
    和
    rollbackSha
    的
    merge.executed
    事件
  • HSM已从
    merge-pending
    状态退出，回到
    delegate
    状态
  • 集成分支的HEAD与记录的
    mergeSha
    一致
若任何标准未满足，请在重新调度前查看
references/recovery-runbook.md
。