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

package/core/steps/context-loader.md

@@ -36,6 +36,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
@@ -48,6 +50,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`
@@ -73,7 +77,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`
@@ -84,6 +88,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.)*
@@ -92,8 +97,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.
 
 ---
 
@@ -113,12 +120,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).
 

package/core/steps/report-footer.md

@@ -20,6 +20,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:
@@ -61,7 +91,10 @@ 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.)*

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

@@ -36,6 +36,21 @@ paths:
   prd_template: "specs/templates/prd.template.md"
   refinement_dir: ".agent/review"
 
+  # QC's OWN analysis/design working docs (qc-analyze/plan/design-test outputs:
+  # REQUIREMENT_ANALYSIS.md, DOC_GAPS.md, TEST_PLAN.md, test-cases/*.Test.md).
+  # One subfolder per UC: {qc_dir}/{UC-ID}/. Default "docs" (the QC team's own
+  # convention), VISIBLE — not hidden under .agent/. NOTE: specs (PRD / .feature /
+  # design-spec) are NOT here — they come from the PO spec submodule (spec_source).
+  qc_dir: "docs"
+
+  # WHERE the qc-* commands LOAD their skills from (qa-analyst / qa-designer / qa-planner
+  # / qa-reviewer / qa-runner + DOC_GAPS.template.md). Default = the framework-bundled
+  # copy at .agent/skills/qc (works standalone). The QC team OWNS these skills in their
+  # canonical repo (ai-automation-qc-base) — point this at that repo/submodule (e.g.
+  # "qc-base/.claude/skills") so the skills evolve INDEPENDENTLY and are NOT overwritten
+  # by framework upgrade (--init / upgrade.sh rewrite only .agent/, never this path).
+  qc_skills_dir: ".agent/skills/qc"
+
   # Product Definitions
   product_definitions_dir: "specs/product-definition"
   product_definition_template: "specs/templates/product-definition.template.md"
@@ -61,11 +76,14 @@ paths:
   # Trace
   trace_dir: ".trace"
 
-  # Tester feedback (written by /report-bug and /propose-scenario).
+  # Tester / QC feedback (written by /report-bug and /propose-scenario).
   # These live in the SHARED spec repo so PO/Dev see them on their next /sync.
   # In umbrella mode, context-loader auto-resolves them under {spec_source}/feedback/.
   bug_reports_dir: "feedback/bug-reports"
   bdd_proposals_dir: "feedback/bdd-proposals"
+  # PRD change requests (new requirement found in test, not covered by any AC) —
+  # written by /propose-scenario Case B so the PO can add/extend an AC then re-/generate-bdd.
+  prd_change_requests_dir: "feedback/prd-change-requests"
 
 tech_stack:
   language: "{{LANGUAGE}}"              # e.g., Java 17 / TypeScript / C# / Go
@@ -93,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

@@ -89,6 +89,8 @@ 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/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)
 
@@ -102,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ị)
 
@@ -130,7 +132,7 @@ Mở Review Board: sidebar panel (Activity Bar), hoặc right-click file `*-find
 Đọc `.trace/*.tsv` — dashboard traceability health toàn project.
 
 - Stat cards: PRDs, Use Cases, Scenarios, Code Cov%, Test Cov%, Drift, Gap.
-- Drill-down: PRD → UC → per-scenario table (Spec ver, Gen ver, Code, Tests, `dev_selftest`, `qc_status`, Status).
+- Drill-down: PRD → UC → per-scenario table (Spec ver, Gen ver, Code, Tests, `dev_selftest`, `qc_status`, Waiting on, Status). *Waiting on* = `qc_owner` + `qc_blocked_by` (chờ dev → `BUG-{id}` / chờ PO → `GAP-{id}`).
 - Status badges: ✅ OK · ⚠️ DRIFT · 🔴 GAP · — UNTRACKED. Filter + search + live reload.
 
 Mở: `Ctrl+Shift+P` → **"Spec Driven Dev: Open Living Documentation"**. Mở được cả ở umbrella root lẫn trong một service submodule riêng lẻ. Nếu trống, chạy `/generate-bdd` cho ≥1 feature để tạo file `.trace/{UC-ID}.tsv` đầu tiên.

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).
 
@@ -56,7 +56,7 @@ Dev hành động theo phân loại:
 - **Scenario proposal map vào AC sẵn có** → thêm scenario vào `.feature` (hoặc `/generate-bdd` lại), rồi `/generate-code` + `/dev-gen-test`
 - **Proposal là yêu cầu mới (PRD change request)** → chuyển PO sửa PRD trước
 
-> Bug reports có thể đến từ hai nguồn: Tester dùng `/report-bug` trực tiếp, **hoặc** từ kết quả QC automation (`qc_status: fail` trong `.trace/*.tsv` → tester chạy `/report-bug` → `/sync` → dev thấy tại đây). Cả hai đều dùng cùng luồng `/fix-bug`.
+> Bug reports có thể đến từ hai nguồn: Tester dùng `/report-bug` trực tiếp, **hoặc** từ kết quả QC automation (`qc_status: fail` trong `.trace/*.tsv` → QC (hoặc tester) chạy `/report-bug` → `/sync` → dev thấy tại đây). Cả hai đều dùng cùng luồng `/fix-bug`.
 
 > Tester chỉ *đề xuất* trong `feedback/` — dev/PO mới đưa vào BDD chính thức. Giữ đúng ownership.
 

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