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）>",
    "phaseGate": "<boolean。true でルート直下の子（Phase 親 or leaf）を sub-issues リスト順（siblingIndex）に直列化し、前 Phase の全子孫が merged/closed になるまで次 Phase 配下のノードに着手しない（opt-in。Issue #494）。既定 false は現行動作（post-order 優先度のみ・追い越しあり）を完全に維持する。boolean 以外はエラーで停止>",
    "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"}] }
}

引数