runtime-verification-discipline

ランタイム検証の規律

内部で共有するスキルです。PDCA ワークフローにおける検証の実行方法の唯一の信頼できる情報源です。AI が適切な環境で自ら検証を実行し、本当に回避できない境界に達した場合に限り、人間に引き継ぎます。ホストは dependencies でこのスキルを宣言し、見つからない場合は処理を中止します。黙ってフォールバックすることはありません。

これはルール層です。検証をどこで、誰が実行するか、そして十分かどうかを定めます。環境を操作する手順（チャネルの選択、CDP 呼び出しなど）は含みません。それらは browser-debug-toolkit などの機能スキルで扱います。具体例とホストごとの統合スニペットはreference.mdを参照してください。

このスキルが必要な理由

これまでのワークフローでは、検証を「AI が Bash のテストコマンドを実行し、それ以外はすべてチェックリストとしてユーザーに渡す」ものとして扱っていました。この姿勢では、実環境やシミュレーション環境を操作できる AI の能力を活用できず、「ユーザーに引き継ぐ」ことが十分に検討されないまま既定の対応になっていました。AI が本当に実行できなかったのではなく、試さなかったために引き継ぐこともあります。その結果、回避できる手動検証の作業が発生し、さらに、忠実度の低いチェックを決定的な検証であるかのように報告することで、誤った確信につながることもあります。

このスキルが徹底するメタレベルの教訓は次のとおりです。

検証は、環境内で AI が行う仕事です。AI が安全かつ決定論的に操作できる、最も忠実度の高い環境を優先してください。本当に回避できない境界に達した場合に限り人間に引き継ぎ、その理由を正確に伝えてください。

適用される場面

バグ修正でも機能開発でも、観測可能な動作に変更がある場合、あらゆるワークフローの検証・チェック段階で適用されます。どの環境でも変更を実行できない場合、このスキルは適用されません（ドキュメントやコメントのみの変更では、ランタイム検証が不要なことがあります）。

絶対原則

検証は環境内で AI が実行します。チェックリストとして人間に委ねてはいけません。

まず実行を試みてください。それが既定の対応であり、任意ではありません。人間への引き継ぎが正当化されるのは、真に回避できない境界だと分類された場合に限り、その理由を明示しなければなりません。

環境のティアモデル

環境を、アプリの本番ランタイムの対象とどれだけ忠実に一致するかで分類します。「実環境」と「シミュレーション環境」の区別は、その対象との相対的なものであり、絶対的なものではありません。

本番の対象	実環境	シミュレーション環境
Web アプリ	実際のブラウザー（CDP で操作。例：ego-browser / chrome-devtools-mcp）	ヘッドレス DOM / jsdom 形式の偽 DOM
Electron アプリ	Electron アプリケーション自体	通常のブラウザー
モバイルアプリ	物理デバイス	エミュレーター / シミュレーター / ブラウザー

プラットフォーム固有のバグを決定的に検証できるのは、そのプラットフォームのランタイムが実際に動作するティアに限られます。

ティア選択ルール

AI が人間の介入なしに操作でき、かつ実施する検証に対して十分に決定論的で安全な、最も忠実度の高いティアを選んでください。忠実度とコストに対する確信度のバランスを取るのであり、やみくもに忠実度を最大化するわけではありません。

• 決定性 — 実環境には実際のネットワークやタイミングが伴うため、動作が不安定になりがちです。安定して繰り返し実行できるシグナルが必要な場合は、まずシミュレーション環境で検証してください。
• 安全性 / 副作用 — 実環境では、実際のバックエンドやユーザーデータを変更したり、実際のプッシュ通知を送信したりする可能性があります。書き込みを伴う検証では、まずシミュレーション（サンドボックス）で検証し、その後、実環境で確認してください。
• バグの種類に応じた忠実度 — プラットフォーム固有のバグには、そのプラットフォームが実行されるティアが必要です。プラットフォームに依存しないロジックのバグでは、そうとは限りません。

つまり、読み取り専用で決定性の高いチェックは、実環境で直接実行します。書き込みを伴うチェックや不安定になりやすいチェックは、まずシミュレーション環境で安定したシグナルを得てから実環境で確認し、両方の結果を明記します。

プロバイダーの解決（プラグイン可能）

優先順位に従って検索し、このプロジェクトの環境でどのように検証するかを解決します。設定より規約を優先します。

1. プロジェクト独自の検証スクリプトまたはスキル — 推奨。AI が指示されなくても見つけられるよう、プロジェクトでは検証手段を見つけやすい規約（例：既知の場所にある検証スクリプトやプロジェクトスキル）で公開することが望まれます。
2. このライブラリの共有機能スキル（例：Web 用の browser-debug-toolkit、Android WebView 用の android-webview-debug）— フォールバックです。
3. どちらも存在しない — 以下の引き継ぎ分類に進みます。

