@educa-corp/sdd-framework 0.2.4 → 0.2.5

package/docs/02-concepts/pipeline-steps/05-tech-docs.md

@@ -0,0 +1,101 @@
+[← BDD](04-bdd.md) · [Pipeline Steps](README.md) · [Next: Code →](06-code.md)
+
+# Bước 5 · Tech-Docs — Thiết kế kỹ thuật (Technical Design)
+
+> **Tóm tắt.** Từ BDD `approved`, sinh **một tech-design full-stack gộp cho cả PRD** — API contract, entity, data, dependency — rồi review đa chiều + **cổng ký liên team** cho contract cross-service.
+> **Commands:** `/generate-tech-docs` → `/review-tech-docs`
+
+| | |
+|---|---|
+| **Giai đoạn** | Design (đầu ra kỹ thuật) |
+| **Owner** | 👤 SA / Tech Lead |
+| **Đầu vào** | BDD `approved` + entity catalog + CLAUDE.md |
+| **Đầu ra** | `tech-docs/{TICKET-ID}-tech-design.md` (một doc full-stack/PRD) |
+| **HITL** | 🟠 Vừa — review đa chiều + cổng ký T7 cho contract liên team |
+
+---
+
+## Mục đích (Purpose)
+
+Đây là nơi **chuyển từ ngôn ngữ nghiệp vụ sang ngôn ngữ kỹ thuật** — ranh giới cuối cùng của Business Language Guard. Tech-design là **API contract** giữa các team: BE viết, FE/App đọc. Chốt sai contract ở đây = đốt budget code cho cả hai phía. Bước này:
+
+- Sinh **một** blueprint full-stack gộp cho cả PRD (BE API/data/DB **và** client), phủ mọi UC.
+- Chuẩn hoá **entity catalog, relationship map, enum registry** làm nguồn chân lý cho code.
+- **Reverse-document** khi API đã tồn tại (mô tả as-is thay vì thiết kế mới).
+- Với dependency cross-service → có thể sinh **System BDD**.
+
+---
+
+## Input (Đầu vào)
+
+- **BDD `approved`** của mọi platform trong PRD.
+- **Entity catalog** + relationship map + enum registry (domain-knowledge).
+- `CLAUDE.md` (§2 kiến trúc) để bám layer/convention của stack.
+- (Nếu reverse-document) mã nguồn API hiện có.
+
+## Output (Đầu ra)
+
+| Artifact | Nội dung |
+|----------|----------|
+| `specs/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` | **Một doc full-stack** phủ mọi UC: API endpoint, DTO, data model, DB, dependency, §10 UC Coverage |
+| `@trace.status: approved` | 🔒 Mở khoá `/generate-code` |
+| (Tuỳ chọn) System BDD | Cho dependency cross-service |
+
+> Contract này là **artifact liên team**: BE viết → FE/App đọc ở `/generate-code --phase=integration`. Trong umbrella, nó nằm ở **spec repo dùng chung**.
+
+---
+
+## Ai làm gì (Roles & responsibilities)
+
+| Ai | Việc |
+|----|------|
+| 👤 **SA / Lead** | Lead: quyết trade-off thiết kế, duyệt contract, **ký** cổng liên team (T7) |
+| 👤 **Dev các team** | Review contract phần mình tiêu thụ/cung cấp |
+| 🤖 **AI** | Sinh tech-design từ BDD + entity catalog; reverse-document API as-is; review đa chiều |
+
+---
+
+## Câu hỏi cần trả lời (Questions this step answers)
+
+- Mỗi UC hiện thực bằng **API/endpoint/DTO** nào?
+- **Entity/field/quan hệ/enum** chuẩn là gì (nguồn chân lý cho code)?
+- Contract giữa BE ↔ FE/App có **khớp** và **đủ** cho mọi scenario không?
+- Dependency **cross-service** nào cần System BDD + ký liên team?
+
+---
+
+## Framework xử lý thế nào (Mechanics)
+
+**`/generate-tech-docs`**
+1. Đọc mọi `.feature approved` của PRD + entity catalog.
+2. Sinh **một** tech-design gộp full-stack, mục **§10 UC Coverage** ánh xạ finding/section về từng UC.
+3. Nếu API đã tồn tại → **reverse-document** (mô tả as-is, không tự chế shape).
+4. Chuẩn hoá entity/DTO/endpoint theo catalog để nhất quán với PRD/BDD.
+
+**`/review-tech-docs`** — review **đa chiều**, findings gom theo từng UC (đọc §10 UC Coverage):
+- Kiểm tính đủ/đúng của contract, entity, error, dependency.
+- **T7 — cổng ký liên team**: contract cross-service phải được các team liên quan **ký** trước khi code.
+
+---
+
+## HITL / Gate
+
+- 🟠 SA duyệt tech-design; **read-only** review — chỉ báo findings, không tự sửa.
+- 🔒 **T7 sign-off**: contract liên team chưa ký → không mở khoá code phía tiêu thụ.
+- `@trace.status: approved` trên tech-design → `/generate-code` dùng §4 làm nguồn contract; `draft/in-review` hoặc còn blocker-GAP → chỉ WARN (không chặn).
+
+---
+
+## Anti-pattern
+
+- ❌ Tự "chế" shape DTO/endpoint khi API đã tồn tại — phải reverse-document as-is.
+- ❌ Bỏ cổng ký T7 rồi để hai team hiểu contract khác nhau → rework tốn kém.
+- ❌ Sinh code khi tech-design còn `draft` với contract chưa chốt.
+
+---
+
+## Bước tiếp theo (Next step)
+
+Tech-design `approved` (+ ký T7) → sinh code:
+
+➡️ [Bước 6 · Code — `/generate-code`](06-code.md)

package/docs/02-concepts/pipeline-steps/06-code.md

@@ -0,0 +1,119 @@
+[← Tech-Docs](05-tech-docs.md) · [Pipeline Steps](README.md) · [Next: Dev self-test →](07-dev-selftest.md)
+
+# Bước 6 · Code — Sinh mã nguồn (Code Generation)
+
+> **Tóm tắt.** Sinh code từ `.feature approved` + tech-design, gắn `@trace` ở boundary, verify build, cập nhật trace state — với checkpoint "AI đã hiểu đúng chưa" trước khi chạy.
+> **Commands:** `/generate-code` · `/review-code` · `/fix-bug`
+
+| | |
+|---|---|
+| **Giai đoạn** | Implementation |
+| **Owner** | 👤 Developer |
+| **Đầu vào** | `.feature approved` + tech-design + CLAUDE.md |
+| **Đầu ra** | Code có `@trace` + trace row trong `.tsv` |
+| **HITL** | 🟡 Mỏng — 🛑 comprehension checkpoint |
+
+---
+
+## Mục đích (Purpose)
+
+Code là **hệ quả của spec, không phải nguồn**. Bước này biến scenario thành code sao cho:
+
+- Mỗi boundary mang **`@trace`** → đọc code biết ngay phục vụ scenario nào.
+- **Drift per-UC** → không đập code refactor mù; chỉ chạm phần lệch.
+- **Build verify** sẵn (≤3 retry) → không nhận code không build được.
+- Không sinh code cho file **không** có `.feature` backing (trừ `/fix-bug`, `/debug`).
+
+---
+
+## Input (Đầu vào)
+
+- **`.feature approved`** (hoặc UC-ID) — target.
+- **Tech-design** `approved` (§4 làm nguồn contract cho shape DTO/endpoint/error).
+- `CLAUDE.md` §2 (thứ tự layer, package strategy) + §3 (coding standards) + §5 (error handling) — **service overlay thắng**.
+- `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` — để so drift.
+
+## Output (Đầu ra)
+
+| Artifact | Nội dung |
+|----------|----------|
+| File code | Theo thứ tự layer của stack, tag `@trace.implements/source` ở boundary |
+| `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` | Trace row cập nhật: `status`, `implemented_by`, `bdd_version`… |
+
+---
+
+## Ai làm gì (Roles & responsibilities)
+
+| Ai | Việc |
+|----|------|
+| 👤 **Dev** | Xác nhận comprehension checkpoint; xem report; gọi `/review-code` nếu cần |
+| 🤖 **AI** | Phát hiện drift, sinh code theo layer, tag trace, build verify, ghi `.tsv` |
+| 👤 **Lead** | `/review-code` (read-only) khi cần soát kỹ |
+
+---
+
+## Câu hỏi cần trả lời (Questions this step answers)
+
+- So với lần sinh trước: SC nào **mới**, **drifted**, hay **synced** (bỏ qua)?
+- Code phải theo **layer/package/convention** nào của stack này?
+- Contract (DTO/endpoint/error) lấy từ đâu — tech-design §4 hay System BDD?
+- Build có **pass** không?
+
+---
+
+## Framework xử lý thế nào (Mechanics)
+
+1. **Drift detection** — so `bdd_version`/spec với `.tsv`: phân loại **new (UNTRACKED)** / **DRIFT** / **OK (synced-skip)**.
+2. 🛑 **Comprehension checkpoint** (mềm): *"{X} new, {Y} drifted, {Z} synced-skip — Proceed?"* → tránh AI hiểu sai mà vẫn chạy.
+3. **Scope Lock** — chỉ implement UC target; code của UC khác trong file dùng chung là **bất khả xâm phạm** (đọc `@trace.implements` để bảo toàn, không xoá).
+4. **Generate** theo **thứ tự layer** (vd Controller → Facade → Service → Repository) từ CLAUDE.md §2; tag `@trace` chỉ ở **boundary** (controller/handler), shared code dò qua import chain.
+5. **Build verify** — chạy `{conventions.build_command}`, ≤3 retry.
+6. **Ghi trace row** vào `.tsv` (trong spec repo nếu umbrella — thao tác ghi liên-repo).
+
+**Phase cho Frontend:**
+| Phase | Ý nghĩa |
+|-------|---------|
+| `--phase=ui` | FE Phase 1 — sinh UI + layer **mock API** từ System BDD contract |
+| `--phase=integration` | FE nối vào **BE contract thật** (đọc tech-design từ spec repo) |
+| *(default)* | Backend — sinh từ tech-design §4 |
+
+**`/review-code`** — read-only, chỉ báo findings (không tự sửa: "AI tự fix tự review" = lặp lỗi).
+**`/fix-bug`** — sửa lỗi có root-cause + regression test; xem [Feedback Loop](10-feedback-loop.md).
+
+---
+
+## HITL / Gate
+
+- 🛑 **Comprehension checkpoint** — điểm dừng chính: Dev xác nhận phân loại drift đúng trước khi sinh.
+- Build phải **pass** trước khi commit.
+- `/review-code` là gate read-only tuỳ chọn — không auto-apply fix.
+
+---
+
+## Ví dụ (Example)
+
+```
+/generate-code UC-02
+  Drift: 1 new (SC-02.3), 1 drifted (SC-02.1 bdd_version 1.0→1.1), 2 synced-skip
+  🛑 Proceed? (Y/N) → Y
+  → sinh/patch code, @trace.implements ở PasswordResetController
+  → build verify ✅ (attempt 1)
+  → cập nhật .trace/auth/quen-mat-khau/UC-02-web.tsv
+```
+
+---
+
+## Anti-pattern
+
+- ❌ Sinh code cho file không có `.feature` backing (ngoài fix-bug/debug).
+- ❌ Tái tạo file dùng chung "chỉ gồm scenario UC này" → xoá nhầm nghiệp vụ UC khác.
+- ❌ Tag `@trace` mọi file → tag explosion; chỉ tag boundary.
+- ❌ Lưu version trong code — version chỉ ở spec; code dùng `.tsv`.
+
+---
+
+## Bước tiếp theo (Next step)
+
+Code build được → dev tự kiểm nhanh:
+
+➡️ [Bước 7 · Dev self-test — `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test`](07-dev-selftest.md)

package/docs/02-concepts/pipeline-steps/07-dev-selftest.md

@@ -0,0 +1,92 @@
+[← Code](06-code.md) · [Pipeline Steps](README.md) · [Next: QC Automation →](08-qc-automation.md)
+
+# Bước 7 · Dev Self-test — Tự kiểm nhanh của Dev (Developer Smoke)
+
+> **Tóm tắt.** Dev tự sinh & chạy bộ **smoke test nhanh** ngay sau khi code, đặt cột `dev_selftest`. Đây là smoke của **dev**, độc lập với QC chính thức.
+> **Commands:** `/dev-gen-test` → `/dev-run-test` → `/dev-smoke-test`
+
+| | |
+|---|---|
+| **Giai đoạn** | Dev self-check |
+| **Owner** | 👤 Developer |
+| **Đầu vào** | Code vừa sinh (bước 6) + `.feature` |
+| **Đầu ra** | Test smoke + cột `dev_selftest` trong `.tsv` |
+| **HITL** | 🟡 Mỏng |
+
+---
+
+## Mục đích (Purpose)
+
+Trước khi đẩy sang QC chính thức, Dev cần một vòng **kiểm nhanh tại chỗ** để bắt lỗi hiển nhiên — không phải bộ test đầy đủ. Bước này:
+
+- Sinh bộ **self-test** bám scenario, chạy nhanh theo platform.
+- Đặt cột **`dev_selftest`** để biết SC nào đã qua smoke của dev.
+- Cho phép **thử tại chỗ** trên service/app đang chạy (`/dev-smoke-test`).
+
+> **`dev_selftest` ≠ `qc_status`.** Hai trục **độc lập**: dev smoke (nhanh, tự kiểm) vs QC chính thức (Playwright, evidence). Không lấn quyền nhau.
+
+---
+
+## Input (Đầu vào)
+
+- Code đã sinh + build được (bước 6).
+- `.feature` target (UC-ID / platform).
+- `active_module` + `platform_type` (chẩn lỗi theo stack).
+
+## Output (Đầu ra)
+
+| Artifact | Nội dung |
+|----------|----------|
+| File test smoke | Bộ tự-kiểm nhanh do `/dev-gen-test` sinh |
+| Cột `dev_selftest` trong `.trace/…/{UC-ID}-{platform}.tsv` | Kết quả smoke của dev |
+
+---
+
+## Ai làm gì (Roles & responsibilities)
+
+| Ai | Việc |
+|----|------|
+| 👤 **Dev** | Chạy self-test, đọc chẩn lỗi, sửa code nếu fail |
+| 🤖 **AI** | Sinh test smoke, chạy + chẩn lỗi theo platform, set `dev_selftest`, thử tại chỗ |
+
+---
+
+## Câu hỏi cần trả lời (Questions this step answers)
+
+- Code vừa sinh có **chạy được / pass smoke** không?
+- Lỗi (nếu có) nằm ở đâu, do platform gì?
+- SC nào đã qua vòng tự kiểm của dev (`dev_selftest`)?
+
+---
+
+## Framework xử lý thế nào (Mechanics)
+
+| Lệnh | Việc |
+|------|------|
+| `/dev-gen-test` | Sinh bộ self-test nhanh bám scenario |
+| `/dev-run-test` | Chạy + **chẩn lỗi theo platform**, set cột `dev_selftest` |
+| `/dev-smoke-test` | Thử **tại chỗ** trên service/app đang chạy |
+
+- Route theo `active_platform` (flat hoặc map-theo-platform) để chạy đúng service.
+- Trace ghi vào `.tsv` (spec repo nếu umbrella).
+
+---
+
+## HITL / Gate
+
+- 🟡 Mỏng — Dev chủ động chạy; không có gate chặn downstream. Đây là bước *tự tin trước khi giao QC*.
+
+---
+
+## Anti-pattern
+
+- ❌ Coi `dev_selftest` là thay QC chính thức — nó chỉ smoke, không có evidence.
+- ❌ Bỏ qua vì "build đã pass" — build pass ≠ hành vi đúng.
+
+---
+
+## Bước tiếp theo (Next step)
+
+Smoke ổn → chuyển sang dây chuyền QC chính thức:
+
+➡️ [Bước 8 · QC Automation — `/qc-analyze` … `/qc-report`](08-qc-automation.md)

package/docs/02-concepts/pipeline-steps/08-qc-automation.md

@@ -0,0 +1,102 @@
+[← Dev self-test](07-dev-selftest.md) · [Pipeline Steps](README.md) · [Next: Validate Traces →](09-validate-traces.md)
+
+# Bước 8 · QC Automation — Dây chuyền kiểm thử 6 trạm (QC Pipeline)
+
+> **Tóm tắt.** Dây chuyền QC tự động 6 trạm: phân rã yêu cầu → lập kế hoạch → thiết kế test case → review → chạy Playwright → report. Ghi `qc_status` **chính thức** + evidence.
+> **Commands:** `/qc-analyze` → `/qc-plan` → `/qc-design-test` → `/qc-review` → `/qc-run-test` → `/qc-report`
+
+| | |
+|---|---|
+| **Giai đoạn** | QC Automation |
+| **Owner** | 👤 QA / Tester |
+| **Đầu vào** | UC-ID + spec (PRD/BDD) + code đã chạy |
+| **Đầu ra** | Test case, script Playwright, `qc_status`, evidence, product-gap |
+| **HITL** | 🟠 Vừa — cổng review case & script trước khi chạy |
+
+---
+
+## Mục đích (Purpose)
+
+Đây là **kiểm thử chính thức** (khác với dev smoke). Dùng module **`qc-playwright`** (Python + pytest-playwright + Page Object) — độc lập với module implementation của dev. Bước này:
+
+- Phân rã yêu cầu thành test case bám scenario, phát hiện **gap tài liệu**.
+- Chạy test thật, ghi **`qc_status` chính thức** + **evidence**.
+- Phân loại FAIL: **script-bug** (sửa script) vs **product-gap** (giữ FAIL + evidence, **không bao giờ fake-pass**).
+- Đẩy **product-gap** ngược về PO/Dev.
+
+---
+
+## Input (Đầu vào)
+
+- **UC-ID** + platform (QC pass khoá 1 platform).
+- Spec: PRD / `.feature` (từ spec repo, qua `spec_source`).
+- Code đã sinh & chạy được.
+- `qc_dir` (working docs của QC) + module `qc-playwright`.
+
+## Output (Đầu ra)
+
+| Artifact | Nội dung |
+|----------|----------|
+| `docs/{UC-ID}/…` | `REQUIREMENT_ANALYSIS.md`, `DOC_GAPS.md`, `TEST_PLAN.md`, `test-cases/*.Test.md` |
+| Script Python pytest-playwright | Sinh từ `.Test.md` đã review |
+| Cột `qc_status` trong `.trace/…/{UC-ID}-{platform}.tsv` | Trạng thái QC **chính thức** |
+| Evidence + report | `/qc-report` — kèm product-gap đẩy về PO/Dev |
+
+---
+
+## Ai làm gì (Roles & responsibilities)
+
+| Ai | Việc |
+|----|------|
+| 👤 **QA/Tester** | Lead: duyệt cổng review case & script; đọc report; phân loại gap |
+| 🤖 **AI** | Phân rã yêu cầu, sinh test case + script Playwright, chạy, phân loại FAIL, ghi `qc_status` |
+| 👤 **PO/Dev** | Nhận **product-gap** để xử lý (không phải lỗi script) |
+
+---
+
+## Câu hỏi cần trả lời (Questions this step answers)
+
+- Yêu cầu phân rã thành những **test case** nào? Tài liệu có **gap** gì?
+- Rủi ro nào cao? Cần hỏi dev điều gì trước khi test?
+- Test case & script đã đủ tốt để **chạy** chưa (cổng review)?
+- SC nào **PASS/FAIL** chính thức (`qc_status`)? FAIL là **script-bug** hay **product-gap**?
+
+---
+
+## Framework xử lý thế nào (Mechanics)
+
+Dây chuyền **6 trạm**, output trạm trước là input trạm sau:
+
+| # | Trạm | Việc |
+|---|------|------|
+| 1 | `/qc-analyze` | Phân rã yêu cầu + phát hiện **gap tài liệu** (`DOC_GAPS.md`) |
+| 2 | `/qc-plan` | Đánh giá **rủi ro** + câu hỏi cho dev (`TEST_PLAN.md`) |
+| 3 | `/qc-design-test` | Thiết kế **test case** dạng Markdown (`*.Test.md`) |
+| 4 | `/qc-review` | 🛑 **Cổng review** hai chiều: test case & script trước khi chạy |
+| 5 | `/qc-run-test` | Sinh & chạy **pytest-playwright**, ghi **`qc_status`** chính thức |
+| 6 | `/qc-report` | Report + **evidence**, đẩy **product-gap** về PO/Dev |
+
+- Stack QC bắt buộc theo `modules/qc-playwright/stack-profile.yaml`: Python + pytest-playwright + Page Object; mỗi test độc lập; gom theo (role, account) để auth không xen kẽ.
+
+---
+
+## HITL / Gate
+
+- 🛑 `/qc-review` — **cổng review** case & script: không chạy test kém.
+- **Không fake-pass**: FAIL là product-gap → giữ nguyên FAIL + evidence, đẩy về PO/Dev.
+
+---
+
+## Anti-pattern
+
+- ❌ Lẫn `qc_status` với `dev_selftest` — hai trục độc lập.
+- ❌ Sửa script cho "xanh" khi thực chất là product-gap → giấu lỗi sản phẩm.
+- ❌ Chạy `/qc-run-test` khi chưa qua cổng `/qc-review`.
+
+---
+
+## Bước tiếp theo (Next step)
+
+Có `qc_status` → soát độ phủ toàn cục:
+
+➡️ [Bước 9 · Validate Traces — `/validate-traces`](09-validate-traces.md)

package/docs/02-concepts/pipeline-steps/09-validate-traces.md

@@ -0,0 +1,104 @@
+[← QC Automation](08-qc-automation.md) · [Pipeline Steps](README.md) · [Next: Feedback Loop →](10-feedback-loop.md)
+
+# Bước 9 · Validate Traces — Ma trận độ phủ (Coverage Matrix)
+
+> **Tóm tắt.** Check **read-only** độ phủ giữa **spec ↔ code ↔ test**, gồm cả PRD version drift. Chỉ ra chỗ chưa phủ — không sửa gì.
+> **Command:** `/validate-traces`
+
+| | |
+|---|---|
+| **Giai đoạn** | Quality (xuyên suốt) |
+| **Owner** | 👤 Dev / QA / Lead |
+| **Đầu vào** | `.trace/*.tsv` + spec + code + test |
+| **Đầu ra** | Ma trận coverage + phân loại từng SC |
+| **HITL** | ⚪ Read-only |
+
+---
+
+## Mục đích (Purpose)
+
+Traceability chỉ có giá trị khi **kiểm được**. Bước này cho một **bức tranh toàn cục**: scenario nào đã có code, có test, hay còn hở — để không "tưởng xong mà chưa xong". Vì là **read-only**, chạy lúc nào cũng an toàn.
+
+- Đối chiếu spec ↔ code ↔ test cho từng SC.
+- Phát hiện **PRD version drift** (spec đổi mà code chưa regen).
+- Chỉ ra **gap** chưa phủ để lên kế hoạch bù.
+
+---
+
+## Input (Đầu vào)
+
+- `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` (mọi UC × platform).
+- Spec (`.feature`), code (`@trace.implements`), test (`@trace.verifies`).
+
+## Output (Đầu ra)
+
+| Artifact | Nội dung |
+|----------|----------|
+| Ma trận coverage spec ↔ code ↔ test | Trạng thái từng SC + `code_coverage` tổng |
+| (Tuỳ chọn) `trace-report.md` | Báo cáo tổng hợp |
+
+---
+
+## Ai làm gì (Roles & responsibilities)
+
+| Ai | Việc |
+|----|------|
+| 👤 **Dev/QA/Lead** | Đọc ma trận, quyết bù gap / regen drift |
+| 🤖 **AI** | Quét trace, phân loại SC, dựng ma trận (không sửa file) |
+
+---
+
+## Câu hỏi cần trả lời (Questions this step answers)
+
+- Scenario nào **chưa có code** (UNTRACKED)? Chưa có test (GAP)?
+- Code nào **lỗi thời** so với spec (DRIFT)?
+- Độ phủ tổng thể (`code_coverage`) bao nhiêu?
+
+---
+
+## Framework xử lý thế nào (Mechanics)
+
+Phân loại mỗi SC theo **thứ tự ưu tiên** (rule sớm thắng):
+
+| # | Trạng thái | Điều kiện |
+|---|-----------|-----------|
+| 1 | **UNTRACKED** | `gen_ver == —` — scenario chưa từng sinh code |
+| 2 | **DRIFT** | có `implemented_by` **và** `spec_ver != gen_ver` — spec đổi sau codegen → **regen trước khi test** |
+| 3 | **GAP** | có `implemented_by` **và** (`test_count == — / 0`) — có code, chưa test |
+| 4 | **OK** | `spec_ver == gen_ver`, có `implemented_by`, `test_count > 0` |
+
+> **Vì sao DRIFT xét trước GAP:** một SC đã có code, chưa test, **và** spec vừa drift phải hiện `DRIFT` (không phải `GAP`) — vì `/generate-code` xử `GAP` = "skip codegen" còn `DRIFT` = "regenerate". Nếu GAP thắng, code lỗi thời bị bỏ qua và test sinh trên code cũ.
+
+---
+
+## HITL / Gate
+
+- ⚪ **Read-only** — bỏ qua checkpoint ghi-file. Đây là công cụ *quan sát*, không phải *hành động*.
+
+---
+
+## Ví dụ (Example)
+
+```
+/validate-traces auth
+  UC-01  SC-01.1  OK
+  UC-01  SC-01.2  GAP        (có code, chưa test)
+  UC-02  SC-02.1  DRIFT      (spec_ver 1.1 ≠ gen_ver 1.0 → regen)
+  UC-02  SC-02.3  UNTRACKED  (chưa sinh code)
+  code_coverage = 7/9 (78%)
+```
+
+---
+
+## Anti-pattern
+
+- ❌ Coi validate-traces là "chạy xong là fix xong" — nó chỉ báo cáo; hành động ở `/generate-code` (regen DRIFT) và QC (bù GAP).
+- ❌ Bỏ qua DRIFT rồi test trên code cũ.
+
+---
+
+## Bước tiếp theo (Next step)
+
+Gap/drift phát hiện → quay lại `/generate-code` (regen) hoặc bù test; lỗi/thiếu từ QC → vòng phản hồi:
+
+➡️ [Bước 10 · Feedback Loop — `/report-bug` · `/propose-scenario` · `/learn` · `/sync`](10-feedback-loop.md)

package/docs/02-concepts/pipeline-steps/10-feedback-loop.md

@@ -0,0 +1,105 @@
+[← Validate Traces](09-validate-traces.md) · [Pipeline Steps](README.md) · [Overview →](../overview.md)
+
+# Bước 10 · Feedback Loop — Vòng phản hồi & tự học (Feedback & Learning)
+
+> **Tóm tắt.** Bug, đề xuất scenario và bài học được đưa vào các **kênh có hồ sơ**, nổi lên qua `/sync`, và nạp lại vào context — **không tạo loop ngầm** mà cải tiến spec & tri thức dự án.
+> **Commands:** `/report-bug` · `/propose-scenario` · `/learn` · `/sync` · `/fix-bug`
+
+| | |
+|---|---|
+| **Giai đoạn** | Cross-cutting (xuyên suốt) |
+| **Owner** | 👤 Tester / QA (và tất cả) |
+| **Đầu vào** | Bug, gap, định hướng lặp lại |
+| **Đầu ra** | `feedback/*`, `project-lessons.md`, Living Docs |
+| **HITL** | ⚪ Kênh có hồ sơ |
+
+---
+
+## Mục đích (Purpose)
+
+Framework là pipeline **một chiều** — nhưng vẫn cần đường **phản hồi ngược có kiểm soát** để hệ thống *học* qua thời gian. Nguyên tắc: định hướng/guardrail lặp lại **phải được ghi**, đừng để nằm trong đầu vài senior. Bước này:
+
+- Cho tester/QC một **kênh feedback có hồ sơ spec** (bug, scenario proposal).
+- Biến bài học thành **lesson dán tường** (`project-lessons.md`) — nạp lại để không sai lại.
+- **Nổi** feedback lên PO/Dev qua `/sync`.
+
+> Đây **không phải loop** để chạy vòng vòng — mỗi phản hồi đi vào spec hoặc tri thức rồi pipeline lại chảy một chiều.
+
+---
+
+## Các kênh (Channels)
+
+| Lệnh | Ai dùng | Kết quả | Đi về đâu |
+|------|---------|---------|-----------|
+| `/report-bug` | Tester / QC | Bug **spec-anchored** (gồm product-gap từ `/qc-*`) | `feedback/bug-reports/` |
+| `/propose-scenario` | Tester / QC | Đề xuất BDD scenario mới | `feedback/bdd-proposals/` |
+| `/learn` | Tất cả | Guardrail lesson | `project-lessons.md` (qua step `capture-lesson`) |
+| `/fix-bug` | Dev | Sửa lỗi có root-cause + regression test | Code + `@trace.fixes/root_cause/regression` |
+| `/sync` | Lead (umbrella) | Pull + submodule + **nổi feedback** + làm mới Living Docs | Chạy hằng ngày |
+
+---
+
+## Ai làm gì (Roles & responsibilities)
+
+| Ai | Việc |
+|----|------|
+| 👤 **Tester/QC** | `/report-bug`, `/propose-scenario` — feedback có hồ sơ |
+| 👤 **Tất cả** | `/learn` khi thấy định hướng lặp lại |
+| 👤 **Dev** | `/fix-bug` — truy gốc → sửa → regression test |
+| 👤 **Lead** | `/sync` — đồng bộ umbrella, nổi feedback |
+| 🤖 **AI** | Ghi feedback đúng schema, incorporate proposal `accepted` vào `/generate-bdd`, nạp lại lessons |
+
+---
+
+## Câu hỏi cần trả lời (Questions this step answers)
+
+- Bug này gắn với **scenario/spec** nào (spec-anchored)?
+- Scenario còn thiếu nào cần đề xuất bổ sung?
+- Định hướng nào **lặp lại** đủ để thành lesson dán tường?
+- (Umbrella) feedback nào cần **nổi lên** cho PO/Dev?
+
+---
+
+## Framework xử lý thế nào (Mechanics)
+
+1. **`/report-bug` / `/propose-scenario`** — ghi feedback kèm tham chiếu spec vào `feedback/` (spec repo nếu umbrella).
+2. **`/learn`** — qua step `capture-lesson`, ghi guardrail vào `project-lessons.md`; các workflow sau **nạp lại** vào context → hệ thống *nhớ*.
+3. **`/generate-bdd`** — có thể incorporate scenario proposal đã `accepted`.
+4. **`/fix-bug`** — đọc bug spec-anchored → tạo branch `fix/{TICKET}-<slug>` → root cause → sửa (tag `@trace.fixes/root_cause/regression`) → regression test + build verify → commit sau khi user duyệt.
+5. **`/sync`** — pull, init submodule, **nổi feedback** lên PO/Dev, bootstrap config service, làm mới Living Docs. An toàn chạy lặp lại.
+
+---
+
+## HITL / Gate
+
+- ⚪ Không gate chặn — nhưng là nơi **con người quyết** điều gì đáng thành spec/lesson.
+- `/fix-bug` commit **sau khi user duyệt**.
+
+---
+
+## Ví dụ (Example)
+
+```
+QC phát hiện: link reset vẫn dùng được sau khi đổi mật khẩu
+  /report-bug  → feedback/bug-reports/BUG-217.md  (@trace tới UC-02/SC-02.1)
+  /sync        → nổi lên cho Dev
+  /fix-bug BUG-217 → branch fix/BUG-217-invalidate-link
+                     → root cause: thiếu invalidate token
+                     → fix + regression test + build ✅
+  /learn "luôn invalidate one-time token sau khi dùng"
+                     → project-lessons.md (nạp lại lần sau)
+```
+
+---
+
+## Anti-pattern
+
+- ❌ Sửa định hướng bằng miệng rồi để AI "quên" — phải `/learn`.
+- ❌ Bug không gắn spec → khó truy vết, khó regression.
+- ❌ Coi feedback loop là "chạy vòng lặp" — nó cải tiến spec/tri thức, pipeline vẫn một chiều.
+
+---
+
+## Hết pipeline (End of pipeline)
+
+Bạn đã đi hết 11 bước (0→10). Xem lại bức tranh lớn ở [Overview](../overview.md), hoặc quay về [danh sách các bước](README.md).