@educa-corp/sdd-framework 0.5.0 → 0.7.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,419 +79,154 @@ 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:
+CHECKPOINT — Target: {resolved file path}
+Tiếp tục? (Y/N)
+```
 
-- **§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*
+**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:
 
-**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.
+```
+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)
+```
 
----
+### 3c — Cờ nào bật, cờ nào KHÔNG
 
-## Bước 4 — [SAFETY] Nạp quy tắc bảo vệ dữ liệu
+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:
 
-Đọc `.agent/rules/data-protection.md` (hoặc `rules/data-protection.md` từ bản cài đặt framework).
+| 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 | ⚠️ |
 
-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.
+**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.
 
-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*`.
+> **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.
 
----
+### 3d — Chờ trả lời
 
-## Bước 5 — [DOMAIN] Nạp Business Dictionary (có điều kiện)
+- "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).
 
-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 ý: Lệnh này **không có target file đơn** — nó quét nhiều thư mục, nên gate Bước 1 không phân giải file. Phạm vi audit do **Step 0-A** phân giải từ `$ARGUMENTS` (`--domain` / `--prd` / `--uc`; không có cờ nào = toàn bộ).*
 
-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
+## 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.
 
-Nếu file không tồn tại → bỏ qua âm thầm. Không cảnh báo hay chặn.
+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ỗ.
 
 ---
 
-## Bước 6 — [DOMAIN] Nạp Core Entities (có điều kiện)
+## Process
 
-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`.
+### Step 0-A — Phân giải **phạm vi audit** *(chạy TRƯỚC Step 0)*
 
-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.)
+*Contract: `bin/trace-schema.json` → `gate.report_root_keys`. Đây là đầu PRODUCER của một sợi dây mà đầu CONSUMER (`gate-trace`) đã có sẵn từ trước.*
 
-**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
+Parse `$ARGUMENTS` (đã tách các cờ khác ở gate Bước 1):
 
-Nếu file không tồn tại → bỏ qua âm thầm.
+| Cờ | `scope.kind` | `scope.value` | Hẹp lại những gì |
+|---|---|---|---|
+| *(không có)* | `all` | `"all"` | Không hẹp — audit toàn bộ |
+| `--domain {domain}` | `domain` | tên domain | Chỉ sổ + spec dưới `{domain}/` |
+| `--prd {TICKET-ID}` | `prd` | TICKET-ID | Chỉ **một** feature-package (phân giải `{domain}/{prd-slug}` từ TICKET-ID) |
+| `--uc {UC-ID}` | `uc` | UC-ID | Chỉ **một** UC — **mọi platform của nó** (`{UC-ID}-*.tsv`) |
 
----
+Nhiều cờ scope cùng lúc → **DỪNG**, báo lỗi: chúng loại trừ nhau, và tự ý ưu tiên một cái là hẹp phạm vi mà người dùng không biết.
 
-## Bước 6.5 — [PLATFORM] Suy ra active_module và platform_type
+`--prd`/`--uc` không phân giải được về một package/UC có thật → **DỪNG** và liệt kê ứng viên. **KHÔNG** âm thầm rơi về `all` (chạy toàn bộ khi người ta xin một phần là đốt 30 phút không ai muốn) và **KHÔNG** âm thầm audit rỗng (báo cáo "sạch" trên 0 row).
 
-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:
+Lưu `scope` — mọi step sau dùng nó:
 
-```
-active_module = tech_stack.module   (vd: "java-spring", "react", "flutter")
-```
-
-| `platform_type` | Modules |
+| Step | Hẹp thế nào |
 |---|---|
-| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
-| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular`, `phaser-game` |
-| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
-
-Nếu `tech_stack.module` rỗng hoặc không nhận diện được → set `platform_type = "unknown"` và gắn cờ ⚠️ trong recap Bước 7.
-
-Hai biến này (`active_module`, `platform_type`) là nguồn chuẩn cho mọi logic rẽ nhánh trong các lệnh cần hành vi riêng theo platform (dev-gen-test, debug, fix-bug, dev-smoke-test).
-
----
-
-## Bước 6.7 — [GUARDRAILS] Nạp Project Lessons (có điều kiện)
-
-*Các lỗi tích luỹ mà AI không được lặp lại trong dự án này. Chúng được bổ sung dần qua `/learn`
-hoặc được chấp nhận trong `/review-code`, `/fix-bug`, `/debug`.*
-
-Phân giải path file lessons:
-- Dùng `paths.lessons_file` nếu được set (có thể bị service override ở chế độ umbrella, Bước 1.6)
-- Else mặc định `specs/domain-knowledge/lessons-learned.md`
-- Ở chế độ umbrella/service (khi `service_root` được set), nếu `paths.lessons_file` chưa set, mặc định `{service_root}/.agent/project-lessons.md`
-
-Nếu file tồn tại, đọc và lưu TẤT CẢ lesson làm **GUARDRAIL ĐANG HOẠT ĐỘNG** cho phiên:
-- Coi **Rule** của mỗi lesson là ràng buộc cứng — cùng mức ưu tiên với coding standards trong CLAUDE.md (Bước 3).
-- Trước khi sinh hoặc sửa bất kỳ artifact nào (PRD, BDD, tech-doc, code, test), đối chiếu output với mọi lesson có `category` khớp lệnh hiện tại VÀ `scope` khớp target (domain / file).
-- Nếu output sinh ra vi phạm một lesson → sửa **trước khi** trình bày, và ghi rõ lesson nào (`L-NNN`) đã được áp dụng.
-
-Nếu file không tồn tại → bỏ qua âm thầm (chưa có lesson nào được ghi nhận).
+| Step 0 / Step 1 | `all_trace_dirs` giữ nguyên, nhưng chỉ đọc TSV **khớp scope**: `{trace_dir}/{domain}/**` · `{trace_dir}/{domain}/{prd-slug}/**` · `{trace_dir}/**/{UC-ID}-*.tsv` |
+| Step 1.0 (lint) | truyền `--trace` như cũ — **lint luôn chạy toàn bộ**. Sổ hỏng ở domain khác vẫn là sổ hỏng, và lint rẻ (không LLM) |
+| Step 2b · 3.9 · 4 · 5* · 7 | chỉ các PRD/UC trong scope |
+| Step 6 · 6b | chỉ ghi lại TSV + mốc của phần trong scope |
+| Step 8 | ghi `scope` **và** `domain` vào biên bản (xem dưới) |
 
