ai-developer-skill-os 9.3.0 → 10.1.0

package/.agents/skills/qk-code-cleaner/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: qk-code-cleaner
+version: 10.1.0
+status: stable
+subtitle: "Refactor & Viết Test"
+description: "Kỹ nghệ Tái cấu trúc (Zero Behavior Change), Nâng cấp thư viện an toàn có Rollback và Xây dựng lưới kiểm thử tự động. Dùng khi: refactor code, tái cấu trúc hàm/file, extract function/hook, clean code, giảm độ phức tạp cyclomatic, nâng cấp dependency package, audit breaking changes, viết unit/integration test — TUYỆT ĐỐI KHÔNG dùng khi chỉ sửa bug đơn lẻ (dùng qk-bug-resolution) hoặc build tính năng mới (dùng qk-feature-delivery)."
+tools:
+  - filesystem
+  - terminal
+rules:
+  - global
+  - coding-standards
+  - safety
+workflow: refactor
+triggers:
+  - "refactor"
+  - "tái cấu trúc"
+  - "tách file quá dài"
+  - "extract function"
+  - "extract hook"
+  - "clean code"
+  - "giảm complexity"
+  - "nâng cấp thư viện"
+  - "upgrade package"
+  - "migrate framework"
+  - "cập nhật dependency"
+  - "viết unit test"
+  - "viết test"
+  - "integration test"
+  - "test strategy"
+---
+
+# qk-code-cleaner — Refactor & Viết Test (Modernization & Test Safety Engine)
+
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+---
+
+## 1. Nguyên Tắc Cốt Lõi & Luật Chống Over-Engineering
+
+> **Core Principle:** Metrics are signals, not goals. Never refactor code merely to satisfy a metric. Optimize for maintainability, correctness, testability, and minimal risk.
+> **Verification Principle:** PASS is a verified conclusion, never a target. Zero workarounds.
+
+### 🛡️ Anti-Overengineering Rule (BẮT BUỘC TUÂN THỦ)
+- **Cấm trừu tượng hóa quá đà:** Tuyệt đối KHÔNG tự ý tạo Design Patterns phức tạp (Abstract Factory, Decorator, Strategy...), Interfaces tầng tầng lớp lớp, Generic Wrappers, hay Custom Hooks nếu không mang lại lợi ích cụ thể, thực tế và rõ ràng cho việc đọc hiểu hoặc kiểm thử.
+- **Ưu tiên giải pháp tối thiểu:** Luôn chọn sự thay đổi cấu trúc nhỏ nhất (smallest structural change) mà giải quyết được vấn đề bảo trì. 3 dòng code tường minh tốt hơn 30 dòng code pattern trừu tượng.
+- **Không chạm vào code đang chạy tốt:** Nếu một đoạn code dài nhưng mạch lạc, có tính bao đóng tốt và không có yêu cầu thay đổi, KHÔNG ĐƯỢC phép xé nhỏ nó chỉ để chạy theo chỉ tiêu số dòng.
+
+### 🔒 No Unrelated Changes Rule (CẤM SỬA LAN MAN)
+- Chỉ sửa các file, hàm hoặc package nằm trong phạm vi tái cấu trúc được yêu cầu.
+- **CẤM** reformat hoặc format lại các file lân cận không thuộc scope.
+- **CẤM** đổi tên biến, signature hàm của các module khác ngoài phạm vi.
+- Nếu phát hiện code smell hoặc vấn đề ngoài scope: **Chỉ ghi nhận vào báo cáo**, tuyệt đối không tự ý chạm vào.
+
+### 🛡️ Anti-Fake-Pass Rule (CẤM ÉP PASS ẢO - R-G-14.5)
+- **CẤM** dùng `as any`, `@ts-ignore`, hoặc `@ts-expect-error` để giấu lỗi type sau khi refactor.
+- **CẤM** làm yếu assertions (weakening assertions), xóa test case hoặc skip test đang fail chỉ để test suite xanh.
+- **CẤM** dùng `catch (e) {}` rỗng để nuốt ngoại lệ.
+
+### ⚖️ Verify Before Claim Rule (CHỐNG BỐC PHÉT DỮ LIỆU)
+- **Chạy lệnh trước khi báo cáo:** Tuyệt đối **KHÔNG ĐƯỢC** tuyên bố "Tests pass", "Types clean", "Build successful", hay "Zero behavior change" nếu chưa thực sự thực thi các câu lệnh kiểm chứng trong terminal (`npm test`, `pytest`, `tsc --noEmit`).
+- **Trung thực khi không chạy được:** Nếu môi trường thiếu dependencies, thiếu database test, hoặc lệnh test không khả dụng, AI **BẮT BUỘC** ghi rõ: `"Trạng thái: NOT VERIFIED — Chưa kiểm chứng bằng lệnh thực tế (Cần user verify thủ công)"`. Cấm bịa đặt số lượng test hay kết quả 100% ảo.
+
+---
+
+## 2. Ranh Giới & Tiêu Chí Phân Định (Decision Rules)
+
+### Khi nào CẦN và KHÔNG CẦN can thiệp:
+1. **File dài (> 300 dòng):**
+   - *Hướng dẫn:* File vượt quá 300 dòng **phải được xem xét (reviewed for decomposition)**, nhưng CHỈ BẮT BUỘC TÁCH khi file có quá nhiều trách nhiệm (vi phạm SRP), logic lộn xộn, hoặc khó kiểm thử.
+   - *Ngoại lệ:* Schema files, DTOs, configurations, code sinh tự động (generated code), hoặc component có cấu trúc đơn khối rõ ràng thì 400-500 dòng vẫn được phép giữ nguyên.
+2. **Hàm dài (> 40 dòng) & Nesting sâu (> 3 tầng):**
+   - Áp dụng **Guard Clauses (Early Return)** để triệt tiêu các khối `if/else` lồng nhau.
+   - Tách các đoạn logic tính toán phức tạp thành các Pure Helper Functions độc lập.
+3. **Chiến lược Test Pyramid (Target Guideline):**
+   - *Định hướng:* Ưu tiên kim tự tháp kiểm thử nghiêng về Unit Tests (chạy nhanh, cô lập), kế đến là Integration Tests, và số ít E2E Tests trọng yếu.
+   - *Tính linh hoạt:* Tỷ lệ 70/20/10 là mục tiêu tham chiếu (Guideline), không phải giáo điều bắt buộc. Tùy thuộc vào bản chất dự án (CRUD, Data pipeline hay UI library) mà điều chỉnh tỷ lệ phù hợp.
+
+### Planning Gate & Exceptions:
+- Với tác vụ thay đổi ≥ 2 files hoặc nâng cấp major package, BẮT BUỘC lập `implementation_plan.md` với `RequestFeedback: true` và dừng lại chờ phê duyệt.
+- **Ngoại lệ bỏ qua Planning Gate:**
+  - Tái cấu trúc chỉ nằm trong duy nhất 1 file (Single-file refactor).
+  - Tinh chỉnh Guard Clauses nhỏ hoặc thêm type annotation đơn giản.
+  - Người dùng chỉ định rõ ràng yêu cầu thực thi ngay lập tức.
+
+### Ranh giới chuyển giao (Scope Handoff):
+- ❌ Nếu phát hiện bug logic trong code cũ → Chuyển sang `qk-bug-resolution`.
+- ❌ Nếu cần phát triển tính năng mới → Chuyển sang `qk-feature-delivery`.
+
+---
+
+## 3. Quy Trình Thực Thi Tuần Tự 5 Bước (Sequential Procedure)
+
+Mọi tác vụ Tái cấu trúc / Nâng cấp / Viết test BẮT BUỘC tuân thủ đúng thứ tự:
+
+```
+[Bước 1: Baseline Check]      ── Chạy test/type hiện có, đo lường hiện trạng trước khi đụng vào code
+            │
+            ▼
+[Bước 2: Safety Net Harness]  ── Nếu module chưa có test, viết Characterization Test bảo vệ hiện trạng
+            │
+            ▼
+[Bước 3: Planning Gate]       ── Nếu sửa ≥ 2 files, tạo plan & chờ duyệt (trừ trường hợp ngoại lệ)
+            │
+            ▼
+[Bước 4: Incremental Refactor]── Sửa từng bước nhỏ (Surgical), áp dụng Guard Clauses, bump từng pkg
+            │
+            ▼
+[Bước 5: Verify or Rollback]  ── Chạy lại test thật. Nếu FAIL ──► Kích hoạt Failure Protocol (Revert ngay)
+```
+
+### Chi tiết từng bước:
+- **Bước 1: Baseline Check:** Chạy bộ test hoặc type-check hiện có để biết hệ thống ban đầu xanh hay đỏ. Không refactor trên nền tảng đang bị gãy mà không báo trước cho user.
+- **Bước 2: Safety Net Harness (Lưới an toàn):** Nếu code cũ không có test, hãy tạo một file test nhỏ kiểm chứng các đầu vào - đầu ra quan trọng hiện thời (Characterization Tests) trước khi đổi cấu trúc.
+- **Bước 3: Planning Gate:** Nếu tác vụ thay đổi ≥ 2 files hoặc nâng cấp major package, tạo artifact `implementation_plan.md` với `RequestFeedback: true` theo mẫu ở Mục 5 và dừng lại chờ phê duyệt (trừ ngoại lệ).
+- **Bước 4: Incremental Refactoring:**
+  - Tái cấu trúc từng khối nhỏ một. Không sửa đồng loạt nhiều module.
+  - Áp dụng Guard Clauses loại bỏ if lồng nhau.
+- **Bước 5: Verification & Zero Behavior Change:**
+  - Chạy lại test suite. Đối chiếu đầu ra đảm bảo 100% khớp với baseline.
+  - CẤM mọi hành vi ép test pass bằng cách sửa assertion hay ép kiểu bẩn.
+
+---
+
+## 4. Xử Lý Sự Cố & Kế Hoạch Khôi Phục (Failure Path & Rollback)
+
+### 🚨 Khi kiểm thử thất bại (Test Fail) hoặc Behavior bị sai lệch:
+1. **Dừng ngay lập tức:** Không cố chấp viết thêm code "vá chằng vá đụp" lên đoạn refactor hỏng.
+2. **Kích hoạt Revert Bước Vừa Làm:**
+   ```bash
+   # Nếu chỉ sửa 1 file:
+   git checkout HEAD -- path/to/file.ts
+   # Nếu đã sửa nhiều file trong workspace:
+   git restore <các_file_vừa_sửa>
+   ```
+3. **Phân tích Delta (Nguyên nhân thất bại):** Xác định tại sao thay đổi nhỏ đó lại làm đổi behavior (Side-effect ngầm? Mutation ẩn? Thứ tự promise bị đảo lộn?).
+4. **Hạ quy mô (Step-down):** Thử lại với bước tái cấu trúc nhỏ hơn một nửa. Nếu vẫn không an toàn, báo cáo dừng lại và giữ nguyên code gốc.
+
+### 📦 Khi nâng cấp Package gặp xung đột (Dependency Conflict / Lockfile):
+1. **Khôi phục ngay:** `git checkout HEAD -- package.json package-lock.json pnpm-lock.yaml`
+2. **Không ép buộc (No `--force` / `--legacy-peer-deps` bừa bãi):** Tìm hiểu chính xác package nào xung đột peer dependency từ changelog, đề xuất user nâng cấp đồng thời hoặc tìm thư viện thay thế.
+
+---
+
+## 5. Khung Kế Hoạch Chuẩn (Implementation Plan Skeleton)
+
+Khi tạo artifact `implementation_plan.md` cho các tác vụ ≥ 2 files:
+
+```markdown
+# Implementation Plan: [Refactor / Upgrade / Testing] - [Tên Module]
+
+## 1. Mục tiêu & Giới hạn phạm vi
+- Mục tiêu: [Cải thiện khả năng đọc / Tách file Service / Thêm unit tests]
+- Cam kết: 100% Zero Behavior Change. Không đổi API contracts hay DB schema.
+
+## 2. Rủi ro & Điểm nhạy cảm
+- [Rủi ro tiềm ẩn, ví dụ: Hàm X có side-effect ngầm, Package Y có breaking change ở v2]
+
+## 3. Các bước thực hiện từng file
+- [ ] [TênFileGốc.ts](file:///<workspace-root>/src/...): Trích xuất logic X sang Helper
+- [ ] [NEW] [TênFileMới.ts](file:///<workspace-root>/src/...): Nhận các pure functions
+- [ ] [TênTest.test.ts](file:///<workspace-root>/tests/...): Chạy kiểm chứng
+
+## 4. Kế hoạch Rollback tức thì
+- Lệnh khôi phục: `git restore src/path/to/files`
+```
+
+---
+
+## 6. Mẫu Code Đa Ngôn Ngữ Thực Chiến (Guard Clauses)
+
+### TypeScript Pattern:
+```typescript
+// ❌ Cũ: Lồng ghép sâu, khó đọc
+function processOrder(order: Order | null, user: User | null) {
+  if (order) {
+    if (user && user.isActive) {
+      if (order.items.length > 0) {
+        return calculateTotal(order);
+      }
+    }
+  }
+  return null;
+}
+
+// ✅ Mới: Tường minh, phẳng hóa logic bằng Early Return
+function processOrder(order: Order | null, user: User | null): number | null {
+  if (!order || !user) return null;
+  if (!user.isActive) return null;
+  if (order.items.length === 0) return null;
+
+  return calculateTotal(order);
+}
+```
+
+### Python Pattern:
+```python
+# ❌ Cũ: Nesting lồng nhau
+def calculate_discount(order, customer):
+    if order is not None:
+        if customer and customer.is_active:
+            if order.total_amount > 1000:
+                return order.total_amount * 0.1
+    return 0.0
+
+# ✅ Mới: Guard Clauses đanh thép
+def calculate_discount(order, customer) -> float:
+    if not order or not customer or not customer.is_active:
+        return 0.0
+    if order.total_amount <= 1000:
+        return 0.0
+
+    return order.total_amount * 0.1
+```
+
+---
+
+## 7. Thích Ứng Theo Role Kỹ Thuật (Role Adaptation)
+
+| Role | Trọng tâm khi Refactor & Viết Test | Hành vi kỹ thuật đặc thù |
+|---|---|---|
+| `frontend` | Tách nhỏ UI component, trích xuất custom hooks, tối ưu re-render | Tách container/presentational, Memoization, component unit test |
+| `backend` | Tách God Service, áp dụng Dependency Injection, chuẩn hóa DTOs | Phân tầng Controller-Service-Repo, Unit test Service với mocked repository |
+| `fullstack` | Đồng bộ hóa contracts, refactor shared types, end-to-end integration | Đồng bộ schemas giữa client/server, viết integration test luồng dữ liệu |
+| `qa` | Thiết kế Test Matrix, tự động hóa regression test suites | Viết test cases biên (boundary analysis), mock scenarios |
+| `data` | Refactor complex SQL queries, module hóa dbt models | Chia nhỏ staging/intermediate/marts models trong dbt, dbt tests |
+
+---
+
+## 8. Báo Cáo Nghiệm Thu Chuẩn Xác (Truth-First Report)
+
+```markdown
+🧹 Code Cleaner Summary                               [Role: <role> | Task: <Tên công việc>]
+─────────────────────────────────────────────────────────────────────
+Trạng thái:          [SUCCESS | BLOCKED | FAILED | PARTIAL]
+Phạm vi thực tế:    [N files đã chỉnh sửa / tạo mới]
+Cam kết tính năng:  ✅ Zero Behavior Change (Hành vi bên ngoài giữ nguyên 100%)
+
+Chi tiết cải thiện (Laser Focus):
+  • [Loại thay đổi]: [Tên file và chi tiết việc đã làm]
+
+Kiểm chứng thực tế (Verify Before Claim):
+  • Lệnh test đã chạy: [npm test / pytest / tsc --noEmit / Chưa chạy (Nêu lý do)]
+  • Kết quả xác thực:  [Pass N/N tests / Types Clean / NOT VERIFIED]
+  • Anti-overengineering: ✅ 0 abstraction thừa, giữ giải pháp tối giản nhất
+  • Zero Hack:          ✅ Không dùng any, @ts-ignore, hay làm yếu test assertion
+
+⚠️ Phương án Rollback nếu cần:
+  • Lệnh: `git restore <các-file-đã-sửa>`
+```

