@mmerterden/multi-agent-pipeline 8.6.2 → 10.0.6

package/pipeline/skills/shared/external/push-notifications/SKILL.md

@@ -1,14 +1,17 @@
 ---
 name: push-notifications
-description: "Implement, review, or debug push notifications in iOS/macOS apps — local notifications, remote (APNs) notifications, rich notifications, notification actions, silent pushes, and notification service/content extensions. Use when working with UNUserNotificationCenter, registering for remote notifications, handling notification payloads, setting up notification categories and actions, creating rich notification content, or debugging notification delivery. Also use when working with alerts, badges, sounds, background pushes, or user notification permissions in Swift apps."
+description: "Implement, review, or debug push notifications in iOS/macOS apps  -  local notifications, remote (APNs) notifications, rich notifications, notification actions, silent pushes, and notification service/content extensions. Use when working with UNUserNotificationCenter, registering for remote notifications, handling notification payloads, setting up notification categories and actions, creating rich notification content, or debugging notification delivery. Also use when working with alerts, badges, sounds, background pushes, or user notification permissions in Swift apps."
 ---
 
 # Push Notifications
 
-Implement, review, and debug local and remote notifications on iOS/macOS using `UserNotifications` and APNs. Covers permission flow, token registration, payload structure, foreground handling, notification actions, grouping, and rich notifications. Targets iOS 26+ with Swift 6.2, backward-compatible to iOS 16 unless noted.
+Implement, review, and debug local and remote notifications on iOS/macOS using `UserNotifications` and APNs. Covers permission flow, token registration, payload structure, foreground handling, notification actions, grouping, and rich notifications. Targets iOS 26+ with Swift 6.3, backward-compatible to iOS 16 unless noted.
+
+Keep adjacent domains separate: Live Activity `content-state` payloads belong in `activitykit`; PushKit/VoIP call pushes belong in `callkit`; App Clip ephemeral notification setup belongs in `app-clips`; long-running or scheduled background work after a silent push belongs in `background-processing`.
 
 ## Contents
 
+- [Correction Reviews](#correction-reviews)
 - [Permission Flow](#permission-flow)
 - [APNs Registration](#apns-registration)
 - [Local Notifications](#local-notifications)
@@ -20,9 +23,13 @@ Implement, review, and debug local and remote notifications on iOS/macOS using `
 - [Review Checklist](#review-checklist)
 - [References](#references)
 
+## Correction Reviews
+
+When reviewing flawed notification proposals, explicitly name the violated contract. APNs token reviews must say token registration is independent from alert authorization, upload on every `didRegister` callback, avoid local-cache-as-truth logic, never assume token length, and treat Simulator registration failure as expected while noting `.apns` files or `simctl push` can simulate delivery. Background-push reviews must say `content-available` only, `apns-push-type: background`, `apns-priority: 5`, Remote notifications background mode, low priority, throttled, not guaranteed, not every few minutes, and bounded `didReceiveRemoteNotification` returning the correct `UIBackgroundFetchResult`. Rich-notification reviews must say service extensions require `mutable-content: 1` plus an alert payload, silent pushes do not trigger them, attachments are supported on-disk files that the system validates and stores, secrets use Keychain Sharing while App Groups are for shared files/UserDefaults, communication notifications require capability + `NSUserActivityTypes` + `INInteraction` donation + `content.updating(from:)`, and every service-extension path including attachment/download failures and `serviceExtensionTimeWillExpire()` must call the content handler exactly once with original, best-attempt, or updated content.
+
 ## Permission Flow
 
-Request notification authorization before doing anything else. The system prompt appears only once; subsequent calls return the stored decision.
+Request notification authorization before scheduling or displaying user-visible alerts, sounds, or badges. The system prompt appears only once; subsequent calls return the stored decision. APNs token registration is separate: call `registerForRemoteNotifications()` when the app needs a device token, even if the user hasn't granted alert authorization.
 
 ```swift
 import UserNotifications
@@ -77,22 +84,7 @@ try await center.requestAuthorization(
 
 ### Handling Denied Permissions
 
-When the user has denied notifications, guide them to Settings. Do not repeatedly prompt or nag.
-
-```swift
-struct NotificationSettingsButton: View {
-    @Environment(\.openURL) private var openURL
-
-    var body: some View {
-        Button("Open Settings") {
-            if let url = URL(string: UIApplication.openSettingsURLString) {
-                openURL(url)
-            }
-        }
-    }
-}
-
-```
+When the user has denied notifications, guide them to Settings with `UIApplication.openSettingsURLString`. Do not repeatedly prompt or nag.
 
 ## APNs Registration
 
@@ -134,27 +126,33 @@ class AppDelegate: NSObject, UIApplicationDelegate {
         didFailToRegisterForRemoteNotificationsWithError error: Error
     ) {
         print("APNs registration failed: \(error.localizedDescription)")
-        // Simulator always fails -- this is expected during development
+        // Simulator can simulate pushes, but it does not register with APNs.
     }
 }
 ```
 
 ### Registration Order
 
-Request authorization first, then register for remote notifications. Registration triggers the system to contact APNs and return a device token.
+Configure delegates and categories at launch. Then request user-notification authorization in context for visible notifications, and register with APNs whenever the app needs a device token. Do not gate APNs registration on `.authorized`; without alert authorization, remote notifications are delivered silently.
 
 ```swift
 @MainActor
-func registerForPush() async {
-    let granted = await requestNotificationPermission()
-    guard granted else { return }
+func configureNotifications() async {
+    let center = UNUserNotificationCenter.current()
+    let settings = await center.notificationSettings()
+
+    if settings.authorizationStatus == .notDetermined {
+        _ = await requestNotificationPermission()
+    }
+
+    // Needed for APNs token delivery and silent remote notifications.
     UIApplication.shared.registerForRemoteNotifications()
 }
 ```
 
 ### Token Handling
 
-Device tokens change. Re-send the token to your server every time `didRegisterForRemoteNotificationsWithDeviceToken` fires, not just the first time. The system calls this method on every app launch that calls `registerForRemoteNotifications()`.
+Device tokens change. Re-send the token to your server every time `didRegisterForRemoteNotificationsWithDeviceToken` fires, not just the first time. Do not persist tokens locally as a source of truth or assume a fixed token length.
 
 ## Local Notifications
 
@@ -168,7 +166,7 @@ content.title = "Workout Reminder"
 content.subtitle = "Time to move"
 content.body = "You have a scheduled workout in 15 minutes."
 content.sound = .default
-content.badge = 1
+content.badge = NSNumber(value: 1)
 content.userInfo = ["workoutId": "abc123"]
 content.threadIdentifier = "workouts"  // groups in notification center
 ```
@@ -249,7 +247,7 @@ let pending = await center.pendingNotificationRequests()
 
 ### Silent / Background Push
 
-Set `content-available: 1` with no alert, sound, or badge. The system wakes the app in the background. Requires the "Background Modes > Remote notifications" capability.
+Set `content-available: 1` with no alert, sound, or badge. Requires "Background Modes > Remote notifications" plus APNs headers `apns-push-type: background` and `apns-priority: 5`. The system treats these as low priority, throttled, and not guaranteed; do not send them every few minutes or rely on them for immediate freshness. In `didReceiveRemoteNotification`, do bounded work and return a `UIBackgroundFetchResult` promptly, within the background execution window.
 
 ```json
 {
@@ -280,7 +278,7 @@ func application(
 
 ### Mutable Content
 
-Set `mutable-content: 1` to allow a Notification Service Extension to modify content before display. Use for downloading images, decrypting content, or adding attachments.
+Set `mutable-content: 1` plus an `alert` dictionary to let a Notification Service Extension modify an alerting remote notification before display. Silent pushes do not trigger the service extension. Use service extensions for bounded work such as downloading supported on-disk attachments, decrypting display text, or configuring communication notifications; call the content handler on every success, failure, and timeout path. For communication notifications, enable the capability, add `NSUserActivityTypes`, donate the `INInteraction`, then call `content.updating(from:)`.
 
 ```json
 {
@@ -316,7 +314,7 @@ Implement the delegate to control foreground display and handle user taps. Set t
 
 ```swift
 @MainActor
-final class NotificationDelegate: NSObject, UNUserNotificationCenterDelegate, Sendable {
+final class NotificationDelegate: NSObject, UNUserNotificationCenterDelegate {
     static let shared = NotificationDelegate()
 
     // Called when notification arrives while app is in FOREGROUND
@@ -359,6 +357,8 @@ Route notification taps to the correct screen using a shared `@Observable` route
 ```swift
 @Observable @MainActor
 final class DeepLinkRouter {
+    static let shared = DeepLinkRouter()
+
     var pendingDestination: AppDestination?
 }
 
@@ -377,7 +377,7 @@ func handleNotificationTap(userInfo: [AnyHashable: Any]) async {
 }
 ```
 
-See `references/notification-patterns.md` for the full deep-linking handler with tab switching.
+See [references/notification-patterns.md](references/notification-patterns.md) for the full deep-linking handler with tab switching.
 
 ## Notification Actions and Categories
 
@@ -467,35 +467,32 @@ let category = UNNotificationCategory(
 
 ## Common Mistakes
 
-**DON'T:** Register for remote notifications before requesting authorization.
-**DO:** Call `requestAuthorization` first, then `registerForRemoteNotifications()`.
-
+**DON'T:** Gate APNs token registration on alert authorization when the app needs silent pushes or server token binding.
+**DO:** Request authorization for alerts/sounds/badges, and register with APNs whenever a device token is needed.
 **DON'T:** Convert device token with `String(data: deviceToken, encoding: .utf8)`.
 **DO:** Use hex: `deviceToken.map { String(format: "%02x", $0) }.joined()`.
-
-**DON'T:** Assume notifications always arrive. APNs is best-effort.
-**DO:** Design features that degrade gracefully; use background refresh as fallback.
-
-**DON'T:** Put sensitive data directly in the notification payload.
-**DO:** Use `mutable-content: 1` with a Notification Service Extension.
-
+**DON'T:** Promise every-few-minutes silent refresh or immediate background delivery.
+**DO:** Say background pushes are low priority, throttled, not guaranteed, limited to a few per hour in practice, and require bounded `didReceiveRemoteNotification` work that returns the correct `UIBackgroundFetchResult`.
+**DON'T:** Expect a silent push to run a Notification Service Extension, or leave the extension without calling its content handler.
+**DO:** Use `mutable-content: 1` with an alert payload, supported on-disk attachments that the system validates and stores, `INInteraction` donation plus `content.updating(from:)` for communication notifications, and original or best-attempt content on every success, failure, and timeout path.
 **DON'T:** Forget foreground handling. Without `willPresent`, notifications are silently suppressed.
 **DO:** Implement `willPresent` and return `.banner`, `.sound`, `.badge`.
-
 **DON'T:** Set delegate too late or register from SwiftUI views without AppDelegate adaptor.
 **DO:** Set delegate in `App.init`; use `UIApplicationDelegateAdaptor` for APNs.
-
-**DON'T:** Send device token only once — tokens change. Re-send on every callback.
+**DON'T:** Upload APNs tokens only when they "change" or assume a fixed token length. **DO:** Upload on every `didRegister` callback and treat the token as opaque data converted to hex.
+**DON'T:** Put Live Activity, VoIP, or App Clip-specific notification rules here. **DO:** Route those to `activitykit`, `callkit`, and `app-clips`.
 
 ## Review Checklist
 
-- [ ] Authorization requested before registering; denied case handled (Settings link)
-- [ ] Device token converted to hex string (not `String(data:encoding:)`)
+- [ ] Authorization requested before visible alerts/sounds/badges; denied case handled (Settings link)
+- [ ] APNs registration not incorrectly blocked by alert authorization status
+- [ ] Device token converted to hex, uploaded on every callback, and not treated as a locally cached or fixed-length constant
 - [ ] `UNUserNotificationCenterDelegate` set in `App.init` or `application(_:didFinishLaunching:)`
 - [ ] Foreground (`willPresent`) and tap (`didReceive`) handling implemented
 - [ ] Categories/actions registered at launch if interactive notifications needed
-- [ ] Silent push configured (Background Modes enabled); `UIApplicationDelegateAdaptor` for APNs
+- [ ] Silent push uses `content-available: 1`, no alert/sound/badge, `apns-push-type: background`, `apns-priority: 5`, Background Modes > Remote notifications, throttling caveats, and correct `UIBackgroundFetchResult`
 
 ## References
-- `references/notification-patterns.md` — AppDelegate setup, APNs callbacks, deep-link router, silent push, debugging
-- `references/rich-notifications.md` — Service Extension, Content Extension, attachments, communication notifications
+- [references/notification-patterns.md](references/notification-patterns.md)  -  AppDelegate setup, APNs callbacks, deep-link router, silent push, debugging
+- [references/rich-notifications.md](references/rich-notifications.md)  -  Service Extension, Content Extension, attachments, communication notifications
+- Apple docs: [APNs registration](https://sosumi.ai/documentation/usernotifications/registering-your-app-with-apns), [permission](https://sosumi.ai/documentation/usernotifications/asking-permission-to-use-notifications), [payloads](https://sosumi.ai/documentation/usernotifications/generating-a-remote-notification), [background pushes](https://sosumi.ai/documentation/usernotifications/pushing-background-updates-to-your-app)

package/pipeline/skills/shared/external/push-notifications/evals/evals.json

@@ -0,0 +1,46 @@
+{
+  "skill_name": "push-notifications",
+  "evals": [
+    {
+      "id": 1,
+      "name": "apns-registration-permission-review",
+      "prompt": "Review this SwiftUI push setup: it only calls registerForRemoteNotifications after the user grants alert permission, stores the APNs token in UserDefaults so it can skip uploads on future launches, and treats a simulator failure as a production bug. What should change?",
+      "expected_output": "A correction-focused review that separates APNs token registration from user-visible notification authorization, uploads APNs tokens on every callback without local token caching, and handles simulator push testing correctly.",
+      "files": [],
+      "assertions": [
+        "Explains that requestAuthorization is for alerts, sounds, and badges, while registerForRemoteNotifications is the APNs token registration path.",
+        "Says APNs registration should not be gated on .authorized when the app needs silent pushes or server token binding.",
+        "Requires sending the device token to the provider server on every didRegister callback and not persisting it locally as a source of truth.",
+        "Notes that Simulator can simulate pushes with .apns or simctl but does not provide real APNs device-token registration."
+      ]
+    },
+    {
+      "id": 2,
+      "name": "background-push-payload-review",
+      "prompt": "A backend wants to keep chat fresh with silent pushes every few minutes and apns-priority 10. The app already has visible notification UI elsewhere. Review only the APNs payload, headers, and app-side notification handling.",
+      "expected_output": "A source-grounded review that requires a background payload and headers, rejects high-priority/frequent silent pushes, names the Remote notifications background mode, and keeps long-running background work in the background-processing boundary.",
+      "files": [],
+      "assertions": [
+        "Requires aps content-available: 1 with no alert, sound, or badge for a background notification.",
+        "Requires apns-push-type: background and apns-priority: 5.",
+        "Warns that background notifications are low priority, throttled, not guaranteed, and should not be sent every few minutes.",
+        "Requires Background Modes > Remote notifications and prompt UIBackgroundFetchResult completion.",
+        "Keeps visible-notification UI and long-running BGTaskScheduler work out of the push-notifications scope except as handoffs."
+      ]
+    },
+    {
+      "id": 3,
+      "name": "rich-notification-extension-review",
+      "prompt": "Review a rich-notification plan: use mutable-content on a silent push to decrypt text, store the decryption key in an App Group UserDefaults suite, attach a downloaded file from any URL, use INSendMessageIntent without extra capability setup, and skip explicit fallback handling when work fails or time expires.",
+      "expected_output": "A review that corrects service-extension triggering, secure shared storage, attachment handling, communication notification setup, and fallback behavior for failed or timed-out service-extension work.",
+      "files": [],
+      "assertions": [
+        "Says a Notification Service Extension requires mutable-content: 1 and an alerting remote notification; silent pushes do not trigger it.",
+        "Uses Keychain Sharing for decryption secrets and App Groups only for shared files or UserDefaults.",
+        "Requires attachments to be supported files on disk and notes the system validates and stores them.",
+        "Requires Communication Notifications capability, NSUserActivityTypes intent entries, intent donation, and content.updating(from:).",
+        "Requires calling the content handler on success, failure, and serviceExtensionTimeWillExpire timeout paths with original, best-attempt, or updated content."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/push-notifications/references/notification-patterns.md

@@ -26,7 +26,7 @@ import UserNotifications
 @main
 struct MyApp: App {
     @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
-    @State private var router = DeepLinkRouter()
+    @State private var router = DeepLinkRouter.shared
 
     init() {
         // Set delegate as early as possible so no notifications are missed.
@@ -48,25 +48,16 @@ struct MyApp: App {
         let center = UNUserNotificationCenter.current()
         let settings = await center.notificationSettings()
 
-        switch settings.authorizationStatus {
-        case .notDetermined:
-            let granted = try? await center.requestAuthorization(
+        if settings.authorizationStatus == .notDetermined {
+            _ = try? await center.requestAuthorization(
                 options: [.alert, .sound, .badge]
             )
-            if granted == true {
-                await MainActor.run {
-                    UIApplication.shared.registerForRemoteNotifications()
-                }
-            }
-        case .authorized, .provisional, .ephemeral:
-            await MainActor.run {
-                UIApplication.shared.registerForRemoteNotifications()
-            }
-        case .denied:
-            // User denied -- do not prompt again. Show in-app UI if needed.
-            break
-        @unknown default:
-            break
+        }
+
+        // APNs registration is independent from alert authorization. If the
+        // user denies alerts, remote notifications can still arrive silently.
+        await MainActor.run {
+            UIApplication.shared.registerForRemoteNotifications()
         }
     }
 }
@@ -103,8 +94,9 @@ class AppDelegate: NSObject, UIApplicationDelegate {
         didFailToRegisterForRemoteNotificationsWithError error: Error
     ) {
         #if targetEnvironment(simulator)
-        // Simulator cannot register for remote notifications. This is expected.
-        print("Simulator: APNs registration not available.")
+        // Simulator can simulate pushes with .apns files or simctl, but it
+        // does not register with APNs for a real device token.
+        print("Simulator: APNs device-token registration is unavailable.")
         #else
         print("APNs registration failed: \(error.localizedDescription)")
         // Log to your analytics/crash reporting service
@@ -125,7 +117,7 @@ class AppDelegate: NSObject, UIApplicationDelegate {
 
 ```swift
 @MainActor
-final class NotificationDelegate: NSObject, UNUserNotificationCenterDelegate, Sendable {
+final class NotificationDelegate: NSObject, UNUserNotificationCenterDelegate {
     static let shared = NotificationDelegate()
 
     private override init() { super.init() }
@@ -320,7 +312,7 @@ Silent pushes wake the app in the background to fetch new content. The system gi
 
 ```swift
 @MainActor
-final class BackgroundNotificationHandler: Sendable {
+final class BackgroundNotificationHandler {
     static let shared = BackgroundNotificationHandler()
 
     func handle(userInfo: [AnyHashable: Any]) async -> UIBackgroundFetchResult {
@@ -353,7 +345,9 @@ final class BackgroundNotificationHandler: Sendable {
 }
 ```
 
-**Important:** The Background Modes capability with "Remote notifications" must be enabled in the Xcode project for silent push to work. Without it, `didReceiveRemoteNotification` is never called for silent pushes.
+**Important:** The Background Modes capability with "Remote notifications" must be enabled in the Xcode project for silent push to work. Send background pushes with `aps.content-available = 1`, no alert/sound/badge keys, `apns-push-type: background`, and `apns-priority: 5`. Delivery is low priority, throttled, and not guaranteed; Apple cautions against more than two or three per hour, so do not use silent pushes for every-few-minutes polling or user-visible notification behavior. Keep `didReceiveRemoteNotification` work bounded and return the correct `UIBackgroundFetchResult` within the background execution window.
+
+When reviewing a background-push proposal, explicitly call out these contracts: background pushes are not immediate freshness signals; APNs may throttle or drop them; the app needs Background Modes > Remote notifications; the app delegate handler must finish promptly and return `.newData`, `.noData`, or `.failed` based on the actual result.
 
 ## Notification Scheduling Manager
 
@@ -457,7 +451,7 @@ final class NotificationScheduler {
 
 ## Token Refresh and Update Flow
 
-Device tokens can change between app launches. Treat the token as ephemeral and always send the latest to your server.
+Device tokens can change between app launches. Treat the token as ephemeral and always send the latest to your server from every `didRegisterForRemoteNotificationsWithDeviceToken` callback. Do not use `UserDefaults` as the source of truth for skipping upload, and do not assume a fixed token length.
 
 ```swift
 @MainActor
@@ -468,13 +462,9 @@ final class TokenService {
     private(set) var currentToken: String?
 
     func upload(token: String) async {
-        // Skip if token has not changed since last successful upload
-        if token == currentToken { return }
-
         do {
             try await APIClient.shared.registerDeviceToken(token)
             currentToken = token
-            UserDefaults.standard.set(token, forKey: "lastUploadedAPNsToken")
         } catch {
             print("Failed to upload APNs token: \(error)")
             // Retry on next launch -- didRegisterForRemoteNotifications fires again
@@ -486,7 +476,6 @@ final class TokenService {
         guard let token = currentToken else { return }
         try? await APIClient.shared.unregisterDeviceToken(token)
         currentToken = nil
-        UserDefaults.standard.removeObject(forKey: "lastUploadedAPNsToken")
     }
 }
 ```
@@ -586,14 +575,14 @@ xcrun simctl push booted com.example.myapp payload.apns
 Use the APNs sandbox environment during development. The device token from a development build uses the sandbox; production builds use the production APNs endpoint.
 
 For quick testing without a server, use tools like:
-- **Xcode Console** to send test payloads via the APNs provider API
-- Third-party push testing tools that send directly to APNs with your key/certificate
+- **Apple Push Notification Console** to send development-environment test payloads and inspect delivery logs
+- Command-line APNs requests generated by the console or your own provider scripts
 
 ### Debugging Delivery
 
 1. **Check entitlements:** Ensure the push notification entitlement is in the app's provisioning profile. The `aps-environment` key must be present.
 
-2. **Verify token format:** The token must be a hex string (64 characters for most devices). If your server receives something shorter or with non-hex characters, the conversion is wrong.
+2. **Verify token format:** The token you send to your provider should be the hexadecimal bytes from `deviceToken`. Do not hard-code a token length; APNs says not to make assumptions about device token size.
 
 3. **Check APNs response codes:**
 
@@ -648,7 +637,7 @@ struct ContentView: View {
 }
 ```
 
-`setBadgeCount(_:)` (iOS 16+) is the modern replacement for setting `UIApplication.shared.applicationIconBadgeNumber`, which is deprecated.
+`setBadgeCount(_:)` (iOS 16+) is the modern `UserNotifications` API for updating the badge count. Use availability checks if you still support older deployment targets.
 
 ## Provisional to Full Authorization Upgrade