@relipa/ai-flow-kit 0.1.9 → 0.2.0-beta.1

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

@@ -83,6 +83,8 @@ evidence/
 
 Với mỗi TC, tạo `evidence/TC_[ID]-[scenario]/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).
+
 **Template khi PASS:**
 
 ```markdown

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

@@ -213,6 +213,8 @@ Với mỗi TC:
 
 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`

package/custom/skills/explore-data/SKILL.md

@@ -71,6 +71,8 @@ Write the EDA results into the `ml-problem.md` file created by `frame-ml-problem
 - Leakage assessment — one paragraph per leakage type stating what was checked and what was found
 - Cleaning actions required before training (drop columns, impute, clip outliers, re-encode)
 
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
+
 ---
 
 ## Completion Checklist

package/custom/skills/frame-ml-problem/SKILL.md

@@ -86,3 +86,5 @@ If any of the above cannot be answered from the ticket, ask exactly **one questi
 - [ ] Success threshold quantified (not "as high as possible")
 - [ ] Constraints listed (latency, memory, interpretability, data volume, compliance)
 - [ ] Findings written to `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` (see `custom/rules/ml-conventions.md` — do NOT use the legacy `plan/[ticket-id]/` path)
+
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).

package/custom/skills/gate-review/SKILL.md

@@ -57,6 +57,8 @@ When generating the output for a gate (e.g. `requirement.md` or `plan.md`), foll
 ### Step 2: Write the gate output file
 Write the gate output file (e.g. `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md`, `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md`, or `docs/ak-[project]/...`) as specified by the gate instructions.
 
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
+
 ### Step 3: Display gate pause message
 
 Instruct the user to review the generated document. Tell them that they can hover over any line and add inline comments in VS Code using the native commenting UI, or edit the file to add standard HTML comments `<!-- comment -->` if they are not using the VS Code extension.

package/custom/skills/generate-spec/SKILL.md

@@ -75,6 +75,8 @@ Create a detailed step-by-step plan based on the requirement document:
 ```
 ```
 
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
+
 > For UI tasks, reference the exact node/component from `design-context.md` in the Task column
 > (e.g. "Build UserCard — nodeId 78-910"). Add an image-copy task when the Image Map is non-empty.
 >

package/custom/skills/generate-test-report/SKILL.md

@@ -61,6 +61,8 @@ Tổng hợp per module theo format template (R1/R2 tracking từ testcase files
 
 Output: `test-plan/test-report.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).
+
 ---
 
 ## Gate 4 Display

package/custom/skills/generate-testcase/SKILL.md

@@ -65,6 +65,8 @@ Xác định phạm vi ảnh hưởng thật từ code dev **trước khi** gene
 
 Liệt kê scenarios theo nhóm, output vào `test-plan/checklist.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).
+
 | ID | Scenario/Checklist Item | Mục đích kiểm tra | Expected Result |
 
 **Nhóm cần cover:**

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

@@ -91,6 +91,8 @@ List all:
 [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

package/custom/skills/improve-algorithm/SKILL.md

@@ -61,6 +61,8 @@ Revert if it does not satisfy the above. Log the failure reason; failed experime
 
 Repeat steps 3–5 for the next bottleneck. Log every attempt — including reversions — so the improvement story is fully reproducible. The final state must be explainable: "we tried X (failed because Y), then tried Z (improved metric by W%)."
 
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
+
 ---
 
 ## Completion Checklist

package/custom/skills/ingest-data/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: ingest-data
+description: Use when taskType is "ingest-data" — PM/BrSE/Comtor ingesting customer communication (Backlog ticket/comment/Document/Wiki link, Jira link, SharePoint link, or pasted text) into AK-Docs/01.QnA/ logs. Covers fetching the source, classifying it into QnA-Log/Meetings-Log/Confirmations-Log, drafting the entry for self-review before Gate 2 opens the MR, and — auto right after Gate 2 — analyzing the entry to propose a PM-approved task list that gets created as real Backlog/Jira tickets.
+keywords: ingest data, comtor, brse, pm workflow, meeting minutes, qna log, confirmations log, backlog document, backlog wiki, sharepoint, gate 1, gate 2, gate 3, sinh task, tạo ticket
+---
+
+# Ingest Data — Gate 1 (fetch/classify/draft)
+
+> **Vai trò:** PM · BrSE · Comtor. **Bối cảnh đầy đủ:** `docs/internal/PM Workflow_v1.0.md` (Flow A + Flow B).
+> Gate mechanics (khi nào chạy Gate 1 vs Gate 2) nằm ở `custom/templates/shared/gate-workflow.md` § "ingest-data Task Type". File này chỉ mô tả **cách làm** của Gate 1: fetch nguồn → phân loại → soạn draft.
+
+---
+
+## 1. Input được hỗ trợ
+
+| Input | Cách xử lý |
+|---|---|
+| Backlog ticket link (`/view/PROJ-N`) hoặc comment (`#comment-N`) | `ak fetch-links "<url>"` → JSON `{ sourceType: "ticket" \| "comment", ... }` |
+| Backlog Document link (`/document/{id}` hoặc `/alias/document/{id}`) | `ak fetch-links "<url>"` → JSON `{ sourceType: "document" \| "document-comment", ... }`. ⚠️ API Document của Nulab còn mới (2026) — nếu lệnh trả lỗi HTTP 404, báo lại cho người dùng, đây là dấu hiệu endpoint cần điều chỉnh, không phải lỗi ở phía bạn. |
+| Backlog Wiki link (`/alias/wiki/{id}`) | `ak fetch-links "<url>"` → JSON `{ sourceType: "wiki", ... }` |
+| Jira ticket/comment link | `ak fetch-links "<url>"` → JSON `{ sourceType: "ticket" \| "comment", ... }` |
+| SharePoint link (`*.sharepoint.com`) | `ak fetch-links "<url>"` → `{ sourceType: "unsupported", reason: "sharepoint-not-configured" }`. **Không có connector** (cần Microsoft Graph API + OAuth, xem PM Workflow doc "Vấn đề 4" — chưa làm POC). Hiển thị `message` trong JSON cho người dùng, và đề nghị: "Paste trực tiếp nội dung comment/tài liệu vào chat, mình sẽ dùng luôn." |
+| Plain text (paste trực tiếp trong chat, hoặc `ak use --manual`) | Dùng nguyên văn `description` từ `.aiflow/context/current.json` — không cần fetch gì thêm. |
+
+Nếu input không khớp bất kỳ dạng nào ở trên (`ak fetch-links` trả lỗi "Not a recognized... URL", exit code 1) → hỏi lại người dùng: link có đúng không, hoặc paste nội dung trực tiếp.
+
+---
+
+## 2. Phân loại — QnA-Log / Meetings-Log / Confirmations-Log
+
+| Log | Khi nào dùng | Nguồn điển hình |
+|---|---|---|
+| `QnA-Log.md` | Trao đổi hỏi-đáp thông thường với khách hàng | Backlog ticket/comment, Jira ticket/comment, SharePoint comment (paste text), text ngắn |
+| `Meetings-Log.md` | Tổng hợp nội dung 1 buổi họp (khách hoặc nội bộ) | Backlog Document, Backlog Wiki, text dài có cấu trúc (attendees/agenda/action items) |
+| `Confirmations-Log.md` | Mốc khách hàng **CHỐT chính thức** một spec/thay đổi | Bất kỳ nguồn nào, miễn nội dung là 1 xác nhận dứt điểm |
+
+**Heuristic gợi ý** (không phải luật cứng):
+- Nội dung có "họp", "meeting", "kickoff", "sprint review", danh sách người tham dự → nghiêng về **Meetings-Log**.
+- Nội dung có "confirm", "chốt", "OK approved", "đồng ý chính thức", đi kèm 1 quyết định rõ ràng, dứt điểm → nghiêng về **Confirmations-Log**.
+- Còn lại (hỏi/đáp, feedback, trao đổi qua lại chưa dứt điểm) → **QnA-Log**.
+
+> ⚠️ **Quy tắc phân biệt "confirm chính thức" vs "trao đổi thường" CHƯA được PM chốt** (xem `PM Workflow_v1.0.md` § "Vấn đề còn mở" #1). Khi không chắc content nào — **luôn hỏi lại người dùng** để chọn log đích, không tự quyết định âm thầm. Một khi PM ra quy tắc rõ ràng, cập nhật heuristic ở đây.
+
+---
+
+## 3. Template từng file (dùng đúng, không tự đổi cấu trúc)
+
+Cả 3 file nằm trong `AK-Docs/01.QnA/` (giữ nguyên tên thư mục hiện có — **không** đổi thành `01.Communications/` như một phương án còn đang chờ PM chốt trong `PM Workflow_v1.0.md`; nếu PM sau này quyết định đổi tên thư mục, đó là một task migration riêng).
+
+Nếu file đích **chưa tồn tại**, tạo file mới với đúng header dưới đây rồi mới append entry.
+
+### 3.1 `QnA-Log.md` (file có sẵn — mở rộng thêm cột `Nguồn`)
+
+Header hiện tại của file có thể chỉ có 5 cột (`Date | Asked By | Question | Answer | Status`). Nếu vậy, **thêm cột `Nguồn` vào cuối** (sửa header + backfill các dòng cũ bằng `—`) rồi mới append dòng mới — để mọi entry từ giờ đều trace được nguồn gốc (yêu cầu traceability, xem PM Workflow doc § "Vấn đề 6"):
+
+```markdown
+| Date | Asked By | Question | Answer | Status | Nguồn |
+|---|---|---|---|---|---|
+| 2026-08-04 | Khách hàng ABC | <tóm tắt câu hỏi> | <tóm tắt câu trả lời, hoặc "—" nếu chưa có> | Pending / Answered | [<mô tả ngắn>](<url hoặc "pasted text">) |
+```
+
+### 3.2 `Meetings-Log.md` (file mới — tạo nếu chưa có)
+
+```markdown
+# Meetings Log
+
+> Meeting minutes với khách hàng hoặc nội bộ — tổng hợp bởi Comtor/BrSE, PM approve tại nguồn trước khi ingest vào đây (xem Flow A trong PM Workflow_v1.0.md).
+
+---
+
+## [YYYY-MM-DD] <Tiêu đề buổi họp>
+
+| Trường | Giá trị |
+|---|---|
+| **Nguồn** | [<mô tả ngắn>](<url Backlog Document/Wiki, hoặc "pasted text">) |
+| **functionId** | <functionId, hoặc `general` nếu không gắn riêng 1 feature> |
+| **Người tổng hợp** | <Comtor/BrSE — tên người chạy lệnh ingest> |
+| **Người approve tại nguồn** | PM — <ngày approve, nếu biết; nếu không biết, hỏi người dùng> |
+
+**Tóm tắt nội dung:**
+<nội dung — giữ đủ ý, không rút gọn quá mức>
+
+**Action items:**
+- [ ] <action item 1, nếu có>
+
+---
+```
+
+Mỗi lần ingest thêm 1 buổi họp mới → append 1 block `## [YYYY-MM-DD] ...` mới vào cuối file (chronological).
+
+### 3.3 `Confirmations-Log.md` (file mới — tạo nếu chưa có)
+
+```markdown
+# Confirmations Log
+
+> Mốc khách hàng CHỐT chính thức — trích từ Meeting Minutes (Backlog) hoặc comment "OK confirm" (SharePoint/Backlog).
+> ⚠️ Quy tắc phân biệt "confirm chính thức" vs "trao đổi thường" CHƯA được PM chốt (xem PM Workflow_v1.0.md § "Vấn đề còn mở" #1) — khi chưa rõ, hỏi lại người ingest trước khi ghi vào đây.
+
+| Date | Nội dung chốt | functionId | Nguồn |
+|---|---|---|---|
+| 2026-08-04 | <mô tả ngắn mốc chốt> | <functionId hoặc general> | [<mô tả ngắn>](<url hoặc "pasted text">) |
+```
+
+---
+
+## 4. Soạn draft — hiển thị đầy đủ, không tóm tắt
+
+Sau khi fetch + phân loại, soạn đúng 1 entry theo template tương ứng ở mục 3, rồi hiển thị **nguyên văn** entry đó cho người dùng (không tóm tắt, không giấu bớt nội dung) kèm footer theo mẫu trong `gate-workflow.md` § "ingest-data" Gate 1 bước 5.
+
+**Không tự ghi file, không tự tạo branch** ở bước này — chỉ hiển thị draft trong hội thoại. Việc ghi file + branch + MR chỉ chạy ở Gate 2, sau khi người dùng gõ **APPROVED**.
+
+Nếu người dùng yêu cầu sửa (thêm/bớt ý, đổi log đích, sửa functionId...) → cập nhật lại draft, hiển thị lại toàn bộ, chờ APPROVED lại — lặp cho tới khi được duyệt.
+
+---
+
+## 5. Gate 3 — Sinh & Duyệt Task List, Tạo Ticket (auto, ngay sau Gate 2)
+
+> Implement "Vấn đề 5" trong `docs/internal/PM Workflow_v1.0.md`. **Trigger đã chốt: TỰ ĐỘNG** — chạy ngay tiếp theo Gate 2 (MR ingest vừa mở xong), không cần lệnh riêng, không chờ PM merge MR trước (merge MR là việc của PM ở luồng riêng, không block bước này).
+> Gate mechanics chi tiết (khi nào gọi lệnh nào) nằm ở `custom/templates/shared/gate-workflow.md` § "ingest-data Task Type" → GATE 3. File này chỉ mô tả **cách phân tích và đề xuất**.
+
+### 5.1 Bước 1 — Đọc lại entry + điều tra phạm vi ảnh hưởng
+
+Đọc lại đúng entry vừa ghi ở Gate 2 (Meetings-Log.md / QnA-Log.md / Confirmations-Log.md — nguyên văn nội dung người dùng đã input ở Gate 1, không phải bản tóm tắt). Sau đó:
+
+1. Xác định `functionId` liên quan (đã có trong entry, hoặc `general`).
+2. Đọc source code + tài liệu hiện có liên quan đến `functionId` đó (UC Spec ở `AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/`, code trong repo source, `AK-Docs/04.Coding/00.Overview/_Index.md`) để hiểu **hệ thống hiện tại đang làm gì**, từ đó đánh giá nội dung mới vừa ingest tác động tới đâu.
+3. Nếu nội dung có Action items rõ ràng trong template Meeting Minutes (mục 3.2) — đây là gợi ý mạnh cho danh sách task, không bỏ qua.
+
+### 5.2 Bước 2 — Quyết định: có cần task hay không
+
+**Không phải mọi entry đều sinh ra task.** Trước khi đề xuất bất kỳ task nào, tự hỏi: nội dung này có yêu cầu một hành động cụ thể (thay đổi spec, code, test, tài liệu...) hay chỉ là thông tin tham khảo/FYI (cập nhật tiến độ, thông tin không đổi hành vi hệ thống, trả lời một câu hỏi đã đóng)?
+
+- **Chỉ là tham khảo** → hiển thị: `ℹ️ Nội dung này không phát sinh task — chỉ lưu làm tài liệu tham khảo. Gate 3 kết thúc.` rồi dừng, không hỏi thêm, không chạy `ak gate 3 start`.
+- **Có hành động cụ thể** → tiếp tục Bước 3. Khi không chắc (ví dụ nội dung vừa có FYI vừa có 1 ý cần sửa code) — nghiêng về đề xuất task cho phần cần hành động, bỏ qua phần FYI, không tự bịa task cho phần không rõ.
+
+### 5.3 Bước 3 — Đề xuất danh sách task
+
+Mỗi task gồm:
+
+| Trường | Ghi chú |
+|---|---|
+| `type` | `spec` (tạo/update UC Spec) · `coding` · `test` · `other` (update tài liệu không thuộc BA/QA/Dev, vd Rules) |
+| `title` | Ngắn, hành động rõ (vd "Cập nhật flow OTP theo feedback khách — tăng thời hạn 30s → 90s") |
+| `track` | BA / Dev / QA — để PM biết ai sẽ nhận task này |
+| `description` | Theo đúng template mục 6.1 `PM Workflow_v1.0.md`: |
+
+```text
+## Nội dung task
+[Mô tả task do AI đề xuất]
+
+## Nguồn tham chiếu
+- Văn bản gốc: [<mô tả ngắn>](<url hoặc "pasted text">)
+- Log AK-Docs: AK-Docs/01.QnA/[QnA-Log.md | Meetings-Log.md | Confirmations-Log.md] (entry ngày <ngày>)
+```
+
+Riêng task `type: "spec"` — thêm 2 mục bắt buộc theo mục 6.1, và **hỏi PM xin link hồ sơ cam kết thay đổi nếu chưa có sẵn** (không tự suy luận):
+
+```text
+## Tổng quan nội dung thay đổi
+[Tóm tắt: thay đổi gì, vì sao thay đổi]
+
+## Nguồn tham chiếu
+- Hồ sơ cam kết thay đổi: [<mô tả ngắn>](<URL do PM cung cấp>)
+- Log AK-Docs (nếu có): AK-Docs/01.QnA/Meetings-Log.md (entry ngày <ngày>)
+```
+
+Hiển thị toàn bộ danh sách cho PM xem — đủ cả `type`/`title`/`track`/`description`, không tóm tắt.
+
+### 5.4 Bước 4 — PM review, sửa trực tiếp trong hội thoại
+
+PM có thể **thêm / sửa / xoá từng task** ngay trong lượt review này (không phải chỉ APPROVED/reject toàn bộ) — cập nhật lại danh sách theo đúng yêu cầu, hiển thị lại toàn bộ, lặp lại cho tới khi PM hài lòng. Task nào type là `spec` mà thiếu "Nguồn tham chiếu" (hồ sơ cam kết thay đổi) → coi như chưa đủ điều kiện, phải hỏi PM bổ sung trước khi cho vào vòng xác nhận tạo ticket ở Bước 5.
+
+### 5.5 Bước 5 — Điểm dừng xác nhận tạo ticket
+
+Hỏi đúng 1 câu, không tự thêm `--yes`:
+
+```text
+Danh sách task như trên (N task) — đồng ý tạo trên [Backlog/Jira]?
+```
+
+- Xác định target `backlog`/`jira` theo đúng adapter của ticket/document gốc đã ingest ở Gate 1/2 (Backlog → target backlog; Jira → target jira). Nếu nguồn là pasted text/SharePoint (không rõ adapter) → hỏi PM muốn tạo trên hệ thống nào.
+- **KHÔNG ĐỒNG Ý** → dừng, để PM tự chỉnh sửa rồi yêu cầu lại (quay lại Bước 4).
+- **ĐỒNG Ý** → sang Bước 6.
+
+### 5.6 Bước 6 — Xác định project đích
+
+Check LOCAL trước, chỉ hỏi khi thật sự chưa biết (Vấn đề 5.1):
+
+1. Backlog: kiểm tra `BACKLOG_DEFAULT_PROJECT_ID` đã lưu chưa (chạy `ak backlog-projects --json`, đọc field `defaultProjectId`). Jira: `ak jira-projects --json`, đọc `defaultProjectKey`.
+2. Đã có → dùng luôn, hiển thị rõ cho PM biết đang dùng project nào + nguồn (đã lưu từ lần trước).
+3. Chưa có → hiển thị danh sách project vừa fetch được, PM chọn 1 → lưu lại bằng `ak backlog-set-default-project <id> <key>` hoặc `ak jira-set-default-project <key>` — để lần sau không hỏi lại.
+
+### 5.7 Bước 7 — Tạo ticket
+
+1. Ghi danh sách task đã duyệt ra 1 file JSON tạm (vd `.aiflow/tmp/tasks-[ticketId].json`), đúng shape mà `ak tasks create-tickets` đọc (xem `scripts/ticket-writer.js`):
+   ```json
+   {
+     "target": "backlog",
+     "tasks": [
+       { "type": "coding", "title": "...", "description": "..." }
+     ]
+   }
+   ```
+2. Chạy `ak tasks create-tickets <file> --json`.
+3. Đọc kết quả JSON trả về:
+   - `{"error":"missing-write-credentials", "field": "...", "message": "..."}` → **đây không phải lỗi hệ thống** — hiển thị đúng `message` cho PM, hỏi PM nhập giá trị key ngay trong hội thoại (dùng luôn khung chat làm nơi PM "nhập & submit"), nhận giá trị → chạy `ak credentials set <field> "<giá trị PM vừa nhập>"` → chạy lại bước 2 (retry đúng 1 lần; nếu vẫn lỗi, báo PM key có thể sai/chưa đủ quyền, không tự thử lại vô hạn).
+   - `{"error":"missing-project", ...}` → quay lại Bước 6 (chưa xác định được project).
+   - Thành công (`ok: true`) → mỗi task có `ticketId` + `url` riêng; task nào `ok: false` (lỗi phía Backlog/Jira, vd thiếu field) → báo rõ cho PM, các task khác đã tạo vẫn giữ nguyên (không rollback).
+
+### 5.8 Bước 8 — Ghi ngược liên kết + đóng Gate
+
+1. Append vào cuối đúng entry gốc (Meetings-Log/QnA-Log/Confirmations-Log) 1 dòng:
+   ```text
+   → Tasks created: TICKET-101 (coding), TICKET-102 (test)
+   ```
+   Việc sửa file này đi qua đúng branch đang dùng ở Gate 2 (không tạo MR riêng — gộp vào cùng thay đổi, hoặc nếu MR đã mở/merge thì tạo 1 commit nhỏ tiếp theo trên cùng branch/1 MR mới tuỳ trạng thái branch lúc đó).
+2. Hiển thị tổng kết:
+   ```text
+   ✅ GATE 3 DONE — Đã tạo N/N ticket trên [Backlog/Jira]:
+     - TICKET-101 (coding) — <url>
+     - TICKET-102 (test) — <url>
+   → Dev/QA chạy `ak use TICKET-XXX` trên từng ticket để bắt đầu Gate tương ứng (Coding/QA workflow hiện có).
+   ```
+3. Run: `ak gate 3 approved --ticket [ticket-id]`.
+
+> **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` khi bắt đầu Bước 1 (bỏ qua nếu Bước 2 kết luận không cần task — không start gate cho trường hợp "chỉ tham khảo"). Run `ak gate 3 approved --ticket [ticket-id]` khi Bước 8 xong.

package/custom/skills/log-bug/SKILL.md

@@ -44,6 +44,8 @@ Thu thập ngay khi test fail:
 **File naming:** `bugs/BUG-[số thứ tự 3 chữ số]-[tên ngắn kebab-case].md`
 **Ví dụ:** `bugs/BUG-001-login-button-not-disabled-on-submit.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).
+
 **Dùng template bên dưới.**
 
 ### Bước 4 — Thông báo TESTER

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

@@ -142,6 +142,8 @@ Ngoài TCs gốc của feature, cần test thêm:
 | Verify Admin User list không bị cache stale | Shared service thay đổi |
 ```
 
+Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem `custom/rules/output-language.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh).
+
 ---
 
 ## Guard Rails (bắt buộc)

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

@@ -1,7 +1,7 @@
 ---
 name: read-study-requirement
-description: Gate 1 — AI reads ticket from Backlog/Jira + reads source code, then uses collaborative Q&A and solution proposal. Adds impact analysis and effort estimate. Outputs requirement.md for DEV to approve.
-keywords: ticket, requirement, study, read, context, backlog, jira, analyze, understand, solution, estimate
+description: Gate 1 — AI reads ticket from Backlog/Jira + reads source code, then uses collaborative Q&A and solution proposal. Adds impact analysis and effort estimate. Outputs requirement.md for DEV to approve. Checks that System Requirement (bridged from UC Spec via `create-system-requirement`) exists and matches the current UC Spec version — shows a non-blocking ⚠️ warning and continues otherwise.
+keywords: ticket, requirement, study, read, context, backlog, jira, analyze, understand, solution, estimate, system requirement, uc spec
 ---
 
 # Analyze Requirement — Gate 1
@@ -12,6 +12,23 @@ keywords: ticket, requirement, study, read, context, backlog, jira, analyze, und
 
 ---
 
+## Step 0: System Requirement Check (Pre-flight, non-blocking warning — runs before Mode Selection)
+
+Before reading the ticket in depth, verify the bridge document from UC Spec — this applies to **every mode**, including Fast Track (it's a 2-file header check, not a heavy investigation). **This check never cancels Gate 1** — any gap only produces a ⚠️ yellow warning; Gate 1 always continues with whatever context is available:
+
+1. Resolve `functionId` from `.aiflow/context/current.json` (or ask DEV once if absent).
+2. Locate the current UC Spec: `AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md` (highest non-archived version).
+   - **Not found** → `⚠️ CẢNH BÁO: Không tìm thấy UC Spec cho [functionId] — Gate 1 tiếp tục chỉ dựa trên ticket/source code, thiếu ngữ cảnh nghiệp vụ BA đã chốt.` Continue to step 3.
+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.
+
+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.
+
+---
+
 ## Mode Selection
 
 Check `mode` in `.aiflow/context/current.json` before starting:
@@ -43,6 +60,7 @@ When creating `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` during G
    - Uncommitted changes detected → SKIP pull and notify DEV: `⚠️ Uncommitted changes detected — skipping git pull. Analysing local state.`
    - `git pull --ff-only` fails (branch diverged from remote) → notify DEV: `⚠️ Local branch diverged from remote — skipping pull. Resolve manually before next ticket.` Then continue with local state.
 1. Read `.aiflow/context/current.json` — ticket title, description, acceptance criteria
+1b. Read `System-Requirement_v{N}.md` for this functionId (confirmed to exist by Step 0) — the authoritative WHAT. Reference its item IDs (`FR-*`, `VR-*`, `ER-*`) instead of restating them.
 2. Identify **directly affected files** from ticket text and file names only.
    DO NOT trace data flow or read unrelated source files.
 3. Q&A: Ask at most **ONE** question if there is a blocking ambiguity.
@@ -74,6 +92,8 @@ When creating `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` during G
 | **Total** | **S/M/L** |
 ```
 
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
+
 5. Display Gate 1 prompt and wait for `APPROVED`.
 
 > After APPROVED, proceed to Gate 2.
@@ -93,6 +113,7 @@ When creating `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` during G
    - `git pull --ff-only` fails because the branch has diverged → notify DEV: `⚠️ Local branch diverged from remote — skipping pull. Resolve manually before next ticket.` Continue with local state.
    - Repo has no remote tracking branch (detached HEAD or local-only branch) → skip silently and proceed.
 1. Read `.aiflow/context/current.json` — ticket info from Backlog/Jira
+1b. Read `System-Requirement_v{N}.md` for this functionId (confirmed to exist and in-sync by Step 0) — this is the authoritative WHAT for the whole functionId. Reference its item IDs (`FR-*`, `NFR-*`, `VR-*`, `ER-*`) in your analysis instead of re-deriving requirements it already covers.
 2. **Supplementary Context:** If `current.json` has a `supplementaryContext[]` array, read each item and integrate it as supporting context for your analysis. Items may be:
    - `[ticket]` — linked tickets (related features, dependencies, parent tickets)
    - `[comment]` — specific comments from PM/QA/stakeholders
@@ -237,6 +258,18 @@ After the developer confirms the design direction (Step 2), run full impact anal
 
 ---
 
+### Step 3.5: Reconcile with System Requirement
+
+Compare this ticket's confirmed scope (Steps 1–3) against `System-Requirement_v{N}.md` (read in Step 1):
+
+- Scope already covered by an existing item → reference its ID (e.g. `FR-03`, `ER-02`) in Section 1 of the requirement doc below. Do not restate it.
+- Investigation surfaces a case, rule, or exception the UC Spec supports but System Requirement missed → **propose** an addition: show DEV the exact diff (which section, new row) before writing anything.
+  - DEV confirms → append to `System-Requirement_v{N}.md` (same version — this does **not** bump `System-Requirement-Version`) + add a `Change Log` row citing this ticket.
+  - DEV declines/unsure → leave System Requirement untouched; note the discrepancy in this ticket's own requirement doc (Section 1, Facts/Assumptions/Gaps) instead.
+- Scope doesn't trace to System Requirement **or** UC Spec at all → this is the fabrication risk proposal #7 targets. STOP and ask DEV: is this actually in scope for this functionId, or does the UC Spec need a BA update first? Do not proceed on a guess.
+
+---
+
 ### Step 4: Write Requirement Document
 
 Save to `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md`:
@@ -432,11 +465,17 @@ Please review the requirement document.
 | Effort estimate | This skill |
 | requirement.md template & output | This skill |
 | Gate 1 APPROVED gate | This skill |
+| System Requirement creation/versioning/sync | `create-system-requirement` task type (separate, own 2 gates) |
+| Mid-ticket addition proposal (Step 3.5 triggers it) | `create-system-requirement` owns the write contract (its Step 8) |
 
 ---
 
 ## Mandatory Rules
 
+- ✅ **MUST** verify System Requirement exists and matches the current UC Spec version (Step 0) before proceeding — show a ⚠️ non-blocking warning and continue otherwise (never cancels Gate 1); record the gap in the requirement doc (Step 4).
+- ✅ **MUST** read System Requirement as mandatory input (Step 1) — not optional context.
+- ❌ **DO NOT** restate content already covered in System Requirement — reference its item ID instead.
+- ❌ **DO NOT** silently accept ticket scope that doesn't trace to System Requirement or UC Spec (Step 3.5) — stop and ask instead of guessing.
 - ❌ **DO NOT** invoke `superpowers:brainstorming` — its terminal state calls `writing-plans` and bypasses Gate 1 approval
 - ❌ **DO NOT** invoke `superpowers:writing-plans` — that belongs to Gate 2 (`generate-spec` skill)
 - ❌ **DO NOT** proceed past Step 2 if design is not confirmed by developer

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

@@ -31,7 +31,11 @@ Fill in the structure below. **Use simple language, avoiding technical jargon.**
 
 ---
 
-## Standard Structure (English)
+## 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
@@ -92,4 +96,4 @@ If problems persist, please contact our support hotline..."]
 - ❌ Do not blame third parties unless certain
 - ❌ Do not commit to specific deadlines unless certain
 
-Present clearly and professionally. Default is English unless otherwise requested.
+Present clearly and professionally, in the language determined above.

package/custom/skills/retest-orchestration/SKILL.md

@@ -84,6 +84,8 @@ BASE_URL=<baseUrl> npx playwright test --grep "AD10_002|AD10_005" --headed
 
 Invoke `evidence-aggregation` skill cho RETEST results:
 
+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).
+
 **Không xóa evidence cũ** — tạo subfolder theo run:
 
 ```

package/custom/skills/review-plan/SKILL.md

@@ -143,6 +143,8 @@ Create file `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md`:
 **Breaking changes:** None / [description if any]
 ```
 
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
+
 ### Step 2.5: Retrospect + propose memory drafts
 
 Synthesize what was learned this task. **Priority order — human corrections first:** if this is a repeat pass through Gate 4 (the developer already sent "BUG: ..." at least once this task), the developer's own correction is the single highest-value lesson — scan back through this session for it and draft it even if you already drafted something for the earlier BUG at Step 4 (dedup will catch an exact repeat; don't skip capturing it out of caution). Only after that, add anything else genuinely new: architecture facts discovered, decisions made and why. For each candidate, create a **local draft** (no approval needed yet — `_pending/` is local-only, doc `docs/common/Memory-Architecture-v1.0.md`):

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

@@ -205,4 +205,4 @@ Trả về danh sách kết quả cho `execute-flow`:
 - ❌ **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
-- ✅ Viết test names và comments bằng tiếng Việt
+- ✅ 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/skills/test-analysis/SKILL.md

@@ -107,6 +107,8 @@ Dựa trên ticket/description, phân tích:
 
 Tạo `test-plan/test-analysis.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).
+
 ```markdown
 # Test Analysis: [Ticket ID / Feature Name]
 

package/custom/skills/test-skills/rules/qa-writing-standards.md

@@ -8,8 +8,8 @@
 
 ## 1. Ngôn ngữ & văn phong
 
-- Nội dung mô tả/diễn giải bằng **tiếng Việt**.
-- **Tiêu đề cột của bảng (checklist, testcase) viết bằng tiếng Anh** theo quy ước team; **nội dung trong ô viết tiếng Việt**.
+- Ngôn ngữ nội dung mô tả/diễn giải **auto-detect theo ngôn ngữ của ticket/input** — xem `custom/rules/output-language.md`: input tiếng Việt → viết tiếng Việt (mặc định trước đây); input tiếng Anh → viết tiếng Anh.
+- **Tiêu đề cột của bảng (checklist, testcase) luôn viết bằng tiếng Anh** theo quy ước team, bất kể ngôn ngữ nội dung ô; **nội dung trong ô theo ngôn ngữ đã xác định ở trên**.
 - Thuật ngữ kỹ thuật/test có thể giữ tiếng Anh trong ngoặc khi cần (vd: kiểm thử biên (boundary)).
 - Viết ngắn gọn, rõ ràng, không lan man. Ưu tiên gạch đầu dòng và bảng.
 

package/custom/skills/train-model/SKILL.md

@@ -49,6 +49,8 @@ Log the following to MLflow or wandb for every run:
 
 Do not leave runs unnamed or untracked.
 
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
+
 ### 5. Checkpointing
 
 Save the best checkpoint by the primary validation metric (not the final epoch). Store the config file alongside the artifact so the checkpoint is self-contained. Use the model registry (MLflow Model Registry or equivalent) when available.

package/custom/templates/shared/create-testcase-workflow.md

@@ -90,7 +90,7 @@ Ví dụ: `functionId = AD06` → thư mục gốc là `03.Testing/`
 ```
 (AI-Artifacts/ = 03.Testing/07.AI-Artifacts/ — viết tắt cho ngắn gọn)
 
