@relipa/ai-flow-kit 0.1.2 → 0.1.4-beta.0

package/custom/skills/ba-skills/skill-ba-ve-luong-mermaid-v1.md

@@ -0,0 +1,35 @@
+# Skill: Vẽ luồng hoạt động bằng Mermaid (Mermaid Charting) - Phiên bản v1
+
+## 1. Mục đích (Purpose)
+Kỹ năng này giúp BA chuyển đổi các đặc tả luồng nghiệp vụ văn bản (Main flow, Alternative flows, Exception flows) thành một sơ đồ hoạt động trực quan (Activity Diagram) sử dụng mã nguồn Mermaid. Sơ đồ này giúp lập trình viên nắm bắt luồng đi tổng thể của hệ thống một cách tức thì và giúp kiểm thử viên xác minh các nhánh rẽ của kịch bản.
+
+## 2. Kiến thức cần có (Prerequisite Knowledge)
+- **Cấu trúc biểu đồ Flowchart trong Mermaid:**
+  - Khai báo hướng biểu đồ: Dùng `graph TD` (Top-Down - từ trên xuống) hoặc `graph LR` (Left-to-Right - từ trái sang phải). Đối với quy trình nghiệp vụ phần mềm, khuyến nghị dùng `graph TD`.
+  - **Ký pháp hình khối chuẩn:**
+    - Khởi đầu/Kết thúc (Start/End): Dùng hình elip/bo góc `([Bắt đầu / Trang chủ])`.
+    - Hành động/Xử lý (Process/Action): Dùng hình chữ nhật `[Hành động của Actor hoặc xử lý của System]`.
+    - Điểm quyết định/Rẽ nhánh (Decision): Dùng hình thoi `{Điều kiện kiểm tra}`.
+    - Hiển thị thông tin/Thông báo lỗi: Dùng hình chữ nhật bo góc hoặc hình bình hành.
+  - **Liên kết nhánh (Arrows & Labels):** Sử dụng `-->|Nhãn nhánh rẽ|` để nối các khối và đặt tên cho các đường đi (ví dụ: `-->|Hợp lệ|`, `-->|Không hợp lệ|`).
+
+## 3. Quy trình thực hiện (Step-by-step Process)
+- **Bước 1: Xác định điểm bắt đầu và kết thúc:**
+  Điểm bắt đầu thường là trigger của Use Case (ví dụ: Người dùng nhấn nút mở trang, hoặc vào link URL). Điểm kết thúc là các Post-conditions (thành công hoặc dừng luồng lỗi).
+- **Bước 2: Vẽ luồng chính trước (Happy Path):**
+  Nối các bước xử lý bình thường từ đầu đến cuối mà không có lỗi xảy ra. Sử dụng các mũi tên thẳng xuống.
+- **Bước 3: Thêm các điểm rẽ nhánh (Alternative/Exception branches):**
+  Tại các bước hệ thống kiểm tra thông tin, chèn các khối hình thoi `{Điều kiện}`. Vẽ nhánh thành công tiếp tục đi xuống luồng chính, và các nhánh lỗi quay ngược lại form nhập liệu hoặc đi tới kết thúc lỗi.
+- **Bước 4: Tinh chỉnh cú pháp Mermaid để tránh lỗi render:**
+  - Tránh sử dụng các ký tự đặc biệt như ngoặc đơn `()`, ngoặc vuông `[]`, dấu nháy kép bên trong nhãn của nút bấm trừ khi nhãn được bọc hoàn toàn trong dấu nháy kép. Ví dụ đúng: `A["Hiển thị thông báo (Lỗi 404)"]`.
+  - Đảm bảo mỗi khối có ID định danh độc nhất (ví dụ: `A`, `B`, `C`, `Step1`, `Check1`).
+
+## 4. Checklist kiểm tra (Checklist for Verification)
+- [ ] Biểu đồ có bắt đầu bằng `graph TD` không?
+- [ ] Tất cả các điểm quyết định (các câu lệnh IF/THEN hoặc kiểm tra hợp lệ) có sử dụng hình thoi `{}` không?
+- [ ] Các nhánh đi ra khỏi hình thoi có được gán nhãn rõ ràng (ví dụ: Đúng/Sai, Có/Không) không?
+- [ ] Có nhánh lỗi nào bị "treo" (không dẫn đi đâu) không? Mọi nhánh phải dẫn về một bước thao tác tiếp theo hoặc kết thúc luồng.
+- [ ] Nhãn của các khối chứa ký tự đặc biệt đã được bọc trong dấu nháy kép `""` chưa để tránh lỗi biên dịch Mermaid?
+
+## 5. Output mong đợi (Expected Output)
+- Một đoạn mã nguồn Mermaid hợp lệ, nằm trong khối ```mermaid và được nhúng trực tiếp vào Mục 4 của tài liệu Đặc tả Use Case.

package/custom/skills/ba-skills/skill-ba-viet-spec-uc-v1.md

@@ -0,0 +1,38 @@
+# Skill: Viết Đặc tả Use Case (Use Case Specification) - Phiên bản v1
+
+## 1. Mục đích (Purpose)
+Kỹ năng này giúp BA chuyển hóa toàn bộ các thông tin yêu cầu nghiệp vụ đã được thống nhất sau quá trình Q&A thành một tài liệu Đặc tả Use Case (Use Case Spec) hoàn chỉnh. Tài liệu này là "nguồn sự thật duy nhất" (Single Source of Truth) giúp đội ngũ Dev lập trình chính xác và đội ngũ Test thiết kế toàn bộ kịch bản kiểm thử (Test Cases/Scripts).
+
+## 2. Kiến thức cần có (Prerequisite Knowledge)
+- **Cấu trúc Use Case chuẩn:** Hiểu rõ các thành phần của một Use Case Spec bao gồm: Thông tin chung, Mô tả màn hình, Mô tả thành phần UI, Luồng hoạt động (Activity Flow) và Quy tắc nghiệp vụ (Business Rules).
+- **Cách mô tả Luồng xử lý (Flow):** 
+  - Phân biệt hành động của Tác nhân (Actor Action) và phản hồi của Hệ thống (System Response).
+  - Trình bày mạch lạc theo các bước đánh số thứ tự (1, 2, 3...).
+- **Tính liên kết logic:** Đảm bảo mã lỗi, thông báo lỗi trong Business Rules phải khớp với các mô tả thành phần UI và vị trí hiển thị lỗi trên Prototype.
+
+## 3. Quy trình thực hiện (Step-by-step Process)
+- **Bước 1: Điền thông tin chung (General Information):**
+  Xác định chính xác Function Name, Description, Actors, Trigger, Pre-Conditions, Main Flow tóm tắt, và Post-Conditions.
+- **Bước 2: Tích hợp thiết kế màn hình:**
+  Nhúng mã nguồn HTML/CSS (hoặc đường dẫn liên kết) của màn hình thiết kế tương ứng vào mục Screen Description.
+- **Bước 3: Mô tả các thành phần UI (UI Components):**
+  Lập bảng chi tiết tất cả các control trên giao diện (các input fields, buttons, links, labels). Đối với mỗi thành phần, cần làm rõ:
+    - Kiểu dữ liệu nhập vào (Text, Number, Date...).
+    - Độ dài giới hạn (Min/Max length).
+    - Tính bắt buộc (Mandatory: Yes/No).
+    - Giá trị mặc định (Default Value).
+    - Mô tả hành vi (Description).
+- **Bước 4: Thiết kế sơ đồ Mermaid (Activity Flow):**
+  Áp dụng kỹ năng `@skill-ba-ve-luong-mermaid-v1.md` để vẽ và nhúng biểu đồ Mermaid.
+- **Bước 5: Đặc tả Business Rules (Quy tắc nghiệp vụ):**
+  Áp dụng kỹ năng `@skill-ba-xay-dung-business-rules-v1.md` để viết chi tiết các điều kiện kiểm tra, validation logic và câu thông báo lỗi đi kèm.
+
+## 4. Checklist kiểm tra (Checklist for Verification)
+- [ ] Luồng đi (Flow) có mô tả rõ ràng sự tương tác qua lại giữa Actor và System chưa?
+- [ ] Bảng mô tả UI Components có bị bỏ sót bất kỳ thành phần nào trên prototype HTML không?
+- [ ] Các Business Rules (BR) đã được đánh mã số rõ ràng (BR1, BR2, BR3...) để dễ tham chiếu chưa?
+- [ ] Mọi trường hợp báo lỗi đều có câu thông báo lỗi (Error message) đi kèm chi tiết chưa?
+- [ ] Tài liệu có sử dụng định dạng markdown chuẩn và cấu trúc thống nhất theo mẫu `@skill-ba-template-uc-v1.md` chưa?
+
+## 5. Output mong đợi (Expected Output)
+- Một tài liệu đặc tả Use Case hoàn chỉnh định dạng markdown, đặt tên theo chuẩn: `Tên chức năng_UC.md` trong thư mục `TÀI LIỆU/output/UC/`.

package/custom/skills/ba-skills/skill-ba-xay-dung-business-rules-v1.md

@@ -0,0 +1,39 @@
+# Skill: Phân tích và Xây dựng Business Rules (Quy tắc nghiệp vụ) - Phiên bản v1
+
+## 1. Mục đích (Purpose)
+Kỹ năng này giúp BA bóc tách, chuẩn hóa và đặc tả các quy tắc nghiệp vụ (Business Rules - BR) của hệ thống một cách chặt chẽ nhất. Các quy tắc nghiệp vụ được định nghĩa chi tiết tại đây sẽ là căn cứ trực tiếp để lập trình viên viết code logic (backend/frontend) và kiểm thử viên viết các kịch bản kiểm thử (Test Cases), đảm bảo bao phủ toàn bộ các trường hợp biên và ngoại lệ.
+
+## 2. Kiến thức cần có (Prerequisite Knowledge)
+- **Các loại Business Rules phổ biến:**
+  - *Validation Rules (Quy tắc kiểm tra dữ liệu):* Bao gồm kiểm tra rỗng (Required), kiểm tra định dạng (Format - Regex, Email, số điện thoại), kiểm tra độ dài/giới hạn (Length/Range), và kiểm tra ràng buộc chéo giữa các trường (Dependency validation - ví dụ: Ngày kết thúc phải sau Ngày bắt đầu).
+  - *Processing/Calculation Rules (Quy tắc xử lý và tính toán):* Các công thức toán học, thuật toán phân chia logic (ví dụ: công thức tính thuế, logic tính điểm thưởng).
+  - *Database/Saving Rules (Quy tắc lưu trữ và ghi nhận dữ liệu):* Các hành động xảy ra trong DB sau khi nghiệp vụ hoàn thành (ví dụ: lưu vào bảng log hệ thống, cập nhật trạng thái đơn hàng từ Draft sang Pending).
+  - *Authorization & Security Rules (Quy tắc phân quyền và bảo mật):* Ai được phép thao tác? Khi nào tài khoản bị khóa?
+- **Cách phân tích Giá trị Biên (Boundary Value Analysis) & Phân vùng tương đương (Equivalence Partitioning):** Tư duy chia dữ liệu để phát hiện điểm thiếu logic (ví dụ: Quy định nhập từ 3-20 ký tự thì phải xác định rõ các biên 2, 3, 20, 21 ký tự sẽ xử lý thế nào).
+
+## 3. Quy trình thực hiện (Step-by-step Process)
+- **Bước 1: Xác định các điểm cần áp dụng Quy tắc nghiệp vụ:**
+  Duyệt qua danh sách các trường thông tin (Inputs) và các nút thao tác chính (Actions) trên giao diện.
+- **Bước 2: Phân loại và phân nhóm các Business Rules:**
+  Đặt mã định danh duy nhất cho từng quy tắc dưới định dạng: `[BR<Nhóm>.<Số thứ tự>]`
+  - Nhóm 1: Validation (ví dụ: `[BR1.1]`, `[BR1.2]`)
+  - Nhóm 2: Processing & Saving (ví dụ: `[BR2.1]`)
+  - Nhóm 3: Authorization & Security (ví dụ: `[BR3.1]`)
+- **Bước 3: Chi tiết hóa từng quy tắc nghiệp vụ:**
+  Mỗi quy tắc cần ghi rõ:
+    - **Điều kiện kích hoạt (Trigger/Condition):** Khi người dùng làm gì hoặc khi dữ liệu đạt trạng thái nào?
+    - **Logic kiểm tra (Logic/Calculation):** Hệ thống so sánh, tính toán như thế nào?
+    - **Kết quả trả về khi kiểm tra thất bại (Failure Action):** Hệ thống hiển thị câu thông báo lỗi (Error message) cụ thể là gì? Ở vị trí nào? Màu sắc ra sao?
+    - **Kết quả trả về khi kiểm tra thành công (Success Action):** Hệ thống lưu trữ vào bảng nào? Chuyển hướng đi đâu?
+- **Bước 4: Rà soát tính đầy đủ cùng Tester:**
+  Đảm bảo mọi lỗi phát sinh đều có thông báo lỗi tương ứng và không bị chồng chéo logic.
+
+## 4. Checklist kiểm tra (Checklist for Verification)
+- [ ] Tất cả các trường dữ liệu bắt buộc (Mandatory fields) đã có quy tắc xử lý khi để trống chưa?
+- [ ] Đã chỉ định chính xác vị trí hiển thị và nội dung chi tiết của các thông báo lỗi chưa? (Ví dụ: Hiển thị inline ngay dưới ô nhập liệu hay hiển thị popup cảnh báo?)
+- [ ] Đã làm rõ logic đối với các ký tự đặc biệt, khoảng trắng (space) và chữ hoa/chữ thường chưa?
+- [ ] Quy tắc lưu trữ đã chỉ ra các bảng cơ sở dữ liệu bị tác động trực tiếp chưa?
+- [ ] Phân quyền thao tác cho từng tác nhân (Actor) đã được mô tả rõ chưa?
+
+## 5. Output mong đợi (Expected Output)
+- Mục 5 (Business rules) của tài liệu đặc tả Use Case chứa danh sách các quy tắc nghiệp vụ được cấu trúc hóa rõ ràng, ký hiệu hóa khoa học theo chuẩn `[BR...]`, có kèm theo nội dung text thông báo lỗi chi tiết.

package/custom/skills/coverage-check/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: coverage-check
+description: Gate 2 Phase 2d — Apply action items từ review-report (Phase 2c), generate coverage matrix (requirement→TC mapping), tạo final testcase set hoàn chỉnh, và trigger automation-testing để sinh Playwright scripts. Chạy sau Phase 2c APPROVED.
+keywords: gate2, phase2d, coverage, matrix, final testcase, playwright, scripts, traceability
+---
+
+# Coverage Check & Final Output — Gate 2 Phase 2d
+
+> **GATE 2 PHASE 2d: Chỉ chạy sau Phase 2c (Review & Optimize) đã được APPROVED.**
+>
+> Phase này là giai đoạn cuối của Gate 2: apply tất cả sửa đổi, generate coverage matrix, xuất final TC set, và sinh Playwright scripts.
+
+---
+
+## Conditions to Enter Phase 2d
+
+- ✅ Phase 2c APPROVED — `test-plan/review-report.md` đã được TESTER approve
+- ✅ Files tồn tại: `test-plan/test-cases/`, `test-plan/review-report.md`, `test-plan/test-analysis.md`
+
+---
+
+## Checklist trước khi output (bắt buộc)
+
+Trước khi xuất final TC set, kiểm tra:
+
+- [ ] Đã xóa duplicate TCs (từ review-report.md Section 1)
+- [ ] Đã sửa TC có vấn đề (từ review-report.md Section 2)
+- [ ] Đã tách/gộp TCs cần optimize (từ review-report.md Section 3)
+- [ ] Đã thêm TC còn thiếu (từ review-report.md Section 4)
+- [ ] Đã bổ sung Accessibility/Compatibility cases (từ review-report.md Section 6)
+- [ ] 100% requirements trong scope được cover bởi ít nhất 1 TC
+
+---
+
+## Step 1: Apply Action Items từ Phase 2c
+
+Đọc `test-plan/review-report.md` và apply từng action item từ **Section 7 — Danh sách cần sửa**:
+
+| Loại action | Cách thực hiện |
+|-------------|---------------|
+| Xóa duplicate | Remove TC file hoặc xóa row khỏi testcase table |
+| Sửa TC có vấn đề | Edit cột Scenario/Steps/Expected Result/Preconditions cụ thể |
+| Tách TC dài | Split thành 2 TC riêng với TC_ID mới |
+| Gộp TC | Merge nội dung, giữ TC_ID của TC đầu tiên |
+| Thêm TC mới | Tạo TC mới với TC_ID tiếp theo trong chuỗi |
+
+Ghi lại những gì đã apply:
+
+```markdown
+## Action Items Applied
+
+| # | Action | TC_ID | Vấn đề | Priority | Status |
+|---|--------|-------|--------|---------|--------|
+| 1 | Sửa Expected Result | AD10_005 | Expected Result mơ hồ | High | ✅ Done |
+| 2 | Thêm Precondition | AD10_007 | Thiếu precondition | High | ✅ Done |
+| 3 | Thêm TC mới | AD10_012 | Thiếu screen reader case | Medium | ✅ Done |
+| 4 | Xóa duplicate | AD10_003 | Duplicate với AD10_001 | High | ✅ Done |
+```
+
+---
+
+## Step 2: Generate Coverage Matrix
+
+So sánh requirements từ `test-plan/test-analysis.md` với TC set hiện tại:
+
+**Format coverage matrix:**
+
+```markdown
+## Coverage Matrix — [Feature Name]
+
+| # | Requirement/Acceptance Criteria | Có TC cover? | TC IDs | % |
+|---|--------------------------------|-------------|--------|---|
+| AC1 | User đăng nhập thành công với credentials hợp lệ | ✅ | AD10_001 | 100% |
+| AC2 | Hiển thị error khi credentials sai | ✅ | AD10_002 | 100% |
+| AC3 | Validate required fields | ✅ | AD10_003, AD10_004 | 100% |
+| BR1 | Account bị lock sau 5 lần sai | ✅ | AD10_008 | 100% |
+| WCAG | Keyboard navigation qua form | ✅ | AD10_006 | 100% |
+| COMPAT | Hoạt động trên Firefox | ⚠️ | AD10_013 (pending) | 0% |
+
+**Summary:**
+- Total requirements/AC: [N]
+- Covered: [N] ([N]%)
+- Not covered: [N] ([N]%)
+```
+
+**Nếu coverage < 100%** → tạo TC mới để cover trước khi tiếp tục.
+
+---
+
+## Step 3: Export Final Testcase Set
+
+Consolidate toàn bộ TCs (sau khi apply actions) vào **1 file duy nhất**:
+
+Lưu `test-plan/test-cases/final-testcases.md`:
+
+```markdown
+# Final Test Cases — [Feature Name]
+
+**Version:** 2.0 (after Phase 2d) | **Date:** [YYYY-MM-DD] | **Status:** Final
+
+| TC_ID | Scenario | Preconditions | Test Steps | Test Data | Expected Result | Severity | Type |
+|-------|----------|---------------|------------|-----------|----------------|----------|------|
+| AD10_001 | Đăng nhập thành công | App chạy. User tồn tại. | 1. Mở /login 2. Nhập email hợp lệ 3. Nhập password hợp lệ 4. Click "Đăng nhập" | user@example.com / Password123! | Redirect tới /dashboard. Hiển thị "Chào [Tên user]" ở header. | Critical | Auto |
+| AD10_002 | Error khi sai password | App chạy. User tồn tại. | 1. Mở /login 2. Nhập email hợp lệ 3. Nhập password SAI 4. Click "Đăng nhập" | user@example.com / WrongPass | Error "Sai email hoặc mật khẩu" hiển thị. URL vẫn /login. | High | Auto |
+| ... | ... | ... | ... | ... | ... | ... | ... |
+```
+
+**Cột Type:**
+- `Auto` — test case này sẽ có Playwright script
+- `Manual` — test case này cần TESTER test thủ công (UI phức tạp, OTP, physical device)
+
+---
+
+## Step 4: Generate Playwright Scripts (Incremental)
+
+Với tất cả TCs có `Type = Auto` trong `final-testcases.md`:
+
+**Bước 4a — Kiểm tra scripts hiện có:**
+```
+Glob: test-plan/test-scripts/*.spec.ts
+```
+Phân loại mỗi TC_ID:
+- `[NEW]` — chưa có `.spec.ts` tương ứng → cần sinh
+- `[UPDATED]` — đã có `.spec.ts` nhưng TC nằm trong danh sách thay đổi (từ Section 7 review-report.md) → cần regenerate
+- `[SKIP]` — đã có `.spec.ts` và TC không thay đổi → giữ nguyên
+
+**Bước 4b — Invoke `automation-testing` skill** chỉ cho TCs `[NEW]` và `[UPDATED]`:
+
+```
+Sinh Playwright scripts cho:
+[NEW]     AD10_005 — Scenario: ...
+[UPDATED] AD10_002 — Scenario: ... (TC content changed: Expected Result đã sửa)
+Output path: test-plan/test-scripts/
+```
+
+Scripts được lưu tại `test-plan/test-scripts/[TC_ID].spec.ts`:
+
+```
+test-plan/test-scripts/
+├── AD10_001.spec.ts   ← [SKIP] unchanged
+├── AD10_002.spec.ts   ← [UPDATED] regenerated
+├── AD10_003.spec.ts   ← [SKIP] unchanged
+├── AD10_004.spec.ts   ← [SKIP] unchanged
+├── AD10_005.spec.ts   ← [NEW] created
+└── ...
+```
+
+**Traceability mapping:**
+
+```markdown
+## Script Traceability
+
+| TC_ID | Script File | Status | Ghi chú |
+|-------|-------------|--------|---------|
+| AD10_001 | test-plan/test-scripts/AD10_001.spec.ts | ✅ SKIP — unchanged | |
+| AD10_002 | test-plan/test-scripts/AD10_002.spec.ts | ✅ UPDATED | Expected Result sửa |
+| AD10_005 | test-plan/test-scripts/AD10_005.spec.ts | ✅ NEW | |
+| AD10_011 | — | 🔧 Manual (OTP required) | |
+```
+
+---
+
+## Gate 2d Display (Final)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⏸️ GATE 2: TEST PLAN READY
+
+Test cases: [N] total ([N] Auto / [N] Manual)
+Coverage:   [N/N] requirements covered ([N]%)
+Scripts:    [N] Playwright specs ([N] new / [N] updated / [N] skipped unchanged)
+
+Issues resolved:
+  Duplicates removed:  [N]
+  TCs fixed:           [N]
+  TCs added:           [N]
+  TCs split/merged:    [N]
+
+→ Review: test-plan/
+│   ├── test-analysis.md        (Gate 1)
+│   ├── checklist.md            (Phase 2a)
+│   ├── test-plan.md            (Phase 2b)
+│   ├── review-report.md        (Phase 2c)
+│   ├── test-cases/final-testcases.md  (Phase 2d final)
+│   └── test-scripts/*.spec.ts  (Playwright)
+→ Type APPROVED to proceed to Gate 3 (Execution)
+→ Or provide feedback to update
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Sau APPROVED → **tiến sang Gate 3**.
+
+---
+
+## Mandatory Rules
+
+- ❌ **KHÔNG** generate scripts trước khi coverage = 100%
+- ❌ **KHÔNG** bỏ qua bất kỳ action item nào từ review-report.md
+- ✅ **PHẢI** apply TẤT CẢ changes từ Phase 2c trước khi generate coverage matrix
+- ✅ **PHẢI** đạt 100% AC coverage trước khi phase kết thúc
+- ✅ **PHẢI** có traceability mapping (TC_ID → script file)
+- ✅ Scripts **PHẢI** dùng selector từ DOM thật (thông qua automation-testing skill Phase 3)

package/custom/skills/evidence-aggregation/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: evidence-aggregation
+description: Gate 3 — Sau khi Playwright chạy xong, tổ chức screenshots/traces/logs vào thư mục evidence/ theo từng TC, generate result.md per TC, auto-draft bug report cho TCs failed.
+keywords: gate3, evidence, screenshots, playwright, test results, bugs, bug report, pass fail
+---
+
+# Evidence Aggregation — Gate 3
+
+> **Mục đích:** Tổ chức evidence từ Playwright test run vào cấu trúc `evidence/` theo từng TC,
+> và auto-generate draft bug reports cho TCs bị fail.
+>
+> **Khi nào chạy:** Sau `npx playwright test` hoàn thành trong Gate 3.
+
+---
+
+## Input
+
+1. `test-results/results.json` — Playwright JSON report (từ config `reporter: ['json']`)
+2. `test-results/` — thư mục chứa screenshots/traces của Playwright
+3. `playwright-report/` — HTML report
+4. `test-plan/test-cases/final-testcases.md` — danh sách TCs gốc (để lấy metadata)
+
+---
+
+## Step 1: Parse Playwright Results
+
+Đọc `test-results/results.json` và extract:
+
+```json
+{
+  "suites": [
+    {
+      "tests": [
+        {
+          "title": "[AD10_001] Đăng nhập thành công với email và password hợp lệ",
+          "status": "passed",
+          "duration": 1234,
+          "attachments": [
+            { "name": "screenshot", "path": "test-results/..." }
+          ],
+          "errors": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+Từ `title` field: extract TC_ID (format: `[ScreenID]_[NNN]` ở đầu title, trong dấu `[]`).
+
+**Mapping rule:** `"[AD10_001] Đăng nhập thành công với email và password hợp lệ"` → `TC_ID = "AD10_001"`.
+
+---
+
+## Step 2: Tổ chức Evidence theo TC
+
+Với mỗi TC, tạo folder và copy files:
+
+```
+evidence/
+├── AD10_001-dang-nhap-thanh-cong/
+│   ├── step-01-mo-trang-login.png      ← screenshot (nếu có)
+│   ├── step-02-nhap-credentials.png
+│   ├── step-03-ket-qua.png
+│   └── result.md                       ← summary (xem Step 3)
+├── AD10_002-error-sai-password/
+│   ├── failure-screenshot.png
+│   ├── trace.zip                       ← Playwright trace (nếu có)
+│   └── result.md
+└── ...
+```
+
+**Đặt tên folder:** `TC_[ID]-[kebab-case-scenario]` (lowercase, dấu cách thành `-`).
+
+**Copy files từ `test-results/`:**
+- Screenshots: tìm theo TC_ID trong filename hoặc theo test title match
+- Traces: `.zip` files trong `test-results/`
+- Nếu không tìm thấy attachment theo TC_ID → ghi chú "no screenshot" trong result.md
+
+---
+
+## Step 3: Generate result.md per TC
+
+Với mỗi TC, tạo `evidence/TC_[ID]-[scenario]/result.md`:
+
+**Template khi PASS:**
+
+```markdown
+# Result: AD10_001 — Đăng nhập thành công
+
+**Status:** ✅ PASS
+**Duration:** 1.23s
+**Run date:** [YYYY-MM-DD HH:MM]
+
+## Evidence
+
+| Step | Screenshot |
+|------|-----------|
+| 1. Mở trang /login | step-01-mo-trang-login.png |
+| 2. Nhập email + password | step-02-nhap-credentials.png |
+| 3. Redirect về /dashboard | step-03-ket-qua.png |
+
+## Notes
+
+_Test passed. No issues found._
+```
+
+**Template khi FAIL:**
+
+```markdown
+# Result: AD10_002 — Error khi sai password
+
+**Status:** ❌ FAIL
+**Duration:** 2.45s
+**Run date:** [YYYY-MM-DD HH:MM]
+
+## Failure Details
+
+**Error message:**
+```
+Error: expect(received).toBeVisible()
+Expected: visible
+Received: not visible (element not found)
+Locator: page.getByText('Sai email hoặc mật khẩu')
+```
+
+**Steps executed:**
+1. ✅ Mở trang /login
+2. ✅ Nhập email hợp lệ
+3. ✅ Nhập password SAI
+4. ✅ Click "Đăng nhập"
+5. ❌ Error message không xuất hiện → FAIL
+
+## Evidence
+
+| File | Mô tả |
+|------|-------|
+| failure-screenshot.png | Trạng thái màn hình lúc fail |
+| trace.zip | Playwright trace (mở bằng `npx playwright show-trace`) |
+
+## Bug Reference
+
+→ Xem: bugs/BUG-001-error-message-khong-hien.md
+```
+
+---
+
+## Step 4: Auto-generate Bug Draft cho TCs Failed
+
+Với mỗi TC có status `failed`, tạo draft bug report:
+
+**Lưu `bugs/BUG-[NNN]-[slug-title].md`** (số tăng dần, bắt đầu từ 001):
+
+```markdown
+# BUG-001 — Error message không hiển thị khi sai password
+
+**TC_ID:** AD10_002
+**Severity:** [High] ← dựa trên Severity của TC trong final-testcases.md
+**Status:** 🔴 Open
+**Found at:** Gate 3 Execution | [YYYY-MM-DD]
+**Environment:** [baseUrl] | Chrome Latest | Windows
+
+---
+
+## Steps to Reproduce
+
+1. Mở trang /login tại [baseUrl/login]
+2. Nhập email hợp lệ: `user@example.com`
+3. Nhập password SAI: `WrongPassword`
+4. Click button "Đăng nhập"
+
+## Expected Result
+
+Error message "Sai email hoặc mật khẩu" hiển thị ngay dưới form.
+
+## Actual Result
+
+Error message KHÔNG hiển thị. Trang vẫn load bình thường, không có feedback cho user.
+
+## Evidence
+
+- Screenshot: `evidence/AD10_002-error-sai-password/failure-screenshot.png`
+- Playwright trace: `evidence/AD10_002-error-sai-password/trace.zip`
+
+## Technical Notes
+
+```
+Playwright assertion failed:
+expect(page.getByText('Sai email hoặc mật khẩu')).toBeVisible()
+Element not found in DOM after 5000ms timeout.
+```
+
+_Dev có thể reproduce bằng cách mở trace: `npx playwright show-trace evidence/AD10_002.../trace.zip`_
+
+---
+
+## Resolution
+
+- [ ] Dev fix
+- [ ] Retest: `RETEST: AD10_002`
+```
+
+**Severity từ TC metadata:**
+- TC Severity = Critical → Bug Severity = Critical
+- TC Severity = High → Bug Severity = High
+- TC Severity = Medium → Bug Severity = Medium
+- TC Severity = Low → Bug Severity = Low
+
+---
+
+## Step 5: Display Gate 3 Summary
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⏸️ GATE 3: EXECUTION COMPLETE
+
+Results:
+  ✅ Passed:  [N] / [total]
+  ❌ Failed:  [N] / [total]
+  🚫 Blocked: [N] / [total]
+  🔧 Manual:  [N] (chưa execute)
+
+Bugs logged:
+  🔴 Critical: [N]
+  🟠 High:     [N]
+  🟡 Medium:   [N]
+  🟢 Low:      [N]
+
+→ Review evidence: evidence/
+→ Review bugs:     bugs/
+→ Type APPROVED when all critical/high bugs resolved
+→ Type RETEST: [TC_ID] to re-execute a specific test case
+→ Type PR: [url] to declare new dev PRs (triggers Dev Artifacts Check)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Mandatory Rules
+
+- ✅ **PHẢI** tạo đúng 1 folder per TC (kể cả TC pass)
+- ✅ **PHẢI** tạo `result.md` trong mỗi folder
+- ✅ **PHẢI** tạo bug draft cho mọi TC failed, không bỏ sót
+- ✅ Bug severity phải map từ TC severity trong final-testcases.md
+- ❌ **KHÔNG** overwrite evidence của previous run — tạo subfolder với timestamp nếu re-run
+- ✅ Nếu `test-results/results.json` không tồn tại → hướng dẫn TESTER chạy `npx playwright test --reporter=json` trước