@sun-asterisk/sungen 3.2.32 → 3.2.34-beta.1

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/*]"
@@ -79,12 +79,21 @@ Stop here for mobile — do not continue to the web path.
 > ⛔ **The `.feature` Gherkin is QA-approved and FROZEN.** During auto-fix you may write
 > **only** `selectors.yaml`, `test-data.yaml` (and other `*.yaml` data), plus the **one narrow
 > `.feature` edit** allowed: the **element-type token** on a `[Reference]` (e.g. `field`→`textbox`,
-> `button`→`link` — selector resolution, not test logic). You must **NOT** change the Gherkin's
+> `button`→`link` — selector resolution, not test logic). A second, equally narrow exception:
+> adding **`@known-defect:DEF-NNN`** to a scenario's tag line once its defect record exists (step 8)
+> — that tag only, the tag line only. You must **NOT** change the Gherkin's
 > content or logic: no rewriting/adding/removing steps, no `wait for` steps, no changed expected
 > values, no weakened assertions. A failure that would need any of those is a **CANDIDATE BUG /
 > 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 +104,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 +183,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 +199,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:
 
@@ -256,8 +272,8 @@ question already.
 5. **Phase 1 — Smoke Check**: Run first 5 `@high` scenarios only. If failures → diagnose, fix fundamentals (page selector, auth, base @steps), re-run. Max 2 attempts. If still broken → ask user.
 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).
+8. **Phase 4 — Regression**: One final full run. No more fix loops. Then run `sungen triage --screen <name>` and render its table as the results summary: every red or flaky scenario already sits in one class (`product-candidate`, `unclassified`, `test-defect`, `environment`, `blocked-capability`, `known-defect`, `flaky`) with the rule and one evidence line. You may move an `unclassified` row into a class only with a written evidence line of your own. You may never turn a `product-candidate` into a `test-defect` by editing the `.feature` or the expected value — the Gherkin is frozen; report it as a candidate bug. For each `product-candidate` you judge to be a product bug, run `sungen defect draft --screen <name> --scenario "<title>"`, fill the record's Summary, check its Expected against `spec.md`, then add `@known-defect:DEF-NNN` to that scenario's tag line (the tag-only exception above). The severity in the draft is `proposed` — confirm it with QA (`AskUserQuestion`) before the hand-back and set `severity_source: qa`. A row you judge is not a product bug stays in the summary with your reason, and gets no record. A `bare-timeout` row (`unclassified`) is never re-run inside this command — Phase 4 was the final run; offer the re-run in Next steps.
+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 +341,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 +376,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 +418,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:
@@ -421,3 +480,7 @@ If tests **failed** (after retries):
 - **`/sungen-create-test <name>`** — Revise test cases
 {{/cap}}
 - **Done for now** — I'll fix manually later
+
+If the triage table has `bare-timeout` rows, put this option FIRST and mark it Recommended: **Re-run the N timed-out scenario(s) once** — it tells a slow environment from a hanging page (name them). Ask; never re-run them on your own: a scenario may create data or spend an OTP/rate limit on a shared environment. On a yes, re-run only those scenarios with the subset-merge flow (§ Playwright command guidelines — never overwrite the result file), then `sungen triage` again:
+- green now → move the row to `flaky` (or `environment`) with that as the evidence line;
+- the same timeout again → read the trace's last action: stuck after a submit or a navigation → candidate bug, handled as in Phase 4 step 8 (`sungen defect draft`, QA confirms the severity); stuck in a wait the test itself defines → `test-defect`.

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-delivery/SKILL.md

@@ -93,6 +93,20 @@ every variant is N/A) and never a bare state word. **`N/A` leaves the denominato
 and actual result share one column `P`; the header row is frozen; ISO dates; landscape print with
 repeated header rows.
 
+**Re-running delivery keeps the tester's Manual results** (#756, since 3.2.33). Before overwriting,
+the CLI reads the existing workbook's **Manual** sheet and carries each variant's `L`–`P` cells into
+the new one by `VP-…` ref, verbatim. A hidden `_sungen_manual` sheet stamps each case's fingerprint,
+so a result recorded against an older procedure is reset to `Pending` with the previous result
+moved into Note. Relay the CLI's `Manual results:` lines to the user: `reset to Pending` means those
+cases must be run again by hand; `not carried` names results whose case left the feature. The
+**Auto** sheet is not carried (the run report owns its Result), and rows a tester added by hand
+have no ref and are not carried. Never tell the user to copy or rename the file to protect manual
+results. A second `not carried` line names a duplicated row (only the first copy is kept) — tell
+the user to merge it by hand. If the CLI prints `not written: cannot read …` (locked or damaged) or
+`not written: … has no "Manual" sheet` (renamed), the unit was deliberately NOT written to protect
+the results: ask the user to close the file or rename the sheet back to `Manual`, or move the file
+aside. Never delete, rename or move it yourself.
+
 `Coverage` sheet — requirement coverage table (every FR/TR/NFR id with an explicit status),
 target × category grid with explicit `—` gaps, dispositions, manifest. CSV mirrors the same model
 flat with a `Level` column (`item`/`variant`) + a requirement-coverage appendix.

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:
@@ -53,6 +73,8 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 
 > **Cardinal sin (do NOT do this):** a `password > 8 chars` rule fails on a 6-char input → "fix" it to `>= 6` so the test passes. The logic is now meaningless. A failing assertion is a **finding**, not a chore.
 
+**`sungen triage` makes the first pass for you.** Its classes are this section's split: `test-defect` = selector-resolution / test-data failure (auto-fix scope), `product-candidate` = assertion-value failure with an Expected and a Received (apply the spec question above), `environment` = the run itself (fix the setup, not the test), `unclassified` = yours to judge — an assertion on an element that never appeared lands here, because a wrong selector and a missing message look the same.
+
 **Auto-fix loop scope:** the run-test auto-fix loop engages ONLY on **selector-resolution** failures. On an assertion-value failure where the app contradicts the spec → **HALT and report**, do not loop it into passing.
 
 **Never hand-edit the generated `.spec.ts`** (e.g. inserting `page.evaluate`/`fetch` to bypass a broken control). `sungen script-check` regenerates the spec from `.feature` and flags any edit as DRIFT — regenerate, don't patch.
@@ -128,8 +150,10 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | `SG-W034` | A `see [X] column with {{v}}` step runs inside a table whose rows are declared with a **`rows:` shape**, so the row is not an ARIA row and holds no ARIA cells — but the assertion's only other way to reach a cell is `getByRole('cell')`, which matches nothing there. `columns.<col>.index` cannot rescue it: it indexes that same empty set. Before this the step failed as a timeout blaming the app. Not reported on a real `<table>`, where the role fallback is correct | Name the cell on the column: `columns: { title: { index: 0, header: 'Title', elements: { cell: { type: locator, value: '.job-title' } } } }`. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
 | `SG-E035` | **`table match data:` on a table declared with a `rows:` shape** and no matching `columns:` entries. The assertion reads its header row from `thead tr` and addresses cells as `td, th`; a <div> list has neither — forever, not as a render race — so the step could only wait out every timeout and fail on an empty header row. Refused at compile time, naming the columns it needs | Declare each DataTable column on the table entry with the selector that matches its cell inside a row: `columns: { title: { index: 0, header: 'Title', elements: { cell: { type: locator, value: '.job-title' } } } }`. Declaring columns also removes the runtime header read on a real `<table>`. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
 | `SG-W036` | A **`remember [X] … as {{v}}` capture through a `locator`/`css` selector with no `nth:`**. A capture reads ONE element and the step takes the FIRST match — the right default, and what the documented `nth: 0` workaround asked for after Playwright's strict mode turned a list-shaped selector into a hard failure naming the count. But the first of many is a decision: if the selector describes every item in a list, the captured value is the first row's. Not reported for testid/label/placeholder/role+name/text entries, which name a particular thing | Declare the index (`nth: 0`) to say the first one is meant, or narrow the selector to the single element. This is a selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
+| `SG-W037` | A **`type: page` entry saying something about the QUERY that the compiler cannot use**. Two causes: the entry's `value` carries a `?`/`#`, which is DROPPED (a page value is the path only — the pattern is matched against `u.pathname`, which never holds a query), or `query:` declares something other than `any`, which is ignored rather than read as permissive so a typo cannot quietly switch off the bare-page assertion. Both used to be silent, and the first is the trap: an author who hit "a bare `see [X] page` requires NO query" reaches for the query in the value, gets byte-identical output, and no hint why | To assert the query, declare it on the STEP (`see [X] page with {{v}}`). If the query is generated at run time — `/admins/detail?id=<the row just clicked>`, which no literal can express — add `query: any` to the entry: the query is then not part of that page's identity. selectors.yaml-only fix — allowed inside the run-test auto-fix loop |
+| `SG-E038` | A **`{{var}}` the compiler cannot resolve** — the feature has no test-data file of its own, the key is absent, or it holds a list/map where a value was needed. This used to emit the PLACEHOLDER TEXT as the value: `fill [Partner Customer ID] field with {{valid_partner_id}}` compiled to `fill('${valid_partner_id}')`, typing those 20 literal characters into the app with `generate` exiting 0. A field with no format validation accepts the string, the server sees an unknown user, and the scenario fails at the assertion it was written to fail at — a suite that looks correct while feeding the system garbage. Every run also shares the SAME literal, so a scenario needing a fresh user silently reuses one. The step now compiles to a `throw` naming the ref and the file | Add the key to the file the message names. Note a feature resolves `{{var}}` against a data file named after **itself** — `qa/screens/<screen>/test-data/<feature>.yaml` — so the second `.feature` in a screen directory needs its own data file, not the screen-named one. `sungen data crosscheck` reports the same gap before you compile |
 
-A diagnostic never changes generation's own exit code — `sungen generate --strict` turns any collected diagnostic into a non-zero exit for CI gates. They are not all inert, though: **`SG-W001`, `SG-W011`, `SG-E020`, `SG-E021`, `SG-W020`, `SG-E023`, `SG-E024`, `SG-E025`, `SG-E026`, `SG-E027` and `SG-E035` additionally compile the offending step to a runtime `throw`, and `SG-E031` refuses the whole file** — a step that reads as a check and silently checks nothing is worse than one that fails loudly. Generation always COMPLETES: the rest of the scenario and the rest of the file still compile. `SG-E022` is the odd one out — it blames the compiler, not your `.feature`, and throws nothing (the file is written so you can inspect it).
+A diagnostic never changes generation's own exit code — `sungen generate --strict` turns any collected diagnostic into a non-zero exit for CI gates. They are not all inert, though: **`SG-W001`, `SG-W011`, `SG-E020`, `SG-E021`, `SG-W020`, `SG-E023`, `SG-E024`, `SG-E025`, `SG-E026`, `SG-E027`, `SG-E035` and `SG-E038` additionally compile the offending step to a runtime `throw`, and `SG-E031` refuses the whole file** — a step that reads as a check and silently checks nothing is worse than one that fails loudly. Generation always COMPLETES: the rest of the scenario and the rest of the file still compile. `SG-E022` is the odd one out — it blames the compiler, not your `.feature`, and throws nothing (the file is written so you can inspect it).
 
 ### Runtime error → `Test data "<key>" references ${QA_*} but the environment variable is not set`
 

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

@@ -629,7 +629,9 @@ 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. `@known-defect:DEF-NNN` names the record in `qa/defects/DEF-NNN-*.md` (`sungen defect draft` writes it); `sungen audit` reports `DEFECT-REF-MISSING` when that file does not exist. **`[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 |
 | `@no-auth` | Disable inherited auth |
 | `@steps:name` | Define reusable step block (base scenario) |
@@ -639,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()` |
@@ -695,6 +698,14 @@ Rules that matter when generating:
   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.
+  A scenario tagged **`@known-defect`** escalates nothing either: its red was designed in, so making
+  the next scenario pay a harder reset for it buys nothing, on every run, forever.
+- **Escalation never picks a tier this session cannot perform.** Reinstalling needs the app's build
+  file, so when the app is attached by package the ladder caps at `data` (Android) / `soft` (iOS) and
+  says it capped, instead of throwing. Nothing asked for the escalated tier, and the throw would land
+  in `beforeEach` — a hook failure, which skips every remaining scenario in the FILE. The cap never
+  goes BELOW the declared tier: a tier you asked for that the session cannot do still throws by name,
+  because that one is an unmet contract rather than a recovery the runner chose.
 - **`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).
@@ -765,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.
 
@@ -933,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)
 
@@ -958,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-harness-audit/SKILL.md

@@ -35,7 +35,11 @@ user-invocable: false
 | **BALANCE** | secondary viewpoints (UI/validation/security) outweigh business-core | **Stop expanding** secondary viewpoints; generate the missing business-core scenarios first. Do not add more subscription/UI variants while core is thin. |
 | **TRACE** | scenarios use ad-hoc `VP-<CAT>-NNN` codes not linked to the viewpoint-overview | Make each scenario map to a viewpoint-overview id (align category codes, or add a mapping comment). |
 | **ORACLE-URL-ONLY** | every `Then` in the scenario is a page/URL assertion — it proves a path was pushed, not that the page rendered; on a permission/guard scenario a late 403 redirect turns it falsely green | Add `anchor:` to the page selector (one line per screen; every `see [X] page` on it becomes a content oracle) or a content assertion after the page step. Never delete the page step to silence it. |
+| **DEFECT-REF-MISSING** | a `@known-defect:DEF-NNN` tag names no file in `qa/defects/` | Draft the record (`sungen defect draft --screen <name> --scenario "<title>"`) or correct the id. Never drop the tag to silence it — the scenario still asserts a live defect. |
+| **DEFECT-ORPHAN** (info) | an open defect record names a scenario this unit no longer has | Update the record's `scenarios:` to the renamed title, or close the record if the scenario was removed on purpose. Nothing in the suite to repair. |
 | **UNIVERSAL** | a universal theme (error/empty-state, accessibility) is absent | Low priority — add if in scope; otherwise note as out-of-scope with reason. |
+| **VIEWPOINT-DRAFT-UNREVIEWED** | `test-viewpoint.md` carries `drafted-by: ai`: no baseline, `atomicLedger` + `traceability` held | A QA action, not a repair. Keep generating; list the decision `sungen audit --screen <name> --accept-viewpoint` in the hand-back for the QA to run after reviewing the draft. Never run it, never delete the line yourself. |
+| **VIEWPOINT-REVIEW-OPEN** (info) | `requirements/viewpoint-review.md` still has `[ ]` rows | A QA action. Report the count in the hand-back with the option to open the file; never tick rows or edit a QA-written viewpoint to clear it. Not scored. |
 
 ## P5 steps for deep cross-screen / list coverage
 
@@ -64,7 +68,7 @@ Use these when repairing GATE/DEPTH findings for the hard viewpoints (cart/detai
 ## Repair loop rules
 
 1. **Budget = 3 rounds.** Re-run `sungen audit` after each repair; track score delta.
-2. **Stop when** `gateStatus == PASS` AND `findings` empty — or budget exhausted.
+2. **Stop when** `gateStatus == PASS` AND `findings` empty — or budget exhausted. QA-action findings (`VIEWPOINT-DRAFT-UNREVIEWED`, `VIEWPOINT-REVIEW-OPEN`) do not count: no repair clears them.
 3. **Never fake a pass.** A shallow `see [Cart] page` does not satisfy `cart-correctness`. If a gap is genuinely cross-screen or needs capabilities the DSL lacks (e.g. capture an element value to compare elsewhere), **report it as a residual gap / flow item** instead of forcing a green gate.
 4. **EP/data families are OK.** A `duplicates` cluster with `sameDataLikely=false` is an intentional equivalence-partition family (e.g. many invalid-email cases) — keep it; only collapse `sameDataLikely=true` exact duplicates.
 5. **Advisory findings — surface, don't gate.** `MANUAL-REASON-MISMATCH` → fix the scenario's `@manual:Mx` code (so the planner recommends the right driver) during repair. `CAPABILITY-SUGGESTION` → **present it to the user as a next-step option** (e.g. "N @manual could be automated — `sungen capability add api db`?"), **recommend-only — never auto-install**. `VERIFICATION-OUT-OF-SCOPE (api|db)` → the unit uses `@api`/`@query`/`@requires:api|db` verification the project's recorded **test type** never opted into (E2E/UI-only per `capabilities.yaml`, and the viewpoint doesn't ask for it). During repair: **rewrite the oracle to be UI-observable** (or downgrade the deep check to an `(optional deep check: …)` note); only keep the API/DB verification if the project genuinely tests that layer — then record it (`verification: [ui, api]` / `sungen capability add`). Keep API/DB-in-E2E to the ≤20% band. Neither of these fails the gate.

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-selector-keys/SKILL.md

@@ -128,7 +128,10 @@ back to the feature's own path (or `/<ref>/`) and warns `SG-W013`: a test that r
 
 If the label is used by only ONE type, the base key (no suffix) is fine — suffix only on collision.
 
-Type aliases (normalized automatically):
+Type aliases (normalized automatically). The suffix and the step may use **different spellings of
+the same type** — `confirm--modal` resolves for `[Confirm] dialog` and `confirm--dialog` resolves
+for `[Confirm] modal`. Prefer the normalized suffix for consistency; either is found.
+
 | Gherkin type | Normalized suffix |
 |---|---|
 | title, label, caption, message | `text` |
@@ -143,6 +146,15 @@ Type aliases (normalized automatically):
 | column | `columnheader` |
 | list-item | `listitem` |
 
+When the step names a type from this table, only a key whose suffix is a spelling of that type is
+used — `[Confirm] dialog` will not fall back to an unrelated `confirm--popup` entry. It reports the
+keys it looked for, so the fix is to add one of them.
+
+A bare `[Confirm]` keeps the older, looser fallback and matches any `confirm--*` entry, because with
+no type there is nothing to match a suffix against. So does a `[Ref]` followed by a word that is not
+an element type at all — `Then User see [Quick Panel] is hidden` reads `is` as that word. This is
+what keeps state-clause steps working on a label whose keys are all suffixed.
+
 ## Nth-Suffixed Keys
 
 When targeting a specific occurrence by index, add `--N` suffix: