@educa-corp/sdd-framework 0.2.4 → 0.2.5

package/commands/generate-architecture.tmpl

@@ -0,0 +1,194 @@
+# /generate-architecture — Sinh / làm mới Architecture Context (SSOT)
+
+> **Mô hình phạm vi:** MỘT `architecture.md` cho mỗi codebase — nguồn chân lý (SSOT)
+> cross-cutting cho kiến trúc, dùng cho cả AI code-gen lẫn ops. Lệnh **thu thập từ mọi
+> nguồn sẵn có (config + tài liệu + code) → phỏng vấn lấp chỗ trống → draft → bàn giao
+> cho người verify**. Tách khỏi `/setup-ai-first` để SA chạy lại nhiều lần (refresh /
+> điền dần). Nó KHÔNG tự ký duyệt — con người là trust-gate.
+>
+> **Triết lý điền:** ưu tiên **hút cái đã biết**, chỉ **hỏi cái chưa biết**. SA không phải
+> điền tay 140 ô — chỉ trả lời vài câu dễ hiểu về phần chưa nguồn nào trả lời được.
+>
+> **Khác `/generate-tech-docs`:** tech-docs là thiết kế **per-PRD/feature**; lệnh này mô tả
+> **kiến trúc toàn hệ thống dùng chung**. Chi tiết per-repo (thư mục, namespace) vẫn ở
+> `.ai-project-guide.md` / CLAUDE.md của từng repo — lệnh này chỉ lo phần cross-cutting.
+
+## Gate
+{{include:steps/gate.md}}
+
+*Với lệnh này — **bỏ qua Gate Bước 1** (không có input feature-file). `$ARGUMENTS` là **tuỳ chọn**, có thể gồm:
+- **service path** (chế độ umbrella, vd `user-service`) → target là `architecture.md` của service đó, scan giới hạn trong `{service}/`.
+- `--from=<path/glob,...>` → danh sách **tài liệu có sẵn** để hút nội dung (README, wiki, ADR, doc thiết kế cũ). Vd `--from=docs/**/*.md,README.md`.
+- `--section=<slug>` → chỉ lấp/refresh **đúng một mục** (điền dần). Danh sách slug ở Bước 5.
+- `--interview` → ép chạy phỏng vấn kể cả brownfield.
+Vẫn chạy Bước 0-B (model check) và Context Loader.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Bước 1 — Phân giải target, chế độ & tham số
+
+1. **Target file:**
+   - Mặc định → `{paths.specs_dir}/architecture.md` (thường `specs/architecture.md`). Umbrella: context-loader đã trỏ `specs_dir`/`service_root` về service active → target nằm cạnh code service.
+   - `$ARGUMENTS` có **service path** → `target = {service}/specs/architecture.md`, scan giới hạn trong `{service}/`.
+   - **Umbrella mà không truyền service path** → DỪNG, hỏi: *"Umbrella không có một stack đơn. Chạy `/generate-architecture {service-path}` cho từng service."*
+
+2. **Parse cờ:** `--from` (danh sách nguồn tài liệu), `--section=<slug>` (chế độ 1-mục → nhảy Bước 5), `--interview` (ép phỏng vấn).
+
+3. **Chế độ code:** brownfield (có build/manifest: `pom.xml`/`*.csproj`/`package.json`/`go.mod`/`pubspec.yaml`/`build.gradle`/`Cargo.toml`) vs greenfield (không có code để scan).
+
+4. **File đã tồn tại?**
+   - Chưa → tạo mới.
+   - `verified_by: AI-draft` (hoặc trống) → được regenerate (xác nhận: *"architecture.md đang là AI-draft chưa verify — regenerate đè lên? (Y/N)"*).
+   - `verified_by: {người thật}` → **KHÔNG đè** → nhảy **Bước 6** (refresh có kiểm soát).
+
+---
+
+## Bước 2 — Thu thập từ mọi nguồn (điền cái đã biết)
+
+Gom dữ kiện cho từng section/field theo **thứ tự ưu tiên**. Với mỗi giá trị điền được, ghi lại **nguồn** + **độ chắc chắn** (chắc / cần xác nhận). KHÔNG bịa ngoài bằng chứng.
+
+**Thứ tự nguồn:**
+
+1. **Config dự án** (luôn có) — đọc `project-context.yaml` + `CLAUDE.md`:
+   | Field template | Nguồn |
+   |---|---|
+   | Tech Stack (language/framework/db/build/test) | `project-context.yaml → tech_stack`, `conventions` |
+   | Các tầng + rules kiến trúc | `CLAUDE.md §2` |
+   | Quy ước đặt tên, response wrapper, error handling | `CLAUDE.md §3, §5` |
+   | Quy ước Git/DB nếu có | `CLAUDE.md §6, §7` |
+
+2. **Tài liệu có sẵn** (nếu có `--from`, hoặc hỏi 1 lần: *"Có tài liệu kiến trúc/thiết kế sẵn không? Trỏ path — README, wiki, ADR, doc cũ. Enter để bỏ qua."*) — đọc từng tài liệu, rút fact và **map vào section/field** tương ứng của template. Ghi chú nguồn theo dạng `<!-- nguồn: {đường-dẫn} -->` ở section được điền.
+
+3. **Scan code** (chỉ brownfield) — quét có mục tiêu:
+   | Nguồn quét | Section suy ra |
+   |---|---|
+   | build/manifest (dependencies) | **Tech Stack** |
+   | cây thư mục + tên project/layer (`*.Domain`/`*.Application`… hoặc `controller/service/repository`) | **Các tầng** + chiều phụ thuộc |
+   | DI registration (`Program.cs`/`Startup`/`*ServiceExtensions`) | **Đăng ký DI**, danh mục service/repo, **Ranh giới truy cập dữ liệu** |
+   | middleware / filter / interceptor | **Luồng Xác thực**, correlation-id, gateway |
+   | `appsettings*`/`application.yml`/`.env.example` | **Caching** (TTL), **Event Bus/Sharding**, **Feature Toggle** (chỉ ghi *tên* cấu hình, KHÔNG copy secret) |
+   | response wrapper / base controller / global exception handler | **Response API chuẩn** |
+   | entity/model (DbSet/@Entity) vs POCO/DTO từ API client | **Phân loại Entity**, **Identity Resolution** (nếu có external-id) |
+   | CI (`.github/workflows`, `Jenkinsfile`…), Dockerfile, k8s | **Triển khai & DevOps** |
+
+**Xử lý xung đột:** nếu ≥2 nguồn nói khác nhau (vd doc cũ "Redis TTL 10m" nhưng config "5m") → **KHÔNG tự chọn**. Đưa vào danh sách cần hỏi (Bước 3) hoặc gắn ⚠️ vào draft. Quy tắc chung: fact máy móc (tech stack, TTL, DI) ưu tiên **code/config**; phần ý đồ/narrative (data flow, rules, NFR) ưu tiên **tài liệu**.
+
+**Sản phẩm Bước 2:** với mỗi section — trạng thái `đã-điền` (kèm nguồn) / `còn-trống` / `xung-đột`. Đây là đầu vào cho phỏng vấn (chỉ hỏi phần còn-trống/xung-đột).
+
+---
+
+## Bước 3 — Phỏng vấn thích ứng (chỉ hỏi cái chưa biết)
+
+### 3.0 — Báo cáo coverage trước khi hỏi
+
+```
+Đã điền từ config/tài liệu/code : {X}/{tổng} mục
+Còn cần hỏi                     : §{A}, §{B}, §{C}
+Xung đột cần xác nhận           : §{D} (nguồn 1 nói …, nguồn 2 nói …)
+```
+
+### 3.1 — Cách đặt câu hỏi (BẮT BUỘC: dễ hiểu, không thuật ngữ trần)
+
+Mỗi câu là một **thẻ giải thích**: tên mục + 1–2 câu nghĩa + ví dụ cụ thể + Có/Không nghĩa là gì. Ví dụ mẫu:
+```
+【 Hệ thống có Multi-tenant không? 】
+Một hệ thống phục vụ NHIỀU khách hàng/chi nhánh, dữ liệu mỗi bên tách riêng,
+không bên nào thấy của bên kia (vd: app SaaS bán hàng — mỗi shop chỉ thấy đơn của mình).
+  • CÓ    → phục vụ nhiều bên, cần cách ly dữ liệu
+  • KHÔNG → chỉ phục vụ một tổ chức duy nhất
+```
+Áp dụng phong cách này cho MỌI câu. Tuyệt đối không hỏi kiểu "Multi-tenant? [Y/N]" trơ trọi.
+
+### 3.2 — Pha 1: Sàng lọc (quyết mục conditional nào bật)
+
+Hỏi các thẻ dưới đây, **BỎ câu nào đã có đáp án** từ Bước 2 (config/tài liệu/code). Mỗi thẻ quyết định (các) section:
+
+| Thẻ hỏi (diễn đạt dễ hiểu như 3.1) | Bật section |
+|---|---|
+| Kiểu kiến trúc? (Layered/Clean/Hexagonal/Component-based) | §Các tầng (chọn sơ đồ mẫu) |
+| Backend có expose REST API cho client gọi? | §Response API + §Quy ước API |
+| Multi-tenant (nhiều khách hàng, dữ liệu tách riêng)? | §Multi-tenant |
+| Có tích hợp hệ ngoài có ID riêng (partner/hệ cũ)? | §Phân loại Entity + §Identity Resolution + §Nguồn dữ liệu + §Ranh giới truy cập dữ liệu |
+| Có xử lý bất đồng bộ qua message bus (Kafka/RabbitMQ…)? | §Event Bus |
+| Dữ liệu chia nhiều DB / sharding? | §Sharding |
+| Có bật/tắt tính năng bằng feature flag lúc chạy? | §Feature Toggle |
+| Có API Gateway đứng trước các service? | §API Gateway |
+| Có cache riêng (Redis…) để tăng tốc? | §Caching |
+| Nhiều repo / nhiều service? | §Repos + §Trách nhiệm service + §Giao tiếp giữa service |
+
+Trả lời KHÔNG → section tương ứng để **STUB** (không hỏi thêm về nó nữa).
+
+### 3.3 — Pha 2: Đào sâu (drill loop, tới khi ĐỦ-ĐỂ-VIẾT)
+
+Với **mỗi mục được bật (CÓ)** mà nội dung còn thiếu để viết đúng, hỏi tiếp bằng thẻ dễ hiểu — **lặp tới khi đủ**. Ví dụ sau khi CÓ multi-tenant:
+```
+Bạn nói CÓ multi-tenant. Để viết đúng phần này, cho hỏi thêm:
+1. Mỗi bản ghi phân biệt khách hàng bằng cột nào? (vd TenantId, MerchantId, OrgId)
+2. Cách ly kiểu gì? [tự động lọc mọi truy vấn / mỗi khách một DB riêng / khác]
+(Chưa rõ thì gõ "để sau" — mục này để trống, bổ sung sau bằng --section=multi-tenant)
+```
+
+**Ràng buộc loop (BẮT BUỘC — tránh lan man/phiền):**
+- **Chỉ đào sâu trong phạm vi mục SA đã trả lời CÓ.** KHÔNG tự mở chủ đề mới. Mục SA nói KHÔNG → không bao giờ hỏi lại.
+- **Chỉ hỏi khi mơ hồ THỰC SỰ cản việc viết đúng** mục đó — không hỏi chi tiết "cho vui".
+- **Gộp 2–3 câu/lượt** theo cụm, không hỏi lắt nhắt từng cái.
+- **Luôn có lối thoát:** SA gõ "để sau / chưa rõ" → mục đó thành **STUB**, dừng đào sâu ngay. → Loop chắc chắn kết thúc.
+- Follow-up cũng **skip-if-answered**: nếu tài liệu/config/code đã trả lời thì không hỏi.
+
+**Kết thúc phỏng vấn khi:** mọi mục CÓ đều (a) đủ để viết, hoặc (b) SA chủ động hoãn (→ stub). Xung đột ở 3.0 cũng được hỏi xác nhận trong pha này.
+
+---
+
+## Bước 4 — Lắp ráp theo tier
+
+Nguồn khung: `.agent/templates/architecture.template.md` (đọc marker `<!-- tier: core|conditional|ops -->` mỗi mục).
+
+1. **core** → **luôn viết**, pre-fill từ Bước 2 + đáp án. Field nào vẫn chưa rõ → giữ `{{PLACEHOLDER}}` + comment (không stub cả mục core).
+2. **conditional** → nếu mục được bật (Bước 2 có nguồn HOẶC phỏng vấn CÓ) → viết đầy đủ; ngược lại → **STUB**:
+   ```
+   ## {Tên mục}  <!-- tier: conditional --> <!-- status: stub -->
+   > ⏳ Chưa tài liệu hoá. Chạy `/generate-architecture --section={slug}` khi cần, hoặc điền tay.
+   ```
+3. **ops** → mặc định **STUB** (không ép điền upfront). Chỉ điền nếu Bước 2 đã có nguồn rõ ràng (vd CI config, logging setup) — khi đó điền luôn, bỏ stub.
+4. **Provenance:** mỗi section điền từ tài liệu ngoài → chèn `<!-- nguồn: {path} -->`. Section có xung đột chưa giải → chèn `<!-- ⚠️ xung đột: … -->`.
+5. **Frontmatter — trust-gate:** `last_verified: {hôm nay}`; `verified_by: AI-draft` (khi có bất kỳ nội dung do AI hút/suy) hoặc `{{AUTHOR}}` (greenfield thuần tay chưa có gì).
+6. Nhất quán thuật ngữ với `business-dictionary.md` + tên entity `core-entities.md`; KHÔNG dùng banned term.
+7. Ghi ra `target`.
+
+---
+
+## Bước 5 — Chế độ `--section=<slug>` (điền dần một mục)
+
+Khi `$ARGUMENTS` có `--section=<slug>`: bỏ qua lắp ráp toàn bộ, **chỉ** lấp/refresh đúng mục đó.
+1. Định vị mục theo bảng slug bên dưới trong `target`.
+2. Chạy thu thập (Bước 2) + phỏng vấn đào sâu (Bước 3.3) **giới hạn cho mục này**.
+3. Thay khối stub bằng nội dung đã điền, gỡ `<!-- status: stub -->`. Nếu mục đã có nội dung → refresh theo chênh lệch, giữ chỉnh tay của người.
+4. Cập nhật `last_verified`; nếu file đang `verified_by: {người}` → chỉ đề xuất diff (không tự đè).
+
+**Bảng slug ↔ mục:** `tech-stack` · `layers` · `naming` · `api-response` · `api-conventions` · `database` (core) — `data-flow` · `repositories` · `entity-classification` · `data-access` · `service-responsibilities` · `di` · `multi-tenant` · `identity-resolution` · `api-gateway` · `caching` · `event-bus` · `sharding` · `feature-toggle` · `auth` (conditional) — `observability` · `deployment` · `testing` · `nfr` (ops).
+
+---
+
+## Bước 6 — Refresh có kiểm soát (khi file đã verify bởi người)
+
+Nếu Bước 1.4 xác định `verified_by: {người thật}`:
+- KHÔNG ghi đè. Chạy lại thu thập (Bước 2) và **so sánh** với nội dung hiện tại.
+- Xuất **danh sách chênh lệch** (drift): mục nào trong code/config/tài liệu đã khác doc.
+- Với mỗi drift, đề xuất câu chữ cập nhật để SA tự áp; KHÔNG tự đổi `verified_by`.
+
+---
+
+## Bước 7 — Bàn giao cho người verify
+
+> Nếu frontmatter ghi `verified_by: AI-draft`:
+> 1. Tech Lead/Architect **duyệt từng section**, sửa chỗ AI đoán sai (đối chiếu `<!-- nguồn: … -->` và `<!-- ⚠️ xung đột -->`).
+> 2. Điền nốt `{{PLACEHOLDER}}` còn lại; lấp các mục STUB cần thiết bằng `--section=<slug>`.
+> 3. Đổi `verified_by: AI-draft` → **tên bạn**, cập nhật `last_verified`. Commit.
+>
+> Chỉ khi `verified_by` là người thật, `/generate-tech-docs` (Bước 0.5 [ARCH]) mới coi doc là **ràng buộc kiến trúc chính thức**. Còn `AI-draft` thì bị gắn ⚠️ và ưu tiên CLAUDE.md/BDD khi mâu thuẫn.
+
+## Output
+{{include:steps/report-footer.md}}

package/commands/generate-code.md

@@ -443,6 +443,8 @@ Lệnh này giới hạn nghiêm ngặt trong **một file feature** được tr
 3. CLAUDE.md §architecture + §coding_standards
 4. **(chỉ FE/App)** Design Spec — nạp qua **Guard** bên dưới (gate approved/độ-tươi + sanity), là nguồn của màn hình, component inventory, và link Figma frame từng-màn.
 
+> **Phạm vi vét nguồn (SRC-CHAIN):** khi một giá trị còn thiếu ở nguồn chính, được phép đọc thêm các artifact **cùng feature-package** `{paths.specs_dir}/{domain}/{prd-slug}/` — PRD `{TICKET-ID}-{prd-slug}.md`, các `.feature` khác (system/web/app), design-spec, tech-doc anh em — cùng `core-entities.md`/`business-dictionary.md`. Đọc **theo nhu cầu** để phân giải giá trị trước khi hỏi người (xem §Quy tắc nguồn giá trị).
+
 ---
 
 ## Guard — BDD & Design Spec đã sẵn sàng chưa *(cảnh báo MỀM — đồng bộ generate-bdd)*
@@ -775,7 +777,18 @@ DTOs → Entity/Model → Repository → Service interface → Service impl →
 
 > **Quy tắc entry-point:** `@trace.implements` phải xuất hiện ở **layer entry-point** như định nghĩa trong `CLAUDE.md §2`. Với REST API → Controller. Với module event-driven → event handler / consumer class. Với context-engineering → hàm orchestration prompt. Không bao giờ chỉ đặt ở layer trong.
 
