@sun-asterisk/sungen 3.2.28 → 3.2.30

package/src/orchestrator/templates/ai-src/skills/sungen-viewpoint/group-f-mobile-native.md

@@ -0,0 +1,419 @@
+# GROUP F: MOBILE NATIVE
+
+> The user holds a device. The app is already launched, there is no URL, the OS interrupts, and a
+> finger is the only pointer. These are the concerns the 17 web patterns have no concept of.
+
+Patterns: 18. Bottom Sheet · 19. Tab Bar / Bottom Navigation · 20. Swipe-to-Delete Row · 21. Native Picker · 22. Permission Dialog · 23. Biometric Prompt · 24. Camera / Gallery Picker · 25. Push Notification · 26. Deep-link Entry · 27. Offline Banner · 28. Onboarding Carousel · 29. Pull-to-Refresh List · 30. Soft-Keyboard Overlap · 31. Settings Toggle List · 32. App Lifecycle & Orientation
+
+See `SKILL.md` for the 4 Viewpoints, the platform-split Shared Checks, and the Security Tag Rules.
+**Step syntax is NOT repeated here** — the step forms live in `sungen-gherkin-syntax` (Platform
+Support + divergence table) and `sungen-mobile-gestures` (the gesture and device vocabulary). This
+file answers only *what to check*. Every step quoted below compiles on the Appium adapter; check
+`docs/spec/step-support-matrix.md` before inventing one.
+
+---
+
+## Read this first: mobile is web patterns PLUS Group F, never instead of
+
+A mobile screen is still whatever it functionally is. A native login screen is **15. Login** and a
+native product list is **10. List / Card View** — those patterns carry the business rules, and the
+harness deliberately routes such a screen to `auth` / `ecommerce-list`, not to a `mobile-*`
+page-type. Group F adds the **platform** concerns on top and never restates the functional ones.
+
+Precedence, in order:
+
+1. **The functional pattern wins.** Route the screen by what it does (1–17), exactly as on web.
+2. **Then add the Group F patterns for the native surfaces present.** A native form screen is
+   **1. Form & Inputs** *and* **30. Soft-Keyboard Overlap** — the field rules are generated once, in
+   pattern 1; pattern 30 adds only the keyboard concern.
+3. **Generate each check once.** If a Group F row would repeat a check the functional pattern
+   already produced, drop the row — a duplicate scenario costs review time and scores nothing.
+4. **`is on [X] screen` is the app-launch anchor, not navigation.** It compiles to an empty comment
+   *by design* (the wdio capabilities launched the app). Change screens with a real tap or gesture;
+   an active `open [X] page` / `navigate to` on mobile reports **SG-W026** because it promises a
+   navigation it does not perform.
+5. **Reset between scenarios is a tag, not a step** — `@reset:none|soft|data|full` on the Feature.
+   A step that tries to establish app state (`Given the user is logged out`) reports **SG-W023**.
+
+---
+
+## Theme coverage map — the contract with the harness
+
+`sungen audit` scores a mobile screen against `universal-viewpoints.yaml`. This table is the
+authoritative link between what that catalog scores and what generates it; a
+`tests/ai-skills/mobile-viewpoint-catalog-parity.run.ts` gate fails if the two ever drift apart.
+
+Read it in the direction you need: **generating** → find the themes of your page-type and go to the
+pattern named; **reviewing** → any theme with no scenario is a scored gap.
+
+| Theme | Page-type | Oracle | Generated by |
+|---|---|---|---|
+| `theme:content-visibility` | `mobile-home` | sighting | **19** Tab Bar / Bottom Navigation |
+| `theme:navigation-correctness` | `mobile-home` | sighting | **19** Tab Bar / Bottom Navigation |
+| `theme:list-data` | `mobile-list` | **data** | **29** Pull-to-Refresh List |
+| `theme:refresh-correctness` | `mobile-list` | **data** | **29** Pull-to-Refresh List |
+| `theme:scroll-reachability` | `mobile-list` | **data** | **29** Pull-to-Refresh List · **20** Swipe-to-Delete Row |
+| `theme:detail-data` | `mobile-detail` | **data** | `group-c` **10. List / Card View** — a native detail screen's data oracle is generic; Group F adds no native concern |
+| `theme:list-detail-consistency` | `mobile-detail` | **data, cross-screen** | a **flow**: `User remember [List Item] text as {{v}} … User see [Detail Title] text contains {{v}}`. On a single screen this is honestly `@manual` deferred-to-flow, never a shallow sighting |
+| `theme:field-validation` | `mobile-form` | **data** | `group-a` **1. Form & Inputs** · **21** Native Picker for picker-backed fields |
+| `theme:keyboard-overlap` | `mobile-form` | sighting | **30** Soft-Keyboard Overlap |
+| `theme:submit-correctness` | `mobile-form` | **data** | `group-a`/`group-b` **1** / **4** / **5** |
+| `theme:credential-validation` | `mobile-auth` | **data** | `group-e` **15. Login / Logout** · **23** Biometric Prompt |
+| `theme:session-persistence` | `mobile-auth` | **data** | **32** App Lifecycle & Orientation |
+| `theme:toggle-state-correctness` | `mobile-settings` | **data** | **31** Settings Toggle List |
+| `theme:setting-persistence` | `mobile-settings` | **data** | **31** Settings Toggle List |
+| `theme:orientation-stability` | *universal* | reminder | **32** App Lifecycle & Orientation |
+| `theme:connectivity-degraded` | *universal* | reminder | **27** Offline Banner |
+| `theme:app-lifecycle-resume` | *universal* | reminder | **32** App Lifecycle & Orientation |
+| `theme:permission-prompt` | *universal* | reminder | **22** Permission Dialog |
+| `theme:gesture-reachability` | *universal* | reminder | **20** Swipe-to-Delete Row · **29** Pull-to-Refresh List |
+| `theme:deep-link-entry` | *universal* | reminder | **26** Deep-link Entry |
+
+**Oracle column — this is the whole point of the phase-06 catalog.** A theme marked **data** is not
+covered by seeing the screen: it needs a value assertion (`text contains {{v}}`, `message contains
+{{v}}`, `field with {{v}}`). A suite that only asserts presence scores as *thin* even with every
+theme "covered". A **reminder** theme is real but unscored — it applies to some mobile screens and
+not others, so generate it when the screen owes it, not to satisfy a gate.
+
+**Patterns 18, 21, 24, 25, 28 carry no scored theme.** They are native surfaces the catalog does not
+score, because not every mobile screen has them. Generate them for real coverage; do not expect a
+score change.
+
+### Being on mobile does not select a `mobile-*` page-type {#page-type-selection}
+
+A mobile target considers the mobile page-types **and the web ones**, and the winner is decided by
+how many `detect_keywords` your scenarios and viewpoints actually hit — at least **2** distinct
+keywords, and at least **1** more than the runner-up. Nothing about the target being mobile tips the
+scale.
+
+The consequence catches people out on the two most ordinary screens:
+
+| You wrote | Selected type | Because |
+|---|---|---|
+| a login screen using *login · password · sign in · credential* | `auth` (web) | those are `auth`'s keywords; `mobile-auth` matches on *biometric · fingerprint · face id · touch id · app lock* |
+| a form using *form · submit · field · input · validation* | `form` (web) | `mobile-form` matches on *soft keyboard · keyboard overlap · hide keyboard · on-screen keyboard · keyboard covers* |
+
+So a mobile login screen is scored against the web `auth` themes, and `theme:session-persistence` /
+`theme:credential-validation` are never demanded of it. That is the catalog's stated philosophy — a
+native page-type is selected by native vocabulary, not by the platform flag — but it means **writing
+a biometric scenario is how you opt in**, not a bonus on top.
+
+**Opting into `mobile-form` costs an `@platform:android` tag.** The vocabulary that selects it is
+keyboard vocabulary, and `hide the keyboard` is Android-only: on iOS the step is guarded out with
+**no throw**, so a scenario written to reach this page-type would pass on iOS having done nothing.
+Tag such a feature `@platform:android` — see **30. Soft-Keyboard Overlap**. `mobile-auth` has no
+equivalent cost; biometric vocabulary runs on both.
+
+Fewer than 2 hits, or a tie, and the page-type is **undetermined**: no themes are required at all and
+the gate passes leniently. A near-miss therefore reads as a pass, not as a gap.
+
+**To settle it deliberately, declare it.** `page-type: mobile-auth` in `test-viewpoint.md` overrides
+detection outright — no keyword counting, no ties. Use that when the screen genuinely owes the native
+themes and the prose does not happen to say the magic words.
+
+*(Keywords above are copied from `universal-viewpoints.yaml`; that file is the source of truth if the
+two ever disagree.)*
+
+---
+
+## 18. Bottom Sheet
+
+**Apply when**: content slides up from the bottom edge over the current screen — a share sheet, a
+filter sheet, an action sheet.
+
+**Shared checks applied**: Loading State
+
+| Check | Condition → Expected | VP | Priority | Theme |
+|---|---|---|---|---|
+| Sheet opens | Tap the trigger → the sheet's own title/content is visible | UI | @high | — |
+| Sheet closes, **proven** | Swipe down on the sheet → `Then User see [Sheet] is hidden`. `dismiss [X]` is best-effort and never fails, so it can only be SETUP — a closure claim needs the hidden assertion | LOGIC | @high | — |
+| Scrim tap | Tap outside the sheet → it closes (or is explicitly modal and does not) | LOGIC | @normal | — |
+| Content behind is inert | While the sheet is up, the underlying control does not react to a tap | LOGIC | @normal | — |
+| Half → full expansion | Swipe up on a half-height sheet → the previously clipped row becomes visible | UI | @low | — |
+
+---
+
+## 19. Tab Bar / Bottom Navigation
+
+**Apply when**: a persistent bar of 3–5 destinations sits at the bottom (or top) of the app.
+
+**Shared checks applied**: Loading State · Empty State
+
+| Check | Condition → Expected | VP | Priority | Theme |
+|---|---|---|---|---|
+| Landing content | The launch screen shows its own content, not an empty shell | UI | @high | `theme:content-visibility` |
+| Tab switches screen | Tap another tab → a marker unique to the destination is visible **and** the origin's own marker `is hidden` | LOGIC | @high | `theme:navigation-correctness` |
+| Active indicator | After switching → the tapped tab reads selected, the previous one does not | UI | @normal | `theme:content-visibility` |
+| State is kept per tab | Scroll a list, leave the tab, come back → the same position/filters, not a reset | LOGIC | @normal | `theme:navigation-correctness` |
+| The bar occludes content | The last list row sits under the floating bar → `User tap top of [Last Row] row`. **`scroll to` cannot fix this** — `scrollIntoView` is a no-op on an element already inside the viewport, occluded or not | LOGIC | @high | `theme:navigation-correctness` |
+
+> Two markers, not one. "Left Home" asserted only by seeing the destination passes when the app
+> never moved and both screens share an element. Assert the destination marker AND the origin
+> marker going `is hidden`.
+
+---
+
+## 20. Swipe-to-Delete Row
+
+**Apply when**: a horizontal swipe on a list row reveals actions (delete, archive, pin).
+
+**Shared checks applied**: Empty State
+
+| Check | Condition → Expected | VP | Priority | Theme |
+|---|---|---|---|---|
+| Swipe reveals the action | `User swipe left on [List Item] row` → the action button is visible | UI | @high | `theme:gesture-reachability` |
+| Delete removes the row's DATA | Confirm the delete → the removed value is gone from the list: `User see all [List Item] text contains {{remaining_label}}`, not merely "the row is hidden" | LOGIC | @high | `theme:scroll-reachability` |
+| Swipe back cancels | Swipe the row the other way → the action hides, nothing was deleted | LOGIC | @normal | `theme:gesture-reachability` |
+| Undo | An undo affordance appears → tapping it restores the row's value | LOGIC | @normal | `theme:scroll-reachability` |
+| Off-screen row | The target row is below the fold → `User scroll to [Last List Item] row` first, then swipe | LOGIC | @normal | `theme:gesture-reachability` |
+| Last row deleted | Delete the only row → the empty state shows, the layout does not break | UI | @normal | — |
+
+---
+
+## 21. Native Picker
+
+**Apply when**: a field opens an OS picker — a wheel/spinner, a date picker, a dropdown sheet.
+
+**Shared checks applied**: (no default shared check)
+
+| Check | Condition → Expected | VP | Priority | Theme |
+|---|---|---|---|---|
+| Selection lands on the field | `User select {{country}} in [Country Picker] dropdown` → `Then User see [Country Picker] text contains {{country}}` | VAL | @high | `theme:field-validation` |
+| Cancel keeps the old value | Open the picker, cancel → the field still holds its previous value | LOGIC | @normal | `theme:field-validation` |
+| Constrained range | A date picker with a min/max → an out-of-range value cannot be selected, or is rejected with the spec's message | VAL | @high | `theme:field-validation` |
+| Dependent picker | Choosing a parent value re-populates the child picker and clears a now-invalid child selection | LOGIC | @high | `theme:field-validation` |
+
+> There is no `<select>` in a native tree. Which template a `select` step reaches is decided by the
+> **selector's role**, not the step text: `role: combobox|listbox` → the native picker path,
+> no role → a custom-dropdown two-tap. Both emit the same open-then-tap shape on mobile, so declare
+> the role in `selectors.yaml` and assert the field afterwards rather than assuming.
+
+---
+
+## 22. Permission Dialog
+
+**Apply when**: the screen needs a runtime permission — camera, location, notifications, contacts.
+
+**Shared checks applied**: Permission over-request
+
+| Check | Condition → Expected | VP | Priority | Theme |
+|---|---|---|---|---|
+| Granted path | `User grant camera permission` → the gated feature works and its content is visible | LOGIC | @high | `theme:permission-prompt` |
+| Asked only in context | The prompt appears when the feature is used, not on cold launch | UI | @normal | `theme:permission-prompt` |
+| Denied path | Deny → an in-app explanation with a route to Settings, **never a crash or a silent dead button**. No step denies a permission, so this is `@manual:M10` unless the project ships a selector for the OS dialog | LOGIC | @high | `theme:permission-prompt` |
+| Never-ask-again | Deny twice, relaunch → the app must not loop the request; shows the Settings route instead. `@manual:M10` | LOGIC | @normal | `theme:permission-prompt` |
+| Revoked while running | Revoke in Settings and return → the app re-checks rather than using a stale grant. `@manual:M10` | LOGIC | @normal | `theme:permission-prompt` |
+
+> `grant [X] permission` is implemented on **both** OSes (Android `changePermissions`, iOS
+> Simulator `setPermission`) — iOS additionally needs the `applesimutils` binary or the driver
+> fails loud with the install hint. Only the *granted* cell is automatable today; the other three
+> carry `@manual:M10` (device/OS capability), which is a reason code, not an excuse.
+
+---
+
+## 23. Biometric Prompt
+
+**Apply when**: the app authenticates with fingerprint / Face ID, or locks behind a biometric gate.
+
+**Shared checks applied**: (no default shared check)
+
+| Check | Condition → Expected | VP | Priority | Theme |
+|---|---|---|---|---|
+| Match unlocks | `User pass biometric authentication` → the protected screen's own data is visible | LOGIC | @high | `theme:credential-validation` |
+| Non-match is refused | `User fail biometric authentication` → the app stays locked and shows the spec's error, and the passcode fallback is offered | VAL | @high | `theme:credential-validation` |
+| Fallback path | Decline biometrics → the password form is reachable and works | LOGIC | @high | `theme:credential-validation` |
+| Not enrolled | No enrolled biometric on the device → the app falls back silently, no error dialog | LOGIC | @normal | `theme:credential-validation` |
+| Lock-out | Repeated non-matches → the OS lock-out is handled with the passcode route, not a stuck screen. `@manual:M11` | LOGIC | @normal | `theme:credential-validation` |
+
+> Emulator/Simulator ONLY (Android `mobile: fingerprint` needs finger 1 enrolled; iOS
+> `sendBiometricMatch`). A real device rejects the command and the step fails loud — on a real-device
+> lane these are `@manual:M11`.
+
+---
+
+## 24. Camera / Gallery Picker
+
+**Apply when**: the flow leaves the app for the system camera or photo library and returns with a file.
+
+**Shared checks applied**: Permission over-request
+
+| Check | Condition → Expected | VP | Priority | Theme |
+|---|---|---|---|---|
+| Return with a file | Pick an image → the app shows the thumbnail/filename and the upload control enables | LOGIC | @high | — |
+| Return with nothing | Cancel the picker → the app returns to the same state, no spinner left running | LOGIC | @high | — |
+| Permission refused | Library/camera access denied → the in-app explanation shows, the picker is not launched | LOGIC | @high | — |
+| Oversized / wrong type | A file past the spec's limit or of a rejected type → the spec's error, no upload | VAL | @high | — |
+| Killed while away | The OS reclaims the app while the camera is open → returning re-enters a valid state, not a blank screen. `@manual:M10` | LOGIC | @normal | — |
+
+> The system camera and library are **other apps**. Automating them means driving a foreign UI, so
+> most of this pattern is honestly `@manual:M11` (real camera) / `@manual:M10` (OS picker variance).
+> Write the checks anyway — a manual case with a real oracle beats a missing one.
+
+---
+
+## 25. Push Notification
+
+**Apply when**: the app receives push messages, or a notification deep-links into a screen.
+
+**Shared checks applied**: (no default shared check)
+
+| Check | Condition → Expected | VP | Priority | Theme |
+|---|---|---|---|---|
+| Shade shows the message | `User open notifications` → the notification's title/body matches the spec. **Android only** → tag the scenario `@platform:android` | UI | @high | — |
+| Tap routes correctly | Tap the notification → the app opens the screen the payload names, with that item's data | LOGIC | @high | — |
+| Foreground arrival | A push arrives while the app is open → in-app banner per spec, no OS shade duplicate | UI | @normal | — |
+| Badge / count | Reading the item clears the badge and the unread count | LOGIC | @normal | — |
+| Real token | Delivery from the real push service needs a real device token → `@manual:M11` | LOGIC | @high | — |
+
+> `open notifications` is the **notification shade** and XCUITest has no shade automation — the step
+> throws loud on iOS. Keep any scenario that uses it `@platform:android`; iOS coverage of the same
+> concern is `@manual:M10`.
+
+---
+
+## 26. Deep-link Entry
+
+**Apply when**: an external link, a notification payload, or a QR code opens a specific screen.
+
+**Shared checks applied**: Deep-link param injection
+
+| Check | Condition → Expected | VP | Priority | Theme |
+|---|---|---|---|---|
+| Cold-start entry | `User open deep link {{item_url}}` from a killed app → the target screen shows **that item's** data, not the default screen | LOGIC | @high | `theme:deep-link-entry` |
+| Warm entry | The same link while the app is running → routes without losing the current stack in a way the spec forbids | LOGIC | @high | `theme:deep-link-entry` |
+| Auth-gated target | A deep link to a protected screen while signed out → the login screen, and after signing in the app lands on the original target | SEC | @high | `theme:deep-link-entry` |
+| Unknown / stale target | A link to a deleted or non-existent id → the spec's not-found state, never a crash or a blank screen | LOGIC | @high | `theme:deep-link-entry` |
+| Malicious param | A path-traversal / script / oversized param in the link → treated as data, no crash, no privileged screen reached | SEC | @high | `theme:deep-link-entry` |
+
+---
+
+## 27. Offline Banner
+
+**Apply when**: the screen reacts to connectivity — an offline banner, cached content, a retry button.
+
+**Shared checks applied**: Loading State · Empty State
+
+All scenarios here need `@platform:android`: connectivity is toggled with `mobile: setConnectivity`
+and XCUITest cannot toggle it, so the step throws loud on iOS.
+
+| Check | Condition → Expected | VP | Priority | Theme |
+|---|---|---|---|---|
+| Banner appears | `User turn wifi off` → the offline banner is visible with the spec's text | UI | @high | `theme:connectivity-degraded` |
+| Cached content survives | Offline on a screen already loaded → the previously fetched values are still asserted, not a blank list | LOGIC | @high | `theme:connectivity-degraded` |
+| Action while offline | Submit while offline → a clear failure message and the entered data is preserved, never a silent loss | LOGIC | @high | `theme:connectivity-degraded` |
+| Recovery | Turn connectivity back on → the banner goes `is hidden` and the data refreshes without a manual reload | LOGIC | @high | `theme:connectivity-degraded` |
+| Cold launch offline | Launch with no connection → the offline state, not an indefinite spinner | UI | @normal | `theme:connectivity-degraded` |
+
+> Do **not** author a cleanup step to restore connectivity "in case the test dies". The generated
+> `wdio.conf.ts` restores the baseline (airplane off, wifi/data/location on) in `onPrepare` /
+> `onComplete`, so even a run whose Appium session died mid-toggle heals itself.
+
+---
+
+## 28. Onboarding Carousel
+
+**Apply when**: first launch shows swipeable intro slides, a tutorial, or a what's-new sheet.
+
+**Shared checks applied**: (no default shared check)
+
+| Check | Condition → Expected | VP | Priority | Theme |
+|---|---|---|---|---|
+| Slides advance | Swipe left on the carousel → slide 2's own text is visible and slide 1's `is hidden` | UI | @high | — |
+| Page indicator | The dot/counter tracks the current slide | UI | @normal | — |
+| Skip / Done | Skip or finish → the app lands on the real first screen with its content loaded | LOGIC | @high | — |
+| Shown once | `User restart the app` after finishing → the onboarding `is hidden` and the app opens straight to the main screen | LOGIC | @high | — |
+| Reappears after reinstall | `User reinstall the app` → onboarding shows again (it is install-time state, not session state) | LOGIC | @normal | — |
+
+> "Shown once" is the classic false pass: asserting only that the main screen appears passes even
+> when the carousel is on top of it. Assert the carousel's own marker going `is hidden`.
+
+---
+
+## 29. Pull-to-Refresh List
+
+**Apply when**: a feed or list reloads by dragging down, pages as it scrolls, or has a Load More control.
+
+**Shared checks applied**: Loading State · Empty State
+
+| Check | Condition → Expected | VP | Priority | Theme |
+|---|---|---|---|---|
+| Rows carry the expected DATA | `User see all [List Item] text contains {{expected_label}}` — a row count or a sighting is **not** this check | VAL | @high | `theme:list-data` |
+| Refresh changes the data | `User pull to refresh [List] section` → `User see all [List Item] text contains {{expected_label}}` for the refreshed set, so a no-op refresh fails | LOGIC | @high | `theme:refresh-correctness` |
+| Spinner resolves | The refresh indicator appears and then goes `is hidden` — a stuck spinner is a real defect | UI | @normal | `theme:refresh-correctness` |
+| Off-screen item is reachable | `User scroll to [Last List Item] row` → `User see [Last List Item] text contains {{expected_last}}` | LOGIC | @high | `theme:scroll-reachability` |
+| Next page appends | Reaching the end loads more and **keeps** the earlier rows rather than replacing them | LOGIC | @high | `theme:scroll-reachability` |
+| Empty feed | No records → the empty state's own message, and pulling to refresh from it does not crash | UI | @normal | `theme:list-data` |
+
+> `scroll to [X]` has two measured failure modes worth knowing before you rely on it: it throws when
+> the screen has no `android.widget.ScrollView` node, and it is a **no-op** when the target is already
+> inside the viewport but hidden behind a floating bar. For the occluded case use `tap top of [X]`.
+
+---
+
+## 30. Soft-Keyboard Overlap
+
+**Apply when**: the screen has any text field — the keyboard covers roughly half the screen.
+
+**Shared checks applied**: (no default shared check)
+
+| Check | Condition → Expected | VP | Priority | Theme |
+|---|---|---|---|---|
+| Focused field stays visible | Tap the lowest field → the field itself is still visible above the keyboard | UI | @high | `theme:keyboard-overlap` |
+| The submit control is reachable | With the keyboard up, the primary action is either visible or reachable by scrolling — not permanently underneath | UI | @high | `theme:keyboard-overlap` |
+| Dismissing reveals what was covered | `User hide keyboard` → the element the keyboard covered is visible again. Tag `@platform:android`: the iOS path is guarded out with **no** throw, so on iOS the step does nothing and this oracle would pass having proven nothing | LOGIC | @high | `theme:keyboard-overlap` |
+| The error message is not hidden | A validation error on a bottom field → the message is visible with the keyboard up | VAL | @high | `theme:keyboard-overlap` |
+| Return-key action | The keyboard's Next/Done key moves focus or submits per spec | LOGIC | @normal | `theme:keyboard-overlap` |
+
+> This is the one Group F theme whose honest oracle is a **sighting**, not a value: after the
+> keyboard is gone the field and its action are visible again. Do not invent a data assertion here.
+
+---
+
+## 31. Settings Toggle List
+
+**Apply when**: a list of switches, preferences, or a profile-settings screen.
+
+**Shared checks applied**: (no default shared check)
+
+| Check | Condition → Expected | VP | Priority | Theme |
+|---|---|---|---|---|
+| Toggle reflects the stored state | `User see [Notifications Toggle] text contains {{expected_state}}` — read the state, do not assume the default | VAL | @high | `theme:toggle-state-correctness` |
+| Flipping takes effect | `User check [Notifications Toggle] checkbox` → the dependent UI appears/disappears **and** the toggle reads the new state | LOGIC | @high | `theme:toggle-state-correctness` |
+| Setting survives a restart | `User restart the app` → `User see [Notifications Toggle] text contains {{expected_state}}` | LOGIC | @high | `theme:setting-persistence` |
+| Failed save reverts | The save fails (offline / server error) → the toggle returns to its real state instead of lying | LOGIC | @high | `theme:setting-persistence` |
+| Dependent settings | Turning a parent off disables its children and their stored values are unchanged when it is turned back on | LOGIC | @normal | `theme:toggle-state-correctness` |
+
+> Use `check`/`uncheck`, never `click`, on a switch — those templates read the current state first
+> and are idempotent, so a re-run does not silently invert the setting.
+
+---
+
+## 32. App Lifecycle & Orientation
+
+**Apply when**: always. Every mobile screen can be backgrounded, rotated, and relaunched.
+
+**Shared checks applied**: Recents / screenshot leak
+
+| Check | Condition → Expected | VP | Priority | Theme |
+|---|---|---|---|---|
+| Resume restores the screen | `User background the app for 5 seconds` → the same screen with its own data, not an empty shell or a re-login | LOGIC | @high | `theme:app-lifecycle-resume` |
+| In-progress input survives | Background mid-form → returning keeps the typed values (or clears them deliberately per spec) | LOGIC | @high | `theme:app-lifecycle-resume` |
+| Session survives a restart | `User restart the app` → `User see [Account Name] text contains {{user_name}}` | LOGIC | @high | `theme:session-persistence` |
+| Rotation keeps state | `User rotate to landscape` → the content and any entered values survive; `User rotate to portrait` restores the layout | UI | @normal | `theme:orientation-stability` |
+| Rotation does not duplicate work | Rotating mid-load does not fire a second request or double-submit | LOGIC | @normal | `theme:orientation-stability` |
+| Process death | The OS kills a backgrounded app and the user returns → the screen is restored from saved state, not a crash. Not expressible as a step → `@manual:M10` | LOGIC | @high | `theme:app-lifecycle-resume` |
+
+> `restart the app` (kill → relaunch) is THE persistence oracle — reach for it for session,
+> setting, dismissal and show-once claims. `reinstall the app` clears install-time state instead,
+> and requires the session to have installed via `APP_APK` / `IOS_APP`; attaching by package makes
+> the step fail loud with that exact fix.
+
+---
+
+## ⚡ Cross-pattern interactions
+
+- **19 + 30**: The keyboard opens over a bottom tab bar → the bar must not float above the keyboard, and the focused field stays visible.
+- **22 + 24**: Permission denied then granted inside one flow → the picker becomes usable without a relaunch.
+- **26 + 15**: A deep link into a protected screen while signed out → login, then land on the original target, not the default home screen.
+- **27 + 29**: Pull to refresh while offline → the offline message, and the previously loaded rows are still asserted rather than cleared.
+- **32 + 31**: Change a setting, background the app, return → the change is still applied and still reads correctly.

