別環境で作られた未マージPRを、現行コードへ安全に移植させる（AI向け指示書）

これは何

「別のPC／別のメンバー／別のAIが作った未マージPR」を取り込むときの手順書。 AI にこの MD を読ませると、cherry-pick して競合を潰すのではなく、移植すべき設計だけを取り出して現行コードの語彙へ統合し直すという順序で動く。

対象は、複数の環境（PC・アカウント・エージェント）が同じリポジトリへ交互にコミットする運用。 PR が2〜3日放置されるだけで、同じファイルが本流で大きく書き換わり、PR本文に書かれた前提が嘘になる。

AI がまず理解すること（ここを飛ばすと必ず事故る）

未マージPRの危険は3層あり、危険の小さい順に目につく。1 だけ直して終わらせるな。

層	症状	本当の危険度
1. コードが当たらない	cherry-pick が競合する	低（気付ける）
2. 軸（語彙）が二重になる	PR が独自の設定軸を足しており、本流にも同じ目的の軸が既にある	最高（気付けない）
3. 文書の前提が古い	PR の README/手順書が、本流で反転した既定値を古い値で説明している	高（そのまま配ると嘘を配る）

層2 は competing な設定軸が2本並ぶので、axisA=旧値 かつ axisB=新値 という意味のない状態を作れてしまう。 競合もテスト失敗も起こさないため、レビューを通り抜けて後から必ず壊れる。

手順

1. 本流側の後発変更を数える（cherry-pick の前に必ず）

git fetch origin main
git log --oneline <PRのbase>..origin/main -- <PRが触るファイル>
git diff --stat <PRのbase> origin/main -- <PRが触るファイル>

• 後発コミットが数個以上／数百行なら cherry-pick は使わない。設計だけ採って手で移植へ切り替える。
• 判断材料として一度だけ cherry-pick を試し、競合ファイル数を見てすぐ --abort するのは有効。

2. 本流に既にある「軸」を先に探す

PR が足そうとしている設定の同義の軸が本流に無いか、名前空間ごとに grep する。

git grep -n "<機能名>\|MODE\|TARGET\|--set-" -- <対象ディレクトリ>

• 環境変数名 / CLI フラグ / 永続化 JSON のキー名 / ログに出る語 の4か所すべてを見る。
• 見つかったら、新しい選択肢は既存の軸の「3つ目の値」として入れる。新しい軸を作らない。
• PR 側の旧表記は捨てず、読むだけ受ける別名にして後方互換を保つ（旧フラグを新フラグのエイリアスにする）。 すでに旧表記を書き込んでしまった環境が存在しうるため。

3. 旧値の読み替えは「意味」ではなく「実害」で決める

PR の旧値を新しい軸のどこへ寄せるかは、辞書的な意味ではなくその値が引き起こした実害の記録で決める。

• 例: 旧値 window（= 別ウィンドウを開く）は、文字通りには「別プロセス経路」に対応する。 だが本流は「別ウィンドウが既存の作業と衝突する」という実害を理由に既定を反転していた。 → 文字通りの対応先へ復活させると、記録済みの実害へ戻る。反転後の既定側へ寄せるのが正しい。
• 判断根拠はコード内コメントや PR 本文に日付付きで残す（次に読む人が同じ判断を再現できるように）。

4. ゲート・前提条件の適用範囲を見直す

本流には、PR が知らないガードが増えていることが多い（多重起動防止、未処理状態の検出、クールダウン等）。 新しい経路に対して、そのガードがそもそも意味を持つかを1つずつ判定する。

• 意味を持つガード（有効/無効フラグ、無人実行の抑止、クールダウン）はそのまま効かせる。
• 新経路と無関係なガード（別経路の未処理状態など）はその経路でだけ無効化し、理由をコメントに書く。
• 併せて、新経路も状態の記録（最終実行の経路名など）を必ず書く。書かないと次回そのガードが誤診する。

5. 文書を「現在の事実」で書き直す

• PR の文書は構成と語り口だけ活かし、事実は全部取り直す。既定値・残る手作業・コマンド名を実物で確認する。
• 配布URLはブランチ参照（/main/ 等）のままにし、コミットハッシュで固定しない。 固定すると改修のたびに受け手へ「URLを貼り替えて」と手作業を強いる。
• 文書を配る前に、受け手が実際に踏むURLを取得して新機能の目印を grep する。

curl -s "<配布URL>" | grep -c "<新フラグ名>"

6. 実装をAIに委譲するなら、受け入れ前に diff を1ハンクずつ読む

「このテストを通せ」を合格条件として渡すと、テストを通すために既存の設計判断を壊すことがある。

実例: 「dry-run が計画を返すこと」を条件に渡したところ、実装AIは 「依存CLIが見つからない場合の早期スキップ」を dry-run の後ろへ移動させて条件を満たした。 その早期スキップは、本流が「依存解決の失敗に気付くための診断ログ」として意図的に置いていたもので、 テストは緑のまま診断能力だけが消えた。

• 受け入れレビューでは「依頼していない挙動変更が混ざっていないか」を専用に1周見る。
• 混ざっていたら戻す。テストが落ちるなら、テストの合格条件のほうを直す。

7. 検証（ここまでやって「移植できた」と言える）

• 全テストを流す（PRのテストではなく現行リポの全体）。
• 実プロセス・実入力での確認を1本は必ずやる。フックなら実際の stdin を流し込む:

echo '{"<イベントのJSON>"}' | node <script> --hook   # 1回目: 期待する出力
echo '{"<同じJSON>"}'     | node <script> --hook   # 2回目: 無出力（一度だけ発火する設計なら）
timeout 6 node <script> --hook < /dev/null          # stdin が来なくてもハングしないこと

• 副作用がある処理は、ホームディレクトリを環境変数で差し替えて隔離して検証する（実設定を壊さない）。
• 既定の挙動が変わっていないことを明示的に確認する（新機能はオプトインで入れる）。

8. 元PRへ敬意を払って閉じる

• 移植コミットに元作者を Co-Authored-By: で残す。
• 新PR本文に「元PRのどこを採り、なぜそのままでは入れられなかったか」を層1/2/3で書く。
• 新PRに Closes #<元PR番号> を入れる（squash マージで自動的に閉じる）。

完了条件（AIはここまで報告する）

1. 全テスト fail 0（件数を書く）
2. 実プロセス・実入力での確認結果（何を流して何が返ったか）
3. 既定の挙動が変わっていないことの確認
4. 配布URLの実測 grep 結果
5. 差し戻した「依頼外の変更」があればその内容

やってはいけないこと

• 競合を力技で解決して cherry-pick を完走させる（層2・層3 が丸ごと残る）
• 新しい設定軸を足す（既存の軸の値として入れる）
• PR本文の「検証済み」を再検証せずに信じる（その検証はPR提出時点の本流に対するもの）
• 共有リポで git stash を使う／他人の未コミット変更を巻き込んで commit する
• 移植の途中で競合状態を放置して離脱する（同じ作業ツリーを使う後続が全員詰まる）