@sun-asterisk/sungen 2.4.0 → 2.4.2

package/src/generators/gherkin-parser/index.ts

@@ -5,6 +5,15 @@ import fs from 'fs';
 import path from 'path';
 import { SelectorResolver } from '../test-generator/utils/selector-resolver';
 
+export interface DataTableRow {
+  cells: string[]; // Cell values in order
+}
+
+export interface ParsedDataTable {
+  headers: string[]; // First row = column headers
+  rows: DataTableRow[]; // Remaining rows = data rows
+}
+
 export interface ParsedStep {
   keyword: string; // Given, When, Then, And, But
   text: string; // Original step text
@@ -16,6 +25,7 @@ export interface ParsedStep {
   featurePath?: string; // NEW: Feature path for page type (e.g., "/", "/dashboard")
   parentRef?: string; // Parent scope reference: "in [Parent Name] parentType" → parentRef = "Parent Name"
   parentType?: string; // Parent scope type: table, list, section, dialog, form
+  dataTable?: ParsedDataTable; // Inline data table (Cucumber DataTable syntax)
 }
 
 export interface ParsedScenario {
@@ -172,6 +182,18 @@ export class GherkinParser {
       nth = SelectorResolver.extractNthFromStep(afterElement);
     }
 
+    // Extract inline data table (Cucumber DataTable syntax)
+    let dataTable: ParsedDataTable | undefined;
+    if (step.dataTable && step.dataTable.rows && step.dataTable.rows.length >= 2) {
+      const rows = step.dataTable.rows;
+      dataTable = {
+        headers: rows[0].cells.map((cell: any) => cell.value),
+        rows: rows.slice(1).map((row: any) => ({
+          cells: row.cells.map((cell: any) => cell.value),
+        })),
+      };
+    }
+
     return {
       keyword: step.keyword.trim(),
       text: step.text, // Preserve original text (with parent scoping) for pattern matching
@@ -182,6 +204,7 @@ export class GherkinParser {
       nth,
       parentRef,
       parentType,
+      dataTable,
     };
   }
 

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/table-match-data.hbs

@@ -0,0 +1,15 @@
+{{~#if isGiven~}}
+{
+  const rows = {{> locator}}.locator('tbody').getByRole('row');
+{{#each assertions}}
+  {{this}}
+{{/each~}}
+}
+{{~else~}}
+{
+  const rows = {{> locator}}.locator('tbody').getByRole('row');
+{{#each assertions}}
+  {{this}}
+{{/each~}}
+}
+{{~/if}}

package/src/generators/test-generator/patterns/index.ts

@@ -74,7 +74,8 @@ export class PatternRegistry {
       const resolved = pattern.resolver(step, context);
 
       // Auto-inject parent scoping if step has parentRef
-      if (step.parentRef && step.parentType) {
+      // Skip for table-* patterns — they resolve the table name internally from step text
+      if (step.parentRef && step.parentType && !pattern.name.startsWith('table-')) {
         resolved.data.parentLocator = PatternRegistry.resolveParentLocator(
           step.parentRef, step.parentType, context
         );

package/src/generators/test-generator/patterns/table-patterns.ts

@@ -2,7 +2,7 @@
  * Table Patterns
  * Handles: table row assertions, table cell lookups, actions in table rows
  *
- * Syntax (v2.3 final):
+ * Syntax (v2.4 final):
  * - User see [Col] column in [Table] table                             # column exists
  * - User see [Ref] row in [Table] table with {{value}}                 # row exists (enters row scope)
  * - User see [Ref] row in [Table] table with {{value}} is hidden       # row hidden
@@ -10,6 +10,9 @@
  * - User see [Table] table is empty                                    # empty table
  * - User see [Col] column with {{value}}                               # cell value (row scoped — handled in step-mapper)
  * - User click [Act] button in [Table] table with {{filter}}           # action in row
+ * - User see [Table] table match data:                                 # exact table match with inline DataTable
+ *       | Header1    | Header2    |
+ *       | {{value1}} | {{value2}} |
  */
 
 import { StepPattern, PatternContext } from './types';
@@ -219,4 +222,58 @@ export const tablePatterns: StepPattern[] = [
     },
     priority: 17,
   },
+
+  // "User see [Table] table match data:" — filter-based table match with inline DataTable
+  // First row = headers, remaining rows = expected data
+  // Uses filter({ hasText }) per row — resilient to data changes, row ordering, extra rows
+  {
+    name: 'table-match-data',
+    matcher: (step) => {
+      return step.elementType === 'table' &&
+             /\btable\s+match\s+data\b/i.test(step.text) &&
+             !!step.dataTable;
+    },
+    resolver: (step, context) => {
+      const resolved = context.selectorResolver.resolveSelector(
+        step.selectorRef!, context.featureName, 'table', step.nth
+      );
+
+      const dataTable = step.dataTable!;
+
+      // Resolve {{variable}} references in cell values
+      const resolvedRows = dataTable.rows.map(row => ({
+        cells: row.cells.map(cell => {
+          const varMatch = cell.match(/^\{\{([a-z0-9\-\.\_]+)\}\}$/i);
+          if (varMatch) {
+            return context.dataResolver.resolveData(varMatch[1], context.featureName);
+          }
+          return cell;
+        }),
+      }));
+
+      // Pre-compute filter-based assertion lines
+      // For each expected row: chain .filter({ hasText }) for all cell values, then assert visible
+      const assertions: string[] = [];
+      for (const row of resolvedRows) {
+        const filters = row.cells
+          .map(cell => `.filter({ hasText: '${cell.replace(/'/g, "\\'")}' })`)
+          .join('');
+        assertions.push(
+          `await expect(rows${filters}).toBeVisible();`
+        );
+      }
+
+      const isGiven = isGivenContext(context);
+      return {
+        templateName: 'table-match-data',
+        data: {
+          ...resolved,
+          assertions,
+          isGiven,
+        },
+        comment: `${isGiven ? 'Wait' : 'Assert'} ${step.selectorRef} table contains ${resolvedRows.length} expected row(s)`,
+      };
+    },
+    priority: 20, // Higher than other table patterns to match first
+  },
 ];

package/src/orchestrator/templates/ai-instructions/claude-cmd-run-test.md

@@ -1,29 +1,32 @@
 ---
 name: run-test
-description: 'Generate selectors, compile, and run Playwright tests — auto-fixes selectors on failure'
+description: 'Compile and run Playwright tests — auto-fixes selectors on failure'
 argument-hint: [screen-name]
 allowed-tools: Read, Grep, Bash, Glob, Edit, AskUserQuestion
 ---
 
 ## Role
 
-You are a **Senior Developer** specialized in Playwright test debugging. You generate selectors from live pages, diagnose test failures, and fix selectors/test-data using the `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills.
+You are a **Senior Developer**. Use `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills.
 
 ## Parameters
 
 Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 
-## Steps
-
-1. Verify `qa/screens/<screen>/` has `.feature` + `test-data.yaml`. If not → `/sungen:create-test` first.
-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.
+## Phase 1: Compile & Run (no MCP)
+
+1. Verify `qa/screens/<screen>/` has `.feature` + `test-data.yaml`
+2. Ensure `selectors.yaml` has page selector. If missing, ask user for URL path
+3. `sungen generate --screen <screen>`
+4. `npx playwright test specs/generated/<screen>/*.spec.ts --reporter=line`
+5. If all pass → done
+
+## Phase 2: Targeted Fix (only if failures)
+
+6. Parse failures → group by root cause
+7. Navigate to page ONCE via MCP → ONE `browser_snapshot`
+8. Fix broken selectors per `sungen-selector-fix` skill
+9. Recompile → re-run only failing tests
+10. Repeat up to 3 attempts
+11. Final full run for regression check
+12. Still failing → ask user

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

@@ -81,12 +81,12 @@ If `toHaveText` fails on an input → the Gherkin step has wrong target type. Fi
 
 | Symptom | Fix |
 |---|---|
-| Redirect to login page | Auth expired. Tell user: `sungen makeauth <role> --url <baseURL>` |
-| `storageState` file not found | Run `sungen makeauth <role> --url <baseURL>` |
-| Most tests timeout on first step | Auth expired — re-run makeauth |
-| Page shows home instead of target | SPA + expired auth. Re-run makeauth + add `wait for` step |
+| Redirect to login page | Auth expired. Ask user to log in manually via MCP browser |
+| `storageState` file not found | Ask user to log in manually via MCP browser, then save storage state |
+| Most tests timeout on first step | Auth expired — ask user to re-authenticate via MCP browser |
+| Page shows home instead of target | SPA + expired auth. Re-authenticate + add `wait for` step |
 
-**Never run `sungen makeauth` yourself.** Tell the user.
+**Never use `sungen makeauth`.** Always let the user log in manually via the MCP browser.
 
 ---
 

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

@@ -50,7 +50,7 @@ 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 upload [T] uploader with {{f}}              # file upload
+User fill [T] uploader with {{f}}                # file upload
 ```
 
 ### Interaction
@@ -161,10 +161,17 @@ User see [Table] table with {{count}}                           # row count
 User see [Table] table is empty                                 # empty table
 User see [Col] column with {{v}}                                # cell value (row scoped)
 User click [Act] button in [Table] table with {{v}}             # action in row
+User see [Table] table match data:                              # exact table match (inline DataTable)
+    | Header1    | Header2    |
+    | {{value1}} | {{value2}} |
 ```
 
+**Priority**: Use row scope patterns for single-row verification + actions. Use `table match data` only when verifying multiple rows at once.
+
 Row scope: `see [Ref] row in [Table] table with {{v}}` defines `tableRow`. Subsequent `see [Col] column with {{v}}` checks the cell in that row. With `columns` config → exact `nth(index)`, without → `filter({ hasText })`.
 
+Table match data: `see [Table] table match data:` followed by a Cucumber DataTable. First row = headers, remaining rows = expected data. Uses **filter-based matching** — verifies rows containing expected values exist, resilient to data changes, extra rows, and row reordering. Use `{{variable}}` for cell values.
+
 ### States
 
 `hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `sorted ascending` `sorted descending`
@@ -240,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-selector-fix.md

@@ -1,41 +1,51 @@
 ---
 name: sungen-selector-fix
-description: 'Selector generation and fixing strategy — explore live page, generate selectors.yaml, validate, auto-fix. Auto-loaded by run-test command.'
+description: 'Selector fixing strategy — diagnose failures, explore live page targeted, fix broken selectors. Auto-loaded by run-test command.'
 user-invocable: false
 ---
 
-## When to Generate
+## Strategy: Fix Only What Breaks
 
-Selectors are generated during `/sungen:run-test`, NOT during `/sungen:create-test`.
+Most selectors auto-infer from Gherkin element types (see `sungen-selector-keys` skill). Only add YAML entries for selectors that fail during test execution.
+
+**Minimal `selectors.yaml`**: page selectors (required), overrides for elements where auto-infer doesn't work. Never generate a full page catalog upfront.
 
 ---
 
-## Step 1: Authenticate & Snapshot
+## Step 1: Diagnose Failures
 
-1. Read `baseURL` from `playwright.config.ts`
-2. `browser_navigate` to `baseURL`
-3. If redirected to login → ask user to log in manually via MCP browser
-4. Navigate to target page → `browser_snapshot`
+Parse Playwright error output to categorize failures:
 
-**Never use `sungen makeauth`.** Never use `browser_evaluate` to inject cookies.
+| Error pattern | Root cause | Fix target |
+|---|---|---|
+| `No element found` / `strict mode violation` | Selector mismatch | `selectors.yaml` |
+| `toBeVisible` timeout | Wrong name or missing element | `selectors.yaml` |
+| `toHaveText` / `toHaveValue` mismatch | Wrong expected data | `test-data.yaml` |
+| `page.goto` error | Wrong URL | page selector in `selectors.yaml` |
+| `frame` error | Element inside iframe | add `frame` field |
+
+**Group by root cause** — if 5 tests fail because `[Submit]` button has a different name, that's 1 fix, not 5.
+
+**Check `test-results/` first** — Playwright captures failure screenshots automatically. Use these to diagnose before any MCP exploration.
 
 ---
 
-## Step 2: Build Element Catalog
+## Step 2: Targeted MCP Exploration
 
-**Never guess names from Gherkin labels. Copy exact values from snapshot.**
+Only when `test-results/` screenshots are insufficient:
 
-Catalog all accessible elements from snapshot: buttons, links, headings, inputs, regions, images.
+1. Read `baseURL` from `playwright.config.ts`
+2. `browser_navigate` to target page
+3. If redirected to login → ask user to log in manually via MCP browser
+4. Take **ONE** `browser_snapshot` — fix all broken selectors from this single snapshot
 
-Then check for `data-testid` attributes:
-```js
-Array.from(document.querySelectorAll('[data-testid]'))
-  .map(e => ({ testid: e.dataset.testid, tag: e.tagName, text: e.textContent.trim().slice(0, 60) }))
-```
+**Never use `sungen makeauth`.** Never use `browser_evaluate` to inject cookies.
 
 ---
 
-## Step 3: Map Gherkin Labels → Selectors
+## Step 3: Fix Broken Selectors
+
+For each failed selector, find the correct locator from the snapshot:
 
 Selector priority (use first applicable):
 
@@ -50,24 +60,24 @@ Selector priority (use first applicable):
 
 **Exact name rule**: copy name character-for-character from snapshot. Never infer from Gherkin label.
 
-**No accessible name**: use `locator` with CSS/ARIA attribute:
-```yaml
-search field:
-  type: 'locator'
-  value: '[role="searchbox"]'
+Check for `data-testid` attributes if role-based matching fails:
+```js
+Array.from(document.querySelectorAll('[data-testid]'))
+  .map(e => ({ testid: e.dataset.testid, tag: e.tagName, text: e.textContent.trim().slice(0, 60) }))
 ```
 
-**Dynamic content**: never use `type: text` with specific value. Use `testid` or structural `role` + `nth`.
-
-**Multiple matches**: add `nth: 0` for first occurrence.
-
-Auto-infer rules and lookup priority → see `sungen-selector-keys` skill.
+Common fixes:
+- Name mismatch → copy exact name from snapshot
+- Multiple matches → add `nth` or `exact: true`
+- No accessible name → use `testid` or `locator` (CSS)
+- Element in iframe → add `frame` field
+- Dynamic content → use `testid` or structural `role` + `nth`
 
 ---
 
 ## Step 4: Table Selectors
 
-For table patterns using the v2.3 syntax, generate table selectors with `columns` config:
+For table patterns, add table selectors with `columns` config:
 
 ```yaml
 users:
@@ -88,15 +98,6 @@ users:
 
 **How to build `columns`**: count column headers in snapshot (left to right, 0-indexed). Map each `[Col] column` reference from feature file to its index.
 
-**Why**: enables exact cell assertion via `cell.nth(index).toHaveText(value)` instead of approximate `cell.filter({ hasText })`.
-
-**Row scope Gherkin** — these patterns use the table selector:
-```gherkin
-Then User see [Username] row in [Users] table with {{user_name}}
-Then User see [Status] column with {{expected_status}}
-When User click [Edit] button in [Users] table with {{user_name}}
-```
-
 ---
 
 ## Step 5: Detail Screens with Dynamic IDs
@@ -113,28 +114,12 @@ user detail:
 
 ---
 
-## Step 6: Validate Before Running
-
-**Fix 80%+ of selector issues before first test run.**
-
-After generating `selectors.yaml`, verify each entry against the live snapshot:
-- `role` + `name` → search snapshot for `role "name"`
-- `testid` → `browser_evaluate`: `document.querySelector('[data-testid="xxx"]')`
-- `placeholder` → search snapshot for textbox with placeholder
-- `page` → verify URL path exists
-
-Common fixes: name mismatch → copy from snapshot, element in iframe → add `frame`, multiple matches → add `nth` or `exact: true`.
-
----
-
-## Step 7: Run & Fix Loop
-
-Run tests in batches of 20. Group failures by root cause (same selector, same error type). Fix once, verify batch, move to next.
-
-```
-compile → batch run 20 → fix root cause → recompile → re-run failures → next batch
-```
+## Step 6: Fix Loop
 
-After all batches pass → run ALL tests once for regression check.
+After fixing selectors:
+1. Recompile: `sungen generate --screen <screen>`
+2. Re-run only failing tests: `npx playwright test --grep "VP-XXX-001|VP-XXX-002" --reporter=line`
+3. If new failures → repeat (max 3 attempts)
+4. After all fixes → run ALL tests once for regression check
 
-If still failing after 5 attempts per batch → ask user about direct `.spec.ts` fix.
+If still failing after 3 attempts → ask user for guidance.

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}}
 
@@ -100,8 +113,28 @@ Feature: <Screen> Screen
     Then User see [Name] column in [Users] table
     And User see [Email] column in [Users] table
     And User see [Status] column in [Users] table
+
+  # --- Data & Validate ---
+
+  Scenario: VP-VAL-010 Table displays correct data
+    Then User see [Users] table match data:
+      | Name         | Email          | Status       |
+      | {{name_1}}   | {{email_1}}    | {{status_1}} |
+      | {{name_2}}   | {{email_2}}    | {{status_2}} |
+
+  Scenario: VP-VAL-011 Edit button targets correct row
+    Given User see [Target] row in [Users] table with {{name_1}}
+    When User click [Edit] button in [Users] table with {{name_1}}
+    Then User see [Name] field with {{name_1}}
 ```
 
+### When to use DataTable vs Row Scope
+
+| Pattern | Use when |
+|---|---|
+| `table match data:` + DataTable | Verifying **multiple rows** exist with expected values |
+| `row in [Table] table with {{v}}` + `column with {{v}}` | Checking **single row** details or **acting** on a row (click, edit) |
+
 **Naming**: `VP-<CATEGORY>-<NNN>` prefix.
 
 **Test data** — `qa/screens/<screen>/test-data/<screen>.yaml`, grouped by section.

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

@@ -52,6 +52,8 @@ user-invocable: false
 - Consistency: total record count on UI matches server data
 - Row Limit: displayed rows never exceed page size/limit
 - Cell Integrity: cell data matches database, correct format (date, currency, status)
+- **Use `table match data:` with inline DataTable** for multi-row content verification (filter-based, resilient to data changes)
+- Use row scope (`row in [Table] table with {{v}}` + `column with {{v}}`) for single-row detail checks or when you need actions on a row
 
 **Logic**
 - Sorting: column sort refreshes data with correct order, updates header icon
@@ -82,7 +84,7 @@ user-invocable: false
 
 **Security**
 - Injection: XSS/SQL encoded as plain text, never executed
-- Wildcards: %, _, * treated as normal text (escaped)
+- Wildcards: `%, _, *` treated as normal text (escaped)
 
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 name: sungen-run-test
-description: 'Generate selectors, compile, and run Playwright tests — auto-fixes selectors on failure. Uses sungen-selector-fix, sungen-selector-keys, and sungen-error-mapping skills.'
+description: 'Compile and run Playwright tests — auto-fixes selectors on failure. Uses sungen-selector-fix, sungen-selector-keys, and sungen-error-mapping skills.'
 argument-hint: '[screen-name]'
 agent: 'agent'
 tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']
@@ -10,23 +10,26 @@ tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwri
 
 ## Role
 
-You are a **Senior Developer** specialized in Playwright test debugging. You generate selectors from live pages, diagnose test failures, and fix selectors/test-data using the `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills.
+You are a **Senior Developer**. Use `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills.
 
 ## Parameters
 
 - **screen** — ${input:screen:screen name (e.g., login, dashboard)}
 
-## Steps
-
-1. Verify `qa/screens/${input:screen}/` has `.feature` + `test-data.yaml`. If not → run `/sungen-create-test` first.
-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.
+## Phase 1: Compile & Run (no MCP)
+
+1. Verify `qa/screens/${input:screen}/` has `.feature` + `test-data.yaml`
+2. Ensure `selectors.yaml` has page selector. If missing, ask user for URL path
+3. `sungen generate --screen ${input:screen}`
+4. `npx playwright test specs/generated/${input:screen}/*.spec.ts --reporter=line`
+5. If all pass → done
+
+## Phase 2: Targeted Fix (only if failures)
+
+6. Parse failures → group by root cause
+7. Navigate to page ONCE via #tool:playwright → ONE `browser_snapshot`
+8. Fix broken selectors per `sungen-selector-fix` skill
+9. Recompile → re-run only failing tests
+10. Repeat up to 3 attempts
+11. Final full run for regression check
+12. Still failing → ask user

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

@@ -81,12 +81,12 @@ If `toHaveText` fails on an input → the Gherkin step has wrong target type. Fi
 
 | Symptom | Fix |
 |---|---|
-| Redirect to login page | Auth expired. Tell user: `sungen makeauth <role> --url <baseURL>` |
-| `storageState` file not found | Run `sungen makeauth <role> --url <baseURL>` |
-| Most tests timeout on first step | Auth expired — re-run makeauth |
-| Page shows home instead of target | SPA + expired auth. Re-run makeauth + add `wait for` step |
+| Redirect to login page | Auth expired. Ask user to log in manually via MCP browser |
+| `storageState` file not found | Ask user to log in manually via MCP browser, then save storage state |
+| Most tests timeout on first step | Auth expired — ask user to re-authenticate via MCP browser |
+| Page shows home instead of target | SPA + expired auth. Re-authenticate + add `wait for` step |
 
-**Never run `sungen makeauth` yourself.** Tell the user.
+**Never use `sungen makeauth`.** Always let the user log in manually via the MCP browser.
 
 ---