@educa-corp/sdd-framework 0.2.5 → 0.2.7

package/docs/02-concepts/pipeline-steps/06-code.md

@@ -70,12 +70,15 @@ Code là **hệ quả của spec, không phải nguồn**. Bước này biến s
 5. **Build verify** — chạy `{conventions.build_command}`, ≤3 retry.
 6. **Ghi trace row** vào `.tsv` (trong spec repo nếu umbrella — thao tác ghi liên-repo).
 
-**Phase cho Frontend:**
-| Phase | Ý nghĩa |
+**Mode theo phase × platform:**
+| Mode | Ý nghĩa |
 |-------|---------|
 | `--phase=ui` | FE Phase 1 — sinh UI + layer **mock API** từ System BDD contract |
-| `--phase=integration` | FE nối vào **BE contract thật** (đọc tech-design từ spec repo) |
-| *(default)* | Backend — sinh từ tech-design §4 |
+| `--phase=integration` | FE Phase 2 — **thay** mock bằng **BE contract thật** (đọc tech-design từ spec repo); UI đã có |
+| *(default, `web`/`app`)* | **`fe_full`** — sinh UI **+** wire API thật một lần, bỏ lớp mock |
+| *(default, `system`)* | Backend — sinh từ tech-design §4 |
+
+> Nhánh wire API thật (`integration` / `fe_full`) đi qua **DS4** (kiểm §4.5.4 đủ, vét nguồn rồi gộp-hỏi) và **DS5** (phát hiện component/service FE đang chạy → hỏi reuse/new, không dựng song song). Bảng hành vi đầy đủ từng bước → [Explain · generate-code](../../explain/09-generate-code.md#hành-vi-theo-mode-phase--platform).
 
 **`/review-code`** — read-only, chỉ báo findings (không tự sửa: "AI tự fix tự review" = lặp lỗi).
 **`/fix-bug`** — sửa lỗi có root-cause + regression test; xem [Feedback Loop](10-feedback-loop.md).

package/docs/03-guides/developer.md

@@ -42,12 +42,15 @@ flowchart LR
 
 ---
 
-## Frontend: hai phase
+## Frontend: hai phase, hoặc một lần (full)
 
-| Phase | Khi nào | Việc |
+| Mode | Khi nào | Việc |
 |-------|---------|------|
 | `--phase=ui` | BE contract chưa sẵn | Sinh UI + layer **mock API** từ System BDD |
-| `--phase=integration` | BE contract `approved` | Nối vào contract thật (đọc tech-design từ spec repo) |
+| `--phase=integration` | BE contract `approved`, UI đã có | Nối vào contract thật (đọc tech-design từ spec repo) |
+| **không flag** (`fe_full`) | contract sẵn, muốn làm dứt điểm | Sinh UI **+** wire API thật một lần, bỏ lớp mock |
+
+> Cả `integration` lẫn `fe_full` đều qua **DS4** (kiểm §4.5.4 đủ trước khi wire; vét nguồn rồi gộp-hỏi thay vì hỏi live) và **DS5** (thấy component/service FE đang chạy thì **hỏi reuse/new**, không im lặng dựng mới). Bảng hành vi đầy đủ theo từng mode → [Explain · generate-code](../explain/09-generate-code.md#hành-vi-theo-mode-phase--platform).
 
 ---
 

package/docs/explain/09-generate-code.md

@@ -15,7 +15,7 @@ Code là **hệ quả của spec**. Command biến scenario thành code sao cho:
 ## Vị trí & tiền đề
 
 - **Vị trí:** Phase Implementation, sau BDD + tech-docs.
-- **Gate vào:** cảnh báo mềm DS1 (BDD chưa approved), DS2 (design-spec), DS3 (tech-doc contract).
+- **Gate vào:** cảnh báo mềm DS1 (BDD chưa approved), DS2 (design-spec), DS3 (tech-doc contract BE), **DS4** (client contract §4.5.4) + **DS5** (FE reuse gate) — DS4/DS5 chỉ khi wire API thật (`integration`/`fe_full`). Xem [Hành vi theo mode](#hành-vi-theo-mode-phase--platform).
 
 ---
 
@@ -30,7 +30,7 @@ Code là **hệ quả của spec**. Command biến scenario thành code sao cho:
 ## Các bước xử lý (chi tiết)
 
 1. **Guard BDD & Design Spec** — DS1/DS2/DS3 cảnh báo mềm nếu nguồn chưa chốt.
-2. **Phase Detection** — `--phase=ui` (FE Phase 1: UI + mock API; **mock source hybrid** = ưu tiên tech-doc §4 contract, fallback System BDD) · `--phase=integration` (thay mock bằng API thật) · default (BE/full-stack). `system` → bỏ flag.
+2. **Phase Detection** — `--phase=ui` (FE Phase 1: UI + mock API; **mock source hybrid** = ưu tiên tech-doc §4 contract, fallback System BDD) · `--phase=integration` (thay mock bằng API thật) · **`fe_full`** (default trên `web`/`app`: UI + real API một lần, bỏ mock) · default BE (`system`, full backend). Chi tiết: [Hành vi theo mode](#hành-vi-theo-mode-phase--platform).
 3. **Figma Dev Mode MCP Check** (sinh UI) — đọc frame Figma độ trung thực cao cho codegen.
 4. **Read Trace State** — so `bdd_version`/spec với `.tsv` → phân loại **new / drifted / synced-skip**.
 5. **Package Placement** — đặt code đúng `code_base_package` + strategy (by-layer/by-feature), chống phân mảnh.
@@ -42,11 +42,47 @@ Code là **hệ quả của spec**. Command biến scenario thành code sao cho:
 8. **CHECKPOINT — Code Generation Plan** — 🛑 trình: scenarios (X new, Y drifted, Z synced-skip) · CREATE (mới) · **EXTEND (ADD-ONLY, cấm full Write)** · **FILL** (lấp stub tại chỗ, không đẻ method song song) · SKIP + danh sách member GIỮ NGUYÊN (UC khác). **Scope Lock**: chỉ đọc/implement UC target.
 9. **Branch** `feature/{TICKET}-{slug}`.
 10. **Generate** theo **thứ tự layer từ CLAUDE.md §2**; tag `@trace.implements/source` ở boundary.
-11. **Mock/Integration** — layer mock (`--phase=ui`) hoặc thay adapter thật (`--phase=integration`).
+11. **Mock/Integration** — layer mock (`--phase=ui`) · thay adapter thật (`--phase=integration`) · wire real thẳng (`fe_full`). Nhánh wire API thật đi qua **DS4** (kiểm §4.5.4 đủ + **SRC-CHAIN** vét nguồn, gộp-hỏi thay vì hỏi live).
 12. **Self-Review (3 vòng)** → **Build Verify** (`{build_command}`, ≤3 retry) → **Write Trace State** → **Refresh Panel Mirror** (Living Docs umbrella) → **Commit** (sau khi duyệt).
 
 ---
 
+## Hành vi theo mode (Phase × Platform)
+
+`generate-code` rẽ nhánh theo `--phase` và platform của `.feature`. Bốn mode:
+
+- **`--phase=ui`** — FE Phase 1: chỉ UI + mock, không chạm API thật (prototype nhanh).
+- **`--phase=integration`** — FE Phase 2: **không** sinh lại UI, chỉ **thay** mock bằng real adapter.
+- **`fe_full`** — default (không flag) trên feature `web`/`app`: UI **+** wire API thật trong một lần, bỏ lớp mock trung gian.
+- **default BE** — không flag trên `system`: full backend.
+
+| Bước / Gate | `--phase=ui` | `--phase=integration` | `fe_full` (default web/app) | default BE (`system`) |
+|---|:--:|:--:|:--:|:--:|
+| **DS1** — BDD `approved` guard | ✅ | ✅ | ✅ | ✅ |
+| **DS2** — design-spec guard (FE) | ✅ | ✅ | ✅ | — |
+| **DS3** — BE contract gate (§4) | — | — | — | ✅ |
+| **DS4** — client contract gate (§4.5.4) | ⏭️ cố ý | ✅ | ✅ | — |
+| **DS5** — FE component/service reuse gate | ⏭️ | ✅ | ✅ | — |
+| **Sinh UI** (Figma MCP, component, state) | ✅ | ⏭️ giữ UI cũ | ✅ | — |
+| **Test Selectors** (emit test-id) | ✅ | ⏭️ | ✅ | — |
+| **Mock API Layer** | ✅ | ⏭️ | ⏭️ | — |
+| **Integration Phase** (real API adapter) | ⏭️ | ✅ | ✅ | — |
+| **Wire-up API** | dùng **mock** | **lật** mock→real | wire **thẳng** real | — (BE là API) |
+| **SRC-CHAIN** (vét nguồn trước khi hỏi) | ✅¹ | ✅ | ✅ | ✅ |
+| **Nguồn shape/contract** | §4 nếu có, else System BDD | §4.5.4 → §4.1–4.3 | §4.5.4 → §4.1–4.3 (+ design-spec) | §4 (DS3, nguyên văn) |
+| **Output adapter** | `{UC}MockApiAdapter` | `{UC}ApiAdapter` (giữ mock) | `{UC}ApiAdapter` (không mock) | — |
+| **Trace `fe_phase`** | `ui` | `integrated` | `integrated` | `—` |
+
+<sub>✅ chạy · ⏭️ bỏ qua (có chủ đích) · — không áp dụng. ¹SRC-CHAIN là quy tắc chung, active mọi mode; chỉ được **gom-hỏi qua DS4** ở integration/fe_full.</sub>
+
+**Bất đối xứng đáng nhớ:**
+- **DS4** có ở mọi nhánh wire API thật (integration + fe_full), **trừ** `ui` (cố ý) và BE (BE dùng DS3).
+- **Mock API Layer** là thứ **duy nhất** riêng `--phase=ui`.
+- **Sinh UI** có ở `ui` và `fe_full`, **không** ở `integration` (giả định UI đã có từ pha ui).
+- **`fe_full` = `ui` + `integration`** gộp một lần (bỏ mock), nhưng **vẫn giữ safety gate DS4** — không phải đường tắt kém an toàn.
+
+---
+
 ## Checkpoint & Gate
 
 - 🛑 **Comprehension checkpoint** (Code Generation Plan) — điểm dừng chính; Dev xác nhận drift + scope đúng.
@@ -59,6 +95,8 @@ Code là **hệ quả của spec**. Command biến scenario thành code sao cho:
 - **Seam & Stub Ledger** — cơ chế tinh vi nhất: giải quyết vấn đề "sinh code từng BDD rời tạo hàm mồ côi". `READY` là cờ 🔴 để lần sau nối hàng thật vào.
 - **Scope Lock + ADD-ONLY + FILL** — bảo toàn code UC khác trong file dùng chung; EXTEND chỉ Edit thêm, FILL lấp stub tại chỗ.
 - **Mock source hybrid** — mock shape ưu tiên contract thật để đỡ rework lúc integration.
+- **SRC-CHAIN + DS4** — "vét cạn nguồn trước khi hỏi": khi §4.5.4 thiếu, quét lần lượt PRD/BDD/design-spec/core-entities/mock adapter (skip-if-answered) rồi **gộp mọi gap vào một checkpoint** thay vì hỏi live từng câu. DS4 là cổng đối xứng với DS3 của BE cho nhánh FE wire API thật (integration/fe_full).
+- **DS5 — FE reuse gate** ("discover & reuse trước khi dựng mới"): ở nhánh wire API thật, nếu **không có mock adapter** (chạy `--phase=integration` một mình trên app brownfield) nhưng **quét thấy component/service FE đang chạy** → **hỏi reuse/new** thay vì im lặng dựng adapter song song, mồ côi. Chọn *reuse* → EXTEND/wire vào code có sẵn.
 - **3 vòng self-review + build ≤3 retry** — hai lớp tự kiểm trước khi giao.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/sdd-framework",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Spec Driven Development workflow framework for Claude Code",
   "bin": {
     "sdd-framework": "./bin/index.js"

package/steps/context-loader.md

@@ -42,6 +42,7 @@ Thực hiện các bước theo đúng thứ tự. Lưu mọi thứ vào bộ nh
 - `paths.business_dictionary` → path tới business-dictionary.md
 - `paths.core_entities` → path tới core-entities.md
 - `paths.tech_docs_dir` → gốc tài liệu kỹ thuật (gộp với specs_dir trong bố cục feature-package — tech-docs nằm dưới `{specs_dir}/{domain}/{prd-slug}/tech-docs/`)
+- `paths.src_dir` → gốc mã nguồn (nơi generate-code đặt & quét code; nguồn chính cho FE + phạm vi reuse-scan của DS5)
 - `paths.trace_dir` → thư mục trạng thái trace; cấu trúc: `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` (mỗi UC × platform một sổ)
 
 Nếu không có section `paths`, dùng các giá trị mặc định:
@@ -54,6 +55,7 @@ Nếu không có section `paths`, dùng các giá trị mặc định:
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
 - `core_entities` = `specs/domain-knowledge/core-entities.md`
 - `tech_docs_dir` = `specs`
+- `src_dir` = `src`
 - `trace_dir` = `.trace`
 
 Lưu ý: Trong bố cục feature-package, `specs_dir` là gốc thống nhất. Mọi loại spec artifact (PRD, BDD, tech-docs, design-spec) đều nằm dưới `{specs_dir}/{domain}/{prd-slug}/`. `prd-slug` là tên folder feature-package, không phải một biến config riêng.

package/steps/gate.md

@@ -49,7 +49,8 @@ Hiển thị và chờ phản hồi:
 
 ## Bước 1 — Xác định Target File
 
-1. Nếu `$ARGUMENTS` được cung cấp và trỏ tới một file tồn tại → dùng trực tiếp làm target.
+0. **Tách cờ trước khi resolve target.** `$ARGUMENTS` có thể lẫn các `--flag` (vd `--phase=integration`, `--comment`, `--fix`). **Loại bỏ mọi token bắt đầu bằng `--`** ra khỏi phần dùng để tìm target — chỉ giữ phần path/UC-ID/ticket. (Các flag đó do phần logic riêng của lệnh parse ở bước sau, KHÔNG phải tên file.)
+1. Nếu `$ARGUMENTS` (đã tách cờ) được cung cấp và trỏ tới một file tồn tại → dùng trực tiếp làm target.
 2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`):
    - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó.
    - **Lệnh PRD** (target là file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)*

package/templates/project-context.yaml

@@ -35,6 +35,12 @@ paths:
   # prd-slug is derived from the PRD folder path — not a separate config variable.
   specs_dir: "specs"
   templates_dir: "specs/templates"
+
+  # Source code root — gốc mã nguồn của service/app này (nơi generate-code đặt & quét code).
+  # BE thường suy vị trí từ CLAUDE.md §2 (code_base_package + layer); src_dir là gốc chung,
+  # và là NGUỒN CHÍNH cho FE (component/hook/service/adapter) + phạm vi quét reuse (DS5).
+  # Ví dụ: "src" (mono FE), "app/src", "src/main/java" (BE). Chỉnh theo layout thật của repo.
+  src_dir: "src"
   feature_template: ".agent/templates/feature.template"   # SoT skeleton .feature (dùng bởi /generate-bdd qua {{include}})
   bdd_writing_guide: "specs/templates/bdd-writing-guide.md"
   trace_report: "specs/.trace/trace-report.md"