spec-lite 1.4.7 → 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.7",
+  "version": "1.5.0",
   "description": "Spec-driven development kit for Claude Code",
   "type": "module",
   "bin": {

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

package/skills/spec-frd/SKILL.md

@@ -223,7 +223,7 @@ Dùng `.claude/templates/main/feature/frd-template.md` làm skeleton, điền n
 
 **ID assignment** (luôn là create — frd mới): US `US-F{NNN}-001+`, Story AC `AC-F{NNN}-001+`, Feature AC `FAC-F{NNN}-001+` (counter độc lập với Story AC), VR `VR-F{NNN}-001+`. `NNN` = số của F-XXX. Flow đánh số từ 1.
 
-**Frontmatter** frd mới: theo template, `status: draft`, `owner: BA`, `feature_id: F-XXX`.
+**Frontmatter** frd mới: theo template, `status: draft`, `owner: BA`, `feature_id: F-XXX`, `template_version` copy từ `frd-template.md` (xem `conventions.md` §7 — chỉ set lúc CREATE; thay đổi sau qua `/spec-new` không đụng version).
 
 Hiển thị **toàn bộ draft** cho user — chưa ghi file. Kèm:
 - danh sách component candidate (nếu có) và VR còn `TBD`;
@@ -360,6 +360,7 @@ Bước tiếp theo:
 - [ ] **Create-only gate**: frd.md của feature mục tiêu CHƯA tồn tại; nếu đã có đã redirect `/spec-new`
 - [ ] Feature mục tiêu có trong Index, HOẶC feature mới đơn lẻ đã được user đồng ý register (Bước 1b)
 - [ ] frd.md có đủ 7 core sections (luôn create mới); `Open Questions` chứa câu hỏi clarify + component candidate còn mở, hoặc đã xóa nếu rỗng
+- [ ] Frontmatter có `template_version` copy từ `frd-template.md`
 - [ ] Mỗi User Story có persona + priority + ít nhất 1 AC Given/When/Then
 - [ ] Feature AC dùng ID `FAC-F{NNN}-{seq}` (counter độc lập với `AC-F{NNN}`), Then đo được
 - [ ] Verification Rules đã confirm với BA (không tự assert); không chứa regex/code/error message; semantic type

package/skills/spec-new/SKILL.md

@@ -343,7 +343,7 @@ Chỉ tiến hành Bước 7 sau khi user confirm. Nếu user yêu cầu chỉnh
 
 Tạo thư mục `.specs/integrations/{NNN}-{slug}/` nếu chưa có.
 
-**[7.1] Ghi spec.md** với status `approved` (không phải `draft` — human đã confirm ở Bước 6 chính là approval). Frontmatter `features` và `components` phải được điền theo những gì đã nhận diện ở Bước 2.
+**[7.1] Ghi spec.md** với status `approved` (không phải `draft` — human đã confirm ở Bước 6 chính là approval). Frontmatter `features` và `components` phải được điền theo những gì đã nhận diện ở Bước 2; `template_version` lấy từ `spec-template.md` (xem `conventions.md` §7).
 
 **[7.2] Auto-apply mỗi Changes block** vào main artifact tương ứng. Thứ tự apply (để tránh forward reference): `prd.md` → `domain.md` → `sad.md` → `component/*/crd.md` → `feature/*/frd.md`.
 
@@ -352,7 +352,7 @@ Cho từng block:
 - **Operation=create:**
   - Tạo file mới tại path tương ứng
   - Nội dung = nội dung của Changes block (theo format của template gốc)
-  - Frontmatter của artifact mới: lấy từ template (status `draft` cho artifact mới — separate lifecycle với spec.md)
+  - Frontmatter của artifact mới: lấy từ template, gồm `template_version` (status `draft` cho artifact mới — separate lifecycle với spec.md). `template_version` chỉ stamp ở operation=create; **operation=update KHÔNG đụng** version của artifact hiện có.
 
 - **Operation=update:**
   - Đọc artifact hiện tại
@@ -443,3 +443,4 @@ Sau khi user confirm (Bước 7):
 - [ ] Auto-apply chạy theo thứ tự prd → domain → sad → crd → frd
 - [ ] 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)
+- [ ] Artifact create (spec.md + frd/crd mới) có `template_version` copy từ template; artifact update giữ nguyên version cũ

package/skills/spec-prd/SKILL.md

@@ -279,6 +279,8 @@ 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.
 
+**5b'. Stamp `template_version`:** frontmatter `prd.md` (lúc create) và `domain.md` (lúc scaffold) lấy `template_version` từ template tương ứng (xem `conventions.md` §7 Template Versioning). Lần chạy sau update `prd.md` → giữ nguyên `template_version` hiện có, KHÔNG đụng.
+
 **5c. Append Change History entry** vào mỗi artifact vừa ghi/scaffold (theo `conventions.md` §5.5):
 
 ```markdown
@@ -323,7 +325,7 @@ Bước tiếp theo:
 
 Trước khi kết thúc, kiểm tra:
 
-- [ ] Frontmatter đầy đủ và đúng schema (id, type, version, status, owner, project_name)
+- [ ] Frontmatter đầy đủ và đúng schema (id, type, status, owner, project_name, `template_version`) — `template_version` copy từ template lúc create, update không đụng
 - [ ] Problem Statement từ góc nhìn business, không mention tech stack
 - [ ] Mỗi persona có: tên vai trò, mục tiêu, pain point
 - [ ] Out of Scope có ít nhất 1 item với lý do

package/skills/spec-sad/SKILL.md

@@ -191,7 +191,7 @@ Chỉ ghi file sau khi user confirm. Nếu user yêu cầu chỉnh sửa → c
 
 ### Bước 5: Save
 
-Ghi nội dung đã được confirm vào `.specs/main/sad.md`.
+Ghi nội dung đã được confirm vào `.specs/main/sad.md`. Frontmatter lấy `template_version` từ `sad-template.md` lúc create (xem `conventions.md` §7); lần chạy update sau giữ nguyên, không đụng.
 
 **Change History:** Append entry vào section `## Change History` cuối `sad.md` (theo `conventions.md` §5.5):
 
@@ -246,7 +246,7 @@ Bước tiếp theo:
 
 Trước khi kết thúc, kiểm tra:
 
-- [ ] Frontmatter đầy đủ và đúng schema
+- [ ] Frontmatter đầy đủ và đúng schema (gồm `template_version` copy từ template lúc create; update không đụng)
 - [ ] Architectural Style có lý do gắn với NFRs hoặc constraints
 - [ ] System Overview có diagram + Components table; danh sách C-XXX khớp với `prd.md > Components` (hoặc cả hai cùng rỗng nếu Component Index chưa được điền)
 - [ ] Mỗi tech stack item có lý do chọn rõ ràng

package/skills/spec-tech/SKILL.md

@@ -216,7 +216,7 @@ Chỉ ghi file sau khi user confirm. Nếu user yêu cầu chỉnh sửa → c
 
 ### 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.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`; `template_version` lấy từ `tech-template.md` (xem `conventions.md` §7).
 
 **[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`.
 
@@ -225,7 +225,7 @@ 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)
+  - Frontmatter: lấy từ template, gồm `template_version` (status `draft` cho artifact mới — separate lifecycle với tech.md). `template_version` chỉ stamp ở operation=create; **operation=update KHÔNG đụng** `template_version` của artifact hiện có.
 
 - **Operation=update:**
   - Đọc artifact hiện tại
@@ -315,3 +315,4 @@ 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)
+- [ ] Artifact create (tech.md + cdd/fdd mới) có `template_version` copy từ template; artifact update giữ nguyên version cũ

package/skills/spec-test/SKILL.md

@@ -284,7 +284,7 @@ Chỉ tiến hành Bước 6 sau khi QC confirm.
 
 ### Bước 6: Save + Auto-cascade
 
-**[6.1] Ghi `.specs/integrations/{slug}/test.md`** với status `approved` (không phải `draft` — human đã confirm ở Bước 5 chính là approval). Frontmatter `features` mirror từ `spec.md`.
+**[6.1] Ghi `.specs/integrations/{slug}/test.md`** với status `approved` (không phải `draft` — human đã confirm ở Bước 5 chính là approval). Frontmatter `features` mirror từ `spec.md`; `template_version` lấy từ `test-template.md` (xem `conventions.md` §7).
 
 **[6.2] Auto-apply mỗi Changes block** vào `feature/{F-XXX}/tsd.md` tương ứng. Thứ tự apply: theo thứ tự xuất hiện trong frontmatter `features` (deterministic, không có forward reference giữa các feature tsd.md). Bỏ qua feature có operation `no-op` trong Cascade Summary.
 
@@ -293,7 +293,7 @@ Cho từng block:
 - **Operation=create:**
   - Tạo file `.specs/main/feature/{F-XXX}-{slug}/tsd.md`
   - Nội dung = nội dung của Changes block (theo format `templates/main/feature/tsd-template.md`)
-  - Frontmatter của tsd.md mới: status `draft` (separate lifecycle với integration test.md)
+  - Frontmatter của tsd.md mới: status `draft` + `template_version` copy từ `tsd-template.md` (separate lifecycle với integration test.md). Chỉ stamp ở operation=create; **operation=update KHÔNG đụng** version của tsd.md hiện có.
 
 - **Operation=update:**
   - Đọc tsd.md hiện tại
@@ -381,3 +381,4 @@ Sau khi QC confirm (Bước 6):
 - [ ] 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)
+- [ ] test.md + tsd.md create có `template_version` copy từ template; tsd.md update giữ nguyên version cũ