@sun-asterisk/sungen 2.5.2 → 2.6.1

package/dist/orchestrator/templates/ai-instructions/copilot-cmd-review.md

@@ -6,7 +6,7 @@ agent: 'agent'
 tools: [vscode, read, edit, search, todo]
 ---
 
-**Input**: Screen name (e.g., `/sungen-review admin-users`).
+**Input**: Screen or flow name (e.g., `/sungen-review admin-users`).
 
 ## Role
 
@@ -14,17 +14,19 @@ You are a **Senior QA Reviewer**. You evaluate Gherkin test cases using the `sun
 
 ## Parameters
 
-- **screen** — ${input:screen:screen name (e.g., login, dashboard)}
+- **name** — ${input:name:screen or flow name (e.g., login, award-submission)}
+
+**Auto-detect context**: check if `qa/flows/<name>/` exists → flow mode (base path: `qa/flows/<name>/`). Else check `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
 
 ## Steps
 
-1. Read `qa/screens/${input:screen}/features/${input:screen}.feature` and `qa/screens/${input:screen}/test-data/${input:screen}.yaml`. If missing → `/sungen-create-test` first.
-2. Follow the `sungen-tc-review` skill — score 3 dimensions: Syntax (30pts), Coverage (40pts), Viewpoint (30pts). Use `sungen-viewpoint` for pattern checklists.
-3. **Unverified Selectors check** — if `qa/screens/${input:screen}/selectors/${input:screen}.yaml` exists, count lines matching `@needs-live-verify`. Include in the review report as a non-scoring metric (see `sungen-tc-review` skill for report format). Does NOT affect the 60% threshold.
+1. Read `<base>/<name>/features/<name>.feature` and `<base>/<name>/test-data/<name>.yaml`. If missing → `/sungen-create-test` first.
+2. Follow the `sungen-tc-review` skill — score 3 dimensions: Syntax (30pts), Coverage (40pts), Viewpoint (30pts). **For flows**, also apply the "Flow Review Additions" section. Use `sungen-viewpoint` for pattern checklists.
+3. **Unverified Selectors check** — if `<base>/<name>/selectors/<name>.yaml` exists, count lines matching `@needs-live-verify`. Include in the review report as a non-scoring metric. Does NOT affect the 60% threshold.
 4. Output review report per `sungen-tc-review` format. **>= 60%**: PASS. **< 60%**: FAIL with recommendations.
 5. If FAIL and user confirms → update test cases following `sungen-gherkin-syntax` and `sungen-tc-generation` skills, then re-review.
 6. After PASS (or user decides to proceed), offer next steps:
 
-- **`/sungen-run-test ${input:screen}`** — Generate selectors, compile, and run tests (Recommended)
-- **`/sungen-create-test ${input:screen}`** — Add more test cases before running
+- **`/sungen-run-test ${input:name}`** — Generate selectors, compile, and run tests (Recommended)
+- **`/sungen-create-test ${input:name}`** — Add more test cases before running
 - **Done for now** — I'll come back later

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

@@ -1,7 +1,7 @@
 ---
 name: sungen-run-test
 description: 'Generate selectors + auth state via Playwright MCP, compile, and run Playwright tests — auto-fixes selectors on failure'
-argument-hint: '[screen-name]'
+argument-hint: '[name]'
 tools: [read, execute, edit, vscode/askQuestions, playwright/*]
 ---
 
@@ -11,11 +11,13 @@ You are a **Senior Developer**. Use `sungen-selector-fix`, `sungen-selector-keys
 
 ## Parameters
 
-Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
+Parse **name** from `$ARGUMENTS`. If missing, ask the user.
+
+**Auto-detect context**: check if `qa/flows/<name>/` exists → flow mode (base path: `qa/flows/<name>/`). Else check `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
 
 ## Pre-run (phased — per `sungen-selector-fix` skill)
 
-1. Verify `qa/screens/<screen>/` has `.feature` + `test-data.yaml`.
+1. Verify `<base>/<name>/` has `.feature` + `test-data.yaml`.
 2. **Phase 0 — Selector Pre-gen**: if `selectors.yaml` is missing/empty or doesn't cover the feature file's `[Reference]`s, apply the following decision tree before running Phase 0 from `sungen-selector-fix`:
 
    ```
@@ -29,14 +31,14 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
                    2. Apply selector heuristics from sungen-figma-source skill (testid > role+name > placeholder > label > locator > text)
                    3. Write selectors.yaml — every provisional entry gets this comment on the line above:
                           # @needs-live-verify source=figma node_id=<id>
-                   4. Compile: sungen generate --screen <screen> — must succeed
+                   4. Compile: Screen: sungen generate --screen <name>. Flow: sungen generate --flow <name> — must succeed
                    5. Phase 1 smoke check runs; tests using unverified selectors may fail
                       → auto-fix triggers on next run-test invocation when a live page is available
              NO  → hard stop: print the following message and stop:
                    "Cannot generate selectors: no live page URL and no spec_figma.md found.
                     Options:
                     • Provide the live URL so Playwright MCP can snapshot the page, OR
-                    • Run: sungen add --screen <screen> --figma <figma-url>  to generate spec_figma.md first"
+                    • Run: sungen add --screen <name> --figma <figma-url>  to generate spec_figma.md first"
    ```
 
    **Auto-fix on subsequent runs**: when `run-test` is invoked again with a reachable live page, Phase 0 compares the DOM snapshot against existing `selectors.yaml` entries. Entries tagged `# @needs-live-verify` are treated as candidates — if the actual selector differs, the entry is replaced and the comment removed (entry becomes verified). Entries that already match are also promoted to verified (comment removed).
@@ -50,7 +52,7 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
      name: "Submit"
    ```
 3. **Phase 0.5 — Auth Persistence**: if the feature has `@auth:<role>` tags and `specs/.auth/<role>.json` is missing/expired, run Phase 0.5 from `sungen-selector-fix` — user logs in manually in MCP browser → `browser_storage_state` → `specs/.auth/<role>.json`. Offer `sungen makeauth <role>` as CLI fallback only if `browser_storage_state` isn't available in this MCP version.
-4. Compile: `sungen generate --screen <screen>` (default: runtime data loading from YAML). Use `--inline-data` only if user requests compile-time hardcoded values.
+4. Compile: **Screen**: `sungen generate --screen <name>`. **Flow**: `sungen generate --flow <name>`. Default: runtime data loading from YAML. Use `--inline-data` only if user requests compile-time hardcoded values.
 
 ## Run & Fix (phased — per `sungen-selector-fix` skill)
 
@@ -61,25 +63,27 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 
 ## Playwright command guidelines
 
-**Per-screen JSON results** — each run must write its JSON report to a dedicated path co-located with the `.spec.ts`, so `sungen delivery` can read the correct results per screen:
+**Per-screen/flow JSON results** — each run must write its JSON report to a dedicated path co-located with the `.spec.ts`, so `sungen delivery` can read the correct results:
 
 ```bash
-# ✅ Correct — per-screen output file via env var
-PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/<screen>/<screen>-test-result.json \
-  npx playwright test specs/generated/<screen>/<screen>.spec.ts
-```
+# ✅ Screen
+PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/<name>/<name>-test-result.json \
+  npx playwright test specs/generated/<name>/<name>.spec.ts
 
-Output: `specs/generated/<screen>/<screen>-test-result.json`
+# ✅ Flow
+PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/flows/<name>/<name>-test-result.json \
+  npx playwright test specs/generated/flows/<name>/<name>.spec.ts
+```
 
 **DO NOT** pass `--reporter=...` flag — it overrides the reporters from `playwright.config.ts` and disables the JSON reporter that `sungen delivery` depends on.
 
 ```bash
 # ❌ Wrong — --reporter flag disables the config's JSON reporter
-npx playwright test specs/generated/<screen>/<screen>.spec.ts --reporter=list
+npx playwright test specs/generated/<name>/<name>.spec.ts --reporter=list
 
 # ❌ Wrong — no env var → writes to default test-results/results.json
 # (overwritten on every screen run, loses per-screen tracking)
-npx playwright test specs/generated/<screen>/<screen>.spec.ts
+npx playwright test specs/generated/<name>/<name>.spec.ts
 ```
 
 If you want to filter scenarios, use `-g "<pattern>"` instead of a reporter override.
@@ -91,10 +95,10 @@ If you want to filter scenarios, use `-g "<pattern>"` instead of a reporter over
 After showing results, use `AskUserQuestion` to offer next steps:
 
 If all tests **passed**:
-- **`/sungen:create-test <screen>`** — Add more test cases (Recommended)
+- **`/sungen-create-test <name>`** — Add more test cases (Recommended)
 - **Done** — All tests passed, I'm finished
 
 If tests **failed** (after retries):
-- **`/sungen:run-test <screen>`** — Re-run after manual fixes
-- **`/sungen:create-test <screen>`** — Revise test cases
+- **`/sungen-run-test <name>`** — Re-run after manual fixes
+- **`/sungen-create-test <name>`** — Revise test cases
 - **Done for now** — I'll fix manually later

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

@@ -21,22 +21,28 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-capture-live` | Capture a live running page via Playwright MCP (snapshot + screenshot) |
 | `sungen-figma-source` | Figma URL → spec_figma.md + ui/*.png + provisional selectors |
 
-## Workflow (5 AI commands)
+## Workflow (6 AI commands)
 
 | Command | What it does |
 |---|---|
 | `/sungen-add-screen <name> <path>` | Scaffold `qa/screens/<name>/` directories |
-| `/sungen-create-test <name>` | Generate `.feature` + `test-data.yaml` (no selectors) |
-| `/sungen-review <name>` | Score syntax, coverage, viewpoint quality (60% threshold) |
-| `/sungen-run-test <name>` | Generate `selectors.yaml` from live page, compile, run, auto-fix |
+| `/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-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) |
 
-**Order:** add-screen → create-test → review → run-test → delivery.
+**Screen path:** add-screen → create-test → review → run-test → delivery.
+**Flow path:** add-flow → create-test → review → run-test → delivery.
+
+`create-test`, `review`, and `run-test` auto-detect context: if `qa/flows/<name>/` exists → flow mode, else `qa/screens/<name>/` → screen mode.
 
 After each command completes, present the next actions as selectable options. Never just print text — always give clickable choices so the user can continue the workflow seamlessly.
 
 ## File Structure
 
+### Screen (single-screen testing)
+
 ```
 qa/screens/<screen-name>/
 ├── features/<screen>.feature      # Gherkin scenarios
@@ -47,9 +53,27 @@ qa/screens/<screen-name>/
 └── requirements/
     ├── spec.md                    # Screen specification (primary source)
     └── ui/                        # Screenshots, mockups
+```
+
+### Flow (E2E cross-screen testing)
 
-qa/deliverables/<screen>-testcases.csv  # Exported test cases (from /sungen-delivery)
-qa/deliverables/<screen>-testcases.xlsx # Styled workbook for client hand-off
+```
+qa/flows/<flow-name>/
+├── features/<flow>.feature        # Gherkin with @flow tag, [Screen:Element] refs
+├── selectors/<flow>.yaml          # Namespaced keys: "login:submit", "awards:title"
+├── test-data/<flow>.yaml          # Namespaced data: login.email, submission.nominee
+├── test-data/<flow>.staging.yaml      # Environment override (optional)
+├── test-data/<flow>.production.yaml   # Environment override (optional)
+└── requirements/
+    ├── spec.md                    # Flow specification (screens, steps, transitions)
+    └── ui/                        # Screenshots, mockups
+```
+
+Flows are **independent** from screens — own selectors, own test-data. Selectors use colon-namespaced keys (`"login:submit":`) to avoid duplicate element names across screens.
+
+```
+qa/deliverables/<name>-testcases.csv   # Exported test cases (from /sungen-delivery)
+qa/deliverables/<name>-testcases.xlsx  # Styled workbook for client hand-off
 ```
 
 ## Test Data
@@ -61,11 +85,18 @@ qa/deliverables/<screen>-testcases.xlsx # Styled workbook for client hand-off
 ## CLI Commands
 
 ```bash
+# Screen
 sungen add --screen <name> --path <url-path>               # Scaffold screen directories
 sungen add --screen <name> --path <path> --feature <name>   # Scaffold with sub-feature
 sungen generate --screen <name>                              # Compile .feature → .spec.ts (runtime data)
 sungen generate --screen <name> --inline-data                # Compile with hardcoded data (legacy)
-sungen generate --all                                        # Compile all screens
+
+# Flow
+sungen add-flow --flow <name> --path <start-url>            # Scaffold flow directories
+sungen generate --flow <name>                                # Compile flow .feature → .spec.ts
+
+# All
+sungen generate --all                                        # Compile all screens and flows
 sungen delivery                                              # Export all screens → CSV + XLSX
-sungen delivery <screen>                                     # Export a single screen
+sungen delivery <name>                                       # Export a single screen or flow
 ```

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-capture-live.md

@@ -61,6 +61,18 @@ Where `<timestamp>` is `YYYYMMDD-HHMM` in local time (e.g. `live-20260421-1430.p
 
 This gives users a visual record they can reference later without re-scanning.
 
+### 6a. Verify unauthenticated redirect target (flow capture only)
+
+When capturing for a **flow** that includes security scenarios (e.g., "unauthenticated user cannot access X"):
+
+1. Open a **fresh incognito/unauthenticated** browser context (no storage state).
+2. `browser_navigate` to the protected route (e.g., `/dashboard`).
+3. Record the **actual redirect URL** — do NOT assume it goes to `/login`. The app may redirect to `/register`, `/`, or any other route.
+4. Report the redirect target to the caller: *"Unauthenticated access to `/dashboard` redirects to `/register`"*.
+5. The caller must use the **actual redirect URL** in Gherkin assertions (e.g., `Then User is on [Register] page`), never an assumed one.
+
+Skip this step if the flow has no security scenarios or the user explicitly says to skip.
+
 ### 6. Detect discrepancies vs spec
 
 If `spec.md` exists, briefly cross-check the snapshot against spec sections:

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

@@ -6,7 +6,7 @@ user-invocable: false
 
 ## Purpose
 
-Export test cases from Sungen screens to a standardized CSV file (format BM-2-901-13) for QA delivery.
+Export test cases from Sungen screens and flows to a standardized CSV file (format BM-2-901-13) for QA delivery.
 
 **This skill delegates all heavy work to the `sungen delivery` CLI.** The CLI is the single source of truth for parsing logic — do NOT re-parse files in AI. Your role is only to:
 
@@ -19,18 +19,19 @@ Export test cases from Sungen screens to a standardized CSV file (format BM-2-90
 ## Architecture
 
 ```
-User → /sungen:delivery [screen...]
+User → /sungen:delivery [name...]
        │
        ▼
   sungen delivery CLI  (deterministic — no AI tokens)
-  ├─ Scope detection (no-arg = all screens)
-  ├─ Pre-flight source checks per screen
+  ├─ Scope detection (no-arg = all screens + flows)
+  ├─ Auto-detect: qa/flows/<name>/ → flow, qa/screens/<name>/ → screen
+  ├─ Pre-flight source checks per target
   ├─ Parse .feature (metadata)
   ├─ Parse .spec.ts (resolved Playwright code — source of truth)
   ├─ Parse test-data.yaml (resolve {{vars}})
   ├─ Parse test-results/results.json (match test titles)
   ├─ Merge sources + generate CSV rows
-  └─ Write qa/deliverables/<screen>-testcases.csv
+  └─ Write qa/deliverables/<name>-testcases.csv
 ```
 
 Source modules: `src/exporters/*.ts`
@@ -39,18 +40,18 @@ Source modules: `src/exporters/*.ts`
 
 ## Required sources (CLI pre-flight checks these)
 
-| # | Source | Path | Created by |
-|---|--------|------|------------|
-| 1 | Feature file | `qa/screens/<screen>/features/<screen>.feature` | `/sungen:add-screen` + `/sungen:create-test` |
-| 2 | Test data | `qa/screens/<screen>/test-data/<screen>.yaml` | `/sungen:create-test` |
-| 3 | Selectors | `qa/screens/<screen>/selectors/<screen>.yaml` | `/sungen:run-test` |
-| 4 | Compiled spec | `specs/generated/<screen>/<screen>.spec.ts` | `sungen generate` (during `/sungen:run-test`) |
-| 5 | Test results | `specs/generated/<screen>/<screen>-test-result.json` (per-screen) or `test-results/results.json` (global fallback) | `/sungen:run-test` |
+| # | Source | Screen path | Flow path | Created by |
+|---|--------|-------------|-----------|------------|
+| 1 | Feature file | `qa/screens/<name>/features/<name>.feature` | `qa/flows/<name>/features/<name>.feature` | `add-screen`/`add-flow` + `create-test` |
+| 2 | Test data | `qa/screens/<name>/test-data/<name>.yaml` | `qa/flows/<name>/test-data/<name>.yaml` | `create-test` |
+| 3 | Selectors | `qa/screens/<name>/selectors/<name>.yaml` | `qa/flows/<name>/selectors/<name>.yaml` | `run-test` |
+| 4 | Compiled spec | `specs/generated/<name>/<name>.spec.ts` | `specs/generated/flows/<name>/<name>.spec.ts` | `sungen generate` |
+| 5 | Test results | `specs/generated/<name>/<name>-test-result.json` or `test-results/results.json` | `specs/generated/flows/<name>/<name>-test-result.json` or global fallback | `run-test` |
 
 **Sources 1-4 are blocking** — CLI aborts if any is missing.
 **Source 5 is optional** — CSV is still generated but Test Result/Date/Executor/Env columns are empty (all tests show as Pending).
 
-The CLI reads the **per-screen result file first** (co-located with `.spec.ts`), then falls back to the global `test-results/results.json`. Per-screen is preferred because the global file gets OVERWRITTEN each time Playwright runs, losing results from earlier screens.
+The CLI reads the **per-target result file first** (co-located with `.spec.ts`), then falls back to the global `test-results/results.json`. Per-target is preferred because the global file gets OVERWRITTEN each time Playwright runs, losing results from earlier targets.
 
 ---
 
@@ -87,17 +88,17 @@ The CLI reads the **per-screen result file first** (co-located with `.spec.ts`),
 ## CLI command reference
 
 ```bash
-# Export all screens
+# Export all screens and flows
 sungen delivery
 
-# Export specific screens
-sungen delivery kudos awards
+# Export specific targets (auto-detects screen vs flow)
+sungen delivery kudos awards nomination-flow
 
 # Skip pre-flight (CI only)
 sungen delivery --skip-preflight
 
-# Skip screens with blocking misses
+# Skip targets with blocking misses
 sungen delivery --continue-on-missing
 ```
 
-Output: `qa/deliverables/<screen>-testcases.csv` (UTF-8 with BOM)
+Output: `qa/deliverables/<name>-testcases.csv` (UTF-8 with BOM)

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-error-mapping.md

@@ -101,6 +101,18 @@ If `toHaveText` fails on an input → the Gherkin step has wrong target type. Fi
 
 ---
 
+## Flow-Specific Errors
+
+| Error | Diagnosis | Fix |
+|---|---|---|
+| Navigation timeout between screens | Cross-screen transition takes too long or URL mismatch | Add explicit `wait for page` step between screen transitions in `.feature`. Verify target URL path |
+| Selector `"screen:element"` not found | Namespace key missing or wrong format | Ensure colon-namespaced key in `selectors.yaml` is **quoted**: `"login:submit":`. Check screen prefix matches `[Screen:Element]` ref in Gherkin |
+| Test data `screen.key` undefined | Phase namespace mismatch | Verify `test-data.yaml` uses dot-namespaced keys: `login.email`, `submission.nominee`. Keys must match `{{screen.key}}` refs in `.feature` |
+| State lost between screens | Auth/session expired during multi-screen flow | Ensure all screens in the flow share the same `@auth:role` tag. Check if the app invalidates sessions on navigation |
+| Duplicate selector key across screens | Two screens use same element name without namespace | Always use `[Screen:Element]` format in flow `.feature`. Selectors must use `"screen:element":` quoted keys |
+
+---
+
 ## Performance & Infrastructure Errors → Fix in `specs/base.ts`
 
 All generated `.spec.ts` import from `specs/base.ts` — shared context caching, navigation, overlay cleanup. AI **can and should** tune `base.ts` to match the project.

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

@@ -120,6 +120,32 @@ Most elements auto-infer from `[Label] type` → `getByRole(type, { name: 'Label
 - Same label, nth occurrence → add `--N` suffix
 - Target Name > 30 chars → shorten to 1–3 meaningful words
 
+## Dynamic Variables (test-data YAML)
+
+Use `{{$var}}` in test-data YAML for values that must be unique per test run. Resolved at **runtime** by `TestDataLoader` — the compiler passes them through unchanged.
+
+| Variable | Example | Output |
+|---|---|---|
+| `{{$timestamp}}` | `"User-{{$timestamp}}"` | `"User-1714000000"` |
+| `{{$uuid}}` | `"{{$uuid}}"` | `"a1b2c3d4-..."` |
+| `{{$random:min:max}}` | `"{{$random:1:100}}"` | `"42"` |
+| `{{$date}}` | `"{{$date}}"` | `"2026-04-24"` |
+| `{{$datetime}}` | `"{{$datetime}}"` | `"2026-04-24T10:30:00.000Z"` |
+
+**Rules:**
+- `$timestamp` and `$uuid` → same value across all keys in one `load()` call (stable within a test file)
+- `$random` → unique per occurrence (each key gets a different random)
+- Resolved once at load time → every `get()` returns the same resolved value
+- Use for CRUD flows to avoid data collision between parallel runs
+
+```yaml
+# test-data/crud-award.yaml
+award:
+  name: "Award-{{$timestamp}}"
+  email: "test+{{$uuid}}@example.com"
+  score: "{{$random:1:100}}"
+```
+
 ## Selectors (priority order)
 
 | type | value | name | use |
@@ -138,27 +164,112 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 
 ## Tags
 
+### Functional tags (affect code generation)
+
 | Tag | Effect |
 |---|---|
-| `@auto` | Standard scenario, ready for automation |
 | `@manual` | Skip in generation |
-| `@smoke` / `@regression` | Test suite grouping |
-| `@critical` | Priority: system unusable if fails (login, auth, core CRUD) |
-| `@high` | Priority: major feature broken (required validation, key business rules) |
-| `@normal` | Priority: degraded experience (UI layout, secondary flows) |
-| `@low` | Priority: minor/cosmetic (tooltips, hover states, empty states) |
 | `@auth:role` | Use auth storage state for role |
 | `@no-auth` | Disable inherited auth |
 | `@steps:name` | Define reusable step block (base scenario) |
 | `@extend:name` | Prepend Given→When from @steps block (skip Then) |
-| `@cleanup:overlay` | Auto-cleanup: dismiss dialogs/overlays after each test (base.ts fixture) |
-| `@cleanup:forms` | Auto-cleanup: clear form fields after each test (base.ts fixture) |
-| `@cleanup:scroll` | Auto-cleanup: scroll to top after each test (base.ts fixture) |
-| `@cleanup:storage` | Auto-cleanup: clear sessionStorage after each test (base.ts fixture) |
+| `@cleanup:overlay` | Auto-cleanup: dismiss dialogs/overlays after each test (cleanupPage) |
+| `@cleanup:forms` | Auto-cleanup: clear form fields after each test (cleanupPage) |
+| `@cleanup:scroll` | Auto-cleanup: scroll to top after each test (cleanupPage) |
+| `@cleanup:storage` | Auto-cleanup: clear sessionStorage after each test (cleanupPage) |
 | `@screenshot:on-failure` | Auto-capture screenshot when test fails (base.ts fixture) |
+| `@parallel` | Opt-out: fresh page per test instead of serial default (for independent scenarios) |
 | `@beforeAll` | Hook: runs once before all tests → `test.beforeAll()` |
 | `@afterEach` | Hook: runs after each test → `test.afterEach()` (custom cleanup) |
 | `@afterAll` | Hook: runs once after all tests → `test.afterAll()` |
+| `@flow` | Mark feature as E2E flow (cross-screen testing) |
+
+### Pass-through tags (filter at runtime via Playwright --grep)
+
+Any tag not listed above passes through to Playwright `{ tag: [...] }`. Feature-level tags inherit to all scenarios.
+
+| Tag | Purpose |
+|---|---|
+| `@smoke` | Quick sanity check — run after every deploy |
+| `@regression` | Full test suite — run nightly or before release |
+| `@critical` | Priority: system unusable if fails (login, auth, core CRUD) |
+| `@high` | Priority: major feature broken (required validation, key business rules) |
+| `@normal` | Priority: degraded experience (UI layout, secondary flows) |
+| `@low` | Priority: minor/cosmetic (tooltips, hover states, empty states) |
+| `@auto` | Standard scenario, ready for automation |
+| Any custom | e.g., `@sprint-42`, `@team-payment` — any tag works |
+
+**Run filtered:**
+```bash
+npx playwright test --grep "@smoke"          # only smoke tests
+npx playwright test --grep "@critical"       # only critical priority
+npx playwright test --grep "@smoke|@critical" # smoke OR critical
+```
+
+### Serial vs Parallel (test execution mode)
+
+**Default: serial** — `test.describe.serial()` with shared page. Background runs once in `beforeAll`. Fail → skip remaining.
+
+**`@parallel` opt-out** — `test.describe()` with fresh page per test. Background runs as `beforeEach`. Use when scenarios are truly independent (validation rules, permission tests).
+
+| Mode | Generated | Page | Background | On fail |
+|---|---|---|---|---|
+| Serial (default) | `test.describe.serial()` | Shared | `beforeAll` (1 goto) | Skip remaining |
+| `@parallel` | `test.describe()` | Fresh per test | `beforeEach` (N goto) | Continue |
+
+**`@parallel` is required** when a feature has multiple auth groups (e.g., `@auth:user` + `@no-auth` scenarios). Serial mode uses one shared browser context and cannot mix auth roles. The compiler will error if `@parallel` is missing in this case.
+
+### `@flow` tag (E2E cross-screen testing)
+
+`@flow` marks a feature as a **flow** — an E2E journey spanning multiple screens. Flows live in `qa/flows/<name>/` with their own selectors, test-data, and requirements.
+
+**Key differences from screen tests:**
+
+| Aspect | Screen (`qa/screens/`) | Flow (`qa/flows/`) |
+|---|---|---|
+| Scope | Single page | Multiple pages |
+| Selectors | `[Element]` → own YAML | `[Screen:Element]` → own YAML (namespaced) |
+| Test data | `{{variable}}` | `{{phase.variable}}` (namespaced by phase) |
+| Tag | `@auto` / `@smoke` etc. | `@flow` (required at feature level) |
+| Multi-domain | N/A | Absolute URL in selector `path:` skips baseURL |
+
+**Selector namespace format:** `[Screen:Element]` where colon separates screen prefix from element name. The YAML key is `"screen:element"` (quoted, lowercase).
+
+```gherkin
+# Feature file
+When User fill [Login:Email] field with {{login.email}}
+And User click [Login:Submit] button
+Then User see [Dashboard] page
+When User click [Dashboard:Awards] link
+```
+
+```yaml
+# selectors.yaml — keys are namespaced, quoted due to colon
+"login:email":
+  type: 'testid'
+  value: 'email-input'
+
+"login:submit":
+  type: 'role'
+  value: 'button'
+  name: 'Login'
+
+dashboard:
+  type: 'page'
+  value: '/dashboard'
+
+"dashboard:awards":
+  type: 'role'
+  value: 'link'
+  name: 'Awards'
+```
+
+**Flow structure:**
+- `Background:` — set starting page only (e.g., `Given User is on [Login] page`)
+- Each `Scenario:` — one phase/step of the flow (login, navigate, submit, etc.)
+- Page navigation between scenarios uses `[Screen] page` references
+
+**CLI:** `sungen add-flow --flow <name>`, `sungen generate --flow <name>`, `sungen generate --all` (includes flows)
 
 ### @extend behavior
 
@@ -185,6 +296,7 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | Missing target type | `fill [email] with {{v}}` | `fill [email] field with {{v}}` |
 | Background with scope | `Background: ... And User is on [X] dialog` | Use `@steps` + `@extend` for scope-dependent flows |
 | `is on` after When | `When ... And User is on [X] dialog` | `And User see [X] dialog` or separate Given |
+| Literal URL navigate | `User navigate to "/dashboard"` | `User is on [Dashboard] page` (add page selector in `selectors.yaml`) |
 
 ## Background vs @steps/@extend
 

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

@@ -24,6 +24,28 @@ Run tests in priority waves — catch fundamental issues early, fix critical pat
 
 If existing selectors already cover the feature file, **skip Phase 0** and go straight to compile + Phase 1.
 
+### Flow Mode: Screen Selector Reference
+
+When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen selectors first before snapshotting live pages. Screen selectors are already verified and proven — reuse them to save time and reduce errors.
+
+**Steps (before the standard Phase 0 steps):**
+
+1. **Parse screen references**: read the `.feature` file for `[Screen:Element]` references. Group by screen name (e.g., `Login`, `Awards`, `Dashboard`).
+2. **For each referenced screen**, check `qa/screens/<screen>/selectors/<screen>.yaml`:
+   - **If exists** → copy matching entries to the flow's `selectors.yaml`, remapping keys to namespace format:
+     - Screen key `submit` with screen `login` → flow key `"login:submit"`
+     - Screen key `email-field` with screen `login` → flow key `"login:email-field"`
+     - Preserve the full selector definition (type, value, name, etc.)
+     - Mark these entries as **verified** (no `@needs-live-verify` comment needed)
+   - **If not found** → add this screen to the "needs live snapshot" list
+3. **Elements not found in any screen selector** → also added to the "needs live snapshot" list
+4. **If "needs live snapshot" list is empty** → Phase 0 screen-reference covered everything, skip to compile
+5. **If "needs live snapshot" list is non-empty** → continue with the standard Phase 0 steps below, but only generate selectors for the missing elements (don't re-snapshot elements already copied from screens)
+
+**Merge rule**: screen-referenced entries take priority over provisional (Figma-sourced) entries. If an element was previously generated from Figma with `@needs-live-verify`, the screen-verified entry replaces it.
+
+**Important**: flow selectors remain private — they live in the flow's own YAML file. This is just initialization from screen data, not a runtime dependency.
+
 ### Steps
 
 1. **Confirm with the user**: *"Generate selectors from the live page via Playwright MCP now?"* — offer **Yes, scan live page** / **Skip (use existing selectors.yaml)** / **Cancel**.
@@ -39,9 +61,10 @@ If existing selectors already cover the feature file, **skip Phase 0** and go st
    - Selector priority: follow the table in **Diagnosis & Fix § Step 3** (`testid` > `role`+name > `placeholder` > `label` > `locator` > `text`).
    - Copy names **character-for-character** from the snapshot. Never infer from the Gherkin label.
    - If an element is auto-inferable per `sungen-selector-keys` § Auto-Infer, **omit it** from YAML — keep the file minimal.
-7. **Merge, don't overwrite**: preserve the page selector and any user-authored entries in `selectors.yaml`. Only add missing keys.
-8. **Show summary + confirm**: list the keys that will be added, ask the user to approve, then write the file.
-9. **Compile**: `sungen generate --screen <screen>` — then proceed to Phase 1.
+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.
+10. **Compile**: **Screen**: `sungen generate --screen <screen>`. **Flow**: `sungen generate --flow <flow>`. Then proceed to Phase 1.
 
 ### Common Phase 0 pitfalls
 
@@ -265,6 +288,7 @@ Array.from(document.querySelectorAll('[data-testid]'))
 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)
 - Element in iframe → add `frame` field
 - Dynamic content → use `testid` or structural `role` + `nth`
@@ -273,7 +297,11 @@ Common fixes:
 
 Always recompile before re-running:
 ```bash
+# Screen
 sungen generate --screen <screen>
+
+# Flow
+sungen generate --flow <flow>
 ```
 
 Then re-run only the current phase's failing tests, not all tests.

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

@@ -27,6 +27,51 @@ Copy the text from `[Reference]` as-is, then lowercase. Unicode characters (Viet
 4. **Keep all Unicode characters as-is** (Vietnamese diacritics, Japanese, etc.)
 5. **Keys use spaces** (not dots) as word separators
 
+## Flow Namespaced Keys
+
+In `@flow` features, selectors are namespaced by screen using colon: `[Screen:Element]` → YAML key `"screen:element"` (quoted).
+
+```
+[Login:Email]        → "login:email"
+[Login:Submit]       → "login:submit"
+[Dashboard:Awards]   → "dashboard:awards"
+[Awards:Submit]      → "awards:submit"
+```
+
+**Rules:**
+1. Same lowercase + Unicode rules as standard keys
+2. Colon separates screen prefix from element name
+3. **YAML keys must be quoted** because of the colon: `"login:email":`
+4. Page references don't need prefix: `[Login]` → `login:` (page type)
+5. Prevents duplicate names across screens (e.g., `"login:submit"` vs `"awards:submit"`)
+
+```yaml
+# Flow selectors — each screen section namespaced
+login:
+  type: 'page'
+  value: '/login'
+
+"login:email":
+  type: 'testid'
+  value: 'email-input'
+
+"login:submit":
+  type: 'role'
+  value: 'button'
+  name: 'Login'
+
+awards:
+  type: 'page'
+  value: '/awards'
+
+"awards:submit":
+  type: 'role'
+  value: 'button'
+  name: 'Submit Award'
+```
+
+**Type and nth suffixes still apply:** `"login:submit--button"`, `"awards:item--3"`
+
 ## Type-Suffixed Keys
 
 When the same label is used for different element types, add `--type` suffix: