@educa-corp/sdd-framework 0.9.5 → 0.9.6

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.9.5
+0.9.6

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

@@ -7,6 +7,11 @@
 > **dev self-test** để QC thấy dev đã tự chạy check của mình.
 
 ## Gate
+
+*Checkpoint: **chặn CỨNG** — ghi đè file test đã có → XOÁ bản sửa tay của dev (mock, fixture, expectation đã chỉnh) mà chính `/dev-run-test` bảo họ làm. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
+
+*Mức cứng chỉ áp khi file test **đã tồn tại**. Lần sinh đầu đi thẳng. Xem §Chạy lại.*
+
 # Gate — Quy trình vào chuẩn cho mọi lệnh
 
 Mọi lệnh PHẢI chạy gate này trước khi thực thi phần logic riêng của nó.
@@ -684,6 +689,63 @@ bên trong từng sub-agent.
 
 ---
 
+## Output — lệnh này ghi những gì, ở đâu
+
+| Ghi gì | Người sửa tay? |
+|---|:---:|
+| File **unit / integration / E2E test** theo layout của `{active_module}` | ✅ **có** — xem §Chạy lại |
+| Sổ trace: `test_count` · `test_classes` · `dev_selftest` | ❌ lệnh ghi |
+
+> **Vì sao mục này tồn tại** *(G84)*. Trước đó §Output chỉ khai `Trace: …tsv updated` — **không
+> khai file test nó ghi ra**. Một lệnh không khai mình ghi gì thì không ai nghĩ tới việc **bảo vệ
+> thứ nó ghi**. Đúng lỗi gốc của G77 ở lane QC. Cột *"người sửa tay?"* là câu hỏi mà
+> `bin/trace-schema.json` → `artifact_writers` ép mọi lệnh trả lời.
+
+## Chạy lại — file test đã tồn tại *(GIỮ phần đã có, sinh phần THIẾU)*
+
+**Dev SỬA TAY chính các file này.** `/dev-run-test` nói thẳng:
+
+> `:260` — *"Test fail → `/fix-bug {TICKET_ID}` (bug thật) hoặc **fix test** (sai expectation)"*
+> `:137` — *"`TimeoutError` | Test gọi LLM endpoint live | **Thêm mock; kiểm tra test fixture**"*
+
+Nên chuỗi bình thường là **sinh → chạy → đỏ → dev sửa tay → chạy lại**, và lần sinh sau **không được**
+là lần xoá.
+
+| Tình huống | Xử lý |
+|---|---|
+| File test đã có, `.feature` **không đổi** | **Không sinh lại.** Không hỏi gì — ca thường nhất |
+| `.feature` có SC **mới** | Sinh **chỉ** test cho SC mới; giữ nguyên file/class đã có |
+| File test có **thay đổi chưa commit** | **DỪNG** — xem dưới |
+
+**Nhận diện "đã sửa tay" bằng `git status` / `git diff`** trên các đường dẫn ở §Output. Không cần ai
+đánh dấu gì, và nó bắt được **mọi** lần sửa — kể cả lần người sửa quên đánh dấu.
+
+```
+❌ {n} file test có thay đổi chưa commit — có thể là bản sửa tay của bạn
+   (mock, fixture, expectation đã chỉnh).  Sinh lại sẽ XOÁ chúng.
+   Files: {danh sách}
+   Cách đúng: commit bản sửa trước, rồi chạy lại.
+   Cố ý bỏ hết và sinh từ trắng: thêm --force
+```
+
+**KHÔNG đoán.** Thấy thay đổi chưa commit thì lệnh **không tự phân biệt** *"dev vừa sửa"* với *"lần
+sinh trước chưa commit"* — hai ca đó nhìn giống hệt nhau trên `git status`. **Dừng oan một lần rẻ
+hơn xoá nhầm một lần.**
+
+> **Vì sao mặc định là "sinh phần thiếu" chứ không phải "đừng sinh".** `/qc-run-test` (G77) có vòng
+> đời **chạy nhiều / sinh ít** nên mặc định của nó là *"CHẠY, đừng sinh lại"*. Lệnh này **chỉ sinh**,
+> không chạy gì — copy nguyên mặc định đó sang là **copy nhầm ngữ cảnh**. *Cùng khuôn không có nghĩa
+> là cùng thuốc.*
+>
+> **Vì sao ca "không đổi gì" phải HOÀN TOÀN im lặng.** Sinh lại test là việc làm mỗi lần spec đổi.
+> Bản vá nào làm nó hỏi mỗi lần thì người dùng sẽ thêm `--force` vào alias — và lúc đó mất sạch lớp
+> bảo vệ này.
+
+Có `--force` → report **bắt buộc** khai:
+```
+⚠️ --force: sinh lại từ trắng — đã xoá {n} file test có thay đổi chưa commit: {danh sách}
+```
+
 ## Output
 
 **Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·

package/core/commands/generate-code.md

@@ -657,7 +657,7 @@ DTOs → Entity/Model → Repository → Service interface → Service impl →
 
 Mỗi element **có action** (button, input, link, select, toggle, form-submit) PHẢI mang một **test-id ổn định** để QC định vị trực tiếp (không scan runtime):
 
-1. **Nguồn id — bảng §4.5.6 là HỢP ĐỒNG, không phải gợi ý.** Đọc **§4.5.6 Test Selectors** cho platform này ở tech-doc gộp `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md`, lọc theo cột "Phục vụ SC" khớp SC của UC này, rồi lấy id **nguyên văn**. Bảng do `/map-testids` ghi ở phase Tech Design — **trước** lệnh này.
+1. **Nguồn id — bảng §4.5.6 là HỢP ĐỒNG, không phải gợi ý.** Đọc **§4.5.6 Test Selectors** cho platform này ở tech-doc gộp `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md`, lọc theo cột "Serves SC" khớp SC của UC này, rồi lấy id **nguyên văn**. Bảng do `/map-testids` ghi ở phase Tech Design — **trước** lệnh này.
 
    **Bảng rỗng hoặc không có row nào cho SC của UC này** → *không tự sinh id rồi đi tiếp*. Cảnh báo rồi **để người quyết**:
 

package/core/commands/generate-tech-docs.md

@@ -614,7 +614,7 @@ sở hữu (DB) vs lấy live (API ngoài), và thao tác ghi chính.}
          trong CÙNG nhóm platform (không bao giờ tạo nhóm 4.5 thứ hai cho cùng platform).
        • §4.5.2–§4.5.5 — tương tự theo màn hình/UC ở chỗ chúng khác nhau.
        • §4.5.6 Test Selectors — MỘT bảng dùng chung cho cả nhóm platform; cột
-         "Phục vụ SC" mang (UC · SC) để consumer per-UC lọc row của mình.
+         "Serves SC" mang (UC · SC) để consumer per-UC lọc row của mình.
      Append: platform mới → nhóm "### 4.5 — {platform}" mới; màn hình/UC mới trong
      platform đã có → thêm sub-block + row vào §4.5.6 (đừng lặp nhóm).
      Bỏ hẳn §4.5 với PRD backend-only. -->
@@ -670,11 +670,11 @@ sở hữu (DB) vs lấy live (API ngoài), và thao tác ghi chính.}
      iOS accessibilityIdentifier. Dùng lại CÙNG giá trị id trên web/app cho cùng một
      element logic.
      MỘT bảng dùng chung cho cả nhóm platform (phủ mọi màn hình/UC của platform này).
-     Cột "Phục vụ SC" mang (UC · SC) để consumer per-UC (generate-code / qc) lọc row
+     Cột "Serves SC" mang (UC · SC) để consumer per-UC (generate-code / qc) lọc row
      của mình qua §10. Nhóm §4.5 này vốn đã theo platform, nên platform là ngầm định
      (khối web → web · SC). -->
 
-| Test-ID | Element | Component (§4.5.1.x) | Action | Phục vụ SC (UC · SC) |
+| Test-ID | Element | Component (§4.5.1.x) | Action | Serves SC (UC · SC) |
 |---------|---------|----------------------|--------|---------------------|
 | `{uc}-{screen}-{element}-{type}` | {Nút submit} | {Component} | {submit} | {UC1 · SC1, UC1 · SC3} |
 

package/core/commands/map-testids.md

@@ -26,15 +26,25 @@ patch, mọi element đều là `new`. Chỉ chạy Step 1 → 2 → 5.
 >
 > ```
 > /review-tech-docs (APPROVED)
->         ├──→ /generate-code      FE gắn attribute theo hợp đồng
->         └──→ /qc-design-test     QC viết test case + script theo CÙNG hợp đồng
+>         ├──→ /generate-code                              FE gắn attribute theo hợp đồng
+>         └──→ /qc-analyze → /qc-plan → /qc-design-test    QC viết test case theo CÙNG hợp đồng
 > ```
 >
+> **Cửa vào làn QC là `/qc-analyze`, KHÔNG phải `/qc-design-test`.** Trạm 3 tiêu thụ output của
+> trạm 1–2 (`REQUIREMENT_ANALYSIS.md` · `DOC_GAP.md` · `TEST_PLAN.md`); trỏ thẳng vào nó là chỉ
+> người ta nhảy vào giữa dây chuyền. Cả ba trạm đầu **không cần code**, nên nhánh QC vẫn song song
+> trọn vẹn với `/generate-code` — chỉ trạm 5 `/qc-run-test` mới cần code chạy được.
+>
 > Hai nhánh **không chờ nhau** vì cùng đọc một bản đã đóng băng, không đọc output của nhau.
 > Chạy sau code thì QC phải xếp hàng, và `/generate-code` không có gì để đọc nên sẽ tự sinh id
 > — hợp đồng thành thứ do code quyết định.
 
 ## Gate
+
+*Checkpoint: **chặn CỨNG** — ghi đè §4.5.6 đã có → ĐỔI id hợp đồng mà SA viết tay, và kéo theo Step 5b hạ `qc_status` + bump `tech_doc_revision` cho một hợp đồng **chưa hỏng**. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
+
+*Mức cứng chỉ áp khi §4.5.6 **đã có row**. Tech-doc chưa có bảng — brownfield thật, ca lệnh này **sinh ra để phục vụ** — đi thẳng, không CHECKPOINT cứng. Xem Step 2 §Bảng đã có id.*
+
 # Gate — Quy trình vào chuẩn cho mọi lệnh
 
 Mọi lệnh PHẢI chạy gate này trước khi thực thi phần logic riêng của nó.
@@ -188,7 +198,7 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
   🔴/⚠️ (không chặn ≠ không báo — người đọc log sau này vẫn cần thấy).
 
 
-*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. Đọc `.feature` FE của UC (web/app), các màn Design Spec của nó, tech-doc gộp `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` (§4.5.6 của platform, nếu có — bảng này gộp mọi UC của platform, **lọc theo cột "Phục vụ SC" khớp SC của UC này** qua §10), và figma-components catalog cho `active_module`.*
+*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID. Đọc `.feature` FE của UC (web/app), các màn Design Spec của nó, tech-doc gộp `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` (§4.5.6 của platform, nếu có — bảng này gộp mọi UC của platform, **lọc theo cột "Serves SC" khớp SC của UC này** qua §10), và figma-components catalog cho `active_module`.*
 
 ## Context
 **BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,
@@ -228,6 +238,47 @@ file tối thiểu) thì ghi tên component.
 - **Reused:** id được áp ở **usage site** (không bake vào component dùng chung) → gán theo cùng quy ước.
 - **Cross-platform:** nếu §4.5.6 của platform **kia** (block `web`/`app` trong cùng tech-doc gộp) đã có id cho cùng element logic, **dùng lại id value đó** (chỉ attribute khác theo platform) để web và app nhất quán và logic QC tái dùng được.
 
+### Bảng §4.5.6 ĐÃ CÓ id cho element này → **DÙNG LẠI AS-IS** *(G83)*
+
+Đối xứng với luật *reverse-document* cho code ở gạch đầu tiên. Chỉ gán id mới cho element **chưa có
+row**. Quy ước `{uc-lower}-{screen}-{element}-{type}` là **mặc định cho id MỚI** — **không** phải
+chuẩn để chuẩn-hoá lại id đã có.
+
+| Tình huống | Xử lý |
+|---|---|
+| Element **đã có row** trong §4.5.6 | **Giữ nguyên id**. Cập nhật cột `Element`/`Component`/`Action` nếu thật sự đổi; **không đụng cột Test-ID** |
+| Element **chưa có row** | Gán theo quy ước, thêm row mới |
+| Row trong bảng mà element **không còn** trong design-spec/BDD | **Không xoá** — nêu ở report để người quyết *(có thể đang phục vụ UC khác)* |
+
+> **Vì sao as-is chứ không chuẩn hoá.** Bảng là **HỢP ĐỒNG**, không phải output của lệnh này. Chuẩn
+> hoá một hợp đồng mà **cả FE lẫn QC đang bám vào**, chỉ vì tên không theo ý lệnh, là đổi hợp đồng
+> **mà không ai yêu cầu** — rồi Step 5b trung thành hạ `qc_status` và bump revision cho một thứ chưa
+> hỏng gì.
+>
+> **Đây là lỗ hổng lâu nhất của lệnh này** *(G83)*. Luật *"đã có test-id → dùng lại as-is"* vốn đã có
+> ở gạch đầu — nhưng **chỉ cho CODE**. Vế cho BẢNG bị thiếu, trong khi bảng mới là hợp đồng còn code
+> là bên phải tuân theo nó. Đo trên dự án thật: **28/28 tech-doc** có §4.5.6 **viết tay**, quy ước
+> riêng (`uc{n}-z2-region` · `uc1-z2-rank-avatar / uc1-z2-rank-name`) mà lệnh này không tái tạo được.
+
+### `--force` — đổi tên hàng loạt *(ca hợp lệ, nhưng phải nói ra)*
+
+Đổi convention toàn dự án là việc thật. Không có cờ → **DỪNG**:
+
+```
+❌ §4.5.6 của {TICKET-ID} ({platform}) đã có {n} id — giữ nguyên theo mặc định.
+   Muốn đặt lại tên toàn bộ theo quy ước framework: thêm --force
+   ⚠️ --force sẽ đổi {n} id mà FE đang gắn và QC đang bám:
+      · code FE trượt locator cho tới khi gắn lại  (lint T17/T18 sẽ kêu)
+      · .Test.md bám id cũ                          (lint T19 sẽ kêu)
+      · qc_status của mọi SC liên quan → not_run    (Step 5b)
+```
+
+Có `--force` → report **bắt buộc** khai:
+```
+⚠️ --force: đã đổi {n} id hợp đồng — {danh sách id cũ → mới}
+   Chạy lại: /generate-code (FE gắn id mới) · /qc-design-test {UC-ID} (TC bám id mới)
+```
+
 ## Step 3 — Đảm bảo component tái dùng forward được test-id (catalog) *(chỉ `--from-code`)*
 
 Với mỗi component **reused** có action, tra section **`## Test-ID Forwarding`** của catalog (`{paths.domain_knowledge_dir}/figma-components/{active_module}.md`):
@@ -254,14 +305,14 @@ Tạo hoặc cập nhật §4.5.6 (block platform tương ứng) trong tech-doc
 
 Mỗi row — **5 cột, đúng thứ tự của template** (`templates/tech-design.template.md` §4.5.6):
 
-`Test-ID | Element | Component | Action | Phục vụ SC (UC · SC)`
+`Test-ID | Element | Component | Action | Serves SC (UC · SC)`
 
 - **Component** — trỏ `§4.5.1.x` nếu §4.5.1 đã vẽ; chưa có (ca brownfield ghi file tối thiểu) thì ghi tên component.
-- **Phục vụ SC** — danh sách `(UC · SC)` mà id này phục vụ. Một id phục vụ nhiều UC là **bình thường**: tiền tố UC trong tên id chỉ nói UC nào giới thiệu element đó đầu tiên.
+- **Serves SC** — danh sách `(UC · SC)` mà id này phục vụ. Một id phục vụ nhiều UC là **bình thường**: tiền tố UC trong tên id chỉ nói UC nào giới thiệu element đó đầu tiên.
 
 > **KHÔNG ghi phân loại `reused`/`existing`/`new` vào bảng.** Nó là phân loại **lúc chạy** của Step 1 (dùng để rẽ nhánh Step 2–4), và nó **đổi theo thời gian** — một element `new` thành `existing` ngay khi dev viết code. Nhét dữ liệu biến thiên vào bảng hợp đồng là làm bảng sai dần mà không ai cập nhật.
 >
-> **Thứ tự cột là load-bearing:** `lint-trace` **T15** đọc cột "Phục vụ SC" theo **vị trí** (ô nội dung cuối cùng) để đối chiếu với `.feature`. Viết sai thứ tự là T15 đọc nhầm ô.
+> **Thứ tự cột là load-bearing:** `lint-trace` **T15** đọc cột "Serves SC" theo **vị trí** (ô nội dung cuối cùng) để đối chiếu với `.feature`. Viết sai thứ tự là T15 đọc nhầm ô.
 
 ## Step 5b — Làm mất hiệu lực `qc_status` của SC bị ảnh hưởng *(chỉ khi ĐỔI id đã có)*
 
@@ -274,13 +325,33 @@ lực ≠ ghi đè"*: *"lệnh nào làm giá trị đó HẾT ĐÚNG thì BẮT
 
 ```
 với mỗi id ĐỔI:
-  đọc cột "Phục vụ SC" của row đó   →  danh sách {UC-ID}-SC{N}
+  đọc cột "Serves SC" của row đó   →  danh sách {UC-ID}-SC{N}
   mở sổ {paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv
   với mỗi SC trong danh sách:
-      qc_status  →  not_run        (chỉ hạ từ `pass`/`fail`; đang `not_run`/`skip` thì để yên)
-      qc_run_at  →  —
+      qc_status          →  not_run    (chỉ hạ từ `pass`/`fail`; đang `not_run`/`skip` thì để yên)
+      qc_run_at          →  —
+      tech_doc_revision  →  @trace.revision MỚI của tech-doc   ← bump, xem dưới
 ```
 
+### Bump `tech_doc_revision` — vì sao lệnh này cũng là một bumper *(G64)*
+
+Tăng `@trace.revision` ở header tech-doc, rồi ghi số mới vào cột `tech_doc_revision` của **mọi row
+trong các sổ vừa chạm**.
+
+§4.5.6 là hợp đồng mà `/qc-design-test` **chép cứng giá trị id vào `.Test.md`** — một artifact **bền,
+nằm lại**. Cơ chế phát hiện lỗi thời của tầng artifact QC (`steps/qc-stamp.md`) hoạt động theo **nhãn**:
+`.Test.md` đóng dấu `tech_doc_revision`, trạm 4–5 so với hiện tại. **Sửa §4.5.6 mà không bump nhãn thì
+cơ chế đó không nổ** — đúng ca quan trọng nhất.
+
+> **Vì sao không dựa vào `Next` → `/review-tech-docs`.** Lệnh đó **có** bump (`:396` — set
+> `tech_doc_revision` cho mọi row). Nhưng đường ấy chỉ đúng **khi người dùng đi theo `Next`**, mà
+> Step 5b này tồn tại chính vì ca *"sửa nhanh một id rồi đi tiếp"*. Dựa vào `Next` là dựa vào **kỷ
+> luật**, không phải vào máy — và `rules/workflow.md` gọi chỗ này là **điểm mù tuyệt đối**: *"mọi
+> drift detector so **nhãn version**, không so **nội dung**"*. Không bump là tự tay đi vòng qua nhãn.
+>
+> **Thêm row MỚI thì KHÔNG bump** — cùng điều kiện với việc hạ `qc_status`: chưa `.Test.md` nào bám
+> id mới, không gì hết đúng.
+
 **KHÔNG đụng `qc_owner` và `qc_blocked_by`.** `rules/workflow.md` miễn trừ tường minh hai cột
 này: chúng là **con trỏ tới bug**, và đổi một test-id không làm con bug biến mất. Xoá đi là mất
 đường về bug đang mở.
@@ -289,10 +360,16 @@ này: chúng là **con trỏ tới bug**, và đổi một test-id không làm c
 
 In ra ở report:
 ```
-⚠️ {n} scenario có script QC bám id CŨ — qc_status hạ về not_run: {danh sách SC}
-   Chạy /qc-design-test (hoặc /qc-run-test) lại cho các UC đó.
+⚠️ {n} scenario có TC/script QC bám id CŨ — qc_status hạ về not_run: {danh sách SC}
+   tech_doc_revision bump → {rev mới} (để .Test.md lỗi thời bị phát hiện ở trạm 4-5)
+   Chạy /qc-design-test lại cho các UC đó.
 ```
 
+> **Chỉ `/qc-design-test`, KHÔNG phải "hoặc `/qc-run-test`"** *(G64 — lời nhắc cũ chỉ sai đường)*.
+> `/qc-run-test` dựng locator từ §4.5.6 **tươi** nên phần locator nó tự cứu — nhưng nó **không sửa**
+> id cũ đã nằm trong `.Test.md`. Ai chọn vế đó sẽ thấy test xanh trở lại và tưởng xong, trong khi tài
+> liệu test vẫn mô tả một element không còn mang id đó.
+
 > **Vì sao hạ chứ không giữ.** `rules/workflow.md`: *"`pass` **không** mang nghĩa 'test đã chạy
 > xanh' — nó mang nghĩa 'scenario này đã được nghiệm thu theo spec **hiện tại**'."* Một script
 > định vị bằng id không còn tồn tại thì không nghiệm thu được gì cả. Và QC biết phải chạy lại