Verdict QA

Verdict

CI · Verdict 自身での検証 · 評価：仕込まれた欠陥を8件中8件検出 · 固定ルール：501件中501件を検出 · PyPI：verdict-qa-mcp · MIT ライセンス

テストスイートはグリーンです。Verdict は、4,595日間潜んでいた欠陥を発見しました。

Verdict は、修正せず、お世辞を言わず、忘れない QA エージェントです。判断する前に測定します。ハーネスがゲートを実行し、指摘が引用するすべての行のハッシュを計算し、旧コミットと新コミットで保護するテストを再実行します。そして、記憶を保ちます。実行ごとに前回との差分を取り、指摘には経過期間を記録し、リグレッションを最優先に並べ、テスター自身の見逃しも検出結果と並べて公開します。Verdict が従う契約は不変であり、すべての判定にハッシュが記録されます。学習内容は契約の隣に日付付きで監査可能な形で保存され、契約を編集することはありません。上記の数字は実際のものです。7k★の Python ライブラリにある FilePerms は、2014-02-07以来、権限ビットを取り消せませんでした。Verdict がこれを報告した日も、625件すべてのテストがグリーンでした。—実行結果と見逃しは台帳に記録されています。

/plugin marketplace add ArtJack/verdict     # Claude Code
/plugin install verdict@verdict
/verdict:run

npx skills add ArtJack/verdict              # every other coding agent

多くの AI「QA エージェント」は、熱意あふれる文章にチェックリストを添えただけです。実行のたびにリポジトリをゼロから監査し、読み飛ばされるようになるまで同じ指摘を20件報告し続け、不安定なテストを「失敗」と呼び、古くなったテストも「失敗」と呼び、最後には「LGTM！🎉」で締めくくります。

Verdict は、QA の実際の運用に即して構築された Claude Code プラグインです。

• 記憶します。 状態ファイルにベースラインを保持します。各指摘には固定 ID と経過期間が付き、実行のたびに NEW / STILL_OPEN / RESOLVED / REGRESSED を報告します。リグレッションは常に最優先です。
• テストの失敗には意味があります。 すべての失敗を分類します。REAL_DEFECT、STALE_EXPECTATION（変更が意図されたものだと証明する引用が必要です）、BRITTLE_TEST、ENVIRONMENT、または FLAKY（再実行で確認し、期限付きで隔離します）。リグレッションを免責する可能性が最も高い分類には、最も高い証拠基準を適用します。
• 根拠を示せる判定です。 すべての実行は、pass | pass with risks | blocked | fail のいずれか1つだけで終了します。未解決の Blocker があれば必ず fail となり、blocked も正当な結果です。また、pass では、テストしなかった項目を必ず明示します。
• コードを修正することはありません。 Edit ツールは存在せず、フックによって書き込み先は QA のルートに限定され、厳格モードの Bash ガードがシェルの書き込み経路を塞ぎます。評価対象を修正するテスターは独立しているとは言えません。このガードはヒューリスティックであり、サンドボックスではありません。README でもその点を明記しています。
• テストされており、自身もテストします。 見逃しを公開するスコア付き評価スイート、モデルが偽造できない署名付き実行履歴、テスター自身が編集できない実績があります。また、リリース自体も監査しています。最初の15回の実行で、自身に対して78件の指摘を登録しました。そのうち59件は修正済みで、修正も検証済み、1件はリスクとして記録上受け入れられ、2件は未解決、16件は証拠なしで終了しました。独自の台帳では、これらを成功ではなく「不明」と数えています。修正されたハーネスの各ルールは、スイートが検出しなければならないミュータントとして固定されています。

実行結果の例：実際の差分レポート — Verdict 自身のコードを対象にした実行14。

モデルの料金は誰が払いますか？ すでにお使いの Claude サブスクリプションを通じて、あなたが支払います。プラグインはあなた自身のセッション内で動作し、ほかの誰かを経由することはありません。また、モデルより下のすべての要素 — 状態、ゲート、ハーネス、評価スコアラー — は無償で動作する標準ライブラリの Python です（オプションの MCP サーバーでは mcp SDK を追加します）。 Python、TypeScript、Go など、テストランナーがある環境で動作します。評価用フィクスチャは Python と TypeScript に対応しています。 次に読む項目： インストール · インストールされるものと実行タイミング · クイックスタート · 別の QA エージェントが必要な理由 · テスト済みのテスター · CI ゲート · リスクの受け入れ · FAQ

インストール

/plugin marketplace add ArtJack/verdict
/plugin install verdict@verdict

Cursor、Codex、OpenCode など、その他のコーディングエージェントは、エージェントスキルのエコシステムで同じ原則を 5 つのスキルとして利用でき、同じハーネスを pip パッケージとして利用できます。

npx skills add ArtJack/verdict        # release risk · verify a fix · flaky triage · root cause · spec review
pip install verdict-qa-mcp            # verdict-facts, verdict-finalize, verdict-gate, verdict-accept, verdict-answer, verdict-replay, verdict-dupes

skills.shに掲載されています。

スキルは、verdict エージェントを実行できないエージェント向けに契約を再提示するものです。読み取り専用の保証を強制するフックは Claude Code にのみ存在するため、そこでの保証はエージェント自身の規律と、ハーネスによる拒否に基づきます。リポジトリのルートにある AGENTS.md と llms.txt は、行動する前に読み込むエージェント向けです。

Python 3.9 以降が必要です。python3 が解決するバージョンを使用します。フックとファクトハーネスは標準ライブラリのみを使用し、その名前で呼び出されます。標準構成の Mac では /usr/bin/python3（3.9）です。オプションの MCP サーバーは pip でインストールし、3.10 以降が必要です。pyproject.toml の requires-python が示すのはこの要件です。最小バージョンでの動作はテスト済みです。Python 3.9 でインポートに失敗するモジュールがあれば、CI も失敗します（tests/test_interpreter_floor.py）。未然に防ぐ失敗が、気づかれないまま起きていたためです。以前、Bash ガードはそこでインポート時に例外を発生させましたが、隣の書き込みガードは動作し続けていました。そのため、厳格なセッションが、制御機能の半分を失ったまま有効に見えていました。

インストールされるものと実行タイミング

プラグインをインストールするということは、そのコードをセッション内で実行させるということです。そこで、このプラグインが実際に行うことを、記憶から要約するのではなく、hooks/hooks.json に基づいて正確に説明します。 6 つのフック登録があり、それぞれのイベント発生時に python3 が起動します（数十ミリ秒）。

イベント	発生タイミング	スクリプト	実行されない条件
PreToolUse	Write／Edit／MultiEdit／NotebookEdit	書き込みスコープガード	VERDICT_STRICT=1 の場合、または呼び出し元が Verdict エージェント自身の場合を除き、常に実行されません。また、どのセッションでも、QA ルートの accepted.json／answers.json への書き込みには実行されません。これらを書き込むのは verdict-accept／verdict-answer だけです
PreToolUse	Bash	bash スコープガード	VERDICT_STRICT=1 の場合、または呼び出し元が Verdict エージェント自身の場合を除き、常に実行されません
PostToolUse	Write／Edit／MultiEdit	状態バリデーター	書き込まれたファイルが QA ルートの state.json または findings/<ID>.json の場合を除き、実行されません
Stop／SubagentStop	ターン終了時	実行契約チェック	このセッション内の QA 実行で手書きの状態が残された場合、またはこのセッションの Verdict エージェントが事実を計測した後、verdict-finalize を実行せずに停止した場合を除き、実行されません（実行マーカーにはセッションが記録されます。他セッションのマーカーや、実行中の別エージェントの停止は何も意味しません）。各条件につきブロックは最大 1 回で、ループはしません
SessionStart	セッション開始時	指摘事項のバナー、または初回のみのヒント	リポジトリに QA 状態がある場合は実行されません。ヒントの場合は、Verdict がまだ見たことのないテストスイートがある Git リポジトリでの、新規の対話セッション開始時に限られます（リポジトリごとに 1 回、1 人あたり 3 リポジトリまで。VERDICT_STRICT、VERDICT_NO_HINT=1、またはヘッドレスの claude -p では表示されません）

すべてのフックはフェイルオープンです。入力が不正な場合、ファイルが見つからない場合、または例外が発生した場合は、終了コード 0 で何も表示しません。壊れたフックによってセッションが決して使えなくなることはありません。スコープガードを有効にするのは VERDICT_STRICT=1 です。これは専用の QA セッション（ヘッドレス、CI、夜間実行）でのみ設定してください。通常の対話作業では、ガードは何もしません。

グローバルにインストールしたくない場合は？ リポジトリ単位でもすべて動作します。agents/verdict.md を <repo>/.claude/agents/ に、hooks/hooks.json のエントリーを <repo>/.claude/settings.json にコピーし、${CLAUDE_PLUGIN_ROOT} をチェックアウト先のパスに置き換えてください。評価ハーネスが一時プロジェクトを準備する方法もまさにこれです。eval/run_eval.py がリファレンス実装です。

クイックスタート

/verdict:run                          # first run: profile + isolation rules + baseline
/verdict:run the payment retry change   # every later run: a delta against the stored state

以降の実行では毎回、保存された状態との差分を確認します。再実行すると、次のような結果が返されます。

VERDICT: fail

Scope: 2c67f47..b4e2943 (4 commits, 16 files) · run 4 (delta)
Isolation check: pass (no .env present; no live service touched)

Findings — REGRESSED first:
REGRESSED  PRICER-F-002  Critical/P0  round_cents uses banker's rounding again (pricer.py:17)
                         resolved 08-19, reintroduced by b4e2943 — this forces the verdict
NEW        PRICER-F-007  Major/P1     quarantine graveyard: test_listable_at_floor_exactly
                         skipped 114 days with no expiry — it is the test that would catch F-001
STILL_OPEN PRICER-F-001  Critical/P0  age 6d  is_listable rejects a price exactly at the floor
FLAKY      test_bulk_discount_applies — fails 3/6 runs with no code change; quarantined
           until 2026-09-07, excluded from this verdict, listed until re-evaluated

Delta gates: tests 213 → 213 · duration +0.4% · coverage on changed files: no decrease
Release blockers: PRICER-F-002 (regressed), PRICER-F-001
Not tested: concurrency under parallel checkout — no harness present
Fix order: 1) F-002  2) F-001 (unskip its test first, watch it fail red)  3) F-007 expiry
Artifact: .qa/reports/2026-08-24-pricer-review.md

新たな QA エージェントが必要な理由

	一般的な qa-expert.md	評価
前回の実行結果を記憶する	いいえ — 実行のたびに新規監査	状態ファイル。経過日数付きの NEW/STILL_OPEN/RESOLVED/REGRESSED
不安定なテスト	「不安定なテストを1％未満に保つ」（説明文）	期限必須の隔離台帳。不安定なテストは評価から除外するが、レポートからは除外しない
リリース判断	「go/no-go」がチェックリストの項目として登場	4段階の評価契約。未解決の Blocker があれば fail
失敗したテストのトリアージ	「失敗を調査する」	5分類の分類体系。STALE_EXPECTATION には意図の引用が必須
品質ゲート	「カバレッジ90％超」の絶対基準	方向性ゲート。変更したファイルのカバレッジは低下させない。テスト収集数0件とテスト失敗1件は同じではない
テスト設計	「エッジケースをテストする」	リスクトリガー付きの24種類の手法カタログ。プロパティベーステスト、（ML/LLM出力向けの）メタモルフィックテスト、MC-DC、コントラクトテストを含む（docs/test-design.md）
コードを編集できる	それを止めるものはない	Edit ツールなし + 書き込み範囲フック + strict モードの Bash ガード
セキュリティ	無視するか、誇大に評価する	オプトインのレポートのみのパス。依存関係監査 + diff のシークレットスキャン。ペネトレーションテストは明示的に対象外
リスクの優先順位付け	「高リスク領域に注力する」	プロジェクト独自の指摘履歴からランキングを算出（重要度で重み付けし、引用の深さをまたいでパスを統合）。レポートにはランキング、しきい値、そしてテスト対象外に分類されるしきい値以下のすべてを表示する
根本原因	「失敗を調査する」	各リンクに引用を付けた4つのリンクからなる連鎖。必須の分類チェック（これは個別の事例か、パターンか？）と、スクラッチコピーで原因を切り替えて因果関係を証明。おとりを組み込んだ専用の採点済みフィクスチャ付き
要件レビュー	行わない — コードのみ	/verdict:spec がコード作成前に仕様を評価（矛盾、測定不能な要件、境界の曖昧さ、履歴との競合）。専用の採点済み評価フィクスチャ付き
「バグは見つかりませんでした！」	頻繁にある	決してない — 代わりにカバレッジ、ギャップ、残存リスクを報告
AI が作成したコード	人間のコードと同じチェックリスト	来歴を測定（対象範囲のトレーラー調査、プロファイル authorship）。各項目に手順と証拠基準を定めたパターンカタログ（docs/ai-authored-code.md）。幻覚によるインポート、プレースホルダー、握りつぶされたエラーの決定論的な調査結果を判断に反映し、採点済みフィクスチャで動作を検証
自身の精度	測定されず、事後の測定も不可能	すべての指摘は登録時に信頼度を明記。指摘が実際にどうなったかに基づいて結果を算出し、恒久台帳に保存して、テスト担当者が編集できない実績として報告
自身をテスト済み	—	採点済み評価スイート。ベースライン + 差分メモリ + 敵対的な正直さのフィクスチャ、決定論的なスコアラー、公開済み解答キー（eval/）
他のツールが利用できる状態	—	verdict-mcp：状態を参照する読み取り専用 MCP サーバー。Cursor、Codex、CI、あらゆる MCP クライアントから利用可能

