resolve-follow-ups

フォローアップの解決

記録された範囲のフォローアップを、個別に検証済みのプルリクエストへ変換します。再現性と権限のゲートを通過できない項目はすべて、そのまま残します。

このスキルには project-knowledge が必要です。作業を始める前に、インストール済みであることを確認してください。インストールされていない場合は、停止し、プロジェクトでパッケージマネージャーのランナーが固定されている場合はそれを使って、インストールコマンド npx skills@latest add toy-crane/skills --skill project-knowledge とともに報告してください。

実行モードの選択

• 特定のフォローアップのパスを指定せずに呼び出された場合は、一括処理として扱います。リポジトリのバックログからワーカーを選び、まとめたレポートを返します。
• フォローアップのパス、ベース SHA、試行 ID、オーナートークン、ブランチ、ワークツリーが指定されて呼び出された場合は、ワーカーとして扱います。その項目だけを解決し、最終結果を1つ返します。
• スケジュールまたは定期実行の頻度は、このスキルの対象外です。1回の呼び出しは1回の一括処理であり、フォローアップごとの定期スケジュールではありません。

バックログの一括処理

このスキルのディレクトリを特定し、そのディレクトリから scripts/resolve-follow-ups.sh を使用します。このスクリプトは、順序、新しいベースの識別、ワークツリーの作成、試行の抑制、クリーンアップを決定論的に行うための境界です。

1. list --repo <root> を実行してリモートのデフォルトブランチを取得し、検出順に並んだすべての有効な候補と、すべての invalid-follow-up を取得します。不正なファイルは、欠けている根拠を補わずに報告してください。古い可能性のあるコーディネーターのチェックアウトから列挙しないでください。
2. 候補ごとに順番に identity --repo <root> --follow-up <path> を実行します。適格なワーカーを3つ開始するか、順序付けられたバックログが尽きるまで続けます。eligible はスナップショットにすぎず、予約ではありません。ワーカーを起動する前に、プラットフォームアダプターがその試行のアトミックな claim または prepare の結果を取得する必要があります。skipped-unchanged ... claimed <owner> [<worktree> <branch>] は、別の一括処理が変更されていないフォローアップをすでに所有していることを意味します。そのアクティブな所有権と記録済みのプルリクエストは、無関係なデフォルトブランチの更新後も維持されます。最終結果がプルリクエスト以外の場合は、その更新後に再試行可能になります。
3. skipped-unchanged の場合：
   • 結果に claimed とオーナーが含まれる場合は、再度ディスパッチしないでください。別のワーカーが、同一の内容とベース ID の組み合わせをすでに所有しています。アダプターによって所有プロセスの終了が確認され、最終結果がない場合は、報告されていればそのプロセスに正確に紐付くワークツリーをクリーンアップしてから、recover --repo <root> --attempt-key <key> --owner <owner> を実行します。claim が古いという理由だけで、アクティブまたは状態不明のワーカーを recover してはいけません。
   • フォローアップの内容またはリモートのデフォルトブランチ SHA が変わるまでは、以前の not-reproduced、needs-shaping、または blocked の結果を維持します。最終状態の identity 出力には owner <owner> [<worktree> <branch>] が保持されます。ワーカー終了後もそのワークツリーが残っている場合は、ベース変更後に再試行を開始する前に、記録された正確な座標を使って cleanup してください。ベースの更新があっても、未クリーンアップの最終ワークツリーは隠れません。
   • 結果に pull-request と URL が含まれる場合は、そのプルリクエストを確認します。オープン中はスキップしたままにします。マージされずにクローズされた後は、再試行の前にそのベース ID に対して clear を実行します。マージ済みのプルリクエストの場合は、更新されたデフォルトブランチ上でフォローアップが削除されている必要があります。重複して作成するのではなく、不一致を報告してください。パスが削除された後に再作成された場合は、Markdown の内容が以前の項目と同じでも、新しいフォローアップとして扱います。
4. ワーカーを並行実行する前に、候補のスコープが互いに独立しているかを確認します。独立性が不明なスコープや重複するスコープは個別に処理し、各項目に別々のワークツリーとプルリクエストを割り当てます。
5. ワーカーが失敗しても、独立した他のワーカーはキャンセルしません。1回の一括処理で実際に稼働するワーカーは、最大3つまでとします。

項目ごとに分離されたワーカーを起動する

各ワーカーには、フォローアップのパス、検証済みのベース SHA、試行 ID、 オーナートークン、ブランチ、ワークツリー、および以下のワーカー契約だけを渡します。チェックアウトの紐付け、結果の記録、クリーンアップにはオーナートークンが必要です。これにより、あるワーカーが別のワーカーの試行を上書きしたり削除したりできなくなります。ディスパッチャーはリポジトリ全体で正規のワークツリーパスも予約します。予約に失敗した場合、別の試行のチェックアウトを再利用して回避してはなりません。

Claude の手順

アクティブなインストールに、フェッチ失敗時に停止し、識別対象のベース SHA を保証する作成時の WorktreeCreate ポリシーまたは同等のチェックがある場合は、isolation: worktree を指定したサブエージェントを使用します。サブエージェントには、編集前に自身の HEAD とその SHA を比較するよう求めます。

ディスパッチ前に、claim --repo <root> --follow-up <path> --base-sha <sha> を実行します。claimed <attempt-key> <owner> という結果の場合にのみディスパッチします。ワーカーの最初のアクションとして、ネイティブチェックアウトから bind --repo <root> --attempt-key <attempt-key> --owner <owner> --worktree <worktree> --branch <branch> を実行します。バインドに失敗した場合、ワーカーは編集を始めずに停止します。コーディネーターが最終結果を記録した後、ネイティブワークツリーを削除するのは Claude の役割です。

ネイティブ作成でこの保証を実現できない場合は、prepare を実行してワークツリーを作成・検証した後、そのディレクトリからトップレベルのヘッドレス Claude ワーカーを起動します。ネイティブサブエージェントがすでに保証する分離を重複させるためだけに、Claude CLI プロセスを入れ子にしてはなりません。

Codex のスケジュール済みタスク

スケジュール済みタスクはコーディネーター専用として扱います。そのバックグラウンドのワークツリーでは、項目ごとのワーカーは分離されません。対象となる各項目について、次の手順を実行します。

1. フォローアップのスラッグと短い試行 ID のサフィックスを含む名前で、一意のワークツリーパスとブランチを選びます。
2. prepare --repo <root> --follow-up <path> --worktree <path> --branch <branch> を実行します。prepared <worktree> <branch> <base-sha> <attempt-key> <owner> の場合にのみ続行します。並行処理中のスイープによってチェックアウトが作成されず、代わりに skipped-unchanged が返されることがあります。ディスパッチャーは作成前に正規のワークツリーの移動先を保存するため、中断された prepare は、匿名のチェックアウトになるのではなく、正確にクリーンアップできるよう、同じクレームオーナー、ワークツリー、予定ブランチとともに報告されます。
3. codex exec -C <worktree> --sandbox workspace-write <prompt> を使って、トップレベルの非対話型 Codex ワーカーを起動します。検証、プッシュ、プルリクエストの作成に必要なネットワーク権限と承認機能のみを設定します。

項目ごとの分離の代わりに、コーディネーターの作業ディレクトリを引き継ぐ書き込みサブエージェントを使用してはなりません。

ワーカー契約を適用する

境界を検証する

• 編集を始める前に、ワーカーの HEAD が指定されたベース SHA と一致することを確認します。
• 1 つのフォローアップファイルを読み、次の 5 つのフィールドをすべて確認します。症状、観察された証拠、推定原因、試したこと、提案する次のステップ。
• ワーカーの差分は選択した項目のみに限定します。ベース、チェックアウト、権限、または環境を検証できない場合は、blocked として停止します。

再現ゲートを通過する

• 製品ソースを変更する前に、記録されたコマンド、ルート、テスト、または環境を通じて症状を再現します。
• 失敗したアサーション、終了ステータス、観測可能な出力、実行時の状態など、具体的なベースラインの証拠を保持します。
• 範囲を限定した実行内で症状を再現できない場合は、試した内容と次に役立つ証拠を添えて not-reproduced を返します。推測に基づくソース変更や解決用プルリクエストは作成しません。

再現の結果、選定された項目の範囲外にある別の不具合が判明した場合は、選定された項目をそのまま維持し、新しい症状、観測された証拠、疑われる原因、試した内容、提案する次のステップをコーディネーターに返します。破棄されるワーカー内に唯一の記録を残してはいけません。コーディネーターは、これら5つのフィールドを受け取って、自身のチェックアウト内で project-knowledge を通じて記録を保存し、報告された docs/follow-ups/<symptom>.md のパスを保持します。ワーカーをクリーンアップする前に、その記録をコミットし、専用のレビュー待ちフォローアップ記録プルリクエストを公開します。選定された項目の解決用プルリクエストに混ぜてはいけません。コーディネーターのローカル変更や終了メッセージへの転記は、永続的な引き継ぎにはなりません。

修正する権限を確認する

• 現行のテスト、仕様、決定事項を定めた契約、サポート対象の実行時動作、または曖昧さのない互換性契約に基づいて、意図された動作を導き出します。
• 意図された結果がすでに確定しており、決定論的に検証できる場合にのみ続行します。
• 項目に製品上の判断、公開契約の変更、または重大なトレードオフが必要な場合は、パッチを作成せずに needs-shaping を返します。後続の shape-idea セッションで決定できるよう、未解決の選択肢を明示します。

