@educa-corp/sdd-framework 0.4.2 → 0.6.0

package/core/commands/validate-traces.md

@@ -3,6 +3,9 @@
 Check read-only độ phủ giữa spec, code, và test — gồm cả PRD version drift.
 
 ## Gate
+
+*Checkpoint: **không chặn** — read-only (ghi trace-report.json + TSV status, không đụng spec/code). Gate Bước 3 bỏ qua CHECKPOINT (Bước 3a).*
+
 # 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ó.
@@ -22,35 +25,31 @@ Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ m
    - Đ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ước 0-B — Ghi nhận Model *(KHÔNG chặn)*
 
-*Bỏ qua bước này nếu `_agent_mode: true` (sub-agent — orchestrator đã kiểm tra rồi).*
+*Bỏ qua nếu `_agent_mode: true` (sub-agent — orchestrator đã ghi nhận 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.
+Ghi lại **model mà bạn — agent đang chạy lệnh này — thực sự đang dùng**, rồi mang nó vào
+dòng `Model:` của report cuối (xem `report-footer`). Nếu bạn biết mình **không** phải một
+model Opus, gắn thêm cảnh báo ngay ở dòng đó.
 
-Hiển thị và chờ phản hồi:
+**KHÔNG hỏi người dùng. KHÔNG chờ. KHÔNG dừng.**
 
-```
-⚙️  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)
-──────────────────────────────────────────────────────────────────
-```
+> **Vì sao bước này từng là prompt chặn, và vì sao bỏ (GAPS-v3 G41):** bản cũ hiện khối
+> `⚙️ MODEL CHECK` rồi chờ `Y/S/N`. Ba vấn đề cùng chỉ một hướng:
+> **(1)** nó hỏi người dùng thứ mà **agent đã biết chính xác**;
+> **(2)** câu trả lời **không kiểm chứng được** — gõ `Y` xong vẫn đang chạy Haiku thì không
+> gì phát hiện;
+> **(3)** **cả `Y` lẫn `S` đều đi tiếp** — cách duy nhất để nó dừng là tự nguyện gõ `N`.
+> Tức nó **không chặn được ai**, mà tốn một lần chặn ở **mọi** lệnh. Một feature đi hết
+> pipeline dùng 20 lệnh; 30/32 lệnh chạy gate. Hai mươi lần bấm cho một tín hiệu tự-khai
+> không kiểm chứng được — và chính cái giá đó làm mòn CHECKPOINT ở Bước 3, cổng có giá trị thật.
+>
+> Khai báo trong report **mạnh hơn** hỏi: đúng nguồn (agent, không phải người), và nằm
+> **cạnh kết quả** để cân nhắc, thay vì nằm trước khi có kết quả để bấm cho xong.
 
-- "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."
+**Vẫn khuyến nghị Opus:** phân tích spec, review kiến trúc và sinh code đòi hỏi suy luận sâu;
+model nhỏ hơn dễ bỏ sót edge case và vi phạm kiến trúc. Đổi: `/model` → chọn Opus.
 
 ## Bước 1 — Xác định Target File
 
@@ -80,414 +79,95 @@ Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phi
 
 ## 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.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.*
+*Bỏ qua nếu `_agent_mode: true`.*
 
-Nếu có section `services`:
+### 3a — Lệnh này có phải chặn không?
 
-**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`
+| Mức | Lệnh nào | `--yes` bỏ qua được? |
+|---|---|:---:|
+| **Không chặn** | Lệnh read-only: `/review-code` · `/validate-traces` · `/debug` · `/review-context` · `/review-tech-docs` | — (vốn không có) |
+| **Chặn thường** | Mọi lệnh sinh/sửa artifact | ✅ |
+| **Chặn CỨNG** | Ghi đè file đã tồn tại · `--resume` áp findings · migrate · prune | ❌ **không bao giờ** |
 
-**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`.
+`--yes` trong `$ARGUMENTS` → bỏ qua CHECKPOINT mức *chặn thường*. (Bước 1 đã tách mọi token
+`--` khỏi phần resolve target, nên cờ này không ảnh hưởng việc tìm file.) Mở đường chạy
+headless: `claude -p "/generate-code UC1 --yes"`.
 
-**2. Route tới service** — nếu active domain khớp một key trong `services`.
+> **KHÔNG tự suy mức từ bảng này.** Mỗi lệnh **tự khai** mức của nó ở một dòng `*Checkpoint: …*`
+> ngay dưới `## Gate` của chính nó — đọc dòng đó, đừng suy diễn. Bảng trên chỉ giải thích ba mức
+> **nghĩa là gì**.
+> Nguồn máy đọc: `bin/trace-schema.json` → `gate.checkpoint_levels`; `self-check` **R11** fail
+> build nếu nhãn trong file lệnh lệch với schema, hoặc nếu một lệnh `hard`/`none` thiếu nhãn.
+> *(Lệnh không có dòng nào = mức **chặn thường**, mặc định.)*
 
-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.
+> **Mức *không chặn* là thực thi đúng miễn trừ mà `rules/workflow.md` đã cấp từ trước** —
+> trước G41 file đó viết *"read-only commands may skip CHECKPOINT"* còn gate thì luôn đòi.
+> Hai file cùng được nạp vào mọi lệnh mà nói ngược nhau; agent theo cái nào là tuỳ lúc.
 
-Thứ trỏ tới đích gọi là một **service entry**. Nó chỉ có hai kiểu:
+### 3b — In gì
 
-| 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 |
+**KHÔNG lặp lại những gì `[CTX LOADED]` vừa in.** Recap của context-loader (Bước 7) đã hiện
+Stack · Platform · Layers · CLAUDE.md · Dict · Entities · Lessons · Service · Status ngay phía
+trên. CHECKPOINT chỉ thêm **một** thông tin mới là `Target`.
 
-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:
+**Mọi thứ sạch** — recap báo `Status: FULL`, không cờ nào bật → in đúng hai dòng:
 
-| 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
+CHECKPOINT — Target: {resolved file path}
+Tiếp tục? (Y/N)
+```
 
-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:
+**Có bất thường** → thêm một dòng cho **mỗi** trạng thái, nặng nhất lên đầu:
 
 ```
-active_module = tech_stack.module   (vd: "java-spring", "react", "flutter")
+CHECKPOINT
+🔴 Service  : unresolved — {lý do context-loader đã ghi}
+⚠️ CLAUDE.md: service overlay THIẾU — dùng root (code sinh ra có thể sai stack)
+⚠️ Target   : resolve bằng wildcard — {n} file khớp, chọn {file}
+⚠️ Module   : not configured — code sinh ra sẽ dùng default
+   Status   : PARTIAL — thiếu: {danh sách}
+   Target   : {resolved file path}
+Tiếp tục? (Y/N)
 ```
 
-| `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` |
+### 3c — Cờ nào bật, cờ nào KHÔNG
 
-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.
+Mỗi dòng ⚠️/🔴 phải ứng với một trạng thái **context-loader đã tính rồi** — không phát minh
+điều kiện mới, chỉ mang thứ đang bị giấu lên chỗ người dùng phải quyết định:
 
-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ật cờ khi | Nguồn | Mức |
+|---|---|:---:|
+| `active_service = unresolved` | context-loader Bước 2b/2c/Fallback | 🔴 |
+| `Status = MINIMAL` | recap Bước 7 | 🔴 |
+| `Status = PARTIAL` | recap Bước 7 | ⚠️ |
+| CLAUDE.md thiếu, hoặc service overlay thiếu | context-loader Bước 3 | ⚠️ |
+| Target resolve qua wildcard, hoặc nhiều file khớp mà lệnh tự chọn | Bước 1 ở trên | ⚠️ |
+| `module` không cấu hình | recap Bước 7 | ⚠️ |
 
----
-
-## 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`.*
+**KHÔNG bật cờ cho:** `Lessons: chưa có` · `Dict: missing` · `Entities: missing`. Đó là
+*"dự án chưa điền"*, không phải *"có gì đó sai"* — chúng ở lại trong recap.
 
-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`
+> **Nguyên tắc một câu:** cờ dành cho thứ **framework không chắc chắn hoặc đã phải đoán**,
+> không dành cho thứ **người dùng chưa làm**. Đẩy hết mọi thứ lên thì CHECKPOINT lại đầy như
+> cũ, và ta quay về đúng chỗ xuất phát: một cổng luôn giống nhau thì bị lướt qua.
 
-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).
-
----
+### 3d — Chờ trả lời
 
-## Bước 7 — [RECAP] Working Memory Recap (chống lost-in-middle)
+- "Y" → tiếp tục sang các bước riêng của lệnh.
+- "N" → dừng, hỏi người dùng muốn thay đổi gì.
+- Có `--yes` và mức *chặn thường* → coi như "Y", **nhưng vẫn IN khối CHECKPOINT** nếu có cờ
+  🔴/⚠️ (không chặn ≠ không báo — người đọc log sau này vẫn cần thấy).
 
-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
+*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.*
 
-Tiếp tục sang bước kế tiếp của lệnh đang gọi.
+## Context
+**BẮT BUỘC — đọc `.agent/steps/context-loader.md` và thực thi TOÀN BỘ quy trình trong đó**,
+rồi mới tiếp tục phần bên dưới.
 
+Bỏ qua bước này thì `{paths.*}`, `{tech_stack.*}`, `{conventions.*}`, guardrail từ
+`project-lessons`, và routing service (chế độ umbrella) đều **chưa được phân giải** — mọi
+placeholder bên dưới sẽ rỗng và lệnh sẽ đọc/ghi sai chỗ.
 
 ---
 
@@ -499,14 +179,17 @@ 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.
+  - **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. Không cần tách theo service vì **mỗi row TSV mang service sở hữu ở cột `service` (cột 23)** — `/generate-bdd` ghi nó từ `@trace.service` của header `.feature`. Đây là trường hợp phổ biến.
+    > *Trước v0.4.3, câu này nói "scenario mang service qua `@trace.service`" nhưng TSV **không có cột nào** cho nó và JSON report cũng không — nên ở đúng chế độ phổ biến nhất, trace hoàn toàn không trả lời được "scenario này thuộc đội nào". Cột 23 là thứ làm câu trên trở thành sự thật.*
   - **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.
+- **Phân giải panel mirror:** `panel_mirror = ./.trace-mirror` ở **gốc workspace hiện tại** (nơi lệnh chạy). Panel VS Code đọc report từ workspace đang mở — ghi ở đây là cái làm view không rỗng khi dev mở một service submodule trực tiếp.
+  **Bỏ qua toàn bộ mirror nếu `{paths.trace_dir}` đã nằm trong workspace hiện tại** (single-service, hoặc dev mở thẳng spec repo) — panel đọc `.trace/trace-report.json` tại chỗ, không cần bản sao.
+  > ⚠️ **`.trace-mirror` ≠ `.trace` — cố ý khác tên.** Trước v0.4.3 cả hai cùng tên `.trace`, nên một luật gitignore theo tên có thể xoá sạch sổ gốc khi hai path trùng nhau. Giờ luật git là tuyệt đối, không có ca nhập nhằng: `.trace-mirror/` **luôn** gitignore · `{paths.trace_dir}` **luôn** commit.
 
 **Nếu không có key `services` (single-service mode):**
 - Set `all_trace_dirs = [ {paths.trace_dir} ]`
@@ -514,6 +197,44 @@ Kiểm tra mảng `services` có tồn tại trong `project-context.yaml` không
 
 ---
 
+### Step 1.0 — Lint sổ trace TRƯỚC khi đọc *(bắt buộc, không bỏ qua được)*
+
+Chạy checker xác định trên mọi trace dir đã phân giải ở Step 0:
+
+```bash
+npx @educa-corp/sdd-framework --lint-trace --trace {all_trace_dirs, ngăn cách bởi dấu phẩy} --specs {paths.specs_dir}
+```
+
+*`bin/` sống trong package npm, không được cài vào project — nên `npx` là đường duy nhất. Không có mạng / npx fail → **bỏ qua step này**, in `⚠️ Chưa lint được sổ trace (npx không khả dụng) — kết quả dưới đây chưa được kiểm cấu trúc` vào report, rồi tiếp Step 1. Đừng để nó chặn cả lệnh.*
+
+**Exit 0 → tiếp Step 1.**
+
+**Exit 1 → DỪNG NGAY.** Đừng nạp, đừng tính `status`, đừng ghi lại gì:
+
+```
+🔴 SỔ TRACE HỎNG — không phán trạng thái trên dữ liệu này.
+
+{nguyên văn output của lint-trace}
+
+Vì sao dừng thay vì cố đọc tiếp: Step 3 tính lại `status` rồi Step 6 GHI NGƯỢC
+vào TSV. Chạy tiếp trên một row đã lệch cột sẽ nướng cái lệch đó vào sổ vĩnh viễn —
+và sổ trace là dữ liệu KHÔNG regenerate được.
+
+Sửa:
+  1. Xem lần ghi nào làm hỏng : git log -p {file}
+  2. Sửa file (thường là thêm/bớt một dấu tab, hoặc giữ cả hai row sau merge)
+  3. Kiểm lại               : npx @educa-corp/sdd-framework --lint-trace
+  4. Rồi chạy lại /validate-traces
+```
+
+> **Vì sao step này tồn tại (G38):** `bin/self-check.js` canh **contract** — nó đọc file lệnh
+> và kiểm "lệnh có gọi đúng tên cột không". Nó không bao giờ mở một `.tsv` thật. Trong khi sổ
+> 24 cột được ghi **bằng tay**, hàng chục lần mỗi feature. Một dấu tab thiếu ở ô 17 dồn mọi ô
+> sau đó sang trái một bậc — ô 21 `status` nhận một ngày tháng — và **trước step này không gì
+> báo lỗi**: lệnh đọc tiếp, in ra số, số chảy vào `trace-report.json` rồi vào dashboard.
+
+---
+
 ### 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.
@@ -577,19 +298,80 @@ Với mỗi UC, so:
 - `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 đó.
+Nếu layer nào sau version PRD hiện tại → trích các changelog entry kể từ version đó, rồi **lọc theo phạm vi ảnh hưởng** (dưới đây) để quyết `PRD_DRIFT` 🟠 hay `PRD_STALE_REF` ⓘ.
+
+#### Lọc theo phạm vi changelog — chống báo động oan
+
+*PRD là tài liệu **cấp feature** phủ nhiều UC, nhưng version của nó là **một scalar**. Nên thêm UC7 — không đụng một chữ nào của UC1–UC6 — vẫn làm cả 6 UC cũ lệch version. So version thuần thì cả 6 ăn cờ đỏ oan.*
+
+Đọc các row `# Change Log` của PRD **từ version của layer cũ nhất tới hiện tại**, trích tập UC/AC/BR được nêu. *(`/refine-prd` Phase 3 và `/extend-prd` **bắt buộc** ghi thông tin này vào mỗi row — chính vì mục đích này. `/generate-bdd` Version Check đã dùng nó từ trước; ở đây chỉ là đọc cùng một dữ liệu.)*
+
+| Điều kiện | Cờ | Hành động |
+|---|---|---|
+| UC này **có** trong tập bị ảnh hưởng | `PRD_DRIFT` 🟠 | Cần regen thật — theo bảng `drifted_layers` bên dưới |
+| UC này **không** có trong tập, **và** mọi row changelog trong khoảng đều nêu rõ scope | `PRD_STALE_REF` ⓘ | Nội dung không đổi, chỉ con trỏ version cũ. **KHÔNG** route regen — dùng `--realign-prd-version` |
+| **Bất kỳ** row nào trong khoảng mơ hồ (không nêu UC/AC/BR) | `PRD_DRIFT` 🟠 cho **MỌI** UC | Không suy đoán được thì quét rộng |
+
+> **Hàng thứ ba là lưới an toàn — hỏng theo hướng an toàn.** Changelog viết ẩu thì ta mất tính năng *lọc*, KHÔNG mất tính năng *cảnh báo*. Đồng bộ với `generate-bdd` Version Check: *"changelog row không nêu rõ UC/AC/BR (mơ hồ) → khuyến nghị F (gen lại toàn bộ)"*.
+>
+> **Vì sao cần bước lọc này:** đây là G1 lộn ngược. G1 làm cờ **im lặng**; so-version-thuần làm cờ **ồn tới mức vô nghĩa** — sau vài lần thêm feature, `PRD_DRIFT` sáng thường trực, người đọc học cách bỏ qua, rồi lần lệch THẬT cũng bị bỏ qua cùng. Kết cục giống hệt nhau: không ai còn tin cờ. Và nó tệ dần theo thời gian — PRD càng nhiều UC, càng nhiều lần bump, nhiễu càng lớn, tức là đánh mạnh nhất vào chính những feature trưởng thành nhất.
+> Framework **đã giải đúng bài này ở cấp scenario**: `sc_version` chỉ bump khi thân scenario thực sự đổi, với lý do ghi thẳng — *"bump vô cớ sẽ tạo DRIFT giả, làm cờ mất giá trị"*. Đây là bản tương ứng ở cấp PRD.
+
+**Ghi rõ layer nào lệch** (`drifted_layers` trong JSON — `"tsv"` và/hoặc `"code"`). Đây là thứ quyết định người dùng phải chạy **một** lệnh hay **hai**:
+
+| `drifted_layers` | Nghĩa | Hành động |
+|---|---|---|
+| `["tsv"]` | BDD chưa gen lại từ PRD mới; code vẫn khớp cột TSV | `/generate-bdd {prd-file}` là **đủ** |
+| `["tsv","code"]` | Cả BDD lẫn code đều cũ | `/generate-bdd` **rồi** `/generate-code {UC-ID}` |
+| `["code"]` | TSV đã cập nhật nhưng code chưa sinh lại | `/generate-code {UC-ID}` |
+
+*Không ghi `drifted_layers` thì hai ca đầu trông hệt nhau — người dùng hoặc chạy thiếu (cờ không sạch) hoặc chạy thừa (sinh lại code không cần thiết).*
 
 ### 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`.
+- **FE integration drift:** `@trace.revision` của doc vs `fe_tech_doc_revision` trong `.tsv` (row FE `--phase=integration`, theo từng platform; §4.5.4).
 
 Skip cột nào chưa có revision đã lưu (`—`), hoặc cả UC chưa có tech-doc.
 
+#### Lọc theo phạm vi — ĐỐI XỨNG với Step 4
+
+*Tech-doc có **đúng cùng hình dạng** với PRD: một doc **GỘP cấp PRD**, một `@trace.revision` chung cho nhiều UC. Chế độ **APPEND** (`generate-tech-docs` Bước 1) thêm UC mới vào doc đã có → revision bump → **mọi UC cũ lệch**, dù phần của chúng không đổi một dòng.*
+
+Đọc **§10 UC Coverage** và **Changelog** của tech-doc, trích tập UC mà row changelog trong khoảng revision đó nêu:
+
+| Điều kiện | Cờ |
+|---|---|
+| UC này **có** trong tập bị ảnh hưởng | `TECHDOC_DRIFT` / `FE_TECHDOC_DRIFT` 🟠 |
+| UC này **không** có, changelog nêu rõ scope | `TECHDOC_STALE_REF` ⓘ — dùng `--realign-techdoc-revision` |
+| Row changelog mơ hồ | 🟠 cho **mọi** UC (lưới an toàn) |
+
+### Step 5e — Realign mode *(chỉ chạy khi có flag)*
+
+*Đường ra rẻ cho hai cờ ⓘ ở Step 4/5. Không có nó thì cờ `PRD_STALE_REF`/`TECHDOC_STALE_REF` **không bao giờ sạch được**: `/generate-bdd` cập nhật được cột TSV, nhưng tag trong code thì chỉ `/generate-code` ghi — mà nó thấy row `OK` là skip (`generate-code` §Read Trace State). Vòng lặp đóng, và lối ra duy nhất là ép sinh lại code cho hàng loạt UC không hề thay đổi.*
+
+Parse `$ARGUMENTS`:
+
+| Flag | Làm gì |
+|---|---|
+| `--realign-prd-version {UC-ID}` | Cập nhật cột `prd_version` của TSV **và** tag `@trace.prd_version` trong các file code của UC đó → version PRD hiện tại |
+| `--realign-techdoc-revision {UC-ID}` | Tương tự với `tech_doc_revision`/`fe_tech_doc_revision` và tag `@trace.tech_doc_revision` → `@trace.revision` hiện tại |
+
+**Ba rào an toàn — bắt buộc, đây là lệnh SỬA CODE:**
+
+1. **Từ chối chạy** nếu UC đó có bất kỳ SC nào đang `DRIFT` hoặc `ORPHANED`, hoặc nếu Step 4/5 xếp nó là 🟠 (không phải ⓘ). Khi đó nội dung **có** đổi thật — dán nhãn lại là **che lỗi**. In:
+   ```
+   ❌ Từ chối realign {UC-ID}: UC này đang {PRD_DRIFT | có SC DRIFT | ORPHANED}.
+      Realign chỉ dành cho ⓘ STALE_REF (nội dung KHÔNG đổi, chỉ con trỏ version cũ).
+      Ở đây nội dung có đổi thật → /generate-bdd rồi /generate-code {UC-ID}.
+   ```
+2. **Chỉ sửa dòng bắt đầu bằng `@trace.`** — không đụng một dòng logic nào. **Guard sau-ghi:** đọc lại file, diff với bản trước; nếu có bất kỳ dòng nào **khác** ngoài các dòng `@trace.*` đã định → **khôi phục file** và dừng.
+3. **In chính xác** file + dòng đã sửa vào report — realign im lặng là realign không kiểm chứng được.
+
+Không đụng `dev_selftest`/`qc_status` (luật G28 không áp: **không có logic nào đổi** — đó chính là tiền đề của realign).
+
 ### Step 5c — BDD version drift check
 
 *Đối xứng với Step 4 (PRD drift). Trước đây tầng BDD là tầng DUY NHẤT không có cờ drift — dù `/generate-code` vẫn ghi `@trace.bdd_version` vào code và JSON report vẫn lưu nó. Dữ liệu có, chỉ thiếu phép so.*
@@ -610,6 +392,29 @@ Code mang version cũ hơn → gắn cờ `BDD_DRIFT`. Kèm theo, liệt kê cá
 
 **Chiều BDD → tech-doc** *(chỉ report, cổng chặn nằm ở `/review-tech-docs`)*: đọc map `@trace.bdd_versions` của tech-doc gộp; platform nào có `.feature` **mới hơn** entry trong map → gắn cờ `TECHDOC_STALE_VS_BDD`. Đây là ca nguy hiểm hơn drift-về-code: `/generate-code` DS3 thấy tech-doc `approved` sẽ lấy shape §4 **nguyên văn** làm contract "đã chốt", nên contract dựng từ BDD cũ sẽ lan thẳng vào code.
 
+### Step 5d — Design-spec drift check *(chỉ FE/App)*
+
+*Bỏ qua hoàn toàn với `system`/backend — không có design-spec.*
+
+*Đối xứng Step 5c. Design-spec là artifact upstream **cuối cùng** được đưa vào trace: nó điều khiển cả BDD FE/App (Screen States + AC-UI, xem `generate-bdd` §Design Spec — Gate & Load) lẫn code FE (màn hình, component inventory, link Figma frame), nhưng trước đây không có cột, không có tag, không có cờ. Nó **có** tự bảo vệ một chiều — `/generate-design-spec` reset `Status: draft` khi PRD đổi — nhưng chiều ngược lại (designer sửa design-spec SAU KHI BDD/code đã sinh) thì không gì bắt được.*
+
+Đọc `| **Version** |` **hiện tại** từ Metadata design-spec tại `{paths.specs_dir}/{domain}/{prd-slug}/design-spec/{TICKET-ID}-design-spec-{platform}-{slug}.md` *(`app-ios`/`app-android` không có bản riêng → fallback bản `-app-`)*.
+
+**Chiều design-spec → BDD.** So với cột `design_spec_version` của TSV:
+- Cột **cũ hơn** → `DESIGNSPEC_STALE_VS_BDD` 🟠. BDD FE/App dựng từ design-spec cũ → có thể thiếu Screen State / AC-UI vừa thêm. Route: `/generate-bdd {prd-file}`.
+
+**Chiều design-spec → code.** So với tag `@trace.design_spec_version` trong các file code FE implement UC đó:
+- Tag **cũ hơn** → `DESIGNSPEC_DRIFT` 🟠. Route: `/generate-code {feature-file}`.
+
+**Không kết luận khi thiếu đầu so:**
+- Cột `design_spec_version` = `—` (TSV cũ, hoặc BDD sinh khi chưa có design-spec) → skip chiều BDD.
+- File code FE **không có** tag `@trace.design_spec_version` (sinh trước khi tag này tồn tại) → skip chiều code, và đếm gộp **một dòng** — y hệt cách Step 5c xử `@trace.bdd_version` thiếu:
+  ```
+  ⚠️  {n} file FE thiếu tag @trace.design_spec_version → drift detection mù ở các file này.
+      Bổ sung khi sửa file lần tới (/review-code lăng kính Traceability sẽ bắt).
+  ```
+- Không tìm thấy file design-spec → skip im lặng (feature có thể chưa cần design-spec; `/generate-bdd` đã cảnh báo mềm ở chỗ của nó).
+
 ### 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).*
@@ -641,7 +446,7 @@ Code mang version cũ hơn → gắn cờ `BDD_DRIFT`. Kèm theo, liệt kê 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`,
+- **Cập nhật sổ `_seams.tsv`** (nếu tồn tại). **Khớp dòng theo khoá `(kind, name, consumer_uc)`** — `name` là tên port (seam) hoặc trách nhiệm (stub). *Không khớp theo `artifact`: class/method stub có thể được đổi tên hoặc di chuyển giữa hai lần chạy, lúc đó ta sẽ append dòng mới thay vì cập nhật dòng cũ và sổ đẻ ra bản ghi ma.* Cập nhật `status` + `last_updated`; giữ nguyên `owner_uc`/`binding` (do `/generate-code` sở hữu). 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`).
@@ -681,10 +486,40 @@ fe_integrated    = rows where fe_phase == integrated  # FE đã wire adapter th
 # công việc CHƯA XONG dù status có thể đã là OK (có code + có test trên mock).
 orphaned_count   = rows where status == ORPHANED     # code còn, scenario đã bị xoá khỏi .feature (Step 2b/Rule 0)
 trace_orphan_count = số tag @trace.implements/@trace.verifies trỏ vào SC không tồn tại VÀ không có row TSV (Step 2b)
+prd_drift_count  = số UC bị cờ PRD_DRIFT (lệch version VÀ changelog nêu UC này — Step 4)
+prd_stale_ref_count = số UC bị cờ PRD_STALE_REF (lệch version nhưng changelog KHÔNG nêu UC này —
+                   nội dung không đổi, chỉ con trỏ cũ). ⓘ không phải lỗi; sạch bằng --realign-prd-version
+techdoc_stale_ref_count = số UC bị cờ TECHDOC_STALE_REF (đối xứng, Step 5)
 bdd_drift_count  = số UC×platform bị cờ BDD_DRIFT (code mang @trace.bdd_version cũ hơn .feature — Step 5c)
+techdoc_drift_count = số UC bị cờ TECHDOC_DRIFT (code sinh từ tech_doc_revision cũ hơn @trace.revision — Step 5)
+fe_techdoc_drift_count = số UC×platform bị cờ FE_TECHDOC_DRIFT (FE wire theo fe_tech_doc_revision cũ — Step 5)
 techdoc_stale_vs_bdd_count = số platform mà tech-doc dựng từ bdd_version cũ hơn .feature hiện tại (Step 5c)
+designspec_drift_count = số UC×platform FE bị cờ DESIGNSPEC_DRIFT (code FE mang design_spec_version cũ hơn — Step 5d)
+designspec_stale_vs_bdd_count = số UC×platform FE mà BDD dựng từ design-spec cũ hơn bản hiện tại (Step 5d)
+by_service       = map {service → {total_scs, coded_scs, tested_scs, drift_count}} — gom theo cột `service` (cột 23)
+                   # Trả lời câu số MỘT của dự án nhiều đội: "đội nào còn bao nhiêu việc".
+                   # Trước khi có cột 23, trace gộp (spec_source) KHÔNG mang thông tin sở hữu ở
+                   # cấp row nên câu này không trả lời được. Bỏ qua map này ở single-service.
+by_platform      = map {platform → {total_scs, coded_scs, tested_scs, drift_count}} — gom theo
+                   platform (lấy từ TÊN FILE sổ `{UC-ID}-{platform}.tsv`, cùng nguồn với field
+                   `platform` của mỗi scenario ở Step 8)
+                   # CHỈ tạo ô cho platform THỰC SỰ có scenario — dự án chỉ có `web` thì chỉ một ô.
+                   # Trả lời "web xong bao nhiêu %, system xong bao nhiêu %" — câu thường ngày khi
+                   # làm FE và BE song song. Trước đó KHÔNG trả lời được từ `summary`: `by_service`
+                   # là bảng chia nhóm DUY NHẤT, mà cột `service` là `—` ở mọi row của dự án
+                   # single-service ⇒ nó gộp tất cả vào MỘT ô, và platform hoàn toàn vô hình.
+                   # Đây là hình dạng của G33: dữ liệu có ở cấp row (G48 vừa thêm `platform` vào
+                   # từng scenario) nhưng KHÔNG có ô tổng ⇒ dashboard chỉ đọc `summary` thì mù.
+                   # Bắt dashboard tự duyệt prds[].ucs[].scenarios[] mà cộng lại chính là cái bẫy
+                   # G33 đã chỉ ra: người viết dashboard đọc `summary`, thấy đủ, rồi tưởng xong.
+                   # KHÔNG thay `by_service` — hai TRỤC khác nhau, cùng hữu ích ở umbrella nhiều đội.
 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)
+seam_pending_count = số seam bị cờ SEAM_PENDING (owner UC chưa gen — ⓘ chưa phải lỗi; PM dùng để xếp thứ tự gen)
 stub_unresolved_count = số stub bị cờ STUB_UNRESOLVED (method còn trắng dù owner đã gen / có hàm song song — Step 5b)
+stub_pending_count = số stub bị cờ STUB_PENDING (owner BDD chưa gen — ⓘ chưa phải lỗi)
+# LUẬT (rules/workflow.md §Trace Contract): MỌI giá trị trong vocabularies.audit_flags phải có
+# một counter {flag_lowercase}_count ở đây VÀ trong summary của JSON. bin/self-check.js R7 ép
+# điều này — thiếu counter = cờ không quan sát được ở tầng tổng hợp, dashboard không thấy.
 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, —)
@@ -702,6 +537,20 @@ waiting_po       = rows where qc_owner == po       # PM view: blocked, waiting o
 tech_docs_count  = count .md files in {paths.tech_docs_dir}/{domain}/*/tech-docs/
 ```
 
+### Step 7b — Hàng đợi yêu cầu đổi PRD còn treo
+
+*Không phải trạng thái trace — nhưng đây là hàng đợi DUY NHẤT trong framework không có lệnh nào quét lại nó, nên nó cần một chỗ để không chìm. Chọn lệnh này vì nó được chạy thường xuyên nhất.*
+
+Quét `{paths.prd_change_requests_dir}/*.md` (mặc định `{spec_source}/feedback/prd-change-requests/`; **không** quét `archived/`). Thư mục không tồn tại hoặc rỗng → bỏ qua **im lặng**, không in gì.
+
+Với mỗi file, đọc metadata: `UC / Ticket`, `Status`, và tiêu đề. Chỉ giữ `Status: Open` (bỏ qua `incorporated` / `rejected`).
+
+Tính `days_waiting` = số ngày từ ngày file được tạo tới hôm nay. Nguồn ngày, theo thứ tự ưu tiên: (1) field ngày trong metadata nếu có · (2) `git -C {REPO} log --diff-filter=A --format=%ad --date=short -1 -- {file}` · (3) không lấy được → để `—`, đừng đoán.
+
+Lưu danh sách này cho §Output. **Không** ghi nó vào `trace-report.json` — nó không phải trạng thái trace, và JSON là contract với panel VS Code.
+
+> **Vì sao cần bước này:** ba hàng đợi feedback thì hai cái đã có người quét lại mỗi lần chạy — `/fix-bug` đọc `bug-reports/`, `/generate-bdd` quét `bdd-proposals/`. Riêng `prd-change-requests/` không có ai. Chỗ duy nhất nó từng xuất hiện là `/sync` Step 1d, mà Step 1d chỉ hiện những gì về **trong đúng lần pull đó** (`{old_sha}..{new_sha}`) — bỏ lỡ một lần là mất khỏi màn hình vĩnh viễn. Đây là loại yêu cầu **không cờ trace nào bắt được**: nó nói về hành vi chưa có AC nào phủ, nên theo mọi thước đo coverage thì nó không tồn tại.
+
 ### 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.
@@ -730,10 +579,19 @@ Schema:
     "fe_integrated": 0,
     "orphaned_count": 0,
     "trace_orphan_count": 0,
+    "prd_drift_count": 0,
+    "prd_stale_ref_count": 0,
     "bdd_drift_count": 0,
+    "techdoc_drift_count": 0,
+    "techdoc_stale_ref_count": 0,
+    "fe_techdoc_drift_count": 0,
     "techdoc_stale_vs_bdd_count": 0,
+    "designspec_drift_count": 0,
+    "designspec_stale_vs_bdd_count": 0,
     "seam_unwired_count": 0,
+    "seam_pending_count": 0,
     "stub_unresolved_count": 0,
+    "stub_pending_count": 0,
     "dev_selftest_passing": 0,
     "dev_selftest_failing": 0,
     "dev_selftest_not_run": 0,
@@ -743,7 +601,17 @@ Schema:
     "qc_not_run": 0,
     "waiting_dev": 0,
     "waiting_po": 0,
-    "tech_docs_count": 0
+    "tech_docs_count": 0,
+    "by_service": {
+      "<service path, e.g. user-service>": {
+        "total_scs": 0, "coded_scs": 0, "tested_scs": 0, "drift_count": 0
+      }
+    },
+    "by_platform": {
+      "<web | app | system — CHỈ platform thực sự có scenario>": {
+        "total_scs": 0, "coded_scs": 0, "tested_scs": 0, "drift_count": 0
+      }
+    }
   },
   "prds": [
     {
@@ -762,6 +630,7 @@ Schema:
           "scenarios": [
             {
               "sc_id": "<e.g. PAY-UC01-SC1>",
+              "platform": "web | app | system",
               "sc_title": "<title>",
               "spec_ver": "<current version from .feature>",
               "gen_ver": "<version at codegen time>",
@@ -778,6 +647,8 @@ Schema:
               "bdd_version": "<bdd version when code was generated>",
               "tech_doc_revision": 0,
               "fe_tech_doc_revision": 0,
+              "service": "<đội/submodule sở hữu — cột 23; null nếu '—'>",
+              "design_spec_version": "<version design-spec lúc sinh BDD — cột 24; null nếu '—'>",
               "status": "OK | DRIFT | GAP | UNTRACKED",
               "orphaned": false,
               "last_updated": "<YYYY-MM-DD>"
@@ -815,10 +686,34 @@ Schema:
     "prd_version_drift": [
       {
         "uc_id": "<UC-ID>",
-        "code_prd_version": "<version in code tag>",
-        "current_prd_version": "<version in PRD file>",
+        "current_prd_version": "<version in PRD file — mốc so sánh>",
+        "tsv_prd_version": "<cột prd_version của TSV — version lúc sinh BDD>",
+        "code_prd_version": "<tag @trace.prd_version trong code — version lúc sinh code>",
+        "drifted_layers": ["tsv", "code"],
         "changelog_since": ["<v1.1: ...>", "<v1.2: ...>"],
-        "fix": "/generate-bdd <prd-file> then /generate-code <UC-ID>"
+        "in_changelog_scope": true,
+        "fix": "chỉ [\"tsv\"] → /generate-bdd <prd-file> là đủ · có \"code\" → /generate-bdd rồi /generate-code <UC-ID>"
+      }
+    ],
+    "prd_stale_ref": [
+      {
+        "uc_id": "<UC-ID>",
+        "current_prd_version": "<version PRD file>",
+        "tsv_prd_version": "<cột prd_version>",
+        "code_prd_version": "<tag trong code>",
+        "drifted_layers": ["code"],
+        "changelog_since": ["<v2.0: thêm UC7 — không đụng UC1>"],
+        "in_changelog_scope": false,
+        "fix": "/validate-traces --realign-prd-version <UC-ID>   (chỉ sửa dòng nhãn, KHÔNG đụng logic)"
+      }
+    ],
+    "techdoc_stale_ref": [
+      {
+        "uc_id": "<UC-ID>",
+        "current_revision": 0,
+        "code_revision": 0,
+        "in_changelog_scope": false,
+        "fix": "/validate-traces --realign-techdoc-revision <UC-ID>"
       }
     ],
     "bdd_drift": [
@@ -840,6 +735,24 @@ Schema:
         "fix": "/generate-tech-docs <feature-file> then /review-tech-docs"
       }
     ],
+    "designspec_drift": [
+      {
+        "uc_id": "<UC-ID>",
+        "platform": "web | app",
+        "code_design_spec_version": "<@trace.design_spec_version trong code FE>",
+        "current_design_spec_version": "<| **Version** | của design-spec>",
+        "fix": "/generate-code <feature-file>"
+      }
+    ],
+    "designspec_stale_vs_bdd": [
+      {
+        "uc_id": "<UC-ID>",
+        "platform": "web | app",
+        "bdd_design_spec_version": "<cột design_spec_version của TSV>",
+        "current_design_spec_version": "<| **Version** | của design-spec>",
+        "fix": "/generate-bdd <prd-file>  — BDD có thể thiếu Screen State / AC-UI vừa thêm"
+      }
+    ],
     "orphaned": [
       {
         "sc_id": "<SC-ID đã bị xoá khỏi .feature>",
@@ -862,7 +775,7 @@ Schema:
         "uc_id": "<UC-ID>",
         "code_revision": 0,
         "current_revision": 0,
-        "fix": "/generate-code <UC-ID>"
+        "fix": "changelog KHÔNG nêu UC này → /validate-traces --realign-techdoc-revision <UC-ID> (rẻ, không đụng logic) · changelog CÓ nêu → /generate-code <UC-ID> --force"
       }
     ],
     "fe_techdoc_drift": [
@@ -871,7 +784,7 @@ Schema:
         "platform": "web | app",
         "code_revision": 0,
         "current_revision": 0,
-        "fix": "/generate-code <UC-ID> --phase=integration"
+        "fix": "changelog KHÔNG nêu UC này → /validate-traces --realign-techdoc-revision <UC-ID> · CÓ nêu → /generate-code <UC-ID> --phase=integration --force"
       }
     ],
     "seam_unwired": [
@@ -899,6 +812,11 @@ Schema:
 ```
 
 **Rules:**
+- **`by_platform` là bắt buộc** (nếu có ít nhất một scenario). Cùng hình dạng `by_service`, khoá **động** — một ô cho mỗi platform tìm thấy, không phải một ô cố định cho mỗi giá trị vocabulary. Thêm platform thứ tư vào vocabulary thì nó tự có ô, không cần sửa gì ở đây.
+  > Đây là lý do `by_platform` **không cần** một rule `self-check` riêng: khác cờ audit (mỗi cờ cần một counter mang tên riêng, nên R7 phải canh từng cái), ở đây không có gì để lệch.
+- **`platform` (bắt buộc, mỗi scenario):** lấy từ **tên file sổ** `{UC-ID}-{platform}.tsv` — Step 2 đã đọc nó để tìm đúng `.feature`. Giá trị: `web` | `app` | `system`.
+  > **Vì sao bắt buộc (G48):** `sc_id` **một mình không định danh được** một scenario. Chính Step 2 phát biểu điều đó: *"sc_id trùng số giữa các platform là 2 scenario khác nhau"*. Sổ TSV giải quyết bằng tên file; JSON thì làm phẳng mọi platform vào chung một cây `scenarios[]`, nên thiếu field này thì `AUTH-UC1-SC1` của web và của app **không phân biệt được** — panel hiện trùng lặp hoặc đè nhau, và không ai trả lời được *"SC1 của app xong chưa"*.
+  > Bất đối xứng cũ: `issues.orphaned[]` và `issues.fe_techdoc_drift[]` **đã** mang `platform`; chỉ cây dữ liệu chính là không.
 - `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
@@ -909,8 +827,10 @@ Schema:
   **TSV giữ nguyên chữ `ORPHANED`** trong cột `status` — TSV là nguồn-sự-thật, JSON chỉ là bản xuất cho panel.
 - `orphaned` (boolean): `true` chỉ khi cột `status` của TSV là `ORPHANED`; mọi row khác ghi `false` (đừng bỏ trống — panel đọc field vắng dễ ra `undefined`).
 - 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.
+- **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`; `service: "—"` → `null`; `design_spec_version: "—"` → `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, đừng bỏ qua cả file**): `qc_owner`/`qc_blocked_by` (pre-19-col) → `null`; `fe_tech_doc_revision` (pre-22-col) → `0`; `service`/`design_spec_version` (pre-24-col) → `null`. Lần `/generate-bdd` gen lại tiếp theo nâng header lên layout **24 cột** hiện tại.
+  > **Đọc theo TÊN CỘT ở header row, KHÔNG theo vị trí.** Header là dòng đầu mỗi `.tsv` — parse nó rồi tra theo tên. Đếm vị trí sẽ vỡ ở đúng file cũ mà luật này sinh ra để đỡ. Header thiếu hoàn toàn (file hỏng) → mới báo lỗi cho file đó và đi tiếp, không abort cả lệnh.
+  > **Cột `service` = `null` không bằng "không có đội".** Nó nghĩa là *chưa biết* (TSV cũ hơn cột 23). Gom vào một nhóm `"(chưa xác định)"` trong `by_service` thay vì bỏ khỏi thống kê — bỏ đi thì tổng của `by_service` nhỏ hơn `total_scs` mà không ai giải thích được vì sao.
 
 ### Step 8b — Living Docs Sync *(chỉ umbrella mode)*
 
@@ -918,18 +838,19 @@ Schema:
 
 **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.
+mỗi scenario row mang service sở hữu ở **cột `service`** (cột 23, do `/generate-bdd` ghi từ
+`@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)
+2. **Mirror tới panel location** `{panel_mirror}` (`./.trace-mirror` ở 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.
+   **Skip nếu `{paths.trace_dir}` đã nằm trong workspace hiện tại** (dev đang đứng trong spec repo —
+   panel đọc thẳng ở đó). **KHÔNG** copy `trace-history.jsonl` sang mirror (xem Step 8c).
 
 3. **In sync summary:**
    ```
@@ -938,115 +859,55 @@ mỗi scenario row mang service sở hữu qua `@trace.service`. Step này chỉ
    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
+> **Ranh giới git — tuyệt đối, không có ngoại lệ:**
+>
+> | Đường dẫn | Vai trò | Git |
+> |---|---|---|
+> | `{paths.trace_dir}/*.tsv` + `trace-history.jsonl` | **AUTHORITATIVE**, không regenerate được | **PHẢI commit** |
+> | `{living_docs_dir}/` (`.living-docs/`) | report sinh ra | gitignore |
+> | `{panel_mirror}/` (`.trace-mirror/`) | bản sao tiện cho panel | gitignore |
+>
+> Hai cái dưới được `/validate-traces` hoặc `/sync` dựng lại bất cứ lúc nào. Cái trên thì không —
+> mất là mất vĩnh viễn. Từ v0.4.3 mirror đổi tên thành `.trace-mirror` chính vì lý do này:
+> khi cả hai cùng tên `.trace`, một luật gitignore theo tên có thể xoá sổ gốc mà không ai biết.
 
-Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
+### Step 8c — Ghi nhật ký lịch sử *(mọi mode)*
 
-## Status Badge
+*`trace-report.json` bị **ghi đè** mỗi lần chạy (Step 8), và cột `last_updated` của TSV chỉ là một ngày bị 8 lệnh cùng ghi đè. Nên framework đo được **trạng thái** rất tốt nhưng không đo được **tốc độ** — không trả lời được "từ bao giờ", "đang lên hay xuống", "case này hỏng đi hỏng lại mấy lần". Step này thêm chiều thời gian với chi phí gần bằng 0.*
 
-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
+**Append** một dòng JSON (một bản ghi trọn vẹn trên một dòng) vào `{paths.trace_dir}/trace-history.jsonl`. Tạo file nếu chưa có.
 
-## Output Artifacts
+**Chỉ ghi DELTA, không chép lại snapshot** — snapshot đầy đủ đã ở `trace-report.json`:
 
-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})
+```json
+{"at":"<ISO-8601>","domain":"<domain hoặc all>",
+ "summary":{ …nguyên khối summary của Step 7… },
+ "changed":[{"sc_id":"PAY-UC1-SC2","platform":"web","from":"OK","to":"DRIFT"},
+            {"sc_id":"PAY-UC1-SC7","platform":"web","from":null,"to":"UNTRACKED"}],
+ "flags_opened":["SEAM_UNWIRED:ScoreAccumulationPort"],
+ "flags_closed":["STUB_UNRESOLVED:SegmentService#calculateSegment"]}
 ```
 
-Nếu không ghi file nào (vd: lệnh review hoặc phân tích) → ghi `Output Artifacts: none (read-only)`.
+**Cách tính `changed` / `flags_opened` / `flags_closed`:** đọc **dòng cuối cùng** của chính file này (đọc ngược từ cuối — không parse cả file) và so với kết quả lần này. `from: null` = row mới xuất hiện. Nếu file chưa tồn tại → đây là baseline: ghi `summary`, để `changed`/`flags_*` là `[]`.
 
-## Pipeline Position
+**Rotate:** file vượt **2000 dòng** → đổi tên thành `trace-history.{YYYY-MM}.jsonl` rồi bắt đầu file mới. Đừng xoá.
 
-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:
+**Năm ràng buộc — đây là phần dễ làm sai:**
 
-```
-Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-```
+| Ràng buộc | Vì sao |
+|---|---|
+| Ghi **CHỈ** vào `{paths.trace_dir}` (nơi authoritative). **KHÔNG** copy sang `{panel_mirror}` hay `{living_docs_dir}` | Nó là dữ liệu tích luỹ, không phải thứ regenerate được. Nhân bản nó ra chỗ sinh-ra là tạo hai lịch sử lệch nhau. |
+| Dòng vừa append **PHẢI kết thúc bằng newline** — file không bao giờ được kết thúc giữa dòng | File này là append-only và được merge bằng `merge=union` (xem `{paths.trace_dir}/.gitattributes`). Thiếu newline cuối thì lần append sau — hoặc một lần union merge — **nối hai bản ghi JSON thành một dòng**, và dòng đó không parse được. `--lint-trace` T8 bắt, nhưng đây là ca phòng được bằng một ký tự. |
+| File này **PHẢI được commit** cùng TSV | Nó là **dữ liệu**, không phải mirror. Regenerate lại không được — mất là mất vĩnh viễn. ⚠️ Đừng để nó dính vào luật gitignore của `.living-docs/` hay panel mirror; hai cái đó là bản sinh ra, cái này thì không. |
+| **Không đụng** TSV và `trace-report.json` | TSV là bảng **trạng thái** — giữ nó phẳng. Lịch sử là file riêng, format riêng, vòng đời riêng. `trace-report.json` là contract với panel VS Code. |
+| **Không lệnh nào được ra quyết định dựa trên file này** | Nó để **quan sát**, không phải để gác cổng. Một cái cổng phụ thuộc file có thể bị xoá là cổng dở. Cổng chặn PR vẫn chỉ là 4 cờ 🔴. |
 
-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) |
-| /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       | 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.)*
+Ghi thất bại (không có quyền, đĩa đầy) → **cảnh báo mềm một dòng rồi đi tiếp**. Nhật ký hỏng không được làm hỏng lệnh audit.
+
+## Output
 
+**Đọc `.agent/steps/report-footer.md`** và áp đúng khuôn footer trong đó (Status Badge ·
+Output Artifacts · Next) cho report cuối, kèm khối bên dưới.
 
 ```
 /validate-traces — {domain}
@@ -1063,6 +924,15 @@ Next     : {lệnh gợi ý kèm ví dụ tham số}
               · {orphaned_count} ORPHANED · {trace_orphan_count} TRACE_ORPHAN
    Build xanh, test từng-UC xanh, coverage đẹp — nhưng luồng ghép chạy vào no-op,
    hoặc code đang trỏ vào scenario đã bị xoá. KHÔNG coi là pass tới khi CẢ BỐN = 0.
+{in dòng ⓘ dưới đây chỉ khi drift_count + bdd_drift_count > 0 — để hai loại cờ đứng cạnh nhau thay vì ở hai đầu report}
+   ⓘ  Ngoài cổng: {drift_count} DRIFT · {bdd_drift_count} BDD_DRIFT — "code CHƯA theo kịp spec".
+      KHÔNG chặn PR (khác 4 cờ trên), nhưng cũng chưa xong.
+
+{khối 📈 CHỈ in khi trace-history.jsonl đã có ≥1 dòng trước lần chạy này (Step 8c) — lần chạy
+ đầu tiên là baseline, không có gì để so, bỏ cả khối. Dấu +/− lấy theo hướng thực tế.}
+📈 So lần chạy trước ({ngày dòng cuối}): code {+2}% · test {−1}% · DRIFT {+3} · UNTRACKED {−5}
+   Đèn mới bật: {SEAM_UNWIRED × 1}   ·   Đèn đã tắt: {STUB_UNRESOLVED × 2}
+   {n} scenario đổi trạng thái — chi tiết: {paths.trace_dir}/trace-history.jsonl
 
 | UC-ID       | SC   | Title (truncated)            | Spec  | Gen   | Code                 | Tests          | Status   |
 |-------------|------|------------------------------|-------|-------|----------------------|----------------|----------|
@@ -1087,6 +957,20 @@ Tech-doc lỗi thời so với BDD:
         "đã chốt" và lấy shape NGUYÊN VĂN → contract từ BDD cũ lan thẳng vào code.
     → /generate-tech-docs {feature-file} → /review-tech-docs (cổng T-BDD)
 
+Design-spec Drift (chỉ FE/App — designer sửa thiết kế SAU KHI BDD/code đã sinh):
+  {UC}-UC1 (web) — code dựng từ design-spec v1.2, design-spec giờ v1.5
+    → /generate-code {feature-file}
+  {UC}-UC4 (app) — BDD dựng từ design-spec v2.0, design-spec giờ v2.3
+    ⚠️  BDD có thể THIẾU Screen State / AC-UI vừa thêm — không phải chỉ lỗi thời nhãn.
+    → /generate-bdd {prd-file}
+  ⚠️  {n} file FE thiếu tag @trace.design_spec_version → drift detection mù ở các file này
+
+{khối by_service CHỈ in ở umbrella mode (có section `services`) — bỏ ở single-service}
+Theo đội (cột `service`):
+  user-service    12/15 SC có code · 10 test ·  2 DRIFT
+  web-app          8/8  SC có code ·  8 test ·  0 DRIFT
+  (chưa xác định)  3/3  SC có code ·  3 test ·  0 DRIFT   ← TSV cũ hơn cột 23, chạy /generate-bdd để điền
+
 FE còn dùng mock (fe_phase = ui — có UI + test nhưng CHƯA nối API thật):
   {UC}-UC1 (web) — {n} SC ở fe_phase=ui
     → /generate-code {feature-file} --phase=integration  (hoặc để trống --phase cho fe_full)
@@ -1107,16 +991,30 @@ Trace orphan (tag trỏ vào SC không tồn tại, KHÔNG có row .tsv nào):
     (Không lệnh nào khác bắt được cái này — row .tsv đã bị xoá bởi version cũ,
      hoặc tag ghi sai id ngay từ đầu.)
 
-PRD Version Drift:
-  {UC}-UC2 — code ở PRD v1.0, PRD giờ ở v1.2
+PRD Version Drift (changelog CÓ nêu UC này — nội dung đổi thật):
+  {UC}-UC2 — code ở PRD v1.0, PRD giờ ở v1.2   [lệch: tsv, code]
     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:
+{khối ⓘ dưới CHỈ in khi prd_stale_ref_count > 0}
+ⓘ PRD_STALE_REF — {n} UC mang con trỏ PRD cũ nhưng changelog KHÔNG nêu chúng:
+  {UC}-UC1, {UC}-UC3, {UC}-UC4 — PRD v1.4 → v2.0 vì "thêm UC7", không đụng các UC này
+    Nội dung KHÔNG đổi → không cần sinh lại code. Chỉ là nhãn version cũ.
+    → /validate-traces --realign-prd-version {UC-ID}   (chỉ sửa dòng @trace.*, KHÔNG đụng logic)
+  ⚠️  Đây KHÔNG phải lỗi. Nó tồn tại vì version PRD là MỘT số cho cả tài liệu nhiều UC —
+      thêm một UC làm mọi UC cũ lệch số. Trước khi có bộ lọc này, cả {n} UC đều ăn cờ đỏ oan,
+      và làm theo hướng dẫn cũng không tắt được (generate-code skip row đang OK).
+
+Tech-Doc Revision Drift (changelog CÓ nêu UC này):
   {UC}-UC3 — code sinh từ tech-doc revision 2, giờ ở revision 4
-    → Review thay đổi tech-doc rồi /generate-code {UC-ID}
+    → /generate-code {UC-ID} --force
+
+{khối ⓘ dưới CHỈ in khi techdoc_stale_ref_count > 0}
+ⓘ TECHDOC_STALE_REF — {n} UC mang revision tech-doc cũ nhưng changelog KHÔNG nêu chúng:
+  {UC}-UC5, {UC}-UC6 — revision 2 → 4 vì UC8 được APPEND vào doc gộp
+    → /validate-traces --realign-techdoc-revision {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,
@@ -1128,11 +1026,27 @@ Seam & Stub Audit (mồ côi khi ghép luồng):
        → /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)
 
+{khối dưới CHỈ in khi Step 7b tìm thấy ≥1 request Status: Open — else bỏ cả khối}
+📥 Yêu cầu đổi PRD đang chờ ({n} — chưa ai xử lý):
+     {UC-ID} — "{title}"        chờ {days_waiting} ngày
+     {UC-ID} — "{title}"        chờ {days_waiting} ngày
+   Đây KHÔNG phải coverage gap: nó là requirement chưa có AC nào phủ, nên KHÔNG cờ
+   trace nào bắt được — theo mọi thước đo coverage thì nó không tồn tại. Chỉ hết khi
+   PO đưa vào PRD.
+   → PO đọc request, đặt Status: accepted, rồi /extend-prd {prd-file}
+     (nó tự nhặt request, chốt AC/BR, đánh số nối tiếp, bump version + changelog,
+      và đóng dấu incorporated + archived/ — không phải làm tay bước nào).
+
 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
+  - /generate-bdd {prd-file}     cho PRD_DRIFT 🟠 (changelog CÓ nêu UC này)
+  - /validate-traces --realign-prd-version {UC-ID}       cho PRD_STALE_REF ⓘ
+  - /validate-traces --realign-techdoc-revision {UC-ID}  cho TECHDOC_STALE_REF ⓘ
+      ↳ Hai cái này chỉ sửa dòng @trace.*, KHÔNG đụng logic. Đừng /generate-code cho
+        chúng — version bump không đụng UC này, sinh lại code là rủi ro không đáng.
   - /generate-code {feature-file} cho BDD_DRIFT (code sinh từ .feature cũ hơn)
+  - /generate-code {feature-file} cho DESIGNSPEC_DRIFT · /generate-bdd cho DESIGNSPEC_STALE_VS_BDD
   - /generate-tech-docs + /review-tech-docs  cho tech-doc lỗi thời so với BDD
   - 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)
@@ -1140,11 +1054,24 @@ Recommendations:
                                  scenario trở lại .feature, hoặc sửa sc_id của tag.
                                  KHÔNG có lệnh tự xử: cần người xác nhận behavior còn cần hay không.
 
-⚠️  Chỉ tạo PR khi mọi cờ 🔴 = 0 (SEAM_UNWIRED · STUB_UNRESOLVED · ORPHANED · TRACE_ORPHAN).
+⚠️  CỔNG TẠO PR = 4 cờ 🔴 đều = 0 (SEAM_UNWIRED · STUB_UNRESOLVED · ORPHANED · TRACE_ORPHAN).
+    Đây là cổng "code đang HỎNG" — luồng ghép chạy vào hàm rỗng, hoặc code trỏ vào
+    scenario đã bị xoá. Bốn cái này build xanh và test xanh vẫn không phát hiện được.
+
+    Cổng này KHÔNG bao gồm DRIFT · BDD_DRIFT · PRD_DRIFT · TECHDOC_DRIFT — đó là
+    "code CHƯA theo kịp spec", một loại nợ khác: nó không làm hỏng luồng đang chạy.
+{dòng dưới CHỈ in khi (drift_count + bdd_drift_count + prd_drift + techdoc_drift) > 0}
+    Hiện có {n} scenario/UC đang ở trạng thái đó — không chặn PR, nhưng xử trước khi
+    coi tính năng là xong. "Hết cờ 🔴" ≠ "sạch".
+
+📜 Lịch sử  → {paths.trace_dir}/trace-history.jsonl  (+1 dòng — {n} lần chạy đã ghi)
+   Đây là DỮ LIỆU, không phải mirror: regenerate lại không được, mất là mất vĩnh viễn.
+   PHẢI commit cùng TSV.
 
 [Chỉ umbrella mode]
 Living Docs canonical → {living_docs_dir}/  (specs module — shared, gitignored)
-Panel mirror          → {panel_mirror}/trace-report.json  (current workspace)
+Panel mirror          → {panel_mirror}/trace-report.json  (.trace-mirror/, gitignored)
   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).
+  ✅ Commit    : {paths.trace_dir}/  (*.tsv + trace-history.jsonl — authoritative)
+  🚫 Gitignore : .living-docs/  và  .trace-mirror/   (sinh ra, dựng lại được)
 ```