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

package/docs/02-guides/product-owner/scenarios.md

@@ -20,11 +20,11 @@ Output: `specs/product-definition/FEAT-01-login.md`
 ```
 Agent tự động: đọc product definition · expand thành PRD đầy đủ với UC, AC, BR · nhắc nếu bạn viết UI details · kiểm tra terminology với business-dictionary.
 
-Output: `specs/auth/FEAT-01-login/prd.md`
+Output: `specs/auth/FEAT-01-login/FEAT-01-login.md`
 
 **Bước 3 — Review nội dung:**
 ```
-/refine-prd specs/auth/FEAT-01-login/prd.md
+/refine-prd specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 Agent fan-out 4 lens (QA/DEV/SA/PO) chạy song song, rồi chạy completeness-critic loop cho đến khi một vòng không tìm ra finding mới, cuối cùng dedup + resolve conflict. Findings đầy đủ trong 1 lần chạy.
 
@@ -33,12 +33,12 @@ Mở findings file, xem xét từng finding: `accepted` → apply · `modified`
 > **Finding khó hiểu? Bấm 💬 Giải thích.** Nếu một finding mô tả nặng tính kỹ thuật, dùng nút **💬 Giải thích** trên Review Board (extension Spec Driven Docs Tools). Claude sẽ giải thích lại bằng ngôn ngữ no-tech + đề xuất phương án cụ thể (cover cả edge case) ngay trong terminal, và **chờ bạn confirm trước khi apply** vào PRD — tránh refine nhiều vòng. Prompt sửa được qua setting `reviewBoard.clarifyPrompt` (không cần cài lại extension).
 
 ```
-/review-context --resume specs/auth/FEAT-01-login/prd.md
+/review-context --resume specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 
 **Bước 4 — Final check:**
 ```
-/review-context specs/auth/FEAT-01-login/prd.md
+/review-context specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 Kiểm tra: `@trace.status`, `@trace.domain`, completeness.
 
@@ -51,7 +51,7 @@ Kiểm tra: `@trace.status`, `@trace.domain`, completeness.
 
 **Bước 6 — Tạo Design Spec (FE/App):**
 ```
-/generate-design-spec specs/auth/FEAT-01-login/prd.md
+/generate-design-spec specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 Agent hỏi platform (web / app). PO phải cung cấp **Figma link node-level** (URL chứa `?node-id=`, lấy bằng right-click vào frame → "Copy link to selection") cho **mỗi screen**. Screen nào thiếu link → bị flag ❌ Missing, Status giữ `draft`, `/generate-bdd` bị BLOCKED cho đến khi đủ link.
 
@@ -59,7 +59,7 @@ Sau khi Designer review + confirm đủ Figma node-id links → `@trace.status:
 
 **Bước 7 — Generate BDD:**
 ```
-/generate-bdd specs/auth/FEAT-01-login/prd.md
+/generate-bdd specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 Agent hỏi: **"Platform? (1) web  (2) app  (3) system"**
 - Chọn `web` → `specs/auth/FEAT-01-login/bdd/web/FEAT-01-UC1-login-web.feature`
@@ -111,7 +111,7 @@ git push
 
 **Bước 1 — Design Spec:**
 ```
-/generate-design-spec specs/auth/FEAT-01-login/prd.md
+/generate-design-spec specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 Output: `specs/auth/FEAT-01-login/design-spec/FEAT-01-design-spec-web.md`
 
@@ -119,7 +119,7 @@ Mỗi screen cần Figma link node-id. Screen thiếu → flag ❌ Missing, BLOC
 
 **Bước 2 — Generate BDD:**
 ```
-/generate-bdd specs/auth/FEAT-01-login/prd.md
+/generate-bdd specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 
 | Lần | Platform | Output |
@@ -147,12 +147,12 @@ cat .agent/review/FEAT-01-login-prd-review-context-findings.yaml
 
 **Bước 3 — Apply:**
 ```
-/review-context --resume specs/auth/FEAT-01-login/prd.md
+/review-context --resume specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 
 **Bước 4 — Re-review:**
 ```
-/review-context specs/auth/FEAT-01-login/prd.md
+/review-context specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 Lặp lại cho đến khi `recommendation: APPROVED`.
 
@@ -167,12 +167,12 @@ Lặp lại cho đến khi `recommendation: APPROVED`.
 
 **Bước 2 — Sửa nội dung:**
 ```
-/refine-prd specs/auth/FEAT-01-login/prd.md "Thêm yêu cầu: hỗ trợ đăng nhập bằng OTP"
+/refine-prd specs/auth/FEAT-01-login/FEAT-01-login.md "Thêm yêu cầu: hỗ trợ đăng nhập bằng OTP"
 ```
 
 **Bước 3 — Review lại:**
 ```
-/review-context specs/auth/FEAT-01-login/prd.md
+/review-context specs/auth/FEAT-01-login/FEAT-01-login.md
 /review-context --resume    (nếu cần fix)
 ```
 
@@ -183,7 +183,7 @@ Lặp lại cho đến khi `recommendation: APPROVED`.
                          # major bump (2.0) nếu thay đổi cơ bản
 ```
 ```bash
-git add specs/auth/FEAT-01-login/prd.md
+git add specs/auth/FEAT-01-login/FEAT-01-login.md
 git commit -m "feat(auth): update FEAT-01 PRD v1.1 — add OTP login AC"
 git push
 ```
@@ -239,7 +239,7 @@ services:
 2. Quyết định PRD nào đúng.
 3. Sửa file:
    ```
-   /review-context --resume specs/auth/FEAT-01-login/prd.md
+   /review-context --resume specs/auth/FEAT-01-login/FEAT-01-login.md
    # với finding P3: modified: "session timeout cập nhật thành 2 giờ theo FEAT-05"
    ```
 4. Cả 2 PRD phải nhất quán trước khi dev team generate BDD.
@@ -268,20 +268,20 @@ git push
 ```
 specs/
 ├── auth/
-│   ├── FEAT-01-login/prd.md          (approved)
-│   └── FEAT-08-sso/prd.md            (draft)
+│   ├── FEAT-01-login/FEAT-01-login.md          (approved)
+│   └── FEAT-08-sso/FEAT-08-sso.md            (draft)
 ├── payment/
-│   ├── FEAT-03-checkout/prd.md       (approved)
-│   └── FEAT-11-refund/prd.md         (draft)
+│   ├── FEAT-03-checkout/FEAT-03-checkout.md       (approved)
+│   └── FEAT-11-refund/FEAT-11-refund.md         (draft)
 └── loyalty/
-    └── FEAT-06-points/prd.md         (in-review)
+    └── FEAT-06-points/FEAT-06-points.md         (in-review)
 ```
 
 **Gợi ý:** Hoàn thiện 1 PRD đến `approved` trước khi bắt đầu PRD tiếp theo. Chỉ PRD `approved` mới được dev team sử dụng.
 
 ```bash
 # Xem nhanh tất cả PRDs và status:
-grep -r "@trace.status" specs/ --include="prd.md"
+grep -r "@trace.status" specs/ --include="*.md"
 ```
 
 ---
@@ -297,7 +297,7 @@ grep -r "@trace.status" specs/ --include="prd.md"
 ```
 
 ```
-/review-context specs/auth/FEAT-01-login/prd.md
+/review-context specs/auth/FEAT-01-login/FEAT-01-login.md
 → Phải thấy recommendation: APPROVED và 0 critical findings
 ```
 
@@ -306,13 +306,13 @@ grep -r "@trace.status" specs/ --include="prd.md"
 [FEAT-01] PRD Login đã approved — sẵn sàng implement
 
 Domain: auth
-File: my-project-specs/specs/auth/FEAT-01-login/prd.md
+File: my-project-specs/specs/auth/FEAT-01-login/FEAT-01-login.md
 Version: 1.0
 Design Spec (Web): my-project-specs/specs/auth/FEAT-01-login/design-spec/FEAT-01-design-spec-web.md
 
 Lệnh để bắt đầu:
   git submodule update --remote my-project-specs
-  /review-context my-project-specs/specs/auth/FEAT-01-login/prd.md
+  /review-context my-project-specs/specs/auth/FEAT-01-login/FEAT-01-login.md
 ```
 
 ---

package/docs/02-guides/tester/bug-reporting.md

@@ -45,7 +45,7 @@ Service  : BE / Web / App
 Severity : Critical / Major / Minor
 
 Spec context:
-  PRD      : specs/{domain}/{prd-slug}/prd.md (v{x.x})
+  PRD      : specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md (v{x.x})
   BDD      : {bdd path} → Scenario: "{scenario title}"
   Tech Doc : {tech_docs path}
 
@@ -77,7 +77,7 @@ Service  : BE
 Severity : Major
 
 Spec context:
-  PRD      : specs/auth/FT-001-login/prd.md (v1.0)
+  PRD      : specs/auth/FT-001-login/FT-001-login.md (v1.0)
   BDD      : free-trial-specs/specs/auth/FT-001-login/bdd/system/FT-001-login.feature
              → Scenario: "Lock account after 5 failed attempts"
   Tech Doc : free-trial-specs/specs/auth/FT-001-login/tech-docs/FT-001-auth-api.md

package/docs/02-guides/tester/reading-specs.md

@@ -18,7 +18,7 @@ Sau khi chạy `/generate-spec-manifest`, tra manifest để lấy paths:
 ```yaml
 # spec-manifest.yaml
 FT-001:
-  prd:          "my-project-specs/specs/auth/FT-001-login/prd.md"
+  prd:          "my-project-specs/specs/auth/FT-001-login/FT-001-login.md"
   bdd:
     be:   "my-project-specs/specs/auth/FT-001-login/bdd/system/FT-001-UC1-login-system.feature"
     web:  "my-project-specs/specs/auth/FT-001-login/bdd/web/FT-001-UC1-login-web.feature"
@@ -26,7 +26,7 @@ FT-001:
     be:   "my-project-specs/specs/auth/FT-001-login/tech-docs/FT-001-auth-api.md"
 ```
 
-**Bước 1: Đọc PRD** tại `my-project-specs/specs/auth/FT-001-login/prd.md`
+**Bước 1: Đọc PRD** tại `my-project-specs/specs/auth/FT-001-login/FT-001-login.md`
 *(nằm trong spec submodule — shared repo của PO)*
 
 ```markdown

package/docs/02-guides/tester/scenarios.md

@@ -16,7 +16,7 @@ git pull && git submodule update --remote --recursive
 # 3. Kiểm tra status
 # FT-042:
 #   status: approved  ← ✅ có thể test
-#   prd: "specs/payment/FT-042-checkout/prd.md"
+#   prd: "specs/payment/FT-042-checkout/FT-042-checkout.md"
 #   bdd:
 #     be:  "free-trial-specs/specs/payment/FT-042-checkout/bdd/system/FT-042-UC1-checkout-system.feature"
 #     web: "free-trial-specs/specs/payment/FT-042-checkout/bdd/web/FT-042-UC1-checkout-web.feature"

package/docs/02-guides/tester/spec-manifest.md

@@ -4,14 +4,14 @@
 
 ## Spec-Manifest Là Gì Và Tại Sao Cần
 
-Trong umbrella repo (có `spec_source`), **mọi spec đều nằm trong spec submodule** — gom theo feature-package: mỗi PRD có một thư mục `specs/{domain}/{prd-slug}/` chứa tất cả artifact (`prd.md`, `bdd/{platform}/`, `tech-docs/`, `design-spec/`), trải trên nhiều domain:
+Trong umbrella repo (có `spec_source`), **mọi spec đều nằm trong spec submodule** — gom theo feature-package: mỗi PRD có một thư mục `specs/{domain}/{prd-slug}/` chứa tất cả artifact (`{TICKET-ID}-{prd-slug}.md`, `bdd/{platform}/`, `tech-docs/`, `design-spec/`), trải trên nhiều domain:
 
 ```
 free-trial-umbrella/                              ← umbrella (Claude Code mở ở đây)
 ├── free-trial-specs/                             ← SPEC submodule — TẤT CẢ spec ở đây
 │   └── specs/
 │       └── auth/FT-001-login/                    ← feature-package (1 PRD = 1 thư mục)
-│           ├── prd.md                            ← PRD
+│           ├── {TICKET-ID}-{prd-slug}.md                            ← PRD
 │           ├── design-spec/...                   ← Design Spec
 │           ├── bdd/system/...                    ← BDD System (BE)
 │           ├── bdd/web/...                        ← BDD Web (FE)
@@ -30,7 +30,7 @@ features:
   FT-001:
     domain: auth
     status: approved
-    prd: "specs/auth/FT-001-login/prd.md"
+    prd: "specs/auth/FT-001-login/FT-001-login.md"
     pdd: "specs/product-definition/auth/FT-001-def.md"
     tech_docs:
       be:  "free-trial-specs/specs/auth/FT-001-login/tech-docs/FT-001-UC1-auth-api.md"

package/docs/02-guides/tester/workflow.md

@@ -16,7 +16,7 @@ git pull && git submodule update --remote --recursive
 Lookup FT-042 trong spec-manifest.yaml
 → status: approved? ✅ (nếu draft → dừng, báo PO)
 → ghi lại paths (tất cả đều nằm trong submodule):
-    prd:          {spec_source}/specs/{domain}/{prd-slug}/prd.md
+    prd:          {spec_source}/specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
     bdd.system:   {spec_source}/specs/{domain}/{prd-slug}/bdd/system/FT-042-*.feature
     bdd.web:      {spec_source}/specs/{domain}/{prd-slug}/bdd/web/FT-042-*.feature
     tech_docs.be: {spec_source}/specs/{domain}/{prd-slug}/tech-docs/FT-042-*.md

package/docs/03-concepts/architecture.md

@@ -58,7 +58,7 @@ LAYER 5 — OUTPUT                          (artifacts in consumer proj)
   Spec module (cross-team, via {spec_source}):
     specs/product-definition/
     specs/{domain}/{prd-slug}/ — feature package gom mọi artifact của một PRD:
-      prd.md · bdd/ (web/app/system) · tech-docs/ (API contract + FE tech-design) · design-spec/
+      {TICKET-ID}-{prd-slug}.md · bdd/ (web/app/system) · tech-docs/ (API contract + FE tech-design) · design-spec/
     feedback/
     .trace/{domain}/{prd-slug}/*.tsv (authoritative, committed — một chỗ cho PM) · .living-docs/ (gitignored)
   Service submodule (per-service):
@@ -76,10 +76,10 @@ LAYER 5 — OUTPUT                          (artifacts in consumer proj)
 
 ## Data flow — một command chạy như thế nào
 
-Ví dụ `/generate-bdd specs/payment/process-payment/prd.md`:
+Ví dụ `/generate-bdd specs/payment/process-payment/{TICKET-ID}-process-payment.md`:
 
 ```
-User types: /generate-bdd specs/payment/process-payment/prd.md
+User types: /generate-bdd specs/payment/process-payment/{TICKET-ID}-process-payment.md
   │
 [L0] data-guard.js check tool calls real-time → đọc .env/*.key → BLOCK + warn
   │

package/docs/03-concepts/pipeline.md

@@ -24,7 +24,7 @@ Vòng đời feature đi qua các phase, mỗi transition có một **AI review
 |-------|-----|----------|--------|
 | **0. Setup** *(one-time)* | Tech Lead | `/setup-ai-first`, `/sync`, `/sync-figma-*` | Config files, submodules, component catalog |
 | **1. Discovery** | PO + AI | `/define-product` | `specs/product-definition/{TICKET-ID}-{slug}.md` |
-| **2. PRD** | AI → SA/PO review | `/generate-prd`, `/refine-prd`, `/review-context` | `specs/{domain}/{prd-slug}/prd.md` |
+| **2. PRD** | AI → SA/PO review | `/generate-prd`, `/refine-prd`, `/review-context` | `specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` |
 | **2b. Design Spec** *(FE/App only)* | AI → Designer/PO sign-off | `/generate-design-spec` | `specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{platform}.md` |
 | **3. BDD Spec** | AI → SA/Dev review | `/generate-bdd`, `/review-context` | `specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature` |
 | **4. Tech Design** *(platform-aware)* | AI → SA/Lead review | `/generate-tech-docs`, `/review-tech-docs` | BE: `specs/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md` (API contract) · FE/App: `{UC-ID}-tech-design-{platform}.md` (client design — **gated** trên System BDD + BE contract) |
@@ -48,7 +48,7 @@ Phase 1: Discovery
          business rules → business logic → AC → validation matrix)
 
 Phase 2: PRD
-  /generate-prd ────────────→ specs/{domain}/{prd-slug}/prd.md
+  /generate-prd ────────────→ specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
   /refine-prd ──────────────→ .agent/review/{prd-slug}-findings.yaml
                   [Review Board: Accept/Modify/Reject]
                 /refine-prd --resume → apply + bump version
@@ -180,7 +180,7 @@ Mọi command bắt đầu ở đây, theo thứ tự:
 ```
 CHECKPOINT
 -----------
-Target     : specs/auth/FEAT-042-login/prd.md
+Target     : specs/auth/FEAT-042-login/FEAT-042-login.md
 Project    : My App
 Tech stack : TypeScript / React 18
 Module     : react

package/docs/04-operations/sync-and-update.md

@@ -100,7 +100,7 @@ npx @edupia-tutor/spec-driven-docs --migrate-specs --apply
 ```
 
 Lệnh sẽ:
-- Di chuyển `specs/prd/{domain}/{slug}.md` → `specs/{domain}/{slug}/prd.md`, và `specs/bdd|tech-docs|design-spec/{domain}/…` → `specs/{domain}/{prd-slug}/{bdd|tech-docs|design-spec}/…`; flat `.trace/{UC-ID}.tsv` → `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`.
+- Di chuyển `specs/prd/{domain}/{slug}.md` → `specs/{domain}/{slug}/{TICKET-ID}-{slug}.md`, và `specs/bdd|tech-docs|design-spec/{domain}/…` → `specs/{domain}/{prd-slug}/{bdd|tech-docs|design-spec}/…`; flat `.trace/{UC-ID}.tsv` → `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`.
 - Suy ra `{prd-slug}` cho mỗi file BDD/tech-doc/design-spec/trace bằng cách đọc header `@trace.source` (PRD nguồn) hoặc tag `@trace.uc` (map qua index `.feature`).
 - Dùng `git mv` cho file đã track (giữ history), `fs.rename` cho phần còn lại.
 - Rewrite các tham chiếu nội bộ (`@trace.source`, đường dẫn `specs/…`) trong những file vừa move.
@@ -130,7 +130,7 @@ Claude Code luôn mở ở **umbrella repo** (không mở trong service submodul
  SPEC SUBMODULE                       SERVICE SUBMODULE(s)
  (PO sở hữu · origin riêng)           (Dev sở hữu · origin riêng)
  specs/{domain}/{prd-slug}/          src/   (chỉ code + tooling)
-   prd.md · bdd/ (web/app/system)
+   {TICKET-ID}-{prd-slug}.md · bdd/ (web/app/system)
    design-spec/ · tech-docs/
  feedback/ (bug · proposal · prd-change)
  .trace/{domain}/{prd-slug}/*.tsv  (qc_status + dev_selftest — write area của dev/QC)
@@ -257,7 +257,7 @@ Topology giả định cho mọi ví dụ dưới đây:
 ```bash
 cd my-project-specs && git pull
 # /generate-prd · /generate-design-spec · /generate-bdd (web/app/system) · set @trace.status: approved
-git add specs/payment/checkout/prd.md \
+git add specs/payment/checkout/{TICKET-ID}-checkout.md \
         specs/payment/checkout/design-spec/FT-042-checkout-design.md \
         specs/payment/checkout/bdd/system/FT-042-UC1-checkout-system.feature \
         specs/payment/checkout/bdd/web/FT-042-UC1-checkout-web.feature \
@@ -416,7 +416,7 @@ cd my-project-web
 /sync                                    # pull + submodule + Living Docs
 git add my-project-specs && git commit -m "chore: sync specs" && git push
 
-/review-context my-project-specs/specs/{domain}/{prd-slug}/prd.md
+/review-context my-project-specs/specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
 # → P0: @trace.domain khớp services config? @trace.status: approved?
 # Đọc Web BDD do PO generate (KHÔNG tự generate BDD):
 #   my-project-specs/specs/{domain}/{prd-slug}/bdd/web/{TICKET-ID}-UC*.feature
@@ -449,7 +449,7 @@ cd my-project-be
 /sync
 # → cũng liệt kê "📥 New tester feedback" → /fix-bug · promote proposal · báo PO
 
-/review-context my-project-specs/specs/{domain}/{prd-slug}/prd.md
+/review-context my-project-specs/specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
 # Đọc System BDD: my-project-specs/specs/{domain}/{prd-slug}/bdd/system/{TICKET-ID}-UC*.feature
 
 /generate-tech-docs {domain}/{TICKET-ID}-UC1

package/docs/05-reference/command-cheatsheet.md

@@ -62,8 +62,8 @@ Có **4 lệnh review** cho **4 loại artifact khác nhau**. Đây là điểm
 
 | Tôi muốn review… | Cách dùng (ví dụ) | Nó kiểm cái gì | Ai chạy |
 |---|---|---|---|
-| **PRD — nội dung & độ đầy đủ** | `/refine-prd specs/auth/login/prd.md` | 4 lens QA·DEV·SA·PO: AC có test được? edge case? scope rõ? | PO |
-| **PRD — chất lượng trước khi approve** | `/review-context specs/auth/login/prd.md` | P-checks: banned term, mơ hồ, mâu thuẫn PRD khác, thiếu section, routing `@trace.domain` | PO |
+| **PRD — nội dung & độ đầy đủ** | `/refine-prd specs/auth/login/{TICKET-ID}-login.md` | 4 lens QA·DEV·SA·PO: AC có test được? edge case? scope rõ? | PO |
+| **PRD — chất lượng trước khi approve** | `/review-context specs/auth/login/{TICKET-ID}-login.md` | P-checks: banned term, mơ hồ, mâu thuẫn PRD khác, thiếu section, routing `@trace.domain` | PO |
 | **BDD `.feature`** | `/review-context specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | B-checks: mỗi AC/BR → có ≥1 scenario? Gherkin R1–R10, compliance C1–C5 | SA/Dev |
 | **Tech design** | `/review-tech-docs specs/auth/login/tech-docs/FEAT-01-UC1-tech-design.md` | T-checks: đúng layer/architecture, entity, trace BDD, cross-team API sign-off | Dev/SA |
 | **Code** | `/review-code FEAT-01-UC1` | 4 lens: Security · Performance · Architecture · Test coverage | Dev |

package/docs/05-reference/commands.md

@@ -56,12 +56,12 @@
 
 | Command | Cách dùng (ví dụ) | Output | When to use |
 |---------|-------------------|--------|-------------|
-| `/generate-prd` | `/generate-prd specs/product-definition/FEAT-01-login.md` | `specs/{domain}/{prd-slug}/prd.md` | After define-product. Thêm `API Source: existing` + section "Existing API Contract" cho feature brownfield. |
-| `/refine-prd` | `/refine-prd specs/auth/login/prd.md` | `.agent/review/{prd-slug}-findings.yaml` | After generate-prd — fan-out 4 review lens + completeness-critic loop, mở Review Board. |
-| `/refine-prd --resume` | `/refine-prd --resume specs/auth/login/prd.md` | Applied findings + bumped version | Sau khi review trong Review Board (nút ⚡ Apply tự chạy lệnh này). |
-| `/review-context` (PRD) | `/review-context specs/auth/login/prd.md` | `.agent/review/{prd-slug}-review-context-findings.yaml` | Quality gate bắt buộc trước Phase 3. Checks: banned terms (P1), ambiguity (P2), conflicts (P3), completeness (P4). |
-| `/review-context --fix` | `/review-context --fix specs/auth/login/prd.md` | Applies all auto-fixable findings immediately | Dev quick-fix, không cần Review Board. |
-| `/review-context --resume` | `/review-context --resume specs/auth/login/prd.md` | Applies accepted findings + bump version | PO/SA review — human quyết từng finding. |
+| `/generate-prd` | `/generate-prd specs/product-definition/FEAT-01-login.md` | `specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` | After define-product. Thêm `API Source: existing` + section "Existing API Contract" cho feature brownfield. |
+| `/refine-prd` | `/refine-prd specs/auth/login/{TICKET-ID}-login.md` | `.agent/review/{prd-slug}-findings.yaml` | After generate-prd — fan-out 4 review lens + completeness-critic loop, mở Review Board. |
+| `/refine-prd --resume` | `/refine-prd --resume specs/auth/login/{TICKET-ID}-login.md` | Applied findings + bumped version | Sau khi review trong Review Board (nút ⚡ Apply tự chạy lệnh này). |
+| `/review-context` (PRD) | `/review-context specs/auth/login/{TICKET-ID}-login.md` | `.agent/review/{prd-slug}-review-context-findings.yaml` | Quality gate bắt buộc trước Phase 3. Checks: banned terms (P1), ambiguity (P2), conflicts (P3), completeness (P4). |
+| `/review-context --fix` | `/review-context --fix specs/auth/login/{TICKET-ID}-login.md` | Applies all auto-fixable findings immediately | Dev quick-fix, không cần Review Board. |
+| `/review-context --resume` | `/review-context --resume specs/auth/login/{TICKET-ID}-login.md` | Applies accepted findings + bump version | PO/SA review — human quyết từng finding. |
 
 ---
 
@@ -69,7 +69,7 @@
 
 | Command | Cách dùng (ví dụ) | Output | When to use |
 |---------|-------------------|--------|-------------|
-| `/generate-design-spec` | `/generate-design-spec specs/auth/login/prd.md` | `specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{platform}.md` | FE/App: sau khi PRD approved, trước BDD. PO phải cấp **node-level Figma frame link** (URL có `?node-id=`) cho mỗi screen; AI fetch từng frame qua Figma MCP. Screen thiếu link → ❌ Missing, spec ở draft và chặn sign-off + `/generate-bdd`. |
+| `/generate-design-spec` | `/generate-design-spec specs/auth/login/{TICKET-ID}-login.md` | `specs/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{platform}.md` | FE/App: sau khi PRD approved, trước BDD. PO phải cấp **node-level Figma frame link** (URL có `?node-id=`) cho mỗi screen; AI fetch từng frame qua Figma MCP. Screen thiếu link → ❌ Missing, spec ở draft và chặn sign-off + `/generate-bdd`. |
 
 > BE teams bỏ qua Phase 2b — đọc PRD trực tiếp rồi `/generate-bdd`.
 
@@ -79,7 +79,7 @@
 
 | Command | Cách dùng (ví dụ) | Output | When to use |
 |---------|-------------------|--------|-------------|
-| `/generate-bdd` | `/generate-bdd specs/auth/login/prd.md` | `specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature` (multi-service: `{prd-slug}/bdd/{service}/{UC-ID}.feature`) | After PRD approved (+ Design Spec sign-off cho FE/App). Đọc Service/Module từ PRD metadata, áp platform vocabulary, hiện SC outline chờ confirm. **Thứ tự outside-in: web → app → system**; `system` **tổng hợp từ web+app BDD** (web&app lệch contract → CHECKPOINT chọn union/platform-hint/separate-endpoints, ghi `@system.resolution:`; chỉ-BE → từ PRD). PRD lớn (>3 UC hoặc >300 dòng) → orchestration mode (1 sub-agent / UC). |
+| `/generate-bdd` | `/generate-bdd specs/auth/login/{TICKET-ID}-login.md` | `specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature` (multi-service: `{prd-slug}/bdd/{service}/{UC-ID}.feature`) | After PRD approved (+ Design Spec sign-off cho FE/App). Đọc Service/Module từ PRD metadata, áp platform vocabulary, hiện SC outline chờ confirm. **Thứ tự outside-in: web → app → system**; `system` **tổng hợp từ web+app BDD** (web&app lệch contract → CHECKPOINT chọn union/platform-hint/separate-endpoints, ghi `@system.resolution:`; chỉ-BE → từ PRD). PRD lớn (>3 UC hoặc >300 dòng) → orchestration mode (1 sub-agent / UC). |
 | `/review-context` (BDD) | `/review-context specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | `.agent/review/{uc-id}-review-bdd-findings.yaml` | Quality gate bắt buộc trước Phase 4. Checks: PRD coverage (mỗi AC + BR → ≥1 SC), Gherkin R1–R10, compliance C1–C5. |
 | `/review-context --fix` | `/review-context --fix specs/auth/login/bdd/web/FEAT-01-UC1-login.feature` | Auto-fix terminology, metadata, coverage matrix | Dev quick-fix. |
 | `/review-context --resume` | `/review-context --resume specs/auth/login/bdd/system/FEAT-01-UC1-login.feature` | Applies accepted findings + bump bdd_version | SA review. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edupia-tutor/spec-driven-docs",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "description": "AI-First Spec-Driven Development workflow framework for Claude Code",
   "bin": {
     "spec-driven-docs": "./bin/index.js"

package/scripts/migrate-specs.js

@@ -5,7 +5,7 @@
  * artifact-type-first layout to the FEATURE-PACKAGE layout.
  *
  *   OLD                                   NEW
- *   specs/prd/{domain}/{slug}.md          specs/{domain}/{slug}/prd.md
+ *   specs/prd/{domain}/{slug}.md          specs/{domain}/{slug}/{TICKET-ID}-{slug}.md
  *   specs/bdd/{domain}/{rest}             specs/{domain}/{prd-slug}/bdd/{rest}
  *   specs/tech-docs/{domain}/{file}       specs/{domain}/{prd-slug}/tech-docs/{file}
  *   specs/design-spec/{domain}/{file}     specs/{domain}/{prd-slug}/design-spec/{file}
@@ -83,7 +83,7 @@ const ticketToSlug = {}; // `${domain}/${TICKET}` -> slug (from PRD metadata)
 const addSlug = (domain, slug) => { (prdByDomain[domain] = prdByDomain[domain] || new Set()).add(slug); };
 const onlySlug = domain => { const s = prdByDomain[domain]; return s && s.size === 1 ? [...s][0] : null; };
 
-// ── Phase 1 — PRDs: specs/prd/{domain}/{slug}.md → specs/{domain}/{slug}/prd.md ──
+// ── Phase 1 — PRDs: specs/prd/{domain}/{slug}.md → specs/{domain}/{slug}/{TICKET-ID}-{slug}.md ──
 const prdRoot = path.join(specsAbs, 'prd');
 for (const file of walk(prdRoot).filter(f => f.endsWith('.md'))) {
   const parts = rel(file).split('/');                  // [SPECS, 'prd', domain, ...rest, name.md]
@@ -98,7 +98,9 @@ for (const file of walk(prdRoot).filter(f => f.endsWith('.md'))) {
   if (ticket) ticketToSlug[`${domain}/${ticket}`] = slug;
   let m; const reUcG = new RegExp(reUcName.source, 'g');
   while ((m = reUcG.exec(body))) ucToSlug[`${domain}/${m[1]}`] = ucToSlug[`${domain}/${m[1]}`] || slug;
-  moves.push({ from: file, to: path.join(specsAbs, domain, slug, 'prd.md'), type: 'prd' });
+  // PRD file name follows the {TICKET-ID}-{slug}.md convention (falls back to {slug}.md if no ticket found)
+  const prdFile = ticket ? `${ticket}-${slug}.md` : `${slug}.md`;
+  moves.push({ from: file, to: path.join(specsAbs, domain, slug, prdFile), type: 'prd' });
 }
 
 // ── Phase 2 — BDD: specs/bdd/{domain}/{rest} → specs/{domain}/{prd-slug}/bdd/{rest}

package/scripts/rename-prd-files.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+/**
+ * rename-prd-files.js — rename feature-package PRD files from the old fixed
+ * name `prd.md` to the `{TICKET-ID}-{slug}.md` convention.
+ *
+ *   OLD                                      NEW
+ *   specs/{domain}/{slug}/prd.md             specs/{domain}/{slug}/{TICKET-ID}-{slug}.md
+ *
+ * For each `specs/{domain}/{slug}/prd.md`:
+ *   - slug    = the feature-package folder name (parent dir)
+ *   - TICKET-ID is read from the PRD body — the Metadata table row
+ *     (| **PRD ID** | … | / | **Ticket** | … |) or, failing that, the leading
+ *     token of the H1 title (`# SEG01-…`). PRDs where no ticket can be resolved
+ *     are LEFT IN PLACE and listed in the report — never renamed to a guess.
+ *
+ * After moving, any reference to the old `…/{slug}/prd.md` path inside other
+ * spec / trace files (.md, .feature, .tsv, .yaml) is rewritten to the new path.
+ *
+ * DRY-RUN by default (prints the plan, changes nothing). Pass --apply to execute.
+ * Tracked files move with `git mv` to preserve history; the rest with fs.rename.
+ *
+ * Usage (from the consumer project root):
+ *   node scripts/rename-prd-files.js                 # dry-run, prints plan
+ *   node scripts/rename-prd-files.js --apply         # execute the rename
+ *   node scripts/rename-prd-files.js --specs specs --trace .trace --root .
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// ── args ────────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2);
+const has  = f => argv.includes(f);
+const flag = (f, d) => { const i = argv.indexOf(f); return i !== -1 ? argv[i + 1] : d; };
+
+const APPLY = has('--apply');
+const ROOT  = path.resolve(flag('--root', '.'));
+const SPECS = flag('--specs', 'specs');
+const TRACE = flag('--trace', '.trace');
+
+const specsAbs = path.join(ROOT, SPECS);
+const traceAbs = path.join(ROOT, TRACE);
+
+// ── git tracked set (for `git mv`) ────────────────────────────────────────────
+let tracked = null;
+try {
+  const out = execSync('git ls-files', { cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  tracked = new Set(out.split('\n').filter(Boolean).map(p => p.replace(/\\/g, '/')));
+} catch { tracked = null; }
+
+const rel       = abs => path.relative(ROOT, abs).replace(/\\/g, '/');
+const isTracked = abs => !!(tracked && tracked.has(rel(abs)));
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+function walk(dir) {
+  const out = [];
+  if (!fs.existsSync(dir)) return out;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...walk(p));
+    else out.push(p);
+  }
+  return out;
+}
+const head = (file, n = 16384) => { try { return fs.readFileSync(file, 'utf8').slice(0, n); } catch { return ''; } };
+
+// Extract the TICKET-ID from a PRD body. Tries the Metadata table first, then the H1 title.
+function extractTicket(body) {
+  // | **PRD ID** | SEG01 |   /   | **Ticket** | [SEG01](...) |   /   | **TICKET-ID** | SEG01 |
+  let m = body.match(/\|\s*\*\*\s*(?:PRD ID|Ticket(?:\s*ID)?|TICKET-ID|Mã(?:\s*ticket)?)\s*\*\*\s*\|\s*\[?\s*([A-Za-z][A-Za-z0-9_.-]*?)\s*\]?\s*(?:\]\([^)]*\))?\s*\|/i);
+  if (m) return m[1];
+  // H1 title: "# SEG01-segment-scoring-service ..." or "# SEG01 Feature Name"
+  m = body.match(/^#\s+([A-Za-z][A-Za-z0-9_.]*(?:-?\d+)?)\b/m);
+  if (m) return m[1];
+  return null;
+}
+
+// ── plan ───────────────────────────────────────────────────────────────────────
+const moves      = [];   // { from(abs), to(abs) }
+const unresolved = [];   // { file(rel), reason }
+
+// Scan specs/{domain}/{slug}/prd.md  (PRD lives directly in the feature-package folder)
+for (const file of walk(specsAbs).filter(f => path.basename(f) === 'prd.md')) {
+  const parts = rel(file).split('/');                 // [SPECS, domain, slug, 'prd.md']
+  if (parts.length < 4) { unresolved.push({ file: rel(file), reason: `not a feature-package PRD (expected ${SPECS}/{domain}/{slug}/prd.md)` }); continue; }
+  const slug = parts[parts.length - 2];
+  const ticket = extractTicket(head(file));
+  if (!ticket) { unresolved.push({ file: rel(file), reason: 'no TICKET-ID found (add a Metadata "PRD ID"/"Ticket" row or an H1 title, then re-run)' }); continue; }
+  const to = path.join(path.dirname(file), `${ticket}-${slug}.md`);
+  if (rel(to) === rel(file)) continue; // already correctly named (shouldn't happen for prd.md)
+  moves.push({ from: file, to });
+}
+
+// ── old→new ref map (repo-root-relative, forward slashes) ──────────────────────
+const refMap = new Map();
+for (const m of moves) refMap.set(rel(m.from), rel(m.to));
+
+// ── report ──────────────────────────────────────────────────────────────────────
+console.log('');
+console.log('╔════════════════════════════════════════════╗');
+console.log(`║  rename-prd-files  —  ${APPLY ? 'APPLY' : 'DRY RUN'}${' '.repeat(APPLY ? 16 : 14)}║`);
+console.log('╚════════════════════════════════════════════╝');
+console.log(`Root  : ${ROOT}`);
+console.log(`Specs : ${SPECS}/   Trace: ${TRACE}/   Git: ${tracked ? 'yes (git mv)' : 'no (fs move)'}`);
+console.log('');
+if (moves.length === 0 && unresolved.length === 0) {
+  console.log(`Nothing to rename — no ${SPECS}/{domain}/{slug}/prd.md files found (already on the {TICKET-ID}-{slug}.md convention?).`);
+  process.exit(0);
+}
+console.log(`Planned renames: ${moves.length}`);
+console.log('');
+for (const m of moves) console.log(`  ${rel(m.from)}\n    → ${rel(m.to)}`);
+if (unresolved.length) {
+  console.log('');
+  console.log('⚠️  Left in place (fix the PRD, then re-run):');
+  for (const u of unresolved) console.log(`  ${u.file}\n      ${u.reason}`);
+}
+console.log('');
+
+// ── apply ────────────────────────────────────────────────────────────────────────
+function gitMv(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  execSync(`git mv -k "${rel(from)}" "${rel(to)}"`, { cwd: ROOT, stdio: ['ignore', 'ignore', 'pipe'] });
+}
+function fsMv(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  fs.renameSync(from, to);
+}
+function rewriteRefs(absFile) {
+  if (!/\.(md|feature|tsv|ya?ml)$/.test(absFile)) return 0;
+  let txt; try { txt = fs.readFileSync(absFile, 'utf8'); } catch { return 0; }
+  let n = 0, out = txt;
+  for (const [oldRef, newRef] of refMap) {
+    if (out.includes(oldRef)) { out = out.split(oldRef).join(newRef); n++; }
+  }
+  if (n) fs.writeFileSync(absFile, out, 'utf8');
+  return n;
+}
+
+if (!APPLY) {
+  console.log('DRY RUN — nothing changed. Re-run with --apply to execute.');
+  process.exit(0);
+}
+
+let moved = 0, failed = 0;
+for (const m of moves) {
+  try {
+    if (fs.existsSync(m.to)) throw new Error('target already exists');
+    (isTracked(m.from) ? gitMv : fsMv)(m.from, m.to);
+    moved++;
+  } catch (e) {
+    failed++;
+    console.log(`  ❌ ${rel(m.from)} — ${e.message}`);
+  }
+}
+
+// rewrite references to the old prd.md paths across specs/ and .trace/
+let rewritten = 0;
+const scanForRefs = [...walk(specsAbs), ...walk(traceAbs)];
+for (const f of scanForRefs) rewritten += rewriteRefs(f) > 0 ? 1 : 0;
+
+console.log('');
+console.log(`✅ Renamed ${moved}/${moves.length} PRD file(s)${failed ? ` (${failed} failed)` : ''}.`);
+console.log(`✅ Rewrote internal references in ${rewritten} file(s).`);
+if (unresolved.length) console.log(`⚠️  ${unresolved.length} file(s) left in place (see list above).`);
+console.log('');
+console.log('Next:');
+console.log('  1. Review the renames (git status / git diff).');
+console.log('  2. Grep your CODE for stale `…/prd.md` refs the move did not touch.');
+console.log('  3. Run /validate-traces to confirm coverage still resolves.');
+console.log('  4. Commit.');
+console.log('');