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

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

@@ -3,7 +3,29 @@
 > **For:** `create-spec`
 > **Persona:** Business Analyst (BA)
 > **Goal:** Chuyển đổi yêu cầu thô (Jira / Backlog / file) thành tài liệu Đặc tả Use Case (UC Spec) hoàn chỉnh để bàn giao Dev/Test, tuân theo quy trình UCflow.
-> **Interaction Rules:** Hỏi ONE câu hỏi tại một thời điểm — đợi BA trả lời trước khi tiếp tục. KHÔNG hỏi nhiều câu cùng lúc.
+> **Interaction Rules:** Hỏi ONE câu hỏi tại một thời điểm — đợi BA trả lời trước khi tiếp tục. KHÔNG hỏi nhiều câu cùng lúc. Số lượng câu hỏi KHÔNG cố định — phải phản ánh đúng độ phức tạp thực tế của yêu cầu (xem chi tiết ở Gate 1 Bước 2).
+
+---
+
+### Quy ước Blocking / Non-blocking & đánh dấu PENDING
+
+> Áp dụng cho **cả 4 Gate** — dùng để quyết định câu hỏi nào bắt buộc phải Confirmed trước khi tiến gate tiếp theo, và câu nào được phép defer mà vẫn cho qua.
+
+Mỗi Gap/Assumption/câu hỏi Q&A phải được gắn nhãn mức độ ảnh hưởng ngay khi phát hiện:
+
+- **🔴 Blocking** — chưa trả lời thì KHÔNG thể tiến gate tiếp theo một cách đáng tin cậy. Gồm: ảnh hưởng cấu trúc dữ liệu (thêm/sửa field, quan hệ), luồng chính (happy path) của use case, phân quyền/bảo mật, hoặc quyết định kiến trúc khó đảo ngược sau khi đã code.
+- **🟡 Non-blocking** — có thể tạm ghi Open (deferred) và vẫn đi tiếp. Gồm: chi tiết UI/text hiển thị, giá trị mặc định có thể chỉnh sau, alternative/exception flow hiếm gặp, câu hỏi cần chờ khách hàng xác nhận nhưng không chặn thiết kế các phần khác.
+
+**Khi BA/khách hàng defer (chưa trả lời ngay) một câu hỏi:**
+
+- 🟡 Non-blocking → đánh dấu **Open**, tiếp tục ngay sang câu hỏi kế tiếp hoặc gate kế tiếp — KHÔNG chặn.
+- 🔴 Blocking → AI phải hiển thị cảnh báo rõ lý do đây là blocking + hệ quả nếu bỏ qua, rồi hỏi xác nhận BA có chắc muốn tiếp tục không. Nếu BA xác nhận đồng ý tiếp tục dù chưa trả lời → vẫn đánh dấu Open nhưng giữ nhãn 🔴 Blocking (không được hạ xuống Non-blocking) — mục "Điều kiện dừng chặn APPROVED" ở mỗi Gate dựa vào nhãn này.
+
+**Đánh dấu PENDING trong tài liệu output:** bất kỳ nội dung nào phụ thuộc vào một câu hỏi còn Open (Blocking hoặc Non-blocking) phải ghi rõ marker tại đúng vị trí liên quan trong `Analysis_v(n).md` / `UI-Prototype` / `UC-Spec_v1.md`, thay vì tự suy diễn nội dung để lấp đầy:
+
+```
+⚠️ [PENDING - QA-0N] <mô tả ngắn nội dung còn thiếu>
+```
 
 ---
 
@@ -189,40 +211,48 @@ Nếu workspace mở dạng parent folder chứa cả `ak docs` lẫn source cod
 - Xem xét các khía cạnh: validate dữ liệu, định dạng nhập liệu, phân quyền, xử lý ngoại lệ, thông báo lỗi
 - Liệt kê **toàn bộ** Gap/Assumption tìm được — không chỉ những điểm "cốt yếu"
 
+> ❌ **KHÔNG** tự giới hạn số câu hỏi theo một số cố định (ví dụ luôn dừng ở 5-6 câu) bất kể độ phức tạp của input. Số câu hỏi phải phản ánh đúng số Gap/Assumption thực sự tồn tại: yêu cầu đơn giản (1 field, 1 luồng) có thể chỉ cần 2-3 câu; yêu cầu phức tạp (nhiều actor, nhiều luồng, tích hợp hệ thống khác) có thể cần 15-20+ câu. Nếu trong lúc hỏi/nghe trả lời phát hiện thêm Gap mới, bổ sung ngay câu hỏi mới vào cuối vòng lặp — không đóng vòng lặp sớm chỉ vì đã hỏi "đủ nhiều".
+
+**Phân loại mức ảnh hưởng:** trước khi hỏi, gắn nhãn mỗi Gap là 🔴 Blocking hoặc 🟡 Non-blocking theo [Quy ước Blocking / Non-blocking](#quy-ước-blocking--non-blocking--đánh-dấu-pending) ở đầu file.
+
 **Vòng lặp hỏi-đáp:** Với từng Gap/Assumption trong danh sách, hỏi **ONE câu một lúc**, đợi BA trả lời trước khi hỏi câu tiếp theo:
 
 - BA trả lời đủ rõ → đánh dấu **Confirmed**, tích hợp ngay vào bản phân tích đang xây dựng, chuyển sang câu hỏi tiếp theo
-- BA trả lời "chưa biết" / "để hỏi lại [stakeholder]" / "chưa chốt được ngay" → đánh dấu **Open** (deferred), ghi chú lý do, vẫn chuyển sang câu hỏi tiếp theo — KHÔNG chặn cả vòng lặp lại vì một câu chưa trả lời được
-- Lặp lại cho tới khi **mọi** Gap/Assumption trong danh sách đã được hỏi (mỗi câu ở trạng thái Confirmed hoặc Open tường minh)
+- BA trả lời "chưa biết" / "để hỏi lại [stakeholder]" / "chưa chốt được ngay":
+  - 🟡 Non-blocking → đánh dấu **Open** (deferred), ghi chú lý do, chuyển ngay sang câu hỏi tiếp theo — KHÔNG chặn
+  - 🔴 Blocking → hiển thị cảnh báo lý do đây là blocking + hệ quả nếu bỏ qua, hỏi BA xác nhận có chắc muốn tiếp tục không; BA xác nhận → đánh dấu **Open** nhưng giữ nhãn 🔴 Blocking, vẫn chuyển sang câu tiếp theo
+- Lặp lại cho tới khi **mọi** Gap/Assumption trong danh sách đã được hỏi (mỗi câu ở trạng thái Confirmed hoặc Open tường minh, kèm nhãn Blocking/Non-blocking)
 
-Chỉ sau khi vòng lặp này hoàn tất (không còn Gap nào **chưa được hỏi**) mới chuyển sang Bước 3. Số lượng câu hỏi Open còn lại sau vòng lặp này chính là input cho Gate 2.
+Chỉ sau khi vòng lặp này hoàn tất (không còn Gap nào **chưa được hỏi**) mới chuyển sang Bước 3. Số lượng câu hỏi Open còn lại (và nhãn Blocking/Non-blocking của chúng) chính là input cho Gate 2.
 
 #### Bước 3: Soạn thảo Kết quả phân tích sơ bộ
 - **READ template:** `.claude/skills/ba-skills/skill-ba-initial-analysis-template-v1.md`
 - Điền đầy đủ các mục theo template: Actors, Facts, Assumptions, Gap Analysis table — dùng câu trả lời **Confirmed** từ vòng lặp Bước 2 làm nội dung chính, không phải giả định của AI
-- Gap Analysis table chỉ còn liệt kê các Gap **Open** (deferred) từ vòng lặp Bước 2
+- Gap Analysis table chỉ còn liệt kê các Gap **Open** (deferred) từ vòng lặp Bước 2, kèm nhãn 🔴 Blocking / 🟡 Non-blocking
+- Với mỗi Gap Open, chèn marker `⚠️ [PENDING - QA-0N]` tại đúng vị trí nội dung liên quan (mục 3/4 của template) thay vì bỏ trống hoặc tự suy diễn
+- Nếu tài liệu còn ít nhất 1 Gap Open → thêm banner đầu tài liệu: `⚠️ TÀI LIỆU CHƯA ĐẦY ĐỦ — còn [N] câu hỏi Open ([X] Blocking, [Y] Non-blocking), xem QnA-Log_v1.md`
 - Lưu: `02.BA-Specs/01.Analysis/[functionId]/Analysis_v1.md`
 
 #### Bước 4: Soạn thảo danh sách Q&A
 
 - **READ skill:** `.claude/skills/ba-skills/skill-ba-qna-v1.md`
 - **READ template:** `.claude/skills/ba-skills/skill-ba-qna-template-v1.md`
-- Ghi lại **toàn bộ** câu hỏi đã hỏi ở vòng lặp Bước 2 dưới dạng log: mỗi câu kèm câu trả lời và trạng thái cuối cùng
+- Ghi lại **toàn bộ** câu hỏi đã hỏi ở vòng lặp Bước 2 dưới dạng log: mỗi câu kèm câu trả lời, nhãn Blocking/Non-blocking, và trạng thái cuối cùng
   - **Confirmed** — BA đã trả lời trong Bước 2, ghi kèm câu trả lời
-  - **Open** — BA đã xác nhận chưa trả lời được ngay (cần hỏi lại stakeholder khác), ghi kèm lý do deferred
+  - **Open** — BA đã xác nhận chưa trả lời được ngay (cần hỏi lại stakeholder khác), ghi kèm lý do deferred + nhãn 🔴 Blocking hoặc 🟡 Non-blocking
 - Không tạo câu hỏi mới ở bước này — đây là bản ghi (log) của vòng lặp đã chạy ở Bước 2, không phải một vòng hỏi mới
 - Lưu: `02.BA-Specs/02.QnA/[functionId]/QnA-Log_v1.md`
 
 #### Bước 5: Gate Review & Pause
 - **INVOKE** `gate-review` skill (generate mode) — ghi `.aiflow/review/gate-1-[functionId].md`
-- **Kiểm tra Q&A bắt buộc:** Đọc `QnA-Log_v1.md` — đếm số câu có trạng thái **Open**
+- **Kiểm tra Q&A bắt buộc:** Đọc `QnA-Log_v1.md` — đếm số câu **Open**, tách riêng theo nhãn 🔴 Blocking và 🟡 Non-blocking
 - Hiển thị gate pause message — chờ phản hồi từ BA
 
-**Nếu nhận được APPROVED mà QnA-Log_v1.md còn câu hỏi Open → từ chối ngay, hiển thị:**
+**Nếu còn câu Open 🔴 Blocking → từ chối APPROVED ngay, hiển thị:**
 
-⛔ GATE 1 BLOCKED — Còn [N] câu hỏi chưa được trả lời trong QnA-Log_v1.md.
+⛔ GATE 1 BLOCKED — Còn [N] câu hỏi Blocking chưa được trả lời trong QnA-Log_v1.md.
 
-| ID | Câu hỏi còn Open |
+| ID | Câu hỏi còn Open (Blocking) |
 |----|-----------------|
 | [Q_ID] | [nội dung câu hỏi] |
 
@@ -231,17 +261,26 @@ Vui lòng cung cấp câu trả lời theo một trong 3 cách:
 → Option B: paste nội dung bảng Q&A đã điền vào chat
 → Option C: đặt file `QnA-Log_v1_response.md` vào thư mục `02.QnA/[functionId]/` rồi gõ NEXT
 
-❌ APPROVED không được chấp nhận cho đến khi 100% câu hỏi đã Confirmed.
+❌ APPROVED không được chấp nhận cho đến khi mọi câu hỏi **Blocking** đã Confirmed.
 
-**Khi APPROVED (chỉ sau khi tất cả câu hỏi trong QA(1).md đã Confirmed):**
+**Nếu chỉ còn câu Open 🟡 Non-blocking (không còn Blocking) → cho phép APPROVED, nhưng hiển thị cảnh báo ngay trong gate pause message trước khi BA gõ APPROVED:**
+
+⚠️ Còn [N] câu hỏi Non-blocking chưa Confirmed — có thể APPROVED để tiếp tục, tài liệu sẽ giữ marker `[PENDING - QA-0N]` tại các phần liên quan cho tới khi được bổ sung ở Gate 2.
+
+| ID | Câu hỏi còn Open (Non-blocking) |
+|----|-----------------|
+| [Q_ID] | [nội dung câu hỏi] |
+
+**Khi APPROVED (không còn câu Blocking Open — câu Non-blocking Open được phép tồn tại):**
 → **INVOKE** `gate-review` skill (verify mode) — chạy `ak review check --gate 1 --ticket [functionId]`
 → Nếu passed: `ak gate 1 approved --ticket [functionId]` → chuyển Gate 2
 → Nếu blocked: làm theo gate-review skill response protocol
 
 **Definition of Done:**
 - [ ] `functionId` đã được xác định và thư mục đầu ra đã sẵn sàng
-- [ ] File `Analysis_v1.md` tạo đúng vị trí, cấu trúc đúng template, có bảng Gap Analysis
-- [ ] File `QnA-Log_v1.md` có ít nhất 1 câu hỏi cho mỗi Gap, tất cả trạng thái **Open**
+- [ ] File `Analysis_v1.md` tạo đúng vị trí, cấu trúc đúng template, có bảng Gap Analysis, số Gap phản ánh đúng độ phức tạp thực tế (không bị gò về một số cố định)
+- [ ] File `QnA-Log_v1.md` có ít nhất 1 câu hỏi cho mỗi Gap, mỗi câu có nhãn Blocking/Non-blocking rõ ràng
+- [ ] Không còn câu hỏi 🔴 Blocking ở trạng thái Open
 - [ ] Không có giả định nào được tự ý chốt thành Spec mà không đưa vào Q&A
 
 > **Telemetry:** Run `ak gate 1 start --ticket [functionId]` khi bắt đầu gate này.
@@ -270,8 +309,8 @@ Vui lòng cung cấp câu trả lời theo một trong 3 cách:
 #### 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:
-  - Đủ thông tin → cập nhật trạng thái: **Confirmed**
-  - Chưa rõ hoặc phát sinh nghiệp vụ mới → giữ trạng thái **Open**, bổ sung ghi chú
+  - Đủ thông tin → cập nhật trạng thái: **Confirmed**, xóa marker `[PENDING - QA-ID]` liên quan
+  - Chưa rõ hoặc phát sinh nghiệp vụ mới → giữ trạng thái **Open**, bổ sung ghi chú, giữ nguyên nhãn 🔴 Blocking / 🟡 Non-blocking đã gắn từ Gate 1 (hoặc gắn mới nếu là Gap phát sinh)
 
 #### Bước 2: Tích hợp thông tin vào tài liệu phân tích
 - Lấy thông tin từ các câu Confirmed → cập nhật vào `Analysis_v(n).md`
@@ -280,7 +319,7 @@ Vui lòng cung cấp câu trả lời theo một trong 3 cách:
 
 #### Bước 3: Rẽ nhánh theo trạng thái Q&A
 
-**Kịch bản A — Vẫn còn câu hỏi Open:**
+**Kịch bản A — Còn câu hỏi Open 🔴 Blocking:**
 1. Kiểm tra `Analysis_v(n+1).md` có phát sinh Gap mới không
 2. Tạo: `02.BA-Specs/02.QnA/[functionId]/QnA-Log_v(m+1).md` — chỉ giữ câu Open và câu mới phát sinh
 3. **INVOKE** `gate-review` skill (generate mode) — ghi `.aiflow/review/gate-2-[functionId]-round-[m+1].md`
@@ -289,7 +328,8 @@ Vui lòng cung cấp câu trả lời theo một trong 3 cách:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ⏸️  GATE 2 — VÒNG Q&A [m+1]
 
-Câu hỏi còn Open: [N]
+Câu hỏi còn Open (🔴 Blocking): [N]
+Câu hỏi còn Open (🟡 Non-blocking): [M]
 File Q&A mới:     [02.BA-Specs/02.QnA/[functionId]/QnA-Log_v(m+1).md](02.BA-Specs/02.QnA/[functionId]/QnA-Log_v(m+1).md)
 File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md)
 
@@ -299,23 +339,40 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 
 5. Lặp lại Bước 1 khi nhận phản hồi mới
 
-**Nếu BA gõ APPROVED khi đang ở Kịch bản A (còn câu hỏi Open) → từ chối ngay:**
+**Nếu BA gõ APPROVED khi đang ở Kịch bản A (còn câu hỏi Open 🔴 Blocking) → từ chối ngay:**
 
-⛔ GATE 2 BLOCKED — Còn [N] câu hỏi chưa Confirmed.
+⛔ GATE 2 BLOCKED — Còn [N] câu hỏi Blocking chưa Confirmed.
 
-| ID | Câu hỏi còn Open |
+| ID | Câu hỏi còn Open (Blocking) |
 |----|-----------------|
 | [Q_ID] | [nội dung câu hỏi] |
 
 → Cung cấp câu trả lời (Option A/B/C) rồi gõ NEXT để AI xử lý tiếp.
-❌ APPROVED chỉ được chấp nhận khi 100% câu hỏi đã Confirmed.
+❌ APPROVED chỉ được chấp nhận khi mọi câu hỏi **Blocking** đã Confirmed.
+
+**Kịch bản B — Chỉ còn câu hỏi Open 🟡 Non-blocking (không còn Blocking):**
+
+1. Tạo `QnA-Log_v(m+1).md` như Kịch bản A (giữ câu Non-blocking Open + câu mới phát sinh)
+2. Hiển thị cho BA 2 lựa chọn, không tự chọn thay:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⏸️  GATE 2 — CÒN [M] CÂU HỎI NON-BLOCKING CHƯA CONFIRMED
+
+Các câu hỏi này không chặn thiết kế Gate 3/4, nhưng output sẽ giữ marker `[PENDING - QA-ID]` tại các phần liên quan cho tới khi được bổ sung.
+
+→ Cách 1: cung cấp câu trả lời (Option A/B/C) rồi gõ NEXT để xử lý tiếp
+→ Cách 2: gõ APPROVED để chấp nhận tiếp tục dù output chưa đầy đủ ở các mục này
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. BA gõ NEXT với phản hồi mới → lặp lại Bước 1
+2. BA gõ APPROVED → coi là đã xác nhận chấp nhận output chưa đầy đủ, chuyển sang xử lý APPROVED bên dưới
 
-**Kịch bản B — Tất cả đã Confirmed:**
+**Kịch bản C — Tất cả đã Confirmed:**
 1. Chốt tài liệu phân tích (phiên bản cuối cùng là đầu vào Gate 3)
 2. **INVOKE** `gate-review` skill (generate mode) — ghi `.aiflow/review/gate-2-[functionId].md`
 3. Hiển thị gate pause message — đợi **APPROVED**
 
-**Khi APPROVED (chỉ áp dụng Kịch bản B):**
+**Khi APPROVED (Kịch bản B hoặc C — không còn câu Blocking Open):**
 → **INVOKE** `gate-review` skill (verify mode) — chạy `ak review check --gate 2 --ticket [functionId]`
 → Nếu passed: `ak gate 2 approved --ticket [functionId]` → chuyển Gate 3
 → Nếu blocked: làm theo gate-review skill response protocol
@@ -323,7 +380,8 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 **Definition of Done:**
 - [ ] Mọi câu trả lời đều được phân tích và phân loại trạng thái
 - [ ] Tài liệu phân tích phiên bản mới tích hợp đầy đủ thông tin nghiệp vụ mới nhất
-- [ ] Không còn câu hỏi nào ở trạng thái **Open** trước khi tiến Gate 3
+- [ ] Không còn câu hỏi 🔴 Blocking ở trạng thái Open trước khi tiến Gate 3
+- [ ] Nếu còn câu 🟡 Non-blocking Open, BA đã xác nhận rõ ràng (gõ APPROVED sau khi thấy cảnh báo) và các mục liên quan trong Analysis đã có marker `[PENDING - QA-ID]`
 
 > **Telemetry:** Run `ak gate 2 start --ticket [functionId]` khi bắt đầu gate này.
 > Run `ak gate 2 approved --ticket [functionId]` sau khi gate-review verify passed. Run as-is — không thêm shell redirects.
@@ -334,7 +392,7 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 
 **Mục tiêu:** Dựa trên tài liệu phân tích đã chốt, thiết kế bản mẫu giao diện (Prototype) độc lập bằng HTML/CSS để trực quan hóa các thành phần và luồng tương tác.
 
-**Điều kiện vào Gate 3:** Tất cả Q&A đã **Confirmed** và Gate 2 đã **APPROVED**.
+**Điều kiện vào Gate 3:** Không còn câu hỏi 🔴 Blocking Open và Gate 2 đã **APPROVED** (câu 🟡 Non-blocking Open, nếu còn, mang marker `[PENDING - QA-ID]` sang cùng Analysis).
 
 **Đầu vào (Inputs):**
 - `02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n).md` — phiên bản cuối
@@ -349,6 +407,7 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 #### 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
+- Nếu Analysis còn marker `[PENDING - QA-ID]` liên quan đến thành phần giao diện nào → giữ nguyên placeholder trực quan cho thành phần đó (không tự bịa nội dung/behavior để lấp đầy) và ghi chú `<!-- PENDING - QA-ID -->` cạnh phần tử HTML tương ứng
 
 #### Bước 2: Thiết kế và viết code HTML/CSS
 - **READ skill:** `.claude/skills/ba-skills/skill-ba-prototype-v1.md` và làm theo
@@ -406,6 +465,7 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 - **READ skill:** `.claude/skills/ba-skills/skill-ba-write-uc-spec-v1.md`
 - Tạo: `02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v1.md`
 - Điền General Information: Use Case ID, Title, Version, Actors, Preconditions, Postconditions
+- Nếu Analysis/Prototype đầu vào còn marker `[PENDING - QA-ID]` (câu Non-blocking chưa Confirmed) → giữ nguyên marker tại đúng vị trí liên quan (Business Rule, UI Component, Flow step) trong UC Spec, không tự bịa nội dung để lấp đầy; thêm banner đầu tài liệu: `⚠️ UC SPEC CHƯA ĐẦY ĐỦ — còn [N] mục PENDING, xem QnA-Log_v(m).md`
 
 #### Bước 2: Mô tả luồng sự kiện (Flow of Events)
 - **Main Flow** — happy path
