@longph2102/v-flow 1.5.0

package/templates/plan-template.md

@@ -0,0 +1,308 @@
+# Template: Technical Plan (Kế hoạch kỹ thuật)
+
+> Được tạo bởi **Plan Agent** từ Specification
+> Feature: [TÊN FEATURE]
+> Spec Version: [vX.Y]
+
+> **Profile** — **Full** (mặc định): điền mọi section áp dụng. **Lite** (feature `quickfix`/`hotfix` trong `.flow-state.yaml`): tối thiểu §1 (tổng quan) + §6 (File Changes) + §3.4 (nếu đụng DB); **bỏ qua** §10 NFR, §11 Observability, §13 Tech Decisions, §3.5 Key Queries. `v-flow validate` tự **nới** các nudge này cho feature lite (không cảnh báo thiếu).
+
+## 1. Tổng quan kiến trúc
+
+### 1.1 Tóm tắt
+<!-- Mô tả tổng quan cách triển khai feature — 3-5 câu -->
+
+### 1.2 Diagram kiến trúc
+
+```mermaid
+graph TB
+    subgraph Presentation
+        UI[UI Layer]
+    end
+    subgraph Domain
+        UC[Use Cases]
+        ENT[Entities]
+    end
+    subgraph Data
+        REPO[Repositories]
+        DS[Data Sources]
+    end
+    UI --> UC
+    UC --> ENT
+    UC --> REPO
+    REPO --> DS
+```
+
+### 1.3 Components liên quan
+
+| Component | Mô tả | Mới/Sửa | REQ mapping |
+|-----------|-------|:-------:|------------|
+| | | Mới / Sửa | REQ-xxx |
+
+---
+
+## 2. Tech Stack & Dependencies
+
+### 2.1 Công nghệ sử dụng
+
+| Mục | Lựa chọn | Lý do | Constitution ref |
+|-----|---------|-------|:----------------:|
+| Framework | | | §1.1 |
+| Database | | | §1.1 |
+| Libraries | | | — |
+
+### 2.2 Dependencies mới
+
+<!-- Libraries, packages cần thêm -->
+- [ ] [package@version] — [lý do] — [impact: bundle size/performance]
+
+---
+
+## 3. Data Model
+
+### 3.1 Entities
+
+<!-- Mô tả các entity / table / collection -->
+
+```
+[Entity Name]
+├── field1: type (required) — [business meaning]
+├── field2: type (optional) — [business meaning]
+└── field3: type — [business meaning]
+```
+
+### 3.2 Relationships
+
+```mermaid
+erDiagram
+    ENTITY_A ||--o{ ENTITY_B : "has many"
+    ENTITY_B }|--|| ENTITY_C : "belongs to"
+```
+
+### 3.3 State Machine (nếu có)
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Active : approve
+    Active --> Completed : complete
+    Active --> Cancelled : cancel
+```
+
+### 3.4 Database Migrations (nếu đụng schema)
+
+> Phân biệt rõ **bảng MỚI** vs **ALTER bảng hiện có**. Bắt buộc điền khi feature thay đổi schema — để dev biết thêm bảng/cột nào, không phải đoán.
+
+| Bảng / Collection | New/ALTER | Cột | Kiểu | Null? | Default | Index / Constraint | REQ |
+|-------------------|:---------:|-----|------|:-----:|---------|--------------------|-----|
+| `users` | ALTER | `last_login_at` | timestamp | ✅ | null | — | REQ-S01 |
+| `audit_log` | NEW | `id`, `user_id`, `action`, `created_at` | — | — | — | PK `id`, idx `user_id` | REQ-O01 |
+
+- **DDL thật (up + rollback)** — câu lệnh copy-paste-được để dev KHÔNG phải đoán. DDL là *đặc tả schema* (không phải code logic) nên không vi phạm "plan không chứa code":
+
+```sql
+-- up
+ALTER TABLE users ADD COLUMN last_login_at timestamp NULL;
+CREATE TABLE audit_log (
+  id          bigserial   PRIMARY KEY,
+  user_id     bigint      NOT NULL REFERENCES users(id),
+  action      text        NOT NULL,
+  created_at  timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX idx_audit_log_user_id ON audit_log(user_id);
+
+-- down (rollback)
+DROP TABLE audit_log;
+ALTER TABLE users DROP COLUMN last_login_at;
+```
+> Dùng ORM/migration tool (Prisma, TypeORM, Alembic…)? → ghi lệnh tương đương của tool thay cho SQL thô (vẫn phải có up + down cụ thể).
+
+- **Migration file**: `migrations/[YYYYMMDD]_[tên].sql` (hoặc theo ORM/tool của dự án)
+- **Rollback**: [cách hoàn tác — drop column / drop table / down migration]
+- **Data backfill**: [có cần backfill dữ liệu cũ không? cách làm — bỏ trống nếu không]
+- **Breaking change → Expand-Contract** (zero-downtime): nếu ALTER phá tương thích (đổi/bỏ cột, thêm NOT NULL) → tách 3 bước: **(1) Expand** thêm cột mới nullable, ghi cả cũ+mới → **(2) Migrate** backfill + chuyển đọc sang cột mới → **(3) Contract** bỏ cột cũ ở release sau. Mỗi bước là 1 task `[DB]` riêng.
+
+### 3.5 Truy vấn quan trọng (Key Queries)
+
+> Cho các truy vấn có **access pattern không hiển nhiên**: filter, join, phân trang, soft-delete, aggregate… Ghi **hình dạng** (bảng / predicate chính / index dùng) để dev biết "đi đường nào" — KHÔNG cần câu SQL hoàn chỉnh (giữ nguyên tắc "plan không chứa code logic"). Bỏ qua nếu chỉ CRUD đơn giản theo khóa chính.
+
+| Truy vấn (mục đích) | Bảng | Predicate / Filter chính | Index dùng | Ghi chú |
+|---------------------|------|--------------------------|-----------|---------|
+| Liệt kê bản ghi active (phân trang) | `products` | `WHERE deleted_at IS NULL` + `LIMIT/OFFSET` | `idx_products_deleted_at` | parameterized; KHÔNG string-concat |
+| | | | | |
+
+---
+
+## 4. API Design (nếu có)
+
+### 4.1 Endpoints
+
+| Method | Path | New/Sửa | Mô tả | Auth | Request | Response | REQ |
+|--------|------|:-------:|-------|:----:|---------|----------|-----|
+| | | Mới / Sửa | | ✅/❌ | | | REQ-xxx |
+
+### 4.2 Data Contracts (field-level)
+
+> Field-level cho request/response — KHÔNG cần đợi `--with-api`. Mỗi field: tên / kiểu / bắt buộc / ràng buộc. Lặp block cho mỗi endpoint cần chi tiết. Contract-first (FE+BE) → đóng băng ở `contracts/api-contract.md`.
+
+**`POST /api/x` — Request**
+
+| Field | Kiểu | Bắt buộc | Ràng buộc |
+|-------|------|:--------:|-----------|
+| `email` | string | ✅ | định dạng email |
+| `password` | string | ✅ | ≥ 8 ký tự |
+
+**Response 200**
+
+| Field | Kiểu | Ghi chú |
+|-------|------|---------|
+| `token` | string | JWT access token |
+| `expiresIn` | number | giây |
+
+### 4.3 Error Codes
+
+| Code | HTTP | Mô tả | Khi nào |
+|------|:----:|-------|--------|
+| | | | |
+
+### 4.4 Thay đổi Contract (nếu SỬA API hiện có)
+
+> Khi sửa endpoint đã tồn tại — ghi rõ field thêm/đổi/bỏ và tính tương thích ngược.
+
+| Endpoint | Field | Thay đổi | Trước | Sau | Breaking? |
+|----------|-------|:--------:|-------|-----|:---------:|
+| `POST /api/x` | `status` | Thêm | — | `enum(active,locked)` | Không |
+| | | Thêm/Đổi/Bỏ | | | Có/Không |
+
+---
+
+## 5. UI / Screen Changes (nếu có giao diện)
+
+> Lấy từ **"Mô tả màn hình"** trong spec (mỗi `UC-xx`). Ghi rõ màn hình nào tạo mới / sửa, sửa gì, component/widget nào, các trạng thái, và token tham chiếu từ `DESIGN.md`. Để dev không phải hỏi "sửa màn nào".
+
+### 5.1 Danh sách màn hình
+
+| Màn hình | UC | New/Sửa | Thay đổi | Component / Widget | Trạng thái (empty/loading/error) | DESIGN token |
+|----------|----|:-------:|----------|---------------------|----------------------------------|--------------|
+| LoginPage | UC-01 | Mới | Form đăng nhập | email field, password field, submit btn | loading, error-401 | `button-primary`, `input-default` |
+| ProductList | UC-03 | Sửa | Thêm cột "Trạng thái" + filter | DataTable, FilterBar | empty, loading | `badge-success`, `badge-error` |
+
+### 5.2 Điều hướng (Navigation flow thay đổi)
+
+<!-- Luồng chuyển màn hình mới hoặc bị thay đổi -->
+- `[Màn A]` --(action)--> `[Màn B]`
+
+---
+
+## 6. File Changes
+
+### 6.1 File mới
+
+| File path | Mô tả | LOC ước tính | REQ |
+|-----------|-------|:------------:|-----|
+| | | | REQ-xxx |
+
+### 6.2 File sửa đổi
+
+> Mỗi dòng phải chỉ rõ **vị trí (hàm/class/widget)** và **hiện trạng → mong muốn** — KHÔNG ghi chung chung "cập nhật logic".
+
+| File path | Vị trí (hàm/class) | Loại | Hiện trạng → Mong muốn | Impact | REQ |
+|-----------|--------------------|:----:|------------------------|:------:|-----|
+| `src/auth/service.ts` | `AuthService.login()` | Sửa logic | Trả 200 ngay → validate role trước khi cấp token | Med | REQ-E01 |
+| `lib/ui/product_page.dart` | `ProductPage.build()` | Thêm UI | Chưa có filter → thêm `FilterBar` widget | Low | REQ-S02 |
+| | | Thêm/Sửa/Xóa/Refactor | | Low/Med/High | REQ-xxx |
+
+---
+
+## 7. Rủi ro kỹ thuật
+
+| Mã | Rủi ro | Xác suất | Ảnh hưởng | Giải pháp | REQ liên quan |
+|----|--------|:--------:|:---------:|----------|:-------------:|
+| R-01 | | Cao/Trung/Thấp | Cao/Trung/Thấp | | REQ-xxx |
+
+> Task gắn `[RISKY]`/`[SPIKE]` nên tham chiếu mã rủi ro (vd `Risk: R-01`) để truy vết hai chiều.
+
+---
+
+## 8. Constitution Compliance Check
+
+> Plan Agent tự kiểm tra plan tuân thủ constitution
+
+| Nguyên tắc Constitution | Plan tuân thủ? | Ghi chú |
+|------------------------|:--------------:|---------|
+| Architecture pattern (§1) | ✅ / ❌ | |
+| Naming convention (§2) | ✅ / ❌ | |
+| Testing standards (§2.2) | ✅ / ❌ | |
+| API standards (§4) | ✅ / ❌ / N/A | |
+
+---
+
+## 9. No-Go Zone Verification
+
+> Nếu legacy project có context.md
+
+| No-Go Zone | Plan đụng? | Ghi chú |
+|-----------|:----------:|---------|
+| [zone 1 từ context.md] | ✅ Safe / ❌ Violated | |
+
+---
+
+## 10. Non-Functional Requirements (NFR)
+
+> Lấy từ **"Yêu cầu đặc biệt"** của mỗi `UC-xx` trong spec (hiệu năng / bảo mật / khả dụng-a11y / tuân thủ-audit). Mỗi NFR phải có **cách plan đáp ứng** + **task/kiểm chứng** — để không rơi rụng khi implement.
+
+| NFR | Loại | Yêu cầu (từ spec) | Cách plan đáp ứng | Verify (task/test) | UC/REQ |
+|-----|------|-------------------|-------------------|--------------------|--------|
+| Hiệu năng | Perf | p95 < 2s | cache + index phù hợp | TC perf budget | UC-01 |
+| Khả dụng | A11y | keyboard + screen reader | semantics/label widget | tiêu chí task `[UI]` | UC-01 |
+| Tuân thủ | Audit | log mọi thao tác ghi | audit interceptor | task `[LOGIC]` | UC-02 |
+
+---
+
+## 11. Observability & Rollout (nếu lên production)
+
+> Cho feature chạy thật: làm sao **biết nó hoạt động/đổ vỡ**, và **tung ra an toàn**. Gieo mầm cho Metrics/Operations agent hạ nguồn.
+
+- **Feature flag**: [tên cờ + default + cách bật dần]
+- **Metrics cần emit**: [counter / latency p95 / error-rate — tên metric cụ thể]
+- **Logs**: [sự kiện log mức info/error — KHÔNG log dữ liệu nhạy cảm]
+- **Alerts**: [ngưỡng cảnh báo — vd error-rate > 1% trong 5 phút]
+- **Rollout**: [canary / % traffic / điều kiện rollback]
+
+---
+
+## 12. Giả định & Câu hỏi mở (Assumptions & Open Questions)
+
+> Gom về **một chỗ** mọi giả định thiết kế và điểm chưa chắc — để Master Check (R.0) và human review thấy ngay, thay vì rải rác trong từng task. Mỗi task `[CLARIFY]` PHẢI có câu hỏi tương ứng ở đây.
+
+### 12.1 Giả định thiết kế (Assumptions)
+
+> Điều plan đang **mặc định là đúng** mà chưa được xác nhận. Nếu sai → phải re-plan.
+
+| Mã | Giả định | Tác động nếu sai | Cần ai xác nhận |
+|----|----------|------------------|-----------------|
+| A-01 | [VD: API trả 401 cho cả sai mật khẩu lẫn khóa tài khoản] | [phải tách 2 luồng lỗi] | [Backend lead] |
+
+### 12.2 Câu hỏi mở (Open Questions — gom từ task `[CLARIFY]`)
+
+> Mỗi dòng map tới task `[CLARIFY]`. Implement Agent KHÔNG được đoán — phải hỏi trước khi code.
+
+| Câu hỏi | Task liên quan | Chặn implement? | Người trả lời |
+|---------|----------------|:---------------:|---------------|
+| [VD: Lockout 5 lần theo IP hay theo account?] | T-0xx | ✅ | [Product owner] |
+
+---
+
+## 13. Tech Decisions & Alternatives (Quyết định kỹ thuật)
+
+> **WHY** của plan: vì sao chọn cách này, đã **cân nhắc & loại** phương án nào. Để người review và Implement Agent không mở lại tranh luận đã chốt. Mỗi quyết định không tầm thường → 1 dòng.
+
+| Mã | Quyết định | Lý do chọn | Phương án đã cân nhắc & loại | Đánh đổi chấp nhận |
+|----|-----------|-----------|------------------------------|--------------------|
+| D-01 | [VD: BLoC cho state mgmt] | constitution §3.2 + dễ test | Provider (ít boilerplate, yếu test), setState (không scale) | nhiều boilerplate hơn |
+| D-02 | | | | |
+
+---
+
+> **Trạng thái**: Draft / Reviewed / Approved
+> **Người review**: [Tech Lead]
+> **Ngày review**: [YYYY-MM-DD]

package/templates/prototype-notes-template.md

@@ -0,0 +1,116 @@
+# Prototype Notes — [Feature NNN: Feature Name]
+
+> **Tạo lúc**: [YYYY-MM-DD HH:MM]
+> **Phase**: S.1.5
+> **Branch**: [LOGIC | UI]
+> **Mode**: [N/A (LOGIC) | from-mockup | explore] _(UI only)_
+> **Sub-shape**: [N/A | A — embedded in /existing-route | B — new route at /prototype/NNN] _(UI explore only)_
+> **Prototype location**: `.v-flow/features/NNN/prototype/`
+> **Render đã chốt**: [`.v-flow/features/NNN/ui/approved/UC-NN.*` | N/A] _(mode=from-mockup)_
+
+---
+
+## Câu hỏi cần trả lời
+
+> [Câu hỏi cụ thể mà prototype này được tạo ra để trả lời]
+> Lấy từ spec.md — không phải câu hỏi tổng quát.
+
+**Liên quan đến**: [REQ-xxx, REQ-xxx]
+
+---
+
+## Branch: [LOGIC | UI]
+
+### Nhánh chọn vì
+
+[Lý do chọn LOGIC hoặc UI branch — behavior/state question vs UI/layout question]
+
+### [LOGIC only] Runtime
+
+[Node.js | TypeScript | Bun | Python | Java | Angular — detected from project files]
+
+### [UI explore only] Sub-shape
+
+[Sub-shape A (embed trong existing page) | Sub-shape B (new throwaway route)]
+Lý do chọn: [tại sao chọn Sub-shape này?]
+
+### [UI only] Design source
+
+[project-root/DESIGN.md | .v-flow/DESIGN.md — file nào được dùng]
+
+### [UI from-mockup] Reproduce — Mockup → Render
+
+- **Mockup nguồn**: [`ui/mockups/UC-NN-*.png` — từ PYC/PTYC/Figma]
+- **Mức ràng buộc**: [Định hướng (layout/thành phần/luồng) | Bắt buộc (pixel)]
+- **Render đã chốt**: `ui/approved/UC-NN.*` (GIỮ làm contract — KHÔNG xóa)
+- **Đối chiếu DESIGN.md**: [token nào dùng; có chỗ nào mockup mâu thuẫn design system không?]
+
+---
+
+## Run command
+
+```bash
+# [Exact command user cần chạy — không được thiếu]
+# Ví dụ LOGIC: pnpm prototype:NNN
+# Ví dụ UI HTML: mở index.html trong browser (double-click)
+# Ví dụ UI Angular: ng serve → http://localhost:4200/route?variant=A
+```
+
+## Kết quả & Verdict
+
+### Verdict: [VALIDATED | REJECTED | INCONCLUSIVE]
+
+**Người duyệt**: [Tên + vai trò — VD: `Nguyễn A (BA/PO)`] · **Duyệt lúc**: [YYYY-MM-DD HH:MM]
+> ⚠️ `VALIDATED` BẮT BUỘC ghi người duyệt thật. Thiếu người duyệt → verdict = `INCONCLUSIVE`, KHÔNG được lock `ui/approved/`.
+
+### Kết quả interact (evidence)
+
+> Mô tả cụ thể những case đã test — không cụ thể = verdict không đáng tin.
+
+- [x] Case 1 — [mô tả và kết quả]
+- [x] Case 2 — [mô tả và kết quả]
+- [ ] Case chưa test — [lý do bỏ qua]
+
+**Phát hiện quan trọng**: [key insight — lý do chính dẫn đến verdict]
+
+### Những gì đã học được
+
+- [Finding 1 — cụ thể, không chung chung]
+- [Finding 2]
+- [Finding 3 nếu có]
+
+### Tác động đến Spec
+
+- [ ] Không cần sửa spec — prototype xác nhận hướng hiện tại đúng
+- [ ] Cần sửa [REQ-xxx]: [mô tả thay đổi cụ thể]
+- [ ] Cần thêm requirement mới: [mô tả]
+
+### Quyết định cần carry-forward vào Plan
+
+> Plan Agent phải biết những điều này khi thiết kế architecture:
+
+- [Quyết định 1 — e.g. "Dùng reducer pattern, không dùng class"]
+- [Quyết định 2 — e.g. "Sidebar layout (Variant B) được chọn"]
+
+---
+
+## Routing
+
+- [ ] **VALIDATED** → `/v.plan + /v.test` (chạy song song)
+- [ ] **REJECTED** → `/v.specify` (update spec với findings trên)
+- [ ] **INCONCLUSIVE** → Chờ stakeholder input: [câu hỏi còn mở]
+
+---
+
+## Cleanup Checklist
+
+- [ ] *(Explore)* Prototype code tại `.v-flow/features/NNN/prototype/` đã được xóa
+- [ ] Hoặc: logic module đã được absorb vào code thật (và marked production-ready)
+- [ ] *(Reproduce)* Render `ui/approved/UC-NN.*` được **GIỮ** (đừng xóa) — đã cập nhật spec UI Intent "Render đã chốt"
+- [ ] Verdict đã được ghi vào `_session.md` (execution trace)
+- [ ] `.flow-state.yaml` đã update `artifacts.prototype.*` (mode, approved_ref, **approved_by + approved_at nếu VALIDATED**)
+- [ ] Spec đã được update (nếu REJECTED)
+
+---
+
+*Prototype là throwaway. File này là thứ duy nhất đáng giữ.*

package/templates/ptyc/ptyc.meta.example.yaml

@@ -0,0 +1,44 @@
+# ptyc.meta.yaml — Metadata trang bìa / ký / căn cứ cho PTYC (BA điền).
+# Copy file này vào .v-flow/features/{NNN}/ptyc.meta.yaml và THAY mọi <...> bằng giá trị THẬT.
+# Nội dung nghiệp vụ (chức năng, requirements...) KHÔNG ở đây — agent lấy từ spec.md.
+#
+# ⚠️ KHÔNG để nguyên số ví dụ. doc_code & tên file tự sinh từ `pyc_ref.no` —
+#    điền sai số PYC thì cả tên tài liệu & tên file đều sai.
+
+doc:
+  system_name: "HỆ THỐNG IOC"        # Tên hệ thống (in trang bìa)
+  project_code: "IOC"                 # Mã hiệu dự án
+  doc_code: ""                        # ĐỂ TRỐNG → tự sinh "PTYC_<project_code>_<pyc_ref.no>_<năm>_V1.0".
+                                      # Chỉ điền nếu muốn override thủ công.
+  place: "Hà Nội"                     # Nơi phát hành
+  date: "<MM/YYYY>"                   # Tháng/năm phát hành tài liệu, vd 06/2026
+
+# §2.1 Căn cứ Phiếu Yêu Cầu (PYC) — `no` là NGUỒN DUY NHẤT cho doc_code & tên file
+pyc_ref:
+  no: "<SỐ PYC>"                      # vd 01 — lấy đúng số trên Phiếu Yêu Cầu của feature này
+  date: "<DD/MM/YYYY>"               # ngày trên PYC
+  unit: "<ĐƠN VỊ YÊU CẦU>"          # vd Phòng Kỹ thuật Công nghệ
+
+# Trang ký (để trống approver nếu ký tay)
+signers:
+  preparer: "<NGƯỜI LẬP>"           # NV phân tích nghiệp vụ
+  approver1: ""
+  approver2: ""
+  approver3: ""
+
+# Bảng ghi nhận thay đổi (A=Tạo mới, M=Sửa, D=Xóa)
+change_log:
+  - date: "<MM/YYYY>"
+    position: "-"
+    amd: "A"
+    source: "<BA>"
+    old_ver: "-"
+    desc: "Tạo mới tài liệu"
+    new_ver: "V1.0"
+
+# §1.4 Tài liệu tham khảo (tùy chọn)
+references:
+  - name: "PYC số <SỐ PYC>"
+    date: "<DD/MM/YYYY>"
+    source: "<ĐƠN VỊ>"
+    note: "-"

package/templates/retrospective-report-template.md

@@ -0,0 +1,136 @@
+# Template: Retrospective Report — Báo cáo Tổng kết
+
+> Được tạo bởi **Retrospective Agent**
+> Feature/Sprint: [TÊN]
+> Ngày: [YYYY-MM-DD]
+
+---
+
+## 1. Tổng quan Feature/Sprint
+
+| Mục | Giá trị |
+|-----|--------|
+| **Feature** | [#NNN — Tên feature] |
+| **Ngày bắt đầu** | [YYYY-MM-DD] |
+| **Ngày hoàn thành** | [YYYY-MM-DD] |
+| **Tổng thời gian** | [X ngày] |
+| **Spec versions** | v1.0 → v[X.Y] ([N] revisions) |
+| **Rework cycles** | [N] (quay lại phase nào) |
+
+---
+
+## 2. Phân tích 5 chiều
+
+### 2.1 🎯 Spec Quality — Chất lượng đặc tả
+
+| Metric | Giá trị | Đánh giá |
+|--------|--------|:--------:|
+| Requirements rõ ràng ngay từ v1? | [%] | ✅ / ⚠️ / ❌ |
+| Số lần phải sửa spec | [N] | ✅ / ⚠️ / ❌ |
+| BA Critic rounds | [N] | ✅ / ⚠️ / ❌ |
+| Requirements bị miss (phát hiện muộn) | [N] | ✅ / ⚠️ / ❌ |
+
+**Nhận xét**: [phân tích]
+
+### 2.2 📐 Planning Quality — Chất lượng kế hoạch
+
+| Metric | Giá trị | Đánh giá |
+|--------|--------|:--------:|
+| Plan đúng ngay từ đầu? | Yes/No | ✅ / ⚠️ / ❌ |
+| Cần re-plan? | [N] lần | ✅ / ⚠️ / ❌ |
+| Task estimation accuracy | [XX]% | ✅ / ⚠️ / ❌ |
+| Dependency issues gặp? | [N] | ✅ / ⚠️ / ❌ |
+
+**Nhận xét**: [phân tích]
+
+### 2.3 🛡️ Quality Gates — Hiệu quả cổng chất lượng
+
+| Metric | Giá trị | Đánh giá |
+|--------|--------|:--------:|
+| Master Check pass lần 1? | Yes/No | ✅ / ⚠️ / ❌ |
+| Code Review pass lần 1? | Yes/No | ✅ / ⚠️ / ❌ |
+| Issues caught by Master Check | [N] | ✅ / ⚠️ / ❌ |
+| Issues leaked to Review | [N] | ✅ / ⚠️ / ❌ |
+| Bugs found after deploy | [N] | ✅ / ⚠️ / ❌ |
+
+**Nhận xét**: [phân tích]
+
+### 2.4 ⚙️ Execution Quality — Chất lượng thực hiện
+
+| Metric | Giá trị | Đánh giá |
+|--------|--------|:--------:|
+| TDD followed? | Yes/No | ✅ / ⚠️ / ❌ |
+| Test coverage | [XX]% | ✅ / ⚠️ / ❌ |
+| Concerns resolved | [N]/[N] | ✅ / ⚠️ / ❌ |
+| Deviations from plan | [N] | ✅ / ⚠️ / ❌ |
+| Constitution violations | [N] | ✅ / ⚠️ / ❌ |
+
+**Nhận xét**: [phân tích]
+
+### 2.5 👥 Team & Process
+
+| Metric | Giá trị | Đánh giá |
+|--------|--------|:--------:|
+| Human response time (avg) | [N] giờ | ✅ / ⚠️ / ❌ |
+| Blocked time total | [N] giờ | ✅ / ⚠️ / ❌ |
+| Communication issues | [N] | ✅ / ⚠️ / ❌ |
+
+**Nhận xét**: [phân tích]
+
+---
+
+## 3. What Went Well ✅
+
+1. [Điều tốt 1]
+2. [Điều tốt 2]
+3. [Điều tốt 3]
+
+## 4. What Could Be Improved ⚠️
+
+1. [Cải thiện 1] → **Action**: [hành động cụ thể]
+2. [Cải thiện 2] → **Action**: [hành động cụ thể]
+3. [Cải thiện 3] → **Action**: [hành động cụ thể]
+
+## 5. What Went Wrong ❌
+
+1. [Vấn đề 1] → **Root cause**: [nguyên nhân] → **Prevention**: [cách phòng tránh]
+
+---
+
+## 6. Action Items
+
+| # | Action | Owner | Deadline | Target |
+|---|--------|-------|----------|--------|
+| 1 | [hành động] | [ai] | [khi nào] | [agent-config / constitution / knowledge-base] |
+| 2 | [hành động] | [ai] | [khi nào] | [mục tiêu] |
+
+---
+
+## 7. Knowledge Base Updates
+
+> Đề xuất cập nhật vào `.v-flow/knowledge/`
+
+| File | Loại update | Nội dung |
+|------|:----------:|---------|
+| `lessons-learned/[topic].md` | Tạo mới / Cập nhật | [tóm tắt bài học] |
+| `patterns/[pattern].md` | Tạo mới / Cập nhật | [pattern mới phát hiện] |
+| `domain-glossary.md` | Cập nhật | [thuật ngữ mới] |
+
+---
+
+## 8. Đánh giá tổng thể
+
+| Tiêu chí | Điểm (1-5) |
+|----------|:-----------:|
+| Spec Quality | /5 |
+| Planning Quality | /5 |
+| Quality Gates | /5 |
+| Execution Quality | /5 |
+| Team & Process | /5 |
+| **Trung bình** | **/5** |
+
+> **So sánh với feature/sprint trước**: Tốt hơn / Tương đương / Kém hơn — [giải thích]
+
+---
+
+> **Bước tiếp theo**: `/v.metrics` (nếu chưa chạy) → Feature complete

package/templates/security-review-template.md

@@ -0,0 +1,84 @@
+# Template: Security Review
+
+> Được tạo bởi **Security Agent** — Phase B.0 (optional)
+> Feature: [TÊN FEATURE]
+> Spec Version: [vX.Y]
+> Ngày review: [YYYY-MM-DD]
+
+---
+
+## 1. Authentication & Authorization
+
+| Kiểm tra | Kết quả | Ghi chú |
+|----------|---------|---------|
+| Có authentication flow? | ✅ / ❌ / N/A | |
+| Auth tokens an toàn? (JWT, expiry, refresh) | ✅ / ❌ / N/A | |
+| Role-based access control? | ✅ / ❌ / N/A | |
+| API endpoints đều yêu cầu auth? | ✅ / ❌ / N/A | |
+
+---
+
+## 2. Input Validation
+
+| Kiểm tra | Kết quả | Ghi chú |
+|----------|---------|---------|
+| SQL Injection protected? | ✅ / ❌ / N/A | |
+| XSS protected? | ✅ / ❌ / N/A | |
+| Input sanitization đầy đủ? | ✅ / ❌ / N/A | |
+| File upload validation? | ✅ / ❌ / N/A | |
+| Rate limiting? | ✅ / ❌ / N/A | |
+
+---
+
+## 3. Data Protection
+
+| Kiểm tra | Kết quả | Ghi chú |
+|----------|---------|---------|
+| Sensitive data encrypted at rest? | ✅ / ❌ / N/A | |
+| HTTPS / TLS enforced? | ✅ / ❌ / N/A | |
+| PII handled correctly? | ✅ / ❌ / N/A | |
+| Logging không chứa sensitive data? | ✅ / ❌ / N/A | |
+
+---
+
+## 4. Infrastructure
+
+| Kiểm tra | Kết quả | Ghi chú |
+|----------|---------|---------|
+| CORS configured đúng? | ✅ / ❌ / N/A | |
+| CSP headers? | ✅ / ❌ / N/A | |
+| Environment secrets an toàn? | ✅ / ❌ / N/A | |
+| Dependencies không có known vulnerabilities? | ✅ / ❌ / N/A | |
+
+---
+
+## 5. Phân loại Issues
+
+### 🔴 Critical Security Issues
+*(Không có)* / Liệt kê nếu có:
+- **[SEC-C001]** [Mô tả] → Fix: [Đề xuất]
+
+### 🟠 Major Security Issues
+*(Không có)* / Liệt kê nếu có:
+- **[SEC-M001]** [Mô tả] → Fix: [Đề xuất]
+
+### 🟡 Security Concerns
+*(Không có)* / Liệt kê nếu có:
+- **[SEC-W001]** [Mô tả] → Implement Agent cần chú ý
+
+### 🔵 Recommendations
+- **[SEC-R001]** [Gợi ý cải thiện]
+
+---
+
+## 6. Verdict
+
+**Security Review**: ✅ PASS / ⚠️ PASS WITH CONCERNS / ❌ FAIL
+
+> **FAIL** nếu có ít nhất 1 Critical hoặc Major security issue.
+> **PASS WITH CONCERNS** nếu có concerns cần Implement Agent chú ý.
+
+---
+
+> **Reviewer**: Security Agent
+> **Mandatory khi**: Feature có auth, payment, user data, hoặc external API integration