spec-lite 1.1.14 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-lite",
-  "version": "1.1.14",
+  "version": "1.2.0",
   "description": "Spec-driven development kit for Claude Code",
   "type": "module",
   "bin": {

package/skills/spec-new/SKILL.md

@@ -160,9 +160,7 @@ Output path: `specs/integrations/{NNN}-{slug}/spec.md`
 
 ### Bước 5: Write — sinh draft
 
-Tổng hợp và viết draft `spec.md`:
-
-**Cấu trúc file**: dùng `.claude/templates/integrations/spec-template.md` làm skeleton, điền nội dung từ interview vào.
+Tổng hợp và viết draft `spec.md`. **spec.md = changeset patch** áp lên main artifacts. Cấu trúc theo `templates/integrations/spec-template.md`: Context, Problem Statement, **Changes** (per-artifact blocks), Out of Scope, Open Questions, Cascade Summary.
 
 **ADO references từ prd.md:** Với mỗi Feature heading (`### Feature: <name> (<ID>)`) trong spec.md, nếu feature đó đã có ADO ticket trong `prd.md` → thêm ngay dòng `**ADO:**` bên dưới heading:
 
@@ -173,62 +171,51 @@ Tổng hợp và viết draft `spec.md`:
 
 Điều này đảm bảo `/ado-create` nhận biết feature đã có ticket và không tạo duplicate.
 
-**Cascade Proposals** — agent đề xuất delta cho main artifacts theo các targets sau (chỉ điền nếu thực sự có thay đổi, không thì ghi "Không có thay đổi đề xuất."):
-
-### prd.md
+#### Sinh `## Changes` section
 
-Đề xuất cập nhật nếu integration này:
-- Giới thiệu feature mới chưa có trong Feature Index → đề xuất thêm row vào Features (auto-pick `F-XXX` next ID, slug từ context)
-- Giới thiệu component mới chưa có trong Component Index → đề xuất thêm row vào Components (auto-pick `C-XXX` next ID)
-- Đổi status feature từ `TODO` sang `In Progress`
-- Có scope hoặc NFR thay đổi
+Với mỗi main artifact bị touched (frd, crd, prd, domain, sad), tạo 1 block. Bỏ block nếu artifact không bị thay đổi.
 
-### domain.md
+**Xác định operation:**
+- `create` — artifact chưa tồn tại
+- `update` — artifact đã tồn tại
 
-Đề xuất cập nhật nếu integration này:
-- Giới thiệu glossary term mới → đề xuất thêm vào Glossary
-- Giới thiệu shared entity mới (entity sẽ được dùng bởi 2+ component) → đề xuất thêm vào Shared Entities với field `Owner: C-XXX`
+**Diff against current state:**
 
-### component/{C-XXX}-{component-name}/crd.md
+Context đã load artifact hiện tại ở Bước 2. Agent so sánh nội dung mới với current state để gán marker per item:
 
-Liệt kê **tất cả** components bị touched trong integration và đánh giá từng cái:
+| Marker | Khi nào dùng |
+| --- | --- |
+| `[NEW]` | Item chưa có trong artifact hiện tại |
+| `[MODIFY {field}]` | Item đã có, đang đổi field cụ thể. Ghi rõ field nào: `[MODIFY priority]`, `[MODIFY rule]`, `[MODIFY status]` |
+| `[REMOVE]` | Item đã có, sẽ bị xóa khỏi artifact |
 
-| Component | crd.md | Đề xuất |
-| --- | --- | --- |
-| C-001 — auth | tồn tại | **Cập nhật** — thêm responsibility "rate limiting", thêm endpoint `POST /auth/rate-check` |
-| C-003 — payment | chưa có | **Tạo mới** crd + cdd |
+Operation=create → không cần marker, mọi item implicit là [NEW].
 
-Với từng component có đề xuất:
+**ID assignment:**
 
-**Tạo mới** `specs/main/component/{C-XXX}-{component-slug}/crd.md` *(và `cdd.md` cascade ở spec-tech)*
-- Dùng khi integration này là lần đầu tiên giới thiệu component này
-- Auto-pick C-XXX (next available) và slug kebab-case từ context
-- Đề xuất nội dung crd: Role, Responsibilities, Owned Entities, Public Interface, Business Rules, Dependencies — dựa trên spec.md
+Đọc artifact hiện tại để lấy `max(seq)` cho mỗi loại ID:
+- `US-F{NNN}-{seq}`, `AC-F{NNN}-{seq}`, `VR-F{NNN}-{seq}` trong frd.md
+- `AC-C{NNN}-{seq}` trong crd.md
 
-**Cập nhật** `specs/main/component/{C-XXX}-{component-slug}/crd.md`
-- Dùng khi crd.md đã tồn tại và integration bổ sung thêm responsibility, interface, hoặc business rule
-- Ghi rõ section nào bị touched và delta cụ thể
+ID mới = `max(seq) + 1`, format 3 chữ số. ID **stable** — không tái sử dụng khi [REMOVE], không renumber khi [MODIFY]. Khi tạo mới artifact (operation=create), bắt đầu từ `001`.
 
-### feature/{F-XXX}-{feature-name}/frd.md
+**Format reference:** Mỗi Changes block dùng đúng format của template gốc:
+- `feature/{F-XXX}/frd.md` → [frd-template.md](../../templates/main/feature/frd-template.md)
+- `component/{C-XXX}/crd.md` → [crd-template.md](../../templates/main/component/crd-template.md)
+- `prd.md` → [prd-template.md](../../templates/main/prd-template.md)
+- `domain.md` → [domain-template.md](../../templates/main/domain-template.md)
+- `sad.md` → [sad-template.md](../../templates/main/sad-template.md)
 
-Liệt kê **tất cả** features liên quan đến integration và đánh giá từng cái:
+Template gốc là single source of truth cho format. KHÔNG duplicate skeleton vào spec.md.
 
-| Feature | Status | frd.md | Đề xuất |
-| --- | --- | --- | --- |
-| F-001 — Authentication | In Progress | tồn tại | **Cập nhật** — bổ sung US-003, AC mới về rate limiting |
-| F-002 — User Profile | TODO | chưa có | **Tạo mới** |
+#### Per-artifact guidance
 
-Với từng feature có đề xuất thay đổi:
+**`feature/{F-XXX}-{feature-slug}/frd.md`**
 
-**Tạo mới** `specs/main/feature/{F-XXX}-{feature-slug}/frd.md`
-- Dùng khi integration này là lần đầu tiên implement feature này
-- Thư mục đặt tên: `{F-XXX}-{feature-slug}` (ví dụ: `F-001-authentication`)
-- Nội dung đề xuất: User Flows, Feature-level AC, User Stories, **Verification Rules**, Scope, Components consumed (reference C-XXX) — từ spec.md
-- **Verification Rules**: xem hướng dẫn ở mục "Verification Rules — quy ước sinh" bên dưới
+Liệt kê **tất cả** features liên quan đến integration và đánh giá từng cái. Không được bỏ qua feature nào — kể cả feature `Done` vẫn phải đánh giá xem spec mới có làm thay đổi scope không.
 
-**Cập nhật** `specs/main/feature/{F-XXX}-{feature-slug}/frd.md`
-- Dùng khi frd.md đã tồn tại và integration này bổ sung thêm stories hoặc criteria
-- Đọc file frd.md hiện tại, liệt kê các sections và hỏi user muốn update section nào:
+- Operation=create khi frd.md chưa tồn tại → nội dung đầy đủ tất cả 7 sections: Overview, User Flows, Feature-level AC, User Stories, Verification Rules, Scope, Dependencies.
+- Operation=update khi frd.md đã tồn tại → hỏi user chọn section cần update:
 
 ```
 frd.md — F-001 Authentication đã tồn tại.
@@ -246,10 +233,40 @@ Sections hiện có:
 Chọn section cần cập nhật (có thể chọn nhiều, ví dụ: 2 3):
 ```
 
-Sau khi user chọn → chỉ sinh nội dung cho section đó. Nếu chọn `A` → sinh lại toàn bộ frd.md như tạo mới.
+Chỉ sinh nội dung cho section đã chọn. Nếu chọn `A` → operation=update với toàn bộ 7 sections.
 
-Không được bỏ qua feature nào — kể cả feature `Done` vẫn phải đánh giá xem spec mới có làm thay đổi scope không.
-```
+**Verification Rules** trong frd.md changes block: xem mục "Verification Rules — quy ước sinh" bên dưới.
+
+**`component/{C-XXX}-{component-slug}/crd.md`**
+
+Liệt kê **tất cả** components bị touched.
+
+- Operation=create khi crd.md chưa tồn tại → auto-pick `C-XXX` next available + slug kebab-case, nội dung đầy đủ: Role, Responsibilities, Owned Entities, Public Interface, Business Rules, Dependencies.
+- Operation=update khi crd.md đã tồn tại → chỉ section bị ảnh hưởng, có markers.
+
+Component-level AC dùng ID `AC-C{NNN}-{seq}`, gắn vào responsibility/interface/rule liên quan.
+
+**`prd.md`**
+
+Tạo block nếu integration:
+- Giới thiệu feature mới chưa có trong Feature Index → row [NEW] (auto-pick `F-XXX` next available)
+- Giới thiệu component mới chưa có trong Component Index → row [NEW] (auto-pick `C-XXX` next available)
+- Đổi status feature → row [MODIFY status]: `TODO → In Progress`
+- Có scope hoặc NFR thay đổi
+
+**`domain.md`**
+
+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`
+- Sửa định nghĩa entity hiện có → entity [MODIFY ...]
+
+**`sad.md`**
+
+Hiếm khi thay đổi per integration. Tạo block chỉ khi:
+- Có cross-cutting concern mới
+- Có guardrail mới
+- Có thay đổi tech stack
 
 #### Verification Rules — quy ước sinh
 
@@ -302,39 +319,68 @@ Không được bỏ qua feature nào — kể cả feature `Done` vẫn phải
 - ❌ Đưa regex, validator code, hoặc error message vào bảng (regex/validator là HOW thuộc `fdd.md`; error/hint message là UI copy ở artifact khác).
 - ❌ Dùng tech type (`varchar(255)`, `int32`...) — phải dùng semantic type (`string`, `integer`, `email`, `enum<...>`...).
 
-Hiển thị draft cho user xem — **chưa ghi file**.
+Cuối Bước 5: tổng hợp **Cascade Summary** table — mỗi row 1 artifact với operation + summary ngắn (vd `+1 US, +2 VR, modify VR-F001-003`). Hiển thị **toàn bộ draft** (Context, Problem, Changes, Out of Scope, Open Questions, Cascade Summary) cho user xem — **chưa ghi file, chưa cascade**.
 
 ---
 
 ### Bước 6: Review — xác nhận với user
 
 > Draft trên đã đúng chưa?
+> - Mỗi Changes block (frd / crd / prd / domain / sad) có đúng operation và markers chưa?
 > - Acceptance Criteria có đủ và đo được không?
-> - Cascade Proposals (nếu có) — cần approve trước khi tiến hành.
+> - Verification Rules đã confirm với BA chưa?
+> - Cascade Summary có khớp với Changes blocks không?
+>
+> **Sau khi confirm, agent sẽ auto-apply tất cả Changes blocks lên main artifacts.**
 
-Chỉ ghi file sau khi user confirm. Nếu user yêu cầu chỉnh sửa → cập nhật draft → hỏi lại.
+Chỉ tiến hành Bước 7 sau khi user confirm. Nếu user yêu cầu chỉnh sửa → cập nhật draft → hỏi lại.
 
 ---
 
-### Bước 7: Save
+### Bước 7: Save + Auto-cascade
 
 Tạo thư mục `specs/integrations/{NNN}-{slug}/` nếu chưa có.
 
-Ghi nội dung đã confirm vào `specs/integrations/{NNN}-{slug}/spec.md`. Frontmatter `features` và `components` phải được điền theo những gì đã nhận diện ở Bước 2.
+**[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.
+
+**[7.2] Auto-apply mỗi Changes block** vào main artifact tương ứng. Thứ tự apply (để tránh forward reference): `prd.md` → `domain.md` → `sad.md` → `component/*/crd.md` → `feature/*/frd.md`.
+
+Cho từng block:
+
+- **Operation=create:**
+  - Tạo file mới tại path tương ứng
+  - Nội dung = nội dung của Changes block (theo format của template gốc)
+  - Frontmatter của artifact mới: lấy từ template (status `draft` cho artifact mới — separate lifecycle với spec.md)
+
+- **Operation=update:**
+  - Đọc artifact hiện tại
+  - Với mỗi item trong Changes block:
+    - `[NEW]` → append/insert vào section tương ứng (giữ thứ tự numeric của ID)
+    - `[MODIFY {field}]` → tìm item bằng ID, update field đã chỉ định, giữ nguyên các field khác
+    - `[REMOVE]` → xóa item khỏi artifact (ID không tái sử dụng — không renumber các ID khác)
+  - Ghi lại artifact
 
-Nếu integration này gắn với feature từ prd.md, cập nhật `specs/main/prd.md`: đổi Status của feature từ `TODO` → `In Progress`.
+**[7.3] Side-effects bổ sung:**
+
+- Nếu integration gắn với feature từ prd.md và prd.md Changes block không tự đổi status → tự động đổi `TODO` → `In Progress` cho feature đó trong prd.md.
+
+**[7.4] Thông báo kết quả:**
 
-Thông báo kết quả:
 ```
-✓ specs/integrations/{NNN}-{slug}/spec.md đã được tạo (status: draft)
-{nếu có} ✓ prd.md — F-XXX status cập nhật: TODO → In Progress
+✓ specs/integrations/{NNN}-{slug}/spec.md đã được tạo (status: approved)
+
+Auto-cascade applied:
+  ✓ prd.md — {summary}
+  ✓ domain.md — {summary}
+  ✓ component/C-XXX-{slug}/crd.md — {created | updated: summary}
+  ✓ feature/F-XXX-{slug}/frd.md — {created | updated: summary}
 
 Bước tiếp theo:
-  - Review spec.md và apply Cascade Proposals (nếu có) vào main artifacts thủ công
-  - Approve spec.md (đổi status: draft → approved)
   - /spec-tech → thiết kế technical design dựa trên spec.md này
 ```
 
+**Nếu apply fail** (ví dụ markers reference ID không tồn tại trong artifact hiện tại) → dừng, báo lỗi cụ thể, **không** ghi spec.md. Yêu cầu user fix draft hoặc check artifact hiện tại.
+
 ---
 
 ## Common Rationalizations
@@ -343,21 +389,30 @@ Bước tiếp theo:
 | --- | --- |
 | "Requirement rõ rồi, bỏ qua spec.md" | Acceptance Criteria chưa viết = không biết khi nào là done. Code xong vẫn có thể sai. |
 | "Out of scope thì ai cũng hiểu rồi" | Không ghi = scope creep không kiểm soát được. DEV sẽ tự quyết định implement hay không. |
-| "Cascade Proposals thì sau cập nhật cũng được" | Domain là shared context. Cập nhật trễ = các spec sau dùng context sai. |
+| "Skip Changes blocks, sửa main artifacts tay sau" | Mất single source of truth. spec.md là PR record — phải reflect đúng patch đã apply. |
 
 ## Red Flags
 
 - Acceptance Criteria dùng từ không đo được: "hoạt động đúng", "hiển thị đẹp", "nhanh"
 - Out of Scope trống — mọi integration đều có thứ liên quan nhưng không làm
 - Open Questions để trống nhưng vẫn còn điểm mơ hồ trong requirements
-- Cascade Proposals không được review trước khi approve
+- Changes blocks không được review trước khi confirm (cascade là irreversible — không có undo)
+- Marker không khớp current state: `[NEW]` cho item đã tồn tại, hoặc `[MODIFY]/[REMOVE]` cho ID không có
 
 ## Verification
 
-Trước khi ghi file, kiểm tra:
+Trước khi user confirm (Bước 6), kiểm tra:
 
 - [ ] Problem Statement từ góc nhìn user/business, không mention tech
 - [ ] Mỗi Acceptance Criterion dùng cú pháp GIVEN / WHEN / THEN, có thể test được
 - [ ] Out of Scope có ít nhất 1 item
-- [ ] Cascade Proposals đã được user review
-- [ ] User đã confirm draft trước khi ghi file
+- [ ] Mỗi Changes block có Operation rõ ràng (create | update)
+- [ ] Mỗi item trong update block có marker đúng ([NEW]/[MODIFY {field}]/[REMOVE])
+- [ ] ID assignment dựa trên max(seq)+1 đọc từ artifact hiện tại, không tái sử dụng
+- [ ] Verification Rules đã confirm với BA (không tự assert)
+- [ ] Cascade Summary table khớp với các Changes blocks
+
+Sau khi user confirm (Bước 7):
+
+- [ ] Auto-apply chạy theo thứ tự prd → domain → sad → crd → frd
+- [ ] Fail-safe: nếu apply fail thì không ghi spec.md

package/templates/integrations/spec-template.md

@@ -13,84 +13,140 @@ referenced_by:
 
 ## Context
 
-<!-- Tóm tắt ngắn các thông tin quan trọng từ context đã load (prd.md, domain.md, frd.md, crd.md), để file self-contained -->
+<!-- Tóm tắt thông tin quan trọng từ context đã load (prd.md, domain.md, frd.md, crd.md), để file self-contained -->
 
 ## Problem Statement
 
 <!-- Vấn đề cần giải quyết là gì, tại sao cần giải quyết -->
 
-## Acceptance Criteria
+## Changes
 
 <!--
-Agent tự chọn cách tổ chức phù hợp với bản chất integration. Có thể mix nếu integration vừa thêm feature, vừa thay đổi component.
+spec.md = changeset patch áp lên main artifacts. Mỗi block dưới đây tương ứng 1 main artifact bị thay đổi.
+Bỏ block nếu artifact không bị thay đổi. Lặp block cho mỗi feature/component bị touched.
 
-AC ID format:
-- AC liên quan feature: `AC-{F_ID}-{seq}` — feature-scoped, cascade vào frd.md
-- AC liên quan component: `AC-{C_ID}-{seq}` — component-scoped, cascade vào responsibilities/interface/rules của crd.md
+**Operation:**
+- `create` — artifact chưa tồn tại. Liệt kê đầy đủ tất cả sections theo template gốc, mọi item implicit [NEW] (không cần marker).
+- `update` — artifact đã tồn tại. Chỉ liệt kê sections bị ảnh hưởng. Mỗi item có marker:
+  - `[NEW]` — item chưa có trong artifact hiện tại
+  - `[MODIFY {field}]` — item đã có, đang đổi field cụ thể (ví dụ `[MODIFY priority]`, `[MODIFY rule]`)
+  - `[REMOVE]` — item đã có, sẽ bị xóa khỏi artifact
 
-Format Given/When/Then. Bỏ block không dùng.
+**Format reference:** dùng đúng format của template gốc — KHÔNG duplicate skeleton ở đây. Template gốc là single source of truth cho format.
+
+**ID assignment:** agent đọc artifact hiện tại để xác định next ID:
+- `US-F{NNN}-{seq}`, `AC-F{NNN}-{seq}`, `VR-F{NNN}-{seq}` cho frd.md
+- `AC-C{NNN}-{seq}` cho crd.md
+- ID stable — không tái sử dụng khi xóa, không renumber.
+
+**Auto-cascade:** sau khi human approve spec.md, agent tự apply tất cả Changes blocks vào main artifacts. spec.md được archive như PR record.
 -->
 
-### Feature: {feature-name} *(bỏ nếu integration không touch feature; lặp lại block cho mỗi feature)*
+### feature/{F-XXX}-{feature-slug}/frd.md *(lặp block cho mỗi feature; bỏ nếu không touch feature)*
 
-**Feature-level AC:**
+**Operation:** create | update
+**Format reference:** [frd-template.md](../../templates/main/feature/frd-template.md)
 
-- [ ] `AC-{F_ID}-{seq}`
-  - **Given** {precondition}
-  - **When** {action}
-  - **Then** {expected outcome}
+<!--
+operation=create → nội dung đầy đủ theo frd-template.md (Overview, User Flows, Feature-level AC, User Stories, Verification Rules, Scope, Dependencies).
+operation=update → chỉ liệt kê section bị ảnh hưởng, mỗi item có marker.
 
-#### US-{F_ID}-{seq}: {Story title}
+Ví dụ operation=update:
 
-**{Persona}** muốn **{hành động}** để **{mục tiêu}**.
+#### User Stories
 
-**Priority:** Must / Should / Could
+##### US-F001-005 [NEW]: {Story title}
+**{Persona}** muốn **{action}** để **{goal}**.
+**Priority:** Must
+**Acceptance Criteria:**
+- `AC-F001-012` [NEW]
+  - **Given** ...
+  - **When** ...
+  - **Then** ...
 
-**Story AC:**
+##### US-F001-002 [MODIFY priority]
+- Priority: Should → Must
 
-- [ ] `AC-{F_ID}-{seq}`
-  - **Given** {precondition}
-  - **When** {action}
-  - **Then** {expected outcome}
+##### US-F001-004 [REMOVE]
+- Lý do: superseded by US-F001-005
 
-### Component: `{C-XXX}-{component-name}` *(bỏ nếu integration không touch component; lặp lại block cho mỗi component)*
+#### Verification Rules
 
-**AC theo responsibility / interface / rule:**
+| ID | Field | Type | Required | Rule | Refs | Op |
+| --- | --- | --- | --- | --- | --- | --- |
+| `VR-F001-008` | email | email | yes | must be unique | US-F001-005 | NEW |
+| `VR-F001-003` | password | string | yes | min length 12 (was 8) | US-F001-001 | MODIFY rule |
+-->
 
-- [ ] `AC-{C_ID}-{seq}` — {responsibility / interface / rule mô tả}
-  - **Given** {precondition}
-  - **When** {action}
-  - **Then** {expected outcome}
+### component/{C-XXX}-{component-slug}/crd.md *(lặp block cho mỗi component; bỏ nếu không touch component)*
 
-## Out of Scope
+**Operation:** create | update
+**Format reference:** [crd-template.md](../../templates/main/component/crd-template.md)
 
-<!-- Những gì KHÔNG thuộc phạm vi của integration này -->
+<!--
+operation=create → nội dung đầy đủ theo crd-template.md (Role, Responsibilities, Owned Entities, Public Interface, Business Rules, Dependencies).
+operation=update → chỉ liệt kê section bị ảnh hưởng, mỗi item có marker (xem ví dụ ở block frd.md).
 
-## Open Questions
+Component-level AC dùng ID `AC-C{NNN}-{seq}`, gắn vào responsibility/interface/rule liên quan.
+-->
 
-<!-- Các điểm còn mơ hồ cần clarify trước khi proceed. Xóa section nếu không có. -->
+### prd.md *(bỏ nếu không có thay đổi)*
 
-## Cascade Proposals
+**Operation:** update
+**Format reference:** [prd-template.md](../../templates/main/prd-template.md)
 
-<!-- Agent điền vào nếu phát hiện main artifacts cần cập nhật -->
-<!-- Human review section này TRƯỚC khi approve spec.md -->
+<!--
+Thường là update — thêm row vào Feature Index / Component Index, đổi status feature, thêm NFR, thêm business constraint, thêm glossary reference.
+Mỗi delta dùng marker, ví dụ:
 
-### prd.md
+#### Features (Feature Index)
+- Row [NEW]: `F-007 — Refund | Cho phép user refund order | Medium | TODO`
+- Row [MODIFY status]: `F-001` TODO → In Progress
 
-Không có thay đổi đề xuất.
+#### Components (Component Index)
+- Row [NEW]: `C-005 — refund-processor | Xử lý refund workflow | TODO`
+-->
 
-### domain.md
+### domain.md *(bỏ nếu không có thay đổi)*
 
-Không có thay đổi đề xuất.
+**Operation:** update
+**Format reference:** [domain-template.md](../../templates/main/domain-template.md)
 
-### component/{C-XXX}-{component-name}/crd.md
+<!--
+Thường là update — thêm glossary term, thêm shared entity, sửa entity definition.
 
-<!-- Lặp lại section này cho mỗi component liên quan đến spec. Bỏ nếu integration không touch component nào. -->
+#### Glossary
+- Row [NEW]: `Refund — số tiền hoàn lại cho user sau khi order bị hủy`
 
-Không có thay đổi đề xuất.
+#### Shared Entities
+- Entity [NEW]: `Refund (Owner: C-005-refund-processor)` — { fields, relationships }
+-->
+
+### sad.md *(bỏ nếu không có thay đổi)*
+
+**Operation:** update
+**Format reference:** [sad-template.md](../../templates/main/sad-template.md)
+
+<!--
+Thường là update — thêm tech stack item, thêm cross-cutting concern, thêm guardrail. Hiếm khi thay đổi per integration.
+-->
+
+## Out of Scope
+
+<!-- Những gì KHÔNG thuộc phạm vi của integration này -->
+
+## Open Questions
+
+<!-- Các điểm còn mơ hồ cần clarify trước khi proceed. Xóa section nếu không có. -->
 
-### feature/{F-XXX}-{feature-name}/frd.md
+## Cascade Summary
 
-<!-- Lặp lại section này cho mỗi feature liên quan đến spec. Bỏ nếu integration không gắn với feature nào. -->
+<!-- Bảng tóm tắt để reviewer scan nhanh trước khi approve. Auto-generated từ các Changes blocks ở trên. -->
 
-Không có thay đổi đề xuất.
+| Artifact | Operation | Summary |
+| --- | --- | --- |
+| `feature/F-XXX-{slug}/frd.md` | create / update | {ngắn: +N US, +M VR, modify AC-X} |
+| `component/C-XXX-{slug}/crd.md` | create / update | {ngắn} |
+| `prd.md` | update | {ngắn} |
+| `domain.md` | update | {ngắn} |
+| `sad.md` | update / no-op | {ngắn} |

package/templates/main/component/crd-template.md

@@ -6,9 +6,16 @@ owner: "{BA / Tech Lead}"
 component_id: "{Component ID từ PRD Component Index, ví dụ C-001}"
 referenced_by:
   - conventions.md > 3. Main Artifacts > 3.2 Component level > crd.md > Cấu trúc
-  - skills/spec-new/SKILL.md > Process > Cascade Proposals > component crd.md
+  - skills/spec-new/SKILL.md > Process > Bước 5: Write — sinh draft > component/{C-XXX}/crd.md
+  - templates/integrations/spec-template.md > Changes > component/{C-XXX}/crd.md
 ---
 
+<!--
+Canonical format cho component/{C-XXX}-{slug}/crd.md.
+spec.md và tech.md REFERENCE template này khi sinh Changes block — KHÔNG duplicate skeleton.
+Mọi thay đổi structure ở file này tự động propagate qua Changes blocks vì chúng dùng đây làm format gốc.
+-->
+
 # Component: {Component Name}
 
 ## Role

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

@@ -6,9 +6,16 @@ owner: "{BA}"
 feature_id: "{Feature ID từ PRD Feature Index}"
 referenced_by:
   - conventions.md > 3. Main Artifacts > 3.3 Feature level > frd.md > Cấu trúc
-  - skills/spec-new/SKILL.md > Process > Bước 5: Write — sinh draft > Cascade Proposals > frd.md
+  - skills/spec-new/SKILL.md > Process > Bước 5: Write — sinh draft > feature/{F-XXX}/frd.md
+  - templates/integrations/spec-template.md > Changes > feature/{F-XXX}/frd.md
 ---
 
+<!--
+Canonical format cho feature/{F-XXX}-{slug}/frd.md.
+spec.md và tech.md REFERENCE template này khi sinh Changes block — KHÔNG duplicate skeleton.
+Mọi thay đổi structure ở file này tự động propagate qua Changes blocks vì chúng dùng đây làm format gốc.
+-->
+
 # Feature: {Feature Name}
 
 ## Overview