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

package/core/commands/refine-prd.md

@@ -631,7 +631,9 @@ Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
    - **Tồn tại** + có `--full` → **FULL**: bỏ qua findings cũ, không truyền `CHANGED_SCOPE` (ép quét lại toàn bộ).
    - **Tồn tại** + KHÔNG có `--full` → so `prd_version` trong findings cũ với `| **Version** |` của PRD hiện tại:
      - **Bằng nhau** (PRD chưa đổi từ lần review trước) → DỪNG, báo: `"PRD chưa đổi từ v{X} (lần review gần nhất). Không có gì để review lại — dùng --full nếu vẫn muốn quét toàn bộ."`
-     - **Khác** (đã có `--resume` bump version) → **DELTA**: `CHANGED_SCOPE` = { `uc_id`/`section` của các finding `status: applied` trong findings cũ } ∪ { UC có trong PRD hiện tại nhưng chưa từng xuất hiện ở findings cũ }. Truyền `CHANGED_SCOPE` này vào Quy trình Review.
+     - **Khác** → kiểm tra `applied_to_version` trong findings cũ (version mà lần `--resume` gần nhất của CHÍNH lệnh này đã bump PRD tới) để biết ai gây ra thay đổi:
+       - **`applied_to_version` có mặt VÀ `==` version PRD hiện tại** → PRD đổi đúng bằng phần lệnh này tự áp, không actor khác động vào → **DELTA**: `CHANGED_SCOPE` = { `uc_id`/`section` của các finding `status: applied` trong findings cũ } ∪ { UC có trong PRD hiện tại nhưng chưa từng xuất hiện ở findings cũ }. Truyền `CHANGED_SCOPE` này vào Quy trình Review.
+       - **`applied_to_version` vắng mặt HOẶC `≠` version hiện tại** → PRD đã bị sửa bởi **actor khác** (lệnh `/review-context`, sửa tay…) sau lần resume này → KHÔNG tin được phạm vi hẹp → **FULL** (KHÔNG truyền `CHANGED_SCOPE`), kèm cảnh báo: `"PRD đổi ngoài tầm theo dõi của findings (applied_to_version={A} ≠ hiện tại={C}); quét lại toàn bộ để khỏi sót UC do người/lệnh khác sửa."`
 
 **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ó:
@@ -663,6 +665,7 @@ Ghi `{paths.refinement_dir}/{prd-slug}-findings.yaml`:
 ```yaml
 prd_source: "{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md"
 prd_version: "{đọc | **Version** | từ metadata PRD lúc sinh findings — dùng để chọn full/delta lần chạy sau}"
+applied_to_version: ""   # để trống lúc phân tích; --resume sẽ ghi version PRD vừa bump tới. Lần delta sau: nếu version PRD hiện tại ≠ giá trị này → PRD bị actor khác sửa → fallback FULL (xem "Chọn full vs delta")
 generated_at: "{ISO datetime}"
 status: "pending_review"
 
@@ -684,14 +687,19 @@ findings:
     # true  = AI tự tin cao vào suggestion này; Review Board có thể hiển thị nút "quick accept"
     # false = cần human đọc kỹ và ghi quyết định trước khi accept
     # Resume Mode luôn áp dụng theo status (accepted|modified), bất kể auto_fixable.
+    # LƯU Ý: /refine-prd CỐ Ý không có `--fix` mode (khác /review-context) — finding 4 lăng kính
+    #   là phán đoán QA/DEV/SA/PO, phải qua người duyệt ở Board; auto_fixable ở đây CHỈ là gợi ý
+    #   quick-accept cho Board, KHÔNG để máy tự áp.
     status: "pending"
-    # Lifecycle finding-level:
+    applied_via: ""
+    # Vòng đời finding-level (CHUNG với /review-context — Review Board đọc cả hai loại file nên enum phải khớp):
     #   pending          → finding mới, chưa được review
     #   accepted         → reviewer chấp nhận suggestion gốc → Resume sẽ apply
     #   modified         → reviewer đã sửa suggestion trong Review Board → Resume dùng suggestion đã sửa
     #   rejected         → reviewer bác bỏ, không apply
-    #   needs_discussion → hai suggestion xung đột, cần con người quyết định trước khi --resume
-    #   applied          → đã được Resume Mode apply vào PRD
+    #   needs_discussion → hai suggestion xung đột, CHẶN --resume (bỏ qua + cảnh báo) tới khi con người quyết
+    #   deferred         → cố ý hoãn (không chặn), bỏ qua lượt này, xem lại sau
+    #   applied          → đã áp vào PRD; applied_via ghi cách áp: "resume" (qua --resume) — /review-context còn dùng "fix" (qua --fix)
 
 summary:
   total_findings: {N}
@@ -781,7 +789,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
@@ -834,7 +842,7 @@ Pipeline : Discovery → [PRD ◀ bạn ở đây] → Design Spec → BDD → T
            Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
 Next     : Mở trong Review Board (chuột phải vào file) → Cập nhật PRD
            → /review-context {prd-file}   ← kiểm tra chất lượng PRD trước khi sinh BDD
-           → /generate-bdd {prd-file}
+           → khi sạch critical, PO đặt | **Status** | approved | → /generate-bdd {prd-file}
 ```
 
 Nếu có finding nào có `status: "needs_discussion"`, thêm warning block sau footer:
@@ -884,7 +892,7 @@ Với mỗi finding được chấp nhận, theo thứ tự severity (critical
 ### Phase 2.5 — Cập nhật file findings
 
 Với mỗi finding đã áp dụng (status là `accepted` hoặc `modified`):
-- Đặt `status: "applied"` trong `{paths.refinement_dir}/{prd-slug}-findings.yaml`.
+- Đặt `status: "applied"` + `applied_via: "resume"` trong `{paths.refinement_dir}/{prd-slug}-findings.yaml`.
 
 Cập nhật `status: "applied"` ở **root level** của file findings (không phải `summary.status`).
 # Lifecycle file-level: pending_review → applied | partially_applied
@@ -901,10 +909,22 @@ 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
 
@@ -918,7 +938,7 @@ Changes  :
 
 💡 Vừa áp {N} phương án (gồm bản PO tự sửa) → chạy lại /refine-prd {prd-file}
    (delta tự động) để lòi edge case mà các phương án vừa áp có thể tạo ra.
-⚠️  BDD có thể đã lỗi thời. Chạy:
+⚠️  Status đã reset về draft (sửa rồi phải duyệt lại). BDD có thể đã lỗi thời. Chạy:
     /review-context {prd-file}   ← kiểm tra chất lượng PRD trước
-    → /generate-bdd {prd-file}
+    → PO đặt | **Status** | approved | khi hài lòng → /generate-bdd {prd-file}
 ```

package/core/commands/report-bug.md

@@ -566,7 +566,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |

package/core/commands/review-code.md

@@ -515,7 +515,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |

package/core/commands/review-context.md

@@ -641,7 +641,9 @@ Convergence: {convergence_rounds} vòng critic — file findings đã đầy đ
    - **Tồn tại** + có `--full` → **FULL**: bỏ qua findings cũ.
    - **Tồn tại** + KHÔNG `--full` → so `source_version` trong findings cũ với version target hiện tại (PRD: Metadata `Version`; BDD: `@trace.bdd_version`):
      - **Bằng nhau** (target chưa đổi từ lần review trước) → DỪNG, báo: `"Target chưa đổi từ v{X} (lần review gần nhất). Không có gì để review lại — dùng --full nếu vẫn muốn quét toàn bộ."`
-     - **Khác** → **DELTA**: `CHANGED_SCOPE` = { `uc_id`/`section` của finding đã xử lý (status `accepted`/`modified`/`applied_automatically`) trong findings cũ } ∪ { UC có trong target hiện tại nhưng chưa từng xuất hiện ở findings cũ }.
+     - **Khác** → kiểm tra `applied_to_version` trong findings cũ (version mà lần `--fix`/`--resume` gần nhất của CHÍNH lệnh này đã bump target tới) để biết ai gây ra thay đổi:
+       - **`applied_to_version` có mặt VÀ `==` version target hiện tại** → target đổi đúng bằng phần lệnh này tự áp, không actor khác động vào → **DELTA**: `CHANGED_SCOPE` = { `uc_id`/`section` của finding đã xử lý (status `accepted`/`modified`/`applied`) trong findings cũ } ∪ { UC có trong target hiện tại nhưng chưa từng xuất hiện ở findings cũ }.
+       - **`applied_to_version` vắng mặt HOẶC `≠` version hiện tại** → target đã bị sửa bởi **actor khác** (lệnh `/refine-prd`, `/generate-bdd` regen, sửa tay…) sau lần áp này → KHÔNG tin được phạm vi hẹp → **FULL** (KHÔNG truyền `CHANGED_SCOPE`), kèm cảnh báo: `"Target đổi ngoài tầm theo dõi của findings (applied_to_version={A} ≠ hiện tại={C}); quét lại toàn bộ để khỏi sót UC do người/lệnh khác sửa."`
 
 ---
 
@@ -653,7 +655,7 @@ Convergence: {convergence_rounds} vòng critic — file findings đã đầy đ
 
 Khi `setup.mode = umbrella`, PRD phải có metadata routing đúng để context-loader Bước 1.5 có thể đưa output sinh ra tới đúng service submodule. Chạy các check này **trước P1–P5**:
 
-> **Nguồn đọc:** PRD mang Domain/Status ở **bảng Metadata** (`| **Domain** | … |`, `| **Status** | … |`) — **KHÔNG** phải frontmatter `@trace.*` (cái đó dành cho file `.feature`/tech-docs do máy đọc). Routing umbrella dựa trên Domain (bảng) + path, đúng như context-loader Bước 1.5 và `generate-bdd` (đọc `| **Status** |`).
+> **Nguồn đọc:** PRD mang **Domain** ở **bảng Metadata** (`| **Domain** | … |`) — **KHÔNG** phải frontmatter `@trace.*` (cái đó dành cho file `.feature`/tech-docs do máy đọc). Routing umbrella dựa trên Domain (bảng) + path, đúng như context-loader Bước 1.5.
 
 **P0.1 — Row `Domain` có mặt trong Metadata**
 - Đọc bảng Metadata của PRD, lấy row `| **Domain** |`.
@@ -673,11 +675,7 @@ Khi `setup.mode = umbrella`, PRD phải có metadata routing đúng để contex
   - `suggestion`: "Cập nhật section services trong `.agent/project-context.yaml` với mapping domain-to-submodule trước khi sinh BDD."
   - `auto_fixable: false`
 
-**P0.3 — Check row `Status` trong Metadata**
-- Nếu row `| **Status** |` **vắng mặt** → **minor**, `auto_fixable: true` (thêm `| **Status** | draft |`)
-- Nếu `Status: draft` → **major**, `auto_fixable: false`:
-  - `finding`: "PRD status là `draft`. Team dev không nên sinh BDD từ một PRD chưa được duyệt."
-  - `suggestion`: "PO/SA nên review và cập nhật Status thành `approved` trước khi team dev tiếp tục."
+> **Status KHÔNG còn là check của P0.** PRD chưa duyệt (`Status: draft`) là trạng thái **bình thường** lúc review — việc duyệt diễn ra *sau khi* review-context sạch, nên báo draft là "lỗi" ở đây chỉ gây nhiễu. Gác duyệt do `/generate-bdd` lo (cảnh báo mềm, áp **mọi mode**); lời nhắc đặt `approved` nằm ở Report (mọi mode). P4 chỉ lo trường hợp row Status **vắng mặt** (auto-fix mặc định `draft`).
 
 > **P0 là một gate check:** Nếu P0.1 hoặc P0.2 cho finding critical, hiển thị cảnh báo trước khi tiếp tục:
 > ```
@@ -741,7 +739,7 @@ hoặc định nghĩa lại field/status transition của một entity khác đi
 - [ ] Có section `# Change Log`
 - [ ] Không còn giá trị `{{PLACEHOLDER}}` chưa điền
 
-→ Section/field thiếu hoặc lệch cấu trúc: **major**. AI có thể thêm skeleton khi `--resume` nếu được chấp nhận. Riêng **"Nhất quán 2 chiều"** lệch → **major**, `auto_fixable: false` (người xác nhận AC↔UC, AI không tự đoán). **API Source: existing thiếu contract** → **major**, `auto_fixable: false` (cần nguồn contract); **greenfield còn sót section "Existing API Contract" rỗng** → **minor**, `auto_fixable: true` (xoá section).
+→ Section/field thiếu hoặc lệch cấu trúc: **major**. AI có thể thêm skeleton khi `--resume` nếu được chấp nhận. Riêng **"Nhất quán 2 chiều"** lệch → **major**, `auto_fixable: false` (người xác nhận AC↔UC, AI không tự đoán). **API Source: existing thiếu contract** → **major**, `auto_fixable: false` (cần nguồn contract); **greenfield còn sót section "Existing API Contract" rỗng** → **minor**, `auto_fixable: true` (xoá section). Riêng **row `Status` vắng mặt** → **minor**, `auto_fixable: true` (thêm `| **Status** | draft |`) — KHÔNG flag *giá trị* draft (đó là trạng thái bình thường lúc review; gác duyệt do `/generate-bdd` lo).
 
 ### P5 — Custom Criteria (tuỳ chọn)
 
@@ -826,6 +824,7 @@ Sau khi chạy hết các check, ghi `{paths.refinement_dir}/{slug}-review-*-fin
 ```yaml
 source_file: "{absolute path to reviewed file}"
 source_version: "{version target lúc sinh findings — PRD: Metadata Version; BDD: @trace.bdd_version — dùng chọn full/delta lần chạy sau}"
+applied_to_version: ""   # để trống lúc phân tích; --fix/--resume sẽ ghi version target vừa bump tới. Lần delta sau: nếu version target hiện tại ≠ giá trị này → target bị actor khác sửa → fallback FULL (xem "Chọn full vs delta")
 generated_at: "{ISO datetime}"
 review_type: "{prd | bdd}"
 status: "pending_review"
@@ -840,7 +839,8 @@ findings:
     finding: "{mô tả rõ ràng vấn đề}"
     suggestion: "{bản fix cụ thể, hành động được — AI sẽ áp dụng khi --resume nếu được chấp nhận}"
     auto_fixable: true       # true = AI áp dụng được; false = người phải viết note trong Review Board
-    status: "pending"        # pending | accepted | modified | rejected | deferred
+    status: "pending"        # pending | accepted | modified | rejected | needs_discussion | deferred | applied (vòng đời chung — xem chú thích dưới)
+    applied_via: ""          # set khi status='applied': "fix" (auto qua --fix) | "resume" (người duyệt qua --resume)
 
 summary:
   total_findings: {N}
@@ -850,6 +850,15 @@ summary:
   recommendation: "APPROVED | NEEDS_REVISION | BLOCKED"
 ```
 
+> **Vòng đời finding-level (CHUNG với `/refine-prd` — một Review Board đọc cả hai loại file nên enum phải khớp):**
+> - `pending` → mới, chưa review
+> - `accepted` → nhận suggestion gốc → `--resume` sẽ áp
+> - `modified` → người đã sửa suggestion trong Review Board → `--resume` dùng bản đã sửa
+> - `rejected` → bác bỏ, không áp
+> - `needs_discussion` → xung đột/chưa ngã ngũ → **chặn** `--resume` (bỏ qua + cảnh báo) tới khi người quyết
+> - `deferred` → cố ý hoãn (không chặn), bỏ qua lượt này, xem lại sau
+> - `applied` → đã áp vào target; `applied_via` ghi cách áp: `"fix"` (auto qua `--fix`) hoặc `"resume"` (người duyệt qua `--resume`)
+
 > **Field định vị (`quote` + `uc_id`) — bắt buộc cho source-jump của Review Board.**
 > Với mỗi finding, copy một đoạn `quote` **nguyên văn** thẳng từ file đang review tại đúng
 > chỗ lỗi xảy ra — KHÔNG diễn giải lại; nó được so khớp với tài liệu để định vị dòng.
@@ -928,7 +937,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
@@ -983,6 +992,12 @@ Lựa chọn tiếp theo:
                   → áp dụng ngay mọi finding auto-fixable
   B) Review Board: mở file findings → accept/modify/reject
                   → /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}:
+  {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.
 ```
 
 ---
@@ -1012,10 +1027,9 @@ Với mỗi finding có `auto_fixable: true`, theo thứ tự (critical → majo
 
 | check_id | Áp dụng gì |
 |----------|--------------|
-| P0.3 (Thiếu status) | Thêm row `| **Status** | draft |` vào bảng Metadata |
 | 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; greenfield → xoá section "Existing API Contract" rỗng |
+| 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 |
 
 > **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.
 
@@ -1033,13 +1047,14 @@ Với mỗi finding có `auto_fixable: true`, theo thứ tự (critical → majo
 | B5 | Thêm @trace header còn thiếu, sinh lại Coverage Matrix / Pre-merge Checklist |
 | B6 | Thêm `And <side-effect>` còn thiếu vào block Then |
 
-Sau khi áp dụng mỗi finding, đánh dấu nó `status: "applied_automatically"` trong file findings.
+Sau khi áp dụng mỗi finding, đánh dấu nó `status: "applied"` + `applied_via: "fix"` trong file findings.
 
 ### 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), 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
+- **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.
+- **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
 
@@ -1054,13 +1069,15 @@ Auto-fixed : {N} findings ({critical} critical, {major} major, {minor} minor)
 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}
-{If BDD}: bdd_version: {old} → {new}
+{If PRD}: Version bumped: {old} → {new}  |  Status: reset về draft (cần duyệt lại)
+{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.
+{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:
@@ -1082,26 +1099,28 @@ Mở file findings trong Review Board → rồi chạy: /review-context --resume
    - PRD: `{paths.refinement_dir}/{prd-slug}-review-context-findings.yaml`
    - BDD: `{paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml`
 2. Đọc file findings.
-3. Gom các finding có `status: "accepted"` hoặc `status: "modified"`.
+3. Gom các finding có `status: "accepted"` hoặc `status: "modified"`. Bỏ qua `rejected`/`deferred`.
 4. Nếu không có → báo "No accepted findings. File unchanged." và dừng.
+5. Nếu còn finding `status: "needs_discussion"` → cảnh báo (không dừng): `"⚠️  {N} finding chưa ngã ngũ (needs_discussion) — bỏ qua lần áp này; giải quyết trong Review Board rồi --resume lại."`
 
 ### Phase 2 — Áp dụng fix
 
 Áp dụng theo thứ tự: critical → major → minor.
 
+Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "applied"` + `applied_via: "resume"` trong findings (hoàn tất vòng đời, cùng quy ước với `--fix` và `/refine-prd`).
+
 > **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.
 
 **Với finding PRD:**
 | check_id | Làm gì |
 |----------|-----------|
-| P0.3 (Thiếu status) | Thêm row `| **Status** | draft |` vào bảng Metadata |
 | P1 (Banned term) | Thay banned term bằng canonical; thuật ngữ kỹ thuật/UI → diễn đạt lại theo Business Language Guard |
 | P2 (Ambiguity) | Áp dụng fix nêu trong `suggestion` hoặc note `modified` |
 | P3 (Conflict) | Áp dụng cách giải quyết nêu trong note modified |
-| P4 (Structure) | Thêm section/metadata field còn thiếu |
+| 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) và thêm entry Changelog.
+→ 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ì |
@@ -1113,22 +1132,25 @@ Mở file findings trong Review Board → rồi chạy: /review-context --resume
 | 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
 
 ```
 /review-context --resume Đã áp dụng — {target file}
 Applied  : {N} findings ({critical} critical, {major} major, {minor} minor)
-Skipped  : {N} rejected/deferred
+Skipped  : {N} rejected/deferred/needs_discussion
 
 Changes:
   - {tóm tắt change 1}
   - {tóm tắt change 2}
 
-{If PRD}: Version bumped: {old} → {new}
-{If BDD}: bdd_version: {old} → {new}
+{If PRD}: Version bumped: {old} → {new}  |  Status: reset về draft (cần duyệt lại)
+{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.
+{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/review-tech-docs.md

@@ -682,7 +682,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |

package/core/commands/setup-ai-first.md

@@ -140,15 +140,15 @@ Rồi:
 - Artifact theo từng feature (`specs/{domain}/{prd-slug}/{ {TICKET-ID}-{prd-slug}.md, bdd/, tech-docs/, design-spec/}`) được tạo on demand bởi các lệnh generate — ĐỪNG tạo trước
 - Skip: `.trace/` (theo service, sống cạnh code trong mỗi service submodule)
 - Sinh `CLAUDE.md` tối thiểu chỉ với §1 (project overview) và §7 (git conventions)
-- Hỏi người dùng: **"Liệt kê các business domain của bạn (vd auth, payment, loyalty):"** — lưu thành domain list cho `project-context.yaml` và nhắc PO các tên này phải được dùng nhất quán làm `@trace.domain` trong mọi PRD
+- Hỏi người dùng: **"Liệt kê các business domain của bạn (vd auth, payment, loyalty):"** — lưu thành domain list cho `project-context.yaml` và nhắc PO các tên này phải được dùng nhất quán ở row `| **Domain** |` của bảng Metadata trong mọi PRD
 - Thông báo:
   - Lệnh cho PO repo: `/define-product`, `/generate-prd`, `/review-context`, `/generate-design-spec`
-  - **Quan trọng cho handoff team dev:** Mọi PRD phải có `@trace.domain: {domain}` trong frontmatter. Team dev dùng nó để route BDD/code sinh ra tới đúng service submodule. Tên domain không nhất quán sẽ phá routing.
-  - Frontmatter PRD khuyến nghị:
+  - **Quan trọng cho handoff team dev:** Mọi PRD phải có row `| **Domain** | {domain} |` trong **bảng Metadata**. Team dev dùng nó để route BDD/code sinh ra tới đúng service submodule. Tên domain không nhất quán sẽ phá routing.
+  - Bảng Metadata PRD (do `/generate-prd` điền sẵn theo template):
     ```
-    @trace.domain: {domain}    ← phải khớp một key trong services config của team dev
-    @trace.id: {TICKET-ID}
-    @trace.status: draft | approved
+    | **Domain** | {domain} |       ← phải khớp một key trong services config của team dev
+    | **Ticket** | {TICKET-ID} |
+    | **Status** | draft | approved |
     ```
 
 ## Step 1 — Tạo cấu trúc thư mục
@@ -446,7 +446,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
@@ -510,7 +510,7 @@ Next:
 Next:
   1. Review .agent/project-context.yaml:
      - Cập nhật services[].path khớp tên thư mục submodule thực tế
-     - Cập nhật domain key của services khớp @trace.domain trong các file PRD
+     - Cập nhật domain key của services khớp row `Domain` (bảng Metadata) trong các file PRD
      - Xác nhận path spec_source đúng
 
   2. Chạy /sync — một lệnh lo mọi thứ còn lại:
@@ -529,7 +529,7 @@ Next:
 ```
 Next:
   1. Điền .agent/project-context.yaml:
-     - domains: [liệt kê mọi business domain — chúng thành giá trị @trace.domain trong PRD]
+     - domains: [liệt kê mọi business domain — chúng thành row `Domain` (bảng Metadata) trong PRD]
      - project.name, project.description
   2. Điền specs/domain-knowledge/business-dictionary.md  ← canonical terms
   3. Điền specs/domain-knowledge/core-entities.md        ← entity glossary
@@ -539,7 +539,7 @@ Next:
   6. /define-product để bắt đầu feature đầu tiên
 
 ⚠️  Nhắc handoff team dev:
-  - Mỗi PRD phải có @trace.domain khớp một trong domains list của bạn
+  - Mỗi PRD phải có row `Domain` (bảng Metadata) khớp một trong domains list của bạn
   - Khi team dev setup umbrella repo của họ, họ map các tên domain này
     tới path service submodule trong section services của project-context.yaml
   - Chia sẻ tên domain với team dev trước khi họ cấu hình umbrella

package/core/commands/sync.md

@@ -364,7 +364,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |

package/core/commands/update-framework.md

@@ -187,7 +187,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |

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
@@ -757,7 +758,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |