@longph2102/v-flow 1.5.0

package/skills/_shared/context-reader/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: context-reader
+description: "Load context.md cho legacy projects, extract No-Go Zones, Technical Debt, và architecture thực tế. Agent PHẢI gọi skill này khi context.md tồn tại."
+trigger: "Đầu mỗi agent session — khi .v-flow/context.md tồn tại"
+phase: "All"
+used_by:
+  - /v.specify
+  - /v.plan
+  - /v.test
+  - /v.check
+  - /v.implement
+  - /v.review
+---
+
+# Context Reader — Hiểu Thực Trạng Legacy
+
+> ⚠️ Đây là **Skill dùng chung cho legacy projects**.
+> Nếu context.md KHÔNG tồn tại → Skip (greenfield project).
+> Nếu TỒN TẠI → **BẮT BUỘC đọc TRƯỚC mọi thứ**.
+>
+> → Xem `gotchas.md` cho lỗi khi đọc context.
+> → Xem `examples/good/` cho mẫu output legacy project.
+
+---
+
+## Khi nào KHÔNG đọc
+
+- Greenfield project (không có context.md)
+- Đang chạy `/v.understand` (đang TẠO context.md)
+
+---
+
+## Trust Levels — Đánh Giá Độ Tin Cậy
+
+> 💡 KHÔNG phải mọi thông tin trong context.md đều đáng tin như nhau.
+
+| Marker | Trust Level | Agent nên |
+|:------:|:----------:|---------|
+| (không marker) | 🟢 **Verified** | Tin tưởng — human đã review |
+| `[⚠️ AI-inferred]` | 🟡 **Inferred** | Double-check với code trước khi rely |
+| `[❓ CẦN VERIFY]` | 🔴 **Unverified** | KHÔNG dựa vào — chờ human confirm |
+
+### Staleness Score
+
+```
+Last updated < 7 ngày  → 🟢 Fresh — tin tưởng nguyên văn
+Last updated 7-30 ngày → 🟡 Aging — verify No-Go Zones và Tech Stack
+Last updated > 30 ngày → 🔴 Stale — WARN + suggest /v.understand --refresh
+Không có date           → 🔴 Unknown — treat như Stale
+```
+
+---
+
+## Fields Cần Extract
+
+> 💡 Mỗi field ảnh hưởng khác nhau đến các Agent downstream.
+
+| Field | Section trong context.md | Ảnh hưởng tới Agent |
+|-------|------------------------|-------------------|
+| **Tech Stack** | §1 Tech Stack Thực Tế | Implement: dùng đúng framework |
+| **Architecture** | §2 Kiến Trúc Thực Tế | Plan: thiết kế phù hợp reality |
+| **Module Map** | §3 Module Map | All: biết scope, dependencies |
+| **No-Go Zones** | §4 🚫 No-Go Zones | Implement: **BLOCK** nếu đụng |
+| **Technical Debt** | §5 Technical Debt | Plan: aware risks, budget fix |
+| **Test Coverage** | §6 Test Coverage | Test: biết baseline, Plan: allocate effort |
+| **Patterns** | §7 Patterns Đang Dùng | Implement: follow existing patterns |
+
+## Per-Agent Impact Matrix
+
+> 💡 Mỗi field ảnh hưởng KHÁC NHAU tới từng Agent:
+
+| Field | BA | Plan | Test | Implement | Review |
+|-------|:--:|:----:|:----:|:---------:|:------:|
+| **Tech Stack** | • | • | • | ⭐ CRITICAL | • |
+| **Architecture** | • | ⭐ CRITICAL | • | ⭐ CRITICAL | ⭐ CRITICAL |
+| **No-Go Zones** | • | ⭐ CRITICAL | • | ⭐ CRITICAL | ⭐ CRITICAL |
+| **Tech Debt** | • | ⭐ CRITICAL | • | • | ⭐ CRITICAL |
+| **Test Coverage** | • | • | ⭐ CRITICAL | • | • |
+| **Patterns** | • | • | • | ⭐ CRITICAL | • |
+
+• = Awareness. ⭐ = Must extract để làm việc đúng.
+
+---
+
+## Đặc Thù — Những Điều KHÔNG Obvious
+
+### 1. AI-inferred ≠ verified
+- LLM hay treat AI-inferred như fact → SAI
+- VD: AI infer "JWT auth" nhưng thực tế dùng session-based
+- **Rule**: Cross-reference `[⚠️ AI-inferred]` items với code TRƯỚC khi plan/implement
+
+### 2. Tech Debt là input cho Plan Agent
+- context.md liệt kê sql injection risk → Plan Agent PHẢI address
+- Không được ignore — ít nhất phải explicit acknowledge trong plan.md
+- Nếu task chồng No-Go Zone + Tech Debt → BLOCK + escalate
+
+### 3. Reality ≠ Rules
+- context.md mô tả **đang dùng gì** (reality)
+- constitution.md mô tả **nên dùng gì** (rules)
+- Code MỚI → follow constitution. Code CŨ → giữ nguyên (No-Go)
+- Flag conflicts rõ ràng trong _session.md
+
+### 4. No-Go Zones là HARD STOP
+- Khi task cần sửa file No-Go → DỪNG ngay
+- Cross-reference với `no-go-zone-guard` skill
+- KHÔNG cố workaround mà không báo
+
+### 5. Module Map = Scope Control
+- Agent chỉ chạm vào modules liệt kê trong Module Map
+- Nếu task cần module KHÔNG có trong map → likely out of scope
+- Ghi _session.md và hỏi trước khi expand scope

package/skills/_shared/context-reader/config.json

@@ -0,0 +1,54 @@
+{
+  "name": "context-reader",
+  "version": "1.0",
+  "description": "Load context.md cho legacy projects, extract No-Go Zones, Technical Debt, architecture thực tế",
+  "agent": "_shared",
+  "phase": ["All"],
+  "triggers": ["session_start"],
+  "dependencies": [],
+  "config": {
+    "context_path": ".v-flow/context.md",
+    "fallback_behavior": "skip_greenfield",
+    "staleness_thresholds": {
+      "fresh_days": 7,
+      "aging_days": 30
+    },
+    "critical_fields": ["no_go_zones", "tech_stack", "architecture"],
+    "trust_levels": {
+      "verified": "no_marker",
+      "inferred": "[⚠️ AI-inferred]",
+      "unverified": "[❓ CẦN VERIFY]"
+    }
+  },
+  "setup_questions": [
+    {
+      "id": "staleness_action",
+      "question": "Khi context.md quá cũ (>30 ngày)?",
+      "options": ["warn", "block", "auto-refresh"],
+      "default": "warn",
+      "description": "warn = hiện warning. block = DỪNG pipeline. auto-refresh = suggest /v.understand --refresh."
+    },
+    {
+      "id": "nogo_enforcement",
+      "question": "Mức độ enforce No-Go Zones?",
+      "options": ["strict", "warn", "log"],
+      "default": "strict",
+      "description": "strict = BLOCK ngay khi đụng. warn = cảnh báo nhưng cho tiếp. log = chỉ ghi log."
+    },
+    {
+      "id": "cross_reference_constitution",
+      "question": "Có cross-reference context.md với constitution.md không?",
+      "type": "boolean",
+      "default": true
+    }
+  ],
+  "hooks": {
+    "pre_read": "Check context.md tồn tại → nếu không → skip (greenfield project)",
+    "post_read": "Check staleness → warn nếu stale. Cross-reference No-Go Zones với constitution §7."
+  },
+  "memory": {
+    "file": "context-reads.log",
+    "format": "[date] | [agent] | [phase] | [staleness_status] | [nogo_zones_count] | [warnings]",
+    "purpose": "Track context awareness — dùng cho /v.understand --check"
+  }
+}

package/skills/_shared/context-reader/examples/good/legacy-nodejs-output.md

@@ -0,0 +1,35 @@
+# Good Example — Context Reader Output cho Legacy Project
+
+> Mẫu output khi context-reader load context.md.
+
+```markdown
+## ⚠️ Legacy Context Active
+
+**Project**: E-Commerce API (Node.js + Express)
+**Stack**: Node.js 14, Express 4, PostgreSQL 12, no ORM (raw SQL)
+**Architecture**: Monolith — routes/ → mixed logic (no service layer)
+**Last Updated**: 2026-03-15 (40 ngày trước — ⚠️ có thể outdated)
+
+### 🚫 No-Go Zones (CRITICAL)
+- 🔴 `routes/payment.js` (487 LOC) — PCI compliance, đã audit
+- 🔴 `middleware/auth.js` (156 LOC) — 12 routes depend on this
+- 🟡 `config/db.js` (45 LOC) — Connection pool, system-wide impact
+
+### ⚡ Technical Debt (6 items)
+- 🔴 SQL injection risk in `routes/products.js:45` (string concatenation)
+- 🔴 No input validation — req.body used directly
+- 🟡 0% test coverage — no test files exist
+- 🟡 Hardcoded secrets in `config/env.js`
+- 🟢 No error classes — errors are plain strings
+- 🟢 Mixed SQL styles (template literal + string concat)
+
+### 📊 Test Coverage
+- Current: 0%
+- Untested: ALL files
+- Priority: routes/products.js, routes/orders.js
+
+### Patterns
+- Direct SQL queries (no ORM, no query builder)
+- Express middleware chain
+- Callback-style error handling
+```

package/skills/_shared/context-reader/gotchas.md

@@ -0,0 +1,49 @@
+# Gotchas — Context Reader
+
+> Cập nhật liên tục khi Agent gặp edge case mới.
+> Legacy projects là "minefield" — mỗi gotcha ở đây từ lỗi thực tế.
+
+---
+
+## Gotchas Phổ Biến
+
+1. ❌ **Skip context.md vì "greenfield"** — File tồn tại = legacy. Phải đọc.
+   - **Check**: `ls .v-flow/context.md` — exists? → read.
+   - **Hậu quả**: Agent implement pattern sai cho legacy codebase.
+
+2. ❌ **AI-inferred → chấp nhận không verify** — AI có thể sai hoàn toàn.
+   - **VD**: AI infer "sử dụng JWT auth" nhưng thực tế dùng session-based.
+   - **Fix**: Cross-reference với code thực. Đánh dấu mức tin cậy.
+   - **Hậu quả**: Plan Agent design JWT flow → implement fail.
+
+3. ❌ **Outdated context → plan wrong** — context.md nói "Node 14" nhưng đã upgrade Node 18.
+   - **Fix**: Check `Last updated` date. > 30 ngày → WARN + suggest refresh.
+   - **Hậu quả**: Implement Agent dùng Node 14 syntax/API → warnings hoặc errors.
+
+4. ❌ **Bỏ qua No-Go Zones trong output** — Đọc context.md nhưng không extract No-Go list.
+   - **Rule**: No-Go Zones ALWAYS included in output, ALWAYS.
+   - **Hậu quả**: Downstream agents đụng No-Go → bị block muộn, waste effort.
+
+5. ❌ **Conflict context vs constitution không flag** — Reality ≠ Rules nhưng Agent chọn 1.
+   - **Fix**: Flag conflict rõ ràng. Ghi _session.md. Implement code mới theo constitution.
+   - **Hậu quả**: Inconsistent codebase — half old style, half new style.
+
+6. ❌ **Quên tech debt entries** — context.md liệt kê SQL injection nhưng Agent plan không address.
+   - **Fix**: Tech debt items PHẢI được xem xét trong plan.md (address hoặc explicit acknowledge).
+   - **Hậu quả**: Known vulnerabilities not addressed → security risk.
+
+7. ❌ **Module Map = boundary** — Agent chạm module ngoài scope.
+   - **VD**: Task nói "fix product page" nhưng Agent sửa cả payment module.
+   - **Fix**: Kiểm tra Module Map. Module không listed = out of scope.
+   - **Hậu quả**: Scope creep → unplanned changes → regression.
+
+8. ❌ **Trust level uniform** — Treat verified và AI-inferred cùng weight.
+   - **Fix**: Xem Trust Levels table trong SKILL.md. 🔴 items = DON'T rely.
+
+---
+
+## Edge Cases
+
+- **context.md rỗng**: File exists nhưng không có content → treat như greenfield
+- **context.md quá dài (> 300 LOC)**: Đọc §4 No-Go Zones TRƯỚC, còn lại after
+- **Multiple context.md** (monorepo): Đọc gần nhất theo directory hierarchy

package/skills/_shared/ears-notation/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: ears-notation
+description: "Quick reference EARS notation cho mọi Agent cần viết hoặc đọc requirements. Gọi khi cần interpret REQ-xxx IDs."
+trigger: "Khi cần viết, đọc, hoặc validate requirements"
+phase: "S.1, B.0a, B.0b, R.0"
+used_by:
+  - /v.specify
+  - /v.plan
+  - /v.test
+  - /v.check
+  - /v.ba-critic
+---
+
+# EARS Notation — Quick Reference Card
+
+> 💡 Đây là **reference card** — không phải skill dạy viết EARS.
+> Để viết EARS chi tiết → xem `specify/ears-writer`.
+>
+> → Xem `gotchas.md` cho lỗi phổ biến khi interpret EARS.
+
+---
+
+## EARS Templates
+
+| Type | Keyword | Template | Signal nhận biết |
+|------|---------|----------|-----------------|
+| **Ubiquitous** | `phải` | Hệ thống **phải** `<action>` | Luôn đúng, không điều kiện |
+| **Event-driven** | `Khi` | **Khi** `<trigger>`, hệ thống phải `<action>` | Có sự kiện cụ thể |
+| **State-driven** | `Trong khi` | **Trong khi** `<state>`, hệ thống phải `<action>` | Suốt thời gian ở state |
+| **Optional** | `Nếu` | **Nếu** `<condition>`, hệ thống phải `<action>` | Có điều kiện tiên quyết |
+
+---
+
+## ID Convention
+
+| Prefix | Type | Example |
+|--------|------|---------|
+| `REQ-U` | Ubiquitous | REQ-U01 |
+| `REQ-E` | Event-driven | REQ-E01 |
+| `REQ-S` | State-driven | REQ-S01 |
+| `REQ-O` | Optional | REQ-O01 |
+
+---
+
+## Interpretation Guide Per Agent
+
+> 💡 Phần này giúp Agent DOWNSTREAM hiểu mỗi loại REQ gợi ý implementation pattern gì.
+
+| REQ Type | Plan Agent → | Test Agent → | Implement Agent → |
+|:--------:|-------------|-------------|-------------------|
+| **REQ-U** | Always-on component, middleware | Unit test: assert always true | Core module, no conditional |
+| **REQ-E** | Event handler, route handler | Event test: given trigger → expect action | Handler/callback function |
+| **REQ-S** | State management, lifecycle | State test: while in state → verify behavior | Stateful component, BLoC |
+| **REQ-O** | Conditional logic, feature flag | Branch test: if true → A, else → B | if/guard clause |
+
+### Mapping sang Test Strategy
+
+| REQ Type | Test Strategy | Minimum TCs |
+|:--------:|--------------|:-----------:|
+| REQ-U | Invariant check — test ở mọi state | 1-2 |
+| REQ-E | Trigger → Action → Assert | 2-3 (success + errors) |
+| REQ-S | Enter state → verify → exit state | 2-4 (enter + during + exit) |
+| REQ-O | Condition true → A, condition false → B | 2+ (mỗi branch) |

package/skills/_shared/ears-notation/config.json

@@ -0,0 +1,55 @@
+{
+  "name": "ears-notation",
+  "version": "1.0",
+  "description": "EARS notation reference — Ubiquitous, Event-driven, State-driven, Optional patterns",
+  "agent": "_shared",
+  "phase": ["S.1"],
+  "triggers": ["spec_creation", "spec_review"],
+  "dependencies": [],
+  "config": {
+    "notation_types": ["Ubiquitous", "Event-driven", "State-driven", "Optional", "Unwanted"],
+    "prefix_mapping": {
+      "Ubiquitous": "REQ-U",
+      "Event-driven": "REQ-E",
+      "State-driven": "REQ-S",
+      "Optional": "REQ-O",
+      "Unwanted": "REQ-W"
+    },
+    "validation_rules": {
+      "min_requirements": 3,
+      "require_acceptance_criteria": true,
+      "max_ambiguous_words": 0
+    }
+  },
+  "setup_questions": [
+    {
+      "id": "strict_mode",
+      "question": "Bắt buộc tất cả requirements phải theo EARS format?",
+      "type": "boolean",
+      "default": true,
+      "description": "true = reject requirements không theo EARS. false = warn nhưng cho phép."
+    },
+    {
+      "id": "ambiguous_words",
+      "question": "Danh sách từ mơ hồ cần detect?",
+      "type": "string_array",
+      "default": ["nên", "hợp lý", "dễ dùng", "nhanh", "tối ưu", "user-friendly", "appropriate", "reasonable"],
+      "description": "Từ mơ hồ → trigger warning khi xuất hiện trong requirement."
+    },
+    {
+      "id": "require_nfr",
+      "question": "Bắt buộc có Non-Functional Requirements?",
+      "type": "boolean",
+      "default": true
+    }
+  ],
+  "hooks": {
+    "pre_write": "Load EARS notation reference → validate hiểu đúng format trước khi viết spec",
+    "post_write": "Scan spec.md → detect ambiguous words, verify mỗi REQ có AC"
+  },
+  "memory": {
+    "file": "ears-quality.log",
+    "format": "[date] | [feature] | [total_reqs] | [U_count] | [E_count] | [S_count] | [O_count] | [ambiguous_count]",
+    "purpose": "Track EARS adoption quality — identify patterns in requirement types"
+  }
+}

package/skills/_shared/ears-notation/examples/good/plan-test-interpretation.md

@@ -0,0 +1,29 @@
+# Good Example — EARS Interpretation cho Plan Agent
+
+> Mẫu cách Plan Agent đọc spec và design architecture dựa trên REQ types.
+
+## Input: spec.md excerpt
+```
+REQ-U01: Hệ thống phải hash password trước khi lưu DB
+REQ-E01: Khi user nhấn Login, hệ thống phải validate credentials
+REQ-S01: Trong khi loading, hệ thống phải hiển thị spinner
+REQ-O01: Nếu user có valid token, hệ thống phải skip login
+```
+
+## Plan Agent Interpretation
+
+| REQ | Type | → Architecture Decision |
+|-----|------|------------------------|
+| REQ-U01 | Ubiquitous | `AuthService` middleware — always hash, mọi endpoint dùng password |
+| REQ-E01 | Event-driven | `LoginController.post()` → `AuthService.validate()` — handler pattern |
+| REQ-S01 | State-driven | `LoginBloc` — state management: `LoginLoading` / `LoginSuccess` / `LoginError` |
+| REQ-O01 | Optional | `AuthGuard` — check token at app startup, conditional redirect |
+
+## Test Agent Interpretation
+
+| REQ | Type | → Test Strategy |
+|-----|------|----------------|
+| REQ-U01 | Ubiquitous | Invariant test — verify hash ở MỌI endpoint lưu password (≥2 TCs) |
+| REQ-E01 | Event-driven | Trigger test — POST /login valid → 200, invalid → 401 (≥3 TCs) |
+| REQ-S01 | State-driven | State test — emit Loading → verify spinner, emit Success → verify redirect (≥3 TCs) |
+| REQ-O01 | Optional | Branch test — có token → skip, không token → show login (≥2 TCs) |

