@sun-asterisk/sungen 3.2.2-beta.9 → 3.2.3-beta.3

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

@@ -1,184 +0,0 @@
----
-name: sungen-capture-mobile
-description: 'Capture a live mobile app screen via Appium MCP — locator tree + screenshot for visual context. Auto-loaded by create-test when the screen is @platform:mobile/android/ios.'
-user-invocable: false
----
-
-## Purpose
-
-Launch a mobile app on a device/emulator, capture **one locator tree** (`generate_locators`) and **one screenshot**, and save them as visual context for test generation. The mobile analogue of `sungen-capture-live` — same job, Appium MCP instead of Playwright MCP.
-
-Use when the target is a native/Flutter/React-Native app (`@platform:android` or `@platform:ios`) running on a connected device or emulator.
-
----
-
-## Prerequisites
-
-- `appium-mcp` connected (see `/mcp`). It runs Appium **embedded** — no separate server needed.
-- A device/emulator booted: `adb devices` shows one for Android; a Simulator for iOS.
-- The app **installed** on the device (`adb install -r <app>.apk` for Android).
-- The screen's `Path:` (in `<screen>/features/*.feature` or `spec.md`) gives the app entry as
-  `<appPackage>/<appActivity>` (Android) or bundleId (iOS), e.g. `com.kngroup.media.converter/.MainActivity`.
-
----
-
-## Steps
-
-### 1. Resolve target app + entry
-
-Resolve in this order:
-1. `Path:` line in the feature / `App ID` in `spec.md` → split into `appPackage` + `appActivity`.
-   A dual-id Path (`<pkg>/<activity> | <iosBundleId>`) → take the part for the OS you are exploring
-   (left of `|` = Android pkg/activity, right = iOS bundle id).
-2. If missing → ask the user: *"What is the appPackage/appActivity (Android) or bundleId (iOS)?"*
-3. **Navigation recipe** — read the feature's `Background:` (the in-app web-path analog). Line 1
-   `Given User is on [Home] screen` is the launcher/landing screen the app opens on; each following
-   `When/And User tap [...]` (or gesture) is one hop toward the target screen. You will **replay**
-   these in step 4.5 so you scan the screen this feature targets — not the launcher. An anchor-only
-   Background (no nav steps) ⇒ the target IS the launcher screen ⇒ no navigation needed.
-
-### 2. Select device
-
-`select_device` with `platform: android` (or `ios`). If exactly one device, it auto-selects.
-If several, list them and ask the user which `deviceUdid`.
-
-### 3. Create the session
-
-`appium_session_management` `action=create`, `platform=android`, capabilities (JSON string):
-```
-appium:appPackage, appium:appActivity, appium:udid,
-appium:noReset=true, appium:autoGrantPermissions=true, appium:newCommandTimeout=300
-```
-For iOS, call `prepare_ios_simulator` first, then create with `appium:bundleId`.
-
-### 4. ⚠️ Wait for the screen to actually render
-
-**This is the #1 gotcha for Flutter / RN apps.** Right after launch the app often shows a blank
-splash — and the locator tree will contain **zero usable elements** (just an empty `FrameLayout`).
-Do **not** capture yet. Take a quick `appium_screenshot`; if it's blank/splash, wait and re-check
-until real content is drawn. Only then capture. (A Flutter app on a loading screen looks "invisible"
-to Appium; the same app on a rendered screen exposes its full Semantics tree.)
-
-### 4.5. ⚠️ Navigate to the target screen (replay the navigation recipe)
-
-**This is what makes capture land on the RIGHT screen** — the mobile equivalent of `page.goto(url)`
-on web. After the launcher screen has rendered, replay the `Background:` nav steps so Appium ends up
-on the screen this feature targets, *then* capture there.
-
-For each nav step **after** the `Given User is on [Home] screen` anchor, in order:
-1. `generate_locators` (or `appium_get_page_source`) on the CURRENT screen.
-2. Resolve the step's `[Label]` against the live tree — prefer `accessibility id`, then visible
-   `text`/`content-desc`, then an `xpath` on a distinctive substring. Gestures (`scroll to [X]`,
-   `swipe …`) follow `sungen-mobile-gestures`.
-3. Perform the tap/gesture, then **wait for the next screen to render** (same blank-splash guard as
-   step 4) before the next step.
-
-After the LAST step you are on the target screen — capture HERE (steps 5–6).
-
-- **Anchor-only Background** (no nav steps) ⇒ the target IS the launcher screen ⇒ skip this step.
-- **A step won't resolve** (its `[Label]` matches no element) ⇒ **STOP. Do not capture the wrong
-  screen.** Screenshot where you are and report: *"recipe step N: [Label] not found — fix the
-  Background nav path."* Fail loud (run-test would fail at the same step anyway).
-- **No recipe yet** (guided-stub Background, but the target is NOT the launcher) ⇒ drive to the
-  screen interactively off the live tree (if unsure which control leads there, ask the user), then
-  **report the exact nav steps you took** so create-test/add-screen can write them into the
-  Background. Do **not** edit the `.feature` yourself — Gherkin authorship stays with those commands.
-
-### 5. Capture the locator tree (primary AI context)
-
-Call **`generate_locators`** — this is the mobile equivalent of the web accessibility snapshot. It
-returns priority-ranked locators per interactable element: `accessibility id`, `id`, platform-native
-(`-android uiautomator` / `-ios predicate string`), and `xpath`, plus `content-desc`/`text`,
-`clickable`, `enabled`. This is what `sungen-tc-generation` and `sungen-selector-keys` consume.
-
-If the tree is huge, also `appium_get_page_source` (saved to a file) and grep it — never dump the
-full XML inline.
-
-### 6. Screenshot
-
-`appium_screenshot` → save to:
-```
-qa/screens/<screen>/requirements/ui/mobile-<timestamp>.png
-```
-`<timestamp>` = `YYYYMMDD-HHMM` local (e.g. `mobile-20260605-1645.png`).
-
-### 7. Detect discrepancies vs spec
-
-If `spec.md` exists, cross-check `generate_locators` labels against spec sections (fields in spec but
-not on screen, and vice-versa). Report; do **not** auto-edit `spec.md`.
-
-### 8. End the session
-
-`appium_session_management` `action=delete` to free the device. Always clean up.
-
-### 9. Report back
-
-> Captured mobile screen `<appPackage>`:
-> - Reached via: <N nav steps replayed from the Background recipe, or "launcher screen — no nav">
-> - Locators: <N> interactable elements (M with accessibility-id)
-> - Screenshot: `requirements/ui/mobile-<timestamp>.png`
-> - Discrepancies vs spec: <count, or "none">
-> - Discovered nav steps (only if the recipe was empty): <the taps you took, for create-test/add-screen to write into the Background>
-
-Hand back to the calling command.
-
----
-
-## Cross-platform discovery (`@platform:mobile` — explore one OS, layer the rest)
-
-When the screen is **`@platform:mobile`** (write-once-run-both), discover the **shared** cases first,
-then peel off only what is genuinely OS-specific. You do **not** need to explore both OSes up front —
-Flutter/RN expose the same Semantics on each, so one exploration covers most of it.
-
-1. **Explore whichever OS has a device up** (Android or iOS — symmetric for Flutter). Capture the tree.
-2. **Classify each component** into THREE buckets (not two):
-   - **Shared-exact** → a stable `accessibility id` equal on both OSes (Flutter Semantics → same value on
-     Android `content-desc` AND iOS `name`) → flat `type: accessibility-id` key in `<screen>.feature`.
-   - **Shared-variant** → SAME step/assertion on both OSes but the LOCATOR differs (composite
-     `content-desc` vs `-ios predicate`; partial/dynamic text via `descriptionContains` vs predicate
-     `CONTAINS`; a different attribute) → STILL `<screen>.feature`, with `android:`/`ios:` variant keys in
-     selectors.yaml. **A native locator alone is NOT a reason to split** — default for composite/partial text.
-   - **Sub-feature** → ONLY for genuine SCENARIO divergence: an element on ONE OS only, divergent
-     steps/flow, an OS-exclusive gesture/permission/dialog flow, or a case needing a per-platform
-     `nth`/`scope` (a variant can't diverge those). → `<screen>-android.feature` / `<screen>-ios.feature`.
-3. **Report the classification** so create-test/run-test scaffolds the right thing:
-   - `<screen>.feature`         `@platform:mobile`  ← shared-exact AND shared-variant (the vast majority)
-   - `<screen>-android.feature` `@platform:android` ← ONLY scenario-divergent Android cases
-   - `<screen>-ios.feature`     `@platform:ios`     ← ONLY scenario-divergent iOS cases
-4. **Verifying the other OS needs no second exploration** — just running the shared spec there
-   (`MOBILE_PLATFORM=both`) IS the check. Re-capture on the 2nd OS only for components that fail, and
-   move those into that OS's sub-feature. (Asking devs to add a Semantics label to an unlabeled element
-   converts an OS-specific case back into a shared one — prefer that when feasible.)
-
-## Selector-quality notes (carry into selectors.yaml)
-
-- **Prefer `accessibility id`** (Android `content-desc` / iOS `accessibilityIdentifier`) — most stable.
-- For **Flutter**, the Semantics label surfaces as `content-desc` ⇒ it usually equals the **visible
-  text**, so it is **locale-dependent** ("Good afternoon!", "English"). Keep such values in test-data
-  and use `{{variable}}` + locale overlays (see `sungen-locale`).
-- **Composite nodes**: cards may concatenate child text into one `content-desc` with `\n` → prefer an
-  xpath `contains(@content-desc,'…')` on a distinctive substring.
-- **Duplicate labels** → use `nth`. **Unlabelled controls** (search fields, icon buttons) → fall back
-  to `xpath` / class.
-
----
-
-## What this skill does NOT do
-
-- Does not run tests or generate `selectors.yaml` (that's `/sungen:run-test` + `sungen-selector-fix-mobile`)
-- Does not generate Gherkin (that's `sungen-tc-generation`) — it may *report* discovered nav steps,
-  but writing them into the Background is create-test/add-screen's job
-- Does not handle login/auth state (mobile auth is a separate concern — deep link / test build)
-- Captures **the feature's target screen** per invocation — reached by replaying the Background
-  navigation recipe (step 4.5), not just the launcher. For a *different* screen, give it its own
-  feature + recipe and re-invoke.
-
----
-
-## Relationship to other capture skills
-
-- `sungen-capture-figma` / `sungen-capture-local` — design/image sources (platform-agnostic)
-- `sungen-capture-live` — web (Playwright MCP)
-- `sungen-capture-mobile` — this skill, mobile (Appium MCP)
-
-All write to `requirements/ui/` and report back to the caller.

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-harness-audit.md

@@ -1,85 +0,0 @@
----
-name: sungen-harness-audit
-description: 'How to read `sungen audit` output and repair test-design findings. Auto-loaded by the design orchestrator.'
-user-invocable: false
----
-
-## What `sungen audit` measures
-
-`sungen audit --screen <name>` runs deterministic sensors over `features/<name>.feature` + `requirements/test-viewpoint.md` and writes `.sungen/reports/<name>-audit.json`. It is the **gate** the orchestrator repairs against. Run with `--json` to parse it.
-
-### Report shape (key fields)
-```jsonc
-{
-  "score": { "overall": 3.9, "coverage": 0.4, "businessDepth": 0.18, "balance": 0.5, "traceability": 0.7 },
-  "gateStatus": "PASS" | "FAIL",
-  "gate": { "pageType": "ecommerce-list", "themesCovered": 2, "themesTotal": 5,
-            "gaps": [ { "theme": "cart-correctness", "keywords": [...] } ] },
-  "depth": { "businessCriticalShallow": 9, "businessCriticalTotal": 11,
-             "shallowBusinessCritical": [ { "name": "...", "category": "PRODUCT" } ] },
-  "balance": { "imbalanced": true, "coreCount": 11, "secondaryCount": 22, "byBucket": {...} },
-  "duplicates": { "clusters": [ { "sameDataLikely": false, "scenarios": [...] } ] },
-  "trace": { "mappedRatio": 0.4, "note": "..." },
-  "findings": [ "GATE: ...", "DEPTH: ...", "BALANCE: ...", "TRACE: ..." ]
-}
-```
-- **`overall` score is business-weighted** (coverage 0.4 + businessDepth 0.3 + balance 0.15 + traceability 0.15). It is intentionally strict on business value — a high count with shallow business coverage scores low. Don't optimize the count; optimize coverage + depth.
-- Exit code **2** when `gateStatus == FAIL` (usable in CI / loop).
-
-## Finding → repair mapping
-
-| Finding prefix | Meaning | Repair action |
-|---|---|---|
-| **GATE** | a critical theme for the page-type has no covering scenario | Generate scenarios for that theme. **If cross-screen** (cart-correctness, product-detail-consistency, filter-result-correctness, multi-item cart) → do NOT fake it on a single screen; plan a **flow** (`/sungen:add-flow`) and record the deferral. |
-| **DEPTH** | business-critical scenarios assert only visibility/navigation | Replace `Then User see [X] page/section` with **observable data assertions**: `Then User see [X] with {{value}}`, `Then User see [T] table match data:`. Capture real expected values into `test-data.yaml`. |
-| **BALANCE** | secondary viewpoints (UI/validation/security) outweigh business-core | **Stop expanding** secondary viewpoints; generate the missing business-core scenarios first. Do not add more subscription/UI variants while core is thin. |
-| **TRACE** | scenarios use ad-hoc `VP-<CAT>-NNN` codes not linked to the viewpoint-overview | Make each scenario map to a viewpoint-overview id (align category codes, or add a mapping comment). |
-| **UNIVERSAL** | a universal theme (error/empty-state, accessibility) is absent | Low priority — add if in scope; otherwise note as out-of-scope with reason. |
-
-## P5 steps for deep cross-screen / list coverage
-
-Use these when repairing GATE/DEPTH findings for the hard viewpoints (cart/detail/filter correctness). They need **runtime data mode** (the default).
-
-- **Capture a value to compare across screens** (product-detail-consistency, cart-correctness):
-  ```gherkin
-  When User remember [Product Name] text as {{selected_product_name}}
-  And User remember [Product Price] text as {{selected_product_price}}
-  And User click [View Product] link
-  Then User see [Detail Product Name] header with {{selected_product_name}}
-  And User see [Detail Product Price] text with {{selected_product_price}}
-  ```
-  `remember` stores the element's text/value at runtime; later `{{var}}` resolves to it. This proves the detail/cart shows the SAME product, not a random one.
-
-- **Assert every item in a result matches** (category/brand-filter-correctness):
-  ```gherkin
-  When User click [Women] link
-  And User click [Dress] link
-  Then User see all [Result Product Name] contain {{selected_category}}
-  ```
-  `see all [X] contain {{v}}` asserts EVERY matching element contains the value → "all displayed products belong to the selected category/brand", not just one.
-
-> Cross-screen flows (home → detail/cart): **automate the journey as a flow** (`/sungen:add-flow`) — it runs as one test, so it is automatable. Do **not** keep a full `@manual` duplicate of it on the screen (a non-running dead copy that `sungen audit` flags as `MANUAL-AUTOMATABLE` and that inflates nothing — deferred business-critical is reported as `DEPTH-DEFERRED`). The screen keeps its screen-contract; the flow owns the cross-screen depth. `@manual` is for genuine judgment / missing-capability only, tagged `@manual:Mx`.
-
-## Repair loop rules
-
-1. **Budget = 3 rounds.** Re-run `sungen audit` after each repair; track score delta.
-2. **Stop when** `gateStatus == PASS` AND `findings` empty — or budget exhausted.
-3. **Never fake a pass.** A shallow `see [Cart] page` does not satisfy `cart-correctness`. If a gap is genuinely cross-screen or needs capabilities the DSL lacks (e.g. capture an element value to compare elsewhere), **report it as a residual gap / flow item** instead of forcing a green gate.
-4. **EP/data families are OK.** A `duplicates` cluster with `sameDataLikely=false` is an intentional equivalence-partition family (e.g. many invalid-email cases) — keep it; only collapse `sameDataLikely=true` exact duplicates.
-5. **Advisory findings — surface, don't gate.** `MANUAL-REASON-MISMATCH` → fix the scenario's `@manual:Mx` code (so the planner recommends the right driver) during repair. `CAPABILITY-SUGGESTION` → **present it to the user as a next-step option** (e.g. "N @manual could be automated — `sungen capability add api db`?"), **recommend-only — never auto-install**. Neither fails the gate.
-
-## Discovery / fallback tree (when input is limited)
-
-```
-spec.md đủ tốt?      → YES: Spec-first
-  │ NO
-source code có?      → YES: Source-first (mine behavior từ code)
-  │ NO
-testcase cũ tương tự?→ YES: History-first
-  │ NO
-domain rủi ro+defect?→ YES: Defect-first
-  │ NO
-→ hỏi QA; QA chưa phản hồi → OUTPUT kèm ASSUMPTION LIST rõ ràng (không stall)
-```
-
-See `docs/orchestration-spec.md` for the full flow and `docs/spec/sungen_refactor_spec.md` for the design rationale.

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

@@ -1,291 +0,0 @@
----
-name: sungen-locale
-description: 'Bootstrap i18n for a screen/flow — audit hardcoded selector text, detect locale-switch mechanism via live Playwright, generate test-data overlay file. Auto-loaded by /sungen:locale command.'
-user-invocable: false
----
-
-## Goal
-
-Take a screen/flow whose `selectors/*.yaml` and `.feature` files were authored against the default locale (usually Vietnamese) and prepare it to run against a second locale. Output:
-
-1. `selectors/<feature>.yaml` — hardcoded `name`/`value` replaced with `{{var}}`
-2. `test-data/<feature>.yaml` — base locale, complete with all new keys
-3. `test-data/<feature>.<locale>.yaml` — overlay with only the keys that change
-4. (Optional) `selectors/<feature>.yaml` Pages block updated when locale uses URL prefix or query param
-
-After this skill finishes, `sungen run-test <name> --env <locale>` Just Works.
-
-## Run mode — Live (preferred) vs Offline (fallback)
-
-Pick mode **once at start**, based on whether MCP Playwright can reach the page.
-
-```
-Try: browser_navigate(baseURL)
-  → succeeds + page renders content → LIVE MODE (all 6 phases)
-  → fails (auth blocked, network down, app broken) → OFFLINE MODE
-    (audit + scaffold template + ask user to fill, skip detection phases)
-```
-
-**Live mode is the value-add** — it auto-detects locale switch mechanism and auto-fills translations. Offline mode just makes the file structure right; user fills in text manually.
-
-Announce which mode is being used before Phase 1.
-
-## Phase 1 — Audit selectors (always, no MCP)
-
-For each `.feature` file under the screen, read the matching `selectors/<feature>.yaml`. List every entry whose `name` or `value` field contains literal text WITHOUT `{{…}}` AND is not a CSS/href selector.
-
-Classify each candidate:
-- **`name` field of `role`-type selector** → very likely locale-dependent
-- **`value` field of `text`-type selector** → very likely locale-dependent
-- **`value` of `locator`-type selector** that contains `:has-text("…")` → check if text is in target language
-- **`value` of `page`-type selector** → URL — handled in Phase 3
-- **CSS / href / attribute selectors** (e.g. `a[href="/awards"]`) → skip, locale-invariant
-
-Print the candidate list as a table:
-
-```
-selector key       | field | hardcoded value           | classification
--------------------+-------+---------------------------+------------------
-nav about          | name  | Giới thiệu SAA 2025       | locale-dependent
-nav awards         | name  | Thông tin giải thưởng     | locale-dependent
-event date         | name  | 26/12/2025                | maybe (date format)
-nav kudos          | name  | Sun* Kudos                | brand — skip
-```
-
-If zero candidates and zero `{{var}}` already in place → screen has no localizable text. Tell user, stop.
-
-## Phase 2 — Capture base locale (LIVE only)
-
-1. Read `playwright.config.ts` for `baseURL`. Read `Path:` from `.feature` for entry path.
-2. If screen has `@auth:<role>` tags, load `specs/.auth/<role>.json` via `browser_set_storage_state` first.
-3. `browser_navigate(baseURL + entryPath)` then `browser_wait_for` for something stable.
-4. Capture:
-   - `browser_snapshot()` — DOM accessibility tree
-   - `browser_evaluate(() => location.href)` — full URL
-   - `browser_evaluate(() => ({ localStorage: {...localStorage}, cookies: document.cookie }))` — storage state hash
-5. For each Phase-1 candidate: verify the hardcoded text actually appears on the page. Drop ones that don't (stale selectors / false positives).
-
-Save state in memory as `baseLocale = { url, snapshot, storage }`.
-
-If page redirects to `/login` (auth blocker) → stop. Print: *"Auth blocked — cannot capture live page. Re-run with `--offline` flag, or unblock auth first."*
-
-## Phase 3 — Switch locale (LIVE only) — detect mechanism + storage delta
-
-Goal: identify (a) HOW to switch the app to the target locale, and (b) WHAT app-side storage state ends up holding the locale preference so a fresh BrowserContext can be primed identically without driving the UI.
-
-Before triggering the switch, capture full storage baseline:
-
-```js
-const before = await browser_evaluate(() => ({
-  sessionStorage: { ...sessionStorage },
-  localStorage:   { ...localStorage },
-  cookies:        document.cookie,
-  url:            location.href,
-}));
-```
-
-Then try mechanisms in order. First one that produces visibly different text wins. For EACH attempt, capture `after` state and diff against `before`.
-
-**3a. URL prefix**
-- `browser_navigate(baseURL + '/' + locale + entryPath)`
-- Wait, snapshot
-- Compare a known Phase-1 candidate's text vs baseLocale
-- If text differs and page didn't 404 → **URL prefix mechanism**. Save `localePrefix = '/' + locale`.
-
-**3b. Query param** (only if 3a failed)
-- `browser_navigate(baseURL + entryPath + '?lang=' + locale)` (also try `?locale=`, `?lng=`, `?l=`, `?language=`)
-- Same diff check
-- If text differs → **Query param mechanism**. Save the variant that worked.
-
-**3c. Language switcher UI** (only if 3a + 3b failed)
-- Look in base-locale snapshot for buttons matching: `'Select language'`, `'Language'`, `'言語'`, `'Ngôn ngữ'`, role=combobox
-- If found, ask user before clicking
-- `browser_click` the switcher, then the locale option
-- Verify text changed
-- If yes → **UI switcher mechanism**.
-
-**3d. None detected** — ask user how to proceed manually.
-
-### Phase 3.5 — Storage diff (always run after Phase 3 succeeds)
-
-After locale text confirmed switched, capture `after` state and diff per area:
-
-```js
-const after = await browser_evaluate(() => ({
-  sessionStorage: { ...sessionStorage },
-  localStorage:   { ...localStorage },
-  cookies:        document.cookie,
-}));
-const sessionDiff = diffEntries(before.sessionStorage, after.sessionStorage);
-const localDiff   = diffEntries(before.localStorage,   after.localStorage);
-const cookieDiff  = diffCookies(before.cookies, after.cookies);
-```
-
-**Filter noise** — only keep entries where:
-- Key name contains `lang|locale|language|i18n|intl` (case-insensitive), OR
-- Value matches `^[a-z]{2}(-[A-Z]{2})?$` or equals the target locale code
-
-Drop noise: auth tokens (`sb-*`, `*-token`, `*-jwt`), analytics (`_ga*`, `_gid`, `_fbp`), app state (`csrf*`, `last-*`).
-
-**Auto-confidence per entry:**
-- High: key name contains locale-related word AND value is a locale code → KEEP, no prompt
-- Medium: only one signal matches → ask user
-- Low: neither matches but key changed → ask user, default skip
-
-### Phase 3.6 — Verification
-
-For each high/medium-confidence storage entry, verify by setting it manually + reloading:
-
-```js
-await browser_evaluate(`() => sessionStorage.setItem('saa-language-preference', 'en')`);
-await browser_navigate(baseURL);  // reload triggers app to read storage on boot
-await browser_snapshot();
-// confirm a known target-locale string appears
-```
-
-Caveat: hard reload kills any in-memory JWT (auth blocker amplifies failure surface). Skip verification if the screen has `@auth:*` tags and JWT persistence is known broken in the app.
-
-If verification fails → drop confidence one tier, ask user.
-
-Save mechanism + verified storage delta to memory for Phase 6.
-
-## Phase 4 — Diff base ↔ target (LIVE only)
-
-For each candidate from Phase 1 that survived Phase 2:
-- Find the SAME element in target-locale snapshot (match by `role`+position, by `aria-label`, by neighbor structure)
-- Extract its text → `targetText`
-- Pair: `(selectorKey, hardcoded baseText, observed targetText)`
-
-If matching fails for a candidate → mark "needs manual" — flag for user input rather than skip silently.
-
-Result: list of triples `{ selectorKey, baseText, targetText, confidence }`.
-
-## Phase 5 — Confirm + edit (always)
-
-Present the proposal table:
-
-```
-selector key       | base text                | target text          | proposed var     | apply?
--------------------+--------------------------+----------------------+------------------+-------
-nav about          | Giới thiệu SAA 2025      | About SAA 2025       | nav_about        | [✓]
-nav awards         | Thông tin giải thưởng    | Awards Info          | nav_awards       | [✓]
-nav kudos          | Sun* Kudos               | Sun* Kudos           | —                | [skip — same]
-event date         | 26/12/2025               | 26/12/2025           | —                | [skip — same]
-```
-
-Var names: snake_case the selector key. Avoid collisions with existing test-data keys.
-
-Auto-skip rows where `baseText === targetText` (brand names, locale-invariant numbers).
-
-Ask user: *"Review the table. Confirm to apply / edit individual rows / re-run capture / cancel."*
-
-If user wants to edit a row → fall through to a per-row prompt for `var name` or `targetText` correction.
-
-OFFLINE mode: same table but `target text` column blank — user fills via subsequent prompts or by editing the overlay file after the skill finishes.
-
-## Phase 6 — Apply changes (always, after confirmation)
-
-For each confirmed row:
-
-**6a. Update `selectors/<feature>.yaml`**
-
-Replace `name: '<baseText>'` with `name: '{{<varName>}}'`. Preserve quoting style.
-
-**6b. Update `test-data/<feature>.yaml`** (base locale, complete dictionary)
-
-Append new keys at the end, grouped under a `# === i18n: <screen> ===` comment:
-
-```yaml
-# === i18n: home ===
-nav_about: 'Giới thiệu SAA 2025'
-nav_awards: 'Thông tin giải thưởng'
-```
-
-**6c. Create `test-data/<feature>.<locale>.yaml`** (overlay, only diffs)
-
-```yaml
-# home — <locale> overlay. Only keys that change vs base.
-# Run with: SUNGEN_ENV=<locale> npx playwright test ...
-
-nav_about: 'About SAA 2025'
-nav_awards: 'Awards Info'
-```
-
-**6d. (URL/query mechanism only) Update Pages selectors**
-
-URL prefix:
-
-```yaml
-home:
-  type: 'page'
-  value: '{{base_path}}/'
-awards:
-  type: 'page'
-  value: '{{base_path}}/awards'
-```
-
-Add to test-data:
-```yaml
-# base
-base_path: ''
-
-# overlay
-base_path: '/en'
-```
-
-Query param mechanism: append `query_suffix` similarly.
-
-UI switcher: do NOT modify Pages. Write storage delta into `specs/generated/locale-config.json` (sibling of generated `base.ts` + `locale-fixture.ts`) (6f).
-
-**6f. Storage injection config — `specs/generated/locale-config.json` (sibling of generated `base.ts` + `locale-fixture.ts`)**
-
-Always write `specs/generated/locale-config.json` (sibling of generated `base.ts` + `locale-fixture.ts`) with the verified storage delta from Phase 3.5/3.6. Consumed by `specs/locale-fixture.ts` (auto-generated alongside `specs/base.ts`), which wraps Playwright's context and calls `addInitScript` + `addCookies` BEFORE the first navigation.
-
-Schema:
-
-```json
-{
-  "$schema": "sungen-locale-config-v1",
-  "sessionStorage": {
-    "saa-language-preference": "${SUNGEN_ENV}"
-  },
-  "localStorage": {},
-  "cookies": [],
-  "notes": "Detected by /sungen:locale on YYYY-MM-DD. ..."
-}
-```
-
-Use `"${SUNGEN_ENV}"` (or `"{{SUNGEN_ENV}}"`) as placeholder for runtime substitution. Use hardcoded literals when the stored value is fixed regardless of locale. Drop auth tokens / session IDs even if the Phase 3.5 diff captured them.
-
-Multi-locale projects use the same file — placeholder gets substituted at runtime per locale.
-
-**6e. Compile**
-
-Run `sungen generate --screen <name>` (or `--flow`) and report any compile errors. Selectors changed → compile MUST succeed before run-test.
-
-## Phase 7 — Hand off
-
-Print summary:
-- N selectors converted to `{{var}}`
-- M base keys added to `test-data/<feature>.yaml`
-- K overlay keys written to `test-data/<feature>.<locale>.yaml`
-- Pages selectors updated: yes/no
-- Locale-switching mechanism: URL prefix `/en` / query `?lang=en` / UI switcher / manual
-
-Suggest:
-
-```
-/sungen:run-test <name> --env <locale>
-```
-
-## Multi-feature screens
-
-If the screen has multiple `.feature` files (e.g. `home.feature` + `home-modal.feature`), repeat Phase 1 → Phase 6 for each feature file with its own selectors + test-data pair. Phase 2 + 3 run **once per screen** — mechanism is the same. Phase 4 runs per feature because UI scope differs.
-
-## What NOT to do
-
-- Do not edit `.feature` files. The i18n shape is already correct there (`{{var}}` was the convention from the start). Only selectors + test-data need surgery.
-- Do not write a separate selectors file per locale (`home.en.yaml`). One selectors file with `{{var}}` works across all locales.
-- Do not delete keys from the base `test-data/<feature>.yaml`. Always append.
-- Do not run tests in this skill. Hand off to `/sungen:run-test`.
-- Do not commit. Hand off to user.