@educa-corp/sdd-framework 0.9.2 → 0.9.3

package/docs/04-reference/configuration.md

@@ -1,146 +1,146 @@
-[← Reference](./) · [Concepts › Architecture](../02-concepts/architecture.md)
-
-# Reference · Configuration
-
-> Hai file cấu hình chính. `/update-framework` **không** đụng chúng — đây là nội dung của bạn.
-
----
-
-## 1. `project-context.yaml`
-
-**Single source of truth** cho paths/mode/routing. Nằm ở `.agent/project-context.yaml`, sinh từ `templates/project-context.yaml` qua token substitution khi init. Mọi workflow đọc file này để biết **WHERE** tìm mọi thứ.
-
-### Cấu trúc chính
-
-```yaml
-project:
-  name: "..."
-  description: "..."
-
-paths:
-  specs_dir: "specs"                 # gốc mọi spec artifact
-  trace_dir: ".trace"                # trace state .tsv
-  qc_dir: "docs"                     # working docs của QC
-  qc_skills_dir: ".agent/skills/qc"  # nơi qc-* nạp skill (override sang repo QC riêng)
-  refinement_dir: ".agent/review"    # findings review
-
-setup:
-  mode: single | umbrella
-  spec_source: "..."                 # (umbrella) spec repo dùng chung
-
-services:                            # (multi/umbrella) map domain → service
-  # dạng phẳng: {domain}: { path, module }
-  # dạng map-theo-platform: {domain}: { web: {path,module}, app: {...}, system: {...} }
-
-conventions:
-  build_command: "..."               # lệnh build verify (≤3 retry)
-  test_command: "..."
-
-tech_stack:
-  database: "..."                    # vd PostgreSQL
-```
-
-### Bố cục feature-package (path resolution)
-
-Mọi artifact của một feature nằm chung `specs/{domain}/{prd-slug}/`:
-
-```
-specs/{domain}/{prd-slug}/
-├── {TICKET-ID}-{prd-slug}.md          # PRD (file .md duy nhất ở gốc)
-├── bdd/{web|app|system}/*.feature     # BDD — subfolder platform LUÔN có
-├── tech-docs/{TICKET-ID}-tech-design.md   # MỘT doc gộp cho cả PRD
-├── design-spec/{TICKET-ID}*.md        # FE/App
-└── changelog/{TICKET-ID}-{prd-slug}.changelog.md   # chỉ tạo khi changelog vượt 5 version
-.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv   # MỘT sổ / UC × platform (24 cột)
-.trace/{domain}/{prd-slug}/_seams.tsv               # sổ seam/stub — nguồn 2 cờ 🔴 chặn PR
-.trace/trace-report.json                            # snapshot cho panel — GHI ĐÈ mỗi lần chạy
-.trace/trace-history.jsonl                          # nhật ký append-only — PHẢI commit
-```
-
-- `{domain}` = segment đầu sau `specs_dir`.
-- `{prd-slug}` = segment kế tiếp (folder feature-package) — **không** phải folder cha trực tiếp của file lồng sâu.
-- **Segment `{platform}` không optional** — mọi mode, kể cả umbrella. `web` và `system` của cùng một UC là hai file khác nhau; bỏ segment thì chúng va tên và **ghi đè nhau**. Trace tách theo platform nên bố cục spec phải khớp.
-  *Project còn ở bố cục phẳng: `npx @educa-corp/sdd-framework --migrate-bdd-platform` (dry-run mặc định).*
-
----
-
-## 2. `CLAUDE.md` (phân tầng)
-
-Instruction cho AI agent — AI *follow* file này thay vì *invent*.
-
-| Tầng | Nội dung |
-|------|----------|
-| **root** `CLAUDE.md` | Luật chung dự án/umbrella |
-| **overlay** `{service}/CLAUDE.md` | §2 kiến trúc & thứ tự layer & package strategy · §3 coding standards · §5 error handling — **theo stack** |
-
-> Service overlay **thắng** root khi mâu thuẫn. context-loader nạp cả hai, đặt ở **cuối** context (Lost-in-the-Middle: "follow style này").
-
----
-
-## 3. Single vs Umbrella
-
-| | Single | Umbrella |
-|---|--------|----------|
-| `setup.mode` | `single` | `umbrella` |
-| Spec ở đâu | Cùng repo | **Spec repo dùng chung** (`spec_source`) |
-| Code ở đâu | Cùng repo | Service submodule (chỉ code + tooling) |
-| Trace/feedback/findings | Cùng repo | Trong spec repo (một nơi authoritative) |
-| Đồng bộ | — | `/sync` (pull + submodule + nổi feedback + Living Docs) |
-
-Khi `spec_source` được đặt, **mọi** PRD/BDD/tech-doc/design-spec/`.trace`/`.agent/review`/`feedback` route về spec repo — vì đều là **artifact liên team**.
-
----
-
-## Vùng nào bị ghi đè khi update
-
-`.agent/` là **mirror sinh ra**: `/update-framework` chạy `npx … --init`, và `--init` copy `core/` → `.agent/` **vô điều kiện**.
-
-| Đường dẫn | Sửa được? | Vì sao |
-|---|:---:|---|
-| `CLAUDE.md` | ✅ | ngoài `.agent/` |
-| `.agent/project-context.yaml` | ✅ | file **duy nhất trong `.agent/`** có guard: chỉ tạo nếu chưa tồn tại |
-| `.agent/project-lessons.md` · `.agent/review/` | ✅ | không nằm trong `core/` nên nâng cấp không đụng |
-| `specs/domain-knowledge/` · `.trace/` · `feedback/` | ✅ | ngoài `.agent/` |
-| `.agent/commands` `steps` `rules` `skills` `hooks` `templates` `modules` | ❌ | copy từ repo framework, **ghi đè mỗi lần nâng cấp** |
-
-**Nếu bạn đã sửa gì trong vùng ❌** — từ v0.4.2 `--init` tự cứu:
-
-- bản cũ copy sang `.agent/.overwritten-{version}-{YYYYMMDD}/` (giữ nguyên cây thư mục)
-- danh sách file bị ghi đè in ra ngay sau bước cài
-- `.agent/.install-manifest.json` ghi hash của **đúng những gì lần cài trước đã viết** — nhờ đó lệnh phân biệt được *bạn sửa file* với *framework tự đổi file giữa hai version* (một phép so nội dung thuần sẽ flag cả hai và báo oan hàng chục file mỗi lần nâng cấp)
-
-Thêm vào `.gitignore` của project:
-
-```gitignore
-.agent/.overwritten-*/
-.agent/.install-manifest.json
-.trace-mirror/          # bản sao cho panel VS Code — sinh lại được
-.living-docs/           # report gộp — sinh lại được  (đặt trong .gitignore của spec repo)
-```
-
-> ### ⚠️ `.trace/` **KHÔNG** được gitignore
->
-> Đây là chỗ dễ mất dữ liệu nhất trong toàn framework.
->
-> | Đường dẫn | Vai trò | Git |
-> |---|---|---|
-> | `{paths.trace_dir}` (`.trace/`) | **AUTHORITATIVE** — `.tsv` + `trace-history.jsonl`. **Không regenerate được** | **PHẢI commit** |
-> | `.trace-mirror/` | bản sao cho panel VS Code | gitignore |
-> | `.living-docs/` | report gộp | gitignore |
->
-> **Trước v0.4.3 cả hai cùng tên `.trace`.** Khi dev mở thẳng spec repo làm workspace thì hai đường dẫn **bằng nhau** — và `/sync` (bản cũ) gợi ý gitignore theo **tên**, không theo vai trò. Làm theo là **mất sổ gốc, im lặng**: máy vẫn chạy, dashboard vẫn có số; chỉ người thứ hai clone về mới phát hiện, và lúc đó lịch sử đã mất vĩnh viễn.
->
-> **Kiểm dự án đang chạy:**
-> ```bash
-> git -C {spec_source} check-ignore .trace    # trả về kết quả = ĐANG DÍNH
-> ```
-> Dính thì gỡ dòng khớp `.trace` khỏi `.gitignore` rồi `git add -f .trace && git commit`.
-> Từ v0.4.3 `/sync` Step 4b tự kiểm và báo động 🔴 nếu phát hiện.
-
-> Muốn thay đổi **bền vững** thì sửa trong repo framework rồi phát hành. Tuỳ biến riêng của một project thuộc về `CLAUDE.md`, `.agent/project-context.yaml`, hoặc `.agent/project-lessons.md` — cả ba đều không bị ghi đè. Ranh giới đầy đủ: `.agent/README.md`.
->
-> **Template `.feature`/PRD không cấu hình được.** Skeleton được `{{include}}` nướng cứng vào file lệnh lúc build, nên sửa `.agent/templates/` **không có tác dụng** (và sẽ bị ghi đè). Đổi cấu trúc artifact = sửa `templates/*` trong repo framework rồi `npm run build`. Chi tiết: `.agent/templates/README.md`.
-
----
-
-→ [Architecture › Configuration](../02-concepts/architecture.md#configuration-2-file) · [Modules](modules.md)
+[← Reference](./) · [Concepts › Architecture](../02-concepts/architecture.md)
+
+# Reference · Configuration
+
+> Hai file cấu hình chính. `/update-framework` **không** đụng chúng — đây là nội dung của bạn.
+
+---
+
+## 1. `project-context.yaml`
+
+**Single source of truth** cho paths/mode/routing. Nằm ở `.agent/project-context.yaml`, sinh từ `templates/project-context.yaml` qua token substitution khi init. Mọi workflow đọc file này để biết **WHERE** tìm mọi thứ.
+
+### Cấu trúc chính
+
+```yaml
+project:
+  name: "..."
+  description: "..."
+
+paths:
+  specs_dir: "specs"                 # gốc mọi spec artifact
+  trace_dir: ".trace"                # trace state .tsv
+  qc_dir: "docs"                     # working docs của QC — {qc_dir}/{TICKET-ID}/{platform}/
+  qc_skills_dir: ".agent/skills/qc"  # nơi qc-* nạp skill (override sang repo QC riêng)
+  refinement_dir: ".agent/review"    # findings review
+
+setup:
+  mode: single | umbrella
+  spec_source: "..."                 # (umbrella) spec repo dùng chung
+
+services:                            # (multi/umbrella) map domain → service
+  # dạng phẳng: {domain}: { path, module }
+  # dạng map-theo-platform: {domain}: { web: {path,module}, app: {...}, system: {...} }
+
+conventions:
+  build_command: "..."               # lệnh build verify (≤3 retry)
+  test_command: "..."
+
+tech_stack:
+  database: "..."                    # vd PostgreSQL
+```
+
+### Bố cục feature-package (path resolution)
+
+Mọi artifact của một feature nằm chung `specs/{domain}/{prd-slug}/`:
+
+```
+specs/{domain}/{prd-slug}/
+├── {TICKET-ID}-{prd-slug}.md          # PRD (file .md duy nhất ở gốc)
+├── bdd/{web|app|system}/*.feature     # BDD — subfolder platform LUÔN có
+├── tech-docs/{TICKET-ID}-tech-design.md   # MỘT doc gộp cho cả PRD
+├── design-spec/{TICKET-ID}*.md        # FE/App
+└── changelog/{TICKET-ID}-{prd-slug}.changelog.md   # chỉ tạo khi changelog vượt 5 version
+.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv   # MỘT sổ / UC × platform (24 cột)
+.trace/{domain}/{prd-slug}/_seams.tsv               # sổ seam/stub — nguồn 2 cờ 🔴 chặn PR
+.trace/trace-report.json                            # snapshot cho panel — GHI ĐÈ mỗi lần chạy
+.trace/trace-history.jsonl                          # nhật ký append-only — PHẢI commit
+```
+
+- `{domain}` = segment đầu sau `specs_dir`.
+- `{prd-slug}` = segment kế tiếp (folder feature-package) — **không** phải folder cha trực tiếp của file lồng sâu.
+- **Segment `{platform}` không optional** — mọi mode, kể cả umbrella. `web` và `system` của cùng một UC là hai file khác nhau; bỏ segment thì chúng va tên và **ghi đè nhau**. Trace tách theo platform nên bố cục spec phải khớp.
+  *Project còn ở bố cục phẳng: `npx @educa-corp/sdd-framework --migrate-bdd-platform` (dry-run mặc định).*
+
+---
+
+## 2. `CLAUDE.md` (phân tầng)
+
+Instruction cho AI agent — AI *follow* file này thay vì *invent*.
+
+| Tầng | Nội dung |
+|------|----------|
+| **root** `CLAUDE.md` | Luật chung dự án/umbrella |
+| **overlay** `{service}/CLAUDE.md` | §2 kiến trúc & thứ tự layer & package strategy · §3 coding standards · §5 error handling — **theo stack** |
+
+> Service overlay **thắng** root khi mâu thuẫn. context-loader nạp cả hai, đặt ở **cuối** context (Lost-in-the-Middle: "follow style này").
+
+---
+
+## 3. Single vs Umbrella
+
+| | Single | Umbrella |
+|---|--------|----------|
+| `setup.mode` | `single` | `umbrella` |
+| Spec ở đâu | Cùng repo | **Spec repo dùng chung** (`spec_source`) |
+| Code ở đâu | Cùng repo | Service submodule (chỉ code + tooling) |
+| Trace/feedback/findings | Cùng repo | Trong spec repo (một nơi authoritative) |
+| Đồng bộ | — | `/sync` (pull + submodule + nổi feedback + Living Docs) |
+
+Khi `spec_source` được đặt, **mọi** PRD/BDD/tech-doc/design-spec/`.trace`/`.agent/review`/`feedback` route về spec repo — vì đều là **artifact liên team**.
+
+---
+
+## Vùng nào bị ghi đè khi update
+
+`.agent/` là **mirror sinh ra**: `/update-framework` chạy `npx … --init`, và `--init` copy `core/` → `.agent/` **vô điều kiện**.
+
+| Đường dẫn | Sửa được? | Vì sao |
+|---|:---:|---|
+| `CLAUDE.md` | ✅ | ngoài `.agent/` |
+| `.agent/project-context.yaml` | ✅ | file **duy nhất trong `.agent/`** có guard: chỉ tạo nếu chưa tồn tại |
+| `.agent/project-lessons.md` · `.agent/review/` | ✅ | không nằm trong `core/` nên nâng cấp không đụng |
+| `specs/domain-knowledge/` · `.trace/` · `feedback/` | ✅ | ngoài `.agent/` |
+| `.agent/commands` `steps` `rules` `skills` `hooks` `templates` `modules` | ❌ | copy từ repo framework, **ghi đè mỗi lần nâng cấp** |
+
+**Nếu bạn đã sửa gì trong vùng ❌** — từ v0.4.2 `--init` tự cứu:
+
+- bản cũ copy sang `.agent/.overwritten-{version}-{YYYYMMDD}/` (giữ nguyên cây thư mục)
+- danh sách file bị ghi đè in ra ngay sau bước cài
+- `.agent/.install-manifest.json` ghi hash của **đúng những gì lần cài trước đã viết** — nhờ đó lệnh phân biệt được *bạn sửa file* với *framework tự đổi file giữa hai version* (một phép so nội dung thuần sẽ flag cả hai và báo oan hàng chục file mỗi lần nâng cấp)
+
+Thêm vào `.gitignore` của project:
+
+```gitignore
+.agent/.overwritten-*/
+.agent/.install-manifest.json
+.trace-mirror/          # bản sao cho panel VS Code — sinh lại được
+.living-docs/           # report gộp — sinh lại được  (đặt trong .gitignore của spec repo)
+```
+
+> ### ⚠️ `.trace/` **KHÔNG** được gitignore
+>
+> Đây là chỗ dễ mất dữ liệu nhất trong toàn framework.
+>
+> | Đường dẫn | Vai trò | Git |
+> |---|---|---|
+> | `{paths.trace_dir}` (`.trace/`) | **AUTHORITATIVE** — `.tsv` + `trace-history.jsonl`. **Không regenerate được** | **PHẢI commit** |
+> | `.trace-mirror/` | bản sao cho panel VS Code | gitignore |
+> | `.living-docs/` | report gộp | gitignore |
+>
+> **Trước v0.4.3 cả hai cùng tên `.trace`.** Khi dev mở thẳng spec repo làm workspace thì hai đường dẫn **bằng nhau** — và `/sync` (bản cũ) gợi ý gitignore theo **tên**, không theo vai trò. Làm theo là **mất sổ gốc, im lặng**: máy vẫn chạy, dashboard vẫn có số; chỉ người thứ hai clone về mới phát hiện, và lúc đó lịch sử đã mất vĩnh viễn.
+>
+> **Kiểm dự án đang chạy:**
+> ```bash
+> git -C {spec_source} check-ignore .trace    # trả về kết quả = ĐANG DÍNH
+> ```
+> Dính thì gỡ dòng khớp `.trace` khỏi `.gitignore` rồi `git add -f .trace && git commit`.
+> Từ v0.4.3 `/sync` Step 4b tự kiểm và báo động 🔴 nếu phát hiện.
+
+> Muốn thay đổi **bền vững** thì sửa trong repo framework rồi phát hành. Tuỳ biến riêng của một project thuộc về `CLAUDE.md`, `.agent/project-context.yaml`, hoặc `.agent/project-lessons.md` — cả ba đều không bị ghi đè. Ranh giới đầy đủ: `.agent/README.md`.
+>
+> **Template `.feature`/PRD không cấu hình được.** Skeleton được `{{include}}` nướng cứng vào file lệnh lúc build, nên sửa `.agent/templates/` **không có tác dụng** (và sẽ bị ghi đè). Đổi cấu trúc artifact = sửa `templates/*` trong repo framework rồi `npm run build`. Chi tiết: `.agent/templates/README.md`.
+
+---
+
+→ [Architecture › Configuration](../02-concepts/architecture.md#configuration-2-file) · [Modules](modules.md)

package/docs/explain/15-qc-analyze.md

@@ -26,7 +26,7 @@ QC chính thức cần hiểu yêu cầu **testable** trước khi viết test.
 
 **Input:** UC-ID + spec (PRD/BDD từ spec repo) + skill `qa-analyst`.
 
-**Output (per UC):** `{qc_dir}/{UC-ID}/{platform}/REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md`.
+**Output (per PRD × nền):** `{qc_dir}/{TICKET-ID}/{platform}/REQUIREMENT_ANALYSIS.md` + `DOC_GAP.md` (11 cột, cột 2 là `UC`) + `{refinement_dir}/{TICKET-ID}-qa-findings.yaml`. Một lần chạy phủ **mọi UC có BDD `approved`** của PRD; UC còn nháp vào bảng *Phạm vi phân tích* với dấu `⏸ Chưa xét` (`--include-draft` để xét luôn).
 
 ---
 

package/docs/explain/16-qc-plan.md

@@ -23,7 +23,7 @@ Không phải mọi scenario rủi ro ngang nhau. Trạm này xếp ưu tiên te
 
 **Input:** analysis từ trạm 1 + skill `qa-planner`.
 
-**Output:** `{qc_dir}/{UC-ID}/{platform}/TEST_PLAN.md` (rủi ro + câu hỏi cho dev).
+**Output:** `{qc_dir}/{TICKET-ID}/{platform}/TEST_PLAN.md` — **một plan cho cả PRD** (rủi ro + câu hỏi cho dev), `Ready`/`Blocked` chấm theo từng UC.
 
 ---
 

package/docs/explain/17-qc-design-test.md

@@ -22,7 +22,7 @@ Tách "thiết kế test case" (con người đọc/review được) khỏi "cod
 
 **Input:** TEST_PLAN.md + skill `qa-designer` (chọn layer, nạp MỘT file).
 
-**Output:** `{qc_dir}/{UC-ID}/{platform}/test-cases/*.Test.md` (trace mapping bắt buộc).
+**Output:** `{qc_dir}/{TICKET-ID}/{platform}/test-cases/*.Test.md` (trace mapping bắt buộc). Gọi theo **từng UC**, ghi vào thư mục test-case dùng chung cấp PRD.
 
 ---
 

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

@@ -1373,6 +1373,145 @@ 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 |
+
+---
+
 # Tổng kết
 
 | | Quyết định ở B7 | Bằng chứng | |
@@ -1415,9 +1554,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 hai bước B0–B11 đã 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.
@@ -1440,7 +1579,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 hai 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.3",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"