package/src/orchestrator/templates/playwright.config.ts

@@ -84,9 +84,16 @@ export default defineConfig({
   /* Output file path is controlled by PLAYWRIGHT_JSON_OUTPUT_NAME env var for per-screen isolation. */
   /* When SUNGEN_ENV is set, the env name is inserted before `.json` so locale */
   /* runs don't overwrite each other (e.g. `<name>-test-result.vi.json`). */
+  /* The sanitize reporter rewrites the JSON report's absolute machine paths to project-relative ones on
+     exit — the file is committed next to the spec, so a username or machine layout must not ship in it.
+     Registered only while its file exists (`sungen init`/`generate`/`update` write it): a cleaned
+     specs/generated must not stop Playwright from loading this config. */
   reporter: [
     ['html'],
     ['json', { outputFile: resolveJsonOutputFile() }],
+    ...(fs.existsSync(path.join(__dirname, 'specs', 'generated', 'report-path-sanitize-reporter.ts'))
+      ? [['./specs/generated/report-path-sanitize-reporter.ts'] as [string]]
+      : []),
   ],
   /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
   use: {

package/src/orchestrator/templates/readme.md

@@ -150,7 +150,7 @@ Add to `.vscode/settings.json` to auto-load Gherkin syntax when editing `.featur
 | Pattern | Example |
 |---|---|
 | Navigate | `User is on [login] page` |
-| Navigate with data | `User is on [user detail] page with {{user_id}}` |
+| Navigate with data | `User is on [user detail] page with {{user_query}}` — `{{v}}` is a query/fragment (`?id=200`, `#tab`) appended to the page value, never a bare id |
 | Click | `User click [Submit] button` |
 | Fill | `User fill [Email] field with {{email}}` |
 | Select | `User select [Country] dropdown with {{country}}` |