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

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

@@ -154,7 +154,9 @@ For append: read highest `VP-<CAT>-<NNN>`, continue from next number. Never modi
 Auto-detected by `create-test` before invoking this skill:
 - `spec.md` — primary, always read if present
 - `spec_figma.md` — Figma supplement (PAT flow already done — just read the file)
-- `ui/*.png` — visual context
+- `ui/*.{png,jpg,jpeg,webp,gif}` — design images. **Every one is read**, and turned into the Design Inventory below — not just "visual context".
+- `ui/figma-meta.md` — Figma MCP capture (`sungen-capture` mode figma-mcp): `## Components` and `## Text Content` feed the Design Inventory; `## Text Content` also supplies exact labels for `test-data.yaml`.
+- `ui-inventory.md` — the Design Inventory (written by create-test, see § Design Inventory). When it already exists, keep its ids and append new items; never renumber.
 - `test-viewpoint.md` — test conditions checklist; scan entirely regardless of format.
   Format varies across projects: hierarchical table (Level 1–4 columns), flat checklist,
   prose, or mixed. Regardless of format:
@@ -181,6 +183,40 @@ This means: do not test other screens' UI layout or navigation. It does NOT mean
 
 ---
 
+## Design Inventory (UI items)
+
+**When:** the unit holds any design source — images in `requirements/ui/`, `ui/figma-meta.md`, or `spec_figma.md`. Without one, skip this section.
+
+**Why:** a design read "for visual context" leaves no trace. An item that exists only on the design (a column `spec.md` never names) or contradicts the spec is then missed by the author AND the reviewer, and "deliberately deferred" looks exactly like "never seen". `sungen audit` checks this file (`UI-INVENTORY-MISSING`, `UI-INVENTORY-INCOMPLETE`, `UI-ITEM-UNCOVERED`).
+
+**Reading order:** `spec.md` (authoritative) → `spec_figma.md` → `ui/figma-meta.md` (`## Components`, `## Text Content`) → **every** image in `ui/`. Many images: group them (primary screen vs states/variants) but read them all — an unread state screen is an un-inventoried one.
+
+**Write `requirements/ui-inventory.md`** — one row per component, table column, button/link, field, state (empty/error/loading/disabled), and design annotation:
+
+```markdown
+# UI Inventory — <screen>
+images read: 3/3 · figma-meta.md: read · spec_figma.md: absent
+
+| ID | Item | Kind | Source | Seen in |
+|---|---|---|---|---|
+| UI-001 | Job List table | table | spec+design | ui/list.png |
+| UI-002 | Contract plan | column | spec+design | ui/list.png |
+| UI-014 | Salary range | column | design-only | ui/list.png |
+| UI-015 | Status badge "Closed" | column | conflict — spec says "Expired" | ui/list.png |
+```
+
+- **Source:** `spec+design` (both name it) · `design-only` (only the design shows it) · `conflict` (they disagree — say how in the cell). `spec.md` stays authoritative; a conflict is reported, never silently resolved in either direction.
+- **IDs** `UI-NNN` are append-only, like scenario ids: re-runs keep existing rows and continue numbering.
+- `images read: N/N` counts the images you actually opened against the images in the folder.
+
+**Account for every `design-only` / `conflict` item in the `.feature`** — either:
+- **cover it**: tag the scenario that proves it `@ui:UI-014`, or
+- **defer it with a reason** in a feature comment: `# UI-DEFERRED: UI-002..013 — per-column checks are owned by job-detail`. A deferral without a reason defers nothing.
+
+`spec+design` items are covered through the spec (`@spec:`), and citing their ids is optional.
+
+---
+
 ## Generation Workflow
 
 ### Step 1 — Orient: patterns + risk
@@ -219,6 +255,10 @@ Viewpoint items:     [TV-01 – <exact wording from test-viewpoint row 1>]
                      [TV-02 – <exact wording from test-viewpoint row 2>]
                      → one entry per row/bullet in test-viewpoint.md, regardless of format
                      → leave empty if no test-viewpoint.md present
+UI items:            [UI-014 – Salary range column (design-only) → covered by VP-TAB-012]
+                     [UI-002..013 – per-column checks → deferred: owned by job-detail]
+                     → one entry per Design Inventory row: covered / deferred-with-reason / uncovered
+                     → leave empty if the unit has no design source
 Spec gaps:           [G1 – behavior undocumented → verify with dev]
 ```
 
@@ -345,7 +385,7 @@ Security:         [S1 – admin only]
    - **`--accept-viewpoint` is the QA's command, not yours.** `sungen next` shows it as a `⚖ decide`
      step. Present the declared-id diff and stop; a yardstick accepted by the process it measures
      reads 100% by construction.
-   - **Match the scenarios to the file — never the file to the scenarios.** A filled `test-viewpoint.md` is an input; do not rewrite its declarations to fit what you generated. That is not compliance, it is moving the yardstick: `traceability` + `atomicLedger` then read 100% by construction and a dropped viewpoint stops being missing from anything. Disagree with the taxonomy → propose the diff and ask. `sungen audit` reports `VIEWPOINT-BASELINE-CHANGED` and excludes both axes until a human accepts the change (`sungen audit --screen <name> --accept-viewpoint`).
+   - **Match the scenarios to the file — never the file to the scenarios.** A filled `test-viewpoint.md` is an input; do not rewrite its declarations to fit what you generated. That is not compliance, it is moving the yardstick: `traceability` + `atomicLedger` then read 100% by construction and a dropped viewpoint stops being missing from anything. Disagree with the taxonomy → report the diff (ids added / removed and why) in `requirements/viewpoint-review.md`; the QA decides — no mid-run question. `sungen audit` reports `VIEWPOINT-BASELINE-CHANGED` and excludes both axes until a human accepts the change (`sungen audit --screen <name> --accept-viewpoint`).
 2. **Spec-coverage triggers** (`TRIGGER-UNCOVERED`, gate-FAIL) — the Validation-Rules table lists a **trigger** per constraint (e.g. `blur, submit`). Generate one scenario **per (constraint × trigger)** — a `format` rule validating *on blur AND on submit* needs BOTH a blur scenario (`press Tab`) and a submit scenario (`click [Submit]` / `press Enter`). Never collapse the trigger × input matrix to one representative case.
 3. **Claim-Proof** (`CLAIM-UNPROVEN`) — a title claiming `all`/`only`/`every`/`single`/`correct`/`same`/`changes`/`hidden`/`cleared`/`restored`/`independent`/`sanitized`/`announces` MUST have the matching assertion (`see all …`, count, `remember`+compare, `is hidden`, return-and-assert-empty, etc.). If the title promises it, the steps must prove it.
    - **Negative / absence claims** (`does not` / `no` / `never` / `prevents` / `không` / `chưa` — any language; `no-side-effect/no-duplicate`, `negative-claim/absence`): the `Then` must **differ** between the claim holding and not holding. A terminal `see [X] page` that looks identical whether or not the bad thing happened proves nothing. For a side-effect that should NOT repeat (re-submit on back, re-charge, duplicate order, resend OTP), assert the **count is unchanged** (`User see [Records] table with {{one}}` / `row with {{count}}`); if it's not UI-observable, mark `@manual` with a request-count oracle (shape below). This is general — it covers any side-effect, not a fixed verb list.

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

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

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

@@ -15,6 +15,24 @@ This skill is a **router**. The detailed checklists live in 6 group files — lo
 
 > All checklist items are written in English. Render scenario names, step text, and test IDs in English.
 
+## Authoring (mode 2) — drafting `test-viewpoint.md`
+
+Draft `requirements/test-viewpoint.md` only when the file is missing, is an untouched scaffold
+(headings, `<…>` placeholders, empty tables), or has one or more VP rows and every one lacks a
+`Kỳ vọng` — a file with no VP ids that is not the scaffold is QA-written (mode 1). Draft it from
+`viewpoint-template.md` in this folder (the QA's sections, in Vietnamese): the file's first line is
+`drafted-by: ai`; every VP row has a non-empty `Kỳ vọng`; whatever the spec leaves open becomes a
+closed question in mục 5, never an invented expectation. Fill sections 1 and 3 and the Coverage
+table from the patterns and Shared Checks below. A viewpoint without `drafted-by: ai` is QA-owned:
+read it, never edit it.
+
+## Review (both modes) — `review-checklist.md`
+
+create-test reviews every viewpoint with `review-checklist.md` in this folder, fed by
+`sungen viewpoint scan --json`, and writes `requirements/viewpoint-review.md`. On a QA-owned file
+that review file is the only output, limited to the checks its `Mode 1` column allows; on your own
+draft, run every check and fix the draft first.
+
 ## Routing table
 
 | UI element on the screen | Pattern | Read file |

package/src/orchestrator/templates/ai-src/skills/sungen-viewpoint/review-checklist.md

@@ -0,0 +1,63 @@
+# Viewpoint review checklist
+
+create-test runs this review of `requirements/test-viewpoint.md` inline, in both modes, and asks
+no question. Inputs: the viewpoint; the scan JSON (`sungen viewpoint scan --screen <name> --json`,
+a flow takes `--flow <name>`); `spec.md`, `ui-inventory.md` and the message table when present.
+Output: `requirements/viewpoint-review.md` (format below).
+
+## Rules
+- **Mode 1 — QA file (no `drafted-by: ai`): read only.** Never edit `test-viewpoint.md`. Every gap
+  goes into the review file; nothing is filled in. Look for what is **missing or contradicts the
+  spec**, not for how the QA writes: run only the checks the `Mode 1` column allows, as narrowed
+  there. A value the spec does not mention is not "invented". Wording the QA checks by eye ("Hiển thị đúng", "Khớp design"), their question style and
+  their environment marks are the QA's convention, never a finding.
+- **Mode 2 — `drafted-by: ai`: review your own draft.** Run the checks, fix the draft, run them
+  again — checks 4 and 9 field by field, before the review is written. The review file keeps only
+  what needs a QA decision: questions, inferred expectations, scope calls.
+- **Cite or drop.** Every finding names at least one VP id from the scan's `vpRows`, or an item ref
+  (`item N`, a spec id). A gap with no VP yet cites the item or spec line it comes from. A finding
+  you cannot anchor is not written.
+- **Distinct ids.** The scan lists a row per table occurrence: an id repeated in the questions table
+  (mục 5) is a reference, not a second VP. Count and cite each id once.
+- **No VP ids** (scan `note`: file has no VP ids): cite the file's own row labels (`DT-2 case 3`, a
+  field name) with the line number, plus item refs.
+- **Meaning, not format.** Headings, column order, wording style and language are never findings.
+- The scan's `withoutScenario` is generation work (a scenario per VP id), not a review finding.
+- **Audit findings** (create-test may route one here, check `audit`) enter only when they cite a VP id
+  from the scan's `vpRows` and the fix is an edit the QA can make in this file. A finding about
+  sungen itself — the page type, an id it read in a message code or a section-8 table — stays in the
+  hand-back, never in the review.
+
+## Checks
+One check, one fix hint. **Output order: 2, 9, 3, 6, 1, 4, 5, 7, 8** — highest impact first.
+
+| # | Check | Mode 1 | Read | Suggestion to write |
+|---|-------|--------|------|---------------------|
+| 1 | Each VP row says what to test and what to expect: `Kỳ vọng` is not empty and not vague ("OK", "đúng", "hiển thị đúng", "như spec"). | empty `Kỳ vọng` only | scan `rowsWithoutExpected`, the rows | Name the observable: message code, target screen, control state, value. |
+| 2 | Every expectation is traceable to the spec, the UI, the message table, a Design Decision (mục 6) or a Shared Check of this skill. One found in none of them is invented, unless mục 5 holds its question (`Nguồn: Suy luận → Q-0x`). | only an expectation that contradicts what the spec states; a value the spec does not mention (a URL, a screen id, a rule of thumb) is the QA's knowledge, not a finding | spec, UI, message table, mục 6 | Cite the source, or turn the expectation into a closed question in mục 5. |
+| 3 | A rule the spec applies to several fields names every field (`Ô` column, or one row per field). | ✓ | spec rules | Name the missing fields. |
+| 4 | Each accepted-input class in the spec (whitelist, value list, allowed characters, conversion such as trim, case, full→half width) has a positive VP — also a whitelist or list the spec names but does not reproduce. | ✓ | spec rules | Add an "accepted, no error" VP for the class, citing the list by name; not a question in mục 5. |
+| 5 | A VP that needs a real device, account, external service or elapsed time is marked `# MANUAL/ENV`. | — | scan `manualRows`, the rows | Mark the row or its group heading. |
+| 6 | Each entry of the scan's `uncitedItems`: deliberately out of scope (mục 6 or the scope note says so), or a gap? | ✓ | scan `uncitedItems`, mục 6, mục 7 | Add a VP citing `item N`, or a Design Decision saying why it is out. |
+| 7 | Questions are closed (yes/no, or pick one of the listed options) and carry `Major` / `Minor`. | — | mục 5 | Rewrite as a closed question; add the level. |
+| 8 | An edge case (mục 4) or decision (mục 6) states testable behaviour that no VP id carries — alone or together: an edge case split across several rows is carried. | ✓ | mục 4, mục 6 | Add a VP row. If a row already covers it, name that id in this finding — not in mục 4, where an id counts as a second declaration (`VIEWPOINT-ID-REUSED`). |
+| 9 | A row's `Kỳ vọng` is only a question pointer (`→ Q-0x`) although the spec states the expected result for that condition. | ✓ | spec, mục 5 | Write the spec's expectation in the row; keep the question for the part the spec leaves open. |
+
+## Output — `requirements/viewpoint-review.md`
+Overwrite it on every run, never append. Write Problem and Suggestion in the viewpoint's language;
+one row per finding, or one row listing every id that shares the same fix.
+
+```markdown
+# Viewpoint review — <unit>
+> Date: <YYYY-MM-DD> · test-viewpoint.md sha256: <hash> · Mode: <1 — QA file, review only | 2 — AI draft>
+> QA: tick `[x]` once handled, or delete the row. `sungen audit` reports the rows still open.
+
+| # | VP / item | Check | Problem | Suggestion | [ ] |
+|---|-----------|-------|---------|------------|-----|
+| 1 | VP-…-NNN · item N | 2 | <what is wrong, in one sentence> | <the fix> | [ ] |
+```
+
+- `sha256` of `test-viewpoint.md` as reviewed (`shasum -a 256` / `sha256sum`); mode 2: after your fixes.
+- At most 20 rows, in check order. Past 20, one line under the table: `+N more (checks …)`.
+- Nothing to report: keep the header, write `No open points.` instead of the table.
+- The hand-back counts the rows: `Viewpoint review: N điểm cần QA xem`.

package/src/orchestrator/templates/ai-src/skills/sungen-viewpoint/viewpoint-template.md

@@ -0,0 +1,158 @@
+# Test Viewpoint — <MÃ MÀN> <Tên màn>
+<!--
+Template Test Viewpoint (skill sungen-viewpoint). Dòng mẫu và hướng dẫn nằm trong comment, nên khung chưa điền khai báo 0 viewpoint. Điền: chép dòng mẫu ra ngoài comment rồi sửa; nhóm không áp dụng thì xoá, ghi lý do ở bảng Coverage (mục 7).
+Nháp do AI soạn (unit chưa có viewpoint QA): dòng ĐẦU TIÊN của file là `drafted-by: ai`, đặt ngoài comment. Nháp không bao giờ được lấy làm chuẩn đo; QA duyệt xong thì accept (`sungen audit … --accept-viewpoint`), accept xoá dòng đó và từ đó file thuộc QA. `sungen add` / `sungen add-flow` không ghi dòng này.
+-->
+> **Tài liệu đầu vào:** <đặc tả / design / bảng message của màn>
+> **Loại tài liệu:** bảng quan điểm kiểm thử — KHÔNG phải test case chi tiết. Mỗi quan điểm gắn mã `VP-…` để truy vết sang test case.
+> **Nguyên tắc:** mỗi dòng trả lời câu hỏi "test CÁI GÌ" và "kỳ vọng ra sao"; điểm spec chưa rõ thì ghi ở mục 5, **không tự bịa kỳ vọng** — spec đã nói thì ghi kỳ vọng theo spec, chỉ phần spec bỏ ngỏ mới thành câu hỏi. Quan điểm cần môi trường/thiết bị/thời gian thật: đánh dấu `# MANUAL/ENV`.
+
+## 0. Metadata
+| Trường | Giá trị |
+|--------|---------|
+| Màn hình | <mã + tên gốc / tên tiếng Việt, route> |
+| Vị trí trong flow | <vào từ đâu, đi tiếp tới đâu> |
+| Primary UI pattern | <form / list / detail / create / login / search…> |
+| Nền tảng | <trình duyệt / thiết bị / độ phân giải cần test> |
+| Đặc thù cần nhấn | <rủi ro hoặc đặc điểm quan trọng nhất của màn> |
+| Tiền điều kiện | <đăng nhập? role? dữ liệu cần chuẩn bị?> |
+| Ngày tạo viewpoint | <YYYY-MM-DD> |
+
+## 1. UI Patterns Identified
+*(Nhận diện màn dùng pattern nào → quyết định nhóm viewpoint nào cần áp dụng.)*
+
+| # | Pattern | Áp dụng? | Ghi chú |
+|---|---------|----------|---------|
+<!-- Áp dụng? = ✅ / ❌ (❌ thì ghi lý do). Một dòng cho mỗi pattern, số + tên theo catalog sungen-viewpoint (web 1–17, mobile thêm 18–32):
+| 1 | Form & Inputs | ✅ | <các ô nhập, validate lúc nào> |
+| 12 | Modal / Dialog | ❌ | <lý do không áp dụng> |
+-->
+
+## 2. Priority Viewpoints
+### Viewpoint grouping — ưu tiên theo nhóm VP
+| Nhóm VP | Priority | Lý do |
+|---------|----------|-------|
+<!-- Priority = High / Med / Low; một dòng cho mỗi nhóm có ở mục 3: VP-VAL (Validation) · VP-LOGIC (Nghiệp vụ) · VP-UI-BTN (Nút & trạng thái) · VP-NAV (Điều hướng) · VP-AUTH (Quyền / tiền điều kiện) · VP-SEC (Bảo mật) · VP-UI (Hiển thị). Ví dụ:
+| VP-VAL (Validation) | High | <lý do> | -->
+
+## 3. Viewpoints chi tiết
+*(Pri = priority. Nguồn = số item trong spec/UI. Mỗi dòng = "test cái gì".)*
+<!--
+- Mọi bảng mục 3 dùng cùng cột. Mã VP-<NHÓM>[-<FIELD>]-NNN ở cột đầu, mỗi mã khai báo một lần. Flow: mã FL-…, thêm nhóm liên màn (dữ liệu / quyền giữ qua các màn).
+- Kỳ vọng = thứ nhìn thấy được: mã message, màn đích, trạng thái control. Kỳ vọng trống thì dòng KHÔNG tính là viewpoint.
+- Ô: để trống khi cả nhóm là một ô. Một luật áp cho nhiều ô: liệt kê đủ từng ô, không lấy 1 ô làm đại diện.
+- Pri = High / Med / Low. Nguồn = `item N` · `SPEC <id>` · `Suy luận → Q-0x` (suy luận bắt buộc có câu hỏi ở mục 5). Cần thiết bị / tài khoản / thời gian thật: `# MANUAL/ENV` trong ô Quan điểm hoặc tiêu đề nhóm.
+-->
+
+### A. VP-UI — Hiển thị tĩnh & trạng thái ban đầu
+| VP | Quan điểm kiểm thử | Ô | Kỳ vọng | Pri | Nguồn |
+|----|--------------------|---|---------|-----|-------|
+<!-- | VP-UI-001 | Trạng thái lúc mở màn | | <nhãn, placeholder, giá trị mặc định, nút chính disabled / enabled> | | item N | -->
+
+### B. VP-VAL-<FIELD> — <Tên field> (item x)
+| VP | Quan điểm kiểm thử | Ô | Kỳ vọng | Pri | Nguồn |
+|----|--------------------|---|---------|-----|-------|
+<!--
+| VP-VAL-…-001 | Rỗng → blur / submit | | → <mã message> | High | |
+| VP-VAL-…-002 | Chỉ khoảng trắng / khoảng trắng đầu-cuối | | | | |
+| VP-VAL-…-003 | Biên độ dài: min−1 / min / max / max+1 | | | High | |
+| VP-VAL-…-004 | Sai định dạng / ký tự không cho phép | | | | |
+| VP-VAL-…-008 | Mọi ký tự / giá trị spec cho phép (whitelist, danh sách, chuyển đổi) được chấp nhận | | Không lỗi, giá trị giữ nguyên / đã chuyển đổi | High | |
+| VP-VAL-…-005 | Full-width / half-width | | | | |
+| VP-VAL-…-006 | Paste / autofill | | | | |
+| VP-VAL-…-007 | Đang lỗi → sửa đúng → message biến mất | | | | |
+-->
+*(Lặp nhóm B cho từng field.)*
+
+### C. VP-LOGIC — Nghiệp vụ chính / submit
+| VP | Quan điểm kiểm thử | Ô | Kỳ vọng | Pri | Nguồn |
+|----|--------------------|---|---------|-----|-------|
+<!--
+| VP-LOGIC-001 | Happy path | | | High | |
+| VP-LOGIC-002 | Server trả lỗi nghiệp vụ | | | | |
+| VP-LOGIC-003 | Lỗi mạng / server `# MANUAL/ENV` | | | | |
+-->
+
+### D. VP-UI-BTN — Nút & trạng thái
+| VP | Quan điểm kiểm thử | Ô | Kỳ vọng | Pri | Nguồn |
+|----|--------------------|---|---------|-----|-------|
+<!--
+| VP-UI-BTN-001 | Chưa đủ điều kiện → disabled | | | High | |
+| VP-UI-BTN-002 | Đủ điều kiện → enabled | | | High | |
+| VP-UI-BTN-003 | Loading sau khi bấm | | | | |
+| VP-UI-BTN-004 | Bấm kép → chỉ 1 request `# MANUAL/ENV` | | | High | |
+-->
+
+### E. VP-NAV — Điều hướng
+| VP | Quan điểm kiểm thử | Ô | Kỳ vọng | Pri | Nguồn |
+|----|--------------------|---|---------|-----|-------|
+<!-- | VP-NAV-001 | | | → <màn đích>, cùng tab / tab mới | | | -->
+
+### F. VP-AUTH — Quyền / tiền điều kiện truy cập (nếu có)
+### G. VP-SEC — Bảo mật (nếu có)
+### H. VP-UI-PLTF — Nền tảng / thiết bị (nếu có)
+
+### DT-1 — Bảng quyết định: <luật phụ thuộc ≥ 2 điều kiện> (nếu có)
+<!-- Mỗi Case = 1 dòng có mã VP. Cột giữa là điều kiện (✓ / ✗ / giá trị), rồi Hành động và Kỳ vọng. Ví dụ:
+| VP | <Điều kiện 1> | <Điều kiện 2> | Hành động | Kỳ vọng | Pri | Nguồn |
+|----|---------------|---------------|-----------|---------|-----|-------|
+| VP-LOGIC-010 | ✓ | ✗ | Tick nốt ô con còn lại | "Chọn tất cả" tự → ✓ | High | item N |
+-->
+
+## 4. Edge Cases
+*(Ca dễ bị sót khi viết test case.)*
+<!--
+- <biên nối tiếp: max rồi max+1>
+- <bấm nút đúng lúc field vừa thành không hợp lệ>
+- <mất mạng trước khi bấm vs trong lúc chờ phản hồi>
+- <phiên hết hạn giữa chừng>
+-->
+
+## 5. Open questions / Điểm CHƯA CHỐT
+*(Spec chưa nêu → KHÔNG tự bịa kỳ vọng; ghi thành câu hỏi đóng để hỏi BA/dev.)*
+
+| Mã | Mức | VP liên quan | Câu hỏi đóng cần BA/dev xác nhận |
+|-----|-----|--------------|----------------------------------|
+<!-- Mức: Major = test case của VP liên quan chờ câu trả lời; Minor = không chặn. -->
+<!-- | Q-01 | Major / Minor | VP-… | <câu hỏi cụ thể, trả lời được bằng có/không hoặc chọn 1 phương án> | -->
+
+## Known issues — lỗi đã biết (KHÔNG phải câu hỏi)
+*(Lỗi đã xác nhận, còn tồn tại: scenario của VP đó gắn `@known-defect:DEF-NNN` (bản ghi ở `qa/defects/`), đỏ có chủ đích. Spec chưa rõ thì ghi ở mục 5.)*
+
+| KI | VP liên quan | Lỗi | Hiện tượng |
+|----|--------------|-----|------------|
+<!-- | KI-1 | VP-… | DEF-001 | <thấy gì, khác Kỳ vọng ở đâu> | -->
+
+## 6. Design Decisions
+*(Quyết định có chủ đích của spec — KHÔNG báo "thiếu" hoặc "bug" cho các mục này.)*
+<!--
+- D1: <vd: nút disabled tới khi đủ điều kiện> (SPEC <id>)
+- D2: <vd: lỗi đăng nhập không nói rõ sai email hay sai mật khẩu>
+-->
+
+## 7. Traceability & tự nhận giới hạn
+- **Tổng: N viewpoint** — liệt kê số lượng theo từng nhóm. Mọi item trong spec có ít nhất 1 VP trỏ về.
+- ⚠ **Giới hạn:** bảng chứng minh "mọi VP đã liệt kê có kỳ vọng" — KHÔNG chứng minh "đã liệt kê ĐỦ VP". Đối chiếu lại với đặc tả gốc + bảng message trước khi viết test case.
+- **Scope note:** <VP nào cần môi trường/thiết bị thật, VP nào test ở tầng API/E2E>.
+- Còn **K điểm chưa chốt** (Q-…) — test case cho VP liên quan chờ câu trả lời.
+
+### Coverage — độ phủ tự kiểm
+<!-- Mỗi nhóm một dòng. Trạng thái: `có VP` (✓) · `để sau → <đích>` (# MANUAL/ENV, unit/flow khác, Q-0x) · `Không áp dụng` (➖) kèm lý do.
+Thêm dòng nền tảng theo catalog sungen-viewpoint khi màn có: web — XSS / SQL injection / URL (Shared Checks); mobile — Bàn phím ảo (30) · Vòng đời app & xoay màn (32) · Offline (27) · Quyền hệ thống (22) · Deep-link (26). -->
+| Nhóm kiểm tra | Trạng thái | VP / lý do |
+|---------------|------------|------------|
+| Happy path | | |
+| Negative | | |
+| Biên | | |
+| Charset | | |
+| Trạng thái nút | | |
+| Điều hướng | | |
+| Quyền | | |
+| Bảo mật | | |
+| Nền tảng | | |
+| Trạng thái tải / rỗng / lỗi | | |
+
+## 8. References · Phụ lục — Mã thông báo dùng trong tài liệu
+| Mã | Nghĩa | Kiểu hiển thị |
+|----|-------|---------------|
+<!-- | M01 | <nội dung message> | <dưới ô nhập / trên form / toast / mail> | -->

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

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

package/src/orchestrator/templates/specs-locale-fixture.ts

@@ -42,18 +42,30 @@ interface LocaleInjection {
 
 let cached: LocaleInjection | null | undefined;
 
+/**
+ * Absent config → null, and locale injection is simply off (the documented no-op).
+ *
+ * A config that EXISTS but does not parse is a different thing and must not read the same way: the
+ * header above tells you to hand-edit this file, and a trailing comma would otherwise turn a
+ * `SUNGEN_ENV=ja` run into a base-locale run that asserts base-locale strings — green, and wrong.
+ * We warn rather than throw, because the injection is genuinely optional and failing every test on
+ * it would be a larger change than the fault warrants; the line names the file and the consequence.
+ */
 function loadLocaleConfig(): LocaleInjection | null {
   if (cached !== undefined) return cached;
+  const cfgPath = path.join(__dirname, 'locale-config.json');
+  if (!fs.existsSync(cfgPath)) {
+    cached = null;
+    return null;
+  }
   try {
-    const cfgPath = path.join(__dirname, 'locale-config.json');
-    if (!fs.existsSync(cfgPath)) {
-      cached = null;
-      return null;
-    }
-    const parsed = JSON.parse(fs.readFileSync(cfgPath, 'utf-8')) as LocaleInjection;
-    cached = parsed;
-    return parsed;
-  } catch {
+    cached = JSON.parse(fs.readFileSync(cfgPath, 'utf-8')) as LocaleInjection;
+    return cached;
+  } catch (e) {
+    console.error(
+      `⚠️  ${cfgPath}: unreadable (${e instanceof Error ? e.message.split('\n')[0] : String(e)}) — ` +
+      `locale state is NOT injected, so this SUNGEN_ENV run behaves as the base locale.`,
+    );
     cached = null;
     return null;
   }

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

@@ -46,6 +46,16 @@ export interface UrlExpectation {
   declared?: string;
   /** The test-data key behind `declared`, so a failure can name what an author must go fix. */
   dataRef?: string;
+  /**
+   * The page selector declared `query: any` — the query string is not part of this page's identity,
+   * so SILENCE from the step stops meaning "there must be no query" (#748).
+   *
+   * Emitted only for a page whose entry says so. The default stays strict: a bare page means a bare
+   * page, which is the #464 assertion and the reason a filter regression cannot read as green.
+   * It is the no-`dataRef` branch alone that this relaxes — a step that declares `with {{v}}` still
+   * asserts every param it names, on this page as on any other.
+   */
+  ignoreQuery?: boolean;
 }
 
 /**
@@ -113,8 +123,14 @@ function locationMatches(pathname: RegExp, hostname: RegExp | undefined, u: URL)
  *                      tracking/UTM param the test never cared about cannot turn it red.
  *                      A declared fragment is asserted too; a declared value carrying no query
  *                      at all constrains the path only (the compiler warns: SG-W014).
+ *
+ * `query: any` on the page's selector entry overrides the FIRST rule only (#748): silence then
+ * means "the query is not mine to judge" instead of "there must be none". It is the escape hatch
+ * for a page whose query is generated at run time — `/admins/detail?id=<the row just clicked>` —
+ * which the strict rule makes unassertable and `with {{v}}` cannot express, since that asserts a
+ * literal. The second rule is untouched: declare params and they are still all checked.
  */
-export function urlMatches({ pathname, hostname, declared, dataRef }: UrlExpectation): (u: URL) => boolean {
+export function urlMatches({ pathname, hostname, declared, dataRef, ignoreQuery }: UrlExpectation): (u: URL) => boolean {
   return (u: URL): boolean => {
     if (!locationMatches(pathname, hostname, u)) return false;
 
@@ -123,7 +139,13 @@ export function urlMatches({ pathname, hostname, declared, dataRef }: UrlExpecta
     // undefined, and they mean opposite things: the first is a real assertion (a bare page must be
     // bare), the second is broken test-data. Only the generator knows which, and it says so by
     // emitting `dataRef` exactly when the step carried a `with {{v}}`.
-    if (!dataRef) return u.search === '';
+    // `query: any` on the page entry (#748): the query is not part of this page's identity, so
+    // silence from the step is not an assertion about it. Without this there is NO way to express
+    // "this path, whatever the query" — `with {{v}}` asserts a LITERAL value, and a detail page
+    // keyed by `?id=<the row just clicked>` has no literal to declare. Checked before the bare-page
+    // rule, never instead of the declared-value rule below: a step that names params still asserts
+    // them here exactly as anywhere else.
+    if (!dataRef) return ignoreQuery ? true : u.search === '';
 
     // Silence is the whole bug class this assertion exists to kill, so an unusable declared value
     // is an ERROR, not a quiet verdict. Returning false would read as "the app is wrong"; these
@@ -183,6 +205,26 @@ interface SettleOpts { settleMs?: number; networkIdleMs?: number }
  * 3000) bounds step 1. Both are runtime knobs, so a slow environment is a config change, not a
  * regenerate.
  */
+/**
+ * A millisecond budget from the environment. `Number()` alone turned `"1s"` / `"abc"` into NaN and
+ * `""` into 0 (`??` keeps an empty string): the hold loop then never ran, so a late redirect passed
+ * unseen, and a 0 / NaN networkidle timeout means "no timeout" to Playwright — the step waited out
+ * the whole test (#856). Unset or empty means the default; a malformed value falls back to it and
+ * says so, once per variable. `allowZero` for a knob where 0 is a real choice (no hold).
+ */
+const warnedEnv = new Set<string>();
+function msEnv(name: string, fallback: number, allowZero = false): number {
+  const raw = process.env[name]?.trim();
+  if (!raw) return fallback;
+  const value = Number(raw);
+  if (Number.isFinite(value) && (value > 0 || (allowZero && value === 0))) return value;
+  if (!warnedEnv.has(name)) {
+    warnedEnv.add(name);
+    console.warn(`[sungen] ${name}=${JSON.stringify(raw)} is not a ${allowZero ? 'non-negative' : 'positive'} number of milliseconds — using the default ${fallback}.`);
+  }
+  return fallback;
+}
+
 async function settleAndHold(
   page: SettleablePage,
   matches: (u: URL) => boolean,
@@ -190,8 +232,9 @@ async function settleAndHold(
   label: string,
   consequence: string,
 ): Promise<void> {
-  const settleMs = opts.settleMs ?? Number(process.env.SUNGEN_URL_SETTLE_MS ?? 1000);
-  const networkIdleMs = opts.networkIdleMs ?? Number(process.env.SUNGEN_URL_NETWORKIDLE_MS ?? 3000);
+  // 0 holds nothing (the operator's call); 0 for networkidle would mean "no timeout", so it is refused.
+  const settleMs = opts.settleMs ?? msEnv('SUNGEN_URL_SETTLE_MS', 1000, true);
+  const networkIdleMs = opts.networkIdleMs ?? msEnv('SUNGEN_URL_NETWORKIDLE_MS', 3000);
   const arrivedAt = page.url();
 
   await page.waitForLoadState('networkidle', { timeout: networkIdleMs }).catch(() => undefined);

package/src/orchestrator/templates/wdio.conf.ts

@@ -48,6 +48,14 @@ function evidenceSlug(s: string): string {
     .slice(0, 80) || 'unnamed';
 }
 
+/**
+ * True only in the launcher process. `@wdio/runner` re-parses this very config inside EVERY worker
+ * it spawns, so anything logged at module scope prints once per spec unless it is gated. WDIO's own
+ * "am I a worker" test is this env var (`@wdio/local-runner` sets it when spawning; `@wdio/utils`
+ * reads it) — reuse it rather than inventing a second signal.
+ */
+const IS_LAUNCHER = !process.env.WDIO_WORKER_ID;
+
 /**
  * Auto-select MOBILE specs and classify each by its target OS (dual-target routing).
  *
@@ -82,7 +90,12 @@ function classifyMobileSpecs(root: string): Array<{ file: string; platform: stri
     .filter((full) => {
       try {
         return fs.readFileSync(full, 'utf-8').includes('@wdio/globals');
-      } catch {
+      } catch (e) {
+        // A spec listed by readdir that cannot be read cannot be classified, so it is excluded.
+        // Excluding it SILENTLY is the fault: WDIO only fails the run when the spec list is
+        // EMPTY ("No specs found to run"), so dropping one spec out of ten leaves a green suite
+        // containing a test that never executed. Name it, and let the count below show the shortfall.
+        if (IS_LAUNCHER) console.warn(`[sungen] could not read ${full} — EXCLUDED from this run: ${(e as Error).message}`);
         return false;
       }
     })
@@ -98,6 +111,16 @@ const androidSpecs = specEntries.filter((e) => e.platform !== 'ios').map((e) =>
 const iosSpecs = specEntries.filter((e) => e.platform !== 'android').map((e) => e.file);
 const mobileSpecs = specEntries.map((e) => e.file); // union — top-level fallback
 
+// What DISCOVERY found — a mobile suite is only trustworthy if you can see how many specs it
+// resolved: WDIO fails loudly on an EMPTY list but says nothing when the list is merely short,
+// which is exactly what a dropped spec looks like.
+//
+// Two things this number is not. It is not an error on 0: WDIO already exits 1 there
+// ("No specs found to run"), and a `--shard` that legitimately receives none must still return 0.
+// And under `--shard` it is the PRE-SHARD total, because ConfigParser slices `specs` down to the
+// shard's portion only after this file has finished evaluating.
+if (IS_LAUNCHER) console.log(`[sungen] specs: ${specEntries.length} mobile spec(s) — android ${androidSpecs.length}, ios ${iosSpecs.length}`);
+
 // App under test — env overrides the init-configured defaults.
 const APP_PACKAGE = process.env.APP_PACKAGE || '__APP_PACKAGE__';
 const APP_ACTIVITY = process.env.APP_ACTIVITY || '__APP_ACTIVITY__';

package/src/orchestrator/trace-mode-install.ts

@@ -0,0 +1,94 @@
+/**
+ * Move an existing project's `use.trace` off the old default so local runs keep a trace.
+ *
+ * The old template paired `trace: 'on-first-retry'` with `retries: process.env.CI ? 2 : 0`: off CI
+ * there is no retry, so there is never a "first retry" and a QA fixing a test on their machine never
+ * got a trace. The template now records `on-first-retry` on CI and `retain-on-failure` locally.
+ *
+ * `playwright.config.ts` is written once at `sungen init` and never re-synced (see
+ * report-sanitize-reporter-install.ts, the same problem for the sanitize reporter), so `sungen update`
+ * calls this. It rewrites the trace line ONLY while it is still the old default — any other value is
+ * a choice the user made, and a wrong edit to a user's config is worse than a missing trace. The same
+ * goes for a `trace` inside `projects: [...]`: that is a per-project override, not the template default.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+/** The template's trace value: cheap on CI (retries exist there), a trace for every local failure. */
+export const TRACE_MODE_EXPRESSION = "process.env.CI ? 'on-first-retry' : 'retain-on-failure'";
+
+/**
+ *   'patched' — the old default was rewritten now
+ *   'present' — already the template expression (idempotent)
+ *   'custom'  — another value, no trace line, more than one old-default line, or one inside
+ *               `projects: [...]`; nothing written
+ *   'absent'  — no playwright.config.ts (a mobile-only project, or not a sungen project)
+ */
+export type TraceModeOutcome = 'patched' | 'present' | 'custom' | 'absent';
+
+const escapeRegExp = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+// Both are anchored to the start of a line, so a commented-out copy (`// trace: …`) never counts.
+// OLD_DEFAULT keeps the indentation in $1 and leaves the trailing comma, comment and EOL alone.
+const OLD_DEFAULT = /^([ \t]*trace:[ \t]*)(['"])on-first-retry\2/gm;
+const PRESENT = new RegExp(`^[ \\t]*trace:[ \\t]*${escapeRegExp(TRACE_MODE_EXPRESSION)}`, 'm');
+
+// The old template's one-line comment, only when it sits directly above the (patched) trace line.
+// A comment the user wrote is theirs and stays.
+const OLD_COMMENT = new RegExp(
+  `^([ \\t]*)/\\* Collect trace when retrying the failed test\\. See https://playwright\\.dev/docs/trace-viewer \\*/(\\r?\\n)(?=[ \\t]*trace:[ \\t]*${escapeRegExp(TRACE_MODE_EXPRESSION)})`,
+  'm',
+);
+const newComment = (indent: string, eol: string): string =>
+  `${indent}/* Trace for a failed test. CI: recorded on the first retry (CI retries). Local: no retries, so${eol}` +
+  `${indent}   'on-first-retry' would never record one — keep the trace of every failed test instead.${eol}` +
+  `${indent}   See https://playwright.dev/docs/trace-viewer */${eol}`;
+
+/**
+ * [start, end] offsets of each live `projects: [...]` array, matched by bracket depth. Brackets inside
+ * a `//` or `/* *\/` comment or a quoted string are skipped: one stray `]` in a note would otherwise
+ * close the span early and expose a per-project override to the patch.
+ */
+function projectsSpans(src: string): Array<[number, number]> {
+  const spans: Array<[number, number]> = [];
+  for (const m of src.matchAll(/^[ \t]*projects\s*:\s*\[/gm)) {
+    const open = m.index! + m[0].length - 1;
+    let depth = 0;
+    for (let i = open; i < src.length; i++) {
+      const ch = src[i];
+      if (ch === '/' && src[i + 1] === '/') { const nl = src.indexOf('\n', i); i = nl < 0 ? src.length : nl; continue; }
+      if (ch === '/' && src[i + 1] === '*') { const end = src.indexOf('*/', i + 2); i = end < 0 ? src.length : end + 1; continue; }
+      if (ch === "'" || ch === '"' || ch === '`') {
+        for (i++; i < src.length && src[i] !== ch; i++) if (src[i] === '\\') i++;
+        continue;
+      }
+      if (ch === '[') depth++;
+      else if (ch === ']' && --depth === 0) { spans.push([open, i]); break; }
+    }
+  }
+  return spans;
+}
+
+export function patchTraceMode(cwd: string, dryRun: boolean = false): TraceModeOutcome {
+  const configPath = path.join(cwd, 'playwright.config.ts');
+  if (!fs.existsSync(configPath)) return 'absent';
+  const src = fs.readFileSync(configPath, 'utf8');
+  if (PRESENT.test(src)) return 'present';
+  const hits = [...src.matchAll(OLD_DEFAULT)];
+  if (hits.length !== 1) return 'custom'; // none: the user's own value · several: ambiguous, don't guess
+  const at = hits[0].index!;
+  if (projectsSpans(src).some(([s, e]) => at > s && at < e)) return 'custom'; // a per-project override
+  if (!dryRun) {
+    const patched = src
+      .replace(OLD_DEFAULT, `$1${TRACE_MODE_EXPRESSION}`)
+      .replace(OLD_COMMENT, (_m, indent: string, eol: string) => newComment(indent, eol));
+    fs.writeFileSync(configPath, patched);
+  }
+  return 'patched';
+}
+
+/** `sungen update` step: patch the trace mode and say so when it changed. */
+export function installTraceMode(cwd: string, dryRun: boolean = false): void {
+  if (patchTraceMode(cwd, dryRun) !== 'patched') return;
+  console.log(`${dryRun ? '📋 would update' : '✓ updated'} playwright.config.ts: local runs now keep a trace for every failed test (trace: ${TRACE_MODE_EXPRESSION})`);
+}