@educa-corp/sdd-framework 0.6.0 → 0.7.0

package/commands/review-code.tmpl

@@ -1,146 +0,0 @@
-# /review-code — Code Review chỉ-đọc
-
-**CẢNH BÁO: READ-ONLY. Chỉ report, KHÔNG sửa.**
-
-## Gate
-
-*Checkpoint: **không chặn** — read-only. 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à một UC-ID, file path, hoặc tên branch hiện tại. Bỏ qua sang nạp context ngay sau khi phân giải target.*
-
-## Context
-{{include:steps/context-loader.md}}
-
----
-
-## Pre-Review Scan
-
-*(Tách khỏi CHECKPOINT của Gate — phần này liệt kê file và scenario thực tế trong scope.)*
-
-Quét tìm file implementation và scenario, rồi hiện:
-
-```
-Review Scope — {UC-ID}
-──────────────────────────────────────
-UC        : {UC-ID}
-Files     : {danh sách file gắn tag @trace.implements={UC-ID}}
-Scenarios : {N} scenario trong file .feature
-
-Tiếp tục review? (Y/N)
-```
-
-Chờ "Y" rõ ràng trước khi tiếp tục.
-
----
-
-## Review Dimensions
-
-### 1. Traceability
-
-*Đây là lăng kính bảo vệ toàn bộ cơ chế drift-detection. `/generate-code` phải ghi **5 tag** lên mỗi entry-point (**6** với FE/App); thiếu bất kỳ tag nào thì `/validate-traces` mù ở file đó — **im lặng**, không lệnh nào khác bắt được.*
-
-- [ ] Mỗi entry-point (layer theo CLAUDE.md §2) có `@trace.implements={UC-ID}-SC{N}`?
-- [ ] **Mỗi block `@trace.implements` có đủ tag đi kèm?** → thiếu bất kỳ tag nào = **major** (không phải minor):
-
-  | Tag | Thiếu thì mù cái gì |
-  |---|---|
-  | `@trace.prd_version` | `/validate-traces` Step 4 — PRD drift |
-  | `@trace.bdd_version` | Step 5c — BDD drift |
-  | `@trace.tech_doc_revision` | Step 5 — tech-doc drift *(bỏ được nếu UC không có tech-doc)* |
-  | `@trace.design_spec_version` | Step 5d — design-spec drift. **CHỈ FE/App** (`@trace.platform` = `web`/`app`): thiếu ở FE = **major**; có ở `system`/backend = **minor** (tag thừa, không có design-spec để so) |
-  | `@trace.source` | mất con trỏ ngược về spec |
-
-- [ ] `@trace.source` trỏ tới file `.feature` **có thật**, đúng platform (`bdd/{platform}/{UC-ID}-{slug}.feature`)? → sai path = **major**
-- [ ] **File phủ nhiều UC: mỗi UC có block tag RIÊNG đặt trên method của nó?** → gộp về một header file, hoặc `@trace.source` trỏ **thư mục**, = **major**. Lý do: 4 tag version là scalar theo từng UC (gộp → Step 4/5/5c/5d báo drift oan hoặc mù drift thật); và các lệnh tra tag bằng **khớp chuỗi chính xác** nên tag trỏ folder ra 0 kết quả → UC rơi về `UNTRACKED` dù code đã có.
-- [ ] Mỗi test file có tag `@trace.verifies={UC-ID}-SC{N}`?
-- [ ] **Không có tag mồ côi** — `@trace.implements`/`@trace.verifies` trỏ tới SC **không tồn tại** trong `.feature`? → **critical** (`TRACE_ORPHAN`; xem `/validate-traces` Step 2b)
-- [ ] Không có tag `@trace` ở sai layer?
-- [ ] `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` cập nhật chưa? (nếu stale → chạy `/validate-traces {UC-ID}` trước, rồi chạy lại review này)
-
-### 2. Layer Architecture (từ CLAUDE.md §2)
-- [ ] Mỗi class ở đúng layer?
-- [ ] Phụ thuộc giữa layer đi đúng chiều?
-- [ ] Không layer nào bị bypass?
-
-### 3. Coding Standards (từ CLAUDE.md §3)
-- [ ] Tuân theo naming convention?
-- [ ] Response wrapper dùng nhất quán?
-- [ ] Exception được throw (không bị nuốt)?
-- [ ] Không magic number, không dữ liệu nhạy cảm trong log?
-- [ ] Annotation transaction đúng?
-
-### 4. Spec Compliance
-- [ ] Mỗi scenario trong .feature có implementation?
-- [ ] Không có endpoint không tài liệu (code không có spec backing)?
-
-### 5. Seam & Stub — mồ côi khi ghép luồng
-
-*`/generate-code` vừa sinh ra sổ `_seams.tsv` ở bước trước. Đây là lớp lỗi mà **build xanh + test từng-UC xanh** vẫn không bắt được: luồng ghép chạy vào no-op, hoặc hàm thật không ai gọi. `/validate-traces` Step 5b cũng soi — trùng có chủ đích, vì bắt ở đây rẻ hơn (ngay sau codegen, trước khi sinh test).*
-
-Đọc sổ `{paths.trace_dir}/{domain}/{prd-slug}/_seams.tsv` (nếu có) + quét code dưới `{code_base_package}`:
-
-- [ ] Sổ **0 dòng** `status = READY`? (`READY` = đồng nghĩa cờ 🔴 `SEAM_UNWIRED` / `STUB_UNRESOLVED`) → còn dòng nào = **critical**
-- [ ] Không có class `*Stub*`/`*Mock*` nào **còn là binding đang dùng** trong khi hàng thật đã tồn tại? → `SEAM_UNWIRED`, **critical**
-- [ ] Không có method nào còn `@trace.stub` rỗng trong khi `@trace.stub_owner` **đã gen**? → `STUB_UNRESOLVED`, **critical**
-- [ ] Không có method thật **mồ côi** — logic thật được đẻ **song song** thay vì lấp vào stub cũ (Fill-before-create bị trượt)? → **critical**
-- [ ] Mỗi stub/seam **mới** sinh trong lần này có đủ tag (`@trace.stub` + `@trace.stub_owner` + `@trace.stub_for`, hoặc `@trace.seam_pending` + `@trace.seam_port`) **và** một dòng `PENDING` trong sổ? → thiếu = **major** (nợ không ghi sổ = nợ tàng hình)
-
-> `SEAM_PENDING` / `STUB_PENDING` (owner UC chưa gen) là **bình thường** — chỉ nhắc, không tạo finding.
-
-## Output
-
-{{include:steps/report-footer.md}}
-
-```
-/review-code Report — {UC-ID}
-Critical: {X} | Major: {Y} | Minor: {Z}
-
-### Critical
-| # | File | Line | Issue | Suggested Fix |
-
-### Major
-| # | File | Line | Issue | Suggested Fix |
-
-### Minor
-| # | File | Line | Issue | Suggested Fix |
-
-Output Artifacts: none (read-only)
-
-Verdict: APPROVED ✅ | NEEDS_FIX ❌
-  (Bất kỳ finding critical nào ở lăng kính 5 → NEEDS_FIX, KỂ CẢ khi build xanh
-   và test từng-UC xanh — đó chính là loại lỗi hai thứ đó không bắt được.)
-
-Nếu APPROVED ✅:
-  Next: /dev-gen-test {UC-ID}
-
-Nếu NEEDS_FIX ❌:
-  - Fix nhỏ (1–3 dòng, không đổi logic) → fix inline → chạy lại /review-code {UC-ID}
-  - Thiếu tag version / @trace.source sai  → bổ sung tại chỗ (giá trị lấy từ header .feature
-                                             + tech-doc), rồi chạy lại /validate-traces {UC-ID}
-  - Tag mồ côi (TRACE_ORPHAN)             → sửa sc_id cho đúng SC hiện có, hoặc xoá code/test
-                                             nếu behavior không còn cần
-  - SEAM_UNWIRED 🔴                        → trỏ binding sang class thật, xoá/thay stub, build lại
-  - STUB_UNRESOLVED 🔴                     → /generate-code {owner_uc} (lấp logic TẠI CHỖ vào
-                                             method trắng, xoá hàm song song)
-  - Vấn đề logic / kiến trúc              → /fix-bug {TICKET_ID}
-  - Spec mismatch (code ≠ scenario)       → /generate-code {feature-file}  (gen lại UC bị ảnh hưởng)
-```
-
----
-
-## Đề xuất ghi Lessons (tuỳ chọn)
-
-Với mỗi finding **Critical/Major** thể hiện một **lỗi AI lặp lại** trong quá trình sinh code
-(một vi phạm kiến trúc/standards mà AI có khả năng làm lại — KHÔNG phải typo một lần hay nguyên nhân bên ngoài), hỏi:
-
-```
-Finding "{issue}" trông như một lỗi lặp lại.
-Ghi nó thành project lesson để /generate-code không lặp lại? (Y/N)
-```
-
-Nếu `Y` → chạy quy trình capture bên dưới với `category=code-gen`, `source=/review-code {UC-ID}`,
-`scope` = domain hoặc file glob bị ảnh hưởng.
-
-{{include:steps/capture-lesson.md}}