@educa-corp/sdd-framework 0.9.3 → 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.3
+0.9.4

package/core/commands/qc-analyze.md

@@ -179,126 +179,13 @@ placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
 
 ## Phạm vi QC — PRD nào, nền nào, những UC nào
 
-# 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.
 
 > **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`