verify-unattended

Reticle、無人での実行

同じ製品、同じ判定。違いは一つだけです。ここでは、人の操作を待つことがありません。

通常のスキルでは、制御を人に返す箇所が2つあります。「クライアントを再起動して、MCP サーバーを認識させる」と「ブラウザーでアプリを開く」です。誰かがその場にいるときは、どちらも正しい手順です。ゴールモードでは、どちらも行き止まりです。再起動すると、この手順を保持しているコンテキストが終了し、タブを開く人はいません。

そこで、このスキルではどちらも不要な方法を選び、判定が得られるか、理由が見つかるまで処理を続けます。

これを機能させる唯一のルール

実行中の自分のプロセスに MCP ツールを追加することはできません。 スラッシュコマンドも、設定の編集も、再登録も、すでに利用可能なツールのリストには反映されません。クライアントは Reticle が存在する前にそのリストを読み込んでいます。試みないでください。また、再起動を依頼しないでください。

代わりに、すでに利用できるものに応じて、一度だけ分岐します。

• reticle_* ツールがある → それらを使って操作します。最も確かな証拠を、ソースに対応付けて完全な判定とともに得られます。
• ない → CLI を使います。reticle verify は、MCP を一切使わずに判定と終了コードを出力します。

どちらの方法でも、最終的に判定が得られます。現在のプロセスで可能な方法を選び、進めてください。

ステップ 1：一度だけ接続する

ユーザーの目標で Reticle が求められている場合、または検証済みの結果が必要な場合に限り、これを実行します。init は package.json、ロックファイル、ビルド設定を変更します。それ以外の場合はスキップしてステップ 3 に進み、ファイルを変更しないリースを使います。

export RETICLE_INSTALL_SOURCE=npx_skill
npx -y @reticlehq/server@latest init

export を独立した行に置いているのには理由があります。このコマンドのほかの箇所では、マーカーをコマンドと同じ行に記述しています。しかし、このスキルはコマンドをプレフィックス許可リストと照合する環境で実行されるため（下記の「コマンドをそのまま記述する」を参照）、RETICLE_INSTALL_SOURCE=... npx ... は npx で始まらなくなります。同じ行に記述すると、このファイルが頼るよう指示しているルールに一致しなくなります。

次に、想定で済ませず、レポートを確認します。重要なのは次の2点です。

• アプリのビルド設定に ⚠ が表示されている場合：接続に失敗しています。表示された編集を自分で適用してください。適用したものとして先に進まないでください。
• バージョンのフォールバックを示す ℹ が表示されている場合：指定された SDK が拒否され、別の SDK がインストールされています。SDK とデーモンのバージョンは一致している必要があります。後の呼び出しでプロトコルエラーが報告された場合は、これが原因です。

init は冪等です。ステップに already wired と表示される場合、それは合格であり、スキップではありません。

init のすべてのステップで、すでに完了していると報告された場合、アプリには作業を始める前から計測が導入されていました。 それ自体は問題ありませんが、この実行でインストールを証明できていないことを意味します。自分が設定したと主張せず、そのように伝えてください。

ステップ 2：アプリが実際に実行中であることを確認する

デーモンが確認するにはページが必要で、ページにはサーバーが必要です。起動するかどうかを尋ねないでください。

1. package.json から開発用スクリプトを読み取ります。
2. スクリプトから推測されるポートで、バックグラウンド起動します。
3. ポートから応答があるまでポーリングします。初回アクセス時にルートのコンパイルが必要な開発サーバーでは、30秒かかることがあります。この時点でのタイムアウトは、まだ失敗ではありません。

そのポートですでにサーバーがリッスン中の場合は、それを使ってください。別のポートで2つ目のサーバーを起動すると、誰も検証していないアプリが起動し、プロセスも残ります。

init の後は再起動が重要です。 すでに読み込み済みの設定に追加されたビルドプラグインは、実行中のサーバーのバンドルには含まれません。ステップ 1 の前からサーバーが起動していた場合は、ここで再起動してください。そうしなければ、この後の作業で計測済みのページが見つかりません。

ステップ 3：ページを接続する

MCP ツールを使う場合：

reticle_session { action: "list" }

セッションが一覧に表示されることが証明になります。セッションが表示されるまでは、このスキルのほかの処理ではアプリについて何も確認できません。

セッションがなく、タブを開く人もいませんか？ 自分で開きます。

reticle_run { tool: "reticle_lease", args: { action: "acquire", url: "http://localhost:<port>/" } }

