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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/commands/generate-bdd.md +76 -8
  2. package/commands/generate-bdd.tmpl +56 -108
  3. package/commands/generate-code.md +18 -1
  4. package/commands/generate-code.tmpl +18 -1
  5. package/commands/generate-design-spec.md +35 -5
  6. package/commands/generate-design-spec.tmpl +35 -5
  7. package/commands/generate-prd.md +15 -5
  8. package/commands/generate-prd.tmpl +1 -0
  9. package/commands/generate-tech-docs.md +1 -0
  10. package/commands/generate-tech-docs.tmpl +1 -0
  11. package/commands/propose-scenario.md +6 -2
  12. package/commands/propose-scenario.tmpl +6 -2
  13. package/commands/qc-analyze.md +14 -0
  14. package/commands/qc-analyze.tmpl +14 -0
  15. package/commands/refine-prd.md +25 -6
  16. package/commands/refine-prd.tmpl +18 -6
  17. package/commands/review-context.md +27 -12
  18. package/commands/review-context.tmpl +20 -12
  19. package/commands/validate-traces.md +1 -0
  20. package/commands/validate-traces.tmpl +1 -0
  21. package/core/FRAMEWORK_VERSION +1 -1
  22. package/core/commands/generate-bdd.md +76 -8
  23. package/core/commands/generate-code.md +18 -1
  24. package/core/commands/generate-design-spec.md +35 -5
  25. package/core/commands/generate-prd.md +15 -5
  26. package/core/commands/generate-tech-docs.md +1 -0
  27. package/core/commands/propose-scenario.md +6 -2
  28. package/core/commands/qc-analyze.md +14 -0
  29. package/core/commands/refine-prd.md +25 -6
  30. package/core/commands/review-context.md +27 -12
  31. package/core/commands/validate-traces.md +1 -0
  32. package/core/skills/code/SKILL.md +7 -759
  33. package/core/skills/debug/SKILL.md +9 -859
  34. package/core/skills/design-spec/SKILL.md +3 -582
  35. package/core/skills/prd/SKILL.md +5 -464
  36. package/core/skills/setup-ai-first/SKILL.md +3 -208
  37. package/core/skills/spec/SKILL.md +7 -450
  38. package/core/skills/test/SKILL.md +10 -1290
  39. package/core/steps/review-fanout.md +7 -0
  40. package/core/steps/spawn-agent.md +12 -7
  41. package/core/templates/feature.template +83 -222
  42. package/core/templates/prd.template.md +14 -5
  43. package/core/templates/project-context.yaml +1 -1
  44. package/docs/01-getting-started/core-concepts.md +2 -2
  45. package/docs/01-getting-started/quickstart.md +4 -3
  46. package/docs/02-guides/bdd-input-checklist.md +68 -0
  47. package/docs/02-guides/developer/README.md +3 -0
  48. package/docs/02-guides/developer/bdd-and-trace.md +1 -0
  49. package/docs/02-guides/developer/commands.md +3 -3
  50. package/docs/02-guides/developer/pr-checklist.md +1 -0
  51. package/docs/02-guides/developer/workflow.md +2 -2
  52. package/docs/02-guides/prd-input-checklist.md +94 -0
  53. package/docs/02-guides/product-owner/README.md +3 -1
  54. package/docs/02-guides/product-owner/commands.md +1 -1
  55. package/docs/02-guides/tech-docs-input-checklist.md +82 -0
  56. package/docs/02-guides/tester/README.md +1 -1
  57. package/docs/02-guides/tester/bug-reporting.md +1 -1
  58. package/docs/02-guides/tester/qc-automation.md +1 -1
  59. package/docs/03-concepts/README.md +1 -0
  60. package/docs/03-concepts/mechanisms-explained.md +57 -0
  61. package/docs/03-concepts/pipeline.md +12 -9
  62. package/docs/03-concepts/traceability.md +4 -1
  63. package/docs/04-operations/bug-flow.md +2 -0
  64. package/docs/05-reference/command-cheatsheet.md +8 -8
  65. package/docs/05-reference/commands.md +12 -10
  66. package/docs/05-reference/trace-schema.md +2 -1
  67. package/package.json +1 -1
  68. package/skills/code/SKILL.md +7 -759
  69. package/skills/code/SKILL.tmpl +7 -164
  70. package/skills/debug/SKILL.md +9 -859
  71. package/skills/debug/SKILL.tmpl +9 -252
  72. package/skills/design-spec/SKILL.md +3 -582
  73. package/skills/design-spec/SKILL.tmpl +3 -87
  74. package/skills/prd/SKILL.md +5 -464
  75. package/skills/prd/SKILL.tmpl +5 -63
  76. package/skills/setup-ai-first/SKILL.md +3 -208
  77. package/skills/setup-ai-first/SKILL.tmpl +3 -108
  78. package/skills/spec/SKILL.md +7 -450
  79. package/skills/spec/SKILL.tmpl +7 -162
  80. package/skills/test/SKILL.md +10 -1290
  81. package/skills/test/SKILL.tmpl +10 -288
  82. package/steps/review-fanout.md +7 -0
  83. package/steps/spawn-agent.md +12 -7
  84. package/templates/feature.template +83 -222
  85. package/templates/prd.template.md +14 -5
  86. package/templates/project-context.yaml +1 -1
