@sun-asterisk/sungen 3.2.2-beta.9 → 3.2.3-beta.3

package/src/orchestrator/templates/ai-instructions/claude-skill-error-mapping.md

@@ -1,176 +0,0 @@
----
-name: sungen-error-mapping
-description: 'Error diagnosis and fix strategy — systematic debugging flow, error patterns, fix priorities. Auto-loaded during run-test.'
-user-invocable: false
----
-
-## Diagnosis Flow (before fixing anything)
-
-**Step 1: Read the error** — extract: error type, element name, expected vs actual, file:line.
-
-**Step 2: Read error context** — check `test-results/` for the snapshot at failure time. This shows the exact page state when the test failed — more reliable than re-navigating with MCP.
-
-**Step 3: Compare** — match the failing selector against the snapshot. Ask:
-- Does the element exist on the page?
-- Does the accessible name match exactly?
-- Are there multiple matches (strict mode)?
-- Is the element inside an iframe or dialog?
-- Is the page in the expected state (correct URL, loaded)?
-
-Then choose the fix from the patterns below.
-
----
-
-## ⛔ Source of truth — classify EVERY failure before you "fix" it
-
-`.feature` + `test-data.yaml` + `spec.md` are the **oracle**. The **live page is NOT** — it may be the thing that's broken. A failing test is not automatically a test to "make pass". Classify first:
-
-- **Selector-resolution failure** (element not found / wrong locator / strict-mode / wrong element type) → the test looked in the wrong place. **Fix the locator in `selectors.yaml`** (re-snapshot, copy the exact accessible name). Legit auto-fix.
-- **Assertion-value failure** (element FOUND, but observed value ≠ expected) → STOP and ask: *is the TEST wrong, or is the APP wrong?*
-  - Expected value/rule is wrong **relative to `spec.md`** (typo, stale test-data) → fix `test-data.yaml`/`.feature` so it matches the **spec** — never the live page.
-  - App behaviour contradicts `spec.md` (spec says X, app shows Y) → **CANDIDATE BUG**. **Report it** (let the test FAIL / surface to the QA in the run summary). **NEVER** change the expected value, loosen the rule, weaken the assertion (`toHaveText`→`toContainText` to dodge a mismatch), edit `.feature`, or edit the generated `.spec.ts` to make it pass.
-
-> **Cardinal sin (do NOT do this):** a `password > 8 chars` rule fails on a 6-char input → "fix" it to `>= 6` so the test passes. The logic is now meaningless. A failing assertion is a **finding**, not a chore.
-
-**Auto-fix loop scope:** the run-test auto-fix loop engages ONLY on **selector-resolution** failures. On an assertion-value failure where the app contradicts the spec → **HALT and report**, do not loop it into passing.
-
-**Never hand-edit the generated `.spec.ts`** (e.g. inserting `page.evaluate`/`fetch` to bypass a broken control). `sungen script-check` regenerates the spec from `.feature` and flags any edit as DRIFT — regenerate, don't patch.
-
----
-
-## Fix Priority (try in order)
-
-1. **Auth issue** — page redirected to login? Fix auth first, everything else is noise
-2. **Element not found** — wrong name/type/value in selectors.yaml. Re-snapshot, copy exact name
-3. **Multiple matches** — add `nth`, `exact: true`, or `scope` to narrow down
-4. **Wrong assertion** — `toHaveText` vs `toHaveValue` mismatch, wrong expected data
-5. **Timing** — SPA not loaded, async content. Add `wait for` step in .feature
-
----
-
-## Playwright Errors
-
-### Selector errors → fix in `selectors.yaml`
-
-| Error | Diagnosis | Fix |
-|---|---|---|
-| 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'` |
-| Frame not found | iframe selector wrong or doesn't exist | Fix `frame` value, verify iframe in snapshot |
-
-### 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.
-
-| Error | Diagnosis | Fix (only if the TEST was wrong per spec) |
-|---|---|---|
-| toHaveText mismatch | Expected text differs from actual | If the test's expected was wrong per spec → fix value in test-data. If element is input type → change Gherkin type to `field`/`textarea` (triggers `toHaveValue`). If the app value contradicts spec → **report as bug**. |
-| toHaveValue mismatch | Expected value differs from actual | Fix value in test-data |
-| toContainText mismatch | Partial text not found | Fix expected partial text in test-data |
-| toBeVisible timeout | Element exists but hidden, or name wrong | Check: is element conditionally visible? Wrong name? Inside dialog? |
-| toHaveCount mismatch | Row count differs | Fix expected count in test-data. Verify: is table loaded? Filtered? |
-
-### Assertion type rule
-
-Sungen picks assertion based on element type:
-- **Input** (`field`, `textarea`, `search`, `dropdown`, `slider`) → `toHaveValue()`
-- **Text** (everything else: `message`, `heading`, `label`, `row`) → `toHaveText()`
-- **Partial** (`contains` keyword) → `toContainText()`
-
-If `toHaveText` fails on an input → the Gherkin step has wrong target type. Fix: change type in `.feature`.
-
----
-
-## Table-Specific Errors
-
-| Error | Diagnosis | Fix |
-|---|---|---|
-| `tableRow is not defined` | Column assertion without preceding row scope step | Add `User see [Ref] row in [Table] table with {{v}}` before `User see [Col] column with {{v}}` |
-| `toHaveText` on cell fails (with columns) | Wrong column index in `columns` config | Re-count columns in snapshot (0-indexed). Fix `index` in selectors.yaml |
-| `toBeVisible` on cell fails (no columns) | `filter({ hasText })` didn't match | Check exact cell text in snapshot. Fix value in test-data |
-| Row filter matches 0 rows | Filter text doesn't match any row content | Re-snapshot → find actual row text. Fix filter value in test-data |
-| Row filter matches multiple rows | Filter text is too generic (matches multiple rows) | Use more specific filter text (unique identifier like email, ID) |
-| Table not found | Wrong table name or table not rendered | Re-snapshot → copy exact table accessible name |
-
----
-
-## Auth Errors
-
-| Symptom | Fix |
-|---|---|
-| Redirect to login page | Auth expired. Ask user to log in manually via MCP browser |
-| `storageState` file not found | Ask user to log in manually via MCP browser, then save storage state |
-| Most tests timeout on first step | Auth expired — ask user to re-authenticate via MCP browser |
-| Page shows home instead of target | SPA + expired auth. Re-authenticate + add `wait for` step |
-
-**Never use `sungen makeauth`.** Always let the user log in manually via the MCP browser.
-
----
-
-## Sungen Compile Errors
-
-| Error | Fix |
-|---|---|
-| Unknown step pattern | Rewrite step to match `sungen-gherkin-syntax` patterns |
-| Missing selector | Add key to `selectors.yaml` |
-| Missing variable | Add key to `test-data.yaml` |
-| Invalid selector type | Use: role/testid/placeholder/label/text/locator/page/upload/frame |
-
----
-
-## Flow-Specific Errors
-
-| Error | Diagnosis | Fix |
-|---|---|---|
-| Navigation timeout between screens | Cross-screen transition takes too long or URL mismatch | Add explicit `wait for page` step between screen transitions in `.feature`. Verify target URL path |
-| Selector `"screen:element"` not found | Namespace key missing or wrong format | Ensure colon-namespaced key in `selectors.yaml` is **quoted**: `"login:submit":`. Check screen prefix matches `[Screen:Element]` ref in Gherkin |
-| Test data `screen.key` undefined | Phase namespace mismatch | Verify `test-data.yaml` uses dot-namespaced keys: `login.email`, `submission.nominee`. Keys must match `{{screen.key}}` refs in `.feature` |
-| State lost between screens | Auth/session expired during multi-screen flow | Ensure all screens in the flow share the same `@auth:role` tag. Check if the app invalidates sessions on navigation |
-| Duplicate selector key across screens | Two screens use same element name without namespace | Always use `[Screen:Element]` format in flow `.feature`. Selectors must use `"screen:element":` quoted keys |
-
----
-
-## 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.
-
-| Symptom | Root cause | Fix |
-|---|---|---|
-| Server 429 (rate limited) | Too many browser contexts | Fix `contextCache` to reuse sessions per `storageState` |
-| Tests slow with `--workers=1` | Redundant navigation | Fix goto patch: skip if `currentPath === url` |
-| Previous test's modal blocks next | Overlay not cleaned up | Add/improve Escape + backdrop click in cleanup hook |
-| All tests fail on first navigation | `page.url()` is `about:blank` | Add try/catch in goto patch |
-| Flaky timeouts on SPA pages | Default timeout too short for app | Increase `actionTimeout` / `navigationTimeout` |
-| Tests pass individually but fail in batch | Shared state leaking between tests | Isolate context per test or reset state in `beforeEach` |
-
-### What AI CAN fix in `base.ts`
-
-- Timeout tuning (increase for slow APIs, decrease for fast apps)
-- Custom overlay/modal dismiss logic (project has unique close patterns)
-- Navigation wait strategy (`networkidle` vs `domcontentloaded` vs custom)
-- Context caching strategy (per-role, per-session)
-- Cookie/localStorage cleanup between tests
-
-### What AI should NOT move into `base.ts`
-
-- Individual selector fixes → belong in `selectors.yaml`
-- Test data values → belong in `test-data.yaml`
-- Single-test workarounds → belong in the `.spec.ts` directly
-
----
-
-## Smart Fix Strategy
-
-### When multiple tests fail on the same element
-Fix the **root cause once** — don't fix each test individually. Group by selector key, fix selectors.yaml, recompile, re-run batch.
-
-### When you're unsure about the fix
-**Re-snapshot** — `browser_navigate` to the failing page, take `browser_snapshot`, compare the live state against what the test expects. This is faster than guessing.
-
-### When the fix might break other tests
-After fixing selectors.yaml, run ALL tests (not just the failing one) to catch regressions from renamed/changed selectors.
-
-### When nothing works after 3 attempts
-Ask the user. The issue might be: dynamic content, race condition, environment-specific state, or a real application bug.

package/src/orchestrator/templates/ai-instructions/claude-skill-gherkin-syntax.md

@@ -1,446 +0,0 @@
----
-name: sungen-gherkin-syntax
-description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Auto-loaded when writing .feature, selectors.yaml, or test-data.yaml.'
-user-invocable: false
----
-
-## Standard Syntax
-
-```
-[Keyword] User <Action> [Target Name] <Target Type> <in [Parent Name] <Parent Type>> <with {{Value}}> <is State>
-```
-
-- **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.
-
-## Keyword → Action Rules
-
-```
-GIVEN  →  is on
-WHEN   →  click · fill · select · press · clear · check · uncheck · hover
-         [⚠️ wait for — only for Spinner/Modal, minimize usage]
-THEN   →  see
-AND    →  inherits from preceding keyword
-```
-
-## Step Patterns (70 patterns)
-
-### Setup / Form / Interaction
-
-```
-User is on [T] page | page with {{v}} | dialog
-User fill [T] field | textarea | search | slider | date-picker with {{v}}
-User fill [T] uploader with {{f}}
-User clear [T] field
-User check [T] checkbox | toggle | radio
-User uncheck [T] checkbox | toggle
-User select [T] dropdown with {{v}}
-User click [T] button | tab | column | breadcrumb
-User click [T] row with {{v}}
-User double click [T] element
-User hover [T] icon | row
-User drag [T] to [T2]
-User expand | collapse [T] row
-```
-
-**click + with {{Value}} rule**: NO value for static (`button`, `link`, `icon`, `tab`). WITH value only for dynamic lists (`row`, `item`, `card`, `option`).
-
-### Alert / Keyboard / Wait / Scroll
-
-```
-User click [OK | Cancel] alert
-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 scroll to [T] section
-User switch to [T] frame | [main] frame
-```
-
-> Alert steps must appear BEFORE the action that triggers the dialog.
-
-### Assertions (8 patterns → determines Playwright assertion)
-
-```
-# 1. Visibility: User see [T] type (NEVER add "is visible") | is hidden
-# 2. Text (toHaveText): User see [T] message | header | label with {{v}}
-# 3. Partial (toContainText): User see [T] text contains {{v}}
-# 4. Input (toHaveValue): User see [T] field | dropdown | date-picker | search | slider with {{v}}
-# 5. State: User see [T] button is disabled | checkbox is checked | dialog with {{v}} is hidden
-# 6. Attribute (toHaveAttribute): User see [T] image | link with {{v}}
-# 7. Count: User see [T] row with {{count}}
-# 8. Page: User see [T] page
-```
-
-### Collection / all-card (P5)
-
-```
-# Every element's TEXT matches a value (filter correctness, all items belong):
-User see all [Result Product Name] text contains {{category_term}}
-# Every CONTAINER holds a CHILD element (structural per-card proof — prove "each card has X"):
-User see all [Product Card] contain [Product Name]
-User see all [Product Card] contain [Add To Cart] button
-```
-
-Use the all-card form whenever a title claims *every / each* card/row exposes something — a single `User see [Add To Cart] button` does NOT prove "each card" and the harness Claim-Proof gate will flag it.
-
-### Table
-
-```
-User see [Col] column in [Table] table
-User see [Ref] row in [Table] table with {{v}}
-User see [Ref] row in [Table] table with {{v}} is hidden
-User see [Table] table with {{count}} | is empty
-User see [Col] column with {{v}}
-User click [Act] button in [Table] table with {{v}}
-User see [Table] table match data:
-    | Header1    | Header2    |
-    | {{value1}} | {{value2}} |
-```
-
-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.
-
-### Database verification (optional Data Driver)
-
-Read-only DB-state checks. **Prefer named queries** — SQL lives in `qa/screens/<screen>/database/queries.yaml` (reviewed once, parameterized). Invoke with the `@query:<name>` annotation; it binds the result rows to `{{name}}`, then assert with `expect`:
-
-```gherkin
-@query:active_user                 # precondition: run query, bind {{active_user}}
-@query:orders(buyer={{email}})     # …with explicit param override
-Scenario: ...
-  Then expect {{active_user.count}} is at least {{one}}   # ≥1 row
-  And  expect {{active_user.first.status}} is "active"     # first row's column
-  And  expect {{orders.count}} is {{expected}}             # exact count
-  And  User see [Total] text is {{orders.first.total}}     # UI ↔ DB
-```
-
-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`.
-
-### States
-
-`hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `sorted ascending` `sorted descending`
-
-### Element Types
-
-| Group | Types |
-|---|---|
-| **Context** | `page` `dialog` `modal` `drawer` `tab` `alert` `overlay` `step` |
-| **Input** | `field` `textarea` `search` `dropdown` `option` `checkbox` `radio` `toggle` `uploader` `slider` `date-picker` |
-| **Trigger** | `button` `link` `icon` `menuitem` `tag` |
-| **Data** | `table` `row` `column` `cell` `list` `item` `card` `section` |
-| **Feedback** | `message` `header` `label` `text` `tooltip` `badge` `breadcrumb` `image` |
-| **System** | `key` `frame` `spinner` `progressbar` |
-
-### Auto-infer (no YAML entry needed)
-
-Most elements auto-infer from `[Label] type` → `getByRole(type, { name: 'Label' })`. Only add YAML when the accessible name differs, needs `nth`, or needs `testid`. Full auto-infer table → see `sungen-selector-keys` skill.
-
-**Types requiring YAML entry:** `date-picker`, `uploader`, `overlay`, `frame`, `step` - these have no standard ARIA role and need explicit selectors.
-
-## YAML Keys
-
-`[Reference]` → **lowercase, keep Unicode**: `[Search Content]` → `search content:`, `[Thời gian]` → `thời gian:`
-
-- Keys use **spaces** (not dots) as word separators
-- Same label, different element types → add `--type` suffix
-- Same label, nth occurrence → add `--N` suffix
-- Target Name > 30 chars → shorten to 1–3 meaningful words
-
-## Dynamic Variables (test-data YAML)
-
-Use `{{$var}}` in test-data YAML for values that must be unique per test run. Resolved at **runtime** by `TestDataLoader` — the compiler passes them through unchanged.
-
-| Variable | Example | Output |
-|---|---|---|
-| `{{$timestamp}}` | `"User-{{$timestamp}}"` | `"User-1714000000"` |
-| `{{$uuid}}` | `"{{$uuid}}"` | `"a1b2c3d4-..."` |
-| `{{$random:min:max}}` | `"{{$random:1:100}}"` | `"42"` |
-| `{{$date}}` | `"{{$date}}"` | `"2026-04-24"` |
-| `{{$datetime}}` | `"{{$datetime}}"` | `"2026-04-24T10:30:00.000Z"` |
-
-**Rules:**
-- `$timestamp` and `$uuid` → same value across all keys in one `load()` call (stable within a test file)
-- `$random` → unique per occurrence (each key gets a different random)
-- Resolved once at load time → every `get()` returns the same resolved value
-- Use for CRUD flows to avoid data collision between parallel runs
-
-```yaml
-# test-data/crud-award.yaml
-award:
-  name: "Award-{{$timestamp}}"
-  email: "test+{{$uuid}}@example.com"
-  score: "{{$random:1:100}}"
-```
-
-## Selectors (priority order)
-
-| type | value | name | use |
-|---|---|---|---|
-| `testid` | data-testid | — | when exists |
-| `role` | button/heading/link… | accessible name | interactive elements |
-| `placeholder` | placeholder text | — | inputs |
-| `label` | label text | — | labeled inputs |
-| `text` | — | — | static text |
-| `locator` | CSS selector | — | last resort |
-| `page` | relative URL | — | navigation |
-| `upload` | — | — | file inputs |
-| `frame` | iframe selector | — | iframes |
-
-Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `columns`
-
-## Tags
-
-### Functional tags (affect code generation)
-
-| Tag | Effect |
-|---|---|
-| `@manual` | Skip in generation |
-| `@auth:role` | Use auth storage state for role |
-| `@no-auth` | Disable inherited auth |
-| `@steps:name` | Define reusable step block (base scenario) |
-| `@extend:name` | Prepend Given→When from @steps block (skip Then) |
-| `@cleanup:overlay` | Auto-cleanup: dismiss dialogs/overlays after each test (cleanupPage) |
-| `@cleanup:forms` | Auto-cleanup: clear form fields after each test (cleanupPage) |
-| `@cleanup:scroll` | Auto-cleanup: scroll to top after each test (cleanupPage) |
-| `@cleanup:storage` | Auto-cleanup: clear sessionStorage after each test (cleanupPage) |
-| `@screenshot:on-failure` | Auto-capture screenshot when test fails (base.ts fixture) |
-| `@parallel` | Opt-out: fresh page per test instead of serial default (for independent scenarios) |
-| `@beforeAll` | Hook: runs once before all tests → `test.beforeAll()` |
-| `@afterEach` | Hook: runs after each test → `test.afterEach()` (custom cleanup) |
-| `@afterAll` | Hook: runs once after all tests → `test.afterAll()` |
-| `@flow` | Mark feature as E2E flow (cross-screen testing) |
-| `@cases:dataset` | Data-driven: run the scenario once per row of the `dataset` LIST in test-data → one `test()` per row |
-| `@query:name` | Database: run the named query from `database/queries.yaml` (precondition) and bind its rows to `{{name}}`; assert with `expect {{name.count}} …` + path access. Override params `@query:name(p={{v}})`. Repeatable. (Optional Data Driver — see Database verification above) |
-| `@api:name` | API: run the named request from `api/apis.yaml` (precondition) and bind the response to `{{name}}`; assert with `expect {{name.status}} …` + path access (`{{name.body.<path>}}`). Override params `@api:name(p={{v}})`. Repeatable. (Optional API Driver) |
-| `@concurrent:N` | API idempotency: fire the bound `@api` request N times in parallel, then bind aggregates on the `@api` name — `{{name.ok_count}}` (2xx count) and `{{name.status_counts}}` (status→count map). Assert the exactly-once invariant (`expect {{name.ok_count}} is 1`); pair with `@query` as a DB oracle. Tag order = run order: `@api` (mutate) before `@query` (verify). (Optional API Driver) |
-| `@hybrid` | One unit, two capabilities: a signed-in browser session (UI) authorizes the `@api` call — the API request reuses the UI `storageState`. (Optional API + UI Drivers) |
-
-### Data-driven scenarios (`@cases`)
-
-For one test case × many inputs (email/format/boundary validation, decision tables), tag the
-scenario `@cases:<dataset>` and reference each row's columns as `{{col}}`. Put the rows as a LIST
-in test-data — NOT inline; data stays runtime + env-overlayable.
-
-```gherkin
-@high @cases:email_validation
-Scenario: VP-VAL-001 The email field rejects invalid formats
-  When User fill [Email] field with {{email}}
-  Then User see [Login Error] message with {{expected_error}}
-```
-```yaml
-# test-data/<screen>.yaml
-email_validation:
-  - { case: "no @",    email: "plainaddress", expected_error: "Invalid email" }
-  - { case: "valid",   email: "ok@x.com",     expected_error: "" }
-```
-An optional `case`/`name`/`label` column labels each run. Each row → its own pass/fail. Prefer
-`@cases` over duplicating a scenario per value. (Gherkin `Scenario Outline`/`Examples` is NOT
-supported — use `@cases`.)
-
-### Pass-through tags (filter at runtime via Playwright --grep)
-
-Any tag not listed above passes through to Playwright `{ tag: [...] }`. Feature-level tags inherit to all scenarios.
-
-| Tag | Purpose |
-|---|---|
-| `@smoke` | Quick sanity check — run after every deploy |
-| `@regression` | Full test suite — run nightly or before release |
-| `@high` | Priority: must pass — login, auth, core CRUD, primary business flow |
-| `@normal` | Priority: important — validation rules, secondary features, search/filter |
-| `@low` | Priority: minor/cosmetic — tooltips, hover states, element presence |
-| `@auto` | Standard scenario, ready for automation |
-| Any custom | e.g., `@sprint-42`, `@team-payment` — any tag works |
-
-**Assign priority by user impact** (canonical mapping — override only when context differs):
-
-| Scenario type | Tag |
-|---|---|
-| Auth redirect / unauthenticated access | `@high` |
-| CRUD happy path (create / update / delete — success) | `@high` |
-| Core business rule, state transition | `@high` |
-| XSS, SQL injection, permission blocked | `@high` |
-| Required field error, unique/duplicate constraint | `@high` |
-| Format validation (email, phone, date…) | `@normal` |
-| Boundary value — inclusive (`<=`, `>=`) → `@high`; standard range → `@normal` | `@normal` |
-| Secondary features (search, filter, sort, pagination) | `@normal` |
-| Element presence, label, placeholder, tooltip | `@low` |
-
-**Run filtered:**
-```bash
-npx playwright test --grep "@smoke"          # only smoke tests
-npx playwright test --grep "@high"           # only high priority
-npx playwright test --grep "@smoke|@high"    # smoke OR high
-```
-
-### Serial vs Parallel (test execution mode)
-
-**Default: serial** — `test.describe.serial()` with shared page. Background runs once in `beforeAll`. Fail → skip remaining.
-
-**`@parallel` opt-out** — `test.describe()` with fresh page per test. Background runs as `beforeEach`. Use when scenarios are truly independent (validation rules, permission tests).
-
-| Mode | Generated | Page | Background | On fail |
-|---|---|---|---|---|
-| Serial (default) | `test.describe.serial()` | Shared | `beforeAll` (1 goto) | Skip remaining |
-| `@parallel` | `test.describe()` | Fresh per test | `beforeEach` (N goto) | Continue |
-
-**`@parallel` is required** when a feature has multiple auth groups (e.g., `@auth:user` + `@no-auth` scenarios). Serial mode uses one shared browser context and cannot mix auth roles. The compiler will error if `@parallel` is missing in this case.
-
-### `@flow` tag (E2E cross-screen testing)
-
-`@flow` marks a feature as a **flow** — an E2E journey spanning multiple screens. Flows live in `qa/flows/<name>/` with their own selectors, test-data, and requirements.
-
-**Key differences from screen tests:**
-
-| Aspect | Screen (`qa/screens/`) | Flow (`qa/flows/`) |
-|---|---|---|
-| Scope | Single page | Multiple pages |
-| Selectors | `[Element]` → own YAML | `[Screen:Element]` → own YAML (namespaced) |
-| Test data | `{{variable}}` | `{{phase.variable}}` (namespaced by phase) |
-| Tag | `@auto` / `@smoke` etc. | `@flow` (required at feature level) |
-| Multi-domain | N/A | Absolute URL in selector `path:` skips baseURL |
-
-**Selector namespace format:** `[Screen:Element]` where colon separates screen prefix from element name. The YAML key is `"screen:element"` (quoted, lowercase).
-
-```gherkin
-# Feature file
-When User fill [Login:Email] field with {{login.email}}
-And User click [Login:Submit] button
-Then User see [Dashboard] page
-When User click [Dashboard:Awards] link
-```
-
-```yaml
-# selectors.yaml — keys are namespaced, quoted due to colon
-"login:email":
-  type: 'testid'
-  value: 'email-input'
-
-"login:submit":
-  type: 'role'
-  value: 'button'
-  name: 'Login'
-
-dashboard:
-  type: 'page'
-  value: '/dashboard'
-
-"dashboard:awards":
-  type: 'role'
-  value: 'link'
-  name: 'Awards'
-```
-
-**Flow structure:**
-- `Background:` — set starting page only (e.g., `Given User is on [Login] page`)
-- Each `Scenario:` — one phase/step of the flow (login, navigate, submit, etc.)
-- Page navigation between scenarios uses `[Screen] page` references
-
-**CLI:** `sungen add-flow --flow <name>`, `sungen generate --flow <name>`, `sungen generate --all` (includes flows)
-
-### @extend behavior
-
-- Tool executes **only Given→When** of `@steps` scenario (skips Then)
-- The `Given` in `@extend` scenario is the **entry assertion** (confirms state after base steps)
-- **Entry assertion MUST use `Given User is on [X] type`** — NEVER `Given User see [X] type`
-- `Given` keyword ONLY allows `is on` action. `see` = `Then` only.
-- If `@steps` scenario fails, `@extend` scenario is **skipped**
-- Name format: `snake_case` or `kebab-case` with module prefix: `@steps:kudos__open_modal`
-
-## Common Syntax Errors
-
-| Error | Wrong | Correct |
-|---|---|---|
-| Wrong keyword | `Given User click [T] button` | `When User click [T] button` |
-| `see` after Given | `Given User see [T] heading with {{v}}` | `Then User see [T] heading with {{v}}` (or `Given User is on [T] page` for entry assertion) |
-| Name ≠ step type | Scenario name says "modal" but step uses `dialog` | Use the **same element type** in both: "...dialog opens" + `[X] dialog` |
-| Wrong action for type | `When User click [T] checkbox` | `When User check [T] checkbox` |
-| press wrong target | `When User press [Submit] button` | `When User press Enter key` |
-| uncheck radio | `When User uncheck [Male] radio` | `When User check [Female] radio` |
-| Hardcode data | `with {{admin@mail.com}}` | `with {{invalid_email}}` |
-| Missing `is` for state | `with {{text}} hidden` | `with {{text}} is hidden` |
-| State as value | `with {{disabled}}` | `is disabled` |
-| Missing target type | `fill [email] with {{v}}` | `fill [email] field with {{v}}` |
-| Background with scope | `Background: ... And User is on [X] dialog` | Use `@steps` + `@extend` for scope-dependent flows |
-| `is on` after When | `When ... And User is on [X] dialog` | `And User see [X] dialog` or separate Given |
-| Literal URL navigate | `User navigate to "/dashboard"` | `User is on [Dashboard] page` (add page selector in `selectors.yaml`) |
-
-## Background vs @steps/@extend
-
-Both `Background` and `@steps`/`@extend` are valid — they serve different purposes.
-
-| Pattern | Use when | Generates |
-|---|---|---|
-| `Background` | Simple shared setup (navigate to page) | `test.beforeEach()` |
-| `@steps`/`@extend` | Complex reusable flows with scope (dialog, frame) | Inline merged steps in `test()` |
-
-**Use `Background` for simple navigation:**
-```gherkin
-Background:
-  Given User is on [Dashboard] page
-
-Scenario: View stats
-  Then User see [Revenue Chart] section
-```
-
-**Use `@steps`/`@extend` when scope matters (dialog, frame):**
-```gherkin
-@steps:open_modal
-Scenario: Open modal
-  Given User is on [Kudos] page
-  When User click [Open] button
-  Then User see [Modal] dialog
-
-@extend:open_modal
-Scenario: VP-UI-001 Title visible
-  Given User is on [Modal] dialog
-  Then User see [Title] heading
-```
-
-**Avoid `Background` with scope-dependent steps** — `When` + `And User is on [X] dialog` creates keyword mismatch (`is on` = Given, not When). Use `@steps`/`@extend` instead.
-
-## Hooks & Cleanup
-
-Two layers for test lifecycle management. Prefer `@cleanup:*` tags (Layer 1) — they work with base.ts automatically. Use hook scenarios (Layer 2) only for custom logic.
-
-### Layer 1: `@cleanup:*` tags (automatic via base.ts)
-
-Feature-level tags that activate cleanup fixtures in base.ts. No Gherkin steps needed.
-
-```gherkin
-@auth:admin
-@cleanup:overlay
-@cleanup:forms
-Feature: User Management
-  Path: /users
-
-  Background:
-    Given User is on [User Management] page
-
-  Scenario: Create user shows form
-    When User click [Add User] button
-    Then User see [Create User] dialog
-
-  Scenario: Search user by name
-    When User fill [Search] field with {{search_name}}
-    Then User see [User Row] row
-```
-
-| Tag | What base.ts does after each test |
-|---|---|
-| `@cleanup:overlay` | Press Escape, click body, dismiss fixed overlays |
-| `@cleanup:forms` | Clear all input/textarea fields, reset selects |
-| `@cleanup:scroll` | Scroll to top of page |
-| `@cleanup:storage` | Clear sessionStorage |
-
-### Layer 2: `@afterEach` scenario (custom cleanup)
-
-Only when `@cleanup:*` tags aren't enough — feature-specific logic.
-
-### Layer 3: `@beforeAll` / `@afterAll` (optional)
-
-For one-time setup/teardown.
-
-**Rendering order in `.spec.ts`:**
-`test.describe` → `test.use(storageState)` → `test.use(autoCleanup)` → `test.beforeAll` → `test.beforeEach` → `test.afterEach` → `test.afterAll` → `test()` blocks