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

package/docs/05-reference/commands.md

@@ -2,7 +2,9 @@
 
 # Command Reference
 
-> Mọi slash command của framework, gom theo phase. Mỗi command kèm **Input**, **Output**, và **When to use**. Phần cuối mô tả **Command Internals** — kiến trúc step file dùng chung bởi mọi command.
+> Mọi slash command của framework, gom theo phase. Mỗi command kèm **Cách dùng (ví dụ cụ thể)**, **Output**, và **When to use**. Phần cuối mô tả **Command Internals** — kiến trúc step file dùng chung bởi mọi command.
+>
+> Ví dụ dùng chung một feature xuyên suốt: domain `auth`, ticket `FEAT-01`, use case `FEAT-01-UC1` (đăng nhập). Thay bằng file/UC-ID của bạn.
 
 ---
 
@@ -18,7 +20,7 @@
 - [Phase 6 — Dev Self-Check](#phase-6--dev-self-check)
 - [Phase 6b — QC Automation (official QC suite)](#phase-6b--qc-automation-official-qc-suite)
 - [Phase 7 — Traceability Audit](#phase-7--traceability-audit)
-- [Phase 8 — Tester Feedback](#phase-8--tester-feedback)
+- [Phase 8 — Tester / QC Feedback](#phase-8--tester--qc-feedback)
 - [Debugging & Cross-cutting](#debugging--cross-cutting)
 - [Command Internals — Step Architecture](#command-internals--step-architecture)
 
@@ -28,13 +30,13 @@
 
 ## Setup & Maintenance
 
-| Command | Input | Output | When to use |
-|---------|-------|--------|-------------|
-| `/setup-ai-first` | — | Project structure + config files | First-time project setup |
-| `/sync` | — | Git pull + submodule update + Living Docs sync | **Daily driver** — đồng bộ *nội dung* project (code/specs trong submodule) |
-| `/update-framework` | — | Refreshed `.agent/` command files from npm | **Occasionally** — nâng cấp *bản thân framework* khi có version mới |
-| `/sync-figma-components {module}` | Module name | Updated `figma-components/{module}.md` | After Figma design system changes |
-| `/sync-figma-tokens {url?}` | Optional Figma URL | Updated `figma-tokens.md` | After design token changes |
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/setup-ai-first` | `/setup-ai-first` | Project structure + config files | First-time project setup |
+| `/sync` | `/sync` | Git pull + submodule update + Living Docs sync | **Daily driver** — đồng bộ *nội dung* project (code/specs trong submodule) |
+| `/update-framework` | `/update-framework` | Refreshed `.agent/` command files from npm | **Occasionally** — nâng cấp *bản thân framework* khi có version mới |
+| `/sync-figma-components {module}` | `/sync-figma-components react` | Updated `figma-components/{module}.md` | After Figma design system changes |
+| `/sync-figma-tokens {url?}` | `/sync-figma-tokens` *(hoặc kèm URL Figma)* | Updated `figma-tokens.md` | After design token changes |
 
 > **`/sync` vs `/update-framework` là hai thứ khác nhau:**
 > - `/sync` cập nhật **nội dung project** — pull code/specs mới từ git remote + refresh Living Docs. Nguồn = git remotes của bạn. Chạy thường xuyên.
@@ -44,30 +46,30 @@
 
 ## Phase 1 — Discovery
 
-| Command | Input | Output | When to use |
-|---------|-------|--------|-------------|
-| `/define-product` | — | `specs/product-definition/{TICKET-ID}-{slug}.md` | Starting any new feature. AI dẫn PO qua 7 phase Q&A có cấu trúc — không cần spec viết sẵn. |
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/define-product` | `/define-product` | `specs/product-definition/{TICKET-ID}-{slug}.md` | Starting any new feature. AI dẫn PO qua 7 phase Q&A có cấu trúc — không cần spec viết sẵn. |
 
 ---
 
 ## Phase 2 — PRD
 
-| Command | Input | Output | When to use |
-|---------|-------|--------|-------------|
-| `/generate-prd` | product-definition file | `specs/prd/{domain}/{TICKET-ID}-{slug}.md` | After define-product. Thêm `API Source: existing` + section "Existing API Contract" cho feature brownfield. |
-| `/refine-prd` | prd file | `.agent/review/{prd-slug}-findings.yaml` | After generate-prd — fan-out 4 review lens + completeness-critic loop, mở Review Board. |
-| `/refine-prd --resume` | prd file | Applied findings + bumped version | Sau khi review trong Review Board. |
-| `/review-context` (PRD) | prd file | `.agent/review/{prd-slug}-review-context-findings.yaml` | Quality gate bắt buộc trước Phase 3. Checks: banned terms (P1), ambiguity (P2), conflicts (P3), completeness (P4). |
-| `/review-context --fix` | prd file | Applies all auto-fixable findings immediately | Dev quick-fix, không cần Review Board. |
-| `/review-context --resume` | prd file | Applies accepted findings + bump version | PO/SA review — human quyết từng finding. |
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/generate-prd` | `/generate-prd specs/product-definition/FEAT-01-login.md` | `specs/prd/{domain}/{TICKET-ID}-{slug}.md` | After define-product. Thêm `API Source: existing` + section "Existing API Contract" cho feature brownfield. |
+| `/refine-prd` | `/refine-prd specs/prd/auth/FEAT-01-login.md` | `.agent/review/{prd-slug}-findings.yaml` | After generate-prd — fan-out 4 review lens + completeness-critic loop, mở Review Board. |
+| `/refine-prd --resume` | `/refine-prd --resume specs/prd/auth/FEAT-01-login.md` | Applied findings + bumped version | Sau khi review trong Review Board (nút ⚡ Apply tự chạy lệnh này). |
+| `/review-context` (PRD) | `/review-context specs/prd/auth/FEAT-01-login.md` | `.agent/review/{prd-slug}-review-context-findings.yaml` | Quality gate bắt buộc trước Phase 3. Checks: banned terms (P1), ambiguity (P2), conflicts (P3), completeness (P4). |
+| `/review-context --fix` | `/review-context --fix specs/prd/auth/FEAT-01-login.md` | Applies all auto-fixable findings immediately | Dev quick-fix, không cần Review Board. |
+| `/review-context --resume` | `/review-context --resume specs/prd/auth/FEAT-01-login.md` | Applies accepted findings + bump version | PO/SA review — human quyết từng finding. |
 
 ---
 
 ## Phase 2b — Design Spec (FE/App)
 
-| Command | Input | Output | When to use |
-|---------|-------|--------|-------------|
-| `/generate-design-spec` | prd file | `specs/design-spec/{domain}/{TICKET-ID}-design-spec-{platform}.md` | FE/App: sau khi PRD approved, trước BDD. PO phải cấp **node-level Figma frame link** (URL có `?node-id=`) cho mỗi screen; AI fetch từng frame qua Figma MCP. Screen thiếu link → ❌ Missing, spec ở draft và chặn sign-off + `/generate-bdd`. |
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/generate-design-spec` | `/generate-design-spec specs/prd/auth/FEAT-01-login.md` | `specs/design-spec/{domain}/{TICKET-ID}-design-spec-{platform}.md` | FE/App: sau khi PRD approved, trước BDD. PO phải cấp **node-level Figma frame link** (URL có `?node-id=`) cho mỗi screen; AI fetch từng frame qua Figma MCP. Screen thiếu link → ❌ Missing, spec ở draft và chặn sign-off + `/generate-bdd`. |
 
 > BE teams bỏ qua Phase 2b — đọc PRD trực tiếp rồi `/generate-bdd`.
 
@@ -75,33 +77,34 @@
 
 ## Phase 3 — BDD Spec
 
-| Command | Input | Output | When to use |
-|---------|-------|--------|-------------|
-| `/generate-bdd` | prd file | `specs/bdd/{domain}/{UC-ID}.feature` (multi-service: `{domain}/{service}/{UC-ID}.feature`) | After PRD approved (+ Design Spec sign-off cho FE/App). Đọc Service/Module từ PRD metadata, áp platform vocabulary, hiện SC outline chờ confirm. PRD lớn (>3 UC hoặc >300 dòng) → orchestration mode (1 sub-agent / UC). |
-| `/review-context` (BDD) | feature file | `.agent/review/{uc-id}-review-bdd-findings.yaml` | Quality gate bắt buộc trước Phase 4. Checks: PRD coverage (mỗi AC + BR → ≥1 SC), Gherkin R1–R10, compliance C1–C5. |
-| `/review-context --fix` | feature file | Auto-fix terminology, metadata, coverage matrix | Dev quick-fix. |
-| `/review-context --resume` | feature file | Applies accepted findings + bump bdd_version | SA review. |
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/generate-bdd` | `/generate-bdd specs/prd/auth/FEAT-01-login.md` | `specs/bdd/{domain}/{UC-ID}.feature` (multi-service: `{domain}/{service}/{UC-ID}.feature`) | After PRD approved (+ Design Spec sign-off cho FE/App). Đọc Service/Module từ PRD metadata, áp platform vocabulary, hiện SC outline chờ confirm. **Thứ tự outside-in: web → app → system**; `system` **tổng hợp từ web+app BDD** (web&app lệch contract → CHECKPOINT chọn union/platform-hint/separate-endpoints, ghi `@system.resolution:`; chỉ-BE → từ PRD). PRD lớn (>3 UC hoặc >300 dòng) → orchestration mode (1 sub-agent / UC). |
+| `/review-context` (BDD) | `/review-context specs/bdd/auth/system/FEAT-01-UC1-login.feature` | `.agent/review/{uc-id}-review-bdd-findings.yaml` | Quality gate bắt buộc trước Phase 4. Checks: PRD coverage (mỗi AC + BR → ≥1 SC), Gherkin R1–R10, compliance C1–C5. |
+| `/review-context --fix` | `/review-context --fix specs/bdd/auth/web/FEAT-01-UC1-login.feature` | Auto-fix terminology, metadata, coverage matrix | Dev quick-fix. |
+| `/review-context --resume` | `/review-context --resume specs/bdd/auth/system/FEAT-01-UC1-login.feature` | Applies accepted findings + bump bdd_version | SA review. |
 
 ---
 
 ## Phase 4 — Tech Design
 
-| Command | Input | Output | When to use |
-|---------|-------|--------|-------------|
-| `/generate-tech-docs` | feature file | `tech-docs/{domain}/{UC-ID}-tech-design.md` (multi-service: `{domain}/{service}/...`) | After BDD approved. Đọc `@trace.module` → chọn template theo platform type. Brownfield (`@trace.api_source: existing`) → reverse-document mode. |
-| `/review-tech-docs` | tech-design file | `.agent/review/{uc-id}-tech-review-findings.yaml` | After generate-tech-docs — mở Review Board. |
-| `/review-tech-docs --resume` | tech-design file | Applies accepted findings + bump revision | Sau khi review trong Review Board. |
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/generate-tech-docs` | `/generate-tech-docs specs/bdd/auth/system/FEAT-01-UC1-login.feature` | **BE** (`system`): `tech-docs/{domain}/{UC-ID}-tech-design.md` (API contract) · **FE/App** (`web`/`app`): `{UC-ID}-tech-design-{platform}.md` (client design) | After BDD approved. **Platform-aware** (`@trace.platform`): BE = API contract; FE/App = client design (components/state/API-integration/routing + **§2b Test Selectors**: test-id ổn định cho element có action → QC locate khỏi scan) — **GATED**: HALT nếu thiếu System BDD hoặc BE contract approved. Brownfield (`@trace.api_source: existing`) → reverse-document (BE). |
+| `/map-testids {UC-ID}` | `/map-testids FEAT-01-UC1` | Cập nhật FE tech-design §2b Test Selectors + patch forwarding/usage-site + ghi `figma-components/{module}.md` | FE/App, cho component **reuse** / code **có sẵn** (brownfield): reverse-document id đang có, gán id còn thiếu, đảm bảo component dùng chung forward được test-id. Bổ trợ cho `/generate-tech-docs` (chỉ gán id cho code mới). |
+| `/review-tech-docs` | `/review-tech-docs tech-docs/auth/FEAT-01-UC1-tech-design.md` | `.agent/review/{uc-id}-tech-review-findings.yaml` | After generate-tech-docs — mở Review Board. |
+| `/review-tech-docs --resume` | `/review-tech-docs --resume tech-docs/auth/FEAT-01-UC1-tech-design.md` | Applies accepted findings + bump revision | Sau khi review trong Review Board. |
 
 ---
 
 ## Phase 5 — Code
 
-| Command | Input | Output | When to use |
-|---------|-------|--------|-------------|
-| `/generate-code` | feature file | `src/...` (tags `@trace.implements`) | After tech-design approved. Default = full impl/BE. |
-| `/generate-code --phase=ui` | feature file | UI + mock API adapter | FE: BE chưa sẵn sàng — sinh UI + mock adapter từ System BDD contract; tester test FE ngay được. |
-| `/generate-code --phase=integration` | feature file | Wires real API | FE: sau khi T7 sign-off gate approved — thay mock adapter bằng real API calls. |
-| `/review-code` | — | Review report: Critical / Major / Minor | After generate-code. Check: mỗi scenario có endpoint, trace tags, layer rules, error handling khớp CLAUDE.md §5. Fix CRITICAL + MAJOR trước khi merge. |
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/generate-code` | `/generate-code specs/bdd/auth/system/FEAT-01-UC1-login.feature` | `src/...` (tags `@trace.implements`) | After tech-design approved. Default = full impl/BE. |
+| `/generate-code --phase=ui` | `/generate-code --phase=ui specs/bdd/auth/web/FEAT-01-UC1-login.feature` | UI + mock API adapter | FE: BE chưa sẵn sàng — sinh UI + mock adapter. Mock **shape**: BE contract nếu có (chuẩn) → else System BDD + warn; fixture values luôn từ System BDD. Tester test FE ngay được. |
+| `/generate-code --phase=integration` | `/generate-code --phase=integration specs/bdd/auth/web/FEAT-01-UC1-login.feature` | Wires real API | FE: sau khi T7 sign-off gate approved — thay mock adapter bằng real API calls. |
+| `/review-code` | `/review-code FEAT-01-UC1` | Review report: Critical / Major / Minor | After generate-code. Check: mỗi scenario có endpoint, trace tags, layer rules, error handling khớp CLAUDE.md §5. Fix CRITICAL + MAJOR trước khi merge. |
 
 ---
 
@@ -109,56 +112,56 @@
 
 > Đây là **developer self-check / smoke** — dev tự kiểm tra code mình vừa sinh ra. **Không phải** official QC suite (đó là Phase 6b `/qc-*`). Signal = `dev_selftest`, tách biệt với `qc_status`.
 
-| Command | Input | Output | When to use |
-|---------|-------|--------|-------------|
-| `/dev-gen-test` | feature file | `src/test/...` (tags `@trace.verifies`) | After generate-code. Tự chọn test framework đúng platform. |
-| `/dev-run-test` | — | Self-check report — ghi `dev_selftest` (pass/fail/not_run) + `dev_selftest_at` vào trace TSV | After dev-gen-test. |
-| `/dev-smoke-test` | — | Live endpoint check | Optional — sau deploy. |
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/dev-gen-test` | `/dev-gen-test specs/bdd/auth/system/FEAT-01-UC1-login.feature` | `src/test/...` (tags `@trace.verifies`) | After generate-code. Tự chọn test framework đúng platform. |
+| `/dev-run-test` | `/dev-run-test FEAT-01-UC1` | Self-check report — ghi `dev_selftest` (pass/fail/not_run) + `dev_selftest_at` vào trace TSV | After dev-gen-test. |
+| `/dev-smoke-test` | `/dev-smoke-test FEAT-01-UC1` | Live endpoint check | Optional — sau deploy. |
 
 ---
 
 ## Phase 6b — QC Automation (official QC suite)
 
-> Pipeline `/qc-*` **là** official QC suite. Chạy **theo thứ tự** sau khi BDD approved (`/review-context` (BDD) APPROVED). Tách biệt hoàn toàn với dev self-check: QC sở hữu `qc_status`, dev sở hữu `dev_selftest`. `/qc-run-test` & `/qc-report` dùng module `qc-playwright`, độc lập với dev implementation module. Xem [../02-guides/qc-automation.md](../02-guides/qc-automation.md).
+> Pipeline `/qc-*` **là** official QC suite. Chạy **theo thứ tự** sau khi BDD approved (`/review-context` (BDD) APPROVED). Tách biệt hoàn toàn với dev self-check: QC sở hữu `qc_status`, dev sở hữu `dev_selftest`. `/qc-run-test` & `/qc-report` dùng module `qc-playwright`, độc lập với dev implementation module. Xem [../02-guides/tester/qc-automation.md](../02-guides/tester/qc-automation.md).
 
-| Command | Input | Output | When to use |
-|---------|-------|--------|-------------|
-| `/qc-analyze` | feature file / UC-ID | QC analysis of scenarios + risks | After BDD approved — đầu pipeline QC. |
-| `/qc-plan` | QC analysis | Test plan (scope, layers, priorities) | After `/qc-analyze`. |
-| `/qc-design-test` | test plan | Test case designs mapped to `{UC-ID}-SC{N}` | After `/qc-plan`. |
-| `/qc-review` | test designs | Reviewed/approved test design set | After `/qc-design-test`. |
-| `/qc-run-test` | test designs | Execution results — ghi `qc_status` (pass/fail/skip/not_run) + `qc_run_at` vào trace TSV, keyed by `@trace.verifies={UC-ID}-SC{N}` | After `/qc-review`. |
-| `/qc-report` | run results | QC report (Playwright Trace + pytest-html) | After `/qc-run-test`. |
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/qc-analyze` | `/qc-analyze FEAT-01-UC1` | **2 file** trong `{qc_dir}/{UC-ID}/` (mặc định `docs/`): `REQUIREMENT_ANALYSIS.md` (gộp requirement + BR + data-flow + AC) + `DOC_GAPS.md` | After BDD approved — đầu pipeline QC. |
+| `/qc-plan` | `/qc-plan FEAT-01-UC1` | `{qc_dir}/{UC-ID}/TEST_PLAN.md` (scope, layers, priorities, questions-for-dev) | After `/qc-analyze`. |
+| `/qc-design-test` | `/qc-design-test FEAT-01-UC1` | `{qc_dir}/{UC-ID}/test-cases/*.Test.md` mapped to `{UC-ID}-SC{N}` | After `/qc-plan`. |
+| `/qc-review` | `/qc-review FEAT-01-UC1` | Verdict APPROVED / NEEDS_FIX + findings (**inline — không sinh file**) | After `/qc-design-test` (test-case) hoặc `/qc-run-test` (script). |
+| `/qc-run-test` | `/qc-run-test FEAT-01-UC1` | Script Python (`pages/`, `tests/`) + ghi `qc_status` (pass/fail/skip/not_run) + `qc_run_at` vào trace TSV, keyed by `@trace.verifies={UC-ID}-SC{N}` | After `/qc-review`. |
+| `/qc-report` | `/qc-report FEAT-01-UC1` | QC report `reports/<feature>/report.html` (Playwright Trace + pytest-html) | After `/qc-run-test`. |
 
 ---
 
 ## Phase 7 — Traceability Audit
 
-| Command | Input | Output | When to use |
-|---------|-------|--------|-------------|
-| `/validate-traces {domain}` | domain name (hoặc UC-ID) | Coverage matrix + drift report + `trace-report.json` | Anytime — verify traceability. Đọc mọi `.trace/{UC-ID}.tsv` rồi tính status OK / DRIFT / GAP / UNTRACKED. |
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/validate-traces {domain}` | `/validate-traces auth` *(hoặc `/validate-traces FEAT-01-UC1`)* | Coverage matrix + drift report + `trace-report.json` | Anytime — verify traceability. Đọc mọi `.trace/{UC-ID}.tsv` rồi tính status OK / DRIFT / GAP / UNTRACKED. |
 
 ---
 
-## Phase 8 — Tester Feedback
+## Phase 8 — Tester / QC Feedback
 
-> Cả hai đều **read-only trên canonical specs/code**. Chúng chỉ ghi vào `feedback/` của shared spec repo và **commit + push** → PO/Dev thấy qua `/sync`. Testers không bao giờ sửa `.feature` trực tiếp.
+> Cả hai đều **read-only trên canonical specs/code**. Chúng chỉ ghi vào `feedback/` của shared spec repo và **commit + push** → PO/Dev thấy qua `/sync`. Tester/QC không bao giờ sửa `.feature` trực tiếp. QC cũng dùng hai lệnh này: `/qc-run-test` FAIL = product-gap và `/qc-analyze` DOC_GAPS blocker đều route sang `/report-bug` hoặc `/propose-scenario` (xem [../02-guides/tester/qc-automation.md](../02-guides/tester/qc-automation.md)).
 
-| Command | Input | Output | When to use |
-|---------|-------|--------|-------------|
-| `/report-bug {UC-ID} {desc}` | UC/TICKET + description | `{spec_repo}/feedback/bug-reports/{BUG-ID}.md` + spec context + layer classification | Tester tìm thấy bug. Phân loại layer (Code/BDD/PRD/Design/Env) để route. |
-| `/propose-scenario {UC-ID} {desc}` | UC + edge-case description | `{spec_repo}/feedback/bdd-proposals/{UC-ID}-*.md` draft Gherkin | Tester tìm thấy edge case BDD chưa cover. Map vào PRD AC sẵn có, hoặc emit PRD change request nếu hành vi thực sự mới. |
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/report-bug {UC-ID} {desc}` | `/report-bug FEAT-01-UC1 "nhập sai mật khẩu vẫn đăng nhập được"` | `{spec_repo}/feedback/bug-reports/{BUG-ID}.md` + spec context + layer classification | Tester hoặc QC tìm thấy bug (gồm QC product-gap). Phân loại layer (Code/BDD/PRD/Design/Env) để route. |
+| `/propose-scenario {UC-ID} {desc}` | `/propose-scenario FEAT-01-UC1 "khoá tài khoản sau 5 lần sai mật khẩu"` | `{spec_repo}/feedback/bdd-proposals/{UC-ID}-*.md` draft Gherkin | Tester hoặc QC tìm thấy edge case BDD chưa cover. Map vào PRD AC sẵn có, hoặc emit PRD change request nếu hành vi thực sự mới. |
 
 ---
 
 ## Debugging & Cross-cutting
 
-| Command | Input | Output | When to use |
-|---------|-------|--------|-------------|
-| `/fix-bug` | — | Bug fix | When a bug is found. |
-| `/debug` | — | Debug session | Deep debugging. |
-| `/learn {text}` | "AI does X, should Y" | Appends guardrail vào project lessons file | Khi AI lặp lại lỗi bạn muốn chặn. |
-| `/generate-spec-manifest` | — | `spec-manifest.yaml` | Sinh manifest làm entry point cho external/tester agents. |
+| Command | Cách dùng (ví dụ) | Output | When to use |
+|---------|-------------------|--------|-------------|
+| `/fix-bug {BUG-ID\|ticket\|desc}` | `/fix-bug BUG-012` *(hoặc ticket / mô tả lỗi)* | Code fix trên branch + regression test; nếu nhận `{BUG-ID}` → set report State `🟢 Open` → `🟡 Fixed` (QC re-verify pass mới → `🟢 Closed`) | Khi tìm thấy bug/ticket, hoặc route một filed bug report. |
+| `/debug` | `/debug "NullPointerException ở LoginService"` | Debug session | Deep debugging. |
+| `/learn {text}` | `/learn "AI hay dùng var, phải dùng const"` | Appends guardrail vào project lessons file | Khi AI lặp lại lỗi bạn muốn chặn. |
+| `/generate-spec-manifest` | `/generate-spec-manifest` | `spec-manifest.yaml` | Sinh manifest làm entry point cho external/tester agents. |
 
 > **Project Lessons:** lessons lưu ở `paths.lessons_file` (default `specs/domain-knowledge/lessons-learned.md`; per-service `.agent/project-lessons.md` trong umbrella mode). Context-loader **Step 6.7** load mọi lesson đầu **mỗi** command như hard constraint. Đây là *project memory*, không phải fine-tuning model.
 
@@ -195,7 +198,7 @@ Load context theo thứ tự ưu tiên nghiêm ngặt (anti-lost-in-middle: fact
 | Step | Priority | What loads |
 |------|----------|-----------|
 | 1 | PROJECT-CONFIG | `project-context.yaml` → stack, conventions, domains, services, paths |
-| 1.5 | SERVICE ROUTING | *(umbrella only)* detect active domain, route `specs_dir`/`tech_docs_dir` → service submodule, store `service_root` |
+| 1.5 | SERVICE ROUTING | *(umbrella only)* detect active domain, route `trace_dir` (+ code) → service submodule, store `service_root`. Khi `spec_source` set: `specs_dir` (BDD) / `tech_docs_dir` / PRD / design-spec / domain-knowledge / feedback → **spec repo** (cross-team), KHÔNG per-service |
 | 1.6 | SERVICE CONVENTIONS | *(umbrella only)* load `{service_root}/.agent/project-context.yaml` → override `test_command`, `build_command`, `paths.trace_dir` |
 | 2 | PROJECT-CONFIG | `.agent/modules/{module}/stack-profile.yaml` → framework-specific layer patterns |
 | 3 | **CRITICAL** | `CLAUDE.md` → architecture layers, coding standards, naming |

package/docs/05-reference/modules.md

@@ -58,7 +58,7 @@ Ví dụ adapt theo platform type:
 
 ## qc-playwright — QC automation stack
 
-`qc-playwright` là **stack QC automation độc lập** với dev implementation module. Nó power native QC pipeline (`/qc-run-test`, `/qc-report`) và được chọn qua `tech_stack.qc_module` hoặc per `/qc-*` run — không phụ thuộc vào stack dev (java-spring, react, flutter…). Per-layer guides nằm ở `skills/qc/<stage>/`. Xem [../02-guides/qc-automation.md](../02-guides/qc-automation.md).
+`qc-playwright` là **stack QC automation độc lập** với dev implementation module. Nó power native QC pipeline (`/qc-run-test`, `/qc-report`) và được chọn qua `tech_stack.qc_module` hoặc per `/qc-*` run — không phụ thuộc vào stack dev (java-spring, react, flutter…). Per-layer guides nằm ở `skills/qc/<stage>/`. Xem [../02-guides/tester/qc-automation.md](../02-guides/tester/qc-automation.md).
 
 **Stack** (từ `modules/qc-playwright/stack-profile.yaml`): Python 3 + pytest-playwright + Page Object Model. Report = Playwright Trace + pytest-html (**không** dùng Allure, không hand-written dashboard, không `record_video`).
 
@@ -85,9 +85,9 @@ Ví dụ adapt theo platform type:
 
 **Folder structure:**
 ```
-docs/<project>/<feature>/   ← test-case Markdown (.Test.md) — source of truth
+{paths.qc_dir}/{UC-ID}/test-cases/ ← test-case Markdown (.Test.md) — source of truth (mặc định docs/, lộ ra ngoài)
 pages/                      ← Page Object Model (base_page.py + <feature>_page.py)
-tests/                      ← pytest scripts, 1-1 với docs/ (conftest.py + test_<feature>.py)
+tests/                      ← pytest scripts, 1-1 với test-cases/ (conftest.py + test_<feature>.py)
 utils/                      ← config_loader, logger, steps, test_ordering, report helpers
 test_data/                  ← JSON datasets
 config/config.yaml          ← browser, timeout, video/screenshot/trace toggles
@@ -107,4 +107,4 @@ reports/  test-results/     ← generated (gitignored): html report, trace.zip,
 
 ---
 
-*Xem thêm:* [Trace TSV Schema](trace-schema.md) (`qc_status` vs `dev_selftest`) · [Command Reference](commands.md) (pipeline `/qc-*`) · [02 · Guides · QC Automation](../02-guides/qc-automation.md).
+*Xem thêm:* [Trace TSV Schema](trace-schema.md) (`qc_status` vs `dev_selftest`) · [Command Reference](commands.md) (pipeline `/qc-*`) · [02 · Guides · QC Automation](../02-guides/tester/qc-automation.md).

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

@@ -22,10 +22,10 @@
 Tab-separated, một header row + một data row mỗi scenario. Header chính xác (từ `generate-bdd.tmpl`):
 
 ```
-sc_id	sc_title	spec_ver	gen_ver	implemented_by	test_count	test_classes	dev_selftest	dev_selftest_at	qc_status	qc_run_at	prd_version	bdd_version	tech_doc_revision	prd_status	uc_status	fe_phase	status	last_updated
+sc_id	sc_title	spec_ver	gen_ver	implemented_by	test_count	test_classes	dev_selftest	dev_selftest_at	qc_status	qc_run_at	qc_owner	qc_blocked_by	prd_version	bdd_version	tech_doc_revision	fe_tech_doc_revision	prd_status	uc_status	fe_phase	status	last_updated
 ```
 
-19 cột, theo đúng thứ tự trên.
+22 cột, theo đúng thứ tự trên.
 
 ---
 
@@ -44,16 +44,23 @@ sc_id	sc_title	spec_ver	gen_ver	implemented_by	test_count	test_classes	dev_selft
 | 9 | `dev_selftest_at` | Ngày chạy dev self-check (`YYYY-MM-DD`) | `—` | **dev-run-test** |
 | 10 | `qc_status` | Kết quả QC chính thức: `pass` / `fail` / `skip` / `not_run` | `—` | **qc-run-test** |
 | 11 | `qc_run_at` | Ngày chạy QC (`YYYY-MM-DD`) | `—` | **qc-run-test** |
-| 12 | `prd_version` | `@trace.prd_version` từ `.feature` header | từ `.feature` | generate-bdd |
-| 13 | `bdd_version` | `@trace.bdd_version` từ `.feature` header | từ `.feature` | generate-bdd |
-| 14 | `tech_doc_revision` | Tech-doc revision tại thời điểm codegen | `—` | generate-code |
-| 15 | `prd_status` | `\| **Status** \|` từ PRD metadata | từ PRD | generate-bdd |
-| 16 | `uc_status` | Trạng thái UC: `draft` / `approved` / … | `draft` (UC mới) | generate-bdd |
-| 17 | `fe_phase` | FE phase khi implement (`ui` / `integration`) | `—` | generate-code `--phase` |
-| 18 | `status` | Trạng thái tổng hợp: `OK` / `DRIFT` / `GAP` / `UNTRACKED` | `UNTRACKED` | validate-traces |
-| 19 | `last_updated` | Ngày update gần nhất (`YYYY-MM-DD`) | today | mọi command ghi row |
+| 12 | `qc_owner` | **Đang chờ ai** (PM view) khi SC chưa pass: `dev` / `po` / `—` | `—` | **qc-run-test** / **report-bug** |
+| 13 | `qc_blocked_by` | Artifact liên quan: `BUG-{id}` / `GAP-{id}` / `—` | `—` | **qc-run-test** / **report-bug** |
+| 14 | `prd_version` | `@trace.prd_version` từ `.feature` header | từ `.feature` | generate-bdd |
+| 15 | `bdd_version` | `@trace.bdd_version` từ `.feature` header | từ `.feature` | generate-bdd |
+| 16 | `tech_doc_revision` | **BE** API-contract revision tại thời điểm codegen | `—` | generate-code / review-tech-docs (BE doc) |
+| 17 | `fe_tech_doc_revision` | **FE** client tech-design revision (`{UC-ID}-tech-design-{platform}.md`) tại thời điểm FE integration | `—` | generate-code `--phase=integration` / review-tech-docs (FE doc) |
+| 18 | `prd_status` | `\| **Status** \|` từ PRD metadata | từ PRD | generate-bdd |
+| 19 | `uc_status` | Trạng thái UC: `draft` / `approved` / … | `draft` (UC mới) | generate-bdd |
+| 20 | `fe_phase` | FE phase khi implement (`ui` / `integration`) | `—` | generate-code `--phase` |
+| 21 | `status` | Trạng thái tổng hợp: `OK` / `DRIFT` / `GAP` / `UNTRACKED` | `UNTRACKED` | validate-traces |
+| 22 | `last_updated` | Ngày update gần nhất (`YYYY-MM-DD`) | today | mọi command ghi row |
 
-> **Re-generation rules (generate-bdd):** SC đã có trong TSV & `spec_ver` không đổi → chỉ update `sc_title`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated`. Nếu `spec_ver` đổi → thêm `spec_ver` và set `status = DRIFT` ngay. SC mới → append với `gen_ver`/`implemented_by`/`test_count`/`test_classes`/`dev_selftest`/`dev_selftest_at`/`qc_status`/`qc_run_at`/`tech_doc_revision` = `—`. SC bị xóa khỏi `.feature` → xóa row.
+> **`qc_owner` / `qc_blocked_by` (PM "waiting-on" view):** dành cho PO kiêm PM xem **case nào đang chờ ai**. `/qc-run-test` set khi ghi `qc_status`: product-gap FAIL → `qc_owner=dev`; `skip`/`not_run` do `DOC_GAPS` 🔴 Blocker mở → `qc_owner=po` + `qc_blocked_by=GAP-{id}`; `pass` → cả hai về `—`. `/report-bug` backfill `qc_blocked_by=BUG-{id}` (+ `qc_owner` theo layer) cho SC khớp. `/validate-traces` tổng hợp `waiting_dev` / `waiting_po` cho dashboard.
+
+> **Re-generation rules (generate-bdd):** SC đã có trong TSV & `spec_ver` không đổi → chỉ update `sc_title`, `prd_version`, `bdd_version`, `prd_status`, `uc_status`, `last_updated`. Nếu `spec_ver` đổi → thêm `spec_ver` và set `status = DRIFT` ngay. SC mới → append với `gen_ver`/`implemented_by`/`test_count`/`test_classes`/`dev_selftest`/`dev_selftest_at`/`qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by`/`tech_doc_revision`/`fe_tech_doc_revision` = `—`. SC bị xóa khỏi `.feature` → xóa row.
+
+> **Backward-compat:** TSV cũ thiếu cột mới ở header → `/validate-traces` đọc thành giá trị rỗng, không lỗi: `qc_owner`/`qc_blocked_by` (trước 19 cột) → `null`; `fe_tech_doc_revision` (trước 22 cột) → `0`. Lần `/generate-bdd` re-gen kế tiếp tự nâng header lên 22 cột.
 
 ---
 
@@ -85,7 +92,7 @@ Trace TSV mang **hai cột tín hiệu độc lập** — không bao giờ trộ
 | 3 | `DRIFT` | `spec_ver != gen_ver` (scenario đổi sau lần codegen gần nhất) |
 | 4 | `OK` | tất cả: `spec_ver == gen_ver`, `implemented_by != —`, `test_count > 0` |
 
-Ngoài ra `/validate-traces` còn flag **`PRD_DRIFT`** (PRD version trong code/TSV trễ hơn PRD file hiện tại) và **`TECHDOC_DRIFT`** (code sinh từ tech-doc revision cũ).
+Ngoài ra `/validate-traces` còn flag **`PRD_DRIFT`** (PRD version trong code/TSV trễ hơn PRD file hiện tại), **`TECHDOC_DRIFT`** (code BE sinh từ BE-contract revision cũ — so `tech_doc_revision`), và **`FE_TECHDOC_DRIFT`** (FE integration code sinh từ FE tech-design revision cũ — so `fe_tech_doc_revision`).
 
 ---
 
@@ -133,13 +140,13 @@ Per-scenario trong file: `# @trace.scenario: {UC-ID}-SC{N}`, `# @trace.sc_versio
 `/validate-traces` ghi `{paths.trace_dir}/trace-report.json` — single source of truth cho web dashboards. Cấu trúc rút gọn:
 
 - `generated_at`, `domain`
-- `summary` — aggregates: `total_prds`, `approved_prds`, `total_ucs`, `approved_ucs`, `draft_ucs`, `total_scs`, `coded_scs`, `tested_scs`, `code_coverage_pct`, `test_coverage_pct`, `drift_count`, `gap_count`, `untracked_count`, `dev_selftest_passing/failing/not_run`, `qc_passing/failing/skipped/not_run`, `tech_docs_count`
+- `summary` — aggregates: `total_prds`, `approved_prds`, `total_ucs`, `approved_ucs`, `draft_ucs`, `total_scs`, `coded_scs`, `tested_scs`, `code_coverage_pct`, `test_coverage_pct`, `drift_count`, `gap_count`, `untracked_count`, `dev_selftest_passing/failing/not_run`, `qc_passing/failing/skipped/not_run`, `waiting_dev`, `waiting_po`, `tech_docs_count`
 - `prds[]` → `ucs[]` → `scenarios[]` — mỗi scenario có đầy đủ các trường của TSV row (gồm `dev_selftest`, `dev_selftest_at`, `qc_status`, `qc_run_at`)
-- `issues` — phân loại: `drift`, `gap`, `untracked`, `prd_version_drift`, `techdoc_drift`, mỗi entry kèm `fix` command gợi ý
+- `issues` — phân loại: `drift`, `gap`, `untracked`, `prd_version_drift`, `techdoc_drift`, `fe_techdoc_drift` (kèm `platform`), mỗi entry kèm `fix` command gợi ý
 
-**TSV `"—"` → JSON mapping:** `implemented_by: "—"` → `null` · `test_count: "—"` → `0` · `test_classes: "—"` → `[]` · `tech_doc_revision: "—"` → `0` · `dev_selftest: "—"` → `"not_run"` · `dev_selftest_at: "—"` → `null` · `qc_status: "—"` → `"not_run"` · `qc_run_at: "—"` → `null`.
+**TSV `"—"` → JSON mapping:** `implemented_by: "—"` → `null` · `test_count: "—"` → `0` · `test_classes: "—"` → `[]` · `tech_doc_revision: "—"` → `0` · `fe_tech_doc_revision: "—"` → `0` · `dev_selftest: "—"` → `"not_run"` · `dev_selftest_at: "—"` → `null` · `qc_status: "—"` → `"not_run"` · `qc_run_at: "—"` → `null`.
 
-> **Umbrella mode:** mỗi service submodule giữ `.trace/` riêng (committed). `/validate-traces` (hoặc `/sync`) publish merged report vào `{spec_source}/.living-docs/` (canonical) + mirror `./.trace/trace-report.json` ở workspace hiện tại. Cả hai là generated mirror — gitignore, không commit.
+> **Umbrella mode:** khi `spec_source` set, `.trace/*.tsv` authoritative nằm **một chỗ** ở `{spec_source}/.trace/` (committed — PM quản lý tập trung; mỗi scenario mang `@trace.service`). `/validate-traces` (hoặc `/sync`) sinh `trace-report.json` vào `{spec_source}/.living-docs/` + mirror `./.trace/trace-report.json` ở workspace hiện tại — cả hai generated, gitignore. (Không có `spec_source` → `.trace` per-service.)
 
 ---
 

package/docs/README.md

@@ -10,8 +10,7 @@ Tài liệu được chia theo **vai trò** và **chủ đề**. Bắt đầu
 | Người mới / cài đặt lần đầu | [01 · Getting Started](01-getting-started/) |
 | Product Owner | [Guide · Product Owner](02-guides/product-owner/README.md) |
 | Developer | [Guide · Developer](02-guides/developer/README.md) |
-| Tester | [Guide · Tester](02-guides/tester/README.md) |
-| QC Automation | [Guide · QC Automation](02-guides/qc-automation.md) |
+| QC / Tester (QA) | [Guide · Tester / QA](02-guides/tester/README.md) — gồm cả pipeline QC tự động (`/qc-*`) |
 | Muốn hiểu kiến trúc | [03 · Concepts](03-concepts/) |
 | Vận hành / admin | [04 · Operations](04-operations/) |
 | Tra cứu lệnh | [05 · Reference](05-reference/) |
@@ -28,8 +27,7 @@ Tài liệu được chia theo **vai trò** và **chủ đề**. Bắt đầu
 ### 02 · [Guides (theo vai trò)](02-guides/)
 - [Product Owner](02-guides/product-owner/README.md) — define-product, PRD, design-spec, review
 - [Developer](02-guides/developer/README.md) — BDD, tech-docs, code, dev self-check
-- [Tester](02-guides/tester/README.md) — spec-manifest, report-bug, propose-scenario, Living Docs
-- [QC Automation](02-guides/qc-automation.md) — pipeline `/qc-*`, qc_status
+- [Tester / QA](02-guides/tester/README.md) — spec-manifest, report-bug, propose-scenario, Living Docs, và **chương [QC Automation](02-guides/tester/qc-automation.md)** (pipeline `/qc-*`, `qc_status`)
 
 ### 03 · [Concepts](03-concepts/)
 - [Architecture](03-concepts/architecture.md) — layers, modules, plug-in system
@@ -48,4 +46,4 @@ Tài liệu được chia theo **vai trò** và **chủ đề**. Bắt đầu
 
 ---
 
-*Mỗi file có breadcrumb điều hướng ở đầu. Phiên bản framework: xem `core/FRAMEWORK_VERSION`.*
+*Mỗi file có breadcrumb điều hướng ở đầu. Phiên bản framework mới nhất: xem trên [npm](https://www.npmjs.com/package/@anhth2/spec-driven-dev-plugin).*

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

@@ -19,14 +19,15 @@ architecture:
     - "Each test independent via pytest-playwright fixtures (page / logged_in_page / …)"
     - "Page Object extends slim BasePage; split 3 layers: locators _x(), actions verb_noun(), assertions assert_x() using expect()"
     - "Locator priority: data-testid → role → label/text → CSS → avoid XPath"
+    - "test-id values come from the FE tech-design §2b Test Selectors contract ({UC-ID}-tech-design-{platform}.md) — prefer them (no runtime scan); fall back to role/text only when an actionable element has no test-id there, and note the gap"
     - "Group tests by (role, account) so login/logout never interleaves across roles"
     - "Cover 100% of TCs in the .Test.md — every TC ends Pass/Fail/Skip, none left Draft"
   folder_structure: |
-    docs/<project>/<feature>/      ← test-case Markdown (.Test.md) — source of truth
+    {paths.qc_dir}/{UC-ID}/test-cases/   ← test-case Markdown (.Test.md) — source of truth (mặc định docs/, lộ ra ngoài)
     pages/                         ← Page Object Model
     │   ├── base_page.py           ← slim BasePage (click/fill/wait/screenshot)
     │   └── <feature>_page.py
-    tests/                         ← pytest scripts, 1-1 with docs/
+    tests/                         ← pytest scripts, 1-1 with test-cases/
     │   ├── conftest.py            ← fixtures: browser, page, logged_in_page, tracing
     │   └── <project>/test_<feature>.py
     utils/                         ← config_loader, logger, steps, test_ordering, report helpers
@@ -41,7 +42,7 @@ coding_standards:
     test_function: "test_TC<NNN>_<snake_case>"
     page_object: "<feature>_page.py with <Feature>Page class extending BasePage"
     files:
-      test_case_md: "docs/<project>/<feature>/TC_<FEATURE>.Test.md"
+      test_case_md: "{paths.qc_dir}/{UC-ID}/test-cases/TC_<FEATURE>.Test.md"
       page_object: "pages/<feature>_page.py"
       test_script: "tests/<project>/test_<feature>.py"
   patterns:

package/package.json

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

package/skills/code/SKILL.md

@@ -152,6 +152,8 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.specs_dir` → BDD specs root
 - `paths.prd_dir` → PRD documents root
 - `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
 - `paths.product_definitions_dir` → product definitions root
 - `paths.domain_knowledge_dir` → domain knowledge root
 - `paths.business_dictionary` → path to business-dictionary.md
@@ -164,6 +166,8 @@ If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
 - `prd_dir` = `specs/prd`
 - `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
 - `product_definitions_dir` = `specs/product-definition`
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
@@ -189,7 +193,7 @@ If `services` section is present:
 - If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
 
 **2. Route to service** — if active domain matches a key in `services`:
-- Override `paths.specs_dir` → `services.{domain}.specs_dir`
+- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, ALL BDD (web/app/**system**) is a shared cross-team artifact → leave `specs_dir` for step 4 to route to the spec repo; do NOT pin it per-service here.
 - Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, the tech-design (API contract) is a cross-team artifact and must live in the shared spec repo (handled in step 4), so leave `tech_docs_dir` for step 4 to route — do NOT pin it per-service here.
 - Store `active_service` = `services.{domain}.path`
 - Store `active_service_module` = `services.{domain}.module`
@@ -200,6 +204,7 @@ If `services` section is present:
 - Set `active_service = unresolved`
 
 **4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
+- Override `paths.specs_dir` → `{spec_source}/specs/bdd` — **always when `spec_source` is set.** All BDD (web/app/**system**) lives in the shared spec repo so every umbrella (FE/App/BE) reads the same scenarios; the FE tech-design gate + `/generate-code --phase=ui`/`--phase=integration` resolve the `system/` BDD here. *(Per-service `specs/bdd` only when there is no `spec_source`.)*
 - Override `paths.prd_dir` → `{spec_source}/specs/prd`
 - Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
 - Override `paths.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
@@ -208,8 +213,10 @@ If `services` section is present:
 - Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
+- Override `paths.trace_dir` → `{spec_source}/.trace` — **always when `spec_source` is set.** Trace TSVs are consolidated in the spec repo (single authoritative location, no per-service split) so the PM/PO has one place to manage status. Code-side commands (`/generate-code`, `/dev-run-test`, `/qc-run-test`) run from `service_root` but **write their trace row into `{spec_source}/.trace`** — like they already push `feedback/` there. *(Per-service `.trace` only when there is no `spec_source`.)*
 
-> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, **all BDD (web/app/system)**, the **API contract (tech-docs)**, tester feedback, **and the `.trace/` coverage state** are all **cross-team artifacts** — they live in the **shared spec repo** so every umbrella (FE/App/BE) and the PM read one source via `/sync`. The service submodule holds only **code** (+ build/test tooling). `.trace/` and `feedback/` are the dev/QC **write areas** in the spec repo (the PRD/BDD/design-spec/tech-docs there stay read-only for dev/QC — only PO edits those). In single-service mode (no `spec_source`), everything defaults under the repo root — still one repo.
 
 ---
 
@@ -229,12 +236,12 @@ When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-
 |----------|--------|
 | `conventions.test_command` | service's `conventions.test_command` |
 | `conventions.build_command` | service's `conventions.build_command` |
-| `paths.trace_dir` | `{active_service}/{service paths.trace_dir}` — default: `{active_service}/.trace` |
-| `paths.specs_dir` | `{active_service}/{service paths.specs_dir}` (if set in service config, else keep Step 1.5 override) |
+| `paths.trace_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/.trace`); ignore any service-level `trace_dir`.** Only when there is no `spec_source`: `{active_service}/{service paths.trace_dir}` (default `{active_service}/.trace`). |
+| `paths.specs_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/specs/bdd`); ignore any service-level `specs_dir`** (BDD is cross-team, never per-service in this mode). Only when there is no `spec_source`: `{active_service}/{service paths.specs_dir}` if set, else the Step 1.5 override. |
 
 **3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
 - Shell commands (`/dev-run-test`, `/dev-gen-test`) run **from within** `service_root`
-- File write operations (test files, trace TSVs) use paths **relative to** `service_root`
+- **Source/test files** are written relative to `service_root`; **trace TSVs** are written to `{paths.trace_dir}` (the spec repo when `spec_source` is set — a cross-repo write, committed/pushed to the spec submodule like `feedback/`).
 
 **4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
 
@@ -513,6 +520,36 @@ Output Artifacts:
 
 If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
 
+## Pipeline Position
+
+Print a one-line map of the pipeline with the CURRENT command's phase marked `◀ bạn ở đây`,
+so the user always sees where this command sits in the end-to-end flow:
+
+```
+Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+```
+
+Find the current command in this phase legend and mark **its** phase in the map above:
+
+| Phase | Commands |
+|-------|----------|
+| Discovery | `/define-product` |
+| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| Design Spec | `/generate-design-spec` |
+| BDD | `/generate-bdd` · `/review-context` (BDD) |
+| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
+| Code | `/generate-code` · `/review-code` |
+| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
+| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
+| Trace Audit | `/validate-traces` |
+
+For a **review command**, also append the 3-step review loop with the current step marked, e.g.:
+`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
+
+**Cross-cutting commands** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
+`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) sit outside the linear pipeline —
+**omit the Pipeline line entirely** for these (do not force-fit them onto the map).
+
 ## Next Command Suggestion
 
 Suggest the logical next command based on workflow phase:
@@ -554,10 +591,13 @@ Suggest the logical next command based on workflow phase:
 Format the footer as:
 ```
 ---
-Status : {badge}
+Status   : {badge}
 {Output Artifacts block}
-Next   : {suggested command with example arguments}
+Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+           (review cmd) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
+Next     : {suggested command with example arguments}
 ```
+*(Omit the `Pipeline` line for cross-cutting commands listed above.)*
 
 
 ---
@@ -638,6 +678,36 @@ Output Artifacts:
 
 If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
 
+## Pipeline Position
+
+Print a one-line map of the pipeline with the CURRENT command's phase marked `◀ bạn ở đây`,
+so the user always sees where this command sits in the end-to-end flow:
+
+```
+Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+```
+
+Find the current command in this phase legend and mark **its** phase in the map above:
+
+| Phase | Commands |
+|-------|----------|
+| Discovery | `/define-product` |
+| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| Design Spec | `/generate-design-spec` |
+| BDD | `/generate-bdd` · `/review-context` (BDD) |
+| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
+| Code | `/generate-code` · `/review-code` |
+| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
+| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
+| Trace Audit | `/validate-traces` |
+
+For a **review command**, also append the 3-step review loop with the current step marked, e.g.:
+`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
+
+**Cross-cutting commands** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
+`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) sit outside the linear pipeline —
+**omit the Pipeline line entirely** for these (do not force-fit them onto the map).
+
 ## Next Command Suggestion
 
 Suggest the logical next command based on workflow phase:
@@ -679,8 +749,11 @@ Suggest the logical next command based on workflow phase:
 Format the footer as:
 ```
 ---
-Status : {badge}
+Status   : {badge}
 {Output Artifacts block}
-Next   : {suggested command with example arguments}
+Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+           (review cmd) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
+Next     : {suggested command with example arguments}
 ```
+*(Omit the `Pipeline` line for cross-cutting commands listed above.)*