@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/swift-ios/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: swift-ios
+description: "Use when building native iOS and Apple-platform apps in Swift with SwiftUI and modern Swift concurrency — observable view models, Swift 6 strict data-race diagnostics, async/await and actors, SwiftData persistence, NavigationStack, and Swift Testing. NOT cross-platform Dart (that is `flutter`), NOT React Native (that is `react-native`), NOT native Kotlin for Android (that is `kotlin-android`), NOT shared KMP code across both OSes (that is `compose-multiplatform`)."
+tags: [swift, swiftui, ios, swift-concurrency, swiftdata, swift-testing, apple]
+recommends: [kotlin-android, compose-multiplatform, flutter, react-native, expo, testing-web, github-actions, ship]
+profiles: []
+origin: ai-hub
+---
+
+# swift-ios
+
+**Hand-off — the language vs the platform.** This skill owns the **platform**: SwiftUI/UIKit views,
+app lifecycle, Xcode, iOS APIs, App Store shipping. Language-level Swift — Swift 6 data-race safety
+and approachable concurrency, actors and task groups, `some` vs `any`, ARC and performance, Swift
+Testing, macros — is this skill's own ground. A concurrency error, a hang, a data race or a
+retain cycle belongs here, and so do interface feel, springs and materials on iOS.
+
+
+Native Apple-platform apps: the code is `.swift`, the UI is SwiftUI, and the compiler enforces actor isolation. If the answer is a `@MainActor`, `@Observable`, `async let`, `#expect`, `NavigationStack`, or `@Model`, you are in the right place.
+
+## First move: match the project before you write a line
+
+Mismatched language modes produce diagnostics you cannot reproduce and "fixes" that break the user's build. Pin the ground truth first.
+
+```bash
+swift --version                               # exact toolchain
+xcodebuild -version                           # Xcode version
+# In the .xcodeproj / Package.swift, read two settings per target:
+#   SWIFT_VERSION (Swift Language Version: 5 or 6)
+#   SWIFT_DEFAULT_ACTOR_ISOLATION (Default Actor Isolation: nonisolated or MainActor)
+```
+
+Assumed baseline: **Xcode 26 / Swift 6.2 / iOS 26 SDK** (current stable seen is Xcode 26.2 / Swift 6.2.3). Do not quote a version you have not confirmed in the user's project. Rule: **write for the target's actual language mode.** Swift 5-mode code dropped into a Swift 6 target (or vice-versa) is the most common source of "it compiles on my machine" failures.
+
+## State & view architecture
+
+For new code use `@Observable` (the Observation framework), never `ObservableObject` / `@Published`. Why: Observation tracks per-property — a view re-renders only when a property it actually reads changes, not on every object mutation.
+
+| Property wrapper | Use it when | One-line why |
+| --- | --- | --- |
+| `@State` | The view *owns* a value or an `@Observable` instance | Lifecycle tied to the view; survives re-renders |
+| `@Binding` | A child needs write access to a parent's value | Passes a mutable reference down, no ownership |
+| `@Bindable` | You need two-way bindings *into* an `@Observable` | Produces `$model.field` for `TextField` etc. |
+| `@Environment` | Dependency injection of a shared `@Observable` | One source of truth, no prop-drilling |
+
+`@Observable` gives you **zero** thread safety. Mutating an observed property off the main actor races the UI. Annotate UI models `@MainActor`.
+
+```swift
+// Bad — legacy pattern, whole-object invalidation, no isolation
+final class CounterModel: ObservableObject {
+    @Published var count = 0
+}
+
+// Good — per-property tracking, main-actor isolated
+@MainActor @Observable
+final class CounterModel {
+    var count = 0
+}
+
+struct CounterView: View {
+    @State private var model = CounterModel()      // view owns it
+    var body: some View {
+        Stepper("\(model.count)", value: $model.count)  // @State gives bindings to @Observable
+    }
+}
+```
+
+## Concurrency correctness (the core)
+
+The mental model: SwiftUI runs on the main actor. Anything that touches UI state is main-actor work. Background work hops off, then hops back to mutate.
+
+- **`@MainActor` class** for UI/view-model state — it *is* the UI thread.
+- **`actor`** for shared *non-UI* mutable state (a cache, a connection pool). Never model a SwiftUI view model as an `actor` — actors are reentrant and not main-bound, so your UI updates land off-main.
+- **`Task { }`** inherits the current actor + priority — use it to fire async work from a `Button`. **`Task.detached`** inherits nothing and is almost never what you want; reaching for it to silence a warning is a bug, not a fix.
+- **`async let` / `TaskGroup`** for structured parallelism (fan out, then `await` all).
+- **Cancellation is mandatory**: check `Task.isCancelled` or `try Task.checkCancellation()` in loops. SwiftUI's `.task {}` auto-cancels when the view disappears — prefer it over a bare `Task {}` for view-lifetime work.
+
+The #1 footgun — mutating observed UI state off the main actor:
+
+```swift
+// Bad — detached task mutates main-isolated state; intermittent glitches + Swift 6 data-race warning
+@MainActor @Observable final class Feed {
+    var items: [Item] = []
+    func load() {
+        Task.detached {
+            let data = try? await API.fetch()
+            self.items = data ?? []          // off-main mutation: WRONG
+        }
+    }
+}
+
+// Good — Task {} inherits the main actor; await off-main work, mutation lands on-main
+@MainActor @Observable final class Feed {
+    var items: [Item] = []
+    func load() async {
+        do {
+            items = try await API.fetch()    // await suspends; assignment is back on main
+        } catch is CancellationError {
+            // view disappeared — nothing to do
+        } catch {
+            // surface error
+        }
+    }
+}
+// In the view: .task { await feed.load() }   // auto-cancels on disappear
+```
+
+Escape hatch for UI-centric apps: set **Default Actor Isolation = MainActor** (SE-0466) on the target — unannotated code becomes main-actor-isolated by default, killing false-positive data-race warnings; you opt *out* with `nonisolated` only where you genuinely need it. The full diagnostic catalog, Sendable rules, and the staged Swift 6 migration live in [references/concurrency.md](references/concurrency.md).
+
+## Persistence
+
+| Choice | Use when |
+| --- | --- |
+| **SwiftData** (default) | New SwiftUI apps; relational/object graph; light-to-moderate migration needs |
+| Core Data | Advanced/custom migrations, mature `NSPersistentCloudKit` edge cases |
+| Files (`Codable` → disk) | Trivial, non-relational blobs only |
+
+```swift
+import SwiftData
+
+@Model final class Workout {
+    var name: String
+    var minutes: Int
+    init(name: String, minutes: Int) { self.name = name; self.minutes = minutes }
+}
+
+// App entry: attach the container once
+WindowGroup { ContentView() }.modelContainer(for: Workout.self)
+
+// In a view: query + mutate
+struct ListView: View {
+    @Query(sort: \Workout.name) private var workouts: [Workout]
+    @Environment(\.modelContext) private var context
+    var body: some View {
+        List(workouts) { Text($0.name) }
+            .toolbar { Button("Add") { context.insert(Workout(name: "Run", minutes: 30)) } }
+    }
+}
+```
+
+Bad: hand-rolling JSON-to-disk for relational data with cross-references. Good: model the relationship with `@Model` and let SwiftData own identity and autosave.
+
+## Navigation
+
+Use `NavigationStack` with a value-typed `path` + `navigationDestination(for:)` — type-safe, programmatic, and deep-linkable. `NavigationView` is deprecated.
+
+```swift
+// Bad
+NavigationView { List(items) { NavigationLink(item.name, destination: DetailView(item: item)) } }
+
+// Good — push by value, deep-link by mutating the path
+@State private var path: [Item] = []
+NavigationStack(path: $path) {
+    List(items) { item in NavigationLink(item.name, value: item) }
+        .navigationDestination(for: Item.self) { DetailView(item: $0) }
+}
+// Deep link: path = [parent, child]
+```
+
+Use `NavigationSplitView` for iPad/Mac multi-column layouts.
+
+## Testing
+
+Swift Testing is the default (Xcode 16+, matured through Xcode 26): `@Test`, `#expect` (soft — keeps running), `#require` (hard — throws/unwraps), `@Test(arguments:)` for parameterized cases, `@Suite` types, parallel + in-process by default.
+
+```swift
+import Testing
+@testable import MyApp
+
+@Suite struct ScoreTests {
+    @Test func startsAtZero() { #expect(Score().value == 0) }
+
+    @Test(arguments: [1, 2, 3]) func adds(_ n: Int) {
+        var s = Score(); s.add(n)
+        #expect(s.value == n)
+    }
+
+    @Test func requiredUser() throws {
+        let user = try #require(UserStore().current)   // hard stop if nil
+        #expect(user.isActive)
+    }
+}
+```
+
+UI automation (`XCUIApplication`) and performance (`XCTMetric`) **stay in XCTest** — both frameworks coexist in one target. Run: `xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17'`. Depth (traits, `confirmation` for async events, in-memory `ModelContainer` for SwiftData, the XCTest migration table) in [references/testing.md](references/testing.md).
+
+## Build / run loop
+
+```bash
+xcodebuild -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17' build
+xcodebuild -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17' test
+xcrun simctl list devices                 # manage simulators
+swift build && swift test                 # SwiftPM packages (libraries / modular targets)
+```
+
+App = `.xcodeproj`/`.xcworkspace` built with `xcodebuild`. Library or shared module = `Package.swift` built with `swift build`; use SwiftPM to pin dependency versions.
+
+## iOS 26 adoption (brief)
+
+New surface: Liquid Glass via `.glassEffect()` (no `UIVisualEffectView`), the `@Animatable` macro for custom animatable shapes, native SwiftUI `WebView`, `Chart3D`, richer `TabView` roles. Adopt them behind `if #available(iOS 26, *)`; do not casually raise the whole deployment target — most apps still support N-1/N-2.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+| --- | --- | --- |
+| `actor` for a SwiftUI view model | Reentrant, not main-bound → UI mutates off-main | `@MainActor @Observable` class |
+| `Task.detached` to silence a warning | Drops actor + priority inheritance; hides the real race | `Task {}` or `.task {}` |
+| `@nonisolated(unsafe)` to quiet isolation errors | Disables the safety you turned on; the race remains | Make the type `Sendable` or keep it main-isolated |
+| `DispatchQueue.main.async` inside an `@Observable` model | Old concurrency model fighting actors | Annotate the model `@MainActor` |
+| `ObservableObject` / `@Published` for new code | Whole-object invalidation, no isolation help | `@Observable` |
+| `NavigationView` | Deprecated, no type-safe path | `NavigationStack` + `navigationDestination` |
+| Blocking the main actor with sync network/disk I/O | Freezes the UI | `await` async work, hop back to main to mutate |
+| `@MainActor` on pure compute / leaf utilities | Needless serialization onto the UI thread | Leave it `nonisolated` |
+| `XCTAssert` in a new Swift Testing file | Mixing frameworks; loses `#expect` diagnostics | `#expect` / `#require` |
+| Force-unwrapping `@Query` / fetch results | Crashes on empty store | Handle the empty case |
+
+## Cross-references
+
+- Native Android in Kotlin/Compose → [../kotlin-android/SKILL.md](../kotlin-android/SKILL.md)
+- One codebase for iOS + Android via KMP/CMP → [../compose-multiplatform/SKILL.md](../compose-multiplatform/SKILL.md)
+- Cross-platform Dart → [../flutter/SKILL.md](../flutter/SKILL.md)
+- React Native runtime / native modules → [../react-native/SKILL.md](../react-native/SKILL.md); the EAS/OTA shipping pipeline → [../expo/SKILL.md](../expo/SKILL.md)
+- Store submission / release process → [../ship/SKILL.md](../ship/SKILL.md)
+- Cloud CI build/sign and the non-Swift test stack are siblings (`github-actions`, `testing-web`) — see `recommends`.

package/skills/shared/swift-ios/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — swift-ios
+
+These cases are routing/trigger fixtures plus one capability rubric. `should_trigger` lists prompts that must select this skill (including a verbatim Swift 6 diagnostic and a Catalan phrasing); `should_not_trigger` lists adjacent prompts that must route to the named sibling instead. No Xcode, simulator, or Swift toolchain is needed to evaluate them — judge whether a router would pick `swift-ios` and explain why. The `capability` case is graded against its `must_include` checklist by reading the model's proposed refactor, not by compiling or running anything; pass it only if the answer covers each rubric point (MainActor isolation, `Task {}` over `Task.detached`, Sendable, `@Observable` + `@State`, cancellation).

package/skills/shared/swift-ios/evals/cases.yaml

@@ -0,0 +1,46 @@
+skill: swift-ios
+
+should_trigger:
+  - prompt: "Build a native iOS app in SwiftUI to track workouts with local persistence."
+    why: Core greenfield SwiftUI app with SwiftData persistence — the skill's home turf.
+  - prompt: "Compiler says 'main actor-isolated property cannot be referenced from a nonisolated context' after I turned on Swift 6 mode."
+    why: Non-obvious — a verbatim strict-concurrency diagnostic that only this skill diagnoses and fixes.
+  - prompt: "Should my SwiftUI view model be an actor or a @MainActor class?"
+    why: Concurrency-architecture decision unique to Swift/SwiftUI; the answer is @MainActor, not actor.
+  - prompt: "Migrate my XCTest cases to #expect / @Test and parameterize them."
+    why: Swift Testing ownership; XCTest-to-Swift-Testing migration lives here.
+  - prompt: "Necesito una app nativa de iOS amb SwiftUI i concurrència moderna (async/await)."
+    why: Catalan/Spanish phrasing for a native SwiftUI + concurrency app.
+  - prompt: "How do I do type-safe programmatic navigation with NavigationStack and deep links?"
+    why: NavigationStack + typed path + navigationDestination is owned by this skill.
+  - prompt: "My @Observable model glitches the UI when it updates from a background fetch — what's wrong?"
+    why: Non-obvious symptom of off-main mutation of observed state, the #1 footgun.
+
+should_not_trigger:
+  - prompt: "Build the same app for both iOS and Android from one Kotlin codebase."
+    route_to: compose-multiplatform
+    why: Shared KMP/CMP across both OSes, not Apple-native single-platform.
+  - prompt: "Build this mobile app in Flutter with Dart."
+    route_to: flutter
+    why: Different language and ecosystem entirely.
+  - prompt: "Set up EAS Build and OTA updates for my React Native app."
+    route_to: expo
+    why: The React Native / Expo shipping pipeline, not Swift coding.
+  - prompt: "Write the native Android version in Jetpack Compose."
+    route_to: kotlin-android
+    why: Kotlin + Compose + Android side of the language/platform split.
+  - prompt: "Add a GitHub Actions workflow to build and sign my iOS app in CI."
+    route_to: github-actions
+    why: Generic cloud CI/signing process, not in-editor Swift app coding.
+
+capability:
+  - scenario: >
+      A SwiftUI screen has an @Observable model that fetches from the network inside a
+      Task.detached and assigns the result to a published-like property, producing intermittent
+      UI glitches and a Swift 6 data-race warning. Refactor it correctly.
+    must_include:
+      - Identifies that the model must be @MainActor (or rely on default-isolation MainActor) and that the off-main mutation is the bug.
+      - Replaces Task.detached with Task {} or .task {} so the main-actor context is inherited; awaits the async work and lets the mutation land back on main.
+      - Marks any cross-actor value types Sendable (or keeps them main-isolated) and explains the diagnostic.
+      - Uses @Observable (not ObservableObject) and owns the model via @State in the view.
+      - Notes cancellation — .task {} auto-cancels on disappear, or checks Task.isCancelled.

package/skills/shared/swift-ios/references/concurrency.md

@@ -0,0 +1,132 @@
+# Swift 6 strict concurrency — migration & diagnostics
+
+Load this when the user hits data-race diagnostics, is migrating a target to the Swift 6 language mode, or needs `actor`/`Sendable`/`AsyncStream` patterns. The SKILL body covers the common path; this is the depth.
+
+## Enabling the Swift 6 language mode (per target, staged)
+
+Do it one target at a time. Flip language mode globally and you drown in diagnostics with no way to triage.
+
+1. **Stage with upcoming-feature flags first** (still in Swift 5 mode). In Build Settings add `SWIFT_UPCOMING_FEATURE_*` or, in SwiftPM, `.enableUpcomingFeature(...)`. Useful ones: `StrictConcurrency`, `InferSendableFromCaptures`, `DisableOutwardActorInference`. Resolve the warnings these surface.
+2. **Then set `SWIFT_VERSION = 6`** on that target. Remaining warnings become errors.
+3. Repeat per target, leaf modules first.
+
+```swift
+// Package.swift — staged adoption for one target
+.target(
+    name: "Core",
+    swiftSettings: [
+        .enableUpcomingFeature("StrictConcurrency"),
+        .defaultIsolation(MainActor.self)   // SE-0466, see below
+    ]
+)
+```
+
+## SE-0466 default actor isolation + Approachable Concurrency
+
+For UI-centric apps, set **Default Actor Isolation = MainActor** (build setting `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`, or `.defaultIsolation(MainActor.self)` in a SwiftPM target). Unannotated declarations become main-actor-isolated by default — the app is effectively single-threaded until you explicitly opt out with `nonisolated`. This removes the bulk of false-positive data-race warnings.
+
+"Approachable Concurrency" is the umbrella build setting that, alongside this, also flips `InferIsolatedConformances` and `NonisolatedNonsendingByDefault`. Turn it on for new UI apps; turn it off and isolate manually for library code that must stay actor-agnostic.
+
+Opt a hot, pure-compute path back off the main actor:
+
+```swift
+nonisolated func parse(_ data: Data) throws -> Model { /* no UI, no shared state */ }
+```
+
+## The canonical diagnostics
+
+### "Non-Sendable type 'X' crossing actor boundary"
+
+A value that is not safe to share is being passed between isolation domains.
+
+```swift
+// Bad — class with mutable state sent into a Task on another actor
+final class Box { var value = 0 }
+func use(_ b: Box) { Task.detached { print(b.value) } }   // Box is not Sendable
+
+// Good — make it a value type, or an immutable/Sendable type
+struct Box: Sendable { let value: Int }
+```
+
+If the type is genuinely safe but the compiler can't prove it (e.g. it guards its own state with a lock), conform with `@unchecked Sendable` — and only then. `@unchecked` is a promise *you* are now responsible for.
+
+### "Main actor-isolated property cannot be referenced from a nonisolated context"
+
+You touched main-isolated state from somewhere not on the main actor.
+
+```swift
+// Bad
+@MainActor @Observable final class VM { var name = "" }
+func log(_ vm: VM) { print(vm.name) }          // nonisolated function reads main state
+
+// Good — make the access main-isolated, or await it
+@MainActor func log(_ vm: VM) { print(vm.name) }
+// or from async code:
+func log(_ vm: VM) async { print(await vm.name) }
+```
+
+### "Capture of 'self' with non-Sendable type in a `@Sendable` closure"
+
+A `Task.detached`/`@Sendable` closure captured a non-Sendable `self`.
+
+```swift
+// Bad
+func refresh() { Task.detached { await self.reload() } }
+
+// Good — Task {} inherits the actor; self stays on its actor, no crossing
+func refresh() { Task { await self.reload() } }
+```
+
+## `actor` patterns
+
+Use an `actor` for shared mutable state that is **not** UI. Its methods are implicitly async from outside; access is serialized.
+
+```swift
+actor ImageCache {
+    private var store: [URL: Data] = [:]
+    func data(for url: URL) -> Data? { store[url] }
+    func set(_ data: Data, for url: URL) { store[url] = data }
+}
+```
+
+**Reentrancy**: an actor can suspend at an `await` and run another call before the first resumes. Re-check invariants *after* every `await` inside an actor method — do not assume state is unchanged across a suspension point.
+
+## Bridging callbacks with `AsyncStream`
+
+Turn a delegate/callback API into an `AsyncSequence`:
+
+```swift
+func locations() -> AsyncStream<CLLocation> {
+    AsyncStream { continuation in
+        let delegate = LocationDelegate { continuation.yield($0) }
+        continuation.onTermination = { _ in delegate.stop() }
+        delegate.start()
+    }
+}
+// for await loc in locations() { ... }   // ends when the task is cancelled
+```
+
+## Structured parallelism & cancellation
+
+```swift
+// Fan out with async let
+async let a = fetchProfile()
+async let b = fetchPosts()
+let (profile, posts) = try await (a, b)
+
+// Dynamic fan-out with a group, cancellation-aware
+try await withThrowingTaskGroup(of: Item.self) { group in
+    for id in ids { group.addTask { try await fetch(id) } }
+    var out: [Item] = []
+    for try await item in group { out.append(item) }   // throws cancel propagation
+    return out
+}
+
+// In a loop, cooperate with cancellation
+for url in urls {
+    try Task.checkCancellation()
+    _ = try await download(url)
+}
+```
+
+Prefer SwiftUI's `.task {}` for view-lifetime async work — it cancels automatically when the view disappears, so you rarely store a `Task` handle yourself.

package/skills/shared/swift-ios/references/testing.md

@@ -0,0 +1,112 @@
+# Swift Testing — depth
+
+Load this for traits, parameterized matrices, async-event testing, and testing `@MainActor @Observable` models or SwiftData. The SKILL body has the skeleton; this is the rest.
+
+## Suites & traits
+
+A `@Suite` groups tests and can carry traits its tests inherit.
+
+```swift
+@Suite("Checkout", .tags(.payments))
+struct CheckoutTests {
+    @Test(.enabled(if: AppConfig.paymentsEnabled)) func charges() { /* ... */ }
+    @Test(.timeLimit(.minutes(1)))                 func slowPath() async { /* ... */ }
+    @Test(.disabled("flaky on CI — FB12345"))      func legacy() { /* ... */ }
+}
+```
+
+Common traits:
+
+| Trait | Effect |
+| --- | --- |
+| `.tags(.foo)` | Group/filter tests across suites |
+| `.enabled(if:)` / `.disabled(_:)` | Conditional run, with a reason string |
+| `.timeLimit(.minutes(n))` | Fail if the test exceeds the limit |
+| `.serialized` | Run a suite's tests in order, not in parallel |
+| `.bug("URL", "id")` | Link a test to a tracker ticket |
+
+By default tests run **in parallel and in-process**. Mark a suite `.serialized` only when tests share mutable global state you cannot isolate.
+
+## Parameterized matrices
+
+```swift
+// One argument set
+@Test(arguments: [0, 1, 100]) func nonNegative(_ n: Int) { #expect(n >= 0) }
+
+// Two zipped collections (paired, not cartesian)
+@Test(arguments: zip(["a", "bb"], [1, 2]))
+func length(_ s: String, _ len: Int) { #expect(s.count == len) }
+
+// Cartesian product: pass two arguments collections
+@Test(arguments: [1, 2], ["x", "y"])
+func combos(_ n: Int, _ s: String) { /* runs 4 cases */ }
+```
+
+## Async events with `confirmation`
+
+For callback/notification-style work that should fire a known number of times:
+
+```swift
+@Test func emitsThreeEvents() async {
+    await confirmation("got events", expectedCount: 3) { confirm in
+        let stream = makeStream()
+        for await _ in stream.prefix(3) { confirm() }
+    }
+}
+```
+
+WWDC25 additions: **attachments** (attach files/data to a failing test's report) and **exit tests** (assert that a process traps/exits — for testing precondition failures).
+
+## `#expect` vs `#require`
+
+- `#expect(cond)` — soft. Records a failure and keeps running. Use for independent assertions.
+- `try #require(cond)` — hard. Throws and stops the test. Use to unwrap optionals or guard preconditions the rest of the test depends on:
+
+```swift
+let row = try #require(rows.first)   // stop here if empty
+#expect(row.id == 1)
+```
+
+## Testing a `@MainActor @Observable` model
+
+Annotate the test (or suite) `@MainActor` so it shares isolation with the model:
+
+```swift
+@MainActor @Suite struct FeedTests {
+    @Test func loadsItems() async throws {
+        let feed = Feed()
+        try await feed.load()
+        #expect(!feed.items.isEmpty)
+    }
+}
+```
+
+## Testing SwiftData with an in-memory container
+
+Never touch the on-disk store in tests. Build a throwaway container:
+
+```swift
+@MainActor @Test func insertsWorkout() throws {
+    let config = ModelConfiguration(isStoredInMemoryOnly: true)
+    let container = try ModelContainer(for: Workout.self, configurations: config)
+    let context = container.mainContext
+    context.insert(Workout(name: "Run", minutes: 30))
+    let all = try context.fetch(FetchDescriptor<Workout>())
+    #expect(all.count == 1)
+}
+```
+
+## XCTest coexistence / migration
+
+Both frameworks live in the same test target. Migrate logic tests; leave the rest.
+
+| XCTest | Swift Testing | Keep in XCTest? |
+| --- | --- | --- |
+| `XCTAssert`, `XCTAssertEqual` | `#expect(...)` | No — migrate |
+| `XCTUnwrap` | `try #require(...)` | No — migrate |
+| `setUp`/`tearDown` | `init`/`deinit` of the suite type | No — migrate |
+| `XCTestExpectation` | `confirmation { }` | No — migrate |
+| `XCUIApplication` (UI automation) | — | **Yes** — XCTest only |
+| `XCTMetric` / `measure {}` (performance) | — | **Yes** — XCTest only |
+
+Run everything from one command: `xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17'`.

package/skills/shared/swift-ios/scripts/verify.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# verify.sh — advisory copy/practice banlist for Swift / SwiftUI files.
+#
+# Pure text checks: no Xcode, no network, no toolchain. Greps emitted .swift
+# (and Package.swift) for stale or footgun patterns and prints file:line on hits.
+#
+# Read-only. Exits 0 when the target is empty/clean (no false failure), 1 on a hit.
+# Greenfield-oriented and ADVISORY: legacy codebases may legitimately match —
+# review hits, do not treat them as hard errors when working in existing code.
+#
+# Usage:
+#   scripts/verify.sh [PATH ...]
+# Defaults to scanning the current directory if no path is given.
+
+set -euo pipefail
+
+# --- collect targets -------------------------------------------------------
+targets=("$@")
+if [ "${#targets[@]}" -eq 0 ]; then
+  targets=(".")
+fi
+
+tmp_list="$(mktemp)"
+trap 'rm -f "$tmp_list"' EXIT
+for t in "${targets[@]}"; do
+  if [ -d "$t" ]; then
+    find "$t" -type f -name '*.swift' 2>/dev/null >> "$tmp_list"
+  elif [ -f "$t" ] && [ "${t%.swift}" != "$t" ]; then
+    printf '%s\n' "$t" >> "$tmp_list"
+  fi
+done
+
+files=()
+while IFS= read -r f; do
+  [ -n "$f" ] && files+=("$f")
+done < <(sort -u "$tmp_list")
+
+# Empty/clean target -> succeed quietly. No false failure.
+if [ "${#files[@]}" -eq 0 ]; then
+  echo "verify.sh: no .swift files to scan — clean."
+  exit 0
+fi
+
+hits=0
+
+# report PATTERN MESSAGE  (egrep across files, prints file:line)
+report() {
+  local pattern="$1" message="$2"
+  local out
+  out="$(grep -REnH "$pattern" "${files[@]}" 2>/dev/null || true)"
+  if [ -n "$out" ]; then
+    echo "FAIL: $message"
+    printf '%s\n' "$out" | sed 's/^/  /'
+    hits=$((hits + 1))
+  fi
+}
+
+# --- global banlist --------------------------------------------------------
+report ': *ObservableObject\b' "ObservableObject in new code — use @Observable (Observation)."
+report '@Published\b'          "@Published in new code — @Observable tracks properties automatically."
+report 'NavigationView\s*[({]'  "NavigationView is deprecated — use NavigationStack + navigationDestination."
+report '@nonisolated\(unsafe\)' "@nonisolated(unsafe) silences isolation instead of fixing it — make the type Sendable or main-isolated."
+
+# --- per-file contextual checks -------------------------------------------
+for f in "${files[@]}"; do
+  # DispatchQueue.main.async inside a file that declares an @Observable model
+  if grep -q '@Observable' "$f" && grep -nE 'DispatchQueue\.main\.async' "$f" >/dev/null 2>&1; then
+    echo "FAIL: DispatchQueue.main.async inside an @Observable model — annotate the model @MainActor: $f"
+    grep -nE 'DispatchQueue\.main\.async' "$f" | sed 's/^/  /'
+    hits=$((hits + 1))
+  fi
+
+  # XCTAssert* in a file that also uses Swift Testing (@Test)
+  if grep -q '@Test' "$f" && grep -nE 'XCTAssert' "$f" >/dev/null 2>&1; then
+    echo "FAIL: XCTAssert in a Swift Testing file — use #expect / #require: $f"
+    grep -nE 'XCTAssert' "$f" | sed 's/^/  /'
+    hits=$((hits + 1))
+  fi
+
+  # Task.detached without an adjacent justification comment (warn)
+  if grep -nE 'Task\.detached\s*[({]' "$f" >/dev/null 2>&1; then
+    while IFS=: read -r ln _; do
+      prev=$((ln - 1))
+      if [ "$prev" -ge 1 ] && sed -n "${prev}p" "$f" | grep -qE '//.*(justif|reason|why|intentional|detach)'; then
+        continue
+      fi
+      echo "WARN: Task.detached without a justification comment (rarely correct — Task {} inherits actor + priority): $f:$ln"
+    done < <(grep -nE 'Task\.detached\s*[({]' "$f")
+  fi
+done
+
+if [ "$hits" -gt 0 ]; then
+  echo "verify.sh: $hits banlist hit(s). Advisory — review before treating as failures."
+  exit 1
+fi
+
+echo "verify.sh: clean."
+exit 0