まず試し、その後にブロッカーを分類する（A/B/C）

AI が検証を実行できない場合は、何かを行う前に理由を分類します。

• A — 自動化が未接続。 チェックは自動化できますが、スクリプトがまだありません。接続する（スクリプトを書く）か、接続を申し出ます。引き継いではいけません。
• B — 一度限りのセットアップが未完了。 チェックは自動化できますが、ツールチェーンまたは環境がインストールされていません。正確なインストール／セットアップコマンドを提示し、ユーザーに判断を委ねます。セットアップ後は AI が引き継ぎます。
• C — 真のハード境界。 人間に引き継ぎ、その理由を述べます。C には 3 種類あります。AI が実行できない（物理デバイス、CAPTCHA、生体認証）、AI が結果を判断できない（主観的な UX、探索的評価）、または操作に現実世界への副作用がある場合です。

分類せずに「Bash がない／環境の制限」と曖昧に言って引き継ぐことは、決してしてはいけません。「人間の作業を最小限にする」という原則を誠実に守るには、この分類によって「接続しなかった」ことと「本当に自動化できない」ことを区別する必要があります。

ピクセルの幾何学的測定はカテゴリ C ではありません。 レイアウト済みフレームとデザイン仕様の数値比較は主観的な UX ではなく、ドキュメントチャネルまたはレイアウトプローブを実行できる場合、物理デバイスでの作業でもありません。プローブがない場合はカテゴリ A です。このターンで、リリース対象の親ディレクトリにマウントしてプローブを書き、実行してください。カテゴリ C の「物理デバイス」は、どのコマンドでも実行できない操作に限られます。「実環境でのスモークテストを推奨」という下位のラベルが付いていても、人間の作業に変わるわけではなく、測定の代わりにもなりません。

UI を開いた場合は、スクリーンショットファイルを残します。 チェックで UI を開いた場合、証拠として、この実行中に保存した空でない png、jpg、jpeg、または webp ファイルへのパスを記載します。ユニットテスト、仕様の検証、および UI を開けず数値を出力するだけのレイアウトプローブでは、画像は不要であり、画像があると偽ってはいけません。画像は、そのチェック独自の合格条件の代わりにはなりません。Figma レポートのチャネル名をここで言い直さないでください。

十分性の確認

検証が十分であるのは、変更の正確な動作を、ソフトウェアが実際に使われる方法で検証している場合に限ります。基準は「アプリが起動すること」ではなく、「修正したバグの具体的な症状が実際の使用経路で解消されていること」、または「新機能が実際の使用経路で動作すること」です。アサーションが変更された動作を網羅していない場合、どの環境で実行したかにかかわらず、検証は不十分です。

UI 検証対象の事前チェック

検証する前に、検証対象に UI の動作が含まれるかどうかを判断します。この判断には、2 つのコマンド出力を使います。目標、タスクカード、修正の説明にある文言は判断材料にしません。

変更セットは、追跡対象の差分と、追跡されていないすべての非無視対象パスです。git rev-parse --show-toplevel の結果のディレクトリから実行します。追跡されていないパスは git ls-files --others --exclude-standard で取得します。追跡対象の差分が空でも、これらのパスを除外しません。

ベースを次の順に 1 つ解決します。

1. git rev-parse --verify --quiet origin/HEAD が成功する場合は、origin/HEAD。
2. それ以外で、git branch --show-current が空でない場合は、HEAD ではなくそのブランチの reflog を読み取ります。リンクされたワークツリーはブランチの reflog を共有し、git branch -m を実行しても新しい名前で保持されます。コマンドは git reflog show --date=unix --format='%H%x09%gd%x09%gs' <current> です。subject が branch: Created from <src> である行を残します。ベースは、%gd の波括弧内の unix 時刻が最小である行の %H コミットです。%H は git rev-parse --verify --quiet に成功し、git merge-base --is-ancestor <commit> HEAD にも成功する必要があります。成功しない場合はその行を除外し、次に時刻が小さい行を採用します。<src> は解決しません。同じ時刻の場合、もう一方の祖先であるコミットを採用します。どちらもそうでない場合は、辞書順で最も小さい SHA を採用します。
3. それ以外の場合は、git for-each-ref --format='%(refname:short) %(committerdate:unix)' refs/heads refs/remotes を一覧表示します。名前が現在のブランチと異なり、git rev-parse <ref> が git rev-parse HEAD と異なり、git merge-base --is-ancestor <ref> HEAD に成功する ref を残します。git reflog show --format=%gs <current> から以前の名前を収集します。現在の名前から始め、各行が Branch: renamed refs/heads/<old> to refs/heads/<new> である場合、<new> がすでに収集済みなら <old> を追加します。残した ref の git reflog show --format=%gs <ref> に、収集済みの名前を含む branch: Created from <name> が含まれている場合、その ref を除外します。また、その reflog に branch: Created from HEAD が含まれ、git rev-parse <ref> がその行の %H と等しく、別の残した ref が <ref> の祖先である場合も除外します。残った ref のうち、コミッターのタイムスタンプが最も大きいものを選びます。同じタイムスタンプの場合は、ref 名が辞書順で最も小さいものを選びます。
4. それ以外の場合はベースがなく、追跡対象の差分は git diff HEAD です。

