hermes-talaria に ht-pr-approve-loop を追加した — user-review-requested:@me の PR を凍結スナップショットから 1 パスで 👌 承認するスキル
前回追加した ht-pr-approve は、PR の URL と自然言語ポリシーを渡すと、Claude Code と Codex による 4 本のレビューを一時 worktree で走らせ、No P0 のときだけ commit 固定の approval を GitHub Pull Request Review API 経由で送る単発スキルです。ただ、私のアカウントにはレビュー依頼が複数溜まっていくので、1 PR ずつスキルを呼び出していくと、同じ repository・同じポリシーの承認を手作業で順番に流す工程が残ります。
hermes-talaria に、この「直接レビュー依頼が来ている PR を 1 パスでまとめて片付ける」工程をスキル化した ht-pr-approve-loop を追加しました。PR は codenote-net/hermes-talaria#65 です。スキルは呼び出し時に明示したリポジトリ内で is:pr state:open user-review-requested:@me sort:created-asc に一致する PR を oldest-first で凍結し、各 PR に対して ht-pr-approve のランナーをそのまま呼び、No P0 の PR だけに 👌 1 文字の approval を 1 回だけ送ります。本記事では、この loop を安全に閉じるために必要になった設計判断を書き留めます。
スキルの輪郭
ht-pr-approve-loop はリポジトリ URL、または同じ検索条件を持つ pulls 画面の検索 URL を 1 つだけ受け取ります。
/ht-pr-approve-loop https://github.com/OWNER/REPO
/ht-pr-approve-loop https://github.com/OWNER/REPO/pulls?q=is%3Apr%20state%3Aopen%20user-review-requested%3A%40me%20sort%3Acreated-asc内部で使うクエリは次のリテラル固定で、repo:OWNER/REPO を付けた形だけを許容します。
is:pr state:open user-review-requested:@me sort:created-ascここで最小限に揃えた制約は次の 4 つです。
- 対象は呼び出し時に明示したリポジトリ 1 本だけで、カレントディレクトリ・Organization・アカウントから補完しない
user-review-requested:@meは認証ユーザー個人への直接依頼を表し、review-requested・team-review-requested・is:openなどの別クエリに差し替えない- 公開に残る書き込みは
event: APPROVE、body: "👌"、commit_id固定の API レビュー 1 回だけで、フィックス・別コメント・マージ・自動再試行は許可しない - 承認ポリシーは「No P0 findings」固定で、P1・P2・P3 の指摘は private な ledger に残るが approval はブロックしない
スキル全体は 5 工程に分かれます。工程 3 で各 PR のレビューに ht-pr-approve の既存ランナーをそのまま呼ぶ形にして、loop 側は discovery と凍結、各 PR の再確認、4 本のレビューの裁定、集計を担当するようにしています。
flowchart TD
IN[repo URL または pulls 検索 URL] --> DISC[discover_prs.py<br/>GitHub search で全ページ取得]
DISC -->|incomplete_results false<br/>total_count 不変<br/>< 1000| SNAP[凍結スナップショット JSON<br/>oldest-first]
SNAP --> LOOP{frozen URL を 1 件ずつ}
LOOP --> ELIG[直接レビュー依頼・state・draft・author・head/base を再確認]
ELIG -->|OK| REUSE[ht-pr-approve の review_pr.py を呼ぶ]
ELIG -->|不一致| SKIPE[PR skip]
REUSE --> ADJ[エージェントが 4 本のレビューを裁定<br/>No P0?]
ADJ -->|PASS| PRE[POST 直前に head/base と依頼を再取得]
ADJ -->|FAIL / UNKNOWN| SKIPP[PR skip]
PRE -->|不一致| STALE[stale として skip]
PRE -->|一致| POST[gh api で commit_id 固定の<br/>approval を送信 body は 👌]
POST --> VERIFY[review ID を読み戻し<br/>reviewer・state・commit_id・body を照合]
VERIFY --> LOOP
LOOP --> REPORT[private な集計レポート]
リポジトリを必ず明示させる
loop 最初の判断は「スコープを呼び出し元から推測しない」ことでした。/ht-pr-approve-loop にリポジトリ URL が付いていなければ、現在ディレクトリの Git リモートや直近に触った Organization から補完せず、ユーザーに確認して止まります。SKILL.md では次のように書いています。
Without an explicit repository target, ask rather than inferring one from the current directory, organization, or account. Never expand the scope.
理由は 2 つあります。1 つは、user-review-requested:@me は repo: を付けなければ GitHub 全体の PR に一致するので、スコープを広げるとエージェントが意図しない Organization の PR まで触りに行きかねない点です。もう 1 つは、branch protection で required approvals を設定したリポジトリでは、承認が入るとマージ可能になる点です。マージの最終判断は別だとしても、承認が勝手に拡散して merge 可能状態の PR が増える経路を残すのは避けたいので、1 回の呼び出しで触れるのはリポジトリ 1 本という形に閉じました。
URL のパースも urlsplit と fullmatch で厳格にして、repo:other/repo を含むクエリ・追加のスコープ・別ホスト・フラグメント・末尾スラッシュなどを自動で修復・正規化せず、全部 ValueError で弾くようにしました。https://github.com/OWNER/REPO と、q パラメータだけを持つ /pulls 検索 URL のどちらかに完全一致する入力だけが通ります。
凍結スナップショットとページネーションを厳密に取り切る
discovery は Python の scripts/discover_prs.py に閉じ込め、GitHub への書き込みはしない、エージェントの推論も挟まない形にしました。中身は GitHub search/issues API を per_page=100 で呼び出し、ページを 1 から順に取るだけです。重要なのは、「取り切れなかったら途中結果を snapshot にしない」という判断を 3 箇所に入れた点です。
- 各ページの
incomplete_resultsが明示的にfalseでなければValueError - 2 ページ目以降の
total_countが初回と変わっていたらValueError total_countが 1000 以上なら API の cap に触れたとみなしてValueError
GitHub の search API は 1000 件で結果が打ち切られるので、total_count が 1000 に達した時点で oldest-first の全件取得は保証されなくなります。「上限で打ち切られた途中までの結果で loop を回すのは、不完全なだけでなく危険」という扱いにして、loop 開始前に止めるようにしました。total_count の不変チェックは、ページ取得中に件数が変わったことを検出したら snapshot を作らずに止めるためのものです。ただし、ページングした search は原子的な snapshot ではなく、件数が同じでも結果集合が変わっていないことまでは保証できません。そのため snapshot は観測した候補を凍結するだけのものとして扱い、各 PR は処理する直前に live で再確認します。
snapshot は呼び出し元の checkout の外側にある外部ランディレクトリに x モードで作り、exists・is_symlink・parents 判定でソースツリーの中や既存ファイルの上書きを禁止しています。ledger や個別の evidence JSON、承認 payload もすべてこの外部ディレクトリに置きます。「private な評価結果が Git にそのまま入らない」という線を 1 本引くための配置です。
直接依頼とチーム依頼を分ける
user-review-requested:@me は認証ユーザー個人への直接依頼だけを拾う修飾子で、チーム依頼は team-review-requested の別修飾子として存在します。直接依頼とチーム依頼を loop の判定で同一視しないために、SKILL.md に次のルールを書いてあります。
user-review-requested:@memeans a request addressed directly to the authenticated user, not a team request. Never replace it withreview-requested,team-review-requested,is:open, or a guessed username.
これに加えて、search 結果の membership は eligibility の証拠にしない、という扱いを別に置いています。POST 直前には GET /repos/OWNER/REPO/pulls/NUMBER/requested_reviewers を全ページ辿って、現在の users に自分の login が残っているかを都度確認し、teams の方に出てくるだけなら対象から外します。search index がチームからの依頼も拾ってしまったり、依頼が後で取り下げられたりしても、POST 直前の最新状態が正になるような形です。「依頼者が直接自分を指名しているのか、チーム経由で広く振ってきたのか」はレビューの重さが違うので、loop が後者を自動で承認しない構造にしておきました。
POST 直前にもう 1 度確認する
snapshot は discovery 時点の結果なので、discovery からレビュー終了までの間に PR の状態は変わり得ます。loop では次のタイミングで PR 側の状態を取り直すようにしました。
- snapshot の URL を 1 件取り出した直後(レビュー実行前)
- 4 本のレビューが揃って No P0 と裁定した直後(POST 直前)
POST 直前の再取得では pulls/{number} を取得し、requested_reviewers・reviews を全ページ辿って、次の条件が今でも成り立つかを確認します。
- 対象リポジトリとレビュアー login が discovery 時と同じ
state == openかつdraft == false- 著者が自分と違う
requested_reviewers.usersに自分の login が今も残っている- 凍結した head SHA・base SHA が現在の pair と一致する
head と base のどちらかが動いていたら「新しい pair を自動でレビューし直す」ことはせず、stale として記録して次の PR に進みます。新しい pair には新しい evidence が必要なので、loop 1 パスで新 head にそのままスライドして承認する経路は開けないようにしました。
ランナーと 👌 本文のための調整
工程 3 では ht-pr-approve のランナー scripts/review_pr.py をそのまま呼びます。「レビュー実行は ht-pr-approve に任せ、loop は discovery と凍結、再確認、裁定と集計を見る」という分担にして、レビュー実行のロジック(ランナー)を 2 箇所に書かないようにしました。loop 側で呼び出す形はシンプルで、snapshot から取り出した URL と freeze した head/base を渡すだけです。
python3 "$APPROVE_SKILL_DIR/scripts/review_pr.py" \
'https://github.com/OWNER/REPO/pull/NUMBER' --repo /absolute/source \
--head FULL_HEAD_SHA --base FULL_BASE_SHA \
--output /external/run/pr-NUMBER-evidence.jsonht-pr-approve の方は、本文を「英語の詳細なポリシー・evidence・counts・rationale」に固定していました。loop で複数 PR に流すときにこの本文をそのまま各 PR に貼ると、通知もタイムラインもノイズが増えるので、本文だけ差し替えられる口を今回追加しました。SKILL.md 側に書いた抜粋は次のとおりです。
An explicitly supplied exact custom approval body overrides only the public body, not the review, policy, freshness, or verification gates. Preserve it exactly, including Unicode and whitespace; do not append explanations or a newline.
ここで大事にしたのは、「差し替えるのは公開本文だけ」という線です。ポリシー解釈・freshness・read-back の検証はすべて従来どおり動かし、policy・evidence・findings の記録は private の ledger に残ります。loop からはこの口を使って 👌 という 1 文字(U+1F44C、改行や空白なし)を渡し、read-back 時に本文が 👌 と完全一致するかを照合しています。
公開本文を絞っても、手元に残す情報は減りません。P1・P2・P3 の指摘と evidence、ランナーの raw レポートはすべて private の ledger ファイルに書かれ、自分が後から 1 PR ずつ振り返れる形で残します。
冪等性は ledger と review ID で担保する
既存の APPROVED レビューを再承認しないための冪等判定は、本文の 👌 一致では閉じられません。別の run・別のポリシー・別の人が同じ絵文字で押しているだけかもしれないし、同じ head への approve が後の CHANGES_REQUESTED や dismissal で effective ではなくなっている可能性もあるからです。SKILL.md では次のように書いています。
Never accept an arbitrary historic APPROVED: account for later effective CHANGES_REQUESTED, dismissal, or other superseding decision state. … The emoji alone proves neither policy equivalence nor review completion.
loop が already_approved を記録して POST を省けるのは、次の 4 つが揃ったときに限定しました。
- 現在 effective で non-dismissed な APPROVED レビューが同じ head に対して存在する
- 外部 ledger にそのレビュー ID と reviewer・body・head/base・完了した 4 本のレビュー evidence・No P0 の裁定記録・ポリシー文字列が紐付いて残っている
- ledger のポリシーが現在の呼び出しと等価である(No P0 どうし)
- レビュー ID を API で読み戻した結果が ledger と一致する
どこかが欠けている時は already_approved ではなく duplicate_ambiguous として記録して、追加の approval は押さず次の PR に進みます。「以前と似ている」を本文の絵文字一致で済ませると、過去に別経路で押された 👌 を自分の run の成功と見分けられなくなるので、本文の文字列を証拠に使わない、という扱いにしました。
曖昧な時は loop を止める
もう 1 つ loop の動きとして明示的に決めたのは、「POST 周りが曖昧になったら loop 全体を止めて、残りの PR は未着手として残す」ことです。API 送信がタイムアウトして成功か失敗か判然としない、read-back で reviewer・state・commit・body のいずれかが一致しない、reconciliation の候補が複数ある、といった状態では submission_unknown を記録して、以降の candidate を触らない形にしました。
If acceptance or read-back cannot be established, persist submission_unknown and stop the entire loop; leave remaining candidates unattempted.
ここで loop を止めるのは、曖昧な承認を blind に再送信するリスクが高い割に、止めてから手でレビュー履歴を読み直すコストは小さいからです。authentication 失敗や rate limit 超過も同じ扱いで、PR 固有の skip には降格させず loop 全体を停止します。「どの PR も次の人が引き取れる」状態だけが残るようにしました。
既知の制限とこれから
discovery では、GitHub search/issues API の返す repository_url と、呼び出し時に渡した repository を大文字小文字を区別して比較しています。GitHub 自体は owner/name を大文字小文字無視で受け付けるので、https://github.com/Example/Project のような混ざった表記で呼ぶと、canonical 表記 example/project の結果と一致せず discovery が弾かれます。現時点では canonical な綴りで呼ぶ運用でしのいでいます。大文字小文字の不一致は discovery のエラーとして止まるだけで、対象外リポジトリの PR を承認することはありません。この挙動は P2 として validation matrix に記録してあり、自動 fix は保留しています。
小さな limitation ですが、文字列比較を正規化する前に repository_url の形そのものが仕様として安定か、GitHub 側で case を変えて返すケースがあるかを別に確認したいので、固定の正規化を急がず置いています。他のリポジトリにスキルを切り出す必要が出てきたときに合わせて見直す予定です。
以上、user-review-requested:@me で溜まった PR を凍結スナップショットから oldest-first 順に 1 パスで 👌 承認する hermes-talaria スキルを追加した、現場からお送りしました。
参考情報
- codenote-net/hermes-talaria PR #65
- hermes-talaria
- ht-pr-approve-loop SKILL.md
- ht-pr-approve-loop scripts/discover_prs.py
- ht-pr-approve-loop references/validation.md
- ht-pr-approve SKILL.md
- hermes-talaria に条件付き PR 承認スキル ht-pr-approve を追加した
- PR レビューを Claude Code と Codex に同時にやらせる
- GitHub REST API: Search issues and pull requests
- GitHub REST API: Pull request reviews
- GitHub REST API: Review requests
- イシューおよびプルリクエストを検索する
- Claude Code ドキュメント
- Codex
- GitHub CLI