@educa-corp/sdd-framework 0.9.3 → 0.9.4

package/core/skills/qc/qa-designer/shared/precision-rules.md

@@ -0,0 +1,198 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/shared/precision-rules.md
+upstream_sha: 1c2005b55bd94c3e8fa25dfa12a29c8b23f7c01e
+---
+# Precision Rules — Quy Tắc Độ Chính Xác
+
+---
+
+## 1. Cấm từ mơ hồ — Bắt buộc lượng hóa
+
+| ❌ Mơ hồ — KHÔNG viết | ✅ Chuẩn — Thay bằng |
+|---|---|
+| "hiển thị nhanh" | "response time < 2 giây (đo P95)" |
+| "giao diện đẹp" | Không test (không đo được — bỏ qua) |
+| "phù hợp" | Chỉ rõ phù hợp với điều gì: "khớp với AC-03 của BR-12" |
+| "hiển thị đúng" | "displays text 'Tên lớp: Toán 6A'" |
+| "hoạt động bình thường" | Liệt kê hành vi cụ thể: "button enabled, click được, navigates to /dashboard" |
+| "không lỗi" | "HTTP 200, không có error message, field is empty" |
+| "dữ liệu chính xác" | "body.name = 'Toán 6A', body.teacher_id = 42" |
+| "validate thành công" | "Error message không hiển thị, form submits successfully" |
+| "load được" | "Page displays within 3 seconds, no console error" |
+
+---
+
+## 2. Assertion Granularity — Mỗi assertion 1 điều kiện
+
+**Nguyên tắc (ATOMIC — QC chốt 2026-07-09):** Mỗi TC có **đúng 1** `#### Expected Result` với **ĐÚNG 1 bullet** (1 outcome; bullet có thể compound `A AND B` trên cùng 1 outcome). **Nhiều bullet / điểm-kiểm → TÁCH thành nhiều TC ĐỘC LẬP, mỗi TC 1 bullet** (không còn gộp checkpoint). Test Steps chỉ `[Action]`/`[Verify]`, **không** gắn `→ [Expected]` ở bước (chi tiết tách + renumber đồng bộ: `tc-metadata-format.md §"1 bullet Expected = 1 TC ĐỘC LẬP"`).
+
+```
+✅ ĐÚNG — 1 outcome, nhiều assertion liên quan:
+Assert: HTTP 201 AND body.id exists AND body.name = "Toán 6A" AND body.teacher_id = 42
+
+✅ ĐÚNG — 1 assertion đơn lẻ:
+Assert: Error message "Email không hợp lệ" displays below email field
+
+❌ SAI — 2 outcome khác nhau gom chung:
+Assert: HTTP 201 AND trên UI hiển thị lớp mới trong danh sách
+→ Tách thành 2 TC riêng: TC API (HTTP 201) + TC UI (danh sách cập nhật)
+```
+
+### 2.1 Chế độ ATOMIC TỐI ĐA (QC chốt 2026-07-14 — khi user yêu cầu "tách tới mức nhỏ nhất")
+
+Mặc định trên vẫn cho compound `A AND B` **cùng 1 outcome**. Nhưng khi chủ dự án YÊU CẦU THẲNG tách nhỏ nhất, áp **atomic tối đa — mỗi assertion độc-lập-fail = 1 TC**, gồm **nổ completeness list theo từng thành phần**:
+- Thẻ/card "hiển thị **đủ** [A, B, C, D, E]" → **mỗi thành phần 1 TC** (vd thẻ khung giờ: ảnh GV / ngày·giờ / tên GV / tên bài / ô chọn = 5 TC; info card 4 mục = 4 TC; hero: tiêu đề / khẩu hiệu / linh vật = 3 TC).
+- Đa-outcome BẮT BUỘC tách kể cả khi liên quan: popup + data-state · silent-handoff (điều hướng + không-popup) · mỗi con (`profile_id` A / B) · mỗi element/breakpoint responsive · mỗi touch-target · include vs exclude của cùng 1 filter.
+
+**⛔ RANH GIỚI — GIỮ 1 TC (đừng over-split vô nghĩa) kể cả ở chế độ tối đa:**
+- *Predicate đa-điều-kiện định-nghĩa-1-khái-niệm*: "chưa bắt đầu **và** còn ≥10' = slot-hợp-lệ" → 1 TC.
+- *Ngưỡng*: "≥44pt/48dp", "WCAG AA ≥4.5:1" → 1 TC (không tách iOS/Android, không tách chữ-thường/chữ-lớn).
+- *Exclusivity* chọn-một; *qualifier* ("không chỉ bằng màu").
+- Bỏ vế TRÙNG nghĩa với TC khác (vd a11y "nút mở sau chọn" trùng TC chọn-1-khung → cắt, không nhân bản).
+
+**Thủ tục bắt buộc trước khi thực thi (chênh quy mô lớn — FEAT-01-4: 82→WEB 132/APP 130):**
+1. **HỎI 1 câu chốt ranh giới completeness** (giữ-1-completeness ~95 TC vs nổ-từng-thành-phần ~130 TC) — quy mô rất khác, phải để user quyết.
+2. Dựng **bản đồ tách** (số mảnh mỗi TC cha) trước, KHÔNG để agent con tự suy diễn → giảm sai + giảm cắt cụt.
+3. Ưu tiên (P0/P1) TC con **kế thừa** từ cha; renumber tuần tự + đồng bộ Mục lục/Tổng hợp(đếm lại P0/P1 từ tag)/Trace Matrix(expand cha→con).
+4. **Làm CẢ 2 nền WEB+APP** (nhóm NFR khác nền: web a11y/responsive vs app safe-area/touch/back-gesture → tổng có thể lệch, granularity atomic tương đương).
+5. **Verify bằng DIFF, không tin lời đếm của agent**: ID tuần tự · `###`=`#### Expected` · mỗi Expected 1 bullet · 0 bảng `|` · Trace Matrix không ID chết · P0/P1 khớp tag (bug renumber KHÔNG throw — xem `qa-agents-large-write-unreliable`).
+
+---
+
+## 3. Đơn vị chuẩn theo domain
+
+| Domain | Đơn vị bắt buộc | Ví dụ |
+|---|---|---|
+| Thời gian phản hồi | `ms` hoặc `giây` + percentile | "< 500ms (P95)" |
+| Throughput | `req/s` hoặc `req/phút` | "≥ 100 req/s" |
+| Tải concurrent | `users` | "50 concurrent users" |
+| Dung lượng file | `KB` hoặc `MB` | "< 5MB" |
+| Ký tự | `ký tự` | "≤ 100 ký tự" |
+| Accessibility | WCAG level + version | "WCAG 2.1 AA" |
+| HTTP status | Mã số đầy đủ | "HTTP 201", "HTTP 400" (không "success") |
+| DB record | Bảng + cột + giá trị | "users.email = 'test@gmail.com'" |
+| Error message | Chuỗi chính xác in nghiêng | `"Email không hợp lệ"` |
+
+---
+
+## 4. Toán tử so sánh — Dùng thống nhất
+
+| Ý nghĩa | Ký hiệu | Ví dụ |
+|---|---|---|
+| Bằng chính xác | `=` | `body.status = "active"` |
+| Nhỏ hơn | `<` | `response time < 2s` |
+| Nhỏ hơn hoặc bằng | `≤` | `file size ≤ 5MB` |
+| Lớn hơn | `>` | `list.count > 0` |
+| Lớn hơn hoặc bằng | `≥` | `throughput ≥ 100 req/s` |
+| Tồn tại | `exists` | `body.id exists` |
+| Không tồn tại | `not exists` | `error_message not exists` |
+| Chứa chuỗi | `contains` | `body.message contains "thành công"` |
+
+---
+
+## 5. Test Data sourcing — Dữ liệu test từ đâu
+
+**Quy tắc:**
+- **Không hardcode** giá trị nhạy cảm (password, token, production data) vào TC.
+- **Dùng placeholder** rõ nghĩa: `<valid_email>`, `<teacher_password>`, `<existing_class_id>`.
+- **Ghi nguồn dữ liệu** khi cần setup: "Seed: tạo 1 lớp học với teacher_id = fixture.teacher.id".
+- **Biên dữ liệu** (BVA) phải ghi rõ giá trị cụ thể: "10 ký tự (biên trên của maxlength=10)".
+
+**Baseline cho NFR:**
+- Lấy từ **SLA document** trong `{paths.specs_dir}` (nếu có).
+- Lấy từ **AC** trong PRD (vd "AC-05: response < 3s").
+- Nếu không có document → ghi rõ `[Cần xác nhận baseline với PO]` trong Test Data.
+
+---
+
+## 6. Format Expected Result chuẩn theo lane
+
+**UI:**
+```
+Assert: <element> <trạng thái> — ví dụ: "Error message 'Email không hợp lệ' is visible below field"
+```
+
+**API:**
+```
+Assert: HTTP <code> AND body.<field> <toán tử> <giá trị> — ví dụ: "HTTP 201 AND body.id exists AND body.name = 'Toán 6A'"
+```
+
+**E2E:**
+```
+Assert: <chuỗi verify point> — ví dụ: "Class 'Toán 6A' displays in list AND teacher dashboard shows 1 new class"
+```
+
+**NFR:**
+```
+Assert: <metric> <toán tử> <ngưỡng> (<đơn vị>) — ví dụ: "P95 response time < 500ms at 50 concurrent users"
+```
+
+**Integration:**
+```
+Assert: <Module A state> AND <Module B state> — ví dụ: "HTTP 201 AND DB: classes.id = new_id AND Kafka: event 'class.created' published"
+```
+
+---
+
+## 7. Decision Table — Quy tắc coverage
+
+**Standard coverage (ISTQB CTFL v4.0):** mỗi rule (cột) = 1 TC tối thiểu.
+
+| Điều kiện | Rule 1 | Rule 2 | Rule 3 | Rule 4 |
+|---|---|---|---|---|
+| user.role = admin | T | T | F | F |
+| resource.owner = self | T | F | T | F |
+| **Action** | 200 OK | 403 | 200 OK | 403 |
+
+→ 4 rules = 4 TC (1 happy + 3 negative/edge).
+
+**BVA — 3 giá trị hay 4 giá trị?**
+
+| Spec | Giá trị phải test |
+|---|---|
+| Range 2 biên (`min ≤ x ≤ max`) | **4 giá trị:** min−1, min, max, max+1 |
+| Biên trên chỉ (`x ≤ max`) | **3 giá trị:** max−1, max, max+1 |
+| Biên dưới chỉ (`x ≥ min`) | **3 giá trị:** min−1, min, min+1 |
+| Đúng 1 giá trị hợp lệ | **3 giá trị:** value−1, value, value+1 |
+
+**Don't-care conditions:** condition không ảnh hưởng action → gộp rule, ghi `DC` (don't care) trong bảng. Ví dụ: `resource.owner` không quan trọng khi `user.role = superadmin` → gộp 2 rules thành 1 TC.
+
+**Đếm TC từ Decision Table:** N unique rules sau gộp don't-care = N TC tối thiểu. Nếu spec không có Decision Table sẵn → tự xây bảng trong Phase Clarify trước khi viết TC.
+
+**Phủ ĐỦ mọi ô — kể cả ô "không hành động".** Mỗi tổ hợp điều kiện phải có TC, kể cả ô mà kết quả là "không làm gì / không hiển thị" (vd: cả 2 trục cùng đủ rõ → KHÔNG hỏi câu phụ; cả 2 cùng chưa rõ → KHÔNG hỏi). Không được bỏ ô vì "không có hành động".
+
+**Kết hợp Decision Table + BVA, không trộn lẫn:**
+- Giá trị trong TC Decision Table nên **cách biệt rõ** so với ngưỡng (vd chênh lệch 25 so với ngưỡng 20) để cô lập đúng rule.
+- Điểm **sát biên** (ngưỡng−1 / = ngưỡng / ngưỡng+1) tách thành TC **BVA riêng**, không nhét vào TC Decision Table.
+
+**Báo coverage bằng TC ID cụ thể.** Khi tổng kết độ phủ cho logic điều kiện/ngưỡng: lập bảng ánh xạ từng rule/điểm biên → TC ID, đánh dấu rõ ô nào đủ/thiếu. Không kết luận "phủ gián tiếp" chung chung.
+
+---
+
+## 8. Teardown Data Strategy
+
+### 3 mức cleanup:
+
+| Mức | Khi nào | Cách thực hiện |
+|---|---|---|
+| **Inline** | TC tạo 1 bản ghi độc lập | Bước cuối Steps: `[Teardown] DELETE /api/v1/resource/{created_id}` |
+| **Fixture** | Nhiều TC dùng chung 1 tập data | Preconditions: `Fixture: seed_class()` — teardown trong `conftest.py` scope=function |
+| **Reset env** | TC thay đổi trạng thái hệ thống (email sent, payment, notification) | Ghi vào TC: `⚠️ Manual teardown: [bước cụ thể]` |
+
+### Format Teardown trong TC:
+
+```markdown
+#### Teardown
+- DELETE /api/v1/classes/{created_id} — xóa lớp đã tạo trong Steps
+- Hoặc: [Reset: fixture scope=function tự cleanup sau mỗi test]
+```
+
+### Quy tắc:
+- TC tạo bản ghi DB hoặc state THẬT (ghi vào tài khoản test) → **bắt buộc** ghi Teardown (API DELETE hoặc fixture rollback / reset tài khoản).
+- TC chỉ đọc (GET) hoặc chỉ verify UI tĩnh → không cần Teardown.
+- **TC chỉ cấu hình mock / route intercept / network monitoring → KHÔNG cần Teardown.** Reset mock về default là trách nhiệm của fixture `conftest.py` (scope=function tự teardown). Ghi "Reset mock về default" trong từng TC là **thừa** — không thêm. (Lane test qua mock hoàn toàn, vd UI/E2E khi API SKIP, hầu hết TC KHÔNG có Teardown.)
+- TC mobile/E2E tạo account → ghi `[Teardown: deactivate user via admin API]`.
+- TC không cleanup được → đánh dấu `⚠️ Manual teardown required` + ghi hướng dẫn chi tiết.

