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

package/custom/skills/execute-flow/SKILL.md

@@ -18,6 +18,40 @@ Flow độc lập để tester thực thi test từ TC file có sẵn, không c
 
 ---
 
+## Cấu trúc thư mục đầu ra
+
+**Không còn dùng `ak-test/` working dir.** Toàn bộ output — script, evidence, result, report, bug — nằm trong `AK-Docs/03.Testing/`, theo cấu trúc chuẩn ở `docs/common/Testing-Structure.md`. `04.Evidence/` chứa screenshot/video/`trace.zip`/`results.json` thô, nhưng **phải nằm trong `.gitignore`** — đây vẫn là binary lớn, không commit lên Git kể cả khi nằm trong AK-Docs.
+
+```
+AK-Docs/03.Testing/
+├── 04.Evidence/{repo}/{featureDir}/run-{N}/    # ⚠️ gitignored — xem Gate 1 item 6
+│   ├── results.json                            # Playwright JSON output thô
+│   └── {TC_ID}-{kebab-scenario}/
+│       ├── step-NN-{desc}.png                  # 1 ảnh / step có mô tả UI
+│       └── trace.zip
+├── 05.Scripts/                                 # Gate 2 — Playwright project, chạy được tại chỗ
+│   ├── package.json / tsconfig.json / node_modules/ (gitignored)
+│   ├── Shared/
+│   │   ├── fixtures/test.ts
+│   │   ├── BasePage.ts
+│   │   └── evidence-helper.ts
+│   └── {repo}/
+│       ├── playwright.config.ts
+│       ├── pages/{ScreenID}Page.ts
+│       └── {featureDir}/{ScreenID}.spec.ts
+├── 02.Reports/{repo}/{featureDir}/run-{N}/
+│   ├── {TC_ID}-{kebab-scenario}/result.md
+│   └── testreport.md                           # Gate 4
+└── 06.Bugs/{repo}/{featureDir}/run-{N}/
+    └── BUG-{NNN}-{slug}.md                     # Gate 3
+```
+
+`featureDir` = `{ScreenID}_{Screen-Name-kebab-case}` (vd `AD10_create-product`).
+
+> **Lịch sử:** bản trước dùng `ak-test/` working dir ngoài AK-Docs cho evidence để tránh phình git history. Tester quyết định bỏ `ak-test/` hoàn toàn — evidence chuyển vào `04.Evidence/` (đúng theo mapping gốc của `docs/common/Testing-Structure.md`), và xử lý vấn đề binary lớn bằng `.gitignore` thay vì tách working dir riêng.
+
+---
+
 ## ⛩️ GATE 1 — Context & Work Plan
 
 ### Pre-flight checks (auto, không hỏi tester)
@@ -47,14 +81,44 @@ Kiểm tra trước khi làm gì:
      > "Để cài thủ công: mở `~/.claude/settings.json`, thêm `playwright` vào `mcpServers`, rồi restart Claude Code."
 
 1. TC file có parse được không? (file tồn tại, có Section 3 — Danh sách Test Cases)
-2. `ak-test/` folder có tồn tại không? Nếu không → hướng dẫn tester tạo: `mkdir ak-test`
+2. `AK-Docs/03.Testing/` có tồn tại không? (thư mục chuẩn theo `docs/common/Testing-Structure.md` — nếu thiếu subfolder `04.Evidence/`, `05.Scripts/`, `02.Reports/`, `06.Bugs/` thì tự tạo)
 3. `BASE_URL` env var có set không? Nếu không → hỏi: "BASE_URL chưa set. App đang chạy ở URL nào?"
 
-Items 1–3 chạy ngay khi entry. Item 4 chạy sau khi repo được xác định từ Bước 1 (parse TC file):
+Items 1–3 chạy ngay khi entry. Items 4–6 chạy sau khi repo được xác định từ Bước 1 (parse TC file):
+
+4. `AK-Docs/03.Testing/05.Scripts/{repo}/playwright.config.ts` có tồn tại không? Nếu không → **tự scaffold** (không cần hỏi tester), xem "Scaffold Playwright Project" bên dưới.
+5. `AK-Docs/03.Testing/05.Scripts/package.json` + `node_modules/` có tồn tại không? Nếu chưa `npm install` → chạy `npm install` trong `AK-Docs/03.Testing/05.Scripts/`, sau đó `npx playwright install chromium` (một lần, cache browser ở `~/.cache/ms-playwright`, không nằm trong repo).
+6. `.gitignore` (ở root của AK-Docs, hoặc root repo chứa AK-Docs) có ignore các dòng sau chưa? Nếu chưa → tự thêm (append, không xoá nội dung cũ):
+   - `03.Testing/04.Evidence/` — **bắt buộc**, evidence là binary (screenshot/video/trace.zip), không commit dù nằm trong AK-Docs
+   - `03.Testing/05.Scripts/**/node_modules/`, `03.Testing/05.Scripts/**/test-results/`, `03.Testing/05.Scripts/**/playwright-report/`, `03.Testing/05.Scripts/**/blob-report/`
+
+Nếu bất kỳ check nào fail và không tự fix được → dừng, hướng dẫn fix. Không proceed.
+
+### Scaffold Playwright Project (chỉ chạy lần đầu, khi chưa có `AK-Docs/03.Testing/05.Scripts/`)
+
+AK-Docs vốn là docs-only repo (không có `package.json`). Vì tester yêu cầu script phải nằm trong AK-Docs để dễ trace cùng report/bug, ta scaffold một Playwright project bên trong `03.Testing/05.Scripts/` — **một package.json/node_modules chung cho tất cả repo**, mỗi repo có `playwright.config.ts` riêng (baseURL khác nhau):
+
+```
+AK-Docs/03.Testing/05.Scripts/
+├── package.json              # 1 lần duy nhất, dùng chung mọi repo
+├── tsconfig.json
+├── node_modules/              # gitignored
+├── Shared/
+│   ├── fixtures/test.ts       # test fixture chung
+│   ├── BasePage.ts
+│   └── evidence-helper.ts     # xem templates/evidence-helper.ts
+└── {repo}/
+    ├── playwright.config.ts   # baseURL riêng cho repo này
+    ├── pages/{ScreenID}Page.ts
+    └── {featureDir}/{ScreenID}.spec.ts
+```
 
-4. `playwright.config.ts` có tồn tại trong `ak-test/{repo}/` không? Nếu không → dừng, hướng dẫn tester: "Chưa có playwright.config.ts cho repo {repo}. Tạo file từ template tại `ak-test/{repo}/playwright.config.ts` (xem skill execute-flow templates)."
+- `package.json`: devDependencies `@playwright/test`, `typescript`. Tạo bằng `npm init -y` rồi `npm install -D @playwright/test typescript`.
+- Copy `custom/skills/execute-flow/templates/playwright.config.ts` → `AK-Docs/03.Testing/05.Scripts/{repo}/playwright.config.ts`, điền `baseURL` = BASE_URL của repo đó.
+- Copy `custom/skills/execute-flow/templates/evidence-helper.ts` → `AK-Docs/03.Testing/05.Scripts/Shared/evidence-helper.ts` (không tạo lại nếu đã tồn tại).
+- `featureDir` = `{ScreenID}_{Screen-Name-kebab-case}` (vd `AD10_create-product`), khớp naming convention của `docs/common/Testing-Structure.md`.
 
-Nếu bất kỳ check nào fail → dừng, hướng dẫn fix. Không proceed.
+> **Vì sao không dùng node_modules riêng cho mỗi repo:** tránh cài `@playwright/test` + Chromium nhiều lần, chỉ cần 1 lần install ở `05.Scripts/` là chạy được cho toàn bộ project.
 
 ### Bước 1: Parse TC file
 
@@ -102,7 +166,7 @@ Phân loại sơ bộ:
 
 ### Bước 3: Scan scripts 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`:
 - Nếu tồn tại: đọc `@tc-id` comments → xác định TCs đã có script
 - Tính hash cho từng TC → so với `@tc-hash` trong file → xác định `updated` vs `skipped`
 - Nếu không tồn tại: tất cả automation TCs đều là `new`
@@ -152,8 +216,10 @@ Gọi `script-sync` skill với context:
 - `tcFile`: path TC file
 - `repo`: từ Gate 1
 - `screenId`: always lowercase ScreenID (vd `ad10`, not `AD10`) — directory path uses lowercase
+- `featureDir`: `{ScreenID}_{Screen-Name-kebab-case}` (vd `AD10_create-product`)
 - `screenUrl`: hỏi tester nếu chưa biết: "URL path của màn hình {ScreenID} là gì? (vd `/admin/products/create`)"
 - `baseUrl`: từ `BASE_URL` env var
+- `scriptsRoot`: `AK-Docs/03.Testing/05.Scripts/{repo}/` (script + Page Object nằm ở đây)
 
 Nhận về: danh sách kết quả per TC.
 
@@ -165,7 +231,7 @@ Gen mới: {N} | Updated: {N} | Skipped: {N}
 Manual (Untest): {N} TCs
 Blocked: {N} TCs — xem lý do bên trên
 
-→ Review: [ak-test/{repo}/scripts/{screenId}/{ScreenID}.spec.ts](ak-test/{repo}/scripts/{screenId}/{ScreenID}.spec.ts)
+→ Review: [AK-Docs/03.Testing/05.Scripts/{repo}/{featureDir}/{ScreenID}.spec.ts](AK-Docs/03.Testing/05.Scripts/{repo}/{featureDir}/{ScreenID}.spec.ts)
 → Type APPROVED to run tests
 → Type SKIP: {TC_ID} để đánh dấu Pending và tiếp tục
 → Or provide feedback to fix scripts
@@ -182,44 +248,50 @@ Chỉ chạy sau Gate 2 APPROVED.
 
 ### Bước 1: Xác định run number
 
-Scan `ak-test/{repo}/results/{screenId}/` để tìm run folder hiện có:
+Scan `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/` để tìm run folder hiện có (nguồn sự thật cho run number):
 - Nếu không có folder nào → `run-1`
 - Nếu có `run-1`, `run-2` → `run-3`
 
-Tạo folder: `ak-test/{repo}/results/{screenId}/run-{N}/`
+Tạo 2 folder song song cho run này (evidence vs report/bug, xem "Cấu trúc thư mục đầu ra"):
+- `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/` — evidence nhị phân (screenshots, video, `trace.zip`)
+- `AK-Docs/03.Testing/02.Reports/{repo}/{featureDir}/run-{N}/` — `result.md` + `testreport.md`
 
 ### Bước 2: Chạy Playwright
 
+Script nằm trong `AK-Docs/03.Testing/05.Scripts/{repo}/`, evidence nhị phân (screenshot/video/trace) ghi trực tiếp vào `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/` — dùng env var `EVIDENCE_DIR` để `playwright.config.ts` set `outputDir` động (xem template). Vì `04.Evidence/` và `05.Scripts/` đều là con trực tiếp của `03.Testing/`, chỉ cần đi lên 1 cấp:
+
 ```bash
-cd ak-test/{repo}
-BASE_URL={baseUrl} npx playwright test scripts/{screenId}/{ScreenID}.spec.ts
+cd AK-Docs/03.Testing/05.Scripts
+EVIDENCE_DIR="$(pwd)/../04.Evidence/{repo}/{featureDir}/run-{N}" \
+BASE_URL={baseUrl} \
+npx playwright test --config={repo}/playwright.config.ts {repo}/{featureDir}/{ScreenID}.spec.ts
 ```
 
-Note: Reporters are already configured in `playwright.config.ts` (json → `test-results/results.json`, html, list). The CLI `--reporter` flag would override these settings, so it is omitted here.
+Note: Reporters đã được config trong `playwright.config.ts` (json → `{EVIDENCE_DIR}/results.json`, html, list) — CLI `--reporter` flag sẽ override nên không dùng ở đây.
 
 ### Bước 3: Parse kết quả
 
-Đọc `ak-test/{repo}/test-results/results.json` (Playwright JSON output).
+Đọc `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/results.json` (Playwright JSON output, ghi trực tiếp vào evidence dir nhờ `EVIDENCE_DIR`).
 
 Với mỗi test:
 - Extract TC_ID từ test title (format: `AD10_001 - {name}` hoặc `[AD10_001] {name}`)
 - Map: TC_ID → `{status: 'passed'|'failed', duration, attachments, errors}`
 
-### Bước 4: Tổ chức Evidence
+**Cross-check trước khi ghi PASS/FAIL** (xem "DOM Verification Rules" bên dưới) — không tin tuyệt đối vào exit code của Playwright, phải verify lại assertion có thực sự map đúng Expected Result trong TC file.
+
+### Bước 4: Tổ chức Evidence + Report
 
 Với mỗi TC:
 
-**Tạo folder:** `ak-test/{repo}/results/{screenId}/run-{N}/{TC_ID}-{kebab-scenario}/`
+**Evidence (ở `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/{TC_ID}-{kebab-scenario}/`)** — Playwright ghi trực tiếp vào đây nhờ `EVIDENCE_DIR`, không cần copy tay:
+- Screenshots per-step → `step-NN-{desc}.png` (xem "Evidence Quality Rules" — mỗi step trong TC Steps phải có 1 screenshot riêng, không chỉ chụp cuối cùng)
+- Trace file → `trace.zip`
 
 Với `kebab-scenario` = Test Case Name lowercase, dấu cách thành `-`, bỏ ký tự đặc biệt.
 
-Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/testcase input — xem `custom/rules/output-language.md` và `custom/skills/test-skills/rules/qa-writing-standards.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh; tiêu đề cột bảng vẫn giữ tiếng Anh).
-
-**Copy files từ Playwright output:**
-- Screenshots → `step-NN-{desc}.png`
-- Trace file → `trace.zip`
+**Report (`AK-Docs/03.Testing/02.Reports/{repo}/{featureDir}/run-{N}/{TC_ID}-{kebab-scenario}/result.md`)** — file text, không chứa binary:
 
-**Tạo `result.md`:**
+Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/testcase input — xem `custom/rules/output-language.md` và `custom/skills/test-skills/rules/qa-writing-standards.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh; tiêu đề cột bảng vẫn giữ tiếng Anh).
 
 Khi PASS:
 ```markdown
@@ -230,6 +302,8 @@ Khi PASS:
 **Run:** run-{N} | {YYYY-MM-DD HH:MM}
 
 ## Evidence
+→ `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/{TC_ID}-{kebab-scenario}/`
+
 | Step | Screenshot |
 |------|-----------|
 | {step 1} | step-01-{desc}.png |
@@ -248,20 +322,22 @@ Khi FAIL:
 **Error:** {error message từ Playwright}
 
 ## Evidence
+→ `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/{TC_ID}-{kebab-scenario}/`
+
 | File | Mô tả |
 |------|-------|
 | failure-screenshot.png | Trạng thái lúc fail |
 | trace.zip | Playwright trace |
 
 ## Bug Reference
-→ Xem: bugs/BUG-{NNN}-{slug}.md
+→ Xem: `AK-Docs/03.Testing/06.Bugs/{repo}/{featureDir}/run-{N}/BUG-{NNN}-{slug}.md`
 ```
 
-Với Manual TCs (Untest): không tạo evidence folder.
+Với Manual TCs (Untest): không tạo evidence folder / result.md.
 
 ### Bước 5: Auto-draft Bug Reports
 
-Với mỗi TC failed, tạo `ak-test/{repo}/results/{screenId}/run-{N}/bugs/BUG-{NNN}-{slug}.md`:
+Với mỗi TC failed, tạo `AK-Docs/03.Testing/06.Bugs/{repo}/{featureDir}/run-{N}/BUG-{NNN}-{slug}.md`:
 
 ```markdown
 # BUG-{NNN} — {Test Case Name}
@@ -288,8 +364,8 @@ Với mỗi TC failed, tạo `ak-test/{repo}/results/{screenId}/run-{N}/bugs/BUG
 
 ## Evidence
 
-- Screenshot: `{TC_ID}-{scenario}/failure-screenshot.png`
-- Playwright trace: `{TC_ID}-{scenario}/trace.zip`
+- Screenshot: `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/{TC_ID}-{scenario}/failure-screenshot.png`
+- Playwright trace: `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/{TC_ID}-{scenario}/trace.zip`
 
 ## Technical Notes
 
@@ -305,7 +381,31 @@ Với mỗi TC failed, tạo `ak-test/{repo}/results/{screenId}/run-{N}/bugs/BUG
 - [ ] Retest: `RETEST: {TC_ID}`
 ```
 
