@sun-asterisk/sungen 2.7.0-beta.0 → 3.0.0-beta.71

package/{dist/orchestrator/templates/ai-instructions/copilot-skill-figma-source.md → src/orchestrator/templates/ai-instructions/claude-skill-capture-mode-figma-pat.md}

@@ -1,18 +1,6 @@
----
-name: sungen-figma-source
-description: 'Figma URL → spec_figma.md envelope + LLM-synthesized narrative from cached raw node JSON. Auto-loaded when --figma flag present or spec_figma.md exists.'
-user-invocable: false
----
+# Capture mode: figma-pat
 
-## When This Skill Loads
-
-Auto-load triggers (any one is sufficient):
-
-- Any sungen AI command invoked with `--figma` flag
-- `requirements/spec_figma.md` exists in the screen directory
-- User mentions a Figma URL or says "generate from Figma"
-
----
+Figma URL → `spec_figma.md` envelope + LLM-synthesized narrative from cached raw node JSON. This mode is the active one when any of these is true: a sungen command was invoked with `--figma`, `requirements/spec_figma.md` exists, or the user says "generate from Figma".
 
 ## Prerequisites
 
@@ -22,8 +10,6 @@ Auto-load triggers (any one is sufficient):
 
 **Never paste the PAT into any transcript, spec file, or commit.**
 
----
-
 ## Two-Layer Architecture
 
 `spec_figma.md` has two layers separated by the `<!-- SYNTHESIS-BELOW -->` marker:
@@ -31,34 +17,27 @@ Auto-load triggers (any one is sufficient):
 | Layer | Producer | Overwrite Rule |
 |---|---|---|
 | **Envelope** (above marker) | sungen CLI | Regenerated each `sungen figma` run — deterministic |
-| **Narrative** (below marker) | This skill (LLM) | Replaced on re-synthesis — everything from marker to EOF |
+| **Narrative** (below marker) | This mode (LLM) | Replaced on re-synthesis — everything from marker to EOF |
 
 The envelope contains: YAML frontmatter, Frame metadata, Screenshots. The narrative is synthesized by YOU from the cached raw Figma node JSON.
 
----
-
 ## Inputs You Read
 
 The scaffolder persists a raw (unfiltered) Figma node tree to:
-
 ```
 .sungen/figma-cache/<fileKey>/<versionId>/<nodeId>-raw.json
 ```
-
 Read this file + the envelope frontmatter of `requirements/spec_figma.md` + any PNGs under `requirements/ui/`. You MUST NOT call the Figma REST API directly — the PAT is not available to you.
 
----
-
 ## Synthesis Task
 
-Append 7 narrative sections below `<!-- SYNTHESIS-BELOW -->`. Each section is inferred from the raw node tree (names, types, `characters`, layout bounds, auto-layout direction, componentProperties):
+Append 7 narrative sections below `<!-- SYNTHESIS-BELOW -->`. Each is inferred from the raw node tree (names, types, `characters`, layout bounds, auto-layout direction, componentProperties):
 
 ### 1. Purpose
 One paragraph. What screen is this? Primary user goal? Infer from frame name + top-level text + dominant CTA.
 
 ### 2. ASCII Layout
-Rough spatial sketch using box characters. Reflect top-bottom / left-right ordering from absoluteBoundingBox. Keep under ~20 lines. Example:
-
+Rough spatial sketch using box characters. Reflect top-bottom / left-right ordering from absoluteBoundingBox. Keep under ~20 lines:
 ```
 ┌──────────────────────────────────────┐
 │ [Logo]                     [Sign In] │
@@ -72,55 +51,46 @@ Rough spatial sketch using box characters. Reflect top-bottom / left-right order
 ```
 
 ### 3. Regions
-Bulleted list of the major layout regions (header, sidebar, main, footer, modal, etc.) with a one-line purpose each. Use auto-layout frames as region hints.
+Bulleted list of major layout regions (header, sidebar, main, footer, modal…) with a one-line purpose each. Use auto-layout frames as region hints.
 
 ### 4. Actions
-Every interactive element the user can trigger. Derive from nodes whose name/type suggests a button, link, icon-button, menu-item, toggle, etc. Format:
-
+Every interactive element the user can trigger (button, link, icon-button, menu-item, toggle…):
 ```
 - **<Action name>** — <what it does> (source: <node name>)
 ```
 
 ### 5. Form Fields
