@damphuquy/agent-init 1.4.4 → 2.0.0

package/templates/en/process/development-protocols/orchestration.md

@@ -1,24 +1,101 @@
 # Subagent Delegation & Orchestration Protocol
 
-<orchestration_protocol version="1.0">
+<orchestration_protocol version="2.0">
 
 <description>
-  Guidelines for delegating, isolating, and coordinating subagents during complex tasks.
+  Engineering guidelines for delegating, isolating, and coordinating subagents during complex, multi-phase tasks. Project-agnostic.
 </description>
 
-## 1. Delegation Principles
-<delegation_rules>
-  <rule id="explicit_scope">
-    Always specify exact files, function signatures, and expected structured output formats.
+---
+
+## 1. Delegation Criteria & Workload Triage
+
+<delegation_criteria>
+  Subagents should be spawned deliberately for bounded, high-leverage subtasks. Do NOT spawn subagents for trivial steps.
+
+  ### When to Delegate to a Subagent:
+  - **Isolated Research Spikes:** Exploring unfamiliar libraries, auditing legacy subsystems, or reading documentation without polluting the parent agent's context window.
+  - **Dedicated Quality Audits:** Independent security vulnerability audits, accessibility reviews (a11y), or strict lint/formatting passes.
+  - **Orthogonal Test Authoring:** Writing standalone unit test fixtures or integration harnesses for a frozen interface contract.
+  - **Parallel Independent Slices:** Implementing non-overlapping, orthogonal components that touch distinct file boundaries.
+
+  ### When Parent Agent MUST Retain Control (Do NOT Delegate):
+  - **Architectural Trade-offs & Decisions:** Authoring `decision.md` options and Gate 1 sign-offs.
+  - **Master Task Contract & Planning:** Defining `task.md`, vertical slice contracts in `plan.md`, and Gate 2 sign-offs.
+  - **Quality Gates & User Approval:** Conducting Gate G3 review sign-off and final `handoff.md` generation.
+  - **Interactive User Clarification:** Any prompt requiring direct user guidance or requirement resolution.
+</delegation_criteria>
+
+---
+
+## 2. Context Containment & Scoping Rules
+
+<context_containment>
+  <rule id="explicit_file_manifest">
+    Always provide the subagent with an explicit list of file paths to inspect or modify. Never prompt a subagent with open-ended instructions like "explore the project" or "look around the codebase".
+  </rule>
+
+  <rule id="port_and_interface_focus">
+    Constrain the subagent's inputs to relevant port interfaces, domain entities, and accompanying test suites. Keep infrastructure noise out of the subagent prompt.
+  </rule>
+
+  <rule id="structured_output_contract">
+    Always demand a structured output format from the subagent (e.g. unified diff, bulleted findings categorized by Confirmed/Observed/Hypothesized, or JSON/markdown table).
+  </rule>
+</context_containment>
+
+---
+
+## 3. Concurrency, Isolation & Write Permissions
+
+<concurrency_and_isolation>
+  <rule id="zero_write_collision">
+    Multiple subagents must NEVER be given write access to the same files or shared mutable database tables concurrently. Overlapping writes cause silent regressions and merge conflicts.
+  </rule>
+
+  <rule id="read_only_by_default">
+    Default subagents to read-only mode whenever possible (e.g. research, code exploration, audit). Only grant write permissions when the target files are strictly isolated to that subagent.
+  </rule>
+
+  <rule id="workspace_isolation">
+    If subagents support isolated workspaces (e.g. branch or worktree mode), use them for speculative spike experiments to ensure the parent working tree remains clean.
+  </rule>
+</concurrency_and_isolation>
+
+---
+
+## 4. State Synchronization & Parent Re-Integration
+
+<state_synchronization>
+  <rule id="parent_owns_master_state">
+    Subagents must NEVER directly edit the parent's master task artifacts (`task.md`, `state.md`, `review.md`). Only the parent agent reconciles subagent outputs into master state files.
+  </rule>
+
+  <rule id="verification_before_acceptance">
+    When a subagent returns modified source code or findings, the parent agent must inspect the diff and execute the slice's designated verifier command before accepting the work.
+  </rule>
+
+  <rule id="evidence_crystallization">
+    Extract verified facts from subagent reports and append them to `state.md > <verification_evidence>`. Discard transient subagent conversation logs to preserve context hygiene.
+  </rule>
+</state_synchronization>
+
+---
+
+## 5. Reactive Coordination, Timeouts & Failure Recovery
+
+<coordination_and_recovery>
+  <rule id="no_polling_loops">
+    Never implement sleep-and-poll loops (`while true; sleep 5; check_status`) to monitor subagents. Rely on the system's reactive message wakeup mechanism to resume execution upon subagent completion.
   </rule>
 
-  <rule id="context_containment">
-    Do not grant unbounded repo access; constrain subagent context to relevant test suites and port contracts.
+  <rule id="retry_budget_enforcement">
+    If a subagent encounters a tool error or recurring failure, enforce the 3-attempt retry budget. If exhausted, record the failure signature in `state.md > <failure_memory>` and escalate to human guidance.
   </rule>
 
-  <rule id="no_polling">
-    Rely on the system's reactive message wakeup mechanism when subagents complete their execution.
+  <rule id="teardown_and_cleanup">
+    Terminate idle or failed subagents cleanly. Ensure any temporary scratch files or experiment branches created by the subagent are deleted before completing the slice.
   </rule>
-</delegation_rules>
+</coordination_and_recovery>
 
 </orchestration_protocol>

package/templates/vi/process/README.md

@@ -24,6 +24,7 @@ process/
 │   ├── 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
+│   ├── pause-template.md.seed        # Biên bản tạm dừng task & đóng băng an toàn
 │   ├── 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
@@ -45,6 +46,7 @@ process/
 │   │       ├── 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
+│   │       ├── paused.md             # (Nếu tạm dừng) Biên bản đóng băng & điều kiện mở lại
 │   │       └── 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
@@ -107,8 +109,10 @@ handoff.md       ← (Complete) Tóm tắt bàn giao 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` |
+| Tạm dừng / Đóng băng | `paused.md` (đóng băng sạch sẽ & checklist mở lại khi bị chặn) |
 | 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` |
 | Gate 2 | Phê duyệt trong `plan.md` |
 | Gate 3 | Phê duyệt trong `review.md` |

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

@@ -121,6 +121,10 @@ 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` |
+| 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` |
 | Gate 2 | Phê duyệt trong `plan.md` |
 | Gate 3 | Phê duyệt trong `review.md` |

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

@@ -6,9 +6,11 @@
      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 -->
+  <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>  <!-- MANUAL | PAIR | DELEGATED | DIAGNOSE-ONLY -->
   <current_phase>RESEARCH</current_phase>  <!-- RESEARCH | INNOVATE | PLAN | EXECUTE | REVIEW -->
   <owner>@engineer</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>
@@ -154,6 +161,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">

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>