package/core/skills/qc/qa-designer/shared/read-doc-gap-inputs.md

@@ -0,0 +1,25 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/shared/read-doc-gap-inputs.md
+upstream_sha: a7e113b19f35aa47acf91e55cdfb3f630539806c
+---
+# Thủ tục: Nạp TOÀN BỘ tài liệu input từ DOC_GAP (BẮT BUỘC trước khi thiết kế/review TC)
+
+> Mục tiêu: designer/reviewer phải đọc **đúng bộ tài liệu nguồn mà qa-tc-analyst đã dùng** để dựng TEST_PLAN + DOC_GAP — không chỉ file domain. Tránh thiết kế/review TC trên ngữ cảnh thiếu, dẫn tới bỏ sót nghiệp vụ hoặc hiểu sai contract.
+
+## Các bước
+
+1. **Tìm file DOC_GAP** tại `{qc_artifact_dir}DOC_GAP.md` — **một file cho cả PRD**, các UC là các hàng phân biệt bằng cột `UC` (xem `/qc-analyze`). Không có → chạy `/qc-analyze {TICKET-ID} {platform}` trước; **đừng thiết kế TC trên ngữ cảnh thiếu**.
+2. **`Read` toàn bộ DOC_GAP.** Định vị mục **`## Tài liệu đầu vào đã đọc để phân tích`** — bảng liệt kê **đầy đủ** file nguồn (cột "Đường dẫn", tính từ `{paths.specs_dir}/`), kèm vai trò & phiên bản.
+3. **`Read` TỪNG file trong bảng đó** — ghép prefix `{paths.specs_dir}/` vào đường dẫn ở cột. Đọc HẾT, không bỏ sót dòng nào (spec chính + ref bắt buộc + transitive 1-hop). Nếu bảng liệt kê phiên bản, kiểm tra file hiện tại khớp; lệch phiên bản → ghi chú, không tự bịa.
+4. **Đối chiếu chéo:** nếu ngoài bảng DOC_GAP còn `## Coverage Attestation` / dòng "Tài liệu nguồn (spec chính)" ở header → xác nhận đã phủ hết; file nào có mặt ở header mà thiếu trong bảng → vẫn đọc.
+5. Chỉ sau khi đã nạp xong toàn bộ input + file domain (`business-dictionary.md`, `product-definition/`) mới bắt đầu viết/soát TC.
+
+## Nguyên tắc
+
+- **Không tự suy diễn ngoài tài liệu.** Chỉ dùng nội dung thực có trong các file đã đọc.
+- **Không đọc thiếu:** nếu DOC_GAP nói "Tổng: N tài liệu" thì phải mở đủ N (trừ file domain đã nạp riêng — vẫn nằm trong N).
+- **Bỏ qua** phần Change log / Appendix / "Giả định AI" khi trích evidence (giống ràng buộc nguồn của analyst), nhưng vẫn được đọc để hiểu ngữ cảnh.
+- Lane API: nếu DOC_GAP ghi SKIP (không có `openapi.yaml`/`.dbml`/`tdd/`) → không bịa endpoint.

package/core/skills/qc/qa-designer/shared/skill-decision-tree.md

@@ -0,0 +1,93 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/shared/skill-decision-tree.md
+upstream_sha: 57125f0c21512f2abcc55d00420e92c84c95fc8f
+---
+# Cây Quyết Định — Chọn Skill Đúng
+
+> Đọc file này khi không chắc nên dùng skill nào. Trả lời lần lượt các câu hỏi từ trên xuống.
+
+---
+
+## Bước 1 — Đối tượng test là gì?
+
+```
+Đối tượng test
+├── Hiển thị / validation / state của 1 screen       → [A] Xét tiếp Bước 2 (UI vs Integration GUI)
+├── User thực hiện workflow có mục tiêu nghiệp vụ    → [B] Xét tiếp Bước 3 (E2E vs Integration)
+├── 1 API endpoint (request/response/mã lỗi)         → api-testcase-designer
+├── NFR (performance/security/a11y/i18n)              → nfr-testcase-designer
+└── Luồng đa màn nằm trong 1 feature, không xuyên hệ thống → ui-testcase-designer (gui-feature)
+```
+
+---
+
+## Bước 2 — UI vs Integration GUI
+
+**Câu hỏi:** TC này có thể chạy với dữ liệu tĩnh/mock mà vẫn valid không?
+
+| Câu trả lời | Skill | Lý do (ISTQB) |
+|---|---|---|
+| **Có** — mock data đủ để verify | `ui-testcase-designer` | Component testing: verify UI behavior độc lập với backend |
+| **Không** — phải có API thật/stub mới verify được | `integration/gui` trong `integration-testcase-designer` | Integration testing: verify contract UI layer ↔ API layer |
+
+**Ví dụ phân biệt:**
+
+| Tình huống | Skill | Lý do |
+|---|---|---|
+| Dropdown có placeholder, đóng khi click ngoài | UI | Behavior tĩnh, không cần API |
+| Dropdown hiển thị đúng N item từ API response | Integration GUI | Verify data flow API → render |
+| Form validate email format | UI | Client-side validation, không cần server |
+| Form validate email "đã tồn tại" qua API | Integration GUI | Server-side validation = API call |
+| Bảng danh sách render đúng số cột, format | UI | Layout/display |
+| Bảng danh sách phản ánh đúng dữ liệu từ GET /list | Integration GUI | API data → UI sync |
+
+---
+
+## Bước 3 — E2E vs Integration
+
+**Câu hỏi:** Chủ thể của test là ai/cái gì?
+
+| Câu trả lời | Skill | Lý do (ISTQB) |
+|---|---|---|
+| **User** hoàn thành 1 mục tiêu nghiệp vụ từ đầu đến cuối | `e2e-testcase-designer` | System testing: user journey perspective |
+| **Module A ↔ Module B** trao đổi dữ liệu/contract đúng | `integration-testcase-designer` | Integration testing: system contract perspective |
+
+**Câu hỏi phụ để phân biệt rõ hơn:**
+
+> "Nếu tôi xóa hết step UI và chỉ test phần trao đổi dữ liệu, TC vẫn còn ý nghĩa không?"
+> - Có → Integration (bản chất là test handshake, UI chỉ là trigger)
+> - Không → E2E (user journey là trọng tâm, không thể tách ra)
+
+**Ví dụ phân biệt:**
+
+| Tình huống | Skill | Lý do |
+|---|---|---|
+| User đăng ký → nhận email → login → vào dashboard | E2E | User journey hoàn chỉnh, verify goal đạt được |
+| User tạo lớp học → lớp hiện trong danh sách | E2E | End-to-end từ action đến kết quả nhìn thấy |
+| Frontend gọi POST /enroll → DB ghi đúng bản ghi | Integration | Module contract: API ↔ DB, không phụ thuộc UI |
+| Service A gửi event Kafka → Service B xử lý đúng | Integration | System-to-system, không liên quan user |
+| Tạo đơn hàng qua UI → kiểm tra DB có bản ghi | Cả hai? | Nếu mục tiêu là "user đặt hàng thành công" → E2E; nếu mục tiêu là "POST /order ghi DB đúng" → Integration |
+
+---
+
+## Tóm tắt nhanh
+
+```
+Có API thật mới verify được?
+  └─ Không → UI
+  └─ Có, verify data flow 1 điểm → Integration GUI
+  └─ Có, user journey đầu-cuối → E2E
+  └─ Có, handshake 2 module/hệ thống → Integration
+```
+
+---
+
+## Quy tắc ưu tiên khi vẫn còn mơ hồ
+
+1. **UI ưu tiên nhỏ nhất:** viết TC nhỏ nhất có thể verify 1 behavior cụ thể.
+2. **Integration GUI** khi có server-side behavior: validation, lookup, list.
+3. **E2E chỉ cho P0/P1 critical path** (ISTQB Test Pyramid: E2E ít nhất, UI/Unit nhiều nhất).
+4. **Integration** khi tách được khỏi UI và vẫn có giá trị test.