@@ -624,6 +624,8 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
624
624
 
625
625
  ## b. Phạm vi
626
626
 
627
+ > **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.
628
+
627
629
  **In Scope**
628
630
  - {hạng mục trong phạm vi 1}
629
631
  - {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
642
644
  # 2. Acceptance Criteria
643
645
 
644
646
  > 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.
647
+ >
648
+ > **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).
645
649
 
646
650
  **AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
647
651
 
648
- **AC2:** {} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
652
+ **AC2:** {Tiêu chí có nhiều nhánh — tách bullet:} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
653
+ - {nhánh/điều kiện 1 → kết quả kỳ vọng}
654
+ - {nhánh/điều kiện 2 → kết quả kỳ vọng}
649
655
 
650
656
  ---
651
657
 
@@ -752,11 +758,14 @@ _(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã
752
758
 
753
759
  # Change Log
754
760
 
755
- ### v1.0 {mô tả} ({date})
761
+ > 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)*
762
+
763
+ <!-- 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;
764
+ cũ hơn → /refine-prd & /review-context tự dồn (rollover) sang file changelog/ ở link trên. -->
756
765
 
757
- | Mục | Thay đổi |
758
- |-----|----------|
759
- | | Bản đầu — sinh từ product-definition. |
766
+ | Version | Date | Changes (UC/AC/BR bị ảnh hưởng) |
767
+ |---------|------|---------------------------------|
768
+ | 1.0 | {date} | Bản đầu — sinh từ product-definition. |
760
769
 
761
770
  ---
762
771
 
@@ -774,6 +783,7 @@ _(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã
774
783
  ## Quality Checklist *(kiểm tra trước khi ghi)*
775
784
 
776
785
  - [ ] 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)
786
+ - [ ] **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ế)
777
787
  - [ ] Mỗi UC có Actor / Description / Pre-condition / Post-condition
778
788
  - [ ] §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
779
789
  - [ ] Business Rule (WHAT) và Business Logic (HOW) nằm chung bảng 3 cột `ID | Business Rule | Business Logic`
@@ -130,6 +130,7 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
130
130
  ## Quality Checklist *(kiểm tra trước khi ghi)*
131
131
 
132
132
  - [ ] 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)
133
+ - [ ] **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ế)
133
134
  - [ ] Mỗi UC có Actor / Description / Pre-condition / Post-condition
134
135
  - [ ] §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
135
136
  - [ ] Business Rule (WHAT) và Business Logic (HOW) nằm chung bảng 3 cột `ID | Business Rule | Business Logic`
@@ -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
113
113
  Rồi: /review-context --resume {feature-file} ← áp dụng các finding được chấp nhận còn lại
114
114
  Rồi chạy lại: /generate-tech-docs {feature-file}
