frontend-visual-qa

フロントエンドのビジュアル QA

ユーザーが実際に目にするインターフェースを監査します。ビルドの成功、DOM の存在、 未確認のスクリーンショットファイルは補助的なシグナルとして扱い、視覚的な証拠とは見なしません。

既定では監査のみとします。ユーザーから UI の修正または変更を明示的に依頼されない限り、 実装の編集、テストの追加、依存関係のインストール、スナップショットの更新は行わないでください。 ソースの修正許可があっても、対象の再ビルド、再起動、デプロイが許可されたことにはなりません。

範囲と振り分け

レンダリング済みの成果物が存在する場合にのみ、このスキルを使用します。依頼の範囲を満たす最小の監査 プロファイルを選択してください。

• コアビジュアル — 構成、タイポグラフィ、間隔、折り返し、クリッピング、画像。
• レスポンシブ — ブレークポイント、リフロー、モバイル向け代替表示、スクロールの担当範囲。
• 状態と導線 — 条件分岐、遷移、復旧、ルート。
• ブラウザー出力 — ダウンロード、共有、クリップボード、ポップアップ、ファイルダイアログ、印刷、PDF。
• ネイティブシェル — Electron またはハイブリッドのクローム、権限、ドラッグ領域、IPC UI。
• ページ契約 — ダッシュボード／管理画面、ランディングページ／デッキ、デザインシステムの成果物、 ブラウザーツール／ゲーム、地図／GIS、レビュー用ツール。
• 参照との一致 — 名前が指定されたスクリーンショット、製品、またはティアとの比較。
• データビジュアライゼーション — チャートの階層、トークン、セマンティクス、アクセシビリティ。

特定のタスク／オブジェクトへのリンク引き継ぎでは、遷移先に対して状態と導線を選択します。 タイトルが重複する場合は、権威あるマシンと実行／ジョブの識別情報も含めます。監査対象は、約束された遷移先に限定してください。

ウェブサイト／ドキュメントを Markdown に変換したもの、または Obsidian などの指定されたリーダーで読む 図解付きトランスクリプト／ノートについては、図の読みやすさを評価する前に references/markdown-reader-handoff.md を読み込んでください。HTML のキャプションや SVG／CSS の依存関係も含め、元の図全体と、実際のドキュメント閲覧キャンバスを比較します。 埋め込み画像が大きすぎる場合は、指定された表示サイズの手順を使い、代表的な縦長画像と隣接するテキストを一緒にテストしてから、 そのレイアウトをドキュメント全体に適用してください。

変更された画面領域やユーザーの依頼によって、広範なリリースレビューが必要な場合にのみ、プロファイルを組み合わせます。 局所的な改行のレビューを、無関係な認証、地図、エクスポート、ネイティブシェルのチェックに無理に結び付けないでください。

段階に応じて、関連するスキルを併用してください。

• ビジュアルの方向性を導き出す／作成する場合や、参照スクリーンショットからデザインシステムを抽出する場合は、 ui-designer、frontend-design、または別のデザインスキルを使用してください。 このスキルは、すでにレンダリングされた成果物を監査するものであり、方向性を導き出すものではありません。
• 目に見える不具合につながっていないロジック、データ、バックエンドの正しさなど、非ビジュアルなコードのデバッグではなく、 すでにレンダリングされた結果のテストにこのスキルを使用してください。
• テスト戦略全体、不具合対応プログラム、リリース指標には qa-expert を使用してください。
• レンダリング済みの視覚的証拠が、より広範な QA ゲートの一部である場合にのみ、このスキルと qa-expert の両方を使用してください。
• このスキルでは、形状だけでなく、レンダリングされた情報階層も対象とします。持続的なラベル、説明、繰り返される文脈が 作業者のタスクに役立つか、あるいは妨げになるかを確認します。この問いを単なる文言の微調整として、別の担当に回さないでください。 領域固有の事実の正確さ、用語、説得力には、適切なコンテンツレビューまたは専門家レビューが引き続き必要です。 レンダリングの確認だけでは、そうした主張の正しさを保証できません。

必須の成果

対象を引き継ぐ前の準備

実行担当の監査者は、共有ブラウザーまたはデバイスを操作する前に、最新のユーザー要件と、ステージ固有のスキルを確認します。このタスクで明示的に指定されたスキルを、実際のエントリーから読み込みます。数値の内訳やグラフを扱う場合は、data-visualization-discipline も使用します。Android を操作する場合は、このビジュアル監査と併せて android-automation を使用します。デザインスキルを追加するのは、ユーザーが指定した場合、またはタスクによってデザインが変更される場合に限ります。デバイスを操作するだけでは、ビジュアル面またはビジネス面の受け入れ基準にはなりません。

選択した最新のスキル本文と、影響を受ける参考資料を読み、そのうえで、担当者の質問、正規の対象、影響を受ける状態、観察可能な回答を固定します。カタログのエントリー、記憶しているセクション名、またはコンテキスト要約は、場所を特定するための手がかりであり、読み込み済みの指示ではありません。コンテキストに変更のない文章が残っている場合は再利用し、コンテキスト圧縮後は、完了済みのテストを再実行せずに必要な指示だけを読み直します。

この準備について、既存のスコープ要件書に、必要な機能、特定した所有者／エントリー、それが提供する受け入れ証拠を記録します。指示が不足している場合、依存する判定は未検証とし、許可された独立した読み取り専用の作業は続行します。共有リソースを使用する短時間のウィンドウに入る前に、ツールと依存関係の準備を完了し、そのウィンドウが終了したら、対象制御の所有者が定める復元要件に従います。これらは監査者が行う作業であり、自動的なスキル読み込みガードがあるという主張ではありません。

次のすべてを作成します。

1. アーティファクト、担当者、作業、対象の種類、正規の対象識別情報、条件付き状態、ビューポート、影響を受けるユーザージャーニー、参照資料／SSOT、認可を明記したスコープ要件書。
2. 検証ステータス：検証済み、部分的、またはブロック。
3. 可視の証拠、影響、状態、ビューポート、再現手順に結び付けた所見。
4. 実際に実施した内容と、未検証のまま残っている内容の一覧。
5. 最新性またはデプロイが主張されている場合は、独立したデリバリーステータスとその識別証拠。対象の変更が明示的に許可されている場合は、変更前後の識別情報、同じ対象／状態／ビューポートでの再実行、回帰を防ぐためのガード。

証拠を集めやすいという理由で、ユーザーの本来の目的を矮小化してはなりません。

ワークフロー

重要な監査では、このチェックリストを追跡します。

- [ ] 1. 監査要件と認可を確立する
- [ ] 2. 必要な証拠レベルと正規のハーネスを選択する
- [ ] 3. 対象、状態、データ、ビューポート、主張されている最新性を確認する
- [ ] 4. マクロ、ローカル、レスポンシブの各証拠を取得して調査する
- [ ] 5. 影響を受けるユーザージャーニーと受信者向けの出力を実行する
- [ ] 6. 所見を報告し、許可されている場合に限り修正と再実行を行う

1. 監査契約を確立する

プロジェクトの指示、デザインシステムの SSOT、トークン、承認済みアセット、 ランチャー／テスト SOP、および変更されたコードを読みます。次に、反証可能な契約を記述します。

成果物／ページ種別:
アクターとジョブ:
ターゲット種別 + 正規の識別子:
  web = ブラウザ内の正確な URL（クエリ／フラグメントを含む）+ 名前付き環境
  単一ファイル／画像 = 正規パス + コンテンツハッシュ + レンダリング方式
  複数リソースの成果物 = 正規のエントリ + 依存関係／マニフェストのダイジェスト + レンダラー
  native = インストール済み成果物のフィンガープリント + ビルド／バージョン + プロセス／ウィンドウ + レンダラールート
条件付き状態:
配信識別子／ステータス。ただし鮮度やデプロイが主張される場合のみ:
参照またはデザインシステムの SSOT:
関連するビューポート／デバイスマトリクス:
意図する投影／キャンバスサイズ（存在する場合）:
影響を受けるインタラクションと出力:
監査プロファイル:
ソースの権限: 監査のみ | 修正と検証
インタラクション／アクションの権限: 読み取り専用ナビゲーション | フィクスチャで安全な状態変更 | <名前付きアクション>
ターゲット変更の権限: なし | 分離された診断 | ローカルターゲット | <名前付き環境>へのデプロイ
アンチゴール／なってはならないもの:
合格条件:

ピクセルを判定する前に、正しい状態を特定します。ログアウト、オンボーディング、空、 権限拒否、シード済み、データ投入済み、読み込み中、およびフィーチャーフラグの各分岐は、 別の製品のように見えることがあります。誤った分岐のきれいなスクリーンショットは無効です。 認可がスコープ内にある場合、サインイン済みだがロールなしというのは別個の分岐であり、 ログアウト状態や完全な権限を持つ証拠ではそれを代用できません。

成功目標としてアクターのタスクを用います。「グラフが存在する」とか「タブが 切り替わる」といった程度では、ユーザーが重大度を判断したり、レビューを完了したり、 エラーから復帰したりする必要がある場合には不十分です。

ユーザーの要件を実装とは別に凍結します。煩雑さ、冗長な説明、無駄なスペースに関する 不満は、丸で囲まれた要素だけでなく、失敗のクラスを特定します。宣言された全面にわたって そのクラスを検査します。レビューを最後のスクリーンショットの矩形に黙って狭めたり、 候補が失敗した後に要件を「タスクは引き続き可能」と書き換えたりしないでください。

合格条件が視覚的参照 — スクリーンショット、別製品のページ、「うちのをあちらに似せる」 — を挙げている場合、 references/reference-parity-decomposition.md を実装を判定する前に、そして修正と検証モードでは次の修正ラウンドを書く前に 読み込みます。これはスキルの実装後スコープを広げるものではありません。分解は 監査の最初の行為であり、参照成果物（常にすでに存在する）に適用され、各パリティ 修正ラウンドはこのスキルの修正と検証権限の内部で行われる実装です。同じ要求が ゼロから作成する視覚的方向性も必要とする場合、その部分は依然としてデザインスキルに 属します — 完成したインベントリをそこへ引き渡し、そこで再導出しないでください。 契約の最初の成果物は、参照の測定された構造インベントリであり、パリティ判定は そのインベントリに対する関係ごとの差分です。ユーザーの最新スクリーンショットが 不満を述べている差分だけをラウンドごとに修正しても、ユーザーを疲弊させることによって のみ収束します — 実際の 5 ラウンドのケースがそのファイルで分解されています。それは また、インベントリより長く生き残る 2 つの罠を統制します。あなた自身の幾何学的な主張は パリティにとってレベル D であり（それらは参照に対するあなたの読みを符号化し、誤読を 通しても緑のままです）、エフェクトに対するユーザーの拒否（「画像を絶対にクロップするな」） は、エフェクトを強制する構造的前提を告発するのであって、その趣を選ぶパラメータを 告発するのではありません。階層参照と比較される報告グレードのデータページについては、 そのファイルと references/data_viz_tier_and_token_audit.md が作業を分担します。分解はページ構造を統制し、階層ベンチマークはデータ提示 パラメータを統制します — 両方を読み込んでください。

2. 証拠レベルを選択する

主張に必要な最も強いレベルを使用します。

レベル	証拠	裏付けられる主張
A	ユーザージャーニーに沿って操作した、実際に表示されている Chrome／ブラウザー、または標準的なネイティブアプリのウィンドウ	ブラウザー／OS のクローム、ダウンロード、クリップボード、ポップアップブロック、ファイル選択／ダイアログ、印刷プレビュー、権限、ネイティブシェル、実際に表示されるウィンドウに関する問題
B	同じ状態のブラウザー DevTools、または代表的なデータを使ったプロジェクトの E2E／Playwright 実行	DOM のジオメトリ、ルート、フォーカス、オーバーレイ、インタラクション状態、再現可能なレスポンシブ動作
C	同梱スクリプトによる、新規のヘッドレス機械的スイープ	はみ出し、折り返し、画像、基本的なレイアウトのヒューリスティック、スクリーンショット候補
D	ソース、Lint、ビルド、ユニットテスト、静的 DOM の推論	仮説およびリグレッションの裏付けのみ

低いレベルの証拠を、より強い結論として扱わないでください。

• 開かれていないスクリーンショットのパスには、視覚的な証拠としての価値はありません。
• 新規のヘッドレス空状態では、ユーザーのデータ入力済み状態を検証できません。
• レンダラーの URL では、Electron／ネイティブシェルを検証できません。
• ハンドラーの呼び出しでは、Chrome の印刷プレビュー、ポップアップ、ダウンロードの UI を検証できません。
• ポインターカーソル、ホバースタイル、「クリックして X」といったバッジだけでは、クリックして何かが実行されることを検証できません。機能するハンドラーのない視覚的な手掛かりは、機能しないクリックです。これを確認できるのは、実際にクリックした場合のみです（ステップ 5）。
• デバイスエミュレーションは近似です。デバイス固有の動作が重要な場合は、実機を使用してください。

必要なレベル A の対象環境を利用できない場合、または別のセッションが GUI を使用している場合は、その代わりになると誤解させない証拠だけを使って作業を続けてください。不足している証拠を正確に報告し、該当する主張に partial または blocked のマークを付けてください。

3. 対象、状態、ビューポートを立証する

何かを起動する前に、プロジェクトが正式に管理するステータスを確認します。標準のランチャーは、それぞれの副作用が対応する権限の範囲内にある場合にのみ使用してください。ライフサイクル権限で許可されるのは再ビルド／再起動／デプロイです。一方、シードデータやトランザクションデータの変更にはインタラクション／アクションの権限が必要です。一方の権限から、もう一方の権限を推測してはなりません。許可された分離診断サーバーには、対象外であることを明記します。

ブラウザーのメモリには正確な Web URL を保持しますが、永続化するのは、構造を保った上で秘匿化した URL と、安定したダイジェスト／クエリキーの一覧のみです。単一のファイル／画像には、パス、コンテンツハッシュ、レンダラーを使用します。複数リソースで構成される HTML／デッキには、正式なリソースマニフェスト、または依存関係全体のダイジェストが必要です。ネイティブ UI では、インストール済みアーティファクトのフィンガープリント／コード署名に加えて、ビルド、プロセス／ウィンドウ、レンダラールートを確認します。レンダラーの開発 URL は診断用途に限られます。未加工のスクリーンショットは、ローカルで一時的に扱う機密証拠として扱ってください。共有／コミットするのは、必要最小限に秘匿化した派生物のみです。

主張がソースの変更、新しさ、またはデプロイに関するものである場合は、さらにソースから対象までのつながりを確認します。

