@educa-corp/sdd-framework 0.4.2 → 0.6.0

package/commands/review-tech-docs.tmpl

@@ -4,6 +4,9 @@
 **Dùng `--resume` để áp dụng các finding được chấp nhận.**
 
 ## Gate
+
+*Checkpoint: **không chặn** — read-only (ghi findings vào .agent/review/). Gate Bước 3 bỏ qua CHECKPOINT (Bước 3a).*
+
 {{include:steps/gate.md}}
 
 *Lưu ý: Với lệnh này, target ở Bước 1 là **file tech-design gộp của PRD** `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{TICKET-ID}-tech-design.md` — MỘT doc full-stack phủ mọi UC của PRD (không còn per-UC / per-platform). Review chạy trên cả doc; findings gom theo từng UC (đọc §10 UC Coverage để biết finding thuộc UC nào).

package/commands/setup-ai-first.md

@@ -22,35 +22,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,23 +76,84 @@ 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:
+*Bỏ qua nếu `_agent_mode: true`.*
+
+### 3a — Lệnh này có phải chặn không?
+
+| 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ờ** |
+
+`--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"`.
+
+> **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.)*
+
+> **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.
+
+### 3b — In gì
+
+**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`.
+
+**Mọi thứ sạch** — recap báo `Status: FULL`, không cờ nào bật → in đúng hai dòng:
 
 ```
-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}
+CHECKPOINT — Target: {resolved file path}
+Tiếp tục? (Y/N)
+```
 
+**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:
+
+```
+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)
 ```
 
-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ì.
+### 3c — Cờ nào bật, cờ nào KHÔNG
+
+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:
+
+| 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 | ⚠️ |
+
+**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.
+
+> **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
+
+- "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).
 
 
 *Lưu ý: Với lệnh này — **bỏ qua Gate Step 1, 2, và 3** (chưa có file input và chưa có project context). Chỉ chạy Step 0-B (model check). Project root là **thư mục làm việc hiện tại**. Đi thẳng tới Precondition Check bên dưới.*
@@ -207,6 +264,34 @@ specs/{domain}/{prd-slug}/
 | **2 — Umbrella** | Chỉ `.trace/` + `.agent/review/` (ở umbrella root) | Mọi thứ khác — **toàn bộ spec sống trong spec submodule (`spec_source`)** dưới `specs/{domain}/{prd-slug}/`; service submodule chỉ chứa **code + `.trace/`** |
 | **3 — PO Spec repo** | `specs/product-definition/`, `specs/domain-knowledge/`, **`feedback/`**, `.agent/review/` (folder `specs/{domain}/{prd-slug}/` theo feature tạo on demand) | `.trace/` (theo service, sống cạnh code trong mỗi service submodule) |
 
+### Step 1b — Luật merge cho sổ trace *(mọi project_type có tạo `.trace/`)*
+
+Ngay khi tạo `.trace/`, tạo luôn `.trace/.gitattributes`:
+
+```gitattributes
+# Sổ trace — dữ liệu KHÔNG regenerate được. Hai luật, hai lý do khác nhau:
+#
+# merge=union — giữ row của CẢ HAI nhánh thay vì bắt người chọn một bên. Trùng sc_id sau
+#   union là ca ĐÚNG VÀ ĐƯỢC MONG ĐỢI: `--lint-trace` T4 bắt nó, rồi /validate-traces
+#   reconcile về một row. Mất row thì KHÔNG có gì bắt được. Đánh đổi có chủ ý — đừng "dọn".
+#   (union là driver built-in của git: không ai cần chạy git config gì thêm.)
+#
+# text eol=lf — BẮT BUỘC đi kèm union. Thiếu nó: một máy ghi CRLF → git thấy MỌI dòng đã
+#   đổi → union giữ cả hai bản → NHÂN ĐÔI CẢ FILE, gồm cả dòng header.
+#
+# KHÔNG thêm *.json — trace-report.json nằm cùng thư mục và union trên JSON tạo ra JSON
+#   không hợp lệ. Nó sinh lại được: conflict thì chạy lại /validate-traces.
+*.tsv    text eol=lf merge=union
+*.jsonl  text eol=lf merge=union
+```
+
+**Vì sao làm ở đây, ngay lúc tạo thư mục:** sổ trace phải commit và được nhiều người ghi trên
+nhiều nhánh song song. Không có luật này, lần merge song song đầu tiên sẽ conflict — và giải
+conflict bằng "take mine" là **mất row của người kia, im lặng**. Đây là ca **chắc chắn xảy ra**
+với team ≥3 người và không cần ai làm sai gì cả.
+
+*Project đã cài từ trước → `/sync` Step 4c kiểm và tạo hộ.*
+
 ## Step 2 — Tạo CLAUDE.md
 
 *Bỏ qua hoàn toàn step này nếu `project_type = 2` (Umbrella) — umbrella không có một tech stack đơn.*
@@ -375,6 +460,50 @@ Hoặc: VS Code → `Ctrl+Shift+P` → **"Extensions: Install from Marketplace"*
 - 📋 **Review Board** — UI trực quan để review findings từ `/refine-prd`, `/review-context`, `/review-tech-docs`
 - 📊 **Living Documentation** — dashboard traceability dựa trên `.trace/*.tsv`
 
+## Step 6b — Cổng chặn bằng máy (Khuyến nghị mạnh)
+
+*Skip nếu `project_type = 3` (PO Spec repo) — không có code thì không có PR cần chặn.*
+
+Framework phát hiện được một lớp lỗi mà **build xanh + test từng-UC xanh KHÔNG thấy**: luồng
+ghép chạy vào hàm rỗng (`SEAM_UNWIRED`, `STUB_UNRESOLVED`), hoặc code trỏ vào scenario đã bị
+xoá (`ORPHANED`, `TRACE_ORPHAN`). Nhưng nếu việc phát hiện đó phụ thuộc vào **có người tự
+nguyện chạy `/validate-traces` rồi đọc report bằng mắt**, thì sau sprint thứ ba không ai làm.
+
+Hai file mẫu đã có sẵn. Hỏi user muốn cài cái nào:
+
+```
+Cài cổng chặn bằng máy? (khuyến nghị cả hai)
+  1. pre-push hook  — chặn push khi sổ trace hỏng cấu trúc. Rẻ, 2 giây, offline được.
+                      Bắt được marker conflict git trước khi nó vào nhánh chung.
+  2. CI workflow    — chặn PR khi có cờ 🔴. Cần GitHub Actions.
+  3. Cả hai         (khuyến nghị)
+  4. Bỏ qua, cài sau
+```
+
+**Chọn 1 hoặc 3** — copy hook rồi cấp quyền chạy:
+```bash
+cp .agent/templates/hooks/pre-push .git/hooks/pre-push && chmod +x .git/hooks/pre-push
+```
+*Nếu `trace_dir` của project không phải `.trace` (vd `../.trace` hay `{spec_source}/.trace`) →
+mở file vừa copy và sửa biến `TRACE_DIR` ở đầu file cho khớp.*
+
+**Chọn 2 hoặc 3** — copy workflow:
+```bash
+mkdir -p .github/workflows && cp .agent/templates/ci/trace-gate.yml .github/workflows/
+```
+*Rồi mở nó ra: sửa `src/**` ở job `require-fresh-audit` cho khớp layout project, và bỏ comment
+`submodules: recursive` nếu spec/trace nằm trong submodule.*
+
+> **Phải COPY RA khỏi `.agent/`** — `.agent/` bị ghi đè mỗi lần `/update-framework`, và
+> `.git/hooks/` thì git không chạy từ chỗ khác. Copy ra rồi thì chúng là file của project.
+
+Kiểm ngay sau khi cài (chưa có sổ trace thì cả hai thoát sạch, không phải lỗi):
+```bash
+npx @educa-corp/sdd-framework --lint-trace
+```
+
+Chi tiết + giới hạn của cổng → `docs/03-guides/architect.md` §Cắm vào CI.
+
 ## Step 7 — Verify
 
 Checklist tuỳ theo `project_type`:
@@ -410,108 +539,8 @@ Checklist tuỳ theo `project_type`:
 
 ## Output
 
-# Report Footer — Định dạng output chuẩn cho mọi lệnh
-
-Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
-
-## Status Badge
-
-Chọn một theo kết quả:
-- `✅ Complete` — mọi bước thành công, không có vấn đề
-- `❌ Failed` — lệnh không hoàn thành được do lỗi chặn
-- `⚠️ Warnings` — hoàn thành nhưng có vấn đề không chặn, nên review lại
-
-## Output Artifacts
-
-Liệt kê mọi file được tạo hoặc sửa bởi lệnh này:
-```
-Output Artifacts:
-  {created|updated} {file-path} ({mô tả ngắn})
-  {created|updated} {file-path} ({mô tả ngắn})
-```
-
-Nếu không ghi file nào (vd: lệnh review hoặc phân tích) → ghi `Output Artifacts: none (read-only)`.
-
-## Pipeline Position
-
-In một sơ đồ pipeline một dòng, đánh dấu phase của lệnh HIỆN TẠI bằng `◀ bạn ở đây`,
-để người dùng luôn thấy lệnh này nằm ở đâu trong luồng end-to-end:
-
-```
-Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-```
-
-Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **phase của nó** trong sơ đồ trên:
-
-| Phase | Commands |
-|-------|----------|
-| Discovery | `/define-product` |
-| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
-| Design Spec | `/generate-design-spec` |
-| BDD | `/generate-bdd` · `/review-context` (BDD) |
-| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
-| Code | `/generate-code` · `/review-code` |
-| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
-| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
-| Trace Audit | `/validate-traces` |
-
-Với **lệnh review**, thêm vòng review 3 bước và đánh dấu bước hiện tại, vd:
-`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
-
-**Lệnh xuyên suốt** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
-`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) nằm ngoài pipeline tuyến tính —
-**bỏ hẳn dòng Pipeline** cho các lệnh này (đừng cố nhét chúng vào sơ đồ).
-
-## Gợi ý lệnh tiếp theo
-
-Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
-
-| Lệnh hiện tại           | Gợi ý lệnh tiếp theo                          |
-|-------------------------|-----------------------------------------------|
-| /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
-| /define-product         | `/generate-prd {product-definition-file}`     |
-| /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
-| /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
-| /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
-| /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
-| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
-| /qc-analyze             | `/qc-plan {UC-ID}` (xử lý các gap blocker 🔴 trước) |
-| /qc-plan                | `/qc-design-test {UC-ID}`                     |
-| /qc-design-test         | `/qc-review {UC-ID}` (review test-case)       |
-| /qc-review (test-case)  | `/qc-run-test {UC-ID}` nếu APPROVED; sửa TC nếu NEEDS_FIX |
-| /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
-| /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
-| /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
-| /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.)*
-
+**Đọ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.
 
 ```
 /setup-ai-first Hoàn tất ✅

package/commands/setup-ai-first.tmpl

@@ -113,6 +113,34 @@ specs/{domain}/{prd-slug}/
 | **2 — Umbrella** | Chỉ `.trace/` + `.agent/review/` (ở umbrella root) | Mọi thứ khác — **toàn bộ spec sống trong spec submodule (`spec_source`)** dưới `specs/{domain}/{prd-slug}/`; service submodule chỉ chứa **code + `.trace/`** |
 | **3 — PO Spec repo** | `specs/product-definition/`, `specs/domain-knowledge/`, **`feedback/`**, `.agent/review/` (folder `specs/{domain}/{prd-slug}/` theo feature tạo on demand) | `.trace/` (theo service, sống cạnh code trong mỗi service submodule) |
 
+### Step 1b — Luật merge cho sổ trace *(mọi project_type có tạo `.trace/`)*
+
+Ngay khi tạo `.trace/`, tạo luôn `.trace/.gitattributes`:
+
+```gitattributes
+# Sổ trace — dữ liệu KHÔNG regenerate được. Hai luật, hai lý do khác nhau:
+#
+# merge=union — giữ row của CẢ HAI nhánh thay vì bắt người chọn một bên. Trùng sc_id sau
+#   union là ca ĐÚNG VÀ ĐƯỢC MONG ĐỢI: `--lint-trace` T4 bắt nó, rồi /validate-traces
+#   reconcile về một row. Mất row thì KHÔNG có gì bắt được. Đánh đổi có chủ ý — đừng "dọn".
+#   (union là driver built-in của git: không ai cần chạy git config gì thêm.)
+#
+# text eol=lf — BẮT BUỘC đi kèm union. Thiếu nó: một máy ghi CRLF → git thấy MỌI dòng đã
+#   đổi → union giữ cả hai bản → NHÂN ĐÔI CẢ FILE, gồm cả dòng header.
+#
+# KHÔNG thêm *.json — trace-report.json nằm cùng thư mục và union trên JSON tạo ra JSON
+#   không hợp lệ. Nó sinh lại được: conflict thì chạy lại /validate-traces.
+*.tsv    text eol=lf merge=union
+*.jsonl  text eol=lf merge=union
+```
+
+**Vì sao làm ở đây, ngay lúc tạo thư mục:** sổ trace phải commit và được nhiều người ghi trên
+nhiều nhánh song song. Không có luật này, lần merge song song đầu tiên sẽ conflict — và giải
+conflict bằng "take mine" là **mất row của người kia, im lặng**. Đây là ca **chắc chắn xảy ra**
+với team ≥3 người và không cần ai làm sai gì cả.
+
+*Project đã cài từ trước → `/sync` Step 4c kiểm và tạo hộ.*
+
 ## Step 2 — Tạo CLAUDE.md
 
 *Bỏ qua hoàn toàn step này nếu `project_type = 2` (Umbrella) — umbrella không có một tech stack đơn.*
@@ -281,6 +309,50 @@ Hoặc: VS Code → `Ctrl+Shift+P` → **"Extensions: Install from Marketplace"*
 - 📋 **Review Board** — UI trực quan để review findings từ `/refine-prd`, `/review-context`, `/review-tech-docs`
 - 📊 **Living Documentation** — dashboard traceability dựa trên `.trace/*.tsv`
 
+## Step 6b — Cổng chặn bằng máy (Khuyến nghị mạnh)
+
+*Skip nếu `project_type = 3` (PO Spec repo) — không có code thì không có PR cần chặn.*
+
+Framework phát hiện được một lớp lỗi mà **build xanh + test từng-UC xanh KHÔNG thấy**: luồng
+ghép chạy vào hàm rỗng (`SEAM_UNWIRED`, `STUB_UNRESOLVED`), hoặc code trỏ vào scenario đã bị
+xoá (`ORPHANED`, `TRACE_ORPHAN`). Nhưng nếu việc phát hiện đó phụ thuộc vào **có người tự
+nguyện chạy `/validate-traces` rồi đọc report bằng mắt**, thì sau sprint thứ ba không ai làm.
+
+Hai file mẫu đã có sẵn. Hỏi user muốn cài cái nào:
+
+```
+Cài cổng chặn bằng máy? (khuyến nghị cả hai)
+  1. pre-push hook  — chặn push khi sổ trace hỏng cấu trúc. Rẻ, 2 giây, offline được.
+                      Bắt được marker conflict git trước khi nó vào nhánh chung.
+  2. CI workflow    — chặn PR khi có cờ 🔴. Cần GitHub Actions.
+  3. Cả hai         (khuyến nghị)
+  4. Bỏ qua, cài sau
+```
+
+**Chọn 1 hoặc 3** — copy hook rồi cấp quyền chạy:
+```bash
+cp .agent/templates/hooks/pre-push .git/hooks/pre-push && chmod +x .git/hooks/pre-push
+```
+*Nếu `trace_dir` của project không phải `.trace` (vd `../.trace` hay `{spec_source}/.trace`) →
+mở file vừa copy và sửa biến `TRACE_DIR` ở đầu file cho khớp.*
+
+**Chọn 2 hoặc 3** — copy workflow:
+```bash
+mkdir -p .github/workflows && cp .agent/templates/ci/trace-gate.yml .github/workflows/
+```
+*Rồi mở nó ra: sửa `src/**` ở job `require-fresh-audit` cho khớp layout project, và bỏ comment
+`submodules: recursive` nếu spec/trace nằm trong submodule.*
+
+> **Phải COPY RA khỏi `.agent/`** — `.agent/` bị ghi đè mỗi lần `/update-framework`, và
+> `.git/hooks/` thì git không chạy từ chỗ khác. Copy ra rồi thì chúng là file của project.
+
+Kiểm ngay sau khi cài (chưa có sổ trace thì cả hai thoát sạch, không phải lỗi):
+```bash
+npx @educa-corp/sdd-framework --lint-trace
+```
+
+Chi tiết + giới hạn của cổng → `docs/03-guides/architect.md` §Cắm vào CI.
+
 ## Step 7 — Verify
 
 Checklist tuỳ theo `project_type`: