@sun-asterisk/sungen 3.2.28 → 3.2.29

package/src/harness/sensors.ts

@@ -76,6 +76,9 @@ export interface CatalogTheme { theme: string; keywords: string[]; depth?: Theme
 export interface Catalog {
   page_types: Record<string, { detect_keywords: string[]; must_cover: CatalogTheme[] }>;
   universal: CatalogTheme[];
+  /** Reminder themes offered to MOBILE targets only — `universal` also applies to web, where
+   *  orientation and connectivity have no meaning. Optional so an older catalog still parses. */
+  mobile_universal?: CatalogTheme[];
 }
 
 export function loadCatalog(): Catalog {
@@ -181,7 +184,10 @@ export function viewpointGate(scenarios: ScenarioInfo[], viewpoints: ViewpointEn
     }
   }
 
-  const universalGaps = catalog.universal
+  // Mobile targets are also reminded of the native-only themes. Same weight as `universal`:
+  // these surface as narrative, not as score — see the note in the catalog.
+  const reminderThemes = [...catalog.universal, ...(isMobile ? catalog.mobile_universal ?? [] : [])];
+  const universalGaps = reminderThemes
     .filter((t) => !t.keywords.some((k) => has(scenarios.map((s) => s.haystack), k)))
     .map((t) => t.theme);
 
@@ -521,6 +527,74 @@ export function duplicateClusters(scenarios: ScenarioInfo[]): DuplicateResult {
   };
 }
 
+// ---------- Sensor 4b: Reused scenario IDs ----------
+
+/**
+ * Two DIFFERENT scenarios wearing the same `VP-<CAT>-<NNN>` id (#694).
+ *
+ * Sensor 4 above is content-shaped — it clusters identical STEP SKELETONS — so two scenarios that
+ * merely share an id sail past it, and every other axis stays green. `VIEWPOINT-ID-REUSED` reads
+ * ids out of `test-viewpoint.md` only; the `.feature`'s own `Scenario:` lines were never compared
+ * against each other. The reported symptom was a ledger item showing UNCOVERED — pointing at the
+ * wrong cause, since the scenario exists and is just wearing the wrong number.
+ *
+ * This is BLOCKING (it joins the gate conjunction) where its three declaration-integrity siblings
+ * are advisory, because a reused id does not stop at the audit — it reaches the client:
+ *
+ *   - `generateTcId()` builds the delivered testcase id straight out of the vpId
+ *     (`${SCREEN}-${vpCore}`), so two scenarios under one id ship as two rows with ONE id in the
+ *     CSV/XLSX the customer reviews.
+ *   - It has already shipped a false green. `scenario-merger.ts` records the field report: a
+ *     feature carried `VP-NAV-001` on 14 scenarios and the result-merge fallback attached an
+ *     automated sibling's result to every @manual sibling — 7 testcases nobody ran were delivered
+ *     as "Passed". The guard added there degrades to "Pending"; it never closed the cause.
+ *   - `matrix/gates.ts` already grades the same condition `severity: 'error'` — but at delivery,
+ *     after generation and review. This moves that judgment to where it can still be acted on
+ *     cheaply: renumber and regenerate.
+ *
+ * Scoped PER FILE, matching the issue's wording. A unit may hold several `.feature`s
+ * (`add --feature`) and ids colliding ACROSS two of them still collapse into one `generateTcId`,
+ * because that id keys on the screen and not on the file — deliberately out of scope here.
+ *
+ * `@cases:<dataset>` is safe: a data-driven scenario is ONE `ScenarioInfo` that expands to N row
+ * tests at runtime, so it can never look like a collision to this count. `Scenario Outline` is not
+ * a vector either — this DSL does not support it (`@cases` is the data-driven form).
+ *
+ * One CONVENTION dependency, stated rather than hidden: `vpId` is whatever leading title token
+ * `isIdLike` accepts (uppercase-first, alphanumeric, carries a digit), not specifically `VP-`/`FL-`.
+ * Two scenarios both titled `iOS15 …` would therefore read as a collision. Every generator path
+ * and skill doc mandates the `VP-<CAT>-<NNN>` scheme, so this has no real surface today — but it is
+ * a convention holding it up, not the parser.
+ */
+export interface ReusedScenarioId {
+  id: string;
+  count: number;
+  titles: string[];
+  /** Basename of the `.feature` holding the collision; '' for hand-built scenarios with no source. */
+  file: string;
+}
+
+export function scenarioIdReuse(scenarios: ScenarioInfo[]): ReusedScenarioId[] {
+  // Keyed by file THEN id: the check is per-file, and a bare id key would silently widen it to
+  // the whole unit. NUL-joined because a feature path may legitimately contain a space.
+  const byFileAndId = new Map<string, ScenarioInfo[]>();
+  for (const s of scenarios) {
+    if (!s.vpId) continue;                 // an id-less scenario is a different finding
+    const key = `${s.sourceFile ?? ''}\u0000${s.vpId.toUpperCase()}`;
+    byFileAndId.set(key, [...(byFileAndId.get(key) ?? []), s]);
+  }
+  // Read the id and the file off the GROUP, never by splitting the key back apart.
+  return [...byFileAndId.values()]
+    .filter((group) => group.length > 1)
+    .map((group) => ({
+      id: group[0].vpId!.toUpperCase(),
+      count: group.length,
+      titles: group.map((s) => s.name),
+      file: group[0].sourceFile ? path.basename(group[0].sourceFile) : '',
+    }))
+    .sort((a, b) => b.count - a.count || a.id.localeCompare(b.id));
+}
+
 // ---------- Sensor 5: Traceability ----------
 
 export interface TraceResult {

package/src/harness/viewpoint-ledger.ts

@@ -222,7 +222,14 @@ export function viewpointLedger(viewpointPath: string, scenarios: ScenarioInfo[]
  * The language has no reload/back step at all (#593), so the honest outcome is a `@manual`
  * deferral naming the gesture — not a silent swap.
  */
-const BROWSER_GESTURES: Array<{ gesture: string; re: RegExp; appSubstitute: RegExp; platform?: string }> = [
+/**
+ * `stepForm` is the step that ANSWERS the gesture, when one exists. The web three have none
+ * (#593), so their honest reply is still `@manual` naming the gesture. The mobile three all
+ * compile now — `go back` closed the last of them (#626) — and the finding must say so, or it
+ * keeps telling the author to defer work the compiler can already do. Data, not a sentence in
+ * the finding: when a reload/back step lands for web, filling this field is the whole change.
+ */
+const BROWSER_GESTURES: Array<{ gesture: string; re: RegExp; appSubstitute: RegExp; platform?: string; stepForm?: string }> = [
   { gesture: 'browser back', re: /\bbrowser(?:'s)?[ -]?(?:back|history)\b|\bhistory[ -]back\b/i,
     appSubstitute: /\bclick \[[^\]]*back[^\]]*\]/i, platform: 'web' },
   { gesture: 'browser reload/refresh', re: /\b(?:page |browser )?(?:reload|refresh)(?:ing|ed|es)?\b/i,
@@ -236,21 +243,35 @@ const BROWSER_GESTURES: Array<{ gesture: string; re: RegExp; appSubstitute: RegE
   // an in-app navigation never touches — so a defect that only appears on the OS path lives
   // exactly in the substitution (#626). The check was web-only, so mobile flows were silent about
   // the very risk it exists to catch.
-  { gesture: 'the OS/hardware back gesture', platform: 'mobile',
+  { gesture: 'the OS/hardware back gesture', platform: 'mobile', stepForm: 'When User go back',
     re: /\b(?:hardware|system|os|device|android|physical)[ -]?back\b|\bback (?:gesture|button|swipe)\b|\bswipe[ -]back\b/i,
     appSubstitute: /\b(?:tap|click) \[[^\]]*back[^\]]*\]/i },
   { gesture: 'backgrounding and resuming the app', platform: 'mobile',
+    stepForm: 'When User background the app for 5 seconds',
     re: /\b(?:background(?:ing|ed)?|foreground(?:ing|ed)?|app switcher|recent apps|minimi[sz]|resum(?:e|ing)|kill(?:ed|ing)? the app|force[ -]stop|process death)\b/i,
     appSubstitute: /\b(?:tap|click) \[[^\]]+\]|is on \[[^\]]+\] screen\b/i },
   { gesture: 'rotating the device', platform: 'mobile',
+    stepForm: 'When User rotate the device to landscape',
     re: /\b(?:rotat(?:e|ing|ion)|landscape|portrait|orientation change)\b/i,
     appSubstitute: /\bis on \[[^\]]+\] screen\b/i },
 ];
 
+/**
+ * The remedy sentence for one substitution. Lives beside the gesture table rather than in the
+ * audit finding: the table is what knows whether a step exists, and a ternary buried in
+ * `audit.ts` would be one branch nothing tests. Both branches are pinned in
+ * `tests/codegen/os-back-step.run.ts`.
+ */
+export function substitutionRemedy(sub: { stepForm?: string }): string {
+  return sub.stepForm
+    ? `That gesture DOES have a step: write \`${sub.stepForm}\` instead of the in-app control.`
+    : 'The step vocabulary has no reload/back step (#593), so defer it with `@manual` naming the gesture rather than substituting silently.';
+}
+
 export function browserGestureSubstitutions(
   viewpointPath: string, scenarios: ScenarioInfo[], platform?: string,
-): Array<{ gesture: string; item: string }> {
-  const out: Array<{ gesture: string; item: string }> = [];
+): Array<{ gesture: string; item: string; stepForm?: string }> {
+  const out: Array<{ gesture: string; item: string; stepForm?: string }> = [];
   // A gesture only applies where its platform does: "reload" means nothing on a native app, and
   // "backgrounding" means nothing in a browser tab. An unknown platform checks everything, which
   // is how the web-only set behaved before.
@@ -266,7 +287,7 @@ export function browserGestureSubstitutions(
       if (!g.re.test(item.text)) continue;
       // A @manual scenario whose own subject IS the gesture is the honest answer.
       if (deferred.some((h) => g.re.test(h))) break;
-      if (automated.some((h) => g.appSubstitute.test(h))) out.push({ gesture: g.gesture, item: item.text });
+      if (automated.some((h) => g.appSubstitute.test(h))) out.push({ gesture: g.gesture, item: item.text, stepForm: g.stepForm });
       break;
     }
   }

package/src/orchestrator/templates/ai-src/commands/delivery.md

@@ -201,8 +201,9 @@ re-asking.
 Forward the CLI summary verbatim (Items = review rows; **Variants = execution units — progress is
 counted in variants, never items**). Then `AskUserQuestion`:
 
-- **Open the workbook** — inspect `qa/deliverables/<unit>-testcases.xlsx` (Testcases sheet:
-  collapse outline level 1 for the customer view; Coverage sheet: target × category grid + gaps).
+- **Open the workbook** — inspect `qa/deliverables/<unit>-testcases.xlsx` (Overview: live roll-up;
+  Auto / Manual: collapse outline level 1 for the customer view; Coverage: target × category
+  grid + gaps).
 - **Run tests to refresh results** — `/sungen:run-test <unit>`, then re-run delivery.
 - **Also export CSV** — `sungen delivery <unit> --format csv` (flat `item`/`variant` rows for pipelines).
 - **Export the legacy workbook too** — `sungen delivery <unit> --legacy`.
@@ -231,6 +232,6 @@ sungen delivery [names...]        # matrix (default; needs the map) → XLSX onl
   --skip-preflight | --continue-on-missing | --env <env>   # as before
 ```
 
-Outputs: `qa/deliverables/<unit>-testcases.xlsx` (Testcases + Coverage sheets) by default;
+Outputs: `qa/deliverables/<unit>-testcases.xlsx` (Overview + Auto + Manual + Coverage sheets) by default;
 `--format csv` writes `<unit>-testcases.csv` instead (flat, `Level` column `item|variant`),
 `--format both` writes both. Legacy mode writes the classic files instead.

package/src/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/src/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/src/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}}
@@ -153,6 +156,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
@@ -214,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]`
 
 ```
@@ -374,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
@@ -387,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/src/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/src/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/src/orchestrator/templates/ai-src/skills/sungen-selector-keys/SKILL.md

@@ -225,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 |
@@ -238,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/src/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: