@sun-asterisk/sungen 2.2.3 → 2.3.1

package/src/orchestrator/templates/ai-instructions/claude-skill-tc-generation.md

@@ -33,6 +33,46 @@ For options 1 and 2:
 For option 3:
 - Overwrite both `.feature` and `test-data.yaml` completely
 
+### Requirements-Driven Generation
+
+When `qa/screens/<screen>/requirements/` exists, use it as the **primary source** for test case generation. This produces higher quality tests because requirements contain exact validation messages, field constraints, business rules, and states.
+
+#### Reading Requirements
+
+1. **`spec.md`** (primary) — structured screen specification:
+   - **Sections** → map directly to test case sections
+   - **Fields table** → generate boundary value tests (min/max constraints), required field tests, format tests
+   - **Validation Rules table** → generate exact assertion tests using the error messages as `{{test_data}}` values
+   - **Actions table** → generate interaction tests (click, submit, navigate)
+   - **States table** → generate state transition tests (loading, error, success, disabled)
+   - **Business Rules** → generate logic tests (limits, permissions, conditional behavior)
+   - **Accessibility** → generate tab-order and aria tests
+
+2. **`ui/`** (supplementary) — screenshots, mockups, design images:
+   - Read images to understand layout, element positions, visual states
+   - Cross-reference with spec.md — identify elements visible in UI but missing from spec
+   - Use for UI/UX viewpoint tests (element visibility, placement, responsive)
+
+3. **`notes.md`** (supplementary) — free-form edge cases, decisions, known issues:
+   - Extract edge cases → add to test coverage
+   - Flag known issues → add TODO scenarios
+
+#### How Requirements Improve Each Viewpoint
+
+| Viewpoint | Without Requirements | With Requirements |
+|-----------|---------------------|-------------------|
+| **UI/UX** | "see [Field] is visible" (generic) | "see [Field] field" + verify label, placeholder, default from spec |
+| **Validation** | "submit empty → see error" (vague) | "submit empty email → see {{email_required_error}}" with exact message from spec |
+| **Logic** | Based on observed page behavior | Business rules drive specific tests (lockout after N attempts, session expiry) |
+| **Security** | Generic injection tests | Role-based tests from auth requirements, permission-specific scenarios |
+
+#### Merging Requirements + Live Page
+
+If the user also explores the live page:
+- **Verify** spec.md against actual page — flag mismatches (e.g., field in spec but not on page)
+- **Supplement** — discover elements on page not in spec (e.g., footer links, tooltips)
+- **Exact text** — capture actual placeholder text, button labels, error messages from live page and update test-data accordingly
+
 ### Page Exploration & Auth
 
 Use Playwright MCP to explore the live page. If the page requires authentication:
@@ -55,26 +95,7 @@ Use Playwright MCP to explore the live page. If the page requires authentication
 
 #### 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 (generated during make-test)
-user detail:
-  type: 'page'
-  value: '/admin/users/de42d800-0f5a-490e-9dcf-344fedbd34a5'
-```
-
-```gherkin
-Scenario: VP-UI-001 User detail displays name
-  Given User is on [User Detail] page
-  And User wait for [User Name] heading is visible
-  Then User see [User Name] heading with {{user_name}}
-```
-
-Note: the selector uses a hardcoded ID from the live page. If the record is deleted, update the ID in `selectors.yaml`.
+For screens like `/admin/users/:id` or `/products/:slug`, write Gherkin normally (`User is on [User Detail] page`). The real ID will be resolved during `/sungen:make-test` when selectors are generated from the live page. See `sungen-selector-fix` skill for details.
 
 ### Section-Focused Approach
 
@@ -113,71 +134,58 @@ For each selected section, generate **20+ scenarios per applicable viewpoint**.
 
 Present a test plan summary and wait for user confirmation before generating files.
 
+### Assertion & Review Quality
+
+For assertion quality rules, action-result coherence rules, and the 9-point quality review checklist, see the `sungen-gherkin-review` skill. That skill is auto-loaded during the self-review step.
+
 ### Viewpoint Categories
 
 | VP Category | Description |
 |---|---|
-| **UI/UX** | Default appearance, element visibility, default states |
-| **Validation** | Input validation, error messages, edge cases. **Must explore live page via MCP to capture actual error messages before writing tests. Use `User see {{error_var}}` pattern — never assert just "is visible".** |
+| **UI/UX** | Default appearance, default values/text, default states. Group related elements per scenario. |
+| **Validation** | Input validation, error messages, edge cases. **Assert exact error messages via `User see [T] with {{error_var}}`** — store texts in test-data.yaml. |
 | **Logic** | Business logic, interactions, state changes |
 | **Security** | Auth guards, injection, permission checks |
 
 ### Coverage Checklist per Section Pattern
 
-Apply the relevant checklist based on the section pattern:
-
 #### Form sections
-- **UI/UX**: All fields visible, labels correct, default values, placeholder text, required indicators
-- **Validation**: Empty submit, each required field empty, invalid format (email, phone, URL), min/max length, special chars, unicode, XSS, SQL injection, whitespace-only, boundary values — **assert exact error messages via `User see {{error_var}}`**, store texts in test-data.yaml
-- **Logic**: Successful submit, submit with all optional fields, edit existing record, cancel resets form, field dependencies (show/hide), auto-complete, date range validation
-- **Security**: CSRF protection, unauthorized submit, role-based field visibility, input sanitization
+- **UI/UX**: All fields + labels + default values in 1-2 grouped scenarios. Default states (button enabled/disabled, checkbox unchecked). Placeholder text via `with {{placeholder}}`.
+- **Validation**: Empty submit → verify all error messages. Each required field empty individually → verify specific error. Invalid formats → verify specific error. Boundary values (min/max length). Special chars, unicode, XSS, SQL injection.
+- **Logic**: Successful submit → verify success state/redirect. Edit existing → verify pre-filled values. Cancel → verify form resets. Field dependencies (show/hide).
+- **Security**: Unauthorized submit, role-based field visibility, input sanitization
 
 #### Data Table sections
-- **UI/UX**: All columns visible, column headers, row data displays correctly, empty state, loading state, action buttons visible
-- **Validation**: N/A (read-only) or inline edit validation
-- **Logic**: Sort ascending/descending per sortable column, filter by each column, search within table, row action menu (edit/delete/view), bulk select, bulk action, row click navigation, column resize
-- **Security**: Cannot access other users' data, action permissions per role, data not exposed in DOM
+- **UI/UX**: All column headers in one scenario. Row data displays with correct values. Empty state message. Action buttons per row.
+- **Logic**: Sort ascending/descending. Filter by column. Search. Row actions (edit/delete/view). Bulk select + action.
+- **Security**: Action permissions per role
 
 #### Search & Filter sections
-- **UI/UX**: Search field visible, filter buttons visible, clear button state
-- **Validation**: Empty search, special chars, SQL injection, XSS, very long text, unicode/emoji, whitespace, partial match, case insensitive
-- **Logic**: Apply single filter, combine multiple filters, clear single filter, clear all filters, search + filter combined, filter persists across pagination, no results state
-- **Security**: Injection via search, injection via filter params
+- **UI/UX**: Search field + filter buttons + clear button states in one scenario
+- **Validation**: Empty search, special chars, injection, long text, unicode
+- **Logic**: Apply/clear single filter, combine filters, no results state with message
+- **Security**: Injection via search/filter params
 
 #### Pagination sections
-- **UI/UX**: Page indicator visible, previous disabled on page 1, next enabled
-- **Logic**: Next page, previous page, navigate to last page, boundary (first/last), page indicator updates, data refreshes on navigation
-- **Security**: Filters persist across pages, search persists, cannot access page beyond max
+- **UI/UX**: Page indicator + button states (previous disabled on page 1, next enabled)
+- **Logic**: Navigate pages, boundary behavior, indicator updates
 
 #### Modal / Dialog sections
-- **UI/UX**: Modal opens, close button visible, overlay visible, form fields inside modal
-- **Validation**: Submit empty form in modal, field validation inside modal
-- **Logic**: Open modal, close with X, close with Escape, close with overlay click, submit success closes modal, submit error keeps modal open
-- **Security**: Cannot open unauthorized modals, CSRF on modal submit
-
-#### Card Grid / List sections
-- **UI/UX**: Cards display all expected fields (title, image, description, metadata), empty state, loading state
-- **Logic**: Click card navigates to detail, load more / infinite scroll, card action buttons (like, share, delete), responsive layout
-- **Security**: User-generated content sanitized, cannot access other users' cards
-
-#### Carousel / Slider sections
-- **UI/UX**: Arrows visible, indicators visible, current slide highlighted
-- **Logic**: Next slide, previous slide, wrap at end, auto-play, indicator click navigates, swipe gesture
-- **Security**: N/A
+- **UI/UX**: Modal content + all fields + close button in one scenario
+- **Validation**: Field validation inside modal with exact errors
+- **Logic**: Open/close methods (X, Escape, overlay), submit success/error behavior
 
 #### Tabs / Accordion sections
-- **UI/UX**: All tabs visible, active tab highlighted, default tab selected
-- **Logic**: Switch tabs, content updates per tab, deep link to tab, accordion expand/collapse, only one accordion open at a time
-- **Security**: Tab content respects permissions
+- **UI/UX**: All tab labels + active tab highlighted + default tab content
+- **Logic**: Switch tabs → verify content changes, accordion expand/collapse
 
 ### General Coverage Dimensions (aim for 20+ total per viewpoint)
 
-**Happy paths (3-5):** Standard flow, all optional fields, minimum required
-**Edge cases (5-8):** Empty, max length, special chars, unicode/CJK/emoji, whitespace, leading/trailing spaces, overflow
-**Boundary values (3-5):** At min/max limit, one above/below, zero/null
-**Negative cases (3-5):** Invalid format, missing required, wrong type, injection attempts
-**State transitions (2-4):** Before/after action, undo, cancel mid-flow
-**Combinatorial (2-4):** Multiple invalid fields, valid+invalid combos, different roles
+**Happy paths (3-5):** Standard flow with full assertion of result state
+**Edge cases (5-8):** Empty, max length, special chars, unicode, whitespace, boundary values
+**Negative cases (3-5):** Invalid format, missing required, wrong type, exact error messages
+**State transitions (2-4):** Before/after action, verify both old and new state
+**Combinatorial (2-4):** Multiple invalid fields, valid+invalid combos
 
 ### SPA Wait-For Steps
 
@@ -208,24 +216,37 @@ Feature: <Screen> Screen
   # Section: Create User Form
   # ============================================================
 
-  # --- UI/UX (20+) ---
+  # --- UI/UX ---
 
-  Scenario: VP-UI-001 Name field is visible
-    ...
+  Scenario: VP-UI-001 Form displays all fields with correct defaults
+    Given User is on [Create User] page
+    Then User see [Create User] heading with {{form_title}}
+    And User see [Name] field
+    And User see [Email] field
+    And User see [Role] dropdown with {{default_role}}
+    And User see [Submit] button is disabled
+    And User see [Cancel] button is enabled
 
-  # --- Validation (20+) ---
+  # --- Validation ---
 
-  Scenario: VP-VAL-001 Submit with empty name
-    ...
+  Scenario: VP-VAL-001 Submit with all empty fields shows errors
+    Given User is on [Create User] page
+    When User click [Submit] button
+    Then User see [Name error] message with {{name_required_error}}
+    And User see [Email error] message with {{email_required_error}}
 
   # ============================================================
   # Section: User Table
   # ============================================================
 
-  # --- UI/UX (20+) ---
+  # --- UI/UX ---
 
-  Scenario: VP-UI-025 Table displays all columns
-    ...
+  Scenario: VP-UI-010 Table displays all columns
+    Given User is on [Users] page
+    Then User see [Name] column in [Users] table
+    And User see [Email] column in [Users] table
+    And User see [Status] column in [Users] table
+    And User see [Actions] column in [Users] table
 ```
 
 **Naming convention:** `VP-<CATEGORY>-<NNN>` prefix in Scenario name.

package/src/orchestrator/templates/ai-instructions/copilot-cmd-add-screen.md

@@ -24,15 +24,23 @@ Run with #tool:terminal:
 sungen add --screen ${input:screen} --path ${input: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/${input: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, tell the user to run `/sungen-make-tc ${input:screen}`.
+If yes → **tell the user to run `/sungen-make-tc ${input:screen}` as a separate command.** Do NOT attempt to generate test cases yourself in this session — the `make-tc` command 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.
 
-### 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`
+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` to create test cases
 - Run `/sungen-make-test` to generate selectors, compile, and run tests

package/src/orchestrator/templates/ai-instructions/copilot-cmd-make-tc.md

@@ -20,9 +20,18 @@ You are a **Senior QA Engineer**. You structure test cases by viewpoint categori
 
 1. Verify `qa/screens/${input:screen}/` exists. If not → run `/sungen-add-screen` first.
 2. Check if `.feature` already has scenarios. If yes → summarize existing coverage and ask: **1) Add new sections**, **2) Add viewpoints to existing sections**, or **3) Replace all**. See `sungen-tc-generation` skill for update mode details.
-3. Ask the user: "How should I explore the page? **1) Live page** (via Playwright MCP) or **2) Static designs** (screenshots, Figma)?". If live page, explore via #tool:playwright (see [copilot-instructions.md](../../copilot-instructions.md) for MCP rules). If auth needed, ask user to log in manually.
-4. Identify screen sections → ask user which to focus on (per `sungen-tc-generation` skill). Present sections as a numbered list and let user pick.
-5. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills.
-6. Show summary → next: `/sungen-make-test ${input:screen}`
+3. **Read requirements** — check `qa/screens/${input: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):
+   - Ask: "How should I explore the page? **1) Live page** (via Playwright MCP) or **2) Static designs** (screenshots, Figma) or **3) Skip** (if requirements are sufficient)?"
+   - If live page, explore via #tool:playwright (see [copilot-instructions.md](../../copilot-instructions.md) for MCP rules). If auth needed, ask user to log in manually.
+   - If exploring, verify and supplement requirements — flag any discrepancies found.
+5. Identify screen sections → ask user which to focus on (per `sungen-tc-generation` skill). When requirements exist, use the "Requirements-Driven Generation" strategy. Present sections as a numbered list and let user pick.
+6. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills.
+7. **Self-review** — re-read the `.feature` file and apply the full **`sungen-gherkin-review` skill**: assertion quality rules (4 rules), action-result coherence (5 rules), and the 9-point quality checklist. **Auto-fix any issues found**, then re-read to verify.
+8. Show summary → next: `/sungen-make-test ${input:screen}`
 
 **No selectors.yaml** — selectors are generated during `/sungen-make-test`.

package/src/orchestrator/templates/ai-instructions/copilot-cmd-make-test.md

@@ -19,16 +19,14 @@ You are a **Senior Developer** specialized in Playwright test debugging. You gen
 ## Steps
 
 1. Verify `qa/screens/${input:screen}/` has `.feature` + `test-data.yaml`. If not → run `/sungen-make-tc` first.
-2. Explore live page via #tool:playwright to generate `selectors.yaml` (per `sungen-selector-fix` skill).
-3. Compile with #tool:terminal: `sungen generate --screen ${input:screen}`
-4. **Initial run** — run ALL tests to get the full failure picture:
-   `npx playwright test specs/generated/${input:screen}/*.spec.ts --reporter=line`
-5. **Batched fix loop** (max 5 attempts) — see `sungen-selector-fix` skill for details:
-   - Group failures by root cause (same selector, same error type)
-   - Fix selectors/test-data for the current batch
-   - Recompile, then re-run ONLY the previously-failing tests (max 20 at a time via `--grep`)
-   - If the batch passes, pick the next batch of remaining failures
-   - Repeat until no failures remain or max attempts reached
-6. **Final confirmation** — run ALL tests once to ensure no regressions.
+2. **Generate selectors** — explore live page via #tool:playwright, build `selectors.yaml` (per `sungen-selector-fix` skill).
+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** with #tool:terminal: `sungen generate --screen ${input:screen}`
+5. **Batched test run** — run tests in batches of 20 via `--grep`:
+   `npx playwright test specs/generated/${input: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/src/orchestrator/templates/ai-instructions/github-skill-sungen-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/src/orchestrator/templates/ai-instructions/github-skill-sungen-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` |