Prepare rollback-safe legacy migration data contract (#7)

docs/LEGACY_DEPLOYMENT_MIGRATION.md

@@ -0,0 +1,40 @@
+# Gecontroleerde migratie van legacy deployments
+
+`docker-compose.migration.yml` is een optionele operatoroverride, geen wijziging
+aan de standaarddeployment. Gebruik deze alleen na de expliciete migratieprocedure
+in ProjectBrain `scripts/legacy-deployment-migration/`.
+
+De operator valideert de exacte Git-revisie en imageprovenance, stopt de oude
+container en maakt een gecontroleerde koude kopie van de volledige `local`-map.
+`MIGRATION_LOCAL_ROOT` verwijst uitsluitend naar die kopie. Media, logs en de
+PostgreSQL-data houden hun geneste mountrelatie. De originele data, image en
+container blijven bewaard voor rollback; startupmigraties mogen ze niet wijzigen.
+
+Alle migratievariabelen zijn verplicht, paden worden niet automatisch aangemaakt,
+en een attemptlabel bindt de nieuwe container aan precies één hersteltransactie.
+De operator controleert gemergde Compose-mounts, gezondheid, HTTP en de echte
+brokerreceipt voordat de configuratie definitief wordt overgezet.
+
+De override is offline getest met echte Compose-rendering en ontbrekende
+invoervariabelen. Toevoeging van dit bestand bewijst geen uitgevoerde productiemigratie.
+# Outbound worker hold
+
+Before starting a migration candidate, create `.migration-worker-hold` in its
+cloned `/app/local` directory. The supervised Celery worker and scheduler wait
+without consuming tasks until the operator removes that exact attempt-owned
+file after the deployment commit. Normal startup is unchanged when it is absent.
+Do not put the marker into the original data. This is a startup gate, not a
+control for pausing an already-running worker. Recovery before commit retains
+the hold and candidate data; recovery after commit resumes activation and must
+never revert to stale original data after outbound work has been released.
+
+The first Django middleware also returns 503 (no-store) for every ordinary
+request while held, including GET requests. Only exact GET/HEAD requests to
+`/health/ready/` and `/health/live/` pass. Marker inspection errors fail closed.
+The migration helper creates a nonce-bound marker only in the cold clone and
+removes it with directory fsync after a durable `committed` journal. Recovery
+after that boundary may resume activation but can never restore old data.
+
+`MIGRATION_NETWORK` is required and must equal the inspected existing
+`vacatureradar_default` network. The managed Compose project does not move the
+application to a newly-created network.

docs/ai/BACKLOG.yaml

@@ -2445,6 +2445,32 @@ tasks:
     note: Releasebootstrap gepind op immutable setup-uv v8.1.0-commit en uv 0.11.12 via Astral-mirror; Gitea Actions-run
       3062 publiceerde digest sha256:98f4b33d met checksum-geldige SBOM/release-evidence; Unraid gepind op volledige
       digest en live health/readiness groen.
+- id: VR-232
+  title: Houd uitgaand werk vast tijdens gecontroleerde datamigratie
+  status: ready
+  priority: P0
+  requirement_ids: [NFR-009]
+  depends_on: [VR-231]
+  summary: Door de eigenaar gevraagde migratie met rollback; Celery start pas na vrijgave van de kandidaatkopie.
+  acceptance_criteria:
+  - Een marker in de kandidaatkopie blokkeert worker en scheduler voor hun eerste externe actie.
+  - Zonder marker blijft normaal opstartgedrag ongewijzigd.
+  - Onbekende procesrollen en ongeldige markers falen gesloten.
+  - De migratie verwijdert uitsluitend haar eigen marker na geverifieerde commit.
+  - Gewone webverzoeken blijven geblokkeerd tot commit; alleen exacte GET/HEAD-healthroutes zijn beschikbaar.
+  - De migratie behoudt het bestaande Docker-netwerk via een verplichte gevalideerde variabele.
+  verification:
+  - uv run pytest tests/unit/test_migration_worker_gate.py
+  - uv run pytest tests/unit/test_migration_maintenance.py
+  - ./scripts/codex_verify.sh
+  primary_paths:
+  - scripts/migration_worker_gate.py
+  - deployment/unraid/supervisord.conf
+  - tests/unit/test_migration_worker_gate.py
+  - tests/unit/test_migration_maintenance.py
+  - apps/core/middleware.py
+  - config/settings.py
+  - docker-compose.migration.yml
 - id: VR-231
   title: Sluit de operationele 0.3.17-restpunten
   status: done

docs/ai/PROJECT_STATE.md

@@ -1,5 +1,17 @@
 # Projectstatus
 
+## Gecontroleerde migratie — 2026-09-09
+
+VR-232 voegt een startup-hold voor Celery worker/beat toe tijdens de expliciet
+goedgekeurde legacy-migratie. Alleen de kandidaatdatakopie krijgt een marker;
+uitgaand werk wordt pas na een geverifieerde deploymentcommit vrijgegeven.
+De eerste middleware blokkeert ook gewone webverzoeken tot commit; alleen exacte
+GET/HEAD-healthroutes blijven beschikbaar. De netwerkoverride behoudt het bestaande
+netwerk. Lokaal slagen 344 tests inclusief browsercontroles (84,07% coverage).
+De volledige `scripts/codex_verify.sh`-gate is groen: Ruff, Django-checks,
+migratiecontrole, tests, taakledger en repositoryvalidatie zijn geslaagd.
+Live migratie is niet uitgevoerd. Bestaande productietaken zijn niet gewijzigd.
+
 - Laatst bijgewerkt: 2026-08-12
 - Repositoryversie: 0.3.17 immutable releaseherstel
 - Uitvoeringsmodus: autonome backlog