---
phase: 8
slug: stack-upgrade-backend-decomposition
status: complete
nyquist_compliant: true
wave_0_complete: true
created: 2026-06-07
audited: 2026-06-12
---

# Phase 8 — Validation Strategy

> Per-phase validation contract for feedback sampling during execution.

---

## Test Infrastructure

| Property | Value |
|----------|-------|
| **Backend framework** | pytest with pytest-asyncio (asyncio_mode = auto) |
| **Backend config file** | `backend/pytest.ini` |
| **Backend quick run** | `cd backend && pytest tests/test_auth.py -x -v` |
| **Backend full suite** | `cd backend && pytest -v` |
| **Frontend framework** | Vitest 4.1.7 |
| **Frontend config** | `frontend/vitest.config.js` |
| **Frontend quick run** | `cd frontend && npm test` |
| **Estimated runtime** | ~60 seconds (backend), ~10 seconds (frontend) |

---

## Sampling Rate

- **After every task commit:** Run `cd backend && pytest -x -v` (backend changes) or `cd frontend && npm test` (frontend changes)
- **After Wave 0 (test stubs):** Confirm all new stubs are xfail — `pytest --tb=no -q`
- **After decomposition plans:** Full suite `cd backend && pytest -v` — zero failures before advancing

---

## Phase Requirements → Test Map

| Req ID | Behavior | Test Type | Automated Command | Status |
|--------|----------|-----------|-------------------|--------|
| CR-01 | `change_password` revokes other sessions, keeps current | integration | `pytest tests/test_auth.py::test_change_password_revokes_other_sessions -x` | ✅ COVERED |
| CR-02 | `enable_totp` revokes other sessions, keeps current | integration | `pytest tests/test_auth.py::test_enable_totp_revokes_other_sessions -x` | ✅ COVERED |
| CR-03 | `disable_totp` revokes other sessions, keeps current | integration | `pytest tests/test_auth.py::test_disable_totp_revokes_other_sessions -x` | ✅ COVERED |
| CODE-01 | All admin URLs still respond on same paths after split | integration | `pytest tests/test_admin_api.py -x` | ✅ COVERED |
| CODE-02 | All document URLs still respond on same paths after split | integration | `pytest tests/test_documents.py -x` | ✅ COVERED |
| CODE-03 | All auth URLs still respond on same paths after split | integration | `pytest tests/test_auth.py -x` | ✅ COVERED |
| CODE-04 | All existing consumer imports resolve; no 35+ files changed | smoke | `cd frontend && npm test` | ✅ COVERED |
| CODE-08 | No model defined twice across packages | static/grep | `grep -rn "class CloudConnectionOut" backend/` | ✅ COVERED |
| PERF-01 | npm list confirms all packages present | install verification | `cd frontend && npm list` | ✅ COVERED |

---

## Wave 0 Gaps (Resolved)

All stubs promoted to real passing tests:

- [x] `backend/tests/test_auth.py:173` — `test_change_password_revokes_other_sessions` (PASSED)
- [x] `backend/tests/test_auth.py:217` — `test_enable_totp_revokes_other_sessions` (PASSED)
- [x] `backend/tests/test_auth.py:270` — `test_disable_totp_revokes_other_sessions` (PASSED)
- [x] Frontend: `SettingsAccountTab.test.js` and `TotpEnrollment.test.js` — 136 frontend tests pass

---

## Critical Test Gates

| Gate | Command | Status |
|------|---------|--------|
| Wave 0 stubs xfail | `pytest --tb=no -q` | ✅ Complete |
| Admin split | `pytest tests/test_admin_api.py -x -v` | ✅ Passed |
| Documents split | `pytest tests/test_documents.py -x -v` | ✅ Passed |
| Auth split | `pytest tests/test_auth.py -x -v` | ✅ Passed |
| Full backend suite | `pytest -v` | ✅ 405 passed, 6 skipped, 7 xfailed |
| Frontend smoke | `npm test` | ✅ 136/136 passed |
| URL regression | `pytest tests/test_admin_api.py tests/test_documents.py tests/test_auth.py -v` | ✅ 58 passed |

---

## Security Validation

| Threat | Test | Evidence |
|--------|------|---------|
| Router prefix doubling | `pytest -v` — all existing route tests pass | URL paths unchanged |
| Admin endpoint auth leakage | `pytest tests/test_admin_api.py -k "not_admin"` | 403 on all admin routes for non-admin |
| Circular import crash | App starts cleanly: `uvicorn main:app --reload` exits 0 | No ImportError |
| CloudConnectionOut import break | `pytest tests/test_cloud.py -x` | Single definition in `backend/api/schemas.py` |

---

## Known Environment Note

`tests/test_extractor.py::test_extract_docx` fails with `ModuleNotFoundError: No module named 'docx'` in the local macOS Python 3.9 environment only. `python-docx` is in `requirements.txt` and runs correctly inside Docker. This is a pre-existing local environment gap unrelated to Phase 8.

---

## Validation Audit 2026-06-12

| Metric | Count |
|--------|-------|
| Gaps found (Wave 0) | 3 |
| Resolved | 3 |
| Escalated | 0 |
| Total requirements | 9 |
| COVERED | 9 |
| PARTIAL | 0 |
| MISSING | 0 |