# /validate-traces — Traceability Coverage Matrix

Check read-only độ phủ giữa spec, code, và test — gồm cả PRD version drift.

## 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  : claude-opus-4 (hoặc 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 dễ bỏ sót edge case.

  Cách đổi trong Claude Code:
    • Settings → Model → chọn "claude-opus"
    • hoặc: /model → chọn claude-opus

  Đang chạy claude-opus?
    Y — đúng, đang dùng claude-opus → 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 claude-opus rồi chạy lại lệnh này."

## Bước 1 — Xác định Target File

1. Nếu `$ARGUMENTS` đượ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**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-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ì.


*Lưu ý: Với lệnh này, target ở Bước 1 là một tên domain hoặc UC-ID cụ thể từ `$ARGUMENTS`. Không có một file đơn để phân giải — lệnh quét nhiều thư mục.*

## 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.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`
- `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`

**2. Route tới service** — nếu active domain khớp với một key trong `services`:
- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, MỌI BDD (web/app/**system**) là artifact dùng chung liên team → để bước 4 route sang spec repo; KHÔNG pin theo service ở đây.
- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **chỉ khi `setup.spec_source` KHÔNG được đặt.** Khi `spec_source` ĐƯỢC đặt, tech-design (API contract) là artifact liên team và phải nằm trong spec repo dùng chung (xử lý ở bước 4), nên để bước 4 route `tech_docs_dir` — KHÔNG pin theo service ở đây.
- 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`)

**3. Fallback** — nếu không phát hiện được domain hoặc không có service key khớp:
- Giữ path mặc định từ Bước 1
- Đặt `active_service = unresolved`

**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 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` |
| `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ó}
Service   : {active_service} ({active_service_module}) | 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.


---

## Process

### Step 0 — Umbrella Mode Detection

Kiểm tra mảng `services` có tồn tại trong `project-context.yaml` không.

**Nếu `services` tồn tại (umbrella mode):**
- Phân giải trace dir:
  - **Nếu `setup.spec_source` được set (consolidated trace):** `all_trace_dirs = [ {spec_source}/.trace ]` — một vị trí authoritative **duy nhất** trong spec repo. Scenario mang service sở hữu qua field `@trace.service`, nên không cần tách theo service. Đây là trường hợp phổ biến.
  - **Else (không có spec_source — legacy per-service trace):** một dir mỗi service — `services[N].trace_dir` nếu set, else `{services[N].path}/.trace`; `all_trace_dirs = [ dir1, dir2, … ]`, gắn tag tên service khi đọc.
- Step 1 đọc TSV từ `all_trace_dirs`.
- **Phân giải Living Docs home (vị trí report sinh ra):**
  - Nếu `setup.spec_source` được set → `living_docs_dir = {spec_source}/.living-docs`
    *(specs module dùng chung — mount trong mọi service/umbrella workspace, nên panel phân giải nó bất kể dev đứng ở submodule nào)*
  - Else (umbrella không có spec repo riêng) → `living_docs_dir = .living-docs` ở umbrella root
- **Phân giải panel mirror:** `panel_mirror = ./.trace` ở **gốc workspace hiện tại** (nơi lệnh chạy). Panel VS Code đọc `.trace/trace-report.json` từ workspace đang mở — ghi report ở đây là cái làm view không rỗng khi dev mở một service submodule trực tiếp.

**Nếu không có key `services` (single-service mode):**
- Set `all_trace_dirs = [ {paths.trace_dir} ]`
- Không cần umbrella sync

---

### Step 1 — Nạp dữ liệu TSV

**Umbrella mode:** đọc tất cả file `{trace_dir}/**/*.tsv` từ mọi dir trong `all_trace_dirs`. Với mỗi TSV, gắn tag row với tên service gốc.

**Single-service mode:** đọc tất cả file `{paths.trace_dir}/{domain}/**/*.tsv` khớp domain target (hoặc `{paths.trace_dir}/**/*.tsv` cho mọi domain nếu không có domain filter).

Mỗi file cho trace state đã lưu của UC đó.

**Nếu không tìm thấy file `.tsv` nào** trong bất kỳ trace dir nào:
- Quét tất cả file `{paths.specs_dir}/**/*.feature` trong domain target để dựng list in-memory mọi scenario.
- Coi mọi scenario là `UNTRACKED` (chưa sinh code).
- In: "⚠️ No trace files found. All {N} scenarios across {M} UCs are UNTRACKED."
- Đề xuất: "Run `/generate-bdd {prd-file}` to initialize trace state, or `/generate-code {feature-file}` to generate code."
- **Bỏ qua hoàn toàn Step 2–6.** Đi thẳng tới Step 7 dùng state in-memory này — ĐỪNG abort.

### Step 2 — Reconcile với file `.feature` hiện tại

Mỗi file trace là `{UC-ID}-{platform}.tsv` (một sổ / UC × platform). Với mỗi row, đọc file `.feature` **của đúng platform đó** (`{specs_dir}/{domain}/{prd-slug}/bdd/{platform}/{UC-ID}*.feature` — platform lấy từ tên file TSV) và lấy `@trace.sc_version` **hiện tại** cho SC đó.
Nếu version SC trong `.feature` khác `spec_ver` của `.tsv` → cập nhật `spec_ver` trong memory (sẽ ghi lại).

Cũng phát hiện SC có trong `.feature` (platform đó) nhưng thiếu trong `.tsv` → thêm row mới với `status: UNTRACKED`. *(sc_id trùng số giữa các platform là 2 scenario khác nhau → mỗi sổ platform giữ tập SC riêng, không dedupe chéo platform.)*

### Step 3 — Tính `status` theo từng scenario

Áp dụng quy tắc theo thứ tự ưu tiên (first-match-wins):

| Rule | Status | Điều kiện |
|------|--------|-----------|
| 1 | `UNTRACKED` | `implemented_by == —` (chưa sinh code) |
| 2 | `DRIFT` | `implemented_by != —` AND `spec_ver != gen_ver` (spec đã đổi sau lần codegen — code cũ, **ưu tiên regen trước khi test**) |
| 3 | `GAP` | `implemented_by != —` AND (`test_count == —` OR `test_count == 0`) |
| 4 | `OK` | tất cả: `spec_ver == gen_ver`, `implemented_by != —`, `test_count > 0` |

> **Vì sao DRIFT xét trước GAP:** một scenario đã có code, chưa test, **và** spec vừa drift phải hiện `DRIFT` (không phải `GAP`) — vì `generate-code` xử `GAP` = "skip codegen, chạy /dev-gen-test" còn `DRIFT` = "regenerate". Nếu GAP thắng, code lỗi thời bị bỏ qua và test lại sinh trên code cũ. UNTRACKED vẫn phải là Rule 1 để scenario chưa code (gen_ver `—`) không lọt vào DRIFT.

### Step 4 — PRD version drift check

Với mỗi UC, so:
- PRD `| **Version** |` hiện tại từ `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md`
- `prd_version` lưu trong `.tsv` (version tại thời điểm sinh BDD)
- `@trace.prd_version` trong các file code implement UC đó

Nếu layer nào sau version PRD hiện tại → gắn cờ `PRD_DRIFT` và trích các changelog entry kể từ version đó.

### Step 5 — Tech-doc revision drift check

Mỗi PRD có **một** tech-doc gộp `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` với một `@trace.revision` chung. So revision đó vs hai cột đã lưu:

- **Backend drift:** `@trace.revision` của doc vs `tech_doc_revision` trong `.tsv`.
  Code sinh từ revision cũ hơn → gắn cờ `TECHDOC_DRIFT`.
- **FE integration drift:** `@trace.revision` của doc vs `fe_tech_doc_revision` trong `.tsv` (row FE `--phase=integration`, theo từng platform).
  Code FE wire theo revision cũ hơn (§4.5.4 đã đổi) → gắn cờ `FE_TECHDOC_DRIFT`.

Skip cột nào chưa có revision đã lưu (`—`), hoặc cả UC chưa có tech-doc.

### Step 5b — Seam & Stub Audit (mồ côi khi ghép luồng)

*Bắt lỗi "gen từng BDD thì đúng, ghép cả luồng thì hỏng": chỗ giả lập còn rỗng trong khi hàng thật đã tồn tại ở nơi khác — luồng chạy vào no-op / hàm thật không ai gọi. Build vẫn xanh, test từng-UC vẫn xanh, nên không cổng nào khác bắt được. Hai loại: `seam` (port cross-UC chưa nối) và `stub` (method trắng nội-feature chưa lấp).*

**Nguồn (dùng cái nào có, hợp nhất):**
1. Sổ chung `{trace_dir}/{domain}/{prd-slug}/_seams.tsv` — do `/generate-code` ghi (cột `kind` phân biệt `seam`/`stub`).
2. Quét code dưới `{code_base_package}` (từ CLAUDE.md §2 đã nạp) — bắt cả chỗ sinh **trước khi** có sổ:
   - **seam:** class mang `@trace.seam_pending` HOẶC tên khớp `*Stub*Adapter`.
   - **stub:** method mang `@trace.stub` (thân còn placeholder — `throw UnsupportedOperationException` / TODO / rỗng).

**Audit A — Seam (port cross-UC).** Với mỗi seam:
- Tìm **hàng thật**: class KHÁC (không `*Stub*`/`*Mock*`) implement cùng port/interface dưới `{code_base_package}`.
- Tìm **binding hiện tại**: stub có còn được tham chiếu như adapter đang dùng không (được inject / `@Primary` / đăng ký trong config) — hàng thật thì KHÔNG có đường vào?

| Điều kiện | Cờ | Ý nghĩa |
|---|---|---|
| Hàng thật CHƯA tồn tại | `SEAM_PENDING` | Bình thường — owner UC chưa gen. Chỉ nhắc. |
| Hàng thật ĐÃ tồn tại **và** stub vẫn là binding đang dùng | `SEAM_UNWIRED` 🔴 | **Lỗi thật** — hàng thật mồ côi, luồng chạy vào stub rỗng. |
| Binding đã trỏ hàng thật (stub chỉ còn cho test) | *(sạch)* | Đã nối xong. |

**Audit B — Stub (method trắng nội-feature).** Với mỗi method còn tag `@trace.stub`:
- Đọc `@trace.stub_owner` (UC lẽ ra phải lấp) + `@trace.stub_for` (trách nhiệm).
- **Owner đã gen chưa?** = có bất kỳ `@trace.implements={stub_owner}-*` nào trong codebase không.
- **Có hàng thật song song không?** = method KHÁC mang `@trace.implements` với thân thật cùng trách nhiệm `stub_for` (dấu hiệu BDD owner đã đẻ hàm song song thay vì lấp).

| Điều kiện | Cờ | Ý nghĩa |
|---|---|---|
| `stub_owner` chưa gen **và** không có hàng song song | `STUB_PENDING` | Bình thường — owner BDD chưa chạy. Chỉ nhắc. |
| `stub_owner` ĐÃ gen (hoặc có method song song cùng `stub_for`) mà method vẫn còn `@trace.stub` rỗng | `STUB_UNRESOLVED` 🔴 | **Lỗi thật** — hàm trắng mồ côi (caller chạy vào rỗng) và/hoặc hàm thật mồ côi (không ai gọi). Fill-before-create đã trượt. |
| Không còn method nào mang `@trace.stub` cho trách nhiệm đó | *(sạch)* | Đã lấp xong. |

- **Cập nhật sổ `_seams.tsv`** (nếu tồn tại): theo `kind`,
  - `seam`: `PENDING`→`READY` khi hàng thật xuất hiện mà chưa nối; `→RESOLVED` khi binding đã trỏ hàng thật.
  - `stub`: `PENDING`→`READY` khi phát hiện `STUB_UNRESOLVED`; `→RESOLVED` khi method đã được lấp (hết `@trace.stub`).
  `READY` = đồng nghĩa cờ 🔴 tương ứng (`SEAM_UNWIRED` / `STUB_UNRESOLVED`).

Không tìm thấy seam/stub nào → bỏ qua im lặng.

### Step 6 — Ghi status lại vào TSV

*Bỏ qua step này nếu không có file TSV nào (đã xử lý bởi path no-TSV của Step 1).*

Với mỗi file `.tsv` đã xử lý: ghi `spec_ver`, `status`, `last_updated` đã cập nhật lại disk.
Đồng thời **đồng bộ `uc_status` ← `@trace.status`** của file `.feature` tương ứng (header `.feature` là nguồn-sự-thật về duyệt BDD — người đặt `approved` sau khi review sạch, giống PO đặt PRD Metadata `Status`). Nhờ vậy `approved_ucs` trên dashboard phản ánh đúng thay vì luôn = 0.
**Đừng** sửa `dev_selftest`/`dev_selftest_at` (do `/dev-run-test` sở hữu) hay `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` (do `/qc-run-test` + `/report-bug` sở hữu); lệnh này chỉ đọc chúng cho report.

### Step 7 — Tính aggregate cho dashboard

```
total_prds       = count distinct PRD files in {paths.specs_dir}/{domain}/*/*.md  (file .md ở gốc mỗi feature folder = PRD)
approved_prds    = PRDs with | Status | approved
total_ucs        = count distinct UC-IDs across all .tsv files (strip the -{platform} suffix from the filename)
approved_ucs     = UCs with uc_status == approved
draft_ucs        = UCs with uc_status == draft
total_scs        = total rows across all .tsv files (a UC's SCs are counted per platform — no cross-platform dedupe by sc_id)
code_coverage    = rows where implemented_by != — / total_scs
test_coverage    = rows where test_count > 0 / total_scs
drift_count      = rows where status == DRIFT
untracked_count  = rows where status == UNTRACKED
gap_count        = rows where status == GAP
seam_unwired_count = số seam bị cờ SEAM_UNWIRED (hàng thật đã có nhưng consumer còn wire vào stub — Step 5b)
stub_unresolved_count = số stub bị cờ STUB_UNRESOLVED (method còn trắng dù owner đã gen / có hàm song song — Step 5b)
dev_selftest_passing = rows where dev_selftest == pass
dev_selftest_failing = rows where dev_selftest == fail
dev_selftest_not_run = rows where dev_selftest in (not_run, —)
# NOTE: dev_selftest is the DEV self-check signal (did the dev run their own smoke tests),
# NOT official coverage — keep it labeled as such on the dashboard.
qc_passing       = rows where qc_status == pass
qc_failing       = rows where qc_status == fail
qc_skipped       = rows where qc_status == skip
qc_not_run       = rows where qc_status in (not_run, —)
# qc_status is the OFFICIAL QC automation result (set by /qc-run-test),
# shown alongside — never merged with — dev_selftest.
waiting_dev      = rows where qc_owner == dev      # PM view: QC-found, waiting on dev to fix
waiting_po       = rows where qc_owner == po       # PM view: blocked, waiting on PO to confirm/clarify
# qc_owner + qc_blocked_by trả lời "case nào đang chờ ai" — surface as a "Waiting on" column.
tech_docs_count  = count .md files in {paths.tech_docs_dir}/{domain}/*/tech-docs/
```

### Step 8 — Ghi JSON report

Ghi `{paths.trace_dir}/trace-report.json` (ghi đè nếu tồn tại). File này là source of truth duy nhất cho web dashboard — nó chứa snapshot đầy đủ tại thời điểm `/validate-traces` chạy lần cuối.

Schema:

```json
{
  "generated_at": "<ISO-8601 timestamp>",
  "domain": "<domain argument, or 'all' if no filter>",
  "summary": {
    "total_prds": 0,
    "approved_prds": 0,
    "total_ucs": 0,
    "approved_ucs": 0,
    "draft_ucs": 0,
    "total_scs": 0,
    "coded_scs": 0,
    "tested_scs": 0,
    "code_coverage_pct": 0,
    "test_coverage_pct": 0,
    "drift_count": 0,
    "gap_count": 0,
    "untracked_count": 0,
    "seam_unwired_count": 0,
    "stub_unresolved_count": 0,
    "dev_selftest_passing": 0,
    "dev_selftest_failing": 0,
    "dev_selftest_not_run": 0,
    "qc_passing": 0,
    "qc_failing": 0,
    "qc_skipped": 0,
    "qc_not_run": 0,
    "waiting_dev": 0,
    "waiting_po": 0,
    "tech_docs_count": 0
  },
  "prds": [
    {
      "prd_id": "<e.g. PAY>",
      "prd_status": "approved | draft | other",
      "total_scs": 0,
      "coded_scs": 0,
      "tested_scs": 0,
      "drift_count": 0,
      "gap_count": 0,
      "untracked_count": 0,
      "ucs": [
        {
          "uc_id": "<e.g. PAY-UC01>",
          "uc_status": "approved | draft | other",
          "scenarios": [
            {
              "sc_id": "<e.g. PAY-UC01-SC1>",
              "sc_title": "<title>",
              "spec_ver": "<current version from .feature>",
              "gen_ver": "<version at codegen time>",
              "implemented_by": "<ClassName.method or null>",
              "test_count": 0,
              "test_classes": ["<TestClass1>", "<TestClass2>"],
              "dev_selftest": "pass | fail | not_run",
              "dev_selftest_at": "<YYYY-MM-DD or null>",
              "qc_status": "pass | fail | skip | not_run",
              "qc_run_at": "<YYYY-MM-DD or null>",
              "qc_owner": "dev | po | null",
              "qc_blocked_by": "<BUG-id / GAP-id or null>",
              "prd_version": "<prd version when BDD was generated>",
              "bdd_version": "<bdd version when code was generated>",
              "tech_doc_revision": 0,
              "fe_tech_doc_revision": 0,
              "status": "OK | DRIFT | GAP | UNTRACKED",
              "last_updated": "<YYYY-MM-DD>"
            }
          ]
        }
      ]
    }
  ],
  "issues": {
    "drift": [
      {
        "sc_id": "<SC-ID>",
        "sc_title": "<title>",
        "spec_ver": "<current>",
        "gen_ver": "<at codegen>",
        "fix": "/generate-code <UC-ID>"
      }
    ],
    "gap": [
      {
        "sc_id": "<SC-ID>",
        "sc_title": "<title>",
        "implemented_by": "<method>",
        "fix": "/dev-gen-test <UC-ID>"
      }
    ],
    "untracked": [
      {
        "sc_id": "<SC-ID>",
        "sc_title": "<title>",
        "fix": "/generate-code <UC-ID>"
      }
    ],
    "prd_version_drift": [
      {
        "uc_id": "<UC-ID>",
        "code_prd_version": "<version in code tag>",
        "current_prd_version": "<version in PRD file>",
        "changelog_since": ["<v1.1: ...>", "<v1.2: ...>"],
        "fix": "/generate-bdd <prd-file> then /generate-code <UC-ID>"
      }
    ],
    "techdoc_drift": [
      {
        "uc_id": "<UC-ID>",
        "code_revision": 0,
        "current_revision": 0,
        "fix": "/generate-code <UC-ID>"
      }
    ],
    "fe_techdoc_drift": [
      {
        "uc_id": "<UC-ID>",
        "platform": "web | app",
        "code_revision": 0,
        "current_revision": 0,
        "fix": "/generate-code <UC-ID> --phase=integration"
      }
    ],
    "seam_unwired": [
      {
        "port": "<PortName>",
        "consumer_uc": "<UC còn gọi stub>",
        "owner_uc": "<UC sở hữu hàng thật>",
        "stub_class": "<StubClass>",
        "real_class": "<RealClass>",
        "fix": "Trỏ binding của <consumer_uc> sang <RealClass> (xoá/thay stub), build lại"
      }
    ],
    "stub_unresolved": [
      {
        "artifact": "<ClassName#method>",
        "stub_for": "<trách nhiệm>",
        "consumer_uc": "<UC để trắng>",
        "owner_uc": "<UC lẽ ra phải lấp>",
        "parallel_impl": "<ClassName#method hàm song song, hoặc null>",
        "fix": "/generate-code <owner_uc> — lấp logic vào <ClassName#method> tại chỗ (Fill-before-create), xoá hàm song song nếu có, build lại"
      }
    ]
  }
}
```

**Rules:**
- `implemented_by`: dùng `null` (không phải `"—"`) trong JSON khi không có giá trị
- `test_count`: dùng integer `0` (không phải `"—"`) khi không có test
- `test_classes`: dùng `[]` (không phải `"—"`) khi không có test class
- `tech_doc_revision` / `fe_tech_doc_revision`: dùng integer; `0` nếu chưa sinh
- `code_coverage_pct` / `test_coverage_pct`: làm tròn về integer gần nhất (0–100)
- Luôn ghi vào `{paths.trace_dir}/trace-report.json` bất kể domain filter — nếu có domain filter, chỉ gồm các PRD đó trong `prds[]` nhưng ghi domain vào field `domain`
- **TSV `"—"` mapping**: khi đọc file TSV, map giá trị dash sang kiểu JSON: `implemented_by: "—"` → `null`; `test_count: "—"` → `0`; `test_classes: "—"` → `[]`; `tech_doc_revision: "—"` → `0`; `fe_tech_doc_revision: "—"` → `0`; `dev_selftest: "—"` → `"not_run"`; `dev_selftest_at: "—"` → `null`; `qc_status: "—"` → `"not_run"`; `qc_run_at: "—"` → `null`; `qc_owner: "—"` → `null`; `qc_blocked_by: "—"` → `null`
- **Backward-compat:** TSV cũ có thể thiếu cột mới hơn trong header — coi cột vắng nào là giá trị rỗng của nó (đừng báo lỗi): `qc_owner`/`qc_blocked_by` (pre-19-col) → `null`; `fe_tech_doc_revision` (pre-22-col) → `0`. Lần `/generate-bdd` gen lại tiếp theo nâng header lên layout 22 cột hiện tại.

### Step 8b — Living Docs Sync *(chỉ umbrella mode)*

*Bỏ qua step này ở single-service mode.*

**Với `spec_source` được set,** các trace TSV authoritative đã sống ở **một** chỗ —
`{spec_source}/.trace/` (committed trong spec repo). **Không có merge theo service**:
mỗi scenario row mang service sở hữu qua `@trace.service`. Step này chỉ
(re)generate report và làm mới panel local.

1. **Ghi report** vào `{living_docs_dir}/trace-report.json` (`mkdir -p` trước) — dựng
   trực tiếp từ `{spec_source}/.trace/*.tsv`, với field `"service"` mỗi scenario row và
   các summary aggregate. *(Umbrella legacy không-`spec_source` vẫn merge mọi `trace-report.json`
   theo service thành một document, namespace theo service.)*

2. **Mirror tới panel location** `{panel_mirror}` (`./.trace` ở gốc workspace hiện tại)
   để dev mở *repo này* thấy data ngay: copy
   `{living_docs_dir}/trace-report.json` (+ các file `{UC-ID}-{platform}.tsv`) → `{panel_mirror}/`.
   Nếu `panel_mirror` đã phân giải về `{spec_source}/.trace`, skip.

3. **In sync summary:**
   ```
   Living Docs → {living_docs_dir}/trace-report.json  ({total} scenarios across {S} services)
   Trace (authoritative) → {spec_source}/.trace/   (committed in spec repo)
   Panel mirror → {panel_mirror}/trace-report.json  (current workspace)
   ```

> **Lưu ý:** trace state committed, authoritative là `{spec_source}/.trace/*.tsv` (trong
> spec repo — một chỗ cho PM). Report (`.living-docs/`) và panel mirror
> (`./.trace` ở workspace không phải spec repo) là **sinh ra** — gitignore chúng;
> chúng được regenerate bởi `/validate-traces` hoặc `/sync`.

## 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` · `/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}` |
| /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) |
| /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        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR |
| /fix-bug                | Tạo PR và link tới ticket                  |
| /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       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
| /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.)*


```
/validate-traces — {domain}

📄 {paths.trace_dir}/trace-report.json  ← updated

┌─────────────────────────────────────────────────────────────────────────────────────┐
│  PRDs      Use Cases     Scenarios   Code Cov.  Test Cov.  Drift  Untracked  Gap   │
│  {N}       {N}           {N}         {N}%       {N}%       {N}    {N}        {N}   │
│  {A} appr  {A} appr                 {X}/{T} SCs {X}/{T} SCs                        │
└─────────────────────────────────────────────────────────────────────────────────────┘
{nếu seam_unwired_count > 0 hoặc stub_unresolved_count > 0, in dòng GATE — ngược lại bỏ}
🔴 GATE — luồng ghép có MỒ CÔI: {seam_unwired_count} SEAM_UNWIRED + {stub_unresolved_count} STUB_UNRESOLVED.
   Build/test từng-UC vẫn xanh nhưng luồng to chạy vào no-op / hàm thật không ai gọi.
   KHÔNG coi là pass tới khi cả hai = 0 (xem Seam & Stub Audit bên dưới).

| UC-ID       | SC   | Title (truncated)            | Spec  | Gen   | Code                 | Tests          | Status   |
|-------------|------|------------------------------|-------|-------|----------------------|----------------|----------|
| {UC}-UC1    | SC1  | {title...}                   | v1.0  | v1.0  | ✅ {Controller.fn}   | ✅ 10 tests    | OK       |
| {UC}-UC1    | SC2  | {title...}                   | v1.1  | v1.0  | ✅ {Controller.fn}   | ✅ 3 tests     | DRIFT    |
| {UC}-UC1    | SC6  | {title...}                   | v1.0  | —     | —                    | —              | UNTRACKED|
| {UC}-UC2    | SC1  | {title...}                   | v1.0  | v1.0  | ✅ {Controller.fn}   | —              | GAP      |

Drift Detail:
  {UC}-UC1-SC2 — spec v1.1 nhưng code sinh từ v1.0
    → Chạy lại: /generate-code {UC-ID}

PRD Version Drift:
  {UC}-UC2 — code ở PRD v1.0, PRD giờ ở v1.2
    Thay đổi kể từ v1.0:
      v1.1: {changelog entry}
      v1.2: {changelog entry}
    → /generate-bdd {prd-file} then /generate-code {UC-ID}

Tech-Doc Revision Drift:
  {UC}-UC3 — code sinh từ tech-doc revision 2, giờ ở revision 4
    → Review thay đổi tech-doc rồi /generate-code {UC-ID}

Seam & Stub Audit (mồ côi khi ghép luồng):
  🔴 SEAM_UNWIRED — {port}: {consumer_uc} còn gọi {stub_class} rỗng,
     hàng thật {real_class} ({owner_uc}) chưa được nối → luồng ghép chạy vào no-op
       → Trỏ binding {consumer_uc} sang {real_class}, xoá/thay stub, build lại
  ⓘ SEAM_PENDING — {port}: {consumer_uc} đang dùng stub, owner {owner_uc} chưa gen (chưa phải lỗi)
  🔴 STUB_UNRESOLVED — {ClassName#method} ({stub_for}): {consumer_uc} để trắng, owner {owner_uc} đã gen
     {parallel_impl → "đẻ hàm song song " + parallel_impl | ""}→ hàm trắng mồ côi / hàm thật không ai gọi
       → /generate-code {owner_uc} lấp logic vào {ClassName#method} tại chỗ, xoá hàm song song, build lại
  ⓘ STUB_PENDING — {ClassName#method} ({stub_for}): owner {owner_uc} chưa gen (chưa phải lỗi)

Recommendations:
  - /generate-code {UC-ID}      cho scenario DRIFT và UNTRACKED
  - /dev-gen-test {UC-ID}     cho GAP (thiếu test)
  - /generate-bdd {prd-file}    cho PRD version drift
  - Nối binding thủ công         cho mỗi SEAM_UNWIRED 🔴 (hàng thật đã có, còn kẹt stub)
  - /generate-code {owner_uc}    cho mỗi STUB_UNRESOLVED 🔴 (lấp method trắng tại chỗ + xoá hàm song song)

[Chỉ umbrella mode]
Living Docs canonical → {living_docs_dir}/  (specs module — shared, gitignored)
Panel mirror          → {panel_mirror}/trace-report.json  (current workspace)
  Tip: chạy /validate-traces (hoặc /sync) sau mỗi phiên codegen để làm mới panel.
  Cả hai là mirror sinh ra — đừng commit (.living-docs/ + .trace/ trong .gitignore).
```