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

package/docs/02-guides/qc-automation.md

@@ -0,0 +1,157 @@
+[📚 Docs](../README.md) › [Guides](README.md) › QC Automation
+
+# Hướng Dẫn QC Automation — Spec-Driven Dev
+
+Pipeline QC automation **chính thức** của framework — được port từ agent của team QC (reference repo `ai-automation-qc-base`) vào ngay trong framework. Nó sinh và chạy automation **Playwright/pytest** từ BDD `.feature` chính thức, rồi ghi tín hiệu **`qc_status`** (authoritative) vào trace TSV → Living Docs.
+
+## Mục Lục
+
+- [Hai luồng test: dev self-check vs QC chính thức](#hai-luồng-test-dev-self-check-vs-qc-chính-thức)
+- [Pipeline 6 bước](#pipeline-6-bước)
+- [Stack — module qc-playwright](#stack--module-qc-playwright)
+- [Trace join: qc_status đến Living Docs như thế nào](#trace-join-qc_status-đến-living-docs-như-thế-nào)
+- [Entry point](#entry-point)
+- [Skills theo layer](#skills-theo-layer)
+
+## Hai Luồng Test: Dev Self-Check vs QC Chính Thức
+
+Pipeline QC này **khác** với developer **self-check** (`/dev-gen-test`, `/dev-run-test`, `/dev-smoke-test`):
+
+| Signal | Owner | Command | Ý nghĩa |
+|--------|-------|---------|---------|
+| `dev_selftest` | Dev | `/dev-run-test` | smoke check của riêng dev (KHÔNG authoritative) |
+| `qc_status` | QC | `/qc-run-test` | kết quả QC automation **chính thức** |
+
+Cả hai hiển thị **cạnh nhau** trong Living Docs; không cái nào ghi đè cái nào. `dev_selftest: pass` chỉ nghĩa "dev đã tự smoke qua"; coverage chính thức nằm ở `qc_status`.
+
+## Pipeline 6 Bước
+
+```
+/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report
+ (requirement   (risk/plan   (test-case      (review     (gen+run     (report +
+  breakdown)     + Q-for-dev)  .Test.md)       gate)       Python →     evidence)
+                                                            qc_status)
+```
+
+| Command | Vai trò | Output |
+|---------|---------|--------|
+| `/qc-analyze` | bóc tách spec chính thức thành **1 file phân tích gộp** (requirement + BR/AC + data-flow) + `DOC_GAPS` | `{qc_dir}/{UC-ID}/` → `REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md` (**2 file**) |
+| `/qc-plan` | risk / what-if / questions-for-dev + test plan | `TEST_PLAN.md` |
+| `/qc-design-test` | thiết kế test case (Markdown `.Test.md`), tag `@trace.verifies={UC-ID}-SC{N}` | `test-cases/` |
+| `/qc-review` | cổng review hai chiều: review test case (sau design) và script (sau run) | findings |
+| `/qc-run-test` | sinh + chạy Python pytest-playwright; **ghi `qc_status`** per scenario | `{trace_dir}/{UC-ID}.tsv` |
+| `/qc-report` | report pytest-html + Playwright trace + evidence | `reports/<feature>/report.html` |
+
+> **Nơi lưu artifact (`qc_dir`):** mọi output của pipeline (trừ report) nằm trong thư mục QC
+> **lộ ra ngoài** `{qc_dir}/{UC-ID}/` — mặc định `docs/{UC-ID}/`, cấu hình qua `paths.qc_dir`
+> trong `project-context.yaml`. Đây là **working-doc riêng của QC** trong repo QC, **không ẩn**
+> (KHÔNG nằm trong `.agent/`). Spec gốc (PRD/`.feature`/design-spec) KHÔNG nằm đây — chúng đến
+> từ **submodule spec của PO** (`spec_source`). `/qc-analyze` chỉ ghi **đúng 2 file**:
+> `REQUIREMENT_ANALYSIS.md` (phân tích gộp) + `DOC_GAPS.md`.
+
+## Stack — Module qc-playwright
+
+`/qc-run-test` và `/qc-report` dùng stack module `qc-playwright`
+(`.agent/modules/qc-playwright/stack-profile.yaml`): **Python + pytest-playwright + Page
+Object** (slim `BasePage`, 3-layer), **Playwright Trace + pytest-html** (KHÔNG Allure). Stack
+này độc lập với module implementation của dev (java-spring, react, flutter, …).
+
+Per-layer guides chi tiết nằm trong `skills/qc/<stage>/` (port từ skills của agent QC):
+functional / integration / e2e / non-functional / exploratory.
+
+## Trace Join: qc_status Đến Living Docs Như Thế Nào
+
+1. `.feature` chính thức định nghĩa scenario là `@trace.scenario={UC-ID}-SC{N}`.
+2. `/qc-design-test` ghi SC mà test case thuộc về; `/qc-run-test` tag mỗi pytest test
+   `# @trace.verifies={UC-ID}-SC{N}`.
+3. `/qc-run-test` ghi `qc_status` (`pass|fail|skip|not_run`) + `qc_run_at` vào trace TSV của
+   service (authoritative), rồi refresh panel mirror local.
+4. `/validate-traces` (hoặc `/sync`) tổng hợp các TSV thành report Living Docs tại
+   `{spec_source}/.living-docs/` — dashboard hiển thị `qc_status` cạnh `dev_selftest`.
+
+## Entry Point
+
+Pipeline QC bắt đầu ngay khi BDD của một UC được approved (`/review-context (BDD)` APPROVED):
+
+```
+/qc-analyze {UC-ID}   →  … → /qc-report {UC-ID}  →  /validate-traces {UC-ID}
+```
+
+## Skills Theo Layer
+
+Các skill chi tiết theo từng giai đoạn QC nằm trong `skills/qc/`:
+
+| Stage skill | Vai trò |
+|---|---|
+| `qa-analyst` | phân tích requirement, sinh `DOC_GAPS` |
+| `qa-planner` | test plan, risk, questions-for-dev |
+| `qa-designer` | thiết kế test case `.Test.md` theo layer (functional / integration / e2e / non-functional / exploratory) |
+| `qa-reviewer` | cổng review test case và script |
+| `qa-runner` | sinh + chạy Python pytest-playwright, sinh report (Playwright Trace + pytest-html) |
+
+Mỗi skill **tự chứa** (self-contained) và có version frontmatter để theo dõi khi nâng cấp.
+
+## Khi QC Tìm Thấy Bug / Spec Gap — Đẩy Lên Specs
+
+QC chạy pipeline nhưng **không tự sửa spec/code**. Khi phát hiện vấn đề, đẩy lên spec repo của PO
+qua flow feedback có sẵn (`/report-bug` · `/propose-scenario` — PO/Dev nhận khi `/sync`):
+
+| QC phát hiện ở | Loại | Hành động |
+|---|---|---|
+| `/qc-run-test` FAIL = **product-gap** (impl ≠ spec, lỗi thật) | bug | `/report-bug {UC-ID} {expected vs actual}` |
+| `/qc-run-test` FAIL = **script-bug** (sai selector/logic script) | — | QC tự sửa script + chạy lại (**KHÔNG** file bug) |
+| `/qc-analyze` `DOC_GAPS` blocker = **spec sai / mơ hồ / mâu thuẫn** (PRD·BDD) | spec defect | `/report-bug {UC-ID}` (BUG_FLOW phân loại PRD/BDD) |
+| `/qc-analyze` `DOC_GAPS` = **thiếu coverage** (behavior trong AC nhưng chưa có scenario) | coverage gap | `/propose-scenario {UC-ID}` |
+| `DOC_GAPS` = `ASSUMPTION` / `OPEN QUESTION` | câu hỏi | qc-plan → questions-for-dev (xác nhận với PO/Dev, không file bug) |
+
+`/report-bug` ghi `feedback/bug-reports/BUG-xxx.md` + commit/push lên spec repo; `/propose-scenario`
+ghi `feedback/bdd-proposals/`. PO/Dev thấy khi `/sync`, rồi BUG_FLOW định tuyến root cause:
+
+```
+• Code bug       → Dev /fix-bug                                  (KHÔNG đổi spec)
+• BDD sai / thiếu → sửa .feature / promote proposal → /generate-bdd
+• PRD mơ hồ / sai → PO sửa PRD → /refine-prd → /review-context → /generate-bdd
+        ↓ (nếu spec đổi → regenerate)
+  /generate-code lại  →  QC /qc-run-test lại  →  qc_status: fail → pass
+```
+
+> QC chỉ **đọc** spec (từ submodule PO) — mọi thay đổi PRD/BDD là việc của PO/Dev. QC đẩy *tín hiệu*
+> (bug / proposal / gap), không tự sửa canonical spec. `/qc-report` ở cuối pipeline **in sẵn** danh
+> sách lệnh `/report-bug` cho từng product-gap để QC chạy. Chi tiết flow bug: [Operations · Bug Flow](../04-operations/bug-flow.md).
+
+## Skill Sourcing & Upgrade-Safety
+
+Các skill QC (`qa-analyst` / `qa-designer` / `qa-planner` / `qa-reviewer` / `qa-runner` +
+`DOC_GAPS.template.md`) **không bị hardcode** — command nạp chúng từ `paths.qc_skills_dir`:
+
+| Tình huống | `qc_skills_dir` | Hệ quả khi `/update-framework` |
+|---|---|---|
+| Mặc định (standalone) | `.agent/skills/qc` (bản framework bundle) | **Bị ghi đè** mỗi lần upgrade → đừng sửa trực tiếp ở đây |
+| QC sở hữu skill (khuyến nghị) | repo QC / submodule, vd `qc-base/.claude/skills` | **Không bao giờ bị đụng** — upgrade chỉ rewrite `.agent/` |
+
+> `qc_skills_dir` chỉ cần trỏ tới thư mục **chứa các folder `qa-*`**. Cả 2 layout đều hợp lệ:
+> framework bundle (`.agent/skills/qc/qa-analyst/…`) và repo QC (`.claude/skills/qa-analyst/…`).
+
+**Cách QC tách skill ra khỏi vòng đời framework:**
+
+```bash
+# 1. Đưa repo skill của QC vào project (submodule để pin version):
+git submodule add <ai-automation-qc-base-repo-url> qc-base
+
+# 2. Trỏ qc_skills_dir trong .agent/project-context.yaml:
+#    paths:
+#      qc_skills_dir: "qc-base/.claude/skills"
+
+# 3. Từ giờ: QC hoàn thiện skill trong repo qc-base, bump submodule khi cần.
+#    /update-framework ghi đè .agent/ nhưng KHÔNG chạm qc-base/ → skill an toàn.
+```
+
+Nhờ vậy **vòng đời skill QC** và **vòng đời framework** tách hẳn nhau: nâng cấp framework
+không nuốt mất skill đang hoàn thiện, và QC update skill 1 chỗ (repo của họ) cho mọi project.
+
+## Xem Thêm
+
+- [Guide › Tester](tester/README.md) — vai trò tester, spec-manifest, `/report-bug`, `/propose-scenario`
+- [Concepts › Traceability](../03-concepts/traceability.md) — trace TSV, dev_selftest vs qc_status
+- [Reference › Modules](../05-reference/modules.md) — chi tiết module `qc-playwright`
+- [Reference › Commands](../05-reference/commands.md) — danh mục đầy đủ mọi command

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

@@ -0,0 +1,74 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › Tester / QA
+
+# Hướng Dẫn Tester — Spec-Driven Dev
+
+Tài liệu dành cho **QA / Tester** — cách kết nối với spec framework, workflow kiểm thử, và các tình huống thực tế.
+
+## Mục Lục
+
+| Trang | Nội dung |
+|---|---|
+| [Spec Manifest & Setup](spec-manifest.md) | Spec manifest là gì · setup tester agent · Living Docs panel |
+| [Workflow](workflow.md) | Luồng làm việc cơ bản từ nhận task đến pass/fail |
+| [Đọc Spec Chain](reading-specs.md) | Thứ tự đọc PRD → BDD → Tech Docs · ví dụ thực tế |
+| [Tình huống thực tế](scenarios.md) | 6 scenario: feature mới, PRD thay đổi, multi-service, regression, ... |
+| [Báo cáo bug](bug-reporting.md) | `/report-bug` · `/propose-scenario` · template báo cáo |
+| [Checklist test pass](test-checklist.md) | Checklist trước khi báo "test pass" |
+
+## Vai Trò Tester Trong Framework
+
+```
+PO/BA          Dev                    Tester
+──────────     ──────────────────     ──────────────────────────
+PRD            BDD (từ PRD)           /sync + /generate-spec-manifest
+               Tech Docs              Đọc PRD + BDD + Tech Docs
+               Code                   Viết test cases · Chạy test
+   ▲              ▲                    /report-bug      (bug → spec-traced)
+   │              │                    /propose-scenario (edge case → BDD draft)
+   └──────────────┴───── feedback/ trong spec repo ◄────┘
+        PO/Dev thấy qua /sync (📥) → fix / promote / update PRD
+```
+
+**Tester chịu trách nhiệm:**
+- Đọc PRD để hiểu business requirement trước khi test
+- Đọc BDD để biết chính xác scenarios cần cover
+- Đọc Tech Docs để hiểu API contracts và data flow
+- Viết test cases dựa trên BDD scenarios
+- Khi bug xảy ra: `/report-bug` → tạo bug report có spec-context đầy đủ, phân loại layer
+- Khi phát hiện edge case chưa có trong BDD: `/propose-scenario` → đề xuất cho PO/Dev duyệt
+
+**Tester KHÔNG làm:**
+- Sửa PRD / BDD / Tech Docs trực tiếp — đó là việc của PO và Dev
+- Approve PRD — chỉ PO
+- Generate code — chỉ Dev
+
+> **Lưu ý về `/propose-scenario`:** lệnh này **không** sửa BDD. Nó chỉ ghi một bản *đề xuất* (draft Gherkin) vào vùng `feedback/bdd-proposals/` của spec repo dùng chung. PO/Dev review và đưa vào `.feature` chính thức.
+
+## Commands Dành Cho Tester
+
+| Command | Mục đích | Khi nào dùng |
+|---|---|---|
+| `/generate-spec-manifest` | Tạo index TICKET-ID → PRD/BDD/tech-doc | Trước mỗi sprint, sau khi pull specs mới |
+| `/report-bug {UC-ID} {mô tả}` | Tạo bug report có spec-context + phân loại layer (read-only) | Khi test fail / phát hiện bug |
+| `/propose-scenario {UC-ID} {mô tả}` | Đề xuất scenario BDD mới cho edge case chưa cover | Khi tìm thấy case ngoài BDD hiện có |
+
+**QC Automation Pipeline (chính thức) — 6 lệnh `/qc-*`:**
+
+| Command | Mục đích | Khi nào dùng |
+|---|---|---|
+| `/qc-analyze` | Phân tích spec chain (PRD + BDD + Tech Docs), xác định scope test | Bước 1, sau khi BDD đã approved |
+| `/qc-plan` | Lập test plan: liệt kê scenarios, layer, ưu tiên | Bước 2 |
+| `/qc-design-test` | Thiết kế test case chi tiết (Page Object, data, assertions) | Bước 3 |
+| `/qc-review` | Review test design trước khi code automation | Bước 4 |
+| `/qc-run-test` | Chạy automation test → ghi `qc_status` per scenario vào trace TSV | Bước 5 |
+| `/qc-report` | Tổng hợp kết quả thành QC report | Bước 6 |
+
+Đây là **bộ test chính thức (authoritative) của QC**, chạy ngay trong framework. Pipeline dùng stack module `qc-playwright` (Python + pytest-playwright + Page Object). Xem chi tiết flow tại **[QC Automation guide](../qc-automation.md)**.
+
+> **Artifact ra đâu:** `/qc-analyze` ghi **2 file** (`REQUIREMENT_ANALYSIS.md` + `DOC_GAPS.md`), `/qc-plan` → `TEST_PLAN.md`, `/qc-design-test` → `test-cases/*.Test.md` — tất cả trong `{qc_dir}/{UC-ID}/` (mặc định `docs/`, **visible**, không phải `.agent/` ẩn). Skill QC nạp từ `paths.qc_skills_dir` — trỏ được tới repo QC để skill **không bị `/update-framework` ghi đè**. Chi tiết: [QC Automation guide](../qc-automation.md#skill-sourcing--upgrade-safety).
+
+> **Phân biệt với test commands của Dev:** `/dev-gen-test`, `/dev-run-test`, `/dev-smoke-test` là **dev tự kiểm tra code của mình** — phát tín hiệu `dev_selftest`, KHÔNG phải bộ test chính thức. Bộ test authoritative của QC là pipeline `/qc-*` (sinh ra `qc_status`). Hai luồng tách biệt.
+
+---
+
+*Xem thêm:* [Developer Guide](../developer/README.md) · [QC Automation Guide](../qc-automation.md) · [Operations › Bug Flow](../../04-operations/bug-flow.md) · [Reference › Commands](../../05-reference/commands.md)

package/docs/02-guides/tester/bug-reporting.md

@@ -0,0 +1,117 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Tester](README.md) › Báo cáo bug
+
+# Khi Tìm Thấy Bug — Quy Trình Trace
+
+Khi test fail, báo cáo phải có đủ **spec context** để Dev fix đúng chỗ.
+
+## Cách nhanh nhất: `/report-bug`
+
+```bash
+/report-bug FT-001 tài khoản khoá sau 6 lần sai, spec ghi 5
+```
+
+Lệnh tự động:
+- Resolve spec-context từ `spec-manifest.yaml`: PRD path + version, BDD scenario fail, tech-doc
+- Tìm **AC bị vi phạm** trong PRD
+- **Phân loại layer** theo BUG_FLOW (Code / BDD / PRD / Design Spec / Env) → route đúng người
+- Phát hiện **coverage gap** → gợi ý `/propose-scenario`
+- Ghi report vào **spec repo** (`{spec_source}/feedback/bug-reports/{BUG-ID}.md`) → **commit + push**
+
+Hoàn toàn **read-only** trên spec/code chính thức — chỉ ghi vào vùng `feedback/`.
+
+> **Làm sao PO/Dev biết?** Report được commit+push vào **spec repo dùng chung**. PO/Dev chạy `/sync` hàng ngày sẽ thấy dòng `📥 New tester feedback`. File nằm local một mình thì không ai biết — chính bước push + `/sync` mới khép vòng. (Không có quyền push → tạo PR/MR.)
+
+## Khi bug là "thiếu scenario" — `/propose-scenario`
+
+Nếu `/report-bug` báo *coverage gap* (behavior đúng nhưng chưa có scenario nào kiểm):
+
+```bash
+/propose-scenario FT-001 login với email có khoảng trắng ở cuối vẫn phải thành công
+```
+
+- Nếu behavior **đã nằm trong một AC của PRD** → lệnh draft Gherkin (tag `@proposed @from-test`), ghi vào `{spec_source}/feedback/bdd-proposals/` → commit + push. PO/Dev review rồi đưa vào `.feature`.
+- Nếu behavior **chưa có trong PRD** → lệnh **ghi** một *PRD change request* (`State: Open`) vào `{spec_source}/feedback/prd-change-requests/{UC-ID}-{slug}.md` → commit + push (KHÔNG chỉ in ra). PO thấy nó khi `/sync`, thêm/sửa AC rồi `/generate-bdd` lại.
+
+> Tester không tự ghi vào BDD — chỉ đề xuất. Giữ đúng ownership.
+
+## Template báo cáo bug
+
+*(Tham khảo — `/report-bug` tự sinh theo format này. Dùng khi báo cáo thủ công.)*
+
+```
+Bug ID   : BUG-{date}-{seq}
+Feature  : FT-{xxx} — {feature name}
+Service  : BE / Web / App
+Severity : Critical / Major / Minor
+
+Spec context:
+  PRD      : specs/prd/{domain}/{TICKET-ID}.md (v{x.x})
+  BDD      : {bdd path} → Scenario: "{scenario title}"
+  Tech Doc : {tech_docs path}
+
+AC bị vi phạm:
+  AC{N}: "{AC text từ PRD}"
+
+BDD Scenario bị fail:
+  "{Scenario title}"
+  Given: {given state}
+  When : {action}
+  Then : {expected theo spec}
+
+Actual behavior:
+  {what actually happened}
+
+Steps to reproduce:
+  1. {step}
+  2. {step}
+
+Environment: staging / production
+```
+
+## Ví dụ báo cáo thực tế
+
+```
+Bug ID   : BUG-20260605-003
+Feature  : FT-001 — User Login
+Service  : BE
+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
+             → Scenario: "Lock account after 5 failed attempts"
+  Tech Doc : free-trial-specs/specs/tech-docs/auth/FT-001-auth-api.md
+
+AC bị vi phạm:
+  AC3: "Sai password 5 lần liên tiếp → khoá tài khoản 30 phút"
+
+BDD Scenario bị fail:
+  "Lock account after 5 failed attempts"
+  Given : user "alice@example.com" has 0 failed attempts
+  When  : login with wrong password 5 times
+  Then  : 5th attempt returns 423 Locked
+          AND retry_after = 1800
+
+Actual behavior:
+  5th attempt returns 401 Unauthorized (không phải 423)
+  Không có retry_after header
+  → Tài khoản không bị khoá, vẫn cho thử tiếp
+
+Steps to reproduce:
+  POST /api/v1/auth/login × 5 với password sai
+  → lần thứ 5 vẫn nhận 401
+
+Environment: staging (deploy 2026-06-05 09:00)
+```
+
+## Sau khi gửi bug report
+
+Dev sẽ xác định bug thuộc layer nào (code / BDD / PRD / env) và phản hồi với root cause + scenario cần re-test.
+
+> Xem flow phối hợp đầy đủ giữa Tester ↔ Dev ↔ PO trong **[Operations › Bug Flow](../../04-operations/bug-flow.md)**.
+
+> **Nếu AI lặp lại cùng kiểu lỗi qua nhiều feature:** ghi chú trong bug report. Dev chạy `/learn` để biến nó thành guardrail — AI sẽ không sinh lại lỗi đó ở các UC sau.
+
+---
+
+← [Tình huống thực tế](scenarios.md) · Tiếp theo: [Checklist test pass](test-checklist.md)

package/docs/02-guides/tester/reading-specs.md

@@ -0,0 +1,79 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Tester](README.md) › Đọc Spec Chain
+
+# Đọc Và Hiểu Spec Chain
+
+## Thứ tự đọc và mục đích
+
+| Tài liệu | Đọc để | Ví dụ thực tế |
+|---|---|---|
+| **PRD** | Hiểu WHAT — business requirement | "Sai password 5 lần → khoá 30 phút" |
+| **BDD** | Biết HOW VERIFIED — exact scenarios | `Given 5 failed logins, Then 423 Locked` |
+| **Tech Docs BE** | Biết API contract khi test BE | `POST /api/v1/auth/login`, error codes |
+| **Tech Docs Web** | Biết UI states khi test Web | Screen names, component behaviors |
+
+## Ví dụ đọc spec chain — FT-001 Login
+
+Sau khi chạy `/generate-spec-manifest`, tra manifest để lấy paths:
+
+```yaml
+# spec-manifest.yaml
+FT-001:
+  prd:          "my-project-specs/specs/prd/auth/FT-001-login.md"
+  bdd:
+    be:   "free-trial-be/specs/bdd/auth/system/FT-001-UC1-login-system.feature"
+    web:  "free-trial-web/specs/bdd/auth/web/FT-001-UC1-login-web.feature"
+  tech_docs:
+    be:   "my-project-specs/specs/tech-docs/auth/FT-001-auth-api.md"
+```
+
+**Bước 1: Đọc PRD** tại `my-project-specs/specs/prd/auth/FT-001-login.md`
+*(nằm trong spec submodule — shared repo của PO)*
+
+```markdown
+# AC trong PRD FT-001:
+AC1: Đăng nhập thành công → truy cập được hệ thống
+AC2: Sai password → hiển thị lỗi, không tiết lộ thông tin user
+AC3: Sai password 5 lần liên tiếp → khoá tài khoản 30 phút
+AC4: Tài khoản bị khoá → thông báo thời gian mở khoá
+```
+
+**Bước 2: Đọc BDD System (cho BE)** tại `free-trial-be/specs/bdd/auth/system/FT-001-UC1-login-system.feature`
+*(nằm trong service submodule của BE — PO gen, chứa contract BE phải đáp ứng)*
+
+```gherkin
+Scenario: Successful login
+  Given user "alice@example.com" exists
+  When POST /api/v1/auth/login {"email": "alice@...", "password": "correct"}
+  Then status 200, body has access_token and refresh_token
+
+Scenario: Lock after 5 failures
+  Given user has 0 failed attempts
+  When login with wrong password 5 times
+  Then 5th attempt returns 423
+  And response has retry_after: 1800
+```
+
+**Bước 3: Đọc Tech Docs BE** tại `my-project-specs/specs/tech-docs/auth/FT-001-auth-api.md`
+*(nằm trong spec submodule — Dev gen, SA sign-off, đây là API contract chính thức)*
+
+```markdown
+# Auth API — Error Codes
+401 — sai password (failed_attempts < 5)
+423 — tài khoản bị khoá (retry_after tính bằng giây)
+404 — email không tồn tại (không phân biệt với 401 — security)
+
+# Headers bắt buộc
+Authorization: Bearer {token}
+X-Request-ID: uuid (optional, dùng để trace)
+```
+
+**Kết quả: tester biết cần test:**
+- `POST /auth/login` với đúng credentials → 200 + token
+- `POST /auth/login` với sai password → 401 (message không reveal user exists/not)
+- 5 lần sai → 423 + `retry_after: 1800`
+- Email không tồn tại → 404 (message = 401 message — security by design)
+- Sau 30 phút → có thể login lại
+
+---
+
+← [Workflow](workflow.md) · Tiếp theo: [Tình huống thực tế](scenarios.md)

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

@@ -0,0 +1,186 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Tester](README.md) › Tình huống thực tế
+
+# Tình Huống Thực Tế
+
+## Tình huống 1: Test feature mới được assign
+
+**Bối cảnh:** PO thông báo FT-042 Checkout đã approved.
+
+```bash
+# 1. Cập nhật repo
+git pull && git submodule update --remote --recursive
+
+# 2. Refresh manifest
+/generate-spec-manifest
+
+# 3. Kiểm tra status
+# FT-042:
+#   status: approved  ← ✅ có thể test
+#   prd: "specs/prd/payment/FT-042-checkout.md"
+#   bdd:
+#     be:  "free-trial-be/specs/bdd/payment/system/FT-042-UC1-checkout-system.feature"
+#     web: "free-trial-web/specs/bdd/payment/web/FT-042-UC1-checkout-web.feature"
+```
+
+**Test plan từ BDD BE (7 scenarios):**
+
+| # | Scenario | Input | Expected |
+|---|---|---|---|
+| 1 | Checkout thành công | Cart đủ hàng, card valid | 201 + order_id |
+| 2 | Cart rỗng | Không có items | 400 EMPTY_CART |
+| 3 | Hết hàng | item_id đã sold out | 409 OUT_OF_STOCK |
+| 4 | Card bị từ chối | card number test declined | 402 PAYMENT_DECLINED |
+| 5 | Timeout payment gateway | mock timeout | 504 + order status PENDING |
+| 6 | Giới hạn thanh toán | amount > 10,000,000 VND | 400 LIMIT_EXCEEDED |
+| 7 | Session hết hạn | expired token | 401 UNAUTHORIZED |
+
+---
+
+## Tình huống 2: PRD thay đổi giữa sprint
+
+**Bối cảnh:** Đang test FT-042 thì PO update PRD v1.0 → v1.1 (giới hạn từ 5tr → 10tr).
+
+```bash
+git pull && git submodule update --remote --recursive
+/generate-spec-manifest
+# spec-manifest.yaml: FT-042 prd_version: "1.1"
+# FT-042 Changelog:
+# v1.1 | 2026-06-05 | BR7: payment limit thay đổi 5,000,000 → 10,000,000
+```
+
+**Cập nhật test case:**
+```
+Test case 6 cũ:  amount > 5,000,000 → 400 LIMIT_EXCEEDED  ← STALE
+Test case 6 mới: amount > 10,000,000 → 400 LIMIT_EXCEEDED ← theo v1.1
+
+Thêm test case mới:
+Test case 6b: amount = 9,999,999 → 201 OK (boundary case — giờ pass)
+Test case 6c: amount = 10,000,001 → 400 LIMIT_EXCEEDED
+```
+
+> Nếu Dev chưa update code theo v1.1 → test fail vì code vẫn dùng limit 5tr → báo Dev, không phải bug.
+
+---
+
+## Tình huống 3: Test BE và Web cùng 1 feature
+
+**Bối cảnh:** FT-001 Login có BDD cho cả BE (API) và Web (UI).
+
+**BE test** — đọc `bdd.be` (System BDD) + `tech_docs.be`:
+
+```
+Endpoint: POST /api/v1/auth/login
+Test tool: Postman / k6 / Jest supertest
+
+Test cases từ BDD System (cho BE):
+✅ SC1: Valid credentials → 200 + JWT
+✅ SC2: Wrong password → 401 (message generic)
+✅ SC3: 5 failures → 423 + retry_after
+✅ SC4: Locked account → 423
+✅ SC5: Email không tồn tại → 404 (message = 401 message)
+```
+
+**Web test** — đọc `bdd.web` + `tech_docs.web`:
+
+```
+Tool: Playwright
+
+Test cases từ BDD Web:
+✅ SC1: Điền đúng → redirect dashboard
+✅ SC2: Sai password → toast error, password cleared
+✅ SC3: 5 lần sai → form disabled + countdown timer
+✅ SC4: "Quên mật khẩu?" link visible sau 3 lần sai
+✅ SC5: Session expired → redirect về login với message
+```
+
+**Cross-check quan trọng:** BE trả `retry_after: 1800` → Web hiển thị countdown `29:59`. Nếu Web không đọc đúng header → bug.
+
+---
+
+## Tình huống 4: Feature chưa có BDD
+
+**Manifest báo:**
+```
+⚠️  1 PRDs with no matching BDD:
+    - FT-055 (notification) — run /generate-bdd first
+```
+
+**Xử lý:**
+```
+Không tự gen BDD — đó là việc của Dev.
+
+1. PRD có status: approved nhưng chưa có BDD → báo Dev lead
+   PRD còn draft → chờ PO approve trước
+
+2. Nếu bị yêu cầu test mà chưa có BDD:
+   → Test dựa trên PRD AC trực tiếp
+   → Ghi chú rõ trong test report: "Tested against PRD AC, no BDD available"
+   → Không thể trace chi tiết → coverage thấp hơn
+
+3. Sau khi Dev gen BDD → refresh manifest → test lại đầy đủ
+```
+
+---
+
+## Tình huống 5: Regression testing sau merge lớn
+
+**Bối cảnh:** Dev merge refactor module Auth (đổi tên `AuthService` → `IdentityService`).
+
+```bash
+git pull && git submodule update --remote --recursive
+/generate-spec-manifest
+```
+
+**Xác định scope regression từ spec-manifest:**
+
+```
+1. Domain bị ảnh hưởng: auth
+2. Tất cả features có domain: auth:
+   - FT-001 (login), FT-003 (register), FT-007 (password reset), FT-012 (2FA)
+
+3. Features khác có @trace.module: IdentityService:
+   → Grep trong tech_docs: "IdentityService"
+   → FT-019 (profile) cũng phụ thuộc vào IdentityService
+
+Regression scope: FT-001, FT-003, FT-007, FT-012, FT-019
+```
+
+---
+
+## Tình huống 6: Test feature multi-service (BE + Web + App)
+
+**Bối cảnh:** FT-042 Checkout có cả BE API, Web UI, và App UI.
+
+```yaml
+FT-042:
+  domain: payment
+  status: approved
+  bdd:
+    be:  "free-trial-be/specs/bdd/payment/system/FT-042-UC1-checkout-system.feature"
+    web: "free-trial-web/specs/bdd/payment/web/FT-042-UC1-checkout-web.feature"
+    app: "free-trial-app/specs/bdd/payment/app/FT-042-UC1-checkout-app.feature"
+```
+
+**Test strategy:**
+
+```
+Layer 1 — BE API:
+→ Test /api/v1/checkout endpoint isolated
+→ Tool: Postman hoặc Jest supertest
+
+Layer 2 — Web E2E:
+→ Tool: Playwright
+→ Flow: Cart → Checkout page → Payment form → Order confirmation
+
+Layer 3 — App E2E:
+→ Tool: Maestro / Detox
+→ Flow: Cart screen → Checkout → Payment → Success screen
+
+Layer 4 — Cross-layer:
+→ Web checkout → kiểm tra order trong BE database
+→ App checkout → cùng order visible trong Web dashboard
+```
+
+---
+
+← [Đọc Spec Chain](reading-specs.md) · Tiếp theo: [Báo cáo bug](bug-reporting.md)