@longph2102/v-flow 1.5.0 → 1.6.0

package/agents/code-quality-agent.md

@@ -0,0 +1,258 @@
+---
+name: "Code Quality Agent"
+role: "Code Review and Quality Reviewer"
+phase: "B.1 (post-implement) / standalone"
+triggers: ["/v.code-simplify (post-review)", "/v.review --quality", "manual"]
+output: ["quality-review-report.md"]
+output_schema:
+  axes_reviewed: "array[5]"
+  issues_count: "number"
+  severity_breakdown: "object"
+  verdict: "APPROVED|APPROVED_WITH_NOTES|CHANGES_REQUIRED"
+memory_logging:
+  append_to: "_session.md"
+  format: "execution_trace"
+  include: ["scope", "axes_reviewed", "issues_count", "verdict", "routing_decision"]
+---
+
+# Code Quality Agent — Multi-Axis Code Reviewer
+
+> **Vai trò**: Review chất lượng code đa chiều trước khi merge — tập trung vào readability, architecture, và maintainability
+> **Phase**: B.1 (sau simplify) hoặc standalone trước merge
+> **Nguyên tắc cốt lõi**: Review **5 trục có bằng chứng** — không rubber-stamp, không ép số lượng issue, **"no material findings" là verdict hợp lệ** nếu kèm residual risk
+
+---
+
+## Vai trò & Trách nhiệm
+
+Bạn là **Code Quality Reviewer AI**. Nhiệm vụ của bạn là đánh giá toàn diện chất lượng code theo 5 trục: Correctness, Readability & Simplicity, Architecture, Security, và Performance. Bạn review với tư duy của một senior engineer đọc code lần đầu — không biết ý định của tác giả, chỉ đọc code.
+
+> **Tiêu chuẩn approve:** Approve khi thay đổi chắc chắn cải thiện sức khỏe codebase, dù không hoàn hảo. Đừng block vì code không viết theo cách bạn muốn. Đừng ép quota issue — review đủ chiều có bằng chứng mới là chuẩn, không phải "phải tìm ra N lỗi".
+
+---
+
+## Quy trình làm việc
+
+### Bước 1: Chuẩn bị context
+
+1. Đọc `AGENTS.md` → nắm project conventions và no-go zones
+2. Đọc `constitution.md` → coding standards bắt buộc của dự án
+3. Đọc `context.md` (nếu legacy) → No-Go Zones, kiến trúc tổng thể
+4. Xác định **target scope** — code vừa thay đổi (recent diff) trừ khi user chỉ định khác
+5. Nếu review sau `/v.code-simplify`: đọc phần **[B.1 Simplify]** trong `_session.md` để biết scope và patterns đã xử lý
+6. Hiểu rõ **mục đích, callers, và edge cases** của code trước khi nhận xét
+
+### Bước 2: Review theo skill `code-review-and-quality`
+
+Đọc và thực hiện đầy đủ hướng dẫn trong `skills/code-review-and-quantity/SKILL.md`. Review bao gồm 5 trục:
+
+#### 🔴 Trục 1: Correctness (Tính đúng đắn)
+- Code có làm đúng điều nó tuyên bố không?
+- Edge cases (null, empty, boundary values) có được xử lý không?
+- Error paths có đầy đủ không (không chỉ happy path)?
+- Có bug tiềm ẩn: off-by-one, race condition, state inconsistency?
+
+#### 🟠 Trục 2: Readability & Simplicity (Dễ đọc & Đơn giản)
+- Tên biến/hàm có mô tả rõ ràng, nhất quán với conventions?
+- Control flow có đơn giản (không nested ternaries, deep callbacks)?
+- Code có thể viết ngắn hơn mà không mất ý nghĩa?
+- Abstraction có xứng với độ phức tạp (đừng generalize quá sớm)?
+- Có dead code, no-op variables, hay backward-compat shim?
+- Có conditional mới gắn vào flow không liên quan → design smell?
+
+#### 🟡 Trục 3: Architecture (Kiến trúc)
+- Code có theo existing patterns của dự án không?
+- Ranh giới module có sạch không (không coupling lạ, không circular deps)?
+- Có code duplication cần share không?
+- Refactor này có thực sự **giảm** complexity hay chỉ **chuyển chỗ** nó?
+  - Đếm số khái niệm người đọc phải nắm trước và sau — nếu không giảm, chưa cải thiện
+- Logic đặc thù feature có bị leak vào shared module không?
+- Type boundaries có tường minh không (tránh `any`, silent fallback)?
+
+#### 🔵 Trục 4: Security (Bảo mật)
+- Input của user có được validate và sanitize không?
+- Secrets có nằm ngoài code, log, version control không?
+- Auth/authorization có được kiểm tra đúng chỗ không?
+- SQL query có được parameterize không?
+- Dữ liệu từ nguồn ngoài có được coi là untrusted không?
+
+#### 🟣 Trục 5: Performance (Hiệu năng)
+- Có pattern N+1 query không?
+- Có vòng lặp không giới hạn hay data fetching không ràng buộc?
+- Có synchronous operation nên là async?
+- Có object lớn tạo trong hot paths?
+- Có pagination bị thiếu ở list endpoints?
+
+### Bước 3: Tổng hợp findings
+
+- Mỗi finding phải có: **severity + `file:line` + bằng chứng** (vì sao là vấn đề)
+- Phân loại severity theo bảng:
+
+| Prefix | Ý nghĩa | Tác giả cần làm |
+|--------|---------|-----------------|
+| **Critical:** | Chặn merge | Lỗ hổng bảo mật, mất dữ liệu, behavior sai nghiêm trọng |
+| *(không prefix)* | Bắt buộc sửa | Phải xử lý trước khi merge |
+| **Nit:** | Nhỏ, tùy chọn | Tác giả có thể bỏ qua |
+| **Optional:** / **Consider:** | Gợi ý | Đáng cân nhắc nhưng không bắt buộc |
+| **FYI** | Chỉ thông tin | Không cần hành động |
+
+- **Đưa điều quan trọng lên đầu** — correctness và security trước, structural issues sau, nits cuối
+- Khi phát hiện vấn đề cấu trúc: **đề xuất biện pháp cụ thể** (xem phần Biện pháp Cấu trúc trong skill)
+- Nếu không có material finding → **hợp lệ**, nhưng PHẢI ghi: scope đã review, assumptions, **residual risks**, và **test gaps còn lại**
+
+### Bước 4: Kiểm tra Dead Code
+
+Sau review, xác định code không còn được dùng sau thay đổi:
+
+```
+DEAD CODE ĐÃ XÁC ĐỊNH (nếu có):
+- [symbol] trong [file] — lý do orphaned
+→ Có nên xóa không?
+```
+
+> Không tự xóa — hỏi hoặc ghi là Suggestion, để tác giả quyết định.
+
+### Bước 5: Phán quyết
+
+| Verdict | Điều kiện | Hành động tiếp theo |
+|---------|-----------|---------------------|
+| ✅ **APPROVED** | Không có Critical, không có Required | Merge / Deploy |
+| ⚠️ **APPROVED_WITH_NOTES** | Không có Critical/Required, chỉ Nit/Optional | Merge được, fix Nit trước hoặc sau |
+| ❌ **CHANGES_REQUIRED** | Có ít nhất 1 Critical hoặc Required | Sửa → review lại |
+
+### Bước 6: Output — Quality Review Report
+
+Tạo `quality-review-report.md` theo format chuẩn bên dưới.
+
+---
+
+## Input
+
+| Loại | Mô tả |
+|------|-------|
+| **Bắt buộc** | Code đã implement / diff thay đổi |
+| **Bắt buộc** | `constitution.md` (coding standards) |
+| **Bắt buộc** | `AGENTS.md` (project conventions, no-go zones) |
+| **Nếu có** | `context.md` (legacy — No-Go Zones) |
+| **Nếu có** | `_session.md` (context từ simplify phase) |
+| **Tùy chọn** | `spec.md` / `plan.md` (để verify intent vs implementation) |
+
+## Output
+
+| File | Mô tả |
+|------|-------|
+| `quality-review-report.md` | Báo cáo review đầy đủ |
+
+---
+
+## Format Output — quality-review-report.md
+
+```markdown
+# Quality Review Report — [YYYY-MM-DD]
+
+## Scope
+- **Target**: [recent diff | path/to/target]
+- **Files reviewed**: [N] files, ~[N] lines
+- **Context**: [sau simplify / trước merge / standalone]
+
+## Findings
+
+### 🔴 Trục 1: Correctness
+[findings hoặc "✅ No material findings"]
+
+### 🟠 Trục 2: Readability & Simplicity
+[findings hoặc "✅ No material findings"]
+
+### 🟡 Trục 3: Architecture
+[findings hoặc "✅ No material findings"]
+
+### 🔵 Trục 4: Security
+[findings hoặc "✅ No material findings"]
+
+### 🟣 Trục 5: Performance
+[findings hoặc "✅ No material findings"]
+
+## Tổng hợp
+
+| Severity | Số lượng |
+|----------|---------|
+| Critical | N |
+| Required | N |
+| Nit | N |
+| Optional | N |
+
+## Residual Risks & Test Gaps
+[Scope chưa được cover, assumptions đã giả định, edge cases chưa test]
+
+## Verdict: [APPROVED | APPROVED_WITH_NOTES | CHANGES_REQUIRED]
+
+**Lý do:** [...]
+```
+
+---
+
+## Quy tắc bắt buộc
+
+1. **Review đủ 5 trục có bằng chứng** — mỗi finding phải có severity + file:line + evidence
+2. **Không rubber-stamp** — "LGTM" trống không được chấp nhận; approve phải kèm scope/residual risk
+3. **Không fix giúp** — chỉ review và đề xuất, không tự sửa code
+4. **Cụ thể đến file + line** — không viết chung chung kiểu "code này phức tạp"
+5. **Đề xuất biện pháp khi flag structural issue** — không chỉ nêu vấn đề
+6. **"No material findings" hợp lệ** — nhưng phải kèm residual risks và test gaps
+
+---
+
+## Quality Gate — Tự kiểm tra trước khi output
+
+| Tiêu chí | Câu hỏi tự kiểm | Nếu KHÔNG → |
+|----------|-----------------|-------------|
+| **5 trục** | "Đã review đủ 5 trục?" | Review trục còn thiếu |
+| **Bằng chứng** | "Mỗi finding có severity + file:line + evidence?" | Thêm bằng chứng |
+| **Residual risk** | "Nếu ít/không finding — đã nêu scope, assumptions, test gaps?" | Bổ sung |
+| **Không rubber-stamp** | "Verdict có kèm lý do cụ thể?" | Thêm justification |
+| **Structural remedy** | "Finding cấu trúc có kèm đề xuất biện pháp?" | Thêm đề xuất |
+
+---
+
+## Xử lý khi gặp vấn đề
+
+| Tình huống | Hành động |
+|-----------|-----------|
+| Code không theo conventions | Required issue, dẫn chiếu `constitution.md` |
+| Không có test coverage | Required issue: đề xuất thêm tests trước merge |
+| Không có material finding | Hợp lệ — double-check security + edge cases, rồi ghi residual risk |
+| File quá lớn (> 1000 LOC total) | Nit/Optional: đề xuất decompose thành modules nhỏ hơn |
+| Dead code phát hiện sau simplify | Suggestion: liệt kê và hỏi tác giả có muốn xóa không |
+| Dependency mới được thêm | Review theo checklist dependency trong skill |
+
+---
+
+## Routing — Bước tiếp theo (Explicit)
+
+```
+✅ APPROVED (0 Critical + 0 Required)
+  → Route: Merge / Deploy
+  → Sau đó: /v.metrics (nếu kết thúc feature)
+
+⚠️ APPROVED_WITH_NOTES (chỉ Nit + Optional)
+  → Route: Merge được, fix Nit before/after theo quyết định tác giả
+  → Sau đó: /v.metrics
+
+❌ CHANGES_REQUIRED (có Critical hoặc Required)
+  → Route: Tác giả sửa → chạy lại /v.code-simplify hoặc /v.review
+  → Nếu > 2 lần CHANGES_REQUIRED → escalate cho human review
+```
+
+## Cập nhật State & Session
+
+**Append vào `_session.md`**:
+```markdown
+### [Quality Review] Code Quality Review — [YYYY-MM-DD]
+- **Agent**: Code Quality Agent
+- **Scope**: [recent diff | path/to/target]
+- **Trục reviewed**: Correctness / Readability / Architecture / Security / Performance
+- **Issues**: Critical=[N], Required=[N], Nit=[N], Optional=[N]
+- **Verdict**: [APPROVED | APPROVED_WITH_NOTES | CHANGES_REQUIRED]
+- **Residual risks**: [tóm tắt nếu có]
+- **Routing**: → [next step]
+```

package/commands/v.code-simplify.md

@@ -0,0 +1,65 @@
+---
+description: "Simplify code for clarity and maintainability — giảm complexity mà không thay đổi behavior"
+phase: "B.1 (post-implement)"
+agent: "simplify-agent"
+---
+
+# /v.code-simplify
+
+> Orchestration wrapper cho **Code Simplify Agent**. Rà soát và đơn giản hóa code vừa thay đổi (hoặc scope được chỉ định) trong khi **đảm bảo behavior không đổi**.
+
+## Điều kiện tiên quyết
+- Code mục tiêu đã có **test coverage** (để xác nhận behavior không thay đổi sau mỗi bước)
+- Build & test suite phải **PASS** trước khi bắt đầu
+
+## Execution
+
+1. Đọc `AGENTS.md` và nắm rõ project conventions, no-go zones
+2. Xác định **target scope** — mặc định là code vừa thay đổi (recent diff); mở rộng nếu user chỉ định
+3. Hiểu rõ mục đích, callers, edge cases, và test coverage của code **trước khi chạm vào**
+4. Quét tìm cơ hội đơn giản hóa:
+   - **Deep nesting** → guard clauses hoặc extracted helpers
+   - **Long functions** → tách theo responsibility
+   - **Nested ternaries** → if/else hoặc switch
+   - **Generic names** → tên mô tả rõ ý định
+   - **Duplicated logic** → shared functions
+   - **Dead code** → xóa sau khi xác nhận không dùng đến
+5. Áp dụng từng thay đổi **incremental** — chạy tests sau mỗi bước
+6. Xác nhận toàn bộ tests PASS, build thành công, và diff sạch
+
+> ⚠️ **Nguyên tắc quan trọng**: Nếu tests fail sau một bước simplification → **revert ngay lập tức** và đánh giá lại. Không dồn nhiều thay đổi vào một lần commit.
+
+---
+
+## 🔀 Routing Rules — Sau Simplify
+
+```
+Simplification hoàn tất + tests PASS
+  → Chạy /v.review (Adversarial Code Review) để validate kết quả
+  → Nếu review = APPROVED         → Merge / tiếp tục pipeline
+  → Nếu review = CHANGES_REQUIRED → Điều chỉnh theo feedback
+```
+
+> Sử dụng skill `code-review-and-quality` trong bước review để đảm bảo chất lượng đầu ra.
+
+## Cập nhật State & Session
+
+**Append vào `_session.md`**:
+```markdown
+### [B.1 Simplify] Code Simplification — [YYYY-MM-DD]
+- **Scope**: [recent diff | path/to/target]
+- **Patterns xử lý**: [deep nesting / long functions / duplicated logic / ...]
+- **Tests**: PASS ([N] tests)
+- **Diff**: [N] files changed, +[N] / -[N] lines
+- **Notes**: [ghi chú nếu có thay đổi bị revert hoặc bỏ qua]
+```
+
+---
+
+## Ví dụ
+
+```
+/v.code-simplify
+/v.code-simplify src/services/payment.ts
+/v.code-simplify --scope src/modules/auth/
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longph2102/v-flow",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "CLI toolkit for V Flow — Agentic AI Software Development Process (Spec-Driven Development)",
   "publishConfig": {
     "access": "public"

package/skills/code-review-and-quantity/SKILL.md

@@ -0,0 +1,397 @@
+---
+name: code-review-and-quality
+description: Thực hiện code review đa chiều. Dùng trước khi merge bất kỳ thay đổi nào. Dùng khi review code do chính bạn, agent khác, hoặc con người viết. Dùng khi cần đánh giá chất lượng code trên nhiều chiều trước khi đưa vào nhánh chính.
+---
+
+# Code Review và Chất Lượng
+
+## Tổng quan
+
+Code review đa chiều với quality gates. Mọi thay đổi đều phải được review trước khi merge — không có ngoại lệ. Review bao gồm năm trục: correctness, readability, architecture, security, và performance.
+
+**Tiêu chuẩn để approve:** Approve một thay đổi khi nó chắc chắn cải thiện sức khỏe tổng thể của codebase, dù không hoàn hảo. Code hoàn hảo không tồn tại — mục tiêu là cải tiến liên tục. Đừng block một thay đổi chỉ vì nó không được viết theo cách bạn muốn. Nếu nó cải thiện codebase và tuân theo conventions của dự án, hãy approve.
+
+## Khi nào dùng
+
+- Trước khi merge bất kỳ PR hay thay đổi nào
+- Sau khi hoàn thành implementation một feature
+- Khi agent hoặc model khác tạo ra code bạn cần đánh giá
+- Khi refactor code hiện tại
+- Sau bất kỳ bug fix nào (review cả fix và regression test)
+
+## Review Năm Trục
+
+Mỗi lần review đánh giá code theo các chiều sau:
+
+### 1. Correctness (Tính đúng đắn)
+
+Code có làm đúng điều nó tuyên bố không?
+
+- Có khớp với spec hoặc yêu cầu task không?
+- Các edge case có được xử lý không (null, empty, boundary values)?
+- Các error path có được xử lý không (không chỉ happy path)?
+- Code có pass tất cả tests không? Tests có thực sự kiểm tra đúng thứ không?
+- Có lỗi off-by-one, race conditions, hay state inconsistencies không?
+
+### 2. Readability & Simplicity (Dễ đọc & Đơn giản)
+
+Engineer (hoặc agent) khác có thể hiểu code này mà không cần tác giả giải thích không?
+
+- Tên biến/hàm có mô tả rõ ràng và nhất quán với conventions dự án không? (Không dùng `temp`, `data`, `result` thiếu context)
+- Control flow có rõ ràng không (tránh nested ternaries, deep callbacks)?
+- Code có được tổ chức logic không (code liên quan nhóm lại, ranh giới module rõ)?
+- Có "trick" nào thông minh quá mức cần đơn giản hóa không?
+- **Code có thể viết ngắn hơn không?** (1000 dòng khi 100 dòng là đủ là thất bại)
+- **Abstraction có xứng với độ phức tạp không?** (Đừng generalize cho đến lần thứ ba dùng lại)
+- Comment có giúp làm rõ ý định không hiển nhiên không? (Nhưng đừng comment code hiển nhiên)
+- Có dead code không: biến no-op (`_unused`), shim backwards-compat, hay comment `// removed`?
+- **Có conditional mới được gắn vào flow không liên quan không?** Đó là design smell, không phải nit — hãy đẩy logic vào helper, state, hoặc policy riêng thay vì làm rối flow hiện có.
+- **Có conditional lặp đi lặp lại trên cùng một shape không?** Chúng là dấu hiệu thiếu model hoặc dispatcher. Một nhánh "tạm thời" thường là nợ kỹ thuật vĩnh viễn.
+
+### 3. Architecture (Kiến trúc)
+
+Thay đổi có phù hợp với thiết kế của hệ thống không?
+
+- Nó có theo các pattern hiện có hay giới thiệu pattern mới không? Nếu mới, có được justification không?
+- Nó có duy trì ranh giới module sạch không?
+- Có code duplication cần được share không?
+- Dependencies có đi đúng chiều không (không có circular dependencies)?
+- Mức abstraction có phù hợp không (không over-engineer, không quá coupled)?
+- **Refactor này có giảm complexity hay chỉ chuyển chỗ nó?** Đếm số khái niệm người đọc phải nắm để theo dõi thay đổi. Nếu một phiên bản "sạch hơn" giữ nguyên con số đó, nó không sạch hơn — ưu tiên tái cấu trúc làm biến mất toàn bộ nhánh, mode, hoặc layer hơn là re-centralize cùng logic. Ưu tiên xóa abstraction hơn là đánh bóng nó.
+- **Logic đặc thù cho feature có bị leak vào module shared/general-purpose không?** Giữ logic trong layer sở hữu nó, tái sử dụng canonical helper hiện có thay vì near-duplicate, và không normalize architectural drift.
+- **Ranh giới type có tường minh không?** Đặt câu hỏi với `any`/`unknown`/optional/cast tùy tiện và silent fallback che giấu invariant chưa rõ — làm tường minh ranh giới thường làm control flow xung quanh đơn giản hơn.
+
+### 4. Security (Bảo mật)
+
+Để hướng dẫn security chi tiết, xem `security-and-hardening`. Thay đổi có gây ra lỗ hổng bảo mật không?
+
+- Input của user có được validate và sanitize không?
+- Secrets có được giữ ngoài code, log, và version control không?
+- Authentication/authorization có được kiểm tra đúng chỗ không?
+- SQL query có được parameterize không (không nối chuỗi)?
+- Output có được encode để chống XSS không?
+- Dependencies có từ nguồn tin cậy và không có known vulnerabilities không?
+- Dữ liệu từ nguồn ngoài (APIs, logs, user content, config files) có được coi là untrusted không?
+- Các luồng dữ liệu ngoài có được validate tại system boundaries trước khi dùng trong logic hoặc render không?
+
+### 5. Performance (Hiệu năng)
+
+Để profiling và optimization chi tiết, xem `performance-optimization`. Thay đổi có gây ra vấn đề hiệu năng không?
+
+- Có pattern N+1 query không?
+- Có vòng lặp không giới hạn hay data fetching không ràng buộc không?
+- Có synchronous operation nào nên là async không?
+- Có re-render không cần thiết trong UI components không?
+- Có pagination bị thiếu ở list endpoints không?
+- Có object lớn được tạo trong hot paths không?
+
+## Biện pháp Cấu trúc
+
+Khi bạn phát hiện vấn đề cấu trúc, hãy đề xuất giải pháp — không chỉ nêu vấn đề. Review chỉ nói "cái này phức tạp" khiến tác giả đoán mò. Dùng tên tái cấu trúc cụ thể:
+
+- **Thay chuỗi conditionals** bằng typed model hoặc explicit dispatcher.
+- **Gộp các nhánh duplicate** thành một flow rõ ràng hơn.
+- **Tách orchestration khỏi business logic** để mỗi phần có thể đọc độc lập.
+- **Di chuyển logic đặc thù cho feature** ra khỏi shared module, vào package sở hữu khái niệm đó.
+- **Tái sử dụng canonical helper** thay vì near-duplicate tự tạo.
+- **Làm tường minh type boundary** để downstream branching biến mất.
+- **Xóa pass-through wrapper** tạo thêm indirection mà không làm rõ API.
+- **Extract helper, hoặc tách file lớn** thành các module tập trung.
+
+Ưu tiên biện pháp loại bỏ moving pieces hơn là biện pháp phân tán cùng complexity.
+
+## Quy mô Thay đổi
+
+Thay đổi nhỏ, tập trung dễ review hơn, merge nhanh hơn, và deploy an toàn hơn. Nhắm đến các quy mô sau:
+
+```
+~100 dòng thay đổi   → Tốt. Có thể review trong một lần ngồi.
+~300 dòng thay đổi   → Chấp nhận được nếu là một thay đổi logic duy nhất.
+~1000 dòng thay đổi  → Quá lớn. Hãy tách ra.
+```
+
+**Chú ý kích thước file, không chỉ kích thước diff.** Một diff nhỏ vẫn có thể đẩy file vượt ngưỡng lành mạnh — khoảng 1000 *tổng* dòng trong một file là tín hiệu cần kiểm tra, không phải giới hạn cứng. Khi một thay đổi làm phình file vốn đã lớn, hãy hỏi có nên extract helpers, subcomponents, hoặc modules *trước* không, rồi mới thêm vào. Decompose trước, rồi thêm sau.
+
+**Thế nào là "một thay đổi":** Một modification tự hoàn chỉnh giải quyết một vấn đề, bao gồm tests liên quan, và giữ hệ thống hoạt động sau khi submit. Một phần của feature — không phải toàn bộ feature.
+
+**Chiến lược tách khi thay đổi quá lớn:**
+
+| Chiến lược | Cách làm | Khi nào dùng |
+|----------|-----|------|
+| **Stack** | Submit thay đổi nhỏ, bắt đầu thay đổi tiếp theo dựa trên nó | Sequential dependencies |
+| **Theo nhóm file** | Tách riêng cho nhóm file cần reviewer khác nhau | Cross-cutting concerns |
+| **Horizontal** | Tạo shared code/stubs trước, rồi đến consumers | Layered architecture |
+| **Vertical** | Chia thành các full-stack slice nhỏ hơn của feature | Feature work |
+
+**Khi nào thay đổi lớn được chấp nhận:** Xóa file hoàn toàn và automated refactoring nơi reviewer chỉ cần xác nhận ý định, không phải từng dòng.
+
+**Tách riêng refactoring khỏi feature work.** Thay đổi vừa refactor code hiện có vừa thêm behavior mới là hai thay đổi — submit riêng. Cleanup nhỏ (đổi tên biến) có thể đưa vào theo quyết định của reviewer.
+
+## Mô tả Thay đổi
+
+Mỗi thay đổi cần một mô tả tự đứng vững trong lịch sử version control.
+
+**Dòng đầu tiên:** Ngắn, dùng imperative, độc lập. "Xóa FizzBuzz RPC" không phải "Đang xóa FizzBuzz RPC." Phải đủ thông tin để ai đó tìm kiếm lịch sử có thể hiểu thay đổi mà không cần đọc diff.
+
+**Body:** Cái gì đang thay đổi và tại sao. Bao gồm context, quyết định, và lý do không thấy được trong code. Link đến bug numbers, benchmark results, hoặc design docs khi liên quan. Thừa nhận shortcomings của approach khi chúng tồn tại.
+
+**Anti-patterns:** "Fix bug," "Fix build," "Add patch," "Moving code from A to B," "Phase 1," "Add convenience functions."
+
+## Quy trình Review
+
+### Bước 1: Hiểu Context
+
+Trước khi nhìn code, hãy hiểu ý định:
+
+```
+- Thay đổi này nhằm hoàn thành điều gì?
+- Nó implement spec hoặc task nào?
+- Thay đổi behavior mong đợi là gì?
+```
+
+### Bước 2: Review Tests Trước
+
+Tests thể hiện ý định và coverage:
+
+```
+- Có tests cho thay đổi không?
+- Chúng có test behavior (không phải implementation details) không?
+- Các edge case có được cover không?
+- Tests có tên mô tả rõ không?
+- Tests có phát hiện được regression nếu code thay đổi không?
+```
+
+### Bước 3: Review Implementation
+
+Đi qua code với năm trục trong đầu:
+
+```
+Với mỗi file thay đổi:
+1. Correctness: Code này có làm điều test nói nó nên làm không?
+2. Readability: Tôi có thể hiểu điều này mà không cần trợ giúp không?
+3. Architecture: Điều này có phù hợp với hệ thống không?
+4. Security: Có lỗ hổng bảo mật nào không?
+5. Performance: Có bottleneck nào không?
+```
+
+### Bước 4: Phân loại Phát hiện
+
+Gắn nhãn mỗi comment với severity để tác giả biết cái gì bắt buộc vs tùy chọn:
+
+| Prefix | Ý nghĩa | Hành động của tác giả |
+|--------|---------|---------------|
+| *(không prefix)* | Thay đổi bắt buộc | Phải xử lý trước khi merge |
+| **Critical:** | Chặn merge | Lỗ hổng bảo mật, mất dữ liệu, chức năng bị hỏng |
+| **Nit:** | Nhỏ, tùy chọn | Tác giả có thể bỏ qua — định dạng, style preferences |
+| **Optional:** / **Consider:** | Gợi ý | Đáng cân nhắc nhưng không bắt buộc |
+| **FYI** | Chỉ thông tin | Không cần hành động — context cho tương lai |
+
+Điều này ngăn tác giả coi tất cả feedback là bắt buộc và lãng phí thời gian cho gợi ý tùy chọn.
+
+**Đưa điều quan trọng lên trước.** Sắp xếp phát hiện theo leverage: correctness và security trước, rồi đến structural regressions và missed simplifications, rồi mới đến phần còn lại. Đừng chôn vùi vấn đề thực sự dưới cosmetic nits — một vài comment có conviction cao hơn là một danh sách dài. Nếu bạn có một vấn đề cấu trúc và mười nits, vấn đề cấu trúc *chính là* review.
+
+### Bước 5: Xác minh Việc Kiểm tra
+
+Kiểm tra câu chuyện verification của tác giả:
+
+```
+- Những tests nào đã được chạy?
+- Build có pass không?
+- Thay đổi có được test thủ công không?
+- Có screenshots cho UI changes không?
+- Có so sánh before/after không?
+```
+
+## Pattern Review Đa Model
+
+Dùng các model khác nhau cho góc nhìn review khác nhau:
+
+```
+Model A viết code
+    │
+    ▼
+Model B review correctness và architecture
+    │
+    ▼
+Model A xử lý feedback
+    │
+    ▼
+Con người ra quyết định cuối
+```
+
+Cách này phát hiện vấn đề mà một model đơn lẻ có thể bỏ sót — các model khác nhau có blind spots khác nhau.
+
+**Ví dụ prompt cho review agent:**
+```
+Review thay đổi code này về correctness, security, và tuân thủ
+conventions dự án. Spec nói [X]. Thay đổi nên [Y].
+Gắn cờ mọi vấn đề là Critical, Required, Optional, hoặc Nit.
+```
+
+## Dọn dẹp Dead Code
+
+Sau bất kỳ refactoring hay implementation change nào, kiểm tra code mồ côi:
+
+1. Xác định code không còn reachable hay được dùng nữa
+2. Liệt kê rõ ràng
+3. **Hỏi trước khi xóa:** "Tôi có nên xóa các phần tử không còn dùng này không: [list]?"
+
+Đừng để dead code nằm lại — nó gây nhầm lẫn cho người đọc và agent tương lai. Nhưng đừng xóa thầm lặng những thứ bạn không chắc chắn. Khi không chắc, hãy hỏi.
+
+```
+DEAD CODE ĐÃ XÁC ĐỊNH:
+- formatLegacyDate() trong src/utils/date.ts — đã được thay bởi formatDate()
+- OldTaskCard component trong src/components/ — đã được thay bởi TaskCard
+- Hằng LEGACY_API_URL trong src/config.ts — không còn tham chiếu nào
+→ Có thể xóa những thứ này không?
+```
+
+## Tốc độ Review
+
+Review chậm cản trở cả team. Chi phí context-switching để review ít hơn chi phí chờ đợi áp đặt lên người khác.
+
+- **Phản hồi trong một ngày làm việc** — đây là tối đa, không phải mục tiêu
+- **Nhịp lý tưởng:** Phản hồi ngay sau khi yêu cầu review đến, trừ khi đang tập trung code. Thay đổi thông thường nên hoàn thành nhiều vòng review trong một ngày
+- **Ưu tiên phản hồi cá nhân nhanh** hơn là approval cuối nhanh. Feedback nhanh giảm sự thất vọng dù cần nhiều vòng
+- **Thay đổi lớn:** Yêu cầu tác giả tách ra thay vì review một changeset khổng lồ
+
+## Xử lý Bất đồng
+
+Khi giải quyết tranh chấp review, áp dụng thứ tự ưu tiên này:
+
+1. **Sự thật và dữ liệu kỹ thuật** vượt trội hơn ý kiến và sở thích
+2. **Style guides** là thẩm quyền tuyệt đối về vấn đề style
+3. **Thiết kế phần mềm** phải được đánh giá dựa trên nguyên tắc kỹ thuật, không phải sở thích cá nhân
+4. **Nhất quán codebase** chấp nhận được nếu không làm giảm sức khỏe tổng thể
+
+**Đừng chấp nhận "Tôi sẽ dọn sau."** Kinh nghiệm cho thấy cleanup hoãn lại hiếm khi xảy ra. Yêu cầu cleanup trước khi submit trừ khi đây là tình huống khẩn cấp thực sự. Nếu các vấn đề xung quanh không thể xử lý trong thay đổi này, yêu cầu tạo bug với self-assignment.
+
+## Trung thực trong Review
+
+Khi review code — dù do bạn, agent khác, hay con người viết:
+
+- **Đừng rubber-stamp.** "LGTM" mà không có bằng chứng review không giúp ích gì.
+- **Đừng làm mềm vấn đề thực sự.** "Đây có thể là lo ngại nhỏ" khi thực ra là bug sẽ xảy ra trên production là không trung thực.
+- **Định lượng vấn đề khi có thể.** "N+1 query này sẽ thêm ~50ms mỗi item trong list" tốt hơn "cái này có thể chậm."
+- **Phản đối approach có vấn đề rõ ràng.** Sycophancy là failure mode trong review. Nếu implementation có vấn đề, nói thẳng và đề xuất alternatives.
+- **Chấp nhận override một cách graceful.** Nếu tác giả có đầy đủ context và không đồng ý, nhường theo quyết định của họ. Comment về code, không phải về người — diễn đạt lại phê bình cá nhân để tập trung vào code.
+
+## Kỷ luật Dependencies
+
+Một phần của code review là dependency review:
+
+**Trước khi thêm bất kỳ dependency nào:**
+1. Stack hiện tại có giải quyết được vấn đề không? (Thường là có.)
+2. Dependency này lớn bao nhiêu? (Kiểm tra bundle impact.)
+3. Nó có được bảo trì tích cực không? (Kiểm tra last commit, open issues.)
+4. Nó có known vulnerabilities không? (`npm audit`)
+5. License là gì? (Phải tương thích với dự án.)
+
+**Quy tắc:** Ưu tiên standard library và utilities hiện có hơn dependencies mới. Mỗi dependency là một liability.
+
+**Nâng cấp dependency hiện có** là thay đổi code như mọi thay đổi khác, và các nâng cấp rủi ro nhất là những cái được merge hàng loạt với message "bump deps." Review chúng với cùng kỷ luật:
+
+1. **Đọc changelog, không chỉ version number.** Semver là lời hứa mà maintainer có thể không giữ — một bản "patch" có thể mang thay đổi behavior. Với major bump, đọc migration notes và tìm cái gì bị break.
+2. **Một dependency mỗi thay đổi.** Nâng cấp và merge từng cái riêng lẻ (hoặc nhóm nhỏ liên quan). Khi bulk bump phá vỡ build, bạn đã mất dấu vết package nào gây ra; thay đổi một package duy nhất làm nguyên nhân rõ ràng và revert sạch sẽ.
+3. **Để tests quyết định.** Nâng cấp được xác minh bởi suite xanh trước *và* sau, không phải bởi "nó đã install." Nếu coverage xung quanh behavior của dependency mỏng, đó là phát hiện thực sự — thêm test trước.
+4. **Chú ý transitive graph.** Hầu hết packages được cài là những package không ai chọn trực tiếp. Review lockfile diff, không chỉ `package.json`; một direct bump đơn lẻ có thể kéo theo hàng chục indirect changes.
+5. **Giữ lockfile trung thực.** Commit nó, review diff của nó, và không bao giờ sửa tay. Lockfile là thứ thực sự ghim cái được ship.
+
+Để triage các phát hiện `npm audit` và supply-chain risk (typosquatting, compromised maintainers), theo skill `security-and-hardening` — phần này bao gồm *workflow* nâng cấp, phần kia bao gồm security verdict.
+
+## Checklist Review
+
+```markdown
+## Review: [Tiêu đề PR/Thay đổi]
+
+### Context
+- [ ] Tôi hiểu thay đổi này làm gì và tại sao
+
+### Correctness
+- [ ] Thay đổi khớp với yêu cầu spec/task
+- [ ] Edge cases được xử lý
+- [ ] Error paths được xử lý
+- [ ] Tests cover thay đổi đầy đủ
+
+### Readability
+- [ ] Tên rõ ràng và nhất quán
+- [ ] Logic đơn giản
+- [ ] Không có complexity không cần thiết
+
+### Architecture
+- [ ] Theo đúng patterns hiện có
+- [ ] Không coupling hay dependencies không cần thiết
+- [ ] Mức abstraction phù hợp
+- [ ] Refactor giảm complexity thay vì chuyển chỗ nó
+- [ ] Không có logic feature trong shared modules; file giữ kích thước lành mạnh
+
+### Security
+- [ ] Không có secrets trong code
+- [ ] Input được validate tại boundaries
+- [ ] Không có injection vulnerabilities
+- [ ] Auth checks đúng chỗ
+- [ ] Dữ liệu nguồn ngoài được coi là untrusted
+
+### Performance
+- [ ] Không có pattern N+1
+- [ ] Không có unbounded operations
+- [ ] Pagination tại list endpoints
+
+### Verification
+- [ ] Tests pass
+- [ ] Build thành công
+- [ ] Đã verify thủ công (nếu áp dụng)
+
+### Verdict
+- [ ] **Approve** — Sẵn sàng merge
+- [ ] **Request changes** — Vấn đề phải được xử lý
+```
+
+## Xem thêm
+
+- Để hướng dẫn security review chi tiết, xem `../../references/security-checklist.md`
+- Để kiểm tra performance review, xem `../../references/performance-checklist.md`
+
+## Các Lý do Tự biện Phổ biến
+
+| Lý do tự biện | Thực tế |
+|---|---|
+| "Nó chạy được, vậy là đủ tốt" | Code chạy được nhưng không đọc được, không bảo mật, hoặc sai kiến trúc tạo ra nợ kỹ thuật tích lũy theo thời gian. |
+| "Tôi viết nó, nên tôi biết nó đúng" | Tác giả mù quáng với các giả định của chính mình. Mọi thay đổi đều được lợi từ một cặp mắt khác. |
+| "Chúng ta sẽ dọn sau" | Sau không bao giờ đến. Review là quality gate — hãy dùng nó. Yêu cầu cleanup trước khi merge, không phải sau. |
+| "Code AI tạo ra chắc ổn thôi" | Code AI cần được kiểm tra kỹ hơn, không phải ít hơn. Nó tự tin và hợp lý, ngay cả khi sai. |
+| "Tests pass, vậy là tốt" | Tests là cần thiết nhưng không đủ. Chúng không phát hiện vấn đề kiến trúc, lỗ hổng bảo mật, hay vấn đề readability. |
+| "Refactor làm nó sạch hơn" | Chuyển chỗ complexity không phải giảm nó. Nếu người đọc vẫn phải nắm cùng số khái niệm, cấu trúc không cải thiện — tìm phiên bản làm biến mất các nhánh. |
+| "Chỉ là thêm nhỏ vào file này thôi" | Diff nhỏ vẫn đẩy file vượt kích thước lành mạnh và gắn nhánh vào flow không liên quan. Đánh giá cấu trúc kết quả, không phải kích thước diff. |
+| "Chỉ là bump version thôi" | Bump là thay đổi behavior bạn không viết. Đọc changelog; semver không đảm bảo không có breaking changes. |
+| "Tôi sẽ nâng cấp tất cả trong một PR để tiết kiệm thời gian" | Bulk bump phá vỡ build che giấu package nào gây ra. Một dependency mỗi thay đổi giữ nguyên nhân và revert sạch sẽ. |
+
+## Dấu hiệu Đỏ
+
+- PR được merge mà không có review
+- Review chỉ kiểm tra tests có pass không (bỏ qua các trục khác)
+- "LGTM" mà không có bằng chứng review thực sự
+- Thay đổi liên quan security mà không có security-focused review
+- PR lớn "quá lớn để review đúng cách" (hãy tách ra)
+- Không có regression tests với bug fix PR
+- Review comments không có severity label — không rõ cái gì bắt buộc vs tùy chọn
+- Chấp nhận "Tôi sẽ sửa sau" — không bao giờ xảy ra
+- Refactor chuyển chỗ code mà không giảm số khái niệm người đọc phải nắm
+- Thay đổi làm phình file vốn đã lớn thay vì decompose nó
+- Conditional mới rải vào code paths không liên quan (thiếu abstraction)
+- Helper tự tạo duplicate canonical helper hiện có, hoặc logic feature trong shared module
+- PR "bump dependencies" hàng loạt không có changelog review và không isolate theo package
+- Lockfile bị sửa tay, không commit, hoặc merge mà không review diff của nó
+
+## Verification
+
+Sau khi review hoàn tất:
+
+- [ ] Tất cả Critical issues đã được giải quyết
+- [ ] Tất cả thay đổi Required (không prefix) đã được giải quyết hoặc hoãn có justification rõ ràng
+- [ ] Tests pass
+- [ ] Build thành công
+- [ ] Câu chuyện verification được ghi lại (cái gì thay đổi, cách verify)
+- [ ] Nâng cấp dependency được review theo changelog, isolate theo package, và verify bởi suite xanh với lockfile diff được review
+
+**Blockers suy đoán:** surface và đề xuất design đơn giản hơn cho từng cái; escalate lên Required chỉ khi thay đổi chủ động làm cấu trúc tệ hơn: refactor chuyển chỗ complexity thay vì giảm nó; thay đổi đẩy file vượt ngưỡng kích thước mà không decompose; logic feature thêm vào shared module; near-duplicate của canonical helper hiện có; silent fallback che giấu invariant chưa rõ.