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

package/{src/orchestrator/templates/ai-instructions/claude-skill-locale.md → dist/orchestrator/templates/ai-src/skills/sungen-locale/SKILL.md}

@@ -1,10 +1,33 @@
 ---
 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.'
+description: 'Bootstrap i18n for a screen/flow — audit hardcoded selector text, detect locale-switch mechanism via Playwright (web) or device locale (mobile), generate test-data overlay file. Auto-loaded by /sungen:locale command.'
 user-invocable: false
 ---
 
-## Goal
+## Platform Detection (do this FIRST)
+
+Read `qa/capabilities.yaml` and check the `platform` field.
+
+- If `platform: mobile` → follow the **mobile path** (see "Mobile path" section below)
+- If `platform: web` or field absent → follow the **web path** (standard, below)
+
+### Mobile path
+
+When `platform: mobile`:
+
+1. **Live capture**: use **Appium MCP** (`select_device` → `appium_session_management(create)` with device at base locale → `appium_get_page_source` / `appium_screenshot`) — NOT Playwright browser tools
+2. **Locale-switch mechanism**: **device locale** — `appium:language` / `appium:locale` caps + `noReset:false` (set by wdio `resolveLocaleCaps` at runtime). No URL prefix, query param, or browser-storage injection
+3. **Phases skipped for mobile**: audit (Phase 1), capture base (Phase 2), detect mechanism (Phase 3) are unchanged. Phases 3.5 (browser storage diff), 3.6 (storage verify), 6d (Pages URL update), 6f (locale-config.json / locale-fixture) are **web-only** — skip them. wdio `resolveLocaleCaps` handles runtime locale automatically
+4. **OFFLINE mode**: scaffold overlay template + ask user to fill manually if device unreachable or `--offline` flag given
+5. **Hand-off**: print `SUNGEN_ENV=<locale> npm run test:mobile`. Include note: "If the device locale code differs from the overlay env name, set `SUNGEN_LOCALE=<code>` — wdio `resolveLocaleCaps` reads it as an override."
+6. **Phase 6 (mobile) writes only**: 6a selectors `{{var}}`, 6b base `test-data/<feature>.yaml`, 6c overlay `test-data/<feature>.<locale>.yaml`. Skip 6d (Pages URL) and 6f (locale-config.json)
+7. **Compile**: `sungen generate --screen <name>` (appium adapter auto-selected in mobile project)
+
+**Stop here for mobile.** Do not continue to the web path below.
+
+---
+
+## Goal (Web)
 
 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:
 
@@ -37,8 +60,14 @@ For each `.feature` file under the screen, read the matching `selectors/<feature
 Classify each candidate:
 - **`name` field of `role`-type selector** → very likely locale-dependent
 - **`value` field of `text`-type selector** → very likely locale-dependent
+{{#cap parallel-subagents}}
 - **`value` of `locator`-type selector** that contains `:has-text("…")` → check if the text is in target language
 - **`value` of `page`-type selector** → URL — handled separately in Phase 3
+{{/cap}}
+{{^cap parallel-subagents}}
+- **`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
+{{/cap}}
 - **CSS / href / attribute selectors** (e.g. `a[href="/awards"]`) → skip, locale-invariant
 
 Print the candidate list as a table:
@@ -52,22 +81,49 @@ event date         | name  | 26/12/2025                | maybe (date format)
 nav kudos          | name  | Sun* Kudos                | brand — skip
 ```
 
+{{#cap parallel-subagents}}
 If there are zero candidates and no `{{var}}` either, the screen has no localizable text → tell user and stop.
+{{/cap}}
+{{^cap parallel-subagents}}
+If zero candidates and zero `{{var}}` already in place → screen has no localizable text. Tell user, stop.
+{{/cap}}
 
 ## Phase 2 — Capture base locale (LIVE only)
 
+{{#cap parallel-subagents}}
 1. Read `playwright.config.ts` for `baseURL`. Read `Path:` from `.feature` for the entry-point path.
 2. If the 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` something stable.
+{{/cap}}
+{{^cap parallel-subagents}}
+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.
+{{/cap}}
 4. Capture:
    - `browser_snapshot()` — DOM accessibility tree
    - `browser_evaluate(() => location.href)` — full URL
    - `browser_evaluate(() => ({ localStorage: {...localStorage}, cookies: document.cookie }))` — storage state hash
+{{#cap parallel-subagents}}
 5. For each candidate from Phase 1: verify the hardcoded text actually appears on the page (string contains check against snapshot text). Drop candidates that don't appear (probably stale selectors or false positives).
+{{/cap}}
+{{^cap parallel-subagents}}
+5. For each Phase-1 candidate: verify the hardcoded text actually appears on the page. Drop ones that don't (stale selectors / false positives).
+{{/cap}}
 
+{{#cap parallel-subagents}}
 Save state to memory as `baseLocale = { url, snapshot, storage }`.
+{{/cap}}
+{{^cap parallel-subagents}}
+Save state in memory as `baseLocale = { url, snapshot, storage }`.
+{{/cap}}
 
+{{#cap parallel-subagents}}
 If page redirects to `/login` (auth blocker) → stop. Print: *"Auth blocked — cannot capture live page. Fall back to OFFLINE mode by re-running once auth works, or pick `Offline-only` next time."*
+{{/cap}}
+{{^cap parallel-subagents}}
+If page redirects to `/login` (auth blocker) → stop. Print: *"Auth blocked — cannot capture live page. Re-run with `--offline` flag, or unblock auth first."*
+{{/cap}}
 
 ## Phase 3 — Switch locale (LIVE only) — detect mechanism + storage delta
 
@@ -87,39 +143,80 @@ const before = await browser_evaluate(() => ({
 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**
+{{#cap parallel-subagents}}
 - `browser_navigate(baseURL + '/' + locale + entryPath)` (e.g. `https://saa-2025.../en/`)
+{{/cap}}
+{{^cap parallel-subagents}}
+- `browser_navigate(baseURL + '/' + locale + entryPath)`
+{{/cap}}
 - Wait, snapshot
+{{#cap parallel-subagents}}
 - Compare text content with baseLocale snapshot for a known-changed element
+{{/cap}}
+{{^cap parallel-subagents}}
+- Compare a known Phase-1 candidate's text vs baseLocale
+{{/cap}}
 - 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
+{{#cap parallel-subagents}}
 - If text differs → **Query param mechanism**. Save `localeQuery = '?lang=' + locale` (or whichever variant worked).
+{{/cap}}
+{{^cap parallel-subagents}}
+- If text differs → **Query param mechanism**. Save the variant that worked.
+{{/cap}}
 
 **3c. Language switcher UI** (only if 3a + 3b failed)
+{{#cap parallel-subagents}}
 - Look in base-locale snapshot for buttons/links matching: `'Select language'`, `'Language'`, `'言語'`, `'Ngôn ngữ'`, role=combobox
 - If found, ask user: *"Detected possible language switcher: [X]. Click it and proceed?"*
 - On confirm: `browser_click` the switcher, then `browser_click` the locale option
+{{/cap}}
+{{^cap parallel-subagents}}
+- 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
+{{/cap}}
 - Verify text changed
+{{#cap parallel-subagents}}
 - If yes → **UI switcher mechanism**. Save selector + option details.
+{{/cap}}
+{{^cap parallel-subagents}}
+- If yes → **UI switcher mechanism**.
+{{/cap}}
 
+{{#cap parallel-subagents}}
 **3d. None detected**
 - AskUserQuestion: *"Couldn't auto-detect locale switching. Either (a) demo it for me in browser then I'll snapshot, (b) provide locale URL manually, (c) skip — assume URL prefix `/<locale>`."*
+{{/cap}}
+{{^cap parallel-subagents}}
+**3d. None detected** — ask user how to proceed manually.
+{{/cap}}
 
 ### Phase 3.5 — Storage diff (always run after Phase 3 succeeds)
 
+{{#cap parallel-subagents}}
 After locale text confirmed switched, capture `after` state and diff:
+{{/cap}}
+{{^cap parallel-subagents}}
+After locale text confirmed switched, capture `after` state and diff per area:
+{{/cap}}
 
 ```js
 const after = await browser_evaluate(() => ({
   sessionStorage: { ...sessionStorage },
   localStorage:   { ...localStorage },
   cookies:        document.cookie,
+{{#cap parallel-subagents}}
   url:            location.href,
+{{/cap}}
 }));
+{{#cap parallel-subagents}}
 
 // Diff each storage area:
+{{/cap}}
 const sessionDiff = diffEntries(before.sessionStorage, after.sessionStorage);
 const localDiff   = diffEntries(before.localStorage,   after.localStorage);
 const cookieDiff  = diffCookies(before.cookies, after.cookies);
@@ -127,48 +224,109 @@ const cookieDiff  = diffCookies(before.cookies, after.cookies);
 
 **Filter noise** — only keep entries where:
 - Key name contains `lang|locale|language|i18n|intl` (case-insensitive), OR
+{{#cap parallel-subagents}}
 - Value matches a locale code pattern: `^[a-z]{2}(-[A-Z]{2})?$` or matches the target locale code exactly
+{{/cap}}
+{{^cap parallel-subagents}}
+- Value matches `^[a-z]{2}(-[A-Z]{2})?$` or equals the target locale code
+{{/cap}}
 
+{{#cap parallel-subagents}}
 Drop known noise:
 - Auth tokens: `sb-*`, `*-token`, `*-jwt`, `*-session-id`
 - Analytics: `_ga*`, `_gid`, `_fbp`
 - App state: `csrf*`, `last-*`, `visit-*`
+{{/cap}}
+{{^cap parallel-subagents}}
+Drop noise: auth tokens (`sb-*`, `*-token`, `*-jwt`), analytics (`_ga*`, `_gid`, `_fbp`), app state (`csrf*`, `last-*`).
+{{/cap}}
 
+{{#cap parallel-subagents}}
 **Auto-confidence scoring** per remaining entry:
 - High confidence: key name contains locale-related word AND value is a locale code matching target → KEEP, no user prompt
 - Medium: only one signal matches → present to user for confirmation
 - Low: neither matches but key changed → present to user, default to skip
-
+{{/cap}}
+{{^cap parallel-subagents}}
+**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
+{{/cap}}
+
+{{#cap parallel-subagents}}
 ### Phase 3.6 — Verification (always run after Phase 3.5)
+{{/cap}}
+{{^cap parallel-subagents}}
+### Phase 3.6 — Verification
+{{/cap}}
 
+{{#cap parallel-subagents}}
 For each high/medium-confidence storage entry, verify by replaying in a FRESH context:
+{{/cap}}
+{{^cap parallel-subagents}}
+For each high/medium-confidence storage entry, verify by setting it manually + reloading:
+{{/cap}}
 
 ```js
+{{#cap parallel-subagents}}
 // 1. Capture current page state (have JWT in memory) — note: can't replay JWT separately
 // 2. Open new browser_navigate to baseURL but pre-set the detected key via addInitScript
 // 3. Snapshot new page and confirm a known target-locale string appears
 
 // Pseudo-code — real impl uses Playwright MCP `browser_evaluate` with init pattern
+{{/cap}}
+{{^cap parallel-subagents}}
+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
+{{/cap}}
 ```
 
+{{#cap parallel-subagents}}
 Actually since MCP browser sessions don't expose `addInitScript` directly, use a softer verification:
 - Manually set the candidate key via `browser_evaluate(() => sessionStorage.setItem('key', 'value'))`
 - Hard reload the page: `browser_navigate(baseURL)` to force re-init
 - Snapshot, look for known target-locale text
 - Caveat: hard reload kills any in-memory JWT — auth blocker amplifies failure surface. Skip verification if the screen has `@auth:*` tags and the staging app has known JWT-persistence issues.
+{{/cap}}
+{{^cap parallel-subagents}}
+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.
+{{/cap}}
 
+{{#cap parallel-subagents}}
 If verification fails / can't run → drop confidence by one tier, ask user.
+{{/cap}}
+{{^cap parallel-subagents}}
+If verification fails → drop confidence one tier, ask user.
+{{/cap}}
 
+{{#cap parallel-subagents}}
 Save mechanism + verified storage delta to memory for use in Phase 6.
+{{/cap}}
+{{^cap parallel-subagents}}
+Save mechanism + verified storage delta to memory for Phase 6.
+{{/cap}}
 
 ## Phase 4 — Diff base ↔ target (LIVE only)
 
 For each candidate from Phase 1 that survived Phase 2:
+{{#cap parallel-subagents}}
 - Find the SAME element in the target-locale snapshot (match by `role`+position, by `aria-label` if available, by neighbor structure)
+{{/cap}}
+{{^cap parallel-subagents}}
+- Find the SAME element in target-locale snapshot (match by `role`+position, by `aria-label`, by neighbor structure)
+{{/cap}}
 - Extract its text → `targetText`
 - Pair: `(selectorKey, hardcoded baseText, observed targetText)`
 
+{{#cap parallel-subagents}}
 If matching fails for a candidate → mark as "needs manual" — flag for user input rather than skip.
+{{/cap}}
+{{^cap parallel-subagents}}
+If matching fails for a candidate → mark "needs manual" — flag for user input rather than skip silently.
+{{/cap}}
 
 Result: list of triples `{ selectorKey, baseText, targetText, confidence }`.
 
@@ -181,20 +339,47 @@ selector key       | base text                | target text          | proposed
 -------------------+--------------------------+----------------------+------------------+-------
 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       | [✓]
+{{#cap parallel-subagents}}
 event location     | Au Co Arts Centre, Hanoi | Au Co Arts Centre…   | event_location   | (already has {{}})
+{{/cap}}
 nav kudos          | Sun* Kudos               | Sun* Kudos           | —                | [skip — same]
 event date         | 26/12/2025               | 26/12/2025           | —                | [skip — same]
 ```
 
+{{#cap parallel-subagents}}
 Propose **var names** by snake_casing the selector key. Avoid collisions with existing test-data keys.
+{{/cap}}
+{{^cap parallel-subagents}}
+Var names: snake_case the selector key. Avoid collisions with existing test-data keys.
+{{/cap}}
 
+{{#cap parallel-subagents}}
 Auto-skip rows where `baseText === targetText` (brand names, dates that don't change between locales).
+{{/cap}}
+{{^cap parallel-subagents}}
+Auto-skip rows where `baseText === targetText` (brand names, locale-invariant numbers).
+{{/cap}}
 
+{{#cap parallel-subagents}}
 Ask user via AskUserQuestion: *"Review the table above. Confirm to apply / edit individual rows / re-run capture / cancel."*
+{{/cap}}
+{{^cap parallel-subagents}}
+Ask user: *"Review the table. Confirm to apply / edit individual rows / re-run capture / cancel."*
+{{/cap}}
 
+{{#cap parallel-subagents}}
 If user wants to edit a row → fall through to a per-row prompt asking for `var name` or `targetText` correction.
+{{/cap}}
+{{^cap parallel-subagents}}
+If user wants to edit a row → fall through to a per-row prompt for `var name` or `targetText` correction.
+{{/cap}}
 
+{{#cap parallel-subagents}}
 In OFFLINE mode this phase is the same table but `target text` column is blank — user fills via subsequent prompts or by editing the overlay file after the skill finishes.
+{{/cap}}
+{{^cap parallel-subagents}}
+OFFLINE mode: same table but `target text` column blank — user fills via subsequent prompts or by editing the overlay file after the skill finishes.
+{{/cap}}
 
 ## Phase 6 — Apply changes (always, after confirmation)
 
@@ -206,7 +391,12 @@ Replace `name: '<baseText>'` with `name: '{{<varName>}}'`. Preserve quoting styl
 
 **6b. Update `test-data/<feature>.yaml`** (base locale, complete dictionary)
 
+{{#cap parallel-subagents}}
 Append new keys at the end, grouped under a `# === i18n: <screen> ===` comment. Example:
+{{/cap}}
+{{^cap parallel-subagents}}
+Append new keys at the end, grouped under a `# === i18n: <screen> ===` comment:
+{{/cap}}
 
 ```yaml
 # === i18n: home ===
@@ -226,10 +416,17 @@ nav_awards: 'Awards Info'
 
 **6d. (URL/query mechanism only) Update Pages selectors**
 
+{{#cap parallel-subagents}}
 If Phase 3 detected URL prefix:
+{{/cap}}
+{{^cap parallel-subagents}}
+URL prefix:
+{{/cap}}
 
 ```yaml
+{{#cap parallel-subagents}}
 # selectors/<feature>.yaml — Pages block becomes locale-aware
+{{/cap}}
 home:
   type: 'page'
   value: '{{base_path}}/'
@@ -238,24 +435,64 @@ awards:
   value: '{{base_path}}/awards'
 ```
 
+{{#cap parallel-subagents}}
 And add to test-data:
+{{/cap}}
+{{^cap parallel-subagents}}
+Add to test-data:
+{{/cap}}
 ```yaml
+{{#cap parallel-subagents}}
 # test-data/<feature>.yaml (base)
+{{/cap}}
+{{^cap parallel-subagents}}
+# base
+{{/cap}}
 base_path: ''
 
+{{#cap parallel-subagents}}
 # test-data/<feature>.<locale>.yaml (overlay)
+{{/cap}}
+{{^cap parallel-subagents}}
+# overlay
+{{/cap}}
 base_path: '/en'
 ```
 
+{{#cap parallel-subagents}}
 If Phase 3 detected query param: similar but with `query_suffix: ''` / `query_suffix: '?lang=en'` appended to each page value.
+{{/cap}}
+{{^cap parallel-subagents}}
+Query param mechanism: append `query_suffix` similarly.
+{{/cap}}
 
+{{#cap parallel-subagents}}
 If Phase 3 detected UI switcher: do NOT modify Pages. Instead, write the storage delta from Phase 3.5 into `specs/generated/locale-config.json` (sibling of `specs/generated/base.ts` + `specs/generated/locale-fixture.ts`) (see 6f below).
+{{/cap}}
+{{^cap parallel-subagents}}
+UI switcher: do NOT modify Pages. Write storage delta into `specs/generated/locale-config.json` (sibling of generated `base.ts` + `locale-fixture.ts`) (6f).
+{{/cap}}
 
+{{#cap parallel-subagents}}
 **6f. Storage injection config — `specs/generated/locale-config.json` (sibling of `specs/generated/base.ts` + `specs/generated/locale-fixture.ts`)**
+{{/cap}}
+{{^cap parallel-subagents}}
+**6f. Storage injection config — `specs/generated/locale-config.json` (sibling of generated `base.ts` + `locale-fixture.ts`)**
+{{/cap}}
 
+{{#cap parallel-subagents}}
 Always write `specs/generated/locale-config.json` (sibling of `specs/generated/base.ts` + `specs/generated/locale-fixture.ts`) with the verified storage delta from Phase 3.5/3.6. This file is consumed by `specs/locale-fixture.ts` (auto-generated alongside `specs/base.ts`) — the fixture wraps Playwright's context, calls `addInitScript` to seed sessionStorage / localStorage, and `addCookies` for any cookies, BEFORE the first page navigation. Without this file, `SUNGEN_ENV=<locale>` only swaps test-data overlay — the browser would still boot in base locale.
+{{/cap}}
+{{^cap parallel-subagents}}
+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.
+{{/cap}}
 
+{{#cap parallel-subagents}}
 Schema (only include areas that actually changed):
+{{/cap}}
+{{^cap parallel-subagents}}
+Schema:
+{{/cap}}
 
 ```json
 {
@@ -265,10 +502,16 @@ Schema (only include areas that actually changed):
   },
   "localStorage": {},
   "cookies": [],
+{{#cap parallel-subagents}}
   "notes": "Detected by /sungen:locale on YYYY-MM-DD. App persists locale in sessionStorage; initial trigger uses ?language=<code> query param."
+{{/cap}}
+{{^cap parallel-subagents}}
+  "notes": "Detected by /sungen:locale on YYYY-MM-DD. ..."
+{{/cap}}
 }
 ```
 
+{{#cap parallel-subagents}}
 Notes on the schema:
 - Use the literal placeholder `"${SUNGEN_ENV}"` (or `"{{SUNGEN_ENV}}"`) when the stored value equals the locale code itself. The fixture substitutes `process.env.SUNGEN_ENV` at runtime, so the same file works for `en`, `ja`, etc.
 - Use a hardcoded literal (e.g. `"en_US"`) when the stored value is fixed regardless of which locale runs.
@@ -277,12 +520,26 @@ Notes on the schema:
 - `notes` is free-form, informational; the fixture ignores it.
 
 Multi-locale projects: the same `locale-config.json` works for every locale because the value templating uses `${SUNGEN_ENV}`. No per-locale file needed.
+{{/cap}}
+{{^cap parallel-subagents}}
+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.
+{{/cap}}
 
+{{#cap parallel-subagents}}
 The file lives at `specs/generated/locale-config.json` (sibling of `specs/generated/base.ts` + `specs/generated/locale-fixture.ts`) (sibling of `specs/base.ts`). If a different output directory is used, mirror the existing `specs/base.ts` location.
+{{/cap}}
+{{^cap parallel-subagents}}
+Multi-locale projects use the same file — placeholder gets substituted at runtime per locale.
+{{/cap}}
 
 **6e. Compile**
 
+{{#cap parallel-subagents}}
 Run `sungen generate --screen <name>` (or `--flow`) and report any compile errors back to the user. The selectors changed so compile must succeed before run-test.
+{{/cap}}
+{{^cap parallel-subagents}}
+Run `sungen generate --screen <name>` (or `--flow`) and report any compile errors. Selectors changed → compile MUST succeed before run-test.
+{{/cap}}
 
 ## Phase 7 — Hand off
 
@@ -301,16 +558,31 @@ Suggest:
 
 ## Multi-feature screens
 
+{{#cap parallel-subagents}}
 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 (live capture + locale switch detection) run **once per screen** — the mechanism is the same. Phase 4 (text diff) runs per feature because each has its own scope of UI.
+{{/cap}}
+{{^cap parallel-subagents}}
+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.
+{{/cap}}
 
 ## 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.
+{{#cap parallel-subagents}}
 - Do not write a separate selectors file per locale (`home.en.yaml`). One selectors file with `{{var}}` works across all locales — that's the whole point.
 - Do not delete keys from the base `test-data/<feature>.yaml`. Always append. Existing tests rely on base values being complete.
 - Do not run tests in this skill. Hand off to `/sungen:run-test` for execution.
+{{/cap}}
+{{^cap parallel-subagents}}
+- 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`.
+{{/cap}}
 - Do not commit. Hand off to user.
 
+{{#cap parallel-subagents}}
 ## Memory link
 
 Related: [[saa-auth-blocker]] — Live mode will not work on SAA staging while the upstream Supabase `persistSession: false` issue is open. Default to Offline mode on SAA until that ships.
+
+{{/cap}}

package/{src/orchestrator/templates/ai-instructions/github-skill-sungen-selector-fix.md → dist/orchestrator/templates/ai-src/skills/sungen-selector-fix/SKILL.md}

@@ -48,13 +48,23 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
 
 ### Steps
 
+{{#cap parallel-subagents}}
+1. **Confirm with the user** via `AskUserQuestion`: *"Generate selectors from the live page via Playwright MCP now?"* — offer **Yes, scan live page** / **Skip (use existing selectors.yaml)** / **Cancel**.
+{{/cap}}
+{{^cap parallel-subagents}}
 1. **Confirm with the user**: *"Generate selectors from the live page via Playwright MCP now?"* — offer **Yes, scan live page** / **Skip (use existing selectors.yaml)** / **Cancel**.
+{{/cap}}
 2. **Collect references**: parse the `.feature` file for every `[Reference]` element + its type (e.g. `[Submit] button`, `[Email] field`). Deduplicate.
 3. **Ensure page selector**: if missing, ask user for URL path and write it first.
 4. **Navigate**:
    - Read `baseURL` from `playwright.config.ts`.
    - `browser_navigate` to the page URL.
+{{#cap parallel-subagents}}
+   - If redirected to login → run **Phase 0.5: Auth Persistence** first (see below), then re-navigate to the target page.
+{{/cap}}
+{{^cap parallel-subagents}}
    - If redirected to login → **ask the user to log in manually in the MCP browser**, wait for confirmation, then continue. Never use `sungen makeauth`. Never inject cookies via `browser_evaluate`.
+{{/cap}}
 5. **Snapshot**: Wait for the page to fully load before snapshotting.
    - Check if the page is still loading (spinner visible, skeleton placeholders, empty table with 0 rows). If so, use `browser_wait_for` to wait until content is rendered.
    - Then take **ONE** `browser_snapshot`. All Phase 0 selectors come from this single snapshot.
@@ -90,6 +100,7 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
 
 ---
 
+{{^cap parallel-subagents}}
 ## Phase 0 (Provisional): Figma-Only Selector Generation (no live page)
 
 **Trigger**: Phase 0 decision tree (in `run-test` command) determined the live page is not reachable AND `requirements/spec_figma.md` exists.
@@ -151,6 +162,7 @@ When `run-test` is called again and the live page is now reachable:
 
 ---
 
+{{/cap}}
 ## Phase 0.5: Auth Persistence (MCP alternative to `sungen makeauth`)
 
 Capture an authenticated session from the MCP browser into `specs/.auth/<role>.json` — the same path `sungen makeauth` writes to, which compiled tests already reference via `test.use({ storageState })` based on `@auth:<role>` tags. No `playwright.config.ts` edits needed. Run once per auth lifetime, not on every selector fix.
@@ -168,7 +180,12 @@ Skip if `specs/.auth/<role>.json` already exists and a probe navigation reaches
 1. **Resolve the role**:
    - Look at the `.feature` file for `@auth:<role>` tags (feature-level or scenario-level). Pick the role for the scenario being run. If no tag exists, default to `user`.
    - Target file: `specs/.auth/<role>.json`. Create `specs/.auth/` if missing.
+{{#cap parallel-subagents}}
+   - If the file already exists → use `AskUserQuestion` to confirm overwrite (mirrors the `(y/N)` prompt in `sungen makeauth`).
+{{/cap}}
+{{^cap parallel-subagents}}
    - If the file already exists → confirm overwrite with the user (mirrors the `(y/N)` prompt in `sungen makeauth`).
+{{/cap}}
 2. **Navigate to login**:
    - Read `baseURL` from `playwright.config.ts` (fall back to `APP_BASE_URL` env, then `http://localhost:3000` — same resolution order as `sungen makeauth`).
    - `browser_navigate` to `<baseURL>/login`. If the app uses a different login path, ask the user.

package/dist/orchestrator/templates/{ai-instructions/claude-skill-selector-fix-mobile.md → ai-src/skills/sungen-selector-fix-mobile/SKILL.md}

@@ -23,7 +23,12 @@ Populate `selectors.yaml` from the live app before compiling so tests don't fail
 - User re-scans after a UI change.
 
 ### Steps
+{{#cap parallel-subagents}}
 1. **Confirm** via `AskUserQuestion`: *"Generate selectors from the live app via Appium MCP now?"* —
+{{/cap}}
+{{^cap parallel-subagents}}
+1. **Confirm**: *"Generate selectors from the live app via Appium MCP now?"* —
+{{/cap}}
    **Yes, scan device** / **Skip (use existing)** / **Cancel**.
 2. **Collect references**: parse the `.feature` for every `[Reference]` + type. Deduplicate.
 3. **Launch the app** (delegate to `sungen-capture-mobile` or inline):

package/dist/orchestrator/templates/{ai-instructions/claude-skill-tc-generation.md → ai-src/skills/sungen-tc-generation/SKILL.md}

@@ -9,7 +9,12 @@ user-invocable: false
 - **Write incrementally — never emit the whole suite in one response.** Build the `.feature` in batches via successive `Write`/`Edit` (≈10–15 scenarios per call). For **Full coverage**, write tier-by-tier: `Write` Tier 1 → `Edit` append Tier 2 → `Edit` append Tier 3.
   → One huge `Write` can exceed the model's output-token cap → `API Error: Claude's response exceeded the N output token maximum`. Single-pass full coverage only fits when `CLAUDE_CODE_MAX_OUTPUT_TOKENS ≥ 64000`; otherwise batch. Batching also lets the audit/reviewer run per batch — higher quality.
 
+{{#cap parallel-subagents}}
 - **Sharded (parallel) generation — keep each shard self-contained.** When `create-test` fans out one `sungen-generator` sub-agent per shard (a viewpoint theme like `VP-SEC`, or a `spec.md` section — see create-test Steps 5a–5c), you are generating **only your shard**: emit your scenarios under **your own `VP-` prefix** (disjoint namespace, so ids never collide), as a **headerless fragment** (no `Feature:` line — the orchestrator owns the single header). Do not reference or renumber other shards. The orchestrator concatenates fragments in stable order (spec-section / theme order), dedups by title, and unions test-data. Small fragments also stay under the output-token cap by construction.
+{{/cap}}
+{{^cap parallel-subagents}}
+- **Generate group-by-group (sequential here).** Copilot has no sub-agents, so generate one viewpoint group/theme at a time, tier-by-tier, keeping each `VP-` theme in its own id prefix. (The Claude Code variant fans these out as parallel `sungen-generator` shards and merges — same output shape, just no speedup. Keep each theme self-contained so it would merge cleanly either way.)
+{{/cap}}
 
 - `spec_figma.md` exists → read file only, **NEVER** call `mcp__figma__*`
   → PAT auth flow already done by `sungen-capture` (mode figma-pat); re-calling fails or duplicates work.

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

@@ -37,14 +37,17 @@ export default defineConfig({
   testDir: './specs/generated',
   /* Output directory for test artifacts (screenshots, videos, traces). */
   outputDir: './test-results',
-  /* Run tests in files in parallel */
-  fullyParallel: true,
+  /* Sequential by default. Scenarios are per-scenario ISOLATED (each test gets a fresh page), so a
+     failure never cascades — but we run one-at-a-time (workers: 1) so a heavy live site isn't hit by
+     concurrent workers (which causes flaky timeouts / ad-consent races). Once your suite is stable
+     and your target tolerates concurrency, raise `workers` (and set `fullyParallel: true`) for speed. */
+  fullyParallel: false,
   /* Fail the build on CI if you accidentally left test.only in the source code. */
   forbidOnly: !!process.env.CI,
   /* Retry on CI only */
   retries: process.env.CI ? 2 : 0,
-  /* Opt out of parallel tests on CI. */
-  workers: process.env.CI ? 1 : 2,
+  /* One worker → sequential execution, no cross-test contention on the target site. */
+  workers: 1,
   /* Global timeout per test */
   timeout: 15_000,
   /* Reporter to use. See https://playwright.dev/docs/test-reporters */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.2",
+  "version": "3.2.3-beta.3",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,7 +12,7 @@
     "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && mkdir -p dist/generators/test-generator/adapters/appium/templates/steps && cp -r src/generators/test-generator/adapters/appium/templates/*.hbs dist/generators/test-generator/adapters/appium/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/appium/templates/steps dist/generators/test-generator/adapters/appium/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html && mkdir -p dist/harness/catalog && cp src/harness/catalog/*.yaml dist/harness/catalog/",
     "build:dashboard": "cd ../../dashboard && npm install --silent && npm run build && cd - && cp ../../dashboard/dist/index.html src/dashboard/templates/index.html",
     "dev": "tsx src/cli/index.ts",
-    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/exporter/feature-parser-category.run.ts && tsx tests/exporter/api-detail-sheet.run.ts && tsx tests/api-runtime/base-path-url-join.run.ts && tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/packaging/run.ts",
+    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/exporter/feature-parser-category.run.ts && tsx tests/exporter/api-detail-sheet.run.ts && tsx tests/exporter/mobile-app-id.run.ts && tsx tests/api-runtime/base-path-url-join.run.ts && tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/packaging/run.ts && tsx tests/generate-hint/run.ts && tsx tests/template-assertion/run.ts && tsx tests/journey/run.ts && tsx tests/harness/serial-cascade.run.ts && tsx src/orchestrator/ai-skills/golden-skills.test.ts",
     "test:update": "tsx tests/golden/run.ts --update && tsx tests/audit/run.ts --update && tsx tests/ingest/run.ts --update",
     "prepublishOnly": "npm run build:dashboard && npm run build"
   },
@@ -33,7 +33,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@sungen/driver-ui": "3.2.2",
+    "@sungen/driver-ui": "3.2.3-beta.3",
     "@anthropic-ai/sdk": "^0.71.0",
     "@babel/parser": "^7.28.5",
     "@babel/traverse": "^7.28.5",