証拠に基づいて修正する

• 最小限の一貫した修正を行い、利用可能な場合は安定した公開の接点を通じて、回帰チェックを追加または維持します。
• 意味のある候補変更を行うたびに再現を再実行します。新しい証拠が次の試行を裏付ける間だけ続行します。新しい証拠のない失敗の繰り返しは blocked として終了します。
• 対象を絞った決定論的チェックと、影響を受けるリポジトリでサポートされている実行時検証を実行します。静的チェックだけでは、実行時の症状は解消されません。
• 元の失敗が解消され、関連する回帰チェックが引き続きすべて成功した場合にのみ、項目を解決済みとして扱います。

結果を公開する

• 検証済みの修正と同じコミット系列内で、解決済みのフォローアップを削除します。Git の履歴がそのアーカイブになります。
• ワーカーブランチのみをプッシュし、レビュー待ちのプルリクエストを1つ作成します。修正前後の再現証拠、実行したチェック、残る不確実性を記載します。
• 別のフォローアップを一緒に含めてはいけません。また、プルリクエストをマージしてはいけません。
• URL を添えて pull-request を返します。公開または検証に失敗した場合は、解決済みと主張せず、フォローアップを保持して blocked を返します。

ワーカーの応答は、outcome、follow-up、base-sha、attempt-key、owner、該当する場合は pull-request、決定的な再現証拠またはブロッカーの証拠、および新たに見つかったコーディネーター向けのフォローアップ記録を含む簡潔なブロックで締めくくります。コーディネーターはこのブロックを使って正確な試行を記録します。説明文だけでは最終結果として扱えません。

各結果を記録してクリーンアップする

ワーカーから結果が返された後：

• プルリクエストの場合は、mark --repo <root> --follow-up <path> --base-sha <sha> --owner <owner> --outcome pull-request --detail <URL> を実行して、後続のスイープで重複しないようにします。
• プルリクエスト以外の結果の場合は、同じ mark コマンドで --outcome not-reproduced、--outcome needs-shaping、または --outcome blocked を指定し、決定的な証拠や次に有効な条件を簡潔に --detail で示します。別のワーカーが最初の終端結果を置き換えることはできません。記録された識別情報は破棄可能なローカル自動化状態であり、追跡対象のフォローアップにおけるステータスフィールドではありません。
• クリーンな状態で、ベースから一度も変更されていない非 PR ワーカーの場合は、cleanup を cleanup --repo <root> --worktree <worktree> --attempt-key <attempt-key> --owner <owner> として実行します。PR ワーカーの場合は、その正確な HEAD がリモートブランチで確認できた後にのみ、同じクリーンアップを実行します。このスクリプトは、その厳密なクレームに紐づけられたワークツリーのみを削除し、ローカルブランチは保持するため、クリーンアップが新しいチェックアウトと競合してその参照を削除することはありません。削除前にリポジトリ全体の座標予約を再検証し、共有リポジトリの設定を変更せず、分離された Git メタデータを通じてクリーンなサブモジュールを安全に初期化解除し、Git の最終的な dirty-worktree 拒否を有効なままにします。ダーティな対象、変更が未公開の対象、不一致の対象、所有者の異なる対象、リポジトリルートを対象とする場合は拒否します。
• 所有プロセスが mark の前に終了した場合は、まず紐づけられたブランチが公開済みか、既存のプルリクエストがあるかを確認します。プルリクエストが見つかった場合は mark で記録します。ブランチが公開済みでプルリクエストがない場合は、その公開を完了するか、明示的にブロックし、識別情報を破棄しないでください。公開されていない場合に限り、記録された紐づけ済みまたは準備中のワークツリーが存在すれば、まず cleanup を使用し、その後、正確な attempt key と owner を指定して recover を実行します。対象を永続化した後、そのパスを作成する前に準備が停止した場合は、クリーンアップをスキップして、不足している対象を直接復旧します。復旧では、所有権を解放する前に、厳密に一致する古い Git ワークツリー登録を削除します。復旧は、使用中のワークツリー、公開済みブランチ、終端結果を拒否します。準備中の対象は、チェックアウトがクリーンで、ベースにデタッチされた状態を維持している場合、または正確な prepare-owned ブランチを head の比較交換で削除できる場合にのみ削除されます。

pull-request、not-reproduced、needs-shaping、blocked、invalid-follow-up、skipped-unchanged のみを使用して、簡潔なスイープレポートを1つ作成します。各プルリクエストにはリンクを付け、その他の各結果には証拠または次の条件を記載します。保持されたフォローアップを修正済みと表現してはいけません。