From e63522b6d9d27a42db653492cf55272bd106fdb2 Mon Sep 17 00:00:00 2001
From: Pigbibi <20649888+Pigbibi@users.noreply.github.com>
Date: Mon, 30 Mar 2026 19:19:52 +0800
Subject: [PATCH 1/4] ci: add strategy catalog workflow

---
 .github/workflows/ci.yml | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 .github/workflows/ci.yml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..b49567b
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          set -euo pipefail
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+
+      - name: Run unit tests
+        run: |
+          set -euo pipefail
+          python -m unittest discover -s tests -v

From 451d0f0e9f3ccb1d602aab87d0f0bbc3cdbc55f1 Mon Sep 17 00:00:00 2001
From: Pigbibi <20649888+Pigbibi@users.noreply.github.com>
Date: Mon, 30 Mar 2026 19:36:02 +0800
Subject: [PATCH 2/4] docs: add repository governance files

---
 .github/CODEOWNERS     |  1 +
 .github/dependabot.yml | 12 ++++++++++++
 CONTRIBUTING.md        | 24 ++++++++++++++++++++++++
 SECURITY.md            | 23 +++++++++++++++++++++++
 4 files changed, 60 insertions(+)
 create mode 100644 .github/CODEOWNERS
 create mode 100644 .github/dependabot.yml
 create mode 100644 CONTRIBUTING.md
 create mode 100644 SECURITY.md

diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
new file mode 100644
index 0000000..943acd4
--- /dev/null
+++ b/.github/CODEOWNERS
@@ -0,0 +1 @@
+* @Pigbibi
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..5860948
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,12 @@
+version: 2
+updates:
+- package-ecosystem: "pip"
+  directory: "/"
+  schedule:
+    interval: "weekly"
+  open-pull-requests-limit: 5
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+    interval: "weekly"
+  open-pull-requests-limit: 5
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..7dbeaa1
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,24 @@
+# Contributing
+
+Thanks for contributing to `CryptoStrategies`.
+
+## Ground Rules
+
+- Prefer small, low-risk pull requests.
+- Keep refactors separate from behavior changes.
+- Add or update tests when changing runtime behavior.
+- Do not use deployment or scheduled workflows as a substitute for local verification.
+
+## Branching and Pull Requests
+
+- Create a topic branch for each change.
+- Open a pull request with a short summary and a concrete test plan.
+- Wait for CI to pass before merging.
+
+## Local Verification
+
+Run the main verification command before opening a pull request:
+
+```bash
+python3 -m pip install -e . && python3 -m unittest discover -s tests -v
+```
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..46952ba
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,23 @@
+# Security Policy
+
+Thanks for helping keep `CryptoStrategies` safe.
+
+This repository is part of a shared strategy package. Please do **not** open a public issue for vulnerabilities involving credentials, broker access, cloud resources, order execution, or secret material.
+
+## Reporting a Vulnerability
+
+- Contact the maintainer directly at GitHub: `@Pigbibi`.
+- If private vulnerability reporting is enabled for this repository, prefer that channel.
+- Include the repository name, affected commit or branch, environment details, and exact reproduction steps.
+
+## Secret and Credential Exposure
+
+If you suspect tokens, passwords, API keys, service-account keys, or broker credentials were exposed:
+
+1. Rotate the exposed secrets immediately.
+2. Pause scheduled jobs or deployments if the exposure can affect automation or trading behavior.
+3. Share only the minimum evidence needed to reproduce the issue.
+
+## Scope Notes
+
+Security fixes should stay minimal and focused. Please avoid bundling unrelated refactors with a security report or patch.

From 3d4d639e2a772db0054fb2c80cb33dabfc1f8f1c Mon Sep 17 00:00:00 2001
From: Pigbibi <20649888+Pigbibi@users.noreply.github.com>
Date: Mon, 30 Mar 2026 19:40:29 +0800
Subject: [PATCH 3/4] ci: add ruff to strategy package validation

---
 .github/workflows/ci.yml | 7 ++++++-
 pyproject.toml           | 3 +++
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b49567b..ffc7a4f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -21,7 +21,12 @@ jobs:
         run: |
           set -euo pipefail
           python -m pip install --upgrade pip
-          python -m pip install -e .
+          python -m pip install -e . ruff
+
+      - name: Run Ruff
+        run: |
+          set -euo pipefail
+          ruff check .
 
       - name: Run unit tests
         run: |
diff --git a/pyproject.toml b/pyproject.toml
index 636b472..3e6712a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -17,3 +17,6 @@ package-dir = {"" = "src"}
 
 [tool.setuptools.packages.find]
 where = ["src"]
+
+[tool.ruff]
+target-version = "py311"

