source-html-to-app-ui

Source HTML からアプリ UI へ

目標

承認済みのソース HTML を、実際に動作するターゲットアプリケーションとして再現します。完成したエクスペリエンスを主な成功基準とします。

• すべてのソースページ、意味のある状態、表示セクション、操作の種類を再現します。
• 根拠がある場合は、ソースのコンテンツ、階層、レイアウト、スタイル、コントロール、動作をターゲットで維持します。
• デスクトップ、モバイル、画面高が短い場合、テーマ、ドロワー、オーバーフローの各動作を使いやすく保ちます。
• 対応する Playwright の証拠により、同じルート、状態、テーマ、ビューポート、セクションでソースとターゲットが一致していることを示します。
• 最終監査で不足している品質対応を特定して修正してから、正確なタスク完了コマンドを実行します。

調査と比較にはソース HTML を使用します。ターゲットは、実際のルート、コンポーネント、スタイル、アセット、ローカル UI 状態を備えた通常のアプリケーションとして作成します。タスクの範囲は UI のみとし、バックエンド、API、データベース、永続化、認証、サーバー、ビジネスロジックは追加しないでください。

厳格な実行契約

<execution_contract>

これはエンドツーエンドの実装ワークフローであり、任意の助言ではありません。フェーズに合格すると次のフェーズに進めますが、それだけで完了として停止してはいけません。次のフェーズに進める状態であれば、自動的に続行してください。フェーズ 4 に合格し、正確なタスク完了コマンドが正常に実行されるまで、タスクは完了していません。

すべてのゲートはエージェントが担当します。ブラウザースクリプトは証拠を収集します。エージェントは証拠を確認し、フェーズを評価し、失敗を修正してマーカーを進めます。通常のパケット失敗は修正ループです。ヘルパーが報告した失敗を調査し、同じパケットを修正し、ライフサイクルヘルパーを通して再実行して、無効になった証拠を更新します。プロセス違反または立証されていないゲートは実行失敗であり、続行や承認の根拠にはなりません。

コンテキスト圧縮、再開、再試行、再接続、新しいセッションの後は、作業に入る前にこのスキル、現在のフェーズのリファレンス、現在のアーティファクト、progress.md、open-gaps.md、次のアクションに必要なタスク所有の証拠を読み直してください。会話の記憶や古い Pass ラベルを、次のステップを決める根拠にしてはいけません。

</execution_contract>

最初のアクションのロック

<first_action_lock>

最初のタスクターンでは、ソースのみを扱います。以下のソースチェックポイントに到達する前に、状況把握、ルートの確認、ロゴの検索、ビルドの確認、アセットの選定を目的としてターゲットリポジトリを調べてはいけません。タスクメッセージに記載されたターゲットパスは入力境界であり、そのパスの読み取りを許可するものではありません。ロック解除までは、ターゲットルートに対して ls、find、tree、rg --files、git status、または同等のコマンドを実行してはいけません。ターゲットディレクトリ名の一覧表示もターゲットの調査に当たり、禁止されています。状況把握の前に読み取りが許されるスキル関連ファイルは、この SKILL.md と、以下に記載された正確なフェーズ 0／ライフサイクルのリファレンスパスのみです。スキルルート、references/、assets/ ディレクトリを一覧表示、グロブ、検索、または調査して、ファイルを見つけてはいけません。

次の順序を厳守してください。

1. このスキルを読み、現在のマーカーに必要な Phase 0 とライフサイクルの参照だけを、参照マップに記載された正確なパスで確認します。オリエンテーションが完了するまでは、.agents/skills/source-html-to-app-ui/ 配下の他のパス（references/、assets/templates/、assets/scripts/ を含む）を一覧表示、グロブ検索、検索、読み込みしないでください。後でコピーするときは、このスキルに記載された正確なアセットパスだけを使用し、スキルパッケージを列挙して見つけないでください。それまでは、テンプレートとヘルパーはコピー専用です。ヘルパーのコマンド契約はすでに正式なものとして確定しています。
2. 新しい task-workflow/ を作成し、CURRENT_PHASE.txt を phase-0-source-contract に設定します。
3. 承認済みのソース HTML とデザイン入力をバイト単位で変更せずに task-workflow/ にコピーします。セットアップのためにデザイン入力を読むことはできますが、まだコピー元またはコピー先の HTML、インライン CSS、JavaScript を開いたり読んだりしないでください。
4. デスクトップとモバイルの両方でライフサイクルヘルパーを使って最初のソースオリエンテーションを実行し、パケットに正確な配信済み HTML URL を渡します（例：--env SOURCE_URL=http://127.0.0.1:5192/approved-mock.html）。オリエンテーションパケットでは、デスクトップ画像とモバイル画像をそれぞれちょうど 1 枚生成します。ヘルパーの実行が成功した後の次の 2 回のツール呼び出しは、正確に次の順序で行ってください。デスクトップのオリエンテーション画像を読み、次にモバイルのオリエンテーション画像を読みます。それぞれについて具体的な所見を記録します。この 2 枚の画像を読み終えるまで、その間にソースまたはデザインを読んだり、パケットを書き込んだり、検索、シェルコマンド、その他のツール呼び出しを行ったりしてはいけません。どちらかの画像をまだ読んでいない場合、ソースの検査は開始されていません。ソースまたはデザインの内容を読むことは Phase 0 の自動失敗となります。応答の成功、最終応答 URL が SOURCE_URL と完全に一致すること、ディレクトリではないドキュメントの内容を必ず検証してください。タスクのメタデータにタイトルまたは識別情報の期待値があれば、それも検証します。なければタイトルを記録し、HTML 全体を読み終えた後に照合します。ヘルパーが準備完了と報告したことや、タイトルが空でないことだけでは不十分です。
5. 承認済みの HTML、インライン CSS、JavaScript を EOF まで完全に読みます。
6. ライフサイクルヘルパーを使って完全なソースインベントリを作成し、実行します。その後、画像ごとにマニフェストを確認します。マニフェスト全体を読み、参照されているフルビュー、セクション、状態、デスクトップ、モバイルのすべての画像を開き、画像ごとに具体的な所見を 1 つ記録します。開いた画像の数がマニフェストに記載された画像の数と正確に一致するまで続けます。キー画像だけの確認、ルートごとに 1 枚だけの確認、代表サンプルの確認、マニフェストだけの確認、1 ビューポートだけの確認は、いずれも Phase 0 の失敗です。
7. task-workflow/phase-0-source-contract.md を作成して読み返し、progress.md と open-gaps.md を整合させ、48/50 以上のスコアを獲得し、すべての必須項目に合格します。
8. CURRENT_PHASE.txt を phase-1-ui-implementation に設定し、Phase 0 の成果物を読み返してから、対象のアーキテクチャ、既存アセット、ルート、パッケージ、設定、ビルド出力、ランタイムファイルを検査します。

