@relipa/ai-flow-kit 0.1.5 → 0.1.7-beta.0

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,57 @@ 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
+5.5. **Retrospect + propose memory drafts:** synthesize anything genuinely new learned while producing this document (architecture fact, business rule, decision) and create a **local draft** for each (no approval needed yet — `_pending/` is local-only, see `docs/internal/Memory-Architecture-v1.0.md`):
+   ```
+   ak memory draft --category 00.Shared/architecture --function-id [functionId] \
+     --slug <short-kebab-slug> --content "<≤150 words, 1 fact>" \
+     --tags <tag1,tag2> --workflows gen-doc --source "[ticket-id] / Gate 2"
+   ```
+   Skip if nothing new was learned. If `ak memory draft` reports a conflict, don't duplicate — mention the existing one instead.
+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

package/docs/common/CHANGELOG.md

@@ -9,6 +9,35 @@ 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.
@@ -16,6 +45,9 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### 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

package/docs/common/cli-reference.md

@@ -262,6 +262,7 @@ ak t n -t PROJ-33                            # specify ticket  (--ticket)
 | `plan/<id>/requirement.md` | Gate 2 |
 | `plan/<id>/plan.md` | Gate 3 |
 | `plan/<id>/summary.md` | Gate 5 |
+| `plan/<id>/output.md` _(gen-doc)_ | Done (Gate 2 complete) |
 
 **Example workflow:**
 ```bash
@@ -316,6 +317,7 @@ ak p feature                                 # generate feature prompt
 ak p investigation                           # generate investigation prompt
 ak p refactor                                # generate refactor prompt
 ak p impact                                  # generate impact analysis prompt
+ak p gen-doc                                 # generate document generation prompt (2-gate)
 ak p -l                                      # list all prompt types  (--list)
 ak p bug-fix -o p.md                         # save to file  (--output)
 ak p bug-fix -L vietnamese                   # Vietnamese language  (--lang)
@@ -323,7 +325,7 @@ ak p bug-fix -d comprehensive                # comprehensive detail  (--detail)
 ```
 
 **Options:**
-- `<type>` — Prompt type (bug-fix, feature, investigation, refactor, impact, docs)
+- `<type>` — Prompt type (bug-fix, feature, investigation, refactor, impact, docs, gen-doc)
 - `-l, --list` — List available prompt types
 - `-o, --output <file>` — Save to file instead of printing
 - `-L, --lang <lang>` — Language (english, vietnamese)