@sun-asterisk/sungen 2.4.3 → 2.4.6

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

@@ -0,0 +1,103 @@
+---
+name: sungen-delivery
+description: 'Export Gherkin scenarios + Playwright results → CSV test case deliverable. Auto-loaded by delivery command.'
+user-invocable: false
+---
+
+## Purpose
+
+Export test cases from Sungen screens 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:
+
+1. Invoke the CLI
+2. Show its output verbatim
+3. Help the user react to pre-flight failures
+
+---
+
+## Architecture
+
+```
+User → /sungen:delivery [screen...]
+       │
+       ▼
+  sungen delivery CLI  (deterministic — no AI tokens)
+  ├─ Scope detection (no-arg = all screens)
+  ├─ Pre-flight source checks per screen
+  ├─ 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
+```
+
+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` |
+
+**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.
+
+---
+
+## Column mapping (handled by CLI)
+
+| CSV Column | Source |
+|------------|--------|
+| TC ID | Generated: `<SCREEN_UPPER>-<VP>-<NNN>` |
+| Category 1 | Scenario name with VP prefix stripped |
+| Category 2 | VP group: `VP-SEC`→Accessing, `VP-UI`→GUI, `VP-VAL`/`VP-LOGIC`→Function |
+| Category 3 | Feature name (first line of `.feature`) |
+| Category 4 | Screen name |
+| Pre-condition | Auth tag → "Logged in as X" / "Not authenticated" + Given steps (natural language) |
+| Test Data | `{{vars}}` from scenario resolved via test-data.yaml → `key: value; key2: value2` |
+| Steps | `.spec.ts` code comments for interactions (numbered) |
+| Expected results | `.spec.ts` `expect(...)` comments (numbered) |
+| Priority | Tag: `@critical`/`@high`/`@normal`/`@low` (default: Normal) |
+| Testcase type | `@manual` → Manual, else Auto. Not compiled → "Not compiled" |
+| Test Result | results.json status: passed→Passed, failed/timedOut→Failed, skipped→N/A, else Pending |
+| Executed Date | results.json startTime formatted as `dd/mm/yyyy` |
+| Test Executor | `git config user.name` |
+| Test Environment | `playwright.config.ts` baseURL + project name |
+| Note | Error message + trace path (for failed tests) |
+
+---
+
+## Excluded from CSV
+
+- `@steps:<name>` **base** scenarios — these are setup-only, inlined into `@extend:...` scenarios at compile time
+- Default scaffold `Sample scenario for <screen>` — not a real test
+
+---
+
+## CLI command reference
+
+```bash
+# Export all screens
+sungen delivery
+
+# Export specific screens
+sungen delivery kudos awards
+
+# Skip pre-flight (CI only)
+sungen delivery --skip-preflight
+
+# Skip screens with blocking misses
+sungen delivery --continue-on-missing
+```
+
+Output: `qa/deliverables/<screen>-testcases.csv` (UTF-8 with BOM)

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

@@ -109,6 +109,8 @@ Row scope: `see [Ref] row in [Table] table with {{v}}` enters scope. Subsequent
 
 Most elements auto-infer from `[Label] type` → `getByRole(type, { name: 'Label' })`. Only add YAML when the accessible name differs, needs `nth`, or needs `testid`. Full auto-infer table → see `sungen-selector-keys` skill.
 
+**Types requiring YAML entry:** `date-picker`, `uploader`, `overlay`, `frame`, `step` - these have no standard ARIA role and need explicit selectors.
+
 ## YAML Keys
 
 `[Reference]` → **lowercase, keep Unicode**: `[Search Content]` → `search content:`, `[Thời gian]` → `thời gian:`

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

@@ -8,7 +8,88 @@ user-invocable: false
 
 Run tests in priority waves — catch fundamental issues early, fix critical paths first, let shared fixes cascade to lower-priority tests.
 
-**Never run all tests blindly.** Always start with a smoke check.
+**Never run all tests blindly.** Always start with selector pre-generation, then a smoke check.
+
+---
+
+## Phase 0: Pre-run Selector Generation (Playwright MCP)
+
+**Before any `sungen generate` or test run**, populate `selectors.yaml` from the live page so tests don't fail on missing keys in Phase 1.
+
+### When to run Phase 0
+
+- `selectors.yaml` missing, empty, or contains only the page selector
+- The `.feature` file has `[Reference]` keys without corresponding YAML entries and the referenced element can't be auto-inferred (see `sungen-selector-keys` § Auto-Infer)
+- User explicitly re-scans after UI changes
+
+If existing selectors already cover the feature file, **skip Phase 0** and go straight to compile + Phase 1.
+
+### Steps
+
+1. **Confirm with the user** via `AskUserQuestion`: *"Generate selectors from the live page via Playwright MCP now?"* — offer **Yes, scan live page** / **Skip (use existing selectors.yaml)** / **Cancel**.
+2. **Collect references**: parse the `.feature` file for every `[Reference]` element + its type (e.g. `[Submit] button`, `[Email] field`). Deduplicate.
+3. **Ensure page selector**: if missing, ask user for URL path and write it first.
+4. **Navigate**:
+   - Read `baseURL` from `playwright.config.ts`.
+   - `browser_navigate` to the page URL.
+   - If redirected to login → run **Phase 0.5: Auth Persistence** first (see below), then re-navigate to the target page.
+5. **Snapshot**: take **ONE** `browser_snapshot`. All Phase 0 selectors come from this single snapshot.
+6. **Generate YAML entries**:
+   - Keys: follow `sungen-selector-keys` (lowercase, Unicode preserved, `--type` / `--N` suffixes).
+   - Selector priority: follow the table in **Diagnosis & Fix § Step 3** (`testid` > `role`+name > `placeholder` > `label` > `locator` > `text`).
+   - Copy names **character-for-character** from the snapshot. Never infer from the Gherkin label.
+   - If an element is auto-inferable per `sungen-selector-keys` § Auto-Infer, **omit it** from YAML — keep the file minimal.
+7. **Merge, don't overwrite**: preserve the page selector and any user-authored entries in `selectors.yaml`. Only add missing keys.
+8. **Show summary + confirm**: list the keys that will be added, ask the user to approve, then write the file.
+9. **Compile**: `sungen generate --screen <screen>` — then proceed to Phase 1.
+
+### Common Phase 0 pitfalls
+
+- Writing keys inferred from the Gherkin label instead of the snapshot name → Phase 1 will fail with "no element found".
+- Skipping Phase 0.5 when an auth redirect happened → snapshot captures the login page, all selectors wrong.
+- Using `browser_evaluate` alone to scrape cookies → misses httpOnly session cookies. Always use `browser_storage_state` (or the `browser_run_code` fallback).
+- Overwriting user-authored selectors → always merge.
+
+---
+
+## Phase 0.5: Auth Persistence (MCP alternative to `sungen makeauth`)
+
+Capture an authenticated session from the MCP browser into `specs/.auth/<role>.json` — the same path `sungen makeauth` writes to, which compiled tests already reference via `test.use({ storageState })` based on `@auth:<role>` tags. No `playwright.config.ts` edits needed. Run once per auth lifetime, not on every selector fix.
+
+### When to run Phase 0.5
+
+- Phase 0 navigation hit a login redirect and `specs/.auth/<role>.json` is missing or expired
+- A scenario tagged `@auth:<role>` is about to run and its auth file is absent
+- User asks to refresh auth
+
+Skip if `specs/.auth/<role>.json` already exists and a probe navigation reaches an authenticated page without redirecting to login.
+
+### Steps
+
+1. **Resolve the role**:
+   - Look at the `.feature` file for `@auth:<role>` tags (feature-level or scenario-level). Pick the role for the scenario being run. If no tag exists, default to `user`.
+   - Target file: `specs/.auth/<role>.json`. Create `specs/.auth/` if missing.
+   - If the file already exists → use `AskUserQuestion` to confirm overwrite (mirrors the `(y/N)` prompt in `sungen makeauth`).
+2. **Navigate to login**:
+   - Read `baseURL` from `playwright.config.ts` (fall back to `APP_BASE_URL` env, then `http://localhost:3000` — same resolution order as `sungen makeauth`).
+   - `browser_navigate` to `<baseURL>/login`. If the app uses a different login path, ask the user.
+   - If the URL doesn't stay on `/login` after load → user is already signed in. Skip step 3.
+3. **Ask the user to log in manually** in the MCP browser (username, password, MFA, SSO — whatever the app needs). Never type credentials via `browser_type` or script the login. Wait for the user to confirm in chat that they're signed in.
+4. **Verify login** — check the current URL or take a `browser_snapshot`; confirm the page is no longer on `/login`.
+5. **Export storage state** (preferred → fallback):
+   - **Preferred** — `browser_storage_state` with `filename: "specs/.auth/<role>.json"` (native Playwright MCP tool; captures cookies including httpOnly + localStorage + sessionStorage via the Playwright context — same output format as `context.storageState({ path })` used by `sungen makeauth`).
+   - **Fallback** — if `browser_storage_state` isn't available in this MCP version, use `browser_run_code` to execute `await context.storageState({ path: 'specs/.auth/<role>.json' })`.
+   - **Do NOT** use `browser_evaluate` for auth export — it misses httpOnly cookies and session auth will fail silently.
+6. **Gitignore** — ensure `specs/.auth/` (or `specs/.auth/*.json`) is in `.gitignore`. Add it if missing.
+7. **Return to Phase 0 step 4** — re-`browser_navigate` to the target page; the session is now active.
+
+### Phase 0.5 pitfalls
+
+- Writing to a path other than `specs/.auth/<role>.json` → compiled tests won't find the file. Always match `sungen makeauth`'s convention.
+- Committing `specs/.auth/*.json` → leaks a live session. Always gitignore.
+- Scripting the login with `browser_type` → bypasses MFA/CAPTCHA and risks account lockout. Always manual.
+- Running Phase 0.5 on every `run-test` invocation → unnecessary; reuse the file until tests start redirecting to login.
+- Mismatch between `<role>` in the auth file and `@auth:<role>` tag → compiled tests reference a nonexistent file.
 
 ---
 
@@ -94,10 +175,10 @@ Only when `test-results/` screenshots are insufficient:
 
 1. Read `baseURL` from `playwright.config.ts`
 2. `browser_navigate` to target page
-3. If redirected to login → ask user to log in manually via MCP browser
+3. If redirected to login → run **Phase 0.5: Auth Persistence**, then re-navigate
 4. Take **ONE** `browser_snapshot` — fix all broken selectors from this single snapshot
 
-**Never use `sungen makeauth`.** Never use `browser_evaluate` to inject cookies.
+Never use `browser_evaluate` to inject or read cookies (misses httpOnly). For auth, use Phase 0.5 or `sungen makeauth`.
 
 ### Step 3: Fix Broken Selectors
 
@@ -181,9 +262,11 @@ user detail:
 
 | Phase | What runs | Max fix attempts | On failure after max |
 |---|---|---|---|
+| 0. Pre-gen | Playwright MCP snapshot → write selectors.yaml | 1 snapshot | Ask user — skip or retry navigation |
+| 0.5. Auth | Manual login in MCP browser → `browser_storage_state` → `specs/.auth/<role>.json` | 1 login | Ask user — retry login or fall back to `sungen makeauth` |
 | 1. Smoke | First 5 @critical/@high | 2 | Ask user — fundamentals broken |
 | 2. Priority | All @critical + @high | 2 | Report failures, continue to Phase 3 |
 | 3. Full | All tests | 1 | Report @low/@normal failures, continue |
 | 4. Regression | All tests | 0 | Report final results |
 
-**Total worst case: 5 fix attempts** (2+2+1), not unbounded loops.
+**Total worst case: 5 fix attempts** (2+2+1), not unbounded loops. Phases 0 and 0.5 don't count toward fix budget.

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

@@ -102,5 +102,27 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 | `[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.).
+
+### Types requiring YAML entry (no auto-infer)
+
+These types need explicit `selectors.yaml` entries:
+
+| Type | Reason |
+|------|--------|
+| `date-picker` | Custom component, needs testid or CSS |
+| `uploader` | File input, needs upload type selector |
+| `overlay` | No standard ARIA role, needs CSS/testid |
+| `frame` | Needs iframe selector |
+| `step` | Custom stepper component, needs testid |

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

@@ -1,9 +1,9 @@
 ---
 name: sungen-add-screen
-description: 'Add a new Sungen screen — scaffolds directories and delegates to /sungen-create-test for test case creation'
+description: 'Add a new Sungen screen — scaffolds directories, helps fill spec.md, and can auto-capture a live-page screenshot via Playwright MCP'
 argument-hint: '[screen-name] [url-path]'
 agent: 'agent'
-tools: [vscode, execute, read, agent, edit, search, web, browser, todo]
+tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']
 ---
 
 **Input**: Screen name and URL path (e.g., `/sungen-add-screen login /login`).
@@ -24,18 +24,27 @@ Run with #tool:terminal:
 sungen add --screen ${input:screen} --path ${input:path}
 ```
 
