@educa-corp/sdd-framework 0.9.4 → 0.9.6

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.9.4
+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-bdd.md

@@ -653,6 +653,7 @@ Với mỗi UC, ghi vào path trên và set `# @trace.platform: {active_platform
 # @trace.prd_version: {đọc từ metadata PRD "| **Version** |"}
 # @trace.bdd_version: {cấp FILE — 1.0 nếu gen mới; tăng 0.1 khi gen lại. Khác @trace.sc_version (cấp từng SC) bên dưới}
 # @trace.business_rules: {TICKET-ID}-UC{N}-BR{m}, {TICKET-ID}-UC{N}-BR{m+1}   ← {m} lấy NGUYÊN từ PRD §3: BR đánh số LIÊN TỤC toàn PRD, KHÔNG reset theo UC
+# @trace.api_source: existing   ← CÓ ĐIỀU KIỆN: chỉ giữ dòng này khi @trace.platform=system VÀ PRD Metadata có "| **API Source** | existing |". Mọi ca khác (greenfield · web · app) → XOÁ HẲN DÒNG NÀY; đừng để trống, đừng ghi "—". Vắng là ĐÚNG (review-context Nhóm C)
 # @trace.dataset: {domain}.testdata.yaml
 # ============================================================
 

package/core/commands/generate-code.md

@@ -657,8 +657,45 @@ 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.** Nếu tech-doc gộp `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` có **§4.5.6 Test Selectors** cho platform này, lấy id **nguyên văn** từ bảng đó (contract). Nếu chưa có (vd `--phase=ui` trước khi §4.5 được vẽ), **sinh id theo quy ước** `{uc-lower}-{screen}-{element}-{type}` (vd `ft001-login-submit-btn`) để QC vẫn có handle ổn định — chúng sẽ được đối chiếu với §4.5.6 của tech-design lúc integration.
-2. **Emit qua attribute platform** — chọn attribute theo **`active_module`** (bảng dưới, mặc định). Chỉ override khi header `.feature` khai tường minh `@trace.testid_attr={attr}` (hiếm; dùng cho stack lai). Không có khai báo → theo module:
+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**:
+
+   ```
+   ⚠️  §4.5.6 Test Selectors RỖNG cho {platform} của {TICKET-ID} — chưa có hợp đồng test-id.
+
+       Sinh code bây giờ nghĩa là mỗi id ở đây là id TẠM do lệnh này tự đặt:
+         · QC chưa bám vào được (họ đọc §4.5.6, không đọc code)
+         · /map-testids sau này phải đối chiếu lại, và có thể phải SỬA CODE nếu lệch
+         · lint-trace T18 sẽ báo "code có test-id mà bảng không có"
+
+       Cách đúng: dừng ở đây → /map-testids {UC-ID} → /review-tech-docs → chạy lại lệnh này.
+
+       Vẫn sinh code bây giờ với id tạm theo quy ước {uc-lower}-{screen}-{element}-{type}? (Y/N)
+   ```
+
+   - **N** → dừng, không sinh gì.
+   - **Y** → sinh id theo quy ước, **và report cuối phải ghi rõ**: `⚠️ {n} test-id TẠM (chưa vào §4.5.6) — chạy /map-testids {UC-ID} để đưa vào hợp đồng`.
+   - **`--yes` (headless)** → coi như **Y**, nhưng dòng cảnh báo ở report là **bắt buộc**. Không được im lặng: `lint-trace --code` T18 là lưới bắt phía sau, và nó chỉ có nghĩa khi người ta biết có gì để tìm.
+
+   > **Vì sao hỏi chứ không tự sinh như trước.** Tự sinh rồi *"đối chiếu lúc integration"* nghe hợp lý nhưng thực tế là **code quyết định hợp đồng**: QC đọc §4.5.6 thấy rỗng nên đi dò DOM, còn FE đã gắn một bộ id không ai biết. Đến lúc đối chiếu thì cả hai bên đều đã làm xong theo hai hướng khác nhau. Hỏi ở đây là đặt quyết định đó vào tay người, **đúng lúc nó còn rẻ**.
+2. **TÊN THUỘC TÍNH: đọc `@trace.testid_attr` từ header tech-doc gộp — KHÔNG tự suy từ module.** Đây là **nửa FE của contract FE↔QC**: `/qc-run-test` đọc **chính field này** để cấu hình locator, và `bin/trace-schema.json` khai `artifact: tech-design.md` (`written_by: map-testids`). Hai bên phải đọc **cùng một bản** — nếu FE suy từ module còn QC đọc tech-doc thì FE gắn một kiểu, QC tìm một kiểu, và **không trùng một element nào**.
+
+   | Đọc được gì | Làm gì |
+   |---|---|
+   | Header tech-doc có `@trace.testid_attr` | Dùng **nguyên văn** giá trị đó |
+   | **Không tìm thấy field** | **Cảnh báo mềm, KHÔNG im lặng hardcode** (khối dưới), rồi mới fallback theo `active_module` |
+   | Header `.feature` cũng khai và **LỆCH** với tech-doc | Ưu tiên tech-doc, nhưng **in cả hai giá trị** — không im lặng chọn một bên. `.feature` là lối cũ, chỉ còn cho stack lai |
+
+   Cảnh báo khi thiếu field (cùng khuôn `/qc-run-test` dùng, để hai nửa của contract nói cùng một giọng):
+   ```
+   ⚠️ Tech-doc thiếu @trace.testid_attr — fallback theo module ({attr mặc định}).
+      Nếu FE dùng thuộc tính khác thì MỌI locator của QC sẽ trượt, và test sẽ đỏ với
+      "element not found" — trông y hệt một bug sản phẩm, nên QC đi mở bug thay vì sửa selector.
+      Chạy /map-testids {UC-ID} để ghi field này.
+   ```
+
+   **Fallback theo `active_module`** (chỉ khi tech-doc không có field):
    - web (`react`/`nextjs`/`vue`/`angular`) → `data-testid="..."`
    - React Native → `testID="..."`
    - Flutter → `Key('...')` (+ `Semantics(identifier: '...')` khi action cần)

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

@@ -232,7 +232,7 @@ Kiểm tra `output_path` đã tồn tại chưa.
 
 - **Chưa tồn tại → chế độ FRESH.** Tạo doc từ template, chỉ điền (các) UC trong `input_features`. (Section của các UC không thuộc batch này giữ placeholder `{…}` / được thêm ở lần chạy sau.)
 - **Đã tồn tại → chế độ APPEND.** Doc là tăng dần — không bao giờ regenerate từ đầu (sẽ đè mất chỉnh tay và sign-off của reviewer). Đọc bảng **§10 UC Coverage** và **Changelog** hiện có → `covered_ucs`. Với mỗi UC trong `input_features`, phân loại:
-  - **UC mới** (không có trong `covered_ucs`) → **thêm** các section của nó: sequence diagram §5 mới **đúng lane platform** (5.A/5.B/5.C, đánh số sau cái cuối cùng hiện có *trong lane đó*); với §4.5 — nếu **platform** này mới với doc → nhóm `### 4.5 — {platform}` mới, ngược lại thêm sub-block `§4.5.1.x {Screen} — {UC}` + row vào §4.5.6 dùng chung của nhóm platform đó (đừng lặp nhóm); row mới ở §3/§4.3/§8/§9. Rồi cập nhật §10 (row khoá theo platform×SC) và thêm một row Changelog **theo format ở Bước 1b**.
+  - **UC mới** (không có trong `covered_ucs`) → **thêm** các section của nó: sequence diagram §5 mới **đúng lane platform** (5.A/5.B/5.C, đánh số sau cái cuối cùng hiện có *trong lane đó*); với §4.5 — nếu **platform** này mới với doc → nhóm `### 4.5 — {platform}` mới, ngược lại thêm sub-block `§4.5.1.x {Screen} — {UC}` (đừng lặp nhóm). **§4.5.6: chỉ tạo KHUNG bảng rỗng nếu chưa có — KHÔNG ghi row nào**, xem §Phân vai §4.5.6; row mới ở §3/§4.3/§8/§9. Rồi cập nhật §10 (row khoá theo platform×SC) và thêm một row Changelog **theo format ở Bước 1b**.
   - **UC đã phủ được trỏ lại** (có trong `covered_ucs`) → đây là refresh/mở rộng có chủ đích (vd tech lead giờ trỏ vào BDD `web/` của một UC mà backend đã thiết kế, hoặc BDD bump version). Xác nhận trước khi đụng nội dung có sẵn:
     ```
     ↻ {UC-ID} đã có trong {TICKET-ID}-tech-design.md.
@@ -378,7 +378,25 @@ Ghi/mở rộng `{output_path}` dùng template dưới đây, chỉ sinh **nội
 - **§1/§2** (Overview/Actors, Architecture) là cấp PRD: viết ở lần chạy đầu; các lần sau chỉ mở rộng nếu batch thêm actor/integration thật sự mới.
 - **§10 UC Coverage** — một row UC (có cột Platforms) + bảng con coverage-scenario khoá theo **(platform, SC)** — mỗi platform×SC một row, vì cùng số SC ở platform khác nhau là scenario khác nhau. Đây là mỏ neo mà chế độ APPEND đọc. Luôn cập nhật nó cho (các) UC/platform của batch.
 
-**Chế độ APPEND (doc đã tồn tại):** **đừng** viết lại section có sẵn. Chèn diagram §5 của UC batch **vào đúng lane platform** (5.A/5.B/5.C, đánh số sau cái cuối trong lane đó, tiêu đề `platform · SC`), các row mới ở §3/§4.3/§8/§9; với §4.5 — platform mới → nhóm `### 4.5 — {platform}` mới, ngược lại thêm sub-block `§4.5.1.x {Screen} — {UC}` + row vào §4.5.6 dùng chung của nhóm (không lặp nhóm); rồi cập nhật §10 (row khoá theo platform×SC) và thêm một row Changelog **theo format ở Bước 1b**. Bump `@trace.revision` và làm mới `@trace.ucs` / `@trace.platforms` ở header, và cập nhật entry của platform vừa đụng trong map `@trace.bdd_versions` (vd set `web=2.0`, giữ nguyên `system`).
+**Chế độ APPEND (doc đã tồn tại):** **đừng** viết lại section có sẵn. Chèn diagram §5 của UC batch **vào đúng lane platform** (5.A/5.B/5.C, đánh số sau cái cuối trong lane đó, tiêu đề `platform · SC`), các row mới ở §3/§4.3/§8/§9; với §4.5 — platform mới → nhóm `### 4.5 — {platform}` mới, ngược lại thêm sub-block `§4.5.1.x {Screen} — {UC}` (không lặp nhóm). **§4.5.6: chỉ khung rỗng, KHÔNG ghi row** — xem §Phân vai §4.5.6; rồi cập nhật §10 (row khoá theo platform×SC) và thêm một row Changelog **theo format ở Bước 1b**. Bump `@trace.revision` và làm mới `@trace.ucs` / `@trace.platforms` ở header, và cập nhật entry của platform vừa đụng trong map `@trace.bdd_versions` (vd set `web=2.0`, giữ nguyên `system`).
+
+## Phân vai §4.5.6 Test Selectors — lệnh này KHÔNG ghi row
+
+Bảng §4.5.6 là **hợp đồng test-id FE↔QC**, và nó có **đúng một người ghi**: `/map-testids`.
+Lệnh này chỉ:
+
+- tạo **khung bảng rỗng** (dòng tiêu đề + dòng phân cách) trong mỗi nhóm `### 4.5 — {platform}` client;
+- ghi `@trace.testid_attr` ở header dưới dạng **placeholder** (giá trị thật do `/map-testids` điền).
+
+> **Vì sao tách người ghi.** Trước đây cả hai lệnh cùng ghi bảng, và luật chống giẫm chân là một
+> câu văn xuôi. Quan trọng hơn: hợp đồng phải chốt **trước** `/generate-code`, để FE và QC cùng
+> đọc một bản đã đóng băng rồi **chạy song song**. Nếu lệnh này dự đoán id còn `/map-testids` sửa
+> lại sau khi code xong thì hợp đồng thành thứ **do code quyết định** — đúng cái nó sinh ra để
+> chống.
+>
+> **Next của lệnh này là `/map-testids`**, không phải `/review-tech-docs`. `/review-tech-docs`
+> sẽ **NEEDS_FIX** nếu có §4.5 client mà §4.5.6 rỗng (T6) — tech-doc có phần UI mà không khai
+> test selector thì chưa viết xong, như có §4 API mà không khai endpoint.
 
 <!--
   ════════════════════════════════════════════════════════════════════════════
@@ -422,6 +440,7 @@ Ghi/mở rộng `{output_path}` dùng template dưới đây, chỉ sinh **nội
 @trace.service: {service — từ header BDD @trace.service}
 @trace.module: {module liên quan — vd dotnet, angular}
 @trace.platforms: {system | web | app | webview | … — tuỳ thư mục BDD nào tồn tại}
+@trace.testid_attr: {TÊN THUỘC TÍNH chứa test-id của stack client — web `data-testid`|`data-test`|`data-qa` · React Native `testID` · Flutter `Key`/`Semantics(identifier:)` · native iOS `accessibilityIdentifier`. MỘT giá trị cho cả doc (khác GIÁ TRỊ test-id từng element — cái đó ở §4.5.6). Do `/map-testids` ghi. Để trống nếu doc chỉ phủ platform `system`.}
 @trace.bdd_versions: {MAP theo từng platform — số nhiều, KHÁC @trace.bdd_version (scalar) của .feature — vd system=1.5, web=1.9, app=1.7; chỉ platform có mặt. Mỗi feature mang bdd_version riêng; đừng gộp về một số.}
 @trace.api_source: {existing | —}
 @trace.revision: 1
@@ -595,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. -->
@@ -651,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

@@ -8,9 +8,43 @@
 > forwarding vào figma-components catalog, patch các usage site, và ghi map §4.5.6 — để QC
 > định vị element bằng id thay vì scan lúc runtime.
 
