verify-app

アプリを検証する

このスキルが答える質問：今回の変更でどの機能に影響があり、隔離されたインスタンスでそれらをどう操作し、何をもって動作の証拠とするか？

Poteto の検証スキルに続く 2 つの要素です。リモートコントロール （node scripts/verify.mjs。引数なしで全コマンドを表示）と機能マップ （docs/verify/。領域ごとに 1 つのファイルがあり、同じ 4 つの H2、Sub-features、How to get to it、Driving it with verify、Gotchas を含みます）。CLI は実行中のインスタンスを操作します。テストランナーではありません。検証では、コマンドを組み合わせてください。検証用のドライバースクリプトは決して作成しないでください。

CLI のうち、製品固有の部分（シード状態、doctor が監視するサーバーフォルダー、up の追加フラグ、ブラウザーのロケールと権限、レポートの文言）は scripts/verify-app.mjs にあります。それ以外は、どのアプリでも同じです。

フローを選ぶ

チェックアウトごとに専用のインスタンスが割り当てられます。ポート、データフォルダー、ブラウザー、ログはチェックアウトのパスから決まり、.verify/<port>/ に置かれます。Git worktree（git rev-parse --git-dir）はメインのチェックアウトや、ほかのエージェントの worktree と競合しません。

• 新しい worktree またはクローンの場合： node scripts/verify.mjs setup で、依存関係と Chromium（不足している場合）をインストールし、ページをビルドしてから up、doctor を実行します。
• セットアップ済みの場合： up の後に doctor を実行します。
• 完了した場合： down を実行します。cleanup でこのインスタンスのデータとログを削除します（cleanup --all ではレポート、トレース、スクリーンショットも削除します）。worktree は、ブランチをプッシュした後、メインのチェックアウトから自分で削除してください。

doctor は fresh と表示する必要があります。そうでない場合は、問題が示されます。STALE BUNDLE（npm run build を実行）、STALE SERVER または commit changed（down の後に up を実行）、WRONG INSTANCE（ポートまたはブラウザーが別のものに属しています）。

手順

1. node scripts/verify.mjs features：変更が影響する領域をすべて特定し、そのファイルだけ（features <area>）を読みます。変更が複数の領域にまたがる場合は、journeys も読みます。変更に関係する規則を docs/INVARIANTS.md で確認します。
2. node scripts/verify.mjs check：ゲートであり、プロジェクトのチェックコマンドです（project.md）。lint、コントラクト（機能マップ、規則、アーキテクチャルール）、単体テスト、形式モデル、型チェック＋ビルド、バンドル内のシークレット、エンドツーエンドのジャーニーを実行します。ほかのことを評価する前に、これを通過する必要があります。反復作業中は check --fast を使います。contract 単独の実行にはインストールは不要です。形式モデルには Java が必要です。Java がない場合は 実行されず、ゲートの結果は「不完全」となり、「合格」にはなりません（formal/README.md）。
3. setup または up ＋ doctor → fresh。
4. report <area…> を実行すると、記入用テンプレート .verify/report-<branch>.md が作成されます。
5. クリック操作で状態を作る代わりに、seed <state> で必要な状態にインスタンスを設定します。空のインスタンスにするには reset を使います。実行中の状態にする場合（再読み込み、または実行途中での切り替え）は、down を実行してから up --delay 4000 を実行します。
6. mark "<what you test>" を実行してから、ユーザーと同じ方法で機能を操作します。open、click、type、upload、press、wait-settle を使います。
7. 証跡を収集します。操作の後と再読み込み後に api <route> を実行します（open "/" で再読み込みされます）。network-summary --since-mark で操作によるリクエスト、ステータス、失敗を確認します。console --errors --since-mark でページエラーがないことを確認します。snapshot、またはプロダクトオーナー向けに screenshot を使います。レビュー担当者が操作を再生する必要がある場合は、trace start … trace stop を使います（npx playwright show-trace <zip>）。ページのウェイトに関する確認には perf を使います。
8. どの状態でも規則を確認します。a11y でアクセシブルな名前のないコントロールとタブ順序を確認します（APP-F6）。続けて viewport 375 812 を実行し、overflow と screenshot でスマートフォン幅を確認します（APP-F7）。その後、viewport 1440 900 を実行します。
9. デフォルトではモデルは偽物です。確認できるのは配線であり、文言ではありません。エージェントが書く内容を変更する場合は、up --real が必要であることを明記します。up --real はエージェントの動作を確認する場合に限り、CODEX_AUTH_FILE にある Codex ログインを使って実行します。
10. ユーザーから見えるものを追加または変更する場合は、同じブランチで docs/verify/ 内の該当ファイルを更新します（複数の領域にまたがる場合は、test/e2e/ 内のジャーニーも更新します）。check は、4つの H2 がないファイルを拒否します。規則の証明方法を変更する場合は、scripts/verify/VERIFY.json を更新します。check は、証拠も記録された延期もない規則を拒否します。

証明の基準

証明では本番経路を実行し、懐疑的なレビュー担当者が納得できる結果を示します。

• ページを操作し、通常のサーバー呼び出しを通します。eval はユーザー経路の実行後に状態を読み取ります。post は seed と同様に状態を準備するだけです。どちらも証明にはなりません。api／post --bearer <token> は、そのトークンの ID として動作します。
• インスタンスが fresh でない場合、そのインスタンスで得た証明は証拠になりません。
• 変更が影響する、到達可能なすべてのエントリーポイントと、成功、失敗、空、キャンセル／再実行、永続化の経路を網羅します（該当する経路は領域ファイルに記載されています。ジャーニー内の page.route、または停止中のサーバーによってリクエストが失敗します）。
• トリガーと安定した最終状態をセットで示します（mark、操作、--since-mark の証拠）。
• ピクセルではなく副作用を確認します。保存されたレコード（api /api/<route>）、実行行（api /api/runs）、再読み込み後または down／up 後の状態を確認します。
• 偽のモデルが認められるのは、本番の境界（同じランタイム、サーバー、ウェブの下にあるモデルプロバイダー）の背後で動作する場合に限られます。ウェブまたはサーバーを経由しないものは、ページのカバレッジにはなりません。
• 到達できなかったもの（ネイティブのファイルピッカー、OS のドラッグ＆ドロップ、実際のプロバイダー、本番環境のみ）を明記し、代わりに網羅した最も近い実際の経路も記載します。

証拠：まず最小コストで十分なものから

lint + contracts + unit tests → formal models → end-to-end journeys (fake models)
→ driven instance (verify) → real models on the instance (up --real)
→ the people's own use

あるレイヤーの合格は、より上位のレイヤーの主張を証明しません。単体テストの成功はページについて何も示さず、偽のモデルを使ったジャーニーは文言について何も示しません。

禁止事項

• リポジトリ、テスト、フィクスチャ、レポート、コミット済みのスクリーンショットのどこにも、実際のユーザーデータを含めないでください。創作したデータのみを使用してください。
• 本番環境をテストベッドにしないでください。verify up のインスタンスは自分のものであり、本番環境はユーザーのものです（docs/verify/deploy.md はデプロイ後に読み取り専用で確認します）。
• マージ、CI の成功、デプロイをもって「検証済み」としないでください。どこで何が実行されたかを確認するのがリリーススキルの役割であり、「不明」も有効な回答です。

検証済みとする前にレポートする

.verify/report-<branch>.md に記入し（report <area…> を使用）、プルリクエストの .github/pull_request_template.md のエビデンステーブルに貼り付けてください。

• コミット、doctor の行、check の結果（正式なモデルを実行したかどうかも含む）、モデル（偽物／実際のもの）。
• 領域ごとに、実行したパス、コマンド、観測された副作用（主要な出力）。
• スキップしたパス、または到達できなかったパス：それぞれを妨げるものと、代わりにカバーした最も近い実際のパス。
• ここで証明できていないこと（たとえば、文言の確認には実際のモデルが必要です）。