@sun-asterisk/sungen 3.2.33 → 3.2.34

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -224,7 +224,7 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 
    **Auto-detect visual source** — do NOT ask the user to pick a source. Instead, check what already exists and use it:
    1. If `spec_figma.md` exists → read it as Figma supplement (PAT flow already completed during `add-screen`). Do NOT call any `mcp__figma__*` tool.
-   2. If `ui/` has images (`.png`, `.jpg`, etc.) → read them for visual context (layout, element positions, states).
+   2. If `ui/` has images (`.png`, `.jpg`, etc.) or `ui/figma-meta.md` → read **all** of them; they feed the Design Inventory (below), not just visual context.
 {{#cap parallel-subagents}}
    3. If neither exists → use `AskUserQuestion` to ask: *"No visual source found. Pick one:"* — then invoke the **`sungen-capture`** skill with the matching **mode** (read only that mode's file):
       - **Figma PAT** — ask for URL, run `sungen add --screen <screen> --figma '<url>'` via Bash, then `sungen-capture` **mode figma-pat**
@@ -242,7 +242,7 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 
    (When `spec_figma.md` exists, that is also `sungen-capture` **mode figma-pat**; when `ui/` images exist, that is **mode local**.)
 
-   **Cross-check**: if both `spec.md` and visual sources exist, flag any discrepancies (missing fields, different labels) before moving on. When `spec_figma.md` is present, follow the Figma supplement rules in `sungen-tc-generation` skill (reading order, Text Inventory, conflict handling).
+   **Cross-check + Design Inventory**: when the unit holds any design source (`ui/` images, `ui/figma-meta.md`, `spec_figma.md`), follow `sungen-tc-generation` § **Design Inventory** (reading order, one `UI-NNN` row per item, `spec+design` / `design-only` / `conflict`) and **write `requirements/ui-inventory.md`** before generating — from the discovery report's UI INVENTORY block when a sub-agent read the sources. Every `design-only` / `conflict` item must then be covered (`@ui:UI-NNN`) or deferred with a reason (`# UI-DEFERRED: UI-NNN — <reason>`) in the `.feature`; `sungen audit` reports `UI-ITEM-UNCOVERED` otherwise. Show the user the conflicts and design-only items — they are decisions, not details.
 
    Summarize what you found in requirements and present to the user.
 

package/src/orchestrator/templates/ai-src/commands/review.md

@@ -51,7 +51,7 @@ You are an **independent QA Reviewer** — you did not author these tests. You d
 1. **Enumerate feature files** — glob `<base>/<name>/features/*.feature` (main + any sub-features). If none → `/sungen:create-test` first.
 2. **Run the harness (source of truth) — do NOT re-score with a separate rubric:**
    - `sungen audit --screen <name>` (Bash) → gate status, business-weighted score, findings, gaps (coverage / assertion-depth / balance / duplicate / traceability).
-   - **`sungen-reviewer`** sub-agent (Task tool, `subagent_type: sungen-reviewer`) → semantic verdict the gate can't see (do steps prove the title, observable Then, @manual justified). Copilot/no-sub-agents: apply the `sungen-reviewer` criteria inline.
+   - **`sungen-reviewer`** sub-agent (Task tool, `subagent_type: sungen-reviewer`) → semantic verdict the gate can't see (do steps prove the title, observable Then, @manual justified) and, when the unit holds design sources (`requirements/ui/*`, `ui/figma-meta.md`, `spec_figma.md`), the **Design ↔ Feature diff** against `ui-inventory.md`. Copilot/no-sub-agents: apply the `sungen-reviewer` criteria inline.
    - `sungen script-check --screen <name>` (Bash) → is the generated spec a 1:1 of the Gherkin (only if a spec exists; flags hand-edit / stale drift).
 3. **Unified scorecard** — present ONE report per feature, anchored on the harness signals (the `sungen-tc-review` 7 dimensions are a *presentation layer* over these, not a competing score):
 {{/cap}}
@@ -63,7 +63,7 @@ You are an **independent QA Reviewer** — you did not author these tests. You d
 1. **Enumerate** `<base>/${input:name}/features/*.feature`. If none → `/sungen-create-test` first.
 2. **Run the harness (source of truth) — no separate rubric:**
    - `sungen audit --screen ${input:name}` → gate, business-weighted score, findings, gaps.
-   - Apply the **`sungen-reviewer` criteria inline** → semantic verdict (do steps prove the title? observable Then? business-critical depth? @manual justified?).
+   - Apply the **`sungen-reviewer` criteria inline** → semantic verdict (do steps prove the title? observable Then? business-critical depth? @manual justified?) and, when `requirements/ui/*` / `ui/figma-meta.md` / `spec_figma.md` exist, read them and diff the design against `ui-inventory.md` and the `.feature` (criterion 7).
    - `sungen script-check --screen ${input:name}` → spec is 1:1 with the Gherkin (flags hand-edit / stale drift; only if a spec exists).
 3. **Unified scorecard** per feature, anchored on harness signals (the `sungen-tc-review` 7 dimensions are a presentation layer, not a competing score):
 {{/cap}}

package/src/orchestrator/templates/ai-src/commands/run-test.md

@@ -1,7 +1,7 @@
 ---
 name: run-test
 description: "Generate selectors + auth state (Playwright MCP for web / Appium MCP for mobile), compile, and run tests — auto-fixes selectors on failure"
-argument-hint: "[screen-name] [--env <locale>] [--ios|--android|--both]"
+argument-hint: "[screen-name] [--ids <ID,…>] [--env <locale>] [--ios|--android|--both]"
 order: 40
 claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_wait_for, mcp__playwright__browser_evaluate, mcp__playwright__browser_run_code, mcp__playwright__browser_storage_state, mcp__playwright__browser_set_storage_state, mcp__appium-mcp__select_device, mcp__appium-mcp__appium_session_management, mcp__appium-mcp__generate_locators, mcp__appium-mcp__appium_get_page_source, mcp__appium-mcp__appium_find_element, mcp__appium-mcp__appium_gesture, mcp__appium-mcp__appium_screenshot, mcp__appium-mcp__appium_set_value"
 copilot-tools: "[read, execute, edit, vscode/askQuestions, playwright/*, appium/*]"
@@ -85,6 +85,13 @@ Stop here for mobile — do not continue to the web path.
 > QA finding → report it, let it FAIL** (it may be a real bug). The live page is NOT the oracle;
 > never hand-edit the generated `.spec.ts` either. See `sungen-error-mapping` § "HARD RULE".
 > (A `password > 8` test that fails on 6 chars is a bug to report, not a `>= 6` edit.)
+>
+> **Blocked by missing seed data / capability** (the run cannot create the state the scenario
+> needs)? Keep every Given/When/Then; add only a tag — `@requires:<cap>` when a driver exists,
+> else `@manual:M1` with a `# MANUAL (<date>, run-test): <reason>` comment inside the scenario —
+> and list each downgrade in the run summary for QA. Never replace the assertion with a presence
+> placeholder and park the oracle in a comment (`SG-W008`). See `sungen-error-mapping` § "Fails
+> because the environment lacks the DATA or CAPABILITY".
 
 ## Parameters
 
@@ -95,7 +102,9 @@ Parse from `$ARGUMENTS`:
   the result over the previous run's file instead of replacing it. Passing it also **skips the scope gate**:
   the flag IS the answer, so asking again would be noise. Without the flag the gate asks — but only when the
   selection is narrower than the whole unit (see the table). Either way a subset run must follow the merge
-  order below; the backup has to exist BEFORE the run, because the report filename is fixed.
+  flow below — web writes the subset to a temp report, mobile backs the fixed-name file up BEFORE the run.
+- **`--ids <ID,…>`** — run exactly these test-case IDs (`VP-UI-001,VP-UI-002`) and merge the result
+  over the previous run's file — see the `--ids` section below. Skips the scope gate, like `--change-only`.
 - **`--ios`**, **`--android`**, **`--both`** (mobile only) — optional. Sets `MOBILE_PLATFORM` for the test run. Default: `android` if not specified. Parsed into `MOBILE_PLATFORM=<value>` and used in WebdriverIO test runs.
 
 If `--env` is passed but no value follows, ask the user which locale to use.
@@ -172,6 +181,7 @@ Read `summary.selected`, `summary.total`, `all`, and `reasons`, then follow this
 | Situation | What to do |
 |---|---|
 | `--change-only` was passed | **Do NOT ask.** Run the changed set, print the list + reasons for the record, follow the merge flow below. |
+| `--ids` was passed | **Do NOT ask, and do not run `sungen changed` at all.** The user named the cases — follow the `--ids` section below. |
 | `all: true` | **Do NOT ask** — there is nothing to choose. Print the reason (`no previous run recorded`, `the Background changed`, `project config changed`, `git reports …`) and run the FULL suite. |
 | `selected == 0` | **Do NOT ask.** Say plainly that nothing changed since the last recorded run, and use `AskUserQuestion` to offer: re-run the full suite anyway / stop here. |
 | `0 < selected < total` | **ASK** — this is the only case with two honest answers. |
@@ -187,6 +197,10 @@ recorded` and runs everything again — the narrowing never starts. Record it af
 results you accept (a full run, or a subset once merged), and NOT after a run you are about to
 redo: leaving the baseline where it is keeps the same scenarios selected on the next attempt.
 
+**Never record after an `--ids` run.** The user's IDs need not cover what an edit changed;
+recording would mark every changed scenario as re-run, and the next `--change-only` would skip the
+ones this run never touched.
+
 When you ask, first PRINT the selection so the choice is informed — one line per scenario with its
 reason, exactly as `sungen changed` renders it — then `AskUserQuestion` with two options:
 
@@ -257,7 +271,7 @@ question already.
 6. **Phase 2 — Priority Wave**: Run all `@high` scenarios. Fix only failures from this wave. Max 2 attempts. Shared selectors fixed here cascade to later phases.
 7. **Phase 3 — Full Run**: Run all tests. Fix only **new** failures (elements unique to `@normal`/`@low`). Max 1 attempt. Don't loop on low-priority failures.
 8. **Phase 4 — Regression**: One final full run. Report results. No more fix loops.
-9. **Phase 8 — Serial-cascade risk check** (#414): If any scenario has many steps, a skipped test may cause downstream steps to be incorrectly skipped due to the serial-cascade sensor detecting false "not reached" conditions. When you see "test skipped" messages during Phase 3–4 runs, check if the skipped scenario is a **blockers-exist** dependency in the test ledger (`sungen ledger query --screen <name>`). If the scenario had high step count and cascade fired, offer: *"Scenarios with deep steps can trigger serial-cascade skipping. Consider parallelizing this spec with `@concurrent` tags or breaking into smaller scenarios. See `sungen-selector-fix` § Phase 8."* Let the user decide whether to refactor (do not auto-apply parallelization).
+9. **Phase 8 — Serial-cascade risk check** (#414): If any scenario has many steps, a skipped test may cause downstream steps to be incorrectly skipped due to the serial-cascade sensor detecting false "not reached" conditions. When you see "test skipped" messages during Phase 3–4 runs, check if the skipped scenario is a **blockers-exist** dependency in the test ledger (`sungen ledger query --screen <name>`). If the scenario had high step count and cascade fired, offer: *"Scenarios with deep steps can trigger serial-cascade skipping. Consider parallelizing this spec with `@concurrent` tags or breaking into smaller scenarios."* Let the user decide whether to refactor (do not auto-apply parallelization).
 {{#cap parallel-subagents}}
 9. **Integrity check & trace (always run after the final run).**
    - `sungen script-check --screen <name>` — verify the generated spec is a **1:1** of the Gherkin (every non-@manual scenario ↔ one `test()`, no drift). If it reports **DRIFT** (spec hand-edited or stale), re-run `sungen generate --screen <name>` so the spec matches the feature, then re-run — **never hand-edit the generated spec** (auto-fix must edit `selectors.yaml`, not the `.spec.ts`).
@@ -325,7 +339,7 @@ sungen results merge --screen <name> specs/generated/<name>/subset-tmp.json
 rm specs/generated/<name>/subset-tmp.json
 ```
 
-`--screen` takes the FEATURE basename — for a multi-feature screen (`home.spec.ts` + `home-modal.spec.ts`), each feature has its own result file: merge `home-modal`'s subset with `--screen home-modal`. If the previous run had zero failures, `--last-failed` runs nothing and writes no JSON — use `-g "<scenario title>"` to pick the cases instead.
+`--screen` takes the FEATURE basename — for a multi-feature screen (`home.spec.ts` + `home-modal.spec.ts`), each feature has its own result file: merge `home-modal`'s subset with `--screen home-modal`. If the previous run had zero failures, `--last-failed` finds no tests: Playwright prints "No tests found", exits 1, and still writes a zero-test report — don't merge it; use `-g "<scenario title>"` to pick the cases instead. `--last-failed` reads the failures of the *previous run only*, so any run in between replaces the list.
 
 For a locale run (`SUNGEN_ENV=vi`), the config appends `.vi` before `.json` to WHATEVER `PLAYWRIGHT_JSON_OUTPUT_NAME` says — the temp report lands at `subset-tmp.vi.json`; merge that file into the matching `<name>-test-result.vi.json` explicitly: `sungen results merge specs/generated/<name>/<name>-test-result.vi.json specs/generated/<name>/subset-tmp.vi.json`. A scenario RENAMED by a spec edit leaves its old-title result in the file — the merge warns and keeps it (delivery builds rows from the feature, so it never renders).
 
@@ -360,29 +374,33 @@ If you want to filter scenarios, use `-g "<pattern>"` instead of a reporter over
 
 ## `--change-only` — re-run just what an edit obliges, without losing the rest
 
-The JSON reporter names its file for the unit + platform + env ONLY, so **any** subset run
-overwrites the full run's results. Re-running 3 cases of a 100-case screen used to throw away the
-97 that still passed, which is why a partial run had to be followed by a full one.
-
-Two commands close that, and the order matters — the backup must exist BEFORE the run, because by
-the time the run finishes the old file is already gone:
+A per-target result file holds the whole unit, so a subset run must never replace it: re-running 3
+cases of a 100-case screen used to throw away the 97 that still passed. The subset is MERGED in
+instead — on web via a temp report, on mobile via a backup taken BEFORE the run (the WDIO reporter
+always writes the fixed-name file, so by the time the run finishes the old one is gone):
 
 ```bash
 # 1. what does the edit oblige?  (empty output = nothing to run, do NOT fall through to a full run)
 npx sungen changed --screen <name>            # human-readable, with the reason per scenario
 GREP=$(npx sungen changed --screen <name> --grep)
 
+# MOBILE — the WDIO reporter always writes the canonical per-OS file, so back it up first:
 # 2. keep the previous results BEFORE the runner overwrites them
 cp specs/generated/<name>/<name>-test-result.<os>.json /tmp/<name>.prev.json
-
 # 3. run only the selected scenarios
 SUNGEN_SPECS='./specs/generated/<name>/<name>.spec.ts' npm run test:mobile -- --mochaOpts.grep "$GREP"
-#   web:  npx playwright test specs/generated/<name>/<name>.spec.ts -g "$GREP"
-
 # 4. merge the subset back over the kept results (same title → new wins, others kept)
 npx sungen results merge /tmp/<name>.prev.json specs/generated/<name>/<name>-test-result.<os>.json \
   -o specs/generated/<name>/<name>-test-result.<os>.json
 
+# WEB — Playwright writes its report to PLAYWRIGHT_JSON_OUTPUT_NAME (else test-results/results.json),
+# never to the per-target file by itself: write the subset to a temp report and merge THAT in (#837).
+# With --env <x>: prefix BOTH commands with SUNGEN_ENV=<x>; the config then writes subset-tmp.<x>.json.
+PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/<name>/subset-tmp.json \
+  npx playwright test specs/generated/<name>/<name>.spec.ts -g "$GREP"
+npx sungen results merge --screen <name> specs/generated/<name>/subset-tmp.json   # --env x → subset-tmp.x.json
+rm specs/generated/<name>/subset-tmp*.json
+
 # 5. record the new baseline — ONLY after a run you accept
 npx sungen changed --screen <name> --record
 ```
@@ -398,6 +416,45 @@ change that broke it.
 **Without `--change-only`** the full run still writes the file wholesale, which is correct — a full
 run IS the complete picture. Merging only matters for subsets.
 
+## `--ids` — run a chosen list of test-case IDs
+
+The user names the cases (`--ids VP-UI-001,VP-UI-002`). `sungen select` resolves them —
+deterministic, exact ID match, grouped per feature — and refuses anything it cannot run:
+
+```bash
+npx sungen select --screen <name> --ids <ID,…>          # human-readable
+npx sungen select --screen <name> --ids <ID,…> --json   # what you act on
+```
+
+**Exit 1 = do not run.** Report every entry of `unknown` (with its `didYouMean`), `notRunnable`
+(manual / owned by a flow — with the reason) and `notCompiled` (→ `sungen generate` first), then
+use `AskUserQuestion` to offer: run the valid IDs only / correct the list. Never fall back to a
+full run, and never run with an empty grep.
+
+Then, **for each entry of `features`** (a multi-feature screen has one spec and one result file per
+feature), with `<spec>` = its `spec`, `<f>` = its `feature`, `<dir>` = the spec's directory and
+`GREP` = its `grep`:
+
+```bash
+# WEB — write the subset to a temp report, then merge it into <f>'s per-target file.
+# With --env <x>: prefix BOTH commands with SUNGEN_ENV=<x>; the config then writes subset-tmp.<x>.json.
+PLAYWRIGHT_JSON_OUTPUT_NAME=<dir>/subset-tmp.json npx playwright test <spec> -g "$GREP"
+npx sungen results merge --screen <f> <dir>/subset-tmp.json      # --env x → <dir>/subset-tmp.x.json
+rm <dir>/subset-tmp*.json
+
+# MOBILE — the reporter always writes <dir>/<f>-test-result.<android|ios>[.<env>].json: back it up first
+# (with --env <x> every <f>-test-result.<os>.json below is <f>-test-result.<os>.<x>.json)
+cp <dir>/<f>-test-result.<os>.json /tmp/<f>.prev.json
+SUNGEN_SPECS='./<spec>' npm run test:mobile -- --mochaOpts.grep "$GREP"
+npx sungen results merge /tmp/<f>.prev.json <dir>/<f>-test-result.<os>.json -o <dir>/<f>-test-result.<os>.json
+```
+
+With no previous result file (first run of the unit, or of this `--env`) there is nothing to merge
+into — `results merge --screen` says so and exits 1: on web run with
+`PLAYWRIGHT_JSON_OUTPUT_NAME=<dir>/<f>-test-result.json`, on mobile skip the backup and the merge.
+With `--both`, back up and merge each OS's file. **Do NOT run `sungen changed --record`** (see the
+scope gate). Report the per-ID outcome, plus the IDs that were refused.
+
 ## Next steps
 
 After showing results, use `AskUserQuestion` to offer next steps:

package/src/orchestrator/templates/ai-src/skills/sungen-capture/mode-local.md

@@ -6,7 +6,7 @@ Use **pre-existing images** in `requirements/ui/` as visual context. No network,
 
 ### 1. List available images
 
-Glob `requirements/ui/*.{png,jpg,jpeg,webp,gif}` and report count + filenames. Filter out metadata files (e.g. `figma-meta.md` written by mode figma-mcp) — those are read by `tc-generation` separately, not treated as images here.
+Glob `requirements/ui/*.{png,jpg,jpeg,webp,gif}` and report count + filenames. Filter out metadata files (e.g. `figma-meta.md` written by mode figma-mcp) — those are read by `tc-generation` (§ Design Inventory) separately, not treated as images here.
 
 ### 2. Handle empty folder
 
@@ -21,7 +21,7 @@ If no images found:
 
 ### 3. Read images for context
 
-Use the `Read` tool on each image — Claude Code reads PNG/JPG/WebP directly as visual context. For large sets (>10 images), ask which are primary and which are states/variants to avoid loading too much at once.
+Use the `Read` tool on **each** image — Claude Code reads PNG/JPG/WebP directly. For large sets (>10 images), ask which are primary and which are states/variants so they can be grouped — but still read them all: every image feeds the Design Inventory (`sungen-tc-generation` § Design Inventory), and the inventory records `images read: N/N`.
 
 ### 4. Summarize
 

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

@@ -39,6 +39,26 @@ weakening assertions, "fixing" an unknown step pattern, adding table-scope steps
 needs any of these, it is a **finding for QA** — surface it in the run summary and let the test
 **FAIL**. A failing test may be a **real bug**; do not edit the QA-approved Gherkin to make it pass.
 
+### Fails because the environment lacks the DATA or CAPABILITY (not the app, not the locator)
+
+Sometimes the scenario is right and the app may be right, but the run cannot set up the state —
+the dev seed has no tie-break pair, no locked account, no second tenant. That is **neither** a
+selector fix **nor** a reason to rewrite. The only allowed `.feature` edit is a **tag** (plus a
+reason comment); the Given/When/Then stay **exactly** as QA approved them:
+
+1. The capability exists as a driver (`db`, `api`, data-factory) → tag `@requires:<cap>` (e.g.
+   `@requires:db`) — it compiles to a skip stub (`AUTOMATION-READY-PENDING`) and runs, unchanged,
+   once `sungen capability add <cap>` is done.
+2. Otherwise → tag `@manual:M1` and put the reason as a comment **inside** the scenario (below the
+   `Scenario:` line — a comment above the tags is attached to the previous scenario):
+   `# MANUAL (<date>, run-test): no seeded pair with equal plan + distinct last-updated`.
+3. **Never** swap the real assertion (`table match data:`, `with {{v}}`, `count is …`) for a
+   presence placeholder (`see [X] table`) and move the oracle into a `# Tester verifies:` comment —
+   that hybrid exports an Expected cell that says nothing about what is checked, and `sungen
+   generate` flags it `SG-W008`.
+4. List **every** downgrade of the run (scenario, tag added, reason) in the run summary so QA
+   reviews it — a downgrade is a coverage decision, not an auto-fix.
+
 ## ⛔ Source of truth — classify EVERY failure before you "fix" it
 
 `.feature` + `test-data.yaml` + `spec.md` are the **oracle**. The **live page is NOT** — it may be the thing that's broken. A failing test is not automatically a test to "make pass". Classify first:

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

@@ -629,6 +629,7 @@ on mobile a dialog-scoped ref still resolves against the whole screen (`SG-W021`
 | Tag | Effect |
 |---|---|
 | `@spec:<id>` | **Traceability**: this scenario proves requirement `<id>` from `requirements/spec.md` (`@spec:FR-003`). Repeatable — a scenario may prove several. Read by `sungen audit` (requirement coverage) and by delivery (the Coverage sheet's requirement table). Without it the link is only inferred from wording and cannot survive an edit. |
+| `@ui:<UI-NNN>` | **Design traceability**: this scenario proves design item `UI-NNN` from `requirements/ui-inventory.md` (`@ui:UI-014`). Repeatable. Read by `sungen audit` (`UI-ITEM-UNCOVERED`). An item deliberately not tested is recorded as a comment instead: `# UI-DEFERRED: UI-002..013 — <reason>`. Rules: `sungen-tc-generation` § Design Inventory. |
 | `@manual` | Skip in generation |
 | `@known-defect` | The scenario is EXPECTED to be red — it asserts a live defect. It still runs and still reports as failed (never skipped, never "fixed"), and it stays a pass-through tag so `--grep @known-defect` selects it. **`[mobile]`** Its failure does NOT escalate the next scenario's `@reset:` tier: a red that was designed in is not evidence of leftover state |
 | `@auth:role` | Use auth storage state for role |
@@ -640,7 +641,8 @@ on mobile a dialog-scoped ref still resolves against the whole screen (`SG-W021`
 | `@cleanup:scroll` | Auto-cleanup: scroll to top after each test (cleanupPage) |
 | `@cleanup:storage` | Auto-cleanup: clear sessionStorage after each test (cleanupPage) |
 | `@screenshot:on-failure` | Auto-capture screenshot when test fails (base.ts fixture) |
-| `@parallel` | Opt-out: fresh page per test instead of serial default (for independent scenarios). Compiles on mobile too, but a single device/emulator gets no session-isolation benefit from it |
+| `@serial` | Opt-in: one shared page for an ordered, genuinely stateful sequence → `test.describe.serial()`. A failure skips the rest |
+| `@parallel` | Names the default (fresh page per test) — changes nothing. Compiles on mobile too, but a single device/emulator gets no session-isolation benefit from it |
 | `@beforeAll` | Hook: runs once before all tests → `test.beforeAll()` |
 | `@afterEach` | Hook: runs after each test → `test.afterEach()` (custom cleanup) |
 | `@afterAll` | Hook: runs once after all tests → `test.afterAll()` |
@@ -774,14 +776,14 @@ npx playwright test --grep "@smoke|@high"    # smoke OR high
 
 ### Serial vs Parallel (test execution mode)
 
-**Default: serial** — `test.describe.serial()` with shared page. Background runs once in `beforeAll`. Fail → skip remaining.
+**Default: isolated** — `test.describe()` with a fresh page per test. Background runs as `beforeEach`; a failing scenario does not skip the others. Write every scenario so it stands alone — no scenario may rely on state another one left behind. `@parallel` only names this default.
 
-**`@parallel` opt-out** — `test.describe()` with fresh page per test. Background runs as `beforeEach`. Use when scenarios are truly independent (validation rules, permission tests).
+**`@serial` opt-in** — `test.describe.serial()` with one shared page. Background runs once in `beforeAll`; a failure skips the rest. Use it only for a genuinely stateful, ordered sequence.
 
 | Mode | Generated | Page | Background | On fail |
 |---|---|---|---|---|
-| Serial (default) | `test.describe.serial()` | Shared | `beforeAll` (1 goto) | Skip remaining |
-| `@parallel` | `test.describe()` | Fresh per test | `beforeEach` (N goto) | Continue |
+| Isolated (default, `@parallel`) | `test.describe()` | Fresh per test | `beforeEach` (N goto) | Continue |
+| `@serial` | `test.describe.serial()` | Shared | `beforeAll` (1 goto) | Skip remaining |
 
 **Multiple auth groups need the default isolation.** A feature mixing `@auth:user` with `@no-auth` compiles as-is — features are parallel by default, and `@parallel` only names that default. What breaks it is `@serial`: one shared browser context cannot carry two different sessions, so the compiler errors and asks you to drop `@serial` or split the feature.
 
@@ -942,7 +944,13 @@ Feature: User Management
 
 ### Layer 2: `@afterEach` scenario (custom cleanup)
 
-Only when `@cleanup:*` tags aren't enough — feature-specific logic.
+Only when `@cleanup:*` tags aren't enough — feature-specific logic. `@afterEach` gets the per-test
+`page`, so UI cleanup steps work in it.
+
+It runs after every test it applies to — and it does NOT apply to the `@no-auth` group when the
+feature mixes `@no-auth` with other scenarios: an anonymous test has an empty session, so a cleanup
+that needs the signed-in page would fail it although its own steps passed. The hook is emitted inside
+each other group instead. A feature whose scenarios are ALL `@no-auth` keeps the hook for them.
 
 ### Layer 3: `@beforeAll` / `@afterAll` (optional)
 
@@ -967,8 +975,9 @@ Scenario: drop the seeded data after the last scenario
   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.
+- `@beforeAll` / `@afterAll` have no `page` fixture on an isolated (non-`@serial`) feature — keep
+  their steps to `@api:`/`@query:` preconditions and `expect` assertions there. `@afterEach` does get
+  the per-test `page`.
 
 **Rendering order in `.spec.ts`:**
 `test.describe` → `test.use(storageState)` → `test.use(autoCleanup)` → `test.beforeAll` → `test.beforeEach` → `test.afterEach` → `test.afterAll` → `test()` blocks.

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

@@ -225,12 +225,33 @@ Skip if `specs/.auth/<role>.json` already exists and a probe navigation reaches
 
 ---
 
+## Where each wave writes its result
+
+`sungen delivery` reads the per-target result file (`specs/generated/<name>/<name>-test-result.json`),
+which the JSON reporter in `playwright.config.ts` writes. Keep it that way in every wave:
+
+- **Never pass `--reporter`** — it replaces the config's reporters, the JSON reporter is switched off, and the run writes no result file.
+- **Subset waves (Phase 1–2) write to `test-results/sungen-wave.json`** — never to the per-target file (a subset would overwrite the unit's full result) and never to the default `test-results/results.json` (delivery falls back to that file when a per-target one is missing, so a 5-scenario smoke would read as the unit's result). `test-results/` is Playwright's output dir, wiped on every run — nothing to clean up.
+- **Full waves (Phase 3–4) write the per-target file** — the Phase 4 file is the result delivery shows.
+- **Scope every run to the unit** — `specs/generated/<name>/` (flow: `specs/generated/flows/<name>/`). Without a path, `--grep` runs every unit in `specs/generated/`.
+
+### Fix retries re-run only what the wave left red (Phase 2–3)
+
+- **The first run of a phase is its full wave.** Each **fix retry** is the same command plus `--last-failed`, written to `test-results/sungen-wave.json` — never to the per-target file.
+- **Retry immediately after the run whose failures you fixed.** `--last-failed` reads the failures of the *previous run only*: run any other test in between (a `-g` debug run) and the list now describes that run. If you did, re-run the full wave instead.
+- **Nothing left red → no retry.** On an empty list Playwright prints "No tests found", exits 1 and still writes a zero-test report — that is not a failure of the unit, and it is why a retry never writes the per-target file.
+- **A locale run (`SUNGEN_ENV=<env>`) writes `test-results/sungen-wave.<env>.json`** — the config inserts the env before `.json`; it is still a scratch file, nothing reads it.
+- **A retry does not show whether your fix broke a test that was green.** Phase 3's full first run catches a Phase 2 fix that did; Phase 4 catches a Phase 3 one.
+
+---
+
 ## Phase 1: Smoke Check (catch fundamentals)
 
 Run **up to 5 scenarios** — pick the first `@high` scenarios in the feature file.
 
 ```bash
-npx playwright test --grep "VP-.*-001|VP-.*-002|VP-.*-003|VP-.*-004|VP-.*-005" --reporter=line
+PLAYWRIGHT_JSON_OUTPUT_NAME=test-results/sungen-wave.json \
+  npx playwright test specs/generated/<name>/ --grep "VP-.*-001|VP-.*-002|VP-.*-003|VP-.*-004|VP-.*-005"
 ```
 
 **Purpose:** Detect broken fundamentals before running 50+ tests:
@@ -248,7 +269,15 @@ npx playwright test --grep "VP-.*-001|VP-.*-002|VP-.*-003|VP-.*-004|VP-.*-005" -
 Run all `@high` scenarios:
 
 ```bash
-npx playwright test --grep "@high" --reporter=line
+PLAYWRIGHT_JSON_OUTPUT_NAME=test-results/sungen-wave.json \
+  npx playwright test specs/generated/<name>/ --grep "@high"
+```
+
+Fix retry — only the scenarios this wave left red:
+
+```bash
+PLAYWRIGHT_JSON_OUTPUT_NAME=test-results/sungen-wave.json \
+  npx playwright test specs/generated/<name>/ --grep "@high" --last-failed
 ```
 
 If your Playwright config doesn't support tag grep, use scenario name grep from the feature file — collect VP IDs of `@high` scenarios.
@@ -261,12 +290,24 @@ Max 2 fix attempts in this phase.
 
 ## Phase 3: Full Run (@normal + @low)
 
-Run remaining scenarios:
+Run remaining scenarios — the whole unit, into its per-target result file:
 
 ```bash
-npx playwright test --reporter=line
+PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/<name>/<name>-test-result.json \
+  npx playwright test specs/generated/<name>/<name>.spec.ts
 ```
 
+A multi-feature screen (one result file per feature) or a locale run (`SUNGEN_ENV`): use the loop in `run-test` § "Playwright command guidelines".
+
+Fix retry — the failures only, into the wave file (the per-target file keeps this phase's full run until Phase 4 rewrites it):
+
+```bash
+PLAYWRIGHT_JSON_OUTPUT_NAME=test-results/sungen-wave.json \
+  npx playwright test specs/generated/<name>/<name>.spec.ts --last-failed
+```
+
+**Multi-feature screen — no `--last-failed` here.** Phase 3 ran one Playwright run per feature spec, so the failure list holds only the LAST spec's failures; a retry would skip every earlier feature's red tests without a word. Re-run the per-spec loop instead.
+
 Many selectors already fixed from Phase 2 (shared elements). Only diagnose **new** failures — selectors that only appear in lower-priority scenarios.
 
 Max 1 fix attempt. If `@low` scenarios still fail after fix → **report and move on**, don't loop.
@@ -275,12 +316,15 @@ Max 1 fix attempt. If `@low` scenarios still fail after fix → **report and mov
 
 ## Phase 4: Regression
 
-One final full run to confirm all phases together:
+One final full run to confirm all phases together — this per-target file is the result `sungen delivery` reads:
 
 ```bash
-npx playwright test --reporter=line
+PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/<name>/<name>-test-result.json \
+  npx playwright test specs/generated/<name>/<name>.spec.ts
 ```
 
+Same multi-feature / locale form as Phase 3.
+
 Report results. Do NOT enter another fix loop here.
 
 ---
@@ -458,13 +502,13 @@ user detail:
 
 ## Attempt Budget Summary
 
-| Phase | What runs | Max fix attempts | On failure after max |
-|---|---|---|---|
-| 0. Pre-gen | Playwright MCP snapshot → write selectors.yaml | 1 snapshot | Ask user — skip or retry navigation |
-| 0.5. Auth | Manual login in MCP browser → `browser_storage_state` → `specs/.auth/<role>.json` | 1 login | Ask user — retry login or fall back to `sungen makeauth` |
-| 1. Smoke | First 5 @high | 2 | Ask user — fundamentals broken |
-| 2. Priority | All @high | 2 | Report failures, continue to Phase 3 |
-| 3. Full | All tests | 1 | Report @low/@normal failures, continue |
-| 4. Regression | All tests | 0 | Report final results |
+| Phase | What runs | Fix retry runs | Max fix attempts | On failure after max |
+|---|---|---|---|---|
+| 0. Pre-gen | Playwright MCP snapshot → write selectors.yaml | — | 1 snapshot | Ask user — skip or retry navigation |
+| 0.5. Auth | Manual login in MCP browser → `browser_storage_state` → `specs/.auth/<role>.json` | — | 1 login | Ask user — retry login or fall back to `sungen makeauth` |
+| 1. Smoke | First 5 @high | the same 5 | 2 | Ask user — fundamentals broken |
+| 2. Priority | All @high | `--last-failed` | 2 | Report failures, continue to Phase 3 |
+| 3. Full | All tests | `--last-failed` (multi-feature screen: the per-spec loop again) | 1 | Report @low/@normal failures, continue |
+| 4. Regression | All tests | — | 0 | Report final results |
 
 **Total worst case: 5 fix attempts** (2+2+1), not unbounded loops. Phases 0 and 0.5 don't count toward fix budget.

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

@@ -154,7 +154,9 @@ For append: read highest `VP-<CAT>-<NNN>`, continue from next number. Never modi
 Auto-detected by `create-test` before invoking this skill:
 - `spec.md` — primary, always read if present
 - `spec_figma.md` — Figma supplement (PAT flow already done — just read the file)
-- `ui/*.png` — visual context
+- `ui/*.{png,jpg,jpeg,webp,gif}` — design images. **Every one is read**, and turned into the Design Inventory below — not just "visual context".
+- `ui/figma-meta.md` — Figma MCP capture (`sungen-capture` mode figma-mcp): `## Components` and `## Text Content` feed the Design Inventory; `## Text Content` also supplies exact labels for `test-data.yaml`.
+- `ui-inventory.md` — the Design Inventory (written by create-test, see § Design Inventory). When it already exists, keep its ids and append new items; never renumber.
 - `test-viewpoint.md` — test conditions checklist; scan entirely regardless of format.
   Format varies across projects: hierarchical table (Level 1–4 columns), flat checklist,
   prose, or mixed. Regardless of format:
@@ -181,6 +183,40 @@ This means: do not test other screens' UI layout or navigation. It does NOT mean
 
 ---
 
+## Design Inventory (UI items)
+
+**When:** the unit holds any design source — images in `requirements/ui/`, `ui/figma-meta.md`, or `spec_figma.md`. Without one, skip this section.
+
+**Why:** a design read "for visual context" leaves no trace. An item that exists only on the design (a column `spec.md` never names) or contradicts the spec is then missed by the author AND the reviewer, and "deliberately deferred" looks exactly like "never seen". `sungen audit` checks this file (`UI-INVENTORY-MISSING`, `UI-INVENTORY-INCOMPLETE`, `UI-ITEM-UNCOVERED`).
+
+**Reading order:** `spec.md` (authoritative) → `spec_figma.md` → `ui/figma-meta.md` (`## Components`, `## Text Content`) → **every** image in `ui/`. Many images: group them (primary screen vs states/variants) but read them all — an unread state screen is an un-inventoried one.
+
+**Write `requirements/ui-inventory.md`** — one row per component, table column, button/link, field, state (empty/error/loading/disabled), and design annotation:
+
+```markdown
+# UI Inventory — <screen>
+images read: 3/3 · figma-meta.md: read · spec_figma.md: absent
+
+| ID | Item | Kind | Source | Seen in |
+|---|---|---|---|---|
+| UI-001 | Job List table | table | spec+design | ui/list.png |
+| UI-002 | Contract plan | column | spec+design | ui/list.png |
+| UI-014 | Salary range | column | design-only | ui/list.png |
+| UI-015 | Status badge "Closed" | column | conflict — spec says "Expired" | ui/list.png |
+```
+
+- **Source:** `spec+design` (both name it) · `design-only` (only the design shows it) · `conflict` (they disagree — say how in the cell). `spec.md` stays authoritative; a conflict is reported, never silently resolved in either direction.
+- **IDs** `UI-NNN` are append-only, like scenario ids: re-runs keep existing rows and continue numbering.
+- `images read: N/N` counts the images you actually opened against the images in the folder.
+
+**Account for every `design-only` / `conflict` item in the `.feature`** — either:
+- **cover it**: tag the scenario that proves it `@ui:UI-014`, or
+- **defer it with a reason** in a feature comment: `# UI-DEFERRED: UI-002..013 — per-column checks are owned by job-detail`. A deferral without a reason defers nothing.
+
+`spec+design` items are covered through the spec (`@spec:`), and citing their ids is optional.
+
+---
+
 ## Generation Workflow
 
 ### Step 1 — Orient: patterns + risk
@@ -219,6 +255,10 @@ Viewpoint items:     [TV-01 – <exact wording from test-viewpoint row 1>]
                      [TV-02 – <exact wording from test-viewpoint row 2>]
                      → one entry per row/bullet in test-viewpoint.md, regardless of format
                      → leave empty if no test-viewpoint.md present
+UI items:            [UI-014 – Salary range column (design-only) → covered by VP-TAB-012]
+                     [UI-002..013 – per-column checks → deferred: owned by job-detail]
+                     → one entry per Design Inventory row: covered / deferred-with-reason / uncovered
+                     → leave empty if the unit has no design source
 Spec gaps:           [G1 – behavior undocumented → verify with dev]
 ```
 

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

@@ -152,6 +152,7 @@ Build a mapping table: for each applicable group, does the feature have a matchi
 | **Account Status** | Deleted / blocked / inactive account login | VP-LOGIC | corresponding account data → error message |
 | **Security** | SQL Injection; XSS; Data Integrity (edit dropdown/remove `disabled` via DevTools → server rejects). SQL on LIKE/search fields → 2 TCs per the `sungen-viewpoint` SQL 2-layer rule. | VP-SEC | `with {{xss_*}}`/`{{sql_*}}`; data-integrity usually `@manual` |
 | **Cross-surface outcomes** | Admin action → outcome on user-facing surface (portal, mobile, widget); spec defines display condition on another URL | VP-LOGIC-CS | `@high @manual` per surface per business rule — at minimum 1 per cross-surface rule; use `@auth:role` + `@extend` if surface reachable in same test run |
+| **Design items** *(when `requirements/ui/*`, `ui/figma-meta.md` or `spec_figma.md` exist)* | Every component / column / button / state the design shows is in `ui-inventory.md`; each `design-only` / `conflict` item is covered or deferred with a reason. Read the images yourself — the inventory can be incomplete | UI-NNN | `@ui:UI-NNN` on the proving scenario, or `# UI-DEFERRED: UI-NNN — <reason>`; rules in `sungen-tc-generation` § Design Inventory |
 
 **Mobile units add four categories** (`@platform:mobile/android/ios` only). Each maps to a theme the
 `sungen audit` mobile catalog scores, so a gap here is a scored gap, not a stylistic note — the
@@ -374,6 +375,12 @@ If `selectors/<name>.yaml` exists, count lines matching `@needs-live-verify` (pr
 | Behavior Handling / Account Status | ... | ... |
 | Security (XSS/SQLi) | ... | ... |
 | Cross-surface outcomes | ... | ... |
+| Design items | n/a / ✓ / ✗ | ... |
+
+### Design ↔ Feature (when the unit holds design sources)
+- Images read: <n>/<n> · inventory items: <n> (covered <n> · deferred <n> · uncovered <n>)
+- Not inventoried: <item> (<image>) …
+- Mislabelled / unproven: UI-NNN …
 
 ### ✗ Must-fix
 1. [DIMENSION] VP-XXX issue description

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

@@ -105,8 +105,10 @@ export default defineConfig({
     /* Per-action timeout (click, fill, etc.) */
     actionTimeout: 10_000,
 
-    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
-    trace: 'on-first-retry',
+    /* Trace for a failed test. CI: recorded on the first retry (CI retries). Local: no retries, so
+       'on-first-retry' would never record one — keep the trace of every failed test instead.
+       See https://playwright.dev/docs/trace-viewer */
+    trace: process.env.CI ? 'on-first-retry' : 'retain-on-failure',
 
     /**
      * Capture screenshot after each test failure.

package/src/orchestrator/templates/specs-url-assert.ts

@@ -205,6 +205,26 @@ interface SettleOpts { settleMs?: number; networkIdleMs?: number }
  * 3000) bounds step 1. Both are runtime knobs, so a slow environment is a config change, not a
  * regenerate.
  */
+/**
+ * A millisecond budget from the environment. `Number()` alone turned `"1s"` / `"abc"` into NaN and
+ * `""` into 0 (`??` keeps an empty string): the hold loop then never ran, so a late redirect passed
+ * unseen, and a 0 / NaN networkidle timeout means "no timeout" to Playwright — the step waited out
+ * the whole test (#856). Unset or empty means the default; a malformed value falls back to it and
+ * says so, once per variable. `allowZero` for a knob where 0 is a real choice (no hold).
+ */
+const warnedEnv = new Set<string>();
+function msEnv(name: string, fallback: number, allowZero = false): number {
+  const raw = process.env[name]?.trim();
+  if (!raw) return fallback;
+  const value = Number(raw);
+  if (Number.isFinite(value) && (value > 0 || (allowZero && value === 0))) return value;
+  if (!warnedEnv.has(name)) {
+    warnedEnv.add(name);
+    console.warn(`[sungen] ${name}=${JSON.stringify(raw)} is not a ${allowZero ? 'non-negative' : 'positive'} number of milliseconds — using the default ${fallback}.`);
+  }
+  return fallback;
+}
+
 async function settleAndHold(
   page: SettleablePage,
   matches: (u: URL) => boolean,
@@ -212,8 +232,9 @@ async function settleAndHold(
   label: string,
   consequence: string,
 ): Promise<void> {
-  const settleMs = opts.settleMs ?? Number(process.env.SUNGEN_URL_SETTLE_MS ?? 1000);
-  const networkIdleMs = opts.networkIdleMs ?? Number(process.env.SUNGEN_URL_NETWORKIDLE_MS ?? 3000);
+  // 0 holds nothing (the operator's call); 0 for networkidle would mean "no timeout", so it is refused.
+  const settleMs = opts.settleMs ?? msEnv('SUNGEN_URL_SETTLE_MS', 1000, true);
+  const networkIdleMs = opts.networkIdleMs ?? msEnv('SUNGEN_URL_NETWORKIDLE_MS', 3000);
   const arrivedAt = page.url();
 
   await page.waitForLoadState('networkidle', { timeout: networkIdleMs }).catch(() => undefined);