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/ROADMAP.md

@@ -82,7 +82,7 @@ Plans:
 **Plans**: 2 plans
 
 Plans:
-- [ ] 05-01: Smart sync with change detection (diff reporting, differential upload)
+- [x] 05-01: Smart sync with change detection (diff reporting, differential upload)
 - [ ] 05-02: Verification and record management (sync verification, individual CRUD)
 
 ### Phase 6: Validation Reports
@@ -106,5 +106,5 @@ Phases execute in numeric order: 1 → 2 → 2.1 → 3 → 4 → 5 → 6
 | 2.1. Additional Sports Stadiums | 3/3 | Complete | 2026-01-10 |
 | 3. Alias Systems | 2/2 | Complete | 2026-01-10 |
 | 4. Canonical Linking | 1/1 | Complete | 2026-01-10 |
-| 5. CloudKit CRUD | 0/2 | In progress | - |
+| 5. CloudKit CRUD | 1/2 | In progress | - |
 | 6. Validation Reports | 0/TBD | Not started | - |

.planning/STATE.md

@@ -5,23 +5,23 @@
 See: .planning/PROJECT.md (updated 2026-01-09)
 
 **Core value:** Every game must correctly link to its teams and stadium — a game at the wrong venue or with broken team links ruins trip planning.
-**Current focus:** Phase 4 — Canonical Linking
+**Current focus:** Phase 5 — CloudKit CRUD
 
 ## Current Position
 
-Phase: 4 of 7 (Canonical Linking) - COMPLETE
-Plan: 1 of 1 in current phase - COMPLETE
-Status: Phase 4 complete, ready for Phase 5
-Last activity: 2026-01-10 — Completed 04-01 (Canonical Linking)
+Phase: 5 of 7 (CloudKit CRUD)
+Plan: 1 of 2 in current phase
+Status: In progress
+Last activity: 2026-01-10 — Completed 05-01 (Smart sync with change detection)
 
-Progress: █████░░░░░ 58% (11 of 19 plans complete)
+Progress: ██████░░░░ 63% (12 of 19 plans complete)
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 11
+- Total plans completed: 12
 - Average duration: 5.8 min
-- Total execution time: 64 min
+- Total execution time: 70 min
 
 **By Phase:**
 
@@ -32,10 +32,11 @@ Progress: █████░░░░░ 58% (11 of 19 plans complete)
 | 2.1. Additional Sports Stadiums | 3/3 | 17 min | 5.7 min |
 | 3. Alias Systems | 2/2 | 6 min | 3 min |
 | 4. Canonical Linking | 1/1 | 4 min | 4 min |
+| 5. CloudKit CRUD | 1/2 | 6 min | 6 min |
 
 **Recent Trend:**
-- Last 5 plans: 02.1-03 (6 min), 03-01 (4 min), 03-02 (2 min), 04-01 (4 min)
-- Trend: Consistent, trending faster
+- Last 5 plans: 03-01 (4 min), 03-02 (2 min), 04-01 (4 min), 05-01 (6 min)
+- Trend: Consistent
 
 ## Accumulated Context
 
@@ -59,6 +60,8 @@ Recent decisions affecting current work:
 - **02.1-03**: Cross-referenced 10 of 13 NWSL stadiums from mls.py for shared venue coordinates
 - **02.1-03**: CBB deferred to future phase (350+ D1 teams requires separate scoped approach)
 - **04-01**: Team abbreviation aliases discovered during canonicalization runs are added iteratively to TEAM_ABBREV_ALIASES
+- **05-01**: New records use forceReplace; updated records use update with recordChangeTag for conflict detection
+- **05-01**: Orphan deletion requires explicit --delete-orphans flag for safety (safe by default)
 
 ### Roadmap Evolution
 
@@ -75,6 +78,6 @@ None yet.
 ## Session Continuity
 
 Last session: 2026-01-10
-Stopped at: Completed Phase 4 (Canonical Linking)
-Resume file: N/A - Phase 4 complete
-Next action: Create Phase 5 plan (CloudKit CRUD)
+Stopped at: Completed 05-01 (Smart sync with change detection)
+Resume file: N/A
+Next action: Execute 05-02 (Verification and record management)

.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*