@educa-corp/sdd-framework 0.4.2 → 0.6.0

package/docs/explain/README.md

@@ -1,134 +1,135 @@
-# 🔬 Explain — Giải phẫu từng command (Command Deep-Dive)
-
-> Tài liệu **đi sâu vào bên trong** từng command của pipeline, theo đúng thứ tự thực thi. Mục tiêu: làm **cơ sở review, phân tích và tối ưu** các bước trong pipeline.
->
-> Khác với [Pipeline Steps](../02-concepts/pipeline-steps/) (tầng khái niệm, gom theo phase), thư mục này bám **logic thực tế trong command file** (`commands/*.md`) — từng bước command làm gì, giải quyết vấn đề gì, và **điểm nào đáng cân nhắc tối ưu**.
-
----
-
-## Cách đọc (How to read)
-
-Mỗi trang command theo cùng một khuôn:
-
-| Mục | Nội dung |
-|-----|----------|
-| **Một câu** | Command làm gì |
-| **Vấn đề giải quyết** | Tại sao command này tồn tại |
-| **Vị trí & tiền đề** | Chạy sau gì, cần gì mở khoá |
-| **Input / Output** | Đầu vào & sản phẩm cụ thể |
-| **Các bước xử lý** | ⭐ Đi từng bước bên trong, dễ hiểu |
-| **Checkpoint & Gate** | Điểm dừng con người |
-| **Cơ chế đặc biệt** | Phần logic riêng đáng chú ý |
-| **👓 Góc nhìn tối ưu** | Điểm review/optimize: chi phí, rủi ro, phụ thuộc |
-| **Kết nối** | Bước trước ← → bước sau |
-
----
-
-## ⭐ Bộ khung chung mọi command (Shared Skeleton)
-
-**Đọc phần này trước.** Mọi command file được build từ `.tmpl` + `{{include:steps/*.md}}`, nên đều có **cùng một bộ khung** bao quanh logic riêng. Hiểu bộ khung một lần → các trang command chỉ cần nói phần **riêng**.
-
-Cấu trúc một command file:
-
-```
-┌─ Gate (steps/gate) ──────────── chung, giống hệt mọi lệnh
-├─ Context Loader (steps/context-loader) ── chung, 7 bước
-├─ Business Language Guard (steps/business-language) ── chung, chỉ lệnh viết doc nghiệp vụ
-├─ ★ LOGIC RIÊNG CỦA LỆNH ★ ──── phần mỗi trang explain tập trung
-└─ Report Footer (steps/report-footer) ── chung
-```
-
-### 1 · Gate — Cổng vào chuẩn (5 bước con)
-
-Chạy **trước** mọi logic riêng:
-
-| Bước | Tên | Việc | Ý nghĩa tối ưu |
-|------|-----|------|----------------|
-| 0 | **Sub-agent mode** | Nếu `$ARGUMENTS` là JSON có `_agent_mode` → bỏ Gate 1/2/3, chạy đúng phạm vi orchestrator giao (target_file, uc_id, uc_section, dimension) | Cơ chế fan-out per-UC dùng chính lệnh này làm "worker" |
-| 0-B | **Model check** | Khuyến nghị Opus. `Y`=tiếp · `S`=bỏ qua (⚠️ report) · khác=DỪNG | Checkpoint mềm; sub-agent bỏ qua (orchestrator đã check) |
-| 1 | **Target file** | Phân giải file mục tiêu từ path / UC-ID / ticket bằng glob theo bố cục feature-package; nhiều kết quả → hỏi | Điểm hay tốn 1 vòng hỏi khi `$ARGUMENTS` rỗng |
-| 2 | **Context loader** | Chạy 7 bước nạp context (mục 2 dưới) | Nơi quyết định "đúng-đủ-gọn" — trọng tâm tối ưu |
-| 3 | **CHECKPOINT** | Trình target + scope → chờ `Y` | Read-only command bỏ qua |
-
-### 2 · Context Loader — "Thủ thư" (7 bước)
-
-Nạp context theo thứ tự chống Lost-in-the-Middle (đầu = "build gì", giữa = ràng buộc, cuối = "follow style này"):
-
-| Bước | Nạp gì | Ghi chú |
-|------|--------|---------|
-| 1 | **project-context.yaml** | tech_stack, conventions, domains, paths; trích `domain`/`prd_slug` từ path target |
-| 1.5 | **Service routing** (umbrella) | Khớp domain → service; dạng phẳng (2a) hay map-theo-platform (2b); override paths sang `spec_source` |
-| 1.6 | **Service conventions** (umbrella) | Nạp `build_command`/`test_command` riêng của service; set `service_root` |
-| 2 | **Module stack-profile** | `.agent/modules/{module}/stack-profile.yaml` — layer/test pattern |
-| 3 | **CLAUDE.md phân tầng** | root (BASE) + service overlay (stack) — **overlay thắng**; §2 layer/package, §3 naming, §5 error |
-| 4 | **data-protection** | Pattern file nhạy cảm — cấm truy cập cả phiên |
-| 5 | **Business dictionary** | Canonical + **banned terms** (thực thi chủ động) + enum registry |
-| 6 | **Core entities** | Entity catalog + field registry + relationship map |
-| 6.5 | **platform_type** | Suy `backend`/`web-frontend`/`mobile` từ module |
-| 6.7 | **Project lessons** | Guardrail từ `/learn` — ràng buộc cứng ngang coding standards |
-| 7 | **Recap** | In khối `[CTX LOADED]` — đẩy sự thật quan trọng lên cuối bộ nhớ |
-
-> 👓 **Đây là component quyết định 80% chất lượng.** Khi review tối ưu: chú ý `required` vs `optional`, filter theo domain, và budget context (~50% window).
-
-### 3 · Business Language Guard (chỉ lệnh viết doc nghiệp vụ)
-
-Chặn thuật ngữ kỹ thuật rò vào PRD/BDD/product-definition. 4 nhóm xử lý: (1) tương tác/UI → diễn đạt lại nghiệp vụ · (2) visual thuần → chuyển Design Spec · (3) backend/contract → bỏ về Tech Docs · (4) ẩn dụ dữ liệu → xét ngữ cảnh (không thay máy móc). Áp cho `/define-product`, `/generate-prd`, `/refine-prd`, `/review-context`, `/generate-bdd`.
-
-### 4 · Report Footer (mọi lệnh)
-
-Kết thúc bằng: **Status badge** (✅/❌/⚠️) · **Output Artifacts** (file tạo/sửa) · **Pipeline Position** (`◀ bạn ở đây`) · **Next command** (gợi ý lệnh kế + tham số).
-
----
-
-## Danh sách command theo thứ tự pipeline (Pipeline Order)
-
-### Phase Setup & Discovery
-- [00 · `/setup-ai-first`](00-setup-ai-first.md)
-- [00b · `/generate-architecture`](00b-generate-architecture.md)
-- [01 · `/define-product`](01-define-product.md)
-
-### Phase Specification (PRD)
-- [02 · `/generate-prd`](02-generate-prd.md)
-- [03 · `/refine-prd`](03-refine-prd.md)
-- [04 · `/review-context`](04-review-context.md) *(dùng cho cả PRD & BDD)*
-
-### Phase Design
-- [05 · `/generate-design-spec`](05-generate-design-spec.md)
-- [06 · `/generate-bdd`](06-generate-bdd.md)
-- [07 · `/generate-tech-docs`](07-generate-tech-docs.md)
-- [08 · `/review-tech-docs`](08-review-tech-docs.md)
-
-### Phase Implementation
-- [09 · `/generate-code`](09-generate-code.md)
-- [10 · `/review-code`](10-review-code.md)
-- [11 · `/map-testids`](11-map-testids.md)
-
-### Phase Dev Self-Test
-- [12 · `/dev-gen-test`](12-dev-gen-test.md)
-- [13 · `/dev-run-test`](13-dev-run-test.md)
-- [14 · `/dev-smoke-test`](14-dev-smoke-test.md)
-
-### Phase QC Automation
-- [15 · `/qc-analyze`](15-qc-analyze.md)
-- [16 · `/qc-plan`](16-qc-plan.md)
-- [17 · `/qc-design-test`](17-qc-design-test.md)
-- [18 · `/qc-review`](18-qc-review.md)
-- [19 · `/qc-run-test`](19-qc-run-test.md)
-- [20 · `/qc-report`](20-qc-report.md)
-
-### Phase Trace & Quality
-- [21 · `/validate-traces`](21-validate-traces.md)
-- [22 · `/generate-spec-manifest`](22-generate-spec-manifest.md)
-
-### Lệnh xuyên suốt (Cross-cutting)
-- [23 · `/fix-bug`](23-fix-bug.md)
-- [24 · `/debug`](24-debug.md)
-- [25 · `/report-bug`](25-report-bug.md)
-- [26 · `/propose-scenario`](26-propose-scenario.md)
-- [27 · `/learn`](27-learn.md)
-- [28 · `/sync`](28-sync.md)
-- [29 · `/update-framework`](29-update-framework.md)
-
----
-
-*Nguồn: `commands/*.md` (build từ `.tmpl` + `steps/`). Khi command đổi, cập nhật trang tương ứng ở đây.*
+# 🔬 Explain — Giải phẫu từng command (Command Deep-Dive)
+
+> Tài liệu **đi sâu vào bên trong** từng command của pipeline, theo đúng thứ tự thực thi. Mục tiêu: làm **cơ sở review, phân tích và tối ưu** các bước trong pipeline.
+>
+> Khác với [Pipeline Steps](../02-concepts/pipeline-steps/) (tầng khái niệm, gom theo phase), thư mục này bám **logic thực tế trong command file** (`commands/*.md`) — từng bước command làm gì, giải quyết vấn đề gì, và **điểm nào đáng cân nhắc tối ưu**.
+
+---
+
+## Cách đọc (How to read)
+
+Mỗi trang command theo cùng một khuôn:
+
+| Mục | Nội dung |
+|-----|----------|
+| **Một câu** | Command làm gì |
+| **Vấn đề giải quyết** | Tại sao command này tồn tại |
+| **Vị trí & tiền đề** | Chạy sau gì, cần gì mở khoá |
+| **Input / Output** | Đầu vào & sản phẩm cụ thể |
+| **Các bước xử lý** | ⭐ Đi từng bước bên trong, dễ hiểu |
+| **Checkpoint & Gate** | Điểm dừng con người |
+| **Cơ chế đặc biệt** | Phần logic riêng đáng chú ý |
+| **👓 Góc nhìn tối ưu** | Điểm review/optimize: chi phí, rủi ro, phụ thuộc |
+| **Kết nối** | Bước trước ← → bước sau |
+
+---
+
+## ⭐ Bộ khung chung mọi command (Shared Skeleton)
+
+**Đọc phần này trước.** Mọi command file được build từ `.tmpl` + `{{include:steps/*.md}}`, nên đều có **cùng một bộ khung** bao quanh logic riêng. Hiểu bộ khung một lần → các trang command chỉ cần nói phần **riêng**.
+
+Cấu trúc một command file:
+
+```
+┌─ Gate (steps/gate) ──────────── chung, giống hệt mọi lệnh
+├─ Context Loader (steps/context-loader) ── chung, 7 bước
+├─ Business Language Guard (steps/business-language) ── chung, chỉ lệnh viết doc nghiệp vụ
+├─ ★ LOGIC RIÊNG CỦA LỆNH ★ ──── phần mỗi trang explain tập trung
+└─ Report Footer (steps/report-footer) ── chung
+```
+
+### 1 · Gate — Cổng vào chuẩn (5 bước con)
+
+Chạy **trước** mọi logic riêng:
+
+| Bước | Tên | Việc | Ý nghĩa tối ưu |
+|------|-----|------|----------------|
+| 0 | **Sub-agent mode** | Nếu `$ARGUMENTS` là JSON có `_agent_mode` → bỏ Gate 1/2/3, chạy đúng phạm vi orchestrator giao (target_file, uc_id, uc_section, dimension) | Cơ chế fan-out per-UC dùng chính lệnh này làm "worker" |
+| 0-B | **Model check** | Khuyến nghị Opus. `Y`=tiếp · `S`=bỏ qua (⚠️ report) · khác=DỪNG | Checkpoint mềm; sub-agent bỏ qua (orchestrator đã check) |
+| 1 | **Target file** | Phân giải file mục tiêu từ path / UC-ID / ticket bằng glob theo bố cục feature-package; nhiều kết quả → hỏi | Điểm hay tốn 1 vòng hỏi khi `$ARGUMENTS` rỗng |
+| 2 | **Context loader** | Chạy 7 bước nạp context (mục 2 dưới) | Nơi quyết định "đúng-đủ-gọn" — trọng tâm tối ưu |
+| 3 | **CHECKPOINT** | Trình target + scope → chờ `Y` | Read-only command bỏ qua |
+
+### 2 · Context Loader — "Thủ thư" (7 bước)
+
+Nạp context theo thứ tự chống Lost-in-the-Middle (đầu = "build gì", giữa = ràng buộc, cuối = "follow style này"):
+
+| Bước | Nạp gì | Ghi chú |
+|------|--------|---------|
+| 1 | **project-context.yaml** | tech_stack, conventions, domains, paths; trích `domain`/`prd_slug` từ path target |
+| 1.5 | **Service routing** (umbrella) | Khớp domain → service; dạng phẳng (2a) hay map-theo-platform (2b); override paths sang `spec_source` |
+| 1.6 | **Service conventions** (umbrella) | Nạp `build_command`/`test_command` riêng của service; set `service_root` |
+| 2 | **Module stack-profile** | `.agent/modules/{module}/stack-profile.yaml` — layer/test pattern |
+| 3 | **CLAUDE.md phân tầng** | root (BASE) + service overlay (stack) — **overlay thắng**; §2 layer/package, §3 naming, §5 error |
+| 4 | **data-protection** | Pattern file nhạy cảm — cấm truy cập cả phiên |
+| 5 | **Business dictionary** | Canonical + **banned terms** (thực thi chủ động) + enum registry |
+| 6 | **Core entities** | Entity catalog + field registry + relationship map |
+| 6.5 | **platform_type** | Suy `backend`/`web-frontend`/`mobile` từ module |
+| 6.7 | **Project lessons** | Guardrail từ `/learn` — ràng buộc cứng ngang coding standards |
+| 7 | **Recap** | In khối `[CTX LOADED]` — đẩy sự thật quan trọng lên cuối bộ nhớ |
+
+> 👓 **Đây là component quyết định 80% chất lượng.** Khi review tối ưu: chú ý `required` vs `optional`, filter theo domain, và budget context (~50% window).
+
+### 3 · Business Language Guard (chỉ lệnh viết doc nghiệp vụ)
+
+Chặn thuật ngữ kỹ thuật rò vào PRD/BDD/product-definition. 4 nhóm xử lý: (1) tương tác/UI → diễn đạt lại nghiệp vụ · (2) visual thuần → chuyển Design Spec · (3) backend/contract → bỏ về Tech Docs · (4) ẩn dụ dữ liệu → xét ngữ cảnh (không thay máy móc). Áp cho `/define-product`, `/generate-prd`, `/refine-prd`, `/review-context`, `/generate-bdd`.
+
+### 4 · Report Footer (mọi lệnh)
+
+Kết thúc bằng: **Status badge** (✅/❌/⚠️) · **Output Artifacts** (file tạo/sửa) · **Pipeline Position** (`◀ bạn ở đây`) · **Next command** (gợi ý lệnh kế + tham số).
+
+---
+
+## Danh sách command theo thứ tự pipeline (Pipeline Order)
+
+### Phase Setup & Discovery
+- [00 · `/setup-ai-first`](00-setup-ai-first.md)
+- [00b · `/generate-architecture`](00b-generate-architecture.md)
+- [01 · `/define-product`](01-define-product.md)
+
+### Phase Specification (PRD)
+- [02 · `/generate-prd`](02-generate-prd.md)
+- [02b · `/extend-prd`](02b-extend-prd.md) — thêm yêu cầu vào PRD **đã duyệt**
+- [03 · `/refine-prd`](03-refine-prd.md)
+- [04 · `/review-context`](04-review-context.md) *(dùng cho cả PRD & BDD)*
+
+### Phase Design
+- [05 · `/generate-design-spec`](05-generate-design-spec.md)
+- [06 · `/generate-bdd`](06-generate-bdd.md)
+- [07 · `/generate-tech-docs`](07-generate-tech-docs.md)
+- [08 · `/review-tech-docs`](08-review-tech-docs.md)
+
+### Phase Implementation
+- [09 · `/generate-code`](09-generate-code.md)
+- [10 · `/review-code`](10-review-code.md)
+- [11 · `/map-testids`](11-map-testids.md)
+
+### Phase Dev Self-Test
+- [12 · `/dev-gen-test`](12-dev-gen-test.md)
+- [13 · `/dev-run-test`](13-dev-run-test.md)
+- [14 · `/dev-smoke-test`](14-dev-smoke-test.md)
+
+### Phase QC Automation
+- [15 · `/qc-analyze`](15-qc-analyze.md)
+- [16 · `/qc-plan`](16-qc-plan.md)
+- [17 · `/qc-design-test`](17-qc-design-test.md)
+- [18 · `/qc-review`](18-qc-review.md)
+- [19 · `/qc-run-test`](19-qc-run-test.md)
+- [20 · `/qc-report`](20-qc-report.md)
+
+### Phase Trace & Quality
+- [21 · `/validate-traces`](21-validate-traces.md)
+- [22 · `/generate-spec-manifest`](22-generate-spec-manifest.md)
+
+### Lệnh xuyên suốt (Cross-cutting)
+- [23 · `/fix-bug`](23-fix-bug.md)
+- [24 · `/debug`](24-debug.md)
+- [25 · `/report-bug`](25-report-bug.md)
+- [26 · `/propose-scenario`](26-propose-scenario.md)
+- [27 · `/learn`](27-learn.md)
+- [28 · `/sync`](28-sync.md)
+- [29 · `/update-framework`](29-update-framework.md)
+
+---
+
+*Nguồn: `commands/*.md` (build từ `.tmpl` + `steps/`). Khi command đổi, cập nhật trang tương ứng ở đây.*

package/hooks/data-guard.js

@@ -2,28 +2,90 @@
 /**
  * data-guard.js — Claude Code PreToolUse Hook
  *
- * Blocks AI from reading, writing, or executing commands involving
- * sensitive files (credentials, secrets, private keys, .env, etc.)
+ * Chặn AI đọc/ghi/thực thi trên file nhạy cảm (credential, secret, private key, .env…).
  *
- * Install: copy to your project and register in .claude/settings.json
- * (see hooks/settings.json for registration template)
+ * Cài: copy vào project + đăng ký trong .claude/settings.json
+ * (mẫu: hooks/settings.json — hoặc dùng `npx @educa-corp/sdd-framework --hooks`)
  *
- * Exit codes:
- *   0 = allow the tool call
- *   2 = block the tool call (Claude Code interprets this as a hard block)
+ * Exit code:
+ *   0 = cho phép
+ *   2 = chặn cứng (Claude Code hiểu mã này là block)
+ *
+ * ── VÌ SAO BẢN NÀY KHÁC BẢN ĐẦU (GAPS-v3 G42) ────────────────────────────────
+ *
+ * Bản đầu có ba lỗi độc lập; hai trong số đó chặn đúng công việc mà framework tồn
+ * tại để làm, và cái còn lại làm lời hứa bảo mật không đúng:
+ *
+ *   (a) matcher thiếu `Grep` — `Grep` với output_mode:"content" trên `.env` TRẢ VỀ
+ *       nội dung file và không đi qua hook. Nên câu "AI will be blocked from reading
+ *       .env" là sai.
+ *   (b) pattern soi CẢ PATH, không neo. `/password/i` khớp
+ *       `specs/auth/forgot-password/UC1.feature` và `src/auth/PasswordResetController.java`
+ *       ⇒ một framework sinh code từ spec KHÔNG LÀM NỔI feature auth khi bật hook
+ *       của chính nó.
+ *   (c) Bash soi cả command string ⇒ `git commit -m "feat: password reset UC1"` bị
+ *       chặn — đúng câu commit mà các lệnh hướng dẫn chạy ở cuối pipeline.
+ *
+ * Cả hai đường đều dẫn tới cùng một kết cục: người dùng TẮT HOOK, và mất luôn phần
+ * bảo vệ thật. Một guard bị tắt bảo vệ bằng không.
+ *
+ * ── MÔ HÌNH MỚI ──────────────────────────────────────────────────────────────
+ *
+ * Secret sống trong file CẤU HÌNH/DỮ LIỆU, không sống trong file MÃ NGUỒN.
+ * `secrets.json` là kho bí mật; `PasswordResetController.java` là code.
+ * Nên pattern chung (secret/credential/password/token/api-key) chỉ áp cho file
+ * KHÔNG phải mã nguồn. Pattern cứng (.env, .pem, .key…) áp cho mọi file.
+ * Cộng thêm allowlist thư mục làm việc của framework (specs/, .trace/, docs/…).
  */
 
