@trungtamcongnghedigital/vsaf 1.0.0

package/skills/NTAPP/.agent/skills/NTAPP-qa-gap-resolver/references/priority-resolution-rule.md

@@ -0,0 +1,64 @@
+# Priority Resolution Rule — cách chốt phương án cho mỗi gap
+
+Đây là **lõi tư duy** của skill. Mọi step phân tích/đề xuất phải tuân theo file này.
+
+---
+
+## 0. Nguyên tắc nền
+
+- **Skill KHÔNG tự quyết.** Skill chỉ *phân tích + đề xuất*. Mọi gap đưa người dùng/PO chốt.
+- **Tách bạch 2 câu hỏi** — một nguồn không trả lời được cả hai:
+  - **(A) Hành vi nào là ĐÚNG?** → dùng để ra phương án.
+  - **(B) Hệ thống HIỆN đang làm gì?** → dùng để đo khoảng cách + chi phí sửa.
+- **Code thực tế thuộc câu hỏi (B), không phải (A).** Code là *hiện trạng để đo độ lệch*, KHÔNG phải chân lý để quyết định hành vi đúng. Chốt theo code chỉ vì "code đang chạy vậy" = hợp thức hoá bug — bị cấm (xem §4).
+
+---
+
+## 1. Thứ tự ưu tiên khi đề xuất "hành vi đúng" (câu hỏi A)
+
+Xét lần lượt, nguồn cao hơn thắng khi mâu thuẫn:
+
+1. **Dữ liệu thực tế** — *chỉ khi report có cite* (staging sample trong `f2`, giá trị thật) **và** data đó hợp lệ nghiệp vụ (không phải rác/legacy). Data mạnh nhất khi dùng để **bác bỏ một ràng buộc sai** (vd regex bắt chữ hoa nhưng data thật là chữ thường → regex chắc chắn cần xem lại). Report KHÔNG cite data thật → bỏ qua tầng này, KHÔNG tự query DB.
+2. **TechSpec / Contract canonical (L2 SSoT)** — theo R8 Contract Lock của dự án. Đây là nguồn mặc định để chốt khi các bản DD/FE lệch nhau.
+3. **DD (L3)** — chỉ dùng khi *không* mâu thuẫn TechSpec.
+
+**Code hiện tại = ĐO độ lệch + chi phí sửa**, không phải nguồn quyết định.
+**PO / nghiệp vụ = tầng phá thế bí** — khi các nguồn trên mâu thuẫn mà không nguồn nào rõ đúng, hoặc gap là mơ hồ nghiệp vụ thật.
+
+---
+
+## 2. Vai trò của code KHÔNG cố định — phải xác định CHIỀU LỆCH
+
+Code có thể **cũ hơn** tài liệu (viết theo DD stale) HOẶC **mới hơn** tài liệu (vừa fix bug/thêm yêu cầu mới nhưng docs chưa cập nhật). Không được áp thứ tự tầng một cách mù quáng — phải xác định chiều lệch bằng **dấu vết thời gian**:
+
+- `git log`/`git blame` dòng code liên quan → ngày sửa gần nhất.
+- Ngày các Change Request trong TechSpec (vd `v2.4 CR-COMPOSE-1`, `v3.0 CR-HUB-PUSH-REMOVAL`).
+- Ngày sinh của DD part (header/frontmatter, hoặc git).
+
+So 3 mốc → biết ai cũ ai mới → chọn đúng loại gap ở §3.
+
+---
+
+## 3. Phân loại gap → hành động tương ứng
+
+Mỗi gap PHẢI gán đúng 1 nhãn. Nhãn quyết định Phase 2 làm gì:
+
+| Nhãn | Dấu hiệu | Hành động đề xuất (Phase 2) |
+|---|---|---|
+| **stale-docs** | DD/FE part cũ hơn TechSpec (sinh trước CR); TechSpec là SSoT rõ ràng | Chốt theo TechSpec canonical → **regen DD part** (gọi `NTAPP-feature-design`/`NTAPP-dd-design`) hoặc sửa docs trực tiếp cho khớp |
+| **code-mới-docs-cũ** | git blame cho thấy code sửa SAU ngày DD/CR; code phản ánh yêu cầu mới/bugfix nhưng docs chưa cập nhật | Chốt theo **code** (là intent thật) → **cập nhật DD/TechSpec cho khớp code**; flag "docs cần đồng bộ" |
+| **lệch-code-vs-contract** | code làm KHÁC contract/SSoT, và code KHÔNG mới hơn (không phải yêu cầu mới) → **bug thật** | **Sửa code** → Phase 2 chỉ **sinh diff + lý do** cho dev duyệt (KHÔNG tự commit code) |
+| **mơ-hồ-nghiệp-vụ** | kể cả TechSpec/data cũng không trả lời được; cần quyết định nghiệp vụ | **KHÔNG execute** — giữ Todo, đề xuất `[Cần PO chốt]` + nêu phương án & trade-off |
+
+> Một gap có thể có nhiều mặt (vd vừa stale-docs vừa lộ bug code). Ghi rõ từng mặt, xử lý từng mặt theo bảng.
+
+---
+
+## 4. Cấm tuyệt đối (Red Flags — dừng lại nếu bạn đang làm)
+
+- ❌ Tự chọn giá trị/enum/hành vi "cho xong" mà không trích nguồn (xem [no-hallucination-rule.md](./no-hallucination-rule.md)).
+- ❌ Chốt theo code chỉ vì code đang chạy vậy, KHI chưa xác định chiều lệch → có thể đang hợp thức hoá bug.
+- ❌ Suy ra chiều lệch mà không mở git blame/log.
+- ❌ Sửa code trực tiếp / commit code trong Phase 2 (code chỉ được sinh diff đề xuất).
+- ❌ Flip một gap sang `Resolved` khi nó là `mơ-hồ-nghiệp-vụ` chưa có PO chốt.
+- ❌ Đề xuất mà không kèm **hiện trạng code đang làm gì** (câu hỏi B) — thiếu cái này thì không đo được độ lệch/chi phí.

package/skills/NTAPP/.agent/skills/NTAPP-qa-gap-resolver/steps/step-01-parse-and-map.md

@@ -0,0 +1,49 @@
+# STEP 01: PARSE & MAP (Phase 1 — Analyze)
+
+> **Acting as:** Senior Engineer / Tech Lead
+> **Tuân thủ:** [priority-resolution-rule.md](../references/priority-resolution-rule.md), [no-hallucination-rule.md](../references/no-hallucination-rule.md)
+
+## 1. Mục tiêu
+Đọc report, biến bảng GAP thành **danh sách gap có cấu trúc**, và map mỗi gap → tính năng/API/màn ảnh hưởng. Đây là nền cho việc rà 4 nguồn ở Step 02.
+
+## 2. Input
+- `report_path` = `{qa_artifacts}/reviews/{id}_qa_report.md` (resolve ở INITIALIZATION). Thiếu/không đọc được → DỪNG, hỏi user.
+
+## 3. Chỉ thị thực thi
+
+1. **Đọc TOÀN BỘ report.** Đọc kỹ phần đầu: "Cách dùng báo cáo", **"Ký hiệu file"** (legend), và mục "ĐÃ ĐỌC GÌ / Pre-flight". Legend là chìa khoá để giải mã đường dẫn file thật từ ký hiệu rút gọn.
+
+2. **Xây bảng giải mã ký hiệu → đường dẫn thật.** Report dùng ký hiệu rút gọn, ví dụ:
+   - `HUB-ts` → `Stage_3_Specs/techspec/HUB_techspec.md`
+   - `HUB-01/f2` → `Stage_4_Design/detailed_design/feature_design_parts/HUB-01/f2_..._part.md`
+   - `COMPOSE/f3` → `.../SCR-COMPOSE/f3_ui_part.md`
+   - `Module0` → `Stage_2_Architecture/00_system_connectivity_integration.md`
+   - `wbs` → `Stage_2_Architecture/project_wbs.md`
+   - `(d.X)` → dòng X trong file đó
+   > Lấy quy ước từ chính legend của report đang xử lý — KHÔNG hardcode; report khác có thể dùng ký hiệu khác.
+
+3. **Parse mỗi dòng GAP** (check TOÀN BỘ — cả 🔴/🟡/⚪) thành bản ghi:
+   | Trường | Nội dung |
+   |---|---|
+   | `gap_id` | GAP-NN |
+   | `severity` | 🔴 Cao / 🟡 Trung bình / ⚪ Thấp |
+   | `status` | Todo / Resolved / Pending (đọc từ cột Trạng thái) |
+   | `problem` | mô tả "Vấn đề" |
+   | `cited_sources` | danh sách (ký hiệu file, §, d.X) trích trong ô Vấn đề + ô Phương án |
+   | `proposed_options` | các phương án A/B/C report gợi sẵn (kèm dấu ✓) |
+   | `po_answer` | nội dung cột Trả lời hiện có (nếu PO đã điền) |
+
+   > Gap đã có `po_answer` (PO chốt rồi) hoặc `status=Resolved` → vẫn phân tích để xác nhận, nhưng đánh dấu "đã có chốt PO" và **ưu tiên tôn trọng quyết định PO** ở Step 02/03 (không đè lên).
+
+4. **Map gap → tính năng ảnh hưởng.** Với mỗi gap, từ các unit trong `cited_sources` (HUB-01, HUB-02, SCR-COMPOSE, PMT-EXT-01…) và mục Pre-flight, xác định:
+   - **Unit/loại**: BE service / FE screen / widget / external endpoint.
+   - **Bề mặt ảnh hưởng**: API nào (path/verb nếu report nêu), màn nào, luồng demo nào.
+   - **Repo code dự kiến**: unit này thuộc repo code nào trong `code_repo_roots` (để Step 02 rà code). Chưa chắc → để Step 02 xác minh.
+
+5. **Nhóm sơ bộ gap cùng gốc.** Nhiều gap thường chung một nguyên nhân (vd "TechSpec CR mới vs DD part stale"). Ghi nhận nhóm để Step 02 rà nguồn 1 lần dùng cho cả nhóm (tiết kiệm) và Step 04 gom theo file đích.
+
+## 4. Output (in-memory, chuyển sang Step 02)
+- Danh sách gap có cấu trúc (bảng ở mục 3.3) + bảng giải mã ký hiệu → đường dẫn thật + map tính năng ảnh hưởng + nhóm gap cùng gốc.
+
+## 5. Gate độ phủ
+Parse **hết** gap trong report (đếm khớp con số tổng ở cuối report, vd "Tổng: 20 điểm"). Thiếu gap = parse chưa xong.

package/skills/NTAPP/.agent/skills/NTAPP-qa-gap-resolver/steps/step-02-evidence-and-propose.md

@@ -0,0 +1,48 @@
+# STEP 02: EVIDENCE & PROPOSE (Phase 1 — Analyze)
+
+> **Acting as:** Senior Engineer / Tech Lead
+> **Tuân thủ:** [priority-resolution-rule.md](../references/priority-resolution-rule.md) (lõi — đọc trước), [no-hallucination-rule.md](../references/no-hallucination-rule.md)
+
+## 1. Mục tiêu
+Với **MỖI gap**, thu thập bằng chứng từ 4 nguồn, xác định chiều lệch, phân loại, và ra **đề xuất phương án có trích dẫn**. Đây là bước nặng nhất → chạy song song.
+
+## 2. Song song hoá (bắt buộc cho report nhiều gap)
+- Dispatch **1 subagent cho mỗi NHÓM gap cùng gốc** (nhóm đã lập ở Step 01) — không phải mỗi gap, để tránh đọc lặp cùng file nguồn. Nhóm độc lập → chạy song song.
+- Mỗi subagent nhận: danh sách gap của nhóm + bảng giải mã ký hiệu + `code_repo_roots` + [priority-resolution-rule.md](../references/priority-resolution-rule.md). Subagent trả về phân tích per-gap theo mục 4.
+- Dùng `general-purpose` agent (cần đọc file + grep code + git). Gom kết quả về theo `gap_id`.
+
+## 3. Thu 4 nguồn cho mỗi gap (theo thứ tự ưu tiên câu hỏi A)
+
+Với mỗi gap, mở ĐÚNG file + §/dòng được cite (đừng đọc mò), thu:
+
+1. **Dữ liệu thực tế** — CHỈ nếu report cite (staging sample trong `f2`, giá trị thật). Ghi giá trị + nguồn. Report không cite → bỏ qua tầng này, KHÔNG tự query DB.
+2. **TechSpec / Contract (SSoT)** — đọc đúng §/dòng canonical. Ghi giá trị canonical + số hiệu CR nếu có.
+3. **DD (L3)** — đọc part BE/FE liên quan. Ghi giá trị + ngày sinh part (frontmatter/git).
+4. **Code thực tế (câu hỏi B — hiện trạng)** — grep trong `code_repo_roots` tìm chỗ xử lý (validator, enum, controller, query…). Ghi:
+   - **Hành vi code đang làm** (path:line).
+   - **`git blame`/`git log`** dòng đó → ngày sửa gần nhất (để xác định chiều lệch).
+
+> Thiếu nguồn quan trọng mà report kỳ vọng có (vd cite một §techspec nhưng file không tồn tại) → ghi `[Không tìm thấy nguồn X]`, KHÔNG bịa.
+
+## 4. Xác định chiều lệch + phân loại (theo priority-resolution-rule §2, §3)
+
+So 3 mốc thời gian (ngày CR TechSpec · ngày DD · ngày commit code) → gán đúng 1 nhãn:
+- **stale-docs** · **code-mới-docs-cũ** · **lệch-code-vs-contract** (bug) · **mơ-hồ-nghiệp-vụ**
+
+Một gap nhiều mặt → ghi từng mặt + nhãn từng mặt.
+
+## 5. Ra đề xuất (per-gap)
+
+Mỗi gap xuất khối phân tích gồm ĐỦ 6 phần (thiếu phần nào = chưa đạt):
+
+1. **Tính năng ảnh hưởng** — unit/API/màn/luồng demo (từ Step 01).
+2. **Bằng chứng 4 nguồn** — bảng: Nguồn | Giá trị/Hành vi | Trích dẫn (file §d.X hoặc path:line) | Ngày. Nguồn không có → ghi "—".
+3. **Phân loại + chiều lệch** — nhãn + 1 câu lý do dựa trên mốc thời gian.
+4. **Đề xuất chốt** — giá trị/hành vi canonical nên chốt + nguồn hậu thuẫn (theo thứ tự ưu tiên). Nếu `mơ-hồ-nghiệp-vụ` → ghi `[Cần PO chốt]` + liệt kê phương án & trade-off, KHÔNG tự chọn.
+5. **Hiện trạng code (câu hỏi B)** — code đang làm gì, **khớp hay lệch** đề xuất, mức độ lệch.
+6. **Việc cần làm nếu chốt phương án này** — liệt kê cụ thể: regen DD part nào / sửa §techspec nào / sửa file code nào (đề xuất diff) — đây là input cho Step 04. Kèm **file đích** của mỗi việc (để Step 04 gom).
+
+> Nếu gap đã có `po_answer` (PO chốt): tôn trọng quyết định PO; phần "Đề xuất chốt" = xác nhận/triển khai theo PO, chỉ cảnh báo nếu phát hiện quyết định PO xung đột bằng chứng thực tế.
+
+## 6. Output (in-memory, chuyển sang Step 03)
+Khối phân tích 6 phần cho mỗi gap + danh sách "việc cần làm" kèm file đích (gom sẵn theo file để Step 04 dùng).

package/skills/NTAPP/.agent/skills/NTAPP-qa-gap-resolver/steps/step-03-writeback-gate.md

@@ -0,0 +1,51 @@
+# STEP 03: WRITE-BACK & GATE 1 (Phase 1 — Analyze)
+
+> **Acting as:** Senior Engineer / Tech Lead
+> **Tuân thủ:** [priority-resolution-rule.md](../references/priority-resolution-rule.md), [no-hallucination-rule.md](../references/no-hallucination-rule.md)
+
+## 1. Mục tiêu
+Ghi kết quả phân tích Step 02 trở lại **report gốc**: điền đề xuất ngắn vào cột Trả lời + append section phân tích chi tiết. Rồi DỪNG chờ người dùng chọn gap xử lý.
+
+## 2. Chỉ thị thực thi
+
+### 2.1. Điền cột "Trả lời" của từng dòng GAP (đề xuất NGẮN)
+Với mỗi gap CHƯA có `po_answer`:
+- Ghi vào ô "Trả lời": `[AI đề xuất] <X> — <lý do 1 dòng + nguồn>`
+  - Ví dụ: `[AI đề xuất] A — chốt theo HUB-ts §11.2.1 (d.1478); DD stale hơn CR-COMPOSE-1`
+  - Nếu là `mơ-hồ-nghiệp-vụ`: ghi `[Cần PO chốt] — <câu hỏi nghiệp vụ>` (KHÔNG chọn A/B/C).
+- Đổi cột **Trạng thái**: `Todo → Pending` (đã có đề xuất nhưng cần user xác nhận). Render đúng checkbox stack sẵn có của report: `☐&nbsp;Todo<br>☐&nbsp;Resolved<br>☑&nbsp;Pending`.
+
+Gap **đã có `po_answer`** → KHÔNG đè cột Trả lời; giữ nguyên Trạng thái do PO đặt.
+
+### 2.2. Append section phân tích chi tiết vào CUỐI report gốc
+Thêm 1 section (không phá bố cục bảng phía trên):
+
+```markdown
+---
+## PHÂN TÍCH & ĐỀ XUẤT (AI) — {date}
+
+> Do `ntapp-qa-gap-resolver` sinh. Đây là **đề xuất có bằng chứng**, KHÔNG phải quyết định cuối — chờ PO/Lead chốt ở cột "Trả lời".
+
+### GAP-NN — <tiêu đề ngắn>  ·  Phân loại: <nhãn>
+1. **Tính năng ảnh hưởng:** …
+2. **Bằng chứng 4 nguồn:** <bảng Nguồn | Giá trị | Trích dẫn | Ngày>
+3. **Phân loại + chiều lệch:** <nhãn> — <lý do theo mốc thời gian>
+4. **Đề xuất chốt:** …
+5. **Hiện trạng code:** <đang làm gì · khớp/lệch · path:line>
+6. **Việc cần làm nếu chốt:** <regen DD / sửa §techspec / diff code> — file đích: …
+```
+Lặp cho mọi gap, theo thứ tự 🔴 → 🟡 → ⚪.
+
+### 2.3. Bảng tổng hợp đầu section (để quét nhanh)
+Ngay dưới tiêu đề section, thêm bảng: `GAP | Mức | Phân loại | Đề xuất tóm tắt | File đích | Cần PO?`.
+
+## 3. Ghi file
+Ghi đè in-place `{qa_artifacts}/reviews/{id}_qa_report.md`. **KHÔNG** tạo archive/`_v{N}`. Giữ nguyên toàn bộ nội dung PO đã điền trước đó.
+
+## 4. GATE 1 (bắt buộc — DỪNG)
+Sau khi ghi file, trình bày trong hội thoại:
+- Bảng tổng hợp (mục 2.3) + đếm theo phân loại.
+- **Nhóm gap cùng gốc** (chốt 1 lần cho cả nhóm) để user quyết theo cụm.
+- Chỉ rõ gap `mơ-hồ-nghiệp-vụ` **bắt buộc PO chốt trước**, skill không execute được.
+
+Rồi HỎI: **"Chọn gap (hoặc nhóm) nào để tôi xử lý ở Phase 2?"**. KHÔNG tự sang Step 04. Chờ người dùng chọn.

package/skills/NTAPP/.agent/skills/NTAPP-qa-gap-resolver/steps/step-04-execute.md

@@ -0,0 +1,44 @@
+# STEP 04: EXECUTE & GATE 2 (Phase 2 — Execute)
+
+> **Acting as:** Senior Engineer / Tech Lead
+> **Tuân thủ:** [priority-resolution-rule.md](../references/priority-resolution-rule.md), [no-hallucination-rule.md](../references/no-hallucination-rule.md)
+> **Chỉ chạy sau khi người dùng đã chọn gap ở GATE 1.**
+
+## 1. Mục tiêu
+Thực thi các gap đã được chọn: sửa docs trực tiếp, sinh diff cho code, giữ gap nghiệp vụ chờ PO. Xử lý **song song theo file đích**.
+
+## 2. Gom theo FILE ĐÍCH (bắt buộc — chống ghi đè lẫn nhau)
+Từ "Việc cần làm" của các gap đã chọn (Step 02 phần 6), **gom theo file đích, KHÔNG theo gap**:
+- Nhiều gap cùng đụng 1 file (vd GAP-01/02/03/04/06 đều regen `HUB-02/f2`) → **1 worker cho file đó**, áp *tất cả* thay đổi liên quan cùng lúc.
+- Song song là **giữa các file khác nhau**, không phải giữa các gap. Hai worker không bao giờ ghi cùng 1 file.
+- Dùng subagent per-file-đích cho các file độc lập; chờ tất cả xong rồi mới sang GATE 2.
+
+## 3. Thực thi theo loại (dựa trên nhãn phân loại)
+
+| Nhãn / loại đích | Hành động | Ràng buộc |
+|---|---|---|
+| **stale-docs → DD part** | Regen DD part theo canonical đã chốt: **gọi skill `NTAPP-feature-design` / `NTAPP-dd-design`** đúng convention (header `id:` + bump `dd_version`, format part) | KHÔNG tự tay viết part lệch convention; tôn trọng pre-commit hook |
+| **stale-docs / code-mới-docs-cũ → TechSpec / Module 0 / ux / wbs** | Sửa docs trực tiếp tại đúng §/dòng cho khớp giá trị canonical (hoặc khớp code nếu `code-mới-docs-cũ`) | Sửa tối thiểu, đúng chỗ; giữ nguyên phần khác |
+| **lệch-code-vs-contract (bug) → code** | **CHỈ sinh diff + lý do**, trình bày cho user duyệt (và tuỳ chọn ghi `{qa_artifacts}/reviews/{id}_code_diff_proposals.md`) | **TUYỆT ĐỐI KHÔNG tự sửa/commit code.** Nêu rõ file, hàm, thay đổi, rủi ro (tài chính) |
+| **mơ-hồ-nghiệp-vụ** | KHÔNG execute | Giữ Trạng thái `Todo`, ghi rõ đang chờ PO |
+
+> Nếu một docs edit tự chế có thể tốt hơn khi delegate (DD part) → luôn ưu tiên gọi skill chuyên biệt. Với hệ tài chính: BigDecimal/transaction/idempotency/audit — dù chỉ là diff đề xuất, phải nêu rõ tác động (xem be-finance-rules).
+
+## 4. Cập nhật report gốc sau execute
+Với mỗi gap đã xử lý xong (docs đã sửa, hoặc diff đã trình):
+- **Docs đã sửa trực tiếp** → cột Trạng thái `→ Resolved`; cột Trả lời thêm `✓ Đã xử lý: <file đã sửa / DD đã regen>`.
+- **Code (diff đề xuất)** → giữ `Pending`; ghi `⏳ Diff code chờ dev duyệt: <file>`. KHÔNG flip Resolved vì code chưa merge.
+- **mơ-hồ-nghiệp-vụ** → giữ `Todo`, ghi `⏸ Chờ PO chốt`.
+
+Cập nhật cả section "## PHÂN TÍCH & ĐỀ XUẤT (AI)": thêm dòng "Kết quả execute {date}" dưới gap tương ứng.
+
+## 5. Rà lại code đã đụng (nếu Phase 2 có sinh diff code BE)
+Trước GATE 2, tự review diff code đề xuất theo [be-finance-rules] + rule Sonar (S3776, S1192, S125, S1128…) đã nêu trong CLAUDE.md của dự án; nêu vi phạm (nếu có) trong báo cáo. Diff docs không áp rule code.
+
+## 6. GATE 2 (bắt buộc — DỪNG)
+Báo cáo cuối:
+- **Đã sửa trực tiếp:** danh sách file docs/DD + tóm tắt thay đổi.
+- **Diff code chờ duyệt:** danh sách + rủi ro.
+- **Còn chờ PO:** gap `mơ-hồ-nghiệp-vụ`.
+- **Trạng thái report:** bao nhiêu Resolved / Pending / Todo.
+Nhắc user: gap 🔴 chỉ mở gate viết testcase khi = Resolved (theo report gốc).

