@educa-corp/sdd-framework 0.6.0 → 0.7.0

package/core/commands/extend-prd.md

@@ -6,6 +6,11 @@
 > |---|---|---|
 > | `/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/` |
+> | `/amend-prd` | *"một yêu cầu đang có cần **ĐỔI** thành gì?"* | PO khai tường minh ID cần sửa |
+>
+> **Ranh giới với `/amend-prd`:** lệnh này **chỉ THÊM** — Bước 5 §3 đòi output là *"superset chặt"*.
+> Nó có **một** cửa sửa nội dung cũ (Bước 3.2 case 1, "mâu thuẫn rule") nhưng cửa đó **phái sinh**:
+> chỉ mở khi phần THÊM làm một BR cũ sai. Muốn đổi một yêu cầu mà **không** thêm gì mới → `/amend-prd`.
 >
 > `/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
@@ -274,8 +279,9 @@ Các từ như `cờ / flag`, `biến / trường / field`, `giá trị / value`
 ℹ️  {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).
+    Sau khi thêm: /generate-bdd cho UC MỚI, VÀ cho mỗi UC cũ mà Bước 3.2 kết luận là
+    "sửa BR/AC cũ" (BR đó đổi hành vi → BDD của nó lỗi thời thật → 🟠 PRD_DRIFT).
+    UC cũ KHÔNG bị sửa gì thì không phải gen lại (ⓘ PRD_STALE_REF).
 ```
 
 ---
@@ -340,7 +346,8 @@ Thêm       : UC{max_uc+1} "{tên}"  [hoặc: mở rộng UC{k}]
 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
+BDD ảnh hưởng: /generate-bdd cho UC mới{, và cho UC{k} vì BR8 bị sửa}
+             {n} UC cũ không đụng gì → KHÔNG phải gen lại
 
 Tiếp tục? (Y/N)
 ```
@@ -406,10 +413,23 @@ Vị trí ghi từng loại nội dung:
 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)*.
 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} |
+   ```
+   **`{changelog_scope}` — mỗi mệnh đề mở đầu bằng UC SỞ HỮU** *(contract: `bin/trace-schema.json` → `changelog_row_contract`)*. Nguồn: UC mới (Bước 4) + **UC sở hữu mỗi BR/AC bị sửa** (kết luận Bước 3.2). Ngăn nhau bằng `;`. Nội dung không thuộc UC nào (§1c phụ thuộc, §1d quy ước) → `PRD-global`.
+
+   **Ví dụ đúng:**
+   ```
+   thêm UC7 (xuất nhiều file): AC12-AC14, BR21-BR23; UC3: sửa BR8 (nâng giới hạn 5→20)
    ```
-   **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.
+   **Ví dụ SAI — mơ hồ:** `cập nhật theo yêu cầu mới` ← `/generate-bdd` sẽ khuyến nghị gen lại **toàn bộ**, và `/validate-traces` gắn `PRD_DRIFT` 🟠 cho **mọi** UC thay vì chỉ UC mới. Mất bộ lọc theo hướng **ỒN**.
+
+   **Ví dụ SAI — nêu BR mà bỏ UC sở hữu:** `…; sửa BR8 (nâng giới hạn 5→20)` ← thiếu `UC3:`.
+
+   > ⚠️ **Đây là ca nguy hiểm HƠN ca mơ hồ, và là lý do luật này thành contract (G53).** Row trên nêu rất nhiều ID nên **không** bị coi là mơ hồ. Nhưng `/validate-traces` Step 4 khớp bằng phép thử *"**UC** này có trong tập bị ảnh hưởng?"* — tập là `{UC7, AC12-14, BR21-23, BR8}`, và **UC3 không có trong đó**. Nên UC3 → ⓘ `PRD_STALE_REF` *"không phải lỗi"*, trong khi BR mà nó sở hữu **vừa đổi hành vi 5→20**.
+   >
+   > Và nó không dừng ở một cờ sai: rào an toàn của `--realign-prd-version` chỉ **từ chối khi UC là 🟠**. Ở đây nó là **ⓘ** ⇒ rào **mở cửa** ⇒ nhãn `prd_version` được dán lại trong cả TSV lẫn tag code ⇒ **cờ sạch vĩnh viễn trên một thay đổi chưa ai implement**. Mất bộ lọc theo hướng **IM LẶNG**.
+   >
+   > Viết `UC3:` là một tiền tố ba ký tự. Bỏ nó là mở một đường tự động che lỗi.
 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ó.
 
@@ -440,13 +460,19 @@ Ví dụ footer cho lệnh này:
 
 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}
+Sửa cũ    : {UC3: BR8 — nâng giới hạn 5→20 | không}   ← LUÔN nêu UC sở hữu
 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 |
+Changelog : | v2.0 | 2026-08-19 | thêm UC7: AC12-AC14, BR21-BR23; UC3: sửa BR8 (giới hạn 5→20) |
 
 Guard sau-ghi : ✅ {n} UC · {m} AC · {k} BR · {j} changelog row cũ — còn nguyên
 
-UC KHÔNG đổi ({n}): {UC1, UC2, UC3…}
+UC BỊ SỬA nội dung ({n}): {UC3}
+  → CẦN /generate-bdd rồi /generate-code cho các UC này — BR/AC của chúng vừa đổi hành vi.
+    /validate-traces sẽ xếp chúng vào 🟠 PRD_DRIFT (đúng).
+    ❌ TUYỆT ĐỐI KHÔNG dùng --realign-prd-version cho chúng — đó là dán nhãn lên thay đổi
+       chưa ai implement.
+
+UC KHÔNG đổi ({n}): {UC1, UC2, UC4…}   ← = existing_ucs TRỪ danh sách "UC BỊ SỬA" ở trên
   → 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}
@@ -466,7 +492,8 @@ Next     : /refine-prd {prd-file}        ← soi phần vừa thêm qua 3 lăng
                • 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.
+           → gen BDD/code cho UC MỚI **và** UC cũ bị sửa BR/AC (xem "UC BỊ SỬA nội dung").
+             CHỈ UC cũ không đụng gì mới dùng --realign-prd-version.
 ```
 
 ---
@@ -478,9 +505,9 @@ Next     : /refine-prd {prd-file}        ← soi phần vừa thêm qua 3 lăng
 - [ ] 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`)*
+- [ ] Dòng changelog: mỗi mệnh đề **mở đầu bằng UC sở hữu** (`UC3: sửa BR8`) — **không** BR/AC đứng một mình, **không** mơ hồ *(contract: `changelog_row_contract`; BR trơ trọi ⇒ UC đó thành ⓘ ⇒ `--realign` che lỗi)*
 - [ ] `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 **CẢ HAI** danh sách: **UC BỊ SỬA nội dung** (→ `/generate-bdd`, cấm `--realign`) và **UC không đổi** (→ `--realign-prd-version`). Danh sách thứ hai = `existing_ucs` **TRỪ** danh sách thứ nhất — không được lấy trọn `existing_ucs`

package/core/commands/generate-bdd.md

@@ -375,9 +375,37 @@ Chỉ cần kiểm tra trạng thái đã phân giải:
 | `active_service` đã phân giải thành path service | Tiếp tục với `active_module` đã set. |
 | `active_service = "multi"` **và** `service_candidates_kind = platform` (domain map-theo-platform, target PRD chưa gắn 1 platform) | Tiếp tục — BDD là artifact liên team, platform-split. Sinh `bdd/{platform}/` cho các platform có trong `service_candidates`; từ vựng lấy theo `service_candidates.{platform}.module`. KHÔNG cần chốt 1 service. Platform nào bị đánh dấu `unresolved` trong candidates (thiếu `prd_slug` tương ứng dưới `by_prd_slug`) → vẫn sinh BDD nhưng gắn ⚠️ nêu rõ chưa có repo nhận. |
 | `active_service = "multi"` **và** `service_candidates_kind = prd_slug` | **DỪNG.** Candidates đang là map feature→repo, KHÔNG phải map platform — sinh `bdd/{slug}/` là sai bố cục. Yêu cầu người dùng chạy lại với target file cụ thể để `prd_slug` được xác định. |
-| `active_service = "unresolved"` (có section `services` nhưng domain PRD không khớp entry nào) | **DỪNG**, báo: "Domain `{domain}` của PRD không khớp service nào trong `services:` của project-context.yaml — bổ sung mapping rồi chạy lại." (Không đoán/hỏi tay — domain là khoá định danh, lệch là lỗi cấu hình cần sửa ở SoT.) |
+| `active_service = "unrouted"` (chưa có mapping cho domain/platform/prd_slug này) | **TIẾP TỤC** — ghi `@trace.service: unrouted`, in ⚠️, **KHÔNG dừng**. Xem khối bên dưới. |
+| `active_service = "unresolved"` (config **sai cấu trúc**: entry vừa có `path` vừa có `by_prd_slug`, hoặc `by_prd_slug` lồng nhau) | **DỪNG**, báo đúng key sai để người dùng sửa `project-context.yaml`. Đây là **bug cấu hình**, không phải trạng thái chờ. |
 | Single-service (không có section `services`) | `active_module = tech_stack.module` (đã set ở Bước 6.5). Tiếp tục. |
 
+#### `unrouted` — vì sao KHÔNG chặn ở đây *(G51)*
+
+PRD và BDD là artifact **nghiệp vụ**. PO biết `domain` (auth, payment) và biết `platform`
+(*"người dùng làm việc này trên web hay app?"*) — nhưng **không** biết code sẽ nằm repo nào,
+và ở feature đầu tiên của một domain mới thì **chưa ai quyết**.
+
+Chặn BDD vì lý do đó là đặt cổng **sai phase**: nó chặn phase KHÔNG CẦN biết, trong khi
+`/generate-code` — phase **buộc phải** biết mới ghi được file — mới là chỗ đúng để chặn.
+
+**Việc cần làm khi `unrouted`:**
+1. `@trace.service: unrouted` vào header `.feature` (đừng để trống — cột 23 sẽ mất thông tin)
+2. **`active_module` chưa biết** ⇒ hỏi người dùng `platform` trực tiếp (`web`/`app`/`system`) thay
+   vì suy từ module. Đây là câu hỏi **nghiệp vụ**, PO trả lời được. Từ vựng step lấy theo platform:
+   `web` → *clicks* · `app` → *taps* · `system` → *calls the API*.
+3. In ⚠️ vào report:
+   ```
+   ⚠️ service: unrouted — chưa có mapping cho domain "{domain}"{ platform "{platform}"} trong
+      services: của project-context.yaml.
+      BDD đã sinh xong và ĐÚNG — đây là việc của architect, không phải của bạn.
+      Architect thêm mapping → /validate-traces tự nâng unrouted → path, KHÔNG cần chạy lại lệnh này.
+      /generate-code sẽ DỪNG cho tới khi có mapping (nó cần biết ghi vào repo nào).
+   ```
+
+> **Vì sao không cần chạy lại `/generate-bdd`:** `/validate-traces` đọc lại `services:` **mỗi lần
+> chạy** và nâng `unrouted` → path khi mapping xuất hiện — cùng cách nó đã làm với `spec_ver`.
+> Sổ **tự lành**.
+
 ### Phân giải `active_platform` (umbrella mode)
 
 Umbrella mode không hỏi platform (khác spec repo mode) — nó **suy** từ module của service. Bắt buộc phải có giá trị: `active_platform` đi vào **path file**, vào **header `@trace.platform`**, và vào **tên sổ trace** `{UC-ID}-{platform}.tsv`.
@@ -505,7 +533,18 @@ Trước khi sinh, kiểm tra các file `.feature` có sẵn cho PRD này:
        F — gen lại toàn bộ scenario
        N — huỷ
      ```
-  3. Tiếp tục theo lựa chọn của người dùng. **Nếu changelog row không nêu rõ UC/AC/BR bị đổi (mơ hồ) → khuyến nghị F** (gen lại toàn bộ) thay vì Y, để khỏi sót scenario bị ảnh hưởng (lưới an toàn — không chắc đổi ở đâu thì quét rộng).
+  3. Tiếp tục theo lựa chọn của người dùng — nhưng **khuyến nghị Y hay F thì đọc `{changelog_scope}` của các row đó** *(contract: `bin/trace-schema.json` → `changelog_row_contract`; cùng dữ liệu `/validate-traces` Step 4 dùng để lọc 🟠 vs ⓘ)*:
+
+     Mỗi mệnh đề trong `{changelog_scope}` mở đầu bằng đơn vị sở hữu (`{UC-ID}:` hoặc `PRD-global:`). Dựng `affected_ucs` **theo đúng ba bước của `/validate-traces` Step 4**, gồm cả bước 2 — phép phân giải **`BR/AC → UC sở hữu`**: `BR{n}` → UC có BR đó trong bảng Business Rule (PRD §3) · `AC{n}` → UC có AC đó ở dòng `**AC liên quan:**`. Rồi:
+
+     | Tình trạng row trong khoảng | Khuyến nghị |
+     |---|---|
+     | **Bất kỳ** row **mơ hồ** (không nêu được đơn vị sở hữu, hoặc BR/AC không phân giải được về UC) | **F** — gen lại toàn bộ. Không chắc đổi ở đâu thì quét rộng |
+     | UC của target **có** trong `affected_ucs` | **Y** — cập nhật đúng scenario của UC đó |
+     | UC của target vào `affected_ucs` **CHỈ** qua mệnh đề mang hậu tố **`[no-behavior]`** | **N** — không có gì để gen lại; đó là thay đổi thuần cấu trúc, producer đã chứng minh không đổi hành vi |
+     | UC của target **không** có trong `affected_ucs` | **N** — bump này không đụng UC này. Nhãn version lệch sẽ được `/validate-traces --realign-prd-version` dọn |
+
+     > **Vì sao phải phân giải BR/AC (G53), không chỉ khớp UC-ID:** một row `thêm UC7: AC12-AC14; UC3: sửa BR8` là đúng contract. Nhưng nếu ai ghi thiếu `UC3:` — thành `…; sửa BR8` — thì row **không** mơ hồ (nó nêu đủ ID) mà UC3 vẫn không xuất hiện khi chỉ khớp UC-ID. Kết quả: khuyến nghị **N** cho đúng UC vừa bị đổi hành vi. Phân giải BR8 → UC3 là thứ chặn ca đó, và nó phải giống hệt phép phân giải của `/validate-traces` — hai consumer đọc cùng một dòng thì không được hiểu khác nhau.
 
 ---
 
@@ -602,7 +641,7 @@ Với mỗi UC, ghi vào path trên và set `# @trace.platform: {active_platform
 # @trace.revision: 1  ← field tĩnh; version theo dõi bằng @trace.bdd_version
 # @trace.domain: <domain>
 # @trace.platform: {active_platform — web | app | system}   ← BẮT BUỘC mọi mode; phải khớp segment bdd/{platform}/ của path
-# @trace.service: {active_service — BẮT BUỘC mọi mode. "—" ở single-service/spec repo mode; "multi" nếu chưa chốt; "unresolved" nếu routing sai. Nguồn của cột TSV `service` — trace gộp không tách theo service nên đây là chỗ DUY NHẤT mang thông tin sở hữu}
+# @trace.service: {service của ĐÚNG platform file này — BẮT BUỘC mọi mode. Nguồn của cột TSV `service`; trace gộp không tách theo service nên đây là chỗ DUY NHẤT mang thông tin sở hữu ở cấp row. Bốn giá trị: {path} · "unrouted" (chưa ai quyết repo — HỢP LỆ, cờ 🟠, KHÔNG chặn) · "unresolved" (config sai cấu trúc — bug) · "—" (single-service). KHÔNG ghi "multi": file này đã có MỘT platform xác định nên service_candidates.{platform}.path đã biết — ghi path đó (G51)}
 # @trace.module: {active_module trong umbrella mode; "unknown" trong spec repo mode}
 # @trace.status: draft
 # @trace.author: AI-generated
@@ -816,7 +855,7 @@ sc_id\tsc_title\tspec_ver\tgen_ver\timplemented_by\ttest_count\ttest_classes\tde
 | `fe_phase` | `—` (set bởi `/generate-code --phase` khi FE implement) |
 | `status` | `UNTRACKED` |
 | `last_updated` | hôm nay `YYYY-MM-DD` |
-| `service` | `@trace.service` từ header `.feature` — đội/submodule sở hữu scenario này. `multi` nếu chưa chốt (map-theo-platform ở cấp PRD), `unresolved` nếu domain không khớp entry nào, `—` ở single-service mode. **Đừng bỏ trống** — trace gộp không tách theo service nên đây là chỗ DUY NHẤT mang thông tin sở hữu ở cấp row. |
+| `service` | `@trace.service` từ header `.feature` — đội/submodule sở hữu scenario này. Bốn giá trị: `{path}` · **`unrouted`** (chưa ai quyết repo — hợp lệ, cờ 🟠) · `unresolved` (config sai cấu trúc — bug) · `—` (single-service). **Đừng bỏ trống** — trace gộp không tách theo service nên đây là chỗ DUY NHẤT mang thông tin sở hữu ở cấp row.<br>⚠️ **KHÔNG ghi `multi` vào file `.feature`** *(G51)*: khi split theo platform, mỗi file đã có **một** platform xác định nên `service_candidates.{platform}.path` **đã biết** — ghi path đó. `multi` chỉ là trạng thái trung gian ở cấp PRD trong bộ nhớ, không phải giá trị được ghi ra. |
 | `design_spec_version` | `\| **Version** \|` của design-spec đã nạp ở §Design Spec — Gate & Load. `—` cho `system`/backend (không có design-spec), và `—` khi người dùng chọn "Y — vẫn sinh BDD" mà không có design-spec. |
 
 ## Refresh Panel Mirror

package/core/commands/generate-code.md

@@ -191,6 +191,39 @@ Lệnh này giới hạn nghiêm ngặt trong **một file feature** được tr
 
 ---
 
+## Guard — biết ghi code vào REPO NÀO chưa *(chặn CỨNG — G51)*
+
+*Chỉ áp ở umbrella/multi-service (có section `services`). Single-service thì bỏ qua.*
+
+Đọc `@trace.service` từ header `.feature` target (và `service_root` từ context-loader Bước 1.6):
+
+| Giá trị | Hành động |
+|---|---|
+| `{path}` — đã route | Tiếp tục. |
+| **`unrouted`** | **DỪNG.** Chưa ai quyết repo cho domain này. |
+| **`unresolved`** | **DỪNG.** Config sai cấu trúc. |
+| `service_root = null` | **DỪNG.** Không có mốc thư mục để ghi file. |
+
+```
+🔴 Chưa biết ghi code vào repo nào — service của {UC-ID} đang là "{value}".
+
+   Lệnh này ghi file source TƯƠNG ĐỐI với service_root, nên không có mapping thì
+   không có chỗ ghi. (Trước G51 nó ghi source vào một thư mục tên đúng chữ
+   "unresolved/" — im lặng.)
+
+   Sửa: thêm mapping cho domain "{domain}" vào `services:` của .agent/project-context.yaml
+        rồi chạy /validate-traces (nó nâng unrouted → path, sổ tự lành), sau đó chạy lại lệnh này.
+
+   BDD của bạn KHÔNG sai và KHÔNG cần sinh lại — đây là bước cấu hình của architect.
+```
+
+> **Vì sao cổng nằm ở ĐÂY chứ không ở `/generate-bdd`** *(G51)*: PRD/BDD là artifact **nghiệp vụ** —
+> PO biết `domain` và `platform`, không biết repo, và ở feature đầu tiên của domain mới thì chưa ai
+> quyết. Trước G51 cổng đặt ngược: `/generate-bdd` **dừng hẳn** (phase không cần biết) còn lệnh này
+> **không kiểm gì** (phase buộc phải biết). Đây là chỗ duy nhất thật sự không chạy nổi khi thiếu.
+
+---
+
 ## Guard — BDD & Design Spec đã sẵn sàng chưa *(cảnh báo MỀM — đồng bộ generate-bdd)*
 
 **BDD (mọi platform) — DS1:** đọc `# @trace.status:` từ header `.feature` target.

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.
+  - **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 đã 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.
@@ -245,6 +245,38 @@ Lưu `mode` (`fresh` | `append`) và, theo từng UC của batch, hành động
 
 ---
 
+## Bước 1b — Format row Changelog *(contract máy đọc — áp cho CẢ Fresh lẫn Append)*
+
+Row Changelog của tech-doc **không phải ghi chú cho người đọc** — `/validate-traces` Step 5 đọc nó để quyết mỗi UC ăn cờ 🟠 `TECHDOC_DRIFT` hay ⓘ `TECHDOC_STALE_REF`.
+
+Format *(contract: `bin/trace-schema.json` → `changelog_row_contract`)*:
+
+```
+| {revision} | {YYYY-MM-DD} | {changelog_scope} |
+```
+
+**`{changelog_scope}` — mỗi mệnh đề mở đầu bằng UC SỞ HỮU.** Nguồn: các UC trong `input_features` của batch vừa thêm/sửa (Bước 1 đã phân loại từng UC là `add-new` / `extend-platform` / `refresh` / `skip` — UC `skip` **KHÔNG** vào dòng này). Ngăn nhau bằng `;`. Nội dung không thuộc UC nào (§11 Cross-cutting, §2 kiến trúc chung) → `doc-global`.
+
+| Ca | Ví dụ đúng |
+|---|---|
+| Fresh | `1 \| 2026-08-19 \| UC1, UC2: sinh lần đầu từ BDD system v1.4` |
+| Thêm UC mới | `2 \| 2026-08-22 \| UC3: thêm §5.9 sequence + §10 coverage, từ BDD system v1.0` |
+| Thêm platform cho UC đã phủ | `3 \| 2026-08-25 \| UC1: thêm block client web §4.5.1.2, từ BDD web v1.2` |
+| Refresh vì BDD bump | `4 \| 2026-08-28 \| UC2: refresh §4.1 endpoint theo BDD system v1.6` |
+| Chỉ sửa phần chung | `5 \| 2026-08-30 \| doc-global: bổ sung §11 chuẩn logging` |
+
+*(Tech-doc **không** dùng hậu tố `[no-behavior]` — `doc-global` đã đủ: không nêu UC nào thì không UC nào ăn cờ. Marker đó chỉ dành cho producer biết chính xác `check_id` của từng fix mình vừa áp, tức `/review-context --fix`.)*
+
+> **Vì sao khai format ở đây (G58).** Trước đó Bước 1 và §Sinh chỉ nói *"thêm một row Changelog"* — **không format, không ví dụ, không nhắc phải nêu UC**. Trong khi `/validate-traces` Step 5 lọc 🟠-vs-ⓘ **bằng chính row đó**, và chế độ APPEND bump `@trace.revision` chung cho cả doc nên **mọi UC cũ lệch revision** dù phần của chúng không đổi một dòng.
+>
+> Chỗ duy nhất có format là một **comment HTML** trong `templates/tech-design.template.md` — mà chế độ APPEND theo định nghĩa **không đọc lại template**. Nên contract đang phụ thuộc vào việc agent tình cờ nhìn thấy một dòng comment ở file khác. Chưa nổ vì ví dụ trong comment tình cờ đúng; đây là nợ chờ lệch, cùng lớp với G52/G53.
+>
+> Hai kiểu viết sai và hậu quả — **đối xứng hoàn toàn với phía PRD**:
+> - **Mơ hồ** (`cập nhật tech design`) → Step 5 gắn 🟠 cho **MỌI** UC của doc. Ồn tới mức cờ mất giá trị.
+> - **Nêu §/SC mà bỏ UC** (`thêm §5.9, §10`) → nêu đủ ID để **không** bị coi là mơ hồ, nhưng Step 5 khớp theo **UC**; nên UC vừa được thêm lại rơi vào ⓘ và `--realign-techdoc-revision` sẽ dán nhãn lại. Im lặng.
+
+---
+
 ## Bước 2 — Cổng Chất lượng (mọi feature nguồn)
 
 Với **mỗi** feature BDD trong scope:
@@ -346,7 +378,7 @@ 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. 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}` + 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`).
 
 <!--
   ════════════════════════════════════════════════════════════════════════════

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

@@ -222,7 +222,7 @@ Sau khi chạy, cập nhật **sổ của platform đang test** `{paths.trace_di
 
 | Cột | Giá trị |
 |--------|-------|
-| `qc_status` | `pass` nếu mọi QC test của SC này pass · `fail` nếu có cái fail · `skip` nếu tất cả skip/xfail · `not_run` nếu không QC test nào phủ nó |
+| `qc_status` | Đọc cột `status` của row **TRƯỚC** — xem §Guard ngay dưới bảng. Row `OK`/`GAP`/`UNTRACKED`: `pass` nếu mọi QC test của SC này pass · `fail` nếu có cái fail · `skip` nếu tất cả skip/xfail · `not_run` nếu không QC test nào phủ nó. Row **`DRIFT`/`ORPHANED`**: **không bao giờ ghi `pass`** — hạ về `not_run` |
 | `qc_run_at` | hôm nay `YYYY-MM-DD` |
 | `last_updated` | hôm nay `YYYY-MM-DD` |
 | `qc_owner` | **SC đang chờ ai** (view "pending" của PM/PO): `dev` nếu FAIL = product-gap (defect thật → dev fix) · `po` nếu `skip`/`not_run` vì một **`DOC_GAPS` 🔴 Blocker đang open** chặn test (PO phải làm rõ PRD/BDD) · `—` nếu `pass`, hoặc FAIL = script-bug (QC tự fix — tạm thời) |
@@ -232,9 +232,35 @@ Set `qc_owner`/`qc_blocked_by` cùng với `qc_status`. Khi `pass`, **clear** c
 Với FAIL product-gap, set `qc_owner=dev` ngay; `BUG-{id}` được backfill vào `qc_blocked_by`
 khi QC chạy `/report-bug` mà `/qc-report` nhắc.
 
+### Guard — ĐỌC `status` trước khi ghi `pass` *(bắt buộc)*
+
+*Contract: `bin/trace-schema.json` → `positive_assertion_guards`. Đối xứng hoàn toàn với `/dev-run-test`; dữ liệu đã có trong sổ, không phát sinh I/O.*
+
+`pass` **không** mang nghĩa *"QC test đã chạy và xanh"*. Nó mang nghĩa **"scenario này đã được nghiệm thu theo spec HIỆN TẠI"**.
+
+| `status` của row | `qc_status` ghi gì | `qc_run_at` |
+|---|---|---|
+| `OK` · `GAP` · `UNTRACKED` | như bảng trên | hôm nay |
+| **`DRIFT`** | test **pass** → **`not_run`** *(KHÔNG `pass`)* · **fail** → **`fail`** như thường · **skip** → `skip` như thường | `—` nếu ghi `not_run` |
+| **`ORPHANED`** | **`not_run`** — scenario đã bị xoá khỏi `.feature` | `—` |
+
+**Chỉ `pass` bị chặn.** `fail` là tin xấu thật, `skip` là giá trị trung tính — cả hai không phải lời khẳng định nên ghi bình thường. Chặn chúng là biến một guard chống-báo-cáo-sai thành một guard che-tin-xấu.
+
+Khi hạ về `not_run` vì `DRIFT`/`ORPHANED`, **KHÔNG** clear `qc_owner`/`qc_blocked_by` và **KHÔNG** chạy §Đóng bug đã verify — hai bước đó chỉ dành cho `pass` **thật**. Đóng một bug dựa trên một lần QC chạy trên spec đã đổi là đóng sai. In:
+```
+⚠️  {sc_id} — QC test XANH nhưng row đang {DRIFT | ORPHANED}, nên KHÔNG ghi pass.
+    Không bug nào được đóng ở lần chạy này cho SC đó.
+    Làm: /generate-code {UC-ID} → /qc-design-test lại → chạy lại lệnh này.
+```
+
+> **Vì sao (GAPS-v4 G55).** Bản cũ khai `qc_status` **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*. `/generate-bdd` hạ `qc_status → not_run` khi spec đổi (kèm lý do *"cái này làm cờ nói dối"*), rồi lần `/qc-run-test` kế tiếp dựng lại `pass` với ngày mới. Ở đây hậu quả còn đi xa hơn `/dev-run-test`: một `pass` sai còn **đóng một bug** (§Đóng bug đã verify) — nên guard phải chặn cả nhánh đó.
+>
+> **Tầng thứ hai độc lập:** `lint-trace` **T12** bắt đúng trạng thái này ở sổ thật, bất kể lệnh nào ghi ra.
+
 Giữ nguyên mọi cột khác — **không bao giờ** đụng `dev_selftest`/`dev_selftest_at`
-(do `/dev-run-test` sở hữu). `qc_status` (QC chính thức) và `dev_selftest` (dev smoke) là
-hai tín hiệu riêng; cả hai trực giao với `status` (OK/GAP/DRIFT/UNTRACKED/ORPHANED = coverage).
+(do `/dev-run-test` sở hữu; nó có guard riêng cùng loại). `qc_status` (QC chính thức) và
+`dev_selftest` (dev smoke) là hai tín hiệu riêng; cả hai trực giao với `status` về **kết quả
+chạy**, nhưng **KHÔNG** trực giao về **quyền khẳng định `pass`** — xem §Guard ở trên.
 
 ## Đóng bug đã verify *(chạy TRƯỚC khi clear `qc_blocked_by`)*
 

package/core/commands/refine-prd.md

@@ -1,5 +1,10 @@
 # /refine-prd — Phân tích PRD qua 3 lăng kính review
 
+> **Ranh giới — lệnh này chỉ áp được fix cho vấn đề mà CHÍNH NÓ tìm ra.** Resume Mode Phase 2 tự
+> cấm đụng bất kỳ section nào không được một finding chấp nhận 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**.
+> Thêm UC/AC/BR mới → `/extend-prd`. **Đổi** một yêu cầu đang đúng cú pháp → **`/amend-prd`**.
+
 ## Gate
 
 *Checkpoint: **chặn CỨNG** — --resume áp findings trực tiếp vào PRD. `--yes` KHÔNG bỏ qua được (gate Bước 3a).*
@@ -621,9 +626,15 @@ Cập nhật `status: "applied"` ở **root level** của file findings (không
 5. Cập nhật `# Change Log` của PRD — **bảng phẳng 1 dòng/version, cửa sổ trượt 5 entry** (nếu gặp format cũ `### v{X}` block → chuẩn hoá sang bảng phẳng khi cập nhật):
    - Thêm row mới lên **đầu** bảng:
      ```
-     | {new_version} | {today} | {tóm tắt — KÈM UC/AC/BR bị ảnh hưởng, vd "UC2: sửa BR5; thêm AC7"} |
+     | {new_version} | {today} | {changelog_scope} |
      ```
-     *(Nêu rõ UC/AC/BR giúp `/generate-bdd` Version Check biết scenario nào cần cập nhật.)*
+     **`{changelog_scope}` — mỗi mệnh đề mở đầu bằng UC SỞ HỮU** *(contract: `bin/trace-schema.json` → `changelog_row_contract`)*. Nguồn: `uc_id` / `section` của các finding được chấp nhận. Ngăn nhau bằng `;`; finding global (`uc_id: ""`) → `PRD-global`.
+
+     **Ví dụ đúng:** `UC2: sửa BR5, thêm AC7; PRD-global: làm rõ scope §1`
+
+     ⚠️ **BR/AC không bao giờ đứng một mình.** `sửa BR5` (thiếu `UC2:`) nêu đủ nhiều ID để **không** bị coi là mơ hồ, nhưng `/validate-traces` Step 4 khớp bằng phép thử *"**UC** này có trong tập?"* — nên UC2 rơi vào ⓘ `PRD_STALE_REF` trong khi BR5 của nó vừa đổi, và `--realign-prd-version` (chỉ chặn 🟠) sẽ dán nhãn version lại lên đó. Đây là G53: mất bộ lọc theo hướng **im lặng**, nguy hiểm hơn hướng mơ hồ/ồn.
+
+     *(Consumer của dòng này: `/generate-bdd` Version Check — biết scenario nào cần cập nhật; `/validate-traces` Step 4 — lọc 🟠 `PRD_DRIFT` vs ⓘ `PRD_STALE_REF`.)*
    - Cập nhật dòng đầu section: `> Hiện tại: **v{new_version}** ({today}) · Lịch sử đầy đủ → [changelog](./changelog/{TICKET-ID}-{prd-slug}.changelog.md)`
    - **Rollover (giữ PRD gọn — đây là chuẩn chung, /review-context cũng theo):** nếu bảng `# Change Log` có **> 5 row** → chuyển **mọi row vượt 5** (cũ nhất) sang **đầu** bảng của file kho `{paths.specs_dir}/{domain}/{prd-slug}/changelog/{TICKET-ID}-{prd-slug}.changelog.md` (giữ thứ tự mới→cũ); PRD chỉ giữ **5 row gần nhất**. Tạo thư mục `changelog/` + file kho nếu chưa có, theo skeleton:
      ```

package/core/commands/review-context.md

@@ -760,14 +760,21 @@ Với mỗi finding có `auto_fixable: true`, theo thứ tự (critical → majo
 
 **Với file PRD:**
 
-| check_id | Áp dụng gì |
-|----------|--------------|
-| P1 (Banned term) | Thay mọi lần xuất hiện banned term bằng canonical term |
-| P1 (Thuật ngữ kỹ thuật/UI) | Diễn đạt lại theo Business Language Guard (Nhóm 1) / chuyển Design Spec (2) / bỏ về Tech Docs (3) |
-| P4 (Structure) | Thêm skeleton section/metadata còn thiếu (row Status vắng → thêm mặc định `draft`); greenfield → xoá section "Existing API Contract" rỗng |
+| check_id | Áp dụng gì | Đổi hành vi? |
+|----------|--------------|:---:|
+| P1 (Banned term) | Thay mọi lần xuất hiện banned term bằng canonical term | **CÓ** |
+| P1 (Thuật ngữ kỹ thuật/UI) | Diễn đạt lại theo Business Language Guard (Nhóm 1) / chuyển Design Spec (2) / bỏ về Tech Docs (3) | **CÓ** |
+| P4 (Structure) | Thêm skeleton section/metadata còn thiếu (row Status vắng → thêm mặc định `draft`); greenfield → xoá section "Existing API Contract" rỗng | KHÔNG |
 
 > **Chạy Business Language Guard trên text vừa sửa TRƯỚC khi ghi** (xem section "Ngôn ngữ nghiệp vụ") — không để bản auto-fix tự kéo thuật ngữ kỹ thuật vào.
 
+**Cột "Đổi hành vi?" là đầu vào của Phase 3** — nó quyết định UC bị đụng có ăn cờ 🟠 `PRD_DRIFT` hay ở lại ⓘ. Ghi lại `check_id` + `uc_id` của **từng** finding vừa áp; Phase 3 cần cả hai.
+
+| | Nghĩa | Vì sao |
+|---|---|---|
+| **CÓ** | Câu văn nghiệp vụ trong PRD đã khác đi | P1 banned-term: term đó **cũng nằm trong `.feature` đã sinh** nên BDD lỗi thời thật về thuật ngữ (B2/C4 sẽ bắt) — đổi từ trong PRD mà không nêu UC là **bỏ sót**, không phải trung tính. P1 tech-jargon: auto-fix của nó **viết lại câu** AC/BR, và nhánh 2/3 **lấy nội dung ra khỏi** PRD |
+| **KHÔNG** | Chỉ thêm/bỏ vỏ cấu trúc, 0 nội dung nghiệp vụ mới | Thêm một heading rỗng hay row `Status` mặc định không làm BDD của UC đó lỗi thời. Đánh dấu nó là drift chính là **báo động giả** |
+
 **Với file BDD:**
 
 | check_id | Áp dụng gì |
@@ -786,8 +793,29 @@ Sau khi áp dụng mỗi finding, đánh dấu nó `status: "applied"` + `applie
 
 ### Phase 3 — Version bump
 
-- **PRD**: nếu ≥1 finding được áp dụng → bump version **minor** (auto-fix chỉ áp dụng thay banned-term P1 và thêm skeleton P4 — không bao giờ thay đổi cấu trúc UC hay nội dung BR, nên minor bump luôn đúng), **reset `| **Status** | draft |` trong Metadata** (PRD vừa đổi sau khi duyệt → con dấu duyệt cũ hết hiệu lực, phải duyệt lại — đồng bộ với /refine-prd), thêm entry Changelog:
-  `| {new_version} | {today} | Auto-fix: applied {N} auto-fixable findings |` — bảng phẳng + **rollover giữ 5 row gần nhất** (dồn dư sang `changelog/{TICKET-ID}-{prd-slug}.changelog.md`); xem quy ước đầy đủ ở refine-prd Phase 3.
+- **PRD**: nếu ≥1 finding được áp dụng → bump version **minor** (auto-fix **không bao giờ thêm/xoá UC và không tái cấu trúc scope** — kể cả P1 tech-jargon nhánh 2/3, thứ nó di dời là *chi tiết cơ chế* xuống đúng tầng, ý định nghiệp vụ không đổi; nên minor luôn đúng), **reset `| **Status** | draft |` trong Metadata** (PRD vừa đổi sau khi duyệt → con dấu duyệt cũ hết hiệu lực, phải duyệt lại — đồng bộ với /refine-prd), thêm entry Changelog:
+
+  `| {new_version} | {today} | Auto-fix — {changelog_scope} |` — bảng phẳng + **rollover giữ 5 row gần nhất** (dồn dư sang `changelog/{TICKET-ID}-{prd-slug}.changelog.md`); xem quy ước đầy đủ ở refine-prd Phase 3.
+
+  **`{changelog_scope}` — BẮT BUỘC, dựng từ `uc_id` + `check_id` của các finding `status: applied`** *(contract: `bin/trace-schema.json` → `changelog_row_contract`)*:
+
+  1. Gom các finding vừa áp theo `uc_id`. `uc_id: ""` → nhóm `PRD-global`.
+  2. Mỗi nhóm thành một mệnh đề `{uc_id}: {tóm tắt các check}`, ngăn nhau bằng `;`.
+  3. Nhóm mà **mọi** finding trong đó đều ở hàng **"Đổi hành vi? KHÔNG"** (Phase 2) → gắn hậu tố **`[no-behavior]`**. Nhóm có **dù chỉ một** finding "CÓ" → **KHÔNG** gắn.
+
+  ```
+  | 1.4 | 2026-08-19 | Auto-fix — UC5: banned-term (khách hàng→người mua); PRD-global: skeleton §4b [no-behavior] |
+  ```
+
+  → `/validate-traces`: **UC5 🟠 `PRD_DRIFT`** (đúng — có sửa thật) · **các UC còn lại ⓘ `PRD_STALE_REF`** (đúng — không đụng).
+
+  > **Vì sao BẮT BUỘC (G52).** Bản cũ ghi cứng `Auto-fix: applied {N} auto-fixable findings` — **không nêu UC nào**. `/validate-traces` Step 4 lọc 🟠-vs-ⓘ bằng cách hỏi *"row changelog có nêu UC này không"*, và một row không nêu gì thì rơi vào lưới an toàn *"mơ hồ → 🟠 cho **MỌI** UC"*. Nên sửa một từ trong UC5 của PRD 8 UC làm **cả 8 UC** ăn cờ 🟠 và route sang `/generate-bdd`.
+  >
+  > Lưới an toàn đó **đúng khi thiếu thông tin** — nhưng ở đây **không thiếu**: findings YAML có `uc_id` **bắt buộc** cho mỗi finding, và Phase 2 vừa đánh dấu `status: applied` cho từng cái. Lệnh **đang cầm** câu trả lời lúc nó ghi dòng đó, rồi vứt đi.
+  >
+  > Cái mất không phải 7 lần kiểm vô ích. `--fix` là đường rẻ nhất trong lane PO nên nó chạy nhiều nhất; sau vài sprint `PRD_DRIFT` sáng thường trực, **người đọc học cách bỏ qua, rồi lần lệch THẬT cũng bị bỏ qua cùng** — chính câu `/validate-traces` Step 4 dùng để biện minh cho bộ lọc.
+  >
+  > **Cách làm đúng đã có sẵn ngay dưới đây, ở nhánh BDD:** *"tăng `sc_version` của **đúng scenario đó**… Scenario không bị sửa → **giữ nguyên**… bump vô cớ tạo `DRIFT` giả và làm cờ mất giá trị"*. Nhánh BDD phân loại check theo *có đổi thân scenario hay không* rồi chỉ đánh dấu đơn vị bị đụng. Ba bước trên là **đúng cách đó**, áp cho PRD.
 - **BDD**: nếu ≥1 finding được áp dụng → tăng `@trace.bdd_version` lên 0.1, **reset `# @trace.status: draft`** trong header (BDD đổi sau khi duyệt → phải duyệt lại — đồng bộ với cơ chế reset draft của PRD)
 - **BDD — `@trace.sc_version` theo từng scenario (BẮT BUỘC):** với **mỗi scenario có ≥1 finding được áp dụng làm đổi thân nó** — R3 (diễn đạt lại step), R7 (thay giá trị cụ thể), R9 (thêm cột data table), R10 (thêm Note), B6 (thêm `And` side-effect), B2 (đổi tên entity/field trong step/table) — tăng `# @trace.sc_version` của **đúng scenario đó** lên 0.1. Scenario không bị sửa → **giữ nguyên**.
   - Đây là tín hiệu DUY NHẤT cho `/validate-traces` biết code của SC đó đã lỗi thời (`spec_ver != gen_ver` → `DRIFT`). `bdd_version` ở cấp file không đủ phân giải để biết SC nào cần regen.
@@ -808,6 +836,9 @@ Còn pending (cần quyết định của con người): {N}
   - F00X [{severity}] {tóm tắt finding}  ← mở file findings trong Review Board
 
 {If PRD}: Version bumped: {old} → {new}  |  Status: reset về draft (cần duyệt lại)
+{If PRD}: Changelog : | {new} | {today} | {changelog_scope} |
+           ↳ UC sẽ hiện 🟠 PRD_DRIFT: {UC5}  ·  UC ở lại ⓘ STALE_REF: {UC1-4, UC6-8}
+             (nhóm [no-behavior] và UC không đụng → KHÔNG cần /generate-bdd)
 {If BDD}: bdd_version: {old} → {new}  |  @trace.status: reset về draft (cần duyệt lại)
 {If BDD, chỉ khi có ≥1 SC bump}: sc_version: {UC-ID}-SC2 1.0→1.1, {UC-ID}-SC5 1.2→1.3
            ↳ {n} SC này sẽ hiện DRIFT ở /validate-traces → /generate-code {feature-file} để sinh lại
@@ -862,7 +893,8 @@ Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "
 | P4 (Structure) | Thêm section/metadata field còn thiếu (row Status vắng → thêm mặc định `draft`) |
 | P5 (Custom) | Áp dụng như nêu trong suggestion/note |
 
-→ Sau khi áp dụng, bump version PRD (minor), **reset `| **Status** | draft |` trong Metadata** (PRD vừa đổi sau khi duyệt → phải duyệt lại — đồng bộ với /refine-prd), thêm row Changelog (bảng phẳng, **kê UC/AC/BR bị ảnh hưởng**, + **rollover giữ 5 row gần nhất** dồn dư sang `changelog/` — xem quy ước ở refine-prd Phase 3), và ghi `applied_to_version: "{new_version}"` ở root level của findings (xem "Chọn full vs delta").
+→ Sau khi áp dụng, bump version PRD (minor), **reset `| **Status** | draft |` trong Metadata** (PRD vừa đổi sau khi duyệt → phải duyệt lại — đồng bộ với /refine-prd), thêm row Changelog `| {new_version} | {today} | {changelog_scope} |` (bảng phẳng + **rollover giữ 5 row gần nhất** dồn dư sang `changelog/` — xem quy ước ở refine-prd Phase 3), và ghi `applied_to_version: "{new_version}"` ở root level của findings (xem "Chọn full vs delta").
+  **`{changelog_scope}` dựng theo đúng 3 bước ở Phase 3 của `--fix`** — gom theo `uc_id`, mỗi nhóm một mệnh đề `{uc_id}: {mô tả}`, `uc_id: ""` → `PRD-global`. Ở Resume Mode phần lớn finding là loại **con người quyết** nên **đổi hành vi** — chỉ gắn `[no-behavior]` cho nhóm thuần cấu trúc (P4). **BR/AC phải đi KÈM UC sở hữu** (`UC3: sửa BR8`), không bao giờ đứng một mình: consumer khớp theo UC, nên `sửa BR8` trơ trọi làm UC3 bị xếp ⓘ trong khi BR8 vừa đổi (G53).
 
 **Với finding BDD:**
 | check_id | Làm gì |
@@ -892,6 +924,9 @@ Changes:
   - {tóm tắt change 2}
 
 {If PRD}: Version bumped: {old} → {new}  |  Status: reset về draft (cần duyệt lại)
+{If PRD}: Changelog : | {new} | {today} | {changelog_scope} |
+           ↳ UC sẽ hiện 🟠 PRD_DRIFT: {UC5}  ·  UC ở lại ⓘ STALE_REF: {UC1-4, UC6-8}
+             (nhóm [no-behavior] và UC không đụng → KHÔNG cần /generate-bdd)
 {If BDD}: bdd_version: {old} → {new}  |  @trace.status: reset về draft (cần duyệt lại)
 {If BDD, chỉ khi có ≥1 SC bump}: sc_version: {UC-ID}-SC2 1.0→1.1, {UC-ID}-SC5 1.2→1.3
            ↳ {n} SC này sẽ hiện DRIFT ở /validate-traces → /generate-code {feature-file} để sinh lại

package/core/commands/sync.md

@@ -180,6 +180,90 @@ Nếu người đọc là PO/Dev, thêm một dòng nudge:
 
 ---
 
+## Step 1e — Spec delta: **tài liệu nào vừa đổi** *(hai mốc, hai câu hỏi khác nhau)*
+
+*Câu hỏi số MỘT của dev sau mỗi lần sync là "tài liệu của phần tôi đang làm có đổi không?". Step này trả lời nó. Range `{old_sha}..{new_sha}` đã thu ở Step 1c — không phát sinh fetch.*
+
+> **Vì sao step này tồn tại (GAPS-v4 G56).** Bản cũ diff **đúng ba** đường dẫn ở Step 1d —
+> `feedback/bug-reports/`, `feedback/bdd-proposals/`, `feedback/prd-change-requests/` — và
+> `specs/` **không có trong danh sách**. Tức `/sync` hỏi *"có góp ý gì mới không"* (đúng và hữu ích)
+> rồi bỏ qua **chính tài liệu mà mọi lệnh downstream đọc**: PRD · BDD · tech-doc · design-spec.
+>
+> Nó **đang cầm sẵn câu trả lời**: Step 1c vừa thu cả hai đầu SHA, và Step 1d đã chạy một `git diff`.
+> Thêm `specs/` là thêm **một tham số đường dẫn**.
+>
+> Thay vào đó, dòng `Next` in cứng `/validate-traces (full coverage check)` — **y hệt nhau** dù 0 file
+> đổi hay 12 file đổi. Một lời nhắc không bao giờ thay đổi thì **không mang thông tin**, nên bị lướt.
+> Đây đúng lập luận `gate.md` Bước 3b dùng để cắt CHECKPOINT xuống hai dòng khi mọi thứ sạch —
+> *"cổng luôn in ra một bảng giống hệt nhau … nên `Y` thành phản xạ và cổng hỏng âm thầm"*. Nguyên
+> tắc đó đã áp cho `gate`; đây là chỗ nó còn thiếu.
+>
+> Và tệ hơn: lệnh duy nhất được gợi ý là lệnh **đắt nhất** (quét cả repo). Nên con đường duy nhất
+> được chỉ là con đường người ta sẽ không đi. Step này làm nó **có scope**.
+>
+> **Đây KHÔNG phải một detector bị hỏng** — mọi detector đều hoạt động đúng. Đây là một **công tắc
+> bị thiếu**: không ai biết là cần bật.
+
+Bỏ qua **im lặng** nếu `{paths.specs_dir}` không tồn tại trong REPO (chọn REPO + range theo đúng quy tắc Step 1d).
+
+### 1e-A — Đổi gì kể từ lần **PULL** trước
+
+```bash
+git -C {REPO} diff --name-status {old_sha}..{new_sha} -- specs/
+```
+
+Nhóm kết quả theo **feature-package** (`specs/{domain}/{prd-slug}/`), và với mỗi file đổi, đọc **nhãn version ở hai đầu** — thứ dev cần không phải tên file mà là *nhãn đã nhảy chưa*:
+
+| Loại file | Nhãn đọc ở đâu | Bản cũ đọc bằng |
+|---|---|---|
+| PRD (`.md` ở gốc package) | Metadata `\| **Version** \|` + row `# Change Log` đầu bảng | `git -C {REPO} show {old_sha}:{path}` |
+| `.feature` | `# @trace.bdd_version` | như trên |
+| `tech-docs/*-tech-design.md` | `@trace.revision` | như trên |
+| `design-spec/*.md` | `\| **Version** \|` | như trên |
+
+**Cap có công bố:** > **20** file đổi → **bỏ** phần đọc nhãn (mỗi file là một `git show`), chỉ liệt kê package + số file, và **in rõ là đã cap**:
+`ⓘ {n} file đổi (> 20) — bỏ phần so nhãn version để không làm chậm sync. Chạy /validate-traces để có bản đầy đủ.`
+*(Luật framework: cap thì phải nói ra. Một giới hạn im lặng đọc như "đã phủ hết" trong khi không phải.)*
+
+### 1e-B — Đổi gì kể từ lần **AUDIT** gần nhất ⭐
+
+*Đây là phần 1e-A **không** trả lời được, và là câu hỏi đúng hơn.*
+
+Diff `{old_sha}..{new_sha}` **reset mỗi lần pull**. Pull thứ Hai, thứ Ba, thứ Tư mà không audit lần nào → đến thứ Năm cái thấy được chỉ là delta của **một ngày**, không phải nợ đã tích.
+
+Đọc mốc **`spec_baseline`** trong `{living_docs_dir}/trace-report.json` — khối do `/validate-traces` Step 6b ghi (contract: `bin/trace-schema.json` → `spec_edit_detection`). Mỗi entry: `prd_path` · `sha_at_audit` · `version_at_audit`.
+
+*Phân giải `living_docs_dir` bằng đúng quy tắc một dòng của Step 5: `{spec_source}/.living-docs` nếu `setup.spec_source` được set, else `.living-docs` ở gốc.*
+
+Với mỗi PRD có entry: so `Version` **hiện tại** với `version_at_audit`.
+
+| Điều kiện | In gì |
+|---|---|
+| Khác nhau | PRD này đã đổi kể từ lần audit — vào danh sách ⚠️ |
+| Bằng nhau | Bỏ qua *(và `/validate-traces` Step 3.9 sẽ lo ca "nội dung đổi mà nhãn không đổi" — không phải việc của step này)* |
+| Không có `trace-report.json`, hoặc khối `spec_baseline` vắng | In `ⓘ Chưa có mốc audit — chạy /validate-traces một lần để Step 1e-B có hiệu lực từ lần sau.` rồi bỏ qua |
+
+**KHÔNG ghi gì cả.** Step này chỉ **đọc** mốc; chủ sở hữu của `spec_baseline` là `/validate-traces` Step 6b. `/sync` ghi mốc sẽ làm mốc audit trượt theo mỗi lần pull — tức phá đúng thứ nó đang dùng.
+
+### Xuất
+
+```
+📄 Spec đã đổi (pulled this sync):
+   payment/create-invoice   PRD v1.2 → v1.4
+                            changelog: UC2: sửa BR5; UC7 mới
+                            bdd/web/PAY01-UC2.feature   (bdd_version 1.3 → 1.4)
+   user/create-account      tech-docs/USR01-tech-design.md   (revision 3 → 4)
+   (hoặc: 📄 Spec: không đổi trong lần pull này)
+
+⚠️  3 PRD đã đổi kể từ lần /validate-traces gần nhất (KHÔNG chỉ lần pull này):
+       payment/create-invoice   audit tại v1.2 · giờ v1.4
+       user/create-account      audit tại v2.0 · giờ v2.1
+       order/bulk-export        audit tại v1.0 · giờ v1.3
+    → /validate-traces {các PRD trên}
+   (hoặc: ✅ Mọi PRD đã được audit ở version hiện tại)
+```
+
+---
 ## Step 2 — Post-sync State Check
 
 Chạy `git status --short` và kiểm tra entry submodule bị modified (dòng bắt đầu bằng ` M` mà path khớp một submodule).
@@ -396,6 +480,22 @@ Umbrella state
   ⚠️ Pointer changed: git add {spec_source} && git commit -m "chore: sync specs"
   (or: ✅ Clean — no commit needed)
 
+Spec đã đổi (pulled this sync)                       ← Step 1e-A
+  📄 payment/create-invoice   PRD v1.2 → v1.4
+                              changelog: UC2: sửa BR5; UC7 mới
+                              bdd/web/PAY01-UC2.feature (bdd_version 1.3 → 1.4)
+     user/create-account      tech-docs/USR01-tech-design.md (revision 3 → 4)
+  (hoặc: 📄 Spec: không đổi trong lần pull này)
+  (hoặc: ⓘ 34 file đổi (> 20) — đã bỏ phần so nhãn version cho nhanh)
+
+Nợ audit đã tích (KHÔNG chỉ lần pull này)             ← Step 1e-B
+  ⚠️ 3 PRD đã đổi kể từ lần /validate-traces gần nhất:
+       payment/create-invoice   audit tại v1.2 · giờ v1.4
+       user/create-account      audit tại v2.0 · giờ v2.1
+       order/bulk-export        audit tại v1.0 · giờ v1.3
+  (hoặc: ✅ Mọi PRD đã được audit ở version hiện tại)
+  (hoặc: ⓘ Chưa có mốc audit — chạy /validate-traces một lần để có hiệu lực từ lần sau)
+
 Tester feedback (pulled this sync)
   📥 1 bug report:  BUG-20260608-01 FT-001 [Code]
      1 proposal:    FT-001-trailing-spaces → AC2 (pending review)
@@ -426,5 +526,9 @@ Spec Manifest
 ---
 Status : ✅ Complete | ⚠️ Warnings
 Output Artifacts: updated .trace-mirror/ (panel mirror), spec-manifest.yaml
-Next   : /validate-traces (full coverage check) | /generate-code {UC-ID} (start coding)
+                  (Step 1e chỉ ĐỌC — nó không bao giờ ghi spec_baseline; chủ sở hữu là /validate-traces Step 6b)
+Next   : {phụ thuộc kết quả Step 1e — KHÔNG in một hằng số}
+           • có PRD trong danh sách 1e-B → /validate-traces {các PRD đó}
+           • 1e-B sạch, 1e-A có đổi      → /generate-code {UC-ID} cho phần vừa đổi
+           • cả hai sạch                 → ✅ Spec khớp audit — không cần audit lại
 ```