noxaur/verify-finite

Verify Finite（Finiteを検証する）

Finiteには2つのインターフェースがあり、ほとんどの機能は両方を必要とします。エージェントは/mcpにあるMCPツール（6つのdoc6ツール。callで/mcp/classicの従来ツールも操作可能）を通じてデザインを編集します。人間はブラウザで確認します。デザイン一覧は/、キャンバスは/design/?id=<designId>です。証明では、エージェント側をcallで操作し、人間側のページでその結果を確認するか、コメントの場合はその逆を行います。

ハーネスはe2e/headless.mjsです。.agents/skills/finite-headless/SKILL.mdがそのコマンドリファレンスです（シャドウルート、サンドボックス化されたiframe、--agent、Pythonに到達するセレクタ）。最初の実行前に必ず一読してください。このスキルは、分離、ドクター、証拠フォルダ、ビフォー・アフター実行、機能マップを追加します。

以下のすべてのコマンドは、チェックアウトルートから実行します。

V=.agents/skills/verify-finite/scripts/verify.sh

シェル変数はツール呼び出し間で保持されません。各呼び出しの先頭でV=...とRUN=...を繰り返してください。

手順

1. 機能を選択する。 変更が影響する機能をfeatures/README.mdの「変更が影響する機能」テーブルから見つけます。
2. 起動する。 修正後のコードの実行環境を起動します。バグ修正の場合は、修正前のコードの実行環境も起動します（「ビフォー・アフター」参照）。
3. 診断する。 各実行環境がok行のみを出力するまで診断します。
4. 操作する。 選択した各機能ファイルのすべてのエントリポイントを実行し、証拠を保存します。
5. クリーンアップする。 起動したすべての実行環境（失敗したものを含む）をクリーンアップします。
6. 報告する。 「報告」の形式に従って報告します。

選択したすべての機能のすべてのエントリポイントが証明されるか、理由とともにスキップされるか、証拠とともに失敗し、$V listが実行中のものを表示しなくなった時点で完了です。

起動

$V launch                          # サーバー、finite.wasm、Webアプリをビルドして起動します
$V launch --no-build               # 最後のビルドを再利用します。コードが前回のビルド以降に変更されている場合は拒否されます。
$V launch --width 390 --height 844 # 電話サイズのページ（デフォルトは1440×900）
$V launch --at main                # 別のコミットの実行環境。一時的なチェックアウト内で起動します（「ビフォー・アフター」参照）

RUN=<run>と出力されます。このIDを保持してください。他のすべてのコマンドがこれを必要とします。コールドビルドには約2分、何もビルドする必要がない場合は数秒かかります。Bashのタイムアウトは600000に設定してください。--no-buildは、ビルドする必要がない場合の数秒のみを節約するため、不明な場合は省略してください。

Finite at http://127.0.0.1:<port>と出力されると、起動の準備ができたことになります。ハーネスは、その行を出力する前に/api/healthを待ち、デザイン一覧を読み込みます。データフォルダは空で始まり、シードデータ、マイグレーション、ログインはありません。人間は「Guest」としてコメントを投稿し、エージェントは--agent <name>を指定しない限り「Agent」として投稿します。

各実行環境は個別のセッション（verify-<run>）であり、独自の空きポート、一時データフォルダ、Chromeプロファイルを持つため、並行して実行できます。自分が起動していないFiniteを操作しないでください。vp run devはcrates/server/dataからユーザーの実際のデザインを提供し、デスクトップアプリもユーザー自身のデータを提供します。ドクターは、他の誰かのサーバーにアタッチしたセッションを失敗とみなします。

実行環境は、30分間アイドル状態が続くと自動的に停止します。その後はdoctorが失敗するため、クリーンアップして再度起動してください。

診断

$V doctor $RUN

状態を読み取るのみで、すべての行がokまたはFAILと表示されます。以下の5つの項目をチェックします。

• セッションが生存しており、プライベートなfinite-headless-data-*フォルダを所有していること。
• /api/healthがokとpackage.jsonのバージョンで応答すること。
• 実行中のビルドがコードと一致していること。ビルド入力（crates/、apps/web/、ハーネス、ロックファイル、追跡されていないファイルを含む）のハッシュと、実行環境がビルドされたコードのハッシュを比較します。ドキュメント、スキル、テストの編集はカウントされません。
• get_screenshotのためにChrome、Chromium、またはEdgeが利用可能であること。
• ページが応答すること。

