spec-lite 1.3.2 → 1.4.0

package/README.md

@@ -51,6 +51,9 @@ Scan codebase để extract main artifacts, sau đó vào Integration Pipeline.
 /spec-brownfield-feature
          │
          ▼
+/spec-tsd [F-XXX]   (tùy chọn — bootstrap tsd.md cho từng feature)
+         │
+         ▼
 (fill in NEEDS_CLARIFY khi có thêm context)
          │
          ▼
@@ -66,6 +69,9 @@ Scan module dirs, tạo `crd.md` + `cdd.md` cho từng component, điền Compon
 #### `/spec-brownfield-feature [path]`
 Scan routes/use cases/tests, tạo `frd.md` + `fdd.md` cho từng feature, điền Feature Index vào `prd.md`. Yêu cầu `component` đã chạy (fdd.md cần C-XXX IDs từ Component Index).
 
+#### `/spec-tsd [F-XXX]`
+Bootstrap `feature/{F-XXX}/tsd.md` (Test Spec Document) trực tiếp từ `frd.md` — mechanical derive Test Scenarios + Test Cases (mỗi Flow → TS, mỗi US/AC → Functional TC, mỗi VR → ≥1 positive + 1+ negative, mỗi FAC → Feature AC TC). Không interview, không cần integration. Dùng sau `/spec-brownfield-feature` để có test coverage tracking từ ngày 1, hoặc khi tsd drift khỏi frd cần regenerate fresh.
+
 > **NEEDS_CLARIFY:** Các mục chưa rõ khi scan được đánh dấu `[NEEDS_CLARIFY]` — không block workflow, fill in dần khi có thêm context.
 
 ---
@@ -78,17 +84,21 @@ Mỗi requirement mới đều đi qua pipeline này.
 /spec-new [requirement]
    (human review + apply cascade proposals + approve)
           │
-   /spec-tech
-   (human review + apply cascade proposals + approve)
-          │
-   /plan
-   (human approve)
-          │
-   /build ◄──────────────┐
-          │               │
-   /review-integration    │ (nếu Critical/Important → sửa và build lại)
-          │               │
-     [approve] ───────────┘ (nếu chỉ Suggestion hoặc không có finding)
+          ├─────────────────┐
+          ▼                 ▼
+   /spec-tech         /spec-test   (song song — cả hai chỉ phụ thuộc spec.md)
+   (DEV approve)      (QC approve, cascade lên feature/*/tsd.md)
+          │                 │
+          └────────┬────────┘
+                  ▼
+               /plan
+          (human approve)
+                  │
+           /build ◄──────────────┐
+                  │               │
+           /review-integration    │ (nếu Critical/Important → sửa và build lại)
+                  │               │
+             [approve] ───────────┘ (nếu chỉ Suggestion hoặc không có finding)
 ```
 
 #### `/spec-new [requirement]`
@@ -98,11 +108,14 @@ Tạo `specs/integrations/{slug}/spec.md` cho một integration mới.
 - Không có argument → hiển thị danh sách features TODO từ `prd.md` để chọn
 
 #### `/spec-tech [number]`
-Tạo `specs/integrations/{slug}/tech.md` sau khi `spec.md` được approve.
+Tạo `specs/integrations/{slug}/tech.md` sau khi `spec.md` được approve. Chạy bởi **DEV**.
 
 - Có argument → chọn integration theo số thứ tự luôn
 - Không có argument → hiển thị danh sách tất cả integrations
 
+#### `/spec-test [number]`
+Tạo `specs/integrations/{slug}/test.md` sau khi `spec.md` được approve. Chạy bởi **QC**, **song song / độc lập** với `/spec-tech` — cả hai chỉ phụ thuộc `spec.md`. Mechanical derive Test Scenarios + Test Cases từ frd.md (Flow → TS, US/AC → Functional TC, VR → positive + negative, FAC → Feature AC TC), priority deterministic. Cascade lên `feature/{F-XXX}/tsd.md` qua Changes blocks. Gate: integration phải có `features:` non-empty (component-thuần không áp dụng).
+
 #### `/plan`
 Tạo `plan.md` và `todo.md` từ `spec.md` + `tech.md`.
 
@@ -122,6 +135,17 @@ Sau khi có findings, hỏi user severity tier muốn xử lý (Critical / Criti
 
 ---
 
+## Maintenance — migrate artifacts khi template thay đổi
+
+Skill ad-hoc dùng khi template đã được update và artifacts hiện có cần migrate. Không phải pipeline — chạy khi cần.
+
+#### `/spec-frd-update`
+Migrate `feature/*/frd.md` hiện có sang format mới nhất của [frd-template.md](.claude/templates/main/feature/frd-template.md). Detect 8 migration vectors: fix Mermaid syntax `[{...}]` → `["..."]`, rename `Feature-level AC` → `Feature AC` với 4 nhóm chuẩn, rename `AC-F{NNN}-*` (Feature AC) → `FAC-F{NNN}-*` + cascade ID remap qua `fdd.md`/`tsd.md`/`integrations/*/{spec,tech,test}.md`, insert US/AC stability notes + Verification Rules, derive Mermaid User Flows từ User Stories, v.v.
+
+Pre-flight yêu cầu git working tree clean — rollback dùng `git checkout -- {file}`, **không** tạo file `.bak`. V4 (FAC remap), V6 (Verification Rules propose), V8 (User Flows propose) đều có confirm step trước khi ghi. No-op safe: nếu mọi FRD đã clean, skill dừng mà không ghi gì.
+
+---
+
 ## Files được tạo ra
 
 | Command | Output |
@@ -131,8 +155,11 @@ Sau khi có findings, hỏi user severity tier muốn xử lý (Critical / Criti
 | `/spec-brownfield-init` | `specs/main/prd.md`, `specs/main/domain.md`, `specs/main/sad.md` |
 | `/spec-brownfield-component` | `specs/main/component/{C-XXX}-*/crd.md + cdd.md` |
 | `/spec-brownfield-feature` | `specs/main/feature/{F-XXX}-*/frd.md + fdd.md` |
+| `/spec-tsd` | `specs/main/feature/{F-XXX}-*/tsd.md` |
+| `/spec-frd-update` | *(modify in-place `feature/*/frd.md` + cascade refs)* |
 | `/spec-new` | `specs/integrations/{slug}/spec.md` |
 | `/spec-tech` | `specs/integrations/{slug}/tech.md` |
+| `/spec-test` | `specs/integrations/{slug}/test.md`, cascade: `feature/{F-XXX}/tsd.md` |
 | `/plan` | `specs/integrations/{slug}/plan.md`, `todo.md` |
 | `/build` | *(implements tasks từ `plan.md`/`todo.md`)* |
 | `/review-integration` | *(findings report — không tạo file)* |

package/package.json

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

package/skills/plan/SKILL.md

@@ -123,7 +123,7 @@ Dùng `.claude/templates/integrations/plan-template.md` làm skeleton, điền n
 **Lưu ý format:**
 - Task ID dùng `·` (middle dot), không dùng `—`
 - `**Các bước:**` là numbered list, đủ cụ thể để agent implement không cần đoán
-- `**Verification:**` là checklist `- [ ]`, gắn AC ID khi có
+- `**Verification:**` là checklist `- [ ]` — test case hoặc observable result cụ thể
 - `**depends:**` luôn có, dùng `—` nếu không có dependency
 
 ### todo.md

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

@@ -191,7 +191,16 @@ Các entities sau được dùng bởi nhiều components.
 Apply cascade proposals vào domain.md? [y/n/edit]
 ```
 
-Nếu `y` → update `specs/main/domain.md` Shared Entities section.
+Nếu `y` → update `specs/main/domain.md` Shared Entities section, đồng thời append entry vào `## Change History` của domain.md (theo `conventions.md` §5.5):
+
+```markdown
+### {YYYY-MM-DD} — manual — update
+
+- **Shared Entities**:
+  - [NEW] Order — owner C-003-payment, used by inventory (detected từ /spec-brownfield-component scan)
+  - [NEW] User — owner C-001-auth, used by user/notification
+```
+
 Nếu `edit` → hỏi chỉnh sửa từng entity trước khi apply.
 
 ---
@@ -212,6 +221,14 @@ Ghi tất cả? [y] hoặc review từng file trước [r]:
 - `y` → ghi tất cả
 - `r` → hiển thị lần lượt từng file, user confirm / skip / edit từng cái
 
+**Change History:** Append entry vào section `## Change History` cuối mỗi `crd.md`/`cdd.md` vừa ghi (theo `conventions.md` §5.5):
+
+```markdown
+### {YYYY-MM-DD} — manual — create
+
+- **All sections**: initial brownfield scaffold qua /spec-brownfield-component (discovered từ code scan)
+```
+
 ---
 
 ### Bước 10: Điền Component Index vào prd.md + sad.md Components table
@@ -238,6 +255,18 @@ Apply? [y/n]
 
 Cột architectural notes trong sad.md nên ngắn gọn — tập trung vào boundary/deployment/key tech concern, không lặp lại business role từ prd.md.
 
+Khi apply → đồng thời append entry vào `## Change History` của prd.md và sad.md (theo `conventions.md` §5.5):
+
+```markdown
+### {YYYY-MM-DD} — manual — update
+
+- **Components**:
+  - [NEW] C-001 — auth (discovered từ /spec-brownfield-component scan)
+  - [NEW] C-002 — user
+  - [NEW] C-003 — payment
+  - [NEW] C-004 — notification
+```
+
 ---
 
 ### Bước 11: Summary

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

@@ -225,6 +225,14 @@ Sẽ tạo {N} features ({2N} files):
 Ghi tất cả? [y] hoặc review từng file trước [r]:
 ```
 
+**Change History:** Append entry vào section `## Change History` cuối mỗi `frd.md`/`fdd.md` vừa ghi (theo `conventions.md` §5.5):
+
+```markdown
+### {YYYY-MM-DD} — manual — create
+
+- **All sections**: initial brownfield scaffold qua /spec-brownfield-feature (discovered từ code scan)
+```
+
 ---
 
 ### Bước 8: Điền Feature Index vào prd.md
@@ -241,6 +249,18 @@ Sẽ điền Feature Index vào prd.md:
 Apply? [y/n]
 ```
 
+Khi apply → đồng thời append entry vào `## Change History` của prd.md (theo `conventions.md` §5.5):
+
+```markdown
+### {YYYY-MM-DD} — manual — update
+
+- **Features**:
+  - [NEW] F-001 — user-registration (discovered từ /spec-brownfield-feature scan)
+  - [NEW] F-002 — authentication
+  - [NEW] F-003 — checkout-flow
+  - [NEW] F-004 — order-history
+```
+
 ---
 
 ### Bước 9: Summary

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

@@ -272,6 +272,14 @@ Confirm? [y] Bỏ qua [n] Chỉnh sửa [e]:
 
 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:
+
+```markdown
+### {YYYY-MM-DD} — manual — create
+
+- **All sections**: initial brownfield scaffold qua /spec-brownfield-init (scan codebase + interview)
+```
+
 ```
 ✓ 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)

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

@@ -52,7 +52,7 @@ Skill detect từng frd hiện tại thuộc "era" nào và apply vectors tươn
 | **V5 US/AC stability notes** | Section User Stories thiếu chuỗi "ID stable" | Insert 2 dòng note | None |
 | **V6 VR section** | Không có heading `## Verification Rules` | Propose VR table từ User Stories → user approve → insert | Medium |
 | **V7 Components Used location** | Section `## Components Consumed` đứng riêng (era pre-84d7303) | Move xuống `## Dependencies` thành subsection `### Components Used` | Low |
-| **V8 User Flows missing** | Không có heading `## User Flows` (era pre-84d7303) | Derive Mermaid flows từ User Stories → propose → user approve → insert. 1 flow / nhóm US liên quan theo journey logic. | Medium |
+| **V8 User Flows missing** | Không có heading `## User Flows` (era pre-84d7303) | Derive Mermaid flows từ User Stories → propose → user approve → insert. 1 flow / nhóm US liên quan theo journey logic. **Bắt buộc — không có option skip; FRD migration không hoàn tất nếu thiếu User Flows.** | Medium |
 
 ---
 
@@ -260,7 +260,7 @@ Apply? (yes / edit / skip-vr)
 
 ### Bước 6: V8 — Derive User Flows section
 
-**Run nếu V8 detected.** Propose-then-approve giống V6 — model derive draft, user duyệt trước khi ghi.
+**Run nếu V8 detected. Bắt buộc — không có option skip.** Propose-then-approve giống V6 nhưng loop cho tới khi user approve: model derive draft, user duyệt (yes) hoặc trả phản hồi (edit) → model regenerate. FRD migration chỉ hoàn tất khi `## User Flows` đã insert.
 
 #### 6.1 Load minimal context
 - Section `## Overview` của FRD (framing scope + actors).
@@ -305,10 +305,11 @@ Flow 2: Login
   ...
   ```
 
-Apply? (yes / edit / skip-flows)
-  yes         → insert vào frd.md
-  edit        → user góp ý flow nào cần sửa (vd: "Flow 1 thiếu nhánh email đã tồn tại")
-  skip-flows  → giữ FRD không có User Flows section
+Apply? (yes / edit)
+  yes   → insert vào frd.md
+  edit  → user góp ý flow nào cần sửa (vd: "Flow 1 thiếu nhánh email đã tồn tại") → regenerate draft, loop lại
+
+User Flows là **bắt buộc** — không có option skip. Nếu user muốn dừng toàn bộ migration cho feature này, dùng "skip-feature" ở Bước 4 hoặc abort skill (Ctrl-C) trước khi V8 chạy.
 ```
 
 #### 6.4 Insert
@@ -326,6 +327,7 @@ Sau khi apply hết vectors cho một FRD, chạy check:
 - [ ] Story AC vẫn dùng `AC-F{NNN}-` (không bị remap nhầm)
 - [ ] Mermaid blocks không còn pattern `[{...}]`
 - [ ] Có heading `## Verification Rules` (nếu V6 applied)
+- [ ] Có heading `## User Flows` với ít nhất 1 Mermaid flowchart (bắt buộc — nếu V8 detected mà section vẫn vắng thì migration chưa hoàn tất)
 - [ ] VR Rule column không chứa keyword UI copy: "error message", "vui lòng", "hint", "tooltip"
 - [ ] Frontmatter `referenced_by` trỏ tới `3.3 Feature level` (không phải `3.2`)
 
@@ -346,6 +348,16 @@ Cho mỗi FRD đã migrate:
   Vectors applied: V5, V6 (5 VRs added)
 ```
 
+**Change History append:** Cho mỗi FRD vừa migrate (và mỗi cascade target `fdd.md`/`tsd.md` bị touched), append entry vào section `## Change History` theo `conventions.md` §5.5:
+
+```markdown
+### {YYYY-MM-DD} — manual — update
+
+- **Migration**: applied vectors V1, V3, V4 (3 IDs remapped: AC-F001-001→FAC-F001-001, ...), V5, V6 (8 VRs added), V8 (2 flows added) qua /spec-frd-update
+```
+
+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.
 
 Append vào [changelogs.md](../../changelogs.md) `## [Unreleased]`:
@@ -371,6 +383,7 @@ Append vào [changelogs.md](../../changelogs.md) `## [Unreleased]`:
 - VR Rule column chứa regex `^[a-z]+$` hoặc tech type `varchar(255)` — đó là HOW, sai vị trí.
 - V8 flows auto-apply không qua propose-then-approve → model có thể bịa glue step / sai journey grouping mà BA không kịp catch.
 - V8 flow chứa step không trace được lên US nào (model bịa) → BA reject draft và yêu cầu regenerate.
+- Để FRD không có `## User Flows` sau migration vì "draft chưa ổn" → sai. V8 bắt buộc; nếu draft chưa ổn, dùng `edit` loop cho tới khi approve. FRD không có User Flows = migration chưa hoàn tất.
 - V8 Mermaid block dùng syntax `[{...}]` thay vì `["..."]` — vi phạm V1 convention.
 - Validate fail nhưng skip rollback → file ở trạng thái nửa migrate, khó debug sau.
 - Load conventions.md hoặc source code "for safety" → contamination, tốn context, không cải thiện output.
@@ -378,7 +391,7 @@ Append vào [changelogs.md](../../changelogs.md) `## [Unreleased]`:
 ## Verification
 
 Trước khi mark feature done:
-- [ ] Tất cả vectors detected đã apply (hoặc skip có log lý do)
+- [ ] Tất cả vectors detected đã apply (hoặc skip có log lý do — riêng V8 KHÔNG được skip)
 - [ ] Validate Bước 6 pass
 - [ ] Working tree clean trước khi skill chạy (git status verified) — rollback dùng git, không có file backup
 - [ ] Cascade ID đã re-grep và confirm 0 false-positive

package/skills/spec-new/SKILL.md

@@ -360,6 +360,30 @@ Cho từng block:
     - `[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
 
+**[7.2.5] Append Change History entry** vào mỗi main artifact bị touched (theo `conventions.md` §5.5). Đây là phần atomic của auto-apply — nếu fail thì rollback luôn cả entry này.
+
+Cho mỗi artifact:
+
+1. Mở file, tìm section `## Change History` (mọi template main đã scaffold sẵn section này — nếu thiếu, append vào cuối file).
+2. Append entry mới ở cuối section, format:
+
+   ```markdown
+   ### {YYYY-MM-DD} — [{NNN}-{slug}](../../integrations/{NNN}-{slug}/spec.md) — {operation}
+
+   - **{Section name 1}**:
+     - [marker] {ID/item} — {mô tả ngắn 1 dòng}
+   - **{Section name 2}**:
+     - [marker] {ID/item} — {mô tả ngắn 1 dòng}
+   ```
+
+   - Operation = `create` nếu vừa scaffold artifact mới, `update` nếu apply Changes block lên artifact đã tồn tại.
+   - Section name = tên section trong template gốc (`User Stories`, `Verification Rules`, `Components`, `Public Interface`, ...).
+   - Mỗi item có marker trong Changes block phải xuất hiện ở entry, không gộp, không bỏ sót.
+   - Mô tả ngắn 1 dòng: đủ context để hiểu thay đổi mà không phải mở `spec.md`. Ví dụ tốt: `[NEW] US-F002-005 — Refund order story cho customer`; ví dụ xấu: `[NEW] US-F002-005`.
+   - Path link: dùng relative path từ artifact đến `integrations/{NNN}-{slug}/spec.md` (số `../` phụ thuộc depth của artifact: 2 cho prd/domain/sad, 3 cho component/feature artifacts).
+
+3. Với operation=create và artifact được seed từ template trống (không có content từ Changes block) → entry body có thể đơn giản: `- **All sections**: initial scaffold`.
+
 **[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.
@@ -415,4 +439,5 @@ Trước khi user confirm (Bước 6), kiểm tra:
 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
+- [ ] Mỗi artifact bị touched có entry mới được append vào `## Change History` (xem `conventions.md` §5.5)
+- [ ] Fail-safe: nếu apply fail thì không ghi spec.md (rollback luôn Change History entries)

package/skills/spec-prd/SKILL.md

@@ -152,6 +152,18 @@ Chỉ ghi file sau khi user confirm. Nếu user yêu cầu chỉnh sửa → c
 
 Nếu `domain.md` đã tồn tại với nội dung thực → không đụng tới.
 
+**5c. Append Change History entry** vào mỗi artifact vừa ghi/scaffold (theo `conventions.md` §5.5):
+
+```markdown
+### {YYYY-MM-DD} — manual — create
+
+- **All sections**: initial scaffold qua /spec-prd
+```
+
+- Áp dụng cho `prd.md` (mỗi lần skill chạy — nếu là lần đầu thì `create`, nếu là update thì `update` và body liệt kê section bị đổi).
+- Áp dụng cho `domain.md` chỉ khi vừa scaffold lần đầu — không đụng nếu đã tồn tại.
+- Operation `update`: liệt kê section đã thay đổi với mô tả ngắn, ví dụ `- **Features**: updated Feature Index từ interview`.
+
 Thông báo kết quả:
 ```
 ✓ specs/main/prd.md đã được cập nhật (status: draft)

package/skills/spec-sad/SKILL.md

@@ -169,6 +169,16 @@ Chỉ ghi file sau khi user confirm. Nếu user yêu cầu chỉnh sửa → c
 
 Ghi nội dung đã được confirm vào `specs/main/sad.md`.
 
+**Change History:** Append entry vào section `## Change History` cuối `sad.md` (theo `conventions.md` §5.5):
+
+```markdown
+### {YYYY-MM-DD} — manual — create
+
+- **All sections**: initial scaffold qua /spec-sad
+```
+
+Nếu chạy lần thứ N (sad.md đã có) → operation = `update`, body liệt kê section đã đổi với mô tả ngắn.
+
 Thông báo kết quả:
 ```
 ✓ specs/main/sad.md đã được cập nhật (status: draft)

package/skills/spec-tech/SKILL.md

@@ -64,12 +64,7 @@ Nếu `status` **không phải** `approved`:
 
 > ⛔ `spec.md` của integration **{slug}** chưa được approve (status hiện tại: `{status}`).
 >
-> Để tiếp tục:
-> 1. Review `specs/integrations/{slug}/spec.md`
-> 2. Apply Cascade Proposals vào main artifacts (nếu có)
-> 3. Đổi `status: draft` → `status: approved` trong frontmatter
->
-> Sau khi approve xong, chạy lại `/spec-tech`.
+> `/spec-new` luôn ghi `spec.md` với `status: approved` sau khi auto-cascade thành công. Nếu file đang ở `draft` → có thể `/spec-new` bị fail giữa chừng hoặc user đổi tay status. Chạy lại `/spec-new` cho integration này.
 
 **Dừng hoàn toàn. Không tiếp tục.**
 
@@ -147,7 +142,7 @@ Tổng hợp và viết draft `tech.md`:
 
 **Cấu trúc file**: dùng `.claude/templates/integrations/tech-template.md` làm skeleton, điền nội dung từ interview vào.
 
-**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."):
+**Changes blocks** — agent sinh delta cho main artifacts trong section `## Changes` của tech.md. Mỗi block tương ứng 1 artifact bị touched, declare `Operation: create | update`, content theo format template gốc với markers `[NEW] / [MODIFY {field}] / [REMOVE]` cho operation=update. Đây là phần draft sẽ auto-apply sau khi user confirm — không có "manual apply" bước riêng. Targets:
 
 ### sad.md
 
@@ -199,7 +194,8 @@ Liệt kê **tất cả** features liên quan trong frontmatter và đánh giá:
 - Nếu integration thêm/đổi rule trong FRD → cập nhật bảng Verification Implementation tương ứng
 
 Bỏ block fdd.md nếu integration không gắn với feature nào (`features: []`).
-```
+
+**Cascade Summary** — sau các Changes blocks, sinh bảng tóm tắt liệt kê tất cả targets (kể cả targets không có block, ghi `no-op`) để reviewer scan nhanh.
 
 Hiển thị draft cho user xem — **chưa ghi file**.
 
@@ -209,27 +205,81 @@ Hiển thị draft cho user xem — **chưa ghi file**.
 
 > Draft trên đã đúng chưa?
 > - Technical Design có đủ để DEV implement không?
-> - Cascade Proposals (nếu có) — cần approve trước khi tiến hành.
+> - Changes blocks đã đúng chưa? Mỗi marker có khớp current state của main artifact không?
+> - Guardrails Compliance đã pass?
+
+> **Sau khi confirm, agent sẽ auto-apply tất cả Changes blocks lên main artifacts (sad → domain → cdd → fdd).** Không có bước manual apply.
 
 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.
 
 ---
 
-### Bước 6: Save
+### Bước 6: Save + Auto-cascade
+
+**[6.1] Ghi `specs/integrations/{slug}/tech.md`** với status `approved` (không phải `draft` — human đã confirm ở Bước 5 chính là approval). Frontmatter `features` và `components` mirror từ `spec.md`.
+
+**[6.2] Auto-apply mỗi Changes block** vào main artifact tương ứng. Thứ tự apply (để tránh forward reference): `sad.md` → `domain.md` → `component/*/cdd.md` → `feature/*/fdd.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 — `cdd-template.md` hoặc `fdd-template.md`)
+  - Frontmatter: lấy từ template (status `draft` cho artifact mới — separate lifecycle với tech.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
+
+**[6.2.5] Append Change History entry** vào mỗi main artifact bị touched (theo `conventions.md` §5.5). Đây là phần atomic của auto-apply — nếu fail thì rollback luôn cả entry này.
+
+Cho mỗi artifact:
 
-Ghi nội dung đã confirm vào `specs/integrations/{slug}/tech.md`.
+1. Mở file, tìm section `## Change History` (mọi template main đã scaffold sẵn — nếu thiếu, append vào cuối file).
+2. Append entry mới ở cuối section, format:
+
+   ```markdown
+   ### {YYYY-MM-DD} — [{NNN}-{slug}](../../integrations/{NNN}-{slug}/tech.md) — {operation}
+
+   - **{Section name}**:
+     - [marker] {ID/item} — {mô tả ngắn 1 dòng}
+   ```
+
+   - Operation = `create` (artifact mới) | `update` (artifact đã tồn tại).
+   - Integration link trỏ tới `tech.md` (không phải `spec.md`) — đây là cascade từ tech.
+   - Section name = tên section trong template gốc (`Module Structure`, `Storage & Persistence`, `Inter-Component Data Flow`, `Verification Implementation`...).
+   - Path link: relative từ artifact đến `integrations/{NNN}-{slug}/tech.md` (số `../` phụ thuộc depth: 2 cho sad/domain, 3 cho component/feature).
+   - Mọi item có marker trong Changes block phải xuất hiện ở entry, group theo section.
+
+3. Với operation=create từ template trống → entry body có thể là `- **All sections**: initial scaffold`.
+
+**[6.3] Atomic rollback:** Nếu apply block nào fail (vd `[MODIFY {ID}]` nhưng ID không tồn tại):
+1. Rollback các block đã apply trước đó (kể cả Change History entries) về state ban đầu
+2. **Không** ghi tech.md
+3. Báo lỗi cụ thể cho user fix draft hoặc artifact hiện tại
+
+**[6.4] Thông báo kết quả:**
 
-Thông báo kết quả:
 ```
-✓ specs/integrations/{slug}/tech.md đã được tạo (status: draft)
+✓ specs/integrations/{slug}/tech.md đã được tạo (status: approved)
+
+Auto-cascade applied:
+  ✓ sad.md — {summary | no-op}
+  ✓ domain.md — {summary | no-op}
+  ✓ component/C-XXX-{slug}/cdd.md — {created | updated: summary}
+  ✓ feature/F-XXX-{slug}/fdd.md — {created | updated: summary}
 
 Bước tiếp theo:
-  - Review tech.md và apply Cascade Proposals (nếu có) vào main artifacts thủ công
-  - Approve tech.md (đổi status: draft → approved)
   - /plan → tạo plan.md và todo.md cho integration này
   - Sau khi tất cả tasks done: đổi status F-XXX trong prd.md thành DONE
 ```
 
+**Nếu apply fail** → dừng, báo lỗi cụ thể, **không** ghi tech.md. Yêu cầu user fix draft hoặc check artifact hiện tại.
+
 ---
 
 ## Common Rationalizations
@@ -238,21 +288,30 @@ Bước tiếp theo:
 | --- | --- |
 | "Tech design thì code xong mới biết được" | Không cần design hoàn hảo, cần đủ để thống nhất approach trước khi viết code. |
 | "Interface thì ghi sau khi implement xong" | Interface chưa được agree = BA không biết integration làm gì, không thể verify AC. |
-| "Cascade Proposals thì sau cập nhật cũng được" | Domain và SAD là shared context. Cập nhật trễ = các tech.md sau dùng context sai. |
+| "Cascade Proposals thì sau cập nhật cũng được" | Cascade là auto-apply atomic với save. Không có "sau" — confirm draft = cascade chạy ngay. |
 
 ## Red Flags
 
 - Solution Overview không có lý do chọn approach — chỉ mô tả "sẽ làm X" mà không giải thích tại sao
 - Interface Changes trống trong khi spec.md có AC về API/response shape
 - Data Model Changes bỏ qua nhưng spec.md có requirement về data mới
-- Cascade Proposals không được review trước khi approve
+- Changes blocks không được review trước khi confirm (cascade auto-apply 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 5), kiểm tra:
 
 - [ ] Solution Overview có lý do chọn approach (không chỉ mô tả)
 - [ ] Mỗi Acceptance Criterion trong spec.md đều được cover bởi design
 - [ ] Interface Changes đầy đủ method, path, auth requirement (nếu có)
-- [ ] 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])
+- [ ] Guardrails Compliance đã pass cho từng GUARD-XXX
+- [ ] Cascade Summary table khớp với các Changes blocks
+
+Sau khi user confirm (Bước 6):
+
+- [ ] Auto-apply chạy theo thứ tự sad → domain → cdd → fdd
+- [ ] Mỗi artifact bị touched có entry mới được append vào `## Change History` (conventions §5.5)
+- [ ] Fail-safe: nếu apply fail thì không ghi tech.md (rollback luôn Change History entries)

package/skills/spec-test/SKILL.md

@@ -304,6 +304,23 @@ Cho từng block:
   - Cập nhật Traceability Matrix: thêm row cho item mới, update row của item bị MODIFY, KHÔNG xóa row của REMOVE (đánh dấu retire)
   - Ghi lại tsd.md
 
+**[6.2.5] Append Change History entry** vào mỗi tsd.md bị touched (theo `conventions.md` §5.5). Đây là phần atomic của auto-apply — nếu fail thì rollback luôn.
+
+Format entry:
+
+```markdown
+### {YYYY-MM-DD} — [{NNN}-{slug}](../../../integrations/{NNN}-{slug}/test.md) — {operation}
+
+- **{Section name}**:
+  - [marker] {TS/TC ID} — {mô tả ngắn 1 dòng}
+```
+
+- Operation = `create` (tsd.md mới) | `update` (tsd.md đã tồn tại).
+- Integration link trỏ tới `test.md` (không phải `spec.md`) — đây là cascade từ test.
+- Section name = tên section trong template tsd (`Test Scenarios`, `Functional Test Cases`, `Validation Test Cases`, `Feature AC Test Cases`, `Traceability Matrix`...).
+- Mọi TS/TC có marker trong Changes block phải xuất hiện ở entry, group theo section.
+- Với operation=create từ template trống (no Changes block content) → entry body có thể là `- **All sections**: initial scaffold`.
+
 **[6.3] Atomic rollback:** Nếu apply block nào fail (vd `[MODIFY TC-F001-005]` nhưng ID không tồn tại):
 1. Rollback các block đã apply trước đó về state ban đầu
 2. **Không** ghi integration test.md
@@ -361,5 +378,6 @@ Trước khi QC confirm (Bước 5), kiểm tra:
 Sau khi QC confirm (Bước 6):
 
 - [ ] Auto-apply theo thứ tự features trong frontmatter
-- [ ] Fail-safe: nếu apply fail thì không ghi integration test.md
+- [ ] Mỗi tsd.md bị touched có entry mới trong `## Change History` (conventions §5.5)
+- [ ] Fail-safe: nếu apply fail thì không ghi integration test.md (rollback luôn Change History entries)
 - [ ] Mỗi feature tsd.md mới có status `draft` (separate lifecycle)

package/skills/spec-tsd/SKILL.md

@@ -187,6 +187,16 @@ Ghi `specs/main/feature/{F-XXX}-{slug}/tsd.md` với status `draft` (feature-lev
 
 Nếu overwrite — file backup `tsd.md.bak.{timestamp}` đã tạo ở Bước 2.
 
+**Change History:** Append entry vào section `## Change History` cuối tsd.md (theo `conventions.md` §5.5):
+
+```markdown
+### {YYYY-MM-DD} — manual — create
+
+- **All sections**: initial scaffold qua /spec-tsd (mechanical derive từ frd.md — N TS, M Functional TC, P Validation TC, Q Feature AC TC)
+```
+
+Nếu overwrite tsd.md cũ → entry vẫn dùng operation `create` (vì IDs regenerate fresh, không phải update), thêm note trong body: `- **Note**: overwrote previous tsd.md (backup tại tsd.md.bak.{timestamp}) — IDs regenerated từ 001`.
+
 Thông báo kết quả:
 
 ```

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

@@ -61,3 +61,17 @@ Các quyết định kỹ thuật đặc thù của component và lý do.
 | Quyết định | Lý do | Alternatives đã cân nhắc |
 | --- | --- | --- |
 | {decision} | {lý do cụ thể} | {option A vs B} |
+
+## Change History
+
+Append-only log của các thay đổi cascade lên artifact này. Quy ước xem `conventions.md` §5.5.
+
+<!-- Entry format:
+### YYYY-MM-DD — [{id}-{slug}](../../../integrations/{id}-{slug}/tech.md) — create|update|manual
+
+- **{Section name}**:
+  - [NEW] {item} — {mô tả ngắn}
+  - [MODIFY {field}] {item} — {old → new}
+  - [REMOVE] {item} — {lý do}
+-->
+

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

@@ -93,3 +93,17 @@ Các component khác mà component này phụ thuộc.
 | Component | Loại dependency | Cách dùng |
 | --- | --- | --- |
 | `{C-XXX}-{name}` | sync call / event subscription / shared entity | {cụ thể: gọi API nào, subscribe event nào} |
+
+## Change History
+
+Append-only log của các thay đổi cascade lên artifact này. Quy ước xem `conventions.md` §5.5.
+
+<!-- Entry format:
+### YYYY-MM-DD — [{id}-{slug}](../../../integrations/{id}-{slug}/spec.md) — create|update|manual
+
+- **{Section name}**:
+  - [NEW] {item} — {mô tả ngắn}
+  - [MODIFY {field}] {item} — {old → new}
+  - [REMOVE] {item} — {lý do}
+-->
+

package/templates/main/domain-template.md

@@ -59,3 +59,17 @@ erDiagram
     EntityA ||--o{ EntityB : ""
     EntityB }o--|| EntityC : ""
 ```
+
+## Change History
+
+Append-only log của các thay đổi cascade lên artifact này. Quy ước xem `conventions.md` §5.5.
+
+<!-- Entry format:
+### YYYY-MM-DD — [{id}-{slug}](../integrations/{id}-{slug}/spec.md) — create|update|manual
+
+- **{Section name}**:
+  - [NEW] {item} — {mô tả ngắn}
+  - [MODIFY {field}] {item} — {old → new}
+  - [REMOVE] {item} — {lý do}
+-->
+

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

@@ -69,3 +69,17 @@ Quy ước:
 - **Layer**: `client` (UI validation trước submit), `gateway` (API gateway / request validator), `service` (business logic component), hoặc kết hợp (`client + gateway` cho double-check). Layer ảnh hưởng UX (inline vs server round-trip).
 - **Owning component**: component nào chịu trách nhiệm enforce. Implementation chi tiết (regex, validator code, error class) nằm trong `cdd.md` của component đó.
 - **Error propagation**: HTTP status + error code semantic + cách render cho user. Wording cụ thể của error message thuộc UI copy artifact, không ở đây.
+
+## Change History
+
+Append-only log của các thay đổi cascade lên artifact này. Quy ước xem `conventions.md` §5.5.
+
+<!-- Entry format:
+### YYYY-MM-DD — [{id}-{slug}](../../../integrations/{id}-{slug}/tech.md) — create|update|manual
+
+- **{Section name}**:
+  - [NEW] {item} — {mô tả ngắn}
+  - [MODIFY {field}] {item} — {old → new}
+  - [REMOVE] {item} — {lý do}
+-->
+

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

@@ -153,3 +153,17 @@ Tham chiếu đến `specs/main/component/{C-XXX}-...`.
 | Component | Vai trò trong feature |
 | --- | --- |
 | `{C-XXX}-{component-name}` | {component này phục vụ cái gì cho feature này} |
+
+## Change History
+
+Append-only log của các thay đổi cascade lên artifact này. Quy ước xem `conventions.md` §5.5.
+
+<!-- Entry format:
+### YYYY-MM-DD — [{id}-{slug}](../../../integrations/{id}-{slug}/spec.md) — create|update|manual
+
+- **{Section name}**:
+  - [NEW] {item} — {mô tả ngắn}
+  - [MODIFY {field}] {item} — {old → new}
+  - [REMOVE] {item} — {lý do}
+-->
+

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

@@ -218,3 +218,17 @@ Cover Feature Acceptance Criteria (`FAC-*`) trong frd. Feature AC trong frd đã
 ### Components Used (input only)
 
 Tham chiếu `frd.md > Components Used` để hiểu contract của các component được feature này dùng. Behavior của component được verify **gián tiếp** qua các TC ở đây — không tách tsd riêng cho component.
+
+## Change History
+
+Append-only log của các thay đổi cascade lên artifact này. Quy ước xem `conventions.md` §5.5.
+
+<!-- Entry format:
+### YYYY-MM-DD — [{id}-{slug}](../../../integrations/{id}-{slug}/test.md) — create|update|manual
+
+- **{Section name}**:
+  - [NEW] {item} — {mô tả ngắn}
+  - [MODIFY {field}] {item} — {old → new}
+  - [REMOVE] {item} — {lý do}
+-->
+

package/templates/main/prd-template.md

@@ -59,3 +59,17 @@ Các thành phần kỹ thuật của hệ thống — chi tiết về vai trò
 
 - {ràng buộc kinh doanh} — constraint
 - {giả định quan trọng} — assumption
+
+## Change History
+
+Append-only log của các thay đổi cascade lên artifact này. Quy ước xem `conventions.md` §5.5.
+
+<!-- Entry format:
+### YYYY-MM-DD — [{id}-{slug}](../integrations/{id}-{slug}/spec.md) — create|update|manual
+
+- **{Section name}**:
+  - [NEW] {item} — {mô tả ngắn}
+  - [MODIFY {field}] {item} — {old → new}
+  - [REMOVE] {item} — {lý do}
+-->
+

package/templates/main/sad-template.md

@@ -74,3 +74,17 @@ Các nguyên tắc sau là bất biến. Agent phải kiểm tra compliance trư
 - GUARD-001: {nguyên tắc — ví dụ: Không dùng raw SQL, phải qua ORM}
 - 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}
+
+## Change History
+
+Append-only log của các thay đổi cascade lên artifact này. Quy ước xem `conventions.md` §5.5.
+
+<!-- Entry format:
+### YYYY-MM-DD — [{id}-{slug}](../integrations/{id}-{slug}/spec.md) — create|update|manual
+
+- **{Section name}**:
+  - [NEW] {item} — {mô tả ngắn}
+  - [MODIFY {field}] {item} — {old → new}
+  - [REMOVE] {item} — {lý do}
+-->
+