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

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/publishing.md

@@ -48,13 +48,28 @@ npm whoami
 3. Điền:
    - Name: `publish-spec-driven-docs`
    - Expiration: 1 year
-   - Packages: chọn `@edupia-tutor/spec-driven-docs` → **Read and write**
+   - **Bypass 2FA**: **bật** (bắt buộc — nếu không, publish sẽ bị chặn với lỗi `403 ... Two-factor authentication ... is required`)
+   - Packages and scopes: chọn `@edupia-tutor/spec-driven-docs` (hoặc cả scope `@edupia-tutor`) → **Read and write**
 4. Copy token, lưu vào nơi an toàn
 
-Publish với token:
+> ⚠️ **KHÔNG** có flag `npm publish --token <token>` — npm sẽ hiểu `<token>` là tên package và báo lỗi `404 Not Found`. Token phải nạp qua npm config/`.npmrc` như dưới.
+
+Publish với token — nạp token vào config trước, rồi publish:
+
+```powershell
+# Nạp token (ghi đè token đăng nhập hiện tại trong .npmrc)
+npm config set //registry.npmjs.org/:_authToken <your-token>
+
+npm publish --access public
+
+# (tùy chọn) gỡ token khỏi .npmrc sau khi xong — sẽ phải npm login lại lần sau
+npm config delete //registry.npmjs.org/:_authToken
+```
+
+**Cách khác — dùng OTP (nếu account đã bật 2FA app, không cần token bypass):**
 
 ```powershell
-npm publish --token <your-token>
+npm publish --access public --otp=<mã-6-số>
 ```
 
 ---
@@ -86,6 +101,8 @@ Lệnh này tự động cập nhật `version` trong `package.json` và tạo g
 npm publish
 ```
 
+> Nếu gặp `403 ... Two-factor authentication ... is required`: thêm `--otp=<mã-6-số>`, hoặc dùng granular token có **Bypass 2FA** (xem mục **2.2 — Tạo Access Token**). Access `public` đã set sẵn trong `package.json` (`publishConfig`).
+
 ### Bước 4 — Push git (bao gồm tag vừa tạo)
 
 ```powershell

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.0",
+  "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('');