@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/subscription-billing-ops/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "We're raising prices next quarter. How do we move existing subscribers to the new price without breaking their renewals?",
+    "What should a customer pay if they upgrade from Basic to Pro halfway through their billing month?",
+    "Design a dunning flow for failed renewal payments: how many retries, which emails, and when do we cut access?",
+    "Our MRR movements don't add up from opening to closing balance each month, help me find out why",
+    "Customers on annual plans who cancel mid-year: should we issue a credit note, a refund, or neither?",
+    "Free trial users get charged twice when the trial ends; the conversion job and the renewal job both fire"
+  ],
+  "should_not_trigger": [
+    "Integrate Stripe Checkout in subscription mode and handle the invoice.paid webhook",
+    "What fields does a VAT invoice need for a B2B customer in Germany?",
+    "Push our paid invoices into QuickBooks Online as Payment entities",
+    "Review the billing module diff for rounding bugs and double charges before we merge",
+    "Write a pricing page with three tiers and a monthly/annual toggle"
+  ]
+}

package/skills/subscription-billing-ops/references/proration.md

@@ -0,0 +1,47 @@
+# Proration: formulas, rounding and edge cases
+
+## Formula
+
+For a period `[start, end)` and a change at instant `t` (`start <= t < end`):
+
+```
+remaining_fraction = (end - t) / (end - start)        # seconds, exact rational
+credit_old  = round(old_amount_minor * remaining_fraction)
+charge_new  = round(new_amount_minor * remaining_fraction)
+proration   = charge_new - credit_old                  # may be negative on a downgrade
+```
+
+Keep the fraction exact (integers for numerator and denominator, or a decimal library) and round each line once. Use a decimal type (`numeric` in SQL, `Decimal` in Python, `decimal.js` or `big.js` in JS, `BigDecimal` in Java), never binary floats.
+
+## Rounding rules
+
+- Pick one rule and write it down: half-up (common for invoices) or half-even (banker's). Many tax authorities specify rounding for tax; use theirs for tax lines.
+- Round per line, then sum. Don't round the total separately, or lines won't add up to it.
+- Zero-decimal currencies (JPY, KRW) have no minor unit below 1; three-decimal currencies (BHD, IQD, JOD, KWD, LYD, OMR, TND in the [ISO 4217 list](https://www.six-group.com/en/products-services/financial-information/data-standards.html) as of Sep 2026) have 1000 minor units. Take minor-unit exponents from ISO 4217 data, not a hard-coded 100.
+
+## Worked example
+
+Monthly plan, 30-day period `2026-04-01T00:00Z` to `2026-05-01T00:00Z` (2,592,000 s). Upgrade from 2,000 to 5,000 (minor units) at `2026-04-16T00:00Z`.
+
+```
+remaining = 15 days = 1,296,000 s → fraction 1/2
+credit_old = round(2000 * 1/2) = 1000
+charge_new = round(5000 * 1/2) = 2500
+proration  = 1500 charged now; renewal on 2026-05-01 is 5000
+```
+
+Same change in a 31-day month at the same calendar date gives `16/31` remaining: credit `round(2000*16/31)=round(1032.26)=1032`, charge `round(5000*16/31)=round(2580.65)=2581`, proration `1549`. Customers notice that months differ; say in the docs whether you prorate by seconds of the actual period or by a fixed 30-day month.
+
+## Edge cases to test
+
+| Case | Expected |
+|---|---|
+| Anchor on the 31st | Next boundary is the last day of shorter months, then back to the 31st when it exists; never drift to the 28th permanently |
+| Anchor on 29 Feb (annual) | Pick 28 Feb or 1 Mar in non-leap years; document it |
+| Change exactly at `end` | Belongs to the next period; no proration on the old one |
+| Two changes in one period | Each prorates from its own `t` against the price then in force; sum of lines equals the net change |
+| Upgrade then downgrade same day | Net proration is small but non-zero; credits must not exceed what was charged |
+| DST change in customer timezone | Period length in seconds differs by an hour; compute from instants, display in local time |
+| Proration below the minimum charge amount | Carry it to the next invoice as a pending line instead of charging (cards have minimums per currency) |
+| Discount or coupon active | Prorate the discounted amount, and state whether the coupon itself prorates |
+| Tax-inclusive prices | Prorate the gross, then split tax using the same rule as normal invoices |

package/skills/subscription-billing-ops/references/revenue-metrics.md

@@ -0,0 +1,38 @@
+# Revenue metrics queries
+
+Shapes for a schema with `subscriptions`, `invoices`, `invoice_lines (invoice_id, subscription_id, kind, amount_minor, currency, period_start, period_end)` and `credit_notes`. Adapt names; give each currency its own figures or convert with a dated rate table, never with today's rate for past months.
+
+## MRR at a date
+
+```sql
+-- Recurring lines whose service period covers :as_of, net of discounts, normalised to a month.
+SELECT l.currency,
+       SUM(l.amount_minor * 2629746.0  -- average seconds per month (365.2425 days / 12)
+           / EXTRACT(EPOCH FROM (l.period_end - l.period_start))) AS mrr_minor
+FROM invoice_lines l
+JOIN invoices i ON i.id = l.invoice_id
+WHERE l.kind = 'recurring'
+  AND i.status IN ('open', 'paid')
+  AND l.period_start <= :as_of AND l.period_end > :as_of
+GROUP BY l.currency;
+```
+
+Subtract credit note lines that credit recurring lines in the same period. Decide whether `open` (unpaid, in dunning) counts; many teams exclude invoices past the final dunning attempt.
+
+## MRR movements for a month
+
+For each customer, compare MRR at the start (`m0`) and end (`m1`) of the month:
+
+| Bucket | Rule |
+|---|---|
+| new | `m0 = 0`, `m1 > 0`, first ever paid subscription for the customer |
+| reactivation | `m0 = 0`, `m1 > 0`, customer had MRR before |
+| expansion | `m1 > m0 > 0` |
+| contraction | `0 < m1 < m0` |
+| churn | `m0 > 0`, `m1 = 0` |
+
+Check: `opening + new + reactivation + expansion - contraction - churn = closing`. Group by customer, not subscription, if a plan change creates a new subscription; otherwise every plan change shows as churn plus new.
+
+## Deferred revenue (straight-line)
+
+For each paid recurring line, revenue earned in month `M` is `amount * overlap_seconds(line period, M) / line_period_seconds`. Deferred balance at a date is paid amount minus earned to date. Hand the per-line schedule to finance; recognition policy, contract modifications and multi-element arrangements are their call.

package/skills/svelte-patterns/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: svelte-patterns
+description: Svelte 5 runes and SvelteKit 2 guidance for $state, $derived, $effect and $props reactivity, snippets instead of slots, universal versus server load functions, form actions with use:enhance and fail(), $lib/server and $env/static/private for server-only code, and SSR traps such as shared module state leaking between users. Use when writing or migrating Svelte components to runes, adding SvelteKit routes, loads or actions, or debugging an effect loop or a value that differs between server and browser.
+license: MIT
+compatibility: Any Agent Skills host. Targets Svelte 5 and SvelteKit 2; Svelte 4 syntax is mentioned only for migration. Needs the project's package manager to run svelte-check and tests.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Svelte 5 and SvelteKit patterns
+
+Write runes-based Svelte components and SvelteKit routes that load data on the right side of the network, keep secrets on the server, and render the same on server and client.
+
+## 0. Orient first
+
+1. Read `package.json` for `svelte` and `@sveltejs/kit` versions and the adapter. Svelte 4 projects (`export let`, `$:`, `on:click`, `<slot>`) need different syntax; do not mix styles inside one component.
+2. To migrate, run `npx sv migrate svelte-5` (and `npx sv migrate app-state` for `$app/stores`), then review the diff.
+3. Run `npx svelte-check` before and after your change; it type-checks `.svelte` files and catches rune misuse.
+
+## 1. Runes
+
+```svelte
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  let { items, onselect, children }: { items: Item[]; onselect: (id: string) => void; children?: Snippet } = $props();
+  let query = $state('');
+  let filtered = $derived(items.filter((i) => i.name.includes(query)));
+</script>
+
+<input bind:value={query} />
+{#each filtered as item (item.id)}
+  <button onclick={() => onselect(item.id)}>{item.name}</button>
+{/each}
+{@render children?.()}
+```
+
+- `$state` for anything that changes. Objects and arrays become deep proxies, so `list.push(x)` works. Use `$state.raw` for large data you replace wholesale.
+- `$derived(expr)` or `$derived.by(() => ...)` for computed values. Never compute derived state with `$effect` writing to another `$state`; that causes extra renders and loops.
+- `$effect` only for side effects that talk to the outside (DOM APIs, timers, analytics, a non-Svelte library). Return a cleanup function for anything it starts. It does not run during SSR.
+- An effect that reads and writes the same state loops forever. Read with `untrack(() => x)` (imported from `svelte`) when you must, or restructure into `$derived`.
+- `$props()` replaces `export let`. Props are read-only by default; to bind two-way, mark the prop `$bindable()` and the parent uses `bind:value`.
+- Destructuring a `$state` object into locals takes a snapshot; read `obj.field` where you need it to stay live. Use `$state.snapshot(obj)` when passing state to code that does not expect a proxy (`structuredClone`, external libs).
+- Shared reactive state lives in `.svelte.ts` / `.svelte.js` modules. Export an object or class with `$state` fields, not a reassigned `let`, because importers cannot see a reassignment.
+
+## 2. Components
+
+- Events are props: `onclick={...}`, and components accept callback props (`onselect`) instead of `createEventDispatcher`.
+- Use snippets (`{#snippet row(item)}...{/snippet}` and `{@render row(item)}`) instead of slots in new code. `children` is the default snippet.
+- Key every `{#each}` that can reorder: `{#each items as item (item.id)}`.
+- `{@html}` with user content is XSS. Sanitise first or render as text.
+
+## 3. SvelteKit load functions
+
+| File | Runs | Use for |
+|---|---|---|
+| `+page.ts` / `+layout.ts` | server on first load, then browser | public APIs, data safe to fetch from the browser |
+| `+page.server.ts` / `+layout.server.ts` | server only | database, secrets, private APIs, cookies |
+
+1. Use the `fetch` passed to `load`, not the global one: it forwards cookies, works with relative URLs on the server, and inlines the response so the browser does not refetch.
+2. Return plain serialisable data from server loads (Svelte's `devalue` handles Date, Map, Set; not class instances or functions).
+3. Start independent requests in parallel; do not `await` them one after another. Avoid waterfalls caused by `await parent()` before your own fetches.
+4. Throw expected failures with `error(404, 'Not found')` and send users elsewhere with `redirect(303, '/login')` from `@sveltejs/kit`. In SvelteKit 2 these throw for you; do not wrap them in a `try` that swallows them.
+5. Read the result in the page with `let { data } = $props();`.
+6. Re-run loads with `invalidate(url)` / `invalidateAll()`; declare custom dependencies with `depends('app:cart')`.
+7. Read page and navigation state from `$app/state` (`page.url`, `page.params`, `navigating`), not the deprecated `$app/stores`.
+
+## 4. Form actions
+
+```ts
+// +page.server.ts
+export const actions = {
+  default: async ({ request, locals }) => {
+    const data = await request.formData();
+    const email = String(data.get('email') ?? '');
+    if (!email.includes('@')) return fail(400, { email, missing: true });
+    await locals.db.subscribe(email);
+    redirect(303, '/thanks');
+  },
+};
+```
+
+- Validate every field on the server, return `fail(status, data)` with the values to refill the form, and read them in the page through `let { form } = $props();`.
+- Add `use:enhance` from `$app/forms` for progressive enhancement; the form must still work without JavaScript.
+- Check authorization in the action itself (`locals.user`), not only in the page load.
+- Use named actions (`?/delete`) when one page has several forms.
+
+## 5. Server-only code and secrets
+
+- Put server modules under `src/lib/server/` or name them `*.server.ts`. SvelteKit refuses to bundle them into client code, which turns a leak into a build error.
+- Secrets come from `$env/static/private` (build-time) or `$env/dynamic/private` (runtime). Only `PUBLIC_`-prefixed values belong in `$env/static/public` / `$env/dynamic/public`.
+- Put request-scoped data (current user, db handle) on `event.locals` in `hooks.server.ts`, and type it in `src/app.d.ts`.
+
+## 6. SSR pitfalls
+
+1. **Module-level state is shared by every user on the server.** A `let user = $state(null)` in a module, or a writable store, set during a request leaks to the next visitor. Keep per-request data in `locals` and load data, or create state in a component and share it with `setContext`/`getContext`.
+2. Do not touch `window`, `document` or `localStorage` during render. Use `$effect` or `onMount`, or guard with `browser` from `$app/environment`.
+3. Values that differ by environment (time, random ids, locale) cause hydration mismatches; compute them on the server and pass them through load data.
+4. Turn off SSR per route with `export const ssr = false` only for genuinely browser-only pages; set `export const prerender = true` for static pages.
+
+## 7. Tests
+
+- Unit-test logic in `.svelte.ts` and server modules with Vitest. Test components with `@testing-library/svelte` (`render`, `screen`, user-event) and assert on visible output.
+- Test actions and loads by calling the exported functions with a minimal event object, or end to end with Playwright against `vite preview`.
+
+## Stop and ask the user
+
+- Migrating a large Svelte 4 codebase to runes in one go.
+- Changing the adapter, or the `ssr`/`prerender` setting of a production route.
+- A secret is in a public env var or a client-reachable module.
+
+## Never
+
+- Never import from `$lib/server` or `$env/*/private` in a `+page.ts`, `+layout.ts` or component.
+- Never derive state with `$effect`; use `$derived`.
+- Never keep per-user data in module-level state.
+
+## Report back
+
+List the files changed, which side (server, universal, client) each new load or action runs on, the `svelte-check` and test results, and anything not checked in a browser.

package/skills/svelte-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Migrate this Svelte component from export let and $: to runes",
+    "My $effect keeps re-running forever when I update the counter",
+    "Add a SvelteKit form action for the newsletter signup with server validation",
+    "Should this SvelteKit load go in +page.ts or +page.server.ts? It reads the database",
+    "One user's cart is showing up for another user in our SvelteKit app"
+  ],
+  "should_not_trigger": [
+    "Add a Nuxt server route that returns the product list",
+    "Write a Vue 3 Pinia store for the shopping cart",
+    "Set up an Angular reactive form with typed controls",
+    "Write Playwright tests that click through the signup flow in the browser",
+    "Audit the signup page for screen reader accessibility"
+  ]
+}

package/skills/swift-patterns/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: swift-patterns
+description: Idiomatic Swift 5.x and 6 for writing or restructuring code, covering structs and enums over classes, protocols with associated types and some/any, optional handling without force unwraps, typed and untyped throws, async/await, actors, Sendable and strict concurrency checking, plus Package.swift layout for SwiftPM. Use when writing new Swift code, choosing between a struct, class or actor, adopting async/await, migrating a module to the Swift 6 language mode, or setting up a Swift package.
+license: MIT
+compatibility: Any Agent Skills host. Needs a Swift 5.9+ toolchain (swift or xcodebuild) to build and check the code. Swift 6.2 features are marked as such.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/requires: "swift"
+  kete-loom/owner: "Kete-org"
+---
+
+# Swift patterns
+
+Write Swift that the compiler can check: value semantics by default, isolation stated explicitly, failure in the type system. This skill is for language-level code. SwiftUI view structure belongs to `swiftui-patterns`; tests belong to `swift-testing`.
+
+## 0. Before you write
+
+1. Find the toolchain and mode: `swift --version`, the `// swift-tools-version:` line in `Package.swift`, or `SWIFT_VERSION` in the Xcode build settings. Tools version 6.0+ defaults to the Swift 6 language mode unless `swiftLanguageModes: [.v5]` (or a target's `.swiftLanguageMode(.v5)`) says otherwise.
+2. Check the concurrency settings: `SWIFT_STRICT_CONCURRENCY`, `SWIFT_DEFAULT_ACTOR_ISOLATION` and `SWIFT_APPROACHABLE_CONCURRENCY` in Xcode, or `swiftSettings` in `Package.swift`. Code that compiles in one setting may not in another, so match the project.
+3. Read two or three neighbouring files and follow their conventions (naming, error types, logging, file layout).
+
+## 1. Pick the type
+
+| Need | Use |
+|---|---|
+| Data with no identity, copied freely | `struct` |
+| A closed set of states or results | `enum` with associated values |
+| Shared mutable state accessed from several tasks | `actor` |
+| UI state or anything touching UIKit/AppKit | a `@MainActor` class or the main-actor default |
+| Identity, inheritance, or Objective-C interop | `final class` (drop `final` only when you need subclassing) |
+
+- Prefer `let`. Make a stored property `var` only when something mutates it.
+- Model impossible states out: `enum LoadState { case idle, loading, loaded(User), failed(Error) }` beats three optionals and a Bool.
+- Large value types with copy-on-write storage are fine; don't convert a struct to a class "for performance" without a measurement.
+
+## 2. Protocols and generics
+
+- Write protocols for capabilities your code needs (`protocol UserStore { func user(id: User.ID) async throws -> User }`), not mirrors of one concrete class.
+- Use `some Protocol` for parameters and return types when one concrete type flows through. Use `any Protocol` only when you need heterogeneous storage or runtime swapping; it costs an existential box.
+- Protocols with `associatedtype` work with `some`, generics and primary associated types (`some Collection<Int>`). Reach for a hand-written type eraser only when `any P<T>` cannot express it.
+- Put shared behaviour in protocol extensions, but remember extension-only methods are statically dispatched: a conforming type cannot override them unless the method is also a requirement.
+
+## 3. Optionals
+
+- Unwrap with `guard let x else { return }` (Swift 5.7 shorthand), `if let`, `??` with a real default, or optional chaining.
+- Never write `!` on a value that comes from input, the network, a dictionary lookup, `first`, a cast or a file. Force unwrap only an invariant visible on the same line, such as `URL(string: "https://example.com")!` on a string literal.
+- No implicitly unwrapped optionals (`var x: T!`) outside `@IBOutlet` and two-phase init you cannot restructure.
+- `try?` throws the error away. Use it only when "no value" is genuinely the same outcome as "failed".
+
+## 4. Errors
+
+- Throw a domain `enum` conforming to `Error` (and `LocalizedError` if users see it). Include the associated data a caller needs to react.
+- Swift 6 typed throws (`func parse() throws(ParseError)`) suit closed, internal error sets and embedded code. For public APIs that will grow new failures, keep plain `throws`.
+- Catch where you can do something: retry, map to a user message, or fall back. Otherwise let it propagate. An empty `catch {}` is a bug.
+- Use `Result` for stored or callback-delivered outcomes; for async code, `async throws` replaces it.
+- `fatalError`, `precondition` and `!` crash release builds. Reserve them for programmer errors, never for bad input.
+
+## 5. Concurrency
+
+1. Make functions `async` instead of taking completion handlers. Wrap a legacy callback API once with `withCheckedThrowingContinuation` and resume exactly once on every path.
+2. Use structured concurrency first: `async let` for a fixed number of child tasks, `withThrowingTaskGroup` for a dynamic number. They cancel children and propagate errors.
+3. Use `Task { }` only at the boundary where sync code starts async work (a button action, `viewDidLoad`). Keep the handle if the work must be cancelled. `Task.detached` is almost never right; it drops priority, task-locals and actor context.
+4. Protect shared mutable state with an `actor`. Remember actor reentrancy: state can change across every `await` inside an actor method, so re-check invariants after each suspension.
+5. Mark UI-facing types `@MainActor`. Don't sprinkle `DispatchQueue.main.async` in new async code.
+6. Check `Task.isCancelled` or call `try Task.checkCancellation()` in long loops.
+7. In Swift 6.2 with `NonisolatedNonsendingByDefault`, a `nonisolated async` function runs on the caller's actor. Mark CPU-heavy work `@concurrent` to move it off the caller.
+
+### Sendable rules
+
+- A type crossing an isolation boundary must be `Sendable`. Structs and enums whose stored properties are all `Sendable` get it implicitly when not public; state it explicitly on public types.
+- A class is `Sendable` only if it is `final` with immutable `let` stored properties of `Sendable` types, or it is actor-isolated.
+- `@unchecked Sendable` is a promise you protect the state yourself (for example with a `Mutex` from the `Synchronization` module, Swift 6 and macOS 15 / iOS 18 or later, or a lock such as `OSAllocatedUnfairLock` or `NSLock`). Write the reason in a comment next to it.
+- `nonisolated(unsafe)` and `@preconcurrency import` are migration tools. Each use needs a comment saying why and when it goes away.
+
+For migrating a module to complete checking or the Swift 6 mode, read `references/concurrency-migration.md`.
+
+## 6. SwiftPM
+
+- One `Package.swift` with explicit `products`, `targets` and `dependencies`. Pin remote packages with `from:` (semver) and commit `Package.resolved` for apps and executables. A library's `Package.resolved` is ignored by packages that depend on it, so its version ranges must be correct on their own.
+- Keep the core logic in a library target with no UIKit/SwiftUI imports so it builds and tests on any platform with `swift build` and `swift test`.
+- Put per-target flags in `swiftSettings`, for example:
+
+```swift
+.target(
+    name: "Core",
+    swiftSettings: [
+        .enableUpcomingFeature("ExistentialAny"),
+        // Swift 5 mode only; Swift 6 mode already enforces complete checking.
+        .enableUpcomingFeature("StrictConcurrency"),
+    ]
+)
+```
+
+- Use `package` access (Swift 5.9+) for symbols shared between targets of one package, and access levels on imports (`internal import Foo`, Swift 6) to stop a dependency leaking into your public API.
+
+## 7. Check your work
+
+1. Build with the project's command (`swift build`, or `xcodebuild -scheme <Scheme> build`). Zero new warnings, not just zero errors.
+2. If the project is still in Swift 5 mode, also build once with `swift build -Xswiftc -strict-concurrency=complete` and report new concurrency warnings rather than hiding them.
+3. Run the tests (`swift test` or `xcodebuild test`).
+
+## Never
+
+- Never silence a concurrency diagnostic with `@unchecked Sendable`, `nonisolated(unsafe)` or `@preconcurrency` without the comment described above. If the honest fix is a redesign, **stop and ask the user**.
+- Never lower the language mode or strict-concurrency level to make code compile without telling the user.
+- Never block a thread waiting on async work (semaphores, `DispatchGroup.wait`) inside an async context; it can deadlock the cooperative pool.
+- Never capture `self` strongly in a long-lived escaping closure stored on `self` (timers, observers, stored callbacks). Use `[weak self]` there.
+
+## Report back
+
+End with: the files changed, the build and test commands you ran with their result, any new `@unchecked Sendable`, `nonisolated(unsafe)` or force unwraps you added and why, and anything you left for the user to decide.

package/skills/swift-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Should this cache be a class, a struct or an actor in Swift?",
+    "Convert these completion-handler network calls in my Swift package to async/await",
+    "Help me design a Swift protocol with an associated type for our repository layer",
+    "We want to move our iOS app's core module to the Swift 6 language mode, where do we start?",
+    "Set up a new Package.swift with a library target and an executable target"
+  ],
+  "should_not_trigger": [
+    "Write Swift Testing tests with #expect for the PriceCalculator struct",
+    "Review this Swift pull request for retain cycles and force unwraps",
+    "Xcode build fails with 'sending value of non-Sendable type' after upgrading, fix it",
+    "Build a SwiftUI settings screen with a NavigationStack and a Form",
+    "Write idiomatic Kotlin coroutines for this Android repository class"
+  ]
+}

package/skills/swift-patterns/references/concurrency-migration.md

@@ -0,0 +1,40 @@
+# Migrating a module to complete concurrency checking
+
+Move one target at a time, leaf modules first. Each step should build cleanly before the next.
+
+## Steps
+
+1. **Measure.** Build once with complete checking and count the diagnostics:
+   - SwiftPM: `swift build -Xswiftc -strict-concurrency=complete 2>&1 | grep -c "warning:"`
+   - Xcode: set `SWIFT_STRICT_CONCURRENCY = complete` for the target, build, read the Issue navigator.
+2. **Turn it on per target in Swift 5 mode** so diagnostics are warnings, not errors:
+   - SwiftPM: `swiftSettings: [.enableUpcomingFeature("StrictConcurrency")]` (on 5.9 toolchains use `.enableExperimentalFeature("StrictConcurrency")`).
+   - Xcode: `SWIFT_STRICT_CONCURRENCY = complete`.
+3. **Fix in this order**, because each step removes many downstream warnings:
+   1. Isolate UI code: add `@MainActor` to view controllers, view models and delegates that touch UIKit/AppKit.
+   2. Make plain data types `Sendable` (usually just adding the conformance to structs and enums).
+   3. Turn classes that guard state with a queue or lock into actors, or keep the lock and mark them `@unchecked Sendable` with a comment.
+   4. Replace global and static `var`s: make them `let`, isolate them to `@MainActor`, or move them into an actor.
+   5. Handle third-party modules that are not yet annotated with `@preconcurrency import Module`, and note it for removal.
+4. **Switch the language mode** once the target has no concurrency warnings:
+   - SwiftPM: `// swift-tools-version:6.0` (or later) and drop any `.swiftLanguageMode(.v5)` on that target.
+   - Xcode: `SWIFT_VERSION = 6.0`.
+5. Run the full test suite. Data-race fixes can change ordering; flaky tests after migration usually point at a real race.
+
+## Common diagnostics and the usual fix
+
+| Diagnostic (paraphrased) | Usual fix |
+|---|---|
+| Static property is not concurrency-safe because it is nonisolated global shared mutable state | Make it `let` of a `Sendable` type, or isolate it with `@MainActor` |
+| Sending value of non-Sendable type risks causing data races | Make the type `Sendable`, or stop sending it across the boundary (create it inside the task) |
+| Capture of non-Sendable type in a `@Sendable` closure | Capture a `Sendable` copy (a value or an ID) instead of the object |
+| Call to main actor-isolated method in a synchronous nonisolated context | Mark the caller `@MainActor`, or make it `async` and `await` the call |
+| Main actor-isolated property cannot be used to satisfy nonisolated protocol requirement | Isolate the conformance (`extension V: @MainActor P`, Swift 6.2) or make the member `nonisolated` if it touches no isolated state |
+| Passing closure as a 'sending' parameter risks causing data races | Avoid capturing mutable non-Sendable state; copy what the closure needs first |
+
+## Swift 6.2 options
+
+- `.defaultIsolation(MainActor.self)` in a target's `swiftSettings` (Xcode: `SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor`) makes unannotated code main-actor isolated. Good for app targets; usually wrong for libraries and networking or model packages. Mark background-safe types `nonisolated`.
+- `.enableUpcomingFeature("NonisolatedNonsendingByDefault")` makes `nonisolated async` functions run on the caller's actor. Use `@concurrent` for work that must leave it.
+- `.enableUpcomingFeature("InferIsolatedConformances")` lets a main-actor type's protocol conformance be inferred as main-actor isolated.
+- Xcode's `SWIFT_APPROACHABLE_CONCURRENCY = YES` turns on a bundle of these upcoming features. New Xcode 26 app templates may enable it and main-actor default isolation; SwiftPM packages do not, so the same code can behave differently in an app target and a package. Check each target.

package/skills/swift-testing/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: swift-testing
+description: Writes and fixes Swift unit, async and UI tests using Apple's Swift Testing framework (@Test, @Suite, #expect, #require, parameterized arguments, confirmation) alongside XCTest, with protocol-based fakes injected through initializers instead of mocking frameworks, and XCUITest basics for UI flows. Use when adding tests to a Swift package or Xcode project, testing async or actor code, replacing a live network or database dependency with a fake, converting XCTestCase classes to Swift Testing, or fixing a flaky Swift test.
+license: MIT
+compatibility: Any Agent Skills host. Swift Testing needs a Swift 6 toolchain or Xcode 16+; XCTest works with any Xcode. UI tests need Xcode and a simulator on macOS.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "swift"
+  kete-loom/owner: "Kete-org"
+---
+
+# Swift testing
+
+Write Swift tests that are fast, deterministic and run in parallel. Use Swift Testing for new unit and integration tests, XCTest where the project or the feature requires it (UI tests, performance tests, older toolchains).
+
+## 0. Before you start
+
+1. Find how tests run here: `swift test` for a package, or `xcodebuild test -scheme <Scheme> -destination '<destination>'` for an Xcode project (`xcodebuild -list` shows schemes; `xcrun simctl list devices available` shows simulators). Check CI config for the exact command.
+2. Run the existing suite once and record the result. If it already fails, **stop and tell the user** before changing anything.
+3. Check which framework the target already uses (`import Testing` or `import XCTest`). Both can live in one test target; don't convert existing XCTest files unless asked.
+
+## 1. Choose the framework
+
+| Test | Use |
+|---|---|
+| New unit or integration test, Swift 6 toolchain | Swift Testing |
+| UI automation (`XCUIApplication`) | XCTest only |
+| Performance (`measure { }`, `XCTMetric`) | XCTest only |
+| Toolchain older than Swift 6 / Xcode 16 | XCTest |
+| Existing XCTest file you are extending | Match the file |
+
+## 2. Swift Testing essentials
+
+```swift
+import Testing
+@testable import Core
+
+@Suite struct PriceCalculatorTests {
+    let calculator = PriceCalculator(taxRate: 0.15)   // fresh instance per test
+
+    @Test func addsTax() {
+        #expect(calculator.total(for: 100) == 115)
+    }
+
+    @Test(arguments: [0, -1, .max])
+    func rejectsInvalidAmounts(_ amount: Int) {
+        #expect(throws: PriceError.self) { try calculator.validate(amount) }
+    }
+
+    @Test func parsesFirstLine() throws {
+        let line = try #require(calculator.lines.first)   // stops the test if nil
+        #expect(line.amount > 0)
+    }
+}
+```
+
+- `#expect` records a failure and continues; `#require` throws and stops. Use `#require` to unwrap optionals instead of `!`.
+- Each `@Test` gets a new suite instance, so `init` replaces `setUp` and `deinit` (in a class or actor suite) replaces `tearDown`.
+- Prefer `@Test(arguments:)` over loops: each argument is reported and re-runnable on its own. Arguments must be `Sendable`.
+- Tests run in parallel by default. Add `.serialized` to a suite only when tests share an external resource you cannot isolate, and say why.
+- Use traits instead of comments: `.disabled("reason")`, `.enabled(if: ...)`, `.bug("url")`, `.tags(.networking)`, `.timeLimit(.minutes(1))`. For a known bug, wrap the failing check in `withKnownIssue { }` rather than deleting it.
+
+For an XCTest-to-Swift-Testing mapping table and more examples, read `references/swift-testing-cheatsheet.md`.
+
+## 3. Async and actor code
+
+1. Mark the test `async throws` and `await` the call directly. Never sleep to wait for work.
+2. For callbacks or delegate events, use `await confirmation(expectedCount: n) { confirm in ... }` in Swift Testing, or `XCTestExpectation` plus `await fulfillment(of: [exp], timeout: 2)` in async XCTest (not `wait(for:)`, which blocks).
+3. For code isolated to the main actor, mark the test or suite `@MainActor`.
+4. Control time: inject a clock (`any Clock<Duration>`) or a `now: () -> Date` closure instead of reading `Date()` or calling `Task.sleep` directly in production code.
+5. Test cancellation explicitly when the code promises to honour it: start a `Task`, cancel it, assert the `CancellationError` or the cleanup.
+
+## 4. Fakes through protocols
+
+1. Find the dependency that makes the test slow or non-deterministic: network, database, file system, clock, randomness, keychain.
+2. Define a small protocol for what the code under test needs, if one does not exist.
+3. Inject it through the initializer with the live type as default only if the codebase already does that.
+4. Write a fake in the test target: a struct or actor that returns canned values and records calls.
+
+```swift
+protocol UserStore: Sendable { func user(id: String) async throws -> User }
+
+actor FakeUserStore: UserStore {
+    var result: Result<User, Error>
+    private(set) var requestedIDs: [String] = []
+    init(_ result: Result<User, Error>) { self.result = result }
+    func user(id: String) async throws -> User {
+        requestedIDs.append(id)
+        return try result.get()
+    }
+}
+```
+
+- Fake only boundaries. Never fake the type under test, and don't fake value types; construct real ones.
+- For `URLSession`, prefer injecting a protocol over subclassing; a custom `URLProtocol` registered on a `URLSessionConfiguration` is the fallback when you must test real request building.
+
+## 5. UI test basics (XCTest)
+
+1. Give elements stable `accessibilityIdentifier`s in the app; query by identifier, not by label text.
+2. Launch with test configuration: `app.launchArguments += ["-ui-testing"]` and `app.launchEnvironment["API_BASE_URL"] = ...`, and have the app swap in fakes when it sees them.
+3. Wait with `element.waitForExistence(timeout: 5)`; never `sleep`.
+4. Keep UI tests to a few critical journeys. Logic belongs in unit tests.
+
+## 6. Run and check
+
+1. Run the single test first: `swift test --filter PriceCalculatorTests/addsTax` or `xcodebuild test -only-testing:<Target>/<Suite>/<test>`.
+2. Then the whole target. Then the full suite.
+3. For a flaky test, run it repeatedly (`swift test --filter <name>` in a loop, or Xcode's run-repeatedly option) and fix the cause (shared state, real time, ordering) rather than adding retries.
+
+## Never
+
+- Never delete, skip or weaken an existing assertion to get green. If a test is wrong, explain why and get the user's agreement.
+- Never hit the real network, real keychain or a shared simulator state in unit tests.
+- Never use `sleep`, `Task.sleep` or fixed delays to wait for asynchronous results.
+- Never add `.serialized` or disable parallel testing to hide a data race.
+
+## Report back
+
+End with: tests added or changed (names), the exact command you ran, pass/fail counts, any fakes or protocols you introduced, and anything left untested.

package/skills/swift-testing/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Add Swift Testing tests with #expect for the CartTotals struct",
+    "How do I test an actor method that's async in Swift?",
+    "Replace the real API client with a fake so my XCTest cases stop hitting the network",
+    "Convert our XCTestCase classes to the new @Test macro style",
+    "My iOS unit test is flaky because of a Task.sleep, how do I make it deterministic?"
+  ],
+  "should_not_trigger": [
+    "Refactor this Swift networking layer to use async/await and actors",
+    "Review my Swift changes for main-thread UI violations",
+    "swift test won't even compile, SwiftPM can't resolve the package graph",
+    "Write Playwright end-to-end tests for the web checkout flow",
+    "Write Kotlin unit tests with JUnit 5 and MockK for the Android repository"
+  ]
+}

package/skills/swift-testing/references/swift-testing-cheatsheet.md

@@ -0,0 +1,81 @@
+# Swift Testing cheatsheet
+
+## XCTest to Swift Testing
+
+| XCTest | Swift Testing |
+|---|---|
+| `class FooTests: XCTestCase` | `@Suite struct FooTests` (the `@Suite` attribute is optional) |
+| `func testBar()` | `@Test func bar()` |
+| `setUp()` / `tearDown()` | `init()` / `deinit` (class or actor suite) |
+| `XCTAssertEqual(a, b)` | `#expect(a == b)` |
+| `XCTAssertTrue(x)` / `XCTAssertFalse(x)` | `#expect(x)` / `#expect(!x)` |
+| `XCTAssertNil(x)` | `#expect(x == nil)` |
+| `let y = try XCTUnwrap(x)` | `let y = try #require(x)` |
+| `XCTAssertThrowsError(try f())` | `#expect(throws: (any Error).self) { try f() }` |
+| `XCTAssertThrowsError` with a specific error | `#expect(throws: MyError.notFound) { try f() }` (error must be `Equatable`) |
+| `XCTAssertNoThrow(try f())` | `#expect(throws: Never.self) { try f() }` |
+| `XCTFail("msg")` | `Issue.record("msg")` |
+| `XCTSkip` | `.enabled(if:)` / `.disabled(_:)` trait |
+| `XCTExpectFailure` | `withKnownIssue { }` |
+| `XCTestExpectation` + `fulfillment(of:)` | `await confirmation { confirm in ... }` (the event must happen before the closure returns) |
+
+Keep these in XCTest: `XCUIApplication` UI tests, `measure { }` performance tests, and anything that needs `XCTestCase` subclass hooks.
+
+## Examples
+
+Parameterized over two collections, paired rather than a cartesian product:
+
+```swift
+@Test(arguments: zip(["1", "42", "-7"], [1, 42, -7]))
+func parsesIntegers(input: String, expected: Int) throws {
+    #expect(try Parser.int(input) == expected)
+}
+```
+
+Counting events:
+
+```swift
+@Test func notifiesOncePerSave() async throws {
+    let store = DocumentStore()
+    try await confirmation(expectedCount: 2) { saved in
+        store.onSave = { _ in saved() }
+        try await store.save("a")
+        try await store.save("b")
+    }
+}
+```
+
+Tags for filtering:
+
+```swift
+extension Tag { @Tag static var integration: Self }
+
+@Test(.tags(.integration)) func syncsWithServer() async throws { ... }
+```
+
+Run a subset: `swift test --filter <regex>` matches suite and test names. Swift Testing and XCTest tests in one package both run under `swift test`.
+
+## Main-actor tests
+
+```swift
+@MainActor @Suite struct ProfileViewModelTests {
+    @Test func loadsProfile() async throws {
+        let model = ProfileViewModel(store: FakeUserStore(.success(.fixture)))
+        await model.load()
+        #expect(model.state == .loaded(.fixture))
+    }
+}
+```
+
+## Async XCTest
+
+```swift
+final class LegacyTests: XCTestCase {
+    func testDelegateCalled() async {
+        let exp = expectation(description: "delegate")
+        let sut = Uploader(onFinish: { exp.fulfill() })
+        sut.start()
+        await fulfillment(of: [exp], timeout: 2)
+    }
+}
+```