From 0ddd98379756e941afa5b587d3fb2bdf437b95de Mon Sep 17 00:00:00 2001 From: curo1305 Date: Tue, 23 Jun 2026 20:35:58 +0200 Subject: [PATCH] chore(planning): update config.json and remove stale debug artifact Co-Authored-By: Claude Sonnet 4.6 --- .planning/config.json | 1 + .../debug/phase-12-cloud-schema-cold-start.md | 49 ------------------- 2 files changed, 1 insertion(+), 49 deletions(-) delete mode 100644 .planning/debug/phase-12-cloud-schema-cold-start.md diff --git a/.planning/config.json b/.planning/config.json index 4e6afeb..36d9891 100644 --- a/.planning/config.json +++ b/.planning/config.json @@ -9,6 +9,7 @@ "plan_check": true, "verifier": true, "nyquist_validation": true, + "use_worktrees": true, "auto_advance": false, "test_gate": true, "security_check": true, diff --git a/.planning/debug/phase-12-cloud-schema-cold-start.md b/.planning/debug/phase-12-cloud-schema-cold-start.md deleted file mode 100644 index 2297da5..0000000 --- a/.planning/debug/phase-12-cloud-schema-cold-start.md +++ /dev/null @@ -1,49 +0,0 @@ -# Debug: Phase 12 Cloud Schema Cold Start - -**Status:** root cause found -**Date:** 2026-06-19 -**UAT tests:** 1, 2 - -## Symptoms - -- `GET /api/cloud/connections` raises `psycopg.errors.UndefinedColumn` for `cloud_connections.display_name_override`. -- `POST /api/cloud/connections/webdav` reaches `_upsert_cloud_connection` and raises the same error, preventing Nextcloud account connection. - -## Root Cause - -The running application code and ORM are at Phase 12, but the live PostgreSQL schema remains at Alembic revision `0005`. - -Live evidence: - -```text -$ docker compose run --rm backend alembic current -0005 -``` - -Migration `backend/migrations/versions/0006_cloud_resource_foundation.py` correctly adds `cloud_connections.display_name_override` and the Phase 12 cloud metadata tables. The ORM correctly maps that column. The defect is that `docker-compose.yml` has no migration service and the backend command starts Uvicorn directly. Backend, Celery worker, and Celery beat depend on PostgreSQL health, but none depends on `alembic upgrade head` completing. Therefore `docker compose up` can run new application code against an old persistent database. - -## Why Automated Tests Missed It - -- Most backend tests build schema directly from `Base.metadata.create_all`, which validates the final ORM shape but bypasses Alembic history and deployment ordering. -- Existing Alembic tests target early migrations and do not exercise an existing PostgreSQL database upgraded from `0005` to `head`. -- Phase verification checked migration file structure and model parity, not a real cold-start Compose upgrade path. - -## Files Involved - -- `docker-compose.yml` — no one-shot migration service; backend/workers start after DB health only. -- `backend/migrations/versions/0006_cloud_resource_foundation.py` — contains the required column and tables but was not applied. -- `backend/db/models.py` — queries `display_name_override`, exposing schema drift immediately. -- `backend/tests/test_alembic.py` — lacks a 0005-to-head PostgreSQL upgrade regression. -- `.planning/phases/12-cloud-resource-foundation/12-VALIDATION.md` — cold-start test expected migration completion, but execution evidence did not actually verify Compose migration orchestration. - -## Required Fix Direction - -1. Add a one-shot Compose migration service that runs `alembic upgrade head` with `DATABASE_MIGRATE_URL` after PostgreSQL becomes healthy. -2. Make backend, Celery worker, and Celery beat wait for that migration service to complete successfully. -3. Add a PostgreSQL/Compose regression proving an existing revision `0005` advances to `0006/head` before the API starts, and assert `display_name_override`, `cloud_items`, `cloud_item_topics`, and `cloud_folder_states` exist. -4. Document the migration lifecycle and recovery command in README/RUNBOOK. -5. For the currently running environment, apply `alembic upgrade head` and restart application processes before resuming UAT. - -## Scope - -Both UAT blockers share this root cause. No evidence currently indicates a separate Nextcloud credential or WebDAV defect.