-const readline = require('readline');
-
-// ── Sensitive file patterns ────────────────────────────────────────────────
+// ── Thư mục làm việc của framework — không bao giờ chứa secret thật ───────────
+// Tên feature ("forgot-password", "api-key-rotation") hay khớp pattern chung, và
+// đây chính là chỗ ca (b) nổ. Cho qua TRƯỚC khi soi.
+const SAFE_DIR_PREFIXES = [
+  'specs/', '.trace/', '.trace-mirror/', '.living-docs/',
+  'docs/', '.agent/', 'feedback/', '.claude/',
+];
 
-const SENSITIVE_PATH_PATTERNS = [
-  // Environment files
+// ── Đuôi file MÃ NGUỒN — pattern chung không áp ───────────────────────────────
+// Một file .java/.ts/.dart tên gì đi nữa cũng là code, không phải kho secret.
+// (Pattern CỨNG bên dưới vẫn áp — nhưng .pem/.key không nằm trong danh sách này.)
+const CODE_EXT = new Set([
+  'java', 'kt', 'kts', 'scala', 'groovy',
+  'ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'vue', 'svelte',
+  'py', 'go', 'rs', 'rb', 'php', 'cs', 'fs', 'vb',
+  'swift', 'm', 'mm', 'dart', 'c', 'h', 'cpp', 'hpp', 'cc',
+  'sql', 'graphql', 'proto', 'feature', 'md', 'mdx', 'txt',
+  'html', 'css', 'scss', 'less', 'tsv', 'csv',
+]);
+
+// ── Pattern CỨNG — áp cho mọi file, soi TÊN FILE ─────────────────────────────
+const SENSITIVE_NAME_HARD = [
   /^\.env$/i,
   /^\.env\./i,
   /\.env$/i,
 
-  // Secret/credential files
+  /\.key$/i,
+  /\.pem$/i,
+  /\.p12$/i,
+  /\.pfx$/i,
+  /\.jks$/i,
+  /\.keystore$/i,
+  /^id_rsa$/i,
+  /^id_ed25519$/i,
+
+  /^application-(prod|production|staging)\.(yml|yaml|properties)$/i,
+  /^appsettings\.(Production|Staging)\.json$/i,
+  /^database\.yml$/i,
+  /^master\.key$/i,
+  /^oauth-private\.key$/i,
+  /^credentials$/i,
+  /^\.npmrc$/i,
+  /^\.pypirc$/i,
+  /^\.netrc$/i,
+];
+
+// ── Pattern CHUNG — chỉ áp cho file KHÔNG phải mã nguồn, soi TÊN FILE ────────
+const SENSITIVE_NAME_SOFT = [
   /secret/i,
   /credential/i,
   /password/i,
@@ -32,60 +94,84 @@ const SENSITIVE_PATH_PATTERNS = [
   /api[_-]?key/i,
   /access[_-]?token/i,
   /auth[_-]?token/i,
+];
 
-  // Crypto keys and certificates
-  /\.key$/i,
-  /\.pem$/i,
-  /\.p12$/i,
-  /\.pfx$/i,
-  /\.jks$/i,
-  /\.keystore$/i,
-
-  // Framework-specific prod configs
-  /application-(prod|production|staging)\.(yml|yaml|properties)$/i,
-  /appsettings\.(Production|Staging)\.json$/i,
-  /database\.yml$/i,
-  /config\/master\.key$/i,
-  /storage\/oauth-private\.key$/i,
-
-  // Secret directories
-  /^secrets\//i,
-  /\/secrets\//i,
-  /^\.secrets\//i,
+// ── Pattern THƯ MỤC — soi cả path ────────────────────────────────────────────
+const SENSITIVE_DIR = [
+  /(^|\/)secrets?\//i,
+  /(^|\/)\.secrets?\//i,
+  /(^|\/)\.ssh\//i,
+  /(^|\/)\.aws\//i,
+  /(^|\/)\.gnupg\//i,
 ];
 
-const SENSITIVE_BASH_PATTERNS = [
+// ── Lệnh bash nguy hiểm bất kể path ──────────────────────────────────────────
+const SENSITIVE_BASH = [
   /\bprintenv\b/i,
-  /\benv\b.*\|\s*(grep|awk|sed).*secret/i,
-  /cat\s+\.env/i,
-  /docker\s+inspect/i,
-  /kubectl\s+get\s+secret.*-o\s+yaml/i,
+  /\benv\b\s*(\||$)/i,
+  /kubectl\s+get\s+secrets?\b[^|]*-o\s*(yaml|json)/i,
+  /\baws\s+secretsmanager\s+get-secret-value/i,
+  /\bgcloud\s+secrets\s+versions\s+access/i,
+  /\bvault\s+(read|kv\s+get)\b/i,
+  // `docker inspect` KHÔNG chặn cả cụm (lệnh debug thường dùng) — chỉ chặn khi nó
+  // thực sự moi Env ra. Bản đầu chặn cả cụm và đó là ma sát không đổi lấy gì.
+  /docker\s+inspect[^|]*\.Config\.Env/i,
 ];
 
-// ── Helpers ────────────────────────────────────────────────────────────────
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function normalize(p) {
+  return String(p).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function extOf(base) {
+  const i = base.lastIndexOf('.');
+  return i > 0 ? base.slice(i + 1).toLowerCase() : '';
+}
 
 function isSensitivePath(filePath) {
   if (!filePath) return false;
-  const normalized = filePath.replace(/\\/g, '/');
-  return SENSITIVE_PATH_PATTERNS.some(pattern => pattern.test(normalized));
+  const p = normalize(filePath);
+
+  // Vùng làm việc của framework — spec/trace/doc không chứa secret thật, và tên
+  // feature ở đó hay khớp pattern chung. Bỏ cả tiền tố tuyệt đối trước khi so.
+  const relish = p.replace(/^([a-zA-Z]:)?\/+/, '');
+  if (SAFE_DIR_PREFIXES.some(d => relish.startsWith(d) || relish.includes('/' + d))) return false;
+
+  if (SENSITIVE_DIR.some(re => re.test(p))) return true;
+
+  const base = p.split('/').pop() || '';
+  if (SENSITIVE_NAME_HARD.some(re => re.test(base))) return true;
+
+  // Pattern chung: bỏ qua mã nguồn. Đây là chỗ bản đầu chặn PasswordResetController.java.
+  if (CODE_EXT.has(extOf(base))) return false;
+  return SENSITIVE_NAME_SOFT.some(re => re.test(base));
 }
 
-function isSensitiveCommand(command) {
-  if (!command) return false;
-  return SENSITIVE_BASH_PATTERNS.some(pattern => pattern.test(command));
+/**
+ * Tách các token TRÔNG GIỐNG PATH ra khỏi một command line.
+ * Bản đầu soi cả chuỗi lệnh nên `git commit -m "feat: password reset"` bị chặn.
+ */
+function pathishTokens(command) {
+  return String(command)
+    .split(/[\s;|&()<>]+/)
+    .map(t => t.replace(/^["']|["']$/g, ''))
+    .filter(t => t && !t.startsWith('-') && /[\/.]/.test(t) && !/^-{1,2}/.test(t));
 }
 
-function block(reason) {
-  console.error(`\n🔒 DATA GUARD — BLOCKED\n${reason}\n`);
-  console.error('If you need configuration values, describe what you need');
-  console.error('without sharing actual secrets. Use placeholder values in generated code.\n');
+function block(reason, detail) {
+  console.error(`\n🔒 DATA GUARD — BLOCKED\n${reason}`);
+  if (detail) console.error(detail);
+  console.error('\nCần giá trị cấu hình? Mô tả thứ bạn cần mà KHÔNG đưa secret thật;');
+  console.error('dùng placeholder trong code sinh ra.');
+  console.error('Nghĩ đây là chặn nhầm? Vùng specs/ .trace/ docs/ .agent/ luôn được cho qua,');
+  console.error('và file mã nguồn (.java/.ts/.dart…) không bị pattern chung đụng tới.\n');
   process.exit(2);
 }
 
-// ── Main ───────────────────────────────────────────────────────────────────
+// ── Main ─────────────────────────────────────────────────────────────────────
 
 let rawInput = '';
-
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', chunk => { rawInput += chunk; });
 process.stdin.on('end', () => {
@@ -93,49 +179,54 @@ process.stdin.on('end', () => {
   try {
     input = JSON.parse(rawInput);
   } catch {
-    // Cannot parse input — allow (fail open, not fail closed)
+    // Fail-open CÓ CHỦ Ý: hook parse lỗi mà chặn hết thì làm cả project đứng máy.
+    // Nhưng không im lặng — im lặng là cách một guard chết mà không ai biết.
+    console.error('⚠️  data-guard: không parse được input hook — CHO QUA (fail-open).');
     process.exit(0);
   }
 
-  const toolName  = input.tool_name  || '';
-  const toolInput = input.tool_input || {};
-
-  // ── Read tool ─────────────────────────────────────────────────────────
-  if (toolName === 'Read') {
-    const filePath = toolInput.file_path || '';
-    if (isSensitivePath(filePath)) {
-      block(`Attempted to READ sensitive file: ${filePath}`);
-    }
-  }
-
-  // ── Write tool ────────────────────────────────────────────────────────
-  if (toolName === 'Write') {
-    const filePath = toolInput.file_path || '';
-    if (isSensitivePath(filePath)) {
-      block(`Attempted to WRITE to sensitive file: ${filePath}`);
+  const tool = input.tool_name || '';
+  const arg  = input.tool_input || {};
+
+  switch (tool) {
+    case 'Read':
+    case 'Write':
+    case 'Edit':
+    case 'NotebookEdit': {
+      const f = arg.file_path || arg.notebook_path || '';
+      if (isSensitivePath(f)) block(`Thao tác ${tool} trên file nhạy cảm: ${f}`);
+      break;
     }
-  }
 
-  // ── Edit tool ─────────────────────────────────────────────────────────
-  if (toolName === 'Edit') {
-    const filePath = toolInput.file_path || '';
-    if (isSensitivePath(filePath)) {
-      block(`Attempted to EDIT sensitive file: ${filePath}`);
+    // Grep ĐỌC ĐƯỢC NỘI DUNG (output_mode: "content"). Thiếu nhánh này thì mọi thứ
+    // ở trên chỉ là cửa trước, còn cửa sau mở toang — chính là lỗi (a) của G42.
+    case 'Grep': {
+      const target = arg.path || '';
+      if (target && isSensitivePath(target)) {
+        block(`Grep nhắm vào path nhạy cảm: ${target}`);
+      }
+      if (arg.glob && isSensitivePath(String(arg.glob).replace(/\*/g, 'x'))) {
+        block(`Grep dùng glob nhắm vào file nhạy cảm: ${arg.glob}`);
+      }
+      // Đang đi TÌM chính chuỗi secret — chặn kèm lý do khác hẳn.
+      if (arg.pattern && /\b(BEGIN [A-Z ]*PRIVATE KEY|aws_secret_access_key|sk-[A-Za-z0-9]{16,})/i
+          .test(String(arg.pattern))) {
+        block(`Grep đang tìm chính giá trị bí mật: ${String(arg.pattern).slice(0, 40)}…`);
+      }
+      break;
     }
-  }
 
-  // ── Bash tool ─────────────────────────────────────────────────────────
-  if (toolName === 'Bash') {
-    const command = toolInput.command || '';
-    if (isSensitiveCommand(command)) {
-      block(`Attempted to execute sensitive command: ${command}`);
-    }
-    // Also check if the command references a sensitive file path
-    if (isSensitivePath(command)) {
-      block(`Bash command references a sensitive file path: ${command}`);
+    case 'Bash': {
+      const cmd = arg.command || '';
+      if (SENSITIVE_BASH.some(re => re.test(cmd))) {
+        block(`Lệnh moi secret: ${cmd.slice(0, 120)}`);
+      }
+      // CHỈ soi token trông giống path — không soi cả chuỗi lệnh (lỗi (c) của G42).
+      const hit = pathishTokens(cmd).find(isSensitivePath);
+      if (hit) block(`Lệnh bash chạm file nhạy cảm: ${hit}`, `   (trong: ${cmd.slice(0, 120)})`);
+      break;
     }
   }
 
-  // Allow all other tool calls
   process.exit(0);
 });

package/hooks/settings.json

@@ -1,11 +1,12 @@
 {
   "_comment": "Claude Code hook registration template. Copy this content into your project's .claude/settings.json",
+  "_matcher_note": "Grep BẮT BUỘC có trong matcher: Grep với output_mode:content ĐỌC ĐƯỢC nội dung file, nên thiếu nó thì việc chặn Read chỉ là cửa trước (GAPS-v3 G42a).",
   "_docs": "https://docs.anthropic.com/claude/claude-code/hooks",
 
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Read|Write|Edit|Bash",
+        "matcher": "Read|Write|Edit|Grep|NotebookEdit|Bash",
         "hooks": [
           {
             "type": "command",