@educa-corp/sdd-framework 0.9.1 → 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/03-refine-prd.md

@@ -1,8 +1,8 @@
 [← /extend-prd](02b-extend-prd.md) · [Explain Home](README.md) · [Next: /review-context →](04-review-context.md)
 
-# 03 · `/refine-prd` — Tinh chỉnh PRD qua 3 lăng kính
+# 03 · `/refine-prd` — Tinh chỉnh PRD qua 4 lăng kính
 
-> **Một câu.** Fan-out review PRD qua **3 lăng kính DEV / SA / PO**, chạy **vòng lặp completeness-critic** để hội tụ đầy đủ trong một lần, rồi sinh file findings cho PO accept/reject ở Review Board.
+> **Một câu.** Fan-out review PRD qua **4 lăng kính QA / DEV / SA / PO**, chạy **vòng lặp completeness-critic** để hội tụ đầy đủ trong một lần, rồi sinh file findings cho PO accept/reject ở Review Board.
 
 ---
 
@@ -33,9 +33,10 @@ Một lượt review đơn không bao giờ liệt kê hết vấn đề — mod
 Chạy qua step **review-fanout** với tham số `GRANULARITY = per-uc`:
 
 ### Phase 1 — Fan-out song song theo dimension
-- **DIMENSIONS = 3 lăng kính** (mỗi lăng kính một sub-agent, context window mới, quét toàn PRD chỉ qua lăng kính đó):
+- **DIMENSIONS = 4 lăng kính** (mỗi lăng kính một sub-agent, context window mới, quét toàn PRD chỉ qua lăng kính đó):
   | Lăng kính | Soi gì |
   |-----------|--------|
+  | **QA** (tầng nghiệm thu) *(bật 2026-08-25)* | AC có nêu **outcome quan sát/kiểm được** chưa? AC có lặp nội dung BR (trùng tầng) không? — hỏi về **HÌNH THỨC**, KHÔNG về nội dung thiếu |
   | **DEV** (cơ chế nghiệp vụ) | BR + Business Logic đã đủ & không mơ hồ để build không phải đoán chưa? Nhánh nghiệp vụ thiếu, điều kiện biên, đường lỗi bỏ ngỏ |
   | **SA** (thông suốt & nhất quán) | Luồng nghiệp vụ thông suốt trên cả feature/domain? Tương tác UC, quan hệ entity, vòng đời trạng thái, ai-làm-gì |
   | **PO** | Scope khoanh vùng? Priority? Success metric? Rủi ro scope creep? |
@@ -66,7 +67,8 @@ Chạy qua step **review-fanout** với tham số `GRANULARITY = per-uc`:
 
 ## Cơ chế đặc biệt
 
-- **Không có `--fix` mode** (khác `/review-context`) — finding 3 lăng kính là phán đoán DEV/SA/PO, **bắt buộc qua người** ở Board; `auto_fixable` chỉ là gợi ý quick-accept.
+- **Lăng kính QA hẹp có chủ ý** — nó hỏi *"phát biểu này kiểm chứng được không?"*, KHÔNG hỏi *"còn thiếu gì?"*. Ở thời điểm PRD chỉ có PRD (design-spec/BDD/tech-doc chưa tồn tại), nên không phân biệt được *"PRD thiếu X"* với *"PRD để X cho design-spec"*. Câu hỏi nội dung thuộc `/qc-analyze`. Số liệu: review chỉ-PRD ra ~14 gap, review đủ 4 nguồn ra ~9,4 — chênh lệch là câu tài liệu sau trả lời hộ.
+- **Không có `--fix` mode** (khác `/review-context`) — finding 4 lăng kính là phán đoán QA/DEV/SA/PO, **bắt buộc qua người** ở Board; `auto_fixable` chỉ là gợi ý quick-accept.
 - **`resolution_edge_cases`** — phân tích bậc-hai (chỉ critical/major): "nếu chốt phương án này thì đẻ ra edge case gì?" → PO thấy trước khi accept (advisory, không chặn).
 - **QA lens đang DISABLED** (comment trong file) — có hướng dẫn bật lại nếu cần.
 
@@ -74,10 +76,10 @@ Chạy qua step **review-fanout** với tham số `GRANULARITY = per-uc`:
 
 ## 👓 Góc nhìn tối ưu
 
-- **Đây là command tốn agent/token nhất phía thượng nguồn** — `per-uc` × 3 lăng kính × (UC+1) + tới 3 vòng critic. `AGENT_CAP=12` là núm chỉnh chính. Với PRD lớn, đây là điểm cần cân đối chi phí ↔ độ đầy đủ.
+- **Đây là command tốn agent/token nhất phía thượng nguồn** — `per-uc` × 4 lăng kính × (UC+1) + tới 3 vòng critic. `AGENT_CAP=12` là núm chỉnh chính. Với PRD lớn, đây là điểm cần cân đối chi phí ↔ độ đầy đủ.
 - **Completeness-critic tới 3 vòng** — điểm đáng đo: thực tế hội tụ ở vòng mấy? Nếu thường 1–2 vòng thì cap 3 hợp lý.
 - **Full/delta logic phức tạp** (`applied_to_version` tracking) — mạnh nhưng nhiều nhánh; dễ rơi về FULL khi có actor khác sửa PRD (vd `/review-context` xen giữa).
-- **Ranh giới với `/review-context`** — cả hai đều review PRD, dùng chung review-fanout. `/refine-prd` = phán đoán chất lượng nghiệp vụ (3 lăng kính); `/review-context` = check có mã P0–P5 + auto-fix. Chồng lấn có chủ đích hay có thể gộp?
+- **Ranh giới với `/review-context`** — cả hai đều review PRD, dùng chung review-fanout. `/refine-prd` = phán đoán chất lượng nghiệp vụ (4 lăng kính); `/review-context` = check có mã P0–P5 + auto-fix. Chồng lấn có chủ đích hay có thể gộp?
 
 ---
 

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

@@ -2,7 +2,7 @@
 
 # 15 · `/qc-analyze` — Trạm 1: Phân rã yêu cầu + gap tài liệu
 
-> **Một câu.** Trạm đầu của dây chuyền QC: phân rã yêu cầu từ spec, map trace, và ghi **DOC_GAPS** (chỗ tài liệu thiếu để test được). Markdown-first, chưa có script.
+> **Một câu.** Trạm đầu của dây chuyền QC: phân rã yêu cầu từ spec, map trace, và ghi **DOC_GAP** (chỗ tài liệu thiếu để test được). Markdown-first, chưa có script.
 
 > 🏭 **Dây chuyền QC 6 trạm** dùng module `qc-playwright` và **QC skill** nạp từ `paths.qc_skills_dir` — mặc định bundled `.agent/skills/qc`, **override sang repo riêng của team QC** để nâng cấp framework không ghi đè (QC skill tiến hoá độc lập).
 
@@ -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_GAPS.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).
 
 ---
 
@@ -36,14 +36,17 @@ QC chính thức cần hiểu yêu cầu **testable** trước khi viết test.
 2. **Platform Resolution** — chốt 1 platform cho toàn QC pass (sổ trace ghi `qc_status` sẽ là `{UC-ID}-{platform}.tsv`).
 3. **Role qa-analyst** — nạp skill `{qc_skills_dir}/qa-analyst/`.
 4. **Trace mapping (bắt buộc)** — map yêu cầu ↔ scenario ↔ SC.
-5. **DOC_GAPS (bắt buộc)** — ghi chỗ tài liệu thiếu/mơ hồ chặn test (blocker 🔴 xử trước ở `/qc-plan`).
-6. **Output** REQUIREMENT_ANALYSIS.md + DOC_GAPS.md.
+5. **DOC_GAP (bắt buộc)** — ghi chỗ tài liệu thiếu/mơ hồ chặn test (blocker 🔴 xử trước ở `/qc-plan`).
+6. **Output** REQUIREMENT_ANALYSIS.md + DOC_GAP.md.
 
 ---
 
 ## Checkpoint & Gate
 
-- Guard mềm (BDD approved). Không gate chặn.
+- **CHECKPOINT: chặn thường** — lệnh ghi 2 file artifact. `--yes` bỏ qua được.
+- Guard mềm (BDD approved) — cảnh báo, không chặn cứng; `--yes` coi như Y nhưng **vẫn in cảnh báo**.
+- **Platform Resolution chạy TRƯỚC Guard** (sửa 2026-08-25): UC đa nền có nhiều `.feature`, mỗi bản
+  mang `@trace.status` riêng — kiểm duyệt trước khi biết platform là kiểm nhầm bản.
 
 ---
 
@@ -51,13 +54,13 @@ QC chính thức cần hiểu yêu cầu **testable** trước khi viết test.
 
 - **QC skill từ repo riêng** (`qc_skills_dir`) — QC team sở hữu, không bị framework upgrade ghi đè.
 - **Platform khoá một lần** cho cả pass → nhất quán sổ trace.
-- **DOC_GAPS** — kênh QC phản hồi ngược chất lượng tài liệu (song song `/report-bug`).
+- **DOC_GAP** — kênh QC phản hồi ngược chất lượng tài liệu (song song `/report-bug`).
 
 ---
 
 ## 👓 Góc nhìn tối ưu
 
-- **DOC_GAPS trùng vai với review-context B-check?** — cả hai bắt gap tài liệu, nhưng QC nhìn từ góc "test được không". Đáng xem có nối được feedback này về spec.
+- **DOC_GAP trùng vai với review-context B-check?** — cả hai bắt gap tài liệu, nhưng QC nhìn từ góc "test được không". Đáng xem có nối được feedback này về spec.
 - **Platform một pass** — feature multi-platform phải chạy QC pass nhiều lần. Chi phí lặp phân tích.
 - **Phụ thuộc QC skill ngoài** — nếu `qc_skills_dir` trỏ sai/thiếu, trạm hụt logic.
 

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

@@ -15,7 +15,7 @@ Không phải mọi scenario rủi ro ngang nhau. Trạm này xếp ưu tiên te
 ## Vị trí & tiền đề
 
 - **Vị trí:** Phase QC (trạm 2), sau `/qc-analyze`.
-- **Tiền đề:** REQUIREMENT_ANALYSIS.md + DOC_GAPS.md; nên xử blocker 🔴 trước.
+- **Tiền đề:** REQUIREMENT_ANALYSIS.md + DOC_GAP.md; nên xử blocker 🔴 trước.
 
 ---
 
@@ -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.
 
 ---
 
@@ -52,7 +52,7 @@ Không phải mọi scenario rủi ro ngang nhau. Trạm này xếp ưu tiên te
 ## 👓 Góc nhìn tối ưu
 
 - **Trạm mỏng nhất** (~thin orchestrator + skill). Giá trị phụ thuộc chất lượng skill qa-planner.
-- **Câu hỏi cho dev** không có cơ chế theo dõi trả lời — dễ rơi. Cân nhắc gắn vào DOC_GAPS/feedback.
+- **Câu hỏi cho dev** không có cơ chế theo dõi trả lời — dễ rơi. Cân nhắc gắn vào DOC_GAP/feedback.
 
 ---
 

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.
 
 ---