From f1442e89d84070aa6ead50cfaa8143878403e798 Mon Sep 17 00:00:00 2001
From: Rijad Zuzo <rijad.zuzo@matriq.ch>
Date: Sun, 15 Feb 2026 20:13:49 +0100
Subject: [PATCH] Add Flutter CI workflow and sync hardening docs

---
 .github/workflows/flutter_ci.yml | 30 +++++++++++++++++++++
 docs/SETUP.md                    | 19 ++++++++++++++
 docs/progress.md                 | 45 ++++++++++++++++++++++++++++++++
 3 files changed, 94 insertions(+)
 create mode 100644 .github/workflows/flutter_ci.yml

diff --git a/.github/workflows/flutter_ci.yml b/.github/workflows/flutter_ci.yml
new file mode 100644
index 0000000..2ac0e2d
--- /dev/null
+++ b/.github/workflows/flutter_ci.yml
@@ -0,0 +1,30 @@
+name: Flutter CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  analyze_and_test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Flutter
+        uses: subosito/flutter-action@v2
+        with:
+          flutter-version: 3.41.1
+          channel: stable
+          cache: true
+
+      - name: Flutter pub get
+        run: flutter pub get
+
+      - name: Flutter analyze
+        run: flutter analyze
+
+      - name: Flutter test
+        run: flutter test
diff --git a/docs/SETUP.md b/docs/SETUP.md
index 5365ecd..637cbe2 100644
--- a/docs/SETUP.md
+++ b/docs/SETUP.md
@@ -22,6 +22,25 @@ Use fake gateway for local/offline development:
 flutter run --dart-define=USE_FAKE_BACKEND=true
 ```
 
+## Background Sync
+
+Background sync (startup + resume + periodic ticks while authenticated) is
+enabled by default.
+
+Control flags:
+
+```bash
+flutter run \
+  --dart-define=ENABLE_BACKGROUND_SYNC=true \
+  --dart-define=BACKGROUND_SYNC_INTERVAL_SECONDS=180
+```
+
+Disable it explicitly:
+
+```bash
+flutter run --dart-define=ENABLE_BACKGROUND_SYNC=false
+```
+
 ## Local Persistence Backend
 
 Default local store:
diff --git a/docs/progress.md b/docs/progress.md
index b9bb867..8f90463 100644
--- a/docs/progress.md
+++ b/docs/progress.md
@@ -2,6 +2,51 @@
 
 Updated: 2026-02-15
 
+## Latest Milestone (2026-02-15): Sync Hardening + CI Baseline
+
+Implemented the next production-readiness slice:
+
+- Added lifecycle-aware background sync runner:
+  - `lib/features/sync/sync_auto_trigger_controller.dart`
+  - `lib/features/sync/sync_background_runner.dart`
+  - mounted while authenticated in `lib/main.dart`
+  - behavior: one trigger on app startup, trigger on app resume, periodic sync
+    ticks (default every 180s), cooldown/concurrency guarded
+- Added runtime config flags:
+  - `ENABLE_BACKGROUND_SYNC` (default `true`)
+  - `BACKGROUND_SYNC_INTERVAL_SECONDS` (default `180`)
+  - in `lib/core/config/app_config.dart`
+- Added user-facing rejected mutation handling:
+  - `lib/features/sync/sync_queue_repository.dart` -> `clearRejections()`
+  - `lib/features/sync/sync_view.dart` now renders a `Rejected Changes` section
+    with dismiss action
+- Added tests:
+  - `test/features/sync/sync_auto_trigger_controller_test.dart`
+  - `test/features/sync/sync_queue_repository_test.dart` rejection clear case
+- Added CI workflow:
+  - `.github/workflows/flutter_ci.yml` (`flutter pub get`, `flutter analyze`,
+    `flutter test`)
+- Updated setup docs:
+  - `docs/SETUP.md` with background sync flags
+
+Validation for this milestone:
+
+- `flutter analyze` -> pass
+- `flutter test` -> pass
+
+### Open Phases (Current)
+
+1. Reminder delivery integration:
+   - add platform notification scheduler (local notifications) and wire reminder
+     CRUD/state changes to schedule/cancel/update jobs.
+2. Conflict resolution UX:
+   - current UX shows and dismisses rejections; still missing guided
+     resolve/retry/inspect flows per entity.
+3. Sync trigger maturity:
+   - add connectivity-aware triggers and backoff policy for repeated failures.
+4. Test depth:
+   - add integration tests for auth + sync + CRUD end-to-end app flows.
+
 ## Latest Milestone (2026-02-15): Sync Queue Storage Adapter + Hive Migration
 
 Extended the storage abstraction approach to sync queue persistence: