deploy: backend from 8439c8b

gates-leaf-lane-c.md

@@ -8,4 +8,4 @@
   EXPECT: Lane C changes are limited to this gate file and the seven new test modules; existing unrelated dirty files are preserved.
   Evidence: status showed the seven new modules and gate file, plus pre-existing dirty `backend/main.py` and `backend/routes/at_risk_resolution.py`; neither production file nor `conftest.py` was edited in Lane C.
 
-Gate-check script evidence: `gate-check.mjs` was not present in the workspace, so the prescribed automated gate-check could not be run; pytest and the scoped status check above are recorded directly.
+Gate-check script evidence: `gate-check.mjs` exists at `.agents/skills/unlazy/scripts/gate-check.mjs`; run it as `node .agents/skills/unlazy/scripts/gate-check.mjs GATES.md` (or per-leaf `gates/` file). The pytest evidence and the scoped status check above are recorded directly.

routes/codemap.md

@@ -5,7 +5,7 @@ FastAPI route modules expose tutoring, curriculum, assessment, teacher, admin, a
 
 ## Design
 - Modules define `APIRouter` instances, Pydantic request/response models, endpoint handlers, and local request/auth validation.
-- `main.py` imports and mounts the routers; `ROLE_POLICIES` there (around line 404) controls path/role authorization.
+- `main.py` imports and mounts the routers; `ROLE_POLICIES` in `backend/main.py` (referenced by symbol, never by line number) controls path/role authorization, with `resolve_required_roles` as the single enforcement point and `backend/tests/role_policy_expectations.py` as the executable contract.
 - Handlers use domain services for reusable work, while some routes retain endpoint-specific orchestration and Firestore access.
 - Representative routers: `rag_routes`, `deepseek_rag_routes`, `practice`, `curriculum_routes`, `class_records_router`, `admin_routes`.
 

tests/README.md

@@ -1,46 +1,32 @@
-# Backend Tests Safe Runner
+# Backend Tests
 
-## Test Pollution Issue
-The test suite has pollution when run in default pytest order. Tests pass in isolation or in specific groupings.
+## Running the suite
 
-## Running Tests Safely
+The full suite runs green in default order — no ignores, subsets, or ordering workarounds needed:
 
-### Option 1: Run core API tests only (137 tests, all green)
 ```bash
 cd backend
-python -m pytest tests/test_api.py tests/test_rag_pipeline.py tests/test_quiz_battle.py tests/test_model_profiles.py -v
+python -m pytest tests/ -v --tb=short
 ```
 
-### Option 2: Run key test files in correct order
-```bash
-python -m pytest tests/ -v --ignore=tests/test_video_routes.py --ignore=tests/test_admin_model_routes.py --ignore=tests/test_hf_monitoring_routes.py
-```
+Run with `PYTHONPATH=<repo>/backend` and UTF-8 mode enabled (this is what CI does). Targeted runs:
 
-### Option 3: Individual test files (all green individually)
 ```bash
-# Each passes individually
-python -m pytest tests/test_api.py -v  # 90 passed
-python -m pytest tests/test_rag_pipeline.py -v  # 13 passed
-python -m pytest tests/test_quiz_battle.py -v  # 19 passed
-python -m pytest tests/test_model_profiles.py -v  # 15 passed
-python -m pytest tests/test_video_routes.py -v  # 11 passed
-python -m pytest tests/test_admin_model_routes.py -v  # 19 passed
-python -m pytest tests/test_hf_monitoring_routes.py -v  # 8 passed
+python -m pytest backend/tests/<module>.py -q  # from repo root
 ```
 
-## Root Cause
-- Different test files set different auth roles at module level
-- `test_api.py`: teacher role
-- `test_video_routes.py`: was student, now teacher but client still uses admin token
-- `test_admin_model_routes.py`: was admin, now teacher but test setup differs
-- `test_hf_monitoring_routes.py`: was admin, tests need admin via separate client
-
-## Fix Attempts
-1. conftest.py - doesn't work (MagicMock doesn't reset properly with @patch)
-2. Using pytest fixtures - doesn't work (@patch doesn't override MagicMock)
-3. Changing module-level auth - causes different tests to fail
-
-## Status
-- 177/180 tests pass when run in safe combinations
-- 3 tests fail only when test_video_routes runs before test_api in default order
-- Tests pass individually or in safe groupings
+Latest verified state: 579 passed, 0 failed.
+
+## Fixtures (`conftest.py`)
+
+- Firebase auth / Firebase Admin test doubles, so no production credentials are needed.
+- Isolated-auth fixture: binds student/teacher claims per test module. Always apply it to auth-sensitive modules — suite-wide auth mocks previously leaked teacher claims into student cases (wrong role = wrong status codes, not real failures).
+
+## Auth/authorization regression coverage
+
+- `test_role_policies_regression.py` — matrix over `ROLE_POLICIES`; expectations live in `role_policy_expectations.py`.
+- `test_diagnostic_iar_states.py`, `test_intervention_pipeline.py`, `test_quiz_battle_api.py`, `test_quiz_generation_regression.py`, `test_rag_regression.py`, `test_risk_wri_regression.py` — all assert 403-first rejection for unauthorized roles.
+
+## History (resolved)
+
+An older revision of this file described test pollution under default ordering (module-level auth roles, MagicMock resets). That failure mode is gone: the isolated-auth fixture plus per-module claim binding fixed it. If ordering failures ever return, check fixture isolation before reintroducing subsets or ignores.

tests/codemap.md

@@ -5,9 +5,10 @@ Python regression and contract tests for backend routes, services, RAG retrieval
 
 ## Design
 - Pytest test modules use focused test functions/classes and `unittest.mock` fixtures to isolate external boundaries.
-- `conftest.py` provides Firebase auth/Firebase Admin test doubles so tests do not require production credentials.
+- `conftest.py` provides Firebase auth/Firebase Admin test doubles so tests do not require production credentials, plus an isolated-auth fixture that binds student/teacher claims per test module (suite-wide auth mocks previously leaked teacher claims into student cases — always apply the isolated fixture to auth-sensitive modules).
 - Route tests use FastAPI `TestClient` and `main.app`; unit tests import service/RAG symbols directly.
 - Representative coverage: `test_rag_pipeline.py`, `test_160_rag_lesson_retrieval.py`, `test_video_routes.py`, `test_admin_model_routes.py`, `test_wri_service.py`, and `test_memory_health.py`.
+- Auth/authorization regression coverage: `test_role_policies_regression.py` (matrix over `ROLE_POLICIES`, expectations in `role_policy_expectations.py`), `test_diagnostic_iar_states.py`, `test_intervention_pipeline.py`, `test_quiz_battle_api.py`, `test_quiz_generation_regression.py`, `test_rag_regression.py`, `test_risk_wri_regression.py` — all assert 403-first rejection for unauthorized roles.
 
 ## Flow
 - Test setup → `conftest.py` patches Firebase boundaries → imports route/service modules or constructs `TestClient(app)`.