update skill and docs

.claude/skills/README-BA.md

@@ -214,35 +214,38 @@ Hai bộ **không thay thế nhau**:
 
 ---
 
-## 6b. Sơ đồ trong tài liệu
+## 6b. Sơ đồ trong tài liệu — chuẩn Archify
 
-Mọi sơ đồ vẽ bằng **mermaid**, không ASCII art — GitHub/GitLab/Confluence và Artifact của
-Claude Code render thẳng, `git diff` đọc được từng cạnh, và ký hiệu là chuẩn chứ không tự chế.
+Mọi sơ đồ của bộ BA (và bộ SA, SAD) tuân **tiêu chuẩn và phong cách [Archify](https://github.com/tt-a1i/archify)**
+(gói MIT đã nhúng ở `archify/`, không cần cài thêm). Toàn bộ quy tắc ở
+[`ba-lifecycle/references/diagram-rules.md`](ba-lifecycle/references/diagram-rules.md). Ba câu chốt:
 
-| Sơ đồ | Loại mermaid | Sinh ở |
-|---|---|---|
-| Ranh giới hệ thống | `flowchart LR` + `subgraph` | `BRIEF` §5.3 |
-| Ma trận stakeholder | `quadrantChart` | `STAKEHOLDER` §2 |
-| 5-Why đào pain point | `flowchart TD` | `ELICITATION` §A9 |
-| Quy trình AS-IS / TO-BE | `flowchart TD` | `PROCESS` A1, B1 |
-| **Use case** | `flowchart LR` + `subgraph` | `BACKLOG` §0 |
-| Cây phân rã RQ→US | `flowchart LR` | `BACKLOG` §1 |
-| Vòng đời trạng thái | `stateDiagram-v2` | `BR` §3 |
-| **ERD khái niệm** | `erDiagram` | `BR` §4 |
-| Điều hướng màn hình | `flowchart LR` | `srs-part2/screen` §2.2 |
-| **Sequence** *(có nhánh lỗi)* | `sequenceDiagram` | `srs-part2/screen` §2.3.4, `api-service` §2.3 |
-| Data lineage | `flowchart LR` | `srs-part2/data-pipeline` §2.2 |
-| Phụ thuộc job | `flowchart LR` | `srs-part2/batch-job` §2.2 |
-| Phân loại Defect/CR/Spec gap | `flowchart TD` | `CR` §0 |
+1. **Một sơ đồ = spec JSON Archify + mermaid trong `.md` + bảng đi kèm.** Spec
+   (`diagrams/<ARTIFACT>_<slug>.<type>.json`, `quality_profile: showcase`) là nguồn sự thật về topology;
+   mermaid có marker `<!-- archify: <type> · <spec> -->` là bản chiếu để GitHub/Confluence render và
+   `git diff` đọc được; bảng để truy vết và test (W13).
+2. **Một đường chính, ≤ 12 node, nhãn cạnh là điều kiện/giao thức/sync-async, không màu.** Quá 12 node
+   ⇒ tách sơ đồ.
+3. **Kiểm bằng máy:** `archify validate … --quality showcase` 0 lỗi, rồi
+   `node .claude/skills/ba-lifecycle/scripts/diagram-check.mjs --md <artifact>` xanh trước khi trình gate.
 
-🔴 **Quy tắc W13: mỗi sơ đồ phải có bảng đi kèm.** Sơ đồ để nhìn, bảng để truy vết và test.
-Sơ đồ không diễn đạt được điều kiện chính xác, ai được làm, mã lỗi nào, ai chịu trách nhiệm.
-Chi tiết cú pháp và mẫu chuẩn: [`ba-lifecycle/references/diagram-rules.md`](ba-lifecycle/references/diagram-rules.md).
+| Sơ đồ | Loại Archify | Mermaid | Sinh ở |
+|---|---|---|---|
+| Ranh giới hệ thống | `architecture` | `flowchart LR` + `subgraph` | `BRIEF` §5.3 |
+| Quy trình AS-IS / TO-BE | `workflow` | `flowchart TD` | `PROCESS` A1, B1 |
+| Vòng đời trạng thái | `lifecycle` | `stateDiagram-v2` | `BR` §3 |
+| Điều hướng màn hình | `workflow` | `flowchart LR` | `srs-part2/screen` §2.2 |
+| **Sequence** *(có nhánh lỗi)* | `sequence` | `sequenceDiagram` | `srs-part2/screen` §2.3.4, `api-service` §2.3 |
+| Data lineage | `dataflow` | `flowchart LR` | `srs-part2/data-pipeline` §2.2 |
+| Phụ thuộc job | `workflow` | `flowchart LR` | `srs-part2/batch-job` §2.2 |
+| Phân loại Defect/CR/Spec gap | `workflow` | `flowchart TD` | `CR` §0 |
+| Use case · cây RQ→US · 5-Why · ERD khái niệm · ma trận 2×2 | `mermaid-only` | `flowchart` · `erDiagram` · `quadrantChart` | `BACKLOG` §0–§1 · `ELICITATION` §A9 · `BR` §4 · `STAKEHOLDER` §2 |
 
-**Không thuộc phạm vi BA:** C4, ADR, class diagram, threat model, schema vật lý — đó là việc
-của Solution Architect, làm bằng bộ `sa-*` (xem §6c).
+Spec mẫu đã validate pass: `ba-2-analysis/templates/diagrams/` (workflow, lifecycle),
+`ba-3-specification/templates/diagrams/` (dataflow), `sa-2-architecture/templates/diagrams/` (architecture, sequence).
 
----
+**Không thuộc phạm vi BA:** C4, ADR, class diagram (`DOM`), threat model, schema vật lý + DDL/migration (`PDM`),
+file OpenAPI/AsyncAPI (`CTR`) — đó là việc của Solution Architect, làm bằng bộ `sa-*` (xem §6c).
 
 ## 6c. Quan hệ với bộ skill SA (`sa-*`)
 
@@ -261,7 +264,9 @@ Bốn chỗ hai bộ giao nhau, và bên nào thắng khi lệch:
 | Artifact BA | Artifact SA | Thắng khi lệch |
 |---|---|---|
 | `NFR` | `QAS` | **`QAS`** — BA ghi nhu cầu, SA chốt con số và cách đo |
-| `API` (BA đề xuất, "chờ BE xác nhận") | `ICD` | **`ICD`** — SA chính là người xác nhận đó |
+| `API` (BA đề xuất, "chờ BE xác nhận") | `ICD` → `CTR` (file OpenAPI/AsyncAPI) | **File contract trong `CTR`** — SA xác nhận qua `ICD` rồi sinh file; `API` ghi `operationId` |
+| `SRS` PART 2 bảng field `FLD-*` | `PDM` (schema vật lý) | Cùng kiểu/độ dài/null — lệch ⇒ `OQ`, không im lặng chọn một bên |
+| `BR` ràng buộc dữ liệu / tính toán | `DOM` (domain model) | `BR` là nguồn; `DOM` nói invariant sống ở class nào |
 | `RBAC` | `SEC` §3.1 | Bổ sung nhau — `SEC` map vai trò nghiệp vụ xuống cơ chế kỹ thuật |
 | `BR` ép ràng buộc kiến trúc | `ADR` | `BR` là nguồn, `ADR` là quyết định |