@edupia-tutor/spec-driven-docs 0.14.6 → 0.14.8

package/skills/test/SKILL.tmpl

@@ -2,295 +2,17 @@
 description: Sinh unit và integration test từ BDD spec, chạy test suite và report kết quả, hoặc dev-smoke-test các API endpoint live trên service đang chạy. Trigger when: "/dev-gen-test", "/dev-run-test", "/dev-smoke-test", "tạo test", "viết test", "chạy test", "generate tests", "run tests", "test kết quả", "smoke test", "test API", "kiểm tra endpoint đang chạy".
 ---
 
-# Test Skills — Generate, Run & Smoke Test
+# Test Skills — Generate, Run & Smoke (Dev Self-Check)
 
-Skill này xử lý ba lệnh: `/dev-gen-test`, `/dev-run-test`, và `/dev-smoke-test`.
+Skill này xử lý `/dev-gen-test`, `/dev-run-test`, `/dev-smoke-test` — **dev self-check** (`dev_selftest`), KHÔNG phải QC chính thức (`/qc-*`). Để **không lệch**, skill KHÔNG nhân bản — mỗi lệnh thực thi **y hệt** command.
 
----
-
-## /dev-gen-test — Generate Unit & Integration Tests
-
-### Gate
-
-<!-- Directory: specs/*/*/bdd/*.feature — or pass UC-ID/class path as argument -->
-{{include:steps/gate.md}}
-
-Cũng đọc:
-- File `.feature` để hiểu các behavior kỳ vọng
-- Tìm file cần test: Controller có `@trace.implements={UC-ID}`, Service implementation, Facade implementation (nếu áp dụng)
-
-### CHECKPOINT — Test Plan
-
-Trước khi sinh, trình bày plan:
-
-```
-Test Plan — {UC-ID}:
-
-Unit Tests ({unit test framework}):
-  - {ServiceName}ServiceImplTest
-    • {method}: {scenario} → {expected result}
-  - {FacadeName}FacadeImplTest (if applicable)
-    • {method}: {scenario} → {expected result}
-
-Integration Tests:
-  - {ControllerName}ControllerTest
-    • {endpoint}: {scenario} → HTTP {status}
-
-Total: {N} test classes, ~{M} test cases
-Proceed? (Y/N)
-```
-
-Chờ xác nhận.
-
-### Generate
-
-#### Unit Test Template
-
-```
-// @trace.verifies={UC-ID}
-// @trace.test_type=unit
-[Test class using your project's test framework]
-
-class {Resource}ServiceImplTest {
-
-  // Mock dependencies
-
-  @Test
-  // "Should {expected outcome} when {condition}"
-  void methodName_whenValid_shouldReturnExpected() {
-    // Given — set up mocks and inputs
-    // When  — call the method under test
-    // Then  — assert results and verify interactions
-  }
-
-  @Test
-  // "Should throw {Exception} when {resource} not found"
-  void methodName_whenNotFound_shouldThrowException() {
-    // Given — mock returns empty/null
-    // When & Then — assert exception is thrown
-  }
-}
-```
-
-#### Integration Test Template (Controller/HTTP layer)
-
-```
-// @trace.verifies={UC-ID}
-// @trace.test_type=integration
-[Integration test class for HTTP layer]
-
-class {Resource}ControllerTest {
-
-  // Inject MockMvc or HTTP test client
-  // MockBean/stub the Facade/Service
-
-  @Test
-  // "GET /v1/{resource} - should return 200 with data"
-  void filter_shouldReturn200() {
-    // Given — stub facade/service
-    // When  — perform HTTP GET
-    // Then  — assert status 200 and response body
-  }
-
-  @Test
-  // "POST /v1/{resource} - should return 201 when valid"
-  void create_shouldReturn201() {
-    // Given — stub facade/service
-    // When  — perform HTTP POST with valid body
-    // Then  — assert status 201
-  }
-
-  @Test
-  // "POST /v1/{resource} - should return 400 when invalid"
-  void create_shouldReturn400WhenInvalid() {
-    // Given — no stub needed
-    // When  — perform HTTP POST with missing required fields
-    // Then  — assert status 400
-  }
-}
-```
-
-### File Placement
-
-Theo cấu trúc test của dự án từ CLAUDE.md. Điển hình:
-```
-src/test/{language}/{package}/
-├── service/impl/{Resource}ServiceImplTest.{ext}
-├── facade/impl/{Resource}FacadeImplTest.{ext}  (if applicable)
-└── controller/{Resource}ControllerTest.{ext}
-```
-
-### Self-Review Checklist
-
-- [ ] Tag `@trace.verifies` trên mỗi test class
-- [ ] Mỗi scenario trong .feature có ít nhất một test
-- [ ] Chỉ mock đúng layer (không mock repo trong controller test)
-- [ ] Test name theo pattern `methodName_whenCondition_shouldOutcome`
-- [ ] Không có debug print trong test
-
-### Output
-
-```
-/dev-gen-test Complete — {UC-ID}:
-  ✅ service/{Service}Test.{ext} ({M} tests)
-  ✅ facade/{Facade}Test.{ext} ({M} tests)
-  ✅ controller/{Controller}Test.{ext} ({M} tests)
-```
-
-{{include:steps/report-footer.md}}
-
----
-
-## /dev-run-test — Run Tests & Report Results
-
-### Gate
-
-{{include:steps/context-loader.md}}
-
-Xác định service/module từ argument (UC-ID hoặc tên service).
-Đọc `conventions.test_command` từ project context đã nạp.
-
-### Run
-
-```bash
-# Run all tests in module
-{TEST_COMMAND}
-
-# Run specific test class (faster)
-{TEST_COMMAND_FOR_CLASS}
-
-# Run by pattern
-{TEST_COMMAND_BY_PATTERN}
-```
-
-### Analyze Results
-
-#### Khi test PASS
-
-```
-✅ Tests passed
-- Total: {N}
-- Passed: {N}
-- Duration: {X}s
-```
-
-#### Khi test FAIL — Debug Mode
-
-Đọc stack trace và phân tích:
-
-| Error Pattern | Nguyên nhân thường gặp | Suggested Fix |
-|---|---|---|
-| NullPointerException trong test | Thiếu setup mock | Kiểm tra setup `given(...)` cho dependency null |
-| Bean/dependency not found | Thiếu khai báo mock/stub | Thêm mock cho dependency thiếu |
-| Expected 200 but got 403 | Thiếu setup auth trong test | Thêm auth user/role vào test context |
-| Expected 200 but got 400 | Request body fail validation | Kiểm tra field bắt buộc trong request DTO |
-| LazyInitializationException | Lazy collection truy cập ngoài transaction | Thêm `@Transactional` trên test hoặc dùng eager fetch |
-| Mapper/mapper implementation not found | Code generator (vd MapStruct) chưa chạy | Chạy compile trước khi test |
-
-### Output
-
-```
-/dev-run-test Report — {service}
-Run at: {datetime}
-
-## Summary
-✅ Passed: {N} | ❌ Failed: {M} | ⏭️ Skipped: {K}
-Duration: {X}s
-
-## Failed Tests
-| Test | Error | Root Cause |
-|------|-------|-----------|
-| {TestClass}.{method} | {exception} | {analysis} |
-
-## Recommendations
-{specific fix for each failure}
-```
-
-{{include:steps/report-footer.md}}
-
----
-
-## /dev-smoke-test — Test Live API Endpoints
-
-Dùng khi service **đang chạy sẵn** để verify endpoint hoạt động đúng.
-Khác `/dev-run-test` (chạy unit/integration test không cần live server).
-
-### Phase 1 — Find Service URL
-
-{{include:steps/context-loader.md}}
-
-Đọc `conventions.service_run` từ project context đã nạp để tìm port.
-Default: `http://localhost:8080`
-
-Kiểm tra service đang chạy:
-```bash
-curl -s http://localhost:{port}/health
-# or /actuator/health for Spring Boot
-```
-
-Nếu chưa chạy: "Service is not running. Start it with: `{RUN_COMMAND}` from your project root."
-
-### Phase 2 — Identify Endpoints
-
-Từ UC-ID → tìm Controller có `@trace.implements={UC-ID}`:
-- Liệt kê: method, path, auth/role bắt buộc
-
-### Phase 3 — Get Auth Token (nếu cần)
-
-Nếu endpoint yêu cầu auth, hỏi:
-```
-This endpoint requires authentication. Options:
-1. Paste your Bearer token (from Postman / browser DevTools / test login)
-2. Use a test/dev token from your local config
-3. Skip auth — only test public endpoints
-```
-
-### Phase 4 — Run Smoke Test
-
-```bash
-# GET
-curl -s -X GET "http://localhost:{port}/v1/{resource}?page=0&size=5" \
-  -H "Authorization: Bearer {token}" | {JSON_FORMATTER}
-
-# POST
-curl -s -X POST "http://localhost:{port}/v1/{resource}" \
-  -H "Authorization: Bearer {token}" \
-  -H "Content-Type: application/json" \
-  -d '{"field1": "test_value"}'
-```
-
-### Phase 5 — Interpret Results
-
-| Result | Ý nghĩa |
-|--------|---------|
-| 200/201 + đúng data | ✅ OK |
-| 200 + sai data | ⚠️ Logic bug → dùng `/debug` |
-| 400 | Request body sai → kiểm tra field bắt buộc |
-| 401 | Token hết hạn hoặc sai realm |
-| 403 | Sai role → kiểm tra auth config |
-| 500 + stacktrace | Server error → dán vào `/debug` |
-| Connection refused | Service chưa chạy hoặc sai port |
-
-Nếu có lỗi trong log:
-```bash
-tail -n 100 {LOG_FILE_PATH}
-```
-
-### Output
-
-```
-/dev-smoke-test Report — {UC-ID}
-Tested at: {datetime}
-Base URL: http://localhost:{port}
-
-## Endpoints Tested
-| Method | Path | Status | Result |
-|--------|------|--------|--------|
-| GET    | /v1/{resource} | 200 ✅ | 5 records returned |
-| POST   | /v1/{resource} | 201 ✅ | Created id=42 |
+## /dev-gen-test — Sinh test dev self-check
+→ **Đọc và tuân theo `commands/dev-gen-test.md`** với cùng `$ARGUMENTS`.
 
-## Issues Found
-{describe any failures}
-```
+## /dev-run-test — Chạy test & ghi `dev_selftest`
+→ **Đọc và tuân theo `commands/dev-run-test.md`** với cùng `$ARGUMENTS`.
+(Command lo: bảng phân tích lỗi theo platform · ghi `dev_selftest`/`dev_selftest_at` vào trace TSV.)
 
-{{include:steps/report-footer.md}}
+## /dev-smoke-test — Smoke test service/app đang chạy
+→ **Đọc và tuân theo `commands/dev-smoke-test.md`** với cùng `$ARGUMENTS`.
+(Command lo: flow theo từng platform — backend curl/health · web E2E Playwright/Cypress · mobile device/emulator · LLM pipeline.)

package/steps/report-footer.md

@@ -60,7 +60,7 @@ Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
 | /define-product         | `/generate-prd {product-definition-file}`     |
 | /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
 | /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (rồi BDD sau khi sign-off); BE: `/generate-bdd {prd-file}` trực tiếp; sửa PRD nếu NEEDS_FIX |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
 | /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
 | /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
 | /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |

package/steps/spawn-agent.md

@@ -71,14 +71,18 @@ Dựng payload và gọi Agent tool cho từng UC:
 ```json
 {
   "_agent_mode": true,
-  "command":      "generate-bdd",
-  "uc_id":        "{TICKET-ID}-UC{N}",
-  "target_file":  "{đường dẫn tuyệt đối tới PRD hoặc feature file}",
-  "uc_section":   { "line_start": {N}, "line_end": {N} },
-  "context":      { "<context gọn từ Bước A>" }
+  "command":         "generate-bdd",
+  "uc_id":           "{TICKET-ID}-UC{N}",
+  "target_file":     "{đường dẫn tuyệt đối tới PRD hoặc feature file}",
+  "uc_section":      { "line_start": {N}, "line_end": {N} },
+  "context":         { "<context gọn từ Bước A>" },
+  "active_platform": "{web|app|system — platform orchestrator đã chọn ở Platform Selection}",
+  "design_coverage": { "<Screen States + AC-UI behavioral orchestrator đã trích ở 'Design Spec — Gate & Load' (B1); rỗng nếu BE / không có design-spec>" }
 }
 ```
 
+> **Truyền state orchestrator đã phân giải (quan trọng):** orchestrator (session chính) đã chạy các Guard + chọn platform + nạp design-spec MỘT LẦN *trước* khi spawn. Phải kèm `active_platform` và `design_coverage` vào payload để sub-agent áp đúng (đặc biệt phủ Screen States + AC-UI cho FE/App). KHÔNG kèm → sub-agent sinh BDD thiếu phần design (PRD lớn mất B1).
+
 > **Phạm vi lệnh**: Chỉ `/generate-bdd` khởi động chế độ orchestration. `/generate-code` và `/dev-gen-test` có thể chạy như sub-agent (chúng tôn trọng `_agent_mode: true` từ Gate Bước 0), nhưng không spawn thêm sub-agent — phạm vi của chúng vốn đã là một UC duy nhất.
 
 Serialize JSON này và truyền làm `$ARGUMENTS` khi gọi lệnh sub-agent.
@@ -108,8 +112,9 @@ Khi `gate.md Bước 0` phát hiện `_agent_mode: true`:
 2. **Bỏ qua context-loader.md** — dùng trực tiếp `payload.context`
 3. **Chỉ giới hạn ở `payload.uc_id`** — không xử lý các UC khác trong file
 4. Chỉ đọc section PRD giữa `payload.uc_section.line_start` và `line_end`
-5. Thực thi logic thường của lệnh cho riêng UC này
-6. Trả về JSON kết quả có cấu trúc (định dạng Bước E ở trên)
+5. **Dùng state orchestrator đã phân giải:** `active_platform` = `payload.active_platform`; `design_coverage` = `payload.design_coverage`. **KHÔNG chạy lại** các Guard (PRD approved / Design-Spec) hay tự nạp lại design-spec / hỏi platform — orchestrator đã làm một lần ở session chính.
+6. Thực thi logic thường của lệnh cho riêng UC này (dùng `design_coverage` từ payload để phủ Screen States + AC-UI)
+7. Trả về JSON kết quả có cấu trúc (định dạng Bước E ở trên)
 
 ---
 

package/templates/prd.template.md

@@ -197,11 +197,14 @@ _(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã
 
 # Change Log
 
-### v1.0 — {mô tả} ({date})
+> Hiện tại: **v1.0** ({date}) · Lịch sử đầy đủ → [changelog](./changelog/{TICKET}-{N}-{slug}.changelog.md) *(file kho chỉ tạo khi changelog vượt 5 version)*
 
-| Mục | Thay đổi |
-|-----|----------|
-| — | Bản đầu — sinh từ product-definition. |
+<!-- Bảng phẳng, MỘT dòng/version, MỚI NHẤT TRÊN CÙNG. Chỉ giữ tối đa 5 version gần nhất ở đây;
+     cũ hơn → /refine-prd & /review-context tự dồn (rollover) sang file changelog/ ở link trên. -->
+
+| Version | Date | Changes (UC/AC/BR bị ảnh hưởng) |
+|---------|------|---------------------------------|
+| 1.0 | {date} | Bản đầu — sinh từ product-definition. |
 
 ---
 

package/templates/project-context.yaml

@@ -14,7 +14,7 @@
 # 3. When a workflow says "→ key.subkey", look up that key
 #    and use the resolved value as the actual path
 # 4. All paths are RELATIVE to workspace root
-# 5. For "{domain}", substitute from spec's @trace.domain
+# 5. For "{domain}", substitute the feature's domain (PRD: row `Domain` in Metadata / folder path; .feature: @trace.domain)
 # =============================================================
 
 project:
@@ -132,7 +132,7 @@ domains:
 # With spec_source set, only ONE override is needed instead of four separate dir vars.
 #
 # services:                                   # domain → service submodule routing
-#   {{DOMAIN_1}}:                             # must match @trace.domain in PRD files
+#   {{DOMAIN_1}}:                             # must match the PRD's `Domain` (Metadata row) / folder path segment
 #     path: "{{SERVICE_SUBMODULE_DIR}}"       # relative path to service submodule (code + .trace/)
 #     module: "{{STACK_MODULE}}"              # e.g., java-spring, nextjs, flutter
 #     # NOTE: with spec_source set, BDD + tech-docs are cross-team and live in the spec repo —