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

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)

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

@@ -0,0 +1,124 @@
+[📚 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, spec files nằm rải rác ở nhiều submodule:
+
+```
+free-trial-spec/
+├── specs/prd/auth/FT-001-login.md         ← PRD (spec submodule)
+├── specs/product-definition/auth/...      ← PDD
+├── free-trial-be/specs/bdd/...            ← BDD của BE
+├── free-trial-web/specs/bdd/...              ← BDD của Web
+└── free-trial-app/specs/bdd/...           ← BDD của App
+```
+
+Tester's agent không biết layout này → cần một **index file** để tra cứu.
+
+`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/prd/auth/FT-001-login.md"
+    pdd: "specs/product-definition/auth/FT-001-def.md"
+    tech_docs:
+      be:  "free-trial-specs/specs/tech-docs/auth/FT-001-UC1-auth-api.md"
+      web: "free-trial-specs/specs/tech-docs/auth/FT-001-UC1-login-web.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"
+```
+
+**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ừ: user-service/.trace/, order-service/.trace/, ...
+# → 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:** Mỗi service submodule cần `.agent/project-context.yaml` với `paths.trace_dir`. Nếu thiếu → panel trống → báo Dev team.
+
+---
+
+← [Tester Guide](README.md) · Tiếp theo: [Workflow](workflow.md)

package/docs/02-guides/tester/test-checklist.md

@@ -0,0 +1,31 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Tester](README.md) › Checklist Test Pass
+
+# Checklist Trước Khi Báo "test pass"
+
+**Spec & coverage:**
+- [ ] Tất cả BDD scenarios đã được cover (happy path + edge + error)
+- [ ] Mọi AC trong PRD đã được verify
+- [ ] Manifest version khớp với PRD version đang deploy
+- [ ] Không có scenarios bị skip mà không có lý do ghi chú
+
+**Môi trường:**
+- [ ] Test đã chạy trên đúng môi trường (staging, không phải local dev)
+- [ ] Cross-service flows đã được verify (nếu feature span nhiều service)
+
+**TSV & Living Docs:**
+- [ ] `/qc-run-test` đã chạy → `qc_status` đã ghi vào `{service}/.trace/{UC-ID}.tsv`
+- [ ] TSV đã được commit vào service submodule + umbrella pointer đã update + push
+- [ ] `/validate-traces` (hoặc `/sync`) đã chạy → Living Docs panel hiển thị `qc_status: pass`
+- [ ] Không còn scenario nào `qc_status: not_run` trong UC đang test
+- [ ] Nếu có `qc_status: fail` → đã `/report-bug` kèm path evidence (`reports/<feature>/report.html`)
+
+## Xem Thêm
+
+- [Guide › QC Automation](../qc-automation.md) — pipeline `/qc-*` chi tiết, `qc_status`, stack `qc-playwright`
+- [Operations › Bug Flow](../../04-operations/bug-flow.md) — flow phối hợp Tester ↔ Dev ↔ PO
+- [Concepts › Traceability](../../03-concepts/traceability.md) — trace TSV, dev_selftest vs qc_status
+- [Reference › Commands](../../05-reference/commands.md) — danh mục đầy đủ mọi command
+
+---
+
+← [Báo cáo bug](bug-reporting.md)

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

@@ -0,0 +1,79 @@
+[📚 Docs](../../README.md) › [Guides](../README.md) › [Tester](README.md) › Workflow
+
+# Workflow Cơ Bản
+
+```
+Nhận task: "Test FT-042 — Checkout flow"
+        │
+        ▼
+git pull && git submodule update --remote --recursive
+        │
+        ▼
+/generate-spec-manifest
+→ spec-manifest.yaml được refresh
+        │
+        ▼
+Lookup FT-042 trong spec-manifest.yaml
+→ status: approved? ✅ (nếu draft → dừng, báo PO)
+→ ghi lại paths (tất cả đều nằm trong submodule):
+    prd:          {spec_source}/specs/prd/{domain}/FT-042-*.md
+    bdd.be:       {service-be}/specs/bdd/{domain}/FT-042-*.feature
+    bdd.web:      {service-web}/specs/bdd/{domain}/FT-042-*.feature
+    tech_docs.be: {spec_source}/specs/tech-docs/{domain}/FT-042-*.md
+        │
+        ▼
+Đọc PRD tại path manifest.prd
+→ file nằm trong SPEC submodule (shared — PO viết)
+→ hiểu AC, UC, BR — đây là "ground truth"
+        │
+        ▼
+Đọc BDD tại path manifest.bdd.be / bdd.web
+→ file nằm trong SERVICE submodule (be/web/app — PO gen từ PRD)
+→ mỗi Scenario = 1 test case cần cover
+→ BE có BDD riêng (system/), Web có BDD riêng (web/), App có BDD riêng (app/)
+        │
+        ▼
+Đọc Tech Docs tại path manifest.tech_docs.be / tech_docs.web
+→ file nằm trong SPEC submodule (shared — Dev gen, SA sign-off)
+→ BE: API endpoints, request/response schema, error codes
+→ Web: screen flow, component states
+        │
+        ▼
+Chạy QC automation pipeline (6 bước — ghi kết quả chính thức vào TSV)
+        │
+        ├─ /qc-analyze {UC-ID}       → bóc tách spec, xác định scope, phát hiện DOC_GAPS
+        ├─ /qc-plan {UC-ID}          → risk + test plan + questions-for-dev
+        ├─ /qc-design-test {UC-ID}   → thiết kế test case chi tiết (.Test.md)
+        ├─ /qc-review {UC-ID}        → review test design trước khi chạy
+        ├─ /qc-run-test {UC-ID}      → sinh + chạy pytest-playwright
+        │                               → ghi qc_status (pass/fail/skip) per scenario
+        │                               → vào {service}/.trace/{UC-ID}.tsv  ← AUTHORITATIVE
+        └─ /qc-report {UC-ID}        → report pytest-html + Playwright trace evidence
+                                        → reports/<feature>/report.html  ← LOCAL, gitignored
+        │
+        ▼
+Commit TSV vào service submodule + update umbrella pointer
+  cd {service}
+  git add .trace/{UC-ID}.tsv
+  git commit -m "qc: record qc_status for {UC-ID} — pass/fail"
+  git push
+  cd ..   ← umbrella root
+  git add {service}
+  git commit -m "chore: update {service} submodule pointer — {UC-ID} qc_status"
+  git push
+        │
+        ▼
+/validate-traces (hoặc /sync)
+→ tổng hợp TSVs từ tất cả services → Living Docs cập nhật cột qc_status
+        │
+        ▼
+Kết quả:
+  qc_status: pass  → done, Living Docs phản ánh coverage chính thức
+  qc_status: fail  → /report-bug với BDD scenario + AC bị vi phạm
+                      đính kèm path evidence: reports/<feature>/report.html
+                      (evidence local — share file hoặc upload riêng nếu cần)
+```
+
+---
+
+← [Spec Manifest & Setup](spec-manifest.md) · Tiếp theo: [Đọc Spec Chain](reading-specs.md)

package/docs/03-concepts/README.md

@@ -0,0 +1,19 @@
+[📚 Docs](../README.md) › Concepts
+
+# Concepts
+
+Hiểu **cách framework được xây dựng và vận hành** — kiến trúc nhiều lớp, pipeline các phase, và hệ thống traceability. Đọc section này khi bạn muốn biết *vì sao* mọi thứ hoạt động như vậy, không chỉ *cách dùng* lệnh.
+
+## Mục lục (this section)
+
+- [architecture.md](architecture.md) — 6 lớp (Protection → Output), module plug-in system, build pipeline (`*.tmpl` → `*.md` → `core/`), directory map, sub-agent orchestration, hook data-protection.
+- [pipeline.md](pipeline.md) — các phase Discovery → PRD → Design-Spec → BDD → Tech-Docs → Code → Dev self-check → QC automation → Tester feedback; review gates; và step-architecture model (gate / context-loader / spawn-agent / report-footer) đằng sau mỗi command.
+- [traceability.md](traceability.md) — `@trace.*` tags, trace TSV, hai tín hiệu `dev_selftest` vs `qc_status`, Living Docs (canonical trong spec-module + panel mirror), và `/validate-traces`.
+
+## Đọc gì trước?
+
+1. Muốn cái nhìn tổng thể? → [architecture.md](architecture.md) — file "đọc trước khi đọc bất kỳ file chi tiết nào".
+2. Muốn hiểu luồng làm việc end-to-end? → [pipeline.md](pipeline.md).
+3. Muốn hiểu coverage / drift / Living Docs? → [traceability.md](traceability.md).
+
+> Tra cứu chi tiết schema và module thì sang [05 · Reference](../05-reference/) — [trace-schema.md](../05-reference/trace-schema.md) và [modules.md](../05-reference/modules.md).