local-merge

/local-merge

使い捨ての浅いクローンを使ってソースブランチをターゲットブランチに取り込み、そのワークツリーがすでにターゲットブランチにある場合に限り、PRIMARY ワークツリーを更新します。

ターゲットのデフォルトは main です。

入力

入力	必須	デフォルト	例
BRANCH	はい	—	feat/local-merge-skill
TARGET	いいえ	main	develop、release/v2
PRIMARY	いいえ	プライマリワークツリーのパス	/Users/you/projects/repo
MESSAGE	いいえ	merge: $BRANCH into $TARGET	merge: feat/auth into main

運用モデル

次の2つの独立した問題として扱います。

1. リモート統合：使い捨ての浅いクローン内でソースブランチをターゲットブランチにマージし、更新したターゲットブランチをプッシュします。
2. ローカルへの反映：PRIMARY がすでにターゲットブランチにある場合は、そのワークツリーを安全に更新します。

リモート統合が成功したからといって、ローカルへの反映も安全だと決めつけないでください。

基本的な不変条件

• マージと公開操作にはローカルの git のみを使用します。
• 統合用のワークスペースには使い捨ての浅いクローンを優先します。
• 追跡対象のローカル状態を破棄しないでください。
• チェックアウト済みのローカルターゲットブランチにローカルのみのコミットがある場合、マージとリベースのどちらを使うかを勝手に選ばないでください。
• ローカルターゲットが単に遅れていて、ほかに問題なく更新できる場合に限り、自動的にファストフォワードします。
• コンフリクトが発生したら停止し、ユーザーに対応を委ねます。
• 強制プッシュはしないでください。
• 絶対パスと、状態を変更するコマンドでの git -C <abs-path> を使用します。
• シェルコマンドを組み立てる前に、参照を検証します。

プライマリワークツリーの特定

リポジトリのプライマリワークツリーを PRIMARY として使用します。

プライマリワークツリーのパスが曖昧な場合は、周辺的な順序から推測せず、停止してユーザーに確認してください。

追跡対象状態の退避

このスキルでチェックアウト済みのターゲットブランチを変更する前に追跡対象のローカル変更を保護する必要がある場合は、次の手順を一貫して使用します。

• 追跡対象の変更のみをステージングする
• 一時的な WIP コミットを作成する
• 続行する前に一時コミットの参照を記録する
• ブランチを更新する
• 一時コミットに対するソフトリセットで追跡対象の状態を正確に復元する

この退避手順に追跡対象外のファイルを黙って含めないでください。

フェーズ 1 — リモート統合

1. 状態の特定

次を確認します。

• リポジトリのルート
• ソースブランチ
• ターゲットブランチ
• リモート名
• プライマリワークツリーのパス
• PRIMARY が現在ターゲットブランチにあるかどうか

次を検証します。

• ソースとターゲットが有効なブランチ参照であること
• 両方のブランチのリモート参照が存在すること

次の場合は停止します。

• ソースブランチがデタッチ状態である
• ソースブランチが公開されておらず、問題なくプッシュできない

ソースブランチが未公開でも問題なくプッシュできる場合は、まずプッシュしてから続行します。リモート統合を始める前に、ソースブランチを公開しておく必要があります。

ソースワークツリーに、公開済みブランチに反映されていない追跡対象のローカル変更がある場合は停止します。local-merge が統合するのは公開済みブランチの状態のみです。フェーズ 1 では、ソース側の未コミット変更を退避したりマージしたりしません。

2. 統合用ワークスペースの作成

リポジトリのリモート URL から使い捨ての浅いクローンを作成します。

必要なものだけをフェッチします。

• <remote>/$TARGET
• <remote>/$BRANCH

マージに必要な履歴をクローンに確保し、必要に応じて安全に再試行できるようにします。浅い履歴では不十分な場合は、慎重に履歴を追加取得するか、停止して制約を報告します。

3. ソースをターゲットにマージ

浅いクローン内でターゲットブランチをチェックアウトし、ソースブランチをマージします。

通常のマージをデフォルトとします。マージがすでにファストフォワードの場合は、そのまま適用します。

コンフリクトが発生した場合は、次のとおりにします。

• 直ちに停止する
• コンフリクトの内容を明確に伝える
• 自動解決しない
• プッシュを続行しない

4. プッシュ先

シャロークローンから、更新されたターゲットブランチをプッシュします。

リモートが更新されたためにプッシュが拒否された場合は、次の方法で1回だけ再試行できます。

• シャロークローン内のターゲットブランチを更新する
• 破棄可能なクローン内だけで、統合コミットを再作成するかリベースする
• 更新後の状態で新たな人間の判断が必要にならない場合に限り、再試行する

再試行で競合が発生した場合、または状況が曖昧になった場合は、直ちに停止します。

再試行の上限：3回。強制プッシュはしないでください。

破棄可能なクローンのクリーンアップに失敗しても、処理は妨げられません。

フェーズ 2 — ローカルへの反映

PRIMARY がすでにターゲットブランチにある場合に限り、このフェーズを実行します。

PRIMARY が別のブランチにある場合は、リモートへの統合が成功したことを報告し、ローカルへの反映は行いません。

1. ローカルのターゲット状態を確認する

ローカルのターゲットブランチの状態を分類できるだけの情報を集めます。

• 作業ツリーに追跡対象のローカル変更があるか
• ローカルの $TARGET が <remote>/$TARGET より遅れているか
• ローカルの $TARGET に <remote>/$TARGET にないコミットがあるか
• ブランチを早送りできるか、分岐しているか
• Git で問題なくマージできる場合でも、取り込み対象の変更とローカルのみの変更が重なり、運用上のリスクがあるか

標準的な Git の情報を使います。

• 状態
• 先行および遅延しているコミット数
• 取り込み対象のコミットログ
• ローカルのみのコミットログ
• 差分の統計

2. ローカルのターゲットブランチを更新する

ケース：クリーンで、遅れているだけ

<remote>/$TARGET まで自動的に早送りします。

ケース：追跡対象のローカル変更があり、遅れているだけ

追跡対象状態の退避手順を使い、<remote>/$TARGET まで早送りした後、退避した追跡対象状態を復元します。

ケース：ローカルのターゲットブランチに <remote>/$TARGET にないコミットがある

黙って書き換えたりマージしたりしないでください。

次のいずれを行うか、ユーザーに確認します。

• ローカルのコミットを、更新されたリモートのターゲットブランチにリベースする
• 更新されたリモートのターゲットブランチを、ローカルのターゲットブランチにマージする

追跡対象のローカル変更もある場合は、その操作の前に追跡対象状態の退避手順を使い、操作後に復元します。

ユーザーがマージまたはリベースを選択したら、エージェントはその選択を実行してかまいません。選択された操作で競合が発生した場合は直ちに停止し、退避参照があればそれを保持して、ユーザーに処理を戻します。

これは、現行のスキルから意図的に方針を厳格化したものです。リスクの低い自動マージが可能な場合でも、ローカルのみのターゲットコミットがあれば、ユーザーの判断が必要なケースとして扱います。

ケース：意味上のリスクまたは曖昧さがある

Git がマージ可能と判断しても、変更箇所の重複に運用上のリスクがある場合は、「テキスト上の競合がない」ことを「安全」とみなさず、停止してエスカレーションします。

例：

• 複数のファイルにまたがる関連設定の変更
• フックと関連スクリプトが並行して変更されている
• コマンドの契約変更により、ローカルの前提が無効になる可能性がある

完了

次の点を報告します。

• リモートへの統合が成功したか
• ローカルへの反映を実行したか
• ローカルのターゲットブランチを早送りしたか、エスカレーションしたか、または手を付けずに残したか
• 追跡対象状態を退避したか
• 引き続き必要なユーザーの判断があるか

安全ルール

• 強制プッシュをしない
• 明示的な指示がない限り、ハードリセットをしない
• 競合を黙って解決しない
• 分岐したローカルのターゲットブランチについて、マージかリベースかを黙って選ばない
• 自動化よりも人間の状態を優先して保持する

出力形式

Source branch: <branch>
Target branch: <target>
Remote: <remote>

Remote integration:
- source branch published: yes/no
- shallow clone merge: clean/conflict
- target pushed: yes/no

Local propagation:
- primary on target: yes/no
- tracked state shelter used: yes/no
- result: fast-forward / user decision required / conflict / skipped

If action is required:
- reason
- exact worktree or branch involved
- whether tracked state is currently sheltered