From 8552479e063fba819704a13abfc90e3b27d0b5f5 Mon Sep 17 00:00:00 2001
From: Szymon Iwacz <szymon@iwacz.pl>
Date: Mon, 10 Aug 2026 11:42:36 +0200
Subject: [PATCH 1/2] =?UTF-8?q?Run=20CI=20quality=20gates=20on=20Python=20?=
 =?UTF-8?q?3.11=E2=80=933.13?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .github/workflows/validate-workflow-contracts.yml | 7 ++++++-
 CHANGELOG.md                                      | 3 ++-
 README.md                                         | 3 ++-
 docs/ai-workflow-setup.md                         | 6 +++---
 4 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/validate-workflow-contracts.yml b/.github/workflows/validate-workflow-contracts.yml
index 673dc76..4eb57b1 100644
--- a/.github/workflows/validate-workflow-contracts.yml
+++ b/.github/workflows/validate-workflow-contracts.yml
@@ -9,6 +9,11 @@ on:
 jobs:
   validate:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    name: validate (Python ${{ matrix.python-version }})
     steps:
       - name: Checkout
         uses: actions/checkout@v7
@@ -26,7 +31,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v7
         with:
-          python-version: "3.11"
+          python-version: ${{ matrix.python-version }}
 
       - name: Materialize private AI workflow
         run: ./scripts/setup-ai-workflow.sh
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 675274e..479d624 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,8 +16,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - `mypy` excludes `build/` (avoids duplicate-module errors after `python -m build`)
-- Maintainer setup notes CI Python 3.11 and that workflow validate needs
+- Maintainer setup notes that workflow validate needs
   `./scripts/setup-ai-workflow.sh` first
+- CI product quality gates run on Python 3.11, 3.12, and 3.13 (matrix)
 - CI runs `ruff format --check src tests`, `ruff check .`, and `mypy .` in
   addition to pytest (matches README / stack-profile quality gates)
 - CI / `[dev]` include `bandit` on `--check` dogfood modules (`checks.py`,
diff --git a/README.md b/README.md
index c265a65..5ff0eb9 100644
--- a/README.md
+++ b/README.md
@@ -332,7 +332,8 @@ Regex rules on **added** hunk lines. Shorthand or table form with optional
 
 ## Tests and quality
 
-Local (same gates as CI on pull requests and `main`):
+Local (same gates as CI on pull requests and `main`). CI runs that set on
+**Python 3.11, 3.12, and 3.13**:
 
 ```bash
 pytest
diff --git a/docs/ai-workflow-setup.md b/docs/ai-workflow-setup.md
index e3d62a8..3843c82 100644
--- a/docs/ai-workflow-setup.md
+++ b/docs/ai-workflow-setup.md
@@ -25,9 +25,9 @@ diffrat product files under `.ai/project/`, `.ai/docs/project-requirements.md`,
 and related paths. Tracked `.ai/ideas/` overlays product entries; template
 `implemented/` wins on rematerialize.
 
-CI runs on **Python 3.11**. Local development needs **Python ≥ 3.11** (3.12+ is
-fine). Before `./scripts/validate-ai-workflow.sh` or
-`python ci/validate-workflow-contracts.py --mode project`, run
+CI runs the product quality gates on **Python 3.11, 3.12, and 3.13**. Local
+development needs **Python ≥ 3.11**. Before `./scripts/validate-ai-workflow.sh`
+or `python ci/validate-workflow-contracts.py --mode project`, run
 `./scripts/setup-ai-workflow.sh` so materialized `.ai/` path references resolve.
 
 ## Full workflow validation (local)

From 772dc998589144d4e0dc7e2c3717327136f2dcf5 Mon Sep 17 00:00:00 2001
From: Szymon Iwacz <szymon@iwacz.pl>
Date: Mon, 10 Aug 2026 11:54:48 +0200
Subject: [PATCH 2/2] Add validate aggregator for branch protection

---
 .github/workflows/validate-workflow-contracts.yml | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/validate-workflow-contracts.yml b/.github/workflows/validate-workflow-contracts.yml
index 4eb57b1..f92703a 100644
--- a/.github/workflows/validate-workflow-contracts.yml
+++ b/.github/workflows/validate-workflow-contracts.yml
@@ -7,7 +7,7 @@ on:
       - main
 
 jobs:
-  validate:
+  test:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -60,3 +60,13 @@ jobs:
 
       - name: Pytest
         run: pytest tests/ -q
+
+  # Branch protection requires a check named exactly "validate". Matrix jobs
+  # report as "validate (Python X.Y)", so this aggregator satisfies the gate.
+  validate:
+    needs: test
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require matrix success
+        run: test "${{ needs.test.result }}" = "success"