-BUG số: đếm file trong `bugs/` folder, +1. Format: `001`, `002`,...
+BUG số: đếm file trong `AK-Docs/03.Testing/06.Bugs/{repo}/{featureDir}/run-{N}/` folder, +1. Format: `001`, `002`,...
+
+### DOM Verification Rules (bắt buộc — tránh false pass/fail)
+
+Script-sync (Gate 2) chịu trách nhiệm sinh assertion đúng, nhưng Gate 3 vẫn phải verify lại trước khi ghi kết quả — vì nguyên nhân phổ biến khiến "TC fail bị báo thành pass" hoặc ngược lại là assertion quá lỏng hoặc chọn nhầm phần tử, không phải do Playwright chạy sai:
+
+- ❌ **Không** coi "test không throw exception" = pass. Phải có ít nhất 1 `expect(...)` khẳng định đúng **nội dung** Expected Result của TC (text, giá trị, trạng thái field, số lượng item...), không chỉ `toBeVisible()` chung.
+- ❌ **Không** dùng locator quá rộng (vd `page.locator('.modal')` khi có nhiều `.modal` trên trang, hoặc `page.locator('button').first()` khi có nhiều button cùng loại) — nếu locator match nhiều hơn 1 element, đây chính là nguyên nhân hay gặp khiến assertion pass "nhầm" vào element khác không phải element cần kiểm tra. Dùng `data-testid`/`id` cụ thể hoặc scope locator trong đúng container (`page.locator('#order-detail').getByText(...)`).
+- ❌ **Không** dùng `try/catch` nuốt lỗi rồi coi là pass nếu catch block không re-throw hoặc không có assertion thay thế.
+- ✅ Khi TC yêu cầu "hiển thị message lỗi X" → assertion phải check đúng text X (`toHaveText`/`toContainText`), không chỉ check element lỗi tồn tại.
+- ✅ Khi TC yêu cầu "field Y bị disable/readonly" → assertion phải là `toBeDisabled()`/`toHaveAttribute('readonly', ...)`, không phải `toBeVisible()`.
+- ✅ Sau khi Playwright báo `passed`, nếu kịch bản TC là **negative/validation case** (kỳ vọng lỗi/chặn hành động) mà spec không có assertion kiểm tra đúng behavior chặn đó → đánh dấu **NEEDS_REVIEW** trong result.md thay vì tin theo status "passed" của Playwright, và note lại trong Gate 3 summary để tester tự kiểm tra bằng mắt qua evidence.
+- ✅ Nếu Playwright báo `failed` do lỗi hạ tầng (timeout do element chưa load kịp, network flake, không phải do app sai) → thử lại tối đa 1 lần (`--retries=1` đã có trong config) trước khi kết luận FAIL và draft bug — tránh báo fail giả do timing.
+
+### Evidence Quality Rules (bắt buộc)
+
+Giải quyết vấn đề "chụp evidence sai thời điểm / mờ / thiếu step / không mở được modal":
+
+1. **Thời điểm chụp:** Nếu TC không có yêu cầu cụ thể về thời điểm chụp, luôn gọi `waitForUiSettled(page)` (từ `Shared/evidence-helper.ts`) trước khi screenshot — hàm này chờ `networkidle` **và** không còn spinner/loading indicator (`[data-loading]`, `.spinner`, `.loading`, role `progressbar`...) **và** fonts đã load xong (`document.fonts.ready`). Không chụp ngay sau khi trigger action.
+2. **Chất lượng ảnh:** Dùng `page.screenshot({ fullPage: true, animations: 'disabled', scale: 'css' })` qua helper — không dùng screenshot mặc định của reporter. Config `deviceScaleFactor: 2` trong `playwright.config.ts` để ảnh sắc nét (đặc biệt chữ Kanji/Katakana). Nếu app hiển thị tiếng Nhật, set `locale: 'ja-JP'` trong config để đúng font rendering, và đảm bảo container/CI có font Nhật (Noto Sans JP) cài sẵn — nếu không có, ảnh sẽ hiện ô vuông/mờ chữ dù code đúng.
+3. **Popup/Modal cần click để mở:** Nếu TC Step mô tả hành động mở popup/modal (vd "Click vào item A để mở modal B1") → script **phải thực hiện click đó** rồi `waitForUiSettled` trước khi chụp bước đó — không chụp màn hình danh sách rồi bỏ qua bước mở modal.
+4. **Nội dung có scroll:** Nếu vùng cần chụp (modal, table, page) cao hơn viewport → dùng `scrollIntoViewIfNeeded()` trên phần tử cần confirm trước khi chụp, hoặc chụp `fullPage: true` cho toàn trang nếu modal không giới hạn scroll riêng. Không chụp full page nếu modal có scroll riêng nội bộ — trong trường hợp đó chụp riêng viewport của modal sau khi cuộn tới đúng vị trí.
+5. **Highlight vùng cần confirm:** Trước khi chụp step có 1 item/element cụ thể cần tester chú ý (item vừa click, message lỗi, field vừa thay đổi...) → gọi `highlightElement(page, selector)` (khoanh viền đỏ 3px + không che nội dung) ngay trước `page.screenshot()`, rồi gọi `removeHighlight(page)` ngay sau đó để không ảnh hưởng bước tiếp theo.
+6. **1 screenshot cho mỗi Step có mô tả UI trong TC:** Nếu TC Steps mô tả nhiều bước điều hướng (vd: "1. Trên màn hình danh sách, click item A để mở A1 → 2. Trên A1, click button B để mở modal B1") → chụp **evidence riêng cho từng bước có thay đổi màn hình/state đáng chú ý**, không chỉ chụp kết quả cuối. Với ví dụ trên: `step-01-{...}.png` (màn hình danh sách, khoanh đỏ item A trước khi click) + `step-02-{...}.png` (màn hình A1, khoanh đỏ button B trước khi click) + `step-03-{...}.png` (modal B1 mở ra, khoanh đỏ nội dung cần confirm). File `step-NN-{desc}.png` đặt tên theo đúng thứ tự Step trong TC file.
+7. Dùng helper `captureStepEvidence(page, evidenceDir, stepIndex, stepDesc, { highlightSelector, scrollSelector })` (xem `templates/evidence-helper.ts`) trong mọi spec mới sinh ra ở Gate 2 — không tự viết lại logic wait/highlight/scroll/screenshot rời rạc trong từng test.
 
 ### Bước 6: Hiển thị Gate 3
 
@@ -321,7 +421,7 @@ Results (run-{N}):
 Bugs drafted: {N} ({N} Critical, {N} High, {N} Medium, {N} Low)
 Unresolved critical: {N}
 
-→ Evidence: ak-test/{repo}/results/{screenId}/run-{N}/
+→ Evidence: AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/
 → Type APPROVED when all critical/high bugs resolved
 → Type RETEST: {TC_ID} to re-execute
 → Type PENDING: {TC_ID} để đánh dấu TC không chạy được
@@ -337,11 +437,13 @@ Khi tester gõ `RETEST: AD10_005, AD10_008`:
    - Nếu phát hiện commit mới → đề xuất TC bổ sung, tester approve delta trước
 2. **Chạy selective test:**
    ```bash
-   cd ak-test/{repo}
-   BASE_URL={baseUrl} npx playwright test --grep "AD10_005|AD10_008"
+   cd AK-Docs/03.Testing/05.Scripts
+   EVIDENCE_DIR="$(pwd)/../04.Evidence/{repo}/{featureDir}/run-{N+1}" \
+   BASE_URL={baseUrl} \
+   npx playwright test --config={repo}/playwright.config.ts --grep "AD10_005|AD10_008"
    ```
 3. Xác định run number mới (run-{N+1})
-4. Tổ chức evidence vào `run-{N+1}/` (không xóa run cũ)
+4. Tổ chức evidence vào `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N+1}/` + report vào `AK-Docs/03.Testing/02.Reports/{repo}/{featureDir}/run-{N+1}/` (không xóa run cũ)
 5. Cập nhật bug status:
    - TC pass sau retest → ghi `RESOLVED` vào bug file: `**Status:** ✅ Resolved`
    - TC vẫn fail → ghi `**Retest {N}:** Still OPEN` vào bug file
@@ -356,15 +458,15 @@ Chỉ chạy sau Gate 3 APPROVED.
 
 ### Bước 1: Tổng hợp kết quả
 
-Đọc tất cả `result.md` trong `run-{N}/`:
+Đọc tất cả `result.md` trong `AK-Docs/03.Testing/02.Reports/{repo}/{featureDir}/run-{N}/`:
 - Count passed/failed/untest/pending per run
 - Identify last run number (run-{max})
 
-Đọc `bugs/BUG-*.md` trong run folder: phân loại severity + status (Open/Resolved).
+Đọc `AK-Docs/03.Testing/06.Bugs/{repo}/{featureDir}/run-{N}/BUG-*.md`: phân loại severity + status (Open/Resolved).
 
 ### Bước 2: Sinh testreport.md
 
-Tạo `ak-test/{repo}/results/{screenId}/run-{N}/testreport.md` theo template chuẩn:
+Tạo `AK-Docs/03.Testing/02.Reports/{repo}/{featureDir}/run-{N}/testreport.md` theo template chuẩn:
 
 ```markdown
 # SUMMARY TEST REPORT
@@ -404,7 +506,7 @@ Hỏi từng bug theo thứ tự severity (Critical → High → Medium → Low)
 
 ```
 🐛 BUG-{NNN} [{Severity}] — {Title}
-   TC: {TC_ID} | Evidence: run-{N}/bugs/BUG-{NNN}...
+   TC: {TC_ID} | Bug: AK-Docs/03.Testing/06.Bugs/{repo}/{featureDir}/run-{N}/BUG-{NNN}... | Evidence: AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/{TC_ID}-{scenario}/
    Steps: {steps tóm tắt}
    Expected: {expected}
    Actual: {actual}
@@ -428,7 +530,7 @@ Passed: {N}/{total} | % hoàn thành: {N}%
 Bugs logged to Jira: {N}/{total bugs}
 Recommendation: {Go / No-go / Conditional go}
 
-→ Review: [ak-test/{repo}/results/{screenId}/run-{N}/testreport.md](ak-test/{repo}/results/{screenId}/run-{N}/testreport.md)
+→ Review: [AK-Docs/03.Testing/02.Reports/{repo}/{featureDir}/run-{N}/testreport.md](AK-Docs/03.Testing/02.Reports/{repo}/{featureDir}/run-{N}/testreport.md)
 → Type APPROVED to sign off
 → Type NO-GO: {reason} to reject release
 
@@ -466,7 +568,11 @@ SKIP-BUG: BUG-{NNN}                   # bỏ qua không log bug này
 ## Mandatory Rules
 
 - ✅ Dừng ở mỗi gate, chờ APPROVED trước khi proceed
