@edupia-tutor/spec-driven-docs 0.14.1 → 0.14.3

package/bin/index.js

@@ -11,6 +11,7 @@ const VERSION  = pkg.version;
 
 const args = process.argv.slice(2);
 const isMigrateSpecs = args.includes('--migrate-specs');
+const isRenamePrd    = args.includes('--rename-prd-files');
 const isInit     = args.includes('--init');
 const isProject  = args.includes('--project');
 const installHooks = args.includes('--hooks');
@@ -73,8 +74,12 @@ if (showHelp) {
   console.log('Maintenance:');
   console.log('  --migrate-specs           Migrate an existing project from the legacy artifact-type-first');
   console.log('                            spec layout (specs/prd, specs/bdd, ...) to the feature-package');
-  console.log('                            layout (specs/{domain}/{prd-slug}/{prd.md,bdd/,tech-docs/,...}).');
+  console.log('                            layout (specs/{domain}/{prd-slug}/{ {TICKET-ID}-{prd-slug}.md,bdd/,...}).');
   console.log('                            DRY-RUN by default; add --apply to execute. Uses git mv when possible.');
+  console.log('  --rename-prd-files        Rename feature-package PRD files from the old fixed name prd.md to the');
+  console.log('                            {TICKET-ID}-{prd-slug}.md convention (e.g. SEG01-segment-scoring-service.md).');
+  console.log('                            For projects already on the feature-package layout. DRY-RUN by default;');
+  console.log('                            add --apply to execute. Uses git mv when possible.');
   console.log('');
   console.log('Options:');
   console.log('  --module <name>           Copy stack module to .agent/modules/<name>/');
@@ -108,6 +113,12 @@ if (isMigrateSpecs) {
   return; // migrate-specs.js calls process.exit itself
 }
 
+// ── --rename-prd-files: rename feature-package prd.md → {TICKET-ID}-{slug}.md ──
+if (isRenamePrd) {
+  require(path.join(__dirname, '..', 'scripts', 'rename-prd-files.js'));
+  return; // rename-prd-files.js calls process.exit itself
+}
+
 // ── Step 1: Build .tmpl → .md ─────────────────────────────────────────────
 const buildScript = path.join(__dirname, 'build.js');
 if (fs.existsSync(buildScript)) {

package/commands/debug.md

@@ -57,13 +57,13 @@ Hiển thị và chờ phản hồi:
 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.
 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à `prd.md`): `{specs_dir}/{domain}/*/prd.md` (khớp feature folder có id tương ứng), nếu không thì `{specs_dir}/*/*/prd.md`.
+   - **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.)*
    - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
    - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
 
    Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
 3. Nếu `$ARGUMENTS` rỗng hoặc không tìm thấy file khớp:
-   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/prd.md` cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
+   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/*.md` — file PRD ở gốc mỗi feature folder — cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
    - Hiển thị danh sách cho người dùng và hỏi: "Bạn muốn làm việc với file nào? (Nhập số thứ tự hoặc tên file)"
    - Chờ người dùng chọn rồi mới tiếp tục.
 
@@ -131,7 +131,7 @@ Thực hiện các bước theo đúng thứ tự. Lưu mọi thứ vào bộ nh
 - `domains` → danh sách các business domain đang hoạt động
 
 **Paths (nếu có):**
-- `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{prd.md | bdd/ | tech-docs/ | design-spec/}`
+- `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{ {TICKET-ID}-{prd-slug}.md | bdd/ | tech-docs/ | design-spec/}` (file PRD đặt tên `{TICKET-ID}-{prd-slug}.md`, là file `.md` duy nhất ở gốc feature folder)
 - `paths.refinement_dir` → thư mục output cho findings/review
 - `paths.qc_dir` → gốc artifact QC automation (hiện ở top-level, mỗi UC một thư mục con: `{qc_dir}/{UC-ID}/`)
 - `paths.qc_skills_dir` → nơi các lệnh qc-* nạp QC skill (mặc định bundled `.agent/skills/qc`; override sang repo/submodule riêng của team QC để bản nâng cấp framework không ghi đè)
@@ -157,7 +157,7 @@ Nếu không có section `paths`, dùng các giá trị mặc định:
 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.
 
 **Cách trích xuất `prd_slug` (đúng cho MỌI target file, bất kể độ sâu lồng nhau):** với một path target dạng `{specs_dir}/{domain}/{prd-slug}/...`, lấy **segment path đầu tiên sau `{specs_dir}/{domain}/`** — tức vị trí `{prd-slug}`. KHÔNG dùng folder cha trực tiếp của file, vì artifact BDD/tech-docs/design-spec lồng sâu hơn một hoặc hai cấp bên trong package. Ví dụ:
-- `specs/payment/create-invoice/prd.md` → `prd_slug = create-invoice`
+- `specs/payment/create-invoice/PAY01-create-invoice.md` → `prd_slug = create-invoice`
 - `specs/payment/create-invoice/bdd/system/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `system`)*
 - `specs/payment/create-invoice/bdd/web/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `web`)*
 - `specs/payment/create-invoice/tech-docs/PAY-UC1-tech-design.md` → `prd_slug = create-invoice` *(KHÔNG phải `tech-docs`)*
@@ -178,7 +178,7 @@ Nếu có section `services`:
 **1. Phát hiện active domain** (theo thứ tự ưu tiên):
 - Đọc `@trace.domain` từ frontmatter của target file (nếu Gate đã nạp một target file)
 - Trích xuất từ path target file: `domain` = segment đầu tiên sau base path `specs_dir`; `prd_slug` = segment kế tiếp (folder feature-package). Điều này đúng ở mọi độ sâu target — xem quy tắc trích xuất `prd_slug` ở Bước 1.  
-  *(vd: `specs/user/create-account/prd.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
+  *(vd: `specs/user/create-account/USR01-create-account.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
 - Nếu `$ARGUMENTS` chứa một path, trích xuất segment domain sau `specs_dir`
 
 **2. Route tới service** — nếu active domain khớp với một key trong `services`:

package/commands/define-product.md

@@ -1,4 +1,4 @@
-# /define-product — Feature Discovery (Q&A 8 Phase)
+# /define-product — Khám phá tính năng (Q&A 8 Phase)
 
 ## Gate
 # Gate — Quy trình vào chuẩn cho mọi lệnh
@@ -54,13 +54,13 @@ Hiển thị và chờ phản hồi:
 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.
 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à `prd.md`): `{specs_dir}/{domain}/*/prd.md` (khớp feature folder có id tương ứng), nếu không thì `{specs_dir}/*/*/prd.md`.
+   - **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.)*
    - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
    - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
 
    Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
 3. Nếu `$ARGUMENTS` rỗng hoặc không tìm thấy file khớp:
-   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/prd.md` cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
+   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/*.md` — file PRD ở gốc mỗi feature folder — cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
    - Hiển thị danh sách cho người dùng và hỏi: "Bạn muốn làm việc với file nào? (Nhập số thứ tự hoặc tên file)"
    - Chờ người dùng chọn rồi mới tiếp tục.
 
@@ -128,7 +128,7 @@ Thực hiện các bước theo đúng thứ tự. Lưu mọi thứ vào bộ nh
 - `domains` → danh sách các business domain đang hoạt động
 
 **Paths (nếu có):**
-- `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{prd.md | bdd/ | tech-docs/ | design-spec/}`
+- `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{ {TICKET-ID}-{prd-slug}.md | bdd/ | tech-docs/ | design-spec/}` (file PRD đặt tên `{TICKET-ID}-{prd-slug}.md`, là file `.md` duy nhất ở gốc feature folder)
 - `paths.refinement_dir` → thư mục output cho findings/review
 - `paths.qc_dir` → gốc artifact QC automation (hiện ở top-level, mỗi UC một thư mục con: `{qc_dir}/{UC-ID}/`)
 - `paths.qc_skills_dir` → nơi các lệnh qc-* nạp QC skill (mặc định bundled `.agent/skills/qc`; override sang repo/submodule riêng của team QC để bản nâng cấp framework không ghi đè)
@@ -154,7 +154,7 @@ Nếu không có section `paths`, dùng các giá trị mặc định:
 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.
 
 **Cách trích xuất `prd_slug` (đúng cho MỌI target file, bất kể độ sâu lồng nhau):** với một path target dạng `{specs_dir}/{domain}/{prd-slug}/...`, lấy **segment path đầu tiên sau `{specs_dir}/{domain}/`** — tức vị trí `{prd-slug}`. KHÔNG dùng folder cha trực tiếp của file, vì artifact BDD/tech-docs/design-spec lồng sâu hơn một hoặc hai cấp bên trong package. Ví dụ:
-- `specs/payment/create-invoice/prd.md` → `prd_slug = create-invoice`
+- `specs/payment/create-invoice/PAY01-create-invoice.md` → `prd_slug = create-invoice`
 - `specs/payment/create-invoice/bdd/system/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `system`)*
 - `specs/payment/create-invoice/bdd/web/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `web`)*
 - `specs/payment/create-invoice/tech-docs/PAY-UC1-tech-design.md` → `prd_slug = create-invoice` *(KHÔNG phải `tech-docs`)*
@@ -175,7 +175,7 @@ Nếu có section `services`:
 **1. Phát hiện active domain** (theo thứ tự ưu tiên):
 - Đọc `@trace.domain` từ frontmatter của target file (nếu Gate đã nạp một target file)
 - Trích xuất từ path target file: `domain` = segment đầu tiên sau base path `specs_dir`; `prd_slug` = segment kế tiếp (folder feature-package). Điều này đúng ở mọi độ sâu target — xem quy tắc trích xuất `prd_slug` ở Bước 1.  
-  *(vd: `specs/user/create-account/prd.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
+  *(vd: `specs/user/create-account/USR01-create-account.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
 - Nếu `$ARGUMENTS` chứa một path, trích xuất segment domain sau `specs_dir`
 
 **2. Route tới service** — nếu active domain khớp với một key trong `services`:
@@ -414,12 +414,12 @@ AI quét dự án và ghi:
 - **Chuẩn hoá thuật ngữ** — map mọi thuật ngữ trong input PO về thuật ngữ chuẩn từ business-dictionary.md.
 
 ```
-| Term in PO input | Canonical term (business-dictionary) |
-|------------------|--------------------------------------|
-| {original}       | {canonical}                          |
+| Thuật ngữ trong input PO | Thuật ngữ chuẩn (business-dictionary) |
+|--------------------------|---------------------------------------|
+| {thuật ngữ gốc}          | {thuật ngữ chuẩn}                     |
 ```
 
-Lưu bản đồ thuật ngữ này vào file product-definition output dưới section `## Terminology Map` — `/generate-prd` sẽ tham chiếu nó trong bước Terminology Rules để đảm bảo nhất quán.
+Lưu bản đồ thuật ngữ này vào file product-definition output dưới section `### Chuẩn hoá thuật ngữ` (trong Phase 0) — `/generate-prd` sẽ tham chiếu nó trong bước **Quy tắc thuật ngữ** để đảm bảo nhất quán.
 
 ---
 
@@ -433,12 +433,10 @@ Hỏi **lần lượt từng câu một**, đợi PO trả lời rồi mới h
 4. **Actors**: Những ai sẽ dùng feature này? Liệt kê từng vai trò, và đánh dấu ai là người dùng chính (Primary), ai phụ (Secondary).
 5. **In Scope**: Feature này làm gì? (mỗi dòng một chức năng — chỉ những gì thuộc ticket này)
 6. **Out of Scope**: Cái gì KHÔNG làm trong ticket này? Ghi rõ kèm lý do hoặc để dành pha/ticket sau — để tránh phình phạm vi.
-7. **User Story**: Xác nhận theo format:
-   ```
-   Là một (As a) {vai trò}
-   Tôi muốn (I want to) {mục tiêu}
-   Để (So that) {giá trị nghiệp vụ}
-   ```
+7. **User Story**: Xác nhận theo format (mỗi ý một bullet):
+   - **Là một (As a)** {vai trò}
+   - **Tôi muốn (I want to)** {mục tiêu}
+   - **Để (So that)** {giá trị nghiệp vụ}
 8. **Phụ thuộc liên service**: Để chạy được, feature có cần **dữ liệu hay năng lực** gì từ feature/team khác không? Mô tả ở mức nghiệp vụ (cần gì, từ ai, vì sao) — chưa cần nói API hay kỹ thuật. Nếu không có → trả lời "Không có".
 
 Sau câu 8 → **tóm tắt lại toàn bộ** cho PO → chờ xác nhận → ghi `✅ PO xác nhận: Có` → sang Phase 2.
@@ -451,7 +449,7 @@ 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):
    ```
-   | Step | Action (user) | Business State / Result | Notes |
+   | Bước | Hành động | Trạng thái/Kết quả nghiệp vụ | Ghi chú |
    ```
 3. **Exit Point**: Kết quả cuối khi flow hoàn thành là gì?
 4. **Edge Cases**: Các kịch bản thất bại nghiệp vụ ngoài happy path? (input thiếu, điều kiện không thoả, thao tác đồng thời, phụ thuộc không sẵn sàng → kết quả nghiệp vụ kỳ vọng)
@@ -462,21 +460,21 @@ Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
 
 ## Phase 3 — Clarification Log *(CHECKPOINT 3)*
 
-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 Unresolved Items.
+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.
 
 ```
-### Round {N}
-| # | Category       | Question   | PO Answer  |
+### Vòng {N}
+| # | Nhóm           | Câu hỏi    | PO trả lời |
 |---|----------------|------------|------------|
-| 1 | Context/Flow/Logic | {question} | {answer} |
+| 1 | Context/Flow/Logic | {câu hỏi} | {trả lời} |
 ```
 
-**BLOCK**: Nếu còn Unresolved Items → KHÔNG được sang Phase 4.
+**BLOCK**: Nếu còn Mục chưa giải quyết → KHÔNG được sang Phase 4.
 
-### Unresolved Items
-- {item — hoặc "None"}
+### Mục chưa giải quyết
+- {mục — hoặc "None"}
 
-Khi mọi Unresolved Items đã giải quyết → ghi `✅ CHECKPOINT 3: No Unresolved Items` → sang Phase 4.
+Khi mọi Mục chưa giải quyết đã xử lý → ghi `✅ CHECKPOINT 3: Không còn mục tồn đọng` → sang Phase 4.
 
 ---
 
@@ -485,9 +483,9 @@ Khi mọi Unresolved Items đã giải quyết → ghi `✅ CHECKPOINT 3: No Unr
 Suy ra từ Phase 1-3. Mỗi BR = một quy tắc (hệ thống PHẢI / KHÔNG được làm gì — WHAT):
 
 ```
-| Rule ID | Action / Trigger    | Rule                          | Condition           |
+| Rule ID | Hành động/Trigger   | Quy tắc                       | Điều kiện           |
 |---------|---------------------|-------------------------------|---------------------|
-| BR-1    | {action from flow}  | System MUST/MUST NOT...       | {applicable condition} |
+| BR-1    | {hành động từ flow} | System MUST/MUST NOT...       | {điều kiện áp dụng} |
 ```
 
 Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
@@ -513,9 +511,9 @@ Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
 Suy ra từ BR + User Story. Mỗi AC phải testable (pass/fail rõ ràng):
 
 ```
-| AC ID | Description             | Expected Behavior         | Derived from |
-|-------|-------------------------|---------------------------|--------------|
-| AC-1  | {criterion description} | {what system should do}   | BR-{N}       |
+| AC ID | Mô tả                   | Hành vi kỳ vọng            | Bắt nguồn từ |
+|-------|-------------------------|----------------------------|--------------|
+| AC-1  | {mô tả tiêu chí}        | {hành vi hệ thống cần làm} | BR-{N}       |
 ```
 
 Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
@@ -527,13 +525,13 @@ Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
 Tự sinh ma trận độ phủ:
 
 ```
-| Flow Action | Has Rule? | Has Logic? | Has AC? | Status  |
-|-------------|-----------|------------|---------|---------|
-| {Action 1}  | ✅/❌     | ✅/❌      | ✅/❌   | OK/GAP  |
+| Hành động Flow | Có Rule? | Có Logic? | Có AC? | Status |
+|----------------|----------|-----------|--------|--------|
+| {Hành động 1}  | ✅/❌    | ✅/❌     | ✅/❌  | OK/GAP |
 ```
 
-- **Conflicts Detected**: liệt kê các rule xung đột, hoặc "None".
-- **Missing Items**: liệt kê gap, hoặc "None".
+- **Xung đột phát hiện**: liệt kê các rule xung đột, hoặc "None".
+- **Mục còn thiếu**: liệt kê gap, hoặc "None".
 
 Nếu phát hiện GAP → cảnh báo PO và giải quyết trước khi đánh dấu completed.
 
@@ -544,7 +542,11 @@ Nếu phát hiện GAP → cảnh báo PO và giải quyết trước khi đánh
 Ghi `{paths.product_definitions_dir}/{TICKET-ID}-{slug}.md` theo `templates/product-definition.template.md`.
 
 Điền tất cả section bằng dữ liệu thu thập qua các phase.
-Đặt `Status: completed` khi Phase 7 pass mà không còn GAP.
+
+**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`.
+- 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.
 
 # Report Footer — Định dạng output chuẩn cho mọi lệnh
 

package/commands/define-product.tmpl

@@ -1,4 +1,4 @@
-# /define-product — Feature Discovery (Q&A 8 Phase)
+# /define-product — Khám phá tính năng (Q&A 8 Phase)
 
 ## Gate
 {{include:steps/gate.md}}
@@ -20,12 +20,12 @@ AI quét dự án và ghi:
 - **Chuẩn hoá thuật ngữ** — map mọi thuật ngữ trong input PO về thuật ngữ chuẩn từ business-dictionary.md.
 
 ```
-| Term in PO input | Canonical term (business-dictionary) |
-|------------------|--------------------------------------|
-| {original}       | {canonical}                          |
+| Thuật ngữ trong input PO | Thuật ngữ chuẩn (business-dictionary) |
+|--------------------------|---------------------------------------|
+| {thuật ngữ gốc}          | {thuật ngữ chuẩn}                     |
 ```
 
-Lưu bản đồ thuật ngữ này vào file product-definition output dưới section `## Terminology Map` — `/generate-prd` sẽ tham chiếu nó trong bước Terminology Rules để đảm bảo nhất quán.
+Lưu bản đồ thuật ngữ này vào file product-definition output dưới section `### Chuẩn hoá thuật ngữ` (trong Phase 0) — `/generate-prd` sẽ tham chiếu nó trong bước **Quy tắc thuật ngữ** để đảm bảo nhất quán.
 
 ---
 
@@ -39,12 +39,10 @@ Hỏi **lần lượt từng câu một**, đợi PO trả lời rồi mới h
 4. **Actors**: Những ai sẽ dùng feature này? Liệt kê từng vai trò, và đánh dấu ai là người dùng chính (Primary), ai phụ (Secondary).
 5. **In Scope**: Feature này làm gì? (mỗi dòng một chức năng — chỉ những gì thuộc ticket này)
 6. **Out of Scope**: Cái gì KHÔNG làm trong ticket này? Ghi rõ kèm lý do hoặc để dành pha/ticket sau — để tránh phình phạm vi.
-7. **User Story**: Xác nhận theo format:
-   ```
-   Là một (As a) {vai trò}
-   Tôi muốn (I want to) {mục tiêu}
-   Để (So that) {giá trị nghiệp vụ}
-   ```
+7. **User Story**: Xác nhận theo format (mỗi ý một bullet):
+   - **Là một (As a)** {vai trò}
+   - **Tôi muốn (I want to)** {mục tiêu}
+   - **Để (So that)** {giá trị nghiệp vụ}
 8. **Phụ thuộc liên service**: Để chạy được, feature có cần **dữ liệu hay năng lực** gì từ feature/team khác không? Mô tả ở mức nghiệp vụ (cần gì, từ ai, vì sao) — chưa cần nói API hay kỹ thuật. Nếu không có → trả lời "Không có".
 
 Sau câu 8 → **tóm tắt lại toàn bộ** cho PO → chờ xác nhận → ghi `✅ PO xác nhận: Có` → sang Phase 2.
