@relipa/ai-flow-kit 0.1.5 → 0.1.6

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.
@@ -77,6 +79,26 @@ 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 `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md`:
@@ -139,6 +161,7 @@ Create file `AK-Docs/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

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

package/custom/templates/shared/gate-workflow.md

@@ -3,12 +3,32 @@
 > **Absolute Rule: Complete Gate N before entering Gate N+1.**
 > **Do not skip, shorten, or merge Gates.**
 
+> **Task type `gen-doc`** uses a **2-gate flow** (Gate 1 + Gate 2 only). See the gen-doc section below — do NOT run Gates 3/4/5 for gen-doc tasks.
+
 You have superpowers. When a ticket context exists in `.aiflow/context/current.json`:
 - **Consult the "AI Skill Registry"** below to find instructions for each skill (`SKILL.md`).
 - **AUTO-START Gate 1 immediately** — do NOT wait to be asked.
 - Read the context, **check `taskType`**, and follow the matching workflow — NO EXCEPTIONS.
 - **PROJECT CONVENTIONS:** Before writing any output file (plan, requirement, summary), read `custom/rules/project-conventions.md`. These rules override upstream skill defaults.
 
+### Pre-flight BẮT BUỘC — Đồng bộ Source & Docs (đầu MỖI Gate)
+
+> Áp dụng cho **mọi Gate** của cả 3 workflow bên dưới ([DEV], [TESTER], [EXECUTE]) — 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 hiện tại → `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, không cần cảnh báo).
+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 (dự án có thể chưa dùng docs repo riêng).
+
+**Nếu bất kỳ lệnh `git pull` nào ở Bước 1–3 thất bại** (conflict, mất mạng, không có remote, v.v.) → **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.
+```
+
 ### Workflow Selection
 
 Read `.aiflow/context/current.json` → check the `taskType` field:
@@ -74,8 +94,21 @@ AI actively reads ticket + source code to understand the requirement:
    → Bắt đầu Gate 1...
    ```
 
+0.5. **Đảm bảo đang làm việc trên branch riêng của ticket (AK-Docs):**
+
+   Trước khi ghi bất kỳ file nào vào `AK-Docs/04.Coding/`, đảm bảo AK-Docs đang ở branch riêng của ticket 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. Kiểm tra `AK-Docs` hiện đang ở branch nào (`git -C AK-Docs branch --show-current`).
+   2. Nếu **chưa** ở branch `feature/[functionId]/[ticketId]`:
+      - Hỏi DEV: "Chưa có branch riêng cho ticket này trong AK-Docs. Tạo branch `feature/[functionId]/[ticketId]` từ `main` — đồng ý không?"
+      - DEV đồng ý → chạy `ak docs branch [functionId] [ticketId] --yes`
+      - DEV từ chối → tiếp tục Gate 1 trên nhánh hiện tại của AK-Docs (DEV tự quản lý branch)
+   3. Nếu **đã** ở đúng branch (ví dụ resume từ session trước, hoặc Gate 2/3/4 tiếp nối Gate 1) → bỏ qua, tiếp tục.
+
+   > ❌ Không tự thêm `--yes` khi chưa thấy DEV gõ xác nhận rõ ràng trong hội thoại.
+
 1. Read `.aiflow/context/current.json` — ticket info
-2. **Pre-flight: sync with remote** — run `git status --porcelain`; if working tree is clean, run `git pull --ff-only` to pull the latest source from remote. Skip the pull (with a `⚠️` notice to DEV) if there are uncommitted changes, the branch has diverged, or no remote tracking branch exists.
+2. **Pre-flight (bắt buộc):** chạy [Pre-flight — Đồng bộ Source & Docs](#pre-flight-bắt-buộc--đồng-bộ-source--docs-đầu-mỗi-gate) ở đầu file (sync repo source + `AK-Docs/` + `Shared-Docs/`). Lỗi → hiển thị ⚠️ cảnh báo, không dừng gate.
 3. Read source code — architecture, related files, data flow
 4. If anything is unclear — ask ONE question at a time, wait for reply
 5. Output `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` with:
@@ -104,6 +137,7 @@ DO NOT just check format — **understand the content and propose solutions**.
 
 **INVOKE:** `generate-spec` skill, then `superpowers:writing-plans`
 
+- **Pre-flight (bắt buộc):** 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.
 - Create a detailed TDD implementation plan based on the approved requirement (`AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md`).
 - Output `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md` with the detailed TDD implementation plan (step-by-step, file list, test-first order).
 - Update tracker row in `AK-Docs/04.Coding/00.Overview/_Index.md` (Gate 2 ✅).
@@ -125,6 +159,7 @@ DO NOT just check format — **understand the content and propose solutions**.
 Only runs after Gate 2 has been APPROVED.
 
 **INVOKE:** `superpowers:test-driven-development`
+- **Pre-flight (bắt buộc):** 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.
 - Complex feature (3+ files): `superpowers:subagent-driven-development`
 - Write tests FIRST — run to confirm FAIL -> implement -> PASS.
 - Bug fix EXTRA: `superpowers:systematic-debugging` + `investigate-bug` skill first.
@@ -142,6 +177,7 @@ Only runs after Gate 2 has been APPROVED.
 **INVOKE:** `review-plan` skill
 
 Mandatory order:
+0. **Pre-flight (bắt buộc):** 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.
 1. `superpowers:verification-before-completion` — all tests must PASS
 2. `impact-analysis` skill — check for breaking changes
 3. Tick `custom/rules/review-checklist.md`
@@ -172,11 +208,18 @@ Only runs after Gate 4 has been APPROVED.
 
 **INVOKE:** `superpowers:requesting-code-review`
 
+0. **Pre-flight (bắt buộc):** 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.
 1. Create `AK-Docs/04.Coding/05.Pull-Requests/[functionId]/[ticketId].md` — PR description gồm:
    - Ticket link, danh sách thay đổi chính, How to Test, Checklist for Reviewer
    - **Related Docs links:** UC Spec (`AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/`), Test Case (`AK-Docs/03.Testing/01.Testcases/[functionId]/`), Dev Plan (`AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md`)
-2. **Lưu tài liệu `AK-Docs/04.Coding/` lên remote (GitLab) TRƯỚC khi tạo Pull Request.**
-3. Guide on creating a Pull Request — dùng nội dung file trên làm PR description.
+2. **Submit `AK-Docs/04.Coding/` lên remote qua Merge Request TRƯỚC khi tạo Pull Request cho source code:**
+   - Soạn title + description cho MR (tóm tắt toàn bộ tài liệu vừa hoàn thành: Requirements, Plan, Review, PR-doc), hiển thị cho DEV xem trước.
+   - Hỏi DEV: "Nội dung commit/MR như trên — đồng ý submit AK-Docs không?"
+     - DEV đồng ý → chạy `ak docs submit --title "..." --description "..." --yes`
+     - DEV từ chối → dừng, để DEV tự commit/tạo MR khi sẵn sàng
+   - Thông báo DEV: 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 DEV tự merge.
+   - ❌ Không tự thêm `--yes` khi chưa thấy DEV gõ xác nhận rõ ràng trong hội thoại.
+3. Guide on creating a Pull Request (source code) — dùng nội dung file trên làm PR description.
 4. Update tracker row in `AK-Docs/04.Coding/00.Overview/_Index.md` (Gate 5 ✅ Done + PR link).
 
 > **Telemetry:** Run `ak gate 5 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.
@@ -192,6 +235,7 @@ Only runs after Gate 4 has been APPROVED.
 
 **INVOKE:** `test-analysis` skill
 
+0. **Pre-flight (bắt buộc):** 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.
 1. Read `.aiflow/context/current.json` — ticket title, description, acceptance criteria
 2. Fetch linked docs if URLs present in description (`ak fetch-links <url>`)
 3. Analyze scope, functional flows, non-functional requirements, risks
@@ -230,6 +274,7 @@ Only runs after Gate 1 APPROVED.
 
 **INVOKE:** `generate-testcase` skill (Phase 2a)
 
+- **Pre-flight (bắt buộc):** 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.
 - If TESTER declared `PR: <url>` → **INVOKE** `pr-impact-analysis` skill (Dev Artifacts Check) first
 - Generate test scenarios/checklist TABLE covering: Happy Path, Negative, Validation, Boundary, Edge Cases, State Transitions, Role-based, Accessibility, Compatibility, Data Integrity, Integration, Exploratory
 - Save `test-plan/checklist.md`
@@ -250,6 +295,7 @@ Only runs after Gate 1 APPROVED.
 
 **INVOKE:** `generate-testcase` skill (Phase 2b)
 
+- **Pre-flight (bắt buộc):** 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.
 - Generate detailed test cases TABLE from Phase 2a checklist: `TC_ID | Scenario | Preconditions | Test Steps | Test Data | Expected Result`
 - TC_ID format: `TC_[Module]_[NNN]` (e.g. `TC_Login_001`)
 - Expected result ONLY from ticket/spec — never from PR/dev description
@@ -271,6 +317,7 @@ Only runs after Gate 1 APPROVED.
 
 **INVOKE:** `generate-testcase` skill (Phase 2c)
 
+- **Pre-flight (bắt buộc):** 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.
 - Self-review: check duplicates, problematic TCs (vague steps, unmeasurable expected result), missing TCs, coverage gaps, accessibility/compatibility coverage
 - Output `test-plan/review-report.md` with action items
 - **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-2c-[ticket-id].md`
@@ -290,6 +337,7 @@ Only runs after Gate 1 APPROVED.
 
 **INVOKE:** `coverage-check` skill
 
+- **Pre-flight (bắt buộc):** 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.
 - Apply all action items from Phase 2c
 - Generate coverage matrix (requirement → TC IDs)
 - Export final test case set to `test-plan/test-cases/final-testcases.md`
@@ -318,6 +366,10 @@ Scripts: [N] Playwright specs generated
 
 Only runs after Gate 2 APPROVED.
 
+**Step 3.0 — Pre-flight (bắt buộc)**
+
+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 3.1 — Dev Artifacts Check (Gate 3 entry)**
 
 **INVOKE:** `pr-impact-analysis` skill — check for new commits since Gate 2. If delta found → propose TC additions → TESTER approves delta only before proceeding.
@@ -372,6 +424,7 @@ Only runs after Gate 3 APPROVED.
 
 **INVOKE:** `generate-test-report` skill
 
+0. **Pre-flight (bắt buộc):** 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.
 1. Aggregate results from `evidence/*/result.md`
 2. Summarize bugs from `bugs/BUG-*.md` by severity
 3. Verify acceptance criteria coverage from Gate 1
@@ -412,6 +465,8 @@ Coverage: [N]% acceptance criteria
 
 **INVOKE:** `execute-flow` skill (from `custom/skills/test-skills/execute-flow/SKILL.md`)
 
+**Đồng bộ Source & Docs (bắt buộc, chạy trước mọi pre-flight check khác):** 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.
+
 Pre-flight checks (stop and report if any fail):
 0. **MCP Playwright is configured** — check `~/.claude/settings.json` (global user-level) for a `playwright` key in `mcpServers`. This is global — set once, works across all repos.
    - If missing: ask TESTER "MCP Playwright chưa cấu hình. Tự động cài vào global settings (~/.claude/settings.json)? [Y/n]"
@@ -451,6 +506,8 @@ Only runs after Gate 1 APPROVED.
 
 **INVOKE:** `script-sync` skill (from `custom/skills/test-skills/script-sync/SKILL.md`)
 
+**Pre-flight (bắt buộc):** 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.
+
 Hash-based TC↔script sync — for each TC in the file:
 - **New TC** (no matching `@tc-hash` in spec): generate Playwright test using MCP (`browser_navigate` → `browser_snapshot` → `browser_generate_locator`). Never fabricate selectors.
 - **Changed TC** (hash mismatch): update the existing test block only.
@@ -479,6 +536,10 @@ Output: `ak-test/{repo}/scripts/{screenId}/{ScreenID}.spec.ts` (1 file per scree
 
 Only runs after Gate 2 APPROVED.
 
+**Step 3.0 — Pre-flight (bắt buộc)**
+
+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 3.1 — Determine run number**
 
 Check `ak-test/{repo}/results/{screenId}/` — next run is `run-{N+1}`.
@@ -526,6 +587,10 @@ Run: run-{N} | Passed: [N] | Failed: [N] | Untest: [N] | Pending: [N]
 
 Only runs after Gate 3 APPROVED.
 
+**Step 4.0 — Pre-flight (bắt buộc)**
+
+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`:
 - Per-module rows with Pass/Fail/Untest/Pending counts, R1/R2 columns, % completion
 - Go/No-Go: 0 unresolved Critical = Go
@@ -552,3 +617,50 @@ Bugs logged: [N] | Skipped: [N]
 → If blocked: follow gate-review skill response protocol
 
 > **Telemetry:** Run `ak gate 4 start --ticket [ticket-id]` when starting. Run `ak gate 4 approved --ticket [ticket-id]` when APPROVED.
+## gen-doc Task Type — 2-Gate Flow
+
+> This section applies **only** when `taskType === "gen-doc"`. All other task types use the 5-gate flow above.
+
+> `gen-doc` reuses the **same** `AK-Docs/04.Coding/` folders as the standard Dev workflow above (see `custom/rules/project-conventions.md`) — it just only uses Gate 1–2 of them, not a separate section.
+
+### GATE 1 — AI Analyze & Plan Document (auto-start)
+
+**INVOKE:** `read-study-requirement` skill
+
+1. Load ticket context + read source code / files to understand scope
+2. **Xác định `functionId` và thư mục đầu ra (BẮT BUỘC)** — theo đúng quy tắc "functionId & ticketId" trong `custom/rules/project-conventions.md`: kiểm tra `functionId`/`screenId` trong `.aiflow/context/current.json` → suy từ ticketId/input → nếu không suy ra được (task ad-hoc, không gắn với chức năng cụ thể), hỏi trực tiếp người yêu cầu (có thể dùng một mã chủ đề ngắn, ví dụ `AD-HOC` hoặc tên báo cáo). KHÔNG ĐƯỢC GHI FILE khi chưa có `functionId`.
+3. **Đảm bảo đang làm việc trên branch riêng của task (AK-Docs):** kiểm tra `AK-Docs` hiện đang ở branch nào (`git -C AK-Docs branch --show-current`). Nếu chưa ở `feature/[functionId]/[ticketId]` → hỏi: "Chưa có branch riêng cho task này trong AK-Docs. Tạo branch `feature/[functionId]/[ticketId]` từ `main` — đồng ý không?" → đồng ý thì chạy `ak docs branch [functionId] [ticketId] --yes`; từ chối thì tiếp tục trên nhánh hiện tại (người dùng tự quản lý branch). Đã đúng branch rồi thì bỏ qua. ❌ Không tự thêm `--yes` khi chưa thấy người dùng xác nhận rõ ràng.
+4. Understand the document goal, target audience, and output format
+5. If unclear → ask ONE question at a time, wait for reply
+6. Output `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` with:
+   - Document scope and target audience
+   - Content outline (sections to cover)
+   - Source references (files, features, flows to analyze)
+   - Output format: Markdown or Excel (note template path if applicable)
+   - Effort estimate
+7. Display "GATE 1: Document plan ready" → wait for **APPROVED**
+
+> **Telemetry:** Run `ak gate 1 start --ticket [ticket-id]` when starting.
+> Run `ak gate 1 approved --ticket [ticket-id]` immediately when APPROVED is received.
+
+---
+
+### GATE 2 — Generate Document + Auto Review (runs immediately after APPROVED)
+
+**DO NOT create `plan.md`. DO NOT run TDD. Proceed directly to document generation.**
+
+1. Re-read `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` (the approved outline)
+2. Read source code, trace data flows, analyze features as needed
+3. Generate the output document:
+   - **Markdown:** Save to `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md` (or the custom path/format noted in the requirement doc — e.g. Excel; still write a short pointer + summary into this file so the AK-Docs history stays complete)
+4. Self-review: verify content completeness against the approved requirement outline
+5. Create `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId]-summary.md` with a brief summary of what was generated
+6. **Submit AK-Docs lên remote qua Merge Request:**
+   - Soạn title + description cho MR (tóm tắt tài liệu vừa tạo, link ticket gốc), hiển thị cho người dùng xem trước.
+   - Hỏi: "Nội dung commit/MR như trên — đồng ý submit AK-Docs không?" → đồng ý thì chạy `ak docs submit --title "..." --description "..." --yes`; từ chối thì dừng, để người dùng tự commit/tạo MR khi sẵn sàng.
+   - Thông báo: MR đã mở, chờ **PM review & merge vào `main`** — đây là bước duyệt cuối cùng, không phải tự merge.
+   - ❌ Không tự thêm `--yes` khi chưa thấy người dùng gõ xác nhận rõ ràng trong hội thoại.
+7. Run: `ak gate 2 approved --ticket [ticket-id]` to close the task
+8. Display: `GATE 2 DONE: Document generated at [path]`
+
+**Do NOT wait for extra approval before generating the document or opening the MR — only the explicit branch/MR confirmations above gate this; run the gate 2 approved command immediately after.**

package/custom/templates/shared/ml-gate-workflow.md

@@ -18,16 +18,18 @@ You have superpowers. When a ticket context exists in `.aiflow/context/current.j
 AI actively reads the ticket and dataset to frame the problem and assess the data:
 1. Read `.aiflow/context/current.json` — ticket info
 2. **Pre-flight: sync with remote** — run `git status --porcelain`; if working tree is clean, run `git pull --ff-only` to pull the latest source from remote. Skip the pull (with a `⚠️` notice to DEV) if there are uncommitted changes, the branch has diverged, or no remote tracking branch exists.
-3. Define the prediction target, evaluation metric, baseline, success threshold, and constraints.
-4. Run EDA; assess data quality and **leakage** (target leakage, train/test contamination, temporal leakage).
-5. If anything is unclear — ask ONE question at a time, wait for reply.
-6. Output `plan/[ticket-id]/ml-problem.md` with:
+3. **Xác định `functionId` và thư mục đầu ra (BẮT BUỘC)** — theo đúng quy tắc "functionId & ticketId" trong `custom/rules/project-conventions.md`: kiểm tra `functionId`/`screenId` trong context → suy từ ticketId/input → nếu không có, hỏi DEV xác nhận trực tiếp. KHÔNG ĐƯỢC GHI FILE khi chưa có `functionId`.
+4. **Đảm bảo đang làm việc trên branch riêng của ticket (AK-Docs):** kiểm tra `AK-Docs` hiện đang ở branch nào (`git -C AK-Docs branch --show-current`). Nếu chưa ở `feature/[functionId]/[ticketId]` → hỏi DEV: "Chưa có branch riêng cho ticket này trong AK-Docs. Tạo branch `feature/[functionId]/[ticketId]` từ `main` — đồng ý không?" → đồng ý thì chạy `ak docs branch [functionId] [ticketId] --yes`; từ chối thì tiếp tục trên nhánh hiện tại (DEV tự quản lý branch). Đã đúng branch rồi thì bỏ qua. ❌ Không tự thêm `--yes` khi chưa thấy DEV xác nhận rõ ràng.
+5. Define the prediction target, evaluation metric, baseline, success threshold, and constraints.
+6. Run EDA; assess data quality and **leakage** (target leakage, train/test contamination, temporal leakage).
+7. If anything is unclear — ask ONE question at a time, wait for reply.
+8. Output `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` with:
    - Problem statement, prediction target, and evaluation metric (with justification)
    - Baseline definition and success threshold
    - Data report (shape, quality, missing values, distributions)
    - Leakage assessment (all three types checked)
    - Constraints and effort estimate
-7. Display "GATE 1: ML problem doc ready" → wait for **APPROVED**
+9. Display "GATE 1: ML problem doc ready" → wait for **APPROVED**
 
 > **Tip:** If auto-start doesn't trigger, the developer can start this gate by typing: **"start"**, **"Gate 1"** or **"Analyze ticket"**.
 
@@ -43,7 +45,7 @@ DO NOT just check format — **understand the data and propose solutions**.
 **INVOKE:** `design-experiment` skill, then `superpowers:writing-plans`
 
 - Define the validation strategy (CV scheme/splits, leakage prevention), candidate approaches and feature sets, ablation plan, and experiment-tracking setup.
-- Output `plan/[ticket-id]/experiment-plan.md` with the detailed experiment plan.
+- Output `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md` with the detailed experiment plan.
 - Display: "GATE 2 PAUSED: type APPROVED to start experiments".
 - NO EXPERIMENTS OR TRAINING until "APPROVED" is received.
 
@@ -77,7 +79,7 @@ Mandatory order:
 2. `evaluate-model` skill — held-out metrics vs baseline and threshold, error analysis, overfitting/leakage/drift checks
 3. `impact-analysis` skill — assess data pipeline and downstream blast radius
 4. Tick `custom/rules/ml-review-checklist.md`
-5. Create `plan/[ticket-id]/eval-report.md` and a model card draft
+5. Create `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` with the eval report and a model card draft (own section in the same file)
 
 Then: "GATE 4 PAUSED: type APPROVED or BUG: [description]"
 - Coding or pipeline bug → fix → repeat Gate 4.
@@ -97,7 +99,12 @@ Only runs after Gate 4 has been APPROVED.
 - Version the artifact (model, training data version, code commit, config) in the registry.
 - Package the full inference pipeline so serving matches training exactly.
 - Define the monitoring plan (input drift, prediction distribution, latency, retraining trigger).
-- Finalize the model card (intended use, data, metrics, limitations, owner).
-- Guide on creating a Pull Request with the ticket link.
+- Finalize the model card (intended use, data, metrics, limitations, owner) in `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md`.
+- **Submit `AK-Docs/04.Coding/` lên remote qua Merge Request TRƯỚC khi tạo Pull Request cho source code:**
+  - Soạn title + description cho MR (tóm tắt ML problem, experiment plan, eval report/model card), hiển thị cho DEV xem trước.
+  - Hỏi DEV: "Nội dung commit/MR như trên — đồng ý submit AK-Docs không?" → đồng ý thì chạy `ak docs submit --title "..." --description "..." --yes`; từ chối thì dừng, để DEV tự commit/tạo MR khi sẵn sàng.
+  - Thông báo DEV: 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 DEV tự merge.
+  - ❌ Không tự thêm `--yes` khi chưa thấy DEV gõ xác nhận rõ ràng trong hội thoại.
+- Guide on creating a Pull Request (source code) with the ticket link.
 
 > **Telemetry:** Run `ak gate 5 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.

package/docs/common/AIFLOW.md

@@ -2,7 +2,8 @@
 
 **Version:** 2.0.0 | **Package:** ai-flow-kit
 
-> This workflow applies to all tasks: feature, bug-fix, refactor, investigation.
+> This workflow applies to coding tasks: feature, bug-fix, refactor, investigation.
+> For document generation tasks, use task type **`gen-doc`** — a 2-gate flow (Gate 1 + Gate 2 only).
 > **Absolute Rule: Complete Gate N → Only then can you enter Gate N+1. No exceptions.**
 
 ---
@@ -399,6 +400,15 @@ Gate 1 (AI analyzes: dependency map, risk level, breaking changes, recommendatio
 → DONE (no Gates 2-5, implementation needs a separate ticket)
 ```
 
+### Generate Document (gen-doc) — 2-Gate Flow
+```
+Gate 1 (AI reads requirement, plans document: outline, scope, output format, sources)
+→ DEV reviews requirement.md → APPROVED
+→ Gate 2 (AI generates document immediately: Markdown output.md or Excel)
+         (AI self-reviews + creates task-summary.md → task DONE)
+→ NO Gate 3/4/5
+```
+
 ---
 
 ## Skills Used in Workflow