-> **Quy tắc nguồn giá trị (chống hard-code):** MỌI giá trị cụ thể (endpoint path, error code, tên field/DTO, enum, limit/timeout, header) phải lấy từ **nguồn đã chốt** — tech-doc §4 (contract) · `core-entities.md` (enum/field) · config/env — **KHÔNG bịa inline**. Nếu một hằng số nghiệp vụ lặp lại hoặc mang ý nghĩa (retry count, ngưỡng, key) → **đặt tên hằng số** (constant/config), không rải magic number/string trong code. Không có nguồn cho một giá trị → đây là GAP: dừng và hỏi, đừng chế bừa (đồng bộ Cổng 2 của generate-tech-docs). *(DS3 đã đảm bảo có §4 contract trước khi tới đây với BE.)*
+> **Quy tắc nguồn giá trị (chống hard-code):** MỌI giá trị cụ thể (endpoint path, error code, tên field/DTO, enum, limit/timeout, header) phải lấy từ **nguồn đã chốt** — **KHÔNG bịa inline**. Nếu một hằng số nghiệp vụ lặp lại hoặc mang ý nghĩa (retry count, ngưỡng, key) → **đặt tên hằng số** (constant/config), không rải magic number/string trong code.
+>
+> **VÉT CẠN NGUỒN TRƯỚC KHI HỎI (SRC-CHAIN) — bắt buộc.** Khi một giá trị chưa thấy ở nguồn chính, PHẢI quét lần lượt các nguồn đã có trong context/spec-package theo thứ tự sau, **dừng ngay khi tìm thấy** (skip-if-answered), KHÔNG hỏi người ngay:
+> 1. Tech-doc gộp §4 (contract: §4.1 endpoint · §4.2 request/response · §4.3 error · §4.5.4 client integration)
+> 2. `core-entities.md` (tên field / type / enum) · `business-dictionary.md` (thuật ngữ chuẩn)
+> 3. PRD của UC (nhất là Appendix "Existing API Contract" khi `API Source: existing`, và metadata)
+> 4. Design-spec (FE/App: field/label/state màn hình)
+> 5. System/platform BDD — mệnh đề `Then` (behavior + giá trị fixture)
+> 6. Code/adapter đã sinh ở lần chạy trước (vd mock adapter `--phase=ui` đã chốt shape port/DTO) · config/env
+> 7. Tech-doc anh em cùng domain
+>
+> Chỉ giá trị **thật sự không nguồn nào có** mới là GAP. **Gom TẤT CẢ GAP còn lại vào MỘT checkpoint** (mỗi GAP ghi rõ "đã tìm ở: {các nguồn}"), hỏi một lượt — KHÔNG hỏi lắt nhắt từng câu, KHÔNG chế bừa (đồng bộ Cổng 2 của generate-tech-docs). *(DS3 đã đảm bảo có §4 contract trước khi tới đây với BE.)*
 
 ### Test Selectors — emit element ID ổn định *(chỉ UI FE/App)*
 
@@ -829,7 +842,8 @@ Dựng mock từ `mock_source` đã phân giải ở Phase Detection — **shape
 *Bỏ qua hoàn toàn section này nếu `--phase` không phải `integration`.*
 
 1. **Đọc integration design.** Trong tech-doc gộp `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md`: ưu tiên §4.5.4 (mapping port→endpoint→DTO→error của platform), dùng §4.1/§4.2/§4.3 làm nguồn endpoint / request-response / error-code. Nếu doc chưa có §4.5.4 cho platform này, trích endpoint + shape + error code trực tiếp từ §4.1–§4.3.
-2. **Đọc mock adapter có sẵn** interface (`{UC-ID}ApiPort`) từ output `--phase=ui`.
+   - **Nếu §4/§4.5.4 thiếu bất kỳ chi tiết integration nào (endpoint, field/DTO, error-code, mapping):** ÁP DỤNG **SRC-CHAIN** (xem §Quy tắc nguồn giá trị) — vét cạn PRD (Appendix Existing API Contract), design-spec, mệnh đề `Then` của System/platform BDD, `core-entities.md`, **mock adapter đã sinh ở `--phase=ui`** (shape port/DTO đã chốt — nguồn shape mạnh nhất, đừng bỏ quên), tech-doc anh em cùng domain — TRƯỚC khi coi là GAP. Skip-if-answered. Chỉ hỏi cái không nguồn nào có, và **gộp mọi GAP còn lại vào MỘT checkpoint** (ghi rõ đã tìm ở đâu). *(Đây là fix cho tình trạng phase=integration hỏi nhiều dù đáp án đã nằm trong tài liệu khác.)*
+2. **Đọc mock adapter có sẵn** interface (`{UC-ID}ApiPort`) từ output `--phase=ui`. Real adapter implements **cùng** interface này → shape port/DTO đã cố định từ mock; **không hỏi lại shape** đã có ở đây.
 3. **Sinh real API adapter** tại `{paths.src_dir}/{domain}/{UC-ID}ApiAdapter.{ext}`:
    - Implements cùng interface `{UC-ID}ApiPort` như mock adapter
    - Gọi HTTP thật tới endpoint từ contract tech-doc

