@educa-corp/sdd-framework 0.6.0 → 0.7.1

package/{commands/extend-prd.md → core/commands/amend-prd.md}

@@ -1,23 +1,33 @@
-# /extend-prd — Thêm yêu cầu mới vào PRD đã duyệt
+# /amend-prd — Sửa tại chỗ một yêu cầu đã duyệt trong PRD
 
-> **Ranh giới với `/refine-prd` — đọc trước khi chọn lệnh:**
+> **Nhánh thứ tư — đọc bảng này trước khi chọn lệnh:**
 >
-> | Lệnh | Câu hỏi nó trả lời | Nguồn đầu vào |
+> | Tình huống | Lệnh | Thao tác ghi |
 > |---|---|---|
-> | `/refine-prd` | *"PRD hiện tại có **vấn đề** gì?"* | 3 lăng kính review soi nội dung ĐANG CÓ |
-> | **`/extend-prd`** | *"PRD hiện tại **thiếu** cái gì mới?"* | PO + hòm thư `prd-change-requests/` |
+> | PRD **chưa có** | `/generate-prd` | **Write** cả file |
+> | PRD đã có, **thêm** UC/AC/BR mới | `/extend-prd` | **Edit add-only** — output là superset chặt |
+> | PRD đã có, **sửa vấn đề review chỉ ra** | `/refine-prd` → Review Board → `--resume` | Edit trong phạm vi finding |
+> | **PRD đã có, PO muốn ĐỔI một yêu cầu đang đúng cú pháp** | **`/amend-prd`** | **Edit tại chỗ** — output **KHÔNG** phải superset |
 >
-> `/refine-prd` **không** thêm được UC/AC/BR mới — nó tự cấm ở Resume Mode Phase 2 (*"không thay đổi
-> bất kỳ section nào không được tham chiếu bởi một finding được chấp nhận"*), và findings của nó sinh
-> từ việc soi PRD hiện có nên **không có đường nào để một yêu cầu MỚI đi vào**.
+> **Vì sao phải là lệnh riêng (GAPS-v4 G54).** Ba lệnh kia đều **từ chối đúng việc này**:
+> `/generate-prd` **DỪNG HẲN** trên file đã có (§Guard: *"Tồn tại → DỪNG. KHÔNG ghi, KHÔNG hỏi
+> Y/N"* — vì ghi đè mất changelog, **đánh số lại BR**, phá `@trace.business_rules` trong mọi
+> `.feature` đã sinh, cả ba không hoàn tác được) · `/extend-prd` chỉ **add-only**, luật
+> Bước 5 §3 đòi output là *"superset chặt"* · `/refine-prd` tự cấm đụng section nào không được một
+> finding trỏ tới, và findings sinh từ việc soi PRD hiện có nên **không có đường nào để một ý định
+> MỚI của PO đi vào**.
 >
-> **Vì sao là lệnh riêng, không phải `/generate-prd --extend`:** hai chế độ ngược nhau về thao tác ghi
-> — `/generate-prd` **Write cả file**, lệnh này **chỉ Edit add-only**. Trộn vào một `.tmpl` chính là
-> hình dạng của G9 (một file, hai hành vi, người đọc chọn nhầm).
+> Trước lệnh này, hành vi hợp lý duy nhất còn lại là **mở file `.md` ra gõ** — và đó là con đường
+> DUY NHẤT framework không nhìn thấy: mọi drift detector so **nhãn version**, không so **nội dung**
+> (0 content hash trong toàn bộ codebase). Sửa tay không bump version ⇒ **0 cờ**, không 🔴 không 🟠
+> không ⓘ. Nên nhánh thiếu không phải một tiện ích còn nợ; nó là **điểm mù mà chính thiết kế tạo ra**.
+>
+> **`/validate-traces` canh cửa sau** bằng cờ `PRD_UNTRACKED_EDIT` (schema → `spec_edit_detection`):
+> nội dung PRD đổi mà `Version` không đổi ⇒ có người đi cửa sau. Cửa chính là lệnh này.
 
 ## Gate
 
-*Checkpoint: **chặn CỨNG** — sửa PRD đã DUYỆT. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
+*Checkpoint: **chặn CỨNG** — SỬA TẠI CHỖ một AC/BR/UC đã duyệt — thao tác ghi DUY NHẤT trong framework được phép làm output KHÔNG phải superset của bản cũ. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
 
 # Gate — Quy trình vào chuẩn cho mọi lệnh
 
@@ -172,7 +182,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à **file PRD đã tồn tại** `{TICKET-ID}-{prd-slug}.md` (file `.md` duy nhất ở gốc feature folder). Nếu `$ARGUMENTS` rỗng → liệt kê `{specs_dir}/*/*/*.md` và hỏi. **Không tìm thấy file PRD → DỪNG** và chỉ sang `/generate-prd` (feature mới thì đi từ discovery, không phải từ đây).*
+*Lưu ý: Với lệnh này, target ở Bước 1 là **file PRD đã tồn tại** `{TICKET-ID}-{prd-slug}.md` (file `.md` duy nhất ở gốc feature folder). `$ARGUMENTS` rỗng → liệt kê `{specs_dir}/*/*/*.md` và hỏi. **Không tìm thấy file PRD → DỪNG** và chỉ sang `/generate-prd`.*
 
 ## Context
 **BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,
@@ -184,7 +194,7 @@ placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
 
 ---
 
-## Ngôn ngữ nghiệp vụ *(áp cho mọi text mới: UC, AC, BR, Business Logic, Scope)*
+## Ngôn ngữ nghiệp vụ *(áp cho mọi text được sửa: AC, BR, Business Logic, Scope)*
 # Business Language Guard — chặn thuật ngữ kỹ thuật rò vào tài liệu nghiệp vụ
 
 Tài liệu nghiệp vụ (PRD, product-definition) mô tả **WHAT** — chỉ ngôn ngữ nghiệp vụ. Guard này chạy **mỗi khi viết hoặc sửa** prose (gen mới, áp fix `--resume`, hiệu chỉnh): **quét và xử lý** các thuật ngữ kỹ thuật/UI phổ thông bên dưới **trước khi ghi**.
@@ -245,190 +255,209 @@ Các từ như `cờ / flag`, `biến / trường / field`, `giá trị / value`
 
 ---
 
-## Bước 1 — Nạp trạng thái PRD hiện có
+## Bước 1 — Nạp PRD và **PO khai tường minh** cái cần sửa
 
 Đọc target PRD, trích và lưu:
 
 | Giá trị | Nguồn | Dùng để |
 |---|---|---|
-| `current_version` | Metadata `\| **Version** \|` | tính version mới ở Bước 6 |
-| `current_status` | Metadata `\| **Status** \|` | cảnh báo nếu đang `draft` (xem dưới) |
-| `max_uc` | số UC lớn nhất trong §3 | UC mới = `max_uc + 1` |
-| `max_br` | số BR lớn nhất **trên TOÀN PRD** | BR mới = `max_br + 1` |
-| `max_ac` | số AC lớn nhất trong §2 | AC mới = `max_ac + 1` |
-| `existing_ucs` | danh sách UC-ID + tên | phát hiện va chạm ở Bước 3 · báo "UC không đổi" ở Bước 7 |
+| `current_version` | Metadata `\| **Version** \|` | tính version mới ở Bước 5 |
+| `current_status` | Metadata `\| **Status** \|` | cảnh báo nếu chưa `approved` |
+| `existing_ucs` | danh sách UC-ID + tên | phân giải UC sở hữu · kiểm va chạm |
+| `all_br` | mọi BR-ID + nội dung, theo UC sở hữu (bảng BR ở §3) | phân giải `BR{n}` → UC |
+| `all_ac` | mọi AC-ID + nội dung, theo UC sở hữu (dòng `**AC liên quan:**`) | phân giải `AC{n}` → UC |
 | `changelog_rows` | bảng `# Change Log` | biết PRD đã đi qua những gì |
-| `api_source` | Metadata `API Source` | quyết có cần hỏi contract cho phần thêm không |
-| `bdd_generated` | glob `{specs_dir}/{domain}/{prd-slug}/bdd/*/{TICKET-ID}-UC*.feature` | **cảnh báo BR ID churn** + route ở Bước 7 |
-
-**Guard — PRD đang `draft`:** nếu `current_status != approved` → cảnh báo mềm, không chặn:
-```
-⚠️  PRD đang ở Status: {status} (chưa approved).
-    Thêm yêu cầu lên một PRD chưa chốt sẽ trộn hai việc: phần chưa duyệt + phần mới.
-    Cân nhắc hoàn tất review vòng hiện tại trước (/review-context → PO duyệt).
-    Vẫn thêm bây giờ? (Y/N)
-```
-
-**Guard — BDD đã sinh:** nếu `bdd_generated` không rỗng, hiện danh sách và nêu rõ hệ quả:
-```
-ℹ️  {n} file BDD đã sinh cho PRD này: {danh sách UC × platform}
-    Lệnh này CHỈ đánh số nối tiếp (UC{max_uc+1}, BR{max_br+1}) — KHÔNG bao giờ đánh lại
-    ID cũ, nên các liên kết @trace.business_rules hiện có KHÔNG bị ảnh hưởng.
-    Sau khi thêm: chỉ cần /generate-bdd cho UC MỚI; các UC cũ không phải gen lại
-    (/validate-traces sẽ xếp chúng vào ⓘ PRD_STALE_REF, không phải 🟠 PRD_DRIFT).
-```
+| `bdd_generated` | glob `{specs_dir}/{domain}/{prd-slug}/bdd/*/{TICKET-ID}-UC*.feature` | tính blast radius ở Bước 6 |
 
----
+### `amend_targets` — **BẮT BUỘC, không suy đoán**
 
-## Bước 2 — Nạp hòm thư `prd-change-requests/`
+PO phải nêu **chính xác ID** cần sửa. Đây là ràng buộc cứng nhất của lệnh: ID được khai
+**trở thành `{changelog_scope}`** ở Bước 5, và cũng là **danh sách duy nhất** mà guard sau-ghi ở
+Bước 4 cho phép nội dung thay đổi.
 
-*Đây là **consumer** mà hàng đợi này thiếu suốt từ đầu: `/propose-scenario` Case B ghi vào đó, `/sync` thông báo lúc-đến, `/validate-traces` Step 7b đếm và nhắc — nhưng **không lệnh nào drain**. Đây là chỗ đó.*
+Nhận `amend_targets` theo thứ tự:
 
-Quét `{paths.prd_change_requests_dir}/*.md` (mặc định `{spec_source}/feedback/prd-change-requests/`; **không** quét `archived/`). Thư mục vắng/rỗng → bỏ qua **im lặng**.
+1. Từ `$ARGUMENTS` nếu PO đã nêu (vd `/amend-prd PAY01 UC3-BR8`).
+2. Nếu không, **hỏi** — kèm danh sách để PO chọn, đừng để PO gõ mò:
+   ```
+   Sửa gì trong {TICKET-ID}? (nhập ID, cách nhau bằng dấu phẩy)
 
-Lọc theo PRD này: khớp `{TICKET-ID}` trong tên file hoặc field `UC / Ticket` của metadata request.
+   UC3 "Xuất báo cáo"
+     BR8   tối đa 5 file mỗi lần
+     BR9   chỉ xuất được đơn đã duyệt
+     AC5   người dùng xuất được nhiều đơn trong một lần
+   UC4 …
+   ```
+3. **KHÔNG tự suy** target từ một mô tả mơ hồ (*"sửa cái giới hạn file ấy"*). Trình danh sách ứng
+   viên rồi để PO chốt. Đoán sai ở đây là sửa sai một yêu cầu đã duyệt.
 
-| `Status` của request | Xử lý |
-|---|---|
-| `accepted` | Đưa `Requested behavior` + `Suggested AC` vào làm **nguyên liệu** cho Bước 3. **KHÔNG chèn thẳng vào PRD** — đây là yêu cầu nghiệp vụ, phải qua PO chốt AC/BR đúng tầng. |
-| `Open` (chưa ai xử) | **Trình cho PO ngay ở CHECKPOINT** kèm số ngày chờ: *"có {n} request chưa xử lý, đưa vào lần này không?"*. PO chọn từng cái. |
-| `rejected` / `incorporated` | Bỏ qua. |
+Với **mỗi** target, phân giải **UC sở hữu** ngay (dùng `all_br` / `all_ac`) và lưu vào
+`affected_ucs`. ID không phân giải được về UC nào → **DỪNG**, báo ID sai; đừng sửa mò.
 
-Lưu danh sách request sẽ xử lý (`incoming_requests`) — Bước 6.5 sẽ đóng dấu chúng.
+### Hai chế độ — và những gì lệnh này **KHÔNG** làm
 
----
+| Chế độ | Cờ | Làm gì |
+|---|---|---|
+| **Sửa nội dung** *(mặc định)* | — | Đổi nội dung của ID đã có. ID **giữ nguyên**. |
+| **Khai tử tại chỗ** | `--retire {ID}` | Đánh dấu ID là không còn hiệu lực **NHƯNG GIỮ NGUYÊN row/ID** (xem Bước 4). |
 
-## Bước 3 — Discovery delta *(CHỈ phần thêm)*
+**Ngoài phạm vi — route đi chỗ khác, đừng làm ở đây:**
 
-*Tái dùng đúng các phase của `/define-product` áp dụng được cho một phần thêm. **KHÔNG** lặp Phase 0 (Knowledge Sync — bối cảnh hệ thống đã có trong PRD), Phase 2 (User Flow toàn feature), Phase 7 (Validation Report toàn feature).*
+| PO muốn | Lệnh đúng | Vì sao không phải lệnh này |
+|---|---|---|
+| Thêm UC/AC/BR mới | `/extend-prd` | Nó có Discovery delta + đánh số nối tiếp. Lệnh này **không đánh số mới** bao giờ |
+| **XOÁ HẲN** một dòng BR/AC/UC | *(không có, và có chủ ý)* | Xoá row làm `@trace.business_rules` trong mọi `.feature` đã sinh trỏ vào ID không còn ⇒ đúng hình dạng `TRACE_ORPHAN`. Dùng `--retire` — nó đạt cùng mục đích nghiệp vụ mà **không** phá liên kết |
+| Sửa lỗi mà `/refine-prd` vừa chỉ ra | `/refine-prd --resume` | Nó đã có findings + `applied_to_version` để theo dõi delta |
 
-**Áp Discovery Contract của `/define-product`:** input của PO (kể cả nội dung request ở Bước 2) là **nguyên liệu thô**, KHÔNG phải câu trả lời thay phỏng vấn. Item đã phủ → trình bản nháp `🤖 trích từ input` rồi hỏi PO xác nhận/sửa; chỉ khi PO chốt mới nâng thành `✅ PO xác nhận`. **Không có luật skip-if-answered.**
+**Guard — PRD chưa `approved`:** nếu `current_status != approved` → cảnh báo mềm, không chặn:
+```
+⚠️  PRD đang ở Status: {status} (chưa approved).
+    Sửa một yêu cầu CHƯA được duyệt thì thường không cần lệnh này — cứ hoàn tất vòng review
+    hiện tại (/review-context → /refine-prd → PO duyệt) là nội dung sẽ đúng.
+    Vẫn sửa tại chỗ bây giờ? (Y/N)
+```
 
-| Phase | Nội dung | Ghi chú |
-|---|---|---|
-| **3.1** | **Định nghĩa phần thêm** — bối cảnh · vấn đề · phạm vi in/out · actor · pre/post-condition | Tương ứng Phase 1 của `/define-product`, thu hẹp vào phần mới |
-| **3.2** | **Va chạm với cái đã có** ⭐ | Xem dưới — đây là phase KHÔNG có trong `/define-product` |
-| **3.3** | **Business Rule** cho phần thêm | Phase 4 |
-| **3.4** | **Business Logic** | Phase 5 |
-| **3.5** | **Acceptance Criteria** | Phase 6 — giữ tầng: AC = outcome quan sát được + ref BR, cơ chế nằm ở BR/BL |
+---
 
-### 3.2 — Kiểm va chạm *(bắt buộc, không bỏ qua)*
+## Bước 2 — Kiểm va chạm *(bắt buộc, không bỏ qua)*
 
-*`/define-product` không có phase này vì lúc đó chưa có gì để va chạm. Ở đây thì có — và va chạm âm thầm là cách một PRD tự mâu thuẫn.*
+*Tái dùng đúng **Bước 3.2** của `/extend-prd`, đảo hướng: ở đó câu hỏi là "phần THÊM có làm cái cũ
+sai không"; ở đây là "cái SỬA có làm phần còn lại sai không". Cùng ba câu, cùng lý do — va chạm âm
+thầm là cách một PRD tự mâu thuẫn.*
 
-Đối chiếu phần thêm với `existing_ucs` + toàn bộ BR hiện có, hỏi PO ba câu:
+Với **mỗi** target, đối chiếu nội dung mới với toàn bộ PRD và hỏi PO:
 
-1. **Mâu thuẫn rule:** phần thêm có làm một BR hiện có trở nên sai/không đủ không? *(vd BR cũ nói "tối đa 5 file", phần mới cần 20)* → nếu có, đây là **sửa BR cũ**, không phải thêm BR mới. Ghi rõ để Bước 5 sửa đúng chỗ và Bước 6 tính bump **major**.
-2. **Trùng lặp:** phần thêm đã được một UC/AC hiện có phủ một phần chưa? → nếu có, hỏi PO: **mở rộng UC cũ** hay **tạo UC mới**. Đừng tự quyết.
-3. **Phụ thuộc:** phần thêm có cần dữ liệu/năng lực từ UC khác hoặc service khác không? → bổ sung vào **§1c Phụ thuộc liên service**.
+1. **Mâu thuẫn ngược:** giá trị/hành vi mới có làm một BR **khác** trở nên sai hoặc không đủ không?
+   *(BR8 nâng 5→20, nhưng BR12 nói "gộp tối đa 5 file vào một hoá đơn")* → nếu có, **BR12 cũng phải
+   vào `amend_targets`**. Đây là lý do bước này không bỏ qua được: sửa một nửa của một cặp ràng buộc
+   là tạo một PRD tự mâu thuẫn, và không cờ nào bắt được mâu thuẫn nội bộ của tài liệu.
+2. **AC lệch theo:** AC nào đang ref target này có còn diễn tả đúng outcome không? → nếu không, AC đó
+   vào `amend_targets`.
+3. **Phụ thuộc liên service:** thay đổi có đụng cam kết ở **§1c** không? → cập nhật §1c (mức nghiệp vụ).
 
-Kết quả 3.2 quyết định hình dạng thay đổi:
+Mỗi câu trả lời "có" **mở rộng `amend_targets`** — và `affected_ucs` mở rộng theo. Chốt lại danh sách
+trước khi sang CHECKPOINT.
 
-| Kết quả | Bước 5 làm gì |
-|---|---|
-| Thuần thêm mới | Append UC/AC/BR mới. Không đụng nội dung cũ. |
-| Có sửa BR cũ | Sửa **tại chỗ** BR đó (Edit) **+** append phần mới. Nêu rõ trong changelog. |
-| Mở rộng UC cũ | Append AC/BR mới **vào UC đó**, không tạo UC mới. |
+### CHECKPOINT trước khi ghi
 
-**CHECKPOINT** trước khi ghi:
 ```
-CHECKPOINT — Extend PRD {TICKET-ID}
+CHECKPOINT — Amend PRD {TICKET-ID}
 ─────────────────────────────────────────────────
-PRD        : v{current_version} ({current_status}) — {n} UC hiện có
-Thêm       : UC{max_uc+1} "{tên}"  [hoặc: mở rộng UC{k}]
-             +{n} AC (AC{max_ac+1}…) · +{m} BR (BR{max_br+1}…)
-Sửa cái cũ : {danh sách BR/AC bị sửa do va chạm — hoặc "không"}
-Từ request : {danh sách file request được đưa vào — hoặc "không"}
-Version    : {current} → {new} ({major|minor}) · Status → draft
-BDD ảnh hưởng: cần /generate-bdd cho UC mới; {n} UC cũ KHÔNG phải gen lại
+PRD        : v{current_version} ({current_status}) — {n} UC
+Sửa        : UC3-BR8  "tối đa 5 file"  →  "tối đa 20 file"
+             UC3-AC5  {tóm tắt thay đổi}
+Khai tử    : {UC4-BR15 (--retire) | không}
+Va chạm    : {UC5-BR12 cũng phải sửa (mâu thuẫn với BR8 mới) | không}
+UC ảnh hưởng: UC3, UC5           ← sẽ là {changelog_scope}
+Version    : v{current} → v{new} ({major|minor}) · Status → draft
+
+Sau khi ghi, các UC trên BẮT BUỘC:
+  /generate-bdd  → /generate-code  → /dev-gen-test → /dev-run-test
+  ❌ KHÔNG dùng --realign-prd-version cho chúng (nội dung đổi thật)
+
+BDD đã sinh sẽ lỗi thời: {danh sách UC × platform}
 
 Tiếp tục? (Y/N)
 ```
 
 ---
 
-## Bước 4 — Đánh số nối tiếp *(TUYỆT ĐỐI không đánh lại)*
+## Bước 3 — Altitude: sửa ở đúng tầng
 
-| Loại | Quy tắc |
-|---|---|
-| UC | `UC{max_uc + 1}`, tăng dần |
-| BR | `{TICKET-ID}-UC{n}-BR{max_br + 1}` — **`max_br` tính trên TOÀN PRD**, không reset theo UC |
-| AC | `AC{max_ac + 1}` |
-
-> **Đây là ràng buộc cứng nhất của lệnh này.** Đánh lại ID cũ — kể cả để "cho gọn" — sẽ phá:
-> - `@trace.business_rules` trong mọi `.feature` đã sinh (BR ID churn)
-> - dòng "AC liên quan" của từng UC
-> - mọi cross-reference `[TICKET-ID](./file.md)` từ PRD khác trỏ tới AC/BR cụ thể
->
-> Số bị bỏ trống (do UC cũ bị xoá ở version trước) **để trống vĩnh viễn**. Đừng lấp lại — ID đã từng
-> tồn tại có thể còn bị tham chiếu ở BDD, code, bug report, hoặc PRD khác.
+*Giống `/extend-prd` Bước 5 và `/refine-prd` Phase 2 — nêu lại vì đây là chỗ dễ trôi nhất khi sửa
+tại chỗ: PO thường mô tả thay đổi bằng cơ chế, và cách rẻ nhất là nhét cơ chế vào AC.*
+
+| Tầng | Chứa gì | KHÔNG chứa gì |
+|---|---|---|
+| **AC** | outcome **quan sát/kiểm được** + ref `_(BR: …)_` | số lần retry, timeout, tên cờ, nhánh lỗi vụn, và **không lặp lại nội dung BR nó ref** |
+| **BR** | quy tắc nghiệp vụ (WHAT) — giá trị, giới hạn, điều kiện | chi tiết kỹ thuật triển khai |
+| **Business Logic** | trình tự nghiệp vụ (HOW **nghiệp vụ**) | API, cấu trúc dữ liệu, thư viện |
+
+Thay đổi là **cơ chế** mà PO đang muốn nhét vào AC → **route xuống BR/BL**, AC chỉ giữ outcome + ref.
+
+**Chạy Business Language Guard trên MỌI text mới TRƯỚC khi ghi.**
 
 ---
 
-## Bước 5 — Ghi vào PRD *(Edit add-only, KHÔNG Write)*
+## Bước 4 — Ghi *(Edit tại chỗ · guard sau-ghi ĐẢO NGƯỢC)*
 
-> **Kỷ luật EXTEND — copy nguyên từ `/generate-code` §File Scan, cùng lý do:**
+> **Đây là chỗ lệnh này khác MỌI thao tác ghi khác trong framework.** `/extend-prd` guard bằng
+> *"output là **superset chặt** của bản cũ"*. Ở đây output **cố ý KHÔNG** phải superset — nên guard
+> phải đảo: **mọi thứ giữ nguyên NGOẠI TRỪ đúng các ID trong `amend_targets`.**
 >
-> 1. **Đọc lại file trên disk NGAY TRƯỚC khi ghi** (không dựa vào bản nạp ở Bước 1 — có thể đã đổi).
-> 2. **CHỈ dùng Edit để THÊM.** **CẤM tuyệt đối Write cả file.** Đây là nguyên nhân số 1 xoá nghiệp vụ đã duyệt.
-> 3. Output PHẢI là **superset chặt** của bản cũ: **mọi** UC, AC, BR, row bảng, dòng changelog, cross-reference cũ **còn nguyên si** — trừ đúng những chỗ Bước 3.2 kết luận là "sửa BR cũ", và chỉ đúng những chỗ đó.
-> 4. **Guard sau-ghi (bắt buộc):** đọc lại file vừa ghi, đối chiếu với bản trước khi sửa. Kiểm: mọi UC-ID cũ · mọi BR-ID cũ · mọi AC cũ · mọi row `# Change Log` cũ **vẫn còn**. Nếu **mất bất kỳ cái nào** → **DỪNG NGAY, khôi phục file về bản cũ** (`git checkout -- {file}` nếu đã commit, hoặc hoàn tác edit), báo:
->    ```
->    ❌ EXTEND làm mất {UC/AC/BR/changelog row} — đã chặn clobber.
->       File đã khôi phục. Sửa lại theo add-only rồi chạy lại.
->    ```
->    **KHÔNG** tiếp tục sang Bước 6.
-
-Vị trí ghi từng loại nội dung:
-
-| Nội dung | Đặt ở đâu |
-|---|---|
-| UC mới | **Cuối §3**, sau UC hiện có cuối cùng. Đủ Actor · Description · Pre-condition · Post-condition · bảng BR · dòng "AC liên quan" |
-| AC mới | **Cuối §2**, kèm ref `_(BR: …)_` trỏ về BR tương ứng |
-| BR mới | Bảng BR của UC sở hữu. **Giữ đúng hình dạng bảng hiện có** (3 cột hay đã mở cột) — đừng đổi hình dạng ở lệnh này |
-| Phụ thuộc mới | **§1c Phụ thuộc liên service** — append, mức nghiệp vụ |
-| Màn hình mới | **§4b Wireframe** — nguồn coverage cho `/generate-bdd` C.1 |
-| Quy ước mới dùng ≥2 chỗ | **§1d**, khai MỘT LẦN, AC/BR trỏ tới thay vì chép |
+> Guard yếu hơn không được: một lệnh được phép sửa nội dung đã duyệt mà không có rào chính xác là
+> đúng cái `/generate-prd` bị chặn-cứng để tránh.
 
-**Altitude khi viết** *(giống `/refine-prd` Phase 2)*: AC = **outcome quan sát/kiểm được + ref BR**, KHÔNG chứa cơ chế (số lần retry, timeout, tên cờ, nhánh lỗi vụn) — cơ chế nằm ở BR/BL. AC không lặp lại nội dung BR nó ref.
+1. **Đọc lại file trên disk NGAY TRƯỚC khi ghi** — không dựa vào bản nạp ở Bước 1.
+2. **CHỈ dùng Edit.** **CẤM tuyệt đối Write cả file.**
+3. **KHÔNG đánh số lại bất kỳ ID nào.** Không thêm ID mới (đó là `/extend-prd`). Không xoá row.
+4. Chế độ `--retire {ID}`: **giữ nguyên row và ID**, đổi nội dung thành dạng khai tử rõ ràng —
+   `~~{nội dung cũ}~~ **(không còn hiệu lực từ v{new})**` — và thêm một dòng nêu lý do nghiệp vụ.
+   *Không xoá row vì `@trace.business_rules` trong `.feature` đã sinh đang trỏ vào ID này; xoá nó
+   biến một liên kết hợp lệ thành `TRACE_ORPHAN` 🔴.*
 
-**Chạy Business Language Guard trên MỌI text mới TRƯỚC khi ghi** — đừng để phần thêm kéo thuật ngữ kỹ thuật/UI vào một PRD đang sạch.
+### Guard sau-ghi *(bắt buộc — DỪNG nếu fail)*
 
----
+Đọc lại file vừa ghi, đối chiếu với bản trước khi sửa. Kiểm **hai chiều**:
+
+| Chiều | Kiểm gì | Fail nghĩa là |
+|---|---|---|
+| **Bảo toàn** | Mọi UC-ID · BR-ID · AC-ID · row `# Change Log` cũ **vẫn còn** (kể cả ID vừa `--retire`) | Đã xoá thứ không được xoá |
+| **Giới hạn** | **Mọi** nội dung đã đổi đều thuộc một ID trong `amend_targets` — **không có** chỗ nào khác đổi | Đã sửa lan ra ngoài phạm vi PO chốt |
 
-## Bước 6 — Bump version & ghi changelog
+Fail bất kỳ chiều nào → **DỪNG NGAY, khôi phục file về bản cũ** (`git checkout -- {file}` nếu đã
+commit, hoặc hoàn tác edit), báo:
+```
+❌ AMEND vi phạm phạm vi — đã chặn.
+   {Mất: UC3-BR9 | Sửa ngoài phạm vi: UC7-BR22 (không có trong amend_targets)}
+   File đã khôi phục. Chỉ sửa đúng ID đã chốt rồi chạy lại.
+```
+**KHÔNG** tiếp tục sang Bước 5.
 
-*Tái dùng **nguyên** `### Phase 3` của `/refine-prd`. Không viết lại luật ở đây — dòng changelog là **contract**: `/generate-bdd` Version Check đọc nó để quyết cập nhật hẹp (Y) hay gen lại toàn bộ (F), và `/validate-traces` Step 4/5 đọc nó để lọc `PRD_DRIFT` 🟠 vs `PRD_STALE_REF` ⓘ. Viết kiểu khác là làm hỏng cả hai.*
+> **Vì sao chiều "Giới hạn" quan trọng bằng chiều "Bảo toàn":** `{changelog_scope}` ở Bước 5 dựng từ
+> `amend_targets`. Nếu bản ghi lỡ sửa một UC không có trong danh sách đó, thì changelog **không nêu**
+> UC ấy ⇒ `/validate-traces` xếp nó vào ⓘ `PRD_STALE_REF` ⇒ `--realign-prd-version` **mở cửa** và dán
+> nhãn version lại lên một thay đổi chưa ai implement. Đúng hình dạng G53, chỉ đến từ một hướng khác.
+
+---
+
+## Bước 5 — Bump version & ghi changelog
 
 1. Loại bump:
-   - **major** (X.0 → X+1.0): thêm UC mới · sửa BR cũ theo hướng breaking · tái cấu trúc scope. *(Thêm UC là major theo định nghĩa của `/refine-prd` Phase 3.)*
-   - **minor** (x.Y → x.Y+1): chỉ thêm AC/BR vào UC đã có, không đổi hành vi cũ.
-2. Cập nhật Metadata: `Version` = mới · `Updated` = hôm nay · **`Status` = `draft`** *(thêm yêu cầu = phải duyệt lại)*.
+   - **major** (X.0 → X+1.0): đổi hành vi theo hướng **breaking** · `--retire` một BR/AC · tái cấu
+     trúc scope. *(Đổi một giới hạn nghiệp vụ 5→20 là **major** — code hiện tại đang chặn ở 5, tức
+     nó đang sai so với spec mới.)*
+   - **minor** (x.Y → x.Y+1): làm rõ diễn đạt mà **không** đổi hành vi nghiệm thu được.
+2. Cập nhật Metadata: `Version` = mới · `Updated` = hôm nay · **`Status` = `draft`**
+   *(yêu cầu đã duyệt vừa đổi ⇒ con dấu duyệt cũ hết hiệu lực — đồng bộ `/refine-prd`, `/extend-prd`.)*
 3. Thêm row lên **đầu** bảng `# Change Log`:
    ```
-   | {new_version} | {today} | {tóm tắt — BẮT BUỘC nêu UC/AC/BR bị ảnh hưởng} |
+   | {new_version} | {today} | {changelog_scope} |
    ```
-   **Ví dụ đúng:** `thêm UC7 (xuất nhiều file): AC12-AC14, BR21-BR23; sửa BR8 (nâng giới hạn 5→20)`
-   **Ví dụ SAI:** `cập nhật theo yêu cầu mới` ← mơ hồ → `/generate-bdd` sẽ khuyến nghị gen lại **toàn bộ**, và `/validate-traces` sẽ gắn `PRD_DRIFT` 🟠 cho **mọi** UC thay vì chỉ UC mới. Một dòng viết ẩu làm mất cả hai bộ lọc.
-4. Cập nhật dòng đầu section: `> Hiện tại: **v{new}** ({today}) · Lịch sử đầy đủ → [changelog](./changelog/{TICKET-ID}-{prd-slug}.changelog.md)`
-5. **Rollover** (cửa sổ trượt 5 row): bảng `# Change Log` vượt **5** row → chuyển mọi row vượt 5 (cũ nhất) sang **đầu** bảng của `{specs_dir}/{domain}/{prd-slug}/changelog/{TICKET-ID}-{prd-slug}.changelog.md`; PRD giữ 5 row gần nhất. Tạo dir + file theo skeleton của `/refine-prd` Phase 3 nếu chưa có.
-
----
-
-## Bước 6.5 — Đóng dấu request đã xử lý
+   **`{changelog_scope}` — mỗi mệnh đề mở đầu bằng UC SỞ HỮU** *(contract:
+   `bin/trace-schema.json` → `changelog_row_contract`)*. Nguồn: `affected_ucs` đã chốt ở Bước 2 —
+   tức **UC sở hữu của từng ID trong `amend_targets`**. Ngăn nhau bằng `;`. Thay đổi ở §1c/§1d
+   (không thuộc UC nào) → `PRD-global`.
 
-Với mỗi file trong `incoming_requests` đã được PO chốt và nội dung đã ghi vào PRD:
+   **Ví dụ đúng**
+   ```
+   | 2.0 | 2026-08-19 | UC3: sửa BR8 (giới hạn 5→20 file), AC5 theo đó; UC5: sửa BR12 (bỏ ràng buộc gộp 5) |
+   | 3.0 | 2026-08-22 | UC4: khai tử BR15 (không còn yêu cầu duyệt hai cấp) |
+   ```
 
-1. Đặt `Status: incorporated` trong file request.
-2. Thêm dòng `Incorporated into: v{new_version}` — để lần sau tra được yêu cầu nào vào version nào.
-3. Chuyển file sang `{paths.prd_change_requests_dir}/archived/` (tạo dir nếu cần).
-4. **Commit + push** spec repo (giống `feedback/` — xem `/propose-scenario` Step 5): `git add feedback/prd-change-requests/ && git commit -m "po(prd-change): {TICKET-ID} — incorporated into v{new}" && git push`. Không có quyền push → mở PR/MR và in fallback.
+   ⚠️ **BR/AC không bao giờ đứng một mình.** `sửa BR8` (thiếu `UC3:`) nêu đủ ID để **không** bị coi
+   là mơ hồ, nhưng consumer khớp theo **UC** — nên UC3 rơi vào ⓘ và `--realign` dán nhãn lại lên
+   đúng thay đổi này. **Lệnh này là producer dễ mắc lỗi đó nhất**, vì đầu vào của nó *là* một BR-ID.
 
-Request mà PO **không** chốt lần này → **để nguyên** `Status: Open`. `/validate-traces` Step 7b sẽ tiếp tục nhắc kèm số ngày chờ.
+   ⚠️ **KHÔNG dùng hậu tố `[no-behavior]` ở lệnh này.** Nó dành cho fix mà producer **chứng minh
+   được** là thuần cấu trúc (`changelog_row_contract.neutral_checks`). Lệnh này tồn tại để đổi **nội
+   dung nghiệp vụ** — theo định nghĩa là có đổi hành vi.
+4. Cập nhật dòng đầu section: `> Hiện tại: **v{new}** ({today}) · Lịch sử đầy đủ → [changelog](./changelog/{TICKET-ID}-{prd-slug}.changelog.md)`
+5. **Rollover** (cửa sổ trượt 5 row) — theo đúng quy ước `/refine-prd` Phase 3.
 
 ---
 
-## Bước 7 — Report
+## Bước 6 — Report
 
 **Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·
 Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
@@ -436,51 +465,55 @@ Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
 Ví dụ footer cho lệnh này:
 
 ```
-/extend-prd Đã thêm — {TICKET-ID} {tên feature}
+/amend-prd Đã sửa — {TICKET-ID} {tên feature}
+
+Version   : v1.3 → v2.0 (major) · Status → draft
+Sửa       : UC3-BR8  "tối đa 5 file"  →  "tối đa 20 file"
+            UC3-AC5  diễn đạt lại outcome theo BR8 mới
+            UC5-BR12 bỏ ràng buộc gộp 5 (va chạm với BR8 mới — Bước 2 câu 1)
+Khai tử   : không
+Changelog : | 2.0 | 2026-08-19 | UC3: sửa BR8 (giới hạn 5→20 file), AC5 theo đó; UC5: sửa BR12 |
+
+Guard sau-ghi : ✅ Bảo toàn — {n} UC · {m} AC · {k} BR · {j} changelog row cũ còn nguyên
+                ✅ Giới hạn  — 0 chỗ đổi ngoài amend_targets
 
-Version   : v{old} → v{new} ({major|minor}) · Status → draft
-Thêm      : UC{N} "{tên}" · AC{a}-AC{b} · BR{c}-BR{d}
-Sửa cũ    : {BR8 — nâng giới hạn 5→20 | không}
-Request   : {2 file → archived/ (incorporated v{new}) | không}
-Changelog : | v{new} | {today} | thêm UC{N}: AC{a}-AC{b}, BR{c}-BR{d}; sửa BR8 |
+🔴 UC PHẢI làm lại (nội dung đổi thật): UC3, UC5
+   /generate-bdd {prd-file}        ← BDD hiện tại đang nghiệm thu giới hạn 5
+   → /generate-code {UC-ID}        ← code đang chặn ở 5
+   → /dev-gen-test → /dev-run-test ← test đang assert 5 và vẫn PASS
+   ❌ TUYỆT ĐỐI KHÔNG --realign-prd-version cho UC3/UC5 — đó là dán nhãn lên thay đổi
+      chưa ai implement.
 
-Guard sau-ghi : ✅ {n} UC · {m} AC · {k} BR · {j} changelog row cũ — còn nguyên
+BDD sẽ lỗi thời: bdd/system/{TICKET-ID}-UC3.feature · bdd/web/{TICKET-ID}-UC3.feature
 
-UC KHÔNG đổi ({n}): {UC1, UC2, UC3…}
-  → KHÔNG cần /generate-bdd hay /generate-code cho các UC này.
-    /validate-traces sẽ xếp chúng vào ⓘ PRD_STALE_REF (nhãn version cũ, nội dung không đổi).
-    Sạch bằng: /validate-traces --realign-prd-version {UC-ID}
+UC KHÔNG đổi ({n}): {UC1, UC2, UC4…}
+   → ⓘ PRD_STALE_REF. Sạch bằng: /validate-traces --realign-prd-version {UC-ID}
 
-⚠️  Status đã reset về draft — phần thêm chưa được duyệt.
+⚠️  Status đã reset về draft — thay đổi chưa được duyệt lại.
 
 ---
 Status   : ✅ Complete
 Output Artifacts:
-  updated {paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md (v{new})
+  updated {paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md (v2.0)
   updated {paths.specs_dir}/{domain}/{prd-slug}/changelog/… (nếu có rollover)
-  updated {paths.prd_change_requests_dir}/archived/… (nếu có request)
 Pipeline : Discovery → [PRD ◀ bạn ở đây] → Design Spec → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-Next     : /refine-prd {prd-file}        ← soi phần vừa thêm qua 3 lăng kính
-           → /review-context {prd-file}  ← kiểm chất lượng trước khi sinh BDD
-           → khi sạch critical, PO đặt Status: approved, rồi:
-               • Feature CÓ màn hình → /generate-design-spec {prd-file} (design-spec sẽ tự
-                 phát hiện lỗi thời vs PRD mới và bắt sign-off lại) rồi /generate-bdd
-               • Thuần backend → /generate-bdd {prd-file} thẳng
-           → CHỈ gen BDD/code cho UC MỚI. UC cũ: dùng --realign-prd-version.
+Next     : /review-context {prd-file}   ← kiểm chất lượng phần vừa sửa
+           → khi sạch critical, PO đặt Status: approved
+           → /generate-bdd {prd-file}   ← CHỈ cho UC3, UC5
 ```
 
 ---
 
 ## Quality Checklist *(kiểm trước khi ghi)*
 
-- [ ] **Không đánh lại BẤT KỲ ID cũ nào** — UC/AC/BR mới đều là `max + 1`; số bị bỏ trống vẫn để trống
-- [ ] `max_br` tính trên **toàn PRD**, không reset theo UC
-- [ ] Guard sau-ghi đã chạy và PASS: mọi UC/AC/BR/changelog row cũ còn nguyên
-- [ ] Bước 3.2 đã hỏi đủ 3 câu va chạm (mâu thuẫn rule · trùng lặp · phụ thuộc)
-- [ ] Mỗi AC mới có ≥1 ref `_(BR: …)_`; mỗi UC mới có dòng "AC liên quan"; hai chiều khớp nhau
-- [ ] Dòng changelog **nêu rõ UC/AC/BR** — không mơ hồ *(contract cho `/generate-bdd` + bộ lọc `PRD_STALE_REF`)*
+- [ ] `amend_targets` do **PO khai tường minh** — không suy từ mô tả mơ hồ
+- [ ] Mỗi target đã phân giải được **UC sở hữu**; ID không phân giải được → đã DỪNG
+- [ ] Bước 2 đã hỏi đủ 3 câu va chạm, và mọi ID phát sinh **đã được thêm** vào `amend_targets`
+- [ ] **KHÔNG** đánh số lại ID nào · **KHÔNG** thêm ID mới · **KHÔNG** xoá row nào
+- [ ] `--retire` giữ nguyên row + ID (chỉ đổi nội dung sang dạng khai tử)
+- [ ] Guard sau-ghi PASS **cả hai chiều**: Bảo toàn **và** Giới hạn
+- [ ] Altitude đúng tầng: cơ chế nằm ở BR/BL, AC chỉ outcome + ref
+- [ ] `{changelog_scope}`: mỗi mệnh đề **mở đầu bằng UC sở hữu**; **không** BR/AC đứng một mình; **không** `[no-behavior]`
 - [ ] `Status` đã reset về `draft`
-- [ ] Hình dạng bảng BR giữ nguyên như cũ (không đổi 3-cột ↔ mở-cột ở lệnh này)
 - [ ] Không có banned term; 0 thuật ngữ kỹ thuật/UI trong text mới
-- [ ] Request đã xử lý → `incorporated` + `archived/` + commit; request chưa xử lý → giữ `Open`
-- [ ] Report nêu rõ danh sách **UC không đổi** + route `--realign-prd-version` cho chúng
+- [ ] Report nêu **UC PHẢI làm lại** kèm lệnh, và **cấm tường minh** `--realign` cho chúng

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

@@ -338,20 +338,58 @@ Sau khi chạy, lưu kết quả vào **TSV authoritative** trong service để
 report Living Docs ở spec module (qua `/sync` + `/validate-traces`). Các file test
 ở lại trong service — chỉ *status* của lần chạy được report.
 
-Cập nhật **sổ của platform đang test** `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` (`{platform}` = platform của code/`.feature` đang test — `system` cho backend, `web`/`app` cho FE/App; nếu `domain`/`prd_slug` không phân giải được từ spec target, định vị TSV bằng cách glob `{paths.trace_dir}/**/{UC-ID}-{platform}.tsv` — nó được tạo trước đó bởi `/generate-bdd`) — cho mỗi scenario row (khớp `sc_id` qua tag
+Cập nhật **sổ của platform đang test** `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` (`{platform}` = platform của code/`.feature` đang test — `system` cho backend, mọi platform khác (`web`/`app`/`webview`/…) cho client; nếu `domain`/`prd_slug` không phân giải được từ spec target, định vị TSV bằng cách glob `{paths.trace_dir}/**/{UC-ID}-{platform}.tsv` — nó được tạo trước đó bởi `/generate-bdd`) — cho mỗi scenario row (khớp `sc_id` qua tag
 `@trace.verifies={UC-ID}-SC{N}` của test). *(Umbrella + `spec_source`: `trace_dir` là `{spec_source}/.trace` — test chạy từ `service_root` nhưng update `dev_selftest` ghi vào **spec repo**; commit/push spec submodule cho nó.)*
 
-| Cột | Giá trị |
-|--------|-------|
-| `dev_selftest` | `pass` nếu mọi test của SC này pass · `fail` nếu có cái fail · `not_run` nếu test của nó bị skip/vắng |
-| `dev_selftest_at` | hôm nay `YYYY-MM-DD` |
-| `last_updated` | hôm nay `YYYY-MM-DD` |
+### ĐỌC cột `status` của row TRƯỚC KHI GHI *(bắt buộc)*
+
+*Contract: `bin/trace-schema.json` → `positive_assertion_guards`. Dữ liệu đã có trong sổ — không phát sinh I/O.*
+
+`pass` **không** mang nghĩa *"test đã chạy và xanh"*. Nó mang nghĩa **"scenario này đã được nghiệm thu theo spec HIỆN TẠI"**. Nên trước khi ghi nó, đọc `status` của đúng row đó:
+
+| `status` của row | `dev_selftest` ghi gì | `dev_selftest_at` |
+|---|---|---|
+| `OK` · `GAP` · `UNTRACKED` | `pass` nếu mọi test của SC này pass · `fail` nếu có cái fail · `not_run` nếu test bị skip/vắng | hôm nay |
+| **`DRIFT`** | test **pass** → **`not_run`** *(KHÔNG ghi `pass`)* · test **fail** → **`fail`** như thường | `—` nếu ghi `not_run`; hôm nay nếu ghi `fail` |
+| **`ORPHANED`** | **`not_run`** — scenario đã bị xoá khỏi `.feature`, không còn gì để nghiệm thu | `—` |
+
+`last_updated` = hôm nay, mọi trường hợp.
+
+**Tin xấu luôn hợp lệ.** Đây là guard cho lời khẳng định **DƯƠNG**, không phải lệnh *"bỏ qua kết quả khi DRIFT"*. Test đỏ trên row DRIFT vẫn là thông tin thật và phải được ghi. Chỉ `pass` cần giấy phép.
+
+**Khi ghi `not_run` vì `DRIFT`/`ORPHANED`, in ngay:**
+```
+⚠️  {sc_id} — test XANH nhưng row đang {DRIFT | ORPHANED}, nên KHÔNG ghi pass.
+    {DRIFT: spec đã đổi sau lần codegen (spec_ver {a} ≠ gen_ver {b}) — test hiện tại đang
+     nghiệm thu một hành vi không còn tồn tại.
+     Làm: /generate-code {UC-ID} → /dev-gen-test {UC-ID} → chạy lại lệnh này.}
+    {ORPHANED: scenario đã bị xoá khỏi .feature nhưng code+test còn. Xử theo /validate-traces.}
+```
+
+> **Vì sao bước này bắt buộc (GAPS-v4 G55).** Bản cũ ghi `pass` chỉ dựa vào *test có xanh không*, và
+> khai `dev_selftest` **trực giao** với `status`. Trực giao về *kết quả chạy* thì đúng — nhưng
+> **không** trực giao về *quyền được khẳng định*.
+>
+> Chuỗi hỏng, mọi mắt nối đều là hành vi framework tự chỉ định: PO đổi AC → `/generate-bdd` đặt
+> `status = DRIFT` và **hạ** `dev_selftest → not_run` (kèm cảnh báo *"test của SC này viết cho spec
+> cũ"*) → sáng sau dev chạy lệnh này theo thói quen, **chưa** `/generate-code`, **chưa**
+> `/dev-gen-test` → test cũ + code cũ xanh hết → ghi `pass` + **ngày hôm nay**.
+>
+> Tức **lệnh kế tiếp trong vòng lặp dev bình thường dựng lại đúng cái tín hiệu `/generate-bdd` vừa
+> hạ xuống.** README §Philosophy: *"Một tín hiệu đã hết đúng phải bị hạ xuống, không được giữ"* —
+> ở đây còn tệ hơn *giữ*: nó **tái phát hành** với dấu ngày mới.
+>
+> Và thứ duy nhất chở tín hiệu *"test đã lỗi thời"* là **một dòng terminal** từ một lần chạy có thể
+> đã xảy ra tuần trước, trong session của người khác: sổ có 24 cột và **không cột nào** giữ *"test
+> được viết cho `spec_ver` nào"*. Dev không có cách nào biết. Đọc `status` là cách rẻ nhất để biết.
+>
+> **Tầng thứ hai độc lập:** `lint-trace` **T12** bắt đúng trạng thái này ở sổ thật (`status` ∈
+> {DRIFT, ORPHANED} mà `dev_selftest`/`qc_status` = `pass`), bất kể lệnh nào ghi ra — kể cả sổ sửa
+> tay hoặc sổ sinh bởi version framework cũ hơn.
 
 Giữ nguyên mọi cột khác — đặc biệt **không bao giờ** đụng `qc_status`/`qc_run_at`
-(kết quả QC automation chính thức, do `/qc-run-test` sở hữu). `dev_selftest` (dev smoke)
-và `qc_status` (QC chính thức) là hai tín hiệu riêng. `dev_selftest`/`dev_selftest_at` cũng
-trực giao với `status` (OK/GAP/DRIFT/UNTRACKED/ORPHANED): `status` theo dõi *coverage*, `dev_selftest`
-theo dõi *kết quả chạy* gần nhất của dev.
+(kết quả QC automation chính thức, do `/qc-run-test` sở hữu; nó có guard riêng cùng loại).
+`dev_selftest` (dev smoke) và `qc_status` (QC chính thức) là hai tín hiệu riêng.
 
 ## Refresh Panel Mirror
 # Làm mới panel mirror của Living Docs *(local)*