@sun-asterisk/sungen 2.7.0-beta.0 → 2.7.0-beta.1

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-selector-keys.md

@@ -166,37 +166,47 @@ Resolver searches in this order:
 
 If no YAML key exists, the resolver infers from the Gherkin element type:
 
-| Gherkin | Inferred locator |
-|---|---|
-| `[X] button` | `getByRole('button', { name: 'X' })` |
-| `[X] link` | `getByRole('link', { name: 'X' })` |
-| `[X] heading` / `header` | `getByRole('heading', { name: 'X' })` |
-| `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` |
-| `[X] radio` | `getByRole('radio', { name: 'X' })` |
-| `[X] field` | `getByPlaceholder('X')` |
-| `[X] text` / `message` / `label` | `getByText('X')` |
-| `[X] logo/image/icon` | `getByRole('img', { name: 'X' })` |
-| `[X] search` | `getByRole('searchbox', { name: 'X' })` |
-| `[X] option` | `getByRole('option', { name: 'X' })` |
-| `[X] slider` | `getByRole('slider', { name: 'X' })` |
-| `[X] toggle` | `getByRole('switch', { name: 'X' })` |
-| `[X] tab` | `getByRole('tab', { name: 'X' })` |
-| `[X] table` | `getByRole('table', { name: 'X' })` |
-| `[X] list` | `getByRole('list', { name: 'X' })` |
-| `[X] column` | `getByRole('columnheader', { name: 'X' })` |
-| `[X] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'X' })` |
-| `[X] dropdown` / `select` | `getByRole('combobox', { name: 'X' })` |
-| `[X] menuitem` | `getByRole('menuitem', { name: 'X' })` |
-| `[X] progressbar` | `getByRole('progressbar', { name: 'X' })` |
-| `[X] section` | `getByRole('region', { name: 'X' })` |
-| `[X] card` | `getByRole('article', { name: 'X' })` |
-| `[X] item` | `getByRole('listitem', { name: 'X' })` |
-| `[X] cell` | `getByRole('cell', { name: 'X' })` |
-| `[X] spinner` | `getByRole('status', { name: 'X' })` |
-| `[X] breadcrumb` | `getByRole('navigation', { name: 'X' })` |
-| `[X] badge` / `tooltip` / `tag` | `getByText('X')` |
-
-**Only add a YAML entry when** the auto-inferred locator won't work (wrong name, need testid, need nth, etc.).
+> ⚠️ **Auto-infer pitfall — the #1 cause of selector failures in production.**
+>
+> `[X] button` auto-infers as `getByRole('button', { name: 'X' })`. This **only works** when the button's accessible name in the DOM is **exactly `X`** — same language, same text, same casing.
+>
+> The Gherkin `[Reference]` is your human label for the element, **not** the DOM name. If the app is in Vietnamese (or any language where the Gherkin label differs from DOM text), auto-infer will produce `No element found` at runtime. **Write an explicit YAML entry** with the real DOM name instead.
+>
+> **Decision rule**: auto-infer is safe ONLY when you have confirmed in the snapshot that the DOM element's accessible name / placeholder text is literally `X`. When in doubt → write YAML.
+
+| Gherkin | Inferred locator | Safe when… |
+|---|---|---|
+| `[X] button` | `getByRole('button', { name: 'X' })` | Button's accessible name = X |
+| `[X] link` | `getByRole('link', { name: 'X' })` | Link text = X |
+| `[X] heading` / `header` | `getByRole('heading', { name: 'X' })` | Heading text = X |
+| `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` | Checkbox label = X |
+| `[X] radio` | `getByRole('radio', { name: 'X' })` | Radio label = X |
+| `[X] field` | `getByPlaceholder('X')` | Placeholder text = X AND field has a placeholder |
+| `[X] text` / `message` / `label` | `getByText('X')` | Visible text = X (partial match) |
+| `[X] logo/image/icon` | `getByRole('img', { name: 'X' })` | Image alt = X |
+| `[X] search` | `getByRole('searchbox', { name: 'X' })` | Searchbox label = X |
+| `[X] option` | `getByRole('option', { name: 'X' })` | Option text = X |
+| `[X] slider` | `getByRole('slider', { name: 'X' })` | Slider label = X |
+| `[X] toggle` | `getByRole('switch', { name: 'X' })` | Toggle label = X |
+| `[X] tab` | `getByRole('tab', { name: 'X' })` | Tab text = X |
+| `[X] table` | `getByRole('table', { name: 'X' })` | Table aria-label = X |
+| `[X] list` | `getByRole('list', { name: 'X' })` | List aria-label = X |
+| `[X] column` | `getByRole('columnheader', { name: 'X' })` | Column header text = X |
+| `[X] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'X' })` | Dialog aria-label/heading = X |
+| `[X] dropdown` / `select` | `getByRole('combobox', { name: 'X' })` | Combobox label = X |
+| `[X] menuitem` | `getByRole('menuitem', { name: 'X' })` | Menu item text = X |
+| `[X] progressbar` | `getByRole('progressbar', { name: 'X' })` | Progressbar label = X |
+| `[X] section` | `getByRole('region', { name: 'X' })` | Section aria-label = X |
+| `[X] card` | `getByRole('article', { name: 'X' })` | Card aria-label = X |
+| `[X] item` | `getByRole('listitem', { name: 'X' })` | List item text = X |
+| `[X] cell` | `getByRole('cell', { name: 'X' })` | Cell text = X |
+| `[X] spinner` | `getByRole('status', { name: 'X' })` | Spinner aria-label = X |
+| `[X] breadcrumb` | `getByRole('navigation', { name: 'X' })` | Navigation aria-label = X |
+| `[X] badge` / `tooltip` / `tag` | `getByText('X')` | Visible text = X |
+
+**Special note on `[X] field`**: `getByPlaceholder('X')` only works when (1) the field has a placeholder attribute AND (2) the placeholder text equals X. For fields without placeholders (floating labels, aria-label), write explicit YAML: `type: label, value: "Actual label text"`.
+
+**Only add a YAML entry when** auto-infer cannot work: DOM name differs from Gherkin label, need `testid`, need `nth`, need `exact: true`, or the field type requires explicit config.
 
 ### Types requiring YAML entry (no auto-infer)
 

package/dist/orchestrator/templates/qa-context.md

@@ -0,0 +1,90 @@
+# Project Context
+
+> Read by the AI before generating test cases for any screen in this project.
+> Fill in what applies — leave sections empty if not relevant.
+> **The more specific you are, the more accurate the generated test cases.**
+
+---
+
+## Project Overview
+
+**Application:**
+<!-- One sentence: what does this app do? -->
+<!-- Example: B2B award nomination platform for enterprise HR teams. -->
+
+**Target users:**
+<!-- Who uses this app and in what context? -->
+<!-- Example: HR managers submit nominations; employees view results. -->
+
+**Domain notes:**
+<!-- Key terminology, conventions, or constraints the AI should know. -->
+<!-- Example: "Nomination = an award record. Once submitted, status cannot revert to Draft." -->
+<!-- Example: "All monetary values are in JPY. No decimal places." -->
+
+---
+
+## Auth Roles
+
+> The AI maps these directly to `@auth:X` tags and generates permission-boundary test scenarios.
+> Leave the table empty (or delete it) if the app has no auth system.
+
+| Role | Can do | Cannot do |
+|------|--------|-----------|
+| | | |
+
+<!--
+Example:
+| Role    | Can do                                      | Cannot do                            |
+|---------|---------------------------------------------|--------------------------------------|
+| admin   | All CRUD, manage users, configure settings  | Nothing blocked                      |
+| manager | Create/edit records, view reports           | Delete records, manage users         |
+| staff   | View and submit own records only            | Edit others' records, view reports   |
+-->
+
+---
+
+## Testing Strategy
+
+**Focus areas** — what to cover thoroughly:
+<!-- List from: functional, security, ui, accessibility, performance -->
+<!-- Example: functional, security -->
+
+**Mandatory coverage:**
+<!-- Rules that override the AI's default tier decisions for every screen. -->
+<!-- Example: "Every screen with admin-only actions MUST have a non-admin blocked-access scenario." -->
+<!-- Example: "All free-text inputs MUST have XSS + SQL injection scenarios regardless of screen risk level." -->
+
+**Deprioritize / skip:**
+<!-- What to move to @low or skip entirely for this project. -->
+<!-- Example: "Skip VP-UI cosmetic checks (label/placeholder presence) — handled separately by design review." -->
+<!-- Example: "Skip accessibility scenarios — separate audit planned." -->
+
+---
+
+## Global Business Rules
+
+> Rules that apply across multiple screens.
+> The AI adds these to the Coverage Map for every screen as `[G]`-tagged Business rules.
+> Screen-specific rules belong in `requirements/spec.md`, not here.
+
+<!-- - Soft-delete only: records are never hard-deleted, only marked inactive -->
+<!-- - All timestamps stored in UTC, displayed in UTC+7 -->
+<!-- - Pagination default: 20 items per page; max 100 -->
+<!-- - File uploads: PNG/JPG/PDF only, max 5 MB -->
+<!-- - After any write operation, the list view must refresh automatically -->
+
+---
+
+## Error Message Patterns
+
+> If your app follows consistent validation error formats, list them here.
+> The AI uses these to fill `test-data.yaml` error keys when `spec.md` doesn't specify exact text.
+> Leave empty to let the AI infer from spec.md.
+
+- Required field: `<!-- "This field is required" -->`
+- Max length: `<!-- "Must be X characters or less" -->`
+- Min length: `<!-- "Must be at least X characters" -->`
+- Invalid format: `<!-- "Invalid format" -->`
+- Unique constraint: `<!-- "Already exists" -->`
+- Not found: `<!-- "Not found" -->`
+- Unauthorized: `<!-- "You do not have permission to perform this action" -->`

