@sun-asterisk/sungen 3.2.8 → 3.2.10-beta.1

package/src/orchestrator/templates/ai-src/config/claude.md

@@ -18,14 +18,16 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-delivery` | Export Gherkin + Playwright results → CSV test case deliverable |
 | `sungen-capture` | Acquire visual/design context — one skill, 4 modes: figma-mcp (Dev Mode MCP), figma-pat (URL → spec_figma.md), live (Playwright MCP scan), local (images in `requirements/ui/`) |
 | `sungen-locale` | Bootstrap i18n — audit selectors, detect locale switch mechanism, generate test-data overlay |
+| `sungen-data-factory` | Standardized test-data — field-type/security catalog, 4-source method, `.overwrite`, blind-spot prompts |
 
-## Workflow (7 AI commands)
+## Workflow (8 AI commands)
 
 | Command | What it does |
 |---|---|
 | `/sungen:add-screen <name> <path>` | Scaffold `qa/screens/<name>/` directories |
 | `/sungen:add-flow <name> [--path <url>]` | Scaffold `qa/flows/<name>/` directories for E2E cross-screen testing |
 | `/sungen:create-test <name>` | Generate `.feature` + `test-data.yaml` (auto-detects screen or flow) |
+| `/sungen:create-data-test <name>` | Generate standardized test-data (valid/boundary/invalid + CHK trace) from the Data Factory catalog; no name = all units (asks to confirm) |
 | `/sungen:review <name>` | Score syntax, coverage, viewpoint quality (auto-detects screen or flow) |
 | `/sungen:run-test <name>` | Generate `selectors.yaml`, compile, run, auto-fix (auto-detects screen or flow) |
 | `/sungen:delivery [name...]` | Export test cases → CSV for QA delivery (all screens if no arg) |

package/src/orchestrator/templates/ai-src/config/copilot.md

@@ -18,14 +18,16 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-delivery` | Export Gherkin + Playwright results → CSV test case deliverable |
 | `sungen-capture` | Acquire visual/design context — one skill, 4 modes: figma-mcp (Dev Mode MCP), figma-pat (URL → spec_figma.md), live (Playwright MCP scan), local (images in `requirements/ui/`) |
 | `sungen-locale` | Bootstrap i18n — audit selectors, detect locale switch mechanism, generate test-data overlay |
+| `sungen-data-factory` | Standardized test-data — field-type/security catalog, 4-source method, `.overwrite`, blind-spot prompts |
 
-## Workflow (7 AI commands)
+## Workflow (8 AI commands)
 
 | Command | What it does |
 |---|---|
 | `/sungen-add-screen <name> <path>` | Scaffold `qa/screens/<name>/` directories |
 | `/sungen-add-flow <name> [--path <url>]` | Scaffold `qa/flows/<name>/` directories for E2E cross-screen testing |
 | `/sungen-create-test <name>` | Generate `.feature` + `test-data.yaml` (auto-detects screen or flow) |
+| `/sungen-create-data-test <name>` | Generate standardized test-data (valid/boundary/invalid + CHK trace) from the Data Factory catalog; no name = all units (asks to confirm) |
 | `/sungen-review <name>` | Score syntax, coverage, viewpoint quality (auto-detects screen or flow) |
 | `/sungen-run-test <name>` | Generate `selectors.yaml`, compile, run, auto-fix (auto-detects screen or flow) |
 | `/sungen-delivery [name...]` | Export test cases → CSV for QA delivery (all screens if no arg) |

package/src/orchestrator/templates/ai-src/skills/sungen-data-factory/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: sungen-data-factory
+description: 'Use when create-data-test (or create-test) needs standardized TEST DATA — valid/boundary/invalid values for input fields with CHK-* traceability. Drives the Data Factory catalog + the 4-source method. Invoke after reading spec.md, when authoring the field-map or filling test-data.'
+user-invocable: false
+---
+
+## What this skill does
+
+Turn a screen/flow's fields into **standardized test data** — not guessed values. You author a
+**field-map**; the deterministic `sungen data gen` expands it from the Data Factory **catalog**
+(field-type + security + technique library) into valid / boundary / invalid values, each carrying a
+`CHK-*` id that traces to the spec. Your judgment goes into *reading the spec correctly* and
+*answering blind spots* — never into inventing values the catalog or the QA should own.
+
+Requires the `data-factory` capability. If `qa/capabilities.yaml` lacks it, run
+`sungen capability add data-factory` (runtime-free — safe to enable).
+
+## The 4-source method (phuong-phap-tao-test-data.md)
+
+Never invent values from memory. Cross-reference four sources — each covers the previous one's gap:
+
+1. **Spec validate rules** — required, format, min/max, business rules, and the **error/message code**
+   per rule. Defines the legal/illegal boundary. (Says the *law*, not every way to *break* it.)
+2. **Field-type catalog** — the accumulated "how this type breaks" knowledge (email/password/phone/
+   number/…). This is the Data Factory `common/` — it fills the "spec doesn't list every break" gap.
+3. **Design technique** — Boundary Value Analysis / Equivalence Partitioning / Decision Table / State
+   Transition — reduces the rule + candidates to a *minimal-but-sufficient* representative set.
+4. **DB mapping** — unique constraints, cross-entity dependency, real backend limits → precondition
+   data, not just a single input value.
+
+Then classify every value into **Valid / Boundary / Invalid** (each invalid tagged with its error
+code) and give it a `CHK-*` id for traceability.
+
+## The field-map — `qa/data-factory/<name>.fields.yaml`
+
+Your main artifact. One entry per input field; the generator expands it:
+
+```yaml
+screen: login                 # or  flow: <name>
+fields:
+  - name: email
+    type: email               # a catalog field-type (see list below)
+    required: true
+    constraints: { maxLocal: 64, maxTotal: 254 }   # the project's REAL limits from spec
+    errorMap: { M13: E1042, M02: E1001 }            # catalog placeholder code → project's real code
+  - name: password
+    type: password
+    constraints: { minLength: 8, maxLength: 32 }
+```
+
+**Catalog field-types** (P1): `email` · `password` · `phone` · `string` · `number-integer` ·
+`number-float` · `currency` · `postcode` · `katakana` (JP). Security payload banks auto-append to a
+field's invalid group via the type's `uses_security` (`sqli`, `xss`, `idor`, `broken-auth`, `upload`,
+`input-validation`).
+
+Rules:
+- Pick the closest `type`; put the project's real numbers in `constraints` (they override the
+  catalog defaults).
+- Map every `errorRef` placeholder (`M13`, `M39`, …) to the spec's real code via `errorMap`. Leave
+  one unmapped **only** if the spec has none — the lint flags it as an open point to confirm.
+
+## Blind spots — ask, never fabricate
+
+If a field's type is **not** in the catalog — a business enum, a cross-entity constraint, a
+project-specific data model — do **not** guess. Ask the QA (via `AskUserQuestion`) for: (1) the valid
+set, (2) invalid / non-existent values, (3) the error code when wrong, (4) dependencies on other
+fields. Record it in `qa/data-factory/project/<entity>.yaml` so it becomes reusable project catalog.
+This is the core discipline: *common is never enough; when blind, think and ask — don't invent.*
+
+## Customizing the catalog — `.overwrite` (survives `sungen update`)
+
+The shipped `common/` is a floor. Project rules go in `qa/data-factory/common.overwrite.yaml`,
+deep-merged over the common (**later-wins**, keyed by `type` + data-point `id`): same `id` replaces,
+new `id` appends, `constraints` merge key-by-key. `sungen update` refreshes `common/` but never
+touches your overlay. If an update makes an overlay entry stale (references a bank/constraint that no
+longer exists), the loader **warns you to prune it** — it never edits your file. Prefer a targeted
+`errorMap`/`constraints` in the field-map for per-screen tweaks; use `.overwrite` only for rules that
+apply project-wide.
+
+## Verify before done — the phuong-phap §6 checklist
+
+Run `sungen data lint` and clear it: every required field has **≥1 valid**, **boundary present**
+(exact min/max, not only over-boundary) for bounded types, **≥1 invalid per rule** (not one generic
+"wrong" value for many rules), no `UNRESOLVED` values, error codes mapped or explicitly left open.
+Then `sungen data gen` writes the standardized `test-data/<name>.yaml`. Do not hand-edit the
+generated values — change the field-map or `.overwrite` and re-run (determinism: same input → same
+data).
+
+## Weaving into scenarios
+
+When a `.feature` exists, express invalid/boundary sets as data-driven `Scenario Outline` + `Examples`
+(`@cases`) referencing the values — see `sungen-gherkin-syntax`. This keeps one logic + many values
+instead of copy-pasted scenarios, and each row carries its `CHK-*` id for traceability.

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

