@educa-corp/sdd-framework 0.6.0 → 0.7.0

package/templates/README.md

@@ -1,70 +0,0 @@
-# templates/ — build-time skeletons
-
-> **Nếu bạn đang mở thư mục này ở `.agent/templates/` trong một project: sửa file ở đây KHÔNG có tác dụng.**
-
-## Vì sao
-
-Các skeleton trong thư mục này được `{{include}}` **nướng cứng vào file lệnh lúc `npm run build`**:
-
-```
-templates/feature.template
-      ↓ {{include:templates/feature.template}}  ← bin/build.js, thay thế văn bản lúc build
-commands/generate-bdd.md
-      ↓ copy vào core/ → mirror sang .agent/
-.agent/commands/generate-bdd.md        ← LỆNH THẬT SỰ CHẠY (đã chứa sẵn skeleton)
-.agent/templates/feature.template      ← bản tham khảo, KHÔNG lệnh nào đọc
-```
-
-Không lệnh nào đọc một path template lúc chạy. `paths.feature_template` / `paths.prd_template` từng tồn tại trong `project-context.yaml` nhưng chưa bao giờ có tác dụng — đã được gỡ bỏ (xem `GAPS.md` G9).
-
-**Thêm nữa:** `.agent/` là vùng bị ghi đè. `/update-framework` chạy `npx … --init`, và `--init` copy `core/` → `.agent/` **vô điều kiện** (`bin/index.js` → `installCore`). File duy nhất được giữ lại là `.agent/project-context.yaml`. Nên mọi chỉnh sửa ở `.agent/templates/` sẽ **biến mất** ở lần nâng cấp kế tiếp — từ v0.4.2 thì không còn im lặng: bản cũ được lưu vào `.agent/.overwritten-{version}-{date}/` và được liệt kê ra (`GAPS.md` G24). Nhưng vẫn phải áp lại bằng tay mỗi version, nên đây không phải chỗ để đặt thay đổi.
-
----
-
-## Ngoại lệ: `ci/` và `hooks/` — template để COPY RA, không phải để build
-
-Hai thư mục này **không** giống phần còn lại của `templates/`. Chúng không được `{{include}}` vào lệnh nào, và **không** được đọc lúc chạy. Chúng là file **hoàn chỉnh, dùng ngay**, chờ một người copy ra khỏi `.agent/`:
-
-| File | Copy tới | Làm gì |
-|---|---|---|
-| `ci/trace-gate.yml` | `.github/workflows/` của project | Chặn PR khi trace có cờ 🔴 (`--gate-trace`) |
-| `hooks/pre-push` | `.git/hooks/pre-push` (rồi `chmod +x`) | Chặn push khi sổ trace hỏng cấu trúc (`--lint-trace`) |
-
-```bash
-# từ gốc project
-mkdir -p .github/workflows && cp .agent/templates/ci/trace-gate.yml .github/workflows/
-cp .agent/templates/hooks/pre-push .git/hooks/pre-push && chmod +x .git/hooks/pre-push
-```
-
-**Phải copy RA, không dùng tại chỗ** — vì đúng cái lý do cả file README này nói: `.agent/` bị ghi đè mỗi lần nâng cấp, và `.git/hooks/` thì git không bao giờ chạy từ chỗ khác. Copy ra rồi thì chúng là file của project: sửa tuỳ ý, nâng cấp framework không đụng tới.
-
-Vì sao chúng tồn tại → `GAPS-v3.md` G39: framework phát hiện được một lớp lỗi mà build xanh + test xanh không thấy, nhưng trước đó việc phát hiện phụ thuộc vào có người tự nguyện chạy một lệnh chat. Hai file này là chỗ nó chặn bằng máy.
-
-## Muốn đổi cấu trúc artifact sinh ra thì làm gì
-
-Sửa file trong **repo framework** rồi build lại:
-
-```bash
-# trong repo sdd-framework
-vim templates/feature.template          # hoặc prd.template.md, tech-design.template.md, …
-npm run build                           # inline lại vào commands/*.md + core/ + .agent/
-```
-
-Rồi phát hành version mới; project chạy `/update-framework` để nhận.
-
-## File nào ở đây đi vào đâu
-
-| Template | Được include vào | Trở thành |
-|---|---|---|
-| `feature.template` | `commands/generate-bdd.tmpl` | mỗi file `.feature` |
-| `prd.template.md` | `commands/generate-prd.tmpl` | mỗi PRD |
-| `tech-design.template.md` | `commands/generate-tech-docs.tmpl` | tech-doc gộp / PRD |
-| `design-spec.template.md` | `commands/generate-design-spec.tmpl` | design-spec / platform |
-| `architecture.template.md` | `commands/generate-architecture.tmpl` | tài liệu kiến trúc |
-| `product-definition.template.md` | `commands/define-product.tmpl` | product definition |
-| `platform-guide.template.md` | (tham khảo) | — |
-| `project-context.yaml` | **không** include — được copy thẳng làm file config khởi tạo | `.agent/project-context.yaml` |
-| `ci/trace-gate.yml` | **không** include — người dùng copy ra | `.github/workflows/trace-gate.yml` |
-| `hooks/pre-push` | **không** include — người dùng copy ra | `.git/hooks/pre-push` |
-
-> Lưu ý `project-context.yaml` là ngoại lệ duy nhất: nó **được** copy ra làm file thật của project, và **được bảo vệ** khỏi ghi đè khi nâng cấp (chỉ tạo nếu chưa tồn tại).

package/templates/architecture.template.md

@@ -1,394 +0,0 @@
----
-last_verified: {{YYYY-MM-DD}}
-verified_by: {{AUTHOR}}
----
-
-# {{SYSTEM_NAME}} — Bối cảnh Kiến trúc (Architecture Context)
-
-> Nguồn chân lý duy nhất (single source of truth) về kiến trúc hệ thống — phục vụ cả bối cảnh sinh code (AI agents) lẫn các vấn đề vận hành (triển khai, CI/CD, NFR).
->
-> HƯỚNG DẪN DÙNG TEMPLATE:
-> - Điền các `{{PLACEHOLDER}}`, xoá comment hướng dẫn (`<!-- ... -->`) sau khi điền.
-> - Không cần điền tay: nên chạy `/generate-architecture` để tự hút từ config/tài liệu/code + phỏng vấn, rồi con người verify.
->
-> PHÂN TẦNG (tier) — mỗi mục có marker `<!-- tier: core|conditional|ops -->`:
-> - **core** — luôn điền. Kiến trúc nền mà mọi feature cần.
-> - **conditional** — chỉ giữ nếu hệ thống thực sự có (multi-tenant, message bus, sharding…). Không dùng → để dạng STUB hoặc xoá hẳn.
-> - **ops** — vận hành, chỉ để người đọc. AI **KHÔNG** nạp khi sinh code/tech-design.
->
-> ĐIỀN DẦN: không phải điền hết một lần. Mục chưa làm để dạng STUB rồi lấp sau bằng `/generate-architecture --section=<slug>`:
-> ```
-> ## Multi-tenant  <!-- tier: conditional --> <!-- status: stub -->
-> > ⏳ Chưa tài liệu hoá. Chạy `/generate-architecture --section=multi-tenant` khi cần, hoặc điền tay.
-> ```
-
-<!-- ════════════════════ CORE (luôn điền) ════════════════════ -->
-
-## Công nghệ sử dụng (Tech Stack)  <!-- tier: core -->
-
-| Tầng | Công nghệ | Phiên bản / Ghi chú |
-|---|---|---|
-| Backend | {{BACKEND_TECH}} | {{VERSION}} |
-| Frontend | {{FRONTEND_TECH}} | {{VERSION}} |
-| ORM / Truy cập dữ liệu | {{ORM}} | {{VERSION}} |
-| Database | {{DATABASE}} | {{PRIMARY_STORE_NOTE}} |
-| Caching | {{CACHE}} | {{CACHE_NOTE}} |
-| Event Bus / Messaging | {{MESSAGING}} | {{MESSAGING_NOTE}} |
-| API Gateway | {{GATEWAY}} | {{GATEWAY_NOTE}} |
-| Kiểm thử | {{TEST_STACK}} | {{TEST_NOTE}} |
-<!-- Thêm/bớt dòng theo thực tế. Cột Ghi chú nên ghi ràng buộc cụ thể AI cần biết (vd: "dùng cho mọi màn hình list", "thư viện private wrapper"). -->
-
-## Các tầng kiến trúc (Architecture Layers)  <!-- tier: core -->
-
-Kiểu kiến trúc: `{{ARCH_STYLE}}`  <!-- vd: Layered / Clean / Hexagonal / Component-based -->
-
-```
-{{LAYER_DIAGRAM}}
-```
-<!-- Ví dụ Clean Architecture:
-┌──────────────────────────────────────┐
-│  Presentation   │  Controllers, Middleware
-├──────────────────────────────────────┤
-│  Application    │  Use Cases, DTOs, Interfaces
-├──────────────────────────────────────┤
-│  Domain         │  Entities, Value Objects, Events
-├──────────────────────────────────────┤
-│  Infrastructure │  ORM, Cache, Messaging
-└──────────────────────────────────────┘
--->
-
-### Chiều phụ thuộc
-- {{OUTER}} → {{MIDDLE}} → {{INNER}} ← {{INFRASTRUCTURE}}
-- {{INNER_LAYER}} có **zero** phụ thuộc ngoài.
-- Infrastructure hiện thực các interface do Application/Domain định nghĩa.
-- Tầng trong KHÔNG được phụ thuộc tầng ngoài.
-
-## Quy ước đặt tên  <!-- tier: core -->
-
-| Thành phần | Quy ước | Ví dụ |
-|---|---|---|
-| Entity | {{ENTITY_CONV}} | {{EXAMPLE}} |
-| Value Object | {{VO_CONV}} | {{EXAMPLE}} |
-| Interface | {{INTERFACE_CONV}} | {{EXAMPLE}} |
-| Use Case Command | {{COMMAND_CONV}} | {{EXAMPLE}} |
-| Use Case Query | {{QUERY_CONV}} | {{EXAMPLE}} |
-| Handler | {{HANDLER_CONV}} | {{EXAMPLE}} |
-| DTO | {{DTO_CONV}} | {{EXAMPLE}} |
-| Controller | {{CONTROLLER_CONV}} | {{EXAMPLE}} |
-| DI Extension | {{DI_EXT_CONV}} | {{EXAMPLE}} |
-| Class test | {{TEST_CLASS_CONV}} | {{EXAMPLE}} |
-| Method test | {{TEST_METHOD_CONV}} | {{EXAMPLE}} |
-
-> Quy ước đặt tên của frontend / từng repo → xem `.ai-project-guide.md` tương ứng.
-
-## Định dạng response API chuẩn  <!-- tier: core -->
-
-```{{LANG}}
-// Thành công
-{{SUCCESS_WRAPPER}}
-→ {{SUCCESS_JSON_SHAPE}}
-
-// Thất bại
-{{FAILURE_WRAPPER}}
-→ {{FAILURE_JSON_SHAPE}}
-```
-
-## Quy ước API  <!-- tier: core -->
-
-| Khía cạnh | Quy ước |
-|---|---|
-| Base URL | {{BASE_URL}} |
-| Versioning | {{VERSIONING}}  <!-- vd: URL path /v1/, theo header, query param --> |
-| Đặt tên URL | {{URL_NAMING}}  <!-- vd: kebab-case --> |
-| Phân trang | {{PAGINATION}}  <!-- vd: ?page=1&pageSize=20 → meta{...} --> |
-| Lọc | {{FILTERING}} |
-| Sắp xếp | {{SORTING}} |
-| Định dạng ngày | {{DATE_FORMAT}}  <!-- vd: ISO 8601 --> |
-| Ngừng hỗ trợ (Deprecation) | {{DEPRECATION_POLICY}} |
-
-### Các endpoint chính theo service  <!-- [TUỲ CHỌN] -->
-
-| Service | Endpoints |
-|---|---|
-| {{SERVICE}} | {{ENDPOINTS}} |
-
-> Tài liệu API đầy đủ: {{API_DOCS_LOCATION}}  <!-- vd: /swagger cho mỗi service -->
-
-## Quy ước Database  <!-- tier: core -->
-
-- **Migration**: {{MIGRATION_STRATEGY}}  <!-- vd: code-first mỗi service -->
-- **Đặt tên**: {{DB_NAMING}}  <!-- vd: PascalCase cho entity, snake_case cho cột -->
-- **Soft Delete**: {{SOFT_DELETE_RULE}}
-- **Cột audit**: {{AUDIT_COLUMNS}}  <!-- vd: CreatedAt NOT NULL, ModifiedAt nullable -->
-- **Xử lý đồng thời**: {{CONCURRENCY_MECHANISM}}  <!-- vd: ROWVERSION / optimistic lock -->
-- **Quy ước ID**: {{PK_TYPE}}  <!-- vd: bigint (không dùng Guid) -->
-
-### Quy ước Migration  <!-- [TUỲ CHỌN] khi dùng SQL migration thủ công -->
-- **Vị trí**: {{MIGRATION_LOCATION}}
-- **Đặt tên**: {{MIGRATION_NAMING}}  <!-- vd: V{YYYYMMDD}_{NN}_{description}.sql -->
-- **Tính idempotent**: {{IDEMPOTENCY_RULE}}  <!-- vd: dùng guard IF NOT EXISTS -->
-
-<!-- ════════════════════ CONDITIONAL (chỉ giữ nếu hệ thống có) ════════════════════ -->
-
-## Luồng dữ liệu tổng quan  <!-- tier: conditional -->
-
-<!-- Mô tả 1-2 câu bản chất luồng dữ liệu của hệ thống (vd: "hệ tổng hợp dữ liệu: master data ở hệ ngoài, config/transaction ở DB local, gộp tại runtime"). -->
-{{DATA_FLOW_SUMMARY}}
-
-```
-{{DATA_FLOW_DIAGRAM}}
-```
-<!-- Vẽ ASCII: Clients → Gateway → Services → điểm composition ở Application → Infrastructure (API ngoài / DB / cache / bus).
-     Ghi rõ phương thức auth của từng client và các điểm composition quan trọng. -->
-
-### Phân loại nguồn dữ liệu  <!-- [TUỲ CHỌN] khi dữ liệu đến từ nhiều nguồn (API ngoài + DB local) -->
-
-| Dữ liệu | Nguồn | Cách truy cập | Caching |
-|---|---|---|---|
-| {{DATA}} | {{SOURCE}} | {{PATH}} | {{TTL_OR_DASH}} |
-
-### Giao tiếp giữa các service  <!-- [TUỲ CHỌN] khi multi-service -->
-
-```
-{{SERVICE_A}}  ──{{PROTOCOL}}──▶ {{SERVICE_B}}   ({{VIA_CLIENT}})
-```
-
-> **Endpoint nội bộ** ({{INTERNAL_ROUTE_PREFIX}}): {{INTERNAL_AUTH_MECHANISM}} — vd: header shared-secret + IP whitelist. Xem §Luồng Xác thực.
-
-## Repositories & Hướng dẫn nền tảng  <!-- tier: conditional -->  <!-- chỉ giữ nếu là hệ multi-repo -->
-
-| Repository | Stack | Platform Guide |
-|---|---|---|
-| `{{repo-name}}/` | {{STACK_SUMMARY}} | `{{repo-name}}/.ai-project-guide.md` |
-
-> **Cấu trúc thư mục, scan path, quy ước namespace, code pattern** → xem `.ai-project-guide.md` của từng repo.
-> File này tập trung vào **kiến trúc cắt ngang** dùng chung cho mọi repo.
-
-## Phân loại Entity  <!-- tier: conditional -->  <!-- khi hệ thống tích hợp dữ liệu từ hệ ngoài -->
-
-Entity được chia thành các nhóm sau. Mọi code, tài liệu, và BDD spec PHẢI dùng các thuật ngữ này nhất quán.
-
-| Nhóm | Thuật ngữ | Lưu ở DB? | ORM quản lý? | Truy cập qua | Ví dụ |
-|---|---|---|---|---|---|
-| **DB Entity** | `[entity] entity` | CÓ | CÓ | {{DB_REPO_INTERFACE}} | {{EXAMPLES}} |
-| **Model nguồn-API** | `[entity] model` | KHÔNG | KHÔNG — POCO/DTO | {{API_SERVICE_INTERFACE}} | {{EXAMPLES}} |
-| **Projection Entity** | `[entity] projection` | CÓ | CÓ | {{PROJECTION_REPO}} | {{EXAMPLES}} |
-
-**Quy tắc:**
-- Model nguồn-API KHÔNG có bảng DB, KHÔNG migration — là POCO/DTO được populate từ API ngoài.
-- {{ID_RULE}}  <!-- vd: Model nguồn-API Id = external ID; DB entity Id = tự sinh -->
-- {{PROJECT_SPECIFIC_RULE}}
-
-## Phân loại truy cập dữ liệu — Ranh giới các tầng  <!-- tier: conditional -->  <!-- khi gộp dữ liệu nhiều nguồn (API ngoài + DB) -->
-
-Cách các tầng truy cập dữ liệu và ranh giới giữa chúng:
-
-```
-{{ACCESS_TREE}}
-```
-<!-- Ví dụ:
-Handler / Controller
-  ├── IProductCatalogService (Application — điểm gộp DUY NHẤT)
-  │     ├── IProductService (Infrastructure — API ngoài)
-  │     └── IDisplayConfigRepository (Infrastructure — DB)
-  └── IOrderRepository (Infrastructure — DB, inject trực tiếp)
--->
-
-| Tầng | Mục đích | Sở hữu | Ví dụ |
-|---|---|---|---|
-| **{{API_SERVICE_LAYER}}** (Infrastructure) | Gọi API ngoài; tự quản cache/retry/circuit-breaker/mapping | Model nguồn-API | {{EXAMPLES}} |
-| **{{DB_REPO_LAYER}}** (Infrastructure) | Thao tác DB local; repository pattern chuẩn | DB entity | {{EXAMPLES}} |
-| **{{APP_SERVICE_LAYER}}** (Application) | Gộp dữ liệu nhiều nguồn; điểm composition duy nhất | Domain object đã enrich | {{EXAMPLES}} |
-| **{{HANDLER_LAYER}}** (Presentation/Application) | Điều phối use-case; mapping request→response | — | {{EXAMPLES}} |
-
-**Quy tắc Injection (BẮT BUỘC tuân theo):**
-1. {{RULE_1}}  <!-- vd: Service gọi API ngoài chỉ inject vào Application Service, KHÔNG inject thẳng vào Handler -->
-2. {{RULE_2}}
-3. {{RULE_3}}
-
-## Trách nhiệm của từng service  <!-- tier: conditional -->  <!-- khi multi-service -->
-
-| Service | Domain | Trách nhiệm chính |
-|---|---|---|
-| {{SERVICE}} | {{DOMAIN}} | {{RESPONSIBILITIES}} |
-
-## Mô hình đăng ký DI  <!-- tier: conditional -->
-
-Mỗi feature đăng ký dependency qua extension method / module:
-```{{LANG}}
-{{DI_REGISTRATION_EXAMPLE}}
-```
-
-## Mô hình Multi-tenant  <!-- tier: conditional -->  <!-- khi một hệ thống phục vụ nhiều khách hàng/chi nhánh, dữ liệu tách riêng -->
-
-Mọi entity (trừ {{GLOBAL_ENTITIES}}) PHẢI có `{{TENANT_KEY}}`. {{ISOLATION_MECHANISM}} đảm bảo cách ly:
-```{{LANG}}
-{{QUERY_FILTER_EXAMPLE}}
-```
-
-Truy cập tenant context qua: `{{TENANT_CONTEXT_ACCESSOR}}`  <!-- các field: TenantId, AppId, UserId... -->
-
-## Phân giải định danh — External ID vs Internal ID  <!-- tier: conditional -->  <!-- khi tích hợp hệ ngoài có ID riêng -->
-
-Hệ thống tích hợp với {{EXTERNAL_SYSTEM}}. Mỗi entity ngoài có ID riêng, **KHÔNG trùng** với internal ID. Hai hệ ID này phải luôn được phân biệt rõ.
-
-| | DB Entity (local) | Model nguồn-API (ngoài) |
-|---|---|---|
-| **`Id`** | {{INTERNAL_ID_RULE}} (tự sinh) | Gán từ response hệ ngoài — KHÔNG tự sinh |
-| **`ExternalId`** | Lưu ID hệ ngoài để tham chiếu chéo | Không áp dụng — `Id` chính là external ID |
-
-### Quy tắc bắt buộc
-1. {{RULE_1}}  <!-- vd: DB Entity Id luôn tự sinh, TUYỆT ĐỐI KHÔNG gán external ID vào Id -->
-2. {{RULE_2}}
-3. {{RULE_3}}
-
-### Anti-pattern (CẤM)
-```{{LANG}}
-// ❌ SAI — {{ANTIPATTERN_DESC}}
-{{BAD_EXAMPLE}}
-
-// ✅ ĐÚNG
-{{GOOD_EXAMPLE}}
-```
-
-## API Gateway  <!-- tier: conditional -->
-
-| Trách nhiệm | Chi tiết |
-|---|---|
-| Xác minh chữ ký / auth | {{DETAIL}} |
-| Rate limiting | {{DETAIL}} |
-| Xử lý CORS | {{DETAIL}} |
-| Định tuyến request | {{DETAIL}} |
-| Cân bằng tải | {{DETAIL}} |
-| IP whitelist | {{DETAIL}} |
-
-**Nguyên tắc thiết kế:** Stateless, không chứa business logic, scale ngang được.
-
-## Chiến lược Caching  <!-- tier: conditional -->
-
-**Mô hình**: {{CACHE_PATTERN}}  <!-- vd: Cache-Aside (read-through) -->
-**Định dạng key**: {{KEY_FORMAT}}  <!-- vd: {entity}:{tenantId}:{id} -->
-
-| Loại dữ liệu | TTL | Cách invalidate |
-|---|---|---|
-| {{DATA}} | {{TTL}} | {{INVALIDATION}} |
-
-## Event Bus  <!-- tier: conditional -->
-
-> **Trạng thái:** {{STATUS}}  <!-- vd: đã cấp hạ tầng nhưng chưa implement / đã chạy production -->
-
-**Nguyên tắc thiết kế:**
-- {{PARTITIONING}}  <!-- vd: partition theo TenantId để đảm bảo thứ tự trong mỗi tenant -->
-- {{DELIVERY_GUARANTEE}}  <!-- vd: at-least-once + theo dõi idempotency -->
-- {{DLQ_RETRY}}  <!-- vd: DLQ {topic}.dlq, retry 3 lần với exponential backoff -->
-
-## Sharding  <!-- tier: conditional -->
-
-- {{SHARD_STRATEGY}}  <!-- vd: mô hình Shard Registry + cache -->
-- {{SHARD_RESOLVER}}  <!-- vd: IShardResolver: cache → Registry DB → tự gán -->
-
-## Feature Toggle  <!-- tier: conditional -->
-
-Hệ thống dùng {{FEATURE_TOGGLE_TOOL}} cho feature flag lúc runtime.
-
-| Điều kiện | Hành vi |
-|---|---|
-| Toggle bị tắt | {{BEHAVIOR}}  <!-- thường: fail-open / cho phép -->|
-| Lỗi khi đánh giá | {{BEHAVIOR}}  <!-- thường: fail-open để sự cố không khoá user -->|
-| Flag trả về false | {{BEHAVIOR}} |
-
-## Luồng Xác thực  <!-- tier: conditional -->
-
-### {{AUTH_METHOD}}  <!-- vd: JWT Bearer / API Key (HMAC) / OAuth2 / Token Exchange -->
-
-```
-{{AUTH_FLOW_STEPS}}
-```
-<!-- Liệt kê tuần tự các bước middleware xử lý: extract → verify → resolve → build context.
-     Nếu có nhiều luồng auth (S2S, browser, internal), mô tả từng luồng. -->
-
-**Quy tắc chính:**
-- {{AUTH_RULE_1}}
-- {{AUTH_RULE_2}}
-
-**Middleware pipeline:**
-```
-{{ROUTE_PATTERN}}  → {{MIDDLEWARE_OR_BYPASS}}
-{{HEALTH_ROUTE}}   → bypass (health probe)
-```
-
-<!-- ════════════════════ OPS (chỉ người đọc — AI không nạp khi sinh code) ════════════════════ -->
-
-## Observability (Khả năng quan sát)  <!-- tier: ops -->
-
-### Ghi log (Logging)
-- Thư viện: {{LOGGING_LIB}}
-- Định dạng: {{LOG_FORMAT}}  <!-- vd: Compact JSON -->
-- Sink: {{LOG_SINKS}}  <!-- vd: file xoay vòng theo ngày, giữ 30 ngày; console chỉ khi dev -->
-- **Correlation ID**: {{CORRELATION_MECHANISM}}  <!-- vd: X-Correlation-Id đẩy vào log context -->
-- Mức log: {{LOG_LEVELS}}
-
-### Metrics  <!-- [TUỲ CHỌN] -->
-
-| Metric | Loại | Mô tả |
-|---|---|---|
-| {{METRIC}} | {{TYPE}} | {{DESC}} |
-
-### Distributed Tracing  <!-- [TUỲ CHỌN] -->
-- {{TRACING_TOOL}} — {{PROPAGATION_SCOPE}}  <!-- vd: OpenTelemetry, propagate qua HTTP + messaging -->
-
-### Health Check
-```{{LANG}}
-{{HEALTH_CHECK_REGISTRATION}}
-```
-- `{{LIVENESS_ROUTE}}` — liveness (chỉ tự kiểm tra)
-- `{{READINESS_ROUTE}}` — readiness (phụ thuộc: DB + cache + bus)
-
-## Triển khai & DevOps  <!-- tier: ops -->
-
-### Chiến lược môi trường
-
-| Môi trường | Mục đích | Hạ tầng |
-|---|---|---|
-| Development | {{PURPOSE}} | {{INFRA}} |
-| Staging | {{PURPOSE}} | {{INFRA}} |
-| Production | {{PURPOSE}} | {{INFRA}} |
-
-### CI/CD Pipeline
-```
-{{PIPELINE_STAGES}}
-```
-<!-- vd: Code Push → Build → Unit Test → Integration Test → Docker Build → Push Registry → Deploy Staging → Smoke → Duyệt tay → Production -->
-
-### Quản lý cấu hình
-
-| Loại cấu hình | Lưu ở | Ví dụ |
-|---|---|---|
-| App Settings | {{STORAGE}} | {{EXAMPLE}} |
-| Secrets | {{SECRET_STORE}} | {{EXAMPLE}}  <!-- secret production TUYỆT ĐỐI KHÔNG commit vào repo -->|
-| Biến môi trường | {{ENV_STORE}} | {{EXAMPLE}} |
-
-## Chiến lược kiểm thử  <!-- tier: ops -->
-
-| Cấp độ | Phạm vi | Công cụ |
-|---|---|---|
-| Unit Test | {{SCOPE}} | {{TOOLS}} |
-| Integration Test | {{SCOPE}} | {{TOOLS}} |
-| Functional Test | {{SCOPE}} | {{TOOLS}} |
-| Load Test | {{SCOPE}} | {{TOOLS}} |
-
-- Đặt tên: {{TEST_NAMING}}  <!-- vd: MethodName_Scenario_ExpectedResult -->
-- {{CI_TEST_RULE}}  <!-- vd: CI chạy unit + integration mỗi PR -->
-
-## Yêu cầu phi chức năng (NFR)  <!-- tier: ops -->
-
-| Yêu cầu | Mục tiêu |
-|---|---|
-| Khả năng mở rộng | {{TARGET}} |
-| Tính sẵn sàng | {{TARGET}}  <!-- vd: SLA uptime 99.9% -->|
-| Triển khai | {{TARGET}}  <!-- vd: zero-downtime, rolling update -->|
-| Tính nhất quán | {{TARGET}} |
-| Độ trễ | {{TARGET}}  <!-- vd: API p95 < 200ms -->|
-| Thông lượng | {{TARGET}} |
-| Lưu trữ dữ liệu | {{TARGET}} |
-| Sao lưu | {{TARGET}} |

package/templates/ci/trace-gate.yml

@@ -1,146 +0,0 @@
-# ─────────────────────────────────────────────────────────────────────────────
-# SDD Framework — Trace Gate (GitHub Actions)
-#
-# COPY file này vào .github/workflows/ của project. Nó KHÔNG tự chạy từ
-# .agent/templates/ — mọi thứ trong .agent/ là bản sinh ra, bị ghi đè mỗi lần
-# /update-framework.
-#
-# VÌ SAO CẦN (GAPS-v3 G39): framework phát hiện được một lớp lỗi mà build xanh +
-# test từng-UC xanh KHÔNG thấy — luồng ghép chạy vào hàm rỗng (SEAM_UNWIRED,
-# STUB_UNRESOLVED), hoặc code trỏ vào scenario đã bị xoá (ORPHANED, TRACE_ORPHAN).
-# Nhưng trước G39 việc phát hiện đó phụ thuộc vào có người TỰ NGUYỆN chạy
-# /validate-traces trong Claude Code rồi đọc report bằng mắt. Cái gì không chặn
-# thì sau sprint thứ ba không ai làm. Đây là chỗ nó chặn.
-#
-# GIỚI HẠN — đọc trước khi tin:
-#   Job này chứng minh "report khớp SỔ, và sổ không có cờ 🔴".
-#   Nó KHÔNG chứng minh "sổ khớp CODE" — việc đó cần quét tag trong source, đọc
-#   .feature, so version, tức cần /validate-traces (một lệnh LLM, không chạy được
-#   trong CI thường). Nên nó bắt ca phổ biến "quên chạy lại /validate-traces",
-#   nhưng KHÔNG bắt ca "sửa code mà không đụng sổ".
-#   Muốn bịt nốt: xem job `require-fresh-audit` ở cuối file.
-# ─────────────────────────────────────────────────────────────────────────────
-
-name: Trace Gate
-
-on:
-  pull_request:
-  push:
-    branches: [main, master, develop]
-
-jobs:
-  trace-gate:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          # Cần lịch sử để job require-fresh-audit so được diff. Bỏ nếu không dùng job đó.
-          fetch-depth: 0
-          # Spec/trace nằm trong submodule (umbrella + spec_source)? Bỏ comment:
-          # submodules: recursive
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      # ── 1. Cấu trúc sổ ───────────────────────────────────────────────────────
-      # Sổ trace 24 cột do LLM ghi bằng tay. Một dấu tab thiếu dồn mọi ô sang trái
-      # và ô `status` nhận một ngày tháng — trước G38 không gì báo. Bước này chặn.
-      # Cũng bắt marker conflict git lọt vào sổ (T7) và sổ thiếu luật merge (T10).
-      - name: Lint sổ trace
-        run: npx -y @educa-corp/sdd-framework@latest --lint-trace
-
-      # ── 2. Cổng chặn PR ──────────────────────────────────────────────────────
-      # --gate-trace tự chạy lại lint ở tầng G1, nên bước 1 ở trên là để có log
-      # riêng dễ đọc khi đỏ. Muốn gọn thì bỏ bước 1 và chỉ giữ bước này.
-      - name: Trace gate (cờ 🔴 chặn PR)
-        run: npx -y @educa-corp/sdd-framework@latest --gate-trace
-
-      # ── 3. (tuỳ chọn) Đưa kết quả vào PR summary ─────────────────────────────
-      - name: Ghi kết quả vào job summary
-        if: always()
-        run: |
-          npx -y @educa-corp/sdd-framework@latest --gate-trace --json --warn-only \
-            > gate.json || true
-          {
-            echo '## Trace Gate'
-            echo '```json'
-            cat gate.json
-            echo '```'
-          } >> "$GITHUB_STEP_SUMMARY"
-
-  # ───────────────────────────────────────────────────────────────────────────
-  # Ép audit phải TƯƠI khi thứ report đang KHẲNG ĐỊNH bị đổi.
-  #
-  # Bịt cái lỗ mà trace-gate không bịt được: gate chứng minh "report khớp SỔ",
-  # không chứng minh "sổ khớp CODE" — việc đó cần /validate-traces, một lệnh LLM
-  # không chạy được ở đây. Nên job này dùng một PROXY: không verify được thì ĐÒI
-  # BẰNG CHỨNG có người vừa verify.
-  #
-  # ĐO BẰNG TAG, KHÔNG BẰNG `src/**`:
-  #   Framework có luật boundary-only tagging — chỉ Controller/Handler/Middleware/
-  #   Steps mang tag @trace; Entity/Repository/DTO/Interface/Base KHÔNG. Nên câu
-  #   hỏi "PR có sửa src/ không?" chặn cả PR chỉ thêm một field vào DTO — một file
-  #   không mang lời khẳng định trace nào. Cái gì báo oan thì bị tắt, rồi mất luôn
-  #   phần thật sự cần chặn.
-  #   Câu hỏi đúng: "PR có chạm dòng nào mang tag mà report đang khẳng định không?"
-  #
-  #   sửa log trong Controller  → cho qua      (bản `src/**` cũ: chặn oan)
-  #   thêm field vào DTO        → cho qua      (bản cũ: chặn oan)
-  #   thêm method + @implements → CHẶN
-  #   lấp một @trace.stub       → CHẶN
-  #
-  # KHÔNG cần sửa gì theo layout project — tag là tag, ở đâu cũng vậy.
-  #
-  # BẢY TAG dưới đây là NGUỒN của đúng 4 cờ chặn PR. Chúng được khai trong
-  # bin/trace-schema.json → gate.audit_invalidating_tags, và self-check R10 fail
-  # build nếu file này không nhắc đủ — tag đổi tên mà đây không biết thì grep
-  # không khớp gì, job LUÔN XANH, và cổng mù trong im lặng.
-  #
-  # GIỚI HẠN ĐÃ BIẾT: đổi tên class (AuthService → AuthenticationService) không
-  # chạm dòng tag ⇒ job này bỏ lọt, dù cột implemented_by giờ trỏ vào tên không
-  # còn. Chấp nhận có chủ ý: ca đó ít gặp và KHÔNG im lặng (/validate-traces lần
-  # sau báo ngay), còn báo oan thì xảy ra mỗi ngày.
-  #   Muốn chặt hơn (bắt cả rename, giá là chặn cả việc sửa log trong Controller):
-  #   đổi bước dưới thành — lấy danh sách file đã đổi, rồi `grep -l` bảy tag đó
-  #   TRÊN NỘI DUNG FILE thay vì trên diff.
-  # ───────────────────────────────────────────────────────────────────────────
-  require-fresh-audit:
-    if: github.event_name == 'pull_request'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }
-
-      - name: Đổi thứ report khẳng định thì audit phải đổi theo
-        shell: bash
-        run: |
-          BASE="origin/${{ github.base_ref }}"
-
-          # 7 tag sinh ra 4 cờ chặn PR — khai ở bin/trace-schema.json,
-          # gate.audit_invalidating_tags (self-check R10 canh danh sách này khớp).
-          TAGS='@trace\.(implements|verifies|seam_port|seam_pending|stub|stub_owner|stub_for)'
-
-          # Chạm dòng mang tag = report có thể đã hết đúng. -U0 để chỉ lấy dòng thật đổi.
-          touched=$(git diff -U0 "$BASE"...HEAD | grep -E "^[+-].*${TAGS}" | head -5 || true)
-          audit=$(git diff --name-only "$BASE"...HEAD | grep -E 'trace-report\.json$' | head -1 || true)
-
-          if [ -n "$touched" ] && [ -z "$audit" ]; then
-            echo "::error::PR đổi tag trace nhưng không kèm trace-report.json được sinh lại."
-            echo ""
-            echo "Những dòng này đã đổi:"
-            echo "$touched" | sed 's/^/    /'
-            echo ""
-            echo "Trace gate chỉ chứng minh 'report khớp SỔ'. Tag vừa đổi mà chưa audit lại"
-            echo "thì mọi cờ 🔴 trong report nói về trạng thái TRƯỚC khi bạn sửa."
-            echo ""
-            echo "Chạy trong Claude Code:  /validate-traces"
-            echo "Rồi commit:              {trace_dir}/trace-report.json + *.tsv"
-            exit 1
-          fi
-
-          if [ -n "$touched" ]; then
-            echo "✅ Tag trace có đổi, và audit đã được sinh lại cùng PR."
-          else
-            echo "✅ PR không chạm tag nào mà report đang khẳng định — audit vẫn còn đúng."
-          fi