@relipa/ai-flow-kit 0.2.0 → 0.2.2-beta.0

package/custom/skills/impact-analysis/SKILL.md

@@ -1,106 +1,106 @@
----
-name: impact-analysis
-description: Analyze the impact scope when modifying logic or the database to ensure system-wide safety.
-keywords: impact, refactor, breaking change, scope
----
-
-# Impact Analysis
-
-## When mandatory to run
-
-- Modifying **Core Services / shared utilities** used in many places
-- Changing **database schema** (add/rename/drop column, table)
-- Changing **API response structure** (rename field, remove field)
-- Changing **interfaces / contracts** between modules
-- After fixing a bug — to ensure the fix doesn't break other parts
-
----
-
-## Analysis Process
-
-### Step 1: Find all usage (Dependency Map)
-
-**Preferred — If GitNexus MCP is available** (`.mcp.json` has `gitnexus` entry):
-```
-impact("ClassName")    → structured blast radius: callers, dependents, risk score
-detect_changes()       → reads current git diff, maps changed lines → affected symbols
-```
-- Use `impact()` when you know the class/function name being modified.
-- Use `detect_changes()` when starting Gate 4 review — it auto-detects what changed from git diff without needing to specify names.
-- One call replaces all grep commands below. Proceed directly to Step 2 with the result.
-
-**Fallback — grep manually** (if GitNexus not configured):
-```bash
-# Find all files importing/calling the class/function being modified
-grep -r "ClassName\|functionName\|methodName" --include="*.php" .
-grep -r "ClassName\|functionName\|methodName" --include="*.java" .
-grep -r "ClassName\|functionName\|methodName" --include="*.ts" .
-
-# Check which routes/controllers trigger this service
-grep -r "ServiceName" app/Http/Controllers/
-```
-
-List all:
-- Controllers / Routes calling it directly
-- Jobs / Commands / Events calling it indirectly
-- Tests mocking/stubbing this class
-- Frontend components calling related APIs
-
-### Step 2: Evaluate each aspect
-
-| Aspect | Checkpoint questions |
-|-----------|---------------------|
-| **Database / Cache** | Which queries are affected by schema changes? Which cache keys need flushing? |
-| **Background Jobs** | Which Crons / Queues call this logic? Will they break? |
-| **Import / Export** | Do bulk data flows use this field/logic? |
-| **Permissions** | Are API / UI permission checks sufficient after the change? |
-| **API / Mobile** | Will JSON responses lose fields? Do mobile clients need updates? |
-| **Tests** | Which tests will fail? Which mocks/stubs need updating? |
-
-### Step 3: Classify impact level
-
-| Level | Definition | Action |
-|-----|-----------|-----------|
-| 🟢 Low | Only 1 file, no dependencies | Proceed |
-| 🟡 Medium | 2–5 files, tests need updates | Review carefully before merging |
-| 🔴 High | 6+ files, API breaking change, DB migration | Discuss with the team first |
-| ⛔ Critical | Affects payment, auth, data integrity | Tech Lead review mandatory |
-
-### Step 4: Export report
-
-**Report structure:**
-
-```
-## Impact Analysis: [Change Name]
-
-**Level:** 🟡 Medium
-
-### Impact Scope
-- [File/Class A] — [reason for impact]
-- [File/Class B] — [reason for impact]
-
-### Breaking changes
-- [Describe breaking change if any]
-
-### Tests to check after merge
-- [ ] [Test case / screen 1]
-- [ ] [Test case / screen 2]
-- [ ] [Job/Command to test run]
-
-### Notes for QA
-[Specific points QA should pay attention to]
-```
-
-Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
-
----
-
-## Completion Checklist
-
-- [ ] Found all dependencies using grep/IDE search
-- [ ] Checked Jobs, Events, and Crons
-- [ ] Checked API response structure
-- [ ] Checked tests
-- [ ] Determined impact level (Low/Medium/High/Critical)
-- [ ] Wrote impact report
-- [ ] Notified the team if High/Critical
+---
+name: impact-analysis
+description: Analyze the impact scope when modifying logic or the database to ensure system-wide safety.
+keywords: impact, refactor, breaking change, scope
+---
+
+# Impact Analysis
+
+## When mandatory to run
+
+- Modifying **Core Services / shared utilities** used in many places
+- Changing **database schema** (add/rename/drop column, table)
+- Changing **API response structure** (rename field, remove field)
+- Changing **interfaces / contracts** between modules
+- After fixing a bug — to ensure the fix doesn't break other parts
+
+---
+
+## Analysis Process
+
+### Step 1: Find all usage (Dependency Map)
+
+**Preferred — If GitNexus MCP is available** (`.mcp.json` has `gitnexus` entry):
+```
+impact("ClassName")    → structured blast radius: callers, dependents, risk score
+detect_changes()       → reads current git diff, maps changed lines → affected symbols
+```
+- Use `impact()` when you know the class/function name being modified.
+- Use `detect_changes()` when starting Gate 4 review — it auto-detects what changed from git diff without needing to specify names.
+- One call replaces all grep commands below. Proceed directly to Step 2 with the result.
+
+**Fallback — grep manually** (if GitNexus not configured):
+```bash
+# Find all files importing/calling the class/function being modified
+grep -r "ClassName\|functionName\|methodName" --include="*.php" .
+grep -r "ClassName\|functionName\|methodName" --include="*.java" .
+grep -r "ClassName\|functionName\|methodName" --include="*.ts" .
+
+# Check which routes/controllers trigger this service
+grep -r "ServiceName" app/Http/Controllers/
+```
+
+List all:
+- Controllers / Routes calling it directly
+- Jobs / Commands / Events calling it indirectly
+- Tests mocking/stubbing this class
+- Frontend components calling related APIs
+
+### Step 2: Evaluate each aspect
+
+| Aspect | Checkpoint questions |
+|-----------|---------------------|
+| **Database / Cache** | Which queries are affected by schema changes? Which cache keys need flushing? |
+| **Background Jobs** | Which Crons / Queues call this logic? Will they break? |
+| **Import / Export** | Do bulk data flows use this field/logic? |
+| **Permissions** | Are API / UI permission checks sufficient after the change? |
+| **API / Mobile** | Will JSON responses lose fields? Do mobile clients need updates? |
+| **Tests** | Which tests will fail? Which mocks/stubs need updating? |
+
+### Step 3: Classify impact level
+
+| Level | Definition | Action |
+|-----|-----------|-----------|
+| 🟢 Low | Only 1 file, no dependencies | Proceed |
+| 🟡 Medium | 2–5 files, tests need updates | Review carefully before merging |
+| 🔴 High | 6+ files, API breaking change, DB migration | Discuss with the team first |
+| ⛔ Critical | Affects payment, auth, data integrity | Tech Lead review mandatory |
+
+### Step 4: Export report
+
+**Report structure:**
+
+```
+## Impact Analysis: [Change Name]
+
+**Level:** 🟡 Medium
+
+### Impact Scope
+- [File/Class A] — [reason for impact]
+- [File/Class B] — [reason for impact]
+
+### Breaking changes
+- [Describe breaking change if any]
+
+### Tests to check after merge
+- [ ] [Test case / screen 1]
+- [ ] [Test case / screen 2]
+- [ ] [Job/Command to test run]
+
+### Notes for QA
+[Specific points QA should pay attention to]
+```
+
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
+
+---
+
+## Completion Checklist
+
+- [ ] Found all dependencies using grep/IDE search
+- [ ] Checked Jobs, Events, and Crons
+- [ ] Checked API response structure
+- [ ] Checked tests
+- [ ] Determined impact level (Low/Medium/High/Critical)
+- [ ] Wrote impact report
+- [ ] Notified the team if High/Critical