115
115
  ```
116
+ 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.)*
116
117
 
117
118
  ## Context
118
119
  # Context Loader — Nạp toàn bộ context dự án
@@ -25,6 +25,7 @@
25
25
  Rồi: /review-context --resume {feature-file} ← áp dụng các finding được chấp nhận còn lại
26
26
  Rồi chạy lại: /generate-tech-docs {feature-file}
27
27
  ```
28
+ 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.)*
28
29
 
29
30
  ## Context
30
31
  {{include:steps/context-loader.md}}
@@ -466,7 +466,10 @@ Viết Gherkin nhất quán với convention của `/generate-bdd` cho `active_p
466
466
 
467
467
  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).
468
468
  KHÔNG đụng `.feature` canonical. Doc proposal chứa draft + metadata review
469
- (xem Output). Nếu nguồn là một bug, tham chiếu `BUG-ID` của nó.
469
+ (xem Output), **gồm dòng `Status: proposed`**. Nếu nguồn là một bug, tham chiếu `BUG-ID` của nó.
470
+
471
+ > **Vòng đời proposal** (máy đọc được để `/generate-bdd` intake đúng):
472
+ > `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.**
470
473
 
471
474
  ## Step 5 — Handoff (để PO/Dev thực sự thấy)
472
475
 
@@ -612,7 +615,8 @@ Scenario đề xuất (DRAFT — chờ PO/Dev review):
612
615
 
613
616
  Để PO/Dev promote:
614
617
  [ ] AC mapping đúng? (hoặc cập nhật PRD nếu requirement thực sự mới)
615
- [ ] Thêm scenario vào {bdd_path} (sửa, hoặc chạy lại /generate-bdd nếu PRD đổi)
618
+ [ ] Đặt `Status: accepted` trong file proposal (để /generate-bdd đưa vào)
619
+ [ ] Chạy lại /generate-bdd {UC-ID} — nó tự chèn proposal `accepted` vào .feature rồi lưu trữ
616
620
  [ ] Rồi: /generate-code {UC-ID} + /dev-gen-test {UC-ID}
617
621
 
618
622
  Handoff : {✅ committed + pushed to spec repo | ⚠️ chạy git command ở trên / mở PR}
@@ -71,7 +71,10 @@ Viết Gherkin nhất quán với convention của `/generate-bdd` cho `active_p
71
71
 
72
72
  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).
73
73
  KHÔNG đụng `.feature` canonical. Doc proposal chứa draft + metadata review
74
- (xem Output). Nếu nguồn là một bug, tham chiếu `BUG-ID` của nó.
74
+ (xem Output), **gồm dòng `Status: proposed`**. Nếu nguồn là một bug, tham chiếu `BUG-ID` của nó.
75
+
76
+ > **Vòng đời proposal** (máy đọc được để `/generate-bdd` intake đúng):
77
+ > `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.**
75
78
 
76
79
  ## Step 5 — Handoff (để PO/Dev thực sự thấy)
77
80
 
@@ -117,7 +120,8 @@ Scenario đề xuất (DRAFT — chờ PO/Dev review):
117
120
 
118
121
  Để PO/Dev promote:
119
122
  [ ] AC mapping đúng? (hoặc cập nhật PRD nếu requirement thực sự mới)
120
- [ ] Thêm scenario vào {bdd_path} (sửa, hoặc chạy lại /generate-bdd nếu PRD đổi)
123
+ [ ] Đặt `Status: accepted` trong file proposal (để /generate-bdd đưa vào)
124
+ [ ] Chạy lại /generate-bdd {UC-ID} — nó tự chèn proposal `accepted` vào .feature rồi lưu trữ
121
125
  [ ] Rồi: /generate-code {UC-ID} + /dev-gen-test {UC-ID}
122
126
 
123
127
  Handoff : {✅ committed + pushed to spec repo | ⚠️ chạy git command ở trên / mở PR}
@@ -411,6 +411,20 @@ Sau khi hoàn thành tất cả các bước, bạn đã nạp:
411
411
  Tiếp tục sang bước kế tiếp của lệnh đang gọi.
412
412
 
413
413
 
414
+ ---
415
+
416
+ ## Guard — BDD đã duyệt chưa
417
+
418
+ Đọc `# @trace.status:` từ header file `.feature` của UC target:
419
+ - `approved` → tiếp tục bình thường.
420
+ - `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):
421
+ ```
422
+ ⚠️ 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.
423
+ Khuyến nghị: review-context (BDD) sạch + người duyệt đặt `# @trace.status: approved` rồi mới chạy QC.
424
+ Vẫn chạy QC bây giờ? (Y/N)
425
+ ```
426
+ Chỉ tiếp khi chọn Y.
427
+
414
428
  ---
415
429
 
416
430
  ## Role
@@ -18,6 +18,20 @@ ported_from: ai-automation-qc-base
18
18
 
19
19
  ---
20
20
 
21
+ ## Guard — BDD đã duyệt chưa
22
+
23
+ Đọc `# @trace.status:` từ header file `.feature` của UC target:
24
+ - `approved` → tiếp tục bình thường.
25
+ - `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):
26
+ ```
27
+ ⚠️ 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.
28
+ Khuyến nghị: review-context (BDD) sạch + người duyệt đặt `# @trace.status: approved` rồi mới chạy QC.
29
+ Vẫn chạy QC bây giờ? (Y/N)
30
+ ```
31
+ Chỉ tiếp khi chọn Y.
32
+
33
+ ---
34
+
21
35
  ## Role
22
36
 
23
37
  Bạn là **QC Analyst** — stage đầu tiên của QC automation pipeline. Lấy requirement
@@ -574,6 +574,13 @@ mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
574
574
  List ONLY real, additional issues NOT already in the list — gaps, ambiguities,
575
575
  contradictions, missing edge/negative paths, coverage holes, terminology drift,
576
576
  structural omissions, and any issue that a fix to an existing finding would expose.
577
+ ALSO flag ROLE-BOUNDARY / altitude violations (you are NOT limited to adding detail):
578
+ content sitting in the WRONG section — detailed mechanism (retry counts, timeouts, flag
579
+ names/owners, error branches) written INSIDE an acceptance criterion or a scope line
580
+ instead of the Business Rule/Logic section; an AC that merely restates its referenced BR
581
+ (same content, converged); a term definition crammed into In/Out Scope. For these, the
582
+ suggestion must be to MOVE the detail to its proper section (AC keeps only the observable
583
+ outcome + BR ref) — NOT to delete it, and NOT to add more detail.
577
584
  Do NOT repeat anything already listed. Return the same finding JSON shape, or [] if
578
585
  nothing new.
579
586
  ```
@@ -638,8 +645,8 @@ Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
638
645
  **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
639
646
  toàn bộ PRD qua đúng lăng kính của nó:
640
647
 
641
- - **Lăng kính QA**: AC có testable không? Edge case đã nêu? Điều kiện biên đã định nghĩa?
642
- - **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? rủi ro kỹ thuật nào?
648
+ - **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.
649
+ - **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?
643
650
  - **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?
644
651
  - **Lăng kính PO**: Scope đã khoanh vùng? Priority rõ chưa? Success metric đã định nghĩa? Rủi ro scope creep?
645
652
 
@@ -886,6 +893,7 @@ Nếu có finding nào có `status: "needs_discussion"`, thêm warning block sau
886
893
  Với mỗi finding được chấp nhận, theo thứ tự severity (critical → major → minor):
887
894
  - Đi tới section PRD được chỉ định bởi `finding.section`.
888
895
  - Á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.
896
+ - **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.
889
897
  - **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.
890
898
  - 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.
891
899
 
@@ -909,10 +917,21 @@ Cập nhật `status: "applied"` ở **root level** của file findings (không
909
917
  - `| **Version** | {new_version} |`
910
918
  - `| **Updated** | {today YYYY-MM-DD} |`
911
919
  - `| **Status** | draft |` ← reset về draft, phải được duyệt lại
912
- 5. Thêm một row mới lên đầu `# Change Log` cuối PRD:
913
- ```
914
- | {new_version} | {today} | {tóm tắt súc tích mọi thay đổi đã áp dụng} |
915
- ```
920
+ 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):
921
+ - Thêm row mới lên **đầu** bảng:
922
+ ```
923
+ | {new_version} | {today} | {tóm tắt — KÈM UC/AC/BR bị ảnh hưởng, vd "UC2: sửa BR5; thêm AC7"} |
924
+ ```
925
+ *(Nêu rõ UC/AC/BR giúp `/generate-bdd` Version Check biết scenario nào cần cập nhật.)*
926
+ - 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)`
927
+ - **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:
928
+ ```
929
+ # Change Log (lịch sử) — {TICKET-ID}
930
+ > 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.
931
+
932
+ | Version | Date | Changes |
933
+ |---------|------|---------|
934
+ ```
916
935
  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").
917
936
 
918
937
  ### Phase 4 — Report
@@ -55,8 +55,8 @@ Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
55
55
  **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
56
56
  toàn bộ PRD qua đúng lăng kính của nó:
57
57
 
58
- - **Lăng kính QA**: AC có testable không? Edge case đã nêu? Điều kiện biên đã định nghĩa?
59
- - **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? rủi ro kỹ thuật nào?
58
+ - **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.
59
+ - **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?
60
60
  - **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?
61
61
  - **Lăng kính PO**: Scope đã khoanh vùng? Priority rõ chưa? Success metric đã định nghĩa? Rủi ro scope creep?
62
62
 
@@ -203,6 +203,7 @@ Nếu có finding nào có `status: "needs_discussion"`, thêm warning block sau
203
203
  Với mỗi finding được chấp nhận, theo thứ tự severity (critical → major → minor):
204
204
  - Đi tới section PRD được chỉ định bởi `finding.section`.
205
205
  - Á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.
206
+ - **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.
206
207
  - **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.
207
208
  - 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.
208
209
 
@@ -226,10 +227,21 @@ Cập nhật `status: "applied"` ở **root level** của file findings (không
226
227
  - `| **Version** | {new_version} |`
227
228
  - `| **Updated** | {today YYYY-MM-DD} |`
228
229
  - `| **Status** | draft |` ← reset về draft, phải được duyệt lại
229
- 5. Thêm một row mới lên đầu `# Change Log` cuối PRD:
230
- ```
231
- | {new_version} | {today} | {tóm tắt súc tích mọi thay đổi đã áp dụng} |
232
- ```
230
+ 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):
231
+ - Thêm row mới lên **đầu** bảng:
232
+ ```
233
+ | {new_version} | {today} | {tóm tắt — KÈM UC/AC/BR bị ảnh hưởng, vd "UC2: sửa BR5; thêm AC7"} |
234
+ ```
235
+ *(Nêu rõ UC/AC/BR giúp `/generate-bdd` Version Check biết scenario nào cần cập nhật.)*
236
+ - 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)`
237
+ - **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:
238
+ ```
239
+ # Change Log (lịch sử) — {TICKET-ID}
240
+ > 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.
241
+
242
+ | Version | Date | Changes |
243
+ |---------|------|---------|
244
+ ```
233
245
  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").
234
246
 
235
247
  ### Phase 4 — Report
@@ -585,6 +585,13 @@ mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
585
585
  List ONLY real, additional issues NOT already in the list — gaps, ambiguities,
586
586
  contradictions, missing edge/negative paths, coverage holes, terminology drift,
587
587
  structural omissions, and any issue that a fix to an existing finding would expose.
588
+ ALSO flag ROLE-BOUNDARY / altitude violations (you are NOT limited to adding detail):
589
+ content sitting in the WRONG section — detailed mechanism (retry counts, timeouts, flag
590
+ names/owners, error branches) written INSIDE an acceptance criterion or a scope line
591
+ instead of the Business Rule/Logic section; an AC that merely restates its referenced BR
592
+ (same content, converged); a term definition crammed into In/Out Scope. For these, the
593
+ suggestion must be to MOVE the detail to its proper section (AC keeps only the observable
594
+ outcome + BR ref) — NOT to delete it, and NOT to add more detail.
588
595
  Do NOT repeat anything already listed. Return the same finding JSON shape, or [] if
589
596
  nothing new.
590
597
  ```
@@ -713,8 +720,10 @@ Quét mỗi AC và BR tìm:
713
720
  | Tham chiếu chưa định nghĩa | "{SomeThing}" được dùng nhưng chưa định nghĩa trong PRD này | Major |
714
721
  | Thiếu luồng âm | AC chỉ mô tả happy path nhưng BR có điều kiện lỗi | Minor |
715
722
  | Câu bị động giấu actor | "Invoice is created" — ai tạo? | Minor |
723
+ | **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 |
724
+ | **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 |
716
725
 
717
- → AI không thể auto-fix finding P2. Người phải viết bản fix trong note "Modify" của Review Board.
726
+ → 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.
718
727
 
719
728
  ### P3 — Domain Conflict Check
720
729
 
@@ -994,8 +1003,10 @@ Lựa chọn tiếp theo:
994
1003
  → /review-context --resume {target-file}
995
1004
 
996
1005
  {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}:
997
- ✅ PRD đã sạch critical. Khi PO hài lòng → đặt `| **Status** | approved |` trong
998
- Metadata PRD (dấu duyệt nghiệp vụ, do người quyết) → rồi /generate-bdd.
1006
+ {If PRD}: ✅ PRD đã sạch critical. Khi PO hài lòng → đặt `| **Status** | approved |` trong
1007
+ Metadata PRD (dấu duyệt nghiệp vụ, do người quyết) → rồi /generate-bdd.
1008
+ {If BDD}: ✅ BDD đã sạch critical. Sau khi review xong → đặt `# @trace.status: approved` trong
1009
+ header file .feature (dấu duyệt BDD, do người quyết) → rồi /generate-tech-docs.
999
1010
  ```
1000
1011
 
1001
1012
  ---
@@ -1050,8 +1061,8 @@ Sau khi áp dụng mỗi finding, đánh dấu nó `status: "applied"` + `applie
1050
1061
  ### Phase 3 — Version bump
1051
1062
 
1052
1063
  - **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:
1053
- `Auto-fix: applied {N} auto-fixable review-context findings`
1054
- - **BDD**: nếu ≥1 finding được áp dụng → tăng `@trace.bdd_version` lên 0.1
1064
+ `| {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.
1065
+ - **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)
1055
1066
  - **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").
1056
1067
 
1057
1068
  ### Phase 4 — Report
@@ -1068,13 +1079,14 @@ Còn pending (cần quyết định của con người): {N}
1068
1079
  - F00X [{severity}] {tóm tắt finding} ← mở file findings trong Review Board
1069
1080
 
1070
1081
  {If PRD}: Version bumped: {old} → {new} | Status: reset về draft (cần duyệt lại)
1071
- {If BDD}: bdd_version: {old} → {new}
1082
+ {If BDD}: bdd_version: {old} → {new} | @trace.status: reset về draft (cần duyệt lại)
1072
1083
 
1073
1084
  File findings:
1074
1085
  {If PRD}: {paths.refinement_dir}/{prd-slug}-review-context-findings.yaml
1075
1086
  {If BDD}: {paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml
1076
1087
  Chạy lại /review-context {file} để xác nhận 0 finding critical còn lại.
1077
- Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
1088
+ {If PRD}: Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
1089
+ {If BDD}: Khi sạch critical + duyệt → đặt # @trace.status: approved trong header .feature rồi /generate-tech-docs.
1078
1090
  ```
1079
1091
 
1080
1092
  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: "
1108
1120
 
1109
1121
  > **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.
1110
1122
 
1123
+ > **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.
1124
+
1111
1125
  **Với finding PRD:**
1112
1126
  | check_id | Làm gì |
1113
1127
  |----------|-----------|
@@ -1117,7 +1131,7 @@ Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "
1117
1131
  | P4 (Structure) | Thêm section/metadata field còn thiếu (row Status vắng → thêm mặc định `draft`) |
1118
1132
  | P5 (Custom) | Áp dụng như nêu trong suggestion/note |
1119
1133
 
1120
- → 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").
1134
+ → 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").
1121
1135
 
1122
1136
  **Với finding BDD:**
1123
1137
  | check_id | Làm gì |
@@ -1129,8 +1143,8 @@ Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "
1129
1143
  | B5 (Metadata) | Thêm @trace header còn thiếu, sinh lại Coverage Matrix / Pre-merge Checklist |
1130
1144
  | B6 (Side effects) | Thêm `And <side-effect>` còn thiếu vào block Then |
1131
1145
 
1132
- → Sau khi áp dụng, tăng `@trace.bdd_version` trong header file lên 0.1.
1133
- → Đồ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.
1146
+ → 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).
1147
+ → Đồ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.
1134
1148
  → Ghi `applied_to_version: "{@trace.bdd_version mới}"` ở root level của findings (xem "Chọn full vs delta").
1135
1149
 
1136
1150
  ### Phase 3 — Report
@@ -1145,8 +1159,9 @@ Changes:
1145
1159
  - {tóm tắt change 2}
1146
1160
 
1147
1161
  {If PRD}: Version bumped: {old} → {new} | Status: reset về draft (cần duyệt lại)
1148
- {If BDD}: bdd_version: {old} → {new}
1162
+ {If BDD}: bdd_version: {old} → {new} | @trace.status: reset về draft (cần duyệt lại)
1149
1163
 
1150
1164
  Chạy lại /review-context {file} để xác nhận 0 finding critical còn lại.
1151
- Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
1165
+ {If PRD}: Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
1166
+ {If BDD}: Khi sạch critical + duyệt → đặt # @trace.status: approved trong header .feature rồi /generate-tech-docs.
1152
1167
  ```
@@ -130,8 +130,10 @@ Quét mỗi AC và BR tìm:
130
130
  | Tham chiếu chưa định nghĩa | "{SomeThing}" được dùng nhưng chưa định nghĩa trong PRD này | Major |
131
131
  | Thiếu luồng âm | AC chỉ mô tả happy path nhưng BR có điều kiện lỗi | Minor |
132
132
  | Câu bị động giấu actor | "Invoice is created" — ai tạo? | Minor |
133
+ | **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 |
134
+ | **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 |
133
135
 
134
- → AI không thể auto-fix finding P2. Người phải viết bản fix trong note "Modify" của Review Board.
136
+ → 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.
135
137
 
136
138
  ### P3 — Domain Conflict Check
137
139
 
@@ -311,8 +313,10 @@ Lựa chọn tiếp theo:
311
313
  → /review-context --resume {target-file}
312
314
 
313
315
  {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}:
314
- ✅ PRD đã sạch critical. Khi PO hài lòng → đặt `| **Status** | approved |` trong
315
- Metadata PRD (dấu duyệt nghiệp vụ, do người quyết) → rồi /generate-bdd.
316
+ {If PRD}: ✅ PRD đã sạch critical. Khi PO hài lòng → đặt `| **Status** | approved |` trong
317
+ Metadata PRD (dấu duyệt nghiệp vụ, do người quyết) → rồi /generate-bdd.
318
+ {If BDD}: ✅ BDD đã sạch critical. Sau khi review xong → đặt `# @trace.status: approved` trong
319
+ header file .feature (dấu duyệt BDD, do người quyết) → rồi /generate-tech-docs.
316
320
  ```
317
321
 
318
322
  ---
@@ -367,8 +371,8 @@ Sau khi áp dụng mỗi finding, đánh dấu nó `status: "applied"` + `applie
367
371
  ### Phase 3 — Version bump
368
372
 
369
373
  - **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:
