@educa-corp/sdd-framework 0.4.2 → 0.5.0

package/core/commands/dev-gen-test.md

@@ -950,10 +950,34 @@ Giữ nguyên mọi cột khác (gồm `dev_selftest_at`, do `/dev-run-test` s
 ---
 
 ## Refresh Panel Mirror
-# Làm mới panel mirror của Living Docs *(local, chế độ umbrella)*
+# Làm mới panel mirror của Living Docs *(local)*
 
-*Bỏ qua hoàn toàn ở chế độ single-service (không có `services` và không có `setup.spec_source`) — ở đó
-`.trace/` của chính repo CHÍNH LÀ vị trí panel, nên không có gì để mirror.*
+> **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}`:
 
@@ -961,11 +985,14 @@ Sau khi cập nhật TSV authoritative tại `{paths.trace_dir}`:
 `{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` tại **gốc workspace hiện tại**.
-2. Nếu `panel_mirror` phân giải ra path khác với `{paths.trace_dir}`, copy mỗi
+
+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 trong
-   `@trace.service` của từng row.
+   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`
@@ -1018,7 +1045,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` |
@@ -1043,6 +1070,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}` |
@@ -1068,7 +1096,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /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 |

package/core/commands/dev-run-test.md

@@ -677,10 +677,34 @@ trực giao với `status` (OK/GAP/DRIFT/UNTRACKED/ORPHANED): `status` theo dõi
 theo dõi *kết quả chạy* gần nhất của dev.
 
 ## Refresh Panel Mirror
-# Làm mới panel mirror của Living Docs *(local, chế độ umbrella)*
+# Làm mới panel mirror của Living Docs *(local)*
 
-*Bỏ qua hoàn toàn ở chế độ single-service (không có `services` và không có `setup.spec_source`) — ở đó
-`.trace/` của chính repo CHÍNH LÀ vị trí panel, nên không có gì để mirror.*
+> **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}`:
 
@@ -688,11 +712,14 @@ Sau khi cập nhật TSV authoritative tại `{paths.trace_dir}`:
 `{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` tại **gốc workspace hiện tại**.
-2. Nếu `panel_mirror` phân giải ra path khác với `{paths.trace_dir}`, copy mỗi
+
+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 trong
-   `@trace.service` của từng row.
+   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`
@@ -743,7 +770,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` |
@@ -768,6 +795,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}` |
@@ -793,7 +821,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /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 |

package/core/commands/dev-smoke-test.md

@@ -716,7 +716,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` |
@@ -741,6 +741,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}` |
@@ -766,7 +767,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /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 |