spec-lite 1.4.6 → 1.5.0

package/README.md

@@ -151,10 +151,13 @@ Sau khi có findings, hỏi user severity tier muốn xử lý (Critical / Criti
 
 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.
+Mỗi template mang `template_version` (số nguyên) trong frontmatter; artifact copy nó lúc được tạo. Khi template đổi structure, artifact cũ thành "lỗi thời" — hai skill dưới phát hiện và migrate. Quy ước đầy đủ: [conventions.md](conventions.md) §7.
 
-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ì.
+#### `/artifact-audit [type]`
+Phát hiện artifact lỗi thời. So `template_version` của artifact với version đọc thẳng từ template. Versioned: `==` → up-to-date; `!=` → out-dated `(vX → vY)` → migrate. Legacy thiếu version → presence-check (đủ required `##` headings + không còn section đã `migrations.remove`): conform → stamp version; lệch → out-dated. Chỉ phát hiện + stamp, KHÔNG migrate. Scope theo arg (1 type / list) hoặc toàn bộ.
+
+#### `/artifact-migrate [path]`
+Migrate artifact lỗi thời lên structure mới (generic mọi type). Tự chạy `/artifact-audit` (classify-only) để phát hiện, rồi áp delta từ block `migrations` của template: **add** required section thiếu (skeleton từ template; nội dung mới → interview hoặc `NEEDS_CLARIFY`, không bịa), **remove** section đã `migrations.remove` (có confirm; giữ content tác giả khác), **update** section đổi format (giữ section + ngữ nghĩa, vd ASCII → Mermaid; show cũ + đề xuất mới, không bịa). Rename = remove+add → hỏi carry-over. Single-artifact, không cascade. Pre-flight git clean — rollback dùng git, không `.bak`. No-op nếu đã up-to-date.
 
 ---
 
@@ -169,7 +172,8 @@ Pre-flight yêu cầu git working tree clean — rollback dùng `git checkout --
 | `/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)* |
+| `/artifact-audit` | *(báo cáo out-dated; + stamp `template_version` cho artifact legacy conform)* |
+| `/artifact-migrate` | *(modify in-place artifact lỗi thời lên structure mới + set `template_version`)* |
 | `/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` |

package/bin/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { cpSync, mkdirSync, existsSync } from 'fs'
+import { cpSync, mkdirSync, existsSync, readFileSync, writeFileSync } from 'fs'
 import { join, dirname } from 'path'
 import { fileURLToPath } from 'url'
 
