@educa-corp/sdd-framework 0.9.4 → 0.9.6

package/docs/explain/16-qc-plan.md

@@ -32,7 +32,10 @@ Không phải mọi scenario rủi ro ngang nhau. Trạm này xếp ưu tiên te
 1. **Role qa-planner** — nạp `{qc_skills_dir}/qa-planner/`.
 2. Đọc analysis + gap → **đánh giá rủi ro** từng vùng.
 3. Nêu **câu hỏi cho dev** (điểm chưa rõ để test đúng).
-4. **Output** TEST_PLAN.md.
+4. **Self-Review** *(mới)* — nạp `skills/qc/_shared/self-review-principles.md`, soát một lượt trước khi in report.
+5. **Output** TEST_PLAN.md.
+> **Self-Review ≠ Guard.** Guard là phép **đếm cơ học**, có hệ quả bắt buộc khi lệch. Self-review là lượt đọc lại **rộng hơn nhưng mềm hơn**, soát ba nhóm lỗi mà phép đếm không bắt được (bịa dữ kiện · lẫn suy đoán với sự thật · bỏ dở giữa chừng). Một bộ nguyên tắc tự soát **không bao giờ** được dùng làm lý do gỡ một Guard — chính file `self-review-principles.md` ghi rõ ranh giới đó ngay ở đầu.
+
 
 ---
 
@@ -46,6 +49,7 @@ Không phải mọi scenario rủi ro ngang nhau. Trạm này xếp ưu tiên te
 
 - **Risk-based** — kế hoạch bám rủi ro, không phủ đều.
 - **Câu hỏi cho dev** — kênh QC ↔ Dev có hồ sơ trước khi viết test.
+- **Self-Review dùng chung** — sáu trạm QC nạp **cùng một** file nguyên tắc, không mỗi trạm một bản. Sáu bản sao thì sáu tháng sau sẽ là sáu luật khác nhau, **im lặng**.
 
 ---
 

package/docs/explain/17-qc-design-test.md

@@ -15,12 +15,13 @@ Tách "thiết kế test case" (con người đọc/review được) khỏi "cod
 ## Vị trí & tiền đề
 
 - **Vị trí:** Phase QC (trạm 3), sau `/qc-plan`.
+- **Không cần code.** Trạm này chỉ cần spec + **hợp đồng test-id §4.5.6** (đã chốt ở `/map-testids`, trước `/generate-code`). Nên nó chạy **song song với FE**.
 
 ---
 
 ## Input / Output
 
-**Input:** TEST_PLAN.md + skill `qa-designer` (chọn layer, nạp MỘT file).
+**Input:** TEST_PLAN.md + skill `qa-designer` (chọn layer, nạp MỘT file) + `.feature` (nguồn scenario cho Guard) + **§4.5.6 Test Selectors**.
 
 **Output:** `{qc_dir}/{TICKET-ID}/{platform}/test-cases/*.Test.md` (trace mapping bắt buộc). Gọi theo **từng UC**, ghi vào thư mục test-case dùng chung cấp PRD.
 
@@ -31,13 +32,31 @@ Tách "thiết kế test case" (con người đọc/review được) khỏi "cod
 1. **Role qa-designer** — chọn layer, nạp một file skill (không nạp cả bộ → tiết kiệm context).
 2. **Conventions** — theo quy ước test-case của QC team.
 3. **Trace mapping (bắt buộc)** — mỗi test case ↔ SC.
