@sun-asterisk/sungen 3.2.27 → 3.2.29

package/dist/orchestrator/templates/ai-src/skills/sungen-viewpoint/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: sungen-viewpoint
-description: '17 UI patterns x 4 viewpoints — structured checklist for test case
-  generation and review. Auto-loaded by create-test and review commands.'
+description: '32 UI patterns (17 web + 15 mobile-native) x 4 viewpoints — structured
+  checklist for test case generation and review. Auto-loaded by create-test and review commands.'
 user-invocable: false
 ---
 
 ## How to use this skill
 
-This skill is a **router**. The detailed checklists live in 5 group files — load only the ones relevant to the screen under test.
+This skill is a **router**. The detailed checklists live in 6 group files — load only the ones relevant to the screen under test. Groups A–E are the 17 platform-agnostic patterns; Group F is the mobile-native layer, read IN ADDITION on a `@platform:mobile/android/ios` unit.
 
 1. Read the **4 Viewpoints** and **Shared Checks** below (always).
 2. Identify which UI patterns the screen contains, resolve any overlap via **Pattern selection** below, then read **only** the matching group file(s) from the routing table.
@@ -36,6 +36,22 @@ This skill is a **router**. The detailed checklists live in 5 group files — lo
 | Login form / logout button | 15. Login / Logout | `group-e-identity.md` |
 | Sign-up form / SSO | 16. Register | `group-e-identity.md` |
 | Forgot / reset / change password | 17. Password Management | `group-e-identity.md` |
+| **Native app screen (`@platform:mobile/android/ios`) — read Group F IN ADDITION to the patterns above** | | |
+| Sheet sliding up from the bottom edge | 18. Bottom Sheet | `group-f-mobile-native.md` |
+| Persistent bar of 3–5 destinations at the bottom | 19. Tab Bar / Bottom Navigation | `group-f-mobile-native.md` |
+| Horizontal swipe on a row reveals actions | 20. Swipe-to-Delete Row | `group-f-mobile-native.md` |
+| Field opening an OS wheel / date / dropdown picker | 21. Native Picker | `group-f-mobile-native.md` |
+| Runtime permission — camera, location, notifications | 22. Permission Dialog | `group-f-mobile-native.md` |
+| Fingerprint / Face ID / app lock | 23. Biometric Prompt | `group-f-mobile-native.md` |
+| Leaves the app for the system camera or photo library | 24. Camera / Gallery Picker | `group-f-mobile-native.md` |
+| Push messages / notification routing | 25. Push Notification | `group-f-mobile-native.md` |
+| External link, notification payload, or QR opens a screen | 26. Deep-link Entry | `group-f-mobile-native.md` |
+| Offline banner, cached content, retry control | 27. Offline Banner | `group-f-mobile-native.md` |
+| First-launch intro slides / tutorial | 28. Onboarding Carousel | `group-f-mobile-native.md` |
+| Feed reloading by drag-down, paging, Load More | 29. Pull-to-Refresh List | `group-f-mobile-native.md` |
+| Any text field — the soft keyboard covers the screen | 30. Soft-Keyboard Overlap | `group-f-mobile-native.md` |
+| List of switches / preferences | 31. Settings Toggle List | `group-f-mobile-native.md` |
+| Every mobile screen (background, rotate, relaunch) | 32. App Lifecycle & Orientation | `group-f-mobile-native.md` |
 
 ## Pattern selection (precedence & inheritance)
 
@@ -54,6 +70,8 @@ A screen often matches several patterns at once — a login screen is *both* a f
    | Both a keyword box and filter controls | Apply **8. Search** *and* **9. Filter** (Search = free-text match; Filter = structured narrowing) + one combined AND-logic scenario |
    | A form rendered inside an overlay | Apply the form's pattern (1/4/5/15…) for fields/submit **and** **12. Modal/Dialog** for open/close/focus-trap/backdrop |
 
+5. **On mobile, Group F is ADDITIVE — never a replacement.** A native screen is still whatever it functionally is: a native login screen is **15**, a native product list is **10**, and the harness routes such a screen to `auth` / `ecommerce-list` deliberately, not to a `mobile-*` page-type. Route by function first (1–17), then add the Group F patterns for the native surfaces present, and generate each check **once** — a native form is **1. Form & Inputs** *and* **30. Soft-Keyboard Overlap**, with the field rules living only in pattern 1. `group-f-mobile-native.md` carries the theme↔catalog map and the precedence detail.
+
 ## 4 Viewpoints
 
 | VP | Focus | Tag |
@@ -90,16 +108,32 @@ The 4 viewpoints above are the *generic* axes. On a domain screen, the `VP-<CAT>
 Generate **once per screen**, do not repeat for each pattern.
 Each pattern only points back with "Shared checks applied: [name]".
 
-| Check | Condition → Expected | VP | Priority |
-|---|---|---|---|
-| **Loading State** | Data fetch in progress → spinner/skeleton shown, user cannot interact | UI | @normal |
-| **Empty State** | Query returns 0 records → clear message shown, layout does not break | UI | @normal |
-| **XSS** | Script tag entered into a field → rendered as literal text, not executed | SEC | @high |
-| **SQL injection** | SQL payload entered into a field → DB unaffected, no data exposed | SEC | @high |
-| **URL Manipulation** | URL params wrong/missing/out-of-range → fallback to default, no 500 crash | SEC | @high |
+The `Platform` column decides which checks a screen owes. Applying the web three to a native
+screen is wasted work — a `<script>` payload cannot execute in a native text view and there is no
+URL to manipulate — while the native surfaces (deep-link params, clipboard, the recents thumbnail)
+go unchecked unless they are named here.
+
+| Check | Condition → Expected | VP | Priority | Platform |
+|---|---|---|---|---|
+| **Loading State** | Data fetch in progress → spinner/skeleton shown, user cannot interact | UI | @normal | both |
+| **Empty State** | Query returns 0 records → clear message shown, layout does not break | UI | @normal | both |
+| **XSS** | Script tag entered into a field → rendered as literal text, not executed | SEC | @high | web |
+| **SQL injection** | SQL payload entered into a field → DB unaffected, no data exposed | SEC | @high | web |
+| **URL Manipulation** | URL params wrong/missing/out-of-range → fallback to default, no 500 crash | SEC | @high | web |
+| **Deep-link param injection** | An external link carries a traversal / script / oversized param → treated as data, no crash, no privileged screen reached | SEC | @high | mobile |
+| **Clipboard leak** | A field holding sensitive data (password, token, card) → the value cannot be copied out, or is excluded from the clipboard | SEC | @high | mobile |
+| **Recents / screenshot leak** | Background the app on a screen showing sensitive data → the app-switcher thumbnail is masked, screenshots blocked where the spec requires it | SEC | @high | mobile |
+| **Root / jailbreak posture** | The app runs on a rooted/jailbroken device → the spec's response (warn, degrade, or block), never a silent full-trust run | SEC | @normal | mobile |
+| **Certificate pinning** | Traffic through an intercepting proxy with a substituted certificate → the app refuses the connection rather than transmitting | SEC | @high | mobile |
+| **Permission over-request** | Cold launch → only the permissions the current feature needs are requested, and each is asked in context | SEC | @normal | mobile |
 
 > **SQL injection — 2 layers for search/LIKE fields**: (1) field-level: UI blocks special chars → `@high` automated; (2) API-level: if the field reaches a LIKE query (search, partial-match), send `1 OR 1=1` straight to the API endpoint (bypassing the UI) → verify a parameterized query is used → `@high @manual`. Missing layer 2 = a real attack vector is overlooked even when field validation is correct.
 
+> **Two mobile edges the table simplifies.** A screen rendered inside a **WebView** is web for these
+> purposes — apply XSS there. And a native app hits the same API as the web client, so the API-level
+> SQL-injection layer above is still owed by the *system*; it is just not a screen-unit check on a
+> mobile unit. Record it once at the API layer (`qa/api/`), not per mobile screen.
+
 ---
 
 ## Security Tag Rules
@@ -108,6 +142,8 @@ For VP-SEC scenarios testing **unauthorized access** (no login, wrong role, dire
 - Use the **`@no-auth`** tag — runs without authentication to verify the redirect/block.
 - Do NOT use `@manual` for these — they are automatable.
 
+On **web** the redirect target is a URL, so asserting the page is a real check:
+
 ```gherkin
 @high @no-auth
 Scenario: VP-SEC-001 Unauthenticated user cannot access admin page
@@ -115,4 +151,17 @@ Scenario: VP-SEC-001 Unauthenticated user cannot access admin page
   Then User see [Login] page
 ```
 
+On **mobile** that same shape is a false pass. A native app has no URL: the assertion compiles to an
+empty comment and reports **SG-W022**, so the scenario goes green having proven nothing. Assert a
+marker element that only exists on the login screen, plus the protected screen's own marker going
+`is hidden`:
+
+```gherkin
+@high @no-auth @platform:mobile
+Scenario: VP-SEC-001 An unauthenticated launch stops at the login screen
+  Given User is on [Login] screen
+  Then User see [Login Submit] button
+  And User see [Account Name] is hidden
+```
+
 Use `@manual` only when the environment truly cannot be set up automatically.

package/dist/orchestrator/templates/ai-src/skills/sungen-viewpoint/group-d-display.md

@@ -147,6 +147,7 @@ See `SKILL.md` for the 4 Viewpoints, Shared Checks, and Security Tag Rules.
 
 - A menu item for a restricted page is shown but the user has no permission → click → a 403 page; or the item is hidden from the menu (verify the DOM has no link and the API returns no data)
 - Direct URL access to a restricted page while not logged in → redirect to Login, the URL is preserved so post-login redirects correctly
+- **The oracle for "role X can open screen Y" is rendered content, not the URL.** A client-side router shows the destination URL before the permission check answers; assert a heading/landmark of the screen (or give its page selector an `anchor:`) so a late 403 bounce fails the case
 
 ---
 

package/dist/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/dist/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}}` |

package/dist/orchestrator/templates/specs-url-assert.d.ts

@@ -64,4 +64,35 @@ export declare function joinPath(base: string, path: string, declared?: string |
  *                      at all constrains the path only (the compiler warns: SG-W014).
  */
 export declare function urlMatches({ pathname, declared, dataRef }: UrlExpectation): (u: URL) => boolean;
+/**
+ * `toHaveURL` is a polling assertion: it passes on the FIRST sample that matches. A client-side
+ * router pushes the destination URL before the route guard or the API has answered, so a user
+ * with no permission is "on" `/items/detail` for a few hundred milliseconds — long enough for
+ * the assertion to sample it, pass, and end the test green — and is then bounced to `/forbidden`
+ * with no assertion left to see it. A real project shipped a permission matrix on that oracle;
+ * the 403s were found by hand (#662).
+ *
+ * `expectPage` is the page oracle `see [X] page` compiles to now. Arriving is not enough: the URL
+ * has to be STILL matching once the page has settled.
+ *   1. arrive   — the same predicate `toHaveURL` always used;
+ *   2. settle   — wait for network to go quiet (bounded: an app that polls forever must not hang
+ *                 the test, so a timeout here is not a failure);
+ *   3. hold     — sample the URL over a settle window; the moment it stops matching, fail and
+ *                 NAME where it went, because that destination is the finding;
+ *   4. re-assert — the arrival predicate, once more, on the settled page.
+ *
+ * `SUNGEN_URL_SETTLE_MS` (default 1000) is the hold window; `SUNGEN_URL_NETWORKIDLE_MS` (default
+ * 3000) bounds step 2. Both are runtime knobs, so a slow environment is a config change, not a
+ * regenerate.
+ */
+export declare function expectPage(page: {
+    url(): string;
+    waitForLoadState(state: 'networkidle', opts?: {
+        timeout?: number;
+    }): Promise<void>;
+}, expectation: UrlExpectation, opts?: {
+    settleMs?: number;
+    networkIdleMs?: number;
+    assertUrl?: (matches: (u: URL) => boolean) => Promise<void>;
+}): Promise<void>;
 //# sourceMappingURL=specs-url-assert.d.ts.map

package/dist/orchestrator/templates/specs-url-assert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"specs-url-assert.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-url-assert.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAYrF;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,cAAc,GAAG,CAAC,CAAC,EAAE,GAAG,KAAK,OAAO,CAuC/F"}
+{"version":3,"file":"specs-url-assert.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-url-assert.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;GAiBG;AAIH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAYrF;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,cAAc,GAAG,CAAC,CAAC,EAAE,GAAG,KAAK,OAAO,CAuC/F;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE;IAAE,GAAG,IAAI,MAAM,CAAC;IAAC,gBAAgB,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,EAC3G,WAAW,EAAE,cAAc,EAC3B,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAAO,GACpH,OAAO,CAAC,IAAI,CAAC,CAyBf"}