docs: publish strategy contract release line

Author: Pigbibi

README.md

@@ -27,6 +27,19 @@ It is not intended to contain:
 - Cloud Run entrypoints
 - scheduler or workflow orchestration specific to one strategy
 
+## Strategy contract boundary
+
+The current mainline split is:
+
+- platform repositories assemble `StrategyContext`
+- platform repositories load a strategy entrypoint through `load_strategy_entrypoint(...)`
+- strategy repositories return a unified `StrategyDecision`
+- platform-local decision mappers turn that decision into broker orders, notifications, and runtime state updates
+
+Strategy repositories should expose `manifest + evaluate(ctx)` and keep any migration-window runtime metadata behind `StrategyRuntimeAdapter`. Broker-specific order sequencing and UI layout should stay out of strategy outputs.
+
+Migration details and follow-up guidance live in [`docs/strategy_contract_migration.md`](./docs/strategy_contract_migration.md).
+
 ## Package layout
 
 ```text
@@ -73,7 +86,7 @@ PYTHONPATH=src python3 -m unittest discover -s tests
 `QuantPlatformKit` is a shared dependency, not a runtime service. Strategy repos should pin a fixed Git tag such as:
 
 ```text
-quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@v0.6.0
+quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@v0.7.0
 ```
 
 Cloud Run and self-hosted runner deployments should continue to deploy the strategy repositories only. See [docs/deployment_model.md](./docs/deployment_model.md) for:
@@ -108,6 +121,19 @@ Cloud Run and self-hosted runner deployments should continue to deploy the strat
 
 这个仓库是各平台仓库共享的公共依赖。
 
+### 策略契约边界
+
+当前主线边界已经固定为：
+
+- 平台仓库负责组装 `StrategyContext`
+- 平台仓库通过 `load_strategy_entrypoint(...)` 加载策略入口
+- 策略仓库只返回统一的 `StrategyDecision`
+- 平台自己的 decision mapper 再把决策映射成券商订单、通知和运行时状态更新
+
+策略仓库应该暴露 `manifest + evaluate(ctx)`；如果迁移窗口里还需要少量运行时元数据，就放在 `StrategyRuntimeAdapter` 里，不要把券商专属下单顺序或展示布局塞回策略输出。
+
+迁移说明和后续约束见 [`docs/strategy_contract_migration.md`](./docs/strategy_contract_migration.md)。
+
 ### 目录结构
 
 ```text

README.zh-CN.md

@@ -16,6 +16,19 @@
 - Cloud Run 入口
 - 某一个策略仓库自己的调度编排
 
+## 策略契约边界
+
+当前主线边界已经固定为：
+
+- 平台仓库负责组装 `StrategyContext`
+- 平台仓库通过 `load_strategy_entrypoint(...)` 加载策略入口
+- 策略仓库只返回统一的 `StrategyDecision`
+- 平台自己的 decision mapper 再把决策映射成券商订单、通知和运行时状态更新
+
+策略仓库应该暴露 `manifest + evaluate(ctx)`；如果迁移窗口里还需要少量运行时元数据，就放在 `StrategyRuntimeAdapter` 里，不要把券商专属下单顺序或展示布局塞回策略输出。
+
+迁移说明和后续约束见 [`docs/strategy_contract_migration.md`](./docs/strategy_contract_migration.md)。
+
 [English README](./README.md)
 
 ## 目录结构
@@ -63,7 +76,7 @@ PYTHONPATH=src python3 -m unittest discover -s tests
 `QuantPlatformKit` 是共享依赖，不单独部署。策略仓库应该固定依赖某个 Git tag，例如：
 
 ```text
-quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@v0.6.0
+quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@v0.7.0
 ```
 
 部署相关说明见：

docs/strategy_contract_migration.md

@@ -18,6 +18,16 @@ PR1 kept the old global compatibility helpers for one compatibility window.
 They have now been removed in the next-window cleanup batch; platforms should use
 `resolve_platform_strategy_definition(...)` and `get_enabled_profiles_for_platform(...)`.
 
+## Fixed-tag release line
+
+The current boundary-refactor release line is:
+
+- `QuantPlatformKit`: `v0.7.0`
+- `UsEquityStrategies`: `v0.7.0`
+- `CryptoStrategies`: `v0.4.0`
+
+Downstream repositories should prefer these fixed tags over long-lived commit SHA pins.
+
 ## How strategy repos should migrate next
 
 ### 1. Add manifest + evaluate entrypoint per live profile
@@ -96,6 +106,36 @@ During the compatibility window, old component loaders may stay in place behind
 - `LongBridgePlatform` / `CharlesSchwabPlatform`: remove allocation shims and hard-coded strategy asset lists.
 - `BinancePlatform`: replace `core` / `rotation` shims with a unified entrypoint and explicit artifact contract.
 
+## How to add a strategy profile
+
+1. Add a `StrategyManifest` for the live profile in the strategy repository.
+2. Expose a unified `entrypoint` or `manifest + evaluate(ctx)` pair.
+3. Keep legacy strategy functions as internal adapters only if they are still needed for rollback safety.
+4. Return only contract fields from the unified path:
+   - `positions`
+   - `budgets`
+   - `risk_flags`
+   - `diagnostics`
+5. Cover the new profile with contract and regression tests before wiring it into a platform runtime.
+
+## How to add a platform
+
+1. Resolve the canonical profile through platform policy and `load_strategy_entrypoint(...)`.
+2. Build `StrategyContext` from platform-owned market data, portfolio snapshots, runtime config, and validated artifacts.
+3. Keep broker-specific behavior in a local decision mapper:
+   - order sizing
+   - order type preference
+   - notifications
+   - runtime state updates
+4. Do not read private strategy constants or platform-only fields from strategy returns in `main.py`.
+
+## How to add an upstream artifact provider
+
+1. Fetch and validate provider payloads in the platform repository, not inside the pure strategy repo.
+2. Normalize the accepted payload into `ctx.artifacts` or a platform-owned runtime helper before calling `evaluate(ctx)`.
+3. Validate freshness, shape, version, and optional checksum at the platform boundary.
+4. Keep the strategy layer focused on decision logic over normalized inputs, not provider-specific transport details.
+
 ## PR6 cleanup status
 
 ### Mainline status by repository

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quant-platform-kit"
-version = "0.6.0"
+version = "0.7.0"
 description = "Shared broker adapters, domain models, execution ports, and notification utilities for QuantStrategyLab strategies."
 readme = "README.md"
 requires-python = ">=3.9"