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/05-tech-debt-3/05-01-SUMMARY.md

@@ -0,0 +1,103 @@
+---
+phase: 05-tech-debt-3
+plan: 01
+subsystem: core
+tags: [flash, session, php, controllers, tech-debt]
+
+requires: []
+provides:
+  - OrdersController używa Flash::set()/Flash::get() zamiast bezpośrednich $_SESSION writes
+  - ShipmentController używa Flash::set()/Flash::get() zamiast bezpośrednich $_SESSION writes
+  - Ujednolicony wzorzec flash messages w całej aplikacji
+affects: []
+
+tech-stack:
+  added: []
+  patterns:
+    - "Flash messages: zawsze Flash::set('namespace.type', ...) / Flash::get('namespace.type', ''); nigdy bezpośrednio $_SESSION"
+
+key-files:
+  created: []
+  modified:
+    - src/Modules/Orders/OrdersController.php
+    - src/Modules/Shipments/ShipmentController.php
+
+key-decisions:
+  - "Klucze flash z namespace: 'order.success'/'order.error' i 'shipment.success'/'shipment.error' — spójne z konwencją dot-notation"
+
+patterns-established:
+  - "Flash messages: Flash::set('module.type', msg) przy zapisie; Flash::get('module.type', '') przy odczycie — bez unset (Flash::get() usuwa automatycznie)"
+
+duration: ~10min
+started: 2026-03-13T00:00:00Z
+completed: 2026-03-13T00:00:00Z
+---
+
+# Phase 5 Plan 01: Flash Migration Summary
+
+**Zastąpiono 10 bezpośrednich odwołań do `$_SESSION['*_flash_*']` wywołaniami `Flash::set()`/`Flash::get()` w OrdersController i ShipmentController — cała aplikacja używa teraz jednego wzorca flash messages.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~10 min |
+| Started | 2026-03-13 |
+| Completed | 2026-03-13 |
+| Tasks | 2 completed |
+| Files modified | 2 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: OrdersController używa Flash | Pass | 4 miejsca zastąpione; import Flash dodany; zero odwołań do `$_SESSION['order_flash_*']` |
+| AC-2: ShipmentController używa Flash | Pass | 6 miejsc zastąpionych; import Flash dodany; zero odwołań do `$_SESSION['shipment_flash_*']` |
+| AC-3: Brak regresji — widoki nadal otrzymują flashSuccess/flashError | Pass | Zmienne `flashSuccess`/`flashError` nadal przekazywane do template->render() bez zmian nazw |
+
+## Accomplishments
+
+- Usunięto 10 bezpośrednich `$_SESSION` writes (4 w OrdersController, 6 w ShipmentController)
+- Dodano `use App\Core\Support\Flash` do obu kontrolerów
+- Cała aplikacja używa teraz jednego mechanizmu flash — `Flash::set()`/`Flash::get()`
+- Concern `[MEDIUM] Direct $_SESSION Writes in Controllers Instead of Flash` zamknięty
+
+## Task Commits
+
+Brak atomicznych commitów — zmiany do zacommitowania po UNIFY (w commit fazy).
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `src/Modules/Orders/OrdersController.php` | Modified | Dodano `use Flash`; 4x `$_SESSION['order_flash_*']` → `Flash::set/get` |
+| `src/Modules/Shipments/ShipmentController.php` | Modified | Dodano `use Flash`; 6x `$_SESSION['shipment_flash_*']` → `Flash::set/get` |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| Klucze `order.success`/`order.error` i `shipment.success`/`shipment.error` | Spójne z dot-notation; namespace izoluje klucze między modułami | Wzorzec do stosowania przy nowych modułach |
+
+## Deviations from Plan
+
+None — plan wykonany dokładnie według specyfikacji.
+
+## Issues Encountered
+
+None.
+
+## Next Phase Readiness
+
+**Ready:**
+- Wzorzec flash messages ujednolicony — nowi deweloperzy mają jeden wzorzec do naśladowania
+
+**Concerns:**
+- None
+
+**Blockers:**
+- None
+
+---
+*Phase: 05-tech-debt-3, Plan: 01*
+*Completed: 2026-03-13*