kite/.planning/phases/08-stack-upgrade-backend-decomposition/.continue-here.md

context, phase, plan, total_tasks, status, last_updated

context	phase	plan	total_tasks	status	last_updated
phase	08-stack-upgrade-backend-decomposition	8	8	in_progress	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>

• Plan 08-08 requires user npm package verification on npmjs.com before execution (see plan frontmatter user_setup section)

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

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.

<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>