@sun-asterisk/sungen 3.2.28 → 3.2.30

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/index.ts

@@ -18,10 +18,17 @@ export { expandRecipe } from './generators/test-generator/recipe-expander';
 export type { RecipeExpandContext, RecipeNode } from './generators/test-generator/recipe-expander';
 export type { ResolvedAppProfile } from './generators/test-generator/app-profile';
 export type { MappedStep } from './generators/test-generator/step-mapper';
+// The shared "nothing honest to compile" step body. Exported for the driver SPI: a pattern that
+// must refuse (SG-W017 and siblings) emits THIS rather than shipping a one-sided refusal template,
+// which would fail the adapter-parity gate and push playwright off its refusal-only floor of 0.
+export { unsupportedStepCode } from './generators/test-generator/patterns/unsupported-step-code';
 export type { ParsedStep } from './generators/gherkin-parser';
 export { getPathCode, inferPath, resolvePathVariables } from './generators/test-generator/utils/path-inference';
 export { formatToRegexSource, formatToRegexLiteral, hasFormatToken } from './generators/test-generator/utils/format-pattern';
 export { LIST_MEMBER_ROLES } from './generators/test-generator/utils/selector-resolver';
+// The compiler's selector-key rule. A driver needs it to look up anything keyed the way a
+// `[Reference]` is keyed — e.g. a table entry's `columns:` map (issue #674).
+export { normalizeRefLabel } from './utils/ref-key';
 
 // --- Precondition-annotation override grammar (shared by the @query / @api driver codegen) ---
 export { parseQueryOverrides } from './harness/annotation-overrides';

package/src/orchestrator/project-initializer.ts

@@ -155,6 +155,7 @@ export class ProjectInitializer {
     if (!this.mobileOnly) {
       this.createPlaywrightConfig();
       this.createSpecsBase();
+      this.createSpecsReportSanitizeReporter();
     }
 
     // Create tsconfig.json if doesn't exist (needed by both web + mobile)
@@ -594,6 +595,22 @@ export class ProjectInitializer {
     this.createdItems.push('specs/generated/base.ts');
   }
 
+  /**
+   * Create specs/generated/report-path-sanitize-reporter.ts — the Playwright reporter the config
+   * registers. Written at init (the config would otherwise reference a file only `generate` writes,
+   * and Playwright refuses to load a config whose reporter module is missing).
+   */
+  private createSpecsReportSanitizeReporter(): void {
+    const reporterPath = path.join(this.cwd, 'specs', 'generated', 'report-path-sanitize-reporter.ts');
+    if (fs.existsSync(reporterPath)) {
+      this.skippedItems.push('specs/generated/report-path-sanitize-reporter.ts');
+      return;
+    }
+    fs.mkdirSync(path.dirname(reporterPath), { recursive: true });
+    fs.writeFileSync(reporterPath, this.readTemplate('specs-report-path-sanitize-reporter.ts'), 'utf-8');
+    this.createdItems.push('specs/generated/report-path-sanitize-reporter.ts');
+  }
+
   /**
    * Create specs/test-data.ts for runtime YAML loading
    */

package/src/orchestrator/report-sanitize-reporter-install.ts

@@ -0,0 +1,109 @@
+/**
+ * Install the report-path-sanitize reporter into a project — the file under `specs/generated/` and
+ * its entry in `playwright.config.ts`.
+ *
+ * A NEW project gets both from the templates at `sungen init`. An EXISTING project has a
+ * `playwright.config.ts` that sungen wrote once and never touches again, so the reporter would never
+ * reach it: `sungen update` calls this to add the reporter file (the same refresh `sungen generate`
+ * applies to `specs/generated/base.ts`) and to insert the reporter line after the JSON reporter,
+ * once. A config that has been customised beyond recognition (no `['json'` reporter line) is left
+ * alone with a printed instruction — a wrong edit to a user's config is worse than a missing reporter,
+ * and `sungen results sanitize` (run by /sungen:run-test) covers the gap.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export const REPORTER_FILE = path.join('specs', 'generated', 'report-path-sanitize-reporter.ts');
+export const REPORTER_CONFIG_ENTRY = "['./specs/generated/report-path-sanitize-reporter.ts']";
+const TEMPLATE = 'specs-report-path-sanitize-reporter.ts';
+
+export type ConfigPatchOutcome = 'patched' | 'present' | 'absent' | 'manual';
+
+/** Write (or refresh) the reporter file from the bundled template. Returns true when the file changed. */
+export function ensureReporterFile(cwd: string, dryRun: boolean = false): boolean {
+  const templatePath = path.join(__dirname, 'templates', TEMPLATE);
+  if (!fs.existsSync(templatePath)) return false;
+  const next = fs.readFileSync(templatePath, 'utf8');
+  const target = path.join(cwd, REPORTER_FILE);
+  if (fs.existsSync(target) && fs.readFileSync(target, 'utf8') === next) return false;
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, next);
+  }
+  return true;
+}
+
+/**
+ * Add the reporter entry to `playwright.config.ts` right after the JSON reporter line.
+ *   'patched'  — inserted now
+ *   'present'  — already there (idempotent)
+ *   'absent'   — no playwright.config.ts (a mobile-only project, or not a sungen project)
+ *   'manual'   — the config has no recognisable `['json', …]` reporter line; nothing written
+ */
+export function patchPlaywrightConfig(cwd: string, dryRun: boolean = false): ConfigPatchOutcome {
+  const configPath = path.join(cwd, 'playwright.config.ts');
+  if (!fs.existsSync(configPath)) return 'absent';
+  const src = fs.readFileSync(configPath, 'utf8');
+  if (src.includes('report-path-sanitize-reporter')) return 'present';
+  const patched = insertAfterJsonReporter(src);
+  if (patched === null) return 'manual';
+  if (!dryRun) fs.writeFileSync(configPath, patched);
+  return 'patched';
+}
+
+/** `sungen update` step: install file + config entry, report what happened. */
+export function installReportSanitizeReporter(cwd: string, dryRun: boolean = false): void {
+  if (!fs.existsSync(path.join(cwd, 'playwright.config.ts'))) return; // nothing to run Playwright with — nothing to sanitize
+  // The file FIRST: a config that names a reporter module Playwright cannot find refuses to load at all.
+  const wroteFile = ensureReporterFile(cwd, dryRun);
+  if (wroteFile) console.log(`${dryRun ? '📋 would write' : '✓ wrote'} ${REPORTER_FILE}`);
+  if (!dryRun && !fs.existsSync(path.join(cwd, REPORTER_FILE))) return; // bundled template missing — leave the config alone
+  const outcome = patchPlaywrightConfig(cwd, dryRun);
+  if (outcome === 'patched') console.log(`${dryRun ? '📋 would add' : '✓ added'} the report-path-sanitize reporter to playwright.config.ts`);
+  if (outcome === 'manual') {
+    console.log(`⚠️  playwright.config.ts has no recognisable ['json', …] reporter line — add ${REPORTER_CONFIG_ENTRY} to its reporter array by hand (until then, /sungen:run-test's \`sungen results sanitize\` step keeps result files free of machine paths).`);
+  }
+}
+
+/**
+ * Insert the reporter entry right after the `['json', …]` entry, whichever shape the config uses:
+ *   - one entry per line (the current template): a new line with the same indentation
+ *   - the whole array on one line (older templates: `reporter: [['list'], ['json', {…}]],`): inline
+ * The entry's end is found by bracket depth, so an `outputFile` expression may carry any braces or
+ * quotes. `null` when there is no `['json'` entry at all.
+ */
+export function insertAfterJsonReporter(src: string): string | null {
+  const eol = src.includes('\r\n') ? '\r\n' : '\n';
+  // the first `['json'` that is code, not a commented-out line
+  let start = -1;
+  for (const m of src.matchAll(/\[\s*['"]json['"]/g)) {
+    const lineStart = src.lastIndexOf('\n', m.index!) + 1;
+    if (/^\s*(\/\/|\*)/.test(src.slice(lineStart, m.index!))) continue;
+    start = m.index!; break;
+  }
+  if (start < 0) return null;
+  let depth = 0;
+  let end = -1;
+  for (let i = start; i < src.length; i++) {
+    const ch = src[i];
+    if (ch === '[' || ch === '{' || ch === '(') depth++;
+    else if (ch === ']' || ch === '}' || ch === ')') {
+      depth--;
+      if (depth === 0) { end = i; break; }
+    }
+  }
+  if (end < 0) return null;
+  const after = end + 1;
+  const restOfLine = src.slice(after, src.indexOf('\n', after) < 0 ? src.length : src.indexOf('\n', after));
+  if (/^\s*,?\s*$/.test(restOfLine)) {
+    // the entry ends its line → add a line below it, same indentation; exactly one comma after the
+    // json entry whether or not the source had one; the file's own line ending
+    const lineStart = src.lastIndexOf('\n', start) + 1;
+    const indent = /^[ \t]*/.exec(src.slice(lineStart))![0];
+    const lineEnd = src.indexOf('\n', after);
+    const rest = lineEnd < 0 ? '' : src.slice(lineEnd + 1);
+    return `${src.slice(0, after)},${eol}${indent}${REPORTER_CONFIG_ENTRY},${lineEnd < 0 ? '' : eol}${rest}`;
+  }
+  // inline array: `…, ['json', {…}]], use: …` → `…, ['json', {…}], [reporter]], use: …`
+  return `${src.slice(0, after)}, ${REPORTER_CONFIG_ENTRY}${src.slice(after)}`;
+}

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/commands/run-test.md

@@ -68,7 +68,7 @@ When `platform: mobile`:
   SUNGEN_SPECS='./specs/generated/<name>/<name>.spec.ts' MOBILE_PLATFORM=both npm run test:mobile
   ```
   `wdio.conf.ts` auto-selects `@wdio/globals` specs and auto-starts Appium. iOS needs a booted Simulator and `IOS_BUNDLE_ID`/`IOS_UDID` env vars.
-- **Results**: the wdio reporter writes `<name>-test-result.<android|ios>[.<env>].json` — one file per capability, so a both-OS run keeps both outcomes.
+- **Results**: the wdio reporter writes `<name>-test-result.<android|ios>[.<env>].json` — one file per capability, so a both-OS run keeps both outcomes. Then run `npx sungen results sanitize` — wdio error stacks quote absolute machine paths, and the result file is committed next to the spec.
 - **Skip** the "Playwright command guidelines" section below — it applies to web only.
 - The phased waves (smoke → priority → full → regression), attempt budgets, and next-steps mirror the web flow — follow the `sungen-selector-fix-mobile` skill for the mobile equivalents.
 
@@ -305,6 +305,14 @@ PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/flows/<name>/<name>-test-result.json
 
 **DO NOT** pass `--reporter=...` flag — it overrides the reporters from `playwright.config.ts` and disables the JSON reporter that `sungen delivery` depends on.
 
+**Sanitize the result file paths right after the run** — the JSON report records the operator's absolute machine paths (`/Users/<name>/…`, `C:\Users\…`) in `config`, error locations, attachments and stack traces, and the file is committed next to the spec:
+
+```bash
+npx sungen results sanitize          # every *-test-result*.json under specs/generated + .sungen/reports/*.json → project-relative paths
+```
+
+Projects created with a recent sungen (or refreshed by `sungen update`) run the same rewrite automatically through the `report-path-sanitize-reporter` in `playwright.config.ts`; this command is the safety net for every other project and is idempotent — an already-clean file is left untouched.
+
 **Re-running a SUBSET (fix-and-retry, or a partially edited spec) when the per-target result file already exists:** the JSON reporter would OVERWRITE it and lose every result you didn't re-run. Write the subset's report to a temp file and MERGE it instead — same title wins, everything else is kept:
 
 ```bash

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

@@ -67,6 +67,16 @@ Never emit a status-only assertion for a success case. Three tiers — see also
 
 Anti-pattern to avoid: re-asserting the value you just sent (`expect {{x.body.username}} is {{username}}` on the thing you created proves little) — assert a **server-derived** field (generated id, timestamp, computed status) or read it back independently.
 
+## Alias entries (binding one endpoint twice)
+
+To bind two responses of the SAME endpoint in one scenario (a control call next to the call under
+test), clone the catalog entry under a second name (`create_order_control`) — identical to the
+original except `name`/`description`. The audit gate counts identical entries as ONE endpoint: its
+must-cover viewpoints (`contract`, `error`) are satisfied when ANY alias asserts them, so the clone
+needs no error scenario of its own. An entry on the same route that differs in any request or
+response detail (`encoding`, `body`, `headers`, `expect`, `fields`, schema) is a distinct endpoint
+and keeps its own viewpoints. An omitted `datasource` resolves to the project default before comparing.
+
 ## Output discipline
 - Enumerate the **full Tier-1 list per endpoint first**, then write incrementally (≈10–15 scenarios per Write call) — never the whole suite in one response (output-token cap).
 - Name scenarios `VP-API-NNN <what it proves>`; keep the endpoint + technique legible.

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

@@ -82,6 +82,7 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | Element is not an input | Wrong element type targeted | Change `type` or `value` to match actual element |
 | not a select | Custom dropdown, not native `<select>` | Set the widget variant: `variant: radix-select`/`antd-select` (built-in recipes), a custom recipe name from `qa/app.yaml`, or project-wide `widgets.select` in `qa/app.yaml` |
 | Frame not found | iframe selector wrong or doesn't exist | Fix `frame` value, verify iframe in snapshot |
+| Timeout / not found on a step AFTER a dialog closed, and the element is plainly there in the snapshot | **Stale dialog scope** — the scenario entered dialog scope (`Given User is on [X] dialog` or `User use dialog`) and never left. Scope is sticky: it survives the click that closed the dialog, and `wait for [X] dialog is hidden` does NOT end it. Every following locator is still prefixed with the dead dialog root | **Not a selectors.yaml fix — the locator is correct.** The `.feature` needs a `close`/`dismiss`/`exit dialog` step after the dialog closes, and the `.feature` is FROZEN during run-test → **report it as a Gherkin gap for QA** and let the test fail |
 
 ### Compile diagnostics (`sungen generate` output) → fix BEFORE running
 
@@ -90,6 +91,7 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | `SG-W001` | Step matched no pattern — sungen has no step form for the sentence. Compiles to `throw new Error("[sungen] …")` naming the step (it emitted a no-op `// TODO` before the unsupported-step gate, which let the scenario PASS asserting nothing) | Rephrase to a documented pattern (`sungen-gherkin-syntax`) or tag `@manual` with a reason. There is no silent fallback — the test goes red until one of those two is done |
 | `SG-W002` | A step's `{{value}}` was parsed but never used in the generated code | The step form isn't the one you think — check the pattern's exact syntax |
 | `SG-W003` | `{ name }` filter defaulted from the Gherkin reference on a name-from-content role (toast/alert/status) | Add explicit `name:` or opt out with `name: null` |
+| `SG-W004` | A selectors.yaml entry declares a **field no consumer reads**, so writing it changes nothing in the generated test. Reserved for this in the original diagnostics spec (`exact: true` on an entry with no construct it applies to) and implemented for the wider class by #712, where `pagination:` and `contenteditable:` were public, documented and plumbed — yet read by nothing, discoverable only by grepping. The field partition lives in `utils/selector-entry-fields.ts`, each entry naming WHO reads it. A warning, not an error: an unknown key is inert, so refusing to compile would break a project over a stray comment-turned-key while teaching nothing | Delete the field, or fix its spelling — the message names the nearest valid key. If the field genuinely should do something, that is a compiler gap: report it rather than leaving the declaration in place believing it works |
 | `SG-W005` | `qa/app.yaml` unknown key / unknown preset / unparseable | Fix the key, or `extends: native\|radix\|antd` |
 | `SG-W006` | `qa/app.<env>.yaml` found — unsupported by design | Describe the app once in `qa/app.yaml`; env differences belong in test-data overlays |
 | `SG-W007` | Browser-alert handler step written AFTER an action — listener registers too late, the dialog auto-dismisses silently | Use the compound form `click [X] button and accept [OK] alert` (preferred), or move the alert step before the trigger |
@@ -98,21 +100,32 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | `SG-W010` | A row step's `[Ref]` looks POSITIONAL (`First…`/`Last…`/`Top…`/`nth`) but has no selectors.yaml entry — the label is display-only, so the step checks existence ANYWHERE in the table; an ordering/sort-stability rule would pass even when the row moved | Declare the row in selectors.yaml (a `type: locator` value RELATIVE to the table, e.g. `first contact row:` → `value: 'tbody tr:first-child'`) — the step then asserts `toContainText` on that exact row. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
 | `SG-W011` | A storage assertion written as `expect … in local/session storage` — `expect` steps only read `{{response}}` refs, so this matches no pattern. Compiles to a `throw` (was a silent no-op) | Rewrite using the supported grammar: `User see [KEY] in local storage exists/…` |
 | `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-W013` | A page step (`see [X] page` / `is on [X] page` / `wait for [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 match can never reach it: the assertion always fails, the wait can only time out | 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-W017` | A step needs a **selector-entry field the entry does not declare**, so there is nothing honest to compile — today, a table paginate step whose table entry declares no `pagination.next`/`.prev` (#712). The mirror of `SG-W004`: that one reports a field written that nothing reads, this one a field a consumer needs that nobody wrote. The step compiles to a loud runtime `throw` rather than guessing a locator, which is the #690 failure mode (a locator no page has, failing far from its cause) | Add the missing field to the entry in selectors.yaml — for pagination: `pagination:` with `next:`/`prev:` locators. This is a selectors.yaml-only fix, allowed inside the run-test auto-fix loop |
+| `SG-W018` | A selectors.yaml entry declares an **`nth:` outside the contract** — `nth: -2`, `nth: 'last'`, `nth: 1.5`. `nth:` was the one entry field whose VALUE nothing checked (issue #720), so the web adapter silently DROPPED the filter (identical to deleting the line — the step then hits `strict mode violation: resolved to N elements`, which names the DOM and never the YAML line) while the mobile adapter emitted `$$('~x')[-1]` / `[last]` — `undefined` indexing and a bare identifier. The value is now ignored and reported once per entry | Write an integer `>= 0` for a zero-based index, or `-1` for the last match (`.last()` on web, `.at(-1)` on mobile). There is no keyword form: `'last'` is a string, not an index. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
 | `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-W028` | A trailing **scope clause was DROPPED**, so the step runs against more of the page than its sentence names. Two causes, one code: (1) the word after `in [X]` is not a container type — `in [Job Card] widget`, or a leaf element used as a parent — so the clause matched nothing and the first-`[ref]`/first-`{{data}}` extractors took only the head of the sentence; (2) the by-content form `in [X] <type> with {{v}}` on the **mobile** adapter, where a parent is chained with `$()` and has no content filter. Before this code, both compiled clean and silently widened the assertion to the WHOLE screen — in a list of look-alike cards the test then passes for the wrong reason, findable only by diffing the generated `.spec.ts` against the Gherkin (#667) | For (1) use a real container type: `table` `list` `list-item` `section` `dialog` `modal` `drawer` `overlay` `form` `card` `item` `row` `group` `panel` `region` `container` `tab` `menu`. For (2) give the container an accessibility-id that identifies it and scope by that, or assert on the element the value belongs to |
+| `SG-W029` | A **mobile feature with no usable app-package `Path:`** — the line is missing, or it holds a web-style route (`Path: /applied-jobs`). The compiler then cannot name the app to reset between scenarios, and before this code that was SILENT: the per-scenario `beforeEach` was not emitted at all, so Background fell to Mocha's `before()` — once per FILE. Every scenario shared one continuous app session, so a tab switch or a scroll in one stranded elements off-screen for every later one, and the `@reset:` tier ladder was dropped with it, leaving the tag inert (#669). The spec now always emits the reset machinery and resolves the app id from the session capability instead, throwing a named error at run time if nothing supplies one | Add the package to the feature: `Path: com.example.app/.MainActivity`, or `Path: <androidPkg>/<activity> | <iosBundleId>` for a dual-id feature. A `Path:` starting with `/` is a web route and will not be read as a package. Failing that, set `APP_PACKAGE` (Android) / `IOS_BUNDLE_ID` (iOS) so `wdio.conf` puts the id on the session |
 | `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 |
+| `SG-E025` | A feature tagged `@platform:ios` uses a step the Appium adapter does **not** serve on iOS — the template either throws deep inside a device run (`set-connectivity`, `location-services`, `open-notifications`) or silently does nothing (`hide-keyboard`, a guarded `if (!driver.isIOS …)`). Derived from the template body via the per-OS axis of the step-support matrix, so it cannot disagree with the adapter. Only an explicit `@platform:ios` is gated (`@platform:mobile` picks its OS at run time). Compiles to a loud `throw` | Use a step the matrix marks ✅ for iOS (see `docs/spec/step-support-matrix.md`), tag the feature `@platform:mobile` if it should run on either OS, or tag the scenario `@manual` |
+| `SG-E026` | A **click step names a position** (`at position "top-left"`, `at offset x=…, y=…`) that would not be honoured: the keyword is misspelt or unquoted, a value is outside the grammar (not a number, negative, above 100%, a missing axis, an unknown preset), text follows the position, or another click form claimed the step first (`try to click`, a `with {{v}}` text filter, `… and accept [OK] alert`, `double click`). Each of those would compile to a click on the element's CENTRE and pass — for a backdrop-dismiss overlay that is the one outcome that proves nothing — so the step compiles to a loud `throw` | Write `click [X] <type> at position "top-left\|top-right\|bottom-left\|bottom-right"` or `… at offset x=<n>px\|%, y=<n>px\|%` as the LAST thing in the step, on a plain `click` (no `try to`, no `with {{v}}`, no alert clause). Web only — on mobile tap the control the position targets |
+| `SG-E027` | A selectors.yaml entry declares a **`type:` that is not a selector type** — `type: 'testId'` (capital I), `'xpth'`, `'rol'`, `'test-id'`. YAML is untyped at run time, so this used to compile clean and resolve through the strategy switch's `default:` as `getByPlaceholder('<the value>')`: a locator that cannot match, surfacing much later as a timeout naming placeholder text nobody wrote. Reported once per entry, naming the entry key and the nearest valid spelling; every step using that entry now compiles to a `throw` | Fix the spelling in selectors.yaml. Valid types: `placeholder`, `role`, `testid`, `label`, `text`, `locator`, `id`, `upload`, `page`, `column`, `frame`, `table`, and the mobile strategies `accessibility-id`, `xpath`, `android-uiautomator`, `ios-predicate`, `css`. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
+| `SG-W030` | A selectors.yaml **`expanded.class`/`expanded.attribute`** value carries a character a class or attribute name cannot — whitespace, a quote, a backslash, `$`, `{`, `}`. The value is pasted into the generated spec (string literal, regex, `classList` argument) and selectors.yaml is often generated from the page under test, so it is refused and the field dropped: the step falls back to driving and asserting `aria-expanded`. Reported once per entry and field. The checked/selected signal is refused outright instead of warned about, because dropping it leaves the step with no state to read at all | Use the plain class or attribute name (Tailwind arbitrary values such as `bg-[#eff6ff]` or `!mt-0` are accepted); never paste a selector fragment or quoted text into the field |
+| `SG-E031` | A selectors.yaml **`checked:`/`selected:` declaration the compiler refuses**: the two spellings disagree (`checked.class` and `selected.class` with different values), a class token or attribute name carries whitespace / a quote / a backslash, or one entry declares both a `class` and an `attribute`. Every one of them is silent at run time — the generated matcher tests a single token, so the step would simply time out blaming your component — and an entry declaring two signals lets an action drive one while the assertion after it reads the other. Refused, not dropped: with no signal the step is back on the *"has no on/off state to set"* failure the declaration exists to remove | Declare ONE spelling and ONE of `class` / `attribute`, as a single plain token: `checked: { class: 'is-checked' }`, `selected: { class: 'border-link' }`, or `checked: { attribute: 'data-checked' }`. This is a selectors.yaml-only fix, allowed inside the run-test auto-fix loop |
 
-A diagnostic never changes generation's own exit code — `sungen generate --strict` turns any collected diagnostic into a non-zero exit for CI gates. They are not all inert, though: **`SG-W001`, `SG-W011`, `SG-E020`, `SG-E021`, `SG-W020`, `SG-E023` and `SG-E024` additionally compile the offending step to a runtime `throw`** — a step that reads as a check and silently checks nothing is worse than one that fails loudly. Generation always COMPLETES: the rest of the scenario and the rest of the file still compile. `SG-E022` is the odd one out — it blames the compiler, not your `.feature`, and throws nothing (the file is written so you can inspect it).
+A diagnostic never changes generation's own exit code — `sungen generate --strict` turns any collected diagnostic into a non-zero exit for CI gates. They are not all inert, though: **`SG-W001`, `SG-W011`, `SG-E020`, `SG-E021`, `SG-W020`, `SG-E023`, `SG-E024`, `SG-E025`, `SG-E026` and `SG-E027` additionally compile the offending step to a runtime `throw`, and `SG-E031` refuses the whole file** — a step that reads as a check and silently checks nothing is worse than one that fails loudly. Generation always COMPLETES: the rest of the scenario and the rest of the file still compile. `SG-E022` is the odd one out — it blames the compiler, not your `.feature`, and throws nothing (the file is written so you can inspect it).
 
 ### Runtime error → `Test data "<key>" references ${QA_*} but the environment variable is not set`
 
@@ -202,6 +215,52 @@ 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 |
+| `[sungen] "switch to X frame" — no WEBVIEW/CHROMIUM context appeared within …ms` | `mobile-webview-context-absent` | 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.