@educa-corp/sdd-framework 0.9.3 → 0.9.5

package/bin/trace-schema.json

@@ -782,11 +782,12 @@
     {
       "n": 10,
       "name": "qc_status",
-      "$comment": "Chủ (ghi pass/fail/skip): qc-run-test — DUY NHẤT. Invalidator (chỉ hạ về not_run khi spec/code vừa đổi): generate-bdd · generate-code. Xem dev_selftest + rules/workflow.md 'Làm mất hiệu lực ≠ ghi đè'.",
+      "$comment": "Chủ (ghi pass/fail/skip): qc-run-test — DUY NHẤT. Invalidator (chỉ hạ về not_run khi spec/code/HỢP ĐỒNG TEST-ID vừa đổi): generate-bdd · generate-code · map-testids. Xem dev_selftest + rules/workflow.md 'Làm mất hiệu lực ≠ ghi đè'. map-testids vào danh sách này vì đổi một test-id trong §4.5.6 làm script QC bám id cũ HẾT ĐÚNG: nó định vị một element không còn mang id đó, nên `pass` cũ không còn nghĩa 'scenario đã được nghiệm thu theo spec hiện tại'. Cột 'Phục vụ SC' của row chính là chỉ mục ngược để biết SC nào bị ảnh hưởng.",
       "written_by": [
         "qc-run-test",
         "generate-bdd",
-        "generate-code"
+        "generate-code",
+        "map-testids"
       ],
       "read_by": [
         "validate-traces",
@@ -799,11 +800,12 @@
     {
       "n": 11,
       "name": "qc_run_at",
-      "$comment": "Chủ: qc-run-test. Invalidator (hạ về —): generate-bdd · generate-code. Xem qc_status.",
+      "$comment": "Chủ: qc-run-test. Invalidator (hạ về —): generate-bdd · generate-code · map-testids. Xem qc_status.",
       "written_by": [
         "qc-run-test",
         "generate-bdd",
-        "generate-code"
+        "generate-code",
+        "map-testids"
       ],
       "read_by": [
         "validate-traces",
@@ -1775,6 +1777,58 @@
       }
     ]
   },
+  "testid_contract": {
+    "$comment": [
+      "HỢP ĐỒNG TEST-ID FE↔QC — phần được MÁY canh.",
+      "",
+      "Contract gồm hai nửa, ở hai chỗ khác nhau trong CÙNG một tech-doc:",
+      "  @trace.testid_attr  (header, scope file) → TÊN THUỘC TÍNH, MỘT giá trị cho cả doc",
+      "  bảng §4.5.6          (thân, theo nền)     → GIÁ TRỊ test-id từng element, N dòng",
+      "Consumer per-UC lọc row của mình qua cột 'Phục vụ SC (UC · SC)'.",
+      "",
+      "VÌ SAO CẦN CANH: trước khối này, bảng §4.5.6 được 3 lệnh ĐỌC (generate-code, qc-run-test,",
+      "qc-design-test) và 2 lệnh GHI (generate-tech-docs, map-testids) — mà 0 nơi kiểm. Luật chống",
+      "giẫm chân giữa hai người ghi là một CÂU VĂN XUÔI ở map-testids Step 5. Đây đúng hình dạng",
+      "đã gặp bốn lần trong loạt GAP: luật ĐÚNG, viết RÕ, và KHÔNG AI CANH (G1 · G28 · G41 · G55).",
+      "",
+      "PHẠM VI NEO VÀO SỰ TỒN TẠI CỦA HỢP ĐỒNG — điều khoản quan trọng nhất của khối này:",
+      "doc không có block §4.5 client thì KHÔNG kiểm gì. Dự án backend-only, hay dự án chưa từng",
+      "chạy /map-testids, phải im lặng hoàn toàn. Hai rule nói 'chỗ nào đã hứa thì phải giữ',",
+      "KHÔNG nói 'mọi chỗ đều phải có hợp đồng'. Thiếu điều khoản này thì mọi dự án đang chạy đỏ",
+      "ngay ngày nâng version, và việc đầu tiên người ta làm là thêm --warn-only vào CI.",
+      "",
+      "KHÔNG vào gate.blocking: đây là nợ cần thấy, không phải 'đang có cái sai' chặn PR.",
+      "Cùng nhóm với TECHDOC_DRIFT / BDD_DRIFT — 13/17 cờ audit hiện tại cũng không chặn."
+    ],
+    "artifact": "tech-design.md",
+    "header_field": "@trace.testid_attr",
+    "table_section": "4.5.6",
+    "serves_column": "Phục vụ SC",
+    "lint_rules": [
+      {
+        "rule": "T15",
+        "level": "error",
+        "why": "Row §4.5.6 trỏ tới SC không tồn tại trong .feature. Consumer per-UC LỌC theo cột 'Phục vụ SC' — trỏ vào SC đã bị gộp/xoá thì không khớp row nào, QC tưởng element không có test-id rồi đi dò DOM. Đây là phép so khớp chuỗi, không có chỗ cho suy luận, nên ERROR."
+      },
+      {
+        "rule": "T16",
+        "level": "error+warn",
+        "why": "Có §4.5 client mà header thiếu @trace.testid_attr → ERROR: QC sẽ đoán tên thuộc tính theo nền, và dự án dùng data-test/data-qa TRƯỢT 100% locator trong im lặng (test đỏ 'element not found' trông y hệt bug sản phẩm). Field còn ở dạng placeholder → WARN, không ERROR: tech-doc vừa sinh ra chưa chạy /map-testids là trạng thái HỢP LỆ trong quy trình, báo đỏ ở đó là bắt oan."
+      },
+      {
+        "rule": "T17",
+        "level": "warn",
+        "needs": "--code",
+        "why": "Id đã khai ở §4.5.6 mà KHÔNG có trong code: FE chưa gắn, gắn sai giá trị, hoặc element đã đổi lúc implement. QC sẽ trượt locator đúng ở những id đó. WARN chứ không ERROR vì id đoán từ thiết kế không sống sót 100% — dev có thể gộp/tách element lúc implement, và đó là nợ cần thấy chứ không phải cái sai chặn người."
+      },
+      {
+        "rule": "T18",
+        "level": "warn",
+        "needs": "--code",
+        "why": "Id nằm trong code mà không có trong §4.5.6 nào: ai đó gắn ngoài hợp đồng — thường là /generate-code chạy khi bảng rỗng (người dùng chọn 'vẫn sinh với id TẠM'), hoặc sửa tay. Đây là lưới bắt phía sau cho quyết định đó: hợp đồng không còn đủ, và QC không biết những id này tồn tại. Chính vì có T18 mà /generate-code được phép hỏi rồi đi tiếp thay vì chặn cứng."
+      }
+    ]
+  },
   "strict_use_check": {
     "$comment": [
       "R3 CANH 'CÓ NHẮC TÊN', KHÔNG CANH 'CÓ DÙNG'. Khối này siết đúng những field mà trả lời",

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.9.3
+0.9.5

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 "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.
+
+   **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

package/core/commands/map-testids.md

@@ -8,7 +8,31 @@
 > 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-design-test     QC viết test case + script theo CÙNG hợp đồng
+> ```
+>
+> 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
 # Gate — Quy trình vào chuẩn cho mọi lệnh
@@ -164,7 +188,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 "Serves 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 "Phục vụ 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 đó**,
@@ -188,8 +212,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 +228,7 @@ 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)
+## 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 +238,66 @@ 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 | Phục vụ 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.
+
+> **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 ô.
+
+## 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 "Phục vụ 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  →  —
+```
+
+**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ó 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 đó.
+```
+
+> **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