Make TACO rebound plugin notification-only

Author: Pigbibi

README.md

@@ -26,8 +26,11 @@ send notifications; plugin research and signal generation live here.
 
 - `crisis_response_shadow`: black-swan defense observer for leveraged US equity
   strategies. It writes shadow-mode artifacts and never calls brokers.
-- `taco_rebound_shadow`: research-only rebound-budget observer. The generic
-  runner keeps it gated until promotion criteria are met.
+- `taco_rebound_shadow`: TQQQ-only event-rebound context notifier. It writes
+  manual-review artifacts and never recommends position size or changes
+  allocations.
+- TACO panic-rebound research and portfolio/overlay backtests also live here;
+  snapshot pipeline repositories keep only compatibility entrypoints.
 
 ## Usage
 
@@ -46,6 +49,16 @@ qsp-build-crisis-response-shadow-signal \
   --output-dir data/output/tqqq_growth_income/plugins/crisis_response_shadow
 ```
 
+Build a TACO rebound notification artifact directly from a local price-history CSV:
+
+```bash
+qsp-build-taco-rebound-shadow-signal \
+  --prices data/input/price_history.csv \
+  --event-set geopolitical-deescalation \
+  --as-of 2026-05-22 \
+  --output-dir data/output/tqqq_growth_income/plugins/taco_rebound_shadow
+```
+
 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`.

README.zh-CN.md

@@ -24,7 +24,8 @@ Brokers、Schwab、LongBridge、Firstrade 等平台仓库只负责加载 artifac
 ## 插件
 
 - `crisis_response_shadow`：面向杠杆美股策略的黑天鹅防守观察插件。它只写入 shadow-mode artifact，不调用券商接口。
-- `taco_rebound_shadow`：研究阶段的反弹预算观察插件。通用 runner 会保持 gating，直到后续验证和晋级标准满足。
+- `taco_rebound_shadow`：仅适用于 TQQQ 的事件反弹上下文通知插件。它只写入人工复核 artifact，不给仓位大小建议，也不改动配置或账户分配。
+- TACO panic-rebound 研究、组合回测和 overlay 对比也归属本仓库；snapshot pipeline 仓库只保留兼容入口。
 
 ## 使用方式
 
