@educa-corp/sdd-framework 0.3.0 → 0.4.2

package/commands/sync.md

@@ -198,7 +198,17 @@ Nếu không có thay đổi → `✅ Umbrella state clean — no commit needed`
 
 *Skip nếu `services` rỗng.*
 
-Với mỗi entry trong `services[]`:
+**Trước tiên — làm phẳng `services` thành danh sách submodule.** Một giá trị trong `services` có thể lồng tới ba tầng (xem `context-loader.md` Bước 1.5), nên duyệt nông sẽ **bỏ sót** submodule:
+
+| Dạng | Cách lấy submodule |
+|---|---|
+| `services.{domain}.path` (2a) | một entry |
+| `services.{domain}.{platform}.path` (2b) | một entry mỗi platform |
+| `…by_prd_slug.{slug}.path` (2c) | một entry mỗi `slug` — ở cấp domain hoặc cấp platform |
+
+Kết quả là tập các cặp `{path, module}` **duy nhất theo `path`** (nhiều domain/platform/slug có thể trỏ chung một submodule — chỉ xử lý một lần). Mọi bước dưới đây chạy trên danh sách đã làm phẳng này.
+
+Với mỗi entry trong danh sách đó:
 
 **A. Nếu `{service.path}/.agent/project-context.yaml` đã tồn tại:**
 - Đọc `conventions.test_command` và `conventions.build_command`
@@ -272,7 +282,7 @@ Nếu thiếu cái nào:
 - `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.
 
-1. Với mỗi service trong `services[]`: 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).
+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`.
@@ -375,6 +385,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}` |
@@ -383,8 +394,8 @@ 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/` |

package/commands/sync.tmpl

@@ -198,7 +198,17 @@ Nếu không có thay đổi → `✅ Umbrella state clean — no commit needed`
 
 *Skip nếu `services` rỗng.*
 
-Với mỗi entry trong `services[]`:
+**Trước tiên — làm phẳng `services` thành danh sách submodule.** Một giá trị trong `services` có thể lồng tới ba tầng (xem `context-loader.md` Bước 1.5), nên duyệt nông sẽ **bỏ sót** submodule:
+
+| Dạng | Cách lấy submodule |
+|---|---|
+| `services.{domain}.path` (2a) | một entry |
+| `services.{domain}.{platform}.path` (2b) | một entry mỗi platform |
+| `…by_prd_slug.{slug}.path` (2c) | một entry mỗi `slug` — ở cấp domain hoặc cấp platform |
+
+Kết quả là tập các cặp `{path, module}` **duy nhất theo `path`** (nhiều domain/platform/slug có thể trỏ chung một submodule — chỉ xử lý một lần). Mọi bước dưới đây chạy trên danh sách đã làm phẳng này.
+
+Với mỗi entry trong danh sách đó:
 
 **A. Nếu `{service.path}/.agent/project-context.yaml` đã tồn tại:**
 - Đọc `conventions.test_command` và `conventions.build_command`
@@ -272,7 +282,7 @@ Nếu thiếu cái nào:
 - `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.
 
-1. Với mỗi service trong `services[]`: 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).
+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`.

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
@@ -198,6 +235,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,8 +244,8 @@ 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/` |

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