@educa-corp/sdd-framework 0.6.0 → 0.7.1

package/commands/extend-prd.tmpl

@@ -1,273 +0,0 @@
-# /extend-prd — Thêm yêu cầu mới vào PRD đã duyệt
-
-> **Ranh giới với `/refine-prd` — đọc trước khi chọn lệnh:**
->
-> | Lệnh | Câu hỏi nó trả lời | Nguồn đầu vào |
-> |---|---|---|
-> | `/refine-prd` | *"PRD hiện tại có **vấn đề** gì?"* | 3 lăng kính review soi nội dung ĐANG CÓ |
-> | **`/extend-prd`** | *"PRD hiện tại **thiếu** cái gì mới?"* | PO + hòm thư `prd-change-requests/` |
->
-> `/refine-prd` **không** thêm được UC/AC/BR mới — nó tự cấm ở Resume Mode Phase 2 (*"không thay đổi
-> bất kỳ section nào không được tham chiếu bởi một finding được chấp nhận"*), và findings của nó sinh
-> từ việc soi PRD hiện có nên **không có đường nào để một yêu cầu MỚI đi vào**.
->
-> **Vì sao là lệnh riêng, không phải `/generate-prd --extend`:** hai chế độ ngược nhau về thao tác ghi
-> — `/generate-prd` **Write cả file**, lệnh này **chỉ Edit add-only**. Trộn vào một `.tmpl` chính là
-> hình dạng của G9 (một file, hai hành vi, người đọc chọn nhầm).
-
-## Gate
-
-*Checkpoint: **chặn CỨNG** — sửa PRD đã DUYỆT. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
-
-{{include:steps/gate.md}}
-
-*Lưu ý: Với lệnh này, target ở Bước 1 là **file PRD đã tồn tại** `{TICKET-ID}-{prd-slug}.md` (file `.md` duy nhất ở gốc feature folder). Nếu `$ARGUMENTS` rỗng → liệt kê `{specs_dir}/*/*/*.md` và hỏi. **Không tìm thấy file PRD → DỪNG** và chỉ sang `/generate-prd` (feature mới thì đi từ discovery, không phải từ đây).*
-
-## Context
-{{include:steps/context-loader.md}}
-
----
-
-## Ngôn ngữ nghiệp vụ *(áp cho mọi text mới: UC, AC, BR, Business Logic, Scope)*
-{{include:steps/business-language.md}}
-
----
-
-## Bước 1 — Nạp trạng thái PRD hiện có
-
-Đọc target PRD, trích và lưu:
-
-| Giá trị | Nguồn | Dùng để |
-|---|---|---|
-| `current_version` | Metadata `\| **Version** \|` | tính version mới ở Bước 6 |
-| `current_status` | Metadata `\| **Status** \|` | cảnh báo nếu đang `draft` (xem dưới) |
-| `max_uc` | số UC lớn nhất trong §3 | UC mới = `max_uc + 1` |
-| `max_br` | số BR lớn nhất **trên TOÀN PRD** | BR mới = `max_br + 1` |
-| `max_ac` | số AC lớn nhất trong §2 | AC mới = `max_ac + 1` |
-| `existing_ucs` | danh sách UC-ID + tên | phát hiện va chạm ở Bước 3 · báo "UC không đổi" ở Bước 7 |
-| `changelog_rows` | bảng `# Change Log` | biết PRD đã đi qua những gì |
-| `api_source` | Metadata `API Source` | quyết có cần hỏi contract cho phần thêm không |
-| `bdd_generated` | glob `{specs_dir}/{domain}/{prd-slug}/bdd/*/{TICKET-ID}-UC*.feature` | **cảnh báo BR ID churn** + route ở Bước 7 |
-
-**Guard — PRD đang `draft`:** nếu `current_status != approved` → cảnh báo mềm, không chặn:
-```
-⚠️  PRD đang ở Status: {status} (chưa approved).
-    Thêm yêu cầu lên một PRD chưa chốt sẽ trộn hai việc: phần chưa duyệt + phần mới.
-    Cân nhắc hoàn tất review vòng hiện tại trước (/review-context → PO duyệt).
-    Vẫn thêm bây giờ? (Y/N)
-```
-
-**Guard — BDD đã sinh:** nếu `bdd_generated` không rỗng, hiện danh sách và nêu rõ hệ quả:
-```
-ℹ️  {n} file BDD đã sinh cho PRD này: {danh sách UC × platform}
-    Lệnh này CHỈ đánh số nối tiếp (UC{max_uc+1}, BR{max_br+1}) — KHÔNG bao giờ đánh lại
-    ID cũ, nên các liên kết @trace.business_rules hiện có KHÔNG bị ảnh hưởng.
-    Sau khi thêm: chỉ cần /generate-bdd cho UC MỚI; các UC cũ không phải gen lại
-    (/validate-traces sẽ xếp chúng vào ⓘ PRD_STALE_REF, không phải 🟠 PRD_DRIFT).
-```
-
----
-
-## Bước 2 — Nạp hòm thư `prd-change-requests/`
-
-*Đây là **consumer** mà hàng đợi này thiếu suốt từ đầu: `/propose-scenario` Case B ghi vào đó, `/sync` thông báo lúc-đến, `/validate-traces` Step 7b đếm và nhắc — nhưng **không lệnh nào drain**. Đây là chỗ đó.*
-
-Quét `{paths.prd_change_requests_dir}/*.md` (mặc định `{spec_source}/feedback/prd-change-requests/`; **không** quét `archived/`). Thư mục vắng/rỗng → bỏ qua **im lặng**.
-
-Lọc theo PRD này: khớp `{TICKET-ID}` trong tên file hoặc field `UC / Ticket` của metadata request.
-
-| `Status` của request | Xử lý |
-|---|---|
-| `accepted` | Đưa `Requested behavior` + `Suggested AC` vào làm **nguyên liệu** cho Bước 3. **KHÔNG chèn thẳng vào PRD** — đây là yêu cầu nghiệp vụ, phải qua PO chốt AC/BR đúng tầng. |
-| `Open` (chưa ai xử) | **Trình cho PO ngay ở CHECKPOINT** kèm số ngày chờ: *"có {n} request chưa xử lý, đưa vào lần này không?"*. PO chọn từng cái. |
-| `rejected` / `incorporated` | Bỏ qua. |
-
-Lưu danh sách request sẽ xử lý (`incoming_requests`) — Bước 6.5 sẽ đóng dấu chúng.
-
----
-
-## Bước 3 — Discovery delta *(CHỈ phần thêm)*
-
-*Tái dùng đúng các phase của `/define-product` áp dụng được cho một phần thêm. **KHÔNG** lặp Phase 0 (Knowledge Sync — bối cảnh hệ thống đã có trong PRD), Phase 2 (User Flow toàn feature), Phase 7 (Validation Report toàn feature).*
-
-**Áp Discovery Contract của `/define-product`:** input của PO (kể cả nội dung request ở Bước 2) là **nguyên liệu thô**, KHÔNG phải câu trả lời thay phỏng vấn. Item đã phủ → trình bản nháp `🤖 trích từ input` rồi hỏi PO xác nhận/sửa; chỉ khi PO chốt mới nâng thành `✅ PO xác nhận`. **Không có luật skip-if-answered.**
-
-| Phase | Nội dung | Ghi chú |
-|---|---|---|
-| **3.1** | **Định nghĩa phần thêm** — bối cảnh · vấn đề · phạm vi in/out · actor · pre/post-condition | Tương ứng Phase 1 của `/define-product`, thu hẹp vào phần mới |
-| **3.2** | **Va chạm với cái đã có** ⭐ | Xem dưới — đây là phase KHÔNG có trong `/define-product` |
-| **3.3** | **Business Rule** cho phần thêm | Phase 4 |
-| **3.4** | **Business Logic** | Phase 5 |
-| **3.5** | **Acceptance Criteria** | Phase 6 — giữ tầng: AC = outcome quan sát được + ref BR, cơ chế nằm ở BR/BL |
-
-### 3.2 — Kiểm va chạm *(bắt buộc, không bỏ qua)*
-
-*`/define-product` không có phase này vì lúc đó chưa có gì để va chạm. Ở đây thì có — và va chạm âm thầm là cách một PRD tự mâu thuẫn.*
-
-Đối chiếu phần thêm với `existing_ucs` + toàn bộ BR hiện có, hỏi PO ba câu:
-
-1. **Mâu thuẫn rule:** phần thêm có làm một BR hiện có trở nên sai/không đủ không? *(vd BR cũ nói "tối đa 5 file", phần mới cần 20)* → nếu có, đây là **sửa BR cũ**, không phải thêm BR mới. Ghi rõ để Bước 5 sửa đúng chỗ và Bước 6 tính bump **major**.
-2. **Trùng lặp:** phần thêm đã được một UC/AC hiện có phủ một phần chưa? → nếu có, hỏi PO: **mở rộng UC cũ** hay **tạo UC mới**. Đừng tự quyết.
-3. **Phụ thuộc:** phần thêm có cần dữ liệu/năng lực từ UC khác hoặc service khác không? → bổ sung vào **§1c Phụ thuộc liên service**.
-
-Kết quả 3.2 quyết định hình dạng thay đổi:
-
-| Kết quả | Bước 5 làm gì |
-|---|---|
-| Thuần thêm mới | Append UC/AC/BR mới. Không đụng nội dung cũ. |
-| Có sửa BR cũ | Sửa **tại chỗ** BR đó (Edit) **+** append phần mới. Nêu rõ trong changelog. |
-| Mở rộng UC cũ | Append AC/BR mới **vào UC đó**, không tạo UC mới. |
-
-**CHECKPOINT** trước khi ghi:
-```
-CHECKPOINT — Extend PRD {TICKET-ID}
-─────────────────────────────────────────────────
-PRD        : v{current_version} ({current_status}) — {n} UC hiện có
-Thêm       : UC{max_uc+1} "{tên}"  [hoặc: mở rộng UC{k}]
-             +{n} AC (AC{max_ac+1}…) · +{m} BR (BR{max_br+1}…)
-Sửa cái cũ : {danh sách BR/AC bị sửa do va chạm — hoặc "không"}
-Từ request : {danh sách file request được đưa vào — hoặc "không"}
-Version    : {current} → {new} ({major|minor}) · Status → draft
-BDD ảnh hưởng: cần /generate-bdd cho UC mới; {n} UC cũ KHÔNG phải gen lại
-
-Tiếp tục? (Y/N)
-```
-
----
-
-## Bước 4 — Đánh số nối tiếp *(TUYỆT ĐỐI không đánh lại)*
-
-| Loại | Quy tắc |
-|---|---|
-| UC | `UC{max_uc + 1}`, tăng dần |
-| BR | `{TICKET-ID}-UC{n}-BR{max_br + 1}` — **`max_br` tính trên TOÀN PRD**, không reset theo UC |
-| AC | `AC{max_ac + 1}` |
-
-> **Đây là ràng buộc cứng nhất của lệnh này.** Đánh lại ID cũ — kể cả để "cho gọn" — sẽ phá:
-> - `@trace.business_rules` trong mọi `.feature` đã sinh (BR ID churn)
-> - dòng "AC liên quan" của từng UC
-> - mọi cross-reference `[TICKET-ID](./file.md)` từ PRD khác trỏ tới AC/BR cụ thể
->
-> Số bị bỏ trống (do UC cũ bị xoá ở version trước) **để trống vĩnh viễn**. Đừng lấp lại — ID đã từng
-> tồn tại có thể còn bị tham chiếu ở BDD, code, bug report, hoặc PRD khác.
-
----
-
-## Bước 5 — Ghi vào PRD *(Edit add-only, KHÔNG Write)*
-
-> **Kỷ luật EXTEND — copy nguyên từ `/generate-code` §File Scan, cùng lý do:**
->
-> 1. **Đọc lại file trên disk NGAY TRƯỚC khi ghi** (không dựa vào bản nạp ở Bước 1 — có thể đã đổi).
-> 2. **CHỈ dùng Edit để THÊM.** **CẤM tuyệt đối Write cả file.** Đây là nguyên nhân số 1 xoá nghiệp vụ đã duyệt.
-> 3. Output PHẢI là **superset chặt** của bản cũ: **mọi** UC, AC, BR, row bảng, dòng changelog, cross-reference cũ **còn nguyên si** — trừ đúng những chỗ Bước 3.2 kết luận là "sửa BR cũ", và chỉ đúng những chỗ đó.
-> 4. **Guard sau-ghi (bắt buộc):** đọc lại file vừa ghi, đối chiếu với bản trước khi sửa. Kiểm: mọi UC-ID cũ · mọi BR-ID cũ · mọi AC cũ · mọi row `# Change Log` cũ **vẫn còn**. Nếu **mất bất kỳ cái nào** → **DỪNG NGAY, khôi phục file về bản cũ** (`git checkout -- {file}` nếu đã commit, hoặc hoàn tác edit), báo:
->    ```
->    ❌ EXTEND làm mất {UC/AC/BR/changelog row} — đã chặn clobber.
->       File đã khôi phục. Sửa lại theo add-only rồi chạy lại.
->    ```
->    **KHÔNG** tiếp tục sang Bước 6.
-
-Vị trí ghi từng loại nội dung:
-
-| Nội dung | Đặt ở đâu |
-|---|---|
-| UC mới | **Cuối §3**, sau UC hiện có cuối cùng. Đủ Actor · Description · Pre-condition · Post-condition · bảng BR · dòng "AC liên quan" |
-| AC mới | **Cuối §2**, kèm ref `_(BR: …)_` trỏ về BR tương ứng |
-| BR mới | Bảng BR của UC sở hữu. **Giữ đúng hình dạng bảng hiện có** (3 cột hay đã mở cột) — đừng đổi hình dạng ở lệnh này |
-| Phụ thuộc mới | **§1c Phụ thuộc liên service** — append, mức nghiệp vụ |
-| Màn hình mới | **§4b Wireframe** — nguồn coverage cho `/generate-bdd` C.1 |
-| Quy ước mới dùng ≥2 chỗ | **§1d**, khai MỘT LẦN, AC/BR trỏ tới thay vì chép |
-
-**Altitude khi viết** *(giống `/refine-prd` Phase 2)*: AC = **outcome quan sát/kiểm được + ref BR**, KHÔNG chứa cơ chế (số lần retry, timeout, tên cờ, nhánh lỗi vụn) — cơ chế nằm ở BR/BL. AC không lặp lại nội dung BR nó ref.
-
-**Chạy Business Language Guard trên MỌI text mới TRƯỚC khi ghi** — đừng để phần thêm kéo thuật ngữ kỹ thuật/UI vào một PRD đang sạch.
-
----
-
-## Bước 6 — Bump version & ghi changelog
-
-*Tái dùng **nguyên** `### Phase 3` của `/refine-prd`. Không viết lại luật ở đây — dòng changelog là **contract**: `/generate-bdd` Version Check đọc nó để quyết cập nhật hẹp (Y) hay gen lại toàn bộ (F), và `/validate-traces` Step 4/5 đọc nó để lọc `PRD_DRIFT` 🟠 vs `PRD_STALE_REF` ⓘ. Viết kiểu khác là làm hỏng cả hai.*
-
-1. Loại bump:
-   - **major** (X.0 → X+1.0): thêm UC mới · sửa BR cũ theo hướng breaking · tái cấu trúc scope. *(Thêm UC là major theo định nghĩa của `/refine-prd` Phase 3.)*
-   - **minor** (x.Y → x.Y+1): chỉ thêm AC/BR vào UC đã có, không đổi hành vi cũ.
-2. Cập nhật Metadata: `Version` = mới · `Updated` = hôm nay · **`Status` = `draft`** *(thêm yêu cầu = phải duyệt lại)*.
-3. Thêm row lên **đầu** bảng `# Change Log`:
-   ```
-   | {new_version} | {today} | {tóm tắt — BẮT BUỘC nêu UC/AC/BR bị ảnh hưởng} |
-   ```
-   **Ví dụ đúng:** `thêm UC7 (xuất nhiều file): AC12-AC14, BR21-BR23; sửa BR8 (nâng giới hạn 5→20)`
-   **Ví dụ SAI:** `cập nhật theo yêu cầu mới` ← mơ hồ → `/generate-bdd` sẽ khuyến nghị gen lại **toàn bộ**, và `/validate-traces` sẽ gắn `PRD_DRIFT` 🟠 cho **mọi** UC thay vì chỉ UC mới. Một dòng viết ẩu làm mất cả hai bộ lọc.
-4. Cập nhật dòng đầu section: `> Hiện tại: **v{new}** ({today}) · Lịch sử đầy đủ → [changelog](./changelog/{TICKET-ID}-{prd-slug}.changelog.md)`
-5. **Rollover** (cửa sổ trượt 5 row): bảng `# Change Log` vượt **5** row → chuyển mọi row vượt 5 (cũ nhất) sang **đầu** bảng của `{specs_dir}/{domain}/{prd-slug}/changelog/{TICKET-ID}-{prd-slug}.changelog.md`; PRD giữ 5 row gần nhất. Tạo dir + file theo skeleton của `/refine-prd` Phase 3 nếu chưa có.
-
----
-
-## Bước 6.5 — Đóng dấu request đã xử lý
-
-Với mỗi file trong `incoming_requests` đã được PO chốt và nội dung đã ghi vào PRD:
-
-1. Đặt `Status: incorporated` trong file request.
-2. Thêm dòng `Incorporated into: v{new_version}` — để lần sau tra được yêu cầu nào vào version nào.
-3. Chuyển file sang `{paths.prd_change_requests_dir}/archived/` (tạo dir nếu cần).
-4. **Commit + push** spec repo (giống `feedback/` — xem `/propose-scenario` Step 5): `git add feedback/prd-change-requests/ && git commit -m "po(prd-change): {TICKET-ID} — incorporated into v{new}" && git push`. Không có quyền push → mở PR/MR và in fallback.
-
-Request mà PO **không** chốt lần này → **để nguyên** `Status: Open`. `/validate-traces` Step 7b sẽ tiếp tục nhắc kèm số ngày chờ.
-
----
-
-## Bước 7 — Report
-
-{{include:steps/report-footer.md}}
-
-Ví dụ footer cho lệnh này:
-
-```
-/extend-prd Đã thêm — {TICKET-ID} {tên feature}
-
-Version   : v{old} → v{new} ({major|minor}) · Status → draft
-Thêm      : UC{N} "{tên}" · AC{a}-AC{b} · BR{c}-BR{d}
-Sửa cũ    : {BR8 — nâng giới hạn 5→20 | không}
-Request   : {2 file → archived/ (incorporated v{new}) | không}
-Changelog : | v{new} | {today} | thêm UC{N}: AC{a}-AC{b}, BR{c}-BR{d}; sửa BR8 |
-
-Guard sau-ghi : ✅ {n} UC · {m} AC · {k} BR · {j} changelog row cũ — còn nguyên
-
-UC KHÔNG đổi ({n}): {UC1, UC2, UC3…}
-  → KHÔNG cần /generate-bdd hay /generate-code cho các UC này.
-    /validate-traces sẽ xếp chúng vào ⓘ PRD_STALE_REF (nhãn version cũ, nội dung không đổi).
-    Sạch bằng: /validate-traces --realign-prd-version {UC-ID}
-
-⚠️  Status đã reset về draft — phần thêm chưa được duyệt.
-
----
-Status   : ✅ Complete
-Output Artifacts:
-  updated {paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md (v{new})
-  updated {paths.specs_dir}/{domain}/{prd-slug}/changelog/… (nếu có rollover)
-  updated {paths.prd_change_requests_dir}/archived/… (nếu có request)
-Pipeline : Discovery → [PRD ◀ bạn ở đây] → Design Spec → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-Next     : /refine-prd {prd-file}        ← soi phần vừa thêm qua 3 lăng kính
-           → /review-context {prd-file}  ← kiểm chất lượng trước khi sinh BDD
-           → khi sạch critical, PO đặt Status: approved, rồi:
-               • Feature CÓ màn hình → /generate-design-spec {prd-file} (design-spec sẽ tự
-                 phát hiện lỗi thời vs PRD mới và bắt sign-off lại) rồi /generate-bdd
-               • Thuần backend → /generate-bdd {prd-file} thẳng
-           → CHỈ gen BDD/code cho UC MỚI. UC cũ: dùng --realign-prd-version.
-```
-
----
-
-## Quality Checklist *(kiểm trước khi ghi)*
-
-- [ ] **Không đánh lại BẤT KỲ ID cũ nào** — UC/AC/BR mới đều là `max + 1`; số bị bỏ trống vẫn để trống
-- [ ] `max_br` tính trên **toàn PRD**, không reset theo UC
-- [ ] Guard sau-ghi đã chạy và PASS: mọi UC/AC/BR/changelog row cũ còn nguyên
-- [ ] Bước 3.2 đã hỏi đủ 3 câu va chạm (mâu thuẫn rule · trùng lặp · phụ thuộc)
-- [ ] Mỗi AC mới có ≥1 ref `_(BR: …)_`; mỗi UC mới có dòng "AC liên quan"; hai chiều khớp nhau
-- [ ] Dòng changelog **nêu rõ UC/AC/BR** — không mơ hồ *(contract cho `/generate-bdd` + bộ lọc `PRD_STALE_REF`)*
-- [ ] `Status` đã reset về `draft`
-- [ ] Hình dạng bảng BR giữ nguyên như cũ (không đổi 3-cột ↔ mở-cột ở lệnh này)
-- [ ] Không có banned term; 0 thuật ngữ kỹ thuật/UI trong text mới
-- [ ] Request đã xử lý → `incorporated` + `archived/` + commit; request chưa xử lý → giữ `Open`
-- [ ] Report nêu rõ danh sách **UC không đổi** + route `--realign-prd-version` cho chúng