-Every input the user can fill. Include label, type (text/email/password/select/checkbox/radio/textarea/date), required hint if inferable, and placeholder.
-
+Every input. Include label, type (text/email/password/select/checkbox/radio/textarea/date), required hint if inferable, placeholder:
 ```
 | Label | Type | Required | Placeholder |
 |---|---|---|---|
 ```
-
-Omit entirely (write `_none_`) if no inputs exist.
+Omit (write `_none_`) if no inputs exist.
 
 ### 6. Data Columns
-If the screen shows a table, list, or card grid — enumerate the columns/fields displayed per row. Otherwise write `_none_`.
+If the screen shows a table/list/card grid — enumerate the columns/fields per row. Otherwise `_none_`.
 
 ### 7. Navigation
-Outgoing links, tab bars, breadcrumbs, back buttons — anything that moves the user to another screen. Include both explicit navigation components and implicit CTAs that navigate.
-
----
+Outgoing links, tab bars, breadcrumbs, back buttons — anything that moves to another screen. Include explicit nav components and implicit CTAs that navigate.
 
 ## Synthesis Workflow
 
 1. Read `requirements/spec_figma.md` — note `file_key`, `node_id`, `figma_version_id` from frontmatter
 2. Read `.sungen/figma-cache/<file_key>/<figma_version_id>/<safe_node_id>-raw.json` (colons in node_id become underscores)
-3. Traverse the tree. Collect: names, types, `characters`, `componentProperties`, `absoluteBoundingBox`
+3. Traverse the tree. Collect names, types, `characters`, `componentProperties`, `absoluteBoundingBox`
 4. Produce the 7 sections above
 5. **Locate the insertion point** in `spec_figma.md`:
    - **If `<!-- SYNTHESIS-BELOW -->` is present** → replace everything from the marker (inclusive) to EOF with: the marker line, a blank line, then the 7 sections.
-   - **If the marker is NOT present** (older `spec_figma.md` pre-envelope-refactor, or hand-edited file) → locate the last non-empty line of the envelope (usually the end of `## Screenshots`), append a blank line, then write the marker, another blank line, then the 7 sections. Do NOT delete any existing envelope content.
+   - **If the marker is NOT present** (older file or hand-edited) → locate the last non-empty line of the envelope (usually the end of `## Screenshots`), append a blank line, then the marker, another blank line, then the 7 sections. Do NOT delete any envelope content.
    - **If the file is missing entirely** → advise the user to re-run `sungen add --screen <screen> --figma <url> --refresh` to regenerate the envelope first. Do not fabricate one.
 6. Preserve the envelope (frontmatter + Frame + Screenshots) byte-for-byte. Never touch content above the marker.
 
----
-
 ## Re-synthesis
 
 - If the envelope's `figma_version_id` changed → envelope is fresh; re-run synthesis
-- If only the narrative is stale (user wants a rewrite) → truncate from marker to EOF and regenerate
+- If only the narrative is stale → truncate from marker to EOF and regenerate
 - Never edit content ABOVE the marker — that is the scaffolder's territory
 
----
-
 ## Selector Heuristics (for downstream `run-test`)
 
 During `run-test` Phase 0, provisional selectors can be seeded from the raw JSON:
@@ -135,15 +105,11 @@ During `run-test` Phase 0, provisional selectors can be seeded from the raw JSON
 | Node name ends `Icon` | `role: img` + `name: "<accessible name>"` |
 
 Every provisional entry MUST carry:
-
 ```
 # @needs-live-verify source=figma node_id=<id>
 ```
-
 Provisional selectors feed `selectors.yaml` as candidates. `run-test` Phase 0 verifies them against the live page and overwrites incorrect entries.
 
----
-
 ## Security
 
 - Never include the PAT in `spec_figma.md`, selectors, test data, or any committed file

package/src/orchestrator/templates/ai-instructions/claude-skill-capture-mode-live.md