package/commands/generate-code.tmpl

@@ -31,6 +31,8 @@ Lệnh này giới hạn nghiêm ngặt trong **một file feature** được tr
 3. CLAUDE.md §architecture + §coding_standards
 4. **(chỉ FE/App)** Design Spec — nạp qua **Guard** bên dưới (gate approved/độ-tươi + sanity), là nguồn của màn hình, component inventory, và link Figma frame từng-màn.
 
+> **Phạm vi vét nguồn (SRC-CHAIN):** khi một giá trị còn thiếu ở nguồn chính, được phép đọc thêm các artifact **cùng feature-package** `{paths.specs_dir}/{domain}/{prd-slug}/` — PRD `{TICKET-ID}-{prd-slug}.md`, các `.feature` khác (system/web/app), design-spec, tech-doc anh em — cùng `core-entities.md`/`business-dictionary.md`. Đọc **theo nhu cầu** để phân giải giá trị trước khi hỏi người (xem §Quy tắc nguồn giá trị).
+
 ---
 
 ## Guard — BDD & Design Spec đã sẵn sàng chưa *(cảnh báo MỀM — đồng bộ generate-bdd)*
@@ -363,7 +365,18 @@ DTOs → Entity/Model → Repository → Service interface → Service impl →
 
 > **Quy tắc entry-point:** `@trace.implements` phải xuất hiện ở **layer entry-point** như định nghĩa trong `CLAUDE.md §2`. Với REST API → Controller. Với module event-driven → event handler / consumer class. Với context-engineering → hàm orchestration prompt. Không bao giờ chỉ đặt ở layer trong.
 
-> **Quy tắc nguồn giá trị (chống hard-code):** MỌI giá trị cụ thể (endpoint path, error code, tên field/DTO, enum, limit/timeout, header) phải lấy từ **nguồn đã chốt** — tech-doc §4 (contract) · `core-entities.md` (enum/field) · config/env — **KHÔNG bịa inline**. Nếu một hằng số nghiệp vụ lặp lại hoặc mang ý nghĩa (retry count, ngưỡng, key) → **đặt tên hằng số** (constant/config), không rải magic number/string trong code. Không có nguồn cho một giá trị → đây là GAP: dừng và hỏi, đừng chế bừa (đồng bộ Cổng 2 của generate-tech-docs). *(DS3 đã đảm bảo có §4 contract trước khi tới đây với BE.)*
+> **Quy tắc nguồn giá trị (chống hard-code):** MỌI giá trị cụ thể (endpoint path, error code, tên field/DTO, enum, limit/timeout, header) phải lấy từ **nguồn đã chốt** — **KHÔNG bịa inline**. Nếu một hằng số nghiệp vụ lặp lại hoặc mang ý nghĩa (retry count, ngưỡng, key) → **đặt tên hằng số** (constant/config), không rải magic number/string trong code.
+>
+> **VÉT CẠN NGUỒN TRƯỚC KHI HỎI (SRC-CHAIN) — bắt buộc.** Khi một giá trị chưa thấy ở nguồn chính, PHẢI quét lần lượt các nguồn đã có trong context/spec-package theo thứ tự sau, **dừng ngay khi tìm thấy** (skip-if-answered), KHÔNG hỏi người ngay:
+> 1. Tech-doc gộp §4 (contract: §4.1 endpoint · §4.2 request/response · §4.3 error · §4.5.4 client integration)
+> 2. `core-entities.md` (tên field / type / enum) · `business-dictionary.md` (thuật ngữ chuẩn)
+> 3. PRD của UC (nhất là Appendix "Existing API Contract" khi `API Source: existing`, và metadata)
+> 4. Design-spec (FE/App: field/label/state màn hình)
+> 5. System/platform BDD — mệnh đề `Then` (behavior + giá trị fixture)
+> 6. Code/adapter đã sinh ở lần chạy trước (vd mock adapter `--phase=ui` đã chốt shape port/DTO) · config/env
+> 7. Tech-doc anh em cùng domain
+>
+> Chỉ giá trị **thật sự không nguồn nào có** mới là GAP. **Gom TẤT CẢ GAP còn lại vào MỘT checkpoint** (mỗi GAP ghi rõ "đã tìm ở: {các nguồn}"), hỏi một lượt — KHÔNG hỏi lắt nhắt từng câu, KHÔNG chế bừa (đồng bộ Cổng 2 của generate-tech-docs). *(DS3 đã đảm bảo có §4 contract trước khi tới đây với BE.)*
 
 ### Test Selectors — emit element ID ổn định *(chỉ UI FE/App)*
 