対象の検査を開始するための条件は、スクリーンショットの取得、インベントリの完成、計画の作成、またはソースを理解したという申告だけではなく、手順 7 のすべてを満たすことです。チェックポイントに不足がある場合は、ソースのみを対象に作業を続けてください。合格したかどうか不確かな場合は、合格していないものとして扱います。最初のソースオリエンテーションにも順序制約があります。手順 4 が完了し、デスクトップとモバイルの画像を開くまでは、オリエンテーションパケットを計画するためであっても、ソース HTML、インライン CSS、JavaScript を開いたり読んだりしないでください。ライフサイクルの実行に失敗した場合、手順 4 は完了していません。その失敗は Phase 0 のハードポーズとして扱います。次に許可される操作は、ヘルパーが管理する失敗内容の確認、範囲を限定した実行の修正（例：別の明示的なポートを選択）、修正したパケットの読み込み、ライフサイクルヘルパー経由での再実行だけです。ヘルパー管理下の再実行が成功し、成功したオリエンテーション画像をすべて開くまでは、ソース HTML、CSS、JavaScript、デザイン JSON を読んだり、Phase 0 の引き継ぎ資料を書いたり、ヘルパーのログや部分的なスクリーンショットをオリエンテーションの証拠として扱ったりしないでください。 このタスクメッセージでは、実在するブランドロゴが必要になる場合があります。その要件は引き続き適用されますが、「唯一の例外」という表現はアセット選択の指示であり、早期調査の例外ではありません。この要件を Phase 0 の契約に記録し、ソースチェックポイントによってターゲットの調査が許可された後でのみ、実在するロゴを調査またはコピーしてください。ロゴを探すために、public/、build/、その他のターゲットアセットのパスを早期に開いてはいけません。

最初のライフサイクルのオリエンテーションが始まる前に、ターゲットリポジトリまたは task-workflow/ で、読み取り、一覧表示、存在確認、環境の確認、利用可能性の確認を実行してはいけません。オリエンテーション前に許可される操作は、task-workflow/** への直接的なスキャフォールド／コピーの書き込み、それに続くオリエンテーションパケットの書き込み、必須のオリエンテーションパケットの読み戻し、そしてライフサイクルヘルパーの呼び出しだけです。セットアップは書き込み専用です。ディレクトリの作成またはファイルのコピーを行うシェルコマンドは、最後の書き込みで終了しなければなりません。cp <anything> task-workflow/... && ls ...、mkdir ... && cp ... && ls ...、セットアップ後の単独の ls、セットアップを知らせるだけの末尾の echo／printf、追記された cat、test、stat、git status、find、rg、その他の検証は、重大なプロセス違反です。最後の書き込みとして printf 'phase-0-source-contract' > task-workflow/CURRENT_PHASE.txt を実行し、その直後にオリエンテーションパケットを書き込むことは、有効なセットアップ書き込みです。セットアップの確認または通知に、2つ目のシェルコマンドを使ってはいけません。最後のセットアップ書き込みの後、次のツール操作はオリエンテーションパケットの書き込みでなければなりません。その書き込みの後、次のツール操作はオリエンテーションパケット全体の読み取りでなければならず、その読み取りに限り、最初のライフサイクル呼び出しを続けて実行できます。後続フェーズ用のテンプレートとライフサイクルヘルパーをコピーすることはできますが、オリエンテーションパケットの読み戻し前に、コピーしたヘルパー、テンプレート、ソースファイル、台帳、その他の task-workflow の成果物を一覧表示、再度開く、または読み取ってはいけません。フラグやパラメーターを調べるために、コピーした playwright-lifecycle.mjs を読むことは禁止されています。以下のコマンド契約が唯一の根拠です。最初に一覧表示をしたり、テンプレートを再度開いたり、台帳を調べたり、存在やメタデータの状態を確認したりしてはいけません。最初のヘルパー実行前は、クリーンアップが必要かどうかの確認やソースファイルのサイズの把握に使う場合も、test -d、test -e、test -f、stat、file、wc、du、head、tail、sed、grep、rg の厳密な形式は禁止されています。ls、find、tree、git status、which、command -v、python --version、node --version、--help、または同様のコマンドを実行してはいけません。Python、Node、Playwright、またはポートが存在するかどうかを先に確認せず、既知の範囲に収まるサーバーコマンドをヘルパーから直接実行してください。

</first_action_lock>

事前オリエンテーション時の読み取り許可リスト — 厳格な制限

最初のライフサイクル・オリエンテーションが正常に完了するまで、エージェントが読み取ってよいファイルは、この SKILL.md、マッピングされた正確なパスにある references/phase-0-source-contract.md と references/playwright-lifecycle.md、およびタスクメッセージのみです。これ以外のパスを読み取ると、実行は無効となり、Phase 0 の失敗として扱われます。これには、assets/scripts/playwright-lifecycle.mjs、assets/templates/ 内のすべてのファイル、コピーしたヘルパーやテンプレート、task-workflow/**、ソース HTML、インライン CSS、JavaScript、デザイン JSON、対象リポジトリ、パッケージファイル、ランタイムファイルが明示的に含まれます。ヘルパーとテンプレートは、内容を確認せず、バイト単位でそのままコピーできますが、フラグ、構造、内容を知るために開いてはいけません。このスキルに記載されたコマンドの規約で十分です。確認や理解のためにヘルパーを読んではいけません。この制限に違反した場合は、作業を中止し、フィクスチャをリセットして、Phase 0 をやり直してください。

最初のオリエンテーションの前に、セットアップで必要な場合は、Asset Map に記載された正確なパスのみを使って、ヘルパーとテンプレートをバイト単位でそのままコピーしてください。フラグ、構造、パラメーターを確認する目的で、.agents/skills/source-html-to-app-ui/references/、.agents/skills/source-html-to-app-ui/assets/scripts/、.agents/skills/source-html-to-app-ui/assets/templates/、またはコピーしたヘルパーやテンプレートの一覧表示、グロブ検索、検索、読み取りを行ってはいけません。ライフサイクルコマンドの規約とマッピング済みの参照先が正式な情報源です。コピーは許可されていますが、ディレクトリの列挙やアセットの確認は禁止です。

必須のテストゲート

<hard_stop_rules>

この実行では、ワークフローに従っているかが検証されます。以下の操作は無害な調査ではありません。それぞれ現在の実行を無効にし、続行する前にリセットが必要です：

実行してはいけない操作	正しい対応
最初のヘルパー実行前に、/ms-playwright、~/Library/Caches/ms-playwright、node_modules/playwright-core、browsers.json、ブラウザー実行ファイルのパス、リビジョン、プロセスやポートの状態を ls、find、cat、または同等の方法で調べること。which、command -v、--version、--help などでサーバーやランタイムの利用可否を確認すること	タスク専用のパケットを作成し、実際のライフサイクルヘルパーを呼び出します。利用可否を確認するのは、最初のパケットだけです
node -e、node --eval、ヒアドキュメント形式のブラウザープログラム、node task-workflow/**/<packet>.mjs、または chromium.launch() を直接実行するプロセス	パケットは、ヘルパーの --run ペイロードとしてのみ実行します
UI の状態を落ち着かせるために page.waitForTimeout(、waitForTimeout(、setTimeout(、setInterval(、シェルの sleep、タイマーや任意のポーリングを使うこと	可視 DOM、URL、レスポンス、ジオメトリ、またはアサーションの状態を待ちます
手動またはバックグラウンドでサーバーを起動すること、curl／wget による準備状況の確認、pkill、lsof、または広範囲なプロセスのクリーンアップ	サーバーの起動、準備状況、ログ、PID のクリーンアップはヘルパーに任せます
タスクのメッセージにあるアセット／ロゴの例外、必須のブランドロゴのパス、ターゲットルートのパス、または実装要件を、早期のターゲット調査を正当化するために使うこと	要件を記録し、文字どおりの Phase 0 チェックポイントを通過するまで、ターゲットの読み取りをすべて保留します
最初のライフサイクルオリエンテーションが完了し、デスクトップ／モバイルの画像を開く前に、承認済みのソース HTML、インライン CSS、または JavaScript を開く、数える、読むこと。ソースファイルに対する wc、stat、file、du、head、tail、sed、grep、rg の実行も含みます	ソースファイルをコピーするだけにします。ライフサイクルヘルパー経由で直ちにオリエンテーションパケットを実行し、画像を開いてからソースを末尾まで読みます
オリエンテーションパケットをディレクトリ一覧、誤ったルート、空白のドキュメント、または無関係なページに移動させること。ヘルパーの準備完了 URL だけを根拠に、承認済み HTML が開かれたと判断すること	パケットに正確な HTML URL を渡し、正確な最終 URL とディレクトリではないコンテンツをアサートします。利用可能な場合はタスクで指定された識別情報もアサートし、後でソースと照合できるようタイトルを記録します。誤ったページの画像は無効にし、ライフサイクルヘルパー経由で再取得します
Phase 0 のソースチェックポイント前に、ターゲットの app/、public/、server/、パッケージ、設定、パッケージファイル、node_modules、ビルド／dist、テスト、ランタイムログ、ターゲットアセット、またはスキルの assets/scripts/ や assets/templates/ を一覧表示、検索、読み取り、調査すること。最初のヘルパー実行前に ls、find、test -d、test -e、test -f、stat、file、wc、du、head、tail、sed、grep、rg を使って task-workflow/ のセットアップを確認すること。スキャフォールド作成コマンドの末尾に ls を付けることや、コピーしたヘルパーを先に読むことも含みます	ソースのみを扱います。タスク専用のスキャフォールドを、書き込みのみのコマンドで作成／コピーします。オリエンテーションパケットのみを書き込み、読み取ってから、ライフサイクルオリエンテーションを実行し、画像を開き、HTML／CSS／JavaScript を末尾まで読みます。ソースの完全なインベントリを実行して開き、その後 Phase 0 の成果物を更新して合格させます
指示／参照資料の設定後、Phase 0 のソースチェックポイント前にワークスペースで許可される作業は、task-workflow/** の直接作成／コピー、承認済み設計メタデータの読み取り、オリエンテーションパケットの作成、そのパケットの監査目的での読み取り、ライフサイクルヘルパーでの実行、ソースエビデンスの確認、Phase 0 アーティファクトの更新のみです。作業内容を決めるためにターゲットルートを一覧表示または読み取ったり、ターゲット環境を調査したりしないでください。タスクプロンプトにはターゲット境界がすでに示されており、ターゲットの調査は明示的な解除後にのみ開始します。必須の順序は、デスクトップ／モバイルでのソースオリエンテーション → オリエンテーション画像を開く → HTML／CSS／JavaScript を EOF まで完全に読む → ソースインベントリの完成とエビデンスを開く → Phase 0 アーティファクトのチェックポイント → ターゲット調査です。スキャフォールド／テンプレート／ソースのコピー後は、コピーしたヘルパーやその他の task-workflow アーティファクトを読まないでください。オリエンテーションパケットのみを書き込み、読み取ってから、最初のライフサイクルオリエンテーションを実行してください。以降の各パケットの前に、そのパケットを読み取り、上記の禁止事項を取り除いてください。無効だとわかっているパケットを、何が起きるか確認するために「一度だけ」実行してはいけません。ライフサイクルヘルパーを使っても、無効なペイロードが許可されるわけではありません。禁止された操作が発生した場合は、直ちに停止し、現在の task-workflow アーティファクトに失敗を記録して、フィクスチャをリセットし、Phase 0 からやり直してください。

</hard_stop_rules>

Phase 0 後の管理対象検証ロック

<managed_verification_lock>

Phase 0 に合格しても、ライフサイクルの管理責任は緩和されません。Phase 1 から完了まで、ターゲットブラウザーのチェック、スクリーンショット、レイアウト測定、スクロールテスト、ランタイム調査はすべて、ライフサイクルが管理するパケットで行う必要があります。pnpm run dev、npm run dev、vite、react-router dev を直接実行しないでください。サーバーをバックグラウンドで起動しないでください。サーバーの起動、待機、調査、停止のために、シェルの sleep、curl、wget、ポートプローブ、手動でのプロセスクリーンアップを使用しないでください。ビルドや型チェックに成功しても、ブラウザー検証にはなりません。

ターゲットブラウザーで許可されるフローは、ターゲットサーバー、準備完了 URL、ランタイムディレクトリ、パケットを明示的に指定して、ライフサイクルヘルパーを使う方法のみです。

cd <target-repository>
node task-workflow/scripts/playwright-lifecycle.mjs \
  --server "<target-start-command>" \
  --ready-url "<target-readiness-url>" \
  --runtime-dir "task-workflow/runtime/target" \
  --run "node task-workflow/target-playwright/<packet>.mjs"

このフローが失敗した場合は、タスク側で管理するパケットまたは範囲を限定したヘルパー呼び出しを修正し、ヘルパー経由で再実行してください。手動のスモークテストで代用してはいけません。ターゲットサーバーの直接起動、シェルでの待機、準備完了プローブ、ブラウザーチェックは重大なプロセス違反です。停止し、記録し、フィクスチャをリセットして、Phase 0 からやり直してください。

</managed_verification_lock>

実行契約

<operating_contract>

このファイルを、5 フェーズからなる実行プロトコルの正本として扱ってください。作業前に読み、各フェーズの境界で再読し、コンパクション、再開、再試行、再接続、新しいコーディングセッションの後にも再読してください。そのフェーズの作業を始める前に、現在のフェーズに対応する参照資料を読み込んでください。

Phase 0 書き込みロック — コマンド実行前に読むこと

task-workflow/phase-0-source-contract.md が作成され、再度開かれ、少なくとも 48/50 のスコアを獲得し、すべての重要な行が合格し、task-workflow/CURRENT_PHASE.txt が phase-1-ui-implementation に設定されるまでは、ソースのみを扱う実行です。書き込みが許可されるのは、ソースのランタイムファイル、ソースペイロード、マニフェスト、スクリーンショット、ログを含む task-workflow/** のみです。app/**、public/**、server/**、パッケージ、設定、パッケージファイル、ビルド／dist、テスト、ターゲットアセットには書き込まないでください。ターゲットパスを出力先とする curl やダウンロードコマンドは実行しないでください。ダウンロードしたソースアセットは task-workflow/ 内に保持してください。Phase 0 のゲート通過後にのみ、ターゲットパスへ移動またはコピーしてください。ブランドロゴの例外によって変わるのは Phase 1 のアセット選択のみであり、ゲート通過前の public/ への書き込みが許可されることはありません。ゲート通過前にターゲットへ書き込んだ場合は、重大な Phase 0 違反です。その書き込みを削除または元に戻し、修正を記録して、実装を始める前に Phase 0 を最初からやり直してください。

ブラウザー、サーバー、準備状態、ランタイム、または証拠に関するすべてのコマンドでは、ライフサイクルヘルパーのみがプロセスを管理します。タスクの実行前および実行中は、`node -e`、`node --eval`、ヒアドキュメント、スタンドアロンスクリプト、キャッシュや実行ファイルの検査、または利用可能性のプローブを使って、ブラウザーや Playwright の事前確認を実行してはいけません。また、`which`、`command -v`、`--version`、`--help` などでサーバーのランタイムをプローブしてはいけません。サーバーを手動で起動したり、`&` でバックグラウンド実行したり、`nohup` を使ったり、シェルの `sleep` を使ったり、`curl`／`wget` でプローブしたり、`pkill`、`lsof`、または広範なプロセス探索でクリーンアップしたりしてはいけません。既存のブラウザーとサーバーが動作するかどうかは、ヘルパーの実際のパケットで確認してください。Phase 0 のゲート通過後に、承認済みのブランドアセットをダウンロードする目的だけで使う `curl` は唯一の例外です。ただし、これは準備状態や UI の証明には決して使えません。ブラウザーや事前確認を直接実行するコマンド、またはサーバーの手動起動、プローブ、クリーンアップのコマンドは、いずれも重大なプロセス違反です。その場合はパケットを停止して違反を記録し、フェーズを採点または昇格する前に `playwright-lifecycle.mjs` 経由でパケットを再実行してください。

探索目的でブラウザーを使う例外はありません。セレクターの確認、アニメーションの診断、スクリーンショットの調査、コンソールのプローブ、レイアウトの測定、または単発の再現であっても、ブラウザーによる証拠収集に該当します。/tmp に診断ファイルを作成したり、シェルでブラウザーファイルを生成したり、ブラウザーのインラインプログラムを実行したり、task-workflow/ の外に一時的な Playwright スクリプトを作成したりしてはいけません。タスク所有のパケットが短いという理由だけで、直接実行してはいけません。診断は該当する task-workflow パケットに追加し、出力は task-workflow 配下に保管したうえで、以下のライフサイクルコマンド形式を使ってそのパケットを実行してください。chromium.launch() が許可されるのは、現在ヘルパーが実行中のパケット内に限られます。それ以外の方法で実行することは、読み取り専用の場合や計算済みスタイルを表示するだけの場合でも、重大な違反です。

最初のライフサイクルパケットは、ブラウザーが利用可能かどうかを確認する唯一の方法でもあります。Playwright が動作するかどうかを判断するために、/ms-playwright、~/Library/Caches/ms-playwright、node_modules/playwright-core、browsers.json、実行ファイルのパス、ブラウザーのリビジョン、.runtime.logs、またはプロセスやポートの状態を調べてはいけません。その目的で ls、find、cat、ps、lsof、またはパッケージやランタイムのプローブを使ってはいけません。実際のヘルパーパケットを実行し、失敗した場合は、ヘルパーが所有するランタイム出力のみを確認して、パケットまたは範囲を限定した呼び出しを修正してください。キャッシュ、実行ファイル、リビジョン、利用可能性を調べることは重大なプロセス違反です。

ヘルパーを呼び出す前に、カスタムパケット全体を1行目からEOFまで読み返してください。パケットを書き込んだり編集したりした後は、次に呼び出すツールで必ずその全体を1行目からEOFまで読み返してください。編集と読み返しの間に grep／rg の実行、別の編集、ヘルパーの呼び出し、その他のツールの使用をしてはいけません。対象箇所の抜粋は、必須の全体読み返しを終えた後であれば編集箇所の確認に使えますが、監査の代わりにはなりません。書き込み結果、差分プレビュー、grep／ripgrep の結果、または内容の記憶は、パケット全体を監査した証拠にはなりません。全体読み返しと固定待機のレビューを、パケットまたはフェーズ成果物に記録してください。page.waitForTimeout(、waitForTimeout(、setTimeout(、setInterval(、シェルの sleep、UI の安定化に使う任意のポーリング／タイマーコード、またはブラウザーの待機、ナビゲーション、スクリーンショット、コンソール、ページエラー、アサーションの失敗を抑制する catch／フォールバックを含むパケットは無効であり、実行してはいけません。ブラウザーパケットは、失敗を明確に表面化させなければなりません。必須のブラウザー処理が失敗した後も処理を続けるために、.catch(() => ...)、広範な try/catch、無視される Promise、または任意のフォールスルーを使ってはいけません。タイマーによる安定化の代わりに、locator.waitFor、waitForSelector、waitForURL、waitForResponse、またはアサーションなどを使い、表示状態、URL、DOM、レスポンス、またはジオメトリの条件を確認してください。これはモデルが所有するパケットの確認であり、採点スクリプトではありません。禁止された構文を含むパケットがヘルパーに渡された場合、それは重大なパケット違反となります。パケットを書き直して再実行するまで、そのフェーズを採点または昇格してはいけません。 エージェントは各ゲートを担当します。フェーズゲートは、証拠に基づく自己レビューです。作業を確認し、スコアを正直に算出し、弱い項目を特定して修正し、無効になった証拠を更新して、再採点します。ゲートに失敗した場合は修正ループに入り、ユーザーへの報告で済ませてはいけません。網羅性、証拠の品質、必要な成果が保たれる限り、タスクに応じてプロセスの詳細を変えてかまいません。

ブラウザースクリプトは証拠を収集するものであり、フェーズの採点や昇格は行いません。フェーズチェック、採点、完了処理、受領確認、強制読み込み、昇格のスクリプトは作成しないでください。提供されているランタイムスクリプトは playwright-lifecycle.mjs のみで、ブラウザー／サーバーのライフサイクルを管理します。検出、操作、キャプチャ、測定、比較にはカスタムの Playwright スクリプトを使用し、それらはこのヘルパーを通じて実行します。

現在の成果物、開いた証拠、読み戻し、実際の対象ファイルのみを根拠に昇格してください。要約での主張、成功したビルド、スクリーンショットのパス、以前の「合格」というラベルだけでは証明になりません。後続の作業でゲートが無効になった場合は、影響を受けた最も早いフェーズに戻り、そこから順に再合格してください。

</operating_contract>

フェーズマップ

<phase_map>

フェーズ	マーカー	担当範囲	ゲート	成果
0	phase-0-source-contract	新しい成果物、管理対象のソース検出、完全なインベントリ、ソース／デザインの引き継ぎ、再現契約	48/50	すべてのソースページ／状態／セクション／インタラクションを理解し、証拠で裏付けている
1	phase-1-ui-implementation	対象の調査、担当範囲の割り当て、レビュー済みの単位での、対象環境に即した順序立てた実装	48/50	契約で定められたすべてのルート／状態／セクション／インタラクションに実際の対象側の担当があり、対象側の UI が実装されている
2	phase-2-paired-responsive-proof	コードの整合性、チェック／ビルド、ソースと対象を組み合わせた Playwright の検証	48/50	レスポンシブ、テーマ、スクロール、サイドバー、ドロワー、および対応する証拠の検証に合格している
3	phase-3-fidelity-repair-signoff	セクション比較、不一致の修正、敵対的チェック、実入力の検証	49/50。デスクトップ／モバイルはそれぞれ 48/50	見た目と動作を一対一で照合し、承認している
4	phase-4-final-audit-completion	成果物の整合性、最新の証拠、最終差分、完了ロック	ちょうど 50/50	すべてのゲートが有効な状態を保ち、完了がロック解除されている

</phase_map>

作業は、それを担当するフェーズ内で進めてください。フェーズごとに作業内容は異なります。前のゲートを避けるために後のフェーズを使ってはいけません。ローカルで修正できる限り、フェーズ 4 まで進めてください。外部のブロッカーを理由に作業を止めてよいのは、それが実証され、現在の成果物と task-workflow/open-gaps.md に記録され、ローカルで復旧する方法がない場合に限ります。

フェーズゲートループ

各フェーズで、次のループを実行します。

1. フェーズ作業を始める前に、task-workflow/CURRENT_PHASE.txt をフェーズマーカーに設定します。
2. このファイル、対応するリファレンス、現在のフェーズ成果物、progress.md、open-gaps.md を読み直します。
3. 作業またはエビデンスの小さなパケットを記録します。範囲、担当予定者、エビデンスのパス、対象外項目、レビューアクションを含めます。
4. 必須の実入力と管理された Playwright ライフサイクルを使用して、そのパケットの作業だけを行います。
5. 変更したファイルと生成された成果物を開き直し、対象を絞った差分を確認し、採点前にパケットの画像ごとのマニフェスト確認を完了します。
6. ブラウザーでの所見、ソースの宣言、ターゲットコード、エビデンスの同一性、ギャップの担当を照合します。
7. フェーズ成果物、progress.md、open-gaps.md を更新し、読み戻して確認します。
8. すべてのルーブリック項目を具体的なエビデンスに基づいて採点し、各重要項目を個別に評価します。
9. 不合格の場合は、マーカーをそのフェーズに保ったまま、最初に修正すべき箇所を記録して修正し、無効になったエビデンスを更新して、ステップ 2 から繰り返します。
10. 合格の場合は、昇格ロックを記録し、成果物の記録一式を開き直して、計算とエビデンスを確認します。次のマーカーを設定したら、直ちに次のリファレンスを読み込みます。

成果物の記録一式は整合している必要があります。マーカー、フェーズ成果物、progress.md、open-gaps.md、エビデンス台帳、実際のファイルが、現在のフェーズと次のアクションについて同じ内容を示していなければなりません。CURRENT_PHASE.txt は再開位置を示すものであり、証明ではありません。progress.md は再開用の簡潔な台帳であり、詳細なエビデンスの代わりにはなりません。

ブラウザー作業とビジュアルレビューは、範囲を限定したパケットで行います。ソースまたはターゲットのパケットは、1 つのルート／状態ファミリーと一貫性のあるビューポート／テーマのセットを対象とし、レビュー可能な数の出力を含める必要があります。無関係なセレクターや状態の不具合が起きたときに再実行が必要になる、単一の巨大なコーパスパケットは作成しないでください。パケットが合格したら、そのマニフェスト行を保持します。修正して再実行するのは、不合格または無効になったパケットだけとし、エビデンスに変更がある場合は新しいリビジョン付きパスを使用します。

Fresh Task Workspace

最初のターゲットリポジトリへの書き込みでは、提供されたアセットからクリーンな task-workflow/ を作成します。古い task-workflow/ の状態を削除してから、次を作成します。

• CURRENT_PHASE.txt、progress.md、open-gaps.md、spec.json；
• 5 つのフェーズそれぞれに対応する成果物 1 つ；
• source-playwright/、source/、target-playwright/、verification/；
• runtime/source/、runtime/target/；
• このスキルからバイト単位でそのままコピーした scripts/playwright-lifecycle.mjs。

提供されたデザイン JSON をバイト単位でそのまま task-workflow/spec.json にコピーします。生成されるすべてのスクリーンショット、スクリプト、マニフェスト、ランタイムログ、メモ、台帳、決定事項は task-workflow/ の中に保管します。提供されたテンプレートと、そのスコアカード、クリティカルゲート、昇格ロックを維持します。同じ証拠が明示され、採点可能な状態を保てる場合に限り、正確な文言を短縮できます。

Phase 0 では、冒頭の運用契約ロックが絶対です。ターゲットの実装、設定、パッケージ、アセット、生成物、ビルド、テストの各ファイルは読み取り専用とし、読み込んではいけません。ソースのみを対象とする証拠収集シーケンスが完了するまでは、ターゲットファイル、ターゲットのビルド出力、ターゲットのランタイムログ、ターゲットのアセット、ターゲットの依存関係を開いたり、一覧表示、grep、検索、調査、確認、調査したりしてはいけません。必要な順序は次のとおりです。(1) task-workflow の足場を作成する。(2) ライフサイクルヘルパーを通じて、デスクトップとモバイルの両方で最初のソースオリエンテーションを実行する。(3) そのオリエンテーション画像を開く。(4) 承認済みの HTML、インライン CSS、JavaScript を末尾まで読む。(5) ライフサイクルヘルパーを通じて、ソースの完全なインベントリ／状態／セクションの証拠を実行し、開く。(6) ソース／デザインの引き継ぎを記録し、クリティカル項目をすべて合格として Phase 0 のソース契約を採点する。(7) 成果物を再度開き、昇格ロックを確認してから、CURRENT_PHASE.txt を phase-1-ui-implementation に設定する。ターゲットの調査を開始できるのは、その後に限られます。Phase 0 の引き継ぎでは、必要なターゲット側の役割と適応方法を明記しますが、ターゲット調査の前に具体的なターゲットファイルを推測して記載してはいけません。ターゲットファイルを早期に調査または書き込みした場合、Phase 0 は失敗です。時期尚早な書き込みのみを削除または元に戻し、失敗を記録して、ソースゲートを再実行してください。時期尚早なターゲット調査や実装を、Phase 0 合格の証拠として決して使用してはいけません。

Evidence Contract

<evidence_contract>

ソースの調査

以下のソースのみを対象とする手順を順番どおり厳守してください。タスクワークフローを作成する。ライフサイクルヘルパーを通じてソースを起動する。デスクトップとモバイルの向きの画像をそれぞれ正確に1枚ずつキャプチャして、両方を開く。その後、承認済みのHTML、インラインCSS、JavaScriptを最後まで完全に読む。その後、ヘルパーを通じてソースの完全なインベントリを実行し、画像ごとにマニフェストを確認する。その後、Phase 0のソース契約を更新して合格させる。それが終わってから初めて、ターゲットのアーキテクチャとアセットを調査してください。向きのペアは起動確認にのみ使用します。後続のマニフェスト確認では、マニフェスト全体を読み、記載順にすべての画像パスを処理し、各画像を読み取り可能な倍率で開き、その画像の識別情報に紐づけて具体的な所見を記録します。開いた画像の数がマニフェスト内の画像数と一致した場合にのみ、確認は完了です。主要な画像、ルートごとに1枚の画像、代表サンプル、コンタクトシートだけ、マニフェストのみのレビュー、または1つのビューポートを根拠に、スコアを付けたり昇格させたりしてはいけません。前半のソースのみを対象とする手順では、ターゲットファイル、ビルド出力、ランタイムログ、依存関係を調査してはいけません。ページに似たすべての画面、ルート、非表示ビュー、状態、セクション、インタラクションの種類、テーマ、ブレークポイント、スクロールを担う要素、固定／スティッキー領域、初期表示では見えないソース宣言項目をインベントリに含めてください。

ページや状態に移動するには、Playwrightのユーザー向け入力APIを使用してください。適切な方法として、locator/pageのclick、fill、selectOption、press、wheel、ドラッグ、タッチを使用します。実際のインタラクションの代わりに、evaluate(() => element.click())、dispatchEvent(...)、合成ルーティング、ハンドラーの直接呼び出し、DOMの変更を使用してはいけません。これには、el.value、el.checked、クラスを割り当ててからinput、change、クリックイベントをディスパッチすることも含まれます。ブラウザーで評価する関数は状態の観察や測定には使用できますが、証拠とする状態を作り出してはいけません。通常の操作に失敗した場合は、ページまたはインタラクション対象を診断して修正してください。DOMからイベントをディスパッチして失敗を回避してはいけません。セレクターはアクティブなルート／状態にスコープを限定し、使用前に対象のコントロールまたはセクションが一意であることをアサートしてください。必須のセクション／状態のキャプチャでは、そのロケーター、アサーション、スクリーンショット、所見のいずれかが失敗した場合、パケットを失敗としてください。不完全な証拠を残したまま、例外を捕捉したり、ログに記録したりして処理を続けてはいけません。インベントリに応じて証拠の量を決めてください。ページ、状態、セクション、スクリーンショットの数に固定上限はありません。インベントリに含めたすべてのページと意味のある状態について、該当する場合はデスクトップとモバイルの全体表示の証拠に加えて、読みやすいセクション／状態／テーマの証拠をキャプチャしてください。

ペアでの証明

ライフサイクルが管理する実行を通じて、ソースとターゲットを別々にキャプチャしてください。ルート、状態、テーマ、ビューポート、セクション、フレーミングに基づいて画像をペアにします。すべての画像に、一意で安定したID／パス、実際の寸法、キャプチャ時刻、ライフサイクル実行、画像を開いた時刻、具体的な所見を付与してください。再キャプチャする場合は、新しいリビジョン付きパスを使用します。

いずれかのフェーズのスコアを付ける前に、画像ごとの視覚的な確認を完了してください。マニフェスト全体を読み、その後、マニフェスト内のすべての画像を個別に開くか、関連する画像を一度に最大4枚まで、少数ずつ読みやすい状態で開いてください。これは各レビュー対象グループのコンテキスト保護のルールであり、ページ、状態、セクション、ビューポート、スクリーンショットの総数に対する上限ではありません。各グループの確認後、開いた結果と画像ごとに具体的な所見を直ちに該当フェーズの成果物に追記し、progress.mdとopen-gaps.mdを更新してから、次のグループを開く前にそれらの更新内容を読み返してください。開いた画像の数がマニフェスト内の画像数と正確に一致するまで続けてください。「主要な画像」、ルートごとに1枚の画像、代表サンプル、構成画像を確認せずにコンタクトシートだけを見ること、マニフェストのみのレビュー、または1つのビューポートだけを開くことは、証拠の自動失敗になります。スクリーンショットのパスやマニフェストの行は、該当する画像そのものが開かれ、その所見が記録されて初めて証拠となります。コンテンツと順序、ジオメトリ、余白、タイポグラフィ、色、背景、境界線、角丸、影、アセット、コントロール、クリッピング、重なり、レスポンシブな変化、インタラクション状態、スクロール動作を比較してください。

レスポンシブ対応とテーマの安全性

デスクトップ、必要に応じてタブレット、モバイル、省略されたサイズへの外挿、短い高さでのオーバーフロー、ソースのテーマ、ターゲットで必須のテーマ、および重要な操作状態を確認します。受け入れ済みのソース／デザインシステムに基づき、不足しているターゲットテーマは慎重に導出します。重なり、クリッピング、途中での切断、キャンバスの意図しない横スクロール、使用不能なコントロール、意図しないドキュメントスクロール、空白領域など、客観的な不具合を修正します。

ソースの初期表示アニメーションが読み取り可能なキャプチャの妨げになる場合は、実際のコントロールで該当の状態にし、ソース固有の DOM、ジオメトリ、透明度、またはトランジションの条件が安定するまで待ちます。スクリーンショットを読み取りやすくするためだけに、スタイルの注入、透明度やクラスの設定、アニメーションの無効化など、ソースの DOM／CSS を変更する操作は行いません。ソースに安定した完了状態がない場合は、パケット内でソースを書き換えるのではなく、その動作と証拠を記録します。

</evidence_contract>

サイドバー、コンテンツスクロール、ドロワーの要件

<sidebar_contract>

サイドバーがある場合、そのスクロール構造は見た目の細部ではなく、ターゲットの要件として扱います。実際のスクロール入力を使い、強制的にオーバーフローさせた高さの短いデスクトップ画面で、スクロール前後のスクリーンショットを撮影して検証します。

次の2つの要件を分けて記録します。

要件	記録する内容
ソースの観察結果	ソースのドキュメント／コンテンツのスクロール値、サイドバーの境界、スティッキー／固定の動作、および表示結果
ターゲットの要件	ビューポート内に収まるシェル、名前付きサイドバー、名前付きコンテンツスクローラー、ドキュメントのスクロールに変化がないこと、コンテンツのスクロールが増加すること、サイドバーがビューポートに固定されていること

ターゲットの検証では、ターゲットのマニフェストから生の値をそのまま使用し、次の値を算出する必要があります。

• ドキュメントのスクロール差分 = 0；
• コンテンツペインのスクロール差分 > 0；
• サイドバーの上端と下端の差分がいずれも 1px 以内；
• サイドバーの高さと下端がビューポート全体を 1px 以内で覆うこと；
• スクロール後の画像にサイドバー下部の空白領域がないこと。

ソースの値は参照の説明に用いるものであり、ターゲットの判定条件を満たしたり緩和したりするものではありません。ドキュメントスクロール、スティッキー配置のみ、固定高の帯、または名前の付いていないオーバーフロー要素に依存するターゲットは、シェルを修正するため Phase 1 に戻します。

モバイルドロワーがある場合は、実際の入力による開閉、オーバーレイによる操作の遮断、ビューポート全体を覆うジオメトリ、body／ドキュメントのスクロールロック、およびスクロール位置の復元を、スクリーンショットと測定値で検証します。

</sidebar_contract>

管理対象の Playwright ライフサイクル

ライフサイクル専用の実行ルール

ブラウザーまたはランタイムの UI チェックは、すべてライフサイクル管理下で実行します。カスタムの Playwright ファイルはヘルパーに渡すペイロードであり、単独で実行するコマンドではありません。node task-workflow/source-playwright/<script>.mjs、node task-workflow/target-playwright/<script>.mjs、Playwright を使う node -e／node --eval、インラインのヒアドキュメントによるブラウザープログラム、その他同等のブラウザー直接実行コマンドは実行しないでください。ブラウザーの動作をデバッグする場合は、タスク管理下の .mjs パケットを編集し、そのパケットをヘルパー経由で再実行してください。診断用ファイルを /tmp やその他の一時的な場所に書き込んではなりません。また、ブラウザースクリプトを作成するためにシェルのヒアドキュメントやリダイレクトを使わないでください。スモークテスト、レディネステスト、ブラウザー実行のためにバックグラウンドサーバーを起動してはなりません。手動で起動したサーバーに Playwright を接続したり、シェルの sleep、curl、その他の手動リクエストをヘルパーの ready URL の代わりに使ったりしないでください。ビルド後は、制限付きサーバーコマンド、ready URL、ランタイムディレクトリ、カスタム Playwright ペイロードを指定してライフサイクルヘルパーを実行し、稼働中のターゲットを検証してください。playwright install、playwright install --dry-run、その他同等のブラウザーインストールコマンドやブラウザー利用可否の確認コマンドは実行しないでください。既存のブラウザーキャッシュをライフサイクルヘルパー経由で使用してください。

ソース用とターゲット用のすべてのパケットで、管理対象のサーバー、レディネスチェック、ペイロードのみを変更し、次の形式を使用してください。

node task-workflow/scripts/playwright-lifecycle.mjs \
  --server "<bounded server command>" \
  --ready-url "http://127.0.0.1:<port>/<ready-path>" \
  --run "node task-workflow/<source-or-target-playwright>/<packet>.mjs"

ヘルパーが起動、レディネス、ブラウザー環境、ランタイムログ、PID 単位のクリーンアップを管理する必要があります。ブラウザーまたはサーバーに問題が発生した場合は、ヘルパーが管理するログを確認し、呼び出しまたはパケットを修正してください。ペイロードが動作するかを確認するために、ヘルパーを迂回してはなりません。単発のデバッグコマンドを含め、Playwright を直接実行するコマンドは、有用な出力が得られた場合でも、プロセス上の重大な違反となります。ライフサイクルの失敗は、ヘルパー管理下で再実行して有用な証拠が得られるまで、ゲートの失敗として扱います。

ソースをヘルパー経由で起動し、証拠を取得して停止します。次にターゲットをヘルパー経由で起動し、証拠を取得して停止してから、保存した証拠を比較してください。ポート、スクリプト、スクリーンショット、ランタイムログはそれぞれ分けてください。

固定時間のスリープではなく、決定論的なレディネス条件と状態条件を使用してください。page.waitForTimeout、シェルの sleep、任意のポーリング間隔、タイマーのみによる待機は、パケットの重大な失敗となります。これらを削除し、ゲートの失敗を記録してから、スコアリング前にヘルパー経由で再実行してください。レディネスと対象を絞ったスクリプトのタイムアウトは、15,000～20,000 ms で開始してください。有用な診断がないままタイマーだけで実行が終了した場合は、クリーンなトリアージを記録してから、60,000 ms で一度だけ再試行してください。対象を絞ったスクリプトは、作業を分割して 120,000 ms 以内に収めてください。有用な失敗は修正チケットとして扱います。再実行する前に、ログ、DOM／状態、コンソール、ネットワーク、サーバー出力を確認してください。

ライフサイクルの管理と PID 単位のクリーンアップは、ヘルパーに任せてください。タスク専用のポート、制限付きスクリプト、対象を絞った再実行を優先してください。ヘルパーはバイト単位で変更せず、そのまま保持してください。プロセスの捜索、バックグラウンドサーバーのループ、無差別なポートスキャン、ブラウザーのダウンロード、手動でのライフサイクル管理は、通常のワークフローでは行わないでください。

適応ルール

• ソースの証拠がある場合は、一対一で対応させてください。
• ソースのコンテンツ、階層、間隔、タイポグラフィ、色、コントロール、状態、ルート、インタラクション、テーマ、アセットを保持してください。
• ソースで見える結果を保ちながら、ターゲットで安全なビューポートシェル／コンテンツスクローラーのアーキテクチャを適用してください。
• ソースの証拠、デザイン JSON、ターゲットのトークンに基づき、省略されたブレークポイントを保守的に推定してください。
• 利用可能な場合は、リポジトリに実在するロゴを使用してください。
• 遷移先を創作せず、サポートされていないナビゲーションを無効にしてください。
• 実装は UI のみに限定し、ソースに裏付けられたものにしてください。

再開と参照情報の読み込み

コンテキストの圧縮後、再開時、再試行時、再接続時、または新しいセッションの開始時は、次の順に読み込んでください。

1. この SKILL.md；
2. task-workflow/progress.md；
3. task-workflow/CURRENT_PHASE.txt；
4. task-workflow/open-gaps.md；
5. 現在のフェーズ、または最初に失敗したフェーズの成果物；
6. そのマーカーに対応する参照資料；
7. そのフェーズで必要なタスク入力、ソース HTML、デザイン JSON、アクティブなターゲットファイル。

参照資料の対応表：

マーカー	読み込む資料
ワークフローの欠落またはフェーズ 0	references/phase-0-source-contract.md、references/playwright-lifecycle.md
フェーズ 1	references/phase-1-ui-implementation.md
フェーズ 2 または 3	references/phase-2-3-playwright-fidelity.md、references/playwright-lifecycle.md
フェーズ 4	references/phase-4-final-audit-completion.md

完了ロック

完了前に、次の事項を確認してください。

1. CURRENT_PHASE.txt が phase-4-final-audit-completion になっていること；
2. すべてのフェーズ成果物が、必要なしきい値で Decision: Pass としていること；
3. すべての重要な行、パケットレビュー、昇格ロック、ギャップ行に、具体的かつ最新の証拠があること；
4. 引用されたすべての画像が存在し、開いて確認済みで、対応するソースとターゲットの比較があること；
5. デスクトップ、モバイル、セクション、サイドバー、ドロワーの最終証拠が、最終ターゲットコードを反映していること；
6. 最終 diff が UI のみであり、必要なチェックとビルドの証拠がすべて最新であること；
7. タスクの指示にある完了コマンドが正確にコピーされ、未実行であり、残る唯一の作業であること。

例に従い、指定されたコマンドをそのまま使用してください。

node /workspace/builder/task_complete.mjs --projectId "<projectId>" --taskId "<taskId>" --status completed --summary "<brief summary>"

フェーズ 4 の成果物と progress.md を読み返した後、そのコマンドをツールで実行する最後の操作として実行してください。その後は別のツールを実行せず、結果を受けて直接応答してください。

アセット対応表

ランタイム成果物	ソースアセット
phase-0-source-contract.md	assets/templates/phase-0-source-contract.md
phase-1-ui-implementation.md	assets/templates/phase-1-ui-implementation.md
phase-2-paired-responsive-proof.md	assets/templates/phase-2-paired-responsive-proof.md
phase-3-fidelity-repair-signoff.md	assets/templates/phase-3-fidelity-repair-signoff.md
phase-4-final-audit-completion.md	assets/templates/phase-4-final-audit-completion.md
progress.md	assets/templates/progress.md
open-gaps.md	assets/templates/open-gaps.md
scripts/playwright-lifecycle.mjs	assets/scripts/playwright-lifecycle.mjs