---
context: phase
phase: 08-stack-upgrade-backend-decomposition
plan: 8
total_tasks: 8
status: in_progress
last_updated: 2026-06-12T08:33:19.724Z
---

# BLOCKING CONSTRAINTS — Read Before Anything Else

> These are not suggestions. Each constraint below was discovered through failure.
> Acknowledge each one explicitly before proceeding.

- [ ] CONSTRAINT: FastAPI empty-path sub-router — `@router.get("")` on a sub-router included via `include_router(sub, prefix="")` raises `FastAPIError: Prefix and path cannot be both empty` in FastAPI 0.128+. Register the list route directly on the parent router using `router.add_api_route("", handler, methods=["GET"])` instead.
- [ ] CONSTRAINT: Test monkeypatching after decomposition — Tests that patch `api.documents.X` break after decomposition because `X` moves to a sub-module. Fix: re-export `X` from `__init__.py` AND use a late import inside the handler so the call resolves through the package namespace at call time.
- [ ] CONSTRAINT: Worktree permission lockdown — Spawned agents with `isolation="worktree"` were denied write access inside their worktree paths this session. If re-spawning agents, test write access first or run inline.

**Do not proceed until all boxes are checked.**

## Critical Anti-Patterns

| Pattern | Description | Severity | Prevention Mechanism |
|---------|-------------|----------|---------------------|
| Empty-path sub-router | `@router.get("")` on a sub-router fails in FastAPI 0.128 when include prefix is also empty | blocking | Register root-path routes directly on the parent aggregator router, not on the sub-router |
| Monkeypatch target drift | Test patches `api.documents.X` but `X` moved to `api.documents.upload` after decomposition | blocking | After decomposition: re-export patched names from `__init__.py`; use late import in handler |
| Worktree write lockdown | Agents spawned with `isolation="worktree"` were denied write permission inside the worktree path | advisory | Verify write access or avoid worktrees; inline execution always has permissions |

<current_state>
Phase 8, Wave 2 complete. Plans 08-01 through 08-07 all done with SUMMARY.md files. Only plan 08-08 remains (Wave 3 — dependency upgrades). Plan 08-08 is `autonomous: false` and requires user to manually verify npm packages on npmjs.com before execution. Full backend suite: 405/406 passed (1 pre-existing python-docx env skip).
</current_state>

<completed_work>

- Plan 08-01: xfail stubs + CR contract locks ✅
- Plan 08-02: CloudConnectionOut migration + schemas.py ✅
- Plan 08-03: CR-01/02/03 session-revocation + toastStore stub ✅
- Plan 08-04: `backend/api/admin/` package (13 routes, monolith deleted) ✅
- Plan 08-05: `backend/api/documents/` package (9 routes, monolith deleted) ✅
- Plan 08-06: `backend/api/auth/` package (15 routes, CR-01/02/03 preserved, limiter re-exported) ✅
- Plan 08-07: `frontend/src/api/` decomposed — `client.js` 20 lines, 7 domain modules + `utils.js` ✅
</completed_work>

<remaining_work>

- Plan 08-08 (Wave 3): Dependency upgrades
  - Add @vueuse/core, @vueuse/integrations, sortablejs, @tailwindcss/forms, rollup-plugin-visualizer to frontend/package.json
  - Upgrade vite to ^6.4.3
  - Wire @tailwindcss/forms plugin in tailwind.config.js
  - Pin all backend/requirements.txt to exact == versions
  - Run pytest -v and npm run build to verify no regressions
  - **REQUIRES user to verify packages on npmjs.com first** (see plan frontmatter `user_setup`)
</remaining_work>

<decisions_made>

- `list_documents` registered directly on parent router in `documents/__init__.py` (not via `include_router`) — FastAPI 0.128 empty-path restriction
- `extract_and_classify` and `get_storage_backend_for_document` re-exported from `api.documents.__init__` for test monkeypatching compatibility; late import used inside handlers
- Wave 2 agents committed directly to main (permission lockdown in worktrees); recovery done inline
</decisions_made>

<blockers>

- Plan 08-08 requires user npm package verification on npmjs.com before execution (see plan frontmatter `user_setup` section)
</blockers>

## Required Reading (in order)
1. `.planning/phases/08-stack-upgrade-backend-decomposition/08-08-PLAN.md` — the only remaining plan; read the `user_setup` section carefully before executing
2. `CLAUDE.md` §"Backend: shared module map" and §"Frontend: shared module map" — non-negotiable rules

## Infrastructure State
- Docker services: not required for tests (SQLite used in tests)
- Full backend suite baseline: 405 passed, 1 skipped (python-docx not installed locally — pre-existing)
- All previous SUMMARY.md files committed

<context>
Session executed Wave 2 (plans 08-04 through 08-07) in parallel worktrees, hit permission lockdowns, recovered inline. All backend API monoliths decomposed. Frontend client.js barrel pattern in place. Wave 3 is one plan (08-08) gated on user npm supply-chain verification.
</context>

<next_action>
Start with: Ask user to verify npm packages on npmjs.com (see 08-08-PLAN.md `user_setup`), then run `/gsd:execute-phase 8` to execute plan 08-08.
</next_action>