Implement Issue Tree

implement-issue-tree

親イシュー番号を指定し、配下のサブイシュー（孫含む）を依存順を保ちつつ worktree で並列に自動実装・ローカル diff レビュー・push + PR 作成・CI 監視・マージ可能状態化まで自動化する Workflow を起動する。squash merge は autoMerge: true + externalChecks 明示（全 App の信頼済み check context 宣言込み）の opt-in ランでのみクライアント側で実行する（references/automerge-design.md の「クライアント側自動マージの設計」節参照）。既定（autoMerge 未指定 / false）ではマージせず停止し、マージは GitHub 上で人間が行う。

CI リソース節約のため「push 前 review」設計を採用している。Implement フェーズではローカルブランチにコミットのみ積み、Review が全通過した後にはじめて push・PR 作成を行う。Review が収束失敗した場合は push も PR も作らないため、CI が一切起動しない。push（PR 作成時・Merge ループの fix 後の再 push）の直前には必ず base ブランチを取り込む（git fetch → git merge）。並列ラン（parallel >= 2）で兄弟イシューの PR が先にマージされていると、作成時点の base が既に古くコンフリクトしている場合があり、その状態のまま push すると GitHub は test merge commit を作れず pull_request トリガーの CI check-run が 1 件も発行されない（Issue #435）ため、push 前ゲートで解消を試みてから push する（解消不能なら push 自体を止める）。さらに push 直後（PR 作成時・fix の再 push 時）には、push した head にチェックが発行されたか（check-run の total_count + combined status の statuses 件数の合計。gh pr checks / merge-exec と同じ集計定義。commit status のみを発行する CI で 0 件と誤判定しないため。Issue #480）と mergeable を有界（30 秒間隔・最大 5 分）で確認し、checksStarted / mergeableAfterPush として返す（Issue #479。push 前ゲート通過後に兄弟 PR がマージされて base が動いたケースを、監視ラウンドを消費する前に捕捉する）。mergeableAfterPush: CONFLICTING を受けたホストは monitor を 1 ラウンドも起動せずに base 取り込み（baseMergeCount で有界）へ直行する。両値はエージェントの自己申告でありマージ判定には使わない（分岐ヒントと状態ファイルへの記録専用。_/issue-trees/<n>.json の pushChecksStarted / pushMergeable）。

末端の実装イシューは post-order DFS の順序を優先度として空きスロットへ貪欲投入し、最大 parallel（既定 3）件まで並列実行する。各 implement / fix は独立した git worktree で隔離実行されるため、並列でもブランチ・working copy が衝突しない。機能的依存（dependsOn）と親子関係（親は全子の完了を待つ verify-close）だけが待機条件となる。

前提条件

• gh CLI がインストールされ、認証済みであること（gh auth status で確認）
• jq CLI がインストールされていること（command -v jq で確認）。「全チェックが pass に見えるのにマージが進まない場合（cancel された run の残存 check）」節の人間の診断専用コマンド (B) は gh api --paginate --slurp の生 JSON を外部の jq へパイプして平坦化・集約するため、gh --jq だけでは代替できない。未導入の場合はそのコマンドを実行せず（rerun もせず）blocked として扱う
• awk CLI がインストールされていること（command -v awk で確認）。同節のエージェント実行可能コマンド (A) は --jq がページ単位にしか適用できないため、ページ跨ぎの重複を集約する際にシェル側 awk へ依存する。未導入の場合はそのコマンドを実行せず UNDETERMINED（判定不能）として扱う
• git working tree が clean であること（git status で確認）
• マージ先ブランチが CI green の状態であること（autoMerge 運用ではランの完了後にも確認する。後述の strict = false 前提により、古い base に対して成功したチェックのままマージされ得るため）。この確認はマージ先ブランチへの push で CI が起動することに依存する。push トリガの workflow が無い、または paths フィルタで該当 head では起動しないリポジトリでは前提確認・完了後確認のいずれも検証不能であり、autoMerge: true は非推奨とする。成立可否の確認手順（対象（マージ先）ブランチを検査するプローブ。branch 未指定時のみ既定ブランチへフォールバック）と不成立時の扱いは references/automerge-design.md の「補償策の成立確認（base CI プローブ）」節を参照
• （autoMerge: true で使う場合）ベースブランチの ruleset で required status checks の strict（マージ前の base 最新化必須 = strict_required_status_checks_policy）を false にしていること。true だと 1 件マージするたびに他の open PR の base が陳腐化し、並列ラン（parallel >= 2）が収束しない。G0 は strict を要件にしないため false でも自動マージは成立する（references/automerge-design.md の「strict を G0 の要件にしない理由」節）
• 対象リポジトリへの書き込み権限があること
• 親イシューと子イシューが GitHub の sub-issues API で紐付いていること（紐付けは create-issue / create-issue-tree を参照）

使い方

Workflow ツールで scriptPath にこのスキルディレクトリ内の scripts/implement-issue-tree.js を指定して起動する。パスは導入形態で異なり、後述の merge-guard hook のパスと同じ導入形態なら同じルート配下にある（js と hook は必ず同一のスキルディレクトリに同居する）。3 レイアウト:

• upstream skills/ レイアウト（本リポジトリ Fandhe-AI/agent-cli-skills のソース）: skills/implement-issue-tree/scripts/implement-issue-tree.js
• .agents/skills/ に vendored（npx skills add Fandhe-AI/agent-cli-skills で導入した downstream リポジトリ）: .agents/skills/implement-issue-tree/scripts/implement-issue-tree.js
• .claude/skills/ symlink 経由（本リポジトリが内部参照に使うレイアウト。実体は skills/ を指す symlink）: .claude/skills/implement-issue-tree/scripts/implement-issue-tree.js

{
  "scriptPath": "<このスキルディレクトリ>/scripts/implement-issue-tree.js",
  "args": {
    "parent": "<親イシュー番号>",
    "branch": "<マージ先ブランチ（省略時 main）>",
    "parallel": "<並列度 1〜8（省略時 3）>",
    "externalChecks": "<外部チェック App と信頼済み required check context の組の配列（例: [{\"app\": \"cursor\", \"context\": \"Cursor Bugbot\"}]。使用しない場合は []。slug 文字列のみの旧形式も受理するが、context 未宣言のためクライアント側自動マージは fail-closed で停止する）>",
    "autoMerge": "<boolean。true + externalChecks 明示（確定。全 App の信頼済み context 宣言込み）でクライアント側 squash merge を実行する（opt-in。references/automerge-design.md の「クライアント側自動マージの設計」節参照）。既定 false / externalChecks 未確定時はマージ可能状態で停止し、マージは GitHub 上で人間が行うか、サーバー側 auto-merge workflow（upstream の docs/implement-issue-tree/auto-merge-sample.yml）+ branch protection に委ねる>",
    "maxResidualWorktrees": "<残置 worktree 総数の上限（0 以上の整数。省略時 100、0 でこの軸のみ上限なし）>",
    "maxResidualWorktreeBytes": "<残置 worktree ディスク使用量の上限（バイト。0 以上の整数。省略時 53687091200 ＝ 50 GiB、0 でこの軸のみ上限なし。件数軸とは独立、Issue #348）>",
    "maxBaseMerges": "<PR が base とコンフリクト（mergeable: CONFLICTING）した際の自動 base 取り込みの回数上限（0〜10 の整数。省略時 3、0 で自動 base 取り込みを無効化しコンフリクトを即 blocked にする）。fixCount とは独立の予算軸（Issue #441）>",
    "repo": "<対象リポジトリの owner/repo（例: \"Fandhe-AI/agent-cli-skills\"）。base 取り込み（maxBaseMerges > 0）の worktree routing ガードが期待する owner/repo として使うホスト側明示宣言。未指定時は base 取り込みの自動起動が無効化され、コンフリクトは blocked+quality で終端する（PR #443 codex P0: エージェント自己申告値は信頼境界に使わない）>"
  }
}

例: 親イシュー #42 の配下を main へ、並列度 3・Cursor Bugbot 導入済みで実行する場合（マージ可能状態まで自動で進み、マージは GitHub 上で人間が行う）:

{
  "scriptPath": ".claude/skills/implement-issue-tree/scripts/implement-issue-tree.js",
  "args": { "parent": 42, "branch": "main", "parallel": 3, "externalChecks": [{"app": "cursor", "context": "Cursor Bugbot"}] }
}

引数

externalChecks の 4 状態（Issue #147 → 下流 sync PR codex P0 で context 束縛へ拡張）:

観測ベースの検出は直近 3 件の merged PR しか見ないため、新規導入 App・条件付き起動 App・直近 3 件で実行されなかった App を取りこぼす。「検出なし」が不在の証明にならないのはもちろん、「検出あり」も集合としての完全性を保証しない（例: 観測で sonarcloud だけを拾い、実際には必須の cursor を取りこぼしたまま「確定済み」として cursor[bot] レビューの再検証を省いてしまう）。したがって観測結果は確定情報として扱わず、参考値としてログ・停止理由・返却値に残すだけにする。externalChecks が配列でない・slug / context の形式不正（context は 1〜255 文字で、制御文字（改行・タブ等）と前後空白のみ不可。GitHub の context には文字種契約がないため文字種は制限せず、matrix 由来の build [ubuntu] や日本語を含む context もそのまま宣言できる — シェル / jq への埋め込み安全性は単一引用符リテラル + jq --arg の値渡しで保証する）・11 件以上の場合は既定値へフォールバックせずエラーで停止する（parallel は性能ノブのため不正値を既定 3 へ落とすが、externalChecks はマージゲートの入力であり、誤記を黙って「未指定」や「なし確定」に読み替えるとゲートが静かに弱まるため）。

自動マージのサーバー側委譲と merge-guard hook（deny 専用・best-effort）

クライアント側の自動マージは autoMerge: true + externalChecks 確定（全 App の信頼済み context 宣言込み）の opt-in ランでのみ実行する（次節「クライアント側自動マージの設計」参照。opt-out 既定では従来どおりマージしない。auto-merge の予約（arm）は引き続き提供しない）。merge-guard hook は deny 専用（承認境界ではなく、迂回可能な best-effort の攻撃面削減）。

詳細: references/automerge-design.md

クライアント側自動マージの設計（重要）

opt-in ランのクライアント側マージは、PR #182 / PR #222 codex P0（未信頼のレビュー本文を読む monitor の虚偽出力による未承認マージ誘導）に対して次の 3 層で対処する: monitor 出力のマージ経路からの分離・merge-exec の自己取得再検証・G0 サーバー側強制の実測（required checks の bypass 不能性に加え、レビュースレッド解消の必須化・合格判定対象チェック context の required 化（client-only チェックの不在）・外部チェック App の宣言 context + App ID 組束縛の required 化・required checks 全エントリの発行元 integration_id 束縛（同名 commit status 偽装の遮断 — issuer-unbound で辞退）まで確認し、共有 gh 認証のどのエージェントが直接マージを試みてもサーバーが同条件で拒否する構成を前提化）、の 3 層。

詳細: references/automerge-design.md

branch protection（マージ判定の本体。人間マージ・サーバー側 auto-merge の両運用で必要）

対象ベースブランチにはサーバー側 branch protection / ruleset を設定することを強く推奨する（ランタイムゲートではなく運用推奨）。compromised なローカルエージェントもサーバー側ルールは迂回できない。

詳細: references/automerge-design.md

フロー

Step 1: ツリーを取得して依存グラフ付き実行キューを構築する（Tree）

gh CLI の sub-issues API で親イシュー配下の全ツリーを再帰取得し、post-order DFS で実行キューを構築する。各 open イシューは本文を読んで機能的依存（dependsOn）を抽出する。

ツリー取得に続いて、直前 3 件の merged PR の check-runs から GitHub Actions 以外の外部チェック App（例: Cursor Bugbot）を観測する。観測結果は参考値であり構成の確定情報ではない。構成の確定は args.externalChecks の明示入力で行い、明示がない限り「確定不能」として後続の Merge ステップで自動マージを停止する（Issue #147）。

# 親イシューのサブイシューを取得（--paginate で 100 件超も全ページ自動取得）
gh api --paginate "repos/{owner}/{repo}/issues/<parent>/sub_issues?per_page=100"

# 各 open イシューの本文を読み、機能的依存を抽出
gh issue view <N>

# 外部チェック観測（直前 3 件の merged PR の check-runs を確認。結果は参考値）
REPO=$(gh repo view --json owner,name --jq '"\(.owner.login)/\(.name)"')
# SHA は位置引数 $1、REPO は位置引数 $2、jq フィルタは位置引数 $3 で渡す
# （REPO を子シェル内で "${REPO}" と展開すると非 export の変数は sh -c に渡らず空になり、
#  gh api が必ず失敗して常に apps: [] へフォールバックする）
gh pr list --state merged --limit 3 --json headRefOid --jq '.[].headRefOid' \
  | xargs -I{} sh -c 'gh api "repos/$2/commits/$1/check-runs" --jq "$3" 2>/dev/null' \
      _ {} "$REPO" '[.check_runs[] | select(.app.slug != "github-actions") | .app.slug] | .[]' \
  | sort -u

実行キューと依存グラフの構築ルール:

• 同一親内のサブイシューは sub_issues API 返却順（siblingIndex）で並べる
• 子イシューがすべて完了してから親イシューを処理する（親ノードは verify-close）
• closed 済みイシューは自動でスキップする
• dependsOn には「機能的に先行完了が必須」のイシュー番号のみを入れる（本文の明示的な依存記述・前提実装に限る。単なる関連やコンフリクトの可能性だけなら含めない）
• 祖先イシューへの dependsOn は無視する（親は子の完了を待つ側のため）
• 依存グラフに循環がある場合は DFS で検出し、循環を構成する非ツリー辺（dependsOn）を除去してデッドロックを防ぐ
• 依存ブロックは各周回で再判定する: 前提イシューの失敗・ブロックで下流が着手不能でも即座に確定せず保留し、halt（3 イシュー連続で完了できなかった場合の新規着手停止。Step 8 参照）発生前に限り、前提がラン中に外部完了（Issue CLOSED / PR MERGED）した場合は同一ラン内で下流を再判定して着手する。halt 後はプローブと状態記録（prereqTransitions・state 永続化）のみ継続し、新規着手は再開しない（halt はユーザー判断を待つ防御であり自動解除しない）。halt 後に記録された外部完了は次回ランの再実行で下流着手に反映される（Issue #442）

Step 2: 中断作業の回復可否を per-issue で判断する（Recover）

各末端イシューに着手する前に、残骸 worktree / ブランチが存在するかを確認する。既存作業がなければ Recover をスキップして Plan へ進む。既存作業がある場合は Recover phase（セッション継承モデルのエージェント）が「途中作業を継続できるか」を判断し、その結果に応じて以下のどちらかへ分岐する。

• continue（継続）: 既存 branch をそのまま checkout し、回復ブリーフ（done / remaining / broken の要約）を Implement へ渡して続きから実装する。Plan はスキップされる。Recover が直接 Review へ進むことはなく、継続作業は必ず Implement → Review → Merge を経由する。旧 worktree の削除は WIP 退避の完了が検証できた場合のみ実行する（後述の削除ゲート）。検証できない場合は残骸を削除せず failed で保全する（退避されていない未コミット変更を欠いたまま継続すると不完全な実装になるため、削除だけを飛ばして継続することはしない）。加えて、旧 worktree の掃除と implementing / reviewing 遷移の完了を状態更新の戻り値で確認できなかった場合も先へ進まず failed で保全する（旧 worktree が branch を掴んだままだと新 worktree が同一 branch を checkout できず、reviewing 未永続化のまま続行すると重複実装につながるため。discard 側の掃除完了確認と対）。
• discard（破棄）: 既存 worktree と branch を削除し、通常の Plan → Implement（新規 branch）で再実行する。削除は WIP 退避の完了が検証できた場合のみ実行する（後述の削除ゲート）。検証できない場合は残骸を削除せず failed で保全し、次回ランの Recover に委ねる。加えて、worktree / branch の掃除完了を状態更新の戻り値で確認できなかった場合も Plan へ進まず failed で保全する（branch 残存下で再 Plan すると git checkout -B が WIP commit を orphan 化するため）。

Recover の判断軸は Review とは別である。Review は「実装が正しいか・マージできるか」を判定するのに対し、Recover は「この途中作業から継続するのが妥当か」を判断する。動かない・未完成でも方向が妥当なら continue（残りは Implement が完成させる）。

未 commit 変更は WIP commit として branch へ退避してから worktree を削除するため、continue / discard どちらの経路でもデータを失わない。discard の場合は WIP commit を残した状態で branch を削除するため、誤判定時に reflog から救出できる。

削除ゲート（continue / discard 共通）: Recover エージェントの返す wipCommitted は自己申告値であり、誤判定・異常応答・プロンプトインジェクションで真を騙られ得る。加えて Recover は「フック失敗等で退避できなかった場合は wipCommitted: false を返して続行する」契約のため、continue も退避失敗時に返り得る。そのため continue / discard いずれの経路でも worktree の削除は次の 2 条件を両方満たす場合にのみ実行する。

1. 申告ゲート: Recover エージェントが wipCommitted: true を返している（退避した場合、および退避すべき未 commit 変更が最初から無かった場合に true。フック失敗等で退避できなかった場合は false）
2. 事実ゲート: ホストが起動する読み取り専用の安全確認エージェントが、対象 worktree に未 commit 変更が残っていないこと（git status --porcelain の出力が空であること）を確認できている

どちらか一方でも満たさない場合、あるいは安全確認自体が失敗した場合は worktree / branch を削除せず failed で保全する（fail-safe）。保全された残骸は次回ランの Recover が再度判断する。worktree が無い branch のみの残骸は削除対象も未 commit 変更も存在しないため、このゲートの対象外とする。

Step 3: イシューごとに実装計画を立案する（Plan）

各 末端イシューを実装する前に、セッション継承モデルのエージェントで実装計画を立案する（worktree なし・読み取りのみ）。計画は Implement エージェントへ引数で渡す（worktree 跨ぎのファイル参照を避けるため）。

Recover phase で continue 判定が出た場合は Plan をスキップし、回復ブリーフを受け取った Implement エージェントが既存 branch から直接実装を続行する。

計画には以下を含める:

• 背景・目的（イシューが解決する課題）
• 対象ファイル・変更箇所（パスと変更内容の概要）
• 実装ステップ（順番に実行可能な具体的手順）
• 検証方法（ビルド・lint・テスト・動作確認の手順）
• OWASP Top 10 観点のセキュリティ考慮事項

計画エージェントが異常終了または計画本文が空の場合は、該当イシューを failed として記録して次へ進む。

Step 4: 末端イシューを worktree 隔離で並列実装する（Implement）

末端の実装イシューを post-order DFS 順を優先度として空きスロットへ貪欲投入し、最大 parallel（既定 3）件まで並列実行する。各 implement / fix エージェントは独立した git worktree で隔離実行されるため、並列でもブランチ・working copy が衝突しない。

ここでは push も PR 作成も行わない。CI リソース節約のため、Review 通過後にまとめて 1 回だけ push・PR 作成する設計になっている。

各イシューの処理内容（Step 3 で立案した計画に従って実装する）: 0. worktree routing ガード（最初に実行）: git remote get-url origin とイシュータイトル照合でカレント worktree が正しいリポ・イシューに配置されているか確認する 0b. 既存 PR・リモートブランチを確認する（中断再開・重複 PR 防止）:

• 0b-a（open PR 検索）: gh pr list --state open でイシュー番号に対応する open PR が既に存在するか確認する。見つかれば新規 PR を作らずそのブランチを取得して続きから作業し、そのブランチ名を返す（PR 番号は返さない。同じブランチの open PR は後続の PR Create フェーズが再検出して再利用する）。手順 2 のブランチ作成はスキップする（origin/<base> から checkout -B し直すとその PR のコミットを失うため）
• 0b-b（リモートブランチ再利用）: open PR が見つからない場合、git ls-remote --heads origin でイシュー番号を含むリモートブランチ（命名規約: <type>/<N>-<short-name>）が残っていないか確認する。「push 成功・PR 作成失敗」で残ったブランチを検出し、git fetch origin <branch> && git checkout -B <branch> origin/<branch> で取得して push 済みコミットを保持したまま続きを実装する（origin/<base> から新規作成し直さない）。branch 名として返し、prNumber は 0 のまま（PR は後続の PR Create フェーズが作成）
• 0b-c: open PR もリモートブランチも存在しない場合のみ手順 1・2 で新規ブランチを作成する

1. 隔離 worktree で git status が clean か確認し、差分があれば作業せず失敗を返す

2. （0b-a で既存 open PR のブランチを取得した場合・0b-b でリモートブランチを再利用した場合はスキップ）指定ブランチ（デフォルト: main）から作業ブランチを作成する（並列時のブランチ名衝突を防ぐためブランチ名にイシュー番号を含める）

3. 渡された計画に従って実装する（計画立案は Plan フェーズで完了済み）。実装は対象リポジトリの delegation ルール・専門サブエージェントがあればそれに従い役割単位で委譲する

   コメント方針（実装時）:

   • コードコメントは「何をするか」より「なぜ存在するか／パッケージ・サービスから見た対象の役割」を書く
   • 後続の読み手（Claude を含む）は渡された情報からしか判断できないため、他ファイル・他サービス・呼び出し元/呼び出し先からの観点を明示する（このシンボルがどこから呼ばれ、どの境界を担うか）
   • 対象リポジトリに .claude/rules/code-comment-style.md（init-claude が配備）が存在する場合はそちらの詳細規約に従う。存在しない場合は上記の要点に従う

4. 対象リポジトリの CLAUDE.md・rules・テスト実行規約に従いビルド・lint・テストを通す。テストが失敗した場合は根本原因を調査してから修正する（対象リポジトリに .claude/rules/debugging.md が存在する場合はその4フェーズを順に踏む。存在しない場合も同じ方針〔調査→分析→仮説→修正〕を踏む。同一箇所で3回失敗したらアーキテクチャ問題と判断し、該当イシューを blocked として記録してユーザーに状況を報告する）

