e2e-workflow-gate reference

e2e-workflow-gate は、実装 workflow で E2E を実行する時期と確認方法を選ぶための gate である。 E2E は default off の opt-in として扱い、通常の validation command とは分けて結果を残す。

対象読者と得られる結果

項目 内容
対象読者 fix-github-issue や implement-from-plan で E2E の要否を指定したい人
選べること E2E を実行しない、review 前に実行する、最後に実行する、両方で実行する
得られる結果 実行した確認、成功・失敗、未実施理由、必要な log や artifact
通常検証との関係 unit test / lint 成功だけでは E2E 実行済み扱いにならない

まず何が起きるか

e2e=final などを実装系 skill に渡すと、通常検証とは別に E2E の実行可否、実行時期、証跡を決める。

  1. 指定値を読み、e2e=auto なら変更対象から実行 mode を決める。
  2. repo-local AGENTS.md や E2E contract から対象 surface と確認方法を特定する。
  3. host-wide state、外部 service、browser などへの影響が安全に判断できるか確認する。
  4. E2E を実行し、対象ごとに実行済み、未実行、対象外を記録する。
  5. PR 本文と完了報告へ、実施内容と結果を人が読める形で渡す。

方法や影響範囲を一意に決められない場合は needs_user_decision で止まり、通常検証の成功では補わない。

Mode

指定 意味
e2e=off / no-e2e E2E を実行しない
e2e=auto 変更対象と repo-local policy から必要最小限の mode を決める
e2e=pre-review 実装と通常検証の後、local reviewer に渡す前に実行する
e2e=final / e2e=on / e2e review 収束後、完了直前に実行する
e2e=both pre-review と final の両方で実行する

requested_e2e_mode は利用者や handoff が指定した値、resolved_e2e_mode は policy 判定後に実行する値である。 後続 workflow へ渡すのは off|pre-review|final|both の resolved value で、auto 自体を実行 mode にはしない。

e2e=auto では、Markdown だけの変更は通常 off、installed skill や設定の local apply は通常 final になる。 実行方法や host-wide state への影響を決められない変更は needs_user_decision になる。

明示した e2e=off|pre-review|final|both は、その指定だけを変更する。 呼び出し元が保持する PR mode、reviewer、その他の selector は引き継ぐ。

E2E Verify

e2e-verify は、実装した Agent と別 context の verifier に追加確認させる option で、default は off である。

指定 意味
e2e-verify=off E2E の実行結果をそのまま判定に使う
e2e-verify=on fresh-context verifier の結果を report_only の追加観測として残す

verifier は E2E の成功判定者ではない。 e2e=off と e2e-verify=on を同時に指定すると、実行対象がないため開始前に停止する。

実行結果の見方

coverage plan は対象を executed、skipped、not_applicable に分ける。 通常 validation の成功は E2E 未実行 item の代替証跡にはしない。

make smoke のように exit code だけで成否が決まる確認では、surface と command の 1 行 mapping を使う。 手動確認、browser 操作、外部 service への副作用がある確認では、対象、手順、影響、証跡、skip 条件を個別に記録する。

E2E の結果を PR 本文へ載せる場合は、実施内容、結果、短い log または reviewer が読める artifact link を記載する。 local path だけ、または「確認済み」という要約だけでは証跡にならない。

final E2E 後に実行対象へ影響する変更が入った場合、以前の結果は stale evidence になる。 変更後の HEAD で final E2E を再実行する。

Local Apply と Browser

installed skill や設定を実環境へ反映する場合は、import 前に agent-dotfiles diff で対象差分を確認する。 e2e-apply=confirmed が指定済みでも、この確認は省略しない。

差分が意図した repo-to-home 反映だけなら、確認済みの指定を使って import へ進める。 home 側の未反映変更、対象外の変更、認証情報や runtime state が混じる場合は import せず、needs_user_decision で止まる。

生成 HTML を browser で確認する場合、in-app Browser には file:// を渡さない。 repo-local 手順に別の方法がなければ、127.0.0.1 の run 固有 unused port で配信し、DOM、screenshot、console error、最終 URL、server 停止後の状態を確認する。

停止と復旧

停止理由 次に行うこと
E2E の方法が repo docs から決まらない 実行方法または skip をユーザーが選ぶ
local apply の差分に対象外変更がある import せず、対象を分けるか home 側変更の扱いを決める
fixed port、simulator、外部 service の影響が不明 使用する資源と許可範囲を確認する
skipped が残る、または全項目が not_applicable 未実施理由を確認し、skip を受け入れるか E2E を追加する
E2E が失敗した、または final E2E 後に対象が変わった 原因を直し、現在の HEAD で再実行する

ユーザーが実行または skip を明示した場合だけ、その選択を記録して再開する。 needs_user_decision を未実行成功として扱わない。

Examples

/fix-github-issue 123 e2e=final e2e-apply=confirmed
/implement-from-plan path/to/plan.md e2e=auto
/e2e-workflow-gate e2e=both e2e-verify=on

e2e=final は review と code-affecting な follow-up が収束してから実行する。 e2e=pre-review は、reviewer に渡す前の実行証跡が必要な変更で使う。

このページは生成物です。原本は元リポジトリ側にあります。