@sun-asterisk/sungen 2.4.1 → 2.4.2

package/dist/cli/index.js

@@ -16,7 +16,7 @@ async function main() {
     program
         .name('sungen')
         .description('Deterministic E2E Test Compiler — Gherkin + Selectors → Playwright')
-        .version('2.4.1');
+        .version('2.4.2');
     // Global options
     program
         .option('-v, --verbose', 'Enable verbose logging');

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

@@ -247,3 +247,39 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | 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}}` |
+| Using Background | `Background: Given User is on...` | Use `@steps` + `@extend` instead |
+| `is on` after When | `When ... And User is on [X] dialog` | `And User see [X] dialog` or separate Given |
+
+## Background vs @steps/@extend
+
+**Do NOT use `Background:` block.** Use `@steps` + `@extend` instead.
+
+**Why:**
+- `Background` runs before EVERY scenario but cannot set dialog/frame scope correctly
+- `Background` with `When` + `And User is on [X] dialog` creates keyword mismatch (`is on` = Given, not When)
+- `@steps` + `@extend` gives explicit control: base steps run Given→When, extending scenario starts with `Given User is on [X] dialog` (correct scope setup)
+
+**Wrong:**
+```gherkin
+Background:
+  Given User is on [Kudos] page
+  When User click [Open] button
+  And User is on [Modal] dialog    ← keyword mismatch
+
+Scenario: VP-UI-001 Title visible
+  Then User see [Title] heading
+```
+
+**Correct:**
+```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
+```

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

@@ -68,25 +68,38 @@ And User wait for [Page Title] heading is visible
 
 **Feature file** — `qa/screens/<screen>/features/<screen>.feature`
 
+**Never use `Background:`.** Use `@steps` + `@extend` for shared setup (see `sungen-gherkin-syntax` skill).
+
 ```gherkin
 @auth:role
 Feature: <Screen> Screen
 
+  # Shared setup — use @steps, not Background
+  @steps:open_form
+  Scenario: Open form
+    Given User is on [Screen] page
+    And User wait for [Screen Title] heading is visible
+    When User click [Create] button
+    Then User see [Form] dialog
+
   # ============================================================
   # Section: Create User Form
   # ============================================================
 
   # --- UI/UX ---
 
+  @extend:open_form
   Scenario: VP-UI-001 Form displays all fields with correct defaults
-    Given User is on [Create User] page
+    Given User is on [Form] dialog
     Then User see [Name] field
     And User see [Email] field
     And User see [Submit] button is disabled
 
   # --- Validation ---
 
+  @extend:open_form
   Scenario: VP-VAL-001 Submit with all empty fields shows errors
+    Given User is on [Form] dialog
     When User click [Submit] button
     Then User see [Name error] message with {{name_required_error}}
 

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

@@ -1,6 +1,6 @@
 ---
 name: sungen-gherkin-syntax
-description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Use this when writing or editing .feature, selectors.yaml, or test-data.yaml files.'
+description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Auto-loaded when writing .feature, selectors.yaml, or test-data.yaml.'
 user-invocable: false
 ---
 
@@ -247,3 +247,39 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | 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}}` |
+| Using Background | `Background: Given User is on...` | Use `@steps` + `@extend` instead |
+| `is on` after When | `When ... And User is on [X] dialog` | `And User see [X] dialog` or separate Given |
+
+## Background vs @steps/@extend
+
+**Do NOT use `Background:` block.** Use `@steps` + `@extend` instead.
+
+**Why:**
+- `Background` runs before EVERY scenario but cannot set dialog/frame scope correctly
+- `Background` with `When` + `And User is on [X] dialog` creates keyword mismatch (`is on` = Given, not When)
+- `@steps` + `@extend` gives explicit control: base steps run Given→When, extending scenario starts with `Given User is on [X] dialog` (correct scope setup)
+
+**Wrong:**
+```gherkin
+Background:
+  Given User is on [Kudos] page
+  When User click [Open] button
+  And User is on [Modal] dialog    ← keyword mismatch
+
+Scenario: VP-UI-001 Title visible
+  Then User see [Title] heading
+```
+
+**Correct:**
+```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
+```

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-tc-generation.md

@@ -68,25 +68,38 @@ And User wait for [Page Title] heading is visible
 
 **Feature file** — `qa/screens/<screen>/features/<screen>.feature`
 
+**Never use `Background:`.** Use `@steps` + `@extend` for shared setup (see `sungen-gherkin-syntax` skill).
+
 ```gherkin
 @auth:role
 Feature: <Screen> Screen
 
+  # Shared setup — use @steps, not Background
+  @steps:open_form
+  Scenario: Open form
+    Given User is on [Screen] page
+    And User wait for [Screen Title] heading is visible
+    When User click [Create] button
+    Then User see [Form] dialog
+
   # ============================================================
   # Section: Create User Form
   # ============================================================
 
   # --- UI/UX ---
 
+  @extend:open_form
   Scenario: VP-UI-001 Form displays all fields with correct defaults
-    Given User is on [Create User] page
+    Given User is on [Form] dialog
     Then User see [Name] field
     And User see [Email] field
     And User see [Submit] button is disabled
 
   # --- Validation ---
 
+  @extend:open_form
   Scenario: VP-VAL-001 Submit with all empty fields shows errors
+    Given User is on [Form] dialog
     When User click [Submit] button
     Then User see [Name error] message with {{name_required_error}}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/cli/index.ts

@@ -17,7 +17,7 @@ async function main() {
   program
     .name('sungen')
     .description('Deterministic E2E Test Compiler — Gherkin + Selectors → Playwright')
-    .version('2.4.1');
+    .version('2.4.2');
 
   // Global options
   program

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

@@ -247,3 +247,39 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | 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}}` |
+| Using Background | `Background: Given User is on...` | Use `@steps` + `@extend` instead |
+| `is on` after When | `When ... And User is on [X] dialog` | `And User see [X] dialog` or separate Given |
+
+## Background vs @steps/@extend
+
+**Do NOT use `Background:` block.** Use `@steps` + `@extend` instead.
+
+**Why:**
+- `Background` runs before EVERY scenario but cannot set dialog/frame scope correctly
+- `Background` with `When` + `And User is on [X] dialog` creates keyword mismatch (`is on` = Given, not When)
+- `@steps` + `@extend` gives explicit control: base steps run Given→When, extending scenario starts with `Given User is on [X] dialog` (correct scope setup)
+
+**Wrong:**
+```gherkin
+Background:
+  Given User is on [Kudos] page
+  When User click [Open] button
+  And User is on [Modal] dialog    ← keyword mismatch
+
+Scenario: VP-UI-001 Title visible
+  Then User see [Title] heading
+```
+
+**Correct:**
+```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
+```

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

@@ -68,25 +68,38 @@ And User wait for [Page Title] heading is visible
 
 **Feature file** — `qa/screens/<screen>/features/<screen>.feature`
 
+**Never use `Background:`.** Use `@steps` + `@extend` for shared setup (see `sungen-gherkin-syntax` skill).
+
 ```gherkin
 @auth:role
 Feature: <Screen> Screen
 
+  # Shared setup — use @steps, not Background
+  @steps:open_form
+  Scenario: Open form
+    Given User is on [Screen] page
+    And User wait for [Screen Title] heading is visible
+    When User click [Create] button
+    Then User see [Form] dialog
+
   # ============================================================
   # Section: Create User Form
   # ============================================================
 
   # --- UI/UX ---
 
+  @extend:open_form
   Scenario: VP-UI-001 Form displays all fields with correct defaults
-    Given User is on [Create User] page
+    Given User is on [Form] dialog
     Then User see [Name] field
     And User see [Email] field
     And User see [Submit] button is disabled
 
   # --- Validation ---
 
+  @extend:open_form
   Scenario: VP-VAL-001 Submit with all empty fields shows errors
+    Given User is on [Form] dialog
     When User click [Submit] button
     Then User see [Name error] message with {{name_required_error}}
 

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

@@ -1,6 +1,6 @@
 ---
 name: sungen-gherkin-syntax
-description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Use this when writing or editing .feature, selectors.yaml, or test-data.yaml files.'
+description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Auto-loaded when writing .feature, selectors.yaml, or test-data.yaml.'
 user-invocable: false
 ---
 
@@ -247,3 +247,39 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | 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}}` |
+| Using Background | `Background: Given User is on...` | Use `@steps` + `@extend` instead |
+| `is on` after When | `When ... And User is on [X] dialog` | `And User see [X] dialog` or separate Given |
+
+## Background vs @steps/@extend
+
+**Do NOT use `Background:` block.** Use `@steps` + `@extend` instead.
+
+**Why:**
+- `Background` runs before EVERY scenario but cannot set dialog/frame scope correctly
+- `Background` with `When` + `And User is on [X] dialog` creates keyword mismatch (`is on` = Given, not When)
+- `@steps` + `@extend` gives explicit control: base steps run Given→When, extending scenario starts with `Given User is on [X] dialog` (correct scope setup)
+
+**Wrong:**
+```gherkin
+Background:
+  Given User is on [Kudos] page
+  When User click [Open] button
+  And User is on [Modal] dialog    ← keyword mismatch
+
+Scenario: VP-UI-001 Title visible
+  Then User see [Title] heading
+```
+
+**Correct:**
+```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
+```

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

@@ -68,25 +68,38 @@ And User wait for [Page Title] heading is visible
 
 **Feature file** — `qa/screens/<screen>/features/<screen>.feature`
 
+**Never use `Background:`.** Use `@steps` + `@extend` for shared setup (see `sungen-gherkin-syntax` skill).
+
 ```gherkin
 @auth:role
 Feature: <Screen> Screen
 
+  # Shared setup — use @steps, not Background
+  @steps:open_form
+  Scenario: Open form
+    Given User is on [Screen] page
+    And User wait for [Screen Title] heading is visible
+    When User click [Create] button
+    Then User see [Form] dialog
+
   # ============================================================
   # Section: Create User Form
   # ============================================================
 
   # --- UI/UX ---
 
+  @extend:open_form
   Scenario: VP-UI-001 Form displays all fields with correct defaults
-    Given User is on [Create User] page
+    Given User is on [Form] dialog
     Then User see [Name] field
     And User see [Email] field
     And User see [Submit] button is disabled
 
   # --- Validation ---
 
+  @extend:open_form
   Scenario: VP-VAL-001 Submit with all empty fields shows errors
+    Given User is on [Form] dialog
     When User click [Submit] button
     Then User see [Name error] message with {{name_required_error}}