spec-lite 1.4.6 → 1.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-lite",
-  "version": "1.4.6",
+  "version": "1.4.7",
   "description": "Spec-driven development kit for Claude Code",
   "type": "module",
   "bin": {

package/skills/ado-config/SKILL.md

@@ -53,16 +53,19 @@ options:
     description: "Cập nhật danh sách PE / SE / DE"
   - label: "Epic ticket"
     description: "Tạo mới hoặc thay Epic ticket đang được lưu"
+  - label: "Area / Iteration path"
+    description: "Cập nhật area_path và iteration_path mặc định cho ticket"
   - label: "Môi trường"
     description: "Cập nhật danh sách environments (dev / stag / prod)"
 ```
 
 Tuỳ theo lựa chọn:
-- **"Toàn bộ từ đầu"** → chạy Bước 2 → 3 → 4 → 5 → 6 → 7
-- **"Thông tin project"** → chỉ chạy Bước 2, bỏ qua Bước 3, 4, 5, nhảy thẳng đến Bước 6 → 7 (giữ nguyên `team`, `epic`, `environments` từ file cũ)
-- **"Team members"** → chỉ chạy Bước 3, bỏ qua Bước 2, 4, 5, nhảy thẳng đến Bước 6 → 7 (giữ nguyên `organization/project`, `epic`, `environments` từ file cũ)
-- **"Epic ticket"** → chỉ chạy Bước 4, bỏ qua Bước 2, 3, 5, nhảy thẳng đến Bước 6 → 7 (giữ nguyên `organization/project`, `team`, `environments` từ file cũ)
-- **"Môi trường"** → chỉ chạy Bước 5, bỏ qua Bước 2, 3, 4, nhảy thẳng đến Bước 6 → 7 (giữ nguyên tất cả từ file cũ)
+- **"Toàn bộ từ đầu"** → chạy Bước 2 → 3 → 4 → 5 → 6 → 7 → 8
+- **"Thông tin project"** → chỉ chạy Bước 2, bỏ qua Bước 3, 4, 5, 6, nhảy thẳng đến Bước 7 → 8 (giữ nguyên `team`, `epic`, `area_path/iteration_path`, `environments` từ file cũ)
+- **"Team members"** → chỉ chạy Bước 3, bỏ qua Bước 2, 4, 5, 6, nhảy thẳng đến Bước 7 → 8 (giữ nguyên `organization/project`, `epic`, `area_path/iteration_path`, `environments` từ file cũ)
+- **"Epic ticket"** → chỉ chạy Bước 4, bỏ qua Bước 2, 3, 5, 6, nhảy thẳng đến Bước 7 → 8 (giữ nguyên `organization/project`, `team`, `area_path/iteration_path`, `environments` từ file cũ)
+- **"Area / Iteration path"** → chỉ chạy Bước 5, bỏ qua Bước 2, 3, 4, 6, nhảy thẳng đến Bước 7 → 8 (giữ nguyên tất cả còn lại từ file cũ)
+- **"Môi trường"** → chỉ chạy Bước 6, bỏ qua Bước 2, 3, 4, 5, nhảy thẳng đến Bước 7 → 8 (giữ nguyên tất cả từ file cũ)
 
 ---
 
@@ -238,7 +241,41 @@ https://dev.azure.com/{organization}/{project_name}/_workitems/edit/{id}
 
 ---
 
-### Bước 5: Cấu hình môi trường
+### Bước 5: Cấu hình Area & Iteration Path
+
+Area Path và Iteration Path mặc định sẽ được gán cho mọi Feature/User Story khi `/ado-create` tạo ticket. Cả hai đều **tùy chọn** — nếu bỏ trống, ADO dùng giá trị mặc định của team.
+
+Hỏi user bằng `AskUserQuestion`:
+
+```
+question: "Cấu hình Area / Iteration path mặc định cho ticket?"
+options:
+  - label: "Nhập area & iteration path"
+    description: "Gán area_path và iteration_path mặc định cho mọi ticket tạo qua /ado-create"
+  - label: "Bỏ qua"
+    description: "Không set — ADO dùng giá trị mặc định của team"
+```
+
+Nếu user chọn **"Nhập area & iteration path"** → hỏi lần lượt (cho phép Enter trống để bỏ từng field):
+
+```
+Area Path (ví dụ: Tickets\Clients\C-GAL\P-GCC):
+> Tickets\Clients\C-GAL\P-GCC
+
+Iteration Path (ví dụ: Tickets\Weekly Sprint):
+> Tickets\Weekly Sprint
+```
+
+Lưu ý khi thu thập:
+- Path dùng dấu backslash `\` phân cách như trên ADO. Chấp nhận cả khi user paste có khoảng trắng ở đầu/cuối → trim.
+- Nếu user nhập area path nhưng không chắc đúng → vẫn lưu nguyên văn, không tự validate qua MCP (tránh fail khi node chưa tồn tại). Validation thực tế sẽ xảy ra lúc `/ado-create` tạo ticket.
+- Field nào để trống → bỏ key tương ứng trong YAML, không ghi `area_path: null`.
+
+Nếu user chọn **"Bỏ qua"** → không thêm `area_path`/`iteration_path` vào config.
+
+---
+
+### Bước 6: Cấu hình môi trường
 
 **Bắt buộc** hỏi user bằng `AskUserQuestion` — không cho phép bỏ qua:
 
@@ -265,7 +302,7 @@ Nếu user chọn "Other" (nhập tay) → parse chuỗi nhập vào (phân các
 
 ---
 
-### Bước 6: Preview và xác nhận
+### Bước 7: Preview và xác nhận
 
 Hiển thị preview YAML sẽ được ghi — **chưa ghi file**:
 
@@ -287,6 +324,9 @@ team:
   DE:
     - d@atstechnology.vn
 
+area_path: 'Tickets\Clients\C-GAL\P-GCC'
+iteration_path: 'Tickets\Weekly Sprint'
+
 epic:
   id: 42
   title: "[GAL-GCC] Spec Lite Kit"
@@ -304,11 +344,13 @@ Nếu user yêu cầu chỉnh sửa → cập nhật preview → hỏi lại.
 
 Nếu user bỏ qua bước Epic (không muốn cấu hình ngay) → bỏ qua key `epic` trong YAML, không ghi `epic: null`.
 
-**Bước 5 (môi trường) là bắt buộc** — không cho phép bỏ qua. Nếu user chưa chọn, nhắc lại trước khi tiếp tục.
+Nếu user bỏ qua Area/Iteration (Bước 5) → bỏ qua key `area_path`/`iteration_path` tương ứng, không ghi giá trị `null`.
+
+**Bước 6 (môi trường) là bắt buộc** — không cho phép bỏ qua. Nếu user chưa chọn, nhắc lại trước khi tiếp tục.
 
 ---
 
-### Bước 7: Ghi file
+### Bước 8: Ghi file
 
 Ghi nội dung đã confirm vào `.claude/ado.yaml`.
 
@@ -345,5 +387,6 @@ Trước khi ghi file, kiểm tra:
 - [ ] `team.PE` có ít nhất 1 email — không được để trống
 - [ ] SE và DE có thể là array rỗng `[]`
 - [ ] Nếu có Epic: `epic.id` là số nguyên, `epic.title` có prefix `[{project_code}]`, `epic.url` là full URL dạng `https://dev.azure.com/{org}/{project_name}/_workitems/edit/{id}`
+- [ ] Nếu có `area_path` / `iteration_path`: là chuỗi đã trim, giữ nguyên dấu `\` (dùng YAML single-quote để tránh escape); bỏ qua key nếu user không nhập — không ghi `null`
 - [ ] `environments` là array ít nhất 1 phần tử (bắt buộc), mỗi phần tử là lowercase string không có khoảng trắng, luôn có `prod` ở cuối
 - [ ] User đã confirm preview trước khi ghi file

package/skills/ado-create/SKILL.md

@@ -14,6 +14,8 @@ description: Tạo Feature và User Story tickets trên ADO từ spec.md của m
 - `.claude/ado.yaml` phải tồn tại và có `epic.id` (chạy `/ado-config` nếu chưa có)
 - `frd.md` tương ứng phải tồn tại trong `.specs/main/features/` cho mỗi feature
 
+**Area / Iteration (tùy chọn):** Nếu `.claude/ado.yaml` có `area_path` và/hoặc `iteration_path`, mọi ticket (Feature + User Story) tạo ở Bước 5 và Bước 6 phải set `areaPath` / `iterationPath` tương ứng. Nếu không khai báo → để ADO dùng giá trị mặc định của team.
+
 ---
 
 ## Process
@@ -131,6 +133,8 @@ Gọi `mcp__azure-devops__wit_create_work_item` với:
 - `title`: `[{project_code}] [{feature_id}] {feature_name}` — ví dụ: `[SDLC-TEST] [F-001] Đăng ký / Đăng nhập`
 - `description`: toàn bộ nội dung `frd.md` (giữ nguyên format Markdown)
 - `assignedTo`: ADO identity ID của current user (nếu resolve thành công)
+- `areaPath`: giá trị `area_path` từ ado.yaml (nếu có)
+- `iterationPath`: giá trị `iteration_path` từ ado.yaml (nếu có)
 
 Sau khi tạo thành công → **ngay lập tức** link parent. Ưu tiên dùng `mcp__azure-devops__wit_add_child_work_items` (parent = Epic ID, child = Feature ticket ID). Nếu tool này không khả dụng, fallback sang `mcp__azure-devops__wit_work_items_link` với:
 - `sourceId`: Feature ticket ID vừa tạo
@@ -186,6 +190,8 @@ Gọi `mcp__azure-devops__wit_create_work_item` với:
 - `title`: `[{project_code}] [{feature_name}] - {US-code} — {story_title}` — ví dụ: `[SDLC-TEST] [Đăng ký / Đăng nhập] - US-F001-001 — Đăng ký`
 - `description`: description đã build ở 6.2
 - `assignedTo`: ADO identity ID của current user
+- `areaPath`: giá trị `area_path` từ ado.yaml (nếu có)
+- `iterationPath`: giá trị `iteration_path` từ ado.yaml (nếu có)
 
 Sau khi tạo thành công → **ngay lập tức** link parent. Ưu tiên dùng `mcp__azure-devops__wit_add_child_work_items` (parent = Feature ticket ID, child = User Story ticket ID). Nếu không khả dụng, fallback sang `mcp__azure-devops__wit_work_items_link` với:
 - `sourceId`: User Story ticket ID vừa tạo

package/skills/spec-frd/SKILL.md

@@ -18,7 +18,7 @@ Skill này là cặp greenfield đối xứng với `/spec-brownfield-feature` (
 2. **CREATE-only** — frd.md đã tồn tại → DỪNG, redirect `/spec-new` để phân tích delta + cascade + downstream (tech/test) (Bước 1c).
 
 **Phạm vi hẹp — chủ yếu frd.md:**
-- ✅ Author frd.md (7 sections) cho **một** feature **chưa có frd**.
+- ✅ Author frd.md (7 core sections + `Open Questions` tùy chọn) cho **một** feature **chưa có frd**.
 - ✅ *Reference* component frd phụ thuộc (Components Used) + ghi component cần-nhưng-chưa-có như **candidate**.
 - ✅ Nếu feature mục tiêu là feature mới chưa có trong Index → **register một row vào `prd.md > Features`** (side-effect hợp lệ lên prd).
 - ✅ **Cascade vocabulary lên `domain.md`** (Bước 4b — pha *mô tả hệ thống*/WHAT): glossary term + **định nghĩa entity đầy đủ** (attributes). `Owner` của entity để `TBD` cho `/spec-sad` điền ở pha *thiết kế hệ thống* (HOW). BA duyệt trước khi ghi. Đây là điểm khác với phiên bản trước (`/spec-frd` từng không đụng domain) — vocabulary sinh ra ở feature-authoring time nên seed luôn, thay vì để domain rỗng tới integration đầu tiên.
@@ -171,6 +171,8 @@ Hỏi tuần tự, từng phần — không hỏi tất cả cùng lúc. Nếu B
 
 Câu trả lời vague → hỏi lại để làm rõ (ngưỡng đo được, field cụ thể, nhánh xử lý).
 
+**Open Questions — gom trong lúc interview.** Điểm nào BA chưa chốt được ngay (chờ stakeholder, phụ thuộc quyết định khác, ngưỡng/nhánh chưa rõ) → KHÔNG đoán bừa vào AC/VR. Ghi lại thành một mục trong `## Open Questions` của draft (kèm ai trả lời / khi nào), rồi tiếp tục các phần còn lại. Section này gom cả component candidate (Bước 4) lẫn câu hỏi clarify từ interview; rỗng thì xóa khi save.
+
 ---
 
 ### Bước 4: Xử lý component (mức reference + candidate)
@@ -225,6 +227,7 @@ Dùng `.claude/templates/main/feature/frd-template.md` làm skeleton, điền n
 
 Hiển thị **toàn bộ draft** cho user — chưa ghi file. Kèm:
 - danh sách component candidate (nếu có) và VR còn `TBD`;
+- **Open Questions** còn mở (câu hỏi clarify + component candidate) để BA xác nhận hoặc giải quyết trước khi save;
 - **danh sách domain vocabulary đề xuất** (Bước 4b): glossary term mới + định nghĩa shared entity (`Owner: TBD`), để BA duyệt trước khi cascade lên `domain.md`.
 
 #### Verification Rules — quy ước sinh
@@ -344,6 +347,7 @@ Bước tiếp theo:
 - frd dùng từ không đo được trong AC ("hoạt động đúng", "nhanh", "đẹp")
 - User Stories không có persona rõ hoặc không có AC
 - Verification Rules tự điền mà chưa hỏi BA
+- Đoán bừa vào AC/VR thay vì ghi điểm chưa chốt vào Open Questions
 - Tạo crd.md/cdd.md (vượt phạm vi — đó là integration time)
 - Component candidate không được surface cho architect
 - **Update frd đã tồn tại** thay vì redirect `/spec-new` (vi phạm CREATE-only)
@@ -355,7 +359,7 @@ Bước tiếp theo:
 - [ ] **Single-feature gate**: nguồn liên quan đúng 1 feature; nếu >1 đã DỪNG và mô tả rõ lý do tách + redirect `/spec-prd`
 - [ ] **Create-only gate**: frd.md của feature mục tiêu CHƯA tồn tại; nếu đã có đã redirect `/spec-new`
 - [ ] Feature mục tiêu có trong Index, HOẶC feature mới đơn lẻ đã được user đồng ý register (Bước 1b)
-- [ ] frd.md có đủ 7 sections (luôn create mới)
+- [ ] frd.md có đủ 7 core sections (luôn create mới); `Open Questions` chứa câu hỏi clarify + component candidate còn mở, hoặc đã xóa nếu rỗng
 - [ ] Mỗi User Story có persona + priority + ít nhất 1 AC Given/When/Then
 - [ ] Feature AC dùng ID `FAC-F{NNN}-{seq}` (counter độc lập với `AC-F{NNN}`), Then đo được
 - [ ] Verification Rules đã confirm với BA (không tự assert); không chứa regex/code/error message; semantic type

package/skills-overview.md

@@ -550,6 +550,7 @@ Tạo hoặc cập nhật `.claude/ado.yaml` — file config ADO dùng chung cho
 - Thông tin project
 - Team members
 - Epic ticket
+- Area / Iteration path
 - Môi trường
 
 **Bước 2 — Project:**
@@ -561,7 +562,9 @@ Tạo hoặc cập nhật `.claude/ado.yaml` — file config ADO dùng chung cho
 
 **Bước 4 — Epic Ticket:** Tạo Epic mới qua MCP (title được prefix `[{project_code}]`, assignee là PE đầu tiên) hoặc nhập ID ticket có sẵn (validate qua MCP: phải là type `Epic`). Lưu `id`, `title`, `url` vào config.
 
-**Bước 5 — Environments:** Collect danh sách môi trường (dev / stag / prod).
+**Bước 5 — Area / Iteration Path:** (tùy chọn) Collect `area_path` và `iteration_path` mặc định cho ticket. Bỏ qua nếu user không nhập → ADO dùng giá trị mặc định của team.
+
+**Bước 6 — Environments:** Collect danh sách môi trường (dev / stag / prod).
 
 **Cuối:** Ghi `.claude/ado.yaml`, đảm bảo file không bị ignore bởi `.gitignore` (thêm `!.claude/ado.yaml` nếu `.claude/` đang bị ignore).
 
@@ -581,7 +584,7 @@ Tạo hoặc cập nhật `.claude/ado.yaml` — file config ADO dùng chung cho
 
 **Bước 4 — Preview:** Hiển thị kế hoạch đầy đủ (Feature và User Story sẽ tạo, skip list) trước khi tạo bất kỳ ticket nào. Chờ user confirm.
 
-**Bước 5-6 — Tạo tickets:**
+**Bước 5-6 — Tạo tickets:** (set `areaPath`/`iterationPath` từ `ado.yaml` nếu có)
 - Feature ticket: type `Feature`, title `[{project_code}] [{feature_id}] {feature_name}`, description từ `frd.md`. Link parent → Epic ngay sau khi tạo.
 - User Story ticket: type `User Story`, title `[{project_code}] [{feature_name}] - {US-code} — {story_title}`, description gồm câu story + ACs. Link parent → Feature ngay sau khi tạo.
 - Nếu link parent fail → retry 1 lần → nếu vẫn fail: đánh dấu `orphan` (KHÔNG xóa ticket), báo cáo cuối.

package/templates/main/feature/frd-template.md

@@ -155,6 +155,13 @@ Tham chiếu đến `.specs/main/component/{C-XXX}-...`.
 | --- | --- |
 | `{C-XXX}-{component-name}` | {component này phục vụ cái gì cho feature này} |
 
+## Open Questions
+
+<!-- Các câu hỏi cần làm rõ trong interview / với stakeholder trước khi proceed.
+     Cũng dùng để note component candidate chưa carve (xem skills/spec-frd). Xóa section nếu không còn câu hỏi nào. -->
+
+- [ ] {câu hỏi cần clarify} — {ai trả lời / khi nào}
+
 ## Change History
 
 Append-only log của các thay đổi cascade lên artifact này. Quy ước xem `conventions.md` §5.5.