@damphuquy/agent-init 1.4.4 → 2.1.0

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

@@ -12,7 +12,7 @@
   ### Triết Lý Thiết Kế Seeds: Bản Chất "Why" & "How"
   * **Tại sao là đuôi `.seed`? (Why):** Đuôi `.seed` đóng vai trò ranh giới bất biến (Blueprint Immutability). Nó giúp phân biệt rõ ràng giữa "khuôn mẫu phôi" và "tài liệu markdown đang làm việc" (`*.md`). Khi AI quét repo bằng các công cụ tìm kiếm, hậu tố `.seed` bảo vệ các file này không bao giờ bị AI sửa đè vào làm hỏng template gốc của cả dự án.
   * **Tại sao tách riêng từng seed theo phase? (Why):** Mỗi giai đoạn trong chu trình RIPER-5 đòi hỏi một kiểu tư duy và ranh giới quyền hạn khác biệt (Khảo sát vs Đề xuất vs Lập kế hoạch vs Thực thi vs Nghiệm thu). Việc tách rời giúp AI chỉ nạp đúng artifact cần thiết, chống phình to context window (Anti-Context Saturation) và gắn chặt với từng Cổng kiểm soát (Gates G1–G3).
-  * **Quy tắc Copy-On-Demand (How):** Tuyệt đối không copy hàng loạt tất cả seed vào thư mục task. Bắt đầu duy nhất với `task.md`. Khi task tiến vào phase nào, mới lần lượt khởi tạo artifact của phase đó (`research.md` $\rightarrow$ `decision.md` $\rightarrow$ `plan.md` $\rightarrow$ `state.md` $\rightarrow$ `review.md` $\rightarrow$ `handoff.md`).
+  * **Quy tắc Copy-On-Demand (How):** Tuyệt đối không copy hàng loạt tất cả seed vào thư mục task. Bắt đầu duy nhất với `task.md`. Khi task tiến vào phase nào, mới lần lượt khởi tạo artifact của phase đó (`research.md` $\rightarrow$ `decision.md` $\rightarrow$ `plan.md` $\rightarrow$ `state.md` $\rightarrow$ `review.md` $\rightarrow$ `handoff.md`). Ở chế độ PAIR, Agent dừng lại chờ người dùng duyệt cổng. Ở chế độ DELEGATED / Fast-Track, Agent tự động khởi tạo seed kế tiếp, tự động duyệt cổng và chạy liên tục không gián đoạn.
 </architectural_rationale>
 
 ---
@@ -23,7 +23,7 @@
 
   <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,
+    Bao gồm: Metadata kiểm soát task (working_mode PAIR/DELEGATED), Đặ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>
 
@@ -38,7 +38,7 @@
   <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,
+    Khuyến nghị của Agent, Quyết định Triển khai (Kỹ sư điền ở PAIR, hoặc Agent tự động chọn ở DELEGATED), Ràng buộc phái sinh,
     Bằng chứng còn cần xác minh, và Checklist Gate 1.
   </seed>
 
@@ -121,9 +121,13 @@ handoff.md      ← Tóm tắt bàn giao cuối cùng (ngắn gọn)
 | 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` |
+| Tạm dừng / Đóng băng | `paused.md` (đóng băng sạch sẽ & checklist mở lại) |
+| 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á) |
+| Chương trình lớn | `program.md` (bản thiết kế chương trình lớn nhiều giai đoạn) |
+| Gate 1 | Phê duyệt trong `decision.md` (Kỹ sư hoặc Auto-DELEGATED) |
+| Gate 2 | Phê duyệt trong `plan.md` (Kỹ sư hoặc Auto-DELEGATED) |
+| Gate 3 | Nghiệm thu trong `review.md` (Kỹ sư hoặc Auto-DELEGATED) |
 
 ---
 

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

@@ -2,7 +2,7 @@
 
 <technical_decision task_id="[TASK-ID]" dec_id="[DEC-ID]" version="1.0" framework="RIPER-5">
 
-<!-- GIAI ĐOẠN CHỈ ĐỌC (READ-ONLY). Đề xuất các phương án. Không tự ý quyết định khi chưa có kỹ sư duyệt. -->
+<!-- GIAI ĐOẠN CHỈ ĐỌC (READ-ONLY). Đề xuất các phương án. PAIR: kỹ sư chọn. DELEGATED: agent tự chọn phương án tối ưu và tự động chuyển phase. -->
 <decision_status>
   <phase>INNOVATE</phase>
   <mode>READ-ONLY</mode>
@@ -98,9 +98,11 @@
 
 ---
 
-## 6. Quyết Định Của Kỹ Sư (Engineer Decision)
+## 6. Quyết Định Triển Khai (Implementation Decision)
 
-<!-- Phần này BẮT BUỘC kỹ sư con người phải điền trước khi Gate 1 được thông qua -->
+<!-- Chế độ PAIR: Kỹ sư con người điền phần này trước khi duyệt Gate 1.
+     Chế độ DELEGATED / Fast-Track: Agent tự động điền phương án khuyến nghị (Recommendation)
+     vào <selected_option>, ghi rõ rationale và ký duyệt Gate 1 với [AUTO: DELEGATED]. -->
 <engineer_decision>
   <selected_option></selected_option>
   <rationale></rationale>
@@ -133,10 +135,9 @@
 
 <gate id="G1">
   - [ ] Toàn bộ phương án đã được trình bày và phân tích đánh đổi.
-  - [ ] Kỹ sư đã xem xét các phương án.
-  - [ ] Phương án do kỹ sư chọn đã được ghi nhận ở trên.
+  - [ ] Phương án được chọn đã được ghi nhận ở trên.
   - [ ] Không còn quyết định nghiệp vụ / schema / bảo mật nào đang bỏ ngỏ.
-  <approved_by></approved_by>
+  <approved_by></approved_by>  <!-- Tên kỹ sư (PAIR) hoặc [AUTO: DELEGATED] (DELEGATED/Fast-Track) -->
   <approved_date></approved_date>
 </gate>
 

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

@@ -127,8 +127,8 @@
   - [ ] Điều kiện dừng đã được định nghĩa cho từng slice.
   - [ ] Điểm hoàn nguyên (rollback point) đã được định nghĩa cho từng slice.
   - [ ] Danh sách lệnh được phép đã được liệt kê.
-  - [ ] Kỹ sư đã ký duyệt.
-  <approved_by></approved_by>
+  - [ ] Kế hoạch đã được ký duyệt.
+  <approved_by></approved_by>  <!-- Tên kỹ sư (PAIR) hoặc [AUTO: DELEGATED] (DELEGATED/Fast-Track) -->
   <approved_date></approved_date>
 </gate>
 

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

@@ -142,7 +142,7 @@
   - [ ] Rủi ro tồn đọng đã được chấp nhận rõ ràng.
   - [ ] Quyết định review: PASS.
   - [ ] Sẵn sàng bàn giao (handoff).
-  <approved_by></approved_by>
+  <approved_by></approved_by>  <!-- Tên kỹ sư (PAIR) hoặc [AUTO: DELEGATED] (DELEGATED/Fast-Track) -->
   <approved_date></approved_date>
 </gate>
 

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

@@ -6,10 +6,12 @@
      PHẦN 0 — KIỂM SOÁT TASK (bản lưu vết trạng thái master)
      ════════════════════════════════════════════ -->
 <task_control>
-  <status>BACKLOG</status>  <!-- BACKLOG | ACTIVE | BLOCKED | REVIEW | COMPLETED -->
+  <status>BACKLOG</status>  <!-- BACKLOG | ACTIVE | BLOCKED | PAUSED | REVIEW | COMPLETED | CANCELLED -->
   <spec_level>S1</spec_level>  <!-- S0=phác thảo | S1=đã định nghĩa | S2=đã kiểm chứng | S3=đã khóa -->
+  <priority>P2</priority>  <!-- P0=khẩn cấp | P1=cao | P2=bình thường | P3=thấp -->
   <risk>MEDIUM</risk>  <!-- LOW | MEDIUM | HIGH -->
-  <working_mode>PAIR</working_mode>  <!-- MANUAL | PAIR | DELEGATED | DIAGNOSE-ONLY -->
+  <estimated_story_points>2</estimated_story_points>  <!-- 1 SP ≈ 2-4 giờ làm việc kỹ thuật tập trung -->
+  <working_mode>PAIR</working_mode>  <!-- PAIR (mặc định: dừng chờ duyệt từng gate) | DELEGATED (fast-track: tự động chạy liên tục qua các phase) | MANUAL | DIAGNOSE-ONLY -->
   <current_phase>RESEARCH</current_phase>  <!-- RESEARCH | INNOVATE | PLAN | EXECUTE | REVIEW -->
   <owner>@engineer</owner>
   <decision_owner>@engineer</decision_owner>
@@ -63,6 +65,11 @@
     - `tests/[duong/dan/toi/test]` — [Khẳng định mục tiêu và test fixtures]
   </target_files>
 
+  <context_groups>
+    <!-- Tham chiếu tới các nhóm ngữ cảnh đã đăng ký trong process/context/all-context.md -->
+    - [planning | tests | protocols | domain-specific-group]
+  </context_groups>
+
   <source_of_truth>
     <requirement>[Liên kết tới tài liệu yêu cầu hoặc đặc tả]</requirement>
     <architecture>[Liên kết tới tài liệu kiến trúc hoặc ADR]</architecture>
@@ -117,18 +124,19 @@
       - [ ] Hành vi hiện tại đã được hiểu và ghi nhận tài liệu.
       - [ ] Luồng thực thi đã được truy vết đầy đủ.
       - [ ] Không còn rào cản khảo sát chưa giải quyết.
+      <!-- Ở chế độ DELEGATED / Fast-Track: Agent tự động đánh giá và chuyển sang Innovate -->
     </gate>
   </phase>
 
   <phase name="Innovate" order="2">
-    <!-- CHỈ ĐỌC. Đề xuất 2-3 phương án khả thi. Không tự ý đơn phương quyết định. -->
+    <!-- CHỈ ĐỌC. Đề xuất 2-3 phương án khả thi. PAIR: kỹ sư chọn. DELEGATED: agent tự chọn phương án tối ưu. -->
     - [ ] Đề xuất 2–3 hướng tiếp cận khác nhau kèm ma trận đánh đổi.
     - [ ] Tạo artifact `decision.md`.
     <gate id="G1" label="Gate 1 — Phê duyệt phương án (Decision Approved)">
-      - [ ] Các phương án đã được kỹ sư xem xét.
+      - [ ] Các phương án đã được xem xét và phân tích đánh đổi.
       - [ ] Phương án được chọn đã ghi nhận vào `decision.md`.
       - [ ] Không còn quyết định nghiệp vụ/schema/bảo mật nào đang bỏ ngỏ.
-      <approved_by></approved_by>
+      <approved_by></approved_by>  <!-- Tên kỹ sư (PAIR) hoặc [AUTO: DELEGATED] (DELEGATED/Fast-Track) -->
       <approved_date></approved_date>
     </gate>
   </phase>
@@ -142,8 +150,8 @@
       - [ ] Phạm vi file được phép / bị cấm sửa được xác định rõ ràng.
       - [ ] Điểm hoàn nguyên (rollback point) được định nghĩa cho từng slice.
       - [ ] Điều kiện dừng khẩn cấp được nêu rõ.
-      - [ ] Kỹ sư đã ký duyệt.
-      <approved_by></approved_by>
+      - [ ] Kế hoạch đã được ký duyệt.
+      <approved_by></approved_by>  <!-- Tên kỹ sư (PAIR) hoặc [AUTO: DELEGATED] (DELEGATED/Fast-Track) -->
       <approved_date></approved_date>
     </gate>
   </phase>
@@ -154,6 +162,7 @@
     - [ ] Chạy verifier ngay sau mỗi slice.
     - [ ] Kiểm tra git diff sau mỗi slice.
     - [ ] Cập nhật `state.md` sau mỗi slice.
+    - [ ] (Tùy chọn) Ghi nhận số liệu định lượng vào `results.tsv` nếu task có đo lường benchmark/hiệu năng.
   </phase>
 
   <phase name="Review" order="5">
@@ -163,9 +172,9 @@
     <gate id="G3" label="Gate 3 — Nghiệm thu đạt (Review Passed)">
       - [ ] Mọi AC đều được kiểm chứng kèm bằng chứng thực tế.
       - [ ] Rủi ro tồn đọng đã được chấp nhận.
-      - [ ] Quyết định review: PASS | CHANGES_REQUIRED | BLOCKED.
+      - [ ] Quyết định review: PASS.
       - [ ] Sẵn sàng bàn giao (handoff).
-      <approved_by></approved_by>
+      <approved_by></approved_by>  <!-- Tên kỹ sư (PAIR) hoặc [AUTO: DELEGATED] (DELEGATED/Fast-Track) -->
       <approved_date></approved_date>
     </gate>
   </phase>

package/templates/vi/process/context/all-context.md

@@ -26,7 +26,7 @@
   <group id="seeds">
     <title>Cẩm Nang Mẫu Chuẩn & Seeds</title>
     <path>[`../_seeds/_GUIDE.md`](../_seeds/_GUIDE.md)</path>
-    <scope>Blueprints mẫu cho task, research, decision, plan, state, review, handoff và program. Đầy đủ chuỗi artifact và lệnh khởi tạo.</scope>
+    <scope>Blueprints mẫu cho task, research, decision, plan, state, review, handoff, tạm dừng task, hủy task, benchmark định lượng và program. Đầy đủ chuỗi artifact và lệnh khởi tạo.</scope>
   </group>
 
   <group id="tests">

package/templates/vi/process/context/planning/all-planning.md

@@ -1,31 +1,87 @@
 # Quy Chuẩn Lập Kế Hoạch & Hiệu Chỉnh Năng Lực (Planning Context)
 
-<planning_context version="1.0">
+<planning_context version="2.0">
 
 <overview>
-  Hướng dẫn ước lượng Story Point, phân rã lát cắt dọc và hiệu chỉnh năng lực thực thi.
+  Hướng dẫn kỹ thuật về ước lượng Story Point, phân rã lát cắt dọc (Vertical Slicing), điểm hoàn nguyên rollback và hiệu chỉnh năng lực thực thi.
 </overview>
 
-## 1. Tiêu Chuẩn Chất Lượng (Quality Standards)
+---
+
+## 1. Tiêu Chuẩn Chất Lượng (Tiêu Chuẩn INVEST)
+
 <quality_standards>
   <standard name="INVEST">
-    - **Độc lập (Independent):** Có thể bàn giao mà không bị chặn bởi các story khác.
-    - **Thương lượng được (Negotiable):** Chi tiết triển khai có thể tinh chỉnh linh hoạt.
-    - **Có giá trị (Valuable):** Mang lại giá trị đo lường được cho người dùng hoặc doanh nghiệp.
-    - **Ước lượng được (Estimable):** Phạm vi đủ rõ để ước lượng khối lượng công việc.
-    - **Nhỏ gọn (Small):** Hoàn thành vừa vặn trong 1-3 ngày làm việc của kỹ sư.
-    - **Kiểm chứng được (Testable):** Có Tiêu chí nghiệm thu (AC) cụ thể, đo lường được.
-  </standard>
-
-  <standard name="Vertical Slicing (Cắt Lát Dọc)">
-    Tránh chia việc theo các tầng ngang độc lập (horizontal silos). Bàn giao từng lát cắt dọc hoàn chỉnh xuyên suốt qua API, logic nghiệp vụ và lưu trữ dữ liệu.
+    - **Độc lập (Independent):** Có thể bàn giao và kiểm chứng độc lập mà không bị phụ thuộc vòng vo vào story khác.
+    - **Thương lượng được (Negotiable):** Chi tiết kỹ thuật và phương án tiếp cận có thể linh hoạt đánh giá trong giai đoạn Innovate.
+    - **Có giá trị (Valuable):** Mang lại năng lực hệ thống rõ ràng hoặc tiến bộ kỹ thuật đo lường được.
+    - **Ước lượng được (Estimable):** Phạm vi đủ rõ và danh sách file cần sửa đủ hẹp để tính toán khối lượng công việc.
+    - **Nhỏ gọn (Small):** Hoàn thành vừa vặn trong 1–3 ngày làm việc của kỹ sư (hoặc 1–3 Story Points).
+    - **Kiểm chứng được (Testable):** Kèm theo các Tiêu chí nghiệm thu (AC) rõ ràng, kiểm chứng được (`- [ ]`).
   </standard>
 </quality_standards>
 
-## 2. Hiệu Chỉnh Năng Lực (Capacity Calibration)
+---
+
+## 2. Kỷ Luật Cắt Lát Dọc (Vertical Slicing Discipline)
+
+<vertical_slicing>
+  ### Lát Cắt Dọc (Vertical Slice) vs Tầng Ngang (Horizontal Silo)
+  - **Quy tắc Lát Cắt Dọc:** Mỗi lát cắt bắt buộc phải đi xuyên suốt toàn bộ các tầng kỹ thuật cần thiết (ví dụ: Thực thể Domain $\rightarrow$ Service/Logic $\rightarrow$ Port Adapter/API $\rightarrow$ Bài kiểm thử tự động) để mang lại một gia số hành vi hoàn chỉnh, kiểm chứng được.
+  - **Phản mẫu Tầng Ngang (Anti-Pattern):** Tuyệt đối không chia việc theo tầng ngang (ví dụ: Slice 1: tạo toàn bộ bảng DB, Slice 2: viết toàn bộ logic service, Slice 3: tạo toàn bộ API endpoint). Các tầng ngang không thể kiểm chứng độc lập, khiến toàn hệ thống ở trạng thái dở dang hoặc không thể chạy test cho đến tận slice cuối cùng.
+
+  ### Luồng Triển Khai Lát Cắt Dọc Mẫu
+  ```text
+  [Slice 1: Lõi tối thiểu xuyên suốt] ──► Domain Entity + Repo giả lập bộ nhớ + Endpoint tối thiểu + Test pass
+  [Slice 2: Lưu trữ & Ranh giới]      ──► Adapter Database thật + File Migration + Kiểm thử tích hợp
+  [Slice 3: Trường hợp biên & Xử lý]  ──► Chuẩn hóa đầu vào nghiêm ngặt + Bắt lỗi + Test trường hợp biên
+  ```
+</vertical_slicing>
+
+---
+
+## 3. Quy Mô Lát Cắt, Khả Năng Kiểm Chứng & Checkpoint
+
+<slice_sizing>
+  <rule id="slice_cardinality">
+    Một task tiêu chuẩn chỉ nên chứa từ **2 đến 5 lát cắt dọc**. Nếu một task đòi hỏi hơn 5 slice, bán kính ảnh hưởng của nó quá lớn và bắt buộc phải phân rã thành Chương trình nhiều giai đoạn (`program-template.md.seed`).
+  </rule>
+
+  <rule id="autonomous_verifier">
+    Mỗi slice trong `plan.md` bắt buộc phải có lệnh kiểm chứng `<verifier>` tường minh, tự động chạy được (ví dụ: `npm run test -- test/duong/dan/test.js` hoặc `pytest tests/unit/test_slice.py`). Một slice CHƯA ĐƯỢC COI LÀ XONG nếu lệnh verifier chưa exit với mã 0.
+  </rule>
+
+  <rule id="atomic_checkpoint">
+    Commit hoặc đánh dấu checkpoint git sau khi mỗi slice vượt qua verifier. Điều này đảm bảo lịch sử git tinh gọn và cho phép hoàn nguyên ngay lập tức nếu các slice sau gặp lỗi không thể cứu vãn.
+  </rule>
+</slice_sizing>
+
+---
+
+## 4. Chiến Lược Hoàn Nguyên (Rollback Strategy) Cho Từng Slice
+
+<rollback_strategy>
+  Mỗi slice trong `plan.md` BẮT BUỘC phải chỉ định một điểm hoàn nguyên cụ thể `<rollback_point>`:
+  - **Checkpoint Git:** `git checkout -- <allowed_files>` hoặc commit hash đảo ngược.
+  - **Checkpoint Stash:** `git stash pop` hoặc branch WIP riêng biệt.
+  - **Rollback Dữ liệu / Schema:** Script down-migration hoặc xóa container test tạm thời.
+
+  Nếu Agent cạn kiệt ngân sách thử lại 3 lần cho một slice, Agent phải thực thi rollback point trước khi dừng lại và xin chỉ thị từ con người.
+</rollback_strategy>
+
+---
+
+## 5. Hiệu Chỉnh Năng Lực & Story Point (Capacity Calibration)
+
 <capacity_calibration>
-  <unit>1 Story Point ≈ 2-4 giờ làm việc kỹ thuật tập trung</unit>
-  <max_task_size>3-5 Story Points (các task lớn hơn bắt buộc phải phân rã nhỏ hơn)</max_task_size>
+  <unit>1 Story Point (SP) ≈ 2–4 giờ làm việc kỹ thuật tập trung</unit>
+  <scale>
+    - **1 SP:** Thay đổi thẳng thắn, phạm vi hẹp và rõ ràng (sửa 1-3 files, 1-2 slices).
+    - **2 SP:** Tính năng tiêu chuẩn hoặc refactor có phạm vi (sửa 3-5 files, 2-3 slices).
+    - **3 SP:** Tác vụ phức tạp vừa phải tác động đến hợp đồng domain và lưu trữ (sửa 4-7 files, 3-4 slices).
+    - **5 SP:** Quy mô tối đa cho một task active đơn lẻ trong `process/features/active/`.
+    - **> 5 SP:** Quá lớn. Bắt buộc phải tách thành nhiều task độc lập hoặc tổ chức dưới `program-template.md.seed`.
+  </scale>
 </capacity_calibration>
 
 </planning_context>

package/templates/vi/process/context/tests/all-tests.md

@@ -1,56 +1,113 @@
 # Tiêu Chuẩn Kiểm Thử & Chiến Lược Khung Thử Nghiệm (Testing Context)
 
-<testing_context version="1.0">
+<testing_context version="2.0">
 
 <overview>
-  Hướng dẫn hiệu chỉnh kim tự tháp kiểm thử, chính sách cách ly, quy ước mock và khung kiểm tra tự động xuyên suốt hệ thống.
+  Hướng dẫn hiệu chỉnh kim tự tháp kiểm thử, chính sách cách ly, quy ước mock, vệ sinh fixture dữ liệu và khung kiểm tra tự động xuyên suốt hệ thống.
 </overview>
 
-## 1. Kim Tự Tháp Kiểm Thử & Phân Loại (Test Pyramid & Classification)
+---
+
+## 1. Kim Tự Tháp Kiểm Thử & Phân Loại Tầng (Test Pyramid & Classification)
+
 <test_pyramid>
   <layer name="Unit Tests (Kiểm thử đơn vị)" path="tests/unit/">
-    - Phạm vi: Logic nghiệp vụ thuần túy, domain models, hàm tiện ích, phân nhánh trường hợp biên.
-    - Tốc độ thực thi: Rất nhanh (< 50ms mỗi test), không có I/O mạng / đĩa / ngoại vi.
-    - Chính sách mock: Mock toàn bộ ranh giới I/O, client bên ngoài và giao diện cổng (port interfaces).
+    - **Phạm vi:** Logic nghiệp vụ thuần túy, mô hình domain, hàm tiện ích, rẽ nhánh trường hợp biên.
+    - **Tốc độ & Ràng buộc:** Cực nhanh (< 50ms mỗi test). Không gọi mạng, không đọc/ghi đĩa I/O, không kết nối database thật.
+    - **Chính sách Mock:** Mock toàn bộ giao diện cổng (port interfaces), client ngoại vi và ranh giới I/O.
   </layer>
 
   <layer name="Integration Tests (Kiểm thử tích hợp)" path="tests/integration/">
-    - Phạm vi: Lưu trữ cơ sở dữ liệu, adapter gọi API bên ngoài, cấu hình framework.
-    - Mức độ cách ly: Test containers tạm thời (ví dụ: Testcontainers) hoặc database test cách ly riêng cho từng suite.
-    - Dọn dẹp (Teardown): Phải đảm bảo không rò rỉ dữ liệu hoặc trạng thái giữa các lần chạy test.
+    - **Phạm vi:** Adapter lưu trữ repository, truy vấn cơ sở dữ liệu, file migration, wrapper gọi HTTP client, cấu hình framework.
+    - **Cách ly:** Test containers tạm thời (ví dụ: Testcontainers), in-memory database, hoặc schema cách ly riêng cho mỗi worker chạy test.
+    - **Dọn dẹp (Teardown):** Bắt buộc phải đảm bảo dọn dẹp dữ liệu 100%, không để rò rỉ trạng thái giữa các lần chạy.
   </layer>
 
   <layer name="End-to-End Tests (Kiểm thử đầu-cuối)" path="tests/e2e/">
-    - Phạm vi: Các luồng trải nghiệm người dùng trọng yếu, toàn bộ vòng đời HTTP/gRPC API, regression smoke tests.
-    - Kiểm chứng: Xác thực tính toàn vẹn hợp đồng đầu-cuối xuyên suốt các subsystem.
+    - **Phạm vi:** Các luồng trải nghiệm người dùng trọng yếu, toàn bộ vòng đời API công khai, luồng xác thực auth hoàn chỉnh, regression smoke tests.
+    - **Kiểm chứng:** Xác thực tính toàn vẹn hợp đồng đầu-cuối xuyên suốt toàn bộ hệ thống.
   </layer>
 </test_pyramid>
 
-## 2. Chính Sách Khung Kiểm Thử (Test Harness Policies)
-<test_policies>
-  <policy name="Determinism (Tính tiền định)">
-    Tuyệt đối không có test chập chờn (flaky tests). Test không được phụ thuộc vào thời gian thực tế của đồng hồ hệ thống (sử dụng frozen clock hoặc fake timer) hay thứ tự thực thi ngẫu nhiên.
-  </policy>
+---
+
+## 2. Ranh Giới Mocking & Các Phản Mẫu (Mocking Boundaries)
+
+<mocking_boundaries>
+  <rule id="mock_at_architectural_boundary">
+    **Mock tại ranh giới kiến trúc, không bao giờ mock ở lõi.** Chỉ mock hạ tầng bên ngoài: HTTP API bên thứ ba, message broker, dịch vụ email, hoặc đồng hồ hệ thống.
+  </rule>
+
+  <rule id="do_not_mock_domain_or_sut">
+    Tuyệt đối không mock Hệ thống đang được kiểm thử (System Under Test - SUT) hoặc các thực thể domain / value objects thuần túy. Nếu một thực thể domain khó khởi tạo nếu thiếu mock, thiết kế đó đang bị thắt chặt và cần được tái cấu trúc (refactor).
+  </rule>
+
+  <rule id="verify_mock_interactions_sparingly">
+    Ưu tiên khẳng định dựa trên giá trị trả về và thay đổi trạng thái quan sát được hơn là kiểm tra số lần gọi hàm nội bộ (`toHaveBeenCalledTimes`), tránh việc gắn chặt test vào chi tiết triển khai ngầm.
+  </rule>
+</mocking_boundaries>
+
+---
+
+## 3. Vệ Sinh Fixture Kiểm Thử & Data Factory (Fixture Hygiene)
+
+<fixture_hygiene>
+  <rule id="data_factories_over_preseeded_db">
+    Sử dụng test factories (hoặc builder functions) rõ ràng với giá trị mặc định hợp lý thay vì phụ thuộc vào các file dump SQL seed tĩnh dùng chung dễ vỡ.
+  </rule>
+
+  <rule id="no_shared_mutable_fixtures">
+    Mỗi bài test bắt buộc phải tự khởi tạo dữ liệu của riêng mình. Tuyệt đối không chia sẻ trạng thái biến đổi hoặc biến test toàn cục giữa các bài test.
+  </rule>
+
+  <rule id="deterministic_teardown">
+    Luôn dọn sạch bản ghi database, tệp tạm thời hoặc đăng ký mock trong các hook `afterEach` / `teardown` để ngăn chặn lỗi dây chuyền sang các bài test khác.
+  </rule>
+</fixture_hygiene>
+
+---
+
+## 4. Tính Tiền Định & Không Chấp Nhận Test Chập Chờn (Determinism)
+
+<determinism>
+  <rule id="frozen_clock">
+    Tuyệt đối không sử dụng đồng hồ thực tế của hệ thống (`Date.now()`, `datetime.now()`) trong các khẳng định nhạy cảm về thời gian. Sử dụng frozen clock hoặc fake timer để đảm bảo kết quả tái lập tuyệt đối.
+  </rule>
+
+  <rule id="order_independence">
+    Các bài test bắt buộc phải chạy pass khi chạy riêng lẻ hoặc chạy theo thứ tự ngẫu nhiên (`--randomize`). Không bao giờ phụ thuộc vào việc bài test này phải chạy trước bài test kia.
+  </rule>
+
+  <rule id="no_arbitrary_sleeps">
+    Tuyệt đối không dùng lệnh chờ tùy tiện `sleep(1000)` trong test bất đồng bộ. Sử dụng helper kiểm tra định kỳ có timeout (`waitFor`, `eventually`) để hoàn thành ngay khi điều kiện kỳ vọng được thỏa mãn.
+  </rule>
+</determinism>
+
+---
+
+## 5. Độ Chính Xác Của Khẳng Định (Assertion Precision)
+
+<assertion_precision>
+  <rule id="exact_assertions">
+    Tránh các khẳng định mơ hồ (ví dụ: `expect(res).toBeTruthy()`). Luôn khẳng định cấu trúc giá trị chính xác, mã trạng thái HTTP và mã lỗi cụ thể.
+  </rule>
 
-  <policy name="Clean State (Trạng thái sạch)">
-    Mỗi bài test phải tự khởi tạo dữ liệu seed hoặc fixtures riêng của mình. Không bao giờ giả định sẵn có các dòng dữ liệu trong database.
-  </policy>
+  <rule id="actionable_failure_messages">
+    Khi viết assertion tùy biến, cung cấp thông báo lỗi rõ ràng chỉ ra dữ liệu đầu vào là gì và điều kiện bất biến nào đã bị vi phạm.
+  </rule>
+</assertion_precision>
 
-  <policy name="Assertion Precision (Độ chính xác của khẳng định)">
-    Tránh các khẳng định mơ hồ (ví dụ: `expect(res).toBeTruthy()`). Luôn khẳng định cấu trúc chính xác kỳ vọng, mã trạng thái HTTP (status code) và loại lỗi.
-  </policy>
+---
 
-  <policy name="Fast Feedback (Phản hồi nhanh)">
-    Toàn bộ bộ unit test phải hoàn thành trong vòng dưới 30 giây. Các bộ integration test chậm phải được phân vùng rõ ràng.
-  </policy>
-</test_policies>
+## 6. Ánh Xạ Lệnh Kiểm Tra (Verification Commands Mapping)
 
-## 3. Ánh Xạ Lệnh Kiểm Tra (Verification Commands Mapping)
 <verification_commands>
   <!-- Giữ đồng bộ với <validation_commands> trong AGENTS.md -->
-  <command type="unit">Chạy bộ kiểm thử unit test nhanh</command>
-  <command type="integration">Chạy kiểm thử tích hợp integration/e2e</command>
-  <command type="coverage">Chạy kiểm tra độ bao phủ test coverage</command>
+  <command type="unit">Chạy bộ kiểm thử unit test nhanh (< 30 giây toàn bộ)</command>
+  <command type="integration">Chạy kiểm thử tích hợp integration/e2e cách ly</command>
+  <command type="typecheck">Chạy kiểm tra kiểu tĩnh (0 lỗi, strict mode)</command>
+  <command type="lint">Chạy linter và kiểm tra format (0 cảnh báo)</command>
+  <command type="coverage">Chạy báo cáo độ bao phủ test coverage và ngưỡng tối thiểu</command>
 </verification_commands>
 
 </testing_context>

package/templates/vi/process/development-protocols/implementation-standards.md

@@ -1,28 +1,117 @@
-# Tiêu Chuẩn Triển Khai & Khung Kiểm Thử (Implementation Standards)
+# Tiêu Chuẩn Triển Khai & Khung Kỹ Thuật (Implementation Standards)
 
-<implementation_standards version="1.0">
+<implementation_standards version="2.0">
 
 <description>
-  Quy chuẩn chất lượng kỹ thuật, an toàn kiểu dữ liệu (type safety) và kiểm thử cho codebase này.
+  Quy chuẩn chất lượng kỹ thuật, an toàn kiểu dữ liệu, kiến trúc sạch và thực thi phòng thủ cho codebase. Dùng chung cho mọi dự án.
 </description>
 
-## 1. An Toàn Kiểu Dữ Liệu & Vệ Sinh Code (Type Safety & Code Hygiene)
-<conventions>
+---
+
+## 1. An Toàn Kiểu Dữ Liệu & Phân Tích Tĩnh (Type Safety & Static Analysis)
+
+<type_safety>
   <rule id="strict_typing">
-    Toàn bộ các hàm, phương thức và thuộc tính class bắt buộc phải có chú thích kiểu dữ liệu (type annotations) rõ ràng. Sử dụng union types hiện đại (`int | None` hoặc `string | null`) và tránh dùng `Any`/`any` không định kiểu trừ khi giao tiếp với payload bên ngoài thô.
+    Toàn bộ các hàm, phương thức và thuộc tính class bắt buộc phải có chú thích kiểu dữ liệu (type annotations) rõ ràng. Sử dụng union types hiện đại (`int | None` hoặc `string | null`). Tránh dùng `Any`/`any` không định kiểu trừ khi giải mã dữ liệu đầu vào thô chưa xác thực tại cổng biên.
+  </rule>
+
+  <rule id="explicit_return_types">
+    Luôn khai báo kiểu trả về tường minh cho các hàm và phương thức public để áp đặt hợp đồng lúc biên dịch (compile-time) và ngăn ngừa hiện tượng suy luận kiểu bị mở rộng vô ý.
+  </rule>
+
+  <rule id="no_suppression">
+    Tuyệt đối không tắt lỗi linter, formatter hoặc type-checker bằng comment bỏ qua nội dòng (`# type: ignore`, `eslint-disable`, `@SuppressWarnings`) để vượt qua cổng kiểm tra giả tạo. Phải xử lý triệt để nguyên nhân gốc rễ.
   </rule>
+</type_safety>
+
+---
+
+## 2. Kiến Trúc Sạch & Độ Thuần Khiết Domain (Clean Architecture & Domain Purity)
+
+<clean_architecture>
+  <rule id="dependency_rule">
+    Chiều phụ thuộc (dependency) chỉ được phép hướng vào lõi Domain bên trong. Các tầng domain bên trong tuyệt đối không import hay phụ thuộc vào framework hạ tầng, database hoặc UI bên ngoài.
+  </rule>
+
   <rule id="domain_purity">
-    Mã nguồn trong các tầng domain phải thuần khiết với 0 phụ thuộc vào hạ tầng bên ngoài (zero external infrastructure dependencies).
+    Logic nghiệp vụ cốt lõi, thực thể domain và value objects phải thuần khiết 100% với 0 tác dụng phụ (zero side-effects), không thực hiện I/O tệp hệ thống và không gọi mạng.
   </rule>
-  <rule id="immutability">
-    Ưu tiên các mô hình bất biến (immutable models) cho các sự kiện domain (domain events), value objects và DTOs.
+
+  <rule id="ports_and_adapters">
+    Định nghĩa giao diện trừu tượng (ports) trong tầng application/domain cho lưu trữ dữ liệu, API bên ngoài và nhắn tin. Triển khai các driver cụ thể (adapters) độc quyền trong các package hạ tầng (infrastructure).
+  </rule>
+
+  <rule id="no_premature_abstraction">
+    Không tự ý đưa vào các lớp trừu tượng mang tính suy diễn, dynamic factory hoặc lớp trung gian bắc cầu không cần thiết cho các tiện ích đơn chức năng đơn giản.
+  </rule>
+</clean_architecture>
+
+---
+
+## 3. Xử Lý Lỗi & Nguyên Tắc Thất Bại Sớm (Error Handling & Fail-Fast)
+
+<error_handling>
+  <rule id="fail_fast_at_boundaries">
+    Kiểm tra hợp lệ toàn bộ tham số, payload và biến môi trường ngay tại điểm vào của hệ thống. Từ chối dữ liệu sai lệch ngay lập tức trước khi gọi vào logic nghiệp vụ.
+  </rule>
+
+  <rule id="no_silent_swallowing">
+    Tuyệt đối không sử dụng `catch {}` rỗng, `except: pass` hoặc bắt ngoại lệ mà không ghi log. Mọi ngoại lệ bị bắt phải được xử lý, chuyển đổi thành lỗi domain có định kiểu hoặc lan truyền (propagate) sạch sẽ.
+  </rule>
+
+  <rule id="typed_domain_errors">
+    Tạo các class lỗi domain rõ ràng kèm mã lỗi đọc được bằng máy (ví dụ: `ResourceNotFoundError`, `ValidationError`, `ConcurrencyConflictError`) thay vì ném ra các exception chung chung.
   </rule>
