grahama1970/agentic-evals

agentic-evals は何をしますか？

このスキルは、通常の単発的なスモークテストでは不十分で、スキルやエージェントのワークフローを繰り返し可能で証拠に基づいた評価が必要なタスクに使用します。

現在の適用範囲

この初期バンドルは、コマンドベースのケースに対する決定論的なフィクスチャランナーを提供します。各ケースを複数回実行し、stdout/stderr/終了ステータスと実行時間を記録し、明示的な期待値をチェックし、機械可読な準備完了サマリーを出力します。

これは宣言されたフィクスチャの動作のみを証明します。意味的な正しさ、実際のサービス統合、LLM判定品質、またはリリース準備状態を証明するものではありません（ただし、フィクスチャコマンド自体がそれらの実パスを実行する場合は除きます）。

使用方法

./run.sh run fixtures/agentic_eval.json
./run.sh run fixtures/agentic_eval.json --output /tmp/agentic-evals-report.json
./run.sh audit-skills ../ --output /tmp/agentic-evals-baseline-gap-report.json
./run.sh scaffold-fixture ../some-skill --output ../some-skill/fixtures/agentic_eval.json
./run.sh apply-scaffolds ../ --write --output /tmp/agentic-evals-apply-scaffolds.json
# ライブディスカバリに基づく要件→ジャーニープランニング（課題 #1629）
./run.sh plan-journeys --fixture fixtures/agentic_eval.json \
  --requirements requirements.json \
  --interaction-inventory discovery/discovery-inventory.json \
  --state-graph discovery/state-graph.json \
  --output journey-plan.json [--scaffold-output fragment.json] [--report-only]
# クレーム / 証拠 / リグレッション / カバレッジ（課題 #1445-#1448）
./run.sh regressions audit ../ --output /tmp/agentic-evals-regressions.json
./run.sh regressions show . && ./run.sh regressions verify .
./run.sh coverage audit ../ --output /tmp/agentic-evals-coverage.json
./run.sh coverage show .