package/dist/orchestrator/templates/readme.md

@@ -12,14 +12,16 @@ sungen generate → compiles Gherkin + selectors + data → Playwright .spec.ts
 ## Directory Structure
 
 ```
-├── qa/screens/<name>/
-│   ├── features/         # .feature files (Gherkin)
-│   ├── selectors/        # Element locator YAML mappings
-│   ├── test-data/        # Test data YAML values
-│   └── requirements/     # Screen specs, UI designs, notes
-│       ├── spec.md       # Structured screen specification
-│       ├── ui/           # Screenshots, mockups, design images
-│       └── test-viewpoint.md      # Edge cases, decisions (optional)
+├── qa/
+│   ├── context.md        # Project-wide context: roles, testing strategy, global rules (fill once)
+│   ├── screens/<name>/
+│   │   ├── features/         # .feature files (Gherkin)
+│   │   ├── selectors/        # Element locator YAML mappings
+│   │   ├── test-data/        # Test data YAML values
+│   │   └── requirements/     # Screen specs, UI designs, notes
+│   │       ├── spec.md       # Structured screen specification
+│   │       ├── ui/           # Screenshots, mockups, design images
+│   │       └── test-viewpoint.md      # Edge cases, decisions (optional)
 ├── specs/
 │   └── generated/        # Auto-generated Playwright tests
 ├── .claude/
@@ -66,11 +68,12 @@ Scaffolds `qa/screens/<name>/` with empty feature, selectors, test-data, and req
 | `/sungen:create-test login` | `/sungen-create-test login` |
 
 AI acts as a **Senior QA Engineer**:
-1. Reads `requirements/spec.md` for screen specs (fields, validation, business rules, states)
-2. Optionally explores the live page via Playwright MCP to verify and supplement
-3. Identifies screen sections → asks user which to focus on
-4. Generates **20+ scenarios per viewpoint** (UI/UX, Validation, Logic, Security) for each section
-5. Confirms test plan before generating `.feature` + `test-data.yaml`
+1. Reads `qa/context.md` for project-wide context (roles, testing strategy, global rules)
+2. Reads `requirements/spec.md` for screen specs (fields, validation, business rules, states)
+3. Optionally explores the live page via Playwright MCP to verify and supplement
+4. Identifies screen sections → asks user which to focus on
+5. Generates **20+ scenarios per viewpoint** (UI/UX, Validation, Logic, Security) for each section
+6. Confirms test plan before generating `.feature` + `test-data.yaml`
 
 ### Step 3: Compile & run tests
 

package/package.json

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

package/src/orchestrator/project-initializer.ts

@@ -39,6 +39,9 @@ export class ProjectInitializer {
     // Create directories
     this.createDirectories();
 
+    // Create qa/context.md for QA lead to fill project-wide context
+    this.createContext();
+
     // Ensure package.json and install Playwright
     await this.setupDependencies();
 
@@ -363,6 +366,23 @@ export class ProjectInitializer {
 
   }
 
+  /**
+   * Create qa/context.md for the QA lead to fill project-wide context
+   * (roles, testing strategy, global rules, error patterns).
+   */
+  private createContext(): void {
+    const contextPath = path.join(this.cwd, 'qa', 'context.md');
+
+    if (fs.existsSync(contextPath)) {
+      this.skippedItems.push('qa/context.md');
+      return;
+    }
+
+    const content = this.readTemplate('qa-context.md');
+    fs.writeFileSync(contextPath, content, 'utf-8');
+    this.createdItems.push('qa/context.md');
+  }
+
   /**
    * Create specs/base.ts for shared browser context
    */

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

@@ -32,7 +32,15 @@ Parse **name** from `$ARGUMENTS`. If missing, ask the user.
    - If no → fresh creation. Use `AskUserQuestion` to ask generation scope:
      - **Tier 1 — Critical & High priority** — ~10-15 scenarios/section covering happy paths, core validation, security basics **(Recommended)**
      - **Full coverage — All tiers at once** — generates Tier 1 + 2 + 3 in one run. Large output (~40-60 scenarios/section), best for experienced users who want complete coverage immediately
-3. **Read requirements & resolve visual source** — check `qa/<screens|flows>/<name>/requirements/`:
+3. **Read project context + screen requirements**
+
+   **Project context** — check `qa/context.md` (project root, not screen-specific):
+   - If exists → read it. Extract: roles, testing strategy directives, global business rules, error patterns.
+   - Summarize what you found in one line (e.g. `"Roles: admin/staff/user | Strategy: focus security, skip VP-UI T1 | 2 global rules"`).
+   - These are carried into the Coverage Map when invoking `sungen-tc-generation`.
+   - If absent → continue without it, no action needed.
+
+   **Screen requirements** — check `qa/<screens|flows>/<name>/requirements/`:
    - If `spec.md` exists → read it as PRIMARY source (sections, fields, validation rules, business rules, states).
    - If `test-viewpoint.md` exists → read it. If it only contains HTML comments (scaffold template), use `AskUserQuestion` to ask:
      - **Fill test-viewpoint.md first** — I'll help you identify edge cases, known issues, and design decisions for this screen before generating tests

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

@@ -41,11 +41,13 @@ Skip this pre-flight when `--env` matches the base locale (no overlay needed in
    Phase 0 — Selector Generation decision tree
 
    Live page reachable? (URL provided and loads without error)
-     YES → existing flow: browser_navigate → one browser_snapshot → generate selectors.yaml (verified entries)
+     YES → existing flow: browser_navigate → wait for page to fully load (no spinner/skeleton/empty table) →
+            one browser_snapshot → cross-verify every [Reference] label vs snapshot name →
+            generate selectors.yaml (verified entries; explicit YAML for any label≠DOM-name mismatch)
      NO  → spec_figma.md exists in requirements/?
              YES → provisional flow (sungen-figma-source + sungen-selector-fix skills):
                    1. Read filtered Figma node data from spec_figma.md (## Components + ## Text Inventory)
-                   2. Apply selector heuristics from sungen-figma-source skill (testid > role+name > placeholder > label > locator > text)
+                   2. Apply selector priority from sungen-selector-fix § Step 3 (testid > role+name > label > placeholder > text > locator CSS last)
                    3. Write selectors.yaml — every provisional entry gets this comment on the line above:
                           # @needs-live-verify source=figma node_id=<id>
                    4. Compile: Screen: sungen generate --screen <name>. Flow: sungen generate --flow <name> — must succeed

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

@@ -55,13 +55,23 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
    - 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.
+5. **Snapshot**: Wait for the page to fully load before snapshotting.
+   - Check if the page is still loading (spinner visible, skeleton placeholders, empty table with 0 rows). If so, use `browser_wait_for` to wait until content is rendered.
+   - Then 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`).
+   - Selector priority: follow the table in **Diagnosis & Fix § Step 3** (`testid` > `role`+name > `label` > `placeholder` > `text` > `locator` CSS last resort).
    - 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.
    - **i18n sites**: if the site supports multiple languages, use `{{variable}}` in `name`/`value` fields instead of hardcoded text. Add corresponding `lbl_*` keys to `test-data.yaml` + locale overlay files (see `sungen-selector-keys` § i18n).
+   - **Selector quality rule**: the Playwright MCP accessibility tree snapshot gives you roles and accessible names directly — use them. Do NOT write XPath or class-based CSS selectors. Only write `type: locator` when no role/text/label/placeholder/testid is available, and restrict the CSS to `#id` or `[data-*]` / `[aria-*]` attribute selectors.
+6b. **Cross-verify Gherkin labels vs snapshot** (prevents the #1 production failure):
+   - For **every** `[Reference]` in the `.feature` that will rely on auto-infer (not written to YAML), check the snapshot:
+     - `[X] button` — is there a button with accessible name **exactly** `X`?
+     - `[X] field` — does an input have placeholder **exactly** `X`? Does it even have a placeholder?
+     - `[X] heading` / `text` / `message` — is that text literally visible in the snapshot?
+   - If any mismatch → write an explicit YAML entry using the real DOM name. Do not leave a mismatch to be caught at runtime.
+   - **Typical mismatch cases**: Gherkin uses English label (`[Submit]`) but app displays Vietnamese (`"Gửi"`); placeholder is descriptive (`"Nhập email của bạn"`) not a bare field name (`"Email"`); button text includes an icon glyph before/after the word.
 7. **Substring ambiguity check**: for each `role` + `name` selector, check if any other element in the snapshot has a name that **contains** this name as a substring (e.g., `"Đăng ký"` vs `"Đăng ký bằng Google"`). If yes → add `exact: true` to prevent strict mode violation at runtime.
 8. **Merge, don't overwrite**: preserve the page selector and any user-authored entries in `selectors.yaml`. Only add missing keys.
 9. **Show summary + confirm**: list the keys that will be added, ask the user to approve, then write the file.
@@ -69,9 +79,13 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
 
 ### Common Phase 0 pitfalls
 
-- Writing keys inferred from the Gherkin label instead of the snapshot name → Phase 1 will fail with "no element found".
+- 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.
+- Taking snapshot while page is still loading (spinner visible, table empty) → selectors for dynamic content will be missing or wrong.
+- Skipping step 6b for "simple" elements like buttons → silent mismatch between Gherkin label and DOM name fails at runtime.
 - Using `browser_evaluate` alone to scrape cookies → misses httpOnly session cookies. Always use `browser_storage_state` (or the `browser_run_code` fallback).
+- Writing XPath or class-based CSS selectors → breaks on DOM/style refactoring. Use role/testid/text/label/placeholder from the accessibility tree.
+- Falling back to `locator: 'div.some-class > span'` when the element IS visible in the accessibility snapshot with a role + name → the snapshot gives you `getByRole` for free; use it.
 - Overwriting user-authored selectors → always merge.
 
 ---
@@ -210,12 +224,24 @@ Selector priority (use first applicable):
 
 | Priority | type | When |
 |---|---|---|
-| 1 | `testid` | `data-testid` exists |
-| 2 | `role` + exact name | Interactive elements |
-| 3 | `placeholder` | Input with placeholder |
-| 4 | `label` | Form field with `<label>` |
-| 5 | `locator` (CSS) | No accessible name |
-| 6 | `text` | Static text only |
+| 1 | `testid` | `data-testid` or any stable test attribute exists |
+| 2 | `role` + exact name | Interactive elements with an accessible name |
+| 3 | `label` | Form field with a visible `<label>` |
+| 4 | `placeholder` | Input/textarea with a placeholder attribute |
+| 5 | `text` | Static visible text content |
+| 6 | `locator` (CSS) | Last resort — `#id` or `[attr=value]` **only** (see restrictions below) |
+
+> ⚠️ **Playwright best practice** ([source](https://playwright.dev/docs/best-practices#use-locators)): user-facing locators (`role`, `label`, `text`, `placeholder`, `testid`) are resilient to refactoring and far less likely to break. CSS class selectors and XPath break whenever a developer renames a class or restructures the DOM — even without changing the UI.
+>
+> **Never write these in `selectors.yaml`**:
+> - XPath: `xpath=//div[@class='...']` or `//button[contains(@class,'btn')]`
+> - Class-based CSS: `div.btn-primary`, `.modal-footer > .submit-btn`
+> - Deep structural CSS: `div:nth-child(3) > ul > li > button`
+>
+> **Acceptable CSS (last resort only)**:
+> - Stable `id`: `#submit-button` (only if the id is truly stable and not dynamic)
+> - Data attributes: `[data-id="123"]`, `[aria-controls="menu"]`
+> - Input type: `input[type="file"]` (when no testid/label exists)
 
 **Exact name rule**: copy name character-for-character from snapshot. Never infer from Gherkin label.
 
@@ -229,9 +255,9 @@ Common fixes:
 - Name mismatch → copy exact name from snapshot
 - Multiple matches → add `nth` or `exact: true`
 - Substring ambiguity (e.g., `"Submit"` matches `"Submit"` and `"Submit & Continue"`) → add `exact: true`
-- No accessible name → use `testid` or `locator` (CSS)
+- No accessible name → use `testid`; only fall back to `locator` CSS as last resort
 - Element in iframe → add `frame` field
-- Dynamic content → use `testid` or structural `role` + `nth`
+- Dynamic content → use `testid` or `role` + `nth`
 
 ### Step 4: Recompile After Fix
 
@@ -248,6 +274,26 @@ Then re-run only the current phase's failing tests, not all tests.
 
 ---
 
+## Common Failure Patterns
+
+Quick reference for the most frequent production failures:
+
+| Symptom | Root cause | Fix |
+|---------|-----------|-----|
+| `No element found` on button/link/heading | Gherkin `[Reference]` label ≠ DOM accessible name (different language or text) | Write explicit YAML: `type: role, value: button, name: "<exact DOM name>"` |
+| `No element found` on `[X] field` | Field has no placeholder, or placeholder ≠ X | Write explicit YAML: `type: label, value: "Actual label"` or `type: placeholder, value: "Actual placeholder"` |
+| `No element found` on `[X] text` / `message` | Visible text differs from Gherkin label, or text is dynamic | Write explicit YAML or use `{{variable}}` for dynamic content |
+| `strict mode violation` | Multiple elements match the same name/text | Add `exact: true` to YAML entry, or add `nth` |
+| `toBeVisible` timeout on dynamic content | Snapshot was taken while page was still loading | Wait for spinner/skeleton to clear before snapshotting; add `browser_wait_for` |
+| All tests fail with page navigate error | Page selector URL wrong or baseURL mismatch | Re-check `playwright.config.ts` `baseURL` and page selector `value` path |
+| Auth redirect on every test | `specs/.auth/<role>.json` missing or expired | Run Phase 0.5 to capture fresh session |
+| Table row assertions fail | `columns` config has wrong indices | Count column headers left-to-right (0-indexed) from snapshot |
+| Wrong text assertions on locale page | Hardcoded Vietnamese/English text in YAML `name`/`value` | Use `{{lbl_*}}` variables with locale overlay files |
+| Element inside iframe not found | `frame` field missing in YAML entry | Add `frame: "iframe[src*='...']"` to the selector entry |
+| Selector breaks after UI redesign with no functional change | CSS class or XPath used — brittle to style refactoring | Rewrite with `role`/`testid`/`label`/`text` from accessibility snapshot |
+
+---
+
 ## Table Selectors
 
 For table patterns, add table selectors with `columns` config:

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

@@ -166,37 +166,47 @@ Resolver searches in this order:
 
 If no YAML key exists, the resolver infers from the Gherkin element type:
 
-| Gherkin | Inferred locator |
-|---|---|
-| `[X] button` | `getByRole('button', { name: 'X' })` |
-| `[X] link` | `getByRole('link', { name: 'X' })` |
-| `[X] heading` / `header` | `getByRole('heading', { name: 'X' })` |
-| `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` |
-| `[X] radio` | `getByRole('radio', { name: 'X' })` |
-| `[X] field` | `getByPlaceholder('X')` |
-| `[X] text` / `message` / `label` | `getByText('X')` |
-| `[X] logo/image/icon` | `getByRole('img', { name: 'X' })` |
-| `[X] search` | `getByRole('searchbox', { name: 'X' })` |
-| `[X] option` | `getByRole('option', { name: 'X' })` |
-| `[X] slider` | `getByRole('slider', { name: 'X' })` |
-| `[X] toggle` | `getByRole('switch', { name: 'X' })` |
-| `[X] tab` | `getByRole('tab', { name: 'X' })` |
-| `[X] table` | `getByRole('table', { name: 'X' })` |
-| `[X] list` | `getByRole('list', { name: 'X' })` |
-| `[X] column` | `getByRole('columnheader', { name: 'X' })` |
-| `[X] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'X' })` |
-| `[X] dropdown` / `select` | `getByRole('combobox', { name: 'X' })` |
-| `[X] menuitem` | `getByRole('menuitem', { name: 'X' })` |
-| `[X] progressbar` | `getByRole('progressbar', { name: 'X' })` |
-| `[X] section` | `getByRole('region', { name: 'X' })` |
-| `[X] card` | `getByRole('article', { name: 'X' })` |
-| `[X] item` | `getByRole('listitem', { name: 'X' })` |
-| `[X] cell` | `getByRole('cell', { name: 'X' })` |
-| `[X] spinner` | `getByRole('status', { name: 'X' })` |
-| `[X] breadcrumb` | `getByRole('navigation', { name: 'X' })` |
-| `[X] badge` / `tooltip` / `tag` | `getByText('X')` |
-
-**Only add a YAML entry when** the auto-inferred locator won't work (wrong name, need testid, need nth, etc.).
+> ⚠️ **Auto-infer pitfall — the #1 cause of selector failures in production.**
+>
+> `[X] button` auto-infers as `getByRole('button', { name: 'X' })`. This **only works** when the button's accessible name in the DOM is **exactly `X`** — same language, same text, same casing.
+>
+> The Gherkin `[Reference]` is your human label for the element, **not** the DOM name. If the app is in Vietnamese (or any language where the Gherkin label differs from DOM text), auto-infer will produce `No element found` at runtime. **Write an explicit YAML entry** with the real DOM name instead.
+>
+> **Decision rule**: auto-infer is safe ONLY when you have confirmed in the snapshot that the DOM element's accessible name / placeholder text is literally `X`. When in doubt → write YAML.
+
+| Gherkin | Inferred locator | Safe when… |
+|---|---|---|
+| `[X] button` | `getByRole('button', { name: 'X' })` | Button's accessible name = X |
+| `[X] link` | `getByRole('link', { name: 'X' })` | Link text = X |
+| `[X] heading` / `header` | `getByRole('heading', { name: 'X' })` | Heading text = X |
+| `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` | Checkbox label = X |
+| `[X] radio` | `getByRole('radio', { name: 'X' })` | Radio label = X |
+| `[X] field` | `getByPlaceholder('X')` | Placeholder text = X AND field has a placeholder |
+| `[X] text` / `message` / `label` | `getByText('X')` | Visible text = X (partial match) |
+| `[X] logo/image/icon` | `getByRole('img', { name: 'X' })` | Image alt = X |
+| `[X] search` | `getByRole('searchbox', { name: 'X' })` | Searchbox label = X |
+| `[X] option` | `getByRole('option', { name: 'X' })` | Option text = X |
+| `[X] slider` | `getByRole('slider', { name: 'X' })` | Slider label = X |
+| `[X] toggle` | `getByRole('switch', { name: 'X' })` | Toggle label = X |
+| `[X] tab` | `getByRole('tab', { name: 'X' })` | Tab text = X |
+| `[X] table` | `getByRole('table', { name: 'X' })` | Table aria-label = X |
+| `[X] list` | `getByRole('list', { name: 'X' })` | List aria-label = X |
+| `[X] column` | `getByRole('columnheader', { name: 'X' })` | Column header text = X |
+| `[X] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'X' })` | Dialog aria-label/heading = X |
+| `[X] dropdown` / `select` | `getByRole('combobox', { name: 'X' })` | Combobox label = X |
+| `[X] menuitem` | `getByRole('menuitem', { name: 'X' })` | Menu item text = X |
+| `[X] progressbar` | `getByRole('progressbar', { name: 'X' })` | Progressbar label = X |
+| `[X] section` | `getByRole('region', { name: 'X' })` | Section aria-label = X |
+| `[X] card` | `getByRole('article', { name: 'X' })` | Card aria-label = X |
+| `[X] item` | `getByRole('listitem', { name: 'X' })` | List item text = X |
+| `[X] cell` | `getByRole('cell', { name: 'X' })` | Cell text = X |
+| `[X] spinner` | `getByRole('status', { name: 'X' })` | Spinner aria-label = X |
+| `[X] breadcrumb` | `getByRole('navigation', { name: 'X' })` | Navigation aria-label = X |
+| `[X] badge` / `tooltip` / `tag` | `getByText('X')` | Visible text = X |
+
+**Special note on `[X] field`**: `getByPlaceholder('X')` only works when (1) the field has a placeholder attribute AND (2) the placeholder text equals X. For fields without placeholders (floating labels, aria-label), write explicit YAML: `type: label, value: "Actual label text"`.
+
+**Only add a YAML entry when** auto-infer cannot work: DOM name differs from Gherkin label, need `testid`, need `nth`, need `exact: true`, or the field type requires explicit config.
 
 ### Types requiring YAML entry (no auto-infer)
 

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

@@ -105,6 +105,14 @@ Auto-detected by `create-test` before invoking this skill:
   2. Each row / bullet / item = 1 viewpoint → add to `Viewpoint items` in Coverage Map.
   3. Do NOT pre-classify into buckets before scanning — classify only when
      writing the scenario.
+- `qa/context.md` — project-wide context set by the QA lead. Read ONCE before building the Coverage Map; apply to every screen. Extraction rules:
+  - **Roles** → for each role in the table: add to the `@auth:X` tag pool; generate a VP-SEC blocked-access scenario for every role boundary relevant to this screen.
+  - **Testing strategy → Focus areas** → if `security` listed: VP-SEC is mandatory Tier 1 for every free-text input regardless of spec risk level; if `ui` not listed: all VP-UI scenarios move to Tier 2 minimum.
+  - **Testing strategy → Mandatory coverage** → each line is a hard override applied to this screen regardless of spec risk; document in `Context constraints` of the Coverage Map.
+  - **Testing strategy → Deprioritize/skip** → record in `Context constraints`; suppress those VP categories from Tier 1 generation.
+  - **Global business rules** → add each to the `Business rules` section tagged `[G]` (e.g. `[G1 – soft-delete only]`); treat as `HIGH` risk unless stated otherwise.
+  - **Error patterns** → use as fallback only when `spec.md` does not give exact error text; never override spec-specified messages.
+  - If `qa/context.md` is absent: proceed without it — no impact on the generation flow.
 
 **Single screen focus**: one URL = one screen. Modals on same page = part of this screen.
 This means: do not test other screens' UI layout or navigation. It does NOT mean skip documenting business outcomes that your screen's actions cause on other surfaces. Those cross-surface outcomes must appear in the Coverage Map and be covered by at least `@manual` scenarios.
@@ -129,6 +137,11 @@ Read `spec.md` fully, then extract into a Coverage Map **before writing any scen
 **Risk tags:** HIGH = complex business rules, cascading fields, multi-step state changes, auth/integration. LOW = display-only, static labels, read-only fields.
 
 ```
+Context constraints: [populated from qa/context.md before writing any scenario]
+                     roles: [list roles, e.g. admin / manager / staff]
+                     strategy: [active overrides, e.g. "VP-SEC mandatory T1", "VP-UI → T2 only"]
+                     global rules: [G1 – ...] → also appear in Business rules below tagged [G]
+                     → leave empty if qa/context.md is absent or has no entries applicable to this screen
 User journeys:       [J1 – ...], [J2 – ...]
 Validation rules:    [V1 – field → "exact error text"], [V2 – ...]
 Business rules:      [B1 HIGH – ...], [B2 LOW – ...]

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

@@ -27,7 +27,15 @@ You are a **Senior QA Engineer**. You structure test cases by viewpoint categori
    - If no → fresh creation. Ask generation scope:
      - **1) Tier 1 — Critical & High priority** — ~10-15 scenarios/section covering happy paths, core validation, security basics **(Recommended)**
      - **2) Full coverage — All tiers at once** — generates Tier 1 + 2 + 3 in one run. Large output (~40-60 scenarios/section), best for experienced users who want complete coverage immediately
-3. **Read requirements & resolve visual source** — check `<base>/${input:name}/requirements/`:
+3. **Read project context + screen requirements**
+
+   **Project context** — check `qa/context.md` (project root, not screen-specific):
+   - If exists → read it. Extract: roles, testing strategy directives, global business rules, error patterns.
+   - Summarize what you found in one line (e.g. `"Roles: admin/staff/user | Strategy: focus security, skip VP-UI T1 | 2 global rules"`).
+   - These are carried into the Coverage Map when invoking the `sungen-tc-generation` skill.
+   - If absent → continue without it, no action needed.
+
+   **Screen requirements** — check `<base>/${input:name}/requirements/`:
    - If `spec.md` exists → read it as PRIMARY source (sections, fields, validation rules, business rules, states).
    - If `test-viewpoint.md` exists → read it. If it only contains HTML comments (scaffold template), ask:
      - **1) Fill test-viewpoint.md first** — identify edge cases, known issues, and design decisions before generating tests

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

@@ -41,11 +41,13 @@ Skip when `--env` matches the base locale.
    Phase 0 — Selector Generation decision tree
 
    Live page reachable? (URL provided and loads without error)
-     YES → existing flow: browser_navigate → one browser_snapshot → generate selectors.yaml (verified entries)
+     YES → existing flow: browser_navigate → wait for page to fully load (no spinner/skeleton/empty table) →
+            one browser_snapshot → cross-verify every [Reference] label vs snapshot name →
+            generate selectors.yaml (verified entries; explicit YAML for any label≠DOM-name mismatch)
      NO  → spec_figma.md exists in requirements/?
              YES → provisional flow (sungen-figma-source + sungen-selector-fix skills):
                    1. Read filtered Figma node data from spec_figma.md (## Components + ## Text Inventory)
-                   2. Apply selector heuristics from sungen-figma-source skill (testid > role+name > placeholder > label > locator > text)
+                   2. Apply selector priority from sungen-selector-fix § Step 3 (testid > role+name > label > placeholder > text > locator CSS last)
                    3. Write selectors.yaml — every provisional entry gets this comment on the line above:
                           # @needs-live-verify source=figma node_id=<id>
                    4. Compile: Screen: sungen generate --screen <name>. Flow: sungen generate --flow <name> — must succeed