Add plugin consumption policy registry

Author: Pigbibi

README.md

@@ -35,8 +35,9 @@ send notifications; plugin research and signal generation live here.
   optional external financial-stress fields. The artifact can expose
   `leverage_scalar` and `risk_asset_scalar` to strategy runtimes that explicitly
   opt in through mounted metadata. OSINT-style fields such as a Pentagon pizza
-  index are kept as watch-only evidence and do not contribute to the actionable
-  trading score.
+  index, plus sentiment fields such as Fear & Greed, put/call, and safe-haven
+  demand, are kept as watch-only evidence and do not contribute to the
+  actionable trading score.
 - `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

README.zh-CN.md

@@ -25,7 +25,7 @@ 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、信用相对压力和可选外部金融压力字段打分，输出 `leverage_scalar` / `risk_asset_scalar` 给显式 opt-in 的策略运行时消费。五角大楼比萨指数这类 OSINT 字段只作为 watch-only 证据，不进入可执行分数。
+- `macro_risk_governor`：面向 TQQQ 的确定性宏观降杠杆插件。它按价格趋势、实现波动、VIX、信用相对压力和可选外部金融压力字段打分，输出 `leverage_scalar` / `risk_asset_scalar` 给显式 opt-in 的策略运行时消费。五角大楼比萨指数、Fear & Greed、put/call、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 只复核事件来源和反弹证据质量。

docs/market-regime-control-plan.zh-CN.md

@@ -26,7 +26,7 @@
 - `crisis_response_shadow`
   负责硬危机防守。`true_crisis` 和泡沫脆弱性触发后，统一插件输出 `risk_off` / `defend`，仓位目标交给策略侧 opt-in 执行。
 - `macro_risk_governor`
-  负责宏观降杠杆。它看价格趋势、实现波动、VIX、信用相对压力和可选金融压力字段，输出 `risk_reduced` 或 `risk_off`。
+  负责宏观降杠杆。它看价格趋势、实现波动、VIX、信用相对压力和可选金融压力字段，输出 `risk_reduced` 或 `risk_off`。Fear & Greed、put/call、safe-haven demand 和五角大楼比萨指数只作为 watch-only 证据，先用于通知和回测观察。
 - `taco_rebound_shadow`
   负责 TQQQ 事件反弹通知。它输出人工复核通知和本地 veto 线索，不直接提高仓位。
 
@@ -71,13 +71,23 @@
 
 旧插件仍可运行历史回测和兼容输出，但新策略集成应优先挂载 `market_regime_control`。
 
+策略插件 runner 使用显式消费权限 registry，而不是只维护松散 allowlist：
+
+- `notification_allowed`：允许生成和分发通知 artifact。
+- `position_control_allowed`：允许策略 runtime 自动消费仓位控制字段。
+- `evidence_status`：记录该策略/插件组合是 `automation_approved`、`notification_only` 还是 `deprecated_compatibility`。
+- `since_version`：记录该消费权限从哪个 runner schema 开始生效。
+
+SOXL/SOXX 不出现在 `market_regime_control` 的策略级消费 registry 中；它通过 `market_regime_notification` 接收通用通知，避免配置误用把通知信号升级成自动调仓。
+
 ## 版本管理
 
 当前对外契约是：
 
 - 统一插件 schema：`market_regime_control.v1`
 - 仲裁器 schema：`market_regime_arbiter.v1`
 - 运行器总 schema：`strategy_plugins.v1`
+- 策略消费权限 schema：随 `strategy_plugins.v1` 通过 `consumption_policy` 输出
 
 升级原则：
 

src/quant_strategy_plugins/macro_risk_governor_plugin.py

@@ -258,6 +258,9 @@ def build_macro_risk_governor_signal(
     hy_oas_delta_threshold: float = 1.0,
     financial_stress_watch_level: float = 1.0,
     pizza_index_watch_level: float = 2.0,
+    fear_greed_extreme_fear_level: float = 25.0,
+    put_call_watch_level: float = 1.20,
+    safe_haven_demand_watch_level: float = 1.0,
     watch_score_threshold: float = 3.0,
     delever_score_threshold: float = 5.0,
     crisis_score_threshold: float = 7.0,
@@ -448,6 +451,53 @@ def build_macro_risk_governor_signal(
         threshold=float(pizza_index_watch_level),
         actionable=False,
     )
+    fear_greed_index = _external_float(
+        external_row,
+        "fear_greed_index",
+        "fear_and_greed_index",
+        "cnn_fear_greed_index",
+        "cnn_fear_and_greed_index",
+    )
+    _add_check(
+        checks,
+        "fear_greed_extreme_fear_watch",
+        fear_greed_index is not None and fear_greed_index <= float(fear_greed_extreme_fear_level),
+        weight=1.0,
+        value=fear_greed_index,
+        threshold=float(fear_greed_extreme_fear_level),
+        actionable=False,
+    )
+    put_call_ratio = _external_float(
+        external_row,
+        "put_call_ratio",
+        "equity_put_call_ratio",
+        "cboe_put_call_ratio",
+        "put_call",
+    )
+    _add_check(
+        checks,
+        "put_call_stress_watch",
+        put_call_ratio is not None and put_call_ratio >= float(put_call_watch_level),
+        weight=1.0,
+        value=put_call_ratio,
+        threshold=float(put_call_watch_level),
+        actionable=False,
+    )
+    safe_haven_demand = _external_float(
+        external_row,
+        "safe_haven_demand",
+        "safe_haven_demand_index",
+        "safe_haven_demand_zscore",
+    )
+    _add_check(
+        checks,
+        "safe_haven_demand_watch",
+        safe_haven_demand is not None and safe_haven_demand >= float(safe_haven_demand_watch_level),
+        weight=1.0,
+        value=safe_haven_demand,
+        threshold=float(safe_haven_demand_watch_level),
+        actionable=False,
+    )
     realized_vol_confirmed_for_action = None
     realized_vol_check = checks.get("benchmark_realized_volatility_high")
     if realized_vol_check is not None:
@@ -476,6 +526,9 @@ def build_macro_risk_governor_signal(
             "hy_oas_delta_63d": hy_oas_delta,
             "financial_stress": financial_stress,
             "pentagon_pizza_index": pizza_index,
+            "fear_greed_index": fear_greed_index,
+            "put_call_ratio": put_call_ratio,
+            "safe_haven_demand": safe_haven_demand,
             "benchmark_realized_volatility_requires_confirmation": bool(realized_vol_requires_confirmation),
             "benchmark_realized_volatility_confirmed_for_action": realized_vol_confirmed_for_action,
         }

src/quant_strategy_plugins/strategy_plugin_runner.py

@@ -39,19 +39,9 @@
 PLUGIN_MACRO_RISK_GOVERNOR = MACRO_RISK_GOVERNOR_PROFILE
 PLUGIN_TACO_REBOUND_SHADOW = TACO_REBOUND_PROFILE
 SUPPORTED_PLUGIN_MODES = (SHADOW_MODE,)
-PLUGIN_COMPATIBLE_STRATEGIES: dict[str, tuple[str, ...]] = {
-    PLUGIN_CRISIS_RESPONSE_SHADOW: ("tqqq_growth_income",),
-    PLUGIN_MARKET_REGIME_CONTROL: (
-        GENERAL_MARKET_REGIME_NOTIFICATION_STRATEGY,
-        "tqqq_growth_income",
-        "global_etf_rotation",
-        "russell_1000_multi_factor_defensive",
-        "tech_communication_pullback_enhancement",
-        "mega_cap_leader_rotation_top50_balanced",
-    ),
-    PLUGIN_MACRO_RISK_GOVERNOR: ("tqqq_growth_income",),
-    PLUGIN_TACO_REBOUND_SHADOW: ("tqqq_growth_income",),
-}
+EVIDENCE_AUTOMATION_APPROVED = "automation_approved"
+EVIDENCE_NOTIFICATION_ONLY = "notification_only"
+EVIDENCE_DEPRECATED_COMPATIBILITY = "deprecated_compatibility"
 PLUGIN_SCHEMA_VERSIONS: dict[str, tuple[str, ...]] = {
     PLUGIN_CRISIS_RESPONSE_SHADOW: ("crisis_response_shadow.v1",),
     PLUGIN_MARKET_REGIME_CONTROL: ("market_regime_control.v1",),
@@ -79,6 +69,115 @@ class PluginRunResult:
     message: str = ""
 
 
+@dataclass(frozen=True)
+class PluginConsumptionPolicy:
+    plugin: str
+    strategy: str
+    notification_allowed: bool
+    position_control_allowed: bool
+    evidence_status: str
+    since_version: str
+    description: str
+    intended_strategy_role: str | None = None
+
+
+PLUGIN_CONSUMPTION_POLICIES: tuple[PluginConsumptionPolicy, ...] = (
+    PluginConsumptionPolicy(
+        plugin=PLUGIN_MARKET_REGIME_CONTROL,
+        strategy=GENERAL_MARKET_REGIME_NOTIFICATION_STRATEGY,
+        notification_allowed=True,
+        position_control_allowed=False,
+        evidence_status=EVIDENCE_NOTIFICATION_ONLY,
+        since_version="strategy_plugins.v1",
+        description="General market-regime notice. Not mounted into an automated strategy runtime.",
+        intended_strategy_role="general_market_regime_notification",
+    ),
+    PluginConsumptionPolicy(
+        plugin=PLUGIN_MARKET_REGIME_CONTROL,
+        strategy="tqqq_growth_income",
+        notification_allowed=True,
+        position_control_allowed=True,
+        evidence_status=EVIDENCE_AUTOMATION_APPROVED,
+        since_version="strategy_plugins.v1",
+        description="Backtested automatic macro/crisis risk controls for the TQQQ growth-income strategy.",
+    ),
+    PluginConsumptionPolicy(
+        plugin=PLUGIN_MARKET_REGIME_CONTROL,
+        strategy="global_etf_rotation",
+        notification_allowed=True,
+        position_control_allowed=True,
+        evidence_status=EVIDENCE_AUTOMATION_APPROVED,
+        since_version="strategy_plugins.v1",
+        description="Local risk-scaling consumer for broad ETF rotation.",
+    ),
+    PluginConsumptionPolicy(
+        plugin=PLUGIN_MARKET_REGIME_CONTROL,
+        strategy="russell_1000_multi_factor_defensive",
+        notification_allowed=True,
+        position_control_allowed=True,
+        evidence_status=EVIDENCE_AUTOMATION_APPROVED,
+        since_version="strategy_plugins.v1",
+        description="Local risk-scaling consumer for the Russell 1000 defensive sleeve.",
+    ),
+    PluginConsumptionPolicy(
+        plugin=PLUGIN_MARKET_REGIME_CONTROL,
+        strategy="tech_communication_pullback_enhancement",
+        notification_allowed=True,
+        position_control_allowed=True,
+        evidence_status=EVIDENCE_AUTOMATION_APPROVED,
+        since_version="strategy_plugins.v1",
+        description="Local risk-scaling consumer for the tech/communication pullback profile.",
+    ),
+    PluginConsumptionPolicy(
+        plugin=PLUGIN_MARKET_REGIME_CONTROL,
+        strategy="mega_cap_leader_rotation_top50_balanced",
+        notification_allowed=True,
+        position_control_allowed=True,
+        evidence_status=EVIDENCE_AUTOMATION_APPROVED,
+        since_version="strategy_plugins.v1",
+        description="Local risk-scaling consumer for the mega-cap leader rotation profile.",
+    ),
+    PluginConsumptionPolicy(
+        plugin=PLUGIN_CRISIS_RESPONSE_SHADOW,
+        strategy="tqqq_growth_income",
+        notification_allowed=True,
+        position_control_allowed=False,
+        evidence_status=EVIDENCE_DEPRECATED_COMPATIBILITY,
+        since_version="strategy_plugins.v1",
+        description="Deprecated direct crisis shadow mount kept for historical replay; new consumers use market_regime_control.",
+    ),
+    PluginConsumptionPolicy(
+        plugin=PLUGIN_MACRO_RISK_GOVERNOR,
+        strategy="tqqq_growth_income",
+        notification_allowed=True,
+        position_control_allowed=False,
+        evidence_status=EVIDENCE_DEPRECATED_COMPATIBILITY,
+        since_version="strategy_plugins.v1",
+        description="Deprecated direct macro governor mount kept for historical replay; new consumers use market_regime_control.",
+    ),
+    PluginConsumptionPolicy(
+        plugin=PLUGIN_TACO_REBOUND_SHADOW,
+        strategy="tqqq_growth_income",
+        notification_allowed=True,
+        position_control_allowed=False,
+        evidence_status=EVIDENCE_NOTIFICATION_ONLY,
+        since_version="strategy_plugins.v1",
+        description="Manual-review event rebound notifier for TQQQ only.",
+    ),
+)
+PLUGIN_CONSUMPTION_POLICY_REGISTRY: dict[tuple[str, str], PluginConsumptionPolicy] = {
+    (policy.plugin, policy.strategy): policy for policy in PLUGIN_CONSUMPTION_POLICIES
+}
+PLUGIN_COMPATIBLE_STRATEGIES: dict[str, tuple[str, ...]] = {
+    plugin: tuple(
+        policy.strategy
+        for policy in PLUGIN_CONSUMPTION_POLICIES
+        if policy.plugin == plugin and policy.notification_allowed
+    )
+    for plugin in sorted({policy.plugin for policy in PLUGIN_CONSUMPTION_POLICIES})
+}
+
+
 PluginRunner = Callable[[Mapping[str, Any], str], PluginRunResult]
 PluginPayloadBuilder = Callable[[pd.DataFrame, Mapping[str, Any]], dict[str, Any]]
 PluginOutputWriter = Callable[[Mapping[str, Any], str | Path], Mapping[str, Path]]
@@ -159,14 +258,19 @@ def _validate_plugin_strategy(plugin_name: str, strategy: str) -> None:
         raise ValueError(
             f"{plugin_name} is research-only and cannot be mounted to {strategy!r}: {research_only_reason}"
         )
-    compatible = PLUGIN_COMPATIBLE_STRATEGIES.get(plugin_name, ())
-    if compatible and strategy not in compatible:
-        choices = ", ".join(compatible)
+    policy = PLUGIN_CONSUMPTION_POLICY_REGISTRY.get((plugin_name, strategy))
+    if policy is None or not policy.notification_allowed:
+        compatible = PLUGIN_COMPATIBLE_STRATEGIES.get(plugin_name, ())
+        choices = ", ".join(compatible) if compatible else "(none)"
         raise ValueError(
             f"{plugin_name} is strategy-limited and can only be mounted to: {choices}; got strategy={strategy!r}"
         )
 
 
+def _plugin_consumption_policy(plugin_name: str, strategy: str) -> PluginConsumptionPolicy | None:
+    return PLUGIN_CONSUMPTION_POLICY_REGISTRY.get((plugin_name, strategy))
+
+
 def _flatten_strategy_plugin_entry(entry: Mapping[str, Any]) -> dict[str, Any]:
     plugin_config = {
         key: value
@@ -333,6 +437,9 @@ def _build_macro_risk_governor_kwargs(plugin_config: Mapping[str, Any]) -> dict[
         "hy_oas_delta_threshold",
         "financial_stress_watch_level",
         "pizza_index_watch_level",
+        "fear_greed_extreme_fear_level",
+        "put_call_watch_level",
+        "safe_haven_demand_watch_level",
         "watch_score_threshold",
         "delever_score_threshold",
         "crisis_score_threshold",
@@ -389,21 +496,34 @@ def _mode_execution_controls(mode: str) -> dict[str, Any]:
         raise ValueError(f"unsupported plugin mode: {mode!r}") from exc
 
 
-def _apply_plugin_contract(payload: Mapping[str, Any], *, strategy: str, plugin: str, mode: str) -> dict[str, Any]:
+def _apply_plugin_contract(
+    payload: Mapping[str, Any],
+    *,
+    strategy: str,
+    plugin: str,
+    mode: str,
+    consumption_policy: PluginConsumptionPolicy | None = None,
+) -> dict[str, Any]:
     contracted_payload = dict(payload)
     contracted_payload["strategy"] = strategy
     contracted_payload["plugin"] = plugin
     contracted_payload["mode"] = mode
     contracted_payload["configured_mode"] = mode
     contracted_payload["effective_mode"] = mode
+    if consumption_policy is not None:
+        contracted_payload["consumption_policy"] = asdict(consumption_policy)
 
     execution_controls = dict(contracted_payload.get("execution_controls") or {})
     execution_controls.update(_mode_execution_controls(mode))
     execution_controls["configured_mode"] = mode
     execution_controls["effective_mode"] = mode
     execution_controls["repository_broker_write_allowed"] = False
     execution_controls["repository_allocation_mutation_allowed"] = False
-    if strategy == GENERAL_MARKET_REGIME_NOTIFICATION_STRATEGY:
+    if consumption_policy is not None:
+        execution_controls["notification_allowed"] = bool(consumption_policy.notification_allowed)
+        execution_controls["position_control_allowed"] = bool(consumption_policy.position_control_allowed)
+        execution_controls["consumption_evidence_status"] = consumption_policy.evidence_status
+    if consumption_policy is not None and consumption_policy.intended_strategy_role == "general_market_regime_notification":
         execution_controls["capital_impact"] = "notification_only"
         execution_controls["strategy_runtime_metadata_allowed"] = False
         execution_controls["position_control_shadow_only"] = True
@@ -482,12 +602,20 @@ def _run_table_strategy_plugin(
             message="plugin disabled",
         )
     _validate_plugin_mode(plugin, mode)
+    _validate_plugin_strategy(plugin, strategy)
+    consumption_policy = _plugin_consumption_policy(plugin, strategy)
 
     prices_path = str(plugin_config.get("prices", "")).strip()
     if not prices_path:
         raise ValueError(f"{plugin} for strategy={strategy} requires a prices path")
     payload = spec.build_payload(read_table(prices_path), plugin_config)
-    payload = _apply_plugin_contract(payload, strategy=strategy, plugin=plugin, mode=mode)
+    payload = _apply_plugin_contract(
+        payload,
+        strategy=strategy,
+        plugin=plugin,
+        mode=mode,
+        consumption_policy=consumption_policy,
+    )
     paths = spec.write_outputs(payload, output_dir)
     return PluginRunResult(
         strategy=strategy,
@@ -640,9 +768,12 @@ def main(argv: list[str] | None = None) -> int:
     "PLUGIN_MACRO_RISK_GOVERNOR",
     "PLUGIN_TACO_REBOUND_SHADOW",
     "PLUGIN_COMPATIBLE_STRATEGIES",
+    "PLUGIN_CONSUMPTION_POLICIES",
+    "PLUGIN_CONSUMPTION_POLICY_REGISTRY",
     "PLUGIN_DEPRECATED_SUCCESSORS",
     "PLUGIN_RESEARCH_ONLY_REASONS",
     "PLUGIN_SCHEMA_VERSIONS",
+    "PluginConsumptionPolicy",
     "PluginRunResult",
     "load_plugin_config",
     "main",