@sun-asterisk/sungen 3.2.21 → 3.2.22-beta.2

package/src/harness/perf.ts

@@ -0,0 +1,112 @@
+/**
+ * Performance budgets — config + percentile math + the per-unit verdict. (#569)
+ *
+ * A flow's regression value includes "still fast enough": after a lib/framework
+ * upgrade the main journeys must not only pass but hold their response-time
+ * budget. Sungen had no perf concept at all — the Playwright JSON parser even
+ * dropped the `duration` field Playwright already emits on every result.
+ *
+ * Scope discipline:
+ *   - This is config + measurement + report over runs sungen already makes.
+ *     Real load tests stay @manual:M8 → a dedicated tool.
+ *   - The AUDIT never reads it: the quality score is documented as a pure
+ *     function of the design artifacts ("reads no test-results, live page, or
+ *     clock"). Perf reports where runs are already read — `sungen delivery`
+ *     and the dashboard. Advisory: a blown budget never fails the design gate.
+ *
+ * Config: qa/perf.yaml
+ *   percentile: p75          # default p75 — "≥75% of runs meet the budget"
+ *   defaults:
+ *     scenario_ms: 30000     # whole-scenario wall clock (Playwright duration)
+ *     page_load_ms: 3000     # Phase B — needs per-transition runtime timing
+ *     transition_ms: 2000    # Phase B
+ *   units:
+ *     place-order: { scenario_ms: 20000 }
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { readTextFile } from './read-text';
+
+export interface PerfConfig {
+  /** 0..100 — e.g. 75 for p75. */
+  percentile: number;
+  defaults: Record<string, number>;
+  units: Record<string, Record<string, number>>;
+}
+
+export interface PerfVerdict {
+  unit: string;
+  metric: string;            // 'scenario_ms' today; page_load_ms/transition_ms in Phase B
+  percentile: number;        // 75
+  budgetMs: number;
+  measuredMs: number;        // the pXX of the observed durations
+  samples: number;
+  pass: boolean;
+  /** Titles of the slowest offenders (only when failing), for the report. */
+  slowest: Array<{ title: string; ms: number }>;
+}
+
+export function perfConfigPath(projectRoot: string): string {
+  return path.join(projectRoot, 'qa', 'perf.yaml');
+}
+
+/** Absent file → null (perf reporting is opt-in; nothing changes until configured). */
+export function loadPerfConfig(projectRoot: string): PerfConfig | null {
+  const p = perfConfigPath(projectRoot);
+  if (!fs.existsSync(p)) return null;
+  let raw: Record<string, unknown>;
+  try { raw = parseYaml(readTextFile(p)) as Record<string, unknown>; } catch { return null; }
+  if (!raw || typeof raw !== 'object') return null;
+  const pctRaw = String(raw.percentile ?? 'p75').toLowerCase().replace(/^p/, '');
+  const percentile = Math.min(100, Math.max(1, Number(pctRaw) || 75));
+  const num = (o: unknown): Record<string, number> => {
+    const out: Record<string, number> = {};
+    if (o && typeof o === 'object') {
+      for (const [k, v] of Object.entries(o as Record<string, unknown>)) {
+        const n = Number(v);
+        if (Number.isFinite(n) && n > 0) out[k] = n;
+      }
+    }
+    return out;
+  };
+  const units: Record<string, Record<string, number>> = {};
+  if (raw.units && typeof raw.units === 'object') {
+    for (const [u, o] of Object.entries(raw.units as Record<string, unknown>)) units[u] = num(o);
+  }
+  return { percentile, defaults: num(raw.defaults), units };
+}
+
+/**
+ * Nearest-rank percentile (ceil), the standard "≥pXX of samples meet the budget"
+ * reading: p75 of [a…] is the value at ceil(0.75·n) in the sorted list. One
+ * sample → that sample. Deterministic, no interpolation.
+ */
+export function percentileOf(p: number, values: number[]): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const rank = Math.min(sorted.length, Math.max(1, Math.ceil((p / 100) * sorted.length)));
+  return sorted[rank - 1];
+}
+
+/** Budget for a metric on a unit: per-unit override, else defaults, else none. */
+export function budgetFor(config: PerfConfig, unit: string, metric: string): number | undefined {
+  return config.units[unit]?.[metric] ?? config.defaults[metric];
+}
+
+/**
+ * The scenario_ms verdict for one unit's run. `durations` = per-test wall-clock ms
+ * (a @cases scenario contributes one sample per row-test — each is a real run).
+ */
+export function perfVerdict(
+  config: PerfConfig,
+  unit: string,
+  samples: Array<{ title: string; ms: number }>,
+): PerfVerdict | null {
+  const budgetMs = budgetFor(config, unit, 'scenario_ms');
+  if (budgetMs === undefined || samples.length === 0) return null;
+  const measuredMs = percentileOf(config.percentile, samples.map((s) => s.ms));
+  const pass = measuredMs <= budgetMs;
+  const slowest = pass ? [] : [...samples].sort((a, b) => b.ms - a.ms).slice(0, 3);
+  return { unit, metric: 'scenario_ms', percentile: config.percentile, budgetMs, measuredMs, samples: samples.length, pass, slowest };
+}

