@educa-corp/sdd-framework 0.8.1 → 0.9.1

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

@@ -1,358 +0,0 @@
-# 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ụ