@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/external/swift-concurrency/references/synchronization-primitives.md

@@ -0,0 +1,341 @@
+# Synchronization Primitives
+
+Low-level synchronization tools for protecting shared mutable state when actors
+are not the right fit. All primitives discussed here are `Sendable` and safe
+to use from multiple threads.
+
+## Contents
+
+- [Mutex](#mutex)
+- [OSAllocatedUnfairLock](#osallocatedunfairlock)
+- [Atomic](#atomic)
+- [Locks vs Actors: When to Use Each](#locks-vs-actors-when-to-use-each)
+
+## Mutex
+
+**Module:** `Synchronization` · **Availability:** iOS 18.0+
+
+`Mutex<Value>` is a synchronization primitive that protects shared mutable
+state via mutual exclusion. It blocks threads attempting to acquire the lock,
+ensuring only one execution context accesses the protected value at a time.
+
+**Documentation:**
+[sosumi.ai/documentation/synchronization/mutex](https://sosumi.ai/documentation/synchronization/mutex)
+
+### Basic Usage
+
+```swift
+import Synchronization
+
+class ImageCache: Sendable {
+    let storage = Mutex<[String: UIImage]>([:])
+
+    func image(forKey key: String) -> UIImage? {
+        storage.withLock { $0[key] }
+    }
+
+    func store(_ image: UIImage, forKey key: String) {
+        storage.withLock { $0[key] = image }
+    }
+
+    func removeAll() {
+        storage.withLock { $0.removeAll() }
+    }
+}
+```
+
+### withLockIfAvailable
+
+Use `withLockIfAvailable` to attempt acquisition without blocking. Returns
+`nil` if the lock is already held.
+
+```swift
+let counter = Mutex<Int>(0)
+
+// Non-blocking attempt — returns nil if lock is contended
+if let value = counter.withLockIfAvailable({ $0 }) {
+    print("Current count: \(value)")
+} else {
+    print("Lock was busy, skipping")
+}
+```
+
+### Key Properties
+
+- **Generic over `Value`:** The protected state is stored inside the mutex,
+  making it clear what the lock protects.
+- **`Sendable`:** `Mutex` conforms to `Sendable`, so it can be stored in
+  `Sendable` types (classes, actors, global state).
+- **Non-recursive:** Attempting to lock a `Mutex` that you already hold on the
+  same thread is undefined behavior.
+- **Synchronous only:** Do not `await` inside `withLock`. The lock is held for
+  the duration of the closure — blocking across a suspension point will
+  deadlock or starve other threads.
+
+## OSAllocatedUnfairLock
+
+**Module:** `os` · **Availability:** iOS 16.0+
+
+`OSAllocatedUnfairLock<State>` wraps `os_unfair_lock` in a safe Swift API.
+It heap-allocates the underlying lock, avoiding the unsound address-of
+problem that makes raw `os_unfair_lock` unusable from Swift.
+
+**Documentation:**
+[sosumi.ai/documentation/os/osallocatedunfairlock](https://sosumi.ai/documentation/os/osallocatedunfairlock)
+
+### State-Protecting Lock
+
+```swift
+import os
+
+enum LoadState: Sendable {
+    case idle
+    case loading
+    case complete(Data)
+    case failed(Error)
+}
+
+final class ResourceLoader: Sendable {
+    let state = OSAllocatedUnfairLock(initialState: LoadState.idle)
+
+    func beginLoading() {
+        state.withLock { $0 = .loading }
+    }
+
+    func completeLoading(with data: Data) {
+        state.withLock { $0 = .complete(data) }
+    }
+
+    var currentState: LoadState {
+        state.withLock { $0 }
+    }
+}
+```
+
+### Stateless Lock
+
+When protecting external state or a code section rather than a specific value:
+
+```swift
+let lock = OSAllocatedUnfairLock()
+
+lock.withLock {
+    // Critical section — no associated state
+    writeToSharedFile(data)
+}
+```
+
+### Manual lock/unlock
+
+Available but discouraged. Must unlock from the same thread that locked.
+**Never** use across `await` suspension points.
+
+```swift
+lock.lock()
+defer { lock.unlock() }
+// Critical section
+```
+
+### Mutex vs OSAllocatedUnfairLock
+
+| | `Mutex<Value>` | `OSAllocatedUnfairLock<State>` |
+|---|---|---|
+| **Availability** | iOS 18+ | iOS 16+ |
+| **Module** | `Synchronization` | `os` |
+| **State model** | Value stored inside lock (generic `Value`) | Optional state via `initialState:` |
+| **`withLockIfAvailable`** | Returns `nil` on contention | Returns `nil` on contention |
+| **Ownership assertions** | Not available | `precondition(.owner)` / `precondition(.notOwner)` |
+| **Manual lock/unlock** | Not available | Available (`lock()` / `unlock()`) |
+| **Recommendation** | Preferred for iOS 18+ code | Use when targeting iOS 16–17 |
+
+**Guideline:** Use `Mutex` for new code targeting iOS 18+. Use
+`OSAllocatedUnfairLock` when you need to support iOS 16–17, or when you need
+ownership assertions for debugging.
+
+## Atomic
+
+**Module:** `Synchronization` · **Availability:** iOS 18.0+
+
+`Atomic<Value>` provides lock-free atomic operations on values conforming to
+`AtomicRepresentable`. Use atomics for simple counters, flags, and
+compare-and-swap patterns where a full lock would be overkill.
+
+**Documentation:**
+[sosumi.ai/documentation/synchronization/atomic](https://sosumi.ai/documentation/synchronization/atomic)
+
+### Counter Example
+
+```swift
+import Synchronization
+
+final class RequestTracker: Sendable {
+    let activeRequests = Atomic<Int>(0)
+
+    func beginRequest() {
+        activeRequests.wrappingAdd(1, ordering: .relaxed)
+    }
+
+    func endRequest() {
+        activeRequests.wrappingSubtract(1, ordering: .relaxed)
+    }
+
+    var count: Int {
+        activeRequests.load(ordering: .relaxed)
+    }
+}
+```
+
+### Boolean Flag
+
+```swift
+let isShutdown = Atomic<Bool>(false)
+
+func shutdown() {
+    let (exchanged, _) = isShutdown.compareExchange(
+        expected: false,
+        desired: true,
+        ordering: .acquiringAndReleasing
+    )
+    guard exchanged else { return } // Already shut down
+    performCleanup()
+}
+```
+
+### Memory Ordering
+
+Atomic operations require an explicit memory ordering:
+
+| Ordering | Use case |
+|---|---|
+| `.relaxed` | Counters, statistics — no ordering guarantees needed |
+| `.acquiring` | Read that must see all writes before a corresponding release |
+| `.releasing` | Write that must be visible to a corresponding acquire |
+| `.acquiringAndReleasing` | Compare-and-swap, read-modify-write |
+| `.sequentiallyConsistent` | Strongest guarantee — rarely needed |
+
+**Guideline:** Use `.relaxed` for simple counters. Use
+`.acquiringAndReleasing` for compare-and-swap patterns. Avoid
+`.sequentiallyConsistent` unless you have a proven need — it is the most
+expensive ordering.
+
+### When to Use Atomics vs Mutex
+
+- **Atomics:** Simple scalar values (Int, Bool, UInt64), single-field updates,
+  counters, flags. Lock-free and very fast.
+- **Mutex:** Compound state (dictionaries, structs with multiple fields),
+  multi-step operations that must be atomic as a group.
+
+## Locks vs Actors: When to Use Each
+
+### Use Actors When:
+
+- **Async isolation is natural.** The protected state is accessed from async
+  contexts and you can afford the hop.
+- **Structured concurrency.** You want the compiler to enforce isolation
+  boundaries and prevent data races statically.
+- **Most Swift code.** Actors are the default recommendation for shared mutable
+  state in Swift concurrency.
+- **Complex state with multiple methods.** Actor isolation protects all
+  properties and methods automatically.
+
+```swift
+// GOOD: Actor for a cache accessed from async contexts
+actor ImageDownloader {
+    private var cache: [URL: UIImage] = [:]
+
+    func image(for url: URL) async throws -> UIImage {
+        if let cached = cache[url] { return cached }
+        let (data, _) = try await URLSession.shared.data(from: url)
+        let image = UIImage(data: data)!
+        cache[url] = image
+        return image
+    }
+}
+```
+
+### Use Mutex / Locks When:
+
+- **Synchronous access is required.** Callers cannot (or should not) be async.
+  Accessing an actor from synchronous code requires `Task` and introduces
+  unwanted asynchrony.
+- **Performance-critical paths.** Lock acquisition is nanoseconds; actor hops
+  involve task scheduling. For tight loops or high-frequency access, a lock
+  may be significantly faster.
+- **Bridging with C/ObjC.** C callbacks, delegate methods, or ObjC APIs that
+  cannot be made async.
+- **Simple counters or flags.** `Atomic<Int>` or `Atomic<Bool>` is cheaper and
+  simpler than creating an actor for a single value.
+
+```swift
+// GOOD: Mutex for synchronous, high-frequency access
+final class MetricsCollector: Sendable {
+    let metrics = Mutex<[String: Int]>([:])
+
+    // Called from tight loops, C callbacks, or synchronous code
+    func increment(_ key: String) {
+        metrics.withLock { $0[key, default: 0] += 1 }
+    }
+
+    func snapshot() -> [String: Int] {
+        metrics.withLock { $0 }
+    }
+}
+```
+
+### Decision Guide
+
+```text
+Need shared mutable state protection?
+├── Can all access be async?
+│   ├── Yes → Use an actor
+│   └── No → Use Mutex or OSAllocatedUnfairLock
+├── Single scalar value (counter, flag)?
+│   └── Use Atomic<Value>
+├── Performance-critical (nanosecond-level)?
+│   └── Use Mutex or Atomic
+└── Bridging C/ObjC callbacks?
+    └── Use Mutex or OSAllocatedUnfairLock
+```
+
+### Anti-Patterns
+
+**Never put locks inside actors.** An actor already serializes access; adding
+a lock creates double synchronization and risks deadlocks.
+
+```swift
+// WRONG: Lock inside an actor — double synchronization
+actor BadCache {
+    let lock = Mutex<[String: Data]>([:])  // Unnecessary!
+    // The actor already protects its state
+}
+
+// CORRECT: Just use the actor's built-in isolation
+actor GoodCache {
+    var cache: [String: Data] = [:]
+
+    func store(_ data: Data, key: String) {
+        cache[key] = data
+    }
+}
+```
+
+**Never use `DispatchSemaphore` or `NSLock` in modern Swift.** Use `Mutex`
+(iOS 18+) or `OSAllocatedUnfairLock` (iOS 16+) instead. Legacy lock types
+have no `Sendable` conformance and are not designed for structured
+concurrency.
+
+**Never hold a lock across `await`.** This blocks the thread and can deadlock
+the cooperative thread pool.
+
+```swift
+// WRONG: Holding lock across suspension point
+mutex.withLock { value in
+    value = await fetchData()  // DEADLOCK RISK
+}
+
+// CORRECT: Fetch first, then lock to update
+let data = await fetchData()
+mutex.withLock { value in
+    value = data
+}
+```

package/pipeline/skills/shared/external/swift-concurrency-expert/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: swift-concurrency-expert
+description: Review and fix Swift concurrency issues such as actor isolation and Sendable violations.
+risk: safe
+source: "Dimillian/Skills (MIT)"
+date_added: "2026-03-25"
+---
+
+# Swift Concurrency Expert
+
+## Overview
+
+Review and fix Swift Concurrency issues in Swift 6.2+ codebases by applying actor isolation, Sendable safety, and modern concurrency patterns with minimal behavior changes.
+
+## When to Use
+
+- When the user asks to review Swift concurrency usage or fix compiler diagnostics.
+- When you need guidance on actor isolation, `Sendable`, `@MainActor`, or async migration.
+
+## Workflow
+
+### 1. Triage the issue
+
+- Capture the exact compiler diagnostics and the offending symbol(s).
+- Check project concurrency settings: Swift language version (6.2+), strict concurrency level, and whether approachable concurrency (default actor isolation / main-actor-by-default) is enabled.
+- Identify the current actor context (`@MainActor`, `actor`, `nonisolated`) and whether a default actor isolation mode is enabled.
+- Confirm whether the code is UI-bound or intended to run off the main actor.
+
+### 2. Apply the smallest safe fix
+
+Prefer edits that preserve existing behavior while satisfying data-race safety.
+
+Common fixes:
+- **UI-bound types**: annotate the type or relevant members with `@MainActor`.
+- **Protocol conformance on main actor types**: make the conformance isolated (e.g., `extension Foo: @MainActor SomeProtocol`).
+- **Global/static state**: protect with `@MainActor` or move into an actor.
+- **Background work**: move expensive work into a `@concurrent` async function on a `nonisolated` type or use an `actor` to guard mutable state.
+- **Sendable errors**: prefer immutable/value types; add `Sendable` conformance only when correct; avoid `@unchecked Sendable` unless you can prove thread safety.
+
+### 3. Verify the fix
+
+- Rebuild and confirm all concurrency diagnostics are resolved with no new warnings introduced.
+- Run the test suite to check for regressions — concurrency changes can introduce subtle runtime issues even when the build is clean.
+- If the fix surfaces new warnings, treat each one as a fresh triage (return to step 1) and resolve iteratively until the build is clean and tests pass.
+
+### Examples
+
+**UI-bound type — adding `@MainActor`**
+
+```swift
+// Before: data-race warning because ViewModel is accessed from the main thread
+// but has no actor isolation
+class ViewModel: ObservableObject {
+    @Published var title: String = ""
+    func load() { title = "Loaded" }
+}
+
+// After: annotate the whole type so all stored state and methods are
+// automatically isolated to the main actor
+@MainActor
+class ViewModel: ObservableObject {
+    @Published var title: String = ""
+    func load() { title = "Loaded" }
+}
+```
+
+**Protocol conformance isolation**
+
+```swift
+// Before: compiler error — SomeProtocol method is nonisolated but the
+// conforming type is @MainActor
+@MainActor
+class Foo: SomeProtocol {
+    func protocolMethod() { /* accesses main-actor state */ }
+}
+
+// After: scope the conformance to @MainActor so the requirement is
+// satisfied inside the correct isolation context
+@MainActor
+extension Foo: SomeProtocol {
+    func protocolMethod() { /* safely accesses main-actor state */ }
+}
+```
+
+**Background work with `@concurrent`**
+
+```swift
+// Before: expensive computation blocks the main actor
+@MainActor
+func processData(_ input: [Int]) -> [Int] {
+    input.map { heavyTransform($0) }   // runs on main thread
+}
+
+// After: hop off the main actor for the heavy work, then return the result
+// The caller awaits the result and stays on its own actor
+nonisolated func processData(_ input: [Int]) async -> [Int] {
+    await Task.detached(priority: .userInitiated) {
+        input.map { heavyTransform($0) }
+    }.value
+}
+
+// Or, using a @concurrent async function (Swift 6.2+):
+@concurrent
+func processData(_ input: [Int]) async -> [Int] {
+    input.map { heavyTransform($0) }
+}
+```
+
+## Reference material
+
+- See `references/swift-6-2-concurrency.md` for Swift 6.2 changes, patterns, and examples.
+- See `references/approachable-concurrency.md` when the project is opted into approachable concurrency mode.
+- See `references/swiftui-concurrency-tour-wwdc.md` for SwiftUI-specific concurrency guidance.

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

@@ -0,0 +1,124 @@
+---
+name: swift-concurrency-pro
+description: Reviews Swift code for concurrency correctness, modern API usage, and common async/await pitfalls. Use when reading, writing, or reviewing Swift concurrency code.
+license: MIT
+metadata:
+  author: Paul Hudson
+  version: "1.0"
+---
+
+Review Swift concurrency code for correctness, modern API usage, and adherence to project conventions. Report only genuine problems - do not nitpick or invent issues.
+
+Review process:
+
+1. Scan for known-dangerous patterns using `references/hotspots.md` to prioritize what to inspect.
+1. Check for recent Swift 6.2 concurrency behavior using `references/new-features.md`.
+1. Validate actor usage for reentrancy and isolation correctness using `references/actors.md`.
+1. Ensure structured concurrency is preferred over unstructured where appropriate using `references/structured.md`.
+1. Check unstructured task usage for correctness using `references/unstructured.md`.
+1. Verify cancellation is handled correctly using `references/cancellation.md`.
+1. Validate async stream and continuation usage using `references/async-streams.md`.
+1. Check bridging code between sync and async worlds using `references/bridging.md`.
+1. Review any legacy concurrency migrations using `references/interop.md`.
+1. Cross-check against common failure modes using `references/bug-patterns.md`.
+1. If the project has strict-concurrency errors, map diagnostics to fixes using `references/diagnostics.md`.
+1. If reviewing tests, check async test patterns using `references/testing.md`.
+
+If doing a partial review, load only the relevant reference files.
+
+
+## Core Instructions
+
+- Target Swift 6.2 or later with strict concurrency checking.
+- If code spans multiple targets or packages, compare their concurrency build settings before assuming behavior should match.
+- Prefer structured concurrency (task groups) over unstructured (`Task {}`).
+- Prefer Swift concurrency over Grand Central Dispatch for new code. GCD is still acceptable in low-level code, framework interop, or performance-critical synchronous work where queues and locks are the right tool – don't flag these as errors.
+- If an API offers both `async`/`await` and closure-based variants, always prefer `async`/`await`.
+- Do not introduce third-party concurrency frameworks without asking first.
+- Do not suggest `@unchecked Sendable` to fix compiler errors. It silences the diagnostic without fixing the underlying race. Prefer actors, value types, or `sending` parameters instead. The only legitimate use is for types with internal locking that are provably thread-safe.
+
+
+## Output Format
+
+Organize findings by file. For each issue:
+
+1. State the file and relevant line(s).
+2. Name the rule being violated.
+3. Show a brief before/after code fix.
+
+Skip files with no issues. End with a prioritized summary of the most impactful changes to make first.
+
+Example output:
+
+### DataLoader.swift
+
+**Line 18: Actor reentrancy – state may have changed across the `await`.**
+
+```swift
+// Before
+actor Cache {
+    var items: [String: Data] = [:]
+
+    func fetch(_ key: String) async throws -> Data {
+        if items[key] == nil {
+            items[key] = try await download(key)
+        }
+        return items[key]!
+    }
+}
+
+// After
+actor Cache {
+    var items: [String: Data] = [:]
+
+    func fetch(_ key: String) async throws -> Data {
+        if let existing = items[key] { return existing }
+        let data = try await download(key)
+        items[key] = data
+        return data
+    }
+}
+```
+
+**Line 34: Use `withTaskGroup` instead of creating tasks in a loop.**
+
+```swift
+// Before
+for url in urls {
+    Task { try await fetch(url) }
+}
+
+// After
+try await withThrowingTaskGroup(of: Data.self) { group in
+    for url in urls {
+        group.addTask { try await fetch(url) }
+    }
+
+    for try await result in group {
+        process(result)
+    }
+}
+```
+
+### Summary
+
+1. **Correctness (high):** Actor reentrancy bug on line 18 may cause duplicate downloads and a force-unwrap crash.
+2. **Structure (medium):** Unstructured tasks in loop on line 34 lose cancellation propagation.
+
+End of example.
+
+
+## References
+
+- `references/hotspots.md` - Grep targets for code review: known-dangerous patterns and what to check for each.
+- `references/new-features.md` - Swift 6.2 changes that alter review advice: default actor isolation, isolated conformances, caller-actor async behavior, `@concurrent`, `Task.immediate`, task naming, and priority escalation.
+- `references/actors.md` - Actor reentrancy, shared-state annotations, global actor inference, and isolation patterns.
+- `references/structured.md` - Task groups over loops, discarding task groups, concurrency limits.
+- `references/unstructured.md` - Task vs Task.detached, when Task {} is a code smell.
+- `references/cancellation.md` - Cancellation propagation, cooperative checking, broken cancellation patterns.
+- `references/async-streams.md` - AsyncStream factory, continuation lifecycle, back-pressure.
+- `references/bridging.md` - Checked continuations, wrapping legacy APIs, `@unchecked Sendable`.
+- `references/interop.md` - Migrating from GCD, `Mutex`/locks, completion handlers, delegates, and Combine.
+- `references/bug-patterns.md` - Common concurrency failure modes and their fixes.
+- `references/diagnostics.md` - Strict-concurrency compiler errors, protocol conformance fixes, and likely remedies.
+- `references/testing.md` - Async test strategy with Swift Testing, race detection, avoiding timing-based tests.