round-trip ループ全体を回す
// GUIDE · ROUND-TRIP
再現 → 修正 → 検証 → 両 PR を、ひとつのオーケストレーションで。
Vivarium の round-trip スキルは、上流バグレポートからドラフトの修正 PR を出すまでの全工程を AI エージェントと人間が協調しながら進めるためのものです。Phase 1〜5 の round-trip 自動化計画で実装したツール群を、ここでは人間視点で読み下した手順として記述します。機械可読版は `.claude/skills/round-trip/SKILL.md` に置かれています (Claude Code が自動 load)。
// 0 · このガイドが扱う範囲
round-trip ループの end-to-end オーケストレーション。
このガイドは round-trip ループを人間視点で説明します — 各 stage で何が起こり、どこまでが自動化され、どこが人間判断のままかを並べます。機械可読の orchestration 本体は
.claude/skills/round-trip/SKILL.md
にあり、Claude Code がトリガー一致時に自動 load します。普段直接読む必要はありません。
もしレシピの scaffold だけを行いたい場合 (完全な fix-and-PR ループ不要) は はじめての 5 分 ガイドを使ってください。
このガイドはまだ反復中です。 メンテナが実際に上流 issue で 1 回ずつ回した結果をフィードバックしながら肉付けしていきます。具体例は今後増えていく想定です。
// 1 · 前提条件
インストールと設定が必要なもの。
まだなら gh auth login を実行。スキル内部では gh issue view、gh pr create、gh workflow run、gh run download を呼ぶので、最低限 repo スコープが必要です。
AI エージェントから使う を参照。round-trip スキルは内部で search_upstream_issues、prepare_new_recipe、verify_and_report_fix、(Layer 2 のみ) create_fork_pr を呼びます。
Vivarium は SCM として Git ではなく Jujutsu を使います。スキルは Vivarium 側 PR のために jj describe / jj bookmark / jj git push を駆動し、gh pr create で PR を開きます。
write:packages スコープを持つ classic PAT を mise run ghcr:login がドキュメント化している場所に配置。Stage 5.5 の mise run branch-fix:publish で使います。
// 2 · 全体の流れ
10 stage、verdict 経路は Layer 依存。
Stage 0〜5 は Layer 非依存で共通、Stage 6 で Layer 1 (WASM in-browser) と Layer 2 (Docker) に分岐します。Layer 3 はレシピを持たないため fixed-verdict 取得の対象外 — 詳細は下の cheat sheet を参照。
Stage 0 Pre-flight (project 活動度、issue 存在、関連 PR なし)
Stage 1 Scaffold (prepare_new_recipe + mise run recipes:new)
Stage 2 再現実装 (人間 + AI)
Stage 3 unfixed verdict 取得 (verify_and_report_fix)
Stage 4 Vivarium PR open (jj git push + gh pr create、ai: generated ラベル付与)
Stage 5 Upstream fork + fix branch push (人間)
Stage 5.5 Layer 2 のみ: branch-fix image を build & push
(mise run branch-fix:publish)
Stage 6 fixed verdict 取得
- Layer 1: prepare_fix_candidate → CI wheel build →
live recipe page (人間が visual confirm)
- Layer 2: verify_and_report_fix に branch_image を渡す →
branch-fix-verdict.yml + artefact
Stage 7 Vivarium PR を fixed verdict で更新
(Layer 2 のみ; jj git push --bookmark)
Stage 8 Upstream draft PR open
- Layer 1: prepare_fix_candidate が返したコマンドを実行
- Layer 2: create_fork_pr (dry_run: false)
Stage 9 最終 Vivarium 側 commit
(Layer 2 のみ; jj git push --bookmark)// 3 · スキルの起動
一文で投げれば、後はエージェントが進める。
AI エージェント (Claude Code / Cursor / Cline) に以下のように依頼:
https://github.com/owner/repo/issues/N の round-trip を回して。Layer 2、タイトルは「short title」、base image は
node:26-slim。
エージェントは round-trip スキル (トリガー一致で自動 load) を選び、各 stage を案内します。人間に渡される箇所 (Stage 2、5、Layer 1 の場合は Stage 6 も) では確認後にエージェントが続行します。失敗時はスキルが
roundtrip.json#/status を
"blocked" に書き換えて停止 — 下の Troubleshooting を参照。
// 4 · LAYER 1 vs LAYER 2 cheat sheet
fixed verdict 経路だけが異なる、他は揃う。
| Layer 1 (WASM) | Layer 2 (Docker) | |
|---|---|---|
| Unfixed verdict ソース | In-browser の Pyodide / Ruby.wasm / php-wasm を Playwright が
| recipe merge 時に CI が capture した deployed
|
| Fix の届け方 | Fork branch → CI で wheel build (Vivarium PR merge 時に
| Fork branch → コントリビュータがローカルで Docker image を build → GHCR に push |
| Fixed verdict ソース | Live recipe page が baseline + fix-candidate を side-by-side で描画、人間が visual に確認 |
|
| Upstream PR の open |
|
|
Layer 3 は
verify_and_report_fix 側で
verify_fixed が明示的に拒否されます —
branch-fix-verdict.yml が
src/layer2_docker/<slug>/ しか扱えず、
対象となる Layer 3 レシピも存在しないためです。
// 5 · TROUBLESHOOTING
スキルが status: blocked で停止したとき。
どの stage でも失敗時は
roundtrip.json#/status が
"blocked" に書き換わり、スキルは停止します。同じ slug に対する
/round-trip 再起動は、人間が解除するまで再開を拒否します。
解除手順:
roundtrip.json#/notes[]を読んで失敗理由と stage 番号を確認。失敗の根本を修正 (典型的には: 失敗したコマンドを verbose フラグ付きで手動再実行し、何が起きたか掴む)。
roundtrip.jsonを編集 —statusを期待値に戻し (進捗具合に応じて"verifying"か"verified")、updated_atを更新。/round-tripを再起動。スキルがroundtrip.jsonを再読込し、verify_and_report_fixのcomputeNextActionステートマシンが適切な stage を選んで再開します。
このガイドで触れていない事象に遭遇したら、
aletheia-works/vivarium
に issue を立ててください。穴を埋めてこのページに反映します。