wikieval

スキル：wikieval

Wiki のゴールデンを CI ゲートに変換します。低コストで決定的なアサーションでほとんどのゴールデンを判定し、コミット済みのベースラインでリグレッションを検出します。また、唯一コストの高い処理である LLM ジャッジは、単一のアダプターファイルの背後に隔離します。

WHAT

目的とコンテキスト

• 目的： Wiki のゴールデンページを、コミット済みのベースラインと、メトリクスがベースラインを下回ったときにのみ発生する CI 終了コードを備えた、純粋なコードでチェックするリグレッションテストスイートにします（モデルは使用しません）。
• 使用するタイミング：
  • エージェント（または PR）が Wiki ページを気付かれずに壊すことのないよう、Wiki ページをリグレッションテストスイートとして機能させたい場合。
  • ゴールデンの入力→期待値のペアがあり、モデルを使わずに純粋なコードでチェックしたい場合。
  • コミット済みのベースラインをメトリクスが下回ったときにのみ、ゼロ以外の値で終了する CI ステップが必要な場合。
  • ユーザーが「wikieval」「eval suite for the wiki」「regression gate for goldens」「assertion cascade」「block CI on eval drop」または /wikieval と言った場合（モデル呼び出しは無効です。ユーザーが呼び出します）。
• 対象外： LLM は呼び出しません（ティア 3 は判定されず、needs-judge として報告されます）。候補出力は生成しません（--outputs から渡されます）。ゴールデンの内容を代わりに作成することもありません。

メンタルモデル

golden (input · expected · rubric? · asserts?) + candidate output → cascade: tier 1 asserts → [tier 2 similarity] → [tier 3 needs-judge] → per-golden pass+score → baseline (write) | regression diff (check)。低コストのティアで判定できた場合は、後続のティアを実行しません。コストの高い処理は、単一のアダプターファイルの背後に置かれています。

入力と出力の仕様

	フィールド	必須？	意味
In	goldens llmwiki/wiki/sources/evals/*.md	はい	YAML frontmatter の input、expected、任意の rubric、任意の asserts、任意の id。さらに R9 type と R2 ## Origin
In	--outputs <outputs.json>	はい	ゴールデンごとの候補出力 — モデルなしでテストスイートを実行できます
In	mode	いいえ	指定なし = レポート、--write-baseline、--check
In	harness/wikieval.config.yaml	いいえ	アダプター設定（verified: false）：ジャッジモデル、ルーブリックのプロンプト、embedding.backend
Out	レポート	はい	ゴールデンごとの pass／fail／score／needs-judge
Out	harness/metrics/eval-baseline.json	--write-baseline の場合	ゴールデンごとの pass + score をコミットします
Out	終了コード	--check の場合	0 = リグレッションなし、2 = メトリクスがベースラインを下回った（リグレッション差分を含む）

ルールと機能

• RULE-01（必須）：ゴールデンに asserts が指定されている場合、合否はティア 1 のみで判定します。不明な演算子は失敗として扱います。
• RULE-02（必須）：ティア 2 の類似度判定に進むのは、ゴールデンに asserts がない場合のみです。embedding.backend が設定されていなければスキップされ、その旨が記録されます（difflib は標準ライブラリによる語彙的な比較で、オフラインで動作します。実際のモデル ID はアダプターが接続されるまでスキップされます）。
• RULE-03（必須）：決定論的モードでは、judge(output, rubric) -> {score, reason} のスタブは決して呼び出されません。エスカレーションされたゴールデンは needs-judge として報告されます。
• RULE-04（必須）：--check はコミット済みのベースラインとの差分を決定論的に確認します。終了コードが 2 になるのは、値が下がった場合のみです。
• RULE-05（必須）：アダプターの境界は 1 つのファイルです。ジャッジを完成させる場合、変更するのは harness/wikieval.config.yaml と judge() のみで、WikiEval のほかの部分は変更しません。
• 機能：ゴールデン、候補出力、アダプター設定の読み取り、ベースラインファイルの書き込み。ネットワークもモデルも使用しません。

失敗の境界

• アサーションが失敗 → ゴールデンは失敗（レポート）。--check ではベースラインとの差分があれば、終了コード 2 とリグレッション差分が発生します。
• 不明なアサーション演算子 → スキップせず、失敗として扱います。
• asserts がないゴールデンで embedding.backend が未設定 → ティア 2 をスキップし、その旨を記録します。ルーブリックによるエスカレーションは needs-judge となります（合格でも失敗でもありません）。
• --outputs ファイルが存在しない、または無効 → 実行不可：候補出力なしでは実行できません。

HOW

主なワークフロー

ステップ	種類	入力	アクション	出力／終了	失敗／次の処理
W01	決定的	ゴールデン、--outputs	ゴールデンと候補出力を読み込む	ゴールデンごとのペア	出力がない → ブロック
W02	決定的	ペア、asserts	Tier 1 の決定的アサーション	アサーションが宣言されていれば合格／不合格	不明な演算子 → フェイルクローズ
W03	決定的	ペア、設定	Tier 2 の類似度（アサーションがない場合のみ）	スコア、または「スキップ＋記録」	バックエンド未設定 → スキップ
W04	決定的	ルーブリック	Tier 3 → レポートに needs-judge を出力（ジャッジは呼び出されません）	needs-judge	—
W05	決定的	結果、モード	レポート／--write-baseline／ベースラインとの差分を --check	レポート、ベースラインファイル、終了コード 0／2	低下 → 終了コード 2

各ステップの詳細（W01～W05 の信頼できる情報源）：

アサーションのカスケード（低コスト → 高コスト、条件成立時に打ち切り）

1. Tier 1 — 決定的アサーション（今すぐ構築するコア部分）：equals／contains／icontains／ not-contains／regex／is-json／is-sql-ish を候補出力に対して実行します。ゴールデンで asserts が宣言されている場合、Tier 1 だけで合否が決まります。不明な演算子はフェイルクローズします。
2. Tier 2 — 類似度（任意）：ゴールデンにアサーションがない場合のみ実行します。設定で embedding.backend が設定されていない限り、スキップして記録します（difflib は標準ライブラリによる語彙的な比較で、オフラインで動作します。実際の モデル ID はアダプターが接続されるまでスキップされます）。
3. Tier 3 — LLM ルーブリックジャッジ＝アダプター（verified: false）。スタブの judge(output, rubric) -> {score, reason} は決定的モードでは決して呼び出されません。エスカレーション対象の ゴールデンは needs-judge としてレポートされます。

ゴールデン

llmwiki/wiki/sources/evals/ 配下の YAML フロントマター付き Markdown です。内容は input、expected、 任意の rubric、任意の asserts（それぞれを引用符で囲みます：'contains:foo'、'regex:^...$'、 'is-json'、'equals:bar'、'is-sql-ish'）です。任意の id（デフォルトはファイル名の拡張子を除いた部分）。 各ゴールデンは R9（フロントマターの type）と R2（## Origin）にも準拠します。

実行（モデル不要）

# run the cascade with a fixed candidate set, print a report
python3 harness/scripts/wikieval.py --outputs harness/evals/wikieval-outputs.example.json

# write / refresh the committed baseline (per-golden pass + score)
python3 harness/scripts/wikieval.py --outputs <outputs.json> --write-baseline

# CI gate: re-run and exit 2 if any metric dropped below baseline (deterministic diff)
python3 harness/scripts/wikieval.py --outputs <outputs.json> --check

ベースライン：harness/metrics/eval-baseline.json。アダプター設定：harness/wikieval.config.yaml。

分岐

ID	種類	条件	動作	スキップ／失敗	再合流
B01	機能（任意）	ゴールデンに asserts がなく、かつ embedding.backend が設定されている	Tier 2 の類似度（difflib はオフラインで動作）	バックエンド未設定、または実際のモデル ID が未接続 → スキップして記録	W04
B02	ユーザー指定（任意）	--write-baseline	harness/metrics/eval-baseline.json を書き込み／更新	—	終了
B03	ユーザー指定（任意）	--check	ベースラインとの差分を決定的に比較し、低下時は終了コード 2	ベースラインがない → 先に --write-baseline を実行	終了

検証と停止条件

アサーション、カスケード、ベースライン差分、終了コードはすべてコードでチェックされ、決定的に処理されます。レビューが必要なのは Tier 3（needs-judge）のみで、アダプターが完成するまでは合否判定の対象外です。

セルフテスト（今すぐ構築する範囲）

OUT=harness/evals/wikieval-outputs.example.json
python3 harness/scripts/wikieval.py --outputs $OUT --write-baseline   # both goldens PASS
python3 harness/scripts/wikieval.py --outputs $OUT --check            # exit 0 — no regression
# flip one output to break an assert, then:
python3 harness/scripts/wikieval.py --outputs <broken.json> --check   # exit 2 + regression diff

例

• 成功例： ベースラインを書き込んだ後に python3 harness/scripts/wikieval.py --outputs harness/evals/wikieval-outputs.example.json --check を実行 → 両方のゴールデンが PASS → 終了コード 0。
• 境界／失敗例： 候補を 1 つ変更して 'contains:foo' に一致しなくすると → --check は、そのゴールデンを示す回帰差分とともに終了コード 2 で終了します。
• 境界例： rubric のみがあり、アサーションも embedding.backend もないゴールデン → Tier 2 はスキップされて記録され、needs-judge としてレポートされます。ジャッジは呼び出されません。

参考 — アダプターの境界（今すぐ構築し、後で適応）

• 今すぐ構築・テスト済み： Tier 1 のアサーション、カスケード、ベースラインの書き込み、--check による回帰差分。
• 隔離済み（verified: false）： harness/wikieval.config.yaml（ジャッジモデルとルーブリックプロンプト、 埋め込みバックエンド。それぞれに # ASSUMPTION の注記があります）と judge() スタブ。
• 完成させる手順： judge() を設定済みモデルに接続し、セルフテストを実行して、verified: true に切り替えます。 変更するのは 1 ファイルだけです。WikiEval のその他の部分は変更しません。

Reference — Files

• harness/scripts/wikieval.py — the eval engine.
• harness/wikieval.config.yaml — the one adapter (verified: false).
• harness/metrics/eval-baseline.json — committed regression baseline (generated).
• llmwiki/wiki/sources/evals/*.md — goldens.
• harness/evals/wikieval-outputs.example.json — self-test candidate outputs.