5. 実装後に OWASP Top 10 観点でセキュリティチェックを実施する（API キーのハードコード・インジェクション等）。問題が見つかった場合は修正してから次へ進む

6. 実装が完了したら create-commit スキルに従い Conventional Commits で実装コミットを 1 つ作成する。 コミット前に対象リポの commitlint 設定（commitlint.config.* / .commitlintrc* / package.json の commitlint フィールド）を読み取って type-enum / scope-enum を確認し、許可された値のみを使う。 該当する scope が無ければ scope ごと省略する（feat: 実装内容）。scope にイシュー番号を置かない （scope-enum を設定したリポでは必ず落ち、Review 3 巡を消費した後の push で初めて検出される）。 イシューとの紐付けは footer の Refs #<N> と PR 本文の Closes #<N> で行う。 push 前 base 最新化ゲート（Step 5・Merge ループの fix）で作る base 取り込みマージコミットの subject も同じ手順で type / scope を決める（固定の chore: は type-enum / scope-enum を持つリポの commit-msg hook に拒否される。拒否されたら git merge --abort して push せず fail-closed）

7. push・PR 作成はここでは行わない。ローカルブランチにコミットを積んだ状態で終了し、後続の Review フェーズへ渡す

# 作業ブランチ作成例（並列時の衝突回避のためイシュー番号を含める）
git fetch origin && git checkout -B feat/<N>-<short-name> origin/<base-branch>

# 実装コミット（push しない）
# scope はイシュー番号ではなく変更対象のモジュール・ディレクトリ名。
# 対象リポの commitlint の scope-enum に該当する値が無ければ scope ごと省略する。
git commit -m "$(cat <<'EOF'
feat(<module>): 実装内容

Refs #<N>
EOF
)"
# → push・PR 作成は Review 全通過後に行う

Step 5: push 前のローカル diff を独立レビューする（Review）

Implement 完了後・push 前に、worktree 隔離で独立 Review エージェントを起動してローカル diff をレビューする。push・PR 作成は行わず、ローカルコミットだけを対象にレビューする。Review エージェントは修正を行わず判定のみを担う。

CI リソース節約の目的: Review が収束失敗した場合は push も PR 作成も行わないため、CI が一切起動しない。fix のたびに push → CI 実行を繰り返すコストを削減する。

レビューは以下の2段階で実施する。

①仕様準拠レビュー（先に実施）:

• イシューの要件・受け入れ条件を充足しているか確認する
• out-of-scope の実装が混入していないか確認する
• Plan フェーズの計画どおりに実装されているか確認する

②コード品質レビュー（①通過後に実施）:

• 可読性・重複・設計（アーキテクチャ準拠・命名規則）を確認する
• OWASP Top 10 セキュリティ（API キーのハードコード・インジェクション・認証認可等）を確認する

詳細は implement-review スキルを参照。

レビュー条件:

• git checkout --detach <branch> でローカルブランチを detached HEAD として取得する（origin/<branch> は push 前のため存在しない）
• レビュー直前に git fetch origin <base-branch>:refs/remotes/origin/<base-branch> を 必ず 1 回実行して比較基準を最新化する（ref の存在有無で分岐しない）。保存先を明示した refspec を使う — git fetch origin <base-branch> のように取得元だけを与えた形は FETCH_HEAD を更新するだけで refs/remotes/origin/<base-branch> の作成・更新を保証せず、fetch 成功後の解決に失敗して実施可能なレビューを blocked で落とす（Issue #361）
• git diff origin/<base-branch>...HEAD でローカル diff を確認する（origin/<base-branch>（直前に取得し直した remote-tracking ref）が比較基準。3 点ドットのため比較点は merge-base(origin/<base-branch>, HEAD) ＝ブランチの分岐点に固定され、以降ラン中に origin が進んでも比較点は不変。既存 ref があっても古ければ merge-base が実際の分岐点より手前に落ち、base 側の無関係なコミットが差分へ混入するため「ref があること」を新しさの根拠にしない。fetch に失敗した場合、および fetch 後も解決できない場合はレビューを実施せず state: "blocked" / highestSeverity: "none" で fail-closed 終端する。blocked は環境要因でレビュー自体が実施不能だったことを表す専用状態で、コード指摘を表す needs-fix とは呼び出し元の扱いが異なり fix エージェントを起動せず即座に終端する — needs-fix / critical は使わない。無関係なコードへの修正試行で修正予算を消費させないため）
• Low（要改善）含む指摘が 1 件でも needs-fix。指摘なしなら ok

ok の場合は push + PR 作成（Step 4.5）を経て Merge ステップへ進む。needs-fix の場合は fix エージェントでローカルに再コミットし再レビューする（push しない）。Review は最大 3 回実施し、最終回（残り 0 回）の needs-fix では再レビューできないため fix を行わず収束失敗とする（修正後に必ず再レビューする原則を守るため。fix は実質最大 2 回）。3 回で収束しない場合はpush も PR 作成も行わず blocked として記録して次のイシューへ進む。この blocked は残置 worktree・branch・最終指摘をレポートへ集約し（Issue #442。references/report-format.md 参照）、再実行時は Recover（継続/破棄）→ 通常 Implement 経路から再着手する（pr: 0 のため monitoring 再開ではない。詳細は references/recovery.md）。

依存ブロックの再判定について: 下流イシューが前提イシューの blocked（本節の Review 非収束等）で連鎖ブロックされても、スケジューラは各周回で保留状態を維持し、halt 発生前に限り、前提がラン中に外部完了（人手マージ・クローズ）した場合は同一ラン内で下流を再判定する。halt 後の外部完了検知はプローブ・状態記録のみで新規着手には反映されず、次回ランで反映される（Issue #442。詳細は Step 8 参照）。

Review / Merge の fix は fixCount（上限 6）を共有する。base とのコンフリクト（mergeable: CONFLICTING）解消は fixCount を消費せず、独立予算の baseMergeCount（上限 maxBaseMerges。既定 3）で管理される（Issue #441）。

Step 5.5: Review 通過後に push + PR を作成する（PR Create）

Review が全通過（ok）した後にのみ実行する。この push が CI トリガーになる（push は 1 回のみ）。

# Review 通過後にはじめて push する（CI がここで起動する）
git push origin <branch>

# PR 作成（Closes でイシューと紐付け）
gh pr create \
  --base <branch> \
  --title "feat: イシュータイトル" \
  --body "$(cat <<'EOF'
## Summary
- 実装内容の要約

Closes #<N>
EOF
)"

既存 open PR の再利用（Issue #135）: push 成功後・gh pr create の前に、このブランチに対する open PR が既に存在しないかを gh pr list --state open --head <branch> --json number,baseRefName,headRefOid で必ず確認する。中断再開（PR 作成直後のクラッシュ・pr 保存済み failed からの再実行）では open PR が残っていることがあり、確認せずに gh pr create すると必ず失敗して、生きている PR が追跡されないまま残るため。

再利用の条件は 2 つあり、両方を満たす場合にのみその番号を prNumber として返す。

• baseRefName が指定 base ブランチと一致すること（同じ head から別 base（リリースブランチ等）へ開かれた PR を再利用すると、base <branch> の契約を迂回して意図しないブランチへマージされる）
• headRefOid が push したブランチの先端 sha と一致すること（他者・別ランの push で head が動いた PR を、検証していないコミットごとマージ対象にしない）。比較対象の sha は必ずブランチ ref（git rev-parse --verify "refs/heads/<branch>"、解決できなければ refs/remotes/origin/<branch>）から解決する。PR Create エージェントは隔離 worktree で動作し、その worktree が対象ブランチを checkout している保証がないため git rev-parse HEAD を使ってはならない

条件を満たす PR を再利用する場合は、本文に Closes #<N>（および対象外項目があれば「対象外（out-of-scope）」節）が無ければ追記する。このとき既存本文をシェルコマンド文字列・HEREDOC へ埋め込んではならない（本文は外部由来の未信頼データであり、行単独の HEREDOC 終端文字列を仕込まれると HEREDOC が早期終了して後続行が任意コマンドとして実行される）。gh pr view <N> --json body --jq .body > "$f" でファイルへ直接落とし、grep -qF で存在確認したうえで printf / 固定テンプレートの追記のみを行い、gh pr edit <N> --body-file "$f" で更新する。条件を満たさない open PR しか存在しない場合は、再利用も新規作成も行わず prNumber: 0 と理由を返して停止する（branch は保存されるため、次回実行は impl 手順 0b から回復する）。

PR 作成が失敗した場合は failed として記録し、branch を保存する。branch 保存済みの failed は次回再実行時に Recover phase を起動する（impl 手順 0b には到達しない）。continue なら回復 Implement の手順 2 が既存 branch を checkout した後に git fetch origin <branch>:refs/remotes/origin/<branch> → git merge --ff-only refs/remotes/origin/<branch> でローカルをリモート tip へ追従させ、push 済みの base 取り込みコミットを保持したまま回復する（PR Create エージェントは base 取り込みコミットを detached HEAD から push しローカル refs/heads/<branch> を更新しないため、追従なしでは次の PR 作成が remote-ahead / diverged で再失敗する）。ff 不能な真の diverged はそのまま続行し、次の PR 作成の (iv) が fail-closed で止める。

Step 6: CI / 外部チェック監視・レビューコメント解決確認・squash merge する（Merge）

gh pr checks --watch で CI を監視し、以下の全条件を満たした場合のみ squash merge する。

クライアント側の自動マージは opt-in ランでのみ実行する（references/automerge-design.md の「クライアント側自動マージの設計」節参照）: autoMerge: true + externalChecks 確定（全 App の信頼済み context 宣言込み）のランでは、monitor の ready 判定後に merge-exec が HEAD sha を自己取得・固定したうえで全条件（checks・未解決スレッド数・外部チェック起動・G0 = ベースブランチのサーバー側強制の実測: required checks の bypass 不能性（ruleset の bypass_actors 空。classic branch protection のみのリポジトリは非対応として classic-unsupported で辞退）・レビュースレッド解消の必須化・合格判定対象チェック context の required 化（client-only チェックの不在）・外部チェック App の宣言 context + App ID 組束縛の required 化・required checks 全エントリの発行元 integration_id 束縛（同名 commit status 偽装の遮断 — issuer-unbound で辞退））を独立再検証し、gh pr merge --squash --delete-branch --match-head-commit <自己取得 sha> で squash merge を実行、さらに merge-verify の独立確認（state=MERGED + merge-exec 申告 sha との完全一致）を通過した場合のみ merged 終端する。monitor の出力（ready / headSha）はマージ経路の入力に使われない（ready は起動タイミングのみ。PR #222 codex P0 対応）。G0 を確認できないリポジトリでは server-enforcement-missing（classic branch protection のみのリポジトリは classic-unsupported）で blocked 終端する（fail-closed。ruleset ベースの branch protection を構成して再実行すれば継続する）。opt-out（既定 false）・externalChecks 未確定・信頼済み context 未宣言（slug のみの旧形式）のランでは従来どおり新規マージを実行せず、PR をマージ可能状態のまま blocked（blockedReason: quality）+ pr 保持で終端する。opt-out 時は monitor が ready（虚偽含む）を返しても merge-exec は gh pr merge を含まない回復専用経路に固定される（既存 Issue #168 機構。recoveryOnly。opt-in 判定はホストの決定的コード = args パースのみ。モデル出力・未信頼テキストに依存しない）。マージ済み PR のクローズ回復（already-merged 経路）は両モードで通る。この経路は「前回ランでマージ済みだが状態記録に失敗した PR」に加えて、サーバー側 auto-merge workflow（upstream の docs/implement-issue-tree/auto-merge-sample.yml）が監視中に PR をマージした場合も同様にカバーし、いずれも正常完了（merged）として終端する。blocked + pr は次回ランの monitoring 再開対象で、マージは GitHub 上で人間が行うか、サーバー側 auto-merge workflow + branch protection に委ねる（references/automerge-design.md の「自動マージのサーバー側委譲と merge-guard hook」節参照）。

クライアント側自動マージの経緯と現契約: 当初は host が発行する grant（正規マージコマンド全文 = expectedCommand）を merge-guard hook が完全一致照合する allow 経路で承認境界を作ろうとした。しかし monitor は未信頼のレビュー本文を読みつつ merge-exec と同じ Bash・gh 認証・FS を共有し、gh pr view で HEAD を取得して任意 nonce の grant を自作できる（grant 偽造 P0）。hook 専用の秘密注入経路がなく、hook が検証でき subagent が読めない鍵を持てないため署名 / MAC も実装不能で、偽造不能なマージ認可を hook で実装することは原理的に不可能。その後 PR #206 のクライアント側 arm（agent precheck + hook carve-out）も、carve-out が認可と結び付かず任意 subagent に arm を開放し（codex P0）、precheck が agent 自己申告で捏造可能（codex P0）、--auto の即時マージで「予約のみ」前提が虚偽（Bugbot High）と確認され撤回した。この時点では Codex 元指摘（rust-ai-library PR #441）の「境界を実装できるまで自動マージ無効化」に従い、grant / canary / branch-protection ランタイムゲートと precheck / arm / carve-out をすべて撤去し、hook を deny 専用（best-effort・承認境界ではない）とし、クライアント側の自動マージ経路をいったん閉じた。現契約（2026-08-12 の opt-in 再有効化以降）: 既定（autoMerge 未指定 / false）は従来どおり新規マージを行わずマージ可能状態の blocked で停止する。autoMerge: true + externalChecks 明示（全 App の信頼済み context 宣言込み）の opt-in ランに限り、monitor 出力のマージ経路からの分離・merge-exec の自己取得再検証・G0（サーバー側強制の実測。確認できなければ server-enforcement-missing で fail-closed 辞退）・--match-head-commit・merge-verify の独立確認を前提としてクライアント側 squash merge を実行する（本 Step 冒頭の opt-in 説明と references/automerge-design.md「クライアント側自動マージの設計」節参照。残存リスクとその受容記録も同節にある）。grant / canary / precheck / arm / hook carve-out は再有効化後も復活していない。正規経路の外（注入に従った monitor 自身の gh pr merge 直接実行・REST / GraphQL merge・approve・alias / extension）は merge-guard hook が best-effort で deny するが、これは迂回可能な多層防御の一層にすぎない。実際にマージを止めるのは opt-out 既定の fail-closed（host が opt-in なしに新規マージ経路を開かない）と、サーバ側 branch protection（第三者=非 author 承認必須・dismiss stale・通常/force push 禁止・required checks。references/automerge-design.md の「自動マージのサーバー側委譲と merge-guard hook」節参照）であり、opt-in ランでも G0 が同条件のサーバー側強制を実測確認できない限りマージしない。opt-in を使わない auto-merge は同節のサーバー側 workflow（upstream の docs/implement-issue-tree/auto-merge-sample.yml）へ委譲する。

監視とマージ実行の分離（Issue #145）・merged 自己申告の独立確認（Issue #160）: このステップは監視・マージ実行・独立確認の 3 つのエージェントに分かれる。実行基盤がエージェント単位のツール権限制御を提供しないため、これは権限の剥奪ではなくコンテキスト分離（未信頼テキストをマージ実行主体へ入れない）である。残存リスクと必要な基盤対応は「非信頼データの扱い」項目 5 を参照。

