@edupia-tutor/spec-driven-docs 0.14.0

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/{domain}/{prd-slug}/prd.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/auth/FT-001-login/prd.md (v1.0)
+  BDD      : free-trial-specs/specs/auth/FT-001-login/bdd/system/FT-001-login.feature
+             → Scenario: "Lock account after 5 failed attempts"
+  Tech Doc : free-trial-specs/specs/auth/FT-001-login/tech-docs/FT-001-auth-api.md
+
+AC bị vi phạm:
+  AC3: "Sai password 5 lần liên tiếp → khoá tài khoản 30 phút"
+
+BDD Scenario bị fail:
+  "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/qc-automation.md

@@ -0,0 +1,165 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Tester](README.md) › QC Automation
+
+# Hướng Dẫn QC Automation — Spec-Driven Docs
+
+> Đây là **một chương của [guide Tester / QA](README.md)** — QC và Tester là **cùng một role**. Chương này đi sâu vào pipeline QC tự động (`/qc-*`); phần vai trò chung, spec-manifest, `/report-bug`, `/propose-scenario`… ở [README của guide](README.md).
+
+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.
+
+### Test-ID contract — locate element không cần scan
+
+Để QC **không** phải dò/giả lập vị trí element lúc runtime (chậm), FE tech-design có section **§2b Test Selectors**: mỗi element **có action** được gán test-id ổn định (`{uc}-{screen}-{element}-{type}`, vd `ft001-login-submit-btn`). `/generate-code` emit đúng id đó theo attribute platform (web `data-testid` · RN `testID` · Flutter `Key`/`Semantics` · iOS `accessibilityIdentifier`); `/qc-design-test` cite test-id trong step; `/qc-run-test` build Page Object locator **thẳng từ map** (ưu tiên trong locator priority `data-testid → role → …`). Element có action mà chưa có test-id trong §2b → QC **fallback** role/text (chậm hơn) và nên bổ sung vào tech-design. Xem [Trace Schema](../../05-reference/trace-schema.md) và FE tech-design (`/generate-tech-docs`).
+
+> **Component reuse / code có sẵn:** `/generate-tech-docs` + `/generate-code` chỉ gán id cho code **mới**. Với component dùng chung (id ở usage site, component phải *forward* test-id) hoặc màn hình **brownfield** đã viết tay → chạy **`/map-testids {UC-ID}`**: reverse-document id đang có, gán id còn thiếu, patch forwarding + ghi vào `figma-components/{module}.md` (section *Test-ID Forwarding*), điền §2b. Nhờ vậy QC vẫn locate-by-id không cần scan.
+
+## 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](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/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/auth/FT-001-login/prd.md"
+  bdd:
+    be:   "my-project-specs/specs/auth/FT-001-login/bdd/system/FT-001-UC1-login-system.feature"
+    web:  "my-project-specs/specs/auth/FT-001-login/bdd/web/FT-001-UC1-login-web.feature"
+  tech_docs:
+    be:   "my-project-specs/specs/auth/FT-001-login/tech-docs/FT-001-auth-api.md"
+```
+
+**Bước 1: Đọc PRD** tại `my-project-specs/specs/auth/FT-001-login/prd.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 `my-project-specs/specs/auth/FT-001-login/bdd/system/FT-001-UC1-login-system.feature`
+*(nằm trong spec submodule — PO gen, chứa contract BE phải đáp ứng; tất cả BDD web/app/system đều ở spec repo)*
+
+```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/auth/FT-001-login/tech-docs/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/payment/FT-042-checkout/prd.md"
+#   bdd:
+#     be:  "free-trial-specs/specs/payment/FT-042-checkout/bdd/system/FT-042-UC1-checkout-system.feature"
+#     web: "free-trial-specs/specs/payment/FT-042-checkout/bdd/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-specs/specs/payment/FT-042-checkout/bdd/system/FT-042-UC1-checkout-system.feature"
+    web: "free-trial-specs/specs/payment/FT-042-checkout/bdd/web/FT-042-UC1-checkout-web.feature"
+    app: "free-trial-specs/specs/payment/FT-042-checkout/bdd/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)

package/docs/02-guides/tester/spec-manifest.md

@@ -0,0 +1,130 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Tester](README.md) › Spec Manifest & Setup
+
+# Spec Manifest & Setup
+
+## Spec-Manifest Là Gì Và Tại Sao Cần
+
+Trong umbrella repo (có `spec_source`), **mọi spec đều nằm trong spec submodule** — gom theo feature-package: mỗi PRD có một thư mục `specs/{domain}/{prd-slug}/` chứa tất cả artifact (`prd.md`, `bdd/{platform}/`, `tech-docs/`, `design-spec/`), trải trên nhiều domain:
+
+```
+free-trial-umbrella/                              ← umbrella (Claude Code mở ở đây)
+├── free-trial-specs/                             ← SPEC submodule — TẤT CẢ spec ở đây
+│   └── specs/
+│       └── auth/FT-001-login/                    ← feature-package (1 PRD = 1 thư mục)
+│           ├── prd.md                            ← PRD
+│           ├── design-spec/...                   ← Design Spec
+│           ├── bdd/system/...                    ← BDD System (BE)
+│           ├── bdd/web/...                        ← BDD Web (FE)
+│           ├── bdd/app/...                        ← BDD App
+│           └── tech-docs/...                     ← Tech Docs (BE contract + FE design)
+├── free-trial-be/    (chỉ code)                  ← SERVICE submodule
+└── free-trial-web/   (chỉ code)                  ← SERVICE submodule
+```
+
+Tester's agent không biết domain nào / file nào ứng với TICKET-ID → cần một **index file** để tra cứu. *(Chỉ khi KHÔNG có `spec_source` thì BDD mới rải theo từng service submodule.)*
+
+`spec-manifest.yaml` là file được gen tự động, ánh xạ TICKET-ID → tất cả file liên quan:
+
+```yaml
+features:
+  FT-001:
+    domain: auth
+    status: approved
+    prd: "specs/auth/FT-001-login/prd.md"
+    pdd: "specs/product-definition/auth/FT-001-def.md"
+    tech_docs:
+      be:  "free-trial-specs/specs/auth/FT-001-login/tech-docs/FT-001-UC1-auth-api.md"
+      web: "free-trial-specs/specs/auth/FT-001-login/tech-docs/FT-001-UC1-login-web.md"
+    bdd:
+      be:  "free-trial-specs/specs/auth/FT-001-login/bdd/system/FT-001-UC1-login-system.feature"
+      web: "free-trial-specs/specs/auth/FT-001-login/bdd/web/FT-001-UC1-login-web.feature"
+```
+
+**Quan trọng:**
+- File này **không commit vào git** (gitignored) — gen local mỗi khi cần
+- Luôn `git pull` trước khi gen để có submodule mới nhất
+- Chỉ test các feature có `status: approved` — draft PRD chưa được approve
+- Nếu nhiều người gen cùng lúc → kết quả **giống nhau** (deterministic) — không conflict
+- Khi PO cập nhật PRD hoặc BDD → re-run `/generate-spec-manifest` để manifest phản ánh nội dung mới
+
+## Setup Tester Agent
+
+### Lần đầu tiên
+
+```bash
+# 1. Clone umbrella repo (nếu chưa có)
+git clone {umbrella-repo-url} free-trial-spec
+cd free-trial-spec
+
+# 2. Init tất cả submodules
+git submodule update --init --recursive
+
+# 3. Mở Claude Code tại umbrella root
+#    QUAN TRỌNG: mở tại free-trial-spec/, không phải free-trial-tests/
+```
+
+### Trước mỗi test sprint
+
+```bash
+# Cập nhật tất cả submodules về commit mới nhất
+git pull
+git submodule update --remote --recursive
+
+# Gen manifest
+/generate-spec-manifest
+# → viết spec-manifest.yaml tại free-trial-spec/ root
+```
+
+### Cấu hình tester agent đọc manifest
+
+Trong tester's agent config (hoặc system prompt), thêm:
+
+```
+Trước khi test bất kỳ feature nào:
+1. Đọc spec-manifest.yaml tại project root
+2. Lookup TICKET-ID → lấy paths của prd, bdd, tech_docs
+3. Chỉ test features có status: approved
+4. Đọc PRD trước để hiểu business context
+5. Đọc BDD để biết scenarios cần cover
+```
+
+## Living Docs Panel (umbrella mode)
+
+Khi làm việc với umbrella repo, VS Code Living Docs panel cần được đồng bộ trước khi xem (chạy `/sync` hoặc `/validate-traces`).
+
+**Report canonical (Living Docs):** `{spec_source}/.living-docs/trace-report.json` + bản mirror TSV — nằm trong **spec module** (gitignored, regenerate mỗi lần `/sync` hoặc `/validate-traces`).
+
+**Panel mirror:** `./.trace` của workspace hiện tại — giữ panel **không bị trống** kể cả khi mở Claude Code bên trong một service submodule đơn lẻ.
+
+```bash
+# Chạy sau mỗi codegen session — hoặc khi cần refresh trạng thái coverage
+/sync            # hoặc /validate-traces
+
+# → Đọc TSVs từ MỘT chỗ: {spec_source}/.trace/  (mỗi scenario mang @trace.service)
+# → Ghi canonical: {spec_source}/.living-docs/trace-report.json (+ TSV mirror)
+# → Ghi panel mirror: ./.trace  (workspace hiện tại — panel luôn có data)
+# → Panel cập nhật ngay sau khi lệnh hoàn tất
+```
+
+Panel hiển thị trạng thái cross-service:
+
+| Cột | Ý nghĩa |
+|-----|---------|
+| PRDs | Số PRD đã approve / tổng |
+| UCs | Số Use Cases đã implement |
+| Code Cov. | % scenarios có code |
+| Test Cov. | % scenarios có test |
+| DRIFT | Spec thay đổi sau khi gen code |
+| GAP | Code có nhưng chưa có test |
+| dev_selftest | Dev đã chạy self-check: `pass` / `fail` / `not_run` |
+| qc_status | Kết quả QC chính thức: `pass` / `fail` / `skip` / `not_run` |
+
+> **`dev_selftest`:** tín hiệu cho QC thấy dev đã tự chạy self-check. **Không phải** coverage chính thức — đó là `qc_status`.
+>
+> **`qc_status`:** kết quả pipeline QC chính thức (`/qc-run-test`). Dashboard hiển thị hai cột cạnh nhau để phân biệt rõ hai luồng.
+
+> **Prerequisite:** umbrella cần `setup.spec_source` trỏ đúng spec submodule → trace TSV authoritative dồn về `{spec_source}/.trace/`. Nếu thiếu → panel trống → báo Dev team. (Chỉ chế độ không có `spec_source` mới cần `paths.trace_dir` per-service.)
+
+---
+
+← [Tester Guide](README.md) · Tiếp theo: [Workflow](workflow.md)