@@ -0,0 +1,60 @@
+# Capture mode: live
+
+Navigate a running application, take **one accessibility snapshot** and **one screenshot**, and save them as visual context for test generation. Use when the app is live (dev, staging, or production with read-only access) and you want tests grounded in the actual rendered UI. Handles auth gracefully: if the page redirects to login, ask the user to sign in manually rather than injecting cookies.
+
+## Prerequisites
+
+- Playwright MCP connected.
+- Dev/staging server reachable (or a public URL).
+- `playwright.config.ts` exists at the project root (for `baseURL` fallback).
+
+## Steps
+
+### 1. Resolve target URL
+
+1. `Live URL` field in `requirements/spec.md` (Overview section)
+2. `baseURL` from `playwright.config.ts` + `URL Path` from `spec.md`
+3. Neither → `AskUserQuestion`: *"Paste the full URL for the page to scan"*
+
+### 2. Navigate
+
+`browser_navigate` to the resolved URL.
+
+### 3. Handle auth redirect
+
+If the page redirects to a login route (URL contains `/login`, `/signin`, `/auth`, or content indicates a login screen):
+1. Tell the user which login URL they landed on.
+2. `AskUserQuestion`:
+   - **I'll log in manually** — wait for confirmation, then re-navigate to the target URL
+   - **Skip live scan** — switch to mode `local`
+   - **Cancel**
+3. **Never** inject cookies or localStorage via `browser_evaluate` / `browser_run_code`. Auth belongs to the user.
+
+### 4. Snapshot
+
+Take **ONE** `browser_snapshot`. This accessibility tree is the primary AI context — roles, names, text, structure that tc-generation uses to identify sections and fields.
+
+### 5. Screenshot (recommended)
+
+Take **ONE** `browser_take_screenshot` with `fullPage: true`. Save to `requirements/ui/live-<timestamp>.png`, where `<timestamp>` is `YYYYMMDD-HHMM` local time (e.g. `live-20260421-1430.png`).
+
+### 6a. Verify unauthenticated redirect target (flow capture only)
+
+When capturing for a **flow** with security scenarios (e.g. "unauthenticated user cannot access X"):
+1. Open a **fresh incognito/unauthenticated** context (no storage state).
+2. `browser_navigate` to the protected route.
+3. Record the **actual redirect URL** — do NOT assume `/login`; it may be `/register`, `/`, etc.
+4. Report the redirect target: *"Unauthenticated access to `/dashboard` redirects to `/register`"*.
+5. The caller must use the **actual redirect URL** in Gherkin assertions, never an assumed one.
+
+Skip if the flow has no security scenarios or the user says to skip.
+
+### 6. Detect discrepancies vs spec
+
+If `spec.md` exists, cross-check the snapshot against spec sections: fields in spec but not in snapshot → *missing in UI*; elements in snapshot but not in spec → *missing in spec*. Report findings but **do not** auto-edit `spec.md`.
+
+### 7. Report back
+
+> Captured live page `<URL>`: Snapshot N interactive elements · Screenshot `requirements/ui/live-<timestamp>.png` · Discrepancies vs spec: <count or "none">
+
+Hand back to the calling command. Scans **exactly one** page per invocation.

package/src/orchestrator/templates/ai-instructions/claude-skill-capture-mode-local.md