ベースが解決された場合、追跡対象の差分は git diff --merge-base <base> です。

• パス接尾辞シグナル — 変更セット内のパスが .html、.css、.scss、.less、.vue、.svelte、.tsx、または .jsx で終わること。名前は、追跡対象の差分に対する git diff --name-only の結果と、未追跡ファイルの一覧です。
• ビュー・マークアップシグナル — 追跡対象の差分に対する git diff -U0 の追加行または削除行が以下の差分パターンに一致すること、または未追跡ファイルのいずれかの行が以下のタグパターンに一致すること。どちらも大文字と小文字を区別します。

差分パターン（git diff -U0 に対する grep -E）：

^[+-].*</?(div|span|button|input|img|svg|path|ul|li|form|label|textarea|canvas|section|header|footer|nav|table|video|iframe|h[1-6])([[:space:]]|>|/)

タグパターン（未追跡ファイルごとの grep -E）：

</?(div|span|button|input|img|svg|path|ul|li|form|label|textarea|canvas|section|header|footer|nav|table|video|iframe|h[1-6])([[:space:]]|>|/)

どちらかの条件に該当する場合、その変更には UI の動作が含まれます。その場合、検証ステージには UI を開くチェックを少なくとも 1 つ含めます。階層ルールに従い、まず実環境を使用します。シミュレートされた UI でも、UI を開いたものとして扱います。そのチェックには、上記のスクリーンショット条項が適用されます。UI 以外のチェックではスクリーンショットを取得せず、画像の捏造も引き続き禁止されます。

この検証を figma-pixel-verify が担当し、レポートチャネルが layout-probe で Screenshot: not-openable の場合、その記録された行がピクセルチェックの UI 証拠の結果となり、この事前チェックを完了します。このスキルで UI を開けるチャネルを使用すると UI が開かれ、スクリーンショットが保持されるため、この事前チェックを満たします。

いずれかのシグナルに該当し、この実行で UI を開けない場合は、レポートを書く前に A/B/C ルールに基づいてブロッカーを分類します。クラス A では、このターンに UI を開くチェックを組み込みます。制限事項の項目はクラス C の場合、および一度限りのセットアップがまだ保留中のクラス B の場合に記載します。その項目には、ブロックされている理由、ブロックされている階層、ギャップを補うための後続アクションを記載し、UI 以外のチェックでは UI の動作をカバーできないことも明記します。

どちらのシグナルにも該当しない場合、この事前チェックは適用されません。従来どおり、UI 以外のチェックで検証を満たせます。

誠実なティア表示（非ブロッキング）

検証レポートには、各チェックで実際に使用したティアを必ず記載してください。使用したティアが本番環境の目標を下回る場合は、「シミュレーションで検証済み。実環境でのスモークテストを推奨します。」と表示してください。これは表示上の義務であり、ゲートではありません。つまり、到達可能なティアでのAIによる検証を妨げることはありませんが、シミュレーションの結果を実環境での確認結果として提示することは禁止します。

境界

• completion-evidence-discipline — 直交する軸です。こちらは証拠の鮮度（今回のターンで実際に実行したか）を管理し、このスキルは環境と実行者（どのティアか、誰が実行したか、十分か）を管理します。合格を主張するには、両方を満たす必要があります。
• runtime-evidence-debug — こちらはデバッグのフォレンジックです。根本原因を特定するために計測します。このスキルは検証の実行です。修正や機能が環境で動作することを確認します。名前は似ていますが、目的は異なります。
• 機能スキル（browser-debug-toolkit、android-webview-debug、今後追加される Electron／モバイル向けスキル）— チャネルの選択と操作手順を担当します。このスキルは、どこで／誰が／十分かを判断するだけで、方法はそれらのスキルに委ねます。

統合ガイド（ホスト向け）

• runtime-verification-discipline をフロントマターの dependencies に宣言し、見つからない場合は起動時に中止します。
• 検証段階に、「検証の実行は runtime-verification-discipline に従います」という簡潔な行と、ホスト独自のスコープ条件を追加します。ホスト独自のオーケストレーションと終了条件は維持してください。
• ホスト側でティアモデル、選択ルール、プロバイダーの解決、または A/B/C の説明を繰り返さないでください。これらの唯一の情報源はこのスキルです。

ホストごとの編集例と実例は、reference.md を参照してください。