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

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

@@ -14,18 +14,19 @@ Tài liệu dành cho **QA / Tester** — cách kết nối với spec framework
 | [Tình huống thực tế](scenarios.md) | 6 scenario: feature mới, PRD thay đổi, multi-service, regression, ... |
 | [Báo cáo bug](bug-reporting.md) | `/report-bug` · `/propose-scenario` · template báo cáo |
 | [Checklist test pass](test-checklist.md) | Checklist trước khi báo "test pass" |
+| [QC Automation](qc-automation.md) | Deep-dive pipeline `/qc-*` 6 bước · stack `qc-playwright` · `qc_status` → Living Docs |
 
 ## Vai Trò Tester Trong Framework
 
 ```
-PO/BA          Dev                    Tester
-──────────     ──────────────────     ──────────────────────────
-PRD            BDD (từ PRD)           /sync + /generate-spec-manifest
-               Tech Docs              Đọc PRD + BDD + Tech Docs
-               Code                   Viết test cases · Chạy test
-   ▲              ▲                    /report-bug      (bug → spec-traced)
-   │              │                    /propose-scenario (edge case → BDD draft)
-   └──────────────┴───── feedback/ trong spec repo ◄────┘
+PO/BA                 Dev                     Tester / QA
+─────────────────     ───────────────────     ──────────────────────────
+PRD                   (đọc BDD — KHÔNG gen)    /sync + /generate-spec-manifest
+BDD web→app→system    Tech Docs               Đọc PRD + BDD + Tech Docs
+Design Spec           Code                    Viết test cases · chạy /qc-*
+   ▲                     ▲                     /report-bug · /propose-scenario
+   │                     │                     (bug / edge case → spec repo)
+   └─────────────────────┴──── feedback/ trong spec repo ◄────┘
         PO/Dev thấy qua /sync (📥) → fix / promote / update PRD
 ```
 
@@ -63,12 +64,12 @@ PRD            BDD (từ PRD)           /sync + /generate-spec-manifest
 | `/qc-run-test` | Chạy automation test → ghi `qc_status` per scenario vào trace TSV | Bước 5 |
 | `/qc-report` | Tổng hợp kết quả thành QC report | Bước 6 |
 
-Đâ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)**.
+Đâ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 **chương [QC Automation](qc-automation.md)** (một phần của guide Tester / QA này).
 
-> **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).
+> **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.
 
 ---
 
-*Xem thêm:* [Developer Guide](../developer/README.md) · [QC Automation Guide](../qc-automation.md) · [Operations › Bug Flow](../../04-operations/bug-flow.md) · [Reference › Commands](../../05-reference/commands.md)
+*Xem thêm:* [Developer Guide](../developer/README.md) · [Chương QC Automation](qc-automation.md) · [Operations › Bug Flow](../../04-operations/bug-flow.md) · [Reference › Commands](../../05-reference/commands.md)

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

@@ -78,7 +78,7 @@ Severity : Major
 
 Spec context:
   PRD      : specs/prd/auth/FT-001-login.md (v1.0)
-  BDD      : free-trial-be/specs/bdd/auth/FT-001-login.feature
+  BDD      : free-trial-specs/specs/bdd/auth/system/FT-001-login.feature
              → Scenario: "Lock account after 5 failed attempts"
   Tech Doc : free-trial-specs/specs/tech-docs/auth/FT-001-auth-api.md
 

package/docs/02-guides/{qc-automation.md → tester/qc-automation.md}

@@ -1,7 +1,9 @@
-[📚 Docs](../README.md) › [Guides](README.md) › QC Automation
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Tester](README.md) › QC Automation
 
 # Hướng Dẫn QC Automation — Spec-Driven Dev
 
+> Đây là **một chương của [guide Tester / QA](README.md)** — QC và Tester là **cùng một role**. Chương này đi sâu vào pipeline QC tự động (`/qc-*`); phần vai trò chung, spec-manifest, `/report-bug`, `/propose-scenario`… ở [README của guide](README.md).
+
 Pipeline QC automation **chính thức** của framework — được port từ agent của team QC (reference repo `ai-automation-qc-base`) vào ngay trong framework. Nó sinh và chạy automation **Playwright/pytest** từ BDD `.feature` chính thức, rồi ghi tín hiệu **`qc_status`** (authoritative) vào trace TSV → Living Docs.
 
 ## Mục Lục
@@ -59,6 +61,12 @@ này độc lập với module implementation của dev (java-spring, react, flu
 Per-layer guides chi tiết nằm trong `skills/qc/<stage>/` (port từ skills của agent QC):
 functional / integration / e2e / non-functional / exploratory.
 
+### Test-ID contract — locate element không cần scan
+
+Để QC **không** phải dò/giả lập vị trí element lúc runtime (chậm), FE tech-design có section **§2b Test Selectors**: mỗi element **có action** được gán test-id ổn định (`{uc}-{screen}-{element}-{type}`, vd `ft001-login-submit-btn`). `/generate-code` emit đúng id đó theo attribute platform (web `data-testid` · RN `testID` · Flutter `Key`/`Semantics` · iOS `accessibilityIdentifier`); `/qc-design-test` cite test-id trong step; `/qc-run-test` build Page Object locator **thẳng từ map** (ưu tiên trong locator priority `data-testid → role → …`). Element có action mà chưa có test-id trong §2b → QC **fallback** role/text (chậm hơn) và nên bổ sung vào tech-design. Xem [Trace Schema](../../05-reference/trace-schema.md) và FE tech-design (`/generate-tech-docs`).
+
+> **Component reuse / code có sẵn:** `/generate-tech-docs` + `/generate-code` chỉ gán id cho code **mới**. Với component dùng chung (id ở usage site, component phải *forward* test-id) hoặc màn hình **brownfield** đã viết tay → chạy **`/map-testids {UC-ID}`**: reverse-document id đang có, gán id còn thiếu, patch forwarding + ghi vào `figma-components/{module}.md` (section *Test-ID Forwarding*), điền §2b. Nhờ vậy QC vẫn locate-by-id không cần scan.
+
 ## Trace Join: qc_status Đến Living Docs Như Thế Nào
 
 1. `.feature` chính thức định nghĩa scenario là `@trace.scenario={UC-ID}-SC{N}`.
@@ -117,7 +125,7 @@ ghi `feedback/bdd-proposals/`. PO/Dev thấy khi `/sync`, rồi BUG_FLOW định
 
 > 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).
+> 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
 
@@ -151,7 +159,7 @@ không nuốt mất skill đang hoàn thiện, và QC update skill 1 chỗ (repo
 
 ## Xem Thêm
 
-- [Guide › Tester](tester/README.md) — vai trò tester, spec-manifest, `/report-bug`, `/propose-scenario`
-- [Concepts › Traceability](../03-concepts/traceability.md) — trace TSV, dev_selftest vs qc_status
-- [Reference › Modules](../05-reference/modules.md) — chi tiết module `qc-playwright`
-- [Reference › Commands](../05-reference/commands.md) — danh mục đầy đủ mọi command
+- [Guide › Tester](README.md) — vai trò tester, spec-manifest, `/report-bug`, `/propose-scenario`
+- [Concepts › Traceability](../../03-concepts/traceability.md) — trace TSV, dev_selftest vs qc_status
+- [Reference › Modules](../../05-reference/modules.md) — chi tiết module `qc-playwright`
+- [Reference › Commands](../../05-reference/commands.md) — danh mục đầy đủ mọi command

package/docs/02-guides/tester/reading-specs.md

@@ -20,8 +20,8 @@ Sau khi chạy `/generate-spec-manifest`, tra manifest để lấy paths:
 FT-001:
   prd:          "my-project-specs/specs/prd/auth/FT-001-login.md"
   bdd:
-    be:   "free-trial-be/specs/bdd/auth/system/FT-001-UC1-login-system.feature"
-    web:  "free-trial-web/specs/bdd/auth/web/FT-001-UC1-login-web.feature"
+    be:   "my-project-specs/specs/bdd/auth/system/FT-001-UC1-login-system.feature"
+    web:  "my-project-specs/specs/bdd/auth/web/FT-001-UC1-login-web.feature"
   tech_docs:
     be:   "my-project-specs/specs/tech-docs/auth/FT-001-auth-api.md"
 ```
@@ -37,8 +37,8 @@ AC3: Sai password 5 lần liên tiếp → khoá tài khoản 30 phút
 AC4: Tài khoản bị khoá → thông báo thời gian mở khoá
 ```
 
-**Bước 2: Đọc BDD System (cho BE)** tại `free-trial-be/specs/bdd/auth/system/FT-001-UC1-login-system.feature`
-*(nằm trong service submodule của BE — PO gen, chứa contract BE phải đáp ứng)*
+**Bước 2: Đọc BDD System (cho BE)** tại `my-project-specs/specs/bdd/auth/system/FT-001-UC1-login-system.feature`
+*(nằm trong spec submodule — PO gen, chứa contract BE phải đáp ứng; tất cả BDD web/app/system đều ở spec repo)*
 
 ```gherkin
 Scenario: Successful login

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

@@ -18,8 +18,8 @@ git pull && git submodule update --remote --recursive
 #   status: approved  ← ✅ có thể test
 #   prd: "specs/prd/payment/FT-042-checkout.md"
 #   bdd:
-#     be:  "free-trial-be/specs/bdd/payment/system/FT-042-UC1-checkout-system.feature"
-#     web: "free-trial-web/specs/bdd/payment/web/FT-042-UC1-checkout-web.feature"
+#     be:  "free-trial-specs/specs/bdd/payment/system/FT-042-UC1-checkout-system.feature"
+#     web: "free-trial-specs/specs/bdd/payment/web/FT-042-UC1-checkout-web.feature"
 ```
 
 **Test plan từ BDD BE (7 scenarios):**
@@ -156,9 +156,9 @@ FT-042:
   domain: payment
   status: approved
   bdd:
-    be:  "free-trial-be/specs/bdd/payment/system/FT-042-UC1-checkout-system.feature"
-    web: "free-trial-web/specs/bdd/payment/web/FT-042-UC1-checkout-web.feature"
-    app: "free-trial-app/specs/bdd/payment/app/FT-042-UC1-checkout-app.feature"
+    be:  "free-trial-specs/specs/bdd/payment/system/FT-042-UC1-checkout-system.feature"
+    web: "free-trial-specs/specs/bdd/payment/web/FT-042-UC1-checkout-web.feature"
+    app: "free-trial-specs/specs/bdd/payment/app/FT-042-UC1-checkout-app.feature"
 ```
 
 **Test strategy:**

package/docs/02-guides/tester/spec-manifest.md

@@ -4,18 +4,23 @@
 
 ## Spec-Manifest Là Gì Và Tại Sao Cần
 
-Trong umbrella repo, spec files nằm rải rác ở nhiều submodule:
+Trong umbrella repo (có `spec_source`), **mọi spec đều nằm trong spec submodule** — nhưng rải ở nhiều thư mục (`prd/`, `bdd/{platform}/`, `tech-docs/`) và nhiều domain:
 
 ```
-free-trial-spec/
-├── specs/prd/auth/FT-001-login.md         ← PRD (spec submodule)
-├── specs/product-definition/auth/...      ← PDD
-├── free-trial-be/specs/bdd/...            ← BDD của BE
-├── free-trial-web/specs/bdd/...              ← BDD của Web
-└── free-trial-app/specs/bdd/...           ← BDD của App
+free-trial-umbrella/                         ← umbrella (Claude Code mở ở đây)
+├── free-trial-specs/                        ← SPEC submodule — TẤT CẢ spec ở đây
+│   └── specs/
+│       ├── prd/auth/FT-001-login.md         ← PRD
+│       ├── design-spec/auth/...             ← Design Spec
+│       ├── bdd/auth/system/...              ← BDD System (BE)
+│       ├── bdd/auth/web/...                 ← BDD Web (FE)
+│       ├── bdd/auth/app/...                 ← BDD App
+│       └── tech-docs/auth/...               ← Tech Docs (BE contract + FE design)
+├── free-trial-be/    (chỉ code)             ← SERVICE submodule
+└── free-trial-web/   (chỉ code)             ← SERVICE submodule
 ```
 
-Tester's agent không biết layout này → cần một **index file** để tra cứu.
+Tester's agent không biết domain nào / file nào ứng với TICKET-ID → cần một **index file** để tra cứu. *(Chỉ khi KHÔNG có `spec_source` thì BDD mới rải theo từng service submodule.)*
 
 `spec-manifest.yaml` là file được gen tự động, ánh xạ TICKET-ID → tất cả file liên quan:
 
@@ -30,8 +35,8 @@ features:
       be:  "free-trial-specs/specs/tech-docs/auth/FT-001-UC1-auth-api.md"
       web: "free-trial-specs/specs/tech-docs/auth/FT-001-UC1-login-web.md"
     bdd:
-      be:  "free-trial-be/specs/bdd/auth/system/FT-001-UC1-login-system.feature"
-      web: "free-trial-web/specs/bdd/auth/web/FT-001-UC1-login-web.feature"
+      be:  "free-trial-specs/specs/bdd/auth/system/FT-001-UC1-login-system.feature"
+      web: "free-trial-specs/specs/bdd/auth/web/FT-001-UC1-login-web.feature"
 ```
 
 **Quan trọng:**
@@ -94,7 +99,7 @@ Khi làm việc với umbrella repo, VS Code Living Docs panel cần được đ
 # Chạy sau mỗi codegen session — hoặc khi cần refresh trạng thái coverage
 /sync            # hoặc /validate-traces
 
-# → Đọc TSVs từ: user-service/.trace/, order-service/.trace/, ...
+# → Đọc TSVs từ MỘT chỗ: {spec_source}/.trace/  (mỗi scenario mang @trace.service)
 # → Ghi canonical: {spec_source}/.living-docs/trace-report.json (+ TSV mirror)
 # → Ghi panel mirror: ./.trace  (workspace hiện tại — panel luôn có data)
 # → Panel cập nhật ngay sau khi lệnh hoàn tất
@@ -117,7 +122,7 @@ Panel hiển thị trạng thái cross-service:
 >
 > **`qc_status`:** kết quả pipeline QC chính thức (`/qc-run-test`). Dashboard hiển thị hai cột cạnh nhau để phân biệt rõ hai luồng.
 
-> **Prerequisite:** Mỗi service submodule cần `.agent/project-context.yaml` với `paths.trace_dir`. Nếu thiếu → panel trống → báo Dev team.
+> **Prerequisite:** umbrella cần `setup.spec_source` trỏ đúng spec submodule → trace TSV authoritative dồn về `{spec_source}/.trace/`. Nếu thiếu → panel trống → báo Dev team. (Chỉ chế độ không có `spec_source` mới cần `paths.trace_dir` per-service.)
 
 ---
 

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/)
         │
@@ -48,24 +49,20 @@ Chạy QC automation pipeline (6 bước — ghi kết quả chính thức vào
         ├─ /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,10 +56,11 @@ 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/,
@@ -219,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
 
@@ -184,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:
 
@@ -111,21 +111,21 @@ Living Docs (VS Code panel) đọc trace TSV và hiển thị traceability healt
 
 | 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.)
 
 ---
 
@@ -135,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,10 +1,10 @@
 [📚 Docs](../README.md) › [Operations](README.md) › Bug Flow
 
-# Bug Flow — PO · Dev · Tester · QC
+# Bug Flow — PO · Dev · QC/Tester
 
-> 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.
+> 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: [Guide · QC Automation](../02-guides/qc-automation.md#khi-qc-tìm-thấy-bug--spec-gap--đẩy-lên-specs).
+> **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).
 
 ---
 
@@ -359,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).