@sun-asterisk/sungen 2.4.2 → 2.4.5

package/dist/orchestrator/templates/ai-instructions/claude-skill-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** via `AskUserQuestion`: *"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 → run **Phase 0.5: Auth Persistence** first (see below), then re-navigate to the target page.
+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 → use `AskUserQuestion` to confirm overwrite (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.

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

@@ -22,7 +22,7 @@ For append: read highest `VP-<CAT>-<NNN>`, continue from next number. Never modi
 When `qa/screens/<screen>/requirements/` exists:
 - **`spec.md`** — primary: sections, field constraints, validation messages, business rules, states
 - **`ui/`** — supplementary: screenshots for layout/visual context
-- **`notes.md`** — supplementary: edge cases, known issues
+- **`test-viewpoint.md`** — supplementary: edge cases, known issues
 
 Requirements improve every viewpoint: exact error messages for VAL, business rules for LOGIC, role permissions for SEC.
 
@@ -47,16 +47,64 @@ When exploring live page or reading Figma designs, actively collect to hardcode
 
 ## Section Identification
 
-Identify sections from page patterns. Use `sungen-viewpoint` skill for the 7 pattern types (Form, Table, Search, Filter, Pagination, Modal, List/Card). Present sections and ask user which to focus on.
+Identify sections from page patterns. Use `sungen-viewpoint` skill for the 10 pattern types (Form & Inputs, Data Table, Create/Add, Update/Edit, Delete, Search, Filter, Pagination, Modal/Dialog, List/Card). Present sections and ask user which to focus on.
 
-## Viewpoint & Coverage
+## Test Generation Strategy
+
+### Step 1 — Spec-first extraction (always do this first)
+
+Before applying any checklist, extract test conditions from `spec.md` (and `test-viewpoint.md` if present):
+- **Validation rules**: field constraints, error messages, required/optional
+- **Business rules**: eligibility, calculation logic, permission-based behavior
+- **State lifecycle**: allowed transitions, blocked transitions
+- **Edge cases**: boundary values, empty states, concurrent conditions
+
+These spec-extracted conditions drive **which scenarios exist** — `sungen-viewpoint` only supplements with generic web UI coverage that spec doesn't explicitly state.
+
+### Step 2 — Apply test design techniques
+
+Apply `sungen-test-design-techniques` to spec-extracted conditions:
+
+| Technique | Apply when spec mentions |
+|---|---|
+| EP | Valid/invalid ranges, categories → **one** scenario per class, not per value |
+| BVA | Numeric range, string length → `min-1`, `min`, `max`, `max+1` (compact 4-point default) |
+| Decision Table | 2+ dependent conditions → one scenario per combination (cap at distinct outcomes if >3 conditions) |
+| State Transition | Entity lifecycle → one scenario per valid transition + key invalid transitions |
+
+### Step 3 — Fill coverage gaps with viewpoint checklists
 
 Use `sungen-viewpoint` skill for per-pattern checklists across 4 viewpoints: UI/UX, Data & Validate, Logic, Security.
 
-Generate **20+ scenarios per applicable viewpoint**. Skip viewpoints truly N/A.
+Add scenarios for generic UI coverage that spec didn't explicitly state (empty states, loading states, keyboard nav, hover effects). Skip viewpoints truly N/A.
 
 **Validation rule**: capture actual error messages from live page or spec.md. Use `User see {{error_var}}` — never assert just "is visible".
 
+## Priority Tags (auto-assign)
+
+Every scenario **MUST** have exactly one priority tag. Add it before the scenario line (after `@extend:` if present).
+
+| Tag | When to use |
+|---|---|
+| `@critical` | System unusable if fails — login/logout, authentication redirect, main create/submit/delete, permission denied |
+| `@high` | Major feature broken — required field validation, core business rules, data displays correctly, key navigation |
+| `@normal` | Degraded experience — UI layout/element presence, secondary flows, optional field validation, search/filter |
+| `@low` | Minor/cosmetic — tooltips, hover states, empty states, default sort, placeholder text |
+
+### Auto-assign heuristics
+
+| Viewpoint + Pattern | Default priority |
+|---|---|
+| VP-SEC-* (all security scenarios) | `@critical` |
+| VP-LOGIC-* with create/submit/delete/login | `@critical` |
+| VP-LOGIC-* other state changes | `@high` |
+| VP-VAL-* required field / submit empty | `@high` |
+| VP-VAL-* format, boundary, optional fields | `@normal` |
+| VP-UI-* form fields present, table columns | `@normal` |
+| VP-UI-* hover, tooltip, empty state, placeholder | `@low` |
+
+**`@steps:` scenarios** do NOT get a priority tag (they are setup blocks, not test cases).
+
 ## SPA Wait-For Steps
 
 ```gherkin
@@ -74,58 +122,38 @@ And User wait for [Page Title] heading is visible
 @auth:role
 Feature: <Screen> Screen
 
-  # Shared setup — use @steps, not Background
+  # Shared setup — NO priority tag on @steps
   @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 ---
+  # --- Section: Create User Form ---
 
-  @extend:open_form
+  @normal @extend:open_form
   Scenario: VP-UI-001 Form displays all fields with correct defaults
     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
+  @high @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}}
 
-  # ============================================================
-  # Section: User Table
-  # ============================================================
-
-  # --- UI/UX ---
+  # --- Section: User Table ---
 
+  @normal
   Scenario: VP-UI-010 Table displays all columns
     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 ---
 
+  @high
   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}}
+      | Name       | Email        |
+      | {{name_1}} | {{email_1}}  |
 ```
 
 ### When to use DataTable vs Row Scope
@@ -135,7 +163,7 @@ Feature: <Screen> Screen
 | `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.
+**Naming**: `VP-<CATEGORY>-<NNN>` prefix. Scenario name must use the **same element type** as the steps — e.g., if the step uses `dialog`, write "dialog opens" not "modal opens".
 
 **Test data** — `qa/screens/<screen>/test-data/<screen>.yaml`, grouped by section.
 

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

@@ -20,16 +20,16 @@ user-invocable: false
 
 ### Coverage (40 pts)
 
-| Dimension | Pts | Min scenarios |
-|---|---|---|
-| Happy paths | 8 | 3-5 |
-| Negative cases | 8 | 3-5 |
-| Edge cases | 8 | 5-8 |
-| Boundary values | 6 | 3-5 |
-| State transitions | 5 | 2-4 |
-| Combinatorial | 5 | 2-4 |
+| Dimension | Technique | Pts | What to check |
+|---|---|---|---|
+| Happy paths | — | 8 | Core success flows exist |
+| Negative cases | EP | 8 | One scenario per invalid class, no redundant same-class scenarios |
+| Edge cases | EP | 6 | Empty, null, whitespace, special chars covered |
+| Boundary values | BVA | 8 | `min-1`, `min`, `max`, `max+1` for each spec range |
+| State transitions | ST | 5 | Valid transitions + key blocked paths from spec |
+| Condition combos | DT | 5 | Dependent conditions covered, distinct outcomes tested |
 
-Score: `(dimensions_covered / 6) * 40`. Per-pattern checklists → `sungen-viewpoint` skill.
+Score: `(dimensions_covered / 6) * 40`. Validate technique application with `sungen-test-design-techniques`. Per-pattern checklists → `sungen-viewpoint` skill.
 
 ### Viewpoint (30 pts)
 
@@ -37,7 +37,8 @@ Score: `(dimensions_covered / 6) * 40`. Per-pattern checklists → `sungen-viewp
 |---|---|
 | All applicable VP present (UI/VAL/LOGIC/SEC) | 10 |
 | Correct classification | 8 |
-| `VP-<CAT>-<NNN>` naming + section grouping | 8 |
+| `VP-<CAT>-<NNN>` naming + section grouping | 4 |
+| Priority tag present and correct (`@critical`/`@high`/`@normal`/`@low`) | 4 |
 | Assertion quality (see rules below) | 4 |
 
 **Classification**: UI = static/always-same appearance. VAL = input validation/errors. LOGIC = behavior/state changes (includes persisted state without When). SEC = auth/permissions.
@@ -58,6 +59,7 @@ Score: `(dimensions_covered / 6) * 40`. Per-pattern checklists → `sungen-viewp
 2. **`When fill [X]`** → Then must assert the **visible result** (search results, validation error). Don't re-assert the field value.
 3. **UI-only scenarios** (no action needed) → use Given + Then without When.
 4. **Scenario name must match the assertion**, not the action.
+5. **Scenario name must use the same element type as the steps** — e.g., "dialog opens" + `[X] dialog`, never "modal opens" + `[X] dialog`.
 
 ### @manual Rules
 
@@ -72,13 +74,16 @@ Do NOT mark `@manual` when data is visible in snapshot or documented in spec —
 
 ## Checklist (auto-fix on detection)
 
-1. **Redundant scenarios** — keep stronger assertion, remove weaker duplicate
+1. **Redundant scenarios (EP violation)** — multiple scenarios testing same equivalence class? Keep one representative, remove rest
 2. **Misclassified VP** — UI tests behavior? Move to LOGIC. Logic tests appearance? Move to UI
 3. **Dynamic content** — exact match on counters/timestamps? Use `contains` instead
 4. **Duplicate across sections** — SEC scenario identical to UI? Remove duplicate
-5. **Always-enabled elements** — `is enabled` on never-disabled element? Remove
-6. **Test-data completeness** — every `{{var}}` must exist in test-data.yaml
-7. **Missing negative/boundary** — every form section needs at least: empty field, invalid format, boundary value
+5. **Missing/wrong priority tag** — every non-`@steps` scenario needs exactly one of `@critical`/`@high`/`@normal`/`@low`. SEC→`@critical`, VAL required→`@high`, UI layout→`@normal`, hover/tooltip→`@low`
+6. **Always-enabled elements** — `is enabled` on never-disabled element? Remove
+7. **Test-data completeness** — every `{{var}}` must exist in test-data.yaml
+8. **Missing BVA boundaries** — spec defines min/max range but scenarios only test midpoint? Add `min-1`, `min`, `max`, `max+1`
+9. **Missing state transitions** — spec defines lifecycle states but only happy path tested? Add blocked transitions
+10. **Uncovered condition combos** — spec has 2+ dependent conditions but only partial combinations tested? Build decision table
 
 ---
 

package/dist/orchestrator/templates/ai-instructions/claude-skill-test-design-techniques.md

@@ -0,0 +1,99 @@
+---
+name: sungen-test-design-techniques
+description: 'Test design techniques (EP, BVA, Decision Table, State Transition) for systematic scenario generation from spec constraints. Auto-loaded by create-test command.'
+user-invocable: false
+---
+
+## When to Apply
+
+| Technique | Apply when spec mentions |
+|---|---|
+| EP (Equivalence Partitioning) | Input types, categories, roles, valid/invalid ranges |
+| BVA (Boundary Value Analysis) | Numeric range, string length, date range, count limit |
+| Decision Table | 2+ mutually dependent conditions with different outcomes |
+| State Transition | Entity lifecycle, workflow states, status changes |
+
+**Rule:** These techniques determine **how many** and **which** scenarios to generate. `sungen-viewpoint` determines **which viewpoints** to cover.
+
+---
+
+## 1. Equivalence Partitioning (EP)
+
+**Goal:** One representative per input class. If one value in a partition passes, all values in that partition pass.
+
+**How to apply:**
+1. Extract partitions from `spec.md` constraints (e.g., field accepts 1-100)
+2. Valid class: 1 <= value <= 100
+3. Invalid class (below): value < 1
+4. Invalid class (above): value > 100
+5. Write **one** scenario per class
+
+**Anti-pattern:**
+```gherkin
+# BAD — 3 scenarios, same class, same result:
+Scenario: VP-VAL-001 Enter value 10
+Scenario: VP-VAL-002 Enter value 50
+Scenario: VP-VAL-003 Enter value 80
+```
+```gherkin
+# GOOD — one representative per class:
+Scenario: VP-VAL-001 Valid range value is accepted       # value = 50
+Scenario: VP-VAL-002 Below minimum is rejected           # value = 0
+Scenario: VP-VAL-003 Above maximum is rejected           # value = 101
+```
+
+---
+
+## 2. Boundary Value Analysis (BVA)
+
+**Goal:** Test exact edges where off-by-one errors occur (`>` vs `>=`, `<` vs `<=`).
+
+### Two modes
+
+| Mode | Values | Use when |
+|---|---|---|
+| **Compact (default)** | `min-1`, `min`, `max`, `max+1` | Most fields |
+| **Full 6-point** | `min-1`, `min`, `min+1`, `max-1`, `max`, `max+1` | Critical fields with `@critical`/`@high` priority |
+
+**How to apply** (example: "quantity must be 1-10"):
+- `min-1` = 0 -> invalid
+- `min` = 1 -> valid (lower boundary)
+- `max` = 10 -> valid (upper boundary)
+- `max+1` = 11 -> invalid
+- Midpoint (e.g., 5) already covered by EP valid class
+
+**BVA scenarios** (example: quantity 1-10):
+- `@high VP-VAL-010 Below minimum (0) is rejected`
+- `@high VP-VAL-011 Minimum boundary (1) is accepted`
+- `@high VP-VAL-012 Maximum boundary (10) is accepted`
+- `@high VP-VAL-013 Above maximum (11) is rejected`
+
+---
+
+## 3. Decision Table
+
+**Goal:** Cover all condition combinations when 2+ conditions constrain each other.
+
+**How to apply:** List conditions from `spec.md` → build combination→outcome table → one scenario per row.
+
+**Cap:** When >3 boolean conditions (>8 rows), prioritize rows with **distinct outcomes** and add `@manual` for exhaustive combos.
+
+**Example** — Submit requires valid form AND permission → 4 combos, 2 distinct outcomes:
+- `@normal` Form invalid + no permission → disabled
+- `@normal` Form valid + no permission → disabled
+- `@normal` Has permission + form invalid → disabled
+- `@critical` Form valid + has permission → succeeds
+
+---
+
+## 4. State Transition
+
+**Goal:** Verify every valid transition AND block invalid ones.
+
+**How to apply:** Extract state diagram from `spec.md` → one scenario per valid transition + key invalid transitions.
+
+**Example** — Order lifecycle (Draft→Pending→Approved→Completed):
+- `@high` Valid: Draft → Pending, Pending → Approved, Approved → Completed
+- `@normal` Invalid: Completed → Draft (blocked), Pending → Completed (skip approval)
+
+**test-data:** Use named state keys (`order_in_draft`, `order_in_pending`).