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

package/core/skills/qc/qa-analyst/data-flow.md

@@ -52,9 +52,13 @@ Thể hiện luồng dạng bước tuần tự hoặc sơ đồ text:
 
 ## Output
 
+Ghi vào **mục Data Flow** của `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md`
+(KHÔNG tạo file riêng — qc-analyze chỉ trả 2 file: `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md`):
+
 - Sơ đồ/list luồng dữ liệu cho mỗi kịch bản chính.
 - Danh sách integration point + state change + failure point.
-- Chặng nào luồng/hành vi chưa rõ (vd lỗi xử lý ra sao, retry, partial commit) →
-  ghi vào `DOC_GAPS.md` (loại MISSING / OPEN QUESTION).
 - Gợi ý loại test cần cho từng điểm (gui-feature / integration / e2e) khi sang qa-designer.
 - Dữ liệu/trạng thái cần chuẩn bị & cleanup → đầu vào fixture cho qa-runner.
+
+Chặng nào luồng/hành vi chưa rõ (vd lỗi xử lý ra sao, retry, partial commit) →
+ghi vào `{paths.qc_dir}/{UC-ID}/DOC_GAPS.md` (loại MISSING / OPEN QUESTION).

package/core/skills/qc/qa-analyst/spec-breakdown.md

@@ -46,12 +46,16 @@ F. GIẢ ĐỊNH & CÂU HỎI MỞ: điều suy ra được vs điều cần dev
 
 ## Output
 
-File Markdown mô tả yêu cầu có cấu trúc (đặt trong `docs/<project>/<feature>/`):
+⚠️ `/qc-analyze` chỉ ghi **ĐÚNG 2 FILE** cho mỗi UC, đặt trong thư mục QC **lộ ra ngoài**
+`{paths.qc_dir}/{UC-ID}/` (mặc định `docs/{UC-ID}/` — KHÔNG để trong `.agent/` ẩn):
+`REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md`. KHÔNG tách mỗi bước phân tích thành file riêng.
+
+Phần spec-breakdown là **mục đầu tiên** của `REQUIREMENT_ANALYSIS.md`:
 - Bảng chức năng + input/output/constraint
 - Sơ đồ/list luồng chính & phụ
 - Danh sách giả định và câu hỏi mở (đánh dấu rõ điều CHƯA chắc)
 
-Đồng thời ghi mọi khoảng trống phát hiện vào `docs/<project>/<feature>/DOC_GAPS.md`
-(theo `.claude/skills/qa-analyst/DOC_GAPS.template.md`), mỗi gap có ID `GAP-xx`.
+Đồng thời ghi mọi khoảng trống phát hiện vào `{paths.qc_dir}/{UC-ID}/DOC_GAPS.md`
+(theo `{paths.qc_skills_dir}/qa-analyst/DOC_GAPS.template.md`), mỗi gap có ID `GAP-xx`.
 
 Kết thúc bằng gợi ý: feature đã đủ rõ để chuyển sang `qa-planner` (phân tích rủi ro) chưa.

package/core/skills/qc/qa-designer/e2e/journey.md

@@ -37,5 +37,5 @@ Mỗi journey → 1 TC bám Format; Expected = chuỗi verify point; chuẩn b
 **Journey phụ thuộc gap vẫn viết + 🚫 Block: GAP-xx**, định tuyến ghi "dự kiến theo BR". Trace BR.
 
 ## Output
-File TC e2e (hoặc nhóm E2E trong file feature) trong `docs/<project>/<feature>/`.
+File TC e2e (hoặc nhóm E2E trong file feature) trong `{paths.qc_dir}/{UC-ID}/test-cases/`.
 In bảng `E2E-ID | Journey | Pri | Trace | Block` + bảng TC block. Bàn giao `qa-reviewer`.

package/core/skills/qc/qa-designer/exploratory/charter.md

@@ -63,6 +63,6 @@ Sinh 10-15 câu hỏi cho dev/BA (assumptions, edge case, error handling, securi
  
 ## Output
  
-Charter files: docs/<project>/exploratory/charters/<feature>_01.md, _02.md...
-Ideas file: docs/<project>/exploratory/ideas/<feature>.md
+Charter files: {paths.qc_dir}/exploratory/charters/<feature>_01.md, _02.md...
+Ideas file: {paths.qc_dir}/exploratory/ideas/<feature>.md
 Bảng tổng kết: STT | Charter | Tour | Risk | Time-box

package/core/skills/qc/qa-designer/exploratory/explore-to-functional.md

@@ -37,7 +37,7 @@ Chuyển draft → TC chính thức bám **format file `TC_<FEATURE>.md`**:
   **Trace** `[BR-xx](REQUIREMENT_ANALYSIS.md#3-business-rules)` (không có BR → `⚠️ Chưa có Business Rule`) · **🚫 Block** `[GAP-xx]` nếu chặn.
 - **Test Data** dạng list · **Steps** `[Action]`/`[Verify]` · **Expected** 1 bullet cụ thể.
 - Phân nhóm GUI/Functional · cuối file: Trace matrix + bảng TC block · bỏ nội dung gạch ngang.
-- Đặt file `docs/<project>/<feature>/TC_<FEATURE>.md`.
+- Đặt file `{paths.qc_dir}/{UC-ID}/test-cases/TC_<FEATURE>.md`.
 
 ## Output
 File TC functional + bảng `TC_ID | Title | Priority | Technique | Trace`. Bàn giao `qa-reviewer`.

package/core/skills/qc/qa-designer/functional/api.md

@@ -41,5 +41,5 @@ response (schema thành công + các mã lỗi 4xx/5xx + body lỗi) · side-eff
 - Mỗi TC bám khối Format; Expected ghi status code + phần body verify; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC (`TC_<FEATURE>_API.md` hoặc gộp trong file feature) trong `docs/<project>/<feature>/`.
+File TC (`TC_<FEATURE>_API.md` hoặc gộp trong file feature) trong `{paths.qc_dir}/{UC-ID}/test-cases/`.
 In bảng TC + Trace matrix. Bàn giao `qa-reviewer`.

package/core/skills/qc/qa-designer/functional/gui-feature.md

@@ -42,5 +42,5 @@ Liệt kê các màn/route + thứ tự điều hướng · state/dữ liệu tr
 - Mỗi TC bám khối Format; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File `TC_<FEATURE>.md` trong `docs/<project>/<feature>/`. In bảng TC + Trace matrix + bảng TC block.
+File `TC_<FEATURE>.md` trong `{paths.qc_dir}/{UC-ID}/test-cases/`. In bảng TC + Trace matrix + bảng TC block.
 Bàn giao `qa-reviewer` (test-case).

package/core/skills/qc/qa-designer/functional/gui-screen.md

@@ -48,5 +48,5 @@ chức năng (input/action/display/nav) · constraint (required/min-max/format/e
 - Mỗi TC bám khối Format trên; trace BR; TC chặn bởi gap → 🚫 Block.
 
 ## Output
-File `TC_<FEATURE>.md` trong `docs/<project>/<feature>/`. In bảng `TC_ID | Title | Priority | Tags | Trace`
+File `TC_<FEATURE>.md` trong `{paths.qc_dir}/{UC-ID}/test-cases/`. In bảng `TC_ID | Title | Priority | Tags | Trace`
 + Trace matrix + bảng TC block. Bàn giao `qa-reviewer` (test-case).

package/core/skills/qc/qa-designer/integration/api.md

@@ -39,4 +39,4 @@ Nhóm TC: happy (dữ liệu đúng đầu→cuối) → contract negative (inpu
 → concurrency → điều kiện đồng bộ (đổ/không đổ). Mỗi TC bám Format; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC integration trong `docs/<project>/<feature>/`. Ưu tiên P0 cho định tuyến & tiền-dữ liệu. Bàn giao `qa-reviewer`.
+File TC integration trong `{paths.qc_dir}/{UC-ID}/test-cases/`. Ưu tiên P0 cho định tuyến & tiền-dữ liệu. Bàn giao `qa-reviewer`.

package/core/skills/qc/qa-designer/integration/db.md

@@ -35,5 +35,5 @@ Nhóm TC: ghi đúng giá trị (happy) → default/null đúng → update khôn
 → audit log → ràng buộc/unique (negative). Mỗi TC bám Format; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC trong `docs/<project>/<feature>/`. Ghi rõ query kiểm tra DB + yêu cầu cleanup;
+File TC trong `{paths.qc_dir}/{UC-ID}/test-cases/`. Ghi rõ query kiểm tra DB + yêu cầu cleanup;
 không hardcode ID, chuẩn bị/dọn data qua fixture. Bàn giao `qa-reviewer`.

package/core/skills/qc/qa-designer/integration/gui.md

@@ -37,4 +37,4 @@ Nhóm TC: UI render đúng dữ liệu backend (happy) → empty state → lỗi
 Mỗi TC bám Format; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC trong `docs/<project>/<feature>/`. Mỗi TC nêu API liên quan + biểu hiện UI. Bàn giao `qa-reviewer`.
+File TC trong `{paths.qc_dir}/{UC-ID}/test-cases/`. Mỗi TC nêu API liên quan + biểu hiện UI. Bàn giao `qa-reviewer`.

package/core/skills/qc/qa-designer/integration/kafka.md

@@ -37,4 +37,4 @@ Nhóm TC: phát đúng topic+payload (happy) → điều kiện không phát →
 Mỗi TC bám Format; trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC trong `docs/<project>/<feature>/`. Mỗi TC ghi topic, key, payload cần verify + hành vi consumer. Bàn giao `qa-reviewer`.
+File TC trong `{paths.qc_dir}/{UC-ID}/test-cases/`. Mỗi TC ghi topic, key, payload cần verify + hành vi consumer. Bàn giao `qa-reviewer`.

package/core/skills/qc/qa-designer/non-functional.md

@@ -37,4 +37,4 @@ Mỗi TC bám Format; **Expected có ngưỡng pass + công cụ đo**; đánh d
 Trace BR; gap chặn → 🚫 Block.
 
 ## Output
-File TC non-functional trong `docs/<project>/<feature>/`. Mỗi TC ghi tiêu chí đo + ngưỡng + công cụ. Bàn giao `qa-reviewer`.
+File TC non-functional trong `{paths.qc_dir}/{UC-ID}/test-cases/`. Mỗi TC ghi tiêu chí đo + ngưỡng + công cụ. Bàn giao `qa-reviewer`.

package/core/skills/qc/qa-planner/test-plan.md

@@ -8,9 +8,9 @@ ported_from: ai-automation-qc-base
 
 Tổng hợp **output của qa-analyst** thành **Test Plan** cho một feature.
 
-**Đầu vào (bắt buộc, chỉ 2 nguồn):**
-1. `docs/<project>/<feature>/REQUIREMENT_ANALYSIS.md` — chức năng, BR-xx, AC-xx, data flow (qa-analyst).
-2. `docs/<project>/<feature>/DOC_GAPS.md` — bảng gap GAP-xx, mức độ, gap Blocker (qa-analyst).
+**Đầu vào (bắt buộc, chỉ 2 nguồn — đúng 2 file qa-analyst trả ra):**
+1. `{paths.qc_dir}/{UC-ID}/REQUIREMENT_ANALYSIS.md` — chức năng, BR-xx, AC-xx, data flow (qa-analyst).
+2. `{paths.qc_dir}/{UC-ID}/DOC_GAPS.md` — bảng gap GAP-xx, mức độ, gap Blocker (qa-analyst).
 
 ## Khi nào trigger
 - "lập test plan cho [Feature]" / "viết test plan"
@@ -53,7 +53,7 @@ Tổng hợp **output của qa-analyst** thành **Test Plan** cho một feature.
 
 ## Output — Template `TEST_PLAN.md`
 
-Đặt tại `docs/<project>/<feature>/TEST_PLAN.md`:
+Đặt tại `{paths.qc_dir}/{UC-ID}/TEST_PLAN.md`:
 
 ```markdown
 # Test Plan – <Feature>

package/core/skills/qc/qa-runner/exploratory/session.md

@@ -23,7 +23,7 @@ Skill **tự chứa**, 2 mode:
 Input: charter + tour + tester + time-box. Tạo file gồm: metadata (date/tester/charter/tour/env/data) ·
 `#SETUP` (bước chuẩn bị) · `#TEST` (5–8 gợi ý theo tour) · `#BUG` template (title, severity, steps,
 expected/actual) · `#QUESTION`, `#IDEA` placeholder · summary cuối session.
-→ `docs/<project>/exploratory/sessions/<YYYY-MM-DD>_<tester>.md`
+→ `{paths.qc_dir}/exploratory/sessions/<YYYY-MM-DD>_<tester>.md`
 
 ## Mode 2 — Convert Findings
 Input: session note (#BUG + #IDEA).
@@ -33,4 +33,4 @@ Input: session note (#BUG + #IDEA).
 - **Weekly summary** (nếu yêu cầu): overview, top findings, coverage gap, recommendations.
 
 ## Output
-Mode 1: file session note. Mode 2: bug reports + file TC trong `docs/<project>/<feature>/` + summary.
+Mode 1: file session note. Mode 2: bug reports + file TC trong `{paths.qc_dir}/{UC-ID}/test-cases/` + summary.

package/core/skills/test/SKILL.md

@@ -331,6 +331,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -343,6 +345,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -387,6 +391,7 @@ If `services` section is present:
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
 
 > **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
@@ -765,6 +770,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -777,6 +784,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -821,6 +830,7 @@ If `services` section is present:
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
 
 > **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 

package/core/steps/context-loader.md

@@ -36,6 +36,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -48,6 +50,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -92,6 +96,7 @@ If `services` section is present:
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
 
 > **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 

package/core/templates/project-context.yaml

@@ -36,6 +36,21 @@ paths:
   prd_template: "specs/templates/prd.template.md"
   refinement_dir: ".agent/review"
 
+  # QC's OWN analysis/design working docs (qc-analyze/plan/design-test outputs:
+  # REQUIREMENT_ANALYSIS.md, DOC_GAPS.md, TEST_PLAN.md, test-cases/*.Test.md).
+  # One subfolder per UC: {qc_dir}/{UC-ID}/. Default "docs" (the QC team's own
+  # convention), VISIBLE — not hidden under .agent/. NOTE: specs (PRD / .feature /
+  # design-spec) are NOT here — they come from the PO spec submodule (spec_source).
+  qc_dir: "docs"
+
+  # WHERE the qc-* commands LOAD their skills from (qa-analyst / qa-designer / qa-planner
+  # / qa-reviewer / qa-runner + DOC_GAPS.template.md). Default = the framework-bundled
+  # copy at .agent/skills/qc (works standalone). The QC team OWNS these skills in their
+  # canonical repo (ai-automation-qc-base) — point this at that repo/submodule (e.g.
+  # "qc-base/.claude/skills") so the skills evolve INDEPENDENTLY and are NOT overwritten
+  # by framework upgrade (--init / upgrade.sh rewrite only .agent/, never this path).
+  qc_skills_dir: ".agent/skills/qc"
+
   # Product Definitions
   product_definitions_dir: "specs/product-definition"
   product_definition_template: "specs/templates/product-definition.template.md"
@@ -61,11 +76,14 @@ paths:
   # Trace
   trace_dir: ".trace"
 
-  # Tester feedback (written by /report-bug and /propose-scenario).
+  # Tester / QC feedback (written by /report-bug and /propose-scenario).
   # These live in the SHARED spec repo so PO/Dev see them on their next /sync.
   # In umbrella mode, context-loader auto-resolves them under {spec_source}/feedback/.
   bug_reports_dir: "feedback/bug-reports"
   bdd_proposals_dir: "feedback/bdd-proposals"
+  # PRD change requests (new requirement found in test, not covered by any AC) —
+  # written by /propose-scenario Case B so the PO can add/extend an AC then re-/generate-bdd.
+  prd_change_requests_dir: "feedback/prd-change-requests"
 
 tech_stack:
   language: "{{LANGUAGE}}"              # e.g., Java 17 / TypeScript / C# / Go

package/docs/01-getting-started/installation.md

@@ -89,6 +89,8 @@ git diff .agent/ && git add .agent/ && git commit -m "chore: upgrade framework"
 ```
 
 > Chỉ upgrade framework command files. `project-context.yaml`, `CLAUDE.md`, domain-knowledge, và `.trace/` không bao giờ bị ghi đè. Để sync *content* của project (submodule code/specs) dùng `/sync`.
+>
+> ⚠️ **QC skills & upgrade:** `--init` / `upgrade.sh` ghi đè **toàn bộ** `.agent/` — **gồm cả** `.agent/skills/qc/`. Nếu QC chỉnh skills trực tiếp trong `.agent/skills/qc/`, các thay đổi đó **mất** khi upgrade. Để giữ an toàn, trỏ `paths.qc_skills_dir` ra một repo/submodule QC **ngoài** `.agent/` (vd `qc-base/.claude/skills`) — upgrade không bao giờ chạm tới đó. Chi tiết: [../02-guides/qc-automation.md#skill-sourcing--upgrade-safety](../02-guides/qc-automation.md#skill-sourcing--upgrade-safety).
 
 ## QC automation stack (tùy chọn)
 
@@ -130,7 +132,7 @@ Mở Review Board: sidebar panel (Activity Bar), hoặc right-click file `*-find
 Đọc `.trace/*.tsv` — dashboard traceability health toàn project.
 
 - Stat cards: PRDs, Use Cases, Scenarios, Code Cov%, Test Cov%, Drift, Gap.
-- Drill-down: PRD → UC → per-scenario table (Spec ver, Gen ver, Code, Tests, `dev_selftest`, `qc_status`, Status).
+- Drill-down: PRD → UC → per-scenario table (Spec ver, Gen ver, Code, Tests, `dev_selftest`, `qc_status`, Waiting on, Status). *Waiting on* = `qc_owner` + `qc_blocked_by` (chờ dev → `BUG-{id}` / chờ PO → `GAP-{id}`).
 - Status badges: ✅ OK · ⚠️ DRIFT · 🔴 GAP · — UNTRACKED. Filter + search + live reload.
 
 Mở: `Ctrl+Shift+P` → **"Spec Driven Dev: Open Living Documentation"**. Mở được cả ở umbrella root lẫn trong một service submodule riêng lẻ. Nếu trống, chạy `/generate-bdd` cho ≥1 feature để tạo file `.trace/{UC-ID}.tsv` đầu tiên.

package/docs/02-guides/developer/commands.md

@@ -56,7 +56,7 @@ Dev hành động theo phân loại:
 - **Scenario proposal map vào AC sẵn có** → thêm scenario vào `.feature` (hoặc `/generate-bdd` lại), rồi `/generate-code` + `/dev-gen-test`
 - **Proposal là yêu cầu mới (PRD change request)** → chuyển PO sửa PRD trước
 
-> Bug reports có thể đến từ hai nguồn: Tester dùng `/report-bug` trực tiếp, **hoặc** từ kết quả QC automation (`qc_status: fail` trong `.trace/*.tsv` → tester chạy `/report-bug` → `/sync` → dev thấy tại đây). Cả hai đều dùng cùng luồng `/fix-bug`.
+> Bug reports có thể đến từ hai nguồn: Tester dùng `/report-bug` trực tiếp, **hoặc** từ kết quả QC automation (`qc_status: fail` trong `.trace/*.tsv` → QC (hoặc tester) chạy `/report-bug` → `/sync` → dev thấy tại đây). Cả hai đều dùng cùng luồng `/fix-bug`.
 
 > Tester chỉ *đề xuất* trong `feedback/` — dev/PO mới đưa vào BDD chính thức. Giữ đúng ownership.
 

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

@@ -54,6 +54,8 @@ BE:      my-project-specs/specs/bdd/{domain}/system/{TICKET-ID}-UC*.feature
 Tạo PR → notify PO/SA review
 ```
 
+> **Commit ở đâu, push mấy tầng?** Code + `.trace/` nằm trong service submodule → **commit 2 tầng** (service rồi umbrella pointer); tech-docs đẩy lên spec repo. Sơ đồ git đầy đủ theo từng role: [Sync & Update — Git flow theo role](../../04-operations/sync-and-update.md#ai-commit-vào-repo-nào-git-flow-theo-role).
+
 ---
 
 ← [BDD & Trace System](bdd-and-trace.md) · Tiếp theo: [Tình huống thực tế](scenarios.md)

package/docs/02-guides/qc-automation.md

@@ -35,13 +35,20 @@ Cả hai hiển thị **cạnh nhau** trong Living Docs; không cái nào ghi đ
 
 | Command | Vai trò | Output |
 |---------|---------|--------|
-| `/qc-analyze` | bóc tách spec chính thức thành requirement + BR/AC + data-flow + `DOC_GAPS` | `{refinement_dir}/qc/{UC-ID}/` |
+| `/qc-analyze` | bóc tách spec chính thức thành **1 file phân tích gộp** (requirement + BR/AC + data-flow) + `DOC_GAPS` | `{qc_dir}/{UC-ID}/` → `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md` (**2 file**) |
 | `/qc-plan` | risk / what-if / questions-for-dev + test plan | `TEST_PLAN.md` |
 | `/qc-design-test` | thiết kế test case (Markdown `.Test.md`), tag `@trace.verifies={UC-ID}-SC{N}` | `test-cases/` |
 | `/qc-review` | cổng review hai chiều: review test case (sau design) và script (sau run) | findings |
 | `/qc-run-test` | sinh + chạy Python pytest-playwright; **ghi `qc_status`** per scenario | `{trace_dir}/{UC-ID}.tsv` |
 | `/qc-report` | report pytest-html + Playwright trace + evidence | `reports/<feature>/report.html` |
 
+> **Nơi lưu artifact (`qc_dir`):** mọi output của pipeline (trừ report) nằm trong thư mục QC
+> **lộ ra ngoài** `{qc_dir}/{UC-ID}/` — mặc định `docs/{UC-ID}/`, cấu hình qua `paths.qc_dir`
+> trong `project-context.yaml`. Đây là **working-doc riêng của QC** trong repo QC, **không ẩn**
+> (KHÔNG nằm trong `.agent/`). Spec gốc (PRD/`.feature`/design-spec) KHÔNG nằm đây — chúng đến
+> từ **submodule spec của PO** (`spec_source`). `/qc-analyze` chỉ ghi **đúng 2 file**:
+> `REQUIREMENT_ANALYSIS.md` (phân tích gộp) + `DOC_GAPS.md`.
+
 ## Stack — Module qc-playwright
 
 `/qc-run-test` và `/qc-report` dùng stack module `qc-playwright`
@@ -84,6 +91,64 @@ Các skill chi tiết theo từng giai đoạn QC nằm trong `skills/qc/`:
 
 Mỗi skill **tự chứa** (self-contained) và có version frontmatter để theo dõi khi nâng cấp.
 
+## Khi QC Tìm Thấy Bug / Spec Gap — Đẩy Lên Specs
+
+QC chạy pipeline nhưng **không tự sửa spec/code**. Khi phát hiện vấn đề, đẩy lên spec repo của PO
+qua flow feedback có sẵn (`/report-bug` · `/propose-scenario` — PO/Dev nhận khi `/sync`):
+
+| QC phát hiện ở | Loại | Hành động |
+|---|---|---|
+| `/qc-run-test` FAIL = **product-gap** (impl ≠ spec, lỗi thật) | bug | `/report-bug {UC-ID} {expected vs actual}` |
+| `/qc-run-test` FAIL = **script-bug** (sai selector/logic script) | — | QC tự sửa script + chạy lại (**KHÔNG** file bug) |
+| `/qc-analyze` `DOC_GAPS` blocker = **spec sai / mơ hồ / mâu thuẫn** (PRD·BDD) | spec defect | `/report-bug {UC-ID}` (BUG_FLOW phân loại PRD/BDD) |
+| `/qc-analyze` `DOC_GAPS` = **thiếu coverage** (behavior trong AC nhưng chưa có scenario) | coverage gap | `/propose-scenario {UC-ID}` |
+| `DOC_GAPS` = `ASSUMPTION` / `OPEN QUESTION` | câu hỏi | qc-plan → questions-for-dev (xác nhận với PO/Dev, không file bug) |
+
+`/report-bug` ghi `feedback/bug-reports/BUG-xxx.md` + commit/push lên spec repo; `/propose-scenario`
+ghi `feedback/bdd-proposals/`. PO/Dev thấy khi `/sync`, rồi BUG_FLOW định tuyến root cause:
+
+```
+• Code bug       → Dev /fix-bug                                  (KHÔNG đổi spec)
+• BDD sai / thiếu → sửa .feature / promote proposal → /generate-bdd
+• PRD mơ hồ / sai → PO sửa PRD → /refine-prd → /review-context → /generate-bdd
+        ↓ (nếu spec đổi → regenerate)
+  /generate-code lại  →  QC /qc-run-test lại  →  qc_status: fail → pass
+```
+
+> QC chỉ **đọc** spec (từ submodule PO) — mọi thay đổi PRD/BDD là việc của PO/Dev. QC đẩy *tín hiệu*
+> (bug / proposal / gap), không tự sửa canonical spec. `/qc-report` ở cuối pipeline **in sẵn** danh
+> sách lệnh `/report-bug` cho từng product-gap để QC chạy. Chi tiết flow bug: [Operations · Bug Flow](../04-operations/bug-flow.md).
+
+## Skill Sourcing & Upgrade-Safety
+
+Các skill QC (`qa-analyst` / `qa-designer` / `qa-planner` / `qa-reviewer` / `qa-runner` +
+`DOC_GAPS.template.md`) **không bị hardcode** — command nạp chúng từ `paths.qc_skills_dir`:
+
+| Tình huống | `qc_skills_dir` | Hệ quả khi `/update-framework` |
+|---|---|---|
+| Mặc định (standalone) | `.agent/skills/qc` (bản framework bundle) | **Bị ghi đè** mỗi lần upgrade → đừng sửa trực tiếp ở đây |
+| QC sở hữu skill (khuyến nghị) | repo QC / submodule, vd `qc-base/.claude/skills` | **Không bao giờ bị đụng** — upgrade chỉ rewrite `.agent/` |
+
+> `qc_skills_dir` chỉ cần trỏ tới thư mục **chứa các folder `qa-*`**. Cả 2 layout đều hợp lệ:
+> framework bundle (`.agent/skills/qc/qa-analyst/…`) và repo QC (`.claude/skills/qa-analyst/…`).
+
+**Cách QC tách skill ra khỏi vòng đời framework:**
+
+```bash
+# 1. Đưa repo skill của QC vào project (submodule để pin version):
+git submodule add <ai-automation-qc-base-repo-url> qc-base
+
+# 2. Trỏ qc_skills_dir trong .agent/project-context.yaml:
+#    paths:
+#      qc_skills_dir: "qc-base/.claude/skills"
+
+# 3. Từ giờ: QC hoàn thiện skill trong repo qc-base, bump submodule khi cần.
+#    /update-framework ghi đè .agent/ nhưng KHÔNG chạm qc-base/ → skill an toàn.
+```
+
+Nhờ vậy **vòng đời skill QC** và **vòng đời framework** tách hẳn nhau: nâng cấp framework
+không nuốt mất skill đang hoàn thiện, và QC update skill 1 chỗ (repo của họ) cho mọi project.
+
 ## Xem Thêm
 
 - [Guide › Tester](tester/README.md) — vai trò tester, spec-manifest, `/report-bug`, `/propose-scenario`

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

@@ -65,6 +65,8 @@ PRD            BDD (từ PRD)           /sync + /generate-spec-manifest
 
 Đây là **bộ test chính thức (authoritative) của QC**, chạy ngay trong framework. Pipeline dùng stack module `qc-playwright` (Python + pytest-playwright + Page Object). Xem chi tiết flow tại **[QC Automation guide](../qc-automation.md)**.
 
+> **Artifact ra đâu:** `/qc-analyze` ghi **2 file** (`REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md`), `/qc-plan` → `TEST_PLAN.md`, `/qc-design-test` → `test-cases/*.Test.md` — tất cả trong `{qc_dir}/{UC-ID}/` (mặc định `docs/`, **visible**, không phải `.agent/` ẩn). Skill QC nạp từ `paths.qc_skills_dir` — trỏ được tới repo QC để skill **không bị `/update-framework` ghi đè**. Chi tiết: [QC Automation guide](../qc-automation.md#skill-sourcing--upgrade-safety).
+
 > **Phân biệt với test commands của Dev:** `/dev-gen-test`, `/dev-run-test`, `/dev-smoke-test` là **dev tự kiểm tra code của mình** — phát tín hiệu `dev_selftest`, KHÔNG phải bộ test chính thức. Bộ test authoritative của QC là pipeline `/qc-*` (sinh ra `qc_status`). Hai luồng tách biệt.
 
 ---

package/docs/02-guides/tester/bug-reporting.md

@@ -30,7 +30,7 @@ Nếu `/report-bug` báo *coverage gap* (behavior đúng nhưng chưa có scenar
 ```
 
 - Nếu behavior **đã nằm trong một AC của PRD** → lệnh draft Gherkin (tag `@proposed @from-test`), ghi vào `{spec_source}/feedback/bdd-proposals/` → commit + push. PO/Dev review rồi đưa vào `.feature`.
-- Nếu behavior **chưa có trong PRD** → lệnh dừng và xuất *PRD change request* cho PO.
+- Nếu behavior **chưa có trong PRD** → lệnh **ghi** một *PRD change request* (`State: Open`) vào `{spec_source}/feedback/prd-change-requests/{UC-ID}-{slug}.md` → commit + push (KHÔNG chỉ in ra). PO thấy nó khi `/sync`, thêm/sửa AC rồi `/generate-bdd` lại.
 
 > Tester không tự ghi vào BDD — chỉ đề xuất. Giữ đúng ownership.
 

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

@@ -41,9 +41,10 @@ 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

package/docs/03-concepts/architecture.md

@@ -62,6 +62,8 @@ LAYER 5 — OUTPUT                          (artifacts in consumer proj)
     src/ · .trace/*.tsv (authoritative, committed) · .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
 ```
 

package/docs/03-concepts/pipeline.md

@@ -90,10 +90,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 +120,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}
 ```

package/docs/03-concepts/traceability.md

@@ -103,7 +103,8 @@ 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:**

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 · Tester · QC
 
-> 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, Tester, và QC 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: [Guide · QC Automation](../02-guides/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