@edupia-tutor/spec-driven-docs 0.14.7 → 0.14.9

package/core/commands/generate-bdd.md

@@ -401,7 +401,20 @@ Sau khi hoàn thành tất cả các bước, bạn đã nạp:
 Tiếp tục sang bước kế tiếp của lệnh đang gọi.
 
 
-> **Proposal của tester (input tuỳ chọn):** trước khi sinh, kiểm tra `{paths.bdd_proposals_dir}/` (mặc định `{spec_source}/feedback/bdd-proposals/`) tìm các scenario mà tester đề xuất qua `/propose-scenario` ứng với AC của UC này. Đưa vào những cái PO/Dev đã chấp nhận — rồi draft của tester được xoá/lưu trữ khỏi `feedback/`. Bỏ qua nếu folder rỗng.
+> **Proposal của tester (input tuỳ chọn):** trước khi sinh, quét `{paths.bdd_proposals_dir}/` (mặc định `{spec_source}/feedback/bdd-proposals/`) tìm `{UC-ID}-*.md`. Với mỗi proposal:
+> - `Status: accepted` (PO/Dev đã duyệt) → chèn scenario vào `.feature` của UC (giữ `@trace`), rồi **lưu trữ**: chuyển file sang `{paths.bdd_proposals_dir}/archived/` + đặt `Status: incorporated`, và **commit + push** spec repo để gỡ khỏi feedback chung.
+> - `Status: proposed`/`rejected` (hoặc thiếu `Status`) → **bỏ qua**, để nguyên cho PO/Dev xử lý (KHÔNG tự đoán, KHÔNG tự đưa vào).
+> Bỏ qua sạch nếu folder rỗng.
+
+---
+
+## Sub-Agent Mode — dùng state từ payload *(nếu `_agent_mode`)*
+
+*Chỉ khi Gate Step 0 phát hiện `_agent_mode: true` (đang chạy như sub-agent do orchestration spawn).* Orchestrator (session chính) đã chạy các Guard + chọn platform + nạp design-spec **một lần**; sub-agent KHÔNG lặp lại:
+- `active_platform` = `payload.active_platform` → **bỏ qua** Platform Selection / Service Detection.
+- `design_coverage` = `payload.design_coverage` → **bỏ qua** "Design Spec — Gate & Load"; nếu rỗng thì chỉ phủ Wireframe PRD.
+- **Bỏ qua** Guard "PRD đã duyệt" + Guard Design-Spec bên dưới (orchestrator đã kiểm).
+- Đi thẳng tới UC Decomposition + Generate cho `payload.uc_id`, dùng `design_coverage` để phủ Screen States + AC-UI.
 
 ---
 
@@ -609,6 +622,41 @@ Chỉ cần kiểm tra trạng thái đã phân giải:
 
 ---
 
+## Design Spec — Gate & Load (chỉ FE/App)
+
+*Chỉ chạy khi target platform là FE/App — spec mode: `active_platform ∈ {web, app, app-ios, app-android}`; umbrella mode: `active_module` là module FE/App (react/nextjs/vue/nuxt/angular/flutter/react-native/ios-swiftui/android-compose). Bỏ qua HOÀN TOÀN với `system` và backend/brownfield.*
+
+**1. Định vị design-spec của platform:**
+`{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md`
+- `app-ios`/`app-android` không có bản riêng → fallback bản `-app-`.
+
+**2. Guard — sign-off & độ tươi (cảnh báo MỀM, đồng bộ Guard PRD — không chặn cứng):**
+Đọc `| **Status** |` và `| **Built from PRD** |` từ Metadata design-spec.
+- Không tìm thấy file, HOẶC `Status ≠ approved`, HOẶC design-spec còn màn ❌ Missing, HOẶC `Built from PRD` ≠ `| **Version** |` của PRD hiện tại (design-spec **lỗi thời** so với PRD) → CHECKPOINT:
+  ```
+  ⚠️  Design Spec cho {active_platform} chưa sẵn sàng (Status: {status} / không có / còn màn thiếu Figma / lỗi thời: dựng từ PRD v{old}, PRD giờ v{new}).
+     BDD FE/App nên sinh từ design-spec đã approved & cập nhật để phủ đúng Screen States + AC-UI.
+     Khuyến nghị: hoàn tất / cập nhật design-spec (chạy lại /generate-design-spec nếu PRD đã đổi) rồi mới sinh BDD.
+     Vẫn sinh BDD bây giờ? (Y/N)
+  ```
+  Chỉ tiếp khi chọn Y. Nếu Y mà KHÔNG có design-spec → bỏ qua bước 3 (chỉ phủ Wireframe PRD §4b).
+- `Status: approved` VÀ `Built from PRD` khớp PRD hiện tại → nạp design-spec, sang bước 2.5.
+
+**2.5. Sanity-scan nội dung design-spec** (lớp soi độc lập — D1; soi nhanh ngay tại chỗ đã mở file, trước khi dùng):
+Quét tìm cờ đỏ; nếu có → **cảnh báo mềm** (liệt kê + hỏi "Vẫn dùng design-spec này? (Y/N)"):
+- Màn nào thiếu state `loading`/`error`/`empty`.
+- AC-UI nào mơ hồ, không testable ("looks good" / "đẹp" / không pass-fail rõ).
+- Component còn `[NEW]` / `[TODO]` (chưa chốt với designer).
+- Còn `❌ Missing` frame (lẽ ra Status đã `draft` — approved mà vẫn Missing là bất thường).
+Bắt lỗi design-spec **ngay trước khi nó lan xuống BDD**. Chọn N → quay lại hoàn thiện design-spec; chọn Y → sang bước 3.
+
+**3. Trích coverage từ design-spec** (lưu thành `design_coverage`, dùng ở UC Decomposition + Coverage Matrix):
+- **Screen States** ≠ `default` cho mỗi màn: `loading`, `error`, `empty`, `success` (cái nào có).
+- **AC-UI behavioral**: giữ AC-UI mà cột `Verified by` là **PO/QA** và mô tả outcome quan sát được (lỗi + đường khôi phục, empty state + CTA, gesture điều hướng, có loading state). **LOẠI AC-UI visual thuần** (khớp Figma trong dung sai, tương phản WCAG, màu/pixel/animation — thường `Verified by: Designer`): Designer/QA review riêng, KHÔNG đưa vào Gherkin (giữ R3/R5/R6).
+- **Dedup**: nếu một Screen State / AC-UI đã trùng một AC nghiệp vụ của PRD → không tạo SC mới, chỉ ghi nhận đã phủ.
+
+---
+
 ## Orchestration Check
 
 *Bỏ qua section này nếu đã ở sub-agent mode (Step 0 của Gate đã kích hoạt).*
@@ -655,7 +703,7 @@ Trước khi sinh, kiểm tra các file `.feature` có sẵn cho PRD này:
 - So với version PRD hiện tại.
 - Nếu **giống** → hỏi: "BDD đã sinh từ PRD v{version}. Gen lại? (Y/N)"
 - Nếu **khác** (PRD đã cập nhật):
-  1. Đọc `# Change Log` từ PRD — trích tất cả row mới hơn `@trace.prd_version` của BDD hiện có.
+  1. Đọc `# Change Log` từ PRD — trích tất cả row mới hơn `@trace.prd_version` của BDD hiện có. **Nếu `@trace.prd_version` của BDD CŨ HƠN row cũ nhất còn trong bảng** (lịch sử đã bị cắt sang `changelog/`) → không thấy đủ diff → **khuyến nghị F** (gen lại toàn bộ), đừng tin Y một phần.
   2. Hiện CHECKPOINT:
      ```
      ⚠️  Phát hiện PRD version drift
@@ -670,7 +718,7 @@ 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.
+  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).
 
 ---
 
@@ -693,7 +741,7 @@ Trước khi sinh, kiểm tra các file `.feature` có sẵn cho PRD này:
 
 | Check | Rule |
 |-------|------|
-| C.1 Wireframe Coverage | Mỗi component/action trong Wireframe có ≥1 SC. |
+| C.1 Wireframe Coverage | Mỗi component/action trong Wireframe (PRD §4b) có ≥1 SC. **FE/App: mỗi Screen State (≠default) và mỗi AC-UI behavioral của design-spec (`design_coverage`) cũng phải có ≥1 SC** — dedup với AC nghiệp vụ PRD; bỏ AC-UI visual thuần. |
 | C.2 PRD Traceability | Mỗi AC và mỗi BR (gồm từng bullet logic) map tới ≥1 SC. |
 | C.3 Business Dictionary | Dùng đúng canonical term từ business-dictionary.md. |
 | C.4 Banned Terms | 0 banned term trong file — grep trước khi gen. |
@@ -742,6 +790,8 @@ Với mỗi UC trong PRD, trình bày outline SC **trước khi sinh**:
   BRs covered: {TICKET-ID}-UC1-BR1, BR2, BR3
 ```
 
+*(FE/App: nếu đã nạp design-spec (xem "Design Spec — Gate & Load"), đưa Screen State ≠default (loading/error/empty) + AC-UI behavioral của `design_coverage` vào outline — dedup với AC nghiệp vụ, đừng tạo SC trùng.)*
+
 CHECKPOINT: "Outline này đúng chưa? Bạn muốn thêm hay bớt SC nào không?" → **Chờ confirm trước khi sinh.**
 
 ---
@@ -787,6 +837,20 @@ Với mỗi UC, ghi vào path đã phân giải ở trên. Dùng từ vựng cho
 # Tham chiếu nhanh các term dùng trong feature này. Chi tiết SoT: business-dictionary.md
 # <Term 1>: <định nghĩa ngắn>
 # <Term 2>: <định nghĩa ngắn>
+#
+# --- Popup/Modal Lifecycle (tùy chọn — BẮT BUỘC nếu feature là popup/modal; Pre-merge yêu cầu) ---
+# - Open trigger:   <khi nào popup hiển thị, vd: click menu sidebar>
+# - Close trigger:  <khi nào popup đóng, vd: F5 / click X / ESC / navigate away>
+# - Refresh model:  <data refresh khi nào, vd: mỗi lần open (NO CACHE) / persisted / polling>
+# - State reset:    <state nào reset khi đóng/mở lại, vd: pagination, expand, dropdown selection>
+#
+# --- Display Logic Matrix (tùy chọn — BẮT BUỘC nếu display logic phụ thuộc ≥2 chiều; Pre-merge yêu cầu) ---
+# Liệt kê đủ ma trận N×M case + map mỗi case → SC. Tên SC theo pattern `<cấu trúc>: <outcome>` (KHÔNG dùng "(Case X)").
+# | # | Dim1 | Dim2 | Format hiển thị        | SC   |
+# |---|------|------|------------------------|------|
+# | 1 | 0    | 0    | `Tên hàng`             | SC{} |
+# | 2 | 0    | 1    | `Tên hàng (đơn vị)`    | SC{} |
+# | ... | ...  | ...  | ...                    | ...  |
 
 Feature: <Feature name>
   As a <role>
