@sun-asterisk/sungen 2.2.2 → 2.3.0

package/dist/orchestrator/templates/ai-instructions/claude-cmd-add-screen.md

@@ -25,19 +25,28 @@ Run:
 sungen add --screen <screen> --path <path>
 ```
 
-### 2. Create test cases
+### 2. Fill requirements (recommended)
+
+Ask the user: "Would you like to fill in `requirements/spec.md` now? This helps generate higher quality test cases."
+
+- If yes → open `qa/screens/<screen>/requirements/spec.md` and help the user fill sections, fields, validation rules, business rules, and states.
+- If they have UI designs (screenshots, Figma exports, mockups) → suggest copying them to `requirements/ui/`.
+- If no → proceed to step 3.
+
+### 3. Create test cases
 
 Ask the user: "Would you like to create test cases now?"
 
-If yes, delegate to `/sungen:make-tc <screen>` to handle:
-- Exploring the live page or analyzing static designs
-- Gathering test viewpoints (UI/UX, Validation, Logic, Security)
-- Generating the 3 files (feature, selectors, test-data)
+If yes → **you MUST use the Skill tool** to invoke `/sungen:make-tc <screen>`. This is critical because `make-tc` auto-loads the `sungen-gherkin-syntax` and `sungen-tc-generation` skills which contain the full Gherkin syntax rules, pattern shapes, viewpoint checklists, and output format. **Do NOT attempt to generate test cases yourself** — always invoke the Skill tool so these skills are properly loaded.
+
+```
+Skill: make-tc
+Args: <screen>
+```
 
-### 3. Confirm
+### 4. Confirm
 
-Tell the user what was created and next steps:
-- If the page requires authentication, the user will be asked to log in via the MCP browser during `/sungen:make-tc`
-- Edit the generated files as needed
+If the user declined test case creation, tell them next steps:
+- Fill `requirements/spec.md` with screen specs (if not done)
 - Run `/sungen:make-tc <screen>` to create test cases
 - Run `/sungen:make-test <screen>` to generate selectors, compile, and run tests

package/dist/orchestrator/templates/ai-instructions/claude-cmd-make-tc.md

@@ -17,9 +17,16 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 
 1. Verify `qa/screens/<screen>/` exists. If not → `/sungen:add-screen` first.
 2. Check if `.feature` file already has scenarios. If yes → use `AskUserQuestion` to ask the update mode (see `sungen-tc-generation` skill for details). If no → fresh creation.
-3. Use `AskUserQuestion` to ask: **Live page** (explore via Playwright MCP) or **Static designs** (screenshots, Figma)? Explore accordingly (see CLAUDE.md for MCP rules).
-4. Follow the `sungen-tc-generation` skill for section identification, viewpoint generation, and output format.
-5. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills.
-6. Show summary → next: `/sungen:make-test <screen>`
+3. **Read requirements** — check `qa/screens/<screen>/requirements/`:
+   - If `spec.md` exists → read it as PRIMARY source (sections, fields, validation rules, business rules, states).
+   - If `ui/` has images → read them for visual context (layout, element positions, states).
+   - If `notes.md` exists → read for edge cases and additional context.
+   - Summarize what you found in requirements and present to the user.
+4. **Explore page** (supplements requirements, or is primary source if no requirements):
+   - Use `AskUserQuestion` to ask: **Live page** (explore via Playwright MCP) or **Static designs** (screenshots, Figma)? Or **Skip** (if requirements are sufficient)?
+   - If exploring, verify and supplement requirements — flag any discrepancies found.
+5. Follow the `sungen-tc-generation` skill for section identification, viewpoint generation, and output format. When requirements exist, use the "Requirements-Driven Generation" strategy.
+6. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills.
+7. Show summary → next: `/sungen:make-test <screen>`
 
 **No selectors.yaml** — selectors are generated during `/sungen:make-test`.

package/dist/orchestrator/templates/ai-instructions/claude-cmd-make-test.md

@@ -16,9 +16,14 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 ## Steps
 
 1. Verify `qa/screens/<screen>/` has `.feature` + `test-data.yaml`. If not → `/sungen:make-tc` first.
-2. Generate `selectors.yaml` from live page using `sungen-selector-fix` and `sungen-selector-keys` skills.
-3. Compile: `sungen generate --screen <screen>`
-4. Run: `npx playwright test specs/screens/<screen>/<screen>.spec.ts`
-5. If fail → fix selectors/test-data per `sungen-selector-fix` + `sungen-error-mapping` skills, retry (max 5).
-6. After 5 fails → ask user about direct `.spec.ts` fix.
-7. Show: pass/fail, attempt count, files changed.
+2. **Generate selectors** — explore live page via MCP, build `selectors.yaml` using `sungen-selector-fix` and `sungen-selector-keys` skills.
+3. **Proactive validation** — verify EVERY selector against the live page using `browser_snapshot` + `browser_evaluate` BEFORE running any test. Fix mismatches immediately. See `sungen-selector-fix` skill "Proactive Selector Validation" section. Target: 80%+ issues fixed before first run.
+4. **Compile**: `sungen generate --screen <screen>`
+5. **Batched test run** — run tests in batches of 20 via `--grep`:
+   `npx playwright test specs/generated/<screen>/*.spec.ts --grep "VP-UI-001|...|VP-UI-020" --reporter=line`
+   - If failures in batch → group by root cause, fix, recompile, re-run only failing tests
+   - If batch passes → move to next 20 tests
+   - Max 5 fix attempts per batch
+6. **Final confirmation** — run ALL tests once to catch regressions.
+7. After 5 fix attempts still failing → ask user about direct `.spec.ts` fix.
+8. Show: pass/fail, attempt count, files changed.

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

@@ -6,16 +6,29 @@ user-invocable: false
 
 ## Playwright Errors → Fix
 
-| Error | Fix in `selectors.yaml` |
+| Error | Fix |
 |---|---|
-| strict mode violation | add `nth`, `exact: true`, or specific `name` |
-| Element is not an input | change `type` or `value` |
-| Timeout waiting for selector | fix `type`/`value`/`name` to match element |
-| toBeVisible Timeout | verify accessible name or use `testid` |
-| toHaveText mismatch | fix in `test-data.yaml` |
-| Navigation failed | fix page `value` path |
-| not a select | set `variant: 'custom'` |
-| Frame not found | fix `frame` value |
+| strict mode violation | add `nth`, `exact: true`, or specific `name` in selectors.yaml |
+| Element is not an input | change `type` or `value` in selectors.yaml |
+| Timeout waiting for selector | fix `type`/`value`/`name` to match element in selectors.yaml |
+| toBeVisible Timeout | verify accessible name or use `testid` in selectors.yaml |
+| toHaveText mismatch | fix expected text in `test-data.yaml` — OR if element is an input (field/textarea/search/dropdown), change Gherkin type so compiler uses `toHaveValue` instead |
+| toHaveValue mismatch | fix expected value in `test-data.yaml` — this is for input elements (field, textarea, search, dropdown, slider, date-picker) |
+| toContainText mismatch | fix expected partial text in `test-data.yaml` |
+| Navigation failed | fix page `value` path in selectors.yaml |
+| not a select | set `variant: 'custom'` in selectors.yaml |
+| Frame not found | fix `frame` value in selectors.yaml |
+| dialog was dismissed | alert step is AFTER the trigger — move `click [OK] alert` BEFORE the button click that opens the dialog |
+| page.once('dialog') never fired | no browser dialog appeared — check if the action actually triggers a `window.alert/confirm/prompt`, not a CSS modal |
+
+### Assertion type mismatch (toHaveText vs toHaveValue)
+
+Sungen picks the assertion based on element type:
+- **Input types** (`field`, `textarea`, `search`, `dropdown`, `slider`, `date-picker`) → `toHaveValue()`
+- **Text types** (everything else: `message`, `header`, `label`, `row`, etc.) → `toHaveText()`
+- **Partial match** (uses `contains` keyword) → `toContainText()`
+
+If you see `toHaveText` failing on an input element, the Gherkin step has the wrong target type. Fix: change the target type in the `.feature` file (e.g., `see [Email] message with {{v}}` → `see [Email] field with {{v}}`).
 
 ## Auth Errors → Fix
 

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

@@ -4,13 +4,35 @@ description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Auto-
 user-invocable: false
 ---
 
-## Step Patterns (65 patterns)
+## 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
 
 ```
 User is on [T] page                              # navigate to page
 User is on [T] page with {{v}}                   # navigate with data (e.g., detail page with ID)
+User is on [T] dialog                            # enter dialog scope
 User is logged in | is not logged in              # auth state
 ```
 
@@ -18,31 +40,57 @@ User is logged in | is not logged in              # auth state
 
 ```
 User fill [T] field with {{v}}                   # text input
+User fill [T] textarea with {{v}}                # multiline input
+User fill [T] search with {{v}}                  # search input
+User fill [T] slider with {{v}}                  # set slider value
+User fill [T] date picker with {{v}}             # date input
 User clear [T] field                             # clear input
 User check [T] checkbox                          # check
+User check [T] toggle                            # toggle on (same as check)
+User check [T] radio                             # select radio
 User uncheck [T] checkbox                        # uncheck
+User uncheck [T] toggle                          # toggle off
 User select [T] dropdown with {{v}}              # select option
-User toggle [T] switch                           # toggle switch/checkbox
-User upload [T] file with {{f}}                  # file upload
+User upload [T] uploader with {{f}}              # file upload
 ```
 
 ### Interaction
 
 ```
-User click [T] button                            # click
-User click [T] button with {{v}}                 # click with text match
+User click [T] button                            # click (static element, no value)
+User click [T] row with {{v}}                    # click dynamic list item (row/item/card/option)
+User click [T] tab                               # switch tab
+User click [T] column                            # sort column
+User click [T] breadcrumb                        # navigate breadcrumb
 User double click [T] element                    # double click
-User hover [T] icon                              # hover
+User hover [T] icon                              # hover (must have see/click after)
+User hover [T] row                               # hover row for hidden actions
 User drag [T] to [T2]                            # drag and drop
 User expand [T] row                              # expand (aria-expanded)
 User collapse [T] row                            # collapse (aria-expanded)
 ```
 
+#### click + with {{Value}} rule
+
+- **NO value** for static elements: `button`, `link`, `icon`, `tab`, `toggle`
+- **WITH value** only for dynamic lists: `row`, `item`, `card`, `option`
+
+### Browser Alert (system dialog)
+
+```
+User click [OK] alert                            # accept (OK/Accept/Yes/Confirm)
+User click [Cancel] alert                        # dismiss (Cancel/Dismiss/No)
+User fill [T] alert with {{v}}                   # fill prompt + accept
+User see [message text] alert                    # assert dialog message
+```
+
+> Alert steps must appear BEFORE the action that triggers the dialog.
+
 ### Keyboard
 
 ```
-User press Escape key                            # global key press
-User press Enter on [T] field                    # key on element
+User press [Escape] key                          # global key press
+User press [Enter] on [T] field                  # key on element
 ```
 
 ### Wait
@@ -53,53 +101,129 @@ User wait for [T] dialog                         # wait for element
 User wait for [T] dialog is STATE                # wait for state
 User wait for [T] dialog with {{v}}              # wait for element with text
 User wait for [T] page                           # wait for navigation
+User wait for [T] message                        # wait for toast/feedback
+User wait for [T] button                         # wait for button to appear
 ```
 
 ### Scroll & Frame
 
 ```
 User scroll to [T] section                       # scroll into view
-User switch to [T] frame                         # enter/exit iframe
+User switch to [T] frame                         # enter iframe
+User switch to [main] frame                      # exit iframe
 ```
 
-### Assertions
+### Assertions (8 verify patterns)
 
 ```
-User see [T] page                                # URL assertion
-User see [T] heading                             # visibility
-User see [T] heading with {{v}}                  # visibility + text
+# 1. Visibility
+User see [T] message                             # visible (default — NEVER add "is visible")
+User see [T] modal is hidden                     # hidden
+
+# 2. Text Content (exact full match — toHaveText)
+User see [T] message with {{v}}                  # exact text match
+User see [T] header with {{v}}                   # heading text
+User see [T] label with {{v}}                    # label text
+
+# 3. Partial Text Match (toContainText)
 User see [T] text contains {{v}}                 # partial text match
-User see [T] text has text {{v}}                 # exact text match
-User see [T] button is STATE                     # state assertion
-User see [T] dialog with {{v}} is STATE          # text + state
-User see {{v}}                                   # see data text
+
+# 4. Input Value (toHaveValue)
+User see [T] field with {{v}}                    # input value
+User see [T] dropdown with {{v}}                 # selected value
+User see [T] date picker with {{v}}              # date value
+User see [T] search with {{v}}                   # search input value
+User see [T] slider with {{v}}                   # slider value
+
+# 5. Component State
+User see [T] button is disabled                  # state assertion
+User see [T] checkbox is checked                 # checked state
+User see [T] toggle is unchecked                 # unchecked state
+User see [T] dialog with {{v}} is hidden         # text + state combined
+
+# 6. Attribute (toHaveAttribute — when selector YAML has `attribute` field)
+User see [T] image with {{v}}                    # image src
+User see [T] link with {{v}}                     # link href
+
+# 7. Count
+User see [T] row with {{count}}                  # element count
+
+# 8. Page Context
+User see [T] page                                # URL assertion
 ```
 
 ### Table
 
 ```
-User see [Table] table has row with {{f}}        # row exists
+User see [Col] column in [Table] table           # column exists (parent scoping)
+User see [Table] table row with {{f}}            # row exists
 User see [Table] table has no row with {{f}}     # row not exists
-User see [Table] table has {{count}} rows        # row count
-User see [Table] table has [Col] column          # column exists
+User see [Table] table with {{count}} rows       # row count
 User see [Table] table is empty                  # empty table
 User see [Table] table row with {{f}} has [Col] with {{v}}  # cell by filter
 User see [Table] table row 1 [Col] cell with {{v}}          # cell by index
 User click [Act] in [Table] table row with {{f}}             # action in row
 ```
 
+### Parent Scoping (disambiguation)
+
+```
+User click [Submit] button in [User Info] form           # button inside specific form
+User fill [Email] field in [Registration] form with {{v}} # field inside specific form
+User see [Total] text in [Summary] section with {{v}}    # text inside specific section
+User click [Delete] button in [Active Users] table       # button inside specific table
+```
+
+- **Optional** — only use when page has 2+ similar UI blocks
+- **Valid parent types**: `table`, `list`, `section`, `dialog`, `form`
+- **Max 2 levels**: `[Target] in [Parent]`. **NEVER** nest 3 levels: `[A] in [B] in [C]`
+- Parent resolves from selectors YAML first, falls back to auto-infer `getByRole(parentType, { name })`
+
 ### States
 
 `hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `sorted ascending` `sorted descending`
 
 ### Element Types
 
-`page` `button` `link` `field` `textarea` `heading` `text` `checkbox` `radio` `switch` `dropdown` `dialog` `modal` `menu` `menuitem` `tab` `tabpanel` `table` `row` `cell` `list` `listitem` `icon` `image` `alert` `spinner` `progressbar` `section` `region` `nav` `frame` `uploader` `file` `columnheader` `tooltip` `slider` `treeitem`
+| 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)
+
+| Gherkin | Playwright locator |
+|---|---|
+| `[Submit] button` | `getByRole('button', { name: 'Submit' })` |
+| `[Home] link` | `getByRole('link', { name: 'Home' })` |
+| `[Welcome] heading` / `header` | `getByRole('heading', { name: 'Welcome' })` |
+| `[Email] field` | `getByPlaceholder('Email')` |
+| `[Success] text` / `message` / `label` | `getByText('Success')` |
+| `[Terms] checkbox` | `getByRole('checkbox', { name: 'Terms' })` |
+| `[Male] radio` | `getByRole('radio', { name: 'Male' })` |
+| `[Global] search` | `getByRole('searchbox', { name: 'Global' })` |
+| `[Vietnam] option` | `getByRole('option', { name: 'Vietnam' })` |
+| `[Price] slider` | `getByRole('slider', { name: 'Price' })` |
+| `[Notification] toggle` | `getByRole('switch', { name: 'Notification' })` |
+| `[Profile] tab` | `getByRole('tab', { name: 'Profile' })` |
+| `[Orders] table` | `getByRole('table', { name: 'Orders' })` |
+| `[Products] list` | `getByRole('list', { name: 'Products' })` |
+| `[Name] column` | `getByRole('columnheader', { name: 'Name' })` |
+| `[Confirm] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'Confirm' })` |
 
 ## 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
+
 ## Selectors (priority order)
 
 | type | value | name | use |
@@ -120,8 +244,30 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 
 | Tag | Effect |
 |---|---|
+| `@auto` | Standard scenario, ready for automation |
+| `@manual` | Skip in generation |
+| `@smoke` / `@regression` | Test suite grouping |
 | `@auth:role` | Use auth storage state for role |
 | `@no-auth` | Disable inherited auth |
-| `@steps:name` | Define reusable step block |
-| `@extend:name` | Prepend steps from @steps block |
-| `@manual` | Skip in generation |
+| `@steps:name` | Define reusable step block (base scenario) |
+| `@extend:name` | Prepend Given→When from @steps block (skip Then) |
+
+### @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)
+- 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` |
+| 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}}` |

package/dist/orchestrator/templates/ai-instructions/claude-skill-selector-fix.md

@@ -124,6 +124,24 @@ To determine the correct `nth` offset, count how many matching elements appear b
 
 ---
 
+### Step 4b: Handle Detail Screens with Dynamic IDs
+
+For screens like `/admin/users/:id` or `/products/:slug`:
+1. Navigate to the **list page** first via MCP browser to find a real record ID
+2. Use that ID in the page selector value
+3. Use `User is on [X] page` — sungen resolves the path from the selector
+
+```yaml
+# selectors.yaml — full path with real ID
+user detail:
+  type: 'page'
+  value: '/admin/users/de42d800-0f5a-490e-9dcf-344fedbd34a5'
+```
+
+Note: the selector uses a hardcoded ID from the live page. If the record is deleted, update the ID in `selectors.yaml`.
+
+---
+
 ### Step 5: Handle SPA / Client-side Routing
 
 Many modern apps (Next.js, Nuxt, SvelteKit, etc.) return the same HTML shell for all URLs and route client-side. `domcontentloaded` fires on the shell before the target page renders.
@@ -168,9 +186,16 @@ Many elements don't need a YAML entry — sungen auto-infers from the Gherkin la
 |---|---|
 | `[Submit] button` | `getByRole('button', { name: 'Submit' })` |
 | `[Home] link` | `getByRole('link', { name: 'Home' })` |
-| `[Welcome] heading` | `getByRole('heading', { name: 'Welcome' })` |
+| `[Welcome] heading` / `header` | `getByRole('heading', { name: 'Welcome' })` |
 | `[Email] field` | `getByPlaceholder('Email')` |
-| `[Success] text` | `getByText('Success')` |
+| `[Success] text` / `message` / `label` | `getByText('Success')` |
+| `[Terms] checkbox` | `getByRole('checkbox', { name: 'Terms' })` |
+| `[Global] search` | `getByRole('searchbox', { name: 'Global' })` |
+| `[Vietnam] option` | `getByRole('option', { name: 'Vietnam' })` |
+| `[Price] slider` | `getByRole('slider', { name: 'Price' })` |
+| `[Notification] toggle` | `getByRole('switch', { name: 'Notification' })` |
+| `[Profile] tab` | `getByRole('tab', { name: 'Profile' })` |
+| `[Confirm] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'Confirm' })` |
 
 **Only add a YAML entry when auto-infer won't work:**
 - The accessible name differs from the Gherkin label
@@ -181,20 +206,101 @@ Many elements don't need a YAML entry — sungen auto-infers from the Gherkin la
 
 ---
 
-### Fix Loop on Test Failure
+### Proactive Selector Validation (before running tests)
+
+**Most failures are selector mismatches.** Validate selectors against the live page BEFORE running any test — this eliminates slow compile→run→read→fix cycles.
+
+After generating `selectors.yaml` (Step 3), verify each entry:
 
+#### How to validate
+
+Use `browser_evaluate` to check if each selector actually finds an element on the page:
+
+```js
+// Validate a role selector
+document.querySelectorAll('[role="button"]').length;
+// or check accessible name exists
+Array.from(document.querySelectorAll('button'))
+  .filter(el => el.textContent.includes('Submit') || el.getAttribute('aria-label')?.includes('Submit'))
+  .length;
 ```
-attempt = 0
-while attempt < 5:
-    compile → run test
-    if pass → done
-    read error-context.md in test-results/ → check exact snapshot state at failure time
-    fix selectors.yaml or test-data.yaml
-    recompile → attempt++
-if still failing → ask user about direct .spec.ts fix
+
+Or use `browser_snapshot` and cross-check:
+1. Read all `[Reference]` entries from `selectors.yaml`
+2. Take a `browser_snapshot`
+3. For each entry, verify:
+   - **role + name**: does the snapshot contain `button "Submit"` or `link "Home"`?
+   - **testid**: does `browser_evaluate` find `[data-testid="xxx"]`?
+   - **placeholder**: does the snapshot contain a textbox with that placeholder?
+   - **locator**: does `browser_evaluate` find `document.querySelector('xxx')`?
+4. Fix mismatches immediately — no need to run tests
+
+#### What to check
+
+| Selector type | Validation method |
+|---|---|
+| `role` + `name` | Search snapshot for `role "name"` text |
+| `testid` | `browser_evaluate`: `document.querySelector('[data-testid="xxx"]')` |
+| `placeholder` | Search snapshot for textbox with placeholder |
+| `locator` (CSS) | `browser_evaluate`: `document.querySelector('xxx')` |
+| `page` | Verify URL path exists (navigate and check) |
+
+#### Common proactive fixes
+
+- Name mismatch → copy exact name from snapshot
+- Element not found → check if element is inside iframe/dialog (needs `frame` or scope)
+- Multiple matches → add `nth: 0` or `exact: true`
+- No accessible name → switch to `testid` or `locator`
+
+**Target: fix 80%+ of selector issues before the first test run.**
+
+---
+
+### Batched Test Execution
+
+After proactive validation, run tests in **batches of 20** for faster feedback:
+
+```
+1. COMPILE — sungen generate --screen <screen>
+
+2. BATCH RUN — run 20 tests at a time:
+     npx playwright test <spec> --grep "VP-UI-001|VP-UI-002|...|VP-UI-020" --reporter=line
+
+3. IF FAILURES in batch:
+     a. Group failures by root cause (same selector, same error type)
+     b. Fix selectors.yaml or test-data.yaml
+     c. Recompile: sungen generate --screen <screen>
+     d. Re-run ONLY the failing tests from this batch
+     e. If fixed → move to next batch
+
+4. NEXT BATCH — repeat with next 20 tests (VP-UI-021...VP-UI-040)
+
+5. FINAL CONFIRMATION — after all batches pass, run ALL tests once:
+     npx playwright test <spec> --reporter=line
+     This catches regressions from selector changes.
+
+6. If still failing after 5 fix attempts per batch → ask user about direct .spec.ts fix
 ```
 
-**Always read the error context snapshot first** — it shows the exact page state when the test failed, which is more reliable than re-navigating with MCP.
+#### Building batch `--grep` patterns
+
+Extract scenario names and batch them:
+```bash
+# Batch 1: first 20
+npx playwright test <spec> --grep "VP-UI-001|VP-UI-002|...|VP-UI-020" --reporter=line
+
+# Batch 2: next 20
+npx playwright test <spec> --grep "VP-VAL-001|VP-VAL-002|...|VP-VAL-020" --reporter=line
+```
+
+#### Grouping failures by root cause
+
+Common patterns where 1 fix resolves many failures:
+- **Same selector** — e.g., all `[Email Error]` tests fail → fix `email error` in selectors.yaml once
+- **Same error type** — e.g., all `strict mode violation` → add `exact: true` or `nth`
+- **Same assertion** — e.g., all `toHaveText` on inputs fail → change Gherkin pattern
+
+Fix the root cause first, verify with the batch, then move on.
 
 ---
 

package/dist/orchestrator/templates/ai-instructions/claude-skill-selector-keys.md

@@ -51,6 +51,10 @@ Type aliases (normalized automatically):
 | logo, image, icon | `img` |
 | btn | `button` |
 | input, textbox, textarea, editor | `field` |
+| search | `searchbox` |
+| toggle | `switch` |
+| alert | `alertdialog` |
+| modal, drawer | `dialog` |
 | column | `columnheader` |
 | list-item | `listitem` |
 
@@ -83,10 +87,20 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 |---|---|
 | `[X] button` | `getByRole('button', { name: 'X' })` |
 | `[X] link` | `getByRole('link', { name: 'X' })` |
-| `[X] heading` | `getByRole('heading', { name: 'X' })` |
+| `[X] heading` / `header` | `getByRole('heading', { name: 'X' })` |
 | `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` |
+| `[X] radio` | `getByRole('radio', { name: 'X' })` |
 | `[X] field` | `getByPlaceholder('X')` |
-| `[X] text` | `getByText('X')` |
+| `[X] text` / `message` / `label` | `getByText('X')` |
 | `[X] logo/image/icon` | `getByRole('img', { name: 'X' })` |
+| `[X] search` | `getByRole('searchbox', { name: 'X' })` |
+| `[X] option` | `getByRole('option', { name: 'X' })` |
+| `[X] slider` | `getByRole('slider', { name: 'X' })` |
+| `[X] toggle` | `getByRole('switch', { name: 'X' })` |
+| `[X] tab` | `getByRole('tab', { name: 'X' })` |
+| `[X] table` | `getByRole('table', { name: 'X' })` |
+| `[X] list` | `getByRole('list', { name: 'X' })` |
+| `[X] column` | `getByRole('columnheader', { name: 'X' })` |
+| `[X] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'X' })` |
 
 **Only add a YAML entry when** the auto-inferred locator won't work (wrong name, need testid, need nth, etc.).