package/skills/NTAPP/.agent/skills/NTAPP-qa-gap-resolver/workflow.md

@@ -0,0 +1,106 @@
+# WORKFLOW: NTAPP QA — GAP RESOLVER
+
+**Goal:** Đọc báo cáo rà soát tính nhất quán tài liệu (`{id}_qa_report.md` — bảng GAP theo mức 🔴/🟡/⚪ do `ntapp-qa-audit` hoặc tương đương sinh ra), **phân tích lần lượt từng gap**, đối chiếu 4 nguồn theo thứ tự ưu tiên, **đề xuất phương án cho người dùng chốt**, rồi **thực thi** các gap đã được chọn.
+
+**Your Role:** Bạn đóng vai **Senior Engineer / Tech Lead** — người rà soát chéo tài liệu + code thực tế, xác định chiều lệch, và đề xuất hướng xử lý có bằng chứng. Bạn là điểm chạm duy nhất với người dùng.
+
+**Compliance (BẮT BUỘC):**
+- [priority-resolution-rule.md](./references/priority-resolution-rule.md) — lõi tư duy: thứ tự ưu tiên, phân loại gap, xác định chiều lệch. **Đọc trước khi phân tích bất kỳ gap nào.**
+- [no-hallucination-rule.md](./references/no-hallucination-rule.md) — mọi đề xuất phải trích nguồn; thiếu bằng chứng → `mơ-hồ-nghiệp-vụ`, chờ PO.
+- **Skill KHÔNG tự quyết.** Có 2 GATE bắt buộc dừng chờ người dùng (§EXECUTION).
+
+---
+
+## ROSTER & ROLES
+
+| Phase | Step | Vai trò | Output |
+|---|---|---|---|
+| 1 ANALYZE | 01 Parse & Map | Parse report → danh sách gap có cấu trúc + map tính năng ảnh hưởng | (in-memory) danh sách gap |
+| 1 ANALYZE | 02 Evidence & Propose | Thu 4 nguồn (song song) → phân loại + chiều lệch → đề xuất | (in-memory) phân tích per-gap |
+| 1 ANALYZE | 03 Write-back & GATE 1 | Điền `[AI đề xuất]` vào report gốc + append section phân tích | report gốc đã cập nhật |
+| 2 EXECUTE | 04 Execute & GATE 2 | Thực thi gap đã chọn (song song theo file đích) | docs đã sửa / code diff / report Resolved |
+
+---
+
+## KIẾN TRÚC WORKFLOW (2 PHASE — 2 GATE)
+
+```
+                    ┌──────────── PHASE 1: ANALYZE ────────────┐
+[report gốc] ──► 01 Parse & Map ──► 02 Evidence & Propose ──► 03 Write-back
+{qa_artifacts}/reviews/         (4 nguồn, song song)      (điền cột Trả lời +
+  {id}_qa_report.md              phân loại + chiều lệch     append phân tích)
+                                                                   │
+                                                          ══ GATE 1 ══  DỪNG:
+                                                          user chọn gap nào xử lý
+                                                                   │
+                    ┌──────────── PHASE 2: EXECUTE ────────────┐  ▼
+                                 04 Execute
+                    gom gap đã chọn THEO FILE ĐÍCH → song song giữa các file:
+                      • docs (DD/TechSpec)  → sửa trực tiếp (DD: gọi feature-design/dd-design)
+                      • code (bug/lệch)     → CHỈ sinh diff + lý do (không commit)
+                      • mơ-hồ-nghiệp-vụ     → giữ Todo, chờ PO
+                                 flip Resolved + ghi đã làm gì
+                                          │
+                                 ══ GATE 2 ══  báo cáo kết quả execute
+```
+
+## INITIALIZATION (Configuration Resolution)
+
+Trước khi chạy bất kỳ step nào, resolve config theo cascade 3 layer (cao → thấp).
+
+### Bước 0 — Resolve `{project-root}` (spec repo)
+Walk up từ `cwd` tìm marker: thấy `_bmad/` → project-root; else thấy `.git/` → project-root; else fallback `cwd` + log warning.
+
+### Layer 1 — BMad project config
+Đọc `{project-root}/_bmad/bmm/config.yaml` nếu có. Lookup: `project_name`, `stage_5_build_verify`. Thay placeholder `{project-root}` bằng absolute path đã resolve.
+
+### Layer 2 — Skill family config (override)
+Đọc `{project-root}/.bmm-config.yaml`, tìm section `ntapp-qa-gap-resolver:`. Override Layer 1 nếu có.
+```yaml
+ntapp-qa-gap-resolver:
+  qa_artifacts: <path>      # optional, override default
+  code_repo_roots:          # optional, danh sách repo code để rà code + git blame
+    - <path-repo-1>
+    - <path-repo-2>
+```
+
+### Layer 3 — Default + Interactive (fallback)
+- `qa_artifacts` chưa resolve → default = `{stage_5_build_verify}/test`. Cả `stage_5_build_verify` cũng miss → DỪNG, hỏi user path, ghi vào `.bmm-config.yaml`.
+- `code_repo_roots` chưa cấu hình → dùng các **additional working directories** của workspace (repo code cạnh spec repo). Nếu không tìm được code cho một unit khi cần rà → DỪNG, hỏi user đường dẫn repo code (rồi có thể ghi vào config).
+
+### Biến runtime
+| Biến | Nguồn | Ghi chú |
+|---|---|---|
+| `project_name` | Layer 1/2/3 | Header tài liệu |
+| `qa_artifacts` | Layer 1/2/3 | Root output QA (= `{stage_5_build_verify}/test`) |
+| `report_path` | User input / suy từ `{id}` | File report cần xử lý (`{qa_artifacts}/reviews/{id}_qa_report.md`) |
+| `id` / `slice_id` | User input / parse từ report | Đơn vị/slice của report |
+| `code_repo_roots` | Layer 2/3 | Nơi rà code + chạy `git blame` |
+| `date` | System | ISO 8601 |
+
+---
+
+## Output Naming (canonical-only, KHÔNG archive)
+
+| Output | Path | Ghi chú |
+|---|---|---|
+| Report gốc đã cập nhật | `{qa_artifacts}/reviews/{id}_qa_report.md` | Ghi đè in-place: điền cột Trả lời + append section "## PHÂN TÍCH & ĐỀ XUẤT (AI) — {date}" |
+| Code diff đề xuất (nếu có) | trình bày trong hội thoại + (tuỳ chọn) `{qa_artifacts}/reviews/{id}_code_diff_proposals.md` | KHÔNG commit code |
+
+Không tạo `archive/` hay `_v{N}`. Report gốc là canonical, cập nhật in-place.
+
+---
+
+## EXECUTION
+
+### PHASE 1 — ANALYZE (chạy liền mạch 01 → 03)
+1. **[Step 01: Parse & Map](./steps/step-01-parse-and-map.md)** — đọc report, parse ra danh sách gap + ký hiệu file, map mỗi gap → tính năng/API/màn ảnh hưởng.
+2. **[Step 02: Evidence & Propose](./steps/step-02-evidence-and-propose.md)** — với MỌI gap (check toàn bộ), thu 4 nguồn **song song**, phân loại + xác định chiều lệch, ra đề xuất theo [priority-resolution-rule.md](./references/priority-resolution-rule.md).
+3. **[Step 03: Write-back & GATE 1](./steps/step-03-writeback-gate.md)** — điền `[AI đề xuất]` vào cột Trả lời (đổi Trạng thái → Pending), append section phân tích chi tiết vào report gốc.
+
+> **GATE 1 (bắt buộc):** Sau Step 03, DỪNG. Trình bày tóm tắt + hỏi người dùng **chọn gap nào để xử lý** (Phase 2). KHÔNG tự đi tiếp.
+
+### PHASE 2 — EXECUTE (chỉ chạy sau khi user chọn)
+4. **[Step 04: Execute & GATE 2](./steps/step-04-execute.md)** — gom gap đã chọn **theo file đích**, xử lý **song song giữa các file**; docs sửa trực tiếp, code chỉ sinh diff, gap nghiệp vụ giữ Todo. Flip Resolved + ghi đã làm gì.
+
+> **GATE 2 (bắt buộc):** Sau Step 04, DỪNG. Báo cáo: đã sửa file nào, diff code nào chờ duyệt, gap nào còn chờ PO.

