feat: track QSL bundle exception metadata

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

Author: Pigbibi

README.md

@@ -35,7 +35,7 @@ This repository is the central manifest source for QSL compatibility checks.
 - `scripts/check_qsl_compat.py`: validate a repo's QSL compliance in `pyproject.toml`/`uv.lock` against central bundle.
 - `python/scripts/qslctl.py`: unified QSL version-control CLI for repo checks, workspace checks, ring reports/plans, and matrix generation.
 - `scripts/render_qsl_dependency_graph.py`: render dependency graph for review.
-- `compat/bundles/2026.07.0.toml`: first compatibility bundle (CalVer).
+- `compat/bundles/2026.07.2.toml`: current compatibility bundle baseline (CalVer).
 - `compat/repo-tiers.toml`: repo tier and upgrade ring policy notes.
 - [QSL compatibility docs](docs/qsl_compat_upgrade.md)
 

docs/qsl_compat_upgrade.md

@@ -5,7 +5,7 @@ This repository defines the QSL central compatibility manifest and its upgrade p
 ## 文件结构
 
 - `compat/bundles/*.toml`
-  - 每个 bundle 用 Calendar Version 命名（当前：`2026.07.1`）。
+  - 每个 bundle 用 Calendar Version 命名（当前：`2026.07.2`）。
   - 记录 QSL 管控的固定内部仓库提交。
 - `compat/repo-tiers.toml`
   - 记录仓库层级（`core/strategy-lib/pipeline/runtime/ops`）与升级 ring 规则。
@@ -26,8 +26,8 @@ This repository defines the QSL central compatibility manifest and its upgrade p
 
 ```toml
 [qsl]
-bundle = "2026.07.1"   # 选择要对齐的 central bundle
-compat = "2026.07.1"   # 兼容检查入口（与 bundle 相同）
+bundle = "2026.07.2"   # 选择要对齐的 central bundle
+compat = "2026.07.2"   # 兼容检查入口（与 bundle 相同）
 tier = "ops/tooling"
 upgrade_ring = "ring_e"
 allow_legacy = false     # 需要临时兼容时可先放开
@@ -48,16 +48,17 @@ python scripts/render_qsl_dependency_graph.py --repo-root . --format md
 - 阶段过渡仓可设置 `enforce_bundle = false`（建议限时）：
   - `forbidden short/invalid` 与 `bundle pin mismatch` 降级为 warning。
   - `forbidden ref 'main'` 始终为 issue，不降级。
+  - 当前 checker 已识别 `legacy_reason` 和 `live_constraint_files`；`owner` / `expires_at` / `next_action` 已进入 checker warning，用于约束过渡例外的负责人、到期日和下一步动作。
 - `--non-strict` 仅用于本地快速预览，不作为发布门禁依据。
 
 ## 当前中心兼容基线
 
-- Bundle: `2026.07.1`
-- QPK: `7032cde4547e7ec59af15df8935d142461a77051`
-- UsEquityStrategies: `9f0e5e2deca8a9c16d711eb4772f08a7901da101`
-- HkEquityStrategies: `dbbefb688cd144837aa59581b1930a14c11411ad`
-- CnEquityStrategies: `357dba7e8896a7f488a484d4a3eea33894708ab9`
-- CryptoStrategies: `64a62781f9194a23548a373c7724e132ef311f1f`
+- Bundle: `2026.07.2`
+- QPK: `37c81901160c5b31127a27dba1c63944933fb6bf`
+- UsEquityStrategies: `17ddb86c72d44b2c7b78ba7a10d8f71b21180166`
+- HkEquityStrategies: `b6a8ac2ad3c8110b5ea74fb059c8206388d63bcd`
+- CnEquityStrategies: `8dfadcf8a4dc6cc516f27a4013248474603d8ce2`
+- CryptoStrategies: `39bf4733cef922bdeacfd0adef394e7819a04908`
 - QuantStrategyPlugins: `1f3a27b8fd83d71b583f4f5160a748e95fbefaa1`
 - MarketSignalSources: `bda8ab10b80a646e4b579ef4c0d5dfe90776e908`
 

python/tests/test_qsl_compat_checker.py

@@ -35,19 +35,19 @@ def test_root_compat_bundle_and_ring_schema(self):
             compat_root = Path(workspace)
             self._write_bundle(
                 compat_root,
-                "2026.07.1",
-                {"QuantPlatformKit": "7032cde4547e7ec59af15df8935d142461a77051"},
+                "2026.07.2",
+                {"QuantPlatformKit": "37c81901160c5b31127a27dba1c63944933fb6bf"},
             )
             repo_root = self._make_repo_root(
                 qsl_toml=(
                     "tier = \"ops/tooling\"\n"
                     "ring = \"ring_e\"\n"
                     "[compat]\n"
-                    'bundle = "2026.07.1"\n'
+                    'bundle = "2026.07.2"\n'
                 ),
                 pyproject=(
                     "dependencies = [\n"
-                    '  "quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@7032cde4547e7ec59af15df8935d142461a77051"\n'
+                    '  "quant-platform-kit @ git+https://github.com/QuantStrategyLab/QuantPlatformKit.git@37c81901160c5b31127a27dba1c63944933fb6bf"\n'
                     "]\n"
                 ),
             )
@@ -57,26 +57,26 @@ def test_root_compat_bundle_and_ring_schema(self):
             self.assertTrue(ok)
             self.assertEqual(issues, [])
             self.assertEqual(warnings, [])
-            self.assertIn("bundle=2026.07.1", notes)
+            self.assertIn("bundle=2026.07.2", notes)
             self.assertIn("upgrade_ring=ring_e", notes)
 
     def test_not_enforced_bundle_reports_warning_for_short_sha_and_mismatch_but_main_stays_issue(self):
         with tempfile.TemporaryDirectory() as workspace:
             compat_root = Path(workspace)
             self._write_bundle(
                 compat_root,
-                "2026.07.1",
+                "2026.07.2",
                 {
-                    "QuantPlatformKit": "7032cde4547e7ec59af15df8935d142461a77051",
-                    "UsEquityStrategies": "9f0e5e2deca8a9c16d711eb4772f08a7901da101",
+                    "QuantPlatformKit": "37c81901160c5b31127a27dba1c63944933fb6bf",
+                    "UsEquityStrategies": "17ddb86c72d44b2c7b78ba7a10d8f71b21180166",
                 },
             )
             repo_root = self._make_repo_root(
                 qsl_toml=(
                     "tier = \"ops/tooling\"\n"
                     "ring = \"ring_e\"\n"
                     "[compat]\n"
-                    'bundle = "2026.07.1"\n'
+                    'bundle = "2026.07.2"\n'
                     "enforce_bundle = false\n"
                 ),
                 pyproject=(
@@ -94,26 +94,27 @@ def test_not_enforced_bundle_reports_warning_for_short_sha_and_mismatch_but_main
             self.assertFalse(ok)
             self.assertEqual(len(issues), 1)
             self.assertIn("forbidden ref 'main'", issues[0])
-            self.assertEqual(len(warnings), 2)
+            self.assertEqual(len(warnings), 3)
             self.assertTrue(any("forbidden short/invalid ref 'abc123'" in warning for warning in warnings))
             self.assertTrue(any("bundle pin mismatch for QuantPlatformKit" in warning for warning in warnings))
+            self.assertTrue(any("missing exception metadata" in warning for warning in warnings))
             self.assertEqual(notes[0], "qsl=" + str(repo_root / "qsl.toml"))
 
     def test_live_constraint_files_allow_full_sha_drift_from_bundle(self):
         with tempfile.TemporaryDirectory() as workspace:
             compat_root = Path(workspace)
             self._write_bundle(
                 compat_root,
-                "2026.07.1",
-                {"QuantPlatformKit": "a" * 40},
+                "2026.07.2",
+                {"QuantPlatformKit": "37c81901160c5b31127a27dba1c63944933fb6bf"},
             )
             repo_root = self._make_repo_root(
                 qsl_toml=(
                     'tier = "core"\n'
                     "ring = 0\n"
                     "allow_legacy = true\n"
                     "[compat]\n"
-                    'bundle = "2026.07.1"\n'
+                    'bundle = "2026.07.2"\n'
                     'live_constraint_files = ["constraints.txt"]\n'
                 ),
                 pyproject="",
@@ -136,16 +137,16 @@ def test_live_constraint_files_still_block_short_refs(self):
             compat_root = Path(workspace)
             self._write_bundle(
                 compat_root,
-                "2026.07.1",
-                {"QuantPlatformKit": "a" * 40},
+                "2026.07.2",
+                {"QuantPlatformKit": "37c81901160c5b31127a27dba1c63944933fb6bf"},
             )
             repo_root = self._make_repo_root(
                 qsl_toml=(
                     'tier = "core"\n'
                     "ring = 0\n"
                     "allow_legacy = true\n"
                     "[compat]\n"
-                    'bundle = "2026.07.1"\n'
+                    'bundle = "2026.07.2"\n'
                     'live_constraint_files = ["constraints.txt"]\n'
                 ),
                 pyproject="",
@@ -162,22 +163,57 @@ def test_live_constraint_files_still_block_short_refs(self):
             self.assertIn("forbidden short/invalid ref 'abc123'", issues[0])
             self.assertEqual(warnings, [])
 
+
+    def test_not_enforced_bundle_exception_metadata_notes(self):
+        with tempfile.TemporaryDirectory() as workspace:
+            compat_root = Path(workspace)
+            self._write_bundle(
+                compat_root,
+                "2026.07.2",
+                {"QuantPlatformKit": "37c81901160c5b31127a27dba1c63944933fb6bf"},
+            )
+            repo_root = self._make_repo_root(
+                qsl_toml=(
+                    'tier = "pipeline"\n'
+                    "ring = 2\n"
+                    'owner = "pipeline-team"\n'
+                    'expires_at = "2099-12-31"\n'
+                    'next_action = "remove transition pin drift"\n'
+                    "[compat]\n"
+                    'bundle = "2026.07.2"\n'
+                    "enforce_bundle = false\n"
+                ),
+                pyproject="",
+            )
+
+            ok, issues, warnings, notes = check_qsl_compat._check(repo_root=repo_root, compat_root=compat_root)
+
+            self.assertTrue(ok)
+            self.assertEqual(issues, [])
+            self.assertEqual(warnings, [])
+            self.assertIn("owner=pipeline-team", notes)
+            self.assertIn("expires_at=2099-12-31", notes)
+            self.assertIn("next_action=remove transition pin drift", notes)
+
     def test_legacy_reason_suppresses_allowed_legacy_warning(self):
         with tempfile.TemporaryDirectory() as workspace:
             compat_root = Path(workspace)
             self._write_bundle(
                 compat_root,
-                "2026.07.1",
-                {"QuantPlatformKit": "a" * 40},
+                "2026.07.2",
+                {"QuantPlatformKit": "37c81901160c5b31127a27dba1c63944933fb6bf"},
             )
             repo_root = self._make_repo_root(
                 qsl_toml=(
                     'tier = "pipeline"\n'
                     "ring = 2\n"
                     "allow_legacy = true\n"
                     'legacy_reason = "runtime deployment compatibility"\n'
+                    'owner = "runtime-team"\n'
+                    'expires_at = "2099-12-31"\n'
+                    'next_action = "replace runtime deployment requirements"\n'
                     "[compat]\n"
-                    'bundle = "2026.07.1"\n'
+                    'bundle = "2026.07.2"\n'
                     "enforce_bundle = false\n"
                 ),
                 pyproject="",

python/tests/test_qslctl.py

@@ -24,11 +24,11 @@ def test_check_all_reports_repo_issues(self) -> None:
         with tempfile.TemporaryDirectory() as workspace:
             root = Path(workspace)
             compat_root = root / "QuantRuntimeSettings"
-            self._write_bundle(compat_root, "2026.07.1", {"QuantPlatformKit": "a" * 40})
+            self._write_bundle(compat_root, "2026.07.2", {"QuantPlatformKit": "37c81901160c5b31127a27dba1c63944933fb6bf"})
             good = root / "GoodRepo"
             bad = root / "BadRepo"
-            self._write_repo(good, "2026.07.1", "a" * 40)
-            self._write_repo(bad, "2026.07.1", "b" * 40)
+            self._write_repo(good, "2026.07.2", "37c81901160c5b31127a27dba1c63944933fb6bf")
+            self._write_repo(bad, "2026.07.2", "b" * 40)
 
             with patch.object(qslctl, "_is_quant_repo", return_value=True):
                 results = qslctl.check_all(projects_root=root, compat_root=compat_root)
@@ -44,17 +44,17 @@ def test_report_groups_repositories_by_ring(self) -> None:
             compat_root = root / "QuantRuntimeSettings"
             self._write_bundle(
                 compat_root,
-                "2026.07.1",
-                {"QuantPlatformKit": "a" * 40},
+                "2026.07.2",
+                {"QuantPlatformKit": "37c81901160c5b31127a27dba1c63944933fb6bf"},
             )
             self._write_repo_tiers(compat_root)
 
             core = root / "CoreRepo"
             warning = root / "WarningRepo"
             clean = root / "CleanRepo"
-            self._write_repo(core, "2026.07.1", "b" * 40, tier="core", ring="ring_a")
-            self._write_repo(warning, "2026.07.1", "b" * 40, tier="strategy-lib", ring="ring_b", enforce_bundle=False)
-            self._write_repo(clean, "2026.07.1", "a" * 40, tier="pipeline", ring="ring_c")
+            self._write_repo(core, "2026.07.2", "b" * 40, tier="core", ring="ring_a")
+            self._write_repo(warning, "2026.07.2", "b" * 40, tier="strategy-lib", ring="ring_b", enforce_bundle=False)
+            self._write_repo(clean, "2026.07.2", "37c81901160c5b31127a27dba1c63944933fb6bf", tier="pipeline", ring="ring_c")
 
             buf = io.StringIO()
             with patch.object(qslctl, "_is_quant_repo", return_value=True), contextlib.redirect_stdout(buf):
@@ -83,14 +83,14 @@ def test_plan_orders_rings_and_actions(self) -> None:
             compat_root = root / "QuantRuntimeSettings"
             self._write_bundle(
                 compat_root,
-                "2026.07.1",
-                {"QuantPlatformKit": "a" * 40},
+                "2026.07.2",
+                {"QuantPlatformKit": "37c81901160c5b31127a27dba1c63944933fb6bf"},
             )
             self._write_repo_tiers(compat_root)
 
-            self._write_repo(root / "CoreRepo", "2026.07.1", "b" * 40, tier="core", ring="ring_a")
-            self._write_repo(root / "WarningRepo", "2026.07.1", "b" * 40, tier="strategy-lib", ring="ring_b", enforce_bundle=False)
-            self._write_repo(root / "CleanRepo", "2026.07.1", "a" * 40, tier="pipeline", ring="ring_c")
+            self._write_repo(root / "CoreRepo", "2026.07.2", "b" * 40, tier="core", ring="ring_a")
+            self._write_repo(root / "WarningRepo", "2026.07.2", "b" * 40, tier="strategy-lib", ring="ring_b", enforce_bundle=False)
+            self._write_repo(root / "CleanRepo", "2026.07.2", "37c81901160c5b31127a27dba1c63944933fb6bf", tier="pipeline", ring="ring_c")
 
             buf = io.StringIO()
             with patch.object(qslctl, "_is_quant_repo", return_value=True), contextlib.redirect_stdout(buf):

qsl.toml

@@ -1,8 +1,8 @@
 [qsl]
 # QuantRuntimeSettings 作为 QSL 中央仓库
 repo = "QuantRuntimeSettings"
-bundle = "2026.07.0"
-compat = "2026.07.0"
+bundle = "2026.07.2"
+compat = "2026.07.2"
 tier = "ops/tooling"
 upgrade_ring = "ring_e"
 allow_legacy = false

scripts/check_qsl_compat.py

@@ -7,6 +7,7 @@
 import json
 import re
 from dataclasses import dataclass
+from datetime import date
 from pathlib import Path
 from typing import Any
 
@@ -65,6 +66,13 @@ def _get_enforce_bundle(config: dict[str, Any]) -> bool:
     return bool(config.get("enforce_bundle", True))
 
 
+def _compat_value(config: dict[str, Any], name: str, default: str = "") -> str:
+    compat = config.get("compat")
+    if isinstance(compat, dict) and name in compat:
+        return str(compat.get(name, default)).strip()
+    return str(config.get(name, default)).strip()
+
+
 def _string_list(value: Any) -> list[str]:
     if not isinstance(value, list):
         return []
@@ -92,6 +100,9 @@ def _load_qsl_config(repo_root: Path) -> dict[str, str | bool | list[str]]:
     allow_legacy = bool(config.get("allow_legacy", False))
     legacy_reason = str(config.get("legacy_reason", "")).strip()
     enforce_bundle = _get_enforce_bundle(config)
+    exception_owner = _compat_value(config, "owner")
+    exception_expires_at = _compat_value(config, "expires_at")
+    exception_next_action = _compat_value(config, "next_action")
     live_constraint_files = _string_list(config.get("live_constraint_files"))
     compat = config.get("compat")
     if isinstance(compat, dict):
@@ -104,6 +115,9 @@ def _load_qsl_config(repo_root: Path) -> dict[str, str | bool | list[str]]:
         "allow_legacy": allow_legacy,
         "legacy_reason": legacy_reason,
         "enforce_bundle": enforce_bundle,
+        "owner": exception_owner,
+        "expires_at": exception_expires_at,
+        "next_action": exception_next_action,
         "live_constraint_files": sorted(set(live_constraint_files)),
         "qsl_path": qsl_path.as_posix(),
     }
@@ -184,6 +198,9 @@ def _check(repo_root: Path, compat_root: Path) -> tuple[bool, list[str], list[st
     allow_legacy = bool(qsl_cfg["allow_legacy"])
     enforce_bundle = bool(qsl_cfg["enforce_bundle"])
     legacy_reason = str(qsl_cfg["legacy_reason"])
+    exception_owner = str(qsl_cfg["owner"])
+    exception_expires_at = str(qsl_cfg["expires_at"])
+    exception_next_action = str(qsl_cfg["next_action"])
     live_constraint_files = set(qsl_cfg["live_constraint_files"]) if isinstance(qsl_cfg["live_constraint_files"], list) else set()
     qsl_path = str(qsl_cfg["qsl_path"])
 
@@ -194,9 +211,23 @@ def _check(repo_root: Path, compat_root: Path) -> tuple[bool, list[str], list[st
     notes.append(f"enforce_bundle={enforce_bundle}")
     if legacy_reason:
         notes.append("legacy_reason=" + legacy_reason)
+    if exception_owner:
+        notes.append("owner=" + exception_owner)
+    if exception_expires_at:
+        notes.append("expires_at=" + exception_expires_at)
+    if exception_next_action:
+        notes.append("next_action=" + exception_next_action)
     if live_constraint_files:
         notes.append("live_constraint_files=" + ",".join(sorted(live_constraint_files)))
 
+    if not enforce_bundle:
+        _validate_bundle_exception_metadata(
+            owner=exception_owner,
+            expires_at=exception_expires_at,
+            next_action=exception_next_action,
+            warnings=warnings,
+        )
+
     bundle_refs = _load_bundle(compat_root, bundle)
 
     if not allow_legacy:
@@ -232,6 +263,24 @@ def _check(repo_root: Path, compat_root: Path) -> tuple[bool, list[str], list[st
     return (len(issues) == 0, issues, warnings, notes)
 
 
+def _validate_bundle_exception_metadata(*, owner: str, expires_at: str, next_action: str, warnings: list[str]) -> None:
+    missing = [
+        field
+        for field, value in (("owner", owner), ("expires_at", expires_at), ("next_action", next_action))
+        if not value
+    ]
+    if missing:
+        warnings.append("enforce_bundle=false missing exception metadata: " + ", ".join(missing))
+    if expires_at:
+        try:
+            expiry = date.fromisoformat(expires_at)
+        except ValueError:
+            warnings.append("enforce_bundle=false expires_at must use YYYY-MM-DD")
+        else:
+            if expiry < date.today():
+                warnings.append(f"enforce_bundle=false exception expired on {expires_at}")
+
+
 def _validate_ref(pin: GitRef, expected_ref: str, issues: list[str], warnings: list[str], enforce_bundle: bool) -> None:
     if _is_main_ref(pin.ref):
         issues.append(f"forbidden ref 'main' in {pin.source}:{pin.line_no}: {pin.repo}")