spec-lite 1.4.2 → 1.4.5

package/skills/spec-brownfield-feature/SKILL.md

@@ -7,7 +7,7 @@ description: Discover features từ code, generate frd.md + fdd.md cho từng fe
 
 ## Overview
 
-Tạo `specs/main/feature/{F-XXX}-{feature-name}/frd.md` và `fdd.md` cho các features trong brownfield project.
+Tạo `.specs/main/feature/{F-XXX}-{feature-name}/frd.md` và `fdd.md` cho các features trong brownfield project.
 
 Skill này **tự discover** features từ routes, use cases, và test files, sau đó scan sâu để extract user stories, AC, và inter-component flows. Khi hoàn thành, **điền Feature Index vào prd.md**.
 
@@ -33,9 +33,9 @@ Skill này **tự discover** features từ routes, use cases, và test files, sa
 **Path:** Nếu có ARGUMENT là path → dùng làm root. Nếu không → CWD.
 
 **Load:**
-- `specs/main/prd.md` — kiểm tra Component Index đã được điền
-- `specs/main/domain.md` — đọc Glossary và Shared Entities
-- `specs/main/component/*/crd.md` — đọc Public Interface của từng component (để cross-reference trong fdd.md)
+- `.specs/main/prd.md` — kiểm tra Component Index đã được điền
+- `.specs/main/domain.md` — đọc Glossary và Shared Entities
+- `.specs/main/component/*/crd.md` — đọc Public Interface của từng component (để cross-reference trong fdd.md)
 
 **Kiểm tra preconditions:**
 
@@ -46,7 +46,7 @@ Nếu `prd.md` Component Index còn trống (không có C-XXX entries) → dừn
 > Component Index chưa có entries. Hãy chạy `/spec-brownfield-component` trước.
 > fdd.md cần tham chiếu C-XXX để mô tả inter-component flows.
 
-Nếu `specs/main/component/` không có crd.md nào → cảnh báo tương tự và dừng.
+Nếu `.specs/main/component/` không có crd.md nào → cảnh báo tương tự và dừng.
 
 **Attachments:**
 > Bạn có tài liệu bổ sung nào không? (user stories, test plans, wireframes, existing specs)
@@ -216,10 +216,10 @@ Với mỗi feature, generate 2 files dùng templates tương ứng:
 
 ```
 Sẽ tạo {N} features ({2N} files):
-  ✓ specs/main/feature/F-001-user-registration/frd.md  (4 NEEDS_CLARIFY)
-  ✓ specs/main/feature/F-001-user-registration/fdd.md  (2 NEEDS_CLARIFY)
-  ✓ specs/main/feature/F-002-authentication/frd.md     (1 NEEDS_CLARIFY)
-  ✓ specs/main/feature/F-002-authentication/fdd.md     (0 NEEDS_CLARIFY)
+  ✓ .specs/main/feature/F-001-user-registration/frd.md  (4 NEEDS_CLARIFY)
+  ✓ .specs/main/feature/F-001-user-registration/fdd.md  (2 NEEDS_CLARIFY)
+  ✓ .specs/main/feature/F-002-authentication/frd.md     (1 NEEDS_CLARIFY)
+  ✓ .specs/main/feature/F-002-authentication/fdd.md     (0 NEEDS_CLARIFY)
   ...
 
 Ghi tất cả? [y] hoặc review từng file trước [r]:
@@ -237,7 +237,7 @@ Ghi tất cả? [y] hoặc review từng file trước [r]:
 
 ### Bước 8: Điền Feature Index vào prd.md
 
-Sau khi artifacts đã được ghi, update `specs/main/prd.md` Feature Index:
+Sau khi artifacts đã được ghi, update `.specs/main/prd.md` Feature Index:
 
 ```
 Sẽ điền Feature Index vào prd.md:
@@ -267,8 +267,8 @@ Khi apply → đồng thời append entry vào `## Change History` của prd.md
 
 ```
 ✓ Generated {N} features:
-  specs/main/feature/F-001-user-registration/  (frd.md + fdd.md)
-  specs/main/feature/F-002-authentication/     (frd.md + fdd.md)
+  .specs/main/feature/F-001-user-registration/  (frd.md + fdd.md)
+  .specs/main/feature/F-002-authentication/     (frd.md + fdd.md)
   ...
 
 ✓ prd.md Feature Index: {N} entries đã được điền
@@ -279,7 +279,7 @@ NEEDS_CLARIFY summary — {total} items:
   ...
 
 Brownfield init hoàn tất! Main artifacts:
-  specs/main/
+  .specs/main/
   ├── prd.md           (Component Index: {N} | Feature Index: {N})
   ├── domain.md        (Glossary: {N} terms | Shared Entities: {N})
   ├── sad.md

package/skills/spec-brownfield-init/SKILL.md

@@ -7,7 +7,7 @@ description: Khởi tạo main artifacts (prd.md, domain.md, sad.md) cho brownfi
 
 ## Overview
 
-Tạo `specs/main/prd.md`, `specs/main/domain.md`, và `specs/main/sad.md` cho một project đã tồn tại.
+Tạo `.specs/main/prd.md`, `.specs/main/domain.md`, và `.specs/main/sad.md` cho một project đã tồn tại.
 
 Skill này chỉ tập trung vào **product và architecture level** — những gì có thể extract từ README, docs, config, và kiến trúc tổng thể. Component Index và Feature Index trong prd.md sẽ **để trống** — chúng sẽ được điền bởi `/spec-brownfield-component` và `/spec-brownfield-feature` sau khi scan code chuyên sâu.
 
@@ -17,9 +17,9 @@ Mỗi file output được sinh ra từ template tương ứng — đọc templa
 
 | Output file | Template |
 | --- | --- |
-| `specs/main/prd.md` | `templates/main/prd-template.md` |
-| `specs/main/domain.md` | `templates/main/domain-template.md` |
-| `specs/main/sad.md` | `templates/main/sad-template.md` |
+| `.specs/main/prd.md` | `templates/main/prd-template.md` |
+| `.specs/main/domain.md` | `templates/main/domain-template.md` |
+| `.specs/main/sad.md` | `templates/main/sad-template.md` |
 
 Giữ nguyên cấu trúc section và frontmatter từ template. Điền nội dung thu thập được từ scan và interview vào đúng vị trí.
 
@@ -32,7 +32,7 @@ Thông tin không thể detect từ code được đánh dấu nhất quán:
 ## When to Use
 
 - Onboarding một brownfield project vào SDD workflow
-- `specs/main/prd.md` chưa có hoặc còn trống
+- `.specs/main/prd.md` chưa có hoặc còn trống
 
 ## When NOT to Use
 
@@ -63,14 +63,14 @@ Load tất cả attachments trước khi scan. Dùng làm context bổ sung tron
 
 ### Bước 2: Kiểm tra existing specs
 
-Kiểm tra `specs/main/prd.md`, `specs/main/domain.md`, `specs/main/sad.md`:
+Kiểm tra `.specs/main/prd.md`, `.specs/main/domain.md`, `.specs/main/sad.md`:
 
 Nếu một trong ba đã có nội dung thực → cảnh báo:
 
 ```
 ⚠ File đã có nội dung:
