@edupia-tutor/spec-driven-docs 0.14.0

package/templates/design-spec.template.md

@@ -0,0 +1,217 @@
+# {TICKET-ID} {Feature Name} — Design Spec [{Platform}]
+
+<!--
+  Template này được sử dụng bởi /generate-design-spec.
+  Platform = web | app | app-ios | app-android
+
+  PLATFORM SECTIONS:
+  - Section 3A + 4A: chỉ dành cho web (react/nextjs/vue/angular). Xóa C khi dùng cho web.
+  - Section 3C + 4B: chỉ dành cho app (flutter/react-native/ios/android). Xóa A+B khi dùng cho app.
+
+  COMPONENT MAPPING (bắt buộc):
+  - Mọi component trong Component Inventory PHẢI được map với figma-components/{module}.md
+  - ✅ Matched     → dùng Code Component và Import Path từ catalog
+  - ⚠️ TODO        → đánh dấu [TODO — chưa implement]
+  - ❌ Chưa có     → đánh dấu [NEW — cần confirm với designer]
+
+  FIGMA LINKS (bắt buộc mỗi màn):
+  - Mỗi screen PHẢI có link Figma node-level (URL chứa ?node-id=...) — lấy bằng
+    right-click frame → "Copy link to selection". Đây là link AI đọc được qua Figma MCP.
+  - Link file trần (không có node-id) KHÔNG hợp lệ — AI không định vị được frame.
+  - Screen chưa có design → đánh dấu ❌ Missing; spec giữ Status "draft", chặn sign-off
+    và /generate-bdd cho tới khi đủ link.
+
+  SCREEN STATES (bắt buộc mỗi màn):
+  - Tối thiểu: default, loading, error
+  - Thêm "empty" nếu màn có thể hiển thị trạng thái không có dữ liệu
+  - Thêm "success" nếu action tạo ra trạng thái xác nhận riêng biệt
+-->
+
+---
+
+## Metadata
+
+| Field              | Value                                                         |
+|--------------------|---------------------------------------------------------------|
+| **Spec ID**        | {TICKET-ID}-DS-{platform}                                     |
+| **Version**        | 1.0                                                           |
+| **Status**         | draft / approved                                              |
+| **Platform**       | {web \| app \| app-ios \| app-android}                        |
+| **Module**         | {active_module}                                               |
+| **Service**        | {active_service}                                              |
+| **Domain**         | {domain}                                                      |
+| **Business PRD**   | [{TICKET-ID}](./{TICKET-ID}-slug.md)                          |
+| **Figma**          | {feature file link} ({linked}/{N} frames linked)             |
+| **Author**         | {PO name or "AI-assisted"}                                    |
+| **Created**        | {YYYY-MM-DD}                                                  |
+| **Updated**        | {YYYY-MM-DD}                                                  |
+
+---
+
+# 1. Screen Inventory
+
+| # | Screen Name | Entry Point | Figma Frame (node-level link) | Notes |
+|---|-------------|-------------|-------------------------------|-------|
+| 1 | {Screen 1}  | {how user arrives} | [Frame]({node-level url}) | |
+| 2 | {Screen 2}  | {entry point} | ❌ Missing — add node-id link | |
+
+---
+
+# 2. Screen Specs
+
+## Screen 1: {Screen Name}
+
+**Figma**: [{Frame name}]({figma_frame_url})
+
+### Layout
+
+{Grid / max-width / padding / spacing — reference design tokens where applicable}
+
+### Component Inventory
+
+| Component (Figma)      | Code Component | Import Path            | States                          | Notes   |
+|------------------------|----------------|------------------------|---------------------------------|---------|
+| {Figma/Button/Primary} | Button         | @/components/ui/Button | default, loading, disabled      |         |
+| {Figma/Input/Text}     | TextInput      | @/components/ui/Input  | default, focus, error, disabled |         |
+
+### Screen States
+
+| State     | Trigger                          | UI Behavior                                              |
+|-----------|----------------------------------|----------------------------------------------------------|
+| default   | Screen loaded, data available    | {Describe full rendered appearance}                      |
+| loading   | API call in flight               | {Skeleton / spinner position and style}                  |
+| error     | API failure / validation error   | {Toast / inline error / error screen + recovery CTA}     |
+| empty     | No data returned                 | {Illustration + CTA — e.g., "No items yet. Add one →"}   |
+| success   | Action completed (if applicable) | {Confirmation toast / navigation / visual change}        |
+
+### Actions & Navigation
+
+| Action          | Trigger                   | Result                                            |
+|-----------------|---------------------------|---------------------------------------------------|
+| {Action name}   | Tap/click {element}       | Navigate to {Screen N} / Open {Modal name}        |
+| {Back/Cancel}   | Back gesture / button     | Return to {previous screen} without saving        |
+
+---
+
+<!--  Repeat ## Screen N for each additional screen  -->
+
+---
+
+# 3. Interaction Patterns
+
+<!-- === WEB ONLY — delete this section for app === -->
+
+## A. Responsive Behavior  *(web)*
+
+| Breakpoint | Width      | Layout Changes                              |
+|------------|------------|---------------------------------------------|
+| Mobile     | < 768px    | {Single column, bottom nav, full-width CTA} |
+| Tablet     | 768–1279px | {2-col grid, sidebar collapsed}             |
+| Desktop    | ≥ 1280px   | {Full layout, max-width 1440px}             |
+
+## B. Hover / Focus / Keyboard  *(web)*
+
+| Element        | Hover                         | Focus                           | Keyboard      |
+|----------------|-------------------------------|---------------------------------|---------------|
+| Primary button | Background → {color.hover}    | Outline 2px {color.focus}       | Enter / Space |
+| Text input     | Border → {color.border.hover} | Border → {color.primary}        | Tab to focus  |
+
+<!-- === APP ONLY — delete sections A+B for app === -->
+
+## C. Gestures & Navigation  *(app)*
+
+| Gesture              | Screen / Element    | Behavior                                    |
+|----------------------|---------------------|---------------------------------------------|
+| Back gesture         | All screens         | {Return / show "Discard changes?" dialog}   |
+| Pull-to-refresh      | {Screen names}      | Refresh data, spinner at top                |
+| Swipe left on row    | {List item}         | Reveal {Delete / Archive} action            |
+
+### Navigation Stack  *(app)*
+
+```
+{e.g., BottomTab(Home) → ListPage → DetailPage → EditPage}
+```
+
+### Platform Conventions  *(app)*
+
+| Aspect           | iOS                                       | Android                             |
+|------------------|-------------------------------------------|-------------------------------------|
+| Navigation bar   | Back button top-left, title centered      | Up arrow, title left-aligned        |
+| Bottom sheet     | UISheetPresentation, grabber visible      | BottomSheet, drag handle            |
+| Dialog           | Actions right-aligned                     | Actions left-aligned                |
+
+---
+
+# 4. Platform Considerations
+
+<!-- === WEB ONLY === -->
+
+## A. Accessibility  *(web)*
+
+- [ ] All interactive elements reachable by Tab key — no keyboard traps
+- [ ] Focus trap inside modals
+- [ ] Icon-only buttons have `aria-label`
+- [ ] Dynamic content announces via `aria-live`
+- [ ] WCAG AA contrast: text ≥ 4.5:1, large text ≥ 3:1
+- [ ] Form inputs have visible labels (not placeholder-only)
+
+<!-- === APP ONLY === -->
+
+## B. Device & OS  *(app)*
+
+- [ ] Safe area insets applied (top + bottom) on all screens
+- [ ] Minimum touch target: 44×44pt (iOS) / 48×48dp (Android)
+- [ ] Tested on 375pt (iPhone SE) and 360dp (small Android)
+- [ ] Deep link: `{scheme}://{host}/{path}` → {screen name}
+- [ ] Permissions: {Camera / Location / Notification} — rationale copy TBD
+- [ ] Offline: {screen name} shows cached data + banner; {action} disabled with tooltip
+- [ ] Dark mode tested — no hardcoded colors
+
+---
+
+# 5. AC-UI — Design Acceptance Criteria
+
+> Reviewed and signed off by **PO + Designer** before BDD generation.
+> Complements business-level AC in [Business PRD](./{TICKET-ID}-slug.md).
+
+| ID     | Acceptance Criterion                                                     | Verified by     |
+|--------|--------------------------------------------------------------------------|-----------------|
+| AC-UI1 | All screens match approved Figma frames within design-system tolerances  | Designer        |
+| AC-UI2 | Loading state appears within 200ms of any API call initiation            | QA              |
+| AC-UI3 | All error messages are visible, descriptive, and include a recovery CTA  | PO              |
+| AC-UI4 | Empty states include illustration and call-to-action                     | PO + Designer   |
+| AC-UI5 | {Platform-specific criterion}                                            | QA              |
+
+---
+
+# Appendix
+
+## Figma Summary
+
+| Screen     | Figma Frame (node-level) | Link / Fetch Status            |
+|------------|--------------------------|--------------------------------|
+| {Screen 1} | [Link]({node-level url}) | ✅ Linked & fetched            |
+| {Screen 2} | —                        | ❌ Missing — no node-id link    |
+
+## Design Tokens Referenced
+
+| Token             | Value    | Used in                    |
+|-------------------|----------|----------------------------|
+| `color.primary`   | {#hex}   | Buttons, links             |
+| `spacing.md`      | {16px}   | Standard vertical gap      |
+
+## References
+
+- [{TICKET-ID}](./{TICKET-ID}-slug.md) — Business PRD
+
+## AI Assumptions
+
+- {Assumption — [AI DRAFT]}
+
+---
+
+## Changelog
+
+| Version | Date         | Changes         |
+|---------|--------------|-----------------|
+| 1.0     | {YYYY-MM-DD} | Initial version |

package/templates/feature.template

@@ -0,0 +1,259 @@
+# ============================================================
+# BDD Feature Template — KVLoyalty AI Native Pipeline (v2)
+# ============================================================
+# Instructions:
+#   1. Copy this file và rename: {TICKET_ID}-UC{N}-feature-name.feature
+#   2. Điền @trace metadata (required)
+#   3. Khai báo Context của UC (1 lần, đầu file)
+#   4. Tạo/cập nhật dataset YAML cùng domain: specs/features/{domain}.testdata.yaml
+#   5. Viết Scenario — mỗi SC PHẢI có dòng `# Side-effects:` ngay trên
+#   6. Đặt file ở: specs/features/{domain}/
+#   7. Chạy: /generate-code
+# ============================================================
+#
+# RULE VIẾT BDD BẮT BUỘC (xem bdd-writing-guide.md PART A + C):
+#   R1  Given/When/Then Semantics  — Given=state, When=action, Then=outcome (mỗi SC đủ G/W/T)
+#   R2  One Behavior Per Scenario  — 1 SC = 1 behavior; KHÔNG chain When-Then
+#   R3  Ubiquitous Language        — KHÔNG dùng UI selector / API name / tech term
+#   R4  Outside-in Naming          — Tên SC mô tả business outcome, KHÔNG có "click"/"(Case X)"/component name
+#   R5  Declarative over Imperative — Mô tả WHAT (intent business), KHÔNG HOW (UI mechanic)
+#   R6  Observable Outcomes Only   — Then assert outcome quan sát được, KHÔNG UI trung gian/internal state
+#   R7  Key Examples / Concrete    — Dùng concrete values, KHÔNG "hợp lệ" chung chung
+#   R8  Independence               — SC chạy độc lập, KHÔNG phụ thuộc state SC khác
+#   R9  Test Data Completeness     — Data table có đủ field external system để derive expected Then
+#   R10 Scope Boundary Explicit    — Cross-UC reference dùng wording navigation + Note comment
+# PROJECT COMPLIANCE (must-pass, fail review nếu thiếu):
+#   C.1 Wireframe Coverage         — Mọi component/action wireframe có ≥1 SC
+#   C.2 PRD Traceability           — Mọi AC/BR (kèm bullet) map về ≥1 SC
+#   C.3 Business Dictionary        — Dùng đúng term, đề xuất term mới qua DICTIONARY-SUGGESTION
+#   C.4 Banned Terms Compliance    — 0 banned term (auto-grep): SKU/Customer/JS SDK/Cửa hàng/...
+#   C.5 NHÓM Grouping Convention   — Scenarios gom theo CHỦ ĐỀ NGHIỆP VỤ (NHÓM N) — xem §NHÓM GROUPING CONVENTION dưới
+# ============================================================
+
+# --- TRACE METADATA (REQUIRED) ---
+# @trace.id: {TICKET_ID}-UC{N}
+# @trace.title: <Tên tính năng bằng tiếng Việt>
+# @trace.revision: 1
+# @trace.domain: <identity|loyalty|membership|messaging|store-management>
+# @trace.service: <KVLoyalty.Identity|KVLoyalty.Loyalty|...>
+# @trace.status: draft|review|approved
+# @trace.author: <tên tác giả>
+# @trace.created_at: <YYYY-MM-DD>
+# @trace.prd: <TICKET-ID hoặc để trống>
+# @trace.prd_version: <version PRD tại thời điểm viết — để drift-detector so sánh>
+# @trace.business_rules: <{TICKET_ID}-UC{N}-BR{M}, ...>
+# @trace.dataset: <{domain}.testdata.yaml — bắt buộc nếu BDD reference dataset>
+
+# === CONTEXT (áp dụng cho toàn Feature) ===
+# Actor:     <vai trò thực hiện hành động, vd: Consumer, Staff, System>
+# Screens:   <các màn liên quan, vd: Cart → Confirm Order → Order Detail>
+# Entities:  <entity nghiệp vụ, vd: Order, OrderItem, Consumer, Branch>
+# Pre-state: <state chung trước khi vào các scenario>
+
+# === SCOPE ===
+# In:  <những gì UC này cover>
+# Out: <những gì KHÔNG thuộc UC này — link sang UC khác / feature khác (R10)>
+
+# === BUSINESS DEFINITION (MANDATORY) ===
+# Quick reference các thuật ngữ dùng trong feature này. SoT chi tiết: business-dictionary.md
+# Mục đích: reader đọc 1 lần hiểu ngay khái niệm trước khi xem scenarios.
+#
+# <Term 1> (English mapping): <định nghĩa ngắn gọn, vd cấu trúc, scope>
+# <Term 2>: <định nghĩa>
+# ...
+#
+# === Test data convention (R9) ===
+# Khai báo default value khi data table không có cột tương ứng.
+# VD: "SC không khai báo cột customerOrdered → ngầm hiểu customerOrdered = 0 (chưa có khách đặt)"
+# VD: "SC không khai báo cột toggle → ngầm hiểu toggle = Hiện (default Ẩn/Hiện trạng thái)"
+#
+# === Popup/Modal Lifecycle (B.2.4 — bắt buộc nếu feature là popup/modal) ===
+# - Open trigger:   <khi nào popup hiển thị, vd: click menu sidebar>
+# - Close trigger:  <khi nào popup đóng, vd: F5 / click X / ESC / navigate away>
+# - Refresh model:  <data refresh khi nào, vd: mỗi lần open (NO CACHE) / persisted / polling>
+# - State reset:    <state nào reset khi đóng/mở lại, vd: pagination, expand, dropdown selection>
+
+# === DISPLAY LOGIC MATRIX (optional — bắt buộc nếu display logic phụ thuộc ≥2 dimension, B.1.7) ===
+# Enumerate full matrix N×M case + map mỗi case → SC.
+# Tên SC theo pattern: `<cấu trúc>: <outcome>` — KHÔNG dùng "(Case X)" suffix.
+# VD ma trận `{số thuộc tính: 0/1/≥2} × {số đơn vị tính: 0/1/≥2}` = 9 case:
+#
+# | # | Dim1 | Dim2 | Format hiển thị                              | SC   |
+# |---|------|------|----------------------------------------------|------|
+# | 1 | 0    | 0    | `Tên hàng`                                   | SC{} |
+# | 2 | 0    | 1    | `Tên hàng (đơn vị)`                          | SC{} |
+# | ... | ... | ...  | ...                                          | ...  |
+
+# === DICTIONARY REFERENCES (R3 + C.4) ===
+# Liệt kê các term từ business-dictionary.md mà feature này dùng → pointer cho reviewer auto-check.
+# Banned terms (xem business-dictionary.md § Banned Terms) MUST NOT appear: 0 match khi grep.
+#
+# Terms dùng trong feature này:
+# - <Term 1> (xem dictionary line {N})
+# - <Term 2> (xem dictionary line {M})
+# - ...
+
+Feature: <Tên tính năng bằng tiếng Việt>
+  Với vai trò là <vai trò>
+  Tôi muốn <hành động>
+  Để <lợi ích nghiệp vụ>
+
+  # --- DATASET REFERENCE CONVENTION ---
+  # Ưu tiên dùng ALIAS (tiếng Việt) thay vì ID kỹ thuật, để BDD dễ đọc.
+  # Backtick ID chỉ dùng khi cần precision (vd: assertion về mã đơn).
+  #
+  # Ví dụ:
+  #   ✅ Given đơn hàng draft "Đơn COD giao hàng — 2× áo + 1× quần, total 650K"
+  #   ✅ Then đơn được gán mã `ZMA{id}` nhận từ Retail
+  #   ❌ Given đơn hàng draft là `ORD_COD_DRAFT_001`   ← khó đọc, hạn chế
+
+  Background:
+    Given <điều kiện tiên quyết chung — dùng alias từ dataset>
+    # Ví dụ: Given consumer "Khách mới đã cấp quyền Zalo" ở màn "Xác nhận đơn hàng"
+    #        của gian hàng "Cửa hàng Thời Trang (đang kích hoạt)"
+
+  # ============================================================
+  # § NHÓM GROUPING CONVENTION (C.5 — bắt buộc cho mọi feature ≥3 SCs)
+  # ============================================================
+  # Mục đích: organize scenarios theo CHỦ ĐỀ NGHIỆP VỤ để dễ navigate + scope-awareness, KHÔNG
+  # theo phân loại happy/negative/edge (deprecated section markers HAPPY-PATH / NEGATIVE-CASE / EDGE-CASE).
+  #
+  # Quy tắc:
+  #   1. **Gom theo chủ đề business** — mỗi NHÓM = 1 business theme (flow / state / behavior subset).
+  #      ✅ NHÓM 1: Khởi tạo gian hàng thành công với dữ liệu mặc định (BR1, BR2)
+  #      ✅ NHÓM 2: Resume khi onboarding bị gián đoạn (BR1 resume)
+  #      ✅ NHÓM 3: Xử lý lỗi khởi tạo (BR3)
+  #      ❌ NHÓM 1: HAPPY-PATH         ← chia theo loại path, không phải chủ đề
+  #      ❌ NHÓM 1: COD scenarios      ← UI feature, không phải business theme
+  #
+  #   2. **Mỗi NHÓM có thể chứa cả @happy + @edge + @negative SCs cùng chủ đề** — KHÔNG tách happy/edge ra 2 NHÓM riêng.
+  #      Ví dụ: NHÓM "Xử lý lỗi khi khởi tạo" chứa SC happy retry + SC edge X close + SC negative no retry.
+  #      Tag taxonomy (@happy/@edge/@cross-system per B.2.3) áp dụng ở SC level — KHÔNG ở NHÓM level.
+  #
+  #   3. **Format NHÓM header** (3 dòng comment box):
+  #         # ==========================================================
+  #         # NHÓM N: <Chủ đề> (<BR refs nếu áp dụng>)
+  #         # ==========================================================
+  #      Indent 2 spaces (cùng level với Background + Scenario).
+  #
+  #   4. **Đánh số NHÓM tuần tự** từ 1 → N. Không skip số. Reorder NHÓM được — KHÔNG ảnh hưởng SC IDs.
+  #
+  #   5. **SC trong NHÓM KHÔNG cần theo thứ tự ID** — VD NHÓM 2 có thể chứa SC8, SC4, SC11 nếu cùng chủ đề.
+  #      SC IDs tuần tự theo lifecycle (skill §3.4), KHÔNG theo NHÓM ordering.
+  #
+  #   6. **Khi nào skip NHÓM**: feature có <3 SCs → có thể bỏ NHÓM headers (không value to organize so few).
+  #      Đơn giản đặt SCs nối tiếp sau Background. Feature ≥3 SCs → BẮT BUỘC NHÓM.
+  #
+  # Pattern thường gặp (gợi ý theme — tuỳ chỉnh per UC):
+  #   - "Khởi tạo / Lưu thành công — các tổ hợp data hợp lệ" (gom happy + alternative)
+  #   - "Validation / Chặn lưu khi không hợp lệ" (gom negative + edge validation)
+  #   - "Xử lý lỗi — API fail / system error" (gom negative + recovery)
+  #   - "Hủy thay đổi / Đóng modal không lưu" (gom edge UX)
+  #   - "Hành vi popup / dialog — multi-select / persist / boundary" (gom edge UX behavior)
+  #   - "Hiệu ứng cross-system / Consumer view" (gom @cross-system SCs)
+  #   - "Idempotency & Concurrency" (gom edge concurrency)
+  #   - "State transition / Recovery completion" (gom @cross-UC behavior chains)
+  #
+  # Ví dụ NHÓM structure cho UC có 9 SCs (LOYAL-32-UC1 reference):
+  #   NHÓM 1: Lưu cấu hình thành công — các tổ hợp PTTT hợp lệ (BR1, BR2)    → SC1, SC2, SC3, SC4
+  #   NHÓM 2: Chặn lưu khi cấu hình không hợp lệ (BR1, BR2) + lỗi hệ thống   → SC5, SC6, SC7
+  #   NHÓM 3: Hủy thay đổi — đóng Modal không lưu                            → SC8
+  #   NHÓM 4: Initial State — Modal phản ánh cấu hình hiện tại               → SC10
+
+  # ==========================================================
+  # NHÓM 1: <Chủ đề business 1> (<BR refs nếu cần>)
+  # ==========================================================
+
+  # Side-effects: <liệt kê NGẮN GỌN các hậu quả Then phải verify — 1 dòng>
+  # @trace.scenario: {TICKET_ID}-UC{N}-SC1
+  # @trace.sc_version: 1.0
+  # @trace.business_rules: {TICKET_ID}-UC{N}-BR{M}
+  @happy
+
+  Scenario: <Mô tả luồng chính — dùng động từ CHÍNH XÁC (tạo/nhận/gán/đồng bộ)>
+    Given <state đầu vào — dùng alias từ dataset, vd: "Đơn COD giao hàng — 2× áo + 1× quần">
+    When <hành động duy nhất>
+    Then <kết quả chính — dùng backtick ID khi cần precision, vd: mã `ZMA{id}`>
+      And <side-effect 1 đã khai báo ở header>
+      And <side-effect 2 đã khai báo ở header>
+      # ... đủ với danh sách Side-effects ở trên (Rule R2)
+
+  # Side-effects: <...>
+  # @trace.scenario: {TICKET_ID}-UC{N}-SC2
+  # @trace.sc_version: 1.0
+  # @trace.business_rules: {TICKET_ID}-UC{N}-BR{M}
+  @happy @alternative
+
+  Scenario: <Cùng chủ đề NHÓM 1 nhưng path khác — vd enum value khác (Rule R4 enum symmetry)>
+    Given <state đầu vào>
+    When <hành động>
+    Then <kết quả>
+
+  # ==========================================================
+  # NHÓM 2: <Chủ đề business 2 — VD: Xử lý lỗi / Validation> (<BR refs>)
+  # ==========================================================
+
+  # Side-effects: <...>
+  # @trace.scenario: {TICKET_ID}-UC{N}-SC3
+  # @trace.sc_version: 1.0
+  # @trace.business_rules: {TICKET_ID}-UC{N}-BR{M}
+  @edge
+
+  Scenario: <Tình huống biên / lỗi cùng chủ đề NHÓM 2>
+    Given <state đầu vào>
+    When <hành động>
+    Then <xử lý lỗi mong đợi>
+
+  # ==========================================================
+  # NHÓM 3: <Chủ đề business 3 — VD: Cross-system / Hiệu ứng downstream> (<BR refs>)
+  # ==========================================================
+
+  # Side-effects: <...>
+  # @trace.scenario: {TICKET_ID}-UC{N}-SC4
+  # @trace.sc_version: 1.0
+  # @trace.business_rules: {TICKET_ID}-UC{N}-BR{M}
+  @happy @cross-system
+
+  Scenario: <Scenario span ≥2 service hoặc hiệu ứng đồng bộ cross-UC>
+    Given <state đầu vào>
+    When <hành động>
+    Then <kết quả tại service A>
+      And <kết quả đồng bộ sang service B>
+
+# === TECHNICAL HINTS (optional, giúp AI gen code chính xác hơn) ===
+# Dependencies: <UC/service phụ thuộc, vd: LOYAL-28 upstream>
+# Entities: <Entity1, Entity2>
+# Events: <EventName> (publish to <topic>)
+# Cache: <cache invalidation notes>
+# Validation: <validation rules>
+
+# === PRD COVERAGE (C.1 + C.2 — wireframe action + AC/BR checklist) ===
+# AC mapping:
+#   AC1 (...) → SC1, SC2
+#   AC2 (...) → SC3
+# BR mapping (mỗi bullet trong BR PHẢI có ≥1 SC — C.2):
+#   BR1 (...) → SC1
+#   BR2 (...) → SC1, SC2
+# Wireframe mapping (mọi component/action có ≥1 SC — C.1):
+#   Screen "<tên màn>":
+#     [x] Click "<button A>"        → SC1
+#     [x] Click "<button B>"        → SC2
+#     [ ] Click "<" back             → MISSING ← BLOCK MERGE
+# Display Logic Matrix mapping (nếu áp dụng — B.1.7):
+#   Case 1 (...) → SC{N}
+#   Case 2 (...) → SC{N}
+# User Flow: <path name> → SC1, SC2, SC3
+
+# === BUSINESS RULES ===
+# {TICKET_ID}-UC{N}-BR1: <mô tả rule>
+# {TICKET_ID}-UC{N}-BR2: <mô tả rule>
+
+# === PRE-MERGE CHECKLIST (auto-verify) ===
+# - [ ] Mọi SC có Side-effects + @trace.scenario + @trace.sc_version + @trace.ac + @trace.business_rules
+# - [ ] Coverage Matrix có 0 dòng `[ ]` MISSING (C.1)
+# - [ ] Mọi AC/BR (kèm từng bullet) map về ≥1 SC (C.2)
+# - [ ] CI grep banned terms = 0 match (C.4) — xem business-dictionary.md § Banned Terms
+# - [ ] Nếu là popup/modal: Popup/Modal Lifecycle khai báo trong BUSINESS DEFINITION (B.2.4)
+# - [ ] Nếu display logic ≥2 dimension: Display Logic Matrix enumerated (B.1.7)
+# - [ ] Feature ≥3 SCs có NHÓM grouping theo chủ đề business (C.5) — KHÔNG dùng section markers cũ HAPPY-PATH/NEGATIVE-CASE/EDGE-CASE
+# - [ ] /review-context score ≥90 (project gate)

package/templates/platform-guide.template.md

@@ -0,0 +1,145 @@
+# Platform Guide — {{SERVICE_NAME}}
+
+> This guide provides context that Claude uses when working in THIS service/repository.
+> Keep it concise and factual. Update when the architecture or domain model changes.
+> Reference: CLAUDE.md for project-wide standards. This file covers service-specific context.
+
+---
+
+# §1. Service Overview
+
+**Service name**: {{SERVICE_NAME}}
+**Purpose**: {{ONE_SENTENCE_PURPOSE}}
+**Bounded context**: {{BOUNDED_CONTEXT}}  # e.g., "Owns all order lifecycle logic. Does NOT own payments or inventory."
+**Team**: {{TEAM_NAME}}
+**Repository**: {{REPO_URL}}
+
+Primary responsibilities:
+- {{RESPONSIBILITY_1}}
+- {{RESPONSIBILITY_2}}
+- {{RESPONSIBILITY_3}}
+
+This service does NOT handle:
+- {{OUT_OF_SCOPE_1}}  # e.g., "Payment processing → see payment-service"
+- {{OUT_OF_SCOPE_2}}
+
+---
+
+# §2. Domain Model
+
+Key entities and their relationships:
+
+```
+{{ENTITY_1}} (aggregate root)
+  ├── {{CHILD_ENTITY_1}} (value object / child entity)
+  └── {{CHILD_ENTITY_2}}
+
+{{ENTITY_2}}
+  └── references {{ENTITY_1}} by ID
+```
+
+**{{ENTITY_1}}**:
+- Key fields: {{KEY_FIELDS}}
+- Status lifecycle: {{STATUS_1}} → {{STATUS_2}} → {{STATUS_3}}
+- Business rules: {{KEY_RULE_1}}
+
+**{{ENTITY_2}}**:
+- Key fields: {{KEY_FIELDS}}
+- Relationships: {{RELATIONSHIP_DESCRIPTION}}
+
+---
+
+# §3. Common Patterns
+
+Patterns specific to this service (supplement the project-wide standards in CLAUDE.md):
+
+## {{PATTERN_NAME_1}}
+```
+// When to use: {{USE_CASE}}
+// Example:
+{{CODE_EXAMPLE}}
+```
+
+## {{PATTERN_NAME_2}}
+```
+// When to use: {{USE_CASE}}
+// Example:
+{{CODE_EXAMPLE}}
+```
+
+---
+
+# §4. Integration Points
+
+## Upstream Dependencies (this service calls these)
+
+| Service / System | What we call | Protocol | Auth |
+|------------------|--------------|----------|------|
+| {{UPSTREAM_1}}   | {{WHAT}}     | REST/gRPC/Event | {{AUTH_METHOD}} |
+| {{UPSTREAM_2}}   | {{WHAT}}     | REST/gRPC/Event | {{AUTH_METHOD}} |
+
+## Downstream Consumers (these services call us or consume our events)
+
+| Consumer | What they use | Protocol |
+|----------|---------------|----------|
+| {{DOWNSTREAM_1}} | {{WHAT}} | REST/Event |
+| {{DOWNSTREAM_2}} | {{WHAT}} | REST/Event |
+
+## Events Produced
+
+| Event name | Trigger | Payload summary |
+|------------|---------|-----------------|
+| {{EVENT_1}} | {{WHEN}} | {{PAYLOAD_FIELDS}} |
+| {{EVENT_2}} | {{WHEN}} | {{PAYLOAD_FIELDS}} |
+
+## Events Consumed
+
+| Event name | From service | What we do with it |
+|------------|-------------|-------------------|
+| {{EVENT_1}} | {{SOURCE}} | {{HANDLER_ACTION}} |
+
+---
+
+# §5. Known Constraints
+
+## Performance Constraints
+- {{PERF_CONSTRAINT_1}}  # e.g., "Order list endpoint must respond < 200ms for up to 1000 orders"
+- {{PERF_CONSTRAINT_2}}
+
+## Business Rule Constraints
+- {{BUSINESS_CONSTRAINT_1}}  # e.g., "Cannot cancel an order after it has been shipped"
+- {{BUSINESS_CONSTRAINT_2}}
+
+## External Dependencies
+- {{EXTERNAL_DEP_1}}  # e.g., "Requires inventory-service to be available for order creation"
+- {{EXTERNAL_DEP_2}}
+
+## Known Technical Debt
+- {{TECH_DEBT_1}}  # e.g., "OrderItem.price is duplicated from catalog — sync via nightly job"
+
+---
+
+# §6. Directory Structure
+
+```
+{{SERVICE_ROOT}}/
+├── {{SOURCE_DIR}}/              # Main source code
+│   ├── {{LAYER_1}}/             # e.g., controller/ or handler/
+│   │   └── {{EXAMPLE_FILE}}
+│   ├── {{LAYER_2}}/             # e.g., service/ or usecase/
+│   │   └── {{EXAMPLE_FILE}}
+│   ├── {{LAYER_3}}/             # e.g., repository/ or repo/
+│   │   └── {{EXAMPLE_FILE}}
+│   └── {{LAYER_4}}/             # e.g., model/ or domain/
+│       └── {{EXAMPLE_FILE}}
+├── {{TEST_DIR}}/                # Tests mirroring src structure
+├── specs/                       # BDD feature files
+│   └── bdd/
+│       └── {{DOMAIN}}/
+│           └── {{UC-ID}}-{{slug}}.feature
+└── {{CONFIG_FILE}}              # e.g., application.yaml / appsettings.json
+```
+
+**Key conventions for this repo:**
+- {{CONVENTION_1}}  # e.g., "All DTOs are in the api/ package, not mixed with domain models"
+- {{CONVENTION_2}}  # e.g., "Integration tests are in src/test/java/.../integration/ with @Tag(\"integration\")"