@sun-asterisk/sungen 3.2.29 → 3.2.30

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/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-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,10 +100,12 @@ 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`** 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) |
@@ -110,11 +114,18 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | `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`
 
@@ -230,6 +241,7 @@ either direction.
 | `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) |

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

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

package/src/orchestrator/templates/ai-src/skills/sungen-selector-fix/SKILL.md

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

package/src/orchestrator/templates/ai-src/skills/sungen-selector-keys/SKILL.md

@@ -219,7 +219,7 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 | `[X] button` | `getByRole('button', { name: 'X' })` | Button's accessible name = X |
 | `[X] link` | `getByRole('link', { name: 'X' })` | Link text = X |
 | `[X] heading` / `header` | `getByRole('heading', { name: 'X' })` | Heading text = X |
-| `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` | Checkbox label = X |
+| `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` | Checkbox label = X — a checkbox-LIKE tile with no `role`/`aria-checked` needs an explicit entry plus `checked: { class: <cls> }` or `checked: { attribute: <attr> }` (read on the located element itself; `expanded.class` reads a descendant) |
 | `[X] radio` | `getByRole('radio', { name: 'X' })` | Radio label = X |
 | `[X] field` | `getByPlaceholder('X')` | Placeholder text = X AND field has a placeholder |
 | `[X] text` / `message` / `label` | `getByText('X')` | Visible text = X (partial match) |
@@ -231,7 +231,7 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 | `[X] tab` | `getByRole('tab', { name: 'X' })` | Tab text = X |
 | `[X] table` | `getByRole('table', { name: 'X' })` | Table aria-label = X |
 | `[X] list` | `getByRole('list', { name: 'X' })` | List aria-label = X |
-| `[X] column` | `getByRole('columnheader', { name: 'X' })` | Column header text = X |
+| `[X] column` | `getByRole('columnheader', { name: 'X' })` | Column header text = X — **overridable**, see the column-header note below |
 | `[X] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'X' })` | Dialog aria-label/heading = X |
 | `[X] dropdown` / `select` | `getByRole('combobox', { name: 'X' })` | Combobox label = X |
 | `[X] menuitem` | `getByRole('menuitem', { name: 'X' })` | Menu item text = X |
@@ -244,6 +244,8 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 | `[X] breadcrumb` | `getByRole('navigation', { name: 'X' })` | Navigation aria-label = X |
 | `[X] badge` / `tooltip` / `tag` | `getByText('X')` | Visible text = X |
 
+**Column headers: the `[Reference]` is not required to be the DOM text.** `[X] column` defaults its accessible name to the reference, which is unmatchable when the page is not in the reference's language (a `[Category]` column whose header reads 記事分類). Declare the real header instead of renaming the reference — the reference is what ships in the delivered test case. Most specific first: the table entry's `columns.<col>.header`, then a `<col>--columnheader` entry's `name:`, then the reference text. A `header` may hold `{{variables}}` for per-locale text, like any `name:`. A same-named entry that is NOT a column header is ignored and cannot hijack the lookup.
+
 **Special note on the list members `[X] item` / `[X] option` / `[X] cell`** — the only rows above that behave differently per platform:
 
 - **Web**: they infer the role with **no `name`**, on purpose. A list member takes its accessible name from its own CONTENT, so a name defaulted from the `[Reference]` text matches zero elements — and `toBeHidden()` PASSES on an empty locator, so the scenario would go green having proved nothing. The role alone is the whole locator; `nth` or a count assertion narrows it. An explicit `name:` you write yourself is always honoured.
@@ -255,6 +257,11 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 
 **Only add a YAML entry when** auto-infer cannot work: DOM name differs from Gherkin label, need `testid`, need `nth`, need `exact: true`, need `name: null`, or the field type requires explicit config.
 
+**`nth:` takes an integer `>= -1`** — `0`, `1`, `2`… are zero-based indexes and `-1` is the LAST
+match (`.last()` on web, `.at(-1)` on mobile). Nothing else is an index: `nth: -2`, `nth: 'last'`
+and `nth: 1.5` are ignored, the selector stops filtering by position, and the compiler reports
+`SG-W018`. Reach for `nth` only when `exact: true` or `scope` cannot disambiguate.
+
 ### `name: null` — name-from-content roles (toast, alert, spinner)
 
 For a `type: role` entry **without** `name:`, the compiler defaults the accessible-name filter to the Gherkin `[Reference]` text. That is right for buttons/links — and **always wrong** for roles whose accessible name derives from their CONTENT (`status`, `alert`, `log`, `marquee`, `timer`): a toast's name is its message text, never the string "Success Toast". The compiler warns (`SG-W003`). Opt out explicitly:

package/src/orchestrator/templates/ai-src/skills/sungen-tc-review/SKILL.md

@@ -97,7 +97,7 @@ Hard-fail gate. Any ✗ is a syntax error — must be fixed; do not score furthe
 
 - [ ] Selector keys: lowercase, keep Unicode, use **spaces** (no underscores/dots); same label → `--type`/`--N` suffix; names >30 chars → shorten to 1–3 words
 - [ ] Types requiring explicit YAML: `date-picker`, `uploader`, `overlay`, `frame`, `step`
