@heyai-rules/pilo-masterkit 2.1.0 → 3.1.0

package/.agent/rules/CORE_RULES.md

@@ -1,72 +1,72 @@
----
-trigger: always_on
----
-
-# 📜 CORE RULES & PROTOCOLS / Quy tắc & Giao thức Cốt lõi
-
-> **Dự án: Pilo Masterkit**
-> **Mục đích**: Thiết lập các quy tắc vận hành bất biến cho AI Agent trong dự án.
-> **Lưu ý**: Tệp này có ưu tiên cao nhất (P0) đối với mọi hoạt động của Agent.
-
----
-
-## 🌐 1. Ngôn ngữ & Giao tiếp (Language & Communication)
-
-1.  **Giao tiếp & Suy luận**: Sử dụng **TIẾNG VIỆT** (Bắt buộc) cho mọi cuộc hội thoại, báo cáo và giải thích.
-2.  **Tài liệu (Artifacts)**: Viết nội dung file `.md` (Plan, Task, Walkthrough) bằng **TIẾNG VIỆT**.
-3.  **Kỹ thuật & Mã nguồn**:
-    - Tên biến, hàm, file: **TIẾNG ANH** (camelCase, snake_case...).
-    - Comment trong code: **TIẾNG ANH** (để chuẩn hóa quy chuẩn quốc tế).
-
----
-
-## 🔄 2. Chu trình PDCA (Vòng đời Quản trị)
-
-Mọi tác vụ lớn (Tính năng/Tái cấu trúc/Sửa lỗi) phải tuân thủ nghiêm ngặt chu trình 4 bước:
-
-1.  **PLAN (Lập kế hoạch)**: Phân tích yêu cầu, liệt kê file bị ảnh hưởng và đề xuất giải pháp kỹ thuật rõ ràng. Luôn lập kế hoạch trước khi thực hiện tác vụ phức tạp. **Quy tắc Trạng thái File**: Mỗi khi một kế hoạch được Duyệt (Approved), Hoàn thành (Completed) hoặc Hủy bỏ (Cancelled), PHẢI ghi chú trạng thái ở đầu file và đổi tên file đính kèm trạng thái đó (VD: `[APPROVED]-plan.md`).
-2.  **DO (Thực thi)**: Thực hiện công việc sau khi kế hoạch được phê duyệt. Tuân thủ tiêu chuẩn mã nguồn sạch (Clean Code).
-3.  **CHECK (Kiểm tra)**: Chạy kiểm thử, kiểm tra lỗi cú pháp (Lint) và xác minh kết quả. **Bằng chứng trước, khẳng định sau**.
-4.  **ACT (Tối ưu)**: Khắc phục lỗi phát sinh, cập nhật tài liệu và đóng phiên làm việc. Nếu gặp vấn đề bất ngờ, hãy DỪNG LẠI và lập lại kế hoạch (Re-plan).
-
----
-
-## 🛑 3. Cổng Kiểm soát Socratic (Socratic Gate)
-
-**Luật Bất Biến**: Không bao giờ thực hiện công việc ngay khi nhận yêu cầu mơ hồ hoặc có rủi ro cao. AI phải chủ động:
-- Đặt ít nhất **3 câu hỏi chiến lược** để xác định mục tiêu và phạm vi nếu yêu cầu chưa rõ ràng.
-- Đánh giá rủi ro ảnh hưởng đến hệ thống hiện tại. Nếu có rủi ro: **CẢNH BÁO**.
-- **No Laziness**: Tìm kiếm nguyên nhân gốc rễ (Root Cause) thay vì chỉ sửa chữa bề nổi.
-- **Task Limit**: Một tác vụ chỉ được thực hiện tối đa 3 lần.
-- **Time Limit**: Mỗi lần thực hiện tối đa 10 phút. Nếu treo quá 10 phút, lập tức dừng tác vụ. Nếu dự tính cần nhiều thời gian hơn, phải đưa ra thời gian ước tính và hỏi ý kiến người dùng.
-
----
-
-## 🛡️ 4. Bảo mật & An toàn (Security Armor)
-
-- **Zero Secrets**: Tuyệt đối không lưu trữ API Keys, mật khẩu vào Git. Kiểm tra `.gitignore` thường xuyên.
-- **Sanitization**: Kiểm tra kỹ các dữ liệu đầu vào (Input) và sử dụng Whitelist cho các kết nối mạng (nếu có).
-- **Audit Requirement**: Luôn chạy quét bảo mật (`security-reviewer`) trước khi bàn giao các đoạn mã nhạy cảm.
-
----
-
-## 🧹 5. Tiêu chuẩn Kỹ thuật (Technical Standards)
-
-- **Immutability**: Ưu tiên tạo đối tượng mới thay vì thay đổi trực tiếp (mutate) đối tượng cũ.
-- **Simplicity First**: Ưu tiên giải pháp đơn giản và thanh lịch nhất. Tránh over-engineering.
-- **Modularization**: Không try-hard code trong một file quá lớn. Chia nhỏ file (<400 dòng), ưu tiên tách components/logic dùng chung để tăng khả năng tái sử dụng.
-- **Model Selection**: Tự chọn model phù hợp (flash cho planning/review, pro cho coding/debug sâu).
-
----
-
-## 📂 6. Tổ chức & Vệ sinh Ngữ cảnh (Context Hygiene)
-
-- **Artifacts Location**: Lưu trữ file vào đúng thư mục chuyên biệt. Không để file tạm ở thư mục gốc.
-- **Context Awareness**: Luôn đọc `PROJECT_MAP.md` và `PILO_MASTER.md` khi bắt đầu một phiên làm việc mới. Đọc có chọn lọc (Selective Reading) các file cần thiết thay vì quét toàn bộ project.
-- **Memory Sync**: Luôn cập nhật memories (hoặc nhật ký công việc) sau mỗi phiên làm việc (bất kể lớn nhỏ) và mỗi khi lập một kế hoạch.
-- **Memory Hygiene**: Tự động đánh giá và dọn dẹp memory định kỳ (hoặc bằng lệnh `/clean_memory`). Hệ thống **PHẢI tổng hợp, chắt lọc những tinh hoa, quyết định quan trọng**, đồng thời xóa bỏ triệt để các log/ngữ cảnh dư thừa để tránh "loãng" bộ nhớ.
-- **Customization**: Có thể tạo thêm quy tắc, kỹ năng, hiến pháp hoặc workflows mới bằng lệnh slash tương ứng.
-- **Documentation Sync**: Mọi thay đổi kiến trúc phải được cập nhật ngay lập tức vào bản đồ dự án.
-
----
-> *"Orchestrating the technology of the future with discipline and soul."*
+---
+trigger: always_on
+---
+
+# 📜 CORE RULES & PROTOCOLS / Quy tắc & Giao thức Cốt lõi
+
+> **Dự án: Pilo Masterkit**
+> **Mục đích**: Thiết lập các quy tắc vận hành bất biến cho AI Agent trong dự án.
+> **Lưu ý**: Tệp này có ưu tiên cao nhất (P0) đối với mọi hoạt động của Agent.
+
+---
+
+## 🌐 1. Ngôn ngữ & Giao tiếp (Language & Communication)
+
+1.  **Giao tiếp & Suy luận**: Sử dụng **TIẾNG VIỆT** (Bắt buộc) cho mọi cuộc hội thoại, báo cáo và giải thích.
+2.  **Tài liệu (Artifacts)**: Viết nội dung file `.md` (Plan, Task, Walkthrough) bằng **TIẾNG VIỆT**.
+3.  **Kỹ thuật & Mã nguồn**:
+    - Tên biến, hàm, file: **TIẾNG ANH** (camelCase, snake_case...).
+    - Comment trong code: **TIẾNG ANH** (để chuẩn hóa quy chuẩn quốc tế).
+
+---
+
+## 🔄 2. Chu trình PDCA (Vòng đời Quản trị)
+
+Mọi tác vụ lớn (Tính năng/Tái cấu trúc/Sửa lỗi) phải tuân thủ nghiêm ngặt chu trình 4 bước:
+
+1.  **PLAN (Lập kế hoạch)**: Phân tích yêu cầu, liệt kê file bị ảnh hưởng và đề xuất giải pháp kỹ thuật rõ ràng. Luôn lập kế hoạch trước khi thực hiện tác vụ phức tạp. **Quy tắc Trạng thái File**: Mỗi khi một kế hoạch được Duyệt (Approved), Hoàn thành (Completed) hoặc Hủy bỏ (Cancelled), PHẢI ghi chú trạng thái ở đầu file và đổi tên file đính kèm trạng thái đó (VD: `[APPROVED]-plan.md`).
+2.  **DO (Thực thi)**: Thực hiện công việc sau khi kế hoạch được phê duyệt. Tuân thủ tiêu chuẩn mã nguồn sạch (Clean Code).
+3.  **CHECK (Kiểm tra)**: Chạy kiểm thử, kiểm tra lỗi cú pháp (Lint) và xác minh kết quả. **Bằng chứng trước, khẳng định sau**.
+4.  **ACT (Tối ưu)**: Khắc phục lỗi phát sinh, cập nhật tài liệu và đóng phiên làm việc. Nếu gặp vấn đề bất ngờ, hãy DỪNG LẠI và lập lại kế hoạch (Re-plan).
+
+---
+
+## 🛑 3. Cổng Kiểm soát Socratic (Socratic Gate)
+
+**Luật Bất Biến**: Không bao giờ thực hiện công việc ngay khi nhận yêu cầu mơ hồ hoặc có rủi ro cao. AI phải chủ động:
+- Đặt ít nhất **3 câu hỏi chiến lược** để xác định mục tiêu và phạm vi nếu yêu cầu chưa rõ ràng.
+- Đánh giá rủi ro ảnh hưởng đến hệ thống hiện tại. Nếu có rủi ro: **CẢNH BÁO**.
+- **No Laziness**: Tìm kiếm nguyên nhân gốc rễ (Root Cause) thay vì chỉ sửa chữa bề nổi.
+- **Task Limit**: Một tác vụ chỉ được thực hiện tối đa 3 lần.
+- **Time Limit**: Mỗi lần thực hiện tối đa 10 phút. Nếu treo quá 10 phút, lập tức dừng tác vụ. Nếu dự tính cần nhiều thời gian hơn, phải đưa ra thời gian ước tính và hỏi ý kiến người dùng.
+
+---
+
+## 🛡️ 4. Bảo mật & An toàn (Security Armor)
+
+- **Zero Secrets**: Tuyệt đối không lưu trữ API Keys, mật khẩu vào Git. Kiểm tra `.gitignore` thường xuyên.
+- **Sanitization**: Kiểm tra kỹ các dữ liệu đầu vào (Input) và sử dụng Whitelist cho các kết nối mạng (nếu có).
+- **Audit Requirement**: Luôn chạy quét bảo mật (`security-reviewer`) trước khi bàn giao các đoạn mã nhạy cảm.
+
+---
+
+## 🧹 5. Tiêu chuẩn Kỹ thuật (Technical Standards)
+
+- **Immutability**: Ưu tiên tạo đối tượng mới thay vì thay đổi trực tiếp (mutate) đối tượng cũ.
+- **Simplicity First**: Ưu tiên giải pháp đơn giản và thanh lịch nhất. Tránh over-engineering.
+- **Modularization**: Không try-hard code trong một file quá lớn. Chia nhỏ file (<400 dòng), ưu tiên tách components/logic dùng chung để tăng khả năng tái sử dụng.
+- **Model Selection**: Tự chọn model phù hợp (flash cho planning/review, pro cho coding/debug sâu).
+
+---
+
+## 📂 6. Tổ chức & Vệ sinh Ngữ cảnh (Context Hygiene)
+
+- **Artifacts Location**: Lưu trữ file vào đúng thư mục chuyên biệt. Không để file tạm ở thư mục gốc.
+- **Context Awareness**: Luôn đọc `PROJECT_MAP.md` và `PILO_MASTER.md` khi bắt đầu một phiên làm việc mới. Đọc có chọn lọc (Selective Reading) các file cần thiết thay vì quét toàn bộ project.
+- **Memory Sync**: Luôn cập nhật memories (hoặc nhật ký công việc) sau mỗi phiên làm việc (bất kể lớn nhỏ) và mỗi khi lập một kế hoạch.
+- **Memory Hygiene**: Tự động đánh giá và dọn dẹp memory định kỳ (hoặc bằng lệnh `/clean_memory`). Hệ thống **PHẢI tổng hợp, chắt lọc những tinh hoa, quyết định quan trọng**, đồng thời xóa bỏ triệt để các log/ngữ cảnh dư thừa để tránh "loãng" bộ nhớ.
+- **Customization**: Có thể tạo thêm quy tắc, kỹ năng, hiến pháp hoặc workflows mới bằng lệnh slash tương ứng.
+- **Documentation Sync**: Mọi thay đổi kiến trúc phải được cập nhật ngay lập tức vào bản đồ dự án.
+
+---
+> *"Orchestrating the technology of the future with discipline and soul."*

package/.agent/rules/PROJECT_MAP.md

@@ -1,58 +1,58 @@
-# 🗺️ Project Map / Bản đồ Điều hướng Dự án
-
-> **Dự án**: Pilo Masterkit
-> **Vai trò**: Cung cấp cái nhìn tổng quan về cấu trúc hệ thống, quy chuẩn kỹ thuật và triết lý vận hành.
-
----
-
-## 🏛️ Quản trị Hệ thống (.agent/)
-
-Đây là "não bộ" của dự án, chứa các quy tắc và thực thể AI:
-
-- **[PILO_MASTER.md](../agents/PILO_MASTER.md)**: Nhân dạng chính & Điều phối viên (Senior Architect).
-- **[CORE_RULES.md](CORE_RULES.md)**: Giao thức bắt buộc (P0), PDCA, Socratic Gate.
-- **[SECURITY_ARMOR.md](SECURITY_ARMOR.md)**: Quy chuẩn bảo mật và quét lỗ hổng.
-- **`agents/`**: Danh sách 20+ chuyên gia kỹ thuật (Planner, Debugger, v.v.).
-- **`skills/`**: Thư viện 125+ kỹ năng chuyên sâu (UI/UX Pro, React Expert, v.v.).
-- **`workflows/`**: Các quy trình tự động hóa kích hoạt bằng Slash Command.
-
-### 🔍 Giao thức Đọc File (Reading Protocol)
-> **Selective Reading**: AI PHẢI đọc có chọn lọc các file cần thiết dựa trên yêu cầu của người dùng thay vì quét toàn bộ project. Hãy ưu tiên các sơ đồ kiến trúc và file quy tắc trước khi đi sâu vào mã nguồn.
-
----
-
-## 💻 Tiêu chuẩn Kỹ thuật (Technical Standards)
-
-Các quy ước bắt buộc cho mã nguồn:
-
-- **[CODE_STANDARDS.md](../../products/CODE_STANDARDS.md)**: Quy tắc đặt tên và cấu trúc file.
-- **[SYSTEM_DESIGN.md](../../products/SYSTEM_DESIGN.md)**: Kiến trúc hệ thống và thẩm mỹ (Master + Overrides).
-- **[TESTING_POLICY.md](../../products/TESTING_POLICY.md)**: Quy trình TDD và yêu cầu Coverage >80%.
-- **[GIT_WORKFLOW.md](../../products/GIT_WORKFLOW.md)**: Conventional Commits và chiến lược nhánh.
-
----
-
-## 📁 Thư mục Chức năng (Functional Directories)
-
-- **`lessons/`**: Bài học kinh nghiệm và kinh nghiệm tích lũy sau mỗi task.
-- **`reports/`**: Báo cáo tiến độ, kết quả audit và hiệu năng.
-- **`plans/`**: Kế hoạch triển khai chi tiết cho các tính năng mới.
-- **`status/`**: Trạng thái hiện tại của dự án và các module.
-- **`tasks/`**: Nhiệm vụ chi tiết (todo, in-progress, done).
-- **`logs/`**: Nhật ký hoạt động chi tiết của Agent và hệ thống.
-- **`walkthroughs/`**: Hướng dẫn từng bước cho các tính năng phức tạp.
-- **`producs/`**: Tài liệu đặc tả sản phẩm (specs, PRD, roadmap).
-- **`.agent/scripts/`**: Các kịch bản Master Audit (`checklist.py`, `verify_all.py`).
-
----
-
-## 🛠️ Trạng thái Hệ thống
-
-| Thành phần | Trạng thái | Ghi chú |
-| :--- | :--- | :--- |
-| **Agent Fleet** | ✅ Sẵn sàng | 20+ Agents đã nạp |
-| **Skill Matrix** | ✅ Sẵn sàng | 125+ Skills đã nạp |
-| **Security Gate** | ✅ Kích hoạt | Bắt buộc quét trước commit |
-
----
-> *"Orchestrating the technology of the future with discipline and soul."*
+# 🗺️ Project Map / Bản đồ Điều hướng Dự án
+
+> **Dự án**: Pilo Masterkit
+> **Vai trò**: Cung cấp cái nhìn tổng quan về cấu trúc hệ thống, quy chuẩn kỹ thuật và triết lý vận hành.
+
+---
+
+## 🏛️ Quản trị Hệ thống (.agent/)
+
+Đây là "não bộ" của dự án, chứa các quy tắc và thực thể AI:
+
+- **[PILO_MASTER.md](../agents/PILO_MASTER.md)**: Nhân dạng chính & Điều phối viên (Senior Architect).
+- **[CORE_RULES.md](CORE_RULES.md)**: Giao thức bắt buộc (P0), PDCA, Socratic Gate.
+- **[SECURITY_ARMOR.md](SECURITY_ARMOR.md)**: Quy chuẩn bảo mật và quét lỗ hổng.
+- **`agents/`**: Danh sách 20+ chuyên gia kỹ thuật (Planner, Debugger, v.v.).
+- **`skills/`**: Thư viện 125+ kỹ năng chuyên sâu (UI/UX Pro, React Expert, v.v.).
+- **`workflows/`**: Các quy trình tự động hóa kích hoạt bằng Slash Command.
+
+### 🔍 Giao thức Đọc File (Reading Protocol)
+> **Selective Reading**: AI PHẢI đọc có chọn lọc các file cần thiết dựa trên yêu cầu của người dùng thay vì quét toàn bộ project. Hãy ưu tiên các sơ đồ kiến trúc và file quy tắc trước khi đi sâu vào mã nguồn.
+
+---
+
+## 💻 Tiêu chuẩn Kỹ thuật (Technical Standards)
+
+Các quy ước bắt buộc cho mã nguồn:
+
+- **[CODE_STANDARDS.md](../../products/CODE_STANDARDS.md)**: Quy tắc đặt tên và cấu trúc file.
+- **[SYSTEM_DESIGN.md](../../products/SYSTEM_DESIGN.md)**: Kiến trúc hệ thống và thẩm mỹ (Master + Overrides).
+- **[TESTING_POLICY.md](../../products/TESTING_POLICY.md)**: Quy trình TDD và yêu cầu Coverage >80%.
+- **[GIT_WORKFLOW.md](../../products/GIT_WORKFLOW.md)**: Conventional Commits và chiến lược nhánh.
+
+---
+
+## 📁 Thư mục Chức năng (Functional Directories)
+
+- **`lessons/`**: Bài học kinh nghiệm và kinh nghiệm tích lũy sau mỗi task.
+- **`reports/`**: Báo cáo tiến độ, kết quả audit và hiệu năng.
+- **`plans/`**: Kế hoạch triển khai chi tiết cho các tính năng mới.
+- **`status/`**: Trạng thái hiện tại của dự án và các module.
+- **`tasks/`**: Nhiệm vụ chi tiết (todo, in-progress, done).
+- **`logs/`**: Nhật ký hoạt động chi tiết của Agent và hệ thống.
+- **`walkthroughs/`**: Hướng dẫn từng bước cho các tính năng phức tạp.
+- **`producs/`**: Tài liệu đặc tả sản phẩm (specs, PRD, roadmap).
+- **`.agent/scripts/`**: Các kịch bản Master Audit (`checklist.py`, `verify_all.py`).
+
+---
+
+## 🛠️ Trạng thái Hệ thống
+
+| Thành phần | Trạng thái | Ghi chú |
+| :--- | :--- | :--- |
+| **Agent Fleet** | ✅ Sẵn sàng | 20+ Agents đã nạp |
+| **Skill Matrix** | ✅ Sẵn sàng | 125+ Skills đã nạp |
+| **Security Gate** | ✅ Kích hoạt | Bắt buộc quét trước commit |
+
+---
+> *"Orchestrating the technology of the future with discipline and soul."*

