@educa-corp/sdd-framework 0.4.2 → 0.6.0

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

@@ -1,67 +1,87 @@
-[← /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` + selector (từ `/map-testids`).
-
-**Output:** script Python + kết quả + cột `qc_status` trong `.trace/…/{UC-ID}-{platform}.tsv` + Panel Mirror.
-
----
-
-## 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).
-6. **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`.
-
----
-
-## 👓 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`.
+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,68 +1,75 @@
-[← /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`; làm mới Living Docs dashboard.
-
----
-
-## 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").
-
----
-
-## 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:** `--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.

package/docs/explain/23-fix-bug.md

@@ -33,9 +33,25 @@ Sửa bug ad-hoc dễ tái phát và mất truy vết. Command áp một quy tr
 2. **Phase 2 · Root Cause Analysis** — truy nguyên nhân gốc (không vá triệu chứng).
 3. **Phase 3 · Fix** — sửa; tag `@trace.fixes` / `@trace.root_cause` / `@trace.regression`.
 4. **Phase 4 · Regression Test** — thêm test tái hiện bug để chống tái phát.
-5. **Phase 5 · Build & Commit** — build verify; umbrella **push 2 tầng** (Tầng 1: fix branch trong service submodule nơi code sống; Tầng 2: umbrella pointer).
-6. **Phase 5.5 · Đóng bug report** — nếu fix một `{BUG-ID}` đã file → cập nhật trạng thái.
-7. **Phase 6 · Đề xuất Lesson** — nếu lỗi tái diễn → `capture-lesson` (L1–L5).
+5. **Phase 4.5 · Cập nhật sổ trace** — regression test phải hiện lên coverage (xem dưới).
+6. **Phase 5 · Build & Commit** — build verify; umbrella **push 2 tầng** (Tầng 1: fix branch trong service submodule nơi code sống; Tầng 2: umbrella pointer).
+7. **Phase 5.5 · Đặt `🟡 Fixed`** — nếu fix một `{BUG-ID}` đã file. **Không** đặt `Closed` — bước đó thuộc `/qc-run-test`.
+8. **Phase 6 · Đề xuất Lesson** — nếu lỗi tái diễn → `capture-lesson` (L1–L5).
+
+### Phase 4.5 — vì sao `/fix-bug` phải ghi sổ trace
+
+Đây từng là lệnh **duy nhất** sinh test mà không ghi `.tsv`. Hệ quả: `test_count` under-report vĩnh viễn → SC đứng `GAP` dù vừa có regression test → `/validate-traces` khuyên `/dev-gen-test` → dev sinh test **trùng**. Và `dev_selftest` giữ `pass` **cũ trên code đã đổi**.
+
+| Cột | Ghi gì |
+|---|---|
+| `test_count` | **+=** số test regression (cộng dồn, không ghi đè) |
+| `test_classes` | **append** tên class mới, giữ tên cũ |
+| `dev_selftest` → `not_run` · `dev_selftest_at` → `—` | code vừa đổi nên tín hiệu self-test cũ hết hiệu lực |
+| `last_updated` | hôm nay |
+
+**Hai nhóm cột cấm đụng:** `qc_*` (QC sở hữu — `/qc-run-test` flip khi re-verify **và** chính nó đóng bug) · `spec_ver`/`gen_ver` (**fix bug không đổi spec** — đụng vào là tạo `DRIFT` giả).
+
+Vì `dev_selftest` bị reset, Next của lệnh là **`/dev-run-test`** để lấy lại tín hiệu xanh, rồi mới tạo PR.
 
 ---
 

package/docs/explain/26-propose-scenario.md

@@ -1,63 +1,70 @@
-[← /report-bug](25-report-bug.md) · [Explain Home](README.md) · [Next: /learn →](27-learn.md)
-
-# 26 · `/propose-scenario` — Đề xuất BDD scenario mới (cho Tester & QC)
-
-> **Một câu.** Tester đề xuất một scenario còn thiếu; command quyết đây là **scenario mới** (draft) hay **thay đổi PRD** (change request), rồi ghi proposal để PO/Dev duyệt.
-
----
-
-## Vấn đề giải quyết
-
-Tester thấy coverage thủng nhưng không được sửa spec trực tiếp. Command cho họ kênh **đề xuất có hồ sơ**: nếu là scenario mới trong scope → draft; nếu chạm yêu cầu nghiệp vụ → PRD change request.
-
----
-
-## Vị trí & tiền đề
-
-- **Vị trí:** xuyên suốt (kênh feedback tester/QC).
-
----
-
-## Input / Output
-
-**Input:** UC + platform + mô tả scenario thiếu.
-
-**Output:** `{bdd_proposals_dir}/…` (Case A: scenario draft) hoặc PRD change request (Case B).
-
----
-
-## Các bước xử lý (chi tiết)
-
-1. **Step 1 · Phân giải UC + Platform.**
-2. **Step 2 · Quyết định Coverage (CRITICAL)** — phân loại:
-   - **Case A** — scenario mới **trong scope** UC hiện tại → draft scenario.
-   - **Case B** — đòi hỏi **thay đổi yêu cầu nghiệp vụ** → **PRD Change Request** (không tự draft, đẩy về PO).
-3. **Step 3 · Draft Scenario** (chỉ Case A) — viết Gherkin đề xuất.
-4. **Step 4 · Ghi Proposal.**
-5. **Step 5 · Handoff** — để PO/Dev thấy; `/generate-bdd` có thể incorporate proposal `accepted`.
-
----
-
-## Checkpoint & Gate
-
-- Không gate — đề xuất, PO/Dev quyết.
-
----
-
-## Cơ chế đặc biệt
-
-- **Phân biệt scenario-gap vs PRD-change** — giữ ranh giới ai được đổi gì (tester không tự đổi yêu cầu nghiệp vụ).
-- **Proposal `accepted` chảy ngược vào `/generate-bdd`** — khép vòng.
-
----
-
-## 👓 Góc nhìn tối ưu
-
-- **Quyết định Case A/B là điểm phán đoán** — sai hướng thì hoặc phình scope BDD hoặc bỏ sót đổi PRD. Tiêu chí rõ quan trọng.
-- **Nối với `/generate-bdd` incorporate** phụ thuộc trạng thái `accepted` được cập nhật — quy trình duyệt cần rõ.
-
----
-
-## Kết nối
-
-**Trước:** tester thấy coverage thiếu · **Sau:** PO/Dev review proposal; Case A accepted → [`/generate-bdd`](06-generate-bdd.md); Case B → [`/refine-prd`](03-refine-prd.md)/PRD.
+[← /report-bug](25-report-bug.md) · [Explain Home](README.md) · [Next: /learn →](27-learn.md)
+
+# 26 · `/propose-scenario` — Đề xuất BDD scenario mới (cho Tester & QC)
+
+> **Một câu.** Tester đề xuất một scenario còn thiếu; command quyết đây là **scenario mới** (draft) hay **thay đổi PRD** (change request), rồi ghi proposal để PO/Dev duyệt.
+
+---
+
+## Vấn đề giải quyết
+
+Tester thấy coverage thủng nhưng không được sửa spec trực tiếp. Command cho họ kênh **đề xuất có hồ sơ**: nếu là scenario mới trong scope → draft; nếu chạm yêu cầu nghiệp vụ → PRD change request.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** xuyên suốt (kênh feedback tester/QC).
+
+---
+
+## Input / Output
+
+**Input:** UC + platform + mô tả scenario thiếu.
+
+**Output:** `{bdd_proposals_dir}/…` (Case A: scenario draft) hoặc PRD change request (Case B).
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Step 1 · Phân giải UC + Platform.**
+2. **Step 2 · Quyết định Coverage (CRITICAL)** — phân loại:
+   - **Case A** — scenario mới **trong scope** UC hiện tại → draft scenario.
+   - **Case B** — đòi hỏi **thay đổi yêu cầu nghiệp vụ** → **PRD Change Request** (không tự draft, đẩy về PO).
+3. **Step 3 · Draft Scenario** (chỉ Case A) — viết Gherkin đề xuất.
+4. **Step 4 · Ghi Proposal.**
+5. **Step 5 · Handoff** — để PO/Dev thấy; `/generate-bdd` có thể incorporate proposal `accepted`.
+
+---
+
+## Checkpoint & Gate
+
+- Không gate — đề xuất, PO/Dev quyết.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Phân biệt scenario-gap vs PRD-change** — giữ ranh giới ai được đổi gì (tester không tự đổi yêu cầu nghiệp vụ).
+- **Proposal `accepted` chảy ngược vào `/generate-bdd`** — khép vòng.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Quyết định Case A/B là điểm phán đoán** — sai hướng thì hoặc phình scope BDD hoặc bỏ sót đổi PRD. Tiêu chí rõ quan trọng.
+- **Nối với `/generate-bdd` incorporate** phụ thuộc trạng thái `accepted` được cập nhật — quy trình duyệt cần rõ.
+
+---
+
+## Kết nối
+
+**Trước:** tester thấy coverage thiếu · **Sau:** PO/Dev review proposal.
+
+| Case | Đi đâu | Ai lấy ra |
+|---|---|---|
+| **A** — thiếu scenario cho AC đã có | `feedback/bdd-proposals/` | [`/generate-bdd`](06-generate-bdd.md) quét thư mục **mỗi lần chạy**, chèn khi `Status: accepted` |
+| **B** — requirement MỚI | `feedback/prd-change-requests/` | [`/extend-prd`](02b-extend-prd.md) — **không** phải `/refine-prd` (lệnh đó không thêm được AC mới) |
+
+> Case B **không tự vào BDD được**: scenario chưa có AC để trace tới. Nó chỉ xuất hiện sau khi PO đưa requirement vào PRD rồi chạy lại `/generate-bdd`. Và vì chưa có AC, **không cờ trace nào bắt được** thiếu sót này — theo mọi thước đo coverage thì hành vi đó *không tồn tại*. Đó là lý do [`/validate-traces`](21-validate-traces.md) Step 7b phải đếm và nhắc lại kèm số ngày chờ.

package/docs/explain/27-learn.md

@@ -46,17 +46,19 @@
 
 ## Cơ chế đặc biệt
 
-- **Lesson là ràng buộc cứng** — context-loader Bước 6.7 nạp mọi lesson khớp `category`+`scope`; output vi phạm → AI sửa trước khi trình + ghi `L-NNN` đã áp.
+- **Lesson là ràng buộc cứng** — context-loader Bước 6.7 nạp lesson `Status: active` có `category` khớp lệnh (+ `general`); output vi phạm → AI sửa trước khi trình + ghi `L-NNN` đã áp.
 - **Dùng chung `capture-lesson`** với `/review-code`, `/fix-bug`, `/debug` — lesson sinh tự nhiên từ chỗ phát hiện.
+- **`/learn --review` — đường RA** *(từ v0.5.1, GAPS-v3 G46)*. Retire = đổi `Status` + ghi lý do, **không xoá** (lesson retired ở lại làm lịch sử). Tiêu chí 🔴 **kiểm được bằng máy**: `Scope` là file glob mà glob không còn khớp file nào ⇒ code lesson canh đã không tồn tại. `Scope` là `all`/domain thì không tự kiểm được — chỉ liệt kê theo tuổi để người quyết.
 
 ---
 
 ## 👓 Góc nhìn tối ưu
 
 - **Bộ nhớ dự án cốt lõi** — nhưng phụ thuộc con người chủ động `/learn`. Lesson không ghi = không nhớ.
-- **Dedup L3 phụ thuộc AI so khớp** — lesson gần giống có thể lọt thành trùng, phình file → tốn context mọi lệnh.
+- **Dedup L3 phụ thuộc AI so khớp** — lesson gần giống có thể lọt thành trùng.
 - **Scope/category filtering** quyết định lesson nào nạp — nếu gắn sai, guardrail không kích hoạt đúng lúc.
-- **Không có cơ chế "retire" lesson lỗi thời** — file chỉ lớn dần. Đáng cân nhắc vòng đời lesson.
+- ~~**Không có cơ chế "retire" lesson lỗi thời** — file chỉ lớn dần.~~ ✅ **Đã có từ v0.5.1** (`/learn --review`). *Ghi chú này từng đứng ở đây trước khi GAPS-v3 rà tới — nó đã đúng, chỉ chưa ai làm.*
+- **Vẫn phụ thuộc con người chạy `--review`** — không gì tự retire. Cố ý: tự bỏ một guardrail trong im lặng là đúng thứ framework này tồn tại để chống. Recap cảnh báo khi ≥40 lesson active.
 
 ---