リースは Reticle が所有して操作するブラウザーを開きます。「ページを開く人がいない」という問題への答えは、これです。

MCP ツールがない場合はステップ 4 に進みます。verify が独自のブラウザーを開きます。

ステップ 4：判定

実行する前に、結果を宣言してください。 これがチェックと正当化の違いであり、このツールが存在する理由のすべてです。

reticle_act_and_wait { ref, action, until: { … } }

アプリが 表示した ことではなく、アプリが 実行した ことを検証してください。サーバーから返された値ではなく、送信したばかりの値を描画する UI は、これまでに書かれたあらゆる DOM レベルのチェックに合格してしまいます。

until: { kind: "net", method: "POST", urlContains: "/api/refund",
         status: 200, bodyContains: "\"refunded\":1187.01" }

bodyContains が読み取るのはレスポンス、つまりサーバーの応答です。これにはボディのキャプチャが必要で、init がアプリの設定に書き込みます。判定結果が outcome_unread なら、それが不足しているものです。

MCP ツールがない場合：

npx @reticlehq/server verify http://localhost:<port>/

終了コード 0 は合格です。アプリを操作し、保存済みのフローを再検証します。そのため、プロジェクトにフローがない場合は、何もチェックされなかったと通知します。これは合格ではありません。先にフローを記録するか、検証対象がなかったことを明確に伝えてください。保存済みのフローがない場合は、代わりにひとつの終了状態を証明してください：npx @reticlehq/server verify http://localhost:<port>/ --expect '{"kind":"element","query":{"testid":"order-confirmed"}}'。これは稼働中のデーモンに問い合わせるもので、デーモンを起動することはありません。また、verified: "yes" の場合に限り終了コード 0 を返します。

ステップ 5：判定結果を正直に読む

• verified: "yes"：証明できました。何が成立したのかを伝えてください。
• verified: "no"：アプリか、期待した結果のどちらかが誤っています。どちらも結果です。報告してください。
• verified: "unknown"：Reticle はアプリを操作しましたが、判断できませんでした。合格ではありません。 決して合格として扱わず、成功するまでアサーションを弱めないでください。それは実際のシグナルを誤ったものに変えてしまいます。それこそ、この製品が防ごうとしている失敗です。

act_and_wait も assert も実行せずに終わった操作には、ツールをいくつ使ったかにかかわらず、結果はありません。

本当に行き詰まったとき

次のどれに当てはまるかを伝えてください。正確な行き止まりは、見せかけの成功報告に勝ります。

確認できること	意味
ツールがない、verify が保存済みフローはないと表示する	まだ検証対象がありません。フローを記録するか、その旨を報告してください
reticle_session { action: "list" } が空で、ポートはリッスン中	バンドルに SDK がありません。init の後で開発サーバーを再起動してください
verified: "unknown"、outcome_unread	レスポンスボディが記録されていません。init が書き込んだプラグインオプションを確認してください
リースがページを読み込むものの、接続されない	アプリが接続を拒否しました。localhost 以外のホストでは、allowNonLocalhost に加えてペアリングトークンが必要です

承認が必要なクライアント向けの注意事項

一部のクライアントでは、コマンドごとに人間の承認が必要です。承認の回数をほぼゼロにする方法が 2 つあります。

• コマンドはそのままにしてください。 npx @reticlehq/server init はプレフィックスルールに一致しますが、同じコマンドをサブシェルや $(…) で囲むと、通常は一致しません。
• ホームディレクトリについてのプロンプトが 1 回表示されることを想定してください。 デーモンはワークスペースの外にある ~/.reticle に状態を保持します。このディレクトリ群を一度承認すれば、その後のすべての呼び出しが対象になります。

クライアントに自律モードや目標モードがある場合、このスキルはそのモードを想定しています。40 回もプロンプトを承認するのではなく、開始前に有効にしてください。承認疲れは、ツールが接続されても何も検証されないまま、インストールが中途半端な状態で実行が放棄される現実的な原因です。

フィードバックの報告

Reticle はエージェント向けに作られているため、修正すべき内容を決めるシグナルは皆さんの体験です。そして、その体験はコンテキストが失われると消えてしまいます。1 回呼び出して、そのまま続行してください。

reticle_session { action: "feedback", kind: "bug" | "gap" | "ambiguity" | "feature_request" | "improvement" | "experience", text: "…" }

接続できない場合：npx @reticlehq/server feedback --agent --kind <kind> "what happened"。不具合はReticleに報告してください。テスト対象のアプリで見つけたバグは、Reticle が正常に機能している証拠であり、回答に記載する内容です。