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

package/docs/04-operations/sync-and-update.md

@@ -48,7 +48,7 @@ Có 2 thứ cần update, **nguồn khác nhau, tần suất khác nhau**:
 
 - Pull specs (spec submodule) + services (service submodules).
 - Refresh Living Docs panel (regenerate trace report — xem [§5](#5-living-docs-sync)).
-- Liệt kê **📥 New tester feedback** — bug report / scenario proposal mới từ tester trong vùng `feedback/` của spec repo.
+- Liệt kê **📥 New tester feedback** — bug report / scenario proposal mới từ tester trong vùng `feedback/` của spec repo. Chỉ surface bug có `State: Open` là đang chờ; `State: Fixed` (chờ QC re-verify) / `Closed` liệt kê riêng để không làm nhiễu view của PO/PM. Vòng đời đầy đủ: [bug-flow.md §10](bug-flow.md).
 
 ```bash
 /sync
@@ -78,12 +78,49 @@ Service submodules không bị ảnh hưởng — luôn checkout đúng SHA mà
 
 > **Umbrella mode:** `/update-framework` chỉ cần chạy ở **umbrella root**. Service submodule chỉ chứa `.agent/project-context.yaml` (config), không có command files → không cần nâng cấp riêng.
 
+> ⚠️ **`--init` ghi đè TOÀN BỘ `.agent/`** (gồm cả `.agent/skills/qc/`) — KHÔNG đụng `.agent/project-context.yaml` (config của bạn) và mọi thứ **ngoài** `.agent/`.
+> **Hệ quả với skill QC:** nếu QC sửa skill **trực tiếp trong `.agent/skills/qc/`** thì sẽ **mất sau upgrade**. Để skill QC tồn tại độc lập, trỏ `paths.qc_skills_dir` (trong `.agent/project-context.yaml`) tới **repo QC riêng / submodule** (vd `qc-base/.claude/skills`) — `qc_skills_dir` nằm ngoài `.agent/` nên upgrade không bao giờ chạm. Chi tiết: [Guide · QC Automation](../02-guides/qc-automation.md#skill-sourcing--upgrade-safety).
+
 ---
 
 ## 4. Umbrella mode & git submodule
 
 Claude Code luôn mở ở **umbrella repo** (không mở trong service submodule). Umbrella thấy được cả spec submodule (read-only) lẫn service submodule (code).
 
+### Ai commit vào repo nào? (git flow theo role)
+
+3 repo độc lập (mỗi cái có origin riêng), umbrella chỉ giữ **pointer**. Mỗi role ghi vào repo khác nhau → số "tầng push" khác nhau:
+
+```
+                UMBRELLA REPO  (Claude Code mở ở đây · .gitmodules + docs/)
+                      │  giữ pointer (SHA) tới từng submodule
+        ┌─────────────┴──────────────┐
+        ▼                             ▼
+ SPEC SUBMODULE                SERVICE SUBMODULE(s)
+ (PO sở hữu · origin riêng)    (Dev sở hữu · origin riêng)
+ specs/prd · specs/bdd               src/
+ specs/design-spec                   .trace/*.tsv   (qc_status + dev_selftest)
+ specs/tech-docs (API contract)
+ feedback/ (bug · proposal · prd-change-request)
+```
+
+| Role | Tạo gì | Repo đích | Push mấy tầng |
+|------|--------|-----------|---------------|
+| **PO** | PRD · BDD · design-spec · sửa PRD theo change-request | SPEC repo | **1 tầng** (spec repo) |
+| **Dev (FE/BE)** | tech-docs · code · dev test (`dev_selftest`) | tech-docs → SPEC repo · code + `.trace/` → SERVICE | code: **2 tầng** (service → umbrella pointer) · tech-docs: thêm 1 tầng ở spec repo |
+| **QC** | analysis/test-cases · `qc_status` · bug/gap | artifacts → `{qc_dir}/{UC-ID}/` (umbrella root `docs/`) · `qc_status` → SERVICE `.trace/` · bug/gap → SPEC `feedback/` | trace: **2 tầng** · feedback: 1 tầng (spec repo) |
+| **Tester** | bug report · scenario proposal · prd-change-request | SPEC repo `feedback/` | **1 tầng** (spec repo) — read-only trên specs/code |
+
+Thứ tự bàn giao (mỗi mũi tên = `git push` rồi role kế tiếp `/sync`):
+
+```
+PO ─push spec─▶ Dev /sync ─code 2 tầng─▶ QC /sync ─qc_status 2 tầng + bug/gap 1 tầng─▶ PO/Dev /sync
+ BDD approved      tech-docs + src         test + report            fix code / sửa PRD → /generate-bdd lại
+                                                                    (vòng feedback: xem Bug Flow §9)
+```
+
+> **`qc_status` ở service nhưng analysis docs ở umbrella:** `qc_dir` (mặc định `docs/`) **không** auto-route theo service như `trace_dir`. Muốn artifacts QC nằm cùng service submodule (push chung 2 tầng với trace) → set `paths.qc_dir` trong `{service}/.agent/project-context.yaml`, hoặc trỏ ra repo QC riêng.
+
 ### 4.1 — Clone lần đầu
 
 ```bash

package/docs/05-reference/commands.md

@@ -123,12 +123,12 @@
 
 | Command | Input | Output | When to use |
 |---------|-------|--------|-------------|
-| `/qc-analyze` | feature file / UC-ID | QC analysis of scenarios + risks | After BDD approved — đầu pipeline QC. |
-| `/qc-plan` | QC analysis | Test plan (scope, layers, priorities) | After `/qc-analyze`. |
-| `/qc-design-test` | test plan | Test case designs mapped to `{UC-ID}-SC{N}` | After `/qc-plan`. |
-| `/qc-review` | test designs | Reviewed/approved test design set | After `/qc-design-test`. |
-| `/qc-run-test` | test designs | Execution results — ghi `qc_status` (pass/fail/skip/not_run) + `qc_run_at` vào trace TSV, keyed by `@trace.verifies={UC-ID}-SC{N}` | After `/qc-review`. |
-| `/qc-report` | run results | QC report (Playwright Trace + pytest-html) | After `/qc-run-test`. |
+| `/qc-analyze` | feature file / UC-ID | **2 file** trong `{qc_dir}/{UC-ID}/` (mặc định `docs/`): `REQUIREMENT_ANALYSIS.md` (gộp requirement + BR + data-flow + AC) + `DOC_GAPS.md` | After BDD approved — đầu pipeline QC. |
+| `/qc-plan` | `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md` | `{qc_dir}/{UC-ID}/TEST_PLAN.md` (scope, layers, priorities, questions-for-dev) | After `/qc-analyze`. |
+| `/qc-design-test` | `TEST_PLAN.md` + `REQUIREMENT_ANALYSIS.md` | `{qc_dir}/{UC-ID}/test-cases/*.Test.md` mapped to `{UC-ID}-SC{N}` | After `/qc-plan`. |
+| `/qc-review` | test-case `.Test.md` **hoặc** script Python | Verdict APPROVED / NEEDS_FIX + findings (**inline — không sinh file**) | After `/qc-design-test` (test-case) hoặc `/qc-run-test` (script). |
+| `/qc-run-test` | reviewed `.Test.md` | Script Python (`pages/`, `tests/`) + ghi `qc_status` (pass/fail/skip/not_run) + `qc_run_at` vào trace TSV, keyed by `@trace.verifies={UC-ID}-SC{N}` | After `/qc-review`. |
+| `/qc-report` | run results | QC report `reports/<feature>/report.html` (Playwright Trace + pytest-html) | After `/qc-run-test`. |
 
 ---
 
@@ -140,14 +140,14 @@
 
 ---
 
-## Phase 8 — Tester Feedback
+## Phase 8 — Tester / QC Feedback
 
-> Cả hai đều **read-only trên canonical specs/code**. Chúng chỉ ghi vào `feedback/` của shared spec repo và **commit + push** → PO/Dev thấy qua `/sync`. Testers không bao giờ sửa `.feature` trực tiếp.
+> Cả hai đều **read-only trên canonical specs/code**. Chúng chỉ ghi vào `feedback/` của shared spec repo và **commit + push** → PO/Dev thấy qua `/sync`. Tester/QC không bao giờ sửa `.feature` trực tiếp. QC cũng dùng hai lệnh này: `/qc-run-test` FAIL = product-gap và `/qc-analyze` DOC_GAPS blocker đều route sang `/report-bug` hoặc `/propose-scenario` (xem [../02-guides/qc-automation.md](../02-guides/qc-automation.md)).
 
 | Command | Input | Output | When to use |
 |---------|-------|--------|-------------|
-| `/report-bug {UC-ID} {desc}` | UC/TICKET + description | `{spec_repo}/feedback/bug-reports/{BUG-ID}.md` + spec context + layer classification | Tester tìm thấy bug. Phân loại layer (Code/BDD/PRD/Design/Env) để route. |
-| `/propose-scenario {UC-ID} {desc}` | UC + edge-case description | `{spec_repo}/feedback/bdd-proposals/{UC-ID}-*.md` draft Gherkin | Tester tìm thấy edge case BDD chưa cover. Map vào PRD AC sẵn có, hoặc emit PRD change request nếu hành vi thực sự mới. |
+| `/report-bug {UC-ID} {desc}` | UC/TICKET + description | `{spec_repo}/feedback/bug-reports/{BUG-ID}.md` + spec context + layer classification | Tester hoặc QC tìm thấy bug (gồm QC product-gap). Phân loại layer (Code/BDD/PRD/Design/Env) để route. |
+| `/propose-scenario {UC-ID} {desc}` | UC + edge-case description | `{spec_repo}/feedback/bdd-proposals/{UC-ID}-*.md` draft Gherkin | Tester hoặc QC tìm thấy edge case BDD chưa cover. Map vào PRD AC sẵn có, hoặc emit PRD change request nếu hành vi thực sự mới. |
 
 ---
 
@@ -155,7 +155,7 @@
 
 | Command | Input | Output | When to use |
 |---------|-------|--------|-------------|
-| `/fix-bug` | — | Bug fix | When a bug is found. |
+| `/fix-bug {BUG-ID\|ticket\|desc}` | filed `BUG-ID` (đọc spec-context từ report) / ticket / description | Code fix trên branch + regression test; nếu nhận `{BUG-ID}` → set report State `🟢 Open` → `🟡 Fixed` (QC re-verify pass mới → `🟢 Closed`) | Khi tìm thấy bug/ticket, hoặc route một filed bug report. |
 | `/debug` | — | Debug session | Deep debugging. |
 | `/learn {text}` | "AI does X, should Y" | Appends guardrail vào project lessons file | Khi AI lặp lại lỗi bạn muốn chặn. |
 | `/generate-spec-manifest` | — | `spec-manifest.yaml` | Sinh manifest làm entry point cho external/tester agents. |

package/docs/05-reference/modules.md

@@ -85,9 +85,9 @@ Ví dụ adapt theo platform type:
 
 **Folder structure:**
 ```
-docs/<project>/<feature>/   ← test-case Markdown (.Test.md) — source of truth
+{paths.qc_dir}/{UC-ID}/test-cases/ ← test-case Markdown (.Test.md) — source of truth (mặc định docs/, lộ ra ngoài)
 pages/                      ← Page Object Model (base_page.py + <feature>_page.py)
-tests/                      ← pytest scripts, 1-1 với docs/ (conftest.py + test_<feature>.py)
+tests/                      ← pytest scripts, 1-1 với test-cases/ (conftest.py + test_<feature>.py)
 utils/                      ← config_loader, logger, steps, test_ordering, report helpers
 test_data/                  ← JSON datasets
 config/config.yaml          ← browser, timeout, video/screenshot/trace toggles

package/docs/05-reference/trace-schema.md

@@ -22,10 +22,10 @@
 Tab-separated, một header row + một data row mỗi scenario. Header chính xác (từ `generate-bdd.tmpl`):
 
 ```
-sc_id	sc_title	spec_ver	gen_ver	implemented_by	test_count	test_classes	dev_selftest	dev_selftest_at	qc_status	qc_run_at	prd_version	bdd_version	tech_doc_revision	prd_status	uc_status	fe_phase	status	last_updated
+sc_id	sc_title	spec_ver	gen_ver	implemented_by	test_count	test_classes	dev_selftest	dev_selftest_at	qc_status	qc_run_at	qc_owner	qc_blocked_by	prd_version	bdd_version	tech_doc_revision	prd_status	uc_status	fe_phase	status	last_updated
 ```
 
-19 cột, theo đúng thứ tự trên.
+21 cột, theo đúng thứ tự trên.
 
 ---
 
@@ -44,16 +44,22 @@ sc_id	sc_title	spec_ver	gen_ver	implemented_by	test_count	test_classes	dev_selft
 | 9 | `dev_selftest_at` | Ngày chạy dev self-check (`YYYY-MM-DD`) | `—` | **dev-run-test** |
 | 10 | `qc_status` | Kết quả QC chính thức: `pass` / `fail` / `skip` / `not_run` | `—` | **qc-run-test** |
 | 11 | `qc_run_at` | Ngày chạy QC (`YYYY-MM-DD`) | `—` | **qc-run-test** |
-| 12 | `prd_version` | `@trace.prd_version` từ `.feature` header | từ `.feature` | generate-bdd |
-| 13 | `bdd_version` | `@trace.bdd_version` từ `.feature` header | từ `.feature` | generate-bdd |
-| 14 | `tech_doc_revision` | Tech-doc revision tại thời điểm codegen | `—` | generate-code |
-| 15 | `prd_status` | `\| **Status** \|` từ PRD metadata | từ PRD | generate-bdd |
-| 16 | `uc_status` | Trạng thái UC: `draft` / `approved` / … | `draft` (UC mới) | generate-bdd |
-| 17 | `fe_phase` | FE phase khi implement (`ui` / `integration`) | `—` | generate-code `--phase` |
-| 18 | `status` | Trạng thái tổng hợp: `OK` / `DRIFT` / `GAP` / `UNTRACKED` | `UNTRACKED` | validate-traces |
-| 19 | `last_updated` | Ngày update gần nhất (`YYYY-MM-DD`) | today | mọi command ghi row |
+| 12 | `qc_owner` | **Đang chờ ai** (PM view) khi SC chưa pass: `dev` / `po` / `—` | `—` | **qc-run-test** / **report-bug** |
+| 13 | `qc_blocked_by` | Artifact liên quan: `BUG-{id}` / `GAP-{id}` / `—` | `—` | **qc-run-test** / **report-bug** |
+| 14 | `prd_version` | `@trace.prd_version` từ `.feature` header | từ `.feature` | generate-bdd |
+| 15 | `bdd_version` | `@trace.bdd_version` từ `.feature` header | từ `.feature` | generate-bdd |
+| 16 | `tech_doc_revision` | Tech-doc revision tại thời điểm codegen | `—` | generate-code |
+| 17 | `prd_status` | `\| **Status** \|` từ PRD metadata | từ PRD | generate-bdd |
+| 18 | `uc_status` | Trạng thái UC: `draft` / `approved` / … | `draft` (UC mới) | generate-bdd |
+| 19 | `fe_phase` | FE phase khi implement (`ui` / `integration`) | `—` | generate-code `--phase` |
+| 20 | `status` | Trạng thái tổng hợp: `OK` / `DRIFT` / `GAP` / `UNTRACKED` | `UNTRACKED` | validate-traces |
+| 21 | `last_updated` | Ngày update gần nhất (`YYYY-MM-DD`) | today | mọi command ghi row |
 
-> **Re-generation rules (generate-bdd):** SC đã có trong TSV & `spec_ver` không đổi → chỉ update `sc_title`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated`. Nếu `spec_ver` đổi → thêm `spec_ver` và set `status = DRIFT` ngay. SC mới → append với `gen_ver`/`implemented_by`/`test_count`/`test_classes`/`dev_selftest`/`dev_selftest_at`/`qc_status`/`qc_run_at`/`tech_doc_revision` = `—`. SC bị xóa khỏi `.feature` → xóa row.
+> **`qc_owner` / `qc_blocked_by` (PM "waiting-on" view):** dành cho PO kiêm PM xem **case nào đang chờ ai**. `/qc-run-test` set khi ghi `qc_status`: product-gap FAIL → `qc_owner=dev`; `skip`/`not_run` do `DOC_GAPS` 🔴 Blocker mở → `qc_owner=po` + `qc_blocked_by=GAP-{id}`; `pass` → cả hai về `—`. `/report-bug` backfill `qc_blocked_by=BUG-{id}` (+ `qc_owner` theo layer) cho SC khớp. `/validate-traces` tổng hợp `waiting_dev` / `waiting_po` cho dashboard.
+
+> **Re-generation rules (generate-bdd):** SC đã có trong TSV & `spec_ver` không đổi → chỉ update `sc_title`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated`. Nếu `spec_ver` đổi → thêm `spec_ver` và set `status = DRIFT` ngay. SC mới → append với `gen_ver`/`implemented_by`/`test_count`/`test_classes`/`dev_selftest`/`dev_selftest_at`/`qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by`/`tech_doc_revision` = `—`. SC bị xóa khỏi `.feature` → xóa row.
+
+> **Backward-compat:** TSV cũ (19 cột, trước nâng cấp) thiếu `qc_owner`/`qc_blocked_by` → `/validate-traces` đọc thành `null`, không lỗi; lần `/generate-bdd` re-gen kế tiếp tự nâng header lên 21 cột.
 
 ---
 
@@ -133,7 +139,7 @@ Per-scenario trong file: `# @trace.scenario: {UC-ID}-SC{N}`, `# @trace.sc_versio
 `/validate-traces` ghi `{paths.trace_dir}/trace-report.json` — single source of truth cho web dashboards. Cấu trúc rút gọn:
 
 - `generated_at`, `domain`
-- `summary` — aggregates: `total_prds`, `approved_prds`, `total_ucs`, `approved_ucs`, `draft_ucs`, `total_scs`, `coded_scs`, `tested_scs`, `code_coverage_pct`, `test_coverage_pct`, `drift_count`, `gap_count`, `untracked_count`, `dev_selftest_passing/failing/not_run`, `qc_passing/failing/skipped/not_run`, `tech_docs_count`
+- `summary` — aggregates: `total_prds`, `approved_prds`, `total_ucs`, `approved_ucs`, `draft_ucs`, `total_scs`, `coded_scs`, `tested_scs`, `code_coverage_pct`, `test_coverage_pct`, `drift_count`, `gap_count`, `untracked_count`, `dev_selftest_passing/failing/not_run`, `qc_passing/failing/skipped/not_run`, `waiting_dev`, `waiting_po`, `tech_docs_count`
 - `prds[]` → `ucs[]` → `scenarios[]` — mỗi scenario có đầy đủ các trường của TSV row (gồm `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`)
 - `issues` — phân loại: `drift`, `gap`, `untracked`, `prd_version_drift`, `techdoc_drift`, mỗi entry kèm `fix` command gợi ý
 

package/modules/qc-playwright/stack-profile.yaml

@@ -22,11 +22,11 @@ architecture:
     - "Group tests by (role, account) so login/logout never interleaves across roles"
     - "Cover 100% of TCs in the .Test.md — every TC ends Pass/Fail/Skip, none left Draft"
   folder_structure: |
-    docs/<project>/<feature>/      ← test-case Markdown (.Test.md) — source of truth
+    {paths.qc_dir}/{UC-ID}/test-cases/   ← test-case Markdown (.Test.md) — source of truth (mặc định docs/, lộ ra ngoài)
     pages/                         ← Page Object Model
     │   ├── base_page.py           ← slim BasePage (click/fill/wait/screenshot)
     │   └── <feature>_page.py
-    tests/                         ← pytest scripts, 1-1 with docs/
+    tests/                         ← pytest scripts, 1-1 with test-cases/
     │   ├── conftest.py            ← fixtures: browser, page, logged_in_page, tracing
     │   └── <project>/test_<feature>.py
     utils/                         ← config_loader, logger, steps, test_ordering, report helpers
@@ -41,7 +41,7 @@ coding_standards:
     test_function: "test_TC<NNN>_<snake_case>"
     page_object: "<feature>_page.py with <Feature>Page class extending BasePage"
     files:
-      test_case_md: "docs/<project>/<feature>/TC_<FEATURE>.Test.md"
+      test_case_md: "{paths.qc_dir}/{UC-ID}/test-cases/TC_<FEATURE>.Test.md"
       page_object: "pages/<feature>_page.py"
       test_script: "tests/<project>/test_<feature>.py"
   patterns:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anhth2/spec-driven-dev-plugin",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "AI-First Spec-Driven Development workflow plugin for Claude Code",
   "bin": {
     "spec-driven-dev": "./bin/index.js"

package/skills/code/SKILL.md

@@ -152,6 +152,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
@@ -164,6 +166,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`
@@ -208,6 +212,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/skills/debug/SKILL.md

@@ -67,6 +67,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
@@ -79,6 +81,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`
@@ -123,6 +127,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/skills/design-spec/SKILL.md

@@ -141,6 +141,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
@@ -153,6 +155,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`
@@ -197,6 +201,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/skills/discovery/SKILL.md

@@ -46,6 +46,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
@@ -58,6 +60,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`
@@ -102,6 +106,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/skills/qc/qa-analyst/acceptance-criteria.md

@@ -51,6 +51,10 @@ Mỗi AC gắn mã trace: chức năng + BR-xx để TC sau này map 1-1.
 
 ## Output
 
-- Danh sách AC dạng Given/When/Then, có mã trace về chức năng và business rule.
+Ghi vào **mục Acceptance Criteria** 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`):
+
+- Danh sách AC dạng Given/When/Then, có mã trace về chức năng, business rule (BR-xx)
+  và scenario chính thức `{UC-ID}-SC{N}` của `.feature`.
 - Bảng ma trận: BR / chức năng × AC để xác nhận không bỏ sót.
 - Đây là đầu vào trực tiếp cho `qa-designer` (mỗi AC → ≥1 test case) và `qa-reviewer` (đối chiếu coverage).

package/skills/qc/qa-analyst/business-rules.md

@@ -49,7 +49,11 @@ Với rule có nhiều điều kiện kết hợp → gợi ý dựng **Decision
 
 ## Output
 
+Ghi vào **mục Business Rules** 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`):
+
 - Bảng business rule có ID (BR-xx) để TC trace ngược về.
-- Rule MÂU THUẪN / KHÔNG RÕ → ghi vào `DOC_GAPS.md` (loại CONTRADICTORY / AMBIGUOUS,
-  cột "Ảnh hưởng" trỏ BR-xx) rồi ghi vào `DOC_GAPS.md`.
 - Gợi ý các rule cần Decision Table / BVA khi sang qa-designer.
+
+Rule MÂU THUẪN / KHÔNG RÕ → ghi vào `{paths.qc_dir}/{UC-ID}/DOC_GAPS.md`
+(loại CONTRADICTORY / AMBIGUOUS, cột "Ảnh hưởng" trỏ BR-xx).

package/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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.