-- [ ] Every `{{var}}` in `.feature` exists in `test-data.yaml`; NO orphan keys
+- [ ] Every `{{var}}` in `.feature` exists in `test-data.yaml`, and every test-data key is bound by some scenario. Both directions are checked by the advisory **data-driven lint** printed at the end of `sungen generate` (warn, never blocking; it is NOT an `audit` finding): **forward** — `{{x}} is not a test-data key and nothing binds it at run time` (the compiler does not fail; the step compiles to the literal text `'${x}'` and runs green having tested nothing, so treat this warning as a defect); **reverse** — `test-data key "x" is defined but never referenced` (dead data). Not counted as unbound/orphan: `{{$…}}` dynamic vars, runtime-bound vars (`remember … as {{v}}`, the scenario's own `@api:`/`@query:` names, a `@beforeAll` hook's `@api:`/`@query:` bindings, a `@steps:` base's captures for its `@extend`ers, and a `@query`/`@api` param bound by name with no override), `@cases` dataset columns, `_*` factory metadata keys, `{{var}}` used in `selectors.yaml` (i18n names) or `mock/mocks.yaml` (mock bodies), and `{{var}}` inside a `@manual` scenario's `# Tester verifies:` comments
 - [ ] Dynamic vars (`{{$timestamp}}`/`{{$uuid}}`/`{{$random:a:b}}`) used correctly for run-unique data (CRUD)
 - [ ] `locator` (CSS) only as a last resort
 
@@ -291,7 +291,7 @@ Do NOT deduct points when a `.feature` lacks the following viewpoints (Playwrigh
 1. ID unique + correct format `VP-<CAT>-<NNN>`?
 2. Title understandable immediately, no context needed?
 3. Every step uses the right keyword (`Given`=is on / `When`=action / `Then`=see)?
-4. Every `{{var}}` exists in `test-data.yaml`?
+4. Every `{{var}}` exists in `test-data.yaml`, and every test-data key is bound by some scenario? (`sungen generate` ends with a data-driven lint warning for either direction — an unbound `{{x}}` compiles to the literal placeholder, it does not fail)
 5. At least one happy path?
 6. Negative cases for invalid classes (EP)?
 7. Boundary covers the 4 points (`min-1/min/max/max+1`)?
@@ -318,7 +318,7 @@ Do NOT deduct points when a `.feature` lacks the following viewpoints (Playwrigh
 9. **Missing negative path** → map invalid classes, add scenarios.
 10. **All `@high`** → reset by user impact per the `sungen-gherkin-syntax` priority table (auth/CRUD/security/required → `@high`; format/standard-range boundary/search → `@normal`; cosmetic → `@low`).
 11. **`@manual` without reason** → add a technical reason comment explaining why automation is not possible.
-12. **Orphan var in test-data** → delete or reconnect.
+12. **Orphan key in test-data** (the advisory lint after `sungen generate` says `defined but never referenced`; a `@query`/`@api` param bound by name, a `@manual` comment ref or a `_*` metadata key is not one) → delete it or bind it into a scenario. **Unbound `{{x}}` in a step** (the same lint says `is not a test-data key and nothing binds it`) → add the key or fix the ref — left alone it runs as the literal text `${x}`.
 13. **Unnecessary CSS/locator selector** → switch to role+name/label/text; keys use spaces.
 14. **Scope crammed into `Background`** → split into `@steps`/`@extend`.
 15. **Mixed auth groups missing `@parallel`** → add `@parallel`.
@@ -361,7 +361,7 @@ If `selectors/<name>.yaml` exists, count lines matching `@needs-live-verify` (pr
 - [ ] Keyword→Action correct
 - [ ] Action→Type correct; click-rule correct
 - [ ] Assertions follow the 8 patterns, no redundant `is visible`
-- [ ] Every {{var}} exists in test-data.yaml; no orphan keys
+- [ ] Every {{var}} exists in test-data.yaml and no orphan keys — both reported by the advisory data-driven lint at `sungen generate` (not `audit`); an unbound {{var}} compiles to a literal placeholder, never a compile error
 - [ ] Selector keys follow sungen-selector-keys; locator only as last resort
 - [ ] Tags valid; @parallel when mixing auth groups
 - Syntax errors found: <n>

package/src/orchestrator/templates/playwright.config.ts

@@ -84,9 +84,16 @@ export default defineConfig({
   /* Output file path is controlled by PLAYWRIGHT_JSON_OUTPUT_NAME env var for per-screen isolation. */
   /* When SUNGEN_ENV is set, the env name is inserted before `.json` so locale */
   /* runs don't overwrite each other (e.g. `<name>-test-result.vi.json`). */
+  /* The sanitize reporter rewrites the JSON report's absolute machine paths to project-relative ones on
+     exit — the file is committed next to the spec, so a username or machine layout must not ship in it.
+     Registered only while its file exists (`sungen init`/`generate`/`update` write it): a cleaned
+     specs/generated must not stop Playwright from loading this config. */
   reporter: [
     ['html'],
     ['json', { outputFile: resolveJsonOutputFile() }],
+    ...(fs.existsSync(path.join(__dirname, 'specs', 'generated', 'report-path-sanitize-reporter.ts'))
+      ? [['./specs/generated/report-path-sanitize-reporter.ts'] as [string]]
+      : []),
   ],
   /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
   use: {