@@ -417,7 +430,8 @@ Dựng mock từ `mock_source` đã phân giải ở Phase Detection — **shape
 *Bỏ qua hoàn toàn section này nếu `--phase` không phải `integration`.*
 
 1. **Đọc integration design.** Trong tech-doc gộp `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md`: ưu tiên §4.5.4 (mapping port→endpoint→DTO→error của platform), dùng §4.1/§4.2/§4.3 làm nguồn endpoint / request-response / error-code. Nếu doc chưa có §4.5.4 cho platform này, trích endpoint + shape + error code trực tiếp từ §4.1–§4.3.
-2. **Đọc mock adapter có sẵn** interface (`{UC-ID}ApiPort`) từ output `--phase=ui`.
+   - **Nếu §4/§4.5.4 thiếu bất kỳ chi tiết integration nào (endpoint, field/DTO, error-code, mapping):** ÁP DỤNG **SRC-CHAIN** (xem §Quy tắc nguồn giá trị) — vét cạn PRD (Appendix Existing API Contract), design-spec, mệnh đề `Then` của System/platform BDD, `core-entities.md`, **mock adapter đã sinh ở `--phase=ui`** (shape port/DTO đã chốt — nguồn shape mạnh nhất, đừng bỏ quên), tech-doc anh em cùng domain — TRƯỚC khi coi là GAP. Skip-if-answered. Chỉ hỏi cái không nguồn nào có, và **gộp mọi GAP còn lại vào MỘT checkpoint** (ghi rõ đã tìm ở đâu). *(Đây là fix cho tình trạng phase=integration hỏi nhiều dù đáp án đã nằm trong tài liệu khác.)*
+2. **Đọc mock adapter có sẵn** interface (`{UC-ID}ApiPort`) từ output `--phase=ui`. Real adapter implements **cùng** interface này → shape port/DTO đã cố định từ mock; **không hỏi lại shape** đã có ở đây.
 3. **Sinh real API adapter** tại `{paths.src_dir}/{domain}/{UC-ID}ApiAdapter.{ext}`:
    - Implements cùng interface `{UC-ID}ApiPort` như mock adapter
    - Gọi HTTP thật tới endpoint từ contract tech-doc

package/commands/generate-tech-docs.md

@@ -463,6 +463,25 @@ Lưu `input_features`, `platforms_present`, danh sách scenario theo từng UC,
 
 ---
 
+## Bước 0.5 — [ARCH] Nạp Architecture Context (nếu có)
+
+Tech-design chắt lọc kiến trúc hệ thống thành API contract + client design, nên đây là **nơi duy nhất** trong pipeline nạp `architecture.md` (SSOT cross-cutting sinh bởi `/generate-architecture`). Không nạp toàn cục ở context-loader — chỉ lệnh này cần nó ở mức sâu.
+
+1. **Phân giải path:** `{paths.specs_dir}/architecture.md` (mặc định `specs/architecture.md`). Chế độ umbrella: context-loader đã trỏ `specs_dir`/`service_root` về service đang active → dùng `architecture.md` của chính service đó (kiến trúc là code-level, per-service).
+2. **Nếu file KHÔNG tồn tại** → bỏ qua âm thầm, đặt `arch = none`. Vẫn dựa vào CLAUDE.md §2 (layers/rules) + core-entities như trước. (Gợi ý mềm một lần trong report cuối: "Chưa có architecture.md — cân nhắc chạy `/generate-architecture` để tech-design bám kiến trúc hệ thống.")
+3. **Nếu tồn tại** → đọc **có chọn lọc theo tier** (mỗi mục có marker `<!-- tier: core|conditional|ops -->`):
+   - **Nạp** thân các mục **`core` + `conditional`** — đây là phần ảnh hưởng code/API/data: layer boundaries + dependency direction, phân loại/nguồn dữ liệu, injection rules, luồng xác thực, response API chuẩn, caching/sharding/messaging, multi-tenant/identity-resolution.
+   - **BỎ QUA** các mục **`ops`** (Observability, Triển khai & DevOps, Chiến lược kiểm thử, NFR) — không đổi thiết kế API/data-model, chỉ làm nhiễu context.
+   - Các section §2–§4 (data model, API contract, integration) PHẢI nhất quán với phần đã nạp — KHÔNG tự suy khác.
+4. **Mục đang STUB (`<!-- status: stub -->`):** nếu một UC trong batch **chạm** tới một concern mà mục tương ứng còn stub (vd UC có tenant scoping nhưng §Multi-tenant là stub) → **cảnh báo mềm** trong report: *"§{Mục} chưa tài liệu hoá trong architecture.md — chạy `/generate-architecture --section={slug}` để tech-design chính xác hơn."* Vẫn tiếp tục dựa vào CLAUDE.md.
+5. **Trust-gate — đọc frontmatter `verified_by`:**
+   - `verified_by: AI-draft` (hoặc trống) → nội dung do AI dựng từ config/tài liệu/code, CHƯA ai verify. Vẫn dùng làm tham chiếu nhưng **cảnh báo** trong report: *"⚠️ architecture.md còn là AI-draft chưa verify — tech-design có thể kế thừa giả định sai. Nên để Tech Lead verify (đổi `verified_by`) trước khi chốt."* Khi mâu thuẫn với CLAUDE.md/BDD thì ưu tiên CLAUDE.md/BDD.
+   - `verified_by: {người thật}` → coi là ràng buộc kiến trúc chính thức.
+
+Lưu `arch` (`none` | `ai-draft` | `verified`) để dùng ở các bước sinh section và report.
+
+---
+
 ## Bước 1 — Chế độ Fresh vs Append
 
 Kiểm tra `output_path` đã tồn tại chưa.

package/commands/generate-tech-docs.tmpl

@@ -51,6 +51,25 @@ Lưu `input_features`, `platforms_present`, danh sách scenario theo từng UC,
 
 ---
 
+## Bước 0.5 — [ARCH] Nạp Architecture Context (nếu có)
+
+Tech-design chắt lọc kiến trúc hệ thống thành API contract + client design, nên đây là **nơi duy nhất** trong pipeline nạp `architecture.md` (SSOT cross-cutting sinh bởi `/generate-architecture`). Không nạp toàn cục ở context-loader — chỉ lệnh này cần nó ở mức sâu.
+
+1. **Phân giải path:** `{paths.specs_dir}/architecture.md` (mặc định `specs/architecture.md`). Chế độ umbrella: context-loader đã trỏ `specs_dir`/`service_root` về service đang active → dùng `architecture.md` của chính service đó (kiến trúc là code-level, per-service).
+2. **Nếu file KHÔNG tồn tại** → bỏ qua âm thầm, đặt `arch = none`. Vẫn dựa vào CLAUDE.md §2 (layers/rules) + core-entities như trước. (Gợi ý mềm một lần trong report cuối: "Chưa có architecture.md — cân nhắc chạy `/generate-architecture` để tech-design bám kiến trúc hệ thống.")
+3. **Nếu tồn tại** → đọc **có chọn lọc theo tier** (mỗi mục có marker `<!-- tier: core|conditional|ops -->`):
+   - **Nạp** thân các mục **`core` + `conditional`** — đây là phần ảnh hưởng code/API/data: layer boundaries + dependency direction, phân loại/nguồn dữ liệu, injection rules, luồng xác thực, response API chuẩn, caching/sharding/messaging, multi-tenant/identity-resolution.
+   - **BỎ QUA** các mục **`ops`** (Observability, Triển khai & DevOps, Chiến lược kiểm thử, NFR) — không đổi thiết kế API/data-model, chỉ làm nhiễu context.
+   - Các section §2–§4 (data model, API contract, integration) PHẢI nhất quán với phần đã nạp — KHÔNG tự suy khác.
+4. **Mục đang STUB (`<!-- status: stub -->`):** nếu một UC trong batch **chạm** tới một concern mà mục tương ứng còn stub (vd UC có tenant scoping nhưng §Multi-tenant là stub) → **cảnh báo mềm** trong report: *"§{Mục} chưa tài liệu hoá trong architecture.md — chạy `/generate-architecture --section={slug}` để tech-design chính xác hơn."* Vẫn tiếp tục dựa vào CLAUDE.md.
+5. **Trust-gate — đọc frontmatter `verified_by`:**
+   - `verified_by: AI-draft` (hoặc trống) → nội dung do AI dựng từ config/tài liệu/code, CHƯA ai verify. Vẫn dùng làm tham chiếu nhưng **cảnh báo** trong report: *"⚠️ architecture.md còn là AI-draft chưa verify — tech-design có thể kế thừa giả định sai. Nên để Tech Lead verify (đổi `verified_by`) trước khi chốt."* Khi mâu thuẫn với CLAUDE.md/BDD thì ưu tiên CLAUDE.md/BDD.
+   - `verified_by: {người thật}` → coi là ràng buộc kiến trúc chính thức.
+
+Lưu `arch` (`none` | `ai-draft` | `verified`) để dùng ở các bước sinh section và report.
+
+---
+
 ## Bước 1 — Chế độ Fresh vs Append
 
 Kiểm tra `output_path` đã tồn tại chưa.

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.2.4
+0.2.5