@edupia-tutor/spec-driven-docs 0.14.0

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

@@ -0,0 +1,460 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Developer](README.md) › Tình huống thực tế
+
+# Tình Huống Thực Tế
+
+- [1. Nhận PRD + BDD mới và bắt đầu work](#tình-huống-1-nhận-prd--bdd-mới-và-bắt-đầu-work)
+- [2. Đọc và hiểu System BDD (BE dev)](#tình-huống-2-đọc-và-hiểu-system-bdd-be-dev)
+- [3. Đọc Web/App BDD (FE/App dev)](#tình-huống-3-đọc-webapp-bdd-feapp-dev)
+- [4. PRD thay đổi mid-sprint](#tình-huống-4-prd-thay-đổi-mid-sprint)
+- [4b. Chờ API design — BE + FE/App đồng thuận](#tình-huống-4b-chờ-api-design--be--feapp-đồng-thuận)
+- [5. Nhận bug report từ Tester](#tình-huống-5-nhận-bug-report-từ-tester)
+- [6. Nhận Design Spec + BDD từ PO (FE/App)](#tình-huống-6-nhận-design-spec--bdd-từ-po-feapp)
+- [7b. Brownfield — API đã tồn tại](#tình-huống-7b-brownfield--api-đã-tồn-tại-trên-hệ-thống-cũ)
+- [7. Setup service submodule (Umbrella)](#tình-huống-7-setup-service-submodule-umbrella-mode)
+- [8. Validate traces trước khi tạo PR lớn](#tình-huống-8-validate-traces-trước-khi-tạo-pr-lớn)
+
+## Tình huống 1: Nhận PRD + BDD mới và bắt đầu work
+
+**Bối cảnh:** PO thông báo PRD `FT-042-checkout.md` và BDD đã approved, sẵn sàng implement.
+```
+1. git submodule update --remote my-project-specs
+   (lấy PRD + BDD mới nhất từ PO)
+
+2. /review-context my-project-specs/specs/payment/checkout/prd.md
+   → Kiểm tra @trace.status = approved (không code khi còn draft)
+   → Đọc kỹ AC, UC, BR
+
+3. Đọc BDD tương ứng theo platform của mình:
+   FE/Web:  my-project-specs/specs/payment/checkout/bdd/web/FT-042-UC*.feature
+   App:     my-project-specs/specs/payment/checkout/bdd/app/FT-042-UC*.feature
+   BE:      my-project-specs/specs/payment/checkout/bdd/system/FT-042-UC*.feature
+
+4. Nếu có thắc mắc về PRD hoặc BDD → hỏi PO ngay, không tự suy diễn
+   Ví dụ: "BR5 trong System BDD nói 'kiểm tra giới hạn thanh toán' — limit này
+           có khác nhau theo tier user không? BDD không chỉ rõ."
+
+5. Bắt đầu: /generate-tech-docs dựa trên BDD
+```
+**Lưu ý:** Nếu `/review-context` báo P0 warning (domain không match config) → **dừng lại**, báo PO/DevOps fix config trước.
+
+## Tình huống 2: Đọc và hiểu System BDD (BE dev)
+
+**Bối cảnh:** BE dev nhận thông báo BDD đã sẵn sàng tại `specs/auth/login/bdd/system/`.
+
+**System BDD tập trung vào:** API contracts được tổng hợp từ FE + App BDD · Business rule enforcement tại system level · Data contracts (request/response shape) · Cross-platform consistency.
+```
+# Đọc file BDD (không generate):
+my-project-specs/specs/auth/login/bdd/system/FT-001-UC1-login-system.feature
+```
+```gherkin
+# Ví dụ System BDD do PO gen (tổng hợp từ web + app BDD)
+Feature: User Authentication — System Contract
+  # @trace.prd: FT-001
+  # @trace.platform: system
+
+  Scenario: Successful login returns token and profile
+    Given a registered user with valid credentials
+    When the system receives a login request
+    Then the system returns an auth token
+    And the system returns the user profile
+    And the session is valid for 3600 seconds
+
+  Scenario: Account locked after 5 failed attempts
+    Given a user with 4 failed login attempts
+    When the system receives a 5th failed login
+    Then the system locks the account for 30 minutes
+    And the system signals the locked state with remaining time
+```
+BE dev dùng System BDD để: thiết kế API endpoint + response schema (`/generate-tech-docs`) · generate code skeleton (`/generate-code`) · viết integration tests (`/dev-gen-test`).
+
+> **Đọc annotation `@system.resolution:` ở header (nếu có).** Khi web & app kỳ vọng response khác nhau, PO đã chốt cách giải quyết lúc gen System BDD — build contract đúng kiểu đó, **đừng tự đổi**:
+> - `union` → trả tất cả field cho mọi client (`{ token, redirect_url, user_profile }`).
+> - `platform-hint` → đọc header `X-Platform: web|app`, tailor response (System BDD dùng `Scenario Outline` + Examples).
+> - `separate-endpoints` → mỗi platform một endpoint (`/auth/login/web` · `/auth/login/app`).
+>
+> Thấy resolution bất hợp lý, hoặc cần field chưa có trong contract → phản hồi PO (contract decision), đừng sửa System BDD trực tiếp. Bối cảnh: [PO › Tình huống 12](../product-owner/scenarios.md#tình-huống-12--system-bdd-synthesis-outside-in--xử-lý-cross-platform-conflict).
+
+## Tình huống 3: Đọc Web/App BDD (FE/App dev)
+
+**Bối cảnh:** FE dev nhận thông báo BDD web đã sẵn sàng tại `specs/auth/login/bdd/web/`.
+```
+# Đọc file BDD (không generate):
+my-project-specs/specs/auth/login/bdd/web/FT-001-UC1-login-web.feature
+```
+```gherkin
+# Ví dụ Web BDD do PO gen (vocabulary: clicks, sees, navigates)
+Scenario: User sees error after wrong password
+  Given user is on the Login screen
+  When user submits login with wrong password
+  Then user sees "Sai mật khẩu" error
+  And the password field is cleared
+
+Scenario: Account locked — countdown shown
+  Given user has submitted wrong password 5 times
+  Then user sees "Tài khoản bị khoá. Thử lại sau 29:45"
+  And the countdown decrements every second
+```
+FE dev dùng Web BDD để:
+1. Thiết kế component spec + API integration plan (`/generate-tech-docs`)
+2. Gen UI + mock adapter (`/generate-code --phase=ui`) — mock **shape** từ BE contract nếu có, else System BDD + warn → Mock adapter trả về fixture data đúng với BDD `Then` clauses → Tester test toàn bộ FE flow ngay, không cần chờ BE
+3. [Trong khi đó — tham gia review API contract, sign-off T7 gate]
+4. Khi sign-off done → wire real API (`/generate-code --phase=integration`)
+5. Viết E2E tests với Playwright/Cypress (`/dev-gen-test`)
+
+## Tình huống 4: PRD thay đổi mid-sprint
+
+**Bối cảnh:** PO update PRD `FT-042` từ v1.0 → v1.1 khi dev đang code.
+```
+PO notify: "FT-042 updated — BR7 thay đổi giới hạn từ 5tr → 10tr"
+        │
+        ▼
+Dev chạy:
+/review-context specs/payment/checkout/prd.md
+→ Xem diff từ v1.0 sang v1.1 (agent highlight thay đổi)
+        │
+        ▼
+Đánh giá impact:
+- BDD bị ảnh hưởng? → thông báo PO để PO update BDD trong spec repo, rồi pull lại
+- Tech Docs bị ảnh hưởng? → update API spec
+- Code bị ảnh hưởng? → update logic + tests
+        │
+        ▼
+/validate-traces
+→ Đảm bảo không có trace nào còn trỏ về spec cũ
+```
+**Nguyên tắc:** Không merge code khi traces broken. Fix traces trước.
+
+## Tình huống 4b: Chờ API design — BE + FE/App đồng thuận
+
+**Bối cảnh:** System BDD đã gen, BE dev bắt đầu `/generate-tech-docs` nhưng FE/App chưa confirm API contract. **Trạng thái tech docs trong thời gian này:** `@trace.status: in-review`.
+```
+BE dev: /generate-tech-docs auth/FT-001-UC1
+# Umbrella mode (có spec_source): output nằm trong SPEC REPO chung
+→ Output: free-trial-specs/specs/auth/login/tech-docs/FT-001-UC1-tech-design.md
+# Single-service (không có spec_source): output nằm tại project root
+→ Output: specs/auth/login/tech-docs/FT-001-UC1-tech-design.md
+→ @trace.status: draft
+→ @trace.sign_off: { be_team: done, fe_team: pending, app_team: pending, sa: pending }
+→ Publish: commit + push file lên spec repo (2-layer) để FE/App `/sync` đọc được
+
+BE dev: /review-tech-docs free-trial-specs/specs/auth/login/tech-docs/FT-001-UC1-tech-design.md
+→ Chạy T1–T7 (bao gồm T7 cross-team contract check)
+→ Report: "Sign-off gate: 🔒 BLOCKED — pending: fe_team, app_team, sa"
+```
+**FE dev review API contract:**
+```
+# FE dev mở tech-design file → xem API contract section
+# Xác nhận: response fields có đủ cho web BDD expectations không?
+# Nếu ok → thêm comment hoặc báo BE dev cập nhật sign_off
+```
+Khi FE/App confirm xong → BE dev update header:
+```yaml
+# @trace.sign_off:
+#   be_team:  done
+#   fe_team:  done    ← FE đã confirm
+#   app_team: done    ← App đã confirm
+#   sa:       done    ← SA đã approve
+```
+```
+BE dev: /review-tech-docs --resume {tech-design-file}
+→ Sign-off gate: ✅ READY
+→ @trace.status: approved
+→ BE có thể chạy /generate-code
+→ FE chạy /generate-code --phase=integration để wire API thật
+```
+```
+# FE — sau khi sign-off gate approved:
+/generate-code --phase=integration auth/FT-001-UC1
+→ Reads existing mock adapter interface ({UC-ID}ApiPort)
+→ Generates real API adapter với calls đến endpoints trong tech-doc
+→ Flips DI/env flag: service dùng real adapter thay mock
+→ Mock adapter giữ lại cho unit test
+```
+**Nguyên tắc:**
+- `/generate-code` (không phase flag) cho BE trả về warning nếu tech docs status là `in-review` hoặc `draft`.
+- FE dùng `--phase=ui` được ngay sau khi đọc BDD — không cần chờ.
+- FE dùng `--phase=integration` chỉ sau khi sign-off gate `approved`.
+
+## Tình huống 5: Nhận bug report từ Tester
+
+**Bối cảnh:** Tester gửi bug report theo đúng format spec-driven, có đầy đủ spec context.
+```
+Bug ID   : BUG-20260605-003
+Feature  : FT-001 — User Login
+Service  : BE
+Severity : Major
+
+Spec context:
+  PRD      : specs/auth/login/prd.md (v1.0)
+  BDD      : free-trial-specs/specs/auth/login/bdd/system/FT-001-login.feature
+             → Scenario: "Lock account after 5 failed attempts"
+  Tech Doc : free-trial-specs/specs/auth/login/tech-docs/FT-001-auth-api.md
+
+AC bị vi phạm:
+  AC3: "Sai password 5 lần liên tiếp → khoá tài khoản 30 phút"
+
+BDD Scenario bị fail:
+  Given : user has 0 failed attempts
+  When  : login with wrong password 5 times
+  Then  : 5th attempt returns 423 Locked AND retry_after = 1800
+
+Actual: 5th attempt trả 401, không có retry_after, tài khoản không bị khoá
+```
+
+**Bước 1 — Tìm code implement scenario bị fail:**
+```
+Đọc theo thứ tự: PRD → BDD → Code
+
+PRD AC3: "5 lần sai → khoá 30 phút"          → rõ ràng ✅
+BDD SC3: "Then 423 Locked, retry_after=1800"  → đúng theo PRD ✅
+Code: ???                                      → kiểm tra tiếp
+```
+Chạy:
+```
+/fix-bug "BUG-20260605-003: FT-001-UC2-BR3 — account not locked after 5 failures
+  PRD: specs/auth/login/prd.md
+  BDD: free-trial-specs/specs/auth/login/bdd/system/FT-001-login.feature"
+```
+Agent sẽ: đọc BDD scenario được chỉ định · tìm code implement scenario đó (theo `@trace.bdd`) · so sánh logic thực tế vs spec · propose fix có giải thích.
+
+**Bước 2 — Xác định bug thuộc layer nào:** Đọc theo thứ tự PRD → BDD → Code để tìm chỗ lệch. Có 3 khả năng:
+
+| PRD | BDD | Code | → Fix ở đâu |
+|---|---|---|---|
+| ✅ rõ | ✅ đúng | ❌ sai | Fix code |
+| ✅ rõ | ❌ sai | ❌ sai | Fix BDD + code |
+| ❌ mơ hồ | bất kỳ | bất kỳ | Hỏi PO trước, không tự fix |
+
+> Flow đầy đủ cho cả 6 cases (bao gồm PRD change, Design Spec bug, env bug) và cách phối hợp với PO/Tester: xem [Operations › Bug Flow](../../04-operations/bug-flow.md).
+
+**Bước 3 — Sau khi fix:**
+```
+/validate-traces
+→ Đảm bảo @trace.bdd trong code vẫn trỏ đúng BDD scenario
+→ Không có trace broken
+
+/dev-run-test
+→ BDD pass = fix đúng theo spec
+
+Notify tester:
+  "BUG-20260605-003 fixed — deploy to staging [link commit/PR]
+   Root cause: Case A — code dùng > thay vì >=
+   BDD: không đổi (spec đã đúng)
+   Re-test: FT-001-UC2-SC3"
+```
+
+## Tình huống 6: Nhận Design Spec + BDD từ PO (FE/App)
+
+**Bối cảnh:** PO tạo Design Spec + BDD web cho tính năng checkout — FE cần implement.
+```
+PO thông báo: "FT-042 Design Spec + BDD đã sẵn sàng"
+        │
+        ▼
+git submodule update --remote my-project-specs
+
+FE dev đọc:
+- my-project-specs/specs/payment/checkout/prd.md                   (business rules)
+- my-project-specs/specs/payment/checkout/design-spec/FT-042-*.md  (screens, components)
+- my-project-specs/specs/payment/checkout/bdd/web/FT-042-UC*.feature  (BDD đã gen sẵn)
+        │
+        ▼
+Bật Figma Dev Mode MCP (nếu dùng Figma — để FE codegen chính xác):
+→ Mở Figma DESKTOP app + enable Dev Mode MCP server (local, http://127.0.0.1:3845)
+→ `/generate-code` (FE/App UI) tự detect server local + prompt nếu chưa bật
+→ Dùng real tokens, components, Code Connect thay vì web link → codegen sát design hơn
+        │
+        ▼
+/generate-tech-docs payment/FT-042-UC1
+→ Gen component spec, API integration plan dựa trên Design Spec + BDD
+        │
+        ▼
+/generate-code payment/FT-042-UC1 --phase=ui
+→ Gen UI components + mock API adapter (fixture từ System BDD Then clauses)
+→ FE codegen đọc Figma Dev Mode MCP local nếu đang bật (tokens/components/Code Connect)
+→ Tester có thể test FE ngay
+        │  [trong khi đó: tham gia review API contract — T7 sign-off gate]
+        ▼
+[Nhận thông báo: sign-off gate approved]
+        │
+        ▼
+/generate-code payment/FT-042-UC1 --phase=integration
+→ Wire real API adapter thay thế mock
+→ /dev-gen-test payment/FT-042-UC1
+→ /review-code {files-changed}
+→ /dev-run-test
+```
+**Lưu ý:** BE không cần đọc Design Spec — chỉ đọc System BDD tại `specs/{domain}/{prd-slug}/bdd/system/`.
+
+## Tình huống 7b: Brownfield — API đã tồn tại trên hệ thống cũ
+
+**Bối cảnh:** PO viết PRD cho feature mới nhưng BE API đã có sẵn trên hệ thống cũ, chưa có tài liệu. PO khai báo luôn trong PRD thay vì thiết kế lại.
+
+**Dấu hiệu nhận ra:** PRD Metadata có `| **API Source** | existing |` · PRD có section "Existing API Contract" với bảng endpoint + response.
+
+**Dev workflow (đơn giản hơn greenfield):**
+```
+git submodule update --remote my-project-specs
+
+1. /review-context → đọc PRD + BDD
+   → BDD system đã dùng contract sẵn có từ PRD (không synthesis)
+   → @trace.api_source: existing trong BDD header
+
+2. /generate-tech-docs {feature-file}
+   → Mode: Reverse-document
+   → §2 API Endpoints: mô tả lại API đã tồn tại từ bảng PRD
+   → Ghi chú gaps nếu contract thực tế khác BDD expectations
+
+3. /review-tech-docs {tech-design-file}
+   → T7 sign-off gate: tự động SKIP (không có API design mới)
+   → Chỉ review T1–T6 (architecture, entity, BDD traceability, ...)
+   → Approved nhanh hơn
+
+4. /generate-code {feature-file}   ← không cần --phase
+   → API đã live, gen real adapter trực tiếp
+```
+
+**Điểm khác biệt so với greenfield:**
+
+| | Greenfield | Brownfield (API existing) |
+|---|---|---|
+| System BDD | Synthesize từ FE + App BDD | Dùng PRD contract trực tiếp |
+| T7 gate | Bắt buộc | Tự động skip |
+| `--phase=ui` | Cần nếu BE chưa ready | Không cần |
+| `generate-tech-docs` | Design mới | Reverse-document |
+
+## Tình huống 7: Setup service submodule (Umbrella mode)
+
+**Bối cảnh:** Project dùng umbrella repo. Dev được assign vào service `mass-product-be`.
+
+**Setup lần đầu:**
+```bash
+# 1. Clone umbrella repo
+git clone {umbrella-repo-url} mass-product
+cd mass-product
+
+# 2. Mở Claude Code TẠI umbrella root (QUAN TRỌNG)
+code .   ← hoặc claude .
+
+# 3. Chạy một lệnh duy nhất — setup toàn bộ
+/sync
+# → tự detect setup mode (submodule chưa init)
+# → git pull + git submodule update --init --recursive --remote
+# → validate service configs (cảnh báo nếu thiếu .agent/project-context.yaml)
+# → sync Living Docs panel
+
+# 4. Framework tự detect umbrella mode từ project-context.yaml
+# Khi chạy /review-context với PRD có @trace.domain: be
+# → CODE route tới mass-product-be/  ·  BDD đọc từ spec repo mass-product-spec/specs/{domain}/{prd-slug}/bdd/ (spec_source set)
+```
+
+**Update hằng ngày — cũng chỉ 1 lệnh:**
+```bash
+/sync
+# → git pull + submodule update --remote
+# → refresh Living Docs
+```
+
+**project-context.yaml của umbrella:**
+```yaml
+setup:
+  mode: umbrella
+  spec_source: "mass-product-spec"
+services:
+  be:
+    path: "mass-product-be"
+    module: "NestJS"
+    # specs_dir KHÔNG khai khi spec_source set — BDD đọc từ spec repo, không per-service
+  web:
+    path: "mass-product-web"
+    module: "NextJS"
+```
+
+> **BDD (specs_dir):** không khai trong `services` khi có `spec_source`. Tất cả BDD (web/app/system) nằm ở `{spec_source}/specs/bdd` (vd `mass-product-spec/specs/bdd`) — context-loader tự route `specs_dir` về đó; mọi `specs_dir` per-service đều bị **bỏ qua**. Per-service `specs_dir` **chỉ** dùng khi KHÔNG có `spec_source`.
+>
+> **Tech-docs (API contract):** không khai trong `services`. Khi `setup.spec_source` được set, BE tech-design (API contract) **LUÔN** nằm tại `{spec_source}/specs/tech-docs` (vd `mass-product-spec/specs/tech-docs`) — context-loader tự route `tech_docs_dir` về đó. BE generate xong → commit + push lên spec repo; FE/App đọc qua `/sync` + `/generate-code --phase=integration`. Per-service tech-docs **chỉ** khi KHÔNG có `spec_source`.
+>
+> **Bắt buộc:** Mỗi service submodule cũng cần file `.agent/project-context.yaml` riêng. Framework đọc file này (context-loader Step 1.6) để lấy đúng `test_command` và `build_command` khi `/dev-run-test` hoặc `/dev-gen-test` chạy từ umbrella root.
+
+**project-context.yaml của từng service submodule:**
+```yaml
+# mass-product-be/.agent/project-context.yaml
+tech_stack:
+  language: "TypeScript"
+  framework: "NestJS"
+  module: "nestjs"
+
+conventions:
+  test_command: "npm test"
+  build_command: "npm run build"
+
+paths:
+  trace_dir: ".trace"
+```
+```yaml
+# mass-product-web/.agent/project-context.yaml
+tech_stack:
+  language: "TypeScript"
+  framework: "Next.js 14"
+  module: "nextjs"
+
+conventions:
+  test_command: "npx vitest run"
+  build_command: "npm run build"
+
+paths:
+  trace_dir: ".trace"
+```
+
+Khi `/dev-run-test` chạy từ umbrella root cho một UC thuộc domain `be`:
+1. Step 1.5 detect `service_root = "mass-product-be"`
+2. Step 1.6 load `mass-product-be/.agent/project-context.yaml` → `test_command = "npm test"`
+3. Lệnh test chạy: `cd mass-product-be && npm test`
+
+**BDD + trace ở spec repo (1 tầng); code ở service (2 tầng):**
+```bash
+# BDD (.feature) + trace (.tsv) → SPEC repo (1 tầng — khi spec_source set)
+cd mass-product-specs
+git add specs/auth/login/bdd/FT-001-login.feature .trace/auth/login/FT-001.tsv
+git commit -m "feat(bdd): add login BDD scenarios — FT-001"
+git push
+
+# Code → service submodule (commit 2 lớp)
+cd ../mass-product-be
+git add src/
+git commit -m "feat(FT-001): login implementation"
+git push origin feature/ft-001-login
+cd ..   ← về umbrella root
+git add mass-product-be
+git commit -m "chore: update mass-product-be submodule pointer — FT-001"
+git push
+```
+**Không commit lớp 2 (pointer) → umbrella repo vẫn trỏ về commit cũ của service.**
+
+## Tình huống 8: Validate traces trước khi tạo PR lớn
+
+**Bối cảnh:** Dev refactor module Auth — đổi tên `AuthService` → `IdentityService`.
+```
+Sau khi refactor xong:
+
+/validate-traces
+        │
+        ▼
+Agent kiểm tra:
+- BDD có @trace.module: AuthService → BROKEN (class không còn tồn tại)
+- Code comments @trace.bdd: FT-001-UC1-SC1 → còn hợp lệ không?
+- Tech Docs mention "AuthService" → stale reference
+        │
+        ▼
+Report:
+  ❌ BROKEN  specs/auth/login/bdd/FT-001-login.feature  @trace.module: AuthService (not found)
+  ❌ BROKEN  specs/auth/login/tech-docs/FT-001-auth-api.md  "AuthService" referenced 7 times
+  ✅ OK      src/identity/identity.service.ts  @trace.bdd: FT-001-UC1-SC1
+        │
+        ▼
+Fix: Update @trace.module và references → re-run /validate-traces → all green → tạo PR
+```
+**Quy tắc:** PR không được merge khi còn broken traces.
+
+---
+
+← [Workflow](workflow.md) · Tiếp theo: [Checklist trước khi tạo PR](pr-checklist.md)

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

@@ -0,0 +1,121 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Developer](README.md) › Workflow
+
+# 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
+        │
+        ▼
+/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}
+→ Kiểm tra @trace.domain, @trace.status = approved
+→ Đọc hiểu AC, UC, BR trong PRD
+→ Đọc BDD tương ứng trong specs/{domain}/{prd-slug}/bdd/{platform}/
+→ Nếu có gì không rõ: hỏi PO TRƯỚC khi tiếp tục
+        │
+        ▼
+(Đọc BDD từ spec submodule — KHÔNG tự generate BDD)
+FE/Web:  my-project-specs/specs/{domain}/{prd-slug}/bdd/web/{TICKET-ID}-UC*.feature
+App:     my-project-specs/specs/{domain}/{prd-slug}/bdd/app/{TICKET-ID}-UC*.feature
+BE:      my-project-specs/specs/{domain}/{prd-slug}/bdd/system/{TICKET-ID}-UC*.feature
+        │
+        ▼
+══════════ 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 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}
+→ 4 lens: Security / Performance / Architecture / Test Coverage
+→ Fix issues trước khi tạo PR
+        │
+        ▼
+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

@@ -0,0 +1,79 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › Product Owner / BA
+
+# Hướng Dẫn PO/BA — Spec-Driven Docs
+
+Tài liệu dành cho **Product Owner (PO)** và **Business Analyst (BA)** — vai trò, commands, các tình huống thực tế, và quy tắc viết PRD.
+
+## Mục Lục
+
+| 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) | 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 |
+
+## Vai Trò PO/BA Trong Framework
+
+PO/BA là người duy nhất viết và approve tài liệu đầu vào + BDD:
+
+```
+PO/BA                     Dev team
+──────────────────────    ──────────────────────────────
+/define-product           đọc product-definition + BDD
+/generate-prd        →    /review-context (xác nhận PRD)
+/refine-prd (SA review)   /generate-tech-docs
+/review-context           /generate-code + tests
+/generate-design-spec →   /review-code / /dev-run-test
+/generate-bdd (web)
+/generate-bdd (app)
+/generate-bdd (system)
+```
+
+**PO/BA chịu trách nhiệm:**
+- Đả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** 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:**
+- Tech docs — dev team tự generate
+- Source code — hoàn toàn dev team
+
+### Tại sao BDD thuộc trách nhiệm của PO?
+
+Đặt BDD trong spec repo giúp **tổng hợp toàn bộ tài liệu nghiệp vụ về một chỗ**.
+
+```
+PRD (WHAT + WHY)  →  BDD (HOW verified)  →  Code (HOW built)
+   ↑ PO/BA            ↑ PO/BA              ↑ Dev
+   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: [chương QC Automation](../tester/qc-automation.md).
+
+**3 lý do chính BDD thuộc PO:**
+
+**1. Tổng hợp tài liệu nghiệp vụ tại một nơi** — Khi BDD nằm trong spec repo cùng PRD, mọi spec nghiệp vụ đều ở một chỗ — dễ review, audit, và generate báo cáo. Dev team đọc spec từ submodule, không cần tự suy ra scenarios.
+
+**2. BDD viết ở mức nghiệp vụ — PO hiểu được** — BDD trong spec repo mô tả **hành vi hệ thống** bằng ngôn ngữ nghiệp vụ, không phải implementation detail:
+
+| Platform | BDD trong spec repo (PO viết) | Test code (Dev viết) |
+|---|---|---|
+| Web | `When user submits login → sees dashboard` | `await page.click('#login-btn')` |
+| App | `When user taps Login → navigates to Home` | `element(by.id('login')).tap()` |
+| System | `When login request received → returns auth token` | `POST /api/auth/login assertions` |
+
+**3. System BDD là nguồn sự thật cho BE** — tổng hợp từ FE + App BDD:
+- FE BDD: "User expects auth token để truy cập tiếp"
+- 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) · [chương QC Automation](../tester/qc-automation.md) · [Reference › Commands](../../05-reference/commands.md)