ci: introduce tiered SDK workflow gates

.github/workflows/publish.yml

@@ -5,15 +5,46 @@ on:
     tags:
       - "v*"
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
 jobs:
+  compatibility:
+    name: compatibility (${{ matrix.os }}, ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: python -m pip install -e ".[test]"
+
+      - name: Run tests
+        run: python -m pytest -v
+
   publish:
+    needs: compatibility
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
         with:
           python-version: "3.12"
 

.github/workflows/tests.yml

@@ -4,14 +4,40 @@ on:
   workflow_dispatch:
   push:
     branches: [main, "codex/**"]
+    tags: ["v*"]
   pull_request:
     branches: [main]
 
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
-  test:
+  fast:
+    name: fast tests (ubuntu-latest, 3.12)
+    if: github.event_name == 'push' && !startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: python -m pip install -e ".[test]"
+
+      - name: Run tests
+        run: python -m pytest -v
+
+  compatibility:
+    name: compatibility (${{ matrix.os }}, ${{ matrix.python-version }})
+    if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/v')
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -20,10 +46,10 @@ jobs:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4.3.1
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
         with:
           python-version: ${{ matrix.python-version }}
 

AGENTS.md

@@ -30,6 +30,16 @@ python tests/test_live_e2e.py
 AVP_URL=http://localhost:8000 pytest tests/ -v
 ```
 
+## CI policy
+
+Follow [`docs/CI_POLICY.md`](docs/CI_POLICY.md).
+
+- Run relevant local tests before pushing code changes.
+- The push fast gate is not release verification.
+- The full OS/Python compatibility gate must pass before release tags or PyPI publication.
+- Do not use `[skip ci]` for code, packaging, security, or behavior changes.
+- When reporting done, state the local commands and CI gates that actually ran.
+
 ## Code style
 
 - Python 3.10+

CLAUDE.md

@@ -0,0 +1,14 @@
+# CLAUDE.md
+
+## Project Instructions
+
+Follow [`AGENTS.md`](AGENTS.md) for repository-specific project notes and security discipline.
+
+## CI Policy
+
+Follow [`docs/CI_POLICY.md`](docs/CI_POLICY.md).
+
+- Run relevant local tests before pushing code changes.
+- Do not treat the fast push gate as release verification.
+- Do not use `[skip ci]` for code, packaging, security, or behavior changes.
+- Before reporting done, state which local commands and CI gates actually ran.

docs/CI_POLICY.md

@@ -0,0 +1,17 @@
+# CI Policy
+
+This repository uses tiered CI so day-to-day agent work stays fast while release quality remains unchanged.
+
+## Gates
+
+- Fast gate: runs on normal branch pushes. It uses Ubuntu and the primary Python version, and must run the full regular pytest suite.
+- Compatibility gate: runs on pull requests to `main`, manual dispatch, and release tags. It uses the full supported OS/Python matrix.
+- Publish gate: package publication is allowed only after the compatibility gate has passed for the release candidate or tag.
+
+## Agent Rules
+
+- Run the relevant local tests before pushing code changes.
+- Do not treat the fast gate as release verification.
+- Do not use `[skip ci]` for code, packaging, security, or behavior changes.
+- Before reporting a change as done, state which local commands and which CI gates actually ran.
+- Before tagging or publishing a release, verify that the compatibility gate passed.