テスト済みのテスター

テストされていない QA エージェントは、まさに自らが退けるべき主張です。 eval/ は、決定論的なスコアラーを備えた採点付き評価スイートです。 score.py は文章ではなく状態ファイルを読み取り、主要な主張を支える 4 つを含む 8 つのフィクスチャがあります。

• Baseline（fixtures/pricer）：5 つすべての失敗分類を網羅する、シード済みの課題が 8 件あります。「一時的に」スキップされたテストに隠れた境界値の不具合や、意図を示す引用が CHANGELOG にある古い期待値も含まれます。 解答。
• Delta（fixtures/pricer_rev_b）：このツールの目玉を採点します。作成済みの run-2 履歴を使った実行では、REGRESSED（最優先）、NEW、STILL_OPEN、RESOLVED を出し、期限切れの隔離を解除する必要があります。その一方で、CHANGELOG のおとりが、新たな不具合を意図されたものだと見せかけようとします。 解答。
• Liar（fixtures/liar）：敵対的な状況での誠実さを検証します。常に「ALL TESTS PASSED」と出力するテストスクリプト、スイート全体をスキップ扱いにする conftest、自身の戻り値を検証するモック、同語反復的なアサーションが含まれます。判定が出力を鵜呑みにしているかを採点します。
• Spec（fixtures/refund-spec）：シフトレフトを検証します。矛盾、測定不能な要件、境界値ちょうどの曖昧さ、明示されていない失敗経路の不足を仕込んだドラフト PRD と、仕様に矛盾する CHANGELOG が含まれます。コードが存在する前に /verdict:spec がすべてを見つけられるかを採点します。

python3 eval/run_eval.py --mode seeded|live|baseline を実行すると、分離された一時リポジトリと一時状態ホームですべてを実行します。結果は測定どおりに公開され、見逃しや解答の修正もすべて表に記録されます（eval/README.md）。

これらの解答はすべて、プロンプトを書いた本人たちが作成しました。外部の解答（eval/swebench.py）は、ここにいる誰も選んでいないものです。SWE-bench Verified のインスタンスは実際の不具合であり、それぞれのメンテナーが修正し、修正前には失敗するテストを用意しています。対象は、セット内で最も小さい 5 つのリポジトリ（pytest、pylint、requests、seaborn、flask）の全インスタンス（40 件）です。チェックアウトの履歴は不具合のベースコミットで終わり、環境はその週にメンテナーが使っていたものと同じです。非公開のテストはツリーに入らず、課題文が唯一の指針です。スコアは決定論的な位置判定です。指摘に記載された path:line が、修正対象ファイルの修正箇所内かつ同じ関数内にあるかを判定します。率、時間、トークン数、すべての見逃しは台帳に記録されています。

状態モード

• Solo（デフォルト）： 状態は ~/.claude/verdict/<repo-name>/ に保存されます。リポジトリには何も追加されません。
• Team： リポジトリに .qa/ を作成し（/verdict:baseline team）、コミットします。チームメイトと CI が同じベースラインを共有し、QA レポートもコードとともに管理できます。

状態スキーマについては docs/state-schema.md に記載されています。バージョン管理され、前方互換性があり、人間にも読みやすい JSON です。

コマンド

プラグインのコマンドにはプラグイン名の名前空間が付いており、完全な形式で入力する必要があります — /verdict:run、 /verdict:status。短縮形はありません。単独の /verdict は未知のコマンドとして扱われ、 推測ではなく実測によって確認されます。

まずはこちら： /verdict:run — 入口となるコマンドです。テスターのメモリーを読み取り、適切なパスを自動的に選びます。状態がまだない場合 → ベースライン、状態がある場合 → 本日の差分、引数が指定された場合 → 指定された内容に絞った差分です。どれを選んだか、その理由も示します。以下の各コマンドは、同じ仕組みを特定の作業に向けたもので、実行したい作業がすでに決まっている場合に使います。

コマンド	内容
/verdict:run	入口 — 保存された状態に基づいて、ベースライン、差分、または範囲を絞ったレビューに振り分けます
/verdict:baseline	QA ルート、プロジェクトプロファイル、ベースライン状態を初期化します
/verdict:regression	回帰チェックリスト：変更箇所 → 隣接するフロー → インテグレーション
/verdict:release	4 つの判定契約に基づくリリースゲート
/verdict:bug	症状／ログ／苦情を分類済みの構造化されたバグレポートに変換します
/verdict:flake	間欠的な失敗を分類します：3 回以上の再現、メカニズムの調査 → BRITTLE_TEST 修正タスク、または期限付きの FLAKY 隔離
/verdict:status	保存された状態の読み取り専用ステータス — 実行なし、書き込みなし、エージェントの起動なし
/verdict:spec	シフトレフト：コードが存在する前に、仕様書／イシュー／PRD のテスト可能性を評価します — 矛盾、測定不能な項目、未定義の境界、見落とされたギャップ、履歴との競合に加え、Given/When/Then の基準も確認します
/verdict:cause	失敗の根本原因を追跡します：症状 → メカニズム → 起点 → クラス。各リンクを引用し、説明を並べるのではなく反事実によって因果関係を証明します。トリガー、原因、潜在条件は分けて扱います
/verdict:charter	プロファイルのインシデント履歴からリスクの重点を定める、時間制限付きの探索的チャーターです。観察事項を証拠として記録し、発見事項をバグレポートおよび回帰候補に変換します

