# GEMINI AGENT KERNEL DIRECTIVES: FREEEXILE 2026 STANDARDS

> **Trọng tâm**: Chỉ thị kỹ thuật cốt lõi và quy tắc vận hành cho Gemini Host Agent và các Sub-Agent tự hành trong dự án FreeExile.  
> **Áp dụng**: Bắt buộc trên toàn bộ mã nguồn, cấu hình, kiểm thử và tài liệu hóa. Tham chiếu bổ trợ: [AGENTS.md](file:///c:/Projects/FreeExile/AGENTS.md).

---

## 1. NGUYÊN TẮC CỐT LÕI (CORE DIRECTIVES)

1. **Action-Driven, Zero Lip-Service**: Mọi quy chuẩn kỹ thuật hoặc cải tiến quy trình phải được văn bản hóa trực tiếp và triển khai mã nguồn thực tế. Tuyệt đối không trả lời hình thức nếu chưa thực hiện hành động cụ thể.
2. **Khai thác Tối Đa MCP Server (Mandatory MCP Tool First)**:
   - `lsp-mcp`: Duyệt AST, phân tích type, dò tìm caller/callee (`lsp_definition`, `lsp_references`, `lsp_diagnostics`). Cấm regex grep thô khi đổi tên symbol hoặc refactor.
   - `ast-grep` / `ast-grep-mcp`: Tìm kiếm và refactoring cấu trúc an toàn qua 2-Phase Safety Gate (Preview -> Mutation).
   - `chrome-devtools-mcp`: Kiểm thử giao diện WebApp PWA mô phỏng mobile, audit performance và chụp ảnh kiểm chứng.
   - `memory` / `mem0`: Lưu trữ đồ thị tri thức (`search_nodes`, `open_nodes`) và nhận thức dài hạn (`mem0_search`, `mem0_add`).
3. **Tiền Kiểm Bảng Thiết Kế (Pre-Flight Game Design Matrix Gate)**:
   - Cấm code hoặc viết lore/quest/skill/item/balance bằng cảm tính hay suy đoán tự do. Bắt buộc kiểm tra ràng buộc quan hệ chéo qua [data/game_design_matrix.db](file:///c:/Projects/FreeExile/data/game_design_matrix.db) hoặc [GameDesignMatrixService](file:///c:/Projects/FreeExile/server/world/game_design_matrix_service.py).
   - Audit chống drift qua `python tools/lint/verify_game_design_matrix.py` trước khi hoàn tất phiên làm việc.
4. **Tường Lửa Native & Kiểm Soát Vùng Ảnh Hưởng (Native Blast Radius Gate)**:
   - Hệ thống Antigravity Runtime kích hoạt Native Hook `PreToolUse` (`~/.gemini/config/hooks.json`) chặn đứng mọi hành vi sửa code/tài liệu khi chưa kiểm tra ảnh hưởng chéo.
   - File/thực thể rủi ro `HIGH` hoặc `CRITICAL` bắt buộc phải chạy `python tools/analysis/blast_radius.py --target <path> --ack` để mở khóa chỉnh sửa an toàn trong 30 phút.
5. **Kiến Trúc Đa Ngôn Ngữ Phản Ứng Tức Thì & Zero Hardcoded UI Strings (Reactive i18n Protocol)**:
   - Cấm hardcode chuỗi ký tự hiển thị trong UI JS. Bắt buộc dùng `data-i18n` hoặc `FreeExileI18n.t()`.
   - Cơ chế Reactive Event Bus (`FreeExileI18n.subscribe`, `freeexile:localeChanged`) cập nhật DOM tại chỗ (in-place atomic re-render) trong 0ms, cấm reload trang.
   - Bảo đảm 100% parity trên cả 9 ngôn ngữ (`vi`, `en`, `zh`, `ja`, `ko`, `th`, `de`, `ru`, `es`) với microcopy $\le 2$ từ, $\le 12$ ký tự. Cổng kiểm tra: `python tools/lint/check_i18n_hygiene.py --strict`.

---

## 2. QUY CHUẨN VIẾT CODE BẬC THẦY 2026 (ELITE CODE STANDARDS)

### 2.1. Python 3.11+ Server & Actor Model
- **Strict Typing 100%**: Mọi hàm, phương thức, biến nội bộ phải có Type Annotations đầy đủ (`mypy --strict`).
- **Memory & Allocation Efficiency**: Sử dụng `@dataclass(slots=True, frozen=True)` cho các đối tượng dữ liệu bất biến nhằm tối ưu hóa RAM và cache locality.
- **Asynchronous Safety**: Quản lý tác vụ song song qua `asyncio.TaskGroup`. Mọi thao tác I/O bắt buộc có `asyncio.timeout` (SLA p99 < 25ms). Cấm triệt để blocking calls trong event loop và cấm `except: pass`.

### 2.2. TypeScript, Apple Metal & Cocos 3.8.x Client Engine
- **Zero Allocation trong Hot Paths**: Cấm cấp phát bộ nhớ động (`new Vector2`, mảng tạm) trong các vòng lặp frame `update(dt)`, `render()`, `interpolate()`. Bắt buộc tái sử dụng đối tượng qua Scratch Memory và Object Pools để bảo vệ ngân sách 120 FPS ProMotion ($8.33\text{ ms/frame}$).
- **Type Narrowing & Immutability**: Bật toàn bộ flags an toàn trong [tsconfig.json](file:///c:/Projects/FreeExile/client/tsconfig.json). Sử dụng Discriminated Unions và `readonly` cho message protocol.
- **Cocos 3.8.x & Metal Shaders**: Sử dụng [SpriteAtlasRenderer.ts](file:///c:/Projects/FreeExile/client/cocos/assets/scripts/animation/SpriteAtlasRenderer.ts) (Pivot `[0.5, 0.90]`, 8 hướng, PoT atlas), shader PBR [sprite_pbr.effect](file:///c:/Projects/FreeExile/client/cocos/assets/resources/shaders/sprite_pbr.effect) (Normal Map Sobel + Emissive), `ParticleSystem2D` và `MotionStreak` (vệt né i-frame 0.25s). Memory alignment theo chuẩn SIMD16/Float4 trên Apple Silicon.

### 2.3. Schema-First Protobuf Protocol
- Mọi giao tiếp mạng phải bắt đầu từ file `.proto` tại [proto/](file:///c:/Projects/FreeExile/proto/). Tuân thủ nghiêm ngặt tính tương thích ngược: Không đổi tag number; sử dụng `reserved` khi xóa bỏ trường.

### 2.4. Kiến Trúc Mùa Giải & Rương Chỉ Rút (PoE2 Seasonal Model)
- **Cơ Chế Song Thực Cảnh (Dual-Realm)**: `Standard Realm` (Cõi Bị Lãng Quên) vĩnh cửu + `Seasonal Challenge Realm` (Đại Nạn Hoang Vực) clean slate mỗi big update.
- **Rương Đồ "Chỉ Rút" (Remove-Only Stash Tabs)**: Hết mùa, rương chuyển thành tab `is_remove_only = True` tại Cõi Bị Lãng Quên. Cấm nạp (`deposit_item` -> REJECT), chỉ cho phép rút (`withdraw_item`).
- **Phân Vùng Tuyệt Đối**: Cấm nhân vật Cõi Bị Lãng Quên tham gia instance của Đại Nạn Hoang Vực. Nhân vật chết trong Hardcore mùa giải lập tức bị lưu đày về Cõi Bị Lãng Quên.

### 2.5. Uỷ Thác Bản Năng & Chiến Hồn Tế Cốt (Multi-LLM Feral Totem)
- **Chiến Hồn Tế Cốt (`Agent_Orb`)**: Não kép gồm tầng phản xạ thú tính 30Hz cục bộ (né i-frame < 25% máu, nhặt thạch, phục dược trong 0ms) + Tầng chiến lược đa mô hình LLM (OpenRouter, DeepSeek, Claude, Gemini, GPT).
- **Server-Authoritative 100%**: Mọi lệnh di chuyển, xuất chiêu, nhặt đồ đều do [server_engine_loop.py](file:///c:/Projects/FreeExile/server/world/server_engine_loop.py) xác thực. Báo cáo thu hoạch minh bạch [DelegationHarvestReport](file:///c:/Projects/FreeExile/server/world/agent_orb_service.py).

### 2.6. Khối Bảo Mật & Cổng Phủ Quyết Release (Independent Security Veto Gate)
- **Cơ Cấu 5 Chuyên Trách**: Phân công độc lập giữa `ciso_agent` (CISO), `red_team_operator`, `blue_team_guardian`, `anti_dupe_economic_auditor`, và `reverse_engineering_analyst`.
- **Quyền Phủ Quyết Bắt Buộc (Security Veto Power)**: Khối Bảo Mật sở hữu quyền VETO độc lập qua [SecurityAuditGate](file:///c:/Projects/FreeExile/server/security/independent_security_auditor.py). Tồn tại dù chỉ 1 lỗi `CRITICAL` hoặc `HIGH` lập tức bị đình chỉ release.
- **Kiểm Toán Độc Lập**: Chạy `python tools/security/run_independent_security_audit.py --build-id "BUILD_ID" --env STAGING`.
- **Khóa Cách Ly Khẩn Cấp**: Khóa rương/giao dịch tức thì qua [EconomicAnomalyDetector](file:///c:/Projects/FreeExile/server/security/independent_security_auditor.py) khi phát hiện đột biến tiền tệ.

### 2.7. Safe Haven Purity & Phân Vùng Bản Đồ PoE2
- Sào Huyệt Cá Nhân (`zone_player_hideout`) và Doanh Trại Hub (`zone_boundless_sanctuary`) an toàn 100%. Cấm quái thù địch hay dã thú đi tuần; chỉ duy nhất Mộc Nhân Bất Hoại (`isDummy: true`) tồn tại. Quái chỉ xuất hiện ở ngoại vực (Open World, Dungeons, Secret Chambers, Map Device). Kiểm duyệt: [ZoneEngine.can_spawn_hostile_monsters](file:///c:/Projects/FreeExile/server/world/zone_engine.py).

### 2.8. Quy Chuẩn Module Hóa & Phân Tách File (Hygiene Limits)
- **Giới Hạn Định Lượng**: Code logic $\le 350-500$ dòng. Danh mục tĩnh $\le 700-1000$ dòng. HTML $\le 150-400$ dòng (Tam phân lập HTML/CSS/JS). CSS domain $\le 350-500$ dòng. Hàm $\le 30-50$ dòng, Cyclomatic complexity $\le 10$.
- **Phân Tách Dữ Liệu & Logic**: Cấm nhồi nhét seed data trong file engine. Bắt buộc tách thành `*_types.py` (models, DTOs) và `*_catalog.py` (seed data).
- **Phân Tầng `common/`, `utils/`, `helpers/`**: `common/` (contracts/protocols), `utils/` (stateless pure math/time), `helpers/` (hàm nghiệp vụ riêng của từng domain).

### 2.9. Quy Chuẩn Bảo Vệ Tài Sản & Phòng Chống Xóa Nhầm (Asset Protection)
- **Quy tắc 2 Pha Xóa An Toàn (2-Phase Deletion Gate)**: Cấm các lệnh xóa đệ quy thô (`rmdir /s /q`, `rm -rf`) trên thư mục gốc khi chưa qua Pha 1 (Dry-Run Inventory kiểm kê toàn bộ file bên trong). Bắt buộc bàn giao tài nguyên sang [client/cocos/assets/resources/](file:///c:/Projects/FreeExile/client/cocos/assets/resources/) và đối soát SHA-256. Kiểm soát: `python tools/lint/check_asset_safety.py`.

### 2.10. Quản Trị Tri Thức Combat Room (Combat Room Knowledge Protocol)
- Toàn bộ biên bản họp lưu tại [combat_room/](file:///c:/Projects/FreeExile/combat_room/) theo 5 cấp độ phân quyền ([combat_room/PERMISSIONS.md](file:///c:/Projects/FreeExile/combat_room/PERMISSIONS.md)).
- Trích xuất quyết định và đầu việc tự động qua [tools/knowledge/combat_room_sync.py](file:///c:/Projects/FreeExile/tools/knowledge/combat_room_sync.py) -> cập nhật [ACTION_ITEMS_TRACKER.md](file:///c:/Projects/FreeExile/combat_room/_indexes/ACTION_ITEMS_TRACKER.md), [DECISION_REGISTER.md](file:///c:/Projects/FreeExile/combat_room/_indexes/DECISION_REGISTER.md) và đồng bộ vào `Mem0`.

---

## 3. QUY TRÌNH REVIEW MÃ NGUỒN, TDD & QUALITY GATES CLI

1. **TDD Closed-Loop**: Viết test trước -> Xác nhận FAIL (Negative Baseline) -> Viết code tối thiểu -> Tự chữa lành (Self-Healing tối đa 5 lần) -> PASS 100% mới commit.
2. **Review Mã Nguồn (Alibaba Open Code Review - Delegation Mode)**: `ocr delegate preview --format json` -> `ocr delegate rule --format json <files...>` -> Gemini Host Agent đối soát checklist và thực hiện auto-fix.
3. **Phân Nhánh Worktree An Toàn**: Tác vụ thay đổi diện rộng bắt buộc dùng `invoke_subagent` với `Workspace: 'branch'`.
4. **Hệ Thống Cổng Kiểm Toán Tự Động (Quality Gates CLI)**:
   - Kiểm toán Vệ sinh Code & Docs: `python tools/lint/check_code_and_doc_hygiene.py --strict`
   - Kiểm toán Ngôn ngữ & i18n: `python tools/lint/check_i18n_hygiene.py --strict`
   - Kiểm toán Toàn vẹn Game Design: `python tools/lint/verify_game_design_matrix.py`
   - Kiểm toán An ninh Độc lập: `python tools/security/run_independent_security_audit.py --build-id "ID" --env STAGING`
   - Kiểm toán An toàn Tài sản: `python tools/lint/check_asset_safety.py`
   - Context Hygiene Gate: Duy trì đồng bộ [.antigravityignore](file:///c:/Projects/FreeExile/.antigravityignore) và [.geminiignore](file:///c:/Projects/FreeExile/.geminiignore) để ngăn quét rác, cache, build artifacts và transcripts.