@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/ios-networking/SKILL.md

@@ -6,7 +6,7 @@ description: "Build, review, or improve networking code in iOS/macOS apps using
 # iOS Networking
 
 Modern networking patterns for iOS 26+ using URLSession with async/await and
-structured concurrency. All examples target Swift 6.2. No third-party
+structured concurrency. All examples target Swift 6.3. No third-party
 dependencies required -- URLSession covers the vast majority of networking
 needs.
 
@@ -18,15 +18,17 @@ needs.
 - [Pagination](#pagination)
 - [Network Reachability](#network-reachability)
 - [Configuring URLSession](#configuring-urlsession)
+- [App Transport Security (ATS)](#app-transport-security-ats)
 - [Common Mistakes](#common-mistakes)
 - [Review Checklist](#review-checklist)
 - [References](#references)
 
 ## Core URLSession async/await
 
-URLSession gained native async/await overloads in iOS 15. These are the
-only networking APIs to use in new code. Never use completion-handler
-variants in new projects.
+URLSession gained native async/await overloads in iOS 15. Prefer these for
+foreground data, upload, download, and streaming work. Background URLSession
+transfers are the main exception: they still use task/delegate APIs so the
+system can deliver events after suspension or relaunch.
 
 ### Data Requests
 
@@ -90,11 +92,20 @@ loading the entire payload into memory.
 // Download to a temporary file
 let (localURL, response) = try await URLSession.shared.download(for: request)
 
-// Move from temp location before the method returns
+// Move or copy the returned temporary file promptly.
 let destination = documentsDirectory.appendingPathComponent("file.zip")
 try FileManager.default.moveItem(at: localURL, to: destination)
 ```
 
+For delegate-based `URLSessionDownloadDelegate`, move or open the temporary
+file before `urlSession(_:downloadTask:didFinishDownloadingTo:)` returns.
+
+Background sessions are delegate-driven transfer queues. Use task creation
+APIs such as `downloadTask(with:)` and file-backed `uploadTask(with:fromFile:)`,
+then handle `URLSessionDelegate` / task delegate callbacks. Do not use async
+convenience APIs such as `data(for:)`, `download(for:)`, or `upload(for:)` as
+the durable background-session pattern.
+
 ```swift
 // Upload data
 let (data, response) = try await URLSession.shared.upload(for: request, from: bodyData)
@@ -169,13 +180,19 @@ The client accepts a `baseURL`, optional custom `URLSession`, `JSONDecoder`,
 and an array of `RequestMiddleware` interceptors. Each method builds a
 `URLRequest` from the endpoint, applies middleware, executes the request,
 validates the status code, and decodes the result. See
-`references/urlsession-patterns.md` for the complete `APIClient` implementation
+[references/urlsession-patterns.md](references/urlsession-patterns.md) for the complete `APIClient` implementation
 with convenience methods, request builder, and test setup.
 
+Production clients should receive an injected, configured `URLSession` instead
+of calling `URLSession.shared` internally. Configure `URLSessionConfiguration`
+with request/resource timeouts, cache policy or `URLCache`,
+`waitsForConnectivity`, data-cost policy, and delegates when authentication
+challenges, redirects, metrics, pinning, or background transfer handling matter.
+
 ### Lightweight Closure-Based Client
 
 For apps using the MV pattern, use closure-based clients for testability
-and SwiftUI preview support. See `references/lightweight-clients.md` for
+and SwiftUI preview support. See [references/lightweight-clients.md](references/lightweight-clients.md) for
 the full pattern (struct of async closures, injected via init).
 
 ### Request Middleware / Interceptors
@@ -261,7 +278,7 @@ enum NetworkError: Error, Sendable {
 | `.cancelled` | Task was cancelled | No action needed; do not show error |
 | `.cannotFindHost` | DNS failure | Check URL, show error |
 | `.secureConnectionFailed` | TLS handshake failed | Check cert pinning, ATS config |
-| `.userAuthenticationRequired` | 401 from proxy | Trigger auth flow |
+| `.userAuthenticationRequired` | Authentication required to access a resource | Trigger auth flow |
 
 ### Decoding Server Error Bodies
 
@@ -318,23 +335,23 @@ func withRetry<T: Sendable>(
 
 Build cursor-based or offset-based pagination with `AsyncSequence`.
 Always check `Task.isCancelled` between pages. See
-`references/urlsession-patterns.md` for complete `CursorPaginator` and
+[references/urlsession-patterns.md](references/urlsession-patterns.md) for complete `CursorPaginator` and
 offset-based implementations.
 
 ## Network Reachability
 
-Use `NWPathMonitor` from the Network framework — not third-party
-Reachability libraries. Wrap in `AsyncStream` for structured concurrency.
+Use `NWPathMonitor` from the Network framework -- not third-party
+Reachability libraries. On current OS targets it conforms to `AsyncSequence`;
+wrap `pathUpdateHandler` only for compatibility or custom projections.
 
 ```swift
 import Network
 
-func networkStatusStream() -> AsyncStream<NWPath.Status> {
-    AsyncStream { continuation in
-        let monitor = NWPathMonitor()
-        monitor.pathUpdateHandler = { continuation.yield($0.status) }
-        continuation.onTermination = { _ in monitor.cancel() }
-        monitor.start(queue: DispatchQueue(label: "NetworkMonitor"))
+func observeNetworkStatus() async {
+    let monitor = NWPathMonitor()
+
+    for await path in monitor {
+        handle(path.status)
     }
 }
 ```
@@ -342,6 +359,11 @@ func networkStatusStream() -> AsyncStream<NWPath.Status> {
 Check `path.isExpensive` (cellular) and `path.isConstrained` (Low Data
 Mode) to adapt behavior (reduce image quality, skip prefetching).
 
+Use Network.framework for low-level TCP, UDP, listeners, Bonjour, path
+monitoring, or WebSocket protocol work -- not ordinary REST APIs. For iOS 26
+`NetworkConnection<QUIC>`, `openStream(...)` and `inboundStreams(...)` are
+async throwing APIs; see [references/network-framework.md#quic-multiplexed-streams](references/network-framework.md#quic-multiplexed-streams).
+
 ## Configuring URLSession
 
 Create a configured session for production code. `URLSession.shared` is
@@ -366,6 +388,25 @@ a network path instead of failing immediately when offline. Combine with
 `urlSession(_:taskIsWaitingForConnectivity:)` delegate callback for UI
 feedback.
 
+## App Transport Security (ATS)
+
+ATS enforces HTTPS for all connections by default. Do not disable it.
+ATS is URL Loading System policy, so it covers `URLSession` rather than making
+lower-level `Network.framework` connections secure automatically. When using
+Network.framework, configure secure TLS parameters and trust handling correctly
+for that protocol stack.
+
+Use domain-specific ATS exceptions only as a last resort.
+
+**Rules:**
+- Never set `NSAllowsArbitraryLoads` to `true` in production unless there is no narrower option.
+- ATS exceptions require justification and may trigger additional App Store review.
+- Use exception domains only for third-party servers you cannot upgrade to HTTPS.
+- `NSAllowsLocalNetworking` is acceptable for local device communication (Bonjour, IoT).
+- Prefer ATS `NSPinnedDomains` for declarative pinning when possible. Raw bytes
+  from `SecKeyCopyExternalRepresentation` are not sufficient for SPKI pinning;
+  correct SPKI pinning hashes Subject Public Key Info and belongs in `swift-security`.
+
 ## Common Mistakes
 
 **DON'T:** Use `URLSession.shared` with custom configuration needs.
@@ -410,7 +451,7 @@ a 500 with an error body require different handling.
 
 ## Review Checklist
 
-- [ ] All network calls use async/await (not completion handlers)
+- [ ] Foreground transfers use async/await; background sessions use delegate/task APIs
 - [ ] Error handling covers URLError cases (.notConnectedToInternet, .timedOut, .cancelled)
 - [ ] Requests are cancellable (respect Task cancellation via `.task` modifier or stored Task references)
 - [ ] Authentication tokens injected via middleware, not hardcoded
@@ -418,24 +459,30 @@ a 500 with an error body require different handling.
 - [ ] Large downloads use `download(for:)` not `data(for:)`
 - [ ] Network calls happen off `@MainActor` (only UI updates on main)
 - [ ] URLSession configured with appropriate timeouts and caching
+- [ ] Production clients inject configured sessions instead of using `URLSession.shared`
+- [ ] Background transfers use task/delegate APIs, not async convenience APIs
 - [ ] Retry logic excludes cancellation and 4xx client errors
 - [ ] Pagination checks `Task.isCancelled` between pages
 - [ ] Sensitive tokens stored in Keychain (not UserDefaults or plain files)
 - [ ] No force-unwrapped URLs from dynamic input
 - [ ] Server error responses decoded and surfaced to users
+- [ ] Network.framework code configures TLS/trust explicitly and keeps deep pinning work in `swift-security`
+- [ ] `NetworkConnection<QUIC>` stream APIs are treated as async throwing
 - [ ] Ensure network response model types conform to Sendable; use @MainActor for UI-updating completion paths
 
 ## References
 
-- See `references/urlsession-patterns.md` for complete API client
+- See [references/urlsession-patterns.md](references/urlsession-patterns.md) for complete API client
   implementation, multipart uploads, download progress, URLProtocol
   mocking, retry/backoff, certificate pinning, request logging, and
   pagination implementations.
-- See `references/background-websocket.md` for background URLSession
+- See [references/background-websocket.md](references/background-websocket.md) for background URLSession
   configuration, background downloads/uploads, WebSocket patterns with
   structured concurrency, and reconnection strategies.
-- See `references/lightweight-clients.md` for the lightweight closure-based
+- See [references/lightweight-clients.md](references/lightweight-clients.md) for the lightweight closure-based
   client pattern (struct of async closures, injected via init for testability
   and preview support).
-- See `references/network-framework.md` for Network.framework (NWConnection,
+- See [references/network-framework.md](references/network-framework.md) for Network.framework (NWConnection,
   NWListener, NWBrowser, NWPathMonitor) and low-level TCP/UDP/WebSocket patterns.
+- See [references/file-storage-patterns.md](references/file-storage-patterns.md) for file system directory
+  selection, FileProtectionType, backup exclusion, and storage pressure handling.

package/pipeline/skills/shared/external/ios-networking/evals/evals.json

@@ -0,0 +1,50 @@
+{
+  "skill_name": "ios-networking",
+  "evals": [
+    {
+      "id": 1,
+      "name": "urlsession-api-client-review",
+      "prompt": "Review this Swift API client plan: every request uses URLSession.shared.data(for:) and decodes without checking HTTP status, retries every error including cancellation and all 4xx responses, stores bearer tokens in UserDefaults, and tests by mocking the APIClient protocol only. Give a concise correction plan with Swift where useful.",
+      "expected_output": "A URLSession API client review that fixes response validation, retry policy, cancellation, token handling boundaries, and test strategy.",
+      "files": [],
+      "assertions": [
+        "Requires validating HTTPURLResponse status codes before decoding and treating 4xx/5xx separately from transport failures.",
+        "Recommends a configured URLSession for production rather than URLSession.shared when timeouts, caching, delegates, or connectivity behavior matter.",
+        "Excludes cancellation and most 4xx client errors from retry logic while allowing appropriate retries such as 429 or 5xx.",
+        "Uses request middleware or a centralized request builder for auth headers rather than hardcoded tokens.",
+        "States that sensitive tokens belong in Keychain and keeps deep credential-storage implementation in the security boundary.",
+        "Mentions URLProtocol or transport-level testing when request/response behavior needs verification."
+      ]
+    },
+    {
+      "id": 2,
+      "name": "background-transfer-websocket-boundary",
+      "prompt": "A team wants one networking manager that uses a background URLSession for JSON polling, large file downloads, file uploads from memory, and a chat WebSocket that must keep receiving after the app is force-quit. Review the plan and say what should change.",
+      "expected_output": "A review that separates background URLSession transfer support from foreground WebSocket behavior and corrects force-quit/background limitations.",
+      "files": [],
+      "assertions": [
+        "States that background URLSession is for HTTP/HTTPS upload and download transfers, not WebSocket durability.",
+        "States that background uploads must be file-backed rather than Data or stream uploads after app exit.",
+        "Says background sessions require delegates and task APIs rather than async convenience APIs as the durable transfer pattern.",
+        "Explains that user force-quit cancels background transfers and prevents automatic relaunch until the user opens the app.",
+        "Requires moving or opening a downloaded temporary file before didFinishDownloadingTo returns.",
+        "Keeps WebSocket guidance to foreground/default-session realtime networking with reconnect when the app is active again."
+      ]
+    },
+    {
+      "id": 3,
+      "name": "network-framework-ats-security-boundary",
+      "prompt": "Review this iOS 26 networking design: use Network.framework for all REST calls to avoid ATS, disable NSAllowsArbitraryLoads globally, implement certificate pinning by hashing SecKeyCopyExternalRepresentation bytes, wrap NWPathMonitor in a custom AsyncStream helper, and sketch NetworkConnection<QUIC> stream work as synchronous callbacks. What should change, and which parts belong to neighboring skills?",
+      "expected_output": "A boundary-aware review that routes REST to URLSession/ATS, low-level networking to Network.framework, certificate trust details to swift-security, uses modern NWPathMonitor guidance, and treats iOS 26 NetworkConnection QUIC stream APIs correctly.",
+      "files": [],
+      "assertions": [
+        "Recommends URLSession for ordinary REST/HTTP API calls and Network.framework only for lower-level TCP, UDP, listeners, Bonjour, path monitoring, WebSocket protocol work, or iOS 26 NetworkConnection needs.",
+        "States that ATS applies to URL Loading/URLSession and that Network.framework callers must take responsibility for secure configuration.",
+        "Rejects global NSAllowsArbitraryLoads as a default and recommends fixing servers or using the narrowest justified ATS exception.",
+        "Corrects raw SecKeyCopyExternalRepresentation hashing as not sufficient for SPKI pinning and routes deep certificate-trust implementation to swift-security.",
+        "Uses NWPathMonitor as AsyncSequence on current OS targets or explicitly labels a wrapper as fallback/custom projection.",
+        "For NetworkConnection QUIC streams, treats openStream and inboundStreams as async throwing APIs."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/ios-networking/references/background-websocket.md

@@ -21,17 +21,21 @@ URLSessionWebSocketTask with structured concurrency.
 
 ## Background URLSession Configuration
 
-Background sessions allow transfers to continue when the app is
-suspended or terminated. The system manages the transfer in a separate
-process and wakes the app on completion.
+Background sessions allow HTTP/HTTPS upload and download transfers to continue
+when the app is suspended or terminated by the system. The system manages the
+transfer in a separate process and wakes the app on completion.
 
 ### Why Background Sessions
 
-- Downloads/uploads survive app suspension, termination, and device restarts.
+- Downloads/uploads survive app suspension, system termination, and device restarts.
 - The system handles retries for network failures automatically.
 - Required for any transfer the user expects to complete even if they
   switch away from the app (e.g., file sync, media downloads).
 
+If the user force-quits the app from the multitasking screen, iOS cancels the
+background transfers and does not relaunch the app until the user opens it
+again.
+
 ### Configuration
 
 ```swift
@@ -113,8 +117,8 @@ extension BackgroundDownloadManager: URLSessionDownloadDelegate {
         downloadTask: URLSessionDownloadTask,
         didFinishDownloadingTo location: URL
     ) {
-        // CRITICAL: Move the file before this method returns.
-        // The temporary file is deleted immediately after.
+        // CRITICAL: Move or open the file before this method returns.
+        // The temporary file is only available until the delegate returns.
         let destinationDir = FileManager.default.urls(
             for: .documentDirectory,
             in: .userDomainMask
@@ -177,8 +181,9 @@ extension BackgroundDownloadManager: URLSessionDownloadDelegate {
 ## Handling Background Session Events
 
 When the system completes a background transfer and the app is not
-running, it relaunches the app and calls the `AppDelegate` method. You
-must call the system's completion handler after processing all events.
+running, it relaunches the app and calls the `AppDelegate` method. If you use
+the completion-handler overload, call the system's completion handler after
+processing all events.
 
 ### UIKit App Delegate
 
@@ -232,9 +237,10 @@ struct MyApp: App {
 }
 ```
 
-**Important:** The completion handler must be called exactly once and
-on the main thread. Failing to call it causes the system to take a
-snapshot of the app in the wrong state and may waste background runtime.
+**Important:** For the handler-based `UIApplicationDelegate` overload, the
+completion handler must be called exactly once and on the main thread. Failing
+to call it causes the system to take a snapshot of the app in the wrong state
+and may waste background runtime.
 
 ---
 
@@ -291,7 +297,10 @@ extension BackgroundDownloadManager {
 ## URLSessionWebSocketTask
 
 `URLSessionWebSocketTask` provides native WebSocket support without
-third-party libraries. Available since iOS 13.
+third-party libraries. Available since iOS 13. WebSockets use `ws:` or `wss:`
+URLs and are foreground/default-session realtime networking; background
+URLSession configuration does not make a WebSocket connection durable after
+suspension.
 
 ### Basic Connection
 
@@ -721,15 +730,18 @@ on background sessions. Use `downloadTask(with:)` and the delegate.
 ### Only download and upload tasks are supported
 Data tasks (`dataTask`) are not supported in background sessions. Convert
 data requests to download tasks if needed for background execution.
+WebSocket tasks are not background transfer tasks; reconnect them when the app
+is active again.
 
 ### The app may be terminated and relaunched
 Store any state you need (task identifiers, file destinations) to disk.
 Do not rely on in-memory state surviving a background relaunch.
+User force-quit is different from system termination: iOS cancels outstanding
+background transfers and will not relaunch the app automatically.
 
-### File must be moved in didFinishDownloadingTo
-The temporary file at `location` is deleted as soon as the delegate
-method returns. Always move or copy the file synchronously within the
-callback.
+### File must be moved or opened in didFinishDownloadingTo
+The temporary file at `location` is available until the delegate method
+returns. Move it to preserve it, or open it for reading before returning.
 
 ### Call the system completion handler exactly once
 Store the completion handler from