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

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

@@ -2,12 +2,46 @@
 
 # Workflow Cơ Bản
 
+> Sơ đồ render thành flowchart trên GitHub (Mermaid). Bản text ASCII (mở mục bên dưới) là fallback cho viewer không hỗ trợ Mermaid.
+
+```mermaid
+flowchart TD
+    A([Nhận PRD + BDD mới từ PO]) --> B["/sync<br/>kéo specs + services · refresh Living Docs"]
+    B --> C["/review-context {prd}<br/>kiểm tra domain · status=approved<br/>đọc AC / UC / BR + BDD"]
+    C --> D["Đọc BDD web/app/system từ spec repo<br/>(dev KHÔNG tự generate BDD)"]
+    D --> TD
+
+    subgraph TD["TECH DESIGN + CODE — BE và FE làm SONG SONG"]
+      direction LR
+      subgraph BE["BE track (system) — làm trước để có contract"]
+        direction TB
+        BE1["/generate-tech-docs {system}<br/>API contract ← System BDD<br/>endpoint · data model · DB"] --> BE2["/review-tech-docs → approved<br/>chốt = BE contract<br/>(FE chờ cái này)"] --> BE3["/generate-code {system}<br/>code BE ← System BDD + contract"]
+      end
+      subgraph FE["FE/App track (web · app) — không chờ BE deploy"]
+        direction TB
+        FE1["① /generate-code {bdd} --phase=ui<br/>UI ← Web/App BDD + Design Spec<br/>mock ← BE contract (nếu có) · else System BDD<br/>emit test-id · Tester test ngay"] --> GATE{{"GATE — chỉ làm tiếp khi ĐÃ CÓ:<br/>System BDD + BE contract (approved)"}}
+        GATE --> FE2["② /generate-tech-docs {web|app}<br/>FE design ← Web/App BDD + BE contract<br/>§4 map API · §2b test-id"] --> FE2b["/review-tech-docs → approved<br/>(bump revision)"] --> FE3["③ /generate-code --phase=integration<br/>thay mock bằng API thật theo §4"]
+      end
+      BE2 -. "cấp BE contract" .-> GATE
+    end
+
+    TD --> E["/dev-gen-test → /dev-run-test<br/>dev tự kiểm (dev_selftest)<br/>ghi vào spec .trace"]
+    E --> F["/validate-traces<br/>cập nhật Living Docs (.living-docs)"]
+    F --> G["/review-code — 4 lens:<br/>Security · Performance · Architecture · Test"]
+    G --> H([Tạo PR → notify PO/SA review])
+```
+
+> **Full-stack / không tách mock:** chỉ cần BE track — chạy `/generate-code {bdd}` một lần (bỏ qua FE 2-phase).
+
+<details>
+<summary>Bản text (ASCII fallback — cho viewer không render Mermaid)</summary>
+
 ```
 Nhận thông báo PRD + BDD mới từ PO
         │
         ▼
-git submodule update --remote my-project-specs
-(lấy spec mới nhất, bao gồm cả BDD đã được PO gen)
+/sync                                          # pull specs + services + refresh Living Docs (1 lệnh, preferred)
+(tương đương raw: git submodule update --remote my-project-specs — lấy spec mới nhất, gồm BDD PO đã gen)
         │
         ▼
 /review-context {prd-file}
@@ -23,27 +57,44 @@ App:     my-project-specs/specs/bdd/{domain}/app/{TICKET-ID}-UC*.feature
 BE:      my-project-specs/specs/bdd/{domain}/system/{TICKET-ID}-UC*.feature
         │
         ▼
-/generate-tech-docs {prd-file}
-→ Gen API spec, DB schema, sequence diagram dựa trên BDD
-→ /review-tech-docs để verify chất lượng
-        │
-        ▼
-# BE (hoặc full-stack không cần mock split):
-/generate-code {bdd-file}
-→ Gen code skeleton theo BDD + tech docs
-→ Đảm bảo @trace.bdd comment trong code
-
-# FE/App (2 phases — không cần chờ BE):
-/generate-code {bdd-file} --phase=ui          # Phase 1: UI + mock adapter
-→ Tester test FE ngay (không cần BE ready)
-/generate-code {bdd-file} --phase=integration # Phase 2: sau khi sign-off done
-→ Wire real API thay thế mock
+══════════ TECH DESIGN + CODE — BE track & FE track CHẠY SONG SONG ══════════
+(/generate-tech-docs là platform-aware: đọc @trace.platform → BE = API contract · FE/App = client design)
+
+BE track (system)   ── làm trước, sinh ra "BE contract" ──
+  /generate-tech-docs {system}   → API contract: endpoints · data model · DB · caching
+  /review-tech-docs → APPROVED   → đây CHÍNH LÀ "BE contract" mà FE chờ
+  /generate-code {system}        → code theo BDD (@trace.bdd)
+  (full-stack / không tách mock: chỉ cần track này — /generate-code {bdd} một lần)
+
+
+FE/App track (web|app)   ── KHÔNG chặn chờ BE ──
+
+  ① BẮT ĐẦU NGAY (song song với BE):
+     /generate-code {bdd} --phase=ui      → UI + mock adapter
+        • UI ← Web/App BDD + Design Spec
+        • mock shape = BE contract nếu có, else System BDD (+warn)
+        • fixture values: LUÔN từ System BDD
+        • emit test-id (convention {uc}-{screen}-{element}-{type})
+        • Tester test FE NGAY (không cần BE deploy API)
+                            │
+        ╔═══════════════════▼═══════════ GATE ═══════════════════
+        ║  Chỉ mở khi CÓ:  System BDD  +  BE contract (approved, từ track BE)
+        ╚═══════════════════╤════════════════════════════════════
+                            ▼
+     ② /generate-tech-docs {web|app}      → FE client design (GATED)
+          • components · state
+          • §4 API-integration map THEO BE contract
+          • §2b Test Selectors (test-id cho element có action)
+        /review-tech-docs → approved (bump revision)
+                            ▼
+     ③ /generate-code {bdd} --phase=integration
+          → wire real API theo §4 FE tech-design (thay mock)
         │
         ▼
 /dev-gen-test {bdd-file}
 → Gen unit test (dev self-check, không phải coverage chính thức)
-→ /dev-run-test để verify → ghi dev_selftest (pass/fail) + dev_selftest_at vào trace TSV
-→ /validate-traces (hoặc /sync) để push trace lên spec-module Living Docs ({spec_source}/.living-docs/)
+→ /dev-run-test để verify → ghi dev_selftest (pass/fail) + dev_selftest_at vào TSV authoritative {spec_source}/.trace (commit 1 tầng ở spec repo)
+→ /validate-traces (hoặc /sync) → regenerate report Living Docs {spec_source}/.living-docs/ (gitignored)
         │
         ▼
 /review-code {files}
@@ -54,6 +105,17 @@ BE:      my-project-specs/specs/bdd/{domain}/system/{TICKET-ID}-UC*.feature
 Tạo PR → notify PO/SA review
 ```
 
+</details>
+
+> **Vì sao đúng thứ tự này? — Chuỗi outside-in.** Toàn bộ pipeline đi từ ngoài (client) vào trong (hệ thống):
+> 1. **PO gen BDD: web → app → System** — System BDD (BE) được **tổng hợp từ web+app BDD** (hành vi client định nghĩa trước, BE/system suy ra để phục vụ các flow đó). *(Project chỉ-BE: System BDD gen thẳng từ PRD.)*
+> 2. **BE tech-docs trước** — API contract dẫn xuất từ **System BDD**.
+> 3. **FE/App tech-docs sau (GATED)** — cần **System BDD + BE contract approved**; §4 map theo BE contract.
+>
+> FE **không** bị chặn chờ BE nhờ `--phase=ui` (mock shape: BE contract nếu có, else System BDD), rồi `--phase=integration` wire API thật khi contract đã có. Chi tiết flow: [Concepts › Pipeline](../../03-concepts/pipeline.md).
+
+> **Commit ở đâu, push mấy tầng?** Code nằm trong service submodule → **commit 2 tầng** (service rồi umbrella pointer). Tech-docs + `.trace/` (dev_selftest/qc_status) đẩy lên **spec repo** (1 tầng, cross-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/product-owner/README.md

@@ -9,7 +9,7 @@ Tài liệu dành cho **Product Owner (PO)** và **Business Analyst (BA)** — v
 | Trang | Nội dung |
 |---|---|
 | [Commands](commands.md) | Bảng lệnh cho PO/BA · project lessons · xử lý feedback tester |
-| [Tình huống thực tế](scenarios.md) | 11 scenario: tính năng mới, design spec, BDD, PRD thay đổi, conflict, brownfield, ... |
+| [Tình huống thực tế](scenarios.md) | 12 scenario: tính năng mới, design spec, BDD, PRD thay đổi, brownfield, **System BDD synthesis & cross-platform conflict**, ... |
 | [Quy tắc viết PRD](prd-writing-rules.md) | Platform-agnostic · testable AC · negative path · BR numbering |
 | [Checklist handoff](handoff-checklist.md) | Checklist verify trước khi thông báo dev team bắt đầu |
 
@@ -34,7 +34,7 @@ PO/BA                     Dev team
 - Đảm bảo PRD platform-agnostic (không chứa UI details hay API specs)
 - Đặt `@trace.domain` đúng để dev team routing hoạt động
 - Cập nhật `@trace.status: approved` trước khi handoff
-- **Generate BDD cho tất cả platforms** (web, app, system) trong spec repo
+- **Generate BDD cho tất cả platforms** theo thứ tự **outside-in: web → app → system** — System BDD được **tổng hợp từ web+app BDD** (project chỉ-BE thì system gen thẳng từ PRD). Xem [scenarios](scenarios.md).
 - Thông báo dev team khi có PRD hoặc BDD mới/update
 
 **PO/BA KHÔNG cần quan tâm:**
@@ -51,7 +51,7 @@ PRD (WHAT + WHY)  →  BDD (HOW verified)  →  Code (HOW built)
    spec repo          spec repo             dev repo
 ```
 
-> **Sau khi BDD approved → QC chạy pipeline tự động:** Khi BDD của một UC được approve, QC team chạy bộ lệnh native `/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report` — đọc official `.feature`, generate + run Playwright/pytest, rồi ghi `qc_status` (official QC coverage) vào Living Docs. PO không chạy QC, nhưng nên biết bước này tồn tại ở downstream. Chi tiết: [QC Automation Guide](../qc-automation.md).
+> **Sau khi BDD approved → QC chạy pipeline tự động:** Khi BDD của một UC được approve, QC team chạy bộ lệnh native `/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report` — đọc official `.feature`, generate + run Playwright/pytest, rồi ghi `qc_status` (official QC coverage) vào Living Docs. PO không chạy QC, nhưng nên biết bước này tồn tại ở downstream. Chi tiết: [chương QC Automation](../tester/qc-automation.md).
 
 **3 lý do chính BDD thuộc PO:**
 
@@ -70,8 +70,10 @@ PRD (WHAT + WHY)  →  BDD (HOW verified)  →  Code (HOW built)
 - App BDD: "App expects user profile sau khi đăng nhập"
 - System BDD: "BE phải trả `{ token, user_profile }` để thỏa mãn cả 2 platform"
 
+> Khi web & app **kỳ vọng response khác nhau**, `/generate-bdd → system` dừng tại **CHECKPOINT** để PO chốt cách giải quyết (union / platform-hint / separate-endpoints) — quyết định ghi vào `@system.resolution:`. Quy trình + ví dụ đầy đủ: [scenarios › Tình huống 12](scenarios.md#tình-huống-12--system-bdd-synthesis-outside-in--xử-lý-cross-platform-conflict).
+
 > Xem [Concepts › Traceability](../../03-concepts/traceability.md) để hiểu trace chain PRD → BDD → Code.
 
 ---
 
-*Xem thêm:* [Developer Guide](../developer/README.md) · [Tester Guide](../tester/README.md) · [QC Automation Guide](../qc-automation.md) · [Reference › Commands](../../05-reference/commands.md)
+*Xem thêm:* [Developer Guide](../developer/README.md) · [Tester Guide](../tester/README.md) · [chương QC Automation](../tester/qc-automation.md) · [Reference › Commands](../../05-reference/commands.md)

package/docs/02-guides/product-owner/commands.md

@@ -12,7 +12,7 @@
 | `/review-context --fix` | Auto-fix các lỗi nhỏ trong PRD | Khi có nhiều lỗi minor tự sửa được |
 | `/review-context --resume` | Apply các fix sau Review Board | Sau khi review findings |
 | `/generate-design-spec` | Tạo Design Spec cho FE/App (cần Figma link node-level `?node-id=` cho từng screen) | Sau khi PRD approved, trước khi generate BDD |
-| `/generate-bdd` | Tạo BDD cho web / app / system | Sau khi PRD + Design Spec approved |
+| `/generate-bdd` | Tạo BDD theo thứ tự **outside-in: web → app → system** (System BDD tổng hợp từ web+app; chỉ-BE → system gen thẳng từ PRD) | Sau khi PRD + Design Spec approved |
 | `/learn {text}` | Ghi lại lỗi AI hay lặp khi gen PRD/BDD thành guardrail | Khi AI lặp lại cùng kiểu sai trong PRD/BDD |
 
 > Danh mục đầy đủ mọi command: [Reference › Commands](../../05-reference/commands.md).

package/docs/02-guides/product-owner/scenarios.md

@@ -29,6 +29,9 @@ Output: `specs/prd/auth/FEAT-01-login-prd.md`
 Agent fan-out 4 lens (QA/DEV/SA/PO) chạy song song, rồi chạy completeness-critic loop cho đến khi một vòng không tìm ra finding mới, cuối cùng dedup + resolve conflict. Findings đầy đủ trong 1 lần chạy.
 
 Mở findings file, xem xét từng finding: `accepted` → apply · `modified` → viết note · `rejected` → bỏ qua.
+
+> **Finding khó hiểu? Bấm 💬 Giải thích.** Nếu một finding mô tả nặng tính kỹ thuật, dùng nút **💬 Giải thích** trên Review Board (extension Spec Driven Dev). Claude sẽ giải thích lại bằng ngôn ngữ no-tech + đề xuất phương án cụ thể (cover cả edge case) ngay trong terminal, và **chờ bạn confirm trước khi apply** vào PRD — tránh refine nhiều vòng. Prompt sửa được qua setting `reviewBoard.clarifyPrompt` (không cần cài lại extension).
+
 ```
 /review-context --resume specs/prd/auth/FEAT-01-login-prd.md
 ```
@@ -63,7 +66,7 @@ Agent hỏi: **"Platform? (1) web  (2) app  (3) system"**
 - Chạy lại, chọn `app` → `specs/bdd/auth/app/FEAT-01-UC1-login-app.feature`
 - Chạy lại, chọn `system` → Agent tổng hợp từ web+app BDDs → `specs/bdd/auth/system/FEAT-01-UC1-login-system.feature`
 
-> Nếu project chỉ có web → chỉ cần gen `web` rồi `system`.
+> Nếu project chỉ có web → chỉ cần gen `web` rồi `system`. Nếu web & app kỳ vọng response khác nhau → agent dừng tại CHECKPOINT để PO chốt resolution (xem [Tình huống 12](#tình-huống-12--system-bdd-synthesis-outside-in--xử-lý-cross-platform-conflict)).
 
 **Bước 8 — Push và thông báo:**
 ```bash
@@ -354,4 +357,80 @@ Chạy ở mode **Reverse-document**: mô tả lại API đã tồn tại, ghi c
 
 ---
 
+## Tình huống 12 — System BDD synthesis: outside-in & xử lý cross-platform conflict
+
+**Bối cảnh:** Đã có Web BDD + App BDD cho FEAT-01. Khi gen System BDD, `/generate-bdd → system` **không viết mới từ PRD** mà **tổng hợp ngược** từ Web + App BDD (outside-in) — vì BE/system tồn tại để phục vụ các flow client.
+
+**4 mode tự nhận diện** (theo BDD client đang có):
+
+| Có sẵn | Mode | System BDD lấy từ |
+|---|---|---|
+| web + app | **Multi-platform** | tổng hợp cả hai (+ conflict check) |
+| chỉ web | **Web-only** | chỉ web |
+| chỉ app | **App-only** | chỉ app |
+| không có web/app | **Backend-only** | gen thẳng từ PRD (business-event language) |
+| PRD có `API Source: existing` | **Brownfield** | dùng contract có sẵn trong PRD (xem [Tình huống 11](#tình-huống-11--brownfield-api-đã-tồn-tại-trên-hệ-thống-cũ)) |
+
+### Ví dụ multi-platform CÓ conflict
+
+Web và App kỳ vọng response **khác nhau**:
+```gherkin
+# web/FEAT-01-UC1-login-web.feature
+Then user sees dashboard          # → cần { token, redirect_url }
+
+# app/FEAT-01-UC1-login-app.feature
+Then app navigates to HomeScreen  # → cần { token, user_profile }
+```
+
+Chạy `/generate-bdd → system` → agent phát hiện **response shape mismatch** → dừng tại CHECKPOINT (bắt buộc, không skip được):
+
+```
+⚠️  CROSS-PLATFORM CONTRACT CONFLICT
+Conflict 1: Response shape mismatch
+  Web (Then sees dashboard)       → { token, redirect_url }
+  App (Then navigates HomeScreen) → { token, user_profile }
+
+Resolution:
+  A — Union: BE trả { token, redirect_url, user_profile }; client bỏ field không dùng (đơn giản, hơi thừa)
+  B — Platform hint: client gửi header X-Platform: web|app, BE tailor response (gọn, BE phức tạp hơn)
+  C — Separate endpoints: POST /auth/login/web · /auth/login/app (linh hoạt nhất, nhiều endpoint)
+  D — Custom: tự mô tả
+```
+
+**4 loại conflict agent bắt:**
+
+| Loại | Ví dụ |
+|---|---|
+| Response shape mismatch | web `{ token, redirect_url }` vs app `{ token, user_profile }` |
+| Error semantics mismatch | web HTTP 423 vs app error code `ACC_LOCKED` |
+| Business rule contradiction | web "khoá sau 5 lần" vs app "khoá sau 3 lần" |
+| Data field conflict | web `expires_in: seconds` vs app `expires_at: ISO timestamp` |
+
+### PO chọn resolution → ghi vào System BDD
+
+Chọn **A (Union)** → System BDD được gen kèm annotation:
+```gherkin
+# system/FEAT-01-UC1-login-system.feature
+# @trace.platform: system
+# @system.resolution: union — clients receive all fields
+Scenario: Successful login returns token, redirect and profile
+  When the system receives a login request
+  Then the system returns { token, redirect_url, user_profile }
+  And the session is valid for 3600 seconds
+```
+- **B (platform-hint)** → `Scenario Outline` + Examples cho web/app variant; annotation `platform-hint`.
+- **C (separate endpoints)** → Scenario riêng mỗi endpoint; annotation ghi rõ split.
+
+Mỗi quyết định được lưu thành `# @system.resolution:` trong file system BDD — để BE dev build contract đúng kiểu đã chốt.
+
+### Bàn giao xuống BE & xử lý thay đổi
+
+- BE dev đọc `@system.resolution:` → build API contract theo đúng kiểu (union / platform-hint / separate-endpoints) trong `/generate-tech-docs`. **Không tự đổi** — nếu thấy bất hợp lý → phản hồi PO (đây là quyết định contract, không phải implementation).
+- **Web/App BDD đổi về sau** → re-gen System BDD (`/generate-bdd → system`) để tổng hợp lại; phát sinh conflict mới → CHECKPOINT lại.
+- **FE cần field mà BE contract chưa có** → là **contract gap**: QC/Dev `/report-bug` hoặc `/propose-scenario` → PO bổ sung vào Web/App BDD → re-synthesize System BDD → BE cập nhật contract. Vòng feedback: [Bug Flow](../../04-operations/bug-flow.md).
+
+> **Tóm tắt outside-in:** Web/App BDD (client trước) → System BDD (tổng hợp, chốt conflict) → BE tech-docs (contract) → FE/App tech-docs (GATED: cần System BDD + BE contract). Chuỗi đầy đủ: [Developer › Workflow](../developer/workflow.md) · [Concepts › Pipeline](../../03-concepts/pipeline.md).
+
+---
+
 ← [Commands](commands.md) · Tiếp theo: [Quy tắc viết PRD](prd-writing-rules.md)

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,10 +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).
 
 > **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

@@ -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.
 
@@ -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/tester/qc-automation.md

@@ -0,0 +1,165 @@
+[📚 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
+
+- [Hai luồng test: dev self-check vs QC chính thức](#hai-luồng-test-dev-self-check-vs-qc-chính-thức)
+- [Pipeline 6 bước](#pipeline-6-bước)
+- [Stack — module qc-playwright](#stack--module-qc-playwright)
+- [Trace join: qc_status đến Living Docs như thế nào](#trace-join-qc_status-đến-living-docs-như-thế-nào)
+- [Entry point](#entry-point)
+- [Skills theo layer](#skills-theo-layer)
+
+## Hai Luồng Test: Dev Self-Check vs QC Chính Thức
+
+Pipeline QC này **khác** với developer **self-check** (`/dev-gen-test`, `/dev-run-test`, `/dev-smoke-test`):
+
+| Signal | Owner | Command | Ý nghĩa |
+|--------|-------|---------|---------|
+| `dev_selftest` | Dev | `/dev-run-test` | smoke check của riêng dev (KHÔNG authoritative) |
+| `qc_status` | QC | `/qc-run-test` | kết quả QC automation **chính thức** |
+
+Cả hai hiển thị **cạnh nhau** trong Living Docs; không cái nào ghi đè cái nào. `dev_selftest: pass` chỉ nghĩa "dev đã tự smoke qua"; coverage chính thức nằm ở `qc_status`.
+
+## Pipeline 6 Bước
+
+```
+/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report
+ (requirement   (risk/plan   (test-case      (review     (gen+run     (report +
+  breakdown)     + Q-for-dev)  .Test.md)       gate)       Python →     evidence)
+                                                            qc_status)
+```
+
+| Command | Vai trò | Output |
+|---------|---------|--------|
+| `/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`
+(`.agent/modules/qc-playwright/stack-profile.yaml`): **Python + pytest-playwright + Page
+Object** (slim `BasePage`, 3-layer), **Playwright Trace + pytest-html** (KHÔNG Allure). Stack
+này độc lập với module implementation của dev (java-spring, react, flutter, …).
+
+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}`.
+2. `/qc-design-test` ghi SC mà test case thuộc về; `/qc-run-test` tag mỗi pytest test
+   `# @trace.verifies={UC-ID}-SC{N}`.
+3. `/qc-run-test` ghi `qc_status` (`pass|fail|skip|not_run`) + `qc_run_at` vào trace TSV của
+   service (authoritative), rồi refresh panel mirror local.
+4. `/validate-traces` (hoặc `/sync`) tổng hợp các TSV thành report Living Docs tại
+   `{spec_source}/.living-docs/` — dashboard hiển thị `qc_status` cạnh `dev_selftest`.
+
+## Entry Point
+
+Pipeline QC bắt đầu ngay khi BDD của một UC được approved (`/review-context (BDD)` APPROVED):
+
+```
+/qc-analyze {UC-ID}   →  … → /qc-report {UC-ID}  →  /validate-traces {UC-ID}
+```
+
+## Skills Theo Layer
+
+Các skill chi tiết theo từng giai đoạn QC nằm trong `skills/qc/`:
+
+| Stage skill | Vai trò |
+|---|---|
+| `qa-analyst` | phân tích requirement, sinh `DOC_GAPS` |
+| `qa-planner` | test plan, risk, questions-for-dev |
+| `qa-designer` | thiết kế test case `.Test.md` theo layer (functional / integration / e2e / non-functional / exploratory) |
+| `qa-reviewer` | cổng review test case và script |
+| `qa-runner` | sinh + chạy Python pytest-playwright, sinh report (Playwright Trace + pytest-html) |
+
+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](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.)
 
 ---