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

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

@@ -64,7 +64,8 @@ restated from screen specs the project does not hold, say so: the audit reports
 `SPEC-RESTATED-UNVERIFIED` because `specFR 100%` over a hand-copied list certifies the copy, not
 the source.
 
-**The viewpoint carries BOTH classification axes.** `VP-LOGIC / VP-VAL / VP-SEC / VP-NAV` classify
+**A viewpoint you draft (mode 2, step 3) carries BOTH classification axes** — on a QA-written one
+(mode 1) a missing axis or guarantee line is a row in `viewpoint-review.md`, not an edit. `VP-LOGIC / VP-VAL / VP-SEC / VP-NAV` classify
 by TECHNICAL RISK; `BF / AF / EF` classify by BUSINESS BRANCH. They answer different questions and
 neither replaces the other — a reviewer needs to see both, so use the compound id
 (`VP-SEC-EF02-001`) and give the viewpoint a section per flow as well as its priority table by
@@ -81,8 +82,8 @@ questions and only one of them is a yardstick:
 | `flow-contract.yaml` | the USE CASE — actor · trigger · goal · precondition · both guarantees · the flow inventory | `flowCoverage` |
 | `test-viewpoint.md` | the CLAIMS the suite must prove — cross-screen concerns, edge cases, design decisions, open questions, priorities | `atomicLedger` · `traceability` |
 
-If `requirements/test-viewpoint.md` is missing, **write it before generating** (`add-flow` scaffolds
-a template; a run that deletes or replaces it has removed the yardstick). Without it two scored
+If `requirements/test-viewpoint.md` is missing or still the scaffold, **draft it before generating**
+(mode 2, step 3 — `add-flow` scaffolds the template; a run that deletes or replaces it has removed the yardstick). Without it two scored
 axes are excluded and four sensors cannot run at all — the atomic ledger, the
 declaration-integrity checks, the browser-gesture check and the two-way continuity check — so the
 audit reports `VIEWPOINT-MISSING` and the result is *unmeasured*, not passing. And the reason the
@@ -95,8 +96,8 @@ ordering choice: a yardstick derived from the scenarios reads 100% by constructi
 dropped along the way stops being missing from anything. `sungen audit` now reports
 `VIEWPOINT-ADOPTED-POST-HOC` on the first sighting of a viewpoint alongside an existing suite and
 holds `atomicLedger` + `traceability` as unverified until a human accepts it — so the honest move
-is to write the claims from `spec.md` and the contract, mark plainly that they are a draft for QA
-review, and let the QA revise before `--accept-viewpoint`. **You never run `--accept-viewpoint` yourself** — `sungen next` lists it as a `⚖ decide` step for exactly this reason: an agent accepting the yardstick it wrote in the same session makes `atomicLedger` and `traceability` read 100% against its own checklist, and the Exception Flow it forgot stops being missing from anything. Present the acceptance to the QA (`AskUserQuestion`) with what the file declares, and stop.
+is to write the claims from `spec.md` and the contract, mark the file `drafted-by: ai` (its first
+line), and let the QA revise before `--accept-viewpoint`. **You never run `--accept-viewpoint` yourself** — `sungen next` lists it as a `⚖ decide` step for exactly this reason: an agent accepting the yardstick it wrote in the same session makes `atomicLedger` and `traceability` read 100% against its own checklist, and the Exception Flow it forgot stops being missing from anything. Present the acceptance to the QA in the hand-back (`AskUserQuestion`) with what the file declares — never as a question mid-run.
 
 **When you give a claim an id, a scenario must carry that id.** The id is the contract: a claim
 whose id no scenario carries is reported MISSING, and word overlap will not rescue it. Several
@@ -110,8 +111,9 @@ narrow the claim to what is actually proven.
 
 **Priority comes from the declaration.** A scenario tagged `@high` under a viewpoint row that says
 `Low` is `PRIORITY-CONTRADICTED` — a smoke run selects on the tag, so it picks up work the QA
