spec-lite 1.3.3 → 1.4.1

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.3",
+  "version": "1.4.1",
   "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

@@ -348,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]`:

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-remove/SKILL.md

@@ -0,0 +1,588 @@
+---
+name: spec-remove
+description: Remove một feature toàn diện — tạo removal integration với Code Inventory, Reverse Dependency Audit, reverse-TDD test strategy, và Finalize Plan (move feature artifacts sang specs/removed/ + đóng ADO tickets) như task cuối trong todo.md. Nhận F-XXX làm argument.
+---
+
+# spec-remove
+
+## Overview
+
+Tạo removal integration cho 1 feature đã tồn tại. Output là `spec.md` với đầy đủ:
+
+- **Code Inventory** — code, route, DB, feature flag, config liên quan
+- **Reverse Dependency Audit** — ai còn reference, an toàn xoá hay không
+- **Test Strategy** — reverse-TDD (regression test "thing is gone")
+- **Finalize Plan** — move feature artifacts sang `specs/removed/` + đóng ADO tickets, được DEV chạy như task cuối trong `todo.md`
+- **Changes blocks** — `[REMOVE]` markers cho mọi artifact bị touched
+
+Skill **không** sinh `tech.md` / `plan.md` / `todo.md`. Sau khi `spec.md` được approve, chạy `/spec-tech` → `/plan` → `/build` như flow thường. `spec.md` đủ giàu để 3 skill đó hoạt động không cần modification.
+
+## When to Use
+
+- Một feature đã ship và cần decommission (deprecated, business pivot, replaced by feature khác)
+- Cần xoá toàn bộ code + spec + ADO state một cách an toàn, có audit trail
+- Có nhiều reverse-dep cần được liệt kê và quyết định rõ ràng trước khi xoá
+
+## When NOT to Use
+
+- Chỉ muốn xoá 1 US / 1 AC / 1 VR khỏi feature → dùng `/spec-new` với marker `[REMOVE]` cho item đó. Feature vẫn sống.
+- Feature chưa từng được implement (chỉ có frd.md, chưa có code) → dùng `/spec-new` với block `[REMOVE]` cho frd.md, không cần workflow này.
+- Muốn pause / disable tạm thời mà giữ code → đây không phải removal, dùng feature flag thay vì skill này.
+
+---
+
+## Prerequisites
+
+- `specs/main/feature/{F-XXX}-*/frd.md` tồn tại
+- `specs/main/prd.md` có row của feature trong Feature Index
+- (Optional) `.claude/ado.yaml` cấu hình nếu muốn đóng ADO tickets ở finalize step
+
+---
+
+## Process
+
+### Bước 1: Validate argument
+
+Argument BẮT BUỘC là Feature ID dạng `F-XXX` (3 chữ số). Nếu argument thiếu hoặc sai format → dừng:
+
+```
+spec-remove cần Feature ID. Ví dụ: /spec-remove F-001
+```
+
+Tìm thư mục `specs/main/feature/F-XXX-*/`:
+- 0 matches → báo lỗi feature không tồn tại, dừng.
+- ≥ 2 matches → báo lỗi data inconsistency (nhiều thư mục cùng prefix), dừng.
+- 1 match → tiếp.
+
+Đọc `frd.md` frontmatter:
+- Nếu `status: removed` → hỏi:
+
+```
+F-XXX đã có status `removed`. Bạn muốn:
+  [1] Re-finalize (move artifacts + close ADO lại, idempotent)
+  [2] Tạo removal integration mới (có thể bạn chưa cleanup code lần trước)
+  [3] Hủy
+```
+
+---
+
+### Bước 2: Load context
+
+Đọc các file sau:
+
+**Bắt buộc:**
+- `specs/main/feature/{F-XXX}-*/frd.md` — full content
+- `specs/main/feature/{F-XXX}-*/fdd.md` — nếu tồn tại
+- `specs/main/prd.md` — Feature Index (capture ADO ticket ID cho F-XXX), Component Index, NFR
+- `specs/main/domain.md` — Glossary + Shared Entities (xác định entity nào owned bởi component thuộc F-XXX)
+
+**Components used by F-XXX:**
+
+Trích từ `frd.md` section `Components Used` + `fdd.md` section `Components Touched`. Với mỗi C-YYY:
+- `specs/main/component/{C-YYY}-*/crd.md`
+- `specs/main/component/{C-YYY}-*/cdd.md` — nếu tồn tại
+
+**Reverse dependency scan:**
+
+Với mỗi C-YYY mà F-XXX sử dụng, grep `specs/main/feature/F-*/frd.md` (trừ F-XXX) tìm references tới C-YYY. Mọi feature khác có reference → load `frd.md` của feature đó để hiểu nó dùng C-YYY làm gì.
+
+Output context summary cho user:
+
+```
+F-XXX — {feature title}
+  Status: {Done/In Progress/...}
+  ADO: #{ticket_id} ({current state}) {nếu prd.md có cột ADO}
+
+  Components dùng bởi F-XXX:
+    - C-YYY-{slug} — {role} ({exclusive | shared with F-AAA, F-BBB})
+    - ...
+
+  Reverse-dep features (dùng chung component với F-XXX):
+    ⚠ F-AAA {title} — dùng C-YYY {interface_name}
+    ⚠ F-BBB {title} — dùng C-ZZZ {interface_name}
+    {hoặc} ✓ Không có reverse-dep — F-XXX hoàn toàn cô lập
+
+  Glossary terms từ domain.md tham chiếu trong F-XXX:
+    - {term} {(unique to F-XXX | shared)}
+    - ...
+
+  Shared entities owned bởi components của F-XXX:
+    - {Entity} (Owner: C-YYY) — {used by F-XXX only | also F-AAA}
+    - ...
+```
+
+---
+
+### Bước 3: Interview ngắn
+
+Hỏi 2 câu, tuần tự:
+
+**3.1 — Lý do remove:**
+
+```
+Lý do remove F-XXX? (sẽ ghi vào Change History + ADO closure comment)
+> ___
+```
+
+**3.2 — Removal strategy:**
+
+Dùng `AskUserQuestion`:
+
+```
+Removal strategy:
+  [1] Single-shot — xoá hết trong 1 deploy. Phù hợp khi feature off-traffic, internal-only, không có DB schema lớn.
+  [2] Phased — disable trước (feature flag off + deprecation banner), soak period, sau đó xoá code. Phù hợp khi có DB / external API / traffic gradual.
+  [3] Phased + drop schema riêng — như Phased nhưng tách thêm 1 integration cho DROP TABLE/COLUMN sau khi code đã xoá và observed.
+```
+
+Nếu chọn `[2]` hoặc `[3]` → hỏi soak period (1-2 tuần là baseline):
+
+```
+Soak period giữa các phase (ngày)?
+> ___
+```
+
+Phased và Phased+drop schema → ghi nhận để Bước 6 (sinh draft) có Removal Phases section.
+
+---
+
+### Bước 4: Code Discovery
+
+Mục tiêu: build **Code Inventory** — danh sách code cụ thể sẽ bị xoá.
+
+**Nguồn discovery (kết hợp):**
+
+1. **fdd.md / cdd.md** — nếu artifact có ghi file path / module path cụ thể trong section như "Implementation Notes" → dùng làm seed trực tiếp.
+2. **Component slug** — search filesystem cho directory matching `{C-YYY}-{slug}` (kebab) hoặc camelCase variant.
+3. **Public Interface signatures** — từ `crd.md` Public Interface, lấy function/class/endpoint name → grep codebase.
+4. **Route paths** — từ `frd.md` User Flows / `fdd.md` sequence diagrams, extract API path patterns (`/api/...`) → grep route registrations.
+5. **Owned Entities** — từ `domain.md` Shared Entities (owned bởi component của F-XXX), table name → grep migrations + queries.
+6. **Feature flag names** — nếu được nhắc trong artifact → grep config files.
+7. **Test files** — sau khi xác định module paths, grep `tests/` cho cùng prefix / cùng tên.
+
+**Tools:** `Grep`, `Glob`, `Bash` (`rg`, `find`). Khi không chắc filesystem layout, hỏi user 1 câu: "Codebase root ở `src/` hay project có monorepo structure khác?"
+
+**Output Code Inventory** dạng table, group theo category:
+
+```
+Code Inventory for F-XXX:
+
+  ROUTES / API ENDPOINTS:
+    [1] POST /api/auth/login        → src/routes/auth.ts:12-50
+    [2] POST /api/auth/logout       → src/routes/auth.ts:52-80
+    [3] POST /api/auth/refresh      → src/routes/auth.ts:82-115
+
+  SOURCE MODULES:
+    [4] src/services/auth/          → entire directory (8 files)
+    [5] src/middleware/auth-token.ts
+    [6] src/utils/jwt.ts            → ⚠ also used by F-007 (reverse-dep)
+
+  TESTS:
+    [7] tests/auth/                 → 12 files
+    [8] tests/integration/auth-flow.test.ts
+
+  DATABASE:
+    [9] table `sessions`            → migration drop_sessions.sql cần tạo
+    [10] table `refresh_tokens`     → migration cần tạo
+    [11] users.last_login_at column → ⚠ used by F-007 analytics
+
+  FEATURE FLAGS:
+    [12] ff_new_auth                → src/config/flags.ts:12
+
+  CONFIG / ENV:
+    [13] AUTH_SECRET, AUTH_TTL      → .env.example, src/config/index.ts
+
+  OTHER (best-effort, manual verify):
+    - Grafana dashboard "Auth metrics" — không scan được tự động, BA verify tay
+    - Docs site có section /docs/auth/ — verify tay
+```
+
+Mỗi item có thể là `safe` (xanh) hoặc `⚠ has external ref` (cần quyết định ở Bước 5).
+
+---
+
+### Bước 5: Reverse Dependency Audit
+
+Với mỗi item trong Code Inventory, grep external references (ngoài thư mục chính của F-XXX). Mọi reference `⚠` cần user quyết định.
+
+```
+Reverse-dep audit:
+
+  [6] src/utils/jwt.ts
+      External refs found:
+        - src/services/admin/sessions.ts:34 — imports `verifyJWT`
+        - src/services/api-gateway/auth-check.ts:12 — imports `signJWT`
+
+      Quyết định:
+        [a] Keep file — không xoá src/utils/jwt.ts (chỉ xoá phần exclusive của F-XXX bên trong nếu có)
+        [b] Migrate consumer first — abort removal, tạo integration migration F-007 + api-gateway sang alternative trước
+        [c] Remove anyway — xoá luôn, downstream tự fix (rủi ro cao, cần justify)
+      Chọn: ___
+
+  [11] users.last_login_at column
+      External refs found:
+        - src/analytics/login-tracking.ts:88 — SELECT this column
+      Quyết định: ___
+```
+
+Mọi item `⚠` đều phải có quyết định trước khi sang Bước 6. Nếu user chọn `[b]` cho bất kỳ item nào → dừng skill, instruct:
+
+```
+F-XXX chưa thể remove vì có reverse-dep chưa migrate:
+  - {item} blocked by {consumer}
+
+Tạo integration migration trước:
+  /spec-new "Migrate {consumer} away from {item}"
+
+Sau khi migration deploy xong, chạy lại /spec-remove F-XXX.
+```
+
+---
+
+### Bước 6: Sinh draft spec.md
+
+Xác định slug và NNN giống `/spec-new`:
+- Slug: `remove-{f-xxx-slug}` (ví dụ `remove-f001-authentication`)
+- NNN: max của thư mục hiện có trong `specs/integrations/` + 1, format 3 chữ số.
+
+Output path: `specs/integrations/{NNN}-remove-{f-xxx-slug}/spec.md`
+
+Cấu trúc spec.md:
+
+```markdown
+---
+id: "{NNN}"
+slug: "remove-{f-xxx-slug}"
+title: "Remove {F-XXX} {feature title}"
+features: [{F-XXX}]
+components: [{C-YYY list những component bị touched}]
+status: approved
+removal: true
+created: {YYYY-MM-DD}
+---
+
+## Context
+{tóm tắt frd/fdd/components/reverse-deps đã load ở Bước 2}
+
+## Problem Statement
+{lý do remove từ Bước 3.1 — ghi từ góc nhìn business/product, không phải tech}
+
+## Removal Strategy
+{Single-shot | Phased | Phased + schema drop} — chi tiết theo lựa chọn:
+
+### Phase 1: Disable (chỉ khi Phased)
+- Tắt feature flag `ff_xxx`
+- Deprecation banner trên UI (nếu user-facing)
+- Telemetry warning log mỗi lần feature được hit
+- Soak: {N} ngày, monitor traffic = 0
+
+### Phase 2: Remove code
+- Xoá code per Code Inventory dưới
+- Regression tests (xem Test Strategy)
+
+### Phase 3: Drop schema (chỉ khi Phased + schema drop)
+- Tạo integration riêng sau {N} ngày Phase 2 deployed
+- Migration DROP TABLE / DROP COLUMN
+
+## Code Inventory
+{copy table từ Bước 4, đã loại bỏ các item user quyết định `[a] Keep`}
+
+## Reverse Dependency Audit
+{liệt kê mỗi item ⚠ + quyết định user đã chọn, kèm lý do/justify}
+
+## Test Strategy (Reverse-TDD)
+
+Pattern cho mỗi target:
+
+1. **Baseline check (trước khi xoá):** ghi nhận test hiện có hoặc viết quick smoke test xác nhận thing exists và functional. Mục đích: confirm mental model trước khi xoá.
+
+2. **Delete trong 1 commit:**
+   - Xoá source code
+   - Xoá test files cũ tương ứng
+   - Update import statements
+
+3. **Regression assertion (sau khi xoá):** thêm test khẳng định thing is gone:
+   - Route → assert GET/POST trả 404 (hoặc proper error code)
+   - Exported function/class → assert import fails (compile-time check, không cần runtime test)
+   - DB table/column → migration test confirm DROP applied, query trả error
+   - Feature flag → assert flag key không tồn tại trong config
+
+4. **Full suite run:** mọi test khác phải pass. Nếu có test fail → reverse-dep chưa detect đủ, rollback commit, audit lại.
+
+Regression tests **được giữ lại** trong codebase như guardrail — future-self không vô tình re-add feature đã removed.
+
+## Finalize Plan
+
+Đây là **task cuối** trong todo.md (sẽ được /plan tự nhặt). DEV thực thi sau khi mọi removal task khác xong và đã deploy verify.
+
+### Actions:
+
+1. **Move feature artifacts:**
+   ```bash
+   mkdir -p specs/removed
+   mv specs/main/feature/{F-XXX}-{slug}/ specs/removed/{F-XXX}-{slug}/
+   ```
+
+2. **Append Change History** vào `specs/removed/{F-XXX}-{slug}/frd.md` (nếu file còn tồn tại sau move):
+   ```markdown
+   ### {YYYY-MM-DD} — [{NNN}-remove-{slug}](../../integrations/{NNN}-remove-{slug}/spec.md) — removed
+   - **Feature decommissioned**: moved from specs/main/feature/ to specs/removed/
+   - Reason: {lý do từ Problem Statement}
+   ```
+
+3. **Update prd.md Feature Index:**
+   - Row F-XXX: status → `Removed`
+   - Add note column hoặc inline: `(see specs/removed/{F-XXX}-{slug}/)`
+
+4. **Close ADO tickets** (nếu prd.md có ADO ticket ID cho F-XXX):
+   - Feature ticket → state `Removed`
+   - Tất cả User Story tickets thuộc F-XXX → state `Removed`
+   - Comment trên mỗi ticket: "Decommissioned per integration {NNN}-remove-{slug}. Reason: {lý do}"
+   - Dùng `mcp__azure-devops__wit_update_work_item` (state) + `mcp__azure-devops__wit_add_work_item_comment` (comment)
+   - Nếu ADO state name khác (vd "Closed") → xem `.claude/ado.yaml` hoặc fetch từ `wit_get_work_item_type`
+
+5. **Verify finalize:**
+   - `ls specs/main/feature/ | grep {F-XXX}` → không còn match
+   - `ls specs/removed/{F-XXX}-{slug}/` → tồn tại
+   - prd.md grep `F-XXX` → status `Removed`
+   - ADO ticket fetch → state khớp
+
+## Changes
+<!-- Changes blocks theo format chuẩn của spec-template.md, áp dụng cho mọi artifact bị touched. Xem markers [NEW]/[MODIFY {field}]/[REMOVE] theo conventions §5.5. -->
+
+### prd.md
+**Operation:** update
+**Format reference:** [prd-template.md](../../templates/main/prd-template.md)
+
+#### Features (Feature Index)
+- Row [MODIFY status]: `F-XXX` {current status} → `Removed`
+- {nếu có note column} Row [MODIFY note]: `F-XXX` add note "see specs/removed/"
+
+#### Components (Component Index) — chỉ component exclusive với F-XXX
+- Row [MODIFY status]: `C-YYY` {current status} → `Removed`
+- ... (component shared thì KHÔNG đổi status)
+
+### feature/{F-XXX}-{slug}/frd.md
+**Operation:** update
+**Format reference:** [frd-template.md](../../templates/main/feature/frd-template.md)
+
+<!--
+Đánh dấu mọi item bằng [REMOVE]. File sẽ bị move sang specs/removed/ ở Finalize step
+nhưng cascade content vẫn ghi vào file gốc trước (để Change History entry được apply).
+-->
+
+#### User Stories
+- US-FXXX-001 [REMOVE] — feature decommissioned
+- US-FXXX-002 [REMOVE] — feature decommissioned
+- ... (mọi US)
+
+#### Acceptance Criteria
+- AC-FXXX-* [REMOVE] — feature decommissioned
+
+#### Verification Rules
+- VR-FXXX-* [REMOVE] — feature decommissioned
+
+#### Frontmatter
+- [MODIFY status]: `draft|approved|...` → `removed`
+
+### feature/{F-XXX}-{slug}/fdd.md *(nếu tồn tại)*
+**Operation:** update
+**Format reference:** [fdd-template.md](../../templates/main/feature/fdd-template.md)
+
+#### Flow Sequences
+- [REMOVE] FS-FXXX-* — feature decommissioned
+
+#### Data Models
+- [REMOVE] {model} — feature decommissioned
+
+#### Frontmatter
+- [MODIFY status]: → `removed`
+
+### component/{C-YYY}-{slug}/crd.md *(lặp cho mỗi component bị touched)*
+**Operation:** update
+**Format reference:** [crd-template.md](../../templates/main/component/crd-template.md)
+
+<!--
+Component exclusive với F-XXX:
+- Toàn bộ sections [REMOVE]
+- Frontmatter status → removed
+
+Component shared (vẫn còn feature khác dùng):
+- Chỉ [REMOVE] những Public Interface / Responsibility / Owned Entity
+  chỉ phục vụ F-XXX (đã audit ở Bước 5)
+- Giữ nguyên phần còn lại
+- Frontmatter status KHÔNG đổi
+-->
+
+#### Public Interface
+- {interface} [REMOVE] — only used by F-XXX, no other consumer
+
+#### Owned Entities
+- {Entity} [REMOVE] — exclusive to F-XXX
+
+### domain.md
+**Operation:** update
+**Format reference:** [domain-template.md](../../templates/main/domain-template.md)
+
+#### Glossary
+- {term} [REMOVE] — unique to F-XXX, no other reference
+
+#### Shared Entities
+- {Entity} [REMOVE] — orphan after F-XXX removal, no other component owns
+
+## Out of Scope
+- {Migration của reverse-dep features tới alternative — separate integration nếu có}
+- {Documentation site cleanup — manual task ngoài integration}
+- {Grafana dashboard cleanup — manual task}
+
+## Cascade Summary
+
+| Artifact | Operation | Summary |
+| --- | --- | --- |
+| `prd.md` | update | F-XXX status → Removed; {N} components status → Removed |
+| `feature/F-XXX-*/frd.md` | update | All items [REMOVE]; status → removed; folder move tại Finalize |
+| `feature/F-XXX-*/fdd.md` | update | All items [REMOVE]; status → removed |
+| `component/C-YYY-*/crd.md` | update | All [REMOVE] (exclusive) / {N} items [REMOVE] (shared) |
+| `domain.md` | update | {N} glossary [REMOVE], {N} entity [REMOVE] |
+```
+
+---
+
+### Bước 7: Review — xác nhận với user
+
+Hiển thị toàn bộ draft. Hỏi:
+
+```
+Draft trên đã đúng chưa?
+  - Code Inventory đầy đủ và chính xác?
+  - Reverse-dep audit đã quyết định hết các ⚠?
+  - Removal Strategy phù hợp (single-shot vs phased)?
+  - Finalize Plan đủ steps?
+  - Changes blocks dùng [REMOVE] đúng chỗ (exclusive vs shared)?
+
+Sau khi confirm, agent sẽ auto-apply Changes blocks lên main artifacts.
+File feature artifacts (frd/fdd) KHÔNG bị move ngay — chỉ apply [REMOVE] markers
++ Change History entry. Move sang specs/removed/ là task cuối trong todo.md,
+do /build chạy sau khi mọi deletion task khác xong.
+```
+
+Chỉ tiến hành Bước 8 sau khi user confirm.
+
+---
+
+### Bước 8: Save + Auto-cascade
+
+Giống `/spec-new` Bước 7, nhưng với removal-specific extensions.
+
+**[8.1] Ghi spec.md** với status `approved`, `removal: true` trong frontmatter. Frontmatter `features` chứa F-XXX, `components` chứa list components touched.
+
+**[8.2] Auto-apply Changes blocks** vào main artifacts. Thứ tự: `prd.md` → `domain.md` → `sad.md` → `component/*/crd.md` → `component/*/cdd.md` → `feature/F-XXX-*/frd.md` → `feature/F-XXX-*/fdd.md`.
+
+Áp dụng marker [REMOVE] theo conventions §5.5:
+- Xoá item khỏi artifact, ID không tái sử dụng, không renumber.
+- Khi toàn bộ items trong frd/fdd của F-XXX bị [REMOVE] → đổi frontmatter `status: removed`.
+
+**[8.3] Append Change History entry** vào mọi artifact bị touched (conventions §5.5). Entry format chuẩn:
+
+```markdown
+### {YYYY-MM-DD} — [{NNN}-remove-{slug}](../../integrations/{NNN}-remove-{slug}/spec.md) — update
+
+- **{Section name}**:
+  - [REMOVE] {ID/item} — feature decommissioned ({lý do ngắn})
+```
+
+**[8.4] Side-effects:**
+
+- Trong prd.md: row F-XXX status đổi `Removed` ngay (không chờ finalize). Lý do: spec.md đã approved tức là quyết định removal đã được ký, status reflect quyết định ngay.
+- ADO tickets KHÔNG transition ngay. Chỉ transition khi DEV chạy task Finalize ở `/build`. Lý do: tránh case rollback removal sau khi spec approve nhưng chưa deploy.
+- File feature/F-XXX-*/ KHÔNG move ngay. Lý do giống ADO — chỉ move sau khi code thật đã xoá và verified.
+
+**[8.5] Thông báo kết quả:**
+
+```
+✓ specs/integrations/{NNN}-remove-{f-xxx-slug}/spec.md đã được tạo (status: approved, removal: true)
+
+Auto-cascade applied:
+  ✓ prd.md — F-XXX status → Removed; {N} components status → Removed
+  ✓ domain.md — {N} glossary/entity [REMOVE]
+  ✓ component/C-YYY-*/crd.md — {summary}
+  ✓ feature/F-XXX-*/frd.md — all items [REMOVE], status → removed
+  ✓ feature/F-XXX-*/fdd.md — all items [REMOVE], status → removed
+
+⚠ File feature/F-XXX-*/ vẫn ở specs/main/feature/. Sẽ được move sang specs/removed/ ở task cuối todo.md.
+⚠ ADO tickets giữ nguyên state. Sẽ được close ở task cuối todo.md (cần .claude/ado.yaml).
+
+Bước tiếp theo:
+  /spec-tech     → thiết kế delete order, migration SQL, regression test cases
+  /plan          → break down deletion tasks + finalize task cuối
+  /build         → execute deletion + finalize
+```
+
+**Nếu apply fail** (markers reference ID không tồn tại, reverse-dep audit chưa hoàn tất, file không ghi được) → dừng, báo lỗi cụ thể, **không** ghi spec.md. Yêu cầu user fix draft.
+
+---
+
+## Downstream Integration (informational)
+
+Skill này chỉ sinh `spec.md`. Để biết các skill sau xử lý removal flavor như nào:
+
+- **`/spec-tech`** đọc `spec.md`, thấy `removal: true` + Code Inventory + Test Strategy + Finalize Plan → sinh `tech.md` với:
+  - Section "Delete Order" liệt kê file paths theo Code Inventory
+  - Section "Migration SQL" nếu có DB target (DROP + rollback)
+  - Section "Regression Tests" theo Test Strategy pattern
+  - Section "Finalize Task" passthrough nguyên xi từ spec.md Finalize Plan
+
+- **`/plan`** đọc cả spec.md + tech.md → sinh `plan.md` + `todo.md`. Task cuối todo.md = Finalize task với 5 sub-actions như Finalize Plan của spec.md.
+
+- **`/build`** chạy tuần tự todo.md. Khi tới Finalize task:
+  - Move folder bằng shell mv
+  - Edit prd.md
+  - Append Change History
+  - Gọi ADO API để transition tickets (cần `.claude/ado.yaml` configured)
+  - Verify outputs
+
+Nếu `/spec-tech` hoặc `/plan` hiện tại chưa nhặt được removal flavor → có thể cần update sau (separate work). Trong v1, spec.md đủ rõ ràng để 2 skill đó produce reasonable output kể cả không có removal-awareness explicit.
+
+---
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "Grep nhanh, không cần Code Inventory chi tiết" | Inventory sót item = code chết nằm trong repo vô thời hạn. Audit trail mất. |
+| "Reverse-dep nhỏ thôi, xoá luôn rồi fix sau" | Một import dangling phá CI cả team. Audit trước rẻ hơn rollback. |
+| "Feature flag off là xong, không cần xoá code" | Code dead vẫn phải maintain (security patch, dependency upgrade). Xoá hẳn mới sạch. |
+| "Single-shot cho nhanh, soak period làm gì" | Có DB / external traffic mà single-shot = rollback đắt khi phát hiện consumer chưa migrate. |
+| "Skip Finalize, để folder ở main feature là được" | Active dir bị noise. Sau 5 features removed, không phân biệt được active vs dead. |
+
+## Red Flags
+
+- Code Inventory empty hoặc chỉ có 1-2 file cho 1 feature đã ship → discovery chưa đủ rộng, xem lại sources
+- Reverse-dep audit không có ⚠ nào cho component shared → grep chưa đủ kỹ
+- Removal Strategy single-shot nhưng có DB schema lớn hoặc external traffic > 0 → cân nhắc Phased
+- Test Strategy chỉ có "delete code" mà không có regression test → future re-add risk
+- Finalize Plan thiếu ADO closure mà prd.md có ticket ID → audit trail không đầy đủ
+- Changes block frd.md mark [REMOVE] nhưng không đổi `status: removed` trong frontmatter → inconsistent state
+
+## Verification
+
+Trước khi user confirm (Bước 7):
+
+- [ ] Code Inventory liệt kê đủ 7 category (route / module / test / DB / flag / config / other)
+- [ ] Mỗi item ⚠ trong Reverse-dep audit đã có quyết định rõ ràng (a/b/c)
+- [ ] Nếu có item chọn `[b] Migrate first` → skill đã dừng, không tạo spec
+- [ ] Removal Strategy match scale: single-shot cho nhỏ, phased cho lớn
+- [ ] Test Strategy có 4 sub-step: baseline / delete / regression / full-suite
+- [ ] Finalize Plan có 5 actions: move folder / change history / prd update / ADO close / verify
+- [ ] Changes blocks: exclusive component → all [REMOVE]; shared component → chỉ items của F-XXX [REMOVE]
+- [ ] frd.md / fdd.md frontmatter có [MODIFY status] → removed
+
+Sau khi user confirm (Bước 8):
+
+- [ ] spec.md frontmatter `removal: true`
+- [ ] Auto-cascade chạy đúng thứ tự prd → domain → sad → crd → cdd → frd → fdd
+- [ ] Mọi artifact bị touched có Change History entry
+- [ ] prd.md row F-XXX status = Removed (đổi ngay sau approve)
+- [ ] File feature/F-XXX-*/ VẪN ở specs/main/feature/ (chưa move — chỉ move ở Finalize task)
+- [ ] ADO tickets KHÔNG bị transition (chưa close — chỉ close ở Finalize task)
+- [ ] Notification cuối ghi rõ 2 ⚠ về việc folder + ADO chưa được động vào

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}
+-->
+