@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/storekit/references/storekit-advanced.md

@@ -2,6 +2,8 @@
 
 Covers subscription control styles, offer management, testing, server-side
 validation, and advanced subscription handling patterns for StoreKit 2.
+Use this after the core purchase, transaction listener, and entitlement patterns
+from the top-level StoreKit skill are in place.
 
 ## Contents
 
@@ -55,7 +57,9 @@ Apply control styles to change how subscription options render in
 
 ### Control Placement
 
-Specify where controls appear within the view:
+Specify where controls appear within the view. Not every placement is supported
+by every control style, so let unsupported combinations fall back to the system
+default instead of assuming exact placement on every platform.
 
 ```swift
 .subscriptionStoreControlStyle(.picker, placement: .bottom)
@@ -139,6 +143,9 @@ Control what information subscription buttons display:
 
 ## Subscription Group Management
 
+The option hierarchy helper views in this section are iOS 18+ APIs for
+organizing subscription choices inside `SubscriptionStoreView`.
+
 ### Hierarchical Layouts with SubscriptionOptionGroup
 
 ```swift
@@ -191,17 +198,10 @@ SubscriptionStoreView(groupID: "group_id", visibleRelationships: .upgrade)
 
 ### Custom Subscription Store Controls
 
-```swift
-// Custom button for a specific subscription option
-SubscriptionStoreButton(option)
-
-// Custom picker with confirmation
-SubscriptionStorePicker(pickerContent: { option in
-    Text(option.displayName)
-}, confirmation: { selectedOption in
-    Text("Subscribe to \(selectedOption.displayName)")
-})
-```
+`SubscriptionStoreButton`, `SubscriptionStorePicker`,
+`SubscriptionOptionGroup`, and related option controls are supported inside a
+custom `SubscriptionStoreControlStyle.makeBody(configuration:)`. Do not place
+them as arbitrary standalone content outside a custom control style.
 
 ## Introductory Offers
 
