spec-lite 1.4.2 → 1.4.5

package/skills-overview.md

@@ -8,13 +8,13 @@ Dùng khi bắt đầu dự án mới chưa có code. Mục tiêu: bootstrap `pr
 
 | Command | Reads | Writes |
 | --- | --- | --- |
-| `/spec-prd` | — *(tùy chọn: nguồn baseline path/@file/paste)* | `specs/main/prd.md`, `specs/main/domain.md` *(skeleton)* |
-| `/spec-sad` | `prd.md`, `domain.md` | `specs/main/sad.md` |
-| `/spec-frd [F-XXX]` *(tùy chọn)* | `prd.md`, `domain.md`, `sad.md`, `crd(s)` *(+ nguồn baseline)* | `specs/main/feature/{F-XXX}-*/frd.md` *(+ register feature row vào `prd.md` nếu feature mới)* |
+| `/spec-prd` | — *(tùy chọn: nguồn baseline path/@file/paste)* | `.specs/main/prd.md`, `.specs/main/domain.md` *(skeleton)* |
+| `/spec-sad` | `prd.md`, `domain.md` | `.specs/main/sad.md` *(+ gán `Owner` cho shared entity còn TBD trong `domain.md`)* |
+| `/spec-frd [F-XXX]` *(tùy chọn)* | `prd.md`, `domain.md`, `sad.md`, `crd(s)` *(+ nguồn baseline)* | `.specs/main/feature/{F-XXX}-*/frd.md` *(+ register feature row vào `prd.md` nếu feature mới; + cascade glossary/entity vào `domain.md`)* |
 
 ### `/spec-prd`
 
-Tạo hoặc cập nhật `specs/main/prd.md` thông qua interview có cấu trúc. Ngoài ra **scaffold luôn `specs/main/domain.md` skeleton** (Glossary placeholder + Shared Entities rỗng) — domain mọc dần qua cascade từ integrations.
+Tạo hoặc cập nhật `.specs/main/prd.md` thông qua interview có cấu trúc. Ngoài ra **scaffold luôn `.specs/main/domain.md` skeleton** (Glossary placeholder + Shared Entities rỗng) — domain mọc dần qua cascade ở hai pha: mô tả (`/spec-frd`, `/spec-new` seed glossary + định nghĩa entity) và thiết kế (`/spec-sad` gán `Owner`).
 
 **Sections template** (7): Problem Statement · Target Users · Scope · Features · Components · Non-Functional Requirements · Business Constraints
 
@@ -33,11 +33,13 @@ Chọn `A` → interview tuần tự 7 sections template (sections thừa không
 
 ### `/spec-sad`
 
-Tạo hoặc cập nhật `specs/main/sad.md`. Yêu cầu `prd.md` và `domain.md` đã tồn tại (cả hai do `/spec-prd` scaffold).
+Tạo hoặc cập nhật `.specs/main/sad.md`. Yêu cầu `prd.md` và `domain.md` đã tồn tại (cả hai do `/spec-prd` scaffold).
 
 Trước khi interview, đọc `prd.md` (NFRs, constraints) và `domain.md` (glossary, shared entities) để surface assumptions và đề xuất options phù hợp khi user chưa quyết định.
 
-**Sections template** (7): Architectural Style · System Overview · Tech Stack · Cross-Cutting Concerns · Inter-Service Communication · Infrastructure Overview · Architectural Guardrails
+**Cascade lên `domain.md` (pha thiết kế/HOW):** carve component là việc thiết kế, nên sau khi Components rõ, `/spec-sad` gán `Owner: C-XXX` + `Used by` cho shared entity mà pha mô tả (`/spec-frd`/`/spec-new`) để `Owner: TBD`. Đây là nửa HOW của domain two-phase cascade.
+
+**Sections template** (8): Architectural Style · System Overview · Tech Stack · Cross-Cutting Concerns · Inter-Service Communication · Infrastructure Overview · Architectural Guardrails · ADR Log
 
 **Khi file chưa tồn tại** → full interview tuần tự từng section.
 
@@ -51,7 +53,7 @@ Nếu `prd.md` chưa có → dừng, yêu cầu chạy `/spec-prd` trước.
 
 ### `/spec-frd [F-XXX]` *(tùy chọn)*
 
-BA author `specs/main/feature/{F-XXX}-*/frd.md` trực tiếp qua interview — **spec-first ở feature level**, chạy *trước* khi DEV bắt đầu integration. Cặp greenfield đối xứng với `/spec-brownfield-feature` (vốn reverse-engineer frd từ code).
+BA author `.specs/main/feature/{F-XXX}-*/frd.md` trực tiếp qua interview — **spec-first ở feature level**, chạy *trước* khi DEV bắt đầu integration. Cặp greenfield đối xứng với `/spec-brownfield-feature` (vốn reverse-engineer frd từ code).
 
 Nhận F-XXX từ argument (hoặc chọn từ prd Feature Index) + tùy chọn nguồn baseline (path/@file/paste như `/spec-prd`). Yêu cầu `prd.md` tồn tại.
 
@@ -65,8 +67,10 @@ Nhận F-XXX từ argument (hoặc chọn từ prd Feature Index) + tùy chọn
 **Phạm vi hẹp — chủ yếu `frd.md`:**
 - Reference component frd phụ thuộc (Components Used → C-XXX có sẵn).
 - Component cần-nhưng-chưa-có → ghi *candidate* + Open Question cho `/spec-sad`/architect chốt boundary.
-- Có thể register **một** feature row vào prd (side-effect hợp lệ duy nhất lên prd). **KHÔNG** tạo `crd.md`/`cdd.md` (sinh ở integration time qua `/spec-new` cascade), không tạo `fdd.md`/`tsd.md`, không đổi status feature đã có, không đụng sad/domain.
-- Change History operation = `manual`. Verification Rules dùng quy ước option-suggester của `/spec-new` (BA owns).
+- Có thể register **một** feature row vào prd (side-effect lên prd).
+- **Cascade vocabulary lên `domain.md`** (pha mô tả/WHAT): glossary term + **định nghĩa shared entity** (attributes), `Owner: TBD` để `/spec-sad` gán ở pha thiết kế (HOW). BA define entity, KHÔNG carve/gán Owner.
+- **KHÔNG** tạo `crd.md`/`cdd.md` (sinh ở integration time qua `/spec-new` cascade), không tạo `fdd.md`/`tsd.md`, không đổi status feature đã có, không đụng sad.
+- Change History operation = `manual` (cả frd lẫn domain). Verification Rules dùng quy ước option-suggester của `/spec-new` (BA owns).
 
 Bỏ qua bước này cũng được — `/spec-new` sẽ tự tạo frd làm fallback khi integration đầu tiên chạm tới feature.
 
@@ -253,17 +257,17 @@ Sau khi main artifacts đã sẵn sàng (từ greenfield hoặc brownfield), m
 
 | Command | Reads | Writes |
 | --- | --- | --- |
-| `/spec-new [requirement]` | `prd.md`, `domain.md`, frd(s), crd(s) | `specs/integrations/{slug}/spec.md` |
-| `/spec-tech [number]` | `sad.md`, `domain.md`, cdd(s), fdd(s), `spec.md` | `specs/integrations/{slug}/tech.md` |
-| `/spec-test [number]` | `spec.md`, frd(s), tsd(s), `tech.md` *(optional)* | `specs/integrations/{slug}/test.md`, `feature/{F-XXX}/tsd.md` |
+| `/spec-new [requirement]` | `prd.md`, `domain.md`, frd(s), crd(s) | `.specs/integrations/{slug}/spec.md` |
+| `/spec-tech [number]` | `sad.md`, `domain.md`, cdd(s), fdd(s), `spec.md` | `.specs/integrations/{slug}/tech.md` |
+| `/spec-test [number]` | `spec.md`, frd(s), tsd(s), `tech.md` *(optional)* | `.specs/integrations/{slug}/test.md`, `feature/{F-XXX}/tsd.md` |
 | `/plan` | `spec.md`, `tech.md`, `domain.md` | `plan.md`, `todo.md` |
 | `/build` | `plan.md`, `todo.md` | *(source code)* |
 | `/review-integration` | `spec.md`, `tech.md`, `plan.md`, `todo.md`, *(source code)* | *(findings report)* |
-| `/archive` | `specs/integrations/` | `specs/archive/` |
+| `/archive` | `.specs/integrations/` | `.specs/archive/` |
 
 ### `/spec-new [requirement]`
 
-Tạo `specs/integrations/{slug}/spec.md` cho một integration mới. Chạy bởi BA.
+Tạo `.specs/integrations/{slug}/spec.md` cho một integration mới. Chạy bởi BA.
 
 **Nếu không có argument** → đọc `prd.md`, hiển thị danh sách features có `Status = TODO`, user chọn số.
 
@@ -283,9 +287,9 @@ Sau khi confirm → ghi `spec.md`, cập nhật `prd.md`: Status `TODO → In Pr
 
 ### `/spec-tech [number]`
 
