@educa-corp/sdd-framework 0.9.1 → 0.9.3

package/docs/plans/qc-merge-plan.md

@@ -0,0 +1,502 @@
+# Kế hoạch sáp nhập dây chuyền QC vào framework
+
+> Đội QC đang chạy một dây chuyền AI automation test **7 agent / 45 skill** bên ngoài framework
+> (`D:\projects\ui-automation-testing`). Framework có **6 trạm QC / 35 skill file**.
+> Tài liệu này giải thích cả hai đang làm gì, ba chỗ chúng va nhau, và cách gộp lại.
+
+| | |
+|---|---|
+| Repo | `sdd-framework @ main` |
+| Nguồn QC | `ui-automation-testing` (`.claude/agents/3-qa-tc-analyst.md` + `.claude/skills/qa-tc-analyst/`) |
+| Trạng thái | chờ 3 quyết định (§5) |
+| Cập nhật | 2026-08-22 |
+
+**Mục lục**
+
+1. [Cốt lõi: framework cần *sổ cái*, không cần report](#1)
+2. [Framework: sáu trạm, đi theo một UC](#2)
+3. [Đội QC: bảy agent, ba lane](#3)
+4. [Ánh xạ hai bên](#4)
+5. [Ba quyết định](#5)
+6. [Món quà đi ngược chiều](#6)
+7. [Plan năm phase](#7)
+8. [Bốn lỗi tìm được khi đọc `/qc-analyze`](#8)
+
+---
+
+<a id="1"></a>
+## 1 · Cốt lõi: framework cần *sổ cái*, không cần report
+
+> Hiểu điều này trước, mọi thiết kế còn lại tự giải thích.
+
+Trước khi QC vào việc, framework đã có sẵn ba thứ do các phase trước sinh ra.
+Ví dụ thật: feature `FT-001-free-trial`, use case `FT-001-UC4` (làm survey), platform `web`.
+
+```
+specs/onboarding/free-trial/
+├── FT-001-free-trial.md              PRD — PO viết, đã approved
+├── bdd/web/FT-001-UC4.feature        Gherkin — mỗi scenario một ID:
+│                                       FT-001-UC4-SC1, SC2, SC3…
+└── tech-docs/FT-001-tech-design.md   §4.5.6 có bảng test-id
+
+.trace/onboarding/free-trial/
+└── FT-001-UC4-web.tsv                ← SỔ CÁI. 1 dòng = 1 scenario.
+```
+
+File `.tsv` đó là trái tim của framework:
+
+| sc_id | status | dev_selftest | qc_status | qc_owner | qc_blocked_by |
+|---|---|---|---|---|---|
+| FT-001-UC4-SC1 | OK | pass | `not_run` | `—` | `—` |
+| FT-001-UC4-SC2 | OK | pass | `not_run` | `—` | `—` |
+| FT-001-UC4-SC3 | DRIFT | pass | `not_run` | `—` | `—` |
+
+> **Điểm mấu chốt:** toàn bộ 6 trạm QC tồn tại để điền **ba cột `qc_*`** đó.
+> Không phải để ra report.
+
+Khác biệt giữa report và sổ cái không phải khác biệt hình thức — nó là khác biệt **cơ chế**:
+
+```
+A · DÂY CHUYỀN QC ĐỘC LẬP
+
+  spec ─► phân tích ─► test case ─► script ─► chạy ─► report.html ─┤
+                                                                    │
+                                          tài liệu chết — ai không mở thì không biết
+
+
+B · FRAMEWORK
+
+  spec ─► phân tích ─► test case ─► script ─► chạy ─GHI─► ┌──────────────┐
+                                                          │   SỔ CÁI     │
+                                                          │ .tsv         │
+                                                          │ qc_status    │
+                                                          └──┬────────┬──┘
+                                                    tín hiệu │        │
+                                                       sống  │        │
+                                            ┌───────────────◄┘        └►───────────────┐
+                                            │ dashboard PO / PM │      │ cổng chặn PR  │
+                                            └───────────────────┘      └───────────────┘
+
+  qc_status = fail  →  cổng chặn merge
+  qc_owner  = dev   →  dashboard hiện "SC này đang chờ dev"
+  qc_owner  = po    →  đang chờ PO làm rõ tài liệu
+```
+
+**Report là tài liệu chết; `qc_status` là tín hiệu sống.**
+Report nằm im chờ người mở. Sổ cái thì chặn PR, điều khiển dashboard, và nói được
+"scenario này đang chờ ai".
+
+→ Nên khi đưa dây chuyền QC vào framework, thứ framework thực sự cần từ nó **không phải**
+DOC_GAP hay TEST_PLAN — mà là: *cuối cùng có ghi được `qc_status` đúng cho từng scenario
+hay không?* Mọi thứ khác là phương tiện.
+
+---
+
+<a id="2"></a>
+## 2 · Framework: sáu trạm, đi theo một UC
+
+> Mỗi trạm là một lệnh riêng, giao việc cho trạm sau **bằng file**.
+
+```
+ TRẠM 1        TRẠM 2      TRẠM 3           TRẠM 4        TRẠM 5         TRẠM 6
+/qc-analyze ─►/qc-plan ─► /qc-design-test ─►/qc-review ─►/qc-run-test ─►/qc-report
+     │             │            │                ↑  │         │              │
+     │             │            │                └──┘         │              │
+     │             │            │       chạy 2 lần:            │              │
+     │             │            │       review test-case,      │              │
+     │             │            │       rồi review script      │              │
+     ▼             ▼            ▼                              ▼              ▼
+┌─────────────┐ ┌──────────┐ ┌────────────┐            ┌───────────┐  ┌────────────┐
+│REQUIREMENT_ │ │TEST_PLAN │ │*.Test.md   │            │tests/*.py │  │report.html │
+│ANALYSIS.md  │ │.md       │ │@trace.     │            └─────┬─────┘  │trace.zip   │
+├─────────────┤ └──────────┘ │ verifies=  │                  │        └────────────┘
+│DOC_GAPS.md  │              │ SC2        │        GHI qc_status
+└──────┬──────┘              └────────────┘                  │
+       │                                                     ▼
+       │  ┌──────────────────────────────┐         ┌──────────────────┐
+       └─►│ trạm 2 VÀ trạm 3 đều ĐỌC lại │         │  SỔ CÁI  .tsv    │
+          │ file này  ←── đây là CÂU 1    │         └──────────────────┘
+          └──────────────────────────────┘
+```
+
+**Trạm 5 còn hai đặc quyền riêng:**
+
+- **Chủ sở hữu duy nhất** của bước bug `🟡 Fixed → 🟢 Closed`.
+  `/report-bug` mở bug, `/fix-bug` đặt `Fixed`, và **chỉ QC chạy lại mới được đóng**.
+- **Guard G55 — quyền được nói "pass".**
+  SC3 test XANH, nhưng `status = DRIFT` (spec đã đổi sau khi sinh code)
+  → ghi `not_run`, **KHÔNG** ghi `pass`, **KHÔNG** đóng bug nào.
+  *Test xanh trên spec cũ không được quyền nói "đã nghiệm thu".*
+
+### Từng trạm, bằng một câu
+
+| # | Lệnh | Câu hỏi nó trả lời | Ghi ra |
+|---|---|---|---|
+| 1 | `/qc-analyze` | Yêu cầu này **là gì?** Bóc thành BR-01…, AC-01…, mỗi cái ghi rõ thuộc scenario nào. | `REQUIREMENT_ANALYSIS.md`<br>`DOC_GAPS.md` |
+| 2 | `/qc-plan` | Rủi ro **ở đâu**, phải hỏi dev gì? Risk matrix, what-if, entry/exit criteria. | `TEST_PLAN.md` |
+| 3 | `/qc-design-test` | Test case cụ thể. Markdown, chưa có code. TC bị chặn bởi gap vẫn viết, đánh dấu `🚫 Block: GAP-03`. | `test-cases/*.Test.md` |
+| 4 | `/qc-review` | Cổng. Chạy **hai lần** — lần 1 review test case, lần 2 review script Python. | verdict |
+| 5 | `/qc-run-test` | Sinh Python, chạy, **ghi sổ cái**. Trạm quan trọng nhất. | `tests/*.py` + `qc_status` |
+| 6 | `/qc-report` | Evidence + đẩy defect thật về spec (in ra lệnh `/report-bug` sẵn chạy). | `report.html`, `trace.zip` |
+
+### Sau khi trạm 5 chạy, sổ cái trông thế này
+
+| sc_id | status | qc_status | qc_owner | qc_blocked_by | Nghĩa là |
+|---|---|---|---|---|---|
+| SC1 | OK | `pass` | `—` | `—` | Xong. Nghiệm thu theo spec hiện tại. |
+| SC2 | OK | `fail` | **dev** | BUG-012 | Lỗi thật. Dashboard hiện "chờ dev". Cổng chặn PR. |
+| SC3 | DRIFT | `not_run` | `—` | `—` | Test xanh, nhưng spec đã đổi → không được quyền nói pass. |
+
+---
+
+<a id="3"></a>
+## 3 · Đội QC: bảy agent, ba lane
+
+> Cùng công việc, nhưng cắt theo một **trục khác**.
+
+```
+                                       ┌───── REJECT → sửa lại ─────┐
+                                       ▼                            │
+inputs/ ─►(1)──────────►(2)───────────►(3)──────────►(4)───────────►(5)──────►(6)──────►(7)
+       qa-io-contract  qa-orchestrator qa-tc-analyst qa-tc-designer qa-tc-   qa-runner qa-gate
+       2 skill         2 skill         18 skill      5 skill        reviewer  2 skill   5 skill
+       validate input, routing 3 lane                               11 skill
+       quét injection
+                                       └────────────────────────────────────┘
+                                        3 LANE XUYÊN SUỐT: UI · API · E2E
+                                        lane API tự SKIP hoàn toàn nếu
+                                        không có openapi / dbml / tdd
+                                                                                        │
+                                                                                        ▼
+                                                                         ┌──────────────────────┐
+                                                                         │ QA_GATE_REPORT.md    │──┤
+                                                                         └──────────────────────┘
+                                                                              không có sổ cái
+
+AUTO-CHAINING: gọi agent 6 mà thiếu output 3/4/5 → tự chạy 3 → 4 → 5 trước.
+```
+
+**Ba lane là trục chính của đội QC, xuất hiện trong mọi agent.**
+Framework không có trục này — nó cắt theo *layer* (functional / integration / e2e /
+non-functional / exploratory) **nhân với** *platform* (web / app / system).
+Hai trục không mâu thuẫn, nhưng cắt chéo nhau — xem §4.
+
+---
+
+<a id="4"></a>
+## 4 · Ánh xạ hai bên
+
+> Bốn trạm khớp gần như hoàn hảo. Vấn đề dồn hết vào một chỗ.
+
+| # | Đội QC | Framework | Tình trạng |
+|---|---|---|---|
+| 1 | `qa-io-contract` — 2 skill, validate input + quét prompt-injection | *không có* — thay bằng `gate` + `context-loader` | ⚠️ **thiếu** Framework mất phần chống injection. Spec là dữ liệu để đọc, không phải mệnh lệnh — đội bạn có gác, framework không. |
+| 2 | `qa-orchestrator` — 2 skill, routing 3 lane | *không có* — thay bằng `Platform Resolution` | ⚠️ **lệch trục** lane ↔ platform |
+| **3** | **`qa-tc-analyst` — 18 skill** | **`/qc-analyze` (4) + `/qc-plan` (1)** | 🔴 **CHỖ ĐANG LÀM.** Framework cắt 1 agent thành 2 trạm, và chỉ lấy 5/18 skill. |
+| 4 | `qa-tc-designer` — 5 skill | `/qc-design-test` — 11 file | ✅ khớp, framework còn phong phú hơn |
+| 5 | `qa-tc-reviewer` — 11 skill | `/qc-review` — 10 file | ✅ khớp |
+| 6 | `qa-runner` — 2 skill | `/qc-run-test` — 7 file *+ ghi sổ cái + đóng bug* | ✅ framework làm nhiều hơn |
+| 7 | `qa-gate` — 5 skill | `/qc-report` — 1 file | ⚠️ **mỏng hơn** framework thiếu `coverage-evaluator`, `risk-matrix-builder`, `gate-decision` |
+
+### Điều có lẽ chưa biết
+
+Framework hiện tại port từ nhánh **`lms_autotest`**, không phải nhánh hợp nhất đang chạy.
+Bằng chứng nằm trong chính file agent của đội QC:
+
+```
+## Skill bổ sung (hợp nhất từ lms_autotest)
+spec-breakdown · business-rules · data-flow · acceptance-criteria · test-plan
+```
+
+**Đúng năm cái đó, không hơn không kém, là toàn bộ những gì framework đang có ở trạm 1 + 2.**
+Framework lấy đúng phần *phụ trợ* của nhánh cũ và bỏ lại 13 skill lõi của nhánh mới.
+(`test-plan` thì bị đẩy sang `qa-planner/` = trạm 2.)
+
+### Trục cắt chéo nhau — nhìn cụ thể
+
+```
+LAYER CỦA FRAMEWORK              LANE CỦA ĐỘI QC
+                                 UI    API   E2E   (không có lane)
+functional/gui-screen            [✓]
+functional/gui-feature           [✓]
+integration/gui                  [✓]
+functional/api                        [✓]
+integration/api                       [✓]
+e2e/journey                                 [✓]
+integration/db                                     [░░░░░░░░]  ┐
+integration/kafka                                  [░░░░░░░░]  │ 4 layer framework
+non-functional                                     [░░░░░░░░]  │ không có lane
+exploratory                                        [░░░░░░░░]  ┘ tương ứng
+
++ TRỤC THỨ HAI mà QC không có: platform (web / app / system)
+  → mỗi QC pass của framework khoá đúng MỘT platform, vì SC3 của web
+    và SC3 của app là hai scenario khác nhau, ghi vào hai file sổ cái khác nhau.
+```
+
+---
+
+<a id="5"></a>
+## 5 · Ba quyết định
+
+> Cả ba đều **không phải lỗi kỹ thuật** — chúng là chỗ hai đội định nghĩa "giao hàng" khác nhau.
+
+Kỳ vọng đặt ra cho `/qc-analyze` là hai chế độ:
+
+- **Mặc định** — trả GAP theo đúng định dạng mà `/refine-prd` sinh ra, như một lăng kính của QA.
+- **`--standard`** — trả đúng kết quả gốc mà đội automation test đang làm.
+
+Ba câu dưới đây là những chỗ hai chế độ đó chạm vào ranh giới đang có của framework.
+
+### Hình chung cho câu 1 và câu 2
+
+```
+CÁCH ĐỘI QC CẮT                          CÁCH FRAMEWORK CẮT
+
+┌──────────────────────┐                 ┌────────────────────┐
+│ qa-tc-analyst        │                 │ /qc-analyze        │
+│ một agent làm cả 3   │                 │  ① bóc yêu cầu     │──► REQUIREMENT_ANALYSIS.md
+│ ─────────────────    │                 │  ② tìm gap         │──► DOC_GAPS.md
+│  ① bóc yêu cầu       │                 └─────────┬──────────┘
+│  ② tìm gap tài liệu  │                           ▼
+│  ③ lập test plan     │                 ┌────────────────────┐
+└──────────┬───────────┘                 │ /qc-plan           │
+           │                             │  ③ lập test plan   │──► TEST_PLAN.md
+           ├──► ✕ requirement analysis   └────────────────────┘
+           │      — giấy nháp, KHÔNG xuất
+           ├──► DOC_GAP_<UC>.md
+           └──► TEST_PLAN_<UC>.md
+
+VÌ SAO CẢ HAI ĐỀU ĐÚNG
+  Đội QC làm ba việc trong MỘT agent → file ① là nháp nội bộ, không cần giao cho ai.
+  Framework tách thành BA lệnh riêng → file ① phải tồn tại vì trạm 2 và trạm 3 đọc nó.
+  → "đúng gốc" theo nghĩa chữ sẽ làm trạm 2 và trạm 3 MẤT INPUT.
+```
+
+---
+
+### CÂU 1 — `REQUIREMENT_ANALYSIS.md`: giữ hay bỏ?
+
+Đội QC nói file này là **giấy nháp**:
+*"phân tích rủi ro / AC / TCOND chỉ là bước trung gian nội bộ, KHÔNG phải deliverable"*.
+Framework coi nó là **hợp đồng giao hàng** — `qc-plan.md:165` và `qc-design-test.md:165`
+đều khai rõ là đọc nó.
+
+> **Hỏi lại cho dễ:** khi chạy `--standard`, có chấp nhận nó vẫn âm thầm ghi ra một file nháp
+> mà QC không cần mở — chỉ để trạm 2 và trạm 3 đọc được — hay "đúng gốc" nghĩa là
+> *tuyệt đối* không có file đó?
+
+| Chọn | Nghĩa là | Giá phải trả |
+|---|---|---|
+| **Vẫn ghi** *(khuyến nghị)* | Giữ hợp đồng giữa các trạm. Coi nó là handoff nội bộ, không phải deliverable của QC. | Không phải sửa gì downstream. QC chỉ cần không mở nó. |
+| Bỏ, trạm 2/3 đọc DOC_GAP | Trung thành 100% với gốc QC. | Sửa cả `qc-plan` + `qc-design-test`, và dựng lại phần requirement chúng đang cần từ nguồn khác. |
+| Bỏ, thay bằng `findings.yaml` | Trạm 2/3 đọc dữ liệu máy-đọc-được thay vì hai file `.md`. | Refactor ba lệnh cùng lúc. Sạch nhất về lâu dài, đắt nhất bây giờ. |
+
+---
+
+### CÂU 2 — `TEST_PLAN`: của trạm 1 hay trạm 2?
+
+Đội QC: analyst xuất **cả** DOC_GAP **và** TEST_PLAN, xong việc phân tích.
+Framework: DOC_GAP ở trạm 1, TEST_PLAN ở trạm 2 (skill `qa-planner/test-plan.md` —
+chính là skill `test-plan` của đội QC, đã bị đẩy sang trạm khác).
+
+> **Hỏi lại cho dễ:** muốn đội QC gõ **một lệnh** ra cả hai file (giống họ đang làm),
+> hay **hai lệnh liền nhau** ra hai file (giữ đúng sáu trạm của framework)?
+
+| Chọn | Nghĩa là | Giá phải trả |
+|---|---|---|
+| **Thêm `--standard` cho cả `/qc-plan`** *(khuyến nghị)* | QC gõ hai lệnh liền nhau, kết quả giống dây gốc của họ. Ranh giới sáu trạm giữ nguyên. | Đội QC phải học là "phân tích" giờ là hai lệnh. |
+| Trạm 1 xuất luôn cả hai file | Khớp gốc bằng đúng một lệnh. | Trạm 2 thành no-op khi đã `--standard` — phải khai rõ để không ai chạy trùng và ghi đè. |
+| Gộp trạm 1 + trạm 2 | Thừa nhận framework đã tách sai so với thực tế đội QC. | Đụng `docs/explain`, `report-footer`, và mọi chỗ khai "pipeline 6 trạm". |
+
+---
+
+### CÂU 3 — Kết quả GAP đi vào file nào?
+
+Framework có một thứ gọi là **Review Board** — bảng mà PO click chuột phải vào file `.yaml`
+để mở, đọc từng finding, bấm accept hoặc reject, rồi lệnh `--resume` *tự sửa PRD* theo
+những cái đã accept.
+
+Hiện `/refine-prd` sinh file `{prd-slug}-findings.yaml` với ba lăng kính **DEV · SA · PO**.
+Có một **lăng kính QA thứ tư đã viết sẵn nhưng bị comment lại** — kèm công thức bật lại
+năm bước, ở `commands/refine-prd.tmpl:60-79`. Nội dung nó hỏi:
+*"AC này có nêu được kết quả quan sát / kiểm chứng được không?"* — đúng góc nhìn QC.
+
+```
+CÁCH A · FILE RIÊNG, CÙNG ĐỊNH DẠNG
+
+  /refine-prd  ──►  {prd-slug}-findings.yaml       (DEV, SA, PO) ─┐
+                                                                   ├─► Review Board
+  /qc-analyze  ──►  {UC-ID}-qa-findings.yaml       (QA)          ─┘   đọc được cả hai —
+                                                                       vì cùng một schema
+
+CÁCH B · CHUNG MỘT FILE
+
+  /refine-prd  ──┐
+                 ├─►  {prd-slug}-findings.yaml
+  /qc-analyze  ──┘         applied_to_version: ???
+                                    │
+                                    ▼
+        refine-prd MẤT KHẢ NĂNG PHÂN BIỆT
+        "PRD đổi là do CHÍNH TÔI áp fix"  ↔  "có người lạ sửa"
+        → mỗi lần chạy: quét lại TOÀN BỘ + bắn cảnh báo giả
+
+        Và lời hứa ở dòng đầu refine-prd — "chỉ áp được fix cho vấn đề
+        mà CHÍNH NÓ tìm ra" — bị phá.
+```
+
+**Cùng một schema, khác file — đó là toàn bộ khác biệt.**
+Review Board đọc theo schema, không theo tên file, nên cách A không mất gì về mặt
+trải nghiệm PO. Thêm nữa: `/refine-prd` chạy lúc PRD chưa có BDD, `/qc-analyze` chạy
+sau khi code đã xong — cùng lăng kính, hai thời điểm khác nhau, nên hai file là phản ánh
+đúng thực tế.
+
+> **Hỏi lại cho dễ:** muốn QC gap nằm **cùng file** với gap của DEV / SA / PO,
+> hay **file riêng cùng định dạng** để Board vẫn đọc được cả hai?
+
+---
+
+<a id="6"></a>
+## 6 · Món quà đi ngược chiều
+
+> Đội QC có một thứ framework đang thiếu, và nên lấy **bất kể ba câu trên trả lời thế nào**.
+
+Framework có một engine fan-out dùng chung, `steps/review-fanout.md`: nhận `DIMENSIONS` +
+`FINDINGS SCHEMA`, spawn nhiều sub-agent song song, rồi chạy vòng lặp
+**completeness-critic** tới khi hai vòng liền không sinh thêm gì mới.
+
+Vòng critic đó chỉ đẩy *recall* lên — tìm thêm, tìm thêm.
+**Không có gì kéo *precision* lại.**
+
+`gap-verifier` của đội QC là đúng nửa còn thiếu đó:
+
+> **Nguyên tắc tối thượng:** một gap chỉ hợp lệ khi có ĐỦ 2 vế —
+> **(1)** spec nguồn nêu / ngụ ý hành vi X **VÀ** **(2)** không tài liệu nào trong `inputs/`
+> trả lời X. Thiếu 1 trong 2 → KHÔNG phải gap.
+>
+> ⚠️ Cấm dùng chính cột Evidence trong DOC_GAP làm bằng chứng.
+
+```
+steps/review-fanout.md
+
+  PHASE 1              PHASE 2                  PHASE 2.5 · THÊM VÀO       PHASE 3
+┌──────────────┐   ┌────────────────────┐   ┌─────────────────────────┐  ┌──────────────┐
+│ fan-out      │──►│ completeness-critic│──►│ gap-verifier  T1–T6     │─►│ dedup + ghi  │
+│ song song    │   └────────────────────┘   │ mở lại nguồn,           │  │ file         │
+└──────────────┘        ↑ đẩy RECALL        │ không tin Evidence      │  └──────────────┘
+                                            └─────────────────────────┘
+                                                 ↑ kéo PRECISION
+
+AI ĐƯỢC HƯỞNG:  /refine-prd   ·   /review-context   ·   /qc-analyze
+                — port một lần, ba lệnh dùng chung
+```
+
+**Sáu phép kiểm T1–T6 giết gap ảo:** evidence bịa hoặc trích sai · yêu cầu tự bịa ·
+gap spec đã trả lời ở chỗ khác · hai rule khác UC/pha bị coi là mâu thuẫn ·
+rule đã có ở tài liệu gốc mà đòi con lặp lại · gap thực ra là "làm kỹ test" chứ không
+phải spec thiếu.
+
+Cùng họ với `T13` ("không kiểm được ≠ sạch") và `R15` ("nhắc tên ≠ dùng") đã có trong framework.
+
+**Tin tốt về chi phí port:** chỉ khoảng **41 dòng** hardcode `inputs/…` trên toàn bộ
+23 skill file — tám file chỉ một dòng; nặng nhất là `full-lane-dispatcher` (13) và
+`exhaustive-gap-scanner` (11). Không phải viết lại 3.980 dòng.
+
+---
+
+<a id="7"></a>
+## 7 · Plan năm phase
+
+> **P0 và P1 không phụ thuộc ba quyết định — làm được ngay.**
+
+### P0 · Chuẩn hoá nền — chưa đụng `qc-analyze`
+
+- Port `gap-verifier` T1–T6 → `steps/gap-verify.md`, cắm vào `review-fanout.md` làm
+  **Phase 2.5** (opt-in qua tham số `VERIFY=on`).
+- Port 6 anti-pattern + 3 câu hỏi lọc bắt buộc vào cùng file đó.
+- Sửa hai lỗi đã tìm ra: hoán vị **Guard ↔ Platform Resolution**; khai `*Checkpoint:*`
+  và sửa `docs/explain/15-qc-analyze.md` (đang ghi "không gate chặn" trong khi hành vi
+  thật là chặn thường).
+
+### P1 · Đưa 18 skill còn thiếu vào
+
+- Copy 23 file → `core/skills/qc/qa-analyst/`, thay ~41 dòng `inputs/…` →
+  `{paths.specs_dir}` / `{spec_source}`.
+- Thêm frontmatter provenance (`upstream_sha` + `upstream_path`) để **phát hiện drift**.
+  Repo QC vẫn là chủ, `qc_skills_dir` vẫn override được — nhưng không có mốc này thì
+  hai bản trôi xa nhau trong im lặng, đúng bệnh mà `R10` tồn tại để chặn.
+- Bổ sung bước **verify `qc_skills_dir` tồn tại + đủ file** vào `context-loader`.
+  Hiện nó chỉ đọc giá trị và gán default, không kiểm — trỏ sai thì lệnh vẫn chạy,
+  vẫn ghi file, phân tích rỗng logic, và *không cờ nào bật*.
+
+### P2 · Chế độ mặc định = lăng kính QA — *phụ thuộc câu 1 và câu 3*
+
+- `/qc-analyze` gọi `review-fanout` với `DIMENSIONS` = 5 chiều của `exhaustive-gap-scanner`
+  (Business Rules · Error Handling · UI/UX · Test Data & Config · Cross-Document),
+  `GRANULARITY=per-uc`, `VERIFY=on`.
+- Ghi `{refinement_dir}/{UC-ID}-qa-findings.yaml`, `lens: "QA"`.
+- `DOC_GAPS.md` trở thành **bản render người-đọc** của cùng dữ liệu đó — một nguồn, hai mặt.
+
+### P3 · Chế độ `--standard` — *phụ thuộc câu 1 và câu 2*
+
+- Bypass `review-fanout`, chạy nguyên dây QC: `full-lane-dispatcher` → lane UI/API/E2E →
+  `exhaustive-gap-scanner` → `gap-verifier`.
+- Ghi `DOC_GAP_{UC-ID}.md` 10 cột theo template gốc, thêm `DOC_GAPS.standard.template.md`.
+
+### P4 · Canh bằng máy
+
+- Rule `self-check` mới: hai template GAP phải khớp số cột đã khai trong `trace-schema.json`;
+  enum `lens` phải đồng bộ giữa `refine-prd` và `qc-analyze`; provenance sha của skill port
+  không được thiếu.
+
+---
+
+<a id="8"></a>
+## 8 · Bốn lỗi tìm được khi đọc `/qc-analyze`
+
+> Độc lập với việc sáp nhập — đúng sai vẫn nên sửa.
+
+### (a) 🔴 Doc nói ngược với hành vi thật
+
+`/qc-analyze` không có dòng `*Checkpoint:*` và không nằm trong
+`trace-schema.json → gate.checkpoint_levels.none` → theo luật gate là **chặn thường**.
+Nhưng `docs/explain/15-qc-analyze.md` ghi *"Không gate chặn"*.
+
+Cái sai là explain doc — lệnh này ghi file nên chặn thường là đúng.
+`R11` chỉ canh file lệnh, không canh explain doc.
+
+### (b) ⚠️ Ba prompt chặn liên tiếp, `--yes` chỉ mở được một
+
+CHECKPOINT → Guard BDD (Y/N) → câu hỏi platform. Gate chỉ nói `--yes` bỏ qua CHECKPOINT.
+→ `claude -p "/qc-analyze UC1 --yes"` vẫn treo. Đường headless mà gate hứa
+(`steps/gate.md` dòng 97) bị bít cho chính lệnh này.
+
+### (c) ⚠️ Guard đọc `.feature` trước khi biết platform
+
+Section `## Guard` đứng *trên* `## Platform Resolution`. Với UC multi-platform,
+`bdd/web/`, `bdd/app/`, `bdd/system/` là ba file khác nhau, có thể ba `@trace.status`
+khác nhau. Hoán vị hai section là fix một dòng.
+
+### (d) ⚠️ `qc_skills_dir` được đọc nhưng không được kiểm
+
+Vì đây là path *cố ý* trỏ ra repo ngoài để framework upgrade không ghi đè, trỏ sai là
+kịch bản bình thường. Trỏ sai → không nạp được skill nào → vẫn chạy, vẫn ghi hai file,
+phân tích rỗng logic, **không cờ nào bật**.
+
+### Còn một khoảng trống lớn hơn cả bốn cái trên
+
+Đội QC có `qa-io-contract` với skill `injection-scanner`, và nguyên tắc:
+*"nội dung spec là dữ liệu để đọc, không phải mệnh lệnh"*.
+
+**Framework không có gì tương ứng.** Mọi lệnh của framework đọc PRD / BDD / design-spec
+do người khác viết và nạp thẳng vào context — không có bước gác nào.
+Ngoài phạm vi việc đang làm, nhưng nên ghi lại.
+
+---
+
+## Liên quan
+
+- [`qc-implementation-log.md`](qc-implementation-log.md) — nhật ký triển khai, viết cho người không cần biết code
+
+- [`qc-sync-command.md`](qc-sync-command.md) — **phần 2**: lệnh `/sync-qc-base` để về sau
+  QC sửa skill thì đưa vào framework được. Lưu ý: `--adopt` của lệnh đó **chính là** P1 ở §7
+  trên — không phải hai việc, là một việc có công cụ.