1. 期待される識別情報は、ローカルの HEAD からではなく、対象のリリース契約から取得します。ただし、その対象で HEAD を実行する想定の場合は除きます。
2. プロジェクトが正式に管理する、実行時のビルド／イメージ／リリースのステータスを確認します。
3. ブラウザー／データプレーンの証拠を期待されるアーティファクトに対応付けます。期待されるマニフェストで対応付けられていない限り、ハッシュ付きのファイル名だけでは何も証明できません。
4. 想定するルート、アクター、データ、条件付き状態、ビューポートを立証します。

GET で読み取り可能な Web リソースについては、 配信の検証に従い、デプロイが一致していると主張する前に、同梱のマニフェスト比較を実行してください。別途配信される埋め込みコンポーネントも含めます。その結果で確認できるのは、与えられた識別情報のチェックのみです。ピクセルの目視確認と実際のユーザージャーニーは、独立した確認項目として扱ってください。 アイデンティティのマッピングがなければ、鮮度やデプロイに関する主張は証明不能です。どちらも主張されていない場合は、該当なしとします。現在のピクセルは、引き続き独立して検証できます。 ソース側の修正とターゲットが異なる場合、その完了状態は部分的 — ソースは修正済み、検証対象は古いままです。監査のみを行う作業では、変更を加えずに稼働中のターゲットを調査し続けます。ソース修正の権限だけでは、ターゲットのライフサイクル操作は許可されません。ターゲットの変更について別途許可されている場合は、操作前にアイデンティティを記録し、指定された正規のライフサイクル操作のみを実行して、アイデンティティを再証明し、同じターゲット、状態、ビューポートで再確認します。ライフサイクルの所有者が未確定の場合、この変更経路はブロックされています。

キャッシュを無効にした再読み込み、または新しいコンテキストを優先してください。クエリの変更は、プロジェクトで意味的に影響しないと宣言されている場合に限り、既存のクエリやフラグメントを保持したまま行い、最終的な証拠は元の URL で取得します。詳細なページ状態の調査、file:// の境界、キャッシュのルール、リダイレクト、ビューポートの比較については、 references/browser-driving-and-observation-traps.md §2～§5を参照してください。CSS の診断を始める前に、最終 URL と寸法を記録し、完了後にユーザーが想定するビューポートに戻します。

読み込み速度に関する主張を検証する場合は、測定前に§2のパフォーマンス比較の境界を確認してください。

スクリプトによる一括検査では、まず以下のいずれかでターゲットの状態を再現できることを証明してください。

• プロジェクトのフィクスチャ／ストレージ状態／セットアップの経路。
• --require フラグを繰り返し指定して渡す、必須のレンダリング済みマーカーを1つ以上。
• 更新後も同じ状態が復元される、直接リンク。

それ以外の場合は、検査結果を合格ではなく新規セッションの診断と記してください。

監査でSPAへのサインインが必要な場合、スクリプトによるログインが失敗するか認証ルートに戻される場合、またはシェルのプロキシ経由でlocalhost上のターゲットを実行している場合は、ログインやネットワークに関する問題を報告する前に references/auth-session-and-environment-traps.md を確認してください。こうした失敗は通常、製品の不具合ではなく、操作ハーネスや環境が不具合を装っているものです。

認証後は、記憶しているサイドバーのラベルに基づいて操作したり、ターゲットのナビゲーションがすでにマウント済みだと想定したりしないでください。最終 URL、表示されている本文の短い抜粋、現在利用可能なリンクとボタンを記録してから、レンダリングされたランディングページが実際に提示している正規のエントリをたどります。想定されるロケーターが見つからない場合は、ターゲットのルート／状態が独立して証明されるまで、ナビゲーション契約またはハーネスのドリフトを第一の診断候補としてください。

4. レンダリングされた証拠のキャプチャと確認

不具合を拡大表示する前に、表示範囲全体の構成をキャプチャし、続いて影響を受けるコンポーネント、関連するレスポンシブ幅、下部のセクションをキャプチャします。各スクリーンショットを画像ビューアーで開いて、確認した内容を記録してください。未確認のファイルは証拠になりません。

キャプチャを信頼する前に、キャリブレーションを行ってください。DOMのジオメトリーに照らして見かけ上のクリッピングを反証し、サポートされている場合はデバイススケールを固定して、フォント、ネットワーク、アニメーションの準備を待ち、受信者が実際に見るエンジンを使用します。DOMの証拠はピクセルの説明にはなりますが、ピクセルそのものの代わりにはなりません。

キャプチャの完全なキャリブレーション手順と最低限の確認項目については、 references/browser-driving-and-observation-traps.md §12を参照してください。ヘッドレスキャプチャ特有の範囲やデバイスエミュレーションの落とし穴は、同じリファレンスの§4～§5にまとめられています。

横方向のホイール入力でオーバーフローしている<pre>を読む前に、 新しい入力ターゲットの確認 を読み、スクロールの動きだけで判断せず、影響を受けるテキストの位置を確認してください。 コアとなる視覚・レスポンシブの不具合カタログと、標準に基づくチェックについては、references/history-derived-checklist.md を読み込んでください。 構成や密度を監査する場合は、改行を修正する前に、その「情報の必要性をレイアウトより先に確認する」チェックを実行してください。スイープの attentionInventory を使うと、表示されるテキスト全体と完全に一致する繰り返しを確認できます。繰り返し候補だけでなく、全体をタスクに照らして確認してください。 全件を確認しても、コンテンツが必要であることの証明にはなりません。

診断にまったく現れない不具合もあります。たとえば、グローバルリセットがコンポーネント独自のスタイルより優先される、ライブラリが内部 DOM クラスの名前を変更したためルール群全体が一致しなくなる、フォントファミリーが宣言されているのに配布されていない、ソーススキャンでは確認できないテーマ設定にジオメトリが記述されている、ファイル内ですでに使用済みの名前が新しいデザイントークンに再利用されている、前提となるレイアウトモードがルールで設定されていないためプロパティが適用されない、要素単位では基準を満たしていても全体として「デザインシステムがない」ように見える、といったケースです。ソースレビュー、型チェック、ジオメトリアサーションでは、こうした問題を構造上検出できません。成果物は有効でも、何の効果もありません。すべてのゲートが成功しているのにページが安っぽく見える場合、その組み合わせが兆候です。クラスごとの検出方法については、references/silent-degradation-and-evidence.md を読み込み、検出効果の高い上位 2 つを機械的に調べてください。

node <skill-root>/scripts/silent_degradation_probe.mjs font \
  --url http://127.0.0.1:5173/ --weight 700 \
  --family "Brand Sans" --family "Fallback Sans"

node <skill-root>/scripts/silent_degradation_probe.mjs class \
  --css path/to/bridge.css --library-css node_modules/<lib>/dist/<lib>.css

フォントスタック内のすべてのファミリーと、ページで実際に使われるウェイトを渡してください。5 種類すべての判定をそのまま解釈してください。プラットフォームの汎用フォントは問題ありません。不具合となるのは、ホスト提供フォントのみの場合とアセットが壊れている場合だけです。計算後のフォントファミリー名、document.fonts.check()、未ロードの候補、CJK のみの幅プローブが、誤った結論につながる理由については、リファレンスで説明しています。

監査対象のプロジェクトから同梱のスイープを実行し、プロジェクトに既存の Playwright 依存関係を解決できるようにしてください。

node <skill-root>/scripts/visual_layout_audit.mjs \
  --url 'http://127.0.0.1:5173/?state=fixture#/ready' \
  --page-type app \
  --require "Expected state marker" \
  --screenshot-sections

ローカルの HTML 成果物には、--file <artifact.html> を使用してください。すべてのフラグを確認するには、node /scripts/visual_layout_audit.mjs --help を実行してください。キャンバスのサイズが固定されている場合は、ビューポートを 1 つ以上正確に指定してください。カスタムビューポートを指定すると、デフォルトのレスポンシブマトリックスは置き換えられます。

node <skill-root>/scripts/visual_layout_audit.mjs \
  --file deck.html --page-type deck --viewport 1920x1080 \
  --screenshot-sections

画面下部のカバー画像やサムネイルが証拠の一部となる長いページでは、--scroll-visible-media を追加してください。キャプチャ前に描画済みのメディア行へ移動することで、遅延読み込みを開始できるようにします。その際、CSS で非表示になっているレスポンシブ用の代替要素は除外されます。このフラグを指定しない場合、画面外にある遅延読み込みメディアは、アセットの破損ではなく、読み込み未完了として報告されます。どちらの場合も、スクリーンショットを確認してください。「リクエストされていない」「読み込み中のまま」「リクエスト完了後にデコードできない」は、それぞれ異なる状態です。

--forbid パターンを繰り返し指定するのは、プロジェクト固有の古い名前、または現在の製品仕様で明示的に禁止されている表示用語に限ってください。一般的な好みを禁止正規表現として設定しないでください。

スクリプトの終了コードは次のとおりです。

• 機械的なエラーが残っていない場合は 0。
• エラーが残っている場合、または --fail-on-warning を指定していて警告が残っている場合は 1。
• 入力が無効、前提条件が不足、または実行時・セットアップ時に失敗した場合は 2。 このスクリプトはスクリーンショットと JSON レポートを一意の一時実行ディレクトリに書き込みます。明示的に指定する --out は、新規または空のディレクトリでなければなりません。これは Level C のスイープであり、最終判定ではありません。生の証拠をコミットまたは共有しないでください。レポートではレンダリングされたラベルをハッシュ化し、対象由来の値を墨消しします。また、派生スクリーンショットでは識別可能なピクセルを墨消しする必要があります。対象文字列のフィンガープリントと単一ファイルのバイトハッシュでは、複数リソースの依存関係全体やネイティブな識別情報は計算されません。プロジェクトの契約を提示してください。

スイープを実行するだけのために、監査対象のプロジェクトを変更しないでください。プロジェクトのパッケージマネージャーと標準のブラウザーハーネスを再利用してください。Playwright がない場合は、利用可能な Level A/B の証拠を使って続行し、省略した Level C のスイープについて報告してください。依存関係の変更が許可されている場合に限り、依存関係をインストールしてください。

ヘッダーは --header-env "Name: ENV_NAME" で渡してください。argv に含めるのはヘッダー名と環境変数名のみで、値は含めないでください。生の --header は無効です。値は対象のオリジン内にとどめてください。明示的に信頼された自己署名オリジンを除き、TLS は有効のままにしてください。

Playwright をすでに提供しているプロジェクトからプローブのリグレッションを実行してください。

node --test <skill-root>/tests/test_silent_degradation_probe.mjs

5. ジャーニーと出力の検証

データ連動型のコントリビューションビューや複数アイテムの読み取りに変更がある場合は、合格と判定する前に、リンク先のジャーニー契約で定められた範囲内のウィンドウのカバレッジ、表示されるコントリビューション、混在した結果からの復旧を確認してください。これらは、認可されたプロジェクトハーネスを通じて監査担当者が行う操作であり、汎用スイープで強制される述語ではありません。

UI のリファクタリング、カテゴリの分割、ナビゲーションの変更では、まず references/journey-and-page-contracts.md の リファクタリングの維持レシピを適用してください。 変更前の不変バージョンから影響を受けるジャーニーを特定し、現在の対象で検証してください。新しいナビゲーションだけでは、何が維持されたかを判断できません。

**表示されている手がかりは、動作の証拠ではありません。副作用が明示的な操作権限の範囲内にある、関連するすべてのコントロールを実際に操作して応答を確認し、それ以外は未検証として扱ってください。**ポインターやホバー、ボタンのスタイルは、実際にはハンドラーが存在しない、または古いままなのに、操作できそうに見える誤った手がかりになることがあります。一方で、スクリーンショットともっともらしいソースコードはいずれも問題なく見えることがあります。動作を検証できるのは、Level A/B の実操作だけです。後から追加されたライトボックス、サムネイルグリッド、コピー操作を優先してください。イベントのディスパッチではなく、結果として生じた状態を確認してください。また、クリックが機能しないと判断する前に、イベント委譲、ハイドレーションのタイミング、信頼されたユーザー操作のゲートが原因でないことを確認してください（browser-driving-and-observation-traps.md のトラップ 1）。正常に動作する機能の周囲に視覚的な手がかりがない場合は、silent-degradation のリファレンスに記載された逆の問題です。

関連する遷移マトリクスのみを検証してください。

開始 -> 準備完了 -> アクティブ -> 処理中 -> 成功／エラー -> 復旧 -> 準備完了

該当する場合は、次の項目も確認してください。

• クリック -> URL／状態 -> 更新 -> ディープリンク -> 戻る／進む
• ドロワー／モーダル／ポップオーバーの開閉、フォーカス、背景操作、終了、およびモバイルでの動作
• トリガー前に観測を開始したうえでの、一時通知のライフサイクル
• 詳細モード -> 現在のモードとトリガーの所有者が表示されること -> デフォルトへのワンステップでの復帰
• プロバイダー／モデル／ランタイムのステータス -> 選択された構成と現在のステータスを示す証拠
• ダウンロード -> ファイルの完成 -> 受け取り側での成果物のオープン
• 共有 -> URL のコピー／オープン -> 受け取り側の状態の更新
• ファイルピッカー／ダイアログ -> 開く／キャンセル／選択のパスが表示されること -> アプリの状態が復旧すること
• 印刷／PDF -> 実際の Chrome プレビュー -> 空白でないページ
• Electron／ネイティブ -> 正規のアプリプロセス／ウィンドウ -> ネイティブコントロールとシェル

監査に状態遷移、認可、モード、要約から詳細への開示、プロバイダー／モデル／ランタイムの真実性、ルート、一時的な状態、オーバーレイ、ブラウザー出力、ネイティブシェル、ランディングページ／デッキ／ブラウザーツール／ゲームの成果物、ダッシュボード、デザインシステムの成果物、GIS／マップ、またはレビュー用ツールが含まれる場合は、 references/journey-and-page-contracts.md を読み込んでください。

元の証拠を示すことを約束する引用マーカーについては、対象となる実際のテキスト、画像、または PDF とその戻り経路に対して、そのリファレンスの 引用元の検査を実施してください。

報告品質を求められるデータページ、名前付きのティア／参照比較、チャートトークンの監査、またはカテゴリ別パレットに該当する場合に限り、 references/data_viz_tier_and_token_audit.md を読み込んでください。

重大な監査について報告する前に、デバッガーのコンテキストなしで、疲れたユーザーのつもりで主要な操作経路をもう一度たどってください。最初に、トリガーやモードの所有者が不明確ではないか、デフォルトへの復帰方法が隠れていないか、復旧が妨げられていないか、ランタイムのラベルが誤解を招かないか、生の機械向け表現がないか、操作できないコントロールがないか、避けられる手作業がないか、同じ不具合の再発を防ぐガードが欠けていないかを確認してください。これは反証を試みる工程であり、局所的な視覚のみの監査をあらゆるプロファイルにまで拡大する口実ではありません。

6. 報告、修正、再実行

外観に関するすべての主張には、その状態を示すピクセル画像を添付してください。 欠陥を目で確認できない読者は、それについて何も判断できず、指摘が実際に正しいかどうかも確かめられません。影響を受けた要素を、場所を特定できる最小限の周辺情報を含めて切り抜いてください。ページ全体のスクリーンショットでは14pxのずれを証明できません。また、文章だけの説明（「ボタンが安っぽく見える」など）は、どれだけ正確でも対応につながりません。scripts/silent_degradation_probe.mjs shot は、そのために要素1つと余白を切り抜きます。

証拠が読者の目に触れても有効であるための、4つのルールです。比較画像は同じ縮尺にしてください（全幅の領域を2つ並べると、縮小されて議論対象の3pxの差が見えなくなります。代わりに、両方を同じ幅の同じコンポーネントに切り抜いてください）。寸法はデバイスpxではなく、CSS pxで報告してください（DPR-2のキャプチャはピクセル数が2倍になり、それをページの高さとして記載したことで、「20画面分の長さ」という誤った指摘につながったことがあります）。修正前のキャプチャには、現状のものとして提示するのではなく、表示されているコミットを明記してください。そして、コードの件数に基づき、画像に基づかない指摘にはその旨を記載し、一覧のどの部分に同程度の証拠があるのかを読者が把握できるようにしてください。

影響度とカテゴリを分けてください。プロジェクトに重大度の分類がある場合はそれに従ってください。ない場合は、次の分類を使用してください。

• Blocker — 成功したように見せかける、破壊的または誤解を招く操作、あるいは安全な回避策なしでは主要な利用フローを完了できない。
• Major — 中核となるタスク、受信者向けの出力、復旧、ルート、または重要なコントロールが使えない。
• Moderate — 理解または操作に実質的な支障があるが、安全な回避策がある。
• Minor — タスクへの影響が小さい、仕上げ上の欠陥。

layout、responsive、state、route、accessibility、browser-output、native-shell、intent、taste などのカテゴリを使用してください。Taste と Intent は重大度ではありません。

次の簡潔なスキーマで報告してください。

現在のレンダリング状況：verified | partial | blocked
配信状況：matched | mismatched | unprovable | not applicable
修正完了状況：verified | partial | blocked | not applicable
対象：<web: 要求時／最終時の情報を秘匿したもの + target-string のフィンガープリント／クエリキー／リダイレクト | 単一ファイル／画像：正規パスを秘匿したもの + コンテンツハッシュ + レンダラー | 複数リソース：エントリー + 権威あるマニフェスト／依存関係クロージャのダイジェスト + レンダラー | ネイティブ：インストール済み成果物のフィンガープリント／署名 + ビルド／バージョン + プロセス／ウィンドウ + レンダラールート>
環境：<検証済みの名称または未検証>
配信 ID：<期待値、観測値（変更前 -> 変更後）、証拠>
実行者／ジョブ；参照／合格条件；影響を受ける利用フロー：
認可：<範囲の情報源；インタラクション／操作の範囲；対象変更の範囲>
対象範囲：<状態、ビューポート、プロファイル>

指摘事項：
- Major · browser-output · PDF action · desktop
  影響／状態／ビューポート／再現手順：
  証拠アーティファクト／切り抜き：
  証拠：表示されているコントロールをクリックすると about:blank が開き、印刷プレビューにはページがありません。
  修正：ユーザージェスチャーに安全な印刷方法を使用し、受信者向けプレビューを再テストしてください。

参照との一致状況の一覧（パリティ監査のみ）：
- <関係 -> matched | deliberately diverged（導出根拠） | not yet。各項目を1行で記載>

検証済み：
- <利用フロー／状態／ビューポート + 具体的な証拠>

未検証：
- <不足している画面／証拠と、その理由>

監査のみモードでは、読み取り専用で証拠収集を続け、ソースや対象に変更を加えないでください。修正と検証モードでは：

1. オーバーフローを隠したり、すべての文字サイズを小さくしたり、検出を回避するためにセレクターを変更したり、機能を削除したりせず、根本原因を修正します。
2. 共有ビジュアルトークンを確定する前に、主観的な代替案をその場でプレビューします。
3. 個別に指定された変更権限のもとでのみ対象を更新します。それ以外の場合は、スコープを拡大せずに、ソース修正済み／対象未検証と報告します。
4. 同じ正規の対象を再実行し、同一性、ルート、状態、ビューポート、操作の流れ、受信者への出力を改めて実証します。
5. 確認された不具合のクラスを検出できる、最小限の回帰防止策を追加または更新します。

修正作業で新たな不具合を生み出さないための習慣が3つあります。どれも実際に不具合を1件ずつ生み出したことがあります。

• 不具合が存在しているうちに「修正前」の画像を撮ります。 再ビルド後には再現できなくなり、完了報告では改善したと主張することしかできなくなります。修正前後の比較で変数を1つだけにするため、修正後の画像にも同じ切り抜き範囲を使います。
• 新しい共有名を導入する前に、Grep で検索します。 ファイル内ですでに使われている語（rail、bar、card）を名前にしたトークンは、定義順によって別の定義を暗黙に上書きしたり、逆に上書きされたりし、2つのサブシステムを同時に変更します（サイレント劣化クラス 1f）。
• 修正したアサーションが失敗することを実証します。 不具合を再発させ、想定どおりの規模で失敗することを確認してから、不具合を取り除きます。不具合の全期間を通じて成功し続けたアサーションは、書き換えただけでは防止策になりません。

完了判定

次の条件を満たした場合にのみ、現在のレンダリングのステータスを検証済みとします。

• 正規の対象の種類／同一性、最終対象、データ、アクターの状態が実証されている。
• 最新性が主張されている場合は配信が一致、不一致、または実証不能と判定されている。それ以外の場合は該当なしとされている。
• 報告書で引用したスクリーンショットがすべて開かれ、確認されている。
• 関連するビューポートと下部のセクションが確認されている。
• 影響を受けるインタラクションと出力が、求められる証拠レベルで検証されている。
• この確認作業と矛盾する未解決の Blocker／Major の指摘がない。
• レイアウト／密度が対象範囲に含まれる場合の情報の必要性を含め、明示された合格条件がすべて満たされている。違反を Moderate、Minor、好み、または「まだ使える」と呼んでも、ユーザーの要件が優先されます。
• 残る制約が明示されている。

修正完了のステータスは、承認された修正を同じ正規の対象／状態／ビューポートで再確認した後にのみ、検証済みとします。それ以外の場合は、一部完了またはブロックとします。

それ以外の場合は、一部完了またはブロックと報告します。利用可能なエージェントツールで実行できる確認を、ユーザーに依頼してはいけません。

同梱リソース

• scripts/visual_layout_audit.mjs — Playwright を活用した、ビューポート、レイアウト、メディア状態の機械的な一括検査。スクリーンショットと JSON の証拠を出力します。
• scripts/attention_inventory.mjs — 検査で使用する、観察されたテキスト／ジオメトリ、反復、ラベルの反響のインベントリです。必要性を認定することはありません。
• scripts/painted_text_probe.mjs — 検査で使用する、垂直方向のテキストフラグメントのクリッピング検査です。調査済み範囲と、サポートされていないクリッピング／スクロールウィンドウを報告します。
• scripts/journey_input.mjs — 認可済みのブラウザーアダプター向けの、非 TTY の JSONL 入力です。コマンド全体を保持し、失敗時には依存するステップを停止します。
• references/history-derived-checklist.md — 中核となる視覚／レスポンシブの不具合カタログと、標準に基づくチェック項目です。
• references/journey-and-page-contracts.md — 状態、ルート、オーバーレイ、ブラウザー出力、ネイティブシェル、ページタイプの契約です。
• references/markdown-reader-handoff.md — 実際の Markdown リーダーでの図全体の比較、依存関係の診断、認可された読みやすい画像への修正について記載しています。
• references/auth-session-and-environment-traps.md — 認証が必要な SPA でのログインとログイン後のナビゲーション操作を妨げる要因、および環境乗っ取りの診断（プロキシ、CSP のエントリーポイント、サーバーログによる三角測量）について記載しています。
• references/data_viz_tier_and_token_audit.md — 条件付きのデータ可視化、参照ティア、トークン、パレットの監査について記載しています。
• references/reference-parity-decomposition.md — 参照同等性プロファイルの手法について記載しています。評価や修正の前に指定された参照の構造を測定してインベントリ化する方法、判定基準を含む関係性ごとの同等性判定、自己作成のアサーションが同等性においてレベル D となる理由、拒否前提の分析、アセットの忠実度、（値ではなく）関係性の翻訳、レポート前の確認リストが含まれます。
• references/browser-driving-and-observation-traps.md — 監査担当者自身の失敗要因について記載しています。クリックの誤読、古いキャッシュ、file:// の制限、ビューポートとページのスクリーンショットの違い、幅の変更とデバイスエミュレーションの違い、デフォルトのスクリーンショットでは確認できない状態、非表示タブでのメディア読み込みの遅延、仮想時間による偽陰性、--dump-dom のタイミング（および適切に実施するタイトル埋め込み型インタラクションプローブ）、Range サーバーでのメディア停止が含まれます。実際のブラウザーを操作する前と、観察結果に違和感があるときは必ずお読みください。
• evals/evals.json と evals/trigger-evals.json — 動作とルーティングのリグレッションケースです。パッケージ化されたランタイムコンテンツからは除外されています。