-[Input: SRS / Jira / Backlog / Spec file] → Pre-flight: BẮT BUỘC xác định functionId
+[Input: UC Spec + System Requirement (bắt buộc, cảnh báo nếu thiếu) / SRS / Jira / Backlog / Spec file] → Pre-flight: BẮT BUỘC xác định functionId
     ↓
 Gate 1: Phân tích yêu cầu & Đánh giá rủi ro  → AI-Artifacts/[functionId]/
     ↓ APPROVED
@@ -169,8 +169,37 @@ Trước khi ghi bất kỳ file nào vào `03.Testing/`, đảm bảo AK-Docs
 
 > ❌ Không tự thêm `--yes` khi chưa thấy QA gõ xác nhận rõ ràng trong hội thoại.
 
+#### Bước 0.6: Kiểm tra UC Spec & System Requirement (input bắt buộc, cảnh báo non-blocking)
+
+**Mục tiêu:** Test Case phải được thiết kế dựa trên cả UC Spec (yêu cầu nghiệp vụ do BA chốt) **và** System Requirement (bản dịch kỹ thuật cho Dev — Validation Rule, Exception/Error Handling, Acceptance Test) — thiếu một trong hai, TC dễ bỏ sót case mà Dev đã implement hoặc case BA đã đặc tả.
+
+1. Tìm UC Spec: `AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md` (version cao nhất, không phải bản archive).
+2. Tìm System Requirement: `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v*.md` (version cao nhất).
+3. Nếu tìm thấy System Requirement, đọc 2 header của nó: `UC-Spec-Version` (phải khớp version UC Spec tìm được ở bước 1) và `Status` (phải là `✅ Approved`).
+
+Nếu **bất kỳ** điều kiện sau không thỏa mãn → hiển thị cảnh báo tương ứng, **không dừng/không cancel Gate 1** — vẫn tiếp tục với dữ liệu hiện có:
+
+| Tình huống | Cảnh báo hiển thị |
+|---|---|
+| Không tìm thấy UC Spec | `⚠️ CẢNH BÁO: Không tìm thấy UC Spec cho [functionId] — Test Case sẽ chỉ dựa trên System Requirement (nếu có) + input khác, thiếu ngữ cảnh nghiệp vụ gốc.` |
+| Không tìm thấy System Requirement | `⚠️ CẢNH BÁO: Không tìm thấy System Requirement cho [functionId] — Test Case sẽ chỉ dựa trên UC Spec, có thể thiếu Validation Rule/Exception Handling/Acceptance Test mà Dev đã chốt riêng.` |
+| Có System Requirement nhưng `UC-Spec-Version` không khớp UC Spec hiện tại | `⚠️ CẢNH BÁO: System Requirement đang trace theo UC Spec v[X], nhưng UC Spec hiện tại là v[Y] — nội dung có thể lỗi thời.` |
+| Có System Requirement, khớp version, nhưng `Status` ≠ `✅ 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.` |
+
+→ Với mọi cảnh báo trên: ghi lại tình huống này vào `[functionId]_01_Requirement_Analysis_QA.md` (mục Assumptions, Bước 4) để QA/Dev biết rõ giới hạn của phân tích — không chỉ hiển thị rồi bỏ qua.
+
+Nếu tất cả điều kiện thỏa mãn → thông báo ngắn rồi tiếp tục:
+
+```
+✓ UC Spec: v[N]
+✓ System Requirement: v[N] (✅ Approved, khớp UC Spec v[N])
+→ Tiếp tục Gate 1...
+```
+
 #### Bước 1: Đọc và tổng hợp đầu vào
 - Đọc `.aiflow/context/current.json` — tiêu đề, mô tả, acceptance criteria, liên kết tài liệu
+- Đọc `UC-Spec_v{N}.md` (tìm thấy ở Bước 0.6) — yêu cầu nghiệp vụ gốc: Main/Alternative/Exception Flow, Business Rules (BR-NNN), UI Components
+- Nếu tìm thấy `System-Requirement_v{N}.md` ở Bước 0.6 → đọc toàn bộ, dùng làm input kỹ thuật bổ sung cho Bước 2 (Phân tích yêu cầu): đối chiếu Functional/Non-Functional Requirements (`FR-*`, `NFR-*`), Validation Rules (`VR-*`), Exception & Error Handling (`ER-*`), Acceptance Test Scenarios (`AT-*`) — TC ở Gate 3 phải bao phủ cả các `AT-*`/`ER-*` này, không chỉ Business Rules trong UC Spec
 - Nếu description có URL → chạy `ak fetch-links <url>` để tải nội dung
 - Nếu có `supplementaryContext[]` → đọc từng item (SRS file, Figma link, API spec, spec MD file)
 - Nếu có file yêu cầu thô được chỉ định → đọc file đó
@@ -227,6 +256,7 @@ Trước khi ghi bất kỳ file nào vào `03.Testing/`, đảm bảo AK-Docs
 
 **Definition of Done:**
 - [ ] `functionId` đã được xác định, thư mục đầu ra đã sẵn sàng
+- [ ] Đã chạy Bước 0.6 (kiểm tra UC Spec + System Requirement); nếu có cảnh báo, đã ghi vào `01_Requirement_Analysis_QA.md`
 - [ ] File `01_Requirement_Analysis_Result.md` có đủ 16 mục + Risk Matrix + Test Scope
 - [ ] Toàn bộ Critical/Major đã được hỏi trực tiếp (từng câu một) và có câu trả lời từ QA — không còn nghi vấn bỏ ngỏ
 - [ ] File `01_Requirement_Analysis_QA.md` đã tạo nếu có issue, ghi lại đầy đủ câu hỏi + câu trả lời (Bước 2b)
@@ -530,6 +560,7 @@ Sau khi Gate 4 đã APPROVED (bộ Test Case hoàn thành):
 - ❌ **KHÔNG** tiến gate tiếp theo khi còn issue Critical hoặc Major chưa giải quyết
 - ✅ **BẮT BUỘC** chạy Bước 0 ở Gate 1 — xác nhận `functionId` và thư mục đầu ra trước khi làm bất cứ điều gì
 - ✅ **BẮT BUỘC** chạy Bước 0.5 ở Gate 1 — đảm bảo AK-Docs đang ở branch `feature/[functionId]/[taskId]` trước khi ghi file đầu tiên
+- ✅ **BẮT BUỘC** chạy Bước 0.6 ở Gate 1 — kiểm tra UC Spec + System Requirement (tồn tại, khớp version, Approved); thiếu/lệch → cảnh báo yellow **không chặn Gate**, ghi vào QA artifact
 - ✅ **BẮT BUỘC** đọc skill từ `.claude/skills/test-skills/` — không suy luận từ bộ nhớ
 - ✅ **BẮT BUỘC** invoke `gate-review` cuối mỗi gate và chờ APPROVED
 - ✅ **BẮT BUỘC** tuân thủ 100% `testcase-template.md` ở Gate 3 và Gate 4