@educa-corp/sdd-framework 0.2.4 → 0.2.5

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

@@ -1,186 +0,0 @@
-[📚 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/FT-042-checkout.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

@@ -1,130 +0,0 @@
-[📚 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 (`{TICKET-ID}-{prd-slug}.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)
-│           ├── {TICKET-ID}-{prd-slug}.md                            ← PRD
-│           ├── design-spec/...                   ← Design Spec
-│           ├── bdd/system/...                    ← BDD System (BE)
-│           ├── bdd/web/...                        ← BDD Web (FE)
-│           ├── bdd/app/...                        ← BDD App
-│           └── tech-docs/...                     ← Tech Docs (1 doc full-stack/PRD: API contract + client 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/FT-001-login.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)

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

@@ -1,31 +0,0 @@
-[📚 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 `{spec_source}/.trace/{UC-ID}-{platform}.tsv` (spec repo — một chỗ)
-- [ ] TSV đã được commit vào **spec repo** (1 tầng, giống `feedback/`) + push — KHÔNG commit vào service submodule
-- [ ] `/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

@@ -1,77 +0,0 @@
-[📚 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/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
-    bdd.system:   {spec_source}/specs/{domain}/{prd-slug}/bdd/system/FT-042-*.feature
-    bdd.web:      {spec_source}/specs/{domain}/{prd-slug}/bdd/web/FT-042-*.feature
-    tech_docs.be: {spec_source}/specs/{domain}/{prd-slug}/tech-docs/FT-042-*.md
-    tech_docs.fe: {spec_source}/specs/{domain}/{prd-slug}/tech-docs/FT-042-*-tech-design-web.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 SPEC submodule (PO gen từ PRD — tất cả BDD web/app/system ở spec repo)
-→ 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}       → 2 file: REQUIREMENT_ANALYSIS.md + DOC_GAPS.md
-        ├─ /qc-plan {UC-ID}          → TEST_PLAN.md (risk + plan + questions-for-dev)
-        ├─ /qc-design-test {UC-ID}   → test-cases/*.Test.md
-        │     ⌙ artifact phân tích/thiết kế → {qc_dir}/{UC-ID}/ (mặc định docs/, VISIBLE)
-        ├─ /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 {spec_source}/.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv  ← AUTHORITATIVE (spec repo)
-        └─ /qc-report {UC-ID}        → report pytest-html + Playwright trace evidence
-                                        → reports/<feature>/report.html  ← LOCAL, gitignored
-        │
-        ▼
-Commit TSV vào spec repo (1 tầng — trace dồn về specs, giống feedback/)
-  cd {spec_source}
-  git add .trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv
-  git commit -m "qc: record qc_status for {UC-ID} — pass/fail"
-  git push
-        │
-        ▼
-/validate-traces (hoặc /sync)
-→ đọc {spec_source}/.trace/ (một chỗ) → 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

@@ -1,20 +0,0 @@
-[📚 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`.
-- [mechanisms-explained.md](mechanisms-explained.md) — giải thích các **cơ chế** framework bằng **ngôn ngữ dễ hiểu** + ví von đời thường (bổ sung cho các trang trên; ưu tiên trực giác).
-
-## Đọ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).