370
- `Auto-fix: applied {N} auto-fixable review-context findings`
371
- - **BDD**: nếu ≥1 finding được áp dụng → tăng `@trace.bdd_version` lên 0.1
374
+ `| {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.
375
+ - **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)
372
376
  - **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").
373
377
 
374
378
  ### Phase 4 — Report
@@ -385,13 +389,14 @@ Còn pending (cần quyết định của con người): {N}
385
389
  - F00X [{severity}] {tóm tắt finding} ← mở file findings trong Review Board
386
390
 
387
391
  {If PRD}: Version bumped: {old} → {new} | Status: reset về draft (cần duyệt lại)
388
- {If BDD}: bdd_version: {old} → {new}
392
+ {If BDD}: bdd_version: {old} → {new} | @trace.status: reset về draft (cần duyệt lại)
389
393
 
390
394
  File findings:
391
395
  {If PRD}: {paths.refinement_dir}/{prd-slug}-review-context-findings.yaml
392
396
  {If BDD}: {paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml
393
397
  Chạy lại /review-context {file} để xác nhận 0 finding critical còn lại.
394
- Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
398
+ {If PRD}: Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
399
+ {If BDD}: Khi sạch critical + duyệt → đặt # @trace.status: approved trong header .feature rồi /generate-tech-docs.
395
400
  ```
396
401
 
397
402
  Nếu 0 finding nào auto-fixable → in:
@@ -425,6 +430,8 @@ Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "
425
430
 
426
431
  > **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.
427
432
 
433
+ > **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.
434
+
428
435
  **Với finding PRD:**
429
436
  | check_id | Làm gì |
430
437
  |----------|-----------|
@@ -434,7 +441,7 @@ Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "
434
441
  | P4 (Structure) | Thêm section/metadata field còn thiếu (row Status vắng → thêm mặc định `draft`) |
435
442
  | P5 (Custom) | Áp dụng như nêu trong suggestion/note |
436
443
 
437
- → 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").
444
+ → 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").
438
445
 
439
446
  **Với finding BDD:**
440
447
  | check_id | Làm gì |
@@ -446,8 +453,8 @@ Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "
446
453
  | B5 (Metadata) | Thêm @trace header còn thiếu, sinh lại Coverage Matrix / Pre-merge Checklist |
447
454
  | B6 (Side effects) | Thêm `And <side-effect>` còn thiếu vào block Then |
448
455
 
449
- → Sau khi áp dụng, tăng `@trace.bdd_version` trong header file lên 0.1.
450
- → Đồ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.
456
+ → 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).
457
+ → Đồ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.
451
458
  → Ghi `applied_to_version: "{@trace.bdd_version mới}"` ở root level của findings (xem "Chọn full vs delta").
452
459
 
453
460
  ### Phase 3 — Report
@@ -462,8 +469,9 @@ Changes:
462
469
  - {tóm tắt change 2}
463
470
 
464
471
  {If PRD}: Version bumped: {old} → {new} | Status: reset về draft (cần duyệt lại)
465
- {If BDD}: bdd_version: {old} → {new}
472
+ {If BDD}: bdd_version: {old} → {new} | @trace.status: reset về draft (cần duyệt lại)
466
473
 
467
474
  Chạy lại /review-context {file} để xác nhận 0 finding critical còn lại.
468
- Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
475
+ {If PRD}: Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
476
+ {If BDD}: Khi sạch critical + duyệt → đặt # @trace.status: approved trong header .feature rồi /generate-tech-docs.
469
477
  ```
@@ -488,6 +488,7 @@ Skip loại nào không có doc / không có revision đã lưu (`—`).
488
488
  *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).*
489
489
 
490
490
  Với mỗi file `.tsv` đã xử lý: ghi `spec_ver`, `status`, `last_updated` đã cập nhật lại disk.
491
+ Đồ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.
491
492
  **Đừ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.
492
493
 
493
494
  ### Step 7 — Tính aggregate cho dashboard
@@ -93,6 +93,7 @@ Skip loại nào không có doc / không có revision đã lưu (`—`).
93
93
  *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).*
94
94
 
95
95
  Với mỗi file `.tsv` đã xử lý: ghi `spec_ver`, `status`, `last_updated` đã cập nhật lại disk.
96
+ Đồ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.
96
97
  **Đừ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.
97
98
 
98
99
  ### Step 7 — Tính aggregate cho dashboard
@@ -1 +1 @@
1
- 0.14.7
1
+ 0.14.9