speckit-runner

リポジトリ $1 のイシュー $0 に対して speckit パイプラインを実行します。

あなたはセッション内で実行するオペレーターです。speckit の各フェーズを通じてプロデューサーを進行させ、そのプッシュ済みチェックポイントを PR 作成前に別のレビューワーカーに渡します。

ゲートウェイ：$PYLOT_API（または $PYLOT_GATEWAY_URL）。トークン：$PYLOT_DISPATCH_TOKEN。 ミッション：$PYLOT_JOB_ID。リポジトリ：$1（または $PYLOT_REPO）。

セッション開始時に、このクリーンアップを一度定義してください。EXIT トラップにより、早期失敗を含むすべての終了経路で、デタッチされたスーパーバイザーのチェックアウト削除が実行されます。

cleanup_supervisor_checkout() {
  if [ -n "${SUPERVISOR_CHECKOUT:-}" ] && [ -d "$SUPERVISOR_CHECKOUT" ]; then
    git worktree remove --force "$SUPERVISOR_CHECKOUT" >/dev/null 2>&1 || true
  fi
}
trap cleanup_supervisor_checkout EXIT

ワーカー API をポーリングして、ワーカーをフォアグラウンドで進行させてください。短いチャンクで、あなた自身が再実行します。 各フェーズのプロンプトをキューに入れたら、Bash ツールで Poll-to-idle スニペット（ステップ P）を実行してください。デフォルトの Bash タイムアウトを使用し、長い timeout は指定しないでください。 各呼び出しは 2 分未満で POLL_RESULT を返します。POLL_RESULT=running が表示されている間は、すぐにステップ P を再実行してください。約 30 分ごとに、ハートビートの経過時間、出力変更フラグ、ログ末尾を含む判断パケットとともに POLL_RESULT=block_elapsed が表示されます。内容を確認し、ワーカーが正常であれば、ステップ P を再実行して次のブロックを許可してください。POLL_RESULT=done が表示されるまで繰り返します。

トラップ（必ず読んでください）： ハーネスは、ツールの timeout（デフォルトで約 120 秒）を超えて実行される Bash コマンドを自動的にバックグラウンド化します。ポーリングがバックグラウンド化されると致命的です。バックグラウンドタスクの完了通知が表示されることがありますが、それを待つ理由にしないでください。 その通知は、セッションがツール呼び出しをアクティブに実行している間だけ発生します。「完了を待つ」ためにターンを終了した瞬間、ヘッドレスの claude -p セッションが終了し、ワーカーが正常なままでもミッションは失敗として確定されます。つまり、ステップ P に長い Bash timeout を決して設定しないでください。バックグラウンド化しないでください。通知を待たないでください。ワーカーのターンが進行中のままターンを終了しないでください。ステップ P がバックグラウンド化された場合は、それをバグとして扱い、終了させてから再実行してください。各呼び出しは、あなたが実行し、出力を読み、再実行する、短時間の同期シェルです。

---

ステップ 0：開始前の照合

何かを起動する前に、ターミナル上のイシューの状態と、すでに開いている PR の両方を確認してください。 ここが再開の境界です。再実行時には、別の PR を作成せず、既存の PR を報告する必要があります。

REPO="${1:-$PYLOT_REPO}"
ISSUE_STATE=$(gh issue view $0 --repo "$REPO" --json state --jq '.state' 2>/dev/null || echo "OPEN")
if [ "$ISSUE_STATE" = "CLOSED" ]; then
  echo "[speckit-runner] already complete — issue $0 is CLOSED"
  exit 0
fi

OPEN_PRS=$(gh pr list --repo "$REPO" --state open --limit 100 \
  --json number,url,headRefName,closingIssuesReferences 2>/dev/null || echo '[]')
EXISTING_PR=$(printf '%s' "$OPEN_PRS" | jq -c --argjson issue "$0" --arg repo "$REPO" '
  [.[] | select(any(.closingIssuesReferences[]?;
    .number == $issue and ((.repository.owner.login + "/" + .repository.name) == $repo)))][0] // empty')

# A pushed checkpoint may not have a PR yet. If exactly one remote branch has
# an issue-number segment, also reconcile an open PR by its exact head ref.
BRANCH_CANDIDATES=$(gh api "repos/$REPO/branches" --paginate --jq '.[].name' 2>/dev/null \
  | awk -v n="$0" '$0 ~ ("(^|[-_/])" n "($|[-_/])")')
if [ "$(printf '%s\n' "$BRANCH_CANDIDATES" | sed '/^$/d' | wc -l | tr -d ' ')" = "1" ]; then
  RESUME_BRANCH=$(printf '%s\n' "$BRANCH_CANDIDATES" | sed '/^$/d')
  HEAD_PR=$(printf '%s' "$OPEN_PRS" | jq -c --arg head "$RESUME_BRANCH" \
    '[.[] | select(.headRefName == $head)][0] // empty')
  [ -n "$EXISTING_PR" ] || EXISTING_PR="$HEAD_PR"
fi
if [ -n "$EXISTING_PR" ]; then
  PR_URL=$(printf '%s' "$EXISTING_PR" | jq -r '.url')
  echo "[speckit-runner] resume reconciliation found existing PR: $PR_URL"
  exit 0
fi

どちらかの照合分岐を終了した場合は、解決済みマーカーを最終アシスタント行全体として出力し（Bash からでもコードフェンス内でもなく）、その後停止してください。

• クローズ済みイシュー：[pylot:$PYLOT_OUTCOME_NONCE] outcome="already complete — issue $0 is CLOSED" status=success
• 既存の PR：[pylot:$PYLOT_OUTCOME_NONCE] outcome="resume reconciliation found existing PR: $PR_URL" status=success

outcome="already complete" が有効なのはこの場合のみです。イシューが実際に CLOSED の場合に限ります。タイムアウトや通知の欠落を理由に、決して出力しないでください。 開いている PR もこの実行では終了条件ですが、「すでに完了」ではなく、照合済みの既存 PR として報告してください。クローズとの正確な紐付けを優先し、一意なチェックポイントブランチであれば、完全一致する head を代替手段として使用します。PR が存在しない場合は、その一意な RESUME_BRANCH をワーカーに渡し、そのチェックポイントがイシューと一致する場合にのみ再開してください。一致候補が曖昧な場合は参考情報として扱い、推測せずデフォルトブランチから開始してください。

---

ステップ 1：ワーカーを起動する

REPO="${1:-$PYLOT_REPO}"
SPAWN_RESP=$(curl -s --max-time 90 -X POST \
  -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"repo\": \"$REPO\"}" \
  "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers")
WID=$(echo "$SPAWN_RESP" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("worker_id",""))' 2>/dev/null)
if [ -z "$WID" ]; then
  echo "[speckit-runner] worker spawn failed: $(echo $SPAWN_RESP | head -c 200)"
  exit 1
fi
echo "[speckit-runner] worker spawned: $WID"

ワーカーの起動に失敗した場合は、解決済みの次のマーカーをアシスタントの最終行全体として（Bash からではなく、コードフェンス内でもなく）出力してから、停止してください。

[pylot:$PYLOT_OUTCOME_NONCE] outcome="worker spawn failed: $(echo $SPAWN_RESP | head -c 200)" status=failed

このスキルには、このファイルと同じ場所に poll-worker.sh ヘルパーが含まれています。boot-sync がスキルディレクトリ全体をコピーするため、オペレーター側の ~/.claude/skills/speckit-runner/poll-worker.sh に配置されます。これはワーカーをポーリングする唯一の方法です（ステップ P を参照）。ポーリングループをインラインで独自に作成したり、通知を待ったりしないでください。

同じ boot-sync では、invariant-matrix フローで使用する 2 つのバリデーター実行ファイルも配置されます。どちらも ~/.claude/skills/speckit-runner/<name>.sh に配置されます。

• validate-invariant-matrix.sh MATRIX — スキーマゲートです。単一の TSV マトリックスについて、ヘッダー、13 列、安定した INV-NNN ID、許可された class／state の値、出所／エビデンスの完全性、実在する repository／checkpoint／receipt を含む passed／failed 行をチェックします。ステップ 4.5 の監督者による照合と、正規スキーマのフィクスチャおよび永続化された計画マトリックスの両方を検証するテストスイートで使用されます。
• validate-review-output.sh MATRIX REVIEW — スキーマゲートの通過後に実行する網羅性ゲートです。すでにスキーマゲートを満たしているマトリックスに対して、独立したレビュアーの出力をチェックします。該当するすべての行に、正確に 1 つの ROW INV-NNN verdict=... 行（または異議を唱える FINDING）が必要です。網羅性は完全でなければならず、形式が不正なマトリックスは即座に拒否されます。ステップ 5 で、FIRST_REVIEW_STATUS=available と unavailable のどちらにするかを判断するために使用されます。

この 2 つを組み合わせることで、2 段階のゲートが形成されます。レビュアーの出力に対して網羅性を検証する前に、マトリックスはスキーマゲートを通過しなければなりません。構造が無効なマトリックスが網羅性チェックに進むことはありません。

---

ステップ P：ポーリングしてアイドル状態になる（ヘルパーを実行し、RUNNING の間は繰り返す）

フェーズプロンプトをキューに入れた後は、Bash ツールで同梱のヘルパーを実行する方法のみでポーリングしてください（デフォルトのタイムアウトを使用し、長いタイムアウトを指定しないでください）。

bash ~/.claude/skills/speckit-runner/poll-worker.sh "$WID" "$TURN_SEQ"

最終行を確認してください。

• POLL_RESULT=done（終了コード 0）→ ワーカーはこのターンで完了しました。出力にフェーズマーカーが含まれています。次に進んでください。
• POLL_RESULT=running（終了コード 10）→ ワーカーは正常に動作しており、作業中です。まったく同じコマンドをもう一度実行してください（WID／TURN_SEQ を再度インラインで指定してください。スクリプトは状態ファイルを使って累積タイマーを引き継ぎます）。実装フェーズではこの呼び出しが何度も必要になります。続けてください。
• POLL_RESULT=block_elapsed（終了コード 20）→ ポーリングブロック（デフォルト 30 分）が経過しました。ワーカーは停止しておらず、作業を続けている可能性が非常に高い状態です。スクリプトは heartbeat_age、output_changed、ワーカー出力の末尾を含む判断パケットを出力します。判断してください。主なシグナルは heartbeat_age です。
  • ハートビートが新しい（約 5 分未満）→ まったく同じコマンドをもう一度実行してください。 これにより、次のブロックが許可されます。正常なワーカーの場合、これがデフォルトの対応です。実装に時間がかかるターンでは、複数のブロックが正当に必要になります。時間が経ったというだけで、正常なワーカーを失敗扱いにしないでください。ターンの途中で output_changed=empty になるのは通常の状態です（ワーカーの出力はターン終了時にのみ反映されます）。停滞の兆候ではありません。
  • ハートビートが古い（10 分超、W_STATE はまだ running）→ ワーカーは応答不能です。 ステップ C を実行し、パケットの内容を引用した失敗結果を出力してください。連続するブロックで output_changed=no になることは補足的な証拠にすぎず、それだけでは決して十分ではありません。
• POLL_RESULT=ceiling_timeout（終了コード 1）→ ターンごとのハード上限（デフォルト 4 時間）に達しました。現在のワーカーはスクリプトによってすでに停止されています。ステップ C を実行してから、失敗結果を出力してください。

設計上、各呼び出しは 2 分未満で返るため、バックグラウンド化されることはありません。ポーリングループを独自に作成したり、Bash の timeout に長い時間を設定したり、呼び出しをバックグラウンドで実行したり、通知を待ったり、ワーカーのターンが実行中のままターンを終了したりすることは決してしないでください。これらはいずれも正常なワーカーを放棄することになり、ミッションの失敗につながります。

---

ステップ C：常時実行するクリーンアップ + 再開レシート

成功、部分的な成功、ブロック、失敗を問わず、すべての終了処理の前に実行します。 プッシュ済みの Git チェックポイントを保持したまま、起動したすべてのワーカーを停止します。また、次回の実行で照合できるよう、正確なリモートの HEAD を出力します。

for WORKER_ID in "${WID:-}" "${RWID:-}"; do
  [ -z "$WORKER_ID" ] || curl -s --max-time 30 -X POST \
    -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
    "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${WORKER_ID}/stop" >/dev/null 2>&1 || true
done

if [ -n "${BRANCH:-}" ]; then
  SAVED_HEAD=$(gh api "repos/$REPO/git/ref/heads/$BRANCH" --jq '.object.sha' 2>/dev/null || true)
  [ -z "$SAVED_HEAD" ] || echo "[speckit-runner] resume branch=$BRANCH head=$SAVED_HEAD"
fi

プロデューサーの失敗は通常どおり失敗／ブロックの結果になりますが、その結果を出すのはステップ C の実行後に限ります。レビュアーの失敗は異なります。レビュアーのみを停止し、レビューを利用不可として記録して、プロデューサーのチェックポイントを使って続行します。

---

ステップ 2：speckit.preflight — 事前確認 + 仕様作成

プロンプトをキューに追加し、ステップ P に従ってポーリングします：bash ~/.claude/skills/speckit-runner/poll-worker.sh "$WID" "$TURN_SEQ" を実行し、POLL_RESULT=running の間は再実行します。

PROMPT=$(python3 -c "import json,sys; print(json.dumps('You are a worker running inside repo $REPO. Issue: #$0.\n\nPre-Flight (MANDATORY — do this FIRST):\n1. Fetch issue: gh issue view $0 --repo $REPO --json title,body,labels,comments\n2. Check if closed: if CLOSED, emit [pylot:$PYLOT_OUTCOME_NONCE] outcome=\"already complete\" status=success and exit.\n3. Verify required labels exist (create '\''in-progress'\'' if missing).\n4. Gather real data: read issue comments, fetch referenced URLs, read existing code patterns.\n\nResume or Specify:\n5. Fetch origin and inspect remote branches whose names identify issue $0. Resume only when exactly one candidate has an existing checkpoint/spec matching this issue; otherwise update the default branch and start clean. Never create or duplicate a PR in this phase.\n6. Bootstrap speckit scaffolding if absent: if [ ! -f \".specify/scripts/bash/create-new-feature.sh\" ]; then /setup-speckit; fi\n7. If the resumed branch already has a valid specification for this issue, continue it. Otherwise run: /speckit-specify $0\n8. Read the generated specification. If there are open questions, answer them from pre-flight data, then run /speckit-clarify.\n9. Set BRANCH=\$(git branch --show-current), commit any completed specification checkpoint, and push the branch.\n\nWhen done: emit [pylot] phase=preflight status=done branch=\$BRANCH head=\$(git rev-parse HEAD)'))")
PROMPT_RESP=$(curl -s --max-time 30 -X POST \
  -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"prompt\": $PROMPT}" \
  "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${WID}/prompt")
TURN_SEQ=$(echo "$PROMPT_RESP" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("turn_seq",""))' 2>/dev/null)
echo "[speckit-runner] preflight prompt queued (turn_seq=$TURN_SEQ)"

今すぐ ステップ P に従ってポーリングします — bash ~/.claude/skills/speckit-runner/poll-worker.sh "$WID" "$TURN_SEQ" を実行し、POLL_RESULT=running の間は再実行します。POLL_RESULT=done が出力されたら、出力されたワーカーの結果を確認し、phase=preflight status=done があることを確かめます。見つからない場合、または status=failed の場合は、ステップ C を実行して失敗の結果を出します。

事前確認が成功したら、last_output を取得し、そのマーカーから BRANCH を設定して、出力された HEAD がリモートの HEAD と一致することを確認します。以降のすべてのステップ C のレシートで BRANCH を保持します。

---

ステップ 3：speckit.plan — 計画 + タスク

プロンプトをキューに追加し、ステップ P に従ってポーリングします：bash ~/.claude/skills/speckit-runner/poll-worker.sh "$WID" "$TURN_SEQ" を実行し、POLL_RESULT=running の間は再実行します。

PROMPT=$(python3 -c "import json; print(json.dumps('Continue on the feature branch from the previous phase.\nRun: /speckit-plan $0\nRead the generated plan and verify the approach.\nRun: /speckit-tasks $0\nRead the generated tasks and verify they are concrete.\n\nDerive the durable invariant matrix described by ~/.claude/skills/speckit-runner/references/invariant-matrix.md from issue, spec, tasks, and trusted repository evidence. Inspect every discovery class, emit every source-backed boundary and no row for an unsupported class, and persist specs/<feature>/invariant-matrix.tsv with stable IDs and initial states. Commit and push the completed planning checkpoint so a later invocation can resume it.\nWhen done: emit [pylot] phase=plan status=done branch=\$(git branch --show-current) head=\$(git rev-parse HEAD), followed by MATRIX RECEIPT path=<path> repository=$REPO checkpoint=\$(git rev-parse HEAD)'))")
PROMPT_RESP=$(curl -s --max-time 30 -X POST \
  -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"prompt\": $PROMPT}" \
  "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${WID}/prompt")
TURN_SEQ=$(echo "$PROMPT_RESP" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("turn_seq",""))' 2>/dev/null)
echo "[speckit-runner] plan prompt queued (turn_seq=$TURN_SEQ)"

今すぐ ステップ P に従ってポーリングします — bash ~/.claude/skills/speckit-runner/poll-worker.sh "$WID" "$TURN_SEQ" を実行し、POLL_RESULT=running の間は再実行します。POLL_RESULT=done が出力されたら、出力されたワーカーの結果を確認し、phase=plan status=done があることを確かめます。ブロックまたは失敗した場合は、ブロック／失敗の結果を出す前にステップ C を実行します。

成功したら、計画マーカーのブランチと HEAD が、同じリモートブランチと一致することを確認します。これにより、実装開始前に再開用チェックポイントが進んだことを確認できます。

---

ステップ 4：speckit.implement — 実装 + 検証 + チェックポイント

プロデューサーはレビュー可能なチェックポイントを実装してプッシュしますが、まだ PR は作成しません。このプロンプトをキューに追加し、ステップ P に従ってポーリングします。

PROMPT=$(python3 -c "import json; print(json.dumps('Continue on the feature branch. Run: /speckit-implement $0\nAfter implementation:\n- Run the repository-defined verification for the affected behavior and fix failures.\n- Exercise the changed behavior through the strongest practical interface available in this repository.\n- Run: /speckit-analyze $0 && /speckit-checklist $0; resolve concrete gaps they find.\n- Commit every intended implementation and specification change, then push the current branch.\n- Do NOT create a PR. This pushed head is the independent-review checkpoint.\nWhen done, emit one marker line: [pylot] phase=implement status=done branch=\$(git branch --show-current) head=\$(git rev-parse HEAD). Then provide a concise CHECKPOINT EVIDENCE block containing the exact verification commands, pass/fail results, behavior exercised, and evidence asset ids or receipts (or explicit N/A).'))")
PROMPT_RESP=$(curl -s --max-time 30 -X POST \
  -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" -H "Content-Type: application/json" \
  -d "{\"prompt\": $PROMPT}" \
  "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${WID}/prompt")
TURN_SEQ=$(echo "$PROMPT_RESP" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("turn_seq",""))' 2>/dev/null)
echo "[speckit-runner] implement prompt queued (turn_seq=$TURN_SEQ)"

done になるまでポーリングし、その後ワーカーの結果を再取得して、出力されたブランチを抽出します。続行する前に、リモートブランチが出力された HEAD を指していることを確認します。

PRODUCER_STATE=$(curl -s --max-time 20 -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
  "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${WID}")
PRODUCER_OUT=$(printf '%s' "$PRODUCER_STATE" | jq -r '.last_output // ""')
BRANCH=$(printf '%s' "$PRODUCER_OUT" | sed -n 's/.*phase=implement status=done branch=\([^ ]*\).*/\1/p' | tail -1)
HEAD_SHA=$(printf '%s' "$PRODUCER_OUT" | sed -n 's/.*phase=implement status=done.* head=\([0-9a-f]*\).*/\1/p' | tail -1)
REMOTE_SHA=$(gh api "repos/$REPO/git/ref/heads/$BRANCH" --jq '.object.sha')
test -n "$BRANCH" && test "$HEAD_SHA" = "$REMOTE_SHA"

マーカーまたはリモート HEAD との一致を確認できない場合は、ステップ C を実行してプロデューサーの失敗を報告します。CHECKPOINT EVIDENCE は参考情報として役立ちますが、検証レシートにはなりません：プロデューサーがこれを報告することはできますが、チェックの合格を証明するものではありません。

---

ステップ 4.5：スーパーバイザー主導の検証

オペレーターがプロデューサーに代わって、変更できないプッシュ済みの HEAD_SHA を対象に、プロデューサーが編集できないデタッチされたチェックアウトで、想定されるチェックを特定して実行します。

SUPERVISOR_CHECKOUT=$(mktemp -d)
git fetch origin "$BRANCH"
git worktree add --detach "$SUPERVISOR_CHECKOUT" "$REMOTE_SHA"

そのデタッチされたチェックアウトで、リポジトリが定める検証項目の特定を行います。タスク／仕様と、リポジトリ独自のコントリビューター、エージェント、ビルド、CI、テストに関する指示を読みます。それらの情報源でこの変更に必要とされるすべてのチェックを特定してください。この共有スキル内で言語、フレームワーク、慣例的なファイル名、コマンド一式をハードコードしてはいけません。また、プロデューサーの「テストは通過した」という主張をもとにチェックを作り出してはいけません。スーパーバイザーのチェックアウトから、自分で特定した各コマンドを実行してください。プロデューサーに指示して実行させてはいけません。

チェックポイントの specs/<feature>/invariant-matrix.tsv を読み込み、references/invariant-matrix.md に照らして検証します。行の状態を調整するのはスーパーバイザーだけです。レビュー済みチェックポイントとリポジトリまたはチェックポイント全体が異なる、実行済みのレシートにはすべて stale を設定し、その後、新たに観測した各チェックを対応する行に passed、failed、または unavailable として記録します。以前のレシートのテキストと検出事項 ID は保持してください。プロデューサーの要約、レビュアーの記述、説明文だけの結果によって passed にすることはできません。調整済みマトリックスのパスと各行の状態を SUPERVISOR_VERIFICATION に含めてください。

調整済みマトリックスはスーパーバイザーが所有するシリアライズ済み成果物であり、デタッチされたチェックアウト内で編集するものではありません。SUPERVISOR_MATRIX には TSV の完全な内容を、SUPERVISOR_MATRIX_RECEIPT には repository=$REPO checkpoint=$REMOTE_SHA を設定し、使用するたびに両方の識別情報を検証します。レビュー、修正、最終レビュー、再開、PR の各プロンプトには、両方の値をそのまま埋め込んでください。ブランチ上のコピーは計画記録のままにします。プロデューサーがこれを調整したり、この成果物を要約で置き換えたりしてはいけません。再開時は、以前のエビデンスを利用する前に、調整済みのリモート HEAD で成果物を再構築してください。

次に、プレーンな Markdown 形式で検証の要約を作成します。想定されるチェックごとに 1 行とし、チェックの識別情報、コマンドの原文、観測された結果を記載します。結果は終了ステータスが 0 の場合のみ passed とし、それ以外は実際の終了ステータスを添えて failed、理由を添えて not-run、または不足しているランタイム／認証情報を明記して unavailable とします。

SUPERVISOR_VERIFICATION="verified at head $REMOTE_SHA:
- <check id>: <command> — <passed|failed (exit N)|not-run: reason|unavailable: reason>
..."

この要約は、レビュー、修正、PR の各ステップで利用できるようにしておきます。セッションの EXIT トラップは、どの終了経路でもデタッチされたワークツリーを削除します。

---

ステップ 5：独立したアドバイザリーレビュー

同じリポジトリで、2 人目の LLM ワーカーを起動します。ワーカーにはイシュー、ブランチ、差分、スーパーバイザーの検証要約、PR で提示する主張を渡します。プロデューサーの根拠は渡しません。ワーカーはクリーンなチェックアウトから開始し、その検出事項は助言として扱います。

FIRST_REVIEW_STATUS="unavailable"
REVIEW_OUT="Independent review unavailable: reviewer did not start."
REVIEW_SPAWN=$(curl -s --max-time 90 -X POST \
  -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" -H "Content-Type: application/json" \
  -d "{\"repo\": \"$REPO\"}" \
  "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers")
RWID=$(printf '%s' "$REVIEW_SPAWN" | jq -r '.worker_id // empty')
if [ -n "$RWID" ]; then
REVIEW_PROMPT=$(BRANCH="$BRANCH" SUPERVISOR_VERIFICATION="$SUPERVISOR_VERIFICATION" SUPERVISOR_MATRIX="$SUPERVISOR_MATRIX" SUPERVISOR_MATRIX_RECEIPT="$SUPERVISOR_MATRIX_RECEIPT" python3 -c "import json,os; print(json.dumps('Independently review issue #$0 in $REPO and pushed branch ' + os.environ['BRANCH'] + ' from a clean checkout. Read the issue, spec, tasks, trusted repository guidance, merge-base diff, and supervisor-owned matrix and receipts below. Do not request or use producer rationale. Do not edit, commit, push, or create a PR.\n\nAttempt to falsify every applicable invariant row by ID. For each surviving row emit exactly: ROW INV-NNN verdict=no-findings. For each challenge emit exactly one line: FINDING F-NNN row_id=INV-NNN priority=P0..P3 status=open evidence=<concrete evidence> suggested_action=<action>. A source-backed omission uses row_id=OMITTED. Cover every applicable row exactly once; unsupported classes need no row. Findings are advisory.\n\nSUPERVISOR MATRIX RECEIPT:\n' + os.environ['SUPERVISOR_MATRIX_RECEIPT'] + '\nSUPERVISOR MATRIX:\n' + os.environ['SUPERVISOR_MATRIX'] + '\nSUPERVISOR VERIFICATION:\n' + os.environ['SUPERVISOR_VERIFICATION'] + '\n\nEnd with [pylot] phase=independent-review status=done actionable=yes|no.'))")
REVIEW_RESP=$(curl -s --max-time 30 -X POST \
  -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" -H "Content-Type: application/json" \
  -d "{\"prompt\": $REVIEW_PROMPT}" \
  "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${RWID}/prompt")
REVIEW_SEQ=$(printf '%s' "$REVIEW_RESP" | jq -r '.turn_seq // empty')
if [ -z "$REVIEW_SEQ" ]; then
  REVIEW_OUT="Independent review unavailable: reviewer prompt was not accepted."
  curl -s --max-time 20 -X POST -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
    "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${RWID}/stop" >/dev/null 2>&1 || true
  RWID=""
fi
fi

RWID が存在する場合は、Step P ではなく、専用の有界ヘルパーでポーリングします。

bash ~/.claude/skills/speckit-runner/poll-reviewer.sh "$RWID" "$REVIEW_SEQ"

最後の行が REVIEW_POLL_RESULT=running の場合に限り、再実行してください。各呼び出しは短時間とし、レビュー全体の上限は 15 分です。done の場合は、以下の出力チェックに進めます。unavailable は、ヘルパーがすでにレビュアーを停止したことを意味します。REVIEW_OUT に利用不可の理由を設定し、FIRST_REVIEW_STATUS=unavailable を維持し、ヘルパーがレビュアーを停止したため RWID="" を設定して、ステップ 6 に進みます。レビュアーの結果を、Step P のプロデューサー失敗／ミッション停止処理に回してはいけません。

if [ -n "$RWID" ]; then
  REVIEW_STATE=$(curl -s --max-time 20 -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
    "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${RWID}")
  REVIEW_OUT=$(printf '%s' "$REVIEW_STATE" | jq -r '.last_output // ""')
  REVIEW_FILE=$(mktemp)
  MATRIX_FILE=$(mktemp)
  printf '%s\n' "$REVIEW_OUT" >"$REVIEW_FILE"
  printf '%s\n' "$SUPERVISOR_MATRIX" >"$MATRIX_FILE"
  if bash ~/.claude/skills/speckit-runner/validate-review-output.sh "$MATRIX_FILE" "$REVIEW_FILE"; then
    FIRST_REVIEW_STATUS="available"
  else
    FIRST_REVIEW_STATUS="unavailable"
    REVIEW_OUT=$(printf 'Independent review unavailable: reviewer output was incomplete or malformed.\nPreserved raw output below is advisory only; do not treat it as complete coverage.\n\n%s\n' "$REVIEW_OUT")
    curl -s --max-time 20 -X POST -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
      "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${RWID}/stop" >/dev/null 2>&1 || true
    RWID=""
  fi
  rm -f "$REVIEW_FILE" "$MATRIX_FILE"
fi

---

ステップ 6：プロデューサーによる 1 回限りの修正

独立した提案をプロデューサーに 1 回だけ送ります。プロデューサーは変更内容と、採用しなかった提案がある場合はその理由を記録する必要があります。修正を無期限に繰り返してはいけません。

CORRECTION_PROMPT=$(REVIEW_OUT="$REVIEW_OUT" SUPERVISOR_MATRIX="$SUPERVISOR_MATRIX" SUPERVISOR_MATRIX_RECEIPT="$SUPERVISOR_MATRIX_RECEIPT" python3 -c "import json,os; print(json.dumps('''This is the one bounded correction pass before PR creation. Independently assess the review suggestions below against the issue and repository. Implement the high-value valid corrections; decline inapplicable or disproportionate suggestions with a concrete reason. Preserve every invariant row ID, evidence state, receipt, and finding ID; record each finding as resolved or declined with its disposition. The supervisor-owned matrix below is read-only producer context. If the pushed head changes, treat all unmatched executed matrix receipts as stale pending fresh supervisor verification; producer prose must not restore passed. Re-run the repository-defined verification plus /speckit-analyze $0 and /speckit-checklist $0, commit any changes, and push the branch. Do not create a PR yet. Emit [pylot] phase=correction status=done branch=\$(git branch --show-current) head=\$(git rev-parse HEAD), followed by a concise CORRECTION SUMMARY that lists each suggestion as resolved or declined with rationale and records the latest verification results.

SUPERVISOR MATRIX RECEIPT:
''' + os.environ['SUPERVISOR_MATRIX_RECEIPT'] + '''
SUPERVISOR MATRIX:
''' + os.environ['SUPERVISOR_MATRIX'] + '''

INDEPENDENT REVIEW:
''' + (os.environ.get('REVIEW_OUT') or 'Review unavailable; verify the checkpoint yourself and report that independent review evidence was unavailable.'))) ")
CORRECTION_RESP=$(curl -s --max-time 30 -X POST \
  -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" -H "Content-Type: application/json" \
  -d "{\"prompt\": $CORRECTION_PROMPT}" \
  "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${WID}/prompt")
TURN_SEQ=$(printf '%s' "$CORRECTION_RESP" | jq -r '.turn_seq // empty')

プロデューサーを done になるまでポーリングします。提案が残っている場合でも、修正はこの 1 回限りです。レシートを取得して検証します。

CORRECTION_STATE=$(curl -s --max-time 20 -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
  "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${WID}")
CORRECTION_OUT=$(printf '%s' "$CORRECTION_STATE" | jq -r '.last_output // ""')
if ! printf '%s' "$CORRECTION_OUT" | grep -q 'phase=correction status=done' \
  || ! printf '%s' "$CORRECTION_OUT" | grep -q 'CORRECTION SUMMARY'; then
  CORRECTION_VALID="no"
else
  CORRECTION_HEAD=$(printf '%s' "$CORRECTION_OUT" | sed -n 's/.*phase=correction status=done.* head=\([0-9a-f]*\).*/\1/p' | tail -1)
  CORRECTION_REMOTE_HEAD=$(gh api "repos/$REPO/git/ref/heads/$BRANCH" --jq '.object.sha' 2>/dev/null || true)
  if [ -n "$CORRECTION_HEAD" ] && [ "$CORRECTION_HEAD" = "$CORRECTION_REMOTE_HEAD" ]; then
    CORRECTION_VALID="yes"
  else
    CORRECTION_VALID="no"
  fi
fi

CORRECTION_VALID=no の場合は Step C を実行し、保存済みのブランチレシートとともにプロデューサー失敗を出力します。レビューまたは PR の作成には進まないでください。

---

ステップ 6.5：修正後の再検証

修正によって新しい HEAD がプッシュされた可能性があります。その境界を越えて passed の結果を引き継いではいけません。CORRECTION_HEAD がステップ 4.5 で検証した HEAD と異なる場合は、古いサマリーを破棄し、CORRECTION_HEAD でステップ 4.5 のリポジトリ管理の検出とスーパーバイザーの実行を繰り返してください。

if [ "$CORRECTION_HEAD" != "$REMOTE_SHA" ]; then
  echo '[speckit-runner] correction moved HEAD; re-verifying at the new head'
  cleanup_supervisor_checkout
  SUPERVISOR_CHECKOUT=$(mktemp -d)
  git fetch origin "$BRANCH"
  git worktree add --detach "$SUPERVISOR_CHECKOUT" "$CORRECTION_HEAD"
  cd "$SUPERVISOR_CHECKOUT"
  # Repeat Step 4.5 discovery and execution here, then rebuild
  # SUPERVISOR_VERIFICATION with "verified at head $CORRECTION_HEAD:".
  # Rebuild SUPERVISOR_MATRIX from those observations and set
  # SUPERVISOR_MATRIX_RECEIPT="repository=$REPO checkpoint=$CORRECTION_HEAD".
fi

新たなチェックが失敗、未実行、または利用不可の場合も、処理を続行してください。最終サマリーには正確な状態をそのまま記載する必要があります。いずれも PR 作成を妨げるものではありません。

---

ステップ 7：任意の最終アドバイザリーレビュー

最初のレビューで actionable=yes と報告された場合、または修正によってプッシュされた HEAD が変更された場合は、更新後のリモート HEAD を確認するよう、レビュー担当者にもう一度だけ依頼してください。最初に挙げられた懸念のうち、解消されたものと残っている提案だけを尋ねてください。プロデューサーによる修正処理を再度開始してはいけません。最初のレビューで対応可能な提案がなかった場合は、RESIDUAL_REVIEW="No residual suggestions." を設定し、このターンをスキップしてください。

最終レビューは引き続きアドバイザリーです。残っている提案は開示のために保存してください。残っているという理由だけで、ミッションを妨げるものにしてはいけません。

RUN_FINAL_REVIEW="no"
if printf '%s' "$REVIEW_OUT" | grep -q 'actionable=yes' \
  || { [ -n "${CORRECTION_HEAD:-}" ] && [ "$CORRECTION_HEAD" != "$HEAD_SHA" ]; }; then
  RUN_FINAL_REVIEW="yes"
fi

if [ "$FIRST_REVIEW_STATUS" = "available" ] && [ -n "$RWID" ] \
  && [ "$RUN_FINAL_REVIEW" = "yes" ]; then
  FINAL_REVIEW_PROMPT=$(CORRECTION_OUT="$CORRECTION_OUT" SUPERVISOR_VERIFICATION="$SUPERVISOR_VERIFICATION" SUPERVISOR_MATRIX="$SUPERVISOR_MATRIX" SUPERVISOR_MATRIX_RECEIPT="$SUPERVISOR_MATRIX_RECEIPT" python3 -c "import json,os; print(json.dumps('Re-fetch branch $BRANCH and review its updated diff for issue #$0. Reassess only your original F-NNN findings against the correction summary and the supervisor-owned matrix at its exact receipt. Preserve finding IDs and report each as resolved, declined, or still open with evidence; do not erase unavailable review or non-passing row states. Do not edit, push, or create a PR. Remaining suggestions are advisory. End with [pylot] phase=final-review status=done.\n\nSUPERVISOR MATRIX RECEIPT:\n' + os.environ['SUPERVISOR_MATRIX_RECEIPT'] + '\nSUPERVISOR MATRIX:\n' + os.environ['SUPERVISOR_MATRIX'] + '\nPRODUCER CORRECTION SUMMARY:\n' + os.environ['CORRECTION_OUT'] + '\n\nCURRENT SUPERVISOR VERIFICATION:\n' + os.environ['SUPERVISOR_VERIFICATION']))")
  FINAL_REVIEW_RESP=$(curl -s --max-time 30 -X POST \
    -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" -H "Content-Type: application/json" \
    -d "{\"prompt\": $FINAL_REVIEW_PROMPT}" \
    "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${RWID}/prompt")
  REVIEW_SEQ=$(printf '%s' "$FINAL_REVIEW_RESP" | jq -r '.turn_seq // empty')
  if [ -z "$REVIEW_SEQ" ]; then
    RESIDUAL_REVIEW="Final advisory review unavailable: prompt was not accepted."
    curl -s --max-time 20 -X POST -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
      "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${RWID}/stop" >/dev/null 2>&1 || true
    RWID=""
  fi
else
  RESIDUAL_REVIEW="No final review run: first review unavailable or had no actionable suggestions."
  if [ -n "${RWID:-}" ]; then
    curl -s --max-time 20 -X POST -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
      "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${RWID}/stop" >/dev/null 2>&1 || true
    RWID=""
  fi
fi

REVIEW_SEQ がある場合は、再度 poll-reviewer.sh を使用し、REVIEW_POLL_RESULT=running の間だけ再実行してください。unavailable の場合は簡潔な利用不可の理由を設定し、RWID をクリアして続行してください。done の場合は出力を取得し、phase=final-review status=done が含まれている場合にのみ受け入れてください。含まれていない場合は利用不可として扱ってください。有効な最終出力を取得したら、直ちにレビュー担当者を停止してください。この待機にも累計 15 分の上限が適用され、ミッションが失敗することはありません。

if [ -n "${RWID:-}" ] && [ -n "${REVIEW_SEQ:-}" ]; then
  FINAL_REVIEW_STATE=$(curl -s --max-time 20 -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
    "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${RWID}")
  FINAL_REVIEW_OUT=$(printf '%s' "$FINAL_REVIEW_STATE" | jq -r '.last_output // ""')
  if printf '%s' "$FINAL_REVIEW_OUT" | grep -q 'phase=final-review status=done'; then
    RESIDUAL_REVIEW="$FINAL_REVIEW_OUT"
  else
    RESIDUAL_REVIEW="Final advisory review unavailable: no valid completion marker."
  fi
  curl -s --max-time 20 -X POST -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
    "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${RWID}/stop" >/dev/null 2>&1 || true
  RWID=""
fi

---

ステップ 8：唯一の PR を作成する

最終アドバイザリー記録をプロデューサーに送信してください。これはパイプラインで 唯一の PR 作成境界 です。

PR_PROMPT=$(SUPERVISOR_VERIFICATION="$SUPERVISOR_VERIFICATION" SUPERVISOR_MATRIX="$SUPERVISOR_MATRIX" SUPERVISOR_MATRIX_RECEIPT="$SUPERVISOR_MATRIX_RECEIPT" FIRST_REVIEW_STATUS="$FIRST_REVIEW_STATUS" REVIEW_OUT="$REVIEW_OUT" CORRECTION_OUT="$CORRECTION_OUT" RESIDUAL_REVIEW="$RESIDUAL_REVIEW" python3 -c "import json,os; print(json.dumps('''Create the single PR for issue #$0 from the already-pushed branch. First confirm the worktree is clean and the remote head matches local HEAD. Invoke /create-compelling-prs and use that skill to compose and open the PR — do not substitute a placeholder template.

Base the PR's Verification section on the supervisor verification summary below. It is authoritative over any producer claim. Consume the supervisor-owned matrix only when its receipt matches the exact current repository/head. Never reconcile or restore execution states yourself. If that identity does not match, disclose executed rows as stale or the matrix as unavailable; do not claim passed evidence for the current head. Disclose every applicable row whose state is failed, not-run, unavailable, or stale; preserve not-applicable rows without presenting them as gaps. Never state or imply readiness when any current check is non-passing. Include an Independent review section summarizing first-review availability, every unresolved or declined F-NNN finding, correction decisions, and residual or unavailable final review. Review suggestions and verification failures are transparent advisory context, not a reason to suppress the PR or create another PR boundary. Emit [pylot] phase=pr status=done pr=<PR_URL>.

CURRENT SUPERVISOR VERIFICATION:
''' + os.environ['SUPERVISOR_VERIFICATION'] + '''

SUPERVISOR MATRIX RECEIPT:
''' + os.environ['SUPERVISOR_MATRIX_RECEIPT'] + '''
SUPERVISOR MATRIX:
''' + os.environ['SUPERVISOR_MATRIX'] + '''

FIRST REVIEW STATUS:
''' + os.environ['FIRST_REVIEW_STATUS'] + '''

FIRST REVIEW:
''' + os.environ['REVIEW_OUT'] + '''

PRODUCER CORRECTION SUMMARY:
''' + os.environ['CORRECTION_OUT'] + '''

FINAL ADVISORY REVIEW:
''' + (os.environ.get('RESIDUAL_REVIEW') or 'Final advisory review unavailable.'))) ")
PR_RESP=$(curl -s --max-time 30 -X POST \
  -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" -H "Content-Type: application/json" \
  -d "{\"prompt\": $PR_PROMPT}" \
  "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${WID}/prompt")
TURN_SEQ=$(printf '%s' "$PR_RESP" | jq -r '.turn_seq // empty')

プロデューサーが done になるまでポーリングし、その出力から PR URL を見つけて、gh pr view でヘッドブランチと Issue の関連付けがこの実行に一致することを確認してください。プロデューサーへのプロンプト、ポーリング、マーカー、または照合の失敗が発生した場合は、最終結果を出力する前にステップ C を実行してください。

ISSUE_NUMBER="$0"
source ~/.claude/skills/speckit-runner/shared/pr-postcondition.sh || {
  echo '[speckit-runner] fatal: pr-postcondition.sh not found — boot sync may be incomplete' >&2
  exit 1
}
verify_pr_postcondition || { echo '[speckit-runner] PR postcondition failed' >&2; exit 1; }

---

ステップ 9：クリーンアップと結果の出力

必ずステップ C を実行してから、PR と独立レビューの利用可否を報告してください。PR が存在する場合、提案が残っている、または利用できない場合でも、status=failed や status=blocked ではなく status=success を出力してください。

# Run the Step C snippet first. The session EXIT trap removes
# SUPERVISOR_CHECKOUT on this and every other terminal path.

if [ -n "$PR_NUM" ]; then
  echo "[speckit-runner] complete: PR #$PR_NUM opened; independent_review=$FIRST_REVIEW_STATUS"
else
  echo "[speckit-runner] verified checkpoint exists but no PR URL was confirmed — check worker output"
fi

報告コマンドの後、解決済みマーカーをちょうど 1 つ、最終行として出力してください（Bash からではなく、フェンス内でもありません）。

• PR を確認済み：[pylot:$PYLOT_OUTCOME_NONCE] outcome="speckit complete: PR #$PR_NUM opened; independent_review=$FIRST_REVIEW_STATUS" status=success
• PR URL なし：[pylot:$PYLOT_OUTCOME_NONCE] outcome="verified checkpoint exists but no PR URL was confirmed — check worker output" status=partial

---

厳守事項

• 事前確認は必須です — 作業担当者は speckit の各フェーズに入る前に、実データを収集する必要があります
• ポーリングにはスクリプトのみを使用してください — 作業担当者のターンでは poll-worker.sh、レビュアーのターンでは上限付きの poll-reviewer.sh を使用します。どちらも1回の呼び出しにつき2分未満で返ります。独自にループを組んだり、Bash のタイムアウトを長く設定したり、ポーリングをバックグラウンドで実行したり、通知を待ったり、作業担当者のターンが進行中のままオペレーターのターンを終了したりしないでください。
• 正常に動作している作業担当者を時間だけを理由に停止しないでください — block_elapsed はチェックポイントであり、失敗を示すものではありません。停止してよいのは、ハートビートが古い（約10分以上）場合、または失敗が報告された場合のみです。経過時間やターン途中の出力がないことだけを理由に停止してはいけません。ハード上限はスクリプトのみが適用します。
• クリーンアップは必ず実行してください — どの終了経路でも Step C を実行します。レビュアーを利用できない場合は、直ちにそのレビュアーを停止して処理を続行します。
• 外部へのディスパッチは引き続きファイア・アンド・フォーゲットです — フォアグラウンドでのポーリングは内部のミッション実行であり、ディスパッチャーがミッションの進行を見守る理由にはなりません。
• クリーンなコンテキストでレビューしてください — 作業担当者が自身のチェックポイントをレビューしてはいけません。レビュアーがチェックポイントを編集してはいけません。
• 検証はスーパーバイザーが担当します — コマンドはタスクとリポジトリが管理する指示からのみ特定し、切り離されたスーパーバイザーのチェックアウトで、プッシュ済みの正確なヘッドに対して実行し、観測した結果を正直に報告してください。作業担当者の説明文によって検証結果が合格になることはありません。
• リポジトリの信頼境界 — /speckit-runner は、コントリビューター、エージェント、CI の指示ファイルがディスパッチトークンと同程度に信頼できるリポジトリに対してのみ使用してください。スーパーバイザーは自身のセッション内で、リポジトリから特定したコマンドを実行します（$PYLOT_DISPATCH_TOKEN、$PYLOT_API、gh の認証情報を保持しています）。対象リポジトリ内の悪意のある、または侵害された指示ファイルにより、これらの認証情報が漏えいするおそれがあります。
• 提案をゲート条件にしないでください — 作業担当者による修正は1回まで許可し、残ったものがあれば明示して、PR の境界まで処理を続けてください。
• PR の作成は最後に1回だけ行ってください — 検証、分析／チェックリスト、チェックポイントのプッシュ、助言的なレビューをすべて /create-compelling-prs より前に実施します。
• 結果マーカーを出力してください — 終了前の最後の完全なアシスタント行として、[pylot:$PYLOT_OUTCOME_NONCE] outcome=... status= を必ず出力してください。
• 「すでに完了」は重複排除ゲートでのみ使用してください — この結果を出力するのは、イシューが実際に CLOSED である場合（Step 0）のみです。タイムアウトや通知がないことを理由に出力してはいけません。
• 1タスクにつきPRは1つです — 隣接するイシューにスコープを広げないでください。