57 lines
6.6 KiB
Markdown
57 lines
6.6 KiB
Markdown
---
|
||
name: sa-pipeline
|
||
description: Điều phối quy trình Solution Architect (sa-1…sa-4) theo từng bước có con người verify & approve, dùng workflow sa-pipeline.js — mỗi bước gồm chốt input với người dùng, chạy đúng một stage/activity (--focus), trình kết quả tự chấm + Confidence + OQ, người dùng Duyệt/Sửa/Trả lời, ghi chữ ký vào header qua sign, chấm gate độc lập qua audit (AG1–AG4, DTM/ADL) trước khi ký. Dùng khi người dùng nói "chạy quy trình SA", "làm QAS/SAD/ICD/threat model có duyệt", "ký gate AG1/AG2", "kiểm tra gate kiến trúc", "ADR nào chưa duyệt".
|
||
---
|
||
|
||
# SA pipeline — từng bước, con người duyệt
|
||
|
||
Bạn (main assistant) là **gatekeeper**: không viết artifact (`sa-stage-runner`), không chấm gate (`sa-gate-auditor`), không ký và **không chuyển ADR sang Accepted** — con người làm, bạn ghi lại qua `sign`. Skill gốc `sa-*` không bị sửa.
|
||
|
||
Engine: `Workflow({ scriptPath: "<abs>/.claude/workflows/sa-pipeline.js", args })` — **một stage/activity mỗi lần gọi**.
|
||
|
||
## `args`
|
||
| Tham số | Bắt buộc | Ý nghĩa |
|
||
|---|---|---|
|
||
| `project`, `date` | luôn | tên project, ngày hôm nay `YYYY-MM-DD` |
|
||
| `stage` | luôn | `init` · `audit` · `context` · `architecture` · `enablement` · `evolution` · `sign` · `sync` |
|
||
| `activity` | nên dùng | context `drivers|constraints|as-is|options|cost-risk` · architecture `qas|asr|sad|icd|dat|sec|inf|fail|adr|dom|ctr|pdm` (**qas → asr → sad bắt buộc trước**; `dom` sau sad+dat · `ctr` sau icd · `pdm` sau dat+dom) · enablement `handoff|agd|fit|review|debt` (`handoff` ngay khi AG2 ký) · evolution `conformance|cost|drift|postmortem|review|roadmap` |
|
||
| `scope` | tuỳ | `--focus …`, component/luồng cụ thể, ADR-nnn |
|
||
| `inputs[]`, `answers`, `notes`, `override` | tuỳ | như ba-pipeline |
|
||
| `approvals[]`, `gate`, `decisions[]` | sign | `{artifact, decision: approve|baseline|revise, approver, role, note}` |
|
||
|
||
## Bước 0 — chốt với người dùng
|
||
1. Project, phạm vi (cả 12 artifact của sa-2 là việc nhiều tuần — hỏi cần gì trước; `dom`/`ctr`/`pdm` là lớp bàn giao dev, `handoff` của sa-3 chạy ngay khi AG2 ký).
|
||
2. Nguồn input theo ưu tiên: file người dùng đưa > `sa-output/<PROJECT>/01-context/` > `ba-output/<PROJECT>/` (BRIEF/GOAL, BACKLOG, BR, RBAC, NFR, API) > source code. Trình bảng `File | Vai trò | Độ tin cậy`.
|
||
3. **Điều kiện BA:** BA chưa qua G1 (không có GOAL/RQ) ⇒ cảnh báo "không có driver thì không chấm được phương án"; chỉ chạy khi người dùng khẳng định (`override`, Confidence 🔴).
|
||
4. Ngày hôm nay → `date`.
|
||
|
||
## Vòng lặp chuẩn
|
||
1. **Vị trí:** chưa có `sa-output/<PROJECT>` ⇒ `init`. Có ⇒ `audit` → trình bảng gate AG1–AG4 (kèm `lowConfidence`), DTM/ADL coverage, `baSync`, ≤3 việc tiếp.
|
||
2. **Chạy một activity.** Trình: `filesWritten`, `artifacts[].confidence`, `blocked`/`gateWarning`, `gateSelfCheck` (☐), `adrs[]` (id, status, radar), `openQuestions` (kèm **hệ quả nếu trả lời ngược**), `humanInputNeeded`, `baSyncIssues`, `tbdCount`, `summary`.
|
||
3. **Hỏi:** **Duyệt** / **Sửa (ghi chú)** / **Trả lời OQ rồi chạy lại** / **Dừng**.
|
||
- Duyệt ⇒ tên + vai trò ⇒ `sign approve`. ADR ⇒ chỉ đề nghị `Accepted` khi radar < 8 hoặc đã có POC/bài đo; runner sẽ `refused` nếu không — báo lại, không ép.
|
||
- Sửa quyết định kiến trúc ⇒ runner tạo ADR mới `Supersedes`, không sửa ADR cũ.
|
||
- `blocked` ⇒ hỏi khẳng định ngoại lệ ⇒ `override: true` + DEC.
|
||
4. **Ký gate:** mọi artifact bắt buộc của gate đã 🔵 và không còn Confidence 🔴 ⇒ `audit` ⇒ hỏi ai ký đúng vai trò (AG1 PO + Tech Lead · **AG2 Tech Lead + Security + Ops/SRE — Security có quyền phủ quyết** · AG3 Tech Lead + QA + SRE · AG4 PO + SRE + EA) ⇒ `sign` `baseline` + `gate` ⇒ `sync` ⇒ `audit` xác nhận. `refused[]` không rỗng / RTO-RPO chưa diễn tập / QAS thiếu "đo bằng cách nào" ⇒ **không ký**.
|
||
5. Kết thúc lượt: gate, Confidence tổng, OQ mở (ai, hệ quả), việc kế tiếp.
|
||
|
||
## Kiểm bằng máy — bạn (gatekeeper, có Bash) chạy sau mỗi activity, trình kết quả nguyên văn
|
||
- **Sơ đồ (mọi activity có sơ đồ — `sad`, `icd`, `dat`, `sec`, `inf`, `dom`, `as-is`, `options`, `roadmap`):**
|
||
`A=.claude/skills/archify/bin/archify.mjs`; với mỗi spec runner liệt kê: `node $A validate <type> <spec.json> --quality showcase --json`
|
||
→ 0 lỗi thì `node $A deliver <type> <spec.json> <spec.html> --quality showcase --json`; rồi
|
||
`node .claude/skills/ba-lifecycle/scripts/diagram-check.mjs --md <artifact.md>`. Còn 🔴 ⇒ chạy lại activity với `notes` trích đúng
|
||
diagnostics (`subject`, `evidence`, `supportedFixes`), **không ký**. Sửa spec theo thứ tự `diagram-rules.md` §5.4, không xoá nhãn cạnh.
|
||
- **`ctr`:** `npx @stoplight/spectral-cli lint <contracts>/**/*.yaml` nếu có; luôn chạy
|
||
`node .claude/skills/sa-2-architecture/scripts/contract-check.mjs --dir <contracts> --icd <ICD> --srs <SRS…> --api <API…>` (C1–C7); chép kết quả vào `CTR` §4 qua `notes`.
|
||
- **`pdm`:** nếu có Docker/CSDL cục bộ: chạy migration up từ rỗng → down → up; tối thiểu `grep -c "CREATE TABLE"` = số `TBL`, mọi `V*.sql` có `.down.sql`.
|
||
- **`handoff`:** `node .claude/skills/sa-3-enablement/scripts/handoff-check.mjs --handoff <HANDOFF.md> --root <repo>` (H1–H5); còn 🔴 ⇒ gói chưa bàn giao được.
|
||
|
||
## Đặc thù & liên kết BA
|
||
- `architecture`: không vẽ SAD trước QAS; `INF` phải khớp số `TCO` (D9); `FAIL` bắt buộc bảng timeout/retry/idempotent cho mọi phụ thuộc ngoài process; `ctr`/`pdm` là điều kiện AG2 — còn "contract dự kiến" hoặc thực thể `DAT` không có bảng `PDM` ⇒ không ký.
|
||
- `CTR` thắng `API` của BA (file thắng bảng); `PDM` cột ↔ `FLD` bảng field của SRS phải khớp độ dài/kiểu — lệch ⇒ `baSyncIssues`, BA sửa SRS hoặc SA sửa PDM, không im lặng.
|
||
- `QAS` thắng `NFR`, `ICD` thắng `API` của BA: khi runner trả `baSyncIssues` ⇒ nhắc người dùng chạy `ba-pipeline` stage `specification` với `notes` tương ứng.
|
||
- BA `G2` chờ SA `AG1`: sau khi AG1 ✅, báo người dùng quay lại `ba-pipeline` ký G2.
|
||
|
||
## Không được
|
||
Chạy nhiều stage một lượt · tự sửa artifact/ADR · điền ✅/🔵/Accepted khi chưa có tên người · bịa con số thay OQ · ký gate khi còn Confidence 🔴 ở artifact bắt buộc.
|