@educa-corp/sdd-framework 0.9.2 → 0.9.4

package/bin/build.js

@@ -56,6 +56,17 @@ const RUNTIME_READ = {
   'steps/report-footer.md':
     '**Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·\n' +
     'Output Artifacts · Next) cho report cuối, kèm khối bên dưới.',
+
+  // Vào đây ở B12: nó được 5 lệnh qc-* include, nên inline là nhân 5 bản của cùng một
+  // quy trình — đúng loại phình mà test "mức slim" tồn tại để canh (nó bắt được thật).
+  'steps/qc-scope.md':
+    '**BẮT BUỘC — đọc `.agent/steps/qc-scope.md` và thực thi TOÀN BỘ quy trình trong đó**,\n' +
+    'rồi mới tiếp tục phần bên dưới.\n' +
+    '\n' +
+    'Nó chốt bốn thứ mà mọi trạm QC đều cần: `TICKET-ID` · `active_platform` ·\n' +
+    '`qc_artifact_dir` · `uc_list` (kèm trạng thái BDD từng UC, và cờ `--include-draft`).\n' +
+    'Bỏ qua thì artifact QC ghi vào **sai thư mục** và `qc_status` ghi vào **sai sổ trace** —\n' +
+    'cả hai đều xảy ra trong im lặng, không có bước nào phía sau bắt được.',
 };
 
 /**

package/bin/qc-base-map.json

@@ -47,7 +47,7 @@
     {
       "upstream": "agents/4-qa-tc-designer.md",
       "targets": [],
-      "state": "undecided",
+      "state": "skipped",
       "why": "dinh nghia agent cua upstream; framework dung command + gate _agent_mode thay cho agent file"
     },
     {
@@ -329,58 +329,83 @@
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/functional/api.md"
+      ],
+      "state": "ported",
+      "base_sha": "211c18728baf029a7572f0ffb161e92a933fa8fb"
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer/api/flows/auth-sequence.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/api/auth-sequence.md"
+      ],
+      "state": "ported",
+      "base_sha": "69d60c12fe6d641638132581cce1dc6c955354a6"
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer/api/flows/common-flows.md",
       "targets": [],
-      "state": "undecided"
+      "state": "skipped",
+      "why": "B12: ban nhap cu, nam gon trong auth-sequence.md + crud-sequence.md (dai va chi tiet hon)."
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer/api/flows/crud-sequence.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/api/crud-sequence.md"
+      ],
+      "state": "ported",
+      "base_sha": "65bf214d9f9beabe3c40b8697ba7c058adfd8bb5"
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer/api/references/common-headers.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/api/common-headers.md"
+      ],
+      "state": "ported",
+      "base_sha": "74f10a36bec7b40f4d9de2d0928798cb6fad0c2c"
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer/api/references/error-codes.md",
       "targets": [],
-      "state": "undecided"
+      "state": "skipped",
+      "why": "B12: ban nhap cu, nam gon trong http-status-codes.md (95 dong, day du hon). Phan header cua no nam trong common-headers.md. Lay ca hai la co hai bang tra cung mot thu roi chung lech nhau."
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer/api/references/http-status-codes.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/api/http-status-codes.md"
+      ],
+      "state": "ported",
+      "base_sha": "a82baa99350f63955245764a6aa57c9dca6d055f"
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer/api/templates/auth-chain.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/api/auth-chain.md"
+      ],
+      "state": "ported",
+      "base_sha": "ef8f9761f1b53d0ccd752f8fe0c13a427fa15f45"
     },
     {
       "upstream": "skills/qa-tc-designer/api-testcase-designer/api/templates/endpoint.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/api/endpoint.md"
+      ],
+      "state": "ported",
+      "base_sha": "7b38edd94e5efd37ff561f53cff92adedabaff7f"
     },
     {
       "upstream": "skills/qa-tc-designer/e2e-testcase-designer.md",
       "targets": [],
-      "state": "undecided"
+      "state": "skipped",
+      "why": "B12: tuong ung skills/qc/qa-designer/e2e/journey.md. Chua doi chieu noi dung — de danh cho lan ra tang E2E rieng."
     },
     {
       "upstream": "skills/qa-tc-designer/integration-testcase-designer.md",
       "targets": [],
-      "state": "undecided"
+      "state": "skipped",
+      "why": "B12: tuong ung 4 skill integration/{api,db,gui,kafka}.md. Chua doi chieu noi dung — de danh."
     },
     {
       "upstream": "skills/qa-tc-designer/manual-excel-testcase.md",
@@ -391,47 +416,70 @@
     {
       "upstream": "skills/qa-tc-designer/nfr-testcase-designer.md",
       "targets": [],
-      "state": "undecided"
+      "state": "skipped",
+      "why": "B12: tuong ung skills/qc/qa-designer/non-functional.md. Chua doi chieu noi dung — de danh."
     },
     {
       "upstream": "skills/qa-tc-designer/shared/action-keywords-glossary.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/shared/action-keywords-glossary.md"
+      ],
+      "state": "ported",
+      "base_sha": "df56df91eea42342537ccf67b5946df32d98dbf4"
     },
     {
       "upstream": "skills/qa-tc-designer/shared/duplicate-check-procedure.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/shared/duplicate-check-procedure.md"
+      ],
+      "state": "ported",
+      "base_sha": "c59357a56b289bb9fb7fae8490db37109209cb3a"
     },
     {
       "upstream": "skills/qa-tc-designer/shared/implicit-scenarios.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/shared/implicit-scenarios.md"
+      ],
+      "state": "ported",
+      "base_sha": "6eb801a137ef4dfda97870c1eb36db62f3c782bc"
     },
     {
       "upstream": "skills/qa-tc-designer/shared/precision-rules.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/shared/precision-rules.md"
+      ],
+      "state": "ported",
+      "base_sha": "1c2005b55bd94c3e8fa25dfa12a29c8b23f7c01e"
     },
     {
       "upstream": "skills/qa-tc-designer/shared/read-doc-gap-inputs.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/shared/read-doc-gap-inputs.md"
+      ],
+      "state": "ported",
+      "base_sha": "a7e113b19f35aa47acf91e55cdfb3f630539806c"
     },
     {
       "upstream": "skills/qa-tc-designer/shared/skill-decision-tree.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/shared/skill-decision-tree.md"
+      ],
+      "state": "ported",
+      "base_sha": "57125f0c21512f2abcc55d00420e92c84c95fc8f"
     },
     {
       "upstream": "skills/qa-tc-designer/shared/tc-metadata-format.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-designer/shared/tc-metadata-format.md"
+      ],
+      "state": "ported",
+      "base_sha": "a31d66a7a8dab19cf821c9102a88282b09e16cb9"
     },
     {
       "upstream": "skills/qa-tc-designer/ui-testcase-designer.md",
       "targets": [],
-      "state": "undecided"
+      "state": "skipped",
+      "why": "B12: framework tach tang UI thanh 3 skill rieng (functional/gui-screen · gui-feature · integration/gui) theo cay quyet dinh, thay vi mot file 341 dong. Ky thuat EP/BVA/Decision-Table/State-Transition da co trong 3 skill do; khuon TC + do chinh xac da tach ra shared/. Con lai la phan khai agent + orchestrator — framework khong co."
     },
     {
       "upstream": "skills/qa-tc-reviewer/api-test-reviewer.md",
@@ -440,23 +488,35 @@
     },
     {
       "upstream": "skills/qa-tc-reviewer/e2e-test-reviewer.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-reviewer/test-case/e2e.md"
+      ],
+      "state": "ported",
+      "base_sha": "276d0516f95421c726c8c55dc84c3c9244cf70e1"
     },
     {
       "upstream": "skills/qa-tc-reviewer/exploratory-test-reviewer.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-reviewer/test-case/exploratory.md"
+      ],
+      "state": "ported",
+      "base_sha": "4e068bb896739b977a6a5b1f638010d498c46aef"
     },
     {
       "upstream": "skills/qa-tc-reviewer/integration-test-reviewer.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-reviewer/test-case/integration.md"
+      ],
+      "state": "ported",
+      "base_sha": "639b54afb68df83b22168581c5c57b0f91d9cf6a"
     },
     {
       "upstream": "skills/qa-tc-reviewer/nfr-test-reviewer.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-reviewer/test-case/non-functional.md"
+      ],
+      "state": "ported",
+      "base_sha": "5747c7a6bdfaaea1ff3e958688b38b3aeaf9b15a"
     },
     {
       "upstream": "skills/qa-tc-reviewer/script-e2e-reviewer.md",
@@ -485,18 +545,28 @@
     },
     {
       "upstream": "skills/qa-tc-reviewer/shared/read-doc-gap-inputs.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-reviewer/shared/read-doc-gap-inputs.md"
+      ],
+      "state": "ported",
+      "base_sha": "3caa1562399ef1167ac2dc620add2c6c729e55df"
     },
     {
       "upstream": "skills/qa-tc-reviewer/shared/review-file-template.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-reviewer/shared/review-file-template.md"
+      ],
+      "state": "ported",
+      "base_sha": "bd596393ecc016cbea106835681a4979c0a9ca0e"
     },
     {
       "upstream": "skills/qa-tc-reviewer/ui-test-reviewer.md",
-      "targets": [],
-      "state": "undecided"
+      "targets": [
+        "skills/qc/qa-reviewer/test-case/functional.md",
+        "skills/qc/qa-reviewer/shared/review-check-groups.md"
+      ],
+      "state": "ported",
+      "base_sha": "54f81eb6a132d3fb331f18ce0f1a7eb3a9cf19df"
     }
   ],
   "$decisions": {

package/bin/self-check.js

@@ -1198,6 +1198,12 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
 //     sau đều đoán. Đây đúng loại việc con người không làm đáng tin bằng sự cẩn thận.
 //     → R16(b).
 //
+// (3) Một file NHẬN nội dung port mà KHÔNG đóng dấu nguồn gốc. Bản đồ khai đầy đủ, sha
+//     đúng, self-check xanh — nhưng người mở file không biết đây là bản port, nên lần
+//     đồng bộ sau bản đồ biết BASE mà người sửa file thì không. Ca thật: B12 gộp nội dung
+//     `api-testcase-designer.md` vào `functional/api.md`. (b) và (e) đều mù vì chúng chỉ
+//     so KHI frontmatter có khai. → R16(f).
+//
 // (a) là cái quan trọng nhất về lâu dài: file upstream KHÔNG có entry trong bản đồ =
 // bị bỏ quên trong im lặng. `state: skipped` (có lý do) là câu trả lời hợp lệ; VẮNG MẶT
 // thì không. Cùng khuôn với `checkpoint_levels` và `strict_use_check`: khai tường minh
@@ -1324,6 +1330,30 @@ for (const [vocab, def] of Object.entries(schema.vocabularies)) {
           }
         }
       }
+
+      // ── (f) target `ported` phải KHAI dấu nguồn gốc, không chỉ "khai đúng nếu có khai" ──
+      //
+      // Vì sao cần nhánh riêng: (b) và (e) đều chạy trong `if (m)` / `if (mp)` — chúng so
+      // frontmatter với bản đồ KHI frontmatter có khai. File không khai gì thì cả hai im lặng.
+      // Ca thật (B12): `functional/api.md` nhận nội dung port từ `api-testcase-designer.md`,
+      // vào bản đồ đầy đủ với base_sha đúng, self-check XANH — mà đọc file thì không ai biết
+      // nó là bản port. Mất `upstream_path` + `upstream_sha` ở file đích là mất BASE của merge
+      // ba chiều lần sau: bản đồ biết, còn người sửa file thì không.
+      for (const e of entries.filter(x => x.state === 'ported')) {
+        for (const t of (e.targets || [])) {
+          const tp = path.join(ROOT, t);
+          if (!fs.existsSync(tp)) continue;            // đã báo ở (c)
+          const txt = fs.readFileSync(tp, 'utf8');
+          const lack = ['upstream_path', 'upstream_sha']
+            .filter(f => !new RegExp(`^${f}: .+$`, 'm').test(txt));
+          if (lack.length) {
+            err('R16', `${t} là target \`ported\` nhưng frontmatter THIẾU ${lack.join(' + ')}`,
+                `Bản đồ khai nó port từ \`${e.upstream}\`, còn chính file thì không đóng dấu.
+` +
+                '        Người mở file không biết đây là bản port, và lần đồng bộ sau mất một chiều BASE.');
+          }
+        }
+      }
     }
   }
 }

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.9.2
+0.9.4

package/core/commands/qc-analyze.md

@@ -165,7 +165,7 @@ Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader
   🔴/⚠️ (không chặn ≠ không báo — người đọc log sau này vẫn cần thấy).
 
 
-*Lưu ý: Với lệnh này, target ở Bước 1 là một UC-ID hoặc file feature/PRD. Đọc spec chính thức của UC đó — file `.feature` (mang `@trace.id={UC-ID}` và mỗi scenario `@trace.scenario={UC-ID}-SC{N}`), PRD, và design-spec — từ feature package `{paths.specs_dir}/{domain}/{prd-slug}/` (file `.feature` dưới `bdd/`, file PRD `{TICKET-ID}-{prd-slug}.md` ở gốc folder, và design-spec dưới `design-spec/`). Spec của framework CHÍNH LÀ source of truth; đừng suy lại các requirement đã có ở đó. **Ngoài ra đọc tech-doc gộp** `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` làm **nguồn thứ hai** — xem §Đối chiếu tài liệu kỹ thuật.*
+*Lưu ý: Với lệnh này, target ở Bước 1 là một **TICKET-ID** (mã PRD), hoặc một UC-ID / file feature / file PRD — cả ba đều quy về TICKET-ID ở §Phạm vi QC. Trạm này chạy cho **cả PRD × một nền**. Đọc spec chính thức của **mọi UC trong phạm vi** — file `.feature` (mang `@trace.id={UC-ID}` và mỗi scenario `@trace.scenario={UC-ID}-SC{N}`), PRD, và design-spec — từ feature package `{paths.specs_dir}/{domain}/{prd-slug}/` (file `.feature` dưới `bdd/`, file PRD `{TICKET-ID}-{prd-slug}.md` ở gốc folder, và design-spec dưới `design-spec/`). Spec của framework CHÍNH LÀ source of truth; đừng suy lại các requirement đã có ở đó. **Ngoài ra đọc tech-doc gộp** `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` làm **nguồn thứ hai** — xem §Đối chiếu tài liệu kỹ thuật.*
 
 ## Context
 **BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,
@@ -177,60 +177,42 @@ placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
 
 ---
 
-## Platform Resolution *(thiết lập cho cả QC pass — mọi stage sau kế thừa)*
+## Phạm vi QC — PRD nào, nền nào, những UC nào
 
-> **PHẢI chạy TRƯỚC Guard bên dưới.** `{UC-ID}-SC{N}` chỉ độc nhất trong (UC × platform), 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`.
-> Guard đọc "file `.feature` của UC" khi chưa biết platform 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.
-> Chốt platform trước thì Guard mới có đúng một file để đọc.
-
-`{UC-ID}-SC{N}` chỉ độc nhất trong (UC × platform) — `web SC3` và `app SC3` là hai scenario khác nhau, và sổ trace tách theo `{UC-ID}-{platform}.tsv`. Nên **một QC pass khoá đúng MỘT platform**, và mọi artifact QC nằm dưới `{paths.qc_dir}/{UC-ID}/{active_platform}/`.
-
-Phân giải `active_platform` — theo thứ tự, dừng ở cái đầu tiên khớp:
-1. `$ARGUMENTS` nêu platform (`web`/`app`/`system`) → dùng.
-2. Target ở Bước 1 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 platform tồn tại → dùng nó.
-4. Nhiều platform mà không suy được → hỏi *"QC pass này cho platform 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 platform là ghi artifact vào sai
-   thư mục và ghi `qc_status` vào sai sổ trace:
-   ```
-   ❌ {UC-ID} có {n} platform ({list}) — không suy được platform nào cho QC pass này.
-      Chạy headless thì phải nêu tường minh: /qc-analyze {UC-ID} web --yes
-   ```
-
-Lưu `active_platform`. Đọc **đúng file `.feature` của platform đó** (`{paths.specs_dir}/{domain}/{prd-slug}/bdd/{active_platform}/{UC-ID}*.feature`) làm nguồn SC — không trộn SC chéo platform.
-
----
-
-## Guard — BDD đã duyệt chưa
+**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.
 
-*Chạy SAU Platform Resolution — xem lý do ở khối trên.*
+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.
 
-Đọc `# @trace.status:` từ header file `.feature` **của `{active_platform}` đã phân giải**:
-- `approved` → tiếp tục bình thường.
-- `draft` (hoặc khác `approved`) → **CHECKPOINT cảnh báo mềm** (không chặn cứng — cho phép QC sớm/prototype):
-  ```
-  ⚠️  BDD của {UC-ID} ({active_platform}) đang ở @trace.status: {status} (chưa duyệt). QC chạy trên BDD chưa chốt có thể phải làm lại.
-     Khuyến nghị: review-context (BDD) sạch + người duyệt đặt `# @trace.status: approved` rồi mới chạy QC.
-     Vẫn chạy QC bây giờ? (Y/N)
-  ```
-  Chỉ tiếp khi chọn Y — **trừ khi `$ARGUMENTS` có `--yes`**: coi như Y, **nhưng vẫn IN khối cảnh
-  báo** (không chặn ≠ không báo — người đọc log sau này vẫn cần thấy QC đã chạy trên BDD nháp).
+> **QC chạy trên BDD chưa chốt có thể phải làm lại.** `qc-scope` mặc định chỉ lấy UC có
+> `@trace.status: approved`; UC còn nháp vẫn vào bảng *Phạm vi phân tích* của `DOC_GAP.md`
+> với dấu `⏸ Chưa xét` — **không im lặng bỏ khỏi bảng**, vì "chưa xét" khác "đã xét, sạch".
+> Cố ý QC sớm thì thêm `--include-draft`, và artifact phải ghi rõ nó dựa trên BDD nháp.
 
-> **Vì sao `--yes` phải phủ cả guard mềm này.** `steps/gate.md` mở đường chạy headless
-> (`claude -p "… --yes"`), nhưng `--yes` chỉ khai là bỏ qua CHECKPOINT của gate. Guard mềm ở đây
-> là một `(Y/N)` thứ hai — nên lệnh vẫn treo vô hạn ở chế độ không có người trả lời, và đường
-> headless mà gate hứa bị bít cho đúng lệnh này. Một cổng chỉ chặn được khi có người ngồi đó
-> thì ở chế độ headless nó không phải cổng, nó là treo.
+> **Vì sao trạm này chạy CẢ PRD chứ không từng UC** *(B11)*. Ba lý do, theo thứ tự quan trọng:
+>
+> 1. **Mâu thuẫn chéo UC chỉ lộ ra khi đọc cùng lúc.** UC1 nói một kiểu, UC3 nói kiểu khác —
+>    chạy tách từng UC thì về **cấu trúc** là không thể thấy, không phải "khó thấy".
+> 2. **Rẻ hơn.** PRD, bản thiết kế, tài liệu kỹ thuật là nguồn **dùng chung**; chạy per-UC là
+>    đọc lại chúng mỗi UC một lượt. Phần dùng chung chiếm đa số đầu vào.
+> 3. **Một tài liệu cho một tính năng** là cách PO và QC vốn làm việc — file gốc của đội QC
+>    (`DOC_GAP_FEAT-02-3.md`) không có hậu tố UC, và `qa-planner/test-plan.md` vốn viết
+>    *"Test Plan cho một feature"*.
 
 ---
 
 ## Đối chiếu tài liệu kỹ thuật *(nguồn thứ hai — bắt lệch nghiệp vụ ↔ kỹ thuật)*
 
 Định vị tech-doc gộp cấp PRD: `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md`.
-Nó phủ **nhiều UC** — lọc theo `@trace.ucs` ở header, chỉ đọc phần chạm `{UC-ID}` đang xét.
+Nó phủ **nhiều UC** — và trạm này cũng phủ nhiều UC, nên đọc **mọi phần chạm `uc_list`**
+(đối chiếu `@trace.ucs` ở header với `uc_list`). Phần thuộc UC ngoài phạm vi (`⏸ Chưa xét`) thì bỏ qua.
+
+> **Đây là chỗ layout cấp PRD trả lãi rõ nhất.** Tech-doc gộp là **một** tài liệu phủ cả PRD.
+> Chạy per-UC thì nó bị đọc lại N lần, mỗi lần lọc bỏ gần hết — và mâu thuẫn giữa hai UC trong
+> **cùng** tài liệu đó không lần nào lộ ra, vì không lần nào thấy cả hai.
 
 **Không tìm thấy → cảnh báo mềm, KHÔNG chặn** (dự án có thể chưa dựng tech-doc):
 ```
@@ -259,9 +241,9 @@ Nó phủ **nhiều UC** — lọc theo `@trace.ucs` ở header, chỉ đọc ph
 Tech-doc có sổ ẩn số thiết kế riêng (`§12`), với vòng đời và người chịu trách nhiệm riêng, và
 `/generate-code` đã canh nó. **Trạm này chỉ đọc, tuyệt đối không ghi vào.**
 
-Với mỗi mục `open` trong §12 chạm `{UC-ID}`:
+Với mỗi mục `open` trong §12 chạm **bất kỳ UC trong `uc_list`**:
 - **KHÔNG mở gap mới** trong `DOC_GAP.md` về cùng chuyện đó.
-- Ghi vào `REQUIREMENT_ANALYSIS.md` mục *"Đang chờ chốt (từ §12 tech-doc)"*: `{id}` · điều chưa biết · owner · severity.
+- Ghi vào `REQUIREMENT_ANALYSIS.md` mục *"Đang chờ chốt (từ §12 tech-doc)"*: `{id}` · **UC** · điều chưa biết · owner · severity.
 - Test case chạm nó về sau sẽ bị chặn — nhưng bị chặn bởi **một mục đã có người xử lý**, không phải bởi một câu hỏi mới gửi PO.
 
 > **Vì sao không ghi vào.** Một ẩn số đã nằm trong §12 nghĩa là **đã có người đang lo**: có
@@ -272,8 +254,8 @@ Với mỗi mục `open` trong §12 chạm `{UC-ID}`:
 
 **Ngoại lệ — mục `spec-defect` là việc của PO.** §12 phân ba loại: `nội tại` (backend tự quyết) ·
 `cross-service` (đội khác) · `spec-defect` (PRD/BDD sai hoặc thiếu). Hai loại đầu → ghi "đang chờ".
-Loại thứ ba **đúng là gap tài liệu** → vẫn ghi vào `DOC_GAP.md`, trỏ ngược về `{id}` của §12 để
-không đếm hai lần.
+Loại thứ ba **đúng là gap tài liệu** → vẫn ghi vào `DOC_GAP.md` (cột `UC` = UC bị chạm), trỏ
+ngược về `{id}` của §12 để không đếm hai lần.
 
 ---
 
@@ -301,7 +283,8 @@ Thứ tự điển hình: spec-breakdown → business-rules / data-flow → acce
 
 File `.feature` chính thức đã định nghĩa scenario là `@trace.scenario={UC-ID}-SC{N}` với
 `@trace.business_rules`. Map mọi `BR-xx` / `AC-xx` bạn tạo ra tới `{UC-ID}-SC{N}` sở hữu nó
-và ghi lại mapping — qc-design-test và qc-run-test cần nó để gắn tag
+và ghi lại mapping — **làm cho từng UC trong `uc_list`**, và `BR`/`AC` phải mang rõ UC của nó
+(một file phân tích giờ phủ nhiều UC, nên `BR-01` không còn tự phân biệt được là của UC nào) — qc-design-test và qc-run-test cần nó để gắn tag
 `@trace.verifies` cho test và ghi `qc_status` theo từng scenario.
 
 ## Quét gap — hai nguồn, gộp rồi mới thẩm định
@@ -367,13 +350,23 @@ Gộp gap từ **cả hai nguồn** vào một tập trước khi sang bước t
 
 ## DOC_GAP (bắt buộc)
 
-Luôn tạo một file gaps theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAP.template.md`:
-- Mỗi gap `GAP-xx`, phân loại MISSING / AMBIGUOUS / CONTRADICTORY / ASSUMPTION / OPEN QUESTION, với severity (🔴 Blocker → 🟢 Low) và function/BR/AC bị ảnh hưởng.
+Luôn tạo **đúng MỘT** file gap cho cả (PRD × nền) theo
+`{paths.qc_skills_dir}/qa-analyst/DOC_GAP.template.md` — các UC là các hàng bên trong, phân
+biệt bằng cột `UC`:
+- **Bảng 11 cột**, cột 2 là `UC`. ID gap `GAP-UC{N}-{nnn}` (vd `GAP-UC1-001`); gap thuộc cả
+  PRD → `GAP-GEN-{nnn}`. Đánh số **độc lập trong từng UC** — phân tích lại UC1 KHÔNG được làm
+  đổi số gap của UC2, vì test case đã có đang trỏ `🚫 Block: [GAP-UC2-003]`.
+- **Section `Phạm vi phân tích`** — mỗi UC một hàng kèm `@trace.status`, đã phân tích chưa, số
+  gap. UC ngoài phạm vi ghi `⏸ Chưa xét`, **không bỏ khỏi bảng**.
+- Mỗi gap phân loại MISSING / AMBIGUOUS / CONTRADICTORY / ASSUMPTION / OPEN QUESTION, với severity (🔴 Blocker → ⚪ Low) và function/BR/AC bị ảnh hưởng.
 - Không bao giờ bịa câu trả lời; đánh dấu giả định là `ASSUMPTION` để PO/dev confirm.
-- Bất kỳ `🔴 Blocker` nào còn `Open` ⇒ UC chưa sẵn sàng cho qc-design-test — bàn giao cho qc-plan.
+- Bất kỳ `🔴 Blocker` nào còn `Open` ⇒ **UC ở cột `UC` của hàng đó** chưa sẵn sàng cho
+  qc-design-test — bàn giao cho qc-plan. *Chặn theo từng UC, KHÔNG chặn cả PRD:* một blocker ở
+  UC3 không có lý do gì dừng việc thiết kế test cho UC1. Ghi rõ UC nào bị chặn ở report.
 - **Đẩy các defect spec thực sự lên PO (không chỉ giữ local).** Một blocker là lỗi thật
   trong spec chính thức — `AMBIGUOUS` / `CONTRADICTORY` / `MISSING` trong PRD/BDD — phải tới
   PO qua feedback flow, không chỉ nằm trong `DOC_GAP.md`: tạo `/report-bug {UC-ID} {desc}`
+  (`{UC-ID}` lấy từ cột `UC` của hàng gap — bug đi theo UC, không theo PRD)
   (BUG_FLOW của nó phân loại PRD vs BDD), hoặc `/propose-scenario {UC-ID}` nếu gap là thiếu test
   coverage. Gap `ASSUMPTION` / `OPEN QUESTION` được confirm qua questions-for-dev của qc-plan — không file thành bug.
 
@@ -399,18 +392,28 @@ nó bị loại. Cập nhật `Tổng số gap` + bảng ưu tiên sau khi áp v
 
 ## Output
 
-Ghi **hai file** dưới `{paths.qc_dir}/{UC-ID}/{active_platform}/` + **một** dưới `{paths.refinement_dir}/` — **đừng** tách phân tích
-thành một-file-mỗi-bước (không có file spec-breakdown / business-rules / data-flow / AC riêng):
-
-1. **`{paths.qc_dir}/{UC-ID}/{active_platform}/REQUIREMENT_ANALYSIS.md`** — bản phân tích hợp nhất duy nhất.
-   Section theo thứ tự: phân rã requirement → bảng business-rule (`BR-xx`) → data-flow →
-   acceptance-criteria (`AC-xx`), mỗi `BR`/`AC` map tới `{UC-ID}-SC{N}` (của `.feature` platform này) sở hữu nó.
-   Cuối file thêm mục **"Đang chờ chốt (từ §12 tech-doc)"** — các ẩn số thiết kế `open` chạm UC này
-   (`{id}` · điều chưa biết · owner · severity). Rỗng thì ghi "Không có"; **đừng bỏ mục**.
-2. **`{paths.qc_dir}/{UC-ID}/{active_platform}/DOC_GAP.md`** — file gap, theo
+Ghi **hai file** dưới `{qc_artifact_dir}` (= `{paths.qc_dir}/{TICKET-ID}/{active_platform}/`)
++ **một** dưới `{paths.refinement_dir}/`.
+
+**Mỗi loại đúng MỘT file cho cả PRD** — đừng tách một-file-mỗi-UC, và cũng đừng tách
+một-file-mỗi-bước (không có file spec-breakdown / business-rules / data-flow / AC riêng):
+
+1. **`{qc_artifact_dir}REQUIREMENT_ANALYSIS.md`** — bản phân tích hợp nhất duy nhất cho cả PRD.
+   Mở đầu bằng **bảng `Phạm vi phân tích`** (cùng nội dung với bảng trong `DOC_GAP.md`), rồi
+   **một mục cho mỗi UC trong phạm vi**, mỗi mục theo thứ tự: phân rã requirement → bảng
+   business-rule (`BR-xx`) → data-flow → acceptance-criteria (`AC-xx`), mỗi `BR`/`AC` map tới
+   `{UC-ID}-SC{N}` (của `.feature` nền này) sở hữu nó.
+   Thêm một mục **"Mâu thuẫn chéo UC"** — chỗ hai UC của cùng PRD nói khác nhau. Rỗng thì ghi
+   "Không có". *Đây là thứ chỉ trạm cấp PRD nhìn thấy được; đừng bỏ mục.*
+   Cuối file thêm mục **"Đang chờ chốt (từ §12 tech-doc)"** — các ẩn số thiết kế `open` chạm
+   các UC trong phạm vi (`{id}` · UC · điều chưa biết · owner · severity). Rỗng thì ghi
+   "Không có"; **đừng bỏ mục**.
+2. **`{qc_artifact_dir}DOC_GAP.md`** — file gap, theo
    `{paths.qc_skills_dir}/qa-analyst/DOC_GAP.template.md` + luật viết ở
    `{paths.qc_skills_dir}/qa-analyst/spec-issue-reporter.md`. Bắt buộc:
-   - **Bảng 10 cột** đúng thứ tự, có cột **Giao cho đội** (Dev / PO / BA / Design / Kiến trúc / Dữ liệu).
+   - **Bảng 11 cột** đúng thứ tự, có cột **`UC`** (cột 2) và cột **Giao cho đội** (Dev / PO / BA / Design / Kiến trúc / Dữ liệu).
+   - Section **"Phạm vi phân tích"** ngay sau metadata — mỗi UC một hàng kèm `@trace.status`,
+     đã phân tích chưa, số gap. UC ngoài phạm vi ghi `⏸ Chưa xét`.
    - Ô câu hỏi đủ **bốn phần** tách bằng `<br/>`: **Bối cảnh → Vấn đề → Tại sao quan trọng → Gợi ý**.
      *Ba phần đầu cho PO xếp ưu tiên; phần cuối cho PO trả lời nhanh mà không phải nghĩ lại từ đầu.*
    - Section **"Tài liệu đầu vào đã đọc để phân tích"** đặt ngay sau metadata — liệt kê **đủ** mọi
@@ -418,7 +421,7 @@ thành một-file-mỗi-bước (không có file spec-breakdown / business-rules
      với *"chưa đọc"*.
    - Mức nặng nhất dùng từ **`🔴 Blocker`** (không phải `Critical`) — `/qc-run-test` đọc đúng từ này
      để đặt *"scenario đang chờ PO"* vào sổ trace.
-3. **`{paths.refinement_dir}/{UC-ID}-qa-findings.yaml`** — **cùng dữ liệu gap**, ở định dạng Review Board đọc được. Xem §Bản findings dưới đây.
+3. **`{paths.refinement_dir}/{TICKET-ID}-qa-findings.yaml`** — **cùng dữ liệu gap**, ở định dạng Review Board đọc được. Xem §Bản findings dưới đây.
 
 `{paths.qc_dir}` là folder top-level NHÌN THẤY trong QC repo (mặc định `docs/`, **không** phải
 `.agent/review/` ẩn) để team QC mở và xử lý output dễ dàng. Spec chính thức ở lại
@@ -433,8 +436,10 @@ Dùng **đúng schema của `/refine-prd`** để Review Board đọc được c
 
 ```yaml
 prd_source: "{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md"
-uc_id: "{UC-ID}"
+ticket_id: "{TICKET-ID}"
 platform: "{active_platform}"
+ucs: ["{UC-ID}", "…"]          # các UC TRONG phạm vi (approved) — theo thứ tự
+ucs_skipped: ["{UC-ID}"]       # UC chưa xét, kèm lý do ở DOC_GAP §Phạm vi phân tích
 generated_at: "{ISO datetime}"
 generated_by: "qc-analyze"
 status: "pending_review"
@@ -452,7 +457,7 @@ findings:
     auto_fixable: false           # LUÔN false — xem cảnh báo dưới
     status: "pending"
     applied_via: ""
-    gap_ref: "GAP-xx"             # trỏ ngược về hàng trong DOC_GAP.md
+    gap_ref: "GAP-UC1-001"        # trỏ ngược về hàng trong DOC_GAP.md (ID mang UC)
 
 summary:
   total_findings: {N}
@@ -473,8 +478,9 @@ summary:
 > Đường đúng vẫn là kênh đã có: `/report-bug` cho defect spec thật, `/propose-scenario` cho thiếu
 > độ phủ. File `.yaml` này để **PO đọc và quyết trong một chỗ quen**, không phải để máy tự áp.
 
-**File riêng, không ghi chung với `/refine-prd`.** Tên có `{UC-ID}` nên không đụng
-`{prd-slug}-findings.yaml`. Ghi chung sẽ phá trường `applied_to_version` mà `/refine-prd` dùng để
+**File riêng, không ghi chung với `/refine-prd`.** Cả hai giờ đều ở cấp PRD, nên khác biệt nằm
+ở **hậu tố**: `{TICKET-ID}-qa-findings.yaml` (trạm này) vs `{prd-slug}-findings.yaml`
+(`/refine-prd`). Đừng gộp. Ghi chung sẽ phá trường `applied_to_version` mà `/refine-prd` dùng để
 phân biệt *"PRD đổi do chính tôi áp fix"* với *"có người lạ sửa"* — và nó sẽ mãi mãi tưởng có
 người sửa sau lưng, mỗi lần chạy đều quét lại toàn bộ kèm cảnh báo giả.
 
@@ -486,17 +492,21 @@ người sửa sau lưng, mỗi lần chạy đều quét lại toàn bộ kèm
 Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
 
 ```
-/qc-analyze Hoàn tất — {UC-ID} ({active_platform})
-Files : {paths.qc_dir}/{UC-ID}/{active_platform}/REQUIREMENT_ANALYSIS.md + DOC_GAP.md (10 cột)
-        {paths.refinement_dir}/{UC-ID}-qa-findings.yaml    ← mở bằng Review Board (chuột phải)
-Nguồn : PRD · BDD({active_platform}) · design-spec · tech-doc{nếu thiếu tech-doc: " (THIẾU — không đối chiếu được nghiệp vụ ↔ kỹ thuật)"}
+/qc-analyze Hoàn tất — {TICKET-ID} ({active_platform})
+Phạm vi: {n}/{N} UC phân tích{nếu có UC chưa xét: " · ⏸ {m} chưa xét: {danh sách UC-ID} (BDD chưa approved)"}
+Files : {paths.qc_dir}/{TICKET-ID}/{active_platform}/REQUIREMENT_ANALYSIS.md + DOC_GAP.md (11 cột)
+        {paths.refinement_dir}/{TICKET-ID}-qa-findings.yaml    ← mở bằng Review Board (chuột phải)
+Nguồn : PRD · BDD({active_platform}, {n} UC) · design-spec · tech-doc{nếu thiếu tech-doc: " (THIẾU — không đối chiếu được nghiệp vụ ↔ kỹ thuật)"}
 Quét  : 4 kỹ năng phân tích + 4 lăng kính (xử lý lỗi · giao diện · dữ liệu & cấu hình
         · đối chiếu chéo: PRD↔design-spec, bdd↔design-spec)
 Verify: {raw} gap thô → {N} còn Open  (❌ {invalid} bịa/đã-trả-lời · ⚠️ {reclass} không phải gap nghiệp vụ · 🔁 {merge} trùng)
-Gaps  : {N} ({blockers} blocker)   ← blocker là spec-defect? → /report-bug {UC-ID}  | coverage gap → /propose-scenario {UC-ID}
-Chờ chốt: {G} ẩn số §12 tech-doc đang open chạm UC này (đã ghi vào REQUIREMENT_ANALYSIS, KHÔNG hỏi lại PO)
+Gaps  : {N} ({blockers} blocker) — theo UC: {UC1: n · UC2: n · …}{nếu có: " · toàn PRD: {n}"}
+        ← blocker là spec-defect? → /report-bug {UC-ID của hàng đó}  | coverage gap → /propose-scenario {UC-ID}
+Chéo UC: {X} mâu thuẫn giữa các UC của cùng PRD (đã ghi vào REQUIREMENT_ANALYSIS §Mâu thuẫn chéo UC)
+Chặn  : {danh sách UC có 🔴 Blocker còn Open} — các UC còn lại vẫn thiết kế test được bình thường
+Chờ chốt: {G} ẩn số §12 tech-doc đang open chạm các UC này (đã ghi vào REQUIREMENT_ANALYSIS, KHÔNG hỏi lại PO)
 SC map: {M} BR/AC map tới {K} scenario
-Next  : /qc-plan {UC-ID} {active_platform}   ← rủi ro / what-if / câu hỏi cho dev
+Next  : /qc-plan {TICKET-ID} {active_platform}   ← rủi ro / what-if / câu hỏi cho dev
         (giải quyết các gap 🔴 Blocker với PO/Dev trước)
 ```