deps-runner

目的

依存関係 PR の検証およびマージのパイプラインです。6 つの ICM ステージに順番に分割されています： scan/context → preflight baseline → risk-eval（単一のまとまったステージで、すべてのグループが対象） → build-test → merge-decision → report。各ステージは分離されたコンテキストで実行されます。重要な判断（リスク評価）は、専用のクリーンコンテキストステージで行われます。 単一の deps-runner スキルと動作上は同等で、ステージに分割されている点だけが異なります。

このスキルはオペレーターのセッションで実行され、ワーカーのライフサイクルを管理します。 ステージ 01 では対象リポジトリの devbox イメージを事前確認し、ワーカーを起動します。ステージ 02～05 はゲートウェイのワーカー API を介してそのワーカーを操作します（pylot-cli スキルの「§ Workers」を参照）。ステージ 06 でワーカーを停止します。gh CLI のみを必要とするステージ（scan-context、merge-decision のラベル付け／マージ処理、report）は、ワーカーに触れず、オペレーターのセッション内でインライン実行されます。

この手順は順次実行します。ファンアウトも、並列の Task 起動もありません。 リスク評価は、すべての依存関係グループを対象に、1 つのステージとして実行します。グループごとにサブエージェントを起動することはありません。ここで ICM を活用する利点は、判断ステップをクリーンコンテキストに隔離でき、ステージから再開できることであり、並列化ではありません。

ワーカーのライフサイクル

ワーカーは、対象リポジトリを実行する Fargate devbox です（pylot-cli の「§ Workers」を参照）。ステージ 01 でリポジトリを事前確認してワーカーを起動し、ステージ 02～05 で操作し、ステージ 06 で停止します。ワーカーの識別子（worker_id）はステージ 01 の引き継ぎ情報で確定し、その後の各ステージの引き継ぎ情報にも変更せずに引き継ぎます。これにより、たとえばステージ 04 のクリーンコンテキストサブエージェントは、オーケストレーターのシェル状態を一切参照せずに、ステージ 02 ですでにウォームアップされたワーカーを特定できます（Task サブエージェントはオーケストレーターの bash 変数を継承しません）。

必要な環境変数とワーカーのターンに関するルール

ワーカー手順には、3 つすべての環境変数が必要です：PYLOT_API（ゲートウェイのベース URL）、PYLOT_JOB_ID（すべてのワーカーコマンドに渡すミッション）、PYLOT_OPERATOR_TOKEN（ゲートウェイのオペレーター認証）。ワーカーを操作する前に、これらが使用可能であることを確認してください。pylot workers output が返すのは最新のターン結果のみです。後続のプロンプトを送信すると読み取り可能な出力が置き換わるため、次の pylot workers prompt を送信する前に、重要な結果をすべて読み取り、記録してください。

# Stage 01 — preflight (no task_def => no built image => cannot spawn)
pylot devboxes project "$REPO"

# Stage 01 — spawn (only if devboxes project reported a task_def)
SPAWN=$(pylot workers spawn --mission "$PYLOT_JOB_ID" repo="$REPO" \
  name="deps-runner-$(echo "$REPO" | tr '/' '-')")
printf '%s' "$SPAWN" > .procedure-output/deps-runner/01-scan-context/.spawn-raw.json  # recovery record before parsing
WID=$(printf '%s' "$SPAWN" | python3 -c 'import sys,json
try:
    print(json.load(sys.stdin).get("worker_id",""))
except Exception:
    print("")')

# Stages 02-05 — drive (each stage reads worker_id from the prior stage's handoff)
pylot workers prompt "$WID" --mission "$PYLOT_JOB_ID" --wait --timeout 600 "<instruction>"
pylot workers output "$WID" --mission "$PYLOT_JOB_ID"

# Stage 06 — stop, FIRST action, before writing the report, then confirm terminal state
pylot workers stop "$WID" --mission "$PYLOT_JOB_ID" --force
# poll `pylot workers list --mission "$PYLOT_JOB_ID"` for this worker's confirmed-stop shape —
# ecs_status == STOPPED, or (ecs_status null/absent and status == stopped with a non-empty
# stopped_at) — on a bounded budget before recording stopped: yes — see stage 06's CONTEXT.md

pylot devboxes project "$REPO" で task_def が報告されない場合、そのリポジトリにはビルド済みのワーカーイメージがありません。イメージのビルド（pylot deploy build-worker <org/repo> --wait）には管理者の認証情報が必要で、オペレーターには 403 が返されるため、この手順では自動修復できません。ステージ 01 の引き継ぎ情報に devbox_ready: false と記録し、ステージ 06 に進んでください。devbox がなければビルドもテストもできませんが、ステージ 06 ではブロックされたことを示すレポートを作成します。

再開した実行で、記録されている worker_id がすでに稼働していない場合（pylot workers view "$WID" --mission "$PYLOT_JOB_ID" の結果が stopped／reaped）、同じリポジトリ用の代替ワーカーを起動し、そのステージの引き継ぎ情報に新しい worker_id を記録して続行してください。新しい devbox はクリーンなチェックアウトから開始するため、パイプラインの残りの処理には影響しません。

引数

Param	Required	Default	Notes
repo	はい	—	対象の org/repo（位置引数 $0）
resume_from	いいえ	（最初から実行）	再開するステージ。例：04-build-test。完了したステージのディスク上の引き継ぎ情報を再利用し、それらのステージはスキップします。

$ARGUMENTS から解析します。次の形式を受け付けます：

• org/repo → 最初から実行
• org/repo resume_from=04-build-test → 実行を再開

実施内容

6 段階の逐次 ICM 手順です。

ステージ	モード	説明
01-scan-context	インライン	候補となる依存関係 PR を取得し、リポジトリとチームの CLAUDE.md を読み込み、リポジトリの devbox を事前確認してワーカーを起動し、PR をグループ化します
02-preflight-baseline	サブエージェント	ワーカー上で main のコンパイルとテストの成功を確認し、ベースラインを記録します。booster のリモート同期も行います
03-risk-eval	サブエージェント	単独のステージです。すべての依存関係グループを分類します（差分、依存関係の種類、直接使用状況、リスク）
04-build-test	サブエージェント	PR ごとに main をチェックアウトしてマージし、インストールとビルドを行います。ランタイムの場合は再起動し、ベースラインと比較してテストを実行します
05-merge-decision	サブエージェント	PR ごとにマージマトリックスを適用します。自動マージ／ラベル付け、対象を絞ったテストの作成、または Max への報告を行います
06-report	インライン	ワーカーを停止し、ローカルのレポートファイルを作成して、結果マーカーを出力します

どのステージも並列展開しません。ステージ 03 では、すべての依存関係グループを一貫した流れで評価します。グループごとにサブエージェントを起動しないでください。

引き継ぎ先

すべての引き継ぎファイルは、リポジトリの作業ディレクトリ内にあります。

.procedure-output/deps-runner/{stage}/handoff.md

ステージ 01 ではルートコンテキストを作成します。各サブエージェントのステージには、その CONTEXT.md に入力として記載された引き継ぎファイルのみを渡してください。オーケストレーターのコンテキスト全体は渡さないでください。

実行

ステージ 01（インライン）

ステージ 01 は自分で実行してください（オーケストレーターコンテキスト）。CONTEXT.md を読み込みます。

.claude/skills/deps-runner/stages/01-scan-context/CONTEXT.md

引き継ぎファイルを .procedure-output/deps-runner/01-scan-context/handoff.md に書き込みます。

ステージ 01 で devbox_ready: false が記録されている場合は、ステージ 02～05 をすべてスキップして、ステージ 06 に進んでください。操作するワーカーがいないためです。

ステージ 02 → 05（逐次サブエージェント — 一度に 1 つ）

各ステージを順番に実行し、Task を必ず 1 つだけ起動してください。次の Task を起動する前に、現在の Task の完了を待ってください。同じ応答内で 2 つのステージを起動しないでください。1 つのステージを複数の同時実行サブエージェントに分割しないでください。

各 Task のプロンプトは、それ単独で完結する内容にしてください。

• そのステージの入力となる引き継ぎファイルのパスのみを含めます（ステージの CONTEXT.md に記載されています）
• ステージの CONTEXT.md のパスを含めます
• オーケストレーターの履歴や、それまでの推論は渡さないでください

Task プロンプトのテンプレート：

You are running stage {NN}-{name} of the deps-runner procedure.

Read your stage instructions:
  .claude/skills/deps-runner/stages/{NN}-{name}/CONTEXT.md

Your inputs:
  {input handoff path(s) from that stage's CONTEXT.md}

Write your output to:
  .procedure-output/deps-runner/{NN}-{name}/handoff.md

Execute all steps in CONTEXT.md. Write handoff.md before exiting.

ステージの引き継ぎファイルにハードブロッカーが報告されている場合（事前確認の失敗、古い PR でのマージ競合、すべての PR でのビルド／テスト失敗）は、そのステージの Failure ルールに従って処理を続けてください。通常、ブロッカーは記録されて報告対象になりますが、レポートを必ず作成するため、実行はステージ 06 まで続行します。

Task 呼び出し自体が失敗した場合（サブエージェントでエラーが発生する、タイムアウトする、または handoff.md を一度も書き込まずに終了する場合）は、正常なステージ失敗として扱わず、上記のルールも適用しません（Failure ルールを確認するための引き継ぎファイルがありません）。この場合は、直接ハードブロッカーとして扱ってください。ステージを再試行せず、次のステージへ進もうとせず、実行を未完了のままにしないでください。直ちにステージ 06 に進み、worker_id が記録された最新の引き継ぎファイルから worker_id を読み取ってください（失敗したステージ自体の引き継ぎファイルは存在しないため、直前のステージのものを使用します）。ステージ 06 では、最初の操作としてそのワーカーを停止し、ブロックされたことを示すレポートを作成します。クラッシュしたサブエージェントによってワーカーを実行したままにしてはいけません。

ステージ 06（インライン）

ステージ 06 は自分で実行してください（オーケストレーターコンテキスト）。CONTEXT.md を読み込みます。

.claude/skills/deps-runner/stages/06-report/CONTEXT.md

最初の操作としてワーカーを停止してから、ローカルのレポートファイルを作成します。[pylot] outcome=... マーカーは、サブエージェントではなくオーケストレーターから出力してください。Quest への POST は行いません。ローカルのレポートファイルのみを書き込んでください。

Resume-from-stage

resume_from={NN-name} が設定されている場合：

1. resume_from より前のすべてのステージの引き継ぎファイルが、すでにディスク上に存在することを確認します。

   ls .procedure-output/deps-runner/*/handoff.md
   

2. 完了済みのステージを再実行してはいけません。引き継ぎファイルはそのまま後続ステージへの入力として再利用します。
3. 指定されたステージから実行を開始し、06-report まで順に続行します。
4. 必要な上流ステージの引き継ぎファイルが見つからない場合は、どのファイルがないかを報告して停止します。再開地点が無効なため、より前のステージから実行する必要があります。
5. ワーカーを駆動するステージ（02～05）から再開する場合は、記録されている worker_id がまだ稼働中であることを確認してから続行します（pylot workers view "$WID" --mission "$PYLOT_JOB_ID"）。stopped／reaped と表示された場合は再起動し、そのステージの引き継ぎファイルに新しい ID を記録します。

resume_from に指定できるステージ名：02-preflight-baseline、03-risk-eval、04-build-test、05-merge-decision、06-report。（01-scan-context は新規実行のため、再開は不要です。）

ステージの引き継ぎチェーン

01-scan-context (inline, preflights + spawns worker)
      │
      ▼
02-preflight-baseline ──► 03-risk-eval ──► 04-build-test ──► 05-merge-decision ──► 06-report (inline)
   (subagent, drives        (subagent,         (subagent,        (subagent,            stops worker,
    worker)                ALL groups,          drives            drives                reads all
                          single pass)          worker)           worker)               handoffs,
                                                                                         writes report)

worker_id は、01 から 06 までの各ステージ固有の引き継ぎファイルで変更せずに引き継ぎます。

終了パス

• 成功：ステージ 06 が [pylot:$PYLOT_OUTCOME_NONCE] outcome="deps-runner complete: {merged}/{total} merged, {flagged} flagged" status=success を出力します。
• 失敗：失敗したステージのブロッカーを受けて、オーケストレーターが [pylot:$PYLOT_OUTCOME_NONCE] outcome="deps-runner failed at stage NN: {reason}" status=failed を出力します。
• ブロック：プリフライトの失敗（メインがコンパイルされない）、または対象リポジトリに devbox イメージがない場合 → [pylot:$PYLOT_OUTCOME_NONCE] outcome="deps-runner blocked: {reason}" status=blocked

いずれの場合も、マーカーが出力される前にステージ 06 がローカルのレポートファイルを書き込みます。

厳守事項

1. 順次実行のみ — 1 回の応答につき Task は 1 つだけとし、各ステージの完了後に次のステージを開始します。どこでも Task を並列起動してはいけません。
2. ファンアウト禁止 — ステージ 03 では、すべての依存関係グループを一連のまとまった評価として扱います。グループ／PR／観点ごとにサブエージェントを起動してはいけません。PR は全体として評価します。
3. ステージ 01 はインラインで実行 — コンテキスト（PR リスト、CLAUDE.md、devbox のプリフライトとワーカーの起動）をここで確立します。
4. ステージ 06 はインラインで実行 — [pylot] outcome=... マーカーは必ずオーケストレーターが出力します。
5. QUEST 禁止 — Quest DB への POST、127.0.0.1:4242、quest.fellowship.dev、QUEST_TOKEN は使用しません。報告はローカルのレポートファイルのみです。
6. オーケストレーターのコンテキスト全体をサブエージェントの Task プロンプトに渡してはいけません — 入力のみを渡します。
7. 各ステージは、次のステージが読み取る前に handoff.md を書き込みます。また、worker_id は変更せずに引き継ぎ、チェーン全体を通じて保持します。
8. ステージを省略してはいけません — 実行内容が「何もしない」場合でも、すべてのステージを実行します（例：候補 PR が 0 件でもプリフライトを実行し、レポートを作成します）。ただし、ステージ 01 で devbox_ready: false が記録された場合は例外です。この場合、ワーカーなしではビルドもテストもできないため、02～05 をすべて省略して、ステージ 06 に直接進みます。
9. resume_from ではディスク上の引き継ぎファイルを再利用 — 完了済みのステージは再実行しません。上流の引き継ぎファイルがない場合、再開地点は無効なので停止して報告します。ワーカーを再度駆動する前に、引き継いだ worker_id がまだ稼働中であることを確認します。
10. 高リスクの変更を自動マージしてはいけません。 常に Max の確認対象としてフラグを付けます。すべてのマージに [skip ci] を付けます。
11. ワーカーを起動する前にリポジトリの devbox をプリフライト（pylot devboxes project）します。ビルド済みイメージのないリポジトリではワーカーを起動できません。その場合は devbox_ready: false を記録し、起動せずにステージ 06 へ直接進みます。
12. ステージ 06 では、レポートを書く前の最初のアクションとして、必ずワーカーを停止します。残されたワーカーは、手動で停止または回収されるまで Fargate のコンピューティングリソースを消費し続けます。
13. ステージレベルの例外はハードブロッカーであり、再試行してはいけません。 ステージ 02～05 の Task サブエージェントがエラーになった場合、タイムアウトした場合、または handoff.md を書き込まずに終了した場合、そのステージを再試行せず、次のステージにも進みません。worker_id が記録されている最新の引き継ぎファイルからその ID を使用して、ステージ 06 に直接進みます。これにより、ステージが正常に失敗を処理できずにクラッシュした場合もワーカーを停止できます。

参照ファイル

• CONTEXT.md — アーキテクチャの概要
• stages/NN-name/CONTEXT.md — 各ステージの入力、タスク、出力契約
• shared/report-template.md — ローカルレポートファイルのテンプレート（ステージ 06）
• shared/risk-matrix.md — リスク分類マトリックス＋マージ判断マトリックス（ステージ 03/05）