From 6701ecc0332423945429c35b926d53c9bb11b3d5 Mon Sep 17 00:00:00 2001
From: Pigbibi <20649888+Pigbibi@users.noreply.github.com>
Date: Mon, 30 Mar 2026 20:06:11 +0800
Subject: [PATCH 4/4] docs: restore detailed strategy descriptions

---
 README.md | 150 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 146 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index ad2decd..ec9eb44 100644
--- a/README.md
+++ b/README.md
@@ -9,12 +9,83 @@
 
 Standalone crypto strategy repository for QuantStrategyLab platforms.
 
-Current strategy implementations:
+This repository owns pure strategy logic and strategy metadata. The downstream execution repo still owns exchange access, market-data fetches, runtime state, circuit breakers, Flexible Earn handling, notifications, and order placement.
 
-- `crypto_leader_rotation`
+### Strategy index
+
+| Profile | Downstream runtime today | Core idea |
+| --- | --- | --- |
+| `crypto_leader_rotation` | `BinancePlatform` | BTC core budget plus monthly altcoin leader rotation |
 
 These strategies are consumed by platform repositories through `QuantPlatformKit` strategy contracts and component loaders.
 
+### crypto_leader_rotation
+
+**Objective**
+- Keep BTC as the core asset while giving the non-BTC sleeve to a selective trend-following rotation.
+- Avoid holding a broad alt basket all the time; only deploy into names that are strong both absolutely and versus BTC.
+
+**Repository boundary**
+- This repository owns:
+  - BTC target-ratio and base-order budgeting helpers
+  - trend-pool ranking and monthly refresh / lock logic
+  - candidate selection, inverse-vol weighting, and sell-reason rules
+- `BinancePlatform` currently owns:
+  - AHR999 and Z-Score data fetches
+  - DCA buy / trim execution
+  - exchange safety checks, balance handling, and circuit breaker behavior
+  - Flexible Earn subscribe / redeem flow and Telegram notifications
+
+**BTC core budget logic**
+- Target BTC weight grows with equity:
+  - `btc_target_ratio = 0.14 + 0.16 * ln(1 + total_equity / 10000)`
+  - capped at `65%`
+- Base daily BTC order size is:
+  - `max(15 USDT, total_equity × 0.0012)`
+- `compute_allocation_budgets(...)` splits available USDT between:
+  - the trend sleeve (`trend_usdt_pool`)
+  - the BTC accumulation sleeve (`dca_usdt_pool`)
+- This lets the downstream executor size BTC accumulation and trend allocation from one equity-aware budget framework.
+
+**Current live BTC execution rules in BinancePlatform**
+- `AHR999 < 0.45` → buy multiplier `5x`
+- `0.45 <= AHR999 < 0.8` → buy multiplier `2x`
+- `0.8 <= AHR999 < 1.2` → buy multiplier `1x`
+- `AHR999 >= 1.2` → no scheduled BTC buy
+- If `Z-Score > sell_trigger`, the runtime trims BTC.
+- Trim size is currently `10%`, `30%`, or `50%` as the overvaluation rises (`trigger`, `>4`, `>5`).
+
+**Trend-pool construction**
+- The live stack prefers an upstream published monthly pool, but this repository also contains the internal ranking logic used to rebuild or validate that pool.
+- Current live Binance defaults:
+  - pool size `5`
+  - minimum history `365` days
+  - minimum `180d` average quote volume `8,000,000`
+  - existing-pool membership bonus `0.10`
+- Ranking factors include:
+  - trend quality (`price vs SMA20 / 60 / 200`)
+  - persistence
+  - liquidity and liquidity stability
+  - relative strength vs BTC
+  - risk-adjusted momentum
+- The pool score is a weighted sum of normalized ranks, with a small bonus for names already in the previous pool.
+
+**Rotation-entry rules**
+- The BTC regime gate must be on.
+- A candidate must be above `SMA20`, `SMA60`, and `SMA200`.
+- Relative strength vs BTC must be positive.
+- Absolute momentum (`0.5×ROC20 + 0.3×ROC60 + 0.2×ROC120`) must also be positive.
+- The top `2` candidates are selected by relative score.
+- Default weighting is inverse volatility, so lower-vol winners receive slightly more capital.
+
+**Exit and defense rules**
+- A held symbol can be sold for three reasons:
+  - it rotated out of the selected top names
+  - price fell below `SMA60`
+  - price broke the ATR trailing stop: `highest_price - ATR_MULTIPLIER × ATR14`
+- The current live Binance profile uses `ATR_MULTIPLIER = 2.5`.
+- Pool membership is locked by upstream `version` / `as_of_date` state so the live pool does not churn mid-month unless a refresh is intended.
+
 ---
 
 <a id="中文"></a>
@@ -22,8 +93,79 @@ These strategies are consumed by platform repositories through `QuantPlatformKit
 
 这是 `QuantStrategyLab` 的独立加密货币策略仓。
 
-当前已收录的策略实现：
+这个仓库负责纯策略逻辑和策略元数据。下游执行仓库继续负责交易所接入、行情获取、运行时状态、熔断、Flexible Earn、通知和实际下单。
 
-- `crypto_leader_rotation`
+### 策略索引
+
+| 策略档位 | 当前下游运行仓库 | 核心思路 |
+| --- | --- | --- |
+| `crypto_leader_rotation` | `BinancePlatform` | 以 BTC 为核心仓，再叠加月度山寨币强者轮动 |
 
 这些策略通过 `QuantPlatformKit` 提供的策略契约和组件加载接口，被各个平台仓库引用。
+
+### crypto_leader_rotation
+
+**策略目标**
+- 让 BTC 继续作为核心资产，同时把非 BTC 仓位交给一套有筛选的趋势轮动。
+- 不长期被动持有一篮子山寨币，只把资金部署到绝对趋势和相对 BTC 强度都过关的标的上。
+
+**仓库边界**
+- 这个仓库负责：
+  - BTC 目标仓位和基础下单预算的计算
+  - 趋势池打分、月度刷新和锁定逻辑
+  - 候选币筛选、逆波动率权重、卖出原因判断
+- 当前 `BinancePlatform` 负责：
+  - `AHR999` 和 `Z-Score` 数据获取
+  - BTC 定投 / 分档止盈执行
+  - 交易所安全检查、余额处理和熔断
+  - Flexible Earn 申购 / 赎回，以及 Telegram 通知
+
+**BTC 核心仓预算逻辑**
+- BTC 目标权重会随总权益增长：
+  - `btc_target_ratio = 0.14 + 0.16 * ln(1 + total_equity / 10000)`
+  - 上限 `65%`
+- BTC 每日基础下单额是：
+  - `max(15 USDT, total_equity × 0.0012)`
+- `compute_allocation_budgets(...)` 会把可用 USDT 拆成：
+  - 趋势层预算 `trend_usdt_pool`
+  - BTC 累积预算 `dca_usdt_pool`
+- 这样下游执行层就能在同一个按权益变化的预算框架里，同时管理 BTC 核心仓和趋势层。
+
+**当前 Binance live 执行层里的 BTC 规则**
+- `AHR999 < 0.45` → 买入倍率 `5x`
+- `0.45 <= AHR999 < 0.8` → 买入倍率 `2x`
+- `0.8 <= AHR999 < 1.2` → 买入倍率 `1x`
+- `AHR999 >= 1.2` → 当轮不做计划内 BTC 买入
+- 当 `Z-Score > sell_trigger` 时，运行层会触发 BTC 分档止盈。
+- 当前止盈比例是 `10% / 30% / 50%` 三档，对应高估程度继续抬升（`trigger`、`>4`、`>5`）。
+
+**趋势池构建**
+- live 链路优先消费上游发布的月度池，但这个仓库也保留了内部打分逻辑，用于重建或校验该池。
+- 当前 Binance live 默认参数：
+  - 池大小 `5`
+  - 最少历史数据 `365` 天
+  - `180 日`平均成交额下限 `8,000,000`
+  - 上月已入池标的加分 `0.10`
+- 打分因子包括：
+  - 趋势质量（`price vs SMA20 / 60 / 200`）
+  - 趋势持续性
+  - 流动性和流动性稳定度
+  - 相对 BTC 强度
+  - 风险调整后动量
+- 最终分数是各个归一化 rank 的加权和，再叠加一小段旧池成员加分。
+
+**趋势层入场规则**
+- 必须先满足 BTC 闸门开启。
+- 候选币必须站上 `SMA20`、`SMA60`、`SMA200`。
+- 相对 BTC 强度必须为正。
+- 绝对动量 `0.5×ROC20 + 0.3×ROC60 + 0.2×ROC120` 也必须为正。
+- 按相对得分选出前 `2` 名。
+- 默认用逆波动率分配权重，所以波动更低的赢家会拿到略高一点的资金。
+
+**退出和防守规则**
+- 已持有的币会因为 3 类原因卖出：
+  - 已经轮出当前 Top 名单
+  - 价格跌破 `SMA60`
+  - 价格跌破 ATR 跟踪止损：`highest_price - ATR_MULTIPLIER × ATR14`
+- 当前 Binance live profile 使用 `ATR_MULTIPLIER = 2.5`。
+- 趋势池会按上游 `version / as_of_date` 做锁定，避免在月中因为偶发刷新造成 live 池频繁抖动。