ci: add qsl exception lifecycle report

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

Author: Pigbibi

.github/workflows/qsl_exception_lifecycle.yml

@@ -0,0 +1,115 @@
+name: QSL Exception Lifecycle
+
+on:
+  schedule:
+    - cron: "17 3 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: qsl-exception-lifecycle
+  cancel-in-progress: false
+
+jobs:
+  report:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Prepare QuantStrategyLab workspace
+        id: workspace
+        env:
+          GH_TOKEN: ${{ secrets.RUNTIME_SETTINGS_GH_TOKEN || github.token }}
+        run: |
+          set -euo pipefail
+          workspace="${RUNNER_TEMP}/qsl-workspace"
+          rm -rf "$workspace"
+          mkdir -p "$workspace"
+          ln -s "$GITHUB_WORKSPACE" "$workspace/QuantRuntimeSettings"
+
+          python3 - <<'PY' > qsl-bundle-repos.tsv
+          import os
+          import tomllib
+          from pathlib import Path
+
+          qsl_payload = tomllib.loads(Path("qsl.toml").read_text(encoding="utf-8"))
+          qsl_config = qsl_payload.get("qsl", qsl_payload)
+          bundle = qsl_config.get("bundle") or qsl_config.get("compat")
+          if isinstance(bundle, dict):
+              bundle = bundle.get("bundle")
+          if not isinstance(bundle, str) or not bundle.strip():
+              raise SystemExit("qsl.toml missing qsl.bundle")
+          bundle = bundle.strip()
+          bundle_path = Path("compat/bundles") / f"{bundle}.toml"
+          if not bundle_path.exists():
+              raise SystemExit(f"bundle manifest not found: {bundle_path}")
+          payload = tomllib.loads(bundle_path.read_text(encoding="utf-8"))
+          repos = payload.get("repos")
+          if not isinstance(repos, dict) or not repos:
+              raise SystemExit(f"bundle manifest missing [repos]: {bundle_path}")
+          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as output:
+              output.write(f"bundle={bundle}\n")
+              output.write(f"workspace={os.environ['RUNNER_TEMP']}/qsl-workspace\n")
+          for repo, ref in sorted(repos.items()):
+              print(f"{repo}\t{ref}")
+          PY
+
+          while IFS=$'\t' read -r repo ref; do
+            [ -n "$repo" ] || continue
+            if [ -e "$workspace/$repo" ]; then
+              continue
+            fi
+            gh repo clone "QuantStrategyLab/$repo" "$workspace/$repo"
+            git -C "$workspace/$repo" checkout --detach "$ref"
+          done < qsl-bundle-repos.tsv
+
+      - name: Generate QSL compatibility report
+        id: report
+        run: |
+          set -euo pipefail
+          python3 python/scripts/qslctl.py report \
+            --projects-root "${{ steps.workspace.outputs.workspace }}" \
+            --compat-root . \
+            --json > qsl-report.json
+          python3 - <<'PY'
+          import json
+          import os
+          from pathlib import Path
+
+          report = json.loads(Path("qsl-report.json").read_text(encoding="utf-8"))
+          lines = [
+              "## QSL Exception Lifecycle Report",
+              f"- Bundle: `${os.environ['QSL_BUNDLE']}`",
+              f"- Workspace: `${os.environ['QSL_WORKSPACE']}`",
+              f"- Total repositories: `{report['total_repositories']}`",
+              f"- Strict repositories: `{report['strict_repositories']}`",
+              f"- Warning repositories: `{report['warning_repositories']}`",
+              f"- Clean repositories: `{report['clean_repositories']}`",
+              "",
+              "### Repository status",
+          ]
+          for repo in report["repositories"]:
+              status = "strict" if repo["issues"] else "warning" if repo["warnings"] else "clean"
+              lines.append(
+                  f"- `{repo['repo']}`: `{status}` "
+                  f"(issues={len(repo['issues'])}, warnings={len(repo['warnings'])})"
+              )
+              for message in repo["issues"] + repo["warnings"]:
+                  lines.append(f"  - {message}")
+          Path(os.environ["GITHUB_STEP_SUMMARY"]).write_text("\n".join(lines).strip() + "\n", encoding="utf-8")
+
+          if report["strict_repositories"] or report["warning_repositories"]:
+              raise SystemExit(1)
+          PY
+        env:
+          QSL_BUNDLE: ${{ steps.workspace.outputs.bundle }}
+          QSL_WORKSPACE: ${{ steps.workspace.outputs.workspace }}

docs/qsl_version_control.md

@@ -35,3 +35,28 @@ python3 python/scripts/qslctl.py generate-matrix --projects-root /Users/lisiyi/P
 - `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?”
+
+## QSL exception lifecycle check
+
+Use the repository workflow `.github/workflows/qsl_exception_lifecycle.yml` to run a scheduled or manual report.
+
+The workflow first reads the current bundle from `qsl.toml`, prepares a temporary workspace, links the current `QuantRuntimeSettings` checkout, clones every repo listed in that bundle manifest, checks each repo out to its pinned bundle SHA, and then runs `qslctl report` against that prepared workspace.
+
+It checks each prepared QuantStrategyLab repo for:
+
+- `enforce_bundle = false` exception metadata completeness
+  - `owner`
+  - `expires_at`
+  - `next_action`
+- expired `expires_at`
+- any strict QSL issues or warning-level QSL issues
+
+It does **not** scan the GitHub Actions checkout directory as a proxy for the full org workspace. If you need a broader multi-repo scan, prepare a local workspace or use external orchestration to clone the repositories first.
+
+Run locally with:
+
+```bash
+python3 python/scripts/qslctl.py report --projects-root /path/to/prepared-workspace --compat-root . --json
+```
+
+The workflow writes the report to the GitHub Actions step summary and fails the job when any strict or warning repository is found. Public repositories can be cloned with the default GitHub token. If a repository becomes private, configure `RUNTIME_SETTINGS_GH_TOKEN` with read access; otherwise the clone step will fail instead of silently skipping it.