-Usage: `/map-testids {UC-ID}`
+Usage: `/map-testids {UC-ID}` · `/map-testids {UC-ID} --from-code`
+
+## Hai chế độ — chọn theo việc code đã có hay chưa
+
+| Chế độ | Khi nào | Nguồn element | Đụng code? | Ai chạy |
+|---|---|---|---|---|
+| **mặc định** (không cờ) | Feature mới — **chạy TRƯỚC `/generate-code`** | design-spec + step `When` của `.feature` | **Không** | Người viết tech-doc |
+| `--from-code` | Brownfield — màn đã có code từ trước framework | **đọc code thật** + design-spec + BDD | Có (patch attribute) | Dev · chạy **một lần** mỗi UC cũ |
+
+Chế độ mặc định **bỏ qua Step 3 và Step 4** (patch catalog / patch usage site): chưa có code để
+patch, mọi element đều là `new`. Chỉ chạy Step 1 → 2 → 5.
+
+> **Vì sao lệnh này chạy TRƯỚC `/generate-code`.** Nguyên liệu để **đặt tên** test-id có từ
+> trước code — Step 1 lấy element từ design-spec + step `When`, cả hai đều thuộc phase Tech
+> Design. Chốt hợp đồng ở đây rồi thì:
+>
+> ```
+> /review-tech-docs (APPROVED)
+>         ├──→ /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,8 +222,15 @@ Phân giải attribute test-id từ `@trace.testid_attr` (hoặc theo module): w
 
 Từ các step `When` trong `.feature` FE của UC + các màn Design Spec, liệt kê mọi element **có action** mà scenario chạm tới (button, input, link, select, toggle, form-submit). Bỏ qua text/label tĩnh. Với mỗi cái, phân giải component render và phân loại:
 - **reused** — khớp một row trong figma-components catalog (component design-system dùng chung);
-- **existing** — component riêng của feature đã có trong codebase (brownfield);
-- **new** — chưa code (để `/generate-code` lo; chỉ ghi lại id dự kiến).
+- **existing** — component riêng của feature đã có trong codebase (brownfield); *chỉ gặp ở `--from-code`*;
+- **new** — chưa code (để `/generate-code` lo; chỉ ghi lại id dự kiến). *Chế độ mặc định: **mọi** element đều là nhóm này.*
+
+Phân loại này là **nội bộ lúc chạy** — dùng để rẽ nhánh Step 2–4. **Không ghi vào bảng §4.5.6**
+(xem Step 5): nó đổi theo thời gian, một element `new` thành `existing` ngay khi dev viết code.
+
+**Cột `Component` của bảng** lấy từ **§4.5.1 Cây Component trong chính tech-doc này** (do
+`/generate-tech-docs` vẽ từ design-spec) — trỏ `§4.5.1.x`. §4.5.1 chưa có (ca `--from-code` ghi
+file tối thiểu) thì ghi tên component.
 
 ## Step 2 — Phân giải test-id ổn định cho mỗi element
 
@@ -197,7 +238,48 @@ Từ các step `When` trong `.feature` FE của UC + các màn Design Spec, li
 - **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.
 
-## Step 3 — Đảm bảo component tái dùng forward được test-id (catalog)
+### 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`):
 - **Đã ghi prop forwarding** → dùng nó ở usage site (Step 4).
@@ -207,17 +289,92 @@ Với mỗi component **reused** có action, tra section **`## Test-ID Forwardin
 
 In mọi row catalog được thêm và mọi component dùng chung được patch (chúng đụng code dùng chung — nêu ra để review).
 
-## Step 4 — Patch usage site (chỉ EXTEND)
+## Step 4 — Patch usage site (chỉ EXTEND) *(chỉ `--from-code`)*
 
 Với mỗi element có action trong các màn **existing/reused** của UC này, thêm test-id ở usage site — attribute thô cho element thường, hoặc prop forwarding cho component tái dùng — với id từ Step 2. **EXTEND mode:** chỉ đụng attribute/prop; không refactor gì khác. Bỏ qua element đã mang đúng id (idempotent).
 
 ## Step 5 — Ghi/làm mới map §4.5.6 Test Selectors
 
 Tạo hoặc cập nhật §4.5.6 (block platform tương ứng) trong tech-doc gộp `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md`:
-- Nếu tech-doc tồn tại → cập nhật bảng §4.5.6 của platform này (thêm block §4.5 cho platform nếu chưa có).
+- Nếu tech-doc tồn tại → **hai việc, không bỏ việc nào**:
+  - **(a) Header.** Đảm bảo khối `@trace` có `@trace.testid_attr` mang đúng giá trị đã phân giải ở Step 0. Thiếu hẳn, hoặc còn placeholder `{…}` → điền. **Đã có giá trị thật mà LỆCH với giá trị vừa phân giải → DỪNG, in cả hai giá trị và hỏi người dùng chọn**; không tự ghi đè.
+  - **(b) Bảng.** Cập nhật bảng §4.5.6 của platform này (thêm block §4.5 cho platform nếu chưa có).
 - Nếu **chưa** tồn tại (pure brownfield) → ghi một file tối thiểu: header `@trace` (gồm `@trace.testid_attr`) + §4.5.6. `/generate-tech-docs` điền các section còn lại sau; nó không được ghi đè các id §4.5.6 mà lệnh này đã ghi.
 
-Mỗi row: `Test-ID | Element | Component (reused/existing/new) | Action | Serves SC`.
+> **Vì sao (a) lệch thì DỪNG chứ không ghi đè.** `@trace.testid_attr` là *tên thuộc tính* mà **mọi** locator QC của PRD này bám vào (`/qc-run-test` đọc nó để cấu hình `get_by_test_id`). Ghi đè sai một lần là làm **trượt toàn bộ** script của PRD — và test sẽ đỏ với `element not found`, trông y hệt một bug sản phẩm, nên QC đi mở bug thay vì sửa selector. Lệch nghĩa là một trong hai đang sai: FE vừa đổi convention, hoặc `active_module` khai sai. Cả hai đều cần người nhìn, không đoán được từ đây.
+
+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 | 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.
+- **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 "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ó)*
+
+Chạy **chỉ khi** Step 5 làm đổi giá trị một test-id **đã tồn tại** trong bảng (thêm row mới
+không kích hoạt bước này — chưa có script nào bám id mới).
+
+Đổi một id nghĩa là mọi script QC bám id cũ **hết đúng**: nó đang định vị một element không còn
+mang id đó. Giữ `qc_status = pass` ở đó là **báo cáo sai** — `rules/workflow.md` §*"Làm mất hiệu
+lực ≠ ghi đè"*: *"lệnh nào làm giá trị đó HẾT ĐÚNG thì BẮT BUỘC hạ nó về giá trị 'chưa biết'"*.
+
+```
+với mỗi id ĐỔI:
+  đọ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          →  —
+      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ở.
+
+**Không có sổ trace cho SC đó** (chưa chạy `/generate-bdd`, hoặc SC mới) → bỏ qua, không tạo sổ.
+
+In ra ở report:
+```
+⚠️ {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
+> bằng đúng cách họ vẫn biết với mọi thay đổi spec khác: dashboard hiện SC đó `not_run` thay vì
+> `pass` — không phải học cơ chế mới nào.
 
 ## Step 6 — Handoff