@sun-asterisk/sungen 2.4.2 → 2.4.3

package/dist/orchestrator/templates/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "types": ["node", "@playwright/test"],
+    "strict": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "outDir": "./dist",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["specs/**/*.ts", "playwright.config.ts"],
+  "exclude": ["node_modules"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "2.4.2",
+  "version": "2.4.3",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/cli/commands/add.ts

@@ -3,9 +3,9 @@ import { Command } from 'commander';
 export function registerAddCommand(program: Command): void {
   program
     .command('add')
-    .description('Add screen or feature definition with scaffolded files')
+    .description('Add screen or feature definition with scaffolded files. Auto-captures screenshots when --path is provided.')
     .requiredOption('--screen <name>', 'Screen name')
-    .option('-p, --path <path>', 'Screen route path (e.g. /awards)')
+    .option('-p, --path <path>', 'Screen route path (e.g. /awards). Also triggers auto-screenshot capture.')
     .option('-f, --feature <name>', 'Add additional feature file to existing screen')
     .option('-d, --description <text>', 'Screen description')
     .action(async (options) => {

package/src/cli/index.ts

@@ -17,7 +17,7 @@ async function main() {
   program
     .name('sungen')
     .description('Deterministic E2E Test Compiler — Gherkin + Selectors → Playwright')
-    .version('2.4.2');
+    .version('2.4.3');
 
   // Global options
   program

package/src/generators/test-generator/code-generator.ts

@@ -4,6 +4,29 @@ import { ParsedFeature, ParsedScenario, ParsedStep } from '../gherkin-parser';
 import { StepMapper } from './step-mapper';
 import { TestGeneratorAdapter, adapterRegistry } from './adapters';
 
+/**
+ * Filter base scenario steps for @extend: only keep Given→When steps.
+ * Skips Then and any And/But that follow Then (since And/But inherit
+ * from the preceding primary keyword).
+ */
+function filterBaseStepsForExtend(steps: ParsedStep[]): ParsedStep[] {
+  const result: ParsedStep[] = [];
+  let lastPrimaryKeyword = 'Given';
+
+  for (const step of steps) {
+    const kw = step.keyword.trim();
+    if (kw === 'Given' || kw === 'When' || kw === 'Then') {
+      lastPrimaryKeyword = kw;
+    }
+    // Skip Then and any And/But that follow Then
+    if (lastPrimaryKeyword === 'Then') {
+      continue;
+    }
+    result.push(step);
+  }
+  return result;
+}
+
 /**
  * Extract auth role from tags
  * @auth:admin → 'admin'
@@ -345,8 +368,9 @@ export class CodeGenerator {
     if (scenario.extendsName) {
       const baseScenario = this.stepsRegistry.get(scenario.extendsName);
       if (baseScenario) {
-        // Prepend base steps inline — fully self-contained, no beforeEach
-        stepsToMap = [...baseScenario.steps, ...scenario.steps];
+        // Prepend base steps inline — only Given→When (skip Then per @extend contract)
+        const filteredBaseSteps = filterBaseStepsForExtend(baseScenario.steps);
+        stepsToMap = [...filteredBaseSteps, ...scenario.steps];
         // Auth precedence: extending @auth > base @auth > feature @auth
         authFeatureTags = [...baseScenario.tags, ...featureTags];
       } else {
@@ -370,9 +394,10 @@ export class CodeGenerator {
     if (scenario.extendsName && this.stepsRegistry.has(scenario.extendsName)) {
       const baseScenario = this.stepsRegistry.get(scenario.extendsName)!;
 
-      // Section header: base steps
+      // Section header: base steps (only Given→When, skip Then per @extend contract)
+      const filteredSteps = filterBaseStepsForExtend(baseScenario.steps);
       steps.push({ code: `    // [from @steps:${scenario.extendsName}]` });
-      for (const step of baseScenario.steps) {
+      for (const step of filteredSteps) {
         const mapped = await Promise.resolve(this.stepMapper.mapStep(step));
         steps.push({ comment: mapped.comment, code: this.indentCode(mapped.code, 4) });
       }

package/src/orchestrator/ai-rules-updater.ts

@@ -29,6 +29,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['claude-skill-selector-keys.md', '.claude/skills/sungen-selector-keys/SKILL.md'],
   ['claude-skill-error-mapping.md', '.claude/skills/sungen-error-mapping/SKILL.md'],
   ['claude-skill-tc-generation.md', '.claude/skills/sungen-tc-generation/SKILL.md'],
+  ['claude-skill-test-design-techniques.md', '.claude/skills/sungen-test-design-techniques/SKILL.md'],
   ['claude-skill-selector-fix.md', '.claude/skills/sungen-selector-fix/SKILL.md'],
   ['claude-skill-tc-review.md', '.claude/skills/sungen-tc-review/SKILL.md'],
   ['claude-skill-viewpoint.md', '.claude/skills/sungen-viewpoint/SKILL.md'],
@@ -38,6 +39,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['github-skill-sungen-selector-keys.md', '.github/skills/sungen-selector-keys/SKILL.md'],
   ['github-skill-sungen-error-mapping.md', '.github/skills/sungen-error-mapping/SKILL.md'],
   ['github-skill-sungen-tc-generation.md', '.github/skills/sungen-tc-generation/SKILL.md'],
+  ['github-skill-sungen-test-design-techniques.md', '.github/skills/sungen-test-design-techniques/SKILL.md'],
   ['github-skill-sungen-selector-fix.md', '.github/skills/sungen-selector-fix/SKILL.md'],
   ['github-skill-sungen-tc-review.md', '.github/skills/sungen-tc-review/SKILL.md'],
   ['github-skill-sungen-viewpoint.md', '.github/skills/sungen-viewpoint/SKILL.md'],

package/src/orchestrator/project-initializer.ts

@@ -44,6 +44,9 @@ export class ProjectInitializer {
     // Create playwright config if doesn't exist
     this.createPlaywrightConfig();
 
+    // Create tsconfig.json if doesn't exist
+    this.createTsConfig();
+
     // Create specs/base.ts for shared context
     this.createSpecsBase();
 
@@ -115,6 +118,22 @@ export class ProjectInitializer {
     this.createdItems.push('playwright.config.ts');
   }
 
+  /**
+   * Create TypeScript configuration
+   */
+  private createTsConfig(): void {
+    const configPath = path.join(this.cwd, 'tsconfig.json');
+
+    if (fs.existsSync(configPath)) {
+      this.skippedItems.push('tsconfig.json');
+      return;
+    }
+
+    const content = this.readTemplate('tsconfig.json');
+    fs.writeFileSync(configPath, content, 'utf-8');
+    this.createdItems.push('tsconfig.json');
+  }
+
   /**
    * Update .gitignore with Sungen-specific entries
    */
@@ -273,6 +292,7 @@ export class ProjectInitializer {
       ['claude-skill-selector-keys.md', '.claude/skills/sungen-selector-keys/SKILL.md'],
       ['claude-skill-error-mapping.md', '.claude/skills/sungen-error-mapping/SKILL.md'],
       ['claude-skill-tc-generation.md', '.claude/skills/sungen-tc-generation/SKILL.md'],
+      ['claude-skill-test-design-techniques.md', '.claude/skills/sungen-test-design-techniques/SKILL.md'],
       ['claude-skill-selector-fix.md', '.claude/skills/sungen-selector-fix/SKILL.md'],
       ['claude-skill-tc-review.md', '.claude/skills/sungen-tc-review/SKILL.md'],
       ['claude-skill-viewpoint.md', '.claude/skills/sungen-viewpoint/SKILL.md'],
@@ -282,6 +302,7 @@ export class ProjectInitializer {
       ['github-skill-sungen-selector-keys.md', '.github/skills/sungen-selector-keys/SKILL.md'],
       ['github-skill-sungen-error-mapping.md', '.github/skills/sungen-error-mapping/SKILL.md'],
       ['github-skill-sungen-tc-generation.md', '.github/skills/sungen-tc-generation/SKILL.md'],
+      ['github-skill-sungen-test-design-techniques.md', '.github/skills/sungen-test-design-techniques/SKILL.md'],
       ['github-skill-sungen-selector-fix.md', '.github/skills/sungen-selector-fix/SKILL.md'],
       ['github-skill-sungen-tc-review.md', '.github/skills/sungen-tc-review/SKILL.md'],
       ['github-skill-sungen-viewpoint.md', '.github/skills/sungen-viewpoint/SKILL.md'],
@@ -363,9 +384,9 @@ export class ProjectInitializer {
       // package.json just created, proceed with install
     }
 
-    // Install Playwright
-    console.log('📦 Installing @playwright/test...\n');
-    execSync('npm install -D @playwright/test', execOpts);
+    // Install Playwright and TypeScript types
+    console.log('📦 Installing @playwright/test and @types/node...\n');
+    execSync('npm install -D @playwright/test @types/node', execOpts);
 
     console.log('\n🎭 Installing Playwright browsers...\n');
     execSync('npx playwright install', execOpts);

package/src/orchestrator/screen-manager.ts

@@ -5,6 +5,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { chromium } from '@playwright/test';
 
 export interface ScreenOptions {
   name: string;
@@ -120,6 +121,76 @@ export class ScreenManager {
       fs.writeFileSync(specPath, this.generateSpecTemplate(options, screenName), 'utf-8');
     }
 
+    // Generate requirements test-viewpoint.md (only on first screen creation)
+    const viewpointPath = path.join(requirementsDir, 'test-viewpoint.md');
+    if (!fs.existsSync(viewpointPath)) {
+      fs.writeFileSync(viewpointPath, [
+        `# ${options.name} — Test Viewpoints`,
+        '',
+        '## Edge Cases',
+        '',
+        '<!-- Sample — replace with actual edge cases for this screen:',
+        '- Paste emoji into text fields (e.g., 🎉👋) — should accept or sanitize?',
+        '- Input 10,000+ characters into free text — truncate or reject?',
+        '- Double-click Submit rapidly — should only create 1 record',
+        '- Browser back button after successful submit — should not re-submit',
+        '-->',
+        '',
+        '## Known Issues',
+        '',
+        '<!-- Sample — replace with actual known issues:',
+        '- [BUG-001] Date picker does not work on Safari < 16',
+        '- [BUG-002] File upload silently fails for files > 20MB (no error shown)',
+        '- Search does not handle Vietnamese accents correctly ("Nguyên" ≠ "Nguyen")',
+        '-->',
+        '',
+        '## Design Decisions',
+        '',
+        '<!-- Sample — replace with actual design decisions:',
+        '- Show all validation errors at once (not one at a time) — per UX review',
+        '- Cancel button resets form completely (no draft saving)',
+        '- Anonymous mode hides sender name but keeps department visible',
+        '-->',
+        '',
+        '## UI Patterns Identified',
+        '',
+        '<!-- Check applicable patterns for this screen (from sungen-viewpoint skill):',
+        '',
+        '| # | Pattern | Applicable? | Notes |',
+        '|---|---------|-------------|-------|',
+        '| 1 | Form & Inputs | ☐ | |',
+        '| 2 | Data Table | ☐ | |',
+        '| 3 | Create / Add | ☐ | |',
+        '| 4 | Update / Edit | ☐ | |',
+        '| 5 | Delete | ☐ | |',
+        '| 6 | Search | ☐ | |',
+        '| 7 | Filter | ☐ | |',
+        '| 8 | Pagination | ☐ | |',
+        '| 9 | Modal / Dialog | ☐ | |',
+        '| 10 | List / Card | ☐ | |',
+        '-->',
+        '',
+        '## Priority Viewpoints',
+        '',
+        '<!-- Rate importance for this screen (High / Medium / Low / Skip):',
+        '',
+        '| VP | Priority | Reason |',
+        '|---|----------|--------|',
+        '| VP-UI | High | Complex form with many states |',
+        '| VP-VAL | High | 14 validation rules from spec |',
+        '| VP-LOGIC | Medium | Standard CRUD, no complex business rules |',
+        '| VP-SEC | Low | Internal tool, basic auth only |',
+        '-->',
+        '',
+      ].join('\n'), 'utf-8');
+    }
+
+    // Auto-screenshot: capture page if --path is provided
+    // Use filename (not screenName) so each feature gets its own screenshots
+    if (options.path) {
+      await this.captureScreenshot(options.path, requirementsUiDir, filename);
+    }
+
     // Display success
     console.log(`Created files:`);
     console.log(`  ${path.relative(this.cwd, featurePath)}`);
@@ -127,6 +198,7 @@ export class ScreenManager {
     console.log(`  ${path.relative(this.cwd, testDataPath)}`);
     if (isFirstFile) {
       console.log(`  ${path.relative(this.cwd, specPath)}`);
+      console.log(`  ${path.relative(this.cwd, viewpointPath)}`);
       console.log(`  ${path.relative(this.cwd, requirementsUiDir)}/`);
     }
     console.log('');
@@ -139,6 +211,58 @@ export class ScreenManager {
     console.log(`  4. Run: npx playwright test\n`);
   }
 
+  /**
+   * Capture full-page screenshot of the screen URL
+   */
+  private async captureScreenshot(pagePath: string, uiDir: string, screenName: string): Promise<void> {
+    const baseURL = this.getBaseURL();
+    if (!baseURL) {
+      console.log('  ⊘ Screenshot skipped: no baseURL found in playwright.config.ts');
+      return;
+    }
+
+    const url = `${baseURL.replace(/\/+$/, '')}${pagePath}`;
+    console.log(`\n📸 Capturing screenshot: ${url}`);
+
+    let browser;
+    try {
+      browser = await chromium.launch();
+      const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
+      await page.goto(url, { waitUntil: 'networkidle', timeout: 15000 });
+
+      // Full-page screenshot
+      const screenshotPath = path.join(uiDir, `${screenName}-full.png`);
+      await page.screenshot({ path: screenshotPath, fullPage: true });
+      console.log(`  ✓ Saved: ${path.relative(this.cwd, screenshotPath)}`);
+
+      // Viewport screenshot (above the fold)
+      const viewportPath = path.join(uiDir, `${screenName}-viewport.png`);
+      await page.screenshot({ path: viewportPath, fullPage: false });
+      console.log(`  ✓ Saved: ${path.relative(this.cwd, viewportPath)}`);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      if (msg.includes('net::ERR') || msg.includes('Timeout')) {
+        console.log(`  ⊘ Screenshot skipped: page not reachable (${msg.split('\n')[0]})`);
+      } else {
+        console.log(`  ⊘ Screenshot skipped: ${msg.split('\n')[0]}`);
+      }
+    } finally {
+      if (browser) await browser.close();
+    }
+  }
+
+  /**
+   * Read baseURL from playwright.config.ts
+   */
+  private getBaseURL(): string | null {
+    const configPath = path.join(this.cwd, 'playwright.config.ts');
+    if (!fs.existsSync(configPath)) return null;
+
+    const content = fs.readFileSync(configPath, 'utf-8');
+    const match = content.match(/baseURL:\s*['"]([^'"]+)['"]/);
+    return match ? match[1] : null;
+  }
+
   private validateScreenName(name: string): void {
     if (!name || name.trim().length === 0) {
       console.error('Error: Screen name cannot be empty');

package/src/orchestrator/templates/ai-instructions/claude-cmd-add-screen.md

@@ -33,20 +33,12 @@ Ask the user: "Would you like to fill in `requirements/spec.md` now? This helps
 - If they have UI designs (screenshots, Figma exports, mockups) → suggest copying them to `requirements/ui/`.
 - If no → proceed to step 3.
 
-### 3. Create test cases
+### 3. Next steps
 
-Ask the user: "Would you like to create test cases now?"
+Tell the user what was created, then use `AskUserQuestion` to offer next steps:
 
-If yes → **you MUST use the Skill tool** to invoke `/sungen:create-test <screen>`. This is critical because `create-test` auto-loads the `sungen-gherkin-syntax` and `sungen-tc-generation` skills which contain the full Gherkin syntax rules, pattern shapes, viewpoint checklists, and output format. **Do NOT attempt to generate test cases yourself** — always invoke the Skill tool so these skills are properly loaded.
+- **`/sungen:create-test <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
 
-```
-Skill: create-test
-Args: <screen>
-```
-
-### 4. Confirm
-
-If the user declined test case creation, tell them next steps:
-- Fill `requirements/spec.md` with screen specs (if not done)
-- Run `/sungen:create-test <screen>` to create test cases
-- Run `/sungen:run-test <screen>` to generate selectors, compile, and run tests
+If user picks `/sungen:create-test`, **you MUST use the Skill tool** to invoke it. Do NOT generate test cases yourself — the skill auto-loads `sungen-gherkin-syntax` and `sungen-tc-generation`.

package/src/orchestrator/templates/ai-instructions/claude-cmd-create-test.md

@@ -20,14 +20,22 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 3. **Read requirements** — check `qa/screens/<screen>/requirements/`:
    - If `spec.md` exists → read it as PRIMARY source (sections, fields, validation rules, business rules, states).
    - If `ui/` has images → read them for visual context (layout, element positions, states).
-   - If `notes.md` exists → read for edge cases and additional context.
+   - If `test-viewpoint.md` exists → read it. If it only contains HTML comments (scaffold template), use `AskUserQuestion` to ask:
+     - **Fill test-viewpoint.md first** — I'll help you identify edge cases, known issues, and design decisions for this screen before generating tests
+     - **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):
    - Use `AskUserQuestion` to ask: **Figma design** (provide Figma URL — recommended), **UI images** (screenshots/mockups in `requirements/ui/`), or **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 scan: `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.
 5. Follow the `sungen-tc-generation` skill for section identification, viewpoint generation, and output format. When requirements exist, use the "Requirements-Driven Generation" strategy.
 6. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills.
-7. Show summary → next: `/sungen:review <screen>` or `/sungen:run-test <screen>`
+7. Show summary, then use `AskUserQuestion` to offer next steps:
+
+- **`/sungen:review <screen>`** — Review syntax, coverage, viewpoint quality (Recommended)
+- **`/sungen:run-test <screen>`** — Skip review, generate selectors and run tests now
+- **`/sungen:create-test <screen>`** — Add more test cases for another section/viewpoint
+- **Done for now** — I'll come back later
 
 **No selectors.yaml** — selectors are generated during `/sungen:run-test`.

package/src/orchestrator/templates/ai-instructions/claude-cmd-review.md

@@ -19,3 +19,8 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 2. Follow the `sungen-tc-review` skill — score 3 dimensions: Syntax (30pts), Coverage (40pts), Viewpoint (30pts). Use `sungen-viewpoint` for pattern checklists.
 3. Output review report per `sungen-tc-review` format. **>= 60%**: PASS. **< 60%**: FAIL with recommendations.
 4. If FAIL and user confirms → update test cases following `sungen-gherkin-syntax` and `sungen-tc-generation` skills, then re-review.
+5. After PASS (or user decides to proceed), use `AskUserQuestion` to offer next steps:
+
+- **`/sungen:run-test <screen>`** — Generate selectors, compile, and run tests (Recommended)
+- **`/sungen:create-test <screen>`** — Add more test cases before running
+- **Done for now** — I'll come back later

package/src/orchestrator/templates/ai-instructions/claude-cmd-run-test.md

@@ -13,20 +13,28 @@ You are a **Senior Developer**. Use `sungen-selector-fix`, `sungen-selector-keys
 
 Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 
-## Phase 1: Compile & Run (no MCP)
+## Compile
 
 1. Verify `qa/screens/<screen>/` has `.feature` + `test-data.yaml`
 2. Ensure `selectors.yaml` has page selector. If missing, ask user for URL path
 3. `sungen generate --screen <screen>`
-4. `npx playwright test specs/generated/<screen>/*.spec.ts --reporter=line`
-5. If all pass → done
-
-## Phase 2: Targeted Fix (only if failures)
-
-6. Parse failures → group by root cause
-7. Navigate to page ONCE via MCP → ONE `browser_snapshot`
-8. Fix broken selectors per `sungen-selector-fix` skill
-9. Recompile → re-run only failing tests
-10. Repeat up to 3 attempts
-11. Final full run for regression check
-12. Still failing → ask user
+
+## 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.
+
+## Next steps
+
+After showing results, use `AskUserQuestion` to offer next steps:
+
+If all tests **passed**:
+- **`/sungen:create-test <screen>`** — 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
+- **Done for now** — I'll fix manually later

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

@@ -10,8 +10,9 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-gherkin-syntax` | All 70+ step patterns, selector types, YAML key rules, tags, element types |
 | `sungen-error-mapping` | Playwright & sungen error → fix mapping |
 | `sungen-tc-generation` | Test case generation strategy, output format |
+| `sungen-test-design-techniques` | EP, BVA, Decision Table, State Transition — systematic scenario generation |
 | `sungen-tc-review` | Review scoring, quality rules, checklist |
-| `sungen-viewpoint` | 7 UI patterns x 4 viewpoints — coverage checklists |
+| `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 |
 
@@ -26,6 +27,8 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 
 **Order:** add-screen → create-test → review → run-test.
 
+After each command completes, use `AskUserQuestion` to 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
 
 ```
@@ -38,102 +41,6 @@ qa/screens/<screen-name>/
     └── ui/                        # Screenshots, mockups
 ```
 
-## Complete Example
-
-Given a login page, here are the 3 files you generate:
-
-**qa/screens/login/features/login.feature**
-```gherkin
-@no-auth
-Feature: Login Screen
-
-  Scenario: VP-LOGIC-001 Successful login
-    Given User is on [login] page
-    When User fill [Email] field with {{email}}
-    And User fill [Password] field with {{password}}
-    And User click [Submit] button
-    Then User see [Welcome] heading with {{welcome_text}}
-    And User see [Dashboard] link
-```
-
-**qa/screens/login/selectors/login.yaml**
-```yaml
-login:
-  type: 'page'
-  value: '/login'
-
-email:
-  type: 'placeholder'
-  value: 'Enter your email'
-
-password:
-  type: 'placeholder'
-  value: 'Enter your password'
-
-submit:
-  type: 'role'
-  value: 'button'
-  name: 'Submit'
-
-welcome:
-  type: 'role'
-  value: 'heading'
-  name: 'Welcome'
-
-dashboard:
-  type: 'role'
-  value: 'link'
-  name: 'Dashboard'
-```
-
-**qa/screens/login/test-data/login.yaml**
-```yaml
-email: 'admin@example.com'
-password: 'password123'
-welcome_text: 'Welcome back'
-```
-
-## Critical Gherkin Rules (quick reference)
-
-1. **NEVER write `is visible`** — `User see [T] type` already asserts visibility. Only use `is hidden` to assert absence.
-2. **Use `@no-auth` for pre-login pages** (login, register, forgot-password). Use `@auth:role` for authenticated pages.
-3. **Scenario names use VP prefix** — `VP-UI-001`, `VP-VAL-001`, `VP-LOGIC-001`, `VP-SEC-001`.
-4. **Values use `{{snake_case}}`** — never hardcode data in `.feature`. All values go in `test-data.yaml`.
-5. **Selectors are deferred** — `selectors.yaml` is generated during `/sungen-run-test` from the live page, NOT during `/sungen-create-test`.
-6. **Every `{{variable}}` must exist in `test-data.yaml`** — missing variables cause compile failures.
-7. **Assertion type is determined by element type** — input types (`field`, `textarea`, `search`, `dropdown`, `slider`, `date-picker`) → `toHaveValue()`. Everything else → `toHaveText()`. Wrong type = wrong assertion = test failure.
-
-## Using Playwright MCP to explore pages
-
-When exploring a page to generate test files:
-1. Read `playwright.config.ts` for `baseURL`
-2. Use `browser_navigate` to open `baseURL + /path`
-3. Use `browser_snapshot` to see all elements
-4. Generate the 3 files from the snapshot
-
-### Allowed MCP tools
-
-| Tool | Use for |
-|---|---|
-| `browser_navigate` | Open pages |
-| `browser_snapshot` | Capture all accessible elements |
-| `browser_click` | Interact with elements (open dialogs, dropdowns) |
-| `browser_fill_form` | Fill form fields |
-| `browser_evaluate` | **Read-only DOM queries only** (e.g., detect `data-testid` attributes) |
-
-**NEVER use `browser_run_code`** — fails with `require is not defined`.
-
-### Authentication via MCP
-
-1. `browser_navigate` to `baseURL`
-2. If redirected to login, ask the user to log in manually:
-   > "This page requires login. Please log in using the browser. Confirm when you're done."
-3. Once confirmed, `browser_navigate` to the target page and take `browser_snapshot`
-
-**Never use `sungen makeauth`.** Always let the user log in manually via the MCP browser.
-**NEVER use `browser_evaluate` to inject cookies or localStorage** — causes size limit issues and server 500 errors. Use `browser_evaluate` ONLY for read-only DOM queries.
-**Minimize navigations** — take one snapshot per page, do not navigate repeatedly.
-
 ## CLI Commands
 
 ```bash