cost-diff

PR レベルのコスト回帰検出です。cost-counterfactual は HYPOTHETICAL ベースライン（always-haiku／sonnet／opus）と比較し、cost-burn は最新のバケットを PRIOR MEAN と比較します。一方、cost-diff は、特定の既知の正常なスナップショット 2 つを比較します。

質問	スキル
「常に X を使っていたら、いくらかかっていたでしょうか？」	cost-counterfactual
「日次の消費額は、過去の平均と比べて増加していますか？」	cost-burn
「この PR で main と比べて支出が増えましたか？」	cost-diff ← これ

アルゴリズム

実装：scripts/diff.mjs。cost summary --format json の安定した JSON コントラクトを使用します。

1. --baseline と --current の JSON スナップショットを読み込みます。
2. 整合性を確認します。両方に total_cost_usd と sessionCount（cost-summary の形式）が必要です。
3. キーごとの差分：byTier（haiku／sonnet／opus）と byModel（各モデル）。
4. 各エントリーには、baseline／current がゼロかどうかに基づいて added／removed／changed のタグが付きます。
5. 表は |delta| の降順で並べ替え、変化が最も大きい項目を先頭に表示します。
6. --alert-on-pct N：total_pct > N のとき終了コード 1 を返します。
7. --alert-on-usd N：total_delta_usd > N のとき終了コード 1 を返します。 両方を設定できます。先に条件を満たした方が適用されます。

PR ゲートのワークフロー

# Capture baseline (e.g. on main, via the cost-tracker-smoke CI workflow)
cost summary --format json > baseline.json

# On the PR branch, capture current state
cost summary --format json > current.json

# Compare; fail the PR if total spend grew >10% OR >$5
cost diff --baseline baseline.json --current current.json \
          --alert-on-pct 10 --alert-on-usd 5.00

両方のフラグを組み合わせると、次のケースを検出できます。

• パーセントのみで発火：絶対額の変化は小さくても、意味のある変化がある場合 （例：$0.10 から $0.20 への倍増は +100% ですが、増加額は +$0.10 にすぎません）。
• USD のみで発火：絶対額の変化は大きくても、パーセントは小さい場合 （例：$100 から $110 への増加は +10% にすぎませんが、増加額は +$10 です）。

いずれかのシグナルだけで PR は失敗します。条件は OR で結合されます。

--alert-on-class-pct（iter 86）

上記の USD レベルの 2 つのしきい値では、回帰の一種を見逃します。つまり、合計支出の増加が modest でも、1 つのトークン種別が不均衡に増加するケースです。例：PR によって冗長なコンテキストキャッシュのパターンが導入され、合計支出は 10% しか増えない（--alert-on-pct 50 未満）一方で、cache_write トークンは 900% 増加します。iter-82 の要因は USD シグナルに隠れてしまいます。

--alert-on-class-pct cache_write:50 は、cache_write トークンが baseline から current にかけて 50% を超えて増加すると、終了コード 1 を返します。1 つのフラグで複数のクラスを確認できます（コンマ区切り）。

cost diff --baseline baseline.json --current current.json \
          --alert-on-class-pct cache_write:50,output:25

最初にしきい値を超えたクラスが適用されます。有効なクラス：input | output | cache_write | cache_read。

推奨する PR ゲートの 3 条件：

cost diff --baseline ... --current ... \
          --alert-on-pct 25 \
          --alert-on-usd 5.00 \
          --alert-on-class-pct cache_write:100

直交する 3 つのシグナルです。pct（合計が増加）、usd（絶対額が大幅に増加）、class-pct（構成が変化）。それぞれ他のシグナルが見逃す変化を検出します。AND-of-OR の条件により、いずれか 1 つが発火すれば PR は失敗します。

スモークテストの記録（合成 baseline + current）

| Total spend       | $1.000000 | $1.500000 | +$0.500000 | 50.00% |
| Sessions          | 10        | 13        | +3         | 30.00% |

## By tier
| opus   | $0      | $0.60   | +$0.600000 | new      | added   |
| sonnet | $0.70   | $0.50   | -$0.200000 | -28.57%  | changed |
| haiku  | $0.30   | $0.40   | +$0.100000 | 33.33%   | changed |

表がアルファベット順ではなく、絶対差分の大きい順に並んでいることに注目してください。最も変化の大きい項目（新たに追加された opus）が先頭に表示されます。上から順に確認することで、オペレーターは「重要だったこと」を最初に把握できます。

終了コード

終了コード	意味
0	アラートなし、またはしきい値未設定
1	--alert-on-pct または --alert-on-usd のしきい値を超過
2	設定エラー（ファイルがない、JSON が無効、スナップショットの形式が不正）

ステータス列

ステータス	意味
added	この tier／モデルは baseline では $0、current では $0 超
removed	この tier／モデルは baseline では $0 超、current では $0
changed	baseline と current の両方が $0 超。差分はその違い

baseline === 0 && current === 0 のエントリーは除外されます（報告する内容がないため）。

cost-summary との組み合わせ

cost-diff は、cost-summary が始めたコントラクトの後半部分です。cost summary --format json の安定した JSON 形式を使用します。両方の仕様は固定されています。summary へのフィールド追加は問題ありませんが、名前の変更や削除はできません。

スナップショットを別の場所（ダッシュボード、アラートなど）で使用する場合も、同じ形式を利用できます。cost-diff はその利用者の 1 つにすぎません。