-- ✅ `run-{N}` không bao giờ bị xóa hay overwrite — luôn tạo folder mới
+- ✅ `run-{N}` không bao giờ bị xóa hay overwrite — luôn tạo folder mới (cả ở `04.Evidence/`, `02.Reports/` và `06.Bugs/`)
 - ✅ Hỏi từng bug một — không auto-log toàn bộ
+- ✅ Evidence nhị phân (screenshot/video/`trace.zip`) luôn ở `AK-Docs/03.Testing/04.Evidence/` — **phải nằm trong `.gitignore`**, không commit lên Git
+- ✅ Script/result/report/bug (text) luôn ở `AK-Docs/03.Testing/{05.Scripts,02.Reports,06.Bugs}/` — không dùng `ak-test/` nữa
+- ✅ Trước khi ghi PASS/FAIL vào result.md, verify lại assertion theo "DOM Verification Rules" — không tin tuyệt đối exit code Playwright
+- ✅ Mọi spec mới sinh dùng `captureStepEvidence()` từ `Shared/evidence-helper.ts` cho evidence — không viết lại logic wait/highlight/scroll rời rạc
 - ❌ Không lấy expected result từ PR/code — chỉ từ TC file
 - ❌ Không skip gate kể cả khi "chỉ có 1 TC"

package/custom/skills/execute-flow/templates/evidence-helper.ts

@@ -0,0 +1,145 @@
+import type { Page, Locator, TestInfo } from '@playwright/test'
+
+/**
+ * Shared evidence helpers for generated Playwright specs (execute-flow / script-sync skills).
+ * Copied once to AK-Docs/03.Testing/05.Scripts/Shared/evidence-helper.ts — do not regenerate
+ * if it already exists; hand edits (e.g. project-specific loading selectors) must survive re-sync.
+ */
+
+/** CSS selectors treated as "still loading" — extend this list per-project if needed. */
+const LOADING_SELECTORS = [
+  '[data-loading="true"]',
+  '.spinner',
+  '.loading',
+  '.skeleton',
+  '[role="progressbar"]',
+]
+
+/**
+ * Waits until the page is visually stable before a screenshot is taken:
+ * network idle, no known loading indicator visible, and web fonts finished loading
+ * (prevents blurry / tofu-box Kanji text in evidence screenshots).
+ */
+export async function waitForUiSettled(page: Page, timeoutMs = 15_000): Promise<void> {
+  await page.waitForLoadState('networkidle', { timeout: timeoutMs }).catch(() => {})
+
+  await page.waitForFunction(
+    (selectors) =>
+      selectors.every((sel) => {
+        const el = document.querySelector(sel)
+        if (!el) return true
+        const style = window.getComputedStyle(el)
+        return style.display === 'none' || style.visibility === 'hidden'
+      }),
+    LOADING_SELECTORS,
+    { timeout: timeoutMs },
+  ).catch(() => {})
+
+  await page.evaluate(() => (document as any).fonts?.ready).catch(() => {})
+}
+
+/** Draws a 3px solid red outline around `target` without shifting layout (outline, not border). */
+export async function highlightElement(target: Locator): Promise<void> {
+  await target.evaluate((el: HTMLElement) => {
+    el.setAttribute('data-evidence-highlight', '1')
+    el.style.outline = '3px solid #ff0000'
+    el.style.outlineOffset = '2px'
+  })
+}
+
+/** Removes the highlight applied by `highlightElement` so it doesn't leak into the next step's screenshot. */
+export async function removeHighlight(target: Locator): Promise<void> {
+  await target
+    .evaluate((el: HTMLElement) => {
+      el.style.outline = ''
+      el.style.outlineOffset = ''
+      el.removeAttribute('data-evidence-highlight')
+    })
+    .catch(() => {})
+}
+
+export interface CaptureStepOptions {
+  /** Element to draw a red rectangle around before the screenshot (the item/content the tester must confirm). */
+  highlightSelector?: Locator
+  /** Element to scroll into view before the screenshot (for content inside a scrollable modal/table). */
+  scrollSelector?: Locator
+  /** Screenshot the full page instead of the current viewport. Default: true. */
+  fullPage?: boolean
+}
+
+/**
+ * Captures one evidence screenshot for one TC Step, following the naming convention
+ * `step-NN-{desc}.png` inside the run's evidence dir (Playwright's configured outputDir,
+ * i.e. `EVIDENCE_DIR` — see playwright.config.ts template).
+ *
+ * Call this once per TC Step that changes UI state or navigates to a new screen/modal —
+ * not just once at the end of the test.
+ */
+export async function captureStepEvidence(
+  page: Page,
+  testInfo: TestInfo,
+  stepIndex: number,
+  stepDesc: string,
+  opts: CaptureStepOptions = {},
+): Promise<void> {
+  await waitForUiSettled(page)
+
+  if (opts.scrollSelector) {
+    await opts.scrollSelector.scrollIntoViewIfNeeded()
+    await waitForUiSettled(page)
+  }
+
+  if (opts.highlightSelector) {
+    await highlightElement(opts.highlightSelector)
+  }
+
+  const slug = stepDesc
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/(^-|-$)/g, '')
+  const fileName = `step-${String(stepIndex).padStart(2, '0')}-${slug}.png`
+
+  await page.screenshot({
+    path: testInfo.outputPath(fileName),
+    fullPage: opts.fullPage ?? true,
+    animations: 'disabled',
+    scale: 'css',
+  })
+
+  if (opts.highlightSelector) {
+    await removeHighlight(opts.highlightSelector)
+  }
+}
+
+/**
+ * Convenience wrapper for steps that click a trigger to open a popup/modal, then capture
+ * the resulting state. Ensures the click happens BEFORE the screenshot — a common source
+ * of "modal never shown in evidence" bugs.
+ */
+export async function openAndCapture(
+  page: Page,
+  testInfo: TestInfo,
+  trigger: Locator,
+  resultLocator: Locator,
+  stepIndex: number,
+  stepDesc: string,
+  opts: CaptureStepOptions = {},
+): Promise<void> {
+  await highlightElement(trigger)
+  await page.screenshot({
+    path: testInfo.outputPath(`step-${String(stepIndex).padStart(2, '0')}-before-click.png`),
+    fullPage: opts.fullPage ?? true,
+    animations: 'disabled',
+  })
+  await removeHighlight(trigger)
+
+  await trigger.click()
+  await resultLocator.waitFor({ state: 'visible' })
+
+  await captureStepEvidence(page, testInfo, stepIndex, stepDesc, {
+    ...opts,
+    highlightSelector: opts.highlightSelector ?? resultLocator,
+  })
+}

