ravel-impl

name	ravel-impl
description	Ravel の実装単位を worktree 隔離でサブエージェントへ委譲し、独立検証 → ravel-review + 独立レビュー（既定 codex、--review で指定 / skip）の 突き合わせ → 指摘対応 → PR → CI → （明示時のみ）マージまで通す。 単位 ID から仕様・完了条件・依存・フェーズ境界を scripts/docs.sh で解決し、 依存が未マージなら起動しない。複数単位は --multi（並行・単位ごとに PR） または --compress（1 PR に集約）。 トリガー: "/ravel-impl"、「この単位を実装して」「委譲して」（単位 ID を伴う）。

ravel-impl

実装単位を、着手からマージ可能な状態まで運ぶ。手を動かすのは サブエージェント、判断と検証は呼び出し側という分担を守る。

既定は 1 単位 1 PR。複数を並行で回すなら --multi、PR を 1 本に畳むなら --compress（§2b）。

既定では呼び出し側（あなた）は司令塔に徹する。実装差分を自分で書き始めない。 例外は「指摘対応のうち局所的なもの」（§5）と、--self を明示したとき（§4）。

0. 引数

/ravel-impl <単位 ID | 自由文> [オプション]

オプション	意味
--agent <claude|kimi|codex>	実装するサブエージェント。既定 claude
--self	委譲せず自分で実装する。worktree 隔離と §5 以降はそのまま
--brief	ブリーフを書いてそこで止まる（起動しない）
--transfer-only	委譲して起動した時点で返す（検証・レビュー・PR をやらない）
--no-pr	指摘対応まで済ませ、PR を作らずブランチを残して返す
--merge	CI 全緑 + Critical / FAIL 無しならマージし、状態更新と掃除まで行う
--review-cycle n	「指摘 → 修正 → 再レビュー」の上限巡回数。既定 2
--stack	未マージ依存のブランチに重ねる（既定は拒否。§2）
--multi	複数の単位 ID を受け、依存上ぶつからないものを並行で、単位ごとに PRで回す
--compress	複数の単位 ID を受け、1 ブランチ 1 PR にまとめる（§2b）
--review <agent|skip>	独立レビューの担当。既定 codex。skip でも自分の検査は省かない（§5）
--squash	マージを squash にする。既定は merge コミット（§7）

既定はマージしない。 --merge は無人で回すときに明示する。

--multi と --compress は排他。前者は PR を分けて並行で速く回す、 後者は PR を 1 本に畳む。同時に指定されたら止めて聞く。

1. 単位の解決

bash scripts/docs.sh id <単位 ID>

ここから 4 つを取る。これがブリーフの背骨になる。

• 仕様の正: 計画書の「単位 N」節（docs/implementation/*-plan.md）
• 完了条件: 同じ節の一覧。言い換えずに写す
• 状態と依存: backlog.md の行
• フェーズ境界: roadmap.md の該当フェーズ表

単位 ID が解決できない自由文のときは規模で判定する:

• 複数クレート / 複数パネル / 評価・永続化・コマンド経路に触れる → 起動せず「先に docs/implementation/ の計画書を」と返す（AGENTS.md の Design gate）
• 局所修正・単一パネルの機能 → そのまま進める

2. 依存の確認

backlog.md の依存列を見て、✅ 以外の依存が 1 つでもあれば起動しない。 理由（どの単位が未マージか、その PR 番号があれば添えて）を返して終わる。

--stack のときだけ依存ブランチから切って重ねる。依存が先にマージされたら rebase する。依存先のレビュー修正は全部下流に伝播するので、既定にしない。

2b. --compress（複数単位を 1 PR に畳む）

フェーズ丸ごとを片付けたいときに、PR の本数を減らす。

主目的はレビューを 1 回にまとめることで、CI 待ちの削減は副次的。 まとめすぎるとレビューの密度が落ち、人間が読むのも辛くなる。迷ったら まとめない側に倒す。

まとめてよい条件

次をすべて満たすときだけ 1 グループにする。

1. 同じ計画書の単位であること。 *-plan.md をまたぐ組は作らない。 PR のテーマが 1 つに保たれ、本文の「なぜ今か」が 1 段落で書ける
2. 集合の中で依存を並べられること。 依存が鎖でなくてもよい （EXPO-4 / EXPO-5 / EXPO-6 のように同じ親にぶら下がる並列も可）。 トポロジカルソートできればよい
3. 集合の外に未マージの依存が無いこと。 §2 と同じ判定

満たさない組が混ざっていたら、満たす部分集合を提案して確認を取る。 勝手に落とさない。

しきい値で確認を取る

上限は設けないが、5 単位を超えるか、diff が 1500 行を超える見込みの ときは、起動前に分割案を出して確認する。

EXPO-2..EXPO-7 の 6 単位（見込み 2400 行）。
2 本に割ることを勧める:
  A: EXPO-2, EXPO-3, EXPO-4   （束縛の解決と列挙）
  B: EXPO-5, EXPO-6, EXPO-7   （編集 UI と文書）
このまま 1 本にするか、A / B に割るか。

進め方の差分

• worktree は 1 つ。 名前はグループを表すもの（.worktrees/expo-binding）。 単位 ID を並べた名前にしない
• ブランチも 1 本。 グループ全体を表す具体的なケバブケース
• ブリーフは単位ごとに節を分ける（§4）。「やること」「完了条件」は 単位ごとに独立して書き、実装順を依存順で明示する
• コミットは単位ごとに分ける。 これは畳まない。git log で単位の 境界が読めることが、まとめた PR をレビュー可能にする唯一の担保。 既定の merge コミットならその境界が main にもそのまま残る （だから --squash との併用は §7 で止めて聞く）
• レビューは単位ごとに検査する。 diff 全体を 1 度眺めて終わりにしない。 §5 のチェックリストを単位ごとに辿る
• 1 単位に FAIL が出ると PR 全体が止まる。 これは受け入れる。 切り離したくなったら、その単位だけ別ブランチへ移す判断を止めて聞く

3. worktree を切る

git worktree add .worktrees/<単位 ID 小文字> -b <prefix>/<kebab-case> <base>

• 場所はリポジトリ直下の .worktrees/。.gitignore に /.worktrees/ が 無ければ最初に足す（一度きり）
• ブランチ名は .agents/rules/ の規約どおり、意味のある prefix + 具体的なケバブケース。単位 ID をブランチ名に入れない
• base は main（--stack なら依存ブランチ）
• 新しい worktree では mise trust を一度実行する。しないと mise run が 全部 Config files … are not trusted で落ちる

4. ブリーフを渡す

ブリーフはリポジトリの外（セッションの一時ディレクトリ）に書き、 サブエージェントにはパスを渡して「まず読め」と指示する。 worktree の中にメモを置かせない（git add -A での混入事故を原理的に断つ）。

ブリーフに必ず入れる 7 項目:

1. 作業場所: worktree の絶対パスとブランチ名。「主ワークツリーと他の worktree には触るな」を明記（並行作業がある）
2. 最初に読むもの: AGENTS.md、対象ファイルに paths が一致する .agents/rules/*.md、計画書の該当単位、関連する docs/dev/ の手順書
3. 前提: 直前にマージされた単位が用意した型・関数・規約。倣うべき既存の 形を名指しする（例「RequiresPlanarP / require_planar と同じ粒度で」）
4. やること: 計画書の記述 + 実測した箇所数（grep -c の結果を書く。 計画書の数字は古いことがある）
5. 完了条件: 計画書から逐語で写す
6. 制約: push と PR の禁止、git add -A 禁止、論理単位ごとの英語 1 行 Conventional Commit（タスク ID・issue 番号・エージェント名・セッション URL を 書かない）、mise run check と mise run docs:check を通す、 scripts/lint-patterns.sh を弱めない、本番依存を追加しない（要ると 判断したら実装せず報告）、backlog / roadmap の状態列は触らない（§7）、 フェーズの外へ出ない（触ってはいけない単位を名指しする）
7. 最終報告の形: コミット一覧、変更ファイル、検証結果、設計判断、 既存ゴールデンが無改変であることの確認、判断が必要な点、worktree のパス

--brief ならここで止まる。--transfer-only なら起動して返す。

--compress のブリーフ

上の 7 項目のうち 1・2・3・6・7 はグループで 1 回書き、 4（やること）と 5（完了条件）は単位ごとに節を分ける。

## 実装順（依存順。この順で 1 単位ずつ完了させること）

1. EXPO-2 束縛の解決と適用
2. EXPO-3 宣言の機械可読な列挙
3. EXPO-4 素材参照の宣言と差し替え

### 単位 1: EXPO-2 …
  やること / 完了条件

### 単位 2: EXPO-3 …
  やること / 完了条件

追加で必ず書く制約:

• 単位ごとにコミットを分ける。 1 単位が複数コミットになるのは可。 複数単位を 1 コミットに混ぜるのは不可
• 前の単位の完了条件を満たしてから次へ進む。 まとめて実装して 最後にテストを書かない
• 報告は単位ごとに節を分ける。 どの単位のどのコミットか対応が付く形

--self（委譲しない）

委譲せず自分で実装する。§1〜3 と §5 以降は変わらない — 単位の解決、 依存の確認、worktree 隔離、独立検証、レビュー、PR、状態更新まで同じ手順を 踏む。飛ばすのはブリーフの受け渡しと起動だけ。

worktree を切るのは --self でも同じ。並行して別の作業が走っていても 主ワークツリーが汚れず、失敗しても捨てられる。

ただしレビューの独立性が落ちる（書いた本人が読むことになる）。 --self のときは §5 の codex への独立レビューを省略しない。codex が 使えないなら、少なくとも「この変更が入れた退行か、元からある穴か」を main と比較して確認する手順を明示的に踏む。

単位が小さい（1 ファイル、機械的、完了条件が 2〜3 個）ときや、委譲の往復が 実装そのものより高くつくときに使う。

エージェント別の起動と進捗の見方

agent	起動	完了の判断
claude	サブエージェント機構（worktree 隔離が使えるならそれに乗る）	完了通知
kimi / codex	herdr pane run <pane> にブリーフのパスを渡す。実行前に cwd と前面プロセスを確認	worktree の git log / git status の変化と画面

agent_status 単独を根拠にしない。 kimi はツール呼び出しごとに idle に 落ち、pane read が空を返すこともある。どちらも停止の証拠にならない。

5. 独立検証とレビュー（1 サイクル）

報告を鵜呑みにしない。必ず自分で回す。

1. mise run check と mise run docs:check を自分の手で実行する
2. main が進んでいれば rebase する（doc の衝突は「両方の内容を残す」で解く）。 rebase の前に、ローカル main の未 push コミットを push しておく。 origin/main が遅れていると、GitHub は PR の merge-base をその古い位置で 計算するので、ローカル main にしか無いコミットが全部 PR の diff に 混ざる。CodeRabbit がそれをレビューして、単位と無関係な指摘が大量に付く （マージ結果自体は正しいので、事故に気づきにくい）
3. ravel-review の検査手順を辿る（render 純粋性、focus 所有権、Command 経路、 Global 用法、コア層分離）
4. --review の指定先に独立レビューを投げ、所見を突き合わせる。 既定は codex。指定したエージェントが使えなければ該当箇所を自分で 読む。「レビューしていない」で通さない
5. 報告に挙がった「判断が必要な点」を §6 で仕分ける
6. 指摘は必ずコードで裏取りしてから採否を決める。既存の main と 比べて「この変更が入れた退行か、元からある穴か」を確認する

--review <agent|skip>

値	意味
codex（既定） / claude / kimi	そのエージェントへ独立レビューを投げる
skip	独立レビューだけを飛ばす

skip でも次は必ずやる（飛ぶのは 4 だけ）:

• 1 の mise run check / mise run docs:check
• 3 の ravel-review の検査手順
• 6 の裏取り
• §7 の CodeRabbit 1 巡

つまり skip は「もう 1 人分の目を省く」であって「レビューしない」ではない。 --self と --review skip の同時指定は拒否する — 書いた本人しか読まない 状態になり、§4 の --self が課している独立性の担保が消える。

--compress のときは、単位ごとにレビューを投げるのではなく、 グループ全体の diff を 1 回投げる。ただし依頼文には単位の境界と それぞれの完了条件を書き、単位ごとに見るよう指示する。

指摘の直し手:

• 局所的・機械的・ドキュメント → 呼び出し側が直す（往復が無駄）
• 構造的・設計判断を伴う・広範 → 実装したサブエージェントへ差し戻す （文脈を持っているので速い）

--review-cycle n の上限に達しても指摘が残るとき:

• FAIL / Critical が残る → PR を作らず停止し、ブランチと残課題を報告
• WARN だけ → PR は作る。本文に「未対応の指摘」として列挙し、マージしない

6. 判断の仕分け

サブエージェントが上げた「判断が必要な点」と、レビューで出た設計上の分岐は 影響範囲で分ける。

• 実装の内側に閉じる（命名、エラー型、テストの置き場、到達不能な腕の書き方、 機械的な修正）→ 決めて進む。決めた内容は報告に列挙する
• 外に出る（ユーザーに見える挙動、仕様の追加・変更、スコープ拡大、 永続化フォーマット、公開 API の破壊）→ 止めて聞く。勝手に広げない

7. PR とマージ

1. bash scripts/review-gate.sh --mark <branch> でゲートを記録する （マーカーが無いと gh pr create がブロックされる）

2. push して PR を作る。本文には次を書く: なぜこの単位を今やるのか （roadmap の根拠）、何を変えたか、設計判断とその理由、既存挙動が 変わらないことの根拠、検証内容、残した制約

   --compress のときは冒頭に単位の一覧と実装順を置き、以降の節を 単位ごとに切る。レビューする人が「どこからどこまでが 1 単位か」を 本文だけで追えるようにする。タイトルはグループ全体を表す Conventional Commit 1 行にする（単位 ID を並べない）

3. CI と CodeRabbit を待つ。CodeRabbit は 1 巡だけ対応して push し、 再レビューは追わない

   待ち方は次で固定。自作のポーリングループを書かない:

   # run_in_background で 1 つのコマンドとして投げる
   gh pr checks <PR 番号> --watch --interval 20 > /tmp/pr<N>-watch.log 2>&1
   gh pr checks <PR 番号> --json name,bucket   > /tmp/pr<N>.json      2>&1
   

   --watch と --json は併用できない（cannot use --watch with --json で即座に usage エラーになり、待たずに「終わった」ように見える）。待つ側と 読む側を 2 コマンドに分け、待ち終わってから bucket を読む。

   --watch は全チェック確定まで待つ。背景実行なら完了時に通知が来るので、 前景の 10 分上限に切られない。背景ジョブは cwd が消えると落ちるので、 worktree の中ではなく主ワークツリーから投げる。

   sleep N を単体で、または sleep N && gh pr checks … の形で使わない。 前景の sleep はブロックされる。

   終了コードだけで「CI 全緑」を判定しない。 0 は pass と skip の 両方で返る（1 = 失敗、8 = 保留）。bucket を見て区別する:

   bucket	意味	扱い
   pass	成功	可
   skipping	ジョブが条件で飛んだ（bench は常にこれ）	可
   fail / cancel	失敗・打ち切り	マージしない
   pending	未確定	まだ待つ

   さらに ravel では ci.yml の paths-ignore により、docs のみの PR で check (macos-latest) / check (windows-latest) が一件も現れない （skipping ですらなく不在。CodeRabbit だけが残る）。よって:

   • Rust を触った単位 → 両 check (…) が であることを確認する。 不在なら の誤爆なので調べる

--no-pr なら 1 の手前で止まる。

8. 報告

最後に必ず返す:

• 単位 ID と PR 番号（作った場合）、マージしたか。 --compress なら含めた単位を全部列挙する
• レビューで出た指摘と、その事実確認の結果・対応。 --compress ならどの単位の指摘かを添える
• 独立レビューを誰に投げたか（--review skip ならその旨と、 代わりに自分で読んだ範囲）
• 止めて聞くべき判断が残っていればそれ（次の一手を提示する）
• 残した制約と、依存が解けて着手可能になった単位

やらないこと

• 実装差分を呼び出し側が書く（§5 の局所修正と --self を除く）
• 計画書に無い機能の追加。フェーズや単位の境界を越える作業
• サブエージェントの報告を検証せずに PR を出すこと
• 指摘が残ったままのマージ
• --compress で計画書をまたいで束ねること、しきい値を超えたのに 確認を取らずに進めること
• --compress の PR を確認なしに --squash でマージすること（単位の履歴が消える）
• 既定を squash と思い込むこと（既定は merge コミット）