@sun-asterisk/sungen 2.4.2 → 2.4.5

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

@@ -1,6 +1,6 @@
 ---
 name: sungen-run-test
-description: 'Compile and run Playwright tests — auto-fixes selectors on failure. Uses sungen-selector-fix, sungen-selector-keys, and sungen-error-mapping skills.'
+description: 'Generate selectors + auth state via Playwright MCP, 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/*']
@@ -16,20 +16,29 @@ You are a **Senior Developer**. Use `sungen-selector-fix`, `sungen-selector-keys
 
 - **screen** — ${input:screen:screen name (e.g., login, dashboard)}
 
-## Phase 1: Compile & Run (no MCP)
+## Pre-run (phased — per `sungen-selector-fix` skill)
 
-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
+1. Verify `qa/screens/${input:screen}/` has `.feature` + `test-data.yaml`.
+2. **Phase 0 — Selector Pre-gen**: if `selectors.yaml` is missing/empty or doesn't cover the feature file's `[Reference]`s, run Phase 0 from `sungen-selector-fix` — confirm with user, `browser_navigate` → one `browser_snapshot` → merge YAML entries.
+3. **Phase 0.5 — Auth Persistence**: if the feature has `@auth:<role>` tags and `specs/.auth/<role>.json` is missing/expired, run Phase 0.5 from `sungen-selector-fix` — user logs in manually in MCP browser → `browser_storage_state` → `specs/.auth/<role>.json`. Offer `sungen makeauth <role>` as CLI fallback only if `browser_storage_state` isn't available in this MCP version.
+4. Compile: `sungen generate --screen ${input:screen}`.
 
-## Phase 2: Targeted Fix (only if failures)
+## Run & Fix (phased — per `sungen-selector-fix` skill)
 
-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
+5. **Phase 1 — Smoke Check**: Run first 5 `@critical`/`@high` scenarios only. If failures → diagnose, fix fundamentals (page selector, auth, base @steps), re-run. Max 2 attempts. If still broken → ask user.
+6. **Phase 2 — Priority Wave**: Run all `@critical` + `@high` scenarios. Fix only failures from this wave. Max 2 attempts. Shared selectors fixed here cascade to later phases.
+7. **Phase 3 — Full Run**: Run all tests. Fix only **new** failures (elements unique to `@normal`/`@low`). Max 1 attempt. Don't loop on low-priority failures.
+8. **Phase 4 — Regression**: One final full run. Report results. No more fix loops.
+
+## Next steps
+
+After showing results, offer next steps:
+
+If all tests **passed**:
+- **`/sungen-create-test ${input:screen}`** — Add more test cases (Recommended)
+- **Done** — All tests passed, I'm finished
+
+If tests **failed** (after retries):
+- **`/sungen-run-test ${input:screen}`** — Re-run after manual fixes
+- **`/sungen-create-test ${input:screen}`** — Revise test cases
+- **Done for now** — I'll fix manually later

package/src/orchestrator/templates/ai-instructions/copilot-config.md

@@ -10,8 +10,9 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-gherkin-syntax` | All 70+ step patterns, selector types, YAML key rules, tags, element types |
 | `sungen-error-mapping` | Playwright & sungen error → fix mapping |
 | `sungen-tc-generation` | Test case generation strategy, output format |
+| `sungen-test-design-techniques` | EP, BVA, Decision Table, State Transition — systematic scenario generation |
 | `sungen-tc-review` | Review scoring, quality rules, checklist |
-| `sungen-viewpoint` | 7 UI patterns x 4 viewpoints — coverage checklists |
+| `sungen-viewpoint` | 10 UI patterns x 4 viewpoints — coverage checklists |
 | `sungen-selector-keys` | YAML key generation from `[Reference]` names, suffixes, lookup priority |
 | `sungen-selector-fix` | Selector generation from live page, auto-fix strategy |
 
@@ -26,6 +27,8 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 
 **Order:** add-screen → create-test → review → run-test.
 
+After each command completes, present the next actions as selectable options. Never just print text — always give clickable choices so the user can continue the workflow seamlessly.
+
 ## File Structure
 
 ```
@@ -38,102 +41,6 @@ qa/screens/<screen-name>/
     └── ui/                        # Screenshots, mockups
 ```
 
-## Complete Example
-
-Given a login page, here are the 3 files you generate:
-
-**qa/screens/login/features/login.feature**
-```gherkin
-@no-auth
-Feature: Login Screen
-
-  Scenario: VP-LOGIC-001 Successful login
-    Given User is on [login] page
-    When User fill [Email] field with {{email}}
-    And User fill [Password] field with {{password}}
-    And User click [Submit] button
-    Then User see [Welcome] heading with {{welcome_text}}
-    And User see [Dashboard] link
-```
-
-**qa/screens/login/selectors/login.yaml**
-```yaml
-login:
-  type: 'page'
-  value: '/login'
-
-email:
-  type: 'placeholder'
-  value: 'Enter your email'
-
-password:
-  type: 'placeholder'
-  value: 'Enter your password'
-
-submit:
-  type: 'role'
-  value: 'button'
-  name: 'Submit'
-
-welcome:
-  type: 'role'
-  value: 'heading'
-  name: 'Welcome'
-
-dashboard:
-  type: 'role'
-  value: 'link'
-  name: 'Dashboard'
-```
-
-**qa/screens/login/test-data/login.yaml**
-```yaml
-email: 'admin@example.com'
-password: 'password123'
-welcome_text: 'Welcome back'
-```
-
-## Critical Gherkin Rules (quick reference)
-
-1. **NEVER write `is visible`** — `User see [T] type` already asserts visibility. Only use `is hidden` to assert absence.
-2. **Use `@no-auth` for pre-login pages** (login, register, forgot-password). Use `@auth:role` for authenticated pages.
-3. **Scenario names use VP prefix** — `VP-UI-001`, `VP-VAL-001`, `VP-LOGIC-001`, `VP-SEC-001`.
-4. **Values use `{{snake_case}}`** — never hardcode data in `.feature`. All values go in `test-data.yaml`.
-5. **Selectors are deferred** — `selectors.yaml` is generated during `/sungen-run-test` from the live page, NOT during `/sungen-create-test`.
-6. **Every `{{variable}}` must exist in `test-data.yaml`** — missing variables cause compile failures.
-7. **Assertion type is determined by element type** — input types (`field`, `textarea`, `search`, `dropdown`, `slider`, `date-picker`) → `toHaveValue()`. Everything else → `toHaveText()`. Wrong type = wrong assertion = test failure.
-
-## Using Playwright MCP to explore pages
-
-When exploring a page to generate test files:
-1. Read `playwright.config.ts` for `baseURL`
-2. Use `browser_navigate` to open `baseURL + /path`
-3. Use `browser_snapshot` to see all elements
-4. Generate the 3 files from the snapshot
-
-### Allowed MCP tools
-
-| Tool | Use for |
-|---|---|
-| `browser_navigate` | Open pages |
-| `browser_snapshot` | Capture all accessible elements |
-| `browser_click` | Interact with elements (open dialogs, dropdowns) |
-| `browser_fill_form` | Fill form fields |
-| `browser_evaluate` | **Read-only DOM queries only** (e.g., detect `data-testid` attributes) |
-
-**NEVER use `browser_run_code`** — fails with `require is not defined`.
-
-### Authentication via MCP
-
-1. `browser_navigate` to `baseURL`
-2. If redirected to login, ask the user to log in manually:
-   > "This page requires login. Please log in using the browser. Confirm when you're done."
-3. Once confirmed, `browser_navigate` to the target page and take `browser_snapshot`
-
-**Never use `sungen makeauth`.** Always let the user log in manually via the MCP browser.
-**NEVER use `browser_evaluate` to inject cookies or localStorage** — causes size limit issues and server 500 errors. Use `browser_evaluate` ONLY for read-only DOM queries.
-**Minimize navigations** — take one snapshot per page, do not navigate repeatedly.
-
 ## CLI Commands
 
 ```bash

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

@@ -27,150 +27,68 @@ AND    →  inherits from preceding keyword
 
 ## Step Patterns (70 patterns)
 
-### Setup
+### Setup / Form / Interaction
 
 ```
-User is on [T] page                              # navigate to page
-User is on [T] page with {{v}}                   # navigate with data (e.g., detail page with ID)
-User is on [T] dialog                            # enter dialog scope
+User is on [T] page | page with {{v}} | dialog
+User fill [T] field | textarea | search | slider | date-picker with {{v}}
+User fill [T] uploader with {{f}}
+User clear [T] field
+User check [T] checkbox | toggle | radio
+User uncheck [T] checkbox | toggle
+User select [T] dropdown with {{v}}
+User click [T] button | tab | column | breadcrumb
+User click [T] row with {{v}}
+User double click [T] element
+User hover [T] icon | row
+User drag [T] to [T2]
+User expand | collapse [T] row
 ```
 
-### Form
+**click + with {{Value}} rule**: NO value for static (`button`, `link`, `icon`, `tab`). WITH value only for dynamic lists (`row`, `item`, `card`, `option`).
 
-```
-User fill [T] field with {{v}}                   # text input
-User fill [T] textarea with {{v}}                # multiline input
-User fill [T] search with {{v}}                  # search input
-User fill [T] slider with {{v}}                  # set slider value
-User fill [T] date picker with {{v}}             # date input
-User clear [T] field                             # clear input
-User check [T] checkbox                          # check
-User check [T] toggle                            # toggle on (same as check)
-User check [T] radio                             # select radio
-User uncheck [T] checkbox                        # uncheck
-User uncheck [T] toggle                          # toggle off
-User select [T] dropdown with {{v}}              # select option
-User fill [T] uploader with {{f}}                # file upload
-```
-
-### Interaction
-
-```
-User click [T] button                            # click (static element, no value)
-User click [T] row with {{v}}                    # click dynamic list item (row/item/card/option)
-User click [T] tab                               # switch tab
-User click [T] column                            # sort column
-User click [T] breadcrumb                        # navigate breadcrumb
-User double click [T] element                    # double click
-User hover [T] icon                              # hover (must have see/click after)
-User hover [T] row                               # hover row for hidden actions
-User drag [T] to [T2]                            # drag and drop
-User expand [T] row                              # expand (aria-expanded)
-User collapse [T] row                            # collapse (aria-expanded)
-```
-
-#### click + with {{Value}} rule
-
-- **NO value** for static elements: `button`, `link`, `icon`, `tab`, `toggle`
-- **WITH value** only for dynamic lists: `row`, `item`, `card`, `option`
-
-### Browser Alert (system dialog)
+### Alert / Keyboard / Wait / Scroll
 
 ```
-User click [OK] alert                            # accept (OK/Accept/Yes/Confirm)
-User click [Cancel] alert                        # dismiss (Cancel/Dismiss/No)
-User fill [T] alert with {{v}}                   # fill prompt + accept
-User see [message text] alert                    # assert dialog message
+User click [OK | Cancel] alert
+User fill [T] alert with {{v}}
+User see [message text] alert
+User press Escape key | Enter on [T] field
+User wait for N seconds | [T] dialog | [T] dialog is STATE | [T] page
+User scroll to [T] section
+User switch to [T] frame | [main] frame
 ```
 
 > Alert steps must appear BEFORE the action that triggers the dialog.
 
-### Keyboard
+### Assertions (8 patterns → determines Playwright assertion)
 
 ```
-User press Escape key                            # global key press
-User press Enter on [T] field                    # key on element
-```
-
-### Wait
-
-```
-User wait for N seconds                          # wait timeout
-User wait for [T] dialog                         # wait for element
-User wait for [T] dialog is STATE                # wait for state
-User wait for [T] dialog with {{v}}              # wait for element with text
-User wait for [T] page                           # wait for navigation
-User wait for [T] message                        # wait for toast/feedback
-User wait for [T] button                         # wait for button to appear
-```
-
-### Scroll & Frame
-
-```
-User scroll to [T] section                       # scroll into view
-User switch to [T] frame                         # enter iframe
-User switch to [main] frame                      # exit iframe
-```
-
-### Assertions (8 verify patterns)
-
-```
-# 1. Visibility
-User see [T] message                             # visible (default — NEVER add "is visible")
-User see [T] modal is hidden                     # hidden
-
-# 2. Text Content (exact full match — toHaveText)
-User see [T] message with {{v}}                  # exact text match
-User see [T] header with {{v}}                   # heading text
-User see [T] label with {{v}}                    # label text
-
-# 3. Partial Text Match (toContainText)
-User see [T] text contains {{v}}                 # partial text match
-
-# 4. Input Value (toHaveValue)
-User see [T] field with {{v}}                    # input value
-User see [T] dropdown with {{v}}                 # selected value
-User see [T] date picker with {{v}}              # date value
-User see [T] search with {{v}}                   # search input value
-User see [T] slider with {{v}}                   # slider value
-
-# 5. Component State
-User see [T] button is disabled                  # state assertion
-User see [T] checkbox is checked                 # checked state
-User see [T] toggle is unchecked                 # unchecked state
-User see [T] dialog with {{v}} is hidden         # text + state combined
-
-# 6. Attribute (toHaveAttribute — when selector YAML has `attribute` field)
-User see [T] image with {{v}}                    # image src
-User see [T] link with {{v}}                     # link href
-
-# 7. Count
-User see [T] row with {{count}}                  # element count
-
-# 8. Page Context
-User see [T] page                                # URL assertion
+# 1. Visibility: User see [T] type (NEVER add "is visible") | is hidden
+# 2. Text (toHaveText): User see [T] message | header | label with {{v}}
+# 3. Partial (toContainText): User see [T] text contains {{v}}
+# 4. Input (toHaveValue): User see [T] field | dropdown | date-picker | search | slider with {{v}}
+# 5. State: User see [T] button is disabled | checkbox is checked | dialog with {{v}} is hidden
+# 6. Attribute (toHaveAttribute): User see [T] image | link with {{v}}
+# 7. Count: User see [T] row with {{count}}
+# 8. Page: User see [T] page
 ```
 
 ### Table
 
 ```
-User see [Col] column in [Table] table                          # column exists
-User see [Ref] row in [Table] table with {{v}}                  # row exists (enters row scope)
-User see [Ref] row in [Table] table with {{v}} is hidden        # row hidden
-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)
+User see [Col] column in [Table] table
+User see [Ref] row in [Table] table with {{v}}
+User see [Ref] row in [Table] table with {{v}} is hidden
+User see [Table] table with {{count}} | is empty
+User see [Col] column with {{v}}
+User click [Act] button in [Table] table with {{v}}
+User see [Table] table match data:
     | 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.
+Row scope: `see [Ref] row in [Table] table with {{v}}` enters scope. Subsequent `see [Col] column with {{v}}` checks cell in that row. Use `table match data:` for multi-row verification.
 
 ### States
 
@@ -223,6 +141,10 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | `@auto` | Standard scenario, ready for automation |
 | `@manual` | Skip in generation |
 | `@smoke` / `@regression` | Test suite grouping |
+| `@critical` | Priority: system unusable if fails (login, auth, core CRUD) |
+| `@high` | Priority: major feature broken (required validation, key business rules) |
+| `@normal` | Priority: degraded experience (UI layout, secondary flows) |
+| `@low` | Priority: minor/cosmetic (tooltips, hover states, empty states) |
 | `@auth:role` | Use auth storage state for role |
 | `@no-auth` | Disable inherited auth |
 | `@steps:name` | Define reusable step block (base scenario) |
@@ -232,6 +154,8 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 
 - Tool executes **only Given→When** of `@steps` scenario (skips Then)
 - The `Given` in `@extend` scenario is the **entry assertion** (confirms state after base steps)
+- **Entry assertion MUST use `Given User is on [X] type`** — NEVER `Given User see [X] type`
+- `Given` keyword ONLY allows `is on` action. `see` = `Then` only.
 - If `@steps` scenario fails, `@extend` scenario is **skipped**
 - Name format: `snake_case` or `kebab-case` with module prefix: `@steps:kudos__open_modal`
 
@@ -240,6 +164,8 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | Error | Wrong | Correct |
 |---|---|---|
 | Wrong keyword | `Given User click [T] button` | `When User click [T] button` |
+| `see` after Given | `Given User see [T] heading with {{v}}` | `Then User see [T] heading with {{v}}` (or `Given User is on [T] page` for entry assertion) |
+| Name ≠ step type | Scenario name says "modal" but step uses `dialog` | Use the **same element type** in both: "...dialog opens" + `[X] dialog` |
 | Wrong action for type | `When User click [T] checkbox` | `When User check [T] checkbox` |
 | press wrong target | `When User press [Submit] button` | `When User press Enter key` |
 | uncheck radio | `When User uncheck [Male] radio` | `When User check [Female] radio` |

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-selector-fix.md

@@ -1,20 +1,161 @@
 ---
 name: sungen-selector-fix
-description: 'Selector fixing strategy — diagnose failures, explore live page targeted, fix broken selectors. Auto-loaded by run-test command.'
+description: 'Selector fixing strategy — phased execution, priority-first diagnosis, targeted MCP exploration. Auto-loaded by run-test command.'
 user-invocable: false
 ---
 
-## Strategy: Fix Only What Breaks
+## Strategy: Phased Execution
 
-Most selectors auto-infer from Gherkin element types (see `sungen-selector-keys` skill). Only add YAML entries for selectors that fail during test execution.
+Run tests in priority waves — catch fundamental issues early, fix critical paths first, let shared fixes cascade to lower-priority tests.
 
-**Minimal `selectors.yaml`**: page selectors (required), overrides for elements where auto-infer doesn't work. Never generate a full page catalog upfront.
+**Never run all tests blindly.** Always start with selector pre-generation, then a smoke check.
 
 ---
 
-## Step 1: Diagnose Failures
+## Phase 0: Pre-run Selector Generation (Playwright MCP)
 
-Parse Playwright error output to categorize failures:
+**Before any `sungen generate` or test run**, populate `selectors.yaml` from the live page so tests don't fail on missing keys in Phase 1.
+
+### When to run Phase 0
+
+- `selectors.yaml` missing, empty, or contains only the page selector
+- The `.feature` file has `[Reference]` keys without corresponding YAML entries and the referenced element can't be auto-inferred (see `sungen-selector-keys` § Auto-Infer)
+- User explicitly re-scans after UI changes
+
+If existing selectors already cover the feature file, **skip Phase 0** and go straight to compile + Phase 1.
+
+### Steps
+
+1. **Confirm with the user**: *"Generate selectors from the live page via Playwright MCP now?"* — offer **Yes, scan live page** / **Skip (use existing selectors.yaml)** / **Cancel**.
+2. **Collect references**: parse the `.feature` file for every `[Reference]` element + its type (e.g. `[Submit] button`, `[Email] field`). Deduplicate.
+3. **Ensure page selector**: if missing, ask user for URL path and write it first.
+4. **Navigate**:
+   - Read `baseURL` from `playwright.config.ts`.
+   - `browser_navigate` to the page URL.
+   - If redirected to login → **ask the user to log in manually in the MCP browser**, wait for confirmation, then continue. Never use `sungen makeauth`. Never inject cookies via `browser_evaluate`.
+5. **Snapshot**: take **ONE** `browser_snapshot`. All Phase 0 selectors come from this single snapshot.
+6. **Generate YAML entries**:
+   - Keys: follow `sungen-selector-keys` (lowercase, Unicode preserved, `--type` / `--N` suffixes).
+   - Selector priority: follow the table in **Diagnosis & Fix § Step 3** (`testid` > `role`+name > `placeholder` > `label` > `locator` > `text`).
+   - Copy names **character-for-character** from the snapshot. Never infer from the Gherkin label.
+   - If an element is auto-inferable per `sungen-selector-keys` § Auto-Infer, **omit it** from YAML — keep the file minimal.
+7. **Merge, don't overwrite**: preserve the page selector and any user-authored entries in `selectors.yaml`. Only add missing keys.
+8. **Show summary + confirm**: list the keys that will be added, ask the user to approve, then write the file.
+9. **Compile**: `sungen generate --screen <screen>` — then proceed to Phase 1.
+
+### Common Phase 0 pitfalls
+
+- Writing keys inferred from the Gherkin label instead of the snapshot name → Phase 1 will fail with "no element found".
+- Skipping Phase 0.5 when an auth redirect happened → snapshot captures the login page, all selectors wrong.
+- Using `browser_evaluate` alone to scrape cookies → misses httpOnly session cookies. Always use `browser_storage_state` (or the `browser_run_code` fallback).
+- Overwriting user-authored selectors → always merge.
+
+---
+
+## Phase 0.5: Auth Persistence (MCP alternative to `sungen makeauth`)
+
+Capture an authenticated session from the MCP browser into `specs/.auth/<role>.json` — the same path `sungen makeauth` writes to, which compiled tests already reference via `test.use({ storageState })` based on `@auth:<role>` tags. No `playwright.config.ts` edits needed. Run once per auth lifetime, not on every selector fix.
+
+### When to run Phase 0.5
+
+- Phase 0 navigation hit a login redirect and `specs/.auth/<role>.json` is missing or expired
+- A scenario tagged `@auth:<role>` is about to run and its auth file is absent
+- User asks to refresh auth
+
+Skip if `specs/.auth/<role>.json` already exists and a probe navigation reaches an authenticated page without redirecting to login.
+
+### Steps
+
+1. **Resolve the role**:
+   - Look at the `.feature` file for `@auth:<role>` tags (feature-level or scenario-level). Pick the role for the scenario being run. If no tag exists, default to `user`.
+   - Target file: `specs/.auth/<role>.json`. Create `specs/.auth/` if missing.
+   - If the file already exists → confirm overwrite with the user (mirrors the `(y/N)` prompt in `sungen makeauth`).
+2. **Navigate to login**:
+   - Read `baseURL` from `playwright.config.ts` (fall back to `APP_BASE_URL` env, then `http://localhost:3000` — same resolution order as `sungen makeauth`).
+   - `browser_navigate` to `<baseURL>/login`. If the app uses a different login path, ask the user.
+   - If the URL doesn't stay on `/login` after load → user is already signed in. Skip step 3.
+3. **Ask the user to log in manually** in the MCP browser (username, password, MFA, SSO — whatever the app needs). Never type credentials via `browser_type` or script the login. Wait for the user to confirm in chat that they're signed in.
+4. **Verify login** — check the current URL or take a `browser_snapshot`; confirm the page is no longer on `/login`.
+5. **Export storage state** (preferred → fallback):
+   - **Preferred** — `browser_storage_state` with `filename: "specs/.auth/<role>.json"` (native Playwright MCP tool; captures cookies including httpOnly + localStorage + sessionStorage via the Playwright context — same output format as `context.storageState({ path })` used by `sungen makeauth`).
+   - **Fallback** — if `browser_storage_state` isn't available in this MCP version, use `browser_run_code` to execute `await context.storageState({ path: 'specs/.auth/<role>.json' })`.
+   - **Do NOT** use `browser_evaluate` for auth export — it misses httpOnly cookies and session auth will fail silently.
+6. **Gitignore** — ensure `specs/.auth/` (or `specs/.auth/*.json`) is in `.gitignore`. Add it if missing.
+7. **Return to Phase 0 step 4** — re-`browser_navigate` to the target page; the session is now active.
+
+### Phase 0.5 pitfalls
+
+- Writing to a path other than `specs/.auth/<role>.json` → compiled tests won't find the file. Always match `sungen makeauth`'s convention.
+- Committing `specs/.auth/*.json` → leaks a live session. Always gitignore.
+- Scripting the login with `browser_type` → bypasses MFA/CAPTCHA and risks account lockout. Always manual.
+- Running Phase 0.5 on every `run-test` invocation → unnecessary; reuse the file until tests start redirecting to login.
+- Mismatch between `<role>` in the auth file and `@auth:<role>` tag → compiled tests reference a nonexistent file.
+
+---
+
+## Phase 1: Smoke Check (catch fundamentals)
+
+Run **up to 5 scenarios** — pick the first `@critical` or `@high` scenarios in the feature file.
+
+```bash
+npx playwright test --grep "VP-.*-001|VP-.*-002|VP-.*-003|VP-.*-004|VP-.*-005" --reporter=line
+```
+
+**Purpose:** Detect broken fundamentals before running 50+ tests:
+- Page selector wrong → ALL tests would fail (1 fix, not 50 diagnoses)
+- Auth redirect → need `@no-auth` or user login
+- Base `@steps:` scenario broken → all `@extend:` scenarios would fail
+
+**If all 5 pass** → skip to Phase 2.
+**If failures** → diagnose and fix (see Diagnosis & Fix below), then re-run smoke. Max 2 attempts here.
+
+---
+
+## Phase 2: Priority Wave (@critical + @high)
+
+Run all `@critical` and `@high` scenarios:
+
+```bash
+npx playwright test --grep "@critical|@high" --reporter=line
+```
+
+If your Playwright config doesn't support tag grep, use scenario name grep from the feature file — collect VP IDs of `@critical` and `@high` scenarios.
+
+**Fix only failures from this wave.** Most shared selectors (buttons, headings, navigation) get fixed here because critical/high scenarios exercise them.
+
+Max 2 fix attempts in this phase.
+
+---
+
+## Phase 3: Full Run (@normal + @low)
+
+Run remaining scenarios:
+
+```bash
+npx playwright test --reporter=line
+```
+
+Many selectors already fixed from Phase 2 (shared elements). Only diagnose **new** failures — selectors that only appear in lower-priority scenarios.
+
+Max 1 fix attempt. If `@low` scenarios still fail after fix → **report and move on**, don't loop.
+
+---
+
+## Phase 4: Regression
+
+One final full run to confirm all phases together:
+
+```bash
+npx playwright test --reporter=line
+```
+
+Report results. Do NOT enter another fix loop here.
+
+---
+
+## Diagnosis & Fix (used in each phase)
+
+### Step 1: Parse Failures
 
 | Error pattern | Root cause | Fix target |
 |---|---|---|