package/custom/skills/execute-flow/templates/playwright.config.ts

@@ -3,24 +3,44 @@ import path from 'path'
 
 const LOGGED_OUT = { storageState: undefined }
 
+// Script lives in AK-Docs/03.Testing/05.Scripts/{repo}/ but binary evidence (screenshots,
+// video, trace.zip, results.json) must land in AK-Docs/03.Testing/04.Evidence/ instead —
+// that folder is gitignored (binaries, never committed) while this script folder is not.
+// See execute-flow SKILL.md "Cấu trúc thư mục đầu ra". The AI sets EVIDENCE_DIR per run
+// (03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}) when invoking `npx playwright test`.
+const evidenceDir = process.env.EVIDENCE_DIR
+  ? path.resolve(process.env.EVIDENCE_DIR)
+  : path.resolve(__dirname, 'test-results')
+
 export default defineConfig({
-  testDir: './scripts',
-  outputDir: './test-results',
+  testDir: '.',
+  outputDir: evidenceDir,
   fullyParallel: false,
   forbidOnly: !!process.env.CI,
-  retries: process.env.CI ? 1 : 0,
+  retries: 1, // absorb transient timing flakes before reporting FAIL — see "DOM Verification Rules"
   workers: 1,
   reporter: [
-    ['json', { outputFile: 'test-results/results.json' }],
-    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['json', { outputFile: path.join(evidenceDir, 'results.json') }],
+    ['html', { outputFolder: path.join(evidenceDir, 'html-report'), open: 'never' }],
     ['list'],
   ],
   use: {
     baseURL: process.env.BASE_URL || 'http://localhost:3000',
-    trace: 'on-first-retry',
-    screenshot: 'on',
-    video: 'on-first-retry',
+    trace: 'retain-on-failure',
+    // Manual per-step screenshots come from captureStepEvidence() in evidence-helper.ts —
+    // this stays 'only-on-failure' so it doesn't duplicate/clash with those step-NN-*.png files.
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
     headless: !process.env.HEADED,
+    // Higher device scale factor = sharper text in evidence, especially Kanji/Katakana.
+    deviceScaleFactor: 2,
+    // Set to the app's actual UI locale so date/number formatting and font fallback match
+    // what the browser renders in production — mismatched locale is a common cause of
+    // "screenshot color/rendering doesn't match what I see in my own browser" reports.
+    locale: process.env.UI_LOCALE || 'ja-JP',
+    viewport: { width: 1440, height: 900 },
+    // Stops CSS/JS animations from being mid-transition when a screenshot fires.
+    reducedMotion: 'reduce',
   },
   projects: [
     // Uncomment nếu cần auth setup:

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.