@relipa/ai-flow-kit 0.1.5-beta.1 → 0.1.6

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

@@ -30,7 +30,7 @@ Check `mode` in `.aiflow/context/current.json` before starting:
 
 ## Fast Mode Output Rules (CRITICAL)
 
-When creating `04.Coding/04.Reviews/[functionId]/[ticketId].md` during Gate 1:
+When creating `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` during Gate 1:
 - You must create the `summary.md` file after Gate 1 is APPROVED, to track session progress.
 - Keep `summary.md` concise. Only include short bullet points tracking Gates.
 - Do not write verbose implementation details in `summary.md` at Gate 1.
@@ -48,7 +48,7 @@ When creating `04.Coding/04.Reviews/[functionId]/[ticketId].md` during Gate 1:
 3. Q&A: Ask at most **ONE** question if there is a blocking ambiguity.
    If the ticket + source file names make intent clear → skip Q&A entirely.
    Wait for answer before writing the requirement doc.
-4. Output `04.Coding/01.Requirements/[functionId]/[ticketId].md` with **3 sections only**:
+4. Output `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` with **3 sections only**:
 
 ```markdown
 # Requirement: [Ticket ID] — [Title]
@@ -76,7 +76,9 @@ When creating `04.Coding/04.Reviews/[functionId]/[ticketId].md` during Gate 1:
 
 5. Display Gate 1 prompt and wait for `APPROVED`.
 
-> After APPROVED, proceed to Gate 2. The lean doc is intentional — Gate 2 plan will fill in the details.
+> After APPROVED, proceed to Gate 2.
+> - **`gen-doc` tasks:** Gate 2 generates the output document immediately (no `plan.md`, no TDD). Self-review + task-summary.md are created automatically.
+> - **All other tasks:** Gate 2 plan fills in the implementation details.
 
 ---
 
@@ -111,6 +113,63 @@ Do this investigation **before** asking any questions. Come prepared.
 
 ---
 
+### Step 1.5: Detect & Read Figma Design (UI tickets only)
+
+Run this only when the ticket touches UI. Skip entirely for non-UI tickets.
+
+1. **Detect a Figma URL** in this order:
+   - `current.json` → `description`
+   - `current.json` → `supplementaryContext[]` items
+   - Pattern: `https://www.figma.com/design/<fileKey>/...?node-id=<nodeId>`
+2. **No URL but ticket looks like UI** (mentions screen, page, component, layout, "theo design"):
+   ask the DEV **once** to paste a Figma URL. If DEV skips → write "Design: TBD" in the
+   Design Analysis section and continue. Do NOT ask again.
+3. **URL found** → invoke `figma-to-component` Steps 0–2.5 (verify MCP, read design,
+   detect & export images). Then persist the shared artifact:
+   - Create `plan/[ticket-id]/design/`
+   - Save raw response to `plan/[ticket-id]/design/nodes.json` (cache for later gates)
+   - Save exported images to `plan/[ticket-id]/design/images/`
+   - Write `plan/[ticket-id]/design/figma-manifest.json` (nodeId → image file) — per-ticket,
+     NOT a shared global manifest
+   - Write `plan/[ticket-id]/design/design-context.md` using the template below
+4. **Figma MCP not connected** → tell DEV to run `aiflow init -a figma` (or `-a figma-desktop`),
+   mark Design Analysis as "⚠️ pending MCP", and continue with the non-UI parts of the requirement.
+   Do NOT abort the ticket.
+
+**`design-context.md` template:**
+
+```markdown
+# Design Context: [ticket-id]
+
+**Figma URL:** <url>   **fileKey:** xxx   **nodeId:** 123-456
+**Fetched:** [YYYY-MM-DD]   **Adapter:** figma (REST) | figma-desktop
+
+## 1. Layout Structure
+- Node tree: Frame > Header / Body > Card[] / Footer
+- Flex direction, gap, padding, alignment per region
+
+## 2. Design Tokens
+| Type | Figma value | Project token |
+|------|-------------|---------------|
+| Color | #3B82F6 | blue-500 / --color-primary |
+| Type  | 16/600    | text-base font-semibold |
+| Space | 16px      | p-4 / gap-4 |
+
+## 3. Components to build
+- [ ] UserCard (variants: default, hover) — nodeId 78-910
+- [ ] Header — nodeId 12-3
+
+## 4. Image Map
+| nodeId | layer | file |
+|--------|-------|------|
+| 123-456 | Banner Top | design/images/banner-top-123-456.png |
+
+## 5. Notes
+- Anything not mapped 1:1 (custom fonts, effects…)
+```
+
+---
+
 ### Step 2: Clarify Requirements via Q&A
 
 Ask clarifying questions directly — **one question at a time**, wait for the developer's response before asking the next.
@@ -154,7 +213,7 @@ After the developer confirms the design direction (Step 2), extend with:
 
 ### Step 4: Write Requirement Document
 
-Save to `04.Coding/01.Requirements/[functionId]/[ticketId].md`:
+Save to `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md`:
 
 ```markdown
 # Requirement: [Ticket ID] — [Title]
@@ -227,6 +286,15 @@ Save to `04.Coding/01.Requirements/[functionId]/[ticketId].md`:
 
 ---
 
+## Design Analysis (UI tickets only)
+
+- **Source:** [Figma URL or "TBD" or "⚠️ pending MCP"]
+- **Artifact:** `plan/[ticket-id]/design/design-context.md`
+- **Summary:** layout, key components to build, design tokens to map, images exported
+- **Impact on approach:** how the design shapes the proposed solution
+
+---
+
 ## 4. Impact Analysis
 
 **Impact Level:** 🟢 Low / 🟡 Medium / 🔴 High
@@ -284,7 +352,7 @@ Save to `04.Coding/01.Requirements/[functionId]/[ticketId].md`:
 ⏸️  GATE 1: REQUIREMENT DOCUMENT READY
 
 Ticket: [ticket-id] — [title]
-File:   04.Coding/01.Requirements/[functionId]/[ticketId].md
+File:   AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md
 
 Summary:
   Type:     [feature / bug-fix / refactor]
@@ -332,5 +400,5 @@ Please review the requirement document.
 - ❌ **DO NOT** skip impact analysis and effort estimate
 - ✅ **MUST** run `git status` + `git pull --ff-only` (Pre-flight) before reading source code, when working tree is clean
 - ✅ **MUST** read source code before Q&A begins
-- ✅ **MUST** save `04.Coding/01.Requirements/[functionId]/[ticketId].md`
+- ✅ **MUST** save `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md`
 - ✅ **MUST** display Gate 1 prompt and wait for `APPROVED`

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

@@ -6,6 +6,8 @@ keywords: review, code review, approve, summary, checklist
 
 # Review Plan — Gate 4
 
+> ⚠️ **Skip this gate for `gen-doc` tasks.** gen-doc tasks only use Gates 1 and 2 (Gate 2 includes self-review automatically). This gate applies to `feature`, `bug-fix`, `refactor`, `documentation`, and `investigation` tasks.
+
 > **GATE 4: Runs after AI has completed code generation.**
 >
 > Principle: AI self-reviews first (verification + impact-analysis), then presents a summary to the developer. The developer decides: APPROVED or report a bug.
@@ -43,7 +45,7 @@ Assess impact by reasoning about the changed files only:
 
 ## Fast Mode Output Rules (CRITICAL)
 
-When creating `04.Coding/04.Reviews/[functionId]/[ticketId].md` in **fast mode**:
+When creating `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` in **fast mode**:
 - **Do not write long explanations or descriptions.**
 - **List format only:** Bullet points with `[NEW]`, `[MODIFIED]`, `[DELETED]`.
 - **Purpose:** Next to each file, write exactly 1 sentence explaining the *purpose* (the "why"), not the implementation details.
@@ -77,9 +79,29 @@ Run in the following mandatory order:
 
 **If any step fails → fix first, do not proceed to Step 2.**
 
+### Step 1.5: Design Conformance Check (UI tickets only)
+
+If `plan/[ticket-id]/design/design-context.md` exists, compare the generated UI against the
+design — **visually against the rendered reference image, not just the text checklist.** Open
+`public/assets/figma/_reference-<nodeId>.png` (or the Figma frame) and the running UI, and check
+region by region (header / panel / sections / footer):
+
+- [ ] **Reference image compared** region by region; every visible difference listed
+- [ ] **Background** is the correct layer (paint order) and actually visible
+- [ ] **No-fabricate**: no element rendered that isn't in the design (no extra button/section)
+- [ ] **No-omit**: every text label + every image node is present in its region
+- [ ] Layout matches (arrangement/position per region, not a generic flow)
+- [ ] Colors match the Design Tokens table (project token or arbitrary value)
+- [ ] Typography matches (size, weight, line-height)
+- [ ] Every component listed in "Components to build" exists
+- [ ] Every image in the Image Map exists under `public/assets/figma/`
+
+Any mismatch → treat as a coding bug: fix before Step 2. A text-only checklist tick is NOT enough —
+if you have not actually looked at the reference image, say so. Skip this step for non-UI tickets.
+
 ### Step 2: Create Summary Report
 
-Create file `04.Coding/04.Reviews/[functionId]/[ticketId].md`:
+Create file `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md`:
 
 ```markdown
 # Summary: [Ticket ID] — [Title]
@@ -139,6 +161,7 @@ Create file `04.Coding/04.Reviews/[functionId]/[ticketId].md`:
 - [ ] Naming and Code Style follow conventions
 - [ ] Sufficient tests (unit + integration)
 - [ ] No dead code / leftover console.logs
+- [ ] UI matches `design-context.md` (layout, color, typography, spacing) — UI tickets only
 ```
 
 ### Step 3: GATE 4 — Present to Developer
@@ -148,7 +171,7 @@ Create file `04.Coding/04.Reviews/[functionId]/[ticketId].md`:
 ⏸️  GATE 4: WAITING FOR DEV REVIEW
 
 I have completed implementation and self-review.
-Summary: 04.Coding/04.Reviews/[functionId]/[ticketId].md
+Summary: AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md
 
 **Self-review results:**
 - Tests: ✅ [N] passed / ❌ [N] failed  

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

@@ -7,6 +7,26 @@
 
 ---
 
+### Pre-flight BẮT BUỘC — Đồng bộ Source & Docs (đầu MỖI Gate)
+
+> Áp dụng cho **cả 4 Gate** bên dưới — không chỉ Gate 1. Chạy đủ các bước sau **trước khi** thực hiện bất kỳ hành động nào khác của gate đó.
+
+1. **Sync repo source (bên trong, không phải AK-Docs/Shared-Docs):** xác định thư mục repo source liên quan (field `repo` trong context, hoặc repo duy nhất mở trong workspace) → `cd` vào đó → chạy `git status --porcelain`; nếu working tree sạch, chạy `git pull --ff-only`. Nếu có thay đổi chưa commit, branch diverged, hoặc không có remote tracking branch → bỏ qua pull (không phải lỗi).
+2. **Sync `AK-Docs/`:** `cd` vào `AK-Docs/` (sibling folder ở workspace root) → chạy `git pull`.
+3. **Sync `Shared-Docs/`:** `cd` vào `Shared-Docs/` (sibling folder ở workspace root) → chạy `git pull`.
+4. Sau khi xong, `cd` quay lại thư mục làm việc ban đầu trước khi tiếp tục các bước khác của gate.
+
+Nếu `AK-Docs/` hoặc `Shared-Docs/` chưa tồn tại tại workspace root, hoặc không phải git repo → bỏ qua bước tương ứng, không cảnh báo.
+
+**Nếu bất kỳ lệnh `git pull` nào ở Bước 1–3 thất bại** → **KHÔNG dừng workflow** — hiển thị cảnh báo và tiếp tục gate với dữ liệu local hiện có:
+
+```
+⚠️ CẢNH BÁO: Không thể pull [tên repo] — [lý do lỗi].
+→ Đang tiếp tục Gate [N] với dữ liệu local hiện tại, có thể chưa mới nhất.
+```
+
+---
+
 ### BA Skills
 
 Các skill sau đây được cài tự động vào `.claude/skills/ba-skills/` khi chạy `ak init` hoặc `ak up`.
@@ -76,6 +96,8 @@ Bàn giao Dev/Test
 
 **Bước thực hiện:**
 
+**Pre-flight (bắt buộc, chạy trước Bước 0):** 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.
+
 #### Bước 0: Pre-flight — Xác định functionId và thư mục đầu ra
 
 **Xác định `functionId` (BẮT BUỘC):**
@@ -115,6 +137,20 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD10, UC-
      → Bắt đầu Gate 1...
      ```
 
