@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/commands/generate-tech-docs.md

@@ -1,1344 +0,0 @@
-# /generate-tech-docs — Sinh Tài liệu Thiết kế Kỹ thuật (một doc gộp per-PRD)
-
-> **Mô hình phạm vi:** MỘT tài liệu thiết kế kỹ thuật cho mỗi **PRD**, không phải
-> per-UC — một blueprint **full-stack, gộp** (backend API/data/DB **và** client
-> component/state/integration trong một file, nối bằng sequence diagram xuyên
-> tầng) để bất kỳ dev nào đọc là implement được cả feature.
->
-> **Tech lead trỏ lệnh vào (các) file BDD cụ thể cần thiết kế lúc này** — một file,
-> hoặc một batch nhỏ (vd `system/` + `web/` + `app/` của cùng một UC). Lệnh chỉ nạp
-> **đúng các file đó** (giữ context nhỏ) rồi ghi/mở rộng tài liệu tech-design duy
-> nhất của PRD. Chạy lại cho (các) file BDD kế tiếp thì doc **lớn dần** — mỗi lần
-> chạy là **append**, không bao giờ regenerate toàn bộ. Lệnh KHÔNG tự gom mọi BDD
-> của PRD (sẽ nổ context).
-
-## Gate
-# Gate — Quy trình vào chuẩn cho mọi lệnh
-
-Mọi lệnh PHẢI chạy gate này trước khi thực thi phần logic riêng của nó.
-
-## Bước 0 — Kiểm tra chế độ Sub-Agent
-
-Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ một orchestrator hay không:
-
-1. Thử parse `$ARGUMENTS` dưới dạng JSON.
-2. Nếu parse thành công **và** chứa `"_agent_mode": true`:
-   - **Bỏ qua hoàn toàn Bước 1, 2 và 3 của Gate này.**
-   - Đặt target file = `payload.target_file`
-   - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
-   - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
-   - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
-   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
-   - Đi thẳng tới phần logic riêng của lệnh.
-3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
-
-## Bước 0-B — Kiểm tra Model
-
-*Bỏ qua bước này nếu `_agent_mode: true` (sub-agent — orchestrator đã kiểm tra rồi).*
-
-Các lệnh sinh nội dung và review phức tạp đòi hỏi khả năng suy luận mạnh.
-Dùng model nhỏ hơn sẽ rủi ro: bỏ sót edge case, phân tích spec thiếu sót, vi phạm kiến trúc.
-
-Hiển thị và chờ phản hồi:
-
-```
-⚙️  MODEL CHECK
-──────────────────────────────────────────────────────────────────
-  Recommended  : model Opus mới nhất
-  Why needed   : Phân tích spec, review kiến trúc, sinh code đòi hỏi
-                 suy luận sâu. Model nhỏ hơn (Haiku/Sonnet) dễ bỏ sót edge case.
-
-  Cách đổi trong Claude Code:
-    • /model → chọn model Opus
-    • hoặc: Settings → Model
-
-  Đang chạy một model Opus?
-    Y — đúng → tiếp tục
-    S — bỏ qua kiểm tra (tôi chấp nhận rủi ro chất lượng thấp hơn với model hiện tại)
-──────────────────────────────────────────────────────────────────
-```
-
-- "Y" → tiếp tục sang Bước 1.
-- "S" → tiếp tục sang Bước 1 (người dùng chấp nhận rủi ro, thêm ⚠️ vào report cuối).
-- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang một model Opus (`/model`) rồi chạy lại lệnh này."
-
-## Bước 1 — Xác định Target File
-
-0. **Tách cờ trước khi resolve target.** `$ARGUMENTS` có thể lẫn các `--flag` (vd `--phase=integration`, `--comment`, `--fix`). **Loại bỏ mọi token bắt đầu bằng `--`** ra khỏi phần dùng để tìm target — chỉ giữ phần path/UC-ID/ticket. (Các flag đó do phần logic riêng của lệnh parse ở bước sau, KHÔNG phải tên file.)
-1. Nếu `$ARGUMENTS` (đã tách cờ) được cung cấp và trỏ tới một file tồn tại → dùng trực tiếp làm target.
-2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`):
-   - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó.
-   - **Lệnh PRD** (target là file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)*
-   - **Lệnh tech-docs** — target là tech-doc **gộp cấp PRD** `{TICKET-ID}-tech-design.md` (MỘT doc phủ nhiều UC; danh sách UC nằm ở `@trace.ucs`). Vì tên file mang `{TICKET-ID}` chứ **không** mang `{UC-ID}`, phải tách trước khi glob:
-     - `$ARGUMENTS` là **UC-ID** (`{TICKET-ID}-UC{N}`) → lấy `{TICKET-ID}` = phần **trước** `-UC`, rồi glob `{specs_dir}/{domain}/*/tech-docs/{TICKET-ID}-tech-design.md`.
-     - `$ARGUMENTS` là **TICKET-ID** → glob trực tiếp như trên.
-     - Chưa biết domain → `{specs_dir}/*/*/tech-docs/{TICKET-ID}-tech-design.md`.
-     - Vẫn không khớp → glob rộng `{specs_dir}/*/*/tech-docs/*tech-design*.md` rồi liệt kê để người dùng chọn.
-     *(Đừng glob `{UC-ID}*-tech-design*.md` — nó nở thành `FT-001-UC1*-tech-design*.md` và **không bao giờ** khớp `FT-001-tech-design.md`.)*
-   - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
-
-   Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
-3. Nếu `$ARGUMENTS` rỗng hoặc không tìm thấy file khớp:
-   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/*.md` — file PRD ở gốc mỗi feature folder — cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
-   - Hiển thị danh sách cho người dùng và hỏi: "Bạn muốn làm việc với file nào? (Nhập số thứ tự hoặc tên file)"
-   - Chờ người dùng chọn rồi mới tiếp tục.
-
-## Bước 2 — Chạy Context Loader
-
-Nạp toàn bộ context của dự án bằng cách làm theo quy trình trong `steps/context-loader.md`.
-Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phiên làm việc của lệnh.
-
-## Bước 3 — CHECKPOINT
-
-Sau khi hoàn thành Bước 1 và 2, hiển thị bản tóm tắt và chờ xác nhận:
-
-```
-CHECKPOINT
------------
-Target     : {resolved file path}
-Project    : {project.name từ project-context.yaml}
-Tech stack : {language} / {framework}
-Module     : {module nếu có, else "not configured"}
-Domains    : {danh sách domain, ngăn cách bởi dấu phẩy}
-
-Tiếp tục? (Y/N)
-```
-
-Chờ người dùng trả lời rõ ràng "Y" hoặc "N" rồi mới tiếp tục.
-- "Y" → tiếp tục sang các bước riêng của lệnh bên dưới.
-- "N" → dừng lại và hỏi người dùng muốn thay đổi gì.
-
-
-*Với lệnh này, `$ARGUMENTS` là **input BDD tech lead chọn tường minh** — một hay nhiều path `.feature` và/hoặc UC-id (cách nhau bằng khoảng trắng), KHÔNG phải cả PRD để glob. Phân giải mỗi tham số thành một `.feature` (Gate Bước 1: `{paths.specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature`), gom vào `input_features` (batch), và suy `{domain}` + `{prd-slug}` + `{TICKET-ID}` từ (các) path khớp — tất cả PHẢI cùng một PRD. Output là doc gộp **duy nhất** của PRD; lần chạy này chỉ thiết kế (các) UC có trong `input_features`.*
-
-## Context
-# Context Loader — Nạp toàn bộ context dự án
-
-Thực hiện các bước theo đúng thứ tự. Lưu mọi thứ vào bộ nhớ trong suốt phiên làm việc của lệnh.
-
-**Hướng dẫn ưu tiên (chống lost-in-middle):**
-- Bước 1–2 là PROJECT-CONFIG — nạp trước, phân giải mọi path và metadata.
-- Bước 3 là CRITICAL — kiến trúc + coding standards, là các sự thật ưu tiên cao nhất khi sinh nội dung.
-- Bước 4 là SAFETY — quy tắc bảo vệ dữ liệu, thực thi ngầm suốt cả phiên.
-- Bước 5–6 là DOMAIN KNOWLEDGE — thuật ngữ và định nghĩa entity.
-- Bước 7 là WORKING MEMORY RECAP — chốt các sự thật quan trọng lên đầu bộ nhớ làm việc.
-
----
-
-## Bước 1 — [PROJECT-CONFIG] Nạp project-context.yaml
-
-Đọc `.agent/project-context.yaml`. Trích xuất và lưu:
-
-**Tech Stack:**
-- `tech_stack.language` → ngôn ngữ đang dùng (vd: Java 17, TypeScript, C#, Go)
-- `tech_stack.framework` → framework đang dùng (vd: Spring Boot 3.2, Angular 17, .NET 8)
-- `tech_stack.build_tool` → build tool (vd: Maven, npm, dotnet, go)
-- `tech_stack.test_framework` → test framework (vd: JUnit 5 + Mockito, Jest, xUnit)
-- `tech_stack.database` → database (vd: PostgreSQL, MySQL, MongoDB)
-- `tech_stack.module` → module profile đang dùng (vd: java-spring, angular, dotnet, golang, context-engineering)
-
-**Conventions:**
-- `conventions.build_command` → cách compile/build
-- `conventions.test_command` → cách chạy test
-- `conventions.service_run` → cách khởi động service
-- `conventions.ticket_prefix` → tiền tố ticket ID (vd: PROJ, FEAT, UC)
-
-**Domains:**
-- `domains` → danh sách các business domain đang hoạt động
-
-**Paths (nếu có):**
-- `paths.specs_dir` → gốc của spec artifact — PRD, BDD, tech-docs, design-spec. Cấu trúc: `{specs_dir}/{domain}/{prd-slug}/{ {TICKET-ID}-{prd-slug}.md | bdd/ | tech-docs/ | design-spec/}` (file PRD đặt tên `{TICKET-ID}-{prd-slug}.md`, là file `.md` duy nhất ở gốc feature folder)
-- `paths.refinement_dir` → thư mục output cho findings/review
-- `paths.qc_dir` → gốc artifact QC automation (hiện ở top-level, mỗi UC một thư mục con: `{qc_dir}/{UC-ID}/`)
-- `paths.qc_skills_dir` → nơi các lệnh qc-* nạp QC skill (mặc định bundled `.agent/skills/qc`; override sang repo/submodule riêng của team QC để bản nâng cấp framework không ghi đè)
-- `paths.product_definitions_dir` → gốc product definition
-- `paths.domain_knowledge_dir` → gốc domain knowledge
-- `paths.business_dictionary` → path tới business-dictionary.md
-- `paths.core_entities` → path tới core-entities.md
-- `paths.tech_docs_dir` → gốc tài liệu kỹ thuật (gộp với specs_dir trong bố cục feature-package — tech-docs nằm dưới `{specs_dir}/{domain}/{prd-slug}/tech-docs/`)
-- `paths.src_dir` → gốc mã nguồn (nơi generate-code đặt & quét code; nguồn chính cho FE + phạm vi reuse-scan của DS5)
-- `paths.trace_dir` → thư mục trạng thái trace; cấu trúc: `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` (mỗi UC × platform một sổ)
-
-Nếu không có section `paths`, dùng các giá trị mặc định:
-- `specs_dir` = `specs`
-- `refinement_dir` = `.agent/review`
-- `qc_dir` = `docs`
-- `qc_skills_dir` = `.agent/skills/qc`
-- `product_definitions_dir` = `specs/product-definition`
-- `domain_knowledge_dir` = `specs/domain-knowledge`
-- `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
-- `core_entities` = `specs/domain-knowledge/core-entities.md`
-- `tech_docs_dir` = `specs`
-- `src_dir` = `src`
-- `trace_dir` = `.trace`
-
-Lưu ý: Trong bố cục feature-package, `specs_dir` là gốc thống nhất. Mọi loại spec artifact (PRD, BDD, tech-docs, design-spec) đều nằm dưới `{specs_dir}/{domain}/{prd-slug}/`. `prd-slug` là tên folder feature-package, không phải một biến config riêng.
-
-**Cách trích xuất `prd_slug` (đúng cho MỌI target file, bất kể độ sâu lồng nhau):** với một path target dạng `{specs_dir}/{domain}/{prd-slug}/...`, lấy **segment path đầu tiên sau `{specs_dir}/{domain}/`** — tức vị trí `{prd-slug}`. KHÔNG dùng folder cha trực tiếp của file, vì artifact BDD/tech-docs/design-spec lồng sâu hơn một hoặc hai cấp bên trong package. Ví dụ:
-- `specs/payment/create-invoice/PAY01-create-invoice.md` → `prd_slug = create-invoice`
-- `specs/payment/create-invoice/bdd/system/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `system`)*
-- `specs/payment/create-invoice/bdd/web/PAY-UC1.feature` → `prd_slug = create-invoice` *(KHÔNG phải `web`)*
-- `specs/payment/create-invoice/tech-docs/PAY01-tech-design.md` → `prd_slug = create-invoice` *(KHÔNG phải `tech-docs`)*
-- `specs/payment/create-invoice/design-spec/PAY-design-spec-web.md` → `prd_slug = create-invoice`
-
-Mọi artifact cùng cấp của một feature (PRD, BDD của từng platform, tech-docs BE + FE, design-spec, và trace TSV) đều phân giải về **cùng một `prd_slug`** — nên một BDD **system** hay tech-doc **system/BE** được tổng hợp sẽ nằm chung package `{specs_dir}/{domain}/{prd-slug}/` với các artifact web/app mà nó được suy ra từ đó.
-
-Nếu `tech_stack.module` được đặt, đồng thời nạp `.agent/modules/{module}/stack-profile.yaml` nếu file tồn tại.
-
----
-
-## Bước 1.5 — [SERVICE ROUTING] Phân giải path service (chế độ umbrella)
-
-*Bỏ qua hoàn toàn bước này nếu `setup.mode` không phải `"umbrella"` và không có section `services` trong project-context.yaml.*
-
-Nếu có section `services`:
-
-**1. Phát hiện active domain** (theo thứ tự ưu tiên):
-- Đọc `@trace.domain` từ frontmatter của target file (nếu Gate đã nạp một target file)
-- Trích xuất từ path target file: `domain` = segment đầu tiên sau base path `specs_dir`; `prd_slug` = segment kế tiếp (folder feature-package). Điều này đúng ở mọi độ sâu target — xem quy tắc trích xuất `prd_slug` ở Bước 1.  
-  *(vd: `specs/user/create-account/USR01-create-account.md` **và** `specs/user/create-account/bdd/system/UC1.feature` đều → domain = `user`, prd_slug = `create-account`)*
-- Nếu `$ARGUMENTS` chứa một path, trích xuất segment domain sau `specs_dir`
-
-**1b. Phát hiện active platform** (chỉ cần khi service ở dạng map-theo-platform — bước 2b):
-- Đọc `@trace.platform` từ header của target `.feature` (`system` | `web` | `app`) — Gate đã resolve target trước bước này.
-- Nếu target không mang `@trace.platform` (vd target là PRD `.md`), thử suy từ segment `bdd/{platform}/` trong path target.
-- Nếu vẫn không xác định được → `active_platform = null`.
-
-**2. Route tới service** — nếu active domain khớp một key trong `services`.
-
-Hình dung việc này như **tra địa chỉ**: đi từ `domain`, có thể qua `platform`, có thể qua `prd_slug`, cho tới khi chỉ còn đúng một submodule.
-
-Thứ trỏ tới đích gọi là một **service entry**. Nó chỉ có hai kiểu:
-
-| Kiểu | Nhận ra bằng | Nghĩa |
-|---|---|---|
-| **Đã chốt** | có `path` | Xong — đây là submodule cần tìm |
-| **Tra tiếp** | có `by_prd_slug` | Ô này còn nhiều submodule → tra thêm một nấc bằng `prd_slug` (2c) |
-
-**Kiểm tra hợp lệ TRƯỚC khi dùng một entry** (làm ngay, đừng đợi tới 2a/2b/2c — sai ở đây mà đi tiếp là route nhầm repo mà không báo gì):
-
-| Entry trông thế nào | Xử lý |
-|---|---|
-| có `path`, không có `by_prd_slug` | hợp lệ → dùng |
-| có `by_prd_slug`, không có `path` | hợp lệ → tra tiếp (2c) |
-| **có CẢ HAI** | ❌ lỗi cấu hình → `active_service = unresolved`. **KHÔNG** ưu tiên `path` rồi bỏ qua `by_prd_slug` — như vậy mọi feature sẽ âm thầm route về cùng một repo. Báo đúng key sai để người dùng sửa. |
-| **không có cái nào** (và cũng không phải map platform) | ❌ lỗi cấu hình → `unresolved`, nêu rõ entry thiếu `path`/`by_prd_slug` |
-| `by_prd_slug` chứa entry lại có `by_prd_slug` | ❌ lỗi cấu hình → `unresolved`. Chỉ tra đúng **một** nấc slug, không đệ quy |
-
-Còn `services.{domain}` thì có thể là **một service entry** (chốt luôn ở cấp domain), hoặc **một map platform → service entry** (phải qua nấc platform trước). Nhận dạng theo đúng thứ tự này:
-
-| Thấy gì trong `services.{domain}` | Đi nhánh |
-|---|---|
-| có `path` | **2a** — chốt luôn |
-| có `by_prd_slug` | **2c** — tra bằng `prd_slug` |
-| không có cả hai (chỉ có các sub-key `system`/`web`/`app`…) | **2b** — tra bằng `platform`, rồi lặp lại đúng bảng này cho entry con |
-
-**2a. Dạng phẳng** — `services.{domain}` có **trực tiếp** `path`/`module` (một domain ↔ một service, mọi platform về cùng submodule). Route như cũ:
-- Lưu `active_service` = `services.{domain}.path`
-- Lưu `active_service_module` = `services.{domain}.module`
-- Nếu service có `module` riêng → dùng nó làm `active_module` (override `tech_stack.module`)
-
-**2b. Dạng map-theo-platform** — `services.{domain}` **KHÔNG** có `path` trực tiếp mà chứa các sub-key platform (`system` / `web` / `app`), mỗi cái là một **service entry** (một business-domain trải trên nhiều platform/submodule). Route theo `active_platform` (bước 1b):
-- Nếu `active_platform` khớp một sub-key → `entry = services.{domain}.{active_platform}`. Nếu `entry` có `path` → lưu `active_service = entry.path`, `active_service_module = entry.module` (→ `active_module`, override `tech_stack.module`). Nếu `entry` có `by_prd_slug` → **đi tiếp sang 2c** với entry đó.
-- Nếu `active_platform = null` (chưa xác định platform, vd đang thao tác cấp PRD) → **KHÔNG** chốt một service; đặt `active_service = multi`, `service_candidates_kind = platform`, và lưu `service_candidates` = map platform→`{path, module}`. **Làm phẳng luôn ở đây:** platform nào có entry `by_prd_slug` thì giải bằng `prd_slug` hiện tại (target cấp PRD vẫn nằm trong một feature-package nên `prd_slug` đã biết từ bước 1) → `service_candidates.{platform}` vẫn là `{path, module}` phẳng. Nếu `prd_slug` không khớp key nào, ghi platform đó là `unresolved` kèm lý do thay vì bỏ im. Nhờ vậy **mọi lệnh downstream chỉ cần biết một kiểu `service_candidates`**. Lệnh cần một service cụ thể (`/generate-code`, `/dev-*`, `/fix-bug`) luôn chạy trên target `.feature` có platform nên sẽ resolve được ở lần chạy đó; lệnh cấp PRD (`/generate-prd`, `/refine-prd`) không cần service cụ thể.
-- Nếu `active_platform` xác định nhưng không có sub-key tương ứng → `active_service = unresolved` (xem Fallback) với lý do "domain `{domain}` chưa cấu hình platform `{active_platform}`".
-
-**2c. Dạng map-theo-prd_slug** — một service entry chứa `by_prd_slug` thay cho `path`: **một ô của bảng định tuyến ứng với NHIỀU submodule**, mỗi feature-package một submodule. Dùng khi một platform (hoặc cả một domain) bị chia thành nhiều repo theo feature — ví dụ mỗi mini-game webview là một repo riêng.
-
-Đến đây `prd_slug` đã được trích ở bước 1 (không cần detect thêm gì). Route:
-
-- Nếu `prd_slug` khớp một key dưới `by_prd_slug` → `entry = {…}.by_prd_slug.{prd_slug}`; lưu `active_service = entry.path`, `active_service_module = entry.module` (→ `active_module`, override `tech_stack.module`).
-  **"Khớp" ở đây là khớp CHÍNH XÁC toàn chuỗi, phân biệt hoa/thường.** KHÔNG prefix, KHÔNG bỏ hậu tố, KHÔNG so gần đúng: `dap-chuot-v2` **không** khớp key `dap-chuot`; `Ban-Cung` **không** khớp `ban-cung`. Feature mới tách ra từ một feature cũ là một repo khác cho tới khi có người khai nó vào bảng.
-- Nếu `prd_slug = null` (chưa xác định feature-package — chỉ xảy ra khi không có target file, vd `$ARGUMENTS` rỗng) → **KHÔNG** chốt một service; đặt `active_service = multi`, `service_candidates_kind = prd_slug`, và lưu `service_candidates` = toàn map `by_prd_slug` (slug → `{path, module}`).
-  ⚠️ Đây là kiểu `service_candidates` **khác** với 2b — lệnh nào duyệt `service_candidates` theo platform (vd `/generate-bdd` sinh `bdd/{platform}/`) phải kiểm `service_candidates_kind = platform` trước; gặp `prd_slug` thì DỪNG và yêu cầu người dùng chỉ rõ target, đừng coi slug là platform.
-- Nếu `prd_slug` xác định nhưng **không** có key tương ứng → `active_service = unresolved` với lý do rõ: "domain `{domain}`{, platform `{active_platform}`} chưa cấu hình prd_slug `{prd_slug}`". **KHÔNG** tự đoán submodule gần đúng theo tên.
-
-Vị trí đặt `by_prd_slug` — hợp lệ ở **cả hai cấp**:
-- **Dưới một platform** (lồng trong 2b): `services.{domain}.{platform}.by_prd_slug` — platform đó có nhiều repo, các platform khác vẫn `{path, module}` như thường.
-- **Ngay dưới domain** (thay cho `path` của 2a): `services.{domain}.by_prd_slug` — domain không chia platform nhưng vẫn nhiều repo theo feature.
-
-*(`by_prd_slug` lồng trong `by_prd_slug` là vô nghĩa — nếu gặp, coi là lỗi cấu hình: `active_service = unresolved`, nêu rõ để người dùng sửa file. Một entry vừa có `path` vừa có `by_prd_slug` cũng là lỗi cấu hình — báo lỗi, không âm thầm ưu tiên cái nào.)*
-
-Ví dụ (một domain trải nhiều platform, riêng `webview` chia theo feature):
-```yaml
-services:
-  learning:
-    system: { path: "backend",     module: "java-spring" }
-    web:    { path: "web-app",     module: "nextjs" }
-    webview:
-      by_prd_slug:
-        dap-chuot: { path: "games/whac-a-mole", module: "phaser-game" }
-        ban-cung:  { path: "games/archery",     module: "phaser-game" }
-```
-→ target `specs/learning/dap-chuot/bdd/webview/UC1.feature` cho `domain = learning`,
-`active_platform = webview`, `prd_slug = dap-chuot` → `active_service = games/whac-a-mole`.
-
-*(Cả 2a/2b/2c: override `paths.specs_dir`/`paths.tech_docs_dir` per-service CHỈ khi `setup.spec_source` KHÔNG được đặt. Khi `spec_source` ĐƯỢC đặt, MỌI BDD/tech-doc là artifact liên team → để bước 4 route sang spec repo; KHÔNG pin per-service ở đây.)*
-
-**3. Fallback**:
-- Không phát hiện được domain, hoặc domain không khớp key nào trong `services` → giữ path mặc định từ Bước 1, đặt `active_service = unresolved`.
-- Domain khớp một map-theo-platform (2b) nhưng `active_platform` xác định mà thiếu sub-key tương ứng → `active_service = unresolved`, ghi lý do rõ để lệnh DỪNG báo lỗi cấu hình (không tự đoán platform).
-- Entry là map-theo-prd_slug (2c) nhưng `prd_slug` xác định mà thiếu key tương ứng → `active_service = unresolved`, ghi lý do rõ (không tự đoán submodule).
-- Entry sai cấu trúc (vừa có `path` vừa có `by_prd_slug`, hoặc `by_prd_slug` lồng nhau) → `active_service = unresolved`, nêu đúng key sai để người dùng sửa `project-context.yaml`.
-
-**4. Tự động override theo spec source** — nếu `setup.spec_source` được đặt VÀ path tương ứng chưa được set tường minh trong `paths:`:
-- Override `paths.specs_dir` → `{spec_source}/specs` — **luôn khi `spec_source` được đặt.** Mọi spec artifact (PRD, BDD, tech-docs, design-spec) nằm dưới gốc spec thống nhất trong spec repo dùng chung theo bố cục feature-package: `{spec_source}/specs/{domain}/{prd-slug}/`. Mọi umbrella (FE/App/BE) đều đọc từ đây. *(`specs/` theo service chỉ khi không có `spec_source`.)*
-- Override `paths.tech_docs_dir` → `{spec_source}/specs` — **luôn khi `spec_source` được đặt** (bước 2 không còn pin tech-docs theo service trong trường hợp này). Tech-docs nằm tại `{spec_source}/specs/{domain}/{prd-slug}/tech-docs/`. Tech-design CHÍNH LÀ API contract liên team: BE viết ở đây, FE/App đọc nó từ cùng spec submodule tại `/generate-code --phase=integration`. *(tech-docs theo service chỉ xảy ra khi không có `spec_source` — repo BE thuần đa-service không có spec module dùng chung.)*
-- Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
-- Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
-- Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
-- Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
-- Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
-- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
-- Override `paths.trace_dir` → `{spec_source}/.trace` — **luôn khi `spec_source` được đặt.** Trace TSV được gộp vào spec repo (một nơi authoritative duy nhất, không tách theo service) để PM/PO có một chỗ duy nhất quản lý trạng thái. Cấu trúc bên trong: `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv`. Các lệnh phía code (`/generate-code`, `/dev-run-test`, `/qc-run-test`) chạy từ `service_root` nhưng **ghi trace row của chúng vào `{spec_source}/.trace/{domain}/{prd-slug}/`** — giống như chúng đã push `feedback/` vào đó. *(`.trace` theo service chỉ khi không có `spec_source`.)*
-- Override `paths.refinement_dir` → `{spec_source}/.agent/review` — **luôn khi `spec_source` được đặt.** Findings review (`/refine-prd`, `/review-context`, `/review-tech-docs`) là artifact liên-team *về* tài liệu trong spec repo (PRD/BDD/tech-design) — thuộc cùng khu vực ghi với `.trace/` và `feedback/`. Các lệnh review chạy từ working dir của service (BE repo) nhưng **ghi findings vào `{spec_source}/.agent/review/`**, KHÔNG phải `.agent/review` của service repo. Bên trong flat, phân biệt bằng tên file đã prefix `{prd-slug}`/`{UC-ID}`/`{TICKET-ID}`. *(`.agent/review` theo service chỉ khi không có `spec_source`.)*
-
-> **Vì sao đặt dưới `spec_source`:** PRD, BDD, tech-docs, design-spec, domain knowledge, feedback của tester, **trạng thái coverage `.trace/`**, **và findings review `.agent/review/`** đều là **artifact liên team** — chúng nằm trong **spec repo dùng chung** theo bố cục feature-package để mọi umbrella (FE/App/BE) và PM đọc từ một nguồn qua `/sync`. Trong bố cục feature-package, một folder `specs/{domain}/{prd-slug}/` gom tất cả loại artifact của một PRD, giúp spec repo tự đủ và dễ điều hướng theo feature. Service submodule chỉ chứa **code** (+ tooling build/test). `.trace/`, `.agent/review/` và `feedback/` là khu vực **ghi** của dev/QC/reviewer trong spec repo. Ở chế độ single-service (không có `spec_source`), mọi thứ mặc định dưới gốc repo — vẫn là một repo.
-
----
-
-## Bước 1.6 — [SERVICE CONVENTIONS] Nạp convention riêng của service (chế độ umbrella)
-
-*Bỏ qua hoàn toàn bước này nếu `active_service` là `"unresolved"` hoặc `"multi"` (chưa chốt một service — dạng map-theo-platform ở cấp PRD) hoặc context ở chế độ single-service.*
-
-Khi `active_service` đã được phân giải thành một path thật ở Bước 1.5 (vd: `user-service/`):
-
-**1. Định vị config của service** — thử theo thứ tự ưu tiên:
-- `{active_service}/.agent/project-context.yaml`
-- `{active_service}/project-context.yaml`
-
-**2. Nếu tìm thấy, override bằng giá trị riêng của service:**
-
-| Biến | Nguồn |
-|----------|--------|
-| `conventions.test_command` | `conventions.test_command` của service |
-| `conventions.build_command` | `conventions.build_command` của service |
-| `paths.trace_dir` | **Nếu `spec_source` được đặt → giữ route spec-repo của bước 4 (`{spec_source}/.trace`); bỏ qua mọi `trace_dir` cấp service.** Chỉ khi không có `spec_source`: `{active_service}/{service paths.trace_dir}` (mặc định `{active_service}/.trace`). |
-| `paths.specs_dir` | **Nếu `spec_source` được đặt → giữ route spec-repo của bước 4 (`{spec_source}/specs`); bỏ qua mọi `specs_dir` cấp service** (mọi spec artifact đều liên team, không bao giờ theo service ở chế độ này). Chỉ khi không có `spec_source`: `{active_service}/{service paths.specs_dir}` nếu được set, else dùng override ở Bước 1.5. |
-| `paths.refinement_dir` | **Nếu `spec_source` được đặt → giữ route spec-repo của bước 4 (`{spec_source}/.agent/review`); bỏ qua mọi `refinement_dir` cấp service** (findings review là artifact liên team). Chỉ khi không có `spec_source`: `{active_service}/.agent/review`. |
-
-**3. Lưu** `service_root = {active_service}` làm mốc thư mục làm việc cho mọi lệnh phía sau:
-- Các lệnh shell (`/dev-run-test`, `/dev-gen-test`) chạy **bên trong** `service_root`
-- **File source/test** được ghi tương đối với `service_root`; **trace TSV** được ghi vào `{paths.trace_dir}` (là spec repo khi `spec_source` được đặt — một thao tác ghi liên-repo, commit/push vào spec submodule giống như `feedback/`).
-
-**4. Nếu không tìm thấy config của service** — giữ mặc định umbrella, vẫn set `service_root = {active_service}` (luôn cần mốc path kể cả khi không có config override).
-
----
-
-## Bước 2 — [PROJECT-CONFIG] Nạp module stack profile (có điều kiện)
-
-Nếu `tech_stack.module` được đặt, đọc `.agent/modules/{module}/stack-profile.yaml`.
-Merge các convention riêng của framework (layer pattern, test pattern, quy tắc đặt tên) vào context đã nạp.
-Nếu file không tồn tại → bỏ qua âm thầm.
-
----
-
-## Bước 3 — [CRITICAL] Nạp CLAUDE.md (phân tầng: root + service overlay)
-
-*Đây là context ưu tiên cao nhất — nó định nghĩa CÁCH viết code và tài liệu cho dự án này.*
-
-CLAUDE.md được nạp theo **hai tầng** để các quy tắc toàn-umbrella và kiến trúc/coding standards
-riêng của service kết hợp đúng cách. Agent luôn đứng ở gốc umbrella, nhưng code triển khai nằm
-trong một service submodule với stack, kiến trúc, và convention RIÊNG của nó — nên CLAUDE.md của
-service phải thắng khi sinh code.
-
-**Tầng 1 — [BASE] Root CLAUDE.md (toàn umbrella).**
-Đọc `CLAUDE.md` ở gốc repo. Coi nội dung của nó là **nền tảng dùng chung** cho cả umbrella —
-git convention, tư thế bảo vệ dữ liệu, quy tắc xuyên suốt, và (ở chế độ single-service) là
-kiến trúc + coding standards duy nhất của dự án.
-
-**Tầng 2 — [OVERLAY] Service CLAUDE.md (chỉ chế độ umbrella).**
-*Chỉ chạy nếu `service_root` đã được set ở Bước 1.6 (tức đã route tới một service thật).*
-Đọc `{service_root}/CLAUDE.md`. File này định nghĩa kiến trúc + coding standards của **stack
-thực sự đang được triển khai** (vd: `user-service` = java-spring, `web` = nextjs).
-Overlay nó lên trên Tầng 1: **khi có xung đột, giá trị của service THẮNG** cho kiến trúc,
-coding standards, và error handling. Các giá trị Tầng 1 mà service không định nghĩa lại
-(vd: git convention, banned pattern dùng chung toàn tổ chức) vẫn có hiệu lực.
-
-Từ kết quả **đã merge**, trích xuất và lưu:
-
-- **§1 Project Overview** → tên dự án, ngôn ngữ, framework, lệnh build/test, domains
-- **§2 Architecture** → thứ tự layer (vd: Controller → Facade → Service → Repository), quy tắc kiến trúc — *service overlay thắng*
-- **§2 Package Layout** → **base package** (vd `vn.edupia.{service}`) + **chiến lược đặt package** (by-layer / by-feature) + nơi code một domain sống. Đây là **quy ước đặt code trên đĩa**, PHẢI enforce khi sinh code. Nếu §2 chỉ nêu base package + thứ tự layer mà **không** nói tới sub-package theo feature → hiểu là **by-layer**: các layer đặt **TRỰC TIẾP** dưới base package (vd `vn.edupia.{service}.service`, `.repository`); feature/UC/prd-slug **KHÔNG** thành sub-package, chỉ phân biệt ở **tên class**. Lưu `code_base_package` + `package_strategy` — *service overlay thắng*.
-- **§3 Coding Standards** → quy tắc đặt tên (class, method), kiểu response wrapper, pattern bị cấm — *service overlay thắng*
-- **§5 Error Handling** → kiểu exception, mapping HTTP status code, tên class not-found exception — *service overlay thắng*
-- **§7 Git Conventions** → pattern đặt tên branch, format commit message — *lấy theo root trừ khi service định nghĩa lại*
-
-**Quy tắc phân giải:**
-- Nếu cả hai tầng tồn tại → merge như trên; ghi `claude_md_source = root + {service_root}`.
-- Nếu chỉ có service overlay (không có root CLAUDE.md) → dùng file service một mình; `claude_md_source = {service_root}`.
-- Nếu `service_root` được set nhưng `{service_root}/CLAUDE.md` **thiếu** → fallback về root CLAUDE.md và gắn cờ ⚠️ trong recap Bước 7 (service không có định nghĩa kiến trúc/coding-standards — việc sinh code sẽ dùng mặc định umbrella, có thể sai stack).
-- Nếu cả hai đều không tồn tại → ghi nhận CLAUDE.md thiếu và tiếp tục chỉ với dữ liệu từ project-context.yaml.
-
----
-
-## Bước 4 — [SAFETY] Nạp quy tắc bảo vệ dữ liệu
-
-Đọc `.agent/rules/data-protection.md` (hoặc `rules/data-protection.md` từ bản cài đặt framework).
-
-Lưu các pattern file nhạy cảm — bạn **tuyệt đối không** đọc, ghi, hiển thị, hay tham chiếu nội dung từ các file khớp những pattern đó trong suốt cả phiên.
-
-Nếu cả hai file đều không tồn tại → áp dụng mặc định built-in: không bao giờ truy cập `.env*`, `*.key`, `*.pem`, `*secret*`, `*password*`, `*credential*`.
-
----
-
-## Bước 5 — [DOMAIN] Nạp Business Dictionary (có điều kiện)
-
-Kiểm tra file business dictionary có tồn tại không (dùng `paths.business_dictionary` đã phân giải ở Bước 1).
-
-Nếu tồn tại, đọc và trích xuất:
-- **Canonical Terms** → danh sách đầy đủ các thuật ngữ chuẩn và định nghĩa
-- **Banned Terms** → danh sách đầy đủ các thuật ngữ bị cấm và bản thay thế chuẩn
-- **Status / Enum Registry** → các giá trị enum được phép theo từng entity
-
-Lưu danh sách banned term để **thực thi chủ động** suốt phiên làm việc của lệnh:
-- Khi sinh bất kỳ văn bản nào (PRD, BDD, comment code, tech docs), kiểm tra không có banned term nào xuất hiện
-- Tự động thay banned term bằng bản chuẩn tương đương
-
-Nếu file không tồn tại → bỏ qua âm thầm. Không cảnh báo hay chặn.
-
----
-
-## Bước 6 — [DOMAIN] Nạp Core Entities (có điều kiện)
-
-Kiểm tra file core entities có tồn tại tại `paths.core_entities` không (đã phân giải ở Bước 1).
-Path mặc định: `specs/domain-knowledge/core-entities.md`.
-
-Nếu tồn tại, đọc và lưu:
-- **Entity catalog** → với mỗi entity: tên, mục đích, service sở hữu, các field chính (tên + kiểu), business invariant, và quan hệ
-- **Field name registry** → tên field chuẩn dùng trong code và tài liệu được sinh ra
-- **Relationship map** → cách các entity liên hệ với nhau (1:N, N:N, embedded, v.v.)
-
-**Cách dùng catalog này:**
-- Khi sinh code: dùng tên field, kiểu, và quan hệ định nghĩa ở đây — KHÔNG suy đoán từ code có sẵn
-- Khi sinh PRD/BDD: tham chiếu tên entity từ catalog này để nhất quán
-- Khi sinh tech-docs: dùng catalog này làm nguồn chân lý cho định nghĩa entity
-
-Nếu file không tồn tại → bỏ qua âm thầm.
-
----
-
-## Bước 6.5 — [PLATFORM] Suy ra active_module và platform_type
-
-Dùng `tech_stack.module` đã nạp ở Bước 1, suy ra và lưu hai biến để mọi lệnh phía sau dùng:
-
-```
-active_module = tech_stack.module   (vd: "java-spring", "react", "flutter")
-```
-
-| `platform_type` | Modules |
-|---|---|
-| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
-| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular`, `phaser-game` |
-| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
-
-Nếu `tech_stack.module` rỗng hoặc không nhận diện được → set `platform_type = "unknown"` và gắn cờ ⚠️ trong recap Bước 7.
-
-Hai biến này (`active_module`, `platform_type`) là nguồn chuẩn cho mọi logic rẽ nhánh trong các lệnh cần hành vi riêng theo platform (dev-gen-test, debug, fix-bug, dev-smoke-test).
-
----
-
-## Bước 6.7 — [GUARDRAILS] Nạp Project Lessons (có điều kiện)
-
-*Các lỗi tích luỹ mà AI không được lặp lại trong dự án này. Chúng được bổ sung dần qua `/learn`
-hoặc được chấp nhận trong `/review-code`, `/fix-bug`, `/debug`.*
-
-Phân giải path file lessons:
-- Dùng `paths.lessons_file` nếu được set (có thể bị service override ở chế độ umbrella, Bước 1.6)
-- Else mặc định `specs/domain-knowledge/lessons-learned.md`
-- Ở chế độ umbrella/service (khi `service_root` được set), nếu `paths.lessons_file` chưa set, mặc định `{service_root}/.agent/project-lessons.md`
-
-Nếu file tồn tại, đọc và lưu TẤT CẢ lesson làm **GUARDRAIL ĐANG HOẠT ĐỘNG** cho phiên:
-- Coi **Rule** của mỗi lesson là ràng buộc cứng — cùng mức ưu tiên với coding standards trong CLAUDE.md (Bước 3).
-- Trước khi sinh hoặc sửa bất kỳ artifact nào (PRD, BDD, tech-doc, code, test), đối chiếu output với mọi lesson có `category` khớp lệnh hiện tại VÀ `scope` khớp target (domain / file).
-- Nếu output sinh ra vi phạm một lesson → sửa **trước khi** trình bày, và ghi rõ lesson nào (`L-NNN`) đã được áp dụng.
-
-Nếu file không tồn tại → bỏ qua âm thầm (chưa có lesson nào được ghi nhận).
-
----
-
-## Bước 7 — [RECAP] Working Memory Recap (chống lost-in-middle)
-
-Sau khi nạp toàn bộ context, tổng hợp và xuất một khối tóm tắt gọn.
-Recap này đảm bảo các sự thật quan trọng nhất được nêu ở CUỐI quá trình nạp context
-(hiệu ứng recency — tươi mới nhất trong bộ nhớ làm việc khi bắt đầu task).
-
-Xuất đúng khối này:
-```
-[CTX LOADED]
-Stack     : {language} / {framework} / {database}
-Platform  : {active_module} ({platform_type})
-Layers    : {thứ tự layer từ CLAUDE.md §2 đã merge, vd: Controller → Facade → Service → Repository}
-Package   : {code_base_package}.{layer} · {by-layer | by-feature}  ← feature/UC → tên class, KHÔNG thành package (nếu by-layer)
-CLAUDE.md : {root + {service_root} | chỉ {service_root} | chỉ root | ⚠️ service overlay THIẾU — dùng root | missing}
-Ticket    : {ticket_prefix}-
-Dict      : {loaded — N canonical terms, M banned terms | missing}
-Entities  : {loaded — EntityA, EntityB, EntityC | missing}
-Lessons   : {loaded — N guardrails | chưa có}
-Platform  : {active_platform: system | web | app | — nếu chưa xác định}
-Service   : {active_service} ({active_service_module}) [← domain{/platform}{/prd_slug} nếu route qua by_prd_slug] | multi (map-theo-platform hoặc map-theo-prd_slug, chốt khi target đủ platform/prd_slug) | single-service
-Svc Root  : {service_root} — đã nạp conventions + trace_dir từ config service | —
-Status    : {FULL | PARTIAL — thiếu: CLAUDE.md / business-dict / core-entities | MINIMAL}
-```
-
-Nếu bất kỳ file CRITICAL nào thiếu (CLAUDE.md), gắn cờ rõ ràng để người dùng quyết định có tiếp tục hay không.
-
----
-
-## Hoàn tất nạp Context
-
-Sau khi hoàn thành tất cả các bước, bạn đã nạp:
-- Định danh dự án, tech stack, convention module
-- Quy tắc kiến trúc và thứ tự layer  ← **[CRITICAL — giữ trong bộ nhớ làm việc]**
-- Coding standards và quy tắc đặt tên  ← **[CRITICAL — giữ trong bộ nhớ làm việc]**
-- Quy tắc bảo vệ dữ liệu (pattern file nhạy cảm không bao giờ truy cập)
-- Quy tắc thuật ngữ kèm danh sách banned term  ← **[DOMAIN — áp dụng cho mọi từ được sinh ra]**
-- Entity catalog (tên field, kiểu, invariant)  ← **[DOMAIN — dùng khi sinh code]**
-- Toàn bộ path đã cấu hình
-
-Tiếp tục sang bước kế tiếp của lệnh đang gọi.
-
-
----
-
-## Bước 0 — Phân giải batch đầu vào (file mà tech lead trỏ vào)
-
-1. Parse `$ARGUMENTS` thành danh sách feature tech lead chọn. Mỗi token là một path `.feature` hoặc một UC-id; phân giải mỗi cái thành file thật (Gate Bước 1). Danh sách này là `input_features` — **batch được thiết kế trong lần chạy này**. **Đừng** mở rộng nó bằng cách glob BDD anh em; chỉ nạp đúng các file này.
-2. **Phân giải định danh từ header, KHÔNG từ tên file.** Với mỗi feature đọc `# @trace.prd` → `{TICKET-ID}` và `# @trace.id` → `{UC-ID}` (cả hai không chứa slug và là chuẩn; TICKET-ID như `FEAT-01-2` có dấu gạch, và slug/title của một UC có thể khác nhau theo platform — vd `…-UC3-sua-cau-bo-qua` (system) vs `…-UC3-sua-cau-quay-lai-bo-qua` (web), nên **đừng bao giờ** parse tên file bằng chuỗi). `{domain}` + `{prd-slug}` lấy từ path (Gate Bước 1). Gom batch thành các UC theo `@trace.id`, để cùng một UC trên system/web/app là **một** UC. Lấy **title** chuẩn của mỗi UC từ PRD (không phải title feature riêng theo platform).
-   **Guard cùng-PRD:** nếu `@trace.prd` khác nhau trong batch → DỪNG: *"Các file thuộc PRD khác nhau ({list}). Chạy /generate-tech-docs mỗi PRD một lần."*
-3. **Cảnh báo mềm cỡ batch (không chặn):** nếu `input_features` có **hơn 5** file:
-   ```
-   ⚠️  {N} file BDD trong một lần chạy. Batch lớn nạp nhiều context hơn và có thể
-       làm giảm chất lượng thiết kế. Cân nhắc chia nhỏ (vd theo UC, hoặc theo platform).
-       Tiếp tục với cả {N}? (Y/N)
-   ```
-   Y → tiếp tục với tất cả · N → để tech lead chạy lại với ít file hơn.
-4. Với mỗi feature trong batch, đọc header + body: `@trace.service`, `@trace.module`, `@trace.platform`, `@trace.bdd_version`, `@trace.status`, `@trace.api_source`, UC id, các scenario (`SC{n}`), và business rule được tham chiếu (`BR{m}`).
-5. Xác định **các platform có trong batch** — cái này quyết định lần chạy sinh ra gì:
-   - feature `system/` → sinh/mở rộng các section **backend** (§2–§4.4, §6–§8) cho UC của nó.
-   - feature `web/` và/hoặc `app/` → sinh/mở rộng block **client §4.5** cho platform đó, và thêm flow của platform đó vào lane **§5** (5.B/5.C).
-   - batch không có feature client → không có việc §4.5 lần này (lần chạy sau trỏ vào BDD `web/`·`app/` sẽ append).
-   - **batch không có feature `system/` (PRD chỉ client):** **đừng** bịa BE contract. §4.1 chỉ liệt kê các endpoint mà client **tiêu thụ** (external / bên thứ ba / của team khác / existing), reverse-document từ mệnh đề Then của client BDD + PRD và đánh dấu "consumed (external)"; nếu feature không gọi mạng → §4 = "N/A — client-only, không backend". §4.5.4 map tới bất cứ gì §4.1 liệt kê (hoặc không có).
-   - Ghi `@trace.bdd_versions` (**số nhiều** — map theo platform, vd `system=1.5, web=1.9`) từ `@trace.bdd_version` (**số ít**, scalar) của mỗi feature — đừng làm phẳng về một số. *(Tên khác nhau là cố ý: cùng một tên cho hai kiểu dữ liệu sẽ làm vỡ mọi parser generic.)*
-6. Đường dẫn output — doc **duy nhất** của PRD:
-   ```
-   {paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md
-   ```
-   *(Không có `{UC-ID}` và không có hậu tố `-{platform}` — một doc gộp per-PRD lớn dần qua các lần chạy.)*
-
-Lưu `input_features`, `platforms_present`, danh sách scenario theo từng UC, và `output_path`.
-
----
-
-## 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.
-
-- **Chưa tồn tại → chế độ FRESH.** Tạo doc từ template, chỉ điền (các) UC trong `input_features`. (Section của các UC không thuộc batch này giữ placeholder `{…}` / được thêm ở lần chạy sau.)
-- **Đã tồn tại → chế độ APPEND.** Doc là tăng dần — không bao giờ regenerate từ đầu (sẽ đè mất chỉnh tay và sign-off của reviewer). Đọc bảng **§10 UC Coverage** và **Changelog** hiện có → `covered_ucs`. Với mỗi UC trong `input_features`, phân loại:
-  - **UC mới** (không có trong `covered_ucs`) → **thêm** các section của nó: sequence diagram §5 mới **đúng lane platform** (5.A/5.B/5.C, đánh số sau cái cuối cùng hiện có *trong lane đó*); với §4.5 — nếu **platform** này mới với doc → nhóm `### 4.5 — {platform}` mới, ngược lại thêm sub-block `§4.5.1.x {Screen} — {UC}` + row vào §4.5.6 dùng chung của nhóm platform đó (đừng lặp nhóm); row mới ở §3/§4.3/§8/§9. Rồi cập nhật §10 (row khoá theo platform×SC) và thêm một row Changelog.
-  - **UC đã phủ được trỏ lại** (có trong `covered_ucs`) → đây là refresh/mở rộng có chủ đích (vd tech lead giờ trỏ vào BDD `web/` của một UC mà backend đã thiết kế, hoặc BDD bump version). Xác nhận trước khi đụng nội dung có sẵn:
-    ```
-    ↻ {UC-ID} đã có trong {TICKET-ID}-tech-design.md.
-      Lần chạy này sẽ {thêm block client {platform} (§4.5) | refresh cho BDD v{new}}.
-      Cập nhật các section của UC này? (Y = merge/mở rộng · N = bỏ qua UC này)
-    ```
-    Y → merge (thêm platform/§ còn thiếu hoặc refresh phần đã đổi, giữ nguyên prose không liên quan) · N → bỏ qua UC đó.
-
-Lưu `mode` (`fresh` | `append`) và, theo từng UC của batch, hành động của nó (`add-new` | `extend-platform` | `refresh` | `skip`). Nếu mọi UC đều `skip` → báo "không có gì để làm" và dừng.
-
----
-
-## Bước 2 — Cổng Chất lượng (mọi feature nguồn)
-
-Với **mỗi** feature BDD trong scope:
-
-1. Tìm `{paths.refinement_dir}/{uc-id}-{platform}-review-bdd-findings.yaml` — `{platform}` = `@trace.platform` của chính feature này (đọc ở Bước 0). Findings là **per (UC × platform)**: mỗi `.feature` của từng platform được review vào file riêng, nên kiểm đúng file khớp feature **này** — không phải của platform anh em (feature `system` phải được gác bởi findings `system`, không phải `web`).
-   - **Thiếu** → cảnh báo mềm (không chặn):
-     ```
-     ⚠️  /review-context chưa chạy cho {uc-id}.feature.
-     Khuyến nghị: chạy /review-context {feature-file} trước để kiểm chất lượng BDD.
-     ```
-   - **Có** → kiểm các finding critical chưa xử lý với `status: "pending"`. Nếu có → **DỪNG** và in (các) feature vi phạm:
-     ```
-     ❌ Cổng Chất lượng thất bại — {feature-file}
-     Còn finding BDD critical chưa xử lý.
-     Chạy: /review-context --fix {feature-file}   ← auto-fix những gì có thể
-     Rồi: /review-context --resume {feature-file}
-     Rồi chạy lại: /generate-tech-docs {đúng các feature file đó}
-     ```
-2. Đọc `# @trace.status:` của feature (tín hiệu duyệt chuẩn). Nếu feature nào ≠ `approved` → cảnh báo mềm (đồng bộ generate-code / qc-analyze): *"BDD {uc-id} chưa approved (@trace.status: {status}) — tech design dựng từ BDD chưa chốt có thể phải làm lại. Tiếp tục? (Y/N)"*.
-
-Cổng này chỉ chạy cho `input_features` (batch) — không bao giờ quét BDD ngoài cái tech lead trỏ vào.
-
----
-
-## Bước 3 — Điều kiện tiên quyết Client (chỉ khi batch có feature `web/` hoặc `app/`)
-
-Các block client §4.5 (phân cấp component, map Figma → design-system, hình dạng state, test selector) được **suy ra** từ design spec. Định vị nó:
-
-- **Design Spec** — `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}*.md`.
-  - **Tìm thấy** → nạp; Screen Specs / Component Inventory / Screen States của nó cấp cho §4.5 và mô hình state client ở §4.5.3.
-  - **Không thấy** → cảnh báo mềm (không chặn cứng — các section backend vẫn giá trị đầy đủ, và §4.5 có thể draft chỉ-text từ client BDD, đánh dấu degraded):
-    ```
-    ⚠️  Không tìm thấy design-spec cho {TICKET-ID}. §4.5 (map UI component, tham chiếu
-        Figma, test selector) sẽ được draft chỉ từ BDD và đánh dấu
-        "[DRAFT — no design-spec]". Chạy /generate-design-spec trước để đủ độ trung thực.
-        Tiếp tục? (Y/N)
-    ```
-
-Cũng nạp, khi có, catalog Figma component (`figma-components/{module}.md`) và design token (đã nạp bởi context-loader Bước 6-B/6-C) để ưu tiên component trong catalog ở §4.5.1/§4.5.2 và token thật ở §4.5.5.
-
-> **Lưu ý:** vì BE và FE giờ nằm trong **cùng** một tài liệu, không còn cổng "BE contract phải tồn tại trước" — backend contract (§4) và client design (§4.5) được sinh cùng nhau. §4.5.4 vẫn yêu cầu mỗi client service method map tới một endpoint **thật** khai báo ở §4.1 (đừng bịa endpoint).
-
----
-
-## Bước 4 — Kiểm tra Brownfield
-
-Đọc `@trace.api_source` ở header mỗi feature của batch, và kiểm bảng Metadata của PRD tìm `| **API Source** | existing |`.
-
-| Giá trị | Chế độ |
-|-------|------|
-| `existing` | **Reverse-document** — API đã tồn tại; mô tả as-is, ghi chú gap so với BDD, không thiết kế mới |
-| vắng / khác | **Greenfield** — thiết kế API từ scenario |
-
-Lưu `active_mode`. Nếu `reverse-document`, nạp appendix "Existing API Contract" từ PRD làm input cho §4.
-
----
-
-## CHECKPOINT — Kế hoạch Tech Design
-
-Trước khi sinh, hiện kế hoạch và chờ **Y** rõ ràng:
-
-```
-Kế hoạch Tech Design — {TICKET-ID}  (doc full-stack / PRD)
-──────────────────────────────────────────────────────
-PRD        : {TICKET-ID} — {feature title}
-Chế độ     : {Fresh (doc mới) | Append (mở rộng doc có sẵn)}
-Batch      : {M} file feature lần này:
-               - {input_features[0]}  ({platform} · UC{n} · {add-new|extend-platform|refresh})
-               - {…}
-Service    : {trace.service}      Module: {trace.module}
-Platform   : {các platform trong batch}
-Chế độ API : {Reverse-document (API existing) | Greenfield (thiết kế mới)}
-Scenario   : {N} scenario trong batch
-BDD ver    : {bdd_version lớn nhất trong batch}
-Design-spec: {đã nạp | ⚠️ thiếu (§4.5 degraded) | n/a — batch không có feature client}
-UC của doc : đã phủ → {covered_ucs hoặc "chưa (doc mới)"};  lần này → {batch UCs}
-Output     : {output_path}   ({tạo | mở rộng})
-
-Section sẽ {sinh | thêm} cho batch này:
-  {backend (system trong batch): §1–§4.4, §6–§8}
-  {client  (web/app trong batch): §4.5 cho {platform}}
-  §5  Key Flows — {N} sequence diagram trong lane platform (5.A system/5.B web/5.C app), mỗi cái tiêu đề "platform · SC"
-  §9  Design Decisions (row mới) · §10 UC Coverage (khoá theo platform×SC) · §11 Cross-cutting · Changelog
-──────────────────────────────────────────────────────
-Tiếp tục? (Y/N)
-```
-
-Chờ "Y" rõ ràng.
-
----
-
-## Sinh
-
-Ghi/mở rộng `{output_path}` dùng template dưới đây, chỉ sinh **nội dung cho (các) UC** trong `input_features`. Điền các placeholder `{…}` liên quan và xoá các comment hướng dẫn khi làm.
-
-- Section **Backend** (§2–§4.4, §6–§8) đến từ feature `system/` trong batch (hoặc, brownfield, từ contract existing của PRD).
-- Block **Client** §4.5 đến từ feature `web/`·`app/` trong batch + design-spec. Dùng **cùng** giá trị test-id giữa web/app cho cùng một element logic (chỉ khác attribute theo platform).
-- **§5 Key Flows** — một mermaid sequence diagram cho mỗi scenario của batch, participant trải mọi tầng (client component → service → API → external API → DB). **Gom theo lane platform** (5.A system · 5.B web · 5.C app) và đặt tiêu đề mỗi diagram bằng **platform · SC** (vd `web · UC1-SC1`) — vì `{UC}-SC{N}` chỉ độc nhất trong (UC × platform): `system UC1-SC1` và `web UC1-SC1` là hai scenario khác nhau. Đừng bao giờ ghi trơ `UC1-SC1`. Chỉ tạo lane cho platform có BDD.
-- **§1/§2** (Overview/Actors, Architecture) là cấp PRD: viết ở lần chạy đầu; các lần sau chỉ mở rộng nếu batch thêm actor/integration thật sự mới.
-- **§10 UC Coverage** — một row UC (có cột Platforms) + bảng con coverage-scenario khoá theo **(platform, SC)** — mỗi platform×SC một row, vì cùng số SC ở platform khác nhau là scenario khác nhau. Đây là mỏ neo mà chế độ APPEND đọc. Luôn cập nhật nó cho (các) UC/platform của batch.
-
-**Chế độ APPEND (doc đã tồn tại):** **đừng** viết lại section có sẵn. Chèn diagram §5 của UC batch **vào đúng lane platform** (5.A/5.B/5.C, đánh số sau cái cuối trong lane đó, tiêu đề `platform · SC`), các row mới ở §3/§4.3/§8/§9; với §4.5 — platform mới → nhóm `### 4.5 — {platform}` mới, ngược lại thêm sub-block `§4.5.1.x {Screen} — {UC}` + row vào §4.5.6 dùng chung của nhóm (không lặp nhóm); rồi cập nhật §10 (row khoá theo platform×SC) và thêm một row Changelog. Bump `@trace.revision` và làm mới `@trace.ucs` / `@trace.platforms` ở header, và cập nhật entry của platform vừa đụng trong map `@trace.bdd_versions` (vd set `web=2.0`, giữ nguyên `system`).
-
-<!--
-  ════════════════════════════════════════════════════════════════════════════
-  TEMPLATE: Tài liệu Thiết kế Kỹ thuật (per-PRD, full-stack, gộp)
-  Dùng bởi: /generate-tech-docs
-  ════════════════════════════════════════════════════════════════════════════
-
-  MÔ HÌNH PHẠM VI
-  - MỘT tài liệu cho mỗi PRD (không phải per-UC). Nó bao phủ MỌI use case của PRD
-    trong một thiết kế full-stack gộp: backend (API, mô hình dữ liệu, DB) VÀ client
-    (component, state, tích hợp API) đặt cạnh nhau, nối bằng sequence diagram xuyên
-    tầng. Đây là "bản vẽ thi công" mà bất kỳ dev nào mở ra để implement cả feature.
-  - ĐẦU VÀO là các file BDD của PRD (web/ · app/ · system/), KHÔNG phải văn xuôi PRD.
-    PRD chỉ nạp để lấy bối cảnh Overview/Goals/Actors.
-
-  TĂNG DẦN / APPEND
-  - Khi BDD mới được thêm vào cùng PRD về sau, tài liệu này được MỞ RỘNG, không sinh
-    lại: thêm section + sequence diagram của UC mới, cập nhật ma trận Độ phủ UC (§10)
-    và Changelog. KHÔNG bao giờ đè nội dung có sẵn hay chỉnh tay.
-
-  QUY TẮC ĐIỀN
-  - Thay MỌI placeholder {…} bằng nội dung thật. Xoá các comment hướng dẫn.
-  - THUẬT NGỮ: tuân 100% từ điển dự án (specs/domain-knowledge/business-dictionary.md).
-    Giá trị status/enum → core-entities.md (Enum Registry). Entity → core-entities.md.
-  - Giữ code/DTO/DB mẫu theo idiom stack của dự án (xem stack-profile của module đang
-    dùng). Snippet C#/Angular bên dưới chỉ MANG TÍNH MINH HOẠ — thay bằng stack thật.
-  - Section không áp dụng cho PRD này: GIỮ heading và viết "N/A — {lý do}" thay vì
-    xoá, để cấu trúc luôn nhất quán, dễ đoán.
-  - Mọi sequence diagram / API / rule phải truy vết được về một scenario: tham chiếu
-    id SC (vd UC1-SC3) mà nó phục vụ.
--->
-
-# {Feature Area} — Tài liệu Thiết kế Kỹ thuật: {PRD Title}
-
-<!-- Khối @trace (cấp PRD). ucs = mọi UC mà doc này phủ; nối thêm id khi thêm UC. GIỮ NGUYÊN key @trace.* — máy đọc. -->
----
-@trace.id: {TICKET-ID}
-@trace.domain: {domain}
-@trace.prd: {TICKET-ID}
-@trace.ucs: {TICKET-ID}-UC1, {TICKET-ID}-UC2{, …}
-@trace.service: {service — từ header BDD @trace.service}
-@trace.module: {module liên quan — vd dotnet, angular}
-@trace.platforms: {system | web | app — tuỳ thư mục BDD nào tồn tại}
-@trace.bdd_versions: {MAP theo từng platform — số nhiều, KHÁC @trace.bdd_version (scalar) của .feature — vd system=1.5, web=1.9, app=1.7; chỉ platform có mặt. Mỗi feature mang bdd_version riêng; đừng gộp về một số.}
-@trace.api_source: {existing | —}
-@trace.revision: 1
-@trace.status: draft
-@trace.generated_at: {YYYY-MM-DD}
----
-
-> **Tài liệu liên quan:** {link các PRD / tech-design anh em mà doc này phụ thuộc, vd [OTHER-TICKET](../{other-slug}/tech-docs/{OTHER-TICKET}-tech-design.md)}. Xoá nếu không có.
-
-## 1. Tổng quan (Overview)
-
-<!-- 2–4 câu: feature làm gì, ai dùng, hình dạng kỹ thuật cốt lõi (nguồn dữ liệu,
-     side effect chính). Nêu rõ dữ liệu đến từ đâu (DB vs API ngoài) và thao tác ghi
-     chính. Nguồn: PRD + system BDD. -->
-
-{Feature làm gì, tác nhân chính, và cơ chế kỹ thuật cốt lõi. Nêu rõ dữ liệu nào được
-sở hữu (DB) vs lấy live (API ngoài), và thao tác ghi chính.}
-
-### Mục tiêu (Goals)
-
-<!-- Liệt kê mục tiêu kỹ thuật — suy từ mục tiêu PRD, diễn đạt thành thứ hệ thống
-     phải đảm bảo. -->
-
-- {Mục tiêu 1}
-- {Mục tiêu 2}
-
-### Tác nhân nghiệp vụ (Business Actors)
-
-| Tác nhân | Mô tả | Kênh |
-|-------|-------------|---------|
-| {Actor} | {vai trò & quyền} | {đường vào, vd App → Widget → Portal → API} |
-
----
-
-## 2. Tổng quan Kiến trúc (Architecture Overview)
-
-### 2.1 Kiến trúc tổng thể (High-level Architecture)
-
-<!-- ASCII (hoặc mermaid) topology thể hiện các hệ thống feature này chạm tới:
-     client → gateway → service(s) → data store / API ngoài. Chỉ giữ các component
-     mà PRD NÀY thực sự dùng. Nguồn: architecture.md / project-context.yaml (services, stack). -->
-
-```
-{Sơ đồ ASCII hoặc mermaid các component feature này chạm tới}
-```
-
-> **Lưu ý:** {chỉ ra dữ liệu nào lấy live từ API ngoài vs lưu trong DB sở hữu, và lớp cache + TTL nếu có.}
-
-### 2.2 Mẫu giao tiếp (Communication Patterns)
-
-| Mẫu | Dùng cho | Phạm vi (UC/SC) |
-|---------|-------|---------------|
-| {Client → Gateway → API} | {auth / action} | {UC1} |
-| {API → API ngoài} | {lấy gì, cache TTL} | {UC1-SC…} |
-
----
-
-## 3. Mô hình Dữ liệu (Data Model)
-
-<!-- Nguồn: core-entities.md (entity sở hữu) + mệnh đề Then của BDD (state) + PRD.
-     Phân biệt entity SỞ HỮU (trong DB) với model NGUỒN-API (lấy live, không lưu).
-     Chỉ liệt kê field mà PRD này đọc hoặc ghi. -->
-
-### 3.1 Thiết kế Entity (Entity Design)
-
-#### {EntityName} ({DB entity | POCO nguồn-API})
-
-{Một dòng: nó biểu diễn gì, và được lưu hay lấy live.}
-
-| Field | Kiểu | Dùng trong {TICKET-ID} |
-|-------|------|----------------------|
-| `{field}` | `{type}` | {feature này dùng thế nào — đọc/ghi, SC nào} |
-
-<!-- Lặp lại cho mỗi entity. Nếu feature có chuyển trạng thái đáng kể, thêm bảng/sơ đồ
-     state nhỏ như dưới. -->
-
-**Chuyển trạng thái (nếu có):**
-
-```
-{state A}:  {điều kiện}  → {kết quả / tín hiệu UI}
-{state B}:  {điều kiện}  → {kết quả}
-```
-
-**Ràng buộc:**
-- {invariant enforce ở tầng application/DB, vd đúng một primary cho mỗi tenant}
-
-### 3.2 Quan hệ Entity (Entity Relationships)
-
-```
-{sơ đồ quan hệ — cardinality, khoá join, field nào read-only vs sở hữu}
-```
-
-### 3.3 Ranh giới Nguồn dữ liệu (Data Source Boundaries)
-
-<!-- Phát biểu gọn PRD NÀY đọc gì vs ghi gì, và cái gì được uỷ thác nơi khác.
-     Chống lem phạm vi. -->
-
-**Phạm vi {TICKET-ID}: {ĐỌC … / GHI …}.**
-
-| Trách nhiệm | Trong phạm vi? | Do ai xử lý |
-|----------------|-----------|-----------|
-| {đọc list đã gộp} | ✅ Có | {endpoint / service} |
-| {ghi cờ X} | ✅ Có | {service} |
-| {dữ liệu gốc} | ❌ Read-only | {API ngoài + cache} |
-| {mối lo module khác} | ❌ Không | {module/team} |
-
-### 3.4 Multi-tenant & Sharding
-
-<!-- Chỉ khi dự án multi-tenant. Nếu không, viết "N/A — single tenant". -->
-
-- {khoá tenant trên entity, cách ly bằng query-filter, phân giải shard — từ architecture.md}
-
----
-
-## 4. Hợp đồng API (API Contracts)
-
-<!-- Contract backend. Greenfield: thiết kế endpoint từ scenario BDD. Brownfield
-     (@trace.api_source = existing): reverse-document API đang chạy as-is và ghi chú
-     gap so với kỳ vọng BDD. Đánh dấu REUSE vs NEW rõ ràng.
-     PRD CHỈ-CLIENT (không có BDD system/ — feature này không sở hữu backend): ĐỪNG
-     bịa contract BE. §4.1 khi đó liệt kê các endpoint mà client TIÊU THỤ (ngoài /
-     bên thứ ba / của team khác / có sẵn), đánh dấu "consumed (external)",
-     reverse-document từ mệnh đề Then của BDD client + PRD; chỉ điền §4.2/§4.3 nếu
-     biết shape. Nếu feature không gọi mạng gì cả → viết "N/A — client-only, no backend".
-     §4.5.4 ánh xạ method client tới bất cứ gì §4.1 liệt kê (hoặc không có). -->
-
-
-### 4.1 Endpoints
-
-```
-{METHOD} {/path}          # NEW | REUSE ({nguồn}) — {mục đích một dòng}
-```
-
-### 4.2 Model Request/Response (Request/Response Models)
-
-<!-- Thể hiện shape DTO theo idiom của stack. Ghi rõ field nào đến từ DB vs API ngoài. -->
-
-```{lang}
-{định nghĩa DTO kèm comment nguồn từng field}
-```
-
-### 4.3 Validation & Mã lỗi (Validation & Error Codes)
-
-**Quy tắc validation:**
-
-```{lang}
-{quy tắc validation, theo idiom stack (vd FluentValidation / class-validator)}
-```
-
-| Code | HTTP Status | Mô tả | Trace |
-|------|-------------|-------------|-------|
-| `{ERROR_CODE}` | {4xx/5xx} | {khi nào phát sinh} | {UC1-SC…} |
-
-### 4.4 Logic Handler (endpoint chính)
-
-<!-- Với các thao tác ghi không tầm thường, viết rõ các bước có thứ tự (validation →
-     transaction → commit/rollback → return). Giữ sequence diagram và code khớp nhau. -->
-
-**{HandlerName}:**
-1. {bước}
-2. {bước — ranh giới transaction nếu có}
-
-### 4.5 Ánh xạ Component UI (UI Component Mapping) — {platform} ({framework})
-
-<!-- Thiết kế CLIENT, NHÓM THEO PLATFORM: một section "### 4.5 … — {platform}" cho mỗi
-     platform client có trong BDD (một nhóm web, một nhóm app). ĐỪNG đặt tên heading
-     này theo màn hình — màn hình/UC nằm ở các sub-block bên dưới.
-     Bên trong một nhóm platform:
-       • §4.5.1 Cây Component — lặp sub-block theo màn hình/UC:
-         "#### 4.5.1.x {Screen} — {UC}". Một PRD nhiều màn hình/UC → nhiều sub-block
-         trong CÙNG nhóm platform (không bao giờ tạo nhóm 4.5 thứ hai cho cùng platform).
-       • §4.5.2–§4.5.5 — tương tự theo màn hình/UC ở chỗ chúng khác nhau.
-       • §4.5.6 Test Selectors — MỘT bảng dùng chung cho cả nhóm platform; cột
-         "Phục vụ SC" mang (UC · SC) để consumer per-UC lọc row của mình.
-     Append: platform mới → nhóm "### 4.5 — {platform}" mới; màn hình/UC mới trong
-     platform đã có → thêm sub-block + row vào §4.5.6 (đừng lặp nhóm).
-     Bỏ hẳn §4.5 với PRD backend-only. -->
-
-> **Nguồn:** {file Figma + node id, từ design-spec}
-> **Stack:** {framework, state primitive, thư viện component}
-> <!-- @figma.url: {url figma cấp node} -->
-
-#### 4.5.1 Cây Component (Component Hierarchy) — {Screen} ({UC})
-
-<!-- Lặp sub-block này theo màn hình/UC trong nhóm platform này (4.5.1.a, 4.5.1.b …). -->
-
-```
-{cây component — container vs presentational, con có điều kiện}
-```
-
-#### 4.5.2 Ánh xạ file Component (Component File Mapping)
-
-| Component | Path | Loại | Trách nhiệm |
-|-----------|------|------|---------|
-| `{Component}` | `{path}` | {Feature/Child} | {trách nhiệm} |
-
-#### 4.5.3 Quản lý State (State Management) ({state primitive})
-
-<!-- Shape state suy từ mệnh đề Then của System BDD + shape response từ §4.2.
-     Thể hiện giá trị dẫn xuất/tính toán và input của chúng. -->
-
-```{lang}
-{khai báo state kèm comment nguồn (mỗi cái map tới field BDD / field BE nào)}
-```
-
-#### 4.5.4 Tầng tích hợp API (API Integration Layer — port/adapter)
-
-<!-- Cấu hình modal/route + bản đồ tích hợp API: mỗi method service client → một
-     endpoint THẬT từ §4.1 (đừng bịa endpoint). Lỗi → state UI theo từng SC.
-     Bảng này là thứ /generate-code --phase=integration đọc để wire adapter thật. -->
-
-| Method client | Endpoint (§4.1) | Map request | Response → model | Lỗi → UI |
-|---------------|-----------------|-------------|------------------|-----------|
-| {svc.getX()} | {GET /…} | {params} | {DTO → ViewModel} | {4xx → state/toast} |
-
-#### 4.5.5 Ánh xạ Figma → Design System
-
-| Element Figma | Class/token design system | Ghi chú |
-|---------------|---------------------------|-------|
-| {element} | {class / token} | {size, màu, state} |
-
-#### 4.5.6 Test Selectors — id element cho phần tử có action (hợp đồng QC)
-
-<!-- Test-id ổn định cho mỗi element tương tác để QC định vị trực tiếp (không scan
-     runtime). Quy ước: {uc-lower}-{screen}-{element}-{type}; ĐỪNG nhúng số scenario.
-     Attribute theo platform: web data-testid · RN testID · Flutter Key/Semantics ·
-     iOS accessibilityIdentifier. Dùng lại CÙNG giá trị id trên web/app cho cùng một
-     element logic.
-     MỘT bảng dùng chung cho cả nhóm platform (phủ mọi màn hình/UC của platform này).
-     Cột "Phục vụ SC" mang (UC · SC) để consumer per-UC (generate-code / qc) lọc row
-     của mình qua §10. Nhóm §4.5 này vốn đã theo platform, nên platform là ngầm định
-     (khối web → web · SC). -->
-
-| Test-ID | Element | Component (§4.5.1.x) | Action | Phục vụ SC (UC · SC) |
-|---------|---------|----------------------|--------|---------------------|
-| `{uc}-{screen}-{element}-{type}` | {Nút submit} | {Component} | {submit} | {UC1 · SC1, UC1 · SC3} |
-
----
-
-## 5. Luồng chính (Key Flows — Sequence Diagrams)
-
-<!-- MỘT mermaid sequence diagram cho mỗi scenario đáng kể. Participant xuyên tầng:
-     component client → service → API → API ngoài → DB.
-     ⚠ id SC chỉ duy nhất trong phạm vi (UC × platform): `{UC}-SC1` ở `system` và
-     `{UC}-SC1` ở `web` là HAI scenario KHÁC nhau. Nên gom luồng vào các LANE PLATFORM
-     (5.A system · 5.B web · 5.C app) và LUÔN ghi kèm platform với SC, vd
-     "(web · UC1-SC1)". Đừng bao giờ viết "UC1-SC1" trơ ở đây — mơ hồ.
-     Chỉ đưa các lane có BDD tồn tại trong PRD này. -->
-
-### 5.A Luồng System
-
-<!-- Một diagram cho mỗi scenario system-BDD. Bỏ lane này nếu không có BDD system/. -->
-
-#### 5.A.1 {tên} (system · {UC}-SC…)
-
-```mermaid
-sequenceDiagram
-    participant {A} as {Actor}
-    {…}
-```
-
-### 5.B Luồng Web
-
-<!-- Một diagram cho mỗi scenario web-BDD. Bỏ lane này nếu không có BDD web/. -->
-
-#### 5.B.1 {tên} (web · {UC}-SC…)
-
-```mermaid
-sequenceDiagram
-    {…}
-```
-
-### 5.C Luồng App
-
-<!-- Một diagram cho mỗi scenario app-BDD. Bỏ lane này nếu không có BDD app/. -->
-
-#### 5.C.1 {tên} (app · {UC}-SC…)
-
-```mermaid
-sequenceDiagram
-    {…}
-```
-
-<!-- Đánh số trong từng lane: 5.A.1, 5.A.2 … / 5.B.1 … / 5.C.1 …. Với scenario mà
-     hiệu ứng lấn sang module khác, ghi "(covered by {OTHER-UC})". -->
-
-**Điểm tích hợp chính (bảng tuỳ chọn cho mỗi luồng):**
-
-| Bước | Chuyển trạng thái | Verify bởi (platform · SC) |
-|------|------------------|-----------------------------|
-| {bước} | {trước → sau} | {web · UC1-SC…} |
-
----
-
-## 6. Điểm tích hợp (Integration Points)
-
-| Tích hợp | Chiều | Phương thức | Mô tả |
-|-------------|-----------|--------|-------------|
-| {Client → API} | Outbound (client) | {REST/Bearer} | {gì} |
-| {API → Ngoài} | Outbound (server) | {REST + header} | {gì, cache TTL} |
-
-### 6.1 Event Bus / Messaging
-
-<!-- Event Kafka/queue mà feature này produce/consume. "N/A — no events" nếu không có. -->
-
-{events, hoặc N/A}
-
-### 6.2 Phụ thuộc Cross-Service (Cross-Service Dependencies)
-
-| Service phụ thuộc | Cần gì | Contract | Trạng thái |
-|-------------------|---------------|----------|--------|
-| {service} | {cần} | {endpoint} | {✅ Có / ⚠️ pending} |
-
----
-
-## 7. Bảo mật & Phân quyền (Security & Authorization)
-
-### 7.1 Xác thực (Authentication)
-
-{Luồng auth + loại token/TTL. Nguồn: auth PRD + rule dự án.}
-
-### 7.2 Quy tắc Phân quyền (Authorization Rules)
-
-| Action | Role/quyền yêu cầu | Mô tả | Trace |
-|--------|--------------------------|-------------|-------|
-| {action} | {role} | {enforce thế nào, ở đâu} | {UC1-SC… / ngoài phạm vi} |
-
----
-
-## 8. Xử lý lỗi & Trường hợp biên (Error Handling & Edge Cases)
-
-<!-- Một row cho mỗi scenario lỗi / biên / âm trong BDD. Phải khớp với mã lỗi §4.3
-     và các sequence diagram lỗi §5. -->
-
-| Scenario | Chiến lược | Chi tiết | Trace |
-|----------|----------|---------|-------|
-| {điều kiện} | {cách xử lý} | {hành vi, message, side effect} | {UC1-SC…, BR…} |
-
----
-
-## 9. Quyết định Thiết kế (Design Decisions)
-
-<!-- Cái "vì sao" đằng sau các lựa chọn không hiển nhiên, kèm phương án đã cân nhắc.
-     Nguồn: alternatives/assumptions của PRD + lập luận lúc sinh. Đây là thứ giúp
-     reviewer tin tưởng thiết kế. -->
-
-| # | Quyết định | Lý do | Phương án đã cân nhắc |
-|---|----------|-----------|-------------------------|
-| 1 | **{quyết định}** | {vì sao} | {phương án — vì sao loại} |
-
-### Ánh xạ NFR → Thiết kế (NFR-to-Design Mapping)
-
-| Nhóm NFR | Yêu cầu PRD | Quyết định thiết kế |
-|--------------|-----------------|-----------------|
-| {vd Cách ly multi-tenant} | {yêu cầu} | {cơ chế} |
-
----
-
-## 10. Độ phủ UC (UC Coverage)
-
-<!-- ĐIỂM NEO ĐỂ APPEND **và là MỤC LỤC cho consumer per-UC**. Mọi UC của PRD có một
-     row; mọi scenario map tới (các) section thiết kế nó.
-     - /generate-tech-docs dùng nó để phát hiện cái gì đã phủ vs còn thiếu.
-     - /generate-code, /map-testids, /qc-* làm việc trên MỘT UC của doc cấp-PRD — chúng
-       tra UC này Ở ĐÂY trước để định vị scenario của nó → các section/lane-§5 (và do đó
-       các endpoint §4.1 mà luồng §5 của nó gọi) thuộc về nó. Đừng lấy
-       endpoint/section của UC khác.
-     ⚠ Độ phủ scenario khoá theo (platform, SC) vì id SC lặp giữa các platform —
-     cột Platform để phân biệt. -->
-
-| UC | Feature | Platforms | Section phủ | Trạng thái |
-|----|---------|-----------|------------------|--------|
-| {TICKET-ID}-UC1 | {title} | {system, web, app} | §… | ✅ Covered |
-
-### Độ phủ Scenario UC1
-
-<!-- Một row cho mỗi (platform, SC). Cùng số SC ở platform khác nhau = scenario khác
-     nhau → row riêng. -->
-
-| Platform | Scenario | Section | Business rule |
-|----------|----------|---------|---------------|
-| system | {UC}-SC1: {tên} | §5.A.1 | {BR…} |
-| web | {UC}-SC1: {tên} | §4.5 (web), §5.B.1 | {BR…} |
-
-<!-- Lặp một khối scenario-coverage cho mỗi UC. -->
-
----
-
-## 11. Cross-cutting & Giả định (Tham chiếu ngoài phạm vi)
-
-<!-- Các mối lo upstream mà PRD này PHỤ THUỘC VÀO nhưng không implement (cổng admin,
-     UI downstream ở module khác, snapshot đơn hàng…). Giữ để có bối cảnh liên team.
-     Tham chiếu UC/team sở hữu + doc. Nguồn: out-of-scope của PRD + ghi chú BR
-     "out of scope" trong BDD. -->
-
-### 11.1 {Mối lo}
-
-> {Trích câu BDD/PRD đã scope nó ra ngoài.}
-
-{Giải thích ranh giới + một sequence diagram tham chiếu nếu hữu ích.}
-
-**Sở hữu bởi:** {team / module}. Xem {link}.
-
----
-
-## 12. GAP Register — ẩn số thiết kế chưa chốt
-
-<!--
-  Mọi [GAP: Gn] / [ASSUMPTION: An] đánh dấu inline trong doc PHẢI có đúng MỘT dòng ở đây
-  (và ngược lại — không marker mồ côi, không dòng thừa). Đây là sổ quản lý vòng đời ẩn số.
-
-  - Loại:
-      • nội tại      — BE tự quyết (đóng: BE điền giá trị, thay marker)
-      • cross-service — cần team/partner khác (đóng: qua T7 sign-off của owner)
-      • spec-defect  — BDD/PRD sai/thiếu (KHÔNG tự đóng: escalate PO sửa .feature/PRD → regen; xem §9 Conflict)
-  - Severity:
-      • 🔴 blocker    — code BẮT BUỘC phải có mới đúng → CHẶN approve
-      • 🟢 non-blocker — đoán tạm chạy được, chỉ cần confirm → không chặn
-    (Nhãn GAP/ASSUMPTION KHÔNG tự quyết severity — một ASSUMPTION vẫn có thể là blocker nếu đoán sai sẽ vỡ.)
-  - Status: open → resolved (owner điền giá trị thật → thay marker inline → bump @trace.revision).
-
-  GATE: còn ≥1 🔴 blocker ở trạng thái `open` → @trace.status KHÔNG được lên `approved`
-        (giữ `in-review`) → generate-code bị chặn. Cùng pattern design-spec giữ `draft` khi còn ❌ Missing.
--->
-
-| id | Dùng ở (§) | Điều chưa biết | Loại | Owner confirm | Severity | Status | Đóng thế nào |
-|----|-----------|----------------|------|---------------|----------|--------|--------------|
-| G1 | {§4.3} | {shape lỗi khi partner từ chối} | cross-service | {team-payment} | 🔴 blocker | open | {T7 sign-off — owner cung cấp contract} |
-| A1 | {§4.1} | {timeout mặc định 30s} | nội tại | {BE lead} | 🟢 non-blocker | open | {BE xác nhận, thay giá trị} |
-
-> Nếu doc **không có** ẩn số nào → ghi "Không có — mọi thiết kế đều có nguồn." **KHÔNG** bịa dòng để lấp trống.
-
----
-
-## Tham chiếu Thiết kế Figma (Figma Design References)
-
-<!-- @figma.url: {url figma cấp node cho mỗi màn hình} -->
-- {Screen}: [Figma — {frame}]({url})
-- Exported: {YYYY-MM-DD}
-
----
-
-## Changelog
-
-| Revision | Ngày | Thay đổi |
-|----------|------|---------|
-| 1 | {YYYY-MM-DD} | Sinh lần đầu từ BDD {TICKET-ID} (v{bdd_version}): {liệt kê UC đã phủ} |
-<!-- Khi append: thêm một row cho mỗi lần mở rộng, vd "2 | {ngày} | Thêm UC3 (§5.9, §10) từ BDD mới v{n}" -->
-
-
----
-
-## Self-Review Gate — REFUTE trước khi ghi *(bắt buộc; chạy cả Fresh lẫn Append)*
-
-Trước khi finalize/append doc, **tự phản biện bản nháp** qua 4 cổng dưới — không phải "sinh rồi tin", mà "sinh rồi ĐỐI CHIẾU với ngữ cảnh rộng hơn + khai GAP tường minh". Nguyên tắc nền: **Completeness ≠ Coverage** — "mọi SC được map" là *cần*, KHÔNG *đủ*; trung thành với lát BDD trước mặt không phải là đúng khi nó chỉ là một lát cắt. Cổng nào không đạt → **sửa, hoặc khai `[GAP]` / `[ASSUMPTION: {owner} confirm]` ngay tại chỗ trong doc** — TUYỆT ĐỐI không bỏ trắng, không bịa lặng.
-
-**Cổng 1 — RECONCILE (đối chiếu chéo, đọc-ngược CÓ GIỚI HẠN).**
-Đọc-ngược **bounded** — chỉ 3 nguồn này, KHÔNG kéo toàn bộ BDD của PRD (giữ batch nhỏ):
-- **PRD Business Rules** của UC → mọi BR có được §3/§4/§5 phản ánh? Nguồn/sự kiện nào BR yêu cầu mà doc thiếu → thêm, hoặc `[GAP]`.
-- **core-entities.md** → mỗi enum/trạng thái doc dùng có **producer** (ai sinh ra giá trị)? Mỗi cột/field có **writer** (luồng nào set)? Enum mồ côi / cột không writer → sửa hoặc flag.
-- **Seam UC anh em cùng domain** (chỉ endpoint/entity giao nhau) → không định nghĩa lại contract đã có ở UC khác; không tự mâu thuẫn enum mình vừa viết trong chính doc này.
-
-**Cổng 2 — GAP-or-FLAG (trung thực, không bịa).**
-Cần một type/giá trị/policy (auth, config, event, error code) mà **không có nguồn** → **không** chép hình dạng ở boundary, **không** bịa: ghi `[GAP]` hoặc `[ASSUMPTION: {owner} confirm]`. Nếu doc định thiết kế endpoint/flow mà **BDD không định nghĩa nghiệp vụ** (design vượt BDD) → khai GAP + escalate, đừng âm thầm hợp thức hoá.
-
-**Cổng 2b — Client integration (§4.5.4) cũng phải đủ, không chỉ contract BE.** Với MỖI client method mà một màn hình/UC cần, §4.5.4 phải map đủ: **endpoint thật ở §4.1 · nguồn field request/response · error→UI**. Bất kỳ mảnh nào không suy được từ nguồn → khai `[GAP]` + một dòng §12 (đừng để §4.5.4 khuyết một phần rồi lọt xuống `/generate-code --phase=integration` — đó chính là chỗ FE bị hỏi live). **Severity blocker (🔴)** nếu màn hình không render/hoạt động được khi thiếu mapping đó (→ giữ `@trace.status: in-review`, chặn code-gen tới khi đóng); non-blocker (🟢) nếu chỉ là chi tiết phụ đoán tạm được. Đối xứng với contract BE: front-load ẩn số client về tech-docs, đừng đẩy sang lúc wire adapter.
-
-**Cổng 3 — CATALOG (không hard-code).**
-Literal & constant rải rác như luật → gom lại: **generic envelope** (đừng typed-per-thing khi PRD-BR đã đưa hợp đồng chung) + bảng catalog (vd `signal_type × source`) + constants **đặt tên**. Fail nếu còn hằng số/enum inline chưa vào catalog.
-
-**Cổng 4 — CROSS-SERVICE & COMPLETENESS.**
-- **Ranh giới:** không kéo định danh **nội bộ** service khác vào lookup của mình — dùng abstraction tầng mình. Tương tác 2 service: nói rõ **bên nào own dedup/ordering** + có **ack path** + cross-field invariant.
-
-  > **Thuật ngữ (đọc nhanh):**
-  > - **dedup** (khử trùng) — cùng một event/message tới **≥2 lần** thì chỉ được xử lý **một** lần (thường qua *idempotency key*). Thiếu → cộng đôi, ghi đôi.
-  > - **ordering** (thứ tự) — event tới **đúng trình tự** phát ra; nếu có thể tới lệch thì chốt: bên nào sắp lại, hay bên nhận phải **chịu được** lệch. Thiếu → state sai (vd "hết hạn" xử lý trước "tạo mới").
-  > - **ack path** (đường xác nhận) — bên nhận xử lý xong **báo lại** bên gửi ("đã nhận/đã xử lý") để bên gửi ngừng gửi lại. Thiếu → mất event, hoặc gửi lại vô hạn.
-  > - **cross-field invariant** — ràng buộc phải **luôn đúng** giữa nhiều field/entity (vd `tổng các phần = tổng`, `trạng thái = paid ⇒ paid_at ≠ null`).
-- **Không happy-only:** mỗi API/flow phải **xét đủ** nhánh happy + partial + error + rollback, kể cả khi BDD chỉ tả happy. Thiết kế nhánh lỗi **từ nguồn** (PRD-BR về xử lý thất bại · pattern rollback ở CLAUDE.md §2 · chuyển-trạng-thái entity ở core-entities). Chi tiết nào **không suy được từ nguồn** (error code/shape của service khác, quyết định retry-hay-fail…) → **khai `[GAP]`, KHÔNG bịa** (Cổng 2). *Bắt buộc CÓ nhánh lỗi ≠ bịa NỘI DUNG nhánh lỗi.*
-- **Đủ chi tiết hàm:** hàm cốt lõi tả **điều kiện chọn / nhánh / kết quả**, không dừng ở tên hàm + sequence-diagram.
-
-**Ghi sổ + cổng chặn (bắt buộc khi có GAP).** Mỗi `[GAP: Gn]`/`[ASSUMPTION: An]` khai inline PHẢI có đúng **một** dòng ở **§12 GAP Register** (không marker mồ côi), gán:
-- **Loại**: `nội tại` (BE tự quyết) · `cross-service` (team/partner khác — đóng qua T7 sign-off) · `spec-defect` (BDD/PRD sai → escalate PO, xem Conflict register dưới).
-- **Severity**: 🔴 `blocker` (code bắt buộc phải có mới đúng) · 🟢 `non-blocker` (đoán tạm chạy được, cần confirm). Nhãn GAP/ASSUMPTION **không** tự quyết severity — một ASSUMPTION vẫn có thể là blocker.
-- **Owner** phải confirm + **Status** = `open`.
-
-Nếu §12 còn **≥1 🔴 blocker `open`** → set `@trace.status: in-review` (KHÔNG để `approved`) — `generate-code` bị chặn tới khi đóng hết blocker. (Cùng pattern design-spec giữ `draft` khi còn ❌ Missing.) Nếu 0 ẩn số → §12 ghi "Không có", đừng bịa dòng.
-
-> **Conflict register:** nếu BDD **mâu thuẫn** một invariant kiến trúc (CLAUDE.md §2 / core-entities) → ghi vào §9 Design Decisions như **conflict cần PO sửa `.feature`** (và một dòng §12 loại `spec-defect`), KHÔNG tự quyết, KHÔNG lặng chép.
-
-> **Guardrail nguồn:** 4 cổng này phản chiếu `project-lessons` **L-012** (nếu project có) — nạp ở context-loader Bước 6.7 như ràng buộc cứng, sống sót qua `/update-framework`. Cổng ở đây là lớp framework; L-012 là lớp project-local; cả hai cùng hiệu lực. `/review-tech-docs` **T8/T9** bắt lại ở cổng review nếu gen bỏ lọt.
-
-Ghi số `[GAP]`/`[ASSUMPTION]` đã khai vào report Output.
-
----
-
-## Công bố — chia sẻ doc (umbrella + spec repo dùng chung)
-
-Nếu `paths.tech_docs_dir` phân giải **dưới `setup.spec_source`** (vd `{spec_source}/specs/{domain}/{prd-slug}/tech-docs`), doc được ghi **bên trong spec submodule**. Công bố nó (commit 2 tầng) để cả team đọc qua `/sync` — tech design gộp per-PRD này là blueprint liên team (API contract cho BE, client design cho FE/App):
-
-```bash
-cd {spec_source}
-git add {output_path}                   # {TICKET-ID}-tech-design.md
-git commit -m "docs({TICKET-ID}): full-stack technical design ({mode})"
-git push origin {spec_branch}           # branch teammate theo dõi trong .gitmodules
-cd -
-git add {spec_source} && git commit -m "chore: bump spec pointer ({TICKET-ID} tech design)"
-```
-
-Nếu `tech_docs_dir` là **local** — tức không có `setup.spec_source` (single-repo, hoặc một BE repo đa-service thuần không có spec module dùng chung) — bỏ qua bước này; không cần publish liên-repo.
-
-## Output
-
-# Report Footer — Định dạng output chuẩn cho mọi lệnh
-
-Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
-
-## Status Badge
-
-Chọn một theo kết quả:
-- `✅ Complete` — mọi bước thành công, không có vấn đề
-- `❌ Failed` — lệnh không hoàn thành được do lỗi chặn
-- `⚠️ Warnings` — hoàn thành nhưng có vấn đề không chặn, nên review lại
-
-## Output Artifacts
-
-Liệt kê mọi file được tạo hoặc sửa bởi lệnh này:
-```
-Output Artifacts:
-  {created|updated} {file-path} ({mô tả ngắn})
-  {created|updated} {file-path} ({mô tả ngắn})
-```
-
-Nếu không ghi file nào (vd: lệnh review hoặc phân tích) → ghi `Output Artifacts: none (read-only)`.
-
-## Pipeline Position
-
-In một sơ đồ pipeline một dòng, đánh dấu phase của lệnh HIỆN TẠI bằng `◀ bạn ở đây`,
-để người dùng luôn thấy lệnh này nằm ở đâu trong luồng end-to-end:
-
-```
-Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-```
-
-Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **phase của nó** trong sơ đồ trên:
-
-| Phase | Commands |
-|-------|----------|
-| Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/extend-prd` · `/refine-prd` · `/review-context` (PRD) |
-| Design Spec | `/generate-design-spec` |
-| BDD | `/generate-bdd` · `/review-context` (BDD) |
-| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
-| Code | `/generate-code` · `/review-code` |
-| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
-| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
-| Trace Audit | `/validate-traces` |
-
-Với **lệnh review**, thêm vòng review 3 bước và đánh dấu bước hiện tại, vd:
-`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
-
-**Lệnh xuyên suốt** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
-`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) nằm ngoài pipeline tuyến tính —
-**bỏ hẳn dòng Pipeline** cho các lệnh này (đừng cố nhét chúng vào sơ đồ).
-
-## Gợi ý lệnh tiếp theo
-
-Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
-
-| Lệnh hiện tại           | Gợi ý lệnh tiếp theo                          |
-|-------------------------|-----------------------------------------------|
-| /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
-| /define-product         | `/generate-prd {product-definition-file}`     |
-| /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
-| /extend-prd             | `/refine-prd {prd-file}` (soi phần vừa thêm) rồi `/review-context {prd-file}` → PO duyệt → `/generate-bdd` **chỉ cho UC MỚI**; UC cũ dùng `/validate-traces --realign-prd-version {UC-ID}` |
-| /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
-| /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
-| /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
-| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
-| /qc-analyze             | `/qc-plan {UC-ID}` (xử lý các gap blocker 🔴 trước) |
-| /qc-plan                | `/qc-design-test {UC-ID}`                     |
-| /qc-design-test         | `/qc-review {UC-ID}` (review test-case)       |
-| /qc-review (test-case)  | `/qc-run-test {UC-ID}` nếu APPROVED; sửa TC nếu NEEDS_FIX |
-| /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
-| /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
-| /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
-| /map-testids            | `/qc-design-test {UC-ID}` (QC dựng Page Object từ contract §4.5.6 vừa ghi) |
-| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
-| /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
-| /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/dev-gen-test {UC-ID}` |
-| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
-| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
-| /dev-run-test (failing)    | `/fix-bug {ticket-id}` hoặc `/debug {error}`    |
-| /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
-| /dev-smoke-test             | Tạo PR và link tới ticket                  |
-| /validate-traces        | **Cờ 🔴 trước (chặn PR):** SEAM_UNWIRED → nối binding sang class thật, xoá/thay stub · STUB_UNRESOLVED → `/generate-code {owner_uc}` (lấp logic tại chỗ + xoá hàm song song) · ORPHANED/TRACE_ORPHAN → quyết định thủ công (xoá code+test, đưa scenario trở lại `.feature`, hoặc sửa `sc_id` của tag). **Rồi:** DRIFT/UNTRACKED → `/generate-code {UC-ID}` · BDD_DRIFT → `/generate-code {feature-file}` · tech-doc lỗi thời vs BDD → `/generate-tech-docs` → `/review-tech-docs` · PRD drift → `/generate-bdd {prd-file}` · GAP → `/dev-gen-test {UC-ID}`. **Chỉ tạo PR khi mọi cờ 🔴 = 0** |
-| /fix-bug                | `/dev-run-test {UC-ID}` (dev_selftest vừa reset về not_run) → tạo PR; nếu fix một `{BUG-ID}` → QC chạy `/qc-run-test {UC-ID}` để verify + đóng bug |
-| /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
-| /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | **Case A** (thiếu scenario cho AC có sẵn) → báo PO/Dev review trong `feedback/bdd-proposals/`; `/generate-bdd` tự chèn khi `Status: accepted`. **Case B** (requirement mới) → `feedback/prd-change-requests/` — PO phải đưa vào PRD trước, KHÔNG tự vào BDD được; `/validate-traces` nhắc lại kèm số ngày chờ chừng nào `Status: Open` |
-| /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
-| /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
-| /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |
-
-Định dạng footer như sau:
-```
----
-Status   : {badge}
-{khối Output Artifacts}
-Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-           (lệnh review) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
-Next     : {lệnh gợi ý kèm ví dụ tham số}
-```
-*(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
-
-
-```
-/generate-tech-docs hoàn tất — {TICKET-ID}  (tech design full-stack, {mode})
-File: {output_path}
-Lần này: {UC/platform của batch đã thiết kế}   |   Doc giờ phủ: {mọi UC trong §10}
-Self-review: {n} [GAP]/[ASSUMPTION] đã khai   ← resolve/confirm với owner trước khi /review-tech-docs
-Next: /review-tech-docs {output_path}
-      ← cần SA/Lead review trước khi sinh code
-      → nếu sống trong spec repo dùng chung: commit + push spec submodule (xem Công bố ở trên) để teammate đọc qua /sync
-      → sau khi approved:
-          BE → /generate-code {system .feature}
-          FE → /generate-code {web|app .feature} --phase=integration   (wire API thật theo §4.5.4 của doc này)
-```