@educa-corp/sdd-framework 0.2.4 → 0.2.5

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

@@ -1,68 +0,0 @@
-[📚 Docs](../README.md) › [Guides](README.md) › Checklist Input BDD (System/BE)
-
-# Checklist Input BDD (System / BE) — Để BDD Chuẩn Ngay Lần Đầu
-
-> Áp cho `/generate-bdd` khi chọn platform **`system`** (BDD cho BE). Chuẩn bị đúng đầu vào để không phải sinh lại.
-
-## Hiểu trước cho đúng: System BDD có HAI kiểu sinh
-
-Khi chọn platform `system`, lệnh tự phân loại:
-
-- **BE thuần** (feature không có web/app) → System BDD **sinh thẳng từ PRD** (AC / Business Rules / Business Logic).
-- **BE trong feature đa-platform** → System BDD **tổng hợp từ web + app BDD đã có** (BE suy ra để phục vụ các luồng client).
-
-→ Biết mình ở kiểu nào mới chuẩn bị đúng.
-
----
-
-## Phần CHUNG — cả hai kiểu đều cần
-
-**1. PRD đã duyệt + Luật/AC rõ ràng** *(đòn bẩy số 1)*
-System BDD phủ **mỗi AC và mỗi Business Rule → ít nhất 1 scenario**. PRD mơ hồ ở Business Rules / Logic = BDD mơ hồ. Đây là chỗ quyết định nhiều nhất.
-
-**2. Loại API đã chốt đúng trong PRD**
-- **"Đã có sẵn"** (brownfield) → bảng **Existing API Contract trong PRD phải đầy đủ**, không còn dấu "⛔ còn thiếu". Lệnh dùng bảng này làm chuẩn và **bỏ qua bước tổng hợp**. Còn thiếu = BDD dễ bịa / sai shape.
-- **"Tự làm mới"** → contract thiết kế sau; BDD chỉ tả hành vi nghiệp vụ.
-
-**3. Từ điển + danh sách thực thể đã cập nhật**
-System BDD viết bằng **ngôn ngữ sự kiện nghiệp vụ** ("hệ thống nhận X → trả về Y"), **không** dùng từ giao diện (click/tap), **không** chốt cứng shape JSON kỹ thuật. Tên thực thể / trường / enum phải đúng `core-entities.md`.
-
-**4. Domain khớp cấu hình service** *(chế độ umbrella)*
-Domain trong PRD phải khớp một service trong config; lệch là lệnh **dừng**.
-
----
-
-## Phần RIÊNG theo kiểu
-
-### Nếu BE trong feature đa-platform (tổng hợp)
-
-**5. Đã sinh web + app BDD TRƯỚC — đúng thứ tự outside-in**
-Nếu sinh `system` khi **chưa có** web/app BDD → lệnh tưởng là "BE thuần", sinh từ PRD và **bỏ lỡ** các kỳ vọng client thật (token, profile, redirect…). Phải theo thứ tự **web → app → system**.
-
-**6. Sẵn sàng quyết "xung đột cross-platform"**
-Nếu web và app **kỳ vọng khác nhau** (response / lỗi / luật) → lệnh **dừng ở CHECKPOINT** bắt PO chọn cách hoà: gộp chung / phân biệt theo platform / tách endpoint. Web+app BDD nên nhất quán, hoặc PO sẵn sàng quyết ngay — nếu không sẽ tắc.
-
-### Nếu BE thuần
-
-Bỏ qua câu 5–6. Dồn lực vào câu 1–3: PRD Business Rules / Logic + contract + thực thể.
-
----
-
-## Checklist nhanh — trước khi `/generate-bdd` (system)
-
-- [ ] PRD `approved`, mỗi AC/BR đủ rõ để suy ra scenario
-- [ ] Loại API đã chốt; brownfield → bảng Existing API Contract **đầy đủ** (hết ⛔)
-- [ ] `business-dictionary` + `core-entities` cập nhật (sự kiện / thực thể)
-- [ ] Domain khớp cấu hình service (umbrella)
-- [ ] *(đa-platform)* web + app BDD đã sinh + review **trước** system
-- [ ] *(đa-platform)* sẵn sàng quyết xung đột cross-platform
-
----
-
-## Sau khi sinh BDD
-
-`/review-context` (BDD) bắt nốt sạn (coverage, Gherkin R1–R10, thuật ngữ); khi 0 critical → người duyệt đặt `# @trace.status: approved` rồi mới sang Tech Docs / Code / QC. Chuẩn bị tốt checklist trên thì bước review nhẹ.
-
----
-
-← [Guides](README.md) · Liên quan: [Checklist Input PRD](prd-input-checklist.md) · [Checklist Input Tech-Docs (BE)](tech-docs-input-checklist.md)

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

