update skill and docs

.claude/skills/sa-3-enablement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sa-3-enablement
-description: Giai đoạn 3 của quy trình Solution Architect — đồng hành cùng team trong lúc thi công. Dùng để biến kiến trúc thành thứ dev dùng được (architecture guideline, reference implementation, skeleton), dựng fitness function kiểm thử ràng buộc kiến trúc tự động trên CI, điều hành design review cho thay đổi chạm kiến trúc, trả lời câu hỏi thiết kế của dev, và quản lý sổ nợ kỹ thuật có chủ có hạn. Kích hoạt khi người dùng nói "chuẩn code", "architecture guideline", "reference implementation", "dev hỏi về thiết kế", "review thiết kế", "kiểm thử kiến trúc", "ArchUnit", "fitness function", "nợ kỹ thuật", "tech debt", "code không đúng kiến trúc", "lệch so với thiết kế". Input là SAD/ADR đã qua AG2; output vào sa-output/<PROJECT>/03-enablement/ và phải qua Gate AG3 (Build conformance) trước khi go-live.
+description: Giai đoạn 3 của quy trình Solution Architect — đồng hành cùng team trong lúc thi công. Dùng để lập gói bàn giao dev (HANDOFF - mục lục mọi đặc tả/contract/schema/ADR theo đường dẫn thật, checklist đủ-thiếu, dev ký đã nhận), biến kiến trúc thành thứ dev dùng được (architecture guideline, reference implementation, skeleton), dựng fitness function kiểm thử ràng buộc kiến trúc tự động trên CI, điều hành design review cho thay đổi chạm kiến trúc, trả lời câu hỏi thiết kế của dev, và quản lý sổ nợ kỹ thuật có chủ có hạn. Kích hoạt khi người dùng nói "bàn giao cho dev", "gói bàn giao", "handoff", "dev cần đọc gì", "chuẩn code", "architecture guideline", "reference implementation", "dev hỏi về thiết kế", "review thiết kế", "kiểm thử kiến trúc", "ArchUnit", "fitness function", "nợ kỹ thuật", "tech debt", "code không đúng kiến trúc", "lệch so với thiết kế". Input là SAD/ADR đã qua AG2; output vào sa-output/<PROJECT>/03-enablement/ và phải qua Gate AG3 (Build conformance) trước khi go-live.
 ---
 
 # GĐ3 · ENABLEMENT — Đồng hành thi công
@@ -8,7 +8,7 @@ description: Giai đoạn 3 của quy trình Solution Architect — đồng hàn
 Mục tiêu duy nhất: **kiến trúc trên giấy trở thành kiến trúc trong code** — và ở lại đó khi
 người viết tài liệu không còn ngồi cạnh.
 
-Output: `AGD` · `FIT` · `DREV` · `TDEBT` trong `sa-output/<PROJECT>/03-enablement/`
+Output: `HANDOFF` · `AGD` · `FIT` · `DREV` · `TDEBT` trong `sa-output/<PROJECT>/03-enablement/`
 
 ## Bốn nguyên tắc bất di bất dịch
 
@@ -30,13 +30,36 @@ Nạp thêm: `../sa-lifecycle/references/design-rules.md` (đặc biệt `D8`)
    source code hiện có, cấu hình CI, `ba-output/…/03-specification/` (`SRS`).
 2. **Kiểm AG2** — `SAD` đã `✅ Baselined` chưa, Security và SRE đã ký chưa? Chưa ⇒ báo rõ:
    ban hành guideline dựa trên kiến trúc chưa chốt sẽ phải ban hành lại.
-3. **Chọn phạm vi** — `--focus agd|fit|review|debt`. Ban hành guideline và dựng fitness
-   function là hai việc khác nhau về khối lượng.
+3. **Chọn phạm vi** — `--focus handoff|agd|fit|review|debt`. Ban hành guideline và dựng fitness
+   function là hai việc khác nhau về khối lượng. `handoff` chạy **đầu tiên**, ngay khi AG2 ký, và
+   chạy lại mỗi khi phạm vi bàn giao (US/module) mở rộng.
 4. **Hỏi người dùng** xác nhận ba điểm trên.
 
 Bỏ bước dừng khi lệnh có `go`.
 
