@sun-asterisk/sungen 2.2.3 → 2.3.1

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

@@ -0,0 +1,228 @@
+---
+name: sungen-gherkin-review
+description: 'Quality review checklist for Gherkin test cases — assertion quality rules, action-result coherence, and 9-point checklist. Auto-loaded during self-review step of make-tc.'
+user-invocable: false
+---
+
+## Assertion Quality Rules
+
+**CRITICAL** — these rules prevent shallow, low-value test cases:
+
+1. **NEVER use `is visible`** — `User see [T] type` already asserts visibility. Writing `is visible` is redundant noise. Only use `is hidden` to assert something is NOT shown.
+2. **Group related assertions** — one scenario can have 3-7 `Then/And` steps. Don't waste a whole scenario on one element. Group elements that verify the same concern.
+3. **Assert content, not just existence** — verify values, text, states, not just "it's there". Every assertion should answer: what EXACTLY should the user see? Add `with {{value}}` or `is state` whenever the expected content/state is known.
+   - `User see [Title] heading with {{page_title}}` — verify text
+   - `User see [Email] field with {{default_email}}` — verify default value
+   - `User see [Submit] button is disabled` — verify state
+   - `User see [Error] message with {{error_text}}` — verify exact error
+4. **Don't assume element roles** — never guess the element type (`button`, `option`, `link`, etc.) based on the label or expected behavior. Developers create custom components that don't match standard HTML roles (e.g., a `<div>` styled as a button, a custom dropdown built from `<li>` elements). Always use the **live-page selector scan result** or the selector YAML to determine the correct type. If you haven't scanned the page and the type is uncertain, use a generic type (`text`) or mark the scenario `@manual` until selectors are confirmed.
+
+**Bad** (shallow — just checks existence):
+```gherkin
+Scenario: VP-UI-001 Email field is visible
+  Given User is on [Login] page
+  Then User see [Email] field is visible
+
+Scenario: VP-UI-002 Password field is visible
+  Given User is on [Login] page
+  Then User see [Password] field is visible
+```
+
+**Good** (rich — verifies content, states, groups related checks):
+```gherkin
+Scenario: VP-UI-001 Login form displays all fields with correct defaults
+  Given User is on [Login] page
+  Then User see [Login] heading with {{login_title}}
+  And User see [Email] field
+  And User see [Password] field
+  And User see [Remember me] checkbox is unchecked
+  And User see [Submit] button is enabled
+  And User see [Forgot password] link
+```
+
+## Action-Result Coherence Rules
+
+Every scenario with a `When` action **must** assert the *result* of that action in `Then` — not just re-assert something already visible.
+
+**Anti-patterns (WRONG):**
+```gherkin
+# BAD: click then assert the same element unchanged
+When User click [Select language] button
+Then User see [Select language] button
+
+# BAD: fill then assert unrelated page (fill doesn't navigate)
+When User fill [Search] field with {{term}}
+Then User see [Home] page
+
+# BAD: action with no meaningful result check
+When User click [Submit] button
+Then User see [Submit] button
+```
+
+**Correct patterns:**
+```gherkin
+# GOOD: click opens something new (dropdown, dialog, page)
+When User click [Select language] button
+Then User see [VN] button
+
+# GOOD: click changes state on the element itself
+When User click [Submit] button
+Then User see [Submit] button is disabled
+
+# GOOD: click navigates to different page
+When User click [Login] button
+Then User see [Dashboard] page
+
+# GOOD: fill triggers visible result (search results, validation)
+When User fill [Search] field with {{term}}
+Then User see [search result] text with {{result_name}}
+
+# GOOD: fill then submit, assert result of submission
+When User fill [Email] field with {{invalid_email}}
+And User click [Submit] button
+Then User see [email error] message with {{email_error_text}}
+
+# GOOD: click opens dialog
+When User click [Submit] button
+Then User see [Confirm] dialog
+
+# GOOD: visibility-only scenario has no When (just Given + Then)
+Given User is on [Login] page
+Then User see [Email] field
+```
+
+**Rules:**
+1. `When click [X]` → `Then` must assert either a **new element appears** (dialog, dropdown, page change, new content) or a **state change on `[X]` itself** (e.g., `is disabled`, `is checked`). Never assert `[X]` unchanged. Asserting something already visible before the click is a pre-existing state error — if the result is uncertain, mark `@manual`.
+2. `When fill [X] field` → `Then` must assert the **visible result of the input** (search results appear, validation message shows, dropdown filters). Do NOT just assert the field has the value — `see [X] field with {{v}}` after fill is a **weak test** (Playwright fill already guarantees the value is set). Only use field value assertion when the field transforms the input (e.g., auto-format phone number, currency mask).
+   - **Search fields need a wait step** — search inputs typically have debounce/delay before results appear. After filling a search field, add `User wait for {{search_delay}}` before asserting results. Without this, the assertion fires before results render and the test flakes.
+   ```gherkin
+   # GOOD: wait for debounce before asserting search results
+   When User fill [Search] field with {{term}}
+   And User wait for {{search_delay}}
+   Then User see [search result] text with {{result_name}}
+   ```
+3. If you only want to verify an element **exists/is visible** — use a UI/UX scenario with **no `When`** (just `Given` + `Then`)
+4. If the result of an action is **unknown or uncertain** (e.g., what appears after filling a search, what dialog opens after click), either **explore via MCP first** to see the actual result, or **mark the scenario `@manual`**. Never guess the result — wrong assertions cause test failures that waste fix cycles.
+5. Scenario **name must match the actual assertion**, not the action. "Fill searchbox shows search results" must assert search results — not field value.
+
+## Quality Review Checklist (9 checks, auto-fix on detection)
+
+After generating scenarios, review every scenario against these checks. **If an issue is detected, fix it immediately** — do not just flag it.
+
+### 1. Redundant scenarios
+
+**Problem:** Two scenarios test the same element with overlapping assertions.
+```gherkin
+# REDUNDANT: VP-UI-009 and VP-UI-010 both test CTA button
+Scenario: CTA button is visible      → Then see [cta] button
+Scenario: CTA button shows text      → Then see [cta] button with {{text}}
+```
+**Fix:** Keep only the stronger assertion (`with {{text}}` implies visibility). Remove the weaker one.
+
+### 2. Misclassified viewpoint
+
+**Problem:** A scenario classified in the wrong viewpoint category.
+
+**Classification rules:**
+- **UI/UX** = Given + Then asserting **static, always-the-same** defaults (layout, placeholder text, initial state on first-ever load)
+- **Logic** = Given + When + Then (action causes a result), OR Given + Then asserting **behavior-dependent state** (persisted values, dynamic content, conditional defaults)
+
+**Key distinction:** If the element's state depends on **previous user interaction, saved preferences, or business rules** — it's Logic even without a `When`, because it verifies behavior, not layout.
+
+```gherkin
+# UI/UX — static default, always the same for every user
+Given User is on [Settings] page
+Then User see [Language] dropdown with {{default_language}}
+
+# Logic — checkbox remembers last user choice (persisted state)
+Given User is on [Settings] page
+Then User see [Newsletter] checkbox is checked
+
+# Logic — empty state text depends on business rule (no data yet)
+Given User is on [Orders] page
+Then User see [empty state] text with {{no_orders_message}}
+```
+
+**Fix:** Check whether the asserted state is truly static (same for all users, all times) or depends on data/behavior. Move accordingly.
+
+### 3. Dynamic/data-dependent content
+
+**Problem:** Asserting content that depends on live data which may change.
+```gherkin
+# FRAGILE: "Attachment 1" only exists if first card has an attachment
+Scenario: Card shows attachment image
+  Then User see [Attachment 1] image
+```
+**Fix:** Mark as `@manual` with a comment explaining the data dependency.
+
+### 4. Duplicate across sections
+
+**Problem:** Security scenario has identical steps to a UI scenario.
+```gherkin
+# VP-UI-006 and VP-SEC-002 are identical
+Scenario: VP-UI-006 User profile button is visible
+Scenario: VP-SEC-002 Authenticated user sees profile button
+```
+**Fix:** Remove the duplicate. Security scenarios should test **auth boundaries** (e.g., `@no-auth` → redirect), not re-test visibility.
+
+### 5. "Enabled" state on always-enabled elements
+
+**Problem:** Testing `is enabled` on elements that have no disabled state in the application.
+```gherkin
+# BAD: this button is never disabled — the assertion adds no value
+Then User see [Home] button is enabled
+```
+**Fix:** Remove. Only assert `is enabled` or `is disabled` when the element **actually toggles** between states based on conditions (e.g., form validity, permissions).
+
+### 6. Exact match on dynamic counters/numbers
+
+**Problem:** Using exact match (`with {{value}}`) on data that changes (counters, totals, timestamps).
+```gherkin
+# FRAGILE: "+61 KUDOS" changes when new kudos are sent
+Then User see [kudos count] text with {{kudos_count}}
+```
+**Fix:** Use partial match (`text contains`) with a stable keyword:
+```gherkin
+Then User see [kudos count] text contains {{kudos_count_keyword}}
+```
+
+### 7. Current active page link
+
+**Problem:** Testing visibility of a nav link pointing to the current page.
+```gherkin
+# LOW VALUE: we are ON /kudos, Sun* Kudos link is always there
+Scenario: Nav link Sun Kudos is visible
+  Given User is on [kudos] page
+  Then User see [Sun* Kudos] link
+```
+**Fix:** Remove or replace with active state test.
+
+### 8. Test-data completeness
+
+**Problem:** Feature file references `{{variable}}` but the corresponding key is missing in `test-data.yaml`.
+```gherkin
+# Feature uses {{login_error}} but test-data.yaml has no "login_error" key
+When User fill [Email] field with {{invalid_email}}
+And User click [Submit] button
+Then User see [error] message with {{login_error}}
+```
+**Fix:** After generation, verify every `{{variable}}` in the `.feature` file has a matching entry in `test-data.yaml`. Add missing entries with realistic values. This is a **mandatory post-generation check** — missing test data causes compile failures.
+
+### 9. Negative/boundary coverage
+
+**Problem:** All scenarios are happy-path. No validation, error, or boundary cases exist.
+```gherkin
+# BAD: only tests successful login — what about invalid credentials?
+Scenario: VP-LOGIC-001 User logs in successfully
+  Given User is on [Login] page
+  When User fill [Email] field with {{valid_email}}
+  And User fill [Password] field with {{valid_password}}
+  And User click [Submit] button
+  Then User see [Dashboard] page
+```
+**Fix:** For every form/input section, ensure at least one scenario covers:
+- **Required field empty** → validation message appears
+- **Invalid format** (email, phone, etc.) → format error appears
+- **Boundary values** (max length, min value) → when relevant
+
+If specific error messages are unknown, mark validation scenarios `@manual` rather than omitting them entirely.

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

@@ -7,12 +7,13 @@ user-invocable: false
 ## Standard Syntax
 
 ```
-[Keyword] User <Action> [Target Name] <Target Type> <with {{Value}}> <is State>
+[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
 
@@ -88,8 +89,8 @@ User see [message text] alert                    # assert dialog message
 ### 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
@@ -112,11 +113,11 @@ User switch to [T] frame                         # enter iframe
 User switch to [main] frame                      # exit iframe
 ```
 
-### Assertions (6 verify patterns)
+### Assertions (8 verify patterns)
 
 ```
 # 1. Visibility
-User see [T] message                             # visible (default)
+User see [T] message                             # visible (default — NEVER add "is visible")
 User see [T] modal is hidden                     # hidden
 
 # 2. Text Content (exact full match — toHaveText)
@@ -140,26 +141,44 @@ 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. Count
+# 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
 
-# 7. Page Context
+# 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`
@@ -246,7 +265,7 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 |---|---|---|
 | 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` |
+| 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` |

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.
@@ -188,54 +206,102 @@ Many elements don't need a YAML entry — sungen auto-infers from the Gherkin la
 
 ---
 
-### Fix Loop on Test Failure (Batched Strategy)
+### Proactive Selector Validation (before running tests)
 
-Running all tests every iteration is slow. Use a batched approach to fix faster:
+**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;
 ```
-1. INITIAL RUN — run ALL tests, collect full failure list
-     npx playwright test <spec> --reporter=line
 
-2. BATCHED FIX LOOP (max 5 attempts):
-     a. Read test output → group failures by root cause:
-        - Same selector broken → 1 fix covers many tests
-        - Same error type (strict mode, timeout, text mismatch)
-     b. Fix selectors.yaml or test-data.yaml for current batch
+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 previously-failing tests (max 20):
-        npx playwright test <spec> --grep "VP-UI-001|VP-UI-002|VP-VAL-001" --reporter=line
-     e. If batch passes → pick next batch of remaining failures
-     f. If batch still fails → fix and retry (counts toward max 5)
+     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)
 
-3. FINAL CONFIRMATION — run ALL tests once:
+5. FINAL CONFIRMATION — after all batches pass, run ALL tests once:
      npx playwright test <spec> --reporter=line
      This catches regressions from selector changes.
 
-4. If still failing after 5 fix attempts → ask user about direct .spec.ts fix
+6. If still failing after 5 fix attempts per batch → ask user about direct .spec.ts fix
 ```
 
-#### Building the `--grep` pattern
+#### Building batch `--grep` patterns
 
-Extract scenario names from the failure output and join with `|`:
+Extract scenario names and batch them:
 ```bash
-# Example: re-run only 3 failing tests
-npx playwright test <spec> --grep "VP-VAL-001|VP-VAL-002|VP-VAL-003" --reporter=line
-```
+# Batch 1: first 20
+npx playwright test <spec> --grep "VP-UI-001|VP-UI-002|...|VP-UI-020" --reporter=line
 
-- Max 20 test names per `--grep` to keep the pattern manageable
-- If >20 failures share the same root cause, fix the cause and run the first 20 to verify
+# 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 (inputs have no text)
+- **Same assertion** — e.g., all `toHaveText` on inputs fail → change Gherkin pattern
 
 Fix the root cause first, verify with the batch, then move on.
 
-**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.
-
 ---
 
 ### Key Rules (from sungen-selector-keys)