drawdown-circuit-breaker

ドローダウン・サーキットブレーカー

概要

口座レベルの実現損益と直近の取引結果に基づいて、トレーダーが今日、新たな取引リスクを取るべきかどうかを評価します。このスキルが読み取るのは、trader-memory-core の thesis YAML ファイルのみです。exposure-coach が生成するマーケット側の exposure_decision を補完する circuit_breaker_decision アーティファクトを生成します。

サーキットブレーカーは、推奨と記録管理のためのツールです。人間の判断に取って代わるものではなく、ブローカー側のブロックや自動注文拒否を強制するものでもありません。

使用するタイミング

• 新しいスイングトレード候補のスクリーニングやサイズ設定を行う前
• 損失が出た取引の後、または一部を手仕舞った後、クールダウンが有効か確認するとき
• trader-memory-core に最近の決済済みまたは一部決済済みポジションが含まれている場合の日次計画中
• swing-opportunity-daily が候補の生成に進む前のワークフローゲートとして
• 日次、週次、月次の損失上限を超過しているか確認するとき

前提条件

• Python 3.9+
• ローカルの trader-memory-core thesis YAML ファイル（通常は state/theses/ の下）
• ドル建ての口座サイズ
• API キーやネットワークアクセスは不要です

ワークフロー

ステップ 1：Trader Memory の状態を読み込む

スクリプトに thesis の状態ディレクトリを指定します。

python3 skills/drawdown-circuit-breaker/scripts/check_circuit_breaker.py \
  --state-dir state/theses \
  --account-size 100000 \
  --output-dir reports/

スクリプトはすべての th_*.yaml ファイルをスキャンし、各 thesis の status_history[] 台帳エントリから実現損益を読み取ります。必要な実現損益台帳が含まれていないため、軽量な参照用ファイルである _index.json は損益の読み取りに使用しません。

各ファイルを検証した後、スクリプトは、大文字と小文字を区別し、前後の空白を取り除いた thesis_id ごとに有効な thesis をグループ化します。有効なファイルで同じ ID が 2 件以上見つかった場合、重複グループ全体を損益および連敗の計算から除外し、実際のすべてのソースパスを報告します。また、重複状態が修復されて判断が再実行されるまで、PARTIAL + HALTED を返します。metrics.theses_scanned は、受け入れられた一意の ID を持つ thesis のみをカウントします。

状態ディレクトリが存在しないか、空のディレクトリの場合、履歴がないことで新しいユーザーがブロックされないよう、このスキルは data_quality: EMPTY_STATE を伴う TRADING_ALLOWED を返します。設定された状態パスが存在していてもディレクトリではない場合、このスキルは状態データが不完全であるとしてフェイルクローズします。

状態が存在するものの、thesis、台帳イベント、または終端結果をスキップする必要がある場合、あるいは別の記録値と矛盾する場合、このスキルは data_quality: PARTIAL、recommendation: HALTED、および incomplete_state_data ルールを伴ってフェイルクローズします。警告を修正し、新たなリスクを取る前に再実行してください。回復可能な例外が 1 つあります。実現損益台帳エントリのないレガシー thesis に対する、有限値の終端 outcome.pnl_dollars フォールバックです。この場合、PARTIAL の表示は維持されますが、それだけで計算された推奨が覆ることはありません。ACTIVE、PARTIALLY_CLOSED、CLOSED、INVALIDATED の thesis では、各履歴イベントは認識可能な status と解析可能な at を持つオブジェクトでなければならず、最後の履歴ステータスは thesis のステータスと一致していなければなりません。ACTIVE と PARTIALLY_CLOSED の thesis にはエントリー実績も必要です。また、PARTIALLY_CLOSED にはポジションが必要です。形式不正、古い、または不完全なライフサイクル履歴があると、終端フォールバックは無効になり、処理は停止します。realized_pnl が欠落している、型が正しくない、または有限値でない台帳形式のイベントも、値が強制的に変換されることなく処理が停止します。

ステップ 2：サーキットブレーカーのルールを評価する

デフォルトのルールは次のとおりです。

ルール	デフォルト	発動時の状態	解除
1 日あたりの最大損失	口座の 2.0%	HALTED	次の ET 平日
連敗クールダウン	ターミナル状態の損失テーゼ 2 件	COOLDOWN	直近の損失決済から 24 時間後
週間ドローダウン停止	口座の 5.0%	HALTED	次の月曜日 ET
月間ドローダウン停止	口座の 8.0%	HALTED	翌月の初日 ET

日、週、月の境界には America/New_York を使用します。trader-memory-core からの日時のみのプロデューサータイムスタンプは、指定された ET 日付に計上されます。評価を決定論的に行うには --as-of を設定します。日時のみの --as-of 値は ET の 1 日全体を対象とし、タイムスタンプ値ではその時刻より後のイベントを除外します。

python3 skills/drawdown-circuit-breaker/scripts/check_circuit_breaker.py \
  --state-dir state/theses \
  --account-size 100000 \
  --as-of 2026-07-02T12:00:00-04:00 \
  --output-dir reports/

ステップ 3：必要に応じてしきい値を上書きする

CLI で個々のしきい値を上書きします。

python3 skills/drawdown-circuit-breaker/scripts/check_circuit_breaker.py \
  --account-size 100000 \
  --max-daily-loss-pct 1.5 \
  --losing-streak-n 3 \
  --cooldown-hours 48 \
  --weekly-drawdown-pct 4 \
  --monthly-drawdown-pct 6

または、JSON 設定ファイルを指定します。

{
  "max_daily_loss_pct": 1.5,
  "losing_streak_n": 3,
  "cooldown_hours": 48,
  "weekly_drawdown_pct": 4.0,
  "monthly_drawdown_pct": 6.0
}

CLI 引数は設定ファイルの値より優先されます。

ステップ 4：判定を解釈する

生成された判定を、新たなトレードリスクを受け入れるためのゲートとして使用します。

推奨	意味
TRADING_ALLOWED	有効なサーキットブレーカーのルールはありません。ワークフローの残りの手順を通じて、新たなトレードリスクに進むことができます
COOLDOWN	新たなポジションを建てないでください。既存のポジションの管理を続け、直近の損失を確認してください
HALTED	ドローダウンの上限に達しているか、口座状態のデータが不完全なため、新規エントリーを停止してください。続行する前に、データの警告を解消するか、再実行してください

既存のポジションをどう管理するかは、引き続き人間が判断します。サーキットブレーカーは、実現損失が発生した後に新たなリスクの拡大を防ぐためのものであり、強制決済を行うものではありません。

時間ベースのルールには ISO 8601 形式の active_until が設定されます。時間ベースではない incomplete_state_data ルールでは active_until: null が使用されます。このルールの Markdown レポートには、状態を修復して判定を再実行するまで停止が続くと記載されます。

出力形式

スクリプトは circuit_breaker_decision_YYYY-MM-DD_HHMMSS.json を出力し、--json-only が設定されていない場合は、対応する Markdown レポートも出力します。

{
  "schema_version": "1.0",
  "generated_at": "2026-07-02T16:00:00+00:00",
  "as_of_date": "2026-07-02",
  "recommendation": "COOLDOWN",
  "triggered_rules": [
    {
      "rule": "losing_streak_cooldown",
      "threshold": 2,
      "observed": 2,
      "active_until": "2026-07-02T15:30:00-04:00",
      "detail": "2 consecutive losing closes; last loss exit 2026-07-01T15:30:00-04:00."
    }
  ],
  "metrics": {
    "realized_pnl_today": 0.0,
    "realized_pnl_wtd": -250.0,
    "realized_pnl_mtd": -250.0,
    "consecutive_losses": 2,
    "last_loss_exit_at": "2026-07-01T15:30:00-04:00",
    "theses_scanned": 12
  },
  "account_size": 100000.0,
  "config": {
    "max_daily_loss_pct": 2.0,
    "losing_streak_n": 2,
    "cooldown_hours": 24.0,
    "weekly_drawdown_pct": 5.0,
    "monthly_drawdown_pct": 8.0
  },
  "data_quality": "OK",
  "warnings": [],
  "rationale": "Recent losing closes triggered a cooldown. Avoid new entries until the cooldown expires."
}

取引所カレンダーの仕様

チェッカーを実行する前に requirements.txt をインストールしてください。日次、週次、月次の停止日は、実際の XNYS 取引日に基づきます。active_until との互換性は維持されます。停止は、次の対象取引日の 00:00 America/New_York に終了し、その取引日の取引開始時刻には終了しません。評価を決定論的に行うには --as-of を使用します。

リソース

• scripts/check_circuit_breaker.py - メインの CLI とルールエンジン
• references/circuit_breaker_framework.md - ルールの定義、デフォルト値、データソースに関する注記
• skills/trader-memory-core/schemas/thesis.schema.json - テーゼ状態のソーススキーマ

主要な原則

1. 実現損失のみ - 日次計算には、記録された実現損益を使用します。含み損益やテーゼ単位の累積値は使用しません。
2. まず生存を優先 - サーキットブレーカーは、損失の発生後にさらなる拡大を防ぐためのものです。
3. 助言であり、自動執行ではない - 出力はワークフローのゲート判断に役立つものであり、ブローカー注文の発注、キャンセル、ブロックは行いません。
4. 状態が不完全な場合は安全側に倒す - 状態が空であれば、新しいユーザーは利用を開始できます。一方、リスクデータに形式不正、破棄、矛盾、または非有限値がある場合は、クラッシュせずに PARTIAL + HALTED を返します。有限値であるレガシーな結果のフォールバックは、復旧可能な PARTIAL として報告され、ブロック要因にはなりません。