@educa-corp/sdd-framework 0.7.5 → 0.8.1

package/docs/plans/qc-sync-command.md

@@ -0,0 +1,358 @@
+# Plan — lệnh sync skill QC từ upstream vào framework
+
+> Tài liệu này là **phần 2** của [`qc-merge-plan.md`](qc-merge-plan.md).
+> Plan kia trả lời *"gộp cái gì, và ba quyết định nào đang chặn"*.
+> Plan này trả lời *"về sau QC sửa skill thì làm sao đưa vào framework mà không vỡ"*.
+
+| | |
+|---|---|
+| Snapshot | `upstream/qc-base/` — 82 file, 10.008 dòng, **không ship** (ngoài `package.json` `files`) |
+| Upstream | `D:\projects\ui-automation-testing` @ `596149f` (git repo thật → pin được) |
+| Đích | `skills/qc/qa-*` (35 file) + 6 lệnh `commands/qc-*.tmpl` |
+| Trạng thái | plan — chưa code |
+
+---
+
+## 1 · Vì sao đây không phải copy file
+
+Ba lý do, xếp theo độ khó tăng dần.
+
+### (a) Ánh xạ không phải 1:1
+
+```
+upstream                          framework
+qa-tc-analyst  (1 agent)   ─┬──►  /qc-analyze   (trạm 1)  +  skills/qc/qa-analyst/
+  23 skill                  └──►  /qc-plan      (trạm 2)  +  skills/qc/qa-planner/
+```
+
+Một đơn vị upstream nở ra hai đơn vị framework. `test-plan.md` của `qa-tc-analyst`
+đã nằm ở `qa-planner/`. Copy theo thư mục là sai ngay từ bước đầu.
+
+### (b) File được **adapt**, không phải copy
+
+Cả 4 file trùng tên đều khác nội dung, và khác có chủ ý:
+
+| | upstream | framework | framework thêm gì |
+|---|---|---|---|
+| `business-rules` | 90 dòng | 59 | `{paths.qc_dir}` · rào *"chỉ trả 2 file"* |
+| `acceptance-criteria` | 57 | 60 | như trên |
+| `data-flow` | 61 | 64 | như trên |
+| `spec-breakdown` | 58 | 61 | như trên |
+
+Copy đè = **xoá sạch phần adapt**. Và `business-rules` bản upstream **dài hơn 31 dòng** —
+nên chiều ngược lại cũng đúng: bản framework có thể đã cắt mất nội dung thật, không chỉ đổi path.
+
+### (c) Đây là bài toán **merge ba chiều**, và hiện đang thiếu một chiều
+
+Khi QC sửa `business-rules.md`, có ba bản:
+
+```
+        BASE                    THEIRS                  OURS
+   bản upstream mà          bản upstream mới         bản framework
+   framework đã port từ                              đã adapt
+        │                         │                       │
+        └────────── diff A ───────┘                       │
+                 "QC đã đổi gì"                           │
+        └──────────────────── diff B ──────────────────────┘
+                       "ta đã adapt gì"
+
+   Không có BASE  ⇒  không phân biệt được A với B
+                 ⇒  mọi merge đều là đoán
+```
+
+**`upstream/qc-base/` chính là BASE** — nhưng chỉ khi nó được **pin**: ghi lại nó ứng với
+commit upstream nào. Một thư mục snapshot không có pin thì chỉ là "một bản copy cũ nào đó",
+không dùng làm base merge được.
+
+> **Đây là lý do kiến trúc của toàn bộ plan này:** lệnh cần dựng không phải lệnh copy,
+> mà là một **vendor-branch merge tool có pin**.
+
+---
+
+## 2 · Ba tạo tác phải có trước khi viết lệnh
+
+### 2.1 · Pin — `upstream/qc-base/.pin.json`
+
+```json
+{
+  "upstream": {
+    "repo": "ui-automation-testing",
+    "url": "<git remote>",
+    "ref": "main",
+    "commit": "596149f",
+    "captured_at": "2026-08-24"
+  },
+  "files": {
+    "skills/qa-tc-analyst/business-rules.md": "sha1…",
+    "skills/qa-tc-analyst/gap-verifier.md":   "sha1…"
+  }
+}
+```
+
+Hash từng file, không chỉ commit. Lý do: snapshot có thể bị sửa tay (ai đó "sửa nhanh một
+dòng trong `upstream/`"), và lúc đó base không còn là base. Hash bắt được, commit thì không.
+
+### 2.2 · Bản đồ ánh xạ — `bin/qc-base-map.json`
+
+Đây là tạo tác quan trọng nhất. Mỗi entry trả lời: file upstream này đi đâu, adapt thế nào,
+ai chịu trách nhiệm.
+
+```json
+{
+  "map": [
+    {
+      "upstream": "skills/qa-tc-analyst/business-rules.md",
+      "targets": ["skills/qc/qa-analyst/business-rules.md"],
+      "adapt": ["path-placeholders", "two-file-guard"],
+      "state": "ported",
+      "base_sha": "sha1 của bản upstream đã port từ"
+    },
+    {
+      "upstream": "skills/qa-tc-analyst/gap-verifier.md",
+      "targets": ["steps/gap-verify.md"],
+      "adapt": ["path-placeholders", "generalize-doc-gap-to-findings"],
+      "state": "planned",
+      "note": "P0 — dùng chung cho refine-prd / review-context / qc-analyze"
+    },
+    {
+      "upstream": "skills/qa-tc-designer/manual-excel-testcase.md",
+      "targets": [],
+      "state": "skipped",
+      "why": "README upstream khai đã bỏ nhánh manual-Excel; file còn sót"
+    },
+    {
+      "upstream": "skills/qa-gate/styled-report-template.py",
+      "targets": [],
+      "state": "undecided",
+      "why": "script thật, không phải prompt — framework QC hiện 100% markdown-first"
+    }
+  ]
+}
+```
+
+**Bốn `state`, và cái thứ tư là cái quan trọng:**
+
+| state | Nghĩa |
+|---|---|
+| `ported` | đã đưa vào, có `base_sha` để merge lần sau |
+| `planned` | đã quyết sẽ đưa, chưa làm |
+| `skipped` | **cố ý** không đưa, có lý do ghi lại |
+| `undecided` | chưa ai quyết ← **đây là hàng đợi việc** |
+
+File upstream **không có entry nào** = bị bỏ quên trong im lặng. Đó là failure mode duy nhất
+mà bản đồ này tồn tại để chặn — và §5 để máy canh nó.
+
+### 2.3 · Luật adapt dạng **dữ liệu**, không phải người nhớ
+
+```json
+{
+  "adapt_rules": {
+    "path-placeholders": [
+      { "from": "inputs/free-trial-spec/specs/", "to": "{paths.specs_dir}/" },
+      { "from": "docs/<feature>/",              "to": "{paths.qc_dir}/{UC-ID}/{active_platform}/" },
+      { "from": "inputs/",                      "to": "{paths.specs_dir}/", "note": "khái niệm nguồn-evidence" }
+    ],
+    "two-file-guard": { "kind": "append-block", "block": "…rào 'chỉ trả 2 file'…" },
+    "orchestrator-to-agent-mode": {
+      "kind": "manual",
+      "why": "upstream nhận routing plan từ qa-orchestrator; framework dùng gate Bước 0 _agent_mode. Không map máy được."
+    }
+  }
+}
+```
+
+Ba loại luật: **thay chuỗi** (máy làm) · **chèn block** (máy làm) · **`manual`** (buộc người
+xem, lệnh dừng lại hỏi). Loại thứ ba là chỗ tránh được cái bẫy "tool tự tin adapt sai".
+
+> **37 file upstream hardcode `inputs/…`** — đây là khối lượng chính của `path-placeholders`.
+
+---
+
+## 3 · Chia việc: script làm phần cơ học, lệnh làm phần phán đoán
+
+Framework đã có tiền lệ cho cách chia này: `bin/lint-trace.js` (script, chạy được trong CI)
+vs `/validate-traces` (LLM, không chạy được trong CI thường). Áp đúng khuôn đó.
+
+```
+bin/qc-sync.js                          /sync-qc-base  (lệnh markdown)
+─────────────────────────────           ────────────────────────────────
+hash + so pin                           "thay đổi này thuộc trạm 1 hay trạm 2?"
+diff ba chiều                           "skill mới này có thuộc phạm vi framework?"
+áp adapt_rules loại string/block        áp adapt_rules loại `manual`
+bookkeeping pin + base_sha              đọc diff, quyết giữ/bỏ phần adapt của ta
+phát hiện entry thiếu / mồ côi          viết lại đoạn cần diễn đạt theo giọng framework
+in báo cáo máy-đọc-được                 CHECKPOINT trước khi ghi
+─────────────────────────────           ────────────────────────────────
+deterministic · CI-able · --dry-run     cần người · cần ngữ cảnh · có gate
+```
+
+Nguyên tắc: **script không bao giờ tự ghi vào `skills/qc/qa-*` hay `commands/`
+khi có `manual` rule hoặc conflict.** Nó dựng patch + báo; lệnh mới là chỗ quyết.
+
+---
+
+## 4 · Sáu lệnh con
+
+Framework không dùng sub-command thật — nó dùng cờ trên một lệnh (`--resume`, `--fix`,
+`--full`). Giữ đúng quy ước đó:
+
+```
+/sync-qc-base [--status] [--pull] [--diff] [--port] [--adopt] [--verify]
+```
+
+| Cờ | Trả lời câu | Đọc | Ghi | Chặn |
+|---|---|---|---|---|
+| `--status` *(mặc định)* | "upstream đi trước ta bao nhiêu?" | pin, snapshot, map, upstream | — | không |
+| `--pull` | "lấy bản upstream mới về snapshot" | upstream git | `upstream/qc-base/` + `.pin.json` | không¹ |
+| `--diff` | "QC đổi gì, ta adapt gì, có đè nhau không?" | 3 chiều | — | không |
+| `--port` | "đưa thay đổi upstream vào file framework" | 3 chiều + adapt_rules | `skills/qc/qa-*`, `commands/*.tmpl` | **CỨNG** |
+| `--adopt` | "nhận một skill upstream CHƯA có trong map" | snapshot + map | map entry + file đích mới | **CỨNG** |
+| `--verify` | "pin/map/frontmatter còn khớp nhau không?" | tất cả | — | không |
+
+¹ `--pull` không chặn vì nó chỉ đụng `upstream/` — nhưng nó **phải** cảnh báo nếu snapshot
+đang bị sửa tay (hash lệch pin), vì lúc đó base sắp bị ghi đè mất.
+
+### Chi tiết từng cờ
+
+**`--status`** — bức ảnh một màn hình:
+```
+Snapshot : 596149f (2026-08-24)   Upstream: a3f21c8 (2026-09-02)  → đi trước 7 commit
+Đổi      : 12 file
+           ├─ 4 ported     → cần --port
+           ├─ 2 planned    → chưa làm, không ảnh hưởng
+           ├─ 1 skipped    → bỏ qua đúng chủ ý
+           └─ 5 KHÔNG CÓ TRONG MAP  ← chạy --adopt hoặc khai skipped
+Framework: 1 file đã bị sửa tay sau lần port (base_sha lệch) → --diff xem trước
+```
+
+**`--pull`** — làm mới snapshot. Không đụng framework. Ba việc: fetch/checkout ref,
+ghi lại `.pin.json`, và **giữ bản pin cũ** thành `.pin.prev.json` — vì merge ba chiều lần
+`--port` sau cần BASE là bản *trước khi* pull.
+
+> Đây là chỗ dễ sai nhất của cả thiết kế: `--pull` mà không lưu base cũ thì `--port`
+> mất chiều thứ ba, và ta quay về đúng vấn đề §1(c).
+
+**`--diff`** — bề mặt review. Mỗi file đổi, in ba khối: QC đổi gì · ta adapt gì · hai cái
+có chạm nhau không. Chạm nhau = conflict thật, cần người.
+
+**`--port`** — merge + adapt + ghi. Chặn CỨNG (`--yes` không bỏ được) vì nó ghi đè file
+framework đã có. Với mỗi file: 3-way merge → áp `adapt_rules` string/block → gặp rule
+`manual` hoặc conflict thì **để lại** vào file findings, không tự quyết → cập nhật
+`base_sha` cho các file đã port sạch.
+
+**`--adopt`** — đường vào cho skill upstream mới (và cho **P1** của plan kia: 18 skill của
+`qa-tc-analyst` chưa có đều đi qua đây). Việc nó làm: hỏi đích (`skills/qc/…`? `steps/`?
+một `commands/*.tmpl`?), hỏi `adapt` nào áp, dựng bản adapt đầu tiên, tạo entry map với
+`state: ported` + `base_sha`.
+
+**`--verify`** — invariant check, chạy được trong CI:
+
+| Kiểm | Bắt lỗi gì |
+|---|---|
+| mọi file snapshot có entry trong map | **skill upstream bị bỏ quên im lặng** |
+| entry map trỏ tới file tồn tại (cả 2 phía) | map lỗi thời sau khi upstream đổi tên |
+| `base_sha` của entry `ported` khớp một file snapshot | base đã trôi, merge lần sau sẽ sai |
+| frontmatter `upstream_path` + `upstream_sha` của file đích khớp map | file đích bị sửa tay ngoài luồng |
+| `skills/qc/qa-*` không còn chuỗi `inputs/` sót | adapt làm nửa vời |
+| lệnh `qc-*` không trỏ vào skill đã mất | **đúng lỗi vừa xảy ra hôm nay** |
+
+---
+
+## 5 · Rule máy canh — `R16`
+
+`--verify` là lệnh người gọi. Nhưng framework này có một nguyên tắc lặp lại năm lần trong
+loạt GAP: *luật đúng, viết rõ, và không ai canh*. Nên phần **cốt lõi** của `--verify` phải
+thành rule trong `bin/self-check.js`, fail build:
+
+```
+R16 — snapshot upstream và framework không được trôi khỏi nhau trong im lặng
+
+  a) mọi file trong upstream/qc-base/ phải có entry trong bin/qc-base-map.json
+     → thiếu entry = bị bỏ quên. state `skipped` là câu trả lời hợp lệ; VẮNG MẶT thì không.
+  b) mọi entry `state: ported` phải có base_sha, và base_sha phải khớp file snapshot
+  c) mọi target của entry `ported` phải tồn tại
+  d) mọi lệnh qc-* trỏ vào {paths.qc_skills_dir}/X phải có X tồn tại trong skills/qc/
+```
+
+**(d) là rule đáng lẽ đã chặn sự cố hôm nay** — 35 file skill bị xoá, `self-check` xanh,
+`build` xanh, `.agent` vẫn chạy được nên dogfood không phát hiện, và installer thì sẽ
+*chủ động xoá* chúng ở project người dùng. Ba tầng che nhau, không tầng nào bắt.
+
+`R16(d)` **đáng làm ngay, độc lập với toàn bộ plan này.**
+
+---
+
+## 6 · Luồng điển hình
+
+```
+QC push skill mới
+     │
+     ▼
+/sync-qc-base --status      "đi trước 7 commit, 12 file đổi, 5 chưa có trong map"
+     │
+     ▼
+/sync-qc-base --pull        snapshot: 596149f → a3f21c8   (giữ .pin.prev.json)
+     │
+     ▼
+/sync-qc-base --diff        đọc: QC đổi gì · ta adapt gì · chỗ nào chạm nhau
+     │
+     ├──► 5 file chưa có trong map
+     │        │
+     │        ▼
+     │    /sync-qc-base --adopt    quyết đích + adapt cho từng cái
+     │
+     ▼
+/sync-qc-base --port        CHECKPOINT CỨNG → merge + adapt → conflict ra findings
+     │
+     ▼
+node bin/self-check.js      R16 xanh
+node bin/build.js           41/41
+     │
+     ▼
+/sync-qc-base --verify      invariant sạch
+```
+
+---
+
+## 7 · Phase triển khai
+
+| Phase | Việc | Phụ thuộc |
+|---|---|---|
+| **S0** | **`R16(d)`** — rule chặn "lệnh qc-* trỏ vào skill không tồn tại" | không · **làm ngay** |
+| **S1** | Dựng `.pin.json` cho snapshot hiện tại (`596149f`) + hash 82 file | không |
+| **S2** | Dựng `bin/qc-base-map.json` — 82 entry. Phần lớn là `undecided`, 5 là `ported` (4 analyst + test-plan), phần còn lại phân loại dần | S1 |
+| **S3** | `bin/qc-sync.js` — `--status` + `--verify` trước (read-only, rẻ, có giá trị ngay) | S1, S2 |
+| **S4** | `R16(a)(b)(c)` vào `self-check.js` | S2 |
+| **S5** | `--pull` + `--diff` (vẫn read-only với framework) | S3 |
+| **S6** | `--adopt` — rồi dùng chính nó chạy **P1** của plan kia (18 skill analyst) | S5 |
+| **S7** | `--port` — merge ba chiều. Phần khó nhất, làm cuối | S6 |
+
+> **Thứ tự này có chủ ý:** mọi thứ read-only xong trước, ghi-file để sau cùng.
+> `--status` + `--verify` đã trả giá trị (biết mình đang lệch bao nhiêu) trước khi
+> viết một dòng logic merge nào.
+
+Và `--adopt` (S6) đứng **trước** `--port` (S7) vì `--adopt` là việc phải làm ngay
+(18 skill đang chờ), còn `--port` chỉ cần khi QC push lần sửa đầu tiên.
+
+---
+
+## 8 · Câu chưa quyết
+
+| # | Câu | Ghi chú |
+|---|---|---|
+| 1 | `upstream/qc-base/` **track git hay không?** | Nên track — cần nó làm BASE và cần diff được qua lịch sử. Đổi lại: +10k dòng vào repo. |
+| 2 | Snapshot lấy bằng **copy tay** hay **git submodule**? | Submodule đúng bản chất hơn nhưng `--pull` phức tạp hơn, và submodule *là* moving target trong khi BASE cần đóng băng. Copy + pin đơn giản hơn, tôi nghiêng về nó. |
+| 3 | `bin/qc-base-map.json` hay gộp vào `bin/trace-schema.json`? | Tách riêng: đây không phải contract về trace. Nhưng `self-check.js` phải đọc cả hai. |
+| 4 | 2 file `.py` của `qa-gate` xử sao? | `state: undecided`. Framework QC hiện 100% markdown-first — nhận script là đổi một nguyên tắc. |
+| 5 | `ported_from: ai-automation-qc-base` đang **sai tên repo** (thật là `ui-automation-testing`) | Sửa luôn khi thêm `upstream_path` + `upstream_sha` vào frontmatter. |
+| 6 | `shared/` của upstream — framework có nhận khái niệm này? | `qa-tc-designer/shared/` 7 file dùng chung. Framework hiện "mỗi skill tự đủ". Nhận `shared/` là đổi kiến trúc skill. |
+| 7 | `read-doc-gap-inputs.md` tồn tại **2 bản khác nội dung** (designer + reviewer) | Trùng tên khác ruột — chọn sai là sai im lặng. Phải chốt 1 bản, hoặc map thành 2 entry riêng. |
+
+---
+
+## Liên quan
+
+- [`qc-implementation-log.md`](qc-implementation-log.md) — nhật ký triển khai, viết cho người không cần biết code
+
+- [`qc-merge-plan.md`](qc-merge-plan.md) — gộp cái gì, ba quyết định đang chặn (§5), plan P0–P4
+- `--adopt` (S6 ở đây) **chính là** P1 của plan kia — không phải hai việc, là một việc có công cụ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/sdd-framework",
-  "version": "0.7.5",
+  "version": "0.8.1",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"

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

@@ -1,63 +0,0 @@
----
-version: 1.1
-updated: 2026-06-11
-ported_from: ai-automation-qc-base
----
-
-# Gap Analysis – <FEATURE>
-
-> File ghi lại các **khoảng trống của tài liệu** mà `qa-analyst` phát hiện sau khi
-> phân tích. Là đầu vào để hỏi dev/BA và cho `qa-planner`. Mỗi gap có ID `GAP-xx`
-> để business rule (BR-xx), acceptance criteria (AC-xx) và test case trace ngược về.
-
-| Trường | Giá trị |
-|---|---|
-| Feature | `<FEATURE>` |
-| Project / Service | `<project or service name / domain>` |
-| Tài liệu nguồn | `<đường dẫn / link PRD / user story>` |
-| Người phân tích | qa-analyst |
-| Ngày phân tích | `<YYYY-MM-DD>` |
-| Tổng số gap | `<N>` (Blocker: x · High: y · Medium: z · Low: w) |
-| Trạng thái chung | 🔴 Blocked / 🟡 Cần làm rõ / 🟢 Đủ rõ để thiết kế TC |
-
----
-
-## Bảng Gap
-
-| ID | Loại | Mô tả gap | Vị trí (mục/nguồn) | Ảnh hưởng (chức năng / BR / AC) | Mức độ | Người trả lời | Trạng thái | Câu trả lời |
-|---|---|---|---|---|---|---|---|---|
-| GAP-01 | MISSING | … | spec §x | chức năng A / BR-02 | 🔴 Blocker | Dev/BA | Open | — |
-| GAP-02 | AMBIGUOUS | … | mockup màn hình Y | AC-03 | 🟠 High | BA | Open | — |
-| GAP-03 | CONTRADICTORY | … | §2 vs §5 | BR-04 | 🟠 High | BA | Open | — |
-| GAP-04 | ASSUMPTION | … (giả định AI tự đưa, cần xác nhận) | — | chức năng B | 🟡 Medium | Dev | Open | — |
-
-### Loại gap
-- **MISSING** – thông tin/chức năng/field/rule chưa được mô tả.
-- **AMBIGUOUS** – mô tả mơ hồ, có ≥ 2 cách hiểu.
-- **CONTRADICTORY** – các phần tài liệu mâu thuẫn nhau.
-- **ASSUMPTION** – giả định do qa-analyst tự suy ra, cần dev/BA xác nhận.
-- **OPEN QUESTION** – câu hỏi mở cần trả lời trước khi thiết kế/triển khai.
-
-### Mức độ
-🔴 Blocker (chặn thiết kế TC) · 🟠 High · 🟡 Medium · 🟢 Low
-
----
-
-## Quy ước cập nhật
-- `qa-analyst` tạo & điền gap khi phân tích; **không tự bịa câu trả lời** cho gap Blocker.
-- Khi có phản hồi dev/BA: điền cột *Câu trả lời*, đổi *Trạng thái* → `Answered`.
-- Còn gap 🔴 Blocker `Open` ⇒ **chưa** chuyển sang `qa-designer`; đẩy sang `qa-planner`
-  (skill `questions-for-dev`) để chốt câu hỏi.
-
----
-
-## ⚠️ Checklist bắt buộc trước khi lưu file
-
-Trước khi lưu `DOC_GAPS.md`, kiểm tra **từng hàng** trong bảng gap:
-
-- [ ] **9 cột đủ** – đúng thứ tự: `ID | Loại | Mô tả gap | Vị trí (mục/nguồn) | Ảnh hưởng (chức năng / BR / AC) | Mức độ | Người trả lời | Trạng thái | Câu trả lời`
-- [ ] **Cột Vị trí không rỗng** – phải có tham chiếu cụ thể đến mục trong tài liệu nguồn (vd `§3 UC4 BR25`, `Appendix B loại 7`, `§4.b Screen 3`). Đây là cột hay bị bỏ thiếu nhất → gây lệch toàn bộ cột sau.
-- [ ] **Cột Ảnh hưởng = BR/AC references** – KHÔNG phải mức độ severity. Ví dụ đúng: `BR25, BR26 / AC-F01-33`. Nếu thấy "Blocker" / "High" ở đây → đang bị lệch cột.
-- [ ] **Cột Mức độ có emoji** – bắt buộc dùng: `🔴 Blocker` / `🟠 High` / `🟡 Medium` / `🟢 Low`. Không được ghi text thuần.
-- [ ] **Cột Người trả lời = vai trò** (PO / BA / Dev / Design / Content / DPO / QC Lead). Nếu thấy "Open" ở đây → đang bị lệch cột.
-- [ ] **Cột Trạng thái = Open / Answered**. Nếu thấy "—" ở đây → đang bị lệch cột.