@educa-corp/sdd-framework 0.6.0 → 0.7.1

package/docs/explain/02c-amend-prd.md

@@ -0,0 +1,152 @@
+[← /extend-prd](02b-extend-prd.md) · [Explain Home](README.md) · [Next: /refine-prd →](03-refine-prd.md)
+
+# 02c · `/amend-prd` — Đổi một yêu cầu đã duyệt
+
+> **Một câu.** Sửa **tại chỗ** nội dung của một AC/BR/UC đã duyệt — PO khai tường minh ID, lệnh kiểm va chạm, ghi bằng `Edit` với guard **hai chiều**, bump version + `Status → draft`, và nói rõ UC nào phải làm lại.
+
+---
+
+## Vấn đề giải quyết
+
+Có bốn tình huống PO chạm PRD. Trước GAPS-v4 G54 chỉ ba cái có lệnh.
+
+| Tình huống | Lệnh | Có từ |
+|---|---|---|
+| PRD chưa có | `/generate-prd` | đầu |
+| **Thêm** UC/AC/BR mới | `/extend-prd` | v0.4.3 |
+| Sửa vấn đề **review chỉ ra** | `/refine-prd` | đầu |
+| **Đổi một yêu cầu đang đúng cú pháp** | *(không có)* | — |
+
+Nhánh thứ tư là *"BR8 nói tối đa 5 file, giờ đổi thành 20"*. Không thêm gì mới. Không phải AI phát hiện lỗi. Chỉ đổi một con số đã duyệt.
+
+Ba lệnh có sẵn đều **từ chối đúng việc đó**:
+
+| Lệnh | Vì sao không dùng được |
+|---|---|
+| `/generate-prd` | **DỪNG HẲN** — §Guard *"Tồn tại → DỪNG. KHÔNG ghi, KHÔNG hỏi Y/N"*. Đúng vậy: ghi đè mất changelog và **đánh số lại BR** ⇒ phá `@trace.business_rules` trong mọi `.feature` đã sinh, cả ba đều không hoàn tác được từ trong lệnh |
+| `/extend-prd` | **Add-only.** Bước 5 §3 đòi output là *"superset chặt"* của bản cũ. Có **một** cửa sửa nội dung cũ (Bước 3.2 case 1, "mâu thuẫn rule") nhưng nó **phái sinh** — chỉ mở khi phần THÊM làm BR cũ sai |
+| `/refine-prd` | Resume Mode Phase 2 tự cấm đụng section nào không được một finding trỏ tới, và findings sinh từ việc soi PRD hiện có ⇒ **không có đường nào để một ý định MỚI của PO đi vào** |
+
+Nên hành vi hợp lý duy nhất còn lại là **mở file `.md` ra gõ**.
+
+---
+
+## Vì sao nhánh thiếu này nặng hơn nó trông (GAPS-v4 G54)
+
+Toàn bộ lưới an toàn của framework so **nhãn version**, không so **nội dung**. Kiểm bằng máy: `grep "content_hash|checksum|sha256|md5"` trên toàn bộ lệnh + schema + step → **0 kết quả**.
+
+Nên khi PO sửa tay: bìa không đổi, trang changelog trắng, con dấu `approved` vẫn còn.
+
+| Tầng canh | Nó hỏi gì | Trả lời | Kết quả |
+|---|---|---|---|
+| `/validate-traces` Step 4 | *"PRD Version == cột `prd_version`?"* | `1.3 == 1.3` | ✅ sạch |
+| `gate-trace` G2 | *"report khớp sổ TSV?"* | khớp | ✅ PASS |
+| `require-fresh-audit` | *"PR có chạm file mang tag trace?"* | PO chỉ sửa `.md` | ✅ không đòi audit |
+
+**Ba tầng xanh, và ba tầng đều đúng theo định nghĩa của chính chúng.** Code vẫn chặn ở 5, test vẫn assert 5 và vẫn PASS — nó đang test đúng code, chỉ là code sai spec. Dashboard hiện `OK · ✅ 10 tests · qc pass`.
+
+So với hai họ hàng gần:
+
+| | Hỏng kiểu gì | Có gì để phát hiện? |
+|---|---|---|
+| G52 | **Ồn** — báo oan cho mọi UC | Có, quá nhiều |
+| G53 | **Im lặng** — nhưng version vẫn lệch, vẫn còn cờ ⓘ để người tinh ý thấy | Có, một chút |
+| **G54** | **Im lặng tuyệt đối** | **Không có gì** |
+
+Và đây là nhánh **dùng nhiều nhất**: trên một sản phẩm đang sống, *"đổi một yêu cầu đã có"* xảy ra thường hơn *"thêm một UC hoàn toàn mới"* rất nhiều.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Specification — nhánh *"PRD đã tồn tại, đổi nội dung"*.
+- **Tiền đề:** có PRD. Không có → `/generate-prd`.
+- **Mức chặn:** **CỨNG** (`--yes` không bỏ qua được). Đây là thao tác ghi **duy nhất** trong framework được phép làm output **không phải superset** của bản cũ.
+
+---
+
+## Nó làm gì, theo thứ tự
+
+| Bước | Làm gì | Điểm đáng chú ý |
+|---|---|---|
+| **1** | Nạp PRD + **PO khai tường minh `amend_targets`** | Trình danh sách UC/BR/AC để PO chọn. **Không tự suy** target từ mô tả mơ hồ — đoán sai là sửa sai một yêu cầu đã duyệt. Mỗi ID được phân giải về **UC sở hữu** ngay |
+| **2** | **Kiểm va chạm** (3 câu) | Tái dùng `/extend-prd` Bước 3.2, **đảo hướng**: ở đó là *"phần THÊM có làm cái cũ sai không"*, ở đây là *"cái SỬA có làm phần còn lại sai không"*. Mỗi "có" **mở rộng `amend_targets`** |
+| **3** | Altitude | Cơ chế xuống BR/BL, AC chỉ giữ outcome + ref. Đây là chỗ dễ trôi nhất khi sửa tại chỗ |
+| **4** | Ghi + **guard sau-ghi HAI CHIỀU** | Xem dưới — đây là phần cốt lõi |
+| **5** | Bump version + `{changelog_scope}` + `Status → draft` | Đổi một giới hạn nghiệp vụ là **major**: code hiện tại đang sai so với spec mới |
+| **6** | Report | Nêu **UC PHẢI làm lại** kèm lệnh, và **cấm tường minh** `--realign` cho chúng |
+
+### Guard hai chiều — chỗ lệnh này khác mọi thao tác ghi khác
+
+`/extend-prd` guard bằng *"output là **superset chặt**"*. Ở đây output **cố ý không** phải superset, nên guard phải đảo:
+
+| Chiều | Kiểm gì | Fail nghĩa là |
+|---|---|---|
+| **Bảo toàn** | Mọi UC/BR/AC-ID + row changelog cũ **vẫn còn** | Đã xoá thứ không được xoá |
+| **Giới hạn** | **Mọi** nội dung đã đổi đều thuộc một ID trong `amend_targets` | Đã sửa **lan ra ngoài** phạm vi PO chốt |
+
+Chiều **Giới hạn** quan trọng bằng chiều Bảo toàn, và vì một lý do cụ thể: `{changelog_scope}` dựng từ `amend_targets`. Nếu bản ghi lỡ sửa một UC không có trong danh sách đó thì changelog **không nêu** UC ấy ⇒ `/validate-traces` xếp nó vào ⓘ `PRD_STALE_REF` ⇒ `--realign-prd-version` **mở cửa** và dán nhãn version lại lên một thay đổi chưa ai implement. Đúng hình dạng **G53**, chỉ đến từ một hướng khác.
+
+Fail chiều nào → **khôi phục file**, dừng, **không** sang Bước 5.
+
+---
+
+## Hai chế độ, và những gì nó **không** làm
+
+| Chế độ | Cờ | Làm gì |
+|---|---|---|
+| Sửa nội dung | *(mặc định)* | Đổi nội dung của ID đã có. ID giữ nguyên |
+| **Khai tử tại chỗ** | `--retire {ID}` | Đánh dấu ID không còn hiệu lực **nhưng GIỮ NGUYÊN row + ID** |
+
+`--retire` tồn tại vì **xoá hẳn một BR là bẫy**: `@trace.business_rules` trong mọi `.feature` đã sinh đang trỏ vào ID đó, nên xoá row biến một liên kết hợp lệ thành `TRACE_ORPHAN` 🔴. Khai tử tại chỗ đạt cùng mục đích nghiệp vụ mà không phá liên kết.
+
+| PO muốn | Lệnh đúng |
+|---|---|
+| Thêm UC/AC/BR mới | `/extend-prd` — lệnh này **không đánh số mới** bao giờ |
+| **Xoá hẳn** một dòng | *(không có, có chủ ý)* → `--retire` |
+| Sửa lỗi `/refine-prd` vừa chỉ ra | `/refine-prd --resume` |
+
+---
+
+## Cửa sau vẫn có chuông
+
+Mở cửa chính không có nghĩa không ai đi cửa sau. `/validate-traces` **Step 3.9** canh:
+
+- Đọc mốc `spec_baseline` (`prd_path` · `sha_at_audit` · `version_at_audit`) mà lần audit trước đã ghi.
+- So bằng **hai nguồn**: `git diff` (sửa đã commit) **và** `git status` (sửa **chưa** commit — ca thường gặp nhất, vì PO đang gõ).
+- Nội dung đổi **mà** `Version` không đổi → 🔴 **`PRD_UNTRACKED_EDIT`**.
+
+**Không báo oan:** sửa **và** bump version ⇒ `version != version_at_audit` ⇒ im.
+
+**Đường ra tự lành, cố ý không có `--accept-edit`:** cách sửa đúng là bump version + ghi row changelog nêu UC — tức đúng việc lệnh này làm hộ. Làm xong thì cờ tự tắt và logic `PRD_DRIFT` bình thường tiếp quản. Thêm một cờ escape sẽ là thêm một đường **dán nhãn lên thay đổi chưa ai xem**, đúng cái ba rào của `--realign` tồn tại để chặn.
+
+**Vì sao cờ này không chặn PR:** `gate.blocking` nghĩa hẹp là *code đang hỏng*; cờ này nói về *spec*. Thêm nữa, mọi project đang chạy đều đã có PRD sửa tay ⇒ một cờ chặn mới sẽ đỏ khắp nơi ở lần đầu ⇒ người ta **tắt cổng** ⇒ mất luôn 4 cờ 🔴 thật. Đó đúng là thất bại mà `self-check` R9(e) được viết ra để chặn, chỉ đến bằng một cửa khác. Team đã dọn sạch nợ tồn thì tự thêm counter vào `gate.blocking`; R13(e) canh việc đó có kèm `why`.
+
+---
+
+## Sau đó chạy gì
+
+```
+/amend-prd {prd-file} UC3-BR8
+  → /review-context {prd-file}      ← kiểm chất lượng phần vừa sửa
+  → PO đặt Status: approved
+  → /generate-bdd {prd-file}        ← CHỈ cho UC bị sửa
+  → /generate-code {UC-ID}
+  → /dev-gen-test → /dev-run-test   ← test cũ đang assert giá trị cũ và vẫn PASS
+```
+
+❌ **Không** `--realign-prd-version` cho UC bị sửa — nội dung đổi thật.
+
+---
+
+## Máy canh gì
+
+| Rule | Canh gì |
+|---|---|
+| `self-check` **R11** | Lệnh phải tự khai mức `chặn CỨNG`, khớp `gate.checkpoint_levels.hard` |
+| `self-check` **R12** | Là producer dòng changelog → phải có **dòng template** mang `{changelog_scope}` |
+| `self-check` **R13** | `spec_baseline` phải được **GHI** như một key trong `trace-report.json` — nếu không, cờ `PRD_UNTRACKED_EDIT` không bao giờ bật mà R6/R7 vẫn ✅ |
+
+---
+
+[← /extend-prd](02b-extend-prd.md) · [Explain Home](README.md) · [Next: /refine-prd →](03-refine-prd.md)

package/docs/explain/06-generate-bdd.md

@@ -2,7 +2,7 @@
 
 # 06 · `/generate-bdd` — Sinh kịch bản BDD (.feature)
 
-> **Một câu.** Phân rã PRD thành các file `.feature` (Gherkin) mang `@trace.*`, theo platform (web/app/system), với fan-out per-UC và tổng hợp **System BDD** từ BDD FE/App.
+> **Một câu.** Phân rã PRD thành các file `.feature` (Gherkin) mang `@trace.*`, theo platform (web/app/webview/system), với fan-out per-UC và tổng hợp **System BDD** từ BDD FE/App.
 
 ---
 

package/docs/explain/13-dev-run-test.md

@@ -37,7 +37,21 @@ Sinh test chưa đủ — phải chạy và biết pass/fail. Command chạy tes
    | web-frontend | Vitest / Jest; E2E Playwright / Cypress |
    | mobile | Flutter test, React Native, iOS (xcodebuild), Android |
 3. **Analyze Failures** — chẩn lỗi theo platform (điều gì fail, tại sao).
-4. **Write Trace State** — set `dev_selftest` (pass/fail) trong `.tsv`.
+4. **Write Trace State** — **ĐỌC cột `status` của row TRƯỚC KHI GHI**, rồi set `dev_selftest`:
+
+   | `status` của row | Ghi gì |
+   |---|---|
+   | `OK` · `GAP` · `UNTRACKED` | `pass` / `fail` như thường |
+   | **`DRIFT`** | test **pass** → **`not_run`** *(KHÔNG ghi `pass`)* · test **fail** → **`fail`** như thường |
+   | **`ORPHANED`** | **`not_run`** — scenario đã bị xoá khỏi `.feature` |
+
+   > **Vì sao (GAPS-v4 G55).** `pass` **không** mang nghĩa *"test đã chạy và xanh"* — nó mang nghĩa *"scenario này đã được nghiệm thu theo spec **hiện tại**"*. Trên row `DRIFT` nghĩa thứ nhất đúng và nghĩa thứ hai **sai**.
+   >
+   > Bản cũ ghi `pass` chỉ dựa vào *test có xanh không*, nên chuỗi này báo xanh sai: PO đổi AC → `/generate-bdd` đặt `status = DRIFT` và **hạ** `dev_selftest → not_run` → sáng sau dev chạy lệnh này theo thói quen (chưa `/generate-code`, chưa `/dev-gen-test`) → test cũ + code cũ xanh hết → ghi `pass` **kèm ngày hôm nay**. Tức lệnh kế tiếp trong vòng lặp dev bình thường **dựng lại** đúng tín hiệu vừa bị hạ.
+   >
+   > **Tin xấu luôn hợp lệ:** đây là guard cho lời khẳng định **DƯƠNG**, không phải lệnh *"bỏ qua kết quả khi DRIFT"*. `fail` vẫn được ghi — chặn cả `fail` là biến guard chống-báo-cáo-sai thành guard **che tin xấu**.
+   >
+   > **Tầng thứ hai độc lập:** `lint-trace` **T12** bắt trạng thái này ở sổ thật (`status ∈ {DRIFT, ORPHANED}` mà `dev_selftest`/`qc_status = pass`), bất kể lệnh nào ghi ra — kể cả sổ sửa tay hoặc sổ sinh bởi version framework cũ.
 5. **Refresh Panel Mirror** — Living Docs local (umbrella).
 
 ---

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

@@ -1,87 +1,91 @@
-[← /qc-review](18-qc-review.md) · [Explain Home](README.md) · [Next: /qc-report →](20-qc-report.md)
-
-# 19 · `/qc-run-test` — Trạm 5: Sinh & chạy Playwright, ghi `qc_status`
-
-> **Một câu.** Biến `.Test.md` đã review thành **Python pytest-playwright**, chạy thật, rồi ghi **`qc_status` chính thức** (có evidence) vào trace TSV.
-
----
-
-## Vấn đề giải quyết
-
-Đây là nơi QC trở thành **chính thức**: chạy test thật trên Playwright, phân loại FAIL (script-bug vs product-gap, **không fake-pass**), và đóng dấu `qc_status` — trạng thái QC authoritative.
-
----
-
-## Vị trí & tiền đề
-
-- **Vị trí:** Phase QC (trạm 5), sau `/qc-review` (case APPROVED).
-- **Stack:** module `qc-playwright` (Python + pytest-playwright + Page Object) — **độc lập** module dev.
-
----
-
-## Input / Output
-
-**Input:** `.Test.md` đã review + skill `qa-runner` + bảng Test Selectors §4.5.6 (**giá trị** test-id, từ `/map-testids`) + **`@trace.testid_attr`** ở header tech-doc (**tên thuộc tính** chứa chúng).
-
-**Output:** script Python + kết quả + cột `qc_status` trong `.trace/…/{UC-ID}-{platform}.tsv` + panel mirror (`.trace-mirror/`).
-
-> **`@trace.testid_attr` — đọc, KHÔNG suy từ platform.** §4.5.6 cho **giá trị** test-id; field này cho **tên thuộc tính** chứa chúng. `get_by_test_id()` của Playwright mặc định dò `data-testid` **nhưng cấu hình được** — dự án dùng `data-test`/`data-qa` thì phải `set_test_id_attribute("{attr}")` trước, không thì **trượt 100% locator**.
->
-> Suy từ platform là **phát biểu lại một sự thật đã ghi ở nơi khác** (`/map-testids` đã phân giải một lần cho cả feature, `/generate-code` đọc chính field đó để emit). Và nó hỏng **im lặng theo kiểu tệ nhất**: test fail `element not found` — trông y hệt một bug sản phẩm, nên QC đi mở bug thay vì sửa selector. Thiếu field → **cảnh báo mềm nêu rõ rủi ro** rồi mới fallback.
-
----
-
-## Các bước xử lý (chi tiết)
-
-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**).
-5. **Write Trace State — `qc_status`** (kết quả QC chính thức) + `qc_run_at`, `qc_owner`, `qc_blocked_by`, `last_updated`.
-6. **Đóng bug đã verify** — chạy **TRƯỚC** bước clear cột (xem dưới).
-7. **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.
-
----
-
-## Cơ chế đặc biệt
-
-- **`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.
-- **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.
-
-### Vì sao đóng bug phải chạy TRƯỚC khi clear cột
-
-Khi `qc_status` flip `pass`, lệnh clear `qc_owner`/`qc_blocked_by` về `—`. Nhưng `qc_blocked_by` **chính là con trỏ tới `{BUG-ID}`** — clear xong là mất đường về, và đối chiếu tay cũng không làm được. Nên thứ tự bắt buộc: **đọc `qc_blocked_by` → đóng bug → rồi mới clear**.
-
-| `State` của bug | SC vừa `pass` → làm gì |
-|---|---|
-| `🟡 Fixed` | → `🟢 Closed` + dòng `Verified: /qc-run-test {today} — {UC-ID}-SC{N} pass` |
-| `🟢 Open` (chưa ai fix) | **KHÔNG đóng.** Giữ `Open` + ghi chú kiểm tra lại test |
-| `GAP-*` thay vì `BUG-*` | không đụng — spec-gap thuộc PO, không phải QC |
-
-> Ca `Open` là ngoại lệ **có chủ đích**: test pass trên một bug chưa ai fix là dấu hiệu **test sai**, không phải bug hết. Tự đóng ở đây sẽ **chôn một defect thật**.
-
-Bug report đã đổi phải **commit + push** vào spec repo — file local là dead drop, PO/Dev chỉ thấy sau khi push.
-
----
-
-## 👓 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.
-
----
-
-## Kết nối
-
-**Trước:** [`/qc-review`](18-qc-review.md) (case) · **Sau:** [`/qc-report`](20-qc-report.md) rồi [`/qc-review`](18-qc-review.md) (script).
+[← /qc-review](18-qc-review.md) · [Explain Home](README.md) · [Next: /qc-report →](20-qc-report.md)
+
+# 19 · `/qc-run-test` — Trạm 5: Sinh & chạy Playwright, ghi `qc_status`
+
+> **Một câu.** Biến `.Test.md` đã review thành **Python pytest-playwright**, chạy thật, rồi ghi **`qc_status` chính thức** (có evidence) vào trace TSV.
+
+---
+
+## Vấn đề giải quyết
+
+Đây là nơi QC trở thành **chính thức**: chạy test thật trên Playwright, phân loại FAIL (script-bug vs product-gap, **không fake-pass**), và đóng dấu `qc_status` — trạng thái QC authoritative.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase QC (trạm 5), sau `/qc-review` (case APPROVED).
+- **Stack:** module `qc-playwright` (Python + pytest-playwright + Page Object) — **độc lập** module dev.
+
+---
+
+## Input / Output
+
+**Input:** `.Test.md` đã review + skill `qa-runner` + bảng Test Selectors §4.5.6 (**giá trị** test-id, từ `/map-testids`) + **`@trace.testid_attr`** ở header tech-doc (**tên thuộc tính** chứa chúng).
+
+**Output:** script Python + kết quả + cột `qc_status` trong `.trace/…/{UC-ID}-{platform}.tsv` + panel mirror (`.trace-mirror/`).
+
+> **`@trace.testid_attr` — đọc, KHÔNG suy từ platform.** §4.5.6 cho **giá trị** test-id; field này cho **tên thuộc tính** chứa chúng. `get_by_test_id()` của Playwright mặc định dò `data-testid` **nhưng cấu hình được** — dự án dùng `data-test`/`data-qa` thì phải `set_test_id_attribute("{attr}")` trước, không thì **trượt 100% locator**.
+>
+> Suy từ platform là **phát biểu lại một sự thật đã ghi ở nơi khác** (`/map-testids` đã phân giải một lần cho cả feature, `/generate-code` đọc chính field đó để emit). Và nó hỏng **im lặng theo kiểu tệ nhất**: test fail `element not found` — trông y hệt một bug sản phẩm, nên QC đi mở bug thay vì sửa selector. Thiếu field → **cảnh báo mềm nêu rõ rủi ro** rồi mới fallback.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+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**).
+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.
+
+---
+
+## Checkpoint & Gate
+
+- Tiền đề: case đã APPROVED ở `/qc-review`. Script sinh ra → review lại ở `/qc-review` (script) trước PR.
+
+---
+
+## Cơ chế đặc biệt
+
+- **`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.
+- **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.
+
+### Vì sao đóng bug phải chạy TRƯỚC khi clear cột
+
+Khi `qc_status` flip `pass`, lệnh clear `qc_owner`/`qc_blocked_by` về `—`. Nhưng `qc_blocked_by` **chính là con trỏ tới `{BUG-ID}`** — clear xong là mất đường về, và đối chiếu tay cũng không làm được. Nên thứ tự bắt buộc: **đọc `qc_blocked_by` → đóng bug → rồi mới clear**.
+
+| `State` của bug | SC vừa `pass` → làm gì |
+|---|---|
+| `🟡 Fixed` | → `🟢 Closed` + dòng `Verified: /qc-run-test {today} — {UC-ID}-SC{N} pass` |
+| `🟢 Open` (chưa ai fix) | **KHÔNG đóng.** Giữ `Open` + ghi chú kiểm tra lại test |
+| `GAP-*` thay vì `BUG-*` | không đụng — spec-gap thuộc PO, không phải QC |
+
+> Ca `Open` là ngoại lệ **có chủ đích**: test pass trên một bug chưa ai fix là dấu hiệu **test sai**, không phải bug hết. Tự đóng ở đây sẽ **chôn một defect thật**.
+
+Bug report đã đổi phải **commit + push** vào spec repo — file local là dead drop, PO/Dev chỉ thấy sau khi push.
+
+---
+
+## 👓 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.
+
+---
+
+## Kết nối
+
+**Trước:** [`/qc-review`](18-qc-review.md) (case) · **Sau:** [`/qc-report`](20-qc-report.md) rồi [`/qc-review`](18-qc-review.md) (script).

package/docs/explain/21-validate-traces.md

@@ -1,75 +1,79 @@
-[← /qc-report](20-qc-report.md) · [Explain Home](README.md) · [Next: /generate-spec-manifest →](22-generate-spec-manifest.md)
-
-# 21 · `/validate-traces` — Ma trận độ phủ spec ↔ code ↔ test
-
-> **Một câu.** Check **read-only** độ phủ giữa spec, code, test (gồm PRD version drift); phân loại mỗi SC và làm mới Living Docs. Không sửa gì.
-
----
-
-## Vấn đề giải quyết
-
-Traceability chỉ có giá trị khi kiểm được. Command cho bức tranh toàn cục: SC nào có code, có test, hay còn hở — để không "tưởng xong mà chưa xong".
-
----
-
-## Vị trí & tiền đề
-
-- **Vị trí:** Phase Trace Audit (xuyên suốt).
-- **Đặc biệt:** read-only — an toàn chạy bất kỳ lúc nào.
-
----
-
-## Input / Output
-
-**Input:** `.trace/…/{UC-ID}-{platform}.tsv` + spec + code + test.
-
-**Output:** ma trận coverage + `code_coverage`; `trace-report.json` (ghi đè) + **`trace-history.jsonl`** (append 1 dòng delta — **phải commit**, không regenerate được); làm mới Living Docs dashboard.
-
-**Flag:** `--realign-prd-version {UC-ID}` · `--realign-techdoc-revision {UC-ID}` — ngoại lệ có kiểm soát của "read-only": chỉ sửa **dòng `@trace.*`** trong code, **từ chối chạy** nếu UC đang `DRIFT`/`ORPHANED`.
-
----
-
-## Các bước xử lý (chi tiết)
-
-1. Quét trace `.tsv` + đối chiếu spec/code/test.
-2. 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 |
-   |---|-----------|-----------|
-   | 1 | UNTRACKED | `gen_ver == —` |
-   | 2 | DRIFT | có code + `spec_ver != gen_ver` |
-   | 3 | GAP | có code + `test_count == —/0` |
-   | 4 | OK | version khớp + có code + có test |
-3. Dựng dashboard: `dev_selftest` (DEV smoke) **và** `qc_status` (QC chính thức) hiển thị cạnh nhau — **không merge**; cột `qc_owner` + `qc_blocked_by` ("Waiting on"); và **hai trục chia nhóm**: **`by_service`** (coverage theo từng đội — cột `service`) · **`by_platform`** (coverage theo `web`/`app`/`system`).
-   > `by_platform` trả lời *"web xong bao nhiêu %, system xong bao nhiêu %"* — câu thường ngày khi làm FE và BE song song. Trước v0.5.1 không trả lời được **từ `summary`**: `by_service` là bảng chia nhóm duy nhất, mà cột `service` là `—` ở mọi row của dự án single-service ⇒ nó gộp tất cả vào một ô.
-4. **Lọc báo động oan (Step 4/5).** PRD và tech-doc là tài liệu **gộp** nhiều UC nhưng chỉ **một** số version — thêm UC7 làm mọi UC cũ lệch số dù không đổi một chữ. Đọc **scope của row changelog**: UC có trong danh sách → `PRD_DRIFT` 🟠 · không có → `PRD_STALE_REF` ⓘ (sạch bằng `--realign-*`) · row **mơ hồ** → 🟠 cho mọi UC (lưới an toàn).
-5. **Step 5d — design-spec drift** *(chỉ FE/App)*: 2 chiều, design-spec→BDD và design-spec→code.
-6. **Step 7b — hàng đợi**: đếm PRD change request còn `Open` kèm **số ngày chờ** (hàng đợi duy nhất không có lệnh nào quét lại mỗi lần chạy).
-7. **Step 8c — nhật ký**: append delta vào `trace-history.jsonl` → in khối `📈 So lần chạy trước` (đo **tốc độ**, không chỉ trạng thái).
-
----
-
-## Checkpoint & Gate
-
-- ⚪ Read-only, không gate.
-
----
-
-## Cơ chế đặc biệt
-
-- **DRIFT xét trước GAP** — code lỗi thời chưa test phải hiện DRIFT (regen) không phải GAP.
-- **`dev_selftest` ≠ `qc_status`** — hai cột riêng, không trộn.
-- **"Waiting on" column** — `qc_owner`/`qc_blocked_by` trả lời "case nào chờ ai".
-
----
-
-## 👓 Góc nhìn tối ưu
-
-- **Chỉ báo cáo, không hành động** — hành động ở `/generate-code` (regen DRIFT) & QC (bù GAP). Chuỗi phụ thuộc người chạy tiếp.
-- **Nguồn sự thật của Living Docs** — chất lượng dashboard phụ thuộc `.tsv` được các lệnh code/test ghi đúng.
-- **Là "single pane" để PM/PO nhìn trạng thái** — ứng viên tốt cho UI viewer (blueprint có gợi ý).
-
----
-
-## Kết nối
-
-**Trước:** bất kỳ (đặc biệt sau [`/qc-report`](20-qc-report.md)) · **Sau:** DRIFT/UNTRACKED → [`/generate-code`](09-generate-code.md); GAP → [`/dev-gen-test`](12-dev-gen-test.md); OK → PR.
+[← /qc-report](20-qc-report.md) · [Explain Home](README.md) · [Next: /generate-spec-manifest →](22-generate-spec-manifest.md)
+
+# 21 · `/validate-traces` — Ma trận độ phủ spec ↔ code ↔ test
+
+> **Một câu.** Check **read-only** độ phủ giữa spec, code, test (gồm PRD version drift); phân loại mỗi SC và làm mới Living Docs. Không sửa gì.
+
+---
+
+## Vấn đề giải quyết
+
+Traceability chỉ có giá trị khi kiểm được. Command cho bức tranh toàn cục: SC nào có code, có test, hay còn hở — để không "tưởng xong mà chưa xong".
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Trace Audit (xuyên suốt).
+- **Đặc biệt:** read-only — an toàn chạy bất kỳ lúc nào.
+
+---
+
+## Input / Output
+
+**Input:** `.trace/…/{UC-ID}-{platform}.tsv` + spec + code + test.
+
+**Output:** ma trận coverage + `code_coverage`; `trace-report.json` (ghi đè) + **`trace-history.jsonl`** (append 1 dòng delta — **phải commit**, không regenerate được); làm mới Living Docs dashboard.
+
+**Flag — phạm vi:** `--domain {d}` · `--prd {TICKET-ID}` · `--uc {UC-ID}`; không cờ nào = **toàn bộ**. Report mang field `scope`, và `gate-trace` **G2 fail** nếu `scope.kind !== "all"` — **không ngoại lệ**, không đếm số domain trên đĩa. Biên bản có scope **không bao giờ** là biên bản đầy đủ; muốn tạo PR thì phải có một lần audit toàn bộ đã commit. *(`/sync` Step 1e nói cho bạn biết scope là gì.)*
+
+**Flag — realign:** `--realign-prd-version {UC-ID}` · `--realign-techdoc-revision {UC-ID}` — ngoại lệ có kiểm soát của "read-only": chỉ sửa **dòng `@trace.*`** trong code, **từ chối chạy** nếu UC đang `DRIFT`/`ORPHANED` hoặc bị Step 4/5 xếp 🟠.
+
+**Cờ mới `PRD_UNTRACKED_EDIT`** 🔴 *(Step 3.9, chạy **trước** Step 4)* — nội dung PRD đổi mà nhãn `Version` **không** đổi ⇒ có người sửa ngoài `/generate-prd` · `/extend-prd` · `/amend-prd` · `/refine-prd` · `/review-context`. So bằng `git diff` **và** `git status` *(nguồn thứ hai bắt ca sửa **chưa** commit — ca thường gặp nhất)* với mốc `spec_baseline` mà Step 6b ghi. **Không chặn PR** có chủ ý, và **không có `--accept-edit`**: đường ra là bump `Version` + row changelog ⇒ cờ tự tắt.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. Quét trace `.tsv` + đối chiếu spec/code/test.
+2. 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 |
+   |---|-----------|-----------|
+   | 1 | UNTRACKED | `gen_ver == —` |
+   | 2 | DRIFT | có code + `spec_ver != gen_ver` |
+   | 3 | GAP | có code + `test_count == —/0` |
+   | 4 | OK | version khớp + có code + có test |
+3. Dựng dashboard: `dev_selftest` (DEV smoke) **và** `qc_status` (QC chính thức) hiển thị cạnh nhau — **không merge**; cột `qc_owner` + `qc_blocked_by` ("Waiting on"); và **hai trục chia nhóm**: **`by_service`** (coverage theo từng đội — cột `service`) · **`by_platform`** (coverage theo `web`/`app`/`system`).
+   > `by_platform` trả lời *"web xong bao nhiêu %, system xong bao nhiêu %"* — câu thường ngày khi làm FE và BE song song. Trước v0.5.1 không trả lời được **từ `summary`**: `by_service` là bảng chia nhóm duy nhất, mà cột `service` là `—` ở mọi row của dự án single-service ⇒ nó gộp tất cả vào một ô.
+4. **Lọc báo động oan (Step 4/5).** PRD và tech-doc là tài liệu **gộp** nhiều UC nhưng chỉ **một** số version — thêm UC7 làm mọi UC cũ lệch số dù không đổi một chữ. Đọc **scope của row changelog**: UC có trong danh sách → `PRD_DRIFT` 🟠 · không có → `PRD_STALE_REF` ⓘ (sạch bằng `--realign-*`) · row **mơ hồ** → 🟠 cho mọi UC (lưới an toàn).
+5. **Step 5d — design-spec drift** *(chỉ FE/App)*: 2 chiều, design-spec→BDD và design-spec→code.
+6. **Step 7b — hàng đợi**: đếm PRD change request còn `Open` kèm **số ngày chờ** (hàng đợi duy nhất không có lệnh nào quét lại mỗi lần chạy).
+7. **Step 8c — nhật ký**: append delta vào `trace-history.jsonl` → in khối `📈 So lần chạy trước` (đo **tốc độ**, không chỉ trạng thái).
+
+---
+
+## Checkpoint & Gate
+
+- ⚪ Read-only, không gate.
+
+---
+
+## Cơ chế đặc biệt
+
+- **DRIFT xét trước GAP** — code lỗi thời chưa test phải hiện DRIFT (regen) không phải GAP.
+- **`dev_selftest` ≠ `qc_status`** — hai cột riêng, không trộn.
+- **"Waiting on" column** — `qc_owner`/`qc_blocked_by` trả lời "case nào chờ ai".
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Chỉ báo cáo, không hành động** — hành động ở `/generate-code` (regen DRIFT) & QC (bù GAP). Chuỗi phụ thuộc người chạy tiếp.
+- **Nguồn sự thật của Living Docs** — chất lượng dashboard phụ thuộc `.tsv` được các lệnh code/test ghi đúng.
+- **Là "single pane" để PM/PO nhìn trạng thái** — ứng viên tốt cho UI viewer (blueprint có gợi ý).
+
+---
+
+## Kết nối
+
+**Trước:** bất kỳ (đặc biệt sau [`/qc-report`](20-qc-report.md)) · **Sau:** DRIFT/UNTRACKED → [`/generate-code`](09-generate-code.md); GAP → [`/dev-gen-test`](12-dev-gen-test.md); OK → PR.

package/docs/explain/28-sync.md

@@ -68,3 +68,28 @@ Umbrella nhiều submodule + một spec repo dùng chung dễ lệch nhau. `/syn
 ## Kết nối
 
 **Trước:** bất kỳ (vận hành) · **Sau:** [`/validate-traces`](21-validate-traces.md); xử lý `📥 tester feedback` nổi lên → [`/fix-bug`](23-fix-bug.md)/[`/generate-bdd`](06-generate-bdd.md).
+
+---
+
+## Step 1e — "tài liệu nào vừa đổi" *(mới, GAPS-v4 G56)*
+
+Câu hỏi số **một** của dev sau mỗi lần sync. Trước đó `/sync` **không** trả lời: nó diff đúng ba đường dẫn `feedback/*` và **bỏ qua `specs/`** — tức hỏi *"có góp ý gì mới"* rồi bỏ qua chính tài liệu mà mọi lệnh downstream đọc (PRD · BDD · tech-doc · design-spec). Range `{old_sha}..{new_sha}` đã có sẵn từ Step 1c, nên thêm nó là thêm **một tham số đường dẫn**.
+
+Step này trả lời **hai câu khác nhau**, bằng **hai mốc khác nhau**:
+
+| | Mốc | Trả lời | Vấn đề nếu chỉ có cái này |
+|---|---|---|---|
+| **1e-A** | `{old_sha}..{new_sha}` | *"đổi gì kể từ lần **PULL** trước"* | Mốc **reset mỗi lần pull**. Pull 4 ngày liền không audit → ngày thứ 5 chỉ thấy delta của **một ngày** |
+| **1e-B** | `spec_baseline.sha_at_audit` | *"đổi gì kể từ lần **AUDIT** gần nhất"* | — con số này **tích luỹ đúng** |
+
+1e-B đọc khối `spec_baseline` mà `/validate-traces` Step 6b ghi (cùng khối dùng cho cờ `PRD_UNTRACKED_EDIT` của G54). `/sync` **chỉ đọc, không bao giờ ghi** — nếu nó cũng ghi thì mốc audit trượt theo mỗi lần pull, tức phá đúng thứ 1e-B tồn tại để cung cấp. `self-check` R13 canh cả lời khai này.
+
+### Và dòng `Next` không còn là hằng số
+
+Bản cũ in cứng `/validate-traces (full coverage check) | /generate-code {UC-ID}` — **y hệt nhau** dù 0 file đổi hay 12 file đổi. Một lời nhắc không bao giờ thay đổi thì không mang thông tin nên bị lướt; cộng thêm việc lệnh duy nhất nó gợi ý là lệnh **đắt nhất** (quét cả repo), nên con đường duy nhất được chỉ là con đường người ta sẽ không đi.
+
+Giờ nó rẽ nhánh: có nợ audit → `/validate-traces {các PRD đó}` · chỉ 1e-A có đổi → `/generate-code` cho phần đó · cả hai sạch → `✅ Spec khớp audit — không cần audit lại`.
+
+> Đây là nguyên tắc `gate.md` Bước 3b đã áp cho CHECKPOINT (*"cổng luôn in ra một bảng giống hệt nhau … nên `Y` thành phản xạ và cổng hỏng âm thầm"*) — G56 là chỗ nó còn thiếu.
+>
+> **Lưu ý về bản chất:** G56 **không** phải một detector bị hỏng. Mọi detector đều đúng. Đây là một **công tắc bị thiếu** — không ai biết là cần bật.