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

package/custom/skills/ingest-data/SKILL.md

@@ -133,17 +133,41 @@ Nếu người dùng yêu cầu sửa (thêm/bớt ý, đổi log đích, sửa
 - **Chỉ là tham khảo** → hiển thị: `ℹ️ Nội dung này không phát sinh task — chỉ lưu làm tài liệu tham khảo. Gate 3 kết thúc.` rồi chạy `ak gate 3 skip --ticket [ticket-id] --reason "<1 câu lý do>"` (không cần `ak gate 3 start` trước) và dừng, không hỏi thêm. Việc này đóng gate đúng cách — dashboard (ai-flow-ex) hiển thị "⏭ Gate 3 skipped — \<lý do\>" thay vì để task treo mãi ở trạng thái "sẵn sàng chạy Gate 3".
 - **Có hành động cụ thể** → tiếp tục Bước 3. Khi không chắc (ví dụ nội dung vừa có FYI vừa có 1 ý cần sửa code) — nghiêng về đề xuất task cho phần cần hành động, bỏ qua phần FYI, không tự bịa task cho phần không rõ.
 
+**Riêng khi nguồn là `Confirmations-Log`** (khách hàng CHỐT chính thức 1 thay đổi requirement) — đây là trường hợp dễ đề xuất thiếu task nhất nếu chỉ dựa vào Action items viết sẵn trong nội dung (vd chỉ thấy 1 bug fix được nêu tên, bỏ sót toàn bộ phần spec/testcase phát sinh từ chính rule vừa chốt). Trước khi sang Bước 3, tự chạy qua đủ checklist tối thiểu sau — không hiển thị checklist này cho PM, chỉ dùng để tự rà soát không bỏ sót:
+
+1. **UC Spec** — functionId này đã có UC Spec chưa, và rule vừa chốt đã phản ánh trong Spec chưa? Chưa → task `spec`.
+2. **System Requirement** — chỉ cần nếu có task `coding` theo sau (Gate 1 coding sẽ tự chặn nếu System Requirement thiếu/lệch version, xem `CLAUDE.md` pre-check) → task `system-requirement`.
+3. **Impact analysis** — thay đổi có đủ phức tạp/rủi ro (ảnh hưởng nhiều module/feature khác, hoặc PM cần thấy effort/scope trước khi giao việc) để cần 1 tài liệu đánh giá riêng, tách khỏi Gate 1 coding không? Cần → task `impact-analysis`.
+4. **Coding** — có thay đổi hành vi hệ thống cần code không? Cần → task `coding` (tách thành nhiều task nhỏ nếu phạm vi lớn, mỗi task 1 title riêng).
+5. **Data migration/backfill** — rule mới có áp dụng hồi tố lên dữ liệu đã tồn tại không (khác với chỉ áp dụng từ nay về sau)? Có → thêm 1 task `coding` **riêng** cho việc migration/backfill, không gộp chung với task coding chính (2 rủi ro/effort khác nhau, cần review riêng).
+6. **Create/Update testcase** — cần → task `test`.
+7. **Execute test** — cần → task `execute-test`.
+
+Không phải mục nào cũng luôn có (case rule chỉ áp dụng tương lai thì mục 5 = không cần) — nhưng phải đi qua đủ 7 mục và có lý do trước khi kết luận không cần, không bỏ qua mục nào chỉ vì nội dung entry không viết thành Action item rõ ràng.
+
 ### 5.3 Bước 3 — Đề xuất danh sách task
 
 Mỗi task gồm:
 
 | Trường | Ghi chú |
 |---|---|
-| `type` | `spec` (tạo/update UC Spec) · `coding` · `test` · `other` (update tài liệu không thuộc BA/QA/Dev, vd Rules) |
+| `type` | `spec` (tạo/update UC Spec) · `system-requirement` (tạo/update System Requirement) · `impact-analysis` (đánh giá phạm vi ảnh hưởng, tách riêng khỏi Gate 1 coding) · `coding` (bao gồm cả migration/backfill, tách task riêng nếu cần) · `test` (tạo/update testcase) · `execute-test` (thực thi testcase có sẵn) · `other` (update tài liệu không thuộc BA/QA/Dev, vd Rules) |
 | `title` | Ngắn, hành động rõ (vd "Cập nhật flow OTP theo feedback khách — tăng thời hạn 30s → 90s") |
-| `track` | BA / Dev / QA — để PM biết ai sẽ nhận task này |
+| `track` | BA / Dev / QA / Analyst — để PM biết ai sẽ nhận task này |
 | `description` | Theo đúng template mục 6.1 `PM Workflow_v1.0.md`: |
 
+Mỗi `type` map thẳng vào 1 task type có sẵn khi người nhận chạy `ak use TICKET-XXX` (không cần Gate workflow mới — xem `scripts/use.js` cho danh sách đầy đủ):
+
+| `type` task | Task type chọn ở `ak use` |
+|---|---|
+| `spec` | 📋 Create Spec |
+| `system-requirement` | 📐 Create System Requirement |
+| `impact-analysis` | 📊 Impact Analysis |
+| `coding` | 🐛 Bug Fix / ✨ Feature / 🔄 Refactor (tuỳ nội dung task) |
+| `test` | ✅ Create TestCase |
+| `execute-test` | ▶️ Execute Test |
+| `other` | Không map task type nào — tuỳ nội dung, người nhận tự xử lý ngoài Gate workflow |
+
 ```text
 ## Nội dung task
 [Mô tả task do AI đề xuất]
@@ -190,33 +214,57 @@ Check LOCAL trước, chỉ hỏi khi thật sự chưa biết (Vấn đề 5.1)
 2. Đã có → dùng luôn, hiển thị rõ cho PM biết đang dùng project nào + nguồn (đã lưu từ lần trước).
 3. Chưa có → hiển thị danh sách project vừa fetch được, PM chọn 1 → lưu lại bằng `ak backlog-set-default-project <id> <key>` hoặc `ak jira-set-default-project <key>` — để lần sau không hỏi lại.
 
+### 5.6b Bước 6b — Ticket cha (chỉ hỏi khi danh sách có ≥ 2 task)
+
+Nếu danh sách chỉ có 1 task, không có gì để gộp — coi `parentTicket.mode = "none"` và bỏ qua bước này.
+
+Nếu ≥ 2 task, hỏi đúng 1 câu:
+
+```text
+Gộp N task này dưới 1 ticket cha?
+1. Tạo mới ticket cha
+2. Dùng ticket cha có sẵn — cho biết ticket ID
+3. Không cần ticket cha
+```
+
+- **(1)** → hỏi PM 1 tiêu đề ngắn cho ticket cha (gợi ý: dùng lại "Tổng quan nội dung thay đổi" đã soạn cho task `spec` ở Bước 3, nếu có; không có thì tự tóm tắt 1 câu). `parentTicket = { "mode": "create", "title": "...", "description": "..." }`.
+- **(2)** → PM nhập ticket ID có sẵn. `parentTicket = { "mode": "existing", "existingId": "<ID do PM nhập>" }`. Việc xác minh ticket đó có tồn tại thật diễn ra ở Bước 7 (khi gọi `ak tasks create-tickets`) — không tự coi là đúng trước khi có kết quả lệnh.
+- **(3)** → `parentTicket = { "mode": "none" }`.
+
+⚠️ **Chưa xác minh trên instance thật:** liên kết cha-con cần Backlog project đã bật tính năng phân cấp issue (Subtasking), hoặc Jira project hỗ trợ field `parent` trực tiếp (rõ nhất với project dạng team-managed; company-managed có thể cần issue type `Subtask` riêng — chưa test). Nếu Bước 7 báo lỗi `parent-create-failed`/`parent-not-found`, hoặc 1 task con lỗi do gán parent thất bại — hiển thị nguyên lỗi cho PM, hỏi PM muốn: thử lại với ticket cha khác, tiếp tục tạo các ticket con không gắn parent (`mode: "none"`), hay dừng lại để PM xử lý cấu hình Backlog/Jira trước.
+
 ### 5.7 Bước 7 — Tạo ticket
 
 1. Ghi danh sách task đã duyệt ra 1 file JSON tạm (vd `.aiflow/tmp/tasks-[ticketId].json`), đúng shape mà `ak tasks create-tickets` đọc (xem `scripts/ticket-writer.js`):
    ```json
    {
      "target": "backlog",
+     "parentTicket": { "mode": "create", "title": "...", "description": "..." },
      "tasks": [
        { "type": "coding", "title": "...", "description": "..." }
      ]
    }
    ```
+   `parentTicket` lấy nguyên từ kết quả Bước 6b (bỏ field này hoặc `{"mode": "none"}` nếu không gộp ticket cha).
 2. Chạy `ak tasks create-tickets <file> --json`.
 3. Đọc kết quả JSON trả về:
    - `{"error":"missing-write-credentials", "field": "...", "message": "..."}` → **đây không phải lỗi hệ thống** — hiển thị đúng `message` cho PM, hỏi PM nhập giá trị key ngay trong hội thoại (dùng luôn khung chat làm nơi PM "nhập & submit"), nhận giá trị → chạy `ak credentials set <field> "<giá trị PM vừa nhập>"` → chạy lại bước 2 (retry đúng 1 lần; nếu vẫn lỗi, báo PM key có thể sai/chưa đủ quyền, không tự thử lại vô hạn).
    - `{"error":"missing-project", ...}` → quay lại Bước 6 (chưa xác định được project).
-   - Thành công (`ok: true`) → mỗi task có `ticketId` + `url` riêng; task nào `ok: false` (lỗi phía Backlog/Jira, vd thiếu field) → báo rõ cho PM, các task khác đã tạo vẫn giữ nguyên (không rollback).
+   - `{"error":"parent-not-found", "message": "..."}` → ticket cha PM cung cấp ở Bước 6b (2) không tồn tại/không đọc được — báo PM, quay lại Bước 6b để nhập ID khác hoặc chọn phương án khác.
+   - `{"error":"parent-create-failed", "message": "..."}` → tạo ticket cha thất bại (thường do project chưa hỗ trợ phân cấp issue) — hiển thị nguyên lỗi, hỏi PM có muốn tạo lại không gắn ticket cha (`mode: "none"`) hay dừng lại.
+   - Thành công (`ok: true`) → mỗi task có `ticketId` + `url` riêng, có thêm `parent` (ticket cha vừa tạo/dùng, nếu có); task nào `ok: false` (lỗi phía Backlog/Jira, vd thiếu field) → báo rõ cho PM, các task khác đã tạo vẫn giữ nguyên (không rollback).
 
 ### 5.8 Bước 8 — Ghi ngược liên kết + đóng Gate
 
-1. Append vào cuối đúng entry gốc (Meetings-Log/QnA-Log/Confirmations-Log) 1 dòng:
+1. Append vào cuối đúng entry gốc (Meetings-Log/QnA-Log/Confirmations-Log) 1 dòng, kèm ticket cha nếu có:
    ```text
-   → Tasks created: TICKET-101 (coding), TICKET-102 (test)
+   → Tasks created: TICKET-100 (parent), TICKET-101 (coding), TICKET-102 (test)
    ```
    Việc sửa file này đi qua đúng branch đang dùng ở Gate 2 (không tạo MR riêng — gộp vào cùng thay đổi, hoặc nếu MR đã mở/merge thì tạo 1 commit nhỏ tiếp theo trên cùng branch/1 MR mới tuỳ trạng thái branch lúc đó).
 2. Hiển thị tổng kết:
    ```text
    ✅ GATE 3 DONE — Đã tạo N/N ticket trên [Backlog/Jira]:
+     - Ticket cha: TICKET-100 — <url>  (bỏ dòng này nếu không gộp ticket cha)
      - TICKET-101 (coding) — <url>
      - TICKET-102 (test) — <url>
    → Dev/QA chạy `ak use TICKET-XXX` trên từng ticket để bắt đầu Gate tương ứng (Coding/QA workflow hiện có).

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, 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.
+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, hoặc `ak gate 3 skip --ticket [ticket-id] --reason "..."` khi Bước 2 kết luận KHÔNG cần task.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relipa/ai-flow-kit",
-  "version": "0.2.0-beta.2",
+  "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

@@ -197,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) {
@@ -262,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 };
@@ -365,6 +401,6 @@ module.exports = {
   fetchBacklogTicket, fetchBacklogComment,
   fetchBacklogDocument, fetchBacklogDocumentComment, fetchBacklogWiki,
   fetchJiraTicket, fetchJiraComment,
-  fetchBacklogIssueTypes, fetchBacklogPriorities, createBacklogIssue,
-  createJiraIssue,
+  fetchBacklogIssueTypes, fetchBacklogPriorities, createBacklogIssue, getBacklogIssue,
+  createJiraIssue, getJiraIssue,
 };

package/scripts/ticket-writer.js

@@ -24,7 +24,9 @@ const {
   fetchBacklogIssueTypes,
   fetchBacklogPriorities,
   createBacklogIssue,
+  getBacklogIssue,
   createJiraIssue,
+  getJiraIssue,
 } = linkResolver;
 
 // Only these keys can be written via `ak credentials set` — dedicated adapter credentials
@@ -104,13 +106,23 @@ async function pickBacklogDefaults(domain, apiKeyRead, projectId) {
  *   "target": "backlog" | "jira",
  *   "projectId": "12345",     // optional — Backlog only, overrides BACKLOG_DEFAULT_PROJECT_ID
  *   "projectKey": "PROJ",     // optional — Jira only, overrides JIRA_DEFAULT_PROJECT_KEY
+ *   "parentTicket": {         // optional — ingest-data SKILL.md § 5.6b "Ticket cha"
+ *     "mode": "create" | "existing" | "none",
+ *     "title": "...",         // required when mode === "create"
+ *     "description": "...",  // optional when mode === "create"
+ *     "existingId": "..."    // required when mode === "existing" (Backlog key/id or Jira key)
+ *   },
  *   "tasks": [
- *     { "type": "spec|coding|test|other", "title": "...", "description": "..." }
+ *     { "type": "spec|system-requirement|impact-analysis|coding|test|execute-test|other", "title": "...", "description": "..." }
  *   ]
  * }
  *
  * `description` is expected to already be fully composed by the AI per the ticket template in
  * PM Workflow_v1.0.md §6.1 (Nội dung task + Nguồn tham chiếu) — this command posts it as-is.
+ *
+ * When `parentTicket.mode` is "create" or "existing", every task in `tasks` is created as a
+ * child of that parent (Backlog `parentIssueId` / Jira `parent`) — see link-resolver.js for the
+ * caveat that this depends on the target project supporting issue hierarchy/subtasks.
  */
 async function createTicketsCommand(inputFile, options = {}) {
   const emit = (obj) => {
@@ -119,6 +131,7 @@ async function createTicketsCommand(inputFile, options = {}) {
       console.log(chalk.red(`✗ ${obj.message || obj.error}`));
     } else {
       console.log(chalk.green(`✓ ${obj.results.filter(r => r.ok).length}/${obj.results.length} ticket(s) created on ${obj.target}.`));
+      if (obj.parent) console.log(`  ${chalk.cyan('↳ parent:')} ${obj.parent.ticketId}  ${chalk.gray(obj.parent.url)}`);
       for (const r of obj.results) {
         console.log(r.ok ? `  ${chalk.green('✓')} ${r.ticketId}  ${chalk.gray(r.title)}` : `  ${chalk.red('✗')} ${chalk.gray(r.title)} — ${r.error}`);
       }
@@ -173,6 +186,34 @@ async function createTicketsCommand(inputFile, options = {}) {
       return;
     }
 
+    const parentTicket = input.parentTicket || { mode: 'none' };
+    let parentRef = null;
+    if (parentTicket.mode === 'create') {
+      try {
+        const createdParent = await createBacklogIssue(write.domain, write.apiKeyWrite, {
+          projectId,
+          summary: parentTicket.title,
+          description: parentTicket.description || '',
+          issueTypeId: defaults.defaultIssueTypeId,
+          priorityId: defaults.defaultPriorityId,
+        });
+        parentRef = { ticketId: createdParent.ticketId, internalId: createdParent.internalId, url: createdParent.url };
+      } catch (err) {
+        emit({ ok: false, error: 'parent-create-failed', message: `Không tạo được ticket cha trên Backlog: ${err.message}` });
+        process.exitCode = 1;
+        return;
+      }
+    } else if (parentTicket.mode === 'existing') {
+      try {
+        const existing = await getBacklogIssue(write.domain, write.apiKeyRead, parentTicket.existingId);
+        parentRef = { ticketId: existing.issueKey, internalId: existing.id, url: `https://${write.domain}/view/${existing.issueKey}` };
+      } catch (err) {
+        emit({ ok: false, error: 'parent-not-found', message: `Không tìm thấy ticket cha "${parentTicket.existingId}" trên Backlog: ${err.message}` });
+        process.exitCode = 1;
+        return;
+      }
+    }
+
     const results = [];
     for (const task of tasks) {
       try {
@@ -182,13 +223,14 @@ async function createTicketsCommand(inputFile, options = {}) {
           description: task.description,
           issueTypeId: task.issueTypeId || defaults.defaultIssueTypeId,
           priorityId: task.priorityId || defaults.defaultPriorityId,
+          parentIssueId: parentRef ? parentRef.internalId : undefined,
         });
         results.push({ type: task.type, title: task.title, ok: true, ticketId: created.ticketId, url: created.url });
       } catch (err) {
         results.push({ type: task.type, title: task.title, ok: false, error: err.message });
       }
     }
-    emit({ ok: true, target, projectId, results });
+    emit({ ok: true, target, projectId, parent: parentRef, results });
     return;
   }
 
@@ -206,6 +248,32 @@ async function createTicketsCommand(inputFile, options = {}) {
     return;
   }
 
+  const parentTicket = input.parentTicket || { mode: 'none' };
+  let parentRef = null;
+  if (parentTicket.mode === 'create') {
+    try {
+      const createdParent = await createJiraIssue(write.domain, write.emailWrite, write.apiTokenWrite, {
+        projectKey,
+        summary: parentTicket.title,
+        description: parentTicket.description || '',
+      });
+      parentRef = { ticketId: createdParent.ticketId, url: createdParent.url };
+    } catch (err) {
+      emit({ ok: false, error: 'parent-create-failed', message: `Không tạo được ticket cha trên Jira: ${err.message}` });
+      process.exitCode = 1;
+      return;
+    }
+  } else if (parentTicket.mode === 'existing') {
+    try {
+      const existing = await getJiraIssue(write.domain, write.emailWrite, write.apiTokenWrite, parentTicket.existingId);
+      parentRef = { ticketId: existing.key, url: `https://${write.domain}/browse/${existing.key}` };
+    } catch (err) {
+      emit({ ok: false, error: 'parent-not-found', message: `Không tìm thấy ticket cha "${parentTicket.existingId}" trên Jira: ${err.message}` });
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   const results = [];
   for (const task of tasks) {
     try {
@@ -214,13 +282,14 @@ async function createTicketsCommand(inputFile, options = {}) {
         summary: task.title,
         description: task.description,
         issueTypeName: task.issueType || 'Task',
+        parentKey: parentRef ? parentRef.ticketId : undefined,
       });
       results.push({ type: task.type, title: task.title, ok: true, ticketId: created.ticketId, url: created.url });
     } catch (err) {
       results.push({ type: task.type, title: task.title, ok: false, error: err.message });
     }
   }
-  emit({ ok: true, target, projectKey, results });
+  emit({ ok: true, target, projectKey, parent: parentRef, results });
 }
 
 /**