# ĐẶC TẢ TỐI ƯU HÓA HARNESS TÁC TỬ & QUẢN TRỊ TRI THỨC TOÀN DIỆN (DOC 66)

> **Tài liệu chuẩn hóa tầng điều phối tác tử (Agent Harness & Governance Layer) của AutoPOE2.**  
> *Mốc thời gian tham chiếu: 16/09/2026 - Kế thừa từ Doc 50, Doc 61 và các bài học tối ưu hóa từ ECC.*

---

## 1. BỐI CẢNH & TẦM NHÌN TỔNG QUAN

Hệ thống **AutoPOE2** đã xây dựng nền tảng kỹ thuật vững chắc với kiến trúc bất đối xứng hai tầng ([Doc 50](50_two_tier_asymmetric_hybrid_architecture_specification.md)) và hàng đợi tự hành SSoT ([Doc 61](61_autonomy_gap_audit_and_next_development_basis.md)).

Tuy nhiên, trong quá trình phát triển dài hạn (Continuous Agentic Development), sự phình to của context, hiện tượng trôi dạt tài liệu (documentation drift), sự chồng chéo ngữ cảnh giữa các sub-agents và sự gián đoạn giữa các phiên làm việc đòi hỏi một quy chuẩn **Tối ưu hóa Harness Tác tử (Agent Harness Performance Optimization)**.

Tài liệu này chuẩn hóa 4 trụ cột quản trị nâng cao được tích hợp vào AutoPOE2:
1. **Living Docs Governance**: Phân loại tài liệu thành 4 vai trò độc lập, không chồng chéo.
2. **Atomic Instincts Engine**: Lưu trữ phản xạ kỹ thuật vi mô có chấm điểm tin cậy.
3. **Path-Scoped Rules Organization**: Định tuyến nạp quy tắc theo đường dẫn tệp để giảm tải token context.
4. **Iterative Retrieval & Sub-Agent Dispatch Protocol**: Khóa chặt phạm vi trách nhiệm của Sub-Agents bằng bộ 3 tham số bắt buộc.

---

## 2. TRỤ CỘT 1: LIVING DOCS GOVERNANCE (4 VAI TRÒ TÀI LIỆU)

Để loại bỏ hoàn toàn hiện tượng mục rữa tài liệu (Docs Rotting), tài liệu dự án được phân định rành mạch vào 4 vai trò không thay thế cho nhau:

```mermaid
flowchart TD
    subgraph ROLES ["HỆ THỐNG 4 VAI TRÒ TÀI LIỆU"]
        direction TB
        C["1. CONSTITUTION (Hiến Pháp Bất Biến)<br/>AGENTS.md, GEMINI.md, Master Invariants Matrix"]
        M["2. MAP (Bản Đồ Kiến Trúc & Luồng Dữ Liệu)<br/>Doc 50 (Two-Tier), Doc 61 (Autonomy Gap), Codebase Maps"]
        S["3. STATUS (Hiện Trạng Vận Hành & Sprint)<br/>SESSION_HANDOFF.md, Task Queues, Live Probe State"]
        H["4. HISTORY (Nhật Ký & Quyết Định Quá Khứ)<br/>ADRs, Incident Dossiers, CHANGELOG.md"]
    end
```

- **Constitution (Hiến pháp)**: Chứa các quy chuẩn cấm kỵ, danh mục bất biến `INV-*`, và kỷ luật kiến trúc. Luôn có hiệu lực tối cao.
- **Map (Bản đồ)**: Hướng dẫn cấu trúc thư mục, luồng dữ liệu giữa Hot Path và Cold Path. Giúp tác tử định hướng mà không cần quét toàn bộ ổ đĩa.
- **Status (Hiện trạng)**: Chỉ phản ánh trạng thái của sprint hoặc phiên hiện tại. Khi hoàn thành, thông tin được xóa hoặc nén vào History.
- **History (Lịch sử)**: Lưu giữ nguyên nhân vì sao hệ thống có kiến trúc như hiện tại (ADR), các lỗi đã từng xảy ra (Incidents). Cấm dùng History làm quy tắc hoạt động cho hiện tại.

---

## 3. TRỤ CỘT 2: KHO LƯU TRỮ PHẢN XẠ VI MÔ (ATOMIC INSTINCTS ENGINE)

Tọa lạc tại `.agents/instincts/`, đây là nơi đúc kết các bài học kỹ thuật đã được xác thực thực nghiệm (Empirical DoD - Rule 5).

