@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/background-processing/SKILL.md

@@ -32,7 +32,7 @@ Every task identifier **must** be declared in `Info.plist` under
 <array>
     <string>com.example.app.refresh</string>
     <string>com.example.app.db-cleanup</string>
-    <string>com.example.app.export</string>
+    <string>com.example.app.export.*</string>
 </array>
 ```
 
@@ -46,14 +46,12 @@ Also enable the required `UIBackgroundModes`:
 </array>
 ```
 
-In Xcode: target > Signing & Capabilities > Background Modes > enable
-"Background fetch" and "Background processing".
+In Xcode: target > Signing & Capabilities > Background Modes > enable "Background fetch" and "Background processing".
 
 ## BGTaskScheduler Registration
 
 Register handlers **before** app launch completes. In UIKit, register in
-`application(_:didFinishLaunchingWithOptions:)`. In SwiftUI, register in the
-`App` initializer.
+`application(_:didFinishLaunchingWithOptions:)`; in SwiftUI, register in `App.init()`.
 
 ### UIKit Registration
 
@@ -68,7 +66,7 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
     ) -> Bool {
         BGTaskScheduler.shared.register(
             forTaskWithIdentifier: "com.example.app.refresh",
-            using: nil  // nil = main queue
+            using: nil  // nil = default background queue
         ) { task in
             self.handleAppRefresh(task: task as! BGAppRefreshTask)
         }
@@ -113,7 +111,8 @@ struct MyApp: App {
 ## BGAppRefreshTask Patterns
 
 Short-lived tasks (~30 seconds) for fetching small data updates. The system
-decides when to launch based on usage patterns.
+decides when to launch based on usage patterns. Review notes should say
+`earliestBeginDate` is a lower-bound hint and the system may run the task later.
 
 ```swift
 func scheduleAppRefresh() {
@@ -121,7 +120,7 @@ func scheduleAppRefresh() {
         identifier: "com.example.app.refresh"
     )
     request.earliestBeginDate = Date(timeIntervalSinceNow: 15 * 60)
-
+    // earliestBeginDate is a lower-bound hint; the system may delay launch.
     do {
         try BGTaskScheduler.shared.submit(request)
     } catch {
@@ -154,7 +153,8 @@ func handleAppRefresh(task: BGAppRefreshTask) {
 ## BGProcessingTask Patterns
 
 Long-running tasks (minutes) for maintenance, data processing, or cleanup.
-Runs only when device is idle and (optionally) charging.
+Runs only when device is idle and (optionally) charging. Review notes should say
+`earliestBeginDate` is a lower-bound hint and the system may run the task later.
 
 ```swift
 func scheduleProcessingTask() {
@@ -164,7 +164,7 @@ func scheduleProcessingTask() {
     request.requiresNetworkConnectivity = false
     request.requiresExternalPower = true
     request.earliestBeginDate = Date(timeIntervalSinceNow: 60 * 60)
-
+    // earliestBeginDate is a lower-bound hint; the system may delay launch.
     do {
         try BGTaskScheduler.shared.submit(request)
     } catch {
@@ -202,32 +202,26 @@ background. The system displays progress via a Live Activity. Conforms to
 
 Unlike `BGAppRefreshTask` and `BGProcessingTask`, this task starts immediately
 from the foreground. The system can terminate it under resource pressure,
-prioritizing tasks that report minimal progress first.
+prioritizing tasks that report minimal progress first. Set `expirationHandler` for user or system cancellation, cancel in-flight work, and clean up partial output before reporting completion.
 
 ```swift
 import BackgroundTasks
 
 func startExport() {
+    // Register the task handler at app launch, not here.
+    // BGTaskScheduler requires registration before app launch completes.
+    let jobID = UUID().uuidString
     let request = BGContinuedProcessingTaskRequest(
-        identifier: "com.example.app.export",
+        identifier: "com.example.app.export.\(jobID)",
         title: "Exporting Photos",
         subtitle: "Processing 247 items"
     )
+    // Use a permitted base wildcard identifier: com.example.app.export.*
+    // earliestBeginDate is ignored for continued processing requests.
     // .queue: begin as soon as possible if can't run immediately
     // .fail: fail submission if can't run immediately
     request.strategy = .queue
 
-    BGTaskScheduler.shared.register(
-        forTaskWithIdentifier: "com.example.app.export",
-        using: nil
-    ) { task in
-        let continuedTask = task as! BGContinuedProcessingTask
-
-        Task {
-            await self.performExport(task: continuedTask)
-        }
-    }
-
     do {
         try BGTaskScheduler.shared.submit(request)
     } catch {
@@ -257,10 +251,10 @@ func performExport(task: BGContinuedProcessingTask) async {
 }
 ```
 
-Check whether the system supports the resources your task needs:
+For GPU work, check support and enable Background GPU Access (`com.apple.developer.background-tasks.continued-processing.gpu`):
 
 ```swift
-let supported = BGTaskScheduler.shared.supportedResources
+let supported = BGTaskScheduler.supportedResources
 if supported.contains(.gpu) {
     request.requiredResources = .gpu
 }
@@ -313,7 +307,7 @@ class DownloadManager: NSObject, URLSessionDownloadDelegate {
 }
 ```
 
-Handle app relaunch — store and invoke the system completion handler:
+Handle app relaunch  -  store and invoke the system completion handler:
 
 ```swift
 // In AppDelegate:
@@ -325,7 +319,7 @@ func application(
     backgroundSessionCompletionHandler = completionHandler
 }
 
-// In URLSessionDelegate — call stored handler when events finish:
+// In URLSessionDelegate  -  call stored handler when events finish:
 func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) {
     Task { @MainActor in
         self.backgroundSessionCompletionHandler?()
@@ -343,6 +337,11 @@ Silent push notifications wake your app briefly to fetch new content. Set
 { "aps": { "content-available": 1 }, "custom-data": "new-messages" }
 ```
 
+Send the APNs request with `apns-push-type: background` and
+`apns-priority: 5`. Background push delivery is low priority and not
+guaranteed; keep sends infrequent, generally no more than two or three per
+hour.
+
 Handle in AppDelegate:
 
 ```swift
@@ -475,11 +474,12 @@ func handleRefresh(task: BGAppRefreshTask) {
 - [ ] `setTaskCompleted(success:)` called on every code path
 - [ ] `expirationHandler` set and cancels in-flight work
 - [ ] Next task scheduled inside the handler (re-schedule pattern)
-- [ ] `earliestBeginDate` uses reasonable intervals (15+ min for refresh)
+- [ ] `earliestBeginDate` uses reasonable intervals and is treated as a hint
 - [ ] Background URLSession uses delegate (not async/closures)
 - [ ] Background URLSession file moved in `didFinishDownloadingTo` before return
 - [ ] `handleEventsForBackgroundURLSession` stores and calls completion handler
 - [ ] Background push payload includes `content-available: 1`
+- [ ] Background push APNs request uses `apns-push-type: background` and `apns-priority: 5`
 - [ ] `fetchCompletionHandler` called promptly with correct result
 - [ ] BGContinuedProcessingTask reports progress via `ProgressReporting`
 - [ ] Work is incremental and cancellation-safe (`Task.checkCancellation()`)
@@ -487,7 +487,7 @@ func handleRefresh(task: BGAppRefreshTask) {
 
 ## References
 
-- See `references/background-task-patterns.md` for extended patterns, background
+- See [references/background-task-patterns.md](references/background-task-patterns.md) for extended patterns, background
   URLSession edge cases, debugging with simulated launches, and background push
   best practices.
 - [BGTaskScheduler](https://sosumi.ai/documentation/backgroundtasks/bgtaskscheduler)

package/pipeline/skills/shared/external/background-processing/evals/evals.json

@@ -0,0 +1,44 @@
+{
+  "skill_name": "background-processing",
+  "evals": [
+    {
+      "id": 1,
+      "name": "bg-task-registration-review",
+      "prompt": "Review this iOS background task setup for a SwiftUI app. It registers a BGAppRefreshTask from a view's .task modifier, submits a BGProcessingTask without adding BGTaskSchedulerPermittedIdentifiers, and does not set an expirationHandler. Give a concise fix plan and corrected Swift/Info.plist snippets.",
+      "expected_output": "Identifies launch-time registration, Info.plist permitted identifiers, required UIBackgroundModes, expiration handling, setTaskCompleted on all paths, and rescheduling patterns.",
+      "files": [],
+      "assertions": [
+        "Says BGTaskScheduler handlers must be registered before app launch completes, not from a view task.",
+        "Names BGTaskSchedulerPermittedIdentifiers and the fetch/processing UIBackgroundModes requirements.",
+        "Requires expirationHandler cancellation and setTaskCompleted(success:) on every path.",
+        "Shows or describes scheduling the next request from inside the task handler."
+      ]
+    },
+    {
+      "id": 2,
+      "name": "continued-processing-ios26",
+      "prompt": "I need an iOS 26 photo export that starts from a user tap and keeps running if the user backgrounds the app. It may use GPU acceleration. What BackgroundTasks API should I use, and what are the identifier, progress, cancellation, and entitlement gotchas?",
+      "expected_output": "Recommends BGContinuedProcessingTaskRequest/BGContinuedProcessingTask and covers foreground user action, wildcard permitted identifier base with unique job identifiers, ProgressReporting, updateTitle/subtitle, expiration cancellation, supportedResources, and the Background GPU Access entitlement.",
+      "files": [],
+      "assertions": [
+        "Recommends BGContinuedProcessingTaskRequest and BGContinuedProcessingTask for iOS 26 foreground-started work.",
+        "Explains that submitted identifiers should be unique per job under a bundle-prefixed wildcard permitted identifier.",
+        "Mentions ProgressReporting or task.progress and cancellation/expiration handling.",
+        "Mentions checking BGTaskScheduler.supportedResources before requesting GPU and requiring the Background GPU Access entitlement."
+      ]
+    },
+    {
+      "id": 3,
+      "name": "background-push-boundary",
+      "prompt": "Our server wants to wake the app with silent pushes every few minutes to keep chat data fresh, and one engineer suggested using apns-priority 10 so they arrive instantly. Review the plan and say what should change. Do not redesign our notification UI.",
+      "expected_output": "Keeps scope to background push refresh behavior, rejects frequent silent pushes and priority 10, requires content-available, remote-notification mode, apns-push-type background, apns-priority 5, and prompt fetch completion.",
+      "files": [],
+      "assertions": [
+        "Requires content-available: 1 and the Remote notifications background mode.",
+        "Requires APNs headers apns-push-type: background and apns-priority: 5.",
+        "Warns that background pushes are low priority, throttled, not guaranteed, and should not be sent every few minutes.",
+        "Stays focused on background refresh behavior rather than redesigning visible notification UI."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/background-processing/references/background-task-patterns.md

@@ -1,15 +1,27 @@
-# Background Task Patterns — Extended Reference
+# Background Task Patterns  -  Extended Reference
 
 Overflow reference for the background-processing skill. Contains debugging tips,
 advanced background URLSession patterns, background push best practices, and
 SwiftUI integration patterns.
 
+## Contents
+
+- [Debugging Background Tasks](#debugging-background-tasks)
+- [Advanced BGProcessingTask Patterns](#advanced-bgprocessingtask-patterns)
+- [Background URLSession  -  Extended Patterns](#background-urlsession--extended-patterns)
+- [Background Push  -  Extended Patterns](#background-push--extended-patterns)
+- [SwiftUI BackgroundTask Modifier](#swiftui-backgroundtask-modifier)
+- [BGContinuedProcessingTask  -  Extended Patterns](#bgcontinuedprocessingtask--extended-patterns)
+
 ## Debugging Background Tasks
 
 ### Simulating Task Launches in Xcode
 
 Use the LLDB console to trigger tasks instantly during development. The app must
-be running in the debugger with a breakpoint hit or paused.
+be running on a device in the debugger with a breakpoint hit or paused.
+
+These are Apple-documented private functions for development only. Do not
+include references to them in App Store-submitted code.
 
 ```swift
 e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.example.app.refresh"]
@@ -45,10 +57,13 @@ BGTaskScheduler.shared.getPendingTaskRequests { requests in
 |---|---|---|
 | Task never fires | Identifier not in Info.plist | Add to `BGTaskSchedulerPermittedIdentifiers` |
 | Task never fires | Background modes not enabled | Enable `fetch` and/or `processing` in capabilities |
-| Task never fires on device | Device in Low Power Mode | Low Power Mode suppresses background tasks |
+| Task never fires on device | Background App Refresh disabled or Low Power Mode active | Check `UIApplication.shared.backgroundRefreshStatus`; Low Power Mode reduces background runtime |
 | `.notPermitted` error | Identifier mismatch | Verify exact string match between code and plist |
 | `.unavailable` error | Running in extension | BGTaskScheduler not available in app extensions |
-| `.tooManyPendingTaskRequests` | Over 10 pending refresh or 1 processing per identifier | Cancel old requests before submitting new ones |
+| `.tooManyPendingTaskRequests` | More than 1 refresh task or 10 processing tasks scheduled in total | Cancel old requests before submitting new ones |
+
+Submitting an unexecuted task request with the same identifier replaces the
+previous request.
 
 ## Advanced BGProcessingTask Patterns
 
@@ -117,7 +132,7 @@ func handleMigration(task: BGProcessingTask) {
 }
 ```
 
-## Background URLSession — Extended Patterns
+## Background URLSession  -  Extended Patterns
 
 ### Configuration Best Practices
 
@@ -238,7 +253,7 @@ func urlSession(
 }
 ```
 
-## Background Push — Extended Patterns
+## Background Push  -  Extended Patterns
 
 ### Push Payload Requirements
 
@@ -257,17 +272,25 @@ The `content-available: 1` flag is required. You can include custom data:
 **Do not** include `alert`, `badge`, or `sound` if you only want a silent push.
 Including visual notification keys changes the push behavior.
 
+Send background notification requests with APNs headers:
+
+```http
+apns-push-type: background
+apns-priority: 5
+```
+
 ### Rate Limiting
 
 Apple throttles background push delivery. Guidelines:
 
-- System limits to a few pushes per hour per app
-- If the user force-quits the app, background pushes stop entirely until next
-  manual launch
-- High-priority pushes (`apns-priority: 10`) are delivered immediately but must
-  only be used when the notification triggers user-visible content
-- Low-priority pushes (`apns-priority: 5`) are batched and delivered
-  opportunistically
+- Delivery is low priority and not guaranteed.
+- Do not send more than two or three background notifications per hour.
+- The system may hold only the newest background notification and discard older
+  held notifications.
+- If the user force-quits the app, background pushes stop until the next manual
+  launch.
+- Use `apns-priority: 5`; high-priority pushes are for user-visible
+  notifications, not silent refresh.
 
 ### Handling Push with Async Work
 
@@ -329,18 +352,20 @@ struct MyApp: App {
 }
 ```
 
-This is a convenience wrapper. Under the hood it registers with
-`BGTaskScheduler`. You still need the Info.plist identifiers and background
-modes.
+This is a SwiftUI handler for matching background tasks. You still need the
+Info.plist identifiers, background modes, scheduling, and cancellation-safe work
+patterns.
 
-## BGContinuedProcessingTask — Extended Patterns
+## BGContinuedProcessingTask  -  Extended Patterns
 
 ### Checking Supported Resources
 
-Before requesting GPU or other resources, verify the device supports them:
+Before requesting GPU or other resources, verify the device supports them and
+enable Background GPU Access
+(`com.apple.developer.background-tasks.continued-processing.gpu`) for GPU work:
 
 ```swift
-let supported = BGTaskScheduler.shared.supportedResources
+let supported = BGTaskScheduler.supportedResources
 if supported.contains(.gpu) {
     request.requiredResources = .gpu
 }