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

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:
@@ -32,7 +52,7 @@ If `taskType` is missing or unrecognized, default to the DEV workflow and ask ON
 ### Cấu trúc thư mục đầu ra
 
 ```
-04.Coding/
+AK-Docs/04.Coding/
 ├── 00.Overview/_Index.md                          ← Tracker: F-ID | Ticket | Dev | Gate | PR (cập nhật mỗi gate)
 ├── 01.Requirements/[functionId]/[ticketId].md    ← Gate 1 tạo
 ├── 02.Plans/[functionId]/[ticketId].md           ← Gate 2 tạo
@@ -54,7 +74,7 @@ AI actively reads ticket + source code to understand the requirement:
 
    Kiểm tra theo thứ tự ưu tiên:
    1. Trường `functionId` hoặc `screenId` trong `.aiflow/context/current.json`
-   2. **Suy ra từ input**: nếu đầu vào có file UC Spec / tài liệu do BA bàn giao (trong `supplementaryContext[]`, description, hoặc file được chỉ định khi `ak use <file>`) → đọc nội dung file để tìm functionId, hoặc suy từ đường dẫn thư mục chứa file (ví dụ file nằm ở `02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v1.md` → lấy `[functionId]`). Có thể tra thêm `04.Coding/00.Overview/_Index.md` hoặc `00.Project-Overview/Function-List.md` theo tên feature.
+   2. **Suy ra từ input**: nếu đầu vào có file UC Spec / tài liệu do BA bàn giao (trong `supplementaryContext[]`, description, hoặc file được chỉ định khi `ak use <file>`) → đọc nội dung file để tìm functionId, hoặc suy từ đường dẫn thư mục chứa file (ví dụ file nằm ở `AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v1.md` → lấy `[functionId]`). Có thể tra thêm `AK-Docs/04.Coding/00.Overview/_Index.md` hoặc `AK-Docs/00.Project-Overview/Function-List.md` theo tên feature.
       → Tìm được ứng viên → **hỏi xác nhận** thay vì hỏi trống:
       ```
       functionId của task này có phải là [X] không? (Y / hoặc nhập giá trị đúng)
@@ -67,22 +87,35 @@ AI actively reads ticket + source code to understand the requirement:
 
    → Đợi DEV trả lời, dùng giá trị này cho toàn bộ 5 Gates. **KHÔNG ĐƯỢC TIẾP TỤC NẾU CHƯA CÓ functionId.**
 
-   Sau đó kiểm tra thư mục `04.Coding/` trong root dự án — chưa có thì tạo đủ cây thư mục (00.Overview → 05.Pull-Requests) và file tracker `00.Overview/_Index.md`. Thông báo:
+   Sau đó kiểm tra thư mục `AK-Docs/04.Coding/` trong root dự án — chưa có thì tạo đủ cây thư mục (00.Overview → 05.Pull-Requests) và file tracker `00.Overview/_Index.md`. Thông báo:
    ```
-   ✓ Thư mục đầu ra: 04.Coding/
+   ✓ Thư mục đầu ra: AK-Docs/04.Coding/
    ✓ functionId: [functionId]  ✓ ticketId: [ticketId]
    → 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 `04.Coding/01.Requirements/[functionId]/[ticketId].md` with:
+5. Output `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` with:
    - Requirements summary (ticket summary + AC), source code analysis
    - Proposed solution and approach
    - Impact analysis, effort estimate, testing plan
-6. Update tracker row in `04.Coding/00.Overview/_Index.md`: `| [F-ID] | [ticketId] | [feature] | [dev] | ✅⬜⬜⬜⬜ Gate 1 | - |`
+6. Update tracker row in `AK-Docs/04.Coding/00.Overview/_Index.md`: `| [F-ID] | [ticketId] | [feature] | [dev] | ✅⬜⬜⬜⬜ Gate 1 | - |`
 7. **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-1-[ticket-id].md`
 8. Display gate pause message from `gate-review` skill — wait for **APPROVED**
 
@@ -104,9 +137,10 @@ DO NOT just check format — **understand the content and propose solutions**.
 
 **INVOKE:** `generate-spec` skill, then `superpowers:writing-plans`
 
-- Create a detailed TDD implementation plan based on the approved requirement (`04.Coding/01.Requirements/[functionId]/[ticketId].md`).
-- Output `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 `04.Coding/00.Overview/_Index.md` (Gate 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. 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 ✅).
 - **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-2-[ticket-id].md`
 - Display gate pause message from `gate-review` skill — CODE WILL NOT BE GENERATED until all items checked and APPROVED received.
 
@@ -125,13 +159,14 @@ 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.
-- Output `04.Coding/03.TDD-Notes/[functionId]/[ticketId].md`:
+- Output `AK-Docs/04.Coding/03.TDD-Notes/[functionId]/[ticketId].md`:
   - **Test List** — danh sách test viết TRƯỚC khi implement (checklist `- [ ] TC-01: ...`)
   - **Implementation Notes** — ghi chú phát sinh trong quá trình code
-- Update tracker row in `04.Coding/00.Overview/_Index.md` (Gate 3 ✅) when tests PASS.
+- Update tracker row in `AK-Docs/04.Coding/00.Overview/_Index.md` (Gate 3 ✅) when tests PASS.
 
 > **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.
 
@@ -142,11 +177,12 @@ 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`
-4. Create `04.Coding/04.Reviews/[functionId]/[ticketId].md` — Test Results, Impact Analysis (files changed, affected features, breaking changes), Review Checklist
-5. Update tracker row in `04.Coding/00.Overview/_Index.md` (Gate 4 ✅)
+4. Create `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` — Test Results, Impact Analysis (files changed, affected features, breaking changes), Review Checklist
+5. Update tracker row in `AK-Docs/04.Coding/00.Overview/_Index.md` (Gate 4 ✅)
 
 Then:
 - **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-4-[ticket-id].md`
@@ -172,12 +208,19 @@ Only runs after Gate 4 has been APPROVED.
 
 **INVOKE:** `superpowers:requesting-code-review`
 
-1. Create `04.Coding/05.Pull-Requests/[functionId]/[ticketId].md` — PR description gồm:
+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 (`02.BA-Specs/04.UC-Specs/[functionId]/`), Test Case (`03.Testing/01.Testcases/[functionId]/`), Dev Plan (`04.Coding/02.Plans/[functionId]/[ticketId].md`)
-2. **Lưu tài liệu `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.
-4. Update tracker row in `04.Coding/00.Overview/_Index.md` (Gate 5 ✅ Done + PR link).
+   - **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. **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/custom/templates/tools/claude.md

@@ -2,7 +2,7 @@
 
 You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
 
-> **Important:** Always read `.aiflow/context/current.json` to load ticket context and check the `04.Coding/` docs directory for existing progress before starting any task.
+> **Important:** Always read `.aiflow/context/current.json` to load ticket context and check the `AK-Docs/04.Coding/` docs directory for existing progress before starting any task.
 
 If Gate 1 does not auto-start, wait for the developer to type **"start"**, **"Gate 1"** or **"Analyze ticket"**.
 

package/custom/templates/tools/copilot.md

@@ -2,7 +2,7 @@
 
 You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
 
-> **Important:** Always check for context in `.aiflow/context/current.json` and progress in the `04.Coding/` docs folder before suggesting changes.
+> **Important:** Always check for context in `.aiflow/context/current.json` and progress in the `AK-Docs/04.Coding/` docs folder before suggesting changes.
 
 If the Gate Workflow hasn't started, wait for the developer to type **"start"** or **"Gate 1"**.
 

package/custom/templates/tools/cursor.md

@@ -2,7 +2,7 @@
 
 You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
 
-> **Important:** Always check `.aiflow/context/current.json` and the `04.Coding/` docs directory before starting any task to understand current context and progress.
+> **Important:** Always check `.aiflow/context/current.json` and the `AK-Docs/04.Coding/` docs directory before starting any task to understand current context and progress.
 
 If Gate 1 doesn't auto-start, wait for the developer to type **"start"**, **"Gate 1"** or **"Analyze ticket"**.
 

package/custom/templates/tools/gemini.md

@@ -2,7 +2,7 @@
 
 You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
 
-> **Important:** When starting a session, always read `.aiflow/context/current.json` to load ticket context and check the `04.Coding/` docs directory for existing progress.
+> **Important:** When starting a session, always read `.aiflow/context/current.json` to load ticket context and check the `AK-Docs/04.Coding/` docs directory for existing progress.
 
 If no instructions are automatically followed, wait for the developer to type **"start"** or **"Gate 1"** to start the analysis.
 

package/custom/templates/tools/generic.md

@@ -4,7 +4,7 @@ You are an expert AI assistant. Follow the project's Gate Workflow and Team Rule
 
 ## Context Awareness
 - **Ticket context**: `.aiflow/context/current.json`
-- **Task progress**: `04.Coding/<section>/[functionId]/[ticketId].md`
+- **Task progress**: `AK-Docs/04.Coding/<section>/[functionId]/[ticketId].md`
 - **Rules**: `.rules/`
 
 Follow the gated workflow and rules defined below.

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.**
 
 ---
@@ -112,7 +113,7 @@ claude                           # open Claude → AI auto-starts Gate 1
 | 2 | Read `CLAUDE.md` + source code | Understand architecture, tech stack, patterns |
 | 3 | Investigate related files & data flow | Identify affected areas, dependencies |
 | 4 | Ask clarifying questions (one at a time) | Ensure full understanding |
-| 5 | Write `04.Coding/01.Requirements/[functionId]/[ticketId].md` | Structured requirement document |
+| 5 | Write `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` | Structured requirement document |
 
 **AI asks questions when:**
 - Business requirements are vague or ambiguous
@@ -121,7 +122,7 @@ claude                           # open Claude → AI auto-starts Gate 1
 - Multiple approaches are possible and need input
 - Impact on existing features is unclear
 
-**Requirement Document Output (`04.Coding/01.Requirements/[functionId]/[ticketId].md`):**
+**Requirement Document Output (`AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md`):**
 
 ```
 ├── 1. Requirements Summary
