metric-validation-harness

メトリック検証ハーネス

このハーネスに候補メトリックとコーパスを指定すると、信頼でき、最適化可能なメトリックに必要な各特性を反証しようとする実験が実行されます。これは deterministic-metric-design の実証的な補完となるものです。このスキルでは単調性、不変性、決定性、構成概念妥当性を証明するよう求めますが、このスキルでは実験を実行して PASS／FAIL を報告し、各結果を検証対象の設計スキルのカテゴリに対応付けます。

読み取り専用です。 計算して結果を報告するだけで、メトリック、コーパス、外部状態を変更することはありません。監視なしで安全に実行できます。

使用する場面

• メトリック／スコア／指数が提案、レビュー、調整、リリースされる際に、その妥当性を示す証拠が必要な場合
• スコアに違和感がある場合 — LOC に左右される、実行ごとに変動する、または飽和するのではないかと疑っている
• エージェントにメトリックを最適化させる前に、見た目だけの編集で攻略されないことを確認する必要がある場合
• deterministic-metric-design に沿って候補を作成し、主張した特性を実証的に確認したい場合
• 2 つのメトリックから選ぶ必要があり、どちらが実際に結果を予測するのか（そして単純なベースラインを上回るのか）を知りたい場合

ワークフローの概要

config.json / env  →  resolve metric_cmd, corpus, thresholds (env > config > bundled default)
        │
        ▼
   verify.sh ──► determinism ─ invariance ─ monotonicity ─ robustness ─ tractability ─ validity
        │            (each property check maps to a deterministic-metric-design category)
        ▼
   PASS / FAIL per property  →  exit 0 (all pass) or 1 (any group failed)

アダプターの契約

メトリックは、パスを最後の引数として受け取り、標準出力に数値を 1 つだけ出力する任意のコマンドです。

$ python3 mymetric.py path/to/file.py
42

言語は問いません。Python、シェルのワンライナー、コンパイル済みバイナリなど、何でも構いません。診断情報は標準エラー出力に出し、標準出力には数値だけを出力してください。ハーネスをすぐに実行できるよう、サンプルのメトリック（AST ノード数を数える scripts/examples/metric_ast_nodes.py）が同梱されています。

実行方法

# 1. Validate the bundled example metric (works with zero setup):
bash scripts/verify.sh

# 2. Validate YOUR metric — set metric_cmd in config.json, or override per-run:
METRIC_CMD="python3 /abs/path/mymetric.py" bash scripts/verify.sh

# 3. Prove the harness itself works (positive + negative cases):
bash scripts/selftest.sh

# 4. Sanity-check your adapter prints one number:
bash scripts/run-metric.sh path/to/file.py

verify.sh はすべてのチェックを実行し、最後に PASS／FAIL を出力します。各チェックは個別に実行することもできます（例：bash scripts/check-determinism.sh）。

チェック内容

チェック	対応するカテゴリ（設計スキル）	内容	PASS 条件
check-determinism.sh	det-	メトリックを 2 回実行し、さらに PYTHONHASHSEED を 0／1 に設定して実行します	毎回同じ数値になる
check-invariance.sh	prop- ／ game-	コメント／空行／空白を追加します（見た目だけの変更）	スコアが変わらない（変わる場合は攻略可能）
check-monotonicity.sh	prop-	コードブロックを追加します（構成を増やす変更）。あわせてスコアのばらつきを確認します	スコアが減少しない。飽和していない
check-robustness.sh	prop-	空の入力と 1 文のみの境界入力を確認します	有限値で、宣言された範囲内に収まり、クラッシュしない
check-tractability.py	comp-	入力を増やしながらメトリックの実行時間を計測します	予算内であり、増加率が二次未満
check-validity.py	valid-	受け入れ済みの値とのスピアマン相関、LOC とのスピアマン相関、結果との AUC を確認します	収束性が高く、弁別性が LOC とほぼ同じではなく、予測性能がベースラインを上回る

統計（スピアマン相関、AUC／マン・ホイットニー検定）は、Python 標準ライブラリだけで計算できます。numpy／scipy は不要です。

セットアップと設定

同梱のサンプルに対しては、設定なしで実行できます。独自のメトリックを検証するには、config.json の項目を設定するか、実行ごとに対応する UPPER_CASE 環境変数で上書きします。

config.json	環境変数による上書き	意味
metric_cmd	METRIC_CMD	メトリックコマンド（パスを受け取り → 数値を出力）
baseline_cmd	BASELINE_CMD	単純なベースライン（デフォルト：同梱の LOC）
corpus_dir	CORPUS_DIR	特性チェックの対象となる成果物
labels_csv	LABELS_CSV	妥当性検証用の path[,outcome][,accepted]
declared_min ／ declared_max	DECLARED_MIN ／ DECLARED_MAX	頑健性チェックで適用する範囲

妥当性のしきい値は環境変数で調整できます：CONVERGENT_MIN、DISCRIMINANT_MAX、PREDICTIVE_MIN（デフォルトは緩めです。実運用では厳しくしてください。gotchas.md を参照）。

設定項目が空の場合は同梱のデモにフォールバックするため、セットアップが不足していてもこのスキルがクラッシュすることはありません。代わりにサンプルを実行します。

ツールの要件

• python3（3.8 以降）— メトリクス、変換処理、統計を実行します
• bash と awk — オーケストレーターと数値比較に使用します（スクリプトは macOS の bash 3.2 に対応しています）

ネットワークも外部パッケージも必要ありません。

結果の解釈

FAIL には、該当するプロパティと参照すべき設計スキルのルールが示されます。例：

• 見た目だけのノイズでスコアが変わった → メトリクスは表層のテキストを読み取っています。prop-prove-invariance-under-irrelevant-transforms と game-make-cheapest-improvement-the-right-one を参照してください。
• コードを追加したらスコアが低下した → 単調性がありません。これを最適化すると、より悪いコードに報いることがあります（prop-prove-monotonicity）。
• |Spearman(metric, LOC)| が高すぎる → LOC に別の名前を付けただけです（valid-discriminant-not-just-loc）。

関連スキル

• deterministic-metric-design — 設計のパートです。メトリクスの構築（構成概念の定義、計算可能な代理指標の選択、尺度の決定、プロパティの根拠の説明）に使用し、このハーネスで主張を実証的に検証します。
• same-results-less-code、complexity-optimizer、knip-deadcode — コード削減を推奨するスキルです。エージェントに最適化させる前に、このハーネスを使って、これらのスキルを動かすために構築した削減メトリクスを検証してください。

各チェックの詳細、独自のメトリクスとコーパスの接続方法、トラブルシューティングについては、references/workflow.md を参照してください。