@@ -1,49 +0,0 @@
-[📚 Docs](../../README.md) › [Guides](../README.md) › Developer
-
-# Hướng Dẫn Developer — SDD Framework
-
-Tài liệu dành cho **Developer (FE / BE / App)** — vai trò, commands, trace system, workflow, và các tình huống thực tế. Được chia nhỏ theo chủ đề để dễ đọc:
-
-## Mục Lục
-
-| Trang | Nội dung |
-|---|---|
-| [Commands](commands.md) | Bảng lệnh cho dev · project lessons · xử lý feedback tester · khi nào dùng `--phase` |
-| [BDD & Trace System](bdd-and-trace.md) | Tại sao BDD quan trọng với dev · `@trace.*` fields · trace chain · khi nào `/validate-traces` |
-| [Checklist input BDD (System/BE)](../bdd-input-checklist.md) | Chuẩn bị để `/generate-bdd` (system) chuẩn ngay lần đầu |
-| [Checklist input Tech-Docs (BE)](../tech-docs-input-checklist.md) | BDD khác tech-doc thế nào · chuẩn bị để `/generate-tech-docs` (BE) ra API contract chuẩn lần đầu |
-| [Workflow](workflow.md) | Luồng làm việc cơ bản từ nhận PRD đến tạo PR |
-| [Tình huống thực tế](scenarios.md) | 8 scenario: nhận PRD mới, đọc System/Web BDD, PRD đổi, API sign-off, bug từ tester, design spec, brownfield, umbrella, validate-traces |
-| [Checklist trước khi tạo PR](pr-checklist.md) | Checklist verify trước khi mở PR |
-
-## Vai Trò Dev Trong Framework
-
-```
-PO/BA                     Dev
-──────────────────────    ──────────────────────────────────────
-/define-product           /review-context (đọc PRD + BDD)
-/generate-prd        →    đọc BDD từ spec submodule
-/refine-prd               /generate-tech-docs (từ BDD → Tech Docs)
-/review-context           /generate-code     (từ BDD + Tech Docs → Code)
-/generate-design-spec →   /dev-gen-test
-/generate-bdd (web)       /review-code
-/generate-bdd (app)       /dev-run-test
-/generate-bdd (system)    /fix-bug / /debug
-                          /validate-traces
-```
-
-**Dev chịu trách nhiệm:**
-- Đọc và hiểu PRD + BDD từ spec submodule trước khi bắt đầu
-- **KHÔNG tự generate BDD** — BDD đã được PO generate trong spec repo
-- Đảm bảo code trace về đúng BDD scenario, BDD trace về đúng PRD
-- **Duyệt BDD:** sau khi `/review-context` (BDD) sạch critical, Dev-lead/SA đặt `# @trace.status: approved` trong `.feature` (cổng trước tech-docs / code / QC)
-- Báo PO/BA khi PRD hoặc BDD có gì không rõ hoặc mâu thuẫn — không tự suy diễn
-
-**Dev KHÔNG làm:**
-- Viết/sửa PRD — đó là việc của PO/BA
-- Viết/sửa Design Spec — đó là việc của PO/BA + Designer
-- Approve PRD — chỉ PO mới có quyền này
-
----
-
-*Xem thêm:* [Product Owner Guide](../product-owner/README.md) · [Tester Guide](../tester/README.md) · [chương QC Automation](../tester/qc-automation.md) · [Concepts › Traceability](../../03-concepts/traceability.md) · [Reference › Commands](../../05-reference/commands.md)

package/docs/02-guides/developer/bdd-and-trace.md

