@educa-corp/sdd-framework 0.5.0 → 0.7.0

package/core/steps/gate.md

@@ -17,35 +17,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
 
@@ -75,20 +71,81 @@ 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).

package/core/steps/report-footer.md

@@ -2,6 +2,29 @@
 
 Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
 
+## Model *(bắt buộc, một dòng)*
+
+In model mà **bạn — agent vừa chạy lệnh này — thực sự đang dùng** (ghi nhận ở Gate Bước 0-B):
+
+```
+Model: {tên model đang chạy}
+```
+
+Nếu bạn biết mình **không** phải một model Opus, thêm cảnh báo ngay trên cùng dòng:
+
+```
+Model: {tên model}   ⚠️ lệnh này khuyến nghị Opus — model nhỏ hơn dễ bỏ sót edge case,
+                        phân tích spec thiếu sót, vi phạm kiến trúc. Cân nhắc chạy lại
+                        với /model → Opus trước khi dùng kết quả này.
+```
+
+> **Vì sao ở ĐÂY chứ không phải một prompt ở đầu lệnh (GAPS-v3 G41):** trước đây Gate hiện
+> `⚙️ MODEL CHECK` rồi chờ `Y/S/N`. Nó **hỏi người dùng thứ agent đã biết**, câu trả lời
+> **không kiểm chứng được**, và **cả `Y` lẫn `S` đều đi tiếp** — tức không chặn được ai, mà
+> tốn một lần chặn ở mọi lệnh (20 lệnh cho một feature). Khai báo ở footer đúng nguồn hơn
+> (agent tự khai, không phải người tự khai) và đúng chỗ hơn: nó nằm **cạnh kết quả** để
+> người đọc cân nhắc có nên tin, thay vì nằm trước khi có kết quả để bấm cho xong.
+
 ## Status Badge
 
 Chọn một theo kết quả:

package/core/templates/README.md

@@ -17,7 +17,28 @@ commands/generate-bdd.md
 
 Không lệnh nào đọc một path template lúc chạy. `paths.feature_template` / `paths.prd_template` từng tồn tại trong `project-context.yaml` nhưng chưa bao giờ có tác dụng — đã được gỡ bỏ (xem `GAPS.md` G9).
 
-**Thêm nữa:** `.agent/` là vùng bị ghi đè. `/update-framework` chạy `npx … --init`, và `--init` copy `core/` → `.agent/` **vô điều kiện** (`bin/index.js` → `copyDirRecursive`, không có existence check, không backup). File duy nhất được giữ lại là `.agent/project-context.yaml`. Nên mọi chỉnh sửa ở `.agent/templates/` sẽ **biến mất im lặng** ở lần nâng cấp kế tiếp.
+**Thêm nữa:** `.agent/` là vùng bị ghi đè. `/update-framework` chạy `npx … --init`, và `--init` copy `core/` → `.agent/` **vô điều kiện** (`bin/index.js` → `installCore`). File duy nhất được giữ lại là `.agent/project-context.yaml`. Nên mọi chỉnh sửa ở `.agent/templates/` sẽ **biến mất** ở lần nâng cấp kế tiếp — từ v0.4.2 thì không còn im lặng: bản cũ được lưu vào `.agent/.overwritten-{version}-{date}/` và được liệt kê ra (`GAPS.md` G24). Nhưng vẫn phải áp lại bằng tay mỗi version, nên đây không phải chỗ để đặt thay đổi.
+
+---
+
+## Ngoại lệ: `ci/` và `hooks/` — template để COPY RA, không phải để build
+
+Hai thư mục này **không** giống phần còn lại của `templates/`. Chúng không được `{{include}}` vào lệnh nào, và **không** được đọc lúc chạy. Chúng là file **hoàn chỉnh, dùng ngay**, chờ một người copy ra khỏi `.agent/`:
+
+| File | Copy tới | Làm gì |
+|---|---|---|
+| `ci/trace-gate.yml` | `.github/workflows/` của project | Chặn PR khi trace có cờ 🔴 (`--gate-trace`) |
+| `hooks/pre-push` | `.git/hooks/pre-push` (rồi `chmod +x`) | Chặn push khi sổ trace hỏng cấu trúc (`--lint-trace`) |
+
+```bash
+# từ gốc project
+mkdir -p .github/workflows && cp .agent/templates/ci/trace-gate.yml .github/workflows/
+cp .agent/templates/hooks/pre-push .git/hooks/pre-push && chmod +x .git/hooks/pre-push
+```
+
+**Phải copy RA, không dùng tại chỗ** — vì đúng cái lý do cả file README này nói: `.agent/` bị ghi đè mỗi lần nâng cấp, và `.git/hooks/` thì git không bao giờ chạy từ chỗ khác. Copy ra rồi thì chúng là file của project: sửa tuỳ ý, nâng cấp framework không đụng tới.
+
+Vì sao chúng tồn tại → `GAPS-v3.md` G39: framework phát hiện được một lớp lỗi mà build xanh + test xanh không thấy, nhưng trước đó việc phát hiện phụ thuộc vào có người tự nguyện chạy một lệnh chat. Hai file này là chỗ nó chặn bằng máy.
 
 ## Muốn đổi cấu trúc artifact sinh ra thì làm gì
 
