@damphuquy/agent-init 1.4.0 → 1.4.2

package/templates/vi/process/README.md

@@ -0,0 +1,150 @@
+# Quy Trình & Điều Phối Task (RIPER-5 Framework)
+
+<process_orchestration version="3.0" framework="RIPER-5">
+
+<overview>
+  Trung tâm điều phối vận hành và mẫu chuẩn để quản lý các tác vụ kỹ thuật, điều phối thực thi AI Agent trong subsystem/project này. Mỗi task đang active là một không gian kỹ thuật độc lập khép kín với đầy đủ chuỗi artifact RIPER-5.
+</overview>
+
+---
+
+## 1. Cấu Trúc Thư Mục
+
+```text
+process/
+├── README.md                         # Hướng dẫn vận hành (tệp này)
+├── .editorconfig                     # Cấu hình định dạng chuẩn cho markdown, tsv, json
+├── _seeds/                           # Blueprints mẫu chuẩn (chỉ đọc)
+│   ├── _GUIDE.md                     # Danh mục mẫu, chuỗi artifact và lệnh khởi tạo
+│   ├── task-template.md.seed         # Hợp đồng master & lưu vết trạng thái RIPER
+│   ├── context-group.md.seed         # Artifact giai đoạn Research (Khảo sát)
+│   ├── decision-template.md.seed     # Artifact giai đoạn Innovate (Lưu vết Gate 1)
+│   ├── plan-template.md.seed         # Artifact giai đoạn Plan (Hợp đồng thực thi, Gate 2)
+│   ├── state-template.md.seed        # Bộ nhớ bền vững trong vòng lặp Execute
+│   ├── review-template.md.seed       # Artifact giai đoạn Review (Gate 3)
+│   ├── handoff-template.md.seed      # Tóm tắt bàn giao cuối cùng (ngắn gọn)
+│   ├── cancellation-template.md.seed # Biên bản hủy task lưu giữ tri thức
+│   ├── results-template.tsv.seed     # Bảng theo dõi số liệu benchmark & định lượng
+│   └── program-template.md.seed      # Bản thiết kế chương trình lớn nhiều giai đoạn
+├── context/                          # Cơ sở tri thức bền vững & router định tuyến
+│   ├── all-context.md                # Router định tuyến ngữ cảnh gốc
+│   ├── planning/all-planning.md      # Quy chuẩn lập kế hoạch & lát cắt dọc (vertical slice)
+│   └── tests/all-tests.md            # Kim tự tháp test, chính sách harness & quy ước mock
+├── development-protocols/            # Quy tắc kỹ thuật & harness thực thi
+│   ├── all-development-protocols.md  # Mục lục protocols
+│   ├── orchestration.md              # Quy tắc phân công subagent
+│   └── implementation-standards.md  # Tiêu chuẩn kiểu dữ liệu, linting và kiểm thử
+├── features/                         # Tính năng theo domain (≥5 files / ≥3 phases)
+│   ├── active/                       # Thư mục task đang làm: {CHG-ID}-{task-slug}/
+│   │   └── CHG-XXX-example/          # Mỗi task một thư mục riêng biệt
+│   │       ├── task.md               # Hợp đồng master & lưu vết trạng thái
+│   │       ├── research.md           # Kết quả khảo sát mã nguồn
+│   │       ├── decision.md           # Các phương án đề xuất (Innovate)
+│   │       ├── plan.md               # Kế hoạch lát cắt dọc chi tiết
+│   │       ├── state.md              # Bộ nhớ tiến độ vòng lặp thực thi
+│   │       ├── review.md             # Biên bản nghiệm thu kiểm thử
+│   │       ├── handoff.md            # Tóm tắt bàn giao
+│   │       ├── results.tsv           # (Tùy chọn) Theo dõi benchmark & metric
+│   │       └── cancelled.md          # (Nếu hủy) Lưu vết nguyên nhân & hoàn nguyên
+│   ├── completed/                    # Lưu trữ các task đã hoàn thành
+│   └── backlog/                      # Ghi chú task tồn đọng: {note_slug}_NOTE_{dd-mm-yy}.md
+└── general-plans/                    # Task độc lập, xuyên suốt, sửa bug nhanh (<5 files)
+    ├── active/
+    ├── completed/
+    └── backlog/
+```
+
+---
+
+## 2. Chuỗi Artifact RIPER-5 & Quy Trình Thực Thi
+
+Mỗi task tạo ra một chuỗi artifact tuần tự. Khởi tạo chúng từng bước khi task tiến triển:
+
+```mermaid
+flowchart TD
+    subgraph Init["0. Khởi tạo"]
+        Seed["task-template.md.seed"] -->|Khởi tạo| Task["task.md (Đặc tả & Tiêu chí AC)"]
+    end
+    subgraph R1["1. RESEARCH (Chỉ đọc)"]
+        Task --> Res["research.md"] --> G0{"Gate G0 (Tự động)"}
+    end
+    subgraph I2["2. INNOVATE (Chỉ đọc)"]
+        G0 --> Dec["decision.md (2-3 Phương án)"] --> G1{"Gate G1 (Kỹ sư duyệt)"}
+    end
+    subgraph P3["3. PLAN (Chỉ lập kế hoạch)"]
+        G1 --> Plan["plan.md (Lát cắt dọc)"] --> G2{"Gate G2 (Kỹ sư ký duyệt)"}
+    end
+    subgraph E4["4. EXECUTE (Đọc/Ghi theo phạm vi)"]
+        G2 --> Code["Thực thi từng Slice"] --> Test["Chạy Verifiers"] --> State["state.md (Bộ nhớ)"]
+    end
+    subgraph R5["5. REVIEW (Chỉ đọc)"]
+        State --> Rev["review.md (Kiểm toán diff)"] --> G3{"Gate G3 (Kỹ sư duyệt)"}
+    end
+    subgraph Done["6. HOÀN THÀNH"]
+        G3 --> Arch["Chuyển sang completed/"] --> Handoff["handoff.md"]
+    end
+```
+
+```text
+task.md          ← (luôn có) Hợp đồng master, trạng thái RIPER phase/gate, AC, decisions
+research.md      ← (Research) Luồng thực thi, bằng chứng, ranh giới hệ thống
+decision.md      ← (Innovate) Các phương án, bảng đánh đổi, Gate 1 — kỹ sư bắt buộc duyệt
+plan.md          ← (Plan) Các lát cắt, verifiers, hợp đồng phạm vi, Gate 2 — kỹ sư duyệt
+state.md         ← (Execute) Tiến độ từng slice, bộ nhớ lỗi, ngân sách thử lại
+review.md        ← (Review) Phát hiện kiểm toán, ma trận kiểm chứng, Gate 3
+handoff.md       ← (Complete) Tóm tắt bàn giao ngắn gọn
+```
+
+### Bảng Ánh Xạ Khái Niệm → Tệp Artifact
+
+| Khái niệm | Artifact |
+|---|---|
+| Task / Đặc tả | `task.md` |
+| Khảo sát / Ngữ cảnh | `research.md` |
+| Đề xuất / Quyết định | `decision.md` |
+| Kế hoạch lát cắt | `plan.md` |
+| Trạng thái vòng lặp | `state.md` |
+| Thực thi | mã nguồn + kiểm thử + `state.md` |
+| Nghiệm thu | `review.md` |
+| Bàn giao | `handoff.md` |
+| Hủy task | `cancelled.md` (lưu giữ tri thức khi hủy bỏ) |
+| Benchmark / Định lượng | `results.tsv` (theo dõi hiệu năng và số liệu đánh giá) |
+| Gate 1 | Phê duyệt trong `decision.md` |
+| Gate 2 | Phê duyệt trong `plan.md` |
+| Gate 3 | Phê duyệt trong `review.md` |
+| Harness / Chính sách | `AGENTS.md` + `development-protocols/` |
+
+---
+
+## 3. Các Giai Đoạn Vận Hành RIPER-5
+
+<operational_phases>
+  <phase order="1" name="Research">
+    CHỈ ĐỌC. Nạp đặc tả task; tuân theo `<information_priority>`; tạo `research.md`.
+    Phân loại bằng chứng: Confirmed (Đã xác nhận) / Observed (Quan sát) / Hypothesized (Giả thuyết).
+    Vượt qua Tiêu chí rời khỏi Khảo sát (Gate 0) trước khi chuyển tiếp.
+  </phase>
+
+  <phase order="2" name="Innovate">
+    CHỈ ĐỌC. Đề xuất 2–3 phương án kèm ma trận đánh đổi. Không tự ý đơn phương quyết định.
+    Tạo `decision.md`. Kỹ sư phê duyệt Gate 1.
+  </phase>
+
+  <phase order="3" name="Plan">
+    Chỉ tạo/sửa artifact kế hoạch — không sửa mã nguồn.
+    Phân rã thành các lát cắt dọc (vertical slices) kèm verifiers, điểm hoàn nguyên và hợp đồng phạm vi.
+    Tạo `plan.md`. Kỹ sư phê duyệt Gate 2.
+  </phase>
+
+  <phase order="4" name="Execute">
+    Chỉ đọc/ghi trong phạm vi đã duyệt từ `plan.md`.
+    Thực hiện từng lát cắt một. Chạy verifier sau mỗi slice. Cập nhật `state.md` sau mỗi slice.
+  </phase>
+
+  <phase order="5" name="Review">
+    CHỈ ĐỌC. Có thể chạy các lệnh kiểm thử xác minh. Không sửa mã nguồn.
+    Tạo `review.md` kèm các phát hiện. Gate 3 phải PASS trước khi bàn giao.
+  </phase>
+</operational_phases>
+
+</process_orchestration>

package/templates/vi/process/_seeds/_GUIDE.md

@@ -0,0 +1,170 @@
+# Cẩm Nang Blueprints & Seeds Mẫu (Seeds Guide)
+
+<seeds_guide version="2.0" framework="RIPER-5">
+
+<scope>
+  `_seeds/` là thư mục mẫu chuẩn chỉ đọc (read-only scaffolding).
+  Sao chép và khởi tạo các seed này khi tạo task mới, chương trình lớn hoặc nhóm ngữ cảnh.
+  Không bao giờ chỉnh sửa trực tiếp bên trong `_seeds/` — luôn luôn sao chép trước khi dùng.
+</scope>
+
+---
+
+## 1. Danh Mục Blueprints Mẫu
+
+<catalog>
+
+  <seed type="task" path="task-template.md.seed">
+    Hợp đồng master và bản lưu vết trạng thái xuyên suốt toàn bộ vòng đời RIPER-5.
+    Bao gồm: Metadata kiểm soát task, Đặc tả (Spec), Ranh giới ngữ cảnh, Chiến lược kiểm chứng,
+    Quyết định kỹ thuật, Kế hoạch thực thi RIPER-5 (kèm Gates G0–G3), và Ranh giới an toàn (Guardrails).
+  </seed>
+
+  <seed type="research" path="context-group.md.seed">
+    Artifact của giai đoạn Khảo sát (Research). CHỈ ĐỌC trong lúc thực hiện.
+    Bao gồm: Hành vi hiện tại, Luồng thực thi, Các thành phần liên quan, Ranh giới hệ thống,
+    Test hiện có, Cấu hình/Runtime, Phân tích nguồn sự thật, Phân loại bằng chứng
+    (Confirmed / Observed / Hypothesized), Giả định, Danh sách file bị ảnh hưởng,
+    Quyết định mở, và Tiêu chí rời khỏi Khảo sát.
+  </seed>
+
+  <seed type="decision" path="decision-template.md.seed">
+    Artifact của giai đoạn Đề xuất giải pháp (Innovate). Bộ nhớ lưu vết Gate 1.
+    Bao gồm: Câu hỏi quyết định, Các phương án (A/B/C) kèm ma trận đánh đổi (Trade-off),
+    Khuyến nghị của Agent, Quyết định của Kỹ sư (bắt buộc con người điền), Ràng buộc phái sinh,
+    Bằng chứng còn cần xác minh, và Checklist Gate 1.
+  </seed>
+
+  <seed type="plan" path="plan-template.md.seed">
+    Artifact của giai đoạn Lập kế hoạch (Plan). Bản hợp đồng thực thi.
+    Bao gồm: Artifact đầu vào, Ràng buộc thực thi (file được phép/bị cấm, lệnh được phép),
+    Bảng tóm tắt lát cắt (Slice Summary), Chi tiết từng slice (mục tiêu, thay đổi cụ thể,
+    verifier, bằng chứng kỳ vọng, điểm hoàn nguyên rollback, điều kiện dừng),
+    Hợp đồng phạm vi (Scope Contract), Ma trận kiểm chứng, và Checklist Gate 2.
+  </seed>
+
+  <seed type="state" path="state-template.md.seed">
+    Bộ nhớ bền vững của vòng lặp Thực thi (Execute). Cập nhật ngay sau mỗi slice.
+    Bao gồm: Phase/Gate hiện tại, Tham chiếu task, Mục tiêu/Bất biến, Quyết định đã duyệt,
+    Các slice đã xong, Slice hiện tại, Git diff hiện tại, Bằng chứng kiểm chứng,
+    Bộ nhớ lỗi (failure memory: signature/hypothesis/experiment/result), Ngân sách thử lại,
+    Thay đổi phạm vi, Rủi ro mở, Hành động tiếp theo, và Kiểm tra độ tươi mới của ngữ cảnh.
+  </seed>
+
+  <seed type="review" path="review-template.md.seed">
+    Artifact của giai đoạn Nghiệm thu (Review). Tách biệt hoàn toàn với Handoff.
+    Bao gồm: Phạm vi review, Review hành vi, Review kiến trúc, Review dữ liệu,
+    Review bảo mật, Review hồi quy, Bảng phát hiện (findings: category/severity/type),
+    Ma trận kiểm chứng, Rủi ro tồn đọng (residual risk), Quyết định review, và Checklist Gate 3.
+  </seed>
+
+  <seed type="handoff" path="handoff-template.md.seed">
+    Artifact tóm tắt bàn giao cuối cùng. Cố tình thiết kế ngắn gọn.
+    Trả lời 4 câu hỏi: Đã thay đổi gì? Vì sao? Bằng chứng nào chứng minh? Còn rủi ro gì?
+    KHÔNG lặp lại chi tiết dài dòng từ các artifact research/plan/review.
+  </seed>
+
+  <seed type="program" path="program-template.md.seed">
+    Bản thiết kế chương trình lớn nhiều giai đoạn với kế hoạch tổng thể, phân rã phase,
+    danh mục bán kính ảnh hưởng (blast radius), và quy tắc cổng chuyển giao từng phase.
+  </seed>
+
+  <seed type="cancellation" path="cancellation-template.md.seed">
+    Biên bản hủy task. Lưu giữ kết quả khảo sát, lý do quyết định,
+    các prototype/test có thể tái sử dụng, và kiểm tra hoàn nguyên khi một task đang làm bị dừng giữa chừng.
+  </seed>
+
+  <seed type="results" path="results-template.tsv.seed">
+    Bảng đăng ký đánh giá số liệu benchmark và định lượng.
+    Dùng để theo dõi latency, throughput, bộ nhớ hoặc điểm đánh giá qua các vòng lặp và lát cắt dọc.
+  </seed>
+
+</catalog>
+
+---
+
+## 2. Chuỗi Artifact Trong Mỗi Task
+
+Mỗi task active đều tuân thủ chuỗi artifact sau:
+
+```text
+task.md         ← Hợp đồng master & lưu vết trạng thái RIPER
+research.md     ← Đầu ra giai đoạn Research (chế độ CHỈ ĐỌC)
+decision.md     ← Đầu ra giai đoạn Innovate, lưu vết Gate 1
+plan.md         ← Đầu ra giai đoạn Plan, hợp đồng thực thi, Gate 2
+state.md        ← Bộ nhớ tiến độ vòng lặp Execute (cập nhật sau mỗi slice)
+review.md       ← Đầu ra giai đoạn Review, Gate 3
+handoff.md      ← Tóm tắt bàn giao cuối cùng (ngắn gọn)
+```
+
+### Bảng Ánh Xạ Khái Niệm → Tệp Artifact
+
+| Khái niệm | Artifact |
+|---|---|
+| Task / Đặc tả | `task.md` |
+| Khảo sát / Ngữ cảnh | `research.md` |
+| Đề xuất / Quyết định | `decision.md` |
+| Kế hoạch lát cắt | `plan.md` |
+| Trạng thái vòng lặp | `state.md` |
+| Thực thi | mã nguồn + kiểm thử + `state.md` |
+| Nghiệm thu | `review.md` |
+| Bàn giao | `handoff.md` |
+| Gate 1 | Phê duyệt trong `decision.md` |
+| Gate 2 | Phê duyệt trong `plan.md` |
+| Gate 3 | Phê duyệt trong `review.md` |
+
+---
+
+## 3. Cấu Trúc Thư Mục Task Được Khuyến Nghị
+
+### Cấu Trúc Dự Án Đơn Chuẩn (Standard Single-Project)
+```text
+process/features/active/CHG-017-your-feature/
+├── task.md          ← khởi tạo từ task-template.md.seed (Đặc tả Master & AC)
+├── research.md      ← khởi tạo từ context-group.md.seed (Kết quả khảo sát)
+├── decision.md      ← khởi tạo từ decision-template.md.seed (Phương án Gate 1)
+├── plan.md          ← khởi tạo từ plan-template.md.seed (Hợp đồng thực thi Gate 2)
+├── state.md         ← khởi tạo từ state-template.md.seed (Bộ nhớ tiến độ)
+├── review.md        ← khởi tạo từ review-template.md.seed (Biên bản kiểm toán Gate 3)
+├── handoff.md       ← khởi tạo từ handoff-template.md.seed (Tóm tắt bàn giao)
+├── results.tsv      ← (Tùy chọn) khởi tạo từ results-template.tsv.seed (Metrics/Benchmarks)
+└── cancelled.md     ← (Nếu hủy task) khởi tạo từ cancellation-template.md.seed
+```
+
+### Cấu Trúc Monorepo / Đa Miền (Tùy Chọn)
+Khi làm việc trong Monorepo với các domain độc lập (ví dụ: `mobile-app`, `billing-service`), phân chia features theo domain:
+```text
+process/features/{domain-slug}/
+├── active/
+│   └── CHG-XXX-your-feature/
+├── backlog/
+└── completed/
+```
+
+Không nhất thiết phải tạo tất cả các artifact ngay từ đầu. Hãy tạo dần dần khi task tiến triển qua các giai đoạn RIPER.
+
+---
+
+## 4. Các Lệnh Khởi Tạo Mẫu (Copy Commands)
+
+```bash
+# Tạo thư mục task mới
+mkdir -p process/features/active/CHG-XXX-your-feature
+
+# Khởi tạo các seed cơ bản vào thư mục task
+cp process/_seeds/task-template.md.seed     process/features/active/CHG-XXX-your-feature/task.md
+cp process/_seeds/context-group.md.seed    process/features/active/CHG-XXX-your-feature/research.md
+cp process/_seeds/decision-template.md.seed process/features/active/CHG-XXX-your-feature/decision.md
+cp process/_seeds/plan-template.md.seed    process/features/active/CHG-XXX-your-feature/plan.md
+cp process/_seeds/state-template.md.seed   process/features/active/CHG-XXX-your-feature/state.md
+cp process/_seeds/review-template.md.seed  process/features/active/CHG-XXX-your-feature/review.md
+cp process/_seeds/handoff-template.md.seed process/features/active/CHG-XXX-your-feature/handoff.md
+
+# (Tùy chọn) Khi cần theo dõi hiệu năng hoặc số liệu benchmark:
+cp process/_seeds/results-template.tsv.seed process/features/active/CHG-XXX-your-feature/results.tsv
+
+# (Khi cần hủy bỏ một task đang dang dở):
+cp process/_seeds/cancellation-template.md.seed process/features/active/CHG-XXX-your-feature/cancelled.md
+```
+
+</seeds_guide>

package/templates/vi/process/_seeds/cancellation-template.md.seed

@@ -0,0 +1,79 @@
+# Biên Bản Hủy Task (Cancellation Record): [TASK-ID] [Tiêu Đề Task]
+
+<cancellation_record task_id="[TASK-ID]" version="1.0" framework="RIPER-5">
+
+<!--
+  QUY CHUẨN HỦY BỎ TASK:
+  - Mục đích: Lưu giữ tri thức khảo sát, phát hiện kỹ thuật và lý do quyết định khi một task bị hủy giữa chừng.
+  - Tuyệt đối không xóa thẳng thư mục task nếu đã diễn ra khảo sát hoặc lập kế hoạch một phần.
+  - Khởi tạo tệp này dưới dạng `cancelled.md` bên trong thư mục task.
+  - Hoàn thành checklist hoàn nguyên, sau đó chuyển thư mục task sang `completed/` (hoặc `cancelled/`).
+-->
+
+<status>
+  <phase_at_cancellation>[RESEARCH | INNOVATE | PLAN | EXECUTE | REVIEW]</phase_at_cancellation>
+  <cancelled_date>[YYYY-MM-DD hoặc DD-MM-YY]</cancelled_date>
+  <cancelled_by>[@engineer_or_product_lead]</cancelled_by>
+  <reversal_status>[CLEAN | ROLLBACK_APPLIED | DIRTY_NEEDS_MANUAL_CLEANUP]</reversal_status>
+</status>
+
+---
+
+## 1. Lý Do Hủy Bỏ (Rationale for Cancellation)
+
+<cancellation_rationale>
+  <primary_reason>
+    <!-- [ví dụ: Thay đổi chiến lược sản phẩm / Rào cản kiến trúc / Bán kính ảnh hưởng quá lớn / Bị thay thế bởi CHG-YYY] -->
+    [Tóm tắt ngắn gọn vì sao task này bị dừng trước thời hạn.]
+  </primary_reason>
+
+  <decision_context>
+    [Ngữ cảnh chi tiết, các đánh đổi đã cân nhắc và chỉ đạo chính từ các bên liên quan dẫn đến quyết định hủy.]
+  </decision_context>
+</cancellation_rationale>
+
+---
+
+## 2. Phát Hiện Kỹ Thuật & Tri Thức Được Lưu Giữ (Preserved Knowledge)
+
+<preserved_knowledge>
+  <codebase_discoveries>
+    <!-- Chúng ta đã học được gì về hệ thống, data models hoặc dependency tiềm ẩn trong lúc làm task này? -->
+    - [Phát hiện 1 — Hành vi của component, giới hạn API chưa có tài liệu hoặc ràng buộc legacy]
+    - [Phát hiện 2 — Các bài test hiện có hoặc ranh giới subsystem được khám phá]
+  </codebase_discoveries>
+
+  <invalidated_hypotheses>
+    <!-- Những giả định nào đã bị chứng minh là sai trong quá trình khảo sát? -->
+    - [Giả thuyết hóa ra không đúng hoặc không khả thi về mặt kỹ thuật]
+  </invalidated_hypotheses>
+
+  <reusable_assets>
+    <!-- Có bài test, bản nháp schema, benchmark hoặc prototype nào các task sau có thể tái sử dụng không? -->
+    - [Tài sản tái sử dụng 1: các ca test hoặc mô hình dữ liệu trong branch nháp / commit]
+  </reusable_assets>
+</preserved_knowledge>
+
+---
+
+## 3. Checklist Hoàn Nguyên Mã Nguồn & Dọn Dẹp (Cleanup Checklist)
+
+<cleanup_checklist>
+  - [ ] Toàn bộ thay đổi chưa commit đã được rollback hoặc stash sạch sẽ (`git status` sạch hoàn toàn)
+  - [ ] Các dòng log debug tạm thời, script scratch hoặc dump dữ liệu test đã bị xóa
+  - [ ] Không còn migration ảo hoặc artifact schema tạm nào bị sót lại trong database nội bộ
+  - [ ] Thư mục task đã được chuyển vào lưu trữ trong `completed/` (hoặc `cancelled/`)
+</cleanup_checklist>
+
+---
+
+## 4. Task Thay Thế Hoặc Kế Hoạch Tiếp Theo (Follow-Up)
+
+<follow_up>
+  <superseded_by>[Liên kết tới thư mục task mới hoặc CHG-YYY, hoặc ghi NONE]</superseded_by>
+  <recommended_next_action>
+    [Khuyến nghị cụ thể nếu bài toán này được xem xét lại trong tương lai.]
+  </recommended_next_action>
+</follow_up>
+
+</cancellation_record>

package/templates/vi/process/_seeds/context-group.md.seed

@@ -0,0 +1,154 @@
+# Khảo Sát (Research): [TASK-ID]
+
+<research_context task_id="[TASK-ID]" version="2.0" framework="RIPER-5">
+
+<!-- GIAI ĐOẠN CHỈ ĐỌC (READ-ONLY). Không sửa mã nguồn. Không tự ý ra quyết định triển khai. -->
+<research_status>
+  <phase>RESEARCH</phase>
+  <mode>READ-ONLY</mode>
+  <research_owner></research_owner>
+  <last_updated></last_updated>
+</research_status>
+
+---
+
+## 1. Hành Vi Hiện Tại (Current Behavior)
+
+<current_behavior>
+  [Hành vi quan sát được của hệ thống trước thay đổi này, dựa trên bằng chứng cụ thể.]
+</current_behavior>
+
+---
+
+## 2. Luồng Thực Thi (Execution Flow)
+
+<execution_flow>
+
+```text
+Điểm vào (Entry)
+→ ...
+→ ...
+→ Tác dụng phụ / Đầu ra (Side effect / output)
+```
+
+</execution_flow>
+
+---
+
+## 3. Các Thành Phần Liên Quan (Relevant Components)
+
+<components>
+
+| File / Symbol | Vai trò | Bằng chứng | Độ tin cậy (Confidence) |
+|---|---|---|---|
+| | | | |
+
+</components>
+
+---
+
+## 4. Phụ Thuộc & Ranh Giới (Dependencies & Boundaries)
+
+<boundaries>
+  <callers>[Ai gọi đến đoạn code mục tiêu này]</callers>
+  <callees>[Đoạn code mục tiêu gọi đến những thành phần nào]</callees>
+  <persistence>[Bảng cơ sở dữ liệu, cache keys, hàng đợi queues]</persistence>
+  <external_systems>[API bên thứ ba, message brokers bên ngoài]</external_systems>
+  <transaction_boundary>[Nơi transaction cơ sở dữ liệu bắt đầu và kết thúc]</transaction_boundary>
+  <security_boundary>[Ngữ cảnh xác thực auth, kiểm tra phân quyền, ranh giới tin cậy]</security_boundary>
+</boundaries>
+
+---
+
+## 5. Các Bài Kiểm Thử Hiện Có (Existing Tests)
+
+<existing_tests>
+
+| Bài test | Hành vi được bao phủ | Lỗ hổng / Điểm thiếu (Gap) |
+|---|---|---|
+| | | |
+
+</existing_tests>
+
+---
+
+## 6. Môi Trường Chạy & Cấu Hình (Runtime / Configuration)
+
+<runtime_config>
+  [Biến môi trường, feature flags, tệp cấu hình liên quan đến thay đổi này.]
+</runtime_config>
+
+---
+
+## 7. Phân Tích Nguồn Sự Thật (Source-of-Truth Analysis)
+
+<source_of_truth_analysis>
+
+| Nguồn | Quy định điều gì | Thẩm quyền | Xung đột |
+|---|---|---|---|
+| | | | |
+
+</source_of_truth_analysis>
+
+---
+
+## 8. Phân Loại Bằng Chứng (Evidence Classification)
+
+<!-- TUYỆT ĐỐI KHÔNG trộn lẫn sự thật thực tế, quan sát và giả định trong cùng một danh sách -->
+<evidence>
+  <confirmed>
+    <!-- Đã xác minh trực tiếp từ mã nguồn, bài test hoặc tài liệu chuẩn -->
+    -
+  </confirmed>
+
+  <observed>
+    <!-- Suy luận từ hành vi, log hoặc đọc gián tiếp — chưa chứng minh trực tiếp -->
+    -
+  </observed>
+
+  <hypothesized>
+    <!-- Các giả định còn cần kiểm chứng trước khi thực hiện -->
+    -
+  </hypothesized>
+</evidence>
+
+---
+
+## 9. Các Giả Định & Độ Không Chắc Chắn (Assumptions & Uncertainty)
+
+<assumptions>
+  [Liệt kê bất kỳ giả định nào định hình kết luận khảo sát. Gắn cờ độ không chắc chắn: LOW / MEDIUM / HIGH.]
+</assumptions>
+
+---
+
+## 10. Danh Sách Tệp Bị Ảnh Hưởng (Impacted Files)
+
+<impacted_files>
+  - `duong/dan/toi/file` — [Lý do bị ảnh hưởng]
+</impacted_files>
+
+---
+
+## 11. Các Quyết Định Đang Mở (Open Decisions)
+
+<open_decisions>
+  <!-- Các câu hỏi chưa được giải quyết cần đưa vào giai đoạn Innovate (decision.md) -->
+  -
+</open_decisions>
+
+---
+
+## 12. Tiêu Chí Rời Khỏi Khảo Sát (Research Exit Criteria)
+
+<research_exit_criteria>
+  - [ ] Hành vi hiện tại đã được hiểu rõ và ghi nhận đầy đủ.
+  - [ ] Luồng thực thi đã được truy vết từ đầu đến cuối (end-to-end).
+  - [ ] Các ranh giới liên quan đã được xác định (callers, callees, persistence, security).
+  - [ ] Xung đột nguồn sự thật đã được làm rõ hoặc xác nhận không có xung đột.
+  - [ ] Danh sách các tệp bị ảnh hưởng đã được xác định rõ ràng.
+  - [ ] Bằng chứng đã được phân loại rõ ràng (Confirmed / Observed / Hypothesized).
+  - [ ] Không còn rào cản khảo sát nào chưa giải quyết.
+</research_exit_criteria>
+
+</research_context>