@@ -57,7 +55,7 @@ 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):
    ```
-   | Step | Action (user) | Business State / Result | Notes |
+   | Bước | Hành động | Trạng thái/Kết quả nghiệp vụ | Ghi chú |
    ```
 3. **Exit Point**: Kết quả cuối khi flow hoàn thành là gì?
 4. **Edge Cases**: Các kịch bản thất bại nghiệp vụ ngoài happy path? (input thiếu, điều kiện không thoả, thao tác đồng thời, phụ thuộc không sẵn sàng → kết quả nghiệp vụ kỳ vọng)
@@ -68,21 +66,21 @@ Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
 
 ## Phase 3 — Clarification Log *(CHECKPOINT 3)*
 
-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 Unresolved Items.
+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.
 
 ```
-### Round {N}
-| # | Category       | Question   | PO Answer  |
+### Vòng {N}
+| # | Nhóm           | Câu hỏi    | PO trả lời |
 |---|----------------|------------|------------|
-| 1 | Context/Flow/Logic | {question} | {answer} |
+| 1 | Context/Flow/Logic | {câu hỏi} | {trả lời} |
 ```
 
-**BLOCK**: Nếu còn Unresolved Items → KHÔNG được sang Phase 4.
+**BLOCK**: Nếu còn Mục chưa giải quyết → KHÔNG được sang Phase 4.
 
-### Unresolved Items
-- {item — hoặc "None"}
+### Mục chưa giải quyết
+- {mục — hoặc "None"}
 
-Khi mọi Unresolved Items đã giải quyết → ghi `✅ CHECKPOINT 3: No Unresolved Items` → sang Phase 4.
+Khi mọi Mục chưa giải quyết đã xử lý → ghi `✅ CHECKPOINT 3: Không còn mục tồn đọng` → sang Phase 4.
 
 ---
 
@@ -91,9 +89,9 @@ Khi mọi Unresolved Items đã giải quyết → ghi `✅ CHECKPOINT 3: No Unr
 Suy ra từ Phase 1-3. Mỗi BR = một quy tắc (hệ thống PHẢI / KHÔNG được làm gì — WHAT):
 
 ```
-| Rule ID | Action / Trigger    | Rule                          | Condition           |
+| Rule ID | Hành động/Trigger   | Quy tắc                       | Điều kiện           |
 |---------|---------------------|-------------------------------|---------------------|
-| BR-1    | {action from flow}  | System MUST/MUST NOT...       | {applicable condition} |
+| BR-1    | {hành động từ flow} | System MUST/MUST NOT...       | {điều kiện áp dụng} |
 ```
 
 Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
@@ -119,9 +117,9 @@ Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
 Suy ra từ BR + User Story. Mỗi AC phải testable (pass/fail rõ ràng):
 
 ```
-| AC ID | Description             | Expected Behavior         | Derived from |
-|-------|-------------------------|---------------------------|--------------|
-| AC-1  | {criterion description} | {what system should do}   | BR-{N}       |
+| AC ID | Mô tả                   | Hành vi kỳ vọng            | Bắt nguồn từ |
+|-------|-------------------------|----------------------------|--------------|
+| AC-1  | {mô tả tiêu chí}        | {hành vi hệ thống cần làm} | BR-{N}       |
 ```
 
 Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
@@ -133,13 +131,13 @@ Xác nhận → ghi `✅ PO xác nhận: Có` → tiếp tục.
 Tự sinh ma trận độ phủ:
 
 ```
-| Flow Action | Has Rule? | Has Logic? | Has AC? | Status  |
-|-------------|-----------|------------|---------|---------|
-| {Action 1}  | ✅/❌     | ✅/❌      | ✅/❌   | OK/GAP  |
+| Hành động Flow | Có Rule? | Có Logic? | Có AC? | Status |
+|----------------|----------|-----------|--------|--------|
+| {Hành động 1}  | ✅/❌    | ✅/❌     | ✅/❌  | OK/GAP |
 ```
 
-- **Conflicts Detected**: liệt kê các rule xung đột, hoặc "None".
-- **Missing Items**: liệt kê gap, hoặc "None".
+- **Xung đột phát hiện**: liệt kê các rule xung đột, hoặc "None".
+- **Mục còn thiếu**: liệt kê gap, hoặc "None".
 
 Nếu phát hiện GAP → cảnh báo PO và giải quyết trước khi đánh dấu completed.
 
@@ -150,7 +148,11 @@ Nếu phát hiện GAP → cảnh báo PO và giải quyết trước khi đánh
 Ghi `{paths.product_definitions_dir}/{TICKET-ID}-{slug}.md` theo `templates/product-definition.template.md`.
 
 Điền tất cả section bằng dữ liệu thu thập qua các phase.
-Đặt `Status: completed` khi Phase 7 pass mà không còn GAP.
+
+**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`.
+- 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.
 
 {{include:steps/report-footer.md}}
 

package/commands/dev-gen-test.md

@@ -60,13 +60,13 @@ Hiển thị và chờ phản hồi:
 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.
 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à `prd.md`): `{specs_dir}/{domain}/*/prd.md` (khớp feature folder có id tương ứng), nếu không thì `{specs_dir}/*/*/prd.md`.
+   - **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.)*
    - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
    - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
 
    Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
 3. Nếu `$ARGUMENTS` rỗng hoặc không tìm thấy file khớp:
-   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/prd.md` cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
+   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/*.md` — file PRD ở gốc mỗi feature folder — cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
    - Hiển thị danh sách cho người dùng và hỏi: "Bạn muốn làm việc với file nào? (Nhập số thứ tự hoặc tên file)"
    - Chờ người dùng chọn rồi mới tiếp tục.
 
@@ -134,7 +134,7 @@ Thực hiện các bước theo đúng thứ tự. Lưu mọi thứ vào bộ nh
 - `domains` → danh sách các business domain đang hoạt động
 
 **Paths (nếu có):**
-- `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{prd.md | bdd/ | tech-docs/ | design-spec/}`
+- `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{ {TICKET-ID}-{prd-slug}.md | bdd/ | tech-docs/ | design-spec/}` (file PRD đặt tên `{TICKET-ID}-{prd-slug}.md`, là file `.md` duy nhất ở gốc feature folder)
 - `paths.refinement_dir` → thư mục output cho findings/review
 - `paths.qc_dir` → gốc artifact QC automation (hiện ở top-level, mỗi UC một thư mục con: `{qc_dir}/{UC-ID}/`)
 - `paths.qc_skills_dir` → nơi các lệnh qc-* nạp QC skill (mặc định bundled `.agent/skills/qc`; override sang repo/submodule riêng của team QC để bản nâng cấp framework không ghi đè)
@@ -160,7 +160,7 @@ Nếu không có section `paths`, dùng các giá trị mặc định:
 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.
 
 **Cách trích xuất `prd_slug` (đúng cho MỌI target file, bất kể độ sâu lồng nhau):** với một path target dạng `{specs_dir}/{domain}/{prd-slug}/...`, lấy **segment path đầu tiên sau `{specs_dir}/{domain}/`** — tức vị trí `{prd-slug}`. KHÔNG dùng folder cha trực tiếp của file, vì artifact BDD/tech-docs/design-spec lồng sâu hơn một hoặc hai cấp bên trong package. Ví dụ:
-- `specs/payment/create-invoice/prd.md` → `prd_slug = create-invoice`
+- `specs/payment/create-invoice/PAY01-create-invoice.md` → `prd_slug = create-invoice`
 - `specs/payment/create-invoice/bdd/system/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `system`)*
 - `specs/payment/create-invoice/bdd/web/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `web`)*
 - `specs/payment/create-invoice/tech-docs/PAY-UC1-tech-design.md` → `prd_slug = create-invoice` *(KHÔNG phải `tech-docs`)*
@@ -181,7 +181,7 @@ Nếu có section `services`:
 **1. Phát hiện active domain** (theo thứ tự ưu tiên):
 - Đọc `@trace.domain` từ frontmatter của target file (nếu Gate đã nạp một target file)
 - Trích xuất từ path target file: `domain` = segment đầu tiên sau base path `specs_dir`; `prd_slug` = segment kế tiếp (folder feature-package). Điều này đúng ở mọi độ sâu target — xem quy tắc trích xuất `prd_slug` ở Bước 1.  
-  *(vd: `specs/user/create-account/prd.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
+  *(vd: `specs/user/create-account/USR01-create-account.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
 - Nếu `$ARGUMENTS` chứa một path, trích xuất segment domain sau `specs_dir`
 
 **2. Route tới service** — nếu active domain khớp với một key trong `services`:

package/commands/dev-run-test.md

@@ -60,13 +60,13 @@ Hiển thị và chờ phản hồi:
 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.
 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à `prd.md`): `{specs_dir}/{domain}/*/prd.md` (khớp feature folder có id tương ứng), nếu không thì `{specs_dir}/*/*/prd.md`.
+   - **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.)*
    - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
    - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
 
    Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
 3. Nếu `$ARGUMENTS` rỗng hoặc không tìm thấy file khớp:
-   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/prd.md` cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
+   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/*.md` — file PRD ở gốc mỗi feature folder — cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
    - Hiển thị danh sách cho người dùng và hỏi: "Bạn muốn làm việc với file nào? (Nhập số thứ tự hoặc tên file)"
    - Chờ người dùng chọn rồi mới tiếp tục.
 
@@ -134,7 +134,7 @@ Thực hiện các bước theo đúng thứ tự. Lưu mọi thứ vào bộ nh
 - `domains` → danh sách các business domain đang hoạt động
 
 **Paths (nếu có):**
