Add unified market regime control plugin

README.md

@@ -30,6 +30,23 @@ send notifications; plugin research and signal generation live here.
   gaps only, never overrides the deterministic route, places orders, or changes
   allocations. Local Codex is tried first when enabled; OpenAI-compatible and
   Anthropic fallback endpoints can be configured.
+- `macro_risk_governor`: deterministic macro de-leveraging governor for TQQQ.
+  It scores price trend, realized volatility, VIX, and credit-pair stress. The
+  artifact can expose
+  `leverage_scalar` and `risk_asset_scalar` to strategy runtimes that explicitly
+  opt in through mounted metadata. External hard-data fields such as HY OAS and
+  financial-stress indices, plus OSINT-style, sentiment, options-volatility,
+  rates, breadth, funding, and liquidity fields such as a Pentagon pizza index,
+  Fear & Greed, put/call, VVIX, SKEW, MOVE, yield curves, dollar stress, and
+  safe-haven demand, are kept as watch-only evidence by default. They do not
+  contribute to the actionable trading score unless explicitly enabled for
+  research.
+- `market_regime_control`: unified deterministic facade for crisis, macro, and
+  TACO signals. Only strategies with positive backtest evidence should mount
+  position controls for automated consumption; SOXL/SOXX currently receives
+  broad macro/crisis signals as general notifications only. Stock/ETF rotation
+  strategies should consume the same artifact through their local risk-scaling
+  policy and keep TACO as notification-only.
 - `taco_rebound_shadow`: TQQQ-only event-rebound context notifier. It writes
   manual-review artifacts and never recommends position size or changes
   allocations. Softening/de-escalation events stay watch-only until post-event
@@ -56,6 +73,23 @@ qsp-build-crisis-response-shadow-signal \
   --output-dir data/output/tqqq_growth_income/plugins/crisis_response_shadow
 ```
 
+Build the public hard-data `external_context` CSV used by macro and unified
+market-regime plugins:
+
+```bash
+qsp-build-macro-external-context \
+  --start 1999-01-01 \
+  --output data/output/market_regime_control/input/external_context.csv
+```
+
+The builder downloads public FRED/CBOE fields when available: VIX, VIX3M,
+VVIX, SKEW, Cboe put/call ratios, HY/IG OAS, financial-stress indices, yield
+curves, trade-weighted dollar stress, and TED/funding stress. Fields without a
+stable no-login historical feed, such as CNN Fear & Greed, AAII, NAAIM,
+Pentagon pizza, MOVE, and breadth, can be supplied with `--manual-context`.
+OAS coverage follows what the public FRED graph endpoint returns; archived
+local OAS history can be injected with the same manual context path.
+
 AI audit reads API settings from environment variables:
 
 - `QSP_STRATEGY_PLUGIN_AI_AUDIT_CODEX_ENABLED`, default `true`
@@ -84,6 +118,24 @@ Generated artifacts include `latest_signal.json`, dated JSON, dated CSV, and
 an evidence CSV. `latest_signal.json` is the file platform runtimes mount via
 `*_STRATEGY_PLUGIN_MOUNTS_JSON`.
 
+## Notification and Log i18n
+
+Runner-managed artifacts add display-only i18n fields for notifications and
+logs:
+
+- `localized_messages.schema_version = strategy_plugin_messages.v1`
+- `localized_messages.notification.en-US` / `localized_messages.notification.zh-CN`
+- `localized_messages.log.en-US` / `localized_messages.log.zh-CN`
+- `log_record.schema_version = strategy_plugin_log.v1`
+- `market_regime_control.notification.localized_message_schema_version`
+
+Strategy and broker runtimes should keep trading logic on machine fields such
+as `schema_version`, `canonical_route`, `suggested_action`, `reason_codes`, and
+`position_control`. Localized strings are for human notification surfaces and
+logs only. `market_regime_control.notification` mirrors the localized
+notification text and reason labels so existing notification code can render a
+message without translating route/action codes itself.
+
 ## Local Checks
 
 ```bash

README.zh-CN.md

@@ -25,6 +25,8 @@ Brokers、Schwab、LongBridge、Firstrade 等平台仓库只负责加载 artifac
 
 - `crisis_response_shadow`：面向杠杆美股策略的黑天鹅防守观察插件。它只写入 shadow-mode artifact，不调用券商接口。
   可选启用 AI shadow audit：AI 只审计证据一致性和数据缺口，不改写确定性路线、不下单、不改仓位；默认优先尝试本机 Codex，失败后可走 OpenAI-compatible 或 Anthropic fallback endpoint。
+- `macro_risk_governor`：面向 TQQQ 的确定性宏观降杠杆插件。它按价格趋势、实现波动、VIX 和信用 ETF 相对压力打分，输出 `leverage_scalar` / `risk_asset_scalar` 给显式 opt-in 的策略运行时消费。HY OAS、金融压力指数、五角大楼比萨指数、Fear & Greed、put/call、VVIX、SKEW、MOVE、收益率曲线、美元压力、safe-haven demand 等外部硬数据、OSINT、情绪或跨资产字段默认只作为 watch-only 证据，不进入可执行分数；只有显式研究开关开启后才允许外部压力字段参与自动分数。
+- `market_regime_control`：统一确定性 facade，汇总 crisis、macro 和 TACO 信号，输出版本化的 `notification` 和 `position_control`。只有经过回测证明自动消费有效的策略才挂载仓位控制；SOXL/SOXX 这类未通过统一宏观插件复核的高波动行业杠杆策略只接收通用通知，人工决定是否干预。股票/ETF 轮动策略通过本地风险缩放策略消费；TACO 在统一插件里保持通知-only，并会被危机和宏观降风险路线 veto。设计说明见 [Market Regime Control 统一插件方案](docs/market-regime-control-plan.zh-CN.md)。
 - `taco_rebound_shadow`：仅适用于 TQQQ 的事件反弹上下文通知插件。它只写入人工复核 artifact，不给仓位大小建议，也不改动配置或账户分配。缓和/降温事件会先保持 watch-only，只有事件后价格反弹确认通过后才触发人工复核通知，以减少过早抄底提醒。
   该插件也可选启用同样的 shadow-only AI audit，但 AI 只复核事件来源和反弹证据质量。
 - TACO panic-rebound 研究、组合回测和 overlay 对比也归属本仓库；snapshot pipeline 仓库只保留兼容入口。
@@ -47,6 +49,21 @@ qsp-build-crisis-response-shadow-signal \
   --output-dir data/output/tqqq_growth_income/plugins/crisis_response_shadow
 ```
 
+生成宏观和统一市场状态插件使用的公开硬数据 `external_context` CSV：
+
+```bash
+qsp-build-macro-external-context \
+  --start 1999-01-01 \
+  --output data/output/market_regime_control/input/external_context.csv
+```
+
+构建器会尽量下载公开 FRED/CBOE 字段：VIX、VIX3M、VVIX、SKEW、Cboe
+put/call、HY/IG OAS、金融压力指数、收益率曲线、贸易加权美元压力和
+TED/funding stress。CNN Fear & Greed、AAII、NAAIM、五角大楼比萨指数、
+MOVE、市场宽度等没有稳定免登录历史源的字段，可以通过 `--manual-context`
+提供。OAS 覆盖范围以 FRED 公开 graph endpoint 实际返回为准；如果需要更早的
+本地归档 OAS 历史，也通过同一个 manual context 注入。
+
 AI audit 使用环境变量读取 API 配置：
 
 - `QSP_STRATEGY_PLUGIN_AI_AUDIT_CODEX_ENABLED`，默认 `true`
@@ -73,6 +90,20 @@ qsp-build-taco-rebound-shadow-signal \
 
 输出包括 `latest_signal.json`、按日期归档的 JSON、按日期归档的 CSV，以及 evidence CSV。平台运行时通过 `*_STRATEGY_PLUGIN_MOUNTS_JSON` 挂载的就是 `latest_signal.json`。
 
+## 通知和日志 i18n
+
+通过 strategy plugin runner 生成的 artifact 会附带展示层 i18n 字段：
+
+- `localized_messages.schema_version = strategy_plugin_messages.v1`
+- `localized_messages.notification.en-US` / `localized_messages.notification.zh-CN`
+- `localized_messages.log.en-US` / `localized_messages.log.zh-CN`
+- `log_record.schema_version = strategy_plugin_log.v1`
+- `market_regime_control.notification.localized_message_schema_version`
+
+策略和券商运行时的交易逻辑仍应只读取 `schema_version`、`canonical_route`、
+`suggested_action`、`reason_codes` 和 `position_control` 等机器字段。中英文文案只用于通知界面和日志展示，不参与策略判断。`market_regime_control.notification`
+会同步包含本地化通知文案和原因标签，方便现有通知代码直接渲染，不需要在策略仓库里重复翻译 route/action code。
+
 ## 本地检查
 
 ```bash