package/skills/NTAPP/.agent/skills/NTAPP-qa-generate-testcase/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: ntapp-qa-generate-testcase
+description: 'Sinh kịch bản kiểm thử E2E automation-ready cho một SLICE HOẶC một đơn vị đứng riêng (HUB/WGT/SCR/MPF… — tính năng không gom vào SLICE) theo School B: shift-left → risk-based allocation → triple-emit. Tập trung trải nghiệm End-to-End từ UI xuống Backend, phối hợp các units (FE/BE/downstream). Input nhận `{id}`: nếu có file SLICE `{slices_root}/{id}-*.md` → lane SLICE (nhiều unit); nếu không nhưng có `{id}_detailed_design.md` → lane unit-đơn. Output 3 artifact tại `{qa_artifacts}/{id}/`: `{id}_testspec.feature` (Gherkin canonical → automation), `{id}_detailed_test_manual_testcase.md` (bảng 11 cột — QA ký + qa-robot parse), `{id}_fixtures.yaml` (data máy-đọc). Bridge sang `/ntapp-qa-robot`. Alias lệnh: `/ntapp_qa_generate_testcase`. Sử dụng khi người dùng nói "sinh testcase slice", "test E2E cho slice", "generate slice qa", "viết KBKT cho một slice", "sinh testcase cho HUB/WGT", "test cho tính năng đứng riêng".'
+---
+
+# NTAPP QA Generate Slice / Unit Testcase (E2E + Automation-Ready)
+
+Sinh kịch bản kiểm thử E2E cho một **SLICE** (nhiều unit) hoặc một **đơn vị đứng riêng** (HUB/WGT/SCR/MPF — tính năng không gom vào SLICE) với **triple-emit** (`.feature` + markdown view + `fixtures.yaml`), risk-based allocation và shift-left gate — output dùng trực tiếp cho automation qua `/ntapp-qa-robot`.
+
+**Hai lane input** (auto-detect ở Step 00 theo `{id}`): `slice` (có file SLICE tương ứng → phối hợp nhiều unit + xếp thứ tự E2E) · `unit` (chỉ có `{id}_detailed_design.md` → coi như "slice một unit", bỏ bước xếp thứ tự liên-unit, giữ nguyên triple-emit + risk allocation). Mọi biến định danh dùng chung **một khóa `{id}`** = ID đầy đủ (vd `SLICE-06`, `WGT-SIDEBAR`, `HUB-01`).
+
+**Hai bề mặt test** (`surface_type`, quyết định ở **cấp test-target** tại Step 00 — KHÔNG per-unit):
+- `ui` — **target có ≥1 màn (`SCR-*`/`WGT-*`)** → E2E **tích hợp đi qua màn** (per-screen loop, oracle UI-first). **Mọi unit BE (HUB/MPF/INT/PMT-EXT…) là BACKEND của màn**, verify bằng oracle API/DB nhúng trong testcase của màn (Background — như cũ). BE **KHÔNG** tách thành bề mặt riêng, KHÔNG đứng riêng trong thứ tự E2E. → **hành vi sinh testcase SLICE giữ nguyên như trước khi có nhánh service.**
+- `service` — **target KHÔNG có màn nào** (unit `HUB/MPF/INT` đứng riêng, hoặc slice thuần BE) → per-operation loop, oracle API-first `api/db/msg/log`, test-design từ error catalog / state machine / idempotency / resilience ([service_surface_rules.md](./principles/service_surface_rules.md)). KHÔNG cần `ui_schema`; qa-robot sinh `RequestsLibrary` vẫn theo POM.
+
+→ **"Không có giao diện thì dùng được không": CÓ** — chạy skill trên chính unit BE đó (target no-UI → `service`). **Có giao diện thì tích hợp đi qua màn như cũ.** 1 lần chạy = 1 target = 1 `surface_type` (không trộn).
+
+**3 lane chạy** (`run_mode`, xem [run_mode_rules.md](./principles/run_mode_rules.md)): `full` (default, 4 HITL gate, governance) · `batch` (2 gate, auto-proceed, lặp nhanh) · `delta` (entry tắt khi 3 artifact đã tồn tại — chỉ patch phần đổi). Mọi lane dùng **Context Ledger** load-once để scoped-reload, chống drift trên slice lớn. Iron Rules + Sync Invariant enforce ở mọi lane.
+
+Đọc đầy đủ và tuân theo: `./workflow.md`

package/skills/NTAPP/.agent/skills/NTAPP-qa-generate-testcase/agents/agent_generate_manual_testcase.md

