update skill and docs

.claude/skills/README-SA.md

@@ -16,8 +16,8 @@ Nền tảng lý thuyết của bộ này: [`../../solution-architect-role.md`](
 |---|---|---|---|---|---|
 | 0 | `sa-lifecycle` | *Điều phối* | "Tôi đang ở đâu, làm gì tiếp?" | Bảng trạng thái pipeline, `INDEX` | — |
 | 1 | `sa-1-context` | Bối cảnh | "Áp lực gì, ràng buộc gì, chọn phương án nào, tốn bao nhiêu?" | `CTX`, `OPT`, `TCO`, `ARISK` | **AG1** |
-| 2 | `sa-2-architecture` | Kiến trúc | "Hệ thống gồm gì, giao tiếp thế nào, hỏng thì sao?" | `QAS`, `ASR`, `SAD`, `ADR`, `ICD`, `DAT`, `SEC`, `INF`, `FAIL` | **AG2** |
-| 3 | `sa-3-enablement` | Thi công | "Làm sao kiến trúc tồn tại trong code và ở lại đó?" | `AGD`, `FIT`, `DREV`, `TDEBT` | **AG3** |
+| 2 | `sa-2-architecture` | Kiến trúc | "Hệ thống gồm gì, giao tiếp thế nào, hỏng thì sao — và dev code theo file nào?" | `QAS`, `ASR`, `SAD`, `ADR`, `ICD`, `DAT`, `SEC`, `INF`, `FAIL` + **`DOM`, `CTR`, `PDM`** (class diagram · OpenAPI/AsyncAPI · schema + DDL/migration) | **AG2** |
+| 3 | `sa-3-enablement` | Thi công | "Dev cần đọc gì, và làm sao kiến trúc tồn tại trong code?" | **`HANDOFF`**, `AGD`, `FIT`, `DREV`, `TDEBT` | **AG3** |
 | 4 | `sa-4-evolution` | Vận hành | "Chạy thật có đúng như cam kết không?" | `CONF`, `TRM`, `PMR` | **AG4** |
 | ⊕ | `sa-conformance` | *Xuyên suốt* | "Có chỗ nào đứt không?" | `DTM`, `ADL`, báo cáo coverage | Chặn AG2–AG4 |
 
@@ -48,8 +48,8 @@ D:\Kakao\Docs\.claude\skills\
 │       ├── design-rules.md         ← 12 quy tắc viết tài liệu kiến trúc (D1–D12)
 │       └── decision-radar.md       ← quyết định nào cần ADR, quyết định nào không
 ├── sa-1-context/       SKILL.md · GUIDE.md · templates/ (4)
-├── sa-2-architecture/  SKILL.md · GUIDE.md · templates/ (8)
-├── sa-3-enablement/    SKILL.md · GUIDE.md · templates/ (4)
+├── sa-2-architecture/  SKILL.md · GUIDE.md · templates/ (11 + contracts/ + diagrams/) · scripts/contract-check.mjs
+├── sa-3-enablement/    SKILL.md · GUIDE.md · templates/ (5) · scripts/handoff-check.mjs
 ├── sa-4-evolution/     SKILL.md · GUIDE.md · templates/ (3)
 └── sa-conformance/     SKILL.md · GUIDE.md · templates/ (2)
 ```
@@ -65,9 +65,12 @@ chuẩn bị gì, ví dụ hội thoại, lỗi thường gặp. **templates/**
 sa-output/<PROJECT>/
 ├── 00-index/            INDEX · DTM · ADL · GLOSSARY · DEC · OQ
 ├── 01-context/          CTX · OPT · TCO · ARISK
-├── 02-architecture/     ASR · QAS · SAD · ICD · DAT · SEC · INF · FAIL
-│   └── adr/             ADR-001_… · ADR-002_… · archive/
-├── 03-enablement/       AGD · FIT · DREV · TDEBT
+├── 02-architecture/     ASR · QAS · SAD · ICD · DAT · SEC · INF · FAIL · DOM · CTR · PDM
+│   ├── adr/             ADR-001_… · ADR-002_… · archive/
+│   ├── contracts/       openapi/*.yaml · asyncapi/*.yaml · partners/*.yaml   ← file máy đọc, thắng mọi bảng
+│   ├── schema/<kho>/    V001__*.sql · V001__*.down.sql · seed/               ← DDL + migration có rollback
+│   └── diagrams/        *.<type>.json (spec Archify) · *.html (đã deliver)
+├── 03-enablement/       HANDOFF · AGD · FIT · DREV · TDEBT
 └── 04-evolution/        CONF · TRM · PMR
 ```
 
@@ -105,6 +108,9 @@ có `Supersedes:`. ADR bị `Rejected` vẫn giữ lại.
 | `IF-nnn` | Interface | 2 |
 | `THR-nn` | Mối đe doạ (STRIDE) | 2 |
 | `FM-nn` | Failure mode | 2 |
+| `TBL-nnn` | Bảng vật lý trong `PDM` | 2 |
+| `MIG-nnn` | Migration (cặp up/down) trong `PDM` §4 | 2 |
+| `CTR-nn` | File contract trong `CTR` | 2 |
 | `FIT-nn` | Fitness function | 3 |
 | `DREV-nnn` | Mục design review | 3 |
 | `TD-nn` | Nợ kỹ thuật | 3 |
@@ -124,6 +130,9 @@ ID **không bao giờ tái sử dụng**. Bỏ một mục ⇒ đánh dấu `[DR
 /sa-2-architecture Settlement --focus qas         # lượng hoá NFR (làm TRƯỚC mọi thứ)
 /sa-2-architecture Settlement --focus sad         # phân rã + C4
 /sa-2-architecture Settlement --focus adr  "..."  # viết một ADR
+/sa-2-architecture Settlement --focus ctr         # sinh OpenAPI/AsyncAPI thật từ ICD
+/sa-2-architecture Settlement --focus pdm         # schema vật lý + DDL/migration
+/sa-3-enablement Settlement --focus handoff       # gói bàn giao dev (chạy ngay khi AG2 ký)
 /sa-3-enablement Settlement --focus fit           # dựng fitness function
 /sa-3-enablement Settlement --focus review "..."  # review một thay đổi
 /sa-4-evolution Settlement --focus conf --period 2026-09
@@ -147,7 +156,9 @@ thiếu, tóm tắt cách hiểu, rồi *chờ bạn xác nhận* mới làm. Th
 | Tuần 2 | `--focus sad` |
 | Tuần 3 | `--focus icd` · `--focus dat` |
 | Tuần 4 | `--focus sec` · `--focus inf` · `--focus fail` |
+| Tuần 5 | `--focus dom` · `--focus ctr` · `--focus pdm` — lớp bàn giao dev |
 | Trước khi BA trình G3 | `/sa-conformance --gate AG2` → trình AG2 |
+| Ngày AG2 ký | `/sa-3-enablement --focus handoff` → dev ký đã nhận |
 | Tuần 1 thi công | `/sa-3-enablement --focus agd` |
 | Tuần 2–4 thi công | `--focus fit` theo lộ trình 4 tuần |
 | Suốt thi công | `--focus review` mỗi thay đổi chạm kiến trúc · `--focus debt` mỗi lệch |
@@ -158,6 +169,24 @@ thiếu, tóm tắt cách hiểu, rồi *chờ bạn xác nhận* mới làm. Th
 
 ---
 
+## 6b. Sơ đồ — chuẩn Archify
+
+Mọi sơ đồ của bộ SA tuân **chuẩn và phong cách Archify** ([`ba-lifecycle/references/diagram-rules.md`](ba-lifecycle/references/diagram-rules.md),
+gói đã nhúng ở `archify/`): mỗi sơ đồ = **spec JSON** (`diagrams/<ARTIFACT>_<slug>.<type>.json`,
+`quality_profile: showcase`, `archify validate` 0 lỗi) + **mermaid** có marker trong `.md` + **bảng đi kèm**.
+
+| Sơ đồ SA | Loại Archify |
+|---|---|
+| C4 Context/Container/Component, deployment, ranh giới tin cậy, phương án mức khối | `architecture` |
+| Luồng chính có nhánh lỗi | `sequence` |
+| Ownership / luồng dữ liệu | `dataflow` |
+| Phụ thuộc roadmap | `workflow` |
+| ERD khái niệm, class diagram | `mermaid-only` |
+
+Một đường chính, ≤ 12 node, nhãn cạnh ghi giao thức + sync/async, không màu. Kiểm:
+`node .claude/skills/ba-lifecycle/scripts/diagram-check.mjs --md <artifact>`. Spec mẫu đã pass:
+`sa-2-architecture/templates/diagrams/`.
+
 ## 7. Quan hệ với bộ skill BA
 
 Hai bộ **chạy đan xen, không nối tiếp**. Bảng chốt thứ tự: