@educa-corp/sdd-framework 0.4.0 → 0.5.0

package/docs/02-concepts/traceability.md

@@ -1,94 +1,126 @@
-[← Roles & HITL](roles-and-hitl.md) · [Concepts](./) · [Architecture →](architecture.md)
-
-# Traceability — Truy vết đầu-cuối (End-to-end Trace)
-
-> Từ scenario nhìn xuống biết code nào hiện thực; từ code nhìn lên biết scenario nào yêu cầu. Đây là một trong ba "trái tim" của framework.
-
----
-
-## Trace tags theo artifact
-
-| Artifact | Trace tag |
-|----------|-----------|
-| **BDD scenario** | `@trace.id` · `@trace.scenario` · `@trace.business_rules` · `@trace.bdd_version` · `@trace.prd_version` |
-| **Code** (boundary only) | `@trace.implements` · `@trace.source` — *KHÔNG lưu version* (tránh dual SSOT) |
-| **Test** | `@trace.verifies` · `@trace.covers` |
-| **Bug fix** | `@trace.fixes` · `@trace.root_cause` · `@trace.regression` |
-
-→ Đầy đủ field & format: [Reference › Trace Schema](../04-reference/trace-schema.md).
-
----
-
-## Boundary-only tagging
-
-Chỉ tag `@trace` ở **boundary**, không tag mọi file → tránh **tag explosion**:
-
-| ✅ Tag | ❌ Không tag |
-|--------|-------------|
-| Controller / Handler / Middleware / Steps file | Entity / Repository / DTO / Interface / Base class |
-
-> Shared code (entity, repo) được dò qua **import chain** từ boundary — không cần tag riêng.
-
----
-
-## Trace state — file `.tsv`
-
-`.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` — mỗi UC × platform một sổ. Trong umbrella, nằm ở **spec repo dùng chung** (một nơi authoritative để PM/PO quản lý).
-
-| Cột | Chủ sở hữu | Ý nghĩa |
-|-----|-----------|---------|
-| `status` | `/generate-code`, `/validate-traces` | OK / GAP / DRIFT / UNTRACKED |
-| `implemented_by` | `/generate-code` | File code hiện thực SC |
-| `dev_selftest` | `/dev-run-test` | Smoke của **dev** |
-| `qc_status` | `/qc-run-test`, `/report-bug` | Trạng thái QC **chính thức** (Playwright) |
-| `bdd_version` / `spec_ver` | spec | Version để phát hiện drift |
-| `gen_ver` | `/generate-code` | Version lúc sinh code (so với `spec_ver`) |
-| `test_count` | test | Số test phủ SC |
-| `last_updated` | nhiều | Mốc cập nhật |
-
-> **`dev_selftest` ≠ `qc_status`.** Dev smoke (nhanh, tự kiểm) và QC chính thức (Playwright, evidence) là **hai trục độc lập** — không lấn quyền nhau.
-
----
-
-## Phân loại coverage (Coverage Status)
-
-`/validate-traces` phân loại mỗi SC theo **thứ tự ưu tiên** (rule sớm thắng):
-
-| # | Trạng thái | Điều kiện | Hành động |
-|---|-----------|-----------|-----------|
-| 1 | **UNTRACKED** | `gen_ver == —` | Chưa sinh code → `/generate-code` |
-| 2 | **DRIFT** | có code **và** `spec_ver != gen_ver` | Spec đổi → **regen trước khi test** |
-| 3 | **GAP** | có code **và** `test_count == — / 0` | Có code, chưa test → bù test |
-| 4 | **OK** | version khớp, có code, có test | Đủ phủ |
-
-> **DRIFT xét trước GAP:** SC có code + chưa test + spec vừa drift phải hiện `DRIFT` (không phải `GAP`) — vì `/generate-code` xử GAP = "skip codegen" còn DRIFT = "regenerate". Nếu GAP thắng, code lỗi thời bị bỏ qua.
-
----
-
-## Single SSOT cho version
-
-- **Version chỉ ở spec level** (`bdd_version`/`prd_version`). Code **không** lưu version riêng — nó dùng `.tsv` (`gen_ver`) để so.
-- Lưu version cả spec lẫn code = **dual SSOT** → drift không đáng tin.
-
----
-
-## Luồng truy vết (Trace Flow)
-
-```mermaid
-flowchart LR
-    PRD["PRD<br/>prd_version"] --> BDD["Scenario<br/>@trace.id + bdd_version"]
-    BDD --> CODE["Code boundary<br/>@trace.implements/source"]
-    CODE --> TEST["Test<br/>@trace.verifies"]
-    BDD -.-> TSV[".tsv state<br/>status/gen_ver/qc_status"]
-    CODE -.-> TSV
-    TEST -.-> TSV
-    TSV --> VM["/validate-traces<br/>Coverage Matrix"]
-```
-
----
-
-## Đọc tiếp (Next)
-
-- [Architecture](architecture.md) — 3 lớp & context-loader
-- [Pipeline › Validate Traces](pipeline-steps/09-validate-traces.md) — dùng ma trận coverage
-- [Reference › Trace Schema](../04-reference/trace-schema.md) — field đầy đủ
+[← Roles & HITL](roles-and-hitl.md) · [Concepts](./) · [Architecture →](architecture.md)
+
+# Traceability — Truy vết đầu-cuối (End-to-end Trace)
+
+> Từ scenario nhìn xuống biết code nào hiện thực; từ code nhìn lên biết scenario nào yêu cầu. Đây là một trong ba "trái tim" của framework.
+
+---
+
+## Trace tags theo artifact
+
+| Artifact | Trace tag |
+|----------|-----------|
+| **BDD file** (header) | `@trace.id` · **`@trace.platform`** · **`@trace.service`** · `@trace.module` · `@trace.domain` · `@trace.prd` · `@trace.prd_version` · `@trace.bdd_version` · `@trace.status` · `@trace.dataset` |
+| **BDD scenario** (mỗi SC) | `@trace.scenario` · **`@trace.sc_version`** · `@trace.business_rules` |
+| **Code** (boundary only) | `@trace.implements` · `@trace.source` · **`@trace.prd_version` · `@trace.bdd_version` · `@trace.tech_doc_revision`** · **`@trace.design_spec_version`** *(chỉ FE/App)* — lặp cả block theo **từng UC** trong file đa-UC |
+| **Code** (chỗ chưa implement) | `@trace.stub` · `@trace.stub_owner` · `@trace.stub_for` · `@trace.seam_pending` · `@trace.seam_port` |
+| **Test** | `@trace.verifies` |
+| **Bug fix** | `@trace.fixes` · `@trace.root_cause` · `@trace.regression` |
+
+→ Đầy đủ field & format: [Reference › Trace Schema](../04-reference/trace-schema.md).
+
+---
+
+## Boundary-only tagging
+
+Chỉ tag `@trace` ở **boundary**, không tag mọi file → tránh **tag explosion**:
+
+| ✅ Tag | ❌ Không tag |
+|--------|-------------|
+| Controller / Handler / Middleware / Steps file | Entity / Repository / DTO / Interface / Base class |
+
+> Shared code (entity, repo) được dò qua **import chain** từ boundary — không cần tag riêng.
+
+---
+
+## Trace state — file `.tsv`
+
+`.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` — mỗi UC × platform một sổ. Trong umbrella, nằm ở **spec repo dùng chung** (một nơi authoritative để PM/PO quản lý).
+
+| Cột | Chủ sở hữu | Ý nghĩa |
+|-----|-----------|---------|
+| `status` | `/generate-code`, `/validate-traces` | OK / GAP / DRIFT / UNTRACKED |
+| `implemented_by` | `/generate-code` | File code hiện thực SC |
+| `dev_selftest` | `/dev-run-test` | Smoke của **dev** |
+| `qc_status` | `/qc-run-test`, `/report-bug` | Trạng thái QC **chính thức** (Playwright) |
+| `bdd_version` / `spec_ver` | spec | Version để phát hiện drift |
+| `service` *(cột 23)* | `/generate-bdd` | Đội/submodule sở hữu SC — nguồn của `by_service` trên dashboard |
+| `design_spec_version` *(cột 24)* | `/generate-bdd` | Version design-spec lúc sinh BDD *(FE/App; `—` cho backend)* |
+
+**24 cột.** TSV cũ thiếu cột mới → đọc thành giá trị rỗng, **không báo lỗi**; header tự nâng ở lần `/generate-bdd` gen lại kế tiếp. Đọc theo **tên cột ở header row**, không theo vị trí.
+
+> **Làm mất hiệu lực ≠ ghi đè.** Chủ sở hữu là người **duy nhất** ghi giá trị **khẳng định** (`pass`/`fail`/số lượng). Nhưng lệnh nào làm giá trị đó **hết đúng** (spec đổi, code đổi) **bắt buộc** hạ nó về `not_run`/`—`. Giữ một `pass` sinh ra từ spec đã bị sửa là **báo cáo sai**, không phải tôn trọng quyền sở hữu cột. Ngoại lệ có chủ ý: `qc_owner`/`qc_blocked_by` (con trỏ bug vẫn còn giá trị) và `test_count`/`test_classes` (test vẫn trên đĩa — **cảnh báo**, không hạ số, để tỷ lệ coverage không nhảy loạn).
+| `gen_ver` | `/generate-code` | Version lúc sinh code (so với `spec_ver`) |
+| `test_count` | test | Số test phủ SC |
+| `last_updated` | nhiều | Mốc cập nhật |
+
+> **`dev_selftest` ≠ `qc_status`.** Dev smoke (nhanh, tự kiểm) và QC chính thức (Playwright, evidence) là **hai trục độc lập** — không lấn quyền nhau.
+
+---
+
+## Phân loại coverage (Coverage Status)
+
+`/validate-traces` phân loại mỗi SC theo **thứ tự ưu tiên** (rule sớm thắng):
+
+| # | Trạng thái | Điều kiện | Hành động |
+|---|-----------|-----------|-----------|
+| 1 | **UNTRACKED** | `gen_ver == —` | Chưa sinh code → `/generate-code` |
+| 2 | **DRIFT** | có code **và** `spec_ver != gen_ver` | Spec đổi → **regen trước khi test** |
+| 3 | **GAP** | có code **và** `test_count == — / 0` | Có code, chưa test → bù test |
+| 4 | **OK** | version khớp, có code, có test | Đủ phủ |
+
+> **DRIFT xét trước GAP:** SC có code + chưa test + spec vừa drift phải hiện `DRIFT` (không phải `GAP`) — vì `/generate-code` xử GAP = "skip codegen" còn DRIFT = "regenerate". Nếu GAP thắng, code lỗi thời bị bỏ qua.
+
+---
+
+## Version sống ở đâu — và vì sao code CŨNG mang version
+
+**Spec là SSOT của "version hiện tại". Code mang version của "lúc tôi được sinh ra".** Hai thứ khác nhau, nên không phải dual SSOT.
+
+| Nơi | Ghi cái gì | Ai ghi |
+|---|---|---|
+| `.feature` / PRD / tech-doc | version **hiện tại** của spec — SSOT | tác giả spec |
+| `.tsv` `spec_ver` | gương của `@trace.sc_version` hiện tại | `/generate-bdd`, `/validate-traces` |
+| `.tsv` `gen_ver` | version scenario **tại thời điểm codegen**, theo từng SC | `/generate-code` |
+| **Code** `@trace.prd_version` · `@trace.bdd_version` · `@trace.tech_doc_revision` · `@trace.design_spec_version` | version của **từng artifact upstream** tại thời điểm codegen, theo từng **method** | `/generate-code` |
+
+Drift = **so các mốc này với nhau**; sự lệch nhau chính là tín hiệu, không phải lỗi dữ liệu:
+
+- `spec_ver != gen_ver` → `DRIFT` (scenario đổi sau khi sinh code)
+- `@trace.prd_version` trong code < Version PRD hiện tại → `PRD_DRIFT`
+- `@trace.bdd_version` trong code < `.feature` hiện tại → `BDD_DRIFT`
+- `@trace.tech_doc_revision` trong code < `@trace.revision` của tech-doc → `TECHDOC_DRIFT`
+- `@trace.design_spec_version` trong code FE < Version design-spec → `DESIGNSPEC_DRIFT`
+
+> **Lệch version KHÔNG luôn là drift.** PRD và tech-doc là tài liệu **gộp** phủ nhiều UC nhưng chỉ có **một** số version. Thêm UC7 làm mọi UC cũ lệch số dù không đổi một chữ. Nên `/validate-traces` **lọc theo scope của row changelog**: UC có trong danh sách bị ảnh hưởng → `PRD_DRIFT` 🟠; không có → `PRD_STALE_REF` ⓘ (chỉ con trỏ cũ, sạch bằng `--realign-prd-version`); row changelog **mơ hồ** → 🟠 cho mọi UC (lưới an toàn).
+
+**Vì sao không thể bỏ tag version trong code và chỉ dựa vào `.tsv`:**
+
+1. **Độ phân giải khác nhau.** `.tsv` là một sổ cho mỗi UC × platform. Một **file code** có thể phục vụ nhiều UC, mỗi UC ở một version khác nhau — chỉ tag đặt cạnh từng method mới diễn đạt được "UC1 ở bdd v1.4, UC3 ở v2.1".
+2. **Vòng đời khác nhau.** `.tsv` là artifact **sinh ra**, có thể regen/xoá/mirror; ở chế độ umbrella nó còn nằm ở **repo khác** (spec submodule) với code. Tag trong code là bản ghi duy nhất **đi cùng** code qua mọi lần copy/move/merge.
+3. **Sự lệch nhau là thứ ta muốn đo.** Nếu chỉ có một bản ghi thì không có gì để so — đó mới là lúc drift trở nên không phát hiện được.
+
+> ⚠️ **Đừng "tối ưu" bằng cách gỡ tag version khỏi code.** `/validate-traces` Step 4/5/5c **đọc chính các tag đó**; gỡ đi là làm drift detection mù **im lặng** — build vẫn xanh, dashboard vẫn đẹp. `/review-code` lăng kính 1 gắn cờ **major** cho mỗi block `@trace.implements` thiếu tag version đi kèm.
+
+---
+
+## Luồng truy vết (Trace Flow)
+
+```mermaid
+flowchart LR
+    PRD["PRD<br/>prd_version"] --> BDD["Scenario<br/>@trace.id + bdd_version"]
+    BDD --> CODE["Code boundary<br/>@trace.implements/source"]
+    CODE --> TEST["Test<br/>@trace.verifies"]
+    BDD -.-> TSV[".tsv state<br/>status/gen_ver/qc_status"]
+    CODE -.-> TSV
+    TEST -.-> TSV
+    TSV --> VM["/validate-traces<br/>Coverage Matrix"]
+```
+
+---
+
+## Đọc tiếp (Next)
+
+- [Architecture](architecture.md) — 3 lớp & context-loader
+- [Pipeline › Validate Traces](pipeline-steps/09-validate-traces.md) — dùng ma trận coverage
+- [Reference › Trace Schema](../04-reference/trace-schema.md) — field đầy đủ

package/docs/03-guides/developer.md

@@ -34,11 +34,22 @@ flowchart LR
 ## Nguyên tắc sống còn cho Dev
 
 1. **Không sinh code cho file không có `.feature` backing** (ngoài fix-bug/debug).
-2. **Boundary-only tagging** — tag `@trace.implements` ở controller/handler, không tag entity/repo.
+2. **Boundary-only tagging** — tag `@trace` ở controller/handler, không tag entity/repo. Nhưng ở boundary thì phải **đủ block 5 tag** (dưới).
 3. **Scope Lock** — chỉ implement UC target; code UC khác trong file dùng chung là **bất khả xâm phạm**. Đọc `@trace.implements` để bảo toàn, đừng xoá.
-4. **Version chỉ ở spec** — code không lưu version; drift dò qua `.tsv`.
-5. **Build phải pass** trước commit (`{conventions.build_command}`, ≤3 retry).
-6. `CLAUDE.md` (§2 layer/package, §3 coding standards, §5 error handling) là nguồn — AI *follow*, bạn giữ nó cập nhật.
+4. **Code CŨNG mang version** — `@trace.prd_version` · `@trace.bdd_version` · `@trace.tech_doc_revision` ghi *"tôi được sinh theo bản nào"*, còn spec giữ *"bản hiện tại"*. Sự **lệch nhau** giữa hai mốc chính là tín hiệu drift. Đừng "tối ưu" bằng cách gỡ chúng — `/validate-traces` đọc đúng các tag đó.
+5. **File phủ nhiều UC → lặp cả block theo từng method.** Không gộp header, không trỏ `@trace.source` vào thư mục.
+6. **Sửa scenario thì bump `@trace.sc_version`** của chính SC đó — nếu bạn sửa `.feature` bằng tay. Quên bump = code cũ vĩnh viễn hiện `OK`.
+7. **Build phải pass** trước commit (`{conventions.build_command}`, ≤3 retry).
+8. `CLAUDE.md` (§2 layer/package, §3 coding standards, §5 error handling) là nguồn — AI *follow*, bạn giữ nó cập nhật.
+
+```java
+// @trace.implements=AUTH-UC1-SC3
+// @trace.prd_version=1.2   @trace.bdd_version=1.4   @trace.tech_doc_revision=3
+// @trace.source=specs/auth/login/bdd/system/AUTH-UC1-login.feature
+public TokenDto login(...) { }
+```
+
+→ Lý do đầy đủ (vì sao **không** phải dual-SSOT): [Traceability](../02-concepts/traceability.md)
 
 ---
 
@@ -67,8 +78,13 @@ flowchart LR
 
 - ❌ Tag `@trace` mọi file → tag explosion.
 - ❌ Tái tạo file dùng chung "chỉ gồm scenario UC này" → xoá nhầm nghiệp vụ UC khác.
+- ❌ Gộp tag của nhiều UC về một header file, hoặc trỏ `@trace.source` vào thư mục → drift báo oan hoặc mù; UC rơi về `UNTRACKED` dù đã có code.
+- ❌ Gỡ tag version khỏi code cho "gọn" → `/validate-traces` mù, **im lặng**.
 - ❌ Coi `dev_selftest` thay QC chính thức.
 - ❌ Để AI tự review code nó vừa sinh.
+- ❌ Tạo PR khi `/validate-traces` còn cờ 🔴 (`SEAM_UNWIRED` · `STUB_UNRESOLVED` · `ORPHANED` · `TRACE_ORPHAN`) — build xanh không chứng minh luồng ghép chạy đúng.
+- ❌ Coi FE `fe_phase = ui` là xong vì status đã `OK` — test đang chạy trên **mock**.
+- ❌ Tự đóng bug mình vừa fix — `/fix-bug` chỉ đặt `🟡 Fixed`; `🟢 Closed` là của `/qc-run-test`.
 
 ---
 

package/docs/03-guides/product-owner.md

@@ -1,68 +1,72 @@
-[← Docs Home](../README.md) · [Guides](./)
-
-# Guide · Product Owner / BA
-
-> Bạn **định nghĩa cái gì đáng làm**. Vai trò của bạn nặng nhất ở **thượng nguồn** (Discovery → PRD → BDD) — nơi sai một ly đi một dặm.
-
----
-
-## Chuỗi bước của bạn (Your path)
-
-```mermaid
-flowchart LR
-    A["/define-product<br/>🟢 Lead"] --> B["/generate-prd<br/>🟢 Lead"]
-    B --> C["/refine-prd<br/>🟢 accept findings"]
-    C --> D["/review-context PRD<br/>🔒 approve"]
-    D --> E["/generate-design-spec<br/>🟡 review (FE/App)"]
-    E --> F["/generate-bdd<br/>🟢 UC decomposition"]
-    F --> G["/review-context BDD<br/>🔒 approve"]
-```
-
-Sau khi BDD `approved`, bạn bàn giao xuống Dev/SA — nhưng vẫn nhận **product-gap** từ QC.
-
----
-
-## Việc của bạn ở mỗi bước
-
-| Bước | Bạn làm gì | Quyết định |
-|------|-----------|------------|
-| [Discovery](../02-concepts/pipeline-steps/01-discovery.md) | Trả lời Q&A 8 chặng, **chốt từng chặng** | Vấn đề, user, UC, BR, AC, edge case, scope |
-| [Specification](../02-concepts/pipeline-steps/02-specification.md) | Duyệt PRD draft; **accept/reject từng finding** của `/refine-prd`; đặt `Status: approved` | Scope & terminology đúng chưa |
-| [Design-Spec](../02-concepts/pipeline-steps/03-design-spec.md) | Review spec visual bám Figma (FE/App) | Visual khớp intent |
-| [BDD](../02-concepts/pipeline-steps/04-bdd.md) | Chốt **UC decomposition**; đặt `@trace.status: approved` | Cấu trúc UC/SC đúng |
-| [QC](../02-concepts/pipeline-steps/08-qc-automation.md) | Nhận **product-gap**, quyết ưu tiên sửa | Gap nào là lỗi sản phẩm |
-
----
-
-## Nguyên tắc sống còn cho PO
-
-1. **Viết thuần ngôn ngữ nghiệp vụ** — đừng nhét API/retry/timeout vào PRD/BDD. Business Language Guard sẽ chặn, nhưng bạn nên tự giữ altitude.
-2. **Bốn ngăn không lộn**: AC (nghiệm thu) · BR/BL (cơ chế) · Scope (ranh giới) · Dictionary (định nghĩa).
-3. **Gate là trạng thái, không phải lệnh** — "duyệt" = bạn tự đặt `| Status | approved |`. Chỉ đặt khi **sạch finding critical**.
-4. **Chốt từng chặng, đừng "để AI tự hiểu"** — AI sẽ suy diễn và bạn trả giá ở downstream.
-5. Khi bạn sửa cùng một kiểu nhiều lần → gợi ý team `/learn` để ghi lesson.
-
----
-
-## Câu hỏi bạn cần trả lời được
-
-- Tính năng này giải quyết pain point gì? Cho ai?
-- Gồm những UC/BR/AC nào? Edge case nào?
-- Cái gì **trong** scope, cái gì **ngoài**?
-- Mỗi scenario BDD có phủ đúng một AC/BR không?
-
----
-
-## Anti-pattern
-
-- ❌ Đặt `approved` khi còn finding critical → phá gate, code rác.
-- ❌ Bỏ `/refine-prd` "vì PRD trông ổn".
-- ❌ Nhảy từ ý tưởng thẳng sang yêu cầu Dev code.
-
----
-
-## Lệnh của bạn (Your commands)
-
-`/define-product` · `/generate-prd` · `/refine-prd` · `/review-context` · `/generate-design-spec` · `/generate-bdd`
-
-→ [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Glossary](../02-concepts/glossary.md)
+[← Docs Home](../README.md) · [Guides](./)
+
+# Guide · Product Owner / BA
+
+> Bạn **định nghĩa cái gì đáng làm**. Vai trò của bạn nặng nhất ở **thượng nguồn** (Discovery → PRD → BDD) — nơi sai một ly đi một dặm.
+
+---
+
+## Chuỗi bước của bạn (Your path)
+
+```mermaid
+flowchart LR
+    A["/define-product<br/>🟢 Lead"] --> B["/generate-prd<br/>🟢 Lead"]
+    B2["/extend-prd<br/>🟢 Lead — PRD đã có"] --> C
+    B --> C["/refine-prd<br/>🟢 accept findings"]
+    C --> D["/review-context PRD<br/>🔒 approve"]
+    D --> E["/generate-design-spec<br/>🟡 review (FE/App)"]
+    E --> F["/generate-bdd<br/>🟢 UC decomposition"]
+    F --> G["/review-context BDD<br/>🔒 approve"]
+```
+
+Sau khi BDD `approved`, bạn bàn giao xuống Dev/SA — nhưng vẫn nhận **product-gap** từ QC.
+
+---
+
+## Việc của bạn ở mỗi bước
+
+| Bước | Bạn làm gì | Quyết định |
+|------|-----------|------------|
+| [Discovery](../02-concepts/pipeline-steps/01-discovery.md) | Trả lời Q&A 8 chặng, **chốt từng chặng** | Vấn đề, user, UC, BR, AC, edge case, scope |
+| [Specification](../02-concepts/pipeline-steps/02-specification.md) | Duyệt PRD draft; **accept/reject từng finding** của `/refine-prd`; đặt `Status: approved` | Scope & terminology đúng chưa |
+| [Design-Spec](../02-concepts/pipeline-steps/03-design-spec.md) | Review spec visual bám Figma (FE/App) | Visual khớp intent |
+| [BDD](../02-concepts/pipeline-steps/04-bdd.md) | Chốt **UC decomposition**; đặt `@trace.status: approved` | Cấu trúc UC/SC đúng |
+| [QC](../02-concepts/pipeline-steps/08-qc-automation.md) | Nhận **product-gap**, quyết ưu tiên sửa | Gap nào là lỗi sản phẩm |
+
+---
+
+## Nguyên tắc sống còn cho PO
+
+1. **Viết thuần ngôn ngữ nghiệp vụ** — đừng nhét API/retry/timeout vào PRD/BDD. Business Language Guard sẽ chặn, nhưng bạn nên tự giữ altitude.
+2. **Bốn ngăn không lộn**: AC (nghiệm thu) · BR/BL (cơ chế) · Scope (ranh giới) · Dictionary (định nghĩa).
+3. **Gate là trạng thái, không phải lệnh** — "duyệt" = bạn tự đặt `| Status | approved |`. Chỉ đặt khi **sạch finding critical**.
+4. **Chốt từng chặng, đừng "để AI tự hiểu"** — AI sẽ suy diễn và bạn trả giá ở downstream.
+5. Khi bạn sửa cùng một kiểu nhiều lần → gợi ý team `/learn` để ghi lesson.
+
+---
+
+## Câu hỏi bạn cần trả lời được
+
+- Tính năng này giải quyết pain point gì? Cho ai?
+- Gồm những UC/BR/AC nào? Edge case nào?
+- Cái gì **trong** scope, cái gì **ngoài**?
+- Mỗi scenario BDD có phủ đúng một AC/BR không?
+
+---
+
+## Anti-pattern
+
+- ❌ Đặt `approved` khi còn finding critical → phá gate, code rác.
+- ❌ Bỏ `/refine-prd` "vì PRD trông ổn".
+- ❌ Chạy `/generate-prd` lại trên PRD đã có để "cập nhật" — nó **từ chối chạy**, và đúng vậy: ghi đè sẽ mất changelog + đánh số lại BR (phá liên kết ở mọi `.feature` đã sinh). Thêm yêu cầu thì dùng **`/extend-prd`**.
+- ❌ Viết dòng changelog kiểu `"cập nhật theo yêu cầu mới"` — dòng đó là **contract**. Mơ hồ thì `/generate-bdd` gen lại **toàn bộ**, và `/validate-traces` báo động oan cho **mọi** UC thay vì chỉ UC vừa đổi. Luôn nêu **UC/AC/BR bị ảnh hưởng**.
+- ❌ Để `feedback/prd-change-requests/` chất đống — đó là yêu cầu thật tester phát hiện từ sản phẩm chạy thật, và **không cờ trace nào bắt được** (chưa có AC thì theo mọi thước đo coverage nó *không tồn tại*). `/validate-traces` nhắc kèm số ngày chờ; xử bằng `/extend-prd`.
+- ❌ Nhảy từ ý tưởng thẳng sang yêu cầu Dev code.
+
+---
+
+## Lệnh của bạn (Your commands)
+
+`/define-product` · `/generate-prd` · `/extend-prd` · `/refine-prd` · `/review-context` · `/generate-design-spec` · `/generate-bdd`
+
+→ [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Glossary](../02-concepts/glossary.md)

package/docs/03-guides/tester-qa.md

@@ -1,70 +1,81 @@
-[← Docs Home](../README.md) · [Guides](./)
-
-# Guide · Tester / QA
-
-> Bạn **chạy kiểm thử chính thức** (dây chuyền `/qc-*`, Playwright) và là **kênh feedback** đưa bug/scenario ngược về spec. Bạn ghi `qc_status` — trạng thái QC chính thức, có evidence.
-
----
-
-## Chuỗi bước của bạn (Your path)
-
-```mermaid
-flowchart LR
-    A["/qc-analyze"] --> P["/qc-plan"] --> D["/qc-design-test"]
-    D --> R["/qc-review<br/>🛑 cổng"] --> RUN["/qc-run-test<br/>ghi qc_status"] --> REP["/qc-report<br/>product-gap"]
-    REP --> FB["/report-bug · /propose-scenario"]
-    FB --> SYNC["/sync"]
-```
-
----
-
-## Việc của bạn ở mỗi bước
-
-| Trạm | Bạn làm gì |
-|------|-----------|
-| [`/qc-analyze`](../02-concepts/pipeline-steps/08-qc-automation.md) | Phân rã yêu cầu + phát hiện **gap tài liệu** |
-| `/qc-plan` | Đánh giá rủi ro + câu hỏi cho dev |
-| `/qc-design-test` | Thiết kế test case Markdown (`*.Test.md`) |
-| `/qc-review` | 🛑 **Cổng review** case & script trước khi chạy |
-| `/qc-run-test` | Chạy pytest-playwright, ghi **`qc_status`**; phân loại FAIL |
-| `/qc-report` | Report + evidence, đẩy **product-gap** về PO/Dev |
-| [Feedback](../02-concepts/pipeline-steps/10-feedback-loop.md) | `/report-bug`, `/propose-scenario` — kênh có hồ sơ spec |
-
-Bạn cũng dùng `/validate-traces` để thấy **gap chưa phủ** (spec ↔ code ↔ test).
-
----
-
-## Nguyên tắc sống còn cho QA
-
-1. **`qc_status` ≠ `dev_selftest`** — bạn ghi QC chính thức (Playwright, evidence); dev smoke là trục độc lập.
-2. **Không bao giờ fake-pass** — FAIL do product-gap thì **giữ FAIL + evidence**, đẩy về PO/Dev. Chỉ sửa script khi là script-bug (selector/logic).
-3. **Không chạy test kém** — phải qua cổng `/qc-review` trước `/qc-run-test`.
-4. **Bug phải spec-anchored** — `/report-bug` gắn `@trace` tới UC/SC để truy vết & regression.
-5. Stack QC cố định: Python + pytest-playwright + Page Object (module `qc-playwright`), **độc lập** module của dev.
-
----
-
-## Câu hỏi bạn cần trả lời được
-
-- Yêu cầu phân rã thành test case nào? Tài liệu có gap gì?
-- Rủi ro nào cao? Cần hỏi dev gì?
-- SC nào PASS/FAIL chính thức? FAIL là **script-bug** hay **product-gap**?
-- Bug này gắn với scenario/spec nào?
-- Scenario nào còn thiếu cần đề xuất (`/propose-scenario`)?
-
----
-
-## Anti-pattern
-
-- ❌ Sửa script cho "xanh" khi thực chất là product-gap → giấu lỗi sản phẩm.
-- ❌ Chạy `/qc-run-test` khi chưa qua `/qc-review`.
-- ❌ Lẫn `qc_status` với `dev_selftest`.
-- ❌ Bug không gắn spec → khó truy vết, khó regression.
-
----
-
-## Lệnh của bạn (Your commands)
-
-`/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` · `/report-bug` · `/propose-scenario` · `/validate-traces`
-
-→ [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Traceability](../02-concepts/traceability.md)
+[← Docs Home](../README.md) · [Guides](./)
+
+# Guide · Tester / QA
+
+> Bạn **chạy kiểm thử chính thức** (dây chuyền `/qc-*`, Playwright) và là **kênh feedback** đưa bug/scenario ngược về spec. Bạn ghi `qc_status` — trạng thái QC chính thức, có evidence.
+
+---
+
+## Chuỗi bước của bạn (Your path)
+
+```mermaid
+flowchart LR
+    A["/qc-analyze"] --> P["/qc-plan"] --> D["/qc-design-test"]
+    D --> R["/qc-review<br/>🛑 cổng"] --> RUN["/qc-run-test<br/>ghi qc_status"] --> REP["/qc-report<br/>product-gap"]
+    REP --> FB["/report-bug · /propose-scenario"]
+    FB --> SYNC["/sync"]
+```
+
+---
+
+## Việc của bạn ở mỗi bước
+
+| Trạm | Bạn làm gì |
+|------|-----------|
+| [`/qc-analyze`](../02-concepts/pipeline-steps/08-qc-automation.md) | Phân rã yêu cầu + phát hiện **gap tài liệu** |
+| `/qc-plan` | Đánh giá rủi ro + câu hỏi cho dev |
+| `/qc-design-test` | Thiết kế test case Markdown (`*.Test.md`) |
+| `/qc-review` | 🛑 **Cổng review** case & script trước khi chạy |
+| `/qc-run-test` | Chạy pytest-playwright, ghi **`qc_status`**; phân loại FAIL |
+| `/qc-report` | Report + evidence, đẩy **product-gap** về PO/Dev |
+| [Feedback](../02-concepts/pipeline-steps/10-feedback-loop.md) | `/report-bug`, `/propose-scenario` — kênh có hồ sơ spec |
+
+Bạn cũng dùng `/validate-traces` để thấy **gap chưa phủ** (spec ↔ code ↔ test).
+
+---
+
+## Nguyên tắc sống còn cho QA
+
+1. **`qc_status` ≠ `dev_selftest`** — bạn ghi QC chính thức (Playwright, evidence); dev smoke là trục độc lập.
+2. **Không bao giờ fake-pass** — FAIL do product-gap thì **giữ FAIL + evidence**, đẩy về PO/Dev. Chỉ sửa script khi là script-bug (selector/logic).
+3. **Không chạy test kém** — phải qua cổng `/qc-review` trước `/qc-run-test`.
+4. **Bug phải spec-anchored** — `/report-bug` gắn `@trace` tới UC/SC để truy vết & regression.
+5. **Bạn là người ĐÓNG bug** — `/fix-bug` của dev chỉ đặt `🟡 Fixed`; `🟢 Closed` do `/qc-run-test` đặt khi `qc_status` của SC liên kết flip `pass`. Dev không tự đóng bug của mình.
+   - Ngoại lệ: SC pass mà bug còn `🟢 Open` (chưa ai fix) → **không đóng**, giữ `Open` + kiểm tra lại test. Test pass trên bug chưa fix là dấu hiệu **test sai**.
+6. **`/propose-scenario` dùng đúng bộ tag canonical** — `@trace.scenario` (placeholder `SC?`, `/generate-bdd` gán số khi chèn) · `@trace.sc_version: 1.0` · `@trace.business_rules`. AC ghi thành comment `# Covers:`, **không** phải trace key. Thiếu `@trace.scenario`/`sc_version` thì scenario vào BDD mà **không có row trace** → vô hình với coverage.
+7. Stack QC cố định: Python + pytest-playwright + Page Object (module `qc-playwright`), **độc lập** module của dev.
+
+---
+
+## Câu hỏi bạn cần trả lời được
+
+- Yêu cầu phân rã thành test case nào? Tài liệu có gap gì?
+- Rủi ro nào cao? Cần hỏi dev gì?
+- SC nào PASS/FAIL chính thức? FAIL là **script-bug** hay **product-gap**?
+- Bug này gắn với scenario/spec nào?
+- Scenario nào còn thiếu cần đề xuất (`/propose-scenario`)?
+- Hành vi phát hiện được có **AC nào phủ** không? → quyết định Case A hay Case B:
+
+  | | Đi đâu | Ai xử |
+  |---|---|---|
+  | **Case A** — thiếu scenario cho AC **đã có** | `feedback/bdd-proposals/` | `/generate-bdd` tự chèn khi bạn đặt `Status: accepted` |
+  | **Case B** — requirement **MỚI**, không AC nào phủ | `feedback/prd-change-requests/` | PO chạy `/extend-prd` |
+
+  Case B **không tự vào BDD được** — scenario chưa có AC để trace tới. Và vì chưa có AC, **không cờ trace nào bắt được** thiếu sót đó. `/validate-traces` sẽ nhắc lại kèm **số ngày chờ** chừng nào request còn `Open`.
+
+---
+
+## Anti-pattern
+
+- ❌ Sửa script cho "xanh" khi thực chất là product-gap → giấu lỗi sản phẩm.
+- ❌ Chạy `/qc-run-test` khi chưa qua `/qc-review`.
+- ❌ Lẫn `qc_status` với `dev_selftest`.
+- ❌ Bug không gắn spec → khó truy vết, khó regression.
+
+---
+
+## Lệnh của bạn (Your commands)
+
+`/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` · `/report-bug` · `/propose-scenario` · `/validate-traces`
+
+→ [Bảng lệnh đầy đủ](../04-reference/commands.md) · [Traceability](../02-concepts/traceability.md)