-- `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{prd.md | bdd/ | tech-docs/ | design-spec/}`
+- `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{ {TICKET-ID}-{prd-slug}.md | bdd/ | tech-docs/ | design-spec/}` (file PRD đặt tên `{TICKET-ID}-{prd-slug}.md`, là file `.md` duy nhất ở gốc feature folder)
 - `paths.refinement_dir` → thư mục output cho findings/review
 - `paths.qc_dir` → gốc artifact QC automation (hiện ở top-level, mỗi UC một thư mục con: `{qc_dir}/{UC-ID}/`)
 - `paths.qc_skills_dir` → nơi các lệnh qc-* nạp QC skill (mặc định bundled `.agent/skills/qc`; override sang repo/submodule riêng của team QC để bản nâng cấp framework không ghi đè)
@@ -160,7 +160,7 @@ Nếu không có section `paths`, dùng các giá trị mặc định:
 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.
 
 **Cách trích xuất `prd_slug` (đúng cho MỌI target file, bất kể độ sâu lồng nhau):** với một path target dạng `{specs_dir}/{domain}/{prd-slug}/...`, lấy **segment path đầu tiên sau `{specs_dir}/{domain}/`** — tức vị trí `{prd-slug}`. KHÔNG dùng folder cha trực tiếp của file, vì artifact BDD/tech-docs/design-spec lồng sâu hơn một hoặc hai cấp bên trong package. Ví dụ:
-- `specs/payment/create-invoice/prd.md` → `prd_slug = create-invoice`
+- `specs/payment/create-invoice/PAY01-create-invoice.md` → `prd_slug = create-invoice`
 - `specs/payment/create-invoice/bdd/system/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `system`)*
 - `specs/payment/create-invoice/bdd/web/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `web`)*
 - `specs/payment/create-invoice/tech-docs/PAY-UC1-tech-design.md` → `prd_slug = create-invoice` *(KHÔNG phải `tech-docs`)*
@@ -181,7 +181,7 @@ Nếu có section `services`:
 **1. Phát hiện active domain** (theo thứ tự ưu tiên):
 - Đọc `@trace.domain` từ frontmatter của target file (nếu Gate đã nạp một target file)
 - Trích xuất từ path target file: `domain` = segment đầu tiên sau base path `specs_dir`; `prd_slug` = segment kế tiếp (folder feature-package). Điều này đúng ở mọi độ sâu target — xem quy tắc trích xuất `prd_slug` ở Bước 1.  
-  *(vd: `specs/user/create-account/prd.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
+  *(vd: `specs/user/create-account/USR01-create-account.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
 - Nếu `$ARGUMENTS` chứa một path, trích xuất segment domain sau `specs_dir`
 
 **2. Route tới service** — nếu active domain khớp với một key trong `services`:

package/commands/dev-smoke-test.md

@@ -56,13 +56,13 @@ Hiển thị và chờ phản hồi:
 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.
 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à `prd.md`): `{specs_dir}/{domain}/*/prd.md` (khớp feature folder có id tương ứng), nếu không thì `{specs_dir}/*/*/prd.md`.
+   - **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.)*
    - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
    - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
 
    Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
 3. Nếu `$ARGUMENTS` rỗng hoặc không tìm thấy file khớp:
-   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/prd.md` cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
+   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/*.md` — file PRD ở gốc mỗi feature folder — cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
    - Hiển thị danh sách cho người dùng và hỏi: "Bạn muốn làm việc với file nào? (Nhập số thứ tự hoặc tên file)"
    - Chờ người dùng chọn rồi mới tiếp tục.
 
@@ -130,7 +130,7 @@ Thực hiện các bước theo đúng thứ tự. Lưu mọi thứ vào bộ nh
 - `domains` → danh sách các business domain đang hoạt động
 
 **Paths (nếu có):**
-- `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{prd.md | bdd/ | tech-docs/ | design-spec/}`
+- `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{ {TICKET-ID}-{prd-slug}.md | bdd/ | tech-docs/ | design-spec/}` (file PRD đặt tên `{TICKET-ID}-{prd-slug}.md`, là file `.md` duy nhất ở gốc feature folder)
 - `paths.refinement_dir` → thư mục output cho findings/review
 - `paths.qc_dir` → gốc artifact QC automation (hiện ở top-level, mỗi UC một thư mục con: `{qc_dir}/{UC-ID}/`)
 - `paths.qc_skills_dir` → nơi các lệnh qc-* nạp QC skill (mặc định bundled `.agent/skills/qc`; override sang repo/submodule riêng của team QC để bản nâng cấp framework không ghi đè)
@@ -156,7 +156,7 @@ Nếu không có section `paths`, dùng các giá trị mặc định:
 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.
 
 **Cách trích xuất `prd_slug` (đúng cho MỌI target file, bất kể độ sâu lồng nhau):** với một path target dạng `{specs_dir}/{domain}/{prd-slug}/...`, lấy **segment path đầu tiên sau `{specs_dir}/{domain}/`** — tức vị trí `{prd-slug}`. KHÔNG dùng folder cha trực tiếp của file, vì artifact BDD/tech-docs/design-spec lồng sâu hơn một hoặc hai cấp bên trong package. Ví dụ:
-- `specs/payment/create-invoice/prd.md` → `prd_slug = create-invoice`
+- `specs/payment/create-invoice/PAY01-create-invoice.md` → `prd_slug = create-invoice`
 - `specs/payment/create-invoice/bdd/system/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `system`)*
 - `specs/payment/create-invoice/bdd/web/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `web`)*
 - `specs/payment/create-invoice/tech-docs/PAY-UC1-tech-design.md` → `prd_slug = create-invoice` *(KHÔNG phải `tech-docs`)*
@@ -177,7 +177,7 @@ Nếu có section `services`:
 **1. Phát hiện active domain** (theo thứ tự ưu tiên):
 - Đọc `@trace.domain` từ frontmatter của target file (nếu Gate đã nạp một target file)
 - Trích xuất từ path target file: `domain` = segment đầu tiên sau base path `specs_dir`; `prd_slug` = segment kế tiếp (folder feature-package). Điều này đúng ở mọi độ sâu target — xem quy tắc trích xuất `prd_slug` ở Bước 1.  
-  *(vd: `specs/user/create-account/prd.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
+  *(vd: `specs/user/create-account/USR01-create-account.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
 - Nếu `$ARGUMENTS` chứa một path, trích xuất segment domain sau `specs_dir`
 
 **2. Route tới service** — nếu active domain khớp với một key trong `services`:

package/commands/fix-bug.md

@@ -54,13 +54,13 @@ Hiển thị và chờ phản hồi:
 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.
 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à `prd.md`): `{specs_dir}/{domain}/*/prd.md` (khớp feature folder có id tương ứng), nếu không thì `{specs_dir}/*/*/prd.md`.
+   - **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.)*
    - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
    - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
 
    Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
 3. Nếu `$ARGUMENTS` rỗng hoặc không tìm thấy file khớp:
-   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/prd.md` cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
+   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/*.md` — file PRD ở gốc mỗi feature folder — cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
    - Hiển thị danh sách cho người dùng và hỏi: "Bạn muốn làm việc với file nào? (Nhập số thứ tự hoặc tên file)"
    - Chờ người dùng chọn rồi mới tiếp tục.
 
@@ -128,7 +128,7 @@ Thực hiện các bước theo đúng thứ tự. Lưu mọi thứ vào bộ nh
 - `domains` → danh sách các business domain đang hoạt động
 
 **Paths (nếu có):**
-- `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{prd.md | bdd/ | tech-docs/ | design-spec/}`
+- `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{ {TICKET-ID}-{prd-slug}.md | bdd/ | tech-docs/ | design-spec/}` (file PRD đặt tên `{TICKET-ID}-{prd-slug}.md`, là file `.md` duy nhất ở gốc feature folder)
 - `paths.refinement_dir` → thư mục output cho findings/review
 - `paths.qc_dir` → gốc artifact QC automation (hiện ở top-level, mỗi UC một thư mục con: `{qc_dir}/{UC-ID}/`)
 - `paths.qc_skills_dir` → nơi các lệnh qc-* nạp QC skill (mặc định bundled `.agent/skills/qc`; override sang repo/submodule riêng của team QC để bản nâng cấp framework không ghi đè)
@@ -154,7 +154,7 @@ Nếu không có section `paths`, dùng các giá trị mặc định:
 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.
 
 **Cách trích xuất `prd_slug` (đúng cho MỌI target file, bất kể độ sâu lồng nhau):** với một path target dạng `{specs_dir}/{domain}/{prd-slug}/...`, lấy **segment path đầu tiên sau `{specs_dir}/{domain}/`** — tức vị trí `{prd-slug}`. KHÔNG dùng folder cha trực tiếp của file, vì artifact BDD/tech-docs/design-spec lồng sâu hơn một hoặc hai cấp bên trong package. Ví dụ:
-- `specs/payment/create-invoice/prd.md` → `prd_slug = create-invoice`
+- `specs/payment/create-invoice/PAY01-create-invoice.md` → `prd_slug = create-invoice`
 - `specs/payment/create-invoice/bdd/system/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `system`)*
 - `specs/payment/create-invoice/bdd/web/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `web`)*
 - `specs/payment/create-invoice/tech-docs/PAY-UC1-tech-design.md` → `prd_slug = create-invoice` *(KHÔNG phải `tech-docs`)*
@@ -175,7 +175,7 @@ Nếu có section `services`:
 **1. Phát hiện active domain** (theo thứ tự ưu tiên):
 - Đọc `@trace.domain` từ frontmatter của target file (nếu Gate đã nạp một target file)
 - Trích xuất từ path target file: `domain` = segment đầu tiên sau base path `specs_dir`; `prd_slug` = segment kế tiếp (folder feature-package). Điều này đúng ở mọi độ sâu target — xem quy tắc trích xuất `prd_slug` ở Bước 1.  
-  *(vd: `specs/user/create-account/prd.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
+  *(vd: `specs/user/create-account/USR01-create-account.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
 - Nếu `$ARGUMENTS` chứa một path, trích xuất segment domain sau `specs_dir`
 
 **2. Route tới service** — nếu active domain khớp với một key trong `services`: