@sun-asterisk/sungen 3.2.28 → 3.2.30

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

@@ -13,7 +13,8 @@ user-invocable: false
 - **Actor**: Always `User`, always active voice.
 - **Value**: `with {{snake_case}}` — never hardcode static data.
 - **State**: `is <keyword>` — never use `{{}}` for states.
-- **Parent scope**: `in [Parent] parentType` — optional, only when page has 2+ similar blocks needing disambiguation.
+- **Parent scope**: `in [Parent] parentType` — optional, only when page has 2+ similar blocks needing disambiguation. Container types: `table` `list` `list-item` `section` `dialog` `modal` `drawer` `overlay` `form` `card` `item` `row` `group` `panel` `region` `container` `tab` `menu`. Anything else is not a container, and the clause is DROPPED with `SG-W028` rather than silently widening the step to the whole page.
+- **Parent scope BY CONTENT** (web only): `… with {{v}} in [Parent] parentType with {{v2}}` — the SECOND `with` picks the one container whose content is `{{v2}}`, for a list of look-alike cards/rows. One `with` after the clause still belongs to the TARGET (`see [first] row in [apply list] table with {{job_name}}`), so the by-content form always carries two. On the mobile adapter it reports `SG-W028` — an Appium parent chain has no content filter.
 
 ## Keyword → Action Rules
 
@@ -35,7 +36,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
@@ -45,6 +46,8 @@ User select [T] dropdown with {{v}}
 User click [T] button | tab | column | breadcrumb
 User click [T] row with {{v}}
 User try to click [T] button | link          # DISABLED element only — see rule below (v3.3) [web]
+User click [T] overlay at position "top-left"           # corner preset: top-left | top-right | bottom-left | bottom-right [web]
+User click [T] overlay at offset x=24px, y=10%          # px or % per axis, from the element's top-left [web]
 User double click [T] element
 User hover [T] icon | row                    # no-op on mobile (see Platform Support)
 User drag [T] to [T2]
@@ -57,7 +60,17 @@ User expand | collapse [T] row
 scenario asserts nothing happens (cooldown re-send, submit before the form is valid). `click` waits for
 `enabled` → it can only time out there; `try to click` compiles to `.click({ force: true })`. Always
 pair it with the proof: `Then User see [T] TYPE is disabled` + an assertion that the effect did NOT occur.
-NEVER use it for a click that is supposed to work — it deletes the actionability wait.
+NEVER use it for a click that is supposed to work — it deletes the actionability wait. (`force: true` is
+reachable ONLY through `try to click` — there is no separate `force` keyword.)
+
+**click at position rule** (web only): a plain `click` lands on the element's CENTRE. To click a
+modal backdrop where the dialog is not, or any control whose centre is covered, append
+`at position "<corner>"` (5% in from that corner) or `at offset x=<n>px|%, y=<n>px|%`. The position
+is checked against the element's real box at run time (an offset past it fails naming the size). The
+suffix is refused at compile time (`SG-E026`, the step throws instead of clicking the centre) when it
+is misspelt or unquoted, when a value is negative / above 100% / missing an axis, when anything
+follows it, and when it is combined with `try to click`, a `with {{v}}` text filter, `… and accept [OK]
+alert`, or `double click` — those forms take no position.
 
 ### Alert / Keyboard / Wait / Scroll
 
@@ -68,12 +81,11 @@ User click [OK | Cancel] alert                    # two-step form: must come BEF
 User fill [T] alert with {{v}}                    # no-op on mobile — native prompt fill is app-specific
 User see [message text] alert
 User press Escape key | [Enter] key | Tab key 5 times | Enter on [T] field
-User wait for N seconds | [T] page                # [T] page: web waits for the URL; mobile pauses (settle) — see Platform Support
+User wait for N seconds | [T] page                # [T] page: web waits for the URL, then HOLDS it (see Pattern 8); mobile pauses (settle) — see Platform Support
 User wait for [T] TYPE is visible | hidden | enabled | disabled     # ANY reference (v3.3)
 User wait for [T] TYPE with {{v}}                                    # until it shows the value
 User wait for [T] table to refresh                                   # filter/search/pagination round-trip (v3.3)
 User scroll to [T] section
-User switch to [T] frame | [main] frame           # web: iframe; mobile: hybrid-app WebView context (no-op if the screen has no WebView)
 ```
 
 > **Browser alerts (native `window.confirm/alert/prompt` only):** prefer the compound form —
@@ -86,6 +98,36 @@ User switch to [T] frame | [main] frame           # web: iframe; mobile: hybrid-
 > `wait for N seconds` stays a last resort. `table to refresh` watches the app's loading
 > indicator (`qa/app.yaml` `feedback.loading.indicator`, default `[aria-busy="true"]`).
 
+### Scope control
+
+```
+User is on [T] dialog                             # ENTER dialog scope, rooted at [T]'s selectors.yaml entry
+User use dialog                                   # ENTER dialog scope, unnamed — plain page.getByRole('dialog')
+User close dialog | dismiss dialog | exit dialog  # EXIT dialog scope (three spellings, identical)
+User switch to [T] frame                          # ENTER frame scope — web: iframe; mobile: hybrid-app WebView context
+User switch to [main] frame                       # EXIT frame scope (no-op if the screen has no WebView)
+```
+
+> **Dialog scope is STICKY — it ends only where you end it.** Once a scenario enters dialog scope,
+> EVERY later locator in that scenario is prefixed with the dialog root, **including the steps that
+> run after the dialog has closed**. Nothing implicit drops it: not a click on the dialog's own
+> Close/OK button, and **not** `wait for [T] dialog is hidden` — that step asserts the dialog went
+> away and then keeps resolving the following steps INSIDE it, which can never succeed. Only
+> `close`/`dismiss`/`exit dialog`, or the start of the next scenario, drops the scope. The failure
+> has a recognisable shape: a step after the dialog closed times out reading "element not found"
+> while the element is plainly on screen — you are not missing a selector, you are still scoped
+> inside a dead dialog.
+>
+> ```gherkin
+> Given User is on [Confirm Delete] dialog   # scope enters here — implicitly, but it still needs an EXPLICIT exit
+> When User click [OK] button                # scoped — correct, the button IS in the dialog
+> And User exit dialog                       # ← REQUIRED: the click closed the dialog, the scope did not
+> Then User see [Deleted] toast              # page-rooted again
+> ```
+>
+> Dialog scope is `[web]`-effective only — no Appium template reads `inDialog`, so on mobile the
+> following steps resolve against the whole screen (`SG-W021`). Frame scope works on both.
+
 ### Positional table rows (v3.3) `[web]`
 
 ```
@@ -103,6 +145,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}}
@@ -139,6 +184,20 @@ detail:
   anchor: { type: 'role', value: 'heading', name: 'Item Detail' }   # the rendered-content proof
 ```
 
+**`wait for [T] page` shares that hold, and only that.** Since 3.2.30 the wait compiles to
+`waitForPage(page, {…})` on the same helper: it arrives, settles, holds the URL, and fails naming
+where the user went — so the steps AFTER the wait no longer run against a page mid-redirect, and
+`/vi/search` no longer resolves on `/vi/search-results`. Two differences from the `Then` side:
+
+- **A wait does not constrain the query.** `see [Results] page` with no `with {{v}}` demands a bare
+  URL; `wait for [Results] page` after submitting a search tolerates the `?q=…` it lands on. Prove
+  the query in the `Then` that follows.
+- **A wait is not an oracle.** It never counts toward a scenario's assertions — `ORACLE-URL-ONLY`
+  and the assertionless-test check both ignore it. Always follow it with a real `Then`.
+
+An absolute page `value` (`https://app.example.com/reception/:id`) compiles its host into a
+separate anchored `hostname:` — the same path on another host no longer satisfies the wait.
+
 **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 check — `expectPage(page, {…})`, built on
 `toHaveURL(urlMatches({…}))` and retrying like any other assertion — comparing the **exact** pathname
@@ -153,6 +212,8 @@ detail:
 | `… 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
@@ -206,6 +267,15 @@ User see [Table] table match data:
 
 Row scope: `see [Ref] row in [Table] table with {{v}}` enters scope. Subsequent `see [Col] column with {{v}}` checks cell in that row. Use `table match data:` for multi-row verification.
 
+**[Col] does not have to be the DOM header text.** `see [Col] column in [T] table` looks for a header whose accessible name is the reference, which cannot match a page in another language. Keep the reference readable — it is what the delivered test case shows — and declare the real header on the table entry (or on a `<col>--columnheader` entry's `name:`, which also takes `{{variables}}` for per-locale text):
+```yaml
+article list:
+  type: role
+  value: table
+  columns:
+    category: { index: 2, header: '記事分類' }
+```
+
 **[Ref] of a row step is a display label UNLESS declared in selectors.yaml.** Without an entry the step checks the value exists in ANY row — a name like `[First Contact Row]` does NOT position the row, and an ordering rule would pass even when the row moved (SG-W010 warns on positional-looking undeclared labels). To assert a POSITION, declare the row (a `type: locator` value RELATIVE to the table):
 ```yaml
 first contact row:
@@ -214,6 +284,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]`
 
 ```
