fix(ci): cap test SQLAlchemy below 2.1 — pg-migrations broke on the new default driver

[dolho]

Summary

• SQLAlchemy 2.1.0 (released 2026-09-24 20:36 UTC) resolves a bare postgresql:// URL to the psycopg v3 driver instead of psycopg2.
• tests/requirements-test.txt had an uncapped sqlalchemy>=2.0.0, so CI started resolving 2.1.0. pg-migrations fails at alembic upgrade head with ModuleNotFoundError: No module named 'psycopg' (seen on feat(skills): skill sets — assign a named slice of the library as a unit (ent#530) #3005, feat(workspace): suggestions — what you can do with this agent, and what is waiting (abilityai/trinity-enterprise#465) #3000, feat(workspace): the autonomy dial — what a companion may do unprompted (ent#641) #2984; dev's last green run used 2.0.54).
• The backend image pins sqlalchemy==2.0.36 + psycopg2-binary, so production is unaffected. This caps the test env to <2.1 so it matches the image again.

Verification

sqlalchemy 2.0.54 -> make_url('postgresql://…').get_dialect().driver == 'psycopg2'
sqlalchemy 2.1.0  -> 'psycopg'

Test Plan

• pg-migrations green on this PR (it triggers on tests/requirements-test.txt)
• schema-parity green

🤖 Generated with Claude Code

[dolho]

/review Report

Branch: fix/ci-pin-sqlalchemy-2.0 → dev (merge-base cec2a64be)
Files changed: 1 (+4/−1), tests/requirements-test.txt
Scope: CLEAN. The PR sets out to cap the test env's SQLAlchemy below 2.1 so pg-migrations stops resolving the psycopg v3 driver, and that is exactly what the diff does.
Plan completion: no issue plan (CI hotfix). The PR test plan has 2 items: schema-parity is ✅ green; pg-migrations is ⚠️ not run by CI on this PR (see I1), so I verified it locally below.

Execution coverage

changed symbol	executed by	live consumer	verdict
sqlalchemy>=2.0.0,<2.1	every CI job that runs pip install -r tests/requirements-test.txt (pytest head/base, schema-parity, pg-migrations)	.github/workflows/pg-migrations.yml:74 and the pytest/schema-parity install steps	✅ executed

Fix mutation: I reproduced the pg-migrations job locally, step for step: postgres:16-alpine, the narrow VARCHAR(32) alembic_version seed, the same pip install lines, and alembic upgrade head from src/backend.

tree	resolved SQLAlchemy	alembic upgrade head	result
dev (no cap)	2.1.0	exit 1, ModuleNotFoundError: No module named 'psycopg'	🔴
PR head (capped)	2.0.54	exit 0	✅ head 0074_role_readiness_rollout_seed, version_num width 255

Critical findings

None.

Informational findings

[I1] Test gap: pg-migrations doesn't trigger on this file, so CI never proved this PR (Confidence: 9/10)
File: .github/workflows/pg-migrations.yml:18-28

  pull_request:
    paths:
      - 'src/backend/migrations/**'
      - 'src/backend/db/**'
      - 'src/backend/alembic.ini'
      - '.github/workflows/pg-migrations.yml'

• The job installs from tests/requirements-test.txt (line 74) but is not path-triggered by it. The test plan's "triggers on tests/requirements-test.txt" is therefore wrong, and the job is absent from this PR's checks.
• That same gap is how the breakage landed silently. A dependency drift only surfaces on the next PR that happens to touch migrations (feat(skills): skill sets — assign a named slice of the library as a unit (ent#530) #3005, feat(workspace): suggestions — what you can do with this agent, and what is waiting (abilityai/trinity-enterprise#465) #3000, feat(workspace): the autonomy dial — what a companion may do unprompted (ent#641) #2984), never on the change that caused it.
• Suggestion: add 'tests/requirements-test.txt' to both paths lists. That's one line each, in this PR or a follow-up. Evidence for this PR stands via the local reproduction above.

[I2] The production path still relies on SQLAlchemy's default driver for a bare postgresql:// URL (Confidence: 7/10)
File: src/backend/db/engine.py (URL taken as-is from DATABASE_URL; no drivername normalisation)

• The image is safe today: docker/backend/Dockerfile:79 pins sqlalchemy==2.0.36 and ships psycopg2-binary.
• But a future bump of that pin to 2.x ≥ 2.1 would reproduce this exact failure at production boot on every PostgreSQL install. The CI cap here would then hide the problem rather than catch it.
• Suggestion (follow-up, not this PR): name the driver explicitly. For example, normalise postgresql:// → postgresql+psycopg2:// in db/engine.py and migrations/env.py. That makes the driver a code decision instead of a library default.

Clean categories

• SQL / data safety, concurrency, auth, credentials: the diff is a single dependency constraint plus a comment. No code paths.
• Enterprise disclosure: no docs/ changes.
• Version consistency: the test env (2.0.54) and the image (2.0.36) are both 2.0.x on psycopg2. The comment's claim that the image pins 2.0.36 is accurate (docker/backend/Dockerfile:79).
• Blast radius: the other jobs that install this file (pytest head/base on SQLite) are green on this PR at 2.0.54.

Summary

• Critical: 0
• Informational: 2 (I1 is a cheap one-line fix worth folding in; I2 is a follow-up)
• Scope: clean
• Verdict: ✅ OK to merge. The fix is verified locally against the real failing job. This PR unblocks fix(git-sync): auto-sync heartbeat fetches and rebases before push; refuses on a shared source-mode branch (#3011) #3016 / fix(git-sync): the auto-sync toggle is authoritative and live (#3010) #3017 / fix(git-sync): validate push access where GitHub enforces it (#2107) #3018 and the rest of the git-sync chain.

[vybe]

merge-train: validated (lane A, one-line test-env cap; green incl. regression diff; #3020's green pg-migrations run carries this cap). Merged alone ahead of the train because every migration-bearing PR's pg-migrations/schema-parity is red on SQLAlchemy 2.1 until it lands.