package/src/harness/sensors.ts

@@ -33,10 +33,22 @@ const BUCKET_ORDER: Array<[string, string[]]> = [
 ];
 const BUCKETS: Record<string, string[]> = Object.fromEntries(BUCKET_ORDER);
 
+// Flow journey-phase categories (FL-HP-001, FL-ER-002 …). Matched on exact SEGMENTS,
+// never by containment — 'SHOP'.includes('HP') is true, which is exactly the kind of
+// false hit substring matching would produce for two-letter phase tokens. (#569)
+const PHASE_BUCKETS: Record<string, string> = {
+  HP: 'business-core',          // happy path = the business goal itself
+  ER: 'validation-security',    // error recovery (validation must not trap the journey)
+  EH: 'validation-security',    // guards & leakage (direct access, back, refresh)
+};
+
 /** 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 seg of cat.split('-')) {
+    if (PHASE_BUCKETS[seg]) return PHASE_BUCKETS[seg];
+  }
   for (const [bucket, kws] of BUCKET_ORDER) {
     if (kws.some((k) => cat.includes(k))) return bucket;
   }
@@ -351,7 +363,7 @@ export function flowRegressionDepth(scenarios: ScenarioInfo[]): FlowDepthResult
   // 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);
+  const teardown = any(/\b(remove|delete|clear)(?:s|d|ed|ing)?\b/i) && any(/\b(empty|emptied|no items|zero|removed|cleared|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;
 

package/src/harness/spec-coverage.ts

@@ -66,21 +66,43 @@ export function parseSpecClauses(specPath: string): { frs: FrClause[]; valRows:
   if (!fs.existsSync(specPath)) return { frs: [], valRows: [] };
   const lines = readTextFile(specPath).split('\n');
 
+  // Requirement ids follow the PROJECT's scheme, not ours (#572): `**FR-1**:` is one
+  // convention among many — a real spec declared ~30 MUST clauses as `` `REQ-SRCH-001`: ``
+  // and the FR-locked pattern returned zero, so the MUST-coverage gate never ran and the
+  // specFR axis was excluded "for lack of evidence" that was sitting right there. Same
+  // silent-failure class as the CRLF parsers, same id-scheme-tolerance lesson as delivery.
+  //
+  // A declaration is: line-leading (optionally bulleted / bold / backticked) `<ID>:` where
+  // the id ends in a number. Table rows are EXCLUDED — traceability tables cite requirement
+  // ids without declaring them — and so are prefixes that are never requirements
+  // (test cases, viewpoints, known-defect records, data-factory checks, flows, delivery items).
+  const NON_REQUIREMENT_PREFIX = /^(TC|VP|KD|CHK|FL|DI)-/i;
   const frs: FrClause[] = [];
+  const seen = new Set<string>();
   for (const line of lines) {
-    const m = line.match(/\*\*FR-(\d+)\*\*\s*:\s*(.+)$/);
-    if (m) frs.push({ id: `FR-${m[1]}`, text: m[2].replace(/\*\*/g, '').trim(), modality: modalityOf(m[2]) });
+    if (/^\s*\|/.test(line)) continue;   // table row = citation, not declaration
+    const m = line.match(/^\s*(?:[-*+]\s+)?[*_`]*([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+[a-zA-Z]?)[*_`]*\s*:\s*(.+)$/);
+    if (!m || NON_REQUIREMENT_PREFIX.test(m[1])) continue;
+    const id = m[1].toUpperCase();
+    if (seen.has(id)) continue;          // first declaration wins
+    seen.add(id);
+    frs.push({ id, text: m[2].replace(/\*\*/g, '').trim(), modality: modalityOf(m[2]) });
   }
 
   // Validation Rules table: a row carries a Constraint, a Trigger cell, and (often) a code.
