@educa-corp/sdd-framework 0.2.6 → 0.2.8

package/commands/debug.md

@@ -55,7 +55,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.)*
@@ -141,6 +142,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:
@@ -153,6 +155,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/commands/define-product.md

@@ -52,7 +52,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.)*
@@ -138,6 +139,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:
@@ -150,6 +152,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.
@@ -481,6 +484,27 @@ Các từ như `cờ / flag`, `biến / trường / field`, `giá trị / value`
 **Checklist (dùng ở Quality Checklist của lệnh):** 0 thuật ngữ kỹ thuật/UI (re-render, UI, timeout, spinner, API/endpoint/token…) trong prose nghiệp vụ — đã diễn đạt lại (Nhóm 1) / chuyển Design Spec (Nhóm 2) / bỏ về Tech Docs (Nhóm 3); 0 ẩn dụ dữ liệu cho trạng thái đã có tên nghiệp vụ (cờ/giá trị/đọc-ghi khi là artifact — Nhóm 4) và 0 backtick bọc giá trị nghiệp vụ.
 
 
+---
+
+## Discovery Contract *(đọc trước — quyết định cách xử lý input của PO)*
+
+Lệnh này là **khai vấn (discovery)**, KHÔNG phải thu thập dữ liệu. Giá trị nằm ở **quá trình hỏi** — nó ép PO nói ra những gì chưa viết (edge case, out-of-scope, phụ thuộc, rule mâu thuẫn). Vì vậy:
+
+> **Input của PO là NGUYÊN LIỆU THÔ, KHÔNG phải câu trả lời thay thế phỏng vấn.**
+> Dù PO dán tài liệu dày cỡ nào — **vẫn đi hết Phase 1→7, mọi CHECKPOINT vẫn phải nổ.** TUYỆT ĐỐI KHÔNG coi input là "đã trả lời" rồi nhảy phase. Đây là điểm khác biệt cốt lõi so với các lệnh thu thập dữ kiện (generate-code/architecture "vét nguồn rồi mới hỏi") — ở discovery, **không có luật skip-if-answered.**
+
+**Cơ chế Confirm-vs-Ask** *(áp cho mọi câu hỏi ở Phase 1–6)*:
+- **Item input ĐÃ phủ** → KHÔNG skip. Trình bản nháp đã trích, đánh dấu `🤖 trích từ input` và hỏi PO **xác nhận / sửa / bổ sung**:
+  ```
+  🤖 Trích từ input: "{nội dung AI hiểu được}"
+  → Đúng chưa? Cần sửa/bổ sung gì không?
+  ```
+  Chỉ khi PO chốt mới nâng dấu thành `✅ PO xác nhận` và đi tiếp.
+- **Item input CHƯA phủ** → hỏi mới bình thường.
+- **Nghịch lý độ dày:** input càng dày → GAP tiềm ẩn càng nhiều (đó là thứ PO *chưa nghĩ tới*), nên phần soi hở ở **Phase 3 càng phải sâu**, KHÔNG được rút ngắn. Input dày tạo *ảo giác đủ* — đừng mắc bẫy.
+
+**Phân biệt dấu (bắt buộc, để chống blitz):** trong file output, mỗi dữ kiện mang một trong hai dấu — `✅ PO xác nhận` (PO đã chốt trực tiếp) hoặc `🤖 AI trích — chờ PO chốt`. Một phase CHỈ được đóng khi mọi item của nó mang dấu `✅`. Không tự nâng `🤖`→`✅` thay PO.
+
 ---
 
 ## Phase 0 — Knowledge Sync *(AI tự điền — bối cảnh hệ thống, KHÔNG phải yêu cầu nghiệp vụ; không cần input PO)*
@@ -511,6 +535,8 @@ Lưu bản đồ thuật ngữ này vào file product-definition output dưới
 
 Hỏi **lần lượt từng câu một**, đợi PO trả lời rồi mới hỏi câu kế. Giữ giọng nghiệp vụ, thân thiện; nếu PO lúng túng, đưa một ví dụ ngắn để gợi ý. Tránh hỏi về giải pháp kỹ thuật ở phase này.
 
+> **Áp Confirm-vs-Ask (Discovery Contract):** với câu mà input PO đã phủ, ĐỪNG bỏ qua — trình bản nháp `🤖 trích từ input` rồi hỏi PO xác nhận/sửa/bổ sung; câu chưa phủ thì hỏi mới. Mọi câu 1–8 đều phải có một cú chạm xác nhận của PO trước khi tóm tắt.
+
 1. **Context**: Bối cảnh / lý do vì sao cần feature này?
 2. **Problem**: Vấn đề cụ thể cần giải quyết?
 3. **Goal**: Khi feature chạy ổn, kết quả nghiệp vụ bạn muốn thấy là gì? Mô tả *thành quả*, chưa cần cách làm.
@@ -529,6 +555,8 @@ Sau câu 8 → **tóm tắt lại toàn bộ** cho PO → chờ xác nhận →
 
 ## Phase 2 — User Flow Definition *(CHECKPOINT 2)*
 
+> **Áp Confirm-vs-Ask (Discovery Contract):** input phủ bước nào → trình bản nháp `🤖 trích từ input` để PO xác nhận/sửa; bước nào input im lặng (đặc biệt Edge Cases) → hỏi mới, KHÔNG tự bịa cho đủ bảng.
+
 Hỏi:
 1. **Entry Point**: Người dùng bắt đầu tương tác với feature này ở đâu?
 2. **Flow Steps**: Mô tả từng bước (dùng bảng):
@@ -550,6 +578,14 @@ Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
 
 Dựa trên Phase 1-2, AI xác định gap và hỏi các câu follow-up. Tiếp tục các vòng cho tới khi không còn Mục chưa giải quyết.
 
+> **BẮT BUỘC chạy ≥1 vòng — KHÔNG được bỏ qua kể cả khi input rất dày.** Đây là nơi bắt GAP mà PO *chưa nghĩ tới*, nên độ dày input KHÔNG làm giảm nhu cầu hỏi — mà **làm tăng**. AI phải chủ động thách thức các **vùng input im lặng**, tối thiểu soi 4 nhóm:
+> 1. **Edge case / luồng lỗi** chưa được nêu (input thiếu, điều kiện không thoả, thao tác đồng thời).
+> 2. **Out-of-scope mơ hồ** — ranh giới ticket chưa rõ, dễ phình phạm vi.
+> 3. **Phụ thuộc liên service** input ngầm giả định nhưng chưa xác nhận (dữ liệu/năng lực từ team khác).
+> 4. **Rule mâu thuẫn / chồng chéo** giữa các phát biểu trong input.
+>
+> Với mỗi item `🤖 AI trích — chờ PO chốt` còn sót từ Phase 1–2 → gom vào đây để PO chốt dứt điểm. **Không được nâng dấu `🤖`→`✅` thay PO.**
+
 ```
 ### Vòng {N}
 | # | Nhóm           | Câu hỏi    | PO trả lời |
@@ -642,6 +678,7 @@ Ghi `{paths.product_definitions_dir}/{TICKET-ID}-{slug}.md` theo `templates/prod
 
 **Cập nhật Metadata theo tiến độ (cho phép resume):**
 - Sau mỗi CHECKPOINT phase được chốt (`✅ PO xác nhận: Có`, hoặc với Phase 3 là `✅ CHECKPOINT 3: Không còn mục tồn đọng`) → cập nhật `Completed Phase` = số phase vừa xong và giữ `Status: in-progress`.
+- **Chống blitz:** một phase CHỈ được tính là chốt khi mọi item của nó mang dấu `✅ PO xác nhận` — nếu còn bất kỳ item `🤖 AI trích — chờ PO chốt` nào, phase đó CHƯA xong, KHÔNG được tăng `Completed Phase`.
 - Khi Phase 7 pass mà không còn GAP → đặt `Completed Phase: 7` và `Status: completed`.
 - Nếu discovery bị ngắt giữa chừng, file vẫn được ghi với `Completed Phase` phản ánh phase cao nhất đã xác nhận — buổi sau resume tiếp từ phase kế tiếp.
 

package/commands/define-product.tmpl

@@ -15,6 +15,27 @@
 
 ---
 
+## Discovery Contract *(đọc trước — quyết định cách xử lý input của PO)*
+
+Lệnh này là **khai vấn (discovery)**, KHÔNG phải thu thập dữ liệu. Giá trị nằm ở **quá trình hỏi** — nó ép PO nói ra những gì chưa viết (edge case, out-of-scope, phụ thuộc, rule mâu thuẫn). Vì vậy:
+
+> **Input của PO là NGUYÊN LIỆU THÔ, KHÔNG phải câu trả lời thay thế phỏng vấn.**
+> Dù PO dán tài liệu dày cỡ nào — **vẫn đi hết Phase 1→7, mọi CHECKPOINT vẫn phải nổ.** TUYỆT ĐỐI KHÔNG coi input là "đã trả lời" rồi nhảy phase. Đây là điểm khác biệt cốt lõi so với các lệnh thu thập dữ kiện (generate-code/architecture "vét nguồn rồi mới hỏi") — ở discovery, **không có luật skip-if-answered.**
+
+**Cơ chế Confirm-vs-Ask** *(áp cho mọi câu hỏi ở Phase 1–6)*:
+- **Item input ĐÃ phủ** → KHÔNG skip. Trình bản nháp đã trích, đánh dấu `🤖 trích từ input` và hỏi PO **xác nhận / sửa / bổ sung**:
+  ```
+  🤖 Trích từ input: "{nội dung AI hiểu được}"
+  → Đúng chưa? Cần sửa/bổ sung gì không?
+  ```
+  Chỉ khi PO chốt mới nâng dấu thành `✅ PO xác nhận` và đi tiếp.
+- **Item input CHƯA phủ** → hỏi mới bình thường.
+- **Nghịch lý độ dày:** input càng dày → GAP tiềm ẩn càng nhiều (đó là thứ PO *chưa nghĩ tới*), nên phần soi hở ở **Phase 3 càng phải sâu**, KHÔNG được rút ngắn. Input dày tạo *ảo giác đủ* — đừng mắc bẫy.
+
+**Phân biệt dấu (bắt buộc, để chống blitz):** trong file output, mỗi dữ kiện mang một trong hai dấu — `✅ PO xác nhận` (PO đã chốt trực tiếp) hoặc `🤖 AI trích — chờ PO chốt`. Một phase CHỈ được đóng khi mọi item của nó mang dấu `✅`. Không tự nâng `🤖`→`✅` thay PO.
+
+---
+
 ## Phase 0 — Knowledge Sync *(AI tự điền — bối cảnh hệ thống, KHÔNG phải yêu cầu nghiệp vụ; không cần input PO)*
 
 AI quét dự án và ghi:
@@ -43,6 +64,8 @@ Lưu bản đồ thuật ngữ này vào file product-definition output dưới
 
 Hỏi **lần lượt từng câu một**, đợi PO trả lời rồi mới hỏi câu kế. Giữ giọng nghiệp vụ, thân thiện; nếu PO lúng túng, đưa một ví dụ ngắn để gợi ý. Tránh hỏi về giải pháp kỹ thuật ở phase này.
 
+> **Áp Confirm-vs-Ask (Discovery Contract):** với câu mà input PO đã phủ, ĐỪNG bỏ qua — trình bản nháp `🤖 trích từ input` rồi hỏi PO xác nhận/sửa/bổ sung; câu chưa phủ thì hỏi mới. Mọi câu 1–8 đều phải có một cú chạm xác nhận của PO trước khi tóm tắt.
+
 1. **Context**: Bối cảnh / lý do vì sao cần feature này?
 2. **Problem**: Vấn đề cụ thể cần giải quyết?
 3. **Goal**: Khi feature chạy ổn, kết quả nghiệp vụ bạn muốn thấy là gì? Mô tả *thành quả*, chưa cần cách làm.
@@ -61,6 +84,8 @@ Sau câu 8 → **tóm tắt lại toàn bộ** cho PO → chờ xác nhận →
 
 ## Phase 2 — User Flow Definition *(CHECKPOINT 2)*
 
+> **Áp Confirm-vs-Ask (Discovery Contract):** input phủ bước nào → trình bản nháp `🤖 trích từ input` để PO xác nhận/sửa; bước nào input im lặng (đặc biệt Edge Cases) → hỏi mới, KHÔNG tự bịa cho đủ bảng.
+
 Hỏi:
 1. **Entry Point**: Người dùng bắt đầu tương tác với feature này ở đâu?
 2. **Flow Steps**: Mô tả từng bước (dùng bảng):
@@ -82,6 +107,14 @@ Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
 
 Dựa trên Phase 1-2, AI xác định gap và hỏi các câu follow-up. Tiếp tục các vòng cho tới khi không còn Mục chưa giải quyết.
 
+> **BẮT BUỘC chạy ≥1 vòng — KHÔNG được bỏ qua kể cả khi input rất dày.** Đây là nơi bắt GAP mà PO *chưa nghĩ tới*, nên độ dày input KHÔNG làm giảm nhu cầu hỏi — mà **làm tăng**. AI phải chủ động thách thức các **vùng input im lặng**, tối thiểu soi 4 nhóm:
+> 1. **Edge case / luồng lỗi** chưa được nêu (input thiếu, điều kiện không thoả, thao tác đồng thời).
+> 2. **Out-of-scope mơ hồ** — ranh giới ticket chưa rõ, dễ phình phạm vi.
+> 3. **Phụ thuộc liên service** input ngầm giả định nhưng chưa xác nhận (dữ liệu/năng lực từ team khác).
+> 4. **Rule mâu thuẫn / chồng chéo** giữa các phát biểu trong input.
+>
+> Với mỗi item `🤖 AI trích — chờ PO chốt` còn sót từ Phase 1–2 → gom vào đây để PO chốt dứt điểm. **Không được nâng dấu `🤖`→`✅` thay PO.**
+
 ```
 ### Vòng {N}
 | # | Nhóm           | Câu hỏi    | PO trả lời |
@@ -174,6 +207,7 @@ Ghi `{paths.product_definitions_dir}/{TICKET-ID}-{slug}.md` theo `templates/prod
 
 **Cập nhật Metadata theo tiến độ (cho phép resume):**
 - Sau mỗi CHECKPOINT phase được chốt (`✅ PO xác nhận: Có`, hoặc với Phase 3 là `✅ CHECKPOINT 3: Không còn mục tồn đọng`) → cập nhật `Completed Phase` = số phase vừa xong và giữ `Status: in-progress`.
+- **Chống blitz:** một phase CHỈ được tính là chốt khi mọi item của nó mang dấu `✅ PO xác nhận` — nếu còn bất kỳ item `🤖 AI trích — chờ PO chốt` nào, phase đó CHƯA xong, KHÔNG được tăng `Completed Phase`.
 - Khi Phase 7 pass mà không còn GAP → đặt `Completed Phase: 7` và `Status: completed`.
 - Nếu discovery bị ngắt giữa chừng, file vẫn được ghi với `Completed Phase` phản ánh phase cao nhất đã xác nhận — buổi sau resume tiếp từ phase kế tiếp.
 

package/commands/dev-gen-test.md

@@ -58,7 +58,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.)*
@@ -144,6 +145,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:
@@ -156,6 +158,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/commands/dev-run-test.md

@@ -58,7 +58,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.)*
@@ -144,6 +145,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:
@@ -156,6 +158,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/commands/dev-smoke-test.md

@@ -54,7 +54,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.)*
@@ -140,6 +141,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:
@@ -152,6 +154,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/commands/fix-bug.md

@@ -52,7 +52,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.)*
@@ -138,6 +139,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:
@@ -150,6 +152,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/commands/generate-architecture.md

@@ -65,7 +65,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.)*
@@ -156,6 +157,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:
@@ -168,6 +170,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/commands/generate-bdd.md

@@ -52,7 +52,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.)*
@@ -136,6 +137,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:
@@ -148,6 +150,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.