@sun-asterisk/sungen 2.2.3 → 2.3.0

package/src/generators/test-generator/patterns/index.ts

@@ -72,6 +72,14 @@ export class PatternRegistry {
     // Prefer resolver (framework-agnostic) over generator (legacy)
     if (pattern.resolver) {
       const resolved = pattern.resolver(step, context);
+
+      // Auto-inject parent scoping if step has parentRef
+      if (step.parentRef && step.parentType) {
+        resolved.data.parentLocator = PatternRegistry.resolveParentLocator(
+          step.parentRef, step.parentType, context
+        );
+      }
+
       const code = context.templateEngine.renderStep(resolved.templateName, resolved.data);
       return {
         code,
@@ -86,6 +94,39 @@ export class PatternRegistry {
     return null;
   }
 
+  /**
+   * Resolve parent scoping to a Playwright locator string.
+   * Tries YAML lookup first, falls back to auto-infer from parentType.
+   *
+   * Parent type → Playwright role:
+   *   table → 'table', list → 'list', section → 'region',
+   *   dialog → 'dialog', form → 'form'
+   */
+  private static resolveParentLocator(
+    parentRef: string, parentType: string, context: PatternContext
+  ): string {
+    // Try resolving from selectors YAML
+    try {
+      const resolved = context.selectorResolver.resolveSelector(
+        parentRef, context.featureName, parentType, 0
+      );
+      return context.renderLocator(resolved);
+    } catch {
+      // Fallback: auto-infer from parentType + parentRef as accessible name
+    }
+
+    const roleMap: Record<string, string> = {
+      table: 'table',
+      list: 'list',
+      section: 'region',
+      dialog: 'dialog',
+      form: 'form',
+    };
+    const role = roleMap[parentType] || parentType;
+    const escapedName = parentRef.replace(/'/g, "\\'");
+    return `page.getByRole('${role}', { name: '${escapedName}' })`;
+  }
+
   /**
    * Check if step matches a pattern matcher
    */

package/src/generators/test-generator/patterns/table-patterns.ts

@@ -6,11 +6,12 @@
 import { StepPattern } from './types';
 
 export const tablePatterns: StepPattern[] = [
-  // "User see [Users] table has {{count}} rows" — must have "rows" AFTER {{data}}
+  // "User see [Users] table with {{count}} rows" (preferred)
+  // Also accepts: "User see [Users] table has {{count}} rows" (backward compat)
   {
     name: 'table-row-count',
     matcher: (step) => {
-      return /\btable\s+has\b/i.test(step.text) &&
+      return /\btable\s+(?:has|with)\b/i.test(step.text) &&
              /\}\}\s*rows?\b/i.test(step.text) &&
              !!step.dataRef;
     },
@@ -29,7 +30,8 @@ export const tablePatterns: StepPattern[] = [
     priority: 16,
   },
 
-  // "User see [Users] table has [Email] column"
+  // "User see [Users] table has [Email] column" (backward compat)
+  // Preferred: "User see [Email] column in [Users] table" (parent scoping)
   {
     name: 'table-column-exists',
     matcher: (step) => {
@@ -152,11 +154,12 @@ export const tablePatterns: StepPattern[] = [
     priority: 17,
   },
 
-  // "User see [Users] table has row with {{name}}"
+  // "User see [Users] table row with {{name}}" (preferred)
+  // Also accepts: "User see [Users] table has row with {{name}}" (backward compat)
   {
     name: 'table-row-exists',
     matcher: (step) => {
-      return /\btable\s+has\s+row\s+with\b/i.test(step.text) && !!step.dataRef;
+      return /\btable\s+(?:has\s+)?row\s+with\b/i.test(step.text) && !!step.dataRef;
     },
     resolver: (step, context) => {
       const resolved = context.selectorResolver.resolveSelector(

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

@@ -0,0 +1,139 @@
+/**
+ * AI Rules Updater
+ * Updates AI rules, commands, and skills from bundled templates.
+ * Used by `sungen update` command.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// File mapping: [templateFile, outputPath]
+// Shared with project-initializer.ts
+export const AI_RULES_FILE_MAPPING: [string, string][] = [
+  // Config
+  ['claude-config.md', 'CLAUDE.md'],
+  ['copilot-config.md', '.github/copilot-instructions.md'],
+
+  // Commands — Claude Code
+  ['claude-cmd-add-screen.md', '.claude/commands/sungen/add-screen.md'],
+  ['claude-cmd-make-tc.md', '.claude/commands/sungen/make-tc.md'],
+  ['claude-cmd-make-test.md', '.claude/commands/sungen/make-test.md'],
+
+  // Commands — GitHub Copilot
+  ['copilot-cmd-add-screen.md', '.github/prompts/sungen-add-screen.prompt.md'],
+  ['copilot-cmd-make-tc.md', '.github/prompts/sungen-make-tc.prompt.md'],
+  ['copilot-cmd-make-test.md', '.github/prompts/sungen-make-test.prompt.md'],
+
+  // Skills — Claude Code
+  ['claude-skill-gherkin-syntax.md', '.claude/skills/sungen-gherkin-syntax/SKILL.md'],
+  ['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-selector-fix.md', '.claude/skills/sungen-selector-fix/SKILL.md'],
+
+  // Skills — GitHub Copilot
+  ['github-skill-sungen-gherkin-syntax.md', '.github/skills/sungen-gherkin-syntax/SKILL.md'],
+  ['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-selector-fix.md', '.github/skills/sungen-selector-fix/SKILL.md'],
+];
+
+export class AIRulesUpdater {
+  private cwd: string;
+  private aiTemplateDir: string;
+
+  constructor(cwd: string) {
+    this.cwd = cwd;
+    this.aiTemplateDir = path.join(__dirname, 'templates', 'ai-instructions');
+  }
+
+  async update(dryRun: boolean): Promise<void> {
+    console.log('🔄 Updating AI rules, commands, and skills...\n');
+
+    const updated: string[] = [];
+    const created: string[] = [];
+    const unchanged: string[] = [];
+    const missing: string[] = [];
+
+    for (const [templateFile, outputRelPath] of AI_RULES_FILE_MAPPING) {
+      const templatePath = path.join(this.aiTemplateDir, templateFile);
+      const outputPath = path.join(this.cwd, outputRelPath);
+
+      if (!fs.existsSync(templatePath)) {
+        missing.push(templateFile);
+        continue;
+      }
+
+      const newContent = fs.readFileSync(templatePath, 'utf-8');
+
+      if (fs.existsSync(outputPath)) {
+        const currentContent = fs.readFileSync(outputPath, 'utf-8');
+        if (currentContent === newContent) {
+          unchanged.push(outputRelPath);
+          continue;
+        }
+
+        if (!dryRun) {
+          fs.writeFileSync(outputPath, newContent, 'utf-8');
+        }
+        updated.push(outputRelPath);
+      } else {
+        if (!dryRun) {
+          const outputDir = path.dirname(outputPath);
+          if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+          }
+          fs.writeFileSync(outputPath, newContent, 'utf-8');
+        }
+        created.push(outputRelPath);
+      }
+    }
+
+    // Print results
+    if (dryRun) {
+      console.log('📋 Dry run — no files changed\n');
+    }
+
+    if (updated.length > 0) {
+      console.log(`✏️  Updated (${updated.length}):`);
+      for (const f of updated) {
+        console.log(`   ${f}`);
+      }
+      console.log();
+    }
+
+    if (created.length > 0) {
+      console.log(`✨ Created (${created.length}):`);
+      for (const f of created) {
+        console.log(`   ${f}`);
+      }
+      console.log();
+    }
+
+    if (unchanged.length > 0) {
+      console.log(`✅ Already up to date (${unchanged.length}):`);
+      for (const f of unchanged) {
+        console.log(`   ${f}`);
+      }
+      console.log();
+    }
+
+    if (missing.length > 0) {
+      console.log(`⚠️  Template not found (${missing.length}):`);
+      for (const f of missing) {
+        console.log(`   ${f}`);
+      }
+      console.log();
+    }
+
+    const totalChanges = updated.length + created.length;
+    if (totalChanges === 0) {
+      console.log('All AI rules are up to date. No changes needed.');
+    } else if (dryRun) {
+      console.log(`${totalChanges} file(s) would be changed. Run without --dry-run to apply.`);
+    } else {
+      console.log(`${totalChanges} file(s) updated successfully.`);
+    }
+  }
+}

package/src/orchestrator/project-initializer.ts

@@ -6,6 +6,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { execSync } from 'child_process';
+import { AI_RULES_FILE_MAPPING } from './ai-rules-updater';
 
 export class ProjectInitializer {
   private baseCwd: string;
@@ -250,38 +251,7 @@ export class ProjectInitializer {
   private createAIRules(): void {
     const aiTemplateDir = path.join(__dirname, 'templates', 'ai-instructions');
 
-    // File mapping: [templateFile, outputPath]
-    const fileMapping: [string, string][] = [
-      // Config
-      ['claude-config.md', 'CLAUDE.md'],
-      ['copilot-config.md', '.github/copilot-instructions.md'],
-
-      // Commands — Claude Code
-      ['claude-cmd-add-screen.md', '.claude/commands/sungen/add-screen.md'],
-      ['claude-cmd-make-tc.md', '.claude/commands/sungen/make-tc.md'],
-      ['claude-cmd-make-test.md', '.claude/commands/sungen/make-test.md'],
-
-      // Commands — GitHub Copilot
-      ['copilot-cmd-add-screen.md', '.github/prompts/sungen-add-screen.prompt.md'],
-      ['copilot-cmd-make-tc.md', '.github/prompts/sungen-make-tc.prompt.md'],
-      ['copilot-cmd-make-test.md', '.github/prompts/sungen-make-test.prompt.md'],
-
-      // Skills — Claude Code
-      ['claude-skill-gherkin-syntax.md', '.claude/skills/sungen-gherkin-syntax/SKILL.md'],
-      ['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-selector-fix.md', '.claude/skills/sungen-selector-fix/SKILL.md'],
-
-      // Skills — GitHub Copilot (separate copies with Copilot-friendly descriptions)
-      ['github-skill-sungen-gherkin-syntax.md', '.github/skills/sungen-gherkin-syntax/SKILL.md'],
-      ['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-selector-fix.md', '.github/skills/sungen-selector-fix/SKILL.md'],
-    ];
-
-    for (const [templateFile, outputRelPath] of fileMapping) {
+    for (const [templateFile, outputRelPath] of AI_RULES_FILE_MAPPING) {
       const outputPath = path.join(this.cwd, outputRelPath);
 
       if (fs.existsSync(outputPath)) {

package/src/orchestrator/screen-manager.ts

@@ -47,6 +47,8 @@ export class ScreenManager {
     const featuresDir = path.join(screenDir, 'features');
     const selectorsDir = path.join(screenDir, 'selectors');
     const testDataDir = path.join(screenDir, 'test-data');
+    const requirementsDir = path.join(screenDir, 'requirements');
+    const requirementsUiDir = path.join(requirementsDir, 'ui');
 
     // File paths
     const featurePath = path.join(featuresDir, `${filename}.feature`);
@@ -66,6 +68,7 @@ export class ScreenManager {
         fs.mkdirSync(featuresDir, { recursive: true });
         fs.mkdirSync(selectorsDir, { recursive: true });
         fs.mkdirSync(testDataDir, { recursive: true });
+        fs.mkdirSync(requirementsUiDir, { recursive: true });
       } catch (error) {
         console.error(`Error: Failed to create directories`);
         console.error(`  ${error instanceof Error ? error.message : String(error)}`);
@@ -111,15 +114,27 @@ export class ScreenManager {
       ].join('\n'), 'utf-8');
     }
 
+    // Generate requirements spec.md (only on first screen creation)
+    const specPath = path.join(requirementsDir, 'spec.md');
+    if (!fs.existsSync(specPath)) {
+      fs.writeFileSync(specPath, this.generateSpecTemplate(options, screenName), 'utf-8');
+    }
+
     // Display success
     console.log(`Created files:`);
     console.log(`  ${path.relative(this.cwd, featurePath)}`);
     console.log(`  ${path.relative(this.cwd, selectorPath)}`);
-    console.log(`  ${path.relative(this.cwd, testDataPath)}\n`);
+    console.log(`  ${path.relative(this.cwd, testDataPath)}`);
+    if (isFirstFile) {
+      console.log(`  ${path.relative(this.cwd, specPath)}`);
+      console.log(`  ${path.relative(this.cwd, requirementsUiDir)}/`);
+    }
+    console.log('');
 
     console.log('Next steps:');
-    console.log(`  1. Use AI (Copilot/Claude) to generate Gherkin + selectors from the live page`);
-    console.log(`  2. Fill in test-data values`);
+    console.log(`  1. Fill requirements/spec.md with screen spec (fields, validation, business rules)`);
+    console.log(`     Optionally add UI designs to requirements/ui/ (screenshots, mockups)`);
+    console.log(`  2. Generate test cases: /sungen:make-tc ${screenName} (or /sungen-make-tc)`);
     console.log(`  3. Compile: sungen generate --screen ${screenName}`);
     console.log(`  4. Run: npx playwright test\n`);
   }
@@ -150,6 +165,60 @@ export class ScreenManager {
     return this.normalizeScreenName(lastSegment);
   }
 
+  private generateSpecTemplate(options: ScreenOptions, screenName: string): string {
+    const pagePath = options.path || `/${screenName}`;
+    return `# ${options.name} Screen Specification
+
+## Overview
+- **URL Path:** ${pagePath}
+- **Auth Required:** no
+- **Platform:** web
+
+## Sections
+
+### Section: [Section Name]
+- **Type:** form | table | list | card | tabs | modal | search | navigation
+- **Description:** [Brief description of this section]
+
+#### Fields
+<!-- Remove this table if section has no input fields -->
+| Field | Type | Required | Constraints | Default |
+|-------|------|----------|-------------|---------|
+| [Field Name] | input (text) | yes | max 255 | — |
+
+#### Actions
+| Action | Element | Behavior |
+|--------|---------|----------|
+| [Action Name] | button | [What happens on click] |
+
+#### Validation Rules
+<!-- Exact error messages help AI generate accurate assertions -->
+| Condition | Error Message |
+|-----------|---------------|
+| Empty required field | "[Exact error message from UI]" |
+
+#### States
+| State | Condition | Visual |
+|-------|-----------|--------|
+| Default | Page load | [Default appearance] |
+| Loading | After submit | [Loading indicator] |
+| Error | Validation fail | [Error appearance] |
+| Success | Action complete | [Success behavior] |
+
+## Business Rules
+<!-- Rules that affect test logic: limits, permissions, conditions -->
+- [Rule 1]
+
+## Accessibility
+<!-- Tab order, aria-labels, screen reader behavior -->
+- Tab order: [field1] → [field2] → [submit]
+
+## Notes
+<!-- Edge cases, known issues, environment-specific behavior -->
+- [Note 1]
+`;
+  }
+
   private generateFeatureTemplate(options: ScreenOptions, filename: string): string {
     const screenName = this.normalizeScreenName(options.name);
     const featurePath = options.path || `/${screenName}`;

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

@@ -25,19 +25,28 @@ Run:
 sungen add --screen <screen> --path <path>
 ```
 
-### 2. Create test cases
+### 2. Fill requirements (recommended)
+
+Ask the user: "Would you like to fill in `requirements/spec.md` now? This helps generate higher quality test cases."
+
+- If yes → open `qa/screens/<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.
+
+### 3. Create test cases
 
 Ask the user: "Would you like to create test cases now?"
 
-If yes, delegate to `/sungen:make-tc <screen>` to handle:
-- Exploring the live page or analyzing static designs
-- Gathering test viewpoints (UI/UX, Validation, Logic, Security)
-- Generating the 3 files (feature, selectors, test-data)
+If yes → **you MUST use the Skill tool** to invoke `/sungen:make-tc <screen>`. This is critical because `make-tc` 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.
+
+```
+Skill: make-tc
+Args: <screen>
+```
 
-### 3. Confirm
+### 4. Confirm
 
-Tell the user what was created and next steps:
-- If the page requires authentication, the user will be asked to log in via the MCP browser during `/sungen:make-tc`
-- Edit the generated files as needed
+If the user declined test case creation, tell them next steps:
+- Fill `requirements/spec.md` with screen specs (if not done)
 - Run `/sungen:make-tc <screen>` to create test cases
 - Run `/sungen:make-test <screen>` to generate selectors, compile, and run tests

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

@@ -17,9 +17,16 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 
 1. Verify `qa/screens/<screen>/` exists. If not → `/sungen:add-screen` first.
 2. Check if `.feature` file already has scenarios. If yes → use `AskUserQuestion` to ask the update mode (see `sungen-tc-generation` skill for details). If no → fresh creation.
-3. Use `AskUserQuestion` to ask: **Live page** (explore via Playwright MCP) or **Static designs** (screenshots, Figma)? Explore accordingly (see CLAUDE.md for MCP rules).
-4. Follow the `sungen-tc-generation` skill for section identification, viewpoint generation, and output format.
-5. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills.
-6. Show summary → next: `/sungen:make-test <screen>`
+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.
+   - Summarize what you found in requirements and present to the user.
+4. **Explore page** (supplements requirements, or is primary source if no requirements):
+   - Use `AskUserQuestion` to ask: **Live page** (explore via Playwright MCP) or **Static designs** (screenshots, Figma)? Or **Skip** (if requirements are sufficient)?
+   - 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:make-test <screen>`
 
 **No selectors.yaml** — selectors are generated during `/sungen:make-test`.

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

@@ -16,16 +16,14 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 ## Steps
 
 1. Verify `qa/screens/<screen>/` has `.feature` + `test-data.yaml`. If not → `/sungen:make-tc` first.
-2. Generate `selectors.yaml` from live page using `sungen-selector-fix` and `sungen-selector-keys` skills.
-3. Compile: `sungen generate --screen <screen>`
-4. **Initial run** — run ALL tests to get the full failure picture:
-   `npx playwright test specs/generated/<screen>/<screen>.spec.ts --reporter=line`
-5. **Batched fix loop** (max 5 attempts) — see `sungen-selector-fix` skill for details:
-   - Group failures by root cause (same selector, same error type)
-   - Fix selectors/test-data for the current batch
-   - Recompile, then re-run ONLY the previously-failing tests (max 20 at a time via `--grep`)
-   - If the batch passes, pick the next batch of remaining failures
-   - Repeat until no failures remain or max attempts reached
-6. **Final confirmation** — run ALL tests once to ensure no regressions.
+2. **Generate selectors** — explore live page via MCP, build `selectors.yaml` using `sungen-selector-fix` and `sungen-selector-keys` skills.
+3. **Proactive validation** — verify EVERY selector against the live page using `browser_snapshot` + `browser_evaluate` BEFORE running any test. Fix mismatches immediately. See `sungen-selector-fix` skill "Proactive Selector Validation" section. Target: 80%+ issues fixed before first run.
+4. **Compile**: `sungen generate --screen <screen>`
+5. **Batched test run** — run tests in batches of 20 via `--grep`:
+   `npx playwright test specs/generated/<screen>/*.spec.ts --grep "VP-UI-001|...|VP-UI-020" --reporter=line`
+   - If failures in batch → group by root cause, fix, recompile, re-run only failing tests
+   - If batch passes → move to next 20 tests
+   - Max 5 fix attempts per batch
+6. **Final confirmation** — run ALL tests once to catch regressions.
 7. After 5 fix attempts still failing → ask user about direct `.spec.ts` fix.
 8. Show: pass/fail, attempt count, files changed.

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

@@ -7,12 +7,13 @@ user-invocable: false
 ## Standard Syntax
 
 ```
-[Keyword] User <Action> [Target Name] <Target Type> <with {{Value}}> <is State>
+[Keyword] User <Action> [Target Name] <Target Type> <in [Parent Name] <Parent Type>> <with {{Value}}> <is State>
 ```
 
 - **Actor**: Always `User`, always active voice.
 - **Value**: `with {{snake_case}}` — never hardcode static data.
 - **State**: `is <keyword>` — never use `{{}}` for states.
+- **Parent scope**: `in [Parent] parentType` — optional, only when page has 2+ similar blocks needing disambiguation.
 
 ## Keyword → Action Rules
 
@@ -112,11 +113,11 @@ User switch to [T] frame                         # enter iframe
 User switch to [main] frame                      # exit iframe
 ```
 
-### Assertions (6 verify patterns)
+### Assertions (8 verify patterns)
 
 ```
 # 1. Visibility
-User see [T] message                             # visible (default)
+User see [T] message                             # visible (default — NEVER add "is visible")
 User see [T] modal is hidden                     # hidden
 
 # 2. Text Content (exact full match — toHaveText)
@@ -140,26 +141,44 @@ User see [T] checkbox is checked                 # checked state
 User see [T] toggle is unchecked                 # unchecked state
 User see [T] dialog with {{v}} is hidden         # text + state combined
 
-# 6. Count
+# 6. Attribute (toHaveAttribute — when selector YAML has `attribute` field)
+User see [T] image with {{v}}                    # image src
+User see [T] link with {{v}}                     # link href
+
+# 7. Count
 User see [T] row with {{count}}                  # element count
 
-# 7. Page Context
+# 8. Page Context
 User see [T] page                                # URL assertion
 ```
 
 ### Table
 
 ```
-User see [Table] table has row with {{f}}        # row exists
+User see [Col] column in [Table] table           # column exists (parent scoping)
+User see [Table] table row with {{f}}            # row exists
 User see [Table] table has no row with {{f}}     # row not exists
-User see [Table] table has {{count}} rows        # row count
-User see [Table] table has [Col] column          # column exists
+User see [Table] table with {{count}} rows       # row count
 User see [Table] table is empty                  # empty table
 User see [Table] table row with {{f}} has [Col] with {{v}}  # cell by filter
 User see [Table] table row 1 [Col] cell with {{v}}          # cell by index
 User click [Act] in [Table] table row with {{f}}             # action in row
 ```
 
+### Parent Scoping (disambiguation)
+
+```
+User click [Submit] button in [User Info] form           # button inside specific form
+User fill [Email] field in [Registration] form with {{v}} # field inside specific form
+User see [Total] text in [Summary] section with {{v}}    # text inside specific section
+User click [Delete] button in [Active Users] table       # button inside specific table
+```
+
+- **Optional** — only use when page has 2+ similar UI blocks
+- **Valid parent types**: `table`, `list`, `section`, `dialog`, `form`
+- **Max 2 levels**: `[Target] in [Parent]`. **NEVER** nest 3 levels: `[A] in [B] in [C]`
+- Parent resolves from selectors YAML first, falls back to auto-infer `getByRole(parentType, { name })`
+
 ### States
 
 `hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `sorted ascending` `sorted descending`