@sun-asterisk/sungen 3.2.0-beta.142 → 3.2.0-beta.144

package/src/harness/sensors.ts

@@ -11,17 +11,36 @@ import * as path from 'path';
 import { parse as parseYaml } from 'yaml';
 import { ScenarioInfo, ViewpointEntry, idPrefix } from './parse';
 
-// Business-critical category codes (project VP-<CAT> prefixes). Configurable later.
-const BUSINESS_CRITICAL_CATS = ['LIST', 'CART', 'PRODUCT', 'FILTER', 'CHECKOUT', 'ORDER'];
-
-// Buckets for coverage-balance.
-const BUCKETS: Record<string, string[]> = {
-  'business-core': BUSINESS_CRITICAL_CATS,
-  'presentation': ['UI'],
-  'validation-security': ['VAL', 'SEC', 'SUB'],
-  'behavior': ['LOGIC'],
-  'navigation': ['NAV'],
-};
+// Business-critical category keywords (matched by CONTAINMENT against the VP category, so a
+// compound category like LIST-DISPLAY / ADD-TO-CART / PRODUCT-DISCOVERY classifies correctly).
+const BUSINESS_CRITICAL_CATS = [
+  // UI commerce cores
+  'LIST', 'CART', 'PRODUCT', 'FILTER', 'CHECKOUT', 'ORDER', 'DETAIL', 'DISCOVERY', 'CATEGORY', 'BRAND', 'DUPLICATE', 'CONSISTENCY',
+  // API / DB capability cores — for an api/db suite the operation IS the business core
+  'API', 'ENDPOINT', 'CRUD', 'QUERY', 'CONTRACT', 'RESOURCE',
+];
+
+// Bucket keyword sets for coverage-balance, in PRECEDENCE order (first match wins). Matched by
+// substring containment so compound categories land in the right bucket (H1): e.g. LIST-DISPLAY
+// → business-core (LIST) not presentation (DISPLAY); CART-TRANSITION → business-core (CART).
+const BUCKET_ORDER: Array<[string, string[]]> = [
+  ['business-core', BUSINESS_CRITICAL_CATS],
+  ['behavior', ['LOGIC', 'TRANSITION', 'WORKFLOW']],
+  ['validation-security', ['VAL', 'SEC', 'SUB', 'AUTH', 'LOGIN']],
+  ['navigation', ['NAV']],
+  ['presentation', ['UI', 'LAYOUT', 'RESPONSIVE', 'DISPLAY', 'SEO', 'ACCESSIBILITY', 'USABILITY', 'VISUAL']],
+];
+const BUCKETS: Record<string, string[]> = Object.fromEntries(BUCKET_ORDER);
+
+/** Classify a VP category into a balance bucket by keyword containment + precedence (H1). */
+export function bucketForCategory(category: string | undefined): string {
+  const cat = (category || '').toUpperCase();
+  if (!cat) return 'other';
+  for (const [bucket, kws] of BUCKET_ORDER) {
+    if (kws.some((k) => cat.includes(k))) return bucket;
+  }
+  return 'other';
+}
 
 export interface ThemeDepth {
   requires: string;           // 'data-assertion' → scenarios on this theme must assert DATA
@@ -242,6 +261,72 @@ export function flowCoveredThemes(
   return out;
 }
 
+// ---------- Sensor: Flow regression-depth (H3) ----------
+
+export interface FlowDepthResult {
+  stateful: boolean;       // the suite mutates a cart/checkout collection (add/remove/quantity)
+  countProof: boolean;     // asserts a row count / item quantity, not just presence
+  teardown: boolean;       // removes an item and verifies the empty/zero state
+  multiSource: boolean;    // adds from >1 distinct source (e.g. main list AND recommended)
+  ratio: number;           // covered dimensions / 3 (1 when not stateful → neutral)
+  missing: string[];
+}
+
+/**
+ * Grades a STATEFUL flow's regression depth beyond "theme covered": a cart/checkout flow that only
+ * proves an item is present is shallower than one that proves the quantity/count, tears the state
+ * back down (remove → empty), and exercises every add-to-cart source. The ratio caps the
+ * businessDepth headroom (audit.ts) so a thin stateful flow can't reach a perfect score. (H3)
+ */
+export function flowRegressionDepth(scenarios: ScenarioInfo[]): FlowDepthResult {
+  const hay = scenarios.map((s) => s.haystack);
+  const any = (re: RegExp) => hay.some((h) => re.test(h));
+  const addsToCart = any(/\b(add to cart|add to basket|added (?:to )?(?:the )?cart|adds? .* cart)\b/i);
+  const stateful = (any(/\b(cart|basket|checkout)\b/i) && (addsToCart || any(/\b(remove|delete|quantity|cart line|cart row)\b/i)));
+  if (!stateful) return { stateful: false, countProof: false, teardown: false, multiSource: false, ratio: 1, missing: [] };
+
+  // 1. Count/quantity proof — a row count or item quantity, not just presence of a row.
+  const countProof = any(/\b(quantity|qty|two (?:rows|lines|cart)|row count|count column|number of items|one[_ ]row|two[_ ]rows|qty[_ ])/i);
+  // 2. Teardown — removes the item and verifies the empty/zero state (the inverse operation).
+  const teardown = any(/\b(remove|delete|clear)\b/i) && any(/\b(empty|no items|zero|removed|0 items)\b/i);
+  // 3. Multi-source — the cart is fed from >1 source (the main list AND a recommended/related rail).
+  const multiSource = any(/\b(recommended|related|you may also|suggest)\b/i) && addsToCart;
+
+  const dims: Array<[string, boolean]> = [['count-proof', countProof], ['teardown', teardown], ['multi-source', multiSource]];
+  const missing = dims.filter(([, v]) => !v).map(([k]) => k);
+  return { stateful: true, countProof, teardown, multiSource, ratio: (dims.length - missing.length) / dims.length, missing };
+}
+
+// ---------- Sensor: Oracle strength (H4) ----------
+
+export interface OracleStrengthResult {
+  weak: { name: string; hint: string }[];   // scenarios proving facet membership by a name-substring
+  facetClaims: number;                       // scenarios that touch a category/brand facet (denominator)
+  ratio: number;                             // 1 - weak/facetClaims (1 when none) — caps businessDepth
+}
+
+// "see all [<item name/title>] ... contain(s) {{<facet>.term}}" — asserting every item's NAME carries
+// a category/brand term does NOT prove the item BELONGS to that facet (a "Dress" item need not contain
+// "Dress" in its name). The strong oracle is the results-page title/header, a detail-page facet field,
+// an API/DB query, or an explicit @manual:M2 deferral.
+const WEAK_FACET_ORACLE = /\bsee all\b\s*\[[^\]]*\b(name|title|label)\b[^\]]*\][^{[]*\bcontains?\b[^{]*\{\{[^}]*\b(categ|brand|facet|filter|term)/i;
+const FACET_REF = /\{\{[^}]*\b(categ|brand|facet|filter)\b[^}]*\}\}|\b(category|brand)\b/i;
+
+export function oracleStrength(scenarios: ScenarioInfo[]): OracleStrengthResult {
+  const weak: { name: string; hint: string }[] = [];
+  for (const s of scenarios) {
+    if (s.manual) continue; // a @manual facet check is a deliberate deferral, not a weak automated oracle
+    if (WEAK_FACET_ORACLE.test(s.stepsText)) {
+      weak.push({
+        name: s.name.slice(0, 80),
+        hint: 'asserting every item NAME contains a category/brand term does not prove facet membership — assert the results-page TITLE/header carries the facet, a detail-page facet field, or an API/DB oracle; or defer the exhaustive check to @manual:M2.',
+      });
+    }
+  }
+  const facetClaims = scenarios.filter((s) => FACET_REF.test(s.stepsText) || FACET_REF.test(s.name)).length;
+  return { weak, facetClaims, ratio: facetClaims ? 1 - weak.length / Math.max(1, facetClaims) : 1 };
+}
+
 /** Collect data-correctness themes (depth.requires) for a page-type + universal. */
 export function dataThemesFor(catalog: Catalog, pageType: string | null): CatalogTheme[] {
   const themes: CatalogTheme[] = [];
@@ -258,6 +343,7 @@ export interface BalanceResult {
   coreCount: number;
   secondaryCount: number;
   imbalanced: boolean;
+  unclassifiedRatio: number;   // share of scenarios that fell into `other` (taxonomy drift signal, H1)
   note: string;
 }
 
@@ -270,23 +356,21 @@ export function coverageBalance(scenarios: ScenarioInfo[]): BalanceResult {
   for (const s of scenarios) {
     const cat = s.category || 'NONE';
     byCategory[cat] = (byCategory[cat] || 0) + 1;
-    const bucket = Object.entries(BUCKETS).find(([, cats]) => cats.includes(cat))?.[0] || 'other';
-    byBucket[bucket]++;
+    byBucket[bucketForCategory(s.category)]++;
   }
 
   const core = byBucket['business-core'];
   const secondary = byBucket['presentation'] + byBucket['validation-security'];
   const imbalanced = secondary > core * 1.5 && core > 0;
-  return {
-    byBucket,
-    byCategory,
-    coreCount: core,
-    secondaryCount: secondary,
-    imbalanced,
-    note: imbalanced
+  const unclassifiedRatio = scenarios.length ? byBucket['other'] / scenarios.length : 0;
+  // A high `other` share means the VP taxonomy drifted from the catalog — the balance axis is then
+  // unreliable, so we surface it (audit.ts caps the balance contribution on this signal).
+  const note = unclassifiedRatio > 0.4
+    ? `Taxonomy drift: ${byBucket['other']}/${scenarios.length} scenarios have an unrecognised VP category (bucket=other) — balance is unreliable until the viewpoint codes match the catalog.`
+    : imbalanced
       ? `Secondary viewpoints (presentation+validation/security = ${secondary}) outweigh business-core (${core}) by >1.5x.`
-      : 'Balanced.',
-  };
+      : 'Balanced.';
+  return { byBucket, byCategory, coreCount: core, secondaryCount: secondary, imbalanced, unclassifiedRatio, note };
 }
 
 // ---------- Sensor 4: Duplicate clusters ----------
@@ -300,6 +384,10 @@ export interface DuplicateResult {
 export function duplicateClusters(scenarios: ScenarioInfo[]): DuplicateResult {
   const map = new Map<string, ScenarioInfo[]>();
   for (const s of scenarios) {
+    // @manual scenarios compile to a degenerate skeleton (no executable steps), so they cluster
+    // with each other even though each is a distinct judgment/capability-manual viewpoint. Excluding
+    // them keeps the exact-dup signal about genuinely-copied AUTOMATED scenarios (H2).
+    if (s.manual) continue;
     const arr = map.get(s.stepSkeleton) || [];
     arr.push(s);
     map.set(s.stepSkeleton, arr);

package/src/orchestrator/ai-rules-updater.ts

@@ -65,6 +65,10 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['claude-skill-capture-mode-live.md', '.claude/skills/sungen-capture/mode-live.md'],
   ['claude-skill-capture-mode-local.md', '.claude/skills/sungen-capture/mode-local.md'],
   ['claude-skill-locale.md', '.claude/skills/sungen-locale/SKILL.md'],
+  // Mobile (Appium) skills — relevant for platform: mobile (MOB-5).
+  ['claude-skill-mobile-gestures.md', '.claude/skills/sungen-mobile-gestures/SKILL.md'],
+  ['claude-skill-capture-mobile.md', '.claude/skills/sungen-capture-mobile/SKILL.md'],
+  ['claude-skill-selector-fix-mobile.md', '.claude/skills/sungen-selector-fix-mobile/SKILL.md'],
 
   // Agents — Claude Code sub-agents (isolated context). Copilot runs these inline.
   ['claude-agent-reviewer.md', '.claude/agents/sungen-reviewer.md'],
@@ -96,6 +100,10 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['github-skill-sungen-capture-mode-live.md', '.github/skills/sungen-capture/mode-live.md'],
   ['github-skill-sungen-capture-mode-local.md', '.github/skills/sungen-capture/mode-local.md'],
   ['github-skill-sungen-locale.md', '.github/skills/sungen-locale/SKILL.md'],
+  // Mobile (Appium) skills — relevant for platform: mobile (MOB-5).
+  ['github-skill-sungen-mobile-gestures.md', '.github/skills/sungen-mobile-gestures/SKILL.md'],
+  ['github-skill-sungen-capture-mobile.md', '.github/skills/sungen-capture-mobile/SKILL.md'],
+  ['github-skill-sungen-selector-fix-mobile.md', '.github/skills/sungen-selector-fix-mobile/SKILL.md'],
 ];
 
 // Skill/asset directories retired in a previous refactor. `sungen update` removes

package/src/orchestrator/templates/ai-instructions/claude-skill-capture-mobile.md

@@ -0,0 +1,184 @@
+---
+name: sungen-capture-mobile
+description: 'Capture a live mobile app screen via Appium MCP — locator tree + screenshot for visual context. Auto-loaded by create-test when the screen is @platform:mobile/android/ios.'
+user-invocable: false
+---
+
+## Purpose
+
+Launch a mobile app on a device/emulator, capture **one locator tree** (`generate_locators`) and **one screenshot**, and save them as visual context for test generation. The mobile analogue of `sungen-capture-live` — same job, Appium MCP instead of Playwright MCP.
+
+Use when the target is a native/Flutter/React-Native app (`@platform:android` or `@platform:ios`) running on a connected device or emulator.
+
+---
+
+## Prerequisites
+
+- `appium-mcp` connected (see `/mcp`). It runs Appium **embedded** — no separate server needed.
+- A device/emulator booted: `adb devices` shows one for Android; a Simulator for iOS.
+- The app **installed** on the device (`adb install -r <app>.apk` for Android).
+- The screen's `Path:` (in `<screen>/features/*.feature` or `spec.md`) gives the app entry as
+  `<appPackage>/<appActivity>` (Android) or bundleId (iOS), e.g. `com.kngroup.media.converter/.MainActivity`.
+
+---
+
+## Steps
+
+### 1. Resolve target app + entry
+
+Resolve in this order:
+1. `Path:` line in the feature / `App ID` in `spec.md` → split into `appPackage` + `appActivity`.
+   A dual-id Path (`<pkg>/<activity> | <iosBundleId>`) → take the part for the OS you are exploring
+   (left of `|` = Android pkg/activity, right = iOS bundle id).
+2. If missing → `AskUserQuestion`: *"What is the appPackage/appActivity (Android) or bundleId (iOS)?"*
+3. **Navigation recipe** — read the feature's `Background:` (the in-app web-path analog). Line 1
+   `Given User is on [Home] screen` is the launcher/landing screen the app opens on; each following
+   `When/And User tap [...]` (or gesture) is one hop toward the target screen. You will **replay**
+   these in step 4.5 so you scan the screen this feature targets — not the launcher. An anchor-only
+   Background (no nav steps) ⇒ the target IS the launcher screen ⇒ no navigation needed.
+
+### 2. Select device
+
+`select_device` with `platform: android` (or `ios`). If exactly one device, it auto-selects.
+If several, list them and ask the user which `deviceUdid`.
+
+### 3. Create the session
+
+`appium_session_management` `action=create`, `platform=android`, capabilities (JSON string):
+```
+appium:appPackage, appium:appActivity, appium:udid,
+appium:noReset=true, appium:autoGrantPermissions=true, appium:newCommandTimeout=300
+```
+For iOS, call `prepare_ios_simulator` first, then create with `appium:bundleId`.
+
+### 4. ⚠️ Wait for the screen to actually render
+
+**This is the #1 gotcha for Flutter / RN apps.** Right after launch the app often shows a blank
+splash — and the locator tree will contain **zero usable elements** (just an empty `FrameLayout`).
+Do **not** capture yet. Take a quick `appium_screenshot`; if it's blank/splash, wait and re-check
+until real content is drawn. Only then capture. (A Flutter app on a loading screen looks "invisible"
+to Appium; the same app on a rendered screen exposes its full Semantics tree.)
+
+### 4.5. ⚠️ Navigate to the target screen (replay the navigation recipe)
+
+**This is what makes capture land on the RIGHT screen** — the mobile equivalent of `page.goto(url)`
+on web. After the launcher screen has rendered, replay the `Background:` nav steps so Appium ends up
+on the screen this feature targets, *then* capture there.
+
+For each nav step **after** the `Given User is on [Home] screen` anchor, in order:
+1. `generate_locators` (or `appium_get_page_source`) on the CURRENT screen.
+2. Resolve the step's `[Label]` against the live tree — prefer `accessibility id`, then visible
+   `text`/`content-desc`, then an `xpath` on a distinctive substring. Gestures (`scroll to [X]`,
+   `swipe …`) follow `sungen-mobile-gestures`.
+3. Perform the tap/gesture, then **wait for the next screen to render** (same blank-splash guard as
+   step 4) before the next step.
+
+After the LAST step you are on the target screen — capture HERE (steps 5–6).
+
+- **Anchor-only Background** (no nav steps) ⇒ the target IS the launcher screen ⇒ skip this step.
+- **A step won't resolve** (its `[Label]` matches no element) ⇒ **STOP. Do not capture the wrong
+  screen.** Screenshot where you are and report: *"recipe step N: [Label] not found — fix the
+  Background nav path."* Fail loud (run-test would fail at the same step anyway).
+- **No recipe yet** (guided-stub Background, but the target is NOT the launcher) ⇒ drive to the
+  screen interactively off the live tree (if unsure which control leads there, `AskUserQuestion`),
+  then **report the exact nav steps you took** so create-test/add-screen can write them into the
+  Background. Do **not** edit the `.feature` yourself — Gherkin authorship stays with those commands.
+
+### 5. Capture the locator tree (primary AI context)
+
+Call **`generate_locators`** — this is the mobile equivalent of the web accessibility snapshot. It
+returns priority-ranked locators per interactable element: `accessibility id`, `id`, platform-native
+(`-android uiautomator` / `-ios predicate string`), and `xpath`, plus `content-desc`/`text`,
+`clickable`, `enabled`. This is what `sungen-tc-generation` and `sungen-selector-keys` consume.
+
+If the tree is huge, also `appium_get_page_source` (saved to a file) and grep it — never dump the
+full XML inline.
+
+### 6. Screenshot
+
+`appium_screenshot` → save to:
+```
+qa/screens/<screen>/requirements/ui/mobile-<timestamp>.png
+```
+`<timestamp>` = `YYYYMMDD-HHMM` local (e.g. `mobile-20260605-1645.png`).
+
+### 7. Detect discrepancies vs spec
+
+If `spec.md` exists, cross-check `generate_locators` labels against spec sections (fields in spec but
+not on screen, and vice-versa). Report; do **not** auto-edit `spec.md`.
+
+### 8. End the session
+
+`appium_session_management` `action=delete` to free the device. Always clean up.
+
+### 9. Report back
+
+> Captured mobile screen `<appPackage>`:
+> - Reached via: <N nav steps replayed from the Background recipe, or "launcher screen — no nav">
+> - Locators: <N> interactable elements (M with accessibility-id)
+> - Screenshot: `requirements/ui/mobile-<timestamp>.png`
+> - Discrepancies vs spec: <count, or "none">
+> - Discovered nav steps (only if the recipe was empty): <the taps you took, for create-test/add-screen to write into the Background>
+
+Hand back to the calling command.
+
+---
+
+## Cross-platform discovery (`@platform:mobile` — explore one OS, layer the rest)
+
+When the screen is **`@platform:mobile`** (write-once-run-both), discover the **shared** cases first,
+then peel off only what is genuinely OS-specific. You do **not** need to explore both OSes up front —
+Flutter/RN expose the same Semantics on each, so one exploration covers most of it.
+
+1. **Explore whichever OS has a device up** (Android or iOS — symmetric for Flutter). Capture the tree.
+2. **Classify each component** into THREE buckets (not two):
+   - **Shared-exact** → a stable `accessibility id` equal on both OSes (Flutter Semantics → same value on
+     Android `content-desc` AND iOS `name`) → flat `type: accessibility-id` key in `<screen>.feature`.
+   - **Shared-variant** → SAME step/assertion on both OSes but the LOCATOR differs (composite
+     `content-desc` vs `-ios predicate`; partial/dynamic text via `descriptionContains` vs predicate
+     `CONTAINS`; a different attribute) → STILL `<screen>.feature`, with `android:`/`ios:` variant keys in
+     selectors.yaml. **A native locator alone is NOT a reason to split** — default for composite/partial text.
+   - **Sub-feature** → ONLY for genuine SCENARIO divergence: an element on ONE OS only, divergent
+     steps/flow, an OS-exclusive gesture/permission/dialog flow, or a case needing a per-platform
+     `nth`/`scope` (a variant can't diverge those). → `<screen>-android.feature` / `<screen>-ios.feature`.
+3. **Report the classification** so create-test/run-test scaffolds the right thing:
+   - `<screen>.feature`         `@platform:mobile`  ← shared-exact AND shared-variant (the vast majority)
+   - `<screen>-android.feature` `@platform:android` ← ONLY scenario-divergent Android cases
+   - `<screen>-ios.feature`     `@platform:ios`     ← ONLY scenario-divergent iOS cases
+4. **Verifying the other OS needs no second exploration** — just running the shared spec there
+   (`MOBILE_PLATFORM=both`) IS the check. Re-capture on the 2nd OS only for components that fail, and
+   move those into that OS's sub-feature. (Asking devs to add a Semantics label to an unlabeled element
+   converts an OS-specific case back into a shared one — prefer that when feasible.)
+
+## Selector-quality notes (carry into selectors.yaml)
+
+- **Prefer `accessibility id`** (Android `content-desc` / iOS `accessibilityIdentifier`) — most stable.
+- For **Flutter**, the Semantics label surfaces as `content-desc` ⇒ it usually equals the **visible
+  text**, so it is **locale-dependent** ("Good afternoon!", "English"). Keep such values in test-data
+  and use `{{variable}}` + locale overlays (see `sungen-locale`).
+- **Composite nodes**: cards may concatenate child text into one `content-desc` with `\n` → prefer an
+  xpath `contains(@content-desc,'…')` on a distinctive substring.
+- **Duplicate labels** → use `nth`. **Unlabelled controls** (search fields, icon buttons) → fall back
+  to `xpath` / class.
+
+---
+
+## What this skill does NOT do
+
+- Does not run tests or generate `selectors.yaml` (that's `/sungen:run-test` + `sungen-selector-fix-mobile`)
+- Does not generate Gherkin (that's `sungen-tc-generation`) — it may *report* discovered nav steps,
+  but writing them into the Background is create-test/add-screen's job
+- Does not handle login/auth state (mobile auth is a separate concern — deep link / test build)
+- Captures **the feature's target screen** per invocation — reached by replaying the Background
+  navigation recipe (step 4.5), not just the launcher. For a *different* screen, give it its own
+  feature + recipe and re-invoke.
+
+---
+
+## Relationship to other capture skills
+
+- `sungen-capture-figma` / `sungen-capture-local` — design/image sources (platform-agnostic)
+- `sungen-capture-live` — web (Playwright MCP)
+- `sungen-capture-mobile` — this skill, mobile (Appium MCP)
+
+All write to `requirements/ui/` and report back to the caller.

package/src/orchestrator/templates/ai-instructions/claude-skill-mobile-gestures.md

@@ -0,0 +1,109 @@
+---
+name: sungen-mobile-gestures
+description: 'Mobile gesture patterns (swipe, long-press, scroll-to, pinch, pull-to-refresh) — Gherkin syntax + Appium MCP mapping. Auto-loaded for @platform:mobile/android/ios screens.'
+user-invocable: false
+---
+
+## Purpose
+
+Document the **mobile-only interactions** that have no web equivalent, so the AI can (a) drive them
+during exploration via Appium MCP and (b) write Gherkin steps for them. These are gestures the web
+patterns (`click`, `hover`, `fill`) don't cover.
+
+> Codegen status (Phase 3): the Appium adapter now **compiles** these gesture steps to WebdriverIO:
+> - **`tap` / `taps`** — synonym for `click` (→ `.click()`); **`double-tap`** → double-click.
+> - **`scroll to [X]`** → `.scrollIntoView()` (shared `scroll-action` template).
+> - **`swipe <dir> on [X]`** → `mobile: swipeGesture`.
+> - **`long-press [X] [for N seconds]`** → `mobile: longClickGesture`.
+> - **`rotate to landscape|portrait`** → `driver.setOrientation(...)`.
+> - **`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)`.
+> - **`open notification panel`** → `driver.openNotifications()`. **Android-only** — XCUITest has no
+>   notification-shade automation; on iOS the generated step throws loud. Keep such scenarios `@platform:android`.
+> - **`tap top of [X]`** / **`tap [X] at top`** → tap the element's **visible top edge** (`mobile: clickGesture`
+>   at top-centre from the element bounds) instead of its centre — use when the centre is occluded by a
+>   floating bottom bar so a normal centre tap would hit the bar.
+>
+> Still exploration-only (no codegen yet): grant/deny permissions, clipboard set/get, dismiss system
+> dialog — author with the `appium_*` tool calls below; templates land in a later phase.
+>
+> 📜 **`scroll to [X]` — two failure modes seen, with the real cause (measured):**
+> 1. *"Default scrollable element '//android.widget.ScrollView' not found"* — wdio's mobile scroll runs
+>    `$$('//android.widget.ScrollView')` and throws if 0 match. This is **state-dependent**: that node
+>    exists on a list/Home screen but NOT on every screen (tool/tab screens may lack it). If scroll runs
+>    while the app is on a screen without one → this error. Not "the screen can't scroll".
+> 2. **`.scrollIntoView()` is a NO-OP when the target is already inside the scroll viewport** — even if it's
+>    visually **occluded by a floating bottom nav**. scrollIntoView only scrolls things that are *off-screen*;
+>    it has no concept of z-order occlusion (verified: element bounds identical before/after, centre tap
+>    still hit the nav). So scroll **cannot** fix an occluded-by-overlay element → use **`tap top of [X]`**
+>    (visible-point tap), not scroll.
+>
+> `scroll to [X]` is still useful for genuinely **off-screen** items: it uses Android `UiScrollable`
+> (accessibility-id targets) or a `mobile: scrollGesture` fallback.
+>
+> ⚠️ **Flutter note:** `.scrollIntoView()` looks for a native `android.widget.ScrollView`. Flutter
+> (and some RN) scrollables don't expose one, and a screen whose content fits the viewport isn't
+> scrollable at all — there `scroll to` fails or no-ops. For an element merely **occluded by a floating
+> bottom nav** on a non-scrollable screen, neither scroll nor `element.click()` (taps the occluded
+> centre) works; that needs a visible-point/coordinate tap (not yet supported) → tag such a scenario
+> `@manual` for now.
+
+---
+
+## Gesture catalog
+
+All map to the `appium_gesture` MCP tool (action + params). Element-relative gestures pass `elementUUID`
+from `appium_find_element`; screen gestures pass `direction` or coordinates.
+
+| Intent | Proposed Gherkin | `appium_gesture` |
+|---|---|---|
+| Tap | `User tap [Settings]` | `action=tap, elementUUID` |
+| Double-tap | `User double-tap [Photo]` | `action=double_tap, elementUUID` |
+| Long-press | `User long-press [Item] for 2 seconds` | `action=long_press, elementUUID, duration=2000` |
+| Swipe (dismiss/switch/carousel) | `User swipe left on [Card]` | `action=swipe, elementUUID, direction=left` |
+| Pull-to-refresh | `User pull-to-refresh on [Feed]` | `action=swipe, direction=down, speed=fast` |
+| 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` |
+| Drag & drop | `User drag [A] onto [B]` | `appium_drag_and_drop` (separate tool) |
+
+Other device-level actions (separate MCP tools, future Gherkin):
+- Rotate: `appium_orientation` — `User rotate to landscape`
+- Permission dialog: `appium_mobile_permissions` / `appium_alert` — `User grant [Location] permission`
+- Background/foreground: `appium_app_lifecycle` — `User send app to background for 5 seconds`
+- Clipboard: `appium_mobile_clipboard` — `User paste into [Field]`
+- Notifications: open panel via `appium_mobile_device_control`
+
+---
+
+## Authoring guidance
+
+- **Prefer `scroll_to_element` over blind scrolling.** When a target may be off-screen, use
+  `appium_gesture action=scroll_to_element` (same strategy+selector as the find) rather than repeated
+  `appium_find_element` — it stops when the element appears or the page stops scrolling.
+- **Direction semantics**: `swipe` = dismiss / switch screen / carousel / pull-to-refresh (use
+  `speed=fast`); `scroll` = browse content in a list/feed. Choose by intent, not interchangeably.
+- **Long-press duration**: default 2000ms; pass `duration` for context menus that need a longer hold.
+- **Element vs screen**: pass `elementUUID` to gesture relative to an element; omit it (+ `direction`)
+  to gesture on the whole screen.
+- **Gestures in the navigation recipe**: a `Background:` step like `When User scroll to [X]` or
+  `And User swipe up on [Feed]` is a valid nav hop — `sungen-capture-mobile` replays it to reach the
+  target screen before scanning (see "Background = the navigation recipe" in `sungen-gherkin-syntax`).
+
+---
+
+## Selectors for gestures
+
+Same rules as `sungen-selector-fix-mobile`: `accessibility-id` first, then `id`, platform-native, xpath.
+For `scroll_to_element`, the `strategy`+`selector` you pass are the target you're scrolling toward — keep
+them stable (accessibility-id) so the scroll terminates reliably.
+
+---
+
+## What this skill does NOT do
+
+- Does not implement gesture codegen (templates land in a later phase).
+- Does not replace `sungen-gherkin-syntax` — it supplements it with the mobile-only step vocabulary.
+- Does not cover tap/set-value/assertions (those are the shared Tier-1 patterns already supported).