cross-refactoring: 多ランタイムでリファクタリングを収束させるループ Skill を追加する

[takemi-ohama]

概要

/ndf:cross-review がレビューを収束させるのと同じ発想で、リファクタリングを収束させる Skill /ndf:cross-refactoring を追加する。

claude / codex / gemini / kiro のうちホストを除いた 3 CLI に「どこを・どう直すか」を提案させ、提案ごとに実装ランタイムとレビューランタイムを必ず別にして適用とレビューを回す。個々の提案がレビュー収束したら次の提案へ進み、全提案を消化したら提案フェーズからやり直す。新しい提案が出なくなった時点で完了とする。

実施計画の全文: issues/issue-113-cross-refactoring-loop.md（ブランチ claude/cross-refactoring-loop-skill-zmnhbx）

背景

refactoring Skill は「テストで守りながら 1 手ずつ直す」手順を持つが、次の 2 つを持っていない。

1. 何を直すかの発見 — どのスメルに手を付けるかが人間または単一 AI の主観で決まり、見落としが体系的に検出されない
2. 直した結果の他者検証 — 実装した本人（同一モデル）の自己レビューでは、手法の妥当性と「振る舞いが本当に変わっていないか」が構造的に検証されない

cross-review は 2 の一部を担うが、対象は人間が作った PR であり、リファクタリング固有の観点（振る舞い不変 / スメルと手法の対応 / 現状固定テストの妥当性 / scope creep）をレビュー観点テンプレートに持たない。

設計の要点

三重ループ

• 外側 = 提案ラウンド — 「指摘がなくなったら完了」の判定単位
• 中間 = 提案 item — 1 件ずつ直列に適用
• 内側 = レビュー収束 — 「指摘がなくなるまで繰り返し」の単位

参加ランタイムはホストを除いた 3 者

ホストセッションはオーケストレータに徹し、どのフェーズにも参加しない。参加者は常に 3 つ揃うので、輪番（実装 1 : レビュー 2）はどのホストでも同じ形になる。

ホスト	参加ランタイム（輪番）
Claude Code	codex / gemini / kiro
Codex	gemini / kiro / claude
Kiro	claude / codex / gemini

RUNTIMES = ["claude", "codex", "gemini", "kiro"] - [host] # 常に 3 要素
impl = RUNTIMES[(outer_round + item_index) % 3]
reviewers = RUNTIMES から impl を除いた 2 つ

指摘の修正は impl ランタイムが行い、レビューの独立性を保つ。ホスト判定は --host の明示指定を第一とし、推定結果は init 出力と state.json に必ず残す（参加者リストにホストが混ざったら init を失敗させる）。

全参加者が CLI になったことの帰結

claude が参加者になる場合もヘッドレス CLI（claude -p）として起動し、ホストの Agent tool（サブエージェント）は一切使わない。そのため ループ全体を 1 本の bash で駆動でき、cross-review の「state.py + launcher + monitor.py」骨組みと多軸完了判定をそのまま流用できる。Skill もランタイム中立になるため、3 ランタイムすべてに配布する。

worktree はエージェント分用意する

<worktree-base>/<owner>--<repo>/rf<PR>/
├── work/ # 書き込み用。PR head ブランチ（唯一の非 detach）
├── <参加1>/ # 読み取り用。--detach
├── <参加2>/ # 読み取り用。--detach
└── <参加3>/ # 読み取り用。--detach

同一ブランチを 2 つの worktree に checkout できないため読み取り用は --detach にする。読み取り専用でも分けるのは、レビュアーがテストを実行して振る舞い不変を確認するため / 生成物の競合を避けるため / gemini の workspace 制約を回避するため。並列化するのは提案とレビューだけで、適用は work/ 上で直列に行う。各 worktree の .cross_refactoring/refs/ へ refactoring Skill の参照ファイルをコピーし、参加ランタイムに NDF が導入済みであることを前提にしない。

Kiro / Claude CLI の固有対応（要検証）

kiro-cli 2.16.1 の実測（issues/ndf-development-skills/03-runtime-conformance.md）から:

• 非対話実行は kiro-cli chat --no-interactive
• Skill frontmatter の allowed-tools は事前承認として機能しない（execute_bash が拒否された実測あり）。agent 定義側で許可し、worktree の .kiro/agents/ に専用 agent JSON を生成する
• workspace agent は cwd 配下の .kiro/agents からしか検出されない
• 既定エージェントはマシン全体の設定なので kiro-cli agent set-default は絶対に呼ばず、常に --agent で明示指定する
• /ndf:* 形式のコマンドは存在しないため、プロンプトは自己完結した平文にする

allowedTools による事前承認が非対話で実際に効くか、および claude -p で編集・シェル実行を通す --permission-mode の値は未検証。Task 3 で最初に実機確認する。Kiro でシェル実行が通らない場合は Kiro を提案・レビュー専任に縮退させ、impl_capable から外す（レビューは 2 者のままなので構造は変わらない）。

終了条件

ループ	終了条件
内側（レビュー）	reviewer 全員 APPROVE / --max-fix-rounds（既定 3）到達で revert して放棄
中間（item）	採用 item を全件消化
外側（ラウンド）	採用 item 0 件 / --max-outer-rounds（既定 3）到達 / 提案の重複率が前ラウンド比 70% 以上

収束しない item は捨てるのが cross-review との重要な差分。レビュー指摘の修正は必須だが、リファクタリングは任意作業なので、揉める提案は PR に残さない。外側ループ終了後は /ndf:cross-review を PR 全体の最終ゲートとして実行する。

タスク分解

• Task 1: 状態管理の骨格（refactor.py の init / start-round / next-item / advance / status）
• Task 2: worktree 準備（prepare-worktrees.sh、stale ガード / sync <sha> / refs コピー / kiro agent JSON 生成）
• Task 3: Kiro / Claude CLI の非対話実行手順の確立（他タスクの前提。最初に着手）
• Task 4: 提案フェーズ（参加 3 CLI 並列起動 + merge-proposals の重複排除・優先度付け）
• Task 5: 適用フェーズ（refactoring Skill 準拠、差分予算・テスト green の機械検証）
• Task 6: レビューフェーズ（リファクタリング専用観点テンプレート + judge-review）
• Task 7: 内側ループの収束と放棄（should-abandon / abandon-item の revert + reply/resolve）
• Task 8: 外側ループの収束判定（採用 0 / 上限 / 提案重複率 70%）と最終ゲート
• Task 9: monitor.py の汎用化（--tmp-dir / --agents <csv> / --stem-template / --state-file。既存テスト無変更通過が完了条件）
• Task 10: SKILL.md と docs 執筆（frontmatter 規約準拠）
• Task 11: テスト（refactor.py 全 subcommand。ホスト別の参加者確定 3 ケースを含む。外部プロセスは呼ばない）
• Task 12: 配布物同期・ドキュメント更新・version bump（8.0.0 → 8.1.0、Skill 数 30 → 31）

副次的な変更

• external-ai に references/cli-kiro.md / references/cli-claude.md を追加し、SKILL.md の CLI 比較表を 4 者へ拡張する
• cross-review/scripts/_gemini-env.sh を抽出し、両 Skill から共用する

やらないこと（v1 スコープ外）

• PR ローテーション（件数上限で総量を抑える方針を先に検証する）
• 複数 item の並列適用（同一ブランチへの同時コミットは競合とレビュー単位の曖昧化を招く）
• ホストランタイム自身を提案・実装・レビューに参加させること（オーケストレータに徹する）
• リファクタリング以外の変更（機能追加・不具合修正）の取り込み

[takemi-ohama]

Task 3 の調査結果（一部確定 / 一部は実機確認が残）

検証記録: issues/issue-113-task3-cli-verification.md

検証環境は Claude Code on the web のリモートコンテナ（root 実行 / git 2.43.0 / claude 2.1.233）。codex / gemini / kiro-cli は未インストールのため、Kiro は公開情報の調査に留めた。

確定したこと

1. git worktree の同一ブランチ制約（実測）

2 つ目の worktree に同じブランチを checkout すると fatal: '<branch>' is already used by worktree at ... で失敗する。読み取り用 worktree を --detach にする設計は正しい。

2. Claude CLI の起動形式（実測）

cat prompt.md | claude -p \
 --permission-mode acceptEdits \
 --allowed-tools "Bash,Write" \
 --output-format json

• プロンプトは stdin から渡せる（argv に長文を載せる必要がない）
• -p 指定時は workspace trust ダイアログが skip される（gemini の --skip-trust 相当は不要）
• bypassPermissions は root では拒否される — --dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons。CI / コンテナは root 実行が多いので既定にできない。acceptEdits + --allowed-tools なら root でも通ることを実測
• 完了検知は --output-format json の is_error / subtype で足りる。sentinel 不要。permission_denials が非空なら承認失敗として早期エラーにできる
• コスト実測: ごく単純な 3 ターンで total_cost_usd = 0.259

3. Kiro の allowedTools は当てにできない（調査 → 設計変更）

初版では worktree に専用 agent JSON を生成して allowedTools で execute_bash を事前承認する想定だったが、kirodotdev/Kiro#7467（Kiro 2.0.0）で ~/.kiro/agents/*.json の設定が honored されず毎回 Allow this action? が出ると報告されている。回避策として挙がっているのは kiro-cli chat --trust-tools "..." というフラグでの明示指定。本リポジトリの既存実測（2.16.1 で Skill frontmatter の allowed-tools が効かない）とも整合する。

→ 専用 agent JSON の生成をやめ、--trust-all-tools / --trust-tools フラグで承認する方針に変更した。カスタム agent 自体が不要になるので Task 2 の該当処理も削除。

4. Kiro の承認漏れは「エラー」ではなく「ハング」

kirodotdev/Kiro#7483 によると --no-interactive は「全承認」か「承認待ちで無限ハング」の二択で、安全な中間がない（--deny-untrusted-tools は要望段階）。

→ monitor.py の stall timeout を kiro に対して必須にし、Allow this action? を早期エラーパターンに追加して即 kill する。

5. frontmatter 予算（実測）

frontmatter 合計: 10612 文字 (上限 11200) で残余 588 文字。cross-review の frontmatter が 407 文字なので、同規模で書くと残り約 180 文字。external-ai の description 拡張分を足すとほぼ使い切る。argument-hint を短く保つ方針を明記した。

残っていること（kiro-cli のある環境で確認）

1. --trust-tools に渡すツール名の正確な綴り（既存実測は execute_bash、#7467 の例は read,write,aws,report と表記ゆれ）
2. --trust-all-tools / --trust-tools が --no-interactive と併用できるか
3. プロンプトを stdin から渡せるか（argv 必須か）
4. 完了検知の手段を正常・ツール拒否・未認証の 3 ケースで確認
5. root 実行の可否
6. 検証に使った kiro-cli の版数（2.16.1 から挙動が変わっていないか）

これらが確定するまで Task 4〜7 の kiro 分岐は書けない。どうしてもシェル実行が通らない場合は、Kiro を提案・レビュー専任に縮退させ impl_capable から外す（レビューは常に impl 以外の 2 者なので構造は変わらない）。

なお公式ドキュメント（kiro.dev/docs/cli/...）はこの環境の egress proxy でブロックされており参照できなかった。

---

Generated by Claude Code