-## Thực hiện — 4 hoạt động
+## Thực hiện — 5 hoạt động
+
+### 0 — Gói bàn giao dev `HANDOFF`  *(`--focus handoff`)*
+
+Điền `templates/dev-handoff.md`. **Không có nội dung mới** — chỉ đường dẫn thật + version + status
+chép từ header, để dev trả lời được một câu: *"tôi cần đọc gì, ở đâu, bản nào, ai ký, còn thiếu gì?"*
+
+Ba việc:
+
+1. **Điền checklist §2** cho phạm vi bàn giao (US/module/release): 9 dòng bộ BA (`BACKLOG`, `BR`,
+   `RBAC`, `SRS`/`AC` **mỗi US**, `NFR`, `API`, artifact design nếu `screen`, `RTM`) + 14 dòng bộ SA
+   (`QAS`, `SAD`, `ADR`, `ICD`, **`CTR` file thật**, `DOM`, `DAT`, **`PDM` + DDL/migration**, `SEC`, `INF`,
+   `FAIL`, `AGD` + reference implementation, `FIT`, sơ đồ đã deliver). Mở từng file, chép `Version`/
+   `Status` **thật**; không có file ⇒ để ☐ và ghi thiếu, **không ghi "dự kiến"**.
+2. **§2.3 việc dev tự quyết** — liệt kê đích danh để không ai tưởng đã có (đặt tên, thư viện tiện ích…).
+3. **§3 `OQ` chặn hành vi** — US còn `OQ` về hành vi ⇒ **loại khỏi gói**, ghi rõ; §4 kênh hỏi và SLA
+   trả lời (BA 1 ngày · SA 2 ngày).
+
+🔴 **Gói bàn giao có dòng ☐ ở §2.1 hàng 4–5 (SRS/AC) hoặc §2.2 hàng 14, 17 (`CTR`, `PDM`) là gói chưa
+bàn giao được** — dev sẽ phải tự đoán contract và schema, đúng hai chỗ tốn nhất để sửa sau.
+
+Người điều phối chạy `node .claude/skills/sa-3-enablement/scripts/handoff-check.mjs --handoff <file>`
+(H1–H5) và chép kết quả vào §5. Tech Lead + đại diện Dev BE/FE/QA ký §6 "đã nhận".
 
 ### 1 — Architecture Guidelines `AGD`  *(`--focus agd`)*
 
@@ -55,6 +78,7 @@ cách kiểm (`FIT-nn` hoặc `⚠️ Khuyến nghị`).
 | Reference implementation phải thể hiện | Vì sao |
 |---|---|
 | Cấu trúc module chuẩn | Dev copy cấu trúc, không copy nhầm |
+| Chạy migration của `PDM` và stub/client sinh từ `CTR` | Schema và contract có một nguồn sự thật, không chép tay |
 | Xử lý lỗi và mã lỗi theo `ICD` | Thống nhất từ file đầu tiên |
 | Log có correlation id | Thêm sau rất tốn |
 | Gọi phụ thuộc ngoài có timeout/retry theo `FAIL` | Đây là chỗ dev hay tự bịa nhất |
@@ -146,6 +170,8 @@ không chấp nhận ước lượng.
 
 **④ Danh sách `TD-nn` mới phát sinh** kèm chủ và hạn.
 
+**⑤ Trạng thái `HANDOFF`** — số dòng ✅/☐ ở §2, US bị loại khỏi gói vì `OQ`, ai đã ký §6.
+
 Rồi nhắc người dùng: AG3 cần **Tech Lead + QA + SRE ký**.
 
 ## Bẫy thường gặp