+#### Bước 0.5: Đảm bảo đang làm việc trên branch riêng của task (AK-Docs)
+
+Trước khi ghi bất kỳ file nào vào `02.BA-Specs/`, đảm bảo AK-Docs đang ở branch riêng của task này, không phải `main` (mọi thay đổi `AK-Docs` phải qua branch + Merge Request, PM duyệt cuối cùng trước khi merge vào `main`):
+
+1. Lấy `taskId` từ trường `taskId` trong `.aiflow/context/current.json`.
+2. Kiểm tra `AK-Docs` hiện đang ở branch nào (`git -C AK-Docs branch --show-current`).
+3. Nếu **chưa** ở branch `feature/[functionId]/[taskId]`:
+   - Hỏi BA: "Chưa có branch riêng cho task này trong AK-Docs. Tạo branch `feature/[functionId]/[taskId]` từ `main` — đồng ý không?"
+   - BA đồng ý → chạy `ak docs branch [functionId] [taskId] --yes`
+   - BA từ chối → tiếp tục Gate 1 trên nhánh hiện tại của AK-Docs (BA tự quản lý branch)
+4. Nếu **đã** ở đúng branch (ví dụ resume từ session trước) → bỏ qua, tiếp tục.
+
+> ❌ Không tự thêm `--yes` khi chưa thấy BA gõ xác nhận rõ ràng trong hội thoại.
+
 #### 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
 - Nếu description có URL → chạy `ak fetch-links <url>` để tải nội dung
@@ -215,6 +251,8 @@ Vui lòng cung cấp câu trả lời theo một trong 3 cách:
 
 **Bước thực hiện:**
 
+**Pre-flight (bắt buộc, chạy trước Bước 1):** 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.
+
 #### Bước 1: Tiếp nhận và đánh giá câu trả lời
 - Đối chiếu từng câu trả lời với câu hỏi trong `QnA-Log_v(m).md`
 - Phân loại:
@@ -292,6 +330,8 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 
 **Bước thực hiện:**
 
+**Pre-flight (bắt buộc, chạy trước Bước 1):** 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.
+
 #### Bước 1: Liệt kê thành phần giao diện
 - Đọc tài liệu phân tích đã chốt
 - Xác định: ô nhập liệu, nút bấm, liên kết, vùng hiển thị lỗi, vùng hiển thị dữ liệu
@@ -345,6 +385,8 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 
 **Bước thực hiện:**
 
+**Pre-flight (bắt buộc, chạy trước Bước 1):** 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.
+
 #### Bước 1: Khởi tạo Spec từ Template
 - **READ template:** `.claude/skills/ba-skills/skill-ba-uc-template-v1.md`
 - **READ skill:** `.claude/skills/ba-skills/skill-ba-write-uc-spec-v1.md`
@@ -399,6 +441,18 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 > **Telemetry:** Run `ak gate 4 start --ticket [functionId]` khi bắt đầu gate này.
 > Run `ak gate 4 approved --ticket [functionId]` sau khi gate-review verify passed. Run as-is — không thêm shell redirects.
 
+#### Bước 8: Submit AK-Docs lên remote qua Merge Request
+
+Sau khi Gate 4 đã APPROVED (UC Spec hoàn thành):
+
+1. Soạn title + description cho Merge Request (tóm tắt UC Spec vừa hoàn thành, link ticket gốc), hiển thị cho BA xem trước.
+2. Hỏi BA: "Nội dung commit/MR như trên — đồng ý submit AK-Docs không?"
+   - BA đồng ý → chạy `ak docs submit --title "..." --description "..." --yes`
+   - BA từ chối → dừng, để BA tự commit/tạo MR khi sẵn sàng
+3. Thông báo BA: MR đã mở, chờ **PM review & merge vào `main`** — đây là bước duyệt cuối cùng cho tài liệu, không phải BA tự merge.
+
+> ❌ Không tự thêm `--yes` khi chưa thấy BA gõ xác nhận rõ ràng trong hội thoại.
+
 ---
 
 ### Bản đồ Skills theo Gate
@@ -419,6 +473,7 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 - ❌ **KHÔNG** tiến Gate 3 khi vẫn còn câu hỏi Open
 - ❌ **KHÔNG chấp nhận APPROVED** ở Gate 1 hoặc Gate 2 khi còn bất kỳ câu hỏi nào trạng thái **Open** — từ chối và hiển thị danh sách câu hỏi cần trả lời
 - ✅ **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** đọc skill từ `.claude/skills/ba-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** mọi thẻ tương tác trong HTML có `id` duy nhất

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

@@ -7,6 +7,26 @@
 
 ---
 
+### Pre-flight BẮT BUỘC — Đồng bộ Source & Docs (đầu MỖI Gate)
+
+> Áp dụng cho **cả 4 Gate** bên dưới — không chỉ Gate 1. Chạy đủ các bước sau **trước khi** thực hiện bất kỳ hành động nào khác của gate đó.
+
+1. **Sync repo source (bên trong, không phải AK-Docs/Shared-Docs):** xác định thư mục repo source liên quan (field `repo` trong context, hoặc repo duy nhất mở trong workspace) → `cd` vào đó → chạy `git status --porcelain`; nếu working tree sạch, chạy `git pull --ff-only`. Nếu có thay đổi chưa commit, branch diverged, hoặc không có remote tracking branch → bỏ qua pull (không phải lỗi).
+2. **Sync `AK-Docs/`:** `cd` vào `AK-Docs/` (sibling folder ở workspace root) → chạy `git pull`.
+3. **Sync `Shared-Docs/`:** `cd` vào `Shared-Docs/` (sibling folder ở workspace root) → chạy `git pull`.
+4. Sau khi xong, `cd` quay lại thư mục làm việc ban đầu trước khi tiếp tục các bước khác của gate.
+
+Nếu `AK-Docs/` hoặc `Shared-Docs/` chưa tồn tại tại workspace root, hoặc không phải git repo → bỏ qua bước tương ứng, không cảnh báo.
+
+**Nếu bất kỳ lệnh `git pull` nào ở Bước 1–3 thất bại** → **KHÔNG dừng workflow** — hiển thị cảnh báo và tiếp tục gate với dữ liệu local hiện có:
+
+```
+⚠️ CẢNH BÁO: Không thể pull [tên repo] — [lý do lỗi].
+→ Đang tiếp tục Gate [N] với dữ liệu local hiện tại, có thể chưa mới nhất.
+```
+
+---
+
 ### QA Skills
 
 Các skill sau đây được cài tự động vào `.claude/skills/test-skills/` khi chạy `ak init` hoặc `ak up`.
@@ -96,6 +116,8 @@ Sẵn sàng thực thi kiểm thử
 
 **Bước thực hiện:**
 
+**Pre-flight (bắt buộc, chạy trước Bước 0):** 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.
+
 #### Bước 0: Pre-flight — Xác định functionId và thư mục đầu ra
 
 **Xác định `functionId` (BẮT BUỘC):**
@@ -133,6 +155,20 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
      → Bắt đầu Gate 1...
      ```
 
+#### Bước 0.5: Đảm bảo đang làm việc trên branch riêng của task (AK-Docs)
+
+Trước khi ghi bất kỳ file nào vào `03.Testing/`, đảm bảo AK-Docs đang ở branch riêng của task này, không phải `main` (mọi thay đổi `AK-Docs` phải qua branch + Merge Request, PM duyệt cuối cùng trước khi merge vào `main`):
+
+1. Lấy `taskId` từ trường `taskId` trong `.aiflow/context/current.json`.
+2. Kiểm tra `AK-Docs` hiện đang ở branch nào (`git -C AK-Docs branch --show-current`).
+3. Nếu **chưa** ở branch `feature/[functionId]/[taskId]`:
+   - Hỏi QA: "Chưa có branch riêng cho task này trong AK-Docs. Tạo branch `feature/[functionId]/[taskId]` từ `main` — đồng ý không?"
+   - QA đồng ý → chạy `ak docs branch [functionId] [taskId] --yes`
+   - QA từ chối → tiếp tục Gate 1 trên nhánh hiện tại của AK-Docs (QA tự quản lý branch)
+4. Nếu **đã** ở đúng branch (ví dụ resume từ session trước) → bỏ qua, tiếp tục.
+
+> ❌ 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 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
 - Nếu description có URL → chạy `ak fetch-links <url>` để tải nội dung
@@ -216,6 +252,8 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 
 **Bước thực hiện:**
 
+**Pre-flight (bắt buộc, chạy trước Bước 1):** 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.
+
 #### Bước 1: Đọc artifact đầu vào
 - Đọc `[functionId]_01_Requirement_Analysis_Result.md` — nắm toàn bộ 16 mục, Risk Matrix, Business Rules
 
@@ -287,6 +325,8 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 
 **Bước thực hiện:**
 
+**Pre-flight (bắt buộc, chạy trước Bước 1):** 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.
+
 #### Bước 1: Đọc template và quy ước bắt buộc
 - **READ template:** `.claude/skills/test-skills/template/testcase-template.md` — **BẮT BUỘC** tuân thủ 100%
 - **READ skill:** `.claude/skills/test-skills/rules/qa-writing-standards.md`
@@ -376,6 +416,8 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 
 **Bước thực hiện:**
 
+**Pre-flight (bắt buộc, chạy trước Bước 1):** 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.
+
 #### Bước 1: Review nội dung và đánh giá bao phủ
 - **READ skill:** `.claude/skills/test-skills/categories/00-core/00.04.testcase-review.md`
 - **READ skill:** `.claude/skills/test-skills/categories/99-review/99.01.coverage-review.md`
@@ -443,6 +485,18 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 > **Telemetry:** Run `ak gate 4 start --ticket [functionId]` khi bắt đầu gate này.
 > Run `ak gate 4 approved --ticket [functionId]` sau khi gate-review verify passed. Run as-is — không thêm shell redirects.
 
+#### Bước 8: Submit AK-Docs lên remote qua Merge Request
+
+Sau khi Gate 4 đã APPROVED (bộ Test Case hoàn thành):
+
+1. Soạn title + description cho Merge Request (tóm tắt bộ Test Case vừa hoàn thành, sign-off status, link ticket gốc), hiển thị cho QA xem trước.
+2. Hỏi QA: "Nội dung commit/MR như trên — đồng ý submit AK-Docs không?"
+   - QA đồng ý → chạy `ak docs submit --title "..." --description "..." --yes`
+   - QA từ chối → dừng, để QA tự commit/tạo MR khi sẵn sàng
+3. Thông báo QA: MR đã mở, chờ **PM review & merge vào `main`** — đây là bước duyệt cuối cùng cho tài liệu, không phải QA tự merge.
+
+> ❌ 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ản đồ Skills theo Gate
@@ -463,6 +517,7 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 - ❌ **KHÔNG** sinh `04_Final_Result.md` mà thiếu `[functionId]_TestCase.md` (hoặc ngược lại)
 - ❌ **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** đọ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