@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/cloudkit-sync/SKILL.md

@@ -3,12 +3,12 @@ name: cloudkit-sync
 description: "Implement, review, or improve CloudKit and iCloud sync in iOS/macOS apps. Use when working with CKContainer, CKRecord, CKQuery, CKSubscription, CKSyncEngine, CKShare, NSUbiquitousKeyValueStore, or iCloud Drive file coordination; when syncing SwiftData models via ModelConfiguration with cloudKitDatabase; when handling CKError codes for conflict resolution, network failures, or quota limits; or when checking iCloud account status before performing sync operations."
 ---
 
-# CloudKit and iCloud Sync
+# CloudKit
 
 Sync data across devices using CloudKit, iCloud key-value storage, and iCloud
 Drive. Covers container setup, record CRUD, queries, subscriptions, CKSyncEngine,
 SwiftData integration, conflict resolution, and error handling. Targets iOS 26+
-with Swift 6.2; older availability noted where relevant.
+with Swift 6.3; older availability noted where relevant.
 
 ## Contents
 
@@ -28,8 +28,7 @@ with Swift 6.2; older availability noted where relevant.
 
 ## Container and Database Setup
 
-Enable iCloud + CloudKit in Signing & Capabilities. A container provides
-three databases:
+Enable iCloud + CloudKit in Signing & Capabilities. A container provides three databases:
 
 | Database | Scope | Requires iCloud | Storage Quota |
 |----------|-------|-----------------|---------------|
@@ -73,9 +72,12 @@ let updated = try await privateDB.save(fetched)
 try await privateDB.deleteRecord(withID: recordID)
 ```
 
-### Custom Record Zones (Private/Shared Only)
+### Custom Record Zones
 
-Custom zones support atomic commits, change tracking, and sharing.
+Apps create custom zones in the private database. Shared databases expose zones
+that other users share with the current user. Custom zones support atomic
+commits, change tracking, and sharing; public databases do not support custom
+zones.
 
 ```swift
 let zoneID = CKRecordZone.ID(zoneName: "NotesZone")
@@ -92,6 +94,13 @@ Query records with NSPredicate. Supported: `==`, `!=`, `<`, `>`, `<=`, `>=`,
 `BEGINSWITH`, `CONTAINS`, `IN`, `AND`, `NOT`, `BETWEEN`,
 `distanceToLocation:fromLocation:`.
 
+`CONTAINS` tests list membership except for tokenized full-text search with
+`self CONTAINS`. `BEGINSWITH` is the string-prefix operator; unsupported
+operators, key paths, or field types fail when the query executes.
+For every encryption review, explicitly call out field eligibility: encrypted
+values cannot be queried or sorted; `CKAsset` is encrypted by default; and
+`CKRecord.Reference` cannot be encrypted because CloudKit needs it server-side.
+
 ```swift
 let predicate = NSPredicate(format: "title BEGINSWITH %@", "Meeting")
 let query = CKQuery(recordType: "Note", predicate: predicate)
@@ -122,7 +131,9 @@ let compound = NSCompoundPredicate(andPredicateWithSubpredicates: [
 ## CKSubscription
 
 Subscriptions trigger push notifications when records change server-side.
-CloudKit auto-enables APNs -- no explicit push entitlement needed.
+CloudKit/Xcode handles the APNs entitlement when CloudKit is enabled; no
+separate explicit App ID push setup is needed. Silent/background processing
+still needs Background Modes > Remote notifications.
 
 ```swift
 // Query subscription -- fires when matching records change
@@ -167,9 +178,12 @@ func application(
 
 ## CKSyncEngine (iOS 17+)
 
-`CKSyncEngine` is the recommended sync approach. It handles scheduling,
-transient error retries, change tokens, and push notifications automatically.
-Works with private and shared databases only.
+`CKSyncEngine` is the recommended sync approach for custom model data. It
+handles scheduling, transient retries, change tokens, and database
+subscriptions, but not app-specific save failures: `CKError.serverRecordChanged`
+from `sentRecordZoneChanges.failedRecordSaves` still requires custom conflict
+resolution and rescheduling. Automatic sync timing is indeterminate. Requires
+CloudKit capability + Remote notifications; private/shared databases only.
 
 ```swift
 import CloudKit
@@ -186,7 +200,7 @@ final class SyncManager: CKSyncEngineDelegate {
         self.syncEngine = CKSyncEngine(config)
     }
 
-    func handleEvent(_ event: CKSyncEngine.Event, syncEngine: CKSyncEngine) {
+    func handleEvent(_ event: CKSyncEngine.Event, syncEngine: CKSyncEngine) async {
         switch event {
         case .stateUpdate(let update):
             Self.saveState(update.stateSerialization)
@@ -205,10 +219,11 @@ final class SyncManager: CKSyncEngineDelegate {
     func nextRecordZoneChangeBatch(
         _ context: CKSyncEngine.SendChangesContext,
         syncEngine: CKSyncEngine
-    ) -> CKSyncEngine.RecordZoneChangeBatch? {
+    ) async -> CKSyncEngine.RecordZoneChangeBatch? {
         let pending = syncEngine.state.pendingRecordZoneChanges
-        return CKSyncEngine.RecordZoneChangeBatch(
-            pendingChanges: Array(pending)
+            .filter { context.options.zoneIDs.contains($0) }
+        return await CKSyncEngine.RecordZoneChangeBatch(
+            pendingChanges: pending
         ) { recordID in self.recordToSend(for: recordID) }
     }
 }
@@ -228,8 +243,15 @@ to resume from the correct change token.
 
 ## SwiftData + CloudKit
 
-`ModelConfiguration` supports CloudKit sync. CloudKit models must use optional
-properties and avoid unique constraints.
+`ModelConfiguration` supports CloudKit sync. In every SwiftData CloudKit
+implementation or review, always report two verdicts:
+
+- **Model compatibility**: no `#Unique` or unique constraints, optional
+  relationships, no `.deny`, and external storage for large `Data`.
+- **Schema rollout**: initialize the development schema in nonproduction builds,
+  verify it in CloudKit Dashboard, promote it before release, and after
+  production promotion only add schema; don't delete model types or change
+  existing attributes.
 
 ```swift
 import SwiftData
@@ -255,10 +277,6 @@ let config = ModelConfiguration(
 let container = try ModelContainer(for: Note.self, configurations: config)
 ```
 
-**CloudKit model rules**: use optionals for all non-String properties; avoid
-`#Unique`; keep models flat; use `@Attribute(.externalStorage)` for large data;
-avoid complex relationship graphs.
-
 ## NSUbiquitousKeyValueStore
 
 Simple key-value sync. Max 1024 keys, 1 MB total, 1 MB per value. Stores
@@ -300,35 +318,28 @@ NotificationCenter.default.addObserver(
 
 ## iCloud Drive File Sync
 
-Use `FileManager` ubiquity APIs for document-level sync.
+Use `FileManager` ubiquity APIs for document-level sync. Call
+`url(forUbiquityContainerIdentifier:)` and `setUbiquitous` off the main thread;
+`setUbiquitous` performs coordinated file work and can block. If the app is
+presenting the file, configure an active file presenter before moving it.
 
 ```swift
-guard let ubiquityURL = FileManager.default.url(
-    forUbiquityContainerIdentifier: "iCloud.com.example.app"
-) else { return }  // iCloud not available
-
-let docsURL = ubiquityURL.appendingPathComponent("Documents")
-let cloudURL = docsURL.appendingPathComponent("report.pdf")
-try FileManager.default.setUbiquitous(true, itemAt: localURL, destinationURL: cloudURL)
-
-// Monitor iCloud files
-let query = NSMetadataQuery()
-query.predicate = NSPredicate(format: "%K LIKE '*.pdf'", NSMetadataItemFSNameKey)
-query.searchScopes = [NSMetadataQueryUbiquitousDocumentsScope]
-NotificationCenter.default.addObserver(
-    forName: .NSMetadataQueryDidFinishGathering, object: query, queue: .main
-) { _ in
-    query.disableUpdates()
-    for item in query.results as? [NSMetadataItem] ?? [] {
-        let name = item.value(forAttribute: NSMetadataItemFSNameKey) as? String
-        let status = item.value(
-            forAttribute: NSMetadataUbiquitousItemDownloadingStatusKey) as? String
-    }
-    query.enableUpdates()
+Task.detached {
+    guard let ubiquityURL = FileManager.default.url(
+        forUbiquityContainerIdentifier: "iCloud.com.example.app"
+    ) else { return }  // iCloud not available
+
+    let docsURL = ubiquityURL.appendingPathComponent("Documents")
+    try FileManager.default.createDirectory(at: docsURL, withIntermediateDirectories: true)
+    let cloudURL = docsURL.appendingPathComponent("report.pdf")
+    try FileManager.default.setUbiquitous(true, itemAt: localURL, destinationURL: cloudURL)
 }
-query.start()
 ```
 
+Monitor files with `NSMetadataQuery` scoped to
+`NSMetadataQueryUbiquitousDocumentsScope` or
+`NSMetadataQueryUbiquitousDataScope`.
+
 ## Account Status and Error Handling
 
 Always check account status before sync. Listen for `.CKAccountChanged`.
@@ -435,9 +446,6 @@ try await privateDB.save(record)
 **DON'T:** Store user-specific data in the public database.
 **DO:** Use private database for personal data; public only for app-wide content.
 
-**DON'T:** Assume data is available immediately after save.
-**DO:** Update local cache optimistically and reconcile on fetch.
-
 **DON'T:** Poll for changes on a timer.
 **DO:** Use `CKDatabaseSubscription` or `CKSyncEngine` for push-based sync.
 ```swift
@@ -453,8 +461,8 @@ try await privateDB.save(sub)
 **DON'T:** Retry immediately on rate limiting.
 **DO:** Use `CKError.retryAfterSeconds` to wait the required duration.
 
-**DON'T:** Merge conflict changes into `clientRecord`.
-**DO:** Always merge into `serverRecord` -- it has the correct change tag.
+**DON'T:** Assume `CKSyncEngine` handles `.serverRecordChanged` conflicts for you.
+**DO:** Resolve `failedRecordSaves` with a three-way merge, then reschedule the save.
 
 **DON'T:** Pass nil change token on every fetch.
 **DO:** Persist change tokens to disk and supply them on subsequent fetches.
@@ -464,22 +472,21 @@ try await privateDB.save(sub)
 - [ ] iCloud + CloudKit capability enabled in Signing & Capabilities
 - [ ] Account status checked before sync; `.noAccount` handled gracefully
 - [ ] Private database used for user data; public only for shared content
+- [ ] Custom record zones created in private DB; shared DB zones discovered from shares
 - [ ] `CKError.serverRecordChanged` handled with three-way merge into `serverRecord`
 - [ ] Network failures queued for retry; `retryAfterSeconds` respected
-- [ ] `CKDatabaseSubscription` or `CKSyncEngine` used for push-based sync
+- [ ] `CKDatabaseSubscription` or `CKSyncEngine` used for push-based sync; Remote notifications enabled for background delivery
 - [ ] Change tokens persisted to disk; `changeTokenExpired` resets and refetches
 - [ ] `.partialFailure` errors inspected per-item via `partialErrorsByItemID`
 - [ ] `.userDeletedZone` handled by recreating zone and resyncing
-- [ ] SwiftData CloudKit models use optionals, no `#Unique`, `.externalStorage` for large data
+- [ ] SwiftData CloudKit review reports model compatibility and schema rollout: initialized/verified development schema, promoted before release, and additive-only production changes
 - [ ] `NSUbiquitousKeyValueStore.didChangeExternallyNotification` observed
-- [ ] Sensitive data uses `encryptedValues` on CKRecord (not plain fields)
+- [ ] Encryption review says `CKRecord.Reference` cannot use `encryptedValues` because CloudKit needs it server-side; no query/sort on encrypted fields; `CKAsset` is encrypted by default
 - [ ] `CKSyncEngine` state serialization persisted across launches (iOS 17+)
 
 ## References
 
-- See `references/cloudkit-patterns.md` for CKFetchRecordZoneChangesOperation
-  incremental sync, CKShare collaboration, record zone management, CKAsset
-  file storage, batch operations, and CloudKit Dashboard usage.
+- See [references/cloudkit-patterns.md](references/cloudkit-patterns.md) for incremental sync, CKShare, zones, CKAsset storage, batch operations, and Dashboard usage.
 - [CloudKit Framework](https://sosumi.ai/documentation/cloudkit)
 - [CKContainer](https://sosumi.ai/documentation/cloudkit/ckcontainer)
 - [CKRecord](https://sosumi.ai/documentation/cloudkit/ckrecord)
@@ -489,4 +496,4 @@ try await privateDB.save(sub)
 - [CKShare](https://sosumi.ai/documentation/cloudkit/ckshare)
 - [CKError](https://sosumi.ai/documentation/cloudkit/ckerror)
 - [NSUbiquitousKeyValueStore](https://sosumi.ai/documentation/foundation/nsubiquitouskeyvaluestore)
-- [CKAsset](https://sosumi.ai/documentation/cloudkit/ckasset)
+- [SwiftData CloudKit sync](https://sosumi.ai/documentation/swiftdata/syncing-model-data-across-a-persons-devices)

package/pipeline/skills/shared/external/cloudkit-sync/evals/evals.json

@@ -0,0 +1,47 @@
+{
+  "skill_name": "cloudkit",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Review this iOS 26 CloudKit sync plan: a CKSyncEngine is configured against the public database, the app only enables iCloud + CloudKit, handleEvent and nextRecordZoneChangeBatch are implemented synchronously, nextRecordZoneChangeBatch returns every pending record-zone change, and the team expects automatic sync to run immediately after each local edit. Write concise corrected guidance with Swift snippets where useful.",
+      "expected_output": "A review that corrects CKSyncEngine database scope, Remote notifications setup, async delegate signatures, context-scoped change batches, state persistence, and automatic sync timing.",
+      "files": [],
+      "assertions": [
+        "States that CKSyncEngine is for private or shared databases and must not sync the public database.",
+        "States that CloudKit plus Remote notifications background mode are required for CKSyncEngine/background delivery.",
+        "Uses async CKSyncEngineDelegate signatures for handleEvent and nextRecordZoneChangeBatch.",
+        "Filters pending record-zone changes to the send context scope, such as context.options.zoneIDs.",
+        "Explains that automatic sync timing is indeterminate and immediate sync requires fetchChanges or sendChanges.",
+        "Mentions persisting CKSyncEngine stateSerialization across launches."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Review this SwiftData model for CloudKit sync: it uses @Unique on an email field, has a nonoptional @Relationship(deleteRule: .deny) to Owner, stores a large image Data property without .externalStorage, and the reviewer says every scalar property must be optional. Explain what should change and what should not be overcorrected.",
+      "expected_output": "A review that flags SwiftData CloudKit schema incompatibilities without incorrectly requiring every scalar property to become optional.",
+      "files": [],
+      "assertions": [
+        "Flags @Unique or unique constraints as unsupported by SwiftData CloudKit sync.",
+        "Flags nonoptional relationships as incompatible and recommends optional relationships.",
+        "Flags the .deny relationship delete rule as incompatible with CloudKit sync.",
+        "Recommends @Attribute(.externalStorage) for large Data fields.",
+        "Does not claim every scalar property must be optional.",
+        "Mentions CloudKit production schemas are additive or require schema promotion care."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Review this CloudKit data/query plan: the app stores sensitive profile fields in record.encryptedValues in the public database, adds a new encrypted field to an already-deployed field name, sorts and filters CKQuery results by that encrypted field, uses title CONTAINS 'road' for substring search, and stores image files as CKAsset. Give corrected guidance.",
+      "expected_output": "A review that corrects encrypted field limits, query predicate semantics, and CKAsset handling.",
+      "files": [],
+      "assertions": [
+        "States that encryptedValues are not available for public database records.",
+        "States that CloudKit can encrypt only new schema fields, not convert an existing field name to encrypted storage.",
+        "States that encrypted fields cannot be indexed, queried, or sorted.",
+        "Explains that CKQuery CONTAINS is list membership except self CONTAINS tokenized full-text search.",
+        "Recommends BEGINSWITH or self CONTAINS where appropriate instead of title CONTAINS for substring search.",
+        "States that CKAsset data is already encrypted by default or does not need encryptedValues."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/cloudkit-sync/references/cloudkit-patterns.md

@@ -216,8 +216,7 @@ func userDidAcceptCloudKitShare(with metadata: CKShare.Metadata) {
     let container = CKContainer(identifier: metadata.containerIdentifier)
     Task {
         do {
-            let share = try await container.accept(metadata)
-            print("Accepted share: \(share.url?.absoluteString ?? "")")
+            try await container.accept([metadata])
             // Fetch shared records from container.sharedCloudDatabase
         } catch {
             print("Accept failed: \(error)")
@@ -384,8 +383,12 @@ database.add(operation)
 
 ## Encrypted Fields
 
-Use `encryptedValues` (iOS 15+) for sensitive data. Encrypted fields are not
-searchable or sortable.
+Use `encryptedValues` (iOS 15+) for sensitive private or shared data that does
+not need query or sort indexes. CloudKit can encrypt only new schema fields;
+you cannot convert an existing field to encrypted storage, and encrypted values
+are unavailable for public database records. `CKAsset` data is encrypted by
+default, while `CKRecord.Reference` is not encrypted because CloudKit needs it
+for server-side relationship handling.
 
 ```swift
 let record = CKRecord(recordType: "HealthEntry")

package/pipeline/skills/shared/external/contacts-framework/SKILL.md

@@ -7,7 +7,7 @@ description: "Read, create, update, and pick contacts using the Contacts and Con
 
 Fetch, create, update, and pick contacts from the user's Contacts database using
 `CNContactStore`, `CNSaveRequest`, and `CNContactPickerViewController`. Targets
-Swift 6.2 / iOS 26+.
+Swift 6.3 / iOS 26+.
 
 ## Contents
 
@@ -26,15 +26,15 @@ Swift 6.2 / iOS 26+.
 
 ### Project Configuration
 
-1. Add `NSContactsUsageDescription` to Info.plist explaining why the app accesses contacts
-2. No additional capability or entitlement is required for basic Contacts access
-3. For contact notes access, add the `com.apple.developer.contacts.notes` entitlement
+1. Add `NSContactsUsageDescription` to Info.plist explaining why the app accesses contacts. The app crashes if it uses contact data APIs without this key.
+2. No additional capability or entitlement is required for ordinary Contacts access.
+3. Add `com.apple.developer.contacts.notes` only when reading or writing `CNContactNoteKey` / `CNContact.note`; this entitlement requires Apple approval before public distribution.
 
 ### Imports
 
 ```swift
-import Contacts       // CNContactStore, CNSaveRequest, CNContact
-import ContactsUI     // CNContactPickerViewController
+@preconcurrency import Contacts  // CNContactStore, CNSaveRequest, CNContact
+import ContactsUI                // CNContactPickerViewController
 ```
 
 ## Authorization
@@ -66,10 +66,18 @@ func checkStatus() -> CNAuthorizationStatus {
 | `.restricted` | Parental controls or MDM restrict access |
 | `.limited` | iOS 18+: user granted access to selected contacts only |
 
+Treat both `.authorized` and `.limited` as usable Contacts API states. With
+`.limited`, fetch, edit, and delete operations only apply to contacts the user
+granted or the app created. Use `ContactAccessButton` or
+`contactAccessPicker(isPresented:completionHandler:)` to let users add contacts
+to the app's limited-access set.
+
 ## Fetching Contacts
 
 Use `unifiedContacts(matching:keysToFetch:)` for predicate-based queries.
 Use `enumerateContacts(with:usingBlock:)` for batch enumeration of all contacts.
+For large cached address books, first fetch identifiers, then fetch detailed
+contacts in batches by identifier.
 
 ### Fetch by Name
 
@@ -313,13 +321,15 @@ Over-fetching wastes memory and slows queries, especially for contacts with
 large photos.
 
 ```swift
-// WRONG: Fetches everything including full-resolution photos
-let keys: [CNKeyDescriptor] = [CNContactCompleteNameKey as CNKeyDescriptor,
+// WRONG: Fetches far more than the UI displays, including full-resolution photos
+let keys: [CNKeyDescriptor] = [
+    CNContactFormatter.descriptorForRequiredKeys(for: .fullName),
     CNContactImageDataKey as CNKeyDescriptor,
     CNContactPhoneNumbersKey as CNKeyDescriptor,
     CNContactEmailAddressesKey as CNKeyDescriptor,
     CNContactPostalAddressesKey as CNKeyDescriptor,
-    CNContactBirthdayKey as CNKeyDescriptor]
+    CNContactBirthdayKey as CNKeyDescriptor
+]
 
 // CORRECT: Fetch only what you display
 let keys: [CNKeyDescriptor] = [
@@ -362,7 +372,9 @@ mutable.givenName = "New Name"
 
 ### DON'T: Skip authorization and assume access
 
-Without calling `requestAccess(for:)`, fetch methods return empty results or throw.
+Do not let fetch or save calls be the first place the user sees authorization.
+If status is `.notDetermined`, request access; if access was denied, contact
+operations fail with an authorization error.
 
 ```swift
 // WRONG: Jump straight to fetch
@@ -377,6 +389,9 @@ let contacts = try store.unifiedContacts(matching: predicate, keysToFetch: keys)
 ### DON'T: Run heavy fetches on the main thread
 
 `enumerateContacts` performs I/O. Running it on the main thread blocks the UI.
+When strict concurrency checks complain about `CNContact` crossing task or actor
+boundaries, use `@preconcurrency import Contacts` in that file or map contacts
+into Sendable view models before returning them.
 
 ```swift
 // WRONG: Main thread enumeration
@@ -400,6 +415,8 @@ func loadContacts() async throws -> [CNContact] {
 
 - [ ] `NSContactsUsageDescription` added to Info.plist
 - [ ] `requestAccess(for: .contacts)` called before fetch or save operations
+- [ ] `.limited` treated as usable access with selected-contact caveats
+- [ ] `ContactAccessButton` or `contactAccessPicker` offered when users need to expand limited access
 - [ ] Authorization denial handled gracefully (guide user to Settings)
 - [ ] Only needed `CNKeyDescriptor` keys included in fetch requests
 - [ ] `CNContactFormatter.descriptorForRequiredKeys(for:)` used when formatting names
@@ -413,7 +430,7 @@ func loadContacts() async throws -> [CNContact] {
 
 ## References
 
-- Extended patterns (multi-select picker, vCard export, search optimization): `references/contacts-patterns.md`
+- Extended patterns (multi-select picker, vCard export, search optimization): [references/contacts-patterns.md](references/contacts-patterns.md)
 - [Contacts framework](https://sosumi.ai/documentation/contacts)
 - [CNContactStore](https://sosumi.ai/documentation/contacts/cncontactstore)
 - [CNContactFetchRequest](https://sosumi.ai/documentation/contacts/cncontactfetchrequest)
@@ -423,3 +440,6 @@ func loadContacts() async throws -> [CNContact] {
 - [CNContactPickerDelegate](https://sosumi.ai/documentation/contactsui/cncontactpickerdelegate)
 - [Accessing the contact store](https://sosumi.ai/documentation/contacts/accessing-the-contact-store)
 - [NSContactsUsageDescription](https://sosumi.ai/documentation/bundleresources/information-property-list/nscontactsusagedescription)
+- [ContactAccessButton](https://sosumi.ai/documentation/contactsui/contactaccessbutton)
+- [contactAccessPicker(isPresented:completionHandler:)](https://sosumi.ai/documentation/swiftui/view/contactaccesspicker(ispresented:completionhandler:))
+- [Contact Keys](https://sosumi.ai/documentation/contacts/contact-keys)

package/pipeline/skills/shared/external/contacts-framework/evals/evals.json

@@ -0,0 +1,41 @@
+{
+  "skill_name": "contacts-framework",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I'm updating an iOS 26 SwiftUI contacts screen. It currently treats only CNAuthorizationStatus.authorized as usable and hides the list for .limited. Review the approach and show the authorization handling I should use, including how someone can add more contacts later.",
+      "expected_output": "Guidance that treats .authorized and .limited as usable Contacts API states, explains limited-access restrictions, and uses ContactsUI limited-access controls.",
+      "files": [],
+      "assertions": [
+        "Treats both .authorized and .limited as states where Contacts API fetch/save code can proceed.",
+        "Explains that .limited exposes only user-granted or app-created contacts, not the whole address book.",
+        "Recommends ContactAccessButton or contactAccessPicker for expanding limited access.",
+        "Distinguishes limited-access management from CNContactPickerViewController selection."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Review this Contacts fetch plan: use CNContactCompleteNameKey for the displayed name, include CNContactImageDataKey by default for avatars, and fetch CNContactNoteKey so the app can show notes. What should change before I ship?",
+      "expected_output": "A source-grounded correction that uses valid name descriptors, avoids over-fetching images, and narrows the notes entitlement requirement.",
+      "files": [],
+      "assertions": [
+        "Rejects CNContactCompleteNameKey and uses CNContactFormatter.descriptorForRequiredKeys(for:) or valid individual name keys instead.",
+        "Recommends fetching only displayed fields and using thumbnail image data for list avatars instead of full image data by default.",
+        "States that CNContactNoteKey / CNContact.note requires the com.apple.developer.contacts.notes entitlement on modern Apple platforms.",
+        "Mentions that the contacts notes entitlement requires Apple approval before public App Store distribution."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "I want a no-permission contact picker for email selection and an incremental Contacts sync. The draft uses CNContactPickerViewController plus store.enumerateChanges(matching: CNChangeHistoryFetchRequest()). Review the API boundaries and give iOS Swift-safe guidance.",
+      "expected_output": "Guidance that keeps picker selection scoped to the user's final choice and rejects unsupported Swift change-history examples.",
+      "files": [],
+      "assertions": [
+        "States that CNContactPickerViewController does not require full Contacts authorization and returns only the user's final selection.",
+        "Mentions picker predicates such as predicateForEnablingContact or predicateForSelectionOfProperty must be configured before presentation.",
+        "Rejects store.enumerateChanges(matching:) as a nonexistent Contacts Swift API.",
+        "Explains that the change-history enumerator is Objective-C-only / unavailable in Swift and recommends CNContactStoreDidChange refetching or an explicit Objective-C bridge for true incremental history."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/contacts-framework/references/contacts-patterns.md

@@ -9,15 +9,17 @@ Overflow reference for the `contacts-framework` skill. Contains advanced pattern
 - [Search and Filtering](#search-and-filtering)
 - [vCard Import and Export](#vcard-import-and-export)
 - [Contact Groups](#contact-groups)
-- [Change History](#change-history)
+- [Change Notifications and Swift Boundaries](#change-notifications-and-swift-boundaries)
 
 ## Contacts SwiftUI Integration
 
-### Contact Manager with @Observable
+### Contact Manager with `@Observable`
 
 ```swift
-import Contacts
+@preconcurrency import Contacts
+import ContactsUI
 import SwiftUI
+import UIKit
 
 @Observable
 @MainActor
@@ -25,22 +27,27 @@ final class ContactManager {
     let store = CNContactStore()
 
     var contacts: [CNContact] = []
-    var isAuthorized = false
+    var canAccessContacts = false
+    var hasLimitedAccess = false
     var authorizationStatus: CNAuthorizationStatus = .notDetermined
 
     func checkAuthorization() {
-        authorizationStatus = CNContactStore.authorizationStatus(for: .contacts)
-        isAuthorized = authorizationStatus == .authorized
+        updateAuthorization(CNContactStore.authorizationStatus(for: .contacts))
     }
 
     func requestAccess() async throws {
-        let granted = try await store.requestAccess(for: .contacts)
-        isAuthorized = granted
-        authorizationStatus = CNContactStore.authorizationStatus(for: .contacts)
+        _ = try await store.requestAccess(for: .contacts)
+        updateAuthorization(CNContactStore.authorizationStatus(for: .contacts))
+    }
+
+    func updateAuthorization(_ status: CNAuthorizationStatus) {
+        authorizationStatus = status
+        canAccessContacts = status == .authorized || status == .limited
+        hasLimitedAccess = status == .limited
     }
 
     func loadContacts() async throws {
-        guard isAuthorized else { return }
+        guard canAccessContacts else { return }
 
         let keys: [CNKeyDescriptor] = [
             CNContactGivenNameKey as CNKeyDescriptor,
@@ -78,7 +85,7 @@ struct ContactListView: View {
     var body: some View {
         NavigationStack {
             Group {
-                if !manager.isAuthorized {
+                if !manager.canAccessContacts {
                     ContentUnavailableView {
                         Label("Contacts Access", systemImage: "person.crop.circle.badge.questionmark")
                     } description: {
@@ -91,12 +98,15 @@ struct ContactListView: View {
                     }
                 } else {
                     contactList
+                    if manager.hasLimitedAccess {
+                        limitedAccessControls
+                    }
                 }
             }
             .navigationTitle("Contacts")
             .task {
                 manager.checkAuthorization()
-                if manager.isAuthorized {
+                if manager.canAccessContacts {
                     try? await manager.loadContacts()
                 }
             }
@@ -105,7 +115,7 @@ struct ContactListView: View {
 
     private var contactList: some View {
         List(manager.contacts, id: \.identifier) { contact in
-            HStack(spacing: 12) {
+            HStack {
                 contactAvatar(contact)
                 VStack(alignment: .leading) {
                     Text(manager.formattedName(for: contact))
@@ -136,9 +146,28 @@ struct ContactListView: View {
                 .foregroundStyle(.secondary)
         }
     }
+
+    @State private var isPresentingContactAccessPicker = false
+
+    private var limitedAccessControls: some View {
+        Button {
+            isPresentingContactAccessPicker = true
+        } label: {
+            Label("Add Contacts", systemImage: "person.crop.circle.badge.plus")
+        }
+        .contactAccessPicker(isPresented: $isPresentingContactAccessPicker) { identifiers in
+            guard !identifiers.isEmpty else { return }
+            Task { try? await manager.loadContacts() }
+        }
+    }
 }
 ```
 
+Under `.limited`, the app can still use Contacts APIs, but only for contacts the
+user has granted or the app created. `ContactAccessButton` works well beside a
+search field; `contactAccessPicker(isPresented:completionHandler:)` presents a
+management sheet and returns identifiers for newly granted contacts only.
+
 ## Multi-Select Contact Picker
 
 ### SwiftUI Wrapper for Multi-Selection
@@ -354,45 +383,16 @@ func removeContactFromGroup(contact: CNContact, group: CNGroup) throws {
 }
 ```
 
-## Change History
+## Change Notifications and Swift Boundaries
 
-Use `CNChangeHistoryFetchRequest` to fetch incremental changes since a saved token.
-This is efficient for syncing contact data.
-
-```swift
-func fetchChanges(since token: Data?) throws {
-    let request = CNChangeHistoryFetchRequest()
-    request.startingToken = token
-    request.additionalContactKeyDescriptors = [
-        CNContactGivenNameKey as CNKeyDescriptor,
-        CNContactFamilyNameKey as CNKeyDescriptor
-    ]
-
-    let result = try store.enumerateChanges(matching: request)
-
-    for event in result {
-        switch event {
-        case let addEvent as CNChangeHistoryAddContactEvent:
-            let contact = addEvent.contact
-            print("Added: \(contact.givenName) \(contact.familyName)")
-
-        case let updateEvent as CNChangeHistoryUpdateContactEvent:
-            let contact = updateEvent.contact
-            print("Updated: \(contact.givenName) \(contact.familyName)")
-
-        case let deleteEvent as CNChangeHistoryDeleteContactEvent:
-            let identifier = deleteEvent.contactIdentifier
-            print("Deleted: \(identifier)")
-
-        default:
-            break
-        }
-    }
-
-    // Save the new token for next sync
-    let newToken = store.currentHistoryToken
-}
-```
+For Swift-first apps, use `CNContactStoreDidChange` to invalidate caches and
+refetch the contacts your authorization status allows. Do not write Swift code
+that calls `store.enumerateChanges(matching:)`; that method does not exist.
+Apple's change-history fetch entry point is the Objective-C
+`enumeratorForChangeHistoryFetchRequest:error:` selector, while the Swift
+`enumerator(for:)` overlay is marked unavailable. If a product truly needs
+incremental history tokens, isolate that bridge in Objective-C and expose a
+small Swift wrapper; otherwise, refetch on change notifications.
 
 ### Watching for Real-Time Changes