package/core/skills/qc/qa-designer/shared/tc-metadata-format.md

@@ -0,0 +1,243 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/shared/tc-metadata-format.md
+upstream_sha: a31d66a7a8dab19cf821c9102a88282b09e16cb9
+---
+# TC Metadata Format (Chuẩn chung)
+
+## ⚠️ Nguyên tắc format file TC (BẮT BUỘC — QC yêu cầu)
+
+- **TOÀN BỘ file TC viết dạng LIST — KHÔNG dùng bảng Markdown** (không ký tự `|`). Áp dụng cho: Test Steps, Tổng hợp TC, Trace Matrix, TC bị Block, metadata đầu file. *(Chỉ file TC output; tài liệu skill này giữ bảng minh hoạ bình thường.)*
+- **Gom nhóm theo LOẠI test** (không theo luồng nghiệp vụ): thứ tự cố định **GUI → Validation → Functional → Integration → NFR → E2E** (xem §Phân nhóm).
+- Khi tái cấu trúc/đảo nhóm: **GIỮ NGUYÊN mã `TC_<FEATURE>_NNN`**, chỉ đổi vị trí (mã không cần liền mạch theo thứ tự đọc).
+- **App/Web là 2 bộ TC ĐỘC LẬP, mỗi nền chạy FULL business-logic** — trùng logic giữa 2 nền là chủ đích, KHÔNG tính duplicate defect; mỗi file phải độc lập đạt full coverage — mỗi nền một thư mục riêng (`{qc_dir}/{TICKET-ID}/web/` vs `/app/`), và sổ trace cũng tách theo nền.
+
+## ⚠️ Quy tắc "1 bullet Expected = 1 TC ĐỘC LẬP" (BẮT BUỘC — QC yêu cầu, testcase ATOMIC)
+
+> **Cập nhật 2026-07-09 (QC chốt — ĐẢO rule cũ):** trước đây cho GỘP nhiều checkpoint cùng-1-hành-vi vào 1 Expected nhiều bullet. **Nay: mỗi Expected chỉ ĐÚNG 1 bullet; mọi TC nhiều bullet phải TÁCH thành nhiều TC độc lập.** KHÔNG còn ngoại lệ "gộp checkpoint".
+
+- **Test Steps chỉ chứa hành động.** Mỗi bước là `[Action]` hoặc `[Verify]` THUẦN — **KHÔNG gắn `→ [Expected] ...` ở cuối bước.** Oracle nằm ở `#### Expected Result`.
+- **Atomic = 1 OUTCOME, không chỉ đếm "1 bullet".** Mỗi TC đúng 1 `#### Expected Result` với ĐÚNG 1 bullet. Bullet compound (`A, B`) **chỉ OK khi cùng 1 outcome** (vd "chỉ 5 slide: đúng 5 dots; slide 6,7 không xuất hiện" · "form hiển thị đủ 3 trường"). **Bullet nối bằng `;` kiểu "khẳng-định + phủ-định/outcome độc lập"** (vd "Có lối Đăng nhập**;** KHÔNG có OTP" · "sang routing**;** không OTP") **= 2 outcome → TÁCH tiếp** — soi nhanh khi review: grep bullet chứa `;` + `không/KHÔNG`. Tuyệt đối KHÔNG ≥2 bullet trong 1 Expected.
+- **Nhiều điểm-kiểm / outcome → TÁCH thành nhiều TC ĐỘC LẬP, mỗi TC 1 bullet.** Áp cho MỌI trường hợp: outcome độc lập (BVA/Decision-rule/tiền đề khác) LẪN nhiều checkpoint của **cùng 1 hành vi** (VD "màn hiển thị đủ ô A + nút B + lối C" → **3 TC**, không còn gộp).
+- **⚠️ Chế độ ATOMIC TỐI ĐA (QC chốt 2026-07-14 — GIẢI mâu thuẫn 2 gạch trên):** khi user YÊU CẦU THẲNG "tách nhỏ nhất", **completeness list nổ từng thành phần** (kể cả "form đủ 3 trường" → **3 TC**; thẻ khung giờ đủ 5 field → 5 TC) — tức áp gạch "→ 3 TC", KHÔNG dùng ngoại lệ "compound cùng-1-outcome" cho completeness. **NHƯNG GIỮ 1 TC** cho: *predicate đa-điều-kiện định-nghĩa-1-khái-niệm* ("chưa bắt đầu & ≥10' = slot-hợp-lệ"), *ngưỡng* ("≥44pt·48dp", "WCAG AA ≥4.5:1"), *exclusivity* chọn-một, *qualifier* ("không chỉ bằng màu"). Trước khi thực thi: **hỏi 1 câu chốt ranh giới completeness** (quy mô ~95 vs ~130 TC) + dựng **bản đồ tách** (số mảnh/TC cha) rồi mới ghi. Chi tiết + thủ tục verify: `precision-rules.md §2.1`. (Mặc định lúc SINH MỚI vẫn cho compound cùng-1-outcome; chế độ tối đa chỉ khi user yêu cầu.)
+- **Mỗi TC tách là testcase ĐỘC LẬP** — KHÔNG phải "con", KHÔNG đánh `(1/N)`, KHÔNG suffix `001a/001b`:
+  - **Tiêu đề mô tả riêng** self-contained (ngữ cảnh màn/hành vi + điểm được kiểm), heading khớp `**Title:**`.
+  - **Giữ FULL Test Steps** — lặp đủ bước để tới trạng thái assert (KHÔNG cắt bước theo từng bullet).
+  - Metadata (Feature/Module/Priority/Status/Tags/Trace) + Preconditions **copy nguyên** từ TC gốc.
+- **`#### Teardown` là SECTION riêng, KHÔNG phải bullet Expected.** Khi tách bằng script: parse `#### Teardown` riêng — **đừng nuốt bullet teardown vào `#### Expected Result`** (bug đã gặp → sinh "TC teardown giả" có Expected="Xoá dữ liệu test…", steps↔expected mâu thuẫn, không pass/fail được). Mỗi TC tách **TẠO bản ghi DB** (register/tạo tài khoản mới) phải giữ `#### Teardown` riêng; flow **login trên seed** không cần.
+- **Renumber TUẦN TỰ toàn dải** khi tách. Đổi số cascade → **đồng bộ NGAY**: `Mục lục` (range mỗi nhóm) · `Tổng hợp` (count + priority) · note `· N TC` mỗi Nhóm · `Trace Matrix` (**expand range** cũ thành list id mới) · `TC bị Block` (map id cũ → các id con). Dùng script xác định + backup trước–sau (agent ghi file lớn hay lỗi âm thầm — xem gạch cuối mục này).
+- **Assertion loại-trừ (KHÔNG hiển thị / KHÔNG xảy ra) là oracle THẬT** → mỗi cái là 1 bullet = 1 TC riêng. Khi tách bằng script cơ học, **kiểm lại không đánh rơi** (đối chiếu backup).
+- **Bullet metadata KHÔNG phải outcome.** `- Mobile: \`@pytest.mark.flaky(...)\`` lọt trong Expected là **marker** → loại khỏi phép đếm outcome, **dời ra meta** (`- **Chạy (mobile):** …`). Đếm nhầm marker là "bullet thứ 2" sẽ kết luận SAI rằng file cần tách. Reviewer cờ `[MARKER_IN_EXPECTED]`.
+- **⚠️ Trước khi viết script tách/renumber — biết 5 bẫy này trước.** 5 bug **không throw exception** (script "chạy xong" rồi ghi file hỏng):
+  1. **Double-remap**: transformer vừa *sinh* ID vừa *remap* ID → regex khớp luôn **heading vừa sinh** → ID trùng. **Chỉ remap `preamble` + `tail`, KHÔNG remap phần vừa sinh.**
+  2. **2 namespace ID**: liệt kê namespace TRƯỚC khi rename (vd FEAT-01-2: nội bộ `TC_FEAT-01-2_{APP,WEB}_NNN` remap ĐƯỢC · **master** `TC_NNN`/`TC_FEAT-01-2_NNN` ở BLOCKED/TODO **KHÔNG remap**). Verify: `diff` tập master-ID backup↔new.
+  3. **Replace-section làm rơi dòng chưa mô hình hoá** (dòng `>` note trong Expected). Giữ trailing note.
+  4. **Tiêu đề cha ≠ prefix con**: auto-title `"<heading cha> — <bullet>"` nhân đôi khi heading cha liệt kê cả 2 vế.
+  5. **Invariant phải gồm DIFF ĐỊNH DẠNG**, không chỉ đếm: liên tục ID · 0 trùng · 1 bullet/TC · oracle lossless (diff vs backup) · 0 dead-ref · **0 dòng-trống-kép/nhiễu whitespace** · master-ID không đổi.
+- **Có file ĐÃ atomic sẵn** — phân tích phân bố bullet/TC trước, đừng tách lấy được. Quy trình bền: sửa **source/backup** → **tái sinh** bằng script xác định → verify → sai thì restore.
+
+## Content Oracle — exact-copy phải self-contained + đúng nguồn
+
+- Chuỗi text spec-defined mà TC assert (tiêu đề màn, nhãn, copy nút, thông báo lỗi) → **ghi nguyên văn trong Expected Result** để TC tự chứa, người đọc không phải mở spec mới biết kỳ vọng.
+- **BẮT BUỘC kiểm nguồn ĐÚNG feature trước khi chép:** mở design-spec/PRD của **chính feature đó** và xác nhận chuỗi tồn tại. **KHÔNG mượn chuỗi từ feature anh em** — VD copy P2 của FEAT-01-1 là *"Việc tạo **tài khoản** đang tạm thời bị gián đoạn…"* còn FEAT-01-2 là *"Việc tạo **câu hỏi** đang tạm thời bị gián đoạn…"*; chép nhầm → oracle sai.
+- Chuỗi **chưa** có trong PRD/design-spec (chỉ ở Figma / chưa chốt) → **KHÔNG bịa oracle**: để trống + gắn `🚫 Block: [GAP-UC{N}-{nnn}]` hoặc `Status: PENDING`, ghi rõ chờ ai chốt.
+- Cờ "MIỄN coverage / thuộc Design Spec" trong BDD **không** cấm assert nếu PRD/design-spec vẫn enumerate đủ chuỗi — vẫn được đưa vào Expected Result; chỉ hạ về mức generic khi thực sự không có nguồn chốt.
+
+## Metadata (bắt buộc, dạng list)
+
+Mỗi trường 1 dòng, không bảng, không emoji dư:
+
+```
+- **Title:** <tên TC ngắn gọn>
+- **Feature:** <tên feature>
+- **Priority:** P0 | P1 | P2
+- **Status:** Draft
+- **Author:** AI
+- **Tags:** <lane>, <loại: smoke|sanity|regression>, <feature-tag>
+- **Trace:** BR-xx (ID gốc trong PRD/BDD ở `{paths.specs_dir}`)
+- **🚫 Block:** [GAP-UC{N}-{nnn}](../DOC_GAP.md) — <lý do> *(chỉ khi có)*
+```
+
+## Quy tắc Trace & Block
+
+- **Trace:** ghi `BR-xx` lấy từ ID trong `{paths.specs_dir}`; không có BR → `⚠️ Chưa có Business Rule`.
+- **🚫 Block:** TC phụ thuộc gap **vẫn viết đủ** + ghi `[GAP-UC{N}-{nnn}] — lý do`; chưa chạy tới khi gap Answered.
+
+## Cấu trúc TC
+
+```markdown
+### [TC_ID] — [Tên TC]
+- **Title:** ...
+- **Feature:** ...
+- **Priority:** P0|P1|P2
+- **Status:** Draft
+- **Author:** AI
+- **Tags:** ...
+- **Trace:** BR-xx
+- **🚫 Block:** (nếu có)
+
+#### Preconditions
+- ...
+
+#### Test Data
+- field: giá trị
+
+#### Test Steps
+1. [Action] ...          ← chỉ hành động; KHÔNG gắn "→ [Expected] ..."
+2. [Verify] ...          ← chỉ điểm quan sát; oracle nằm ở Expected Result
+
+#### Expected Result
+- <1 bullet kết quả cuối cụ thể, đo được — xem §"1 Expected Result / TC">
+
+#### Teardown   ← CHỈ khi TC tạo/sửa bản ghi hoặc state THẬT
+- <cách cleanup: API DELETE / reset tài khoản test / fixture / `⚠️ Manual teardown required`>
+```
+
+## Quy tắc Teardown (khi nào CÓ / KHÔNG)
+
+- **CÓ Teardown** chỉ khi TC tạo/sửa **bản ghi DB hoặc state thật** tồn tại sau test (vd: ghi phân khúc vào tài khoản test, tạo bản ghi qua API thật).
+- **KHÔNG cần Teardown** khi TC chỉ cấu hình **mock / route intercept / network monitoring** — việc reset mock về default là trách nhiệm của **fixture `conftest.py`** (scope `function` tự teardown mỗi test). Ghi "Reset mock về default" trong từng TC là **thừa** → không thêm.
+- Lane test qua mock hoàn toàn (vd lane UI/E2E khi API SKIP) → hầu hết TC KHÔNG có Teardown; chỉ TC chạm tài khoản/state thật mới có.
+
+## Phân nhóm TC & đánh số nhóm (chuẩn chung)
+
+TC trong file được gom theo **nhóm phân loại nội dung** và đánh **số CỐ ĐỊNH theo LOẠI** — số nhóm gắn cứng với loại, loại KHÔNG có TC thì **BỎ TRỐNG số đó** (KHÔNG đánh tuần tự lại). *(QC chốt 2026-07-08 — thay quy ước "liên tục" cũ.)*
+
+Gom theo **LOẠI test**, số nhóm CỐ ĐỊNH theo loại, chỉ tạo nhóm THỰC SỰ có TC:
+
+1. **GUI** — UI tĩnh, label, layout, placeholder, icon, trạng thái hiển thị (không đổi state).
+2. **Validation** — field-level: validate input, EP/BVA, biên, error message, trạng thái nút enabled/disabled theo điều kiện, read-only, ràng buộc.
+3. **Functional** — nghiệp vụ/luồng: business logic, submit/navigation, decision table, use case hoàn chỉnh.
+4. **Integration** — bắt tay ≥2 module/dịch vụ (kể cả qua mock): đọc/ghi cross-service, handshake, data flow, contract.
+5. **NFR** — phi chức năng: performance, a11y/keyboard, WCAG, security, i18n, compatibility.
+6. **E2E** — journey đầu-cuối nhiều use case.
+
+**Quy tắc đánh số & phân nhóm:**
+- Gán số CỐ ĐỊNH theo loại: **GUI=1 · Validation=2 · Functional=3 · Integration=4 · NFR=5 · E2E=6**. Loại KHÔNG có TC → **BỎ TRỐNG số đó**. VD file chỉ có GUI + Validation + Functional + E2E → `Nhóm 1 — GUI` / `Nhóm 2 — Validation` / `Nhóm 3 — Functional` / **`Nhóm 6 — E2E`** (bỏ trống 4 Integration, 5 NFR). **E2E LUÔN là Nhóm 6, NFR luôn 5, Integration luôn 4** — KHÔNG dồn số.
+- Phân vân **Validation vs Functional**: chỉ test trạng thái field/nút/biên → Validation; có luồng/submit/navigation/logic → Functional. **KHÔNG tạo nhóm "Tương tác"/"Happy Path" riêng.**
+- Lane chỉ có functional (API/Integration/NFR, không có GUI) → bỏ nhóm GUI, bắt đầu từ nhóm phù hợp.
+- **GIỮ NGUYÊN mã TC** khi gom/đảo nhóm — chỉ đổi vị trí; mã không cần liền mạch theo thứ tự đọc.
+- Mọi tham chiếu số nhóm trong file (Trace Matrix, ghi chú) phải khớp số CỐ ĐỊNH đã gán.
+
+## Cuối file (bắt buộc)
+
+Cả 2 mục dạng LIST (không bảng):
+
+```markdown
+## Trace Matrix
+- **BR-xx:** TC_001, TC_002
+- **⚠️ BR-yy:** — (Chưa có TC)
+
+## TC bị Block
+- **GAP-03** — TC_005: Chờ openapi.yaml
+```
+
+> Không thêm section `#### Python Test Mapping`. Bỏ nội dung gạch ngang.
+
+> ⚠️ **Bổ sung khi Edit thêm TC mới:** nối bullet mới **ngay liền sau bullet cuối** của list (Trace Matrix / TC bị Block), KHÔNG chèn dòng trắng giữa các bullet. Kiểm lại số TC khớp sau khi thêm.
+
+---
+
+## Tài liệu shared liên quan (bắt buộc nạp khi viết TC)
+
+| File | Mục đích |
+|---|---|
+| `shared/action-keywords-glossary.md` | Từ điển action keywords chuẩn — Click/Enter/Verify/Assert... |
+| `shared/precision-rules.md` | Quy tắc lượng hóa Expected Result, cấm từ mơ hồ, đơn vị chuẩn |
+| `shared/duplicate-check-procedure.md` | Quy trình kiểm tra TC trùng lặp trước khi viết mới |
+| `shared/implicit-scenarios.md` | Danh sách implicit scenarios cần xét thêm |
+| `shared/skill-decision-tree.md` | Cây quyết định chọn đúng skill |
+
+---
+
+## Gap Escalation Path (Xử lý khi TC bị Block)
+
+Khi TC có `🚫 Block: [GAP-UC{N}-{nnn}]` — thực hiện theo timeline:
+
+| Thời điểm | Hành động |
+|---|---|
+| **T+0 (phát hiện gap)** | Ghi GAP vào `DOC_GAP.md` — ID, loại, mô tả, tác động, nguồn |
+| **T+2 (2 ngày)** | Chưa có phản hồi → ping QA Lead / PO |
+| **T+5 (5 ngày)** | Vẫn chưa có → ghi **assumption tạm thời** vào TC bị Block |
+| **T+7 (7 ngày)** | Leo thang PO/PM — gap ảnh hưởng sprint delivery |
+
+### Format Assumption khi gap chưa được trả lời (T+5):
+
+```
+⚠️ Assumption (T+5): API trả về HTTP 422 khi tên lớp trùng — dựa trên pattern UC1.
+Nếu behavior khác → cập nhật Expected Result và re-review.
+```
+
+### Quy trình khi gap được giải quyết (Answered):
+1. Cập nhật `DOC_GAP.md`: status → `Answered`, ghi note giải thích.
+2. Bỏ `🚫 Block` trong TC → cập nhật Expected Result nếu có assumption sai.
+3. Thông báo `qa-tc-reviewer` review lại TC.
+4. Nếu answer thay đổi scope → tạo TC mới hoặc split TC hiện tại.
+
+---
+
+# Phần riêng của framework *(B12 — không có ở upstream)*
+
+Mọi thứ trên là chuẩn của đội QC. Bốn thứ dưới đây là **của framework**, và mọi skill tầng test
+đều theo — đừng lặp lại chúng trong từng skill.
+
+## Hai file TC, chia theo "có qua giao diện"
+
+```
+{qc_artifact_dir}test-cases/
+├── TC_<FEATURE>.Test.md          ← mặc định
+│     ## Nhóm 1 — GUI          ## Nhóm 4 — Integration (qua UI)
+│     ## Nhóm 2 — Validation   ## Nhóm 5 — NFR
+│     ## Nhóm 3 — Functional   ## Nhóm 6 — E2E
+└── TC_<FEATURE>_API.Test.md      ← cờ --api
+      ## Nhóm 1 — Endpoint
+      ## Nhóm 2 — Integration API/DB/Kafka
+```
+
+**Câu hỏi phân file:** *"TC này verify được mà **không cần UI** không?"*
+→ **có** = file API · **không** = file giao diện. *(Trùng Bước 2 của `skill-decision-tree.md`.)*
+
+⚠️ **Đuôi file là `.Test.md`, không phải `.md`.** `/qc-run-test` và `/qc-review` tìm `*.Test.md`;
+ghi ra file thiếu phần `.Test` là ghi ra thứ **không trạm nào tìm thấy**, và không có gì báo lỗi.
+
+Đánh số `TC_<FEATURE>_NNN` **liên tục toàn file**, không đánh lại theo từng nhóm.
+
+## Trace — hai hệ, ghi cả hai
+
+| Trường | Dạng | Vì sao cần |
+|---|---|---|
+| `**Trace:**` | `[BR-xx](../REQUIREMENT_ANALYSIS.md#3-business-rules)` — không có BR → `⚠️ Chưa có Business Rule` | truy về luật nghiệp vụ |
+| `**@trace.verifies:**` | `{UC-ID}-SC{N}` (lấy từ `@trace.scenario` của file `.feature`) | **join key** để `/qc-run-test` ghi `qc_status` theo từng kịch bản vào sổ trace |
+
+Một `SC` map được nhiều TC. **Thiếu `@trace.verifies` thì kết quả chạy không vào được sổ** — TC
+vẫn chạy, vẫn pass/fail, nhưng không ai biết nó phủ kịch bản nào.
+
+Cuối file: **Trace matrix** (BR ↔ TC ↔ SC) + **danh sách TC bị block** — cả hai **dạng danh
+sách**, không bảng (§Nguyên tắc format file đầu tài liệu này).
+
+## `🚫 Block` trỏ về file gap cấp PRD
+
+```
+- **🚫 Block:** [GAP-UC{N}-{nnn}](../DOC_GAP.md) — <lý do>
+```
+
+`DOC_GAP.md` nằm ở **thư mục cha** của `test-cases/`, nên liên kết đi lên một cấp. Mã gap mang
+UC (`GAP-UC1-001`) vì một file gap phủ cả PRD.
+
+## Dòng `Test-ID attribute`
+
+Ghi một dòng ở phần metadata **đầu file**:
+
+```
+Test-ID attribute: {attr}
+```
+
+Đọc `@trace.testid_attr` từ header tech-doc gộp (do `/map-testids` ghi). Bảng §4.5.6 chỉ cho
+**giá trị** test-id; đây là **tên thuộc tính** chứa chúng. `/qc-run-test` cần nó để cấu hình
+locator, `/qc-review` cần nó để biết selector trong script có đúng hợp đồng không.
+
+Thiếu field trong tech-doc → ghi `Test-ID attribute: — (thiếu @trace.testid_attr, chạy /map-testids)`.
+**Đừng bỏ trống và đừng tự đoán** — đoán sai thì mọi locator trượt 100%, và trượt vì lý do
+không liên quan gì tới thứ đang test.

package/core/skills/qc/qa-planner/risk-model.md

@@ -102,5 +102,5 @@ tiền không đáng.
 |---|---|---|---|---|---|
 | … | 2 · tiền | Cao | Cao | **P0** | functional/api + giá trị biên; e2e luồng thanh toán |
 
-Mỗi dòng rủi ro phải **trỏ được về BR-xx hoặc GAP-xx** đã có ở `REQUIREMENT_ANALYSIS.md` /
+Mỗi dòng rủi ro phải **trỏ được về `BR-xx` hoặc `GAP-UC{N}-{nnn}`** đã có ở `REQUIREMENT_ANALYSIS.md` /
 `DOC_GAP.md` — rủi ro không neo vào yêu cầu nào là rủi ro tự nghĩ ra.

package/core/skills/qc/qa-reviewer/script/e2e.md

@@ -84,4 +84,12 @@ F. CONVENTION:
 
 Mỗi issue: `file:line` | severity | mô tả | suggestion fix.
 Severity: 🔴 fix ngay (missing cleanup, dữ liệu không verify cross-module, shortcut journey) · 🟠 quan trọng (timeout thiếu, assertion chỉ ở bước cuối) · 🟡 nhỏ (style, docstring/title sai).
-Score: A/B/C/D · Top 5 issue cần fix trước merge.
+**Điểm `XX/100`** — ánh xạ mức độ sang điểm trừ: 🔴 = `FAIL` (−5đ) · 🟠 = `WARN` (−2đ) ·
+🟡 = ghi nhận, không trừ. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
+**Verdict:** `≥80` VÀ không còn 🔴 → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+
+**Ghi vào `{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — thêm một hàng vào bảng Tổng quan
+(cột `Tầng` phân biệt vai soát-code với vai soát-kịch-bản; **không ghi đè** hàng của vai kia).
+Khuôn + quy tắc ghi: `../shared/review-file-template.md`.
+
+**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-run-test`.