@@ -28,24 +169,18 @@ Parse Playwright error output to categorize failures:
 
 **Check `test-results/` first** — Playwright captures failure screenshots automatically. Use these to diagnose before any MCP exploration.
 
----
-
-## Step 2: Targeted MCP Exploration
+### Step 2: Targeted MCP Exploration
 
 Only when `test-results/` screenshots are insufficient:
 
 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
+3. If redirected to login → run **Phase 0.5: Auth Persistence**, then re-navigate
 4. Take **ONE** `browser_snapshot` — fix all broken selectors from this single snapshot
 
-**Never use `sungen makeauth`.** Never use `browser_evaluate` to inject cookies.
+Never use `browser_evaluate` to inject or read cookies (misses httpOnly). For auth, use Phase 0.5 or `sungen makeauth`.
 
----
-
-## Step 3: Fix Broken Selectors
-
-For each failed selector, find the correct locator from the snapshot:
+### Step 3: Fix Broken Selectors
 
 Selector priority (use first applicable):
 
@@ -73,9 +208,18 @@ Common fixes:
 - Element in iframe → add `frame` field
 - Dynamic content → use `testid` or structural `role` + `nth`
 
+### Step 4: Recompile After Fix
+
+Always recompile before re-running:
+```bash
+sungen generate --screen <screen>
+```
+
+Then re-run only the current phase's failing tests, not all tests.
+
 ---
 
-## Step 4: Table Selectors
+## Table Selectors
 
 For table patterns, add table selectors with `columns` config:
 
@@ -100,7 +244,7 @@ users:
 
 ---
 
-## Step 5: Detail Screens with Dynamic IDs
+## Detail Screens with Dynamic IDs
 
 For screens like `/admin/users/:id`:
 1. Navigate to list page via MCP to find a real record ID
@@ -114,12 +258,15 @@ user detail:
 
 ---
 
-## Step 6: Fix Loop
+## Attempt Budget Summary
 
-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
+| Phase | What runs | Max fix attempts | On failure after max |
+|---|---|---|---|
+| 0. Pre-gen | Playwright MCP snapshot → write selectors.yaml | 1 snapshot | Ask user — skip or retry navigation |
+| 0.5. Auth | Manual login in MCP browser → `browser_storage_state` → `specs/.auth/<role>.json` | 1 login | Ask user — retry login or fall back to `sungen makeauth` |
+| 1. Smoke | First 5 @critical/@high | 2 | Ask user — fundamentals broken |
+| 2. Priority | All @critical + @high | 2 | Report failures, continue to Phase 3 |
+| 3. Full | All tests | 1 | Report @low/@normal failures, continue |
+| 4. Regression | All tests | 0 | Report final results |
 
-If still failing after 3 attempts → ask user for guidance.
+**Total worst case: 5 fix attempts** (2+2+1), not unbounded loops. Phases 0 and 0.5 don't count toward fix budget.