# Implement Issue Tree

> 親イシュー配下のサブイシュー（孫含む）を依存順を保ちつつ worktree で並列に自動実装・push 前 review・PR 作成・CI 監視・マージ可能状態化まで一括自動化。 「イシューツリーを並列実装」「配下のサブイシューをまとめて実装」「ツリー全体を並列で実装して」「イシュー階層を自動開発」で使用。 per-issue 計画立案（Plan: セッション継承モデル）→実装（Implement: sonnet）の分業。push 前 review（Review 通過後にのみ push・PR 作成して CI を 1 回だけ起動）。 外部チェック構成は args の externalChecks で明示（{"app", "context"} の組で宣言。[] で「なし」を確定して不要待機なし・未指定なら自動マージ停止・slug のみの旧形式は自動マージ fail-closed）。 自動 squash merge は autoMerge: true + externalChecks 明示（全 App の信頼済み context 宣言込み）の opt-in で実行（merge-exec の自己取得再検証 + サーバー側 branch protection 実測が前提。既定 false はマージ可能状態で停止し人間がマージ。サーバー側 workflow サンプル（upstream の docs/implement-issue-tree/auto-merge-sample.yml 参照）+ branch protection への委譲も可）。並列度（parallel）と依存（dependsOn）で実行順を制御。 単一イシューの実装は implement-issue、PR レビューは implement-review-pr を参照。

- Skill: `fandhe-ai-agent-reference-skil/implement-issue-tree-2` (Agent Skill, multi-file: 30 files)
- Install (CLI): `npx skillmds@latest add fandhe-ai-agent-reference-skil/implement-issue-tree-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fandhe-ai-agent-reference-skil/implement-issue-tree-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: fandhe-ai (https://skillmd.com/u/fandhe-ai-agent-reference-skil)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/fandhe-ai-agent-reference-skil/implement-issue-tree-2

---


# 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`

```json
{
  "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 上で人間が行う）:

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

### 引数

| 引数 | 必須 | 既定 | 説明 |
|------|------|------|------|
| `parent` | 必須 | — | 親（ルート）イシュー番号。`issue` でも可 |
| `branch` | 任意 | `main` | マージ先ブランチ。不正な文字を含む場合はエラー |
| `parallel` | 任意 | `3` | 並列実行数（1〜8）。`1` を指定すると実質的に直列実行になる |
| `externalChecks` | 任意 | 未指定 | GitHub Actions 以外の外部チェック宣言の配列（最大 10 件）。要素は `{"app": "<slug>", "context": "<required check context>"}` の組で宣言する（slug は英小文字・数字・ハイフン。複数 context は `contexts` 配列。slug 文字列のみの旧形式も受理するが context 未宣言としてクライアント側自動マージは fail-closed で停止する）。**未指定と `[]` は意味が異なる** |
| `autoMerge` | 任意 | `false` | **`true` + `externalChecks` 明示（確定。全 App の信頼済み context 宣言込み）の opt-in ランでクライアント側 squash merge を実行する**（references/automerge-design.md の「クライアント側自動マージの設計」節参照。マージは merge-exec の自己取得再検証（HEAD sha・checks・スレッド・外部チェック）+ G0（ベースブランチのサーバー側強制の実測 = required status checks の bypass 不能性（ruleset は `bypass_actors` 空。classic branch protection のみのリポジトリは非対応 — bypass 不能性の検証に必要な protection 読取が admin 権限を要求し write トークンで証明できないため `classic-unsupported` で辞退）+ strict 適用（マージ前の base 最新化必須）+ レビュースレッド解消の必須化 + 手順 3 の合格判定対象チェック context の required 化（client-only チェックの不在）+ 外部チェック App の宣言 context + App ID 組（`context` + `integration_id`）束縛の required 化 + required checks 全エントリの発行元 `integration_id` 束縛（同名 commit status 偽装の遮断。検証できなければ `issuer-unbound`）。確認できなければ `server-enforcement-missing` で `blocked` 終端）+ `--match-head-commit` + merge-verify の独立確認を経る。monitor の出力はマージ経路の入力に使われない）。既定 `false`・`externalChecks` 未確定時・信頼済み context 未宣言時（slug のみの旧形式）は従来どおりマージせず、PR はマージ可能状態の `blocked` で停止する（実装・push 前 Review・PR 作成・CI 監視・fix ループは値によらず自動で進む）。opt-in を使わない場合、auto-merge はサーバー側 workflow（upstream の `docs/implement-issue-tree/auto-merge-sample.yml`）+ branch protection への委譲、または GitHub 上での人間マージで行う（対象ブランチに branch protection を設定することを推奨）。注意: merge-guard hook 導入リポでは subagent の `gh pr merge` が deny されるため opt-in マージと hook は併用できない。boolean 以外はエラーで停止（誤記を黙って読み替えない） |
| `maxResidualWorktrees` | 任意 | `100` | 残置 worktree 総数の上限（DoS 防止ゲートの件数軸。バイト軸 `maxResidualWorktreeBytes` と独立に併用され、判定は OR＝どちらか一方でも超過すれば新規着手を止める）。ラン開始時に横断スキャンで観測した worktree の**物理総数**（メイン worktree のみ除外。状態ファイル追跡済み＝使用中の worktree も数える。使用中かどうかはディスク消費を変えないため。PR #185 codex P1 第 5 ラウンド）がこの値を**超過**（`>`）していたら、ディスク枯渇を防ぐため**新規イシューの着手を停止**する（fail-closed。既に走行中のイシュー・monitoring の継続は停止しない）。dispatch ループは新規着手の直前に毎回「開始時観測 + 本ラン積み増し（`ephemeralWorktrees.length`。implement / review / pr-create / fix-routing-error の新規作成台帳）」を再評価し、本ランの積み増しで上限を超えた時点でも以降の新規着手を停止する（PR #185 codex P1。バイト軸にも同種の途中経過再評価があるが、算出方法が異なるため後述）。さらに並列投入済みでまだ記録に到達していないタスク分を見込み、新規着手 1 件あたり最大 6 件（implement ×1 + review ×3 + pr-create ×1 + fix-routing-error ×1。`EPHEMERAL_KIND_MAX` テーブルから導出）、monitoring 再開 1 件あたり最大 1 件（fix-routing-error 分）を予約計上し、「実測 + 予約 + 着手候補分」が上限を超える投入を止める。**monitoring 再開自体もこの予約込み判定の対象**（ただし `item.kind === 'implement'` の再開に限る。verify-close ノードとして到達した再開は `runVerifyClose` が Merge ループへ入らず fix-routing-error を積み増さないため予約 0 で対象外。PR #185 Bugbot Medium と同じ線引き）であり、開始前に同じ projected 判定を適用して超過が見込まれる場合は当該イシューの再開をこの周回に限り defer する（恒久停止はしない。次周回・次回実行で予約解放後に再評価。pet-hub PR #1062 codex-review P1 対応。修正前は monitoring 再開自身の開始を無条件で許可しており、monitoring 項目を順次再開し続けると上限を無視して残置数を際限なく増やせた）。予約起因の超過見込みは今周回の投入見送り（defer）に留め、予約が解放されれば再開する。実測超過は従来どおり恒久停止する（PR #185 codex P1 第 2 ラウンド。ただしこの恒久停止＝`newStartSuppressed` は monitoring 再開の開始自体は妨げない設計を維持しており、上記の monitoring 再開専用 defer とは独立したゲート）。ラン開始時の横断スキャン自体が失敗した場合も、いずれかの軸が有効（`maxResidualWorktrees > 0 || maxResidualWorktreeBytes > 0`）なら残置総数を確認できないとみなして新規着手を停止する（fail-closed。両軸とも `0` 指定時のみ観測失敗でも続行。観測失敗時（`residualObserved === false`）も monitoring 再開（`item.kind === 'implement'` の再開に限る）は fail-closed で defer する — 観測できない状態での worktree 積み増しを許す fail-open を避けるため、`monitoringResumeGateDeferred` へ理由を記録してこの周回の再開を見送る（恒久停止ではない。次周回・次回実行で再評価する））。スキャン一覧が非空でも、独立取得したレコード総数との件数照合に不一致（転記の一部脱落の疑い）があれば同様に観測失敗として停止する（PR #185 codex P1 第 4 ラウンド）。使い捨て worktree は削除しない設計（references/recovery.md の「worktree の自動削除」節）のため、この上限超過時は `git worktree list` で確認し不要な worktree を `git worktree remove` で**手動削除**してから再実行する。`0` は「この件数軸のみ上限なし（チェック無効）」の明示オプトアウト（バイト軸の fail-closed には影響しない）。**負値・非整数はエラーで停止**（マージゲート入力と同じ厳格さ。誤記を黙って読み替えない）。既定値は 100（旧既定 20 では 1 イシュー消化あたり実測 4〜6 件の積み増しで 1 ラン 3 件着手が頭打ちになったため Issue #348 で引き上げ。linked worktree は object store を共有し working tree 分のみディスク消費のため 100 件でも過大ではないが、根拠は本リポジトリ 1 件のみの実測〔≈ 3.4 MB/件〕であり、配布先ごとに追跡ファイル量が異なるため、リポジトリ非依存の絶対閾値として `maxResidualWorktreeBytes` を必ず併用する。codex-review 指摘・PR #390）。**ただし `maxResidualWorktreeBytes: 0` でバイト軸を明示オプトアウトし、かつ本引数を未指定のままにした場合はこの補強が働かないため、既定値を安全側の旧既定 `LEGACY_DEFAULT_MAX_RESIDUAL_WORKTREES`（20）へ自動的に引き下げる**（`parseMaxResidualWorktrees` の `bytesAxisDisabled` 引数。codex-review 指摘・PR #390 第 2 ラウンド: 件数軸だけを緩和した既定値を、リポジトリ非依存の絶対閾値という補強なしに残さない）。利用者が本引数へ明示的に値を指定した場合はこのフォールバックの対象外（指定値をそのまま使う） |
| `maxResidualWorktreeBytes` | 任意 | `53687091200`（50 GiB） | 残置 worktree ディスク使用量の上限（DoS 防止ゲートのバイト軸。バイト単位。件数軸 `maxResidualWorktrees` と独立に検証・無効化でき、判定は OR）。**ラン開始時のみの観測ではない**（旧記載の訂正。codex-review 指摘・PR #390 第 2 ラウンド: 実装は当初からラン中の再評価を持っていたが本節がそれを反映していなかった）。ラン開始時に、残置パス一覧全件へ `du -sk` を実行して KiB を単純合計する観測に加え、共有 `.git` object store を除いたメイン worktree の working tree 相当サイズ（`measureMainWorktreeContentBytes`）を新規 1 worktree あたりの安全側予約 `perWorktreeByteReserve` として確定する（PR #390 codex-review P1・Cursor Bugbot High: 素の `du` 値は object store 全量を含み過大予約になるため除外する）。件数軸の「本ラン積み増し再評価」「予約計上」と同じ形で、`perWorktreeByteReserve × (台帳件数 − 直近基準確定時点の台帳件数)` の projection をラン中の新規着手・monitoring 再開の両方の直前に毎回再評価し、超過見込みで新規着手を止める（`projectResidualBytes`。基準確定時点までの積み増しは実測基準値に既に含まれているため、そこを差し引かないと二重計上になる。K8Dc 対応・PR #390）。**さらに** `perWorktreeByteReserve` は開始時に確定する下限 floor 値であり、ビルド成果物等で 1 worktree が floor を超えて成長した場合 projection だけでは過小評価し得るため、使い捨て worktree 台帳が `BYTE_REMEASURE_LEDGER_INTERVAL`（3 件）積み増されるごとに残置パス一覧＋台帳パスの合計を実際に `du` し直し（`remeasureResidualBytesIfDue`）、実測が上限を超えていれば独立に新規着手を止める。**加えて、新規着手（implement）の直前には台帳増分ゲートを介さず必ず実測し直す**（`remeasureResidualBytesNow`。台帳が 3 件増えない間も実行中 worktree はビルド成果物等で成長し得るため、台帳増分だけを契機にすると容量超過後の着手を止められない fail-open が残る — PR #390 codex-review P1 第 4 ラウンド。測定コストは「同一 dispatch 周回内は 1 回」の間引きで有界化する）。**この実測し直しは以後の projection の基準（`residualBytesAtStart`・台帳オフセット `byteBaselineLedgerCount`）を同一代入で更新する**（実測結果を上限超過の即時判定にのみ使って破棄すると、以後の判定が古い基準のまま容量超過の新規着手を許す fail-open になる。K8Dc 対応）。合計（直近の実測基準・projection・実測し直しのいずれか）が上限を**超過**していたら新規イシューの着手を停止する（fail-closed。既に走行中のイシュー・monitoring の継続は停止しない。件数軸で既に停止済みの場合は追加の抑止はせず観測値のみログへ記録する）。測定不能（`du` が 1 件でも失敗・非0終了・許可文字集合外のパス混入）は 0 で補わず観測失敗として扱い、この軸が有効なら新規着手を停止する（`countResidualWorktrees` の「検証不可」計上と同じ fail-closed の理由。実測し直しの失敗も projection へフォールバックせず新規着手を停止する。存在しないパス〔並行 cleanup による削除〕のみ 0 として許容し、`du` 自体の実エラーのみ測定失敗とする）。**エージェントの `worktreePath` 省略・空文字で台帳に未検証エントリが生じた場合は、この時点で `git worktree list --porcelain` の物理一覧（メイン除く全件・独立レコードカウントとの件数照合付き）へフォールバックして実測を継続し、フォールバックも失敗した場合（一覧取得不成立・件数不一致・パス検証不可）のみ従来どおり fail-closed で新規着手を停止する**（`buildPhysicalByteMeasureTargets`。review / pr-create / fix 系 worktree は隔離 worktree 内で detach するため branch 照合による帰属特定ができず、フォールバックは測定専用（削除経路へは流さない）で物理一覧を丸ごと差し替える。Issue #404）。ラン開始時観測が失敗したまま（`residualBytesObserved === false`）の場合は、monitoring 再開の projected 判定（前述の `item.kind === 'implement'` 限定の projection）自体も件数軸と同じ fail-closed 方針で defer し、観測が回復するまでそのランの monitoring 再開全体を待機させる（観測不能のまま fix-routing-error worktree の新規作成を許すと容量を確認できないまま超過し得るため）。`0` は「このバイト軸のみ上限なし（チェック無効）」の明示オプトアウト（件数軸の fail-closed には影響しない。件数軸の既定値フォールバックについては `maxResidualWorktrees` 行を参照）。**負値・非整数はエラーで停止**。既定 50 GiB は Issue #348 の検討案 B（実バイト数上限）を採用した後、Issue #467 でビルド成果物の大きいリポジトリでの誤停止（vector-db #629 実測）を踏まえ 2 GiB から引き上げたもので、配布先リポジトリのファイル量に依存しない絶対閾値として件数軸既定値 100 の妥当性を補強する。**残置サイズの合計上限とは独立に、実ディスクの空き容量そのものも新規着手・monitoring 再開の直前に毎回検証し直す**（`measureFreeDiskKib` / `remeasureFreeDiskNow`。Issue #467 P0 codex-review 対応・PR #468 で P0/High の再指摘に追加対応: 残置合計サイズが上限（既定 50 GiB）未満でも、実ディスクの空き容量自体はそれよりずっと小さいことがあり得るため〔例: 残置 8 GiB・実空き 4 GiB の導入先では、残置サイズだけを見るゲートは 50 GiB に達するまで新規着手を止めない〕、`df -Pk` でメイン worktree が属するファイルシステムの実空き容量を測定する。**ラン開始時 1 回だけの測定では以後の消費を反映できない**ため（codex-review P0）、バイト軸の `remeasureResidualBytesNow` と同じ「新規着手・monitoring 再開の直前に必ず実測し直す（間引きは同一 dispatch 周回内 1 回）」設計を踏襲する。判定に使う必要バイト数は**単一 worktree 分の予約とだけ比較しない**（codex-review P0: 実行中タスクの未消費予約・投入済み候補自身の予約を合算していないと過小評価になる）。`projectFreeDiskReserveBytes` が「実行中タスクの残余予約（`reservedUnits`。件数軸・バイト軸 (b) と同じ「最大増分 − 記録済み数」の計算をそのまま再利用）＋着手候補自身の最大増分（`extraReserveUnits`）」の合計に **1 worktree あたりの生の容量見積り（`rawPerWorktreeByteReserve`）** を掛けて必要バイト数を算出し、実測空き容量がこれを下回れば抑止する。バイト軸の `perWorktreeByteReserve`（`clampPerWorktreeByteReserve` で容量上限に対する予算配分としてクランプ済みの値）はここでは使わない — クランプ後の値は実際の 1 worktree サイズより小さくなり得るため、実ディスクの物理的な枯渇判定に使うと危険側を見逃す（Cursor Bugbot High 指摘）。件数軸・バイト軸と同じ OR 評価＝いずれか一方でも危険側なら抑止する。測定不能時も 0 で補わず、また古い実測値をそのまま流用せず観測失敗として新規着手を停止する（fail-closed）。大容量環境や `parallel` を大きく設定する環境では、実行中タスクの投入済み予約（`reservedUnits`）の合算により必要バイト数が大きくなる（例: raw ~8 GiB × 予約合計 9 件 = 72 GiB）。ラン開始時（`reservedUnits: 0`）の停止は着手候補自身の予約のみで必要量が決まり、`args.parallel` を下げても `maxResidualWorktreeBytes` を変更してもこの必要量は減らない（`maxResidualWorktreeBytes` は残置サイズ合計の上限であり本ゲートとは独立）ため、実ディスクの空き容量を確保する（メイン worktree の gitignored なビルド成果物・依存関係の削除を含む）ことでのみ解消できる（codex-review 指摘・Issue #467）。ラン中（`reservedUnits > 0`）の停止は投入済み予約の合算が要因になり得るため、空き容量確保に加え `args.parallel` を下げることも有効）。**`rawPerWorktreeByteReserve` の更新（実測 du 由来の予約見積り再算出）が未解決 implement パス・implement 限定 du 失敗のいずれかで失敗しても、全件測定（`du` の kib）自体が成功していれば `reserveStale: true` を返すのみで `failed: true` にはしない**（Issue #475: `failed: true` にすると、既に容量超過を確定済みでも verify-close を止める全 kind latch へ到達しない cap latch 省略を招くため、容量超過判定・全 kind latch は全件測定成功直後に先出しで確定する）。**ただし monitoring 再開の defer 判定は別**（Issue #475 fix #2・codex-review P0 再指摘）: `reserveStale` のまま古い予約見積りで monitoring 再開を進めると再開が作る worktree の見積りが過小評価され容量枯渇を許し得るため、monitoring 再開の defer 判定は `failed || exceeded || reserveStale` の OR とし `reserveStale` も defer を発火させる（当該周回のみの一過性の待機で、次回の予約更新が成功すれば再評価される）。**`df` 実測時点から新規着手・monitoring 再開の判定直前までの間に並行タスクが worktree を記録した分（台帳増分）も、`projectFreeDiskReserveBytes` の未測定予約として加算する**（df の実測値と台帳増分は独立に古びるため、実測直後に確定した空き容量をそのまま使い回すと、その間の消費が予約にも実測空き容量にも反映されない） |
| `maxBaseMerges` | 任意 | `3` | **`args.repo` が未指定のランでは値によらず base 取り込みは起動しない**（`args.repo` の形式不正は起動時にエラーで停止しラン自体が始まらない。`repo` 行参照）。PR が base とコンフリクト（`mergeable: CONFLICTING`。monitor の `conflicting` 経路、または merge-exec の `not-mergeable` 写像のいずれか）した際に、fix 予算（`fixCount`）を消費せず自動起動する base 取り込み専用エージェント（`baseMergePrompt`）の回数上限（0〜10 の整数。Issue #441）。`monitorsLeft` と独立の第 2 の停止性ガードとして機能する。上限到達時は `blocked` / `blockedReason: "quality"` で終端する（halt 非カウント。#141 の needs-fix と異なり、上限到達後も human が PR ブランチへ直接 base を取り込んで push すればコンフリクトが解消し、次回 monitor は `conflicting` を返さずこの分岐自体を再度通らないため `unrecoverable` は使わない。blocked 終端後の再実行は monitoring として直接再開する — Recover / PR Create フェーズは通らない。baseMergeCount は上限到達値のまま引き継がれるため、上限到達後の解消には人間が PR ブランチへ base を直接取り込んで push する必要がある）。`0` は自動 base 取り込みを無効化し、コンフリクト検出時点で即 `blocked` にする明示オプトアウト（この場合も `blockedReason: "quality"`。Issue #441 codex-review P1・PR #443）。**負値・非整数・小数はエラーで停止**（マージゲート入力と同じ厳格さ） |
| `repo` | 任意（`maxBaseMerges > 0` で base 取り込みを使うなら実質必須） | 未指定（`""`） | 対象リポジトリの `owner/repo`（例: `"Fandhe-AI/agent-cli-skills"`）。`baseMergePrompt` の worktree routing ガードが期待する owner/repo（`expectedRepo`）として使う、人間が明示するホスト側入力。**エージェントの自己申告値（外部チェック観測エージェント等）は一切使わない**（PR #443 codex P0: 自己申告値を信頼境界に使うと誤配置 worktree からの別リポジトリへの push を防げない）。未指定は `expectedRepo` を空文字のまま確定し、base 取り込み（`baseMergePrompt` の起動）を行わず conflicting は即 `blocked` / `blockedReason: "quality"` で終端する（fail-closed。実装・push 前 Review・PR 作成・CI 監視は値によらず自動で進む）。**形式不正（`isValidRepoSlug` の owner/repo 形式を通らない値）は起動時にエラーで停止**（マージゲート入力と同じ厳格さ。誤記を黙って未指定へ読み替えるとガードが静かに弱まるため） |

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

| 指定 | 意味 | マージ挙動 |
|------|------|-----------|
| 未指定 | 外部チェック構成が**未確定** | 観測結果にかかわらず自動マージを停止し `blocked` で終端する（実装・PR 作成・CI までは進む） |
| `[]` | 「外部チェックを使用しない」と人間が**確定** | 外部レビュー待機をスキップして CI green と未解決スレッドなしのみで判定する |
| `[{"app": "cursor", "context": "Cursor Bugbot"}]` 等 | 指定 App + 信頼済み required check context を正とする（観測結果より優先） | 指定した**全 App** について HEAD sha に対する起動を検証する。cursor は「レビューが 1 件以上到着し、かつ CHANGES_REQUESTED が 0 件であること」（Issue #146。個別指摘はレビュースレッドとして残るため「未解決スレッド 0 件」ゲートが内容非依存に遮断する。監視側の内容評価は修正ループ用 advisory でありマージ可否の入力ではない）、それ以外の App は check-run が 1 件以上ならその全件が許容 conclusion であること、check-run が 0 件のときに限りフォールバックとして「APPROVED レビューが 1 件以上かつ否定的レビュー 0 件」であることをマージ条件とする（Issue #155）。opt-in マージでは G0 が宣言 `context` + App ID の組で required 化を照合する |
| `["cursor"]` 等（slug のみの旧形式） | App は確定するが信頼済み context が**未宣言** | 監視・外部レビュー待機は上と同じ。ただしクライアント側自動マージは fail-closed で停止する（`autoMerge: true` でもマージせず `blocked` 終端。App ID だけの照合では同一 App の無関係な context の required 化でも G0 を通過してしまうため — 下流 sync PR codex P0 変種 1） |

観測ベースの検出は直近 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](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](references/automerge-design.md)

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

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

詳細: [references/automerge-design.md](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）。

```bash
# 親イシューのサブイシューを取得（--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 フェーズへ渡す

```bash
# 作業ブランチ作成例（並列時の衝突回避のためイシュー番号を含める）
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 回のみ）。

```bash
# 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)