spec-lite 1.1.12 → 1.1.13

package/package.json

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

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

@@ -128,6 +128,40 @@ Nếu không có tests → AC section sẽ là NEEDS_CLARIFY.
 - Transaction boundaries nếu explicit (`@Transaction`, `queryRunner`)
 - Retry / timeout config nếu detect được
 
+**4e. Verification Rules — reverse-engineer từ code:**
+
+Áp dụng cho mọi input field user nhập trong feature (request body, query param, form field).
+
+Scan và extract rule từ các nguồn sau, ưu tiên từ trên xuống:
+- **Schema declarations**: Zod, Joi, Yup, Pydantic, class-validator decorators (`@IsEmail()`, `@MinLength(8)`...), Mongoose/TypeORM column constraints
+- **Validator middleware / guard**: custom validation function trong middleware, NestJS pipes, FastAPI dependencies
+- **Inline check trong handler/use case**: `if (!email.includes('@')) throw ...`
+- **DB constraint**: migration files với `UNIQUE`, `NOT NULL`, `CHECK`, length limits
+- **Test assertion**: `expect(() => validate(input)).toThrow(...)` → reverse-engineer rule từ test
+
+Convert mỗi rule sang **human-readable diễn đạt** (không copy regex hoặc code nguyên):
+- `@IsEmail()` → "email format hợp lệ"
+- `@MinLength(8)` → "≥ 8 ký tự"
+- `regex: /^[a-zA-Z0-9_]{3,20}$/` → "3-20 ký tự, alphanumeric + `_`"
+- `UNIQUE` constraint → "unique"
+- `@IsOptional()` → đánh `Required: no`
+
+**Type**: derive semantic type (string/integer/email/date/...) từ field type, KHÔNG copy tech type (`varchar(255)`).
+
+**Đánh dấu source** trong note hoặc inline comment: `(extracted from Zod schema)`, `(from DB constraint)`, `(from test assertion)`.
+
+**Auto-assign Rule ID** `VR-F{NNN}-{seq}` cho mỗi rule extract được — tăng dần toàn feature, không reset theo field. Sub-rule phức tạp → tách flat thành nhiều rule riêng, mỗi cái 1 ID.
+
+**Quan trọng — flag cho BA review:**
+- Rule trong code có thể **thiếu** (validation chỉ chạy ở 1 layer, không cover hết) → list những field xuất hiện trong US nhưng không có validation → mark `NEEDS_CLARIFY`.
+- Rule trong code có thể **lệch business intent** → toàn bộ Verification Rules section nên có header note: *"Rules dưới đây reverse-engineer từ code hiện tại. BA cần review và confirm có match business intent không."*
+- Nếu field nào không có validation → fallback sang flow suggest options (xem `spec-new` SKILL.md → "Verification Rules — quy ước sinh") để BA quyết định khi review.
+
+**Cấm:**
+- ❌ Đưa regex / validator code nguyên xi vào bảng (đó là HOW, thuộc `fdd.md`).
+- ❌ Đưa error message / user-facing copy vào bảng (UI copy, không thuộc FRD).
+- ❌ Bỏ qua field có validation chỉ vì rule "có vẻ tầm thường" — vẫn phải ghi để BA confirm.
+
 ---
 
 ### Bước 5: Hỏi clarification — batch
@@ -161,6 +195,7 @@ Với mỗi feature, generate 2 files dùng templates tương ứng:
 - User flows: Mermaid flowchart cho happy case và edge cases (infer từ test chains / UI navigation, NEEDS_CLARIFY nếu không detect được)
 - User stories (đánh dấu source)
 - Acceptance criteria (extract từ tests nếu có, NEEDS_CLARIFY nếu không)
+- **Verification Rules**: bảng `Field | Type | Required | Rule | Refs` từ Bước 4e. Thêm header note nhắc BA review match business intent. Field thiếu validation → NEEDS_CLARIFY.
 - Scope: In scope từ detected routes/actions; Out of scope → NEEDS_CLARIFY
 - Dependencies:
   - Feature Dependencies: feature-to-feature dependencies nếu detect được
@@ -246,5 +281,6 @@ grep "NEEDS_CLARIFY" để tìm và fill in khi có thêm context.
 - [ ] Components consumed list reference đúng C-XXX IDs từ Component Index
 - [ ] User stories và AC detect được đánh dấu source `(inferred)` hoặc `(from tests)`
 - [ ] 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
 - [ ] NEEDS_CLARIFY items được list đầy đủ trong summary

package/skills/spec-new/SKILL.md

@@ -68,8 +68,9 @@ Sections hiện có:
   [2] User Flows
   [3] Feature-level Acceptance Criteria
   [4] User Stories
-  [5] Scope (In Scope / Out of Scope)
-  [6] Dependencies (Feature Dependencies + Components Used)
+  [5] Verification Rules
+  [6] Scope (In Scope / Out of Scope)
+  [7] Dependencies (Feature Dependencies + Components Used)
   [A] All — viết lại toàn bộ từ đầu
   [S] Lên spec từ frd.md hiện tại — frd.md đã đầy đủ, không cần chỉnh
 
@@ -222,7 +223,8 @@ Với từng feature có đề xuất thay đổi:
 **Tạo mới** `specs/main/feature/{F-XXX}-{feature-slug}/frd.md`
 - Dùng khi integration này là lần đầu tiên implement feature này
 - Thư mục đặt tên: `{F-XXX}-{feature-slug}` (ví dụ: `F-001-authentication`)
-- Nội dung đề xuất: User Stories, AC, Components consumed (reference C-XXX) — từ spec.md
+- Nội dung đề xuất: User Flows, Feature-level AC, User Stories, **Verification Rules**, Scope, Components consumed (reference C-XXX) — từ spec.md
+- **Verification Rules**: xem hướng dẫn ở mục "Verification Rules — quy ước sinh" bên dưới
 
 **Cập nhật** `specs/main/feature/{F-XXX}-{feature-slug}/frd.md`
 - Dùng khi frd.md đã tồn tại và integration này bổ sung thêm stories hoặc criteria
@@ -236,8 +238,9 @@ Sections hiện có:
   [2] User Flows
   [3] Feature-level Acceptance Criteria
   [4] User Stories
-  [5] Scope (In Scope / Out of Scope)
-  [6] Dependencies (Feature Dependencies + Components Used)
+  [5] Verification Rules
+  [6] Scope (In Scope / Out of Scope)
+  [7] Dependencies (Feature Dependencies + Components Used)
   [A] All — viết lại toàn bộ từ đầu
 
 Chọn section cần cập nhật (có thể chọn nhiều, ví dụ: 2 3):
@@ -248,6 +251,57 @@ Sau khi user chọn → chỉ sinh nội dung cho section đó. Nếu chọn `A`
 Không được bỏ qua feature nào — kể cả feature `Done` vẫn phải đánh giá xem spec mới có làm thay đổi scope không.
 ```
 
+#### Verification Rules — quy ước sinh
+
+Áp dụng khi sinh hoặc cập nhật section `Verification Rules` trong `frd.md`.
+
+**Nguyên tắc:**
+- Verification Rules là **business decision** — BA owns. Agent **KHÔNG** được tự assert rule.
+- Agent đóng vai **option-suggester**, không phải decision-maker.
+
+**Quy trình:**
+
+1. Scan các User Stories vừa confirm. Detect mọi input field user nhập (form field, query param, request body...).
+
+2. Với mỗi field, **suggest 2-4 phương án validation** dựa trên field name + semantic type + common patterns. Luôn kèm option `Custom` và `TBD`.
+
+   Ví dụ với field `password`:
+   ```
+   Verification rules cho `password` (type: string)?
+     [A] ≥ 8 ký tự, có chữ hoa + số                   (baseline common)
+     [B] ≥ 12 ký tự, có chữ hoa + số + ký tự đặc biệt (strict)
+     [C] ≥ 6 ký tự, không yêu cầu thêm                (loose, internal tool)
+     [D] Custom — BA mô tả tay
+     [E] TBD — quyết định sau
+   ```
+
+3. BA chọn → agent **auto-assign Rule ID** `VR-F{NNN}-{seq}` và ghi vào bảng `Verification Rules` của frd.md. Chọn `Custom` → hỏi tiếp. Chọn `TBD` → ghi `TBD` ở cột Rule (vẫn assign ID để referencable) và list ra ở cuối draft để BA follow-up.
+
+**Quy ước Rule ID (`VR-F{NNN}-{seq}`):**
+- `NNN` = feature ID, `seq` = số thứ tự 3 chữ số tăng dần toàn feature, **không reset** theo field.
+- Khi **tạo mới frd.md**: bắt đầu `VR-F{NNN}-001`, tăng tuần tự theo thứ tự rule được BA confirm.
+- Khi **update frd.md hiện có**: đọc bảng Verification Rules hiện tại, lấy `max(seq)` + 1 làm seq tiếp theo. **Không tái sử dụng** ID đã từng tồn tại (kể cả rule đã bị xóa). **Không renumber** rule cũ.
+- Sub-rule phức tạp (ví dụ password complexity 4 điều kiện) → **tách flat** thành nhiều rules riêng, mỗi cái 1 ID (`VR-F001-005`, `VR-F001-006`...). Không dùng hierarchy (`-005a`, `-005b`).
+
+**Heuristic suggest theo field name (gợi ý, không bắt buộc):**
+
+| Field name pattern | Categories cần hỏi |
+|---|---|
+| `email`, `*_email` | format, required, unique (nếu là identifier) |
+| `password`, `pwd` | min length, complexity, max length |
+| `username`, `login` | length range, allowed chars, unique |
+| `*_at`, `*_date`, `birthday` | format, range (past/future), timezone |
+| `age`, `quantity`, `*_count` | type (integer), range (min/max), positive |
+| `phone`, `mobile` | format (E.164 / local), length |
+| `url`, `link` | format, allowed protocols |
+| `*_id`, `id` | type (UUID/integer), exists in domain |
+
+**Cấm:**
+- ❌ Tự điền rule vào bảng mà chưa hỏi BA.
+- ❌ Suggest chỉ 1 option và mặc định chấp nhận.
+- ❌ Đưa regex, validator code, hoặc error message vào bảng (regex/validator là HOW thuộc `fdd.md`; error/hint message là UI copy ở artifact khác).
+- ❌ Dùng tech type (`varchar(255)`, `int32`...) — phải dùng semantic type (`string`, `integer`, `email`, `enum<...>`...).
+
 Hiển thị draft cho user xem — **chưa ghi file**.
 
 ---

package/skills/spec-tech/SKILL.md

@@ -85,6 +85,7 @@ Load các file sau:
 - `specs/main/sad.md` — đọc Tech Stack và Architectural Guardrails
 - `specs/main/domain.md` — đọc Glossary và Shared Entities
 - `specs/main/component/{C-XXX}-{slug}/cdd.md` — cho mỗi component trong frontmatter `components` (nếu cdd.md tồn tại)
+- `specs/main/feature/{F-XXX}-{slug}/frd.md` — cho mỗi feature trong frontmatter `features` (đọc `Verification Rules` để sinh `Verification Implementation` trong fdd.md)
 - `specs/main/feature/{F-XXX}-{slug}/fdd.md` — cho mỗi feature trong frontmatter `features` (nếu fdd.md tồn tại)
 
 Tóm tắt context và surface assumptions:
@@ -190,10 +191,12 @@ Liệt kê **tất cả** features liên quan trong frontmatter và đánh giá:
 
 **Tạo mới** `specs/main/feature/{F-XXX}-{feature-slug}/fdd.md`
 - Khi feature gắn với integration nhưng chưa có fdd.md
-- Nội dung: Inter-component data flow, Orchestration, Cross-component invariants — từ tech.md (chỉ phần inter-component, không lặp internal design của component)
+- Nội dung: Inter-component data flow, Orchestration, Cross-component invariants, **Verification Implementation** — từ tech.md (chỉ phần inter-component, không lặp internal design của component)
+- **Verification Implementation**: với mỗi rule trong `frd.md > Verification Rules` của feature này, sinh row trong bảng `Rule ID | Rule (short) | Layer | Owning component | Error propagation`. Reference rule bằng `VR-F{NNN}-{seq}` ID (lấy nguyên từ FRD, không tạo ID mới). Rule (short) copy ngắn gọn từ FRD để row tự đọc được. Layer = client/gateway/service (có thể combine). Owning component reference C-XXX. KHÔNG đưa regex/validator code/error message wording vào — đó thuộc `cdd.md` của owning component (cascade riêng) hoặc UI copy artifact. Bỏ qua nếu FRD không có Verification Rules.
 
 **Cập nhật** `specs/main/feature/{F-XXX}-{feature-slug}/fdd.md`
 - Khi fdd.md đã tồn tại, ghi rõ thay đổi flow nào
+- Nếu integration thêm/đổi rule trong FRD → cập nhật bảng Verification Implementation tương ứng
 
 Bỏ block fdd.md nếu integration không gắn với feature nào (`features: []`).
 ```

package/skills-overview.md

@@ -135,7 +135,7 @@ Component Index và Feature Index **để placeholder** — sẽ được điề
 
 **Bước 1 — Discover:** scan use case files, route groups, test describe blocks, page/screen dirs → detect feature candidates → present cho user confirm/adjust → assign F-XXX IDs.
 
-**Bước 2 — Deep scan từng feature:** user stories (infer từ use case + routes + tests) · AC (extract từ test assertions, đánh dấu source) · components consumed (map sang C-XXX) · inter-component call chain (cho fdd.md).
+**Bước 2 — Deep scan từng feature:** user stories (infer từ use case + routes + tests) · AC (extract từ test assertions, đánh dấu source) · components consumed (map sang C-XXX) · inter-component call chain (cho fdd.md) · **verification rules** (reverse-engineer từ Zod/Joi/Pydantic/class-validator schemas, DB constraints, validator middleware, test assertions — convert sang human-readable, flag cho BA review).
 
 **Bước 3 — Generate batch:** frd.md + fdd.md cho tất cả. Batch clarification tối đa 5 câu.
 
@@ -204,7 +204,7 @@ Tạo `specs/integrations/{slug}/tech.md` cho một integration. Chạy bởi DE
 
 Nếu integration đã có `tech.md` → hỏi confirm trước khi ghi đè.
 
-Context load: `spec.md` + `sad.md` + `domain.md` + `cdd.md` (cho mỗi component bị touched) + `fdd.md` (cho mỗi feature liên quan).
+Context load: `spec.md` + `sad.md` + `domain.md` + `cdd.md` (cho mỗi component bị touched) + `frd.md` (đọc Verification Rules để sinh Verification Implementation trong fdd.md) + `fdd.md` (cho mỗi feature liên quan).
 
 **Interview** (4 phần, tuần tự): Solution Overview · Data Model Changes · Interface Changes · Implementation Notes
 

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

@@ -50,3 +50,22 @@ Các invariant cần đảm bảo xuyên component — consistency, transactiona
 
 - {ví dụ: Order chỉ được đánh dấu `paid` sau khi Payment component confirm thành công}
 - {ví dụ: Inventory phải được reserve trước khi Order được tạo, rollback nếu Payment fail}
+
+## Verification Implementation
+
+Map mỗi rule trong `frd.md > Verification Rules` sang implementation strategy ở cấp inter-component. Section này KHÔNG chứa internal detail của validation (regex cụ thể, validator library, error code) — những thứ đó thuộc về `cdd.md` của component sở hữu logic. Section này chỉ trả lời: rule chạy **ở đâu** trong flow, do component nào enforce, và lỗi propagate ra sao.
+
+Bỏ section nếu feature không có Verification Rules.
+
+| Rule ID | Rule (short) | Layer | Owning component | Error propagation |
+| --- | --- | --- | --- | --- |
+| `VR-F001-001` | username 3-20 ký tự, alphanumeric + `_` | client + gateway | `{C-XXX}-api-gateway` | 400 `INVALID_USERNAME` → UI inline error |
+| `VR-F001-002` | username unique | service | `{C-YYY}-user-service` | 409 `USERNAME_TAKEN` → UI inline error |
+| `VR-F001-003` | password ≥ 8 ký tự, có chữ hoa + số | client + gateway | `{C-XXX}-api-gateway` | 400 `WEAK_PASSWORD` → UI inline error |
+
+Quy ước:
+- **Rule ID**: reference tới `VR-F{NNN}-{seq}` trong `frd.md > Verification Rules`. ID là source of truth — nếu lệch giữa FRD và FDD, FRD đúng.
+- **Rule (short)**: copy ngắn gọn từ FRD để row tự đọc được, không phải nhảy file. Nếu rule dài → giữ short ở đây, full description ở FRD.
+- **Layer**: `client` (UI validation trước submit), `gateway` (API gateway / request validator), `service` (business logic component), hoặc kết hợp (`client + gateway` cho double-check). Layer ảnh hưởng UX (inline vs server round-trip).
+- **Owning component**: component nào chịu trách nhiệm enforce. Implementation chi tiết (regex, validator code, error class) nằm trong `cdd.md` của component đó.
+- **Error propagation**: HTTP status + error code semantic + cách render cho user. Wording cụ thể của error message thuộc UI copy artifact, không ở đây.

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

@@ -24,19 +24,19 @@ referenced_by:
 
 ```mermaid
 flowchart TD
-    A([{Điểm bắt đầu}]) --> B[{Bước 1}]
-    B --> C{Điều kiện?}
-    C -- Happy case --> D[{Bước 2 — thành công}]
-    C -- Edge case --> E[{Xử lý lỗi / nhánh phụ}]
-    D --> F([{Kết thúc thành công}])
-    E --> G([{Kết thúc thất bại / fallback}])
+    A(["Điểm bắt đầu"]) --> B["Bước 1"]
+    B --> C{"Điều kiện?"}
+    C -- Happy case --> D["Bước 2 — thành công"]
+    C -- Edge case --> E["Xử lý lỗi / nhánh phụ"]
+    D --> F(["Kết thúc thành công"])
+    E --> G(["Kết thúc thất bại / fallback"])
 ```
 
 ### Flow 2: {Tên luồng phụ / edge case lớn} *(nếu có)*
 
 ```mermaid
 flowchart TD
-    A([{Điểm bắt đầu}]) --> B[{...}]
+    A(["Điểm bắt đầu"]) --> B["..."]
 ```
 
 ## Feature-level Acceptance Criteria
@@ -87,6 +87,25 @@ US ID format: `US-F{NNN}-{seq}` — đánh số tăng dần toàn feature.
 
 ---
 
