spec-lite 1.4.7 → 1.5.1

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 **main** template mang `template_version` (số nguyên) trong frontmatter; main artifact copy nó lúc được tạo. Khi template đổi structure, main artifact cũ thành "lỗi thời" — hai skill dưới phát hiện và migrate. **Chỉ áp dụng cho main artifacts** (integration artifacts ephemeral nên không versioned). 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 **main 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 main type / list) hoặc mọi main type.
+
+#### `/artifact-migrate [path]`
+Migrate **main artifact** lỗi thời lên structure mới (mọi main 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 main artifact legacy conform)* |
+| `/artifact-migrate` | *(modify in-place main 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.1",
   "description": "Spec-driven development kit for Claude Code",
   "type": "module",
   "bin": {

package/skills/artifact-audit/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: artifact-audit
+description: Audit MAIN artifacts trong .specs/main/ xem có lỗi thời so với template không (chỉ main artifacts — prd/domain/sad/frd/fdd/tsd/crd/cdd; integration artifacts ngoài scope). 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 main type làm scope (vd `frd`, `frd,crd`); không có arg → audit mọi main type.
+---
+
+# artifact-audit
+
+## Overview
+
+Trả lời một câu hỏi: **main artifact nào trong `.specs/main/` đã lỗi thời so với template mới nhất?**
+
+> **Scope = chỉ main artifacts** (`prd`, `domain`, `sad`, `frd`, `fdd`, `tsd`, `crd`, `cdd` — đều nằm dưới `.specs/main/`). Integration artifacts (`spec`, `tech`, `test`, `plan`, `todo`, `techdebt` dưới `.specs/integrations/`) **không** thuộc scope của skill này — chúng là ephemeral và immutable sau khi `done`, không audit/migrate theo version.
+
+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` (cho mọi main 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 main type cụ thể (`/artifact-audit frd`) hoặc mọi main type (`/artifact-audit`).
+- Sau khi bump `template_version` của một template → tìm mọi main artifact giờ thành `out-dated`.
+- Onboarding repo cũ → stamp version cho main 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 main artifact resolve theo **filename**. 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` |
+
+**Chỉ main artifacts.** Integration artifacts (`spec`, `tech`, `test`, `plan`, `todo`, `techdebt`) **không** thuộc scope — gặp file integration thì bỏ qua. File không khớp bảng (vd `notes.md`, `*.bak`) → cũng bỏ qua.
+
+---
+
+## Process
+
+### Bước 0: Resolve scope
+
+- **ARGUMENT là 1 main type hoặc list** (vd `frd`, `frd,crd`) → chỉ audit các type đó. Type lạ hoặc type integration (`spec`/`tech`/`test`/`plan`/`todo`/`techdebt`, không có trong map) → cảnh báo và bỏ qua type đó.
+- **Không có ARGUMENT** → audit **mọi** main 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 **chỉ** main artifacts trong `.specs/main/**` (prd, domain, sad, và feature/component artifacts).
+
+**Bỏ qua:**
+- Toàn bộ `.specs/integrations/**` — integration artifacts ngoài scope skill này (ephemeral + immutable sau `done`; không audit/migrate theo version).
+- `.specs/archive/**`, `.specs/removed/**`, file `*.bak.*`, file không khớp type map.
+
+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 main | frd, crd}
+Current template versions: prd v1 · domain v1 · sad v1 · frd v2 · crd 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
+  component/C-001-core/crd.md        crd    → 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 ngoài scope: bất kỳ file nào trong `.specs/integrations/` (integration artifacts ngoài scope), `.specs/archive/`, `.specs/removed/` — bỏ qua hết.
+- Đọc version từ một manifest/cache thay vì đọc thẳng frontmatter template.
+
+## Verification
+
+- [ ] Scope = **chỉ main artifacts** (`.specs/main/**`); resolve đúng từ argument (1 main type / list / mọi main type)
+- [ ] Current version đọc thẳng từ frontmatter template tại `.claude/templates/...` (không manifest)
+- [ ] Bỏ qua toàn bộ `.specs/integrations/`, `.specs/archive/`, `.specs/removed/`, `*.bak.*`, và file không khớp type map
+- [ ] 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,159 @@
+---
+name: artifact-migrate
+description: Migrate MAIN artifact trong .specs/main/ lên structure template mới nhất (chỉ main artifacts — prd/domain/sad/frd/fdd/tsd/crd/cdd; integration artifacts ngoài scope). 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 main artifact (path); không có arg → quét mọi main artifact, migrate từng cái có confirm + skip.
+---
+
+# artifact-migrate
+
+## Overview
+
+Đưa một main artifact (hoặc toàn bộ main artifacts) **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**).
+
+> **Scope = chỉ main artifacts** (`prd`, `domain`, `sad`, `frd`, `fdd`, `tsd`, `crd`, `cdd` — đều dưới `.specs/main/`). Integration artifacts (`spec`, `tech`, `test`, `plan`, `todo`, `techdebt`) **không** thuộc scope — ephemeral + immutable sau `done`, không migrate theo version.
+
+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 của main artifact theo **filename** (giống `/artifact-audit`). 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`
+
+**Chỉ main artifacts.** Integration artifacts (`spec`/`tech`/`test`/`plan`/`todo`/`techdebt`) ngoài scope → bỏ qua. File không khớp map → cũng bỏ qua.
+
+---
+
+## Process
+
+### Bước 0: Resolve scope
+
+- **ARGUMENT là path tới 1 main artifact** → migrate riêng nó. Nếu path là integration artifact (`.specs/integrations/...`) → **DỪNG**, báo "integration artifact ngoài scope — chỉ migrate main artifacts". Nếu 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 **chỉ** `.specs/main/**`, áp **đúng skip list của `/artifact-audit`** (bỏ toàn bộ `.specs/integrations/`, archive/removed, `*.bak.*`).
+
+### 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.
+- Main artifact có `## Change History` ở cuối → 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 ngoài scope: bất kỳ file nào trong `.specs/integrations/` (integration artifacts ngoài scope), `.specs/archive`, `.specs/removed` (phải skip / DỪNG).
+- 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
+
+- [ ] Scope = **chỉ main artifacts** (`.specs/main/**`); arg là integration artifact → DỪNG, no-arg chỉ quét `.specs/main/**`
+- [ ] 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 copy từ template (plan.md là integration artifact — **không** mang `template_version`; versioning chỉ áp dụng cho main artifacts, 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 copy từ template (todo.md là integration artifact — không mang `template_version`).
 
 ---
 
@@ -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 (integration) KHÔNG mang `template_version` (versioning chỉ cho main artifacts)

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. (spec.md là integration artifact — **không** mang `template_version`; versioning chỉ áp dụng cho main artifacts, 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)
+- [ ] Main artifact create (frd/crd mới) có `template_version` copy từ template; artifact update giữ nguyên version cũ. spec.md (integration) KHÔNG mang `template_version`

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`. (tech.md là integration artifact — **không** mang `template_version`; versioning chỉ áp dụng cho main artifacts, 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)
+- [ ] Main artifact create (cdd/fdd mới) có `template_version` copy từ template; artifact update giữ nguyên version cũ. tech.md (integration) KHÔNG mang `template_version`

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`. (test.md là integration artifact — **không** mang `template_version`; versioning chỉ áp dụng cho main artifacts, 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)
+- [ ] Main artifact tsd.md create có `template_version` copy từ template; tsd.md update giữ nguyên version cũ. test.md (integration) KHÔNG mang `template_version`

package/skills/spec-tsd/SKILL.md

@@ -183,7 +183,7 @@ Hiển thị draft đầy đủ — chưa ghi file.
 
 ### Bước 6: Save
 
-Ghi `.specs/main/feature/{F-XXX}-{slug}/tsd.md` với status `draft` (feature-level artifact có lifecycle riêng, không phải `approved` — QC còn fill placeholders nên status `draft` cho đến khi đầy đủ).
+Ghi `.specs/main/feature/{F-XXX}-{slug}/tsd.md` với status `draft` (feature-level artifact có lifecycle riêng, không phải `approved` — QC còn fill placeholders nên status `draft` cho đến khi đầy đủ). Frontmatter lấy `template_version` từ `tsd-template.md` (xem `conventions.md` §7).
 
 Nếu overwrite — file backup `tsd.md.bak.{timestamp}` đã tạo ở Bước 2.
 
@@ -238,3 +238,4 @@ Trước khi ghi file:
 - [ ] Priority deterministic theo bảng 4.3
 - [ ] Nếu overwrite: tsd.md.bak.{timestamp} đã được tạo
 - [ ] QC đã confirm draft
+- [ ] Frontmatter có `template_version` copy từ `tsd-template.md`

package/skills-overview.md

@@ -220,34 +220,35 @@ Nhóm skill dọn dẹp / migrate artifacts hiện có sau khi template được
 
 | Command | Reads | Writes |
 | --- | --- | --- |
-| `/spec-frd-update` | `feature/*/frd.md`, `frd-template.md` | `feature/*/frd.md`, cascade: `fdd.md`, `tsd.md`, `integrations/*/spec.md`, `tech.md`, `test.md` |
+| `/artifact-audit [type]` | `.specs/main/**` artifacts, `.claude/templates/main/*-template.md` | *(báo cáo; + stamp `template_version` cho main artifact legacy conform)* |
+| `/artifact-migrate [path]` | `.specs/main/**` artifacts, `.claude/templates/main/*-template.md` (block `migrations`) | main artifact được migrate (structure + `template_version`) |
 
-### `/spec-frd-update`
+### `/artifact-audit [type]`
 
-Migrate frd.md hiện có lên format mới nhất của `templates/main/feature/frd-template.md`. Dùng cho repo đã chạy `/spec-brownfield-feature` hoặc `/spec-new` từ trước, frd.md sinh ra theo template cũ.
+Phát hiện **main artifact** lỗi thời so với template (xem `conventions.md` §7 Template Versioning). So `template_version` của artifact với `template_version` đọc thẳng từ template tại `.claude/templates/main/` — không manifest, không cache. **Chỉ main artifacts** (`prd`/`domain`/`sad`/`frd`/`fdd`/`tsd`/`crd`/`cdd`); integration artifacts ngoài scope.
 
-**8 migration vectors** detect tự động:
+**Scope:** argument là 1 main type (`/artifact-audit frd`) hoặc list (`frd,crd`); không có arg → audit mọi main type. Type resolve theo **filename**.
 
-| Vector | Action | Risk |
-|---|---|---|
-| V1 | Fix Mermaid syntax `[{...}]` → `["..."]` | None |
-| V2 | Insert "Flow numbering stable" note | None |
-| V3 | Rename `Feature-level AC` → `Feature AC` + 4 nhóm chuẩn | Low |
-| V4 | Rename `AC-F{NNN}-` (Feature AC) → `FAC-F{NNN}-` (counter riêng) + cascade refs | **HIGH** |
-| V5 | Insert US/AC stability notes | None |
-| V6 | Propose Verification Rules từ User Stories → user approve → insert | Medium |
-| V7 | Move `Components Consumed` → `Dependencies > Components Used` | Low |
-| V8 | Derive Mermaid flows từ User Stories → propose → user approve → insert | Medium |
+**Phân loại mỗi artifact:**
+- Có `template_version` → `==`: **up-to-date**; `!=`: **out-dated** `(vX → vY)` → migrate.
+- Thiếu version (legacy) → presence-check (đủ required `##` + không còn section `migrations.remove`): conform → **stamp** `template_version` (có confirm); lệch → **out-dated** + tóm tắt phần thiếu.
 
-**Workflow:** Pre-flight git clean check → discover & classify → per-FRD context load → apply mechanical vectors (V1/V2/V3/V5/V7) → V4 dry-run preview với cascade impact → confirm → V6 propose VR → confirm → V8 propose Flows → confirm → validate → report.
+**Ranh giới:** chỉ phát hiện + stamp legacy conform. **KHÔNG migrate** — đổi structure là việc của `/artifact-migrate`. Bỏ qua toàn bộ `.specs/integrations/`, `.specs/archive/`, `.specs/removed/`.
 
-**Cảnh báo:**
-- V4 mặc định dry-run, in remap table + cascade diff trước khi ghi.
-- V6 luôn propose-then-approve, không auto-apply (model dễ bịa rule).
-- V8 luôn propose-then-approve — model derive flow từ US journey grouping, BA phải review để catch glue step bịa hoặc grouping sai.
-- KHÔNG tạo file `.bak` — rollback dùng `git checkout -- {file}`. Pre-flight yêu cầu working tree clean.
+### `/artifact-migrate [path]`
 
-**No-op safe:** nếu mọi FRD đã clean, skill báo và dừng — không ghi gì.
+Migrate **main artifact** lỗi thời lên structure template mới nhất, cho mọi main type (vế **fix** đối xứng với `/artifact-audit` vế **detect**). Integration artifacts ngoài scope.
+
+**Scope:** arg = 1 main artifact (path) → migrate riêng nó; không arg → quét mọi main artifact trong `.specs/main/`, migrate từng cái có confirm + skip.
+
+**Quy trình:** pre-flight git clean → **tự chạy `/artifact-audit` classify-only (scoped)** để phát hiện out-dated (up-to-date → no-op sớm) → đọc block `migrations` của template lấy delta `add`/`remove`/`update` → dry-run + confirm → apply (set `template_version` = current; main artifact thêm Change History `manual`/migrate).
+
+**Quy tắc:**
+- **ADD** = required `##` thiếu (skeleton từ body template); section nội dung mới → interview hoặc `NEEDS_CLARIFY`, **KHÔNG bịa**.
+- **REMOVE** = section trong `migrations.remove` còn sót (có confirm); giữ content tác giả khác (superset).
+- **UPDATE** = section trong `migrations.update` — giữ section + ngữ nghĩa, chỉ đổi **format/cách thể hiện** (vd ASCII → Mermaid); show cũ + đề xuất mới, confirm; KHÔNG thêm/bớt thông tin. (Không presence-check được → chỉ bắt qua version compare.)
+- Rename (remove+add) → hỏi carry-over nội dung.
+- **Single-artifact, KHÔNG cascade.** ID remap (hiếm) → ghi ở `note`, sửa tay. Rollback dùng git (không `.bak`).
 
 ---
 

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

@@ -4,6 +4,10 @@ type: cdd
 status: draft
 owner: "{Tech Lead / Senior Dev}"
 component_id: "{Component ID, ví dụ C-001}"
+template_version: 1
+migrations:
+  - to: 1
+    note: "baseline"
 referenced_by:
   - conventions.md > 3. Main Artifacts > 3.2 Component level > cdd.md > Cấu trúc
   - skills/spec-tech/SKILL.md > Process > Cascade Proposals > component cdd.md

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

@@ -4,6 +4,10 @@ type: crd
 status: draft
 owner: "{BA / Tech Lead}"
 component_id: "{Component ID từ PRD Component Index, ví dụ C-001}"
+template_version: 1
+migrations:
+  - to: 1
+    note: "baseline"
 referenced_by:
   - conventions.md > 3. Main Artifacts > 3.2 Component level > crd.md > Cấu trúc
   - skills/spec-new/SKILL.md > Process > Bước 5: Write — sinh draft > component/{C-XXX}/crd.md

package/templates/main/domain-template.md

@@ -3,6 +3,10 @@ id: domain
 type: domain
 status: draft
 owner: "{BA/Domain Expert}"
+template_version: 1
+migrations:
+  - to: 1
+    note: "baseline"
 referenced_by:
   - conventions.md > 3. Main Artifacts > 3.1 Product level > domain.md > Cấu trúc
   - skills/spec-prd/SKILL.md > Process > Bước 5: Save (scaffold domain.md skeleton)

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

@@ -4,6 +4,10 @@ type: fdd
 status: draft
 owner: "{Tech Lead / Senior Dev}"
 feature_id: "{Feature ID}"
+template_version: 1
+migrations:
+  - to: 1
+    note: "baseline"
 referenced_by:
   - conventions.md > 3. Main Artifacts > 3.3 Feature level > fdd.md > Cấu trúc
   - skills/spec-tech/SKILL.md > Process > Bước 4: Write — sinh draft > Cascade Proposals > fdd.md

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

@@ -4,6 +4,10 @@ type: frd
 status: draft
 owner: "{BA}"
 feature_id: "{Feature ID từ PRD Feature Index}"
+template_version: 1
+migrations:
+  - to: 1
+    note: "baseline"
 referenced_by:
   - conventions.md > 3. Main Artifacts > 3.3 Feature level > frd.md > Cấu trúc
   - skills/spec-frd/SKILL.md > Process > Bước 5: Write — sinh draft
@@ -158,7 +162,8 @@ Tham chiếu đến `.specs/main/component/{C-XXX}-...`.
 ## Open Questions
 
 <!-- Các câu hỏi cần làm rõ trong interview / với stakeholder trước khi proceed.
-     Cũng dùng để note component candidate chưa carve (xem skills/spec-frd). Xóa section nếu không còn câu hỏi nào. -->
+     Cũng dùng để note component candidate chưa carve (xem skills/spec-frd).
+     Section required-emptyable: GIỮ heading; để trống (không có bullet) nếu không còn câu hỏi nào. -->
 
 - [ ] {câu hỏi cần clarify} — {ai trả lời / khi nào}
 

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

@@ -5,6 +5,10 @@ status: draft
 owner: "{QC}"
 feature_id: "{Feature ID — match frd.md}"
 frd_ref: "feature/{F-XXX}-{slug}/frd.md"
+template_version: 1
+migrations:
+  - to: 1
+    note: "baseline"
 referenced_by:
   - conventions.md > 3. Main Artifacts > 3.3 Feature level > tsd.md > Cấu trúc
 ---

package/templates/main/prd-template.md

@@ -4,6 +4,10 @@ type: prd
 status: draft
 owner: "{PM/BA}"
 project_name: "{tên dự án}"
+template_version: 1
+migrations:
+  - to: 1
+    note: "baseline"
 referenced_by:
   - conventions.md > 3. Main Artifacts > 3.1 Product level > prd.md > Cấu trúc
   - skills/spec-prd/SKILL.md > Process > Bước 1: Kiểm tra preconditions

package/templates/main/sad-template.md

@@ -3,6 +3,10 @@ id: sad
 type: sad
 status: draft
 owner: "{Tech Lead / Architect}"
+template_version: 1
+migrations:
+  - to: 1
+    note: "baseline"
 referenced_by:
   - conventions.md > 3. Main Artifacts > 3.1 Product level > sad.md > Cấu trúc
   - skills/spec-sad/SKILL.md > Process > Bước 1: Kiểm tra preconditions

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

@@ -1,398 +0,0 @@
----
-name: spec-frd-update
-description: Migrate frd.md hiện có lên cấu trúc template mới nhất — fix Mermaid syntax, rename Feature AC → FAC (counter riêng), thêm Verification Rules section, cascade ID remap qua fdd/tsd/test/spec/tech. Dùng cho repo đã onboard SDD từ trước khi template thay đổi.
----
-
-# spec-frd-update
-
-## Overview
-
-Migrate các file `.specs/main/feature/{F-XXX}-{slug}/frd.md` hiện có sang **format mới nhất** của [templates/main/feature/frd-template.md](../../templates/main/feature/frd-template.md).
-
-Skill này **chỉ làm migration mechanical + propose** — không phải BA interview. Mọi quyết định nội dung mới (Verification Rules content) đều cần user approve trước khi ghi.
-
-## When to Use
-
-- Repo đã chạy `/spec-brownfield-feature` hoặc `/spec-new` từ lâu, frd.md sinh ra theo template cũ — giờ template đã update.
-- Sau khi `git pull` kit mới và phát hiện frd.md hiện tại thiếu section so với template mới.
-- Audit định kỳ để đảm bảo mọi frd.md tuân thủ cùng format.
-
-## When NOT to Use
-
-- frd.md chưa tồn tại → dùng `/spec-brownfield-feature` (brownfield) hoặc `/spec-new` (greenfield).
-- Muốn thay đổi **nội dung** frd (thêm US, đổi AC text) → edit thủ công hoặc qua integration changeset.
-- Template chưa thay đổi gì so với khi frd.md được tạo → skill này sẽ no-op, không có gì để làm.
-
----
-
-## Cảnh báo về ID cascade
-
-Skill này có thể **rename Feature AC ID** từ `AC-F{NNN}-{seq}` sang `FAC-F{NNN}-{seq}` (counter riêng, reset từ 001). Các file sau có thể reference những ID này và cần cascade:
-
-- `feature/{F-XXX}/fdd.md` — section Verification Implementation
-- `feature/{F-XXX}/tsd.md` — Traceability Matrix, Test Cases
-- `integrations/*/spec.md` — Cascade Proposals, Changes blocks
-- `integrations/*/tech.md` — Changes blocks
-- `integrations/*/test.md` — Coverage table
-
-**Mặc định dry-run** — skill in toàn bộ ID remap + diff trước khi ghi, user xác nhận từng feature một.
-
----
-
-## Migration vectors
-
-Skill detect từng frd hiện tại thuộc "era" nào và apply vectors tương ứng:
-
-| Vector | Detect bằng | Action | Risk |
-|---|---|---|---|
-| **V1 Mermaid syntax** | Có pattern `\[\{.+?\}\]` trong code block mermaid | Rewrite `[{X}]` → `["X"]` | None |
-| **V2 Flow stability note** | Section `## User Flows` thiếu chuỗi "Flow numbering" | Insert dòng note sau intro | None |
-| **V3 Section rename** | Có heading `## Feature-level Acceptance Criteria` | Rename → `## Feature Acceptance Criteria` + insert 4-group block + Out-of-scope note | Low |
-| **V4 FAC ID renumber** | Trong section Feature AC, IDs dùng prefix `AC-F` (chứ không phải `FAC-F`) | Remap → `FAC-F{NNN}-001..N` + cascade references trong repo | **HIGH** |
-| **V5 US/AC stability notes** | Section User Stories thiếu chuỗi "ID stable" | Insert 2 dòng note | None |
-| **V6 VR section** | Không có heading `## Verification Rules` | Propose VR table từ User Stories → user approve → insert | Medium |
-| **V7 Components Used location** | Section `## Components Consumed` đứng riêng (era pre-84d7303) | Move xuống `## Dependencies` thành subsection `### Components Used` | Low |
-| **V8 User Flows missing** | Không có heading `## User Flows` (era pre-84d7303) | Derive Mermaid flows từ User Stories → propose → user approve → insert. 1 flow / nhóm US liên quan theo journey logic. **Bắt buộc — không có option skip; FRD migration không hoàn tất nếu thiếu User Flows.** | Medium |
-
----
-
-## Process
-
-### Bước 0: Pre-flight — working tree clean
-
-Chạy `git status --porcelain`. Nếu output không rỗng (có file modified / untracked / staged):
-
-```
-⛔ Working tree không clean. Skill không tạo file backup `.bak` — rollback dựa vào git.
-Hãy commit hoặc stash thay đổi hiện tại trước khi chạy `/spec-frd-update`, rồi chạy lại.
-
-Files dirty:
-  M .specs/main/feature/F-001-auth/frd.md
-  ?? notes.md
-```
-
-Dừng hoàn toàn. Skill chỉ proceed khi `git status` clean — đảm bảo mọi change sau đó đều thuộc migration, dễ revert bằng `git checkout -- {path}` hoặc `git restore`.
-
-Nếu repo không phải git repo → cảnh báo và yêu cầu confirm:
-> ⚠ Thư mục này không phải git repo. Skill không tạo file backup. Nếu apply sai, không thể rollback. Tiếp tục? (yes / no — default no)
-
----
-
-### Bước 1: Discover & classify
-
-Quét `.specs/main/feature/*/frd.md`. Với mỗi file:
-
-1. Parse headings và frontmatter.
-2. Run detection cho V1–V8.
-3. Build classification table.
-
-Display kết quả:
-
-```
-Detected FRDs:
-
-  [1] F-001 — auth          | Era: 2026-04 | Vectors needed: V1, V3, V4 (3 IDs), V5, V6
-  [2] F-002 — checkout      | Era: 2026-05 | Vectors needed: V5, V6
-  [3] F-003 — refund        | Era: current | Vectors needed: — (đã clean)
-  [4] F-004 — admin-panel   | Era: pre-flows | Vectors needed: V1, V3, V4 (2 IDs), V5, V6, V7, V8
-
-Tổng: 4 FRDs · 3 cần migration · 1 đã sạch.
-```
-
-Hỏi user scope:
-
-```
-Migrate FRDs nào?
-  [A] Tất cả cần migration (3 files)
-  [1] Chỉ F-001
-  [2] Chỉ F-002
-  ...
-  [N] Chọn subset (nhập danh sách số, vd: "1 4")
-  [X] Hủy
-
-Lựa chọn:
-```
-
-Nếu không có FRD nào cần migration → thông báo `Tất cả frd.md đã clean. No-op.` rồi dừng.
-
----
-
-### Bước 2: Load context per FRD
-
-Với mỗi FRD đã chọn, load các file sau (chỉ những gì cần thiết — KHÔNG load conventions.md, KHÔNG load source code):
-
-| File | Bắt buộc | Mục đích |
-|---|---|---|
-| `.specs/main/feature/{F-XXX}-{slug}/frd.md` | ✓ | File cần migrate |
-| [templates/main/feature/frd-template.md](../../templates/main/feature/frd-template.md) | ✓ | Target structure — copy text cho V2/V3/V5 |
-| `.specs/main/feature/{F-XXX}-{slug}/fdd.md` | nếu tồn tại | Cascade target cho V4 (AC→FAC rename) |
-| `.specs/main/feature/{F-XXX}-{slug}/tsd.md` | nếu tồn tại | Cascade target cho V4 |
-| `.specs/main/domain.md` (Shared Entities block) | optional | Cho V6 — match field name với entity glossary để pick semantic type consistent |
-
-**KHÔNG load:**
-- `conventions.md` — template đã self-contained, load là thừa
-- Source code — frd là WHAT, derive VR từ US/AC chứ không phải implementation
-- `tech.md`/`cdd.md` — có thể contaminate VR bằng tech detail (regex, varchar(255)…)
-
----
-
-### Bước 3: Apply mechanical vectors (V1, V2, V3, V5, V7)
-
-Đây là các vector **không cần model reasoning** — pure text manipulation. Apply tuần tự, không hỏi user.
-
-#### V1 — Mermaid syntax fix
-- Regex trong mỗi code block ```mermaid: `\[\{([^}]+)\}\]` → `["$1"]`
-- Edge case: keep escaped braces nguyên vẹn, chỉ replace pattern `[{...}]` ở edge label / node label.
-
-#### V2 — Flow stability note
-- Sau bullet intro của `## User Flows` (dòng `{Mỗi flow là một Mermaid…}`), insert:
-  > Flow numbering **stable** — không renumber khi xóa flow. Nếu xóa Flow 1, Flow 2 giữ nguyên số (không tái sử dụng số 1).
-
-#### V3 — Section rename + structure
-- Rename heading `## Feature-level Acceptance Criteria` → `## Feature Acceptance Criteria`.
-- Replace block intro (dòng "Criteria áp dụng cho toàn bộ feature — không gắn với story…") bằng full block từ template (4 nhóm + Out-of-scope + Format note). Copy nguyên văn từ frd-template.md.
-
-#### V5 — US/AC stability notes
-- Sau dòng `US ID format: ...` trong User Stories section, đảm bảo có 2 dòng:
-  > US ID format: `US-F{NNN}-{seq}` — đánh số tăng dần toàn feature. ID **stable** — không tái sử dụng seq khi xóa, không renumber.
-  >
-  > Story AC ID format: `AC-F{NNN}-{seq}` — đánh số tăng dần toàn feature (không reset giữa các story). ID **stable** — không tái sử dụng seq khi xóa, không renumber.
-
-#### V7 — Components Used relocation
-- Detect `## Components Consumed` section.
-- Cắt nội dung bảng, xóa heading.
-- Trong `## Dependencies`, ensure có 2 subsections: `### Feature Dependencies` (giữ bảng cũ nếu có) và `### Components Used` (chèn bảng vừa cắt).
-
----
-
-### Bước 4: V4 — AC → FAC renumber với cascade
-
-**Đây là vector cao risk nhất.** Mỗi feature làm tuần tự, không batch.
-
-#### 4.1 Parse Feature AC IDs
-- Trong section `## Feature Acceptance Criteria` (đã rename ở V3), extract tất cả ID dạng `AC-F{NNN}-{seq}`.
-- List: `[AC-F001-002, AC-F001-005, AC-F001-007]` (gap OK).
-
-#### 4.2 Build remap table
-- Cũ → mới: reset counter từ 001, giữ thứ tự xuất hiện.
-- Ví dụ:
-  ```
-  AC-F001-002  →  FAC-F001-001
-  AC-F001-005  →  FAC-F001-002
-  AC-F001-007  →  FAC-F001-003
-  ```
-
-#### 4.3 Scan cascade references
-- Grep toàn `.specs/` cho từng ID cũ.
-- **CRITICAL**: chỉ remap những match THUỘC Feature AC (Bước 4.1 list). KHÔNG đụng Story AC trùng namespace `AC-F{NNN}-{seq}` — đây là string overlap nhưng khác counter.
-- Tạo bảng impact:
-  ```
-  Cascade impact for F-001:
-    feature/F-001-auth/fdd.md          3 refs
-    feature/F-001-auth/tsd.md          5 refs
-    integrations/003-otp-flow/spec.md  1 ref
-    integrations/003-otp-flow/test.md  2 refs
-  ```
-
-#### 4.4 Dry-run preview
-Hiển thị:
-- Full remap table
-- Per-file diff snippet (3 dòng context mỗi ref)
-- Confirm prompt:
-
-```
-Apply remap cho F-001? (yes / no / skip-feature)
-  yes          → apply tất cả changes (frd.md + cascade files)
-  no           → hủy V4 cho feature này, vẫn giữ AC-F prefix
-  skip-feature → bỏ qua toàn bộ migration cho F-001
-```
-
-#### 4.5 Apply
-- Edit `frd.md`: rewrite IDs trong section Feature AC.
-- Edit từng cascade file: replace exact ID strings (sử dụng Edit với context dòng để tránh false-positive).
-- Validate: re-grep ID cũ, phải về 0 trong Feature AC scope; Story AC giữ nguyên.
-
----
-
-### Bước 5: V6 — Generate Verification Rules section
-
-**Vector tiêu tốn LLM nhất.** Run nếu V6 detected.
-
-#### 5.1 Load minimal context
-- Section `## User Stories` của FRD đó (đã chứa AC).
-- Optional: `domain.md > Shared Entities` block (nếu có field match entity name).
-
-**KHÔNG load:** code, fdd.md, tech.md. Mục đích: tránh contamination bằng HOW.
-
-#### 5.2 Derive rules
-Quét từng AC trong User Stories:
-- Identify input action ("nhập email", "submit form", "chọn date", "upload file"…).
-- Extract field name + implicit constraint.
-- Output bảng VR theo format template:
-  - **Type**: semantic (`string`, `email`, `enum<A|B|C>`, …) — không bao giờ concrete tech type.
-  - **Rule**: human-readable diễn đạt, không regex.
-  - **Refs**: trỏ tới US/AC source.
-- Sub-rule phức tạp (vd: password = letter + digit + symbol) → tách flat thành nhiều ID.
-
-#### 5.3 Propose & approve
-Hiển thị bảng VR đề xuất:
-
-```
-Proposed Verification Rules for F-001:
-
-| ID | Field | Type | Required | Rule | Refs |
-|----|-------|------|----------|------|------|
-| VR-F001-001 | email | email | yes | định dạng email hợp lệ | US-F001-001 |
-| VR-F001-002 | password | string | yes | tối thiểu 8 ký tự | US-F001-001 |
-...
-
-Apply? (yes / edit / skip-vr)
-  yes      → insert vào frd.md
-  edit     → user trả lời text-edit rules nào cần sửa
-  skip-vr  → giữ FRD không có VR section
-```
-
-#### 5.4 Insert
-- Insert `## Verification Rules` section ngay trước `## Scope` (theo thứ tự template).
-- Copy nguyên block intro + quy ước từ template, chỉ replace bảng bằng nội dung derived.
-
----
-
-### Bước 6: V8 — Derive User Flows section
-
-**Run nếu V8 detected. Bắt buộc — không có option skip.** Propose-then-approve giống V6 nhưng loop cho tới khi user approve: model derive draft, user duyệt (yes) hoặc trả phản hồi (edit) → model regenerate. FRD migration chỉ hoàn tất khi `## User Flows` đã insert.
-
-#### 6.1 Load minimal context
-- Section `## Overview` của FRD (framing scope + actors).
-- Section `## User Stories` (đã chứa AC — source của journey steps).
-
-**KHÔNG load:** code, fdd.md, tech.md, sequence diagrams hiện có. Mục đích: flow ở frd là **user-facing journey** (WHAT), không phải implementation sequence (HOW thuộc fdd).
-
-#### 6.2 Derive flows
-Nhóm User Stories theo journey logic, mỗi journey → 1 Mermaid flowchart:
-
-- **Grouping rule:** US chia sẻ chung trigger / actor / postcondition → cùng 1 flow. Vd `US-001 Đăng ký` + `US-002 Xác thực email` → 1 flow "Onboarding"; còn `US-003 Reset password` là journey riêng.
-- **Mermaid structure:**
-  - Start node = trigger (user action mở đầu, từ Given của AC đầu tiên).
-  - Decision nodes = branch từ AC (happy / error paths).
-  - End node = postcondition (từ Then của AC cuối).
-  - Edge label = user action hoặc system response (từ When / Then).
-- **Naming:** `Flow {N}: {tên ngắn}` — N đánh số từ 1 theo thứ tự xuất hiện trong frd.
-- **Mermaid syntax:** dùng `["..."]` chứ KHÔNG `[{...}]` (V1 convention).
-
-#### 6.3 Propose & approve
-
-Hiển thị draft full mermaid blocks (chưa ghi file):
-
-```
-Proposed User Flows for F-001:
-
-Flow 1: Onboarding (đăng ký + xác thực email)
-  Spans: US-F001-001, US-F001-002
-  ```mermaid
-  flowchart TD
-    A["User mở trang Sign up"] --> B["Nhập email + password"]
-    B --> C{"Validation pass?"}
-    C -->|yes| D["Gửi email xác thực"]
-    C -->|no| E["Hiển thị lỗi"]
-    D --> F["User click link trong email"]
-    F --> G["Account active"]
-  ```
-
-Flow 2: Login
-  Spans: US-F001-003
-  ```mermaid
-  ...
-  ```
-
-Apply? (yes / edit)
-  yes   → insert vào frd.md
-  edit  → user góp ý flow nào cần sửa (vd: "Flow 1 thiếu nhánh email đã tồn tại") → regenerate draft, loop lại
-
-User Flows là **bắt buộc** — không có option skip. Nếu user muốn dừng toàn bộ migration cho feature này, dùng "skip-feature" ở Bước 4 hoặc abort skill (Ctrl-C) trước khi V8 chạy.
-```
-
-#### 6.4 Insert
-- Insert section `## User Flows` ngay sau `## Overview` (theo thứ tự template).
-- Copy intro + **Flow numbering stable** note (V2 convention) từ template, sau đó list các Mermaid blocks theo flow numbering.
-
----
-
-### Bước 7: Validate
-
-Sau khi apply hết vectors cho một FRD, chạy check:
-
-- [ ] `## Feature Acceptance Criteria` (không phải Feature-**level**)
-- [ ] Không còn ID `AC-F{NNN}-` trong scope Feature AC (chỉ có `FAC-F{NNN}-`)
-- [ ] Story AC vẫn dùng `AC-F{NNN}-` (không bị remap nhầm)
-- [ ] Mermaid blocks không còn pattern `[{...}]`
-- [ ] Có heading `## Verification Rules` (nếu V6 applied)
-- [ ] Có heading `## User Flows` với ít nhất 1 Mermaid flowchart (bắt buộc — nếu V8 detected mà section vẫn vắng thì migration chưa hoàn tất)
-- [ ] VR Rule column không chứa keyword UI copy: "error message", "vui lòng", "hint", "tooltip"
-- [ ] Frontmatter `referenced_by` trỏ tới `3.3 Feature level` (không phải `3.2`)
-
-Nếu check fail → rollback bằng `git checkout -- {file}` (skill không tạo backup vật lý vì git history đã đảm nhận vai trò này). Yêu cầu working tree clean trước khi chạy skill — nếu dirty, skill báo lỗi và dừng để tránh trộn lẫn change của user với change của migration.
-
----
-
-### Bước 8: Report + changelog
-
-Cho mỗi FRD đã migrate:
-
-```
-✓ F-001 — auth
-  Vectors applied: V1, V3, V4 (3 IDs remapped), V5, V6 (8 VRs added), V8 (2 flows added)
-  Cascade: fdd.md (3 refs), tsd.md (5 refs), integrations/003 (3 refs)
-
-✓ F-002 — checkout
-  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]`:
-
-```
-- chore: migrate frd.md format cho {N} features (vectors: ...)
-```
-
----
-
-## Common Rationalizations
-
-| Rationalization | Reality |
-|---|---|
-| "Format mới optional, frd cũ vẫn dùng được" | Đúng cho đọc thủ công. Nhưng `/spec-test` và `/spec-tsd` derive TC theo IDs FAC/VR — frd thiếu sẽ break derivation, fallback bằng placeholder không trace được. |
-| "Tự sinh VR an toàn, model giỏi infer constraint" | Model dễ bịa rule không có trong AC ("password tối thiểu 12 ký tự" khi AC chỉ nói "password hợp lệ"). Luôn propose-then-approve, không auto-apply. |
-| "Skip cascade, chỉ rename trong frd thôi" | Sẽ break tsd.md Traceability Matrix và test.md Coverage. Hoặc cascade full, hoặc skip V4 toàn bộ. |
-| "Migrate batch tất cả cùng lúc cho nhanh" | V4 cascade dễ break — user cần xem diff per-feature. Batch mode chỉ áp dụng cho V1, V2, V3, V5, V7 (mechanical, low risk). V6 và V8 phải propose-then-approve. |
-
-## Red Flags
-
-- Apply V4 không có dry-run preview → user không kịp catch cascade reference sai.
-- VR Rule column chứa regex `^[a-z]+$` hoặc tech type `varchar(255)` — đó là HOW, sai vị trí.
-- V8 flows auto-apply không qua propose-then-approve → model có thể bịa glue step / sai journey grouping mà BA không kịp catch.
-- V8 flow chứa step không trace được lên US nào (model bịa) → BA reject draft và yêu cầu regenerate.
-- Để FRD không có `## User Flows` sau migration vì "draft chưa ổn" → sai. V8 bắt buộc; nếu draft chưa ổn, dùng `edit` loop cho tới khi approve. FRD không có User Flows = migration chưa hoàn tất.
-- V8 Mermaid block dùng syntax `[{...}]` thay vì `["..."]` — vi phạm V1 convention.
-- Validate fail nhưng skip rollback → file ở trạng thái nửa migrate, khó debug sau.
-- Load conventions.md hoặc source code "for safety" → contamination, tốn context, không cải thiện output.
-
-## Verification
-
-Trước khi mark feature done:
-- [ ] Tất cả vectors detected đã apply (hoặc skip có log lý do — riêng V8 KHÔNG được skip)
-- [ ] Validate Bước 6 pass
-- [ ] Working tree clean trước khi skill chạy (git status verified) — rollback dùng git, không có file backup
-- [ ] Cascade ID đã re-grep và confirm 0 false-positive
-- [ ] User confirm VR proposal nếu V6 applied