fix: keep dependency drift reports hermetic

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

Author: Pigbibi

.github/workflows/validate.yml

@@ -55,7 +55,23 @@ jobs:
           GH_TOKEN: ${{ github.token }}
         run: bash python/shell/checkout_internal_dependency_consumers.sh --output-root ..
       - name: Report internal dependency matrix
-        run: python3 python/scripts/check_internal_dependency_matrix.py --projects-root .. --json --strict --require-consumer-files
+        run: python3 python/scripts/check_internal_dependency_matrix.py --projects-root .. --json --require-consumer-files
+      - name: Enforce internal dependency matrix when its ledger changes
+        run: |
+          set -euo pipefail
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            comparison_range="origin/${{ github.base_ref }}...HEAD"
+          elif git rev-parse --verify HEAD^ >/dev/null 2>&1; then
+            comparison_range="HEAD^...HEAD"
+          else
+            echo "No parent commit is available; reporting dependency drift without a strict ledger gate."
+            exit 0
+          fi
+          if git diff --quiet "$comparison_range" -- internal_dependency_matrix.json; then
+            echo "Internal dependency ledger did not change; retaining the report without making this unrelated PR non-hermetic."
+            exit 0
+          fi
+          python3 python/scripts/check_internal_dependency_matrix.py --projects-root .. --json --strict --require-consumer-files
 
   js:
     runs-on: ubuntu-latest

docs/internal_dependency_pin_policy.md

@@ -7,7 +7,10 @@ QuantStrategyLab shares Python packages across platforms, strategies, and pipeli
 ## Source of truth
 
 - **Tracked pins** live in [`internal_dependency_matrix.json`](../internal_dependency_matrix.json).
-- **Validation** runs in QuantRuntimeSettings CI via:
+- **Validation** runs in QuantRuntimeSettings CI: every PR publishes a drift report, while
+  strict enforcement blocks only changes to `internal_dependency_matrix.json`. This prevents
+  an unrelated console or documentation PR from failing non-hermetically merely because a
+  separately checked-out consumer advanced; a ledger change must still match every consumer.
 
 ```bash
 python3 scripts/check_internal_dependency_matrix.py --projects-root .. --strict

docs/internal_dependency_pin_policy.zh-CN.md

@@ -7,7 +7,10 @@ QuantStrategyLab 通过 git URL pin 在平台、策略与 pipeline 之间共享
 ## 权威来源
 
 - **已追踪的 pin** 记录在 [`internal_dependency_matrix.json`](../internal_dependency_matrix.json)。
-- **校验** 在 QuantRuntimeSettings CI 中执行：
+- **校验** 在 QuantRuntimeSettings CI 中执行：每个 PR 都生成漂移报告；只有修改
+  `internal_dependency_matrix.json` 的变更才会以严格模式阻塞合并。这样一个无关的
+  控制台或文档 PR 不会因为 checkout 时其他仓库恰好前进而变成不可复现的失败；台账
+  本身仍必须在提交时与所有 consumer 一致。
 
 ```bash
 python3 scripts/check_internal_dependency_matrix.py --projects-root .. --strict