@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/external/swift-concurrency-pro/references/interop.md

@@ -0,0 +1,129 @@
+# Interop and migration
+
+Approved patterns for migrating legacy concurrency mechanisms to Swift concurrency.
+
+## Completion handlers → `async`/`await`
+
+Unless the user requested you to modernize their code, it’s better to leave existing completion handler code alone because it’s understood, tested, and mature.
+
+Instead, provide modern Swift concurrency wrappers for it using `withCheckedThrowingContinuation`. Resume exactly once on every path. See `bridging.md` for detailed rules.
+
+```swift
+func loadUser(id: String) async throws -> User {
+    try await withCheckedThrowingContinuation { continuation in
+        api.fetchUser(id: id) { result in
+            continuation.resume(with: result)
+        }
+    }
+}
+```
+
+If the SDK already provides an async overload, use it directly instead of wrapping.
+
+
+## Delegates → `AsyncStream`
+
+Delegates that deliver multiple values over time map well to `AsyncStream`. Use `makeStream(of:)` and yield from delegate callbacks. See `bridging.md` for the full pattern.
+
+Single-shot delegates (one callback, then done) can use `withCheckedContinuation` instead.
+
+
+## `DispatchQueue.main.async` → `@MainActor`
+
+```swift
+// Before
+DispatchQueue.main.async {
+    self.label.text = "Done"
+}
+
+// After – make the enclosing function or type @MainActor
+@MainActor
+func updateLabel() {
+    label.text = "Done"
+}
+```
+
+If called from a non-isolated async context, the `await` at the call site replaces the dispatch:
+
+```swift
+await updateLabel()
+```
+
+
+## `DispatchQueue.global().async` → `@concurrent` or Task Group
+
+For one-off background work:
+
+```swift
+// Before
+DispatchQueue.global().async {
+    let result = heavyComputation()
+    DispatchQueue.main.async { self.result = result }
+}
+
+// After (Swift 6.2)
+@concurrent
+func heavyComputation() async -> ComputationResult { ... }
+
+// At call site:
+self.result = await heavyComputation()
+```
+
+A plain `async` helper does not offload CPU work by itself. If the goal is to leave the caller's executor, make that explicit.
+
+For parallel batch work, use `withTaskGroup`. See `structured.md`.
+
+
+## Serial `DispatchQueue` → `actor`
+
+A serial dispatch queue protecting mutable state maps directly to an `actor`:
+
+```swift
+// Before
+class TokenStore {
+    private let queue = DispatchQueue(label: "token-store")
+    private var token: String?
+
+    func setToken(_ t: String) {
+        queue.sync { token = t }
+    }
+
+    func getToken() -> String? {
+        queue.sync { token }
+    }
+}
+
+// After
+actor TokenStore {
+    private var token: String?
+
+    func setToken(_ t: String) { token = t }
+    func getToken() -> String? { token }
+}
+```
+
+
+## Locks and checked sendability
+
+If the API must stay synchronous, prefer a lock over introducing actor isolation just to serialize access.
+
+- `Mutex` gives the best compile time and can preserve checked `Sendable` on the owning type.
+- Traditional locks still work, but the owning reference type often ends up with `@unchecked Sendable`.
+
+*Choose an actor only when the API itself should become actor-isolated.*
+
+
+## Moving from Combine to `AsyncSequence`
+
+| Combine | Swift Concurrency |
+|---------|-------------------|
+| `publisher.sink { }` | `for await value in stream { }` |
+| `publisher.map { }` | `stream.map { }` |
+| `publisher.filter { }` | `stream.filter { }` |
+| `PassthroughSubject` | `AsyncStream` via `makeStream(of:)` |
+| `CurrentValueSubject` | No direct equivalent (see note below) |
+| `publisher.values` | Already an `AsyncSequence` – use directly |
+
+If a Combine publisher already exposes a `.values` property, consume that directly rather than wrapping it in a new `AsyncStream`.
+
+Combine is not officially deprecated at this time, but Apple’s advice is to avoid using it.

package/pipeline/skills/shared/external/swift-concurrency-pro/references/new-features.md

@@ -0,0 +1,224 @@
+# Swift 6.2 concurrency
+
+Use this file for recent concurrency changes that materially affect review advice.
+
+## Control default actor isolation inference
+
+Swift 6.2 can opt a module into main-actor isolation by default. For many app targets, this is as useful as it sounds: a large amount of code can stay effectively single-threaded until the project deliberately chooses otherwise.
+
+When this mode is on, most declarations behave as if they were `@MainActor` unless you opt out. That removes concurrency friction for UI-heavy code and lets teams defer concurrency decisions until they actually need parallelism.
+
+Review implications:
+
+- This is a per-module setting. Neighboring modules and dependencies can use different defaults.
+- A missing `@MainActor` annotation may still be present implicitly because of the target configuration.
+- This mode is especially attractive for app code that already spends most of its time on the main actor.
+- Networking and other naturally async APIs still work fine. Suspending I/O does not mean the caller blocks the main actor.
+- Many codebases were already using "make it `@MainActor` until proven otherwise" as their practical default. Swift 6.2 turns that into an explicit tool.
+- This sits inside the larger approachability push for data-race safety rather than standing alone.
+- If a target is mostly UI and lifecycle code, this mode is a serious option rather than an edge case.
+
+**Important:** Some users believe that making their app target `@MainActor` means that networking will also run on the main actor, which is not true – that’s an external module, so it runs elsewhere like it always has.
+
+
+## Global-actor isolated conformances
+
+Swift 6.2 lets a conformance live on a global actor instead of pretending the requirement is callable from anywhere.
+
+```swift
+@MainActor
+class User: @MainActor Equatable {
+    var id: UUID
+    var name: String
+
+    init(name: String) {
+        self.id = UUID()
+        self.name = name
+    }
+
+    static func ==(lhs: User, rhs: User) -> Bool {
+        lhs.id == rhs.id
+    }
+}
+```
+
+Review implications:
+
+- A `@MainActor` type can satisfy a protocol while keeping the conformance actor-bound.
+- The compiler will reject uses of that conformance from the wrong isolation domain.
+- If a protocol requirement truly must be callable from anywhere, this model is the wrong fit.
+
+
+## Run `nonisolated` async functions on the caller's actor by default
+
+Swift 6.2 changes the mental model for plain async methods. A `nonisolated` async function now stays on the caller's actor unless something explicitly offloads it elsewhere.
+
+```swift
+struct Measurements {
+    func fetchLatest() async throws -> [Double] {
+        let url = URL(string: "https://hws.dev/readings.json")!
+        let (data, _) = try await URLSession.shared.data(from: url)
+        return try JSONDecoder().decode([Double].self, from: data)
+    }
+}
+
+@MainActor
+struct WeatherStation {
+    let measurements = Measurements()
+
+    func getAverageTemperature() async throws -> Double {
+        let readings = try await measurements.fetchLatest()
+        return readings.reduce(0, +) / Double(readings.count)
+    }
+}
+```
+
+Before Swift 6.2, the call to `measurements.fetchLatest()` would leave the caller's actor automatically. In Swift 6.2 and later, it stays on the caller's actor unless you say otherwise.
+
+Review implications:
+
+- Plain async on an owned helper no longer implies background execution.
+- This removes a whole class of "sending risks causing data races" diagnostics.
+- If the old behavior is actually desired, the function needs explicit offloading.
+
+
+## Offloading work with `@concurrent`
+
+`@concurrent` is the opt-in tool for code that should leave the caller's actor and run on the concurrent pool.
+
+```swift
+nonisolated struct Measurements {
+    @concurrent
+    func analyzeReadings(_ readings: [Double]) async -> AnalysisResult { ... }
+}
+
+let result = await Measurements().analyzeReadings(readings)
+```
+
+Review implications:
+
+- Use this for CPU-heavy work such as parsing, image processing, compression, or large transforms.
+- Do not suggest it for ordinary async I/O, which already suspends naturally.
+- If a function is `nonisolated` but still expected to run "in the background", check whether `@concurrent` is the missing piece.
+
+
+## Starting tasks synchronously from caller context
+
+`Task.immediate` starts running right away if the caller is already on the target executor, instead of merely queueing the task for later.
+
+```swift
+print("Starting")
+
+Task {
+    print("In Task")
+}
+
+Task.immediate {
+    print("In Immediate Task")
+}
+
+print("Done")
+try await Task.sleep(for: .seconds(0.1))
+```
+
+That ordering means `Task.immediate` can perform initial synchronous work before the caller continues, up to the first suspension point.
+
+Review implications:
+
+- Use it only when that immediate start is the point.
+- It is still an unstructured task after that first synchronous stretch.
+- Task groups also gained `addImmediateTask()` and `addImmediateTaskUnlessCancelled()` for the same immediate-start behavior with child tasks.
+
+
+## Isolated deinit
+
+By default, a deinitializer on an actor-isolated class is *not* isolated - it runs outside the actor, even if the class itself is `@MainActor`. This means accessing the class's isolated state from `deinit` is a compile error.
+
+Mark the deinitializer `isolated` to run it on the class's actor:
+
+```swift
+@MainActor
+class Session {
+    let user: User
+
+    init(user: User) {
+        self.user = user
+        user.isLoggedIn = true
+    }
+
+    isolated deinit {
+        // Runs on the main actor, so accessing user is safe.
+        user.isLoggedIn = false
+    }
+}
+```
+
+Without `isolated`, the deinit would fail to compile because `user` is main actor-isolated and the deinitializer is not. Use this whenever teardown logic needs to touch actor-protected state.
+
+
+## Task priority escalation APIs
+
+Swift 6.2 exposes priority escalation directly. Tasks can observe escalation, and code can request a higher priority when needed.
+
+```swift
+let newsFetcher = Task(priority: .medium) {
+    try await withTaskPriorityEscalationHandler {
+        let url = URL(string: "https://hws.dev/messages.json")!
+        let (data, _) = try await URLSession.shared.data(from: url)
+        return data
+    } onPriorityEscalated: { oldPriority, newPriority in
+        print("Priority has been escalated to \(newPriority)")
+    }
+}
+
+newsFetcher.escalatePriority(to: .high)
+```
+
+Review implications:
+
+- Priority escalation is usually automatic when a higher-priority task waits on lower-priority work.
+- Manual escalation exists, but most code should leave this to the runtime.
+- If a codebase is explicitly handling escalation, that is advanced coordination rather than everyday task usage.
+
+
+## Task naming
+
+Swift 6.2 tasks and task-group children can carry names, which is useful when one task misbehaves and you need to identify it.
+
+```swift
+let task = Task(name: "MyTask") {
+    print("Current task name: \(Task.name ?? "Unknown")")
+}
+```
+
+Task groups support naming too:
+
+```swift
+let stories = await withTaskGroup { group in
+    for i in 1...5 {
+        group.addTask(name: "Stories \(i)") {
+            do {
+                let url = URL(string: "https://hws.dev/news-\(i).json")!
+                let (data, _) = try await URLSession.shared.data(from: url)
+                return try JSONDecoder().decode([NewsStory].self, from: data)
+            } catch {
+                print("Loading \(Task.name ?? "Unknown") failed.")
+                return []
+            }
+        }
+    }
+
+    var allStories = [NewsStory]()
+
+    for await stories in group {
+        allStories.append(contentsOf: stories)
+    }
+
+    return allStories
+}
+```
+
+Review implications:
+
+- Task names are debugging aids, not correctness features.
+- They are worth keeping when logs, tracing, or failure diagnosis matter.

package/pipeline/skills/shared/external/swift-concurrency-pro/references/structured.md

@@ -0,0 +1,101 @@
+# Structured concurrency
+
+## `async let` vs task groups
+
+Use `async let` when you have a fixed number of independent operations that return different types, e.g. fetching the news, the weather, and an app update at the same time. Use task groups when you have a dynamic number of operations of the same type, e.g. downloading all images in an array of URLs.
+
+
+## Task groups over loops
+
+It’s generally a bad idea to use unstructured tasks in a loop; prefer task groups.
+
+```swift
+// WRONG: No cancellation propagation, no way to await all results, leaked tasks on failure.
+for url in urls {
+    Task { try await fetch(url) }
+}
+
+// RIGHT: Structured, cancellable, collects results.
+let results = try await withThrowingTaskGroup { group in
+    for url in urls {
+        group.addTask { try await fetch(url) }
+    }
+
+    var collected = [Data]()
+    for try await result in group {
+        collected.append(result)
+    }
+    return collected
+}
+```
+
+
+## `withDiscardingTaskGroup` (Swift 5.9+)
+
+When child tasks don't return meaningful results (fire-and-forget), use `withDiscardingTaskGroup` instead of `withTaskGroup`. It avoids accumulating unused results in memory.
+
+```swift
+// Preferred for side-effect-only child tasks
+await withDiscardingTaskGroup { group in
+    for connection in connections {
+        group.addTask { await connection.sendHeartbeat() }
+    }
+}
+```
+
+
+## Limiting concurrency
+
+Task groups launch all child tasks eagerly, which may be undesirable. Consider limiting concurrency manually when it is appropriate:
+
+```swift
+try await withThrowingTaskGroup { group in
+    let maxConcurrent = 4
+    var iterator = urls.makeIterator()
+
+    // Start initial batch
+    for _ in 0..<maxConcurrent {
+        guard let url = iterator.next() else { break }
+        group.addTask { try await fetch(url) }
+    }
+
+    // As each finishes, start the next
+    for try await result in group {
+        process(result)
+        if let url = iterator.next() {
+            group.addTask { try await fetch(url) }
+        }
+    }
+}
+```
+
+
+## Error handling with partial results
+
+When one child task throws, the group cancels all remaining children. If you need partial results, catch errors inside each child task:
+
+```swift
+await withTaskGroup(of: (URL, Result<Data, Error>).self) { group in
+    for url in urls {
+        group.addTask {
+            do {
+                return (url, .success(try await fetch(url)))
+            } catch {
+                return (url, .failure(error))
+            }
+        }
+    }
+
+    for await (url, result) in group {
+        switch result {
+        case .success(let data): handle(data)
+        case .failure(let error): log(error, for: url)
+        }
+    }
+}
+```
+
+
+## Inferring the type of task groups
+
+Swift is usually able to infer the type of task groups, but not always. Simple types like `String`, `URL`, `Data`, etc, usually work fine, but the example above uses `withTaskGroup(of: (URL, Result<Data, Error>).self)` and that is an example of the specific type being required – Swift would not be able to infer that.

package/pipeline/skills/shared/external/swift-concurrency-pro/references/testing.md

@@ -0,0 +1,218 @@
+# Testing concurrent code
+
+## Async tests with Swift Testing
+
+Swift Testing supports async test functions natively. No special setup required:
+
+```swift
+@Test func userLoads() async throws {
+    let user = try await UserService().load(id: "123")
+    #expect(user.name == "Alice")
+}
+```
+
+Do not wrap async work in `Task {}` or use expectations/semaphores inside Swift Testing tests – just make the test function `async`.
+
+
+## Testing actor state
+
+Access actor properties through `await` in tests, just like production code. Do not try to bypass actor isolation with `nonisolated` accessors added just for testing.
+
+```swift
+@Test func cachingWorks() async throws {
+    let cache = ImageCache()
+    let image = try await cache.image(for: testURL)
+    let cached = try await cache.image(for: testURL)
+    #expect(image == cached)
+}
+```
+
+
+## The `.serialized` trait and concurrent tests
+
+Swift Testing runs tests in parallel by default, which is usually what you want for concurrency code. However, you may encounter the `.serialized` trait for controlling execution order.
+
+**Important:** `.serialized` only affects parameterized tests. It tells Swift Testing to run that test's argument cases one at a time rather than in parallel. Applying `.serialized` to a non-parameterized test does nothing. Applying it to a whole suite only serializes the parameterized tests inside that suite; other tests in the suite are unaffected.
+
+Agents frequently assume `.serialized` works on any test. It does not.
+
+```swift
+// .serialized controls execution order of parameterized cases only.
+@Test(.serialized, arguments: ["alice", "bob", "charlie"])
+func accountCreation(username: String) async throws {
+    let account = try await AccountService().create(username: username)
+    #expect(account.isActive)
+}
+```
+
+
+## Confirmation for async events
+
+When testing that an async event fires (e.g., a callback, notification, or stream value), use `confirmation()` from Swift Testing:
+
+```swift
+@Test func notificationFires() async {
+    await confirmation { confirmed in
+        // Start listening before posting, and yield to ensure
+        // the for-await loop is actually iterating before the
+        // notification is sent. Without the yield the post can
+        // arrive before the listener is ready, making the test flaky.
+        let task = Task {
+            for await _ in NotificationCenter.default.notifications(named: .dataDidChange) {
+                confirmed()
+                break
+            }
+        }
+
+        // Give the task a chance to reach its first suspension
+        // inside the for-await loop.
+        await Task.yield()
+
+        NotificationCenter.default.post(name: .dataDidChange, object: nil)
+        await task.value
+    }
+}
+```
+
+`confirmation()` fails the test if the closure is never called, replacing the old XCTest pattern of `XCTestExpectation` + `wait(for:timeout:)`.
+
+**Important:** All async work being confirmed must complete before the `confirmation()` closure returns. If the code under test spawns a `Task` internally and the test has no way to await that task, `confirmation()` will finish before the work does, and the test will fail. Either make the production API `async` so the test can await it directly, or have it return its `Task` handle so the test can call `await task.value` before the closure ends.
+
+
+## Actor isolation in tests
+
+By default, Swift Testing runs tests on any executor it chooses. You can constrain this when testing code that requires specific actor isolation.
+
+Mark individual tests or whole suites with `@MainActor` when the code under test requires main-actor isolation:
+
+```swift
+@MainActor
+@Test func viewModelUpdatesOnMainActor() async {
+    let vm = ViewModel()
+    await vm.refresh()
+    #expect(vm.items.isEmpty == false)
+}
+```
+
+For finer control, `confirmation()` and `withKnownIssue()` both accept an `isolation` parameter. This runs just that closure on a specific actor while the rest of the test runs elsewhere:
+
+```swift
+@Test func loadingUpdatesUI() async {
+    await confirmation(isolation: MainActor.shared) { confirmed in
+        let vm = ViewModel(onUpdate: { confirmed() })
+        await vm.load()
+    }
+}
+```
+
+Also be aware that test targets can have default actor isolation enabled at the module level (e.g., a default main-actor module). When reviewing test failures around isolation, check the target's build settings.
+
+
+## Test scoping traits with `@TaskLocal`
+
+**Requires Swift 6.1 or later.**
+
+When multiple tests need a shared configuration (e.g., a mock environment or injected dependency), test scoping traits provide a concurrency-safe way to set it up using task-local values rather than shared mutable state.
+
+Create a type conforming to `TestTrait` and `TestScoping`, then set the task-local value inside `provideScope()`:
+
+```swift
+struct MockEnvironmentTrait: TestTrait, TestScoping {
+    func provideScope(
+        for test: Test,
+        testCase: Test.Case?,
+        performing function: () async throws -> Void
+    ) async throws {
+        let env = Environment(apiBase: URL(string: "https://test.example.com")!)
+
+        try await Environment.$current.withValue(env) {
+            try await function()
+        }
+    }
+}
+
+extension Trait where Self == MockEnvironmentTrait {
+    static var mockEnvironment: Self { Self() }
+}
+```
+
+Then apply it to any test or suite:
+
+```swift
+@Test(.mockEnvironment) func fetchUsesTestAPI() async throws {
+    // Environment.current is now the mock, scoped to this test's task.
+    let users = try await UserService().fetchAll()
+    #expect(users.isEmpty == false)
+}
+```
+
+This avoids the concurrency hazards of a shared `setUp()` mutating global state. Each test's configuration lives in the task-local, so parallel tests get independent values automatically.
+
+
+## Avoid timing-based tests
+
+Never use `Task.sleep`, `Thread.sleep`, or fixed delays to "wait for something to happen." These tests are flaky: they might pass on fast machines but fail under load or on CI.
+
+```swift
+// BROKEN: Relies on timing.
+@Test func dataLoads() async throws {
+    viewModel.load()
+    try await Task.sleep(for: .seconds(1))
+    #expect(viewModel.items.isEmpty == false)
+}
+```
+
+Instead, await the actual async operation:
+
+```swift
+// CORRECT: Awaits the real work.
+@Test func dataLoads() async throws {
+    await viewModel.load()
+    #expect(viewModel.items.isEmpty == false)
+}
+```
+
+If the API is callback-based, wrap it with `withCheckedContinuation` or use `confirmation()`.
+
+
+## Testing cancellation
+
+The goal is to verify that the *code under test* checks for cancellation, not just that `Task.checkCancellation()` works in a test harness. Design the test so the code under test is the thing that observes the cancellation flag.
+
+A reliable approach: give the code under test a stream or signal it blocks on, cancel the task while it's suspended on that signal, then verify it exits with `CancellationError`:
+
+```swift
+@Test func processorRespectsCancel() async throws {
+    // Processor.run() calls Task.checkCancellation() between items.
+    // Feed it enough work that cancellation will be checked mid-flight.
+    let processor = Processor(items: Array(repeating: .stub, count: 1_000))
+
+    let task = Task {
+        try await processor.run()
+    }
+
+    // Let the processor start, then cancel.
+    try await Task.sleep(for: .zero)
+    task.cancel()
+
+    await #expect(throws: CancellationError.self) {
+        try await task.value
+    }
+}
+```
+
+If the code under test is a `for await` loop, you can cancel the consuming task and verify the loop exits. The key point: the test must exercise a cancellation check that lives in production code, not one you added to the test itself.
+
+
+## Race detection
+
+It’s a good idea to enable Thread Sanitizer (TSan) in your test scheme to catch data races at runtime. TSan finds races that the compiler's static checks often miss, particularly in code using `@unchecked Sendable` or unsafe pointers.
+
+In Xcode: Product → Scheme Edit Scheme → Diagnostics → Thread Sanitizer.
+
+TSan adds overhead, so consider enabling it for a dedicated CI job rather than every local run.
+
+
+## Swift Testing + Swift concurrency
+
+For more help with Swift Testing, suggest the [Swift Testing Pro agent skill](https://github.com/twostraws/swift-testing-agent-skill).