MCP 経由でテスターの記憶を参照（任意）

Verdict の状態はエージェント内に閉じ込められていません。verdict-mcp は、同じ状態ファイルを参照する小規模な読み取り専用の MCP サーバーです。そのため、マージを承認するオーケストレーター、Cursor や Codex のセッション、PR にコメントする CI ステップなど、MCP に対応するあらゆるものが QA の記憶を参照できます。

ツール	返される内容
get_verdict(project)	最後の判定、リリースブロッカー、レポートのパス、未テスト項目の一覧
get_findings(project, status)	open（デフォルト）、all、または NEW / STILL_OPEN / RESOLVED / REGRESSED — REGRESSED を最初に表示
get_quarantine(project)	不安定なテストの台帳。各項目に expired フラグが計算されます
get_questions(project)	テスターが人に確認するために保留した質問と、それぞれの経過日数、およびどの実行にもまだ読み取られていない回答 — verdict-answer で回答できます
get_history(project)	レポートの INDEX を解析した、実行ごとの推移
get_report(project, report?)	レポートの全内容（デフォルトは最後の実行のもの）— QA ルートへのパスが制限されているため、CI ステップで証拠にリンクするだけでなく、引用できます
get_profile(project)	プロジェクトの QA プロファイル：分離ルール、リスク領域、実際のテストコマンド — さらに、存在する場合は教訓の台帳
get_trends(project)	INDEX から取得した実行ごとの推移、現在の負荷状況（重大度別の未解決件数、経過日数の分布、隔離件数、所要時間）、およびホットスポット — このプロジェクトの不具合が実際に集中している箇所を、プロジェクト固有の検出結果から算出し、ランキングの根拠となる実行回数も表示します
list_projects() / get_state(project)	ベースラインのあるすべてのプロジェクト / 状態の生データ

claude mcp add verdict -- uvx --from verdict-qa-mcp verdict-mcp

配布パッケージ名は verdict-qa-mcp です。コンソールスクリプトとインポートパッケージの名前は引き続き verdict-mcp / verdict_mcp です。PyPI のインデックス上での名前だけが異なります。これは、そこで verdict-mcp が無関係なプロジェクトに使われているためです。リポジトリから直接インストールすることもでき、リリースを待つ必要はありません。 uvx --from git+https://github.com/ArtJack/verdict verdict-mcp

project は、単独モードではルート（~/.claude/verdict/。VERDICT_HOME で上書き可能）のキー、チームモードではリポジトリのパスです（<repo>/.qa/ に解決されます）。すべてのツールに読み取り専用の注釈が付いており、サーバーが書き込みを行うことはありません — テスターの記憶は公開 API ですが、テスターのペンは公開 API ではありません。 uv（または pipx install verdict-qa-mcp）が必要です。プラグイン自体は引き続き依存関係がゼロで、サーバーなしでも動作します。

ループを閉じる（テスターには修正させない）

Verdict は修正ループのゲートであり、決して実行者ではありません。修正してから自分の修正を再評価するエージェントは、自分の宿題を自分で採点しているようなものです。ループを担うのはオーケストレーター、コーディングエージェント、または CI です。Verdict の役割は、ループを一周するたびに、根拠を引用させ、安易な承認を不可能にすることです。

┌─────> implement the ordered fix list   (you / your coding agent)
│                    │
│                    v
│        /verdict:run — delta run        (scoped by diff, findings aged)
│                    │
│                    v
│        get_verdict over MCP ────────── pass ──> merge
│                    │                            (the not-tested list travels with the PR)
└──────── fail · pass with risks
          (fix order is dependency-aware, REGRESSED first)

最小限のドライバー。任意の MCP クライアントで使用できます。

while True:
    before = mcp.call("verdict", "get_verdict", {"project": "myapp"}).get("run_number") or 0
    subprocess.run(["claude", "-p", "/verdict:run delta pass on myapp"])   # the agent runs
    v = mcp.call("verdict", "get_verdict", {"project": "myapp"})          # the gate reads
    assert (v.get("run_number") or 0) > before, "run died before writing state — not a verdict"
    if v["verdict"] == "pass":
        break
    fix(v["release_blockers"],
        mcp.call("verdict", "get_findings", {"project": "myapp", "status": "open"}))

（run_number のチェックは重要です。これがないと、状態を書き込む前にクラッシュした実行で、昨日の verdict が再利用されます。昨日が合格だった場合、未レビューのコードがマージされてしまいます。verdict-gate --min-run-number でも CLI と同じチェックを行えます。）

ループを誠実に保つルール。希望に頼るのではなく、すべてエージェントの契約で強制されます。

• REGRESSED はループを明確に停止させます。 再発した指摘は NEW の指摘がいくつあっても優先され、すべてのレポートと get_findings の応答で最初に表示されます。
• テスト失敗は正しい経路で解消します。 STALE_EXPECTATION は意図の引用を伴うテスト更新タスクで解消し、REAL_DEFECT はコード修正で解消します。ループが赤いテストをコードに合わせて編集することで収束することはありません。
• 不安定なテストを埋もれさせません。 隔離されたテストはゲートの対象外になりますが、期限切れになると再び対象に戻るため、スキップを重ねて合格にたどり着くことはできません。
• blocked は停止を意味し、合格ではありません。 環境が不足している場合、判定にすり替えるのではなく、オペレーターの対応が必要な状態でループを停止します。
• クラッシュした実行は判定ではありません。 ゲートは run_number が進んでいることを確認します。古い状態は独自の終了コード（5）となり、合格とも不合格とも区別されます。

これは仮定の話ではありません。作者のプライベートなデプロイ環境で、実運用中のコードベースに対して毎晩無人で実行しているループです。

指摘が引用する内容に変更がない夜には、verdict-run --skip-unless-drift がモデルを実行する代わりにスイープを確定します。前回の判定を ID で引き継ぎ、モデルによる署名は付けず、実行番号を進めます。また、実行できない場合はその理由を出力します。条件はハーネス独自の測定結果に基づきます。引用された各行の位置が変わっていないこと、すべてのゲートが合格していること、テスト ID のセットに変更がないこと、期限を迎える隔離テストがないことです（docs/nightly.md）。

CI：テスターの記録に基づいて PR をゲートする

このリポジトリは、複合 GitHub Action としても機能します。ゲートモードでは API キー、インストール、モデルは不要です。標準ライブラリのみを使うスクリプトが、コミット済みのチームモード .qa/ 状態を読み取り、ジョブのステータスを設定し、PR に固定コメントを 1 つ維持します（判定の見出し、ブロッカー、REGRESSED を最初に表示する指摘の表、未テストの項目）。

permissions:
  pull-requests: write
concurrency: verdict-${{ github.ref }}

steps:
  - uses: actions/checkout@v4
  - uses: ArtJack/verdict@v0
    with:
      max-age-hours: 48        # a stale verdict is exit 5, never a pass
      max-commits-behind: 0    # ...and so is one measured before these commits

実行モード（実験的）では、まず Verdict をヘッドレスで実行します。GitHub ホストランナーでは anthropic-api-key を使用し、claude setup-token で取得した claude-oauth-token を使うセルフホストランナーでは、API の利用料金ではなくサブスクリプションで夜間 QA を実行できます（anthropic-base-url を指定すると Anthropic 互換ゲートウェイに引き継がれます）。同じ契約は CLI としてどこでも利用できます。

verdict-gate myapp --max-age-hours 24 --max-commits-behind 0 --fail-on risks

終了コード：0 合格 · 1 不合格 · 2 使用方法 · 3 ブロック · 4 状態なし（テスターが実行されていない） · 5 古い状態 · 6 手書きの状態（--require-harness を指定した場合）。4 と 5 は、意図的に 1 と区別されています。「テスターが実行されていない」ことが、「テスターが否定した」ことのように見えてはなりません。夜間実行を自分のマシンで行う方法（cron、systemd、サブスクリプショントークン、厳格モード）については、docs/nightly.md を参照してください。

--format sarif を指定すると、未解決の指摘が SARIF 2.1.0 形式で出力されます（重要度 → レベル、file:line の根拠から解析した位置情報）。GitHub の Security タブにアノテーションとして表示できます。

- run: verdict-gate --format sarif > verdict.sarif || true
- uses: github/codeql-action/upload-sarif@v3
  with: { sarif_file: verdict.sarif }

テスターにプロジェクトを見せる（MCP はご自身で用意してください）

エージェントに付属するのはコアツールのみですが、フロントマターは拡張ポイントです。agents/verdict.md をプロジェクトの .claude/agents/ にコピーし、プロジェクトの MCP ツール（データベース、ステージング API、ブラウザー）を tools: リストに追加します。エージェントがそれらをどのように使用できるかは、§0 の分離ルールに従います。事実の読み取り専用に限り、変更は一切行わず、検証できない場合は blocked とします。このパターンは実戦で検証済みです。このエージェントの非公開の前身は、読み取り専用のマーケットプレイスデータベースツールを 11 個使って毎晩実行されており、それによって、ソースコードをいくら読んでも見つけられなかった実際の過剰販売バグを検出できました。

動作例 — Playwright MCP に接続したウェブアプリ：

# your project's .claude/agents/verdict.md, frontmatter tools:
tools:
  - Read
  - Glob
  - Grep
  - Bash
  - Write
  - mcp__playwright__browser_navigate
  - mcp__playwright__browser_snapshot
  - mcp__playwright__browser_click
  - mcp__playwright__browser_console_messages

…そしてプロファイルには運用ルールが記載されています。テスト環境のオリジン（本番環境は絶対に使用しない）、テスト用アカウント、また、ナビゲーション、スナップショット、読み取りは対象範囲内であり、送信、支払い、アカウントの変更を行う操作は禁止されていることです。§0 は Bash と同じようにブラウザーツールにも適用されます。クリックで変更が発生するかどうかわからない場合は、変更が発生すると判断し、クリックせずにリスクを報告してください。探索的チャーター（§4、手法 23）もそのまま適用できます。リスクに焦点を当てた時間制限付きのブラウザーセッションを行い、観察結果を証拠とし、再現可能な失敗をバグ報告にします。

モデルは判断し、システムは測定する

状態ファイルの約 3 分の 2 は、タイムスタンプ、SHA、差分範囲、ゲートの終了コード、所要時間、テスト件数、検出事項のハッシュ、経過日数、差分といった、算術と転記で占められています。これらに判断は一切必要ありませんが、どれも自信満々に誤る可能性があります。

そこで実行を分割します。verdict-facts が測定を担当します。指定されたゲートを実行して所要時間を測り、件数を解析し、Git を読み取り、プロジェクトキーを導き出し、run_number と run_type を決定します（実行を再ベースラインとして宣言し直す必要がある場合も含みます）。次にエージェントは判断のみを記述します。立証された時点で各検出事項を個別ファイルに記録し、書き込みながら検証します。確認した結果、変化がない検出事項は ID として記録し、判定と未テスト項目も記録します。verdict-finalize はファイルを組み立て、各検出事項のハッシュ、first_seen、age_days、および前回の状態からの NEW/STILL_OPEN/RESOLVED/REGRESSED の差分を計算します。また、証拠が示すすべての行をハッシュ化し、次回の実行時にコードが移動した場所を把握できるようにしてから、結果を検証し、すべてが完了した後に書き込みます。

verdict-finalize はレポートのレンダリングも行います。同じ状態からスコープ、ゲート、REGRESSED を先頭にした検出事項の表、未テスト項目、隔離対象を生成し、エージェントの文章（リスク、修正順序、検出事項ごとの説明）を挿入します。レポートはハーネスが書き込むため、欠落することはありません。また、状態そのものを基にするため、状態と矛盾することもありません。

モデルが正しく計算できないものを、モデルに計算させることはありません。

テスター自身の誤り率

指摘の価値は、テスターの実績が示す価値に基づきます。Verdict はその実績を保持します。ここでの設計原則は他のすべての箇所と同じです。モデルが甘く評価したくなる部分には、モデルが触れられないようにします。

各指摘には、報告時点での確信度を記録します。proven（実際に発生することを実証済み）、probable（追跡済みだが実行はしていない）、hypothesis（疑いがある）から選びます。バリデーターは、確信度のない新しい指摘を受け付けず、ハーネスはこれを固定します。後続の実行で結果を見たあとに予測を修正することはできません。

結果は計算されるものであり、申告するものではありません。 リグレッションが発生した指摘、または欠陥を再注入してガードの失敗を確認することで修正を検証した指摘は、的中と判定されます。テスターが取り下げた指摘は的中しません。それ以外はすべて未確定のままとなり、どの率からも除外されます。検証されていない解決は、証拠ではなく不在を意味し、未解決の指摘は何も確定していないためです。判定済みの結果は outcomes.json に保持されます。state.json では2回前の実行で解決した指摘が削除され、そうしなければサンプルがいつまでもリセットされてしまうためです。

レポートには「実績」セクションが追加されます。このプロジェクトが追跡した指摘の数、判定済みの数、確信度別と証明方法別の件数が示されます。パーセンテージが表示されるのは、各区分で判定済みの結果が30件に達してからです。それまでは、装飾にすぎない「67%」ではなく、事実を示す「3件中2件」と表示されます。

リスクを受け入れる — メンテナーの決定

正しい指摘であっても、修正されないものがあります。評価して決定ログに記録された残存リスクや、廃止予定の機能に潜む欠陥などです。open のままにしておくと、プロジェクトが続く限り、バナーには未解決の Major として毎回再報告されます。これは、このツールが防ごうとしている「読み続ける気が失せるまで、同じ指摘が20件並び続ける」問題です。一方、withdrawn にすると、正しい指摘をテスター側の誤りとして扱ってしまいます。そのため、4つ目のステータスがあります。ただし、テスターはこれを書き込めません。

verdict-accept myapp MYAPP-F-021 --cite "DECISIONS.md 2026-09-02" \
    --reason "deleting the ledger too defeats the anchor; the cost is the whole track record"

これにより、QA ルートの outcomes.json と同じ場所に accepted.json が書き込まれます。このファイルはスコープガードによってエージェントから保護され、このステータスはバリデーターによって判定で拒否されます。この指摘はすぐに未解決件数から除外され（バナー、verdict-gate、MCP サーバー）、次回の実行では判定から除外されます。また、引用元とともにすべてのレポートの 受け入れ済みのリスク に表示され、測定済みおよび申告済みの確認とは別に、メンテナーの判断に基づいて confirmed として実績に記録されます。--revoke は理由を添えてこれを取り消し、--list は台帳を表示します。決定が変えるのは次回の判定であり、直前の判定ではありません。

人の判断でしか決められないもうひとつのことが、質問です。; は今でもクエリーセパレーターなのか、単一ファイルでのベンダリングはサポート対象なのか、ゲートはインストール済みの wheel に対して実行すべきなのか。テスターが質問を保留すると（判定の questions に記録し、finalize が MYAPP-Q-3 を付与して questions.json に保存します）、2つ目の決定を記入します。

verdict-answer myapp MYAPP-Q-3 --answer "at or above is the rule; README rule 1 is the spec"

これにより answers.json が書き込まれ、accepted.json と同様にエージェントから保護されます。次回の実行では、事実情報の中に決定が読み込まれ、同じ質問が再び出されることはありません。レポートでは台帳に基づいて 人の判断が必要 と表示され、セッション開始時のバナーと verdict-gate には、回答待ちの件数が表示されます。質問をメールで送ることも、課題として登録することもありません。あなたが目にするすべての画面に表示され、そこに残ります。

3つ目の決定は、テスターを検証します。実証済みの Major 以上の指摘には repro が付属します。これは欠陥を示す1つのコマンドと、その実行結果です。verdict-replay myapp は、テスターのプローブによる変更が何も存在しない HEAD の独立したワークツリーで、該当するすべてのコマンドを実行します。

verdict-replay myapp              # every open Major+ finding with a repro; --show lists the commands first
verdict-replay myapp MYAPP-F-3    # one finding

それぞれの結果は、署名対象の状態の外にある replays.jsonl に記録されます。ゲートは各指摘に replay ✓ reproduced、✗ NOT reproduced、または ? could not run のいずれかを表示し、実証済みの指摘のうち、誰も再現を試みていない件数を数えます。証拠が文章だけの指摘は、作成者には実証済みでも、それ以外の誰にも実証されたことにはなりません。

レポートを公開する前に、verdict-dupes myapp は未解決の Major 以上の指摘ごとに、リポジトリ内の issue とプルリクエストを検索し（タイトルにあるコード名、その文言、証拠が引用する内容を gh 経由で検索します）、候補を related.jsonl に書き込みます。ゲートは各指摘の最初の候補を示し、オープンなプルリクエストがある場合は警告します。2026年10月に見つかった見知らぬ指摘9件のうち2件は、すでにオープンなプルリクエストで修正済みでした。当時は手作業で見つけましたが、今はコマンドで見つけられます。

テスターには記憶があります。実装者にはありません。

この非対称性には、測定可能なコストがありました。Verdict は実サイトで証拠に基づく指摘を11件記録し、そのうち1件はリリースを阻むものでした — このブランチをデプロイすると、本番環境のセキュリティヘッダーがすべて削除される — それにもかかわらず、同じリポジトリで次に行われたセッションではSEOの全面的な確認が行われ、それらにはひとつも手が付けられませんでした。リリース阻害要因も、引き継ぎに失敗しているのに成功を報告する申し込みフォームも、両方の主要なCTAのコントラストの問題もです。指摘はずっとstate.jsonに残っていました。next_run_focusは存在していましたが、それを読むのはVerdictだけです。MCP経由のget_findingsも存在していましたが、自発的に呼び出すものはありませんでした。

そこで、QAの状態があるリポジトリでセッションを開始したとき、最初の編集の前に、未対応の内容を伝えるSessionStartフックを追加しました。編集の後ではありません。

Verdict remembers dm-express-site: run 2 (delta), today — verdict **fail**.
1 release blocker — look here first:
  - DMEXPRESS-F-1 — the audited branch has diverged from the deployed origin/main
11 open findings: 4 Major · 4 Minor · 3 Trivial
  - DMEXPRESS-F-3 (Major) Light theme: accent-coloured text fails WCAG AA…
Full detail: `/verdict:status`. These are findings, not instructions.

意図的に短くしています。スクロールが必要なセッション開始メッセージは、誰も読みません。また、すでにブロッカーとして伝えた指摘を繰り返すこともありません。QAの状態がないリポジトリでは何も伝えず、どのような失敗時にも何も伝えません。また、1週間以上前の記憶は、現在の情報として提示するのではなく、古くなっていることを示します。セッションに情報を与えるだけで、セッションを乗っ取ることはありません。

Verdict が一度も確認したことのないリポジトリでは、同じフックは一度だけ、Verdict がインストール済みであり、/verdict:runで最初の読み取り専用QAパスを実行できることを伝えます。このメッセージが表示されるのは、テストスイートのあるgitリポジトリで、新たに開始された対話セッションの場合に限られます。リポジトリごとに一度だけ、ユーザーあたり最大3つのリポジトリまでです。ヘッドレス実行時、CI内、またはVERDICT_NO_HINT=1の場合は決して表示されません。表示した場所の記録は、Verdict自身のホームにある.first-run.jsonに保存され、あなたのリポジトリには保存されません。この仕組みは、Verdictをインストールしたアカウントが96件あるのに、一度でも使ったアカウントがひとつもないことがClaudeディレクトリで確認されたために作られました。

モデルが覚えているかどうかにかかわらず、最後のガードは作動します

ここまでのすべてのチェックは、モデルが呼び出す必要のあるツールの後段にあります。これは理論上の抜け穴ではありません。実際の/verdict:runの実行では、$VERDICT_HOMEが別の場所を指していたにもかかわらず、デフォルトの状態ルートに書き込みが行われ、プロジェクトキーが捏造され、ハーネスが丸ごと省略されたうえで、もっともらしい、自信に満ちたFAILが出力されました。verdict-validateならその状態を拒否し、verdict-gate --require-harnessなら終了コード6で終了していたでしょう。しかし、どちらも実行されませんでした。呼び出すものがなかったからです。

（以前は偽造ではなく、模倣によってこのチェックを回避できました。永続的なシグナルは、dictを値に持つキーと固定のフッター文字列の2つで、どちらもコミット済みの成果物からそのままコピーできました。Verdictは自身の監査によってこの問題を見つけました。現在は各実行が、ひとつ前のリンクのハッシュで実行履歴に署名し、その署名を状態に記録します。リンクをコピーしても検証は通らず、署名後に状態を編集した場合も同様です。）

そこでStopフックを用意しました。ターンの終了時にひとつだけ問いかけます — QA実行の直後に、手書きの状態がディスクに残されたか？ — もし残されていたら、停止を一度だけブロックし、やり直す内容を伝えます。モデルがチェックをするかどうかを決めるときではなく、ターンの終了時に作動します。

このフックは有効になっているすべてのセッションのすべてのターンの終わりに実行されるため、作動条件は意図的に厳しくしています。そのターンがすでにこのフックによって継続中であってはなりません（ループは起こしません）。セッションのcwdからQAルートを解決できる必要があり、そのstate.jsonは直近30分以内に書き込まれていて、ハーネスのトレースが欠落していなければなりません。それ以外の場合は、stat呼び出し約2回で終了します — 実測値は37 msです。入力を解析できない場合、インポート先を解決できない場合、状態を読み取れない場合を含め、すべての失敗パスで何も出力せずに終了します。セッションを停止させるフックは、それが監視する問題よりも悪質です。

状態の契約は機械的にチェックされます

プロンプトに文章でルールを書けば、モデルが値を捏造する頻度は下がりますが、捏造できる値を捏造するのを防ぐことはできません。ここでの実測結果です。date -u を明示的なルールにしてから数か月後も、本番のタイムスタンプ4件中2件は秒がちょうど :00 でした。下流のすべての利用者が信じている状態で、ひそかに捏造されていました。

そこで、契約は文章での説明をやめ、ゲートになりました。verdict-validate は、すべての state.json 書き込み時に PostToolUse フックとして実行され（CI では CLI としても実行され）、次のいずれかに該当する状態を即座にセッション内で報告します。report に実在するファイルへのパスではない値が指定されている · 測定値ではなく記憶に基づいたタイムスタンプが含まれている · クラッシュした実行のまま run_number が更新されていない · 列挙値が捏造されている · 未解決の Critical があるのに pass とされている · 根拠のない未解決の検出事項が登録されている · 期限のないテストが隔離されている。

本番で稼働中の4つの状態に対する初回の実行では、そのうち2つに違反が見つかりました。その中には、プロンプトのルールでは3回にわたって防げなかった、まったく同じ回避策（report フィールドの "delivered inline to the caller…"）も含まれていました。ここにあるすべてのルールは、実際の実行で問題が発生したことを受けて作られました。

読み取り専用の保証について、正直に説明します

4 つのレイヤーがあります。（1）エージェントには Edit ツールがありません。（2）その契約により、Write は QA ルート内に限定されます。（3）PreToolUse フックが、対象範囲外への Write／Edit 呼び出しをブロックします。（4）もう 1 つのフックが、よく使われる Bash の書き込み経路を塞ぎます。具体的には、出力リダイレクト（>、>>、&>、>&file、N<>）、tee、sed -i／perl -i、rm／mv／cp など、変更を行う git のサブコマンドと、読み取り用サブコマンドの --output、書き込みを行う形式のフォーマッター（black .、ruff format、prettier --write）、インプレース圧縮ツール、find -exec と xargs でこれらを実行するものです。それぞれの対象パスは QA ルートを基準に解決されます。両方のフックは、プラットフォームが呼び出し元として判定エージェントを指定した場合（Claude Code はサブエージェント内で発生するすべてのフック入力に agent_type を含めます）、および VERDICT_STRICT=1 の場合に有効になります。ヘッドレス実行、CI、スケジュール実行では、セッション全体が QA 実行そのものとなるため、この設定が適用されます。ご自身による編集やシェル操作は保護されません。エージェントを示す情報がないイベントは、厳格モードでないセッションではそのまま通過します。ただし例外が 1 つあります。メンテナーの台帳（accepted.json、answers.json）は verdict-accept と verdict-answer だけが書き込めます。誰が要求しても、これらへの Write や Edit は拒否され、テスターによるこの 2 つのコマンドの実行も拒否されます。

ハーネス自体の書き込みにも同じ制限が適用されます。facts.json、状態、レポート、実行インデックス、台帳は、QA ルート内の指定された場所に書き込まれます。そのため、何かを作成する前に、verdict-facts、verdict-finalize、verdict-local、メンテナー用コマンドはルートの場所を確認します。ソロ用ホーム、チェックアウトの最上位にある .qa/ 内またはその配下、あるいはチェックアウト外がルートとして認められます。それ以外のチェックアウト内の場所はコードとして扱われます。また、ルート直下、reports/、findings/ にシンボリックリンク、ジャンクション、または 2 つ目のハードリンクを持つファイルがある場合、そのルートは拒否されます。リンクを介した書き込みは別の場所への書き込みになるためです。レポートは reports/ 直下に置かれる単一の通常ファイルであり、実行インデックスにはなりません （tests/test_qa_root_links.py）。

Bash ガードはコマンド文字列に対するヒューリスティックであり、サンドボックスではありません。2026-10-02 の監査で、その限界が明らかになりました。このガードは、プログラム自身のコードを通じて書き込む処理を止めません。たとえば、インタープリター（python3 -c、node -e）、ビルドやパッケージ処理（pip、npm、cargo、pytest 独自のキャッシュや .coverage）、タスクランナー（npm run format、make fmt）、ファイルやパイプから読み込んだスクリプト、シェル関数、エイリアスなどです。QA の実行には pytest、カバレッジツール、リンターが必要なため、未知のコマンドは実行されます。実際の境界は、OS レベルのサンドボックスを使うこと、またはテスターを使い捨てのコピーに対して実行することです。このガードは、うっかりした変更のコストを引き上げます。フック入力の形式が不正な場合は、処理を許可します。いったん有効になった後は、ガードが読み取れないコマンドは許可せず、拒否します。CI では Python 3.9 でテストしています。これは標準状態の Mac がこれらのフックを実行する際に使う python3 です （tests/test_hooks.py、tests/test_hooks_0903.py、tests/test_hooks_pens.py、tests/test_hooks_links.py）。これがすべてです。QA ツールは、自らの制御機能を誇張すべきではありません。

FAQ

モデルの料金は誰が支払いますか？ ご自身でお支払いいただきます。すでにお持ちの Claude サブスクリプションを使うため、作者を経由することはなく、API キーも不要です。キーが使われる可能性があるのは、任意の GitHub Action の実行モードだけです。その場合も、ご自身のリポジトリで CI に使用する、ご自身のキーです。モデルより下の部分は、すべて通常のファイルと Python 標準ライブラリです。

ローカル LLM で実行できますか？ コストの低い順に、3 つの答えがあります。モデルをまったく使わない場合： verdict-run --skip-unless-drift は、指摘の根拠となっている内容に変更がない夜には、前回の判定を引き継ぎます。2 秒で完了し、その旨を伝えます。小規模なローカルモデルの場合： verdict-local は制御の流れを逆転させます。ハーネスが計測し、コードを切り出してスクラッチコピー内で主張を検証し、モデルは一度に範囲を限定した質問に 1 つだけ答えます。LiteLLM と Ollama 経由の qwen3:8b で計測した結果は、ベースラインフィクスチャで 9/10・9/10・10/10、1 回あたり約 30 回の呼び出しと 7,000 入力トークンでした。0.90.0 以降は初回チェックだけでなく差分にも対応し、すでに状態があるプロジェクト上でも安全に動作します。以前の未解決の指摘はすべて、誰かが選んだテストで計測された fail→pass によって解決されるか、変更の原因となったドリフトとともに、それぞれの ID で再登録されます。ハーネスは沈黙を解決と見なすため、何も言及されない指摘が残ることはありません。判定は単調に変化します。悪化させることも、そのまま維持することもできますが、判断力のある人が確認するまでは、fail と blocked のどちらもそのまま残ります。使い捨ての --qa-root と併せて --range／--base を使えば、プロジェクト自体の状態に触れずにブランチを判定できます。また、Python を含まない範囲を指定した場合は、何も読み取らずその旨を伝え、クリーンな合格として報告することはありません。verdict-run --on-drift local で夜間実行に組み込めます。このコマンドが claude CLI に到達することは決してありません。 ゲートウェイ経由のフルエージェント（verdict-run --env-file、ANTHROPIC_BASE_URL → LiteLLM → ご自身のモデルサーバー、docs/nightly.md）には、CLI 独自のプロンプトに加えて 12,000 トークンの契約を収められるコンテキストウィンドウを持つモデルが必要です。4k で提供される 8B モデルでは足りません。どのモデルが判定に署名できるかは評価の結果で決めるものであり、既定値で決めるものではありません。誠実さのフィクスチャでは Sonnet が Opus と同点で、根本原因の特定でも n=3 で同等でした。また、状態を書き込まなかった実行が 1 回ありました（モデル軸：Opus と Sonnet のペア比較）。実行してスコアを公開し、そのうえで判断してください。

なぜ見つけたバグを修正しないのですか？ 独立性を保つためです。コードにパッチを当てたエージェントが、そのコードを正常だと宣言するのは、自分で自分の宿題を採点するようなものです。Verdict は、実行する人（またはコーディングエージェント）が使える、順序付きの実装可能な修正リストを返します。

CI の代わりになりますか？ いいえ。CI の上に位置するものです。CI はテストスイートが失敗していることを知らせます。Verdict は、失敗のうちどれが重要か、何を意味するのか、前回の実行から何が退行したのか、そしてそのままリリースできるかどうかを知らせます。

スケジュール実行やヘッドレス実行に対応していますか？ はい。そのために状態ファイルがあります。夜間に実行し、毎回新たに監査するのではなく、コーヒーを飲みながら差分レポートを読めます。

ロードマップ

• ローカルファーストのトラック（このプロジェクトが当初目指していた方向）：agent-skills-standard 版。プロンプト、手法カタログ、状態コントラクトをポータブルな Markdown にすることで、Claude 以外のランタイムにも対応できるようにします。これに加えて、ローカルモデルの実験として、Anthropic 互換ゲートウェイを通じてローカルモデルで評価スイートを実行し、スコアを公開します。夜間実行を任されるモデルは、ほかのモデルと同じ評価に合格する必要があります。
• Python 版に加えて JS/TS の評価フィクスチャを追加
• ツールが利用可能な環境でミューテーションテストを統合

ライセンス

MIT