Add plugin lifecycle policy registry

Co-Authored-By: Codex <noreply@openai.com>

Author: Pigbibi

README.md

@@ -33,7 +33,7 @@ python -m pytest -q
 ```
 
 ## Useful docs
-
+- [`docs/plugin_lifecycle_policy.md`](docs/plugin_lifecycle_policy.md)
 - [`docs/market-regime-control-plan.md`](docs/market-regime-control-plan.md)
 - [`docs/market-regime-control-plan.zh-CN.md`](docs/market-regime-control-plan.zh-CN.md)
 

README.zh-CN.md

@@ -17,6 +17,10 @@ QuantStrategyPlugins 是 QuantStrategyLab 的策略插件包。提供 market-reg
 - 密钥和环境专属配置不要写进共享库代码。
 - 会影响多个平台或策略包的改动，需要在文档中说明。
 
+## 延伸文档
+
+- [`docs/plugin_lifecycle_policy.zh-CN.md`](docs/plugin_lifecycle_policy.zh-CN.md)
+
 ## 仓库结构
 
 - `src/`：库代码和运行时代码。
@@ -34,6 +38,7 @@ python -m pytest -q
 
 ## 延伸文档
 
+- [`docs/plugin_lifecycle_policy.zh-CN.md`](docs/plugin_lifecycle_policy.zh-CN.md)
 - [`docs/market-regime-control-plan.md`](docs/market-regime-control-plan.md)
 - [`docs/market-regime-control-plan.zh-CN.md`](docs/market-regime-control-plan.zh-CN.md)
 

docs/market-regime-control-plan.md

@@ -5,6 +5,9 @@
 This document records the current design boundary, arbitration order, strategy
 consumption policy, and backtest evidence for `market_regime_control`.
 
+See also: [`plugin_lifecycle_policy.md`](./plugin_lifecycle_policy.md) for the
+shared plugin stage ladder and gate model.
+
 ## Goals
 
 `market_regime_control` is a unified deterministic market-regime facade. It

docs/plugin_lifecycle_policy.md

@@ -0,0 +1,72 @@
+# Plugin Lifecycle Policy
+
+[简体中文](./plugin_lifecycle_policy.zh-CN.md)
+
+This document defines the lifecycle ladder and gate model for strategy plugins.
+
+## Design Goal
+
+Plugins should be easy to observe, hard to misuse, and very hard to let affect
+capital without explicit approval.
+
+- AI may monitor and summarize plugin evidence.
+- AI must not upgrade a plugin into live authority by itself.
+- Notification delivery is not the same as position-control authority.
+- Compatibility mounts can exist for history, but they should not expand live
+permission by accident.
+
+## Recommended Plugin Stages
+
+| Stage | Meaning | Capital impact |
+| --- | --- | --- |
+| `research_only` | Research artifact, not meant for platform runtime | none |
+| `notification_only` | Can notify humans, but cannot control position | none |
+| `shadow_observer` | Can be attached to runtime metadata and audit trails | none |
+| `automation_candidate` | Has enough evidence to be considered for automation | gated |
+| `automation_approved` | Strategy-side automation is allowed when the platform gate also passes | yes |
+| `deprecated_compatibility` | Kept for replay or staged migration only | none |
+
+## Three-Gate Rule
+
+For any plugin-driven capital impact, all three gates must pass:
+
+1. **Plugin schema gate**
+   - The artifact must match a supported schema version and remain in `shadow`
+     mode for the shared contract.
+2. **Plugin evidence gate**
+   - The plugin must be marked `automation_approved` and
+     `position_control_allowed = true`.
+3. **Strategy/platform gate**
+   - The consuming strategy must explicitly opt in to the plugin and remain
+     allowed by the platform catalog.
+
+If any gate fails, the plugin should stay notification-only or compatibility-only.
+
+## Current Policy Shape
+
+- `src/quant_strategy_plugins/plugin_policies.py` is the machine-readable source
+  for lifecycle, consumption, notification-target, schema-version, and
+  deprecated-successor policy.
+- `market_regime_control` is the unified default runtime plugin.
+- `crisis_response_shadow`, `macro_risk_governor`, and `taco_rebound_shadow`
+  remain compatibility mounts or notification-only sidecars.
+- `panic_reversal_shadow` remains research-heavy and should stay notification-only
+  unless it is separately promoted.
+
+## Recommended Operating Rules
+
+- Keep `notification_allowed` broad for research visibility.
+- Keep `position_control_allowed` narrow and explicit.
+- Prefer a single shared policy registry instead of spreading allowlists across
+  runners.
+- When a strategy consumes a plugin for live capital impact, keep the platform
+  notification path separate from the strategy execution path.
+
+## Practical Interpretation
+
+- If the artifact is only for human review, use `notification_only`.
+- If the artifact is still a sidecar evidence layer, use `shadow_observer`.
+- If the plugin is being prepared for automation, keep it in
+  `automation_candidate` until the strategy gate also passes.
+- If the plugin is no longer the preferred path, mark it
+  `deprecated_compatibility` and keep it out of new runtime defaults.

docs/plugin_lifecycle_policy.zh-CN.md

@@ -0,0 +1,62 @@
+# 插件生命周期策略
+
+[English](./plugin_lifecycle_policy.md)
+
+本文定义策略插件的生命周期阶梯和门槛模型。
+
+## 设计目标
+
+插件应该容易观察、难以误用，而且在没有显式批准前非常难影响资金。
+
+- AI 可以监控和总结插件证据。
+- AI 不能单独把插件升级成 live 权限。
+- 通知投递不等于仓位控制权限。
+- 兼容挂载可以保留用于历史回放，但不能意外扩大 live 权限。
+
+## 推荐插件阶段
+
+| 阶段 | 含义 | 资金影响 |
+| --- | --- | --- |
+| `research_only` | 研究 artifact，不打算进入平台 runtime | 无 |
+| `notification_only` | 可以通知人工，但不能控制仓位 | 无 |
+| `shadow_observer` | 可以挂到 runtime metadata 和审计轨迹 | 无 |
+| `automation_candidate` | 证据足够，进入自动化候选 | 受门槛控制 |
+| `automation_approved` | 当平台门槛也通过时，策略侧可自动消费 | 有 |
+| `deprecated_compatibility` | 仅用于回放或迁移兼容 | 无 |
+
+## 三道门槛
+
+任何由插件驱动的资金影响，都必须同时通过三道门槛：
+
+1. **插件 schema 门槛**
+   - artifact 必须匹配支持的 schema version，并在共享契约中保持 `shadow` 模式。
+2. **插件证据门槛**
+   - 插件必须标记为 `automation_approved`，且 `position_control_allowed = true`。
+3. **策略 / 平台门槛**
+   - 消费策略必须显式 opt-in，并且仍然被平台 catalog 允许。
+
+任意一项失败，插件就应该停留在 notification-only 或兼容模式。
+
+## 当前策略形态
+
+- `src/quant_strategy_plugins/plugin_policies.py` 是 lifecycle、消费权限、
+  notification target、schema version 和 deprecated successor 的机器可读来源。
+- `market_regime_control` 是统一默认 runtime 插件。
+- `crisis_response_shadow`、`macro_risk_governor` 和 `taco_rebound_shadow`
+  仍然是兼容挂载或 notification-only sidecar。
+- `panic_reversal_shadow` 仍然偏研究，应继续保持 notification-only，
+  除非后续单独晋级。
+
+## 推荐运行规则
+
+- `notification_allowed` 可以保持宽松，方便研究可见。
+- `position_control_allowed` 必须保持窄而明确。
+- 尽量使用统一的 policy registry，不要把 allowlist 分散到多个 runner。
+- 当策略消费插件并产生 live 资金影响时，平台通知路径应与策略执行路径分离。
+
+## 实际解释
+
+- 只给人工复核看的 artifact，用 `notification_only`。
+- 仍然只是 sidecar 证据层的 artifact，用 `shadow_observer`。
+- 正在准备自动化的插件，用 `automation_candidate`，直到策略门槛也通过。
+- 不再是新默认路径的插件，用 `deprecated_compatibility`，并避免出现在新的 runtime 默认值里。