@educa-corp/sdd-framework 0.5.0 → 0.6.0

package/commands/validate-traces.tmpl

@@ -3,6 +3,9 @@
 Check read-only độ phủ giữa spec, code, và test — gồm cả PRD version drift.
 
 ## Gate
+
+*Checkpoint: **không chặn** — read-only (ghi trace-report.json + TSV status, không đụng spec/code). Gate Bước 3 bỏ qua CHECKPOINT (Bước 3a).*
+
 {{include:steps/gate.md}}
 
 *Lưu ý: Với lệnh này, target ở Bước 1 là một tên domain hoặc UC-ID cụ thể từ `$ARGUMENTS`. Không có một file đơn để phân giải — lệnh quét nhiều thư mục.*
@@ -38,6 +41,44 @@ Kiểm tra mảng `services` có tồn tại trong `project-context.yaml` không
 
 ---
 
+### Step 1.0 — Lint sổ trace TRƯỚC khi đọc *(bắt buộc, không bỏ qua được)*
+
+Chạy checker xác định trên mọi trace dir đã phân giải ở Step 0:
+
+```bash
+npx @educa-corp/sdd-framework --lint-trace --trace {all_trace_dirs, ngăn cách bởi dấu phẩy} --specs {paths.specs_dir}
+```
+
+*`bin/` sống trong package npm, không được cài vào project — nên `npx` là đường duy nhất. Không có mạng / npx fail → **bỏ qua step này**, in `⚠️ Chưa lint được sổ trace (npx không khả dụng) — kết quả dưới đây chưa được kiểm cấu trúc` vào report, rồi tiếp Step 1. Đừng để nó chặn cả lệnh.*
+
+**Exit 0 → tiếp Step 1.**
+
+**Exit 1 → DỪNG NGAY.** Đừng nạp, đừng tính `status`, đừng ghi lại gì:
+
+```
+🔴 SỔ TRACE HỎNG — không phán trạng thái trên dữ liệu này.
+
+{nguyên văn output của lint-trace}
+
+Vì sao dừng thay vì cố đọc tiếp: Step 3 tính lại `status` rồi Step 6 GHI NGƯỢC
+vào TSV. Chạy tiếp trên một row đã lệch cột sẽ nướng cái lệch đó vào sổ vĩnh viễn —
+và sổ trace là dữ liệu KHÔNG regenerate được.
+
+Sửa:
+  1. Xem lần ghi nào làm hỏng : git log -p {file}
+  2. Sửa file (thường là thêm/bớt một dấu tab, hoặc giữ cả hai row sau merge)
+  3. Kiểm lại               : npx @educa-corp/sdd-framework --lint-trace
+  4. Rồi chạy lại /validate-traces
+```
+
+> **Vì sao step này tồn tại (G38):** `bin/self-check.js` canh **contract** — nó đọc file lệnh
+> và kiểm "lệnh có gọi đúng tên cột không". Nó không bao giờ mở một `.tsv` thật. Trong khi sổ
+> 24 cột được ghi **bằng tay**, hàng chục lần mỗi feature. Một dấu tab thiếu ở ô 17 dồn mọi ô
+> sau đó sang trái một bậc — ô 21 `status` nhận một ngày tháng — và **trước step này không gì
+> báo lỗi**: lệnh đọc tiếp, in ra số, số chảy vào `trace-report.json` rồi vào dashboard.
+
+---
+
 ### Step 1 — Nạp dữ liệu TSV
 
 **Umbrella mode:** đọc tất cả file `{trace_dir}/**/*.tsv` từ mọi dir trong `all_trace_dirs`. Với mỗi TSV, gắn tag row với tên service gốc.
@@ -303,6 +344,19 @@ by_service       = map {service → {total_scs, coded_scs, tested_scs, drift_cou
                    # Trả lời câu số MỘT của dự án nhiều đội: "đội nào còn bao nhiêu việc".
                    # Trước khi có cột 23, trace gộp (spec_source) KHÔNG mang thông tin sở hữu ở
                    # cấp row nên câu này không trả lời được. Bỏ qua map này ở single-service.
+by_platform      = map {platform → {total_scs, coded_scs, tested_scs, drift_count}} — gom theo
+                   platform (lấy từ TÊN FILE sổ `{UC-ID}-{platform}.tsv`, cùng nguồn với field
+                   `platform` của mỗi scenario ở Step 8)
+                   # CHỈ tạo ô cho platform THỰC SỰ có scenario — dự án chỉ có `web` thì chỉ một ô.
+                   # Trả lời "web xong bao nhiêu %, system xong bao nhiêu %" — câu thường ngày khi
+                   # làm FE và BE song song. Trước đó KHÔNG trả lời được từ `summary`: `by_service`
+                   # là bảng chia nhóm DUY NHẤT, mà cột `service` là `—` ở mọi row của dự án
+                   # single-service ⇒ nó gộp tất cả vào MỘT ô, và platform hoàn toàn vô hình.
+                   # Đây là hình dạng của G33: dữ liệu có ở cấp row (G48 vừa thêm `platform` vào
+                   # từng scenario) nhưng KHÔNG có ô tổng ⇒ dashboard chỉ đọc `summary` thì mù.
+                   # Bắt dashboard tự duyệt prds[].ucs[].scenarios[] mà cộng lại chính là cái bẫy
+                   # G33 đã chỉ ra: người viết dashboard đọc `summary`, thấy đủ, rồi tưởng xong.
+                   # KHÔNG thay `by_service` — hai TRỤC khác nhau, cùng hữu ích ở umbrella nhiều đội.
 seam_unwired_count = số seam bị cờ SEAM_UNWIRED (hàng thật đã có nhưng consumer còn wire vào stub — Step 5b)
 seam_pending_count = số seam bị cờ SEAM_PENDING (owner UC chưa gen — ⓘ chưa phải lỗi; PM dùng để xếp thứ tự gen)
 stub_unresolved_count = số stub bị cờ STUB_UNRESOLVED (method còn trắng dù owner đã gen / có hàm song song — Step 5b)
@@ -396,6 +450,11 @@ Schema:
       "<service path, e.g. user-service>": {
         "total_scs": 0, "coded_scs": 0, "tested_scs": 0, "drift_count": 0
       }
+    },
+    "by_platform": {
+      "<web | app | system — CHỈ platform thực sự có scenario>": {
+        "total_scs": 0, "coded_scs": 0, "tested_scs": 0, "drift_count": 0
+      }
     }
   },
   "prds": [
@@ -415,6 +474,7 @@ Schema:
           "scenarios": [
             {
               "sc_id": "<e.g. PAY-UC01-SC1>",
+              "platform": "web | app | system",
               "sc_title": "<title>",
               "spec_ver": "<current version from .feature>",
               "gen_ver": "<version at codegen time>",
@@ -596,6 +656,11 @@ Schema:
 ```
 
 **Rules:**
+- **`by_platform` là bắt buộc** (nếu có ít nhất một scenario). Cùng hình dạng `by_service`, khoá **động** — một ô cho mỗi platform tìm thấy, không phải một ô cố định cho mỗi giá trị vocabulary. Thêm platform thứ tư vào vocabulary thì nó tự có ô, không cần sửa gì ở đây.
+  > Đây là lý do `by_platform` **không cần** một rule `self-check` riêng: khác cờ audit (mỗi cờ cần một counter mang tên riêng, nên R7 phải canh từng cái), ở đây không có gì để lệch.
+- **`platform` (bắt buộc, mỗi scenario):** lấy từ **tên file sổ** `{UC-ID}-{platform}.tsv` — Step 2 đã đọc nó để tìm đúng `.feature`. Giá trị: `web` | `app` | `system`.
+  > **Vì sao bắt buộc (G48):** `sc_id` **một mình không định danh được** một scenario. Chính Step 2 phát biểu điều đó: *"sc_id trùng số giữa các platform là 2 scenario khác nhau"*. Sổ TSV giải quyết bằng tên file; JSON thì làm phẳng mọi platform vào chung một cây `scenarios[]`, nên thiếu field này thì `AUTH-UC1-SC1` của web và của app **không phân biệt được** — panel hiện trùng lặp hoặc đè nhau, và không ai trả lời được *"SC1 của app xong chưa"*.
+  > Bất đối xứng cũ: `issues.orphaned[]` và `issues.fe_techdoc_drift[]` **đã** mang `platform`; chỉ cây dữ liệu chính là không.
 - `implemented_by`: dùng `null` (không phải `"—"`) trong JSON khi không có giá trị
 - `test_count`: dùng integer `0` (không phải `"—"`) khi không có test
 - `test_classes`: dùng `[]` (không phải `"—"`) khi không có test class
@@ -671,11 +736,12 @@ mỗi scenario row mang service sở hữu ở **cột `service`** (cột 23, do
 
 **Rotate:** file vượt **2000 dòng** → đổi tên thành `trace-history.{YYYY-MM}.jsonl` rồi bắt đầu file mới. Đừng xoá.
 
-**Bốn ràng buộc — đây là phần dễ làm sai:**
+**Năm ràng buộc — đây là phần dễ làm sai:**
 
 | Ràng buộc | Vì sao |
 |---|---|
 | Ghi **CHỈ** vào `{paths.trace_dir}` (nơi authoritative). **KHÔNG** copy sang `{panel_mirror}` hay `{living_docs_dir}` | Nó là dữ liệu tích luỹ, không phải thứ regenerate được. Nhân bản nó ra chỗ sinh-ra là tạo hai lịch sử lệch nhau. |
+| Dòng vừa append **PHẢI kết thúc bằng newline** — file không bao giờ được kết thúc giữa dòng | File này là append-only và được merge bằng `merge=union` (xem `{paths.trace_dir}/.gitattributes`). Thiếu newline cuối thì lần append sau — hoặc một lần union merge — **nối hai bản ghi JSON thành một dòng**, và dòng đó không parse được. `--lint-trace` T8 bắt, nhưng đây là ca phòng được bằng một ký tự. |
 | File này **PHẢI được commit** cùng TSV | Nó là **dữ liệu**, không phải mirror. Regenerate lại không được — mất là mất vĩnh viễn. ⚠️ Đừng để nó dính vào luật gitignore của `.living-docs/` hay panel mirror; hai cái đó là bản sinh ra, cái này thì không. |
 | **Không đụng** TSV và `trace-report.json` | TSV là bảng **trạng thái** — giữ nó phẳng. Lịch sử là file riêng, format riêng, vòng đời riêng. `trace-report.json` là contract với panel VS Code. |
 | **Không lệnh nào được ra quyết định dựa trên file này** | Nó để **quan sát**, không phải để gác cổng. Một cái cổng phụ thuộc file có thể bị xoá là cổng dở. Cổng chặn PR vẫn chỉ là 4 cờ 🔴. |

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.5.0
+0.6.0

package/core/README.md

@@ -29,6 +29,26 @@ Từ v0.4.2, `--init` **phát hiện và cứu** các file đó:
 - Danh sách file bị ghi đè được in ra ngay sau bước cài
 - `.agent/.install-manifest.json` ghi hash của đúng những gì lần cài trước đã ghi — nhờ đó lệnh phân biệt được **bạn sửa file** với **framework tự đổi file giữa hai version** (một phép so nội dung thuần sẽ flag cả hai, và mỗi lần nâng cấp lại báo oan hàng chục file)
 
+## Nâng cấp cũng GỠ file, không chỉ thêm
+
+Từ v0.5.1, `--init` gỡ những file framework **không còn ship** — trước đó nó chỉ copy, nên một
+lệnh bị bỏ ở version mới nằm lại trong `.agent/commands/` và `.claude/commands/` **vĩnh viễn**:
+vẫn hiện trong menu `/`, vẫn chạy được, vẫn mang logic version cũ, kể cả khi framework đã bỏ nó
+*vì nó sai*.
+
+Một file chỉ bị gỡ khi **cả ba** đúng:
+
+1. có trong manifest lần cài trước → do framework đặt vào, không phải bạn tạo
+2. không còn trong bản mới → framework đã bỏ
+3. hash khớp manifest → **còn nguyên bản**, gỡ đi không mất gì
+
+Đúng (1)+(2) mà **bạn đã sửa** file đó → **giữ lại** + backup + báo ra. Thà để lại một file lạc
+còn hơn xoá thứ ai đó đã bỏ công viết.
+
+`.claude/commands/` cũng được quản như vậy — cộng thêm: nếu project bạn **đã có sẵn** một slash
+command trùng tên (`/debug`, `/sync`, `/learn` là những cái hay trùng), bản cũ của nó được backup
+vào `.agent/.overwritten-{YYYYMMDD}-shortcuts/` và bạn được báo, thay vì bị đè im lặng.
+
 Nên thêm vào `.gitignore` của project:
 
 ```gitignore