docs/examples/strategy_plugins.example.toml

@@ -3,11 +3,84 @@ default_mode = "shadow"
 
 [[strategy_plugins]]
 strategy = "tqqq_growth_income"
-plugin = "crisis_response_shadow"
+plugin = "market_regime_control"
 enabled = true
-# The runner enforces plugin/strategy compatibility. This plugin is scoped to
-# TQQQ/SOXL leveraged equity black-swan defense strategies.
-# mode is optional when it matches default_mode; only shadow notification mode is supported.
+# Default runtime contract. This facade arbitrates crisis_response_shadow,
+# macro_risk_governor, and taco_rebound_shadow into one deterministic signal.
+# Strategy code consumes only notification and position_control from this
+# artifact; broker writes and live allocation mutation remain disabled.
+# Runner artifacts include en-US/zh-CN localized_messages and log_record for
+# display/logging. Strategy logic should still read machine route/action codes.
+
+[strategy_plugins.inputs]
+prices = "data/output/market_regime_control/input/tqqq_price_history.csv"
+# Build with:
+# qsp-build-macro-external-context --start 1999-01-01 --output data/output/market_regime_control/input/external_context.csv
+external_context = "data/output/market_regime_control/input/external_context.csv"
+event_set = "geopolitical-deescalation"
+benchmark_symbol = "QQQ"
+attack_symbol = "TQQQ"
+vix_symbols = ["VIX", "^VIX", "VIXCLS"]
+vix3m_symbols = ["VIX3M", "^VIX3M", "VXV", "^VXV"]
+credit_pairs = ["HYG:IEF", "LQD:IEF"]
+financial_symbols = ["XLF", "KRE"]
+rate_symbols = ["IEF", "TLT"]
+strategy_policy = "levered_growth_income_v1"
+realized_vol_threshold = 0.30
+realized_vol_requires_confirmation = true
+# Fixed production default after external-context backtest: external hard-data
+# stress fields are notification/watch evidence unless this research switch is
+# explicitly enabled.
+external_stress_actionable = false
+delever_risk_asset_scalar = 0.0
+taco_opportunity_size_scalar = 0.0
+crisis_enabled = true
+macro_enabled = true
+taco_enabled = true
+
+[strategy_plugins.outputs]
+output_dir = "data/output/tqqq_growth_income/plugins/market_regime_control"
+
+[[strategy_plugins]]
+strategy = "market_regime_notification"
+plugin = "market_regime_control"
+enabled = true
+# General market-regime notification. This artifact is not mounted into the
+# SOXL/SOXX strategy runtime; sector-levered SOXL keeps its own validated SOXX
+# volatility gate and humans decide whether broad macro/crisis notices matter.
+
+[strategy_plugins.inputs]
+prices = "data/output/market_regime_control/input/soxl_price_history.csv"
+external_context = "data/output/market_regime_control/input/external_context.csv"
+event_set = "full"
+benchmark_symbol = "SOXX"
+attack_symbol = "SOXL"
+vix_symbols = ["VIX", "^VIX", "VIXCLS"]
+vix3m_symbols = ["VIX3M", "^VIX3M", "VXV", "^VXV"]
+credit_pairs = ["HYG:IEF", "LQD:IEF"]
+financial_symbols = ["XLF", "KRE"]
+rate_symbols = ["IEF", "TLT"]
+strategy_policy = "levered_growth_income_v1"
+realized_vol_threshold = 0.30
+realized_vol_requires_confirmation = true
+external_stress_actionable = false
+delever_risk_asset_scalar = 0.0
+taco_enabled = false
+crisis_enabled = true
+macro_enabled = true
+
+[strategy_plugins.outputs]
+output_dir = "data/output/market_regime_notification/plugins/market_regime_control"
+
+# Deprecated compatibility mounts. They remain runnable for historical
+# backtests and downstream consumers that have not migrated to
+# market_regime_control yet. New strategy integrations should not read them
+# directly.
+
+[[strategy_plugins]]
+strategy = "tqqq_growth_income"
+plugin = "crisis_response_shadow"
+enabled = false
 
 [strategy_plugins.inputs]
 prices = "data/output/crisis_response_shadow/input/price_history.csv"
@@ -16,41 +89,37 @@ event_set = "full"
 financial_symbols = ["XLF", "KRE"]
 credit_pairs = ["HYG:IEF", "LQD:IEF"]
 rate_symbols = ["IEF", "TLT"]
-# Optional shadow-only AI audit. API keys are read from env vars, not TOML:
-# QSP_STRATEGY_PLUGIN_AI_AUDIT_API_KEY / QSP_STRATEGY_PLUGIN_AI_AUDIT_FALLBACK_API_KEY
-# Legacy QSP_CRISIS_AI_AUDIT_* names are still accepted.
-ai_audit_enabled = true
-ai_audit_codex_enabled = true
-ai_audit_model = "gpt-5.4-mini"
-# ai_audit_base_url = "https://api.openai.com/v1"
-# ai_audit_fallback_base_url = "https://fallback.example.com/v1"
-# ai_audit_fallback_model = "fallback-model"
-# Anthropic fallback follows the CryptoCodexAuditBridge provider-fallback style.
-# ai_audit_anthropic_model = "claude-sonnet-4-6"
-# ai_audit_anthropic_base_url = "https://api.anthropic.com/v1"
-# ai_audit_anthropic_version = "2023-06-01"
 
 [strategy_plugins.outputs]
 output_dir = "data/output/tqqq_growth_income/plugins/crisis_response_shadow"
 
+[[strategy_plugins]]
+strategy = "tqqq_growth_income"
+plugin = "macro_risk_governor"
+enabled = false
+
+[strategy_plugins.inputs]
+prices = "data/output/macro_risk_governor/input/price_history.csv"
+external_context = "data/output/macro_risk_governor/input/external_context.csv"
+benchmark_symbol = "QQQ"
+attack_symbol = "TQQQ"
+vix_symbols = ["VIX", "^VIX", "VIXCLS"]
+vix3m_symbols = ["VIX3M", "^VIX3M", "VXV", "^VXV"]
+credit_pairs = ["HYG:IEF", "LQD:IEF"]
+external_stress_actionable = false
+
+[strategy_plugins.outputs]
+output_dir = "data/output/tqqq_growth_income/plugins/macro_risk_governor"
+
 [[strategy_plugins]]
 strategy = "tqqq_growth_income"
 plugin = "taco_rebound_shadow"
-enabled = true
-# Notification-only TACO context. The artifact may trigger manual-review alerts,
-# but it never recommends position size or mutates allocations.
-# Manual-review alerts require post-event price rebound confirmation by default.
+enabled = false
 
 [strategy_plugins.inputs]
 prices = "data/output/taco_rebound_shadow/input/price_history.csv"
 event_set = "geopolitical-deescalation"
 start_date = "2026-01-01"
-# Optional shadow-only AI audit for event/source quality. It cannot alter the
-# manual-review/watch-only route or generate allocation/order instructions.
-ai_audit_enabled = true
-ai_audit_codex_enabled = true
-ai_audit_model = "gpt-5.4-mini"
-# ai_audit_anthropic_model = "claude-sonnet-4-6"
 
 [strategy_plugins.outputs]
 output_dir = "data/output/tqqq_growth_income/plugins/taco_rebound_shadow"