synthesize

Synthesis Skill

VCS プロバイダー

このスキルでは、Exarchos MCP アクション（create_pr、merge_pr、list_prs、check_ci など）を通じて VCS 操作を行います。 これらのアクションは、適切な VCS プロバイダー（GitHub、GitLab、Azure DevOps）を自動的に検出して振り分けます。 gh／glab／az コマンドは不要です。プロバイダーへの振り分けは MCP サーバーが処理します。

統合マージと混同しないでください。 このスキルは、VCS プロバイダー経由でユーザー向けの PR を main に取り込むため、merge_pr を呼び出します。これはリモート操作です。上流の関連スキルは serialize_merge（@skills/merge-orchestrator/SKILL.md）です。これは統合マージの経路であり、シングルライターのリースを保持しながら、delegate → merge-pending → delegate HSM ループ中に、サブエージェントのワークツリーブランチから統合ブランチへのローカルな git merge を構成します（生の merge_orchestrate は、その構成済みの実行ツール、または統合マージ以外の経路です）。Synthesize が serialize_merge や merge_orchestrate を呼び出すことはありません。merge-pending が merge_pr を呼び出すこともありません。

概要

レビュー段階の完了後に、スタックされた PR を提出します。複合アクション prepare_synthesis は、準備状況の確認、スタックの検証、テストの検証、品質シグナルの分析を 1 回の呼び出しにまとめます。これにより、これまで合成の失敗を引き起こしていた複数スクリプトの連携が不要になります。

前提条件：

• 委任されたすべてのタスクが完了し、レビュー（仕様および品質）に合格している
• 委任段階ですでに統合ブランチが作成されている
• タスクブランチが存在し、リモートにプッシュされている

レビューが未完了または不合格の場合は、先に進まず、まず review に戻ってください。

開始点： Synthesis には通常、機能／デバッグ／リファクタリングのワークフローにおける review 段階から移行します。また、オプトイン経路を通じて 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 は必須です。準備状況を確認する4つの項目（テストスイート、型チェック、スタック、変更ファイル）はすべて、これを作業ディレクトリとしてシェルコマンドを実行するため、判定対象となるツリーを指定します。ゲートはサーバーの起動時のディレクトリを代わりに使うことはありません。省略すると、誤ったリポジトリについて回答する代わりに、呼び出しが拒否されます。スタック型の統合中は、統合ワークツリーの絶対パスを渡してください。

このアクションでは、以下を実行します。

• フェーズの準備状況 -- ワークフローが正しいフェーズにあり、すべてのレビューが完了していることを確認します
• スタックの整合性 -- 分岐したブランチ、欠落したタスクブランチ、壊れた親ブランチの連鎖を検出し、自動的に再構築します
• テストの検証 -- スタックの最上位から 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 に従って構造化された説明を作成します。必須セクションは Summary、Changes、Test Plan とフッターです。プロジェクトでは、.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 をキューに登録しました：[URL]。CI／マージキューを待機しています。」と出力し、その後、ユーザーからの入力を待機します：「スタックをマージしますか？（yes/no/feedback）」

• '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]
  }
}})

シェパードの反復処理（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。

イベントが欠けている場合は、明示的なゲート呼び出しで、またヒントが未解消の間にテレメトリミドルウェアがツールの結果に追加する _eventHints フィールドで、complete: false とともにヒントが返されます。stack.submitted はチェックされません。

マージ後のクリーンアップ

PR のマージ後、クリーンアップを呼び出します：

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

続いて同期します：git fetch --prune を実行し、ワークツリーを回収します。

ワークツリーの GC 実行タイミング — synthesize の後（INV-12）。 ワークフローが 合成に到達すると、管理対象のワークツリーは不要になるため、この時点で 回収します。場当たり的な git worktree remove ではなく、管理対象のガベージ コレクター prune_worktrees を使用します。まずはドライランを実行します （デフォルトでは候補と回収可能なバイト数を報告し、何も削除しません）。その後、 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 です。作成するかどうかを判断する前に 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 への遷移は通常、action: "cleanup" によって cleanup が担います。フェーズのみを指定する単独の遷移は、手動クリーンアップ用の回避策です。

スタックブランチへの直接編集

スタックブランチはいつでも直接編集できます。ファイルを編集した後、ステージしてコミットを amend します（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 を実行する
スタックブランチを強制プッシュする	通常のプッシュを使用する
マージ前にワークツリーを削除する	マージの確認を待つ
テストに失敗した状態で PR を作成する	まずレビューフェーズに合格する
準備スクリプトを手動で実行する	prepare_synthesis 複合アクションを使用する

失敗への対処

テストの失敗、PR チェックの失敗、マージキューによる却下、MCP ツールのエラーについては、references/troubleshooting.md を参照してください。

フェーズ遷移とガード

遷移テーブルの全体については、@skills/checkpoint/references/phase-transitions.md を参照してください。

クイックリファレンス： synthesize → completed の遷移にはガード pr-url-exists が必要です。phase と同じ set 呼び出しで synthesis.prUrl または artifacts.pr を設定してください。

スキーマの確認

パラメータスキーマについては exarchos_workflow({ action: "describe", actions: ["update", "init"] }) を使用し、フェーズ遷移、ガード、プレイブックのガイダンスについては exarchos_workflow({ action: "describe", playbook: "feature" }) を使用してください。オーケストレーションアクションのスキーマについては exarchos_orchestrate({ action: "describe", actions: ["prepare_synthesis"] }) を使用してください。

完了条件

• prepare_synthesis の準備状況チェックに合格している
• references/pr-descriptions.md に従って PR の説明が作成されている
• PR が作成され、自動マージが有効になっている
• PR のリンクがユーザーに提供されている
• PR の URL とマージ順で状態が更新されている