@damphuquy/agent-init 3.2.0 → 3.4.0

package/templates/vi/process/development-protocols/observability-and-evals.md

@@ -9,7 +9,37 @@
 
 ---
 
-## 1. Quan Sát Chi Phí Token & Ngân Sách Thực Thi (Cost & Token Observability)
+## 1. Cơ Chế Kích Hoạt Có Điều Kiện (Trigger-Based Observability & Evals)
+
+<trigger_governance>
+  Để đảm bảo tối ưu chi phí token và không lãng phí lượt gọi công cụ (tool calls), hệ thống áp dụng cơ chế kích hoạt theo trigger:
+
+  ### 1. Trạng Thái Mặc Định — Tinh Gọn (Default LEAN Mode):
+  - **Mặc định là OFF (Zero-Overhead):** Đối với hầu hết các task phát triển thông thường (CRUD, sửa lỗi nhỏ, thêm UI, chỉnh sửa tài liệu), Agent KHÔNG cần đo đạc chi phí token, không tự đếm tool calls giữa chừng và không tạo bảng benchmark. Khối `<cost_observability>` trong `state.md` được giữ nguyên giá trị mặc định.
+
+  ### 2. Các Trigger Kích Hoạt Tường Minh (Explicit Triggers):
+  Agent chỉ kích hoạt theo dõi khi phát hiện một trong các trigger sau:
+  - **Cờ Prompt:**
+    - `--profile` hoặc `[profile]`: Kích hoạt theo dõi chi phí và hiệu suất thực thi task.
+    - `--bench` hoặc `[benchmark]`: Kích hoạt vòng đời Benchmark định lượng và tạo bảng `results.tsv`.
+    - `--eval` hoặc `[eval]`: Kích hoạt bộ kiểm thử đánh giá bảo mật / ranh giới tin cậy (`process/evals/`).
+  - **Thẻ Điều Khiển Trong Task Spec (`task.md` / `task-lite.md`):**
+    - `<observability_mode>PROFILE</observability_mode>`: Kích hoạt theo dõi chi phí.
+    - `<observability_mode>BENCHMARK</observability_mode>`: Kích hoạt đo lường hiệu năng kép (A/B baseline vs candidate).
+
+  ### 3. Quy Tắc Tổng Kết Cuối Task (Single-Shot Finalization):
+  - Khi có trigger `--profile`, Agent **TUYỆT ĐỐI KHÔNG** cập nhật liên tục sau mỗi lát cắt nhỏ làm phình to context window.
+  - Agent chỉ thực hiện tổng kết số liệu (đếm tool calls, số retry, thời gian hoàn thành) và ghi vào mục 14 `<cost_observability>` trong `state.md` **đúng 1 lần duy nhất khi kết thúc phase EXECUTE**, ngay trước khi tạo `review.md`.
+
+  ### 4. Trigger Tự Động Theo Ngưỡng Rủi Ro (Adaptive Fallback Trigger):
+  Agent tự động kích hoạt ghi nhận chi phí và bộ nhớ lỗi `<failure_memory>` mà không cần cờ báo trước nếu:
+  - Một lát cắt thất bại kiểm chứng từ lần thứ 2 trở lên (`retries >= 2`).
+  - Task vượt quá 30 tool calls mà chưa hoàn tất lát cắt.
+</trigger_governance>
+
+---
+
+## 2. Quan Sát Chi Phí Token & Ngân Sách Thực Thi (Cost & Token Observability)
 
 <token_cost_governance>
   Mọi phiên làm việc của Agent đều chịu sự chi phối của ngân sách token và tài nguyên tính toán.
@@ -28,7 +58,7 @@
 
 ---
 
-## 2. Chuẩn Hóa Git-Atomic Commits & Môi Trường Cách Ly (Sandboxing)
+## 3. Chuẩn Hóa Git-Atomic Commits & Môi Trường Cách Ly (Sandboxing)
 
 <atomic_commits_and_sandboxing>
   ### Quy Ước Commit Nguyên Tử (Git-Atomic Commit Convention):
@@ -52,7 +82,7 @@
 
 ---
 
-## 3. Khung Đánh Giá Benchmark & Đo Lường Định Lượng (Evals Framework)
+## 4. Khung Đánh Giá Benchmark & Đo Lường Định Lượng (Evals Framework)
 
 <evals_framework>
   Đối với các task tối ưu hóa hiệu năng, refactor kiến trúc hoặc nâng cấp thuật toán:
@@ -65,7 +95,7 @@
 
 ---
 
-## 4. Evals Governance Xác Định & Vệ Sinh Bằng Chứng
+## 5. Evals Governance Xác Định & Vệ Sinh Bằng Chứng
 
 <governance_evals>
   Dùng `process/evals/eval-case.json` làm fixture offline, có tính xác định. Mỗi case ghi input như dữ liệu, policy verdict, side effect và evidence reference kỳ vọng; nó không bao giờ được khiến lệnh hay MCP call thực thi.