@damphuquy/agent-init 1.4.3 → 2.0.0

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

@@ -1,28 +1,117 @@
 # Implementation & Harness Standards
 
-<implementation_standards version="1.0">
+<implementation_standards version="2.0">
 
 <description>
-  Engineering quality, type safety, and testing conventions for this codebase.
+  Engineering quality, strict typing, clean architecture, and defensive execution conventions. Project-agnostic.
 </description>
 
-## 1. Type Safety & Code Hygiene
-<conventions>
+---
+
+## 1. Type Safety & Static Analysis
+
+<type_safety>
   <rule id="strict_typing">
-    All functions, methods, and class attributes must have explicit type annotations. Use modern union types (`int | None` or `string | null`) and avoid untyped `Any`/`any` unless interfacing with raw external payloads.
+    All functions, methods, and class attributes must have explicit type annotations. Use modern union types (`int | None` or `string | null`). Avoid untyped `Any`/`any` unless deserializing unvalidated external payloads at boundary gateways.
+  </rule>
+
+  <rule id="explicit_return_types">
+    Always declare explicit return types on public functions and methods to enforce compile-time contracts and prevent accidental type widening.
+  </rule>
+
+  <rule id="no_suppression">
+    Never silence linter, formatter, or type-checker errors with inline suppression directives (`# type: ignore`, `eslint-disable`, `@SuppressWarnings`) to artificially pass a validation gate. Fix the underlying root cause.
   </rule>
+</type_safety>
+
+---
+
+## 2. Clean Architecture & Layered Domain Purity
+
+<clean_architecture>
+  <rule id="dependency_rule">
+    Dependencies must only point inward toward the core domain. Inner domain layers must never import or depend on outer infrastructure frameworks, databases, or UI modules.
+  </rule>
+
   <rule id="domain_purity">
-    Code in domain layers must remain pure with zero external infrastructure dependencies.
+    Core business logic, domain entities, and value objects must remain 100% pure with zero side-effects, zero filesystem I/O, and zero network calls.
   </rule>
-  <rule id="immutability">
-    Prefer immutable models for domain events, value objects, and DTOs.
+
+  <rule id="ports_and_adapters">
+    Define abstract interfaces (ports) in the application/domain layer for persistence, external APIs, and messaging. Implement concrete drivers (adapters) strictly within infrastructure packages.
+  </rule>
+
+  <rule id="no_premature_abstraction">
+    Do not introduce speculative abstraction layers, dynamic factories, or unnecessary indirection for simple single-purpose utilities.
+  </rule>
+</clean_architecture>
+
+---
+
+## 3. Error Handling & Fail-Fast Principles
+
+<error_handling>
+  <rule id="fail_fast_at_boundaries">
+    Validate all incoming parameters, payloads, and environment variables at system entrypoints. Reject malformed input immediately before invoking business logic.
+  </rule>
+
+  <rule id="no_silent_swallowing">
+    Never use empty `catch {}`, `except: pass`, or unlogged exception handlers. Every caught exception must either be handled, transformed into a typed domain error, or cleanly propagated.
+  </rule>
+
+  <rule id="typed_domain_errors">
+    Create explicit domain error classes with machine-readable error codes (e.g. `ResourceNotFoundError`, `ValidationError`, `ConcurrencyConflictError`) rather than throwing generic exceptions.
   </rule>
-</conventions>
+</error_handling>
 
-## 2. Test Architecture
-<test_structure>
-  - `tests/unit/`: Fast, isolated tests for domain models, core logic, and mock adapters.
-  - `tests/integration/`: End-to-end flow tests with test services or local databases.
-</test_structure>
+---
+
+## 4. Immutability & Concurrency Safety
+
+<concurrency_and_immutability>
+  <rule id="immutable_data_structures">
+    Prefer immutable models (`dataclass(frozen=True)`, `readonly` interfaces, or `Readonly<T>`) for domain events, configuration objects, and Data Transfer Objects (DTOs).
+  </rule>
+
+  <rule id="no_shared_mutable_state">
+    Avoid global mutable variables, module-level state caches, or singletons with mutable fields. Pass dependencies explicitly via constructors (Dependency Injection).
+  </rule>
+
+  <rule id="safe_async_lifecycle">
+    Always handle asynchronous error rejection and cancellation cleanly. Ensure timeouts are specified for external network calls and database queries.
+  </rule>
+</concurrency_and_immutability>
+
+---
+
+## 5. Observability & Logging Hygiene
+
+<observability_hygiene>
+  <rule id="structured_logging">
+    Use structured logging with key-value context (`task_id`, `user_id`, `component`) instead of unstructured string concatenation.
+  </rule>
+
+  <rule id="no_credential_leakage">
+    Never log sensitive data: passwords, tokens, API keys, cookies, or personally identifiable information (PII).
+  </rule>
+
+  <rule id="clean_production_diff">
+    Remove all temporary debug logs (`console.log`, `print()`, `debugger`, `dump()`) before requesting Gate G3 sign-off.
+  </rule>
+</observability_hygiene>
+
+---
+
+## 6. Defensive Resource Management & Teardown
+
+<resource_management>
+  <rule id="deterministic_teardown">
+    Always manage file handles, network sockets, and database transactions using deterministic scoping constructs (`try...finally`, Python `with`, TypeScript `using`, or language-native RAII).
+  </rule>
+
+  <rule id="isolated_test_state">
+    Test fixtures must create and destroy their own temporary state. Tests must leave the system in a clean state upon completion.
+  </rule>
+</resource_management>
 
 </implementation_standards>

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

@@ -81,6 +81,11 @@
     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="pause" path="pause-template.md.seed">
+    Biên bản tạm dừng task. Bảo toàn trạng thái cây làm việc git, ảnh chụp các slice đã xong,
+    điều kiện kích hoạt lại và đánh giá nguy cơ lỗi thời khi task bị đóng băng tạm thời.
+  </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.
@@ -116,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` |
@@ -135,6 +144,7 @@ process/features/active/CHG-017-your-feature/
 ├── 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)
+├── paused.md        ← (Nếu tạm dừng) khởi tạo từ pause-template.md.seed
 └── cancelled.md     ← (Nếu hủy task) khởi tạo từ cancellation-template.md.seed
 ```
 
@@ -170,6 +180,9 @@ cp process/_seeds/handoff-template.md.seed process/features/active/CHG-XXX-your-
 # (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 tạm dừng hoặc đóng băng task đang làm):
+cp process/_seeds/pause-template.md.seed process/features/active/CHG-XXX-your-feature/paused.md
+
 # (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
 ```

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

@@ -0,0 +1,106 @@
+# Biên Bản Tạm Dừng Task: [TASK-ID] [Tiêu Đề Task]
+
+<pause_record task_id="[TASK-ID]" version="1.0" framework="RIPER-5">
+
+<!--
+  HƯỚNG DẪN TẠM DỪNG & ĐÓNG BĂNG TASK (TASK PAUSE):
+  - Mục đích: Đóng băng sạch sẽ task đang thực thi khi gặp blocker bên ngoài, thay đổi độ ưu tiên, hoặc chờ phản hồi từ con người.
+  - Tuyệt đối không bỏ dở task mà không lưu vết chính xác trạng thái git và điều kiện kích hoạt lại.
+  - Khởi tạo file này thành `paused.md` bên trong thư mục task đang làm.
+  - Nếu tạm dừng dài hạn (> 2 tuần), chuyển thư mục task từ `active/` sang `backlog/` (hoặc `paused/`) để giữ `active/` luôn sạch.
+-->
+
+<status>
+  <phase_at_pause>[RESEARCH | INNOVATE | PLAN | EXECUTE | REVIEW]</phase_at_pause>
+  <paused_date>[YYYY-MM-DD hoặc DD-MM-YY]</paused_date>
+  <paused_by>[@engineer_hoac_tech_lead]</paused_by>
+  <git_branch>[feature/CHG-XXX-mo-ta]</git_branch>
+  <git_state>[COMMITTED_WIP | STASHED | CLEAN]</git_state>
+  <git_commit_or_stash_ref>[ví dụ: commit hash a1b2c3d hoặc stash@{0}]</git_commit_or_stash_ref>
+</status>
+
+---
+
+## 1. Lý Do Tạm Dừng & Yếu Tố Chặn (Blockers)
+
+<pause_context>
+  <primary_reason>
+    <!-- [ví dụ: Bị chặn bởi API Task CHG-042 / Chờ review bảo mật / Ưu tiên khẩn cấp cho hotfix P0 / Chờ feedback sản phẩm] -->
+    [Tóm tắt ngắn gọn lý do tại sao task này phải tạm dừng.]
+  </primary_reason>
+
+  <blocker_details>
+    [Ngữ cảnh chi tiết về điều kiện chặn, ticket bên ngoài hoặc sự phụ thuộc kiến trúc.]
+  </blocker_details>
+</pause_context>
+
+---
+
+## 2. Tiến Độ Đang Làm & Snapshot Lát Cắt (Slice)
+
+<progress_snapshot>
+  <completed_slices>
+    <!-- Những slice nào trong plan.md đã vượt qua verifier thành công? -->
+    - [Slice 1: Mục tiêu — ĐÃ KIỂM THỬ XANH & COMMIT]
+  </completed_slices>
+
+  <active_slice_at_pause>
+    <!-- Slice nào đang dang dở khi dừng? -->
+    <slice_id>[ví dụ: Slice 2]</slice_id>
+    <state_summary>[ví dụ: Đã viết xong logic service, đang viết 2 unit test nhưng còn lỗi mock]</state_summary>
+  </active_slice_at_pause>
+
+  <touched_files>
+    <!-- Danh sách file đã sửa hoặc tạo mới trong quá trình thực thi -->
+    - `src/...`
+    - `tests/...`
+  </touched_files>
+</progress_snapshot>
+
+---
+
+## 3. Điều Kiện Kích Hoạt Lại (Resumption Criteria)
+
+<resumption_criteria>
+  <!-- Sự kiện, ticket hay điều kiện cụ thể nào sẽ mở khóa để tiếp tục task này? -->
+  <trigger_condition>
+    [ví dụ: CHG-042 được merge vào main và deploy lên môi trường staging]
+  </trigger_condition>
+
+  <responsible_owner>[@ky_su_phu_trach]</responsible_owner>
+</resumption_criteria>
+
+---
+
+## 4. Đánh Giá Nguy Cơ Lỗi Thời (Stale-Risk & Bit-Rot)
+
+<stale_risk_assessment>
+  <!-- Những gì có nguy cơ biến đổi hoặc xung đột nếu task bị đóng băng nhiều tuần/tháng? -->
+  <schema_drift_risk level="[LOW|MEDIUM|HIGH]">
+    [Nguy cơ database migration hoặc schema API thay đổi song song trên main.]
+  </schema_drift_risk>
+
+  <dependency_drift_risk level="[LOW|MEDIUM|HIGH]">
+    [Nguy cơ thư viện phụ thuộc hoặc module dùng chung được nâng cấp phiên bản.]
+  </dependency_drift_risk>
+
+  <architecture_drift_risk level="[LOW|MEDIUM|HIGH]">
+    [Nguy cơ quy chuẩn hoặc tái cấu trúc làm vô hiệu các giả thuyết trong research.md.]
+  </architecture_drift_risk>
+</stale_risk_assessment>
+
+---
+
+## 5. Checklist Kiểm Tra Trước Khi Khởi Động Lại (Pre-Flight Resumption)
+
+<resumption_checklist>
+  <!-- BẮT BUỘC thực hiện tuần tự trước khi mở lại vòng lặp EXECUTE -->
+  - [ ] 1. Chuyển thư mục task trở lại `active/` (nếu trước đó đã cất vào `backlog/`).
+  - [ ] 2. Checkout đúng branch và rebase/merge code mới nhất từ `main` (`git checkout <branch> && git pull --rebase origin main`).
+  - [ ] 3. Chạy lệnh kiểm thử gốc (`npm run test && npm run lint`) để đảm bảo codebase đang hoàn toàn xanh.
+  - [ ] 4. Kiểm tra độ tươi ngữ cảnh (Context Freshness): Đọc lại `task.md`, `state.md`, và xác nhận các giả thuyết trong `research.md` còn đúng không.
+  - [ ] 5. Nếu `<allowed_files>` bị thay đổi trên `main`, cập nhật lại phạm vi trong `plan.md`.
+  - [ ] 6. Xóa hoặc lưu trữ `paused.md`, cập nhật lại `state.md` và tiếp tục thực hiện slice đang dở.
+</resumption_checklist>
+
+</pause_record>

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>