@@ -1,126 +0,0 @@
-[📚 Docs](../../README.md) › [Guides](../README.md) › [Developer](README.md) › BDD & Trace System
-
-# BDD & Trace System
-
-- [Tại sao BDD quan trọng với Dev](#tại-sao-bdd-quan-trọng-với-dev)
-- [Hiểu Trace System](#hiểu-trace-system)
-
-## Tại Sao BDD Quan Trọng Với Dev
-
-### BDD không phải "viết test thêm"
-
-BDD là **spec thực thi được** — nó định nghĩa CHÍNH XÁC hệ thống phải làm gì trước khi viết một dòng code.
-```
-PRD (business language)  →  BDD (technical spec)  →  Code (implementation)
-"Sai password 5 lần         Given 5 failed logins       if failCount >= 5:
- → khoá 30 phút"            Then account locked            lockAccount(30min)
-                            And locked_until = now+30m
-```
-
-### BDD định hướng kiến trúc code
-
-BDD scenario là unit of work — mỗi scenario ánh xạ thành một test case, một function, một API endpoint. Viết BDD trước buộc dev phải nghĩ về interface trước implementation.
-```gherkin
-# BDD này buộc dev phải tạo:
-# - POST /auth/login endpoint
-# - lockAccount(duration) service method
-# - AccountLocked exception/response
-
-Scenario: Lock account after 5 failed attempts
-  Given user "alice@example.com" exists
-  When user attempts login with wrong password 5 times
-  Then account is locked for 30 minutes
-  And login returns 423 Locked with "retry_after" header
-```
-
-### BDD là tài liệu sống
-
-Khi BDD pass → code đang hoạt động đúng spec. Khi BDD fail → code lệch khỏi yêu cầu. Không cần đọc PRD để biết feature có đang hoạt động không — chạy BDD là biết ngay.
-
-### BDD đến từ spec repo — Dev đọc, không tự gen
-
-BDD được PO generate trong spec repo, nằm tại `specs/{domain}/{prd-slug}/bdd/`:
-
-| Subfolder | Platform | Dev team đọc |
-|---|---|---|
-| `web/` | FE/Web (clicks, sees, navigates) | FE/Web dev |
-| `app/` | Mobile (taps, sees screen, navigates) | App dev |
-| `system/` | System/BE (request, response, business rules) | BE dev |
-
-Cả 3 subfolder đều trace về **cùng 1 PRD**. BE không cần đọc BDD của FE và ngược lại.
-
-## Hiểu Trace System
-
-Framework dùng metadata `@trace.*` để liên kết PRD → BDD → Code. (Chi tiết khái niệm: [Concepts › Traceability](../../03-concepts/traceability.md).)
-
-### Các trace fields quan trọng
-
-| Field | Vị trí | Ý nghĩa |
-|---|---|---|
-| `Domain` | bảng Metadata PRD | Domain của feature (auth, payment, ...) — dùng để route vào đúng service submodule |
-| `@trace.module` | BDD / Tech Doc header | Module trong codebase sẽ implement |
-| `@trace.prd` | BDD / Tech Doc header | Link về PRD gốc |
-| `@trace.bdd` | Code comment / test | Link về BDD scenario |
-| `Status` | bảng Metadata PRD | `draft` / `approved` — chỉ code khi `approved` |
-| `@trace.status` | BDD `.feature` header | `draft` / `approved` — Dev-lead/SA đặt approved sau review-context BDD sạch; mirror → `uc_status` (dashboard) |
-| `dev_selftest` | Trace TSV | `pass` / `fail` / `not_run` — kết quả dev self-check, set bởi `/dev-run-test`. Surfaced trong Living Docs để QC biết dev đã chạy self-check — **KHÔNG phải coverage chính thức** |
-| `dev_selftest_at` | Trace TSV | Timestamp lần chạy `/dev-run-test` gần nhất |
-| `qc_status` | Trace TSV | `pass` / `fail` / `skip` / `not_run` — kết quả **QC chính thức**, set bởi `/qc-run-test` (do QC chạy, KHÔNG phải dev). Orthogonal với `dev_selftest` và với coverage `status` |
-| `qc_run_at` | Trace TSV | Timestamp lần chạy `/qc-run-test` gần nhất |
-
-### Ví dụ trace chain hoàn chỉnh
-
-```
-specs/auth/login/{TICKET-ID}-login.md                              ← Metadata: Domain: auth, Status: approved
-    ↓
-specs/auth/login/bdd/system/FT-001-UC1-login.feature ← @trace.prd: FT-001 · web/app/system riêng (system tổng hợp từ web+app)
-    ↓
-src/auth/auth.service.ts                             ← // @trace.bdd: FT-001-UC1-SC1   (service submodule)
-    ↓
-{spec_source}/.trace/auth/login/FT-001.tsv           ← coverage/drift — authoritative ở SPEC repo
-```
-
-### Khi nào chạy /validate-traces?
-
-- Sau khi refactor đổi tên file/function
-- Sau khi PRD được PO cập nhật (version mới)
-- Trước khi tạo PR lớn
-- Khi CI báo trace validation fail
-- **Sau mỗi codegen session trong umbrella mode** — để sync Living Docs panel
-
-```
-/validate-traces
-→ Sẽ report: broken links, orphan BDD (không có PRD), dead code traces
-```
-
-**Lưu ý khi dùng umbrella (submodule):**
-```
-Vấn đề: Living Docs panel mở ở umbrella root (hoặc một service submodule đơn lẻ) → nếu không có mirror local → TRỐNG.
-         TSV authoritative nằm committed MỘT chỗ ở spec repo: {spec_source}/.trace/
-
-Giải pháp: /validate-traces (hoặc /sync) regenerate canonical trace-report.json + TSV mirror
-          trong SPEC MODULE tại {spec_source}/.living-docs/ (gitignored), đồng thời ghi
-          mirror local tại ./.trace của workspace hiện tại để panel không trống khi dev mở
-          một service submodule đơn lẻ.
-
-Lệnh chạy sau mỗi session:
-/validate-traces
-→ Reads .trace/*.tsv authoritative (committed) MỘT chỗ: {spec_source}/.trace/ (mỗi row mang @trace.service)
-→ Writes trace-report.json → {spec_source}/.living-docs/ (gitignored, regenerated bởi /sync hoặc /validate-traces)
-→ Writes panel mirror → ./.trace của workspace hiện tại (non-empty khi mở repo lẻ)
-→ Living Docs panel cập nhật ngay
-```
-
-> **Authoritative vs mirror:** `.trace/*.tsv` được **commit** ở spec repo `{spec_source}/.trace/` (nguồn sự thật, một chỗ). `{spec_source}/.living-docs/` và `./.trace` chỉ là mirror gitignored, regenerated bởi `/sync` hoặc `/validate-traces`.
-
-Thêm `.living-docs/` (spec module) và umbrella/workspace `.trace/` mirror vào `.gitignore`:
-```
-# .gitignore — spec module
-.living-docs/
-# .gitignore — workspace/umbrella root (mirror, không commit)
-.trace/
-```
-
----
-
-← [Commands](commands.md) · Tiếp theo: [Workflow](workflow.md)

package/docs/02-guides/developer/commands.md

@@ -1,76 +0,0 @@
-[📚 Docs](../../README.md) › [Guides](../README.md) › [Developer](README.md) › Commands
-
-# Commands Dành Cho Dev
-
-| Command | Mục đích | Khi nào dùng |
-|---|---|---|
-| `/sync` `[spec-branch]` | **One-command setup hoặc update** — git pull + submodule sync + Living Docs refresh. Truyền branch để override branch spec submodule (vd `/sync develop`) | **Mỗi sáng trước khi bắt đầu work** |
-| `/update-framework` | Nâng cấp **bản thân framework** (`.agent/commands/`, steps/, modules/) từ npm | Khi có version framework mới — không đụng project-context/CLAUDE.md |
-| `/review-context {prd-file}` | Đọc + xác nhận PRD + BDD đủ rõ trước khi code — fan-out review dimension thành sub-agent song song + completeness-critic loop, findings file đầy đủ ngay trong 1 lần chạy | **Bước đầu tiên** khi nhận PRD mới |
-| `/generate-tech-docs {1..n BDD file}` | **1 doc full-stack/PRD.** Trỏ vào file BDD (system→§4 API contract; web/app→§4.5 client design) — gộp vào `{TICKET-ID}-tech-design.md`, append qua nhiều lần chạy. Cảnh báo >5 file/lần. Client thiếu design-spec → §4.5 degraded (soft) | Sau BDD approved. Nên trỏ System BDD trước (chốt §4), rồi web/app BDD (append §4.5 map theo §4.1) |
-| `/generate-code {bdd-file}` | Sinh code — BE hoặc FE khi API đã sẵn sàng. Guard mềm: BDD `@trace.status` approved; FE/App design-spec approved+fresh+sanity | Sau khi tech docs `approved` |
-| `/generate-code {bdd-file} --phase=ui` | FE: gen UI + mock adapter. Mock **shape** từ BE contract nếu có (chuẩn) → else infer từ System BDD + warn (`mock_source=contract\|system-bdd`); fixture values luôn từ System BDD | Ngay sau khi đọc BDD (BE chưa cần deploy API) |
-| `/generate-code {bdd-file} --phase=integration` | FE: wire API thật thay mock | Sau khi sign-off gate `approved` |
-| `/dev-gen-test {bdd-file}` | **Dev self-check** — sinh test cases từ BDD để dev tự verify code mình vừa gen (KHÔNG phải bộ test chính thức của QC/dev-team) | Song song hoặc sau generate-code |
-| `/review-code {file}` | Review code theo 4 lăng kính (Traceability/Layer/Coding Standards/Spec Compliance) | Trước khi tạo PR |
-| `/review-tech-docs {tech-doc-file}` | Review chất lượng Tech Docs | Sau generate-tech-docs |
-| `/dev-run-test` | **Dev self-check** — chạy test do dev tự gen để xác nhận code mình hoạt động (smoke/self-verify, KHÔNG phải coverage chính thức) — *umbrella mode: tự `cd` vào service_root, dùng service's `test_command`*. Ghi `dev_selftest` (pass/fail) vào trace TSV | Sau khi code + tests sẵn sàng |
-| `/fix-bug {issue}` | Phân tích + fix bug có trace | Khi có bug report |
-| `/debug {symptom}` | Debug vấn đề chưa rõ nguyên nhân | Khi cần trace root cause |
-| `/dev-smoke-test` | **Dev self-check** — kiểm tra nhanh các luồng chính của code mình vừa làm (smoke, không thay thế bộ test chính thức) | Sau deploy hoặc merge lớn |
-| `/validate-traces` | Kiểm tra toàn bộ trace chain còn hợp lệ | Sau refactor hoặc khi PRD update |
-| `/learn {text}` | Ghi lại lỗi AI hay lặp thành guardrail | Khi AI lặp lại lỗi mà bạn không muốn nó tái diễn |
-
-> **Dev self-check vs QC chính thức:** `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` (ghi `dev_selftest`) chỉ là **smoke self-check của riêng dev**. Bộ QC chính thức giờ là native pipeline `/qc-analyze → /qc-plan → /qc-design-test → /qc-review → /qc-run-test → /qc-report` — **do QC chạy, không phải việc của dev** — và ghi `qc_status` riêng. Chi tiết: [chương QC Automation](../tester/qc-automation.md).
-
-> Danh mục đầy đủ mọi command: [Reference › Commands](../../05-reference/commands.md).
-
-## Project Lessons — dạy framework không lặp lỗi
-
-AI đôi khi lặp đi lặp lại một lỗi trong dự án (vd: gọi repository thẳng từ controller, quên null-check). Thay vì sửa thủ công mỗi lần, **ghi lại thành "lesson"** — context-loader sẽ nạp nó vào đầu **mọi** lệnh như một ràng buộc cứng.
-
-**2 cách ghi nhận:**
-```bash
-# Cách 1 — chủ động
-/learn AI hay gọi repository thẳng từ controller, phải đi qua service layer
-
-# Cách 2 — tự động: khi /review-code, /fix-bug, /debug phát hiện lỗi lặp lại
-# → nó hỏi "Record as a project lesson? (Y/N)" → Y
-```
-
-**Lưu ở đâu:** `paths.lessons_file` (mặc định `specs/domain-knowledge/lessons-learned.md`; umbrella: `.agent/project-lessons.md` mỗi service). **Commit file này** để cả team cùng được bảo vệ.
-
-> Đây là **bộ nhớ dự án**, không phải fine-tune model — lesson được nạp vào context mỗi lần chạy, nên AI "nhớ" và không lặp lại. Xem `[CTX LOADED]` có dòng `Lessons: loaded — N guardrails`.
-
-## Xử lý feedback từ tester
-
-Tester gửi bug report (`/report-bug`) và đề xuất scenario (`/propose-scenario`) vào `feedback/` của **spec repo**. Khi dev chạy `/sync`, nó liệt kê:
-```
-📥 New tester feedback (pulled this sync):
-   Bug reports:    BUG-20260608-01  FT-001 — ...  [layer: Code]
-   Scenario proposals: FT-001-trailing-spaces → AC2 (pending review)
-```
-
-Dev hành động theo phân loại:
-- **Bug report** → `/fix-bug {BUG-ID}` (report đã có sẵn spec-context + AC bị vi phạm + layer)
-- **Scenario proposal map vào AC sẵn có** → đặt `Status: accepted` trong file proposal → `/generate-bdd` tự chèn vào `.feature` rồi lưu trữ (`incorporated`); hoặc thêm tay. Rồi `/generate-code` + `/dev-gen-test`
-- **Proposal là yêu cầu mới (PRD change request)** → chuyển PO sửa PRD trước
-
-> Bug reports có thể đến từ hai nguồn: Tester dùng `/report-bug` trực tiếp, **hoặc** từ kết quả QC automation (`qc_status: fail` trong `.trace/*.tsv` → QC (hoặc tester) chạy `/report-bug` → `/sync` → dev thấy tại đây). Cả hai đều dùng cùng luồng `/fix-bug`.
-
-> Tester chỉ *đề xuất* trong `feedback/` — dev/PO mới đưa vào BDD chính thức. Giữ đúng ownership.
-
-## Khi nào dùng `--phase` cho FE/App?
-
-| Tình huống | Command |
-|---|---|
-| API **đã có sẵn** và đang hoạt động | `/generate-code {file}` — không flag, gen real API ngay |
-| BE **chưa ready**, FE muốn bắt đầu ngay | `/generate-code {file} --phase=ui` — UI + mock adapter |
-| Sign-off gate xong, cần wire API thật | `/generate-code {file} --phase=integration` |
-| BE implement (system BDD) | `/generate-code {file}` — không flag |
-
-> `--phase` chỉ có giá trị khi BE chưa sẵn sàng. Nếu API đã live → bỏ qua `--phase`, chạy thẳng default.
-
----
-
-← [Developer Guide](README.md) · Tiếp theo: [BDD & Trace System](bdd-and-trace.md)

package/docs/02-guides/developer/pr-checklist.md

@@ -1,16 +0,0 @@
-[📚 Docs](../../README.md) › [Guides](../README.md) › [Developer](README.md) › PR Checklist
-
-# Checklist Trước Khi Tạo PR
-
-- [ ] `/validate-traces` → all green (không broken trace)
-- [ ] `/dev-run-test` → all pass *(umbrella: đảm bảo service có `.agent/project-context.yaml` với `test_command` trước khi chạy)*
-- [ ] `/review-code` → không có issue Critical hoặc Major chưa xử lý
-- [ ] Code trace về đúng BDD scenarios trong `my-project-specs/specs/{domain}/{prd-slug}/bdd/`
-- [ ] Code có `@trace.bdd` comment cho các function implement BDD scenario
-- [ ] BDD `@trace.status: approved` (đã duyệt) trước khi code/PR; FE/App: Design Spec `Status: approved` + `Built from PRD` khớp PRD hiện tại
-- [ ] Tech Docs đã được update nếu có thay đổi API/DB schema
-- [ ] **Không tự sửa BDD** — BDD là của PO, nếu cần update thì báo PO rồi pull lại
-
----
-
-← [Tình huống thực tế](scenarios.md)