---
paths:
  - "src/**/*.py"
  - "!src/core/**"
  - "tests/**/*.py"
  - "scripts/**/*.py"
domain: "python_companion"
---

# AutoPOE2 - Python 3.11 Companion HUD Rules (Cold Path 1-30Hz)

> **Tài liệu quy chuẩn chuyên biệt cho tầng Tier 2 Python Companion HUD & Autonomous Coordination.**  
> Mở rộng từ Hiến pháp SSoT tại [`AGENTS.md`](../../../AGENTS.md) và [Doc 50](docs/development/50_two_tier_asymmetric_hybrid_architecture_specification.md).

## 1. Event-Driven Architecture (EDA) & Triệt Tiêu Proxy Shims
- **EventBus Pub-Sub**: Toàn bộ giao tiếp giữa các module (Overlay, Control Center, Coordinator, Discord Bot) phải thông qua `EventBus` phi tập trung, siêu nhẹ.
- **Cấm Proxy Shims**: Tuyệt đối không tạo các lớp vỏ bọc chuyển tiếp hàm (proxy wrapper/shim) thừa thãi hoặc khối `except: pass` nuốt lỗi.
- **Không chặn luồng chính (Decoupled & GIL-Friendly)**:
  - Các tác vụ I/O nặng (ghi disk, gửi webhook Discord, OCR Tesseract, request mạng) bắt buộc chạy trong worker thread riêng biệt hoặc non-blocking.
  - Vòng lặp giao diện Tkinter (`root.mainloop()`) phải mượt mà, không giật lag.

## 2. Zero External Heavy Dependencies & Sub-0.05ms Inference
- **Zero Heavy ML Libs**: Tuyệt đối không import NumPy, SciPy, PyTorch, Scikit-learn vào runtime cốt lõi. Mọi thuật toán toán học ma trận (LinUCB trong `src/agentic_engine/`) được viết hoàn toàn bằng thư viện chuẩn Python 3.11 Standard Library.
- **Độ trễ suy luận vi mô**: Các hàm xử lý viễn trắc 30Hz từ `CoreShmBridge` phải đạt thời gian thực thi $< 0.05\text{ms}$ để tránh drop frame và nghẽn buffer IPC.

## 3. Kiến Trúc Chống Phình Tệp (Anti-Monolithic Policy - Rule 4A)
- **Trần độ dài tệp (Ceiling)**: Một file Python không được vượt quá **500 – 800 dòng**. Khi file chạm ngưỡng hoặc gánh $\ge 2$ trách nhiệm, bắt buộc phân tách thành package với các sub-module chuyên biệt.
- **Cấm nhồi nhét mã vào tệp chính**: Tuyệt đối cấm nhồi thêm logic nghiệp vụ, giao diện hoặc xử lý sự kiện vào `control_center.py` hay `autonomous_mapping_coordinator.py`. Tệp chính chỉ đóng vai trò ủy nhiệm (delegation / glue code) từ 1–3 dòng.

## 4. Invariant Bắt Buộc Giám Sát Trong Python
- `INV-FSM-SINGLE-OWNER`: Chỉ một chủ sở hữu FSM duy nhất; khi C++ `CharacterFSM` đang active, Python cấm gửi lệnh click/move song song.
- `INV-KEY-NO-U-FOR-MAP-DEVICE`: Cấm phím `U` tại Map Device; phím `U` chỉ dành cho World Map campaign.
- `INV-KEY-NO-F-FOR-INTERACT`: Cấm gửi phím `F` để tương tác NPC/Object. Phím `F` là Skill 8 của người chơi.
- `INV-FSM-TOWN-NO-EXPLORE`: Khi ở trạng thái `TownIdle` / `HideoutIdle`, cấm đề xuất Explore/Unstuck.