From f8eecd48e054db139621c24011ddbfed08cc576f Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sun, 16 Aug 2026 11:05:21 -0700 Subject: [PATCH] docs(ios-qa): document the bridge compatibility preflight and non-SwiftPM fallback Re-derived from PR #2581 under the generated-file screening rule (template hunk taken; SKILL.md regenerated). Prevents the agent from inventing project wiring on apps the bridge doesn't support (ObservableObject-style or non-SwiftPM apps): the preflight now names the compatibility check and the manual fallback path. Co-authored-by: Tim White Co-Authored-By: Claude Fable 5 --- ios-qa/SKILL.md | 17 +++++++++++++++-- ios-qa/SKILL.md.tmpl | 17 +++++++++++++++-- 2 files changed, 30 insertions(+), 4 deletions(-) diff --git a/ios-qa/SKILL.md b/ios-qa/SKILL.md index dd58bd0e1..2d9c29594 100644 --- a/ios-qa/SKILL.md +++ b/ios-qa/SKILL.md @@ -886,7 +886,20 @@ fi ## Phase 1: Read source, plan codegen -1. Walk the app source (passed as `--source `) and identify all `@Observable` +1. Before changing the app or replacing an installed build, verify that the + bridge is compatible with the project: + - The generator currently supports file-scope `@Observable` classes only; + `ObservableObject`, `@StateObject`, and other observation models do not + produce accessors. + - The documented dependency wiring assumes a SwiftPM app manifest. For an + `.xcodeproj` or `.xcworkspace`, do not invent package or target wiring. + If either requirement is unmet, stop the bridge bootstrap without modifying + the app. Preserve any installed production or TestFlight build. Prefer an + existing real-device XCUITest harness; when a separate QA build is needed, + use an isolated bundle identifier and non-production entitlements so it can + coexist with the production app. Report fixture-driven state, provider UI, + and actual external-provider success as distinct evidence tiers. +2. Walk the app source (passed as `--source `) and identify all `@Observable` classes. Note any property immediately preceded by the generator marker comment `// @Snapshotable` — those are the snapshot-eligible fields. The marker is a comment so it composes with the `@Observable` macro. Each @@ -897,7 +910,7 @@ fi Optional compositions. Keys must be unique across observable classes. Codegen stops with a source diagnostic instead of emitting a broken or lossy harness when any of these constraints is violated. -2. Show the user the accessor list and ask whether to install the DebugBridge +3. Show the user the accessor list and ask whether to install the DebugBridge SPM dependency into their `Package.swift` (one AskUserQuestion). ## Phase 2: Bootstrap the device bridge diff --git a/ios-qa/SKILL.md.tmpl b/ios-qa/SKILL.md.tmpl index 78f9454b1..2e147c5ae 100644 --- a/ios-qa/SKILL.md.tmpl +++ b/ios-qa/SKILL.md.tmpl @@ -96,7 +96,20 @@ fi ## Phase 1: Read source, plan codegen -1. Walk the app source (passed as `--source `) and identify all `@Observable` +1. Before changing the app or replacing an installed build, verify that the + bridge is compatible with the project: + - The generator currently supports file-scope `@Observable` classes only; + `ObservableObject`, `@StateObject`, and other observation models do not + produce accessors. + - The documented dependency wiring assumes a SwiftPM app manifest. For an + `.xcodeproj` or `.xcworkspace`, do not invent package or target wiring. + If either requirement is unmet, stop the bridge bootstrap without modifying + the app. Preserve any installed production or TestFlight build. Prefer an + existing real-device XCUITest harness; when a separate QA build is needed, + use an isolated bundle identifier and non-production entitlements so it can + coexist with the production app. Report fixture-driven state, provider UI, + and actual external-provider success as distinct evidence tiers. +2. Walk the app source (passed as `--source `) and identify all `@Observable` classes. Note any property immediately preceded by the generator marker comment `// @Snapshotable` — those are the snapshot-eligible fields. The marker is a comment so it composes with the `@Observable` macro. Each @@ -107,7 +120,7 @@ fi Optional compositions. Keys must be unique across observable classes. Codegen stops with a source diagnostic instead of emitting a broken or lossy harness when any of these constraints is violated. -2. Show the user the accessor list and ask whether to install the DebugBridge +3. Show the user the accessor list and ask whether to install the DebugBridge SPM dependency into their `Package.swift` (one AskUserQuestion). ## Phase 2: Bootstrap the device bridge