@sun-asterisk/sungen 2.6.15 → 2.7.0-beta.1

package/src/orchestrator/templates/ai-instructions/claude-skill-tc-generation.md

@@ -1,417 +1,483 @@
 ---
 name: sungen-tc-generation
-description: 'Test case generation strategy — section-focused, viewpoint-driven, Gherkin + test-data only. Auto-loaded by create-test command.'
+description: 'Use when create-test needs to translate spec.md/Figma/UI into .feature + test-data.yaml. Invoke after requirements are read, before any selectors.yaml work.'
 user-invocable: false
 ---
 
-## Goal
+## ⚠️ Gotchas — read before generating
 
-Generate **focused test cases per screen section** using a **tier-based approach** for faster results. Output `.feature` + `test-data.yaml` only — selectors are deferred to `/sungen:run-test`.
+- `spec_figma.md` exists → read file only, **NEVER** call `mcp__figma__*`
+  → PAT auth flow already done by `sungen-figma-source`; re-calling fails or duplicates work.
 
-### Tier System
+- `selectors.yaml` → do **NOT** generate — handled by `run-test`
+  → Selectors need live DOM inspection via Playwright MCP, only `run-test` triggers it.
 
-| Tier | Priority | What to generate | When |
-|---|---|---|---|
-| **Tier 1** (default) | `@high` | Happy paths, required validation, core business rules, security basics | First run of `create-test` |
-| **Tier 2** (expand) | `@normal` + `@low` | UI presence, optional validation, edge cases, cosmetic checks | User runs `create-test` again with "Add viewpoints" mode |
-| **Tier 3** (deep) | `@high` + `@normal` + `@low` | Extra BVA combinations, cross-field validation, negative/destructive inputs, concurrent/race conditions, complex state transitions | Recommended after Tier 2 completes |
-| **Full** (all-at-once) | All | Tier 1 + 2 + 3 combined in one run | Option at first run, **not recommended** — large output |
+- `@steps:` scenarios → **NO** priority tag (setup blocks, not test cases)
+  → Priority tags filter test runs; setup blocks must always run via `@extend:`, never be filtered out.
 
-**Round 1 (Tier 1)** targets **~10-15 scenarios per section** — enough to cover critical flows and catch real bugs. This is the default behavior. A **Full** option is available but not recommended — it generates all tiers at once, producing very large output (~40-60 scenarios/section).
+- Hardcode exact error messages in test-data.yaml — never leave `{{error}}` vague
+  → Assertions are string-equal; vague placeholders produce false-positive passes.
 
-**Round 2 (Tier 2)** expands coverage when the user explicitly chooses "Add viewpoints" or "Add new sections" update mode. Only then generate `@normal` + `@low` scenarios to fill coverage gaps.
+- `@parallel` required when mixing `@auth:X` + `@no-auth` in the same feature
+  → Playwright shares browser context per worker; auth state leaks across scenarios without isolation.
 
-## Update Mode
+- XSS ≠ SQL injection — generate as **2 separate scenarios**, never merge
+  → Different attack vectors (client render vs DB query) and different observable failures (alert popup vs DB error).
 
-When `.feature` already has scenarios, detect which tiers exist by scanning section comments, then ask the appropriate update mode.
+- **SQL injection has 2 layers — generate both when field reaches a backend query:**
+  - Layer 1 → field UI: special chars blocked by input field → `@high` automated scenario
+  - Layer 2 → API server: field accepts alphanumeric (e.g. LIKE/search field) → send payload like `1 OR 1=1` directly to API (curl/Postman, bypass UI) → verify server uses parameterized query, not string concat → `@high @manual`
+  → Skipping Layer 2 = missing real attack vector even when field validation is correct.
+  → Trigger: any free-text field whose value reaches a LIKE, partial-match, or dynamic WHERE clause.
 
-**Tier detection** — scan for `# --- Section:` comments:
-- Only `(Tier 1: @high)` comments → **Tier 1 only**
-- Has `(Tier 2: @normal + @low)` comments → **Tier 1 + 2**
-- Has `(Tier 3: deep)` comments → **Tier 1 + 2 + 3**
+- **Concurrent / race conditions — generate `@manual` when spec or viewpoint mentions multi-tab, multi-user, or simultaneous actions:**
+  → Examples: two browser tabs same search with different conditions must not contaminate each other; double-click submit must not create duplicates.
+  → `@normal @manual` by default — unless data integrity at risk → `@high @manual`.
+  → Do NOT skip because "hard to automate" — document as `@manual` so it appears in the test plan.
 
-**If Tier 1 only:**
-1. **Add new sections** — append new sections with Tier 2 (`@normal` + `@low`) scenarios, continue numbering
-2. **Add viewpoints** — expand existing sections with Tier 2 (`@normal` + `@low`) scenarios
+- Spec mentions outcomes on a **different user-facing surface** (another URL, mobile app, user portal, widget)
+  → "Single screen focus" means don't test other screens' UI patterns — it does NOT exempt you from documenting business outcomes on other surfaces.
+  → **Always generate `@manual` scenarios for the output surface** — at minimum one `@high @manual` per cross-surface business rule.
+  → If the output surface is reachable with a different auth role in the same test run, use `@auth:role` + `@extend` setup instead of `@manual`.
+  → Skipping these entirely = zero test can catch "admin creates record correctly but user never sees it" — the most silent failure class.
+  → Add `Display surfaces` + `Cross-surface rules` to the Coverage Map (see Step 2).
 
-**If Tier 1 + 2:**
-1. **Deep coverage (Tier 3)** — add advanced scenarios: extra BVA, cross-field validation, negative inputs, race conditions **(Recommended)**
-2. **Add new sections** — append new sections with Tier 2 scenarios, continue numbering
+- Spec uses **inclusive boundary operators** (`<=`, `>=`, `≤`, `≥`, "at least N", "no more than N", "up to and including")
+  → The boundary point itself **must** be a test case — not just "inside" and "outside" regions.
+  → Generate: `boundary - 1` (must fail/not-display), `boundary` (must pass/display), `boundary + 1` (must pass or fail depending on direction).
+  → Example: `end_at >= now` → test `end_at = now` (inclusive: display), `end_at = now - 1s` (exclusive: no display).
+  → Off-by-one at inclusive boundaries is the most common display-logic bug.
 
-**If Tier 1 + 2 + 3** (full coverage):
-1. **Add new sections** — append new sections if screen has changed
-
-> **Replace all** (available in all modes) — overwrite with fresh Tier 1 (`@high`) generation. Use when spec has changed significantly.
-
-For append: read highest `VP-<CAT>-<NNN>`, continue from next number. Never modify existing scenarios.
+- **AND condition in business rule — test each branch failing independently:**
+  When spec defines "A AND B AND C must all be true", generate:
+  (1) A fails while B/C pass, (2) B fails while A/C pass, (3) C fails while A/B pass.
+  OR condition: generate 1 scenario per branch where that branch alone triggers the outcome.
+  → Happy-path only = missing the most common multi-condition implementation bug.
 
-## Requirements-Driven Generation
+---
 
-When `qa/screens/<screen>/requirements/` exists:
-- **`spec.md`** — primary: sections, field constraints, validation messages, business rules, states
-- **`ui/`** — supplementary: screenshots for layout/visual context
-- **`test-viewpoint.md`** — supplementary: edge cases, known issues
+## Tier System
 
-Requirements improve every viewpoint: exact error messages for VAL, business rules for LOGIC, role permissions for SEC.
+| Tier | Priority | What to generate | When |
+|---|---|---|---|
+| **Tier 1** (default) | `@high` | Happy paths, required validation, core business rules, security basics | First run of `create-test` |
+| **Tier 2** (expand) | `@normal` + `@low` | UI presence, optional validation, edge cases, cosmetic checks | User runs `create-test` with "Add viewpoints" mode |
 
-If also exploring live page: verify spec vs actual, flag mismatches, capture exact text.
+**Tier 1 stops when:**
+- Every core user task has a happy-path scenario
+- Every validation rule has at least one negative case (required, format, boundary)
+- Every business rule has at least one scenario
+- Security basics covered (auth redirect, permission blocked, injection)
 
-### Tier 1 — Lightweight Guard
+**Tier 2** only when the user explicitly chooses "Add viewpoints" or "Add new sections".
 
-> Tier 1 uses the quick 3-step strategy (Step 1–3) without full section walking. After generation, verify these checks against `spec.md` — if any are missing, add them before finalizing:
+**Fast-path** — display-only screens (no form, no state machine, ≤2 sections):
+skip Coverage Map (Step 2) entirely. Go straight to Output Format with Tier 1 VP-UI presence checks
+and any obvious VP-SEC (auth redirect). Spec drives nothing here — viewpoint covers it.
 
-| Spec section | Minimum TC requirement | Tag |
-|---|---|---|
-| Fields row, `Required=yes` | At least 1 required-error TC per required field | `@high` |
-| Validation Rules row | At least 1 exact-message TC per validation rule | `@high` |
-| Business Rule bullet | At least 1 behavioral TC per business rule | `@high` |
-| Security-sensitive actions (auth, permissions) | At least 1 security check (VP-SEC) | `@high` |
-| Entity with lifecycle states | At least 1 key state transition (VP-LOGIC) | `@high` |
-
-Other spec sections (Section header, Default, Accessibility, Notes) are deferred to Tier 2.
-
-### Mapping Contract (Tier 2+ — MANDATORY)
-
-> **Full contract applies from Tier 2 onwards.** Walk `spec.md` top-to-bottom. For every section listed below, you **MUST** produce the indicated TCs. If a section is missing or empty, note it explicitly — do **NOT** silently skip.
-
-#### Table 1 — `spec.md` → TC Mapping Contract
-
-| Spec section | TC requirement | Tier | Tag | Viewpoint |
-|---|---|---|---|---|
-| Section header | 1 presence TC | T2 | `@low` | VP-UI |
-| Fields row, `Required=yes` | 1 per-field required-error TC (individual, not bulk) | T2 | `@normal` | VP-VAL |
-| Fields `Constraints` cell (non-empty, non-`—`) | 4 BVA for numeric range; 1 EP for format | T2 | `@normal` | VP-VAL |
-| Fields `Constraints` cell (numeric) | 2 extra BVA (`min+1`, `max-1`) + mid-range → total 7-point with T2 | T3 | `@normal` | VP-VAL |
-| Fields `Default` cell (non-empty, non-`—`) | 1 default-state TC | T2 | `@low` | VP-UI |
-| Fields with dependencies (conditional required, cascading) | 1 cross-field TC per dependency | T3 | `@normal` | VP-VAL |
-| Fields accepting free text input | 1 negative input TC (XSS/SQL injection/special chars) | T3 | `@high` | VP-SEC |
-| Actions row (primary: submit, create, delete) | 1 edge/alternate behavior TC | T2 | `@normal` | VP-LOGIC |
-| Actions row (secondary: cancel, reset, export) | 1 behavior TC | T2 | `@normal` | VP-LOGIC |
-| Actions with submit/save | 1 race condition TC (double-submit, back after POST) | T3 | `@normal` | VP-LOGIC |
-| Validation Rules row | 1 exact-message TC | T2 | `@normal` | VP-VAL |
-| States row (Default/Loading/Error/Success) | 1 visual state TC | T2 | `@normal` | VP-UI / VP-LOGIC |
-| States row (other states) | 1 visual TC | T2 | `@low` | VP-UI |
-| Business Rule bullet | 1 edge-case behavioral TC; `@manual` if unautomatable | T2 | `@normal` | VP-LOGIC |
-| Accessibility tab order | 1 tab-walking TC | T2 | `@low` | VP-UI |
-| Notes bullet | classify per content (page title→VP-UI, env→`@manual`, edge→relevant section) | T2 | `@low` | varies |
-
-#### Table 2 — `test-viewpoint.md` → TC Mapping Contract
-
-| Section / format | TC requirement |
-|---|---|
-| `## Edge Cases` (bulleted) | classify per spec Notes |
-| `## Known Issues` (bulleted) | `@manual` TCs with bug ID comment |
-| `## Design Decisions` | behavioral TCs |
-| `## UI Patterns Identified` | confirm `sungen-viewpoint` pattern checklists |
-| `## Priority Viewpoints` | adjust Tier-2 emphasis |
-| `## Element Overview` (table) | 1 presence/state TC per row (T2, `@low`) |
-| `## State Transitions` (table) | 1 TC per valid transition + key blocked |
-| Free-form notes | re-read with heading as context |
-
-### Figma supplement (`spec_figma.md`)
-
-When `requirements/spec_figma.md` is present alongside `spec.md`, treat it as a **secondary input** with these rules:
-
-- **Never override `spec.md`**: `spec.md` is authoritative for all business rules, field constraints, and behavior. `spec_figma.md` only supplements with visual/text data that `spec.md` may lack.
-- **`## Text Inventory` → literal strings**: use text label values from this section verbatim in `test-data.yaml` (button labels, input placeholders, error messages shown in Figma). Do not paraphrase or invent alternatives.
-- **`## Interaction States` → state coverage checkpoints**: use the listed variants (e.g., empty, loading, error, success) as a checklist for state-coverage scenarios. Only generate scenarios for states that are either (a) confirmed in both `spec.md` and `spec_figma.md`, or (b) explicitly documented in one source without contradiction from the other.
-- **Flag disagreements**: if a field name, label, or behavior in `spec_figma.md` contradicts `spec.md`, insert an HTML comment at the top of the `.feature` file:
-  ```gherkin
-  <!-- FIGMA-SPEC CONFLICT: <brief description> — using spec.md value -->
-  ```
-  Then proceed using the `spec.md` value.
-
-## Screen Input Sources
-
-**Auto-detect** — the parent command (`create-test`) resolves visual sources before invoking this skill. By the time generation starts, the available sources are already determined:
-- `spec.md` — primary, always read if present
-- `spec_figma.md` — Figma supplement, read if present (PAT flow already completed)
-- `ui/*.png` — visual context, read if present
-- `test-viewpoint.md` — edge cases and known issues, read if present
+## Update Mode
 
-**IMPORTANT:** If `spec_figma.md` exists, do NOT call any `mcp__figma__*` tool. The PAT flow is complete — just read the file.
+When `.feature` already has scenarios, summarize and ask:
+1. **Add new sections** — append Tier 1 scenarios, continue numbering
+2. **Add viewpoints** — expand existing sections with Tier 2 scenarios
+3. **Replace all** — overwrite with fresh Tier 1 generation
 
-**Single screen focus**: one URL = one screen. Don't explore sibling paths. Modals on same page = part of this screen.
+For append: read highest `VP-<CAT>-<NNN>`, continue from next number. Never modify existing scenarios.
 
-### Capture Real Data
+> **IDs are immutable & append-only.** The dashboard tracks each test case by its ID (namespaced at export as `<SCREEN>-<CAT>-<NNN>`, e.g. `LOGIN-SEC-001`). When updating a `.feature`:
+> - **Never renumber** existing scenarios — even when earlier ones were deleted. Renumbering changes the dashboard key and loses that test's pass/fail history.
+> - **New scenarios** take the next unused number per `VP-<CAT>` group (continue from the highest; do NOT fill gaps left by deletions).
+> - **Deleting** a scenario retires its number permanently — never reuse it.
+> - Editing a scenario's title text or steps is fine — the ID stays the same.
 
-When exploring live page or reading Figma designs, actively collect to hardcode in `test-data.yaml`:
-- User names, option labels, card content, error messages, counter keywords
-- **Hardcode first, @manual last** — stale data that fails fast > @manual that never runs
+---
 
-## Section Identification
+## Input Sources
 
-Identify sections from page patterns. Use `sungen-viewpoint` skill for the 10 pattern types (Form & Inputs, Data Table, Create/Add, Update/Edit, Delete, Search, Filter, Pagination, Modal/Dialog, List/Card). Present sections and ask user which to focus on.
+Auto-detected by `create-test` before invoking this skill:
+- `spec.md` — primary, always read if present
+- `spec_figma.md` — Figma supplement (PAT flow already done — just read the file)
+- `ui/*.png` — visual context
+- `test-viewpoint.md` — test conditions checklist; scan entirely regardless of format.
+  Format varies across projects: hierarchical table (Level 1–4 columns), flat checklist,
+  prose, or mixed. Regardless of format:
+  1. Scan entire file top to bottom.
+  2. Each row / bullet / item = 1 viewpoint → add to `Viewpoint items` in Coverage Map.
+  3. Do NOT pre-classify into buckets before scanning — classify only when
+     writing the scenario.
+- `qa/context.md` — project-wide context set by the QA lead. Read ONCE before building the Coverage Map; apply to every screen. Extraction rules:
+  - **Roles** → for each role in the table: add to the `@auth:X` tag pool; generate a VP-SEC blocked-access scenario for every role boundary relevant to this screen.
+  - **Testing strategy → Focus areas** → if `security` listed: VP-SEC is mandatory Tier 1 for every free-text input regardless of spec risk level; if `ui` not listed: all VP-UI scenarios move to Tier 2 minimum.
+  - **Testing strategy → Mandatory coverage** → each line is a hard override applied to this screen regardless of spec risk; document in `Context constraints` of the Coverage Map.
+  - **Testing strategy → Deprioritize/skip** → record in `Context constraints`; suppress those VP categories from Tier 1 generation.
+  - **Global business rules** → add each to the `Business rules` section tagged `[G]` (e.g. `[G1 – soft-delete only]`); treat as `HIGH` risk unless stated otherwise.
+  - **Error patterns** → use as fallback only when `spec.md` does not give exact error text; never override spec-specified messages.
+  - If `qa/context.md` is absent: proceed without it — no impact on the generation flow.
+
+**Single screen focus**: one URL = one screen. Modals on same page = part of this screen.
+This means: do not test other screens' UI layout or navigation. It does NOT mean skip documenting business outcomes that your screen's actions cause on other surfaces. Those cross-surface outcomes must appear in the Coverage Map and be covered by at least `@manual` scenarios.
+
+**Capture real data** from live page or Figma: option labels, error messages, counter keywords. Hardcode in `test-data.yaml` — stale data that fails fast beats `@manual` that never runs.
 
-## Test Generation Strategy
+---
 
-### Step 1 — Spec-first extraction (always do this first)
+## Generation Workflow
 
-Before applying any checklist, extract test conditions from `spec.md` (and `test-viewpoint.md` if present):
-- **Validation rules**: field constraints, error messages, required/optional
-- **Business rules**: eligibility, calculation logic, permission-based behavior
-- **State lifecycle**: allowed transitions, blocked transitions
-- **Edge cases**: boundary values, empty states, concurrent conditions
+### Step 1 — Orient: patterns + risk
 
-These spec-extracted conditions drive **which scenarios exist** — `sungen-viewpoint` only supplements with generic web UI coverage that spec doesn't explicitly state.
+Identify core user tasks. Categorize page sections by UI pattern group using `sungen-viewpoint`:
+data entry (A), data manipulation (B), data exploration (C), display/feedback (D), identity (E).
 
-### Step 2 — Apply test design techniques
+Proceed directly to Step 2. Pause to ask the user only when section priority is genuinely ambiguous from spec (e.g. multiple top-level forms without business context).
 
-Apply `sungen-test-design-techniques` to spec-extracted conditions:
+### Step 2 — Build Coverage Map
 
-| Technique | Apply when spec mentions |
-|---|---|
-| EP | Valid/invalid ranges, categories → **one** scenario per class, not per value |
-| BVA | Numeric range, string length → `min-1`, `min`, `max`, `max+1` (compact 4-point default) |
-| Decision Table | 2+ dependent conditions → one scenario per combination (cap at distinct outcomes if >3 conditions) |
-| State Transition | Entity lifecycle → one scenario per valid transition + key invalid transitions |
+Read `spec.md` fully, then extract into a Coverage Map **before writing any scenario**. Nothing is skipped at this stage — risk only affects depth in Step 3.
 
-### Step 3 — Fill coverage gaps with viewpoint checklists
+**Risk tags:** HIGH = complex business rules, cascading fields, multi-step state changes, auth/integration. LOW = display-only, static labels, read-only fields.
 
-Use `sungen-viewpoint` skill for per-pattern checklists across 4 viewpoints: UI/UX, Data & Validate, Logic, Security.
+```
+Context constraints: [populated from qa/context.md before writing any scenario]
+                     roles: [list roles, e.g. admin / manager / staff]
+                     strategy: [active overrides, e.g. "VP-SEC mandatory T1", "VP-UI → T2 only"]
+                     global rules: [G1 – ...] → also appear in Business rules below tagged [G]
+                     → leave empty if qa/context.md is absent or has no entries applicable to this screen
+User journeys:       [J1 – ...], [J2 – ...]
+Validation rules:    [V1 – field → "exact error text"], [V2 – ...]
+Business rules:      [B1 HIGH – ...], [B2 LOW – ...]
+Secondary behaviors: [SB1 – tiebreaker: when X identical → sort by Y DESC]
+                     [SB2 – default state when no condition applies: ...]
+                     → capture "otherwise", "when tied", "secondary sort", "fallback" rules here
+States:              [StateA → StateB], [blocked: StateC → StateA]
+Security:            [S1 HIGH – OAuth/SSO flow], [S2 HIGH – free-text inputs → XSS + SQL injection]
+Concurrency risks:   [C1 – spec/viewpoint mentions multi-tab, concurrent edit, or simultaneous action]
+                     → leave empty if neither spec nor viewpoint mentions concurrency
+Display surfaces:    [Surface1 – /url, auth:role], [Surface2 – /url, auth:user]  ← list every surface spec mentions as output
+Cross-surface rules: [B1 – action on /admin → outcome on /user (3-condition AND logic)]  ← mandatory if Display surfaces exist
+Inclusive bounds:    [start_at <= now → boundary: start_at=now must display], [end_at >= now → boundary: end_at=now must display]
+Viewpoint items:     [TV-01 – <exact wording from test-viewpoint row 1>]
+                     [TV-02 – <exact wording from test-viewpoint row 2>]
+                     → one entry per row/bullet in test-viewpoint.md, regardless of format
+                     → leave empty if no test-viewpoint.md present
+Spec gaps:           [G1 – behavior undocumented → verify with dev]
+```
 
-**Tier-aware gap filling:**
-- **Tier 1 (first run)**: only add `@high` items from the checklists. Skip `@normal`/`@low` items. After generation, apply the **Lightweight Guard** to verify coverage.
-- **Tier 2 (expand run)**: add `@normal` + `@low` scenarios — UI presence, optional validation, edge cases, cosmetic checks, keyboard nav, hover effects.
-- **Tier 3 (deep run)**: do NOT use viewpoint checklists. Instead, re-apply test design techniques with deeper analysis:
-  - **BVA**: expand from 4-point to 6-point (`min-1`, `min`, `min+1`, `max-1`, `max`, `max+1`) + typical mid-range value
-  - **Decision Table**: enumerate combinations previously capped — cover remaining outcome rows
-  - **Cross-field**: identify field dependencies from spec, generate one scenario per dependency
-  - **Negative inputs**: add security-oriented inputs (SQL `' OR 1=1`, XSS `<script>`, special chars `<>&"'`, max+100 length)
-  - **Race conditions**: double-click submit, browser back after POST, concurrent edit by two users
-- **Full (all-at-once)**: apply Tier 1 + 2 + 3 rules in a single pass. Use all viewpoint checklists and all test design technique depths. Mark sections with all three tier comments.
+**Example — login screen (2 sections, 5 validation rules):**
+```
+User journeys:       [J1 – account login with valid credentials]
+Validation rules:    [V1 – empty email → "Invalid email address"],
+                     [V2 – short password → "Password must be at least 6 characters"],
+                     [V3 – invalid format → "Invalid email address"],
+                     [V4 – wrong credentials → "Invalid email or password"]
+Business rules:      [B1 HIGH – toggle is same-page state, not route change]
+States:              [Default → Account form], [Account form → Google login],
+                     [Account form → Loading → Success/Error]
+Security:            [S1 HIGH – free-text email/password → XSS + SQL injection]
+Display surfaces:    [Login page – /login, no-auth]  ← same surface, no cross-surface rules needed
+Cross-surface rules: (none)
+Inclusive bounds:    (none)
+Spec gaps:           [G1 – auth error on 401 unconfirmed on live]
+
+Tier 1 output:    VP-LOGIC-001 (toggle reveals form), VP-LOGIC-002 (restore Google state),
+                  VP-LOGIC-003 (login success → redirect), VP-VAL-001 (empty fields),
+                  VP-VAL-002 (invalid format), VP-VAL-003 (short password),
+                  VP-VAL-004 (wrong credentials), VP-SEC-001 (XSS), VP-SEC-002 (SQL injection)
+```
 
-**Validation rule**: capture actual error messages from live page or spec.md. Use `User see {{error_var}}` — never assert just "is visible".
+**Example — admin notice management screen (cross-surface + inclusive bounds):**
+```
+User journeys:       [J1 – create notice], [J2 – edit notice], [J3 – toggle active], [J4 – delete notice]
+Validation rules:    [V1 – title empty → "必須項目です"], [V2 – end_at <= start_at → "終了日時は開始日時より後に…"],
+                     [V3 – title > 255 chars → "255文字以内で入力してください"]
+Business rules:      [B1 CRITICAL – notice displays on user-facing portal only when: is_active=ON AND start_at<=now AND end_at>=now],
+                     [B2 HIGH – is_active=ON by default on create; not on form],
+                     [B3 HIGH – toggle not blocked by date range]
+States:              [Scheduled → Live → Expired], [any → OFF via toggle]
+Security:            [S1 HIGH – free-text title/content → XSS + SQL injection], [S2 HIGH – admin-only, non-admin blocked]
+Display surfaces:    [Admin panel – /admin/notices, auth:admin], [User portal – /user-facing-url, auth:user]  ← TWO surfaces
+Cross-surface rules: [B1 – admin creates/toggles → user portal shows/hides banner; 8-combination decision table]
+Inclusive bounds:    [start_at <= now → boundary: start_at=now must display], [end_at >= now → boundary: end_at=now must display]
+Spec gaps:           [G1 – exact content max length unconfirmed]
+
+Tier 1 output (admin surface):    VP-LOGIC-001 to VP-LOGIC-013, VP-VAL-001 to VP-VAL-007, VP-SEC-001 to VP-SEC-003
+Cross-surface output (user portal): VP-LOGIC-CS-001 @manual (M-01: all 3 ON → display),
+                                    VP-LOGIC-CS-002 @manual (M-05: is_active=OFF → no display),
+                                    VP-LOGIC-CS-003 @manual (M-03: start_at future → no display),
+                                    VP-LOGIC-CS-004 @manual (M-02: end_at past → no display),
+                                    VP-LOGIC-CS-005 @manual (boundary: start_at=now → display),
+                                    VP-LOGIC-CS-006 @manual (boundary: end_at=now → display)
+```
 
-## Priority Tags (auto-assign)
+**❌ Bad Coverage Map — silently misses validation rules AND cross-surface outcomes:**
+```
+User journeys:    [J1 – create notice], [J2 – edit notice]
+Business rules:   [B1 – display logic: is_active + date range]
+Security:         [S1 – admin only]
+```
+→ Output misses VP-VAL-* entirely (validation rules not listed with exact messages).
+→ Output misses user portal scenarios entirely (no `Display surfaces` or `Cross-surface rules` field).
+→ Output misses boundary tests for `start_at <= now`, `end_at >= now` (no `Inclusive bounds` field).
+→ Root cause: Coverage Map only captured admin CRUD journeys; spec section on "display flow" and "user-facing surface" was not scanned into the map.
 
-Every scenario **MUST** have exactly one priority tag. Add it before the scenario line (after `@extend:` if present).
+**✅ Good** — see admin notice example above: `Display surfaces` lists every URL spec mentions as output, `Cross-surface rules` maps each admin action to its user-facing outcome, `Inclusive bounds` flags every `<=`/`>=` for BVA. Every item maps to a VP-ID in `Tier 1 output`.
 
-**Rule: look at what the WHEN step does and what THEN asserts — that determines the tag.**
+#### Tier 1 guard — minimum before writing scenarios
 
-| Tag | Scenario type | Examples |
+| Spec section | Minimum requirement | Tag |
 |---|---|---|
-| `@high` | Auth actions | login, logout, protected page redirect |
-| `@high` | CRUD happy path | create / update / delete → success message or redirect |
-| `@high` | Security gate | unauthenticated access → redirected to login |
-| `@high` | Primary business flow | core flow step completes successfully |
-| `@normal` | Input validation | invalid / empty input → error message shown |
-| `@normal` | Boundary / format | email format, length limit, numeric range |
-| `@normal` | Secondary features | search, filter, sort, pagination, notification |
-| `@normal` | Non-primary state transition | cancel, undo, back |
-| `@low` | Element presence | component / section is visible |
-| `@low` | Text content | label, placeholder, tooltip, warning text |
-| `@low` | Visual / cosmetic | alignment, icon, empty state, hover style |
+| Required field | 1 required-error TC per field | `@high` |
+| Validation rule | 1 exact-message TC per rule | `@high` |
+| Business rule | 1 behavioral TC per rule | `@high` |
+| **Secondary behavior / tiebreaker** | **1 TC per tiebreaker or fallback rule in `Secondary behaviors`** | **`@high`** |
+| Auth / OAuth / permissions | 1 VP-SEC TC | `@high` |
+| Free-text input | 1 XSS TC **and** 1 SQL injection TC (separate) | `@high` |
+| **Free-text LIKE / partial-match field** | **1 field-level SQL TC + 1 API-level SQL `@manual` TC** | **`@high`** |
+| Lifecycle states | 1 key state transition TC | `@high` |
+| Public page | 1 accessible-without-auth TC | `@high` |
+| **Cross-surface business rule** | **1 `@high @manual` TC per affected surface per rule** — even if not automated today | **`@high`** |
+| **Inclusive boundary condition** (`<=`, `>=`) | **4 TCs per range: `min-1` (fail), `min` (pass), `max` (pass), `max+1` (fail)** — never skip the exact boundary point | **`@high`** |
+| **Concurrency risk (from `Concurrency risks`)** | **1 `@manual` TC per risk — `@normal` unless data integrity at risk → `@high`** | **`@normal`** |
+| States row (Default / Loading / Error / Success) | 1 visual state TC per named state — separate from lifecycle transition TC | `@normal` |
+| Actions secondary (cancel, reset, export) | 1 behavior TC per secondary action | `@normal` |
 
-**`@steps:` scenarios** do NOT get a priority tag (they are setup blocks, not test cases).
+> **Completeness check** — after generating all scenarios, scan Coverage Map line by line.
+> Every spec item must map to at least one scenario. Every `Viewpoint items` entry must be mapped to a VP-ID or marked `[covered: VP-ID]`. Do NOT silently skip either source.
+> Specifically verify: `Display surfaces` each have ≥1 scenario; `Inclusive bounds` each have a boundary-point TC.
 
-### Priority assignment — disambiguation tie-breaker
+#### Tier 2 strategy
 
-When in doubt between `@low` and `@normal`, apply this rule:
+Walk `spec.md` top-to-bottom and apply `sungen-viewpoint` Tier 2 checklist for each identified pattern. Depth by risk: high-risk section → all items; low-risk → presence checks only. Skip items already covered by Tier 1.
+For HIGH-tagged sections: use the same depth as Step 3 (full BVA + Decision Table) when generating new Tier 2 VP-VAL items not already covered by Step 3. For LOW-tagged sections: EP valid + EP invalid only — skip BVA and Decision Table. Do NOT re-generate scenarios already created in Step 3.
 
-| Pattern | Tag |
-|---|---|
-| 0 When steps + Then asserts only `User see [T] type` (presence) | `@low` (always) |
-| 0 When steps + Then asserts `User see [T] type with {{value}}` (content) | `@low` (label/text) |
-| When steps but no state change (e.g., navigation only) | `@low` |
-| When provides invalid input + Then asserts validation error | `@normal` |
-| When triggers business logic + Then asserts state change | `@high` or `@normal` per heuristics |
-
-**Example:** `Then User see [Email] field` (no When) → `@low`. `When User fill ... And User click ... Then User see [Error]` → `@normal`.
+**When `test-viewpoint.md` is present — mandatory line-by-line scan:**
+Every item in `test-viewpoint.md` must appear in `Viewpoint items` of the Coverage Map (done in Step 2). In Tier 2, walk `Viewpoint items` line by line:
+- Item already covered by Tier 1 → mark `[covered: VP-ID]`, skip.
+- Item automatable → generate `@normal` scenario.
+- Item requires DB setup / network manipulation → `@normal @manual`.
+- Item marked as known bug → `@manual` with comment `# Known issue: <ID>`.
 
-## SPA Wait-For Steps
+> **Viewpoint completeness check** — after Tier 2, every `Viewpoint items`
+> entry must be mapped to a VP-ID or marked `[covered: VP-ID]`.
+> If any item has neither → generate missing scenario before finishing.
+> Do NOT silently skip viewpoint items because they seem redundant or
+> hard to automate.
 
-```gherkin
-Given User is on [Screen] page
-And User wait for [Page Title] heading is visible
-```
+### Step 3 — Apply test design techniques
 
-## Cleanup & Hooks
+Delegate to `sungen-test-design-techniques` for technique selection and depth.
+Risk level from Coverage Map drives depth: HIGH section → full BVA / Decision Table; LOW section → EP valid+invalid only.
 
-### Auto-assign `@cleanup:*` tags based on screen sections
+**BVA constraint:** Use compact 4-point mode only (min-1, min, max, max+1). Do not apply Full 6-point mode.
 
-After identifying screen sections, add appropriate `@cleanup:*` feature-level tags. These activate base.ts fixtures that auto-clean state between tests.
+### Step 4 — Supplement with viewpoint checklists
 
-| Screen has | Add tag | Why |
-|---|---|---|
-| Modal / Dialog / Drawer | `@cleanup:overlay` | Dismiss leftover overlays between tests |
-| Form & Inputs / Search / Filter | `@cleanup:forms` | Clear form fields, reset selects |
-| Long scrollable content | `@cleanup:scroll` | Scroll to top for consistent assertions |
-| Auth tokens / session data in tests | `@cleanup:storage` | Clear sessionStorage |
-| CI/CD or debug-heavy screens | `@screenshot:on-failure` | Auto-capture screenshot on test failure |
+Use `sungen-viewpoint` for defect-prone patterns spec never documents. Skip items already covered by spec-driven scenarios.
 
-**Always add `@cleanup:overlay`** if ANY section opens a dialog (Create/Add, Update/Edit, Delete confirmation). Most CRUD screens need it.
+> **XSS and SQL injection** are generated at Tier 1 guard (Step 2). Skip them when applying `sungen-viewpoint` Shared Checks — do not generate again.
 
-**Always add `@cleanup:forms`** if the screen has inline search, filter dropdowns, or editable forms that persist between tests.
+#### 4a. Shared Checks — generate ONCE per screen
 
-### When to add `@afterEach` hook scenario
+Apply the **Shared Checks table in `sungen-viewpoint`** (single source). Generate each at most once per screen, not per pattern. Since XSS and SQL injection are already covered at the Tier 1 guard (Step 2, above), at this step generate only the remaining ones that fit the screen: **Loading State** (any async fetch), **Empty State** (any list/table/card that can return 0 records), **URL Manipulation** (URL params affecting displayed data).
 
-Only when `@cleanup:*` tags aren't enough — feature-specific cleanup logic:
-- Reset a dropdown filter to default value (not just clear)
-- Navigate away from a sub-tab back to the main tab
-- Close a specific sidebar panel
+#### 4b. Pattern Tier 1 / Tier 2
 
-```gherkin
-@afterEach
-Scenario: Reset filters to default
-  When User select [Status Filter] dropdown with {{default_status}}
-```
+**Gap check rule — Step 4b fills gaps from Step 3, not a new generation source:**
+- **VP-VAL BVA/EP items**: skip if Step 3 already generated scenarios for that field. Generate only if Step 3 missed the field entirely.
+- **VP-LOGIC, VP-UI, VP-SEC items**: generate normally — Step 3 does not cover these.
 
-### `@beforeAll` / `@afterAll` — optional, low priority
+- **Tier 1**: all items from `#### Tier 1 — @high` → VP-LOGIC, VP-VAL, VP-SEC
+- **Tier 2**: items from `#### Tier 2 — @normal + @low` → VP-UI
 
-For one-time setup/teardown. Most screens don't need these.
+Risk weighting: high-risk section → all Tier 1 items. Low-risk (e.g. read-only table) → only clearly applicable items.
 
-### `@parallel` — when tests need independent browser state
+#### 4c. Cross-pattern interactions — where spec-invisible bugs live
 
-Add `@parallel` at feature level when:
+For every pair of patterns present on the screen, walk the **⚡ Cross-pattern interactions** list in each `sungen-viewpoint` group file (single source). Never-miss pairs:
+- **Create / Update / Delete × Data Table** — new record missing or count not updated; row shows stale data; last-record delete → blank page.
+- **Search / Filter × Pagination** — results don't reset to page 1.
+- **Form × Modal/Dialog** — modal stays open on success / data wiped on failure.
+- **Import × Data Table** — table not refreshed / count wrong after import.
+- **Sort × Data Table** — all cells in a row must reorder together (data must not shift to wrong columns).
+- **Filter (≥2 active)** — generate 1 scenario with all filters active simultaneously to verify AND logic.
 
-1. **Multiple auth groups** (required) — e.g., `@auth:user` + `@no-auth` scenarios. Serial mode uses one shared context and cannot mix auth roles. Compiler will error without this tag.
-2. **Validation-heavy features** (recommended) — each scenario fills forms with different invalid data and needs a clean form. Serial shared page keeps previous test's input.
+Cross-pattern: `@high` by default.
 
-Serial (default) is best for: CRUD flows, sequential user journeys, UI checks on the same page.
+**Assert values, not existence.** Never bare "is visible". Capture exact error messages into test-data.yaml.
 
-```gherkin
-@parallel @auth:user
-@cleanup:forms
-Feature: kudos Screen
+---
 
-  @high
-  Scenario: Send kudos
-    ...
+## Priority Tags
 
-  @high @no-auth
-  Scenario: Unauthenticated user is redirected
-    ...
-```
+Every scenario **MUST** have exactly one priority tag. Assign by user impact per the **"Assign priority by user impact"** table in `sungen-gherkin-syntax`; override only when context differs.
 
-## Output Format
+Quick fallback: auth / CRUD / security / required-field / unique-constraint → `@high`; format validation / standard-range boundary / search / filter / sort → `@normal`; presence / label / placeholder / cosmetic → `@low`. (Inclusive-operator or critical boundary → `@high`.)
 
-**Feature file** — `qa/screens/<screen>/features/<screen>.feature`
+---
 
-`Background` is valid for simple shared setup (navigate to page). Use `@steps`/`@extend` for complex flows with scope (dialog, frame).
+## SPA Wait-For Steps
 
 ```gherkin
-@auth:role
-@cleanup:overlay
-@cleanup:forms
-Feature: <Screen> Screen
+Given User is on [Screen] page
+And User wait for [Page Title] heading is visible
+```
 
-  Background:
-    Given User is on [Screen] page
+---
 
-  # Shared setup — NO priority tag on @steps
-  @steps:open_form
-  Scenario: Open form
-    When User click [Create] button
-    Then User see [Form] dialog
+## Cleanup & Hooks
 
-  # --- Section: Create User Form (Tier 1: @high) ---
+Add cleanup tags per the `sungen-gherkin-syntax` Cleanup table. Key rules:
+- **Always `@cleanup:overlay`** if ANY section opens a dialog; **always `@cleanup:forms`** if the screen has inline search, filter, or editable forms.
+- **`@parallel`** is required when mixing auth groups (`@auth:X` + `@no-auth`); recommended for validation-heavy features needing a clean form state per scenario.
+- **`@afterEach`** hook only when `@cleanup:*` tags aren't enough (feature-specific reset logic).
 
-  @high @extend:open_form
-  Scenario: VP-LOGIC-001 Submit form with valid data creates record
-    Given User is on [Form] dialog
-    When User fill [Name] field with {{valid_name}}
-    And User click [Submit] button
-    Then User see {{success_message}} message
+---
 
-  @high @extend:open_form
-  Scenario: VP-VAL-001 Submit with all empty fields shows errors
-    Given User is on [Form] dialog
-    When User click [Submit] button
-    Then User see [Name error] message with {{name_required_error}}
+## Output Format
 
-  # --- Section: User Table (Tier 1: @high) ---
+**Files:** `qa/screens/<screen>/features/<screen>.feature` + `qa/screens/<screen>/test-data/<screen>.yaml`
 
-  @high
-  Scenario: VP-VAL-010 Table displays correct data
-    Then User see [Users] table match data:
-      | Name       | Email        |
-      | {{name_1}} | {{email_1}}  |
+Use step patterns and element types from `sungen-gherkin-syntax`.
+**Naming**: `VP-<CATEGORY>-<NNN>`. Scenario name must use the **same element type** as the steps.
 
-  @high
-  Scenario: VP-SEC-010 Unauthorized user cannot access page
-    Given User is not logged in
-    When User navigate to [Screen] page
-    Then User is on [Login] page
-```
+**Test data** — grouped by section, loaded at runtime:
 
-**Tier 2 (expand run)** appends sections with `# --- Section: X (Tier 2: @normal + @low) ---` comments. Adds UI field presence, hover states, tooltips, empty states.
+```yaml
+# login.yaml (base)
+valid_email: admin@dev.example.com
+valid_password: DevPass123
 
-**Tier 3 (deep run)** appends sections with `# --- Section: X (Tier 3: deep) ---` comments. Adds extra BVA boundaries, cross-field validation, negative/destructive inputs, concurrent/race conditions.
+# login.staging.yaml (override)
+valid_email: admin@staging.example.com
+valid_password: StagingPass456
+```
 
-### When to use DataTable vs Row Scope
+**DataTable vs Row Scope:**
 
 | Pattern | Use when |
 |---|---|
 | `table match data:` + DataTable | Verifying **multiple rows** exist with expected values |
-| `row in [Table] table with {{v}}` + `column with {{v}}` | Checking **single row** details or **acting** on a row (click, edit) |
+| `row in [Table] table with {{v}}` + `column with {{v}}` | Single row detail or action on a row |
 
-**Naming**: `VP-<CATEGORY>-<NNN>` prefix. Scenario name must use the **same element type** as the steps — e.g., if the step uses `dialog`, write "dialog opens" not "modal opens".
-
-**Test data** — `qa/screens/<screen>/test-data/<screen>.yaml`, grouped by section. Data is loaded **at runtime** — keys become runtime lookups, not hardcoded strings. The same compiled test works across environments.
-
-**Environment-specific data**: create `<screen>.<env>.yaml` alongside the base file with only the keys that change. Users run `SUNGEN_ENV=staging npx playwright test` to merge overrides.
+---
 
-**i18n / multilingual**: use the same `SUNGEN_ENV` overlay for locale variants — e.g., `login.vi.yaml`, `login.staging-ja.yaml`. Include `lbl_*` / `msg_*` keys for selector `{{variable}}` references (see `sungen-selector-keys` § i18n). One feature file + one selector file works across all locales.
+## Worked Example — spec → Coverage Map → output
 
-## Flow Test Generation
+A minimal end-to-end pass. Use this to calibrate output: every Coverage Map line below maps to exactly one scenario, and every `{{var}}` exists in the YAML.
 
-When generating tests for a **flow** (`qa/flows/<name>/`), adapt the strategy:
+**① Input — `spec.md` (excerpt):**
+```
+## Coupon Form
+- Code: required, free text, max 20 chars, must be unique.
+- Discount %: required, integer 1–100 inclusive.
+- Submit creates a coupon; it appears at the top of the Coupon List.
+- Only authenticated admins can create coupons.
+```
 
-### Structure
+**② Coverage Map (Step 2 output):**
+```
+User journeys:       [J1 – admin creates coupon → appears top of list]
+Validation rules:    [V1 – code empty → "Code is required"],
+                     [V2 – code > 20 chars → "Code must be 20 characters or less"],
+                     [V3 – duplicate code → "Code already exists"],
+                     [V4 – discount empty → "Discount is required"]
+Business rules:      [B1 HIGH – new coupon sorts to top of list]
+States:              (none — no lifecycle)
+Security:            [S1 HIGH – free-text code → XSS + SQL injection], [S2 HIGH – admin-only]
+Display surfaces:    [Coupon admin – /admin/coupons, auth:admin]  ← single surface
+Cross-surface rules: (none)
+Inclusive bounds:    [discount 1–100 inclusive → BVA: 0, 1, 100, 101]
+Spec gaps:           (none)
+
+Tier 1 output:  VP-LOGIC-001 (create → top of list), VP-VAL-001 (code empty),
+                VP-VAL-002 (code > 20), VP-VAL-003 (duplicate code), VP-VAL-004 (discount empty),
+                VP-VAL-005 (discount=0 reject), VP-VAL-006 (discount=1 accept),
+                VP-VAL-007 (discount=100 accept), VP-VAL-008 (discount=101 reject),
+                VP-SEC-001 (XSS), VP-SEC-002 (SQL injection), VP-SEC-003 (non-admin blocked)
+```
+> Note how `Inclusive bounds` line forces 4 BVA scenarios (0/1/100/101), not just "valid + invalid".
 
-- **Background** — starting page only: `Given User is on [Login] page`
-- **Scenarios** — each phase of the E2E journey as a separate scenario
-- **Selector refs** — use `[Screen:Element]` namespace format (see `sungen-gherkin-syntax`)
-- **Test data** — namespace by phase: `login.email`, `submission.nominee`
-- **Feature tag** — `@flow` required at feature level
+**③ Output — `coupons.feature` (excerpt, 4 of 12 scenarios):**
+```gherkin
+@parallel @auth:admin
+@cleanup:overlay
+@cleanup:forms
+Feature: Coupons Screen
 
-### Flow vs Screen Differences
+  Background:
+    Given User is on [Coupons] page
+
+  @steps:open_create_form
+  Scenario: Open create form
+    When User click [Create Coupon] button
+    Then User see [Create Coupon] dialog
+
+  # --- Section: Create Coupon (Tier 1) ---
+
+  @high @extend:open_create_form
+  Scenario: VP-LOGIC-001 Submit valid coupon adds it to top of list
+    Given User is on [Create Coupon] dialog
+    When User fill [Code] field with {{valid_coupon.code}}
+    And User fill [Discount] field with {{valid_coupon.discount}}
+    And User click [Save] button
+    Then User see [Create Coupon] dialog is hidden
+    And User see [Coupon List] row in [Coupon List] table with {{valid_coupon.code}}
+
+  @high @extend:open_create_form
+  Scenario: VP-VAL-005 Discount of 0 is rejected (boundary min-1)
+    Given User is on [Create Coupon] dialog
+    When User fill [Code] field with {{valid_coupon.code}}
+    And User fill [Discount] field with {{discount_zero}}
+    And User click [Save] button
+    Then User see [Discount Error] message with {{error.discount_range}}
+
+  @high @extend:open_create_form
+  Scenario: VP-VAL-006 Discount of 1 is accepted (boundary min)
+    Given User is on [Create Coupon] dialog
+    When User fill [Code] field with {{valid_coupon.code}}
+    And User fill [Discount] field with {{discount_min}}
+    And User click [Save] button
+    Then User see [Create Coupon] dialog is hidden
 
-| Aspect | Screen | Flow |
-|---|---|---|
-| Section focus | UI patterns per section | Journey phases across screens |
-| Viewpoints | VP-UI, VP-VAL, VP-LOGIC, VP-SEC per section | VP-LOGIC (flow transitions), VP-SEC (auth persistence), VP-VAL (cross-screen data) |
-| Tier 1 focus | Happy path + required validation per section | Happy path through entire flow + auth + key error recovery |
-| Background | Navigate to screen | Navigate to starting page |
+  @high @no-auth
+  Scenario: VP-SEC-003 Unauthenticated user is redirected to login
+    Then User see [Login] page
+```
 
-### Flow-specific scenarios by tier
+**④ Output — `coupons.yaml` (excerpt):**
+```yaml
+valid_coupon:
+  code: "SAVE-{{$uuid}}"
+  discount: "20"
+discount_zero: "0"      # boundary min-1 (reject)
+discount_min: "1"       # boundary min (accept)
+discount_max: "100"     # boundary max (accept)
+discount_over: "101"    # boundary max+1 (reject)
+error:
+  discount_range: "Discount must be between 1 and 100"
+```
 
-| Category | Tier | Examples |
-|---|---|---|
-| **Happy path** | T1 | Complete flow end-to-end with valid data |
-| **Auth persistence** | T1 | Auth state maintained across screen transitions |
-| **Error recovery** | T1 | Invalid input mid-flow → fix → continue |
-| **Incomplete flow** | T2 | User abandons at each phase → state cleanup |
-| **Cross-screen data** | T2 | Data entered on screen A visible on screen B |
-| **Screen transition edges** | T2 | Back button, refresh, deep link mid-flow |
-| **UI state across screens** | T2 | Breadcrumb, progress indicator, nav state |
-| **Negative inputs mid-flow** | T3 | XSS/SQL in cross-screen fields, special chars |
-| **Concurrent flow** | T3 | Two tabs same flow, session expiry mid-flow |
-| **Cross-screen validation** | T3 | Field dependency across screens, cascading errors |
-
-### Flow Lightweight Guard (Tier 1)
-
-> After generating Tier 1 flow scenarios, verify these checks — if any are missing, add them:
-
-| Flow requirement | Minimum TC | Tag |
-|---|---|---|
-| Complete flow end-to-end with valid data | At least 1 happy path scenario | `@high` |
-| Auth state across screen transitions | At least 1 auth persistence check (if flow crosses auth) | `@high` |
-| Invalid input mid-flow → fix → continue | At least 1 error recovery scenario | `@high` |
+---
 
-### Flow Section Comments
+## Flow Test Generation
 
-Flow features use the same `# --- Section:` comment format, with phase names instead of UI sections:
+> **Auto-detect**: if path is `qa/flows/<name>/` → use this section. Skip Steps 1–4 above.
 
-```gherkin
-# --- Section: Login Phase (Tier 1: @high) ---
-# --- Section: Submission Phase (Tier 2: @normal + @low) ---
-```
+| Aspect | Screen | Flow |
+|---|---|---|
+| Section focus | UI patterns per section | Journey phases across screens |
+| Selector format | `[Element]` | `[Screen:Element]` (namespaced) |
+| Test data keys | `{{variable}}` | `{{phase.variable}}` |
+| Feature tag | `@auto` / `@smoke` etc. | `@flow` (required) |
+| Viewpoints | VP-UI/VAL/LOGIC/SEC per section | VP-LOGIC (transitions), VP-SEC (auth persistence), VP-VAL (cross-screen data) |
 
-Update Mode tier detection works identically — scan for tier markers in these comments.
+**Scenarios to generate:**
 
-### Output Format (Flow)
+| Category | What to test |
+|---|---|
+| Happy path | Complete flow end-to-end with valid data |
+| Auth persistence | Auth state maintained across screen transitions |
+| Error recovery | Invalid input mid-flow → fix → continue |
+| Cross-screen data | Data entered on screen A visible on screen B |
 
 ```gherkin
 @flow @auth:user
@@ -420,36 +486,30 @@ Feature: Award Submission Flow
   Background:
     Given User is on [Login] page
 
-  # --- Section: Login Phase (Tier 1: @high) ---
-
   @high
-  Scenario: User login successfully
+  Scenario: User logs in successfully
     When User fill [Login:Email] field with {{login.email}}
     And User fill [Login:Password] field with {{login.password}}
     And User click [Login:Submit] button
     Then User see [Dashboard] page
 
-  # --- Section: Submission Phase (Tier 1: @high) ---
-
   @high
-  Scenario: User navigates to awards and submits
-    Given User is on [Awards] page
+  Scenario: User submits nomination
+    When User click [Dashboard:Awards] link
+    Then User see [Awards] page
     When User fill [Awards:Nominee] field with {{submission.nominee}}
-    And User fill [Awards:Reason] field with {{submission.reason}}
     And User click [Awards:Submit] button
-    Then User see [Awards:Success Message] text with {{submission.success_message}}
+    Then User see {{success_message}} message
 ```
 
 ```yaml
-# test-data — namespaced by phase
+# flows/<name>/test-data/<name>.yaml
 login:
-  email: "user@example.com"
-  password: "Password123"
-
+  email: "admin@example.com"
+  password: "secret123"
 submission:
   nominee: "John Doe"
-  reason: "Outstanding contribution to the team"
-  success_message: "Award submitted successfully"
+success_message: "Award submitted successfully"
 ```
 
-**Do NOT generate**: `selectors.yaml` (created during run-test), Playwright code (sungen compiles).
+**Do NOT generate**: `selectors.yaml` (created during `run-test`), Playwright code (sungen compiles).