放置された open PR を安全に棚卸しする（マージすべきか、クローズすべきかを機械的に判定する）

これは何のための指示書か

長く動いているリポジトリには、CI は緑なのに誰も処理しないまま数週間〜数ヶ月放置された PR が溜まる。 これを「とりあえずマージ」すると 現行仕様を過去の仕様へ巻き戻す事故が起きる。逆に全部閉じると、 まだ有効な修正を捨てる。

この指示書は、放置 PR を1件ずつ 「マージ / クローズ / 保留」に振り分ける手順を、 すべてコマンドの実測値に基づいて機械的に決める形にしたもの。 AI エージェントにそのまま実行させられる粒度で書いてある。

対象: GitHub リポジトリ（gh CLI が使えること）。言語・フレームワークは問わない。

---

大前提: 共有作業ツリーを絶対に触らない

棚卸しは必ず 使い捨ての worktree で行う。開発中の作業ツリーで git merge や git reset を試すと、 並行して動いている別のエージェント・別のセッションの未コミット変更を壊す。

git -C <repo> fetch origin --quiet
git -C <repo> worktree add --detach <一時ディレクトリ> origin/main

終わったら必ず片付ける:

git -C <repo> worktree remove --force <一時ディレクトリ>
git -C <repo> worktree prune

---

手順0: 一覧は「処理する直前に」取り直す

並行エージェントが同じリポジトリを触っている環境では、PR 一覧は数分で陳腐化する。 セッション冒頭に取った一覧を後の判断に使い回してはいけない。

gh pr list --repo <owner/repo> --state open --json number,title,mergeable,statusCheckRollup,updatedAt --limit 30

1件に着手する直前に、必ず単票でも確認する:

gh pr view <n> --repo <owner/repo> --json state,mergedAt,mergeable

失敗例: 一覧では open だった PR をマージしてみたら差分ゼロだったため 「他の変更に取り込まれた(superseded)」と結論してクローズ コメントを投稿した。 実際は その数十分前に別セッションがマージ済みで、差分ゼロはその結果だった。 差分ゼロは「superseded」と「マージ済み」の両方で起きる。必ず state / mergedAt を見る。

---

手順1: 「残差分ゼロ」を測る（＝もう main に入っているか）

各 PR を現在の main に実際にマージしてみて、マージ結果が main と何も変わらないなら、その PR に 新規性は残っていない。

for n in <PR番号...>; do
  git fetch origin pull/$n/head:pr$n -f -q
  git reset --hard origin/main -q
  if git merge --no-commit --no-ff pr$n >/dev/null 2>&1; then
    echo "PR#$n MERGE_OK 残差分=$(git diff --cached --name-status origin/main | wc -l)"
  else
    echo "PR#$n CONFLICT"
  fi
  git merge --abort 2>/dev/null; git reset --hard origin/main -q
done

判定:

結果	意味	処置
MERGE_OK 残差分=0	main に取り込み済み（または既にマージ済み）	クローズ（state を確認してから）
MERGE_OK 残差分>0	まだ有効な変更が残っている	手順3（検証してマージ）
CONFLICT	陳腐化している可能性が高い	手順2で陳腐度を測る

---

手順2: コンフリクトした PR の「陳腐度」を数字で出す

コンフリクトを解決する価値があるかを、感覚ではなく2つの数字で決める。

base=$(git merge-base origin/main pr$n)
# (a) base 以降に main が同じファイル群へ入れたコミット数
git rev-list --count $base..origin/main -- $(git diff --name-only $base pr$n | tr '\n' ' ')
# (b) 主要ファイルの行数比較（main の方が大きければ main が先へ進んでいる）
for f in $(git diff --name-only $base pr$n | head -5); do
  echo "$f  main=$(git show origin/main:$f | wc -l)行 / PR=$(git show pr$n:$f | wc -l)行"
done

(a) が数十コミット以上あり、かつ (b) で main の方が大きいなら、その PR は古いスナップショット。 コンフリクトを解いても得られる新規機能は無いのでクローズする。

さらに、追加しようとしているファイルが既に main に全部あるかも確認する:

for f in <PRが追加するファイル>; do
  git cat-file -e origin/main:$f 2>/dev/null && echo "✅ $f は既に main にある" || echo "❌ $f は main に無い"
done

---

手順3: 「マージすると退行する PR」を見抜く（最重要）

CI が緑でも、その PR の結論が後から覆されていればマージは退行になる。 ドキュメント・ルール・ポリシーを変更する PR で特に起きる。CI はルールの新旧を判定できない。

やること: PR が追加する主張を1つ取り出し、現在の main に反対の記述がないかを検索する。

# PR の追加行だけを取り出す
git diff $(git merge-base origin/main pr$n) pr$n -- <対象ファイル> | grep '^+' | grep -v '^+++' | sed 's/^+//'
# その主張に関するキーワードで、現在の main を検索する
git show origin/main:<対象ファイル> | grep -n "<主張のキーワード>"

判定の型（実例）:

PR の主張	main の現状	判定
「この操作だけは人間の承認を残す」	後日「その承認は廃止」と明記されていた	退行 → クローズ（根拠を引用してコメント）
「機能 X は全面禁止」	後日「条件付きで許可」へ改定されていた	退行 → クローズ
「手順 Y を追加」	同内容が要約されて別ファイルへ分離済み	取り込み済み → クローズ

ポイント: PR に複数の主張が含まれる場合、まだ有効な部分だけを現在の main の上に新しい PR として 作り直し、元の PR はそれを参照してクローズする。これが最も損失の少ない畳み方。

---

手順4: マージする場合の検証（read-back まで必須）

git reset --hard origin/main -q && git merge --no-edit pr$n     # コンフリクトなしを確認
<テストコマンド>                                                  # 全緑を確認（件数を記録）
gh pr merge <n> --repo <owner/repo> --squash --delete-branch

マージ後、マージした気になって終わらない。リモートの実ファイルを読んで反映を確認する:

git fetch origin --quiet
git log origin/main -1 --format='HEAD=%h %s'
git cat-file -e origin/main:<新規追加ファイル> && echo "✅ 実在"
git show origin/main:<変更ファイル> | grep -n "<入ったはずの文字列>"

gh pr merge が was already merged を返しても異常ではない（並行エージェントが先に処理しただけ）。 read-back で目的が達成されていれば成功として扱う。

---

手順5: クローズには必ず「数字の根拠」を残す

理由なしのクローズは、後から誰かが同じ PR を作り直す。コメントにはコマンド出力の実測値を書く。

テンプレート:

検証の結果、<マージ済み / 取り込み済み / 古いスナップショットで退行する> ためクローズします。

実測（使い捨て worktree・共有ツリーは未使用）:
- origin/main = <sha> に本PRをマージ → 残差分 <N> ファイル
- base <sha>(<日付>) 以降、同じファイル群に main へ <M> コミット
- 行数比較: <file> main=<X>行 / PR=<Y>行

<退行の場合> 本PRの結論「<主張>」は <日付> に <改定内容> へ変更済みです（main の該当行を引用）。

---

この手順が防ぐ失敗

1. 退行マージ: CI 緑を根拠にマージして、廃止済みのルールを復活させる
2. 共有ツリーの破壊: 開発中の作業ツリーで merge/reset を試し、他のエージェントの未コミット変更を消す
3. 陳腐化した一覧での誤判断: 数分前の一覧を信じて、マージ済み PR に「superseded」と誤ったコメントを残す
4. read-back 忘れ: gh pr merge の成功メッセージだけ見て、実際には反映されていない状態で完了報告する

適用の目安

• open PR が10件を超え、うち半分が2週間以上放置されている
• 複数のエージェント／人が同じリポジトリへ並行して PR を出している
• ルールやポリシーをドキュメントとしてリポジトリで管理している（＝退行の危険がある）