-  - specs/main/prd.md
-  - specs/main/sad.md
+  - .specs/main/prd.md
+  - .specs/main/sad.md
 
 Skill này sẽ overwrite các file trên. Tiếp tục? [y/n]
 ```
@@ -236,7 +236,7 @@ Phần lớn auto từ scan. Chỉ hỏi 2 câu.
   [0] Chưa rõ → NEEDS_CLARIFY tất cả
 ```
 
-**7c. Hỏi additional constraints:**
+**7c. Hỏi architectural decisions (→ ADR Log):**
 
 ```
 ❓ Có architectural decision nào quan trọng chưa detect được không?
@@ -245,6 +245,8 @@ Phần lớn auto từ scan. Chỉ hỏi 2 câu.
   [0] Không có thêm
 ```
 
+Điền **ADR Log**: tạo ADR entry (status `accepted`) cho mỗi quyết định lớn — gồm cả các quyết định infer được ở 7a (architecture style, tech stack chính, communication) lẫn câu trả lời 7c. Mỗi entry ghi context/rationale + consequences ở mức suy luận được từ code; chỗ không chắc → NEEDS_CLARIFY.
+
 ---
 
 ### Bước 8: Review drafts
@@ -253,7 +255,7 @@ Hiển thị draft từng file lần lượt. Với mỗi file:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-DRAFT: specs/main/{file}
+DRAFT: .specs/main/{file}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 {nội dung draft}
 
@@ -270,7 +272,7 @@ Confirm? [y] Bỏ qua [n] Chỉnh sửa [e]:
 
 ### Bước 9: Save
 
-Tạo `specs/main/` nếu chưa có. Ghi các files đã được confirm.
+Tạo `.specs/main/` nếu chưa có. Ghi các files đã được confirm.
 
 **Change History:** Append entry vào section `## Change History` cuối mỗi file vừa ghi (`prd.md`, `domain.md`, `sad.md`) theo `conventions.md` §5.5:
 
@@ -281,9 +283,9 @@ Tạo `specs/main/` nếu chưa có. Ghi các files đã được confirm.
 ```
 
 ```
-✓ specs/main/prd.md        (Component Index và Feature Index: placeholder — chưa có)
-✓ specs/main/domain.md     (Glossary: {n} terms | Shared Entities: trống — sẽ mọc qua cascade)
-✓ specs/main/sad.md
+✓ .specs/main/prd.md        (Component Index và Feature Index: placeholder — chưa có)
+✓ .specs/main/domain.md     (Glossary: {n} terms | Shared Entities: trống — sẽ mọc qua cascade)
+✓ .specs/main/sad.md
 
 NEEDS_CLARIFY summary — {total} items cần làm rõ:
   prd.md:    {n} — [Problem Statement, Business Constraints, ...]

package/skills/spec-frd/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: spec-frd
-description: Author MỚI frd.md (Feature Requirements Document) trực tiếp ở feature level qua interview. Role BA, chạy trước integration. CREATE-only, đúng một feature/lần: frd đã tồn tại → redirect /spec-new (delta cascade); nguồn nhiều feature → redirect /spec-prd. Nhận F-XXX từ argument (hoặc chọn từ prd Feature Index) + tùy chọn nguồn baseline (path/@file/paste). Chỉ author frd.md (+ register feature row vào prd nếu feature mới) — reference component, KHÔNG tạo crd/cdd.
+description: Author MỚI frd.md (Feature Requirements Document) trực tiếp ở feature level qua interview. Role BA, chạy trước integration. CREATE-only, đúng một feature/lần: frd đã tồn tại → redirect /spec-new (delta cascade); nguồn nhiều feature → redirect /spec-prd. Nhận F-XXX từ argument (hoặc chọn từ prd Feature Index) + tùy chọn nguồn baseline (path/@file/paste). Chỉ author frd.md (+ register feature row vào prd nếu feature mới; cascade glossary term + định nghĩa shared entity lên domain, Owner TBD để /spec-sad gán) — reference component, KHÔNG tạo crd/cdd.
 ---
 
 # spec-frd
 
 ## Overview
 
-Author `specs/main/feature/{F-XXX}-{feature-slug}/frd.md` trực tiếp qua interview — **spec-first ở feature level**, do **BA** chạy trước khi bất kỳ integration nào bắt đầu.
+Author `.specs/main/feature/{F-XXX}-{feature-slug}/frd.md` trực tiếp qua interview — **spec-first ở feature level**, do **BA** chạy trước khi bất kỳ integration nào bắt đầu.
 
 `frd.md` là **what to build** của một feature: Overview, User Flows, Feature AC, User Stories, Verification Rules, Scope, Dependencies. Đây là baseline ổn định, **author một lần** — mọi thay đổi sau đó đi qua `/spec-new` (delta cascade).
 
@@ -20,10 +20,11 @@ Skill này là cặp greenfield đối xứng với `/spec-brownfield-feature` (
 **Phạm vi hẹp — chủ yếu frd.md:**
 - ✅ Author frd.md (7 sections) cho **một** feature **chưa có frd**.
 - ✅ *Reference* component frd phụ thuộc (Components Used) + ghi component cần-nhưng-chưa-có như **candidate**.
-- ✅ Nếu feature mục tiêu là feature mới chưa có trong Index → **register một row vào `prd.md > Features`** (side-effect hợp lệ duy nhất lên prd).
+- ✅ Nếu feature mục tiêu là feature mới chưa có trong Index → **register một row vào `prd.md > Features`** (side-effect hợp lệ lên prd).
+- ✅ **Cascade vocabulary lên `domain.md`** (Bước 4b — pha *mô tả hệ thống*/WHAT): glossary term + **định nghĩa entity đầy đủ** (attributes). `Owner` của entity để `TBD` cho `/spec-sad` điền ở pha *thiết kế hệ thống* (HOW). BA duyệt trước khi ghi. Đây là điểm khác với phiên bản trước (`/spec-frd` từng không đụng domain) — vocabulary sinh ra ở feature-authoring time nên seed luôn, thay vì để domain rỗng tới integration đầu tiên.
 - ❌ KHÔNG tạo/sửa `crd.md`/`cdd.md` — component artifacts ra đời ở integration time qua `/spec-new` cascade.
 - ❌ KHÔNG tạo `fdd.md` (inter-component design) hay `tsd.md` (test) — để skill/role khác lo.
-- ❌ KHÔNG đổi status feature đã có, không đụng sad/domain.
+- ❌ KHÔNG carve component / quyết `Owner` của shared entity (để `/spec-sad`/`/spec-new`); KHÔNG đổi status feature đã có; KHÔNG đụng sad.
 
 ## When to Use
 
@@ -59,7 +60,7 @@ Có nguồn → trích baseline cho từng section frd (overview, flows, stories
 
 ### Bước 1: Xác định feature
 
-**Precondition:** đọc `specs/main/prd.md`. Nếu không tồn tại / template rỗng → dừng:
+**Precondition:** đọc `.specs/main/prd.md`. Nếu không tồn tại / template rỗng → dừng:
 > `prd.md` chưa có nội dung. Hãy chạy `/spec-prd` trước.
 
 `/spec-frd` là skill **CREATE-only, đúng một feature mỗi lần chạy**. Xác định feature mục tiêu qua ba gate — phải pass cả ba mới vào interview.
@@ -103,7 +104,7 @@ Chọn feature để author frd:
 
 #### 1c. Create-only gate — frd.md CHƯA tồn tại
 
-Kiểm tra `specs/main/feature/{F-XXX}-*/frd.md`.
+Kiểm tra `.specs/main/feature/{F-XXX}-*/frd.md`.
 
 - **Chưa tồn tại** → tiếp Bước 2 (author mới).
 - **Đã tồn tại** → **DỪNG**, redirect `/spec-new`:
@@ -117,10 +118,10 @@ Kiểm tra `specs/main/feature/{F-XXX}-*/frd.md`.
 ### Bước 2: Load context
 
 Load:
-- `specs/main/prd.md` — Problem Statement, Target Users (personas), Scope, **row của feature này** trong Feature Index (tên, mô tả, priority), Component Index, **cột ADO** (nếu feature có ticket → lưu lại để spec.md sau này không tạo duplicate).
-- `specs/main/domain.md` — Glossary + Shared Entities liên quan.
-- `specs/main/sad.md` — bảng Components (góc nhìn kiến trúc, để biết C-XXX nào đã có boundary).
-- `specs/main/component/{C-XXX}-*/crd.md` — Public Interface của các component khả năng feature sẽ dùng (nếu đã tồn tại).
+- `.specs/main/prd.md` — Problem Statement, Target Users (personas), Scope, **row của feature này** trong Feature Index (tên, mô tả, priority), Component Index, **cột ADO** (nếu feature có ticket → lưu lại để spec.md sau này không tạo duplicate).
+- `.specs/main/domain.md` — Glossary + Shared Entities liên quan.
+- `.specs/main/sad.md` — bảng Components (góc nhìn kiến trúc, để biết C-XXX nào đã có boundary).
+- `.specs/main/component/{C-XXX}-*/crd.md` — Public Interface của các component khả năng feature sẽ dùng (nếu đã tồn tại).
 
 Tóm tắt context + surface assumptions:
 
@@ -186,6 +187,33 @@ Lý do: giữ **một authority duy nhất** cho việc carve component (archite
 
 ---
 
+### Bước 4b: Trích domain vocabulary (glossary + định nghĩa entity)
+
+Author frd là **điểm đầu tiên** business vocabulary xuất hiện cụ thể. Để `domain.md` không nằm rỗng tới integration đầu tiên (và để term không trôi/đụng nhau giữa các frd), skill seed vocabulary mới vào `domain.md` ngay tại BA-time. Giống VR và component candidate: **agent đề xuất, BA quyết** — không tự assert.
+
+Đọc `domain.md` (đã load ở Bước 2) để biết Glossary/Shared Entities **đã có gì**, rồi rà draft frd tìm cái **mới**:
+
+**1. Glossary term — ghi thẳng.** Thuật ngữ business xuất hiện trong frd mà chưa có trong domain Glossary. Glossary thuần vocabulary, không phụ thuộc component → cascade trực tiếp được. Với mỗi term đề xuất:
+> Term mới phát hiện: **{term}** — đề xuất định nghĩa: "{định nghĩa}". Thêm vào domain Glossary? [y / sửa / bỏ]
+
+Cấm: định nghĩa mơ hồ, hoặc nhét term thực ra là tên feature/component (không phải vocabulary nghiệp vụ).
+
+**2. Entity — định nghĩa đầy đủ (WHAT), `Owner` để design-time điền.** Đây là điểm tách bạch quan trọng:
+
+- **Define entity là *mô tả hệ thống* (WHAT)** → thuộc BA, làm ngay tại frd-time. BA định nghĩa entity đầy đủ: tên, mô tả, **attributes** (business type: text/number/money/date/email/phone), state machine nếu có lifecycle nghiệp vụ. Đây là vocabulary chung, không phải artifact hạng hai.
+- **Entity *nằm ở component nào* (`Owner`) là *thiết kế hệ thống* (HOW)** → thuộc architect, điền ở `/spec-sad` (hoặc `/spec-new` khi carve). `/spec-frd` **không carve component** nên **không** quyết `Owner`.
+
+Vì vậy khi seed entity vào domain Shared Entities:
+- Điền đầy đủ definition + attributes từ frd.
+- Để **`Owner: TBD (điền ở /spec-sad — design time)`** và **`Used by: TBD`**. Không phải vì entity "chưa chắc có thật", mà vì ownership là quyết định thiết kế chưa tới lượt.
+- Entity rõ ràng chỉ là cấu trúc dữ liệu kỹ thuật nội bộ (không phải vocabulary nghiệp vụ) → không thuộc domain; bỏ qua, để lộ ra ở `crd.md` lúc carve.
+
+> Entity feature mô tả: **{Entity}** với attributes {…}. Đây là vocabulary nghiệp vụ chung → mình seed định nghĩa vào domain (Owner để architect điền ở /spec-sad). Đồng ý? [y / sửa / bỏ]
+
+BA quyết **định nghĩa entity** (WHAT); `Owner` để `/spec-sad` cascade bổ sung (HOW). Xem two-phase cascade ở `conventions.md` §5.5.
+
+---
+
 ### Bước 5: Write — sinh draft
 
 Dùng `.claude/templates/main/feature/frd-template.md` làm skeleton, điền nội dung từ interview.
@@ -194,7 +222,9 @@ Dùng `.claude/templates/main/feature/frd-template.md` làm skeleton, điền n
 
 **Frontmatter** frd mới: theo template, `status: draft`, `owner: BA`, `feature_id: F-XXX`.
 
-Hiển thị **toàn bộ draft** cho user — chưa ghi file. Kèm danh sách component candidate (nếu có) và VR còn `TBD`.
+Hiển thị **toàn bộ draft** cho user — chưa ghi file. Kèm:
+- danh sách component candidate (nếu có) và VR còn `TBD`;
+- **danh sách domain vocabulary đề xuất** (Bước 4b): glossary term mới + định nghĩa shared entity (`Owner: TBD`), để BA duyệt trước khi cascade lên `domain.md`.
 
 #### Verification Rules — quy ước sinh
 
@@ -215,6 +245,7 @@ Hiển thị **toàn bộ draft** cho user — chưa ghi file. Kèm danh sách c
 > - User Stories + AC đo được chưa?
 > - Verification Rules đã confirm với BA chưa (không còn TBD ngoài ý muốn)?
 > - Components Used đúng chưa? Component candidate (nếu có) có hợp lý để chuyển cho /spec-sad không?
+> - Glossary term / định nghĩa shared entity đề xuất cascade lên domain đã đúng chưa? (term có phải vocabulary nghiệp vụ thật, entity có đáng là shared không, attributes đủ chưa?)
 
 Chỉ ghi file sau khi user confirm. Yêu cầu chỉnh → cập nhật draft → hỏi lại.
 
@@ -222,7 +253,7 @@ Chỉ ghi file sau khi user confirm. Yêu cầu chỉnh → cập nhật draft
 
 ### Bước 7: Save
 
-**7a. Ghi `specs/main/feature/{F-XXX}-{slug}/frd.md`** — tạo thư mục nếu chưa có. Status `draft` (lifecycle riêng của artifact).
+**7a. Ghi `.specs/main/feature/{F-XXX}-{slug}/frd.md`** — tạo thư mục nếu chưa có. Status `draft` (lifecycle riêng của artifact).
 
 Slug feature lấy từ tên trong prd Feature Index, kebab-case (ví dụ F-001 "Authentication" → `F-001-authentication`).
 
@@ -251,14 +282,36 @@ Và append Change History entry vào prd.md (theo `conventions.md` §5.5):
   - [NEW] F-XXX — {tên} (registered qua /spec-frd)
 ```
 
-Đây là **side-effect hợp lệ duy nhất** của `/spec-frd` lên prd — thêm một feature row. Việc này atomic với 7a/7b: nếu fail thì rollback cả frd.
+Đây là side-effect hợp lệ của `/spec-frd` lên prd — thêm một feature row. Việc này atomic với 7a/7b: nếu fail thì rollback cả frd.
+
+**7b''. (Chỉ khi Bước 4b/6 BA đã confirm vocabulary)** Cascade lên `.specs/main/domain.md`:
+
+- **Glossary** → append row `[NEW]` cho mỗi term đã confirm: `| {term} | {định nghĩa} | {example/context} |`.
+- **Shared Entities** → cho mỗi entity đã confirm, thêm một entry mới theo template với definition + attributes đầy đủ, để `**Owner:** TBD (điền ở /spec-sad — design time)` và `**Used by:** TBD`.
 
-**7c. KHÔNG đụng gì khác.** Không đổi status của các feature *đã có* (frd tồn tại ≠ integration bắt đầu; marker "→ frd.md tồn tại" derive từ file existence). Không thêm component vào Index (chỉ candidate). Không tạo crd/cdd/fdd/tsd. Không đụng sad/domain.
+Append **một** Change History entry vào `domain.md`, operation = `manual` (author trực tiếp ngoài integration — cùng quy ước với 7b, theo `conventions.md` §5.5):
+
+```markdown
+### {YYYY-MM-DD} — manual — update
+
+- **Glossary**:
+  - [NEW] {term} — {mô tả ngắn} (qua /spec-frd F-XXX)
+- **Shared Entities**:
+  - [NEW] {Entity} — định nghĩa + attributes; Owner TBD chờ /spec-sad (qua /spec-frd F-XXX)
+```
+
+(Nếu domain.md đang là skeleton create lần đầu thì entry vẫn `manual`/`update` — file đã được `/spec-prd` scaffold với operation `create` từ trước.) Atomic với 7a: domain cascade fail → rollback cả frd. `Owner` của entity do `/spec-sad`/`/spec-new` cascade bổ sung sau (HOW phase) qua `[MODIFY Owner]`.
+
+**7c. KHÔNG đụng gì khác.** Không đổi status của các feature *đã có* (frd tồn tại ≠ integration bắt đầu; marker "→ frd.md tồn tại" derive từ file existence). Không thêm component vào Index (chỉ candidate). Không carve component / không tự quyết `Owner` của shared entity. Không tạo crd/cdd/fdd/tsd. Không đụng sad.
 
 **7d. Thông báo kết quả:**
 
 ```
-✓ specs/main/feature/{F-XXX}-{slug}/frd.md đã được tạo (status: draft)
+✓ .specs/main/feature/{F-XXX}-{slug}/frd.md đã được tạo (status: draft)
+
+{nếu có} Domain cascade (pha mô tả hệ thống):
+  - Glossary: +{N} term
+  - Shared Entities: +{N} entity (định nghĩa đầy đủ; Owner TBD — chờ /spec-sad gán ở pha thiết kế)
 
 {nếu có} Component candidate cần carve (chuyển cho architect / integration):
   - {tên đề xuất} — {vai trò}
@@ -269,7 +322,7 @@ Và append Change History entry vào prd.md (theo `conventions.md` §5.5):
 Bước tiếp theo:
   - /spec-tsd F-XXX  → QC bootstrap test spec từ frd này
   - /spec-new F-XXX  → DEV bắt đầu integration (frd sẽ được consume, crd/cdd sinh qua cascade)
-  {nếu có candidate} - /spec-sad → architect chốt boundary cho component candidate
+  {nếu có candidate hoặc entity Owner TBD} - /spec-sad → architect chốt boundary component + gán Owner cho shared entity
 ```
 
 ---
@@ -282,6 +335,8 @@ Bước tiếp theo:
 | "BA cứ tạo luôn crd cho component cần" | Carve component là quyết định kiến trúc. BA tạo crd sớm = boundary sai sớm. Chỉ reference. |
 | "Verification rule mình tự điền cho nhanh" | VR là business decision. Agent tự assert = rule sai mà không ai review. |
 | "User Flows vẽ sau cũng được" | Flow buộc phải nghĩ edge case. Không có flow = AC thiếu nhánh thất bại. |
+| "BA gán luôn Owner component cho entity cho gọn" | Ownership là quyết định *thiết kế* (HOW). BA gán sớm = boundary sai sớm. Để `Owner: TBD`, `/spec-sad` điền. |
+| "Entity chưa biết owner thì khoan ghi vào domain" | Define entity là *mô tả* (WHAT) — độc lập với việc nó nằm ở component nào. Ghi định nghĩa luôn, Owner điền sau. |
 
 ## Red Flags
 
@@ -306,6 +361,7 @@ Bước tiếp theo:
 - [ ] ID bắt đầu từ 001 (create mới)
 - [ ] Components Used reference C-XXX có sẵn; component mới ghi candidate + surface cho /spec-sad
 - [ ] Nếu register feature mới: prd Features có row [NEW] + Change History entry; status feature đã có KHÔNG đổi
-- [ ] KHÔNG tạo crd/cdd/fdd/tsd; KHÔNG đụng sad/domain
-- [ ] Change History entry operation = `manual` (luôn `create`)
+- [ ] Domain cascade (nếu có vocabulary mới, đã BA confirm): Glossary term ghi đủ định nghĩa; Shared Entity ghi đủ definition + attributes với `Owner: TBD` (KHÔNG tự gán C-XXX); domain.md có Change History entry operation = `manual`
+- [ ] KHÔNG tạo crd/cdd/fdd/tsd; KHÔNG carve component / gán Owner entity; KHÔNG đụng sad
+- [ ] Change History entry (frd) operation = `manual` (luôn `create`)
 - [ ] User đã confirm trước khi ghi file

package/skills/spec-frd-update/SKILL.md

@@ -7,7 +7,7 @@ description: Migrate frd.md hiện có lên cấu trúc template mới nhất
 
 ## Overview
 
-Migrate các file `specs/main/feature/{F-XXX}-{slug}/frd.md` hiện có sang **format mới nhất** của [templates/main/feature/frd-template.md](../../templates/main/feature/frd-template.md).
+Migrate các file `.specs/main/feature/{F-XXX}-{slug}/frd.md` hiện có sang **format mới nhất** của [templates/main/feature/frd-template.md](../../templates/main/feature/frd-template.md).
 
 Skill này **chỉ làm migration mechanical + propose** — không phải BA interview. Mọi quyết định nội dung mới (Verification Rules content) đều cần user approve trước khi ghi.
 
@@ -67,7 +67,7 @@ Chạy `git status --porcelain`. Nếu output không rỗng (có file modified /
 Hãy commit hoặc stash thay đổi hiện tại trước khi chạy `/spec-frd-update`, rồi chạy lại.
 
 Files dirty:
-  M specs/main/feature/F-001-auth/frd.md
+  M .specs/main/feature/F-001-auth/frd.md
   ?? notes.md
 ```
 
@@ -80,7 +80,7 @@ Nếu repo không phải git repo → cảnh báo và yêu cầu confirm:
 
 ### Bước 1: Discover & classify
 
-Quét `specs/main/feature/*/frd.md`. Với mỗi file:
+Quét `.specs/main/feature/*/frd.md`. Với mỗi file:
 
 1. Parse headings và frontmatter.
 2. Run detection cho V1–V8.
@@ -123,11 +123,11 @@ Với mỗi FRD đã chọn, load các file sau (chỉ những gì cần thiết
 
 | File | Bắt buộc | Mục đích |
 |---|---|---|
-| `specs/main/feature/{F-XXX}-{slug}/frd.md` | ✓ | File cần migrate |
+| `.specs/main/feature/{F-XXX}-{slug}/frd.md` | ✓ | File cần migrate |
 | [templates/main/feature/frd-template.md](../../templates/main/feature/frd-template.md) | ✓ | Target structure — copy text cho V2/V3/V5 |
-| `specs/main/feature/{F-XXX}-{slug}/fdd.md` | nếu tồn tại | Cascade target cho V4 (AC→FAC rename) |
-| `specs/main/feature/{F-XXX}-{slug}/tsd.md` | nếu tồn tại | Cascade target cho V4 |
-| `specs/main/domain.md` (Shared Entities block) | optional | Cho V6 — match field name với entity glossary để pick semantic type consistent |
+| `.specs/main/feature/{F-XXX}-{slug}/fdd.md` | nếu tồn tại | Cascade target cho V4 (AC→FAC rename) |
+| `.specs/main/feature/{F-XXX}-{slug}/tsd.md` | nếu tồn tại | Cascade target cho V4 |
+| `.specs/main/domain.md` (Shared Entities block) | optional | Cho V6 — match field name với entity glossary để pick semantic type consistent |
 
 **KHÔNG load:**
 - `conventions.md` — template đã self-contained, load là thừa
@@ -183,7 +183,7 @@ Với mỗi FRD đã chọn, load các file sau (chỉ những gì cần thiết
   ```
 
 #### 4.3 Scan cascade references
-- Grep toàn `specs/` cho từng ID cũ.
+- Grep toàn `.specs/` cho từng ID cũ.
 - **CRITICAL**: chỉ remap những match THUỘC Feature AC (Bước 4.1 list). KHÔNG đụng Story AC trùng namespace `AC-F{NNN}-{seq}` — đây là string overlap nhưng khác counter.
 - Tạo bảng impact:
   ```
@@ -358,7 +358,7 @@ Cho mỗi FRD đã migrate:
 
 Nếu artifact chưa có section `## Change History` (vì template cũ) → tạo section mới ở cuối file rồi append entry. Đây cũng là một migration vector ngầm — đảm bảo mọi main artifact sau migration đều có Change History section.
 
-Rollback (nếu user phát hiện sai sau khi skill xong): `git checkout -- specs/main/feature/{F-XXX}-{slug}/` để revert toàn bộ feature dir, hoặc `git restore -p` để revert per-hunk.
+Rollback (nếu user phát hiện sai sau khi skill xong): `git checkout -- .specs/main/feature/{F-XXX}-{slug}/` để revert toàn bộ feature dir, hoặc `git restore -p` để revert per-hunk.
 
 Append vào [changelogs.md](../../changelogs.md) `## [Unreleased]`:
 

package/skills/spec-new/SKILL.md

@@ -7,7 +7,7 @@ description: Tạo spec.md cho một integration mới thông qua interview có
 
 ## Overview
 
-Tạo `spec.md` cho một integration mới trong `specs/integrations/{NNN}-{slug}/`.
+Tạo `spec.md` cho một integration mới trong `.specs/integrations/{NNN}-{slug}/`.
 
 `spec.md` là functional spec — định nghĩa **what to build**: vấn đề, requirements, acceptance criteria, out of scope. Không chứa technical design.
 
@@ -33,7 +33,7 @@ Tạo `spec.md` cho một integration mới trong `specs/integrations/{NNN}-{slu
 
 **Nếu không có ARGUMENT:**
 
-Đọc `specs/main/prd.md`. Nếu file không tồn tại hoặc là template rỗng → dừng:
+Đọc `.specs/main/prd.md`. Nếu file không tồn tại hoặc là template rỗng → dừng:
 > `prd.md` chưa có nội dung. Hãy chạy `/spec-prd` trước.
 
 Đọc toàn bộ bảng Features. Hiển thị **tất cả** features kèm trạng thái — không lọc — để thấy rõ feature nào có FRD cần update:
@@ -50,7 +50,7 @@ Features trong PRD:
 Chọn số feature để bắt đầu spec:
 ```
 
-Ghi chú `→ frd.md tồn tại` nếu file `specs/main/feature/{F-XXX}-*/frd.md` đã có.
+Ghi chú `→ frd.md tồn tại` nếu file `.specs/main/feature/{F-XXX}-*/frd.md` đã có.
 
 Nếu tất cả features đều Done → thông báo:
 > Tất cả features trong prd.md đã được implement. Nếu có yêu cầu mới, hãy truyền nó trực tiếp: `/spec-new <yêu cầu>`.
@@ -88,10 +88,10 @@ Lưu lại lựa chọn section.
 
 Từ raw requirement, agent xác định features và components liên quan, rồi load các file sau:
 
-- `specs/main/prd.md` — đọc Problem Statement, Target Users, Scope, Feature Index, Component Index; **đặc biệt ghi nhận cột `ADO` trong bảng Features** — nếu feature đã có ticket ID thì lưu lại `{feature_id → ado_ticket_id, ado_ticket_title, ado_ticket_url}`
-- `specs/main/domain.md` — đọc Glossary và Shared Entities
-- `specs/main/feature/{F-XXX}-{slug}/frd.md` — cho mỗi feature liên quan (nếu file đã tồn tại)
-- `specs/main/component/{C-XXX}-{slug}/crd.md` — cho mỗi component bị touched (nếu file đã tồn tại)
+- `.specs/main/prd.md` — đọc Problem Statement, Target Users, Scope, Feature Index, Component Index; **đặc biệt ghi nhận cột `ADO` trong bảng Features** — nếu feature đã có ticket ID thì lưu lại `{feature_id → ado_ticket_id, ado_ticket_title, ado_ticket_url}`
+- `.specs/main/domain.md` — đọc Glossary và Shared Entities
+- `.specs/main/feature/{F-XXX}-{slug}/frd.md` — cho mỗi feature liên quan (nếu file đã tồn tại)
+- `.specs/main/component/{C-XXX}-{slug}/crd.md` — cho mỗi component bị touched (nếu file đã tồn tại)
 
 Tóm tắt context và surface assumptions:
 
@@ -150,11 +150,11 @@ Từ title của integration, sinh slug:
 - Nếu từ prd.md: dùng `{feature-id}-{feature-slug}`, ví dụ: `f001-authentication`
 
 Xác định số thứ tự (`NNN`):
-- Liệt kê các thư mục hiện có trong `specs/integrations/` theo pattern `{NNN}-*`
+- Liệt kê các thư mục hiện có trong `.specs/integrations/` theo pattern `{NNN}-*`
 - Lấy số lớn nhất hiện có và cộng thêm 1, format 3 chữ số (ví dụ: `001`, `002`, `012`)
 - Nếu chưa có thư mục nào → bắt đầu từ `001`
 
-Output path: `specs/integrations/{NNN}-{slug}/spec.md`
+Output path: `.specs/integrations/{NNN}-{slug}/spec.md`
 
 ---
 
@@ -258,7 +258,8 @@ Tạo block nếu integration:
 
 Tạo block nếu integration:
 - Giới thiệu glossary term mới → row [NEW] trong Glossary
-- Giới thiệu shared entity mới (entity sẽ được dùng bởi 2+ component) → entity [NEW] với `Owner: C-XXX`
+- Giới thiệu shared entity mới (entity sẽ được dùng bởi 2+ component) → entity [NEW] với `Owner: C-XXX` (component đã carve trong integration này); component chưa carve → `Owner: TBD`, `/spec-sad` gán sau (xem two-phase cascade `conventions.md` §5.5)
+- Gán owner cho entity còn `Owner: TBD` (do pha mô tả seed) → entity [MODIFY Owner] `TBD → C-XXX`
 - Sửa định nghĩa entity hiện có → entity [MODIFY ...]
 
 **`sad.md`**
@@ -339,7 +340,7 @@ Chỉ tiến hành Bước 7 sau khi user confirm. Nếu user yêu cầu chỉnh
 
 ### Bước 7: Save + Auto-cascade
 
-Tạo thư mục `specs/integrations/{NNN}-{slug}/` nếu chưa có.
+Tạo thư mục `.specs/integrations/{NNN}-{slug}/` nếu chưa có.
 
 **[7.1] Ghi spec.md** với status `approved` (không phải `draft` — human đã confirm ở Bước 6 chính là approval). Frontmatter `features` và `components` phải được điền theo những gì đã nhận diện ở Bước 2.
 
@@ -391,7 +392,7 @@ Cho mỗi artifact:
 **[7.4] Thông báo kết quả:**
 
 ```
-✓ specs/integrations/{NNN}-{slug}/spec.md đã được tạo (status: approved)
+✓ .specs/integrations/{NNN}-{slug}/spec.md đã được tạo (status: approved)
 
 Auto-cascade applied:
   ✓ prd.md — {summary}

package/skills/spec-prd/SKILL.md

@@ -7,15 +7,15 @@ description: Điền hoặc cập nhật prd.md — Product Requirements Documen
 
 ## Overview
 
-Tạo nội dung cho `specs/main/prd.md` thông qua interview có cấu trúc. PRD là nguồn sự thật ở product level — nó định nghĩa vấn đề, users, scope, features, components, và NFRs trước khi bất kỳ technical decision nào được đưa ra.
+Tạo nội dung cho `.specs/main/prd.md` thông qua interview có cấu trúc. PRD là nguồn sự thật ở product level — nó định nghĩa vấn đề, users, scope, features, components, và NFRs trước khi bất kỳ technical decision nào được đưa ra.
 
-Skill này cũng scaffold `specs/main/domain.md` skeleton nếu chưa tồn tại — domain.md sẽ được mọc dần qua cascade từ integrations (glossary terms, shared entities).
+Skill này cũng scaffold `.specs/main/domain.md` skeleton nếu chưa tồn tại — domain.md mọc dần qua cascade ở hai pha: mô tả (`/spec-frd`, `/spec-new` seed glossary + định nghĩa entity, `Owner: TBD`) và thiết kế (`/spec-sad` gán `Owner`). Xem two-phase cascade `conventions.md` §5.5.
 
 PRD không chứa: tech stack, implementation details, entity schema, glossary, business rules — những thứ đó thuộc về `sad.md` hoặc `domain.md`.
 
 ## When to Use
 
-- `specs/main/prd.md` chưa có nội dung hoặc vẫn còn là template
+- `.specs/main/prd.md` chưa có nội dung hoặc vẫn còn là template
 - Cần bổ sung hoặc cập nhật một phần của PRD hiện tại
 - Requirements thay đổi và PRD cần được đồng bộ lại
 
@@ -46,6 +46,32 @@ Chạy qua các phép thử; đa số phiếu nghiêng đâu thì xếp vào đ
 | **Đặt tên** | Danh từ hệ thống (`auth`, `payment`) | Luồng nghiệp vụ (`checkout-flow`, `password-reset`) |
 | **Trả lời** | "Phần nào của hệ thống chịu trách nhiệm X?" | "User làm được gì, nhận giá trị gì?" |
 
+### Mục có tính chất kép — vừa Feature vừa Component
+
+Litmus test ở trên giả định mỗi mục rơi vào **một** bucket. Nhưng một số mục có **hai mặt** và xứng đáng đăng ký ở **cả hai** index — kinh điển là `auth`:
+
+- **Mặt trải nghiệm người dùng** (đăng nhập SSO/OTP, có Flows + User Stories + Acceptance Criteria) → **Feature**.
+- **Mặt năng lực cross-cutting** (RBAC enforce mọi endpoint, session) mà mọi feature khác tham chiếu → **Component**.
+
+**Phép thử tính kép** — một mục là *cả hai* khi thỏa CẢ hai điều kiện:
+
+1. Nó là component **Given** (xem Given/Derived bên dưới — thường trúng câu 2 Mandated-substrate), VÀ
+2. Nó có một **trải nghiệm người dùng** (Flows/US/AC) mà (a) **không** biểu diễn được trong `crd.md` (CRD chỉ có Role/Responsibilities/Interface/Business Rules — KHÔNG có Flows/User Stories/Acceptance Criteria), và (b) **không** thuộc sở hữu của feature nào khác.
+
+Nếu kép → đăng ký **một Feature (F-XXX)** cho mặt UX + **một Component (C-XXX)** cho mặt năng lực, và chia trách nhiệm dứt khoát:
+- Flows / User Stories / Acceptance Criteria / rule của luồng → **Feature** (`frd.md`), trỏ tới component qua mục "Components Used".
+- Năng lực dùng chung + interface + rule nội bộ → **Component** (`crd.md`/`cdd.md`). Mô tả component **thu hẹp** về mặt năng lực, ghi rõ "UX thuộc F-XXX".
+
+| Ứng viên | Mặt Feature (UX) | Mặt Component (năng lực) | Kết luận |
+| --- | --- | --- | --- |
+| auth | login SSO/OTP, lockout | RBAC enforce, session/token | **kép** |
+| notification | notification center (chuông/panel, mark-read) | kênh gửi email + push dùng chung | **kép** |
+| file-storage | document repository (upload/preview/download) | blob storage + access control | **kép** |
+| payment-gateway / e-signature / erp-adapter | — (UX nằm trong feature tiêu thụ) | adapter tích hợp ngoài | **component-only** |
+| checkout, password-reset | luồng nghiệp vụ | — (không năng lực cross-cutting) | **feature-only** |
+
+**Cảnh báo:** đa số component **External** (câu 1 — adapter Stripe/DocuSign/BC) là **component-only** — trải nghiệm dùng chúng (thanh toán, ký, xem dữ liệu BC) thuộc về các feature tiêu thụ, bản thân adapter không có UX riêng. Tính kép chủ yếu xuất hiện ở component **Mandated-substrate** (câu 2: auth, notification, file-storage).
+
 ### Quy tắc đặt tên (cho cả Feature và Component)
 
 **Goldilocks:** đặt tên ở mức trừu tượng **cao nhất mà vẫn truyền đạt đúng MỘT trách nhiệm/luồng rõ ràng**. Cao hơn → mất boundary; thấp hơn → rò rỉ chi tiết. Tên dùng kebab-case.
@@ -92,6 +118,7 @@ Input là **baseline, không phải chân lý tuyệt đối**:
 
 - Reuse tên/ID/boundary nếu input đã có → không tự đẻ cấu trúc song song.
 - Vẫn chạy litmus test (phân loại) + Given/Derived để **validate**. Nếu input gọi X là "component" mà nó fail ownership test → flag, đề xuất reclassify thành feature (không im lặng bê nguyên).
+- Chạy **Phép thử tính kép** cho mọi component Given. Nếu input gọi X là "component" (vd `auth`) nhưng X cũng có trải nghiệm người dùng riêng (SSO/OTP flow, có Flows/US/AC) không thuộc feature khác → flag, đề xuất đăng ký **thêm** một Feature cho mặt UX và thu hẹp component về mặt năng lực — đừng để mặt UX không có nhà.
 - Component **Derived** do input cung cấp → ghi nhận như *candidate*, chuyển sang `/spec-sad`, **không** nhồi vào Component Index của PRD.
 - Phần input thiếu → mới interview để bù.
 
@@ -118,9 +145,9 @@ Nếu không có nguồn → bỏ qua, interview từ đầu như bình thườn
 
 ### Bước 1: Kiểm tra preconditions
 
-Đọc `specs/main/prd.md`:
+Đọc `.specs/main/prd.md`:
 
-- **File không tồn tại** → tạo thư mục `specs/main/` (nếu chưa có) rồi tiến hành Bước 2 (full interview).
+- **File không tồn tại** → tạo thư mục `.specs/main/` (nếu chưa có) rồi tiến hành Bước 2 (full interview).
 
 - **File là template rỗng** → tiến hành Bước 2 (full interview).
 
@@ -205,6 +232,8 @@ Sau đó hỏi tuần tự, từng phần một — không hỏi tất cả cùn
 > - **Given** (trúng câu 1 External hoặc câu 2 Mandated-substrate) → khai vào Component Index.
 > - **Derived** (câu 3 — boundary phụ thuộc cách carve lõi nghiệp vụ hoặc đánh đổi NFR, vd `order`, `pricing`) → **KHÔNG** khai. Để `/spec-sad` chốt, hoặc mọc qua `/spec-new F-XXX` cascade.
 >
+> Với mỗi component **Given** (nhất là Mandated-substrate), chạy thêm **Phép thử tính kép** (xem section "Mục có tính chất kép"): nếu nó cũng có trải nghiệm người dùng riêng (Flows/US/AC) không thuộc feature khác → đăng ký **thêm** một Feature cho mặt UX vào Phần 4, và thu hẹp mô tả component về mặt năng lực. Vd `auth` → Feature `authentication` (login UX) + Component `auth` (RBAC enforce).
+>
 > **KHÔNG** mechanical-derive components từ feature areas (vd: thấy "Pricing" trong yêu cầu → tạo ngay `C-pricing`; đó là Derived). Section này có thể chỉ có 3-6 entries, hoặc thậm chí trống. Đừng cố fill cho đủ.
 
 **Phần 6 — Non-Functional Requirements:**
@@ -240,11 +269,11 @@ Chỉ ghi file sau khi user confirm. Nếu user yêu cầu chỉnh sửa → c
 
 ### Bước 5: Save
 
-**5a. Ghi `specs/main/prd.md`** — nội dung đã được confirm, thay thế toàn bộ nội dung cũ.
+**5a. Ghi `.specs/main/prd.md`** — nội dung đã được confirm, thay thế toàn bộ nội dung cũ.
 
-**5b. Scaffold `specs/main/domain.md`** *(chỉ khi file này chưa tồn tại)*:
+**5b. Scaffold `.specs/main/domain.md`** *(chỉ khi file này chưa tồn tại)*:
 
-- Copy `.claude/templates/main/domain-template.md` thành `specs/main/domain.md`.
+- Copy `.claude/templates/main/domain-template.md` thành `.specs/main/domain.md`.
 - Section **Glossary** giữ format bảng rỗng — terms sẽ được thêm dần qua cascade từ integrations.
 - Section **Shared Entities** giữ block placeholder — entities sẽ mọc dần qua cascade khi integration giới thiệu shared entity.
 
@@ -264,8 +293,8 @@ Nếu `domain.md` đã tồn tại với nội dung thực → không đụng t
 
 Thông báo kết quả:
 ```
-✓ specs/main/prd.md đã được cập nhật (status: draft)
-{nếu vừa scaffold} ✓ specs/main/domain.md đã được scaffold (skeleton — sẽ mọc dần qua cascade)
+✓ .specs/main/prd.md đã được cập nhật (status: draft)
+{nếu vừa scaffold} ✓ .specs/main/domain.md đã được scaffold (skeleton — sẽ mọc dần qua cascade)
 
 Bước tiếp theo:
   - /spec-sad → thiết kế kiến trúc kỹ thuật
@@ -300,7 +329,8 @@ Trước khi kết thúc, kiểm tra:
 - [ ] Out of Scope có ít nhất 1 item với lý do
 - [ ] Features có ít nhất 1 item, mỗi item có ID (F-XXX), tên, mô tả, priority. Mỗi item pass litmus test (đơn vị delivery, không phải ownership)
 - [ ] Components: mọi entry là **Given** (trúng câu 1 External hoặc câu 2 Mandated-substrate). Không có component **Derived** (boundary phụ thuộc carve lõi nghiệp vụ — thuộc `/spec-sad`). Có thể trống. Mỗi item có ID (C-XXX), tên kebab-case, mô tả 1 câu
-- [ ] Nếu input context có sẵn feature/component: đã reuse làm baseline, đã validate qua litmus + Given/Derived, đã flag mục phân loại sai (nếu có)
+- [ ] Đã chạy **Phép thử tính kép** cho mọi component Given: mục có cả mặt UX riêng (vd auth/notification/file-storage) được đăng ký ở **CẢ** Feature Index lẫn Component Index, mô tả mỗi mặt thu hẹp đúng phạm vi (UX→feature, năng lực→component)
+- [ ] Nếu input context có sẵn feature/component: đã reuse làm baseline, đã validate qua litmus + Given/Derived + Phép thử tính kép, đã flag mục phân loại sai (nếu có)
 - [ ] Mỗi NFR có target đo được (không phải "nhanh", "bảo mật chung chung")
 - [ ] domain.md tồn tại (đã scaffold skeleton hoặc có nội dung sẵn)
 - [ ] User đã confirm trước khi file được ghi