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

package/commands/generate-bdd.md

@@ -837,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>
@@ -884,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
@@ -915,8 +925,11 @@ Feature: <Feature name>
 # - [ ] 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/commands/generate-bdd.tmpl

@@ -410,117 +410,10 @@ CHECKPOINT: "Outline này đúng chưa? Bạn muốn thêm hay bớt SC nào kh
 Với mỗi UC, ghi vào path đã phân giải ở trên. Dùng từ vựng cho active platform (từ Platform Selection hoặc Service Detection).
 
 ```gherkin
-# ============================================================
-# @trace.id: {TICKET-ID}-UC{N}
-# @trace.title: <Feature name>
-# @trace.revision: 1  ← field tĩnh; dùng @trace.bdd_version để theo dõi version (tăng bởi /review-context --fix hoặc --resume)
-# @trace.domain: <domain>
-# @trace.platform: {active_platform — web | app | system | (bỏ trong umbrella mode)}
-# @trace.service: {active_service — bỏ trong spec repo mode}
-# @trace.module: {active_module trong umbrella mode; "unknown" trong spec repo mode}
-# @trace.status: draft
-# @trace.author: AI-generated
-# @trace.created_at: {YYYY-MM-DD}
-# @trace.prd: {TICKET-ID}
-# @trace.prd_version: {đọc từ metadata PRD "| **Version** |"}
-# @trace.bdd_version: {1.0 nếu gen mới; tăng 0.1 khi gen lại — vd 1.0 → 1.1}
-# @trace.business_rules: {TICKET-ID}-UC{N}-BR1, {TICKET-ID}-UC{N}-BR2
-# @trace.dataset: {domain}.testdata.yaml
-# ============================================================
-
-# === CONTEXT ===
-# Actor:     <vai trò thực hiện hành động, vd: Consumer, Staff, System>
-# Screens:   <các màn liên quan, vd: Cart → Confirm Order → Order Detail>
-# Entities:  <business entity, vd: Order, OrderItem, Consumer>
-# Pre-state: <state dùng chung trước khi vào các scenario>
-
-# === SCOPE ===
-# In:  <UC này phủ gì>
-# Out: <cái gì KHÔNG thuộc UC này — link tới UC/feature khác (R10)>
-
-# === BUSINESS DEFINITION ===
-# 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>
-
-Feature: <Feature name>
-  As a <role>
-  I want to <action>
-  So that <business value>
-
-  Background:
-    Given <precondition dùng chung — dùng alias từ dataset, không phải ID kỹ thuật>
-
-  # ==========================================================
-  # NHÓM 1: <Business theme> (<BR refs>)
-  # ==========================================================
-
-  # Side-effects: <liệt kê ngắn các Then side-effect cần verify>
-  # @trace.scenario: {TICKET-ID}-UC{N}-SC1
-  # @trace.sc_version: 1.0
-  # @trace.business_rules: {TICKET-ID}-UC{N}-BR1
-  @happy
-  Scenario: <mô tả business outcome — dùng động từ chính xác: create/receive/assign/block>
-    Given <input state — alias từ dataset>
-    When <single action>
-    Then <main observable outcome>
-      And <side-effect 1 khai báo trong header>
-
-  # Side-effects: <...>
-  # @trace.scenario: {TICKET-ID}-UC{N}-SC2
-  # @trace.sc_version: 1.0
-  # @trace.business_rules: {TICKET-ID}-UC{N}-BR1
-  @happy @alternative
-  Scenario: <cùng theme NHÓM 1 nhưng path khác — vd: giá trị enum khác>
-    Given <state>
-    When <action>
-    Then <outcome>
-
-  # ==========================================================
-  # NHÓM 2: <Business theme 2> (<BR refs>)
-  # ==========================================================
-
-  # Side-effects: <...>
-  # @trace.scenario: {TICKET-ID}-UC{N}-SC3
-  # @trace.sc_version: 1.0
-  # @trace.business_rules: {TICKET-ID}-UC{N}-BR2
-  @edge
-  Scenario: <scenario boundary / error>
-    Given <state>
-    When <action>
-    Then <expected error handling>
+{{include:templates/feature.template}}
 ```
 
-### 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
-#   AC2 (...) → SC3
-# BR mapping (mỗi bullet PHẢI có ≥1 SC — C.2):
-#   {TICKET-ID}-UC{N}-BR1 (...) → SC1, SC2
-#   {TICKET-ID}-UC{N}-BR2 (...) → SC3
-# Wireframe mapping (mỗi component/action ≥1 SC — C.1):
-#   Screen "<screen 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.)*
 
 ---
 

package/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}
 
 ---
 
@@ -777,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/commands/generate-prd.tmpl

@@ -130,6 +130,7 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
 ## 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/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.
 

package/commands/refine-prd.tmpl

@@ -55,8 +55,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?
 
@@ -203,6 +203,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.
 

package/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
 
@@ -1111,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ì |
 |----------|-----------|

package/commands/review-context.tmpl

@@ -130,8 +130,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
 
@@ -428,6 +430,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ì |
 |----------|-----------|

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.14.8
+0.14.9

package/core/commands/generate-bdd.md

@@ -837,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>
@@ -884,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
@@ -915,8 +925,11 @@ Feature: <Feature name>
 # - [ ] 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-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}
 
 ---
 
@@ -777,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/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.
 

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
 
@@ -1111,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ì |
 |----------|-----------|

package/core/steps/review-fanout.md

@@ -112,6 +112,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.
    ```