@@ -834,11 +898,7 @@ Feature: <Feature name>
     Given <state>
     When <action>
     Then <expected error handling>
-```
 
-### Coverage Matrix & Pre-merge Checklist *(thêm vào cuối mỗi file)*
-
-```gherkin
 # === PRD COVERAGE (C.1 + C.2) ===
 # AC mapping:
 #   AC1 (...) → SC1, SC2
@@ -851,17 +911,25 @@ Feature: <Feature name>
 #     [x] <action 1>  → SC1
 #     [x] <action 2>  → SC2
 #     [ ] <action 3>  → MISSING ← BLOCK MERGE
+# Design Spec coverage (chỉ FE/App — C.1 mở rộng; bỏ khối này nếu không nạp design-spec):
+#   Screen "<screen>": loading → SC?, error → SC?, empty → SC?
+#   AC-UI behavioral: AC-UI3 (lỗi+khôi phục) → SC?, AC-UI4 (empty CTA) → SC?
+#     (bỏ AC-UI visual thuần: AC-UI1 khớp Figma, AC-UI5 WCAG — Designer/QA review riêng)
 
 # === PRE-MERGE CHECKLIST ===
 # - [ ] Mỗi SC có Side-effects + @trace.scenario + @trace.sc_version + @trace.business_rules
 # - [ ] Coverage Matrix: 0 dòng MISSING (C.1)
+# - [ ] FE/App: mỗi Screen State (≠default) + AC-UI behavioral của design-spec có ≥1 SC (C.1 mở rộng)
 # - [ ] Mỗi AC/BR map tới ≥1 SC (C.2)
 # - [ ] 0 banned term (C.4) — grep file trước khi merge
 # - [ ] Feature ≥3 SC có NHÓM grouping theo business theme (C.5)
 # - [ ] Nếu popup/modal: khai báo Popup/Modal Lifecycle trong BUSINESS DEFINITION
 # - [ ] Nếu display logic ≥2 chiều: Display Logic Matrix trong BUSINESS DEFINITION
+
 ```
 
+*(Template `.feature` là **single-source** ở `templates/feature.template` — sửa file đó để đổi cấu trúc mọi `.feature` sinh ra. Coverage Matrix + Pre-merge Checklist nằm ở **cuối** template, thêm vào cuối mỗi file.)*
+
 ---
 
 ## Write Trace State

package/core/commands/generate-code.md

@@ -422,7 +422,24 @@ Lệnh này giới hạn nghiêm ngặt trong **một file feature** được tr
 1. Chỉ file `.feature` đã giới hạn scope
 2. Tech-doc tại `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` (nếu tồn tại)
 3. CLAUDE.md §architecture + §coding_standards
-4. **(chỉ FE/App)** Design Spec tại `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-*{slug}.md` (nếu tồn tại) — nguồn của màn hình, component inventory, và link Figma frame từng-màn.
+4. **(chỉ FE/App)** Design Spec — nạp qua **Guard** bên dưới (gate approved/độ-tươi + sanity), là nguồn của màn hình, component inventory, và link Figma frame từng-màn.
+
+---
+
+## 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.
+- `approved` → tiếp tục. Khác `approved` → CHECKPOINT mềm:
+  ```
+  ⚠️  BDD {UC-ID} đang @trace.status: {status} (chưa duyệt). Code sinh từ BDD chưa chốt có thể phải làm lại.
+     Vẫn sinh code bây giờ? (Y/N)
+  ```
+  Chỉ tiếp khi chọn Y.
+
+**Design Spec (chỉ FE/App — `@trace.platform` = web/app) — DS2:** định vị `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{@trace.platform}-{slug}.md`, đọc `| **Status** |` + `| **Built from PRD** |`:
+- Không có file, HOẶC `Status ≠ approved`, HOẶC còn màn ❌ Missing, HOẶC `Built from PRD` ≠ `| **Version** |` PRD hiện tại (lỗi thời) → CHECKPOINT mềm (liệt kê lý do + "Vẫn dùng design-spec này? (Y/N)"). Nếu Y mà KHÔNG có design-spec → sinh UI từ BDD + Wireframe PRD (thiếu chi tiết visual).
+- **Sanity-scan** (như generate-bdd bước 2.5): màn thiếu state loading/error/empty, AC-UI không testable, component `[NEW]`/`[TODO]` chưa chốt, còn ❌ Missing frame → cảnh báo trong cùng CHECKPOINT.
+- `Status: approved` VÀ `Built from PRD` khớp PRD hiện tại VÀ sạch cờ đỏ → dùng làm nguồn màn hình / component / Figma.
 
 ---
 

package/core/commands/generate-design-spec.md

@@ -455,6 +455,30 @@ Dùng `active_module` và `platform_type` suy ra từ context loading:
 
 ---
 
+## Version Check (PRD drift)
+
+Trước khi sinh, kiểm tra design-spec đã tồn tại cho platform này:
+`{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md`
+Đọc `| **Version** |` hiện tại của PRD từ Metadata (vd `1.3`).
+
+- **Không tồn tại** → sinh mới; ghi `| **Built from PRD** | v{prd_version hiện tại} |`.
+- **Tồn tại** → đọc row `| **Built from PRD** |` của nó, so với `| **Version** |` PRD hiện tại:
+  - **Bằng nhau** → hỏi: "Design Spec đã dựng từ PRD v{x}. Sinh lại? (Y/N)".
+  - **Khác** (PRD đã đổi) → CHECKPOINT drift:
+    ```
+    ⚠️  Phát hiện PRD version drift
+    Design Spec dựng từ PRD v{old}; PRD giờ ở v{new}.
+    Thay đổi kể từ v{old} (đọc # Change Log của PRD):
+      {changelog rows}
+    Options:
+      Y — cập nhật phần ảnh hưởng (màn / flow đổi)
+      F — sinh lại toàn bộ
+      N — huỷ
+    ```
+- Khi sinh / sinh lại → cập nhật `| **Built from PRD** | v{prd_version hiện tại} |`, bump `| **Version** |` Design Spec, **reset `| **Status** | draft |`** (design đổi → sign-off lại), thêm row Changelog.
+
+---
+
 ## Screen Discovery
 
 Từ Section 4 của PRD (User Flow + Wireframe), trích xuất mọi tên screen / page / modal được nhắc tới.
@@ -516,8 +540,8 @@ Nếu một màn chưa có design, gõ  none  cho màn đó.
 
 **Gate bắt buộc (không abort — sinh ra draft):**
 - Nếu **bất kỳ** màn nào ❌ Missing → spec được sinh dưới dạng **draft** với các màn đó
-  được gắn cờ, nhưng `Status` vẫn là `draft` và **sign-off / `/generate-bdd` bị chặn** cho tới khi
-  mọi màn có link frame đọc được, đã fetch. Ghi `missing_frames = [screens]`.
+  được gắn cờ, `Status` giữ `draft` cho tới khi mọi màn có link frame đọc được, đã fetch.
+  `/generate-bdd` FE/App sẽ **cảnh báo mềm** (đồng bộ Guard PRD) nếu sinh BDD khi design-spec chưa `approved`. Ghi `missing_frames = [screens]`.
 - Thêm một AI Assumption cho mỗi màn thiếu: "Không có Figma frame đọc được cho {screen} — spec
   của màn này chỉ là text và không được sign off cho tới khi thêm link `node-id`."
 
@@ -603,6 +627,7 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{
 | **Service**        | {active_service}                                              |
 | **Domain**         | {domain}                                                      |
 | **Business PRD**   | [{TICKET-ID}](../{TICKET-ID}-{prd-slug}.md)                   |
+| **Built from PRD** | v{prd_version — `\| **Version** \|` của PRD lúc sinh; dùng phát hiện drift} |
 | **Figma**          | {figma_url — link file feature} ({linked}/{N} frame đã link)  |
 | **Author**         | {tên PO hoặc "AI-assisted"}                                   |
 | **Created**        | {YYYY-MM-DD}                                                  |
@@ -830,7 +855,7 @@ Exit: {người dùng rời thế nào — back stack / chuyển tab / deeplink
 
 ---
 
-## Quality Checklist *(kiểm tra trước khi ghi)*
+## Self-Review Gate *(cổng tự-rà — bắt buộc chạy trước khi ghi)*
 
 - [ ] Mọi màn trong Screen Inventory có Screen Spec đầy đủ ở Section 2
 - [ ] Mọi màn có tối thiểu các state: default, loading, error
@@ -841,7 +866,12 @@ Exit: {người dùng rời thế nào — back stack / chuyển tab / deeplink
 - [ ] Link cross-reference Business PRD là relative path hợp lệ
 - [ ] Mọi màn có link Figma frame node-level (`?node-id=`) — và các màn có link đã được fetch qua Figma MCP và dùng để ground spec
 - [ ] Mỗi màn ❌ Missing được gắn cờ trong spec (`> [DRAFT — no Figma frame...]`), liệt kê trong Figma Summary, và có một AI Assumption
-- [ ] Nếu bất kỳ màn nào ❌ Missing → Status giữ `draft` và Output bên dưới chặn `/generate-bdd`
+- [ ] Nếu bất kỳ màn nào ❌ Missing → Status giữ `draft` (generate-bdd FE/App cảnh báo mềm, không chặn cứng)
+
+> **Đây là CỔNG, không phải nhắc nhở:** chạy từng mục trên TRƯỚC khi ghi file. Mục nào **FAIL** → **bắt buộc**:
+> 1. ghi một dòng `⚠️ {mục thiếu — màn/section cụ thể}` vào section **"Giả định AI"** của file (đừng để lọt im lặng), VÀ
+> 2. giữ `| **Status** | draft |` (chưa đủ điều kiện để PO+Designer sign-off `approved`).
+> KHÔNG xuất design-spec như "hoàn chỉnh" khi còn mục fail chưa gắn cờ.
 
 ---
 
@@ -967,7 +997,7 @@ Next   : Chia sẻ với Designer → PO + Designer sign-off (Status: approved)
 Status : ⚠️ Warnings — {count} màn không có link Figma frame đọc được: {missing_frames ngăn cách bởi dấu phẩy}
 Output Artifacts:
   created {paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{active_platform}-{slug}.md  (v1.0, draft)
-Next   : 🔒 Sign-off & /generate-bdd bị CHẶN cho tới khi mọi màn có link Figma node-id.
+Next   : 🔒 Khuyến nghị hoàn tất sign-off trước (đủ link Figma node-id); /generate-bdd FE/App sẽ cảnh báo nếu design-spec chưa approved.
          1. Trong Figma: chọn mỗi frame còn thiếu → chuột phải → Copy link to selection
          2. Chạy lại /generate-design-spec {prd-file} → AI fetch & ground các frame mới
 ```

package/core/commands/generate-prd.md

@@ -624,6 +624,8 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 
 ## b. Phạm vi
 
+> **Scope = ranh giới, KHÔNG phải đặc tả.** Mỗi mục một dòng ngắn "làm gì / không làm gì". Đừng nhét **cơ chế** (retry/timeout/nhánh lỗi → BR/BL) hay **định nghĩa thuật ngữ** (vd "điểm khởi tạo = …" → Business Definition / business-dictionary) vào đây.
+
 **In Scope**
 - {hạng mục trong phạm vi 1}
 - {hạng mục trong phạm vi 2}
@@ -642,10 +644,14 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 # 2. Acceptance Criteria
 
 > Mỗi AC kế thừa liên kết "Bắt nguồn từ BR" của Product Definition (Phase 6), remap sang BR ID của PRD. Vì BR ID đã chứa số UC nên ref BR truy ngược được tới đúng UC.
+>
+> **1 AC = 1 tiêu chí NGHIỆM THU (outcome quan sát/kiểm được) + ref BR.** KHÔNG viết cơ chế trong AC (số lần retry, timeout, tên/chủ cờ, nhánh lỗi chi tiết) — cái đó thuộc **BR/BL** ở §3, AC chỉ trỏ tới. Nếu tiêu chí có **nhiều nhánh** → tách **bullet con** (mỗi ý một dòng), đừng dồn thành câu dài. Khi `/refine-prd` làm rõ thêm: chi tiết cơ chế → đẩy sang BR/BL; ở tầng AC thì tách bullet/AC mới — KHÔNG nối mệnh đề vào câu cũ (tránh AC thành "đoạn văn" và trùng BR).
 
 **AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
 
-**AC2:** {…} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
+**AC2:** {Tiêu chí có nhiều nhánh — tách bullet:} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
+  - {nhánh/điều kiện 1 → kết quả kỳ vọng}
+  - {nhánh/điều kiện 2 → kết quả kỳ vọng}
 
 ---
 
@@ -752,11 +758,14 @@ _(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã
 
 # Change Log
 
-### v1.0 — {mô tả} ({date})
+> Hiện tại: **v1.0** ({date}) · Lịch sử đầy đủ → [changelog](./changelog/{TICKET}-{N}-{slug}.changelog.md) *(file kho chỉ tạo khi changelog vượt 5 version)*
+
+<!-- Bảng phẳng, MỘT dòng/version, MỚI NHẤT TRÊN CÙNG. Chỉ giữ tối đa 5 version gần nhất ở đây;
+     cũ hơn → /refine-prd & /review-context tự dồn (rollover) sang file changelog/ ở link trên. -->
 
-| Mục | Thay đổi |
-|-----|----------|
-| — | Bản đầu — sinh từ product-definition. |
+| Version | Date | Changes (UC/AC/BR bị ảnh hưởng) |
+|---------|------|---------------------------------|
+| 1.0 | {date} | Bản đầu — sinh từ product-definition. |
 
 ---
 
@@ -774,6 +783,7 @@ _(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã
 ## Quality Checklist *(kiểm tra trước khi ghi)*
 
 - [ ] Mọi AC đều testable (pass/fail rõ ràng), không có chi tiết kỹ thuật (API/token/DB) hay visual chi tiết (màu sắc, font, animation)
+- [ ] **Altitude (AC vs BR/BL)**: AC chỉ nêu **outcome quan sát/kiểm được + ref BR** — KHÔNG chứa cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi chi tiết); cơ chế nằm ở **BR/BL** (§3). AC không lặp lại nội dung BR nó ref. **Scope** = ranh giới (KHÔNG định nghĩa thuật ngữ / KHÔNG cơ chế)
 - [ ] Mỗi UC có Actor / Description / Pre-condition / Post-condition
 - [ ] §1c "Phụ thuộc liên service" có mặt: kế thừa từ discovery Phase 1 câu 8 (hoặc "Không có" nếu discovery trống); case partner song song có ghi phụ thuộc partner ở đây
 - [ ] Business Rule (WHAT) và Business Logic (HOW) nằm chung bảng 3 cột `ID | Business Rule | Business Logic`

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

@@ -113,6 +113,7 @@ Chờ người dùng trả lời rõ ràng "Y" hoặc "N" rồi mới tiếp t
    Rồi: /review-context --resume {feature-file}  ← áp dụng các finding được chấp nhận còn lại
    Rồi chạy lại: /generate-tech-docs {feature-file}
    ```
+4. **Đồng thời** đọc `# @trace.status:` của `.feature` (tín hiệu duyệt chuẩn — B3): nếu ≠ `approved` → cảnh báo MỀM (đồng bộ qc-analyze/generate-code): "BDD chưa duyệt (@trace.status: {status}) — tech-docs sinh từ BDD chưa chốt có thể phải làm lại. Tiếp tục? (Y/N)". *(Nếu `approved` thì BDD đã sign-off; finding-gate ở trên vẫn chạy để chặn critical sót.)*
 
 ## Context
 # Context Loader — Nạp toàn bộ context dự án

package/core/commands/propose-scenario.md

@@ -466,7 +466,10 @@ Viết Gherkin nhất quán với convention của `/generate-bdd` cho `active_p
 
 Ghi vào `{paths.bdd_proposals_dir}/{UC-ID}-{slug}.md` (phân giải về `{spec_source}/feedback/bdd-proposals/` ở umbrella mode; tạo dir nếu cần).
 KHÔNG đụng `.feature` canonical. Doc proposal chứa draft + metadata review
-(xem Output). Nếu nguồn là một bug, tham chiếu `BUG-ID` của nó.
+(xem Output), **gồm dòng `Status: proposed`**. Nếu nguồn là một bug, tham chiếu `BUG-ID` của nó.
+
+> **Vòng đời proposal** (máy đọc được để `/generate-bdd` intake đúng):
+> `proposed` → PO/Dev duyệt đặt `accepted` (hoặc `rejected`) → `/generate-bdd` chèn cái `accepted` vào `.feature` rồi đặt `incorporated` + lưu trữ. **Chỉ `accepted` mới được đưa vào BDD.**
 
 ## Step 5 — Handoff (để PO/Dev thực sự thấy)
 
@@ -612,7 +615,8 @@ Scenario đề xuất (DRAFT — chờ PO/Dev review):
 
 Để PO/Dev promote:
   [ ] AC mapping đúng? (hoặc cập nhật PRD nếu requirement thực sự mới)
-  [ ] Thêm scenario vào {bdd_path} (sửa, hoặc chạy lại /generate-bdd nếu PRD đổi)
+  [ ] Đặt `Status: accepted` trong file proposal (để /generate-bdd đưa vào)
+  [ ] Chạy lại /generate-bdd {UC-ID} — nó tự chèn proposal `accepted` vào .feature rồi lưu trữ
   [ ] Rồi: /generate-code {UC-ID} + /dev-gen-test {UC-ID}
 
 Handoff : {✅ committed + pushed to spec repo | ⚠️ chạy git command ở trên / mở PR}

package/core/commands/qc-analyze.md

@@ -411,6 +411,20 @@ Sau khi hoàn thành tất cả các bước, bạn đã nạp:
 Tiếp tục sang bước kế tiếp của lệnh đang gọi.
 
 
+---
+
+## Guard — BDD đã duyệt chưa
+
+Đọc `# @trace.status:` từ header file `.feature` của UC target:
+- `approved` → tiếp tục bình thường.
+- `draft` (hoặc khác `approved`) → **CHECKPOINT cảnh báo mềm** (không chặn cứng — cho phép QC sớm/prototype):
+  ```
+  ⚠️  BDD của {UC-ID} đang ở @trace.status: {status} (chưa duyệt). QC chạy trên BDD chưa chốt có thể phải làm lại.
+     Khuyến nghị: review-context (BDD) sạch + người duyệt đặt `# @trace.status: approved` rồi mới chạy QC.
+     Vẫn chạy QC bây giờ? (Y/N)
+  ```
+  Chỉ tiếp khi chọn Y.
+
 ---
 
 ## Role

package/core/commands/refine-prd.md

@@ -574,6 +574,13 @@ mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
    List ONLY real, additional issues NOT already in the list — gaps, ambiguities,
    contradictions, missing edge/negative paths, coverage holes, terminology drift,
    structural omissions, and any issue that a fix to an existing finding would expose.
+   ALSO flag ROLE-BOUNDARY / altitude violations (you are NOT limited to adding detail):
+   content sitting in the WRONG section — detailed mechanism (retry counts, timeouts, flag
+   names/owners, error branches) written INSIDE an acceptance criterion or a scope line
+   instead of the Business Rule/Logic section; an AC that merely restates its referenced BR
+   (same content, converged); a term definition crammed into In/Out Scope. For these, the
+   suggestion must be to MOVE the detail to its proper section (AC keeps only the observable
+   outcome + BR ref) — NOT to delete it, and NOT to add more detail.
    Do NOT repeat anything already listed. Return the same finding JSON shape, or [] if
    nothing new.
    ```
@@ -638,8 +645,8 @@ Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
 **DIMENSIONS** = 4 lăng kính dưới đây — fan out một sub-agent cho mỗi lăng kính, mỗi cái quét
 toàn bộ PRD qua đúng lăng kính của nó:
 
-- **Lăng kính QA**: AC có testable không? Edge case đã nêu? Điều kiện biên đã định nghĩa?
-- **Lăng kính DEV**: Input/output API rõ chưa? Business rule có mơ hồ không? Cross-service deps mô tả đủ chưa? Có rủi ro kỹ thuật nào?
+- **Lăng kính QA (tầng nghiệm thu)**: AC có nêu **outcome quan sát/kiểm được** chưa? — **KHÔNG** hỏi "AC đủ chi tiết chưa" (câu đó kéo cơ chế vào AC). Chi tiết cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi vụn) thuộc **BR/BL**: nếu gap là cơ chế → suggestion phải **route sang BR/BL + AC ref**, KHÔNG phình AC. AC có lặp lại nội dung BR (trùng tầng) không → nếu có, đề xuất làm mỏng AC.
+- **Lăng kính DEV (tầng cơ chế)**: BR (WHAT) + Business Logic (HOW) đã đủ & rõ chưa — **đây là NƠI chứa chi tiết**: rẽ nhánh, điều kiện biên, retry, error path. Business rule có mơ hồ không? Cross-service deps đủ chưa? Rủi ro kỹ thuật?
 - **Lăng kính SA**: Khớp kiến trúc hiện tại? Hệ luỵ security/auth? Mô hình dữ liệu rõ chưa?
 - **Lăng kính PO**: Scope đã khoanh vùng? Priority rõ chưa? Success metric đã định nghĩa? Rủi ro scope creep?
 
@@ -886,6 +893,7 @@ Nếu có finding nào có `status: "needs_discussion"`, thêm warning block sau
 Với mỗi finding được chấp nhận, theo thứ tự severity (critical → major → minor):
 - Đi tới section PRD được chỉ định bởi `finding.section`.
 - Áp dụng `finding.suggestion`. Với finding `status: "modified"`, người đã sửa sẵn `finding.suggestion` trong Review Board — giá trị đã sửa đó CHÍNH LÀ bản fix cần áp dụng.
+- **Giữ ĐÚNG TẦNG + gọn khi áp fix (altitude):** AC = **outcome quan sát được + ref BR**, KHÔNG chứa cơ chế. Nếu fix là **chi tiết cơ chế/rule** (retry N, timeout, tên/chủ cờ, nhánh lỗi) → **ghi vào bảng BR/BL của UC** (hoặc tạo BR mới), AC chỉ **ref**; KHÔNG inline vào câu AC. Nếu fix làm rõ **≥2 điều kiện/nhánh** ở đúng tầng của nó → **tách bullet con** (mỗi ý một dòng `  - …`) hoặc **AC/BR mới**, đừng nối mệnh đề vào câu cũ. Một AC = một tiêu chí kiểm chứng; đừng để AC lặp lại nội dung BR.
 - **Chạy Business Language Guard trên text mới TRƯỚC khi ghi** (xem section "Ngôn ngữ nghiệp vụ"): diễn đạt lại / gỡ thuật ngữ kỹ thuật-UI để fix không tự kéo theo term kỹ thuật vào PRD.
 - 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.
 
@@ -909,10 +917,21 @@ Cập nhật `status: "applied"` ở **root level** của file findings (không
    - `| **Version** | {new_version} |`
    - `| **Updated**  | {today YYYY-MM-DD} |`
    - `| **Status**   | draft |` ← reset về draft, phải được duyệt lại
-5. Thêm một row mới lên đầu `# Change Log` ở cuối PRD:
-   ```
-   | {new_version} | {today} | {tóm tắt súc tích mọi thay đổi đã áp dụ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"} |
+     ```
+     *(Nêu rõ UC/AC/BR giúp `/generate-bdd` Version Check biết scenario nào cần cập nhật.)*
+   - 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:
+     ```
+     # Change Log (lịch sử) — {TICKET-ID}
+     > PRD: [../{TICKET-ID}-{prd-slug}.md](../{TICKET-ID}-{prd-slug}.md) — 5 version gần nhất nằm trong PRD; đây là phần cũ hơn.
+
+     | Version | Date | Changes |
+     |---------|------|---------|
+     ```
 6. Ghi `applied_to_version: "{new_version}"` ở **root level** của findings — đóng dấu "PRD đổi tới version này là do lệnh này áp", để lần review delta sau phân biệt được thay đổi của chính mình với thay đổi do actor khác (xem "Chọn full vs delta").
 
 ### Phase 4 — Report

package/core/commands/review-context.md

@@ -585,6 +585,13 @@ mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
    List ONLY real, additional issues NOT already in the list — gaps, ambiguities,
    contradictions, missing edge/negative paths, coverage holes, terminology drift,
    structural omissions, and any issue that a fix to an existing finding would expose.
+   ALSO flag ROLE-BOUNDARY / altitude violations (you are NOT limited to adding detail):
+   content sitting in the WRONG section — detailed mechanism (retry counts, timeouts, flag
+   names/owners, error branches) written INSIDE an acceptance criterion or a scope line
+   instead of the Business Rule/Logic section; an AC that merely restates its referenced BR
+   (same content, converged); a term definition crammed into In/Out Scope. For these, the
+   suggestion must be to MOVE the detail to its proper section (AC keeps only the observable
+   outcome + BR ref) — NOT to delete it, and NOT to add more detail.
    Do NOT repeat anything already listed. Return the same finding JSON shape, or [] if
    nothing new.
    ```
@@ -713,8 +720,10 @@ Quét mỗi AC và BR tìm:
 | Tham chiếu chưa định nghĩa | "{SomeThing}" được dùng nhưng chưa định nghĩa trong PRD này | Major |
 | Thiếu luồng âm | AC chỉ mô tả happy path nhưng BR có điều kiện lỗi | Minor |
 | Câu bị động giấu actor | "Invoice is created" — ai tạo? | Minor |
+| **AC lấn tầng (chứa cơ chế)** | AC ghi số lần retry / timeout / tên-chủ cờ / nhánh lỗi chi tiết — cái này thuộc BR/BL | Major |
+| **AC ≈ BR (trùng nội dung, hội tụ tầng)** | AC lặp lại đúng nội dung BR nó ref | Major |
 
-→ AI không thể auto-fix finding P2. Người phải viết bản fix trong note "Modify" của Review Board.
+→ AI không thể auto-fix finding P2. Người viết bản fix trong note "Modify". Với 2 tín hiệu **altitude** (AC lấn tầng / AC≈BR): suggestion là **DI DỜI chi tiết cơ chế xuống BR/BL (§3), AC giữ outcome + ref** — không xoá, không phình.
 
 ### P3 — Domain Conflict Check
 
@@ -994,8 +1003,10 @@ Lựa chọn tiếp theo:
                   → /review-context --resume {target-file}
 
   {CHỈ in khối này khi 0 finding critical còn lại — còn critical thì nhắc duyệt là vô nghĩa}:
-  ✅ PRD đã sạch critical. Khi PO hài lòng → đặt `| **Status** | approved |` trong
-     Metadata PRD (dấu duyệt nghiệp vụ, do người quyết) → rồi /generate-bdd.
+  {If PRD}: ✅ PRD đã sạch critical. Khi PO hài lòng → đặt `| **Status** | approved |` trong
+            Metadata PRD (dấu duyệt nghiệp vụ, do người quyết) → rồi /generate-bdd.
+  {If BDD}: ✅ BDD đã sạch critical. Sau khi review xong → đặt `# @trace.status: approved` trong
+            header file .feature (dấu duyệt BDD, do người quyết) → rồi /generate-tech-docs.
 ```
 
 ---
@@ -1050,8 +1061,8 @@ 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:
-  `Auto-fix: applied {N} auto-fixable review-context findings`
-- **BDD**: nếu ≥1 finding được áp dụng → tăng `@trace.bdd_version` lên 0.1
+  `| {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.
+- **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)
 - **Cả hai**: ghi `applied_to_version: "{version vừa bump tới}"` ở root level của findings — đóng dấu "target đổi tới version này là do lệnh này áp", để lần review delta sau phân biệt thay đổi của chính mình với thay đổi do actor khác (xem "Chọn full vs delta").
 
 ### Phase 4 — Report
@@ -1068,13 +1079,14 @@ 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 BDD}: bdd_version: {old} → {new}
+{If BDD}: bdd_version: {old} → {new}  |  @trace.status: reset về draft (cần duyệt lại)
 
 File findings:
   {If PRD}: {paths.refinement_dir}/{prd-slug}-review-context-findings.yaml
   {If BDD}: {paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml
 Chạy lại /review-context {file} để xác nhận 0 finding critical còn lại.
-Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
+{If PRD}: Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
+{If BDD}: Khi sạch critical + duyệt → đặt # @trace.status: approved trong header .feature rồi /generate-tech-docs.
 ```
 
 Nếu 0 finding nào auto-fixable → in:
@@ -1108,6 +1120,8 @@ Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "
 
 > **Chạy Business Language Guard trên text vừa sửa TRƯỚC khi ghi** (xem section "Ngôn ngữ nghiệp vụ") — đặc biệt với P2 (sửa câu mơ hồ) / P4 skeleton: không để bản fix tự kéo thuật ngữ kỹ thuật-UI vào PRD.
 
+> **Giữ ĐÚNG TẦNG + gọn khi áp fix (altitude):** AC = outcome quan sát được + ref BR, KHÔNG chứa cơ chế. Fix là **chi tiết cơ chế/rule** (retry, timeout, tên/chủ cờ, nhánh lỗi) → **di dời vào bảng BR/BL của UC** (hoặc BR mới), AC chỉ ref; KHÔNG inline vào AC. Fix làm rõ ≥2 nhánh ở đúng tầng → **tách bullet con** hoặc AC/BR mới, đừng nối mệnh đề vào câu cũ. Đừng để AC lặp lại nội dung BR.
+
 **Với finding PRD:**
 | check_id | Làm gì |
 |----------|-----------|
@@ -1117,7 +1131,7 @@ 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 entry Changelog, 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 (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").
 
 **Với finding BDD:**
 | check_id | Làm gì |
@@ -1129,8 +1143,8 @@ Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "
 | B5 (Metadata) | Thêm @trace header còn thiếu, sinh lại Coverage Matrix / Pre-merge Checklist |
 | B6 (Side effects) | Thêm `And <side-effect>` còn thiếu vào block Then |
 
-→ Sau khi áp dụng, tăng `@trace.bdd_version` trong header file lên 0.1.
-→ Đồng thời cập nhật `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv`: đặt cột `bdd_version` thành giá trị `@trace.bdd_version` mới cho mọi row, và đặt `last_updated` thành ngày hôm nay.
+→ Sau khi áp dụng, tăng `@trace.bdd_version` trong header file lên 0.1, **reset `# @trace.status: draft`** trong header (BDD đổi sau khi duyệt → phải duyệt lại).
+→ Đồng thời cập nhật `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv`: đặt cột `bdd_version` thành giá trị `@trace.bdd_version` mới cho mọi row, đặt `uc_status = draft` (khớp header), và đặt `last_updated` thành ngày hôm nay.
 → Ghi `applied_to_version: "{@trace.bdd_version mới}"` ở root level của findings (xem "Chọn full vs delta").
 
 ### Phase 3 — Report
@@ -1145,8 +1159,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 BDD}: bdd_version: {old} → {new}
+{If BDD}: bdd_version: {old} → {new}  |  @trace.status: reset về draft (cần duyệt lại)
 
 Chạy lại /review-context {file} để xác nhận 0 finding critical còn lại.
-Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
+{If PRD}: Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
+{If BDD}: Khi sạch critical + duyệt → đặt # @trace.status: approved trong header .feature rồi /generate-tech-docs.
 ```

package/core/commands/validate-traces.md

@@ -488,6 +488,7 @@ Skip loại nào không có doc / không có revision đã lưu (`—`).
 *Bỏ qua step này nếu không có file TSV nào (đã xử lý bởi path no-TSV của Step 1).*
 
 Với mỗi file `.tsv` đã xử lý: ghi `spec_ver`, `status`, `last_updated` đã cập nhật lại disk.
+Đồng thời **đồng bộ `uc_status` ← `@trace.status`** của file `.feature` tương ứng (header `.feature` là nguồn-sự-thật về duyệt BDD — người đặt `approved` sau khi review sạch, giống PO đặt PRD Metadata `Status`). Nhờ vậy `approved_ucs` trên dashboard phản ánh đúng thay vì luôn = 0.
 **Đừng** sửa `dev_selftest`/`dev_selftest_at` (do `/dev-run-test` sở hữu) hay `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` (do `/qc-run-test` + `/report-bug` sở hữu); lệnh này chỉ đọc chúng cho report.
 
 ### Step 7 — Tính aggregate cho dashboard