@educa-corp/sdd-framework 0.4.2 → 0.5.0

package/commands/setup-ai-first.md

@@ -446,7 +446,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` |
@@ -471,6 +471,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}` |
@@ -496,7 +497,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/commands/sync.md

@@ -261,16 +261,37 @@ Với mỗi entry trong danh sách đó:
 
 ## Step 4 — Check `.gitignore`
 
-Kiểm tra các Living Docs mirror được sinh ra có gitignore không:
-- `.trace/` trong `.gitignore` của repo hiện tại (hoặc `.git/info/exclude`)
-- `.living-docs/` trong `.gitignore` của **specs module** (khi `setup.spec_source` được set)
+*Bước này kiểm **hai chiều ngược nhau**, và nhầm chiều là mất dữ liệu — đọc bảng trước:*
 
-Nếu thiếu cái nào:
+| Đường dẫn | Vai trò | Kỳ vọng |
+|---|---|---|
+| `{paths.trace_dir}` (`.trace/` hoặc `{spec_source}/.trace/`) | **AUTHORITATIVE** — TSV + `trace-history.jsonl`, không regenerate được | **PHẢI commit** — gitignore nó là **lỗi nghiêm trọng** |
+| `.trace-mirror/` | bản sao tiện cho panel VS Code | phải gitignore |
+| `.living-docs/` | report sinh ra | phải gitignore |
+
+**4a. Cảnh báo mềm — mirror chưa gitignore.**
+Kiểm `.trace-mirror/` trong `.gitignore` của repo hiện tại (hoặc `.git/info/exclude`), và `.living-docs/` trong `.gitignore` của **specs module** (khi `setup.spec_source` được set). Thiếu cái nào:
+```
+⚠️ Mirror chưa gitignore — chúng được sinh ra, đừng bao giờ commit:
+   echo ".trace-mirror/" >> .gitignore
+   echo ".living-docs/" >> {spec_source}/.gitignore   # specs module (nếu có spec_source)
+```
+
+**4b. 🔴 Báo động — sổ gốc ĐANG bị bỏ qua.**
+Phân giải `{paths.trace_dir}`; nếu nó nằm trong một git repo, chạy `git -C {repo} check-ignore -q {trace_dir}`. **Trúng** (exit 0) → in ngay, mức chặn:
 ```
-⚠️ Living Docs mirrors not gitignored — they are generated, never commit them:
-   echo ".trace/" >> .gitignore
-   echo ".living-docs/" >> {spec_source}/.gitignore   # specs module (if spec_source set)
+🔴 NGUY HIỂM — sổ gốc trace ĐANG bị git bỏ qua: {paths.trace_dir}
+   Toàn bộ trạng thái theo dõi (spec_ver · gen_ver · implemented_by · test_count ·
+   dev_selftest · qc_status) VÀ trace-history.jsonl KHÔNG được lưu vào git.
+   Người khác clone repo về sẽ không thấy gì, và lịch sử thì KHÔNG dựng lại được.
+
+   Sửa:
+     1. Gỡ dòng khớp `.trace` khỏi .gitignore của {repo}
+     2. git -C {repo} add -f {trace_dir} && git -C {repo} commit -m "restore trace state"
+   Nguyên nhân thường gặp: bản trước v0.4.3 gọi panel mirror là `.trace` (trùng tên sổ gốc),
+   nên gợi ý "gitignore .trace/" của chính lệnh này có thể đã nhắm trúng sổ gốc.
 ```
+> **Vì sao cần báo động này:** trước v0.4.3, mirror và sổ gốc **cùng tên `.trace`**. Khi dev mở thẳng spec repo làm workspace thì hai path bằng nhau — và Step 4 (bản cũ) gợi ý gitignore theo **tên**, không theo vai trò. Làm theo là mất sổ gốc, **im lặng**: máy vẫn chạy, dashboard vẫn có số; chỉ người thứ hai clone về mới phát hiện. Bản v0.4.3 đổi tên mirror thành `.trace-mirror` để cái bẫy biến mất, nhưng **dự án đã dính từ trước thì vẫn dính** — 4b là để tìm ra chúng.
 
 ---
 
@@ -280,12 +301,12 @@ Nếu thiếu cái nào:
 
 **Phân giải Living Docs home (cùng quy tắc như `/validate-traces`):**
 - `living_docs_dir` = `{spec_source}/.living-docs` nếu `setup.spec_source` được set, else `.living-docs` ở umbrella root. *(Specs module được mount trong mọi service workspace, nên panel phân giải nó kể cả khi dev mở một service submodule đơn.)*
-- `panel_mirror` = `./.trace` ở gốc workspace hiện tại.
+- `panel_mirror` = `./.trace-mirror` ở gốc workspace hiện tại. *(Cố ý KHÁC tên `.trace` — xem Step 4.)*
 
 1. Với mỗi service trong danh sách **đã làm phẳng** ở Step 3 (gồm cả các submodule nằm dưới `by_prd_slug` — bỏ sót chúng là mất trace của các repo chia theo feature): nếu `{service.path}/.trace/` có file `.tsv` → copy chúng vào `{living_docs_dir}/{service-name}/` (tạo dir nếu cần).
 2. Ghi merged `{living_docs_dir}/trace-report.json`:
    - Tổng hợp TSV `.trace/` của mỗi service, thêm field `"service"` **và `"platform"`** (suy từ tên file `{UC-ID}-{platform}.tsv`) cho mỗi row, tính lại summary totals. **Không dedupe theo `sc_id` giữa các platform** — `web·SC1` và `system·SC1` là 2 row khác nhau; nhờ field `platform` dashboard hiển thị tách bạch coverage từng platform.
-3. **Mirror tới panel location:** copy `{living_docs_dir}/trace-report.json` (+ TSV namespaced) → `{panel_mirror}/` để panel trong repo đang mở không rỗng. Skip nếu `panel_mirror` đã bằng `living_docs_dir`.
+3. **Mirror tới panel location:** copy `{living_docs_dir}/trace-report.json` (+ TSV namespaced) → `{panel_mirror}/` để panel trong repo đang mở không rỗng. Skip nếu `panel_mirror` đã bằng `living_docs_dir`, hoặc nếu `{paths.trace_dir}` đã nằm trong workspace hiện tại (panel đọc thẳng ở đó). **KHÔNG** copy `trace-history.jsonl` — nó là dữ liệu tích luỹ, không phải thứ sinh lại được.
 
 In kết quả sync:
 ```
@@ -348,7 +369,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` |
@@ -373,6 +394,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}` |
@@ -398,7 +420,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 |
@@ -445,18 +467,20 @@ Service Configs
                        → create it so /dev-run-test works correctly
 
 .gitignore
-  ✅ .trace/ is gitignored
-  (or: ⚠️ Add .trace/ to .gitignore)
+  ✅ .trace-mirror/ + .living-docs/ gitignored   (mirror — sinh lại được)
+  ✅ {paths.trace_dir}/ KHÔNG bị gitignore       (sổ gốc — phải commit)
+  (hoặc: ⚠️ Thêm .trace-mirror/ vào .gitignore)
+  (hoặc: 🔴 NGUY HIỂM — sổ gốc {paths.trace_dir} đang bị gitignore, xem Step 4b)
 
 Living Docs
-  ✅ .trace/ synced — {N} TSVs across {S} services
-     (run /validate-traces for full coverage report)
+  ✅ {panel_mirror}/ synced — {N} TSVs across {S} services
+     (chạy /validate-traces để có report coverage đầy đủ)
 
 Spec Manifest
   ✅ spec-manifest.yaml — {N} features indexed
 
 ---
 Status : ✅ Complete | ⚠️ Warnings
-Output Artifacts: updated .trace/ (umbrella mirror), spec-manifest.yaml
+Output Artifacts: updated .trace-mirror/ (panel mirror), spec-manifest.yaml
 Next   : /validate-traces (full coverage check) | /generate-code {UC-ID} (start coding)
 ```

package/commands/sync.tmpl

@@ -261,16 +261,37 @@ Với mỗi entry trong danh sách đó:
 
 ## Step 4 — Check `.gitignore`
 
-Kiểm tra các Living Docs mirror được sinh ra có gitignore không:
-- `.trace/` trong `.gitignore` của repo hiện tại (hoặc `.git/info/exclude`)
-- `.living-docs/` trong `.gitignore` của **specs module** (khi `setup.spec_source` được set)
+*Bước này kiểm **hai chiều ngược nhau**, và nhầm chiều là mất dữ liệu — đọc bảng trước:*
 
-Nếu thiếu cái nào:
+| Đường dẫn | Vai trò | Kỳ vọng |
+|---|---|---|
+| `{paths.trace_dir}` (`.trace/` hoặc `{spec_source}/.trace/`) | **AUTHORITATIVE** — TSV + `trace-history.jsonl`, không regenerate được | **PHẢI commit** — gitignore nó là **lỗi nghiêm trọng** |
+| `.trace-mirror/` | bản sao tiện cho panel VS Code | phải gitignore |
+| `.living-docs/` | report sinh ra | phải gitignore |
+
+**4a. Cảnh báo mềm — mirror chưa gitignore.**
+Kiểm `.trace-mirror/` trong `.gitignore` của repo hiện tại (hoặc `.git/info/exclude`), và `.living-docs/` trong `.gitignore` của **specs module** (khi `setup.spec_source` được set). Thiếu cái nào:
+```
+⚠️ Mirror chưa gitignore — chúng được sinh ra, đừng bao giờ commit:
+   echo ".trace-mirror/" >> .gitignore
+   echo ".living-docs/" >> {spec_source}/.gitignore   # specs module (nếu có spec_source)
+```
+
+**4b. 🔴 Báo động — sổ gốc ĐANG bị bỏ qua.**
+Phân giải `{paths.trace_dir}`; nếu nó nằm trong một git repo, chạy `git -C {repo} check-ignore -q {trace_dir}`. **Trúng** (exit 0) → in ngay, mức chặn:
 ```
-⚠️ Living Docs mirrors not gitignored — they are generated, never commit them:
-   echo ".trace/" >> .gitignore
-   echo ".living-docs/" >> {spec_source}/.gitignore   # specs module (if spec_source set)
+🔴 NGUY HIỂM — sổ gốc trace ĐANG bị git bỏ qua: {paths.trace_dir}
+   Toàn bộ trạng thái theo dõi (spec_ver · gen_ver · implemented_by · test_count ·
+   dev_selftest · qc_status) VÀ trace-history.jsonl KHÔNG được lưu vào git.
+   Người khác clone repo về sẽ không thấy gì, và lịch sử thì KHÔNG dựng lại được.
+
+   Sửa:
+     1. Gỡ dòng khớp `.trace` khỏi .gitignore của {repo}
+     2. git -C {repo} add -f {trace_dir} && git -C {repo} commit -m "restore trace state"
+   Nguyên nhân thường gặp: bản trước v0.4.3 gọi panel mirror là `.trace` (trùng tên sổ gốc),
+   nên gợi ý "gitignore .trace/" của chính lệnh này có thể đã nhắm trúng sổ gốc.
 ```
+> **Vì sao cần báo động này:** trước v0.4.3, mirror và sổ gốc **cùng tên `.trace`**. Khi dev mở thẳng spec repo làm workspace thì hai path bằng nhau — và Step 4 (bản cũ) gợi ý gitignore theo **tên**, không theo vai trò. Làm theo là mất sổ gốc, **im lặng**: máy vẫn chạy, dashboard vẫn có số; chỉ người thứ hai clone về mới phát hiện. Bản v0.4.3 đổi tên mirror thành `.trace-mirror` để cái bẫy biến mất, nhưng **dự án đã dính từ trước thì vẫn dính** — 4b là để tìm ra chúng.
 
 ---
 
@@ -280,12 +301,12 @@ Nếu thiếu cái nào:
 
 **Phân giải Living Docs home (cùng quy tắc như `/validate-traces`):**
 - `living_docs_dir` = `{spec_source}/.living-docs` nếu `setup.spec_source` được set, else `.living-docs` ở umbrella root. *(Specs module được mount trong mọi service workspace, nên panel phân giải nó kể cả khi dev mở một service submodule đơn.)*
-- `panel_mirror` = `./.trace` ở gốc workspace hiện tại.
+- `panel_mirror` = `./.trace-mirror` ở gốc workspace hiện tại. *(Cố ý KHÁC tên `.trace` — xem Step 4.)*
 
 1. Với mỗi service trong danh sách **đã làm phẳng** ở Step 3 (gồm cả các submodule nằm dưới `by_prd_slug` — bỏ sót chúng là mất trace của các repo chia theo feature): nếu `{service.path}/.trace/` có file `.tsv` → copy chúng vào `{living_docs_dir}/{service-name}/` (tạo dir nếu cần).
 2. Ghi merged `{living_docs_dir}/trace-report.json`:
    - Tổng hợp TSV `.trace/` của mỗi service, thêm field `"service"` **và `"platform"`** (suy từ tên file `{UC-ID}-{platform}.tsv`) cho mỗi row, tính lại summary totals. **Không dedupe theo `sc_id` giữa các platform** — `web·SC1` và `system·SC1` là 2 row khác nhau; nhờ field `platform` dashboard hiển thị tách bạch coverage từng platform.
-3. **Mirror tới panel location:** copy `{living_docs_dir}/trace-report.json` (+ TSV namespaced) → `{panel_mirror}/` để panel trong repo đang mở không rỗng. Skip nếu `panel_mirror` đã bằng `living_docs_dir`.
+3. **Mirror tới panel location:** copy `{living_docs_dir}/trace-report.json` (+ TSV namespaced) → `{panel_mirror}/` để panel trong repo đang mở không rỗng. Skip nếu `panel_mirror` đã bằng `living_docs_dir`, hoặc nếu `{paths.trace_dir}` đã nằm trong workspace hiện tại (panel đọc thẳng ở đó). **KHÔNG** copy `trace-history.jsonl` — nó là dữ liệu tích luỹ, không phải thứ sinh lại được.
 
 In kết quả sync:
 ```
@@ -344,18 +365,20 @@ Service Configs
                        → create it so /dev-run-test works correctly
 
 .gitignore
-  ✅ .trace/ is gitignored
-  (or: ⚠️ Add .trace/ to .gitignore)
+  ✅ .trace-mirror/ + .living-docs/ gitignored   (mirror — sinh lại được)
+  ✅ {paths.trace_dir}/ KHÔNG bị gitignore       (sổ gốc — phải commit)
+  (hoặc: ⚠️ Thêm .trace-mirror/ vào .gitignore)
+  (hoặc: 🔴 NGUY HIỂM — sổ gốc {paths.trace_dir} đang bị gitignore, xem Step 4b)
 
 Living Docs
-  ✅ .trace/ synced — {N} TSVs across {S} services
-     (run /validate-traces for full coverage report)
+  ✅ {panel_mirror}/ synced — {N} TSVs across {S} services
+     (chạy /validate-traces để có report coverage đầy đủ)
 
 Spec Manifest
   ✅ spec-manifest.yaml — {N} features indexed
 
 ---
 Status : ✅ Complete | ⚠️ Warnings
-Output Artifacts: updated .trace/ (umbrella mirror), spec-manifest.yaml
+Output Artifacts: updated .trace-mirror/ (panel mirror), spec-manifest.yaml
 Next   : /validate-traces (full coverage check) | /generate-code {UC-ID} (start coding)
 ```

package/commands/update-framework.md

@@ -198,7 +198,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` |
@@ -223,6 +223,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}` |
@@ -248,7 +249,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 |