その後、最後の呼び出し以降のページのコンソールを出力します。最初、何か問題が発生した後、そして最終的な証拠をキャプチャする前に実行してください。FAILの場合は、操作を続行せず、クリーンアップして再度起動してください。コードを変更した後は、ビルドチェックが設計上失敗するため、クリーンアップして再度起動してください。

操作

$V h $RUN <command> ... は、任意のe2e/headless.mjsコマンドをこの実行環境に対して実行します。最もよく使用するコマンドは以下の通りです。

$V h $RUN call create_design '{"name":"Verify"}'      # エージェント側: designId "<id>" を出力
$V h $RUN call create_artboard @input.json            # JSONインライン、@file、または - で標準入力
$V h $RUN design <designId>                           # 人間側: キャンバスを開き、アートボードを待つ
$V h $RUN snapshot --selector main                    # アクセシビリティツリー、人間が見ているもの
$V h $RUN click 'button[title="Comment (C)"]'
$V h $RUN click '[data-artboard] >>> h1' --shift      # Shift+クリック
$V h $RUN upload 'input[type=file]' card.html         # OSのファイルピッカーのようにファイルを選択
$V h $RUN api GET /api/designs/<designId>             # 保存されたデザイン。コメントも含む

これらの安定したハンドルを使用してください。これらはアプリのアクセシブルな名前とタイトルです。

場所	ハンドル
デザイン一覧	見出し Designs、ボタン New design、検索ボックス Search designs by name、各デザインカードのリンク link 1つ
キャンバス上部バー	リンク ← Designs、button[title="CSS variables every artboard uses, in each mode"]（トークン）、button[title="Every comment, open and resolved"]（コメント、名前に開いている数を含む）、Import、Export、各エージェントごとのチップ
キャンバスツール	ツールバー Tools: button[title="Pointer (V)"]、button[title="Comment (C)"]; キー v、c、Shift+1（フィット）、=/-（ズーム）
コメントボックス	テキストボックス Add a comment、button[title="Change your name"]、[data-selection-count]、ボタン Send、Comment: <first message> という名前のピン
コメントスレッド	[role=dialog] で名前は Comment thread: ボタン Delete、Resolve/Reopen、Close、自分の最新メッセージの Edit、テキストボックス Reply
パネル	aside[aria-label=Comments] タブ Open N / Resolved N 付き; section[aria-label=Tokens] フォーム form[aria-label="Add a token"] 付き; nav[aria-label=Pages]; [role=menu][aria-label=Export]; aside[aria-label=Import] ステータス status 付き
アートボードコンテンツ	[data-artboard="<artboardId>"] >>> <css>; エージェントの data-name 属性はDOMに残ります

座標よりもこれらを優先してください。座標は、セレクタが到達できないサンドボックス化された（スクリプト）アートボードにのみ使用します。clickはCSSセレクタを受け取り、テキストは受け取りません。そのため、タイトルのないボタンは位置で選択します: [role=dialog] button --nth 1、queryで順序を確認します。

テキスト入力には2つの注意点があります。typeはフィールドの内容に追加され、key Meta+aはCDPを介してテキストを選択しません。フィールドのテキストを置き換えるには、フィールドにフォーカスを当てた状態で$V h $RUN eval "document.execCommand('selectAll')"を実行し、その後typeを使用します。

バックグラウンド呼び出し

wait_for_commentsは、人間がコメントするまでブロックするため、ページを操作しながら実行する必要があります。

$V bg $RUN 02-wait call wait_for_comments '{"designId":"<D>","timeoutSeconds":30}'
# ...ページを操作...
$V await $RUN 02-wait 30      # 呼び出しが戻るまでブロックし、その後 .verify/<run>/02-wait.txt を出力

結果はawaitで読み取り、ファイルを直接読み取らないでください。ファイルは呼び出しが戻った後にのみ存在します。バックグラウンド呼び出しはツール呼び出し間で維持されます。

証拠

すべてはチェックアウト内の.verify/<run>/に保存されます。.gitignoreが対象としており、クリーンアップもこれを保持します。

$V save $RUN 01-comment-posted snapshot --selector main     # コマンド、その出力、終了コード
$V shot $RUN 02-canvas                                      # .verify/<run>/02-canvas.png
$V shot $RUN 03-panel --selector 'aside[aria-label=Comments]'

saveは任意のヘッドレスコマンド（callを含む）を受け取り、コマンド、その出力、[exit N]を含む<name>.txtを書き込みます。名前には番号を付け、実行順に読めるようにしてください。各PNGは、それに依存する前にReadツールで読み取ってください。get_screenshot画像とパスを指定せずに撮影されたページスクリーンショットは、セッションの一時フォルダに保存されます。クリーンアップにより、これらは.verify/<run>/tool-images/に、サーバーログは.verify/<run>/server.logにコピーされます。テスト入力として作成したファイル（インポートするファイルなど）も.verify/<run>/に配置します。

証明は以下の基準を満たしている必要があります。

• 実際のパス。 人間の操作はページ（クリック、キー、タイプ、アップロード）を通じて行われ、エージェントの操作はMCPのcallを通じて行われます。REST APIは保存された状態を読み取るためにのみ使用します。APIを通じて書き込むと、証明しようとしているUIがスキップされます。
• 操作と結果。 操作を実行するステップとその後の状態の両方を保存します。最終的なスクリーンショットだけではありません。
• 副作用。 変更が保存された状態と表示された状態の両方を示します。api GET /api/designs/<id>はmeta、nodes、commentsをサーバーが保存したまま返し、エージェントの読み取りツール（get_comments、get_tokens、get_tree_summary）は次のエージェントが見るものを表示します。
• ライブ機能の双方向性。 エージェントの編集は、リロードなしでページに反映される必要があります。人間のコメントは待機中のエージェントに到達する必要があります。
• モックなし。 実行環境は実際のサーバー、実際のブラウザ、実際のMCPセッションを使用します。
• クリーンなコンソール。 $V save $RUN <n>-console consoleで終了します。そこに例外や失敗したリクエストがあると、証明が無効になります。

ビフォー・アフター

バグ修正が証明されたと言えるのは、同じ操作手順が古いコードでは失敗し、新しいコードでは成功した場合です。両方を並行して実行します。

$V launch --at main     # RUN=<before>: mainの一時チェックアウト。インストールとビルド（約1分）
$V launch               # RUN=<after>: このチェックアウト

両方で同じ手順を、同じ証拠名で操作します。before実行はバグを示す必要があります。そうでない場合、操作手順はバグに到達しておらず、after実行は修正について何も証明しません。--atは任意のgit ref（ブランチ、タグ、コミット、または修正がまだコミットされていない場合はHEAD）を受け取ります。ドクターは、実行環境がビルドされたrefとコミットを表示します。クリーンアップは一時チェックアウトを削除し、その証拠は保持します。

クリーンアップ

$V cleanup $RUN

この実行環境のデーモンを停止します。デーモンは、自身が起動したサーバー（SIGTERM。これによりデザインが最初に保存されます）と起動したChromeを停止し、それらの一時データとプロファイルを削除します。その後、クリーンアップはサーバーログとツール画像を証拠フォルダにコピーし、--at実行の一時チェックアウトを削除し、保持したものをリストします。他のセッション、vp run dev、デスクトップアプリには影響しません。

$V listは、このチェックアウト内で、まだ実行中またはチェックアウトを残している実行環境を表示します。各実行環境は$V cleanup <run>でクリーンアップし、pkillは使用しないでください。$V prune [days]は、クリーンアップ済みの実行環境の証拠のうち、指定された日数（デフォルト7日）より古いものを削除します。報告しようとしている実行環境の証拠は決してpruneしないでください。

報告

操作した各機能につき、1つのブロックで終了します。

<機能ID> via <エントリポイント>: proven | skipped | failed
  evidence: .verify/<run>/<files>
  why (skipped or failed): <実行したコマンドと、欠落していたものや問題だったもの>

次に、実行ID、各実行のドクターの出力、そして修正の場合はバグを示すbefore実行の証拠を示します。別のエントリポイントが同じ動作を証明した場合でも、スキップされたエントリポイントは「skipped」として報告します。

ヘルパー

scripts/verify.shは、launch、doctor、h、save、shot、bg、await、cleanup、list、pruneの各コマンドを受け取ります。引数なしで実行すると、その引数が表示されます。これはe2e/headless.mjsの薄いラッパーです。セッションはverify-<run>で、証拠は.verify/<run>/に保存されます。