@educa-corp/sdd-framework 0.4.0 → 0.5.0

package/commands/update-framework.md

@@ -121,6 +121,43 @@ Tóm tắt cho người dùng:
 
 Nếu có command mới xuất hiện (vd một slash command mới), nêu rõ để user biết nó giờ đã có.
 
+**Kiểm file bị ghi đè.** `--init` copy `core/` → `.agent/` **vô điều kiện** — mọi thứ project đã sửa trong `.agent/` (trừ `project-context.yaml`) bị ghi đè. Từ v0.4.2 lệnh cài tự cứu chúng. Kiểm:
+
+```bash
+ls -d .agent/.overwritten-*/ 2>/dev/null
+```
+
+Nếu có → nêu **nổi bật** trong report (đây là thứ dễ trôi nhất trong một diff nâng cấp lớn):
+```
+⚠️  {n} file bạn sửa trong .agent/ đã bị bản nâng cấp ghi đè.
+    Bản cũ: .agent/.overwritten-{version}-{date}/
+    Xem diff: diff -r .agent/.overwritten-{version}-{date}/ .agent/
+    Sửa trực tiếp trong .agent/ KHÔNG bền — nó là mirror sinh ra. Muốn giữ thay đổi:
+    chuyển vào repo framework rồi phát hành, hoặc đặt ở CLAUDE.md /
+    .agent/project-context.yaml / .agent/project-lessons.md (ba chỗ không bị ghi đè).
+    Xử lý xong thì xoá thư mục backup.
+```
+
+Nếu **không** có thư mục nào → không in gì. *(Ranh giới vùng-sửa-được đầy đủ: `.agent/README.md`.)*
+
+---
+
+## Step 5.5 — Kiểm bố cục spec cần migrate
+
+*Chỉ quét, KHÔNG tự chuyển file — di chuyển spec là việc người dùng chốt.*
+
+Một số version thay đổi **bố cục** spec, không chỉ nội dung command. Quét nhanh hai dạng cũ và in hướng dẫn nếu gặp:
+
+| Phát hiện | Nghĩa | Lệnh migrate (dry-run trước) |
+|---|---|---|
+| Có file `.feature` **trực tiếp** dưới `{paths.specs_dir}/*/*/bdd/` (không trong subfolder platform) | Bố cục phẳng trước v0.4.1. `web`/`system` cùng UC va tên nhau; `/validate-traces` không thấy file; System BDD Synthesis luôn rơi về Backend-only. | `npx @educa-corp/sdd-framework --migrate-bdd-platform` → xem plan → thêm `--apply` |
+| Có `{paths.specs_dir}/prd/` hoặc `{paths.specs_dir}/bdd/` ở cấp gốc | Bố cục artifact-type-first (rất cũ) | `npx @educa-corp/sdd-framework --migrate-specs` → `--apply` |
+| Có `{paths.trace_dir}/*.tsv` phẳng (không có `{domain}/{prd-slug}/`) | Trace layout cũ | `--migrate-specs` (xử luôn) |
+
+Nếu sạch cả ba → không in gì.
+
+Sau migrate, nhắc chạy `/validate-traces` để reconcile sổ trace với bố cục mới.
+
 ---
 
 ## Output
@@ -161,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` |
@@ -186,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}` |
@@ -198,6 +236,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}` |
@@ -206,11 +245,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 |

package/commands/update-framework.tmpl

@@ -121,6 +121,43 @@ Tóm tắt cho người dùng:
 
 Nếu có command mới xuất hiện (vd một slash command mới), nêu rõ để user biết nó giờ đã có.
 
+**Kiểm file bị ghi đè.** `--init` copy `core/` → `.agent/` **vô điều kiện** — mọi thứ project đã sửa trong `.agent/` (trừ `project-context.yaml`) bị ghi đè. Từ v0.4.2 lệnh cài tự cứu chúng. Kiểm:
+
+```bash
+ls -d .agent/.overwritten-*/ 2>/dev/null
+```
+
+Nếu có → nêu **nổi bật** trong report (đây là thứ dễ trôi nhất trong một diff nâng cấp lớn):
+```
+⚠️  {n} file bạn sửa trong .agent/ đã bị bản nâng cấp ghi đè.
+    Bản cũ: .agent/.overwritten-{version}-{date}/
+    Xem diff: diff -r .agent/.overwritten-{version}-{date}/ .agent/
+    Sửa trực tiếp trong .agent/ KHÔNG bền — nó là mirror sinh ra. Muốn giữ thay đổi:
+    chuyển vào repo framework rồi phát hành, hoặc đặt ở CLAUDE.md /
+    .agent/project-context.yaml / .agent/project-lessons.md (ba chỗ không bị ghi đè).
+    Xử lý xong thì xoá thư mục backup.
+```
+
+Nếu **không** có thư mục nào → không in gì. *(Ranh giới vùng-sửa-được đầy đủ: `.agent/README.md`.)*
+
+---
+
+## Step 5.5 — Kiểm bố cục spec cần migrate
+
+*Chỉ quét, KHÔNG tự chuyển file — di chuyển spec là việc người dùng chốt.*
+
+Một số version thay đổi **bố cục** spec, không chỉ nội dung command. Quét nhanh hai dạng cũ và in hướng dẫn nếu gặp:
+
+| Phát hiện | Nghĩa | Lệnh migrate (dry-run trước) |
+|---|---|---|
+| Có file `.feature` **trực tiếp** dưới `{paths.specs_dir}/*/*/bdd/` (không trong subfolder platform) | Bố cục phẳng trước v0.4.1. `web`/`system` cùng UC va tên nhau; `/validate-traces` không thấy file; System BDD Synthesis luôn rơi về Backend-only. | `npx @educa-corp/sdd-framework --migrate-bdd-platform` → xem plan → thêm `--apply` |
+| Có `{paths.specs_dir}/prd/` hoặc `{paths.specs_dir}/bdd/` ở cấp gốc | Bố cục artifact-type-first (rất cũ) | `npx @educa-corp/sdd-framework --migrate-specs` → `--apply` |
+| Có `{paths.trace_dir}/*.tsv` phẳng (không có `{domain}/{prd-slug}/`) | Trace layout cũ | `--migrate-specs` (xử luôn) |
+
+Nếu sạch cả ba → không in gì.
+
+Sau migrate, nhắc chạy `/validate-traces` để reconcile sổ trace với bố cục mới.
+
 ---
 
 ## Output