package/.agents/skills/qk-code-review/SKILL.md

@@ -1,253 +1,132 @@
 ---
-# ── Identity ───────────────────────────────────────────────
-name: qk-code-review
-version: 9.2.0
-status: stable
-description: "Review code, AI config, hoặc skin rules theo 4 phases với Architect mindset — phát hiện bug, security issue, architecture smell, logic error. Dùng skill này khi user nhắc đến: review code, code review, kiểm tra code, đánh giá code, review skin, review rule, review ai config, audit PR — kể cả khi chỉ nói \"xem thử code này ổn không\"."
-platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-
-# ── V9: Classification ─────────────────────────────────────
-type: utility
-
-intent:
-  - code-review
-  - quality-assurance
-  - architecture-review
-  - ai-config-audit
-
-complexity:
-  level: high
-  criteria:
-    files_affected: "1-15"
-    has_behavior_change: false
-    has_external_dependency: false
-    has_breaking_change: false
-
+name: qk-code-review
+version: 10.1.0
+status: stable
+subtitle: "Review Code & Audit"
+description: "Kiểm toán mã nguồn toàn diện: Đánh giá kiến trúc, chấm điểm sức khỏe Codebase Health Score (0–100), quét bảo mật OWASP Top 10 và kiểm định chất lượng Web WCAG AA. Dùng khi: review code, code review, kiểm tra code, đánh giá code, health check, nợ kỹ thuật, security audit, scan lỗ hổng, owasp, secret leak, a11y, accessibility, wcag — TUYỆT ĐỐI KHÔNG dùng khi trực tiếp sửa code (dùng qk-code-cleaner)."
+tools:
+  - filesystem
+  - terminal
+rules:
+  - global
+  - coding-standards
+  - security
+workflow: code-review
 triggers:
   - "review code"
   - "code review"
   - "kiểm tra code"
   - "đánh giá code"
-  - "review skin"
-  - "review rule"
-  - "review ai config"
-  - "audit PR"
-
-
-selection:
-  priority: high
-  confidence_threshold: 0.85
-
-# ── V8: References ─────────────────────────────────────────
-workflow: code-review
-
-rules:
-  - global
-
-tools:
-  - filesystem
-
-related_skills:
-  - qk-project-health
-  - qk-security-audit
-
-knowledge_scope:
-  owns:
-    - code-review-standards
-    - ai-configuration-review
-    - feedback-delivery
-  references:
-    - architecture
-    - security
-    - anti-patterns
-
-# ── V8: Verification ───────────────────────────────────────
-verification:
-  required: true
-  strategy: review
-
-# ── V8: Knowledge links ────────────────────────────────────
-examples: []
-learnings: []
-
-# ── V7 Runtime ─────────────────────────────────────────────
-execution_mode: deterministic
-cost: high
-latency: medium
-risk: low
-side_effects: read_only
-produces: [report]
-consumes: [source-code, rules, workflows]
-
-token_budget:
-  max_files_read: 10
-  max_lines_per_read: 300
-  max_shell_commands: 2
-  stop_early: true
-
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
----
-
-# qk-code-review — Elite Review System
-
-> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
-
-Biến quá trình Code Review từ "bắt bẻ" (gatekeeping) thành "chia sẻ tri thức" (knowledge sharing) thông qua phản hồi mang tính xây dựng, phân tích có hệ thống và hợp tác cải tiến theo tư duy Kiến trúc sư (Architect mindset).
-
----
-
-## Preconditions
-
-Trước khi thực hiện review, AI BẮT BUỘC kiểm tra:
-
-- [ ] Xác định đối tượng review: files cụ thể, diff/PR, hay cấu hình AI/rules.
-- [ ] Đọc `.agents/DEV_PROFILE.md` để nắm coding standards, architectural rules, và constraints.
-- [ ] Đảm bảo files cần review tồn tại và có thể đọc được nội dung.
-- [ ] Nếu scope review vượt quá khả năng context (ví dụ toàn bộ repo hàng nghìn files cùng lúc):
-  → **EXIT: BLOCKED**
-  → Báo cáo user chia nhỏ phạm vi review theo module hoặc PR diff.
-
----
-
-## Scope
-
-✅ Skill này làm:
-- Phân tích code theo 4 tầng: Bug/Logic, Security, Architecture/Maintainability, Coding Standards.
-- Đánh giá chất lượng của cấu hình AI (SKILL.md, workflow YAML, system rules).
-- Cung cấp feedback định lượng, phân loại độ nghiêm trọng: CRITICAL, HIGH, MEDIUM, LOW.
-- Gợi ý giải pháp cụ thể (concrete diffs / refactor snippet) cho từng vấn đề.
-- Hoạt động ở chế độ **read-only** (chỉ xuất báo cáo, không tự ý sửa code).
-
-❌ Skill này KHÔNG làm:
-- Tự động áp dụng code fix vào source code của user (→ user quyết định hoặc dùng `qk-refactor`).
-- Quét toàn bộ vulnerabilities của third-party dependencies qua CVE database (→ `qk-security-audit`).
-- Đo lường và chấm điểm tổng thể kỹ thuật dự án (→ `qk-project-health`).
-
----
-
-## Execution Steps
-
-### Step 1 — Context & Target Ingestion
-```
-Inputs:  Danh sách files/diff từ user, DEV_PROFILE.md
-Actions:
-  - Đọc nội dung source code mục tiêu.
-  - Phân tích vai trò của file trong kiến trúc chung (domain, service, UI, infra).
-Output: Scope boundary & Review target map
-```
-
-### Step 2 — Multi-Dimensional Analysis
-```
-Inputs:  Source code, Standards & Rules
-Actions:
-  - Phase 1: Logic & Correctness (xử lý null/undefined, race conditions, edge cases).
-  - Phase 2: Security & Privacy (input validation, SQLi/XSS, secret leaks, access control).
-  - Phase 3: Architecture & Clean Code (SOLID, DRY, coupled dependencies, readability).
-  - Phase 4: Conventions & Performance (quy ước đặt tên, N+1 query, re-render).
-Output: Raw findings list
-```
-
-### Step 3 — Constructive Synthesis & Remediation
-```
-Inputs:  Raw findings list
-Actions:
-  - Lọc bỏ false positives và gán nhãn mức độ nghiêm trọng (CRITICAL/HIGH/MEDIUM/LOW).
-  - Với mỗi finding, viết lý do (Why) và đề xuất code snippet cải tiến (How to fix).
-Output: Structured Review Report
-```
-
-### Step 4 — Verification & Delivery
-```
-Inputs:  Structured Review Report
-Actions:
-  - Rà soát tính khả thi của các đề xuất.
-  - Trình bày báo cáo rõ ràng, mạch lạc theo ngôn ngữ tiếng Việt (code snippets giữ English).
-Exit: SUCCESS
-```
-
----
-
-## Prompt Template
-
-AI đọc `DEV_PROFILE.md` để biết conventions + constraints. Review sẽ đánh giá theo đúng tiêu chuẩn dự án.
-
-```
-Review:     [File / folder / PR diff cần review]
-Focus:      [security / performance / architecture / logic / correctness — hoặc "full"]
-Context:    [Đây là feature mới / bug fix / refactor / migration / ...]
-Bỏ qua:    [Những thứ không cần comment — vd: style, naming, test coverage]
-```
-
----
-
-### Theo Role — AI review theo tiêu chí khác nhau:
-
-**role: fe**
-```
-Review:     src/features/cart/ (toàn bộ folder — PR mới)
-Focus:      correctness + performance
-Context:    Vừa implement giỏ hàng — lần đầu có optimistic updates
-Bỏ qua:    CSS naming convention
-```
-→ AI xem xét: race condition trong optimistic update, stale closure trong
-  useCallback/useEffect, unnecessary re-render (missing memo/deps array),
-  missing error boundary, accessibility của interactive elements,
-  bundle size impact của dependencies mới.
-
-**role: be**
-```
-Review:     src/routes/payments/ + src/services/PaymentService.ts
-Focus:      security + correctness
-Context:    Tích hợp payment gateway mới (Stripe) — business critical
-Bỏ qua:    Code style
-```
-→ AI xem xét: idempotency key usage, webhook signature verification,
-  sensitive data logging (card numbers, CVV không được log),
-  error handling không leak internal info ra response, DB transaction scope,
-  rate limiting, secrets không hardcode.
-
-**role: fullstack**
-```
-Review:     src/features/reports/ (FE + BE cùng PR)
-Focus:      architecture + contract
-Context:    Feature mới — export báo cáo, cả FE và BE trong cùng PR
-Bỏ qua:    Test coverage (sẽ thêm sau)
-```
-→ AI xem xét: type contract giữa FE-BE (có dùng shared types không),
-  FE không hard-code assumptions về response shape, BE thay đổi response
-  có break FE không, error shape nhất quán, loading state đầy đủ.
-
-**role: data**
-```
-Review:     dags/customer_churn_pipeline.py + models/mart/fct_churn.sql
-Focus:      correctness + reliability
-Context:    Pipeline mới chạy weekly, dữ liệu dùng cho ML model
-Bỏ qua:    SQL formatting style
-```
-→ AI xem xét: idempotency (re-run an toàn không), partition filter đúng chưa
-  (tránh full scan), data quality assertions có đủ không, schema evolution
-  strategy, downstream dependencies được documented chưa, SLA realistic không.
-
-**role: ai-engineer**
-```
-Review:     prompts/ + retrieval/pipeline.py
-Focus:      correctness + hallucination risk
-Context:    RAG pipeline sắp ra production — cần review kỹ trước khi deploy
-Bỏ qua:    Code style
-```
-→ AI xem xét: system prompt có enforce grounding không ("chỉ dùng context được cung cấp"),
-  retrieval có thể trả empty context không (edge case), temperature setting phù hợp,
-  PII trong training data / retrieved context, prompt injection risk,
-  eval metrics có được log không, fallback khi LLM unavailable.
-
-**role: devops**
-```
-Review:     .github/workflows/ + terraform/modules/ecs/
-Focus:      security + correctness
-Context:    Infrastructure change — scale up ECS service + thêm ALB rule
-Bỏ qua:    Resource naming convention (đã có convention riêng)
-```
-→ AI xem xét: secrets exposed trong logs hay env vars không, IAM least-privilege
-  (role có quá nhiều permission không), rollback plan rõ ràng chưa,
-  state file được lock và store an toàn không, có test trên staging trước prod không,
-  blast radius nếu Terraform apply fail giữa chừng.
+  - "health check"
+  - "kiểm tra sức khỏe code"
+  - "project score"
+  - "nợ kỹ thuật"
+  - "tech debt"
+  - "security audit"
+  - "kiểm tra bảo mật"
+  - "scan lỗ hổng"
+  - "owasp"
+  - "tìm secret leak"
+  - "a11y"
+  - "wcag"
+---
+
+# qk-code-review — Review Code & Audit (360° Architecture & Security Audit Engine)
+
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+---
+
+## 1. Nguyên Tắc Cốt Lõi & Luật Chống Giáo Điều (Anti-Dogma)
+
+> **Core Principle:** Metrics are signals, not goals. A file of 320 lines that is cohesive, clean, and well-tested is far superior to 5 fragmented micro-files created solely to satisfy an arbitrary line-count limit.
+> **Audit Principle:** PASS is a verified conclusion, never a target. Zero sugarcoating.
+
+### 🛡️ Anti-Dogma Review Rule (CẤM BẮT BẺ VỤN VẶT)
+- **Đánh giá theo ngữ cảnh:** Tuyệt đối KHÔNG trừ điểm máy móc nếu file dài hơn 300 dòng một chút nhưng cấu trúc rõ ràng (như DTOs, config, state machine hoặc generated code). Chỉ gắn cờ cảnh báo khi file đó có nhiều trách nhiệm lộn xộn (God file) và khó bảo trì.
+- **Tập trung vào giá trị thực:** Ưu tiên phát hiện rủi ro bảo mật (OWASP), logic lỗi ngầm, rò rỉ bộ nhớ, và vi phạm quyền truy cập thay vì sa đà vào các nhận xét phong cách (formatting/linting) mà prettier có thể tự sửa.
+
+### 🔒 Laser Focus & Repository Inspection Rule (R-G-13)
+- Chỉ quét và kiểm toán các file thuộc diff hoặc module được người dùng chỉ định.
+- **CẤM** quét toàn bộ codebase bừa bãi hoặc biến việc audit thành một bản tấu sớ lan man hàng trăm file không liên quan.
+
+### ⚖️ Verify Before Claim Rule (XÁC MINH TRƯỚC KHI BÁO CÁO - R-G-14.7)
+- **Không bịa đặt số liệu:** Cấm báo cáo "0 Secret Leaks" nếu chưa chạy regex quét chuỗi nhạy cảm. Cấm báo cáo "Đạt chuẩn WCAG AA" nếu chưa kiểm tra màu sắc tương phản và thẻ ARIA.
+- **Rõ ràng phạm vi:** Phải nêu rõ danh sách chính xác các file đã đọc và kiểm toán. Những file chưa đọc phải ghi rõ nằm ngoài phạm vi review đợt này.
+
+---
+
+## 2. Ranh Giới & Phạm Vi Kỹ Thuật (Hard Boundaries)
+
+### ✅ Việc skill này BẮT BUỘC làm:
+- **Tư duy Kiến trúc sư (Architect Mindset):** Đánh giá tính đóng gói, ranh giới giữa các module, luồng dữ liệu một chiều và xử lý lỗi phòng thủ.
+- **Health Scorecard Định Lượng (0–100):** Chấm điểm nợ kỹ thuật theo thang đo khách quan, có đối chứng số dòng và độ sâu lồng ghép.
+- **OWASP Top 10 Scan:** Quét lỗ hổng Broken Access Control (IDOR), SQL Injection, XSS, Secret Leaks (regex quét tokens, passwords, keys).
+- **Dual-Stream Reporting:** Tạo file artifact `review_report.md` chi tiết tại thư mục brain, và chỉ in bản tóm tắt điều hành 15–25 dòng tại cửa sổ chat.
+
+### ❌ Việc skill này TUYỆT ĐỐI KHÔNG làm (Chuyển giao quyền):
+- Tự tiện sửa mã nguồn trong repo → Skill này là Read-Only Auditor. Để thực thi sửa đổi an toàn, chuyển giao sang `qk-code-cleaner`.
+
+---
+
+## 3. Thang Điểm Sức Khỏe Codebase (Health Score: 0–100)
+
+```
+Điểm khởi điểm: 100 điểm. Trừ điểm dựa trên vi phạm thực tế:
+─────────────────────────────────────────────────────────────────────────────
+• God File (Lộn xộn > 300L):           -5 điểm / file (Có xem xét ngữ cảnh)
+• Long Function (Phức tạp > 40L):      -2 điểm / hàm
+• Deep Nesting (> 3 tầng if/for):      -2 điểm / vị trí
+• Hardcoded Secret (Lộ Key/Pass):      -25 điểm (CRITICAL — Báo động đỏ ngay)
+• Broken Access Control (Dính IDOR):   -20 điểm (CRITICAL)
+• SQL / Command Injection:             -20 điểm (CRITICAL)
+─────────────────────────────────────────────────────────────────────────────
+Xếp loại: 90-100 (Xuất sắc) | 75-89 (Khá) | 50-74 (Cảnh báo) | <50 (Nguy hiểm)
+```
+
+---
+
+## 4. Quy Trình Kiểm Toán 4 Bước & Báo Động Khẩn
+
+```
+[Bước 1: Phạm vi & Regex Scan]  ── Đọc danh sách file, quét regex tìm Secret Leaks
+            │
+            ▼
+[Bước 2: OWASP & Logic Audit]   ── Rà soát IDOR, Injection, Null safety & Error handling
+            │
+            ▼
+[Bước 3: Scorecarding]          ── Tính điểm Health Score, phân loại P0 (Critical) đến P3
+            │
+            ▼
+[Bước 4: Dual-Stream Report]    ── Xuất review_report.md + Chat Executive Summary 15-25L
+```
+
+### 🚨 Giao thức Báo Động Khẩn (Critical Security Trigger):
+Nếu phát hiện **Hardcoded API Key/Secret** hoặc **Lỗ hổng SQL Injection/IDOR**:
+- BẮT BUỘC in cảnh báo đỏ nổi bật ngay dòng đầu tiên của chat:
+  `🚨 [CRITICAL SECURITY ALERT]: Phát hiện lộ Secret/Lỗ hổng nghiêm trọng tại [TênFile.ts:L42](file:///<workspace-root>/path#L42)! Cần xử lý thu hồi ngay lập tức!`
+
+---
+
+## 5. Chuẩn Báo Cáo Antigravity Dual-Stream (Truth-First)
+
+```markdown
+🔍 Code Review & Health Scorecard                     [Role: <role> | Score: <Điểm>/100]
+─────────────────────────────────────────────────────────────────────
+Phạm vi thực tế:    [N files đã rà soát / Tên module]
+Đánh giá chung:     [Xuất sắc / Khá / Cảnh báo / Nguy hiểm]
+
+🚨 Vấn đề then chốt cần khắc phục:
+  ❌ [CRITICAL/OWASP]: [Mô tả ngắn nếu có — kèm file:/// link]
+  ⚠️ [TECH DEBT]:      [Các hàm phức tạp hoặc vi phạm SRP cần tách]
+
+📊 Chỉ số đo lường thực tế (Truth-First):
+  • Health Score:       <Điểm> / 100
+  • Secret Leaks:       [0 (Đã quét regex) / N phát hiện]
+  • OWASP Violations:   [N Critical, N Major]
+  • Anti-Dogma:         ✅ Đã xem xét ngữ cảnh, không bắt bẻ file schema/config
+
+📄 Báo cáo chi tiết & Phương án khắc phục mẫu:
+  Đã lưu tại: [review_report.md](file:///C:/Users/qkhanh/.gemini/antigravity-ide/brain/f7ef21b2-6e3e-4177-a422-5ddcad5a5843/review_report.md)
+  👉 Dùng `./qk-code-cleaner` để bắt đầu phân tách và dọn dẹp mã nguồn an toàn.
+```