-</conventions>
+</error_handling>
 
-## 2. Kiến Trúc Kiểm Thử (Test Architecture)
-<test_structure>
-  - `tests/unit/`: Các bài test nhanh, cách ly cho domain models, logic cốt lõi và mock adapters.
-  - `tests/integration/`: Các bài test luồng đầu-cuối với dịch vụ kiểm thử hoặc database nội bộ.
-</test_structure>
+---
+
+## 4. Bất Biến & An Toàn Khi Chạy Đồng Thời (Immutability & Concurrency Safety)
+
+<concurrency_and_immutability>
+  <rule id="immutable_data_structures">
+    Ưu tiên các cấu trúc dữ liệu bất biến (`dataclass(frozen=True)`, `readonly` interface, hoặc `Readonly<T>`) cho các sự kiện domain, cấu hình và DTO.
+  </rule>
+
+  <rule id="no_shared_mutable_state">
+    Tránh sử dụng biến toàn cục có thể thay đổi (mutable globals), cache trạng thái cấp module hoặc singleton có trường biến đổi. Truyền dependency rõ ràng thông qua hàm khởi tạo (Dependency Injection).
+  </rule>
+
+  <rule id="safe_async_lifecycle">
+    Luôn xử lý dọn dẹp và từ chối lỗi bất đồng bộ (async error rejection/cancellation) cẩn thận. Thiết lập timeout rõ ràng cho mọi lệnh gọi mạng hoặc truy vấn cơ sở dữ liệu.
+  </rule>
+</concurrency_and_immutability>
+
+---
+
+## 5. Giám Sát & Vệ Sinh Ghi Log (Observability & Logging Hygiene)
+
+<observability_hygiene>
+  <rule id="structured_logging">
+    Sử dụng ghi log có cấu trúc (structured logging) kèm ngữ cảnh dạng key-value (`task_id`, `user_id`, `component`) thay vì nối chuỗi văn bản thuần túy.
+  </rule>
+
+  <rule id="no_credential_leakage">
+    Không bao giờ ghi log dữ liệu nhạy cảm: mật khẩu, tokens, API keys, cookies hoặc thông tin nhận dạng cá nhân (PII).
+  </rule>
+
+  <rule id="clean_production_diff">
+    Xóa sạch toàn bộ debug log tạm thời (`console.log`, `print()`, `debugger`, `dump()`) trước khi đề nghị ký duyệt Gate G3.
+  </rule>
+</observability_hygiene>
+
+---
+
+## 6. Quản Lý Tài Nguyên Phòng Thủ & Dọn Dẹp (Resource Management & Teardown)
+
+<resource_management>
+  <rule id="deterministic_teardown">
+    Luôn quản lý con trỏ tệp (file handles), kết nối mạng socket và transaction database bằng các cấu trúc giải phóng tiền định (`try...finally`, Python `with`, TypeScript `using`, hoặc RAII nguyên bản của ngôn ngữ).
+  </rule>
+
+  <rule id="isolated_test_state">
+    Mỗi fixture kiểm thử phải tự tạo và tự dọn sạch trạng thái tạm thời của mình. Không để sót lại dữ liệu rác sau khi chạy xong test.
+  </rule>
+</resource_management>
 
 </implementation_standards>