spec-lite 1.3.0 → 1.3.2

package/package.json

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

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

@@ -0,0 +1,385 @@
+---
+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. | 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.** Propose-then-approve giống V6 — model derive draft, user duyệt trước khi ghi.
+
+#### 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 / skip-flows)
+  yes         → insert vào frd.md
+  edit        → user góp ý flow nào cần sửa (vd: "Flow 1 thiếu nhánh email đã tồn tại")
+  skip-flows  → giữ FRD không có User Flows section
+```
+
+#### 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)
+- [ ] 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)
+```
+
+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.
+- 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)
+- [ ] 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

package/skills-overview.md

@@ -185,6 +185,43 @@ Component Index và Feature Index **để placeholder** — sẽ được điề
 
 ---
 
+## Maintenance — migrate artifacts khi template thay đổi
+
+Nhóm skill dọn dẹp / migrate artifacts hiện có sau khi template được update. Không phải pipeline — chạy ad-hoc khi cần.
+
+| 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` |
+
+### `/spec-frd-update`
+
+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ũ.
+
+**8 migration vectors** detect tự động:
+
+| 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 |
+
+**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.
+
+**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.
+
+**No-op safe:** nếu mọi FRD đã clean, skill báo và dừng — không ghi gì.
+
+---
+
 ## Integration Pipeline — dùng cho cả greenfield và brownfield
 
 Sau khi main artifacts đã sẵn sàng (từ greenfield hoặc brownfield), mọi requirement mới đều đi qua pipeline này.