@sun-asterisk/sungen 3.2.24 → 3.2.26

package/src/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -36,7 +36,7 @@ AND    →  inherits from preceding keyword
 
 ```
 User is on [T] page | page with {{v}} | dialog
-User fill [T] field | textarea | search | slider | date-picker with {{v}}
+User fill [T] field | textarea | search | slider | date-picker with {{v}}   # date-picker: web only unless qa/app.yaml declares widgets.datepicker — appium refuses it
 User fill [T] uploader with {{f}}                                    [web]
 User clear [T] field
 User check [T] checkbox | toggle | radio
@@ -104,13 +104,23 @@ two content-filtered queries can hit different rows if the table re-renders in b
 # 1. Visibility: User see [T] type (NEVER add "is visible") | is hidden
 # 2. Text (toHaveText): User see [T] message | header | label with {{v}}
 # 3. Partial (toContainText): User see [T] text contains {{v}}
-# 4. Input (toHaveValue): User see [T] field | dropdown | date-picker | search | slider with {{v}}
+# 3b. Format (shape, not value): User see [T] label matches "yyyy/mm/dd ~ yyyy/mm/dd"
+# 4. Input (toHaveValue): User see [T] field | date-picker | search | slider with {{v}}
+#    dropdown | select | combobox → tag probed at runtime (toHaveValue native, toHaveText custom trigger)
 # 5. State: User see [T] button is disabled | checkbox is checked | dialog with {{v}} is hidden
 # 6. Attribute (toHaveAttribute): User see [T] image | link with {{v}}
 # 7. Count: User see [T] row with {{count}}
 # 8. Page: User see [T] page | page with {{url}}   ← `with` also asserts the query string
+#    NEVER a state: `page is hidden` / `page is empty` … are NOT step forms (see Pattern 8 below)
 ```
 
+> **`page` takes NO state clause.** The only two forms are `see [T] page` and `see [T] page with
+> {{url}}`. `see [X] page is hidden` is not a supported step: `page` compiles to a URL assertion, so
+> the clause is dropped and the step asserts the page IS displayed — the opposite of what it reads
+> as. The compiler now rejects it (`SG-E021`) instead of generating that. To say "we left page X",
+> assert the page you expect (`Then User see [Other] page`); to say "this went away", assert a marker
+> element (`Then User see [Some Element] is hidden`).
+
 **Pattern 8 — the page assertion judges pathname AND query together.** Both `see [T] page` and
 `is on [T] page` (Then-side) compile to ONE web-first predicate — `toHaveURL(urlMatches({…}))`,
 which retries like any other assertion — comparing the **exact** pathname (anchored, trailing slash
@@ -197,7 +207,31 @@ Then User see key matching "PATTERN" in local storage      # regex over key name
 # same five forms with `session storage`
 ```
 
-`[KEY]` is a **storage key, not a selector** — never add it to selectors.yaml. It may embed `{{vars}}`: `[{{exclusive_code}}_ACCESS_TOKEN]`. The check runs inside the browser and returns only a boolean, so a failure message never contains the stored value (safe for tokens). There is deliberately no `equals {{expected}}` form. ⚠️ `expect [KEY] in local storage …` is NOT valid (`expect` reads `{{response}}` refs only) — the compiler warns SG-W011.
+`[KEY]` is a **storage key, not a selector** — never add it to selectors.yaml. It may embed `{{vars}}`: `[{{exclusive_code}}_ACCESS_TOKEN]`. **This is the ONLY bracket that accepts a `{{var}}`.** An element `[Reference]` is a selectors.yaml key matched **literally** — it is never interpolated, so `[{{var}}]` for an element is invalid and the compiler rejects it. To target text that varies (locale, `@cases` column), keep the reference static and put the variable in the selector entry's `name:`/`value:` field, or pick by text with `with {{var}}` (`User click [Answer List] item with {{confirm_value}}`). The check runs inside the browser and returns only a boolean, so a failure message never contains the stored value (safe for tokens). There is deliberately no `equals {{expected}}` form. ⚠️ `expect [KEY] in local storage …` is NOT valid (`expect` reads `{{response}}` refs only) — the compiler warns SG-W011.
+
+### Format assertion `see [T] type matches "<format>"`
+
+A spec often states a label's contract as a **shape**, not a value — "Format: yyyy/mm/dd ~ yyyy/mm/dd",
+"Format: 残りX個". Write it verbatim; no regex belongs in a `.feature`:
+
+```gherkin
+Then User see [Application Period] label matches "yyyy/mm/dd ~ yyyy/mm/dd"
+Then User see [Remaining Stock] label matches "残りX個"
+Then User see [Total Plans] label matches "*X件"
+```
+
+| Token | Matches | | Token | Matches |
+|---|---|---|---|---|
+| `yyyy` | a 4-digit year | | `X` | an integer, `1,280` allowed |
+| `mm` `dd` `hh` `ss` | a zero-padded 2-digit part | | `*` | any run of characters |
+
+Everything else is a **literal**. The match is **anchored** — `"X件"` is not satisfied by `12件です`;
+use `*` where the label legitimately carries more (a mobile node that fuses a prefix and its count,
+`開催中の企画\n2件` → `"*X件"`). A token glued to an ASCII letter stays literal, so `"Comment: X件"`
+keeps its `mm`.
+
+Use this instead of `with {{v}}` when the VALUE varies but the SHAPE is the requirement: an exact
+value pins data that changes daily (red while the app is right), and `contains` passes on anything.
 
 ### Tab order `[web]`
 
@@ -307,8 +341,13 @@ Full-shape contract check: `expect {{name.body}} matches schema [Ref]` validates
 ### Platform Support — web-only / mobile-only / divergences
 
 Every claim below is checked against a shipped `.hbs` under
-`adapters/{playwright,appium}/templates/steps/` or a shipped diagnostic — see
-`tests/codegen/adapter-template-parity.run.ts` `DIVERGENCES` for the authoritative one-sided list.
+`adapters/{playwright,appium}/templates/steps/` or a shipped diagnostic. The authoritative
+per-template answer is **generated from the adapters themselves** — `docs/spec/step-support-matrix.md`
+(regenerate: `npm run gen:step-matrix`; `DIVERGENCES` lives in `tools/step-support-matrix/sources.ts`). Read
+it when this prose and the compiler seem to disagree: the matrix is derived, this section is authored.
+
+The matrix maps **templates**, not phrasings — a phrasing no pattern requests is absent from it
+entirely (a *pattern* gap, not a template gap), which is what the catalogue below is for.
 
 **Web-only `[web]`** — the Appium template throws, naming the reason: `fill [T] uploader with
 {{f}}`, Positional table rows, the whole Table section, Browser storage, Tab order, `@mock`,
@@ -355,6 +394,10 @@ zero-match assertion failure, not a platform gap.
 | Group | Types |
 |---|---|
 | **Context** | `page` `dialog` `modal` `drawer` `tab` `alert` `overlay` `step` |
+
+> `page` is the one Context type with **no state**: `dialog`/`modal`/`drawer`/`tab` etc. all take
+> `is hidden` / `is visible`, `page` never does. It asserts a URL. See Pattern 8.
+
 | **Input** | `field` `textarea` `search` `dropdown` `option` `checkbox` `radio` `toggle` `uploader` `slider` `date-picker` |
 | **Trigger** | `button` `link` `icon` `menuitem` `tag` |
 | **Data** | `table` `row` `column` `cell` `list` `item` `card` `section` |
@@ -443,12 +486,68 @@ on mobile a dialog-scoped ref still resolves against the whole screen (`SG-W021`
 | `@afterEach` | Hook: runs after each test → `test.afterEach()` (custom cleanup) |
 | `@afterAll` | Hook: runs once after all tests → `test.afterAll()` |
 | `@flow` | Mark feature as E2E flow (cross-screen testing) |
+| `@reset:none\|soft\|data\|full` | **`[mobile]`** How much state each scenario starts from. Default `soft`. Feature-level, or on a Scenario to RAISE (never lower) that one scenario's tier. See "Reset tiers" below |
 | `@cases:dataset` | Data-driven: run the scenario once per row of the `dataset` LIST in test-data → one `test()` per row |
 | `@query:name` | Database: run the named query from `database/queries.yaml` (precondition) and bind its rows to `{{name}}`; assert with `expect {{name.count}} …` + path access. Override params `@query:name(p={{v}})`. Repeatable. (Optional Data Driver — see Database verification above) |
 | `@api:name` | API: run the named request from `api/apis.yaml` (precondition) and bind the response to `{{name}}`; assert with `expect {{name.status}} …` + path access (`{{name.body.<path>}}`). Override params `@api:name(p={{v}})`. Repeatable. (Optional API Driver) |
 | `@concurrent:N` | API idempotency: fire the bound `@api` request N times in parallel, then bind aggregates on the `@api` name — `{{name.ok_count}}` (2xx count) and `{{name.status_counts}}` (status→count map). Assert the exactly-once invariant (`expect {{name.ok_count}} is 1`); pair with `@query` as a DB oracle. Tag order = run order: `@api` (mutate) before `@query` (verify). (Optional API Driver) |
 | `@hybrid` | One unit, two capabilities: a signed-in browser session (UI) authorizes the `@api` call — the API request reuses the UI `storageState`. (Optional API + UI Drivers) |
 
+### Reset tiers (`@reset`) `[mobile]`
+
+Web gets a clean slate for free — a URL reload is effectively fresh state. Mobile does not: to save
+time the app stays alive across the whole session, so the end state of one scenario becomes the start
+state of the next. Left uncontrolled that breaks test independence (scenarios can't run in isolation
+or in parallel, a leftover "nearly right" state makes the FOLLOWING scenario fail, and a scenario that
+dies mid-flow poisons every one after it). Nobody just reinstalls between scenarios because a cold
+start is 5–30s — hence a ladder rather than one all-or-nothing switch.
+
+| Tier | Mechanism | Cost | Clears |
+|---|---|---|---|
+| `none` | nothing — only the NATIVE-context + portrait guards | 0s | — state carries over BY DESIGN |
+| `soft` | `terminateApp` + `activateApp` — **the default** | ~1–3s | in-memory state, navigation stack |
+| `data` | `soft` + wipe the app's data layer | ~2–5s | + local DB, cache, prefs, keychain |
+| `full` | `removeApp` + `installApp` | ~5–30s | + permissions, install-time state |
+
+```gherkin
+@platform:mobile @reset:data
+Feature: Onboarding
+  Path: com.example.app/.MainActivity | com.example.app
+
+  Scenario: VP-001 First-run tutorial shows for a brand-new user
+    Then User see [Tutorial Slide 1] section
+
+  @reset:full
+  Scenario: VP-002 Needs a clean install, unlike its neighbours
+    Then User see [Permission Prompt] dialog
+```
+
+Rules that matter when generating:
+
+- **`soft` is the default** — omit the tag unless the scenario actually needs more. An untagged
+  feature behaves exactly as it always did.
+- **Pick `data` for first-run / onboarding / empty-state oracles.** A plain relaunch leaves a
+  completed tutorial completed, so the scenario passes on run 1 and fails on run 2.
+- **Pick `full` only for permissions or install-time state.** It costs a cold start every scenario.
+- **Pick `none` only for a deliberate carryover chain** (a cart accumulating across scenarios). Order
+  becomes load-bearing, and the scenarios can no longer run independently — that is the trade.
+- **A scenario tier RAISES the feature tier, never lowers it.** A `@reset:full` feature is not weakened
+  by a `@reset:soft` scenario; use a separate feature if you need a weaker one.
+- **A failed scenario escalates the NEXT one by one rung** (`soft`→`data`→`full`), because a process
+  relaunch does not undo a half-written local DB. One rung, one scenario, and never from `none`.
+  A **retry** of the failed scenario is NOT escalated — it re-runs at its declared tier, so a
+  state-dependent failure fails both attempts and is reported honestly instead of passing on attempt 2.
+- **`SUNGEN_RESET_TIER=data` raises the floor for a whole run** without regenerating specs — CI can run
+  stricter than local dev. It never lowers a declared tier.
+- **`data`/`full` on iOS reinstall the app**, because `mobile: clearApp` is Android-only (UiAutomator2).
+  That needs `IOS_APP` (or `APP_APK` on Android) so the `appium:app` capability is present, or the
+  reset throws naming it.
+- **`data` and `full` wipe app data on the target device.** Emulator / dedicated test device only.
+
+Mobile app-state preconditions have no per-step equivalent: `Given the user is logged out` compiles to
+a COMMENT on Appium (auth lives in the keychain, not in cookies) and reports **SG-W023**. Declare
+`@reset:data` on the Feature instead of writing a step that establishes nothing.
+
 ### Data-driven scenarios (`@cases`)
 
 For one test case × many inputs (email/format/boundary validation, decision tables), tag the
@@ -575,7 +674,7 @@ dashboard:
 
 - Tool executes **only Given→When** of `@steps` scenario (skips Then)
 - The `Given` in `@extend` scenario is the **entry assertion** (confirms state after base steps)
-- **Entry assertion MUST use `Given User is on [X] type`** — NEVER `Given User see [X] type`
+- **Entry assertion MUST use `Given User is on [X] page`** (or `[X] dialog`) — NEVER `Given User see [X] type`. `is on` takes ONLY `page` (`screen` on mobile) and `dialog`: it names a navigation target. For a state inside the current page (a wizard step, a panel) assert it with `Then User see [X] section` and reach it via the flow's When steps or an `@steps`/`@extend` base — the compiler rejects `is on [X] <other type>`.
 - `Given` keyword ONLY allows `is on` action. `see` = `Then` only.
 - If `@steps` scenario fails, `@extend` scenario is **skipped**
 - Name format: `snake_case` or `kebab-case` with module prefix: `@steps:kudos__open_modal`
@@ -593,6 +692,11 @@ dashboard:
 | Hardcode data | `with {{admin@mail.com}}` | `with {{invalid_email}}` |
 | Missing `is` for state | `with {{text}} hidden` | `with {{text}} is hidden` |
 | State as value | `with {{disabled}}` | `is disabled` |
+| State on a `page` | `Then User see [Home] page is hidden` | `Then User see [Other] page` — or assert a marker element: `Then User see [Home Banner] is hidden`. `page` asserts a URL; the clause is dropped and the assertion INVERTS. Rejected by `SG-E021` |
+| State the step form cannot assert | `wait for [X] spinner is checked` · `see [R] row in [T] table with {{v}} is disabled` | Assert the state on the element itself: `Then User see [X] checkbox is checked`. A `wait` only honours `hidden`/`visible`/`disabled`/`enabled`; a row/column step only honours `is hidden`. Anything else is dropped → `SG-E021` |
+| Invented step form | any sentence with no matching pattern | Use a form from this reference. There is no silent fallback any more — an unmatched step compiles to a runtime `throw` (`SG-W001`). If the check cannot be automated, tag the scenario `@manual` |
+| Assertion clause the pattern drops | `Then User see [Code] text matches "<format>"` compiling to a bare `toBeVisible()` | Use the exact supported phrasing for the clause (see the `matches` / `contains` / `has text` forms above). A clause that gets swallowed leaves an assertion that passes whatever the element says, so the step is rejected with `SG-E023` instead. If the step still compiles bare, you are on an older global sungen — run `npx sungen` |
+| Mobile lifecycle step with no app id | `When User restart the app` in a feature whose `Path:` carries only a route | Declare the app id on the Feature: `Path: com.example.app/.MainActivity \| com.example.app`. The lifecycle steps resolve the app from `Path`; without it the whole spec would die at runtime, so the step is rejected with `SG-E024`. For a mobile unit `--path` carries the APP ID, `--reach` carries the navigation recipe |
 | Missing target type | `fill [email] with {{v}}` | `fill [email] field with {{v}}` |
 | Background with scope | `Background: ... And User is on [X] dialog` | Use `@steps` + `@extend` for scope-dependent flows |
 | `is on` after When | `When ... And User is on [X] dialog` | `And User see [X] dialog` or separate Given |

package/src/orchestrator/templates/ai-src/skills/sungen-locale/SKILL.md

@@ -575,7 +575,7 @@ If the screen has multiple `.feature` files (e.g. `home.feature` + `home-modal.f
 
 ## 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 edit `.feature` files. Their `[Target]` labels are locale-stable keys — they are matched literally and must NOT be turned into `[{{var}}]`. Localised text lives in the selector entry's `name:`/`value:`, so 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.

package/src/orchestrator/templates/ai-src/skills/sungen-mobile-gestures/SKILL.md

@@ -43,6 +43,14 @@ patterns (`click`, `hover`, `fill`) don't cover.
 > - **`reinstall the app`** → remove → install from the session's build file → launch. **Requires
 >   the session to have installed via `APP_APK` / `IOS_APP`** (the `appium:app` cap) — attaching by
 >   package only makes the step fail loud with that exact fix in the message.
+>
+> **These two are IN-scenario steps. Reset BETWEEN scenarios is a tag, not a step** — `@reset:` on the
+> Feature (`none` · `soft` = default · `data` · `full`), which runs in the `beforeEach` hook. Reach for
+> the tag when the whole suite needs a cleaner starting state, and for these steps when one scenario's
+> ORACLE is "does this survive a restart / a reinstall". Writing a step to establish app state does not
+> work on mobile: `Given the user is logged out` compiles to a comment (auth lives in the keychain, not
+> in cookies) and reports **SG-W023** — declare `@reset:data` instead. Full tier table + trade-offs:
+> `sungen-gherkin-syntax` → "Reset tiers".
 > - **`turn airplane mode|wifi|mobile data on|off`** → `mobile: setConnectivity`. **Android-only** —
 >   XCUITest cannot toggle connectivity; on iOS the step throws loud. Keep such scenarios
 >   `@platform:android`. Do NOT author cleanup steps to restore connectivity "in case the test

package/src/orchestrator/templates/ai-src/skills/sungen-selector-fix/SKILL.md

@@ -57,7 +57,7 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
 2. **Collect references**: parse the `.feature` file for every `[Reference]` element + its type (e.g. `[Submit] button`, `[Email] field`). Deduplicate.
 
    ⛔ **Non-selector bracket refs — never hunt the DOM for these, never write a selectors.yaml entry:**
-   - `[KEY] in local storage …` / `[KEY] in session storage …` — a **storage key**, checked via `page.evaluate`, not an element (the key may embed `{{vars}}`, e.g. `[{{code}}_ACCESS_TOKEN]`).
+   - `[KEY] in local storage …` / `[KEY] in session storage …` — a **storage key**, checked via `page.evaluate`, not an element (the key may embed `{{vars}}`, e.g. `[{{code}}_ACCESS_TOKEN]` — this is the ONLY bracket that accepts one; an element `[Reference]` is matched literally and `[{{var}}]` is rejected by the compiler).
    - Bracket refs consumed by other non-DOM step families (`@mock` route refs) follow the same rule: if the step's grammar does not target a UI element, the bracket content is NOT a selector.
    Writing a fabricated entry for these breaks the real step (the pattern parses the bracket itself) and pollutes selectors.yaml.
    ✅ **Tab-order table cells ARE selector refs** — each `| [Ref] |` row under `Then User see tab order:` resolves through selectors.yaml like any element (verify them once; they are the same refs the scenario's other steps use — don't double-count them as new elements).

package/src/orchestrator/templates/ai-src/skills/sungen-tc-generation/SKILL.md

@@ -449,6 +449,15 @@ Cross-pattern: `@high` by default.
 
 ---
 
+## Format over value
+
+When the spec states a label's contract as a **shape** ("Format: yyyy/mm/dd ~ yyyy/mm/dd", "Format: X件", "Format: 残りX個"), generate `matches "<format>"` — never `with {{v}}`. An exact value pins data that changes daily (red while the app is right); `contains` proves nothing. Tokens: `yyyy mm dd hh ss X *`. Anchored — use `*` when a node fuses a prefix with the value. See `sungen-gherkin-syntax` → Format assertion.
+
+```gherkin
+Then User see [Application Period] label matches "yyyy/mm/dd ~ yyyy/mm/dd"
+Then User see [Total Plans] label matches "*X件"
+```
+
 ## Priority Tags
 
 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.
@@ -709,7 +718,7 @@ flows:
     branchFrom: "BF step 1, the control tapped twice"
     outcome: "One request, one record"
     status: pending-clarification      # the spec is silent — ASK, never assume a guard
-    reason: "The guard lives in ST_AUTH_001's spec, which this project does not hold."
+    reason: "The guard lives in SCREEN_A_001's spec, which this project does not hold."
 ```
 
 Four statuses, and **silence is not one of them**: `covered` · `deferred` · `pending-clarification`
@@ -719,6 +728,36 @@ missing flow. `sungen audit` then measures `flowCoverage` per DECLARED FLOW and
 `FLOW-UNCOVERED` (declared, nobody wrote it), `FLOW-UNDECLARED` (a scenario claiming a flow id the
 inventory never declares), `FLOW-STATUS-UNREASONED` and `FLOW-INVENTORY-MISSING`.
 
+**Enumerate every branch the spec declares — do not rely on reading carefully.** Before writing
+scenarios, list each mutually-exclusive branch the spec makes explicit, one line per arm:
+
+- every `### Exception Flow X` / `### Alternative Flow X` heading;
+- every row of a decision table (`DEC-*`, `BR-*`, any table of conditions → outcomes);
+- every arm of an if/elif/else cascade in pseudocode;
+- every state transition a state machine declares.
+
+Each arm needs its OWN scenario, or a written exclusion. **Covering a sibling arm proves nothing
+about this one** — and two scenarios that assert the same thing under different names are one test
+counted twice, which is worse than a gap because the coverage sheet reports it as two.
+`sungen audit` reports `SPEC-BRANCH-UNCOVERED` and `BRANCH-OVERCLAIMED`. This rule existed as
+prose before and was missed three times in three flows; it is enumerated now for that reason.
+
+**Two viewpoints per UI region, not one.** A region that has both conditional rendering (`DEC-*`)
+and an acceptance scenario describing a click needs a case for EACH: "render — DEC-xxx" and
+"interaction — click → destination". Finishing the render half is the easy half, and stopping there
+is the common failure. Every navigation target the spec names needs a click-through case
+(`NAV-TARGET-ABSENT`), even when this flow does not consume the destination — a context param
+handed to another screen is that screen's input, and the handoff is where it goes wrong.
+
+**A deny case needs its allow case.** "permission denied → content hidden" passes just as happily
+when the content is hidden for everyone. Pair it with "permission granted → content shown", the
+way a boundary needs `min-1 / min / max / max+1` (`PERMISSION-PAIR-MISSING`).
+
+**State that ARRIVES with the data is a different case from state the test creates.** A
+discriminator field you can only observe at load (an item already favourited before the page
+opens) is a different oracle timing from the same field set by an action inside the test. Both are
+needed; the first is usually `@manual:M1` or a data-factory fixture.
+
 **One id per atomic CLAIM in the viewpoint.** The flow id groups; the viewpoint id identifies.
 Writing `FL-BF-001` on four different claims makes the ledger count four items while traceability
 sees one, so the coverage arithmetic and "which test proves this?" are both wrong and neither

package/src/orchestrator/templates/ai-src/skills/sungen-tc-review/SKILL.md

@@ -46,7 +46,12 @@ Hard-fail gate. Any ✗ is a syntax error — must be fixed; do not score furthe
 - [ ] `Given` → only `is on` · `When` → action (click/fill/select/press/clear/check/uncheck/hover/wait) · `Then` → only `see` · `And` inherits the preceding keyword
 - [ ] NO `Given User see…` (→ `Then`, or entry assertion `Given User is on [X] page`)
 - [ ] NO `When … And User is on [X] dialog` (→ `And User see` or a separate `Given`)
+- [ ] `dismiss [X]` is SETUP, never proof — it is best-effort and never fails, so a scenario that
+      claims an overlay closed must assert it: `Then User see [X] is hidden` (mobile: tap the
+      close/scrim node explicitly, then assert)
+- [ ] `is on` takes ONLY `[X] page` (`[X] screen` on mobile) / `[X] dialog` — `is on [X] step|section|card` ✗ (it compiles to a real navigation, or to a URL assertion that cannot fail). A state inside the page → `Then User see [X] section`.
 - [ ] NO literal-URL navigation (`navigate to "/x"`) → `User is on [X] page` + declare in `selectors.yaml`
+- [ ] NO `{{var}}` inside a `[Target]` (`[{{confirm_value}}]` ✗) — a target is a selector key matched literally. For text that varies (locale, `@cases` column) keep the target static and move the variable into the selector entry's `name:`/`value:`, or pick by text with `with {{var}}`. Only a browser-storage key may embed one.
 
 ### A2. Action → Element type
 
@@ -67,6 +72,16 @@ Hard-fail gate. Any ✗ is a syntax error — must be fixed; do not score furthe
 ### A4. Assertion (8 patterns → determines the Playwright assertion)
 
 - [ ] Visibility `see [T] type` → NO redundant `is visible`; hidden uses `is hidden`
+- [ ] **No state clause on `[T] page`** — `page is hidden`/`is empty`/… are not step forms. `page`
+      asserts a URL, so the clause is dropped and the assertion inverts (`SG-E021`). Assert the
+      expected page, or a marker element
+- [ ] **The state is one the step form can actually assert** — a `wait for` honours only
+      `hidden`/`visible`/`disabled`/`enabled`; `row in [T] table` / `column in [T] table` honour
+      only `is hidden`. Anything else is dropped (`SG-E021`) — move the state onto the element
+- [ ] **No invented step forms** — every step matches a pattern in `sungen-gherkin-syntax`. An
+      unmatched step compiles to a runtime `throw` (`SG-W001`), never a silent pass; park a
+      genuinely unautomatable check as `@manual`
+- [ ] A spec `Format:` line → `matches "<format>"`, NOT `with {{v}}` (an exact value pins data that changes daily; `contains` proves nothing)
 - [ ] Correct pattern: text(`message/header/label with {{v}}`) · partial(`text contains {{v}}`) · input(`field/dropdown with {{v}}`) · state(`is …`) · attribute(`image/link with {{v}}`) · count(`row with {{count}}`) · page(`[T] page`)
 - [ ] Table: `[Col] column in [Table] table`, `[Ref] row in [Table] table with {{v}}`, `table with {{count}}`/`is empty`, `table match data:`; row scope used correctly
 

package/src/orchestrator/templates/env.appium.example

@@ -24,6 +24,16 @@ JAVA_HOME=/opt/homebrew/opt/openjdk@21
 # IOS_BUNDLE_ID=<ios bundle id>      # REQUIRED — the iOS bundle (⚠ NOT the Android package)
 # IOS_TEAM_ID=<Apple Team ID>        # REQUIRED — 10-char id (Xcode → Settings → Accounts)
 
+# ════════════ State reset between scenarios ════════════
+# Raises the reset floor for a WHOLE run without regenerating any spec — CI can run stricter than
+# local dev. It never LOWERS a tier a feature declared with @reset:. Tiers, weakest → strongest:
+#   none  nothing reset (state carries over by design)      0s
+#   soft  terminate + relaunch — THE DEFAULT               ~1–3s
+#   data  + wipe local DB / cache / prefs / keychain        ~2–5s   (iOS: reinstalls, needs IOS_APP)
+#   full  + remove and reinstall (permissions too)          ~5–30s  (needs APP_APK / IOS_APP)
+# ⚠ data and full WIPE APP DATA on the target device — emulator / dedicated test device only.
+# SUNGEN_RESET_TIER=data
+
 # ════════════ Appium server security (opt-in) ════════════
 # Allow `mobile: shell` (raw adb passthrough) for device-level oracles (e.g. pulling an app's
 # SQLite DB via run-as). Starts the server with --allow-insecure=uiautomator2:adb_shell.

package/src/orchestrator/templates/specs-api.ts

@@ -58,6 +58,124 @@ function substitute(text: string, params: Record<string, any>): string {
 function substituteRaw(text: string, params: Record<string, any>): string {
   return text.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_m, p) => String(params[p] ?? ''));
 }
+
+/** The five predefined XML entities — a bound value containing a bare `&` or `<` would
+ *  otherwise re-create exactly the invalid_xml rejection this encoding exists to avoid. */
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Bind `:param` tokens into an XML string template by WHITELIST of the passed param
+ * names — a generic `:word` scan would mangle namespace prefixes (soapenv:Envelope).
+ * Longest name first + a word-boundary lookahead so `:id` can never eat the prefix
+ * of `:id_2` or the head of `:idx`. Values are XML-escaped by default; a token the
+ * template wraps as `<![CDATA[:param]]>` binds raw inside its CDATA section instead.
+ * Replacer FUNCTIONS everywhere — a value containing `$&`-style sequences must never
+ * be interpreted as a replacement pattern.
+ */
+function bindXmlParams(template: string, params: Record<string, any>): string {
+  let out = template;
+  for (const name of Object.keys(params).sort((a, b) => b.length - a.length)) {
+    const value = String(params[name] ?? '');
+    // A value containing "]]>" would terminate the CDATA section early and ship
+    // malformed XML — split it across two sections so the document stays valid.
+    const cdataSafe = value.split(']]>').join(']]]]><![CDATA[>');
+    out = out.replace(new RegExp(`<!\\[CDATA\\[:${name}\\]\\]>`, 'g'), () => `<![CDATA[${cdataSafe}]]>`);
+    out = out.replace(new RegExp(`:${name}(?![A-Za-z0-9_])`, 'g'), () => escapeXml(value));
+  }
+  return out;
+}
+
+/** Decode an XML-ish response body: Content-Type charset, else the XML declaration's
+ *  encoding (read from an ASCII-compatible prefix), else UTF-8. Unknown charsets fall
+ *  back to UTF-8 rather than failing the whole request. */
+function decodeXmlAwareText(bytes: Buffer, contentType: string): string {
+  // A UTF-16 BOM means the latin1 declaration scan below would see NUL-laden
+  // garbage that still "parses" \u2014 decode by the BOM first.
+  if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) return new TextDecoder('utf-16le').decode(bytes);
+  if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) return new TextDecoder('utf-16be').decode(bytes);
+  const head = bytes.subarray(0, 200).toString('latin1');
+  const declared = (head.match(/^\uFEFF?\s*<\?xml[^>]*\bencoding=["']([^"']+)["']/i) || [])[1];
+  // Candidates in precedence order; an unsupported CT charset falls back to the
+  // XML declaration's encoding rather than straight to a mojibake UTF-8 decode.
+  const candidates = [(contentType.match(/charset=["']?([^;"'\s]+)/i) || [])[1], declared, 'utf-8'];
+  for (const charset of candidates) {
+    if (!charset) continue;
+    try { return new TextDecoder(charset).decode(bytes); } catch { /* next candidate */ }
+  }
+  return new TextDecoder('utf-8').decode(bytes);
+}
+
+/**
+ * Parse an XML response body to a plain object, or null on a real parse failure (the
+ * caller then keeps the raw string, matching the non-JSON behavior).
+ *
+ * Locked parser posture:
+ *  - processEntities/htmlEntities OFF — fast-xml-parser's entity processing (ON by
+ *    default, including DOCTYPE entities) is exactly the XXE-shaped surface a QA tool
+ *    must not expose to a live server's response. The five predefined entities are
+ *    decoded AFTERWARDS by our own pass.
+ *  - parseTagValue/parseAttributeValue OFF — `<error_code>01000001</error_code>` must
+ *    stay a string; numeric coercion destroys leading zeros.
+ *  - attributes kept with the `@_` prefix (`{{r.body.tag.@_id}}`).
+ *  - repeated elements: XML cannot distinguish "one item" from "a list of one" — the
+ *    catalog declares `arrayPaths:` (dot jpaths INCLUDING the root element) and those
+ *    paths are ALWAYS arrays, so `[0]` access works for 1 and N occurrences alike
+ *    (an EMPTY parent has no child key at all — no array to index).
+ */
+function parseXmlBody(text: string, label: string, arrayPaths?: string[]): any | null {
+  let XMLParser: any;
+  try {
+    // Lazy require: generated projects created before this capability existed don't
+    // have the dep; they must fail with the install command, not MODULE_NOT_FOUND.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    ({ XMLParser } = require('fast-xml-parser'));
+  } catch {
+    throw new Error(`API Driver: ${label} — the response is XML but "fast-xml-parser" is not installed in this project. Run: npm install --save-dev fast-xml-parser`);
+  }
+  const arraySet = new Set(arrayPaths || []);
+  const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: '@_',
+    processEntities: false,
+    htmlEntities: false,
+    parseTagValue: false,
+    parseAttributeValue: false,
+    trimValues: true,
+    isArray: (_name: string, jpath: string) => arraySet.has(jpath),
+  });
+  try {
+    return decodeXmlEntitiesDeep(parser.parse(text));
+  } catch {
+    return null;
+  }
+}
+
+/** Decode the five predefined XML entities in every string leaf (`&amp;` last, so a
+ *  literal `&amp;lt;` decodes to `&lt;` and not further). */
+function decodeXmlEntitiesDeep(value: any): any {
+  if (typeof value === 'string') {
+    return value
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&apos;/g, "'")
+      .replace(/&amp;/g, '&');
+  }
+  if (Array.isArray(value)) return value.map(decodeXmlEntitiesDeep);
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, any> = {};
+    for (const [k, v] of Object.entries(value)) out[k] = decodeXmlEntitiesDeep(v);
+    return out;
+  }
+  return value;
+}
 /** Delete any case-insensitive variant of a header (HTTP header names are case-insensitive, but a
  *  plain object keys on exact case — so a datasource `Content-Type` and our `content-type` would
  *  both be sent). Call before setting, or to let fetch own the header (multipart boundary). */
@@ -94,7 +212,11 @@ function loadStorageStateCookieHeader(storageStatePath: string, url: string): st
   const targetIsSecure = target.protocol === 'https:';
   const matches = cookies.filter((c) => {
     const domain = (c.domain || '').replace(/^\./, '');
-    const domainOk = !domain || target.hostname === domain || target.hostname.endsWith(`.${domain}`);
+    // A cookie with NO domain must match nothing, not everything — Playwright
+    // always records a domain, so a domainless entry only comes from a hand-
+    // edited state file, and treating it as a wildcard would attach the session
+    // cookie to any origin a response-bound absolute URL points at.
+    const domainOk = !!domain && (target.hostname === domain || target.hostname.endsWith(`.${domain}`));
     const pathOk = target.pathname.startsWith(c.path || '/');
     const notExpired = c.expires === undefined || c.expires < 0 || c.expires > nowSec;
     // A Secure cookie must never leave over plaintext. Playwright's own cookie jar enforces this,
@@ -201,22 +323,72 @@ class ApiClient {
    */
   async call(
     label: string,
-    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart'; files?: Record<string, FileSpec | FileSpec[]>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string },
+    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart' | 'xml'; files?: Record<string, FileSpec | FileSpec[]>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string; arrayPaths?: string[] },
     params: Record<string, any> = {},
     opts: { storageState?: string } = {},
   ): Promise<{ status: number; ok: boolean; body: any; headers: Record<string, string> }> {
     const { conf } = this.cfg(req.datasource);
     const base = (conf.base_url || conf.baseUrl || '').replace(/\/$/, '');
     if (!base) throw new Error(`API Driver: ${label} — datasource has no base_url (set it in .env.qa).`);
-    const urlPath = substitute(req.path, params);   // path params (:id) bind at runtime
 
-    const headers: Record<string, string> = { ...(conf.headers || {}) };
+    // Whole-token path (`path: ":url"`): bind RAW and use an absolute http(s)
+    // value directly — an export/download link returned by a prior response
+    // (often on another origin, e.g. blob storage). substitute() would percent-
+    // encode the whole URL into `https%3A%2F%2F…` and joinApiUrl would glue it
+    // onto base_url. Raw binding also keeps presigned query escapes (%2F)
+    // untouched; new URL() is used for VALIDATION only (a response value can be
+    // anything — file:/data: schemes are refused, never fetched).
+    let fullUrl: string;
+    let absolute = false;
+    const wholeToken = req.path.match(/^:([A-Za-z_][A-Za-z0-9_]*)$/);
+    if (wholeToken) {
+      // The bound value MUST be an absolute http(s) URL. Anything else — empty
+      // string (a broken export returning {"url":""}), a relative path, or a
+      // data:/mailto:/file: form — is refused loudly: falling through to the
+      // legacy base_url join would silently GET the API root and let the
+      // scenario false-pass on exactly the failure it exists to catch. (A
+      // whole-token path was never valid before this feature, so there is no
+      // legacy behavior to preserve.)
+      const wholeVal = String(params[wholeToken[1]] ?? '');
+      let parsed: URL | null = null;
+      if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(wholeVal)) {
+        try { parsed = new URL(wholeVal); } catch { parsed = null; }
+      }
+      if (!parsed || (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')) {
+        throw new Error(`API Driver: ${label} — :${wholeToken[1]} must be an absolute http(s) URL (the value is bound from a live response); got: ${JSON.stringify(wholeVal)}`);
+      }
+      if (parsed.username || parsed.password) {
+        throw new Error(`API Driver: ${label} — :${wholeToken[1]} must not carry credentials (user:pass@host): fetch refuses such URLs.`);
+      }
+      // Raw string, not parsed.toString(): URL normalization could rewrite the
+      // presigned query escapes (%2F) the storage host signed.
+      fullUrl = wholeVal;
+      absolute = true;
+    } else if (/^https?:\/\//i.test(req.path)) {
+      // Literal absolute catalog path — its :params (if any) bind with the normal encoding.
+      fullUrl = substitute(req.path, params);
+      absolute = true;
+    } else {
+      fullUrl = joinApiUrl(base, substitute(req.path, params));   // path params (:id) bind at runtime
+    }
+
+    // Cross-origin absolute URL: the datasource's own headers must NOT travel to
+    // another origin — auth tokens, cookies and tenant keys live in conf.headers
+    // with no metadata separating them from benign defaults, so ALL of them stay
+    // home; only headers declared on the entry itself are sent. An unparseable
+    // base counts as a different origin (fail closed).
+    const sameOrigin = !absolute || (() => {
+      try { return new URL(fullUrl).origin === new URL(base).origin; } catch { return false; }
+    })();
+    const headers: Record<string, string> = sameOrigin ? { ...(conf.headers || {}) } : {};
     // catalog headers; :param tokens bind at runtime — raw (no URL-encoding, unlike the path)
     for (const [k, v] of Object.entries(req.headers || {}))
       headers[k] = substituteRaw(String(v), params);
     // Body: substitute `:param` into the body template (object values), then encode per `encoding`.
+    // An XML body is a raw STRING template and binds by param-name WHITELIST below —
+    // the generic whole-value substitution here must not touch it.
     let body: any;
-    if (req.body !== undefined && req.body !== null) {
+    if (req.body !== undefined && req.body !== null && req.encoding !== 'xml') {
       body = JSON.parse(JSON.stringify(req.body).replace(/":([A-Za-z_][A-Za-z0-9_]*)"/g, (_m, p) => JSON.stringify(params[p] ?? null)));
     }
     // Map the wire format to a fetch request body (#345): json → JSON string (application/json,
@@ -244,6 +416,17 @@ class ApiClient {
       // drop any datasource default Content-Type so it doesn't conflict with / duplicate it.
       deleteHeader(headers, 'content-type');
       fetchBody = buildMultipart(req.files, body, params, label);
+    } else if (req.encoding === 'xml' && req.body !== undefined && req.body !== null) {
+      // XML body: the catalog carries a raw string template (any shape — attributes,
+      // namespaces, CDATA, nesting). :params bind by WHITELIST of the passed param
+      // names, never by a generic `:word` scan — that scan would mangle namespace
+      // prefixes (soapenv:Envelope, xsi:type) into bound values. A BODYLESS xml
+      // entry is fine — a GET whose xml RESPONSE needs arrayPaths carries no body.
+      if (typeof req.body !== 'string') {
+        throw new Error(`API Driver: ${label} — encoding: xml requires body: to be a string template (a YAML block scalar holding the raw XML).`);
+      }
+      fetchBody = bindXmlParams(req.body, params);
+      if (!hasHeader(headers, 'content-type')) headers['content-type'] = 'application/xml';
     } else if (body !== undefined) {
       const enc = req.encoding ?? 'json';
       if (enc === 'form') {
@@ -266,9 +449,6 @@ class ApiClient {
       throw new Error(`API Driver: ${label} — a ${req.method.toUpperCase()} request cannot carry a body. Remove body:/files:/bodyFile: from the catalog entry, or change its method to POST/PUT/PATCH.`);
     }
 
-    // Full URL (not a baseURL-relative path) so a base path component like /api/v3 is preserved.
-    const fullUrl = joinApiUrl(base, urlPath);
-
     // @hybrid: `storageState` is the @auth role's saved session (Playwright's `context.storageState()`
     // JSON) — reuse its cookies (scoped to `fullUrl`'s domain/path) so the request shares the
     // browser's authenticated session without a browser/Playwright context.
@@ -292,9 +472,32 @@ class ApiClient {
         ...(fetchBody !== undefined ? { body: fetchBody } : {}),
         signal: controller.signal,
       });
-      const text = await res.text();
+      // Read bytes, not res.text(): the fetch spec hard-decodes text() as UTF-8, so a
+      // Shift_JIS/ISO-8859-1 XML response (common from OTA backends) would mojibake
+      // silently. XML-ish responses decode by Content-Type charset, then the XML
+      // declaration's encoding, then UTF-8; everything else keeps the UTF-8 decode
+      // res.text() always performed.
+      const bytes = Buffer.from(await res.arrayBuffer());
+      const contentType = res.headers.get('content-type') || '';
+      // XML detection: an explicit xml Content-Type (text/xml, application/xml,
+      // application/soap+xml — never text/html), else — only when the CT is absent or
+      // octet-stream — a sniff REQUIRING the `<?xml` declaration. Never sniff on a bare
+      // `<`: the parser does not validate, so an HTML 502 page would come back as a
+      // junk object instead of the raw string an author can at least read.
+      const ctIsXml = /xml/i.test(contentType) && !/html/i.test(contentType);
+      const maySniff = !contentType || /octet-stream/i.test(contentType);
+      // Non-XML branch uses TextDecoder, NOT Buffer.toString: the fetch spec's
+      // "UTF-8 decode" (what res.text() did) STRIPS a leading BOM, and a BOM'd
+      // JSON response must keep parsing as an object exactly as before.
+      const text = ctIsXml || maySniff ? decodeXmlAwareText(bytes, contentType) : new TextDecoder('utf-8').decode(bytes);
+      const isXml = (ctIsXml || (maySniff && /^\uFEFF?\s*<\?xml/.test(text))) && text.length > 0;
       let parsed: any = text;
-      try { parsed = text ? JSON.parse(text) : null; } catch { /* non-JSON → keep text */ }
+      if (isXml) {
+        const xml = parseXmlBody(text, label, req.arrayPaths);
+        parsed = xml !== null ? xml : text; // real parse failure → keep the raw string
+      } else {
+        try { parsed = text ? JSON.parse(text) : null; } catch { /* non-JSON → keep text */ }
+      }
       return { status: res.status, ok: res.ok, body: parsed, headers: Object.fromEntries(res.headers.entries()) };
     } finally {
       clearTimeout(timer);
@@ -310,7 +513,7 @@ class ApiClient {
    */
   async callN(
     label: string,
-    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart'; files?: Record<string, FileSpec | FileSpec[]>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string },
+    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart' | 'xml'; files?: Record<string, FileSpec | FileSpec[]>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string; arrayPaths?: string[] },
     params: Record<string, any> = {},
     n = 1,
     opts: { storageState?: string } = {},