-deliberately deprioritised. Inherit the declared priority; if the tag is right, fix the
-declaration instead of leaving both on record.
+deliberately deprioritised. Inherit the declared priority; if the tag is right, the declaration is
+what is wrong — fix it in your own draft (mode 2), or report it in `viewpoint-review.md` for the QA
+(mode 1). Never leave both on record silently.
 
 ---
 
@@ -205,26 +207,15 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
    **Screen requirements** — check `<base>/${input:name}/requirements/`:
 {{/cap}}
    - If `spec.md` exists → read it as PRIMARY source (sections, fields, validation rules, business rules, states).
+   - `test-viewpoint.md` → **Viewpoint — review or draft** below, once every source is read. No question here.
 {{#cap parallel-subagents}}
-   - If `test-viewpoint.md` exists → read it. If it only contains HTML comments (scaffold template), use `AskUserQuestion` to ask:
-     - **Fill test-viewpoint.md first** — I'll help you identify edge cases, known issues, and design decisions for this screen before generating tests
-     - **Continue without it** — generate tests from spec and other sources only
-
-   **A filled `test-viewpoint.md` is an INPUT — never an output.** Do NOT rewrite, re-order, or replace its viewpoint declarations as part of generating tests. It is the yardstick two scored axes measure the suite against (`traceability`, `atomicLedger`): rewrite it to match what you just generated and both read 100% by construction, while any viewpoint you quietly dropped stops being missing from anything. If the declared taxonomy genuinely does not fit the screen, **report the mismatch and ask** — propose the diff (ids added / removed and why) and let the QA decide. `sungen audit` reports `VIEWPOINT-BASELINE-CHANGED` and stops scoring both axes when this file moves, so an unannounced rewrite lowers the score rather than raising it.
 
    **Context discovery (prefer an isolated agent).** Reading all sources here can flood this context. **Claude Code:** spawn the **`sungen-discovery`** sub-agent (Task tool, `subagent_type: sungen-discovery`) to read spec/figma/ui/live in isolation and return a **compact discovery report** (sources, completeness, conflicts, recommended route, key facts); use that report instead of pasting raw sources. **Copilot / no sub-agents:** do the reading inline as below.
 {{/cap}}
-{{^cap parallel-subagents}}
-   - If `test-viewpoint.md` exists → read it. If it only contains HTML comments (scaffold template), ask:
-     - **1) Fill test-viewpoint.md first** — identify edge cases, known issues, and design decisions before generating tests
-     - **2) Continue without it** — generate tests from spec and other sources only
-
-   **A filled `test-viewpoint.md` is an INPUT — never an output.** Do NOT rewrite, re-order, or replace its viewpoint declarations while generating tests. It is the yardstick two scored axes measure the suite against (`traceability`, `atomicLedger`): rewrite it to match what you just generated and both read 100% by construction, while any viewpoint you quietly dropped stops being missing from anything. If the declared taxonomy genuinely does not fit the screen, **report the mismatch and ask** — propose the diff (ids added / removed and why) and let the QA decide. `sungen audit` reports `VIEWPOINT-BASELINE-CHANGED` and stops scoring both axes when this file moves.
-{{/cap}}
 
    **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 +233,19 @@ 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.