@@ -43,5 +64,7 @@ Rồi phát hành version mới; project chạy `/update-framework` để nhận
 | `product-definition.template.md` | `commands/define-product.tmpl` | product definition |
 | `platform-guide.template.md` | (tham khảo) | — |
 | `project-context.yaml` | **không** include — được copy thẳng làm file config khởi tạo | `.agent/project-context.yaml` |
+| `ci/trace-gate.yml` | **không** include — người dùng copy ra | `.github/workflows/trace-gate.yml` |
+| `hooks/pre-push` | **không** include — người dùng copy ra | `.git/hooks/pre-push` |
 
 > Lưu ý `project-context.yaml` là ngoại lệ duy nhất: nó **được** copy ra làm file thật của project, và **được bảo vệ** khỏi ghi đè khi nâng cấp (chỉ tạo nếu chưa tồn tại).

package/core/templates/ci/trace-gate.yml

@@ -0,0 +1,146 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# SDD Framework — Trace Gate (GitHub Actions)
+#
+# COPY file này vào .github/workflows/ của project. Nó KHÔNG tự chạy từ
+# .agent/templates/ — mọi thứ trong .agent/ là bản sinh ra, bị ghi đè mỗi lần
+# /update-framework.
+#
+# VÌ SAO CẦN (GAPS-v3 G39): 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 trước G39 việc phát hiện đó phụ thuộc vào có người TỰ NGUYỆN chạy
+# /validate-traces trong Claude Code rồi đọc report bằng mắt. Cái gì không chặn
+# thì sau sprint thứ ba không ai làm. Đây là chỗ nó chặn.
+#
+# GIỚI HẠN — đọc trước khi tin:
+#   Job này chứng minh "report khớp SỔ, và sổ không có cờ 🔴".
+#   Nó KHÔNG chứng minh "sổ khớp CODE" — việc đó cần quét tag trong source, đọc
+#   .feature, so version, tức cần /validate-traces (một lệnh LLM, không chạy được
+#   trong CI thường). Nên nó bắt ca phổ biến "quên chạy lại /validate-traces",
+#   nhưng KHÔNG bắt ca "sửa code mà không đụng sổ".
+#   Muốn bịt nốt: xem job `require-fresh-audit` ở cuối file.
+# ─────────────────────────────────────────────────────────────────────────────
+
+name: Trace Gate
+
+on:
+  pull_request:
+  push:
+    branches: [main, master, develop]
+
+jobs:
+  trace-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Cần lịch sử để job require-fresh-audit so được diff. Bỏ nếu không dùng job đó.
+          fetch-depth: 0
+          # Spec/trace nằm trong submodule (umbrella + spec_source)? Bỏ comment:
+          # submodules: recursive
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      # ── 1. Cấu trúc sổ ───────────────────────────────────────────────────────
+      # Sổ trace 24 cột do LLM ghi bằng tay. Một dấu tab thiếu dồn mọi ô sang trái
+      # và ô `status` nhận một ngày tháng — trước G38 không gì báo. Bước này chặn.
+      # Cũng bắt marker conflict git lọt vào sổ (T7) và sổ thiếu luật merge (T10).
+      - name: Lint sổ trace
+        run: npx -y @educa-corp/sdd-framework@latest --lint-trace
+
+      # ── 2. Cổng chặn PR ──────────────────────────────────────────────────────
+      # --gate-trace tự chạy lại lint ở tầng G1, nên bước 1 ở trên là để có log
+      # riêng dễ đọc khi đỏ. Muốn gọn thì bỏ bước 1 và chỉ giữ bước này.
+      - name: Trace gate (cờ 🔴 chặn PR)
+        run: npx -y @educa-corp/sdd-framework@latest --gate-trace
+
+      # ── 3. (tuỳ chọn) Đưa kết quả vào PR summary ─────────────────────────────
+      - name: Ghi kết quả vào job summary
+        if: always()
+        run: |
+          npx -y @educa-corp/sdd-framework@latest --gate-trace --json --warn-only \
+            > gate.json || true
+          {
+            echo '## Trace Gate'
+            echo '```json'
+            cat gate.json
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  # ───────────────────────────────────────────────────────────────────────────
+  # Ép audit phải TƯƠI khi thứ report đang KHẲNG ĐỊNH bị đổi.
+  #
+  # Bịt cái lỗ mà trace-gate không bịt được: gate chứng minh "report khớp SỔ",
+  # không chứng minh "sổ khớp CODE" — việc đó cần /validate-traces, một lệnh LLM
+  # không chạy được ở đây. Nên job này dùng một PROXY: không verify được thì ĐÒI
+  # BẰNG CHỨNG có người vừa verify.
+  #
+  # ĐO BẰNG TAG, KHÔNG BẰNG `src/**`:
+  #   Framework có luật boundary-only tagging — chỉ Controller/Handler/Middleware/
+  #   Steps mang tag @trace; Entity/Repository/DTO/Interface/Base KHÔNG. Nên câu
+  #   hỏi "PR có sửa src/ không?" chặn cả PR chỉ thêm một field vào DTO — một file
+  #   không mang lời khẳng định trace nào. Cái gì báo oan thì bị tắt, rồi mất luôn
+  #   phần thật sự cần chặn.
+  #   Câu hỏi đúng: "PR có chạm dòng nào mang tag mà report đang khẳng định không?"
+  #
+  #   sửa log trong Controller  → cho qua      (bản `src/**` cũ: chặn oan)
+  #   thêm field vào DTO        → cho qua      (bản cũ: chặn oan)
+  #   thêm method + @implements → CHẶN
+  #   lấp một @trace.stub       → CHẶN
+  #
+  # KHÔNG cần sửa gì theo layout project — tag là tag, ở đâu cũng vậy.
+  #
+  # BẢY TAG dưới đây là NGUỒN của đúng 4 cờ chặn PR. Chúng được khai trong
+  # bin/trace-schema.json → gate.audit_invalidating_tags, và self-check R10 fail
+  # build nếu file này không nhắc đủ — tag đổi tên mà đây không biết thì grep
+  # không khớp gì, job LUÔN XANH, và cổng mù trong im lặng.
+  #
+  # GIỚI HẠN ĐÃ BIẾT: đổi tên class (AuthService → AuthenticationService) không
+  # chạm dòng tag ⇒ job này bỏ lọt, dù cột implemented_by giờ trỏ vào tên không
+  # còn. Chấp nhận có chủ ý: ca đó ít gặp và KHÔNG im lặng (/validate-traces lần
+  # sau báo ngay), còn báo oan thì xảy ra mỗi ngày.
+  #   Muốn chặt hơn (bắt cả rename, giá là chặn cả việc sửa log trong Controller):
+  #   đổi bước dưới thành — lấy danh sách file đã đổi, rồi `grep -l` bảy tag đó
+  #   TRÊN NỘI DUNG FILE thay vì trên diff.
+  # ───────────────────────────────────────────────────────────────────────────
+  require-fresh-audit:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+
+      - name: Đổi thứ report khẳng định thì audit phải đổi theo
+        shell: bash
+        run: |
+          BASE="origin/${{ github.base_ref }}"
+
+          # 7 tag sinh ra 4 cờ chặn PR — khai ở bin/trace-schema.json,
+          # gate.audit_invalidating_tags (self-check R10 canh danh sách này khớp).
+          TAGS='@trace\.(implements|verifies|seam_port|seam_pending|stub|stub_owner|stub_for)'
+
+          # Chạm dòng mang tag = report có thể đã hết đúng. -U0 để chỉ lấy dòng thật đổi.
+          touched=$(git diff -U0 "$BASE"...HEAD | grep -E "^[+-].*${TAGS}" | head -5 || true)
+          audit=$(git diff --name-only "$BASE"...HEAD | grep -E 'trace-report\.json$' | head -1 || true)
+
+          if [ -n "$touched" ] && [ -z "$audit" ]; then
+            echo "::error::PR đổi tag trace nhưng không kèm trace-report.json được sinh lại."
+            echo ""
+            echo "Những dòng này đã đổi:"
+            echo "$touched" | sed 's/^/    /'
+            echo ""
+            echo "Trace gate chỉ chứng minh 'report khớp SỔ'. Tag vừa đổi mà chưa audit lại"
+            echo "thì mọi cờ 🔴 trong report nói về trạng thái TRƯỚC khi bạn sửa."
+            echo ""
+            echo "Chạy trong Claude Code:  /validate-traces"
+            echo "Rồi commit:              {trace_dir}/trace-report.json + *.tsv"
+            exit 1
+          fi
+
+          if [ -n "$touched" ]; then
+            echo "✅ Tag trace có đổi, và audit đã được sinh lại cùng PR."
+          else
+            echo "✅ PR không chạm tag nào mà report đang khẳng định — audit vẫn còn đúng."
+          fi

package/core/templates/feature.template

@@ -4,7 +4,7 @@
 # @trace.revision: 1  ← field tĩnh; version theo dõi bằng @trace.bdd_version
 # @trace.domain: <domain>
 # @trace.platform: {active_platform — web | app | system}   ← BẮT BUỘC mọi mode; phải khớp segment bdd/{platform}/ của path
-# @trace.service: {active_service — BẮT BUỘC mọi mode. "—" ở single-service/spec repo mode; "multi" nếu chưa chốt; "unresolved" nếu routing sai. Nguồn của cột TSV `service` — trace gộp không tách theo service nên đây là chỗ DUY NHẤT mang thông tin sở hữu}
+# @trace.service: {service của ĐÚNG platform file này — BẮT BUỘC mọi mode. Nguồn của cột TSV `service`; trace gộp không tách theo service nên đây là chỗ DUY NHẤT mang thông tin sở hữu ở cấp row. Bốn giá trị: {path} · "unrouted" (chưa ai quyết repo — HỢP LỆ, cờ 🟠, KHÔNG chặn) · "unresolved" (config sai cấu trúc — bug) · "—" (single-service). KHÔNG ghi "multi": file này đã có MỘT platform xác định nên service_candidates.{platform}.path đã biết — ghi path đó (G51)}
 # @trace.module: {active_module trong umbrella mode; "unknown" trong spec repo mode}
 # @trace.status: draft
 # @trace.author: AI-generated

package/core/templates/hooks/pre-push

@@ -0,0 +1,61 @@
+#!/usr/bin/env sh
+# ─────────────────────────────────────────────────────────────────────────────
+# SDD Framework — git pre-push hook
+#
+# CÀI (từ gốc project):
+#   cp .agent/templates/hooks/pre-push .git/hooks/pre-push
+#   chmod +x .git/hooks/pre-push
+#
+# Trên Windows: Git for Windows chạy hook bằng sh nên file này dùng được như vậy.
+#
+# VÌ SAO CÓ HOOK NÀY khi đã có CI (GAPS-v3 G39/G40): nó chặn ở chỗ RẺ NHẤT.
+# Cụ thể là T7 — marker conflict git (`<<<<<<< HEAD`) lọt vào sổ trace. Một khi
+# thứ đó vào nhánh chung thì mọi người kéo về đều có sổ hỏng, và sổ trace là dữ
+# liệu KHÔNG dựng lại được. Bắt trước lúc push tốn 2 giây; bắt ở CI thì đã muộn
+# một vòng, bắt bằng mắt thì thường là ba tuần sau.
+#
+# CỐ Ý CHỈ LINT, KHÔNG GATE:
+#   --lint-trace  = cấu trúc sổ. Nhanh, offline được sau lần đầu, và một lỗi ở đây
+#                   LUÔN là lỗi thật (tab lệch, marker conflict, enum sai).
+#   --gate-trace  = cờ 🔴. Cần trace-report.json còn tươi, mà giữa lúc làm việc thì
+#                   nó thường chưa tươi — đỏ liên tục ⇒ người ta gõ --no-verify ⇒
+#                   mất luôn cả phần lint. Cờ 🔴 để CI chặn.
+#
+# Bỏ qua một lần (dùng có ý thức, đừng thành phản xạ):  git push --no-verify
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Không có node thì im lặng cho qua — hook không được làm người ta không push được
+# vì lý do không liên quan tới việc họ đang làm.
+command -v node >/dev/null 2>&1 || exit 0
+
+# Không có sổ trace thì không có gì để kiểm (project chưa chạy /generate-bdd lần nào).
+# Sửa đường dẫn nếu trace_dir của project khác (vd ../.trace, hay {spec_source}/.trace).
+TRACE_DIR=".trace"
+[ -d "$TRACE_DIR" ] || exit 0
+
+echo "→ Lint sổ trace trước khi push ..."
+
+if npx -y @educa-corp/sdd-framework@latest --lint-trace --trace "$TRACE_DIR"; then
+  exit 0
+fi
+
+cat <<'MSG'
+
+──────────────────────────────────────────────────────────────────────
+🔴 PUSH BỊ CHẶN — sổ trace hỏng cấu trúc.
+
+Sổ trace là dữ liệu KHÔNG regenerate được. Đẩy một sổ hỏng lên nhánh
+chung thì mọi người kéo về đều nhận bản hỏng.
+
+Thường gặp nhất — marker conflict git chưa giải (T7):
+  1. Mở file lint vừa nêu, xoá 3 dòng <<<<<<<  =======  >>>>>>>
+  2. GIỮ CẢ HAI BÊN, đừng chọn một bên (mất row là mất vĩnh viễn)
+  3. npx @educa-corp/sdd-framework --lint-trace     # xác nhận sạch
+  4. /validate-traces trong Claude Code             # reconcile row trùng
+
+Playbook đầy đủ: docs/02-concepts/traceability.md
+Bỏ qua một lần: git push --no-verify
+──────────────────────────────────────────────────────────────────────
+
+MSG
+exit 1

package/docs/02-concepts/architecture.md

@@ -61,15 +61,70 @@ Spec-driven thành/bại phụ thuộc **~80%** vào việc context được n
 ## Template Pipeline
 
 ```
-.tmpl (source) + steps/*.md  --[node bin/build.js, {{include:...}}]-->  commands/*.md + core/
-                                     │                                        │
-                                     │  templates/*.template* cũng được inline │
-                                     ▼                                        ▼
-                        bin/self-check.js (fail build)      .agent/commands/*.md (runtime)
+.tmpl + steps/*.md ──build──► commands/*.md ──► core/* ──► .agent/    904 KB
+                                    │                        ▲
+                     bin/self-check.js (fail build)      --init cài vào đây
 ```
 
-- Cơ chế `{{include:steps/...}}` ghép phẳng → single source of truth ở `.tmpl` + `steps/`.
+**Vì sao slim (G45):** build inline `{{include:}}` vào **từng** file lệnh. Với 32 lệnh, kết quả là
+2069 KB mà chỉ 580 KB là nội dung riêng của chúng — **72% là vài step giống hệt nhau, chép 30 lần**.
+`/generate-code` từng nặng 108 KB (≈27k token đọc **trước** khi làm gì), gần một nửa không nói gì về
+việc sinh code. Cái giá thật không phải tiền: trên PRD nhiều UC nó làm tăng rủi ro **cạn context
+giữa lúc ghi sổ trace**.
+
+| Step | Xử lý trong `core/` | Vì sao |
+|---|---|---|
+| `context-loader.md` (33 K × 29) | **đọc lúc chạy** | 64% lãng phí. Bỏ sót ⇒ lệnh **dừng ngay** vì thiếu path/config — hỏng ồn ào |
+| `report-footer.md` (7 K × 32) | **đọc lúc chạy** | 16%. Bỏ sót ⇒ report kém cấu trúc, không hỏng gì |
+| `gate.md` (7 K × 30) | **giữ inline** | Chỉ 15%, nhưng là **lưới an toàn** (model check · resolve target · CHECKPOINT). Bỏ sót ⇒ lệnh **vẫn chạy** mà không còn cổng nào — hỏng **âm thầm** |
+
+Kết quả: `/generate-code` 108 KB → **69 KB**, `/refine-prd` 85 KB → **45 KB**.
+
+> **Một biến thể duy nhất.** Bản đầu của G45 phải build **hai** bản: `commands/*.md` inline đầy đủ
+> cho legacy mode (`--project` / không cờ) — vì nó copy thẳng file đó vào `.claude/commands/` mà
+> **không** cài `.agent/`, nên không có `.agent/steps/` để đọc — và bản slim cho `--init`.
+> **G50 gỡ hẳn legacy mode**, nên giờ mọi bản cài đều có `.agent/steps/` và nhánh build thứ hai
+> biến mất. Hai nhánh build gần giống nhau là nợ chờ lệch.
+
+### Tập publish — chỉ ship MỘT bản *(GAPS-v4 G59)*
+
+`npm pack` chỉ mang **`bin/` · `core/` · `scripts/` · `docs/`**.
+
+Trước G59, `files` có **10 mục**, và **7 trong 10** là bản sao của thứ đã có trong `core/` —
+`commands/` (33/33 file `.md` **byte-identical** với `core/commands/`), cộng
+`hooks/ modules/ rules/ skills/ steps/ templates/` (`diff -rq` không khác gì). Installer đọc
+**chỉ `core/`** (`installCore(coreDir, agentDir, …)`), nên bản thứ hai không bao giờ được dùng.
+
+| | Trước | Sau |
+|---|---:|---:|
+| Tarball nén | 1.2 MB | **710 kB** |
+| Giải nén | 4.5 MB | **2.3 MB** |
+| Số file | 395 | **215** |
+
+**Nhưng cái đáng sửa hơn là một phép phân biệt bị vô hiệu.** `bin/index.js` dùng
+`hasSources = exists(commands/generate-code.tmpl)` để biết *"đây là dev checkout hay bản cài từ
+npm"*, và chú thích của nó viết thẳng: *"Chỉ nói trong DEV CHECKOUT. **Consumer không cần biết bước
+này tồn tại**"*. Nhưng `commands/` được ship ⇒ `.tmpl` có mặt ⇒ phép thử **luôn đúng** ⇒ **mọi**
+người dùng `npx` thấy `"Vừa sửa commands/*.tmpl ? Chạy npm run build trước"` — một câu họ không thể
+làm gì với nó. *(Kiểm bằng cách `npm pack` rồi chạy tarball thật, không phải suy đoán.)*
+
+Bốn nhánh sau khi sửa, `hasSources` đặt tên **một lần**:
+
+| `corePrebuilt` | `hasSources` | Nghĩa | Làm gì |
+|:---:|:---:|---|---|
+| ✗ | ✓ | dev checkout, `core/` vắng/lệch | build từ nguồn |
+| ✗ | ✗ | **bản cài npm bị thiếu/hỏng** | **lỗi rõ ràng + `exit 1`** — không cố build (G43: build ghi vào npx cache / global `node_modules`, có thể read-only, và hai `--init` song song sẽ đua nhau) |
+| ✓ | ✓ | dev checkout, đã khớp version | in lời nhắc *"sửa `.tmpl` thì build lại"* |
+| ✓ | ✗ | **bản cài npm, mọi thứ đúng** | **im lặng** ← đường của consumer |
+
+Bất biến được `test/run.js` canh, viết theo **hình dạng** chứ không theo danh sách tên nên tự khớp
+với dir thêm sau này: *không mục nào trong `files` được có bản mirror dưới `core/`*.
+
+`scripts/` **phải giữ** — `bin/index.js` `require('../scripts/migrate-specs.js')` cho `--migrate-*`.
+
+- Cơ chế `{{include:steps/...}}` → single source of truth ở `.tmpl` + `steps/`.
 - **Không sửa tay** `commands/*.md` / `.agent/` — sửa `.tmpl`/`steps` rồi `node bin/build.js`. *(Quy ước + memory bảo vệ, không phải hook.)*
+- **Sửa `steps/context-loader.md` hay `report-footer.md` giờ có hiệu lực NGAY** ở project đã cài — chúng được đọc lúc chạy, không còn phải build + publish + `/update-framework`.
 - **Template artifact cũng bị inline lúc build.** `templates/feature.template` và `prd.template.md` được `{{include}}` **nướng cứng** vào file lệnh, nên lệnh không đọc path template lúc chạy — sửa `.agent/templates/` **không có tác dụng**. Đổi cấu trúc `.feature`/PRD = sửa `templates/*` trong repo framework rồi build lại.
 
 ### Self-check — contract trace không được lệch

package/docs/02-concepts/traceability.md

@@ -119,6 +119,63 @@ flowchart LR
 
 ---
 
+## Sổ trace trong git — và khi nó conflict
+
+Sổ trace là **dữ liệu không dựng lại được**, nằm trong git, và **được nhiều người ghi trên
+nhiều nhánh song song**. Ba thứ đó cộng lại nghĩa là git phải được dạy cách merge nó.
+
+### Luật đã cài sẵn
+
+`/setup-ai-first` tạo `{trace_dir}/.gitattributes`; `/sync` Step 4c kiểm và tạo hộ nếu thiếu:
+
+```gitattributes
+*.tsv    text eol=lf merge=union
+*.jsonl  text eol=lf merge=union
+```
+
+| Luật | Không có nó thì sao |
+|---|---|
+| `merge=union` | Hai nhánh cùng ghi một sổ → **conflict**. Giải bằng "take mine" = **mất row của người kia, im lặng**. Với `trace-history.jsonl` (append cuối file) thì **mọi** cặp nhánh song song đều conflict. |
+| `text eol=lf` | 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. Team mixed Windows/macOS gặp ca này mà không ai làm gì sai. |
+
+`union` là driver **built-in** của git — không ai cần chạy `git config` gì thêm.
+
+> **`*.json` cố ý KHÔNG có trong danh sách.** `trace-report.json` nằm cùng thư mục và union
+> trên JSON tạo ra **JSON không hợp lệ** → panel VS Code parse lỗi. Nó **sinh lại được**:
+> conflict ở đó thì chạy lại `/validate-traces`, đừng merge tay.
+
+### Đánh đổi có chủ ý: trùng row thay vì mất row
+
+`merge=union` **có thể** tạo hai row cùng `sc_id`. Đó là **thiết kế**, không phải lỗi:
+
+```
+trùng row  →  --lint-trace T4 bắt được  →  /validate-traces reconcile  →  sạch
+mất  row  →  KHÔNG có gì bắt được       →  phát hiện sau 3 tuần        →  khôi phục bằng tay
+```
+
+Đây là lý do luật merge và `--lint-trace` là **một cặp**: union chuyển lỗi từ dạng *im lặng*
+sang dạng *bắt được*, và cái bắt nó phải tồn tại. Có union mà không có lint thì chỉ là đổi chỗ lỗi.
+
+### Playbook — 4 bước
+
+Vẫn thấy conflict trong `{trace_dir}/` (nhánh phân kỳ quá xa, hoặc luật vừa mới được thêm):
+
+1. **GIỮ CẢ HAI BÊN.** Xoá ba dòng marker (`<<<<<<<`, `=======`, `>>>>>>>`), giữ toàn bộ row
+   của cả hai phía. **Đừng chọn một bên.**
+2. `npx @educa-corp/sdd-framework --lint-trace` — T7 xác nhận không còn marker, T4 chỉ ra row nào trùng.
+3. `/validate-traces` — reconcile row trùng về một row đúng, tính lại `status`.
+4. Commit.
+
+**Ba điều không bao giờ làm:**
+
+| ❌ | Vì sao |
+|---|---|
+| `git checkout --ours/--theirs` trên file trace | Xoá sạch row của một phía. Không có gì báo. |
+| Xoá file trace để "cho sạch" rồi chạy lại pipeline | Sổ **không regenerate được** — `trace-history.jsonl` mất là mất vĩnh viễn. |
+| Commit khi còn marker | Marker thành một "row" TSV. `--lint-trace` T7 bắt, nhưng nếu chưa cắm vào CI thì nó vào nhánh chung. |
+
+---
+
 ## Đọc tiếp (Next)
 
 - [Architecture](architecture.md) — 3 lớp & context-loader