docs(05-01): complete smart sync with change detection plan

Tasks completed: 2/2
- Add change detection with diff reporting
- Add differential sync with smart-sync flag

SUMMARY: .planning/phases/05-cloudkit-crud/05-01-SUMMARY.md

.planning/phases/05-cloudkit-crud/05-01-SUMMARY.md

@@ -0,0 +1,106 @@
+---
+phase: 05-cloudkit-crud
+plan: 01
+subsystem: data-pipeline
+tags: [cloudkit, python, sync, diff, change-detection]
+
+# Dependency graph
+requires:
+  - phase: 04-canonical-linking
+    provides: 5760 canonicalized games with resolved team/stadium links
+provides:
+  - query_all() method with pagination for CloudKit queries
+  - compute_diff() for comparing local vs cloud records
+  - --diff flag for diff reporting without sync
+  - --smart-sync flag for differential uploads
+  - --delete-orphans flag for removing orphan records
+affects: [05-02-verification, 06-validation-reports]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - "Differential sync with recordChangeTag conflict detection"
+    - "Pagination via continuationMarker for large record sets"
+
+key-files:
+  created: []
+  modified:
+    - Scripts/cloudkit_import.py
+
+key-decisions:
+  - "New records use forceReplace, updated records use update with recordChangeTag"
+  - "Conflict handling (409) retries with forceReplace after re-query"
+  - "Location comparison uses 0.0001 tolerance for lat/lng"
+  - "Orphan deletion requires explicit --delete-orphans flag for safety"
+
+patterns-established:
+  - "Differential sync pattern: query → diff → selective upload"
+  - "Field comparison: direct for strings, tolerance for coords, recordName for refs"
+
+issues-created: []
+
+# Metrics
+duration: 6min
+completed: 2026-01-10
+---
+
+# Phase 5 Plan 1: Smart Sync Summary
+
+**CloudKit differential sync with query_all() pagination, compute_diff() change detection, and --smart-sync flag for selective uploads**
+
+## Performance
+
+- **Duration:** 6 min
+- **Started:** 2026-01-10T16:02:53Z
+- **Completed:** 2026-01-10T16:08:31Z
+- **Tasks:** 2
+- **Files modified:** 1
+
+## Accomplishments
+
+- Added `query_all()` method with pagination using continuationMarker for >200 records
+- Added `compute_diff()` function returning new/updated/unchanged/deleted categorization
+- Added `--diff` flag showing change report without importing
+- Added `--smart-sync` flag for differential uploads (skips unchanged records)
+- Added `--delete-orphans` flag for removing CloudKit records not in local data
+- Added update operation handling with recordChangeTag conflict detection
+- Added menu options 12 (Smart sync) and 13 (Smart sync + delete orphans)
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add change detection with diff reporting** - `0c74495` (feat)
+2. **Task 2: Add differential sync with smart-sync flag** - `d9a6aa4` (feat)
+
+## Files Created/Modified
+
+- `Scripts/cloudkit_import.py` - Added query_all(), compute_diff(), sync_diff(), new flags
+
+## Decisions Made
+
+- New records use forceReplace (creates or replaces)
+- Updated records use update operationType with recordChangeTag
+- Conflict handling (409) retries with forceReplace after re-query
+- Location comparison uses 0.0001 degree tolerance for lat/lng
+- Orphan deletion requires explicit flag (safe by default)
+- Field comparison ignores recordChangeTag and timestamps
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None.
+
+## Next Phase Readiness
+
+- Smart sync infrastructure complete
+- Ready for 05-02: Verification and record management
+- --diff can verify CloudKit state before/after sync operations
+
+---
+*Phase: 05-cloudkit-crud*
+*Completed: 2026-01-10*