@@ -0,0 +1,38 @@
+# Capture mode: local
+
+Use **pre-existing images** in `requirements/ui/` as visual context. No network, no MCP, no live site — works for any design tool (Figma export, Sketch, Penpot, Zeplin, hand-drawn, staging screenshots). This is the **baseline fallback**: if the live domain is down and Figma MCP isn't configured, this always works as long as the user drops images in the folder.
+
+## Steps
+
+### 1. List available images
+
+Glob `requirements/ui/*.{png,jpg,jpeg,webp,gif}` and report count + filenames. Filter out metadata files (e.g. `figma-meta.md` written by mode figma-mcp) — those are read by `tc-generation` separately, not treated as images here.
+
+### 2. Handle empty folder
+
+If no images found:
+1. Tell the user the folder is empty, with the full path so they can open it in Finder.
+2. `AskUserQuestion`:
+   - **I'll drop images now** — wait for confirmation, then re-glob
+   - **Switch to Figma** — switch to mode `figma-mcp`
+   - **Switch to live page scan** — switch to mode `live`
+   - **Cancel** — abort create-test
+3. If "drop images now", wait for confirmation (e.g. "done") then re-run step 1.
+
+### 3. Read images for context
+
+Use the `Read` tool on each image — Claude Code reads PNG/JPG/WebP directly as visual context. For large sets (>10 images), ask which are primary and which are states/variants to avoid loading too much at once.
+
+### 4. Summarize
+
+> Loaded N image(s) from `requirements/ui/`:
+> - `<filename-1>` — <one-line description of what's visible>
+> - `<filename-2>` — <one-line description>
+
+Hand back to the calling command.
+
+## File naming hints for users
+
+Nudge users toward consistent filenames (don't enforce):
+- `<section>-default.png` / `-error.png` / `-loading.png` / `-empty.png` — section states
+- `full-page.png` / `viewport.png` — whole screen (auto-generated by `sungen add --capture`)

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

@@ -0,0 +1,35 @@
+---
+name: sungen-capture
+description: 'Acquire visual/design context for test generation from one of four sources (modes): figma-mcp, figma-pat, live, local. Auto-loaded by create-test/add-screen when a visual source is needed, or when --figma flag / spec_figma.md is present. Router skill — read only the mode file you need.'
+user-invocable: false
+---
+
+## Purpose
+
+Bring **visual + design context** into test generation so `sungen-tc-generation` can author Gherkin + test-data grounded in the real UI. This is a **router**: pick exactly **one mode** for the run, then read only that mode's file. Do **not** read all four.
+
+This skill never generates Gherkin or `selectors.yaml` — it only acquires context and reports back to the calling command.
+
+## Pick the mode
+
+| Mode | Read | Use when | Needs |
+|---|---|---|---|
+| **figma-mcp** | `mode-figma-mcp.md` | Pre-launch / Figma is source of truth, **Figma Dev Mode MCP** connected | Figma MCP + frame URL |
+| **figma-pat** | `mode-figma-pat.md` | `--figma` flag was used, or `requirements/spec_figma.md` exists (synthesize narrative from cached raw node JSON) | `sungen figma auth` PAT |
+| **live** | `mode-live.md` | App is running (dev/staging/prod read-only) and you want the actual rendered UI | Playwright MCP + reachable URL |
+| **local** | `mode-local.md` | Images already dropped in `requirements/ui/` (any design tool, screenshots, mockups) — baseline fallback, no network | nothing |
+
+### How the mode is chosen (when the caller didn't specify)
+
+1. `requirements/spec_figma.md` exists → **figma-pat** (PAT flow already ran during `add-screen`).
+2. `requirements/ui/` has images → **local**.
+3. Neither → ask the user which source (figma-mcp / live / local), then load that one mode file.
+
+Modes are **mutually exclusive per run**, but the user can run `create-test` again with a different mode to layer context. All modes write to `requirements/ui/` and report back.
+
+## What this skill (any mode) does NOT do
+
+- Does not generate Gherkin — that's `sungen-tc-generation`.
+- Does not write `selectors.yaml` — that's `/sungen:run-test`.
+- Does not inject auth/cookies — the user logs in manually (see `live`).
+- Does not crawl or generate images.

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

@@ -0,0 +1,84 @@
+---
+name: sungen-harness-audit
+description: 'How to read `sungen audit` output and repair test-design findings. Auto-loaded by the design orchestrator.'
+user-invocable: false
+---
+
+## What `sungen audit` measures
+
+`sungen audit --screen <name>` runs deterministic sensors over `features/<name>.feature` + `requirements/test-viewpoint.md` and writes `.sungen/reports/<name>-audit.json`. It is the **gate** the orchestrator repairs against. Run with `--json` to parse it.
+
+### Report shape (key fields)
+```jsonc
+{
+  "score": { "overall": 3.9, "coverage": 0.4, "businessDepth": 0.18, "balance": 0.5, "traceability": 0.7 },
+  "gateStatus": "PASS" | "FAIL",
+  "gate": { "pageType": "ecommerce-list", "themesCovered": 2, "themesTotal": 5,
+            "gaps": [ { "theme": "cart-correctness", "keywords": [...] } ] },
+  "depth": { "businessCriticalShallow": 9, "businessCriticalTotal": 11,
+             "shallowBusinessCritical": [ { "name": "...", "category": "PRODUCT" } ] },
+  "balance": { "imbalanced": true, "coreCount": 11, "secondaryCount": 22, "byBucket": {...} },
+  "duplicates": { "clusters": [ { "sameDataLikely": false, "scenarios": [...] } ] },
+  "trace": { "mappedRatio": 0.4, "note": "..." },
+  "findings": [ "GATE: ...", "DEPTH: ...", "BALANCE: ...", "TRACE: ..." ]
+}
+```
+- **`overall` score is business-weighted** (coverage 0.4 + businessDepth 0.3 + balance 0.15 + traceability 0.15). It is intentionally strict on business value — a high count with shallow business coverage scores low. Don't optimize the count; optimize coverage + depth.
+- Exit code **2** when `gateStatus == FAIL` (usable in CI / loop).
+
+## Finding → repair mapping
+
+| Finding prefix | Meaning | Repair action |
+|---|---|---|
+| **GATE** | a critical theme for the page-type has no covering scenario | Generate scenarios for that theme. **If cross-screen** (cart-correctness, product-detail-consistency, filter-result-correctness, multi-item cart) → do NOT fake it on a single screen; plan a **flow** (`/sungen:add-flow`) and record the deferral. |
+| **DEPTH** | business-critical scenarios assert only visibility/navigation | Replace `Then User see [X] page/section` with **observable data assertions**: `Then User see [X] with {{value}}`, `Then User see [T] table match data:`. Capture real expected values into `test-data.yaml`. |
+| **BALANCE** | secondary viewpoints (UI/validation/security) outweigh business-core | **Stop expanding** secondary viewpoints; generate the missing business-core scenarios first. Do not add more subscription/UI variants while core is thin. |
+| **TRACE** | scenarios use ad-hoc `VP-<CAT>-NNN` codes not linked to the viewpoint-overview | Make each scenario map to a viewpoint-overview id (align category codes, or add a mapping comment). |
+| **UNIVERSAL** | a universal theme (error/empty-state, accessibility) is absent | Low priority — add if in scope; otherwise note as out-of-scope with reason. |
+
+## P5 steps for deep cross-screen / list coverage
+
+Use these when repairing GATE/DEPTH findings for the hard viewpoints (cart/detail/filter correctness). They need **runtime data mode** (the default).
+
+- **Capture a value to compare across screens** (product-detail-consistency, cart-correctness):
+  ```gherkin
+  When User remember [Product Name] text as {{selected_product_name}}
+  And User remember [Product Price] text as {{selected_product_price}}
+  And User click [View Product] link
+  Then User see [Detail Product Name] header with {{selected_product_name}}
+  And User see [Detail Product Price] text with {{selected_product_price}}
+  ```
+  `remember` stores the element's text/value at runtime; later `{{var}}` resolves to it. This proves the detail/cart shows the SAME product, not a random one.
+
+- **Assert every item in a result matches** (category/brand-filter-correctness):
+  ```gherkin
+  When User click [Women] link
+  And User click [Dress] link
+  Then User see all [Result Product Name] contain {{selected_category}}
+  ```
+  `see all [X] contain {{v}}` asserts EVERY matching element contains the value → "all displayed products belong to the selected category/brand", not just one.
+
+> Cross-screen flows (home → detail/cart): if the target screen is a separate screen, prefer a **flow** (`/sungen:add-flow`) so the journey is one test. On a single screen, keep the cross-screen assertion but tag `@manual` with a `# Deferred to a flow` comment.
+
+## Repair loop rules
+
+1. **Budget = 3 rounds.** Re-run `sungen audit` after each repair; track score delta.
+2. **Stop when** `gateStatus == PASS` AND `findings` empty — or budget exhausted.
+3. **Never fake a pass.** A shallow `see [Cart] page` does not satisfy `cart-correctness`. If a gap is genuinely cross-screen or needs capabilities the DSL lacks (e.g. capture an element value to compare elsewhere), **report it as a residual gap / flow item** instead of forcing a green gate.
+4. **EP/data families are OK.** A `duplicates` cluster with `sameDataLikely=false` is an intentional equivalence-partition family (e.g. many invalid-email cases) — keep it; only collapse `sameDataLikely=true` exact duplicates.
+
+## Discovery / fallback tree (when input is limited)
+
+```
+spec.md đủ tốt?      → YES: Spec-first
+  │ NO
+source code có?      → YES: Source-first (mine behavior từ code)
+  │ NO
+testcase cũ tương tự?→ YES: History-first
+  │ NO
+domain rủi ro+defect?→ YES: Defect-first
+  │ NO
+→ hỏi QA; QA chưa phản hồi → OUTPUT kèm ASSUMPTION LIST rõ ràng (không stall)
+```
+
+See `docs/orchestration-spec.md` for the full flow and `reports/sungen_refactor_spec.md` for the design rationale.

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)