@educa-corp/sdd-framework 0.4.0 → 0.5.0

package/commands/extend-prd.tmpl

@@ -0,0 +1,270 @@
+# /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
+{{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

package/commands/fix-bug.md

@@ -32,23 +32,23 @@ Hiển thị và chờ phản hồi:
 ```
 ⚙️  MODEL CHECK
 ──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4 (hoặc model Opus mới nhất)
+  Recommended  : model Opus mới nhất
   Why needed   : Phân tích spec, review kiến trúc, sinh code đòi hỏi
-                 suy luận sâu. Model nhỏ hơn dễ bỏ sót edge case.
+                 suy luận sâu. Model nhỏ hơn (Haiku/Sonnet) dễ bỏ sót edge case.
 
   Cách đổi trong Claude Code:
-    • Settings → Model → chọn "claude-opus"
-    • hoặc: /model → chọn claude-opus
+    • /model → chọn model Opus
+    • hoặc: Settings → Model
 
-  Đang chạy claude-opus?
-    Y — đúng, đang dùng claude-opus → tiếp tục
+  Đang chạy một model Opus?
+    Y — đúng → tiếp tục
     S — bỏ qua kiểm tra (tôi chấp nhận rủi ro chất lượng thấp hơn với model hiện tại)
 ──────────────────────────────────────────────────────────────────
 ```
 
 - "Y" → tiếp tục sang Bước 1.
 - "S" → tiếp tục sang Bước 1 (người dùng chấp nhận rủi ro, thêm ⚠️ vào report cuối).
-- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang claude-opus rồi chạy lại lệnh này."
+- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang một model Opus (`/model`) rồi chạy lại lệnh này."
 
 ## Bước 1 — Xác định Target File
 
@@ -57,7 +57,12 @@ Hiển thị và chờ phản hồi:
 2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`):
    - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó.
    - **Lệnh PRD** (target là file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)*
-   - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
+   - **Lệnh tech-docs** — target là tech-doc **gộp cấp PRD** `{TICKET-ID}-tech-design.md` (MỘT doc phủ nhiều UC; danh sách UC nằm ở `@trace.ucs`). Vì tên file mang `{TICKET-ID}` chứ **không** mang `{UC-ID}`, phải tách trước khi glob:
+     - `$ARGUMENTS` là **UC-ID** (`{TICKET-ID}-UC{N}`) → lấy `{TICKET-ID}` = phần **trước** `-UC`, rồi glob `{specs_dir}/{domain}/*/tech-docs/{TICKET-ID}-tech-design.md`.
+     - `$ARGUMENTS` là **TICKET-ID** → glob trực tiếp như trên.
+     - Chưa biết domain → `{specs_dir}/*/*/tech-docs/{TICKET-ID}-tech-design.md`.
+     - Vẫn không khớp → glob rộng `{specs_dir}/*/*/tech-docs/*tech-design*.md` rồi liệt kê để người dùng chọn.
+     *(Đừng glob `{UC-ID}*-tech-design*.md` — nó nở thành `FT-001-UC1*-tech-design*.md` và **không bao giờ** khớp `FT-001-tech-design.md`.)*
    - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
 
    Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
@@ -569,9 +574,10 @@ git checkout -b fix/{TICKET_ID}-{description}
 ```
 Áp dụng fix. Thêm trace annotation nếu file có `@trace.implements`:
 ```
-@trace.fixes={TICKET_ID}
+@trace.fixes={BUG-ID nếu fix từ một bug report đã file · else TICKET_ID}
 @trace.root_cause={brief description}
 ```
+*(Ưu tiên `{BUG-ID}`: khi fix bắt nguồn từ `/report-bug` thì thường **không có** ticket ID nào, và `{BUG-ID}` mới là thứ trace ngược được về spec context + AC bị vi phạm.)*
 
 ## Phase 4 — Regression Test
 ```
@@ -581,7 +587,83 @@ Test: "Regression {TICKET_ID}: {bug description}"
 ```
 Chạy test. Nếu fail → debug và fix (tối đa 3 vòng).
 
-## Phase 5 — Build & Commit (push 2 tầng ở umbrella mode)
+## Phase 4.5 — Cập nhật sổ trace
+
+*Bỏ qua nếu fix không chạm SC nào có row trace (vd fix hạ tầng/config).*
+
+Đây là lệnh **duy nhất** sinh test mà trước đây không ghi sổ — hệ quả: `test_count` under-report vĩnh viễn (SC đứng `GAP` dù vừa có regression test, rồi `/validate-traces` khuyên `/dev-gen-test` → dev sinh test trùng), và `dev_selftest` giữ `pass` cũ **trên code đã đổi**.
+
+Định vị sổ platform `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` — `{platform}` = platform của code vừa fix; không rõ → glob `{UC-ID}-*.tsv` tìm sổ nào chứa `sc_id` đó, khớp nhiều sổ → **hỏi** (cùng luật với `/report-bug` Step 5.5).
+
+Với mỗi SC mà regression test phủ (theo `@trace.verifies` của test vừa viết):
+
+| Cột | Giá trị |
+|---|---|
+| `test_count` | **+=** số test method regression vừa thêm (cộng dồn, không ghi đè) |
+| `test_classes` | **append** tên test class/describe mới, giữ nguyên tên cũ |
+| `dev_selftest` | `not_run` — code vừa đổi nên tín hiệu self-test cũ hết hiệu lực |
+| `dev_selftest_at` | `—` |
+| `last_updated` | hôm nay `YYYY-MM-DD` |
+
+Giữ nguyên mọi cột khác. Đặc biệt:
+- **KHÔNG** đụng `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` — QC sở hữu; `/qc-run-test` sẽ flip khi re-verify (và chính nó đóng `{BUG-ID}` → `🟢 Closed`).
+- **KHÔNG** đụng `spec_ver`/`gen_ver` — fix bug **không** đổi spec, nên không được tạo tín hiệu DRIFT giả.
+
+Rồi làm mới panel mirror:
+# Làm mới panel mirror của Living Docs *(local)*
+
+> **Hai vị trí, HAI TÊN KHÁC NHAU — đọc trước khi sửa gì ở đây.**
+>
+> | Đường dẫn | Vai trò | Git |
+> |---|---|---|
+> | `{paths.trace_dir}` (`.trace/` hoặc `{spec_source}/.trace/`) | **AUTHORITATIVE** — TSV + `trace-history.jsonl`. Không regenerate được. | **PHẢI commit** |
+> | `./.trace-mirror/` ở gốc workspace hiện tại | **MIRROR** — bản sao tiện cho panel VS Code. Sinh lại được bất cứ lúc nào. | **Luôn gitignore** |
+>
+> Trước v0.4.3 cả hai đều tên `.trace`, nên một luật gitignore theo tên có thể **xoá sạch sổ gốc**
+> khi dev mở thẳng spec repo làm workspace (lúc đó hai path bằng nhau). Hai tên khác nhau làm
+> luật git đọc được bằng mắt và **không còn ca nhập nhằng nào**: `.trace-mirror/` không bao giờ
+> commit, `.trace/` không bao giờ gitignore.
+
+## Khi nào CÓ mirror
+
+Mirror chỉ tồn tại khi **`{paths.trace_dir}` nằm NGOÀI workspace hiện tại** — panel đọc từ workspace đang mở nên cần một bản sao ở đây.
+
+| Tình huống | `{paths.trace_dir}` | Có mirror? |
+|---|---|---|
+| Single-service | `./.trace` — **trong** workspace | ❌ Không. Panel đọc thẳng `.trace/trace-report.json`. Bỏ qua cả file này. |
+| Dev mở thẳng **spec repo** | `./.trace` — **trong** workspace | ❌ Không. Như trên. |
+| Umbrella + `spec_source`, dev đứng ở umbrella hoặc service submodule | `{spec_source}/.trace` — **ngoài** workspace | ✅ Có |
+| Umbrella legacy (không `spec_source`) | `.trace` theo từng service | ✅ Có |
+
+Quy tắc một dòng: **phân giải `panel_mirror = ./.trace-mirror` ở gốc workspace hiện tại; nếu `{paths.trace_dir}` đã nằm trong workspace này thì bỏ qua toàn bộ bước mirror.**
+
+---
+
+Sau khi cập nhật TSV authoritative tại `{paths.trace_dir}`:
+
+**Khi `setup.spec_source` được đặt (trace gộp — trường hợp phổ biến):**
+`{paths.trace_dir}` phân giải về `{spec_source}/.trace` — vị trí authoritative duy nhất.
+Lệnh này chạy từ `service_root`, nên thao tác ghi là **liên-repo vào spec submodule**;
+commit/push spec submodule cho lần cập nhật trace (giống như `feedback/`).
+
+1. Phân giải `panel_mirror = ./.trace-mirror` tại **gốc workspace hiện tại**.
+2. Nếu `{paths.trace_dir}` **không** nằm trong workspace hiện tại, copy mỗi
+   `{UC-ID}-{platform}.tsv` vừa cập nhật → `{panel_mirror}/{UC-ID}-{platform}.tsv` (tạo thư mục; ghi đè).
+   Không namespace theo service — chỉ có một bộ trace; service sở hữu được mang ở
+   **cột `service` (cột 23)** của chính từng row, do `/generate-bdd` ghi từ `@trace.service`.
+3. **KHÔNG copy `trace-history.jsonl`.** Nó là dữ liệu tích luỹ, không phải thứ sinh lại được —
+   nhân bản nó ra một thư mục gitignore là tạo hai lịch sử lệch nhau rồi mất bản thật.
+
+**Legacy (không có `spec_source` — trace theo service):**
+Copy mỗi `{UC-ID}-{platform}.tsv` vừa cập nhật → `{panel_mirror}/{service-name}/{UC-ID}-{platform}.tsv`
+(namespace theo `active_service`).
+
+Cách này giữ panel Living Docs của workspace đang mở luôn mới **giữa các lần sync** — nó chỉ là
+một **mirror tiện lợi cục bộ**. File `trace-report.json` đã merge (canonical, trong
+`{spec_source}/.living-docs/`) được build lại bởi `/sync` hoặc `/validate-traces`. Với các lệnh
+được orchestrate, làm việc này một lần trong orchestrator sau khi tất cả sub-agent trả về — không phải
+bên trong từng sub-agent.
+
 ```bash
 {conventions.build_command}   # tối đa 3 retry — chạy trong {service_root} ở umbrella mode
 # Tầng 1 — push fix branch trong service submodule (nơi code sống):
@@ -746,7 +828,7 @@ Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **pha
 | Phase | Commands |
 |-------|----------|
 | Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| PRD | `/generate-prd` · `/extend-prd` · `/refine-prd` · `/review-context` (PRD) |
 | Design Spec | `/generate-design-spec` |
 | BDD | `/generate-bdd` · `/review-context` (BDD) |
 | Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
@@ -771,6 +853,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
+| /extend-prd             | `/refine-prd {prd-file}` (soi phần vừa thêm) rồi `/review-context {prd-file}` → PO duyệt → `/generate-bdd` **chỉ cho UC MỚI**; UC cũ dùng `/validate-traces --realign-prd-version {UC-ID}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
 | /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
@@ -783,6 +866,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
 | /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
 | /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
+| /map-testids            | `/qc-design-test {UC-ID}` (QC dựng Page Object từ contract §4.5.6 vừa ghi) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
 | /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/dev-gen-test {UC-ID}` |
@@ -791,11 +875,11 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /dev-run-test (failing)    | `/fix-bug {ticket-id}` hoặc `/debug {error}`    |
 | /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
 | /dev-smoke-test             | Tạo PR và link tới ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR |
-| /fix-bug                | Tạo PR và link tới ticket                  |
+| /validate-traces        | **Cờ 🔴 trước (chặn PR):** SEAM_UNWIRED → nối binding sang class thật, xoá/thay stub · STUB_UNRESOLVED → `/generate-code {owner_uc}` (lấp logic tại chỗ + xoá hàm song song) · ORPHANED/TRACE_ORPHAN → quyết định thủ công (xoá code+test, đưa scenario trở lại `.feature`, hoặc sửa `sc_id` của tag). **Rồi:** DRIFT/UNTRACKED → `/generate-code {UC-ID}` · BDD_DRIFT → `/generate-code {feature-file}` · tech-doc lỗi thời vs BDD → `/generate-tech-docs` → `/review-tech-docs` · PRD drift → `/generate-bdd {prd-file}` · GAP → `/dev-gen-test {UC-ID}`. **Chỉ tạo PR khi mọi cờ 🔴 = 0** |
+| /fix-bug                | `/dev-run-test {UC-ID}` (dev_selftest vừa reset về not_run) → tạo PR; nếu fix một `{BUG-ID}` → QC chạy `/qc-run-test {UC-ID}` để verify + đóng bug |
 | /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
 | /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
+| /propose-scenario       | **Case A** (thiếu scenario cho AC có sẵn) → báo PO/Dev review trong `feedback/bdd-proposals/`; `/generate-bdd` tự chèn khi `Status: accepted`. **Case B** (requirement mới) → `feedback/prd-change-requests/` — PO phải đưa vào PRD trước, KHÔNG tự vào BDD được; `/validate-traces` nhắc lại kèm số ngày chờ chừng nào `Status: Open` |
 | /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
 | /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
 | /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |
@@ -817,8 +901,10 @@ Next     : {lệnh gợi ý kèm ví dụ tham số}
 Root Cause: {analysis}
 Changes: {list}
 ✅ Regression test added | ✅ Build: SUCCESS
+{Trace: {UC-ID}-{platform}.tsv updated — test_count +{n}, dev_selftest → not_run | nếu có chạm row trace}
 {🐞 BUG-{id} → State: Fixed (pushed) — Closed sau khi /qc-run-test re-verify pass | nếu fix một bug đã file}
 {📝 Lesson L-NNN recorded (nếu đã capture)}
 Branch: fix/{TICKET_ID}-{slug}
-Next: Tạo PR và link tới ticket. {QC: chạy lại /qc-run-test {UC-ID} để verify + đóng bug | nếu áp dụng}
+Next: /dev-run-test {UC-ID}  ← dev_selftest vừa bị reset về not_run, chạy để lấy lại tín hiệu xanh
+      Rồi tạo PR và link tới ticket. {QC: chạy lại /qc-run-test {UC-ID} để verify + đóng bug | nếu áp dụng}
 ```

package/commands/fix-bug.tmpl

@@ -95,9 +95,10 @@ git checkout -b fix/{TICKET_ID}-{description}
 ```
 Áp dụng fix. Thêm trace annotation nếu file có `@trace.implements`:
 ```
-@trace.fixes={TICKET_ID}
+@trace.fixes={BUG-ID nếu fix từ một bug report đã file · else TICKET_ID}
 @trace.root_cause={brief description}
 ```
+*(Ưu tiên `{BUG-ID}`: khi fix bắt nguồn từ `/report-bug` thì thường **không có** ticket ID nào, và `{BUG-ID}` mới là thứ trace ngược được về spec context + AC bị vi phạm.)*
 
 ## Phase 4 — Regression Test
 ```
@@ -107,7 +108,30 @@ Test: "Regression {TICKET_ID}: {bug description}"
 ```
 Chạy test. Nếu fail → debug và fix (tối đa 3 vòng).
 
-## Phase 5 — Build & Commit (push 2 tầng ở umbrella mode)
+## Phase 4.5 — Cập nhật sổ trace
+
+*Bỏ qua nếu fix không chạm SC nào có row trace (vd fix hạ tầng/config).*
+
+Đây là lệnh **duy nhất** sinh test mà trước đây không ghi sổ — hệ quả: `test_count` under-report vĩnh viễn (SC đứng `GAP` dù vừa có regression test, rồi `/validate-traces` khuyên `/dev-gen-test` → dev sinh test trùng), và `dev_selftest` giữ `pass` cũ **trên code đã đổi**.
+
+Định vị sổ platform `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` — `{platform}` = platform của code vừa fix; không rõ → glob `{UC-ID}-*.tsv` tìm sổ nào chứa `sc_id` đó, khớp nhiều sổ → **hỏi** (cùng luật với `/report-bug` Step 5.5).
+
+Với mỗi SC mà regression test phủ (theo `@trace.verifies` của test vừa viết):
+
+| Cột | Giá trị |
+|---|---|
+| `test_count` | **+=** số test method regression vừa thêm (cộng dồn, không ghi đè) |
+| `test_classes` | **append** tên test class/describe mới, giữ nguyên tên cũ |
+| `dev_selftest` | `not_run` — code vừa đổi nên tín hiệu self-test cũ hết hiệu lực |
+| `dev_selftest_at` | `—` |
+| `last_updated` | hôm nay `YYYY-MM-DD` |
+
+Giữ nguyên mọi cột khác. Đặc biệt:
+- **KHÔNG** đụng `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` — QC sở hữu; `/qc-run-test` sẽ flip khi re-verify (và chính nó đóng `{BUG-ID}` → `🟢 Closed`).
+- **KHÔNG** đụng `spec_ver`/`gen_ver` — fix bug **không** đổi spec, nên không được tạo tín hiệu DRIFT giả.
+
+Rồi làm mới panel mirror:
+{{include:steps/trace-mirror.md}}
 ```bash
 {conventions.build_command}   # tối đa 3 retry — chạy trong {service_root} ở umbrella mode
 # Tầng 1 — push fix branch trong service submodule (nơi code sống):
@@ -164,8 +188,10 @@ Nếu `Y` → chạy quy trình capture bên dưới với `source=/fix-bug {TIC
 Root Cause: {analysis}
 Changes: {list}
 ✅ Regression test added | ✅ Build: SUCCESS
+{Trace: {UC-ID}-{platform}.tsv updated — test_count +{n}, dev_selftest → not_run | nếu có chạm row trace}
 {🐞 BUG-{id} → State: Fixed (pushed) — Closed sau khi /qc-run-test re-verify pass | nếu fix một bug đã file}
 {📝 Lesson L-NNN recorded (nếu đã capture)}
 Branch: fix/{TICKET_ID}-{slug}
-Next: Tạo PR và link tới ticket. {QC: chạy lại /qc-run-test {UC-ID} để verify + đóng bug | nếu áp dụng}
+Next: /dev-run-test {UC-ID}  ← dev_selftest vừa bị reset về not_run, chạy để lấy lại tín hiệu xanh
+      Rồi tạo PR và link tới ticket. {QC: chạy lại /qc-run-test {UC-ID} để verify + đóng bug | nếu áp dụng}
 ```

package/commands/generate-architecture.md

@@ -45,23 +45,23 @@ Hiển thị và chờ phản hồi:
 ```
 ⚙️  MODEL CHECK
 ──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4 (hoặc model Opus mới nhất)
+  Recommended  : model Opus mới nhất
   Why needed   : Phân tích spec, review kiến trúc, sinh code đòi hỏi
-                 suy luận sâu. Model nhỏ hơn dễ bỏ sót edge case.
+                 suy luận sâu. Model nhỏ hơn (Haiku/Sonnet) dễ bỏ sót edge case.
 
   Cách đổi trong Claude Code:
-    • Settings → Model → chọn "claude-opus"
-    • hoặc: /model → chọn claude-opus
+    • /model → chọn model Opus
+    • hoặc: Settings → Model
 
-  Đang chạy claude-opus?
-    Y — đúng, đang dùng claude-opus → tiếp tục
+  Đang chạy một model Opus?
+    Y — đúng → tiếp tục
     S — bỏ qua kiểm tra (tôi chấp nhận rủi ro chất lượng thấp hơn với model hiện tại)
 ──────────────────────────────────────────────────────────────────
 ```
 
 - "Y" → tiếp tục sang Bước 1.
 - "S" → tiếp tục sang Bước 1 (người dùng chấp nhận rủi ro, thêm ⚠️ vào report cuối).
-- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang claude-opus rồi chạy lại lệnh này."
+- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang một model Opus (`/model`) rồi chạy lại lệnh này."
 
 ## Bước 1 — Xác định Target File
 
@@ -70,7 +70,12 @@ Hiển thị và chờ phản hồi:
 2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`):
    - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó.
    - **Lệnh PRD** (target là file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)*
-   - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
+   - **Lệnh tech-docs** — target là tech-doc **gộp cấp PRD** `{TICKET-ID}-tech-design.md` (MỘT doc phủ nhiều UC; danh sách UC nằm ở `@trace.ucs`). Vì tên file mang `{TICKET-ID}` chứ **không** mang `{UC-ID}`, phải tách trước khi glob:
+     - `$ARGUMENTS` là **UC-ID** (`{TICKET-ID}-UC{N}`) → lấy `{TICKET-ID}` = phần **trước** `-UC`, rồi glob `{specs_dir}/{domain}/*/tech-docs/{TICKET-ID}-tech-design.md`.
+     - `$ARGUMENTS` là **TICKET-ID** → glob trực tiếp như trên.
+     - Chưa biết domain → `{specs_dir}/*/*/tech-docs/{TICKET-ID}-tech-design.md`.
+     - Vẫn không khớp → glob rộng `{specs_dir}/*/*/tech-docs/*tech-design*.md` rồi liệt kê để người dùng chọn.
+     *(Đừng glob `{UC-ID}*-tech-design*.md` — nó nở thành `FT-001-UC1*-tech-design*.md` và **không bao giờ** khớp `FT-001-tech-design.md`.)*
    - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
 
    Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
@@ -701,7 +706,7 @@ Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **pha
 | Phase | Commands |
 |-------|----------|
 | Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| PRD | `/generate-prd` · `/extend-prd` · `/refine-prd` · `/review-context` (PRD) |
 | Design Spec | `/generate-design-spec` |
 | BDD | `/generate-bdd` · `/review-context` (BDD) |
 | Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
@@ -726,6 +731,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
+| /extend-prd             | `/refine-prd {prd-file}` (soi phần vừa thêm) rồi `/review-context {prd-file}` → PO duyệt → `/generate-bdd` **chỉ cho UC MỚI**; UC cũ dùng `/validate-traces --realign-prd-version {UC-ID}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
 | /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
@@ -738,6 +744,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
 | /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
 | /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
+| /map-testids            | `/qc-design-test {UC-ID}` (QC dựng Page Object từ contract §4.5.6 vừa ghi) |
 | /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
 | /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
 | /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/dev-gen-test {UC-ID}` |
@@ -746,11 +753,11 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /dev-run-test (failing)    | `/fix-bug {ticket-id}` hoặc `/debug {error}`    |
 | /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
 | /dev-smoke-test             | Tạo PR và link tới ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR |
-| /fix-bug                | Tạo PR và link tới ticket                  |
+| /validate-traces        | **Cờ 🔴 trước (chặn PR):** SEAM_UNWIRED → nối binding sang class thật, xoá/thay stub · STUB_UNRESOLVED → `/generate-code {owner_uc}` (lấp logic tại chỗ + xoá hàm song song) · ORPHANED/TRACE_ORPHAN → quyết định thủ công (xoá code+test, đưa scenario trở lại `.feature`, hoặc sửa `sc_id` của tag). **Rồi:** DRIFT/UNTRACKED → `/generate-code {UC-ID}` · BDD_DRIFT → `/generate-code {feature-file}` · tech-doc lỗi thời vs BDD → `/generate-tech-docs` → `/review-tech-docs` · PRD drift → `/generate-bdd {prd-file}` · GAP → `/dev-gen-test {UC-ID}`. **Chỉ tạo PR khi mọi cờ 🔴 = 0** |
+| /fix-bug                | `/dev-run-test {UC-ID}` (dev_selftest vừa reset về not_run) → tạo PR; nếu fix một `{BUG-ID}` → QC chạy `/qc-run-test {UC-ID}` để verify + đóng bug |
 | /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
 | /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
+| /propose-scenario       | **Case A** (thiếu scenario cho AC có sẵn) → báo PO/Dev review trong `feedback/bdd-proposals/`; `/generate-bdd` tự chèn khi `Status: accepted`. **Case B** (requirement mới) → `feedback/prd-change-requests/` — PO phải đưa vào PRD trước, KHÔNG tự vào BDD được; `/validate-traces` nhắc lại kèm số ngày chờ chừng nào `Status: Open` |
 | /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
 | /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
 | /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |