@sun-asterisk/sungen 3.2.29 → 3.2.30

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

@@ -13,7 +13,8 @@ user-invocable: false
 - **Actor**: Always `User`, always active voice.
 - **Value**: `with {{snake_case}}` — never hardcode static data.
 - **State**: `is <keyword>` — never use `{{}}` for states.
-- **Parent scope**: `in [Parent] parentType` — optional, only when page has 2+ similar blocks needing disambiguation.
+- **Parent scope**: `in [Parent] parentType` — optional, only when page has 2+ similar blocks needing disambiguation. Container types: `table` `list` `list-item` `section` `dialog` `modal` `drawer` `overlay` `form` `card` `item` `row` `group` `panel` `region` `container` `tab` `menu`. Anything else is not a container, and the clause is DROPPED with `SG-W028` rather than silently widening the step to the whole page.
+- **Parent scope BY CONTENT** (web only): `… with {{v}} in [Parent] parentType with {{v2}}` — the SECOND `with` picks the one container whose content is `{{v2}}`, for a list of look-alike cards/rows. One `with` after the clause still belongs to the TARGET (`see [first] row in [apply list] table with {{job_name}}`), so the by-content form always carries two. On the mobile adapter it reports `SG-W028` — an Appium parent chain has no content filter.
 
 ## Keyword → Action Rules
 
@@ -45,6 +46,8 @@ User select [T] dropdown with {{v}}
 User click [T] button | tab | column | breadcrumb
 User click [T] row with {{v}}
 User try to click [T] button | link          # DISABLED element only — see rule below (v3.3) [web]
+User click [T] overlay at position "top-left"           # corner preset: top-left | top-right | bottom-left | bottom-right [web]
+User click [T] overlay at offset x=24px, y=10%          # px or % per axis, from the element's top-left [web]
 User double click [T] element
 User hover [T] icon | row                    # no-op on mobile (see Platform Support)
 User drag [T] to [T2]
@@ -57,7 +60,17 @@ User expand | collapse [T] row
 scenario asserts nothing happens (cooldown re-send, submit before the form is valid). `click` waits for
 `enabled` → it can only time out there; `try to click` compiles to `.click({ force: true })`. Always
 pair it with the proof: `Then User see [T] TYPE is disabled` + an assertion that the effect did NOT occur.
-NEVER use it for a click that is supposed to work — it deletes the actionability wait.
+NEVER use it for a click that is supposed to work — it deletes the actionability wait. (`force: true` is
+reachable ONLY through `try to click` — there is no separate `force` keyword.)
+
+**click at position rule** (web only): a plain `click` lands on the element's CENTRE. To click a
+modal backdrop where the dialog is not, or any control whose centre is covered, append
+`at position "<corner>"` (5% in from that corner) or `at offset x=<n>px|%, y=<n>px|%`. The position
+is checked against the element's real box at run time (an offset past it fails naming the size). The
+suffix is refused at compile time (`SG-E026`, the step throws instead of clicking the centre) when it
+is misspelt or unquoted, when a value is negative / above 100% / missing an axis, when anything
+follows it, and when it is combined with `try to click`, a `with {{v}}` text filter, `… and accept [OK]
+alert`, or `double click` — those forms take no position.
 
 ### Alert / Keyboard / Wait / Scroll
 
@@ -68,12 +81,11 @@ User click [OK | Cancel] alert                    # two-step form: must come BEF
 User fill [T] alert with {{v}}                    # no-op on mobile — native prompt fill is app-specific
 User see [message text] alert
 User press Escape key | [Enter] key | Tab key 5 times | Enter on [T] field
-User wait for N seconds | [T] page                # [T] page: web waits for the URL; mobile pauses (settle) — see Platform Support
+User wait for N seconds | [T] page                # [T] page: web waits for the URL, then HOLDS it (see Pattern 8); mobile pauses (settle) — see Platform Support
 User wait for [T] TYPE is visible | hidden | enabled | disabled     # ANY reference (v3.3)
 User wait for [T] TYPE with {{v}}                                    # until it shows the value
 User wait for [T] table to refresh                                   # filter/search/pagination round-trip (v3.3)
 User scroll to [T] section
-User switch to [T] frame | [main] frame           # web: iframe; mobile: hybrid-app WebView context (no-op if the screen has no WebView)
 ```
 
 > **Browser alerts (native `window.confirm/alert/prompt` only):** prefer the compound form —
@@ -86,6 +98,36 @@ User switch to [T] frame | [main] frame           # web: iframe; mobile: hybrid-
 > `wait for N seconds` stays a last resort. `table to refresh` watches the app's loading
 > indicator (`qa/app.yaml` `feedback.loading.indicator`, default `[aria-busy="true"]`).
 
+### Scope control
+
+```
+User is on [T] dialog                             # ENTER dialog scope, rooted at [T]'s selectors.yaml entry
+User use dialog                                   # ENTER dialog scope, unnamed — plain page.getByRole('dialog')
+User close dialog | dismiss dialog | exit dialog  # EXIT dialog scope (three spellings, identical)
+User switch to [T] frame                          # ENTER frame scope — web: iframe; mobile: hybrid-app WebView context
+User switch to [main] frame                       # EXIT frame scope (no-op if the screen has no WebView)
+```
+
+> **Dialog scope is STICKY — it ends only where you end it.** Once a scenario enters dialog scope,
+> EVERY later locator in that scenario is prefixed with the dialog root, **including the steps that
+> run after the dialog has closed**. Nothing implicit drops it: not a click on the dialog's own
+> Close/OK button, and **not** `wait for [T] dialog is hidden` — that step asserts the dialog went
+> away and then keeps resolving the following steps INSIDE it, which can never succeed. Only
+> `close`/`dismiss`/`exit dialog`, or the start of the next scenario, drops the scope. The failure
+> has a recognisable shape: a step after the dialog closed times out reading "element not found"
+> while the element is plainly on screen — you are not missing a selector, you are still scoped
+> inside a dead dialog.
+>
+> ```gherkin
+> Given User is on [Confirm Delete] dialog   # scope enters here — implicitly, but it still needs an EXPLICIT exit
+> When User click [OK] button                # scoped — correct, the button IS in the dialog
+> And User exit dialog                       # ← REQUIRED: the click closed the dialog, the scope did not
+> Then User see [Deleted] toast              # page-rooted again
+> ```
+>
+> Dialog scope is `[web]`-effective only — no Appium template reads `inDialog`, so on mobile the
+> following steps resolve against the whole screen (`SG-W021`). Frame scope works on both.
+
 ### Positional table rows (v3.3) `[web]`
 
 ```
@@ -142,6 +184,20 @@ detail:
   anchor: { type: 'role', value: 'heading', name: 'Item Detail' }   # the rendered-content proof
 ```
 
+**`wait for [T] page` shares that hold, and only that.** Since 3.2.30 the wait compiles to
+`waitForPage(page, {…})` on the same helper: it arrives, settles, holds the URL, and fails naming
+where the user went — so the steps AFTER the wait no longer run against a page mid-redirect, and
+`/vi/search` no longer resolves on `/vi/search-results`. Two differences from the `Then` side:
+
+- **A wait does not constrain the query.** `see [Results] page` with no `with {{v}}` demands a bare
+  URL; `wait for [Results] page` after submitting a search tolerates the `?q=…` it lands on. Prove
+  the query in the `Then` that follows.
+- **A wait is not an oracle.** It never counts toward a scenario's assertions — `ORACLE-URL-ONLY`
+  and the assertionless-test check both ignore it. Always follow it with a real `Then`.
+
+An absolute page `value` (`https://app.example.com/reception/:id`) compiles its host into a
+separate anchored `hostname:` — the same path on another host no longer satisfies the wait.
+
 **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 check — `expectPage(page, {…})`, built on
 `toHaveURL(urlMatches({…}))` and retrying like any other assertion — comparing the **exact** pathname
@@ -211,6 +267,15 @@ User see [Table] table match data:
 
 Row scope: `see [Ref] row in [Table] table with {{v}}` enters scope. Subsequent `see [Col] column with {{v}}` checks cell in that row. Use `table match data:` for multi-row verification.
 
+**[Col] does not have to be the DOM header text.** `see [Col] column in [T] table` looks for a header whose accessible name is the reference, which cannot match a page in another language. Keep the reference readable — it is what the delivered test case shows — and declare the real header on the table entry (or on a `<col>--columnheader` entry's `name:`, which also takes `{{variables}}` for per-locale text):
+```yaml
+article list:
+  type: role
+  value: table
+  columns:
+    category: { index: 2, header: '記事分類' }
+```
+
 **[Ref] of a row step is a display label UNLESS declared in selectors.yaml.** Without an entry the step checks the value exists in ANY row — a name like `[First Contact Row]` does NOT position the row, and an ordering rule would pass even when the row moved (SG-W010 warns on positional-looking undeclared labels). To assert a POSITION, declare the row (a `type: locator` value RELATIVE to the table):
 ```yaml
 first contact row:
@@ -402,7 +467,7 @@ Full syntax → `sungen-mobile-gestures`.
 |---|---|---|
 | `see [T] page` \| `page with {{v}}` | asserts path+query | **silent no-op** — asserts nothing; the scenario passes regardless. Assert a screen-marker element instead |
 | `is on [T] page` \| `open [T] page` (Given/When) | navigates via URL | `is on` = the app-launch anchor, correctly a no-op. `open`/`navigate to` = a no-op that **reports `SG-W026`** — it promises a screen change and performs none; use tap/gesture steps instead |
-| `wait for [T] page` | waits for the URL | fixed `driver.pause(500)` settle — not a real wait condition |
+| `wait for [T] page` | waits for the URL, then settles and HOLDS it (`waitForPage`) | fixed `driver.pause(500)` settle — not a real wait condition |
 | `go back` (OS/hardware back) | **not a web step** — reports `SG-W020`; re-enter with `is on [X] page` or tag `@manual` | Android: `KEYCODE_BACK`, the real hardware key. iOS: WDA **navigation**-back, *not* the user's edge swipe-back (iOS has no hardware back). Distinct from `tap [Back] button`: system back skips the screen's own handler unless the app wires it |
 | `hover [T] icon \| row` | real hover | no-op — hover-revealed content is normally already visible on mobile; use `tap` |
 | `fill [T] alert with {{v}}` | fills native `prompt()` | no-op (comment only) — app-specific, handle manually |
@@ -492,7 +557,17 @@ award:
 | `upload` | — | — | file inputs |
 | `frame` | iframe selector | — | iframes |
 
-Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `columns`
+Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `columns` `checked` `selected`
+
+`checked: { class: <cls> }` or `checked: { attribute: <attr> }` — how a checkbox-like control that is
+NOT a real checkbox (a `<div>` tile with no `role`/`aria-checked`; `.check()` throws "Not a checkbox or
+radio button") shows its state. `selected:` is an ALIAS of the same signal, for a card/tab picker where
+`checked:` reads wrong; declare ONE spelling and ONE of class/attribute. `check`/`uncheck` click only
+when the state differs, then assert it; `is checked` / `is unchecked` / `is selected` (plain or
+`with {{v}}`) assert it. The class is read on the located element OR on a descendant (a checkmark
+`<svg>` that only mounts when on); the attribute is read on the located element itself. Other states on
+the same entry (`is focused`, …) keep their native matchers. The value must be ONE plain class token or
+attribute name — whitespace, a quote or a backslash is refused at compile time, naming the entry.
 
 `scope` (e.g. `scope: dialog`) is `[web]`-effective only — no Appium template reads `inDialog`, so
 on mobile a dialog-scoped ref still resolves against the whole screen (`SG-W021`).
@@ -809,7 +884,32 @@ Only when `@cleanup:*` tags aren't enough — feature-specific logic.
 
 ### Layer 3: `@beforeAll` / `@afterAll` (optional)
 
-For one-time setup/teardown.
+For one-time setup/teardown. A hook scenario takes `@api:` / `@query:` preconditions exactly like an
+ordinary scenario (override args and `@concurrent:N` included) — they run inside the hook and bind
+`{{name}}`:
+
+```gherkin
+@beforeAll @api:login(email={{email}},password={{pw}}) @api:list_items(token={{login.body.token}})
+Scenario: seed the session once before any scenario
+  Then expect {{login.status}} is 200
+  And expect {{list_items.status}} is 200
+
+@afterAll @api:cleanup
+Scenario: drop the seeded data after the last scenario
+  Then expect {{cleanup.status}} is 204
+```
+
+- A variable bound in `@beforeAll` (`{{login.body.token}}`) is readable from EVERY scenario of the
+  feature (it runs before each of them). `@afterEach`/`@afterAll` bindings stay hook-local.
+- A failing hook skips every test in the file, so hook steps are COLLECTED: each `Then` that fails is
+  recorded and the next step still runs; a failing action step (`Given`/`When`) stops the hook there.
+  The hook fails ONCE with the full list (`Hook preconditions not met`), not with the first failure.
+- `@cases` and `@extend` are not supported on a hook — they are ignored with a compile warning.
+- A hook has no `page` fixture on a per-scenario (non-`@serial`) feature — keep its steps to `@api:`/
+  `@query:` preconditions and `expect` assertions there.
 
 **Rendering order in `.spec.ts`:**
-`test.describe` → `test.use(storageState)` → `test.use(autoCleanup)` → `test.beforeAll` → `test.beforeEach` → `test.afterEach` → `test.afterAll` → `test()` blocks
+`test.describe` → `test.use(storageState)` → `test.use(autoCleanup)` → `test.beforeAll` → `test.beforeEach` → `test.afterEach` → `test.afterAll` → `test()` blocks.
+On a `@serial` feature the user `@beforeAll`/`@afterAll` blocks are registered right after the built-in
+`beforeAll` (page creation) and BEFORE the built-in `afterAll` (page close): Playwright runs `afterAll`
+hooks in registration order, so the shared `page` is still open for the user's teardown steps.

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

@@ -96,6 +96,7 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
    - Toast/alert named from content (no aria-label) → `feedback.toast: { role: status, named_by: content }` + `name: null` on the selector entries.
    - Loading indicator for `wait for [T] table to refresh` → `feedback.loading.indicator` (skip if the app sets `aria-busy`).
    - **Every qa/app.yaml edit MUST carry provenance** in `detection:`: who/when (`detected_by`) and the observed evidence per key (`evidence:`). A profile without evidence is a guess a human cannot review.
+7c. **Checkbox-like control that is not a checkbox** (`.check()` failed with `Not a checkbox or radio button`; the snapshot shows a `<div>`/`<button>` tile with no `role="checkbox"` and no `aria-checked`): keep the locator that finds the tile and add the state signal to the SAME entry — `checked: { class: '<class present when on>' }` (a class on that element itself, e.g. `bg-selected`) or `checked: { attribute: '<attr>' }` (a `'true'`/`'false'` attribute such as `data-checked`); on a card/tab picker write `selected:` instead — same signal, different spelling. This is what makes `check`/`uncheck`/`is checked`/`is selected` compile for the tile. ONE plain class token or attribute name only — whitespace or a quoted fragment is refused at compile time, naming the entry. Same shape as `expanded:` for accordions; `checked.class` matches on the located element OR a descendant carrying it (the checkmark icon), while `checked.attribute` is read on the located element itself.
 8. **Merge, don't overwrite**: preserve the page selector and any user-authored entries in `selectors.yaml`. Only add missing keys.
    - **Type-collision check** (see `sungen-selector-keys` § Collision rule): before writing a base key, check whether it already exists with a *different* `type`. If so, give **both** entries a `--type` suffix instead of clobbering or sharing the base key — a base-key entry of the wrong type gets picked up by any step referencing that label. Watch `page` especially: a `[X] page` step reads `value` as a URL, so if `X` already holds a button (`value: 'button'`) the compiler won't use the button's value as a URL, but it can't invent the real one either — it falls back to the feature's own path and warns `SG-W013`, asserting a page that isn't `X`'s. Write `X--page` (URL from the live page / feature `Path:`) alongside `X--button`.
 9. **Show summary + confirm**: list the keys that will be added, ask the user to approve, then write the file.

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

@@ -219,7 +219,7 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 | `[X] button` | `getByRole('button', { name: 'X' })` | Button's accessible name = X |
 | `[X] link` | `getByRole('link', { name: 'X' })` | Link text = X |
 | `[X] heading` / `header` | `getByRole('heading', { name: 'X' })` | Heading text = X |
-| `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` | Checkbox label = X |
+| `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` | Checkbox label = X — a checkbox-LIKE tile with no `role`/`aria-checked` needs an explicit entry plus `checked: { class: <cls> }` or `checked: { attribute: <attr> }` (read on the located element itself; `expanded.class` reads a descendant) |
 | `[X] radio` | `getByRole('radio', { name: 'X' })` | Radio label = X |
 | `[X] field` | `getByPlaceholder('X')` | Placeholder text = X AND field has a placeholder |
 | `[X] text` / `message` / `label` | `getByText('X')` | Visible text = X (partial match) |
@@ -231,7 +231,7 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 | `[X] tab` | `getByRole('tab', { name: 'X' })` | Tab text = X |
 | `[X] table` | `getByRole('table', { name: 'X' })` | Table aria-label = X |
 | `[X] list` | `getByRole('list', { name: 'X' })` | List aria-label = X |
-| `[X] column` | `getByRole('columnheader', { name: 'X' })` | Column header text = X |
+| `[X] column` | `getByRole('columnheader', { name: 'X' })` | Column header text = X — **overridable**, see the column-header note below |
 | `[X] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'X' })` | Dialog aria-label/heading = X |
 | `[X] dropdown` / `select` | `getByRole('combobox', { name: 'X' })` | Combobox label = X |
 | `[X] menuitem` | `getByRole('menuitem', { name: 'X' })` | Menu item text = X |
@@ -244,6 +244,8 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 | `[X] breadcrumb` | `getByRole('navigation', { name: 'X' })` | Navigation aria-label = X |
 | `[X] badge` / `tooltip` / `tag` | `getByText('X')` | Visible text = X |
 
+**Column headers: the `[Reference]` is not required to be the DOM text.** `[X] column` defaults its accessible name to the reference, which is unmatchable when the page is not in the reference's language (a `[Category]` column whose header reads 記事分類). Declare the real header instead of renaming the reference — the reference is what ships in the delivered test case. Most specific first: the table entry's `columns.<col>.header`, then a `<col>--columnheader` entry's `name:`, then the reference text. A `header` may hold `{{variables}}` for per-locale text, like any `name:`. A same-named entry that is NOT a column header is ignored and cannot hijack the lookup.
+
 **Special note on the list members `[X] item` / `[X] option` / `[X] cell`** — the only rows above that behave differently per platform:
 
 - **Web**: they infer the role with **no `name`**, on purpose. A list member takes its accessible name from its own CONTENT, so a name defaulted from the `[Reference]` text matches zero elements — and `toBeHidden()` PASSES on an empty locator, so the scenario would go green having proved nothing. The role alone is the whole locator; `nth` or a count assertion narrows it. An explicit `name:` you write yourself is always honoured.
@@ -255,6 +257,11 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 
 **Only add a YAML entry when** auto-infer cannot work: DOM name differs from Gherkin label, need `testid`, need `nth`, need `exact: true`, need `name: null`, or the field type requires explicit config.
 
+**`nth:` takes an integer `>= -1`** — `0`, `1`, `2`… are zero-based indexes and `-1` is the LAST
+match (`.last()` on web, `.at(-1)` on mobile). Nothing else is an index: `nth: -2`, `nth: 'last'`
+and `nth: 1.5` are ignored, the selector stops filtering by position, and the compiler reports
+`SG-W018`. Reach for `nth` only when `exact: true` or `scope` cannot disambiguate.
+
 ### `name: null` — name-from-content roles (toast, alert, spinner)
 
 For a `type: role` entry **without** `name:`, the compiler defaults the accessible-name filter to the Gherkin `[Reference]` text. That is right for buttons/links — and **always wrong** for roles whose accessible name derives from their CONTENT (`status`, `alert`, `log`, `marquee`, `timer`): a toast's name is its message text, never the string "Success Toast". The compiler warns (`SG-W003`). Opt out explicitly:

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

@@ -97,7 +97,7 @@ Hard-fail gate. Any ✗ is a syntax error — must be fixed; do not score furthe
 
 - [ ] Selector keys: lowercase, keep Unicode, use **spaces** (no underscores/dots); same label → `--type`/`--N` suffix; names >30 chars → shorten to 1–3 words
 - [ ] Types requiring explicit YAML: `date-picker`, `uploader`, `overlay`, `frame`, `step`
-- [ ] Every `{{var}}` in `.feature` exists in `test-data.yaml`; NO orphan keys
+- [ ] Every `{{var}}` in `.feature` exists in `test-data.yaml`, and every test-data key is bound by some scenario. Both directions are checked by the advisory **data-driven lint** printed at the end of `sungen generate` (warn, never blocking; it is NOT an `audit` finding): **forward** — `{{x}} is not a test-data key and nothing binds it at run time` (the compiler does not fail; the step compiles to the literal text `'${x}'` and runs green having tested nothing, so treat this warning as a defect); **reverse** — `test-data key "x" is defined but never referenced` (dead data). Not counted as unbound/orphan: `{{$…}}` dynamic vars, runtime-bound vars (`remember … as {{v}}`, the scenario's own `@api:`/`@query:` names, a `@beforeAll` hook's `@api:`/`@query:` bindings, a `@steps:` base's captures for its `@extend`ers, and a `@query`/`@api` param bound by name with no override), `@cases` dataset columns, `_*` factory metadata keys, `{{var}}` used in `selectors.yaml` (i18n names) or `mock/mocks.yaml` (mock bodies), and `{{var}}` inside a `@manual` scenario's `# Tester verifies:` comments
 - [ ] Dynamic vars (`{{$timestamp}}`/`{{$uuid}}`/`{{$random:a:b}}`) used correctly for run-unique data (CRUD)
 - [ ] `locator` (CSS) only as a last resort
 
@@ -291,7 +291,7 @@ Do NOT deduct points when a `.feature` lacks the following viewpoints (Playwrigh
 1. ID unique + correct format `VP-<CAT>-<NNN>`?
 2. Title understandable immediately, no context needed?
 3. Every step uses the right keyword (`Given`=is on / `When`=action / `Then`=see)?
-4. Every `{{var}}` exists in `test-data.yaml`?
+4. Every `{{var}}` exists in `test-data.yaml`, and every test-data key is bound by some scenario? (`sungen generate` ends with a data-driven lint warning for either direction — an unbound `{{x}}` compiles to the literal placeholder, it does not fail)
 5. At least one happy path?
 6. Negative cases for invalid classes (EP)?
 7. Boundary covers the 4 points (`min-1/min/max/max+1`)?
@@ -318,7 +318,7 @@ Do NOT deduct points when a `.feature` lacks the following viewpoints (Playwrigh
 9. **Missing negative path** → map invalid classes, add scenarios.
 10. **All `@high`** → reset by user impact per the `sungen-gherkin-syntax` priority table (auth/CRUD/security/required → `@high`; format/standard-range boundary/search → `@normal`; cosmetic → `@low`).
 11. **`@manual` without reason** → add a technical reason comment explaining why automation is not possible.
-12. **Orphan var in test-data** → delete or reconnect.
+12. **Orphan key in test-data** (the advisory lint after `sungen generate` says `defined but never referenced`; a `@query`/`@api` param bound by name, a `@manual` comment ref or a `_*` metadata key is not one) → delete it or bind it into a scenario. **Unbound `{{x}}` in a step** (the same lint says `is not a test-data key and nothing binds it`) → add the key or fix the ref — left alone it runs as the literal text `${x}`.
 13. **Unnecessary CSS/locator selector** → switch to role+name/label/text; keys use spaces.
 14. **Scope crammed into `Background`** → split into `@steps`/`@extend`.
 15. **Mixed auth groups missing `@parallel`** → add `@parallel`.
@@ -361,7 +361,7 @@ If `selectors/<name>.yaml` exists, count lines matching `@needs-live-verify` (pr
 - [ ] Keyword→Action correct
 - [ ] Action→Type correct; click-rule correct
 - [ ] Assertions follow the 8 patterns, no redundant `is visible`
-- [ ] Every {{var}} exists in test-data.yaml; no orphan keys
+- [ ] Every {{var}} exists in test-data.yaml and no orphan keys — both reported by the advisory data-driven lint at `sungen generate` (not `audit`); an unbound {{var}} compiles to a literal placeholder, never a compile error
 - [ ] Selector keys follow sungen-selector-keys; locator only as last resort
 - [ ] Tags valid; @parallel when mixing auth groups
 - Syntax errors found: <n>

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

@@ -84,9 +84,16 @@ export default defineConfig({
   /* Output file path is controlled by PLAYWRIGHT_JSON_OUTPUT_NAME env var for per-screen isolation. */
   /* When SUNGEN_ENV is set, the env name is inserted before `.json` so locale */
   /* runs don't overwrite each other (e.g. `<name>-test-result.vi.json`). */
+  /* The sanitize reporter rewrites the JSON report's absolute machine paths to project-relative ones on
+     exit — the file is committed next to the spec, so a username or machine layout must not ship in it.
+     Registered only while its file exists (`sungen init`/`generate`/`update` write it): a cleaned
+     specs/generated must not stop Playwright from loading this config. */
   reporter: [
     ['html'],
     ['json', { outputFile: resolveJsonOutputFile() }],
+    ...(fs.existsSync(path.join(__dirname, 'specs', 'generated', 'report-path-sanitize-reporter.ts'))
+      ? [['./specs/generated/report-path-sanitize-reporter.ts'] as [string]]
+      : []),
   ],
   /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
   use: {

package/dist/orchestrator/templates/specs-checked-state.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Sungen checked-state helper — auto-generated into specs/checked-state.ts. DO NOT EDIT.
+ *
+ * Playwright's `.check()` / `.uncheck()` accept ONLY native checkbox/radio inputs and
+ * `role=checkbox|radio|switch`. Anything else throws "Not a checkbox or radio button" (#675).
+ * A toggle BUTTON — `<button aria-pressed>`, the correct ARIA pattern for a pressed/unpressed
+ * control — is none of those, so a bare `.check()` could never drive one.
+ *
+ * Rewriting the Gherkin to `click` is NOT an equivalent workaround, and that is the whole reason
+ * this helper exists: `click` flips UNCONDITIONALLY, so a scenario that re-runs, or starts from an
+ * unknown state, drives the toggle the WRONG way. Idempotence — end up in the requested state
+ * regardless of where you started — is the entire meaning of `check` / `uncheck`.
+ *
+ * The mechanism is chosen from the ELEMENT at run time, not from the selector's declared role,
+ * because the resolved selector is very often a testid/CSS locator carrying no role at all — so
+ * codegen cannot know what it will hit.
+ *
+ * Deliberately depends on NOTHING but the `Locator` TYPE: no `expect`, no test-runner context. That
+ * keeps the branching testable against a fake locator without a browser (tests/runtime/
+ * checked-state.run.ts) — this file runs inside every user's suite, so its logic is worth pinning.
+ */
+import type { Locator } from '@playwright/test';
+/** A signal DECLARED in selectors.yaml: the class token, or the boolean attribute, marking ON. */
+export interface DeclaredSignal {
+    class?: string;
+    attribute?: string;
+}
+/** Where the control publishes its on/off state — decided in the page, from the real element. */
+export type StateSource = 'native' | 'aria-pressed' | 'aria-checked' | 'class' | 'attribute' | 'none';
+export interface ControlProbe {
+    source: StateSource;
+    /** Current state, already normalised. Meaningless when `source` is 'native' (Playwright reads it). */
+    on: boolean;
+    /** Button-like: a control a human would press. Decides how a MISSING state is read — see below. */
+    buttonLike: boolean;
+}
+/**
+ * Runs IN THE PAGE, so it must stay self-contained: Playwright serialises it and the browser has
+ * none of this module's scope.
+ *
+ * It also must contain NO inner function of its own — not even an arrow helper. A bundler with
+ * keepNames (esbuild, which is what Playwright itself transpiles specs with) rewrites every named
+ * inner function to `__name(fn, "…")`, that wrapper travels inside the serialised source, and the
+ * page throws `ReferenceError: __name is not defined` on EVERY check step. Straight-line code with
+ * the normalise repeated inline is the price of being serialisable; `tests/runtime/
+ * checked-state.run.ts` pins it so the next edit cannot quietly reintroduce a helper.
+ *
+ * Structurally typed rather than via the DOM lib names because this file is also typechecked
+ * inside the compiler build, whose tsconfig carries no DOM lib.
+ */
+export declare function probeControl(node: unknown, declared?: DeclaredSignal): ControlProbe;
+/**
+ * Drive `target` to the requested on/off state, idempotently.
+ *
+ * @param target the control
+ * @param want   `true` = checked/pressed, `false` = unchecked/unpressed
+ * @param label  the `[Selector Ref]` from the feature file, used only in error messages
+ * @param options.checkedClass `checked:`/`selected:` from selectors.yaml — the class marking ON,
+ *        for a control that publishes no ARIA at all (issue #730). Overrides every ARIA reading.
+ * @param options.checkedAttribute the same declaration published as a boolean attribute
+ *        ('true'/'false') instead of a class. A selector declares one or the other, never both.
+ */
+export declare function setCheckedState(target: Locator, want: boolean, label: string, options?: {
+    timeout?: number;
+    checkedClass?: string;
+    checkedAttribute?: string;
+}): Promise<void>;
+/**
+ * Assert the on/off state of the same control family — the read side of #675.
+ *
+ * `expect(locator).toBeChecked()` throws the identical "Not a checkbox or radio button" on a
+ * `<button aria-pressed>`, so driving a toggle worked while asserting it did not. Polls like
+ * Playwright's own web-first assertions rather than sampling once, and reads state exactly the way
+ * setCheckedState does, so an action and the assertion after it can never disagree about what the
+ * control says. Uses `locator.isChecked()` (not `expect`) for the native family, which keeps this
+ * file free of any test-runner dependency.
+ */
+export declare function expectCheckedState(target: Locator, expected: boolean, label: string, options?: {
+    timeout?: number;
+    checkedClass?: string;
+    checkedAttribute?: string;
+}): Promise<void>;
+//# sourceMappingURL=specs-checked-state.d.ts.map

package/dist/orchestrator/templates/specs-checked-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specs-checked-state.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-checked-state.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAchD,kGAAkG;AAClG,MAAM,WAAW,cAAc;IAAG,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE;AAEtE,iGAAiG;AACjG,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,cAAc,GAAG,cAAc,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,CAAC;AACtG,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,sGAAsG;IACtG,EAAE,EAAE,OAAO,CAAC;IACZ,mGAAmG;IACnG,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,YAAY,CAkDnF;AA4BD;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAC7C,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/E,OAAO,CAAC,IAAI,CAAC,CA6Gf;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EACjD,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/E,OAAO,CAAC,IAAI,CAAC,CA4Cf"}