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

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/shared/gate-workflow.md

@@ -475,9 +475,10 @@ Pre-flight checks (stop and report if any fail):
    - If Y: read and update `~/.claude/settings.json` by merging the playwright entry into `mcpServers`, then instruct TESTER to **restart Claude Code** before retrying. Stop here.
    - If n: show manual install instructions (add `playwright` to `mcpServers` in `~/.claude/settings.json`). Stop here.
 1. TC file is parseable — Section 3 has at least one TC row
-2. `ak-test/{repo}/` directory exists (or offer to scaffold it)
+2. `AK-Docs/03.Testing/` subfolders exist (`04.Evidence/`, `05.Scripts/`, `02.Reports/`, `06.Bugs/` — auto-create if missing)
 3. `BASE_URL` env var is set
-4. `ak-test/{repo}/playwright.config.ts` exists (or offer to create from template)
+4. `AK-Docs/03.Testing/05.Scripts/{repo}/playwright.config.ts` exists (or auto-scaffold the Playwright project inside AK-Docs — package.json, node_modules gitignored — see `execute-flow` SKILL.md "Scaffold Playwright Project")
+5. `.gitignore` (repo root containing AK-Docs) ignores `03.Testing/04.Evidence/` (binary evidence, never committed even though it lives inside AK-Docs) and `03.Testing/05.Scripts/**/{node_modules,test-results,playwright-report,blob-report}/` — auto-append if missing
 
 Then display work plan:
 
@@ -516,7 +517,7 @@ Hash-based TC↔script sync — for each TC in the file:
 - **Unchanged TC** (hash matches): skip — do not touch.
 - **Manual/Blocked TC**: mark `⏭️ Untest` / `⏳ Pending` — no script generated.
 
-Output: `ak-test/{repo}/scripts/{screenId}/{ScreenID}.spec.ts` (1 file per screen, all TCs inside)
+Output: `AK-Docs/03.Testing/05.Scripts/{repo}/{featureDir}/{ScreenID}.spec.ts` (1 file per screen, all TCs inside). Every TC Step that changes UI must call `captureStepEvidence()` from `Shared/evidence-helper.ts` (waits for loading to finish, opens popups/modals via click before capturing, scrolls to the confirm area, red-outline highlights the item to confirm) and every assertion must check the actual Expected Result content — not just element presence. See `script-sync` SKILL.md "Assertion Rules" / "Evidence Capture per Step".
 
 - **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-2-[ticket-id].md`
 - Display gate pause message from `gate-review` skill — wait for **APPROVED**
@@ -544,17 +545,22 @@ Chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đ
 
 **Step 3.1 — Determine run number**
 
-Check `ak-test/{repo}/results/{screenId}/` — next run is `run-{N+1}`.
+Check `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/` — next run is `run-{N+1}`.
 
-**Step 3.2 — Execute Playwright**
+**Step 3.2 — Execute Playwright** (script and evidence both live inside AK-Docs; evidence stays out of Git via `.gitignore`, not via a separate working dir):
 
 ```bash
-BASE_URL=<url> 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=<url> \
+npx playwright test --config={repo}/playwright.config.ts {repo}/{featureDir}/{ScreenID}.spec.ts
 ```
 
-**Step 3.3 — Organize evidence** into `ak-test/{repo}/results/{screenId}/run-{N}/`:
-- Per-TC folder `{TC_ID}-{scenario}/` with `step-NN-{desc}.png`, `trace.zip`, `result.md`
-- Auto-draft `bugs/BUG-NNN-{slug}.md` for failed TCs
+**Step 3.3 — Organize evidence + report:**
+- Evidence (already written directly to `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/{TC_ID}-{scenario}/`, gitignored): `step-NN-{desc}.png` per Step, `trace.zip`
+- Report (`AK-Docs/03.Testing/02.Reports/{repo}/{featureDir}/run-{N}/{TC_ID}-{scenario}/result.md`) — text only, links back to the `04.Evidence/` path
+- Before recording PASS/FAIL, re-check that the assertion actually matches the TC's Expected Result content (not just "did not throw") — see `execute-flow` SKILL.md "DOM Verification Rules"
+- Auto-draft `AK-Docs/03.Testing/06.Bugs/{repo}/{featureDir}/run-{N}/BUG-NNN-{slug}.md` for failed TCs
 
 **Step 3.4 — Update TC file** R1/R2 columns:
 - `✅ Pass` · `❌ Fail` · `⏭️ Untest` · `⏳ Pending`
@@ -593,7 +599,7 @@ Only runs after Gate 3 APPROVED.
 
 Chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file. Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.
 
-**Step 4.1** — Generate `ak-test/{repo}/results/{screenId}/run-{N}/testreport.md`:
+**Step 4.1** — Generate `AK-Docs/03.Testing/02.Reports/{repo}/{featureDir}/run-{N}/testreport.md`:
 - Per-module rows with Pass/Fail/Untest/Pending counts, R1/R2 columns, % completion
 - Go/No-Go: 0 unresolved Critical = Go
 
@@ -609,7 +615,7 @@ Wait for reply before moving to next bug.
 ⏸️ GATE 4: REPORT READY
 Decision: [GO / NO-GO]
 Bugs logged: [N] | Skipped: [N]
-→ 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
 ```
 

package/docs/common/CHANGELOG.md

@@ -9,6 +9,14 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-08-24
+
+### Changed
+
+- **`execute-test` flow (`execute-flow` + `script-sync` skills) no longer uses an `ak-test/` working dir at all — everything, including binary evidence, now lives inside `AK-Docs/03.Testing/`.** Previously the whole flow (Playwright scripts, per-TC `result.md`, bug drafts, `testreport.md`, and evidence) lived under `ak-test/{repo}/`, outside the project's docs tree — reports/bugs/scripts had no place in version control alongside the rest of `AK-Docs/03.Testing/` (Testcases, Reports, Bugs). New mapping: `05.Scripts/{repo}/{featureDir}/{ScreenID}.spec.ts` (Gate 2), `04.Evidence/{repo}/{featureDir}/run-{N}/` (Gate 3, screenshots/video/`trace.zip`/raw `results.json`), `02.Reports/{repo}/{featureDir}/run-{N}/{result.md, testreport.md}` (Gate 3/4), `06.Bugs/{repo}/{featureDir}/run-{N}/BUG-NNN-*.md` (Gate 3) — this restores `docs/common/Testing-Structure.md`'s original Gate 3 → `04.Evidence/` mapping instead of diverging from it (an earlier iteration of this change had evidence live in `ak-test/` to keep binaries out of AK-Docs entirely; superseded before release in favor of `.gitignore`). `05.Scripts/` is a self-contained, runnable Playwright project (`package.json`/`node_modules`/`tsconfig.json`) living inside AK-Docs — Gate 1 auto-scaffolds it and appends `03.Testing/04.Evidence/` plus `03.Testing/05.Scripts/**/{node_modules,test-results,playwright-report,blob-report}` to `.gitignore` if missing, so the binary evidence and Playwright build artifacts never get committed even though they're colocated with the rest of the docs tree. `playwright.config.ts`'s `outputDir`/JSON reporter path read `EVIDENCE_DIR` (set by the AI per run to the `04.Evidence/` path, a simple 1-level-up relative path from `05.Scripts/` since both now live under the same `03.Testing/` parent) so each run gets its own evidence folder.
+
+- **`execute-flow`/`script-sync` gained explicit DOM-assertion and evidence-quality rules** to fix reported false pass/fail results and low-quality screenshots: locators that match more than one element are now called out as the primary root cause of mis-graded TCs (fix: scope to the right container or use `data-testid`, not `.first()`/broad CSS); assertions must check the actual Expected Result content (`toHaveText`/`toBeDisabled`/etc.), not just element presence; negative/validation TCs need an assertion on the actual blocking behavior, not "page didn't crash." New shared helper `custom/skills/execute-flow/templates/evidence-helper.ts` (copied once to `AK-Docs/03.Testing/05.Scripts/Shared/`) provides `waitForUiSettled()` (networkidle + no loading indicator + fonts ready — fixes screenshots taken mid-spinner), `highlightElement()`/`removeHighlight()` (red 3px outline around the item to confirm), and `captureStepEvidence()`/`openAndCapture()` (per-TC-Step screenshot, click-to-open-modal before capturing, `scrollIntoViewIfNeeded()` for scrollable content) — every generated spec must use these instead of ad-hoc screenshot calls. `playwright.config.ts` template gained `deviceScaleFactor: 2` and a configurable `locale` (default `ja-JP`) for sharper, correctly-rendered Kanji/Katakana text in evidence, plus 1 retry to absorb timing flakes before a TC is reported FAIL.
+
 ## [0.2.1] - 2026-08-17
 
 ### Added

package/docs/common/INDEX.md

@@ -29,6 +29,7 @@
 | `99.Memory/` Project Brain — full design, scoring model, mem-id scheme, role/PM permissions | [Memory-Architecture-v1.0.md](./Memory-Architecture-v1.0.md) | v1.1 — Phase 1 (`draft/list/submit/remove`) is what's implemented today; later phases in this doc are roadmap, not shipped yet |
 | How updates to `AK-Docs`/`Shared-Docs` get reviewed — branch/Merge Request flow, who can merge to `main` | [Docs-Management-Flow.md](./Docs-Management-Flow.md) | Doc's own header says `Trạng thái: Draft — chờ PM review` — flag that when answering, don't present it as final policy |
 | PM/BrSE/Comtor — ingest a Backlog/Jira/SharePoint link or pasted text into `AK-Docs/01.QnA/` | [Project-Structure.md](./Project-Structure.md) (§ `01.QnA/`), `.claude/skills/ingest-data/SKILL.md` | `ak use` → taskType `ingest-data`, 2-gate flow (fetch/classify/draft → branch+MR). SharePoint link fetch is **not connected yet** — falls back to pasted text |
+| Any role — how to read `System-Requirement_v{N}.md` (who reads which field, Classification/Implementation Reference/Tech Reference meaning), why it's separate from UC Spec, and how to review/approve it without reading code | [System-Requirement-Read-Guide.md](./System-Requirement-Read-Guide.md) | Field glossary + Classification state machine (Gap/Assumption/Decision/Deviation) + FAQ (why not merge with UC Spec, who writes it, when to update) + 6-step review checklist |
 
 ## Unanswered topics (do not invent — say so and stop here)
 

package/docs/common/QUICK_START.md

@@ -382,7 +382,7 @@ ak execute ./testcases/AD10.md        # AI starts execute-flow with this TC file
 ak execute                            # AI asks: "TC file ở đâu?"
 ```
 
-Output lands in `ak-test/{repo}/results/{screenId}/run-{N}/` — never deleted between runs.
+Evidence (screenshots/video/trace.zip) lands in `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/` — never deleted between runs. Scripts, result/report/bug docs live in `AK-Docs/03.Testing/` instead (05.Scripts / 02.Reports / 06.Bugs) so they're versioned with the rest of the project's docs, while binary evidence stays out of that git history.
 
 ### Figma Design → Code
 

package/docs/common/System-Requirement-Read-Guide.md

@@ -0,0 +1,178 @@
+# Hướng Dẫn Đọc System Requirement (mọi role)
+
+> **Dành cho:** bất kỳ ai cần đọc một `System-Requirement_v{N}.md` — PM, Comtor, BrSE, Tester, Dev, Tech Lead. Mục tiêu của tài liệu này: giúp bạn biết **mình cần đọc phần nào**, đọc xong hiểu đúng, không cần đọc code hay đọc hết mọi dòng.
+> **Tài liệu được đọc:** `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v{N}.md`, sinh ra bởi task type **"📐 Create System Requirement"** — cầu nối giữa UC Spec (BA) và code (Dev).
+> **Nếu bạn là người duyệt (approve)** tài liệu này, xem thêm Mục 5 (Checklist) — phần còn lại của guide vẫn áp dụng, checklist chỉ là bước cuối.
+
+---
+
+## 1. Ai đọc phần nào
+
+Mỗi `System-Requirement_v{N}.md` đã có sẵn bảng này ngay ở đầu file (nói 1 lần, không lặp lại theo từng dòng). Nhắc lại ở đây để bạn không cần mở file mới nhớ ra:
+
+| Field trong tài liệu | Ai cần đọc |
+|---|---|
+| `Requirement` | PM/BrSE/Comtor, Tester |
+| `System Behavior` | Tester |
+| `Error Response` | Tester (đầy đủ, gồm HTTP code) — PM/BrSE/Comtor chỉ cần câu thông báo hiển thị |
+| `Traced UC Ref` / `Traced UC BR` / `Traced Exception Flow` | PM/BrSE/Comtor (đối chiếu UC Spec) |
+| `Classification` | PM/BrSE/Comtor — dấu hiệu "cần quyết định" hoặc "đã chốt" |
+| `Implementation Reference` / `Tech Reference` | Dev |
+| Mục 5 (Acceptance Test Scenarios) | Tester |
+
+**Dev và AI đọc toàn bộ tài liệu.** Nếu bạn là PM/Comtor/BrSE và thấy 1 dòng `Implementation Reference` mình không hiểu — đó là bình thường, **bỏ qua**, không phải bạn thiếu kiến thức.
+
+---
+
+## 2. Cách đọc 1 item (Requirement/System Behavior/Implementation Reference)
+
+`System-Requirement_v{N}.md` được thiết kế theo 3 tầng, mỗi tầng cho 1 nhóm người đọc khác nhau trong **cùng một item**:
+
+| Tầng | Viết bằng | Dành cho | Bạn cần đọc? |
+|---|---|---|---|
+| **Requirement** | Ngôn ngữ nghiệp vụ, không có tên class/method/framework | PM, Comtor, BrSE, **Tester** | ✅ Luôn đọc |
+| **System Behavior** | Vẫn ngôn ngữ thường, mô tả điều kiện/thứ tự xử lý | BA, Tester | ✅ Luôn đọc |
+| **Error Response** | HTTP code + message hiển thị cho end-user | Tester | ✅ Đọc nếu là Validation/Exception |
+| **Implementation Reference / Tech Reference** | file:line, class, method, enum | Dev | ❌ **Bỏ qua được** — không phải Dev thì không cần đọc |
+
+**Nguyên tắc:** nếu bạn phải đọc `Implementation Reference` để hiểu `Requirement` đang nói gì, đó là **lỗi của tài liệu** (leak kỹ thuật lên tầng nghiệp vụ) — báo lại cho Dev viết lại, không phải bạn thiếu kiến thức.
+
+---
+
+## 3. Giải thích về Classification
+
+Mỗi item (FR/NFR/VR/ER) có thể mang 1 trong 4 nhãn `Classification`.
+
+| Nhãn | Nghĩa | Ai tạo ra | Hành động bạn cần làm |
+|---|---|---|---|
+| **Gap** | UC Spec chưa có nội dung này | Dev, khi viết tài liệu | PM/BA phải trả lời. **Còn Gap chưa trả lời → tài liệu chưa được approve.** |
+| **Assumption** | Dev suy đoán, chưa ai xác nhận | Dev | PM confirm → thành Decision. PM reject → quay lại Gap |
+| **Decision** | Đã chốt, có ngày và người chốt | Sau khi PM trả lời | Chỉ đọc, không cần hành động |
+| **Deviation** | Code hiện tại khác UC Spec | Dev, khi so sánh với code thật | BA/PM chọn: sửa code theo UC Spec, hoặc sửa UC Spec theo code |
+
+### Khi 1 item có nhiều quyết định — cách đọc
+
+Trường hợp 1 item có **2+ quyết định** liên quan (ví dụ BA chốt 1 phần, Dev chốt phần còn lại). Ví dụ:
+
+```
+Classification: Gap → Decision
+  - OQ-35 (BA): sử dụng mã lượt đặt hàng để xác định yêu cầu đặt hàng trùng và tránh tạo đơn nhiều lần.
+  - D-03 (Dev): nếu mã lượt đặt hàng đã được xử lý, không tạo đơn mới; trả về HTTP 400 kèm đơn đã tạo trước đó. Mã có hiệu lực trong 30 phút.
+```
+
+Cách đọc: mỗi dòng là **1 mã số + ai chốt + nội dung ngắn**.
+- `OQ-xx` = quyết định gốc do BA chốt, kế thừa từ UC Spec (thường trong lúc Q&A trước khi UC Spec được ký duyệt).
+- `D-xx` = quyết định phát sinh riêng khi Dev soạn tài liệu System Requirement này (ví dụ: UC Spec chốt "phải chống trùng đơn" nhưng chưa viết rõ máy chủ trả gì — Dev phải tự chốt thêm chi tiết kỹ thuật đó, ghi lại thành D-xx để không tự quyết ngầm).
+
+Nếu bạn không nhớ hoặc không đồng ý với 1 trong các quyết định đó, nêu lại ngay — đừng chờ tới khi ra sản phẩm.
+
+---
+
+## 4. Workflow trạng thái Classification
+
+```mermaid
+%%{init: {'flowchart': {'curve': 'linear'}}}%%
+flowchart TD
+    Start([Dev viết draft]) --> Gap[Gap]
+    Gap -->|"PM/BA trả lời chắc chắn"| Decision[Decision]
+    Gap -->|"PM/BA trả lời<br/>nhưng chưa chắc 100%"| Assumption[Assumption]
+    Assumption -->|"PM confirm đúng"| Decision
+    Assumption -->|"PM reject / cần hỏi lại"| Gap
+    Decision -->|"sau này Dev thấy<br/>code thực tế khác"| Deviation[Deviation]
+    Deviation -->|"PM chọn sửa code<br/>theo UC Spec (đã fix xong)"| Decision
+    Deviation -->|"PM chọn giữ code, sửa UC Spec<br/>(BA cập nhật UC Spec, tăng version mới)"| Decision
+```
+
+**Rule:** tài liệu **không được approve** khi còn item ở trạng thái `Gap` chưa trả lời. `Assumption` được phép tồn tại tạm nếu PM đã xác nhận "tạm chấp nhận, sẽ chốt sau" — nhưng phải ghi rõ trong Mục 8 (Decision Log), không được im lặng bỏ qua.
+
+---
+
+## 5. Checklist Review (dành cho người duyệt — không cần đọc code)
+
+Làm theo đúng thứ tự — dừng và reject ngay khi 1 bước fail.
+
+### Bước 1 — Đọc Executive Summary (30 giây)
+- [ ] `Traceability coverage` = X/X? Thiếu → tài liệu chưa đầy đủ, trả lại Dev.
+- [ ] `Action needed from PM` có danh sách → đây là Gap/Assumption bạn phải trả lời **trước**, ngay tại bước này.
+
+### Bước 2 — Khớp 1-1 với UC Spec (Mục 0 — Traceability Matrix)
+- [ ] Mở UC Spec `v{N}` ghi ở header song song.
+- [ ] Mỗi Main/Alternative/Exception Flow, mỗi Business Rule trong UC Spec → tìm đúng 1 dòng tương ứng trong Traceability Matrix.
+- [ ] Thiếu dòng nào → **reject**.
+
+### Bước 3 — Đọc tầng Requirement (Mục 1–4)
+- [ ] Chỉ đọc `Requirement` + `System Behavior` — bỏ qua `Implementation Reference`.
+- [ ] Thấy tên class/method/framework lọt vào `Requirement`/`System Behavior` → **reject**, yêu cầu viết lại.
+- [ ] Với Validation/Exception: `Error Response` phải giữ HTTP code + message hiển thị.
+
+### Bước 4 — Xử lý từng nhãn Classification
+- [ ] `Gap`/`Assumption` → trả lời theo workflow ở Mục 4.
+- [ ] `Deviation` → chọn rõ: sửa code hay sửa UC Spec — không để lơ lửng.
+- [ ] `Decision` → chỉ xác nhận đúng là điều đã chốt; không nhớ đã chốt → hỏi lại, đừng mặc định đúng.
+
+### Bước 5 — Đối chiếu Mục 7 (Assumptions/Gaps/Decisions/Deviations)
+- [ ] Mọi item có nhãn ở Mục 1–4 phải có dòng tương ứng ở Mục 7. Thiếu → reject.
+
+### Bước 6 — Quyết định
+- [ ] Còn `Gap` chưa trả lời → **không approve**.
+- [ ] Pass hết Bước 1–5 → gõ `APPROVED`.
+
+---
+
+## 6. Câu hỏi thường gặp (FAQ)
+
+### System Requirement để làm gì? Tôi có UC Spec rồi thì cần gì System Requirement nữa?
+
+UC Spec và System Requirement trả lời 2 câu hỏi khác nhau:
+
+- **UC Spec (BA viết)** trả lời: *"hệ thống PHẢI làm gì theo mong muốn của khách/nghiệp vụ?"* — viết **trước khi** biết chắc code hiện tại đang làm gì, không cần Dev tham gia để ký duyệt.
+- **System Requirement (Dev viết, sau khi đọc UC Spec + mở code thật ra đối chiếu)** trả lời: *"code hiện tại đã làm đúng chưa? Còn thiếu gì? Có tình huống nào UC Spec không viết tới nhưng hệ thống vẫn phải xử lý?"*
+
+Ví dụ thật trong tài liệu BUY074: UC Spec chỉ viết "chống bán vượt tồn kho", nhưng KHÔNG viết tới tình huống "2 khách đặt cùng 1 sản phẩm cùng lúc thì ai thắng, ai thua, giỏ của người thua xử lý sao, có bị deadlock không nếu đơn có nhiều sản phẩm giao nhau". Đây là những **Gap** mà chỉ khi Dev đọc code + tưởng tượng ra kịch bản thật mới phát hiện được — BA khi viết UC Spec không có đủ góc nhìn kỹ thuật để lường trước. System Requirement chính là nơi những Gap này được phát hiện, hỏi lại BA/PM, và ghi lại chốt là gì.
+
+Nói ngắn: **UC Spec = ý định. System Requirement = ý định đó khi va vào code thật thì phải cụ thể hoá ra sao.**
+
+### Vì sao không gộp UC Spec và System Requirement thành 1 tài liệu, review 1 lần cho gọn?
+
+3 lý do:
+
+1. **Thời điểm ký duyệt khác nhau.** UC Spec phải được BA/PM ký duyệt **trước**, không cần chờ Dev có thời gian đọc hết code. Nếu gộp 2 tài liệu, UC Spec sẽ bị kẹt chờ Dev investigate code xong mới ký được — làm chậm cả quy trình dù bản chất nghiệp vụ đã rõ và có thể duyệt độc lập với chi tiết kỹ thuật.
+2. **Người review và tiêu chí review khác nhau.** Review UC Spec cần Dev đánh giá "khả thi kỹ thuật ở mức khái niệm" + Tester đánh giá "khả năng test được ở mức khái niệm". Review System Requirement cần Dev + Tester **đối chiếu từng dòng với UC Spec** (khác câu hỏi, khác độ chi tiết) — trộn 2 việc vào 1 lần review dễ khiến người review làm qua loa 1 trong 2, thay vì làm kỹ cả 2.
+3. **Traceability rõ ràng hơn khi tách riêng.** Mỗi `System-Requirement_v{N}` phải matching đúng 1 phiên bản UC Spec (`UC-Spec-Version` header) — nếu 2 tài liệu là một, việc UC Spec đổi version (do yêu cầu nghiệp vụ đổi) và System Requirement đổi version (do Dev phát hiện thêm case khi code) sẽ lẫn vào nhau, khó biết cái gì đổi vì lý do gì.
+
+**Nhưng:** Dự án có thể linh hoạt sắp xếp gộp 1 buổi review chung cho 2 tài liệu này, trong trường hợp có thể output 2 tài liệu cùng nhau thay vì phải chờ 1 khoảng thời gian dài để Dev điều tra.
+
+### System Requirement có được phép thay đổi/thêm nội dung so với UC Spec không?
+
+Không. System Requirement **không bao giờ bịa ra** nội dung mà UC Spec không có — mọi FR/VR/ER phải trace được về 1 dòng cụ thể trong UC Spec, hoặc được đánh dấu `Gap`/`Assumption`/`Deviation` và chờ PM/BA xác nhận. Nếu bạn thấy 1 `Requirement` mà không tìm được nguồn trong UC Spec, đó là lỗi — báo lại ngay (xem Bước 2/3 ở Mục 5).
+
+### Khi nào cần viết lại/update System Requirement?
+
+Hai trường hợp: (1) UC Spec lên version mới (BA sửa yêu cầu) → System Requirement phải `RESYNC` theo version mới; (2) trong lúc code 1 ticket, Dev phát hiện 1 case UC Spec có viết nhưng System Requirement bỏ sót → được đề xuất bổ sung, ghi thêm 1 dòng ở Change Log (Mục 9), không cần tăng version vì UC Spec chưa đổi.
+
+### Mục 8 (Decision Log) chỉ có 1 dòng ngắn — thiếu thông tin à?
+
+Không thiếu — chủ ý tránh viết trùng 2 nơi. Chi tiết đầy đủ đã nằm trong dòng `Classification` của item tương ứng ở Mục 1–4; Mục 8 chỉ là bảng tra cứu ngược (ID → ai chốt → ngày → 1 dòng tóm tắt).
+
+### Tôi không hiểu `Implementation Reference` ghi gì, có sao không?
+
+Tuỳ role. Nếu bạn là **PM/BrSE/Comtor/Tester** — không sao, tầng đó không dành cho bạn (xem Mục 1, 2); nếu bạn *cần* hiểu nó để đánh giá đúng/sai của `Requirement`, đó là lỗi tài liệu — báo lại, đừng tự trách mình thiếu kiến thức.
+
+Nếu bạn là **Dev** — **bắt buộc phải hiểu**, vì đây chính là field ghi cho bạn (file:line/class/method để code) và AI cũng dựa vào nó ở Gate 3 coding. Không hiểu được thì không phải lỗi của bạn cần bỏ qua, mà là dấu hiệu tài liệu viết thiếu rõ (ví dụ thiếu context, path sai, hoặc tham chiếu tới code không còn tồn tại) — cần hỏi lại người viết (Dev khác/AI) hoặc tự mở code kiểm tra trước khi bắt đầu implement, không được đoán.
+
+### `Tech Reference` trong Mục 6.2 (Glossary) khác gì `Implementation Reference`?
+
+`Implementation Reference` nằm rải trong từng item, chỉ Dev cần. `Tech Reference` ở Mục 6.2 là **bảng tra cứu tập trung** — mỗi giá trị kỹ thuật (ví dụ enum `TagStatusEnum::PENDING`) map sang 1 ý nghĩa nghiệp vụ đã được PM xác nhận (`Decision`) hoặc chưa (`Assumption`). Dùng bảng này khi muốn biết "giá trị thô này nghĩa là gì với nghiệp vụ" mà không cần lục từng item.
+
+### Tài liệu này có thay UC Spec không?
+
+Không. UC Spec là nguồn nghiệp vụ gốc (BA sign-off). System Requirement là bản dịch sang góc nhìn Dev + trace lại UC Spec.
+
+---
+
+## 7. Liên quan
+
+- Skill sinh ra tài liệu này: `.claude/skills/create-system-requirement/SKILL.md`
+- Template: `.claude/skills/create-system-requirement/system-requirement-template-v1.md`
+- Cấu trúc thư mục `02.BA-Specs/`: [BA-Specs-Structure.md](./BA-Specs-Structure.md)
+- Quy trình SDLC end-to-end (Checkpoint #2/#3, gộp thread review): `docs/internal/SDLC-Unified-Workflow_v1.0.md`

package/docs/common/Testing-Structure.md

@@ -38,30 +38,34 @@
 │       ├── Users.csv
 │       └── Fixtures.sql
 │
-├── 04.Evidence/                            # Gate 3: Screenshots, videos, logs per execution
-│   └── F-001_User-Login/
-│       ├── TICKET-100_2026-06-15/          # Ticket + date to identify execution round
-│       │   ├── TC_001_PASS/
-│       │   │   └── Screenshot.png
-│       │   └── TC_002_FAIL/
-│       │       ├── Screenshot.png
-│       │       └── Video.mp4
-│       └── TICKET-100_Retest_2026-06-18/
-│           └── TC_002_PASS/
-│               └── Screenshot.png
+├── 04.Evidence/                            # ⚠️ MUST be in .gitignore — binary (screenshots/video/trace.zip)
+│   ├── F-001_User-Login/                   # manual QA evidence (screenshots attached by hand)
+│   │   └── TICKET-100_2026-06-15/          # Ticket + date to identify execution round
+│   │       └── TC_003_PASS/
+│   │           └── Screenshot.png
+│   └── {repo}/{featureDir}/run-{N}/        # execute-test flow's AUTOMATION evidence (Gate 3)
+│       ├── results.json                    # Playwright JSON output
+│       └── {TC_ID}-{scenario}/
+│           ├── step-NN-{desc}.png
+│           └── trace.zip
 │
-├── 05.Scripts/                             # Playwright automation (by Repo → Feature)
+├── 05.Scripts/                             # Playwright automation — RUNNABLE project (by Repo → Feature)
+│   ├── package.json                        # 1 install for the whole 05.Scripts tree
+│   ├── tsconfig.json
+│   ├── node_modules/                       # gitignored — see Rules
+│   ├── Shared/                             # Fixtures, helpers, evidence-helper used across repos
+│   │   ├── fixtures/test.ts
+│   │   ├── BasePage.ts
+│   │   └── evidence-helper.ts              # waitForUiSettled / highlightElement / captureStepEvidence
 │   ├── Repo1/                              # e.g. frontend app
-│   │   ├── playwright.config.ts            # baseURL, browser config for this repo
+│   │   ├── playwright.config.ts            # baseURL, EVIDENCE_DIR-driven outputDir for this repo
+│   │   ├── pages/LoginPage.ts
 │   │   └── F-001_User-Login/
 │   │       └── Login.spec.ts
-│   ├── Repo2/                              # e.g. admin app
-│   │   ├── playwright.config.ts
-│   │   └── F-003_Admin-Panel/
-│   │       └── Admin.spec.ts
-│   └── Shared/                             # Fixtures, helpers used across repos
-│       ├── Fixtures.ts
-│       └── Helpers.ts
+│   └── Repo2/                              # e.g. admin app
+│       ├── playwright.config.ts
+│       └── F-003_Admin-Panel/
+│           └── Admin.spec.ts
 │
 ├── 06.Bugs/                                # Gate 3: Bug reports (AI draft on TC fail)
 │   └── F-001_User-Login/
@@ -109,9 +113,9 @@
 | Gate | Output | Folder |
 |---|---|---|
 | Gate 1 | Chuẩn bị & Lập kế hoạch thực thi | (Console output / Work Plan) |
-| Gate 2 | Đồng bộ kịch bản kiểm thử (Script Sync) | `05.Scripts/[Repo]/[Feature]/[Feature].spec.ts` |
-| Gate 3 | Thực thi test & Thu thập evidence | `04.Evidence/[Feature]/[Ticket]_[Date]/` & `06.Bugs/[Feature]/` |
-| Gate 4 | Báo cáo test & Log bug | `02.Reports/[Feature]/[Ticket]/Execution-Report.md` |
+| Gate 2 | Đồng bộ kịch bản kiểm thử (Script Sync) | `05.Scripts/[Repo]/[Feature]/[Feature].spec.ts` (project chạy được tại chỗ — có `package.json`/`node_modules`) |
+| Gate 3 | Thực thi test & Thu thập evidence | Binary evidence (screenshot/video/`trace.zip`) → `04.Evidence/[Repo]/[Feature]/run-{N}/` (gitignored, xem Rules) & bug reports (text) → `06.Bugs/[Repo]/[Feature]/run-{N}/` |
+| Gate 4 | Báo cáo test & Log bug | `02.Reports/[Repo]/[Feature]/run-{N}/testreport.md` |
 
 ---
 
@@ -119,6 +123,8 @@
 
 - Không tự sửa template — template nằm trong shared repo riêng
 - Lưu testcase và kết quả lên GitLab **sau khi Gate 4 được APPROVED**
-- Khi retest: tạo subfolder `TICKET-XXX_Retest_Date/` mới trong Evidence — không ghi đè cũ
-- `05.Scripts/` chỉ chứa `.spec.ts` và `playwright.config.ts` — không chứa testcase `.md`
+- Khi retest: tạo subfolder `run-{N+1}/` mới trong Evidence & Reports — không ghi đè cũ
+- `05.Scripts/` là 1 Playwright project chạy tại chỗ trong AK-Docs (`.spec.ts`, `playwright.config.ts`, `pages/`, `Shared/` fixtures + `evidence-helper.ts`, `package.json`, `node_modules/`) — không chứa testcase `.md`
+- `05.Scripts/**/node_modules/`, `test-results/`, `playwright-report/`, `blob-report/` **phải** nằm trong `.gitignore` của repo chứa AK-Docs — execute-flow Gate 1 tự kiểm tra và thêm nếu thiếu
+- **`04.Evidence/` phải nằm trong `.gitignore`** — dù chứa cả evidence tay (manual QA) và evidence automation (execute-test), toàn bộ nội dung là binary (screenshot/video/`trace.zip`), không commit lên Git. Không có `ak-test/` hay working dir nào khác ngoài AK-Docs cho flow này nữa.
 - `07.AI-Artifacts/` là working docs của AI — không phải tài liệu chính thức

package/docs/common/cli-reference.md

@@ -171,19 +171,21 @@ ak execute                                   # manual — AI asks for TC file
 - `[target]` — Optional. A ticket ID (`PROJ-44`), a path to a TC file (`./testcases/AD10.md`), or omitted for manual entry.
 
 **What it does (4 gates):**
-1. **Gate 1 — Pre-flight:** Parse TC file, verify `ak-test/{repo}/` and `playwright.config.ts` exist, check `BASE_URL`
-2. **Gate 2 — Script Sync:** Hash-based sync — gen new TCs, update changed, skip unchanged. Uses Playwright MCP for real selectors (never fabricates).
-3. **Gate 3 — Execute & Evidence:** Run Playwright, organize evidence into `run-{N}/`, update TC file R1/R2 columns (`✅ Pass` · `❌ Fail` · `⏭️ Untest` · `⏳ Pending`)
-4. **Gate 4 — Report & Bug Logging:** Generate `testreport.md`, confirm each bug with TESTER before logging to Jira
+1. **Gate 1 — Pre-flight:** Parse TC file, verify `AK-Docs/03.Testing/` subfolders and `AK-Docs/03.Testing/05.Scripts/{repo}/playwright.config.ts` exist (auto-scaffold if missing), check `BASE_URL`
+2. **Gate 2 — Script Sync:** Hash-based sync — gen new TCs, update changed, skip unchanged. Uses Playwright MCP for real selectors (never fabricates). Every step captures evidence via `evidence-helper.ts` and asserts on actual Expected Result content (see "DOM Verification Rules" in `execute-flow` SKILL.md).
+3. **Gate 3 — Execute & Evidence:** Run Playwright from `AK-Docs/03.Testing/05.Scripts/`, evidence written into `AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/` via `EVIDENCE_DIR`, update TC file R1/R2 columns (`✅ Pass` · `❌ Fail` · `⏭️ Untest` · `⏳ Pending`)
+4. **Gate 4 — Report & Bug Logging:** Generate `testreport.md` in AK-Docs, confirm each bug with TESTER before logging to Jira
 
 **Output structure:**
 ```
-ak-test/{repo}/
-├── scripts/{screenId}/{ScreenID}.spec.ts
-└── results/{screenId}/run-{N}/
-    ├── {TC_ID}-{scenario}/  (screenshots, trace.zip, result.md)
-    ├── bugs/BUG-NNN-{slug}.md
-    └── testreport.md
+AK-Docs/03.Testing/
+├── 04.Evidence/{repo}/{featureDir}/run-{N}/            # gitignored — screenshots, trace.zip
+│   └── {TC_ID}-{scenario}/
+├── 05.Scripts/{repo}/{featureDir}/{ScreenID}.spec.ts   # runnable Playwright project
+├── 02.Reports/{repo}/{featureDir}/run-{N}/
+│   ├── {TC_ID}-{scenario}/result.md
+│   └── testreport.md
+└── 06.Bugs/{repo}/{featureDir}/run-{N}/BUG-NNN-{slug}.md
 ```
 
 **Example:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.2.1",
+  "version": "0.2.2-beta.0",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Example Team",
   "publishConfig": {

package/scripts/prompt.js

@@ -386,16 +386,16 @@ Follow gates IN ORDER. Do NOT skip or merge gates.
 
 ### GATE 1 — Pre-flight & Work Plan (auto-start)
 **INVOKE:** \`execute-flow\` skill
-Check: MCP Playwright configured, TC file is parseable, \`ak-test/{repo}/\` scaffold exists, \`BASE_URL\` set, Playwright config exists. Display the work plan (TC file, repo, screen, BASE_URL) → wait for **APPROVED**.
+Check: MCP Playwright configured, TC file is parseable, \`AK-Docs/03.Testing/\` subfolders exist (\`04.Evidence/\`, \`05.Scripts/\`, \`02.Reports/\`, \`06.Bugs/\`), \`BASE_URL\` set, \`AK-Docs/03.Testing/05.Scripts/{repo}/playwright.config.ts\` exists (auto-scaffold if missing), \`.gitignore\` covers \`03.Testing/04.Evidence/\` and \`05.Scripts/**/node_modules\`. Display the work plan (TC file, repo, screen, BASE_URL) → wait for **APPROVED**.
 
 ### GATE 2 — Script Sync
 Only runs after Gate 1 APPROVED.
 **INVOKE:** \`script-sync\` skill
-Hash-based TC↔script sync: new TC → generate Playwright test via MCP snapshot/locator (never fabricate selectors); changed TC → update; unchanged → skip; manual/blocked → mark Untest/Pending. Display new/updated/skipped/manual counts → wait for **APPROVED**.
+Hash-based TC↔script sync: new TC → generate Playwright test via MCP snapshot/locator (never fabricate selectors, never use a locator matching more than one element); changed TC → update; unchanged → skip; manual/blocked → mark Untest/Pending. Every step calls \`captureStepEvidence()\` from \`Shared/evidence-helper.ts\`. Display new/updated/skipped/manual counts → wait for **APPROVED**.
 
 ### GATE 3 — Execute & Evidence
 Only runs after Gate 2 APPROVED.
-Run \`BASE_URL=<url> npx playwright test scripts/{screenId}/{ScreenID}.spec.ts\`, organize evidence (screenshots/trace/result.md) into \`ak-test/{repo}/results/{screenId}/run-{N}/\`, auto-draft bug reports for failures, update R1/R2 columns in the TC file. Supports \`RETEST: [TC_ID]\` and \`PR: [url]\`. Display pass/fail/untest/pending counts → wait for **APPROVED** (all Critical/High bugs resolved).
+Run from \`AK-Docs/03.Testing/05.Scripts/\` with \`EVIDENCE_DIR\` pointed at \`AK-Docs/03.Testing/04.Evidence/{repo}/{featureDir}/run-{N}/\` (gitignored), organize evidence (screenshots/trace) there and text output (\`result.md\`, \`testreport.md\`) into \`AK-Docs/03.Testing/02.Reports/{repo}/{featureDir}/run-{N}/\`, auto-draft bug reports into \`AK-Docs/03.Testing/06.Bugs/{repo}/{featureDir}/run-{N}/\`, update R1/R2 columns in the TC file. Cross-check assertions against the TC's actual Expected Result before recording PASS/FAIL — don't trust Playwright's exit code alone. Supports \`RETEST: [TC_ID]\` and \`PR: [url]\`. Display pass/fail/untest/pending counts → wait for **APPROVED** (all Critical/High bugs resolved).
 
 ### GATE 4 — Report & Bug Logging (wait for APPROVED)
 Only runs after Gate 3 APPROVED.

package/scripts/scaffold-playwright.js

@@ -18,7 +18,9 @@ const HARNESS_FILES = [
 
 const GITIGNORE_LINES = [
   '# Playwright',
+  'node_modules/',
   'playwright-report/',
+  'blob-report/',
   'test-results/',
   'tests/e2e/.auth/',
   '.env',