### 3.1. Cấu Trúc Bản Ghi Instinct
Mỗi Instinct là một tệp Markdown nhỏ độc lập chứa:
- `id`: Mã định danh duy nhất (ví dụ: `poe2-dynamic-xyz-playerfinder`).
- `trigger`: Điều kiện kích hoạt tra cứu.
- `confidence`: Điểm tin cậy (từ `0.3` đến `0.95`).
- `domain`: Lĩnh vực kỹ thuật (`memory_re`, `cpp_hotpath`, `python_eda`, `hardware_safety`, `build_toolchain`).
- `scope`: `project` (chỉ áp dụng riêng cho AutoPOE2).
- `lesson`: Bài học cốt lõi ngắn gọn.
- `evidence`: Bằng chứng thực nghiệm định lượng.

### 3.2. Quy Trình Thăng Cấp (Promotion)
- Khi phát hiện một giải pháp kỹ thuật mới, tác tử tạo bản ghi ở mức `confidence: 0.5`.
- Sau khi được kiểm chứng qua live test hoặc bộ test tự động không gây lỗi hồi quy, thăng cấp lên `confidence: 0.8 - 0.9`.
- Chỉ các nguyên tắc phổ quát kiến trúc mới được đưa vào `AGENTS.md` SSoT.

---

## 4. TRỤ CỘT 3: ĐỊNH TUYẾN QUY TẮC THEO PHẠM VI (PATH-SCORED RULES)

Thay vì buộc mọi sub-agent phải gánh toàn bộ ngữ cảnh khổng lồ của cả dự án, thư mục `.agents/rules/` được cấu trúc thành các domain chuyên biệt:

1. **`common/development-workflow.md`**: Quy chuẩn chung (Research-First, 4-step RCA, Anti-Point-Fixing, Rule 5).
2. **`cpp/engine-rules.md`**: Quy chuẩn C++23 Hot Path 120Hz (Zero Heap Allocation, DOD, RAII, Seqlock, pre-build taskkill).
3. **`python/systems-rules.md`**: Quy chuẩn Python 3.11 Cold Path (EventBus, Tkinter non-blocking, zero heavy ML libs, ceiling 500-800 lines).
4. **`hardware/controls-and-safety.md`**: Quy chuẩn KMBox Net, mouse Bézier, WASD dwell $\ge 300\text{ms}$, Focus Interlock.

---

## 5. TRỤ CỘT 4: QUY TRÌNH ĐIỀU PHỐI SUB-AGENT & NÉN NGỮ CẢNH CÓ CHỦ ĐÍCH

### 5.1. Bộ Ba Tham Số Bắt Buộc Khi Dispatch Sub-Agent
Mỗi khi Senior Orchestrator triệu hồi sub-agent thông qua `invoke_subagent`, prompt bắt buộc phải chứa 3 thông số định lượng:

1. **`Objective`**: Mục tiêu kỹ thuật cụ thể cần giải quyết (tránh mô tả chung chung).
2. **`Forbidden Surface`**: Danh sách các file hoặc khu vực mã nguồn tuyệt đối CẤM chạm vào (bảo vệ nguyên tắc Single Responsibility và chống monolithic bloat).
3. **`Merge Gate`**: Điều kiện nghiệm thu định lượng (test nào phải PASS, lệnh CLI cụ thể nào phải thành công với mã trả về `0`).

### 5.2. Chu Trình Iterative Retrieval Loop
- Sub-agent báo cáo theo định dạng 4 phần chuẩn (`AGENTS.md` Mục 2).
- Orchestrator đóng vai trò thẩm định độc lập. Nếu sub-agent trả kết quả thiếu chiều sâu kiến trúc, orchestrator gửi câu hỏi phản biện truy vấn sâu (tối đa 3 vòng lặp) trước khi tiến hành tích hợp.

### 5.3. Chiến Lược Nén Ngữ Cảnh Có Chủ Đích (Strategic Compaction)
- Không dựa vào tính năng Auto-Compact tự động ngẫu nhiên của môi trường.
- Chủ động gom trạng thái và tạo tệp `.agents/SESSION_HANDOFF_TEMPLATE.md` tại các ranh giới pha tự nhiên (Research $\to$ Plan $\to$ Implement $\to$ Verify).
- Handoff file luôn trả lời 3 câu hỏi cốt lõi:
  1. Đã làm thành công những gì (kèm bằng chứng test thực tế)?
  2. Đã thử những gì nhưng thất bại (kèm RCA)?
  3. Những việc còn lại cần làm và ưu tiên số 1 khi bắt đầu phiên mới là gì?