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:

Composes preflight guards (ancestry, current-branch protection, main-worktree assertion, working-tree drift).
Records pre-merge
```
HEAD
```
of the integration branch as a rollback anchor.
Performs a local
```
git merge
```
of the source (subagent) branch into the target (integration) branch.
On any failure, runs
```
git reset --hard <rollbackSha>
```
and surfaces a categorized failure reason.
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

（将子代理分配到工作树）与需要接收其工作成果的集成分支之间的闭环。当委托任务在工作树内完成后，该技能会执行以下步骤：

组合预检防护规则（祖先校验、当前分支保护、主工作树断言、工作树漂移检测）。
将集成分支合并前的
```
HEAD
```
记录为回滚锚点。
执行源分支（子代理分支）到目标分支（集成分支）的本地
```
git merge
```
操作。
若出现任何失败，执行
```
git reset --hard <rollbackSha>
```
并返回分类后的失败原因。
发送专属事件类型，以便仅通过事件日志即可重构合并时间线。

可恢复性：终端阶段（

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：选择合并策略

Strategy	Local git operation	When 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 history	No 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`	Meaning	Operator 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 type	When	Carries
`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

merge_pr

区分：

merge_orchestrate

merge_pr

Two related actions, two distinct concerns:

Aspect	`merge_orchestrate` (this skill)	`merge_pr` (synthesis skill)
Layer	Local SDLC handoff	Remote PR primitive
Phase affinity	`merge-pending` (between delegate and review)	`synthesize`
What it merges	A subagent worktree branch into the integration branch	A 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't	Do Instead
Use this skill to merge a remote PR	Use `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 worktree	Preflight 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

。

merge-orchestrator

Original

Translation

Merge Orchestrator Skill

Merge Orchestrator 技能

Local Git, Not Remote VCS

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

Overview

概述

Triggers

触发条件

Process

流程

Step 1: Pick the merge strategy

步骤1：选择合并策略

Step 2: Invoke

步骤2：调用方式

Step 3: Interpret the result

步骤3：结果解读

Step 4: Confirm event emissions

步骤4：确认事件发送

Disambiguation:
`merge_orchestrate`
vs
`merge_pr`

区分：
`merge_orchestrate`
vs
`merge_pr`

Resume Semantics

恢复语义

Dry-Run

试运行（Dry-Run）

Anti-Patterns

反模式

Phase Transitions and Guards

阶段转换与防护规则

Schema Discovery

Schema 发现

Completion Criteria

完成标准

merge-orchestrator

Original

Translation

Merge Orchestrator Skill

Merge Orchestrator 技能

Local Git, Not Remote VCS

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

Overview

概述

Triggers

触发条件

Process

流程

Step 1: Pick the merge strategy

步骤1：选择合并策略

Step 2: Invoke

步骤2：调用方式

Step 3: Interpret the result

步骤3：结果解读

Step 4: Confirm event emissions

步骤4：确认事件发送

Disambiguation: merge_orchestrate vs merge_pr

区分：merge_orchestrate vs merge_pr

Resume Semantics

恢复语义

Dry-Run

试运行（Dry-Run）

Anti-Patterns

反模式

Phase Transitions and Guards

阶段转换与防护规则

Schema Discovery

Schema 发现

Completion Criteria

完成标准

Disambiguation:
`merge_orchestrate`
vs
`merge_pr`

区分：
`merge_orchestrate`
vs
`merge_pr`