mcpField
S
surrogate-verifier

surrogate-verifier

github.com/mathews-tomテスト・品質33776 回インストール2 日前に更新
リポジトリ

surrogate-verifier について

スキル定義、タスクのプロンプト、出力をもとに、構造化されたアサーションと失敗診断を生成する検証スキルです。生成側の推論を隔離して検証バイアスを抑えますが、アサーション自体は実行しません。

主な機能

  1. 01タスクごとに5～10件のアサーションを生成
  2. 02完全性・形式・事実上のシグナルを確認
  3. 03失敗を根本原因別に分類
  4. 04実行可能な修正案を提示
  5. 05テストを実行せずテキストを検証

活用シーン

  1. 01スキルパッケージの評価用アサーションを生成
  2. 02失敗したアサーションから定義やワークフローの問題を特定
  3. 03隔離されたコンテキストで Agent の出力を検証

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/mathews-tom/armory --skill surrogate-verifier

インストール後、Claude Code で/surrogate-verifierを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

evals/
cases.yaml
references/
assertion-patterns.md
diagnostic-templates.md

詳細

Surrogate Verifier

情報を隔離した検証を通じて、スキルパッケージ向けの構造化されたテストアサーションと失敗診断を生成します。検証器はスキル生成器の推論にアクセスせずに動作します。スキル定義、タスクプロンプト、出力成果物のみを参照します。この隔離により確証バイアスを防ぎ、共進化型生成におけるスキル品質の向上（EvoSkills によると +30pp）に最も大きく貢献します。

参照ファイル

ファイル内容読み込むタイミング
references/assertion-patterns.mdスキルカテゴリ別のアサーションカタログと重み付けの指針常に
references/diagnostic-templates.md根本原因カテゴリ別の失敗診断テンプレート失敗レポートを作成するとき

情報隔離プロトコル

これは最も重要な制約です。隔離に違反すると、検証品質が低下します。

検証器は以下にアクセスしてはなりません：

  • 生成器の会話履歴や推論チェーン
  • 以前の進化イテレーションや改善のコンテキスト
  • 生成器の内部メモや判断理由
  • 以下に明示されているもの以外のコンテキスト

検証器が受け取るのは以下のみです：

  1. スキルのSKILL.mdの内容（定義ファイル）
  2. 想定される用途を表す1つ以上のタスクプロンプト
  3. スキルの出力（失敗診断時）
  4. scripts/eval_assertions.pyによるアサーション結果（失敗診断時）

実装： test-engineerエージェントによって呼び出される場合、このスキルはisolation: "worktree"を使用して別個の Agent spawnに読み込む必要があります。最低限、共有コンテキストのない新しいセッションを使用してください。呼び出し元エージェントは、会話中の参照ではなく、成果物を明示的なテキストとして渡します。

ワークフロー

モード 1：アサーション生成

スキルの定義とタスクプロンプトを基に、そのスキルのアサーションを生成します。

フェーズ 1：スキル分析

SKILL.mdの定義を読み、以下を抽出します。

  1. 明示された機能 — スキルが何を行うと謳っているか（説明とワークフローのセクションから）
  2. 出力形式 — スキルの出力に期待される構造（Markdown、JSON、表など）
  3. エラー処理 — 文書化された失敗モードと復旧手順
  4. 前提条件 — 必要なツール、依存関係、またはコンテキスト
  5. トリガーの境界 — スキルが対応しない内容（対象範囲外）
フェーズ 2：アサーション設計

各タスクプロンプトについて、次の観点を網羅する5〜10個のアサーションを生成します。

観点使用するアサーションの種類目的
出力の完全性contains、matches_regex謳われたすべてのセクションや構成要素が存在する
形式への準拠output_format、contains出力が宣言された構造と一致する
事実に関するシグナルcontains、not_contains重要な分野用語が含まれ、特徴的な兆候がない
ツールの使用calls_tool想定されたツールが呼び出された
否定的制約not_contains禁止されたパターンが存在しない

重み付け：

  • 出力の完全性に関するアサーション：重み 1.0（必須）
  • 形式への準拠に関するアサーション：重み 0.8（構造上の正しさ）
  • 事実に関するシグナルのアサーション：重み 0.6（内容の品質）
  • ツールの使用に関するアサーション：重み 0.5（手法の検証）
  • 否定的制約に関するアサーション：重み 0.3（不在チェックはシグナルとして弱い）

カテゴリ別のアサーションカタログについては、references/assertion-patterns.mdを参照してください。

フェーズ 3：出力

evals/cases.yaml のスキーマ形式でアサーションを生成します。

assertions:
  - type: contains
    target: "## Scalability"
    weight: 1.0
  - type: output_format
    target: markdown_table
    weight: 0.8
  - type: not_contains
    target: "TODO"
    weight: 0.3
  - type: calls_tool
    target: Read
    weight: 0.5

コンテキスト上限： 使用可能なコンテキストウィンドウの 70% を超えて消費しないでください。 スキルの定義が非常に長い場合は、ワークフローの各フェーズと出力形式のセクションを中心にアサーションを生成します。逐語的な引用ではなく、要約してください。

モード 2：失敗診断

オラクルが fail を返した場合、失敗の理由を説明する構造化診断を生成します。

入力
  • スキルの SKILL.md（モード 1 と同じ）
  • 実行されたタスクプロンプト
  • 失敗した出力
  • アサーションの結果：合格したもの、失敗したもの、および詳細
フェーズ 1：失敗の分類

失敗した各アサーションを根本原因のカテゴリに分類します。

カテゴリシグナル重大度
能力の欠落機能を約束している contains アサーションが失敗HIGH
形式の不一致output_format アサーションが失敗HIGH
出力の不足同じセクションで複数の contains アサーションが失敗MEDIUM
内容の捏造禁止パターンが存在するため not_contains アサーションが失敗HIGH
ツールの誤使用calls_tool アサーションが失敗MEDIUM
部分的な成功グループ内の一部のアサーションは合格し、ほかは失敗LOW
フェーズ 2：根本原因の分析

失敗した各アサーションについて：

  1. 欠落した機能を約束している SKILL.md の該当セクションを特定します
  2. スキルの定義が指示している内容と、実際の出力に含まれている内容を比較します
  3. その差が生じた原因を推測します（ワークフローのステップ不足、指示の曖昧さ、誤ったツールの選択）
フェーズ 3：修正案

各根本原因について、具体的で実行可能な修正を提示します。

  • 能力の欠落： 「フェーズ 2 とフェーズ 3 の間に、[X] を明示的に生成するワークフローのステップを追加する」
  • 形式の不一致： 「出力形式の指示を『要約を作成する』から『列 [A、B、C] の Markdown テーブルを作成する』に変更する」
  • 内容の捏造： 「ワークフローに否定的な制約を追加する：『[条件] を満たさない限り、[X] を含めない』」
  • ツールの誤使用： 「『ファイルの読み取りに Bash を使う』を『ファイルの内容には Read ツールを使う』に置き換える」
フェーズ 4：診断の出力

構造化された診断文字列を生成します。

DIAGNOSTIC: [skill-name] failed on [task-prompt-summary]

FAILED ASSERTIONS (N/M):
  1. [SEVERITY] type=contains target="..." — Missing capability: [explanation]
  2. [SEVERITY] type=output_format target="..." — Format mismatch: [explanation]

ROOT CAUSES:
  - [category]: [specific explanation with SKILL.md section reference]

REMEDIATION:
  1. [Concrete change to SKILL.md with exact section and wording]
  2. [Concrete change to workflow with step numbers]

根本原因のカテゴリごとの作成例については、references/diagnostic-templates.md を参照してください。

予算パラメーター

EvoSkills Algorithm 1 に従います。

  • コンテキスト上限： 0.7（使用可能なコンテキストウィンドウの 70%）
  • サロゲートの最大再試行回数： オラクルの各ラウンドにつき 15 回
  • オラクルの最大ラウンド数： 5 回（検証器ではなく、オーケストレーションを行うエージェントが適用します）

検証器は自身の予算を追跡しません。反復回数の上限は test-engineer エージェントが管理します。

制限事項

  • 実行機能なし： 検証器はアサーションを生成しますが、実行はしません。実行はオラクルである scripts/run_evals.py が行います。
  • テキストのみの検証： 視覚的な出力、対話的な動作、副作用は検証できません。アサーションはテキスト出力のみを対象とします。
  • 単一ターンの範囲： 各検証は独立しています。検証器は前のラウンドを記憶しません（必要に応じて、オーケストレーションを行うエージェントがコンテキストを渡します）。
  • アサーションの粒度： 5 種類のアサーションは一般的なパターンをカバーしますが、考えられるすべての検証ニーズには対応していません。カスタムのアサーション型を使用するには、scripts/eval_assertions.py を拡張する必要があります。

エラー処理

エラー解決策
スキル定義が大きすぎますワークフローのフェーズと出力形式のセクションのみに要約します
生成可能なアサーションがありません警告を付けて空のアサーションリストを返します。スキルが曖昧すぎる可能性があります
出力形式が曖昧ですcontains アサーションをデフォルトとし、output_format のチェックは避けます
コンテキストの上限を超えました診断の詳細を短縮し、失敗したアサーションのリストは保持します

コメント

Markdown 対応