+## Verification Rules
+
+Constraint logic áp dụng cho input/data của feature — derive từ các input action mô tả trong User Stories ở trên. Pure WHAT, không chứa UI copy (error message, hint message thuộc về presentation, đặt ở artifact khác).
+
+VR ID format: `VR-F{NNN}-{seq}` — đánh số tăng dần toàn feature (không reset theo field). ID **stable** — đã assign rồi giữ nguyên kể cả khi rule bị xóa (không tái sử dụng seq, không renumber). Nếu xóa rule → ID đó retire, seq mới tiếp tục tăng từ max.
+
+Quy ước:
+- **ID**: `VR-F{NNN}-{seq}` — stable identifier để FDD và test plan reference.
+- **Type**: semantic type, không phải concrete tech type. Dùng `string`, `number`, `integer`, `boolean`, `date`, `datetime`, `email`, `url`, `enum<A|B|C>`, `array<T>`. KHÔNG dùng `varchar(255)`, `int32`, v.v. — đó là HOW.
+- **Required**: `yes` / `no` — field bắt buộc hay optional. Product quyết định.
+- **Rule**: diễn đạt human-readable. KHÔNG viết regex/code cụ thể (đó là HOW, thuộc `fdd.md`). Một field có thể có nhiều rules → mỗi rule một dòng, mỗi dòng 1 ID riêng.
+- **Refs**: link tới US/AC yêu cầu rule này.
+
+Sub-rule phức tạp (vd: password complexity với nhiều điều kiện) → **tách flat** thành nhiều rules riêng biệt, mỗi cái 1 ID, không hierarchy.
+
+| ID | Field | Type | Required | Rule | Refs |
+| --- | --- | --- | --- | --- | --- |
+| `VR-{F_ID}-001` | `{field_name}` | `{semantic_type}` | yes / no | {rule diễn đạt human-readable} | `US-{F_ID}-{seq}` |
+
 ## Scope
 
 ### In Scope

package/templates/main/feature/test-plan-template.md

@@ -0,0 +1,60 @@
+---
+id: "003-assign-todo"
+slug: "assign-todo"
+title: "Assign Todo — Test Plan"
+features: ["F-004"]
+status: draft
+created: 2026-04-21
+---
+
+## Test Strategy
+
+Approach tổng quan: test pyramid distribution, environment setup, fixtures.
+
+## AC Coverage Matrix
+
+| AC ID | Primary Level | Test Case ID(s) | Status |
+|-------|--------------|-----------------|--------|
+| AC-F004-001 | Component | TC-001 | draft |
+| AC-F004-002 | Component | TC-002 | draft |
+| ... |
+
+## Verification Rules Coverage
+
+Mỗi rule trong `frd.md > Verification Rules` của feature phải có **≥ 1 positive test case** (input hợp lệ pass) và **≥ 1 negative test case** (input vi phạm rule bị reject). Nếu rule áp dụng ở nhiều layer (client + gateway, xem `fdd.md > Verification Implementation`) → cover từng layer.
+
+| Rule ID | Layer (từ FDD) | Test Case ID(s) | Status |
+|---------|----------------|-----------------|--------|
+| VR-F004-001 | service | TC-010 (pos), TC-011 (neg) | draft |
+| VR-F004-002 | gateway | TC-012 (neg) | draft |
+| ... |
+
+## Test Cases
+
+### TC-001: Non-owner không thấy assign control
+**Verifies:** AC-F004-001 (primary)
+**Level:** Component test (TodoModal)
+**Setup:**
+- Render TodoModal với prop `isOwner: false`
+**Steps:**
+1. Mở modal
+2. Query assign control
+**Expected:**
+- Assign control không có trong DOM
+**Negative variants:** —
+
+### TC-006: Happy path assign
+**Verifies:** AC-F004-006, AC-F004-007 (primary), AC-F004-008 (supporting)
+**Level:** E2E (Playwright)
+**Setup:**
+- Seed: userA, userB
+- userA login, tạo todo
+**Steps:**
+1. userA mở task detail
+2. Click assign, chọn userB
+3. Confirm
+**Expected:**
+- Modal hiển thị owner = userB
+- Refresh dashboard → card hiển thị userB
+**Verification queries:**
+- DB: `SELECT * FROM todo_history WHERE todo_id=? AND event_type='ASSIGNED'` → 1 row, payload đúng