@@ -450,7 +510,7 @@ File phân tích:   [02.BA-Specs/01.Analysis/[functionId]/Analysis_v(n+1).md](02
 - [ ] 100% element HTML được mô tả trong bảng UI Components (id, loại, ràng buộc)
 - [ ] Mã Mermaid hợp lệ, thể hiện đủ Main/Alternative/Exception Flow
 - [ ] Business Rules đầy đủ với mã `[BR-NNN]` và thông báo lỗi chính xác
-- [ ] Tài liệu không chứa ghi chú mơ hồ hoặc câu hỏi chưa giải quyết
+- [ ] Không còn giả định ngầm chưa Confirm bị viết như thể đã chốt; mọi nội dung Non-blocking Open còn lại đã có marker `[PENDING - QA-ID]` rõ ràng tại đúng vị trí (không phải ghi chú mơ hồ chung)
 
 > **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.
@@ -497,9 +557,11 @@ Sau khi Gate 4 đã APPROVED (UC Spec hoàn thành):
 - ❌ **KHÔNG** bỏ qua thứ tự Gate — luôn đi từ Gate 1 → 2 → 3 → 4
 - ❌ **KHÔNG** tự chốt giả định nghiệp vụ mà không đưa vào Q&A
 - ❌ **KHÔNG** dùng `superpowers:brainstorming` ở Gate 1 — terminal state của skill đó invoke `writing-plans`, bypass cấu trúc BA workflow
-- ✅ **BẮT BUỘC** ở Gate 1 Bước 2: hỏi hết **toàn bộ** Gap/Assumption xác định được, từng câu một, ngay trong hội thoại — không giới hạn ở "điểm mơ hồ cốt yếu". Chỉ được ghi Open (deferred sang QnA-Log) khi BA xác nhận rõ ràng là chưa trả lời được ngay
-- ❌ **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** ở Gate 1 Bước 2: hỏi hết **toàn bộ** Gap/Assumption xác định được, từng câu một, ngay trong hội thoại — không giới hạn ở "điểm mơ hồ cốt yếu" và **không giới hạn theo một số câu hỏi cố định** bất kể độ phức tạp input. Chỉ được ghi Open (deferred sang QnA-Log) khi BA xác nhận rõ ràng là chưa trả lời được ngay
+- ✅ **BẮT BUỘC** gắn nhãn 🔴 Blocking / 🟡 Non-blocking cho mỗi Gap/câu hỏi ngay khi phát hiện (xem [Quy ước Blocking / Non-blocking](#quy-ước-blocking--non-blocking--đánh-dấu-pending))
+- ❌ **KHÔNG** tiến Gate 3 khi vẫn còn câu hỏi 🔴 Blocking ở trạng thá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 🔴 **Blocking** 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
+- ✅ **ĐƯỢC PHÉP chấp nhận APPROVED** ở Gate 1/2/4 khi chỉ còn câu hỏi 🟡 **Non-blocking** Open, với điều kiện: đã hiển thị cảnh báo rõ ràng cho BA trước khi nhận APPROVED, và mọi nội dung phụ thuộc câu hỏi đó được đánh dấu `[PENDING - QA-ID]` tại đúng vị trí trong output — không được tự suy diễn nội dung để lấp đầy
 - ✅ **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ớ

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

@@ -18,6 +18,8 @@
 
 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.
 
+> ❌ **KHÔNG** tự ý liệt kê (`git branch -a`), checkout, hoặc đọc/diff nhiều branch trong repo source để tự dò tìm "nhánh đang phát triển" của feature — rất tốn token và thời gian, và dễ đọc nhầm code chưa hoàn chỉnh/chưa merge. Bước 1 chỉ `git pull` đúng branch hiện tại đang checkout (thường là `main`/`develop`). Nếu cần biết chính xác code nào đã thay đổi cho ticket này → xem bước **Dev Artifacts Check** (Bước 1.5, Gate 1, bên dưới): hỏi TESTER cung cấp PR link hoặc commit SHA/branch name cụ thể, rồi fetch/diff **đúng** phạm vi đó qua skill `pr-impact-analysis`.
+
 **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ó:
 
 ```
@@ -33,6 +35,7 @@ Các skill sau đây được cài tự động vào `.claude/skills/test-skills
 
 | Skill | File |
 |---|---|
+| `PR Impact Analysis` | `.claude/skills/pr-impact-analysis/SKILL.md` |
 | `QA Writing Standards` | `.claude/skills/test-skills/rules/qa-writing-standards.md` |
 | `Directory & Naming Convention` | `.claude/skills/test-skills/rules/directory-and-naming-convention.md` |
 | `Template TestCase` | `.claude/skills/test-skills/template/testcase-template.md` |
@@ -204,6 +207,26 @@ Nếu tất cả điều kiện thỏa mãn → thông báo ngắn rồi tiếp
 - Nếu có `supplementaryContext[]` → đọc từng item (SRS file, Figma link, API spec, spec MD file)
 - Nếu có file yêu cầu thô được chỉ định → đọc file đó
 
+#### Bước 1.5: Dev Artifacts Check (PR/Commit-based)
+
+**Mục tiêu:** xác định **chính xác** phạm vi code đã thay đổi cho ticket này, để mở rộng coverage (regression scope) mà **không** phải tự dò/đọc toàn bộ branch đang phát triển của feature (tốn token, tốn thời gian, dễ đọc nhầm code chưa xong).
+
+1. Kiểm tra ticket/context có PR link đính kèm không (`.aiflow/context/current.json`, mô tả ticket).
+2. **Có PR link, hoặc TESTER đã khai báo `PR: <url>` trong chat** → **INVOKE** skill `pr-impact-analysis` ngay, dùng PR đó.
+3. **Chưa có PR/commit nào được biết** → hỏi TESTER **một câu duy nhất**:
+
+```text
+Để xác định đúng phạm vi ảnh hưởng code (tránh phải rà toàn bộ branch), bạn cung cấp giúp PR link hoặc commit SHA/branch name của thay đổi cho ticket này (có thể nhiều PR/commit nếu multi-repo). Nếu chưa có, gõ "chưa có" để bỏ qua bước này.
+```
+
+4. Xử lý câu trả lời của TESTER:
+   - Cung cấp PR/commit/branch → **INVOKE** skill `pr-impact-analysis` với thông tin đó (dùng fallback `git fetch` + `git diff main...<branch>` nếu không phải PR).
+   - Trả lời "chưa có" → ghi nhận vào `test-plan/impact-analysis.md` (hoặc tương đương) "chưa có dev artifacts — sẽ re-check ở Gate 3", **không block Gate 1**.
+5. Kết quả `pr-impact-analysis` (màn hình ảnh hưởng trực tiếp/gián tiếp, đề xuất regression TCs) được dùng làm input bổ sung cho Bước 2 và Gate 2 (Scenario Building) — **không** dùng để xác định expected result (vẫn lấy từ ticket/UC Spec/System Requirement).
+
+> ❌ **KHÔNG** tự ý `git branch -a`, checkout, hoặc đọc lần lượt nhiều branch để tìm "code đang phát triển" — luôn đi qua PR/commit cụ thể mà TESTER xác nhận, qua skill `pr-impact-analysis`.
+> Ở Gate 3 (trước khi thiết kế TC chi tiết), re-run bước này nếu đã có `impact-analysis.md` từ Gate 1 — dùng Delta Detection của `pr-impact-analysis` (so SHA cũ/mới) để bắt commit mới, không đọc lại toàn bộ diff.
+
 #### Bước 2: Phân tích yêu cầu và đánh giá rủi ro
 - **READ skill:** `.claude/skills/test-skills/rules/qa-writing-standards.md` — đọc trước để nắm quy ước chung
 - **READ skill:** `.claude/skills/test-skills/categories/00-core/00.01.requirement-analysis.md`
@@ -357,6 +380,10 @@ Nếu tất cả điều kiện thỏa mãn → thông báo ngắn rồi tiếp
 
 **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 0.7: Dev Artifacts Check — Delta Detection
+
+Nếu `test-plan/impact-analysis.md` đã có PR/commit từ Gate 1 (Bước 1.5) → re-run `pr-impact-analysis` (Delta Detection): so SHA đã ghi với SHA hiện tại, nếu có commit mới thì chỉ đọc diff phần thêm mới, bổ sung TC nếu cần. Không có gì mới hoặc chưa từng có PR → bỏ qua, không cần hỏi lại TESTER.
+
 #### 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`
@@ -545,15 +572,16 @@ Sau khi Gate 4 đã APPROVED (bộ Test Case hoàn thành):
 
 | Gate | Skills đọc | Output |
 |---|---|---|
-| Gate 1 | `QA_Writing_Standards`, `00.01 Requirement Analysis`, `00.02 Risk Analysis` | `01_Requirement_Analysis_Result.md`, `01_QA.md` |
+| Gate 1 | `pr-impact-analysis` (Bước 1.5), `QA_Writing_Standards`, `00.01 Requirement Analysis`, `00.02 Risk Analysis` | `01_Requirement_Analysis_Result.md`, `01_QA.md` |
 | Gate 2 | `00.03 Scenario Builder`, `01.06 Error Guessing`, `03.02 Workflow Testing`, Domain skills | `02_Test_Scenarios_Result.md`, `02_QA.md` |
-| Gate 3 | `testcase-template`, `01.01 BVA`, `01.02 EP`, `01.03 Decision Table`, `01.06 Error Guessing`, `02.01`–`02.04`, `03.01`, `03.03`, `04.01`, `04.04` | `03_Test_Cases_Draft_Result.md`, `03_QA.md` |
+| Gate 3 | `pr-impact-analysis` (Delta Detection nếu có PR từ Gate 1), `testcase-template`, `01.01 BVA`, `01.02 EP`, `01.03 Decision Table`, `01.06 Error Guessing`, `02.01`–`02.04`, `03.01`, `03.03`, `04.01`, `04.04` | `03_Test_Cases_Draft_Result.md`, `03_QA.md` |
 | Gate 4 | `00.04 TC Review`, `99.01 Coverage Review` | `04_Final_Result.md`, `04_QA.md`, `[functionId]_TestCase.md` |
 
 ---
 
 ### Quy tắc bắt buộc
 
+- ❌ **KHÔNG** tự ý liệt kê/checkout/đọc nhiều branch trong repo source để dò tìm thay đổi code — xác định phạm vi ảnh hưởng code phải qua PR link hoặc commit SHA/branch cụ thể do TESTER cung cấp (Bước 1.5, Gate 1) + skill `pr-impact-analysis`
 - ❌ **KHÔNG** bỏ qua thứ tự Gate — luôn đi từ Gate 1 → 2 → 3 → 4
 - ❌ **KHÔNG** tự suy diễn nghiệp vụ — ghi rõ Assumption và TBD khi thiếu thông tin
 - ❌ **KHÔNG** sinh `04_Final_Result.md` mà thiếu `[functionId]_TestCase.md` (hoặc ngược lại)

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

@@ -725,12 +725,13 @@ Bugs logged: [N] | Skipped: [N]
 > Implements "Vấn đề 5" trong `docs/internal/PM Workflow_v1.0.md`. **Không chờ APPROVED để bắt đầu** — chạy tự động ngay sau Gate 2 Bước 7, không cần lệnh riêng và không cần chờ PM merge MR (merge là việc độc lập của PM). `INVOKE`: `ingest-data` skill § 5 cho toàn bộ logic phân tích/đề xuất — mục này chỉ nêu gate mechanics.
 
 1. Đọc lại entry vừa ghi + điều tra source/docs liên quan (skill § 5.1).
-2. Quyết định content này có cần task không (skill § 5.2). Nếu KHÔNG cần task → hiển thị thông báo tương ứng và **kết thúc luôn, không chạy `ak gate 3 start`, không có Gate 3 Display**.
+2. Quyết định content này có cần task không (skill § 5.2 — với entry từ `Confirmations-Log`, chạy qua checklist tối thiểu thay vì chỉ dựa Action items viết sẵn). Nếu KHÔNG cần task → hiển thị thông báo tương ứng, chạy `ak gate 3 skip --ticket [ticket-id] --reason "<1 câu lý do>"` (không chạy `ak gate 3 start`), và **kết thúc luôn, không có Gate 3 Display**. `skip` vẫn đóng gate đúng cách (advance `currentGate` giống `approved`) — task hiện đúng "done" trên dashboard, không treo ở trạng thái "sẵn sàng chạy Gate 3" mãi.
 3. Nếu CẦN task → chạy `ak gate 3 start --ticket [ticket-id]`, rồi đề xuất danh sách task (skill § 5.3), cho PM sửa/thêm/xoá (skill § 5.4), lặp tới khi PM hài lòng.
 4. Điểm dừng xác nhận trước khi tạo ticket (skill § 5.5) — ❌ không tự thêm `--yes`, phải có xác nhận rõ ràng trong hội thoại.
 5. Xác định project đích trên Backlog/Jira (skill § 5.6, dùng `ak backlog-projects`/`ak jira-projects` + `ak backlog-set-default-project`/`ak jira-set-default-project`).
-6. Tạo ticket bằng `ak tasks create-tickets <file>.json --json` (skill § 5.7). Nếu thiếu WRITE credentials, hỏi PM nhập ngay trong chat rồi `ak credentials set <field> "<value>"` và thử lại đúng 1 lần.
-7. Ghi ngược link ticket vào entry gốc + hiển thị tổng kết (skill § 5.8).
+6. Nếu danh sách có ≥ 2 task, hỏi PM có muốn gộp dưới 1 ticket cha không — tạo mới / dùng sẵn / không cần (skill § 5.6b).
+7. Tạo ticket bằng `ak tasks create-tickets <file>.json --json` (skill § 5.7), kèm `parentTicket` nếu Bước 6 xác định có. Nếu thiếu WRITE credentials, hỏi PM nhập ngay trong chat rồi `ak credentials set <field> "<value>"` và thử lại đúng 1 lần. Nếu lỗi `parent-not-found`/`parent-create-failed`, hiển thị nguyên lỗi và hỏi PM muốn thử ticket cha khác, bỏ qua ticket cha, hay dừng lại.
+8. Ghi ngược link ticket vào entry gốc + hiển thị tổng kết (skill § 5.8).
 8. Run: `ak gate 3 approved --ticket [ticket-id]` để đóng task.
 
-> **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` chỉ khi Bước 2 kết luận CẦN task. Run `ak gate 3 approved --ticket [ticket-id]` khi Gate 3 hoàn tất.
+> **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` chỉ khi Bước 2 kết luận CẦN task. Run `ak gate 3 approved --ticket [ticket-id]` khi Gate 3 hoàn tất, hoặc `ak gate 3 skip --ticket [ticket-id] --reason "..."` khi Bước 2 kết luận KHÔNG cần task.

package/docs/common/CHANGELOG.md

@@ -7,6 +7,16 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.2.2] - 2026-08-06
+
+### Added
+
+- **`ak gate <n> skip --ticket <id> [--reason <text>]`** — a gate can now close as "skipped" (legitimately produced no deliverable) instead of only `start`/`approved`. First consumer: `ingest-data` Gate 3, when the AI decides the ingested content is reference-only and no task list is needed — it now runs `ak gate 3 skip` instead of leaving the gate untouched. `scripts/task.js`'s `updateTaskGateState()` gained a `skip` branch that records `skippedGates[gate] = {at, reason}` in `task-state.json` and advances `currentGate` exactly like `approved` does, so every existing "is this task done" check (which only ever inspects `currentGate`) keeps working with zero changes. Prompted by an impact assessment for the `ai-flow-ex` VS Code extension's dashboard, which was showing skipped-Gate-3 ingest-data tasks stuck as "ready to run Gate 3" forever — see `docs/superpowers/specs/2026-08-06-ingest-data-gate3-skipped-state-design.md` in `ai-flow-ex` for the paired UI-side change (reads `skippedGates` to render a distinct "⏭ Skipped" badge instead of the generic "✓ Approved").
+
+### Fixed
+
+- **`ak task next` treated `ingest-data` as a 2-gate flow** — a stale assumption left over from before Gate 3 (task creation & ticket generation) was added to `ingest-data` earlier in the same release cycle. `scripts/task.js` grouped it with `gen-doc`/`create-system-requirement` (`maxGate = 2`), so pausing via `ak task next` on Gate 2 would prematurely mark the task `status: 'done'` and `gateLabel(3, 'ingest-data')` returned `'Done'` instead of `'Sinh Task & Tạo Ticket'`. Split into its own 3-gate branch (`maxGate = 3`); `gen-doc`/`create-system-requirement` are unaffected.
+
 ## [0.2.1] - 2026-08-05
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0",
   "description": "All-in-one AI Flow Kit for team development with Claude AI - skills, templates, and MCP adapters",
   "author": "Example Team",
   "publishConfig": {

package/scripts/link-resolver.js

@@ -3,9 +3,13 @@ const https = require('https');
 const chalk = require('chalk');
 
 const BACKLOG_RE = /https?:\/\/([\w.-]+\.backlog(?:tool)?\.com)\/view\/([A-Z][A-Z0-9_]+-\d+)(?:#comment-(\d+))?/i;
-// Backlog Document permalink — "Copy link" on a Document page gives /alias/document/{id}.
-// NOTE: Nulab's Document REST API is new (2026) — path unverified against a live space, adjust if it 404s.
-const BACKLOG_DOCUMENT_RE = /https?:\/\/([\w.-]+\.backlog(?:tool)?\.com)\/(?:alias\/)?document\/(\d+)(?:#comment-(\d+))?/i;
+// Backlog Document permalink — "Copy link" on a Document page gives /alias/document/{id},
+// where {id} is Nulab's hex document ID (e.g. 0193b335c62173de9547bab5dd0b5324), not numeric.
+// Newer "Share link" format adds a project-key + /e/ prefix: /document/{PROJECT_KEY}/e/{id}.
+// Confirmed live against a real space (2026-08-06): GET /api/v2/documents/{id} returns the
+// body as `plain` (not `plainText`/`content`) — see fetchBacklogDocument below.
+// Comment fetch (fetchBacklogDocumentComment) is still unverified — adjust its field names if it 404s or returns empty content.
+const BACKLOG_DOCUMENT_RE = /https?:\/\/([\w.-]+\.backlog(?:tool)?\.com)\/(?:alias\/)?document\/(?:[A-Z][A-Z0-9_]*\/e\/)?([0-9a-f]+)(?:#comment-(\d+))?/i;
 // Backlog Wiki permalink — "Copy link" on a Wiki page gives /alias/wiki/{id}.
 const BACKLOG_WIKI_RE = /https?:\/\/([\w.-]+\.backlog(?:tool)?\.com)\/alias\/wiki\/(\d+)/i;
 const JIRA_RE = /https?:\/\/([\w.-]+\.atlassian\.net)\/browse\/([A-Z][A-Z0-9_]+-\d+)/i;
@@ -150,7 +154,7 @@ async function fetchBacklogDocument(domain, apiKey, documentId) {
     documentId: String(documentId),
     title: doc.title || doc.name || '',
     tag: (doc.tags || []).map(t => t.name).join(', '),
-    content: (doc.plainText || doc.content || '').substring(0, 4000),
+    content: (doc.plain || doc.plainText || doc.content || '').substring(0, 4000),
   };
 }
 
@@ -193,24 +197,41 @@ async function fetchBacklogPriorities(domain, apiKey) {
   return httpsGet(`https://${domain}/api/v2/priorities?apiKey=${apiKey}`);
 }
 
+/**
+ * Fetches a single Backlog issue — used to validate a PM-supplied "ticket cha có sẵn" before
+ * using it as `parentIssueId` for a batch of child issues (PM Workflow_v1.0.md Vấn đề 5, ticket cha).
+ * Returns the internal numeric `id` (needed for `parentIssueId`, which is NOT the issueKey).
+ */
+async function getBacklogIssue(domain, apiKey, issueIdOrKey) {
+  const issue = await httpsGet(`https://${domain}/api/v2/issues/${issueIdOrKey}?apiKey=${apiKey}`);
+  return { id: issue.id, issueKey: issue.issueKey, projectId: issue.projectId, summary: issue.summary || '' };
+}
+
 /**
  * Creates a Backlog issue. Requires an apiKey with WRITE permission — distinct from the
  * read-only key used elsewhere in this file for `ak fetch-links`/`ak use`.
  * `projectId`, `summary`, `issueTypeId`, `priorityId` are mandatory per Backlog's API.
+ *
+ * `parentIssueId` (optional) — Backlog's internal numeric issue `id` (not the `issueKey`) to
+ * link this as a child issue. ⚠️ NOT verified against a live space: requires the target project
+ * to have issue hierarchy ("Subtasking") enabled — if it isn't, Backlog rejects the request and
+ * the caller should surface the raw error rather than assume the link succeeded.
  */
-async function createBacklogIssue(domain, apiKeyWrite, { projectId, summary, description, issueTypeId, priorityId }) {
+async function createBacklogIssue(domain, apiKeyWrite, { projectId, summary, description, issueTypeId, priorityId, parentIssueId }) {
+  const payload = {
+    projectId: String(projectId),
+    summary,
+    issueTypeId: String(issueTypeId),
+    priorityId: String(priorityId),
+    description: description || '',
+  };
+  if (parentIssueId) payload.parentIssueId = String(parentIssueId);
   const issue = await httpsPost(
     `https://${domain}/api/v2/issues?apiKey=${apiKeyWrite}`,
-    {
-      projectId: String(projectId),
-      summary,
-      issueTypeId: String(issueTypeId),
-      priorityId: String(priorityId),
-      description: description || '',
-    },
+    payload,
     { bodyType: 'form' }
   );
-  return { ticketId: issue.issueKey, url: `https://${domain}/view/${issue.issueKey}`, raw: issue };
+  return { ticketId: issue.issueKey, internalId: issue.id, url: `https://${domain}/view/${issue.issueKey}`, raw: issue };
 }
 
 function jiraAuth(email, token) {
@@ -258,25 +279,44 @@ async function fetchJiraComment(domain, email, token, ticketId, commentId) {
 
 // ── Jira WRITE — issue creation (PM Workflow_v1.0.md "Vấn đề 5") ────────────
 
+/**
+ * Fetches a single Jira issue — used to validate a PM-supplied "ticket cha có sẵn" before
+ * using its key as `parent` for a batch of child issues.
+ */
+async function getJiraIssue(domain, email, token, ticketId) {
+  const issue = await httpsGet(
+    `https://${domain}/rest/api/3/issue/${ticketId}`,
+    { Authorization: jiraAuth(email, token), Accept: 'application/json' }
+  );
+  const fields = issue.fields || {};
+  return { key: issue.key, projectKey: fields.project ? fields.project.key : null, summary: fields.summary || '' };
+}
+
 /**
  * Creates a Jira issue. `apiTokenWrite`/`emailWrite` are distinct from the read-only
  * credentials used elsewhere in this file — same "separate WRITE key" policy as Backlog.
+ *
+ * `parentKey` (optional) — Jira issue key to link this as a child via `fields.parent`.
+ * ⚠️ NOT verified against a live instance: this field works directly for team-managed
+ * ("next-gen") projects; company-managed ("classic") projects may require the child's
+ * `issuetype` to be a dedicated `Subtask` type instead — if Jira rejects the request,
+ * surface the raw error rather than assume the link succeeded.
  */
-async function createJiraIssue(domain, emailWrite, apiTokenWrite, { projectKey, summary, description, issueTypeName }) {
+async function createJiraIssue(domain, emailWrite, apiTokenWrite, { projectKey, summary, description, issueTypeName, parentKey }) {
+  const fields = {
+    project: { key: projectKey },
+    summary,
+    issuetype: { name: issueTypeName || 'Task' },
+    description: {
+      type: 'doc',
+      version: 1,
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: description || '' }] }],
+    },
+  };
+  if (parentKey) fields.parent = { key: parentKey };
   const issue = await httpsPost(
     `https://${domain}/rest/api/3/issue`,
-    {
-      fields: {
-        project: { key: projectKey },
-        summary,
-        issuetype: { name: issueTypeName || 'Task' },
-        description: {
-          type: 'doc',
-          version: 1,
-          content: [{ type: 'paragraph', content: [{ type: 'text', text: description || '' }] }],
-        },
-      },
-    },
+    { fields },
     { headers: { Authorization: jiraAuth(emailWrite, apiTokenWrite), Accept: 'application/json' }, bodyType: 'json' }
   );
   return { ticketId: issue.key, url: `https://${domain}/browse/${issue.key}`, raw: issue };
@@ -361,6 +401,6 @@ module.exports = {
   fetchBacklogTicket, fetchBacklogComment,
   fetchBacklogDocument, fetchBacklogDocumentComment, fetchBacklogWiki,
   fetchJiraTicket, fetchJiraComment,
-  fetchBacklogIssueTypes, fetchBacklogPriorities, createBacklogIssue,
-  createJiraIssue,
+  fetchBacklogIssueTypes, fetchBacklogPriorities, createBacklogIssue, getBacklogIssue,
+  createJiraIssue, getJiraIssue,
 };

package/scripts/task.js

@@ -345,8 +345,9 @@ async function nextGate(taskId) {
     const isGenDoc = taskType === 'gen-doc';
     const isSystemRequirement = taskType === 'create-system-requirement';
     const isIngestData = taskType === 'ingest-data';
-    const isTwoGateDoc = isGenDoc || isSystemRequirement || isIngestData;
-    const maxGate = isTwoGateDoc ? 2 : 5;
+    const isTwoGateDoc = isGenDoc || isSystemRequirement;
+    const isDocFlow = isTwoGateDoc || isIngestData;
+    const maxGate = isTwoGateDoc ? 2 : isIngestData ? 3 : 5;
 
     const taskState = {
         ...existing,
@@ -371,7 +372,7 @@ async function nextGate(taskId) {
     console.log(chalk.green(`✓ Gate ${currentGate} approved for ${resolvedId}.`));
     console.log(chalk.gray(`  Summary saved to: .aiflow/tasks/${resolvedId}/task-summary.md`));
 
-    if (isTwoGateDoc && currentGate >= maxGate) {
+    if (isDocFlow && currentGate >= maxGate) {
         console.log(chalk.green('\n  ✅ Document workflow complete. Task is done.'));
     } else {
         const nextLabel = gateLabel(nextGateNum, taskType);
@@ -380,7 +381,7 @@ async function nextGate(taskId) {
         console.log(chalk.gray(`    1. Open a NEW chatbox or terminal session.`));
         console.log(chalk.gray(`    2. Run: aiflow task resume ${resolvedId} (to load context).`));
         console.log(chalk.gray(`    3. Type "start" or "continue from the current plan".`));
-        if (!isTwoGateDoc) {
+        if (!isDocFlow) {
             console.log(chalk.yellow(`       (Note: Gate 3 progress is saved via [x] checkboxes in the Gate 2 plan doc (AK-Docs/04.Coding/02.Plans/).`));
             console.log(chalk.yellow(`        The AI will automatically resume the exact task you left off.)`));
         }
@@ -485,7 +486,10 @@ async function detectCurrentGate(taskId) {
 
 async function generateMarkdownSummary(taskState, taskType = null) {
     taskType = taskType || taskState.taskType || 'feature';
-    const maxGate = taskType === 'testing' ? 4 : ((taskType === 'gen-doc' || taskType === 'create-system-requirement' || taskType === 'ingest-data') ? 2 : 5);
+    const maxGate = taskType === 'testing' ? 4
+        : taskType === 'ingest-data' ? 3
+        : (taskType === 'gen-doc' || taskType === 'create-system-requirement') ? 2
+        : 5;
     const lines = [];
     lines.push(`# Task Summary: ${taskState.taskId}`);
     lines.push(`**Title:** ${taskState.title}`);
@@ -531,7 +535,8 @@ function gateLabel(n, taskType = null) {
     if (taskType === 'ingest-data') {
         if (n === 1) return 'Fetch, Classify, Draft';
         if (n === 2) return 'Branch + Merge Request';
-        if (n >= 3) return 'Done';
+        if (n === 3) return 'Sinh Task & Tạo Ticket';
+        if (n >= 4) return 'Done';
     }
     const labels = {
         1: 'AI Analyze Requirement',
@@ -599,15 +604,19 @@ module.exports.createOrActivateTaskState = async function createOrActivateTaskSt
 };
 
 /**
- * Called by `aiflow gate <N> <start|approved>` to keep task-state.json in sync
+ * Called by `aiflow gate <N> <start|approved|skip>` to keep task-state.json in sync
  * with the actual gate progress — without requiring the user to run `task next`.
  *
  * - 'start'   : advances currentGate to N (if N is higher than stored value)
  * - 'approved': records approval timestamp + advances currentGate to N+1
+ * - 'skip'    : records a skip (gate legitimately produced no deliverable, e.g.
+ *               ingest-data Gate 3 deciding no task is needed) + advances currentGate
+ *               to N+1, same as 'approved' — every "is this task done" check only ever
+ *               inspects `currentGate`, so a skipped gate still lets the task complete.
  *
  * Silently no-ops when task-state.json does not exist yet (task not saved).
  */
-module.exports.updateTaskGateState = async function updateTaskGateState(ticketId, gateNum, action) {
+module.exports.updateTaskGateState = async function updateTaskGateState(ticketId, gateNum, action, options = {}) {
     if (!ticketId) return;
     const taskDir   = path.join(TASKS_DIR, ticketId);
     const statePath = path.join(taskDir, 'task-state.json');
@@ -633,6 +642,14 @@ module.exports.updateTaskGateState = async function updateTaskGateState(ticketId
         if (gateNum >= (existing.currentGate || 1)) {
             updated.currentGate = gateNum + 1;
         }
+    } else if (action === 'skip') {
+        const skippedGates = { ...(existing.skippedGates || {}) };
+        skippedGates[String(gateNum)] = { at: now, reason: options.reason || '' };
+        updated.skippedGates = skippedGates;
+        // Advance currentGate to next gate (only if not already ahead) — same as 'approved'
+        if (gateNum >= (existing.currentGate || 1)) {
+            updated.currentGate = gateNum + 1;
+        }
     }
 
     await fs.writeJson(statePath, updated, { spaces: 2 });