package/.agent/rules/QUALITY_ASSURANCE.md

@@ -1,54 +1,54 @@
-# 🧪 Quality Assurance & Testing Policy
-
-This document defines the rigorous automated testing standards for the Pilo Masterkit. **Zero-Bug Tolerance** is our ultimate target.
-
-> *"If it's not tested, it's broken."*
-
----
-
-## 📐 1. The Testing Pyramid
-
-1. **Unit Tests (Base)**: Individual functions, utilities, and components (Vitest/Pytest).
-2. **Integration Tests (Middle)**: Interaction between modules and service integrations.
-3. **End-to-End (E2E) Tests (Peak)**: Critical user flows and frontend-backend interactions (Playwright).
-
----
-
-## 🚀 2. Mandatory TDD Workflow (CRITICAL)
-
-**Test-Driven Development (TDD)** is mandatory for all new features and bug fixes. Follow the **Red-Green-Refactor** cycle:
-
-1. **RED**: Write a failing test for the new functionality or bug. (Viết test thất bại trước).
-2. **GREEN**: Write the minimal implementation to make the test pass. (Viết code tối thiểu để pass).
-3. **REFACTOR**: Optimize the code and test suite for clarity and performance. (Tối ưu hóa mã nguồn).
-
----
-
-## 🛠️ 3. Testing Stack & Tools
-
-- **Core Engine**: Vitest (Web), Pytest (Python).
-- **Automation**: Playwright (E2E, Cross-browser).
-- **Mocking**: MSW (Mock Service Worker) for API layer simulation.
-- **Component Test**: Testing Library (React/Vue/Svelte).
-
----
-
-## 📜 4. Operational Requirements
-
-- **Root Cause Analysis**: Every failing test must be analyzed for its root cause. Fix the cause, not the symptoms.
-- **Regression Guard**: Every discovered bug MUST have a corresponding regression test to prevent its return.
-- **Coverage Goal**: 
-  - **Business Logic**: 80%+ mandatory coverage.
-  - **Main API Endpoints**: 100% coverage (Success & Error cases).
-  - **UI Components**: Ensure error, loading, and success states are tested.
-
----
-
-## 🏁 5. Verification & Reporting
-
-- **Manual Audit**: Use `python .agent/scripts/checklist.py .` before completion.
-- **Evidence Collection**: Test logs and coverage reports MUST be included in the final `walkthrough.md`.
-- **Pre-Commit Check**: No code shall be committed with failing tests or critical lint errors.
-
----
-> *"Quality is not an act, it is a habit."*
+# 🧪 Quality Assurance & Testing Policy
+
+This document defines the rigorous automated testing standards for the Pilo Masterkit. **Zero-Bug Tolerance** is our ultimate target.
+
+> *"If it's not tested, it's broken."*
+
+---
+
+## 📐 1. The Testing Pyramid
+
+1. **Unit Tests (Base)**: Individual functions, utilities, and components (Vitest/Pytest).
+2. **Integration Tests (Middle)**: Interaction between modules and service integrations.
+3. **End-to-End (E2E) Tests (Peak)**: Critical user flows and frontend-backend interactions (Playwright).
+
+---
+
+## 🚀 2. Mandatory TDD Workflow (CRITICAL)
+
+**Test-Driven Development (TDD)** is mandatory for all new features and bug fixes. Follow the **Red-Green-Refactor** cycle:
+
+1. **RED**: Write a failing test for the new functionality or bug. (Viết test thất bại trước).
+2. **GREEN**: Write the minimal implementation to make the test pass. (Viết code tối thiểu để pass).
+3. **REFACTOR**: Optimize the code and test suite for clarity and performance. (Tối ưu hóa mã nguồn).
+
+---
+
+## 🛠️ 3. Testing Stack & Tools
+
+- **Core Engine**: Vitest (Web), Pytest (Python).
+- **Automation**: Playwright (E2E, Cross-browser).
+- **Mocking**: MSW (Mock Service Worker) for API layer simulation.
+- **Component Test**: Testing Library (React/Vue/Svelte).
+
+---
+
+## 📜 4. Operational Requirements
+
+- **Root Cause Analysis**: Every failing test must be analyzed for its root cause. Fix the cause, not the symptoms.
+- **Regression Guard**: Every discovered bug MUST have a corresponding regression test to prevent its return.
+- **Coverage Goal**: 
+  - **Business Logic**: 80%+ mandatory coverage.
+  - **Main API Endpoints**: 100% coverage (Success & Error cases).
+  - **UI Components**: Ensure error, loading, and success states are tested.
+
+---
+
+## 🏁 5. Verification & Reporting
+
+- **Manual Audit**: Use `python .agent/scripts/checklist.py .` before completion.
+- **Evidence Collection**: Test logs and coverage reports MUST be included in the final `walkthrough.md`.
+- **Pre-Commit Check**: No code shall be committed with failing tests or critical lint errors.
+
+---
+> *"Quality is not an act, it is a habit."*

package/.agent/rules/SECURITY_ARMOR.md

@@ -1,44 +1,44 @@
-# 🛡️ SECURITY ARMOR / Giao thức Bảo mật Cốt lõi
-
-> **Dự án**: Pilo Masterkit
-> **Nguyên tắc**: Bảo mật không phải là một sản phẩm, mà là một quy trình xuyên suốt (Security-First).
-
----
-
-## 🔐 1. Quản lý Bí mật (Zero Secrets)
-
-- **Tuyệt đối cấm**: Không bao giờ hardcode API Keys, mật khẩu, tokens vào mã nguồn hoặc commit lên Git.
-- **Lưu trữ**: Chỉ sử dụng biến môi trường (`.env`) hoặc hệ thống quản lý bí mật chuyên dụng.
-- **Xác minh**: Luôn kiểm tra file `.gitignore` để đảm bảo các file nhạy cảm không bị lộ.
-- **Sự cố**: Nếu phát hiện rò rỉ, ngay lập tức: **Dừng tiến trình -> Thu hồi Key -> Tạo mới Key -> Quét toàn bộ lịch sử Git.**
-
----
-
-## 🛠️ 2. An toàn Runtime & Công cụ
-
-- **Quyền hạn tối thiểu (Least Privilege)**: AI chỉ hoạt động trong phạm vi thư mục dự án được cấp quyền.
-- **Hạn chế hệ thống**: Cấm AI tự ý thay đổi các cấu trúc cốt lõi của hệ điều hành (OS) trừ khi có chỉ thị cụ thể và được người dùng phê duyệt.
-- **Kết nối mạng**: Sử dụng Whitelist cho các kết nối ra ngoài. Luôn hỏi ý kiến người dùng trước khi thực hiện các yêu cầu mạng phức tạp.
-
----
-
-## 🧪 3. Kiểm tra Bảo mật (Security Audit)
-
-**Trước khi bàn giao bất kỳ đoạn mã nào, AI PHẢI:**
-
-1.  **Sanitization**: Kiểm tra kỹ các dữ liệu đầu vào (Input) từ người dùng để ngăn chặn SQL Injection và XSS.
-2.  **Vulnerability Scan**: Sử dụng kỹ năng `vulnerability-scanner` hoặc chạy script `security_scan.py` nếu có.
-3.  **Dependency Check**: Kiểm tra các thư viện bên thứ ba để đảm bảo không có lỗ hổng bảo mật đã biết (CVE).
-
----
-
-## 📊 4. Danh sách Kiểm tra (Security Checklist)
-
-- [ ] Không có thông tin nhạy cảm trong mã nguồn.
-- [ ] Dữ liệu đầu vào đã được làm sạch và xác thực.
-- [ ] Các thông báo lỗi không làm lộ thông tin cấu hình hệ thống.
-- [ ] Mật khẩu/Token được mã hóa an toàn nếu được lưu trữ.
-- [ ] Quyền truy cập tệp tin (File Permissions) được thiết lập đúng.
-
----
-> *"Security is a process, not a destination."*
+# 🛡️ SECURITY ARMOR / Giao thức Bảo mật Cốt lõi
+
+> **Dự án**: Pilo Masterkit
+> **Nguyên tắc**: Bảo mật không phải là một sản phẩm, mà là một quy trình xuyên suốt (Security-First).
+
+---
+
+## 🔐 1. Quản lý Bí mật (Zero Secrets)
+
+- **Tuyệt đối cấm**: Không bao giờ hardcode API Keys, mật khẩu, tokens vào mã nguồn hoặc commit lên Git.
+- **Lưu trữ**: Chỉ sử dụng biến môi trường (`.env`) hoặc hệ thống quản lý bí mật chuyên dụng.
+- **Xác minh**: Luôn kiểm tra file `.gitignore` để đảm bảo các file nhạy cảm không bị lộ.
+- **Sự cố**: Nếu phát hiện rò rỉ, ngay lập tức: **Dừng tiến trình -> Thu hồi Key -> Tạo mới Key -> Quét toàn bộ lịch sử Git.**
+
+---
+
+## 🛠️ 2. An toàn Runtime & Công cụ
+
+- **Quyền hạn tối thiểu (Least Privilege)**: AI chỉ hoạt động trong phạm vi thư mục dự án được cấp quyền.
+- **Hạn chế hệ thống**: Cấm AI tự ý thay đổi các cấu trúc cốt lõi của hệ điều hành (OS) trừ khi có chỉ thị cụ thể và được người dùng phê duyệt.
+- **Kết nối mạng**: Sử dụng Whitelist cho các kết nối ra ngoài. Luôn hỏi ý kiến người dùng trước khi thực hiện các yêu cầu mạng phức tạp.
+
+---
+
+## 🧪 3. Kiểm tra Bảo mật (Security Audit)
+
+**Trước khi bàn giao bất kỳ đoạn mã nào, AI PHẢI:**
+
+1.  **Sanitization**: Kiểm tra kỹ các dữ liệu đầu vào (Input) từ người dùng để ngăn chặn SQL Injection và XSS.
+2.  **Vulnerability Scan**: Sử dụng kỹ năng `vulnerability-scanner` hoặc chạy script `security_scan.py` nếu có.
+3.  **Dependency Check**: Kiểm tra các thư viện bên thứ ba để đảm bảo không có lỗ hổng bảo mật đã biết (CVE).
+
+---
+
+## 📊 4. Danh sách Kiểm tra (Security Checklist)
+
+- [ ] Không có thông tin nhạy cảm trong mã nguồn.
+- [ ] Dữ liệu đầu vào đã được làm sạch và xác thực.
+- [ ] Các thông báo lỗi không làm lộ thông tin cấu hình hệ thống.
+- [ ] Mật khẩu/Token được mã hóa an toàn nếu được lưu trữ.
+- [ ] Quyền truy cập tệp tin (File Permissions) được thiết lập đúng.
+
+---
+> *"Security is a process, not a destination."*

package/.agent/rules/VERSION_ORCHESTRATION.md

@@ -1,64 +1,64 @@
-# 🌿 Version Orchestration & Collaboration
-
-This document defines the Git workflow, branching strategy, and commit message standards for the Pilo Masterkit to ensure a clean, traceable, and professional history.
-
-> *"Clean Git history is as important as clean code."*
-
----
-
-## 🌿 1. Modular Branching Strategy
-
-- **`main`**: The source of truth. Always stable and production-ready.
-- **`dev`**: The primary integration branch for new features and fixes.
-- **`feature/[name]`**: Dedicated branch for developing a specific feature.
-- **`bugfix/[name]`**: Dedicated branch for fixing identified bugs.
-- **`hotfix/[name]`**: Urgent production fixes.
-
----
-
-## 💬 2. Conventional Commit Standards
-
-Every commit message MUST follow the **Conventional Commits** format: `type(scope): description`.
-
-| Type | Description |
-| :--- | :--- |
-| **feat** | A new feature or capability. |
-| **fix** | A bug fix. |
-| **docs** | Documentation-only changes. |
-| **style** | Formatting, missing semi-colons, etc. (no business logic change). |
-| **refactor** | Code change that neither fixes a bug nor adds a feature. |
-| **perf** | A code change that improves performance. |
-| **test** | Adding missing tests or correcting existing tests. |
-| **chore** | Changes to the build process, auxiliary tools, or libraries. |
-| **ci** | Changes to CI configuration files and scripts. |
-
-*Example: `feat(auth): add JWT login support`*
-
----
-
-## 🚀 3. Pull Request (PR) Protocol
-
-Before submitting or merging any PR, the AI Task Force must ensure:
-
-1. **Protocol Verification**: All code adheres to `CORE_RULES.md` and `CODE_CRAFTSMANSHIP.md`.
-2. **Quality Gate**: 
-   - `python .agent/scripts/checklist.py .` must pass with zero critical blockers.
-   - All tests pass with **80%+ coverage**.
-3. **Walkthrough Inclusion**: A final `walkthrough.md` report must be provided, detailing:
-   - What changed and why.
-   - Evidence of successful tests (logs/screenshots).
-   - Side-effects analyzed via mental simulation.
-4. **Knowledge Capture**: Any important project context, architectural decisions, or lessons learned must be updated in `.agent/tasks/lessons.md`.
-5. **Approval**: Final confirmation from the User or a senior AI Orchestrator.
-
----
-
-## 🧹 4. Repository Hygiene
-
-- **Micro-Commits**: Prefer small, atomic commits covering a single logical change.
-- **Zero Secrets**: Strictly prohibit committing `.env` files, API keys, or any sensitive credentials.
-- **Sanitized History**: Use `rebase` (where appropriate) to keep a linear and clean history.
-- **File Integrity**: Never leave temporary files, build artifacts, or IDE configs in the repository.
-
----
-> *"Orchestrate the history as you orchestrate the code."*
+# 🌿 Version Orchestration & Collaboration
+
+This document defines the Git workflow, branching strategy, and commit message standards for the Pilo Masterkit to ensure a clean, traceable, and professional history.
+
+> *"Clean Git history is as important as clean code."*
+
+---
+
+## 🌿 1. Modular Branching Strategy
+
+- **`main`**: The source of truth. Always stable and production-ready.
+- **`dev`**: The primary integration branch for new features and fixes.
+- **`feature/[name]`**: Dedicated branch for developing a specific feature.
+- **`bugfix/[name]`**: Dedicated branch for fixing identified bugs.
+- **`hotfix/[name]`**: Urgent production fixes.
+
+---
+
+## 💬 2. Conventional Commit Standards
+
+Every commit message MUST follow the **Conventional Commits** format: `type(scope): description`.
+
+| Type | Description |
+| :--- | :--- |
+| **feat** | A new feature or capability. |
+| **fix** | A bug fix. |
+| **docs** | Documentation-only changes. |
+| **style** | Formatting, missing semi-colons, etc. (no business logic change). |
+| **refactor** | Code change that neither fixes a bug nor adds a feature. |
+| **perf** | A code change that improves performance. |
+| **test** | Adding missing tests or correcting existing tests. |
+| **chore** | Changes to the build process, auxiliary tools, or libraries. |
+| **ci** | Changes to CI configuration files and scripts. |
+
+*Example: `feat(auth): add JWT login support`*
+
+---
+
+## 🚀 3. Pull Request (PR) Protocol
+
+Before submitting or merging any PR, the AI Task Force must ensure:
+
+1. **Protocol Verification**: All code adheres to `CORE_RULES.md` and `CODE_CRAFTSMANSHIP.md`.
+2. **Quality Gate**: 
+   - `python .agent/scripts/checklist.py .` must pass with zero critical blockers.
+   - All tests pass with **80%+ coverage**.
+3. **Walkthrough Inclusion**: A final `walkthrough.md` report must be provided, detailing:
+   - What changed and why.
+   - Evidence of successful tests (logs/screenshots).
+   - Side-effects analyzed via mental simulation.
+4. **Knowledge Capture**: Any important project context, architectural decisions, or lessons learned must be updated in `.agent/tasks/lessons.md`.
+5. **Approval**: Final confirmation from the User or a senior AI Orchestrator.
+
+---
+
+## 🧹 4. Repository Hygiene
+
+- **Micro-Commits**: Prefer small, atomic commits covering a single logical change.
+- **Zero Secrets**: Strictly prohibit committing `.env` files, API keys, or any sensitive credentials.
+- **Sanitized History**: Use `rebase` (where appropriate) to keep a linear and clean history.
+- **File Integrity**: Never leave temporary files, build artifacts, or IDE configs in the repository.
+
+---
+> *"Orchestrate the history as you orchestrate the code."*