@damphuquy/agent-init 1.4.4 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # agent-instructions (@damphuquy/agent-init)
 
-> **AI Coding Agent Scaffolding & Orchestration System (RIPER-5 Framework)**
+> **AI Coding Agent Scaffolding & Orchestration System v2.0 (RIPER-5 Framework)**
 
 <p align="center">
   <b>English</b> • <a href="README.vi.md">Tiếng Việt</a>
@@ -8,7 +8,13 @@
 
 ---
 
-A structured scaffolding framework for AI Coding Agents following the **RIPER-5 Framework** — cleanly separated into three layers: `AGENTS.md` (project configuration), `.agents/` (agent behavioral controls), and `process/` (task execution and verification workflow).
+A structured scaffolding framework for AI Coding Agents following the **RIPER-5 Framework v2.0** — cleanly separated into three layers: `AGENTS.md` (project configuration), `.agents/` (agent behavioral controls), and `process/` (task execution and verification workflow).
+
+Featuring four core **v2.0 Engineering Protocols**:
+* **Subagent Orchestration v2.0:** Parallel vertical slicing with zero write collision and reactive wakeup.
+* **Implementation Standards v2.0:** Strict typing (zero `any`), domain purity, fail-fast boundary validation, and deterministic teardown.
+* **Planning & Slicing Standards v2.0:** INVEST-compliant vertical slices (2–5 per task) with mandatory automated verifiers.
+* **Testing Standards & Harness v2.0:** Deterministic test pyramid with frozen clocks, fixture factories, and strict mocking boundaries.
 
 ```bash
 # Bootstrap immediately into your project (takes 30 seconds)
@@ -23,11 +29,11 @@ Designed for minimal overhead, practical focus, and zero fluff:
 
 ### 1. For Daily Development (Start Here)
 * **[01 · Hands-on Walkthrough from A–Z](docs/en/01-getting-started.md)**: **The core guide to get started in 10–15 minutes**. Step-by-step instructions with **2 practical examples** (Task 1 Strict Track $\rightarrow$ Handoff $\rightarrow$ Task 2 Fast-Track with knowledge inheritance), prompt templates, and quality gate sign-offs.
-* **[02 · Daily Cheat Sheet](docs/en/02-cheat-sheet.md)**: Copy-paste prompt templates for each phase, quality gates summary (Gates G0–G3), and file ownership matrix (Human vs Agent).
+* **[02 · Daily Cheat Sheet](docs/en/02-cheat-sheet.md)**: Copy-paste prompt templates for each phase, quality gates summary (Gates G0–G3), subagent delegation prompts, and v2.0 protocol matrix.
 * **[03 · Advanced Workflows & Production Edge Cases](docs/en/03-advanced-workflows.md)**: Complex real-world scenarios: Epics in `process/features/`, multi-developer concurrency, git rebase conflicts, P0 emergency hotfixes, secret scanning, model switching, complex test harnesses, and task parking (`paused.md`).
 
 ### 2. In-Depth Reference (For Tech Leads & Maintainers)
-* **[3-Layer Architecture & Context Router](docs/en/reference/architecture.md)**: Deep dive into the 3-layer decoupled architecture and Minimum Sufficient Context principles (No Full-Repo Scan).
+* **[3-Layer Architecture & Context Router (v2.0)](docs/en/reference/architecture.md)**: Deep dive into the 3-layer decoupled architecture, the 11-seed catalog, and the v2.0 Engineering Protocols.
 * **[DevOps & Release Automation](docs/en/reference/devops-release.md)**: CI/CD release lifecycle, automated Semantic Versioning, and NPM package publishing.
 
 ---

package/README.vi.md

@@ -1,6 +1,6 @@
 # agent-instructions (@damphuquy/agent-init)
 
-> **Hệ thống điều phối và khởi tạo AI Coding Agent theo chuẩn RIPER-5**
+> **Hệ thống điều phối và khởi tạo AI Coding Agent v2.0 theo chuẩn RIPER-5**
 
 <p align="center">
   <a href="README.md">English</a> • <b>Tiếng Việt</b>
@@ -8,7 +8,13 @@
 
 ---
 
-Hệ thống mẫu (scaffold) điều phối AI Coding Agent theo chuẩn **RIPER-5 Framework** — phân tách thành ba layer rõ ràng: `AGENTS.md` (cấu hình dự án), `.agents/` (quy chuẩn hành vi của Agent), và `process/` (quy trình thực thi task và kiểm thử).
+Hệ thống mẫu (scaffold) điều phối AI Coding Agent theo chuẩn **RIPER-5 Framework v2.0** — phân tách thành ba layer rõ ràng: `AGENTS.md` (cấu hình dự án), `.agents/` (quy chuẩn hành vi của Agent), và `process/` (quy trình thực thi task và kiểm thử).
+
+Tích hợp 4 **Giao thức Kỹ thuật v2.0** cốt lõi:
+* **Điều phối Subagent v2.0:** Chia lát cắt song song, không xung đột ghi (zero write collision) và đánh thức phản ứng.
+* **Quy chuẩn Hiện thực Mã nguồn v2.0:** Kiểm soát kiểu nghiêm ngặt (không `any`), domain thuần khiết, fail-fast tại ranh giới và dọn dẹp tài nguyên xác định.
+* **Quy chuẩn Lập kế hoạch & Cắt lát v2.0:** Lát cắt dọc theo chuẩn INVEST (2–5 slice/task) với lệnh kiểm chứng tự động bắt buộc.
+* **Quy chuẩn Kiểm thử & Test Harness v2.0:** Kim tự tháp kiểm thử xác định với đóng băng thời gian (frozen clocks), fixture factories và mock có kiểm soát.
 
 ```bash
 # Khởi tạo ngay vào project của bạn (chỉ mất 30 giây)
@@ -23,11 +29,11 @@ Tài liệu được thiết kế tối giản, tập trung vào thực hành, k
 
 ### 1. Dành cho công việc hằng ngày (Bắt đầu tại đây)
 * 📘 **[01 · Hướng dẫn Thực chiến từ A–Z](docs/vi/01-getting-started.md)**: **Tài liệu cốt lõi để bắt đầu trong 10–15 phút**. Hướng dẫn từng bước với **2 ví dụ thực tế liên hoàn** (Task 1 Strict Track $\rightarrow$ Bàn giao $\rightarrow$ Task 2 Fast-Track kế thừa tri thức), prompt mẫu và cách duyệt qua các cổng.
-* ⚡ **[02 · Sổ tay Tra cứu Nhanh (Cheat Sheet)](docs/vi/02-cheat-sheet.md)**: Bảng copy-paste prompt mẫu cho từng giai đoạn, bảng 4 cổng kiểm soát (Gates G0–G3), và ma trận quyền hạn file (Human vs Agent).
+* ⚡ **[02 · Sổ tay Tra cứu Nhanh (Cheat Sheet)](docs/vi/02-cheat-sheet.md)**: Bảng copy-paste prompt mẫu cho từng giai đoạn, bảng 4 cổng kiểm soát (Gates G0–G3), prompt ủy quyền subagent và ma trận giao thức v2.0.
 * 🚀 **[03 · Quy trình Nâng cao & Tình huống Thực chiến](docs/vi/03-advanced-workflows.md)**: Các kịch bản production phức tạp: Epic trong `process/features/`, đa lập trình viên đồng thời, xử lý xung đột rebase, hotfix P0 khẩn cấp, quét secret bảo mật, đổi model chat, và đóng băng task dài hạn (`paused.md`).
 
 ### 2. Tài liệu Chuyên sâu & Tham khảo (Dành cho Lead / Maintainer)
-* 🏛️ **[Kiến trúc 3 Tầng & Cơ chế Context Router](docs/vi/reference/architecture.md)**: Giải thích sâu về thiết kế tách rời 3 layer và cơ chế nạp ngữ cảnh tối thiểu (No Full-Repo Scan).
+* 🏛️ **[Kiến trúc 3 Tầng & Cơ chế Context Router (v2.0)](docs/vi/reference/architecture.md)**: Giải thích sâu về thiết kế tách rời 3 layer, danh mục 11 seed template và 4 Giao thức Kỹ thuật v2.0.
 * 🚢 **[Cẩm nang DevOps & Tự động hóa Phát hành](docs/vi/reference/devops-release.md)**: Quy trình CI/CD tự động tính Semantic Versioning và publish package lên NPM.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@damphuquy/agent-init",
-  "version": "1.4.4",
+  "version": "2.0.0",
   "description": "Scaffolding CLI to bootstrap RIPER-5 Coding Agents & Operational Workspace",
   "type": "module",
   "main": "./dist/index.js",

package/templates/en/process/README.md

@@ -24,6 +24,7 @@ process/
 │   ├── review-template.md.seed       # Review phase artifact (Gate 3)
 │   ├── handoff-template.md.seed      # Final projection (short)
 │   ├── cancellation-template.md.seed # Knowledge-preserving cancellation record
+│   ├── pause-template.md.seed        # Task pause & parking record (temporary blockages)
 │   ├── results-template.tsv.seed     # Benchmark & quantitative metrics tracker
 │   └── program-template.md.seed      # Multi-phase program blueprint
 ├── context/                          # Durable knowledge base & context routers
@@ -45,6 +46,7 @@ process/
 │   │       ├── review.md             # Review phase output
 │   │       ├── handoff.md            # Final projection
 │   │       ├── results.tsv           # (Optional) Benchmark & metric iteration tracking
+│   │       ├── paused.md             # (If paused) Parking record & resumption criteria
 │   │       └── cancelled.md          # (If aborted) Cancellation findings & rollback status
 │   ├── completed/                    # Archived task workspaces
 │   └── backlog/                      # Backlog notes: {note_slug}_NOTE_{dd-mm-yy}.md
@@ -107,8 +109,10 @@ handoff.md       ← (Complete) Short final projection
 | Execute | source code + tests + `state.md` |
 | Review | `review.md` |
 | Handoff | `handoff.md` |
+| Pause / Park | `paused.md` (clean freeze & resumption criteria upon temporary block) |
 | Cancellation | `cancelled.md` (knowledge preservation upon abort) |
 | Benchmark / Metrics | `results.tsv` (performance and eval metrics) |
+| Program | `program.md` (multi-phase umbrella epic blueprint) |
 | Gate 1 | `decision.md` approval |
 | Gate 2 | `plan.md` approval |
 | Gate 3 | `review.md` approval |

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

@@ -121,6 +121,10 @@ handoff.md      ← Final projection (short)
 | Execute | source code + tests + `state.md` |
 | Review | `review.md` |
 | Handoff | `handoff.md` |
+| Pause / Park | `paused.md` (clean freeze & resumption checklist) |
+| Cancellation | `cancelled.md` (knowledge preservation upon abort) |
+| Benchmark / Metrics | `results.tsv` (performance and eval metrics) |
+| Program | `program.md` (multi-phase umbrella epic blueprint) |
 | Gate 1 | `decision.md` approval |
 | Gate 2 | `plan.md` approval |
 | Gate 3 | `review.md` approval |

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

@@ -6,9 +6,11 @@
      SECTION 0 — TASK CONTROL (master state record)
      ════════════════════════════════════════════ -->
 <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=sketch | S1=defined | S2=verified | S3=locked -->
+  <priority>P2</priority>  <!-- P0=urgent | P1=high | P2=normal | P3=low -->
   <risk>MEDIUM</risk>  <!-- LOW | MEDIUM | HIGH -->
+  <estimated_story_points>2</estimated_story_points>  <!-- 1 SP ≈ 2-4 focused engineering hours -->
   <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/[path/to/test_file]` — [Target assertions and test fixtures]
   </target_files>
 
+  <context_groups>
+    <!-- References to registered context groups from process/context/all-context.md -->
+    - [planning | tests | protocols | domain-specific-group]
+  </context_groups>
+
   <source_of_truth>
     <requirement>[Link to requirement or spec]</requirement>
     <architecture>[Link to architecture doc or ADR]</architecture>
@@ -154,6 +161,7 @@
     - [ ] Run verifier after each slice.
     - [ ] Inspect diff after each slice.
     - [ ] Update `state.md` after each slice.
+    - [ ] (Optional) Record quantitative metric deltas in `results.tsv` if tracking benchmarks/performance.
   </phase>
 
   <phase name="Review" order="5">

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

@@ -26,7 +26,7 @@
   <group id="seeds">
     <title>Seeds & Archetypes Guide</title>
     <path>[`../_seeds/_GUIDE.md`](../_seeds/_GUIDE.md)</path>
-    <scope>Scaffolding seeds for tasks, research, decisions, plans, state, reviews, handoffs, and programs. Full artifact chain and instantiation commands.</scope>
+    <scope>Scaffolding seeds for tasks, research, decisions, plans, state, reviews, handoffs, pause, cancellation, benchmarks, and programs. Full artifact chain and instantiation commands.</scope>
   </group>
 
   <group id="tests">

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

@@ -1,31 +1,87 @@
 # Planning Standards & Calibration Context
 
-<planning_context version="1.0">
+<planning_context version="2.0">
 
 <overview>
-  Guidelines for story point estimation, vertical slicing, and capacity calibration.
+  Engineering guidelines for story point estimation, vertical slicing, rollback checkpointing, and capacity calibration.
 </overview>
 
-## 1. Quality Standards
+---
+
+## 1. Quality Standards (INVEST Criteria)
+
 <quality_standards>
   <standard name="INVEST">
-    - **Independent:** Deliverable without cross-story blockers.
-    - **Negotiable:** Implementation details are flexibly refined.
-    - **Valuable:** Delivers measurable user or business value.
-    - **Estimable:** Scoped clearly to estimate effort.
-    - **Small:** Fits within 1-3 engineering days.
-    - **Testable:** Concrete Acceptance Criteria defined.
-  </standard>
-
-  <standard name="Vertical Slicing">
-    Avoid horizontal silos. Deliver end-to-end vertical slices across API, logic, and persistence.
+    - **Independent:** Deliverable and verifiable without cross-story circular blockers.
+    - **Negotiable:** Implementation details and technical approaches can be flexibly evaluated during the Innovate phase.
+    - **Valuable:** Delivers demonstrable capability or verifiable engineering progress.
+    - **Estimable:** Scoped tightly enough that effort and file touchpoints can be calculated.
+    - **Small:** Sized to fit comfortably within 1–3 engineering days (or 1–3 Story Points).
+    - **Testable:** Accompanied by unambiguous, verifiable Acceptance Criteria (`- [ ]`).
   </standard>
 </quality_standards>
 
-## 2. Capacity Calibration
+---
+
+## 2. Vertical Slicing Discipline
+
+<vertical_slicing>
+  ### Vertical Slice vs Horizontal Silo
+  - **The Vertical Slice Rule:** Each slice must cut through all required technical layers (e.g. Domain Model $\rightarrow$ Service/Logic $\rightarrow$ Port Adapter/API $\rightarrow$ Automated Test) to deliver one complete, verifiable increment of behavior.
+  - **The Horizontal Silo Anti-Pattern:** Never slice horizontally (e.g., Slice 1: create all database tables, Slice 2: create all services, Slice 3: create all endpoints). Horizontal layers cannot be verified independently, leaving the system in a broken or unprovable state until the final slice.
+
+  ### Vertical Slicing Workflow
+  ```text
+  [Slice 1: Thin End-to-End Core] ──► Domain Entity + In-Memory Repo + Minimal Endpoint + Passing Test
+  [Slice 2: Persistence & Boundary] ──► Real Database Adapter + Migration + Integration Verifier
+  [Slice 3: Edge Cases & Validation] ──► Strict Input Sanitization + Error Handlers + Boundary Tests
+  ```
+</vertical_slicing>
+
+---
+
+## 3. Slice Sizing, Atomic Verifiability & Checkpoints
+
+<slice_sizing>
+  <rule id="slice_cardinality">
+    A standard task should contain between **2 and 5 vertical slices**. If a task requires more than 5 slices, it has high blast radius and must be decomposed into a Multi-Phase Program (`program-template.md.seed`).
+  </rule>
+
+  <rule id="autonomous_verifier">
+    Every single slice in `plan.md` must have an explicit, executable `<verifier>` command (e.g. `npm run test -- test/path/test.js` or `pytest tests/unit/test_slice.py`). A slice is NOT complete until its verifier exits with code 0.
+  </rule>
+
+  <rule id="atomic_checkpoint">
+    Commit or checkpoint each slice atomically upon verification passing. This guarantees clean git history and enables instant rollback if subsequent slices encounter irrecoverable regressions.
+  </rule>
+</slice_sizing>
+
+---
+
+## 4. Rollback Strategy per Slice
+
+<rollback_strategy>
+  Every slice in `plan.md` MUST specify a concrete `<rollback_point>`:
+  - **Git Checkpoint:** `git checkout -- <allowed_files>` or revert commit hash.
+  - **Stash Checkpoint:** `git stash pop` or dedicated WIP branch.
+  - **Data/Schema Rollback:** Down-migration script or drop ephemeral test container.
+
+  If the agent exhausts its 3-attempt retry budget on a slice, it must execute the rollback point before halting and escalating to human guidance.
+</rollback_strategy>
+
+---
+
+## 5. Story Point Capacity Calibration
+
 <capacity_calibration>
-  <unit>1 Story Point ≈ 2-4 focused engineering hours</unit>
-  <max_task_size>3-5 Story Points (larger tasks must be decomposed)</max_task_size>
+  <unit>1 Story Point (SP) ≈ 2–4 focused engineering hours</unit>
+  <scale>
+    - **1 SP:** Straightforward change with clear scope (1-3 files touched, 1-2 slices).
+    - **2 SP:** Standard feature or refactoring (3-5 files touched, 2-3 slices).
+    - **3 SP:** Moderately complex task touching domain contracts and persistence (4-7 files, 3-4 slices).
+    - **5 SP:** Maximum size for a single active task in `process/features/active/`.
+    - **> 5 SP:** Oversized. Must be split into multiple standalone tasks or organized under `program-template.md.seed`.
+  </scale>
 </capacity_calibration>
 
 </planning_context>

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

@@ -1,56 +1,113 @@
 # Testing Standards & Harness Strategy Context
 
-<testing_context version="1.0">
+<testing_context version="2.0">
 
 <overview>
-  Guidelines for test pyramid calibration, isolation policies, mock conventions, and automated verification harness across the system.
+  Guidelines for test pyramid calibration, isolation policies, mock conventions, fixture hygiene, and automated verification harness across the system.
 </overview>
 
-## 1. Test Pyramid & Classification
+---
+
+## 1. Test Pyramid & Layer Calibration
+
 <test_pyramid>
   <layer name="Unit Tests" path="tests/unit/">
-    - Scope: Pure business logic, domain models, utility functions, edge case branching.
-    - Execution speed: Fast (< 50ms per test), zero network/disk/external I/O.
-    - Mock policy: Mock all I/O boundaries, external clients, and port interfaces.
+    - **Scope:** Pure domain models, business logic calculations, utility functions, edge-case branching.
+    - **Speed & Constraints:** Ultra-fast (< 50ms per test). Zero network calls, zero disk I/O, zero real database connections.
+    - **Mocking Policy:** Mock all port interfaces, external clients, and I/O boundaries.
   </layer>
 
   <layer name="Integration Tests" path="tests/integration/">
-    - Scope: Database persistence, external API client adapters, framework wiring.
-    - Isolation: Ephemeral test containers (e.g. Testcontainers) or dedicated isolated test database per suite.
-    - Teardown: Must guarantee zero state leakage across test runs.
+    - **Scope:** Repository persistence adapters, database queries, migration scripts, HTTP client wrappers, framework wiring.
+    - **Isolation:** Ephemeral test containers (e.g. Testcontainers), in-memory databases, or isolated schema instances per test worker.
+    - **Teardown:** Must guarantee 100% state cleanup with zero leakage across test runs.
   </layer>
 
   <layer name="End-to-End Tests" path="tests/e2e/">
-    - Scope: Critical user journeys, full HTTP/gRPC API lifecycle, regression smoke tests.
-    - Verification: Validates end-to-end contract integrity across subsystems.
+    - **Scope:** Critical user journeys, public API lifecycle, full authentication flows, regression smoke tests.
+    - **Verification:** Validates end-to-end contract integrity across the entire system.
   </layer>
 </test_pyramid>
 
-## 2. Test Harness Policies
-<test_policies>
-  <policy name="Determinism">
-    Zero flaky tests. Tests must not depend on real wall-clock time (use frozen clocks or fake timers) or randomized execution order.
-  </policy>
+---
+
+## 2. Mocking Boundaries & Anti-Patterns
+
+<mocking_boundaries>
+  <rule id="mock_at_architectural_boundary">
+    **Mock at the boundaries, never at the core.** Only mock external infrastructure: third-party HTTP APIs, message brokers, email services, or system clock.
+  </rule>
+
+  <rule id="do_not_mock_domain_or_sut">
+    Never mock the System Under Test (SUT) or pure domain entities/value objects. If a domain entity is hard to instantiate without mocks, its design is coupled and requires refactoring.
+  </rule>
+
+  <rule id="verify_mock_interactions_sparingly">
+    Prefer asserting on return values and observable state changes rather than verifying exact method call counts (`toHaveBeenCalledTimes`), which couples tests to private implementation details.
+  </rule>
+</mocking_boundaries>
+
+---
+
+## 3. Test Fixture & Data Factory Hygiene
+
+<fixture_hygiene>
+  <rule id="data_factories_over_preseeded_db">
+    Use explicit test factories (or builder functions) with sensible defaults rather than relying on brittle, shared SQL seed dumps.
+  </rule>
+
+  <rule id="no_shared_mutable_fixtures">
+    Every test must instantiate its own data fixtures. Never share mutable state or global test variables between tests.
+  </rule>
+
+  <rule id="deterministic_teardown">
+    Always clean up database records, temp files, or mock registries in `afterEach` / `teardown` hooks to prevent cascading cross-test failures.
+  </rule>
+</fixture_hygiene>
+
+---
+
+## 4. Determinism & Flaky Test Zero-Tolerance
+
+<determinism>
+  <rule id="frozen_clock">
+    Never use real wall-clock time (`Date.now()`, `datetime.now()`) in time-sensitive assertions. Use frozen clocks or fake timers to ensure absolute reproducibility.
+  </rule>
+
+  <rule id="order_independence">
+    Tests must pass when run individually or in random order (`--randomize`). Never rely on one test running before another.
+  </rule>
+
+  <rule id="no_arbitrary_sleeps">
+    Never use arbitrary `sleep(1000)` in async tests. Use explicit polling helpers with timeouts (`waitFor`, `eventually`) that resolve as soon as the expected condition is met.
+  </rule>
+</determinism>
+
+---
+
+## 5. Assertion Precision & Failure Clarity
+
+<assertion_precision>
+  <rule id="exact_assertions">
+    Avoid vague assertions (e.g. `expect(res).toBeTruthy()`). Always assert exact expected values, HTTP status codes, and error codes.
+  </rule>
 
-  <policy name="Clean State">
-    Every test must seed its own data or fixtures. Tests must never assume pre-existing database rows.
-  </policy>
+  <rule id="actionable_failure_messages">
+    When custom assertions are used, provide clear error messages indicating what input was given and what specific invariant was violated.
+  </rule>
+</assertion_precision>
 
-  <policy name="Assertion Precision">
-    Avoid vague assertions (e.g. `expect(res).toBeTruthy()`). Always assert exact expected structures, status codes, and error types.
-  </policy>
+---
 
-  <policy name="Fast Feedback">
-    Unit tests must execute in under 30 seconds for the entire suite. Slow integration suites must be cleanly partitioned.
-  </policy>
-</test_policies>
+## 6. Verification Commands Mapping
 
-## 3. Verification Commands Mapping
 <verification_commands>
   <!-- Keep aligned with AGENTS.md <validation_commands> -->
-  <command type="unit">Run fast unit test suite</command>
-  <command type="integration">Run integration/e2e tests</command>
-  <command type="coverage">Run test coverage check</command>
+  <command type="unit">Run fast unit test suite (< 30 seconds total)</command>
+  <command type="integration">Run isolated integration/e2e tests</command>
+  <command type="typecheck">Run static type checker (zero errors, strict mode)</command>
+  <command type="lint">Run linter and format checker (zero warnings)</command>
+  <command type="coverage">Run test coverage report and threshold check</command>
 </verification_commands>
 
 </testing_context>

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>