• 監視エージェント（monitor）: CI・外部チェック・レビュースレッドを確認し、state（ready / needs-fix / unresolved-comments / timeout / blocked）と headSha（40 桁）を返す助言的判定のみを行う。PR レビュー本文という未信頼データを読むため、gh pr merge / gh issue close / gh pr edit / resolve mutation の実行権限を持たない。
• マージ実行エージェント（merge-exec）: 監視が ready を返したときにホストが起動する。レビュー本文・Issue 本文・チェック名を一切読まず、リポジトリ内ファイル（CLAUDE.md・.claude/rules 等 = PR 側で変更可能な未信頼テキスト）も読まない（実装系エージェント向けの共通指示 COMMON を挿入せず、merge-verify と同一の最小指示で構成する）。PR の state / headRefOid / mergeable（enum・sha）、チェックの状態別件数（gh pr checks <N> --json state --jq '[.[].state] | group_by(.) | map({state: .[0], count: length})'。素の gh pr checks や --json name / description / link は使わない）、未解決レビュースレッドの件数のみ（GraphQL から comments を外して body を取得しない）、および args.externalChecks で確定した外部チェック App について HEAD sha に対する件数と状態 enum のみ（--jq で正規化。App 名・チェック名・body 等のテキストは取得しない）を自ら再取得して検証し、さらに G0 ゲート（ベースブランチのサーバー側強制の実測: required checks の bypass 不能性（ruleset の bypass_actors 空。classic branch protection のみのリポジトリは bypass 不能性を write トークンから証明できないため非対応 — classic-unsupported で辞退）・レビュースレッド解消の必須化・合格判定対象チェック context の required 化（HEAD sha 上の check-run / commit status のうち required に含まれないものが 0 件であることを jq の集合差の件数のみで照合。context 文字列は取得しない）・外部チェック App の宣言 context + App ID 組（context + integration_id）束縛の required 化 + required checks 全エントリの発行元 integration_id 束縛（HEAD の check-run の .app.id と一致することの件数照合。同名 commit status 偽装の遮断 — 検証できなければ issuer-unbound で辞退）。件数・真偽値のみの API 出力で確認し、確認できなければ server-enforcement-missing で辞退）を通過した場合にのみ squash merge とイシュークローズを実行する。HEAD sha は自身の gh pr view 観測から取得・固定し（monitor から受け取らない。PR #222 codex P0 対応）、マージは gh pr merge <N> --squash --delete-branch --match-head-commit <自己取得 sha> で実行して、照合とマージの間に push される競合（TOCTOU）を GitHub 側の条件評価で塞ぐ。
  • チェック名を除外するのは、名称が PR 側の workflow / job / matrix 定義から生成される外部由来テキストであり、マージ権限を持つ実行主体のコンテキストへ命令文を持ち込む経路になるため（PR #150 codex-review P0 対応）。外部チェックの件数（非負整数）と .conclusion / .status の状態 enum は任意テキストを注入できる媒体ではないため、この理由づけの対象外として --jq 正規化つきの取得のみを許可する（Issue #146 / #155）。App の絞り込みは、args 入力時に slug 形式（英小文字・数字・ハイフン、39 文字以内）へ検証済みの値との app.slug 一致で行い、App 名・description・output はコンテキストへ入れない。
  • 外部チェックの再検証を監視エージェント側だけに置かないのは、未信頼テキストを読む監視の判定は「マージを試みてよい」という起動条件にすぎず、ゲートの証拠にできないため。
  • 監視の headSha はマージ経路の入力に使われない（診断用の記録のみ。PR #222 codex P0 対応。マージ判定用の HEAD sha は merge-exec が自己取得・固定する）。opt-out・外部チェック構成が未確定のラン（externalChecks 未指定）・信頼済み context 未宣言のラン（slug のみの旧形式）では merge-exec は回復専用経路（allowMerge=false）で起動し、新規マージは行わず「PR が既に MERGED ならイシュークローズ確認のみ」に限定される（前回ランでマージ済み・状態記録に失敗した PR の回復パスを保ちつつ fail-closed を維持する）。この限定はプロンプト解釈に任せず、マージ実行手順の文面もホスト側で分岐し、回復専用経路のプロンプトには gh pr merge / --match-head-commit を一切含めずイシュークローズ確認のみを出力する（Issue #161 / #168）。
  • マージ成功でもイシューのクローズを確認できない場合（issueClosed: false）は merged として終端せず再監視でクローズを再試行し、監視回数を使い切った場合は「PR はマージ済みだがクローズ未確認」として blocked で終端する（次回実行の monitoring 再開で回復する）。
• 独立確認エージェント（merge-verify、Issue #160）: merge-exec が merged: true を返しても、ホストはそれを未検証のモデル出力として扱い無条件受理しない。merged: true は reason が merged / already-merged と整合する場合のみ受理候補とし（不整合・enum 外は systemic failure として failed 終端・halt カウント対象）、さらに merge-exec とは別コンテキストの読み取り専用エージェントが gh pr view <N> --json state,headRefOid,mergeCommit の取得値のみを返し、ホストが state の完全一致（MERGED）と監視時点 HEAD sha との一致（sanitizeSha 通過値。前回ランでマージ済み・headSha 未記録の already-merged 回復経路では比較対象がないため state のみ）を厳密再検証する。裏付けられない場合（state 不一致・HEAD 不一致・取得不能・無効応答）は fail-closed で blocked（blockedReason: quality）で終端し、worktree 削除・dependsOn 後続イシューの解放は行わない。blocked + pr は次回ランの monitoring 再開対象のため、実際にマージ済みなら already-merged 経路で自然回復する。返却 schema は自由文フィールドを持たず、確認エージェントはレビュー本文・Issue 本文・コメント・チェック名を一切読まない（ホストのログ・note には enum 完全一致・sanitizeSha 通過済みの検証値のみを合成する）。
  • 辞退理由（reason）はホスト側で head-moved / checks-not-green（許容外 state の存在に加え、チェック総数 0 件・gh pr checks 非ゼロ終了の fail-closed 辞退を含む。Issue #159） / merge-failed → 再監視、unresolved-threads → fix ループ（ただし手元にスレッド内容の構造化一覧がない場合は fix を起動せず再監視し、監視エージェントに内容を収集させる）、not-mergeable（コンフリクト等） → conflicting（base 取り込み専用エージェントへ回す。fixCount を消費しない独立予算 baseMergeCount。Issue #441）、wrong-target（base 不一致・draft。fix では解消しないため fix 予算を消費しない） → blocked、pr-closed → blocked、external-review-missing → bloc

…(truncated)