evr

evidence-readiness

エージェントの実行トレースに、事後的な因果関係の再構成に必要となる証拠が含まれているかを確認します。

AI エージェントが損失を引き起こした場合（設定変更の失敗、セッションをまたぐデータ漏えい、エージェント間で連鎖する汚染された出力、プロンプトインジェクションなど）、いずれ誰かがトレースから なぜそうなったのか を再構成する必要があります。汎用エージェント計装のトレースでは、その再構成を裏付けられません。証拠がそもそも記録されていないからです。このリポジトリには、エビデンス・レディネス仕様（SPEC.md）、仕様に照らしてトレースを評価するチェッカー、準拠した計装の例を示す参照用フィクスチャが含まれています。

これは何か — 何ではないか

• 確認するのは証拠が 存在する ことだけであり、それが 真実である ことではありません。 捏造されていても内部的に整合しているトレースは合格します。このツールは何も認証しません。また、その結果を「このエージェントは安全です」と伝えてはなりません。
• 障害が発生したかどうかを判定することはありません。 「クラス X の再構成に必要な情報がこのトレースに含まれているか」には答えますが、「クラス X が発生したか」には答えません。検出やスコアリングのロジックは含まれていません。
• このリポジトリに再構成エンジンは含まれていません。 手法を評価できるよう仕様を公開しています。エンジンは SOURCE_AVAILABILITY.md の条件に基づいて閲覧できます。
• 対象となる障害クラスは 4 つです：config_drift、session_isolation_failure、cascade_contamination、prompt_injection。5 つ目の (tool_misuse) は調査のうえ、明記された構造上の理由から対象外としました。これは文書化された否定的な結果であり、欠落ではありません（SPEC.md §8）。
• この仕様はOTel GenAI セマンティック規約のプロファイルです。コア OTel と文書化された拡張を含みます（SPEC.md §2）。標準化団体による承認を受けたものではありません。

対象ユーザー

• エージェントに計装を実装するエンジニア：インシデントを事後に再構成できるようにしたい方。トレースを準拠フィクスチャと比較し、追加すべき項目を確認できます。
• レビュー担当者（保険会社、監査担当者、取引相手）：エージェントシステムのテレメトリーが、損失に関する事後の判断を裏付けられるかを評価する方。
• コーディングエージェント：llms.txt、spec.json（生成される機械可読な仕様のエクスポート。手作業で保守することはありません）、および src/evidence_readiness/mcp_server.py の MCP サーバー（設定は以下を参照）をご覧ください。

クイックスタート（60 秒）

# from a clone of this repository
pip install .
evr check path/to/trace.json        # or a directory of traces
evr check --json path/to/traces/    # machine-readable report
evr check --require-class prompt_injection path/to/trace.json

このパッケージには実行時依存関係が一切ありません。Python ≥3.10 環境で pip install . を実行すればセットアップは完了です。同等の uvx 形式も検証済みです。クローンから実行する場合は uvx --from . evr check ./traces、パッケージインデックスから実行する場合は uvx --from evidence-readiness evr check ./traces を使用します。

どちらも --from が必要で、末尾の evr も省略できません。 uvx evidence-readiness ... とだけ実行すると、ディストリビューション名と同じ名前のコンソールスクリプトが実行されます。このスクリプトはチェッカーではなく MCP サーバー（以下を参照）です。標準入力を読み取り、引数を無視して、何もチェックせずに正常終了します。

終了コードに再構成に関する意味はありません。0 はすべての要件を満たす、1 は 1 つ以上の要件を部分的に満たす、2 は 1 つ以上の要件を満たさない、3 は入力形式が不正であることを表します（正式な定義は SPEC.md §9 を参照してください）。終了コードは共通要件（EVR-R1..R6）に基づきます。クラスごとのエビデンス・レディネスは別途報告され、--require-class を指定すると、指定したクラスのレディネスが終了コードに反映されます。要件を満たさない場合、出力には不足しているフィールドと、そのフィールドが属するスパン種別が具体的に示されます。

すべての実行は、この README の冒頭と同じ説明で終わります。存在であって、真実ではありません。証拠が存在しても本物であるとは限らず、トレースに合格してもエージェントが安全であるとは限りません。

CI：すべての PR をチェックする（GitHub Action）

仕様は一度読むだけですが、すべての PR で実行されるチェックは計測動作を変えます。トレースを生成するリポジトリのワークフローに、次の内容を追加してください（公開後は evidence-readiness がこのリポジトリのオーナーです。このリポジトリ内からは uses: ./.github/actions/readiness-check を使用します）。

steps:
  - uses: actions/checkout@v4
  - uses: evidence-readiness/spec/.github/actions/readiness-check@main
    with:
      trace-path: traces/

設定はこれだけです。GitHub のデフォルトランナーにある python3 で十分で、Action がチェッカー自体をインストールします（依存関係はありません）。チェッカーの終了コードが minimum-passing-exit-level（デフォルトは 0。終了コードの意味は上記のクイックスタートと同じです）を超えると、このステップは失敗します。required-classes を指定すると、名前付きクラスのエビデンス要件も終了コードに反映されます。出力は exit-code、exit-meaning、report-path（JSON レポート全体）、per-class-readiness です。PR の注釈には、未完了の各要件について、具体的に不足しているフィールドとスパンの種類が示されます。すべての注釈はエージェントについてではなく、トレースのテレメトリについての記述です。注釈が付いた PR はエビデンスが不完全ということであり、障害が検出されたということではありません。また、チェックに問題がなくても、エージェントが安全だということにはなりません。このリポジトリ独自の CI（.github/workflows/ci.yml）では、fixtures/ に対して Action を実際に使用し、バケットごとに想定された、意図的にゼロではない終了コードを検証しています。

MCP サーバー（エージェント向けインターフェース）

src/evidence_readiness/mcp_server.py は、Model Context Protocol（stdio）経由で、チェッカーと要件データをエージェントに公開します。ツールは 3 つです。check_trace_readiness（ファイル、ディレクトリ、またはインライン JSON に対応。インラインコンテンツはメモリ内で処理され、どこにも書き込まれません）、get_requirement、list_class_requirements です。

パッケージをインストールすると、コンソールスクリプトが3 つ提供されます。以下をコピーする前に、それぞれの役割を正確に確認しておくとよいでしょう。

スクリプト	実行するもの
evr	チェッカーの CLI。人が使うのはこちらです
evr-mcp	stdio 上で動作する MCP サーバー
evidence-readiness	stdio 上で動作する MCP サーバー。evr-mcp と同じものを実行します。パッケージ名に合わせた名前で、<package> を同名のスクリプトに解決する、呼び出しごとのランナーで見つけられるようにしています

つまり、evidence-readiness はチェッカーではありません。シェルで実行すると、stdin 上で JSON-RPC を待ち受けるサーバーが起動するため、ハングしたように見えます。evr を使ってください。

パッケージがインストール済みの場合は、evr-mcp コンソールスクリプトだけで設定できます。

{
  "mcpServers": {
    "evidence-readiness": {
      "command": "evr-mcp"
    }
  }
}

クローンからインストールせずに使う場合は、代わりにパスを指定してモジュールを実行します。

{
  "mcpServers": {
    "evidence-readiness": {
      "command": "python3",
      "args": [
        "/absolute/path/to/evidence-readiness/src/evidence_readiness/mcp_server.py"
      ]
    }
  }
}

どちらの方法も依存関係は不要で、後者はインストールも必要ありません。ローカルのみで動作し、ネットワーク呼び出しやホームへの通信はなく、何も永続化されません。 意図的に送信ツールはありません。サーバーは何も送信しません。トレースをどこかに送信するかどうかは人が決めることであり、その判断には CONTRIBUTING.md の免責事項と、エージェントにはできない匿名化の判断が必要です。すべてのツールの説明には、存在することは真実を意味しないという注意書きが含まれているため、準備状況の結果を「このエージェントは安全です」と伝えることはできません。

ステータス

仕様はバージョン管理されており（SPEC.md に現在のバージョンと修正履歴が記載されています）、チェッカーは仕様に基づいて実装されています。また、リファレンス用フィクスチャ（fixtures/）、機械可読形式のエクスポート（spec.json）、エージェント向けのインターフェース（llms.txt、MCP サーバー）、CI アクション（.github/actions/readiness-check/）も用意されています。方法論と限界に関する論文の草稿（PAPER.md）もあり、冒頭のバナーには、敵対的レビューを受けたセクションと受けていないセクションが記載されています。継続的な開示方針は SOURCE_AVAILABILITY.md に、報告およびトレース提出の条件は CONTRIBUTING.md に定められており、秘匿化のガイダンスは REDACTION.md、リリースの検証については RELEASING.md に記載されています。修正内容は CHANGELOG.md に記録されています。仕様は記述的なものであり、すべての要件は、240 件の再構成試行を記録した検証記録で観察された結果によって裏付けられています。そのうち 222 件は合成データです。裏付けは要件ごとに、該当要件を検証した個別のケースに基づくものであり、240 件全体を通じて測定された特性ではありません（実世界の Who&When ケース18件が検証するのは棄却の方向性のみです。この内訳は、件数が記載される箇所すべてに明記されています — SPEC.md §1）。

クレジット

Brien Buckman

Apache-2.0 ライセンスの下でライセンスされています（LICENSE を参照）。

このリポジトリの開発記録の実質的な内容は公開されています。公開済みの内容に影響する修正は CHANGELOG.md に記録され、手法に関わる開発上の欠陥記録は PAPER.md §8.6 に要約されています。これらのファイルの草稿作成と改訂に用いられたコミット履歴は公開されていません。