@anhth2/spec-driven-dev-plugin 0.11.0 → 0.14.0

package/docs/02-guides/tester/test-checklist.md

@@ -13,15 +13,15 @@
 - [ ] Cross-service flows đã được verify (nếu feature span nhiều service)
 
 **TSV & Living Docs:**
-- [ ] `/qc-run-test` đã chạy → `qc_status` đã ghi vào `{service}/.trace/{UC-ID}.tsv`
-- [ ] TSV đã được commit vào service submodule + umbrella pointer đã update + push
+- [ ] `/qc-run-test` đã chạy → `qc_status` đã ghi vào `{spec_source}/.trace/{UC-ID}.tsv` (spec repo — một chỗ)
+- [ ] TSV đã được commit vào **spec repo** (1 tầng, giống `feedback/`) + push — KHÔNG commit vào service submodule
 - [ ] `/validate-traces` (hoặc `/sync`) đã chạy → Living Docs panel hiển thị `qc_status: pass`
 - [ ] Không còn scenario nào `qc_status: not_run` trong UC đang test
 - [ ] Nếu có `qc_status: fail` → đã `/report-bug` kèm path evidence (`reports/<feature>/report.html`)
 
 ## Xem Thêm
 
-- [Guide › QC Automation](../qc-automation.md) — pipeline `/qc-*` chi tiết, `qc_status`, stack `qc-playwright`
+- [Guide › QC Automation](qc-automation.md) — pipeline `/qc-*` chi tiết, `qc_status`, stack `qc-playwright`
 - [Operations › Bug Flow](../../04-operations/bug-flow.md) — flow phối hợp Tester ↔ Dev ↔ PO
 - [Concepts › Traceability](../../03-concepts/traceability.md) — trace TSV, dev_selftest vs qc_status
 - [Reference › Commands](../../05-reference/commands.md) — danh mục đầy đủ mọi command

package/docs/02-guides/tester/workflow.md

@@ -17,9 +17,10 @@ Lookup FT-042 trong spec-manifest.yaml
 → status: approved? ✅ (nếu draft → dừng, báo PO)
 → ghi lại paths (tất cả đều nằm trong submodule):
     prd:          {spec_source}/specs/prd/{domain}/FT-042-*.md
-    bdd.be:       {service-be}/specs/bdd/{domain}/FT-042-*.feature
-    bdd.web:      {service-web}/specs/bdd/{domain}/FT-042-*.feature
+    bdd.system:   {spec_source}/specs/bdd/{domain}/system/FT-042-*.feature
+    bdd.web:      {spec_source}/specs/bdd/{domain}/web/FT-042-*.feature
     tech_docs.be: {spec_source}/specs/tech-docs/{domain}/FT-042-*.md
+    tech_docs.fe: {spec_source}/specs/tech-docs/{domain}/FT-042-*-tech-design-web.md
         │
         ▼
 Đọc PRD tại path manifest.prd
@@ -28,7 +29,7 @@ Lookup FT-042 trong spec-manifest.yaml
         │
         ▼
 Đọc BDD tại path manifest.bdd.be / bdd.web
-→ file nằm trong SERVICE submodule (be/web/app — PO gen từ PRD)
+→ file nằm trong SPEC submodule (PO gen từ PRD — tất cả BDD web/app/system ở spec repo)
 → mỗi Scenario = 1 test case cần cover
 → BE có BDD riêng (system/), Web có BDD riêng (web/), App có BDD riêng (app/)
         │
@@ -41,30 +42,27 @@ Lookup FT-042 trong spec-manifest.yaml
         ▼
 Chạy QC automation pipeline (6 bước — ghi kết quả chính thức vào TSV)
         │
-        ├─ /qc-analyze {UC-ID}       → bóc tách spec, xác định scope, phát hiện DOC_GAPS
-        ├─ /qc-plan {UC-ID}          → risk + test plan + questions-for-dev
-        ├─ /qc-design-test {UC-ID}   → thiết kế test case chi tiết (.Test.md)
+        ├─ /qc-analyze {UC-ID}       → 2 file: REQUIREMENT_ANALYSIS.md + DOC_GAPS.md
+        ├─ /qc-plan {UC-ID}          → TEST_PLAN.md (risk + plan + questions-for-dev)
+        ├─ /qc-design-test {UC-ID}   → test-cases/*.Test.md
+        │     ⌙ artifact phân tích/thiết kế → {qc_dir}/{UC-ID}/ (mặc định docs/, VISIBLE)
         ├─ /qc-review {UC-ID}        → review test design trước khi chạy
         ├─ /qc-run-test {UC-ID}      → sinh + chạy pytest-playwright
         │                               → ghi qc_status (pass/fail/skip) per scenario
-        │                               → vào {service}/.trace/{UC-ID}.tsv  ← AUTHORITATIVE
+        │                               → vào {spec_source}/.trace/{UC-ID}.tsv  ← AUTHORITATIVE (spec repo)
         └─ /qc-report {UC-ID}        → report pytest-html + Playwright trace evidence
                                         → reports/<feature>/report.html  ← LOCAL, gitignored
         │
         ▼
-Commit TSV vào service submodule + update umbrella pointer
-  cd {service}
+Commit TSV vào spec repo (1 tầng — trace dồn về specs, giống feedback/)
+  cd {spec_source}
   git add .trace/{UC-ID}.tsv
   git commit -m "qc: record qc_status for {UC-ID} — pass/fail"
-  git push
-  cd ..   ← umbrella root
-  git add {service}
-  git commit -m "chore: update {service} submodule pointer — {UC-ID} qc_status"
   git push
         │
         ▼
 /validate-traces (hoặc /sync)
-→ tổng hợp TSVs từ tất cả services → Living Docs cập nhật cột qc_status
+→ đọc {spec_source}/.trace/ (một chỗ) → Living Docs cập nhật cột qc_status
         │
         ▼
 Kết quả:

package/docs/03-concepts/architecture.md

@@ -56,12 +56,15 @@ LAYER 4 — EXECUTION                               (command logic)
                           │
 LAYER 5 — OUTPUT                          (artifacts in consumer proj)
   Spec module (cross-team, via {spec_source}):
-    specs/product-definition/ · specs/prd/ · specs/bdd/
-    specs/tech-docs/ (API contract) · .living-docs/ (gitignored)
+    specs/product-definition/ · specs/prd/ · specs/bdd/ (web/app/system)
+    specs/tech-docs/ (API contract + FE tech-design) · feedback/
+    .trace/*.tsv (authoritative, committed — một chỗ cho PM) · .living-docs/ (gitignored)
   Service submodule (per-service):
-    src/ · .trace/*.tsv (authoritative, committed) · .agent/review/
+    src/ (chỉ code) · .agent/review/
   QC automation outputs:
     QC test cases / scripts (Python pytest-playwright, Page Object)
+    → QC analysis / test-cases ghi vào {qc_dir}/{UC-ID}/ (mặc định docs/,
+      visible — KHÔNG nằm trong .agent/)
     → guides per-layer ở skills/qc/<stage>/ · qc_status trong .trace/*.tsv
 ```
 
@@ -217,7 +220,7 @@ spec-driven-dev/
 
 > **Umbrella mode — API contract (tech-docs) là cross-team artifact:** khi `setup.spec_source` được set, tech-docs LUÔN route về `{spec_source}/specs/tech-docs/` (giống PRD / design-spec / domain-knowledge), KHÔNG per-service — để FE/App đọc contract qua spec submodule ở `/generate-code --phase=integration`. Chỉ khi không có `spec_source` thì tech-docs mới nằm per-service.
 
-> **Living Docs / trace data location:** `.trace/*.tsv` của mỗi service là **authoritative** và commit trong chính service submodule. Canonical report (`trace-report.json` + TSV mirror namespaced) sinh vào spec module tại `{spec_source}/.living-docs/` (gitignored), cộng một panel mirror cục bộ tại `./.trace`. Chi tiết: [traceability.md](traceability.md#living-docs--canonical-trong-spec-module--panel-mirror).
+> **Living Docs / trace data location:** khi `spec_source` set, `.trace/*.tsv` **authoritative** nằm **một chỗ** ở `{spec_source}/.trace/` (committed trong spec repo — PM quản lý tập trung; mỗi scenario mang `@trace.service`). Report `trace-report.json` sinh vào `{spec_source}/.living-docs/` (gitignored) + panel mirror cục bộ `./.trace`. Chỉ khi không có `spec_source` thì `.trace` mới per-service. Chi tiết: [traceability.md](traceability.md#living-docs--canonical-trong-spec-module--panel-mirror).
 
 ---
 

package/docs/03-concepts/pipeline.md

@@ -27,7 +27,7 @@ Vòng đời feature đi qua các phase, mỗi transition có một **AI review
 | **2. PRD** | AI → SA/PO review | `/generate-prd`, `/refine-prd`, `/review-context` | `specs/prd/{domain}/{TICKET-ID}-{slug}.md` |
 | **2b. Design Spec** *(FE/App only)* | AI → Designer/PO sign-off | `/generate-design-spec` | `specs/design-spec/{domain}/{TICKET-ID}-design-spec-{platform}.md` |
 | **3. BDD Spec** | AI → SA/Dev review | `/generate-bdd`, `/review-context` | `specs/bdd/{domain}/{UC-ID}.feature` |
-| **4. Tech Design** | AI → SA/Lead review | `/generate-tech-docs`, `/review-tech-docs` | `tech-docs/{domain}/{UC-ID}-tech-design.md` |
+| **4. Tech Design** *(platform-aware)* | AI → SA/Lead review | `/generate-tech-docs`, `/review-tech-docs` | BE: `tech-docs/{domain}/{UC-ID}-tech-design.md` (API contract) · FE/App: `{UC-ID}-tech-design-{platform}.md` (client design — **gated** trên System BDD + BE contract) |
 | **5. Code** | AI → Dev review | `/generate-code` *(FE: `--phase=ui`/`--phase=integration`)*, `/review-code` | `src/...` |
 | **6. Dev Self-Check** | Dev (own code) | `/dev-gen-test`, `/dev-run-test`, `/dev-smoke-test` | `src/test/...` — dev smoke (`dev_selftest`), tách khỏi QC suite |
 | **6b. QC Automation** *(official QC suite)* | QC | `/qc-analyze` → `/qc-plan` → `/qc-design-test` → `/qc-review` → `/qc-run-test` → `/qc-report` | QC test designs + run results — set `qc_status` (`qc-playwright` module) |
@@ -64,21 +64,33 @@ Phase 2b/3: Design Spec & BDD
         sign-off + /generate-bdd blocked tới khi mọi screen có link)
               [Designer review + PO sign-off]
   /generate-bdd ────────────→ specs/bdd/{domain}/{UC-ID}.feature
+       THỨ TỰ OUTSIDE-IN (khi có client): web → app → system
+         System BDD được TỔNG HỢP từ web+app BDD (client-facing trước → BE/system suy ra để phục vụ)
+         (project chỉ-BE, không web/app: system gen thẳng từ PRD)
        (apply platform vocabulary: web "clicks" / mobile "taps" / backend "submits a request")
   /review-context {feature} → .agent/review/{uc-id}-review-bdd-findings.yaml
        Checks: PRD coverage (mỗi AC + BR bullet → ≥1 scenario) · Gherkin R1–R10 · compliance C1–C5
        ✅ APPROVED → Phase 4
 
-Phase 4: Tech Design
-  /generate-tech-docs ──────→ tech-docs/{domain}/{UC-ID}-tech-design.md
-       (đọc @trace.module → chọn template theo platform; brownfield: reverse-document mode)
+Phase 4: Tech Design  (platform-aware — đọc @trace.platform)
+  BE (system):
+    /generate-tech-docs {system .feature} → tech-docs/{domain}/{UC-ID}-tech-design.md
+         API contract: endpoints, data model, DB, caching (brownfield: reverse-document)
+  FE/App (web|app) — GATED, cần CÓ trước: System BDD + BE contract (approved):
+    /generate-tech-docs {web|app .feature} → tech-docs/{domain}/{UC-ID}-tech-design-{platform}.md
+         client design: components, state, API-integration map theo BE contract, routing,
+         §2b Test Selectors (test-id ổn định cho element có action → QC locate khỏi scan)
+         (thiếu System BDD hoặc BE contract → HALT, in hướng dẫn)
   /review-tech-docs ────────→ .agent/review/{uc-id}-tech-review-findings.yaml
               [Review Board] → --resume (apply + bump revision)
        ✅ APPROVED → Phase 5
 
 Phase 5: Code
   /generate-code ───────────→ src/...  (@trace.implements tags)
-       FE: --phase=ui (UI + mock adapter, tester-ready) → --phase=integration (real API after sign-off)
+       FE: --phase=ui (UI + mock adapter, tester-ready)
+           mock shape: BE contract nếu có (chuẩn) → else System BDD (tạm, warn) — fixture values luôn từ System BDD
+           → khi BE contract approved → /generate-tech-docs {web|app} (FE design, Phase 4)
+           → --phase=integration (wire real API theo §4 của FE tech-design)
        (component enforcement: ✅ existing / ⚠️ TODO blocked / ❌ NEW confirm)
   /review-code ─────────────→ Report: Critical / Major / Minor → fix CRITICAL/MAJOR
 
@@ -90,10 +102,13 @@ Phase 5 (cont): Dev Self-Check  (dev verifies their OWN code — NOT the officia
 
 Phase 5b: QC Automation  (the OFFICIAL QC suite — see below)
 
-Phase 6: Tester Feedback  (QA → PO/Dev, closes the loop)
-  /report-bug {UC-ID} ──────→ {spec}/feedback/bug-reports/{BUG-ID}.md  → commit+push
-  /propose-scenario {UC-ID} → {spec}/feedback/bdd-proposals/{...}.md   → commit+push
-              PO/Dev: /sync → "📥 New tester feedback" → /fix-bug · add to BDD · update PRD
+Phase 6: Tester / QC Feedback  (QA/QC → PO/Dev, closes the loop)
+  /report-bug {UC-ID} ──────→ {spec}/feedback/bug-reports/{BUG-ID}.md (State: Open) → push
+  /propose-scenario {UC-ID} → behavior ∈ AC → {spec}/feedback/bdd-proposals/{...}.md → push
+                              behavior MỚI  → {spec}/feedback/prd-change-requests/{...}.md → push
+              QC nguồn: /qc-run-test FAIL & /qc-analyze DOC_GAPS cũng route vào đây
+              PO/Dev: /sync → "📥 State: Open" → /fix-bug {BUG-ID} (Open→Fixed) · add BDD · update PRD
+              QC: /qc-run-test re-verify pass → bug Closed (qc_owner/qc_blocked_by clear)
 
 Cross-cutting (any role, anytime)
   /sync ────────────────────→ git pull + submodules + Living Docs + surface feedback
@@ -117,8 +132,18 @@ BDD approved (specs/bdd/*.feature)
 /qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report
    (đọc UC/SC, phân tích)                          chạy test → set qc_status
         ▼                                                ▼
-  QC test cases / scripts                       .trace/*.tsv: qc_status
-  (skills/qc/<stage>/ guides)                   (pass/fail/skip/not_run)
+  QC analysis + test cases                      .trace/*.tsv: qc_status
+  → {qc_dir}/{UC-ID}/  (visible, mặc định docs/) (pass/fail/skip/not_run)
+    REQUIREMENT_ANALYSIS.md · DOC_GAPS.md ·       + qc_owner / qc_blocked_by
+    TEST_PLAN.md · test-cases/*.Test.md           (skills load từ {qc_skills_dir})
+
+  ── Feedback loop về spec (đóng vòng) ───────────────────────────────────
+  /qc-analyze DOC_GAPS blocker (spec sai/mơ hồ) ┐
+  /qc-run-test FAIL = product-gap               ├─▶ /report-bug · /propose-scenario
+  /qc-report tổng hợp gap → in sẵn lệnh         ┘            │  (cùng flow tester)
+                                                             ▼
+                                  feedback/ trong spec repo (State: Open)
+                                  → commit+push → PO/Dev thấy qua /sync (xem bug-flow.md)
 
 Mapping: mỗi QC test → scenario qua @trace.verifies={UC-ID}-SC{N}
 ```
@@ -171,7 +196,7 @@ Load toàn bộ project context vào working memory theo thứ tự ưu tiên ng
 | Step | Priority | What loads |
 |------|----------|-----------|
 | 1 | PROJECT-CONFIG | `project-context.yaml` → stack, conventions, domains, services, paths |
-| 1.5 | SERVICE ROUTING | *(umbrella only)* detect active domain, route `specs_dir`/`tech_docs_dir` tới service submodule, store `service_root` |
+| 1.5 | SERVICE ROUTING | *(umbrella only)* detect active domain, route `trace_dir` (+ code) tới service submodule, store `service_root`. Khi `spec_source` set: `specs_dir` (BDD) / `tech_docs_dir` / PRD / design-spec / domain-knowledge / feedback → **spec repo** (cross-team), KHÔNG per-service |
 | 1.6 | SERVICE CONVENTIONS | *(umbrella only)* load `{service_root}/.agent/project-context.yaml` → override `test_command`, `build_command`, `paths.trace_dir` |
 | 2 | PROJECT-CONFIG | `.agent/modules/{module}/stack-profile.yaml` → layer patterns |
 | 3 | **CRITICAL** | `CLAUDE.md` → architecture layers, coding standards, naming |

package/docs/03-concepts/traceability.md

@@ -22,12 +22,12 @@ Mỗi artifact mang `@trace.*` metadata liên kết về artifact trước nó:
 
 ```
 product-definition.md
-  └─► PRD.md (Service, Module trong metadata; @trace.domain, @trace.status)
-        └─► {UC-ID}.feature (@trace.service, @trace.module, @trace.prd_version)
-              └─► tech-design.md (@trace.bdd_version)
-                    └─► src/ code (@trace.implements, @trace.prd_version, @trace.bdd_version)
+  └─► PRD.md (@trace.domain, @trace.status; Service/Module trong metadata)
+        └─► specs/bdd/{domain}/{web|app|system}/{UC-ID}.feature (@trace.prd_version, @trace.module)
+              └─► specs/tech-docs/{domain}/{UC-ID}-tech-design*.md (@trace.bdd_version)
+                    └─► src/ code — service submodule (@trace.implements)
                           └─► src/test/ (@trace.verifies, @trace.service)
-                                └─► .trace/{UC-ID}.tsv (drift tracking)
+   ════► {spec_source}/.trace/{UC-ID}.tsv — TSV authoritative ở SPEC repo (coverage/drift)
 ```
 
 **Các trace field quan trọng:**
@@ -62,7 +62,7 @@ Ví dụ tags trong `.feature`, code, và test:
 
 ## Trace TSV — coverage & drift
 
-`.trace/{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`. File `.trace/*.tsv` authoritative **được commit** trong chính service submodule (không phải mirror).
+`.trace/{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:
 
@@ -103,28 +103,29 @@ Living Docs (VS Code panel) đọc trace TSV và hiển thị traceability healt
 └──────────────────────────────────────────────────────────────────┘
 ```
 
-- Drill down: PRD → UC → per-scenario table (Spec ver, Gen ver, Code, Tests, **Dev Self-Check**, **QC Status**, Status)
+- 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? |
 |--------|---------|---------|
-| `{service}/.trace/*.tsv` | **Authoritative** — nguồn sự thật per-service | ✅ Committed trong service submodule |
-| `{spec_source}/.living-docs/` (`trace-report.json` + TSV mirror namespaced) | **Canonical report** — tổng hợp cross-team, 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 kể cả khi mở Claude Code/VS Code bên trong một service submodule đơn lẻ | ❌ Gitignored |
+| `{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 canonical nằm ở spec module?** Spec module được mount vào mọi umbrella/service workspace, nên nó là nơi chung luôn resolve được cho cross-team dashboard. Vấn đề trước đây: panel mở ở umbrella root (hoặc một service submodule đơn lẻ) sẽ TRỐNG nếu không có mirror — vì TSV authoritative nằm rải rác trong từng service submodule. Panel mirror `./.trace` giải quyết case mở single service.
+**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` (cả hai là mirror read-only, không commit):
+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 / umbrella root (mirror)
+# workspace không phải spec repo (panel mirror)
 .trace/
 ```
 
-> **Prerequisite cho data chính xác:** mỗi service submodule cần `.agent/project-context.yaml` với `paths.trace_dir` configure đúng. Thiếu → framework không biết ghi trace TSV về đâu → panel thiếu data.
+> **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.)
 
 ---
 
@@ -134,10 +135,10 @@ Chạy `/validate-traces {domain}` bất cứ lúc nào (đặc biệt **sau m
 
 ```
 /validate-traces {domain}
-→ Reads .trace/*.tsv authoritative (committed) trong từng service:
-  user-service/.trace/, order-service/.trace/, ...
-→ Writes canonical trace-report.json + TSV mirror → {spec_source}/.living-docs/ (gitignored)
-→ Writes panel mirror → ./.trace của workspace hiện tại (non-empty khi mở single service)
+→ 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
 ```
 

package/docs/04-operations/README.md

@@ -4,7 +4,7 @@
 
 > 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 · Tester · QC) và người maintain framework.
+Mục này dành cho cả team (PO · Dev · QC/Tester) và người maintain framework.
 
 ---
 

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

@@ -1,8 +1,10 @@
 [📚 Docs](../README.md) › [Operations](README.md) › Bug Flow
 
-# Bug Flow — PO · Dev · Tester
+# Bug Flow — PO · Dev · QC/Tester
 
-> Cách **PO, Dev, và 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.
+> 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).
 
 ---
 
@@ -242,6 +244,40 @@ 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`):
@@ -306,11 +342,16 @@ Trước khi đánh "Resolved":
 - [ ] 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:**
-- [ ] Re-test đúng scenario được chỉ định
+**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
@@ -318,4 +359,4 @@ Trước khi đánh "Resolved":
 
 ---
 
-*Xem thêm:* [Sync & Update](sync-and-update.md) · [Guide · Tester](../02-guides/tester/README.md) · [Guide · QC Automation](../02-guides/qc-automation.md).
+*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).