ibd-distribution-day-monitor

IBD Distribution Day Monitor

目的

主要な市場ETF（ナスダックの代理指標としてのQQQ、S&P 500の代理指標としてのSPY）について、IBD方式のディストリビューション・デイを検出し、日次の市場悪化シグナルとTQQQ/QQQのエクスポージャー推奨を出力します。市場終了後のレビューを想定して設計されています。

使用するタイミング

このスキルは、次のような場合に呼び出してください。

• 米国市場の終了後、毎日。
• TQQQのエクスポージャーを増やす前、またはレバレッジポジションをリバランスする前。
• 上昇トレンドが調整局面に対して脆弱になっているかを評価するとき。
• FTD（フォロースルー・デイ）検出や、その他の市場状態フレームワークへの上流入力として。

このスキルは、次の用途には使用しないでください。

• 取引の実行や注文の変更。
• IBDルールセットの範囲外での裁量的な市場予測の生成。

入力

• シンボル（デフォルト：QQQ、SPY）とルックバック期間（デフォルト：取引セッション80回）。
• 過去のセッションを対象にバックテストする場合は、オプションの --as-of YYYY-MM-DD を指定します。
• 戦略コンテキスト：金融商品（TQQQまたはQQQ）、現在のエクスポージャー%、ベースのトレーリングストップ%。
• FMP APIキー。--api-key、config.data.api_key、またはFMP_API_KEY環境変数から指定します（優先順位順）。

基本ルール

ディストリビューション・デイは、次の条件を満たす場合に検出されます。

1. 本日の終値が前日の終値を少なくとも0.2%下回っている。
2. 本日の出来高が前日の出来高を上回っている。

ディストリビューション・デイは、次のいずれかに該当すると有効カウントから除外されます。

• DDから25取引セッションを超える期間が経過した。
• DDの終値から指数が5%上昇した（デフォルトではDD後の高値を使用し、終値を基準とする設定にも変更可能）。

本日のDDは、5%上昇の判定対象となるDD後のセッションがないため、直ちに無効化されることはありません。

カウント方法

• d5_count / d15_count / d25_count は、age_sessions <= N の有効な記録数をカウントします。
• つまり、N+1セッション（age 0～Nを含む）を調べます。そのため、レポートでは曖昧さを避けるために「直近N取引日」ではなく「経過Nセッション以内」と記載します。

リスク分類

リスク	条件
NORMAL	d25 <= 2
CAUTION	d25 >= 3
HIGH	d25 >= 5 OR d15 >= 3 OR d5 >= 2
SEVERE	d25 >= 6 OR d15 >= 4 OR (market_below_21ema_or_50ma AND d25 >= 5)

QQQとSPYの両方を読み込む場合、QQQに重みを置いた全体判定ロジック（TQQQを考慮）が適用されます。SEVEREが1つでもあれば全体をSEVEREに引き上げます。QQQがHIGHなら全体もHIGHに引き上げます。QQQがNORMALでSPYがHIGHの場合も、広範な市場への波及を考慮して全体をHIGHに引き上げます。

TQQQのエクスポージャーポリシー

リスク	アクション	目標エクスポージャー	トレーリングストップ
NORMAL	HOLD_OR_FOLLOW_BASE_STRATEGY	100%	base
CAUTION	AVOID_NEW_ADDS	75%	min(base, 7%)
HIGH	REDUCE_EXPOSURE	50%	min(base, 5%)
SEVERE	CLOSE_TQQQ_OR_HEDGE	25%	min(base, 3%)

QQQは3倍レバレッジではないため、より抑制的なポリシーを適用します（HIGH＝75%、SEVERE＝50%）。

ワークフロー

1. FMPのget_historical_pricesを使って、設定済みのシンボルのOHLCVを読み込みます。
2. データ品質を検証し、スキップしたセッションを監査ログに記録します。
3. prepare_effective_historyで基準をリセットし、effective_history[0]が評価対象セッションになるようにします。
4. 生のディストリビューション・デイを検出し、high_since、無効化イベント、ステータスを追加します。
5. 有効な記録のd5 / d15 / d25をカウントします。
6. 21EMAおよび50SMAのフィルターを計算し、market_below_21ema_or_50maを設定します（データ不足の場合はNone）。
7. 各指数を分類し、QQQに重みを置いたポリシーで統合します。
8. 設定された金融商品に対するポートフォリオアクションを生成します。
9. APIキーを秘匿したうえで、JSONおよびMarkdownレポートを--output-dirに書き込みます。

出力

reports/（または--output-dir）に保存されます。

• ibd_distribution_day_monitor_YYYY-MM-DD_HHMMSS.json
• ibd_distribution_day_monitor_YYYY-MM-DD_HHMMSS.md

JSONはensure_ascii=Falseを指定したUTF-8形式です（日本語の説明を保持します）。機密キー（api_key、fmp_api_key、tokenなど）は自動的に秘匿されます。

運用原則

• config/default.yaml を意図的に変更しない限り、IBD のルール定義を上書きしないでください。
• アクティブカウントに寄与した日付を必ず説明してください。
• 欠損または信頼性の低い出来高データは、Distribution Day としてではなく、警告（audit_flag）として扱ってください。
• 取引は行わないでください。ポートフォリオに関するアクションはリスク管理の提案であり、実行指示ではありません。

CLI

python3 skills/ibd-distribution-day-monitor/scripts/ibd_monitor.py \
  --symbols QQQ,SPY \
  --lookback-days 80 \
  --instrument TQQQ \
  --current-exposure 100 \
  --base-trailing-stop 10 \
  --output-dir reports/

API 要件

FMP API キーが必要です。無料枠（1 日あたり 250 回の呼び出し）で、QQQ と SPY の日次実行には十分です。

関連スキル

• ftd-detector：Follow-Through Days による底値確認（このトップサイドシグナルに対応するもの）。
• market-top-detector：O'Neil の分配など、複数の要素を用いた 0〜100 の複合トップ確率スコア。
• position-sizer：リスク管理の推奨事項を株数に換算します。