-4. **Output** `.Test.md`.
+4. **Guard — SC coverage** *(mới)* — phép **đếm cơ học**, không phải lượt đọc lại:
+
+   ```
+   1. Thu SC — mọi @trace.scenario trong .feature của uc_list (đúng nền).
+               LOẠI SC của UC mà qc-scope đã lọc ra (⏸ BDD chưa approved).
+   2. Thu V  — mọi @trace.verifies trong các file *.Test.md VỪA GHI.
+   3. Đếm    — mỗi SC ∈ tập bước 1 phải có ≥ 1 TC trỏ tới.
+   ```
+
+   | Kết quả | Hành vi |
+   |---|---|
+   | Mọi SC đều có ≥1 TC | in `Guard SC coverage: khớp {K}/{K}` |
+   | Có SC chưa phủ | **viết bù TC ngay**, rồi in `⚠️ Guard SC coverage: {K}/{total} — đã bù {m} SC: {…}` |
+
+   **In dòng này kể cả khi sạch** — guard im lặng khi sạch là guard không ai biết nó tồn tại, nên cũng không ai phát hiện khi nó hỏng.
+
+5. **Self-Review** — nạp `skills/qc/_shared/self-review-principles.md`, soát một lượt trước khi in report.
+6. **Output** `.Test.md`.
 
 ---
 
 ## Checkpoint & Gate
 
-- Không gate ở đây; gate là `/qc-review` kế tiếp.
+- Không gate chặn người ở đây; gate là `/qc-review` kế tiếp.
+- Nhưng Guard SC coverage **có hệ quả bắt buộc**: thiếu thì lệnh **viết bù** rồi mới báo, không phải chỉ cảnh báo.
 
 ---
 
@@ -46,6 +65,8 @@ Tách "thiết kế test case" (con người đọc/review được) khỏi "cod
 - **Markdown-first** — test case là tài liệu review được trước khi thành code.
 - **Nạp MỘT file skill theo layer** — tối ưu context (chỉ layer cần).
 - **Trace mapping** — giữ test case gắn SC để về sau ghi `qc_status` đúng.
+- **Guard SC coverage KHÔNG có đường thoát.** SC bị gap chặn **vẫn** phải có TC — viết đủ, mang dấu `🚫 Block: [GAP-UC{N}-{nnn}] — lý do`. Gap là thứ được **ghi vào** test case, không phải cái cớ để không viết. Cho phép "bỏ trống có lý do" là dạy hai luật trái nhau trong cùng một lệnh, và cho agent một câu-lý-do-cho-qua.
+- **Guard ≠ Self-Review.** Guard là phép **đếm**, có hệ quả bắt buộc. Self-review là lượt đọc lại rộng hơn nhưng mềm hơn. Không bao giờ dùng self-review làm lý do gỡ Guard.
 
 ---
 
@@ -53,6 +74,8 @@ Tách "thiết kế test case" (con người đọc/review được) khỏi "cod
 
 - **Tách design ↔ script** thêm một trạm nhưng cho phép review sớm — đánh đổi giữa số bước và chất lượng gate.
 - **Phụ thuộc convention QC team** — cần đồng bộ khi convention đổi.
+- **Guard đếm sớm, ở chỗ còn sửa được.** `/qc-report` cũng tính design coverage bằng **đúng phép đếm này**, nhưng ở **cuối** — lúc đó chỉ còn kịp báo, không còn kịp viết bù. Cùng một phép đếm, giá trị khác hẳn theo thời điểm.
+- Con số `{K}/{total}` vốn **đã in** ở report từ trước, nhưng **không có phép tính nào đứng sau nó**. Một con số trong báo cáo không chứng minh có phép đo.
 
 ---
 

package/docs/explain/18-qc-review.md

@@ -29,8 +29,11 @@ Không chạy test kém. Trạm này chặn: (1) test case chưa đủ tốt tr
 ## Các bước xử lý (chi tiết)
 
 1. **Role qa-reviewer** — nạp `{qc_skills_dir}/qa-reviewer/`.
-2. **Review focus** — kiểm test case (đủ phủ, đúng SC) hoặc script (đúng logic, selector, không fake-pass).
-3. Verdict: APPROVED → đi tiếp; NEEDS_FIX → sửa rồi review lại.
+2. **Review focus** — kiểm test case (đủ phủ, đúng SC) hoặc script (đúng logic, **selector bám §4.5.6 chứ không dò DOM**, không fake-pass).
+3. **Self-Review** *(mới)* — nạp `skills/qc/_shared/self-review-principles.md`, soát một lượt trước khi in report.
+4. Verdict: APPROVED → đi tiếp; NEEDS_FIX → sửa rồi review lại.
+> **Self-Review ≠ Guard.** Guard là phép **đếm cơ học**, có hệ quả bắt buộc khi lệch. Self-review là lượt đọc lại **rộng hơn nhưng mềm hơn**, soát ba nhóm lỗi mà phép đếm không bắt được (bịa dữ kiện · lẫn suy đoán với sự thật · bỏ dở giữa chừng). Một bộ nguyên tắc tự soát **không bao giờ** được dùng làm lý do gỡ một Guard — chính file `self-review-principles.md` ghi rõ ranh giới đó ngay ở đầu.
+
 
 ---
 
@@ -44,6 +47,7 @@ Không chạy test kém. Trạm này chặn: (1) test case chưa đủ tốt tr
 
 - **Một lệnh, hai vai** — review case và review script dùng chung skill, khác focus.
 - **Gate thật của QC** — điểm HITL chính trong dây chuyền tự động.
+- **Review script thì soát cả nguồn selector** — script lấy locator từ §4.5.6 Test Selectors, hay tự dò DOM? Dò DOM là script giòn: dev đổi một class là vỡ, và **không ai báo**.
 
 ---
 

package/docs/explain/19-qc-run-test.md

@@ -36,20 +36,41 @@
 1. **Role & stack** — qc-playwright (`stack-profile.yaml`): Python, pytest-playwright fixture, Page Object; mỗi test độc lập; gom theo (role, account) để auth không xen kẽ.
 2. **Skills** — nạp một file skill `qa-runner` theo layer.
 3. **Sinh script** từ `.Test.md`; tag `@trace.verifies={UC-ID}-SC{N}`.
-4. **Chạy** — phân loại mỗi FAIL: **script-bug** (fix selector/logic) vs **product-gap** (giữ FAIL + evidence, **không bao giờ fake-pass**).
+4. **Chạy.** Test đỏ **một lần** chưa nói được nó đỏ vì cái gì → **chạy lại riêng test đó, tối đa 2 lần**, rồi mới phân loại thành **ba** nhãn:
+
+   ```
+   đỏ → đỏ → đỏ     ⇒ NHẤT QUÁN       → sang bước điều tra: script-bug | product-gap
+   đỏ → xanh        ⇒ KHÔNG NHẤT QUÁN → flaky
+   đỏ → đỏ → xanh   ⇒ KHÔNG NHẤT QUÁN → flaky
+   ```
+
+   | Nhãn | Khi nào | Hệ quả |
+   |---|---|---|
+   | `script-bug` | Sai locator / logic test / timing / dữ liệu test | QC tự sửa. **Không** mở bug |
+   | `product-gap` | Hành vi thật ≠ spec — defect thật | Mở bug qua `/report-bug`. Giữ `fail` + evidence, **không bao giờ fake-pass** |
+   | `flaky` | Không nhất quán ở bước chạy lại — **chưa đủ căn cứ** | Cách ly + ghi **nghi vấn** nguyên nhân. **Không** mở bug từ một lần chạy hên xui |
+
+   **Điều tra bằng bằng chứng, không đoán** — đọc trace/video/log: timeline, DOM snapshot, network, console **tại thời điểm fail**. Không chắc giữa `script-bug` và `product-gap` → **mời Dev cùng xem trace**.
+
+   🛑 **Người xác nhận TRƯỚC khi hành động** — lệnh in đề xuất kèm evidence cụ thể rồi **dừng chờ**. **Không ghi `qc_status`** cho scenario nào còn FAIL chưa được xác nhận nhãn.
 5. **Write Trace State — `qc_status`** (kết quả QC chính thức) + `qc_run_at`, `qc_owner`, `qc_blocked_by`, `last_updated`.
 
    ⚠️ **ĐỌC cột `status` TRƯỚC KHI GHI `pass`** *(GAPS-v4 G55, đối xứng `/dev-run-test`)*: row `DRIFT`/`ORPHANED` + test xanh → **`not_run`**, không bao giờ `pass`. `fail` và `skip` ghi bình thường — chỉ giá trị **khẳng định** cần giấy phép.
 
    Và ở lệnh này hậu quả đi **xa hơn** `/dev-run-test`: một `pass` sai còn **đóng một bug** (§Đóng bug đã verify). Nên khi hạ về `not_run`, lệnh **KHÔNG** clear `qc_owner`/`qc_blocked_by` và **KHÔNG** chạy bước đóng bug — đóng bug dựa trên một lần QC chạy trên spec đã đổi là đóng sai.
-6. **Đóng bug đã verify** — chạy **TRƯỚC** bước clear cột (xem dưới).
-7. **Refresh Panel Mirror** — Living Docs local.
+   `flaky` → `qc_status = not_run`, `qc_owner = qc`. Không tạo trạng thái mới: `not_run` đúng nghĩa *"chưa có kết luận"*, và `qc_owner = qc` để nó không rơi vào khoảng không ai nhận.
+6. **Self-Review** *(mới)* — nạp `skills/qc/_shared/self-review-principles.md`, soát một lượt trước khi in report.
+7. **Đóng bug đã verify** — chạy **TRƯỚC** bước clear cột (xem dưới).
+8. **Refresh Panel Mirror** — Living Docs local.
 
 ---
 
 ## Checkpoint & Gate
 
 - Tiền đề: case đã APPROVED ở `/qc-review`. Script sinh ra → review lại ở `/qc-review` (script) trước PR.
+- 🛑 **Xác nhận nhãn FAIL** — cổng chặn được **thêm vào**, trong khi framework vốn đang giảm số cổng chặn (G41). Lý do: **cả hai hướng sai đều không đảo ngược rẻ.** Gắn nhầm `script-bug` cho lỗi sản phẩm thật là **giấu bug** cho tới khi khách gặp; mở bug từ một lần chạy hên xui là **đốt thời gian dev** và làm mòn niềm tin vào QC.
+
+> **Đây KHÔNG phải `retries` trong config test runner.** `retries` tự thử lại rồi báo *"passed on retry"* — nó **che** sự không nhất quán. Ở đây chạy **tách biệt từng lần để quan sát**, vì chính sự không nhất quán mới là thông tin cần.
 
 ---
 
@@ -57,6 +78,7 @@
 
 - **`qc_status` là trục authoritative** — khác `dev_selftest`; có evidence.
 - **Không fake-pass** — product-gap giữ nguyên FAIL, đẩy về PO/Dev.
+- **Chạy lại để QUAN SÁT, không để cho qua** — ba nhãn FAIL tách *chưa đủ căn cứ* (`flaky`) ra khỏi *đã đủ căn cứ* (`script-bug` / `product-gap`). Trước đây hai nhãn gộp cả ba tình huống, nên một test hên xui hoặc bị gán bừa `script-bug` (giấu bug), hoặc thành một bug ma gửi cho dev.
 - **Stack QC tách hẳn dev** — `@trace.verifies` nối script ↔ SC.
 - **`active_platform` khoá sổ trace** — `qc_status` ghi đúng `{UC-ID}-{platform}.tsv`.
 - **Chủ sở hữu bước `🟡 Fixed → 🟢 Closed`.** `/report-bug` mở bug (`🟢 Open`), `/fix-bug` đặt `🟡 Fixed`, và **chỉ QC re-verify mới đóng được** — dev không tự đóng bug của mình.
@@ -80,9 +102,10 @@ Bug report đã đổi phải **commit + push** vào spec repo — file local l
 ## 👓 Góc nhìn tối ưu
 
 - **Trạm nặng nhất của QC** — sinh + chạy + phân loại + ghi trace. Chạy thật phụ thuộc môi trường (browser, data, service lên).
-- **Phân loại script-bug vs product-gap phụ thuộc AI/reviewer** — sai loại → hoặc giấu lỗi sản phẩm hoặc báo nhầm. Đáng có tiêu chí rõ.
-- **Selector phụ thuộc `/map-testids`** — nếu chưa map, script giòn.
-- **Chạy lại tốn tài nguyên** — cân nhắc scoped run như dev-run-test.
+- **Phân loại vẫn phụ thuộc người đọc evidence** — nhưng giờ có **tiêu chí và thứ tự bắt buộc**: chạy lại ×2 → đọc trace/log → đề xuất nhãn → **người xác nhận**. Chỗ mềm còn lại là ranh giới `script-bug` ↔ `product-gap` khi hành vi nằm ở **biên của spec**; đường ra đã ghi rõ là **mời Dev cùng xem trace**, không đoán cho xong.
+- **Selector bám hợp đồng `/map-testids`** — §4.5.6 đã được chốt **trước** `/generate-code`, nên trạm này có bảng selector sẵn. Ca còn lại: §4.5.6 rỗng (dự án cũ chưa từng chạy `/map-testids`) → script quay về dò DOM và **giòn**.
+- **Chạy lại tốn tài nguyên** — ×2 cho mỗi FAIL là chi phí thật. Đánh đổi có chủ đích: rẻ hơn nhiều so với một bug ma gửi cho dev, hoặc một defect thật bị gán `script-bug` rồi chôn.
+- **`flaky` không có cột riêng trong sổ trace** — nó nằm ở `qc_status = not_run` + `qc_owner = qc` + nghi vấn ghi trong report. Cố ý: thêm một giá trị enum mới sẽ kéo theo sửa schema, lint, mọi lệnh đọc cột đó — trong khi `not_run` đã đúng nghĩa *chưa có kết luận*. Cái giá là **không truy được lịch sử flaky bằng máy**, phải đọc report.
 
 ---
 

package/docs/explain/20-qc-report.md

@@ -30,8 +30,11 @@ Kết quả chạy cần được trình bày có bằng chứng và **định t
 
 1. **Role qa-runner/report** — nạp skill report.
 2. **Procedure** — tổng hợp kết quả run (pass/fail per SC), đính evidence.
-3. Tách **product-gap** → định tuyến về PO/Dev (có thể thành `/report-bug`).
-4. **Output** report.
+3. Tách **product-gap** → định tuyến về PO/Dev (có thể thành `/report-bug`). Scenario mang nhãn **`flaky`** **không** thành bug — nó là *chưa có kết luận*, `qc_status` để `not_run`.
+4. **Self-Review** *(mới)* — nạp `skills/qc/_shared/self-review-principles.md`, soát một lượt trước khi in report.
+5. **Output** report.
+> **Self-Review ≠ Guard.** Guard là phép **đếm cơ học**, có hệ quả bắt buộc khi lệch. Self-review là lượt đọc lại **rộng hơn nhưng mềm hơn**, soát ba nhóm lỗi mà phép đếm không bắt được (bịa dữ kiện · lẫn suy đoán với sự thật · bỏ dở giữa chừng). Một bộ nguyên tắc tự soát **không bao giờ** được dùng làm lý do gỡ một Guard — chính file `self-review-principles.md` ghi rõ ranh giới đó ngay ở đầu.
+
 
 ---
 

package/docs/explain/README.md

@@ -98,12 +98,15 @@ Kết thúc bằng: **Status badge** (✅/❌/⚠️) · **Output Artifacts** (f
 - [05 · `/generate-design-spec`](05-generate-design-spec.md)
 - [06 · `/generate-bdd`](06-generate-bdd.md)
 - [07 · `/generate-tech-docs`](07-generate-tech-docs.md)
+- [**11** · `/map-testids`](11-map-testids.md) ← **chốt hợp đồng test-id, TRƯỚC code**
 - [08 · `/review-tech-docs`](08-review-tech-docs.md)
 
+> Danh sách này xếp theo **thứ tự chạy**, không theo số file. `/map-testids` giữ số `11` vì lý do lịch sử — giữ tên file để không gãy link cũ.
+> §4.5.6 chốt ở đây là lý do **Phase Implementation** và **Phase QC Automation** chạy được **song song**.
+
 ### Phase Implementation
 - [09 · `/generate-code`](09-generate-code.md)
 - [10 · `/review-code`](10-review-code.md)
-- [11 · `/map-testids`](11-map-testids.md)
 
 ### Phase Dev Self-Test
 - [12 · `/dev-gen-test`](12-dev-gen-test.md)