+
+   **Viewpoint — review or draft (no question asked).** Run `sungen viewpoint scan --screen <name> --json` (a flow: `--flow <name>`). It reads ids and item numbers only. Its `mode` (1 or 2) and `modeReason` name the row below — follow them; the table explains them:
+
+   | `requirements/test-viewpoint.md` | Mode | You |
+   |---|---|---|
+   | missing; nothing but the scaffold (headings, `<…>` placeholders, empty tables); or ONE OR MORE VP rows and every one of them lacks a `Kỳ vọng` | **2 — draft** | Write it from `sungen-viewpoint/viewpoint-template.md`, first line `drafted-by: ai`, keeping any row already there. Each row answers "test CÁI GÌ" and "kỳ vọng ra sao"; where the spec states the expected result, write it; only what the spec leaves open becomes a closed question in mục 5, never an invented expectation; every accepted-input class the spec names (whitelist, value list, conversion) gets an "accepted, no error" row, citing the list by name; a VP that needs a real device, account or time is `# MANUAL/ENV`. Then scan again. |
+   | first line `drafted-by: ai` | **2 — re-review** | Your draft, not yet accepted: you may revise it, from the spec and the review. |
+   | anything else — QA-written, with or without VP ids (a scaffold from an older sungen reads as this row too: delete the file to have it drafted) | **1 — review only** | Never edit it. Generate from it as written; a gap is reported, not filled. |
+
+   Then review it with `sungen-viewpoint/review-checklist.md` and the scan JSON (mode 2: fix your draft until only QA decisions remain) and write `requirements/viewpoint-review.md`, overwritten each run. Mode 2 also runs `sungen audit --screen <name> --no-baseline` before generating. Keep the review's row count for the hand-back.
+
+   **A filled `test-viewpoint.md` is an INPUT — never an output.** Do NOT rewrite, re-order, or replace its viewpoint declarations as part of generating tests — your own draft included: a draft is revised from the spec, never from the scenarios. It is the yardstick two scored axes measure the suite against (`traceability`, `atomicLedger`): rewrite it to match what you just generated and both read 100% by construction, while any viewpoint you quietly dropped stops being missing from anything. If the declared taxonomy genuinely does not fit the screen, **report the mismatch in `viewpoint-review.md`** — the diff (ids added / removed and why) — and let the QA decide. `sungen audit` reports `VIEWPOINT-BASELINE-CHANGED` and stops scoring both axes when this file moves, so an unannounced rewrite lowers the score rather than raising it.
 
    Summarize what you found in requirements and present to the user.
 
@@ -284,6 +287,7 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
      - **BALANCE** → stop expanding secondary viewpoints; add business-core scenarios first.
      - **TRACE** → align `VP-` ids with the viewpoint-overview.
    - Stop when the gate PASSes and findings clear, **or** the budget is exhausted → report residual gaps honestly (never fake a pass).
+   - **Repair never edits a QA-written viewpoint (mode 1).** A finding whose fix is an edit to `test-viewpoint.md` becomes a row in `viewpoint-review.md` for the QA when it cites one of the file's VP ids (the checklist's audit rule; anything else goes in the hand-back); in a mode-2 draft, fix the draft.
 
 5.6. **Record (reuse + observability).** Build the manifest and report usage:
    - `sungen manifest --screen <name>` — fingerprints for next-run change detection. On a **re-run**, start the whole command by `sungen manifest --screen <name> --diff` and only regenerate scenarios whose spec section changed (keep/regenerate/retire).
@@ -297,7 +301,7 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
    > **No parallel fan-out here.** Copilot has no sub-agents, so generation is sequential (the Claude Code variant fans out one `sungen-generator` per viewpoint group and merges). Same output, no speedup.
 5.3. **Standardize field test-data — Data Factory (when the unit has input fields).** For each input field, author the field-map `qa/data-factory/<name>.fields.yaml` (field → catalog `type` + real `constraints` + `errorMap`), then run `sungen data lint --screen ${input:name}` and `sungen data gen --screen ${input:name}` per the **`sungen-data-factory`** skill. `data gen` **MERGES** into `test-data.yaml` (replaces only its field keys, preserves the rest), so it is safe here. Weave the standardized boundary/invalid sets into `@cases` with `CHK-*` trace. Then `… data validate` (values correct) + `… data crosscheck` (testcase↔data agree); for a stateful precondition, `… data state --scaffold <name>` to auto-draft → fill entities + confirm with QA → `… data state`, weave the `@manual:data-setup` `Background` (works spec+viewpoint only). **Same standard as `/sungen:create-data-test`, applied inline — do NOT run that command separately afterwards.** No input fields (navigation/list) → skip.
 5.4. **Depth self-check (deterministic — BEFORE the audit).** Run `sungen depth-lint --screen ${input:name}`. It splits every shallow business-critical scenario into **DEEPEN IN PLACE** (add a real value assertion — the printed `template` is a theme-keyed hint, apply judgment to the actual claim; never fake one onto a visibility/behavior scenario) and **CROSS-SCREEN** (route to a flow / tag `@manual:Mx` + reason — removes it from the depth denominator honestly). Act on both, re-run until `deepen` is empty (or only honest over-counts remain), THEN gate. Lifts first-pass `businessDepth` mechanically instead of via 2–3 repair rounds.
-5.5. **Quality gate & repair (harness — always run).** Per `sungen-harness-audit`: run `sungen audit --screen ${input:name}` (structural), THEN do an **independent semantic review inline** using the `sungen-reviewer` criteria (does each scenario's steps PROVE its title/viewpoint? observable Thens? business-critical assertion depth?). Merge both sets of issues; if gate FAILs / findings exist, repair (budget 3) and re-audit — GATE missing theme → generate it (cross-screen → **automate it in the flow** via `/sungen:add-flow`, NOT a full `@manual` screen duplicate — `sungen audit` flags an automatable `@manual` as `MANUAL-AUTOMATABLE`; reserve `@manual:Mx` for true judgment/missing-capability); DEPTH → add data assertions; BALANCE → add business-core first; TRACE → align VP ids. Never fake a pass.
+5.5. **Quality gate & repair (harness — always run).** Per `sungen-harness-audit`: run `sungen audit --screen ${input:name}` (structural), THEN do an **independent semantic review inline** using the `sungen-reviewer` criteria (does each scenario's steps PROVE its title/viewpoint? observable Thens? business-critical assertion depth?). Merge both sets of issues; if gate FAILs / findings exist, repair (budget 3) and re-audit — GATE missing theme → generate it (cross-screen → **automate it in the flow** via `/sungen:add-flow`, NOT a full `@manual` screen duplicate — `sungen audit` flags an automatable `@manual` as `MANUAL-AUTOMATABLE`; reserve `@manual:Mx` for true judgment/missing-capability); DEPTH → add data assertions; BALANCE → add business-core first; TRACE → align VP ids. Never fake a pass. Repair never edits a QA-written viewpoint (mode 1): a finding whose fix is an edit to `test-viewpoint.md` and cites one of its VP ids becomes a row in `viewpoint-review.md`; in a mode-2 draft, fix the draft.
 5.6. **Record.** `sungen manifest --screen ${input:name}`. Ledger **each phase** (not just repair) — pick one `runId` at the start and pass it so `trace`/`ledger report` show THIS run, not a mix: `sungen ledger record --screen ${input:name} --run <runId> --step <discovery|viewpoint|gherkin|audit|repair:N> --ms <elapsed>`. On re-run, start with `sungen manifest --screen ${input:name} --diff` and only regenerate changed sections.
 6. **Converge — show the trace.** Run `sungen trace --screen ${input:name}` and present: process map (phases + repair rounds), bottlenecks, **HUMAN-LOOP FOCUS** (@manual to verify), audit score + gate + residual gaps. Then offer next steps based on which tier was just generated:
 {{/cap}}
@@ -363,9 +367,13 @@ Do not stop after writing the files. Close every run with, in this order:
 1. **The traceability check below** — an untagged requirement becomes an uncovered gap at delivery.
 2. **The harness result in one line** — score, gate verdict, and the axis the `SCORE-CAPPED` finding
    names (that finding is the single answer to "how do I raise the score").
-3. **`AskUserQuestion` with the next actions** — never end with prose alone. Offer
+3. **The viewpoint review in one line** — `Viewpoint review: N điểm cần QA xem` (N = the `[ ]` rows
+   of `requirements/viewpoint-review.md`).
+4. **`AskUserQuestion` with the next actions** — never end with prose alone. Offer
    `/sungen:run-test <name>` (recommended once the tiers are written), re-running `create-test` to
-   extend, and "Done for now". A run that ends without this leaves the operator guessing.
+   extend, "Mở viewpoint-review.md" when N > 0, and "Done for now". After a mode-2 draft also list
+   the decision `sungen audit --screen <name> --accept-viewpoint` — for the QA to run once the draft
+   is reviewed; you never run it yourself. A run that ends without this leaves the operator guessing.
 
 ### Requirement traceability
 

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-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.

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

@@ -629,8 +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. **`[mobile]`** Its failure does NOT escalate the next scenario's `@reset:` tier: a red that was designed in is not evidence of leftover state |
+| `@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) |
@@ -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-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.