クレームベースの準備完了状態 (#1445)

決定論的テストはメカニズムを証明し、実際のE2Eテストは機能を証明します。 合格する決定論的ケースの山が、一度も実行されたことのないライブ機能の準備完了状態を示しているように見えてはなりません。したがって、準備完了状態はケース数からではなく、宣言された機能クレームごとに計算され、集約されます。

capability_claimsを宣言します（v2フィクスチャの互換性を保つため、claimsの証明範囲の散文とは別に保持します）。各クレームをサポートするケースは、それ自体にタグを付けます：

{
  "capability_claims": [
    {"id": "ask.roundtable.mixed_provider", "description": "...",
     "criticality": "critical",
     "evidence_required": {"deterministic": true, "live_e2e": true}}
  ],
  "cases": [
    {"name": "roundtable-live", "type": "positive", "evidence_class": "live_e2e",
     "supports_claims": ["ask.roundtable.mixed_provider"],
     "command": ["bash", "run.sh", "..."],
     "expected": {"exit_code": 0, "artifacts": [{"path": "out/join.json", "json_pointer": "/settled", "equals": true}]}}
  ]
}

証拠クラス: deterministic、property_or_fuzz、fault_injected_deterministic、live_e2e、adversarial_live_e2e、human_evaluation。クレームごとの評決: PROVEN、PARTIALLY_PROVEN、BLOCKED_EXTERNAL、FAILED、NOT_ESTABLISHED。スキルがREADYとみなされるのは、必要なすべての critical クレームが、それぞれの証拠要件の下でPROVENである場合のみです。クレームが宣言されている場合、runのゲートはケースベースとクレームベースの準備完了状態のうち悪い方となるため、20のグリーンな決定論的ケースがありながら、必須のlive_e2eスロットが満たされていない場合、READYには到達できません。複数のクレームをサポートするライブケースは、クレームごとに独立したアーティファクトを持つ必要があります。そうでない場合、どのクレームに対してもカウントされません。report["capability_readiness"]には、クレームごとの内訳が保持されます。

不変条件から導出されたクレーム（回答をスタブ化しない）— オペレーター 2026-09-11

oai-trialは1つの省略によって失われました。「PIIが出力に到達しない」という要件が、暗黙のうちに「PII文字列が出力に到達しない」に狭められました。すべての評価、検証、および資格認定実行は、整数型の電話番号がそのまま通過している間、狭められたクレームがグリーンであることを証明しました。クライアントはドメインスコープで不変条件を読み取り、私たちはメカニズムスコープでそれを証明しました。ルール：

1. クレームはドメインの不変条件から導出され、コードが既に行っていることから導出されてはなりません。 capability_claimsを宣言する前に、不変条件をクライアントの言葉で（「いかなる表現においてもXが出力に到達しない」）書き、それをそのままクリティカルクレームとして宣言します。現在の動作を説明するクレームはスタブです。
2. 値に関連するクレームには表現マトリックスが必須です。 データ値（PII、金額、識別子、シークレット）に関するクレームは、入力形式が許容する表現（JSON文字列/整数/浮動小数点/指数表記、CSV引用、SQL型）を列挙し、表現ごとに少なくとも1つの敵対的ケースを持ち、それぞれが失敗可能である必要があります。表現マトリックスなしの値クレームはPROVENにはなりません。
3. データ値を変換、フィルタリング、または編集するパイプラインには、value-representation（criticality: critical）という名前のカバレッジシームが必須です。 監査は、そのシームに有能なガードが存在することを示さなければなりません。
4. 独立したチェッカーは、プロデューサーのデータジェネレーターを共有してはなりません。 検証のフィクスチャには、変換自体のフィクスチャが持たない表現を含める必要があります。そうでなければ、独立性は名目上のものになります。
5. 表現のギャップが出荷された場合、それをfixtures/regressions.json（インシデント→保持されたガード）とvalue-representationシームに記録します — 同じ種類のミスが永久に検出可能でなければなりません。

アンチスロップ契約は自己充足的配管を拒否します。これらのルールは自己充足的仮定を拒否します — 正直で、敵対的で、複数試行でありながら、すべてのフィクスチャがデータの形状に関する1つの目に見えない前提条件を共有しているために盲目であるスイートに対してです。

実際のエンドツーエンド証拠契約 (#1446)

evidence_classは、コマンドにrun.shやcurlが含まれていることから推測されません。ライブクラス（live_e2e/adversarial_live_e2e）を宣言するケースは、構造的に認定され、以下の場合にダウングレードされます（黙って受け入れられることはありません）：

• 境界権限として自身にfixtures//スタブ/mocked入力を与える場合；
• 実質的な本番エントリポイントに到達しない場合；
• 独立した読み返しオラクル（expected.artifacts、readback: true、またはstdout_excludes）がない場合 — 終了コードとコマンド自身の成功を示す散文は証拠になりません；または
• $askブラウザtau-dag/competeハンドラーに対して、--executeと、node-receipt.json、response.md、response.meta.json、browser-tab-lifecycle.json、execution-status.json、roundtable-summary.md、またはcompete-scorecard.jsonなどのブラウザ/プロバイダ実行アーティファクトからの読み返しなしで、ライブ証拠を主張する場合。コンパイル/プリフライトのみの$askケースは決定論的メカニズムの証拠であり、live_e2eになることはありません。

ダウングレードされたケースはfault_injected_deterministic（実パス上の障害）またはdeterministicになり、レポートにはevidence_disqualifiersが記録されます。BLOCKED_EXTERNALケースによってのみ満たされる必須のライブスロットは、クレームをPROVENにしません。

例外は明示的であり、有効期限があります。クレームはexemptionsを保持でき、evidence_class、reason_code、justification、owner、およびexpiresを指定します。有効な例外はレポートに表示されます（exempt_evidence）が、クレームをPROVENにすることはありません。期限切れまたは不完全な例外は無視されます。実行可能な運用機能に対して、包括的なeval_not_requiredが満たされることはありません。

インシデントから保持されたリグレッションへ (#1447)

ライブ障害はfixtures/regressions.json（agentic_evals.regressions.v1）に永続的な証拠となります。各レコードはインシデントをそれが脅かしたクレームとシームにリンクし、保持されたガードケース（retained_case / retained_fixture）を指定し、fail_before_fix.proof_commandを保持します。

• regressions show <skill> / regressions audit <root> レポート：保護されていないリグレッション（保持されたケースが欠落/名前変更）、証明されたことのない（おそらく空虚な）リグレッション、古くなったライブプルーフ、廃止されたリグレッション、およびリグレッションマッピングのないオープンインシデント。
• regressions verify <skill> は各プルーフコマンドを再実行し、ガードが実際に壊れた動作に対して失敗する（非ゼロで終了する）ことを確認します — 自己報告フラグではなく、非空虚性の証明です。アクティブなリグレッションのガードが修正前の失敗を示せない場合、非ゼロで終了します。

評価の期待値を壊れた出力に合わせて編集することによってバグを修正することは、まさに非空虚性証明が捕捉するものです。リグレッションを廃止するにはretirement理由が必要です。

リスクベースのカバレッジ十分性 (#1448)

ケース数を数えることはゲーム可能です。coverage audit/coverage showは、宣言されたseamごとに尋ねます：そのシームでリグレッションを検出できるケースが少なくとも1つあり、シームのリスクが必要とする各証拠クラスにおいて存在するか？seam_id、seam_type、criticality、およびrequired_evidenceを持つseamsを宣言し、ケースにseamsでタグを付けます。ケースは、そのシームをリストしかつ失敗できるオラクルを保持する場合にのみ、シームをカバーします。ベアなexit 0のポジティブはweak_onlyであり、カウントされません。監査は、カバーされている/されていないシーム、weak-onlyカバレッジ、ライブ vs 決定論的カバレッジ、マッピングされたインシデントリグレッション、および優先順位付けされた次の評価を報告します。カバレッジ（有能なガードが宣言されている）と新鮮さ（ライブプルーフが最新である）は別々の次元です。ランナーはここでシームケースを実行しません。

フィクスチャ契約

{
  "version": 2,
  "skill": "example-skill",
  "trials": 3,
  "proof_scope": "fixture wiring smoke",
  "claims": {
    "proves": "the declared command exits with the expected status",
    "does_not_prove": "semantic correctness, live service behavior, or full skill readiness"
  },
  "cases": [
    {
      "name": "happy-path",
      "type": "positive",
      "command": ["echo", "success"],
      "expected": {
        "exit_code": 0,
        "stdout_contains": ["success"]
      }
    }
  ]
}

各ケースは以下を宣言する必要があります：

• name
• type： positive、negative、またはadversarial
• command： 空でないargvリスト
• expected.exit_code

オプションの期待値：

• expected.stdout_contains
• expected.stderr_contains
• must_exercise： ケースのトップレベルコマンドに現れなければならないダウンストリーム契約コマンドの部分文字列のリスト。これは、ラッパーが成功を偽造できる場合に使用します。たとえば、$ticket/$project-watchdogのルーティング可能性を主張する評価は、OKを出力するヘルパースクリプトのみではなく、"skills/ticket/run.sh feature"を含める必要があります。

アンチスロップ契約（フェイルクローズド）

スキル評価フィクスチャは、現実世界の証拠ではなく自己充足的な決定論的配管である場合、ロード時に拒否されます（非ゼロ終了、実行なし）。合格するためには、スキルフィクスチャは以下を必須とします：

• trials >= 2 を設定する（単一試行は証拠ではありません）；
• 少なくとも1つのnegativeまたはadversarialケースを含む（全ポジティブフィクスチャは自己充足的です）；
• 少なくとも1つの現実世界ケース："real_world": trueであり、そのコマンドが実パス（スキルのrun.sh / スクリプト / ライブHTTP / テストランナー）を実行し、自身にfixtures/スタブ入力を与えてはなりません；
• 何も証明しない些細なecho/定数ケースを含まない。

拒否メッセージはすべての違反を指定します。これにより、スキルが実際に動作するかどうかを何も証明せずに簡単にパスしてしまう評価を防ぎます。

コンプライアンスティア（"eval_tier": "compliance"）

コンプライアンスパイプラインステージをガードするフィクスチャは"eval_tier": "compliance"を宣言し、ランナーはベースラインに加えて強力な契約を必須とします（オペレーター指令2026-08-12、「これはコンプライアンスパイプラインであり、堅牢に強化されなければならない」）。このようなフィクスチャは、以下の場合を除き拒否されます：

• 厳格な過半数のケースがadversarial/negativeである（正確に半数ではなく、半数超 — ポジティブコントロールは少数派）；
• 少なくとも1つのケースが非決定論的である：そのコマンドが--samples、--seed、またはシェルの$RANDOMを介して毎回新しい入力をサンプリングする（固定キーを持つプローブスクリプト名はカウントされません）；
• すべての非決定論的ケースが--samples >= 50 を指定し、各ステージのカバレッジが実行ごとに数百から数千のアサーションとなり、そのモード全体でステージあたり約1000をターゲットとする。

この宣言は静かに緩和されることはありません。コンプライアンスパイプライン自体のフィクスチャがティアを設定するため、ゲートを回避するためにそれを削除すること自体がリグレッションです。tests/test_compliance_tier_gate.pyは、各ルールの弱体化を阻止します。

正直に宣言された2つの例外はゲートをバイパスします — 実際のスキル評価では決して有効ではありません：

• "eval_kind": "runner_selftest" — このランナー自体、またはドキュメント例をテストするフィクスチャ。
• "eval_kind": "scaffold" — scaffold-fixture / apply-scaffoldsによって出力される機械的な最初の姿勢フィクスチャ。監査は依然として実際のケースが必要であることをフラグ付けします。

準備完了状態マッピング

準備完了状態は必須ケースのみに対してスコアリングされます（"required": falseはケースを対象外にします）。必須のBLOCKEDケースはREADYに到達できません：満たされていない前提条件は、成功の証拠ではなく、証拠の欠如です。

• READY：すべての必須ケースがすべての試行に合格しました。
• USABLE_WITH_GAPS：少なくとも1つの試行が合格し、少なくとも1つが合格しませんでした。
• NOT_READY：試行は実行されましたが、必須ケースが完全に合格したものはありませんでした。
• NOT_ESTABLISHED：ケースが実行されませんでした。

フェイルクローズド終了

runは、準備完了状態がREADYでない限り非ゼロで終了します。USABLE_WITH_GAPSで0で終了するランナーは、失敗したケースがあっても外部のCIジョブをグリーンにさせてしまいます。これは、このゲートが存在する目的全体の失敗です。ゲートなしでレポートが必要な場合は、--report-onlyを使用してください。

ケースの結果

各ケースは1つのoutcomeを報告します。これらはゲートにとって異なる意味を持つためです：

結果	意味
PASS	すべての試行がすべての期待値を満たしました
FAIL	欠陥、タイムアウト、または子プロセスを残した試行
BLOCKED	前提条件が満たされていません。blocked_when_stdout_containsを介してマーカーを宣言します
NOT_TESTED	試行が実行されませんでした

アーティファクトアサーション

stdoutの部分文字列一致では、「これらの2つのレシートが同じセッションを指定している」や「実行が何も残さなかった」を表現できません。expected.artifactsを宣言します：

"expected": {
  "exit_code": 0,
  "artifacts": [
    {"path": "out/session.json", "json_pointer": "/sessionId",
     "equals_artifact": {"path": "out/detach.json", "json_pointer": "/sessionId"}},
    {"path": "out/attach.json", "json_pointer": "/sessionId",
     "equals_artifact": {"path": "out/detach.json", "json_pointer": "/sessionId"}},
    {"path": "out/cleanup.log", "not_exists": true}
  ]
}

各アーティファクトエントリは以下をサポートします：

• path： フィクスチャの作業ディレクトリからの相対パス。
• json_pointer（オプション）： 評価するJSON内のパス。
• equals： リテラル値（文字列、数値、ブール値、null）と比較します。
• equals_artifact： 同じフィクスチャ実行内の別のアーティファクトパス+json_pointer。2つのセッションIDが一致することをアサートするために使用します。
• not_exists： アーティファクトが存在しないことを確認します（クリーンアップの検証）。
• exists： アーティファクトの存在を確認します（not_existsと相互排他的）。

json_pointerなしのequals/equals_artifactは、ファイル全体をその値と比較します（ベアなテキストファイルに便利）。アーティファクトアサーションは、stdoutの部分文字列だけでは不十分なクロスチェックに特に有効です。

トラジェクトリチェック

動的プロセスは重要な出力を標準ストリームに書き込むことはできますが、どの呼び出しがどのような順序で行われたかの記録であるトラジェクトリを残すこともできます。以下を宣言します：

"expected": {
  "trajectory": {
    "required_events": [
      {"type": "tool_use", "name": "execute_command", "parameters.user_interaction_approved": true},
      {"type": "output", "content_contains": "handoff"}
    ],
    "required_order": true,
    "forbidden_events": [
      {"type": "tool_use", "name": "execute_command", "parameters.command_contains": "rm -rf"}
    ]
  }
}

必須イベントは、イベントタイプおよび/またはパラメータフィールドの存在と値に対してテストされます。required_orderは、必須イベントが順番に現れる必要があるかどうかを決定します（falseは順不同の一致を許可します）。禁止イベントは、評価実行全体を通じて照合されます。

トラジェクトリ記録はスキルとは別の設定によって有効になります（例：CLAUDE_CODE_TRAJECTORY_RECORDING=true）；フィクスチャそれ自体はトラジェクトリをキャプチャしません。トラジェクトリを見つけられなかったランナーは、そのチェックをNOT_TESTEDとして報告します。

安全性と制約

CLI生成スキルはファイルシステムへのアクセスが制限されません。allowed_domains / disallowed_domainsで許可されるネットワークドメインを宣言します：allowed_domains: ["api.example.com"]、disallowed_domains: ["internal.corp.net"]。ケースがexpected.allowed_domainsを宣言する場合、ランナーはそのケースの実行中にドメイン制限の実施を試みる場合があります。制限の実施に失敗したランナーは違反を報告しますが、ケースを失敗させることはありません — 実施は評価インフラストラクチャに依存します。

準備完了状態のゲート動作

runは以下を行います：

1. フィクスチャをロードして検証します。
2. 各ケースをtrials回実行します。
3. すべての試行がすべての期待値を満たしているかどうかチェックします。
4. 結果に基づいて準備完了状態を計算します。
5. レポートを出力します（stdoutに、および--outputが指定された場合はファイルに）。
6. 準備完了状態がREADYでない限り、非ゼロで終了します（--report-onlyでオーバーライド可能）。

このゲートは、評価が「おそらく動作する」ではなく「動作することが証明された」という強いシグナルであることを保証します。