spec-lite 1.3.1 → 1.3.3

package/package.json

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

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

@@ -52,12 +52,32 @@ Skill detect từng frd hiện tại thuộc "era" nào và apply vectors tươn
 | **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 |
+| **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:
@@ -116,7 +136,7 @@ Với mỗi FRD đã chọn, load các file sau (chỉ những gì cần thiết
 
 ---
 
-### Bước 3: Apply mechanical vectors (V1, V2, V3, V5, V7, V8)
+### 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.
 
@@ -143,12 +163,6 @@ Với mỗi FRD đã chọn, load các file sau (chỉ những gì cần thiết
 - 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
@@ -244,7 +258,67 @@ Apply? (yes / edit / skip-vr)
 
 ---
 
-### Bước 6: Validate
+### 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:
 
@@ -253,28 +327,29 @@ Sau khi apply hết vectors cho một FRD, chạy check:
 - [ ] 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 cách restore từ backup `.bak.{timestamp}` (skill tạo backup trước khi modify mỗi file).
+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 7: Report + changelog
+### 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)
+  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)
-  Backup: frd.md.bak.20260519-1430
 
 ✓ F-002 — checkout
   Vectors applied: V5, V6 (5 VRs added)
-  Backup: frd.md.bak.20260519-1430
 ```
 
+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]`:
 
 ```
@@ -290,21 +365,24 @@ Append vào [changelogs.md](../../changelogs.md) `## [Unreleased]`:
 | "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). |
+| "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 placeholder bị fill nội dung tự sinh (model bịa flow) — flow là decision của product.
+- 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)
+- [ ] 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
-- [ ] Backup `.bak.{timestamp}` còn nguyên
+- [ ] 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

@@ -208,14 +208,15 @@ Migrate frd.md hiện có lên format mới nhất của `templates/main/feature
 | 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 | Insert `User Flows` placeholder (KHÔNG tự sinh flow) | None |
+| V8 | Derive Mermaid flows từ User Stories → propose → user approve → insert | Medium |
 
-**Workflow:** Discover & classify → per-FRD context load → apply mechanical vectors (V1/V2/V3/V5/V7/V8) → V4 dry-run preview với cascade impact → confirm → V6 propose VR → confirm → validate → report.
+**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 chỉ chèn placeholder TODO, không tự sinh flow (flow là decision của product).
+- 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ì.