@edupia-tutor/spec-driven-docs 0.14.3 → 0.14.5

package/core/templates/prd.template.md

@@ -46,7 +46,7 @@
 | **Domain**    | {domain}                                 |
 | **Created**   | {date}                                   |
 | **Updated**   | {date}                                   |
-| **Jira Ticket** | [{TICKET}-{N}]({ticket_url})            |
+| **Ticket**    | {TICKET}-{N}{ — nếu PO có link tracker thật, thêm bên cạnh: `{TICKET}-{N} ([Jira]({tracker_url}))`} |
 | **API Source** | *(để trống nếu greenfield — chỉ điền `existing` khi PRD bọc một API đã chạy production)* |
 
 ---
@@ -76,13 +76,21 @@
 **Out of Scope** *(chỉ thêm khi có ranh giới cần nói rõ)*
 - {hạng mục ngoài phạm vi + lý do / chủ sở hữu}
 
+## c. Phụ thuộc liên service *(mức nghiệp vụ — KHÔNG mô tả API/event/kỹ thuật)*
+
+> Kế thừa từ Product Definition Phase 1 ("Phụ thuộc liên service"). Nếu contract do đối tác phát triển song song (xem `API Source`), ghi phụ thuộc partner vào đây.
+
+- {Cần {dữ liệu/năng lực} từ {feature/team/partner} — vì {lý do nghiệp vụ}} — hoặc "Không có"
+
 ---
 
 # 2. Acceptance Criteria
 
-**AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.}
+> Mỗi AC kế thừa liên kết "Bắt nguồn từ BR" của Product Definition (Phase 6), remap sang BR ID của PRD. Vì BR ID đã chứa số UC nên ref BR truy ngược được tới đúng UC.
 
-**AC2:** {…}
+**AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
+
+**AC2:** {…} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
 
 ---
 
@@ -100,6 +108,8 @@
 **Post-condition:**
 - {kết quả sau 1}
 
+**AC liên quan:** AC{x}, AC{y}  *(các AC mà UC này thoả — phải đúng bằng tập AC có ref BR trỏ về UC này ở §2)*
+
 **Business Rule**
 
 | ID | Business Rule | Business Logic |

package/core/templates/product-definition.template.md

@@ -100,6 +100,13 @@
 | 1    | {hành động}     | {trạng thái/kết quả nghiệp vụ} | {ghi chú}  |
 | 2    | {hành động}     | {trạng thái/kết quả nghiệp vụ} | {ghi chú}  |
 
+### Màn hình & thành phần chính
+> Mức nghiệp vụ — nguồn cho Wireframe PRD (§4b) và độ phủ BDD (C.1). KHÔNG pixel/layout/màu.
+
+| Màn hình | Thành phần chính | Hành động → kết quả nghiệp vụ |
+|----------|------------------|-------------------------------|
+| {màn 1}  | {thành phần}     | {hành động → kết quả}         |
+
 ### Điểm ra (Exit Point)
 {Kết quả cuối khi flow hoàn thành}
 
@@ -176,6 +183,6 @@
 <!--
   NEXT STEPS:
   Khi Product Definition hoàn tất (Status: completed), chạy:
-  /generate-prd {path-to-this-file} --jira {TICKET-ID}
+  /generate-prd {path-to-this-file}
   để sinh PRD từ Product Definition này.
 -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edupia-tutor/spec-driven-docs",