package/core/skills/qc/qa-reviewer/script/exploratory.md

@@ -39,7 +39,15 @@ Review session note sau khi test, coaching QC cải thiện kỹ năng.
  
 ## Output
  
-Score: A (excellent) / B (good) / C (needs improvement) / D (redo)
+**Điểm `XX/100`** — ánh xạ mức độ sang điểm trừ: 🔴 = `FAIL` (−5đ) · 🟠 = `WARN` (−2đ) ·
+🟡 = ghi nhận, không trừ. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
+**Verdict:** `≥80` VÀ không còn 🔴 → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+
+**Ghi vào `{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — thêm một hàng vào bảng Tổng quan
+(cột `Tầng` phân biệt vai soát-code với vai soát-kịch-bản; **không ghi đè** hàng của vai kia).
+Khuôn + quy tắc ghi: `../shared/review-file-template.md`.
+
+**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-run-test`.
 Mỗi tiêu chí: ✅/⚠️/❌ + feedback cụ thể
 Top 3 improvement suggestions (coaching tone)
 Đề xuất charter tiếp theo nếu chưa đủ coverage

package/core/skills/qc/qa-reviewer/script/functional.md

@@ -98,4 +98,12 @@ empty step `:pass` · test gọi `_private()` · Counter≠Pagination → xfail
  
 Mỗi issue: file:line | severity | mô tả | suggestion fix.
 Severity: 🔴 fix ngay (sai logic, POM breach, silent fail) · 🟠 quan trọng (fragile selector, wrong column, missing assert) · 🟡 nhỏ (style, thừa wait, orphan constant).
-Score: A/B/C/D · Top 5 issue cần fix trước.
+**Điểm `XX/100`** — ánh xạ mức độ sang điểm trừ: 🔴 = `FAIL` (−5đ) · 🟠 = `WARN` (−2đ) ·
+🟡 = ghi nhận, không trừ. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
+**Verdict:** `≥80` VÀ không còn 🔴 → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+
+**Ghi vào `{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — thêm một hàng vào bảng Tổng quan
+(cột `Tầng` phân biệt vai soát-code với vai soát-kịch-bản; **không ghi đè** hàng của vai kia).
+Khuôn + quy tắc ghi: `../shared/review-file-template.md`.
+
+**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-run-test`.

package/core/skills/qc/qa-reviewer/script/integration.md

@@ -88,4 +88,12 @@ F. CONVENTION:
 
 Mỗi issue: `file:line` | severity | mô tả | suggestion fix.
 Severity: 🔴 fix ngay (mock thay real call, missing DB verify, no cleanup) · 🟠 quan trọng (thiếu error state, hardcode ID, timeout ngắn) · 🟡 nhỏ (style, marker thiếu sub-domain).
-Score: A/B/C/D · Top 5 issue cần fix trước merge.
+**Điểm `XX/100`** — ánh xạ mức độ sang điểm trừ: 🔴 = `FAIL` (−5đ) · 🟠 = `WARN` (−2đ) ·
+🟡 = ghi nhận, không trừ. ≥80 đạt · 60–79 cần cải thiện · <60 không đạt.
+**Verdict:** `≥80` VÀ không còn 🔴 → **`APPROVED`**; ngược lại **`NEEDS_FIX`**.
+
+**Ghi vào `{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — thêm một hàng vào bảng Tổng quan
+(cột `Tầng` phân biệt vai soát-code với vai soát-kịch-bản; **không ghi đè** hàng của vai kia).
+Khuôn + quy tắc ghi: `../shared/review-file-template.md`.
+
+**KHÔNG tự sửa code** — chỉ nêu `file:line` + cách sửa. Người sửa là `/qc-run-test`.