@@ -0,0 +1,27 @@
+# SYSTEM INSTRUCTION: SENIOR QA ENGINEER (GENERATE)
+
+## [B] - BACKGROUND (Bối Cảnh)
+Bạn là một Senior QA Engineer chuyên nghiệp. Sản phẩm phần mềm chỉ được phép nghiệm thu đưa vào Stage 5 khi vượt qua được bộ kịch bản kiểm thử (KBKT) hệ thống/E2E chặt chẽ, chi tiết và có độ bao phủ 100% logic/giao diện do bạn thiết kế.
+
+## [M] - MISSION (Sứ Mệnh)
+Theo `input_type` đã detect ở Step 00:
+- **lane `slice`:** Tiêu thụ file mô tả **SLICE (`{slices_root}/{id}-*.md`)** để xác định danh sách các units tham gia.
+- **lane `unit`:** đối tượng là MỘT đơn vị đứng riêng `{id}` (HUB/WGT/SCR/MPF…) — bỏ qua bước đọc file SLICE.
+
+Sau đó đọc **file thiết kế chi tiết `{unit}_detailed_design.md`** (lane `unit`: chính `{id}_detailed_design.md`; bỏ phần Đảm bảo chất lượng / Kiểm thử) để xây dựng tài liệu kịch bản kiểm thử E2E độc lập tại **`{qa_artifacts}/{id}/{id}_detailed_test_manual_testcase.md`** (path resolve từ config, KHÔNG hardcode — theo R6).
+## [A] - ACTIONS & RULES (Hành Động & Quy Tắc Thiết Kế)
+
+### 1. Áp Dụng Quy Tắc Hệ Thống (Rules & Compliance):
+Bạn cần đọc, tham chiếu và áp dụng các tài liệu quy tắc sau đây trong suốt quá trình viết kịch bản kiểm thử:
+- **Nguyên tắc bất biến và chống mẫu:** Tuân thủ [ntapp-core-compliance.md](../references/kbkt-generation/00-core/ntapp-core-compliance.md) (Quy tắc Zero-Summarization, Zero-Fabrication, Traceability, và các quy tắc chống mẫu).
+- **Kỹ thuật thiết kế kịch bản:** Áp dụng các kỹ thuật thiết kế test case (EP, BVA, Decision Tables, State Transition, Error Guessing) được quy định tại [test-design-techniques-rule.md](../references/kbkt-generation/00-core/test-design-techniques-rule.md) và đảm bảo không có ảo tưởng dữ liệu theo [no-hallucination-rule.md](../references/kbkt-generation/00-core/no-hallucination-rule.md).
+- **Load Rule đặc thù — theo R1:** Trước khi viết kịch bản cho bất kỳ control nào, thực hiện Rule Mapping và đọc file rule tương ứng trong `references/kbkt-generation/`. Xem chi tiết tại [Iron Rules R1](../principles/iron_rules.md).
+- **Theo `surface_type` (Step 00):** bề mặt **`ui`** → thiết kế theo control màn hình (rule `01-ui`/`02-input`/`03-selection`...). Bề mặt **`service`** (no-UI: HUB/MPF/INT — API/service/job/consumer) → thiết kế theo operation/hợp đồng ([service_surface_rules.md](../principles/service_surface_rules.md)): request-validation tầng payload + `10-be` + error catalog + state machine + idempotency; oracle `api/db/msg/log` (KHÔNG `ui`).
+- **Không tóm tắt rule (Exhaustive Rule Expansion):** Không tóm tắt hay gộp các testcase được quy định trong các file Rule (ví dụ: maxlength-rule.md). Nếu một Rule liệt kê 6 trường hợp kiểm thử cho một control (ví dụ: N-1, N, N+1...), bạn phải sinh đủ số lượng kịch bản kiểm thử độc lập tương ứng trong bảng 11 cột.
+
+### 2. Xây Dựng Cấu Trúc Tài Liệu Đầy Đủ:
+- Nạp và sử dụng nguyên vẹn khung cấu trúc trong file `../references/templates/slice_testcase_table_template.md` (Mục 5.0 → 5.4 + **5.6 Coverage Debt Ledger**; KHÔNG còn 5.5 charter) làm sườn tài liệu đầu ra.
+- Tuân thủ toàn bộ các quy tắc chi tiết về cách viết, định dạng bảng, và phân bổ kịch bản được quy định chặt chẽ tại `../references/kbkt-generation/00-core/kbkt-format-rule.md`.
+
+## [D] - DELIVERABLES (Kết Quả Đầu Ra)
+Tạo file Markdown tại đường dẫn: **`{qa_artifacts}/{id}/{id}_detailed_test_manual_testcase.md`** tuân thủ cấu trúc trong template `../references/templates/slice_testcase_table_template.md`.

package/skills/NTAPP/.agent/skills/NTAPP-qa-generate-testcase/principles/automation_contract_rules.md

@@ -0,0 +1,125 @@
+# AUTOMATION CONTRACT RULES — Hợp đồng bàn giao cho Automation (School B)
+
+> **Mục đích:** Định nghĩa **artifact canonical máy-đọc-được** và **tag dictionary** để output của skill này
+> dùng trực tiếp cho automation (qua skill `/ntapp-qa-robot`) thay vì chỉ là tài liệu manual.
+> File này là **nguồn sự thật duy nhất** cho format bàn giao automation. Mọi step/template tham chiếu về đây.
+>
+> **Quan hệ với [iron_rules.md](./iron_rules.md):** Contract này KHÔNG nới lỏng bất kỳ Iron Rule nào (R1 zero-fabrication, R2 zero-summarization, R3 traceability vẫn giữ nguyên). Nó chỉ thêm **lớp emit thứ 2 và thứ 3** bên cạnh markdown.
+
+---
+
+## 1. Triple-Emit Contract (1 nguồn → 3 artifact)
+
+Skill emit **3 artifact từ cùng một tập kịch bản đã chốt**, KHÔNG sinh rời rạc:
+
+| # | Artifact | Vai trò | Người/Máy tiêu thụ |
+|---|---|---|---|
+| 1 | `{id}_testspec.feature` | **CANONICAL** — Gherkin + tags. Nguồn-sự-thật về *what to test* + routing automation | Human BDD review · qa-robot (P3) · Playwright (tương lai) |
+| 2 | `{id}_detailed_test_manual_testcase.md` | **VIEW** render bảng 11 cột — interface chính với `qa-robot` hiện tại + bản QA ký HITL | Manual tester · qa-robot (parse bảng) |
+| 3 | `{id}_fixtures.yaml` | **DATA** máy-đọc: dữ liệu mồi + môi trường + mock (thay Mục 5.3 prose) | qa-robot `test_data_generator` |
+
+**Bất biến đồng bộ (Sync Invariant) — mô hình "1 SỐ GỐC + 2 PHÉP CHIẾU" (CANONICAL — mọi file khác cite về đây):** Mỗi `Scenario`/`Example` trong `.feature` ⇔ đúng 1 dòng bảng markdown **có `@exec:automate` hoặc `@exec:exploratory`** ⇔ cùng `@id:KB-{id}-NN` (`{id}` = ID đầy đủ SLICE/unit, vd `KB-SLICE-06-02` / `KB-WGT-SIDEBAR-02`).
+
+**Số tổng CHỐT ngay ở bước plan; các con số artifact chỉ là PHÂN HOẠCH của số đó theo cột Exec — KHÔNG đếm lại, KHÔNG phải đẳng thức độc lập (CẤM viết "3-way ==").**
+
+- **Số gốc `X`** = tổng case **chốt cụ thể ở Step 02 Math Forcing** (đây là con số cuối cùng, không phải ước lượng; chỉ đổi khi `risk-gated` Step 02b cắt P2, kèm công thức trừ tường minh). `X` gồm **cả** automate + manual + exploratory. "Bước ra số trước, bước sau tuân theo" → từ Step 02b trở đi `X` bất biến; Step 03 BẮT BUỘC ghi đủ `X` dòng, KHÔNG đẻ số mới.
+- **Step 02b KHÔNG đổi tổng `X`** — chỉ **dán nhãn** `Exec` cho từng dòng: mỗi dòng trong `X` mang đúng 1 nhãn → `A`(automate) `+ E`(exploratory) `+ M`(manual) `= X`. `A/E/M` là cách chia đúng `X` dòng đã cố định, KHÔNG phải số mới đếm ra.
+- **Gate gốc (Math Check):** `Y == X`, với `Y` = **tổng** dòng markdown thực ghi (KỂ CẢ manual).
+- **Phép chiếu 1 (feature):** `count(@id distinct trong .feature) == A + E` — chỉ *đếm bao nhiêu dòng route sang* `.feature`.
+- **Phép chiếu 2 (fixtures):** `count(dataset trong fixtures.yaml) == A` (exploratory chỉ ghi `note:`, không dataset; manual ở lại markdown, không sang `.feature`/fixtures).
+
+Hai phép chiếu chỉ *đếm dòng route sang từng file*, KHÔNG định nghĩa lại và KHÔNG bao giờ vượt `X`. Lệch bất kỳ đâu → vi phạm R2, phải sửa (KHÔNG hạ manual, KHÔNG drop @id để "cho khớp").
+
+> **[HARD CHECK — cross-artifact, BẮT BUỘC]** Kiểm phép chiếu 1 bằng cách so CHÉO `.md`↔`.feature`, **KHÔNG** đếm nội bộ `.feature` (`count(Scenario)==count(@id)` là tautology — không thấy khi @id bị drop).
+> **Sàn chống FALSE-PASS (BẮT BUỘC trước khi tin `comm`):** đếm `N_md = số dòng grep được ở phía `.md`` và đối chiếu `N_md == A + E` (số automate+exploratory kỳ vọng từ Step 02b). **`N_md == 0` hoặc `N_md != A+E` → FAIL ngay** (thường do format bảng lệch làm grep trượt) — `comm` rỗng lúc này là rỗng-giả, KHÔNG được coi là PASS. Chỉ khi `N_md == A+E` mới chạy `comm`, và `comm` phải RỖNG:
+> **So trong bộ nhớ, KHÔNG sinh file trung gian.** ⛔ CẤM `<(…)` (process substitution) — trên git-bash Windows nó materialize thành file thật trong `/tmp`, tức ghi rác ra ngoài dự án.
+> ```powershell
+> $md = Select-String -Path '{id}_detailed_test_manual_testcase.md' -Pattern '^\| \*\*(KB-[A-Z0-9-]+)\*\*.*\| (automate|exploratory) \|' |
+>        ForEach-Object { $_.Matches[0].Groups[1].Value } | Sort-Object -Unique
+> $ft = Select-String -Path '{id}_testspec.feature' -Pattern 'KB-[A-Z0-9-]+' -AllMatches |
+>        ForEach-Object { $_.Matches.Value } | Sort-Object -Unique
+> "N_md=$($md.Count)  N_feature=$($ft.Count)"      # N_md phải == A+E trước khi tin kết quả so
+> Compare-Object $md $ft                            # rỗng = khớp; '<=' là @id .feature bỏ sót
+> ```
+> Ra @id nào = dòng `Exec∈{automate,exploratory}` của `.md` bị `.feature` bỏ sót → **DỪNG**, bổ sung 1 Example/Scenario cho mỗi @id (Rebalance §6.1 đổi cấu trúc, KHÔNG giảm @id).
+
+**Nhất quán data E2E (fixtures):** Trong 1 slice, mỗi luồng dùng **một bộ định danh thống nhất** xuyên suốt — giá trị để chọn/tick (lấy từ unit pending/nguồn) PHẢI trùng với giá trị trong payload tạo và giá trị assert ở DB. CẤM ghép sample rời từ phần Dữ liệu (`_detailed_design`) của từng unit khiến lệch `merchantCode`/`subId`/khóa định danh giữa "data hiển thị để thao tác" và "data được tạo/verify". Fixture `scope: e2e` (chạy qua UI) phải đủ field để **drive UI**: filter value (vd `merchantCode`), định danh phần tử để tương tác (vd dòng pending để tick) — không chỉ payload API. Thiếu giá trị thật → `[TBD]` (R1), KHÔNG lấy bừa sample của unit khác.
+
+**Dynamic Binding (field Runtime-dependent):** Field Loại 1 (FK/lookup) và Loại 2 (unique) theo [dynamic_data_rules.md](./dynamic_data_rules.md) KHÔNG hardcode — khai báo trong `overrides` bằng `$db.query(<source_id>: SELECT ...)` (chỉ SELECT) · `$seed.create(<source_id>: <operation>)` · `$uuid` · `$timestamp(format)`. `<source_id>` phải có trong `{qa_artifacts}/data_sources.yaml`. Không xác định được nguồn → `[UNRESOLVED-BACKEND]` + `note:`, không bịa.
+
+**Ví dụ nhận diện nhanh (để KHÔNG bỏ sót khi viết fixtures.yaml):** subId/subSystem của 1 dòng lấy từ danh sách trả về bởi unit khác (vd fan-out pending) là Loại 1, PHẢI dùng $db.query/$seed.create, KHÔNG được viết cứng kiểu "PMT-2026-00451". merchantCode/mã dùng làm điều kiện filter để tìm bản ghi có sẵn cũng là Loại 1. ULID/PK do backend tự sinh (vd compositeId trả về sau POST) thì KHÔNG cần fixture, chỉ capture runtime. Field tự do do Tester gõ (tên hồ sơ, mô tả, ghi chú) là Loại 3, viết tĩnh bình thường, KHÔNG áp dụng mục này.
+
+**Inline-value vs `fixture_ref` (BẮT BUỘC — chống indirection khó đọc):** Đọc 1 dòng dataset phải thấy NGAY dữ liệu của nó, không phải nhảy lên mục `fixtures:` tra. Quyết định theo bảng:
+
+| Data của dataset là… | Cách ghi | Ví dụ |
+|---|---|---|
+| **Loại 3 tĩnh, dùng 1 lần** (validation/BVA/security-input/space-handling — giá trị chính là thứ đang test) | **Ghi thẳng inline** trong `data: {…}` ngay trên dòng dataset. CẤM tách thành fixture tên riêng rồi `fixture_ref`. | `- { id: KB-…-054, data: { name: "<tiếng Việt 100 ký tự>" } }` |
+| **Dùng lại ≥2 dataset** (cùng 1 session, cùng 1 pending fan-out, cùng 1 payload submit) | `fixture_ref: <key>` (+ `overrides:` nếu case này khác chút) | `- { id: KB-…-203, fixture_ref: valid_compose_minimal }` |
+| **Payload/seed nhiều field phức tạp** (dài, lồng mảng — inline sẽ vỡ 1 dòng) | `fixture_ref: <key>` | `fixture_ref: pending_all_sources` |
+| **Loại 1/2 động** (FK/filter/unique — theo Dynamic Binding ở trên) | `fixture_ref: <key>` chứa `$db.query/$seed.*`, hoặc inline `data:` mang trực tiếp marker `$…` | `data: { subId: "$db.query(pmt_pending: …)" }` |
+
+Nguyên tắc 1 câu: **fixture tên riêng chỉ tồn tại khi được ≥2 dataset dùng chung, hoặc data quá phức tạp/động để inline.** Fixture chỉ-dùng-1-lần cho giá trị tĩnh = indirection thừa → nội hoá (inline) vào chính dòng dataset. Điều này KHÔNG nới lỏng R1 (giá trị vẫn phải truy về phần Dữ liệu của `_detailed_design`/audit) — chỉ đổi *nơi ghi* giá trị, không đổi *nguồn* giá trị.
+
+> **`data:` phải máy-đọc-được để qa-robot bind trực tiếp:** keyed theo TÊN FIELD + giá trị thật (`data: { merchantCode: "doi@tac#1" }`). CẤM prose gộp 1 khóa `input:` và CẤM placeholder mô tả (`"<100 ký tự>"`); chuỗi biên dài dùng `"a"×255` hoặc giá trị thật. Prose/placeholder → robot không bind được, buộc hardcode (vỡ R8).
+
+---
+
+## 2. Tag Dictionary (taxonomy bắt buộc trên mỗi Scenario)
+
+Mỗi `Scenario` mang đủ các tag dưới đây (trừ tag đánh dấu *(optional)*):
+
+| Tag | Giá trị hợp lệ | Ý nghĩa | Nguồn |
+|---|---|---|---|
+| `@<id>` | `@SLICE-06` / `@WGT-SIDEBAR` / `@HUB-01` | SLICE/unit sở hữu | file SLICE / WBS |
+| `@scr:<unit_id>` *(bề mặt `ui`)* | `@scr:SCR-COMPOSE` | Màn hình Action chứa case | unit `[Action]` |
+| `@svc:<unit_id>` *(bề mặt `service`)* | `@svc:HUB-01` | Operation/endpoint chứa case (dùng THAY `@scr` khi no-UI) | unit `[Operation]` |
+| `@id:<KB-id>` | `@id:KB-SLICE-06-02` | Khóa 1-1 với dòng markdown | running ID |
+| `@block` | `ui` \| `functional` \| `security` \| `contract` | Khối testcase. *(ui)* 3 khối `ui`/`functional`/`security` · *(service)* 3 khối `contract` (Hợp đồng & Request Validation) / `functional` (Nghiệp vụ & E2E) / `security` — KHÔNG dùng `ui` cho service | cấu trúc 3 khối |
+| `@tech` | `EP` \| `BVA` \| `DT` \| `ST` \| `EG` | Kỹ thuật thiết kế test | rule file `@tech` |
+| `@rule:<slug>` | `@rule:textbox-base` | Truy vết về file kbkt-generation | bảng Mapping Rule (Step 02) |
+| `@risk` | `P0` \| `P1` \| `P2` | Risk tier (= cột "Độ ưu tiên") | [risk_based_allocation_rules.md](./risk_based_allocation_rules.md) |
+| `@exec` | `automate` \| `manual` \| `exploratory` | **Cổng automation** | risk allocation (Step 02b) |
+| `@target` *(chỉ khi `@exec:automate`)* | `robot` \| `playwright` | Đích sinh code | mặc định `robot` |
+| `@oracle` | `ui` `api` `db` `log` `msg` (đa giá trị) | Tầng kiểm chứng assert được (`msg` = event/message phát ra — bề mặt service) | Expected result đa lớp |
+| `@manual-verify` *(optional)* | — | Đánh dấu tầng oracle phải verify bằng người (automation KHÔNG được giả vờ phủ) | — |
+| `@regression` *(optional)* | — | Thuộc bộ regression guard (P5) | — |
+
+**Quy tắc `@exec` (cổng quyết định automation):**
+- `automate` → có ≥1 `@oracle` tự động assert được (ui/api/db) **và** không phụ thuộc phán đoán người. Bắt buộc có `@target`.
+- `manual` → oracle chủ yếu visual/UX/khó-tự-động (vd zoom, responsive, focus order) → ở lại markdown view, KHÔNG sang automation.
+- `exploratory` → **mặc định KHÔNG dùng** và **KHÔNG tạo charter/section riêng**. Mọi rủi ro bất định (timing/đồng thời/phiên/spec `[TBD]`/UX mới) phải phân tích ra oracle rồi viết thành **case scripted (`automate`/`manual`) trong KHỐI 2/3** (dòng `[BR]` nếu expected neo theo contract canonical mà code chưa đạt) — theo [risk_based_allocation_rules §3](./risk_based_allocation_rules.md) + [explore_and_consistency_rules §5](./explore_and_consistency_rules.md). CHỈ giữ `exploratory` cho quan sát thẩm mỹ thuần không assert được (so màu/spacing), nằm trong KHỐI 1 UI.
+
+**Quy tắc `@oracle` (theo bề mặt):**
+- *Bề mặt `ui` — UI-first:* test được/quan sát được qua UI thì BẮT BUỘC có `@oracle:ui` + drive qua `@scr` (cột Công cụ `Chrome`). API-only (bỏ `@scr`, Công cụ `Postman`) CHỈ khi hành vi không có mặt trên UI.
+- *Bề mặt `service` — API-first:* dùng `@svc` (không `@scr`), Công cụ `Postman`/`RequestsLibrary`. BẮT BUỘC `@oracle:api` (hoặc `@oracle:db`/`@oracle:msg` khi job/consumer không trả HTTP); **CẤM `@oracle:ui`**. `@oracle:msg` = event/message phát ra outbox/topic. Chi tiết: [service_surface_rules.md §3](./service_surface_rules.md).
+
+Chi tiết chấm risk/exec: [risk_based_allocation_rules.md §3](./risk_based_allocation_rules.md).
+
+**Quy tắc `@target`:** mặc định `robot` (consumer sẵn có). Chỉ đặt `playwright` khi project khai báo `automation_target: playwright` ở `.bmm-config.yaml`.
+
+---
+
+## 3. Cấu trúc Scenario chuẩn (Gherkin)
+
+- **1 `Scenario` tường minh = 1 dòng testcase (per-case — CẤM gom).** Mỗi case là 1 block `Scenario` riêng, đọc đứng một mình là hiểu đủ input→expected. **CẤM `Scenario Outline` + `Examples`** — kể cả BVA/EP nhiều giá trị cùng-một-logic: viết N `Scenario` riêng, mỗi cái 1 `@id`. Chống trùng-lặp KHÔNG bằng cách gom scenario mà bằng cách **để giá trị input ở `fixtures.yaml`** (mỗi case 1 dataset) — `.feature` chỉ tham chiếu qua nhãn/`<fixture_ref>`, phần thân N scenario khác nhau ở giá trị được nạp, không copy-paste literal. Lý do: giữ map 1-1 (R2) tường minh, fail chỉ đúng case, dễ skip/annotate lẻ.
+- `Given/When/Then` mô tả hành động vật lý tuần tự — **không** chứa selector/endpoint-URL cứng. *(ui)* chỉ dùng **Nhãn hiển thị UI** (selector do qa-robot lấy từ `ui_schema_{id}.json`) · *(service)* mô tả gọi request theo tên operation + nhận response + quan sát side-effect (endpoint path lấy từ Contract Map/DD, không hardcode payload dài — dùng `<fixture_ref>`).
+- Mỗi tầng oracle = 1 dòng `Then`/`And`, prefix theo thứ tự ưu tiên: *(ui)* `UI:` → `API:` → `DB:` → `Log:` · *(service)* `API:` → `DB:` → `MSG:` → `Log:` — khớp đúng thứ tự Expected result của markdown.
+- Tầng oracle không tự động được → gắn comment `# @manual-verify` ở cuối dòng `Then` đó.
+- Data lấy từ fixtures: tham chiếu `<fixture_ref>` (vd `<valid_compose_payload>`), KHÔNG hardcode payload dài trong feature.
+
+Khung mẫu đầy đủ: [`references/templates/testspec_feature_template.feature`](../references/templates/testspec_feature_template.feature).
+
+---
+
+## 4. Ranh giới với qa-robot (không lấn việc)
+
+- Skill này **KHÔNG sinh selector/keyword, KHÔNG sinh Robot code**. Chỉ sinh *what to test* (feature) + *data* (fixtures) + *view* (markdown).
+- `qa-robot` chịu trách nhiệm: *(ui)* selector từ `ui_schema`, POM Selenium, execute, self-heal · *(service)* keyword `RequestsLibrary` **vẫn theo POM** (mỗi endpoint/operation = 1 "service object" đóng vai page-object), execute, self-heal.
+- Vì vậy: *(ui)* thiếu `ui_schema_{id}.json` **không** chặn skill này (việc của qa-robot) — nhưng PHẢI cảnh báo ở Mục 5.3/round-trip rằng automation sẽ chặn nếu thiếu · *(service)* **KHÔNG cần `ui_schema`**; thay bằng `automation_prereq`: `base_url` + `auth` + `api_contract` + `mocks` (xem [service_surface_rules.md §5](./service_surface_rules.md)).
+
+---
+
+## 5. Backward-compatibility
+
+- Markdown view giữ nguyên bảng 3-khối + Mục 5.x để QA hiện tại ký HITL không gãy. Thêm **đúng 1 cột `Exec`** (xem table template).
+- `.feature` và `fixtures.yaml` là **mới, không thay thế** markdown. Nếu config `emit_automation: false` (Layer 3) → skill chỉ emit markdown như cũ (chế độ legacy).