-  "version": "0.14.3",
+  "version": "0.14.5",
   "description": "AI-First Spec-Driven Development workflow framework for Claude Code",
   "bin": {
     "spec-driven-docs": "./bin/index.js"

package/skills/code/SKILL.md

@@ -28,6 +28,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/skills/design-spec/SKILL.md

@@ -31,6 +31,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/skills/prd/SKILL.md

@@ -28,6 +28,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 
@@ -186,7 +187,7 @@ Template (cấu trúc đầu ra — single-source từ `templates/prd.template.m
 | **Domain**    | {domain}                                 |
 | **Created**   | {date}                                   |
 | **Updated**   | {date}                                   |
-| **Jira Ticket** | [{TICKET}-{N}]({ticket_url})            |
+| **Ticket**    | {TICKET}-{N}{ — nếu PO có link tracker thật, thêm bên cạnh: `{TICKET}-{N} ([Jira]({tracker_url}))`} |
 | **API Source** | *(để trống nếu greenfield — chỉ điền `existing` khi PRD bọc một API đã chạy production)* |
 
 ---
@@ -216,13 +217,21 @@ Template (cấu trúc đầu ra — single-source từ `templates/prd.template.m
 **Out of Scope** *(chỉ thêm khi có ranh giới cần nói rõ)*
 - {hạng mục ngoài phạm vi + lý do / chủ sở hữu}
 
+## c. Phụ thuộc liên service *(mức nghiệp vụ — KHÔNG mô tả API/event/kỹ thuật)*
+
+> Kế thừa từ Product Definition Phase 1 ("Phụ thuộc liên service"). Nếu contract do đối tác phát triển song song (xem `API Source`), ghi phụ thuộc partner vào đây.
+
+- {Cần {dữ liệu/năng lực} từ {feature/team/partner} — vì {lý do nghiệp vụ}} — hoặc "Không có"
+
 ---
 
 # 2. Acceptance Criteria
 
-**AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.}
+> Mỗi AC kế thừa liên kết "Bắt nguồn từ BR" của Product Definition (Phase 6), remap sang BR ID của PRD. Vì BR ID đã chứa số UC nên ref BR truy ngược được tới đúng UC.
 
-**AC2:** {…}
+**AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
+
+**AC2:** {…} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
 
 ---
 
@@ -240,6 +249,8 @@ Template (cấu trúc đầu ra — single-source từ `templates/prd.template.m
 **Post-condition:**
 - {kết quả sau 1}
 
+**AC liên quan:** AC{x}, AC{y}  *(các AC mà UC này thoả — phải đúng bằng tập AC có ref BR trỏ về UC này ở §2)*
+
 **Business Rule**
 
 | ID | Business Rule | Business Logic |

package/skills/spec/SKILL.md

@@ -28,6 +28,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/skills/test/SKILL.md

@@ -28,6 +28,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/steps/business-language.md

@@ -0,0 +1,36 @@
+# Business Language Guard — chặn thuật ngữ kỹ thuật rò vào tài liệu nghiệp vụ
+
+Tài liệu nghiệp vụ (PRD, product-definition) mô tả **WHAT** — chỉ ngôn ngữ nghiệp vụ. Guard này chạy **mỗi khi viết hoặc sửa** prose (gen mới, áp fix `--resume`, hiệu chỉnh): **quét và xử lý** các thuật ngữ kỹ thuật/UI phổ thông bên dưới **trước khi ghi**.
+
+> Guard này là **baseline framework**, chạy **song song** với Banned Terms của `business-dictionary.md` (cơ chế dictionary giữ nguyên; project vẫn bổ sung term đặc thù vào đó). Khi cả hai cùng áp, ưu tiên bản chuẩn của dictionary nếu có.
+
+## Bản đồ xử lý (3 nhóm)
+
+**Nhóm 1 — Tương tác/triển khai → DIỄN ĐẠT LẠI sang nghiệp vụ (giữ nguyên nghĩa):**
+
+| Kỹ thuật/UI | Cách nói nghiệp vụ |
+|---|---|
+| re-render / render lại / reload / refresh (màn) | "hiển thị lại {tên màn}" |
+| timeout | "quá thời gian chờ" |
+| lỗi mạng / network error | "lỗi kết nối" |
+| UI / giao diện (khi chỉ một màn) | "màn" / "màn hình" |
+| click / tap | "bấm" / "chọn" |
+| popup / modal (nếu chỉ là khái niệm hiển thị) | "hộp thoại" / "thông báo" |
+| disable / enable (nút) | "khoá" / "mở" thao tác |
+| redirect / navigate | "chuyển tới {màn}" |
+
+**Nhóm 2 — Visual thuần → CHUYỂN Design Spec (bỏ khỏi PRD, ghi nhận lại):**
+`spinner`, `loading indicator`, `animation`, `fade/slide`, màu sắc, font, layout pixel, micro-interaction → *"Chi tiết visual này thuộc Design Spec — ghi nhận để tạo Design Spec sau."*
+
+**Nhóm 3 — Backend/contract thuần → BỎ khỏi PRD (thuộc Tech Docs):**
+`API`, `endpoint`, `token/JWT`, `HTTP status`, tên class/bảng/cột DB, query, payload, header.
+*(Ngoại lệ DUY NHẤT: Appendix "Existing API Contract" khi `API Source: existing` — xem Platform Strategy.)*
+
+## Quy tắc áp dụng
+- Quét toàn bộ text sắp ghi (User Story, AC, BR, Business Logic, Scope, Edge Cases, Assumptions…).
+- Nhóm 1 → thay tại chỗ, giữ nguyên nghĩa nghiệp vụ. **Đồng bộ cách diễn đạt** với chỗ đã có sẵn trong cùng tài liệu (vd nếu "quá thời gian chờ" đã dùng ở một BR → dùng nhất quán ở mọi nơi).
+- Nhóm 2 → gỡ khỏi prose nghiệp vụ + nhắc chuyển Design Spec.
+- Nhóm 3 → gỡ khỏi PRD (trừ ngoại lệ brownfield).
+- Nếu term không có trong bản đồ nhưng rõ ràng là tên kỹ thuật/triển khai → vẫn diễn đạt lại theo tinh thần Nhóm 1, đừng để lọt.
+
+**Checklist (dùng ở Quality Checklist của lệnh):** 0 thuật ngữ kỹ thuật/UI (re-render, UI, timeout, spinner, API/endpoint/token…) trong prose nghiệp vụ — đã diễn đạt lại (Nhóm 1) / chuyển Design Spec (Nhóm 2) / bỏ về Tech Docs (Nhóm 3).

package/steps/gate.md

@@ -13,6 +13,7 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
    - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
    - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
+   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
    - Đi thẳng tới phần logic riêng của lệnh.
 3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
 

package/steps/review-fanout.md

@@ -6,10 +6,12 @@ dừng ở mức "đủ" findings, nên mỗi vòng review sau lại lòi ra v
 fan out song song theo các chiều review, rồi lặp một critic độ-đầy-đủ cho tới khi một
 vòng không sinh thêm gì mới, *trước khi* ghi file findings.
 
-Lệnh gọi cung cấp hai thứ:
+Lệnh gọi cung cấp hai thứ bắt buộc + hai tuỳ chọn:
 - **DIMENSIONS** — danh sách các chiều review để fan out
   (`/refine-prd` → 4 lăng kính; `/review-context` → các P-check hoặc B-check).
 - **FINDINGS SCHEMA** — dạng YAML mà mỗi finding phải theo (định nghĩa trong lệnh).
+- **GRANULARITY** *(tuỳ chọn, mặc định `auto`)* — `auto`: chọn độ mịn fan-out theo bảng ngưỡng kích thước ở Phase 1 (hành vi cũ). `per-uc`: **LUÔN** fan-out theo từng UC, **bỏ qua ngưỡng** — dùng cho review cần độ đầy đủ cao (`/refine-prd` truyền cái này để lần đầu đã quét sâu). Lệnh không truyền → `auto` → hành vi không đổi.
+- **CHANGED_SCOPE** *(tuỳ chọn)* — danh sách UC/section đã thay đổi (review **delta**). Nếu được truyền, Phase 1 chỉ fan-out trên các phạm vi này + PRD-global; Phase 2 critic vẫn quét **toàn doc** làm lưới an toàn. Không truyền → quét toàn bộ như thường.
 
 > **Bỏ qua ở chế độ sub-agent:** Nếu Gate Bước 0 đã set `_agent_mode: true`, toàn bộ
 > quy trình này bị **bỏ qua** — orchestrator đã chạy sẵn một dimension/UC cho mỗi
@@ -21,8 +23,11 @@ Lệnh gọi cung cấp hai thứ:
 
 **Bao nhiêu sub-agent:** *số lượng* agent không phải là đòn bẩy độ đầy đủ — bề rộng được
 cố định bởi taxonomy DIMENSION (thêm agent vào cùng một dimension chỉ tìm lại cùng vấn đề),
-còn *độ sâu* thuộc về vòng lặp critic ở Phase 2. Chọn **độ mịn fan-out**
-theo kích thước target, tái dùng ngưỡng của `steps/spawn-agent.md`:
+còn *độ sâu* thuộc về vòng lặp critic ở Phase 2.
+
+**Nếu `GRANULARITY = per-uc`:** **bỏ qua bảng ngưỡng dưới đây**, luôn dùng độ mịn **DIMENSION × phạm vi UC** (kể cả PRD nhỏ) — đảm bảo quét sâu, không bỏ sót ngay lần đầu. (Cái giá: nhiều agent hơn cho PRD nhỏ — chấp nhận để lần đầu đầy đủ.)
+
+**Nếu `GRANULARITY = auto`** (mặc định): chọn **độ mịn fan-out** theo kích thước target, tái dùng ngưỡng của `steps/spawn-agent.md`:
 
 | Kích thước target | Độ mịn | Số agent |
 |-------------|-------------|-------------|
@@ -45,6 +50,7 @@ UC duy nhất — chính là điều ngăn bỏ sót trên các PRD lớn.
 agent). Giới hạn mỗi wave ở **`AGENT_CAP = 12`** agent và gom batch các phạm vi UC cho vừa:
 
 1. Dựng danh sách phạm vi = `[UC1, UC2, …, UCn, PRD-global]` (độ dài `UCs + 1`).
+   - **Nếu `CHANGED_SCOPE` được truyền (review delta):** danh sách phạm vi = `[các UC trong CHANGED_SCOPE] + [PRD-global]` (chỉ các UC đã đổi + global), KHÔNG phải tất cả UC. Số agent tụt theo đó.
 2. Tính số-phạm-vi-mỗi-bucket: `groups = max(1, floor(AGENT_CAP / dimensions))`.
    - Nếu `groups ≥ UCs + 1` → không cần batch, chạy một agent cho mỗi `DIMENSION × scope`.
    - Else chia danh sách phạm vi thành `groups` bucket liền kề kích thước xấp xỉ bằng nhau
@@ -86,10 +92,20 @@ Gom mảng findings của mọi sub-agent vào một danh sách hợp nhất `AL
 Đây là bước chống đập-chuột-chũi. Lặp cho tới khi **hai vòng liên tiếp thêm 0 finding
 mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
 
+> **Lưu ý delta:** kể cả khi `CHANGED_SCOPE` giới hạn Phase 1 vào các UC đã đổi, completeness-critic ở Phase 2 **vẫn đọc TOÀN bộ doc** — đây là lưới an toàn bắt các vấn đề mà một fix ở UC đã đổi có thể làm lộ ra ở chỗ khác.
+
 1. Spawn một sub-agent **completeness-critic** bằng Agent tool. Cho nó:
    - toàn bộ target file (`{target_file}`),
-   - danh sách `ALL_FINDINGS` hiện tại (để nó biết những gì đã được ghi nhận),
-   - cùng context gọn đó.
+   - danh sách findings đã ghi nhận dưới dạng **slim JSON** — chỉ 3 fields cốt lõi
+     đủ để critic nhận ra trùng lặp (không cần `quote`, `suggestion`, `auto_fixable`, `severity`):
+     ```json
+     [
+       { "uc_id": "...", "section": "...", "finding": "..." },
+       ...
+     ]
+     ```
+     Nếu `ALL_FINDINGS` vượt 60 items, rút gọn `finding` xuống còn 80 ký tự đầu mỗi item.
+   - cùng slim context (banned terms, canonical entities, layer order, domains).
    Prompt nó:
    ```
    Here is a document and a list of issues already found. Read the WHOLE document.

package/templates/prd.template.md

@@ -46,7 +46,7 @@
 | **Domain**    | {domain}                                 |
 | **Created**   | {date}                                   |
 | **Updated**   | {date}                                   |
-| **Jira Ticket** | [{TICKET}-{N}]({ticket_url})            |
+| **Ticket**    | {TICKET}-{N}{ — nếu PO có link tracker thật, thêm bên cạnh: `{TICKET}-{N} ([Jira]({tracker_url}))`} |
 | **API Source** | *(để trống nếu greenfield — chỉ điền `existing` khi PRD bọc một API đã chạy production)* |
 
 ---
@@ -76,13 +76,21 @@
 **Out of Scope** *(chỉ thêm khi có ranh giới cần nói rõ)*
 - {hạng mục ngoài phạm vi + lý do / chủ sở hữu}
 
+## c. Phụ thuộc liên service *(mức nghiệp vụ — KHÔNG mô tả API/event/kỹ thuật)*
+
+> Kế thừa từ Product Definition Phase 1 ("Phụ thuộc liên service"). Nếu contract do đối tác phát triển song song (xem `API Source`), ghi phụ thuộc partner vào đây.
+
+- {Cần {dữ liệu/năng lực} từ {feature/team/partner} — vì {lý do nghiệp vụ}} — hoặc "Không có"
+
 ---
 
 # 2. Acceptance Criteria
 
-**AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.}
+> Mỗi AC kế thừa liên kết "Bắt nguồn từ BR" của Product Definition (Phase 6), remap sang BR ID của PRD. Vì BR ID đã chứa số UC nên ref BR truy ngược được tới đúng UC.
 
-**AC2:** {…}
+**AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
+
+**AC2:** {…} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
 
 ---
 
@@ -100,6 +108,8 @@
 **Post-condition:**
 - {kết quả sau 1}
 
+**AC liên quan:** AC{x}, AC{y}  *(các AC mà UC này thoả — phải đúng bằng tập AC có ref BR trỏ về UC này ở §2)*
+
 **Business Rule**
 
 | ID | Business Rule | Business Logic |

package/templates/product-definition.template.md

@@ -100,6 +100,13 @@
 | 1    | {hành động}     | {trạng thái/kết quả nghiệp vụ} | {ghi chú}  |
 | 2    | {hành động}     | {trạng thái/kết quả nghiệp vụ} | {ghi chú}  |
 
+### Màn hình & thành phần chính
+> Mức nghiệp vụ — nguồn cho Wireframe PRD (§4b) và độ phủ BDD (C.1). KHÔNG pixel/layout/màu.
+
+| Màn hình | Thành phần chính | Hành động → kết quả nghiệp vụ |
+|----------|------------------|-------------------------------|
+| {màn 1}  | {thành phần}     | {hành động → kết quả}         |
+
 ### Điểm ra (Exit Point)
 {Kết quả cuối khi flow hoàn thành}
 
@@ -176,6 +183,6 @@
 <!--
   NEXT STEPS:
   Khi Product Definition hoàn tất (Status: completed), chạy:
-  /generate-prd {path-to-this-file} --jira {TICKET-ID}
+  /generate-prd {path-to-this-file}
   để sinh PRD từ Product Definition này.
 -->