@educa-corp/sdd-framework 0.9.2 → 0.9.4

package/docs/plans/qc-implementation-log.md

@@ -1373,6 +1373,287 @@ Lăng kính này phân biệt được. Hiện **không ai làm**.
 
 ---
 
+# ✅ B11 — Gộp tài liệu QC về cấp PRD (thôi chia nhỏ theo từng UC)
+
+**Việc này khởi từ một ảnh chụp thư mục.** Đội QC chạy trạm phân tích và nhận về một cây vỡ
+vụn: mỗi UC một thư mục gốc riêng — 10 UC là 10 thư mục, 30 file, cùng một tính năng.
+
+## Điều làm tôi phải xem lại kết luận của chính mình
+
+Câu hỏi ban đầu tôi hiểu là *"xếp lại thư mục cho gọn"*. Nó không phải. Nó là **đổi độ mịn của
+chính tài liệu**: một file gap cho cả tính năng, không phải một file mỗi UC.
+
+Và khi đi kiểm, hoá ra **framework đang làm sai, không phải đội QC**. Ba bằng chứng độc lập,
+đều nằm sẵn trong repo từ trước:
+
+| # | Bằng chứng | Nó nói gì |
+|---|---|---|
+| 1 | File thật của đội QC tên `DOC_GAP_FEAT-02-3.md` | Mã tính năng, **không có** hậu tố UC. Họ vốn làm ở cấp tính năng |
+| 2 | Mã gap trong template gốc là `GAP-<UC>-001` | Mã **mang tên UC** chỉ có nghĩa khi **một file chứa nhiều UC**. Trong file một-UC nó là thừa |
+| 3 | Kỹ năng lập kế hoạch test viết *"Test Plan cho một **feature**"*, khuôn là `# Test Plan – <Feature>` | Cấp tính năng, từ đầu |
+
+Cả ba đều chỉ về cấp tính năng. **Việc chia nhỏ theo UC là framework tự áp vào lúc port** —
+không ai yêu cầu, và nó phá đúng cái mà mã `GAP-<UC>-…` được thiết kế để làm.
+
+Thêm một chỗ bất nhất đã tồn tại: **sổ kết quả kiểm thử vốn đã gom theo tính năng**
+(`.trace/{domain}/{tính-năng}/…`). Nên trước B11, hai nơi cùng nói về một UC lại xếp theo hai
+kiểu khác nhau.
+
+## Ba thứ đổi
+
+```
+TRƯỚC                                  SAU
+docs/FEAT-01-2-UC1/web/DOC_GAP.md      docs/FEAT-01-2/web/DOC_GAP.md
+docs/FEAT-01-2-UC2/web/DOC_GAP.md        ← UC1…UC5 chung một bảng,
+docs/FEAT-01-2-UC3/web/DOC_GAP.md          phân biệt bằng cột "UC"
+docs/FEAT-01-2-UC4/web/DOC_GAP.md      docs/FEAT-01-2/web/TEST_PLAN.md
+docs/FEAT-01-2-UC5/web/DOC_GAP.md      docs/FEAT-01-2/web/REQUIREMENT_ANALYSIS.md
+   (× 3 loại tài liệu = 15 file)          (3 file)
+```
+
+**Nền vẫn là một cấp thư mục — bắt buộc.** Một kịch bản `SC3` của web và `SC3` của app là hai
+thứ khác nhau, và sổ kết quả tách theo nền. Gộp nền lại là trộn hai bộ kịch bản.
+
+## Chỗ tôi tưởng phải trả giá, mà hoá ra được lãi
+
+Tôi tưởng gộp 5 UC vào một lần chạy sẽ tốn gấp 5 lần. **Ngược lại.**
+
+Chạy từng UC thì tài liệu yêu cầu, bản thiết kế, tài liệu kỹ thuật **bị đọc lại mỗi lần** —
+5 UC là đọc 5 lượt cùng một tài liệu. Phần dùng chung chiếm đa số đầu vào; chỉ phần kịch bản
+test là riêng theo UC.
+
+Và có lợi thêm về **chất**, không chỉ chi phí: **chỗ hai UC của cùng tính năng nói khác nhau**
+— UC1 một kiểu, UC3 kiểu khác — chỉ nhìn thấy được khi đọc cùng lúc. Chạy tách UC thì về
+**cấu trúc** là không thể thấy, không phải "khó thấy". Nên trạm phân tích giờ có thêm một mục
+bắt buộc: *"Mâu thuẫn chéo UC"*.
+
+## Chỗ nguy hiểm — và vì sao nó đã được giải sẵn
+
+Gộp nhiều UC vào một bảng thì mã gap có thể đè nhau. Nếu đánh số liền `GAP-01…GAP-60` thì
+**chạy lại UC1 sẽ đánh số lại toàn bộ UC2–UC5** — mà khoảng 15 kỹ năng đang ghi
+`🚫 Chặn bởi: GAP-xx` vào từng test case. Test case sẽ trỏ sang gap khác, **im lặng, không ai
+báo lỗi**.
+
+Điểm hay: **template gốc đã giải sẵn** — mã của nó là `GAP-<UC>-001`, mang tên UC. Chạy lại UC1
+không đụng số của UC khác. B11 chỉ **định nghĩa rõ** thành `GAP-UC1-001`, và thêm `GAP-GEN-001`
+cho gap thuộc cả tính năng.
+
+*(Kết quả đội QC chạy hôm trước ghi `GAP-01` phẳng — tức nó **không theo template**. Đó là một
+vấn đề khác, xem §Cố ý chưa làm.)*
+
+## Một luật, một chỗ
+
+Luật *"xác định tính năng nào, nền nào, những UC nào"* trước đây **bị chép ở 5 lệnh** và câu chữ
+đã lệch nhau. Năm bản của một luật là nơi lỗi sống: sửa bốn, quên một, và trạm bị quên ghi tài
+liệu vào sai thư mục **mà không báo gì**.
+
+Giờ nó là **một file dùng chung**, cả 6 trạm cùng nạp. Đổi bố cục lần này buộc phải sửa cả 5
+bản dù sao — nên dồn về một chỗ là rẻ hơn, không đắt hơn.
+
+## Trạm nào chạy cả tính năng, trạm nào vẫn theo UC
+
+| Trạm | Phạm vi | Vì sao |
+|---|---|---|
+| Phân tích yêu cầu · Lập kế hoạch test | **cả tính năng × 1 nền** | Chúng sinh ra 3 tài liệu cần gộp |
+| Thiết kế test · Soát · Chạy test | **vẫn theo từng UC** | Thiết kế và chạy test **thật sự** làm tăng dần theo UC. Giữ được việc làm UC1 khi UC3 chưa xong là đúng — chỉ **chỗ đọc/ghi** đổi |
+| Sổ kết quả kiểm thử | **không đổi** | Mỗi hàng là một kịch bản; liên kết với bảng gap đi qua cột `UC` |
+
+**Gap chặn theo từng UC, không chặn cả tính năng.** Một gap nghiêm trọng ở UC3 không có lý do
+gì dừng việc thiết kế test cho UC1.
+
+## UC chưa duyệt: ghi "chưa xét", không im lặng bỏ
+
+Trạm phân tích chỉ lấy UC có kịch bản test **đã duyệt**. UC còn nháp **vẫn có một hàng** trong
+bảng *Phạm vi phân tích*, đánh dấu `⏸ Chưa xét` kèm lý do.
+
+> **Vì sao không bỏ khỏi bảng.** *"Chưa xét"* khác *"đã xét, không thấy gap"*. Bỏ khỏi bảng là
+> để hai chuyện đó trông giống nhau — và một UC bị bỏ sót sẽ trông như một UC sạch.
+
+Giữ lại cờ `--include-draft` cho ai cố ý chạy sớm trên bản nháp. Cách dùng đó **vốn được cho
+phép** (cổng cũ là cảnh báo mềm, không phải chặn cứng); bỏ hẳn là lấy đi một năng lực đang có
+mà không ai khai.
+
+## Dữ liệu cũ của đội QC: lưu trữ, không gộp tay
+
+Gộp 5 thư mục về 1 thì tài liệu phân tích của UC1 và UC2 **đâm nhau ở cùng một đường dẫn** —
+không có cách gộp tự động hai tài liệu văn xuôi. Nên script `migrate-qc-docs.js` **không giả vờ
+gộp**:
+
+| Loại | Xử lý |
+|---|---|
+| Test case | **dời** sang thư mục mới — tên file mang tên tính năng nên không đâm nhau |
+| 3 tài liệu cấp trên | **lưu trữ** vào `docs/_archive-per-uc/`, in danh sách cần sinh lại |
+| `DOC_GAPS.md` (tên cũ) | đổi thành `DOC_GAP.md` — trả luôn món nợ B9 còn treo |
+| File nằm ngoài mọi nền | **để nguyên + báo** — tài liệu QC không mang dấu nền nên không suy được |
+| Đích đã có file | **không ghi đè**, báo ra để người xử lý |
+
+**Sinh lại tốt hơn gộp tay**, vì bản cấp tính năng thấy được mâu thuẫn chéo UC mà 5 bản rời
+không thấy. Không xoá gì — thư mục lưu trữ là đường lùi, và là **cách duy nhất** để đối chiếu
+xem bản mới có bắt thêm gap thật hay không.
+
+## Đã kiểm chứng
+
+| Phép kiểm | Kết quả |
+|---|---|
+| Dựng lại toàn bộ | 41/41 mẫu lệnh ✅ |
+| Bộ kiểm tra nội bộ (16 luật) | sạch ✅ |
+| Bộ test tự động | **199/199** ✅ (không tụt so với trước B11) |
+| Đường dẫn cũ còn sót trong mã | **0** (34 chỗ → 0) |
+| Luật dùng chung đã lan vào cả 6 trạm | ✅ đếm được trong bản đã đóng gói |
+| Script dời file — chạy thử trên cây giả lập 31 file | **31 → 31 file, không mất gì**; chạy lại lần hai không đổi gì thêm |
+| 5 ca biên của script (tên cũ · hai nền · file lạc · bố cục đã mới · đích bị chiếm) | đều xử lý đúng ✅ |
+
+## Cố ý chưa làm — và vì sao để riêng
+
+| Việc | Vì sao |
+|---|---|
+| **Máy kiểm cấu trúc file gap** | Đây mới là cách chữa thật cho bệnh *"không theo template"* (kết quả hôm trước ra 6 cột, dùng chữ `Major` — không theo template nào cả). Nhưng nó là **năng lực mới**, không phải đổi bố cục. Trộn vào thì sau này không biết cái nào chữa được bệnh gì. Làm sau khi có phép thử thật |
+| **`Blocker` ↔ `Critical`** | File thật của đội QC dùng `🔴 Critical`; framework đổi thành `Blocker` vì trạm chạy test đọc chữ đó. Nhìn kết quả hôm trước thì rõ là **đổi từ ngữ của họ làm tăng khả năng lệch, không giảm** — nhưng đó là quyết định riêng, một dòng, và cần bạn chốt |
+
+---
+
+# ✅ B12 — Rà trạm viết kịch bản kiểm thử theo bản gốc
+
+Đi theo đúng thứ tự dây chuyền: xong trạm 1 và 2 (B11) thì tới trạm 3 — **trạm quyết định có
+test hay không có test**.
+
+## Hai điều rà ra
+
+**① Trạm này chưa hề được đụng trong cả đợt merge.** Bản đồ port ghi **21/21 file gốc ở trạng
+thái "chưa quyết"**. 11 kỹ năng đang chạy đến từ **một nguồn khác** (`lms_autotest`), không phải
+từ đội QC.
+
+| | File | Dòng |
+|---|---|---|
+| Bản gốc đội QC | 21 | **2.509** |
+| Framework | 11 | **496** *(~20%)* |
+
+**② Một lỗi im lặng, cùng lớp với `DOC_GAPS` / `DOC_GAP`:**
+
+| Ai | Nói tên file là |
+|---|---|
+| 2 kỹ năng | `TC_<FEATURE>.md` |
+| 1 kỹ năng | `TC_<FEATURE>_API.md` |
+| **4 kỹ năng** | **không nêu tên gì cả** |
+| Lệnh thiết kế · lệnh chạy · lệnh soát · module Playwright *(13 chỗ)* | `*.Test.md` |
+
+**Trạm thiết kế ghi ra thứ trạm chạy không tìm thấy.** Và không có gì báo lỗi — file vẫn nằm
+đó, trạm sau chỉ đơn giản không thấy.
+
+Framework có **phương pháp** (EP/BVA/bảng quyết định, danh sách nhóm TC); bản gốc có **chi
+tiết** (cấm từ mơ hồ, khuôn TC, từ điển hành động, bảng tra mã HTTP). Đúng khuôn đã gặp ở B1.
+
+## Bốn quyết định
+
+| # | Chốt | Nghĩa cho người dùng |
+|---|---|---|
+| **1** | **Luật ATOMIC, có cả chế độ tách tối đa** | Mỗi test case đúng **một** dòng kết quả mong đợi. Nhiều điểm kiểm → tách thành nhiều TC độc lập |
+| **2** | **Bỏ bảng trong file test case** | Toàn bộ dạng danh sách, không ký tự `\|` — kể cả mục Tổng hợp và Trace Matrix |
+| **3** | **Hai file, chia theo "có qua giao diện"** | mặc định → file giao diện (6 nhóm) · `--api` → file API (2 nhóm) · `--all` → cả hai |
+| **4** | **Lấy trọn 7 file luật chung + cả nhánh API, nhưng VIẾT LẠI 2 file mẫu** | 1.523 dòng |
+
+## Chỗ suýt tự bắn vào chân mình
+
+Nhánh API của bản gốc có 2 file **test case mẫu**. Đọc kỹ thì chúng viết **trước** luật ATOMIC
+(đội QC chốt 2026-07-09, và văn bản ghi rõ *"ĐẢO rule cũ"*):
+
+```
+MẪU GỐC (cũ hơn luật)                  ĐÃ VIẾT LẠI
+**Expected:**                           #### Expected Result
+- HTTP 201; body.id = x;                - HTTP 201 AND body.id exists
+  bản ghi có trong DB
+     ▲ ba kết cục nối bằng ";"         → TC_002: body.<field> = <giá trị>
+  mã: API-<FEATURE>-001                → TC_003: DB có bản ghi id = body.id
+     ▲ hệ mã khác                       mã: TC_<FEATURE>_NNN
+```
+
+**Lấy nguyên hai file này là dạy AI làm ngược đúng cái luật vừa chốt** — vì mẫu cụ thể luôn
+thắng luật trừu tượng. Đã viết lại cả hai, và kiểm bằng máy: **13/13 khối kết quả mong đợi có
+đúng 1 dòng**.
+
+Cũng bỏ 26 dòng là **bản nháp cũ** của chính họ: một bảng tra mã lỗi 14 dòng nằm gọn trong bảng
+95 dòng, một file chuỗi gọi 12 dòng nằm gọn trong hai file dài hơn. Lấy cả hai là có hai bảng
+tra cùng một thứ, rồi chúng lệch nhau.
+
+## Bốn thứ giờ mới có
+
+| Luật | Nó chặn điều gì |
+|---|---|
+| **Cấm 9 cụm từ mơ hồ** | *"hiển thị đúng"* · *"hoạt động bình thường"* · *"không lỗi"* → bắt viết giá trị đo được. Phép thử: **hai QC đọc có ra cùng một kết luận đỗ/trượt không?** |
+| **Khuôn TC + luật ATOMIC** | Mỗi TC một kết cục; mẫu đầy đủ; 5 bẫy khi đánh số lại hàng loạt |
+| **Cây quyết định chọn tầng** | ~12 ví dụ phân biệt: *"dropdown có placeholder"* = giao diện, *"dropdown hiện đúng N mục từ API"* = tích hợp |
+| **Từ điển hành động** | Một hành động **một** từ: Click (web) / Tap (mobile) / Enter (nhập) — cấm dùng Type, Input, Fill lẫn lộn |
+
+Thêm **kiểm trùng lặp** — thứ framework trước đây **không có gì cả**. Nó quan trọng hơn sau khi
+bật chế độ tách tối đa: nhân một TC trùng lên 5 mảnh thì thành 5 TC trùng, và không ai đếm
+được nữa. Nên kiểm trùng phải chạy **trước** khi tách.
+
+Và B11 vừa gom mọi UC vào **một thư mục** — nên **trùng chéo UC** giờ mới thực sự nhìn thấy
+được, và mới thực sự xảy ra. Hai UC của cùng tính năng rất hay dùng lại một luật nghiệp vụ;
+gặp thì trỏ trace về UC nguồn, **không viết lại**.
+
+## Chín bản của một luật → một bản
+
+Khối *"Format file TC"* trước đây **bị chép ở 9 kỹ năng** và câu chữ đã lệch nhau. Giờ một
+bản dùng chung, 9 kỹ năng trỏ về. **Cùng bệnh 5-bản mà B11 vừa chữa** — và lần này nó không
+tiết kiệm dòng, nó chỉ bỏ đi khả năng chín bản nói khác nhau.
+
+Cũng bỏ chữ **"hoặc"**: hai kỹ năng từng ghi *"file riêng **hoặc** gộp trong file feature"*.
+Chữ "hoặc" nghĩa là AI tự chọn mỗi lần một kiểu — nên hai lần chạy cùng một tính năng có thể ra
+hai cấu trúc thư mục khác nhau.
+
+## Hai lần bị máy bắt lỗi — và đó là điểm sáng
+
+**Lần 1 — self-check chặn.** Tôi dồn phần `@trace.testid_attr` sang file dùng chung, làm lệnh
+không còn nhắc tag nữa. Rule R3 đỏ ngay: *"schema khai `qc-design-test` là consumer nhưng lệnh
+KHÔNG nhắc tới nó"*. Đúng — tôi gộp quá tay. Đã trả lại ở lệnh.
+
+**Lần 2 — bộ test chặn.** `qc-scope.md` (B11) được 5 lệnh nạp, nên nó bị nướng 5 bản vào 5 file
+lệnh. Cộng thêm phần B12, tổng vượt ngưỡng: **1203 KB / ngưỡng 1200**. Framework đã có cơ chế
+cho đúng ca này (đọc-lúc-chạy thay vì nướng vào), chỉ là chưa dùng cho file đó. Chuyển xong:
+**1174 KB**.
+
+> Cả hai lỗi đều là **lỗi của tôi**, và **cả hai đều do máy bắt, không phải do tôi đọc lại**.
+> Đây chính là lập luận cho mục còn treo 2b: thứ có máy canh thì không đi lệch.
+
+## Bịt một điểm mù của chính bộ máy canh
+
+Cập nhật bản đồ port xong, self-check **xanh** — nhưng `functional/api.md` nhận nội dung port mà
+**không đóng dấu nguồn gốc** nào. Đọc lại luật thì rõ vì sao: nó so dấu với bản đồ **khi file có
+khai**. File không khai gì thì nó im lặng.
+
+Đã thêm một nhánh mới: **target đã port thì PHẢI khai** nguồn gốc, không chỉ "khai đúng nếu có
+khai". Và **thử cháy thật** cả hai góc (bỏ cả hai dòng · bỏ một dòng) — kêu đúng cả hai lần.
+
+Mất dấu nguồn gốc ở file đích nghĩa là: bản đồ biết file này port từ đâu, còn **người mở file
+thì không** — và lần đồng bộ sau, mọi thứ thành đoán.
+
+## Đã kiểm chứng
+
+| Phép kiểm | Kết quả |
+|---|---|
+| Dựng lại toàn bộ | 41/41 ✅ |
+| Bộ kiểm tra nội bộ | sạch (giờ có **17** nhánh luật) ✅ |
+| Bộ test tự động | **199/199** ✅ |
+| Tổng kích thước lệnh | 1174 KB / ngưỡng 1200 ✅ |
+| Tên file cũ còn sót | **0** |
+| Lệnh "in bảng" trong kỹ năng thiết kế | **0** |
+| Dấu vết mẫu cũ trong nhánh API | **0** |
+| Khối kết quả mong đợi đúng 1 dòng | **13/13** |
+| Entry "chưa quyết" của trạm này | **21 → 0** |
+| Target đã port có đủ dấu nguồn gốc | **23/23** |
+| File mới tới đủ ba tầng (nguồn → đóng gói → đang chạy) | **13/13/13** |
+
+## Cố ý chưa làm
+
+| Việc | Vì sao |
+|---|---|
+| **Máy kiểm cấu trúc file test case** | Vẫn là năng lực mới, và vẫn chờ kết quả phép thử của trạm 1. Nhưng B12 làm nó **rẻ hơn hẳn**: cả hai luật mới đều **đếm được** — "0 ký tự `\|`" và "1 dòng mỗi kết quả". Nếu phép thử kết luận cần máy kiểm thì làm một lượt cho cả file gap và file test case |
+| **4 file tầng test của bản gốc** *(ui · e2e · integration · nfr — 935 dòng)* | Đã ghi `skipped` **kèm lý do**, không để "chưa quyết". Framework tách tầng UI thành 3 kỹ năng theo cây quyết định thay vì một file 341 dòng; phần khuôn TC và độ chính xác **đã tách ra dùng chung**. Còn lại là phần khai kiến trúc agent — framework không có. Đối chiếu nội dung từng tầng để dành |
+| **3 trạm còn lại** | Đi theo thứ tự dây chuyền. Trạm soát là trạm kế tiếp, và nó **tiêu thụ** đúng chuẩn B12 vừa đặt ra — làm sau là đúng thứ tự |
+
+---
+
 # Tổng kết
 
 | | Quyết định ở B7 | Bằng chứng | |
@@ -1415,9 +1696,9 @@ rồi, giờ bắt nó **so** với hai tài liệu kia"*. Không nạp thêm fi
 
 # Các bước còn lại
 
-**Chín bước B0–B9 đã xong.** Không còn bước nào đang chờ quyết định để bắt đầu.
+**Mười ba bước B0–B12 đã xong.** Không còn bước nào đang chờ quyết định để bắt đầu.
 
-Nhưng có **một quyết định sai đã phát hiện** và **hai món nợ** — xem §Còn treo ở cuối.
+Nhưng có **hai việc chưa validate** và **bốn món nợ** — xem §Còn treo ở cuối.
 Mô tả kế hoạch gốc nằm ở [`qc-merge-plan.md`](qc-merge-plan.md).
 
 > **Nhật ký này chỉ ghi bước đã hoàn thành** — mỗi bước xong mới nạp vào đây, không viết trước.
@@ -1429,7 +1710,7 @@ Mô tả kế hoạch gốc nằm ở [`qc-merge-plan.md`](qc-merge-plan.md).
 Sau mỗi bước, toàn bộ hệ thống được dựng lại và kiểm tra tự động:
 
 - 41/41 mẫu lệnh dựng thành công
-- Bộ kiểm tra nội bộ báo sạch
+- Bộ kiểm tra nội bộ báo sạch (17 nhánh luật sau B12)
 - Nội dung mới đã lan đủ ba tầng: bản nguồn → bản đóng gói → bản đang chạy
 - **9** dấu nguồn gốc đều được kiểm chứng khớp với file gốc thật
 - Báo khói đã **thử cháy thật** cả 5 nhánh — không giao một cái chưa bao giờ kêu
@@ -1440,7 +1721,9 @@ Sau mỗi bước, toàn bộ hệ thống được dựng lại và kiểm tra
 
 | # | Câu | Mức | Ai quyết |
 |---|---|---|---|
-| **1** | Chạy thử trên một tính năng thật — **chín bước, chưa một lần chạy**. Ước lượng chi phí của tôi đã sai 3 lần, đều ước thấp | 🔴 chưa validate | bạn (cần spec thật) |
-| **2** | Đưa nhật ký cho đội QC xem — họ là chủ sở hữu các kỹ năng này, và định dạng họ nhận đã đổi | 🟠 | bạn |
+| **1** | Chạy thử trên một tính năng thật — **mười ba bước, chưa một lần chạy**. Sau B11 phép thử này còn quan trọng hơn: nó là cách duy nhất biết bản cấp tính năng có bắt được mâu thuẫn chéo UC, và có theo đúng template hay không. Ước lượng chi phí của tôi đã sai 3 lần, đều ước thấp | 🔴 chưa validate | bạn (cần spec thật) |
+| **2** | Đưa nhật ký cho đội QC xem — họ là chủ sở hữu các kỹ năng này, và định dạng họ nhận đã đổi **hai lần** (B9 rồi B11) | 🟠 | bạn |
+| **2b** | **Máy kiểm cấu trúc file gap** — bệnh *"không theo template"* vẫn chưa có gì chặn bằng máy. Hiện chỉ có chỉ thị bằng văn xuôi, tức **cùng loại** với câu chỉ đường đã thất bại, chỉ mạnh hơn | 🟠 chưa chữa | bạn (sau khi chạy thử B11) |
+| **2c** | `Blocker` ↔ `Critical` — đổi trạm chạy test đọc `Critical` (một dòng) thay vì bắt đội QC đổi thói quen. Kết quả hôm trước cho thấy đổi từ ngữ của họ làm **tăng** khả năng lệch | 🟡 | bạn |
 | 3 | 30 file không có bản gốc — framework tự sở hữu, gộp lại, hay ghép tay? | 🟡 nợ | bạn |
 | 4 | Có lấy lại 38 dòng đã mất của phần "lập kế hoạch test" không? | 🟡 nợ | bạn |

package/docs/plans/qc-sync-command.md

@@ -149,7 +149,8 @@ mà bản đồ này tồn tại để chặn — và §5 để máy canh nó.
   "adapt_rules": {
     "path-placeholders": [
       { "from": "inputs/free-trial-spec/specs/", "to": "{paths.specs_dir}/" },
-      { "from": "docs/<feature>/",              "to": "{paths.qc_dir}/{UC-ID}/{active_platform}/" },
+      { "from": "docs/<feature>/",              "to": "{paths.qc_dir}/{TICKET-ID}/{active_platform}/",
+        "note": "sau B11 phép map này gần như đồng nhất — upstream vốn đã là cấp feature (`docs/<feature>/`); chỉ thêm một cấp nền" },
       { "from": "inputs/",                      "to": "{paths.specs_dir}/", "note": "khái niệm nguồn-evidence" }
     ],
     "two-file-guard": { "kind": "append-block", "block": "…rào 'chỉ trả 2 file'…" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/sdd-framework",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"

package/scripts/migrate-qc-docs.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * migrate-qc-docs — move per-UC QC working docs into the per-PRD layout.
+ *
+ *   docs/{TICKET-ID}-UC{N}/{platform}/…
+ *     → docs/{TICKET-ID}/{platform}/…
+ *
+ * The per-UC layout shattered one feature across N sibling folders (10 UCs = 10 root
+ * folders, 30 files). It was the framework's own imposition when the QC skills were
+ * ported: upstream has always been PRD-scoped — their real file is `DOC_GAP_FEAT-02-3.md`
+ * (no UC suffix), the gap-ID format `GAP-<UC>-001` only means anything when ONE file holds
+ * several UCs, and `qa-planner/test-plan.md` says "Test Plan cho một feature". See B11.
+ *
+ * WHY THIS SCRIPT DOES NOT MERGE. Collapsing N UC folders into one makes UC1's
+ * REQUIREMENT_ANALYSIS.md and UC2's collide on the same target path, and two prose
+ * documents cannot be merged mechanically. So:
+ *
+ *   test-cases/*   → MOVED   (filenames carry <FEATURE>, they do not collide)
+ *   the 3 top docs → ARCHIVED to {qc}/_archive-per-uc/{UC-ID}/{platform}/
+ *                    and listed as NEEDS REGENERATE
+ *
+ * Regenerating beats hand-merging: a PRD-level pass reads the PRD, design-spec and
+ * tech-doc ONCE instead of once per UC, and it sees cross-UC contradictions that N
+ * separate passes structurally cannot. Nothing is deleted — the archive is the way back,
+ * and the only way to check whether the PRD-level run caught anything the old ones missed.
+ *
+ * Also folds in the pending `DOC_GAPS.md` → `DOC_GAP.md` rename (B9), in the same pass,
+ * including for folders that are ALREADY in the new layout. Without it `/qc-plan` reports
+ * "DOC_GAP not found" while the analysis sits right there under the old name.
+ *
+ * Reports (does NOT guess) two conditions that need a human:
+ *   - NO PLATFORM : files sit directly under {qc}/{UC-ID}/ with no platform level. The
+ *                   platform cannot be inferred from a QC artifact, so they are left alone.
+ *   - OCCUPIED    : the target path already holds a file — moving would overwrite it.
+ *
+ * DRY-RUN by default (prints the plan, changes nothing). Pass --apply to execute.
+ * Tracked files move with `git mv` to preserve history; the rest with fs.rename.
+ *
+ * Usage (from the consumer project root):
+ *   node scripts/migrate-qc-docs.js                 # dry-run, prints plan
+ *   node scripts/migrate-qc-docs.js --apply         # execute
+ *   node scripts/migrate-qc-docs.js --qc docs --root .
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// ── args ──────────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2);
+const has = f => argv.includes(f);
+const flag = (f, d) => { const i = argv.indexOf(f); return i !== -1 ? argv[i + 1] : d; };
+
+const APPLY = has('--apply');
+const ROOT = path.resolve(flag('--root', '.'));
+const QC = flag('--qc', 'docs');
+
+const qcAbs = path.join(ROOT, QC);
+const ARCHIVE = '_archive-per-uc';
+
+// The three PRD-level documents. Anything else at that level is archived too (safe
+// default) but called out separately so nobody loses a file without seeing its name.
+const TOP_DOCS = ['REQUIREMENT_ANALYSIS.md', 'DOC_GAP.md', 'DOC_GAPS.md', 'TEST_PLAN.md'];
+
+// `{TICKET-ID}-UC{N}` — the framework's UC-ID contract (steps/gate.md Bước 1: TICKET-ID is
+// the part before `-UC`). Anchored at both ends so `FEAT-01-2-UC1` matches but a folder
+// that merely contains the letters "uc" does not.
+const UC_DIR = /^(.+)-UC(\d+)$/i;
+
+// ── git tracked set (for `git mv`) ────────────────────────────────────────────
+let tracked = null;
+try {
+  const out = execSync('git ls-files', { cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  tracked = new Set(out.split('\n').filter(Boolean).map(p => p.replace(/\\/g, '/')));
+} catch { tracked = null; }
+
+const rel = abs => path.relative(ROOT, abs).replace(/\\/g, '/');
+const isTracked = abs => !!(tracked && tracked.has(rel(abs)));
+const isDir = p => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+
+function walk(dir) {
+  let out = [];
+  if (!isDir(dir)) return out;
+  for (const n of fs.readdirSync(dir)) {
+    const p = path.join(dir, n);
+    out = out.concat(isDir(p) ? walk(p) : [p]);
+  }
+  return out;
+}
+
+// ── plan ──────────────────────────────────────────────────────────────────────
+const moves = [];       // { from, to, kind }
+const noPlatform = [];  // { ucDir, files }
+const occupied = [];    // { from, to }
+const regen = new Map();// "TICKET|platform" → { ticket, platform, ucs:Set }
+
+if (!isDir(qcAbs)) {
+  console.log(`\n${QC}/ does not exist under ${ROOT} — nothing to migrate.\n`);
+  process.exit(0);
+}
+
+const ucDirs = fs.readdirSync(qcAbs)
+  .filter(n => n !== ARCHIVE)
+  .map(n => ({ name: n, abs: path.join(qcAbs, n) }))
+  .filter(d => isDir(d.abs) && UC_DIR.test(d.name));
+
+function plan(from, to, kind) {
+  // Never overwrite, and never let two sources land on one target.
+  if (fs.existsSync(to) || moves.some(m => m.to === to)) { occupied.push({ from, to }); return; }
+  moves.push({ from, to, kind });
+}
+
+for (const d of ucDirs) {
+  const m = UC_DIR.exec(d.name);
+  const ticket = m[1];
+  const ucNum = m[2];
+  const ucId = d.name;
+
+  // Files sitting directly under {qc}/{UC-ID}/ mean the platform level is absent. A QC
+  // artifact carries no @trace.platform, so there is nothing to infer it from — leave them.
+  const loose = fs.readdirSync(d.abs).filter(x => !isDir(path.join(d.abs, x)));
+  if (loose.length) noPlatform.push({ ucDir: ucId, files: loose });
+
+  for (const platform of fs.readdirSync(d.abs).filter(x => isDir(path.join(d.abs, x)))) {
+    const src = path.join(d.abs, platform);
+
+    const key = `${ticket}|${platform}`;
+    if (!regen.has(key)) regen.set(key, { ticket, platform, ucs: new Set() });
+    regen.get(key).ucs.add(`UC${ucNum}`);
+
+    for (const abs of walk(src)) {
+      const within = path.relative(src, abs).replace(/\\/g, '/');
+      const base = path.basename(abs);
+
+      if (within.startsWith('test-cases/')) {
+        // Survives the merge — the filename carries <FEATURE>, and the Trace SC column
+        // is what says which UC a TC belongs to.
+        plan(abs, path.join(qcAbs, ticket, platform, within), 'test-case');
+      } else {
+        // Archive, renaming DOC_GAPS.md → DOC_GAP.md so the archive uses one name.
+        const outName = base === 'DOC_GAPS.md' ? 'DOC_GAP.md' : base;
+        const outRel = path.join(path.dirname(within), outName);
+        plan(abs, path.join(qcAbs, ARCHIVE, ucId, platform, outRel),
+          TOP_DOCS.includes(base) ? 'archive' : 'archive-other');
+      }
+    }
+  }
+}
+
+// ── second pass — DOC_GAPS.md → DOC_GAP.md for folders ALREADY in the new layout ──
+for (const abs of walk(qcAbs)) {
+  if (path.basename(abs) !== 'DOC_GAPS.md') continue;
+  if (rel(abs).includes(`/${ARCHIVE}/`)) continue;
+  if (moves.some(mv => mv.from === abs)) continue;   // already handled above
+  plan(abs, path.join(path.dirname(abs), 'DOC_GAP.md'), 'rename');
+}
+
+// ── report ────────────────────────────────────────────────────────────────────
+const pad = (s, n) => s + ' '.repeat(Math.max(0, n - s.length));
+console.log('');
+console.log('╔════════════════════════════════════════════════╗');
+console.log(`║  migrate-qc-docs  —  ${pad(APPLY ? 'APPLY' : 'DRY RUN', 25)}║`);
+console.log('╚════════════════════════════════════════════════╝');
+console.log(`Root  : ${ROOT}`);
+console.log(`QC    : ${QC}/   Git: ${tracked ? 'yes (git mv)' : 'no (fs move)'}`);
+console.log('');
+
+if (!moves.length && !noPlatform.length && !occupied.length) {
+  console.log('Nothing to migrate — no per-UC folder found, and no DOC_GAPS.md to rename.');
+  console.log(`(Scanned ${QC}/ for folders matching {TICKET-ID}-UC{N}.)`);
+  console.log('');
+  process.exit(0);
+}
+
+const byKind = k => moves.filter(m => m.kind === k);
+const show = (title, list) => {
+  if (!list.length) return;
+  console.log(`${title}  (${list.length})`);
+  for (const m of list) console.log(`  ${rel(m.from)}\n    -> ${rel(m.to)}`);
+  console.log('');
+};
+
+show('📦 MOVE — test cases (survive the merge)', byKind('test-case'));
+show('🗄  ARCHIVE — the 3 PRD-level docs (regenerate instead of merging)', byKind('archive'));
+show('🗄  ARCHIVE — other files found at that level', byKind('archive-other'));
+show('✏️  RENAME — DOC_GAPS.md -> DOC_GAP.md (B9, already-new layout)', byKind('rename'));
+
+if (noPlatform.length) {
+  console.log(`⚠️  NO PLATFORM — left in place (${noPlatform.length})`);
+  console.log('    Files sit directly under the UC folder with no web/app/system level.');
+  console.log('    A QC artifact carries no @trace.platform, so the platform cannot be');
+  console.log('    inferred — move these by hand into the right platform folder.');
+  for (const x of noPlatform) console.log(`  ${QC}/${x.ucDir}/  ->  ${x.files.join(', ')}`);
+  console.log('');
+}
+
+if (occupied.length) {
+  console.log(`❌ OCCUPIED — NOT moved, target already exists (${occupied.length})`);
+  console.log('    Moving would overwrite. Resolve by hand, then re-run.');
+  for (const x of occupied) console.log(`  ${rel(x.from)}\n    x ${rel(x.to)}`);
+  console.log('');
+}
+
+if (regen.size) {
+  console.log('🔄 NEEDS REGENERATE — run these after the move:');
+  for (const r of regen.values()) {
+    console.log(`  /qc-analyze ${r.ticket} ${r.platform}      <- was ${[...r.ucs].sort().join(' + ')}`);
+    console.log(`  /qc-plan    ${r.ticket} ${r.platform}`);
+  }
+  console.log('');
+  console.log('    The archived per-UC docs are the way back, and the only way to check');
+  console.log('    whether the PRD-level run caught cross-UC contradictions the old ones');
+  console.log('    could not see. Compare, then delete the archive when you are satisfied.');
+  console.log('');
+}
+
+if (!APPLY) {
+  console.log('DRY RUN — nothing changed. Re-run with --apply to execute.');
+  console.log('');
+  process.exit(0);
+}
+
+// ── execute ───────────────────────────────────────────────────────────────────
+function mv(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  if (isTracked(from)) execSync(`git mv -k "${rel(from)}" "${rel(to)}"`, { cwd: ROOT, stdio: ['ignore', 'ignore', 'pipe'] });
+  else fs.renameSync(from, to);
+}
+
+let moved = 0, failed = 0;
+for (const m of moves) {
+  try { mv(m.from, m.to); moved++; }
+  catch (err) {
+    console.log(`  ❌ ${rel(m.from)} — ${err.message.split('\n')[0]}`);
+    failed++;
+  }
+}
+
+// Prune folders the move emptied — deepest first, and only if genuinely empty.
+let pruned = 0;
+const dirsDeepFirst = [];
+(function collect(dir) {
+  if (!isDir(dir)) return;
+  for (const n of fs.readdirSync(dir)) collect(path.join(dir, n));
+  dirsDeepFirst.push(dir);
+})(qcAbs);
+for (const d of dirsDeepFirst) {
+  if (d === qcAbs) continue;
+  try { if (fs.readdirSync(d).length === 0) { fs.rmdirSync(d); pruned++; } } catch { /* keep */ }
+}
+
+console.log(`✅ Moved ${moved} file(s)${failed ? `, ${failed} FAILED` : ''}.`);
+console.log(`✅ Pruned ${pruned} empty folder(s).`);
+console.log('');
+console.log('Next:');
+console.log('  1. git status  — review the moves (nothing was deleted)');
+console.log('  2. Run the /qc-analyze + /qc-plan commands listed above');
+console.log(`  3. Compare against ${QC}/${ARCHIVE}/, then remove the archive when satisfied`);
+console.log('');