package/skills/_shared/ears-notation/gotchas.md

@@ -0,0 +1,43 @@
+# Gotchas — EARS Notation
+
+> Cập nhật liên tục khi Agent gặp edge case mới.
+> Đây là "cheat sheet sai lầm" cho mọi Agent làm việc với requirements.
+
+---
+
+## Interpretation Gotchas
+
+1. ❌ **Prefix sai loại** — REQ-E nhưng nội dung Ubiquitous.
+   - **VD**: "REQ-E01: Hệ thống phải hash password" → thiếu trigger → là REQ-U.
+   - **Hậu quả**: Test Agent viết event test cho invariant rule → miss coverage.
+
+2. ❌ **Interpret REQ-U như "nice-to-have"** — "Hệ thống phải validate" → Agent nghĩ "optional".
+   - **Rule**: "phải" = MANDATORY. Ubiquitous = always enforced, every single request.
+
+3. ❌ **Confuse State-driven vs Event-driven**
+   - "Khi" = 1 event xảy ra, xong rồi thôi → **E**
+   - "Trong khi" = suốt thời gian ở state → **S**
+   - **VD**: "Khi user nhấn nút" = E. "Trong khi đang tải" = S.
+
+4. ❌ **Quên branch test cho REQ-O** — Optional REQ chỉ test condition=true.
+   - **Rule**: REQ-O PHẢI có test cho CẢ true branch VÀ false branch.
+   - **Hậu quả**: Untested else branch → bug khi condition false.
+
+5. ❌ **Count TCs sai per type**
+   
+   | REQ Type | Minimum TCs | Lý do |
+   |:--------:|:-----------:|-------|
+   | REQ-U | 1-2 | Invariant — verify ở ≥1 context |
+   | REQ-E | 2-3 | Success + error + edge case |
+   | REQ-S | 2-4 | Enter state + during + exit + timeout |
+   | REQ-O | 2+ | condition=true + condition=false |
+
+6. ❌ **Plan Agent bỏ qua REQ-S** — Quên design state management.
+   - **Signal**: Spec có REQ-S nhưng plan không mention state. 
+   - **Fix**: Mỗi REQ-S → plan.md PHẢI có state management component.
+
+7. ❌ **REQ-U nhưng implement conditional** — "Hệ thống phải log" nhưng code có `if (env === 'prod')`.
+   - **Rule**: REQ-U = unconditional. Nếu cần conditional → chuyển sang REQ-O.
+
+8. ❌ **Mixed language IDs** — REQ-E01 viết tiếng Việt nhưng REQ-E02 viết tiếng Anh.
+   - **Rule**: Đọc `config.json → language` setting. Nhất quán.

package/skills/check/cross-validator/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: cross-validator
+description: "Hướng dẫn Master Check Agent cross-validate Spec ↔ Plan ↔ Tests. Agent PHẢI đọc skill này khi /v.check được gọi. Đảm bảo traceability 100% và phát hiện gaps/conflicts."
+trigger: "Khi /v.check được gọi"
+phase: "R.0"
+used_by:
+  - /v.check
+hooks:
+  pre_check: "Load spec.md + plan.md + tasks.md + test-cases.md → build traceability matrix"
+  post_check: "Output validation-report.md với verdict + routing + concerns"
+---
+
+# Cross Validator — Kiểm Tra Chéo Có Hệ Thống
+
+> ⚠️ Đây là **Skill bắt buộc** cho Master Check Agent.
+> QUAN TRỌNG: Verdict PHẢI dựa trên EVIDENCE, không phải cảm tính.
+>
+> → Xem `gotchas.md` cho bias phổ biến khi validate.
+> → Xem `examples/good/` cho mẫu validation-report chuẩn.
+> → Xem `config.json` để customize (strictness, concern_threshold).
+
+---
+
+## Khi nào KHÔNG cần full cross-validation
+
+- Quick Fix (`/v.quickfix`) — simplified check: spec → code direct
+- Hotfix (`/v.hotfix`) — minimal check: correctness + security only
+- Documentation-only — no code change, no check needed
+
+---
+
+## 3-Phase Validation Engine
+
+> 💡 Agent PHẢI thực hiện tất cả 3 phases. Kết quả mỗi phase ảnh hưởng verdict.
+
+### Phase 1: Traceability Matrix — REQ ↔ Task ↔ TC
+
+**Build ma trận (REQ + AC-NN):**
+```
+Bước 1: Extract tất cả REQ-xxx + AC-NN từ spec.md (§4 Acceptance Criteria)
+Bước 2: Map REQ-xxx / AC-NN → T-NNN từ tasks.md (field "REQ / UC mapping" + "Done khi: AC-NN")
+Bước 3: Map REQ-xxx → TC-xx từ test-cases.md (Test Matrix §1)
+Bước 4: Tạo matrix:
+
+| REQ / AC | Task(s) | TC(s) | Status |
+|----------|---------|-------|--------|
+| REQ-E01 / AC-01 | T-001, T-004 | TC-01, TC-02 | ✅ Full |
+| REQ-E02 / AC-02 | T-004 | TC-03 | ✅ Full |
+| REQ-U01 / AC-03 | — | TC-04 | ❌ Missing Task |
+| REQ-O01 / AC-04 | T-004 | — | ❌ Missing TC |
+```
+
+**Verdict impact:**
+- ✅ REQ + mọi AC-NN có Task + TC = FULL → OK
+- ⚠️ REQ có Task nhưng không TC = WARNING (concern)
+- ❌ REQ **hoặc** AC-NN không có task nào phủ = CRITICAL GAP → FAIL (mọi AC-NN PHẢI có ≥1 task)
+
+### Phase 2: Consistency Check — Spec vs Plan Alignment
+
+**Kiểm tra:**
+
+| Kiểm tra | Signal sai | Action |
+|----------|-----------|--------|
+| Architecture vs Constitution | Plan dùng pattern khác constitution | FAIL |
+| File paths vs existing code | Plan modify file không tồn tại | WARNING |
+| No-Go Zone compliance | Plan modify No-Go Zone code | FAIL |
+| Dependency direction | Plan vi phạm layer rules | WARNING |
+| Error handling completeness | Plan thiếu error architecture | WARNING |
+| Security section | Feature cần auth nhưng plan không có | FAIL nếu security-critical |
+
+### Phase 3: Quality Assessment — Plan + Tasks + Tests Quality
+
+**Kiểm tra:**
+
+| Kiểm tra | Criteria | Action |
+|----------|---------|--------|
+| Task annotations | Có đúng 1 ENTRYPOINT? Có circular DEPENDS? | WARNING/FAIL |
+| Task granularity | Nhiều task Complexity **L** (nên tách)? Σ sizing quá lớn? | WARNING |
+| TDD trong task | Mỗi task có block **TDD (Red→Green)** + **Done khi (AC-NN)**? | WARNING nếu thiếu |
+| AC coverage | Mọi **AC-NN** (spec §4) được ≥1 task phủ? | FAIL nếu có AC chưa phủ |
+| Tech Decisions | Quyết định không tầm thường có ghi ở plan §13 (lý do + phương án loại)? | WARNING nếu thiếu |
+| Test coverage | ≥1 TC per REQ? Edge cases covered? | FAIL nếu < 100% |
+| Test types | Có unit + integration cho critical paths? | WARNING |
+| TC priority | Có P1 cho core logic + security? | WARNING |
+
+---
+
+## 3-Level Verdict System
+
+| Verdict | Điều kiện | Routing |
+|---------|-----------|---------|
+| ✅ **PASS** | 0 Critical + 0 Major | → B.1 (Implement) |
+| ⚠️ **PASS WITH CONCERNS** | 0 Critical + có Warning(s) | → B.1 + carry concerns [W-xxx] |
+| ❌ **FAIL** | Có ≥1 Critical gap/conflict | → Routing tùy `fail_reason` |
+
+### Fail Routing Logic
+
+```
+fail_reason = "missing_tasks"     → route: /v.plan (Plan Agent tạo tasks thiếu)
+fail_reason = "missing_tests"     → route: /v.test (Test Agent tạo TCs thiếu)
+fail_reason = "spec_conflict"     → route: /v.specify (BA Agent fix spec)
+fail_reason = "plan_conflict"     → route: /v.plan (Plan Agent redesign)
+fail_reason = "nogo_violation"    → route: /v.plan (Plan Agent redesign around No-Go)
+fail_reason = "constitution_violation" → route: /v.plan (Plan Agent align constitution)
+```
+
+---
+
+## Concerns System — [W-xxx]
+
+Concerns là issues KHÔNG đủ nghiêm trọng để FAIL nhưng PHẢI được addressed:
+
+```markdown
+### W-001: {Tên concern}
+- **Type**: Coverage / Consistency / Quality
+- **Severity**: Low / Medium
+- **Description**: {Mô tả concern}
+- **Assigned to**: {Phase/Agent nào cần resolve}
+- **Must verify at**: R.1 (Review Agent phải check)
+```
+
+**Rules:**
+- Concerns PHẢI được carry-forward vào `_session.md`
+- Implement Agent PHẢI resolve W-xxx assigned cho mình
+- Review Agent PHẢI verify W-xxx resolved ở R.1
+- Nếu W-xxx không resolved → Review Agent tạo issue tương ứng
+
+---
+
+## Đặc Thù Và Quy Ước
+
+### 1. Evidence-Based Verdict
+
+Mỗi quyết định trong report PHẢI có evidence:
+- ❌ "Plan looks good" → không có evidence
+- ✅ "4/4 REQs có task + TC, traceability 100%. Constitution alignment verified." → evidence
+
+### 2. Không Suy Đoán
+
+- Nếu spec mơ hồ → flag MƠ HỒ, không tự interpret
+- Nếu plan thiếu detail → flag THIẾU, không tự bổ sung
+- Nếu TC coverage unclear → flag GAP, không tự assume covered
+
+### 3. Cross-check Constitution
+
+Luôn verify:
+- Architecture pattern match
+- Naming convention match
+- Error handling pattern match
+- Security requirements covered (nếu constitution yêu cầu)
+
+---
+
+## Output — Validation Report Structure
+
+```markdown
+# Validation Report — Feature {NNN}
+
+**Ngày:** {date}
+**Verdict:** ✅ PASS / ⚠️ PASS WITH CONCERNS / ❌ FAIL
+
+## 1. Traceability Matrix
+| REQ | Task(s) | TC(s) | Status |
+|-----|---------|-------|--------|
+(matrix)
+
+## 2. Consistency Checks
+(spec vs plan alignment findings)
+
+## 3. Quality Assessment
+(plan + tasks + tests quality)
+
+## 4. Concerns [W-xxx]
+(if PASS WITH CONCERNS)
+
+## 5. Issues Found
+### Critical (blocks PASS)
+### Major (requires action)
+### Minor (suggestions)
+
+## 6. Verdict Rationale
+(evidence-based explanation)
+
+## 7. Routing Decision
+fail_reason: "{reason}"
+route_decision: "{/v.xxx}"
+```
+
+---
+
+## V-Flow Integration Points
+
+- **spec.md** → Source of truth: REQ list
+- **plan.md** → Design: components, file paths
+- **tasks.md** → Implementation plan: task list, dependencies
+- **test-cases.md** → Test coverage: TC list, REQ mapping
+- **constitution.md** → Rules: patterns, conventions
+- **context.md** → Constraints: No-Go Zones
+- **_session.md** → Output: concerns carry-forward
+- **validation-report.md** → Output: full report
+
+---
+
+## Gotchas
+
+→ Xem `gotchas.md` cho bias phổ biến khi validate — cập nhật liên tục.