chore(env): standardize backend python on 3.12

Co-Authored-By: Codex <noreply@openai.com>

.ai/DECISIONS.md

@@ -13,6 +13,16 @@
 
 ---
 
+## 2026-05-07 — Standardize backend Python on 3.12
+
+**Context:** Runtime facts had drifted from docs. The backend Dockerfiles and running dev container were already on Python 3.12, GitHub CI had just been updated to 3.12, but project docs still said Python 3.11 and Gitea CI relied on the runner's ambient Python.
+
+**Decision:** Treat Python 3.12 as the backend standard. Pin local pyenv via `.python-version` to 3.12.13, matching the current `python:3.12-slim` container patch level. Add explicit Python 3.12 setup to Gitea CI and keep GitHub CI on Python 3.12.
+
+**Rejected:** Moving Docker/runtime back to Python 3.11. The application was already building and running on 3.12, so reverting the runtime would add churn without a product or dependency reason.
+
+**Consequences:** Native backend work should use `backend/venv` created from Python 3.12.13. Future docs/CI/runtime changes should preserve Python 3.12 unless a deliberate upgrade decision is recorded.
+
 ## 2026-04-30 — Add `applied_pending` non-terminal status to suggested fixes
 
 **Context:** The verifying banner forces a synchronous verdict — worked / didn't / partial — but a lot of real MSP fixes are async. Engineer ran the script but is waiting on the client to power-cycle, AD replication, an O365 license sync. With only the existing outcomes, the engineer either leaves the banner stale (eroding the verifying signal) or guesses wrong (corrupting outcome data). User flagged the gap directly. Today's `NudgeBanner` "Still checking" button just silences the nudge — it doesn't tell the system anything.

.ai/HANDOFF.md

@@ -2,7 +2,7 @@
 
 # HANDOFF.md
 
-**Last updated:** 2026-05-07 (Phase 2 code complete + four post-implementation fixes; cutover ops still pending)
+**Last updated:** 2026-05-07 (Python 3.12 standardization applied; cutover ops still pending)
 
 **Active task:** None mid-flight. Branch `feat/self-serve-signup-phase-2` (HEAD `502c0a4`) is ready to PR.
 
