@educa-corp/sdd-framework 0.2.3 → 0.2.5

package/docs/explain/08-review-tech-docs.md

@@ -0,0 +1,79 @@
+[← /generate-tech-docs](07-generate-tech-docs.md) · [Explain Home](README.md) · [Next: /generate-code →](09-generate-code.md)
+
+# 08 · `/review-tech-docs` — Review Technical Design (7 dimension + ký T7)
+
+> **Một câu.** Review tech-design qua **7 dimension T1–T7** (kiến trúc, entity, BDD trace, cross-PRD conflict, nội bộ, cấu trúc, và cổng ký liên team), sinh findings + `--resume`.
+
+---
+
+## Vấn đề giải quyết
+
+Chốt sai contract kỹ thuật = rework tốn kém cho nhiều team. `/review-tech-docs` soát tech-design đa chiều **trước khi đốt budget code**, và đảm bảo FE/App/BE **đồng thuận contract** qua sign-off T7.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Design, sau `/generate-tech-docs`.
+- **Đặc biệt:** read-only (chỉ báo findings); có **Resume Mode** áp finding accepted.
+
+---
+
+## Input / Output
+
+**Input:** tech-design (một doc full-stack) + CLAUDE.md §2 + core-entities + mọi BDD của PRD (system/web/app).
+
+**Output:** findings file + cập nhật `@trace.sign_off` khi đủ.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+Chạy 7 dimension (mỗi cái phân loại severity + auto-fixable):
+
+| Dim | Tên | Soi gì | Auto-fix |
+|-----|-----|--------|----------|
+| **T1** | Architecture Alignment | Vi phạm CLAUDE.md §2 (controller gọi repo, logic trong controller, pattern cấm) — **luôn critical** | ❌ người quyết |
+| **T2** | Entity Consistency | Đối chiếu core-entities (entity thiếu, tên field lệch, quan hệ khác) | một phần (field → canonical) |
+| **T3** | BDD Traceability | 2 chiều design ↔ scenario, **theo đúng lane platform** (system/web/app SC không so chéo) | một phần |
+| **T4** | Cross-PRD Endpoint Conflict | grep endpoint/entity ở doc PRD khác, **load-on-hit**; va chạm shape/behavior → critical | ❌ |
+| **T5** | Internal Consistency | Sequence vs mô tả, API spec vs code sketch, ref không định nghĩa | một phần |
+| **T6** | Structural Completeness | Section chuẩn có mặt & không rỗng | ✅ thêm skeleton |
+| **T7** | Cross-Team API Contract | **Cổng ký liên team** — chỉ khi doc có backend (system) + không phải `api_source: existing` | sign-off block auto-fix |
+
+**T7 chi tiết:**
+- Đọc block `@trace.sign_off` (be_team / fe_team / app_team / sa); vắng → thêm skeleton.
+- Cross-check contract §4 vs web & app BDD → đảm bảo mọi team đồng thuận trước khi implement.
+
+Sau phân tích → ghi findings; **Resume Mode** áp finding `accepted`/`modified`.
+
+---
+
+## Checkpoint & Gate
+
+- 🔒 **T7 sign-off** — contract liên team chưa ký đủ (be/fe/app/sa) → chưa mở khoá code phía tiêu thụ.
+- Read-only — không tự sửa; findings qua Board → `--resume`.
+
+---
+
+## Cơ chế đặc biệt
+
+- **T4 load-on-hit** — không nạp full doc PRD khác, chỉ grep path/entity rồi đọc đoạn khớp → rẻ.
+- **SC scope theo platform** — `system UC1-SC1` ≠ `web UC1-SC1`; match trong đúng lane.
+- **T7 skip khi brownfield** (`api_source: existing`) — contract đã do PO chốt, không có design mới để đồng thuận.
+- **T1 luôn critical** — vi phạm kiến trúc chặn cứng.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **7 dimension trong một lệnh** — nặng; T4 (cross-PRD) và T7 (sign-off) là hai phần đắt nhất. T4 dùng grep khéo để rẻ; T7 phụ thuộc con người ký.
+- **T7 sign-off là quy trình đa người** — dễ nghẽn nếu một team chậm ký. Đáng có cơ chế nhắc/timeout.
+- **Chồng lấn với conflict resolution ở generate-bdd (system)** — cả hai lo contract cross-platform. Ranh giới: BDD-system chốt *hành vi contract*, T7 chốt *shape API + đồng thuận team*.
+- **Không dùng review-fanout** (khác `/review-context`/`/refine-prd`) — 7 dimension chạy tuần tự trong một session. Với doc lớn có thể lost-in-the-middle; cân nhắc fan-out.
+
+---
+
+## Kết nối
+
+**Trước:** [`/generate-tech-docs`](07-generate-tech-docs.md) · **Sau:** đủ ký T7 → [`/generate-code {feature}`](09-generate-code.md).

package/docs/explain/09-generate-code.md

@@ -0,0 +1,78 @@
+[← /review-tech-docs](08-review-tech-docs.md) · [Explain Home](README.md) · [Next: /review-code →](10-review-code.md)
+
+# 09 · `/generate-code` — Sinh mã nguồn từ BDD
+
+> **Một câu.** Sinh code từ một `.feature` approved + tech-design, phát hiện **drift per-UC**, gắn `@trace` ở boundary, nối/lấp **seam & stub** (chống mồ côi), verify build, ghi trace state — với comprehension checkpoint.
+
+---
+
+## Vấn đề giải quyết
+
+Code là **hệ quả của spec**. Command biến scenario thành code sao cho: mỗi boundary có trace, chỉ chạm phần drift (không đập refactor mù), không sinh code không có `.feature` backing, và build được trước khi commit.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Implementation, sau BDD + tech-docs.
+- **Gate vào:** cảnh báo mềm DS1 (BDD chưa approved), DS2 (design-spec), DS3 (tech-doc contract).
+
+---
+
+## Input / Output
+
+**Input:** `.feature` (hoặc UC-ID) + tech-design §4 + CLAUDE.md §2/§3/§5 + `.trace/…/{UC-ID}-{platform}.tsv` + `_seams.tsv`.
+
+**Output:** file code (tag `@trace` boundary) + trace row `.tsv` + cập nhật `_seams.tsv`.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Guard BDD & Design Spec** — DS1/DS2/DS3 cảnh báo mềm nếu nguồn chưa chốt.
+2. **Phase Detection** — `--phase=ui` (FE Phase 1: UI + mock API; **mock source hybrid** = ưu tiên tech-doc §4 contract, fallback System BDD) · `--phase=integration` (thay mock bằng API thật) · default (BE/full-stack). `system` → bỏ flag.
+3. **Figma Dev Mode MCP Check** (sinh UI) — đọc frame Figma độ trung thực cao cho codegen.
+4. **Read Trace State** — so `bdd_version`/spec với `.tsv` → phân loại **new / drifted / synced-skip**.
+5. **Package Placement** — đặt code đúng `code_base_package` + strategy (by-layer/by-feature), chống phân mảnh.
+6. **Seam & Stub Ledger** (`_seams.tsv`) — trước khi tạo chỗ giả lập, ghi sổ:
+   - `seam` = gọi ra port cross-UC (UC khác sở hữu) · `stub` = method trắng nội-feature (logic thuộc BDD khác của chính feature).
+   - Trạng thái: `PENDING` (chưa có hàng thật) · `READY` 🔴 (hàng thật đã có nhưng chưa nối) · `RESOLVED`.
+   - Vá 2 lỗi kinh điển: **hàm trắng mồ côi** (no-op khi ghép luồng) và **hàm thật mồ côi** (đẻ hàm mới thay vì lấp stub cũ).
+7. **File Scan** — quét file hiện có để quyết CREATE/EXTEND/FILL/SKIP.
+8. **CHECKPOINT — Code Generation Plan** — 🛑 trình: scenarios (X new, Y drifted, Z synced-skip) · CREATE (mới) · **EXTEND (ADD-ONLY, cấm full Write)** · **FILL** (lấp stub tại chỗ, không đẻ method song song) · SKIP + danh sách member GIỮ NGUYÊN (UC khác). **Scope Lock**: chỉ đọc/implement UC target.
+9. **Branch** `feature/{TICKET}-{slug}`.
+10. **Generate** theo **thứ tự layer từ CLAUDE.md §2**; tag `@trace.implements/source` ở boundary.
+11. **Mock/Integration** — layer mock (`--phase=ui`) hoặc thay adapter thật (`--phase=integration`).
+12. **Self-Review (3 vòng)** → **Build Verify** (`{build_command}`, ≤3 retry) → **Write Trace State** → **Refresh Panel Mirror** (Living Docs umbrella) → **Commit** (sau khi duyệt).
+
+---
+
+## Checkpoint & Gate
+
+- 🛑 **Comprehension checkpoint** (Code Generation Plan) — điểm dừng chính; Dev xác nhận drift + scope đúng.
+- Build phải pass trước commit.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Seam & Stub Ledger** — cơ chế tinh vi nhất: giải quyết vấn đề "sinh code từng BDD rời tạo hàm mồ côi". `READY` là cờ 🔴 để lần sau nối hàng thật vào.
+- **Scope Lock + ADD-ONLY + FILL** — bảo toàn code UC khác trong file dùng chung; EXTEND chỉ Edit thêm, FILL lấp stub tại chỗ.
+- **Mock source hybrid** — mock shape ưu tiên contract thật để đỡ rework lúc integration.
+- **3 vòng self-review + build ≤3 retry** — hai lớp tự kiểm trước khi giao.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Command nặng nhất về logic thực thi** — 12 bước, nhiều nhánh (phase, drift, seam, scope lock). Đây là nơi bug/tối ưu tác động trực tiếp code chất lượng.
+- **Seam ledger phụ thuộc kỷ luật ghi sổ** — nếu một lần gen quên ghi `_seams.tsv`, cơ chế chống mồ côi thủng. Đáng có validate.
+- **`--phase=ui` với mock từ System BDD (không contract)** → shape có thể lệch → rework ở integration. Chi phí này giảm nếu BE publish tech-doc §4 trước.
+- **Build verify ≤3 retry** — nếu 3 lần fail thì sao? Đáng làm rõ hành vi khi vượt retry.
+- **Refresh Panel Mirror** chỉ local umbrella — trạng thái Living Docs phụ thuộc `/sync` để lan.
+
+---
+
+## Kết nối
+
+**Trước:** [`/review-tech-docs`](08-review-tech-docs.md) · **Sau:** lần đầu → [`/review-code`](10-review-code.md); gen lại → [`/dev-gen-test`](12-dev-gen-test.md).

package/docs/explain/10-review-code.md

@@ -0,0 +1,70 @@
+[← /generate-code](09-generate-code.md) · [Explain Home](README.md) · [Next: /map-testids →](11-map-testids.md)
+
+# 10 · `/review-code` — Review code (read-only, 4 dimension)
+
+> **Một câu.** Soát code vừa sinh qua **4 dimension** (traceability, layer, coding standards, spec compliance) — **chỉ báo findings, không tự sửa** — và có thể đề xuất ghi lesson.
+
+---
+
+## Vấn đề giải quyết
+
+"AI tự fix tự review" = lặp lỗi. `/review-code` tách vai review khỏi generate: một vòng đọc độc lập đối chiếu code với spec + CLAUDE.md, báo cáo để Dev/Lead quyết.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Implementation, sau `/generate-code` (lần đầu).
+- **Đặc biệt:** **read-only** — bỏ qua checkpoint ghi-file, không commit, không auto-fix.
+
+---
+
+## Input / Output
+
+**Input:** code của UC + `.feature` + CLAUDE.md §2/§3 + trace `.tsv`.
+
+**Output:** báo cáo findings (`Output Artifacts: none (read-only)`) + tuỳ chọn đề xuất lesson.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+Chạy checklist 4 dimension:
+
+| # | Dimension | Kiểm gì |
+|---|-----------|---------|
+| 1 | **Traceability** | Mỗi controller endpoint có `@trace.implements`? Test có `@trace.verifies`? Tag đúng layer? `.tsv` cập nhật chưa (stale → chạy `/validate-traces` trước)? |
+| 2 | **Layer Architecture** (CLAUDE.md §2) | Class đúng layer? Phụ thuộc đúng chiều? Không bypass layer? |
+| 3 | **Coding Standards** (CLAUDE.md §3) | Naming? Response wrapper nhất quán? Exception không bị nuốt? Không magic number / log dữ liệu nhạy cảm? Transaction đúng? |
+| 4 | **Spec Compliance** | Mỗi scenario có implementation? Không endpoint không tài liệu (code không có spec backing)? |
+
+Sau review → **Đề xuất ghi Lessons** (tuỳ chọn) qua step `capture-lesson`: nếu phát hiện lỗi lặp lại → đề xuất ghi guardrail vào `project-lessons.md` (L1 phân giải file → L2 dựng lesson → L3 dedup → L4 ghi → L5 xác nhận).
+
+---
+
+## Checkpoint & Gate
+
+- Không gate chặn — báo cáo tư vấn. Dev tự sửa (không phải AI auto-fix).
+
+---
+
+## Cơ chế đặc biệt
+
+- **Read-only nghiêm ngặt** — thể hiện nguyên tắc "review tách khỏi generate".
+- **Tự phát hiện trace stale** → nhắc chạy `/validate-traces` trước để review chính xác.
+- **Cầu nối với `/learn`** — review là nơi tự nhiên phát hiện pattern lặp → đề xuất lesson.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Không auto-fix có chủ đích** — nhưng nghĩa là mọi finding cần vòng người sửa. Với lỗi cơ học (thiếu tag `@trace`), cân nhắc một `--fix` an toàn giống `/review-context`?
+- **Checklist tĩnh 4 dimension** (không fan-out) — với file code lớn có thể sót. Nhẹ hơn review tài liệu vì scope hẹp (1 UC).
+- **Phụ thuộc `.tsv` không stale** — nếu stale, dimension 1 kém tin cậy; đã có cơ chế nhắc validate-traces.
+- **Đề xuất lesson là điểm mạnh** — biến review thành tích luỹ tri thức; nhưng phụ thuộc người xác nhận L5.
+
+---
+
+## Kết nối
+
+**Trước:** [`/generate-code`](09-generate-code.md) · **Sau:** pass → [`/dev-smoke-test`](14-dev-smoke-test.md) hoặc tạo PR; lỗi lặp → [`/learn`](27-learn.md).

package/docs/explain/11-map-testids.md

@@ -0,0 +1,69 @@
+[← /review-code](10-review-code.md) · [Explain Home](README.md) · [Next: /dev-gen-test →](12-dev-gen-test.md)
+
+# 11 · `/map-testids` — Dán test-id ổn định cho UI (FE)
+
+> **Một câu.** Gắn **test-id ổn định** vào các element có hành động trên UI FE và ghi bản đồ selector vào tech-doc §4.5.6 — làm cầu nối để QC Playwright bám selector không vỡ.
+
+---
+
+## Vấn đề giải quyết
+
+Test tự động (Playwright) vỡ khi selector đổi (class/text thay đổi). `/map-testids` chuẩn hoá **test-id ổn định** cho mọi element tương tác, đảm bảo component tái dùng forward được test-id, và ghi map để QC dùng — tách concern "làm UI test được" khỏi "viết test".
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Tech Design / Implementation (FE), giữa code FE và QC.
+- **Chặn cứng:** chỉ FE/App (platform guard) — BE không có UI.
+
+---
+
+## Input / Output
+
+**Input:** UI code FE (element có action) + catalog component tái dùng + tech-doc §4.5.
+
+**Output:** code FE được patch test-id + map §4.5.6 Test Selectors trong tech-doc.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+| Step | Việc |
+|------|------|
+| **0 · Platform guard** | Chỉ FE/App; else STOP |
+| **1 · Thu thập element có action** | Quét UI tìm element người dùng tương tác (nút, ô nhập, link…) |
+| **2 · Phân giải test-id ổn định** | Đặt test-id ổn định (không phụ thuộc text/class dễ đổi) cho mỗi element |
+| **3 · Đảm bảo component tái dùng forward test-id** | Component dùng lại (catalog) phải cho phép truyền test-id xuống — sửa component nếu chưa |
+| **4 · Patch usage site** (chỉ EXTEND) | Gắn test-id vào nơi dùng, chỉ thêm (không viết đè) |
+| **5 · Ghi/làm mới map §4.5.6** | Ghi bảng Test Selectors vào tech-doc để QC bám |
+| **6 · Handoff** | Bàn giao cho QC (`/qc-*`) |
+
+---
+
+## Checkpoint & Gate
+
+- Không gate chặn; EXTEND-only khi patch (an toàn).
+
+---
+
+## Cơ chế đặc biệt
+
+- **Test-id ổn định** — chống test vỡ do đổi visual; nguyên tắc "selector là contract QC↔FE".
+- **Forward test-id qua component tái dùng** — sửa gốc component để test-id lan xuống, không hardcode từng chỗ.
+- **Map ở §4.5.6 tech-doc** — QC đọc từ một nguồn, không tự dò.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Lệnh cầu nối FE→QC** — vị trí pipeline hơi mờ (giữa Tech Design & Code). Chạy sớm quá thì UI chưa xong, muộn quá thì QC phải chờ. Đáng làm rõ thời điểm tối ưu.
+- **Phụ thuộc catalog component tái dùng** — nếu component không forward được prop test-id, Step 3 phát sinh sửa lan rộng.
+- **EXTEND-only** an toàn nhưng nếu test-id cũ sai thì không tự sửa.
+- **Không bắt buộc trong golden path** — dễ bị bỏ qua, khiến QC selector giòn. Cân nhắc tích hợp vào `/generate-code --phase=ui`.
+
+---
+
+## Kết nối
+
+**Trước:** [`/generate-code`](09-generate-code.md) (UI FE) · **Sau:** [`/qc-*`](15-qc-analyze.md) dùng selector đã map.

package/docs/explain/12-dev-gen-test.md

@@ -0,0 +1,66 @@
+[← /map-testids](11-map-testids.md) · [Explain Home](README.md) · [Next: /dev-run-test →](13-dev-run-test.md)
+
+# 12 · `/dev-gen-test` — Sinh bộ tự-kiểm của Dev
+
+> **Một câu.** Sinh bộ **self-test nhanh** (unit/integration theo platform) bám scenario, gắn `@trace.verifies`, để Dev tự kiểm code vừa sinh — trước QC chính thức.
+
+---
+
+## Vấn đề giải quyết
+
+Sau `/generate-code`, Dev cần một lớp test nhanh để bắt lỗi hiển nhiên tại chỗ. Đây **không** phải bộ test chính thức (đó là QC) — mà là smoke của dev, gắn với cột `dev_selftest`.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Dev Self-Test, sau `/generate-code`.
+- **Tiền đề:** code build được + `.feature`.
+
+---
+
+## Input / Output
+
+**Input:** code UC + `.feature` + `active_module`/`platform_type` + stack-profile (test pattern).
+
+**Output:** file test (tag `@trace.verifies={UC-ID}`, `@trace.test_type=unit|integration`) + cập nhật trace + Panel Mirror.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Service Detection** — route service (umbrella) / single.
+2. **CHECKPOINT — Test Plan** — 🛑 trình kế hoạch test (loại test, scenario phủ) → chờ Y.
+3. **Generate** — sinh test theo test pattern của stack (từ stack-profile): unit test cho logic, integration cho boundary; mỗi test tag `@trace.verifies` + `@trace.test_type`.
+4. **Checklist** — tự kiểm bộ test đủ phủ scenario.
+5. **Write Trace State** — cập nhật `.tsv` (`test_count`).
+6. **Refresh Panel Mirror** — làm mới Living Docs local (umbrella).
+
+---
+
+## Checkpoint & Gate
+
+- 🛑 CHECKPOINT Test Plan trước generate.
+- Không gate chặn downstream.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Theo test pattern của stack** — đọc stack-profile thay vì hardcode → cùng lệnh chạy cho java-spring/react/flutter…
+- **Tag test_type** phân biệt unit/integration.
+- **Orthogonal với QC** — bộ này phục vụ `dev_selftest`, không phải `qc_status`.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Ranh giới với QC** — dev-gen-test sinh test "nhanh", qc-design-test sinh test-case "chính thức". Có thể trùng công sức viết test 2 lần. Đáng xem có tái dùng được không.
+- **Phụ thuộc stack-profile `test_types`** — stack thiếu khai báo → test kém định hình.
+- **CHECKPOINT cho mọi lần** — với thay đổi nhỏ có thể là ma sát; cân nhắc short-circuit.
+
+---
+
+## Kết nối
+
+**Trước:** [`/generate-code`](09-generate-code.md) · **Sau:** [`/dev-run-test`](13-dev-run-test.md).

package/docs/explain/13-dev-run-test.md

@@ -0,0 +1,69 @@
+[← /dev-gen-test](12-dev-gen-test.md) · [Explain Home](README.md) · [Next: /dev-smoke-test →](14-dev-smoke-test.md)
+
+# 13 · `/dev-run-test` — Chạy self-test + chẩn lỗi, ghi `dev_selftest`
+
+> **Một câu.** Chạy bộ self-test theo lệnh test của platform, chẩn đoán lỗi, và ghi kết quả vào cột **`dev_selftest`** của trace.
+
+---
+
+## Vấn đề giải quyết
+
+Sinh test chưa đủ — phải chạy và biết pass/fail. Command chạy test đúng service/platform, phân tích lỗi, và ghi trạng thái smoke của dev vào trace (độc lập với QC).
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Dev Self-Test, sau `/dev-gen-test`.
+- **Đặc biệt:** chạy lệnh shell **bên trong** `service_root` (umbrella).
+
+---
+
+## Input / Output
+
+**Input:** bộ self-test + `conventions.test_command` (theo service) + `platform_type`.
+
+**Output:** cột `dev_selftest` trong `.tsv` + Panel Mirror; nếu fail → chẩn đoán.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Service Detection** + **Submodule Working Directory** — xác định thư mục chạy.
+2. **Run** — chạy test theo platform (scoped để feedback nhanh):
+   | platform_type | Lệnh (ví dụ) |
+   |---------------|--------------|
+   | backend | java-spring (mvn), golang (go test), dotnet, php-laravel, pytest |
+   | web-frontend | Vitest / Jest; E2E Playwright / Cypress |
+   | mobile | Flutter test, React Native, iOS (xcodebuild), Android |
+3. **Analyze Failures** — chẩn lỗi theo platform (điều gì fail, tại sao).
+4. **Write Trace State** — set `dev_selftest` (pass/fail) trong `.tsv`.
+5. **Refresh Panel Mirror** — Living Docs local (umbrella).
+
+---
+
+## Checkpoint & Gate
+
+- Không gate chặn. Fail → gợi ý `/fix-bug` hoặc `/debug`.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Scoped run** — chạy hẹp (theo class) cho feedback nhanh thay vì toàn bộ suite.
+- **`dev_selftest` là trục riêng** — không đụng `qc_status`.
+- **Chẩn lỗi theo platform** — dùng `platform_type` để đọc lỗi đúng ngữ cảnh stack.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Bảng lệnh test theo stack lớn** — mỗi stack một dòng; thêm stack mới phải sửa ở đây (dù stack-profile đã có `test_command`). Có thể đọc hoàn toàn từ profile.
+- **Kết quả `dev_selftest`** không chặn pipeline — dev có thể bỏ qua fail và đi tiếp. Đáng cân nhắc có nên cảnh báo mạnh hơn trước QC.
+- **Chẩn lỗi phụ thuộc AI đọc log** — với lỗi mơ hồ có thể cần `/debug`.
+
+---
+
+## Kết nối
+
+**Trước:** [`/dev-gen-test`](12-dev-gen-test.md) · **Sau:** pass → [`/review-code`](10-review-code.md) / [`/dev-smoke-test`](14-dev-smoke-test.md); fail → [`/fix-bug`](23-fix-bug.md) / [`/debug`](24-debug.md).

package/docs/explain/14-dev-smoke-test.md

@@ -0,0 +1,67 @@
+[← /dev-run-test](13-dev-run-test.md) · [Explain Home](README.md) · [Next: /qc-analyze →](15-qc-analyze.md)
+
+# 14 · `/dev-smoke-test` — Thử tại chỗ trên service/app đang chạy
+
+> **Một câu.** Kiểm tra nhanh feature **trên service/app đang chạy thật** (health endpoint, curl, chạy app trên simulator) — smoke cuối của dev trước khi giao.
+
+---
+
+## Vấn đề giải quyết
+
+Test đơn vị pass ≠ chạy thật OK. `/dev-smoke-test` xác nhận feature hoạt động trên runtime thật (server lên, endpoint trả 200, app chạy không crash) — lớp kiểm cuối trước PR/QC.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase Dev Self-Test (cuối), sau `/dev-run-test`.
+- **Tiền đề:** service/app khởi động được (`conventions.service_run`).
+
+---
+
+## Input / Output
+
+**Input:** service/app đang chạy + `.feature` + `platform_type`.
+
+**Output:** kết quả smoke tại chỗ (báo cáo), chẩn crash nếu có.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+Rẽ nhánh theo `platform_type`:
+
+| platform_type | Việc |
+|---------------|------|
+| **backend** | Thử health endpoint; gọi GET/POST thật (curl); hoặc pytest smoke marker |
+| **web-frontend** | curl kiểm 200 (Linux/mac/Windows); nếu không → khởi động bằng `service_run`; chạy Playwright/Cypress scenario gắn UC |
+| **mobile** | Chạy app trên simulator (Flutter/React Native/Android Compose/iOS SwiftUI); đọc crash log nếu lỗi |
+
+---
+
+## Checkpoint & Gate
+
+- Không gate chặn — smoke tư vấn. Pass → tạo PR.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Chạy trên runtime thật** — khác dev-run-test (chạy test suite); đây là "bấm thử" thực tế.
+- **Rẽ nhánh 3 platform_type** với lệnh cụ thể cho từng stack + đọc crash log mobile.
+- **Bắc cầu sang QC E2E** — web dùng chính Playwright/Cypress mà QC sẽ dùng.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Chồng lấn QC E2E** — web smoke đã chạy Playwright scenario; QC cũng Playwright. Ranh giới: dev-smoke = nhanh/thủ công, QC = đầy đủ/evidence. Đáng làm rõ.
+- **Phụ thuộc service chạy được** — nếu môi trường local chưa dựng, smoke không chạy → giá trị giảm.
+- **Không ghi trace** (khác dev-run-test) — kết quả smoke không lưu trạng thái; chỉ báo cáo. Cân nhắc có nên lưu.
+- **Ba nhánh platform** với nhiều biến thể lệnh — chi phí bảo trì theo số stack.
+
+---
+
+## Kết nối
+
+**Trước:** [`/dev-run-test`](13-dev-run-test.md) · **Sau:** tạo PR, hoặc chuyển QC chính thức → [`/qc-analyze`](15-qc-analyze.md).

package/docs/explain/15-qc-analyze.md

@@ -0,0 +1,68 @@
+[← /dev-smoke-test](14-dev-smoke-test.md) · [Explain Home](README.md) · [Next: /qc-plan →](16-qc-plan.md)
+
+# 15 · `/qc-analyze` — Trạm 1: Phân rã yêu cầu + gap tài liệu
+
+> **Một câu.** Trạm đầu của dây chuyền QC: phân rã yêu cầu từ spec, map trace, và ghi **DOC_GAPS** (chỗ tài liệu thiếu để test được). Markdown-first, chưa có script.
+
+> 🏭 **Dây chuyền QC 6 trạm** dùng module `qc-playwright` và **QC skill** nạp từ `paths.qc_skills_dir` — mặc định bundled `.agent/skills/qc`, **override sang repo riêng của team QC** để nâng cấp framework không ghi đè (QC skill tiến hoá độc lập).
+
+---
+
+## Vấn đề giải quyết
+
+QC chính thức cần hiểu yêu cầu **testable** trước khi viết test. Trạm này phân rã spec thành phân tích yêu cầu + phát hiện **gap tài liệu** (thiếu gì để test được) → tránh viết test trên hiểu lầm.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase QC (trạm 1), sau code chạy được.
+- **Gate vào:** Guard — cảnh báo nếu BDD chưa approved.
+- **Đặc biệt:** **Platform Resolution** ở đây khoá platform cho **cả QC pass** — mọi trạm sau kế thừa.
+
+---
+
+## Input / Output
+
+**Input:** UC-ID + spec (PRD/BDD từ spec repo) + skill `qa-analyst`.
+
+**Output (per UC):** `{qc_dir}/{UC-ID}/{platform}/REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md`.
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Guard — BDD approved?** — cảnh báo mềm nếu chưa.
+2. **Platform Resolution** — chốt 1 platform cho toàn QC pass (sổ trace ghi `qc_status` sẽ là `{UC-ID}-{platform}.tsv`).
+3. **Role qa-analyst** — nạp skill `{qc_skills_dir}/qa-analyst/`.
+4. **Trace mapping (bắt buộc)** — map yêu cầu ↔ scenario ↔ SC.
+5. **DOC_GAPS (bắt buộc)** — ghi chỗ tài liệu thiếu/mơ hồ chặn test (blocker 🔴 xử trước ở `/qc-plan`).
+6. **Output** REQUIREMENT_ANALYSIS.md + DOC_GAPS.md.
+
+---
+
+## Checkpoint & Gate
+
+- Guard mềm (BDD approved). Không gate chặn.
+
+---
+
+## Cơ chế đặc biệt
+
+- **QC skill từ repo riêng** (`qc_skills_dir`) — QC team sở hữu, không bị framework upgrade ghi đè.
+- **Platform khoá một lần** cho cả pass → nhất quán sổ trace.
+- **DOC_GAPS** — kênh QC phản hồi ngược chất lượng tài liệu (song song `/report-bug`).
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **DOC_GAPS trùng vai với review-context B-check?** — cả hai bắt gap tài liệu, nhưng QC nhìn từ góc "test được không". Đáng xem có nối được feedback này về spec.
+- **Platform một pass** — feature multi-platform phải chạy QC pass nhiều lần. Chi phí lặp phân tích.
+- **Phụ thuộc QC skill ngoài** — nếu `qc_skills_dir` trỏ sai/thiếu, trạm hụt logic.
+
+---
+
+## Kết nối
+
+**Trước:** code + [`/validate-traces`](21-validate-traces.md) · **Sau:** xử gap blocker 🔴 → [`/qc-plan`](16-qc-plan.md).

package/docs/explain/16-qc-plan.md

@@ -0,0 +1,61 @@
+[← /qc-analyze](15-qc-analyze.md) · [Explain Home](README.md) · [Next: /qc-design-test →](17-qc-design-test.md)
+
+# 16 · `/qc-plan` — Trạm 2: Kế hoạch test theo rủi ro
+
+> **Một câu.** Từ phân tích yêu cầu, lập **TEST_PLAN** ưu tiên theo rủi ro và nêu câu hỏi cần dev làm rõ.
+
+---
+
+## Vấn đề giải quyết
+
+Không phải mọi scenario rủi ro ngang nhau. Trạm này xếp ưu tiên test theo rủi ro (tránh dàn trải) và gom câu hỏi cho dev trước khi thiết kế test.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** Phase QC (trạm 2), sau `/qc-analyze`.
+- **Tiền đề:** REQUIREMENT_ANALYSIS.md + DOC_GAPS.md; nên xử blocker 🔴 trước.
+
+---
+
+## Input / Output
+
+**Input:** analysis từ trạm 1 + skill `qa-planner`.
+
+**Output:** `{qc_dir}/{UC-ID}/{platform}/TEST_PLAN.md` (rủi ro + câu hỏi cho dev).
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Role qa-planner** — nạp `{qc_skills_dir}/qa-planner/`.
+2. Đọc analysis + gap → **đánh giá rủi ro** từng vùng.
+3. Nêu **câu hỏi cho dev** (điểm chưa rõ để test đúng).
+4. **Output** TEST_PLAN.md.
+
+---
+
+## Checkpoint & Gate
+
+- Không gate chặn.
+
+---
+
+## Cơ chế đặc biệt
+
+- **Risk-based** — kế hoạch bám rủi ro, không phủ đều.
+- **Câu hỏi cho dev** — kênh QC ↔ Dev có hồ sơ trước khi viết test.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Trạm mỏng nhất** (~thin orchestrator + skill). Giá trị phụ thuộc chất lượng skill qa-planner.
+- **Câu hỏi cho dev** không có cơ chế theo dõi trả lời — dễ rơi. Cân nhắc gắn vào DOC_GAPS/feedback.
+
+---
+
+## Kết nối
+
+**Trước:** [`/qc-analyze`](15-qc-analyze.md) · **Sau:** [`/qc-design-test`](17-qc-design-test.md).