@@ -166,13 +167,13 @@ Summary:
 - Approach: [brief description]
 - Files affected: [N] files
 
-→ Review: 04.Coding/01.Requirements/[functionId]/[ticketId].md
+→ Review: AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md
 → Type APPROVED to proceed
 → Or provide feedback to update
 ```
 
 **Gate 1 Output:**
-- `04.Coding/01.Requirements/[functionId]/[ticketId].md` approved by DEV
+- `AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md` approved by DEV
 - DEV has typed "APPROVED"
 
 ---
@@ -265,14 +266,14 @@ In fast mode, AI uses the `tdd-lean` skill instead of per-test TDD to save massi
 | 1 | `superpowers:verification-before-completion` | All tests PASS |
 | 2 | `impact-analysis` skill | No breaking changes outside scope |
 | 3 | `custom/rules/review-checklist.md` | All items ticked |
-| 4 | Create `04.Coding/04.Reviews/[functionId]/[ticketId].md` | File exists and is complete |
+| 4 | Create `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` | File exists and is complete |
 
 **If any step fails → AI fixes it first, without showing DEV.**
 
 **Summary report output:**
 
 ```
-04.Coding/04.Reviews/[functionId]/[ticketId].md
+AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md
 ├── List of changed files + reasons
 ├── Acceptance Criteria → results (Done/Not Done)
 ├── Tests: quantity, coverage
@@ -287,7 +288,7 @@ In fast mode, AI uses the `tdd-lean` skill instead of per-test TDD to save massi
 Tests: ✅ [N] passed
 Impact: [Low/Medium/High]
 Checklist: [N/N] ✅
-Summary: 04.Coding/04.Reviews/[functionId]/[ticketId].md
+Summary: AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md
 
 Type APPROVED if OK
 Type BUG: [description] if there are issues
@@ -299,7 +300,7 @@ Type BUG: [description] if there are issues
 - `BUG: requirement bug` → AI updates requirement doc → back to Gate 1
 
 **Gate 4 Output:**
-- `04.Coding/04.Reviews/[functionId]/[ticketId].md` completed
+- `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` completed
 - DEV has typed "APPROVED"
 
 ---
@@ -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
@@ -458,7 +468,7 @@ aiflow telemetry disable              # disable tracking
 
 ## Multi-AI Environment Setup
 
-One of the core strengths of `ai-flow-kit` is that the **Gate Workflow** is tool-agnostic. Since state is saved in `.aiflow/context/current.json` and the `04.Coding/` docs directory, you can switch tools mid-task.
+One of the core strengths of `ai-flow-kit` is that the **Gate Workflow** is tool-agnostic. Since state is saved in `.aiflow/context/current.json` and the `AK-Docs/04.Coding/` docs directory, you can switch tools mid-task.
 
 ### How to Switch Tools
 1. **Analyze (Gate 1)** using Claude Code CLI (great for deep codebase scans).
@@ -506,7 +516,7 @@ A: Yes. Use `aiflow task pause` to save your current progress, then `aiflow use
 **Q: If I resume a task, will Claude know which gate to start at?**
 A: Yes. The SessionStart hook reads `.aiflow/tasks/<taskId>/task-state.json` and injects gate-aware instructions. If Gate 1 was already approved, Claude will skip to Gate 2, and so on.
 **Q: Can I resume a Gate 3 (Code Generation) task in a new chatbox?**
-A: Yes. Gate 3 progress is saved via `[x]` checkboxes in `04.Coding/02.Plans/[functionId]/[ticketId].md`. If you open a new chatbox and say "continue", the AI will automatically skip completed tasks and pick up exactly where it left off.
+A: Yes. Gate 3 progress is saved via `[x]` checkboxes in `AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md`. If you open a new chatbox and say "continue", the AI will automatically skip completed tasks and pick up exactly where it left off.
 
 **Q: How does AI estimate effort?**
 A: AI analyzes the scope of changes (files affected, complexity, test requirements) and categorizes: S (< 1h), M (1-4h), L (4-8h), XL (8h+, should split).

package/docs/common/CHANGELOG.md

@@ -7,6 +7,49 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [Unreleased]
+
+## [0.1.6] - 2026-07-13
+
+### Added
+
+- **Mandatory Source & Docs sync at the start of every Gate — across DEV, TESTER, EXECUTE, BA, and QA workflows.** Previously, `git pull` for `AK-Docs`/`Shared-Docs` only ran via the `ak init` / `ak update` CLI commands (`scripts/docs-repo.js`), and the source repo itself was only synced once — inside the DEV workflow's Gate 1 pre-flight bullet. Now every Gate of every workflow syncs both the source repo and the docs repos before doing anything else:
+  - **New shared procedure — "Pre-flight — Đồng bộ Source & Docs":** (1) `cd` into the source repo itself (not just the outer workspace) → `git status --porcelain`, then `git pull --ff-only` if the working tree is clean (skipped silently if dirty, diverged, or no remote tracking branch); (2) `cd` into `AK-Docs/` (sibling folder at workspace root) → `git pull`; (3) `cd` into `Shared-Docs/` (sibling folder at workspace root) → `git pull`; (4) `cd` back to the original working directory before continuing the gate.
+  - **Failure handling:** if any `git pull` in the procedure fails (conflict, no remote, network, etc.), the AI does **not** block or stop the workflow — it shows a `⚠️ CẢNH BÁO` warning to the user and continues the gate with the current local data.
+  - **`custom/templates/shared/gate-workflow.md`** — added the shared procedure once under the mandatory intro; wired a short pointer to it into every gate of all 3 workflows it defines: `[DEV]` 5-Gate (Gates 1–5), `[TESTER]` 4-Gate (Gate 1, Phases 2a/2b/2c/2d, Gates 3–4), and `[EXECUTE]` 4-Gate (Gates 1–4). The old DEV Gate 1 bullet that only synced the source repo now points at the shared procedure instead of duplicating a narrower version of it.
+  - **`custom/templates/shared/create-spec-workflow.md`** (`[BA]` 4-Gate Spec Creation) — added the shared procedure near the top and a pointer to it at the start of Gates 1–4.
+  - **`custom/templates/shared/create-testcase-workflow.md`** (`[QA]` 4-Gate TestCase Creation) — added the shared procedure near the top and a pointer to it at the start of Gates 1–4.
+  - If `AK-Docs/` or `Shared-Docs/` doesn't exist at the workspace root, or isn't a git repo, that step is skipped silently (no warning) — the project may not use a separate docs repo.
+- **New task type `gen-doc` — "Generate Document" 2-Gate flow** (`!34 feature/new_task_type`). A lighter flow for ad-hoc documentation tasks that don't need TDD/coding gates: Gate 1 (AI reads the request, plans the document — outline, scope, output format, sources) → APPROVED → Gate 2 runs immediately (generates the document, self-reviews, writes a task summary, then auto-closes the task — no Gate 3/4/5).
+  - `scripts/detect.js` — new keyword set (`gen-doc`, `generate doc`, `tạo tài liệu`, `flow document`, …) so free-text task descriptions can auto-detect this type.
+  - `scripts/use.js` — new picker entry "📝 Generate Doc 2 Gate" in the manual task-type selector.
+  - `scripts/task.js` — `gen-doc` capped at `maxGate = 2`; gate labels ("Generate Document" / "Done") and gate-history summary generation updated accordingly.
+  - `scripts/prompt.js` (`ak prompt gen-doc`) and `scripts/hooks/session-start.js` (auto-start + fast-mode messages) — new gen-doc-specific instructions.
+  - `custom/templates/shared/gate-workflow.md` — new `## gen-doc Task Type — 2-Gate Flow` section; `custom/rules/project-conventions.md` — new gen-doc output-path table; `docs/common/AIFLOW.md` / `cli-reference.md` — documented the flow and the new `ak p gen-doc` prompt type.
+  - Initial output paths were `plan/[ticket-id]/requirement.md` / `output.md` / `task-summary.md` — since relocated to `AK-Docs/04.Coding/`, see **Changed** below.
+- **Figma design integrated into the DEV Gate workflow (Gate 1→4)** (`!32 feature/figma-gate-workflow`). UI tickets now get Figma wired in automatically, no manual skill invocation:
+  - **Gate 1** (`read-study-requirement`) detects a Figma URL (ticket description / `supplementaryContext[]` / asks DEV once), fetches the design **exactly once** via Figma MCP, and caches the shared artifact `design/` (`design-context.md` with layout/tokens/component list/image map, `nodes.json` raw cache, `images/`, `figma-manifest.json`).
+  - **Gate 2** (`generate-spec`) reads the cached `design-context.md` (no second MCP call) and folds the component tree, design-token mapping, and an image-copy task into the TDD plan.
+  - **Gate 3** (`figma-to-component`, new **Gate mode**) reuses the cached `nodes.json`, copies images to `public/assets/figma/`, and generates the components — again without re-calling MCP.
+  - **Gate 4** (`review-plan`) adds a **Design Conformance Check**: compares the built UI against `design-context.md` region-by-region, against the actual rendered reference image, not just a text checklist (no-fabricate / no-omit / layout / color / typography / every component and image present).
+  - Refresh: typing "reload figma" re-fetches at Gate 1 and overwrites the cached `design/` artifact.
+  - **New anti-429 guard** — `scripts/hooks/figma-rate-limit.js`, a `PreToolUse` hook (installed by `scripts/init.js`) that throttles every `mcp__figma__*` call to 6 REST-call-units/60s (tunable via `FIGMA_RATE_LIMIT_UNITS`; `download_figma_images` counts as 3 units). It **sleeps rather than fails**, so calls are delayed, never dropped — needed because Figma rate-limits `get_figma_data`/image renders by **seat tier**, and a View/Collab-seat token gets only ~6 Tier-1 calls/**month** (effectively unusable) vs 10–20/min for a Dev/Full seat.
+  - `docs/common/workflows/figma.md` — documents the Gate-by-Gate table above, the shared `design/` artifact layout, and a new "Rate limits (429)" section (seat-tier budget table, `Retry-After` triage, troubleshooting entry for immediate 429s).
+- **`ak docs branch` / `ak docs submit`** — new CLI commands (`scripts/docs-branch.js`) so the AI can help create a `feature/<functionId>/<taskId>` branch in `AK-Docs`/`Shared-Docs` from `main` (`ak docs branch`) and commit + push + open a Merge Request (`ak docs submit --title ... --description ...`), auto-detecting GitLab/GitHub via the remote URL to run `glab mr create` / `gh pr create`, or falling back to a pre-filled manual MR link if neither CLI is installed. Both commands print the full plan and only perform any git write action when passed `--yes` — which the AI may only add after the developer has explicitly confirmed the plan in chat (otherwise, or with no interactive TTY, it's a no-op dry run). This keeps the same "AI never commits/pushes unasked" guarantee as the existing `block-git-write` hook, extended to a capability that hook can't cover.
+- **`docs/internal/Docs-Management-Flow.md`** — new internal doc formalizing the `AK-Docs` branch/MR workflow for every role: `main` is protected, PM-reviewed-and-merged only; every other role (BA/Dev/QA/TL) updates docs on a `feature/<functionId>/<taskId>` branch created from `main`; a step-by-step table makes explicit which steps are self-review (the authoring role) vs. the single mandatory PM-review-and-merge gate. Generalizes the branch/MR model `Memory-Architecture-v1.0.md` §5.1 designed for `99.Memory/` to all of `AK-Docs`.
+
+### Fixed
+
+- **`aiflow prompt <type>` still emitted `plan/[ticket-id]/...` paths** — The 0.1.5 migration to `04.Coding/` (see below) updated `gate-workflow.md`, the skills, all 5 tool templates, and `session-start.js`, but missed `scripts/prompt.js`. Its `PROMPT_TEMPLATES` (used by `aiflow prompt feature|bug-fix|refactor|investigation|impact-analysis|testing|documentation` to build the copy-paste prompt for Cursor/Gemini/manual use) still hard-coded `Output plan/[ticket-id]/requirement.md` / `plan.md` / `summary.md`, contradicting the `custom/rules/project-conventions.md` override appended later in the same prompt — this was the root cause of `/plan` still appearing at the project root even on 0.1.5-beta.1. All 11 occurrences now point at the current `04.Coding/<section>/[functionId]/[ticketId].md` convention.
+- **`ak init` still gitignored `plan/`** — `ensureAiflowGitignored()` in `scripts/init.js` added `plan/` to `.gitignore` on every init, reinforcing the deprecated convention. Removed; `04.Coding/` output now lives in `AK-Docs/` (see below) and isn't part of the source repo's `.gitignore` concerns.
+
+### Changed
+
+- **`gen-doc` and ML workflow output relocated from `plan/[ticket-id]/` to `AK-Docs/04.Coding/`.** Both `gen-doc` (2-gate, added this version — see **Added** above) and the ML 5-gate workflow (`ml-gate-workflow.md`, pre-existing) still wrote to the legacy `plan/[ticket-id]/requirement.md` / `output.md` / `task-summary.md` / `ml-problem.md` / `experiment-plan.md` / `eval-report.md` paths that the 0.1.5 Dev-workflow migration deliberately left untouched. Per user decision, neither gets its own AK-Docs section — both now reuse the **same** `01.Requirements/02.Plans/03.TDD-Notes/04.Reviews` folders as the standard Dev workflow (gen-doc only ever populates the first two; ML uses all it needs through Gate 4, folding the model card into the Gate 4 review doc). Both workflows now also require the same mandatory `functionId` confirmation at Gate 1 that DEV/BA/QA already had, which neither had before. Updated: `custom/templates/shared/gate-workflow.md` (gen-doc section) and `ml-gate-workflow.md`, `custom/rules/project-conventions.md` and `ml-conventions.md` (output-path tables + legacy-path deprecation notice extended to cover these), `scripts/prompt.js` (gen-doc template) and `scripts/hooks/session-start.js` (gen-doc fast-mode text), and 4 ML skills (`design-experiment`, `evaluate-model`, `explore-data`, `frame-ml-problem`) whose completion checklists still hard-coded the old paths independent of the rules-file override.
+- **Branch/MR hooks wired into every workflow that writes to `AK-Docs`.** `create-spec-workflow.md` (BA), `create-testcase-workflow.md` (QA), `gate-workflow.md` (DEV + gen-doc), and `ml-gate-workflow.md` (ML) each now: (a) confirm `functionId`/`taskId` and create/checkout the `AK-Docs` branch `feature/[functionId]/[taskId]` **before** writing the first gate output (new Bước 0.5, right after the existing functionId pre-flight), and (b) at the final gate, submit that branch via `ak docs submit` — with the commit/MR title+description shown and explicitly confirmed by the user first — instead of the previous vague "lưu tài liệu lên remote (GitLab)" instruction. Every step is explicit that PM reviews and merges the MR; the authoring role never merges it themselves.
+
+- **DEV workflow output relocated to `AK-Docs/04.Coding/`** — Per `docs/internal/Project-Structure.md` / `Coding-Structure.md`, `04.Coding/` (and its BA/QA siblings `02.BA-Specs/`, `03.Testing/`, `00.Project-Overview/`) belong under the `AK-Docs/` docs repo (a sibling of the source repo, synced via `scripts/docs-repo.js`), not directly at the source repo root. Updated all references across `CLAUDE.md`, `custom/rules/project-conventions.md`, `custom/templates/shared/gate-workflow.md`, the 5 tool templates, the DEV skills (`read-study-requirement`, `generate-spec`, `review-plan`, `gate-review`), `docs/common/AIFLOW.md` / `ai-integration.md` / `workflows/{bug-fix,feature}.md`, `scripts/hooks/session-start.js`, and `scripts/prompt.js`. `scripts/task.js` now resolves the coding dir via `resolveDocsRepoPath(PROJECT_DIR, 'AK-Docs')` (from `docs-repo.js`) instead of hard-coding the path, so `findTaskDocs()` / `detectCurrentGate()` look under `AK-Docs/04.Coding/` first, with the legacy `plan/<taskId>/` folder (at the source repo root) still checked as a fallback.
+
 ## [0.1.5] - 2026-07-01
 
 ### Added