----
-
-## 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:
+**In phạm vi ngay đầu run**, trước khi làm gì:
 ```
-[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}
+Phạm vi: {all | domain={d} | prd={TICKET-ID} | uc={UC-ID}}
+         {n} PRD · {m} UC · {k} sổ  →  {ước lượng: toàn bộ repo | một phần}
 ```
-
-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.
-
+*Không có dòng này thì người dùng không biết mình vừa gọi một lệnh cỡ nào — và đây là lệnh đắt nhất trong 33 lệnh (~33k token chỉ dẫn trước khi mở artifact nào).*
+
+> **Vì sao step này là "nối dây", không phải "thêm tính năng" (GAPS-v4 G57).**
+> Trước nó, **năm** chỗ trong lệnh này mô tả một *"domain argument"* / *"domain filter"* **không tồn
+> tại**: ghi chú Gate (*"target là một tên domain hoặc UC-ID cụ thể từ `$ARGUMENTS`"*) · Step 1 đọc TSV
+> *"khớp domain target"* · schema biên bản `"<domain argument, or 'all' if no filter>"` · Step 8
+> *"nếu có domain filter, chỉ gồm các PRD đó"* · dòng `trace-history` mang field `domain`.
+> Và `gate-trace` **đã** đọc `report.domain` rồi **chặn PR** nếu nó khác `all`.
+>
+> Nhưng Step 0 đặt `all_trace_dirs` = toàn bộ **vô điều kiện**, và chỗ duy nhất parse `$ARGUMENTS` là
+> Step 5e cho hai cờ `--realign`. Nên ô đó **luôn** ghi `all`, và phần kiểm của gate **chưa bao giờ
+> chạy một lần nào**.
+>
+> Đây đúng hình dạng **R1 fail build vì nó** — *"field có consumer mà không có producer"*, ca
+> `@trace.sc_version` (3 consumer, 0 producer, sống qua nhiều version không ai bắt được). Nó sống
+> được vì R1 chỉ canh field trong **sổ TSV** và tag trong **code**, không canh key ở cấp gốc **biên
+> bản JSON**. `self-check` **R9(h)** giờ canh cả hai đầu.
+>
+> Và ghi chú Gate còn **tệ hơn im lặng** — nó gây nhầm: một agent đọc *"target là một tên domain hoặc
+> UC-ID"* sẽ **tin rằng** scoping hoạt động.
 
 ---
-
-## Process
-
 ### Step 0 — Umbrella Mode Detection
 
 Kiểm tra mảng `services` có tồn tại trong `project-context.yaml` không.
@@ -517,6 +251,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.
@@ -539,6 +311,29 @@ Nếu version SC trong `.feature` khác `spec_ver` của `.tsv` → cập nhật
 
 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 2c — Phân giải lại `service` từ config hiện tại *(G51)*
+
+*Cùng tinh thần Step 2 với `spec_ver`: cột TSV là **cache**, `services:` trong `project-context.yaml`
+là **nguồn**. Mỗi lần chạy, đối chiếu lại.*
+
+Với mỗi row có `service` ∈ (`unrouted`, `unresolved`), tra lại `services:` theo
+`domain` + `platform` (từ tên file sổ) + `prd_slug`:
+
+| Kết quả tra | Hành động |
+|---|---|
+| Giờ **khớp** một entry | **Cập nhật `service` = path đó** (in memory, ghi lại ở Step 6). Không cần chạy lại `/generate-bdd`. |
+| Vẫn không khớp | Giữ `unrouted` → gắn cờ 🟠 `SERVICE_UNROUTED` |
+| Config vẫn sai cấu trúc | Giữ `unresolved` → cùng cờ, nhưng lý do khác (bug config, không phải chờ quyết) |
+
+> **Vì sao lệnh này được ghi một cột do `/generate-bdd` sở hữu:** đây là **ngoại lệ có chủ ý** với luật
+> *"mỗi cột một chủ"* (`rules/workflow.md` §Trace Contract), và nó **không vi phạm tinh thần** của luật:
+> lệnh này **không ghi một giá trị mới** — nó chỉ **phân giải một placeholder mà `/generate-bdd` đã cố ý
+> để lại**. Khai tường minh trong `bin/trace-schema.json`: `service.written_by = [generate-bdd, validate-traces]`.
+>
+> Đây là thứ làm sổ **tự lành**: architect thêm mapping → lần `/validate-traces` kế tiếp nâng
+> `unrouted` → path. Không sửa tay, không sinh lại BDD. Không có bước này thì `unrouted` **đọng lại
+> vĩnh viễn** — đúng bệnh `TBD` mà G1/G28 đã chỉ ra.
+
 ### Step 2b — Reverse audit (bắt tag mồ côi)
 
 *Step 2 đi chiều **spec → code** (mỗi row TSV, SC đó implement tới đâu). Step này đi **chiều ngược** — bắt lớp lỗi mà Step 2 cấu trúc không thể thấy: code trỏ vào một scenario **không còn tồn tại**. Xảy ra khi gen lại BDD làm một SC biến mất (gộp / đổi số / xoá) trong khi code implement nó vẫn nằm đó, vẫn được caller gọi.*
@@ -573,6 +368,84 @@ Không tìm thấy tag mồ côi nào → bỏ qua im lặng.
 
 > **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 3.9 — Phát hiện sửa spec ngoài đường chính thức *(chạy TRƯỚC Step 4)*
+
+*Contract: `bin/trace-schema.json` → `spec_edit_detection`. Cờ: `PRD_UNTRACKED_EDIT`.*
+
+**Vì sao bước này đứng TRƯỚC Step 4.** Step 4 và mọi bước sau nó đều dựa trên một giả định
+**chưa được kiểm**: *nhãn `Version` của PRD phản ánh đúng nội dung hiện tại của nó.* Nếu ai sửa nội
+dung mà không bump nhãn thì giả định đó sai, và Step 4 sẽ phán *"version khớp ⇒ sạch"* trên một tài
+liệu đã đổi. Kiểm cấu trúc drift trên một nhãn không còn đúng thì cũng vô nghĩa như G1 kiểm cấu trúc
+một quyển sổ sắp mất — nên hỏi trước.
+
+**Điểm mù mà nó bịt (GAPS-v4 G54).** Toàn bộ lưới an toàn của framework so **nhãn version**, không so
+**nội dung** — không có một content hash nào ở đâu. Nên một PRD bị sửa tay là điểm mù **tuyệt đối**:
+Step 4 thấy `PRD Version == prd_version` ⇒ sạch · `gate-trace` thấy report khớp sổ ⇒ PASS ·
+`require-fresh-audit` thấy PR không chạm tag ⇒ không đòi audit. **Cả ba tầng xanh, và cả ba đúng theo
+định nghĩa của chính chúng.**
+
+#### Đọc mốc của lần audit trước
+
+Đọc khối **`spec_baseline`** trong `trace-report.json` của lần chạy trước (path:
+`{living_docs_dir}/trace-report.json`). Mỗi entry: `prd_path` · `sha_at_audit` · `version_at_audit`.
+
+- Khối **vắng** (lần audit đầu, hoặc report sinh bởi version cũ hơn) → **bỏ qua so sánh**, chỉ **ghi
+  mốc mới** ở Step 6b. In một dòng: `ⓘ spec_baseline: lần đầu ghi mốc — check sửa-ngoài-đường bắt đầu có hiệu lực từ lần chạy sau.`
+
+#### So — hai nguồn bằng chứng, cần cả hai
+
+Với mỗi file PRD trong phạm vi, ở repo chứa `{paths.specs_dir}`:
+
+| Nguồn | Lệnh | Bắt ca nào |
+|---|---|---|
+| **git diff** | `git -C {specs repo} diff --name-only {sha_at_audit}..HEAD -- {prd_path}` | sửa **đã commit** |
+| **git status** | `git -C {specs repo} status --porcelain -- {prd_path}` | sửa **CHƯA commit** — ca thường gặp nhất, vì PO đang gõ |
+
+Thiếu nguồn thứ hai là mù với cả một lớp ca: PO sửa xong, chưa commit, chạy audit — và audit nói sạch.
+
+#### Phán
+
+| Nội dung đổi? | `Version` hiện tại vs `version_at_audit` | Kết luận |
+|:---:|---|---|
+| **có** | **BẰNG NHAU** | 🔴 **`PRD_UNTRACKED_EDIT`** — có người sửa ngoài `/generate-prd` · `/extend-prd` · `/amend-prd` · `/refine-prd` · `/review-context` |
+| có | khác | ✅ không cờ — đã đi đường chính thức. Step 4 tiếp quản bình thường |
+| không | bất kỳ | ✅ không cờ |
+
+**Không có báo oan:** ca duy nhất bật cờ là *"đổi nội dung, giữ nguyên nhãn"*. Sửa **và** bump
+version thì `version != version_at_audit` ⇒ im.
+
+#### Ca không kiểm được → nói rõ là đang mù
+
+Không phải git repo · `sha_at_audit` không còn (history bị rewrite) · `git` không khả dụng →
+**bỏ qua** check này và in:
+```
+⚠️  Chưa kiểm được sửa-ngoài-đường cho {n} PRD ({lý do}) — điểm mù G54 đang MỞ ở các file này.
+```
+**KHÔNG** bịa cờ, và **KHÔNG** im lặng. Im lặng là lựa chọn rẻ nhất và tệ nhất trong ba.
+
+#### Đường ra — tự lành, cố ý KHÔNG có lệnh escape
+
+Cách sửa đúng là **bump version + ghi một row changelog nêu UC bị ảnh hưởng** — tức đúng việc
+`/amend-prd` làm hộ. Làm xong thì `version != version_at_audit` ⇒ cờ tự tắt, và logic `PRD_DRIFT`
+bình thường tiếp quản (đúng, vì nội dung có đổi thật).
+
+> **Vì sao KHÔNG có `--accept-edit`:** thêm nó là thêm một đường **dán nhãn lên thay đổi chưa ai
+> xem** — đúng cái sai mà ba rào của `--realign` (Step 5e) tồn tại để chặn.
+
+#### Vì sao cờ này KHÔNG nằm trong `gate.blocking`
+
+Quyết định có chủ ý, ghi ở `spec_edit_detection.$comment`:
+
+| | |
+|---|---|
+| `gate.blocking` nghĩa hẹp là **code đang hỏng** | Cờ này nói về **spec**; code có thể đang hoàn toàn đúng. R9(e) tồn tại để giữ đúng ranh giới đó |
+| Nợ tồn khi mới bật | Mọi project đang chạy đều đã có PRD sửa tay ⇒ cờ chặn mới sẽ đỏ khắp nơi ở lần đầu ⇒ **người ta tắt cổng** ⇒ mất luôn 4 cờ 🔴 thật. Đó đúng là thất bại R9(e) được viết ra để chặn, chỉ đến bằng một cửa khác |
+| Nhưng nó vẫn 🔴 | In mỗi lần chạy, có khối riêng trong report + counter trong `summary` — đủ để thấy, không đủ để làm tắt cổng |
+
+Team nào đã dọn sạch nợ tồn thì tự thêm `prd_untracked_edit_count` vào `gate.blocking` (kèm `why`) —
+`self-check` R13(e) canh việc đó.
+
+---
 ### Step 4 — PRD version drift check
 
 Với mỗi UC, so:
@@ -586,13 +459,43 @@ Nếu layer nào sau version PRD hiện tại → trích các changelog entry k
 
 *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.)*
+Đọc các row `# Change Log` của PRD **từ version của layer cũ nhất tới hiện tại**. Mỗi row mang một `{changelog_scope}` — contract máy đọc, khai ở `bin/trace-schema.json` → `changelog_row_contract`; producer là `/refine-prd` Phase 3, `/extend-prd` Bước 6, `/review-context` Fix/Resume Phase 3, và **bắt buộc** ghi thông tin này chính vì mục đích ở đây. *(`/generate-bdd` Version Check đọc cùng dữ liệu.)*
+
+**Dựng `affected_ucs` theo ba bước — KHÔNG bỏ bước 2:**
+
+**1. Tách mệnh đề.** Mỗi row `{changelog_scope}` gồm các mệnh đề ngăn bằng `;`, mỗi mệnh đề mở đầu bằng đơn vị sở hữu: `{UC-ID}: {mô tả}` hoặc `PRD-global: {mô tả}`.
+
+**2. Chuẩn hoá về UC — phép phân giải `BR/AC → UC sở hữu`.** Trong mỗi mệnh đề, ngoài UC-ID mở đầu còn có thể có BR/AC được nêu. Đưa **mọi** BR/AC về UC sở hữu **trước khi** so:
+
+| Gặp | Phân giải thành |
+|---|---|
+| `BR{n}` | UC có `BR{n}` trong **bảng Business Rule** của nó (PRD §3) |
+| `AC{n}` | UC có `AC{n}` ở dòng **`**AC liên quan:**`** của nó (PRD §3) |
+| `PRD-global` | **không** thuộc UC nào — không thêm gì vào `affected_ucs` |
+| BR/AC **không** phân giải được về UC nào *(ID đã bị xoá, hoặc PRD lệch cấu trúc)* | coi **cả row** là **mơ hồ** → hàng 3 dưới đây. **KHÔNG** bỏ qua im lặng mệnh đề đó |
+
+*Không phát sinh I/O: Step 4 đã mở file PRD này ở đầu bước.*
+
+**3. Phân loại từng UC** *(first-match-wins)*:
 
 | Đ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 |
+| **Bất kỳ** row nào trong khoảng **mơ hồ** (không mệnh đề nào nêu được đơn vị sở hữu, hoặc bước 2 không phân giải được) | `PRD_DRIFT` 🟠 cho **MỌI** UC | Không suy đoán được thì quét rộng |
+| UC này **có** trong `affected_ucs` | `PRD_DRIFT` 🟠 | Cần regen thật — theo bảng `drifted_layers` bên dưới |
+| UC này có trong `affected_ucs` **CHỈ** qua (các) mệnh đề mang hậu tố **`[no-behavior]`** | `PRD_STALE_REF` ⓘ | Producer đã **chứng minh** thay đổi không đổi hành vi (chỉ thêm/bỏ vỏ cấu trúc). Xem `changelog_row_contract.neutral_checks` |
+| UC này **không** có trong `affected_ucs`, **và** mọi row 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` |
+
+> **Vì sao bước 2 là bắt buộc (G53).** Bản cũ viết *"trích tập UC/AC/BR được nêu"* rồi so bằng phép thử *"**UC** này có trong tập?"*. Hai câu đó **không khớp nhau**: tập chứa lẫn UC, AC và BR, nhưng phép thử chỉ hỏi về UC. Nên một row như `thêm UC7: AC12-AC14; sửa BR8` cho tập `{UC7, AC12-14, BR8}` — và **UC3, chủ sở hữu BR8, không có trong đó**.
+>
+> Row đó nêu rất nhiều ID nên **không** rơi vào hàng "mơ hồ". Kết quả: UC3 → ⓘ *"không phải lỗi"*, trong khi BR mà nó sở hữu vừa đổi hành vi. Và ⓘ **mở cửa** cho `--realign-prd-version` (rào an toàn của nó chỉ **từ chối khi UC là 🟠**) ⇒ nhãn `prd_version` bị dán lại ở cả TSV lẫn tag code ⇒ **cờ sạch vĩnh viễn trên thay đổi chưa ai implement**.
+>
+> Đây là G1 đúng nghĩa — cờ **im lặng** — chỉ khác là lần này có thêm một lệnh tự động đóng dấu lên nó.
+
+> **Vì sao hàng "mơ hồ" lên ĐẦU bảng.** Nó là điều kiện **cấp row**, không phải cấp UC: một row mơ hồ làm mọi phán đoán per-UC trong khoảng đó vô giá trị. Xét nó sau các hàng kia thì một UC có thể được xếp ⓘ **trước khi** ta biết là không suy đoán được gì — và ⓘ là hạng mở cửa cho `--realign`.
+
+> **Hàng "mơ hồ" 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õ scope (mơ hồ) → khuyến nghị F (gen lại toàn bộ)"*.
+>
+> ⚠️ **Nhưng lưới an toàn KHÔNG phải cái cớ để producer ghi bừa.** Nó đúng khi **thiếu** thông tin; nó sai khi producer **có** thông tin mà không ghi. Đó là G52: `/review-context --fix` từng ghi cứng `Auto-fix: applied {N} findings` — 0 scope — trong khi findings YAML của nó có `uc_id` bắt buộc cho từng finding. Một sửa từ trong UC5 làm **cả 8 UC** ăn 🟠. `self-check` R12 giờ fail build nếu producer nào không nhắc `{changelog_scope}`.
 
 > **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ộ)"*.
 >
@@ -622,13 +525,18 @@ Skip cột nào chưa có revision đã lưu (`—`), hoặc cả UC chưa có t
 
 *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:
+Đọc **§10 UC Coverage** và **Changelog** của tech-doc. Mỗi row Changelog mang một `{changelog_scope}` cùng contract với PRD (`changelog_row_contract`); producer là `/generate-tech-docs` Bước 1b, đơn vị "global" ở đây tên là `doc-global` thay cho `PRD-global`.
+
+Dựng `affected_ucs` **theo đúng ba bước của Step 4**, kể cả bước 2 (`BR/AC → UC sở hữu`) — tech-doc cũng nêu §/SC/BR trong mô tả, và một mệnh đề nêu `§5.9` mà bỏ UC thì UC đó rơi vào ⓘ y như ca BR8 ở Step 4. Rồi phân loại *(first-match-wins, cùng thứ tự)*:
 
 | Đ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) |
+| **Bất kỳ** row nào trong khoảng **mơ hồ** (không nêu được đơn vị sở hữu, hoặc bước 2 không phân giải được) | 🟠 cho **MỌI** UC (lưới an toàn) |
+| UC này **có** trong `affected_ucs` | `TECHDOC_DRIFT` / `FE_TECHDOC_DRIFT` 🟠 |
+| UC này có trong `affected_ucs` **CHỈ** qua mệnh đề mang hậu tố `[no-behavior]` | `TECHDOC_STALE_REF` ⓘ |
+| UC này **không** có trong `affected_ucs`, mọi row nêu rõ scope | `TECHDOC_STALE_REF` ⓘ — dùng `--realign-techdoc-revision` |
+
+> **`doc-global` là đường ra bình thường cho tech-doc, không phải ngoại lệ.** Sửa §11 Cross-cutting hay §2 kiến trúc chung thì không mệnh đề nào nêu UC ⇒ `affected_ucs` rỗng ⇒ mọi UC ở lại ⓘ. Nên `/generate-tech-docs` **không cần** dùng `[no-behavior]`; marker đó dành cho producer biết chính xác `check_id` của từng fix (`/review-context --fix`). Consumer vẫn phải **hiểu** marker vì cùng một hàng bảng phục vụ cả hai artifact.
 
 ### Step 5e — Realign mode *(chỉ chạy khi có flag)*
 
@@ -744,6 +652,22 @@ Với mỗi file `.tsv` đã xử lý: ghi `spec_ver`, `status`, `last_updated`
 Và **đồng bộ `prd_status` ← `| **Status** |`** của PRD tương ứng (`{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md`) — đối xứng với `uc_status`: PRD Metadata là nguồn-sự-thật về duyệt PRD. Không có bước này thì `prd_status` là **write-once** (chỉ `/generate-bdd` ghi một lần) và sẽ giữ `approved` vĩnh viễn sau khi `/refine-prd` hay `/review-context --fix` reset PRD về `draft`. *(Step 4 đã đọc file PRD này rồi — không phát sinh I/O.)*
 **Đừ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 6b — Ghi mốc `spec_baseline` cho lần audit sau
+
+*Đây là **nửa GHI** của check ở Step 3.9. Thiếu nó thì cờ `PRD_UNTRACKED_EDIT` **không bao giờ bật** — và mọi rule khác vẫn ✅, vì R6 chỉ canh "giá trị enum có xuất hiện" và R7 chỉ canh "cờ có counter". `self-check` R13 canh đúng nửa này.*
+
+Với **mỗi** file PRD trong phạm vi lần chạy này, ghi một entry vào khối `spec_baseline` của `trace-report.json` (Step 8):
+
+| Key | Giá trị |
+|---|---|
+| `prd_path` | path tương đối tới file PRD trong specs repo |
+| `sha_at_audit` | `git -C {specs repo} rev-parse HEAD` — commit tại thời điểm audit |
+| `version_at_audit` | `\| **Version** \|` hiện tại của PRD |
+
+Không phải git repo / `git` không khả dụng → ghi `sha_at_audit: null` và **vẫn ghi** `version_at_audit` (lần sau Step 3.9 sẽ báo đang mù, không im lặng).
+
+> **Ghi mốc là thao tác cuối, sau khi đã phán xong.** Ghi trước thì một lần chạy bị ngắt giữa đường sẽ để lại mốc mới mà chưa phán gì — và lần sau so với mốc đó thì thay đổi trong khoảng đó **biến mất khỏi tầm quan sát vĩnh viễn**.
+
 ### Step 7 — Tính aggregate cho dashboard
 
 ```
@@ -768,6 +692,9 @@ 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_untracked_edit_count = số file PRD có nội dung đổi kể từ `sha_at_audit` mà `Version` KHÔNG đổi
+                   (Step 3.9). 🔴 — có người sửa ngoài đường chính thức, nên MỌI phán đoán version
+                   của Step 4/5 trên file đó đang dựa vào một nhãn không còn đúng.
 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
@@ -782,10 +709,28 @@ by_service       = map {service → {total_scs, coded_scs, tested_scs, drift_cou
                    # 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)
+service_unrouted_count = số row có `service` ∈ (unrouted, unresolved) SAU khi đã phân giải lại ở
+                   Step 2c. 🟠 KHÔNG chặn PR — "chưa ai quyết repo" là trạng thái hợp lệ ở feature
+                   đầu tiên của một domain mới, không phải code hỏng. Nhưng phải NHÌN THẤY ĐƯỢC:
+                   không có counter thì `unrouted` đọng lại vĩnh viễn và `by_service` có một ô rác
+                   mà không ai để ý — đúng bệnh `TBD` (G51).
 # 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.
@@ -829,7 +774,11 @@ Schema:
 ```json
 {
   "generated_at": "<ISO-8601 timestamp>",
-  "domain": "<domain argument, or 'all' if no filter>",
+  "scope": {
+    "kind": "all | domain | prd | uc",
+    "value": "<giá trị scope, hoặc 'all'>"
+  },
+  "domain": "<domain trong scope, hoặc 'all'>",
   "summary": {
     "total_prds": 0,
     "approved_prds": 0,
@@ -848,6 +797,7 @@ Schema:
     "fe_integrated": 0,
     "orphaned_count": 0,
     "trace_orphan_count": 0,
+    "prd_untracked_edit_count": 0,
     "prd_drift_count": 0,
     "prd_stale_ref_count": 0,
     "bdd_drift_count": 0,
@@ -861,6 +811,7 @@ Schema:
     "seam_pending_count": 0,
     "stub_unresolved_count": 0,
     "stub_pending_count": 0,
+    "service_unrouted_count": 0,
     "dev_selftest_passing": 0,
     "dev_selftest_failing": 0,
     "dev_selftest_not_run": 0,
@@ -875,6 +826,11 @@ Schema:
       "<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": [
@@ -894,6 +850,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>",
@@ -921,7 +878,24 @@ Schema:
       ]
     }
   ],
+  "spec_baseline": [
+    {
+      "prd_path": "<specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md>",
+      "sha_at_audit": "<git rev-parse HEAD của specs repo, hoặc null nếu không phải git repo>",
+      "version_at_audit": "<Version của PRD tại thời điểm audit>"
+    }
+  ],
   "issues": {
+    "prd_untracked_edit": [
+      {
+        "prd_path": "<specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md>",
+        "version": "<Version hiện tại — KHÔNG đổi kể từ lần audit>",
+        "sha_at_audit": "<commit lần audit trước>",
+        "evidence": "git diff | git status | cả hai",
+        "affected_ucs": ["<mọi UC của PRD này — không suy đoán được ai bị đụng>"],
+        "fix": "bump Version + ghi row changelog nêu UC bị ảnh hưởng (đó là việc /amend-prd làm hộ). KHÔNG có --accept-edit: dán nhãn lên thay đổi chưa ai xem là đúng cái rào của --realign tồn tại để chặn."
+      }
+    ],
     "drift": [
       {
         "sc_id": "<SC-ID>",
@@ -1060,6 +1034,16 @@ Schema:
         "fix": "Trỏ binding của <consumer_uc> sang <RealClass> (xoá/thay stub), build lại"
       }
     ],
+    "service_unrouted": [
+      {
+        "sc_id": "<SC-ID>",
+        "platform": "web | app | system",
+        "domain": "<domain của PRD>",
+        "value": "unrouted | unresolved",
+        "reason": "<lý do context-loader đã ghi — vd: domain chưa có entry trong services:>",
+        "fix": "thêm mapping cho domain <domain> vào services: của .agent/project-context.yaml, rồi chạy lại /validate-traces (nó tự nâng unrouted → path). KHÔNG cần sinh lại BDD."
+      }
+    ],
     "stub_unresolved": [
       {
         "artifact": "<ClassName#method>",
@@ -1075,6 +1059,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
@@ -1084,7 +1073,11 @@ Schema:
   Row `ORPHANED` xuất ra JSON là: `"status": "DRIFT"` + `"orphaned": true`. Panel chưa hỗ trợ vẫn hiện nó như `DRIFT` — đủ đúng về nghĩa ("code không khớp spec, cần xử lý") và **không im lặng**; panel có đọc `orphaned` thì hiện nhãn riêng. Chi tiết đầy đủ luôn có ở `orphaned[]` và ở report terminal.
   **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`
+- Luôn ghi vào `{paths.trace_dir}/trace-report.json` bất kể phạm vi — nếu có scope, chỉ gồm các PRD/UC đó trong `prds[]`, và ghi **cả hai** field:
+  - **`scope`** = `{kind, value}` từ Step 0-A. Đây là field `gate-trace` dùng để quyết chặn — xem dưới.
+  - **`domain`** = domain trong scope (`--domain` → chính nó · `--prd`/`--uc` → domain phân giải được · không scope → `all`). Giữ cho **tương thích ngược** với `gate-trace` bản cũ.
+
+  > ⚠️ **Biên bản có scope KHÔNG BAO GIỜ được coi là biên bản đầy đủ.** `gate-trace` G2 fail nếu `scope.kind !== "all"`, **không ngoại lệ** — nó không nhìn xem trên đĩa có bao nhiêu domain. Vì sao tuyệt đối: bản cũ hỏi *"còn domain nào khác không"*, nên trong repo **một domain** thì `others` là **rỗng** ⇒ không fail ⇒ một biên bản hẹp-theo-PRD được nhận là *"toàn bộ"*. Đó đúng là *"cấp giấy xanh cho thứ chưa ai xem"* mà chú thích của chính gate cảnh báo. Thêm cờ scope mà không siết G2 là biến cổng thành **sân khấu** — đúng cái G39 dựng lên để chống.
 - **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.
@@ -1150,11 +1143,12 @@ mỗi scenario row mang service sở hữu ở **cột `service`** (cột 23, do
 
 **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á.
 
-**Bốn ràng buộc — đây là phần dễ làm sai:**
+**Năm ràng buộc — đây là phần dễ làm sai:**
 
 | 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ờ 🔴. |
@@ -1163,109 +1157,8 @@ Ghi thất bại (không có quyền, đĩa đầy) → **cảnh báo mềm mộ
 
 ## Output
 
-# Report Footer — Định dạng output chuẩn cho mọi lệnh
-
-Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
-
-## Status Badge
-
-Chọn một theo kết quả:
-- `✅ Complete` — mọi bước thành công, không có vấn đề
-- `❌ Failed` — lệnh không hoàn thành được do lỗi chặn
-- `⚠️ Warnings` — hoàn thành nhưng có vấn đề không chặn, nên review lại
-
-## Output Artifacts
-
-Liệt kê mọi file được tạo hoặc sửa bởi lệnh này:
-```
-Output Artifacts:
-  {created|updated} {file-path} ({mô tả ngắn})
-  {created|updated} {file-path} ({mô tả ngắn})
-```
-
-Nếu không ghi file nào (vd: lệnh review hoặc phân tích) → ghi `Output Artifacts: none (read-only)`.
-
-## Pipeline Position
-
-In một sơ đồ pipeline một dòng, đánh dấu phase của lệnh HIỆN TẠI bằng `◀ bạn ở đây`,
-để người dùng luôn thấy lệnh này nằm ở đâu trong luồng end-to-end:
-
-```
-Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-```
-
-Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **phase của nó** trong sơ đồ trên:
-
-| Phase | Commands |
-|-------|----------|
-| Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/extend-prd` · `/refine-prd` · `/review-context` (PRD) |
-| Design Spec | `/generate-design-spec` |
-| BDD | `/generate-bdd` · `/review-context` (BDD) |
-| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
-| Code | `/generate-code` · `/review-code` |
-| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
-| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
-| Trace Audit | `/validate-traces` |
-
-Với **lệnh review**, thêm vòng review 3 bước và đánh dấu bước hiện tại, vd:
-`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
-
-**Lệnh xuyên suốt** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
-`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) nằm ngoài pipeline tuyến tính —
-**bỏ hẳn dòng Pipeline** cho các lệnh này (đừng cố nhét chúng vào sơ đồ).
-
-## Gợi ý lệnh tiếp theo
-
-Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
-
-| Lệnh hiện tại           | Gợi ý lệnh tiếp theo                          |
-|-------------------------|-----------------------------------------------|
-| /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
-| /define-product         | `/generate-prd {product-definition-file}`     |
-| /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
-| /extend-prd             | `/refine-prd {prd-file}` (soi phần vừa thêm) rồi `/review-context {prd-file}` → PO duyệt → `/generate-bdd` **chỉ cho UC MỚI**; UC cũ dùng `/validate-traces --realign-prd-version {UC-ID}` |
-| /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
-| /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
-| /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
-| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
-| /qc-analyze             | `/qc-plan {UC-ID}` (xử lý các gap blocker 🔴 trước) |
-| /qc-plan                | `/qc-design-test {UC-ID}`                     |
-| /qc-design-test         | `/qc-review {UC-ID}` (review test-case)       |
-| /qc-review (test-case)  | `/qc-run-test {UC-ID}` nếu APPROVED; sửa TC nếu NEEDS_FIX |
-| /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
-| /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
-| /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
-| /map-testids            | `/qc-design-test {UC-ID}` (QC dựng Page Object từ contract §4.5.6 vừa ghi) |
-| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
-| /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
-| /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/dev-gen-test {UC-ID}` |
-| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
-| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
-| /dev-run-test (failing)    | `/fix-bug {ticket-id}` hoặc `/debug {error}`    |
-| /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
-| /dev-smoke-test             | Tạo PR và link tới ticket                  |
-| /validate-traces        | **Cờ 🔴 trước (chặn PR):** SEAM_UNWIRED → nối binding sang class thật, xoá/thay stub · STUB_UNRESOLVED → `/generate-code {owner_uc}` (lấp logic tại chỗ + xoá hàm song song) · ORPHANED/TRACE_ORPHAN → quyết định thủ công (xoá code+test, đưa scenario trở lại `.feature`, hoặc sửa `sc_id` của tag). **Rồi:** DRIFT/UNTRACKED → `/generate-code {UC-ID}` · BDD_DRIFT → `/generate-code {feature-file}` · tech-doc lỗi thời vs BDD → `/generate-tech-docs` → `/review-tech-docs` · PRD drift → `/generate-bdd {prd-file}` · GAP → `/dev-gen-test {UC-ID}`. **Chỉ tạo PR khi mọi cờ 🔴 = 0** |
-| /fix-bug                | `/dev-run-test {UC-ID}` (dev_selftest vừa reset về not_run) → tạo PR; nếu fix một `{BUG-ID}` → QC chạy `/qc-run-test {UC-ID}` để verify + đóng bug |
-| /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
-| /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | **Case A** (thiếu scenario cho AC có sẵn) → báo PO/Dev review trong `feedback/bdd-proposals/`; `/generate-bdd` tự chèn khi `Status: accepted`. **Case B** (requirement mới) → `feedback/prd-change-requests/` — PO phải đưa vào PRD trước, KHÔNG tự vào BDD được; `/validate-traces` nhắc lại kèm số ngày chờ chừng nào `Status: Open` |
-| /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
-| /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
-| /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |
-
-Định dạng footer như sau:
-```
----
-Status   : {badge}
-{khối Output Artifacts}
-Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-           (lệnh review) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
-Next     : {lệnh gợi ý kèm ví dụ tham số}
-```
-*(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
-
+**Đọ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}
@@ -1349,6 +1242,20 @@ 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_UNTRACKED_EDIT — nội dung PRD đổi mà nhãn Version KHÔNG đổi ({n} file):
+  specs/payment/create-invoice/PAY01-create-invoice.md   Version 1.3 (không đổi từ lần audit)
+    Bằng chứng : git status — sửa CHƯA commit
+    Mốc cũ     : sha a1b2c3d · Version 1.3
+    ⚠️  MỌI phán đoán version bên dưới cho PRD này đang dựa vào một nhãn không còn đúng.
+        Không suy đoán được UC nào bị đụng → phải coi cả {n} UC của nó là chưa rõ.
+    Sửa: bump Version + ghi một row changelog NÊU UC bị ảnh hưởng.
+         Đó đúng là việc /amend-prd làm hộ (kèm kiểm va chạm + guard sau-ghi).
+         Không có --accept-edit: dán nhãn lên thay đổi chưa ai xem là đúng cái rào của
+         --realign tồn tại để chặn.
+
+  (hoặc: ⚠️ Chưa kiểm được sửa-ngoài-đường cho {n} PRD ({lý do}) — điểm mù G54 đang MỞ)
+  (hoặc: ⓘ spec_baseline: lần đầu ghi mốc — check có hiệu lực từ lần chạy sau)
+
 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:
@@ -1384,6 +1291,14 @@ 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 service_unrouted_count > 0 — else bỏ cả khối}
+Routing chưa chốt ({service_unrouted_count} scenario) — 🟠 KHÔNG chặn PR:
+  🟠 SERVICE_UNROUTED — {sc_id} ({platform}), domain "{domain}": {reason}
+       → thêm mapping cho domain "{domain}" vào `services:` của .agent/project-context.yaml,
+         rồi chạy lại /validate-traces — nó tự nâng unrouted → path. KHÔNG cần sinh lại BDD.
+   BDD của các scenario này KHÔNG sai. Đây là bước cấu hình của architect, và nó chỉ CHẶN
+   ở /generate-code (lệnh đó buộc phải biết ghi file vào repo nào).
+
 {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