@@ -274,8 +274,19 @@ let result = try await product.purchase(options: [
 
 ### SwiftUI Automatic Promotional Offer
 
+For StoreKit SwiftUI views on iOS 26+, provide the offer and the compact JWS
+signature asynchronously:
+
 ```swift
-.subscriptionPromotionalOffer(offer: promoOffer, signature: signature)
+.subscriptionPromotionalOffer { product, subscription in
+    subscription.promotionalOffers.first
+} compactJWS: { product, subscription, offer in
+    guard let offerID = offer.id else { throw StoreError.invalidOffer }
+    return try await offerSigner.compactJWS(
+        productID: product.id,
+        offerID: offerID
+    )
+}
 ```
 
 ### Preferred Offer Selection
@@ -299,14 +310,25 @@ Target former subscribers who cancelled. Available since iOS 18.
 let winBackOffers = product.subscription?.winBackOffers ?? []
 ```
 
+`winBackOffers` is the raw offer list for the product. Filter it through
+`renewalInfo.eligibleWinBackOfferIDs` before showing or applying offers.
+
 ### Checking Eligibility via Renewal Info
 
 ```swift
-let statuses = try await Product.SubscriptionInfo.Status.status(for: groupID)
-for status in statuses {
-    guard case .verified(let renewalInfo) = status.renewalInfo else { continue }
-    let eligibleIDs = renewalInfo.eligibleWinBackOfferIDs
-    // Display offers matching these IDs
+let statuses = try await Product.SubscriptionInfo.status(for: groupID)
+let eligibleOfferIDs = statuses.flatMap { status -> [String] in
+    guard case .verified(let renewalInfo) = status.renewalInfo else { return [] }
+    return renewalInfo.eligibleWinBackOfferIDs
+}
+
+let offersByID = Dictionary(uniqueKeysWithValues: winBackOffers.compactMap { offer in
+    offer.id.map { ($0, offer) }
+})
+
+let eligibleWinBackOffers = eligibleOfferIDs.compactMap { offersByID[$0] }
+for offer in eligibleWinBackOffers {
+    // Display or apply only eligible offers.
 }
 ```
 
@@ -344,17 +366,33 @@ var body: some View {
 .storeButton(.visible, for: .redeemCode)
 ```
 
+### Testing Offer Codes
+
+Test offer-code redemption in StoreKit configuration files and sandbox. In
+StoreKit testing, use the configured offer-code reference name:
+
+```swift
+try await product.purchase(options: [.codeOffer(referenceName: "SUMMER2024")])
+```
+
+Also test the user-facing redemption path with `.storeButton(.visible, for:
+.redeemCode)` or `.offerCodeRedemption(isPresented:)`, then verify the resulting
+transaction uses `transaction.offer?.type == .code` and the expected
+`transaction.offer?.id`.
+
 ### Verifying Applied Offers in Transactions
 
 ```swift
-if let offerType = transaction.offerType {
-    switch offerType {
+if let offer = transaction.offer {
+    switch offer.type {
     case .introductory: break  // Introductory offer applied
-    case .promotional: break   // Check transaction.offerID
+    case .promotional: break   // Promotional offer applied
     case .code: break          // Offer code redeemed
     case .winBack: break       // Win-back offer applied
     default: break
     }
+
+    let offerID = offer.id
 }
 ```
 
@@ -431,6 +469,7 @@ try await product.purchase(options: [.codeOffer(referenceName: "SUMMER2024")])
 ### StoreKit Testing Capabilities
 
 - Simulate failed transactions, interrupted purchases, refunds
+- Test Ask to Buy pending approvals for promotional, win-back, and offer-code purchases
 - Speed up subscription renewals (renewals happen in minutes, not months)
 - Test grace period and billing retry states
 - Clear purchase history between test runs
@@ -586,8 +625,9 @@ member stops sharing, the transaction is revoked.
 
 ## Ask to Buy Handling
 
-Ask to Buy applies to child accounts in Family Sharing. The purchase
-returns `.pending` and must be approved by the family organizer.
+Ask to Buy applies to child accounts in Family Sharing. The purchase returns
+`.pending`; show a waiting-for-approval state, keep content locked, and unlock
+only after the approved transaction arrives from `Transaction.updates`.
 
 ```swift
 case .pending:
@@ -602,7 +642,9 @@ case .pending:
 try await product.purchase(options: [.simulatesAskToBuyInSandbox(true)])
 ```
 
-Then approve or decline in Xcode's Transaction Manager.
+Then approve or decline in Xcode's Transaction Manager. Include this path when
+testing promotional offers, win-back offers, offer codes, and renewal states so
+deferred approval does not bypass verification or entitlement updates.
 
 ## .currentEntitlementTask SwiftUI Modifier
 
@@ -624,11 +666,16 @@ enum EntitlementTaskState<Value> {
 }
 ```
 
-Use `map` and `flatMap` for transformations:
+Pattern-match the verified optional transaction before granting access:
 
 ```swift
 .currentEntitlementTask(for: ProductID.premium) { state in
-    self.isPremium = state.map { $0 != nil } ?? false
+    if case .success(.some(.verified(let transaction))) = state,
+       transaction.revocationDate == nil {
+        self.isPremium = true
+    } else {
+        self.isPremium = false
+    }
 }
 ```
 
@@ -697,7 +744,9 @@ if case .verified(let renewalInfo) = status.renewalInfo {
 
 ## Unfinished Transactions
 
-Process transactions that were not finished in previous sessions:
+`Transaction.updates` emits unfinished transactions once immediately after app
+launch. Use `Transaction.unfinished` when you need an explicit recovery sweep,
+such as after a delivery-server outage or a late listener startup:
 
 ```swift
 func processUnfinishedTransactions() async {
@@ -709,18 +758,18 @@ func processUnfinishedTransactions() async {
 }
 ```
 
-Call this at app launch alongside the `Transaction.updates` listener to
-ensure no purchases are lost.
+Keep the `Transaction.updates` listener as the primary always-on path, and use
+the sweep as a recovery tool rather than a replacement for the listener.
 
 ## Common Advanced Mistakes
 
-### Not processing unfinished transactions at launch
+### Missing a recovery path for unfinished transactions
 
 ```swift
-// WRONG: Only listen for updates, ignore pending deliveries
-init() { transactionListener = listenForTransactions() }
+// WRONG: No launch listener and no recovery sweep
+init() { }
 
-// CORRECT: Process unfinished transactions AND listen for updates
+// CORRECT: Start updates at launch; sweep unfinished transactions when needed
 init() {
     transactionListener = listenForTransactions()
     Task { await processUnfinishedTransactions() }

package/pipeline/skills/shared/external/swift-api-design-guidelines/SKILL.md

@@ -0,0 +1,449 @@
+---
+name: swift-api-design-guidelines
+description: "Apply Swift API Design Guidelines to name, label, and document Swift APIs. Covers argument label rules (prepositional phrase rule, grammatical phrase rule, first-label omission), mutating/nonmutating pair naming (-ed/-ing participle pattern, form- prefix, sort/sorted, formUnion/union), side-effect naming (noun for pure, verb for mutating), documentation comment structure (summary by declaration kind, O(1) complexity rule), clarity at call site, role-based naming, protocol naming (-able/-ible/-ing), default arguments over method families, casing conventions, and terminology. Use when designing new Swift APIs, reviewing naming and argument labels, writing documentation comments, or refactoring for call site clarity."
+---
+
+# Swift API Design Guidelines
+
+Apply the Swift API Design Guidelines when naming types, methods, properties, parameters, and argument labels. Targets Swift 6.3. For language features and syntax, see `swift-language`. For concurrency patterns, see `swift-concurrency`. For mixed requests, answer the API naming portion briefly, then route Swift type-system details to `swift-language` and lint configuration to `swiftlint` instead of implementing those sibling domains here.
+
+## Contents
+
+- [Argument Label Rules](#argument-label-rules)
+- [Side-Effect Naming](#side-effect-naming)
+- [Mutating and Nonmutating Pairs](#mutating-and-nonmutating-pairs)
+- [Documentation Comments](#documentation-comments)
+- [Clarity and Naming](#clarity-and-naming)
+- [Fluent Usage and Protocols](#fluent-usage-and-protocols)
+- [General Conventions](#general-conventions)
+- [Common Mistakes](#common-mistakes)
+- [Review Checklist](#review-checklist)
+- [References](#references)
+
+## Argument Label Rules
+
+Argument labels determine how a call site reads. Apply these rules in order.
+
+### When to omit the first argument label
+
+**Grammatical phrase rule.** When the first argument forms a grammatical phrase with the base name, omit the label. Move any leading words from what would be the label into the base name instead.
+
+```swift
+// GOOD  -  reads as "add subview y"
+view.addSubview(y)
+
+// BAD  -  redundant label breaks the phrase
+view.add(subview: y)
+```
+
+**Value-preserving type conversions.** When an initializer performs a value-preserving (widening) conversion, omit the first argument label.
+
+```swift
+// GOOD  -  widening conversion, no label
+let value = Int64(someUInt32)
+let str = String(someCharacter)
+
+// Narrowing or lossy conversions keep a label
+let approx = Int64(truncating: someDecimal)
+let str = String(describing: someObject)
+```
+
+**Indistinguishable arguments.** When all arguments cannot be usefully distinguished, omit all labels.
+
+```swift
+// GOOD  -  arguments are peers
+let smaller = min(x, y)
+zip(sequence1, sequence2)
+```
+
+### When to use a prepositional label
+
+**Prepositional phrase rule.** When the first argument completes a prepositional phrase with the base name, label it with the preposition.
+
+```swift
+// GOOD  -  "remove boxes having length 12"
+x.removeBoxes(havingLength: 12)
+
+// GOOD  -  "fade from red"
+view.fade(from: red)
+
+// GOOD  -  "relative path from root"
+path.relativePath(from: root)
+```
+
+**Exception  -  abstraction boundary.** When the first two arguments represent parts of a single abstraction, fold the preposition into the base name so each component gets its own label.
+
+```swift
+// GOOD  -  x and y are parts of a single abstraction (a point)
+a.moveTo(x: b, y: c)
+
+// BAD  -  preposition attaches to first arg, leaving y unlabeled
+a.move(toX: b, y: c)
+```
+
+### Default: label everything else
+
+When no special rule above applies, label the argument.
+
+```swift
+// GOOD
+array.split(maxSplits: 2)
+button.setTitle("OK", for: .normal)
+controller.dismiss(animated: true)
+array.sorted(by: >)
+```
+
+### Argument label decision table
+
+| Situation | Rule | Example |
+|-----------|------|---------|
+| First arg completes grammatical phrase | Omit label, merge words into base name | `addSubview(y)` |
+| Value-preserving init conversion | Omit first label | `Int64(someUInt32)` |
+| Arguments are indistinguishable peers | Omit all labels | `min(x, y)` |
+| First arg completes prepositional phrase | Label with preposition | `fade(from: red)` |
+| First two args form a single abstraction | Fold preposition into base name | `moveTo(x: b, y: c)` |
+| Everything else | Label it | `split(maxSplits: 2)` |
+
+For extended examples and edge cases, see [references/argument-labels-and-parameters.md](references/argument-labels-and-parameters.md).
+
+## Side-Effect Naming
+
+Name functions and methods by their side effects.
+
+### Functions with side effects  -  imperative verbs
+
+When a function mutates state, name it as an imperative verb phrase.
+
+```swift
+// Mutates  -  imperative verb
+array.sort()
+array.append(newElement)
+list.remove(at: index)
+timer.invalidate()
+```
+
+### Functions without side effects  -  nouns or adjective phrases
+
+When a function returns a result without mutating anything, name it as a noun phrase, adjective phrase, or read as a description of what it returns.
+
+```swift
+// Pure  -  noun/description
+let d = point.distance(to: origin)
+let area = rect.intersection(other)
+let line = text.trimmingCharacters(in: .whitespaces)
+```
+
+### Boolean properties and methods
+
+Boolean properties and methods read as assertions about the receiver.
+
+```swift
+// GOOD  -  reads as "line is empty"
+line.isEmpty
+set.contains(element)
+url.isFileURL
+
+// BAD  -  not an assertion
+line.empty       // verb? adjective?
+set.includes     // incomplete phrase
+```
+
+For more examples, see [references/side-effects-and-mutating-pairs.md](references/side-effects-and-mutating-pairs.md).
+
+## Mutating and Nonmutating Pairs
+
+When an operation has both mutating and nonmutating variants, name them as a pair.
+
+### Verb-described operations  -  -ed/-ing suffix
+
+When the operation is naturally described by a verb:
+- **Mutating:** imperative verb (`sort`, `append`, `reverse`)
+- **Nonmutating:** past participle `-ed` or present participle `-ing`
+
+Default to `-ed` (past participle) when the phrase naturally describes the returned value. Use `-ing` (present participle) only when the `-ed` form is ungrammatical or describes the direct object rather than the returned receiver or result. A direct object is a clue to check the grammar, not the rule by itself.
+
+| Mutating | Nonmutating | Why |
+|----------|-------------|-----|
+| `sort()` | `sorted()` | `-ed`  -  "a sorted array" |
+| `reverse()` | `reversed()` | `-ed`  -  "a reversed collection" |
+| `sortLines()` | `sortedLines()` | `-ed`  -  "sorted lines" describes the result |
+| `append(y)` | `appending(y)` | `-ing`  -  `appended` does not describe the returned receiver clearly |
+| `stripNewlines()` | `strippingNewlines()` | `-ing`  -  direct-object pattern from the guidelines |
+
+### Noun-described operations  -  form- prefix
+
+When the operation is naturally described by a noun:
+- **Nonmutating:** the noun itself (`union`, `intersection`)
+- **Mutating:** `form` prefix (`formUnion`, `formIntersection`)
+
+```swift
+// Nonmutating  -  returns new value
+let combined = a.union(b)
+
+// Mutating  -  modifies in place
+a.formUnion(b)
+```
+
+### Factory methods  -  make- prefix
+
+Factory methods that create a new value start with `make`.
+
+```swift
+let iterator = collection.makeIterator()
+let buffer = parser.makeBuffer()
+```
+
+In mixed routing answers, briefly validate existing `make...` factory names before handing off unrelated type-system or linting details to sibling skills.
+
+### Pair decision table
+
+| Operation described by | Mutating name | Nonmutating name | Example pair |
+|------------------------|---------------|-------------------|-------------|
+| Verb (default) | verb | verb + `-ed` | `sort()` / `sorted()` |
+| Verb (`-ed` is ungrammatical) | verb | verb + `-ing` | `stripNewlines()` / `strippingNewlines()` |
+| Noun | `form` + Noun | noun | `formUnion(b)` / `union(b)` |
+
+For the full -ed/-ing decision tree and expanded naming patterns, see [references/side-effects-and-mutating-pairs.md](references/side-effects-and-mutating-pairs.md).
+
+## Documentation Comments
+
+Every public declaration must have a documentation comment.
+
+### Summary rules by declaration kind
+
+| Declaration | Summary describes |
+|-------------|-------------------|
+| Function / method | What it does and what it returns |
+| Subscript | What it accesses |
+| Initializer | What it creates |
+| Type / property / variable | What it **is** |
+
+Write summaries as a single sentence fragment, beginning with a verb (for actions) or a noun phrase (for entities), ending in a period.
+
+```swift
+/// Returns the element at the specified index.
+func element(at index: Int) -> Element { ... }
+
+/// The number of elements in the collection.
+var count: Int { ... }
+
+/// Creates a new array with the given elements.
+init(_ elements: some Sequence<Element>) { ... }
+
+/// Accesses the element at the specified position.
+subscript(index: Int) -> Element { ... }
+```
+
+### Symbol markup
+
+Use standard symbol markup after the summary when relevant:
+
+- `- Parameter name:` for individual parameters
+- `- Parameters:` block for multiple parameters
+- `- Returns:` for the return value
+- `- Throws:` for errors thrown
+- `- Complexity:` for algorithmic complexity
+
+```swift
+/// Removes and returns the element at the specified position.
+///
+/// - Parameter index: The position of the element to remove.
+/// - Returns: The removed element.
+/// - Complexity: O(*n*), where *n* is the length of the collection.
+mutating func remove(at index: Int) -> Element { ... }
+```
+
+### O(1) complexity rule
+
+Document the complexity of any computed property that is not O(1). Callers assume properties are O(1) by default. If a property does more than constant-time work, state the complexity explicitly.
+
+```swift
+/// The total weight of all items.
+///
+/// - Complexity: O(*n*), where *n* is the number of items.
+var totalWeight: Double {
+    items.reduce(0) { $0 + $1.weight }
+}
+```
+
+For documentation patterns and examples, see [references/conventions-and-special-rules.md](references/conventions-and-special-rules.md).
+
+## Clarity and Naming
+
+Clarity at the point of use is the most important goal. Every design decision serves the person reading a call site.
+
+**Clarity over brevity.** Longer names are acceptable when they remove ambiguity. Do not abbreviate.
+
+```swift
+// GOOD
+employees.remove(at: position)
+
+// BAD  -  ambiguous: remove the element? remove at position?
+employees.remove(position)
+```
+
+**Include words needed to avoid ambiguity.** If omitting a word makes the call site unclear, keep it.
+
+```swift
+// GOOD  -  "at" clarifies the argument's role
+friends.remove(at: index)
+
+// BAD  -  is "index" the element to remove or the position?
+friends.remove(index)
+```
+
+**Omit needless words.** Do not repeat type information already available from the context.
+
+```swift
+// GOOD
+allViews.remove(cancelButton)
+
+// BAD  -  "Element" repeats the type
+allViews.removeElement(cancelButton)
+```
+
+**Name variables and parameters by role, not type.** Use the entity's role in the current context, not its type name.
+
+```swift
+// GOOD  -  describes the role
+var greeting: String
+func add(_ observer: NSObject, for keyPath: String)
+
+// BAD  -  names the type
+var string: String
+func add(_ object: NSObject, for string: String)
+```
+
+**Compensate for weak type information.** When a parameter type is `Any`, `AnyObject`, or a fundamental type like `Int` or `String`, add role-clarifying words to the name.
+
+```swift
+// GOOD  -  role is clear despite weak types
+func addObserver(_ observer: NSObject, forKeyPath path: String)
+
+// BAD  -  what does "string" mean here?
+func add(_ object: NSObject, for string: String)
+```
+
+For extended naming examples and patterns, see [references/naming-and-clarity.md](references/naming-and-clarity.md).
+
+## Fluent Usage and Protocols
+
+**Call sites read as grammatical English.** Prefer names that form grammatical phrases at the point of use.
+
+```swift
+// GOOD  -  reads fluently
+x.insert(y, at: z)          // "x, insert y at z"
+x.subviews.remove(at: i)    // "x's subviews, remove at i"
+x.makeIterator()             // "x, make iterator"
+
+// BAD  -  ungrammatical
+x.insert(y, position: z)
+x.subviews.remove(i)
+```
+
+**Initializer first argument.** The first argument to an initializer should not form a phrase continuing the type name.
+
+```swift
+// GOOD
+let foreground = Color(red: 32, green: 64, blue: 128)
+
+// BAD  -  "Color with red" reads awkwardly
+let foreground = Color(havingRGBValuesRed: 32, green: 64, blue: 128)
+```
+
+**Protocol naming conventions:**
+
+| Protocol describes | Naming pattern | Examples |
+|--------------------|----------------|----------|
+| What something **is** | Noun | `Collection`, `IteratorProtocol` |
+| A **capability** | `-able`, `-ible`, or `-ing` suffix | `Equatable`, `Hashable`, `Sendable` |
+
+## General Conventions
+
+**Casing.** Types and protocols use `UpperCamelCase`. Everything else uses `lowerCamelCase`. Acronyms that are commonly all-caps in American English appear uniformly upper- or lower-cased based on position.
+
+```swift
+var utf8Bytes: [UTF8.CodeUnit]
+var isRepresentableAsASCII = true
+var userSMTPServer: SMTPServer
+```
+
+**Methods and properties over free functions.** Prefer methods and properties. Use free functions only when:
+1. There is no obvious `self`  -  `min(x, y)`
+2. The function is an unconstrained generic  -  `print(value)`
+3. The function syntax is established domain notation  -  `sin(x)`
+
+**Default arguments over method families.** Prefer a single method with default parameters over a family of methods that differ only in which parameters they accept. Place defaulted parameters at the end. Parameters with default values should always have argument labels  -  defaulted parameters are usually omitted at call sites, so their labels must be clear when they do appear.
+
+```swift
+// GOOD  -  labeled with defaults
+func decode(_ data: Data, encoding: String.Encoding = .utf8) -> String?
+
+// BAD  -  method family
+func decode(_ data: Data) -> String?
+func decode(_ data: Data, encoding: String.Encoding) -> String?
+```
+
+**Overload safety.** Methods may share a base name when they operate in different type domains or when their meaning is clear from context. Avoid return-type-only overloads that cause ambiguity at the call site.
+
+For casing edge cases, overload patterns, and tuple/closure naming, see [references/conventions-and-special-rules.md](references/conventions-and-special-rules.md).
+
+## Common Mistakes
+
+1. **Omitting needed argument labels.** Using `remove(position)` instead of `remove(at: position)` when the role of the argument is ambiguous without the label.
+
+2. **Using -ed when -ing is correct.** Applying `stripped()` when the past participle is ungrammatical  -  use `stripping()` instead. Test: does "a [verb]-ed [noun]" read naturally?
+
+3. **Using verb names for side-effect-free operations.** Naming a nonmutating method `sort()` that returns a new collection  -  use `sorted()` to signal no mutation.
+
+4. **Naming by type instead of role.** Using `string` instead of `greeting`, or `array` instead of `elements`, when the role would be more informative.
+
+5. **Missing documentation comments.** Leaving public declarations undocumented, or writing summaries that describe the implementation rather than the purpose.
+
+6. **Not documenting non-O(1) computed properties.** Exposing a linear-time computed property without a `Complexity:` note, causing callers to assume O(1) and use it in loops.
+
+7. **Applying form- prefix to verb-based operations.** Writing `formSort()` instead of just `sort()`  -  the `form` prefix is only for noun-based operations (`formUnion`).
+
+8. **Factory methods without make- prefix.** Naming factory methods as `createIterator()` or `buildBuffer()` instead of `makeIterator()` and `makeBuffer()`.
+
+9. **Repeating type information in names.** Writing `removeElement(cancelButton)` or `stringValue: String` when the type is already evident from context.
+
+10. **Return-type-only overloads.** Defining overloads that differ only in return type, creating ambiguity when the compiler cannot infer the expected type.
+
+11. **Unlabeled tuple members and closure parameters.** Exposing tuples or closures in public API without naming their components, forcing callers to use positional access.
+
+## Review Checklist
+
+### Argument Labels
+- [ ] First argument follows the correct label rule (grammatical phrase, prepositional, conversion, or labeled)
+- [ ] Prepositional labels do not incorrectly group independent arguments
+- [ ] Value-preserving conversion initializers omit the first label
+- [ ] All non-special-case arguments have labels
+
+### Naming Semantics
+- [ ] Mutating methods use imperative verb form
+- [ ] Nonmutating methods use -ed/-ing or noun form
+- [ ] Mutating/nonmutating pairs follow the correct pattern (verb pair or noun/form-noun pair)
+- [ ] Boolean properties read as assertions (`isEmpty`, `isValid`, `contains`)
+- [ ] Variables and parameters are named by role, not type
+
+### Documentation
+- [ ] Every public declaration has a doc comment
+- [ ] Summaries are single sentence fragments ending in a period
+- [ ] Summaries describe the correct thing per declaration kind (action, access, creation, entity)
+- [ ] Non-O(1) computed properties document their complexity
+- [ ] Parameters, return values, and thrown errors are documented with symbol markup
+
+### Conventions
+- [ ] Types and protocols use UpperCamelCase; everything else uses lowerCamelCase
+- [ ] Acronyms are uniformly cased based on position
+- [ ] Default arguments are preferred over method families
+- [ ] Overloads do not differ only in return type
+- [ ] Protocol names follow the noun (is-a) or suffix (capability) convention
+
+## References
+
+- Naming clarity, role-based naming, weak-type compensation, and terminology: [references/naming-and-clarity.md](references/naming-and-clarity.md)
+- Argument label edge cases, parameter naming, and default argument strategy: [references/argument-labels-and-parameters.md](references/argument-labels-and-parameters.md)
+- Side-effect naming examples, -ed/-ing decision tree, form- prefix patterns, and factory methods: [references/side-effects-and-mutating-pairs.md](references/side-effects-and-mutating-pairs.md)
+- Casing edge cases, complexity documentation, overload safety, tuple/closure naming, and free function exceptions: [references/conventions-and-special-rules.md](references/conventions-and-special-rules.md)