-Tạo `specs/integrations/{slug}/tech.md` cho một integration. Chạy bởi DEV sau khi `spec.md` đã được approve.
+Tạo `.specs/integrations/{slug}/tech.md` cho một integration. Chạy bởi DEV sau khi `spec.md` đã được approve.
 
-**Luôn hiển thị danh sách tất cả integrations** trong `specs/integrations/`, đánh dấu `✓` những cái đã có `tech.md`. Nếu có argument → argument là số thứ tự (`1`, `001`...), chọn luôn không cần hiển thị.
+**Luôn hiển thị danh sách tất cả integrations** trong `.specs/integrations/`, đánh dấu `✓` những cái đã có `tech.md`. Nếu có argument → argument là số thứ tự (`1`, `001`...), chọn luôn không cần hiển thị.
 
 Nếu integration đã có `tech.md` → hỏi confirm trước khi ghi đè.
 
@@ -299,9 +303,9 @@ Context load: `spec.md` + `sad.md` + `domain.md` + `cdd.md` (cho mỗi component
 
 ### `/spec-test [number]`
 
-Tạo `specs/integrations/{slug}/test.md` cho một integration. Chạy bởi **QC** sau khi `spec.md` đã được approve. **Song song / độc lập** với `/spec-tech` — cả hai chỉ phụ thuộc `spec.md`. Không có thứ tự bắt buộc giữa chúng.
+Tạo `.specs/integrations/{slug}/test.md` cho một integration. Chạy bởi **QC** sau khi `spec.md` đã được approve. **Song song / độc lập** với `/spec-tech` — cả hai chỉ phụ thuộc `spec.md`. Không có thứ tự bắt buộc giữa chúng.
 
-**Luôn hiển thị danh sách tất cả integrations** trong `specs/integrations/`, đánh dấu `✓` những cái đã có `test.md`. Nếu có argument → chọn luôn không cần hiển thị.
+**Luôn hiển thị danh sách tất cả integrations** trong `.specs/integrations/`, đánh dấu `✓` những cái đã có `test.md`. Nếu có argument → chọn luôn không cần hiển thị.
 
 **Gate check:** spec.md phải `approved` + `features:` non-empty. Integration có `features: []` (thuần component) → dừng vì component-level `tsd` không tồn tại trong kit này.
 
@@ -326,7 +330,7 @@ QC review: override priority defaults, fill placeholders (env / data / OOS / str
 Tạo `plan.md` và `todo.md` từ `spec.md` + `tech.md`. Là SDD wrapper quanh `planning-and-task-breakdown`.
 
 **Bước 1: Xác định integration**
-Quét `specs/integrations/`, hiển thị danh sách với trạng thái `spec✓/—`, `tech✓/—`, `plan✓/—`. Nếu có argument → chọn luôn. Nếu `plan.md`/`todo.md` đã tồn tại → hỏi trước khi ghi đè.
+Quét `.specs/integrations/`, hiển thị danh sách với trạng thái `spec✓/—`, `tech✓/—`, `plan✓/—`. Nếu có argument → chọn luôn. Nếu `plan.md`/`todo.md` đã tồn tại → hỏi trước khi ghi đè.
 
 **Bước 2: Load và surface context**
 Đọc `spec.md`, `tech.md`, `domain.md`. Surface tóm tắt (features, components, AC IDs, thay đổi kỹ thuật, shared entities) và assumptions để user confirm. Plan mode từ đây — chỉ đọc, không viết code.
@@ -379,17 +383,17 @@ Review implementation sau `/build` theo năm trục: correctness, readability, a
 
 ### `/archive`
 
-Di chuyển integration đã hoàn thành hoặc không còn active từ `specs/integrations/` sang `specs/archive/` để dọn dẹp thư mục làm việc chính.
+Di chuyển integration đã hoàn thành hoặc không còn active từ `.specs/integrations/` sang `.specs/archive/` để dọn dẹp thư mục làm việc chính.
 
-**Bước 1 — Kiểm tra thư mục:** Tự động tạo `specs/archive/` nếu chưa tồn tại.
+**Bước 1 — Kiểm tra thư mục:** Tự động tạo `.specs/archive/` nếu chưa tồn tại.
 
-**Bước 2 — Liệt kê:** Quét `specs/integrations/`, hiển thị numbered list kèm status (đọc từ `spec.md` nếu có). Nếu không có integration nào → thông báo và dừng.
+**Bước 2 — Liệt kê:** Quét `.specs/integrations/`, hiển thị numbered list kèm status (đọc từ `spec.md` nếu có). Nếu không có integration nào → thông báo và dừng.
 
 **Bước 3 — Xác nhận:** Hiển thị preview mapping `integrations/{slug}/ → archive/{slug}/` trước khi di chuyển. Chờ user confirm.
 
-**Bước 4 — Di chuyển:** Move toàn bộ thư mục, giữ nguyên cấu trúc bên trong. Nếu slug đã tồn tại trong `specs/archive/` → bỏ qua và cảnh báo để tránh ghi đè.
+**Bước 4 — Di chuyển:** Move toàn bộ thư mục, giữ nguyên cấu trúc bên trong. Nếu slug đã tồn tại trong `.specs/archive/` → bỏ qua và cảnh báo để tránh ghi đè.
 
-**Bước 5 — Kết quả:** Liệt kê integrations đã archive, integrations bị bỏ qua (nếu có), và số integration còn lại trong `specs/integrations/`.
+**Bước 5 — Kết quả:** Liệt kê integrations đã archive, integrations bị bỏ qua (nếu có), và số integration còn lại trong `.specs/integrations/`.
 
 ---
 
@@ -432,7 +436,7 @@ Khác với `/review-integration` (chạy sau `/build` cho một integration c
 
 | Command | Reads | Writes |
 | --- | --- | --- |
-| `/review-everything` | `prd.md`, `domain.md`, `sad.md`, *(source code)* | `specs/integrations/{NNN}-{slug}/review-findings.md` *(qua /spec-new)* |
+| `/review-everything` | `prd.md`, `domain.md`, `sad.md`, *(source code)* | `.specs/integrations/{NNN}-{slug}/review-findings.md` *(qua /spec-new)* |
 
 ### `/review-everything`
 
@@ -450,7 +454,7 @@ Review codebase ở project level theo năm trục của `code-review-and-qualit
 
 Nếu user chọn fix → gom selected findings thành raw requirement, invoke `/spec-new` với ARGUMENT đó. Integration được tạo và xử lý như integration thường (`/spec-tech` → `/plan` → `/build`).
 
-`review-findings.md` (full snapshot, gồm cả deferred) được ghi vào `specs/integrations/{NNN}-{slug}/` để traceability.
+`review-findings.md` (full snapshot, gồm cả deferred) được ghi vào `.specs/integrations/{NNN}-{slug}/` để traceability.
 
 **Khi dùng:**
 
@@ -571,7 +575,7 @@ Tạo hoặc cập nhật `.claude/ado.yaml` — file config ADO dùng chung cho
 
 **Bước 1 — Current user:** Đọc `git config user.email`, tìm trong `team.*` của `ado.yaml`. Nếu không khớp → hỏi user chọn. Resolve email → ADO identity ID để dùng làm assignee.
 
-**Bước 2 — Chọn integration:** List tất cả `specs/integrations/` kèm title và status từ frontmatter `spec.md`.
+**Bước 2 — Chọn integration:** List tất cả `.specs/integrations/` kèm title và status từ frontmatter `spec.md`.
 
 **Bước 3 — Parse spec.md:** Extract Features (`### Feature: <name> (<ID>)`) và User Stories (`#### US-FXXX-YYY — <title>`). Detect ticket đã tồn tại qua dòng `**ADO:**` ngay sau heading — đánh dấu `already_created`, bỏ qua khi tạo.
 
@@ -599,7 +603,7 @@ Cập nhật state đồng loạt cho User Story (và tuỳ chọn Feature) tick
 
 **Bước 1 — Load config:** Đọc `ado.yaml`. Dừng nếu thiếu file hoặc `environments` rỗng.
 
-**Bước 2 — Chọn integration:** List `specs/integrations/` kèm title và status.
+**Bước 2 — Chọn integration:** List `.specs/integrations/` kèm title và status.
 
 **Bước 3 — Parse & validate:** Extract tất cả Feature và User Story tickets từ dòng `**ADO:**` trong `spec.md`. Nếu bất kỳ ticket nào chưa có → dừng, báo danh sách thiếu, yêu cầu chạy `/ado-create` trước.
 

package/templates/main/domain-template.md

@@ -6,15 +6,17 @@ owner: "{BA/Domain Expert}"
 referenced_by:
   - conventions.md > 3. Main Artifacts > 3.1 Product level > domain.md > Cấu trúc
   - skills/spec-prd/SKILL.md > Process > Bước 5: Save (scaffold domain.md skeleton)
+  - skills/spec-frd/SKILL.md > Process > Bước 4b (cascade glossary + entity definition — WHAT)
+  - skills/spec-sad/SKILL.md > Process > Phần 1.6 (gán Owner cho shared entity — HOW)
   - skills/spec-new/SKILL.md > Process > Cascade Proposals > domain.md
   - skills/spec-tech/SKILL.md > Process > Cascade Proposals > domain.md
 ---
 
 # Domain
 
-> File này mỏng — chỉ chứa **shared vocabulary** và **shared entities** (entities được dùng bởi 2+ component).
+> File này mỏng — chỉ chứa **shared vocabulary** và **shared entities** (entity ở mức vocabulary nghiệp vụ chung, dự kiến dùng bởi 2+ component; việc dùng-bởi-2+ và `Owner` được xác nhận ở pha thiết kế).
 >
-> Business rules, domain events, internal entities thuộc về component sở hữu — xem `specs/main/component/{C-XXX}-{component-name}/crd.md`.
+> Business rules, domain events, internal entities thuộc về component sở hữu — xem `.specs/main/component/{C-XXX}-{component-name}/crd.md`.
 
 ## Glossary
 
@@ -26,13 +28,17 @@ referenced_by:
 
 ## Shared Entities
 
-Chỉ liệt kê entity được dùng bởi **2 hoặc nhiều component**. Entity nội bộ một component không vào đây — chúng nằm trong `crd.md` của component đó.
+Entity ở mức vocabulary nghiệp vụ chung. Hai phần thông tin tới từ hai pha (xem two-phase cascade, `conventions.md` §5.5):
+- **Định nghĩa** (tên, attributes, state machine) — *mô tả hệ thống* (WHAT): seed bởi `/spec-prd`/`/spec-frd`/`/spec-new`.
+- **`Owner` / `Used by`** — *thiết kế hệ thống* (HOW): gán bởi `/spec-sad` (hoặc `/spec-new` khi carve component). Khi entity vừa được seed mà component chưa carve → để `Owner: TBD`.
+
+Entity rõ ràng nội bộ một component (không phải vocabulary chung) không vào đây — chúng nằm trong `crd.md` của component đó.
 
 ### {Entity Name}
 
-**Owner:** `{C-XXX}-{component-name}` *(component sở hữu canonical definition)*
+**Owner:** `{C-XXX}-{component-name}` *(component sở hữu canonical definition; `TBD` nếu chưa carve — `/spec-sad` điền)*
 
-**Used by:** `{C-XXX}`, `{C-YYY}` *(các component reference entity này)*
+**Used by:** `{C-XXX}`, `{C-YYY}` *(các component reference entity này; `TBD` cho tới khi gán Owner)*
 
 {Mô tả entity này đại diện cho cái gì trong business context.}
 

package/templates/main/feature/frd-template.md

@@ -149,7 +149,7 @@ Sub-rule phức tạp (vd: password complexity với nhiều điều kiện) →
 
 ### Components Used
 
-Tham chiếu đến `specs/main/component/{C-XXX}-...`.
+Tham chiếu đến `.specs/main/component/{C-XXX}-...`.
 
 | Component | Vai trò trong feature |
 | --- | --- |

package/templates/main/prd-template.md

@@ -56,7 +56,7 @@ Section này **chỉ liệt kê component có boundary _Given_** — tức bound
 - `/spec-sad` — architect lock component boundaries dựa trên full feature index + NFRs
 - `/spec-new F-XXX` cascade — khi analyze 1 feature, discover component mới nếu cần và register vào đây qua Change History
 
-Chi tiết về vai trò và thiết kế nằm trong `specs/main/component/{C-XXX}-{component-name}/`.
+Chi tiết về vai trò và thiết kế nằm trong `.specs/main/component/{C-XXX}-{component-name}/`.
 
 | ID | Component | Mô tả ngắn | Status |
 | --- | --- | --- | --- |

package/templates/main/sad-template.md

@@ -75,6 +75,14 @@ Các nguyên tắc sau là bất biến. Agent phải kiểm tra compliance trư
 - GUARD-002: {nguyên tắc — ví dụ: Mọi external API call phải có retry + timeout}
 - GUARD-003: {nguyên tắc — ví dụ: Không để business logic trong API layer}
 
+## ADR Log
+
+Architecture Decision Records — ghi lại các quyết định kiến trúc quan trọng cùng bối cảnh và hệ quả. Nắm *tại sao* chọn (điều mà Guardrails và Tech Stack không giải thích), giúp người sau hiểu trade-off thay vì đoán lại. Mỗi quyết định lớn (chọn style, tech chính, đánh đổi đáng kể) nên có một entry.
+
+| ID | Decision | Status | Context & Rationale | Consequences |
+| --- | --- | --- | --- | --- |
+| ADR-001 | {quyết định ngắn gọn} | proposed / accepted / deprecated / superseded | {bối cảnh + lý do chọn, các option đã cân nhắc} | {hệ quả, đánh đổi phải chấp nhận} |
+
 ## Change History
 
 Append-only log của các thay đổi cascade lên artifact này. Quy ước xem `conventions.md` §5.5.