From a6e2191ab6940ca6f44f023d18cea9207ef8dfd3 Mon Sep 17 00:00:00 2001 From: Pigbibi <20649888+Pigbibi@users.noreply.github.com> Date: Wed, 3 Jun 2026 19:27:36 +0800 Subject: [PATCH 1/2] Document crypto live pool authority --- README.md | 8 ++++---- README.zh-CN.md | 8 ++++---- docs/integration_contract.md | 7 +++++++ docs/operator_runbook.md | 6 ++++++ 4 files changed, 21 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 5dea2e2..eed11cb 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ ## What this repository is -CryptoSnapshotPipelines is the QuantStrategyLab crypto snapshot and release pipeline. It builds the crypto live pool, rankings, shadow candidate tracks, and release artifacts used by CryptoStrategies. +CryptoSnapshotPipelines is the QuantStrategyLab crypto snapshot and release pipeline. It is the authority for monthly crypto live-pool membership, ordering, rankings, shadow candidate tracks, and release artifacts used by CryptoStrategies. It is an evidence-producing repository. It does not place trades and should not be treated as an execution platform. @@ -14,7 +14,7 @@ It is an evidence-producing repository. It does not place trades and should not ### Direct runtime strategies -The trading logic lives in CryptoStrategies. This repository produces the live-pool and validation artifacts that the strategy package reads. +The trading logic lives in CryptoStrategies. This repository produces the live-pool and validation artifacts that the strategy package reads, and it owns the monthly selection and order of the published pool. ### Snapshot-backed work handled here @@ -24,11 +24,11 @@ The trading logic lives in CryptoStrategies. This repository produces the live-p ### Downstream use -CryptoStrategies and BinancePlatform should consume only release artifacts that pass the documented contract checks. +CryptoStrategies and BinancePlatform should consume only release artifacts that pass the documented contract checks. Downstream systems should preserve `live_pool.json["symbols"]` order and should not rebuild the monthly pool from local indicators. ## What the artifacts are for -Snapshot artifacts are used to make strategy decisions reproducible: ranking inputs, feature snapshots, manifests, validation summaries, and promotion evidence. They are not marketing claims. Before a downstream repository promotes a profile, review the latest artifacts across short, medium, and long windows where applicable. +Snapshot artifacts are used to make strategy decisions reproducible: ranking inputs, live-pool snapshots, manifests, validation summaries, and promotion evidence. `live_pool.json` and `artifact_manifest.json` are the stable downstream execution contract; ranking files and research outputs stay upstream evidence unless the contract explicitly promotes them. They are not marketing claims. Before a downstream repository promotes a profile, review the latest artifacts across short, medium, and long windows where applicable. ## Repository layout diff --git a/README.zh-CN.md b/README.zh-CN.md index 21ce6d6..6829b71 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -6,7 +6,7 @@ ## 这个仓库是什么 -CryptoSnapshotPipelines 是 QuantStrategyLab 的加密货币 snapshot 与发布流水线。为 CryptoStrategies 生成 live pool、ranking、shadow candidate tracks 和发布产物。 +CryptoSnapshotPipelines 是 QuantStrategyLab 的加密货币 snapshot 与发布流水线。它是月度加密 live-pool 成员、顺序、ranking、shadow candidate tracks 和发布产物的权威来源，供 CryptoStrategies 使用。 这是一个产出证据的仓库，不直接下单，也不应该被当作执行平台。 @@ -14,7 +14,7 @@ CryptoSnapshotPipelines 是 QuantStrategyLab 的加密货币 snapshot 与发布 ### 普通 runtime 策略 -交易逻辑在 CryptoStrategies。本仓库生成策略包读取的 live-pool 和验证产物。 +交易逻辑在 CryptoStrategies。本仓库生成策略包读取的 live-pool 和验证产物，并负责已发布池的月度选择和顺序。 ### 本仓库处理的 Snapshot-backed 工作 @@ -24,11 +24,11 @@ CryptoSnapshotPipelines 是 QuantStrategyLab 的加密货币 snapshot 与发布 ### 下游如何使用 -CryptoStrategies 和 BinancePlatform 应只消费通过 contract 检查的发布产物。 +CryptoStrategies 和 BinancePlatform 应只消费通过 contract 检查的发布产物。下游系统应保留 `live_pool.json["symbols"]` 的顺序，不应根据本地指标重建月度池。 ## 这些产物用来做什么 -Snapshot artifact 的作用是让策略判断可复现：包括 ranking 输入、feature snapshot、manifest、validation summary 和提升证据。它们不是宣传式收益承诺。下游仓库提升 profile 前，应在适用场景下检查最新短、中、长周期产物。 +Snapshot artifact 的作用是让策略判断可复现：包括 ranking 输入、live-pool snapshot、manifest、validation summary 和提升证据。`live_pool.json` 和 `artifact_manifest.json` 是稳定的下游执行合约；ranking 文件和研究输出默认留在上游作为证据，除非合约明确提升它们。它们不是宣传式收益承诺。下游仓库提升 profile 前，应在适用场景下检查最新短、中、长周期产物。 ## 仓库结构 diff --git a/docs/integration_contract.md b/docs/integration_contract.md index 14d993a..c62d259 100644 --- a/docs/integration_contract.md +++ b/docs/integration_contract.md @@ -17,6 +17,12 @@ The upstream project publishes a monthly `core_major` live pool and exposes it t 2. versioned and current objects in GCS 3. a lightweight Firestore summary document +## Authority Boundary + +`CryptoSnapshotPipelines` owns monthly live-pool membership, ranking, and order for `crypto_leader_rotation`. Downstream strategy and execution repositories should treat the ordered `symbols` list from `live_pool.json` or `artifact_manifest.json` as canonical. + +Downstream systems may apply runtime execution gates, sell rules, top-N selection, sizing, and degraded-source policy after artifact validation. They should not recalculate monthly membership or replace the published order from local indicators. `latest_ranking.csv` and `selection_meta` are upstream evidence and diagnostics; `live_pool.json` plus `artifact_manifest.json` are the stable execution contract. + ## Canonical Downstream Files ### `artifact_manifest.json` @@ -130,6 +136,7 @@ Stable contract fields for downstream validation: Meaning: - `pool_size` and `symbols` always describe the full official exported pool for that monthly snapshot +- `symbols` order is the official upstream monthly order and should be preserved by downstream payload normalization - downstream display panels, local ranking previews, or final execution targets are separate downstream-layer concepts Research/reporting extras are intentionally not part of the stable contract. Downstream consumers should not infer live readiness from local research CSVs or validation summaries. diff --git a/docs/operator_runbook.md b/docs/operator_runbook.md index 835ae52..5e8430a 100644 --- a/docs/operator_runbook.md +++ b/docs/operator_runbook.md @@ -40,6 +40,11 @@ The GCS prefix, Firestore document, and `source_project` value intentionally remain in the `crypto-leader-rotation` v1 artifact namespace for downstream compatibility. +This repository owns the monthly live-pool membership, ranking, and published +symbol order. Downstream runtime repositories should consume the validated +artifact contract and preserve that order when passing the pool into strategy +code. + ## Research Path Vs Production Path Production path: @@ -81,6 +86,7 @@ Operator-facing summary entrypoints: Boundary rules: - Downstream execution systems should consume the validated release artifacts, not recreate the monthly report layer. +- Downstream systems should not rerank or rebuild the monthly live pool from local runtime indicators. - Research reports and shadow-track diagnostics stay upstream and are not part of the minimum downstream execution contract. - Telegram messages from this repository are operational release notifications, not trade execution alerts. From be90fd7ca0db812b48e623353aa1775c41115e8f Mon Sep 17 00:00:00 2001 From: Pigbibi <20649888+Pigbibi@users.noreply.github.com> Date: Wed, 3 Jun 2026 19:30:03 +0800 Subject: [PATCH 2/2] Restore monthly review README defaults --- README.zh-CN.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.zh-CN.md b/README.zh-CN.md index 6829b71..60f7375 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -30,6 +30,12 @@ CryptoStrategies 和 BinancePlatform 应只消费通过 contract 检查的发布 Snapshot artifact 的作用是让策略判断可复现：包括 ranking 输入、live-pool snapshot、manifest、validation summary 和提升证据。`live_pool.json` 和 `artifact_manifest.json` 是稳定的下游执行合约；ranking 文件和研究输出默认留在上游作为证据，除非合约明确提升它们。它们不是宣传式收益承诺。下游仓库提升 profile 前，应在适用场景下检查最新短、中、长周期产物。 +## 月度 review 自动化 + +月度 publish workflow 通过 `CodexAuditBridge` 触发自动 review 和 remediation；`SELFHOSTED_CODEX_REVIEW_PROVIDER` 默认走 `auto`，优先使用 self-hosted Codex 路径，再按桥接仓库配置 fallback 到 API reviewer。`OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 等 provider secret 配置在 `CodexAuditBridge`，本仓库不直接读取这些 provider key。 + +生产发布目标如 GCP project、GCS bucket 和 Firestore document 必须从 GitHub variable 读取。本仓库不再保留 source-local `ai_review.yml`；旧的本仓库本地 API review workflow 已移除，provider 选择和 fallback 逻辑集中在 `CodexAuditBridge`。 + ## 仓库结构 - `src/`：库代码和运行时代码。