# 14. Quy Chuẩn Kỹ Thuật & Cổng Kiểm Soát Chất Lượng (Engineering Rules & Quality Gates)

> **Mốc thời gian chuẩn hóa**: 07/09/2026  
> **Tiêu chuẩn áp dụng**: Google Senior SWE Invariant Engineering & Claude 3.7 Sonnet / Opus Agentic Verification Rigor  
> **Tài liệu tham chiếu liên quan**: `AGENTS.md`, `GEMINI.md`, `01_system_architecture.md`, `vitals_calibration_architecture.md`

---

## 1. Bối Cảnh & Phân Tích Lỗ Hổng Văn Hóa Kỹ Thuật (Retrospective & Root-Cause Analysis)

Trước thời điểm 07/09/2026, quá trình phát triển hệ sinh thái AutoPOE2 bộc lộ những lỗ hổng mang tính hệ thống trong phong cách làm việc của các Agent:

### 1.1. Ảo tưởng ngữ cảnh cục bộ (Local Context Myopia)
- **Triệu chứng**: Agent chỉ quan sát 10–20 dòng mã quanh điểm phát sinh lỗi, tạo ra các bản vá tức thời (band-aid fixes) mà không phân tích đồ thị phụ thuộc (call graph) hoặc bất biến kiến trúc (architectural invariants).
- **Hệ quả thực tế**:
  - Khi người chơi kẹt Grace Period, agent spawn một thread độc lập `keybd_event('W')` mà không qua kiểm tra cửa sổ tiền cảnh (`KMBoxNet::IsGameWindowFocused()`), phá hủy hoàn toàn nguyên tắc Focus Interlock.
  - Khi chưa có entity calibration, agent sinh quái giả HP 100/100 bằng địa chỉ bộ nhớ làm ID (`id = addr & 0xFFFFFFFF`), gây nhiễu loạn bộ nhớ dedup loot.

### 1.2. Xu hướng tự mãn & Ảo tưởng thực thi (Execution Hallucination & Confirmation Bias)
- **Triệu chứng**: Agent viết code xong lập tức tuyên bố `[COMPLETED]` chỉ dựa trên việc code "trông có vẻ hợp lý" hoặc biên dịch thành công (build pass), không chạy test case thực tế. Thậm chí sao chép số liệu test cũ (như "610/610 PASS", "696/696 PASS") vào báo cáo mới dù chưa hề chạy lại CTest.
- **Hệ quả thực tế**: Các lỗi logic nghiệm trọng (như đảo ngược dấu trục Y `screen_y = cy - (ndx + ndy) * 0.45f` trong `reflex_manager.cpp` và `loot_controller.cpp` so với dấu `+` trong `quest_navigator.cpp`) tồn tại nhiều phiên mà không bị phát hiện.

### 1.3. Lệch pha Tài liệu và Mã nguồn (Documentation Drift)
- **Triệu chứng**: Tài liệu mô tả các tham số lý tưởng (Wishful Thinking) nhưng mã nguồn cài đặt các giải pháp tiện tay.
- **Hệ quả thực tế**:
  - Tài liệu cam kết chu kỳ phản xạ 200Hz (5ms), nhưng code chạy 1 vòng lặp duy nhất 120Hz (`sleep 8ms`).
  - Tài liệu cam kết Watchdog mất tim 3s thì chuyển Co-Pilot Passive bảo vệ nhân vật, nhưng code 5s gọi `shm.RequestStop()` giết luôn toàn bộ Core.
  - Tài liệu ghi F11/F12 là Panic Hotkey, nhưng code gán F11 làm phím quét lại XYZ.

---

## 2. Hệ Thống 4 Quy Tắc Kỹ Thuật Nâng Cấp (Rules 8–11)

### Quy Tắc 8: Triệt Tiêu Sửa Lỗi Triệu Chứng (Root-Cause-First & Anti-Symptom Patching)
1. **Cấm Monkey-Patching**: Không dùng `|| true`, ép kiểu thô, hardcode số ma thuật (`totalGoldLooted += 150`, `spMax <= 2000`, `+36`).
2. **Quy trình 4 bước RCA bắt buộc**:
   - **Bước 1: Reproduce & Trace**: Tái hiện lỗi, cô lập input bẩn và trace call graph.
   - **Bước 2: Invariant Invalidation Analysis**: Chỉ rõ bất biến nào bị vi phạm.
   - **Bước 3: Structural Architectural Fix**: Viết lại hàm chuẩn hóa dùng chung duy nhất (Single Source of Logic - ví dụ `WorldToScreen`).
   - **Bước 4: Invariant Assertion**: Khóa chặn bằng `assert()`, `static_assert()`, hoặc preconditions.

### Quy Tắc 9: Cổng Kiểm Thử Đối Chiếu Nghiêm Ngặt Trước Khi Công Bố (Verification Gate Before Done)
1. **Nguyên tắc "Untested code is broken code"**: Mọi task chỉ được chuyển `[COMPLETED]` khi có Raw Terminal Output tươi mới trong phiên.
2. **Yêu cầu Bằng chứng**: Phải trích xuất stdout/stderr từ lệnh chạy thật (`pytest`, `CTest`, script mock verification). Cấm sao chép kết quả phiên cũ.
3. **Môi trường Non-elevated**: Nếu thiếu quyền Admin chạy RPM thật, bắt buộc chạy Mock Unit Harness ở User Mode.

### Quy Tắc 10: Hợp Đồng Đồng Bộ Tuyệt Đối Tài Liệu & Mã Nguồn (Zero-Drift Code-Doc Contract)
1. **Single Source of Truth (SSoT)**: Tần số (Hz), độ trễ (ms), hotkeys, memory layout offsets phải khớp 100% giữa `docs/` và mã nguồn.
2. **Atomic Doc-Code Commit**: Sửa code logic thì bắt buộc grep và cập nhật tài liệu tương ứng trong cùng lượt làm việc.
3. **Phân biệt Hiện trạng vs Quy hoạch**: Tính năng chưa cài đặt chỉ được ghi `[PLANNED]` hoặc `[DRAFT]`.

### Quy Tắc 11: Phòng Ngừa Hồi Quy Bằng Mock Harness Tự Động (Automated Regression Prevention via Mock Harness)
1. **Tách biệt Logic khỏi Game Client**: Các thuật toán tính toán (A*, Bézier curve, Coordinate Transform, Vitals Sanitizer) phải chạy độc lập trên Mock Harness ở User Mode.
2. **Bug-Driven Regression Tests**: Mỗi khi một lỗi logic được phát hiện, BẮT BUỘC phải viết ngay một Unit Test case tái hiện đúng lỗi đó trước khi sửa code.
3. **Continuous Enforcement**: Đưa test case vào bộ kiểm thử định kỳ để ngăn chặn tái phát vĩnh viễn.

---

## 3. Ma Trận Đối Chiếu Chuẩn Google SWE & Claude 3.7 Agentic Rigor

| Tiêu chí | Phong cách Cũ (Pre-Upgrade) | Chuẩn Nâng Cấp (Post-Upgrade) |
|---|---|---|
| **Phương thức sửa lỗi** | Thêm điều kiện bypass, hardcode tạm, vá triệu chứng | 4-step RCA, tìm root-cause, bảo vệ bằng invariants |
| **Xác nhận hoàn thành** | Đoán bằng mắt, code biên dịch xong là báo xong | Cổng kiểm thử độc lập, Raw Terminal Output bắt buộc |
| **Độ khớp tài liệu** | Docs nói 200Hz, code chạy 120Hz; docs ghi 3s passive, code kill core | Zero-Drift SSoT, Atomic Doc-Code Commit |
| **Môi trường kiểm thử** | Trông cậy vào game thật (cần admin, dễ bế tắc) | Mock/Simulated Harness chạy User Mode 100% độc lập |