ci: isolate live URL verification

CodeSigils · CodeSigils · commit d448bab7d3f3 · 2026-07-14T11:46:40.000+03:00
what:
- move URL reachability checks out of the four-cell validation matrix
- run them once on scheduled or manual workflows
- add a CI policy validator that preserves deterministic push and PR checks

why:
- URL checks are platform-independent and repeating them increases runner use and transient network failures
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -55,12 +55,12 @@ jobs:
       - name: Check cross-agent portability
         run: python3 .github/scripts/check-portability.py
 
+      - name: Validate CI policy
+        run: python3 scripts/validate-ci.py
+
       - name: Run skill source checks
         run: python3 scripts/validate.py
 
-      - name: Verify referenced URLs
-        run: python3 scripts/verify-urls.py
-
       - name: Test payload sync behavior
         run: python3 scripts/test-sync-payload.py
 
@@ -69,3 +69,14 @@ jobs:
 
       - name: Ruff check scripts
         run: python3 -m ruff check scripts
+
+  verify-urls:
+    name: Verify external references
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Verify referenced URLs
+        run: python3 scripts/verify-urls.py
diff --git a/README.md b/README.md
@@ -118,6 +118,7 @@ references in any shipped skill file or reference.
 
 ```bash
 python3 .github/scripts/check-portability.py
+python3 scripts/validate-ci.py
 python3 scripts/validate.py
 python3 scripts/verify-urls.py
 python3 scripts/test-sync-payload.py
@@ -144,6 +145,7 @@ python-project-workflow/
 │   ├── payload-manifest.json
 │   ├── sync-payload.sh
 │   ├── test-sync-payload.py
+│   ├── validate-ci.py
 │   ├── validate.py
 │   └── verify-urls.py
 └── skills/
diff --git a/scripts/validate-ci.py b/scripts/validate-ci.py
@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Validate CI routing contracts that keep push and PR checks deterministic."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+WORKFLOW = ROOT / ".github/workflows/ci.yml"
+
+
+def job_body(workflow: str, name: str) -> str | None:
+    match = re.search(
+        rf"(?ms)^  {re.escape(name)}:\n(?P<body>.*?)(?=^  [A-Za-z0-9_-]+:\n|\Z)",
+        workflow,
+    )
+    return match.group("body") if match else None
+
+
+def main() -> int:
+    workflow = WORKFLOW.read_text(encoding="utf-8")
+    errors: list[str] = []
+
+    validate = job_body(workflow, "validate")
+    external = job_body(workflow, "verify-urls")
+    if validate is None:
+        errors.append("ci.yml: missing validate job")
+    else:
+        if "python3 scripts/verify-urls.py" in validate:
+            errors.append(
+                "ci.yml: live URL checks must not run in the validation matrix"
+            )
+        if "python3 scripts/validate-ci.py" not in validate:
+            errors.append("ci.yml: validation matrix must run the CI policy check")
+
+    if external is None:
+        errors.append("ci.yml: missing verify-urls job")
+    else:
+        required = (
+            "if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'",
+            "runs-on: ubuntu-latest",
+            "run: python3 scripts/verify-urls.py",
+        )
+        for line in required:
+            if line not in external:
+                errors.append(f"ci.yml: verify-urls job missing {line!r}")
+        if "matrix:" in external:
+            errors.append("ci.yml: verify-urls job must not use a matrix")
+
+    if workflow.count("run: python3 scripts/verify-urls.py") != 1:
+        errors.append("ci.yml: URL verifier must appear exactly once")
+
+    if errors:
+        for error in errors:
+            print(error, file=sys.stderr)
+        return 1
+
+    print("PASS: live URL verification is isolated from push and pull-request CI")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