+  // A "Trigger" column alone is NOT enough to claim the table (#578): a screen-STATES table
+  // ("State ID | Trigger | URL/heading oracle | …") uses Trigger for the user action that
+  // enters the state, and reading it as validation rows invented three gate-relevant
+  // TRIGGER-UNCOVERED gaps on a real spec. The table must also name a Constraint/Rule/
+  // Validation column — the thing a validation row is ABOUT.
   const valRows: ValRow[] = [];
   let cTrigger = -1, cConstraint = -1, cCode = -1, inTable = false;
   for (const raw of lines) {
     const line = raw.trim();
-    if (line.startsWith('|') && /\btrigger\b/i.test(line) && cTrigger < 0) {
+    if (line.startsWith('|') && /\btrigger\b/i.test(line) && /\b(constraint|rule|validation)\b/i.test(line) && cTrigger < 0) {
       const cells = line.split('|').map((c) => c.trim());
       cTrigger = cells.findIndex((c) => /^trigger$/i.test(c));
-      cConstraint = cells.findIndex((c) => /constraint/i.test(c));
+      cConstraint = cells.findIndex((c) => /constraint|rule|validation/i.test(c));
       cCode = cells.findIndex((c) => /code/i.test(c));
       inTable = cTrigger >= 0;
       continue;
@@ -104,12 +126,40 @@ function scenarioBlocks(featureText: string): string[] {
   return featureText.split(/\n\s*\n/).filter((b) => /\bScenario:/.test(b)).map((b) => b.toLowerCase());
 }
 
+/**
+ * Requirement ids CITED anywhere in the feature (tags, comments, prose) — with the
+ * compressed notations authors naturally write expanded (#578 follow-up, 3rd recurrence):
+ * `REQ-CART-001..005` (range), `REQ-QTY-001/003` (enumeration). A plain substring check
+ * missed exactly the ids inside the shorthand, so a deferral comment that HONESTLY listed
+ * its flow-owned requirements still left them reported as uncovered.
+ */
+export function citedIds(featureText: string): Set<string> {
+  const t = featureText.toUpperCase();
+  const out = new Set<string>();
+  for (const m of t.matchAll(/\b([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+[A-Z]?)\b/g)) out.add(m[1]);
+  // Range: PREFIX-001..005 (also – — ~ as the dash). Width follows the FIRST number.
+  for (const m of t.matchAll(/\b([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-)(\d+)\s*(?:\.\.|–|—|~)\s*(\d+)/g)) {
+    const w = m[2].length;
+    for (let i = parseInt(m[2], 10); i <= parseInt(m[3], 10) && i - parseInt(m[2], 10) < 200; i++) {
+      out.add(m[1] + String(i).padStart(w, '0'));
+    }
+  }
+  // Enumeration: PREFIX-001/003/007 — every slash part is an id under the same prefix.
+  for (const m of t.matchAll(/\b([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-)(\d+)((?:\/\d+)+)/g)) {
+    const w = m[2].length;
+    out.add(m[1] + m[2]);
+    for (const part of m[3].split('/').filter(Boolean)) out.add(m[1] + part.padStart(w, '0'));
+  }
+  return out;
+}
+
 export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featureText: string): SpecCoverageResult {
   const { frs, valRows } = parseSpecClauses(specPath);
   if (!fs.existsSync(specPath) || (frs.length === 0 && valRows.length === 0)) {
     return { hasSpec: fs.existsSync(specPath), frTotal: 0, frCovered: 0, uncoveredMust: [], inferredOnly: [], triggerGaps: [], verdict: 'pass' };
   }
   const featLower = featureText.toLowerCase();
+  const cites = citedIds(featureText);
 
   // FR coverage: explicit @spec:FR / literal FR-id citation, else keyword fallback.
   const uncoveredMust: { id: string; text: string }[] = [];
@@ -117,7 +167,7 @@ export function specCoverage(specPath: string, scenarios: ScenarioInfo[], featur
   let frCovered = 0;
   for (const fr of frs) {
     const idLower = fr.id.toLowerCase();
-    const cited = featLower.includes(idLower);
+    const cited = featLower.includes(idLower) || cites.has(fr.id.toUpperCase());
     const words = [...new Set((fr.text.toLowerCase().match(/[a-z][a-z-]{4,}/g) || []))]
       .filter((w) => !/must|should|system|screen|users?|value|input|field/.test(w));
     const kwHit = words.length > 0 && scenarios.some((s) => words.filter((w) => s.haystack.includes(w)).length >= Math.min(2, words.length));

package/src/orchestrator/templates/ai-src/commands/add-flow.md

@@ -86,15 +86,62 @@ qa/flows/${input:flow}/
     └── ui/                        # Screenshots, mockups
 ```
 
-### 1a. Identify the screens in the flow
+### 1a. Define the flow's BOUNDARY, then its screens
 
-Ask the user: "Which screens does this flow visit, in order? (e.g., login → dashboard → award-form → confirmation)"
+> QA teams often call this level **System Test** — same thing: one fully-integrated business
+> journey verified against the spec. Use whichever name the team knows; the boundary rules
+> below are the ISTQB system-test design rules.
+
+
+A flow is the **smallest complete business action chain**: one clear trigger ending in ONE
+observable, valuable outcome. Before asking for screens, walk this checklist with the user —
+if 1, 3 or 8 fails, propose SPLITTING into separate flows:
+
+1. Exactly **one business goal**? (cart correctness + category filtering = two flows)
+2. A clear **trigger** and precondition?
+3. **One observable final outcome**? (a final assertion you can write in one sentence)
+4. Is that outcome **valuable to the actor**? (an order placed, a password reset — not "a page rendered")
+5. Is **every step necessary** for that outcome?
+6. Are all steps at the **same business abstraction**?
+7. Are optional/error branches **phases of this goal** (ER/EH), not new goals?
+8. Does **no segment** form an independently valuable flow on its own?
+9. Can you write **a single clear final assertion**?
+10. Can you name it "**Verb + outcome**"? (`place-order`, `reset-password` — not `cart-and-filter`)
+
+Then ask: "Which screens does this flow visit, in order? (e.g., login → dashboard → award-form → confirmation)"
 
 Record the screen list — you will need it for:
 - Filling `spec.md` (Step 3)
 - Suggesting `[Screen:Element]` namespace prefixes
 - Capturing visuals per screen (Step 2)
 
+### 1b. Author the Flow Contract (`requirements/flow-contract.yaml`)
+
+Write the answers down as the flow's contract — `sungen audit` scores the flow **against it**
+(the `flowCoverage` axis: HP/ER/EH journey phases; `FLOW-OUTCOME-UNPROVEN` when no automated
+scenario asserts data on the outcome screen; `FLOW-SCOPE-CREEP` when scenarios never touch it):
+
+```yaml
+goal: "Place an order for a product added from home"   # Verb + outcome
+actor: user
+trigger: "Add a product to the cart from the home featured list"
+precondition: "A registered account; an empty cart"
+outcome:
+  screen: checkout            # the [Screen:...] namespace carrying the final proof
+  assertion: "The confirmation shows the order number and the paid total"
+value: "The customer has paid; the shop has a new order"
+phases: [HP, ER, EH]          # journey phases (default); add UI only if the flow owns UI states
+stateful: cart                # the mutated collection, if any — enables regression-depth dims
+golden: true                  # optional — release-critical: Final Inspection expects @golden scenarios here
+external:                     # optional — legs owned by another team/vendor (System INTEGRATION Testing)
+  - name: payment-gateway
+    owner: vendor-x
+    screens: [payment]        # the flow namespaces that leg passes through
+```
+
+**A filled contract is an INPUT to generation — never an output.** Like `test-viewpoint.md`,
+generation must not rewrite it to match what was generated; disagree → propose the diff and ask.
+
 ### 2. Capture visual source
 
 **Mobile path** (`platform: mobile`):
@@ -187,7 +234,8 @@ If user picks `/sungen:create-test`, **you MUST use the Skill tool** to invoke i
 - Test data namespaced by phase: `login.email`, `submission.nominee`
 - `@flow` tag required at feature level
 - `Background:` should only contain the starting navigation — the URL path (web) or the `--reach` nav recipe (mobile)
-- Each scenario = one phase of the journey
+- Each scenario = one phase of the journey; ids are `FL-<PHASE>-NNN` (`HP`/`ER`/`EH`, optional `UI`)
+- One flow = ONE business goal with ONE observable outcome (`requirements/flow-contract.yaml`) — a segment with its own value is its own flow
 {{#cap parallel-subagents}}
 - Mobile flows are tagged `@platform:mobile` and run via `/sungen:run-test <flow>` (WebdriverIO, not Playwright)
 {{/cap}}

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -6,6 +6,16 @@ order: 20
 claude-tools: "Read, Grep, Bash, Glob, Write, AskUserQuestion, Skill, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot"
 copilot-tools: "[vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']"
 codex-trigger: "Run when the user asks to CREATE, generate, write, or author test cases / a .feature file for a screen or flow. Step 2 (after add-screen/add-flow, before run-test). Do NOT use for executing, running, or compiling existing tests."
+---
+## ⛔ HARD RULE — the run's LAST action is the next-step hand-back
+
+A create-test run is NOT finished when the files are written or the audit prints. The final
+action of EVERY run — success, partial, or aborted — is the next-step hand-back
+({{#cap parallel-subagents}}an `AskUserQuestion` offering the next actions{{/cap}}{{^cap parallel-subagents}}a numbered list of next-action choices{{/cap}};
+see "Finish — always hand the next step back" at the end of this file). Ending with a prose
+summary and no choices is a broken run: the operator is left guessing. This holds no matter
+how long the generation/repair loop ran.
+
 ---
 {{#cap parallel-subagents}}
 ## ⛔ HARD RULE — No Figma MCP when PAT data exists

package/src/orchestrator/templates/ai-src/commands/run-test.md

@@ -7,6 +7,29 @@ claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwr
 copilot-tools: "[read, execute, edit, vscode/askQuestions, playwright/*, appium/*]"
 codex-trigger: "Run when the user asks to RUN, execute, or compile tests, generate selectors.yaml, or run tests. Step 4. Do NOT use for authoring/creating new test cases."
 ---
+## ⛔ HARD RULE — the transition INTO this run is a tool call, never prose
+
+A QA field report: the user picked "Run test" from create-test's hand-back, and the session
+answered with a BRIEFING — missing selector, expected reds, "run under Node 22" — written as
+"Before you do…", then stopped. Correct facts, wrong role: those are conditions YOU handle
+inside the run, not reasons to stop and hand the work back.
+
+- The first thing this command produces is a **tool call** (platform detection, preflight,
+  compile — whatever comes first). Never open with a plan and end the turn.
+- A **missing selector** goes to the selector-generation/fix step — that is what this command
+  is FOR.
+- **Expected-red scenarios** (@known-defect asserting a live defect) stay red; note them in
+  the results summary, never "fix" them and never stop for them.
+- **Runtime selection is yours**: check `node -v` first. If the major version is ≥ 23 and
+  Playwright browser runs are known-broken on it, select Node 22 yourself when available —
+  `export PATH="$HOME/.nvm/versions/node/$(ls $HOME/.nvm/versions/node | grep '^v22' | tail -1)/bin:$PATH"`
+  — and say so in one line. Only if NO compatible Node exists do you stop, with the exact
+  install command as the hand-back.
+- Ending this run follows the same law as create-test: the LAST action is the next-step
+  hand-back (the AskUserQuestion in "After showing results"), no matter how the run went.
+
+---
+
 ## Role
 
 You are a **Senior Developer**.

package/src/orchestrator/templates/ai-src/skills/sungen-api-design/SKILL.md

@@ -79,10 +79,10 @@ A flow (`create → login → delete`) is a **Functional integration** test, **n
         - ":gift_image_1"    # test-data: gift_image_1 → fixtures/a.png
         - ":gift_image_2"    # test-data: gift_image_2 → fixtures/b.png
     ```
-    Each element binds its own `:param` from test-data. Use this for endpoints that accept a list of files under the same field — a single object value can only hold one file. **Automate multi-file uploads with `@api`; don't defer to `@manual`.** (File uploads use Playwright's `FormData` multipart, which requires **`@playwright/test` ≥ 1.44** — the version sungen installs by default; only projects pinned to an older Playwright need to upgrade.)
+    Each element binds its own `:param` from test-data. Use this for endpoints that accept a list of files under the same field — a single object value can only hold one file. **Automate multi-file uploads with `@api`; don't defer to `@manual`.** (File uploads are sent as `multipart/form-data` built on Node's global `FormData`/`Blob` — **Node 18+, no Playwright dependency**, so the same upload runs in mobile specs too.)
 - **`bodyFile:`** → raw binary body (the whole body IS the file's bytes, e.g. `application/octet-stream`): `bodyFile: { path: ":image", mimeType: application/octet-stream }`.
 
-Fixture path resolves cwd-relative/absolute first, else `qa/fixtures/<path>` (drop sample files there, reference by name from `test-data`). An empty resolved file param omits the part → use for missing-file `@cases` error rows. `files:`/`bodyFile:` are mutually exclusive. **Automate the upload success case with `@api`** — don't defer it to `@manual`.
+Fixture path resolves cwd-relative/absolute first, else `qa/fixtures/<path>` (drop sample files there, reference by name from `test-data`). An empty resolved file param omits the part → use for missing-file `@cases` error rows. `files:`/`bodyFile:` are mutually exclusive. A **`GET`/`HEAD` entry may carry no body at all** (no `body:`/`files:`/`bodyFile:`) — HTTP forbids it and the catalog lint refuses it; put the inputs in the path or `query`, or use `POST`. **Automate the upload success case with `@api`** — don't defer it to `@manual`.
 
 ## Per-endpoint knobs & auth patterns
 - **Timeout** — a slow endpoint can override the datasource default (15s) with `timeout_ms: 30000` on its catalog entry (else the datasource `timeout_ms` applies).

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

@@ -99,6 +99,10 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | `SG-W012` | A mock-install step written AFTER a navigation step in the same block — `page.route()` registered after `goto()` misses every request fired during page load | Move the mock-install step before the navigation, or into `Background` |
 | `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-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-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-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` |
 
 ### Runtime error → `Test data "<key>" references ${QA_*} but the environment variable is not set`
 

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

@@ -27,21 +27,26 @@ AND    →  inherits from preceding keyword
 
 ## Step Patterns (70 patterns)
 
+> **Platform legend:** unmarked = `[both]` (compiles on Playwright AND Appium). `[web]` = compiles
+> only on Playwright — the Appium template throws, naming the reason. `[mobile]` = mobile-only
+> vocabulary with no web counterpart. Every marking is checked against a shipped `.hbs` — see
+> **Platform Support** at the end of this section for the full web-only/mobile-only/divergence list.
+
 ### Setup / Form / Interaction
 
 ```
 User is on [T] page | page with {{v}} | dialog
 User fill [T] field | textarea | search | slider | date-picker with {{v}}
-User fill [T] uploader with {{f}}
+User fill [T] uploader with {{f}}                                    [web]
 User clear [T] field
 User check [T] checkbox | toggle | radio
 User uncheck [T] checkbox | toggle
 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)
+User try to click [T] button | link          # DISABLED element only — see rule below (v3.3) [web]
 User double click [T] element
-User hover [T] icon | row
+User hover [T] icon | row                    # no-op on mobile (see Platform Support)
 User drag [T] to [T2]
 User expand | collapse [T] row
 ```
@@ -60,15 +65,15 @@ NEVER use it for a click that is supposed to work — it deletes the actionabili
 User click [T] button and accept [OK] alert       # PREFERRED (v3.3): natural order,
 User click [T] button and dismiss [Cancel] alert  # compiler registers the listener first
 User click [OK | Cancel] alert                    # two-step form: must come BEFORE the trigger
-User fill [T] alert with {{v}}
+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
+User wait for N seconds | [T] page                # [T] page: web waits for the URL; 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
+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 —
@@ -81,7 +86,7 @@ User switch to [T] frame | [main] frame
 > `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"]`).
 
-### Positional table rows (v3.3)
+### Positional table rows (v3.3) `[web]`
 
 ```
 User remember [Col] column in [T] table row {{n}} as {{var}}   # read a cell by POSITION
@@ -135,6 +140,11 @@ Two asymmetries worth knowing rather than discovering:
 2. **A repeated param matches as a subset per key**, which is the same rule as "extra params are
    tolerated": every value you declare must be present, and the URL may carry more.
 
+> **Mobile:** `Then User is on [T] page` **throws** (no URL/address bar on native). `Then User see
+> [T] page` \| `page with {{v}}` **silently no-ops** — the compiled step asserts nothing and the
+> scenario passes regardless. Never use Pattern 8 to prove "landed on screen X" on mobile — assert
+> a screen-marker element instead (`Then User see [X] header`).
+
 The predicate itself lives in `specs/url-assert.ts` (auto-generated, `DO NOT EDIT`). If `[T]` has no
 `type: page` selector entry — or its key collides with a non-page entry, so `value` is something like
 `button` rather than a URL — the step falls back to another path and cannot match the real URL. The
@@ -152,7 +162,7 @@ User see all [Product Card] contain [Add To Cart] button
 
 Use the all-card form whenever a title claims *every / each* card/row exposes something — a single `User see [Add To Cart] button` does NOT prove "each card" and the harness Claim-Proof gate will flag it.
 
-### Table
+### Table `[web]`
 
 ```
 User see [Col] column in [Table] table
@@ -176,7 +186,7 @@ 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.
 
-### Browser storage (web)
+### Browser storage `[web]`
 
 ```
 Then User see [KEY] in local storage exists
@@ -189,7 +199,7 @@ Then User see key matching "PATTERN" in local storage      # regex over key name
 
 `[KEY]` is a **storage key, not a selector** — never add it to selectors.yaml. It may embed `{{vars}}`: `[{{exclusive_code}}_ACCESS_TOKEN]`. The check runs inside the browser and returns only a boolean, so a failure message never contains the stored value (safe for tokens). There is deliberately no `equals {{expected}}` form. ⚠️ `expect [KEY] in local storage …` is NOT valid (`expect` reads `{{response}}` refs only) — the compiler warns SG-W011.
 
-### Tab order (web only)
+### Tab order `[web]`
 
 ```
 Then User see tab order:
@@ -201,7 +211,7 @@ Then User see tab order:
 
 Focuses row 1 (the pinned origin — there is no separate `focus [X]` step) and asserts it actually HOLDS focus (a non-focusable ref fails loudly), then presses Tab per following row and asserts it receives focus. Cell refs ARE selector references (resolved via selectors.yaml; optional element type after the ref). Requires the `| Ref |` header and ≥2 element rows — a missing header or single row is a compile error, never an empty pass. A mismatch reports the expected ref + the actual focused element (shadow-DOM-aware tag/role/name). Limitations: web only (no Appium); declare tab order OUTSIDE `use dialog`/frame scope (cell locators render page-rooted — put `scope: dialog` on the selector ENTRIES if the elements live in a dialog); focus traps / dynamic comboboxes / `tabindex=-1` reordering / WebKit differences may need `@manual` keyboard-only audits — those stay legitimate manuals.
 
-### Network mocking (optional Mock Driver — `sungen capability add mock`)
+### Network mocking `[web]` (optional Mock Driver — `sungen capability add mock`)
 
 ```gherkin
 @mock
@@ -294,6 +304,42 @@ Full-shape contract check: `expect {{name.body}} matches schema [Ref]` validates
 - **Error (4xx/5xx)** → assert the status (via `@cases` `expect_status` or an explicit `is 4xx`); assert the error message field when the contract defines one.
 - **Anti-pattern** — re-asserting the value you just sent (`{{x.body.email}} is {{email}}` on the thing you created) proves little; assert a **server-derived** field (id, timestamp, computed status) or read it back.
 
+### Platform Support — web-only / mobile-only / divergences
+
+Every claim below is checked against a shipped `.hbs` under
+`adapters/{playwright,appium}/templates/steps/` or a shipped diagnostic — see
+`tests/codegen/adapter-template-parity.run.ts` `DIVERGENCES` for the authoritative one-sided list.
+
+**Web-only `[web]`** — the Appium template throws, naming the reason: `fill [T] uploader with
+{{f}}`, Positional table rows, the whole Table section, Browser storage, Tab order, `@mock`,
+`Then User is on [T] page` (route-assertion). Each targets something native has no equivalent for
+(HTML `<table>`, `<input type=file>`, DOM storage, keyboard-focus traversal, `page.route`, a URL bar).
+
+**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. Full syntax → `sungen-mobile-gestures`.
+
+**Divergences — compiles on both, means something different:**
+
+| 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 |
+| `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 (no WebView found) |
+| `see [X] with {{v}}` (filtered visibility forms) | CSS `hasText` filter | hand-rolled substring match over `getText()`/`content-desc` (Android) or `label`/`value` (iOS) — same substring semantics, different attribute set |
+| `… is sorted …` / `… is loading` inside a filtered row/state check | reads `aria-sort`/`aria-busy` | **throws** — no native analog for these two states specifically (the plain, unfiltered `is loading` on a spinner still works on both) |
+| `scope: dialog` selector option | resolves inside the dialog | no effect (`SG-W021`) — steps resolve against the whole screen |
+| `open notification panel` (mobile gesture) | n/a | Android-only — throws on iOS |
+
+**Partial support, not full unsupported** — read the `.hbs` before marking anything `[web]`:
+`all-contain-*`, `check`/`uncheck`/`toggle-action`, `contain-text`/`have-text-assertion`,
+`visible-filtered-assertion`, `disabled`/`hidden-with-filter-assertion` are fully supported on
+mobile even though a grep shows a `throw` somewhere in their file — the throw is a normal
+zero-match assertion failure, not a platform gap.
+
 ### States
 
 `hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `sorted ascending` `sorted descending`
@@ -366,6 +412,9 @@ award:
 
 Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `columns`
 
+`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`).
+
 ## Tags
 
 ### Functional tags (affect code generation)
@@ -383,7 +432,7 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | `@cleanup:scroll` | Auto-cleanup: scroll to top after each test (cleanupPage) |
 | `@cleanup:storage` | Auto-cleanup: clear sessionStorage after each test (cleanupPage) |
 | `@screenshot:on-failure` | Auto-capture screenshot when test fails (base.ts fixture) |
-| `@parallel` | Opt-out: fresh page per test instead of serial default (for independent scenarios) |
+| `@parallel` | Opt-out: fresh page per test instead of serial default (for independent scenarios). Compiles on mobile too, but a single device/emulator gets no session-isolation benefit from it |
 | `@beforeAll` | Hook: runs once before all tests → `test.beforeAll()` |
 | `@afterEach` | Hook: runs after each test → `test.afterEach()` (custom cleanup) |
 | `@afterAll` | Hook: runs once after all tests → `test.afterAll()` |

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

@@ -10,7 +10,8 @@ Document the **mobile-only interactions** that have no web equivalent, so the AI
 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:
+> Codegen status: the Appium adapter **compiles** all of the following (verified against the shipped
+> `.hbs` under `adapters/appium/templates/steps/{gestures,actions}/`):
 > - **`tap` / `taps`** — synonym for `click` (→ `.click()`); **`double-tap`** → double-click.
 > - **`scroll to [X]`** → `.scrollIntoView()` (shared `scroll-action` template).
 > - **`swipe <dir> on [X]`** → `mobile: swipeGesture`.
@@ -24,9 +25,19 @@ patterns (`click`, `hover`, `fill`) don't cover.
 > - **`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.
+> - **`dismiss [X]`** (any non-alert element) → best-effort tap-if-shown-within-2.5s, never fails the
+>   step (`dismiss-action`) — for launch interstitials / promo overlays, not the native alert dialog
+>   (that's the existing `accept/dismiss [OK] alert` form).
+> - **`hide the keyboard`** → `driver.hideKeyboard()`. **Android-only** — XCUITest cannot dismiss the
+>   keyboard generically (WDA throws + retries, ~12s wasted); on iOS the step is a silent best-effort
+>   no-op (never fails, just does nothing).
+> - **`grant [X] permission`** → Android `mobile: changePermissions`; iOS (Simulator only) `mobile:
+>   setPermission` — needs the `applesimutils` binary on iOS or the driver fails loud with the install hint.
+> - **`set the clipboard to {{v}}`** → `driver.setClipboard(...)`. **Write-only**: the appium adapter
+>   ships a `clipboard-text-assertion` template that reads the clipboard back, but no Gherkin pattern
+>   requests it yet — there is currently no phrasing that compiles to an actual clipboard-read
+>   assertion. Don't author "see clipboard contains X" expecting it to compile; tag it `@manual` instead.
+> - **`set location to {{lat}}, {{lng}}`** → `driver.setGeoLocation(...)`.
 >
 > 📜 **`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
@@ -69,12 +80,14 @@ from `appium_find_element`; screen gestures pass `direction` or coordinates.
 | 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):
+Other device-level actions (separate MCP tools for exploration; Gherkin now compiles — see codegen
+status above):
 - 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`
+- Clipboard write: `appium_mobile_clipboard` — `User set the clipboard to {{value}}` (read-back has
+  no Gherkin pattern yet — see codegen status above)
+- Notifications: open panel via `appium_mobile_device_control` — `User open notification panel`
 
 ---
 
@@ -104,6 +117,7 @@ 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).
+- Does not yet support a clipboard-READ assertion via Gherkin (see "Write-only" note above) — the
+  template exists but no pattern requests it.