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

package/core/steps/trace-mirror.md

@@ -1,18 +1,26 @@
 # Refresh Living Docs panel mirror *(local, umbrella mode)*
 
 *Skip entirely in single-service mode (no `services` and no `setup.spec_source`) — there
-the service `.trace/` IS the panel location, so nothing to mirror.*
+the repo's own `.trace/` IS the panel location, so nothing to mirror.*
 
-After updating the authoritative service TSV(s) at `{paths.trace_dir}`:
+After updating the authoritative TSV(s) at `{paths.trace_dir}`:
 
-1. Resolve `panel_mirror = ./.trace` at the **current workspace root** (where this command runs).
+**When `setup.spec_source` is set (consolidated trace — the common case):**
+`{paths.trace_dir}` resolves to `{spec_source}/.trace` — the single authoritative location.
+This command runs from `service_root`, so the write is **cross-repo into the spec submodule**;
+commit/push the spec submodule for the trace update (same as `feedback/`).
+1. Resolve `panel_mirror = ./.trace` at the **current workspace root**.
 2. If `panel_mirror` resolves to a different path than `{paths.trace_dir}`, copy each
-   just-updated `{UC-ID}.tsv` → `{panel_mirror}/{service-name}/{UC-ID}.tsv`
-   (create the dir; overwrite). Use `active_service` for `{service-name}`.
+   just-updated `{UC-ID}.tsv` → `{panel_mirror}/{UC-ID}.tsv` (create the dir; overwrite).
+   No per-service namespacing — there is one trace set; the owning service is carried in each
+   row's `@trace.service`.
+
+**Legacy (no `spec_source` — per-service trace):**
+Copy each just-updated `{UC-ID}.tsv` → `{panel_mirror}/{service-name}/{UC-ID}.tsv`
+(namespaced by `active_service`).
 
 This keeps the open workspace's Living Docs panel current **between syncs** — it is a
-**local convenience mirror only**. The *canonical* report in the spec module
-(`{spec_source}/.living-docs/`) and the merged `trace-report.json` are rebuilt by
-`/sync` or `/validate-traces` (those need every service's data, so a single per-UC
-command cannot produce them). For orchestrated commands, do this once in the orchestrator
-after all sub-agents return — not inside each sub-agent.
+**local convenience mirror only**. The merged `trace-report.json` (canonical, in
+`{spec_source}/.living-docs/`) is rebuilt by `/sync` or `/validate-traces`. For orchestrated
+commands, do this once in the orchestrator after all sub-agents return — not inside each
+sub-agent.

package/core/templates/project-context.yaml

@@ -111,19 +111,22 @@ domains:
 #   mode: umbrella                            # "umbrella" | "single" (default: single)
 #   spec_source: "{{SPEC_SUBMODULE_PATH}}"   # path to PO spec submodule, e.g. "free-trial-specs"
 #
-# When spec_source is set, context-loader auto-derives:
+# When spec_source is set, context-loader auto-derives (ALL specs live in the spec repo;
+# service submodules hold only code + .trace/):
+#   specs_dir            → {spec_source}/specs/bdd            # ALL BDD (web/app/system) — cross-team
 #   prd_dir              → {spec_source}/specs/prd
 #   design_spec_dir      → {spec_source}/specs/design-spec
-#   tech_docs_dir        → {spec_source}/specs/tech-docs   # shared API contract (per-service tech_docs_dir below wins in multi-service)
+#   tech_docs_dir        → {spec_source}/specs/tech-docs      # BE API contract + FE tech-design
 #   domain_knowledge_dir → {spec_source}/specs/domain-knowledge
 # (You can still override these manually in paths: section below.)
 #
 # services:                                   # domain → service submodule routing
 #   {{DOMAIN_1}}:                             # must match @trace.domain in PRD files
-#     path: "{{SERVICE_SUBMODULE_DIR}}"       # relative path to service submodule
+#     path: "{{SERVICE_SUBMODULE_DIR}}"       # relative path to service submodule (code + .trace/)
 #     module: "{{STACK_MODULE}}"              # e.g., java-spring, nextjs, flutter
-#     specs_dir: "{{SERVICE_SUBMODULE_DIR}}/specs/bdd"
-#     tech_docs_dir: "{{SERVICE_SUBMODULE_DIR}}/specs/tech-docs"
+#     # NOTE: with spec_source set, BDD + tech-docs are cross-team and live in the spec repo —
+#     # do NOT pin per-service specs_dir / tech_docs_dir here (they would be ignored).
+#     # Per-service specs_dir / tech_docs_dir apply ONLY when there is no spec_source.
 #
 # IMPORTANT — per-service CLAUDE.md:
 #   Each service submodule should have its OWN CLAUDE.md ({path}/CLAUDE.md) defining its

package/docs/01-getting-started/core-concepts.md

@@ -51,11 +51,11 @@ Mỗi artifact link tới artifact khác qua `@trace.*` tags:
 ```
 product-definition.md
   └─► PRD.md (Service, Module trong metadata)
-        └─► {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)
-                          └─► src/test/ (@trace.verifies, @trace.service)
-                                └─► .trace/{UC-ID}.tsv (drift tracking)
+        └─► specs/bdd/{domain}/{web|app|system}/{UC-ID}.feature (@trace.prd_version)
+              └─► specs/tech-docs/{domain}/{UC-ID}-tech-design*.md (@trace.bdd_version)
+                    └─► src/ code — service submodule (@trace.implements)
+                          └─► src/test/ (@trace.verifies)
+   ════► {spec_source}/.trace/{UC-ID}.tsv — authoritative ở SPEC repo (drift tracking)
 ```
 
 `/validate-traces {domain}` đọc các `.trace/{UC-ID}.tsv` và báo cáo:
@@ -92,8 +92,8 @@ my-project-umbrella/          ← mở Claude Code ở đây
 └── web-app/                  ← submodule: FE app
 ```
 
-- **Spec module** (`{spec_source}/`): chứa PRD, Design Spec, và tech-docs (API contract) — shared để mọi umbrella đọc cùng contract. Report canonical của Living Docs cũng sinh tại `{spec_source}/.living-docs/`.
-- **Routing:** context-loader đọc `@trace.domain` từ PRD → tra trong `services` config → route BDD/code vào đúng service submodule. PRD phải có `@trace.domain` khớp một key trong `services`.
+- **Spec module** (`{spec_source}/`): chứa PRD, Design Spec, **ALL BDD (web/app/system)**, tech-docs (BE API contract + FE tech-design), domain-knowledge, feedback — shared để mọi umbrella đọc cùng nguồn. Report canonical của Living Docs cũng sinh tại `{spec_source}/.living-docs/`.
+- **Routing:** context-loader đọc `@trace.domain` từ PRD → tra trong `services` config → route **code** vào đúng service submodule; **BDD + tech-docs + specs + `.trace/` + feedback** đều ở spec module (cross-team, một chỗ cho PM). PRD phải có `@trace.domain` khớp một key trong `services`.
 
 Setup umbrella đầy đủ, file ownership, two-layer commit, multi-platform → [Operations › Sync & Update §4 Umbrella mode](../04-operations/sync-and-update.md#4-umbrella-mode--git-submodule).
 

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

@@ -90,7 +90,7 @@ git diff .agent/ && git add .agent/ && git commit -m "chore: upgrade framework"
 
 > Chỉ upgrade framework command files. `project-context.yaml`, `CLAUDE.md`, domain-knowledge, và `.trace/` không bao giờ bị ghi đè. Để sync *content* của project (submodule code/specs) dùng `/sync`.
 >
-> ⚠️ **QC skills & upgrade:** `--init` / `upgrade.sh` ghi đè **toàn bộ** `.agent/` — **gồm cả** `.agent/skills/qc/`. Nếu QC chỉnh skills trực tiếp trong `.agent/skills/qc/`, các thay đổi đó **mất** khi upgrade. Để giữ an toàn, trỏ `paths.qc_skills_dir` ra một repo/submodule QC **ngoài** `.agent/` (vd `qc-base/.claude/skills`) — upgrade không bao giờ chạm tới đó. Chi tiết: [../02-guides/qc-automation.md#skill-sourcing--upgrade-safety](../02-guides/qc-automation.md#skill-sourcing--upgrade-safety).
+> ⚠️ **QC skills & upgrade:** `--init` / `upgrade.sh` ghi đè **toàn bộ** `.agent/` — **gồm cả** `.agent/skills/qc/`. Nếu QC chỉnh skills trực tiếp trong `.agent/skills/qc/`, các thay đổi đó **mất** khi upgrade. Để giữ an toàn, trỏ `paths.qc_skills_dir` ra một repo/submodule QC **ngoài** `.agent/` (vd `qc-base/.claude/skills`) — upgrade không bao giờ chạm tới đó. Chi tiết: [../02-guides/tester/qc-automation.md#skill-sourcing--upgrade-safety](../02-guides/tester/qc-automation.md#skill-sourcing--upgrade-safety).
 
 ## QC automation stack (tùy chọn)
 
@@ -104,7 +104,7 @@ pip install pytest-playwright
 python3 -m playwright install
 ```
 
-`qc-playwright` = Python + pytest-playwright + Page Object (output: Playwright Trace + pytest-html). Chi tiết pipeline: [../02-guides/qc-automation.md](../02-guides/qc-automation.md).
+`qc-playwright` = Python + pytest-playwright + Page Object (output: Playwright Trace + pytest-html). Chi tiết pipeline: [../02-guides/tester/qc-automation.md](../02-guides/tester/qc-automation.md).
 
 ## VS Code extension (khuyến nghị)
 

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

@@ -80,6 +80,6 @@ Mỗi review command ghi findings vào `.agent/review/*-findings.yaml`. Mở **R
 ## Bước tiếp theo
 
 - Hiểu khái niệm phía sau pipeline → [core-concepts.md](core-concepts.md).
-- QC suite chính thức (`/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report`) → [../02-guides/qc-automation.md](../02-guides/qc-automation.md).
+- QC suite chính thức (`/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report`) → [../02-guides/tester/qc-automation.md](../02-guides/tester/qc-automation.md).
 - Role guides, scenarios thực tế, multi-repo/umbrella → [../02-guides](../02-guides) và [../03-concepts](../03-concepts).
 - Full command reference → [../05-reference](../05-reference).

package/docs/02-guides/README.md

@@ -10,8 +10,7 @@ Mỗi role trong framework spec-driven-dev có một guide riêng: vai trò, com
 |---|---|---|
 | [Product Owner / BA](product-owner/README.md) | PO, BA | Viết PRD platform-agnostic, generate Design Spec + BDD, handoff cho dev team |
 | [Developer (FE / BE / App)](developer/README.md) | Dev | Đọc PRD + BDD từ spec submodule, generate tech-docs + code, dev self-check, trace system |
-| [Tester / QA](tester/README.md) | QA, Tester | Spec-manifest, đọc spec chain, viết test cases, `/report-bug` + `/propose-scenario` |
-| [QC Automation](qc-automation.md) | QC | Pipeline `/qc-*` 6 bước, `qc_status` chính thức, stack module `qc-playwright` |
+| [Tester / QA](tester/README.md) | QA / Tester / QC | Spec-manifest, đọc spec chain, viết test cases, `/report-bug` + `/propose-scenario`, và chương **[QC Automation](tester/qc-automation.md)** (pipeline `/qc-*` 6 bước, `qc_status`, stack `qc-playwright`) — **một role duy nhất** |
 | Designer | Designer, UX | Tham gia giai đoạn Design Spec — sign-off màn hình + component trước khi PO gen BDD. Chưa có guide riêng; xem [Product Owner › Design Spec](product-owner/scenarios.md#tình-huống-3--tạo-design-spec-và-bdd-sau-khi-prd-approved) để biết điểm giao. |
 
 ## Phân biệt nhanh hai luồng test

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

@@ -43,4 +43,4 @@ PO/BA                     Dev
 
 ---
 
-*Xem thêm:* [Product Owner Guide](../product-owner/README.md) · [Tester Guide](../tester/README.md) · [QC Automation Guide](../qc-automation.md) · [Concepts › Traceability](../../03-concepts/traceability.md) · [Reference › Commands](../../05-reference/commands.md)
+*Xem thêm:* [Product Owner Guide](../product-owner/README.md) · [Tester Guide](../tester/README.md) · [chương QC Automation](../tester/qc-automation.md) · [Concepts › Traceability](../../03-concepts/traceability.md) · [Reference › Commands](../../05-reference/commands.md)

package/docs/02-guides/developer/bdd-and-trace.md

@@ -70,11 +70,13 @@ Framework dùng metadata `@trace.*` để liên kết PRD → BDD → Code. (Chi
 ### Ví dụ trace chain hoàn chỉnh
 
 ```
-specs/prd/auth/FT-001-login.md          ← @trace.domain: auth, @trace.status: approved
+specs/prd/auth/FT-001-login.md                 ← @trace.domain: auth, @trace.status: approved
     ↓
-specs/bdd/auth/FT-001-login.feature     ← @trace.prd: FT-001, @trace.module: AuthService
+specs/bdd/auth/system/FT-001-UC1-login.feature ← @trace.prd: FT-001 · web/app/system riêng (system tổng hợp từ web+app)
     ↓
-src/auth/auth.service.ts                ← // @trace.bdd: FT-001-UC1-SC1
+src/auth/auth.service.ts                        ← // @trace.bdd: FT-001-UC1-SC1   (service submodule)
+    ↓
+{spec_source}/.trace/FT-001.tsv                 ← coverage/drift — authoritative ở SPEC repo
 ```
 
 ### Khi nào chạy /validate-traces?
@@ -93,7 +95,7 @@ src/auth/auth.service.ts                ← // @trace.bdd: FT-001-UC1-SC1
 **Lưu ý khi dùng umbrella (submodule):**
 ```
 Vấn đề: Living Docs panel mở ở umbrella root (hoặc một service submodule đơn lẻ) → nếu không có mirror local → TRỐNG.
-         TSV authoritative nằm committed trong từng service submodule: user-service/.trace/, order-service/.trace/
+         TSV authoritative nằm committed MỘT chỗ ở spec repo: {spec_source}/.trace/
 
 Giải pháp: /validate-traces (hoặc /sync) regenerate canonical trace-report.json + TSV mirror
           trong SPEC MODULE tại {spec_source}/.living-docs/ (gitignored), đồng thời ghi
@@ -102,13 +104,13 @@ Giải pháp: /validate-traces (hoặc /sync) regenerate canonical trace-report.
 
 Lệnh chạy sau mỗi session:
 /validate-traces
-→ 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, regenerated bởi /sync hoặc /validate-traces)
-→ Writes panel mirror → ./.trace của workspace hiện tại (non-empty khi mở single service)
+→ Reads .trace/*.tsv authoritative (committed) MỘT chỗ: {spec_source}/.trace/ (mỗi row mang @trace.service)
+→ Writes trace-report.json → {spec_source}/.living-docs/ (gitignored, regenerated bởi /sync hoặc /validate-traces)
+→ 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
 ```
 
-> **Authoritative vs mirror:** per-service `.trace/*.tsv` vẫn được **commit** trong từng service (nguồn sự thật). `{spec_source}/.living-docs/` và `./.trace` chỉ là mirror gitignored, regenerated bởi `/sync` hoặc `/validate-traces`.
+> **Authoritative vs mirror:** `.trace/*.tsv` được **commit** ở spec repo `{spec_source}/.trace/` (nguồn sự thật, một chỗ). `{spec_source}/.living-docs/` và `./.trace` chỉ là mirror gitignored, regenerated bởi `/sync` hoặc `/validate-traces`.
 
 Thêm `.living-docs/` (spec module) và umbrella/workspace `.trace/` mirror vào `.gitignore`:
 ```

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

@@ -7,9 +7,9 @@
 | `/sync` `[spec-branch]` | **One-command setup hoặc update** — git pull + submodule sync + Living Docs refresh. Truyền branch để override branch spec submodule (vd `/sync develop`) | **Mỗi sáng trước khi bắt đầu work** |
 | `/update-framework` | Nâng cấp **bản thân framework** (`.agent/commands/`, steps/, modules/) từ npm | Khi có version framework mới — không đụng project-context/CLAUDE.md |
 | `/review-context {prd-file}` | Đọc + xác nhận PRD + BDD đủ rõ trước khi code — fan-out review dimension thành sub-agent song song + completeness-critic loop, findings file đầy đủ ngay trong 1 lần chạy | **Bước đầu tiên** khi nhận PRD mới |
-| `/generate-tech-docs {prd-file}` | Sinh Tech Docs (API, DB schema, sequence diagram) | Sau khi đọc BDD từ spec submodule |
+| `/generate-tech-docs {feature-file}` | **Platform-aware.** BE (`system`): API contract (endpoints, DB, caching). FE/App (`web`/`app`): client design (components, state, API-integration map theo BE contract, routing) — **GATED**: cần System BDD + BE contract approved trước, nếu thiếu sẽ HALT | BE: sau khi đọc System BDD. FE: sau `--phase=ui`, khi BE contract đã approved |
 | `/generate-code {bdd-file}` | Sinh code — BE hoặc FE khi API đã sẵn sàng | Sau khi tech docs `approved` |
-| `/generate-code {bdd-file} --phase=ui` | FE: gen UI + mock adapter (BE chưa ready) | Ngay sau khi đọc BDD |
+| `/generate-code {bdd-file} --phase=ui` | FE: gen UI + mock adapter. Mock **shape** từ BE contract nếu có (chuẩn) → else infer từ System BDD + warn (`mock_source=contract\|system-bdd`); fixture values luôn từ System BDD | Ngay sau khi đọc BDD (BE chưa cần deploy API) |
 | `/generate-code {bdd-file} --phase=integration` | FE: wire API thật thay mock | Sau khi sign-off gate `approved` |
 | `/dev-gen-test {bdd-file}` | **Dev self-check** — sinh test cases từ BDD để dev tự verify code mình vừa gen (KHÔNG phải bộ test chính thức của QC/dev-team) | Song song hoặc sau generate-code |
 | `/review-code {file}` | Review code theo 4 lens (Security/Perf/Arch/Test) | Trước khi tạo PR |
@@ -21,7 +21,7 @@
 | `/validate-traces` | Kiểm tra toàn bộ trace chain còn hợp lệ | Sau refactor hoặc khi PRD update |
 | `/learn {text}` | Ghi lại lỗi AI hay lặp thành guardrail | Khi AI lặp lại lỗi mà bạn không muốn nó tái diễn |
 
-> **Dev self-check vs QC chính thức:** `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` (ghi `dev_selftest`) chỉ là **smoke self-check của riêng dev**. Bộ QC chính thức giờ là native pipeline `/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report` — **do QC chạy, không phải việc của dev** — và ghi `qc_status` riêng. Chi tiết: [QC Automation Guide](../qc-automation.md).
+> **Dev self-check vs QC chính thức:** `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` (ghi `dev_selftest`) chỉ là **smoke self-check của riêng dev**. Bộ QC chính thức giờ là native pipeline `/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report` — **do QC chạy, không phải việc của dev** — và ghi `qc_status` riêng. Chi tiết: [chương QC Automation](../tester/qc-automation.md).
 
 > Danh mục đầy đủ mọi command: [Reference › Commands](../../05-reference/commands.md).
 

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

@@ -67,6 +67,13 @@ Feature: User Authentication — System Contract
 ```
 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/bdd/auth/web/`.
@@ -89,7 +96,7 @@ Scenario: Account locked — countdown shown
 ```
 FE dev dùng Web BDD để:
 1. Thiết kế component spec + API integration plan (`/generate-tech-docs`)
-2. Gen UI + mock adapter từ System BDD contract (`/generate-code --phase=ui`) → 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
+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`)
@@ -179,7 +186,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
 
@@ -206,7 +213,7 @@ Chạy:
 ```
 /fix-bug "BUG-20260605-003: FT-001-UC2-BR3 — account not locked after 5 failures
   PRD: specs/prd/auth/FT-001-login.md
-  BDD: free-trial-be/specs/bdd/auth/FT-001-login.feature"
+  BDD: free-trial-specs/specs/bdd/auth/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.
 
@@ -337,7 +344,7 @@ code .   ← hoặc claude .
 
 # 4. Framework tự detect umbrella mode từ project-context.yaml
 # Khi chạy /review-context với PRD có @trace.domain: be
-# → tự động route tới mass-product-be/specs/bdd/
+# → CODE route tới mass-product-be/  ·  BDD đọc từ spec repo mass-product-spec/specs/bdd/ (spec_source set)
 ```
 
 **Update hằng ngày — cũng chỉ 1 lệnh:**
@@ -356,13 +363,14 @@ services:
   be:
     path: "mass-product-be"
     module: "NestJS"
-    specs_dir: "mass-product-be/specs/bdd"
+    # 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"
-    specs_dir: "mass-product-web/specs/bdd"
 ```
 
+> **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.
@@ -402,21 +410,25 @@ Khi `/dev-run-test` chạy từ umbrella root cho một UC thuộc domain `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`
 
-**Commit 2 lớp (bắt buộc):**
+**BDD + trace ở spec repo (1 tầng); code ở service (2 tầng):**
 ```bash
-# Lớp 1: Commit trong service submodule
-cd mass-product-be
-git add specs/bdd/auth/FT-001-login.feature
+# BDD (.feature) + trace (.tsv) → SPEC repo (1 tầng — khi spec_source set)
+cd mass-product-specs
+git add specs/bdd/auth/FT-001-login.feature .trace/FT-001.tsv
 git commit -m "feat(bdd): add login BDD scenarios — FT-001"
-git push origin feature/ft-001-login
+git push
 
-# Lớp 2: Update pointer tại umbrella
+# 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 BDD"
+git commit -m "chore: update mass-product-be submodule pointer — FT-001"
 git push
 ```
-**Không commit lớp 2 → umbrella repo vẫn trỏ về commit cũ của service.**
+**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
 

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,7 +105,16 @@ BE:      my-project-specs/specs/bdd/{domain}/system/{TICKET-ID}-UC*.feature
 Tạo PR → notify PO/SA review
 ```
 
-> **Commit ở đâu, push mấy tầng?** Code + `.trace/` nằm trong service submodule → **commit 2 tầng** (service rồi umbrella pointer); tech-docs đẩy lên spec repo. Sơ đồ git đầy đủ theo từng role: [Sync & Update — Git flow theo role](../../04-operations/sync-and-update.md#ai-commit-vào-repo-nào-git-flow-theo-role).
+</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).
 
 ---
 

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)