@mrciphersmith/keryx 0.3.2 → 0.3.5

package/src/gdskills/bundled/stacks/swift-ios/governance/scout.json

@@ -0,0 +1,32 @@
+[
+  {
+    "query": "Use when implementing or extending a feature in a SwiftUI/iOS app -- state ownership (@State/@Binding/@Environment/@Observable), Swift concurrency (async/await, actors, @MainActor, TaskGroup, Sendable), and view composition.",
+    "decision": "create",
+    "topMatch": "flutter-dart/flutter-implementation",
+    "recordedAt": "2026-09-25T15:32:07.026Z",
+    "skillName": "swiftui-implementation"
+  },
+  {
+    "query": "Use when a Swift/iOS test suite needs writing, extending, or fixing -- Swift Testing's @Test/#expect/#require, parameterized tests, legacy XCTest, and mocking network/persistence dependencies at a protocol boundary rather than the type under test's internals.",
+    "decision": "fork",
+    "topMatch": "csharp-dotnet/dotnet-testing",
+    "recordedAt": "2026-09-25T15:35:21.070Z",
+    "skillName": "swift-testing",
+    "justification": "Nearest match csharp-dotnet/dotnet-testing tests C# with xUnit/NUnit/Moq, a different language and tooling entirely; no existing test skill covers Swift Testing's @Test/#expect, XCTest, or Swift protocol-boundary mocking."
+  },
+  {
+    "query": "Use when reviewing a Swift/iOS change for concurrency, memory, and safety risks -- force-unwraps, retain cycles from closures capturing self, missing @MainActor isolation, @unchecked Sendable used to silence checks, and secrets stored outside the Keychain. Read-only, no edits.",
+    "decision": "create",
+    "topMatch": "csharp-dotnet/dotnet-code-review",
+    "recordedAt": "2026-09-25T15:32:07.629Z",
+    "skillName": "swift-code-review"
+  },
+  {
+    "query": "Use when xcodebuild/swift build fails, or a Swift 6 strict-concurrency/Sendable error, SwiftLint failure, or failing test blocks the build -- resolves the root cause instead of force-unwrapping, adding @unchecked Sendable, or disabling a lint rule to silence the check.",
+    "decision": "fork",
+    "topMatch": "ts-js-node/nodejs-build-fix",
+    "recordedAt": "2026-09-25T15:35:21.350Z",
+    "skillName": "swift-build-fix",
+    "justification": "Nearest match ts-js-node/nodejs-build-fix fixes tsc/ESM/eslint errors for Node/TS, not xcodebuild/Swift 6 concurrency/Sendable/SwiftLint failures; each build-fix skill is scoped to its own toolchain's specific failure surface."
+  }
+]

package/src/gdskills/bundled/stacks/swift-ios/pack.json

@@ -0,0 +1,38 @@
+{
+  "id": "swift-ios",
+  "family": "framework",
+  "modules": ["swift-ios-rules", "swift-ios-skills"],
+  "detectionMarkers": ["ios"],
+  "provenance": { "origin": "authored", "sourceRef": "flow 336, Wave 4 batch 4" },
+  "stability": "experimental",
+  "skills": {
+    "implement": ["swiftui-implementation"],
+    "test": ["swift-testing"],
+    "review": ["swift-code-review"],
+    "build-fix": ["swift-build-fix"],
+    "migrate": []
+  },
+  "agentProfile": {
+    "displayName": "Swift/iOS",
+    "auditFocus": [
+      "force-unwrapping (`!`) or force-try (`try!`) on a value that can genuinely be nil or throw, especially on network/decoded data",
+      "an `@Observable` model or any UI-touching type not isolated to `@MainActor`, risking a cross-actor data race",
+      "a closure captured strongly by `self` in a long-lived callback (completion handler, Combine sink, stored closure) causing a retain cycle",
+      "a secret, API key, or auth token stored in `UserDefaults` or hardcoded in source instead of the Keychain",
+      "state ownership mismatches: `@State` for a value that is actually shared/mutated by a parent, or a legacy `@StateObject` recreated inline instead of owned once",
+      "`@unchecked Sendable` or a blanket concurrency-checking suppression applied to silence the compiler instead of fixing the actual data-race shape"
+    ],
+    "buildCommands": [
+      "xcodebuild build -scheme <Scheme> -destination 'platform=iOS Simulator,name=<Simulator>' (or swift build for a SwiftPM package)",
+      "xcodebuild test -scheme <Scheme> -destination 'platform=iOS Simulator,name=<Simulator>' (or swift test)",
+      "swiftlint",
+      "swift-format lint --recursive . (or swiftformat --lint . depending on the project's configured formatter)"
+    ],
+    "fixGuardrails": [
+      "never mark a type `@unchecked Sendable` to silence a strict-concurrency error without actually proving and documenting why its mutable state is safe",
+      "never force-unwrap (`!`) or force-try (`try!`) just to clear a compiler warning about an optional or a throwing call",
+      "never disable a SwiftLint/swift-format rule repo-wide (or with a blanket `// swiftlint:disable`) to make one finding disappear",
+      "never delete or skip a failing test, or loosen its assertion, to reach a green build"
+    ]
+  }
+}

package/src/gdskills/bundled/stacks/swift-ios/rules/coding-style.mdc

@@ -0,0 +1,92 @@
+---
+extends: common
+paths: ["**/*.swift"]
+metadata:
+  origin: authored
+---
+
+# Swift/iOS coding style
+
+Narrows `core-common-rules`' stack-agnostic style rules to modern Swift
+(6.x) and SwiftUI idiom. Applies only to `*.swift` files — everything not
+Swift-specific still comes from the common rules this file `extends`.
+
+## Naming and structure
+
+- Types (`struct`, `class`, `enum`, `protocol`) are `UpperCamelCase`;
+  properties, methods, and cases are `lowerCamelCase` — never
+  `snake_case` for either.
+- Protocol names read as a capability (`Fetchable`, `Cacheable`) or a
+  role noun (`DataSource`, `Delegate`); do not suffix a protocol with
+  `Protocol`.
+- An identifier's name shrinks with its scope: a tight closure parameter
+  can be `$0`/a one-letter name, a public API member gets a full
+  descriptive name.
+- File name matches the primary type it declares (`OrderService.swift`
+  declares `OrderService`); one primary type per file for anything
+  public.
+
+## Value types vs reference types
+
+- Default to `struct` (and `enum` for closed sets of cases) for model and
+  state types — value semantics mean a copy cannot be mutated out from
+  under another owner, which is what SwiftUI's data flow assumes.
+- Reach for `class` only when you need reference semantics on purpose:
+  shared mutable state across owners, identity that must be preserved
+  (`===`), or Objective-C interop. Justify a `class` model type in review
+  rather than defaulting to it out of habit from other languages.
+- A `class` used as SwiftUI-observed state is marked `@Observable` (see
+  `patterns.mdc`) and, when its mutable state is touched from view code,
+  isolated to `@MainActor`.
+
+## Guard for early exit
+
+- Use `guard let`/`guard` with an early `return`/`continue`/`throw` to
+  unwrap a precondition and keep the "happy path" unindented, rather than
+  nesting the whole function body inside an `if let`.
+- Prefer a single `guard` with multiple comma-separated conditions over a
+  pyramid of nested `if let`s when several optionals must all be present
+  before the function can proceed.
+
+## Optionals
+
+- Treat `!` (force-unwrap) and `try!` (force-try) as a last resort, not a
+  convenience — reserve them for a value whose absence is a genuine
+  programmer error that should crash in development (an `IBOutlet` wired
+  in a storyboard, a compile-time-guaranteed non-nil literal), never for
+  network responses, decoded JSON, user input, or anything else that can
+  legitimately be nil or throw in production.
+- Prefer `guard let`/`if let`, nil-coalescing (`??`) with a real default,
+  or `try`/`try?` with explicit handling. Use `#require(...)` (Swift
+  Testing) or `XCTUnwrap` in tests instead of `!` when a test needs to
+  unwrap and fail with a clear message if the value is missing.
+- Chain optional access with `?.`/optional chaining rather than
+  force-unwrapping an intermediate step in a chain.
+
+## @Observable vs legacy ObservableObject
+
+- For code targeting iOS 17+, model types that drive SwiftUI view
+  updates use the `@Observable` macro, not the legacy
+  `ObservableObject`/`@Published` combination — `@Observable` tracks
+  property-level access automatically, so a view only re-renders for the
+  properties it actually reads, where `@Published` re-renders on any
+  change to the whole object.
+- Mark an `@Observable` class `@MainActor` unless the project has set a
+  module-wide default actor isolation to `MainActor` — this keeps its
+  mutable state confined to the main actor by construction (see
+  `patterns.mdc` for the concurrency implications).
+- Only reach for `ObservableObject`/`@Published`/`@StateObject`/
+  `@ObservedObject` when the project's minimum deployment target
+  predates iOS 17, or an existing codebase has not yet migrated; do not
+  introduce the legacy pattern in new code on a project that already
+  targets iOS 17+.
+
+## Formatting and linting
+
+- Format with the project's configured formatter (`swift-format` or
+  `swiftformat`) before finishing a change; do not hand-format around a
+  formatter that is already configured in the project.
+- Fix a SwiftLint finding at its root cause; do not silence it with a
+  blanket `// swiftlint:disable` covering more than the one line it
+  actually applies to, and never disable a rule repository-wide to clear
+  one finding.

package/src/gdskills/bundled/stacks/swift-ios/rules/patterns.mdc

@@ -0,0 +1,112 @@
+---
+extends: common
+paths: ["**/*.swift"]
+metadata:
+  origin: authored
+---
+
+# Swift/iOS patterns
+
+Narrows `core-common-rules`' stack-agnostic design guidance to idiomatic
+Swift concurrency and SwiftUI state ownership. Applies only to `*.swift`
+files.
+
+## Swift concurrency: async/await and structured concurrency
+
+- Prefer `async`/`await` over completion-handler callbacks for new
+  asynchronous code — it reads linearly and composes with structured
+  concurrency instead of nesting closures.
+- Start concurrent child work with `async let` (a small, fixed number of
+  parallel tasks) or `TaskGroup`/`withThrowingTaskGroup` (a dynamic or
+  unbounded set of child tasks); both guarantee every child task is
+  awaited or cancelled before the parent scope exits, unlike a bare
+  unstructured `Task {}` with no owner to join it. (`Task {}` is
+  "unstructured" — it inherits the creating context's actor and priority
+  but nothing tracks its lifetime; `Task.detached {}` is a stronger,
+  rarely-needed form that inherits neither — do not use the two names
+  interchangeably.)
+- SwiftUI's `.task { }` modifier closure is already async — it is the
+  boundary, not a place to wrap another `Task {}` inside it. Reach for a
+  bare `Task {}` only at a genuine synchronous-to-async boundary with no
+  async closure already available (a button action's `Void`-returning
+  handler, a delegate callback); give it an explicit reason it does not
+  need to be joined. Prefer `.task { }` directly on a SwiftUI view over a
+  manually created `Task` when the work should be tied to the view's
+  lifetime (it is cancelled automatically when the view disappears).
+- Respect cancellation in long-running async work: check
+  `Task.isCancelled`/call `try Task.checkCancellation()` in a loop, so a
+  cancelled parent actually stops the child's work instead of running to
+  completion regardless.
+
+## Actors and @MainActor
+
+- Use `actor` to protect mutable state that multiple tasks touch
+  concurrently — its methods are implicitly isolated, so the compiler
+  (not a convention) prevents unsynchronized access, the same guarantee
+  a manual lock only provides by discipline.
+- Since the iOS 18 SDK, `View` conformance is itself `@MainActor`-isolated
+  — a view's own `body` and any `@State`/`@Binding` kept directly on the
+  view struct are already main-actor-isolated automatically, with no
+  explicit annotation needed. That isolation does NOT extend to a
+  SEPARATE type: mark any standalone type whose state SwiftUI reads or
+  mutates `@MainActor` explicitly — view models, `@Observable` stores, or
+  any other type outside the `View` struct itself that a `body` touches.
+  Isolate at the type level (`@MainActor final class ...`) rather than
+  sprinkling `@MainActor` on individual methods, unless only some of the
+  type's methods genuinely need main-actor isolation.
+- Cross an actor boundary explicitly with `await`; do not reach for
+  `@unchecked Sendable` or `nonisolated(unsafe)` to make a boundary
+  error disappear — either the type's state genuinely needs no
+  isolation (make that case explicitly, with a comment), or it needs a
+  real actor/lock, not a suppression.
+
+## Sendable conformance
+
+- A value crossing a concurrency boundary (passed into a `Task`, an
+  actor method, or a `TaskGroup` child) must be `Sendable`: a `struct`
+  or `enum` with only `Sendable` members is `Sendable` for free; a
+  `final class` with only immutable (`let`) stored properties can
+  declare conformance explicitly.
+- Do not slap `@unchecked Sendable` on a class to silence a
+  strict-concurrency diagnostic without actually auditing and
+  documenting why its mutable state cannot race — that trades a
+  compile-time guarantee for an unchecked promise, which is exactly the
+  class of bug Swift 6's data-race safety exists to catch.
+- Under the Swift 6 language mode, treat a "Sendable" or "actor
+  isolation" compiler error as a real potential data race to fix at the
+  root (add an actor, make the type immutable, or copy the value before
+  crossing), not friction to suppress.
+
+## SwiftUI state ownership
+
+- `@State` owns a value the view itself creates and is the sole owner
+  of — a simple value type, or (iOS 17+) an `@Observable` reference type
+  the view instantiates directly (`@State private var model = Model()`,
+  not `@StateObject` for `@Observable` types).
+- `@Binding` is for a child view that needs to both read and mutate a
+  value it does not own — the parent passes `$value`, and the child
+  writes through the binding instead of receiving a copy it cannot
+  propagate changes from.
+- `@Environment` is for values that are ambient to a whole subtree
+  (theme, a shared service, a feature flag) rather than threaded
+  explicitly through every initializer; do not reach for it as a
+  shortcut to avoid passing an explicit dependency that only one or two
+  views actually need.
+- A view that receives an `@Observable` model from a parent and needs to
+  pass a binding to one of its properties down further uses `@Bindable`,
+  not a manually reconstructed `Binding(get:set:)`.
+
+## Anti-patterns to flag
+
+- A retain cycle from a closure (completion handler, Combine `sink`,
+  stored callback) that captures `self` strongly when the closure
+  outlives the call that created it — use `[weak self]` and unwrap, or
+  `[unowned self]` only when `self`'s lifetime is provably guaranteed to
+  exceed the closure's.
+- Lifting a value into `@State`/`@StateObject` at the view that merely
+  displays it, when a parent further up actually owns and mutates it —
+  that duplicates state instead of using `@Binding`/`@Observable`
+  references, and the two copies drift.
+- A massive view or view-model type that owns navigation, networking,
+  and persistence together — split by responsibility the same way a
+  "god package"/"god object" is flagged in any other stack.

package/src/gdskills/bundled/stacks/swift-ios/rules/security.mdc

@@ -0,0 +1,78 @@
+---
+extends: common
+paths: ["**/*.swift"]
+metadata:
+  origin: authored
+---
+
+# Swift/iOS security
+
+Narrows `core-common-rules`' stack-agnostic security rules to
+iOS/Apple-platform-specific risks and the safe framework API to use
+instead. Applies only to `*.swift` files.
+
+## Secrets and credential storage
+
+- Store credentials, tokens, and refresh tokens in the Keychain
+  (`Security` framework, or a thin wrapper around it) — never in
+  `UserDefaults`, which is unencrypted plist storage readable by
+  anything with filesystem access to the app's container, and never in a
+  plain file the app writes itself.
+- Never hardcode an API key, client secret, or signing credential as a
+  string literal in source. Load it from a build-time configuration
+  (an `.xcconfig` value injected into `Info.plist`, a secrets manager
+  fetched at runtime) that is excluded from source control, and treat a
+  literal key found in a diff as a finding, not a style nit.
+- Set an appropriate Keychain accessibility level
+  (`kSecAttrAccessibleWhenUnlockedThisDeviceOnly` or stricter) for
+  anything sensitive — the default accessibility can survive a device
+  backup/restore onto different hardware, which is usually not the
+  intended threat model for a session token.
+
+## Network security (ATS and transport)
+
+- Leave App Transport Security (ATS) at its default (HTTPS-only,
+  TLS 1.2+); do not add `NSAllowsArbitraryLoads` or a blanket
+  `NSExceptionDomains` bypass to `Info.plist` to work around a backend
+  that is not yet on HTTPS — fix the backend, or scope an ATS exception
+  to the exact domain and the exact minimum relaxation needed, with a
+  comment saying why.
+- Validate TLS the platform's normal way (`URLSession`'s default trust
+  evaluation); do not implement a `URLSessionDelegate` that accepts any
+  server certificate (`.performDefaultHandling` bypassed with
+  unconditional trust) outside of a short-lived local/test
+  configuration, and never ship that in production.
+
+## Biometric authentication
+
+- Treat a `LAContext` biometric (Face ID/Touch ID) result as a *local
+  presence* gate, not proof of identity to a remote server on its own —
+  a successful `evaluatePolicy` unlocks a locally-held secret (a
+  Keychain item, a locally cached credential); it does not substitute
+  for a real authentication token when talking to a backend.
+- Check the specific `LAError` case on failure (`.userCancel`,
+  `.biometryNotAvailable`, `.biometryLockout`, ...) and present a
+  fallback (passcode, credential re-entry) rather than treating every
+  failure identically or silently retrying.
+- Do not cache "biometric succeeded" as a long-lived boolean flag read
+  later by unrelated code paths — re-evaluate at the point access is
+  actually needed, scoped to what that specific action requires.
+
+## Input handling and injection-adjacent risks
+
+- Parameterize any `NSPredicate`/Core Data query built from
+  user-influenced input rather than interpolating the value directly
+  into the predicate format string — the same injection-shaped risk as
+  building SQL by string concatenation.
+- Validate/sanitize any URL or deep link the app opens
+  (`UIApplication.open`, a Universal Link handler) before acting on it —
+  a deep link is untrusted input from outside the process, not a value
+  to trust and route on directly.
+
+## Logging
+
+- Never log a token, password, or full PII payload at a level that
+  reaches persistent device logs (`print`, unredacted `os_log`/`Logger`
+  interpolation) — use `Logger`'s privacy-redaction (`\(value,
+  privacy: .private)`) for anything sensitive, or omit it from the log
+  entirely.

package/src/gdskills/bundled/stacks/swift-ios/rules/testing.mdc

@@ -0,0 +1,90 @@
+---
+extends: common
+paths: ["**/*.swift"]
+metadata:
+  origin: authored
+---
+
+# Swift/iOS testing
+
+Narrows `core-common-rules`' stack-agnostic testing rules to Swift
+Testing (the current default for new test code) and legacy XCTest, where
+the project has not yet migrated. Applies only to `*.swift` files.
+
+## Swift Testing vs XCTest
+
+- For new test code on a toolchain that supports it, prefer the Swift
+  Testing framework (`import Testing`, `@Test` functions, `#expect`/
+  `#require` macros) over XCTest — it gives clearer failure messages
+  (`#expect` captures the evaluated sub-expressions), native
+  parameterized tests, and tests run in parallel by default.
+- Swift Testing does not yet replace XCTest everywhere: UI automation
+  (`XCUITest`) and performance tests (`XCTMetric`/`measure`) still run
+  on XCTest, and an existing XCTest suite does not need a wholesale
+  rewrite just to adopt Swift Testing — the two frameworks coexist in
+  the same target. Match whichever the project's existing test target
+  already uses for a given kind of test; introduce Swift Testing for new
+  unit-test coverage rather than mixing conventions within one file.
+- A Swift Testing function is `@Test func name() async throws { ... }`
+  (not `test`-prefixed, no `XCTestCase` subclass needed); assert with
+  `#expect(condition)` for a check that should record a failure and
+  continue, or `try #require(optional)` for one that must stop the test
+  immediately if it fails (the Swift Testing equivalent of
+  `XCTUnwrap`/`XCTAssert...` followed by an early return).
+
+## Structure and naming
+
+- One `@Test` (or `XCTest` method) per behavior being verified; a
+  descriptive test name (`@Test("returns nil for an empty cart")` or a
+  method named `test_returnsNil_whenCartIsEmpty`) over `test1`/`test2`.
+- Use Swift Testing's `arguments:` parameterization for the same
+  assertion repeated over several inputs, instead of a hand-rolled loop
+  inside one test function or several copy-pasted test functions that
+  differ only by input.
+- Group related tests with a `struct`/`enum` namespace and Swift
+  Testing's `@Suite`, or an `XCTestCase` subclass for legacy code,
+  matching whatever the target already does.
+
+## Mocking at the protocol boundary
+
+- Mock external dependencies — network clients, persistence
+  (`UserDefaults`, Core Data, a database layer), platform services
+  (location, notifications) — at a protocol boundary the production code
+  already depends on, never by mocking the type under test's own
+  internal collaborators or reaching into its private state.
+- Define (or reuse) a narrow protocol for the dependency (`protocol
+  OrderClient { func fetchOrder(id: String) async throws -> Order }`),
+  inject a real conforming type in production and a test double
+  conforming to the same protocol in tests — the type under test never
+  needs to know it is under test.
+- Do not mock one layer too deep (stubbing a private helper method, or
+  a concrete `URLSession` call inside a class instead of the protocol
+  that wraps it) — that couples the test to an implementation detail and
+  breaks on a harmless refactor instead of only on an actual behavior
+  change.
+
+## Async and concurrency in tests
+
+- Mark a test `async` and `await` the async call under test directly —
+  Swift Testing and modern `XCTestCase` both support `async` test
+  methods natively; do not reach for an `XCTestExpectation`/semaphore to
+  bridge an `async` API into a synchronous-looking test unless the
+  project's minimum toolchain predates async test support.
+- Never synchronize with a fixed delay (`Thread.sleep`/`Task.sleep` used
+  as a guess at "enough time") to wait for concurrent work to finish —
+  `await` the async call, join a `TaskGroup`, or await an
+  `XCTestExpectation` with a real fulfillment signal instead of a timed
+  guess.
+- Annotate a test `@MainActor` when it exercises `@MainActor`-isolated
+  view-model/state code, so the test itself runs on the same actor its
+  subject requires.
+
+## Determinism
+
+- A test must not depend on real network access, the real Keychain, or
+  wall-clock time; inject a fake/in-memory conforming type at the
+  protocol boundary and, for time-dependent logic, inject a clock/date
+  provider instead of calling `Date()` directly inside the code under
+  test.
+- A bug fix gets a regression test that fails before the fix and passes
+  after; new behavior gets new test coverage in the same change.

package/src/gdskills/bundled/stacks/swift-ios/skills/swift-build-fix/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: swift-build-fix
+description: "Use when xcodebuild/swift build fails, or a Swift 6 strict-concurrency/Sendable error, SwiftLint failure, or failing test blocks the build -- resolves the root cause instead of force-unwrapping, adding @unchecked Sendable, or disabling a lint rule to silence the check."
+triggers:
+  - "xcodebuild is failing"
+  - "swift build error"
+  - "fix this Swift 6 concurrency error"
+  - "SwiftLint is failing"
+  - "resolve this Sendable conformance error"
+  - "this Swift test is failing, fix the build"
+metadata:
+  origin: authored
+  category: build-fix
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Swift/iOS build fix
+
+Resolve an `xcodebuild`/`swift build` failure, a Swift 6 strict-
+concurrency or `Sendable` conformance error, a SwiftLint/swift-format
+failure, or a failing test blocking the build — with the smallest change
+that fixes the actual root cause. `rules/coding-style.mdc` and
+`rules/patterns.mdc` govern what a "correct" fix looks like; this skill
+never reaches for a suppression instead of a fix.
+
+## Workflow
+
+### Step 1: Reproduce and classify
+
+```bash
+xcodebuild build -scheme <Scheme> -destination 'platform=iOS Simulator,name=<Simulator>'
+# or, for a Swift package:
+swift build
+```
+
+Run the project's configured linter/formatter if present (`swiftlint`,
+`swift-format lint`/`swiftformat --lint`). Read the exact error text and
+classify it:
+
+- **Compile error** (undefined symbol, type mismatch, wrong argument
+  count/label).
+- **Concurrency/Sendable** (`Sendable` conformance error, an actor-
+  isolation error, a Swift 6 strict-concurrency diagnostic).
+- **Optional-binding warning** (a `guard`/`if let` the compiler flags as
+  always-succeeding or a value it infers as never-nil).
+- **Dependency/toolchain** (Swift Package Manager resolution failure, a
+  CocoaPods/Carthage mismatch, an Xcode/Swift toolchain version the
+  project's minimum predates).
+- **Lint/format finding** (SwiftLint rule, swift-format/swiftformat
+  diagnostic).
+- **Failing test** blocking a scheme that runs tests as part of build.
+
+### Step 2: Fix by category
+
+**Concurrency/Sendable:** read exactly what the compiler says is
+crossing the boundary unsafely. If the type's mutable state genuinely
+needs protecting, isolate it with an `actor` or `@MainActor`; if it is
+genuinely immutable, conform it to `Sendable` properly (all stored
+properties `Sendable`, or an explicit, justified conformance). Only use
+`@unchecked Sendable` when you can state in the report exactly why the
+type's access pattern is safe despite the compiler being unable to prove
+it — never as a default move to clear the error.
+
+**Optional-binding warning:** fix the actual type/control-flow issue the
+compiler is pointing at (a value that genuinely cannot be nil should not
+be declared `Optional`; a value that can be nil needs the `guard`/`if
+let` the compiler is questioning). Never force-unwrap (`!`) to silence
+the warning instead of addressing why the compiler flagged it.
+
+**Dependency/toolchain:** for a Swift Package Manager resolution
+failure, check `Package.resolved` against `Package.swift`'s declared
+requirements before bumping a version by hand; for a toolchain mismatch,
+confirm the project's actual minimum Swift/Xcode version before changing
+`swift-tools-version` or the deployment target just to make an error
+disappear.
+
+**Lint/format finding:** fix the underlying issue the rule names (a real
+force-unwrap, a genuinely too-long function, an unused variable). Never
+add a blanket `// swiftlint:disable` covering more than the one flagged
+line, and never disable a rule repository-wide in `.swiftlint.yml` to
+clear one finding without discussing why the rule itself is wrong for
+this codebase.
+
+**Failing test:** read the failure and fix the actual regression it
+caught; do not delete, skip (`.disabled()`/`XCTSkip` used to dodge
+rather than genuinely skip an environment-specific case), or loosen the
+test's assertion just to reach a green build.
+
+### Step 3: Verify
+
+```bash
+xcodebuild build -scheme <Scheme> -destination 'platform=iOS Simulator,name=<Simulator>'
+xcodebuild test -scheme <Scheme> -destination 'platform=iOS Simulator,name=<Simulator>'
+```
+
+Re-run the project's linter/formatter if it was part of the original
+failure. All must exit 0 before reporting done.
+
+### Step 4: Report
+
+```
+Fixed: Sendable conformance error in OrderCache
+  - Root cause: OrderCache held mutable state accessed from two tasks
+    with no isolation; converted it to an actor
+  - xcodebuild build/test both pass, swiftlint clean
+```
+
+State the root cause in one sentence, not just "fixed the error."
+
+## Rules
+
+- Find and fix the smallest change that addresses the actual root cause
+  — never widen a fix beyond what the failure requires.
+- NEVER mark a type `@unchecked Sendable` to silence a strict-
+  concurrency error without stating, in the report, exactly why its
+  mutable state is safe.
+- NEVER force-unwrap (`!`) or force-try (`try!`) just to clear a
+  compiler warning about an optional or a throwing call.
+- NEVER add a blanket `// swiftlint:disable` (or disable a rule
+  repository-wide) to make one finding disappear.
+- NEVER delete or skip a failing test to reach a green build.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll mark this `@unchecked Sendable`, it's the fastest way to clear the error" | Trades a compile-time data-race guarantee for an unchecked promise; audit the actual access pattern or add real isolation instead |
+| "I'll force-unwrap this to silence the compiler's optional-binding warning" | The warning exists because the compiler cannot prove the value is non-nil; force-unwrapping does not fix that, it just moves the failure to a runtime crash |
+| "I'll add `// swiftlint:disable force_unwrapping` for this whole file" | Silences every future violation in the file, not just the one the fix addressed — scope any disable as narrowly as the actual justified exception |
+| "This test is flaky, I'll mark it `.disabled()` for now" | Hides a real regression or a genuine flake worth fixing (non-deterministic async wait, shared state) instead of fixing the underlying cause |
+
+## Verification
+
+Do not report the fix done until all of the following hold:
+
+- `xcodebuild build`/`swift build` and `xcodebuild test`/`swift test`
+  both exit 0.
+- The project's linter/formatter (if configured) exits 0.
+- The change is the smallest one that addresses the stated root cause —
+  no unrelated files touched.
+- The report states the root cause in one sentence, not just "build now
+  passes."