package/custom/skills/read-study-requirement/SKILL.md

@@ -22,8 +22,7 @@ Before reading the ticket in depth, verify the bridge document from UC Spec —
 3. Check `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v*.md`:
    - **Missing** → `⚠️ CẢNH BÁO: Không tìm thấy System Requirement cho [functionId]. Khuyến nghị chạy "ak use" → "📐 Create System Requirement" trước ticket kế tiếp — Gate 1 vẫn tiếp tục ngay bây giờ dựa trên UC Spec/ticket.`
    - **Exists, but its `UC-Spec-Version` header doesn't match the UC Spec found in step 2** → `⚠️ CẢNH BÁO: System Requirement đang trace theo UC Spec v[X], UC Spec hiện tại là v[Y] — nội dung có thể lỗi thời.` Treat its items as Assumption rather than Fact in Step 1.75.
-   - **Exists, matches, but its `Status` header is not `✅ Approved`** → `⚠️ CẢNH BÁO: System Requirement cho [functionId] chưa Approved (Status: [giá trị hiện tại]) — nội dung có thể còn thay đổi.`
-   - **Exists, matches, and Approved** → continue silently. Keep this file's path — Step 1 must read it as mandatory input.
+   - **Exists and matches** → continue silently. Keep this file's path — Step 1 must read it as mandatory input. (Its presence in the repo already means DEV approved and pushed it — approval isn't tracked with a separate header.)
 
 Any warning raised above must also be written into this ticket's requirement doc (Section 1, Facts/Assumptions/Gaps in Step 4) — not just printed and forgotten. If DEV wants the gap closed properly, they can run `ak use` → "📐 Create System Requirement" for `[functionId]` at any point (before or after this ticket) — it's a separate 2-gate task type, not an inline sub-skill here.
 

package/custom/skills/report-customer/SKILL.md

@@ -1,99 +1,99 @@
----
-name: report-customer
-description: Write an incident report for customers or customer service after a production bug fix. Non-technical, easy-to-understand language.
-keywords: report, incident, customer, customer service, CS
----
-
-# Report Customer (Incident Report)
-
-## When to use
-
-- After fixing a bug that affects users/customers
-- Customer Service needs a report explaining the cause to customers
-- Need to document the incident for future reference
-
----
-
-## Process
-
-### Step 1: Gather information
-
-Collect from `investigate-bug` results or developer descriptions:
-- Ticket ID and title
-- Discovery time / impact duration
-- Number of affected users / orders
-- Identified root cause
-- Deployment status
-
-### Step 2: Write the report
-
-Fill in the structure below. **Use simple language, avoiding technical jargon.**
-
----
-
-## Standard Structure
-
-Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md`
-(Vietnamese ticket → Vietnamese report; otherwise English). CS can request a specific language
-explicitly, which overrides auto-detect. Structure below is shown in English.
-
-```markdown
-## 📋 Incident Verification Report
-
-**Ticket ID:** [ID]
-**Assigned to:** [Dev Name]
-**Resolution Date:** [YYYY-MM-DD]
-**Status:** ✅ Resolved / 🔄 In Progress
-
----
-
-### 1. Summary
-
-[1–2 sentences describing the issue in non-technical language.
-Example: "Between 14:00–15:30 on [Date], some 
-users were unable to complete order payments."]
-
----
-
-### 2. Root Cause
-
-[Simple explanation, no code references.
-Example: "Due to a system update failing to correctly handle 
-slow connections with the payment gateway."]
-
----
-
-### 3. Resolution
-
-[Steps taken by the technical team.
-Example: "Updated the timeout handling mechanism and deployed 
-the fix at 16:00 on [Date]."]
-
----
-
-### 4. Data Impact
-
-- Was existing data affected? [Yes / No]
-- Data recovery status: [Update script run / Not necessary]
-
----
-
-### 5. Expected Behavior
-
-[Actions the customer should take to verify normal operation.
-Example: "Customers can now attempt payment normally.
-If problems persist, please contact our support hotline..."]
-```
-
----
-
-## Writing Rules
-
-- ✅ Simple language, avoid technical jargon
-- ✅ Honest about scope and duration of impact
-- ✅ Focus on **user impact**, not code details
-- ✅ Always include instructions for the customer to verify the fix
-- ❌ Do not blame third parties unless certain
-- ❌ Do not commit to specific deadlines unless certain
-
-Present clearly and professionally, in the language determined above.
+---
+name: report-customer
+description: Write an incident report for customers or customer service after a production bug fix. Non-technical, easy-to-understand language.
+keywords: report, incident, customer, customer service, CS
+---
+
+# Report Customer (Incident Report)
+
+## When to use
+
+- After fixing a bug that affects users/customers
+- Customer Service needs a report explaining the cause to customers
+- Need to document the incident for future reference
+
+---
+
+## Process
+
+### Step 1: Gather information
+
+Collect from `investigate-bug` results or developer descriptions:
+- Ticket ID and title
+- Discovery time / impact duration
+- Number of affected users / orders
+- Identified root cause
+- Deployment status
+
+### Step 2: Write the report
+
+Fill in the structure below. **Use simple language, avoiding technical jargon.**
+
+---
+
+## Standard Structure
+
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md`
+(Vietnamese ticket → Vietnamese report; otherwise English). CS can request a specific language
+explicitly, which overrides auto-detect. Structure below is shown in English.
+
+```markdown
+## 📋 Incident Verification Report
+
+**Ticket ID:** [ID]
+**Assigned to:** [Dev Name]
+**Resolution Date:** [YYYY-MM-DD]
+**Status:** ✅ Resolved / 🔄 In Progress
+
+---
+
+### 1. Summary
+
+[1–2 sentences describing the issue in non-technical language.
+Example: "Between 14:00–15:30 on [Date], some 
+users were unable to complete order payments."]
+
+---
+
+### 2. Root Cause
+
+[Simple explanation, no code references.
+Example: "Due to a system update failing to correctly handle 
+slow connections with the payment gateway."]
+
+---
+
+### 3. Resolution
+
+[Steps taken by the technical team.
+Example: "Updated the timeout handling mechanism and deployed 
+the fix at 16:00 on [Date]."]
+
+---
+
+### 4. Data Impact
+
+- Was existing data affected? [Yes / No]
+- Data recovery status: [Update script run / Not necessary]
+
+---
+
+### 5. Expected Behavior
+
+[Actions the customer should take to verify normal operation.
+Example: "Customers can now attempt payment normally.
+If problems persist, please contact our support hotline..."]
+```
+
+---
+
+## Writing Rules
+
+- ✅ Simple language, avoid technical jargon
+- ✅ Honest about scope and duration of impact
+- ✅ Focus on **user impact**, not code details
+- ✅ Always include instructions for the customer to verify the fix
+- ❌ Do not blame third parties unless certain
+- ❌ Do not commit to specific deadlines unless certain
+
+Present clearly and professionally, in the language determined above.

package/custom/skills/script-sync/SKILL.md

@@ -18,7 +18,9 @@ Sync test cases (từ TC file `.md`) với Playwright spec files, sử dụng **
 - `tcFile`: path đến TC file markdown (vd `testcases/AD10.md`)
 - `repo`: tên repo (vd `repo-fe`)
 - `screenId`: mã màn hình, always lowercase (vd `ad10`, not `AD10`) — directory paths use lowercase; spec file name `{ScreenID}.spec.ts` remains uppercase
+- `featureDir`: `{ScreenID}_{Screen-Name-kebab-case}` (vd `AD10_create-product`)
 - `baseUrl`: URL của app để Playwright MCP snapshot
+- `scriptsRoot`: `AK-Docs/03.Testing/05.Scripts/{repo}/` — script + Page Object sinh ra nằm ở đây, `Shared/evidence-helper.ts` nằm ở `AK-Docs/03.Testing/05.Scripts/Shared/`
 
 ---
 
@@ -39,7 +41,7 @@ Không tính vào hash: `Severity`, `Pre-condition`, `Data Test`, `Ticket ID`, `
 
 ## Spec File Structure
 
-Mỗi TC trong spec file có metadata comment ngay trước `test()`:
+Mỗi TC trong spec file có metadata comment ngay trước `test()`. File nằm ở `AK-Docs/03.Testing/05.Scripts/{repo}/{featureDir}/{ScreenID}.spec.ts`:
 
 ```typescript
 // @screen-id: AD10
@@ -48,20 +50,25 @@ Mỗi TC trong spec file có metadata comment ngay trước `test()`:
 // @screen-url: /admin/products/create
 // @generated: YYYY-MM-DD
 
-import { test, expect } from '../../shared/fixtures/test'
+import { test, expect } from '../../Shared/fixtures/test'
+import { captureStepEvidence } from '../../Shared/evidence-helper'
 import { AD10Page } from '../pages/AD10Page'
 
 test.describe('AD10 - Create Product', () => {
 
   // @tc-hash: a3f9b2c1
   // @tc-id: AD10_001
-  test('AD10_001 - Truy cập trực tiếp qua URL khi chưa đăng nhập', async ({ page }) => {
+  test('AD10_001 - Truy cập trực tiếp qua URL khi chưa đăng nhập', async ({ page }, testInfo) => {
+    const pageObj = new AD10Page(page)
     // ...
+    // xem "Assertion Rules" + "Evidence Capture per Step" bên dưới — mỗi step UI trong TC
+    // phải gọi captureStepEvidence(page, testInfo, N, 'desc', {...}) và assertion phải khẳng
+    // định đúng nội dung Expected Result, không chỉ kiểm tra element tồn tại.
   })
 
   // @tc-hash: d7e2f4a9
   // @tc-id: AD10_002
-  test('AD10_002 - Truy cập trực tiếp qua URL khi đã đăng nhập', async ({ page }) => {
+  test('AD10_002 - Truy cập trực tiếp qua URL khi đã đăng nhập', async ({ page }, testInfo) => {
     // ...
   })
 
@@ -84,7 +91,7 @@ Nhận diện **Manual TCs** — các TC không thể automation:
 
 ### Bước 2: Scan spec file hiện tại
 
-Tìm `ak-test/{repo}/scripts/{screenId}/{ScreenID}.spec.ts`.
+Tìm `AK-Docs/03.Testing/05.Scripts/{repo}/{featureDir}/{ScreenID}.spec.ts` (`scriptsRoot` từ input + `{featureDir}/{ScreenID}.spec.ts`).
 
 Nếu tồn tại: đọc file, extract tất cả cặp `@tc-hash` + `@tc-id` bằng regex:
 ```
@@ -114,25 +121,40 @@ Với mỗi TC cần gen mới:
    - `mcp__playwright__browser_navigate` → `baseUrl + screenUrl`
    - `mcp__playwright__browser_snapshot` → lấy accessibility tree
    - Với từng element trong Steps: `mcp__playwright__browser_generate_locator`
-3. Sinh test block với metadata comments:
+   - Nếu locator match **nhiều hơn 1 element** trên snapshot → không dùng locator đó, tìm locator scope hẹp hơn (trong đúng container/row/modal) hoặc dùng `data-testid` cụ thể. Xem "Assertion Rules" — locator mơ hồ là nguyên nhân chính gây false pass/fail.
+3. Sinh test block với metadata comments — **mỗi Step trong TC file map 1:1 với 1 action + 1 evidence capture**, assertion cuối phải khẳng định đúng nội dung Expected Result:
 
 ```typescript
   // @tc-hash: {hash}
   // @tc-id: {TC_ID}
-  test('{TC_ID} - {Test Case Name}', async ({ page }) => {
+  test('{TC_ID} - {Test Case Name}', async ({ page }, testInfo) => {
     const pageObj = new {ScreenID}Page(page)
-    // Step 1: {step text}
+
+    // Step 1: {step text — vd "Trên màn hình danh sách, click item A để mở A1"}
     await pageObj.{action}()
-    // Step 2: {step text}
+    await captureStepEvidence(page, testInfo, 1, '{step-1-desc}', { highlightSelector: pageObj.itemALocator })
+
+    // Step 2: {step text — vd "Trên A1, click button B để mở modal B1"}
     await pageObj.{action}()
-    // Expected: {expected result}
-    await expect(page.{locator}).{assertion}
+    await captureStepEvidence(page, testInfo, 2, '{step-2-desc}', { highlightSelector: pageObj.buttonBLocator })
+
+    // Step 3 (nếu step mở popup/modal): chờ modal hiện + settle rồi mới chụp + assert
+    await expect(pageObj.modalB1Locator).toBeVisible()
+    await captureStepEvidence(page, testInfo, 3, '{step-3-desc}', {
+      highlightSelector: pageObj.confirmFieldLocator,   // đúng vùng cần confirm theo Expected Result
+      scrollSelector: pageObj.confirmFieldLocator,       // nếu modal có scroll
+    })
+
+    // Expected: {expected result — assertion PHẢI check đúng nội dung, không chỉ tồn tại}
+    await expect(pageObj.confirmFieldLocator).toHaveText('{expected text từ TC file}')
   })
 ```
 
+> Nếu TC chỉ có 1 step / không mở modal mới, vẫn gọi `captureStepEvidence` ít nhất 1 lần ở trạng thái cuối (sau khi `waitForUiSettled`) — không bỏ qua evidence.
+
 4. Nếu spec file chưa tồn tại: tạo file mới với file header + describe wrapper + test block.
 5. Nếu spec file đã tồn tại: append test block vào trước closing `})` của `test.describe`.
-6. Nếu `{ScreenID}Page.ts` chưa tồn tại: tạo Page Object với locators cho các elements đã snapshot.
+6. Nếu `{ScreenID}Page.ts` chưa tồn tại: tạo Page Object với locators cho các elements đã snapshot — **đặt tên locator theo đúng item được mô tả trong Step** (vd `itemALocator`, `buttonBLocator`) để dùng lại cho `highlightSelector` ở bước capture evidence.
 
 **File header khi tạo spec mới:**
 ```typescript
@@ -142,7 +164,8 @@ Với mỗi TC cần gen mới:
 // @screen-url: {url path}
 // @generated: {YYYY-MM-DD}
 
-import { test, expect } from '../../shared/fixtures/test'
+import { test, expect } from '../../Shared/fixtures/test'
+import { captureStepEvidence } from '../../Shared/evidence-helper'
 import { {ScreenID}Page } from '../pages/{ScreenID}Page'
 
 test.describe('{ScreenID} - {Screen Name}', () => {
@@ -188,8 +211,8 @@ mcp__playwright__browser_close
 ⚠️ Manual:   {N} TCs → {TC_IDs} (lý do)
 ❌ Blocked:  {N} TCs → {TC_IDs} (lý do)
 
-→ Script: ak-test/{repo}/scripts/{screenId}/{ScreenID}.spec.ts
-→ Page Object: ak-test/{repo}/scripts/pages/{ScreenID}Page.ts
+→ Script: AK-Docs/03.Testing/05.Scripts/{repo}/{featureDir}/{ScreenID}.spec.ts
+→ Page Object: AK-Docs/03.Testing/05.Scripts/{repo}/pages/{ScreenID}Page.ts
 ```
 
 Trả về danh sách kết quả cho `execute-flow`:
@@ -199,10 +222,25 @@ Trả về danh sách kết quả cho `execute-flow`:
 
 ---
 
+## Assertion Rules (bắt buộc — tránh false pass/fail)
+
+- ❌ **Không** dùng locator match nhiều hơn 1 element làm căn cứ assertion — verify qua `browser_snapshot` rằng locator chỉ trúng đúng 1 node trước khi dùng. Nếu snapshot cho thấy nhiều node giống nhau (list item, nhiều modal ẩn/hiện cùng lúc) → scope locator trong đúng container (`getByRole('dialog').getByText(...)`, `row.getByTestId(...)`) hoặc thêm `.filter({ hasText: ... })`.
+- ❌ **Không** dùng `toBeVisible()`/`toBeAttached()` làm assertion duy nhất khi Expected Result mô tả **nội dung cụ thể** (text, giá trị, số lượng, trạng thái field) — phải dùng `toHaveText`/`toContainText`/`toHaveValue`/`toBeDisabled`/`toHaveCount` tương ứng.
+- ❌ **Không** wrap action trong `try/catch` rồi để pass nếu catch nuốt lỗi mà không có assertion thay thế khẳng định behavior đúng.
+- ✅ Với negative/validation TC (kỳ vọng lỗi, kỳ vọng bị chặn) → assertion phải khẳng định đúng **hành vi chặn** đó xảy ra (message lỗi đúng text, hoặc action bị disable, hoặc điều hướng không xảy ra) — không chỉ assert "trang không crash".
+- ✅ Mỗi step có mô tả thay đổi UI trong TC Steps → phải có 1 lệnh gọi `captureStepEvidence(...)` tương ứng, đặt **ngay sau** `waitForUiSettled` implicit trong helper — xem "Evidence Capture per Step" dưới.
+
+## Evidence Capture per Step
+
+- Import `captureStepEvidence`, `waitForUiSettled`, `highlightElement` từ `Shared/evidence-helper.ts` (không viết lại logic này trong từng spec).
+- Nếu Step yêu cầu click để mở popup/modal → thực hiện click **trước**, chờ modal `toBeVisible()`, rồi mới `captureStepEvidence` cho step đó — không chụp step trước khi hành động mở modal xảy ra.
+- Nếu vùng cần confirm nằm ngoài viewport (modal dài, table nhiều dòng) → truyền `scrollSelector` để helper tự `scrollIntoViewIfNeeded()` trước khi chụp.
+- Truyền `highlightSelector` = đúng locator của item/nội dung mà Expected Result yêu cầu tester xác nhận — helper tự khoanh viền đỏ rồi remove sau khi chụp.
+
 ## Mandatory Rules
 
 - ❌ **Không bao giờ bịa selector** — phải dùng Playwright MCP snapshot
 - ❌ **Không overwrite** test block có hash match — skip hoàn toàn
 - ✅ Ưu tiên locator: `getByRole` > `getByLabel` > `getByPlaceholder` > `getByText` > `getByTestId` > CSS
-- ✅ Không tạo lại `BasePage.ts` / `fixtures/test.ts` nếu đã tồn tại
+- ✅ Không tạo lại `BasePage.ts` / `fixtures/test.ts` / `evidence-helper.ts` nếu đã tồn tại
 - ✅ Test names/comments theo ngôn ngữ của TC input (xem `custom/rules/output-language.md`) — TC tiếng Việt → tiếng Việt, TC tiếng Anh → tiếng Anh

package/custom/templates/nestjs.md

@@ -1,72 +1,5 @@
-# NestJS AI System Prompt
-
-You are an expert NestJS developer. Follow these modular architecture rules and best practices.
-
----
-
-## Project Architecture
-
-NestJS follows a strict **Module-based** architecture. Every feature should be contained in its own module.
-
-```
-src/
-├── app.module.ts
-├── main.ts
-└── features/
-    └── [feature-name]/
-        ├── [feature].module.ts
-        ├── [feature].controller.ts
-        ├── [feature].service.ts
-        ├── [feature].entity.ts (if using TypeORM)
-        └── dto/
-            ├── create-[feature].dto.ts
-            └── update-[feature].dto.ts
-```
-
----
-
-## NestJS Rules
-
-- Use **Constructor Injection** for all dependencies.
-- Always use **DTOs** (Data Transfer Objects) with `class-validator` for input validation.
-- Annotate controllers with `@Controller()`.
-- Use `@Injectable()` for services.
-- Leverage **Pipes** for data transformation and validation.
-- Leverage **Interceptors** for logging and response mapping.
-
-```typescript
-// ✅ Good: DTO with validation
-export class CreateUserDto {
-  @IsEmail()
-  email: string;
-
-  @IsString()
-  @MinLength(8)
-  password: string;
-}
-```
-
----
-
-## Testing Rules
-
-- Use the built-in **Jest** testing suite.
-- Use `Test.createTestingModule` to create isolated environments for unit tests.
-
-```typescript
-describe('UsersService', () => {
-  let service: UsersService;
-
-  beforeEach(async () => {
-    const module: TestingModule = await Test.createTestingModule({
-      providers: [UsersService],
-    }).compile();
-
-    service = module.get<UsersService>(UsersService);
-  });
-
-  it('should be defined', () => {
-    expect(service).toBeDefined();
-  });
-});
-```
+# NestJS AI System Prompt
+
+You are an expert NestJS developer. Follow these modular architecture rules and best practices.
+
+> **Rules & code examples:** Read `.rules/javascript/nestjs-rules.md` (architecture, module rules, testing) and `.rules/javascript/nestjs-examples.md` (code samples per rule area) **in full** before writing or modifying any NestJS code in this project.