@sun-asterisk/sungen 2.4.3 → 2.4.6

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

@@ -0,0 +1,142 @@
+---
+name: sungen-capture-figma
+description: 'Fetch design context + PNG from a Figma frame URL via Figma Dev Mode MCP. Auto-loaded by create-test when user picks Figma as the visual source.'
+user-invocable: false
+---
+
+## Purpose
+
+Pull **structured design data** (layout, typography, colors, component tree, design tokens) and a **PNG screenshot** from a Figma frame URL, so `sungen-tc-generation` can author Gherkin + test-data before a live domain exists.
+
+Use this when the project is pre-launch, or when Figma is the source of truth and the live build lags the design.
+
+---
+
+## Prerequisites
+
+- **Figma MCP server** (`https://mcp.figma.com/mcp`, HTTP transport) connected in `.vscode/mcp.json` — `sungen init` scaffolds this automatically. On first use, VS Code / Copilot opens a browser for Figma OAuth. Official tools: `get_design_context`, `get_variable_defs`, `get_screenshot`.
+- Figma account signed in with access to the file. **Dev/Full seats** get per-minute rate limits; **Starter/View seats** get monthly tool-call limits.
+- A Figma URL with both **fileKey** and **nodeId** in it.
+
+If the MCP is not connected, **do not fail silently** — tell the user:
+> "Figma MCP not detected. Run `sungen init` to scaffold the config, or manually add `figma` with `url: https://mcp.figma.com/mcp` to `.vscode/mcp.json`. Then sign in when VS Code prompts."
+
+Then stop.
+
+---
+
+## Steps
+
+### 1. Resolve Figma URL
+
+Prefer in this order:
+
+1. `Figma URL` field in `qa/screens/<screen>/requirements/spec.md` (Overview section)
+2. If empty or missing → ask the user: *"Paste the Figma frame URL"*
+
+Accept any of these URL shapes:
+
+```
+https://www.figma.com/file/<fileKey>/<title>?node-id=<nodeId>
+https://www.figma.com/design/<fileKey>/<title>?node-id=<nodeId>
+https://www.figma.com/proto/<fileKey>/<title>?node-id=<nodeId>
+```
+
+Parse:
+- `fileKey` = the segment after `/file/`, `/design/`, or `/proto/`
+- `nodeId` = the `node-id` query param (may use `-` or `:` — pass through as-is; MCP accepts both)
+
+If `node-id` is missing, ask the user to select a frame in Figma and copy the **frame URL** specifically (not the file root URL).
+
+### 2. Fetch design context
+
+Call **both** in parallel:
+
+```
+get_design_context({ fileKey, nodeId })
+get_variable_defs({ fileKey, nodeId })
+```
+
+`get_design_context` returns layout, typography, color values, component structure, spacing.
+`get_variable_defs` returns named design tokens (color/spacing/typography variables).
+
+### 3. Fetch screenshot
+
+```
+get_screenshot({ fileKey, nodeId })
+```
+
+Save the returned PNG to:
+
+```
+qa/screens/<screen>/requirements/ui/figma-<sanitized-nodeId>.png
+```
+
+Sanitize `nodeId` for filesystem: replace `:` and `-` with `_`. Example: `42-15` → `figma-42_15.png`.
+
+### 4. Write metadata dump
+
+Combine the design context + variables into a Markdown summary at:
+
+```
+qa/screens/<screen>/requirements/ui/figma-meta.md
+```
+
+Format:
+
+```markdown
+# Figma Capture — <nodeId>
+
+**Source:** <full Figma URL>
+**Captured:** <ISO date>
+
+## Components
+<hierarchical list of component names + variants from get_design_context>
+
+## Typography
+<font families, sizes, weights, line heights>
+
+## Colors
+<color tokens + raw hex values>
+
+## Spacing & Layout
+<spacing tokens, auto-layout specs>
+
+## Text Content
+<visible text strings from the frame — used by tc-generation to populate test-data>
+```
+
+This file is consumed by `sungen-tc-generation` as a secondary source alongside `spec.md`.
+
+### 5. Report back
+
+Output a short summary to the user:
+
+> Captured Figma frame `<nodeId>`:
+> - Components: N
+> - Text strings: M
+> - Design tokens: K
+> - Screenshot: `qa/screens/<screen>/requirements/ui/figma-<nodeId>.png`
+> - Metadata: `requirements/ui/figma-meta.md`
+
+Then hand back to the calling command.
+
+---
+
+## Error handling
+
+| Error | Action |
+|---|---|
+| MCP tool not available | Print setup instructions, stop, do not fall back silently |
+| `fileKey` missing from URL | Ask user to paste a valid frame URL |
+| `nodeId` missing from URL | Ask user to right-click a frame in Figma → *Copy link to selection* |
+| `get_design_context` 403 | Ask user to check Dev Mode seat on that file |
+| `get_screenshot` returns no image | Continue with metadata only; warn user no PNG was captured |
+
+---
+
+## What this skill does NOT do
+
+- Does not generate Gherkin (that's `sungen-tc-generation`)
+- Does not write `selectors.yaml` (that's `/sungen-run-test`)
+- Does not validate the design against live UI (future skill: `sungen-capture-live` can be run afterwards for cross-check)

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

@@ -0,0 +1,100 @@
+---
+name: sungen-capture-live
+description: 'Capture a live running page via Playwright MCP — snapshot + screenshot for visual context. Auto-loaded by create-test when user picks Live page scan.'
+user-invocable: false
+---
+
+## Purpose
+
+Navigate a running application, take **one accessibility snapshot** and **one screenshot**, and save them as visual context for test generation. Use when the app is live (dev, staging, or production with read-only access) and you want the tests grounded in the actual rendered UI.
+
+This skill handles auth gracefully: if the page redirects to login, it asks the user to sign in manually rather than injecting cookies.
+
+---
+
+## Prerequisites
+
+- Playwright MCP connected.
+- Dev/staging server reachable (or a public URL).
+- `playwright.config.ts` exists at the project root (for `baseURL` fallback).
+
+---
+
+## Steps
+
+### 1. Resolve target URL
+
+Resolve in this order:
+
+1. `Live URL` field in `qa/screens/<screen>/requirements/spec.md` (Overview section)
+2. `baseURL` from `playwright.config.ts` + `URL Path` from `spec.md`
+3. If neither works → ask the user: *"Paste the full URL for the page to scan"*
+
+### 2. Navigate
+
+`browser_navigate` to the resolved URL.
+
+### 3. Handle auth redirect
+
+If the page redirects to a login route (URL contains `/login`, `/signin`, `/auth`, or the page title/content indicates a login screen):
+
+1. Tell the user which login URL they landed on.
+2. Ask the user:
+   - **1) I'll log in manually** — wait for user confirmation, then re-navigate to the target URL
+   - **2) Skip live scan** — tell caller to invoke `sungen-capture-local` instead
+   - **3) Cancel**
+3. **Never** inject cookies or localStorage via `browser_evaluate` or `browser_run_code`. Auth belongs to the user.
+
+### 4. Snapshot
+
+Take **ONE** `browser_snapshot`. This accessibility tree is the primary AI context — it contains roles, names, text, and structure that the tc-generation skill uses to identify sections and fields.
+
+### 5. Screenshot (optional but recommended)
+
+Take **ONE** `browser_take_screenshot` with `fullPage: true`. Save to:
+
+```
+qa/screens/<screen>/requirements/ui/live-<timestamp>.png
+```
+
+Where `<timestamp>` is `YYYYMMDD-HHMM` in local time (e.g. `live-20260421-1430.png`).
+
+This gives users a visual record they can reference later without re-scanning.
+
+### 6. Detect discrepancies vs spec
+
+If `spec.md` exists, briefly cross-check the snapshot against spec sections:
+
+- Fields listed in spec but not in snapshot → flag as *missing in UI*
+- Elements visible in snapshot but not in spec → flag as *missing in spec*
+
+Report findings but **do not** auto-edit `spec.md` — let the user decide.
+
+### 7. Report back
+
+> Captured live page `<URL>`:
+> - Snapshot: <N> interactive elements detected
+> - Screenshot: `requirements/ui/live-<timestamp>.png`
+> - Discrepancies vs spec: <count, or "none">
+
+Hand back to the calling command.
+
+---
+
+## What this skill does NOT do
+
+- Does not run tests
+- Does not generate `selectors.yaml` (that's `/sungen-run-test`)
+- Does not inject auth state (user logs in manually)
+- Does not crawl — scans **exactly one** page per invocation
+- Does not generate Gherkin — that's `sungen-tc-generation`
+
+---
+
+## Relationship to other capture skills
+
+- `sungen-capture-figma` — design source of truth (pre-launch)
+- `sungen-capture-local` — any image the user dropped in `requirements/ui/`
+- `sungen-capture-live` — this skill, verifies/supplements against the running app
+
+All three write to `requirements/ui/` and report back to the caller. They are mutually exclusive per create-test run, but a user can run create-test multiple times with different sources to layer context.

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

@@ -0,0 +1,73 @@
+---
+name: sungen-capture-local
+description: 'Load existing UI assets (screenshots, Figma exports, hand-drawn mockups) from requirements/ui/. Auto-loaded by create-test when user picks UI images as the visual source.'
+user-invocable: false
+---
+
+## Purpose
+
+Use **pre-existing images** in `qa/screens/<screen>/requirements/ui/` as visual context for test generation. No network, no MCP, no live site required — works for any design tool (Figma export, Sketch, Penpot, Zeplin, hand-drawn, screenshots of a staging env).
+
+This is the **baseline fallback**: if live domain is down and Figma MCP isn't configured, this always works as long as the user drops images in the folder.
+
+---
+
+## Steps
+
+### 1. List available images
+
+Glob `qa/screens/<screen>/requirements/ui/*.{png,jpg,jpeg,webp,gif}` and report count + filenames.
+
+Filter out metadata files (e.g. `figma-meta.md` written by `sungen-capture-figma`) — those are read by `tc-generation` separately, not treated as images here.
+
+### 2. Handle empty folder
+
+If no images found:
+
+1. Tell the user the folder is empty, with the full path so they can navigate there in their file manager.
+2. Ask the user to pick:
+   - **1) I'll drop images now** — wait for user to confirm, then re-glob
+   - **2) Switch to Figma URL** — tell caller to invoke `sungen-capture-figma` instead
+   - **3) Switch to live page scan** — tell caller to invoke `sungen-capture-live` instead
+   - **4) Cancel** — abort create-test
+3. If user picks "drop images now", wait for their confirmation message (e.g. "done") then re-run step 1.
+
+### 3. Read images for context
+
+Use the `read` tool on each image file — the assistant can read PNG/JPG/WebP directly as visual context.
+
+For large sets (>10 images), ask the user which are primary and which are states/variants, to avoid loading too much visual context at once.
+
+### 4. Summarize
+
+Output a short summary:
+
+> Loaded N image(s) from `qa/screens/<screen>/requirements/ui/`:
+> - `<filename-1>` — <one-line description of what's visible>
+> - `<filename-2>` — <one-line description>
+> ...
+
+Hand back to the calling command.
+
+---
+
+## File naming hints for users
+
+When this skill reports back, nudge users toward consistent filenames so future runs are self-documenting:
+
+- `<section>-default.png` — baseline state of a section
+- `<section>-error.png` — error state
+- `<section>-loading.png` — loading state
+- `<section>-empty.png` — empty state
+- `full-page.png` / `viewport.png` — whole screen (auto-generated by `sungen add --capture`)
+
+Don't enforce — just suggest if filenames are ambiguous.
+
+---
+
+## What this skill does NOT do
+
+- Does not download images from external URLs
+- Does not generate images (no AI image generation)
+- Does not modify existing images (no crop/resize)
+- Does not generate Gherkin — that's `sungen-tc-generation`

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-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/github-skill-sungen-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/github-skill-sungen-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**: *"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 → **ask the user to log in manually in the MCP browser**, wait for confirmation, then continue. Never use `sungen makeauth`. Never inject cookies via `browser_evaluate`.
+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 → confirm overwrite with the user (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/github-skill-sungen-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/playwright.config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playwright.config.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/playwright.config.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAKH;;GAEG;;AACH,wBAoEG"}
+{"version":3,"file":"playwright.config.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/playwright.config.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAKH;;GAEG;;AACH,wBAyEG"}

package/dist/orchestrator/templates/playwright.config.js

@@ -24,7 +24,12 @@ exports.default = (0, test_1.defineConfig)({
     /* Global timeout per test */
     timeout: 10000,
     /* Reporter to use. See https://playwright.dev/docs/test-reporters */
-    reporter: 'html',
+    /* JSON reporter is required by `sungen delivery` to populate test result columns in the exported CSV. */
+    /* Output file path is controlled by PLAYWRIGHT_JSON_OUTPUT_NAME env var for per-screen isolation. */
+    reporter: [
+        ['html'],
+        ['json', { outputFile: process.env.PLAYWRIGHT_JSON_OUTPUT_NAME || 'test-results/results.json' }],
+    ],
     /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
     use: {
         /* Base URL to use in actions like `await page.goto('')`. */

package/dist/orchestrator/templates/playwright.config.js.map

@@ -1 +1 @@
-{"version":3,"file":"playwright.config.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/playwright.config.ts"],"names":[],"mappings":";;AAAA,2CAAyD;AAEzD;;;GAGG;AACH,+BAA+B;AAC/B,2BAA2B;AAC3B,4DAA4D;AAE5D;;GAEG;AACH,kBAAe,IAAA,mBAAY,EAAC;IAC1B,OAAO,EAAE,mBAAmB;IAC5B,oCAAoC;IACpC,aAAa,EAAE,IAAI;IACnB,iFAAiF;IACjF,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;IAC5B,sBAAsB;IACtB,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,6BAA6B;IAC7B,OAAO,EAAE,KAAM;IACf,qEAAqE;IACrE,QAAQ,EAAE,MAAM;IAChB,wGAAwG;IACxG,GAAG,EAAE;QACH,4DAA4D;QAC5D,OAAO,EAAE,qBAAqB;QAE9B,+FAA+F;QAC/F,KAAK,EAAE,gBAAgB;KACxB;IAED,2CAA2C;IAC3C,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,UAAU;YAChB,GAAG,EAAE,EAAE,GAAG,cAAO,CAAC,gBAAgB,CAAC,EAAE;SACtC;QAED;;;;;;;;;;;;;;;;;;;;;4CAqBoC;QACpC,IAAI;QACJ,4BAA4B;QAC5B,4DAA4D;QAC5D,KAAK;QACL,IAAI;QACJ,2BAA2B;QAC3B,8DAA8D;QAC9D,KAAK;KACN;IAED,yDAAyD;IACzD,eAAe;IACf,8BAA8B;IAC9B,kCAAkC;IAClC,0CAA0C;IAC1C,KAAK;CACN,CAAC,CAAC"}
+{"version":3,"file":"playwright.config.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/playwright.config.ts"],"names":[],"mappings":";;AAAA,2CAAyD;AAEzD;;;GAGG;AACH,+BAA+B;AAC/B,2BAA2B;AAC3B,4DAA4D;AAE5D;;GAEG;AACH,kBAAe,IAAA,mBAAY,EAAC;IAC1B,OAAO,EAAE,mBAAmB;IAC5B,oCAAoC;IACpC,aAAa,EAAE,IAAI;IACnB,iFAAiF;IACjF,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;IAC5B,sBAAsB;IACtB,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,6BAA6B;IAC7B,OAAO,EAAE,KAAM;IACf,qEAAqE;IACrE,yGAAyG;IACzG,qGAAqG;IACrG,QAAQ,EAAE;QACR,CAAC,MAAM,CAAC;QACR,CAAC,MAAM,EAAE,EAAE,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,2BAA2B,IAAI,2BAA2B,EAAE,CAAC;KACjG;IACD,wGAAwG;IACxG,GAAG,EAAE;QACH,4DAA4D;QAC5D,OAAO,EAAE,qBAAqB;QAE9B,+FAA+F;QAC/F,KAAK,EAAE,gBAAgB;KACxB;IAED,2CAA2C;IAC3C,QAAQ,EAAE;QACR;YACE,IAAI,EAAE,UAAU;YAChB,GAAG,EAAE,EAAE,GAAG,cAAO,CAAC,gBAAgB,CAAC,EAAE;SACtC;QAED;;;;;;;;;;;;;;;;;;;;;4CAqBoC;QACpC,IAAI;QACJ,4BAA4B;QAC5B,4DAA4D;QAC5D,KAAK;QACL,IAAI;QACJ,2BAA2B;QAC3B,8DAA8D;QAC9D,KAAK;KACN;IAED,yDAAyD;IACzD,eAAe;IACf,8BAA8B;IAC9B,kCAAkC;IAClC,0CAA0C;IAC1C,KAAK;CACN,CAAC,CAAC"}

package/dist/orchestrator/templates/playwright.config.ts

@@ -24,7 +24,12 @@ export default defineConfig({
   /* Global timeout per test */
   timeout: 10_000,
   /* Reporter to use. See https://playwright.dev/docs/test-reporters */
-  reporter: 'html',
+  /* JSON reporter is required by `sungen delivery` to populate test result columns in the exported CSV. */
+  /* Output file path is controlled by PLAYWRIGHT_JSON_OUTPUT_NAME env var for per-screen isolation. */
+  reporter: [
+    ['html'],
+    ['json', { outputFile: process.env.PLAYWRIGHT_JSON_OUTPUT_NAME || 'test-results/results.json' }],
+  ],
   /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
   use: {
     /* Base URL to use in actions like `await page.goto('')`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "2.4.3",
+  "version": "2.4.6",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,6 +40,7 @@
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",
+    "exceljs": "^4.4.0",
     "fast-glob": "^3.3.3",
     "glob": "^13.0.0",
     "handlebars": "^4.7.8",

package/src/cli/commands/add.ts

@@ -3,19 +3,26 @@ import { Command } from 'commander';
 export function registerAddCommand(program: Command): void {
   program
     .command('add')
-    .description('Add screen or feature definition with scaffolded files. Auto-captures screenshots when --path is provided.')
+    .description('Add screen or feature definition with scaffolded files. Use --capture to auto-capture a live-page screenshot.')
     .requiredOption('--screen <name>', 'Screen name')
-    .option('-p, --path <path>', 'Screen route path (e.g. /awards). Also triggers auto-screenshot capture.')
+    .option('-p, --path <path>', 'Screen route path (e.g. /awards)')
+    .option('-c, --capture', 'Auto-capture a live-page screenshot to requirements/ui/ (requires --path)')
     .option('-f, --feature <name>', 'Add additional feature file to existing screen')
     .option('-d, --description <text>', 'Screen description')
     .action(async (options) => {
       try {
+        if (options.capture && !options.path) {
+          console.error('Error: --capture requires --path to be set');
+          process.exit(1);
+        }
+
         const { ScreenManager } = require('../../orchestrator/screen-manager');
         const manager = new ScreenManager();
 
         await manager.addScreen({
           name: options.screen,
           path: options.path,
+          capture: options.capture,
           feature: options.feature,
           description: options.description,
         });