ci: extend Python test matrix to include 3.13 and 3.14 (#349)

[cmeans-claude-dev]

Closes #349.

Summary

One-line change in .github/workflows/ci.yml:

```diff
matrix:

•      python-version: [\"3.10\", \"3.11\", \"3.12\"]
  

•      python-version: [\"3.10\", \"3.11\", \"3.12\", \"3.13\", \"3.14\"]
  

```

pyproject.toml declares requires-python = \">=3.10\" — the package metadata allows 3.13 and 3.14, but CI never exercised them. That's a source of silent breakage for any self-hoster running the package under a newer Python than we tested.

What stays unchanged

• lint / typecheck / codecov jobs still pinned to Python 3.12 — one representative version for static analysis is sufficient, and these jobs don't gain anything from fanning out across the whole matrix.
• pyproject.toml metadata — requires-python = \">=3.10\" already allowed both. No lower-bound or classifier changes.
• docker-publish.yml, docker-smoke.yml — untouched. The Dockerfile pins to python:3.12-slim; bumping that is a separate decision (see chore(deps)(deps): bump python from 3.12-slim to 3.14-slim #346 / ci: add docker build + import smoke on PRs touching Dockerfile / pyproject.toml / uv.lock #348 / the earlier thread).

Why this is additive, not redundant, with #348

This PR validates Python versions under actions/setup-python; #348 (merged as PR #350) validates the shipped Docker image. Both are needed for full CI coverage:

• The matrix catches Python-version-specific code breakage (stdlib removals, syntax/semantics changes, transitive-dep wheel availability for newer Pythons).
• The docker-smoke catches image-specific breakage (FROM python:X.Y-slim changes, pip install failures inside the slim image, entry-point registration).

Neither substitutes for the other.

Risks and unknowns

This is the "may surface hidden work" case I flagged when we ordered the P3s. Two outcomes for the new matrix entries:

• Happy path: 3.13 and 3.14 both pass. Merge and move on.
• Unhappy path: 3.13 or 3.14 fails — likely because a transitive dependency (testcontainers, psycopg, lingua-language-detector, mcp, pgvector, pydantic, etc.) doesn't ship wheels for that Python yet, or a stdlib removal breaks a dep. Each failure is a separate triage: bump a dep to a version that supports the newer Python, or exclude the entry with a note, or declare the >=3.10 floor more strictly as an upper bound in pyproject.toml.

CI on this PR is the load-bearing test. If it's green, #349 is closed. If it's red, we'll have a triage list to work through.

Scope

• .github/workflows/ci.yml — +1, -1 (matrix list)
• CHANGELOG.md — +3 (new ### Added entry under [Unreleased])

No source, no tests, no compose-file changes, no migrations.

References

• Closes #349
• Pairs with ci: add docker build + import smoke on PRs touching Dockerfile / pyproject.toml / uv.lock #348 (docker-smoke, merged via PR ci: add docker-smoke workflow — build + import smoke on Dockerfile PRs (#348) #350) — additive, both needed

QA

Prerequisites

None. Pure CI-workflow change.

Automated checks

• test (3.10/3.11/3.12) — existing entries; expected to remain green.
• test (3.13) and test (3.14) — new entries; expected to exercise the full pytest tests/ suite against these versions. If any fail, that's the actual finding this PR surfaces.
• lint, typecheck, codecov/patch — pinned to 3.12; unchanged.
• docker-smoke — not triggered (no Dockerfile / pyproject.toml / uv.lock / .dockerignore / workflow-file-matching-its-trigger change).
• CodeQL (actions) — will re-scan ci.yml; no new taint-flow sites introduced.

Manual tests

1. • YAML parse.
     ```
     python3 -c "import yaml; yaml.safe_load(open('.github/workflows/ci.yml')); print('OK')"
     ```
     Expected: OK.
2. • Matrix lists 5 entries in order.
     ```
     grep -A1 '^ matrix:' .github/workflows/ci.yml | tail -1
     ```
     Expected: python-version: [\"3.10\", \"3.11\", \"3.12\", \"3.13\", \"3.14\"].
3. • CI runs 5 test jobs on this PR. Verify in the Actions tab that test (3.10), test (3.11), test (3.12), test (3.13), test (3.14) all appear in the check list for this PR.

4. • All five test jobs pass. The actual acceptance test — if 3.13 or 3.14 fails, this PR needs follow-up work before it can merge:

     • test (3.13) fails → read the log; common culprits: testcontainers / lingua-language-detector / mcp without a 3.13 wheel
     • test (3.14) fails → same, newer target; 3.14 wheel coverage is generally thinner than 3.13

     Each failure is a separate triage decision (bump the dep, exclude the matrix entry with a note, or tighten requires-python upper bound).

5. • Lint/typecheck unchanged. lint and typecheck jobs still use python-version: \"3.12\" — they should continue to run in their existing time envelope. Verify by checking that neither job's duration in this PR's CI is materially different from the last green main CI run.
6. • No other files changed. git diff --stat origin/main shows exactly .github/workflows/ci.yml (+1, -1) and CHANGELOG.md (+3). Nothing else.

Acceptance

• ☐ All 5 test matrix entries pass — load-bearing, pending CI
• ✅ pyproject.toml requires-python = \">=3.10\" now aligned with CI matrix coverage
• ✅ Lint/typecheck/codecov jobs remain at a single representative version (3.12)
• ✅ No overlap with or replacement of ci: add docker build + import smoke on PRs touching Dockerfile / pyproject.toml / uv.lock #348's docker-smoke — complementary coverage

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans]

QA Active — reviewing the Python matrix extension (closes #349). Happy path: 3.13 and 3.14 both green on first try.

[cmeans]

QA Review — Round 1

Verdict: Ready for QA Signoff.

Clean one-line matrix extension — and the load-bearing acceptance criterion already passed on this PR's own CI: both test (3.13) and test (3.14) are SUCCESS on their first run. No hidden dep/wheel compat issues surfaced. Happy path outcome from #349.

Steps verified

Step	Result
1. YAML parse	OK ✓
2. Matrix lists 5 entries in order	python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"] ✓ (see note below — the PR body's grep command for this step has a small indent issue, so I used a corrected version)
3. CI runs 5 test jobs on this PR	✓ — test (3.10), test (3.11), test (3.12), test (3.13), test (3.14) all present in the check list
4. All five test jobs pass	✓ — all five SUCCESS
5. Lint/typecheck unchanged	✓ — lint 28s, typecheck 43s on this PR, consistent with recent main runs; both still pinned to 3.12
6. Diff stat	ci.yml (+1, -1), CHANGELOG.md (+3) — exactly as described ✓

Minor observation (non-blocking)

The PR body's step-2 grep uses ^ matrix: (8 spaces), but matrix: sits at 6-space indent in ci.yml:62 inside strategy: → matrix:. Running the command returns empty instead of the expected python-version: [...] line. Substantive property (matrix has 5 entries) is correct; only the verification regex is slightly off. Easy tidy if you want to fix it, but since the five matrix entries all actually ran and passed on this PR's CI, the substance of step 2 is demonstrated.

Other notes

• pyproject.toml declares requires-python = ">=3.10" — metadata already allowed 3.13/3.14; CI now exercises them. No pyproject.toml change needed.
• docker-smoke skipped as designed (no Dockerfile / pyproject.toml / uv.lock / .dockerignore / workflow-file-matching-its-trigger change).
• CodeQL (actions) green — no new taint-flow sites introduced.

CI rollup on 5346ccce: all matrix test jobs + lint + typecheck + CodeQL + codecov + license/cla — all SUCCESS.

Maintainer to apply QA Approved.

[cmeans]

Audit: applying Ready for QA Signoff as the final act on 5346ccce. Happy-path outcome — both test (3.13) and test (3.14) SUCCESS on first try; #349 closes cleanly with no dep/wheel triage surfaced. Non-blocking observation in the review about the step-2 grep command indent being slightly off (6 vs 8 spaces); matrix content itself is correct. All 6 steps ticked. Removing QA Active, applying Ready for QA Signoff.

[cmeans]

LGTM