Merge remote-tracking branch 'origin/main' into codex-reusable-pr-review

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

Author: Pigbibi

README.md

@@ -33,6 +33,7 @@ This repository is the central manifest source for QSL compatibility checks.
 
 - `qsl.toml`: current repo QSL metadata (`tier`, `upgrade_ring`, `bundle`).
 - `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/repo-tiers.toml`: repo tier and upgrade ring policy notes.

compat/bundles/2026.07.2.toml

@@ -0,0 +1,12 @@
+name = "2026.07.2"
+description = "QSL compatibility bundle after QuantPlatformKit live-constraints and QPK_PIN refresh"
+created_at = "2026-07-05"
+
+[repos]
+QuantPlatformKit = "37c81901160c5b31127a27dba1c63944933fb6bf"
+UsEquityStrategies = "17ddb86c72d44b2c7b78ba7a10d8f71b21180166"
+HkEquityStrategies = "b6a8ac2ad3c8110b5ea74fb059c8206388d63bcd"
+CnEquityStrategies = "8dfadcf8a4dc6cc516f27a4013248474603d8ce2"
+CryptoStrategies = "39bf4733cef922bdeacfd0adef394e7819a04908"
+QuantStrategyPlugins = "1f3a27b8fd83d71b583f4f5160a748e95fbefaa1"
+MarketSignalSources = "bda8ab10b80a646e4b579ef4c0d5dfe90776e908"

docs/qsl_version_control.md

@@ -0,0 +1,37 @@
+# QSL version control plane
+
+QuantRuntimeSettings is the control plane for QuantStrategyLab internal version
+management.
+
+## Source of truth
+
+- `compat/bundles/*.toml` is the source of truth for internal repository commit pins.
+- Each consumer repository declares its bundle in `qsl.toml`.
+- Consumer files (`pyproject.toml`, `uv.lock`, `requirements.txt`, `constraints.txt`) must match the declared bundle.
+- `internal_dependency_matrix.json` is generated from local consumer dependency files; do not hand-edit it except for emergency repair.
+
+## CLI
+
+Use `qslctl` for repository and workspace checks:
+
+```bash
+python3 python/scripts/qslctl.py check --repo-root ../UsEquityStrategies
+python3 python/scripts/qslctl.py check-all --projects-root /Users/lisiyi/Projects
+python3 python/scripts/qslctl.py report --projects-root /Users/lisiyi/Projects
+python3 python/scripts/qslctl.py plan --projects-root /Users/lisiyi/Projects
+python3 python/scripts/qslctl.py generate-matrix --projects-root /Users/lisiyi/Projects --check
+python3 python/scripts/qslctl.py generate-matrix --projects-root /Users/lisiyi/Projects --sync
+```
+
+## Rollout policy
+
+1. Create or update a bundle in `compat/bundles/`.
+2. Apply that bundle by ring: core → strategy libraries → pipelines/research → runtime platforms → ops/tooling.
+3. Regenerate `internal_dependency_matrix.json` after consumer pins are updated.
+4. Keep strict checks enabled only after a ring is converged.
+
+## Workspace report / plan
+
+- `qslctl report` is read-only. It groups the current workspace by ring, status, and bundle hotspot.
+- `qslctl plan` is read-only. It renders the ring-by-ring convergence order and highlights which repos should be fixed before the next ring starts.
+- Use `report` to answer “what is broken right now?” and `plan` to answer “what should we fix first?”