@educa-corp/sdd-framework 0.9.3 → 0.9.4

package/core/commands/qc-review.md

@@ -174,126 +174,13 @@ placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
 
 ## Phạm vi QC
 
-# QC Scope — phân giải phạm vi cho mọi lệnh `qc-*`
-
-**Chạy TRƯỚC phần logic riêng của lệnh, và SAU `steps/gate.md`.** Bước này chốt bốn thứ mà
-cả 6 trạm QC đều cần, để chúng không tự suy mỗi trạm một kiểu:
-
-| Biến | Là gì |
-|---|---|
-| `TICKET-ID` | mã PRD — **thư mục artifact QC mang tên này** |
-| `active_platform` | `web` \| `app` \| `system` \| … — một QC pass khoá đúng MỘT nền |
-| `qc_artifact_dir` | `{paths.qc_dir}/{TICKET-ID}/{active_platform}/` |
-| `uc_list` | các UC của (PRD × nền) này, kèm trạng thái BDD từng UC |
-
-> **Vì sao gom về một chỗ.** Luật phân giải nền từng được copy-paste ở 5 lệnh và câu chữ đã
-> lệch nhau. Năm bản của một luật là nơi drift sống: sửa bốn, quên một, và trạm bị quên ghi
-> artifact vào sai thư mục **trong im lặng**.
-
----
-
-## 1 — `TICKET-ID`
-
-Artifact QC gom theo **PRD**, không theo UC. Nên mọi trạm phải quy được về `TICKET-ID`:
-
-| `$ARGUMENTS` là | Cách lấy |
-|---|---|
-| **UC-ID** (`{TICKET-ID}-UC{N}`) | phần **trước** `-UC` — đúng luật `steps/gate.md` Bước 1 dùng để tìm tech-doc gộp |
-| **TICKET-ID** | dùng trực tiếp |
-| một **path file** (`.feature` / PRD / design-spec) | phân giải `{domain}` + `{prd-slug}` theo luật `context-loader` Bước 1, rồi lấy `TICKET-ID` từ tên file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder |
-
-Đối chiếu: `TICKET-ID` suy ra phải khớp tên file PRD thật. Lệch → **DỪNG**, in cả hai giá
-trị. (Suy sai `TICKET-ID` là ghi cả một PRD vào sai thư mục — không có bước nào phía sau bắt được.)
-
----
-
-## 2 — `active_platform`
-
-> **PHẢI phân giải TRƯỚC mọi phép đọc `.feature`.** `{UC-ID}-SC{N}` chỉ độc nhất trong
-> (UC × nền), nên một UC đa nền có **nhiều file `.feature`** — `bdd/web/`, `bdd/app/`,
-> `bdd/system/` — và mỗi file mang `@trace.status` **riêng**: bản web có thể `approved`
-> trong khi bản app còn `draft`. Đọc "file `.feature` của UC" khi chưa biết nền là đọc một
-> file **bất kỳ trong ba**: báo `approved` trong khi bản đang dùng còn nháp, hoặc chặn oan
-> một bản đã duyệt.
-
-Theo thứ tự, dừng ở cái đầu tiên khớp:
-
-1. `$ARGUMENTS` nêu nền (`web`/`app`/`system`/…) → dùng.
-2. Target là một file `.feature` → đọc `# @trace.platform` của nó.
-3. Glob `{paths.specs_dir}/{domain}/{prd-slug}/bdd/*/` — **đúng một** thư mục nền → dùng nó.
-4. Glob `{paths.qc_dir}/{TICKET-ID}/*/` — **đúng một** thư mục nền đã có artifact → dùng nó.
-   *(chỉ dùng cho trạm 2–6; trạm `/qc-analyze` là trạm tạo ra thư mục đó nên không có gì để soi.)*
-5. Nhiều nền mà không suy được → hỏi *"QC pass này cho nền nào? (web/app/system)"*.
-   **Có `--yes`:** không hỏi — DỪNG với lỗi rõ ràng, vì đoán bừa nền là ghi artifact vào sai
-   thư mục và ghi `qc_status` vào sai sổ trace:
-   ```
-   ❌ {TICKET-ID} có {n} nền ({list}) — không suy được nền nào cho QC pass này.
-      Chạy headless thì phải nêu tường minh: /{lệnh} {TICKET-ID} web --yes
-   ```
-
-Lưu `active_platform`. Từ đây, **mọi** phép đọc `.feature` chỉ đọc thư mục
-`bdd/{active_platform}/` — không trộn SC chéo nền.
-
----
-
-## 3 — `qc_artifact_dir`
-
-```
-qc_artifact_dir = {paths.qc_dir}/{TICKET-ID}/{active_platform}/
-```
-
-Chứa: `REQUIREMENT_ANALYSIS.md` · `DOC_GAP.md` · `TEST_PLAN.md` · `test-cases/*.Test.md`
-— **mỗi loại đúng MỘT file cho cả PRD**, các UC là mục/hàng bên trong.
-
-`{paths.qc_dir}` là folder top-level **nhìn thấy** trong repo QC (mặc định `docs/`, **không**
-phải `.agent/` ẩn) để đội QC mở và xử lý output dễ dàng. Spec chính thức ở lại spec submodule
-của PO — đừng ghi artifact QC vào đó.
-
-> **Sổ trace KHÔNG theo layout này.** Nó vẫn là `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv`
-> — một sổ cho mỗi (UC × nền), vì mỗi hàng là một scenario. Liên kết giữa hai bên đi qua
-> **cột `UC`** của bảng gap, không qua đường dẫn file.
-
----
-
-## 4 — `uc_list`
-
-Glob `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/*.feature`. Mỗi file → một
-UC: đọc `# @trace.id` (mã UC) và `# @trace.status` từ header.
-
-Chia hai nhóm:
-
-| Nhóm | Điều kiện | Xử lý |
-|---|---|---|
-| **Trong phạm vi** | `@trace.status: approved` | phân tích / thiết kế / chạy bình thường |
-| **Chưa xét** | khác `approved` | **KHÔNG** phân tích; vẫn ghi một hàng vào bảng phạm vi kèm trạng thái thật |
-
-In bảng phạm vi ra trước khi làm gì:
-```
-Phạm vi QC — {TICKET-ID} / {active_platform}
-  ✅ {UC-ID}  {tên UC}                     approved
-  ⏸  {UC-ID}  {tên UC}                     draft   → chưa xét
-  → {n} UC trong phạm vi · {m} chưa xét
-```
-
-**Cờ `--include-draft`:** phân tích cả UC chưa duyệt, nhưng **vẫn in bảng trên** và đánh dấu
-trong artifact là dựa trên BDD nháp.
-
-**Không UC nào `approved` và không có `--include-draft` → DỪNG:**
-```
-❌ {TICKET-ID} ({active_platform}): 0/{n} UC có BDD approved — không có gì để chạy.
-   Cách đúng: người duyệt đặt `# @trace.status: approved` rồi chạy lại.
-   Muốn chạy sớm trên BDD nháp (prototype): thêm --include-draft
-```
-
-> **Vì sao có `--include-draft` chứ không chặn cứng.** QC sớm trên BDD nháp là một cách dùng
-> **cố ý được cho phép** từ trước (guard cũ là cảnh báo mềm, không phải chặn). Bỏ hẳn nó là
-> lấy đi một năng lực đang có mà không ai khai. Còn để mặc định `approved`-only thì cái
-> thường gặp là cái an toàn, và cái sớm phải nói ra.
-
-> **Vì sao `--yes` không thay được `--include-draft`.** `--yes` nghĩa *"tôi không ngồi đây để
-> trả lời"*; `--include-draft` nghĩa *"tôi biết BDD còn nháp và vẫn muốn chạy"*. Gộp hai cái
-> là để một lần chạy headless âm thầm phân tích spec chưa chốt rồi bàn giao như thể đã chốt.
+**BẮT BUỘC — đọc `.agent/steps/qc-scope.md` và thực thi TOÀN BỘ quy trình trong đó**,
+rồi mới tiếp tục phần bên dưới.
 
+Nó chốt bốn thứ mà mọi trạm QC đều cần: `TICKET-ID` · `active_platform` ·
+`qc_artifact_dir` · `uc_list` (kèm trạng thái BDD từng UC, và cờ `--include-draft`).
+Bỏ qua thì artifact QC ghi vào **sai thư mục** và `qc_status` ghi vào **sai sổ trace** —
+cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắt được.
 
 > **Trạm này vẫn gọi theo TỪNG UC** *(B11)* — thiết kế và chạy test **thật sự** làm tăng dần
 > theo UC, nên giữ khả năng làm UC1 khi UC3 chưa xong là đúng. Chỉ **chỗ đọc/ghi** đổi: mọi
@@ -318,16 +205,61 @@ tồn tại cho UC và mới hơn → review script. Nếu mơ hồ, hỏi.
 
 ## Skills (`{paths.qc_skills_dir}/qa-reviewer/`)
 
-Chọn theo mode + layer, nạp MỘT file:
-- Review test-case: `test-case/{functional,e2e,integration,non-functional,exploratory}.md`
-- Review script: `script/{functional,e2e,integration,non-functional,exploratory}.md`
+**Nạp trước — nhưng đúng vai:**
+
+| File | Vai nào | Cho gì |
+|---|---|---|
+| `shared/read-doc-gap-inputs.md` | **cả hai** | Nạp **đủ** mọi tài liệu nguồn theo bảng *Tài liệu đầu vào đã đọc* của `DOC_GAP.md` — soát mù thì kết luận "0 lỗi" là vô nghĩa |
+| `shared/review-file-template.md` | **cả hai** | Khuôn file kết quả · thang điểm `XX/100` · luật ghi file · nguyên tắc *mặc định hoài nghi* |
+| ↳ §*Kiểm tra cấu trúc TC* của file đó | **chỉ vai 1** | Tầng kiểm các luật của trạm 3: ATOMIC 1-bullet · không ký tự `\|` · cụm từ mơ hồ · teardown đúng chỗ · marker ≠ oracle |
+| `shared/review-check-groups.md` | **chỉ vai 1** | **7 nhóm kiểm tra** chạy tuần tự · registry 46 nhãn lỗi · **7 mẫu-hay-thiếu** của Nhóm 6 · nền tảng ISTQB · anti-pattern |
+
+> ⚠️ **Vai 2 (soát code) KHÔNG nạp 7 nhóm kiểm tra.** Chúng kiểm **cấu trúc file test case** —
+> áp vào file Python là bảo reviewer đi tìm `#### Expected Result` trong một Page Object, rồi
+> gắn nhãn lỗi cho thứ đáng lẽ không có ở đó. Vai 2 dùng bộ tiêu chí riêng ở `script/*.md`.
+
+**Rồi chọn theo vai + tầng, nạp MỘT file:**
+- Soát test-case: `test-case/{functional,e2e,integration,non-functional,exploratory}.md`
+- Soát script: `script/{functional,e2e,integration,non-functional,exploratory}.md`
 
 ## Review focus
 
 - **Test-case:** mọi `{UC-ID}-SC{N}` đã phủ? happy + negative + boundary? expected cụ thể? trace (`BR-xx` + `@trace.verifies` SC) có mặt? không có TC orphan?
 - **Script:** khớp `.Test.md` 1-1? Page Object 3 lớp + BasePage gọn? `expect()` không phải bare assert? không hard-code URL/cred/timeout, không `time.sleep`, không Allure? selector theo priority (data-testid→role→…)? 100% TC đã script (không còn Draft)?
 
-Sinh findings (severity + vị trí + fix). Verdict APPROVED hoặc NEEDS_FIX.
+Sinh findings (mức độ + vị trí + cách sửa), chấm điểm, ra verdict.
+
+**KHÔNG tự sửa** file TC hay code. Chỉ nhận xét và chấm điểm — người sửa là `/qc-design-test`
+(vai 1) hoặc `/qc-run-test` (vai 2). *Reviewer tự sửa rồi tự duyệt là bỏ mất cái cổng.*
+
+## Output
+
+Ghi vào **`{qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md`** — đứng **cạnh** file TC vừa soát:
+
+```
+{qc_artifact_dir}test-cases/
+├── TC_<FEATURE>.Test.md
+├── REVIEW_<FEATURE>.md            ← soát file trên
+├── TC_<FEATURE>_API.Test.md
+└── REVIEW_<FEATURE>_API.md        ← soát file trên
+```
+
+⚠️ **Tên file review KHÔNG có đuôi `.Test.md`.** Đuôi đó là của file test case; gắn vào file
+review sẽ làm `/qc-run-test` nhặt nó lên như một file test case rồi cố sinh script từ một bảng điểm.
+
+Khuôn đầy đủ + quy tắc ghi: `shared/review-file-template.md`. Ba điều bắt buộc:
+
+- **Điểm `XX/100`** — trừ 5đ mỗi `FAIL`, 2đ mỗi `WARN`. Verdict **suy ra được**:
+  `≥80` VÀ không còn `FAIL` chặn → `APPROVED`; ngược lại `NEEDS_FIX`.
+- **Bảng Tổng quan THÊM một hàng mỗi vòng**, không ghi đè — đó là cách duy nhất thấy được điểm
+  có tăng không. Các bảng chi tiết thì ghi đè phần của tầng mình.
+- **Hai vai ghi vào CÙNG một file**, phân biệt bằng cột `Tầng`. Chúng cách nhau một trạm, nên
+  hàng của vai sau **không được ghi đè** hàng của vai trước.
+
+> **Vì sao cổng này phải ghi ra file** *(B13)*. Trước đây lệnh chỉ nói *"sinh findings"* — không
+> nói ghi đâu, dạng gì, và điểm là `A/B/C/D` **không có luật chấm**. Hệ quả: hai người soát ra
+> hai kết quả, và **vòng 2 không so được với vòng 1** — tức không ai biết sửa xong có tốt lên
+> không. Một cổng không để lại dấu vết đo được thì không phải cổng, nó là một lượt đọc.
 
 ## Report
 
@@ -335,8 +267,10 @@ Sinh findings (severity + vị trí + fix). Verdict APPROVED hoặc NEEDS_FIX.
 Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
 
 ```
-/qc-review Hoàn tất — {UC-ID} ({test-case | script} review)
-Verdict: {APPROVED | NEEDS_FIX} — {N} findings ({crit} critical)
+/qc-review Hoàn tất — {UC-ID} ({soát test-case | soát script}) vòng #{N}
+Điểm  : {XX}/100  ({fail} FAIL × −5đ · {warn} WARN × −2đ){nếu có vòng trước: "   ← vòng #{N-1}: {YY}/100"}
+Verdict: {APPROVED | NEEDS_FIX} — {n} findings ({crit} chặn)
+File  : {qc_artifact_dir}test-cases/REVIEW_<FEATURE>.md (thêm 1 hàng vào bảng Tổng quan)
 Next (test-case APPROVED): /qc-run-test {UC-ID}
 Next (script APPROVED)   : /qc-report {UC-ID}  rồi tạo PR
      (NEEDS_FIX → fix artifact bị gắn cờ, rồi chạy lại /qc-review {UC-ID})

package/core/commands/qc-run-test.md

@@ -174,126 +174,13 @@ placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
 
 ## Phạm vi QC
 
-# QC Scope — phân giải phạm vi cho mọi lệnh `qc-*`
-
-**Chạy TRƯỚC phần logic riêng của lệnh, và SAU `steps/gate.md`.** Bước này chốt bốn thứ mà
-cả 6 trạm QC đều cần, để chúng không tự suy mỗi trạm một kiểu:
-
-| Biến | Là gì |
-|---|---|
-| `TICKET-ID` | mã PRD — **thư mục artifact QC mang tên này** |
-| `active_platform` | `web` \| `app` \| `system` \| … — một QC pass khoá đúng MỘT nền |
-| `qc_artifact_dir` | `{paths.qc_dir}/{TICKET-ID}/{active_platform}/` |
-| `uc_list` | các UC của (PRD × nền) này, kèm trạng thái BDD từng UC |
-
-> **Vì sao gom về một chỗ.** Luật phân giải nền từng được copy-paste ở 5 lệnh và câu chữ đã
-> lệch nhau. Năm bản của một luật là nơi drift sống: sửa bốn, quên một, và trạm bị quên ghi
-> artifact vào sai thư mục **trong im lặng**.
-
----
-
-## 1 — `TICKET-ID`
-
-Artifact QC gom theo **PRD**, không theo UC. Nên mọi trạm phải quy được về `TICKET-ID`:
-
-| `$ARGUMENTS` là | Cách lấy |
-|---|---|
-| **UC-ID** (`{TICKET-ID}-UC{N}`) | phần **trước** `-UC` — đúng luật `steps/gate.md` Bước 1 dùng để tìm tech-doc gộp |
-| **TICKET-ID** | dùng trực tiếp |
-| một **path file** (`.feature` / PRD / design-spec) | phân giải `{domain}` + `{prd-slug}` theo luật `context-loader` Bước 1, rồi lấy `TICKET-ID` từ tên file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder |
-
-Đối chiếu: `TICKET-ID` suy ra phải khớp tên file PRD thật. Lệch → **DỪNG**, in cả hai giá
-trị. (Suy sai `TICKET-ID` là ghi cả một PRD vào sai thư mục — không có bước nào phía sau bắt được.)
-
----
-
-## 2 — `active_platform`
-
-> **PHẢI phân giải TRƯỚC mọi phép đọc `.feature`.** `{UC-ID}-SC{N}` chỉ độc nhất trong
-> (UC × nền), nên một UC đa nền có **nhiều file `.feature`** — `bdd/web/`, `bdd/app/`,
-> `bdd/system/` — và mỗi file mang `@trace.status` **riêng**: bản web có thể `approved`
-> trong khi bản app còn `draft`. Đọc "file `.feature` của UC" khi chưa biết nền là đọc một
-> file **bất kỳ trong ba**: báo `approved` trong khi bản đang dùng còn nháp, hoặc chặn oan
-> một bản đã duyệt.
-
-Theo thứ tự, dừng ở cái đầu tiên khớp:
-
-1. `$ARGUMENTS` nêu nền (`web`/`app`/`system`/…) → dùng.
-2. Target là một file `.feature` → đọc `# @trace.platform` của nó.
-3. Glob `{paths.specs_dir}/{domain}/{prd-slug}/bdd/*/` — **đúng một** thư mục nền → dùng nó.
-4. Glob `{paths.qc_dir}/{TICKET-ID}/*/` — **đúng một** thư mục nền đã có artifact → dùng nó.
-   *(chỉ dùng cho trạm 2–6; trạm `/qc-analyze` là trạm tạo ra thư mục đó nên không có gì để soi.)*
-5. Nhiều nền mà không suy được → hỏi *"QC pass này cho nền nào? (web/app/system)"*.
-   **Có `--yes`:** không hỏi — DỪNG với lỗi rõ ràng, vì đoán bừa nền là ghi artifact vào sai
-   thư mục và ghi `qc_status` vào sai sổ trace:
-   ```
-   ❌ {TICKET-ID} có {n} nền ({list}) — không suy được nền nào cho QC pass này.
-      Chạy headless thì phải nêu tường minh: /{lệnh} {TICKET-ID} web --yes
-   ```
-
-Lưu `active_platform`. Từ đây, **mọi** phép đọc `.feature` chỉ đọc thư mục
-`bdd/{active_platform}/` — không trộn SC chéo nền.
-
----
-
-## 3 — `qc_artifact_dir`
-
-```
-qc_artifact_dir = {paths.qc_dir}/{TICKET-ID}/{active_platform}/
-```
-
-Chứa: `REQUIREMENT_ANALYSIS.md` · `DOC_GAP.md` · `TEST_PLAN.md` · `test-cases/*.Test.md`
-— **mỗi loại đúng MỘT file cho cả PRD**, các UC là mục/hàng bên trong.
-
-`{paths.qc_dir}` là folder top-level **nhìn thấy** trong repo QC (mặc định `docs/`, **không**
-phải `.agent/` ẩn) để đội QC mở và xử lý output dễ dàng. Spec chính thức ở lại spec submodule
-của PO — đừng ghi artifact QC vào đó.
-
-> **Sổ trace KHÔNG theo layout này.** Nó vẫn là `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{active_platform}.tsv`
-> — một sổ cho mỗi (UC × nền), vì mỗi hàng là một scenario. Liên kết giữa hai bên đi qua
-> **cột `UC`** của bảng gap, không qua đường dẫn file.
-
----
-
-## 4 — `uc_list`
-
-Glob `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/*.feature`. Mỗi file → một
-UC: đọc `# @trace.id` (mã UC) và `# @trace.status` từ header.
-
-Chia hai nhóm:
-
-| Nhóm | Điều kiện | Xử lý |
-|---|---|---|
-| **Trong phạm vi** | `@trace.status: approved` | phân tích / thiết kế / chạy bình thường |
-| **Chưa xét** | khác `approved` | **KHÔNG** phân tích; vẫn ghi một hàng vào bảng phạm vi kèm trạng thái thật |
-
-In bảng phạm vi ra trước khi làm gì:
-```
-Phạm vi QC — {TICKET-ID} / {active_platform}
-  ✅ {UC-ID}  {tên UC}                     approved
-  ⏸  {UC-ID}  {tên UC}                     draft   → chưa xét
-  → {n} UC trong phạm vi · {m} chưa xét
-```
-
-**Cờ `--include-draft`:** phân tích cả UC chưa duyệt, nhưng **vẫn in bảng trên** và đánh dấu
-trong artifact là dựa trên BDD nháp.
-
-**Không UC nào `approved` và không có `--include-draft` → DỪNG:**
-```
-❌ {TICKET-ID} ({active_platform}): 0/{n} UC có BDD approved — không có gì để chạy.
-   Cách đúng: người duyệt đặt `# @trace.status: approved` rồi chạy lại.
-   Muốn chạy sớm trên BDD nháp (prototype): thêm --include-draft
-```
-
-> **Vì sao có `--include-draft` chứ không chặn cứng.** QC sớm trên BDD nháp là một cách dùng
-> **cố ý được cho phép** từ trước (guard cũ là cảnh báo mềm, không phải chặn). Bỏ hẳn nó là
-> lấy đi một năng lực đang có mà không ai khai. Còn để mặc định `approved`-only thì cái
-> thường gặp là cái an toàn, và cái sớm phải nói ra.
-
-> **Vì sao `--yes` không thay được `--include-draft`.** `--yes` nghĩa *"tôi không ngồi đây để
-> trả lời"*; `--include-draft` nghĩa *"tôi biết BDD còn nháp và vẫn muốn chạy"*. Gộp hai cái
-> là để một lần chạy headless âm thầm phân tích spec chưa chốt rồi bàn giao như thể đã chốt.
+**BẮT BUỘC — đọc `.agent/steps/qc-scope.md` và thực thi TOÀN BỘ quy trình trong đó**,
+rồi mới tiếp tục phần bên dưới.
 
+Nó chốt bốn thứ mà mọi trạm QC đều cần: `TICKET-ID` · `active_platform` ·
+`qc_artifact_dir` · `uc_list` (kèm trạng thái BDD từng UC, và cờ `--include-draft`).
+Bỏ qua thì artifact QC ghi vào **sai thư mục** và `qc_status` ghi vào **sai sổ trace** —
+cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắt được.
 
 > **Trạm này vẫn gọi theo TỪNG UC** *(B11)* — thiết kế và chạy test **thật sự** làm tăng dần
 > theo UC, nên giữ khả năng làm UC1 khi UC3 chưa xong là đúng. Chỉ **chỗ đọc/ghi** đổi: mọi

package/core/commands/setup-ai-first.md

@@ -448,13 +448,13 @@ Hướng dẫn: "Mở `specs/domain-knowledge/core-entities.md` và định ngh
 
 ## Step 6 — Cài VS Code Extension (Khuyến nghị)
 
-Khuyến nghị user cài extension VS Code **Spec Driven Docs Tools** — nó cung cấp panel Review Board + Living Documentation tích hợp với workflow này.
+Khuyến nghị user cài extension VS Code **SDD Board** — nó cung cấp panel Review Board + Living Documentation tích hợp với workflow này.
 
 ```bash
-code --install-extension SpecDrivenDocsTools.spec-driven-docs-tool
+code --install-extension EducaCorp.sdd-board
 ```
 
-Hoặc: VS Code → `Ctrl+Shift+P` → **"Extensions: Install from Marketplace"** → tìm **Spec Driven Docs Tools**.
+Hoặc: VS Code → `Ctrl+Shift+P` → **"Extensions: Install from Marketplace"** → tìm **SDD Board**.
 
 **Nó làm gì:**
 - 📋 **Review Board** — UI trực quan để review findings từ `/refine-prd`, `/review-context`, `/review-tech-docs`
@@ -557,7 +557,7 @@ Next:
   4. Điền specs/domain-knowledge/core-entities.md
   5. git add và commit 4 file đó
   6. Cài VS Code extension:
-     code --install-extension SpecDrivenDocsTools.spec-driven-docs-tool
+     code --install-extension EducaCorp.sdd-board
   7. /define-product để bắt đầu feature đầu tiên
 ```
 
@@ -591,7 +591,7 @@ Next:
   3. Điền specs/domain-knowledge/core-entities.md        ← entity glossary
   4. git add và commit các file đó
   5. Cài VS Code extension:
-     code --install-extension SpecDrivenDocsTools.spec-driven-docs-tool
+     code --install-extension EducaCorp.sdd-board
   6. /define-product để bắt đầu feature đầu tiên
 
 ⚠️  Nhắc handoff team dev:

package/core/commands/update-framework.md

@@ -193,7 +193,7 @@ Your content was preserved:
 Review & commit:
    git diff .agent/
    git add .agent/ .claude/commands/
-   git commit -m "chore: upgrade spec-driven-docs v{current} → v{latest}"
+   git commit -m "chore: upgrade sdd-framework v{current} → v{latest}"
    {umbrella mode: this is the umbrella root — service submodules need no framework update}
 
 ---

package/core/commands/validate-traces.md

@@ -1223,7 +1223,7 @@ Schema:
 - `test_classes`: dùng `[]` (không phải `"—"`) khi không có test class
 - `tech_doc_revision` / `fe_tech_doc_revision`: dùng integer; `0` nếu chưa sinh
 - `code_coverage_pct` / `test_coverage_pct`: làm tròn về integer gần nhất (0–100)
-- **`status` trong JSON CỐ TÌNH chỉ có 4 giá trị** `OK`/`DRIFT`/`GAP`/`UNTRACKED` — KHÔNG ghi `ORPHANED` vào field này. VS Code extension "Spec Driven Docs Tools" (sống **ngoài** repo này) switch trên `status`; thêm giá trị thứ 5 sẽ rơi vào nhánh không khớp và có thể làm row mất khỏi panel.
+- **`status` trong JSON CỐ TÌNH chỉ có 4 giá trị** `OK`/`DRIFT`/`GAP`/`UNTRACKED` — KHÔNG ghi `ORPHANED` vào field này. VS Code extension "SDD Board" (sống **ngoài** repo này) switch trên `status`; thêm giá trị thứ 5 sẽ rơi vào nhánh không khớp và có thể làm row mất khỏi panel.
   Row `ORPHANED` xuất ra JSON là: `"status": "DRIFT"` + `"orphaned": true`. Panel chưa hỗ trợ vẫn hiện nó như `DRIFT` — đủ đúng về nghĩa ("code không khớp spec, cần xử lý") và **không im lặng**; panel có đọc `orphaned` thì hiện nhãn riêng. Chi tiết đầy đủ luôn có ở `orphaned[]` và ở report terminal.
   **TSV giữ nguyên chữ `ORPHANED`** trong cột `status` — TSV là nguồn-sự-thật, JSON chỉ là bản xuất cho panel.
 - `orphaned` (boolean): `true` chỉ khi cột `status` của TSV là `ORPHANED`; mọi row khác ghi `false` (đừng bỏ trống — panel đọc field vắng dễ ra `undefined`).

package/core/rules/workflow.md

@@ -1,6 +1,6 @@
 # Workflow Rules
 
-> General AI behavior rules for all spec-driven-docs commands.
+> General AI behavior rules for all SDD Framework commands.
 > Loaded by `steps/context-loader.md` at the start of every command.
 
 ---

package/core/skills/qc/qa-analyst/DOC_GAP.template.md

@@ -129,7 +129,7 @@ Trước khi lưu file gap, kiểm tra **từng hàng** trong bảng gap:
 - [ ] **Có section `Phạm vi phân tích`** – bảng mỗi UC một hàng kèm `@trace.status` + Đã phân tích? + Số gap. UC chưa duyệt vẫn có hàng, ghi `⏸ Chưa xét`. Thiếu bảng này thì không ai phân biệt được *"đã xét, không thấy gap"* với *"chưa xét"*.
 - [ ] **11 cột đủ** – đúng thứ tự: `ID | UC | Loại | Vấn đề cần confirm | Câu hỏi / Lý do cần confirm & Gợi ý | Trích đoạn tài liệu (Evidence) | Giao cho đội | Mức độ | Người trả lời | Trạng thái | Câu trả lời`
 - [ ] **Cột 2 = `UC`** – mã UC đầy đủ (`<TICKET-ID>-UC{N}`), hoặc `— (toàn PRD)` cho gap `GAP-GEN-`. Mọi UC có gap phải khớp một hàng `✅` ở bảng *Phạm vi phân tích*.
-- [ ] **ID dạng `GAP-UC{N}-{nnn}`** (hoặc `GAP-GEN-{nnn}`) – KHÔNG dùng `GAP-01` phẳng: số phẳng sẽ bị đánh lại khi phân tích lại một UC, làm đứt `🚫 Block: [GAP-xx]` trong test case đã có.
+- [ ] **ID dạng `GAP-UC{N}-{nnn}`** (hoặc `GAP-GEN-{nnn}`) – KHÔNG dùng `GAP-01` phẳng: số phẳng sẽ bị đánh lại khi phân tích lại một UC, làm đứt `🚫 Block: [GAP-UC1-001]` trong test case đã có.
 - [ ] **Cột 4 = `Vấn đề cần confirm`** – KHÔNG viết tắt thành `Vấn đề`
 - [ ] **Cột 5 = `Câu hỏi / Lý do cần confirm & Gợi ý`** – bắt buộc có đủ 4 phần, tách bằng `<br/>`:
   ```

package/core/skills/qc/qa-analyst/spec-breakdown.md

@@ -29,7 +29,7 @@ Bóc tách spec/PRD/user story thô thành mô tả yêu cầu có cấu trúc c
    vào phân tích/BR/AC. Với file Confluence/HTML/MHTML: phát hiện qua thẻ `<s>`,
    `<strike>`, `<del>` hoặc style `text-decoration: line-through`.
 3. Xác định: feature name, actor/role, mục tiêu nghiệp vụ, phạm vi (in/out scope).
-4. Đánh dấu phần MƠ HỒ / THIẾU → ghi vào `DOC_GAP.md` (gap GAP-xx).
+4. Đánh dấu phần MƠ HỒ / THIẾU → ghi vào `DOC_GAP.md` (gap `GAP-UC{N}-{nnn}`; gap thuộc cả PRD → `GAP-GEN-{nnn}`).
 
 ---
 
@@ -58,6 +58,6 @@ Phần spec-breakdown là **mục đầu tiên** của `REQUIREMENT_ANALYSIS.md`
 - Danh sách giả định và câu hỏi mở (đánh dấu rõ điều CHƯA chắc)
 
 Đồng thời ghi mọi khoảng trống phát hiện vào `{qc_artifact_dir}DOC_GAP.md`
-(theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAP.template.md`), mỗi gap có ID `GAP-xx`.
+(theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAP.template.md`), mỗi gap có ID `GAP-UC{N}-{nnn}` — mã mang UC để phân tích lại một UC không đánh số lại UC khác.
 
 Kết thúc bằng gợi ý: feature đã đủ rõ để chuyển sang `qa-planner` (phân tích rủi ro) chưa.

package/core/skills/qc/qa-designer/api/auth-chain.md

@@ -0,0 +1,155 @@
+---
+version: 1.0
+updated: 2026-09-04
+ported_from: ui-automation-testing
+upstream_path: skills/qa-tc-designer/api-testcase-designer/api/templates/auth-chain.md
+upstream_sha: ef8f9761f1b53d0ccd752f8fe0c13a427fa15f45
+---
+
+> **VIẾT LẠI, không copy** *(B12)* — cùng lý do với `endpoint.md`: bản upstream có trước luật
+> ATOMIC (2026-07-09), gộp nhiều kết cục vào một `**Expected:**` và dùng hệ mã
+> `API-<FEATURE>-AUTH-001`. Ba nhóm ca giữ nguyên; cấu trúc theo `shared/tc-metadata-format.md`.
+
+# Khuôn TC — chuỗi xác thực (login → token → gọi endpoint được bảo vệ)
+
+Dùng khi TC phải đăng nhập lấy token trước khi gọi endpoint chính. Thứ tự gọi và điểm verify
+của từng chuỗi: xem `auth-sequence.md`.
+
+Phủ **3 nhóm ca**: chuỗi thành công · token hết hạn · login sai mật khẩu.
+
+> **Một chuỗi auth KHÔNG phải một TC.** Chuỗi có nhiều bước, mỗi bước có kết cục riêng —
+> nên nó là **nhiều TC độc lập**, mỗi TC giữ FULL steps để tự tới được trạng thái cần assert.
+> Đây đúng là chỗ luật ATOMIC dễ bị bỏ nhất, vì cảm giác "một chuỗi = một ca".
+
+---
+
+## Nhóm ca 1 — Chuỗi thành công
+
+### TC_<FEATURE>_101 — login trả về access_token
+
+- **Title:** Login role `<role>` với thông tin đúng trả về access_token
+- **Feature:** <TICKET-ID> — <Tên feature>
+- **Priority:** P0
+- **Status:** Draft
+- **Author:** AI
+- **Tags:** api, happy-path, auth, <feature-tag>
+- **Trace:** BR-xx
+- **@trace.verifies:** {UC-ID}-SC{N}
+
+#### Preconditions
+- Tài khoản role `<role>` đã tồn tại (username `<username>`, password `<password>`).
+
+#### Test Data
+- Method: POST
+- Path: `/auth/login`
+- Headers: Content-Type: application/json
+- Body:
+  ```json
+  { "username": "<username>", "password": "<password>" }
+  ```
+
+#### Test Steps
+1. **[Action]** Gửi `POST /auth/login` với body trên.
+2. **[Verify]** Đọc `body.access_token`.
+
+#### Expected Result
+- HTTP 200 AND `body.access_token` exists
+
+> ✅ Compound hợp lệ — cả hai vế nói về **cùng một** kết cục: "login thành công và có token".
+
+### TC_<FEATURE>_102 — token lấy được gọi được endpoint bảo vệ
+
+- **Title:** Token của role `<role>` gọi <METHOD> <protected_path> trả về <success_code>
+- **Priority:** P0
+- **Tags:** api, happy-path, auth, <feature-tag>
+- **Trace:** BR-xx
+
+#### Preconditions
+- Tài khoản role `<role>` đã tồn tại.
+
+#### Test Steps
+1. **[Action]** Gửi `POST /auth/login` lấy `access_token`.
+2. **[Action]** Gửi `<METHOD> <protected_path>` với `Authorization: Bearer {access_token}`.
+3. **[Verify]** Đọc status code của request thứ hai.
+
+#### Expected Result
+- HTTP `<success_code>`
+
+> ⚠️ Bước 1 **lặp lại đủ**, không viết "dùng token từ TC_101". Mỗi TC tách phải tự chạy độc
+> lập — nếu nó phụ thuộc TC khác đã chạy thì thứ tự chạy trở thành điều kiện ẩn, và chạy riêng
+> một TC sẽ fail vì lý do không liên quan tới thứ nó kiểm.
+
+---
+
+## Nhóm ca 2 — Token hết hạn
+
+### TC_<FEATURE>_103 — token hết hạn trả về 401
+
+- **Priority:** P0
+- **Tags:** api, negative, auth, security
+- **Trace:** BR-xx
+
+#### Preconditions
+- Có sẵn một token đã quá thời hạn (`<expired_token>` — seed hoặc lấy từ fixture).
+
+#### Test Data
+- Headers: Authorization: Bearer `<expired_token>`
+
+#### Test Steps
+1. **[Action]** Gửi `<METHOD> <protected_path>` với token đã hết hạn.
+2. **[Verify]** Đọc status code.
+
+#### Expected Result
+- HTTP 401
+
+*Chuỗi refresh token (nếu API có) là nhóm ca riêng — xem `auth-sequence.md` §Chuỗi 2. Mỗi bước
+của chuỗi refresh cũng là một TC.*
+
+---
+
+## Nhóm ca 3 — Login sai mật khẩu
+
+### TC_<FEATURE>_104 — sai password trả về 401
+
+- **Priority:** P0
+- **Tags:** api, negative, auth, security
+- **Trace:** BR-xx
+
+#### Test Data
+- Body: `{ "username": "<username>", "password": "<wrong_password>" }`
+
+#### Test Steps
+1. **[Action]** Gửi `POST /auth/login` với password sai.
+2. **[Verify]** Đọc status code.
+
+#### Expected Result
+- HTTP 401
+
+### TC_<FEATURE>_105 — sai password KHÔNG trả về token
+
+- **Priority:** P0
+- **Tags:** api, negative, auth, security
+- **Trace:** BR-xx
+
+#### Test Steps
+1. **[Action]** Gửi `POST /auth/login` với password sai.
+2. **[Verify]** Kiểm trường `access_token` trong body.
+
+#### Expected Result
+- `body.access_token` not exists
+
+> **Vì sao tách khỏi TC_104 dù cùng một request.** *"Trả 401"* và *"không phát token"* là hai
+> kết cục **fail độc lập được**: một API hỏng có thể trả 401 mà vẫn kèm token trong body. Gộp
+> lại thì TC pass khi chỉ một nửa đúng — và nửa còn lại là lỗ bảo mật.
+>
+> Đây chính là luật *"assertion loại-trừ (KHÔNG có / KHÔNG xảy ra) là oracle THẬT"* ở
+> `shared/tc-metadata-format.md`. Khi tách bằng script, kiểm lại không đánh rơi các bullet
+> phủ định — chúng dễ bị bỏ nhất.
+
+---
+
+## Không cần Teardown
+
+Cả 5 TC trên **không tạo bản ghi thật** — chúng chỉ login và đọc. Không thêm dòng
+`#### Teardown` cho có. Thêm khi và chỉ khi TC tạo tài khoản mới hoặc đổi trạng thái thật; lúc
+đó ghi `[Teardown: deactivate user via admin API]` *(`shared/precision-rules.md` §8)*.