@@ -43,6 +44,16 @@ qsp-build-crisis-response-shadow-signal \
   --output-dir data/output/tqqq_growth_income/plugins/crisis_response_shadow
 ```
 
+从本地价格历史 CSV 直接生成 TACO 反弹通知 artifact：
+
+```bash
+qsp-build-taco-rebound-shadow-signal \
+  --prices data/input/price_history.csv \
+  --event-set geopolitical-deescalation \
+  --as-of 2026-05-22 \
+  --output-dir data/output/tqqq_growth_income/plugins/taco_rebound_shadow
+```
+
 输出包括 `latest_signal.json`、按日期归档的 JSON、按日期归档的 CSV，以及 evidence CSV。平台运行时通过 `*_STRATEGY_PLUGIN_MOUNTS_JSON` 挂载的就是 `latest_signal.json`。
 
 ## 本地检查

docs/examples/strategy_plugins.example.toml

@@ -19,3 +19,18 @@ rate_symbols = ["IEF", "TLT"]
 
 [strategy_plugins.outputs]
 output_dir = "data/output/tqqq_growth_income/plugins/crisis_response_shadow"
+
+[[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.
+
+[strategy_plugins.inputs]
+prices = "data/output/taco_rebound_shadow/input/price_history.csv"
+event_set = "geopolitical-deescalation"
+start_date = "2026-01-01"
+
+[strategy_plugins.outputs]
+output_dir = "data/output/tqqq_growth_income/plugins/taco_rebound_shadow"

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quant-strategy-plugins"
-version = "0.1.0"
+version = "0.1.1"
 description = "Open sidecar strategy plugins that emit QuantPlatformKit-compatible signal artifacts."
 readme = "README.md"
 requires-python = ">=3.11"

src/quant_strategy_plugins/strategy_plugin_runner.py

@@ -28,13 +28,9 @@
 SUPPORTED_PLUGIN_MODES = (SHADOW_MODE,)
 PLUGIN_COMPATIBLE_STRATEGIES: dict[str, tuple[str, ...]] = {
     PLUGIN_CRISIS_RESPONSE_SHADOW: ("tqqq_growth_income", "soxl_soxx_trend_income"),
+    PLUGIN_TACO_REBOUND_SHADOW: ("tqqq_growth_income",),
 }
-PLUGIN_RESEARCH_ONLY_REASONS: dict[str, str] = {
-    PLUGIN_TACO_REBOUND_SHADOW: (
-        "MAGS TACO rebound is research-only for now; use the standalone research builder/backtests, "
-        "and promote a separate TQQQ TACO overlay plugin only after its own validation."
-    ),
-}
+PLUGIN_RESEARCH_ONLY_REASONS: dict[str, str] = {}
 
 
 @dataclass(frozen=True)
@@ -230,10 +226,6 @@ def _build_taco_rebound_kwargs(plugin_config: Mapping[str, Any]) -> dict[str, An
         "attack_symbol",
     }
     numeric_keys = {
-        "tariff_softening_sleeve",
-        "geopolitical_deescalation_sleeve",
-        "shock_sleeve",
-        "max_sleeve",
         "crisis_guard_drawdown",
     }
     integer_keys = {

src/quant_strategy_plugins/taco_rebound_shadow_plugin.py

@@ -22,30 +22,24 @@
 )
 from .taco_panic_rebound_research import (
     DEFAULT_EVENT_SET,
-    EVENT_KIND_SHOCK,
     EVENT_KIND_SOFTENING,
     TRADE_WAR_EVENT_SETS,
     TradeWarEvent,
     resolve_trade_war_event_set,
 )
 from .yfinance_prices import download_price_history
 
-SCHEMA_VERSION = "taco_rebound_shadow.v1"
+SCHEMA_VERSION = "taco_rebound_shadow.v2"
 SHADOW_MODE = "shadow"
 TACO_REBOUND_PROFILE = "taco_rebound_shadow"
 ROUTE_TACO_REBOUND = "taco_rebound"
-ACTION_INCREASE_REBOUND_BUDGET = "increase_rebound_budget"
+ACTION_NOTIFY_MANUAL_REVIEW = "notify_manual_review"
 ACTION_WATCH_ONLY = "watch_only"
 ACTION_NO_ACTION = "no_action"
-ACTION_BLOCKED = "blocked"
 DEFAULT_OUTPUT_DIR = "data/output/taco_rebound_shadow"
 DEFAULT_START_DATE = "2018-01-01"
 DEFAULT_MAX_PRICE_AGE_DAYS = 4
 DEFAULT_ACTIVE_SIGNAL_DAYS = 10
-DEFAULT_TARIFF_SOFTENING_SLEEVE = 0.05
-DEFAULT_GEOPOLITICAL_DEESCALATION_SLEEVE = 0.10
-DEFAULT_SHOCK_SLEEVE = 0.0
-DEFAULT_MAX_SLEEVE = 0.10
 HARD_DEFENSE_BREAK_BEAR_REGIONS = frozenset({"iran_middle_east"})
 
 
@@ -57,29 +51,18 @@ def _next_index_date(index: pd.DatetimeIndex, raw_date: str | pd.Timestamp) -> p
     return pd.Timestamp(candidates[0]).normalize()
 
 
-def _event_sleeve(
-    event: TradeWarEvent,
-    *,
-    tariff_softening_sleeve: float,
-    geopolitical_deescalation_sleeve: float,
-    shock_sleeve: float,
-    max_sleeve: float,
-) -> float:
-    if event.kind == EVENT_KIND_SHOCK:
-        sleeve = float(shock_sleeve)
-    elif str(event.region).strip().lower() == "iran_middle_east":
-        sleeve = float(geopolitical_deescalation_sleeve)
-    else:
-        sleeve = float(tariff_softening_sleeve)
-    return max(0.0, min(float(max_sleeve), sleeve))
-
-
 def _event_allows_hard_defense(event: TradeWarEvent | None) -> bool:
     if event is None or event.kind != EVENT_KIND_SOFTENING:
         return False
     return str(event.region).strip().lower() in HARD_DEFENSE_BREAK_BEAR_REGIONS
 
 
+def _event_notice_priority(event: TradeWarEvent) -> tuple[int, int, str]:
+    kind_priority = 1 if event.kind == EVENT_KIND_SOFTENING else 0
+    region_priority = 1 if str(event.region).strip().lower() in HARD_DEFENSE_BREAK_BEAR_REGIONS else 0
+    return kind_priority, region_priority, str(event.event_date)
+
+
 def _active_recognized_events(
     events: Sequence[TradeWarEvent],
     *,
@@ -107,10 +90,6 @@ def build_taco_rebound_shadow_signal(
     benchmark_symbol: str = DEFAULT_BENCHMARK_SYMBOL,
     attack_symbol: str = DEFAULT_ATTACK_SYMBOL,
     active_signal_days: int = DEFAULT_ACTIVE_SIGNAL_DAYS,
-    tariff_softening_sleeve: float = DEFAULT_TARIFF_SOFTENING_SLEEVE,
-    geopolitical_deescalation_sleeve: float = DEFAULT_GEOPOLITICAL_DEESCALATION_SLEEVE,
-    shock_sleeve: float = DEFAULT_SHOCK_SLEEVE,
-    max_sleeve: float = DEFAULT_MAX_SLEEVE,
     suppress_when_price_crisis_guard_active: bool = True,
     crisis_guard_drawdown: float = DEFAULT_PRICE_CRISIS_GUARD_DRAWDOWN,
     crisis_guard_ma_days: int = DEFAULT_PRICE_CRISIS_GUARD_MA_DAYS,
@@ -171,43 +150,40 @@ def build_taco_rebound_shadow_signal(
 
     selected_event: TradeWarEvent | None = None
     selected_event_signal_date: pd.Timestamp | None = None
-    sleeve = 0.0
     for event, event_signal_date in active_events:
-        candidate_sleeve = _event_sleeve(
-            event,
-            tariff_softening_sleeve=float(tariff_softening_sleeve),
-            geopolitical_deescalation_sleeve=float(geopolitical_deescalation_sleeve),
-            shock_sleeve=float(shock_sleeve),
-            max_sleeve=float(max_sleeve),
-        )
-        if candidate_sleeve >= sleeve:
+        if selected_event is None or _event_notice_priority(event) >= _event_notice_priority(selected_event):
             selected_event = event
             selected_event_signal_date = event_signal_date
-            sleeve = candidate_sleeve
 
-    canonical_route = ROUTE_TACO_REBOUND if sleeve > 0.0 else "no_action"
-    suggested_action = ACTION_INCREASE_REBOUND_BUDGET if sleeve > 0.0 else ACTION_NO_ACTION
-    would_trade_if_enabled = sleeve > 0.0
-    allow_hard_defense = bool(would_trade_if_enabled and _event_allows_hard_defense(selected_event))
+    rebound_context_active = bool(
+        selected_event is not None and selected_event.kind == EVENT_KIND_SOFTENING and not crisis_guard_active
+    )
+    manual_review_required = rebound_context_active
+    canonical_route = ROUTE_TACO_REBOUND if manual_review_required else "no_action"
+    suggested_action = ACTION_NOTIFY_MANUAL_REVIEW if manual_review_required else ACTION_NO_ACTION
+    would_trade_if_enabled = False
+    event_rebound_break_bear = bool(manual_review_required and _event_allows_hard_defense(selected_event))
     suppression_reason = ""
-    if active_events and sleeve <= 0.0:
+    notification_reason = "event rebound context active" if manual_review_required else ""
+    if active_events and not manual_review_required:
         suggested_action = ACTION_WATCH_ONLY
-        suppression_reason = "active event has zero configured sleeve"
-        allow_hard_defense = False
+        suppression_reason = "active event is not a softening/de-escalation rebound context"
     if crisis_guard_active:
         canonical_route = "no_action"
-        suggested_action = ACTION_BLOCKED
-        would_trade_if_enabled = False
-        sleeve = 0.0
-        allow_hard_defense = False
+        suggested_action = ACTION_WATCH_ONLY
+        manual_review_required = False
+        rebound_context_active = False
+        event_rebound_break_bear = False
         suppression_reason = "price crisis guard active"
+        notification_reason = ""
     if kill_reasons:
         canonical_route = "no_action"
-        suggested_action = ACTION_BLOCKED
-        would_trade_if_enabled = False
-        sleeve = 0.0
-        allow_hard_defense = False
+        suggested_action = ACTION_WATCH_ONLY
+        manual_review_required = False
+        rebound_context_active = False
+        event_rebound_break_bear = False
         suppression_reason = "; ".join(kill_reasons)
+        notification_reason = ""
 
     generated_at = datetime.now(timezone.utc).isoformat()
     payload = {
@@ -217,9 +193,10 @@ def build_taco_rebound_shadow_signal(
         "profile": TACO_REBOUND_PROFILE,
         "canonical_route": canonical_route,
         "suggested_action": suggested_action,
-        "sleeve_suggestion": sleeve if sleeve > 0.0 else None,
-        "allow_hard_defense": allow_hard_defense,
-        "event_rebound_break_bear": allow_hard_defense,
+        "manual_review_required": manual_review_required,
+        "notification_reason": notification_reason,
+        "rebound_context_active": rebound_context_active,
+        "event_rebound_break_bear": event_rebound_break_bear,
         "would_trade_if_enabled": would_trade_if_enabled,
         "price_stress_scan_active": scan_active,
         "price_crisis_guard_active": crisis_guard_active,
@@ -255,10 +232,12 @@ def build_taco_rebound_shadow_signal(
             "broker_order_allowed": False,
             "live_allocation_mutation_allowed": False,
             "log_namespace": TACO_REBOUND_PROFILE,
-            "notification_profile": "shadow_only",
-            "intended_strategy_role": "left_side_rebound_budget_modifier",
+            "notification_profile": "manual_review_only",
+            "intended_strategy_role": "event_rebound_notification",
             "selection_allowed": False,
-            "hard_defense_override_signal_allowed": allow_hard_defense,
+            "position_sizing_allowed": False,
+            "allocation_recommendation_allowed": False,
+            "hard_defense_override_signal_allowed": False,
         },
         "generated_at": generated_at,
     }
@@ -285,8 +264,9 @@ def write_taco_rebound_shadow_outputs(payload: Mapping[str, Any], output_dir: st
         "as_of": payload.get("as_of"),
         "canonical_route": payload.get("canonical_route"),
         "suggested_action": payload.get("suggested_action"),
-        "sleeve_suggestion": payload.get("sleeve_suggestion"),
-        "allow_hard_defense": payload.get("allow_hard_defense"),
+        "manual_review_required": payload.get("manual_review_required"),
+        "notification_reason": payload.get("notification_reason"),
+        "rebound_context_active": payload.get("rebound_context_active"),
         "event_rebound_break_bear": payload.get("event_rebound_break_bear"),
         **flatten_for_csv(payload.get("data_freshness", {})),
         **flatten_for_csv(payload.get("selected_event") or {}),
@@ -316,14 +296,6 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--benchmark-symbol", default=DEFAULT_BENCHMARK_SYMBOL)
     parser.add_argument("--attack-symbol", default=DEFAULT_ATTACK_SYMBOL)
     parser.add_argument("--active-signal-days", type=int, default=DEFAULT_ACTIVE_SIGNAL_DAYS)
-    parser.add_argument("--tariff-softening-sleeve", type=float, default=DEFAULT_TARIFF_SOFTENING_SLEEVE)
-    parser.add_argument(
-        "--geopolitical-deescalation-sleeve",
-        type=float,
-        default=DEFAULT_GEOPOLITICAL_DEESCALATION_SLEEVE,
-    )
-    parser.add_argument("--shock-sleeve", type=float, default=DEFAULT_SHOCK_SLEEVE)
-    parser.add_argument("--max-sleeve", type=float, default=DEFAULT_MAX_SLEEVE)
     parser.add_argument("--output-dir", default=DEFAULT_OUTPUT_DIR)
     return parser
 
@@ -355,10 +327,6 @@ def main(argv: Sequence[str] | None = None) -> int:
         benchmark_symbol=args.benchmark_symbol,
         attack_symbol=args.attack_symbol,
         active_signal_days=args.active_signal_days,
-        tariff_softening_sleeve=args.tariff_softening_sleeve,
-        geopolitical_deescalation_sleeve=args.geopolitical_deescalation_sleeve,
-        shock_sleeve=args.shock_sleeve,
-        max_sleeve=args.max_sleeve,
     )
     paths = write_taco_rebound_shadow_outputs(payload, args.output_dir)
     print(
@@ -370,10 +338,7 @@ def main(argv: Sequence[str] | None = None) -> int:
 
 
 __all__ = [
-    "ACTION_INCREASE_REBOUND_BUDGET",
-    "DEFAULT_GEOPOLITICAL_DEESCALATION_SLEEVE",
-    "DEFAULT_MAX_SLEEVE",
-    "DEFAULT_TARIFF_SOFTENING_SLEEVE",
+    "ACTION_NOTIFY_MANUAL_REVIEW",
     "ROUTE_TACO_REBOUND",
     "SCHEMA_VERSION",
     "TACO_REBOUND_PROFILE",

tests/test_strategy_plugin_runner.py

@@ -302,7 +302,43 @@ def test_strategy_plugin_runner_filters_by_strategy(tmp_path) -> None:
     ).exists()
 
 
-def test_strategy_plugin_runner_rejects_taco_rebound_runtime_mount_while_research_only(tmp_path) -> None:
+def test_strategy_plugin_runner_runs_taco_rebound_notification_mount_for_tqqq(tmp_path) -> None:
+    prices_path = tmp_path / "taco_prices.csv"
+    output_dir = tmp_path / STRATEGY_NAME / "plugins" / PLUGIN_TACO_REBOUND_SHADOW
+    _taco_rebound_prices().to_csv(prices_path, index=False)
+    config = {
+        "output_dir": str(tmp_path / "runner"),
+        "default_mode": "shadow",
+        "strategy_plugins": [
+            {
+                "strategy": STRATEGY_NAME,
+                "plugin": PLUGIN_TACO_REBOUND_SHADOW,
+                "enabled": True,
+                "inputs": {
+                    "prices": str(prices_path),
+                    "event_set": "geopolitical-deescalation",
+                    "as_of": "2026-04-02",
+                    "start_date": "2026-03-20",
+                },
+                "outputs": {"output_dir": str(output_dir)},
+            }
+        ],
+    }
+
+    summary = run_configured_plugins(config)
+
+    result = summary["strategy_plugins"][0]
+    assert result["strategy"] == STRATEGY_NAME
+    assert result["plugin"] == PLUGIN_TACO_REBOUND_SHADOW
+    assert result["status"] == "ok"
+    assert "route=taco_rebound action=notify_manual_review" in result["message"]
+    latest = json.loads((output_dir / "latest_signal.json").read_text(encoding="utf-8"))
+    assert latest["manual_review_required"] is True
+    assert latest["would_trade_if_enabled"] is False
+    assert "sleeve_suggestion" not in latest
+
+
+def test_strategy_plugin_runner_rejects_taco_rebound_for_non_tqqq_strategy(tmp_path) -> None:
     prices_path = tmp_path / "taco_prices.csv"
     output_dir = tmp_path / LEFT_SIDE_STRATEGY_NAME / "plugins" / PLUGIN_TACO_REBOUND_SHADOW
     _taco_rebound_prices().to_csv(prices_path, index=False)
@@ -325,13 +361,13 @@ def test_strategy_plugin_runner_rejects_taco_rebound_runtime_mount_while_researc
         ],
     }
 
-    with pytest.raises(ValueError, match="research-only"):
+    with pytest.raises(ValueError, match="strategy-limited"):
         run_configured_plugins(config)
 
     assert not (output_dir / "latest_signal.json").exists()
 
 
-def test_strategy_plugin_runner_can_skip_disabled_research_only_taco_mount(tmp_path) -> None:
+def test_strategy_plugin_runner_can_skip_disabled_taco_notification_mount(tmp_path) -> None:
     output_dir = tmp_path / LEFT_SIDE_STRATEGY_NAME / "plugins" / PLUGIN_TACO_REBOUND_SHADOW
     config = {
         "output_dir": str(tmp_path / "runner"),