@@ -63,7 +63,7 @@ New env vars (Vite ARG/ENV in Dockerfile + `.env.example`): `VITE_SELF_SERVE_ENA
 
 ## Environment notes (carry-forward)
 
-- Code-server LXC: docker-only, no native python/node/npm. Use `docker exec resolutionflow_{backend,frontend} ...`.
+- Code-server LXC now standardizes on Python 3.12. `.python-version` pins 3.12.13 to match the Docker image; native backend work should use `backend/venv` built from that interpreter. `pytest --version` and `alembic --version` pass natively when `DEBUG=true SECRET_KEY=ci-test-secret-key-not-for-production` are supplied to avoid local `.env` validation failures.
 - Pytest: `docker exec resolutionflow_backend pytest tests/<file> -v --override-ini="addopts="`.
 - Vitest: `docker exec -w /app resolutionflow_frontend npm test -- <path> --run`.
 - TS build: `docker exec -w /app resolutionflow_frontend npx tsc -b`.

.ai/PROJECT_CONTEXT.md

@@ -26,7 +26,7 @@ Go-to-Market Validation (pre-PMF). Backend feature-complete (55+ endpoints, 100+
 
 ## Tech stack
 
-- **Backend:** Python 3.11 + FastAPI, SQLAlchemy 2.0 async (asyncpg), Alembic, Pydantic v2, JWT (python-jose + bcrypt, JTI refresh rotation), APScheduler (in-process with FastAPI lifespan).
+- **Backend:** Python 3.12 + FastAPI, SQLAlchemy 2.0 async (asyncpg), Alembic, Pydantic v2, JWT (python-jose + bcrypt, JTI refresh rotation), APScheduler (in-process with FastAPI lifespan).
 - **Frontend:** React 19 + Vite + TypeScript, Tailwind v4 (CSS-only config in `index.css`), Zustand (immer + zundo), React Router v7, Axios (token-refresh interceptor), Lucide.
 - **DB:** PostgreSQL 16 (RLS enabled Phase 4, pgvector).
 

.ai/SESSION_LOG.md

@@ -12,6 +12,22 @@
 
 ---
 
+## 2026-05-07 11:30 EDT — Codex — Standardize backend Python on 3.12
+
+- Standardized repo declarations around Python 3.12: added `.python-version` pinned to 3.12.13, updated stale Python 3.11 docs, and added explicit Python 3.12 setup steps to Gitea CI. GitHub CI was already updated to Python 3.12 by the user.
+- Installed pyenv Python 3.12.13 and created `backend/venv` from that interpreter. Installed `backend/requirements-dev.txt` into the venv.
+- Verified native `python --version` and venv `python --version` both report 3.12.13. Verified native `pytest 8.4.2` and `alembic 1.18.3` with explicit safe test env vars; plain pytest import still depends on local `.env` values being valid.
+- Rebuilt and restarted the dev backend container with `docker compose -f docker-compose.dev.yml build backend` and `up -d backend`; confirmed `docker exec resolutionflow_backend python --version` reports 3.12.13.
+- Files touched: `.python-version`, `.gitea/workflows/ci.yml`, `.github/workflows/ci.yml`, `README.md`, `DEV-ENV.md`, `.ai/PROJECT_CONTEXT.md`, `.ai/DECISIONS.md`, `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`.
+
+## 2026-05-07 11:14 EDT — Codex — Recheck native Python availability
+
+- Re-ran the startup ritual and checked the host Python state after the user reported fixing the missing native Python issue.
+- Verified `python` and `python3` resolve to `/config/.pyenv/shims/*` and run Python 3.12.10. `pip` and `pip3` are available as pip 25.0.1 under the same pyenv install.
+- Confirmed there is no native `python3.11`, pyenv currently lists only `3.12.10`, no repo virtualenv exists under `backend/venv`, `backend/.venv`, or root `.venv`, and `python -m pytest --version` from `backend/` fails with `No module named pytest`.
+- Conclusion: native Python is present, but it is not yet a ready backend dev/test environment for ResolutionFlow. Docker remains the reliable path for pytest/alembic until a Python 3.11 virtualenv with `backend/requirements*.txt` is installed.
+- Files touched: `.ai/HANDOFF.md`, `.ai/SESSION_LOG.md`.
+
 ## 2026-05-06 — Claude — Self-serve signup Phase 2 (frontend + cutover code) shipped on `feat/self-serve-signup-phase-2`
 
 - Executed Tasks 27–44 of `docs/superpowers/plans/2026-05-06-self-serve-signup-phase-2-frontend-cutover.md` via `superpowers:subagent-driven-development`. 18 commits on `feat/self-serve-signup-phase-2` (off `main` `f918b76`); HEAD `c75ce0c`. Each task: dispatched implementer subagent with full task text + curated context, then spec-compliance + code-quality review subagents; review issues either fixed in-flight via `git commit --amend` or noted as deferred scope.

.gitea/workflows/ci.yml

@@ -46,6 +46,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
       - name: Cache pip
         uses: actions/cache@v3
         with:
@@ -171,6 +176,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
       - name: Cache pip
         uses: actions/cache@v3
         with:

.github/workflows/ci.yml

@@ -37,10 +37,10 @@ jobs:
     steps:
       - uses: actions/checkout@v5
 
-      - name: Set up Python 3.11
+      - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
+          python-version: "3.12"
           cache: pip
           cache-dependency-path: |
             backend/requirements.txt
@@ -143,10 +143,10 @@ jobs:
     steps:
       - uses: actions/checkout@v5
 
-      - name: Set up Python 3.11
+      - name: Set up Python 3.12
         uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
+          python-version: "3.12"
           cache: pip
           cache-dependency-path: |
             backend/requirements.txt

.python-version

@@ -0,0 +1 @@
+3.12.13

DEV-ENV.md

@@ -108,7 +108,7 @@ Run these in order. Stop at the first failure and investigate.
 # Ubuntu / Debian
 sudo apt update && sudo apt install -y \
   git curl build-essential \
-  python3.11 python3.11-venv python3-pip \
+  python3.12 python3.12-venv python3-pip \
   postgresql-client   # not the server — only if running Postgres natively
 
 # Node 20 via nvm (survives container rebuilds if stored in a volume)
@@ -236,7 +236,7 @@ REPO_ROOT=/absolute/path/to/resolutionflow
 
 ```bash
 cd backend
-python3.11 -m venv venv
+python3.12 -m venv venv
 source venv/bin/activate
 pip install -r requirements.txt
 

README.md

@@ -11,7 +11,7 @@
 ## Quick Start
 
 ```bash
-# Prerequisites: Docker, Python 3.11+, Node.js 20+
+# Prerequisites: Docker, Python 3.12, Node.js 20+
 
 # Start PostgreSQL
 docker start patherly_postgres