@educa-corp/sdd-framework 0.2.3 → 0.2.5

package/docs/02-guides/tech-docs-input-checklist.md

@@ -1,109 +0,0 @@
-[📚 Docs](../README.md) › [Guides](README.md) › Checklist Input Tech-Docs
-
-# Checklist Input Tech-Docs — Tech Lead Cần Làm Gì Để Gen Chuẩn
-
-> Áp cho `/generate-tech-docs`. Từ **một hoặc vài file BDD bạn (tech lead) trỏ vào**, lệnh sinh/bồi đắp **một** tech-doc full-stack cho cả PRD. Chuẩn bị đúng đầu vào để dev đọc là code được, và FE không phải chờ sửa lại.
-
-## Mô hình (đọc trước để trỏ lệnh cho đúng)
-
-- **1 PRD = 1 file tech-doc** `{TICKET-ID}-tech-design.md` — gộp cả BE (API, data model, DB) lẫn client (§4.5 component/state/Figma) + §5 sequence xuyên tầng.
-- **Input = file BDD bạn chỉ định**, KHÔNG phải cả PRD. Lệnh chỉ nạp đúng file bạn trỏ (giữ context nhỏ), rồi **ghi/bồi đắp** vào doc chung của PRD.
-- **Append là đường chính:** chạy lệnh trên BDD này → lần sau trỏ BDD khác cùng PRD → doc **lớn dần lên**, không ghi đè phần cũ. §10 UC Coverage là "sổ điểm danh" để lệnh biết cái gì đã có.
-
-```
-BDD (web/app/system) ──/generate-tech-docs {file(s) bạn trỏ}──▶ {TICKET}-tech-design.md
-        run 1: system/UC1        →  tạo doc, phần BE của UC1
-        run 2: web/UC1 app/UC1   →  append §4.5 client cho UC1
-        run 3: system/UC2 …      →  append UC2
-```
-
-## Bạn trỏ lệnh thế nào (batching)
-
-`/generate-tech-docs` nhận **1 hoặc nhiều** file/UC trong một lần (space-separated) — coi là **một batch**, gộp vào doc trong lần chạy đó.
-
-| Cách trỏ | Khi nào dùng |
-|----------|--------------|
-| `/generate-tech-docs system/{UC}.feature` | Vẽ phần BE (API contract) của 1 UC trước |
-| `/generate-tech-docs {UC}` (system+web+app cùng UC) | Muốn cả full-stack của 1 UC trong 1 lần — trỏ đủ 3 file platform |
-| `/generate-tech-docs system/UC1 system/UC2` | Bồi thêm nhiều UC backend một lượt |
-
-- **Cảnh báo mềm nếu > 5 file/lần** (không chặn) — batch to = nạp nhiều context, chất lượng thiết kế giảm. Nên tách nhỏ: **per UC**, hoặc **per platform**.
-- **Kinh nghiệm:** greenfield nên đi **system trước** (chốt API contract) → rồi mới trỏ `web/`·`app/` để append §4.5 bám đúng endpoint. Không bắt buộc (BE+FE cùng file) nhưng ít rework hơn.
-- Trỏ lại UC **đã có** trong doc → lệnh hỏi xác nhận trước khi cập nhật (thêm platform còn thiếu / refresh khi BDD bump version).
-
----
-
-## BDD khác tech-doc thế nào?
-
-Hai cái trả lời **hai câu hỏi khác nhau** về cùng một tính năng:
-
-| | **BDD (web/app/system)** | **Tech-doc (design)** |
-|---|---|---|
-| Trả lời | **CÁI GÌ** — hệ thống/màn phải làm gì (hành vi) | **LÀM SAO** — hiện thực kỹ thuật |
-| Chi tiết kỹ thuật? | **KHÔNG** | **CÓ** — nơi *duy nhất* chứa endpoint/shape/DB/component/state |
-| Ai làm | PO (spec repo) | Tech lead/Dev (`/generate-tech-docs`) |
-| Dùng để | kiểm chứng hành vi (QC trace về đây) | dev code theo; FE đọc để gọi API thật |
-
-```
-PRD → BDD (CÁI GÌ) → /generate-tech-docs → tech-doc (LÀM SAO) → code
-```
-
-> Một câu: **BDD nói "đúng thì ra cái gì", tech-doc nói "gọi/dựng thế nào để ra cái đó".**
-
----
-
-## Chuẩn bị trước khi `/generate-tech-docs`
-
-**1. BDD được trỏ đã duyệt + sạch lỗi chưa?**
-Mỗi file trong batch nên `@trace.status: approved` và **0 finding critical** từ `/review-context`. Lệnh **HALT** nếu còn lỗi critical; chưa approved → cảnh báo mềm.
-→ *Tech-doc dẫn xuất từ BDD; BDD lỗi thì design lỗi theo.*
-
-**2. BDD đã mô tả đủ hành vi chưa?**
-Mỗi scenario rõ: **kết quả trả về**, **side-effect** (lưu/đổi gì), **tín hiệu lỗi** (báo gì khi nào).
-→ *Nguyên liệu để suy ra endpoint, mã lỗi, data model, và §5 sequence. Thiếu = design thiếu.*
-
-**3. Có client (web/app) trong batch → có design-spec chưa?**
-§4.5 (component, Figma mapping, test-id, state) lấy fidelity từ **design-spec**. Thiếu → cảnh báo mềm, §4.5 vẽ tạm từ BDD và đánh dấu `[DRAFT — no design-spec]`.
-→ *Muốn §4.5 chuẩn: chạy `/generate-design-spec` trước.*
-
-**4. `core-entities.md` đã chuẩn chưa?**
-§3 Data Model cần bảng/trường/kiểu/enum đúng. Sai tên một trường = lệch cả request/response lẫn DB.
-
-**5. `CLAUDE.md` có kiến trúc + coding standard chưa?**
-§2 Architecture + service flow bám **layer/kiến trúc project**. Thiếu → design chung chung, code sau lệch.
-
-**6. Service trỏ đúng stack module chưa?** (java-spring / golang / dotnet / angular / …)
-→ *Sai module = mẫu layer/component sai stack.*
-
-**7. Brownfield? → bảng "Existing API Contract" trong PRD phải đầy đủ.**
-`API Source: existing` → lệnh **chép lại** contract (reverse-document). Còn "⛔ thiếu" → tech-doc hổng.
-
-**8. Phụ thuộc liên service đã ghi chưa?** (§1c PRD)
-→ *Bỏ sót = §6 thiếu chỗ nối, đội khác tích hợp hụt.*
-
----
-
-## Checklist nhanh — trước khi gõ lệnh
-
-- [ ] Đã chọn **đúng file BDD** cần vẽ lần này (per UC / per platform); batch **≤ 5** file
-- [ ] Mỗi file trong batch `@trace.status: approved` + **0 finding critical** (không → HALT)
-- [ ] Mỗi scenario rõ: kết quả + side-effects + tín hiệu lỗi
-- [ ] Có `web/`·`app/` trong batch → **design-spec sẵn** (không → §4.5 degraded)
-- [ ] `core-entities.md` cập nhật (data model)
-- [ ] `CLAUDE.md` có kiến trúc layer + coding standards
-- [ ] Service trỏ đúng stack module
-- [ ] Brownfield → bảng Existing API Contract trong PRD **đầy đủ** (hết ⛔)
-- [ ] Phụ thuộc liên service (§1c PRD) ghi rõ nếu có
-
----
-
-## Sau khi sinh tech-doc
-
-- Ra **một** file `{TICKET-ID}-tech-design.md` (hoặc doc cũ được bồi thêm), trạng thái `draft`.
-- `/review-tech-docs` chạy các check T1–T7. **T7 = cổng sign-off liên đội**: greenfield/partner cần FE/App/SA confirm contract trước khi `@trace.status: approved`; brownfield (`existing`) skip T7 vì contract đã chốt.
-- Nếu doc sống trong spec repo dùng chung → **commit + push** để cả team `/sync` đọc.
-- Approved rồi mới `/generate-code`.
-
----
-
-← [Guides](README.md) · Liên quan: [Checklist Input BDD (System/BE)](bdd-input-checklist.md) · [Checklist Input PRD](prd-input-checklist.md) · [Giải thích /generate-tech-docs](../06-commands/explain-generate-tech-docs.md)

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

@@ -1,75 +0,0 @@
-[📚 Docs](../../README.md) › [Guides](../README.md) › Tester / QA
-
-# Hướng Dẫn Tester — SDD Framework
-
-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" |
-| [QC Automation](qc-automation.md) | Deep-dive pipeline `/qc-*` 6 bước · stack `qc-playwright` · `qc_status` → Living Docs |
-
-## Vai Trò Tester Trong Framework
-
-```
-PO/BA                 Dev                     Tester / QA
-─────────────────     ───────────────────     ──────────────────────────
-PRD                   (đọc BDD — KHÔNG gen)    /sync + /generate-spec-manifest
-BDD web→app→system    Tech Docs               Đọc PRD + BDD + Tech Docs
-Design Spec           Code                    Viết test cases · chạy /qc-*
-   ▲                     ▲                     /report-bug · /propose-scenario
-   │                     │                     (bug / edge case → spec repo)
-   └─────────────────────┴──── 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 `@trace.status: approved` (cảnh báo mềm nếu chưa) |
-| `/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 **chương [QC Automation](qc-automation.md)** (một phần của guide Tester / QA này).
-
-> **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) · [Chương QC Automation](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

@@ -1,117 +0,0 @@
-[📚 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`, mang `Status: proposed`), ghi vào `{spec_source}/feedback/bdd-proposals/` → commit + push. PO/Dev review → đặt `Status: accepted` → `/generate-bdd` tự chèn vào `.feature` rồi lưu trữ (`incorporated`).
-- 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}/{TICKET-ID}-{prd-slug}.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/FT-001-login.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

@@ -1,165 +0,0 @@
-[📚 Docs](../../README.md) › [Guides](../README.md) › [Tester](README.md) › QC Automation
-
-# Hướng Dẫn QC Automation — SDD Framework
-
-> Đâ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}-{platform}.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 **§4.5.6 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 §4.5.6 → 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 §4.5.6. 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 khi BDD của một UC đã duyệt — `# @trace.status: approved` (sau `/review-context (BDD)` sạch critical + người duyệt đặt). `/qc-analyze` đọc field này và **cảnh báo mềm** nếu chưa 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

@@ -1,79 +0,0 @@
-[📚 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/FT-001-login.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/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 `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)