@@ -374,7 +453,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
@@ -387,8 +466,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 |
-| `wait for [T] page` | waits for the URL | fixed `driver.pause(500)` settle — not a real wait condition |
+| `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, then settles and HOLDS it (`waitForPage`) | 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 |
@@ -477,7 +557,17 @@ award:
 | `upload` | — | — | file inputs |
 | `frame` | iframe selector | — | iframes |
 
-Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `columns`
+Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `columns` `checked` `selected`
+
+`checked: { class: <cls> }` or `checked: { attribute: <attr> }` — how a checkbox-like control that is
+NOT a real checkbox (a `<div>` tile with no `role`/`aria-checked`; `.check()` throws "Not a checkbox or
+radio button") shows its state. `selected:` is an ALIAS of the same signal, for a card/tab picker where
+`checked:` reads wrong; declare ONE spelling and ONE of class/attribute. `check`/`uncheck` click only
+when the state differs, then assert it; `is checked` / `is unchecked` / `is selected` (plain or
+`with {{v}}`) assert it. The class is read on the located element OR on a descendant (a checkmark
+`<svg>` that only mounts when on); the attribute is read on the located element itself. Other states on
+the same entry (`is focused`, …) keep their native matchers. The value must be ONE plain class token or
+attribute name — whitespace, a quote or a backslash is refused at compile time, naming the entry.
 
 `scope` (e.g. `scope: dialog`) is `[web]`-effective only — no Appium template reads `inDialog`, so
 on mobile a dialog-scoped ref still resolves against the whole screen (`SG-W021`).
@@ -794,7 +884,32 @@ Only when `@cleanup:*` tags aren't enough — feature-specific logic.
 
 ### Layer 3: `@beforeAll` / `@afterAll` (optional)
 
-For one-time setup/teardown.
+For one-time setup/teardown. A hook scenario takes `@api:` / `@query:` preconditions exactly like an
+ordinary scenario (override args and `@concurrent:N` included) — they run inside the hook and bind
+`{{name}}`:
+
+```gherkin
+@beforeAll @api:login(email={{email}},password={{pw}}) @api:list_items(token={{login.body.token}})
+Scenario: seed the session once before any scenario
+  Then expect {{login.status}} is 200
+  And expect {{list_items.status}} is 200
+
+@afterAll @api:cleanup
+Scenario: drop the seeded data after the last scenario
+  Then expect {{cleanup.status}} is 204
+```
+
+- A variable bound in `@beforeAll` (`{{login.body.token}}`) is readable from EVERY scenario of the
+  feature (it runs before each of them). `@afterEach`/`@afterAll` bindings stay hook-local.
+- A failing hook skips every test in the file, so hook steps are COLLECTED: each `Then` that fails is
+  recorded and the next step still runs; a failing action step (`Given`/`When`) stops the hook there.
+  The hook fails ONCE with the full list (`Hook preconditions not met`), not with the first failure.
+- `@cases` and `@extend` are not supported on a hook — they are ignored with a compile warning.
+- A hook has no `page` fixture on a per-scenario (non-`@serial`) feature — keep its steps to `@api:`/
+  `@query:` preconditions and `expect` assertions there.
 
 **Rendering order in `.spec.ts`:**
-`test.describe` → `test.use(storageState)` → `test.use(autoCleanup)` → `test.beforeAll` → `test.beforeEach` → `test.afterEach` → `test.afterAll` → `test()` blocks
+`test.describe` → `test.use(storageState)` → `test.use(autoCleanup)` → `test.beforeAll` → `test.beforeEach` → `test.afterEach` → `test.afterAll` → `test()` blocks.
+On a `@serial` feature the user `@beforeAll`/`@afterAll` blocks are registered right after the built-in
+`beforeAll` (page creation) and BEFORE the built-in `afterAll` (page close): Playwright runs `afterAll`
+hooks in registration order, so the shared `page` is still open for the user's teardown steps.

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

@@ -96,6 +96,7 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
    - Toast/alert named from content (no aria-label) → `feedback.toast: { role: status, named_by: content }` + `name: null` on the selector entries.
    - Loading indicator for `wait for [T] table to refresh` → `feedback.loading.indicator` (skip if the app sets `aria-busy`).
    - **Every qa/app.yaml edit MUST carry provenance** in `detection:`: who/when (`detected_by`) and the observed evidence per key (`evidence:`). A profile without evidence is a guess a human cannot review.
+7c. **Checkbox-like control that is not a checkbox** (`.check()` failed with `Not a checkbox or radio button`; the snapshot shows a `<div>`/`<button>` tile with no `role="checkbox"` and no `aria-checked`): keep the locator that finds the tile and add the state signal to the SAME entry — `checked: { class: '<class present when on>' }` (a class on that element itself, e.g. `bg-selected`) or `checked: { attribute: '<attr>' }` (a `'true'`/`'false'` attribute such as `data-checked`); on a card/tab picker write `selected:` instead — same signal, different spelling. This is what makes `check`/`uncheck`/`is checked`/`is selected` compile for the tile. ONE plain class token or attribute name only — whitespace or a quoted fragment is refused at compile time, naming the entry. Same shape as `expanded:` for accordions; `checked.class` matches on the located element OR a descendant carrying it (the checkmark icon), while `checked.attribute` is read on the located element itself.
 8. **Merge, don't overwrite**: preserve the page selector and any user-authored entries in `selectors.yaml`. Only add missing keys.
    - **Type-collision check** (see `sungen-selector-keys` § Collision rule): before writing a base key, check whether it already exists with a *different* `type`. If so, give **both** entries a `--type` suffix instead of clobbering or sharing the base key — a base-key entry of the wrong type gets picked up by any step referencing that label. Watch `page` especially: a `[X] page` step reads `value` as a URL, so if `X` already holds a button (`value: 'button'`) the compiler won't use the button's value as a URL, but it can't invent the real one either — it falls back to the feature's own path and warns `SG-W013`, asserting a page that isn't `X`'s. Write `X--page` (URL from the live page / feature `Path:`) alongside `X--button`.
 9. **Show summary + confirm**: list the keys that will be added, ask the user to approve, then write the file.
@@ -428,6 +429,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

@@ -219,35 +219,49 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 | `[X] button` | `getByRole('button', { name: 'X' })` | Button's accessible name = X |
 | `[X] link` | `getByRole('link', { name: 'X' })` | Link text = X |
 | `[X] heading` / `header` | `getByRole('heading', { name: 'X' })` | Heading text = X |
-| `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` | Checkbox label = X |
+| `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` | Checkbox label = X — a checkbox-LIKE tile with no `role`/`aria-checked` needs an explicit entry plus `checked: { class: <cls> }` or `checked: { attribute: <attr> }` (read on the located element itself; `expanded.class` reads a descendant) |
 | `[X] radio` | `getByRole('radio', { name: 'X' })` | Radio label = X |
 | `[X] field` | `getByPlaceholder('X')` | Placeholder text = X AND field has a placeholder |
 | `[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 |
 | `[X] table` | `getByRole('table', { name: 'X' })` | Table aria-label = X |
 | `[X] list` | `getByRole('list', { name: 'X' })` | List aria-label = X |
-| `[X] column` | `getByRole('columnheader', { name: 'X' })` | Column header text = X |
+| `[X] column` | `getByRole('columnheader', { name: 'X' })` | Column header text = X — **overridable**, see the column-header note below |
 | `[X] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'X' })` | Dialog aria-label/heading = X |
 | `[X] dropdown` / `select` | `getByRole('combobox', { name: 'X' })` | Combobox label = X |
 | `[X] menuitem` | `getByRole('menuitem', { name: 'X' })` | Menu item text = X |
 | `[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 |
 
+**Column headers: the `[Reference]` is not required to be the DOM text.** `[X] column` defaults its accessible name to the reference, which is unmatchable when the page is not in the reference's language (a `[Category]` column whose header reads 記事分類). Declare the real header instead of renaming the reference — the reference is what ships in the delivered test case. Most specific first: the table entry's `columns.<col>.header`, then a `<col>--columnheader` entry's `name:`, then the reference text. A `header` may hold `{{variables}}` for per-locale text, like any `name:`. A same-named entry that is NOT a column header is ignored and cannot hijack the lookup.
+
+**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.
 
+**`nth:` takes an integer `>= -1`** — `0`, `1`, `2`… are zero-based indexes and `-1` is the LAST
+match (`.last()` on web, `.at(-1)` on mobile). Nothing else is an index: `nth: -2`, `nth: 'last'`
+and `nth: 1.5` are ignored, the selector stops filtering by position, and the compiler reports
+`SG-W018`. Reach for `nth` only when `exact: true` or `scope` cannot disambiguate.
+
 ### `name: null` — name-from-content roles (toast, alert, spinner)
 
 For a `type: role` entry **without** `name:`, the compiler defaults the accessible-name filter to the Gherkin `[Reference]` text. That is right for buttons/links — and **always wrong** for roles whose accessible name derives from their CONTENT (`status`, `alert`, `log`, `marquee`, `timer`): a toast's name is its message text, never the string "Success Toast". The compiler warns (`SG-W003`). Opt out explicitly:

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.
 
@@ -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: