feat(04-schema-docs): annotate ensure_* compensating migrations and update DB_SCHEMA.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.paul/phases/04-schema-docs/04-01-SUMMARY.md

@@ -0,0 +1,112 @@
+---
+phase: 04-schema-docs
+plan: 01
+subsystem: database
+tags: [migrations, schema, documentation]
+
+requires: []
+provides:
+  - Adnotowane migracje kompensujące ensure_* (5 plików SQL)
+  - Sekcja Compensating Migrations w DOCS/DB_SCHEMA.md
+  - Usunięty concern schema drift z CONCERNS.md
+affects: []
+
+tech-stack:
+  added: []
+  patterns:
+    - "Compensating migration pattern: nagłówek -- COMPENSATING MIGRATION z polami Kompensuje/Powód/Status"
+
+key-files:
+  created: []
+  modified:
+    - database/migrations/20260308_000038_ensure_order_status_mappings_table.sql
+    - database/migrations/20260308_000039_ensure_integrations_fetch_columns.sql
+    - database/migrations/20260308_000040_ensure_shoppro_orders_import_schedule.sql
+    - database/migrations/20260308_000041_ensure_shoppro_status_sync_schedule_and_direction.sql
+    - database/migrations/20260308_000042_ensure_shoppro_payment_sync_schedule_and_columns.sql
+    - DOCS/DB_SCHEMA.md
+
+key-decisions:
+  - "000042 nie ma poprzednika — prefiks ensure_ użyty defensywnie od początku"
+
+patterns-established:
+  - "Compensating migration: nagłówek SQL z Kompensuje/Powód/Status jako standard dokumentacji"
+
+duration: ~10min
+started: 2026-03-13T00:00:00Z
+completed: 2026-03-13T00:00:00Z
+---
+
+# Phase 4 Plan 01: Schema Docs Summary
+
+**5 migracji ensure_* zaadnotowanych jako compensating migrations; sekcja w DB_SCHEMA.md dodana; concern schema drift zamknięty.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~10 min |
+| Started | 2026-03-13 |
+| Completed | 2026-03-13 |
+| Tasks | 2 completed |
+| Files modified | 7 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Każda migracja ensure_* ma nagłówek SQL | Pass | Bloki `-- COMPENSATING MIGRATION` z polami Kompensuje/Powód/Status we wszystkich 5 plikach |
+| AC-2: DB_SCHEMA.md zawiera sekcję compensating migrations | Pass | Sekcja `## Compensating Migrations` z tabelą 5 wierszy dodana na początku pliku |
+| AC-3: Concern usunięty z CONCERNS.md | Pass | Sekcja `[MEDIUM] 5 "ensure_*" Migrations Indicate Schema Drift` usunięta |
+
+## Accomplishments
+
+- Zaadnotowano wszystkie 5 migracji `ensure_*` — każda ma nagłówek wyjaśniający którą oryginalną migrację kompensuje i dlaczego
+- Zidentyfikowano i udokumentowano kluczową różnicę: 000042 nie ma poprzednika (defensywny ensure_ od początku), pozostałe 4 kompensują konkretne nie-idempotentne oryginały
+- DOCS/DB_SCHEMA.md ma teraz trwałą sekcję `## Compensating Migrations` jako tabelę referencyjną
+
+## Task Commits
+
+Brak atomicznych commitów w tej sesji — zmiany do zacommitowania po UNIFY.
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `database/migrations/20260308_000038_ensure_order_status_mappings_table.sql` | Modified | Nagłówek COMPENSATING MIGRATION (kompensuje 000020) |
+| `database/migrations/20260308_000039_ensure_integrations_fetch_columns.sql` | Modified | Nagłówek COMPENSATING MIGRATION (kompensuje 000017, nie-idempotentny ALTER) |
+| `database/migrations/20260308_000040_ensure_shoppro_orders_import_schedule.sql` | Modified | Nagłówek COMPENSATING MIGRATION (kompensuje cron seed w 000018, koryguje interval) |
+| `database/migrations/20260308_000041_ensure_shoppro_status_sync_schedule_and_direction.sql` | Modified | Nagłówek COMPENSATING MIGRATION (kompensuje 000021, nie-idempotentny ALTER + interval) |
+| `database/migrations/20260308_000042_ensure_shoppro_payment_sync_schedule_and_columns.sql` | Modified | Nagłówek COMPENSATING MIGRATION (brak poprzednika — defensywny ensure_) |
+| `DOCS/DB_SCHEMA.md` | Modified | Sekcja `## Compensating Migrations` z tabelą 5 wierszy |
+| `.paul/codebase/CONCERNS.md` | Modified | Usunięty concern `[MEDIUM] 5 "ensure_*" Migrations Indicate Schema Drift` |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| 000042 zakwalifikowana jako "brak poprzednika" | Żadna wcześniejsza migracja nie definiuje payment_sync_status_codes_json ani shoppro_payment_status_sync | Dokładniejsza adnotacja niż ogólne "schema drift" |
+
+## Deviations from Plan
+
+None — plan wykonany dokładnie według specyfikacji.
+
+## Issues Encountered
+
+None.
+
+## Next Phase Readiness
+
+**Ready:**
+- Migracje compensating są w pełni udokumentowane — nowi deweloperzy rozumieją historię schematu
+- CONCERNS.md zmniejszony o jeden wpis — lista aktywna
+
+**Concerns:**
+- None
+
+**Blockers:**
+- None
+
+---
+*Phase: 04-schema-docs, Plan: 01*
+*Completed: 2026-03-13*