@edupia-tutor/spec-driven-docs 0.14.0

package/docs/03-concepts/traceability.md

@@ -0,0 +1,149 @@
+[📚 Docs](../README.md) › [Concepts](README.md) › Traceability
+
+# Traceability & Living Docs
+
+Mỗi artifact link tới mọi artifact khác qua `@trace.*` tags, và trạng thái coverage/drift được tổng hợp vào **trace TSV** rồi surface trong **Living Docs**. Đây là cách framework đảm bảo *mọi dòng code trace về một scenario*, và phân biệt hai tín hiệu test độc lập: **`dev_selftest`** (dev tự kiểm) vs **`qc_status`** (QC chính thức).
+
+## Mục lục
+
+- [Artifact chain & @trace tags](#artifact-chain--trace-tags)
+- [Trace TSV — coverage & drift](#trace-tsv--coverage--drift)
+- [Hai tín hiệu test: dev_selftest vs qc_status](#hai-tín-hiệu-test-dev_selftest-vs-qc_status)
+- [Living Docs — canonical trong spec-module + panel mirror](#living-docs--canonical-trong-spec-module--panel-mirror)
+- [/validate-traces](#validate-traces)
+
+> Schema TSV đầy đủ (mọi cột) và full danh sách trace tag: xem [../05-reference/trace-schema.md](../05-reference/trace-schema.md). Trang này tập trung vào **khái niệm** và cách hai tín hiệu hoạt động.
+
+---
+
+## Artifact chain & @trace tags
+
+Mỗi artifact mang `@trace.*` metadata liên kết về artifact trước nó:
+
+```
+product-definition.md
+  └─► PRD.md (@trace.domain, @trace.status; Service/Module trong metadata)
+        └─► specs/{domain}/{prd-slug}/bdd/{web|app|system}/{UC-ID}.feature (@trace.prd_version, @trace.module)
+              └─► specs/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design*.md (@trace.bdd_version)
+                    └─► src/ code — service submodule (@trace.implements)
+                          └─► src/test/ (@trace.verifies, @trace.service)
+   ════► {spec_source}/.trace/{domain}/{prd-slug}/{UC-ID}.tsv — TSV authoritative ở SPEC repo (coverage/drift)
+```
+
+**Các trace field quan trọng:**
+
+| Field | Vị trí | Ý nghĩa |
+|-------|--------|---------|
+| `@trace.domain` | PRD frontmatter | Domain của feature (auth, payment, …) — route vào đúng service submodule |
+| `@trace.status` | PRD frontmatter | `draft` / `approved` — dev team chỉ code khi `approved` |
+| `@trace.service` / `@trace.module` | BDD / Tech Doc header | Service + module sẽ implement |
+| `@trace.prd_version` / `@trace.bdd_version` | BDD / code / test | Version của spec mà artifact được sinh từ — base cho drift detection |
+| `@trace.implements` | Code comment | Scenario mà code này implement: `={UC-ID}-SC{N}` |
+| `@trace.verifies` | Test / QC test | Scenario mà test này verify: `={UC-ID}` hoặc `={UC-ID}-SC{N}` |
+| `@trace.api_source: existing` | BDD header | Brownfield — API đã tồn tại, contract lấy từ PRD |
+
+Ví dụ tags trong `.feature`, code, và test:
+
+```gherkin
+# @trace.id: FEAT-001-UC1
+# @trace.service: web-admin
+# @trace.module: react
+# @trace.prd_version: 1.2
+# @trace.bdd_version: 3
+```
+```java
+// @trace.implements=FEAT-001-UC1-SC2   // @trace.verifies=FEAT-001-UC1
+// @trace.prd_version=1.2               // @trace.service=api-backend
+// @trace.bdd_version=3                 // @trace.test_type=integration
+// @trace.tech_doc_revision=2
+```
+
+---
+
+## Trace TSV — coverage & drift
+
+`.trace/{domain}/{prd-slug}/{UC-ID}.tsv` là nguồn sự thật per-scenario về trạng thái implement/test. Được **ghi** bởi `/generate-bdd`, `/generate-code`, `/dev-gen-test`, `/qc-run-test`, và **update** bởi `/validate-traces`. Khi `spec_source` set, file `.trace/**/*.tsv` authoritative **được commit ở một chỗ** trong spec repo (`{spec_source}/.trace/`) — một nơi cho PM quản lý; mỗi scenario mang `@trace.service`. (Không có `spec_source` → `.trace` per-service.)
+
+Status coverage per scenario:
+
+| Status | Meaning |
+|--------|---------|
+| ✅ OK | Code version khớp spec version |
+| ⚠️ DRIFT | Code gen từ PRD/BDD cũ hơn — re-generate |
+| 🔴 GAP | Scenario có trong spec nhưng không tìm thấy code implement |
+| — UNTRACKED | Scenario ghi nhận nhưng chưa code-gen |
+
+---
+
+## Hai tín hiệu test: dev_selftest vs qc_status
+
+Trace TSV mang **hai cột độc lập**, cả hai **orthogonal** với cột `status` (coverage) ở trên:
+
+| Cột | Set bởi | Giá trị | Ý nghĩa |
+|-----|---------|---------|---------|
+| `dev_selftest` (+ `dev_selftest_at`) | `/dev-run-test` | `pass` / `fail` / `not_run` | **Dev self-check** — dev tự chạy bộ self-check test của mình trên scenario đó. **KHÔNG** phải coverage QC chính thức. |
+| `qc_status` (+ `qc_run_at`) | `/qc-run-test` | `pass` / `fail` / `skip` / `not_run` | **QC chính thức** — kết quả native QC pipeline (do QC chạy, không phải dev), keyed theo `@trace.verifies={UC-ID}-SC{N}`. |
+
+- **`dev_selftest`** là tín hiệu để QC **thấy** rằng developer đã smoke/self-check qua scenario đó. `dev_selftest: pass` chỉ nghĩa "dev đã tự kiểm" — không phải tuyên bố coverage.
+- **`qc_status`** là coverage QC chính thức từ pipeline `/qc-analyze → … → /qc-run-test → /qc-report` (xem [pipeline.md](pipeline.md#qc-automation-pipeline-phase-5b)). `/qc-run-test` dùng stack module `qc-playwright`, độc lập với dev implementation module.
+- Hai tín hiệu **sit side by side** trong Living Docs để dễ phân biệt hai luồng. Tester vẫn nên verify độc lập theo BDD + PRD ở phần chưa được automation cover.
+
+> Phân biệt rõ: `/dev-*` (dev self-check, `dev_selftest`) ≠ `/qc-*` (official QC suite, `qc_status`). Đừng coi output của `/dev-*` là coverage chính thức.
+
+---
+
+## Living Docs — canonical trong spec-module + panel mirror
+
+Living Docs (VS Code panel) đọc trace TSV và hiển thị traceability health toàn dự án:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ PRDs  Use Cases  Scenarios  Code Cov.  Test Cov.  Drift  Gap     │
+│  19     86        1077        93%        89%       212    93      │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+- Drill down: PRD → UC → per-scenario table (Spec ver, Gen ver, Code, Tests, **Dev Self-Check**, **QC Status**, **Waiting on**, Status)
+- **Waiting on** (cột `qc_owner` + `qc_blocked_by`): cho PO/PM thấy case chưa pass đang **chờ dev** (product-gap → `BUG-{id}`) hay **chờ PO** confirm/clarify (spec gap → `GAP-{id}`). Aggregates `waiting_dev` / `waiting_po` ở header dashboard.
+- Status badges: ✅ OK · ⚠️ DRIFT · 🔴 GAP · — UNTRACKED · filter theo domain/PRD status/doc status · search theo UC/SC ID.
+
+**Ba nơi chứa trace data — phân biệt authoritative vs mirror:**
+
+| Vị trí | Vai trò | Commit? |
+|--------|---------|---------|
+| `{spec_source}/.trace/*.tsv` | **Authoritative** — nguồn sự thật, một chỗ cho cả team/PM (mỗi row mang `@trace.service`) | ✅ Committed trong spec repo |
+| `{spec_source}/.living-docs/trace-report.json` | **Report** — dashboard tổng hợp, regenerate bởi `/sync` hoặc `/validate-traces` | ❌ Gitignored |
+| `./.trace` của workspace hiện tại | **Panel mirror** — giữ Living Docs panel không trống khi mở Claude Code/VS Code ở một repo không phải spec repo | ❌ Gitignored |
+
+**Vì sao authoritative + report nằm ở spec module?** Spec module được mount vào mọi umbrella/service workspace, nên là nơi chung luôn resolve được cho cross-team dashboard, và là **một chỗ duy nhất** để PM/PO quản lý trạng thái. Code-side commands (`/generate-code`, `/dev-run-test`, `/qc-run-test`) chạy trong service nhưng ghi trace cross-repo vào đây (giống `feedback/`). Panel mirror `./.trace` chỉ để panel không trống khi mở một repo lẻ.
+
+Thêm vào `.gitignore` (report + mirror là read-only generated, không commit; `.trace/*.tsv` thì commit trong spec repo):
+```
+# spec module
+.living-docs/
+# workspace không phải spec repo (panel mirror)
+.trace/
+```
+
+> **Prerequisite cho data chính xác:** umbrella cần `setup.spec_source` trỏ đúng spec submodule → framework ghi mọi trace TSV vào `{spec_source}/.trace`. (Chế độ không có `spec_source` mới cần `paths.trace_dir` per-service.)
+
+---
+
+## /validate-traces
+
+Chạy `/validate-traces {domain}` bất cứ lúc nào (đặc biệt **sau mỗi codegen session trong umbrella mode**) để:
+
+```
+/validate-traces {domain}
+→ Reads .trace/*.tsv authoritative (committed) từ MỘT chỗ: {spec_source}/.trace/
+  (mỗi scenario mang @trace.service — không cần quét/merge từng service)
+→ Writes trace-report.json → {spec_source}/.living-docs/ (generated, gitignored)
+→ Writes panel mirror → ./.trace của workspace hiện tại (non-empty khi mở repo lẻ)
+→ Living Docs panel cập nhật ngay
+```
+
+Báo cáo: scenario nào chưa có code (GAP) · code nào gen từ PRD/BDD cũ (DRIFT) · broken links / orphan BDD (không có PRD) / dead code traces · coverage % per domain.
+
+**Khi nào chạy:** sau refactor đổi tên file/function · sau khi PO cập nhật PRD (version mới) · trước PR lớn · khi CI báo trace validation fail · sau mỗi codegen session (umbrella).
+
+> **Nguyên tắc:** không merge code khi traces broken — fix traces trước. `/sync` cũng regenerate Living Docs như một bước phụ; `/validate-traces` là lệnh chuyên trách kiểm tra trace chain.

package/docs/04-operations/README.md

@@ -0,0 +1,33 @@
+[📚 Docs](../README.md) › Operations
+
+# 04 · Operations
+
+> Vận hành hằng ngày với framework: đồng bộ nội dung & nâng cấp framework, quy trình xử lý bug, và publish package lên npm.
+
+Mục này dành cho cả team (PO · Dev · QC/Tester) và người maintain framework.
+
+---
+
+## Trong mục này
+
+| Trang | Nội dung |
+|-------|----------|
+| [Sync & Update](sync-and-update.md) | `/sync` vs `/update-framework`, umbrella mode, đồng bộ Living Docs, workflow hằng ngày theo role |
+| [Bug Flow](bug-flow.md) | Phân loại bug theo spec layer (Code/BDD/PRD/Design/Env), 6 case, format thông báo, checklist đóng bug |
+| [Publishing](publishing.md) | Build + publish `@edupia-tutor/spec-driven-docs` lên npm, versioning, transfer ownership |
+
+---
+
+## Hai loại "update" — đừng nhầm
+
+| | `/sync` | `/update-framework` |
+|---|---|---|
+| Update cái gì | Nội dung dự án: code/specs trong submodule + Living Docs | Bản thân framework: commands, steps, modules |
+| Nguồn | Git remote của submodule | npm registry |
+| Tần suất | Mỗi sáng / trước khi work | Khi có version framework mới (hiếm) |
+
+Chi tiết: [Sync & Update](sync-and-update.md).
+
+---
+
+*Xem thêm:* [02 · Guides](../02-guides/) (theo vai trò) · [03 · Concepts](../03-concepts/) (kiến trúc) · [05 · Reference](../05-reference/) (tra cứu lệnh).

package/docs/04-operations/bug-flow.md

@@ -0,0 +1,362 @@
+[📚 Docs](../README.md) › [Operations](README.md) › Bug Flow
+
+# Bug Flow — PO · Dev · QC/Tester
+
+> Cách **PO, Dev, và QC/Tester phối hợp** khi phát hiện bug. Mọi bug đều được trace về spec layer để fix đúng chỗ và tránh lặp lại.
+
+> **QC cũng là nguồn bug.** Pipeline `/qc-*` đẩy vào **cùng** flow này: `/qc-run-test` FAIL = `product-gap` → `/report-bug {UC-ID}`; `/qc-analyze` `DOC_GAPS` blocker (spec sai/mơ hồ) → `/report-bug` (Case 2/3) hoặc thiếu coverage → `/propose-scenario`. Cùng phân loại Case 1–6 bên dưới. Chi tiết: [chương QC Automation](../02-guides/tester/qc-automation.md#khi-qc-tìm-thấy-bug--spec-gap--đẩy-lên-specs).
+
+---
+
+## Mục lục
+
+1. [Bug thuộc layer nào?](#1-bug-thuộc-layer-nào)
+2. [Bảng quyết định nhanh](#2-bảng-quyết-định-nhanh)
+3. [Case 1 — Code Bug (Code ≠ BDD)](#3-case-1--code-bug-code--bdd)
+4. [Case 2 — BDD Bug (BDD ≠ PRD)](#4-case-2--bdd-bug-bdd--prd)
+5. [Case 3 — PRD Ambiguity (PRD không rõ)](#5-case-3--prd-ambiguity-prd-không-rõ)
+6. [Case 4 — PRD Change (yêu cầu thay đổi)](#6-case-4--prd-change-yêu-cầu-thay-đổi)
+7. [Case 5 — Design Spec Bug (UI ≠ Design Spec)](#7-case-5--design-spec-bug-ui--design-spec)
+8. [Case 6 — Environment / Data Bug](#8-case-6--environment--data-bug)
+9. [Giao tiếp hiệu quả — các format thông báo](#9-giao-tiếp-hiệu-quả--các-format-thông-báo)
+10. [Checklist đóng bug](#10-checklist-đóng-bug)
+
+---
+
+## 1. Bug thuộc layer nào?
+
+Tester đọc spec chain **PRD → BDD → Code** để xác định layer của bug:
+
+```
+              ┌─────────────────────────────┐
+              │     Bug được phát hiện      │
+              └──────────────┬──────────────┘
+              ┌──────────────▼──────────────┐
+              │ Tester đọc PRD → BDD → Code │
+              └──────────────┬──────────────┘
+        ┌────────────────────┼────────────────────┐
+┌───────▼───────┐  ┌─────────▼─────────┐  ┌────────▼────────┐
+│ PRD mơ hồ /   │  │ BDD sai so PRD /  │  │ Code sai so BDD │
+│ yêu cầu đổi   │  │ thiếu scenario    │  │ (phổ biến nhất) │
+└───────┬───────┘  └─────────┬─────────┘  └────────┬────────┘
+   → PO xử lý          → Dev xử lý           → Dev xử lý
+   (Case 3, 4)          (Case 2)              (Case 1)
+```
+
+---
+
+## 2. Bảng quyết định nhanh
+
+| PRD | BDD | Code | Chẩn đoán | Ai fix | Re-test |
+|---|---|---|---|---|---|
+| ✅ rõ ràng | ✅ đúng | ❌ sai | **Code bug** | Dev | Tester |
+| ✅ rõ ràng | ❌ sai | ❌ sai | **BDD bug** | Dev | Tester |
+| ❌ mơ hồ | bất kỳ | bất kỳ | **PRD ambiguity** | PO → Dev | Tester |
+| ✅ rõ ràng | ✅ đúng | ✅ đúng | **Env / data bug** | DevOps / Dev | Tester |
+| Yêu cầu thay đổi | cũ | cũ | **PRD change** | PO → Dev | Tester |
+| ✅ rõ ràng | ✅ đúng | ❌ UI sai | **Design Spec bug** | PO/Designer → Dev | Tester |
+
+---
+
+## 3. Case 1 — Code Bug (Code ≠ BDD)
+
+> Phổ biến nhất. Spec đúng, code implement sai.
+
+```
+Tester                    Dev
+──────                    ────────────────────────────────────────────
+Gửi bug report
+(kèm spec context:
+ PRD path, BDD path,
+ AC bị vi phạm,
+ BDD scenario fail)
+                          Nhận bug report; đọc BDD scenario được chỉ định
+                          /fix-bug "{BUG-ID}: {mô tả}"
+                              → agent tìm divergence code vs BDD → propose fix
+                          Review + apply fix
+                          /dev-run-test → dev self-check pass ✅
+                          (dev_selftest — smoke check, KHÔNG phải official QC;
+                           QC pipeline /qc-run-test set qc_status ở flow riêng)
+                          /validate-traces → no broken
+                          Tạo PR + notify tester:
+                          "Fixed — root cause: {X}; Re-test: {BDD scenario}"
+Nhận thông báo; re-test scenario
+→ PASS: đóng bug
+→ FAIL: gửi lại với actual behavior mới
+```
+
+**Ví dụ:**
+
+```
+Bug: FT-001 — tài khoản khoá sau 6 lần sai, không phải 5
+PRD AC3 : "5 lần sai → khoá"           ✅
+BDD SC3 : "When 5 failures, Then 423"   ✅
+Code    : if failCount > 5: lock()      ❌  ← > thay vì >=
+Fix: đổi > thành >= → chạy BDD test → pass
+→ notify: "Case 1 fixed, re-test FT-001-UC2-SC3"
+```
+
+> **Nếu root cause là lỗi AI hay lặp khi gen code** (vd dùng `>` thay vì `>=` cho boundary, hay gọi repository thẳng từ controller): `/fix-bug` sẽ hỏi *"Record as a project lesson? (Y/N)"* → chọn **Y**. Lesson được nạp vào mọi lần gen sau. Hoặc chủ động `/learn "AI hay X, đúng phải Y"`.
+
+---
+
+## 4. Case 2 — BDD Bug (BDD ≠ PRD)
+
+> Dev gen BDD sai từ đầu, hoặc PRD đã update nhưng BDD chưa.
+
+```
+Tester                    Dev                       PO/BA
+──────                    ────────────              ──────
+Gửi bug report
+(BDD scenario mâu
+ thuẫn với PRD AC)
+                          Đọc PRD → BDD: xác nhận BDD sai
+                          Nếu PRD rõ ràng:
+                            → update BDD scenario + code nếu cần
+                            → /dev-run-test → dev self-check pass
+                            → /validate-traces → PR + notify
+                          Nếu PRD chưa đủ rõ → báo PO
+                                                    Clarify PRD
+                                                    (không đổi version
+                                                     nếu chỉ làm rõ)
+                          Update BDD + code → PR + notify
+Re-test
+```
+
+**Ví dụ:**
+
+```
+Bug: FT-001 — BDD ghi "3 lần sai → khoá", PRD ghi "5 lần"
+PRD AC3 : "5 lần sai → khoá"           ✅
+BDD SC3 : "When 3 failures, Then 423"   ❌  ← dev gen BDD sai
+Code    : if failCount >= 3: lock()     ❌  ← code theo BDD sai
+Fix: 1) BDD 3→5  2) code >=3 → >=5  3) update test data
+→ notify: "BDD + code fixed, re-test với 5 lần"
+```
+
+---
+
+## 5. Case 3 — PRD Ambiguity (PRD không rõ)
+
+> Không ai sai — PRD viết thiếu, dev và tester hiểu khác nhau.
+
+```
+Tester                    Dev                       PO/BA
+──────                    ────────────              ──────
+Gửi bug report
+(AC mơ hồ: dev hiểu
+ X, tester expect Y)
+                          Đọc PRD → xác nhận AC chưa đủ rõ
+                          KHÔNG tự fix code
+                          Báo PO: "AC3 mơ hồ: dev assume 5 lần,
+                          tester expect 3. Đúng là bao nhiêu?"
+                                                    Quyết định: 5 lần
+                                                    Update PRD AC3
+                                                    Bump version nếu
+                                                    thay đổi behavior
+                                                    Notify dev + tester
+                          Nhận PRD mới; update BDD/code nếu cần
+                          /validate-traces → PR + notify
+Re-test theo PRD mới
+```
+
+**Ví dụ:**
+
+```
+PRD AC3: "Sai password nhiều lần → khoá tài khoản"  ← "nhiều lần" = bao nhiêu?
+Dev assume 5 lần; Tester expect 3 lần (thông lệ ngân hàng)
+→ Không phải bug code/BDD — là PRD thiếu thông tin
+→ PO quyết định 5 lần: "Sai password 5 lần liên tiếp → khoá 30 phút"
+→ BDD đã đúng → chỉ close bug, không fix code
+```
+
+---
+
+## 6. Case 4 — PRD Change (yêu cầu thay đổi)
+
+> Không phải bug — business requirement thay đổi sau khi đã implement.
+
+```
+Tester                    Dev                       PO/BA
+──────                    ────────────              ──────
+Gửi bug report
+(behavior đổi theo
+ yêu cầu business mới)
+                          So sánh PRD version: code theo v1.0,
+                          tester expect v1.1 → báo PO xác nhận
+                                                    Xác nhận: PRD change,
+                                                    không phải bug
+                                                    Update PRD v1.1
+                                                    Notify dev + tester
+                          Nhận PRD v1.1
+                          /review-context → xem diff
+                          Update BDD + code + tests
+                          /validate-traces → PR + notify:
+                          "Implemented per PRD v1.1; re-test behavior mới"
+Re-test theo PRD v1.1
+```
+
+**Lưu ý quan trọng:** Bug report phải được **re-classify** thành "PRD Change Request" trước khi xử lý — không đưa vào bug backlog.
+
+---
+
+## 7. Case 5 — Design Spec Bug (UI ≠ Design Spec)
+
+> Chỉ áp dụng cho FE/App. Code không khớp Design Spec.
+
+```
+Tester                    Dev (FE/App)              PO/BA + Designer
+──────                    ────────────              ──────────────────
+Gửi bug report
+(screen X không khớp
+ Design Spec section Y)
+                          Đọc Design Spec → xác nhận spec nói gì
+                          Nếu code sai Design Spec:
+                            → fix code theo spec → PR + notify
+                          Nếu Design Spec sai/lỗi thời:
+                            → báo PO/Designer
+                                                    Review + update Design Spec
+                                                    Notify dev
+                          Nhận Design Spec mới → fix code → PR + notify
+Re-test UI
+```
+
+---
+
+## 8. Case 6 — Environment / Data Bug
+
+> Spec đúng hết, code đúng hết — lỗi ở infra hoặc test data.
+
+```
+Dấu hiệu nhận biết:
+- Bug chỉ xảy ra trên staging, không reproduce local
+- Bug xảy ra với 1 user cụ thể, không với user khác
+- Bug xảy ra sau deploy, không trước
+- /dev-run-test (dev_selftest — dev self-check) pass nhưng manual / QC test fail
+
+Xử lý:
+Tester → cung cấp: environment, user ID, timestamp, request ID
+Dev    → check logs, config, database state
+DevOps → check infra, env vars, deploy artifacts
+```
+
+---
+
+## 9. Giao tiếp hiệu quả — các format thông báo
+
+### Git flow của feedback loop (2 repo, 1 vòng)
+
+Mọi feedback đi qua **git**, không qua chat: file được ghi vào spec repo, commit+push, rồi PO/Dev kéo về bằng `/sync`. Đây là đường đi đầy đủ — từ lúc QC/Tester phát hiện tới lúc bug `Closed`:
+
+```
+  QC / Tester                     SPEC REPO (PO sở hữu)              SERVICE SUBMODULE (Dev sở hữu)
+  ─────────────                   ─────────────────────              ──────────────────────────────
+  /report-bug      read-only
+  /propose-scenario  specs/code
+  (QC: /qc-run-test FAIL,
+   /qc-analyze DOC_GAPS)
+        │ ghi file ──────────────▶ feedback/bug-reports/*.md          (KHÔNG sửa specs/code trực tiếp)
+                                   feedback/bdd-proposals/*.md
+                                   feedback/prd-change-requests/*.md
+                                     State: Open
+                                       │ git commit + push  (tầng spec repo)
+                                       ▼
+                                  origin(spec) ──── /sync (PO/Dev pull) ────┐
+                                                                            ▼
+                                       ┌──────────────── phân loại (Case 1–6) ───────────────┐
+                                       ▼                                                      ▼
+                          PRD/BDD gap → PO sửa PRD + bump                  Code bug → Dev /fix-bug {BUG-ID}
+                          → commit+push spec repo                          → set State: Fixed
+                          → /generate-bdd lại                              → commit+push service (tầng 1)
+                                       │                                   + umbrella pointer (tầng 2)
+                                       └───────────────────┬──────────────────┘
+                                                           ▼
+                          QC /qc-run-test re-verify ──── pass ──▶ State: Closed
+                                                                  (qc_owner / qc_blocked_by tự clear)
+```
+
+- **2 tầng push** chỉ áp dụng phía service submodule (xem [Sync & Update §4.4](sync-and-update.md#44--commit-2-tầng-thay-đổi-trong-service-submodule)); feedback file nằm trong **spec repo** nên chỉ cần push 1 tầng ở đó.
+- `/sync` chỉ surface bug `State: Open`; `Fixed`/`Closed` để riêng (xem [§10](#10-checklist-đóng-bug)).
+
+### Bug report (Tester → Dev)
+
+Tester chạy `/report-bug {UC-ID} {mô tả}` → tự sinh report theo format dưới (gồm phân loại layer + phát hiện coverage gap), commit+push vào **spec repo** `feedback/bug-reports/{BUG-ID}.md`. PO/Dev thấy khi chạy `/sync` (dòng `📥 New tester feedback`):
+
+```
+[BUG-{ID}] {Feature} — {mô tả ngắn}
+
+Spec:  {PRD path} v{x.x} | AC{N}: "{AC text}"
+BDD:   {BDD path} → "{Scenario title}"   (hoặc: ⚠️ no scenario covers this)
+Layer: Code / BDD / PRD / Env  ← Tester đề xuất, Dev xác nhận
+
+Expected: {theo spec}
+Actual:   {thực tế}
+Repro:    {steps}
+Env:      staging / {date deploy}
+```
+
+> **Nếu Layer = "coverage gap"** (behavior đúng nhưng chưa scenario nào cover): tester chạy `/propose-scenario {UC-ID}` → draft scenario vào `bdd-proposals/` cho PO/Dev duyệt. Xem [Case 2](#4-case-2--bdd-bug-bdd--prd).
+
+### Fix xong (Dev → Tester)
+
+```
+[BUG-{ID}] Fixed ✅
+
+Root cause: Case {1..6} — {mô tả ngắn}
+Changed:
+  - {file/component}: {what changed}
+  - BDD: {updated / unchanged}
+  - PRD: {unchanged / clarified by PO}
+
+Deploy: staging @ {time} — {commit/PR link}
+Re-test: {BDD scenario ID hoặc AC number}
+```
+
+### Cần PO clarify (Dev → PO)
+
+```
+[PRD-CLARIFY] {Feature} — AC{N} mơ hồ
+
+Tình huống:
+  Dev implement: {X}
+  Tester expect: {Y}
+  Triggered by: BUG-{ID}
+
+PRD AC hiện tại: "{AC text}"
+
+Câu hỏi: {câu hỏi cụ thể — 1 câu}
+Cần trả lời trước: {date} để unblock tester
+```
+
+---
+
+## 10. Checklist đóng bug
+
+Trước khi đánh "Resolved":
+
+**Dev:**
+- [ ] Root cause xác định rõ (Case 1/2/3/4/5/6)
+- [ ] Fix đúng layer — không patch code khi lỗi ở BDD hoặc PRD
+- [ ] `/validate-traces` → no broken traces
+- [ ] `/dev-run-test` → dev self-check pass (`dev_selftest` — smoke check, KHÔNG thay official QC `qc_status` do `/qc-run-test` set)
+- [ ] Nếu root cause là lỗi AI gen hay lặp → đã `/learn` (hoặc accept prompt khi `/fix-bug`)
+- [ ] Notify tester với đầy đủ thông tin re-test
+
+**Tester / QC:**
+- [ ] Re-test đúng scenario được chỉ định (QC: `/qc-run-test {UC-ID}` lại → `qc_status` flip `fail → pass`)
+- [ ] Kiểm tra regression: các AC khác của cùng PRD không bị ảnh hưởng
+- [ ] Confirm PASS trước khi close
+
+**Vòng đời bug report (đừng để `feedback/` phình mãi):**
+- [ ] `State` của `feedback/bug-reports/{BUG-ID}.md`: `🟢 Open` → `🟡 Fixed` (set bởi `/fix-bug {BUG-ID}`) → `🟢 Closed` (sau khi `/qc-run-test` re-verify pass).
+- [ ] Khi `Closed`: `/qc-run-test` clear `qc_owner`/`qc_blocked_by` của SC (tự động khi `qc_status=pass`); tuỳ chọn move file sang `feedback/bug-reports/archive/`.
+- [ ] `/sync` chỉ surface bug `State: Open` là "đang chờ" — Fixed/Closed không làm nhiễu PO/PM.
+
+**PO** *(nếu PRD được cập nhật)*:
+- [ ] PRD version mới đã được bump
+- [ ] Changelog có entry cho thay đổi
+- [ ] Notify dev và tester về version mới
+
+---
+
+*Xem thêm:* [Sync & Update](sync-and-update.md) · [Guide · Tester](../02-guides/tester/README.md) · [chương QC Automation](../02-guides/tester/qc-automation.md).

package/docs/04-operations/publishing.md

@@ -0,0 +1,137 @@
+[📚 Docs](../README.md) › [Operations](README.md) › Publishing
+
+# Publishing — Publish lên npm
+
+> Hướng dẫn publish package `@edupia-tutor/spec-driven-docs` lên npm: setup lần đầu, publish version mới, kiểm tra sau publish, và transfer ownership.
+
+Package: `@edupia-tutor/spec-driven-docs`
+Registry: <https://www.npmjs.com/package/@edupia-tutor/spec-driven-docs>
+
+---
+
+## Mục lục
+
+1. [Yêu cầu](#1-yêu-cầu)
+2. [Setup lần đầu](#2-setup-lần-đầu)
+3. [Publish version mới](#3-publish-version-mới)
+4. [Kiểm tra sau khi publish](#4-kiểm-tra-sau-khi-publish)
+5. [Transfer package sang account khác](#5-transfer-package-sang-account-khác)
+
+---
+
+## 1. Yêu cầu
+
+- Node.js đã cài (`node -v`)
+- Tài khoản npm: <https://www.npmjs.com> — account có quyền publish vào scope `@edupia-tutor`
+
+---
+
+## 2. Setup lần đầu
+
+### 2.1 — Đăng nhập npm
+
+```powershell
+npm login
+```
+
+Trình duyệt sẽ mở trang xác thực npm. Đăng nhập bằng account có quyền publish vào scope `@edupia-tutor`, sau đó quay lại terminal. Kiểm tra:
+
+```powershell
+npm whoami
+# output: <npm-username>
+```
+
+### 2.2 — Tạo Access Token (nếu cần dùng CI hoặc tránh 2FA mỗi lần)
+
+1. Vào <https://www.npmjs.com> → Avatar → **Access Tokens**
+2. **Generate New Token** → **Granular Access Token**
+3. Điền:
+   - Name: `publish-spec-driven-docs`
+   - Expiration: 1 year
+   - Packages: chọn `@edupia-tutor/spec-driven-docs` → **Read and write**
+4. Copy token, lưu vào nơi an toàn
+
+Publish với token:
+
+```powershell
+npm publish --token <your-token>
+```
+
+---
+
+## 3. Publish version mới
+
+### Bước 1 — Cập nhật nội dung commands (nếu có thay đổi)
+
+Sửa các file trong thư mục `commands/`.
+
+### Bước 2 — Tăng version trong `package.json` (semver)
+
+| Loại thay đổi | Lệnh | Ví dụ |
+|---|---|---|
+| Fix nhỏ, sửa lỗi | `npm version patch` | 0.1.0 → 0.1.1 |
+| Thêm command mới | `npm version minor` | 0.1.0 → 0.2.0 |
+| Thay đổi lớn, breaking | `npm version major` | 0.1.0 → 1.0.0 |
+
+```powershell
+# Ví dụ: thêm command mới
+npm version minor
+```
+
+Lệnh này tự động cập nhật `version` trong `package.json` và tạo git commit + tag.
+
+### Bước 3 — Publish
+
+```powershell
+npm publish
+```
+
+### Bước 4 — Push git (bao gồm tag vừa tạo)
+
+```powershell
+git push && git push --tags
+```
+
+---
+
+## 4. Kiểm tra sau khi publish
+
+```powershell
+# Xem version mới trên npm
+npm view @edupia-tutor/spec-driven-docs version
+
+# Chạy thử
+npx @edupia-tutor/spec-driven-docs@latest
+```
+
+---
+
+## 5. Transfer package sang account khác
+
+Khi cần chuyển quyền sở hữu package cho người khác (ví dụ: sang account `edupia-tutor`):
+
+### Thêm maintainer
+
+```powershell
+npm owner add <npm-username> @edupia-tutor/spec-driven-docs
+```
+
+### Transfer toàn bộ
+
+```powershell
+npm access grant read-write <npm-username> @edupia-tutor/spec-driven-docs
+```
+
+Hoặc làm thủ công trên website:
+
+1. Vào <https://www.npmjs.com/package/@edupia-tutor/spec-driven-docs>
+2. Tab **Settings** → **Maintainers** → thêm username mới
+
+> **Lưu ý:** Nếu muốn đổi tên package, cần publish lại với tên mới vì npm không cho đổi tên package đã publish. Sau đó deprecate package cũ:
+> ```powershell
+> npm deprecate @edupia-tutor/spec-driven-docs "Moved to <new-package-name>"
+> ```
+
+---
+
+*Xem thêm:* [Sync & Update](sync-and-update.md) (`/update-framework` kéo version mới từ npm về project) · [Bug Flow](bug-flow.md).