@@ -78,9 +78,20 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | strict mode violation | Multiple elements match | Add `nth: 0`, `exact: true`, or more specific `name` |
 | Timeout / not found | Element doesn't exist or name wrong | Re-snapshot → copy exact accessible name. Check iframe/dialog scope |
 | 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 `variant: 'custom'` |
+| 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 |
 
+### Compile diagnostics (`sungen generate` output) → fix BEFORE running
+
+| Code | Meaning | Fix |
+|---|---|---|
+| `SG-W001` | Step matched no pattern — compiled to a no-op `// TODO` (the test runs weaker than it reads) | Rephrase to a documented pattern (`sungen-gherkin-syntax`) or tag `@manual` with a reason |
+| `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-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 |
+
 ### Assertion errors → apply the Source-of-truth gate above FIRST
 
 > The "Fix" column below applies **only when the expected value was wrong relative to `spec.md`** (a test defect). If the app's value contradicts the spec, the row is a **candidate bug → report it, do not edit the expected to match live**. Never weaken `toHaveText`→`toContainText` just to pass.

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

@@ -50,16 +50,41 @@ User expand | collapse [T] row
 ### Alert / Keyboard / Wait / Scroll
 
 ```
-User click [OK | Cancel] alert
+User click [T] button and accept [OK] alert       # PREFERRED (v3.3): natural order,
+User click [T] button and dismiss [Cancel] alert  # compiler registers the listener first
+User click [OK | Cancel] alert                    # two-step form: must come BEFORE the trigger
 User fill [T] alert with {{v}}
 User see [message text] alert
 User press Escape key | Enter on [T] field
-User wait for N seconds | [T] dialog | [T] dialog is STATE | [T] page
+User wait for N seconds | [T] page
+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
 ```
 
-> Alert steps must appear BEFORE the action that triggers the dialog.
+> **Browser alerts (native `window.confirm/alert/prompt` only):** prefer the compound form —
+> it reads in the user's real order and declares the trigger↔dialog causality in one step.
+> The two-step form stays valid but the alert step must appear BEFORE the triggering action
+> (a late `page.once('dialog')` lets the dialog auto-dismiss silently — compile warning
+> `SG-W007`). Custom confirm MODALS (ARIA dialogs — most modern apps) are ordinary buttons:
+> write normal click steps, no alert step at all.
+> State-based waits (`is hidden`, `with {{v}}`, `table to refresh`) are legitimate; time-based
+> `wait for N seconds` stays a last resort. `table to refresh` watches the app's loading
+> indicator (`qa/app.yaml` `feedback.loading.indicator`, default `[aria-busy="true"]`).
+
+### Positional table rows (v3.3)
+
+```
+User remember [Col] column in [T] table row {{n}} as {{var}}   # read a cell by POSITION
+User click [Act] button in [T] table row {{n}}                 # act on the SAME row
+User click [Act] button in [T] table row 2                     # literal row number
+```
+
+Row numbers are 1-based data rows (header not counted; override via `qa/app.yaml`
+`conventions.table`). Use positional rows when you must READ then ACT on the same row —
+two content-filtered queries can hit different rows if the table re-renders in between.
 
 ### Assertions (8 patterns → determines Playwright assertion)
 
@@ -118,6 +143,44 @@ Scenario: ...
 
 Path access on a bound result: `{{q.count}}`/`{{q.length}}`, `{{q.first.col}}`, `{{q.last.col}}`, `{{q[2].col}}`, `{{q.col}}` (= first row's col). `expect A is B` also supports `is at least` / `is at most` / `is not`. Tier-2 declarative (trivial inline, no catalog): `User see [<table>] row where [<col>] is {{v}} [has [<col2>] = "x"]`, `… no row where …`, `… count is {{n}}`. Full grammar + catalog/datasource/secret rules → **Advanced → Database** doc. Only emit DB steps when the project has a `database/` catalog / `datasources.yaml`.
 
+### NoSQL engines (Cosmos, MongoDB, DynamoDB) — natively supported
+
+Beyond the three SQL engines, the Data Driver has native NoSQL engines. Declarative steps (`User see [table] row where …`, `… no row …`, `… count is …`) work across ALL of them; only the raw `@query` catalog shape differs per engine:
+
+- **`engine: cosmos`** (Azure Cosmos DB, NoSQL API) — SQL dialect. Author `sql:` catalog entries against the mandatory `c` alias (`SELECT * FROM c WHERE c.<field> = :p`); named params bind automatically. Config: `endpoint`+`key` (or a connection-string `url`), `database`, `container` (default when no `[table]`). Read-only by construction (the query API can't mutate).
+- **`engine: mongodb`** — no SQL. Author a `find:` (`{collection, filter, projection?, sort?, limit?}`) or `pipeline:` (`{collection, stages: […]}`) catalog entry; `:param` placeholders bind at runtime. `$out`/`$merge`/`$where`/`$function`/`$accumulator`/`mapReduce` are refused. Config: a `mongodb://` `url`. Read-only = a server-side read role.
+- **`engine: dynamodb`** — raw `@query` is PartiQL SELECT (`sql: SELECT … FROM "table" WHERE pk = :p`). Declarative steps route GetItem/Query only for partition-/sort-key filters via a `keySchema:` registry; a **non-key filter is refused** (use a raw PartiQL SELECT — never a full-table Scan). Config: `region` + `keySchema` (credentials from the AWS env chain). Read-only = IAM `PartiQLSelect`-only.
+
+Full config + catalog examples → **Advanced → Database** doc.
+
+### Unsupported DB engine — fallback (ask, don't improvise)
+
+Direct SQL verification (`@query`, the Data Driver) covers these SQL engines: **`{postgres, sqlite, mysql}`** — plus the three native NoSQL engines above (Cosmos, MongoDB, DynamoDB). When a datasource's `engine` (or the DB the user describes) is **outside all of those** — e.g. Cassandra, Oracle, Neo4j, a proprietary store:
+
+1. **Do not** attempt a direct connect. **Do not** improvise a verification method.
+2. Present a fixed `AskUserQuestion` with exactly these 3 branches (always these, no others invented):
+   - **@api** — verify state via the project's internal API (route to the API driver).
+   - **@manual** — emit a `@manual` step + manual-check guidance (e.g. the vendor console / CLI — `cqlsh` for Cassandra, `cypher-shell` for Neo4j).
+   - **Proxy / read-replica SQL** — if the user can supply a SQL-compatible endpoint (including Azure Cosmos DB **for PostgreSQL** / Citus), treat it as `engine: postgres` (or `mysql`) and use the normal Data Driver path above.
+3. **Recommend, don't decide.** Check the project for signals and put the best-fit branch **first**, tagged **"(Recommended)"** with a one-line reason:
+   - a project API driver / `qa/api/` catalog / `PEERCONNE_URL`-style internal API exists → **@api** first;
+   - else the user hints at a SQL-compatible replica/proxy → **proxy-SQL** first;
+   - else → **@manual** first.
+   The other two branches plus an **"Other"** option (user describes their own approach) stay available.
+4. **The user always overrides** — they may pick any branch or "Other" regardless of the recommendation.
+5. **Never auto-run** a branch and never silently pick one on the user's behalf — the question must always be asked.
+
+Example:
+```
+AskUserQuestion:
+  question: "This datasource's engine (cassandra) isn't a supported Data Driver engine ({postgres, sqlite, mysql} + Cosmos/MongoDB/DynamoDB) — direct connect isn't supported. How should DB state be verified?"
+  options:
+    - "@api — verify via the project's internal API (Recommended: qa/api/ catalog found)"
+    - "@manual — emit a @manual step + cqlsh check"
+    - "Proxy / read-replica SQL — supply a SQL-compatible endpoint → engine: postgres"
+    - "Other — describe your own verification approach"
+```
+
 ### API response assertions (optional API Driver)
 
 An `@api:<name>` call binds the response to `{{name}}` = `{ status, ok, body, headers }` (+ `ok_count`/`status_counts` under `@concurrent`). Assert with the same `expect A is B` grammar + path access:

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

@@ -83,6 +83,13 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
    - If any mismatch → write an explicit YAML entry using the real DOM name. Do not leave a mismatch to be caught at runtime.
    - **Typical mismatch cases**: Gherkin uses English label (`[Submit]`) but app displays Vietnamese (`"Gửi"`); placeholder is descriptive (`"Nhập email của bạn"`) not a bare field name (`"Email"`); button text includes an icon glyph before/after the word.
 7. **Substring ambiguity check**: for each `role` + `name` selector, check if any other element in the snapshot has a name that **contains** this name as a substring (e.g., `"Đăng ký"` vs `"Đăng ký bằng Google"`). If yes → add `exact: true` to prevent strict mode violation at runtime.
+7b. **Widget & profile fingerprinting** (App Profile, v3.3): while the snapshot is open, identify the UI library and non-standard widget behavior, and record it so the compiler stops guessing:
+   - **Fingerprints** (check DOM classes/attributes): `.ant-select`/`.ant-picker` → antd · `[data-radix-*]` / shadcn portals → radix · `.MuiSelect-*`/`.MuiPickersDay` → MUI · `.select2-container` → select2 · plain `<select>` → native.
+   - **Project-wide** conclusion (the whole app uses one library) → write/update `qa/app.yaml`: `extends: radix|antd|native`. **Element-level** outlier (one widget differs from the rest) → set `variant:` on that selector entry only (e.g. `variant: native`, `variant: antd-select`).
+   - Custom widget nobody's preset covers (in-house datepicker etc.) → author a recipe in `qa/app.yaml` `recipes:` (closed primitives: click/type/press/waitFor/clickText/expectText/expectValue/forEach) and bind it per element with `variant: <recipe-name>`.
+   - 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.
 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 assertion compiles to `toHaveURL(/button/)`. 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.
@@ -301,6 +308,18 @@ Only when `test-results/` screenshots are insufficient:
 
 Never use `browser_evaluate` to inject or read cookies (misses httpOnly). For auth, use Phase 0.5 or `sungen makeauth`.
 
+### Step 2b: Selector sanity probe — suspect the compiler/profile BEFORE the app
+
+For every failing locator, while the live page is in the failing state, count matches before attributing the failure to server load, timing, or flakiness:
+
+1. **Probe the exact generated locator** (copy it from the `.spec.ts`): count = 0 while the element is clearly on screen → the locator is wrong, not the app.
+2. **Peel one constraint at a time and re-count**:
+   - drop the `{ name }` filter → now found? → invented/wrong accessible name → fix `name:` or set `name: null` (name-from-content roles; matches compile warning `SG-W003`)
+   - drop the dialog/parent scope → now found? → portal-rendered element → check `qa/app.yaml` `layers.portal_roles` / remove a wrong `scope: 'dialog'`
+   - drop `exact`/text filter → now found? → text mismatch (NBSP, trailing space, i18n) → fix the value or use `{{variable}}`
+3. **Repair at the right altitude**: a per-element mistake → fix that `selectors.yaml` entry; a pattern repeated across elements (every toast, every dropdown) → fix `qa/app.yaml` once (with `detection.evidence`) so every screen inherits the fix. **Never rewrite the `.feature` to dodge a selector problem** — intent stays, identity/behavior get repaired.
+4. Also read the generate output: `SG-W001/W002/W003` diagnostics fired at compile time usually name the broken step before you run anything.
+
 ### Step 3: Fix Broken Selectors
 
 Selector priority (use first applicable):
@@ -367,6 +386,9 @@ Quick reference for the most frequent production failures:
 | `No element found` on `[X] field` | Field has no placeholder, or placeholder ≠ X | Write explicit YAML: `type: label, value: "Actual label"` or `type: placeholder, value: "Actual placeholder"` |
 | `No element found` on `[X] text` / `message` | Visible text differs from Gherkin label, or text is dynamic | Write explicit YAML or use `{{variable}}` for dynamic content |
 | `strict mode violation` | Multiple elements match the same name/text | Add `exact: true` to YAML entry, or add `nth` |
+| `strict mode violation` on `… with {{v}}` clicks (prefix-sharing options: "Văn phòng Hà Nội 1/2/…") | The `{{v}}` filter is a substring match by default | Add `exact: true` — since 3.3 it also anchors the `.filter({ hasText })` of action steps (`/^value$/`), not just role-name matching |
+| Toast/alert/spinner assertion times out but `[role="status"]` exists on the live page (`SG-W003` at generate time) | Entry has no `name:` → compiler defaulted `{ name: '<Gherkin ref>' }`, but status/alert names derive from CONTENT and never equal the reference | Add `name: null` to the entry (match by role only). Do NOT switch to `type: locator` |
+| Option/menu click inside a dialog times out, but the SAME locator works without dialog scope | Portal-rendered layer (Radix/MUI/antd) lives outside the dialog's DOM subtree | Since 3.3 the compiler page-roots portal roles (option/listbox/menu/menuitem/tooltip) automatically; for a listbox genuinely inside the dialog add `scope: 'dialog'` to the entry. Check `qa/app.yaml` `layers.portal_roles` (preset `native` disables the exemption) |
 | `toBeVisible` timeout on dynamic content | Snapshot was taken while page was still loading | Wait for spinner/skeleton to clear before snapshotting; add `browser_wait_for` |
 | All tests fail with page navigate error | Page selector URL wrong or baseURL mismatch | Re-check `playwright.config.ts` `baseURL` and page selector `value` path |
 | Auth redirect on every test | `specs/.auth/<role>.json` missing or expired | Run Phase 0.5 to capture fresh session |

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

@@ -239,7 +239,20 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 
 **Special note on `[X] field`**: `getByPlaceholder('X')` only works when (1) the field has a placeholder attribute AND (2) the placeholder text equals X. For fields without placeholders (floating labels, aria-label), write explicit YAML: `type: label, value: "Actual label text"`.
 
-**Only add a YAML entry when** auto-infer cannot work: DOM name differs from Gherkin label, need `testid`, need `nth`, need `exact: true`, or the field type requires explicit config.
+**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.
+
+### `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:
+
+```yaml
+success toast:
+  type: 'role'
+  value: 'status'
+  name: null        # deliberate: match by role only, no name filter
+```
+
+Use this for every toast/alert/spinner content assertion. Do NOT fall back to `type: locator, value: '[role="status"]'` — `name: null` keeps role semantics.
 
 ### Types requiring YAML entry (no auto-infer)