cost-health

4 つの CI ゲートスキル（budget／burn／anomaly／projection）は、それぞれ異なる質問に答えます。このスキルはそれらを組み合わせ、4 つすべてを並列で実行し、max(exit_codes) を返して、各チェックの概要を 1 行ずつ表示します。

サブチェック	質問	デフォルトのしきい値
budget	「設定した予算を超えていますか？」	100% で HARD_STOP
burn	「日次の消費ペースは加速していますか？」	前週平均比 +100%
anomaly	「特定のセッションが 3.5σ を超える外れ値ですか？」	外れ値が 1 件以上
projection	「予算の 100% に達するのはいつですか？」	14 日未満

アルゴリズム

実装：scripts/health.mjs。

1. 4 つすべてのサブチェックスクリプトを並列で起動します（child_process.spawn に対する Promise.all）。
2. 各サブチェックは --format json を出力します。これを解析し、終了コードを取得します。
3. Projection には組み込みの終了コードがないため、daysUntilReached[100%] < --alert-days-to-exhaust から終了コードを生成します。
4. 最終的な終了コード = max(サブチェックの終了コード)。1 つでも失敗するとゲート全体が失敗します。
5. 各チェックの概要を 1 行ずつ表示し、全体の HEALTHY／UNHEALTHY バッジも表示します。

CI への統合

- name: Cost health gate
  run: cost health --alert-acceleration 100 --alert-outliers 1

1 つのステップで 4 つのアラートラダーを網羅できます。このスキルを使う前は、npx とメモリーリストのオーバーヘッドが重複する 4 つのゲートを個別に設定する必要がありましたが、今ではシェルアウト 1 回で済みます（4 つのサブチェックの npx 呼び出しは内部で並列実行されます）。

しきい値のカスタマイズ

# Quarterly review — stricter thresholds
cost health --alert-acceleration 50 --alert-outliers 1 --alert-days-to-exhaust 30

# Production drift gate — only fire on egregious changes
cost health --alert-acceleration 200 --alert-outliers 3 --alert-days-to-exhaust 7

# Skip the slow burn check during a smoke run
cost health --skip burn

スモークテストの記録（健全なセッション 5 件の後、外れ値を 1 件追加）

# Healthy
Overall: ✓ HEALTHY (max exit code 0)
| Check | Status | Detail |
| budget | ✓ | unknown — no budget configured |
| burn | ✓ | delta within ±100% |
| anomaly | ✓ | 0 outliers — under threshold ≥1 |
| projection | ✓ | no budget configured — skipping |

# After adding $5 outlier (vs $0.10 baseline)
Overall: ⚠ UNHEALTHY (max exit code 1)
| burn | ⚠ | ALERT 5163.2% acceleration: latest bucket $5.00 is 5163.2% above prior mean $0.095 |
| anomaly | ⚠ | ALERT 1 outlier (|z|>3.5) |

サブチェックのスキップ

cost health --skip burn,projection   # only budget + anomaly

次のような場合に便利です：

• サブチェックが該当しない場合（予算が未設定 → projection をスキップ）
• サブチェックが高速フィードバックのコンテキスト（スモーク実行）には遅すぎる場合
• サブチェックがすでに独立した CI ゲートの対象になっている場合

終了コードの意味

終了コード	意味
0	すべてのサブチェックが OK
1	少なくとも 1 つのサブチェックがアラートを発生させた（budget の HARD_STOP、burn の変動、anomaly の外れ値、projection の枯渇が迫っている状態）
2	サブチェックで設定または使用方法のエラーが発生した（例：無効な CLI 引数がサブスクリプトに渡された）
127	サブチェックの起動に失敗した（スクリプトが見つからないなど）

max() により、最も悪いシグナルが優先されます。つまり、終了コード 2（設定エラー）は常に終了コード 1（アラート）より優先されるため、設定ミスのあるパイプラインが健全なものに見えてしまう前に気づけます。