-### 2. Fill requirements (recommended)
+### 2. Fill spec.md
 
-Ask the user: "Would you like to fill in `requirements/spec.md` now? This helps generate higher quality test cases."
+Ask: *"Fill `spec.md` now?"* — offer **1) Yes, fill now (Recommended)** / **2) Skip, fill later**.
 
-- If yes → open `qa/screens/${input:screen}/requirements/spec.md` and help the user fill sections, fields, validation rules, business rules, and states.
-- If they have UI designs (screenshots, Figma exports, mockups) → suggest copying them to `requirements/ui/`.
-- If no → proceed to step 3.
+If yes → open `qa/screens/${input:screen}/requirements/spec.md` and help the user fill sections, fields, validation rules, business rules, and states. Especially prompt for the optional **Figma URL** and **Live URL** fields in Overview — those unlock auto-capture without re-asking next run.
 
-### 3. Next steps
+### 3. Capture visual source
+
+Ask the user to pick a visual source. Always offer all three so pre-launch projects work:
+
+- **1) Figma design** (Recommended for pre-launch) — invoke `sungen-capture-figma` skill
+- **2) Live page scan** (dev/staging is up) — invoke `sungen-capture-live` skill
+- **3) Skip** — user will drop images manually into `requirements/ui/` later, or rely on `/sungen-create-test` to prompt again
+
+Each capture skill writes outputs into `qa/screens/${input:screen}/requirements/ui/` and reports back. Do not inline capture logic here — delegate to the skill so behavior stays consistent with `/sungen-create-test`.
+
+If the user has additional UI designs (mockups, hand-drawn sketches), suggest copying them to `requirements/ui/` — `sungen-capture-local` will pick them up during `/sungen-create-test`.
+
+### 4. Next steps
 
 Tell the user what was created and offer next steps:
 
 - **`/sungen-create-test ${input:screen}`** — Create test cases from requirements/designs (Recommended)
-- **Fill `requirements/spec.md`** — Write screen specs first for better test quality
 - **Done for now** — I'll come back later

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

@@ -28,10 +28,12 @@ You are a **Senior QA Engineer**. You structure test cases by viewpoint categori
      - **2) Continue without it** — generate tests from spec and other sources only
    - Summarize what you found in requirements and present to the user.
 4. **Screen input** (supplements requirements, or is primary source if no requirements):
-   - Ask: "How should I get the screen design? **1) Figma design** (provide Figma URL — recommended), **2) UI images** (screenshots/mockups in `requirements/ui/`), or **3) Live page scan** (optional, via Playwright MCP)?"
-   - Recommend Figma or UI images first. Live page scan is optional — useful to verify specs vs actual UI or capture real data.
-   - If live page: `browser_navigate` → ONE `browser_snapshot`. If auth redirect → ask user to log in manually. Never use `browser_run_code` or `browser_evaluate` to inject cookies.
-   - If exploring, verify and supplement requirements — flag any discrepancies found.
+   - Ask the user to pick a visual source. Always offer all three so pre-launch projects work:
+     - **1) Figma design** (Recommended for pre-launch) — invoke `sungen-capture-figma` skill
+     - **2) UI images** (existing screenshots/mockups in `requirements/ui/`) — invoke `sungen-capture-local` skill
+     - **3) Live page scan** (dev/staging is up) — invoke `sungen-capture-live` skill
+   - Each capture skill writes outputs into `qa/screens/${input:screen}/requirements/ui/` and reports back. Do not inline capture logic here — delegate to the skill so behavior stays consistent.
+   - After the capture skill returns, cross-check its output against `spec.md` and flag any discrepancies before moving on.
 5. Identify screen sections → ask user which to focus on (per `sungen-tc-generation` skill). When requirements exist, use the "Requirements-Driven Generation" strategy. Present sections as a numbered list and let user pick.
 6. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills.
 7. Show summary and offer next steps:

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

@@ -0,0 +1,71 @@
+---
+name: delivery
+description: 'Export Gherkin scenarios + Playwright results to CSV test case file for QA delivery.'
+argument-hint: "[screen-name...] (omit for all screens)"
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+## Role
+
+You are a **QA Test Delivery Engineer**. Your job is to invoke the deterministic `sungen delivery` CLI that performs all parsing and CSV export. Your role is minimal — just run the CLI and help the user if pre-flight checks fail.
+
+## Parameters
+
+Parse **screens** from `$ARGUMENTS`:
+- If empty → CLI will process **all** screens in `qa/screens/`
+- If provided → pass them through to the CLI
+
+## Steps
+
+### 1. Invoke the CLI
+
+Run via Bash (single command, no extra parsing):
+
+```bash
+npx sungen delivery <screens>
+```
+
+- If no screen args → just run `npx sungen delivery`
+- If screen args → pass them as positional arguments
+
+The CLI handles:
+- Scope detection (all screens vs specific)
+- Pre-flight source checks with colorful output
+- Parsing `.feature`, `.spec.ts`, `test-data.yaml`, `test-results/results.json`
+- Generating CSV at `qa/deliverables/<screen>-testcases.csv`
+- Printing summary table
+
+### 2. Handle pre-flight failures (if CLI exits non-zero)
+
+If the CLI exits with blocking issues, it will have already printed a clear table showing exactly what's missing per screen.
+
+Use `AskUserQuestion` to offer next steps:
+
+**Options:**
+- **Fix missing sources** (Recommended) — Print the suggested commands from CLI output and stop. User will run those commands manually, then re-invoke `/sungen:delivery`.
+- **Continue with available screens** — Re-run as `npx sungen delivery <screens> --continue-on-missing` to skip screens with blocking issues.
+- **Cancel** — Exit.
+
+### 3. Show summary + offer next steps (on success)
+
+Forward the CLI's summary table to the user verbatim. Then use `AskUserQuestion`:
+
+- **Open a specific CSV** — Help user inspect one of the exported files with Read tool.
+- **Run tests to refresh results** — Suggest `/sungen:run-test <screen>` to update `test-results/results.json`, then re-run delivery.
+- **Export another screen** — User can run `/sungen:delivery <other-screen>`.
+- **Done** — Exit.
+
+## Important notes
+
+- **Do NOT parse files yourself** — the CLI is the source of truth for parsing logic. Your job is orchestration + user interaction.
+- **Do NOT modify feature/spec.ts/test-data files** — the delivery is read-only.
+- **The CLI already respects `@manual` tags, skips `@steps:` base scenarios, groups by Category 2, and generates UTF-8 BOM CSV for Excel compatibility with Vietnamese.**
+- **Pre-flight check is built into the CLI** — use `--skip-preflight` only in CI/automated pipelines where checks are done externally.
+
+## CLI Reference
+
+```
+sungen delivery [screens...]
+  [--skip-preflight]          Skip pre-flight checks (not recommended)
+  [--continue-on-missing]     Skip screens with blocking misses
+```

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

@@ -1,43 +1,68 @@
 ---
-name: sungen-run-test
-description: 'Compile and run Playwright tests — auto-fixes selectors on failure. Uses sungen-selector-fix, sungen-selector-keys, and sungen-error-mapping skills.'
-argument-hint: '[screen-name]'
-agent: 'agent'
-tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']
+name: run-test
+description: 'Generate selectors + auth state via Playwright MCP, compile, and run Playwright tests — auto-fixes selectors on failure'
+argument-hint: [screen-name]
+allowed-tools: Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_wait_for, mcp__playwright__browser_evaluate, mcp__playwright__browser_run_code, mcp__playwright__browser_storage_state, mcp__playwright__browser_set_storage_state
 ---
 
-**Input**: Screen name (e.g., `/sungen-run-test admin-users`).
-
 ## Role
 
 You are a **Senior Developer**. Use `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills.
 
 ## Parameters
 
-- **screen** — ${input:screen:screen name (e.g., login, dashboard)}
+Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 
-## Compile
+## Pre-run (phased — per `sungen-selector-fix` skill)
 
-1. Verify `qa/screens/${input:screen}/` has `.feature` + `test-data.yaml`
-2. Ensure `selectors.yaml` has page selector. If missing, ask user for URL path
-3. `sungen generate --screen ${input:screen}`
+1. Verify `qa/screens/<screen>/` 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, run Phase 0 from `sungen-selector-fix` — confirm with user, `browser_navigate` → one `browser_snapshot` → merge YAML entries.
+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>`.
 
 ## Run & Fix (phased — per `sungen-selector-fix` skill)
 
-4. **Phase 1 — Smoke Check**: Run first 5 `@critical`/`@high` scenarios only. If failures → diagnose, fix fundamentals (page selector, auth, base @steps), re-run. Max 2 attempts. If still broken → ask user.
-5. **Phase 2 — Priority Wave**: Run all `@critical` + `@high` scenarios. Fix only failures from this wave. Max 2 attempts. Shared selectors fixed here cascade to later phases.
-6. **Phase 3 — Full Run**: Run all tests. Fix only **new** failures (elements unique to `@normal`/`@low`). Max 1 attempt. Don't loop on low-priority failures.
-7. **Phase 4 — Regression**: One final full run. Report results. No more fix loops.
+5. **Phase 1 — Smoke Check**: Run first 5 `@critical`/`@high` scenarios only. If failures → diagnose, fix fundamentals (page selector, auth, base @steps), re-run. Max 2 attempts. If still broken → ask user.
+6. **Phase 2 — Priority Wave**: Run all `@critical` + `@high` scenarios. Fix only failures from this wave. Max 2 attempts. Shared selectors fixed here cascade to later phases.
+7. **Phase 3 — Full Run**: Run all tests. Fix only **new** failures (elements unique to `@normal`/`@low`). Max 1 attempt. Don't loop on low-priority failures.
+8. **Phase 4 — Regression**: One final full run. Report results. No more fix loops.
+
+## 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:
+
+```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
+```
+
+Output: `specs/generated/<screen>/<screen>-test-result.json`
+
+**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
+
+# ❌ 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
+```
+
+If you want to filter scenarios, use `-g "<pattern>"` instead of a reporter override.
+
+`sungen delivery` reads the per-screen file first, falls back to the global `test-results/results.json` if missing.
 
 ## Next steps
 
-After showing results, offer next steps:
+After showing results, use `AskUserQuestion` to offer next steps:
 
 If all tests **passed**:
-- **`/sungen-create-test ${input:screen}`** — Add more test cases (Recommended)
+- **`/sungen:create-test <screen>`** — Add more test cases (Recommended)
 - **Done** — All tests passed, I'm finished
 
 If tests **failed** (after retries):
-- **`/sungen-run-test ${input:screen}`** — Re-run after manual fixes
-- **`/sungen-create-test ${input:screen}`** — Revise test cases
+- **`/sungen:run-test <screen>`** — Re-run after manual fixes
+- **`/sungen:create-test <screen>`** — Revise test cases
 - **Done for now** — I'll fix manually later

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

@@ -15,8 +15,12 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-viewpoint` | 10 UI patterns x 4 viewpoints — coverage checklists |
 | `sungen-selector-keys` | YAML key generation from `[Reference]` names, suffixes, lookup priority |
 | `sungen-selector-fix` | Selector generation from live page, auto-fix strategy |
+| `sungen-delivery` | Export Gherkin + Playwright results → CSV test case deliverable |
+| `sungen-capture-figma` | Fetch design context + PNG from a Figma frame URL via Figma Dev Mode MCP |
+| `sungen-capture-local` | Load existing UI assets (screenshots, mockups, Figma exports) from `requirements/ui/` |
+| `sungen-capture-live` | Capture a live running page via Playwright MCP (snapshot + screenshot) |
 
-## Workflow (4 AI commands)
+## Workflow (5 AI commands)
 
 | Command | What it does |
 |---|---|
@@ -24,8 +28,9 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `/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-delivery [name...]` | Export test cases → CSV for QA delivery (all screens if no arg) |
 
-**Order:** add-screen → create-test → review → run-test.
+**Order:** add-screen → create-test → review → run-test → delivery.
 
 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.
 
@@ -39,6 +44,9 @@ qa/screens/<screen-name>/
 └── requirements/
     ├── spec.md                    # Screen specification (primary source)
     └── ui/                        # Screenshots, mockups
+
+qa/deliverables/<screen>-testcases.csv  # Exported test cases (from /sungen-delivery)
+qa/deliverables/<screen>-testcases.xlsx # Styled workbook for client hand-off
 ```
 
 ## CLI Commands
@@ -48,4 +56,6 @@ sungen add --screen <name> --path <url-path>               # Scaffold screen dir
 sungen add --screen <name> --path <path> --feature <name>   # Scaffold with sub-feature
 sungen generate --screen <name>                              # Compile .feature → .spec.ts
 sungen generate --all                                        # Compile all screens
+sungen delivery                                              # Export all screens → CSV + XLSX
+sungen delivery <screen>                                     # Export a single screen
 ```