spec-lite 1.2.2 → 1.3.1

package/package.json

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

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

@@ -266,6 +266,10 @@ Brownfield init hoàn tất! Main artifacts:
   ├── component/       ({N} components, mỗi cái có crd.md + cdd.md)
   └── feature/         ({N} features, mỗi cái có frd.md + fdd.md)
 
+Bước tiếp theo (tùy chọn):
+  /spec-tsd [F-XXX]  → bootstrap tsd.md (Test Spec Document) cho từng feature
+                       — derive 1:1 từ frd.md, có test coverage tracking từ ngày 1.
+
 Để bắt đầu implement, dùng /spec-new để tạo integration đầu tiên.
 grep "NEEDS_CLARIFY" để tìm và fill in khi có thêm context.
 ```

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

@@ -0,0 +1,310 @@
+---
+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) | Insert section placeholder với `<!-- TODO: BA fill in flows -->`. **KHÔNG tự sinh flow.** | None |
+
+---
+
+## Process
+
+### 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, V8)
+
+Đâ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).
+
+#### V8 — User Flows placeholder
+- Sau `## Overview`, insert:
+  > ## User Flows
+  >
+  > <!-- TODO: BA fill in flows. KHÔNG tự sinh — flow là decision của product, không derive được từ AC. -->
+
+---
+
+### 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: 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 cách restore từ backup `.bak.{timestamp}` (skill tạo backup trước khi modify mỗi file).
+
+---
+
+### Bước 7: Report + changelog
+
+Cho mỗi FRD đã migrate:
+
+```
+✓ F-001 — auth
+  Vectors applied: V1, V3, V4 (3 IDs remapped), V5, V6 (8 VRs added)
+  Cascade: fdd.md (3 refs), tsd.md (5 refs), integrations/003 (3 refs)
+  Backup: frd.md.bak.20260519-1430
+
+✓ F-002 — checkout
+  Vectors applied: V5, V6 (5 VRs added)
+  Backup: frd.md.bak.20260519-1430
+```
+
+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-V3, V5, V7, V8 (mechanical, low risk). |
+
+## 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 placeholder bị fill nội dung tự sinh (model bịa flow) — flow là decision của product.
+- 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
+- [ ] Backup `.bak.{timestamp}` còn nguyên
+- [ ] Cascade ID đã re-grep và confirm 0 false-positive
+- [ ] User confirm VR proposal nếu V6 applied