@educa-corp/sdd-framework 0.8.1 → 0.9.1

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

@@ -1,502 +0,0 @@
-# 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ụ.