@sun-asterisk/sungen 3.2.9 → 3.2.10-beta.11

package/src/generators/test-generator/utils/selector-resolver.ts

@@ -5,6 +5,8 @@ import { readYaml, readYamlIfExists } from '../../../utils/yaml-io';
 
 import { SelectorType } from '../../../utils/selector-types';
 import { DataResolver } from './data-resolver';
+import { DiagnosticsCollector } from '../diagnostics';
+import { DEFAULT_CONTENT_NAMED_ROLES } from '../app-profile';
 
 // Structured selector format v2
 interface SelectorEntry {
@@ -27,7 +29,9 @@ interface SelectorEntry {
   ios?: SelectorEntry;
 
   // === v2: Complex Elements ===
-  variant?: 'native' | 'custom' | 'dragdrop';  // Dropdown/upload subtype
+  // Dropdown/upload subtype: 'native' | 'custom' | 'dragdrop', or a widget-recipe/variant
+  // name ('radix-select', 'office-datepicker', …) — wins over qa/app.yaml widgets.<kind>.
+  variant?: string;
   trigger?: string;       // Visible button that triggers hidden file input
   frame?: string;         // iframe selector for cross-frame elements
   contenteditable?: boolean;  // Rich text editor (contenteditable div)
@@ -96,7 +100,7 @@ export interface ResolvedSelector {
   // === v2 fields ===
   scope?: string;       // Parent landmark to scope within
   match?: 'exact' | 'partial';  // For getByText exact matching
-  variant?: 'native' | 'custom' | 'dragdrop';  // Dropdown/upload type
+  variant?: string;     // Dropdown/upload subtype or widget-recipe name
   trigger?: string;     // Button that triggers hidden file input
   frame?: string;       // iframe selector
   contenteditable?: boolean;  // Rich text editor
@@ -117,12 +121,26 @@ export class SelectorResolver {
   private featureName?: string;
   private screenName?: string;
   private flowMode: boolean = false;
+  /** SG-W003 channel + config: roles whose accessible name derives from content. */
+  private diagnostics?: DiagnosticsCollector;
+  private contentNamedRoles: string[] = DEFAULT_CONTENT_NAMED_ROLES;
+  private warnedContentNamed = new Set<string>();
 
   constructor(selectorsDir?: string, screenName?: string) {
     this.selectorsDir = selectorsDir || path.join(process.cwd(), 'qa', 'selectors', 'screens');
     this.screenName = screenName;
   }
 
+  /** Attach the compile-diagnostics collector (SG-W003) */
+  setDiagnostics(collector: DiagnosticsCollector): void {
+    this.diagnostics = collector;
+  }
+
+  /** Override the name-from-content role list from the app profile (qa/app.yaml feedback.toast) */
+  setContentNamedRoles(roles: string[]): void {
+    this.contentNamedRoles = roles;
+  }
+
   setFlowMode(enabled: boolean): void {
     this.flowMode = enabled;
   }
@@ -390,6 +408,20 @@ export class SelectorResolver {
     if (elementType) {
       const inferred = SelectorResolver.inferFromElementType(elementType, displayLabel);
       if (inferred) {
+        // Same SG-W003 class as the explicit-entry path: an auto-inferred name on a
+        // name-from-content role ([Loading] spinner → getByRole('status', { name: 'Loading' }))
+        // can never match. Add a YAML entry with name: null to opt out.
+        if (inferred.strategy === 'role' && inferred.name && inferred.role && this.contentNamedRoles.includes(inferred.role)) {
+          const warnKey = `${inferred.role}:${displayLabel}`;
+          if (!this.warnedContentNamed.has(warnKey)) {
+            this.warnedContentNamed.add(warnKey);
+            this.diagnostics?.add(
+              'SG-W003',
+              `role "${inferred.role}" derives its accessible name from content, but "[${displayLabel}]" auto-inferred { name: '${inferred.name}' } which will likely never match. Add a selectors.yaml entry with an explicit name: or name: null`,
+              { feature: this.featureName }
+            );
+          }
+        }
         return inferred;
       }
     }
@@ -566,6 +598,21 @@ export class SelectorResolver {
         });
 
       case 'role':
+        // SG-W003 — the entry has no `name:` so the compiler defaulted it to the Gherkin
+        // reference text. For name-from-content roles (status/alert/…) that filter can
+        // never match the live element (its accessible name is computed from its content,
+        // e.g. a toast's message text) — issue #467. Opt out with `name: null`.
+        if (entry.name === undefined && name && this.contentNamedRoles.includes(value)) {
+          const warnKey = `${value}:${originalLabel}`;
+          if (!this.warnedContentNamed.has(warnKey)) {
+            this.warnedContentNamed.add(warnKey);
+            this.diagnostics?.add(
+              'SG-W003',
+              `role "${value}" derives its accessible name from content, but the entry for "${originalLabel}" has no name: — the defaulted { name: '${name}' } will likely never match. Set an explicit name: or opt out with name: null`,
+              { feature: this.featureName }
+            );
+          }
+        }
         return withExtras({
           strategy: 'role',
           role: value,

package/src/harness/capability.ts

@@ -24,6 +24,7 @@ export interface DriverMeta {
   package: string;
   runtime?: string;
   adapter?: string;        // registry adapter name (defaults to id)
+  bundled?: boolean;       // shipped as a core dependency — present without `capability add`
   capabilities: string[];
   unblocks?: string[];
 }

package/src/harness/catalog/drivers.yaml

@@ -51,7 +51,8 @@ drivers:
   data-factory:
     kind: capability
     package: "@sungen/driver-data-factory"
-    status: planned
+    status: shipped
+    bundled: true          # runtime-free knowledge+codegen — shipped by default (no `capability add` needed)
     capabilities: ["@dataFactory"]
     unblocks: [M1]
   mock:

package/src/index.ts

@@ -14,6 +14,9 @@ export type { DiscoveredContext } from './orchestrator/context-discovery';
 
 // --- Step-pattern authoring (a driver contributes step patterns via its descriptor) ---
 export type { PatternContext, StepPattern, StepTemplateData } from './generators/test-generator/patterns/types';
+export { expandRecipe } from './generators/test-generator/recipe-expander';
+export type { RecipeExpandContext, RecipeNode } from './generators/test-generator/recipe-expander';
+export type { ResolvedAppProfile } from './generators/test-generator/app-profile';
 export type { MappedStep } from './generators/test-generator/step-mapper';
 export type { ParsedStep } from './generators/gherkin-parser';
 export { getPathCode, inferPath, resolvePathVariables } from './generators/test-generator/utils/path-inference';
@@ -22,8 +25,8 @@ export { getPathCode, inferPath, resolvePathVariables } from './generators/test-
 export { parseQueryOverrides } from './harness/annotation-overrides';
 
 // --- Named-query catalog (shared: the DB driver's codegen + core's data-driven advisory lint) ---
-export { resolveQuery, compileQuery, lintCatalog } from './harness/query-catalog';
-export type { QueryEntry } from './harness/query-catalog';
+export { resolveQuery, compileQuery, compileShape, isShapeEntry, lintCatalog } from './harness/query-catalog';
+export type { QueryEntry, MongoFind, MongoPipeline } from './harness/query-catalog';
 
 // --- Shared harness: viewpoint catalog + coverage gate / assertion depth ---
 // (the UI capability's gateProvider composes these; they also back core's ingest + audit fallback)

package/src/orchestrator/templates/ai-src/commands/create-data-test.md

@@ -0,0 +1,99 @@
+---
+name: create-data-test
+description: "Generate standardized test-data for a screen/flow from the Data Factory catalog — valid/boundary/invalid values with CHK-* traceability (no free-form guessing)"
+argument-hint: [screen-or-flow-name]
+order: 25
+claude-tools: "Read, Grep, Bash, Glob, Write, Edit, AskUserQuestion, Skill"
+copilot-tools: "[vscode, execute, read, agent, edit, search, todo]"
+codex-trigger: "Run when the user asks to CREATE, generate, or standardize TEST DATA / test values for a screen or flow (valid/boundary/invalid, boundary values, negative data). Uses the Data Factory driver. Not for generating the .feature scenarios themselves (that is create-test)."
+---
+
+**Input**: A screen or flow name (e.g., `/sungen:create-data-test login`), OR **no name** to do every unit (with a confirmation — see ALL mode). Load the `sungen-data-factory` skill for the full method.
+
+> **When to use.** `/sungen:create-test` already standardizes field test-data via Data Factory **inline** (its step 5.3), so you normally do **not** need this command as a follow-up. Use it **on demand** to *re-standardize*: after you edit a field-map or the `.overwrite`, for a unit authored before Data Factory existed, to refresh error-code mappings, or to (re)generate across many units at once (ALL mode). It MERGES into existing test-data (never clobbers).
+
+## Role
+
+You are a **Senior QA Engineer** producing **test data to a standard**, not by guessing. You do NOT invent values field-by-field. You follow the 4-source method (spec rules → field-type catalog → design technique → DB mapping), driven by the **Data Factory** capability driver. Values come from the catalog (`common/` + the project's `.overwrite`), each tagged with a `CHK-*` id that traces back to the spec. Where the catalog cannot cover a project-specific field, you **ask the QA** — you never fabricate domain data.
+
+## Preconditions
+
+1. **Availability** — Data Factory is **bundled with core** (no `capability add` needed); its CLI (`sungen data …`) is available out of the box. Just continue.
+2. Determine mode from `$ARGUMENTS`:
+   - A **name** given → single-unit mode (that screen/flow only).
+   - **No name** → **ALL mode** (see below — always confirm first).
+
+## ALL mode (no name) — confirm before doing everything
+
+If no name was given, the user wants **all** screens/flows — but this is wide, and a missing name is often a typo (they meant `create-data-test home`). So:
+
+1. List every unit under `qa/screens/*` and `qa/flows/*`, and classify each as **new** (no `test-data/<name>.yaml` yet) vs **would-overwrite**.
+2. Show the list and use `AskUserQuestion` to confirm: *"Generate test-data for ALL N units? (X new · Y would overwrite)"* — default to **No**.
+3. Only proceed when the user confirms. Then run the per-unit flow below for each (the CLI `sungen data gen --all` also enforces this confirm; `--yes` after the user agrees).
+
+## Per-unit flow (single unit, or each unit in ALL mode)
+
+Auto-detect: `qa/flows/<name>/` → flow; else `qa/screens/<name>/` → screen. (API units carry their contract in `apis.yaml` — data there is `@cases` in create-test, not this command.)
+
+### 1. Read the sources (Nguồn 1 + 4)
+
+Read `qa/<screens|flows>/<name>/requirements/spec.md` and `test-viewpoint.md`. For **each input field / parameter**, extract:
+- data **type** (map to a catalog field-type: email · password · phone · string · number-integer · number-float · currency · postcode · katakana …),
+- `required`, format, **min/max** length or value,
+- the real **error/message code** the spec shows when a rule is violated,
+- any **DB mapping** (unique, cross-entity dependency) noted in the spec.
+
+Viewpoint tells you which fields are high-priority → give them the fullest data.
+
+**No input fields → nothing to generate.** If the unit is a pure navigation / listing / capture-compare flow (e.g. a home-shopping browse flow) with **no user-input fields or parameters**, Data Factory has nothing to standardize. Report *"`<name>`: no input fields → nothing to generate"* and stop for this unit — do **not** write an empty `qa/data-factory/<name>.fields.yaml`. (Its scenarios are covered by create-test's data, not by field-level test data.)
+
+### 2. Write the field-map — `qa/data-factory/<name>.fields.yaml`
+
+This is the input the deterministic generator expands. One entry per field:
+
+```yaml
+screen: <name>            # or: flow: <name>
+fields:
+  - name: email
+    type: email
+    required: true
+    unique: true                                   # fresh-per-run (register email won't collide)
+    constraints: { maxLocal: 64, maxTotal: 254 }   # project's real limits
+    errorMap: { M13: E1042, M02: E1001 }            # catalog placeholder → project's real code
+  - name: password
+    type: password
+    constraints: { minLength: 8, maxLength: 32 }
+```
+
+**`unique: true`** — set it for a field that must be **different every run** (register email/username that can't clash with a record a previous run created). The valid value then gets a runtime `{{$timestamp}}` (email → `user+{{$timestamp}}@…`), so each run is fresh — no cross-run cache, no order-dependent flakiness. Boundary/invalid values stay literal (they test rules, not record creation).
+
+Map every placeholder error code you can (`errorMap`) to the spec's real code. Leave a code unmapped only if the spec truly has none — the lint will flag it as an open point to confirm with BA/Dev.
+
+**Complex forms — nested & dependent fields.** For a grouped/object field, give it **`fields:`** (sub-fields, expanded recursively; no `type` on the group). For a field whose rule depends on another, add **`dependsOn: { field: <other>, value: <v> }`** — it's recorded as a note so the scenario/`@cases` honor it (the generator doesn't resolve the runtime condition):
+```yaml
+fields:
+  - name: address                       # group → nested object
+    fields:
+      - { name: city, type: string, constraints: { maxLength: 50 } }
+      - { name: postcode, type: postcode, dependsOn: { field: country, value: JP } }
+```
+
+### 3. Blind spots — ask, do not invent
+
+If a field's type is **not** in the catalog (a business enum, a cross-entity constraint, a project data model), **stop and ask the QA** with `AskUserQuestion` for: (1) the valid set, (2) invalid / non-existent values, (3) the error code when wrong, (4) dependencies on other fields. Record the answer in `qa/data-factory/project/<entity>.yaml` for reuse. Never fabricate domain values.
+
+### 4. Lint the coverage
+
+Run (local-first): `[ -x ./bin/sungen.js ] && ./bin/sungen.js data lint --screen <name> || npx sungen data lint --screen <name>`. Fix what it reports: add missing boundary values, resolve `UNRESOLVED` items (supply the constraint), map `OPEN_ERRORREF` codes. The bar is the phuong-phap §6 checklist — every required field has valid + boundary + invalid, one invalid per rule.
+
+### 5. Generate the test-data
+
+Run (local-first): `[ -x ./bin/sungen.js ] && ./bin/sungen.js data gen --screen <name> || npx sungen data gen --screen <name>`. If `test-data/<name>.yaml` already exists it **merges** the standardized field data in — it **replaces only the field keys it owns and preserves every other key** (create-test's data, flow-namespaced keys, `@cases` datasets, overrides). It asks before merging (in ALL mode after they confirmed, add `--yes`; `--force` skips the prompt). The output is standardized `valid/boundary/invalid` values with `CHK-*` traceability.
+
+### 6. Weave into scenarios (if create-test already ran)
+
+If the `.feature` exists, turn the generated invalid/boundary sets into data-driven `Scenario Outline` + `Examples` (`@cases`) referencing the values — following `sungen-gherkin-syntax`. Otherwise leave the standardized `test-data/<name>.yaml` for `/sungen:run-test` to consume.
+
+## After running
+
+Use `AskUserQuestion` to offer the next step: review the generated data, run `/sungen:create-test <name>` (if scenarios don't exist yet), or `/sungen:run-test <name>`.

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -167,6 +167,8 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 
    **5d. Sequential fallback.** Use the single-context incremental path (Step 2: tier-by-tier `Write`/`Edit` batches) when: only **one** shard applies, **Copilot / no sub-agents**, or a constrained setup. Same output, just no speedup. **For flows**: `[Screen:Element]` namespace refs, test-data namespaced by phase, `@flow` tag.
 
+5.3. **Standardize field test-data — Data Factory (when the unit has input fields).** Don't hand-invent per-field values — make them **standard**. For each input field, author the field-map `qa/data-factory/<name>.fields.yaml` (field → catalog `type` + the spec's real `constraints` + `errorMap` placeholder→real code), then run (Bash, local-first) `[ -x ./bin/sungen.js ] && ./bin/sungen.js data lint --screen <name> || npx sungen data lint --screen <name>` and `… data gen --screen <name>`, per the **`sungen-data-factory`** skill. `data gen` **MERGES** into `test-data.yaml` (replaces only its field keys, preserves your scenario/namespaced data), so it is safe to run here. Weave the standardized **boundary/invalid** sets into `@cases` (`Scenario Outline` + `Examples`) with `CHK-*` trace; keep the map's `errorMap`/`constraints` aligned to the spec. **This is the same standard as `/sungen:create-data-test`, applied inline — so you do NOT run that command separately afterwards.** A unit with **no input fields** (navigation / list / capture-compare) → **skip this step** (nothing to standardize).
+
 5.4. **Depth self-check (deterministic — run BEFORE the audit).** Run `sungen depth-lint --screen <name>` (Bash). It reuses the audit's businessDepth classifier and splits every shallow business-critical scenario into two actionable buckets — act on them now so the audit/repair loop doesn't burn rounds on depth:
    - **DEEPEN IN PLACE** — add a real value assertion to each (`User see all [X] contain {{v}}`, `User remember [X] as {{v}}` + `… with {{v}}`). The printed `template` is a **hint** keyed off the theme — apply judgment to the scenario's actual claim; do NOT paste a value assertion that doesn't fit (e.g. a carousel-visibility scenario should assert the product SET, not a price). If a flagged scenario is genuinely visibility/behavior (not data-correctness), that's an over-count — leave it and note it, never fake an assertion.
    - **CROSS-SCREEN** — route to a flow (`/sungen:add-flow`) or tag `@manual:Mx` + reason; do NOT fake an on-screen data assertion. This removes it from the screen's depth denominator honestly.
@@ -194,6 +196,7 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 4. Follow the `sungen-tc-generation` skill for section identification, viewpoint generation, and output format. **For flows**, use the "Flow Test Generation" section in the skill. When requirements exist, use the "Requirements-Driven Generation" strategy. **For Tier 1**, apply the **Lightweight Guard** — verify required fields, validation rules, business rules, security checks, and key state transitions all have TCs after generation. **For Tier 2+**, **MUST** apply the full **Mapping Contract** — walk every `spec.md` section top-to-bottom and produce the indicated TCs per Table 1; handle `test-viewpoint.md` per Table 2. Do not silently skip sections. Present sections as a numbered list and let user pick.
 5. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills. Generate **group-by-group** (one viewpoint group at a time, tier-by-tier `Write`/`Edit` batches) to stay under the output-token cap. **For flows**: use `[Screen:Element]` namespace format, namespace test-data by phase, add `@flow` tag. **If a scenario needs `@query` DB verification**, check the datasource `engine` first — unsupported engine → follow `sungen-gherkin-syntax` § "Unsupported DB engine — fallback" instead of authoring `@query` steps.
    > **No parallel fan-out here.** Copilot has no sub-agents, so generation is sequential (the Claude Code variant fans out one `sungen-generator` per viewpoint group and merges). Same output, no speedup.
+5.3. **Standardize field test-data — Data Factory (when the unit has input fields).** For each input field, author the field-map `qa/data-factory/<name>.fields.yaml` (field → catalog `type` + real `constraints` + `errorMap`), then run `sungen data lint --screen ${input:name}` and `sungen data gen --screen ${input:name}` per the **`sungen-data-factory`** skill. `data gen` **MERGES** into `test-data.yaml` (replaces only its field keys, preserves the rest), so it is safe here. Weave the standardized boundary/invalid sets into `@cases` with `CHK-*` trace. **Same standard as `/sungen:create-data-test`, applied inline — do NOT run that command separately afterwards.** No input fields (navigation/list) → skip.
 5.4. **Depth self-check (deterministic — BEFORE the audit).** Run `sungen depth-lint --screen ${input:name}`. It splits every shallow business-critical scenario into **DEEPEN IN PLACE** (add a real value assertion — the printed `template` is a theme-keyed hint, apply judgment to the actual claim; never fake one onto a visibility/behavior scenario) and **CROSS-SCREEN** (route to a flow / tag `@manual:Mx` + reason — removes it from the depth denominator honestly). Act on both, re-run until `deepen` is empty (or only honest over-counts remain), THEN gate. Lifts first-pass `businessDepth` mechanically instead of via 2–3 repair rounds.
 5.5. **Quality gate & repair (harness — always run).** Per `sungen-harness-audit`: run `sungen audit --screen ${input:name}` (structural), THEN do an **independent semantic review inline** using the `sungen-reviewer` criteria (does each scenario's steps PROVE its title/viewpoint? observable Thens? business-critical assertion depth?). Merge both sets of issues; if gate FAILs / findings exist, repair (budget 3) and re-audit — GATE missing theme → generate it (cross-screen → **automate it in the flow** via `/sungen:add-flow`, NOT a full `@manual` screen duplicate — `sungen audit` flags an automatable `@manual` as `MANUAL-AUTOMATABLE`; reserve `@manual:Mx` for true judgment/missing-capability); DEPTH → add data assertions; BALANCE → add business-core first; TRACE → align VP ids. Never fake a pass.
 5.6. **Record.** `sungen manifest --screen ${input:name}`. Ledger **each phase** (not just repair) — pick one `runId` at the start and pass it so `trace`/`ledger report` show THIS run, not a mix: `sungen ledger record --screen ${input:name} --run <runId> --step <discovery|viewpoint|gherkin|audit|repair:N> --ms <elapsed>`. On re-run, start with `sungen manifest --screen ${input:name} --diff` and only regenerate changed sections.

package/src/orchestrator/templates/ai-src/commands/run-test.md

@@ -127,6 +127,7 @@ If the unit is **api-first**, skip every selector/capture phase (an API test has
 ## Pre-run (phased — per `sungen-selector-fix` skill)
 
 1. Verify `<base>/<name>/` has `.feature` + `test-data.yaml`. **If the feature has `@query` steps**, check the resolved datasource `engine` in `qa/datasources.yaml` — unsupported engine → follow the `sungen-gherkin-syntax` skill § "Unsupported DB engine — fallback" before compiling (do not attempt a direct connect).
+1.5. **Data Factory pre-check (before running)** — Data Factory is bundled with core, so whenever a field-map exists (`qa/data-factory/<name>.fields.yaml`), confirm the test-data is standardized and covers each field before you run: `[ -x ./bin/sungen.js ] && ./bin/sungen.js data lint --screen <name> || npx sungen data lint --screen <name>`. If it reports coverage gaps (missing boundary/invalid, unresolved values, unmapped error codes) or the field-map is newer than `test-data/<name>.yaml`, refresh via `/sungen:create-data-test <name>` (or `sungen data gen --screen <name>`) — then compile. Blind spots (a `type` not in the catalog) are for the QA to answer, not to invent. No field-map / driver disabled → skip this step.
 2. **Phase 0 — Selector Pre-gen**: if `selectors.yaml` is missing/empty or doesn't cover the feature file's `[Reference]`s, apply the following decision tree before running Phase 0 from `sungen-selector-fix`:
 
    ```

package/src/orchestrator/templates/ai-src/config/claude.md

@@ -18,14 +18,16 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-delivery` | Export Gherkin + Playwright results → CSV test case deliverable |
 | `sungen-capture` | Acquire visual/design context — one skill, 4 modes: figma-mcp (Dev Mode MCP), figma-pat (URL → spec_figma.md), live (Playwright MCP scan), local (images in `requirements/ui/`) |
 | `sungen-locale` | Bootstrap i18n — audit selectors, detect locale switch mechanism, generate test-data overlay |
+| `sungen-data-factory` | Standardized test-data — field-type/security catalog, 4-source method, `.overwrite`, blind-spot prompts |
 
-## Workflow (7 AI commands)
+## Workflow (8 AI commands)
 
 | Command | What it does |
 |---|---|
 | `/sungen:add-screen <name> <path>` | Scaffold `qa/screens/<name>/` directories |
 | `/sungen:add-flow <name> [--path <url>]` | Scaffold `qa/flows/<name>/` directories for E2E cross-screen testing |
 | `/sungen:create-test <name>` | Generate `.feature` + `test-data.yaml` (auto-detects screen or flow) |
+| `/sungen:create-data-test <name>` | Generate standardized test-data (valid/boundary/invalid + CHK trace) from the Data Factory catalog; no name = all units (asks to confirm) |
 | `/sungen:review <name>` | Score syntax, coverage, viewpoint quality (auto-detects screen or flow) |
 | `/sungen:run-test <name>` | Generate `selectors.yaml`, compile, run, auto-fix (auto-detects screen or flow) |
 | `/sungen:delivery [name...]` | Export test cases → CSV for QA delivery (all screens if no arg) |

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

@@ -18,14 +18,16 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-delivery` | Export Gherkin + Playwright results → CSV test case deliverable |
 | `sungen-capture` | Acquire visual/design context — one skill, 4 modes: figma-mcp (Dev Mode MCP), figma-pat (URL → spec_figma.md), live (Playwright MCP scan), local (images in `requirements/ui/`) |
 | `sungen-locale` | Bootstrap i18n — audit selectors, detect locale switch mechanism, generate test-data overlay |
+| `sungen-data-factory` | Standardized test-data — field-type/security catalog, 4-source method, `.overwrite`, blind-spot prompts |
 
-## Workflow (7 AI commands)
+## Workflow (8 AI commands)
 
 | Command | What it does |
 |---|---|
 | `/sungen-add-screen <name> <path>` | Scaffold `qa/screens/<name>/` directories |
 | `/sungen-add-flow <name> [--path <url>]` | Scaffold `qa/flows/<name>/` directories for E2E cross-screen testing |
 | `/sungen-create-test <name>` | Generate `.feature` + `test-data.yaml` (auto-detects screen or flow) |
+| `/sungen-create-data-test <name>` | Generate standardized test-data (valid/boundary/invalid + CHK trace) from the Data Factory catalog; no name = all units (asks to confirm) |
 | `/sungen-review <name>` | Score syntax, coverage, viewpoint quality (auto-detects screen or flow) |
 | `/sungen-run-test <name>` | Generate `selectors.yaml`, compile, run, auto-fix (auto-detects screen or flow) |
 | `/sungen-delivery [name...]` | Export test cases → CSV for QA delivery (all screens if no arg) |

package/src/orchestrator/templates/ai-src/skills/sungen-data-factory/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: sungen-data-factory
+description: 'Use when create-data-test (or create-test) needs standardized TEST DATA — valid/boundary/invalid values for input fields with CHK-* traceability. Drives the Data Factory catalog + the 4-source method. Invoke after reading spec.md, when authoring the field-map or filling test-data.'
+user-invocable: false
+---
+
+## What this skill does
+
+Turn a screen/flow's fields into **standardized test data** — not guessed values. You author a
+**field-map**; the deterministic `sungen data gen` expands it from the Data Factory **catalog**
+(field-type + security + technique library) into valid / boundary / invalid values, each carrying a
+`CHK-*` id that traces to the spec. Your judgment goes into *reading the spec correctly* and
+*answering blind spots* — never into inventing values the catalog or the QA should own.
+
+Data Factory is **bundled with core** (runtime-free) — no `capability add` needed; the `sungen data …`
+CLI is available out of the box.
+
+## The 4-source method (phuong-phap-tao-test-data.md)
+
+Never invent values from memory. Cross-reference four sources — each covers the previous one's gap:
+
+1. **Spec validate rules** — required, format, min/max, business rules, and the **error/message code**
+   per rule. Defines the legal/illegal boundary. (Says the *law*, not every way to *break* it.)
+2. **Field-type catalog** — the accumulated "how this type breaks" knowledge (email/password/phone/
+   number/…). This is the Data Factory `common/` — it fills the "spec doesn't list every break" gap.
+3. **Design technique** — Boundary Value Analysis / Equivalence Partitioning / Decision Table / State
+   Transition — reduces the rule + candidates to a *minimal-but-sufficient* representative set.
+4. **DB mapping** — unique constraints, cross-entity dependency, real backend limits → precondition
+   data, not just a single input value.
+
+Then classify every value into **Valid / Boundary / Invalid** (each invalid tagged with its error
+code) and give it a `CHK-*` id for traceability.
+
+## The field-map — `qa/data-factory/<name>.fields.yaml`
+
+Your main artifact. One entry per input field; the generator expands it:
+
+```yaml
+screen: login                 # or  flow: <name>
+fields:
+  - name: email
+    type: email               # a catalog field-type (see list below)
+    required: true
+    constraints: { maxLocal: 64, maxTotal: 254 }   # the project's REAL limits from spec
+    errorMap: { M13: E1042, M02: E1001 }            # catalog placeholder code → project's real code
+  - name: password
+    type: password
+    constraints: { minLength: 8, maxLength: 32 }
+```
+
+**Catalog field-types** (P1): `email` · `password` · `phone` · `string` · `number-integer` ·
+`number-float` · `currency` · `postcode` · `katakana` (JP). Security payload banks auto-append to a
+field's invalid group via the type's `uses_security` (`sqli`, `xss`, `idor`, `broken-auth`, `upload`,
+`input-validation`).
+
+Rules:
+- Pick the closest `type`; put the project's real numbers in `constraints` (they override the
+  catalog defaults).
+- Map every `errorRef` placeholder (`M13`, `M39`, …) to the spec's real code via `errorMap`. Leave
+  one unmapped **only** if the spec has none — the lint flags it as an open point to confirm.
+- **Complex forms:** a **group** field takes nested **`fields:`** (recursive; no `type` on the group → renders a nested object like `address.city`). A field whose rule depends on another takes **`dependsOn: { field, value }`** — recorded as a `_depends_on` note (the generator doesn't resolve the runtime condition; weave it into the scenario/`@cases`).
+- Set **`unique: true`** on a field that must be fresh every run (register email/username, anything
+  that would clash with a record a previous run left behind). Its valid value then carries a runtime
+  `{{$timestamp}}` (email → `user+{{$timestamp}}@…`) so each run is unique — no cross-run cache
+  (which would make tests order-dependent/flaky). Prefer this over caching prior-run values. For
+  reusing a value produced earlier **within the same run** (register → then log in with it), bind it
+  via the scenario (`@dataFactory` recipe / `testData.bind`), not a cross-run cache.
+
+## No input fields → nothing to generate
+
+Data Factory standardizes **field-level input data**. If a unit has no user-input fields or
+parameters — a pure navigation, listing, or capture-compare flow — there is nothing to generate.
+Report *"no input fields → nothing to generate"* and skip it; do **not** write an empty field-map.
+Those scenarios are covered by the data create-test already produced, not by field-level test data.
+(This is a correct outcome, not a gap — don't force a field-map to make the unit "processed".)
+
+## Blind spots — ask, never fabricate
+
+If a field's type is **not** in the catalog — a business enum, a cross-entity constraint, a
+project-specific data model — do **not** guess. Ask the QA (via `AskUserQuestion`) for: (1) the valid
+set, (2) invalid / non-existent values, (3) the error code when wrong, (4) dependencies on other
+fields. Record it in `qa/data-factory/project/<entity>.yaml` so it becomes reusable project catalog.
+This is the core discipline: *common is never enough; when blind, think and ask — don't invent.*
+
+## Customizing the catalog — `.overwrite` (survives `sungen update`)
+
+The shipped `common/` is a floor. Project rules go in `qa/data-factory/common.overwrite.yaml`,
+deep-merged over the common (**later-wins**, keyed by `type` + data-point `id`): same `id` replaces,
+new `id` appends, `constraints` merge key-by-key. `sungen update` refreshes `common/` but never
+touches your overlay. If an update makes an overlay entry stale (references a bank/constraint that no
+longer exists), the loader **warns you to prune it** — it never edits your file. Prefer a targeted
+`errorMap`/`constraints` in the field-map for per-screen tweaks; use `.overwrite` only for rules that
+apply project-wide.
+
+## Bulk-import fixtures (CSV)
+
+For CSV/Excel import or bulk-upload testing, `sungen data fixture --screen <name> [--rows N] [--invalid]`
+turns the field-map into a fixture FILE under `qa/fixtures/`: `<name>.csv` (N valid rows; nested groups
+→ dotted headers; `unique` fields row-indexed) that should import cleanly, and — with `--invalid` —
+`<name>.invalid.csv` (one seeded-bad row per field + a `_violation` column) for row-level rejection
+tests. Reference it from an `@api` upload (`files:`) or a UI file input.
+
+## Verify before done — the phuong-phap §6 checklist
+
+Run `sungen data lint` and clear it: every required field has **≥1 valid**, **boundary present**
+(exact min/max, not only over-boundary) for bounded types, **≥1 invalid per rule** (not one generic
+"wrong" value for many rules), no `UNRESOLVED` values, error codes mapped or explicitly left open.
+Then `sungen data gen` writes the standardized `test-data/<name>.yaml`. Do not hand-edit the
+generated values — change the field-map or `.overwrite` and re-run (determinism: same input → same
+data).
+
+## Weaving into scenarios
+
+When a `.feature` exists, express invalid/boundary sets as data-driven `Scenario Outline` + `Examples`
+(`@cases`) referencing the values — see `sungen-gherkin-syntax`. This keeps one logic + many values
+instead of copy-pasted scenarios, and each row carries its `CHK-*` id for traceability.

package/src/orchestrator/templates/ai-src/skills/sungen-error-mapping/SKILL.md

@@ -78,9 +78,20 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | strict mode violation | Multiple elements match | Add `nth: 0`, `exact: true`, or more specific `name` |
 | Timeout / not found | Element doesn't exist or name wrong | Re-snapshot → copy exact accessible name. Check iframe/dialog scope |
 | Element is not an input | Wrong element type targeted | Change `type` or `value` to match actual element |
-| not a select | Custom dropdown, not native `<select>` | Set `variant: 'custom'` |
+| not a select | Custom dropdown, not native `<select>` | Set the widget variant: `variant: radix-select`/`antd-select` (built-in recipes), a custom recipe name from `qa/app.yaml`, or project-wide `widgets.select` in `qa/app.yaml` |
 | Frame not found | iframe selector wrong or doesn't exist | Fix `frame` value, verify iframe in snapshot |
 
+### Compile diagnostics (`sungen generate` output) → fix BEFORE running
+
+| Code | Meaning | Fix |
+|---|---|---|
+| `SG-W001` | Step matched no pattern — compiled to a no-op `// TODO` (the test runs weaker than it reads) | Rephrase to a documented pattern (`sungen-gherkin-syntax`) or tag `@manual` with a reason |
+| `SG-W002` | A step's `{{value}}` was parsed but never used in the generated code | The step form isn't the one you think — check the pattern's exact syntax |
+| `SG-W003` | `{ name }` filter defaulted from the Gherkin reference on a name-from-content role (toast/alert/status) | Add explicit `name:` or opt out with `name: null` |
+| `SG-W005` | `qa/app.yaml` unknown key / unknown preset / unparseable | Fix the key, or `extends: native\|radix\|antd` |
+| `SG-W006` | `qa/app.<env>.yaml` found — unsupported by design | Describe the app once in `qa/app.yaml`; env differences belong in test-data overlays |
+| `SG-W007` | Browser-alert handler step written AFTER an action — listener registers too late, the dialog auto-dismisses silently | Use the compound form `click [X] button and accept [OK] alert` (preferred), or move the alert step before the trigger |
+
 ### Assertion errors → apply the Source-of-truth gate above FIRST
 
 > The "Fix" column below applies **only when the expected value was wrong relative to `spec.md`** (a test defect). If the app's value contradicts the spec, the row is a **candidate bug → report it, do not edit the expected to match live**. Never weaken `toHaveText`→`toContainText` just to pass.

package/src/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -50,16 +50,41 @@ User expand | collapse [T] row
 ### Alert / Keyboard / Wait / Scroll
 
 ```
-User click [OK | Cancel] alert
+User click [T] button and accept [OK] alert       # PREFERRED (v3.3): natural order,
+User click [T] button and dismiss [Cancel] alert  # compiler registers the listener first
+User click [OK | Cancel] alert                    # two-step form: must come BEFORE the trigger
 User fill [T] alert with {{v}}
 User see [message text] alert
 User press Escape key | Enter on [T] field
-User wait for N seconds | [T] dialog | [T] dialog is STATE | [T] page
+User wait for N seconds | [T] page
+User wait for [T] TYPE is visible | hidden | enabled | disabled     # ANY reference (v3.3)
+User wait for [T] TYPE with {{v}}                                    # until it shows the value
+User wait for [T] table to refresh                                   # filter/search/pagination round-trip (v3.3)
 User scroll to [T] section
 User switch to [T] frame | [main] frame
 ```
 
-> Alert steps must appear BEFORE the action that triggers the dialog.
+> **Browser alerts (native `window.confirm/alert/prompt` only):** prefer the compound form —
+> it reads in the user's real order and declares the trigger↔dialog causality in one step.
+> The two-step form stays valid but the alert step must appear BEFORE the triggering action
+> (a late `page.once('dialog')` lets the dialog auto-dismiss silently — compile warning
+> `SG-W007`). Custom confirm MODALS (ARIA dialogs — most modern apps) are ordinary buttons:
+> write normal click steps, no alert step at all.
+> State-based waits (`is hidden`, `with {{v}}`, `table to refresh`) are legitimate; time-based
+> `wait for N seconds` stays a last resort. `table to refresh` watches the app's loading
+> indicator (`qa/app.yaml` `feedback.loading.indicator`, default `[aria-busy="true"]`).
+
+### Positional table rows (v3.3)
+
+```
+User remember [Col] column in [T] table row {{n}} as {{var}}   # read a cell by POSITION
+User click [Act] button in [T] table row {{n}}                 # act on the SAME row
+User click [Act] button in [T] table row 2                     # literal row number
+```
+
+Row numbers are 1-based data rows (header not counted; override via `qa/app.yaml`
+`conventions.table`). Use positional rows when you must READ then ACT on the same row —
+two content-filtered queries can hit different rows if the table re-renders in between.
 
 ### Assertions (8 patterns → determines Playwright assertion)
 
@@ -118,14 +143,24 @@ Scenario: ...
 
 Path access on a bound result: `{{q.count}}`/`{{q.length}}`, `{{q.first.col}}`, `{{q.last.col}}`, `{{q[2].col}}`, `{{q.col}}` (= first row's col). `expect A is B` also supports `is at least` / `is at most` / `is not`. Tier-2 declarative (trivial inline, no catalog): `User see [<table>] row where [<col>] is {{v}} [has [<col2>] = "x"]`, `… no row where …`, `… count is {{n}}`. Full grammar + catalog/datasource/secret rules → **Advanced → Database** doc. Only emit DB steps when the project has a `database/` catalog / `datasources.yaml`.
 
+### NoSQL engines (Cosmos, MongoDB, DynamoDB) — natively supported
+
+Beyond the three SQL engines, the Data Driver has native NoSQL engines. Declarative steps (`User see [table] row where …`, `… no row …`, `… count is …`) work across ALL of them; only the raw `@query` catalog shape differs per engine:
+
+- **`engine: cosmos`** (Azure Cosmos DB, NoSQL API) — SQL dialect. Author `sql:` catalog entries against the mandatory `c` alias (`SELECT * FROM c WHERE c.<field> = :p`); named params bind automatically. Config: `endpoint`+`key` (or a connection-string `url`), `database`, `container` (default when no `[table]`). Read-only by construction (the query API can't mutate).
+- **`engine: mongodb`** — no SQL. Author a `find:` (`{collection, filter, projection?, sort?, limit?}`) or `pipeline:` (`{collection, stages: […]}`) catalog entry; `:param` placeholders bind at runtime. `$out`/`$merge`/`$where`/`$function`/`$accumulator`/`mapReduce` are refused. Config: a `mongodb://` `url`. Read-only = a server-side read role.
+- **`engine: dynamodb`** — raw `@query` is PartiQL SELECT (`sql: SELECT … FROM "table" WHERE pk = :p`). Declarative steps route GetItem/Query only for partition-/sort-key filters via a `keySchema:` registry; a **non-key filter is refused** (use a raw PartiQL SELECT — never a full-table Scan). Config: `region` + `keySchema` (credentials from the AWS env chain). Read-only = IAM `PartiQLSelect`-only.
+
+Full config + catalog examples → **Advanced → Database** doc.
+
 ### Unsupported DB engine — fallback (ask, don't improvise)
 
-Direct SQL verification (`@query`, the Data Driver) only supports these engines: **`{postgres, sqlite, mysql}`**. When a datasource's `engine` (or the DB the user describes) is **outside this set** — e.g. Cosmos NoSQL, MongoDB, Cassandra, DynamoDB:
+Direct SQL verification (`@query`, the Data Driver) covers these SQL engines: **`{postgres, sqlite, mysql}`** — plus the three native NoSQL engines above (Cosmos, MongoDB, DynamoDB). When a datasource's `engine` (or the DB the user describes) is **outside all of those** — e.g. Cassandra, Oracle, Neo4j, a proprietary store:
 
 1. **Do not** attempt a direct connect. **Do not** improvise a verification method.
 2. Present a fixed `AskUserQuestion` with exactly these 3 branches (always these, no others invented):
    - **@api** — verify state via the project's internal API (route to the API driver).
-   - **@manual** — emit a `@manual` step + manual-check guidance (e.g. Cosmos Data Explorer, `az cosmosdb`, the vendor CLI).
+   - **@manual** — emit a `@manual` step + manual-check guidance (e.g. the vendor console / CLI — `cqlsh` for Cassandra, `cypher-shell` for Neo4j).
    - **Proxy / read-replica SQL** — if the user can supply a SQL-compatible endpoint (including Azure Cosmos DB **for PostgreSQL** / Citus), treat it as `engine: postgres` (or `mysql`) and use the normal Data Driver path above.
 3. **Recommend, don't decide.** Check the project for signals and put the best-fit branch **first**, tagged **"(Recommended)"** with a one-line reason:
    - a project API driver / `qa/api/` catalog / `PEERCONNE_URL`-style internal API exists → **@api** first;
@@ -138,11 +173,11 @@ Direct SQL verification (`@query`, the Data Driver) only supports these engines:
 Example:
 ```
 AskUserQuestion:
-  question: "This datasource's engine (cosmos-nosql) isn't in {postgres, sqlite, mysql} — direct SQL connect isn't supported. How should DB state be verified?"
+  question: "This datasource's engine (cassandra) isn't a supported Data Driver engine ({postgres, sqlite, mysql} + Cosmos/MongoDB/DynamoDB) — direct connect isn't supported. How should DB state be verified?"
   options:
     - "@api — verify via the project's internal API (Recommended: qa/api/ catalog found)"
-    - "@manual — emit a @manual step + Cosmos Data Explorer / az cosmosdb check"
-    - "Proxy / read-replica SQL — supply a SQL-compatible endpoint (e.g. Cosmos DB for PostgreSQL) → engine: postgres"
+    - "@manual — emit a @manual step + cqlsh check"
+    - "Proxy / read-replica SQL — supply a SQL-compatible endpoint → engine: postgres"
     - "Other — describe your own verification approach"
 ```
 

package/src/orchestrator/templates/ai-src/skills/sungen-selector-fix/SKILL.md

@@ -83,6 +83,13 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
    - 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.
+7b. **Widget & profile fingerprinting** (App Profile, v3.3): while the snapshot is open, identify the UI library and non-standard widget behavior, and record it so the compiler stops guessing:
+   - **Fingerprints** (check DOM classes/attributes): `.ant-select`/`.ant-picker` → antd · `[data-radix-*]` / shadcn portals → radix · `.MuiSelect-*`/`.MuiPickersDay` → MUI · `.select2-container` → select2 · plain `<select>` → native.
+   - **Project-wide** conclusion (the whole app uses one library) → write/update `qa/app.yaml`: `extends: radix|antd|native`. **Element-level** outlier (one widget differs from the rest) → set `variant:` on that selector entry only (e.g. `variant: native`, `variant: antd-select`).
+   - Custom widget nobody's preset covers (in-house datepicker etc.) → author a recipe in `qa/app.yaml` `recipes:` (closed primitives: click/type/press/waitFor/clickText/expectText/expectValue/forEach) and bind it per element with `variant: <recipe-name>`.
+   - Toast/alert named from content (no aria-label) → `feedback.toast: { role: status, named_by: content }` + `name: null` on the selector entries.
+   - Loading indicator for `wait for [T] table to refresh` → `feedback.loading.indicator` (skip if the app sets `aria-busy`).
+   - **Every qa/app.yaml edit MUST carry provenance** in `detection:`: who/when (`detected_by`) and the observed evidence per key (`evidence:`). A profile without evidence is a guess a human cannot review.
 8. **Merge, don't overwrite**: preserve the page selector and any user-authored entries in `selectors.yaml`. Only add missing keys.
    - **Type-collision check** (see `sungen-selector-keys` § Collision rule): before writing a base key, check whether it already exists with a *different* `type`. If so, give **both** entries a `--type` suffix instead of clobbering or sharing the base key — a base-key entry of the wrong type gets picked up by any step referencing that label. Watch `page` especially: a `[X] page` step reads `value` as a URL, so if `X` already holds a button (`value: 'button'`) the assertion compiles to `toHaveURL(/button/)`. Write `X--page` (URL from the live page / feature `Path:`) alongside `X--button`.
 9. **Show summary + confirm**: list the keys that will be added, ask the user to approve, then write the file.
@@ -301,6 +308,18 @@ Only when `test-results/` screenshots are insufficient:
 
 Never use `browser_evaluate` to inject or read cookies (misses httpOnly). For auth, use Phase 0.5 or `sungen makeauth`.
 
+### Step 2b: Selector sanity probe — suspect the compiler/profile BEFORE the app
+
+For every failing locator, while the live page is in the failing state, count matches before attributing the failure to server load, timing, or flakiness:
+
+1. **Probe the exact generated locator** (copy it from the `.spec.ts`): count = 0 while the element is clearly on screen → the locator is wrong, not the app.
+2. **Peel one constraint at a time and re-count**:
+   - drop the `{ name }` filter → now found? → invented/wrong accessible name → fix `name:` or set `name: null` (name-from-content roles; matches compile warning `SG-W003`)
+   - drop the dialog/parent scope → now found? → portal-rendered element → check `qa/app.yaml` `layers.portal_roles` / remove a wrong `scope: 'dialog'`
+   - drop `exact`/text filter → now found? → text mismatch (NBSP, trailing space, i18n) → fix the value or use `{{variable}}`
+3. **Repair at the right altitude**: a per-element mistake → fix that `selectors.yaml` entry; a pattern repeated across elements (every toast, every dropdown) → fix `qa/app.yaml` once (with `detection.evidence`) so every screen inherits the fix. **Never rewrite the `.feature` to dodge a selector problem** — intent stays, identity/behavior get repaired.
+4. Also read the generate output: `SG-W001/W002/W003` diagnostics fired at compile time usually name the broken step before you run anything.
+
 ### Step 3: Fix Broken Selectors
 
 Selector priority (use first applicable):
@@ -367,6 +386,9 @@ Quick reference for the most frequent production failures:
 | `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` |
+| `strict mode violation` on `… with {{v}}` clicks (prefix-sharing options: "Văn phòng Hà Nội 1/2/…") | The `{{v}}` filter is a substring match by default | Add `exact: true` — since 3.3 it also anchors the `.filter({ hasText })` of action steps (`/^value$/`), not just role-name matching |
+| Toast/alert/spinner assertion times out but `[role="status"]` exists on the live page (`SG-W003` at generate time) | Entry has no `name:` → compiler defaulted `{ name: '<Gherkin ref>' }`, but status/alert names derive from CONTENT and never equal the reference | Add `name: null` to the entry (match by role only). Do NOT switch to `type: locator` |
+| Option/menu click inside a dialog times out, but the SAME locator works without dialog scope | Portal-rendered layer (Radix/MUI/antd) lives outside the dialog's DOM subtree | Since 3.3 the compiler page-roots portal roles (option/listbox/menu/menuitem/tooltip) automatically; for a listbox genuinely inside the dialog add `scope: 'dialog'` to the entry. Check `qa/app.yaml` `layers.portal_roles` (preset `native` disables the exemption) |
 | `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 |