@sun-asterisk/sungen 3.2.27 → 3.2.29

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

@@ -63,7 +63,16 @@ instead; `--format both` writes both.
 every unit it did not export with the reason, and exits 0 as long as it wrote something — a
 scaffolded unit never blocks the ready ones.
 
-**Workbook**: `Testcases` sheet — parent rows + outline-level-1 variant sub-rows for **every**
+**Workbook** (matrix mode): four sheets — `Overview` (live roll-up over the two below), `Auto`,
+`Manual`, `Coverage`. Auto and Manual split **per variant**, so a **mixed item's parent row
+appears on both**, each side carrying only its own variants and rolling up only what is on that
+sheet — expect the same ID twice in the workbook, with two different numbers. Both detail sheets
+always exist even when one is empty. Layout is BM-2-901-13: band on rows 6/7/8, `*: Mandatory`
+legend on row 12, the 16 headers `A..P` on row 13, data from row 14, frozen at `A14`.
+`Testcase type` (`K`) is variant-level (`Auto` · `Auto · Mocked` · `Manual (M6)`) and blank on a
+parent row. Full detail: `docs/spec/delivery-coverage-matrix-spec.md` §8.
+
+`Auto` / `Manual` — parent rows + outline-level-1 variant sub-rows for **every**
 item (single-variant included: the sub-row carries the source VP-id, resolved data, and the
 result/evidence entry). Sub-rows are **delta-only**: knowledge common to the whole item
 (precondition, trigger) is written ONCE on the parent; a child repeats only what distinguishes it
@@ -80,9 +89,9 @@ never a concatenation of variant titles.
 Variant Result cells hold exactly one of `Passed`/`Failed`/`Blocked`/`Pending`/`N/A` (dropdown) —
 that vocabulary is the contract: the parent Result and the summary band are **live Excel formulas**
 counting those words, so a parent label is always a composed `n/m Passed …` string (`All N/A` when
-every variant is N/A) and never a bare state word. **`N/A` leaves the denominator.** Evidence and
-Defect ID are separate columns; ID + Target frozen; ISO dates; landscape print with repeated
-header rows.
+every variant is N/A) and never a bare state word. **`N/A` leaves the denominator.** Note, Defect ID
+and actual result share one column `P`; the header row is frozen; ISO dates; landscape print with
+repeated header rows.
 
 `Coverage` sheet — requirement coverage table (every FR/TR/NFR id with an explicit status),
 target × category grid with explicit `—` gaps, dispositions, manifest. CSV mirrors the same model
@@ -201,7 +210,7 @@ The base sheet label comes from `base_locale:` (default **EN**). Undeclared env
 
 ## API delivery — extra worksheet
 
-For **api-kind units** (`qa/api/<area>/`), the `.xlsx` gains a final worksheet **`API detail`** (appended after Overview/Auto/Manual). The main BM-2-901-13 Testcases layout is unchanged. The CSV is unchanged (16-column, no extra sheet).
+For **api-kind units** (`qa/api/<area>/`), the `.xlsx` gains a final worksheet **`API detail`** (appended after Overview/Auto/Manual). The main BM-2-901-13 testcase-sheet layout is unchanged. The CSV is unchanged (16-column, no extra sheet).
 
 ### Required sources (API detail sheet only)
 

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

@@ -101,13 +101,15 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | `SG-W013` | A page assertion (`see [X] page` / `is on [X] page`) whose `[Ref]` has no `type: page` selector entry (or collides with a non-page entry) — the step falls back to the feature's own path (or `/<ref>/`) instead of `X`'s real URL, so the anchored assertion can never pass | Declare a `type: page` entry for `[Ref]` with its real URL; if the key collides with another type, disambiguate with a `--type` suffix (`sungen-selector-keys` § Collision rule) |
 | `SG-W014` | `[X] page with {{v}}` where `{{v}}`'s base test-data value carries no query and no fragment — the step checks the PATH only, asserting less than it reads as | Informational — pass a value like `?q=…` if you meant to assert a query, or drop `with {{v}}` for a bare page |
 | `SG-W015` | `see [X] card/item with {{n}}` where `{{n}}`'s test-data value is a **bare number** — this compiles to a TEXT assertion (`toHaveText('3')`), NOT a count. An author reaching for "3 cards are shown" gets an assertion that can only pass if the card's TEXT is literally the digit: a wrong test with no error. Scoped to container-ish element types (`card`/`item`/`option` + plurals); a text element asserting a numeric readout (`[Row Quantity] text with 4`) stays silent | For a COUNT use a form that has count semantics: `see [Ref] row with {{n}}` / `see [T] table with {{n}}`, or a list `should have count`. If the number really is the element's text, assert it on a **text/label** element instead |
+| `SG-W016` | A table step on a table located by CSS/testid whose value does not mention `table` and that declares no `rows:` — the table templates find rows by `getByRole('row')`; on a list built from `<div>`s that is 0 rows, so `is hidden`/`is empty` PASS without checking anything and counts/clicks time out (issue #688). A heuristic — the compiler cannot see the DOM — so it warns once per table | Declare the row shape on the TABLE entry (`rows: 'div.job-row'`, relative to the table) — it drives all seven table steps — or locate the table by `role: table` if it really is one. Do not put the shape on a row label's entry: that key positions ONE row |
 | `SG-E020` | A step matched a pattern, but the **active adapter ships no template** for it (e.g. a web-only step compiled under `platform: mobile`). The feature file still generates — that one step compiles to `throw new Error("[sungen] …")` naming the step, feature, pattern, template and adapter, so the failure is loud and traceable rather than a crashed build | Rephrase to a step the target adapter actually ships (see `sungen-gherkin-syntax` Platform Support section / `sungen-mobile-gestures`), or tag the scenario `@manual` with the platform reason |
 | `SG-E021` | The step carries a trailing **state clause** (`… is hidden`) that the pattern which matched it does not assert — the clause would be SILENTLY DROPPED. Worst shape in this table: it does not weaken an assertion, it can INVERT one. `see [X] page is hidden` matched `page-assertion` (priority 13) ahead of `is-hidden` (11), so the step compiled to `toHaveURL(...)` — asserting the page IS displayed, and passing. Also fires on `wait for [X] is checked` (a wait honours only `hidden`/`visible`/`disabled`/`enabled`; everything else silently fell back to `visible`) and on `row`/`column in [T] table … is <state>` for any state but `hidden` | Move the state onto the element that has it: `Then User see [X] checkbox is checked`. For a page, assert the page you expect (`Then User see [Other] page`) or a marker element (`Then User see [Banner] is hidden`). If sungen cannot express the check, tag the scenario `@manual`. The diagnostic names the pattern that swallowed the clause — that name tells you which form you actually hit |
-| `SG-W020` | The matched pattern **declares `platforms`** (today: `@mock`) and the active platform isn't among them. Caught before template lookup, so the diagnostic can name the native alternative directly | Drop `@mock` from a mobile unit (there is no Mock Driver on Appium) — use `@api`/`@query` or a `@manual` note instead |
+| `SG-W020` | The matched pattern **declares `platforms`** and the active platform isn't among them. Caught before template lookup, so the diagnostic names the alternative for the platform you are on. This is now the MAIN off-platform channel, not a corner case: the whole web-only set (`table-*`, `storage-*`, `route-assertion`, `tab-order`, `sorted`, `upload`, `alert-fill`) and the whole mobile-only set (gestures, device state, app lifecycle, device oracles) declare it, so the refusal arrives at compile time with a concrete substitute instead of at run time from inside a template. It still compiles to a `throw` — moving the message earlier never turns a refusal into a silent pass | Do what the message says: it carries the pattern's OWN `platformAlternative`, e.g. a table assertion on mobile → per-row accessibility-id assertions; `local storage` on mobile → assert the state via a UI element or `@api`/`@query`; a swipe on web → drive the control the swipe reveals. `@mock` on a mobile unit is the same shape (there is no Mock Driver on Appium) |
 | `SG-W021` | `use dialog` / `User is on [X] dialog` scope under the **mobile** adapter — the scope is recorded but no Appium template reads `inDialog`, so every following step resolves against the whole screen, not just the dialog | Don't rely on `scope: dialog`/`use dialog` for disambiguation on mobile — give the element inside the dialog its own unique accessibility-id/testid instead |
 | `SG-W022` | `Then User see [X] page` under the **mobile** adapter — a native app has no URL, so the step compiles to a bare COMMENT: it reads as an assertion, checks nothing, and the scenario passes whatever is on screen. Worse than a hard failure, because nothing ever goes red. (Its `is on [X] page` twin throws via `route-assertion`; `Given User is on [X] page` is the app-LAUNCH directive and correctly emits nothing) | Assert something actually on the screen — `Then User see [Some Header] text` / a screen-marker accessibility-id — instead of a page/URL check, or tag the scenario `@manual` |
 | `SG-W023` | A mobile **setup** step that emitted NO executable code, so a declared PRECONDITION is never established. `Given the user is logged out` matches `user-not-logged-in` → the `clear-auth` template, which on Appium is a bare COMMENT: mobile auth lives in the keychain/prefs, not in cookies, so no per-step action can clear it. The scenario then runs against whatever the PREVIOUS scenario left signed in and passes regardless — the same false-pass class as `SG-W022`, arriving through setup instead of assertion. Deliberately NOT a `throw` (an unestablished precondition weakens setup, it does not INVERT an assertion) | Declare a feature-level reset tier — `@reset:data` on the Feature — so each scenario starts from a wiped data layer; app state is reset in the `beforeEach` hook, not mid-scenario by a step. For BACKEND state (`database is empty`) the remedy is different: reset through a test API/script, or bind a `@query:` precondition, the same way the web adapter has to |
 | `SG-W024` | Two or more scenarios in one feature **share a name** and at least ONE carries a `@reset:` tag. The generated per-scenario tier lookup is keyed on the scenario NAME (a `@cases` title is built at runtime, so no compile-time key can match the rendered title), so every same-named scenario resolves to the SAME tier — including one that declared none, which then silently runs at its namesake's tier: a `@reset:none` chain broken, or a reinstall nobody asked for. Counted over EVERY scenario rather than the tagged subset, because the untagged twin is the one that gets the wrong tier and has no tag to be counted by | **Rename** the scenarios so each title is unique. Reported rather than resolved by precedence on purpose — two tests genuinely sharing one title cannot be told apart by a name-keyed lookup, so a rename is the only honest fix (silently picking a winner would be the same silent-discard shape as `SG-W021`) |
+| `SG-W026` | A mobile **active-navigation** step that emitted NO executable code, so a promised screen change never happens. `When User open [Settings] page` compiles to the one-line `navigation` template — a COMMENT noting the app was already launched by the wdio capabilities — so the step reads as "go to Settings" and goes nowhere; pair it with a `page` assertion (itself a no-op, `SG-W022`) and the scenario passes without ever touching the app. Scoped to the ACTIVE forms only: `Given User is on [X] page|screen` is the app-LAUNCH anchor and correctly emits nothing, so it is never reported. Deliberately NOT a `throw` — an unfulfilled navigation weakens the scenario rather than INVERTING an assertion, and throwing would break every mobile suite already carrying one | Change screens the way a user does — `When User tap [Settings] button` — then assert a marker on the new screen (`Then User see [Settings Header] text`). Keep `is on [X] screen` only as the feature's opening anchor. Note `generate --strict` fails on any diagnostic, so this code is blocking there from the day it lands |
 | `SG-E022` | The **generated spec file itself** is not parseable JS/TS, so NOTHING in it runs — Playwright reports one `SyntaxError` and every scenario in the unit is lost. A compiler self-check (`@babel/parser`) on the emitted code, added after a field report where the runtime-data marker post-processor mis-paired quote delimiters across two literals and the user only found out at `npx playwright test`. Reported, never thrown — the file is still written so you keep the artifact to inspect. **Unlike every other code in this table this one blames the COMPILER, not your `.feature`** | Nothing to fix in the Gherkin — this should be impossible. **Report it** with the `.feature` (and the step) the file was generated from, attaching the unparseable `.spec.ts`. Check first that you are running the project-local compiler (`npx sungen`), not an older global one |
 | `SG-E023` | The step carries an **assertion clause** (`matches "…"`, `contains`, `has text`) but the generated code is a BARE VISIBILITY check — the clause was swallowed by a catch-all and the test would pass whatever the element says. The sibling of `SG-E021`, for the clauses that are not states: `SG-E021` closed the state case declaratively, but a dropped `matches`/`contains`/`has text` still slid through (reproduced live: a `matches "<format>"` step compiled by an older sungen lost the assertion entirely, emitted no warning, and left a `toBeVisible()` that passed whatever the label said). Four separate defects arrived this way, so the step now compiles to a runtime `throw`. Deliberately narrow — fires only on the bare-visibility shape, so a pattern that genuinely consumed the clause (`is-hidden`, `contains`, `matches-format`, the state family, or a `filter({ hasText })` on a list member) is untouched | Either the phrasing is not the supported one for that clause — check the exact form in `sungen-gherkin-syntax` — or this sungen predates the step: verify you are running the project-local compiler (`npx sungen`), not an older global one |
 | `SG-E024` | A mobile **app-lifecycle** step (`User restart the app` / `User reinstall the app`) in a feature that declares no `Path:` app id. The lifecycle templates resolve the target app through `__resolveAppId()`, a helper the appium test-file template emits ONLY when the id is present, so the spec used to compile clean and then die at runtime with `ReferenceError: __resolveAppId is not defined` — taking the WHOLE spec down, not the one step, because the failure lands in a before hook. (Field case: a mobile unit scaffolded with the nav recipe in `--path` instead of `--reach`, so `Path` never carried an app id.) Now refused at compile time as a `throw` naming the missing line | Add the app id under the `Feature` line: `Path: com.example.app/.MainActivity \| com.example.app`. For a mobile unit `--path` carries the **APP ID** and `--reach` carries the navigation recipe — if the nav recipe ended up in `--path`, that is the mistake |
@@ -202,6 +204,51 @@ If `toHaveText` fails on an input → the Gherkin step has the wrong target type
 
 ---
 
+## Mobile Runtime Errors (Appium / WebdriverIO)
+
+**The fixes are NOT written here.** They live once, as data, in `driver-mobile/src/mobile-repair.ts`,
+and `sungen repair --screen <unit>` prints the matching one for the failure you actually got:
+
+```bash
+sungen audit --screen <unit>     # findings
+npx playwright test              # (or the wdio run) — leaves the result JSON
+sungen repair --screen <unit>    # → the concrete fix for each finding + each failure
+```
+
+This table is the INDEX into that catalog — symptom → rule id — so you can recognise a failure class
+by eye and know a rule already covers it. Two copies of a fix drift; one copy plus an index does not.
+`tests/ai-skills/error-mapping-repair-parity.run.ts` fails if this table and the catalog disagree in
+either direction.
+
+| What you see | Rule id | Class |
+|---|---|---|
+| `Element not found: ~key` / `no such element` | `mobile-element-absent` | selector |
+| `iOS geometry oracle: rect={…0x0…}` | `mobile-ios-offscreen` | selector |
+| `element click intercepted` / `is not clickable at point` | `mobile-tap-intercepted` | selector |
+| `Default scrollable element '//android.widget.ScrollView' not found` | `mobile-scroll-no-scrollable` | selector |
+| `A new session could not be created` | `mobile-session-not-created` | session |
+| `Could not proxy command to the remote server` / `socket hang up` | `mobile-driver-proxy-lost` | session |
+| `The instrumentation process cannot be initialized` | `mobile-instrumentation-failed` | session |
+| `No Chromedriver found that can automate Chrome '…'` | `mobile-chromedriver-mismatch` | session |
+| `@auth:<role> login did not complete` / `could not decide the login state` | `mobile-auth-session` | session |
+| `device log (logcat) did not contain "…"` | `mobile-device-log-silent` | oracle |
+| `[sungen] … web-only` / `not supported on the appium adapter` | `mobile-web-only-step` | compile (SG-W020/E020) |
+| `[sungen] step "…" matched no pattern` | `mobile-step-unmatched` | compile (SG-W001) |
+| `… needs the app id: the mobile lifecycle steps resolve …` | `mobile-lifecycle-no-app-id` | compile (SG-E024) |
+| `… This feature declares @platform:ios` | `mobile-ios-unsupported-step` | compile (SG-E025) |
+| `UNIVERSAL: missing theme(s): …` | `mobile-universal-theme` | audit |
+| `GATE: critical theme "…" has NO covering scenario` | `mobile-gate-theme-uncovered` | audit |
+| `GATE: critical theme "…" covered only by SHALLOW` | `mobile-gate-theme-shallow` | audit |
+| `VIEWPOINT-GESTURE-SUBSTITUTED: …` | `mobile-gesture-substituted` | audit |
+| `MANUAL-CODE-MISSING: …` | `mobile-manual-uncoded` | audit |
+| `PAGE-TYPE-UNDETERMINED: …` | `mobile-page-type-undetermined` | audit |
+
+A failure with no rule id is reported by `sungen repair` under **"No known rule (review manually)"**.
+That list is deliberately not empty-by-construction: a rule broad enough to match everything would
+hide the findings nobody has looked at yet.
+
+---
+
 ## Performance & Infrastructure Errors → Fix in `specs/base.ts`
 
 All generated `.spec.ts` import from `specs/base.ts` — shared context caching, navigation, overlay cleanup. AI **can and should** tune `base.ts` to match the project.

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

@@ -35,7 +35,7 @@ AND    →  inherits from preceding keyword
 ### Setup / Form / Interaction
 
 ```
-User is on [T] page | page with {{v}} | dialog
+User is on [T] page | page with {{v}} | dialog      # {{v}} = query/fragment ("?id=200", "#tab") APPENDED to the page value — a bare "200" onto "/x?id=199" gives "?id=199200"
 User fill [T] field | textarea | search | slider | date-picker with {{v}}   # date-picker: web only unless qa/app.yaml declares widgets.datepicker — appium refuses it
 User fill [T] uploader with {{f}}                                    [web]
 User clear [T] field
@@ -103,6 +103,9 @@ two content-filtered queries can hit different rows if the table re-renders in b
 ```
 # 1. Visibility: User see [T] type (NEVER add "is visible") | is hidden
 # 2. Text (toHaveText): User see [T] message | header | label with {{v}}
+#    `label` forks on the entry: declared by IDENTITY (xpath/accessibility-id/testid/id/css)
+#    → asserts THAT element contains {{v}} (add `exact: true` for a strict match); no entry,
+#    or `type: text` → matches the caption+value text pair anywhere on screen
 # 3. Partial (toContainText): User see [T] text contains {{v}}
 # 3b. Format (shape, not value): User see [T] label matches "yyyy/mm/dd ~ yyyy/mm/dd"
 # 4. Input (toHaveValue): User see [T] field | date-picker | search | slider with {{v}}
@@ -121,10 +124,28 @@ two content-filtered queries can hit different rows if the table re-renders in b
 > assert the page you expect (`Then User see [Other] page`); to say "this went away", assert a marker
 > element (`Then User see [Some Element] is hidden`).
 
+**Pattern 8 is a URL oracle, and a URL is not a rendered page.** `see [T] page` proves the router
+pushed a path — it does NOT prove the page rendered for this user. A client-side router pushes the
+destination BEFORE the route guard or the permission API has answered, so a user with no permission
+is "on" `/items/detail` for a few hundred milliseconds before being bounced to the 403 page. Since
+3.2.28 the step compiles to `expectPage(page, {…})` — arrive, let the page settle, HOLD the URL, and
+re-assert — so a late redirect fails and names where the user ended up. But the page having
+rendered is still unproven: **for permission / auth-guard / "role X can open screen Y" scenarios,
+give the page selector an `anchor:`** (a heading or landmark only the rendered page has) — every
+`see [T] page` on that screen then asserts the anchor too — or follow the page step with a content
+assertion. A scenario whose every `Then` is a page assertion is reported as `ORACLE-URL-ONLY`.
+
+```yaml
+detail:
+  type: 'page'
+  value: '/items/detail'
+  anchor: { type: 'role', value: 'heading', name: 'Item Detail' }   # the rendered-content proof
+```
+
 **Pattern 8 — the page assertion judges pathname AND query together.** Both `see [T] page` and
-`is on [T] page` (Then-side) compile to ONE web-first predicate — `toHaveURL(urlMatches({…}))`,
-which retries like any other assertion — comparing the **exact** pathname (anchored, trailing slash
-normalised) plus the query:
+`is on [T] page` (Then-side) compile to ONE web-first check — `expectPage(page, {…})`, built on
+`toHaveURL(urlMatches({…}))` and retrying like any other assertion — comparing the **exact** pathname
+(anchored, trailing slash normalised) plus the query:
 
 | step | asserts |
 |---|---|
@@ -135,6 +156,8 @@ normalised) plus the query:
 | `… page with {{v}}`, `v` = `/vi/search` (no query) | **path only**, and the compiler warns (`SG-W014`): the step asserts less than it reads as |
 | `… page with {{v}}`, `v` empty or key missing at run time | **throws, naming the key** — an unusable value is never a silent pass |
 
+**Navigating** with data (`Given User is on [T] page with {{v}}`) appends `{{v}}` to the page selector's value **verbatim** — no merging, by design (the primary use is injecting malformed query input, which the compiler must not sanitize). So the page value carries the PATH only and `{{v}}` carries the whole query: `value: '/job/detail'` + `job_query: "?id=200"`. A page value that already holds `?id=199` plus `{{v}}` = `"200"` navigates to `?id=199200`. A rooted `{{v}}` (`/other/path`) replaces the page's path; an absolute URL replaces everything.
+
 So pass `with {{v}}` whenever the URL carries state worth proving, and leave it off when the page
 must be reached clean. A dynamic segment in the selector value (`/users/:id/profile`) wildcards to
 `[^/]+` on its own, still anchored — `/users/42/profile/edit` does not match. Params compare
@@ -196,6 +219,15 @@ first contact row:
 ```
 → compiles to `expect(table.locator('tbody tr:first-child')).toContainText(v)` — the exact row must hold the value — and still enters row scope for `[Col] column` checks.
 
+**A list built from `<div>`s is a table only if you tell sungen what a row is.** Every table step finds rows by `getByRole('row')`; a `<div>` list has none, so `is hidden` and `is empty` would pass on 0 rows (asserting nothing) and counts/clicks would time out. Declare the row SHAPE on the **table** entry — `rows:` is relative to the table and drives all seven table steps:
+```yaml
+job table:
+  type: locator
+  value: 'div.job-list'
+  rows: 'div.job-row'        # what EVERY row matches — NOT a row label's entry
+```
+Two different keys, two meanings: `rows:` on the table = every row (the shape); a `type: locator` entry on a **row label** = ONE positioned row (`tbody tr:first-child`). A shape put on a row label fails at run time with a `toHaveCount(1)` message that points back here. A CSS-located table with no `rows:` gets `SG-W016`. On a shaped table `table row {{n}}` counts from the first data row (no header offset).
+
 ### Browser storage `[web]`
 
 ```
@@ -356,7 +388,7 @@ entirely (a *pattern* gap, not a template gap), which is what the catalogue belo
 
 **Mobile-only `[mobile]`** — the gesture catalog (swipe, long-press, pinch-zoom, pull-to-refresh,
 rotate, background/foreground, notifications, grant-permission, clipboard set, set-geolocation,
-hide-keyboard, tap-top-of) has no web counterpart, and neither do the lifecycle / device-state /
+hide-keyboard, tap-top-of, `go back`) has no web counterpart, and neither do the lifecycle / device-state /
 timing steps (`restart the app`, `reinstall the app`, `turn airplane mode|wifi|mobile data on|off`,
 `turn device location on|off` — the latter two Android-only, throw on iOS — the window
 assertions `see [X] disappear within N seconds` / `still visible after N seconds`, and the
@@ -369,8 +401,9 @@ Full syntax → `sungen-mobile-gestures`.
 | Step | Web | Mobile |
 |---|---|---|
 | `see [T] page` \| `page with {{v}}` | asserts path+query | **silent no-op** — asserts nothing; the scenario passes regardless. Assert a screen-marker element instead |
-| `is on [T] page` \| `open [T] page` (Given/When) | navigates via URL | no-op — the app is already launched; use tap/gesture steps for mobile screen changes |
+| `is on [T] page` \| `open [T] page` (Given/When) | navigates via URL | `is on` = the app-launch anchor, correctly a no-op. `open`/`navigate to` = a no-op that **reports `SG-W026`** — it promises a screen change and performs none; use tap/gesture steps instead |
 | `wait for [T] page` | waits for the URL | fixed `driver.pause(500)` settle — not a real wait condition |
+| `go back` (OS/hardware back) | **not a web step** — reports `SG-W020`; re-enter with `is on [X] page` or tag `@manual` | Android: `KEYCODE_BACK`, the real hardware key. iOS: WDA **navigation**-back, *not* the user's edge swipe-back (iOS has no hardware back). Distinct from `tap [Back] button`: system back skips the screen's own handler unless the app wires it |
 | `hover [T] icon \| row` | real hover | no-op — hover-revealed content is normally already visible on mobile; use `tap` |
 | `fill [T] alert with {{v}}` | fills native `prompt()` | no-op (comment only) — app-specific, handle manually |
 | `switch to [T] frame` | enters an `<iframe>` | switches a hybrid app's WebView context; no-op on a pure-native screen. **Needs `APPIUM_CHROMEDRIVER_AUTODOWNLOAD=1`** (.env.appium) or the switch fails with "No Chromedriver found". INSIDE the webview, selectors are **css/xpath only** — UiSelector-based types and the text-value asserts (`label with {{v}}`) don't apply there; assert element presence via css/xpath refs, then `switch to [main] frame` back |

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

@@ -34,6 +34,7 @@ user-invocable: false
 | **DEPTH** | business-critical scenarios assert only visibility/navigation | Replace `Then User see [X] page/section` with **observable data assertions**: `Then User see [X] with {{value}}`, `Then User see [T] table match data:`. Capture real expected values into `test-data.yaml`. |
 | **BALANCE** | secondary viewpoints (UI/validation/security) outweigh business-core | **Stop expanding** secondary viewpoints; generate the missing business-core scenarios first. Do not add more subscription/UI variants while core is thin. |
 | **TRACE** | scenarios use ad-hoc `VP-<CAT>-NNN` codes not linked to the viewpoint-overview | Make each scenario map to a viewpoint-overview id (align category codes, or add a mapping comment). |
+| **ORACLE-URL-ONLY** | every `Then` in the scenario is a page/URL assertion — it proves a path was pushed, not that the page rendered; on a permission/guard scenario a late 403 redirect turns it falsely green | Add `anchor:` to the page selector (one line per screen; every `see [X] page` on it becomes a content oracle) or a content assertion after the page step. Never delete the page step to silence it. |
 | **UNIVERSAL** | a universal theme (error/empty-state, accessibility) is absent | Low priority — add if in scope; otherwise note as out-of-scope with reason. |
 
 ## P5 steps for deep cross-screen / list coverage

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

@@ -17,6 +17,21 @@ patterns (`click`, `hover`, `fill`) don't cover.
 > - **`swipe <dir> on [X]`** → `mobile: swipeGesture`.
 > - **`long-press [X] [for N seconds]`** → `mobile: longClickGesture`.
 > - **`rotate to landscape|portrait`** → `driver.setOrientation(...)`.
+> - **`go back`** (also `goes back` · `press the back button` · `hardware|system|device back` ·
+>   `back gesture` · `swipe back`) → Android `mobile: pressKey` with keycode 4 (KEYCODE_BACK — the
+>   real hardware key); iOS `driver.back()`, which is WebDriverAgent's **navigation** back and *not*
+>   the user's edge swipe-back gesture — iOS has no hardware back key. **This is NOT `tap [Back]`:**
+>   Android's system back does not run the screen's own handler unless the app wires it
+>   (`onBackPressed` / `BackHandler`), so a defect on the OS path is invisible to an in-app tap —
+>   which is why the viewpoint ledger refuses the in-app button as an answer to its "OS/hardware
+>   back gesture" theme. The step takes **no `[Ref]`**; that absence is what selects it. A phrasing
+>   that names a target (`go back to [List] screen`) is refused rather than reinterpreted, so pick
+>   one form: `go back`, or a tap.
+>   **`swipe back` is only a spelling of this step, not a swipe.** It compiles to the same
+>   `KEYCODE_BACK` / `driver.back()` as every other phrasing above, so on iOS — where the edge
+>   swipe-back *is* what a real user does — a scenario named for the gesture never performs it. If
+>   the edge swipe itself is under test, that needs a left-edge `mobile: swipe`, which no step
+>   currently emits: tag it `@manual` rather than letting the wording imply coverage it does not have.
 > - **`pull-to-refresh on [X]`** → fast `mobile: swipeGesture` (direction down).
 > - **`pinch-zoom in|out on [X]`** → `mobile: pinchOpenGesture` / `pinchCloseGesture`.
 > - **`send app to background for N seconds`** → `driver.background(N)`.
@@ -108,7 +123,7 @@ from `appium_find_element`; screen gestures pass `direction` or coordinates.
 | Scroll a list | `User scroll down on [Feed]` | `action=scroll, direction=down` |
 | Scroll until visible | `User scroll to [Footer]` | `action=scroll_to_element, strategy, selector, direction` |
 | Pinch zoom in/out | `User pinch-zoom in on [Map]` | `action=pinch_zoom, elementUUID, scale` (>1 in, <1 out) |
-| System back | `User go back` | `action=back` |
+| System back | `User go back` | `action=back` — **compiles** (see codegen status; per-OS) |
 | Drag & drop | `User drag [A] onto [B]` | `appium_drag_and_drop` (separate tool) |
 
 Other device-level actions (separate MCP tools for exploration; Gherkin now compiles — see codegen

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

@@ -428,6 +428,17 @@ users:
 
 **How to build `columns`**: count column headers in snapshot (left to right, 0-indexed). Map each `[Col] column` reference from feature file to its index.
 
+**A list built from `<div>`s (no `<table>`, no `role="row"` in the snapshot)** — the table steps still work, but you must declare the row SHAPE on the table entry, or every row step resolves 0 rows (`is hidden`/`is empty` pass vacuously — `SG-W016` warns about exactly this):
+
+```yaml
+job list:
+  type: 'locator'
+  value: 'div.job-list'
+  rows: 'div.job-row'        # RELATIVE to the table: what every row matches
+```
+
+Pick `rows` from the snapshot as the repeating child that holds one record (a class like `.job-row`, `[data-testid="job-item"]`, or `> div`). Do **not** put it on a row label's entry — that key positions ONE row (`div.job-row:first-child`) and strict-mode-fails when it matches many.
+
 ---
 
 ## Detail Screens with Dynamic IDs

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

@@ -63,6 +63,10 @@ login:
 awards:
   type: 'page'
   value: '/awards'
+  anchor:                      # optional — the element that proves the page RENDERED (#662).
+    type: 'role'               # `see [Awards] page` asserts the URL, then this; without it the step is
+    value: 'heading'           # a URL-only oracle a late 403 redirect can satisfy. One line per screen.
+    name: 'Awards'
 
 "awards:submit":
   type: 'role'
@@ -221,7 +225,7 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 | `[X] text` / `message` / `label` | `getByText('X')` | Visible text = X (partial match) |
 | `[X] logo/image/icon` | `getByRole('img', { name: 'X' })` | Image alt = X |
 | `[X] search` | `getByRole('searchbox', { name: 'X' })` | Searchbox label = X |
-| `[X] option` | `getByRole('option', { name: 'X' })` | Option text = X |
+| `[X] option` | `getByRole('option')` — **no name** | web only (see the list-member note below) |
 | `[X] slider` | `getByRole('slider', { name: 'X' })` | Slider label = X |
 | `[X] toggle` | `getByRole('switch', { name: 'X' })` | Toggle label = X |
 | `[X] tab` | `getByRole('tab', { name: 'X' })` | Tab text = X |
@@ -234,12 +238,19 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 | `[X] progressbar` | `getByRole('progressbar', { name: 'X' })` | Progressbar label = X |
 | `[X] section` | `getByRole('region', { name: 'X' })` | Section aria-label = X |
 | `[X] card` | `getByRole('article', { name: 'X' })` | Card aria-label = X |
-| `[X] item` | `getByRole('listitem', { name: 'X' })` | List item text = X |
-| `[X] cell` | `getByRole('cell', { name: 'X' })` | Cell text = X |
+| `[X] item` | `getByRole('listitem')` — **no name** | web only (see the list-member note below) |
+| `[X] cell` | `getByRole('cell')` — **no name** | web only (see the list-member note below) |
 | `[X] spinner` | `getByRole('status', { name: 'X' })` | Spinner aria-label = X |
 | `[X] breadcrumb` | `getByRole('navigation', { name: 'X' })` | Navigation aria-label = X |
 | `[X] badge` / `tooltip` / `tag` | `getByText('X')` | Visible text = X |
 
+**Special note on the list members `[X] item` / `[X] option` / `[X] cell`** — the only rows above that behave differently per platform:
+
+- **Web**: they infer the role with **no `name`**, on purpose. A list member takes its accessible name from its own CONTENT, so a name defaulted from the `[Reference]` text matches zero elements — and `toBeHidden()` PASSES on an empty locator, so the scenario would go green having proved nothing. The role alone is the whole locator; `nth` or a count assertion narrows it. An explicit `name:` you write yourself is always honoured.
+- **Mobile**: they do **not** auto-infer at all. A native a11y tree has no role concept, so with no name there is nothing to build an accessibility-id from — the old behaviour emitted the role token itself (`~listitem`), which no tree ever contains. `sungen generate` now fails naming the key to add, and selector generation (Phase 0) scans the live page for it instead of skipping. **Write an explicit entry**, e.g. `job list--item: { type: accessibility-id, value: 'job-row' }`.
+
+**On mobile, `type: role` needs a `name:`.** The rule above is not about these three types — it is about a role with **no accessible name**, whichever way it got that way. On mobile such a role compiles to the role token (`~status`) and can never match, so it is refused at compile time. That includes `name: null`, which is the web opt-out for a content-named role: it has no mobile meaning, and `SG-W003` (which recommends it) does not fire on mobile for that reason. On a native app, prefer `type: accessibility-id`, `type: xpath` or `type: id` over `type: role` — the device exposes content-desc / accessibilityIdentifier, not ARIA roles.
+
 **Special note on `[X] field`**: `getByPlaceholder('X')` only works when (1) the field has a placeholder attribute AND (2) the placeholder text equals X. For fields without placeholders (floating labels, aria-label), write explicit YAML: `type: label, value: "Actual label text"`.
 
 **Only add a YAML entry when** auto-infer cannot work: DOM name differs from Gherkin label, need `testid`, need `nth`, need `exact: true`, need `name: null`, or the field type requires explicit config.

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

@@ -309,7 +309,7 @@ Security:         [S1 – admin only]
 **Depth is a GATE dimension (harness-roadmap P1) — self-raise, never silently go shallow:**
 - For every data-correctness theme the catalog marks `depth.requires: data-assertion`, emit its `depth.template` shape by **default** — don't wait for the repair loop. `sungen audit` measures `businessDepth` (ratio of these scenarios that assert data) against an intent threshold (functional ≥ 0.70); below it the **gate FAILs**.
 - **Verify depth deterministically before the gate:** run `sungen depth-lint --screen <name>`. It classifies every shallow business-critical scenario into **deepen-in-place** (add the theme's value assertion — the printed `template` is a hint, fit it to the actual claim) vs **cross-screen** (route to a flow / `@manual:Mx`). Clear the `deepen` list first — this is the mechanical way to hit `businessDepth` on the first pass instead of churning repair rounds. Never fake a value assertion onto a visibility/behavior scenario the lint over-counts; leave it and note the over-count.
-- `depth.cross_screen: true` (cart / detail / filter / brand correctness) → write the deep capture/compare shape as an **automated flow scenario** (in the flow — do NOT leave a full-step `@manual` duplicate on the screen). `@manual` is **only** for genuine judgment (M6 visual/UX · M8 not-worth · M9 human) or a missing capability (M1–M5/M7), and it **must** carry a reason code (`@manual:Mx`, or a reason comment the planner can infer). A `@manual` scenario that still has full automatable steps (a data assertion, no visual/mock/a11y judgment) is now flagged by `sungen audit` as `MANUAL-AUTOMATABLE`, and business-critical scenarios you defer to `@manual` are reported as `DEPTH-DEFERRED` (they do NOT silently inflate `businessDepth`). Deferring automatable work to `@manual` lowers quality — automate it in the flow instead.
+- `depth.cross_screen: true` (cart / detail / filter / brand correctness) → write the deep capture/compare shape as an **automated flow scenario** (in the flow — do NOT leave a full-step `@manual` duplicate on the screen). `@manual` is **only** for genuine judgment (M6 visual/UX · M8 not-worth · M9 human), a device/OS limit on mobile (M10 OS capability · M11 real-device only), or a missing capability (M1–M5/M7), and it **must** carry a reason code (`@manual:Mx`, or a reason comment the planner can infer). A `@manual` scenario that still has full automatable steps (a data assertion, no visual/mock/a11y judgment) is now flagged by `sungen audit` as `MANUAL-AUTOMATABLE`, and business-critical scenarios you defer to `@manual` are reported as `DEPTH-DEFERRED` (they do NOT silently inflate `businessDepth`). Deferring automatable work to `@manual` lowers quality — automate it in the flow instead.
 - **Pick the right `@manual:Mx` code — it decides which driver can later automate the case** (`sungen audit` flags a code↔reason mismatch). Tag the code that matches the **oracle the reason describes**:
 
   | The reason needs… | Code | Unblocked by |
@@ -321,9 +321,11 @@ Security:         [S1 – admin only]
   | an external dependency (email, payment gateway, download) | `M5` | mail-file / contract |
   | visual / UX / responsive / a11y judgment | `M6` | — (keep manual) |
   | not worth automating · true human judgment | `M8` / `M9` | — (keep manual) |
+  | **mobile** — what the OS/driver will not expose (notification shade, app switcher/recents, permission variance by OS version, call interruption) | `M10` | — (keep manual) |
+  | **mobile** — what an emulator/simulator cannot be (biometrics, real camera, NFC, a real push token) | `M11` | — (keep manual) |
 
   e.g. "submit a payload then check the subscribers **table**" is an API+DB oracle → `@manual:M2` (NOT `M1`); "seed a DB with zero products" is a data state → `M1`; "throttle the network" → `M3`.
-- **Prefer automation-ready `@requires:<cap>` over prose `@manual`.** When you *can* write the steps for a capability-manual case (an API/DB oracle, a seeded state), write it **automation-ready** — the real `@api`/`@query`/… steps tagged `@requires:<cap>` (e.g. `@requires:db @query:subscriber_row`) — instead of a prose `@manual:M2`. It compiles to a skipped-with-reason stub until `sungen capability add <cap>`, then runs as a real test with **no rewrite**. Reserve prose `@manual:Mx` for cases whose steps genuinely can't be expressed (M6/M8/M9 judgment, or a capability with no driver). `sungen audit` reports these as `AUTOMATION-READY-PENDING` (not a gap, not manual).
+- **Prefer automation-ready `@requires:<cap>` over prose `@manual`.** When you *can* write the steps for a capability-manual case (an API/DB oracle, a seeded state), write it **automation-ready** — the real `@api`/`@query`/… steps tagged `@requires:<cap>` (e.g. `@requires:db @query:subscriber_row`) — instead of a prose `@manual:M2`. It compiles to a skipped-with-reason stub until `sungen capability add <cap>`, then runs as a real test with **no rewrite**. Reserve prose `@manual:Mx` for cases whose steps genuinely can't be expressed (M6/M8/M9 judgment, M10/M11 device-or-OS limits on mobile, or a capability with no driver). `sungen audit` reports these as `AUTOMATION-READY-PENDING` (not a gap, not manual).
 - **If the spec lacks the concrete value** a deep assertion needs (exact message, price, count): still write the deep shape with a `{{var}}` placeholder and leave a `# SPEC-GAP: <field> value not in spec` comment — do **not** downgrade to `see [X] section`. A visible gap is better than a silent shallow pass.
 - **Blind-Spot Memory:** before finishing, run `sungen blindspot list --prompt` (Bash) and make sure the suite satisfies each recorded pattern (e.g. "for any Add/Create action: check success + resulting data state + duplicate/double-submit"). These are gaps QA hit before — don't repeat them.
 
@@ -375,7 +377,7 @@ Security:         [S1 – admin only]
 | Validation rule | 1 exact-message TC per rule | `@high` |
 | Business rule | 1 behavioral TC per rule | `@high` |
 | **Secondary behavior / tiebreaker** | **1 TC per tiebreaker or fallback rule in `Secondary behaviors`** | **`@high`** |
-| Auth / OAuth / permissions | 1 VP-SEC TC | `@high` |
+| Auth / OAuth / permissions | 1 VP-SEC TC — **with a rendered-content oracle**: `see [X] page` alone is a URL check a late 403 redirect passes; give the page selector an `anchor:` or add a content assertion (`ORACLE-URL-ONLY`) | `@high` |
 | Free-text input | 1 XSS TC **and** 1 SQL injection TC (separate) | `@high` |
 | **Free-text LIKE / partial-match field** | **1 field-level SQL TC + 1 API-level SQL `@manual` TC** | **`@high`** |
 | Lifecycle states | 1 key state transition TC | `@high` |
@@ -478,6 +480,90 @@ And User wait for [Page Title] heading is visible
 
 ---
 
+## Mobile — the two axes web has no concept of
+
+Applies to a `@platform:mobile/android/ios` unit. Read `sungen-viewpoint` →
+`group-f-mobile-native.md` for *what to check* per native pattern (it carries the theme↔catalog
+map the audit scores against); this section is the two **cross-cutting** axes that multiply every
+other scenario on a device, and that a web-shaped coverage map has no row for.
+
+### Axis 1 — the app lifecycle state machine
+
+A browser tab is either open or closed. An app has five states, and a screen can be wrong in any of
+them. Generate lifecycle scenarios from the transitions, not from the states.
+
+```
+                         launch (cold)
+                               │
+                               ▼
+        ┌──────────────► FOREGROUND ──────────────┐
+        │                     │                   │
+        │       background N seconds        restart (kill)
+        │                     ▼                   ▼
+        │               BACKGROUNDED         RELAUNCHED  ── reinstall ──► FIRST-RUN
+        │                     │                                          (install state cleared)
+        └──── resume ─────────┤
+                              ▼
+                        PROCESS DEATH   (the OS reclaims a backgrounded app)
+```
+
+| Transition | Step | Availability |
+|---|---|---|
+| foreground → backgrounded → resumed | `User background the app for 5 seconds` | both OSes |
+| foreground → killed → relaunched | `User restart the app` | both OSes — **the** persistence oracle |
+| → first-run | `User reinstall the app` | both OSes; needs the session to have installed via `APP_APK` / `IOS_APP` |
+| a clean state *between* scenarios | `@reset:none\|soft\|data\|full` on the Feature | a tag, never a step — a step that tries reports **SG-W023** |
+| backgrounded → process death → resumed | *no step* | `@manual:M10` (OS capability) |
+
+**Every lifecycle scenario needs a DATA oracle.** "The screen is still there" passes on an empty
+shell and on a silently re-logged-in session. Assert the value that must have survived:
+
+```gherkin
+@high @platform:mobile
+Scenario: VP-LOGIC-001 The session survives a cold restart
+  Given User is on [Account] screen
+  When User restart the app
+  Then User see [Account Name] text contains {{user_name}}
+```
+
+Minimum for any mobile unit: **one resume scenario** (the screen owes its own data back) and, when
+the screen persists anything — a session, a setting, a dismissal, a show-once card — **one restart
+scenario per persisted thing**. Rotation belongs here too: `User rotate to landscape` must not lose
+entered values or fire the request twice.
+
+### Axis 2 — permission × network decision table
+
+These two multiply: a permission-gated feature behaves differently offline, and the honest expected
+result is often "which message wins". Build the table, then **test only the rows with distinct
+outcomes** — the usual decision-table discipline, not all 12 combinations.
+
+| # | Permission | Network | Expected | How |
+|---|---|---|---|---|
+| 1 | granted | online | the happy path, feature content asserted | `User grant camera permission` — both OSes (iOS Simulator needs `applesimutils`) |
+| 2 | granted | offline | the spec's cached/queued behaviour + a clear message; entered data never silently lost | `User turn wifi off` → `@platform:android` (XCUITest cannot toggle connectivity); iOS is `@manual:M10` |
+| 3 | granted | off → on | recovers and refreshes with no manual reload | `@platform:android` |
+| 4 | denied | online | an in-app explanation with a route to Settings — never a crash or a dead button | `@manual:M10` — no step denies a permission |
+| 5 | denied | offline | one message wins per spec; do NOT generate this row unless the spec says which | `@manual:M10` |
+| 6 | never-ask-again | online | no request loop; the Settings route is shown | `@manual:M10` |
+| 7 | revoked while running | online | the app re-checks instead of trusting a stale grant | `@manual:M10` |
+
+Row 1 is `@high` and automated. Rows 2–3 are `@high` and automated **on Android only** — tag them,
+do not write them platform-neutral and hope. Rows 4–7 carry `@manual:M10`, which is a reason code
+and a real oracle, not a shrug: write the steps a human follows and the value they must see.
+
+### Two mobile traps worth naming while generating
+
+- **A `page` assertion proves nothing on mobile.** A native app has no URL, so `Then User see [Login]
+  page` compiles to an empty comment (**SG-W022**) and the scenario passes without looking. The
+  `screen` spelling is different and is what you want: it treats the target as a plain element and
+  emits a real visibility assertion — so name a marker only that screen has (`Then User see [Login
+  Submit] button`, or `Then User see [Login] screen` against a screen-root selector), and pair it
+  with the previous screen's marker going `is hidden`.
+- **An `open [X] page` / `navigate to` step on mobile navigates nowhere** (**SG-W026**) — the app was
+  already launched by the capabilities. Change screens with a real tap or gesture.
+
+---
+
 ## Cleanup & Hooks
 
 Add cleanup tags per the `sungen-gherkin-syntax` Cleanup table. Key rules:

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

@@ -84,6 +84,7 @@ Hard-fail gate. Any ✗ is a syntax error — must be fixed; do not score furthe
 - [ ] A spec `Format:` line → `matches "<format>"`, NOT `with {{v}}` (an exact value pins data that changes daily; `contains` proves nothing)
 - [ ] Correct pattern: text(`message/header/label with {{v}}`) · partial(`text contains {{v}}`) · input(`field/dropdown with {{v}}`) · state(`is …`) · attribute(`image/link with {{v}}`) · count(`row with {{count}}`) · page(`[T] page`)
 - [ ] Table: `[Col] column in [Table] table`, `[Ref] row in [Table] table with {{v}}`, `table with {{count}}`/`is empty`, `table match data:`; row scope used correctly
+- [ ] Table on a `<div>` list (no `<table>` / `role="row"` in the app): the table entry declares `rows:` — without it `is hidden`/`is empty` pass on 0 rows (`SG-W016`). A row label's own `type: locator` entry is ONE positioned row, never the shape
 
 ### A5. Alert / Scope / Background
 
@@ -107,6 +108,30 @@ Hard-fail gate. Any ✗ is a syntax error — must be fixed; do not score furthe
 - [ ] `@parallel` is REQUIRED when a feature mixes auth groups (`@auth:user` + `@no-auth`)
 - [ ] `@flow`: `[Screen:Element]` namespace is consistent; YAML keys quoted with the colon (`"login:submit":`)
 
+### A8. Mobile (`@platform:mobile/android/ios` units only)
+
+Hard-fail rules — each one is a scenario that PASSES while proving nothing, which is worse than a
+failing one. Skip this section entirely for a web unit.
+
+- [ ] **`Then User see [X] page` → FAIL.** A native app has no URL: the step compiles to an empty
+      comment (**SG-W022**) and the scenario goes green without looking at the app. Require a marker
+      element (`see [X] screen` against a screen-root selector, or a button/text unique to the
+      screen) plus the previous screen's marker going `is hidden`.
+- [ ] **`When User open [X] page` / `navigate to` → FAIL.** It navigates nowhere (**SG-W026**) — the
+      app was already launched by the wdio capabilities. Require a real tap or gesture.
+      `Given User is on [X] screen` is the legitimate app-launch anchor and is NOT a violation.
+- [ ] **A step that establishes app state → FAIL.** `Given the user is logged out` compiles to a
+      comment (**SG-W023**); auth lives in the keychain, not in cookies. Require `@reset:data|full`
+      on the Feature instead.
+- [ ] **Android-only vocabulary without `@platform:android` → FAIL.** `turn airplane mode|wifi|mobile
+      data …`, `open notifications` and `turn device location …` throw on iOS; `hide keyboard` is
+      worse — its iOS path is guarded out with **no** throw, so the scenario passes having done
+      nothing. Cross-check `docs/spec/step-support-matrix.md` (the `iOS` column) when unsure.
+- [ ] **A web-only step on a mobile unit → FAIL.** Tables, browser storage, tab order, `@mock`, the
+      uploader and `hover` have no native equivalent — see `sungen-gherkin-syntax` → Platform Support.
+- [ ] No `{{variable}}` used as a coordinate in `set location to …` — the numbers are resolved at
+      compile time and a variable silently becomes `0, 0`. Literal digits only.
+
 ---
 
 ## Layer B — Coverage Matrix (against Sun Common Checklist for QA)
@@ -128,6 +153,22 @@ Build a mapping table: for each applicable group, does the feature have a matchi
 | **Security** | SQL Injection; XSS; Data Integrity (edit dropdown/remove `disabled` via DevTools → server rejects). SQL on LIKE/search fields → 2 TCs per the `sungen-viewpoint` SQL 2-layer rule. | VP-SEC | `with {{xss_*}}`/`{{sql_*}}`; data-integrity usually `@manual` |
 | **Cross-surface outcomes** | Admin action → outcome on user-facing surface (portal, mobile, widget); spec defines display condition on another URL | VP-LOGIC-CS | `@high @manual` per surface per business rule — at minimum 1 per cross-surface rule; use `@auth:role` + `@extend` if surface reachable in same test run |
 
+**Mobile units add four categories** (`@platform:mobile/android/ios` only). Each maps to a theme the
+`sungen audit` mobile catalog scores, so a gap here is a scored gap, not a stylistic note — the
+per-pattern checklists are in `sungen-viewpoint` → `group-f-mobile-native.md`:
+
+| Category | Sub-viewpoint to check | VP map | Sungen representation |
+|---|---|---|---|
+| **App lifecycle** | Resume after background restores the screen's data; a restart preserves what the spec says persists (session, setting, dismissal, show-once); rotation loses nothing and does not double-submit | VP-LOGIC | `background the app for N seconds` · `restart the app` · `rotate to landscape\|portrait`, each with a **value** assertion |
+| **Permission** | Granted path works; denied path explains and routes to Settings; never-ask-again does not loop; a revoked grant is re-checked | VP-LOGIC/SEC | `grant [X] permission` for the granted row; the other three are `@manual:M10` with a real oracle |
+| **Gesture reachability** | The target is reachable — off-screen needs `scroll to`, occluded-by-a-floating-bar needs `tap top of` (scroll is a no-op there); swipe-revealed actions are asserted, not assumed | VP-LOGIC | `swipe <dir> on [X]` · `scroll to [X]` · `tap top of [X]` · `pull to refresh [X]` |
+| **Connectivity** | Offline banner; cached content survives; an action while offline fails clearly without losing input; recovery refreshes without a manual reload | VP-LOGIC | `turn wifi off` → `@platform:android`; iOS `@manual:M10` |
+
+**Deduct when a mobile suite has no lifecycle, permission, or gesture oracle at all** — those are the
+three concerns a web-shaped test set always misses, and their absence is the single strongest signal
+that the suite was written for a browser and re-tagged. A screen that genuinely owes none of them
+(a static read-only screen with no permissions) is not penalised — say so in the notes.
+
 **Tier-aware**: if the suite only has `@high` (Tier 1) → do NOT penalize missing pure VP-UI (deferred to Tier 2). Require full VP coverage only on a Full review.
 
 ### EP/BVA rules when mapping
@@ -180,6 +221,18 @@ Build a mapping table: for each applicable group, does the feature have a matchi
 - **error (4xx)** — the status IS the assertion; also check the error-message field when the contract defines one.
 - **anti-pattern (counts against "Avoids anti-patterns")** — re-asserting the input just sent instead of a server-derived value.
 
+**Mobile scenarios — depth rubric:** the mobile catalog marks most themes as needing a **data**
+oracle, so a sighting where a value is owed fails the "Specific" check:
+- **a lifecycle/persistence claim asserted by a sighting = fail.** "The screen is still there" after
+  `restart the app` passes on an empty shell and on a silent re-login. Require the value that had to
+  survive (`text contains {{v}}`, `field with {{v}}`).
+- **a list claim asserted by a count or a sighting = fail.** `see all [List Item] text contains {{v}}`
+  is the oracle; a row count passes on the wrong rows.
+- **a navigation claim asserted by one marker = weak.** Require the destination's marker AND the
+  origin's marker going `is hidden` — one marker passes when the app never moved.
+- **`keyboard-overlap` is the exception**: its honest oracle IS a sighting (the covered element is
+  visible again). Do not deduct for the absence of a value assertion there.
+
 ### Test Data (10)
 
 | Check | Pts |
@@ -271,6 +324,10 @@ Do NOT deduct points when a `.feature` lacks the following viewpoints (Playwrigh
 15. **Mixed auth groups missing `@parallel`** → add `@parallel`.
 16. **Missing secondary behaviors** — spec defines tiebreaker, fallback rule, or secondary sort but no scenario tests it? Add 1 `@high` TC per rule.
 17. **Missing concurrency scenarios** — spec or test-viewpoint mentions multi-tab, multi-user, or simultaneous actions but no `@manual` scenario exists? Add 1 `@manual` TC per risk (`@normal` by default; `@high` if data integrity at risk).
+18. **Mobile: `see [X] page` oracle** → replace with a marker element on the destination screen + the origin's marker `is hidden` (SG-W022 — the original passes having proven nothing).
+19. **Mobile: `open [X] page` / `navigate to`** → replace with the real tap/gesture that changes screens (SG-W026).
+20. **Mobile: Android-only step without a platform tag** → add `@platform:android`, and add the iOS counterpart as `@manual:M10` if the spec owes iOS coverage.
+21. **Mobile: no lifecycle scenario** → add 1 resume scenario (`background the app for N seconds` + a value assertion) and 1 restart scenario per persisted thing.
 
 ---
 
@@ -338,5 +395,5 @@ If `selectors/<name>.yaml` exists, count lines matching `@needs-live-verify` (pr
 
 - **When NOT to apply**: exploratory charters, performance/load scripts, pure NFR specs — this rubric grades functional test cases.
 - **Adapting weights**: a project may rebalance the 7 dimensions (e.g. security-critical service: Security→15, Maintainability→0) as long as the total stays 100 and the PASS/CONDITIONAL/FAIL thresholds are restated. Record any change in this section.
-- **References**: detailed syntax → `sungen-gherkin-syntax`; selector keys → `sungen-selector-keys`; VP classification → `sungen-viewpoint`; generation workflow → `sungen-tc-generation`.
+- **References**: detailed syntax → `sungen-gherkin-syntax`; selector keys → `sungen-selector-keys`; VP classification → `sungen-viewpoint` (mobile-native patterns → its `group-f-mobile-native.md`); mobile step vocabulary → `sungen-mobile-gestures`; per-OS support → `docs/spec/step-support-matrix.md`; generation workflow → `sungen-tc-generation`.
 - **Owner / version**: Owner: `<QA Lead>` · Version: `2.0` · Last updated: `2026-06-03`.

package/dist/orchestrator/templates/ai-src/skills/sungen-test-design-techniques/SKILL.md

@@ -116,3 +116,16 @@ Scenario: VP-VAL-003 Above maximum is rejected           # value = 101
 - `@normal` Invalid: Completed → Draft (blocked), Pending → Completed (skip approval)
 
 **test-data:** Use named state keys (`order_in_draft`, `order_in_pending`).
+
+**On mobile, three state machines exist that no spec draws** — apply this technique to them even
+when `spec.md` has no diagram, because the states are imposed by the platform rather than the
+product:
+
+| Machine | States | Transition steps that compile |
+|---|---|---|
+| App lifecycle | foreground · backgrounded · relaunched · first-run · process-death | `background the app for N seconds` · `restart the app` · `reinstall the app`; process-death is `@manual:M10` |
+| Screen entry / exit | entered by tap · entered by deep link · left by OS back · left by in-app control | `open deep link {{url}}` · `go back` (OS/hardware) · a tap on the in-app control — **the last two are different transitions**, since system back skips the screen's own handler unless the app wires it |
+| Connectivity | online · offline · recovering | `turn wifi off` / back on → `@platform:android` (XCUITest cannot toggle connectivity) |
+
+Full matrices and the permission axis → `sungen-tc-generation` → "Mobile — the two axes web has no
+concept of". Per-pattern checklists → `sungen-viewpoint` → `group-f-mobile-native.md`.