@@ -11,6 +11,8 @@ if (command === 'install') {
   const pkgRoot = join(__dirname, '..')
   const claudeDir = join(cwd, '.claude')
 
+  const pkg = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8'))
+
   mkdirSync(claudeDir, { recursive: true })
 
   // Copy skills → .claude/skills/
@@ -28,6 +30,25 @@ if (command === 'install') {
   // Copy references → .claude/references/
   cpSync(join(pkgRoot, 'references'), join(claudeDir, 'references'), { recursive: true })
   console.log('✓ references  →  .claude/references/')
+
+  // Write install metadata → .claude/spec-lite.json
+  const metaPath = join(claudeDir, 'spec-lite.json')
+  const prev = existsSync(metaPath)
+    ? JSON.parse(readFileSync(metaPath, 'utf8'))
+    : null
+  const now = new Date().toISOString()
+  const meta = {
+    name: pkg.name,
+    version: pkg.version,
+    installedAt: prev?.installedAt ?? now,
+    updatedAt: now,
+    contents: ['skills', 'templates', 'references'],
+  }
+  writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n')
+  const action = prev
+    ? `updated ${prev.version} → ${pkg.version}`
+    : `installed ${pkg.version}`
+  console.log(`✓ spec-lite.json  →  .claude/spec-lite.json (${action})`)
 } else {
   console.log('Usage: npx spec-lite install')
   process.exit(1)

package/package.json

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

package/skills/ado-config/SKILL.md

@@ -53,16 +53,19 @@ options:
     description: "Cập nhật danh sách PE / SE / DE"
   - label: "Epic ticket"
     description: "Tạo mới hoặc thay Epic ticket đang được lưu"
+  - label: "Area / Iteration path"
+    description: "Cập nhật area_path và iteration_path mặc định cho ticket"
   - label: "Môi trường"
     description: "Cập nhật danh sách environments (dev / stag / prod)"
 ```
 
 Tuỳ theo lựa chọn:
-- **"Toàn bộ từ đầu"** → chạy Bước 2 → 3 → 4 → 5 → 6 → 7
-- **"Thông tin project"** → chỉ chạy Bước 2, bỏ qua Bước 3, 4, 5, nhảy thẳng đến Bước 6 → 7 (giữ nguyên `team`, `epic`, `environments` từ file cũ)
-- **"Team members"** → chỉ chạy Bước 3, bỏ qua Bước 2, 4, 5, nhảy thẳng đến Bước 6 → 7 (giữ nguyên `organization/project`, `epic`, `environments` từ file cũ)
-- **"Epic ticket"** → chỉ chạy Bước 4, bỏ qua Bước 2, 3, 5, nhảy thẳng đến Bước 6 → 7 (giữ nguyên `organization/project`, `team`, `environments` từ file cũ)
-- **"Môi trường"** → chỉ chạy Bước 5, bỏ qua Bước 2, 3, 4, nhảy thẳng đến Bước 6 → 7 (giữ nguyên tất cả từ file cũ)
+- **"Toàn bộ từ đầu"** → chạy Bước 2 → 3 → 4 → 5 → 6 → 7 → 8
+- **"Thông tin project"** → chỉ chạy Bước 2, bỏ qua Bước 3, 4, 5, 6, nhảy thẳng đến Bước 7 → 8 (giữ nguyên `team`, `epic`, `area_path/iteration_path`, `environments` từ file cũ)
+- **"Team members"** → chỉ chạy Bước 3, bỏ qua Bước 2, 4, 5, 6, nhảy thẳng đến Bước 7 → 8 (giữ nguyên `organization/project`, `epic`, `area_path/iteration_path`, `environments` từ file cũ)
+- **"Epic ticket"** → chỉ chạy Bước 4, bỏ qua Bước 2, 3, 5, 6, nhảy thẳng đến Bước 7 → 8 (giữ nguyên `organization/project`, `team`, `area_path/iteration_path`, `environments` từ file cũ)
+- **"Area / Iteration path"** → chỉ chạy Bước 5, bỏ qua Bước 2, 3, 4, 6, nhảy thẳng đến Bước 7 → 8 (giữ nguyên tất cả còn lại từ file cũ)
+- **"Môi trường"** → chỉ chạy Bước 6, bỏ qua Bước 2, 3, 4, 5, nhảy thẳng đến Bước 7 → 8 (giữ nguyên tất cả từ file cũ)
 
 ---
 
@@ -238,7 +241,41 @@ https://dev.azure.com/{organization}/{project_name}/_workitems/edit/{id}
 
 ---
 
-### Bước 5: Cấu hình môi trường
+### Bước 5: Cấu hình Area & Iteration Path
+
+Area Path và Iteration Path mặc định sẽ được gán cho mọi Feature/User Story khi `/ado-create` tạo ticket. Cả hai đều **tùy chọn** — nếu bỏ trống, ADO dùng giá trị mặc định của team.
+
+Hỏi user bằng `AskUserQuestion`:
+
+```
+question: "Cấu hình Area / Iteration path mặc định cho ticket?"
+options:
+  - label: "Nhập area & iteration path"
+    description: "Gán area_path và iteration_path mặc định cho mọi ticket tạo qua /ado-create"
+  - label: "Bỏ qua"
+    description: "Không set — ADO dùng giá trị mặc định của team"
+```
+
+Nếu user chọn **"Nhập area & iteration path"** → hỏi lần lượt (cho phép Enter trống để bỏ từng field):
+
+```
+Area Path (ví dụ: Tickets\Clients\C-GAL\P-GCC):
+> Tickets\Clients\C-GAL\P-GCC
+
+Iteration Path (ví dụ: Tickets\Weekly Sprint):
+> Tickets\Weekly Sprint
+```
+
+Lưu ý khi thu thập:
+- Path dùng dấu backslash `\` phân cách như trên ADO. Chấp nhận cả khi user paste có khoảng trắng ở đầu/cuối → trim.
+- Nếu user nhập area path nhưng không chắc đúng → vẫn lưu nguyên văn, không tự validate qua MCP (tránh fail khi node chưa tồn tại). Validation thực tế sẽ xảy ra lúc `/ado-create` tạo ticket.
+- Field nào để trống → bỏ key tương ứng trong YAML, không ghi `area_path: null`.
+
+Nếu user chọn **"Bỏ qua"** → không thêm `area_path`/`iteration_path` vào config.
+
+---
+
+### Bước 6: Cấu hình môi trường
 
 **Bắt buộc** hỏi user bằng `AskUserQuestion` — không cho phép bỏ qua:
 
@@ -265,7 +302,7 @@ Nếu user chọn "Other" (nhập tay) → parse chuỗi nhập vào (phân các
 
 ---
 
-### Bước 6: Preview và xác nhận
+### Bước 7: Preview và xác nhận
 
 Hiển thị preview YAML sẽ được ghi — **chưa ghi file**:
 
@@ -287,6 +324,9 @@ team:
   DE:
     - d@atstechnology.vn
 
+area_path: 'Tickets\Clients\C-GAL\P-GCC'
+iteration_path: 'Tickets\Weekly Sprint'
+
 epic:
   id: 42
   title: "[GAL-GCC] Spec Lite Kit"
@@ -304,11 +344,13 @@ Nếu user yêu cầu chỉnh sửa → cập nhật preview → hỏi lại.
 
 Nếu user bỏ qua bước Epic (không muốn cấu hình ngay) → bỏ qua key `epic` trong YAML, không ghi `epic: null`.
 
-**Bước 5 (môi trường) là bắt buộc** — không cho phép bỏ qua. Nếu user chưa chọn, nhắc lại trước khi tiếp tục.
+Nếu user bỏ qua Area/Iteration (Bước 5) → bỏ qua key `area_path`/`iteration_path` tương ứng, không ghi giá trị `null`.
+
+**Bước 6 (môi trường) là bắt buộc** — không cho phép bỏ qua. Nếu user chưa chọn, nhắc lại trước khi tiếp tục.
 
 ---
 
-### Bước 7: Ghi file
+### Bước 8: Ghi file
 
 Ghi nội dung đã confirm vào `.claude/ado.yaml`.
 
@@ -345,5 +387,6 @@ Trước khi ghi file, kiểm tra:
 - [ ] `team.PE` có ít nhất 1 email — không được để trống
 - [ ] SE và DE có thể là array rỗng `[]`
 - [ ] Nếu có Epic: `epic.id` là số nguyên, `epic.title` có prefix `[{project_code}]`, `epic.url` là full URL dạng `https://dev.azure.com/{org}/{project_name}/_workitems/edit/{id}`
+- [ ] Nếu có `area_path` / `iteration_path`: là chuỗi đã trim, giữ nguyên dấu `\` (dùng YAML single-quote để tránh escape); bỏ qua key nếu user không nhập — không ghi `null`
 - [ ] `environments` là array ít nhất 1 phần tử (bắt buộc), mỗi phần tử là lowercase string không có khoảng trắng, luôn có `prod` ở cuối
 - [ ] User đã confirm preview trước khi ghi file

package/skills/ado-create/SKILL.md

@@ -14,6 +14,8 @@ description: Tạo Feature và User Story tickets trên ADO từ spec.md của m
 - `.claude/ado.yaml` phải tồn tại và có `epic.id` (chạy `/ado-config` nếu chưa có)
 - `frd.md` tương ứng phải tồn tại trong `.specs/main/features/` cho mỗi feature
 
+**Area / Iteration (tùy chọn):** Nếu `.claude/ado.yaml` có `area_path` và/hoặc `iteration_path`, mọi ticket (Feature + User Story) tạo ở Bước 5 và Bước 6 phải set `areaPath` / `iterationPath` tương ứng. Nếu không khai báo → để ADO dùng giá trị mặc định của team.
+
 ---
 
 ## Process
@@ -131,6 +133,8 @@ Gọi `mcp__azure-devops__wit_create_work_item` với:
 - `title`: `[{project_code}] [{feature_id}] {feature_name}` — ví dụ: `[SDLC-TEST] [F-001] Đăng ký / Đăng nhập`
 - `description`: toàn bộ nội dung `frd.md` (giữ nguyên format Markdown)
 - `assignedTo`: ADO identity ID của current user (nếu resolve thành công)
+- `areaPath`: giá trị `area_path` từ ado.yaml (nếu có)
+- `iterationPath`: giá trị `iteration_path` từ ado.yaml (nếu có)
 
 Sau khi tạo thành công → **ngay lập tức** link parent. Ưu tiên dùng `mcp__azure-devops__wit_add_child_work_items` (parent = Epic ID, child = Feature ticket ID). Nếu tool này không khả dụng, fallback sang `mcp__azure-devops__wit_work_items_link` với:
 - `sourceId`: Feature ticket ID vừa tạo
@@ -186,6 +190,8 @@ Gọi `mcp__azure-devops__wit_create_work_item` với:
 - `title`: `[{project_code}] [{feature_name}] - {US-code} — {story_title}` — ví dụ: `[SDLC-TEST] [Đăng ký / Đăng nhập] - US-F001-001 — Đăng ký`
 - `description`: description đã build ở 6.2
 - `assignedTo`: ADO identity ID của current user
+- `areaPath`: giá trị `area_path` từ ado.yaml (nếu có)
+- `iterationPath`: giá trị `iteration_path` từ ado.yaml (nếu có)
 
 Sau khi tạo thành công → **ngay lập tức** link parent. Ưu tiên dùng `mcp__azure-devops__wit_add_child_work_items` (parent = Feature ticket ID, child = User Story ticket ID). Nếu không khả dụng, fallback sang `mcp__azure-devops__wit_work_items_link` với:
 - `sourceId`: User Story ticket ID vừa tạo

package/skills/artifact-audit/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: artifact-audit
+description: Audit artifacts trong .specs/ xem có lỗi thời so với template không. So `template_version` của artifact với `template_version` hiện tại đọc thẳng từ template (.claude/templates/). Versioned khớp → up-to-date, lệch → out-dated (in vX → vY). Artifact thiếu version (sinh trước versioning) → đối chiếu structure với template: khớp thì stamp version, lệch thì flag out-dated. KHÔNG tự migrate — chỉ stamp khi chắc chắn khớp + báo cáo. Nhận tùy chọn 1 hay nhiều type làm scope (vd `frd`, `frd,spec`); không có arg → audit mọi type.
+---
+
+# artifact-audit
+
+## Overview
+
+Trả lời một câu hỏi: **artifact nào trong `.specs/` đã lỗi thời so với template mới nhất?**
+
+Cơ chế (xem `conventions.md` §7 Template Versioning):
+- **Nguồn sự thật** = `template_version` trong frontmatter template đang cài (`.claude/templates/...`). Đọc thẳng lúc chạy — không manifest, không cache.
+- Mỗi artifact mang `template_version` (copy lúc CREATE bởi skill sinh nó). Audit so số artifact với số template.
+
+Skill này **chỉ phát hiện + stamp legacy**, **KHÔNG migrate**. Việc đưa structure artifact lên format mới là của `/artifact-migrate` (generic cho mọi type).
+
+## When to Use
+
+- Sau khi `git pull` kit mới (template có thể đã bump version) → xem artifact nào cần migrate.
+- Audit định kỳ một type cụ thể (`/artifact-audit frd`) hoặc toàn repo (`/artifact-audit`).
+- Sau khi bump `template_version` của một template → tìm mọi artifact giờ thành `out-dated`.
+- Onboarding repo cũ → stamp version cho artifact legacy khớp structure, lọc ra cái cần migrate.
+
+## When NOT to Use
+
+- Muốn **migrate** artifact lên format mới → `/artifact-migrate` (skill này chỉ flag, không sửa structure).
+- Muốn đổi **nội dung** artifact → integration changeset (`/spec-new`) hoặc edit tay.
+- Chưa cài template vào `.claude/templates/` → skill không có nguồn version để so; dừng.
+
+---
+
+## Type → template map
+
+Type của artifact resolve theo **filename** (integration artifact không có field `type` trong frontmatter). Mỗi type map tới đúng một template:
+
+| Filename | type | Template (`.claude/templates/...`) |
+| --- | --- | --- |
+| `prd.md` | prd | `main/prd-template.md` |
+| `domain.md` | domain | `main/domain-template.md` |
+| `sad.md` | sad | `main/sad-template.md` |
+| `frd.md` | frd | `main/feature/frd-template.md` |
+| `fdd.md` | fdd | `main/feature/fdd-template.md` |
+| `tsd.md` | tsd | `main/feature/tsd-template.md` |
+| `crd.md` | crd | `main/component/crd-template.md` |
+| `cdd.md` | cdd | `main/component/cdd-template.md` |
+| `spec.md` | spec | `integrations/spec-template.md` |
+| `tech.md` | tech | `integrations/tech-template.md` |
+| `test.md` | test | `integrations/test-template.md` |
+| `plan.md` | plan | `integrations/plan-template.md` |
+| `todo.md` | todo | `integrations/todo-template.md` |
+| `techdebt.md` | techdebt | `integrations/techdebt-template.md` |
+
+File không khớp bảng (vd `notes.md`, `*.bak`) → bỏ qua, không phải artifact có template.
+
+---
+
+## Process
+
+### Bước 0: Resolve scope
+
+- **ARGUMENT là 1 type hoặc list** (vd `frd`, `frd,spec,tech`) → chỉ audit các type đó. Type lạ (không có trong map) → cảnh báo và bỏ qua type đó.
+- **Không có ARGUMENT** → audit **mọi** type trong map.
+
+### Bước 1: Đọc current version của template
+
+Cho mỗi type trong scope, đọc frontmatter template tương ứng tại `.claude/templates/...` → lấy `template_version`.
+
+- Template thiếu field `template_version` → không audit được type đó (chưa versioned ở phía template); cảnh báo, skip type.
+- Template không tồn tại tại `.claude/templates/` → báo kit chưa cài đủ; dừng.
+
+Lưu bảng `currentVersion[type]`.
+
+### Bước 2: Discover artifacts
+
+Quét artifacts trong:
+- `.specs/main/**` (prd, domain, sad, và feature/component artifacts)
+- `.specs/integrations/**` (spec, tech, test, plan, todo, techdebt)
+
+**Bỏ qua** (đã đóng băng — không audit/migrate):
+- `.specs/archive/**`, `.specs/removed/**`, file `*.bak.*`, file không khớp type map.
+- **Integration folder đã `done`**: nếu `.specs/integrations/{X}/spec.md` có `status: done` → bỏ qua **toàn bộ folder đó** (spec/tech/test/plan/todo/techdebt). Integration artifacts là **immutable sau khi done** (conventions §7 Versioning) — không migrate record bất biến. Folder integration đang active (spec chưa `done`) và mọi **main artifact** thì vẫn audit/migrate bình thường.
+
+Với mỗi file khớp: resolve type theo filename, đọc frontmatter để lấy `template_version` (có thể thiếu).
+
+### Bước 3: Classify
+
+Cho mỗi artifact:
+
+**3a. Có `template_version`** → so với `currentVersion[type]`:
+- `==` → **up-to-date**.
+- `!=` → **out-dated** → cần migrate. Ghi `(vX → vY)`.
+
+Version compare bắt **mọi** loại delta của các bump ở giữa — `add` / `remove` / **`update` (format)** — kể cả thay đổi format mà presence-check không thấy được. Số version là tín hiệu tổng.
+
+**3b. Thiếu `template_version`** (unversioned — sinh trước versioning) → chưa kết luận được bằng số. Áp **conformance check** (xem `conventions.md` §7 "Conformance model — required-emptyable").
+
+> **Điểm mù:** presence-check chỉ thấy heading có/không → **KHÔNG phát hiện được format-update** (vd section vẫn đó nhưng dùng ASCII diagram thay vì Mermaid). Artifact unversioned đủ heading sẽ bị stamp thành conform dù format cũ. Đây là giới hạn cố hữu của nhánh unversioned (format-update chỉ bắt được qua version compare ở 3a). Chấp nhận vì là edge-case pre-versioning.
+
+**Presence-check, quan hệ BAO HÀM (superset).** Conformance = artifact **chứa đủ mọi heading required** của template (body rỗng OK). Template là skeleton tối thiểu; artifact đã điền luôn chứa nhiều hơn. KHÔNG đòi giống hệt template.
+- **Required heading** = các heading **`##`** của template body, TRỪ cái đánh dấu `*(nếu có)*` (conditional). Heading `###` là instance/sub (vd `### US-F{NNN}-001`, `### Flow 1`) → KHÔNG tính. Phân biệt bằng level nên deterministic.
+
+**Hai dấu hiệu out-dated** (artifact tụt sau template) — đọc `remove` từ block `migrations` của template để biết tên section deprecated cần dò:
+1. **Thiếu** một required heading mà template hiện tại có.
+2. **Còn chứa** một section mà `migrations.remove` ghi đã bỏ (deprecated còn sót).
+
+(Đổi tên section được biểu diễn bằng remove + add ở block `migrations`, nên rơi vào cả 2 dấu hiệu: tên cũ nằm trong `remove` → dấu hiệu 2; tên mới là required heading bị thiếu → dấu hiệu 1.)
+
+**KHÔNG phải out-dated** (authoring bình thường, vẫn **stamp**):
+- Artifact **thêm** sub-section / heading con không có trong template (vd dưới `### Feature Acceptance Criteria` có thêm `#### NFR AC`). Required heading vẫn có mặt → conform.
+- Body rỗng của một required-emptyable section.
+- Thêm nội dung/bảng/ghi chú riêng **không nằm trong `migrations.remove`**; khác thứ tự; số item nhiều/ít hơn ví dụ.
+
+> **Quan trọng — phân biệt dấu hiệu 2 với superset:** section "thừa" (có trong artifact, không trong template) chỉ là out-dated khi tên nó **nằm trong `migrations.remove`** (đã khai báo deprecated). Section thừa **không** được khai báo remove → là content tác giả → **giữ, conform** (superset). Đây là cách removal vẫn detect được bằng presence-check mà không xóa nhầm content.
+
+Kết luận:
+- **Conform** (đủ required heading, không dính 1–2) → **stamp** `template_version: <currentVersion>`. Lần audit sau so bằng số.
+- **Out-dated** (dính ≥1 trong 1–2) → KHÔNG stamp. Tóm tắt đúng dấu hiệu (thiếu required heading gì / section deprecated nào còn sót) để `/artifact-migrate` xử lý.
+
+> Nguyên tắc thận trọng — chỉ về việc **có stamp hay không**: nếu nghi ngờ một required heading có thực sự thiếu hay không (diễn đạt khác) → flag out-dated thay vì stamp (thà flag thừa còn hơn giấu artifact lỗi thời). **Nội dung thừa không khai báo remove KHÔNG bao giờ là lý do nghi ngờ** — chỉ thiếu-required / deprecated-còn-sót mới tính.
+
+### Bước 4: Confirm trước khi stamp
+
+> **Chế độ classify-only** (khi `/artifact-migrate` gọi audit làm bước phát hiện): **bỏ qua Bước 4–5** — KHÔNG stamp, KHÔNG confirm, chỉ trả phân loại (up-to-date / legacy-conformant / out-dated) cho caller. Mọi ghi (stamp + migrate) do `/artifact-migrate` điều phối trong một luồng confirm duy nhất. Phần dưới chỉ áp dụng khi audit chạy **standalone**.
+
+Nếu Bước 3b có artifact cần stamp → hiển thị danh sách **sẽ stamp** + danh sách **out-dated** trước, xin confirm:
+
+> Sẽ ghi `template_version` vào {N} artifact legacy khớp structure (additive frontmatter change). {M} artifact out-dated sẽ KHÔNG bị đụng. Tiếp tục? [y/n]
+
+`y` → ghi stamp (chỉ thêm field `template_version` vào frontmatter, không đụng nội dung khác). `n` → bỏ qua stamp, vẫn in báo cáo.
+
+Stamp là thay đổi additive an toàn; khuyến nghị commit riêng để diff sạch.
+
+### Bước 5: Report
+
+In bảng phân nhóm (xem Output Format). Skill **không** migrate, **không** đổi nội dung artifact ngoài việc stamp ở Bước 4.
+
+---
+
+## Output Format
+
+```
+ARTIFACT AUDIT — scope: {all | frd, spec}
+Current template versions: prd v1 · domain v1 · sad v1 · frd v2 · spec v1 · ...
+
+OUT-DATED ({n}) — cần migrate:
+  feature/F-002-payment/frd.md       frd    v1 → v2   → /artifact-migrate
+  feature/F-003-x/frd.md             frd    unversioned, lệch structure (thiếu: Verification Rules) → migrate
+
+STAMPED ({n}) — legacy khớp structure, vừa ghi template_version:
+  feature/F-001-auth/frd.md          frd    → v2
+  integrations/001-checkout/spec.md  spec   → v1
+
+UP-TO-DATE ({n}): {đếm, liệt kê path ngắn gọn hoặc gập lại nếu nhiều}
+
+Bước tiếp theo (nếu có out-dated):
+  - /artifact-migrate [path]
+```
+
+---
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "Cứ stamp hết cho gọn rồi tính sau" | Stamp nhầm artifact lệch structure = giấu luôn nó khỏi audit lần sau. Chỉ stamp khi structure khớp chắc chắn. |
+| "Audit luôn tiện migrate luôn" | Hai trách nhiệm khác nhau. Audit chỉ phát hiện; migrate (đổi structure) là `/artifact-migrate` với dry-run + confirm. |
+| "Thiếu version thì coi như out-dated hết" | Sai — legacy khớp structure chỉ là chưa stamp, không phải lỗi thời. Phải đối chiếu structure trước khi kết luận. |
+| "Artifact có thêm `#### NFR AC` mà template không có → lệch → out-dated" | Sai — template là skeleton tối thiểu; thừa sub-section/nội dung là authoring bình thường. Conformance là quan hệ bao hàm: section bắt buộc còn đó → conform. Chỉ thiếu/đổi-tên/đổi-format mới là out-dated. |
+
+## Red Flags
+
+- Stamp `template_version` cho artifact mà chưa đối chiếu structure với template.
+- Tự sửa structure / nội dung artifact (vượt phạm vi — đó là migration skill).
+- Flag out-dated chỉ vì artifact có thêm sub-section / nội dung ngoài template (thừa ≠ lỗi thời; chỉ thiếu/đổi-tên/đổi-format mới tính).
+- Audit/stamp artifact đóng băng: `.specs/archive/`, `.specs/removed/`, hoặc integration folder có spec.md `status: done` (immutable record — bỏ qua).
+- Đọc version từ một manifest/cache thay vì đọc thẳng frontmatter template.
+
+## Verification
+
+- [ ] Scope resolve đúng từ argument (1 type / list / mọi type)
+- [ ] Current version đọc thẳng từ frontmatter template tại `.claude/templates/...` (không manifest)
+- [ ] Bỏ qua `.specs/archive/`, `.specs/removed/`, `*.bak.*`, file không khớp type map, và integration folder có spec.md `status: done`
+- [ ] Versioned: `==` → up-to-date; `!=` → out-dated `(vX → vY)` → migrate
+- [ ] Unversioned: conformance là quan hệ bao hàm (artifact chứa đủ structure bắt buộc; thừa sub-section/nội dung không khai báo remove KHÔNG phải lỗi thời); 2 dấu hiệu out-dated = thiếu required heading / section `migrations.remove` còn sót
+- [ ] Conform → stamp; out-dated → tóm tắt đúng dấu hiệu (thiếu required heading gì / section deprecated nào còn sót). Lưu ý: presence-check KHÔNG bắt format-update (blind spot unversioned)
+- [ ] Có confirm trước khi ghi stamp; stamp chỉ thêm field `template_version`, không đụng nội dung khác
+- [ ] KHÔNG migrate / không sửa structure artifact
+- [ ] Report phân nhóm out-dated / stamped / up-to-date + bước tiếp theo

package/skills/artifact-migrate/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: artifact-migrate
+description: Migrate artifact trong .specs/ lên structure template mới nhất. Generic cho mọi type. Tự chạy /artifact-audit (classify-only, scoped) để phát hiện out-dated, rồi áp delta từ block `migrations` của template — add section thiếu, remove section deprecated, update format section (vd ASCII→Mermaid) — set template_version = current. Tương tác: confirm add/remove/update, hỏi carry-over khi rename, section nội dung mới thì interview hoặc NEEDS_CLARIFY (không bịa). Single-artifact, KHÔNG cascade. Nhận tùy chọn 1 artifact (path); không có arg → quét toàn bộ, migrate từng cái có confirm + skip.
+---
+
+# artifact-migrate
+
+## Overview
+
+Đưa một artifact (hoặc toàn bộ) **lỗi thời** lên đúng structure của template mới nhất, rồi cập nhật `template_version`. Đây là vế **fix** đối xứng với `/artifact-audit` (vế **detect**).
+
+Cơ chế (xem `conventions.md` §7 Template Versioning):
+- **Required section hiện tại** = body `##` headings của template (deterministic theo level; `###` = instance).
+- **Delta giữa các version** = đọc từ block `migrations` của template: mỗi entry `to: N` ghi `add` (section thêm) + `remove` (section bỏ) + `update` (section giữ nhưng đổi format/cách thể hiện, vd ASCII → Mermaid). `remove` và `update` không suy lại được từ body → block `migrations` là nguồn duy nhất.
+- Migrate **single-artifact, KHÔNG cascade**. ID format đổi (hiếm, cross-artifact) → xử lý tay theo `note`.
+
+## When to Use
+
+- Sau `git pull` kit mới, `/artifact-audit` báo có artifact out-dated → migrate chúng lên template mới.
+- Onboarding repo cũ: artifact legacy thiếu version / lệch structure.
+- Sau khi bump `template_version` một template → migrate các artifact cùng type.
+
+## When NOT to Use
+
+- Chỉ muốn **biết** artifact nào lỗi thời (không sửa) → `/artifact-audit`.
+- Muốn đổi **nội dung** artifact (thêm US, đổi AC) → integration changeset (`/spec-new`) hoặc edit tay.
+- Working tree đang dirty → commit/stash trước (skill rollback dựa git, không tạo `.bak`).
+
+---
+
+## Type → template map
+
+Resolve type theo **filename** (giống `/artifact-audit` — integration artifact không có field `type`). Mỗi type map tới đúng một template tại `.claude/templates/...`:
+
+`prd.md`→`main/prd-template.md` · `domain.md`→`main/domain-template.md` · `sad.md`→`main/sad-template.md` · `frd.md`→`main/feature/frd-template.md` · `fdd.md`→`main/feature/fdd-template.md` · `tsd.md`→`main/feature/tsd-template.md` · `crd.md`→`main/component/crd-template.md` · `cdd.md`→`main/component/cdd-template.md` · `spec.md`→`integrations/spec-template.md` · `tech.md`→`integrations/tech-template.md` · `test.md`→`integrations/test-template.md` · `plan.md`→`integrations/plan-template.md` · `todo.md`→`integrations/todo-template.md` · `techdebt.md`→`integrations/techdebt-template.md`
+
+File không khớp map → bỏ qua.
+
+---
+
+## Process
+
+### Bước 0: Resolve scope
+
+- **ARGUMENT là path tới 1 artifact** → migrate riêng nó. Nếu artifact thuộc integration folder đã `done` (spec.md `status: done`) hoặc nằm trong `.specs/archive`/`.specs/removed` → **DỪNG**, báo "artifact đóng băng (immutable record) — không migrate".
+- **Không có ARGUMENT** → quét `.specs/main/**` + `.specs/integrations/**`, áp **đúng skip list của `/artifact-audit`** (bỏ archive/removed, `*.bak.*`, và **integration folder có spec.md `status: done`**).
+
+### Bước 1: Pre-flight — working tree clean
+
+Chạy `git status --porcelain`. Output không rỗng → **DỪNG**:
+> ⛔ Working tree không clean. Skill không tạo `.bak` — rollback dựa git. Hãy commit/stash trước rồi chạy lại.
+
+Không phải git repo → cảnh báo, yêu cầu confirm (default no) vì không rollback được.
+
+### Bước 2: Detect — tự chạy `/artifact-audit` (classify-only, scoped)
+
+Dùng **chính conformance check của `/artifact-audit`** (presence-check, conventions §7) làm bước phát hiện — một nguồn phán đoán duy nhất, không tự cài lại logic. Scoped theo Bước 0:
+- Có arg → audit đúng artifact/type đó.
+- Không arg → audit toàn bộ scope.
+
+Audit chạy **classify-only** ở đây: chỉ phân loại, **không tự stamp/confirm** (migrate sẽ điều phối mọi ghi vào một luồng confirm). Kết quả mỗi artifact:
+- **up-to-date** (versioned, version `==` template) → bỏ qua. Target đơn lẻ → **no-op sớm**, thoát.
+- **legacy-conformant** (thiếu version nhưng đủ required `##`, không dính `migrations.remove`) → chỉ cần **stamp** version (không đổi structure).
+- **out-dated** (versioned `!=` template, HOẶC unversioned thiếu required `##`, HOẶC còn section trong `migrations.remove`) → cần migrate structure.
+
+Không arg → in danh sách phân nhóm trước, rồi xử lý **từng artifact một, có confirm + cho skip** (không bulk-auto).
+
+### Bước 3: Lập transform plan cho từng artifact
+
+Resolve type→template, đọc template: `template_version` hiện tại + block `migrations` + body `##` headings.
+
+Gộp delta các entry `to:` > version artifact (hoặc tất cả nếu artifact unversioned):
+
+1. **Sections cần ADD** = required `##` của template mà artifact **thiếu**. (Phát hiện bằng so `##` body, deterministic; `migrations.add` để tham khảo delta.)
+2. **Sections cần REMOVE** = section trong **`migrations.remove`** mà artifact **còn chứa**.
+3. **Sections cần UPDATE format** = section trong **`migrations.update`** (giữ section, đổi cách thể hiện — vd ASCII → Mermaid). Section vẫn còn → không add/remove; chỉ transform format theo mô tả `change`. (Không suy được từ presence-check → bắt buộc dựa `migrations.update`.)
+4. **Rename phát hiện được** khi một `remove` (tên cũ) đi kèm một `add` (tên mới) trong cùng entry — đánh dấu để hỏi carry-over content.
+5. **ID format** (nếu `note` đề cập, cross-artifact) → liệt kê để người dùng sửa tay; skill không tự remap.
+
+### Bước 4: Dry-run + confirm (một luồng)
+
+Trình bày cho user **trước khi ghi**:
+- sections sẽ ADD (kèm skeleton lấy từ body template) + sections sẽ REMOVE (kèm reason).
+- sections sẽ UPDATE format → show **nội dung hiện tại** + **đề xuất bản chuyển format** (vd ASCII diagram → Mermaid tương ứng), giữ nguyên ngữ nghĩa.
+- cặp rename phát hiện được → hỏi: "carry-over nội dung từ {cũ} sang {mới}?".
+- artifact legacy-conformant trong scope → sẽ stamp version (gộp vào cùng confirm).
+
+User confirm (toàn bộ / từng item / skip artifact). **Section nội dung mới** (vd Verification Rules) → **interview user điền** hoặc chèn `**[NEEDS_CLARIFY]**` — **KHÔNG tự bịa nội dung**. Với UPDATE format: chuyển *cách thể hiện*, **không bịa thêm/bớt thông tin** so với bản cũ; phần không chắc → giữ + `[NEEDS_CLARIFY]`.
+
+### Bước 5: Apply (atomic mỗi artifact)
+
+- Chèn section ADD theo đúng thứ tự body template; nếu là rename + user đồng ý carry-over → move nội dung từ section cũ sang.
+- Xóa section REMOVE (đã confirm).
+- Áp UPDATE format: thay nội dung section bằng bản chuyển format đã confirm (giữ section + ngữ nghĩa).
+- **Giữ nguyên** mọi sub-section / content tác giả **không nằm trong `remove`/`update`** (superset rule).
+- Set frontmatter `template_version` = current.
+- Nếu template có `## Change History` (main artifact) → append entry, operation = `manual`:
+  ```markdown
+  ### {YYYY-MM-DD} — manual — migrate
+
+  - **Migration**: v{cũ} → v{current} qua /artifact-migrate (add: {...}; remove: {...}; update: {...})
+  ```
+- **Single-artifact, KHÔNG cascade.** Apply fail → rollback bằng git (`git checkout -- {file}`); báo user.
+
+### Bước 6: Report
+
+```
+ARTIFACT MIGRATE — scope: {file | all}
+
+MIGRATED ({n}):
+  feature/F-002-payment/frd.md    v0 → v1   +User Flows, −Components Consumed, ~System Overview (ASCII→Mermaid)
+STAMPED ({n}) — legacy conform, chỉ set version:
+  feature/F-001-auth/frd.md       → v1
+SKIPPED / up-to-date ({n})
+
+{nếu có} NEEDS_CLARIFY còn lại:
+  feature/F-002-payment/frd.md → Verification Rules (chờ điền)
+{nếu có} Cần sửa tay (ID remap theo note):
+  ...
+```
+
+---
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "Tự đoán nội dung cho section mới cho nhanh" | Section nội dung mới = quyết định của BA/owner. Bịa = sai mà không ai review. Interview hoặc NEEDS_CLARIFY. |
+| "Section thừa chắc là rác, xóa luôn" | Chỉ xóa section nằm trong `migrations.remove`. Thừa khác là content tác giả → giữ (superset). |
+| "Format đổi thì xóa section rồi thêm lại" | remove+add làm **mất nội dung**. Format-update giữ section + ngữ nghĩa, chỉ chuyển cách thể hiện (dùng op `update`). |
+| "Chuyển format thì tiện viết lại nội dung cho đẹp" | UPDATE chỉ đổi *cách thể hiện*, KHÔNG thêm/bớt thông tin. Phần không chắc → giữ + NEEDS_CLARIFY. |
+| "Migrate tiện remap ID luôn" | Không có op remap; cascade đã bỏ. ID đổi (hiếm) ghi ở `note`, người dùng sửa tay. |
+| "Khỏi chạy audit, tự check structure cho nhanh" | Phải dùng audit classify-only → một nguồn phán đoán duy nhất, không lệch giữa hai skill. |
+
+## Red Flags
+
+- Bịa nội dung cho section ADD thay vì interview / NEEDS_CLARIFY.
+- Xóa section không nằm trong `migrations.remove` (vi phạm superset).
+- Tự remap ID / đụng tới artifact khác (migrate là single-artifact, không cascade).
+- Chạy khi working tree dirty (mất đường rollback).
+- Migrate artifact đóng băng: integration folder đã `done`, `.specs/archive`, `.specs/removed` (immutable record — phải skip).
+- Migrate artifact đã up-to-date (phải no-op sớm).
+- Tự cài lại logic detect thay vì dùng audit classify-only.
+
+## Verification
+
+- [ ] Pre-flight: working tree clean (hoặc user confirm khi không phải git repo)
+- [ ] Detect bằng `/artifact-audit` classify-only, scoped theo target; version `==` → up-to-date → no-op sớm; `!=` → migrate
+- [ ] Required `##` thiếu → ADD (skeleton từ body template); section `migrations.remove` còn sót → REMOVE (confirm)
+- [ ] Section `migrations.update` → chuyển format (giữ section + ngữ nghĩa); show cũ + đề xuất mới, confirm; KHÔNG thêm/bớt thông tin
+- [ ] Rename (remove+add) → hỏi carry-over content; section nội dung mới → interview / NEEDS_CLARIFY (KHÔNG bịa)
+- [ ] Giữ content tác giả không nằm trong `remove`/`update` (superset)
+- [ ] Set `template_version` = current; main artifact có Change History entry operation `manual`/migrate
+- [ ] Single-artifact, KHÔNG cascade; ID remap (nếu có) chỉ báo để sửa tay
+- [ ] Không arg → liệt kê trước, migrate từng cái có confirm + skip
+- [ ] Apply fail → rollback git; user được thông báo

package/skills/plan/SKILL.md

@@ -118,7 +118,7 @@ Invoke `planning-and-task-breakdown` với context đã load. Skill đó sẽ th
 
 ### plan.md
 
-Dùng `.claude/templates/integrations/plan-template.md` làm skeleton, điền nội dung từ breakdown vào từng section.
+Dùng `.claude/templates/integrations/plan-template.md` làm skeleton, điền nội dung từ breakdown vào từng section. Frontmatter lấy `template_version` từ template (xem `conventions.md` §7).
 
 **Lưu ý format:**
 - Task ID dùng `·` (middle dot), không dùng `—`
@@ -128,7 +128,7 @@ Dùng `.claude/templates/integrations/plan-template.md` làm skeleton, điền n
 
 ### todo.md
 
-Dùng `.claude/templates/integrations/todo-template.md` làm skeleton, điền nội dung từ breakdown vào từng section.
+Dùng `.claude/templates/integrations/todo-template.md` làm skeleton, điền nội dung từ breakdown vào từng section. Frontmatter lấy `template_version` từ template.
 
 ---
 
@@ -146,3 +146,4 @@ Nếu trong quá trình breakdown phát hiện delta cần cập nhật `sad.md`
 - [ ] plan.md có section **Dependency Graph**
 - [ ] Mỗi task có đủ: Mục tiêu / depends / Các bước / Verification
 - [ ] Không viết code trong suốt quá trình
+- [ ] plan.md + todo.md có `template_version` copy từ template tương ứng

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

@@ -221,6 +221,8 @@ 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
 
+**Stamp `template_version`:** frontmatter mỗi `crd.md`/`cdd.md` lấy `template_version` từ template tương ứng (xem `conventions.md` §7).
+
 **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
@@ -304,4 +306,5 @@ Bước tiếp theo:
 - [ ] prd.md Component Index đã được update
 - [ ] sad.md Components table đã được update — danh sách C-XXX khớp với prd.md
 - [ ] Shared Entities đã được cascade vào domain.md (nếu có)
+- [ ] Mỗi crd.md/cdd.md có `template_version` copy từ template tương ứng
 - [ ] NEEDS_CLARIFY items được list đầy đủ trong summary

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

@@ -225,6 +225,8 @@ Sẽ tạo {N} features ({2N} files):
 Ghi tất cả? [y] hoặc review từng file trước [r]:
 ```
 
+**Stamp `template_version`:** frontmatter mỗi `frd.md`/`fdd.md` lấy `template_version` từ template tương ứng (xem `conventions.md` §7).
+
 **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
@@ -307,4 +309,5 @@ grep "NEEDS_CLARIFY" để tìm và fill in khi có thêm context.
 - [ ] Feature không có tests → AC section có NEEDS_CLARIFY rõ ràng
 - [ ] Verification Rules: rule reverse-engineer từ code đã đánh dấu source; field thiếu validation đã NEEDS_CLARIFY; không chứa regex/code/error message
 - [ ] prd.md Feature Index đã được update
+- [ ] Mỗi frd.md/fdd.md có `template_version` copy từ template tương ứng
 - [ ] NEEDS_CLARIFY items được list đầy đủ trong summary

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

@@ -272,7 +272,7 @@ Confirm? [y] Bỏ qua [n] Chỉnh sửa [e]:
 
 ### Bước 9: Save
 
-Tạo `.specs/main/` nếu chưa có. Ghi các files đã được confirm.
+Tạo `.specs/main/` nếu chưa có. Ghi các files đã được confirm. Frontmatter mỗi file (`prd.md`/`domain.md`/`sad.md`) lấy `template_version` từ template tương ứng (xem `conventions.md` §7).
 
 **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:
 
@@ -320,3 +320,4 @@ Format chuẩn — dùng nhất quán trong tất cả artifacts:
 - [ ] sad.md có Architectural Guardrails section
 - [ ] NEEDS_CLARIFY items được list đầy đủ trong summary cuối
 - [ ] User đã confirm từng file trước khi ghi
+- [ ] Mỗi file (prd/domain/sad) có `template_version` copy từ template tương ứng