@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/storekit/SKILL.md

@@ -1,272 +1,296 @@
 ---
 name: storekit
-description: "Implement, review, or improve in-app purchases and subscriptions using StoreKit 2. Use when building paywalls with SubscriptionStoreView or ProductView, processing transactions with Product and Transaction APIs, verifying entitlements, handling purchase flows (consumable, non-consumable, auto-renewable), implementing offer codes or promotional/win-back/introductory offers, managing subscription status and renewal state, setting up StoreKit testing with configuration files, or integrating Family Sharing, Ask to Buy, refund handling, and billing retry logic."
+description: "StoreKit 2 in-app purchases and subscriptions: SubscriptionStoreView, StoreView and ProductView paywalls, consumable, non-consumable and auto-renewable purchase flows, Product and Transaction APIs, entitlement verification, subscription status and renewal, offer codes, introductory, promotional and win-back offers, configuration file testing, Family Sharing, Ask to Buy, refunds, billing retry. Use when building or reviewing purchase, paywall, entitlement or subscription code. Not for App Store review (app-store-review) or ASO (app-store-optimization)."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# StoreKit 2 In-App Purchases and Subscriptions
-
-Implement in-app purchases, subscriptions, paywalls, and StoreKit testing using
-StoreKit 2 on iOS 26+. Use the modern Swift-based `Product`, `Transaction`,
-`PurchaseAction`, `StoreView`, and `SubscriptionStoreView` APIs. Avoid original
-In-App Purchase APIs (`SKProduct`, `SKPaymentQueue`) unless legacy OS support
-requires them.
-
-When reviewing StoreKit code, explicitly separate "preferred SwiftUI path" from
-"invalid API": `PurchaseAction` is the preferred custom SwiftUI button path, but
-direct `product.purchase(options:)` is still valid for lower-level custom
-StoreKit flows.
-
-Full, copyable code for the core flows lives in
-[references/core-patterns.md](references/core-patterns.md). This guide keeps the
-review guidance and short snippets; load the reference for a complete example.
-
-## Contents
-
-- [Implementation Review Minimums](#implementation-review-minimums)
-- [Product Types](#product-types)
-- [Loading Products](#loading-products)
-- [Purchase Flow](#purchase-flow)
-- [Transaction.updates Listener](#transactionupdates-listener)
-- [Entitlement Checking](#entitlement-checking)
-- [Store Views (SubscriptionStoreView, StoreView, ProductView)](#store-views-subscriptionstoreview-storeview-productview)
-- [Subscription Status Checking](#subscription-status-checking)
-- [Restore Purchases](#restore-purchases)
-- [App Transaction](#app-transaction)
-- [Purchase Options](#purchase-options)
-- [SwiftUI Purchase Callbacks](#swiftui-purchase-callbacks)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+# StoreKit 2
+
+StoreKit 2 is the Swift-native purchase API: `Product` describes what you
+sell, `Transaction` records what the user owns, and SwiftUI supplies
+`PurchaseAction`, `StoreView`, `ProductView` and `SubscriptionStoreView` to
+sell it. This skill targets iOS 26 and names the release where each API
+appeared, because older deployment targets change what you may call.
+
+The original In-App Purchase API (`SKProduct`, `SKPaymentQueue`,
+`SKProductsRequest`) stays out of new code. Use it only when an old OS
+version forces you to.
+
+Two review rules shape everything below:
+
+- Separate "the preferred SwiftUI path" from "an invalid API". For a custom
+  SwiftUI buy button, `PurchaseAction` is preferred; calling
+  `product.purchase(options:)` directly is still correct for flows that need
+  low-level control. Never call the direct call wrong in itself.
+- This file carries the rules and short snippets. Complete code for each core
+  flow is in [references/core-patterns.md](references/core-patterns.md).
+
+Where neighbouring work goes:
+
+| Topic | Skill |
+|-------|-------|
+| Submission readiness, privacy manifests, ATT, metadata, screenshots, rejection audits | `app-store-review` |
+| Keywords, ranking, screenshot captions, conversion strategy | `app-store-optimization` |
+
+In a file that imports SwiftUI, the bare name `Transaction` clashes with
+SwiftUI's animation transaction when used as a type. Write
+`StoreKit.Transaction` there.
 
 ## Implementation Review Minimums
 
-When reviewing a paywall, purchase manager, or entitlement gate, include these
-points explicitly:
-
-- Standard SwiftUI paywalls should prefer `StoreView`, `ProductView`, or
-  `SubscriptionStoreView`; custom SwiftUI buy buttons should prefer
-  `PurchaseAction`; direct `product.purchase(options:)` is valid for
-  lower-level custom StoreKit flows.
-- `Transaction.updates` must start at app launch because it catches purchases
-  from other devices, Family Sharing changes, renewals, Ask to Buy approvals,
-  refunds, revocations, and unfinished transactions.
-- Include this entitlement-scope sentence verbatim when reviewing
-  `Transaction.currentEntitlements`: "It covers non-consumables, active or
-  grace-period auto-renewable subscriptions, and non-renewing subscriptions; it
-  does not include consumable purchase or delivery history."
-- Verify every `VerificationResult` before granting access. Deliver or persist
-  the entitlement first, then call `transaction.finish()`.
-- Pending purchases and user cancellations never unlock content; pending Ask to
-  Buy approvals unlock only after a verified transaction arrives through the
-  launch-time listener.
-- Exclude refunded or revoked transactions from active entitlement state and
-  re-check entitlements when refunds or revocations arrive through
-  `Transaction.updates`.
-- Provide a visible restore purchases path and Terms of Service / Privacy
-  Policy links on subscription paywalls.
+When you review a paywall, a purchase manager or an entitlement gate, say each
+of these out loud, even when the code already gets it right:
+
+1. Standard SwiftUI paywalls use `StoreView`, `ProductView` or
+   `SubscriptionStoreView`; custom SwiftUI buy buttons use `PurchaseAction`.
+2. `Transaction.updates` is iterated from app launch. That is the only place
+   the app hears about purchases made on another device, Family Sharing
+   changes, renewals, Ask to Buy approvals, refunds, revocations and
+   transactions left unfinished last time.
+3. When `Transaction.currentEntitlements` comes up, include this sentence
+   verbatim: "`Transaction.currentEntitlements` covers non-consumables, active
+   or grace-period auto-renewable subscriptions, and non-renewing
+   subscriptions; it does not include consumable purchase or delivery
+   history."
+4. Every `VerificationResult` is checked before access is granted.
+5. Content is delivered or the entitlement persisted first, and only then is
+   `transaction.finish()` called.
+6. A pending purchase or a cancelled one never unlocks anything. A pending Ask
+   to Buy purchase unlocks when the approved, verified transaction arrives on
+   the launch-time listener.
+7. Refunded or revoked transactions are excluded from entitlement state, and
+   entitlements are recomputed when a refund or revocation arrives on
+   `Transaction.updates`.
+8. A subscription paywall shows a restore path and links to Terms of Service
+   and the Privacy Policy.
 
 ## Product Types
 
-| Type | Enum Case | Behavior |
-|---|---|---|
-| **Consumable** | `.consumable` | Used once, can be repurchased (gems, coins) |
-| **Non-consumable** | `.nonConsumable` | Purchased once permanently (premium unlock) |
-| **Auto-renewable** | `.autoRenewable` | Recurring billing with automatic renewal |
-| **Non-renewing** | `.nonRenewing` | Time-limited access without automatic renewal |
+| Kind | `Product.ProductType` | Behaviour | Example |
+|------|----------------------|-----------|---------|
+| Consumable | `.consumable` | used up, can be bought again | hint packs, credits |
+| Non-consumable | `.nonConsumable` | bought once, kept forever | pro unlock |
+| Auto-renewable | `.autoRenewable` | billed on a schedule until cancelled | monthly plan |
+| Non-renewing | `.nonRenewing` | access for a fixed period, no renewal | season pass |
 
 ## Loading Products
 
-Define product IDs as constants. Fetch products with `Product.products(for:)`.
+Keep identifiers in one place and fetch them together:
 
 ```swift
-enum ProductID {
-    static let premium = "com.myapp.premium"
-    static let monthlyPlan = "com.myapp.monthly"
-    static let all: [String] = [premium, monthlyPlan]
+import StoreKit
+
+enum StoreItem {
+    static let proUnlock = "com.example.recipes.pro"
+    static let monthly = "com.example.recipes.monthly"
+    static let annual = "com.example.recipes.annual"
+    static let everything = [proUnlock, monthly, annual]
 }
 
-let products = try await Product.products(for: ProductID.all)
+func loadCatalog() async throws -> [Product] {
+    try await Product.products(for: StoreItem.everything)
+}
 ```
 
 ## Purchase Flow
 
-Prefer StoreKit views for standard paywalls because they initiate purchases,
-restore purchases, and display policy controls. For custom SwiftUI purchase
-buttons, prefer `PurchaseAction` from the environment. Use direct
-`product.purchase(options:)` only for lower-level custom flows, and use
-`purchase(confirmIn:options:)` for UIKit or AppKit confirmation. Always handle
-every `PurchaseResult`, verify before access, deliver durably, then finish.
+Pick the entry point by how much control you need:
 
-Review wording: do not call `product.purchase(options:)` inherently wrong. Say
-"prefer `PurchaseAction` for SwiftUI buttons; keep `product.purchase(options:)`
-for lower-level custom flows that need direct StoreKit control."
+| Need | Use | Since |
+|------|-----|-------|
+| Standard paywall | `StoreView`, `ProductView`, `SubscriptionStoreView`; they buy, restore and show policy links | iOS 17 |
+| Custom SwiftUI button | `@Environment(\.purchase)` (`PurchaseAction`) | iOS 17 |
+| Low-level custom flow | `product.purchase(options:)` | iOS 15 |
+| UIKit or AppKit confirmation sheet | `product.purchase(confirmIn:options:)` | iOS 17 |
 
-Full purchase-flow example with `checkVerified` and `.pending` handling:
-references/core-patterns.md#purchase-flow
+Whatever the entry point, handle every `PurchaseResult` case, verify before
+granting, persist the delivery, then finish. In a review, recommend
+`PurchaseAction` for SwiftUI buttons and leave direct `purchase(options:)` in
+place where the flow genuinely needs it; do not flag it as a bug. The full
+flow with the `verified(_:)` helper and `.pending` handling is at
+[core-patterns.md#buying-with-purchaseaction](references/core-patterns.md#buying-with-purchaseaction).
 
 ## Transaction.updates Listener
 
-Start at app launch, not when a paywall appears. Catches purchases from other
-devices, Family Sharing changes, renewals, Ask to Buy approvals, refunds,
-revocations, and unfinished transactions Apple emits once immediately after
-launch. Keep the task retained for the app lifetime.
+- Start it when the app launches, never when a paywall appears.
+- It delivers other-device purchases, Family Sharing changes, renewals, Ask
+  to Buy approvals, refunds and revocations.
+- Right after launch it also delivers, once, every transaction that was never
+  finished.
+- Keep the task alive for the whole life of the app.
 
-In implementation reviews, name the launch-time coverage explicitly: purchases
-made on other devices, Family Sharing changes, subscription renewals, Ask to Buy
-approvals, refunds, revocations, and unfinished transactions.
-
-Full launch-time listener wired into `App.init`:
-references/core-patterns.md#transactionupdates-listener
+In a review, list those event kinds by name. The listener wired into
+`App.init` is at
+[core-patterns.md#launch-time-transaction-listener](references/core-patterns.md#launch-time-transaction-listener).
 
 ## Entitlement Checking
 
-Use `Transaction.currentEntitlements` for non-consumables, active or grace
-period auto-renewable subscriptions, and non-renewing subscriptions. It excludes
-consumables and consumable delivery history; track consumable fulfillment in
-your own app or server ledger. It also excludes refunded or revoked
-transactions. Use `Transaction.unfinished` for unfinished consumables and
-recovery sweeps. Always check `revocationDate` when processing transactions.
-
-In reviews, include this sentence verbatim: "Transaction.currentEntitlements
-covers non-consumables, active or grace-period auto-renewable subscriptions, and
-non-renewing subscriptions; it does not include consumable purchase or delivery
-history." Do not replace this with only a code sample or a revocation check.
-
-Full `StoreManager.updateEntitlements()` and the `.currentEntitlementTask`
-SwiftUI gate: references/core-patterns.md#entitlement-checking
-
-## Store Views (SubscriptionStoreView, StoreView, ProductView)
-
-`SubscriptionStoreView(groupID:)` is the built-in subscription paywall; it loads
-products, runs the purchase UI, and can expose restore and policy controls.
-`StoreView(ids:)` merchandises multiple products, and `ProductView(id:)` renders
-a single product. All expose `.onInAppPurchaseCompletion` and
+- `Transaction.currentEntitlements` covers non-consumables, active or
+  grace-period auto-renewable subscriptions, and non-renewing subscriptions.
+- It does not contain consumables or their delivery history; record consumable
+  fulfilment in your own ledger, on device or on a server.
+- It leaves out refunded and revoked transactions, but still check
+  `revocationDate` whenever you process a transaction.
+- `Transaction.unfinished` is the sweep for unfinished consumables and
+  recovery.
+- For one product, `Transaction.currentEntitlements(for:)` (iOS 18.4) replaces
+  `Transaction.currentEntitlement(for:)`, deprecated in iOS 18.4.
+
+In a review the verbatim scope sentence from the minimums is required; a code
+sample or a revocation check alone does not replace it. The full
+`refresh()` and the `.currentEntitlementTask` gate are at
+[core-patterns.md#computing-entitlements](references/core-patterns.md#computing-entitlements).
+
+## Store Views
+
+`SubscriptionStoreView(groupID:)` is a complete subscription paywall: it
+loads products, runs the purchase sheet and can show restore and policy
+controls. `StoreView(ids:)` sells several products; `ProductView(id:)` shows
+one. All three are iOS 17 and all accept `.onInAppPurchaseCompletion` and
 `.storeButton(.visible, for: .restorePurchases)`.
 
 ```swift
-SubscriptionStoreView(groupID: "YOUR_GROUP_ID")
-    .storeButton(.visible, for: .restorePurchases)
-    .subscriptionStorePolicyDestination(url: termsURL, for: .termsOfService)
-    .subscriptionStorePolicyDestination(url: privacyURL, for: .privacyPolicy)
+import StoreKit
+import SwiftUI
+
+struct PlanPicker: View {
+    let group: String
+    let terms: URL
+    let privacy: URL
+
+    var body: some View {
+        SubscriptionStoreView(groupID: group)
+            .storeButton(.visible, for: .restorePurchases)
+            .subscriptionStorePolicyDestination(url: terms, for: .termsOfService)
+            .subscriptionStorePolicyDestination(url: privacy, for: .privacyPolicy)
+    }
+}
 ```
 
-Full paywall, custom marketing content, `StoreView`, and `ProductView` examples:
-references/core-patterns.md#subscriptionstoreview and
-references/core-patterns.md#storeview-and-productview
-
-For control styles, hierarchical option layouts, offers, and container
-backgrounds see [references/storekit-advanced.md](references/storekit-advanced.md).
+Complete examples are at
+[core-patterns.md#subscription-paywall](references/core-patterns.md#subscription-paywall)
+and [core-patterns.md#product-shelves-storeview-and-productview](references/core-patterns.md#product-shelves-storeview-and-productview).
+Control styles, grouped layouts, offers and backgrounds are in
+[references/storekit-advanced.md](references/storekit-advanced.md).
 
 ## Subscription Status Checking
 
-Read status with `Product.SubscriptionInfo.status(for: groupID)`; treat
+Read status with `Product.SubscriptionInfo.status(for: groupID)`. Count
 `.subscribed` and `.inGracePeriod` as active.
 
-| State | Meaning |
-|---|---|
-| `.subscribed` | Active subscription |
-| `.expired` | Subscription has expired |
-| `.inBillingRetryPeriod` | Payment failed, Apple is retrying |
-| `.inGracePeriod` | Payment failed but access continues during grace period |
-| `.revoked` | Apple refunded or revoked the subscription |
+| `RenewalState` | Meaning |
+|----------------|---------|
+| `.subscribed` | active |
+| `.expired` | ended |
+| `.inBillingRetryPeriod` | a charge failed and Apple keeps retrying |
+| `.inGracePeriod` | a charge failed, but access continues for the grace window |
+| `.revoked` | refunded or revoked by Apple |
 
-Full status-check helper: references/core-patterns.md#subscription-status-checking.
-For renewal-state access decisions, expiration reasons, grace period, and billing
-retry see [references/storekit-advanced.md](references/storekit-advanced.md).
+The helper is at
+[core-patterns.md#is-a-plan-active](references/core-patterns.md#is-a-plan-active);
+what to grant in each state, expiration reasons, grace period and billing retry
+are in [references/storekit-advanced.md](references/storekit-advanced.md).
 
 ## Restore Purchases
 
-StoreKit 2 handles restoration via `Transaction.currentEntitlements`. Add a
-restore button or call `AppStore.sync()` explicitly.
+In StoreKit 2 there is no separate restore step for data: whatever the user
+owns shows up in `Transaction.currentEntitlements`. Still offer a restore
+control. On a store view use `.storeButton(.visible, for: .restorePurchases)`;
+in custom UI call `AppStore.sync()` and recompute:
 
 ```swift
-func restorePurchases() async throws {
+func restoreTapped(using store: EntitlementStore) async throws {
     try await AppStore.sync()
-    await StoreManager.shared.updateEntitlements()
+    await store.refresh()
 }
 ```
 
-On store views: `.storeButton(.visible, for: .restorePurchases)`
-
 ## App Transaction
 
-Verify the legitimacy of the app installation with `AppTransaction.shared`. Use
-for business model changes or detecting tampered installations (iOS 16+); read
-`originalAppVersion` / `originalPurchaseDate` on the verified result and restrict
-features on `.unverified`.
-
-Full `verifyAppPurchase()` example: references/core-patterns.md#app-transaction
+`AppTransaction.shared` (iOS 16) proves the app install itself is genuine.
+Use it when the business model changes, such as moving from a paid app to a
+subscription while honouring earlier buyers, and to spot tampered installs.
+From the verified value read `originalAppVersion` and `originalPurchaseDate`;
+on `.unverified`, limit features. Full code at
+[core-patterns.md#verifying-the-install-with-apptransaction](references/core-patterns.md#verifying-the-install-with-apptransaction).
 
 ## Purchase Options
 
-```swift
-try await product.purchase(options: [.appAccountToken(UUID())]) // server reconciliation
-try await product.purchase(options: [.quantity(5)])             // consumable quantity
-try await product.purchase(options: [.simulatesAskToBuyInSandbox(true)]) // sandbox
-```
+| Option | Purpose |
+|--------|---------|
+| `.appAccountToken(uuid)` | ties the purchase to your account ID for server reconciliation |
+| `.quantity(n)` | buys several of a consumable |
+| `.simulatesAskToBuyInSandbox(true)` | forces the Ask to Buy flow in sandbox |
 
 ## SwiftUI Purchase Callbacks
 
-Store views expose `.onInAppPurchaseStart`, `.onInAppPurchaseCompletion`, and
-`.inAppPurchaseOptions`. In the completion handler, verify the transaction,
-deliver content, then `finish()`.
-
-Full callback example: references/core-patterns.md#swiftui-purchase-callbacks
+Store views take `.onInAppPurchaseStart`, `.onInAppPurchaseCompletion` and
+`.inAppPurchaseOptions`. In the completion handler: verify, deliver, finish.
+Example at
+[core-patterns.md#store-view-callbacks](references/core-patterns.md#store-view-callbacks).
 
 ## Common Mistakes
 
-The ten most common StoreKit 2 defects, each with a WRONG/CORRECT example, are in
-references/core-patterns.md#common-mistakes:
-
-1. Not starting `Transaction.updates` at app launch
-2. Forgetting `transaction.finish()`
-3. Ignoring the verification result
-4. Using original In-App Purchase APIs in new StoreKit 2 code
-5. Not checking `revocationDate`
-6. Hardcoding prices instead of `product.displayPrice`
-7. Not handling the `.pending` purchase result
-8. Checking entitlements only once at launch
-9. Missing restore purchases button
-10. Subscription views without Terms / Privacy policy links
+Each has a wrong and a right version in
+[core-patterns.md#ten-mistakes-fixed](references/core-patterns.md#ten-mistakes-fixed).
+
+1. No `Transaction.updates` listener at launch.
+2. Never calling `transaction.finish()`.
+3. Ignoring the verification result.
+4. `SKProduct` or `SKPaymentQueue` in new StoreKit 2 code.
+5. Not checking `revocationDate`.
+6. Prices typed into strings instead of `product.displayPrice`.
+7. No handling for `.pending`.
+8. Checking entitlements once at launch and never again.
+9. No restore purchases control.
+10. Subscription screens without Terms and Privacy links.
+
+## Old API to Current API
+
+These replacements are regression facts; flag the left column in review.
+
+| Stale code | Current code | Why |
+|------------|--------------|-----|
+| `Product.SubscriptionInfo.Status.status(for:)` | `Product.SubscriptionInfo.status(for:)` | the former does not exist |
+| `transaction.offerType`, `transaction.offerID` | `transaction.offer?.type`, `transaction.offer?.id` | deprecated in iOS 17.2 |
+| `.promotionalOffer(offerID:signature:)` and `.promotionalOffer(offerID:keyID:nonce:signature:timestamp:)` | `Product.PurchaseOption.promotionalOffer(_:compactJWS:)` | deprecated in iOS 26; the new call returns an array of options |
+| `.subscriptionPromotionalOffer(offer:signature:)` on store views | `.subscriptionPromotionalOffer(offer:compactJWS:)` (iOS 26) | deprecated in iOS 26 |
+| `Transaction.currentEntitlement(for:)` | `Transaction.currentEntitlements(for:)` | deprecated in iOS 18.4 |
+| Showing every `winBackOffers` entry | only entries whose IDs are in the verified `renewalInfo.eligibleWinBackOfferIDs` | the raw list is not per user |
+| `.purchaseDate(_:renewalBehavior: .default)` | `.purchaseDate(_:renewalBehavior:)` with `.renewUntilNow` or `.cancelImmediately`, from `StoreKitTest` | there is no `.default`; the option is test-only |
 
 ## Review Checklist
 
-- [ ] `Transaction.updates` listener starts at app launch in App init
-- [ ] All transactions verified before granting access
-- [ ] `transaction.finish()` called only after durable content delivery
-- [ ] Revoked/refunded transactions excluded and entitlement state updated
-- [ ] `.pending` result shows Ask to Buy/deferred-approval feedback
-- [ ] Restore purchases button visible on paywall and store views
-- [ ] Terms of Service and Privacy Policy links on subscription views
-- [ ] Prices shown using `product.displayPrice`, never hardcoded
-- [ ] Subscription terms (price, duration, renewal) clearly displayed
-- [ ] Free trial states post-trial pricing clearly
-- [ ] No original In-App Purchase APIs (`SKProduct`, `SKPaymentQueue`) unless legacy OS support requires them
-- [ ] Product IDs defined as constants, not scattered strings
-- [ ] StoreKit tests cover promotional offers, win-back, offer codes, Ask to Buy, renewals, refunds, and revocations
-- [ ] Entitlements re-checked on Transaction.updates and app foreground
-- [ ] Server-side validation uses `jwsRepresentation` if applicable
-- [ ] Consumables delivered and finished promptly
-- [ ] Transaction observer types and product model types are `Sendable` when shared across concurrency boundaries
+- [ ] `Transaction.updates` listener starts in the `App` initializer
+- [ ] Every transaction is verified before access
+- [ ] `transaction.finish()` runs only after durable delivery
+- [ ] Revoked and refunded transactions are excluded and entitlements refreshed
+- [ ] `.pending` shows Ask to Buy or deferred-approval feedback
+- [ ] Restore purchases is visible on the paywall and store views
+- [ ] Subscription screens link to Terms of Service and the Privacy Policy
+- [ ] Prices come from `product.displayPrice`
+- [ ] Price, period and renewal terms are clear before purchase
+- [ ] Free-trial copy states what is charged after the trial
+- [ ] No `SKProduct` or `SKPaymentQueue` unless an old OS needs them
+- [ ] Product IDs live in constants
+- [ ] StoreKit tests cover promotional, win-back and code offers, Ask to Buy, renewals, refunds and revocations
+- [ ] Entitlements are recomputed on `Transaction.updates` and when the app returns to the foreground
+- [ ] Server validation, where used, receives `jwsRepresentation`
+- [ ] Consumables are delivered and finished promptly
+- [ ] Types that cross concurrency domains (observers, product models) are `Sendable`
 
 ## References
 
-- See [references/core-patterns.md](references/core-patterns.md) for full core
-  code: purchase flow, launch-time transaction listener, entitlement checking,
-  store views, subscription status, app transaction, purchase callbacks, and the
-  ten annotated common mistakes. Load it when writing or reviewing a core flow.
-- See [references/storekit-advanced.md](references/storekit-advanced.md) for
-  subscription control styles, offer management (introductory, promotional,
-  win-back, offer codes), server-side validation, StoreKit testing, renewal
-  states, grace period/billing retry, refunds, and Family Sharing. Load it for
-  offers, testing setup, or advanced subscription handling.
-- See [references/app-review-guidelines.md](references/app-review-guidelines.md)
-  for IAP rules (Guideline 3.1.1), subscription display requirements, and
-  rejection prevention. Load it before a submission or when diagnosing a payment
-  rejection.
-- For submission, privacy, metadata, screenshots, and rejection-risk audits use `app-store-review`.
-- For keyword, screenshot-caption, ranking, and conversion strategy use `app-store-optimization`.
-- Official Apple docs: [Choosing a StoreKit API](https://sosumi.ai/documentation/storekit/choosing-a-storekit-api-for-in-app-purchases), [Transaction.updates](https://sosumi.ai/documentation/storekit/transaction/updates), [Transaction.currentEntitlements](https://sosumi.ai/documentation/storekit/transaction/currententitlements),
-  [SubscriptionStoreView](https://sosumi.ai/documentation/storekit/subscriptionstoreview), and [PurchaseAction](https://sosumi.ai/documentation/storekit/purchaseaction).
+- [references/core-patterns.md](references/core-patterns.md): load when writing
+  or reviewing a core flow.
+- [references/storekit-advanced.md](references/storekit-advanced.md): offers,
+  test setup, subscription edge cases.
+- [references/app-review-guidelines.md](references/app-review-guidelines.md):
+  before submission or when a payment rejection needs diagnosing (Guideline
+  3.1.1, subscription disclosure, avoiding rejections).
+- Apple: [Choosing a StoreKit API](https://developer.apple.com/documentation/storekit/choosing-a-storekit-api-for-in-app-purchases),
+  [Transaction.updates](https://developer.apple.com/documentation/storekit/transaction/updates),
+  [Transaction.currentEntitlements](https://developer.apple.com/documentation/storekit/transaction/currententitlements),
+  [SubscriptionStoreView](https://developer.apple.com/documentation/storekit/subscriptionstoreview),
+  [PurchaseAction](https://developer.apple.com/documentation/storekit/purchaseaction).

package/pipeline/skills/shared/external/storekit/evals/evals.json

@@ -3,41 +3,44 @@
   "evals": [
     {
       "id": 1,
-      "prompt": "Build a SwiftUI StoreKit 2 paywall for an iOS 26 app with monthly and yearly subscriptions. Include product loading, purchase handling, entitlement checks, restore purchases, transaction updates, and what to do for Ask to Buy or refunds.",
-      "expected_output": "A current StoreKit 2 subscription paywall plan that uses StoreKit views or PurchaseAction, verifies transactions, starts Transaction.updates at launch, handles current entitlements correctly, and exposes restore and policy links.",
+      "name": "ios26-subscription-paywall",
+      "prompt": "Write the StoreKit 2 side of an iOS 26 SwiftUI meditation app that sells a monthly and a yearly plan. I need product loading, buying, entitlement checks, restore, reacting to changes made outside the app, Ask to Buy, and refunds.",
+      "expected_output": "Sells through SubscriptionStoreView, StoreView or a PurchaseAction button as the preferred path instead of only calling product.purchase(options:). Iterates Transaction.updates from app launch in a task that cannot throw, and names what it brings in: renewals, refunds, approvals of Ask to Buy requests, and transactions a previous run never finished. Checks every VerificationResult before granting and finishes only after delivery. Explains the reach of Transaction.currentEntitlements: it lists permanent unlocks, auto-renewing plans that are active or in their grace period, and non-renewing passes, and it keeps no record of consumables. Handles .pending and .userCancelled, removes refunded or revoked access, offers restore, and links Terms of Service and the Privacy Policy on the paywall.",
       "files": [],
-      "assertions": [
-        "Uses `SubscriptionStoreView`, `StoreView`, or SwiftUI `PurchaseAction` as the preferred purchase path instead of defaulting only to `product.purchase(options:)`.",
-        "Starts a `Transaction.updates` listener at app launch using a non-throwing task and notes that updates can deliver Ask to Buy approvals, refunds, renewals, and unfinished transactions.",
-        "Verifies `VerificationResult` before granting access and calls `transaction.finish()` after content delivery.",
-        "Explains that `Transaction.currentEntitlements` covers non-consumables, active or grace-period auto-renewable subscriptions, and non-renewing subscriptions, but not consumable delivery history.",
-        "Handles `.pending`, `.userCancelled`, refunds or revocations, restore purchases, and subscription policy links."
+      "expectations": [
+        "Prefers SubscriptionStoreView, StoreView or PurchaseAction over a bare product.purchase(options:) call",
+        "Starts Transaction.updates at launch in a non-throwing task and says it carries renewals, refunds, Ask to Buy approvals and leftovers from earlier runs",
+        "Checks VerificationResult before granting and calls finish() after delivery",
+        "Explains that currentEntitlements holds permanent unlocks, live or grace-period auto-renewing plans and non-renewing passes, and nothing about consumables",
+        "Covers .pending, .userCancelled, refunds and revocations, restore, and the subscription policy links"
       ]
     },
     {
       "id": 2,
-      "prompt": "Review this StoreKit subscription-offer code plan: use `Product.SubscriptionInfo.Status.status(for:)`, show every `winBackOffers` entry to cancelled users, use `.subscriptionPromotionalOffer(offer: signature:)`, and inspect `transaction.offerType` / `transaction.offerID` on purchase. Correct the API and eligibility mistakes.",
-      "expected_output": "A correction-focused answer that updates stale StoreKit offer APIs, filters win-back offers through renewal eligibility, and verifies applied offers through the current transaction offer model.",
+      "name": "stale-offer-apis",
+      "prompt": "Review this offer code from an older branch: it reads Product.SubscriptionInfo.Status.status(for:) to find the plan state, shows every entry of winBackOffers to anyone who cancelled, applies .subscriptionPromotionalOffer(offer:signature:) on the store view, and logs transaction.offerType and transaction.offerID after purchase. Bring it up to date for iOS 26 and say how to test it.",
+      "expected_output": "Changes Product.SubscriptionInfo.Status.status(for:), which does not exist, to the static Product.SubscriptionInfo.status(for:). Explains that winBackOffers is an unfiltered list and must be narrowed to the IDs in the verified renewalInfo.eligibleWinBackOfferIDs before anything is shown or bought. Moves the store view to the iOS 26 .subscriptionPromotionalOffer(offer:compactJWS:) closures, or keeps signed promotional offers separate as purchase options built with promotionalOffer(_:compactJWS:). Swaps the deprecated offerType and offerID properties for the optional offer property and its type and id. Suggests exercising promotional, win-back and code redemptions, Ask to Buy and renewal states in a StoreKit configuration file or the sandbox.",
       "files": [],
-      "assertions": [
-        "Replaces `Product.SubscriptionInfo.Status.status(for:)` with `Product.SubscriptionInfo.status(for:)`.",
-        "Explains that `product.subscription?.winBackOffers` is a raw list and must be filtered through verified `renewalInfo.eligibleWinBackOfferIDs` before display or purchase.",
-        "Uses the iOS 26 SwiftUI `subscriptionPromotionalOffer` closure plus `compactJWS` closure for StoreKit views, or clearly separates it from lower-level signed purchase options.",
-        "Uses `transaction.offer?.type` and `transaction.offer?.id` instead of stale `transaction.offerType` and `transaction.offerID`.",
-        "Mentions StoreKit configuration or sandbox testing for promotional, win-back, offer code, Ask to Buy, and renewal-state flows."
+      "expectations": [
+        "Uses the static Product.SubscriptionInfo.status(for:) in place of Product.SubscriptionInfo.Status.status(for:)",
+        "Filters winBackOffers through verified renewalInfo.eligibleWinBackOfferIDs and calls showing all of them to every lapsed user wrong",
+        "Uses the iOS 26 subscriptionPromotionalOffer closures with compactJWS, or keeps the signed purchase option path visibly apart",
+        "Replaces offerType and offerID with the offer property (offer?.type, offer?.id)",
+        "Suggests a StoreKit configuration file or the sandbox to exercise promotional, win-back and code offers, Ask to Buy and renewal states"
       ]
     },
     {
       "id": 3,
-      "prompt": "Use StoreKit guidance to review an iOS app that sells premium app features, has a reader-account sign-up link, and also wants App Store keywords and privacy manifest checks. Keep the answer scoped: what belongs in StoreKit, what belongs in App Store Review or ASO, and what IAP compliance caveats should be called out?",
-      "expected_output": "A boundary-aware response that keeps StoreKit focused on IAP implementation, routes broader submission and metadata work to sibling skills, and states current IAP/external-link rules without overclaiming.",
+      "name": "scope-boundaries",
+      "prompt": "Before launch our subscription app needs a privacy manifest, an ATT prompt, new screenshots after a metadata rejection, a keyword refresh for search ranking, and a check that the paywall is compliant. We also link to our website for cheaper annual plans. Which parts are StoreKit work?",
+      "expected_output": "Keeps StoreKit to products, paywalls, purchase flows, verification, restore and entitlements, including the paywall compliance points. Hands the privacy manifest, ATT, the new screenshots, the metadata rejection and overall launch readiness to app-store-review, and keywords, search ranking, captions and conversion to app-store-optimization. Explains that digital features are normally sold through in-app purchase, with room for a present-day exception, a storefront-specific rule or an entitlement Apple has granted. Rejects the idea that any link to the website is an automatic rejection, and notes that reader-app provisions and the storefront decide whether the cheaper-plans link may stay.",
       "files": [],
-      "assertions": [
-        "Keeps StoreKit guidance focused on IAP products, paywalls, purchase flows, transaction verification, restore, and entitlement handling.",
-        "Routes privacy manifests, ATT, screenshot, metadata rejection, and full submission readiness to the `app-store-review` skill.",
-        "Routes keyword strategy, ranking, screenshot-caption optimization, and conversion work to the `app-store-optimization` skill.",
-        "States that digital features generally require IAP unless a current guideline exception, storefront rule, or approved entitlement applies.",
-        "Avoids a blanket claim that all external purchase links are always rejected and instead calls out reader-app and regional or storefront-sensitive rules."
+      "expectations": [
+        "Limits StoreKit to products, paywalls, purchase flows, verification, restore and entitlements",
+        "Hands privacy manifests, ATT, screenshots, metadata rejections and launch readiness to app-store-review",
+        "Hands keywords, ranking, screenshot captions and conversion to app-store-optimization",
+        "Says digital features are normally sold through in-app purchase, with room for a current exception, a storefront rule or a granted entitlement",
+        "Does not treat every external link as an automatic rejection; mentions reader-app and storefront-dependent rules"
       ]
     }
   ]