@educa-corp/sdd-framework 0.4.2 → 0.6.0

package/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/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ỏ trong spec repo mode}
+# @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.module: {active_module trong umbrella mode; "unknown" trong spec repo mode}
 # @trace.status: draft
 # @trace.author: AI-generated

package/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/scripts/init.sh

@@ -1,49 +0,0 @@
-#!/usr/bin/env bash
-# init.sh — First-time setup of SDD Framework framework in a consumer project.
-#
-# Usage:
-#   bash scripts/init.sh
-#   bash scripts/init.sh --module java-spring
-#   bash scripts/init.sh --module java-spring --hooks
-#
-# What it does:
-#   1. Copies framework files to .agent/ (commands, steps, hooks, rules, templates, modules)
-#   2. Creates lightweight shortcut files in .claude/commands/ that delegate to .agent/
-#   3. Writes .agent/FRAMEWORK_VERSION for upgrade.sh to track installed version
-#
-# After init:
-#   - Commit .agent/ to git so the entire team shares the framework
-#   - Run /setup-ai-first in Claude Code to complete project setup
-#   - To upgrade later: bash scripts/upgrade.sh
-
-set -euo pipefail
-
-echo ""
-echo "╔══════════════════════════════════════════╗"
-echo "║   SDD Framework — Project Init            ║"
-echo "╚══════════════════════════════════════════╝"
-echo ""
-
-# ── Prerequisite check ────────────────────────────────────────────────────────
-
-if ! command -v node &> /dev/null; then
-  echo "❌ Node.js is required. Install from https://nodejs.org"
-  exit 1
-fi
-
-# ── Run installer via npx ─────────────────────────────────────────────────────
-
-echo "Running: npx @educa-corp/sdd-framework --init $*"
-echo ""
-
-npx -y @educa-corp/sdd-framework --init "$@"
-
-echo ""
-echo "✅ Init complete!"
-echo ""
-echo "Recommended next steps:"
-echo "  git add .agent/ .claude/commands/"
-echo "  git commit -m 'chore: init spec-driven-docs framework'"
-echo ""
-echo "Then open Claude Code and run: /setup-ai-first"
-echo ""

package/scripts/upgrade.sh

@@ -1,94 +0,0 @@
-#!/usr/bin/env bash
-# upgrade.sh — Upgrade SDD Framework framework in an existing project.
-#
-# Usage:
-#   bash scripts/upgrade.sh
-#   bash scripts/upgrade.sh --module java-spring   # also upgrade a stack module
-#
-# What it does:
-#   1. Reads current installed version from .agent/FRAMEWORK_VERSION
-#   2. Checks npm registry for the latest published version
-#   3. If newer: runs npx @educa-corp/sdd-framework@latest --init to update .agent/
-#   4. Reports what changed so you can review before committing
-#
-# Requirements:
-#   - Project was set up with init.sh (or npx ... --init)
-#   - .agent/FRAMEWORK_VERSION exists
-
-set -euo pipefail
-
-AGENT_DIR=".agent"
-VERSION_FILE="${AGENT_DIR}/FRAMEWORK_VERSION"
-
-echo ""
-echo "╔══════════════════════════════════════════╗"
-echo "║   SDD Framework — Upgrade                 ║"
-echo "╚══════════════════════════════════════════╝"
-echo ""
-
-# ── Prerequisite checks ───────────────────────────────────────────────────────
-
-if ! command -v node &> /dev/null; then
-  echo "❌ Node.js is required. Install from https://nodejs.org"
-  exit 1
-fi
-
-if ! command -v npm &> /dev/null; then
-  echo "❌ npm is required. Install Node.js from https://nodejs.org"
-  exit 1
-fi
-
-if [ ! -f "$VERSION_FILE" ]; then
-  echo "❌ .agent/FRAMEWORK_VERSION not found."
-  echo ""
-  echo "   This project was not set up with --init."
-  echo "   To set up the new structure:"
-  echo ""
-  echo "     bash scripts/init.sh"
-  echo "   or:"
-  echo "     npx @educa-corp/sdd-framework --init"
-  echo ""
-  exit 1
-fi
-
-# ── Version comparison ────────────────────────────────────────────────────────
-
-CURRENT=$(cat "$VERSION_FILE" | tr -d '[:space:]')
-echo "Checking npm registry ..."
-
-LATEST=$(npm view @educa-corp/sdd-framework version 2>/dev/null || echo "unknown")
-
-echo ""
-echo "  Installed : v${CURRENT}"
-echo "  Latest    : v${LATEST}"
-echo ""
-
-if [ "$LATEST" = "unknown" ]; then
-  echo "⚠️  Could not reach npm registry. Check your internet connection."
-  exit 1
-fi
-
-if [ "$CURRENT" = "$LATEST" ]; then
-  echo "✅ Already up to date (v${CURRENT}). Nothing to do."
-  echo ""
-  exit 0
-fi
-
-# ── Upgrade ───────────────────────────────────────────────────────────────────
-
-echo "Upgrading v${CURRENT} → v${LATEST} ..."
-echo ""
-
-npx -y @educa-corp/sdd-framework@latest --init "$@"
-
-# ── Post-upgrade guidance ─────────────────────────────────────────────────────
-
-echo ""
-echo "✅ Upgraded to v${LATEST}!"
-echo ""
-echo "Review what changed in .agent/ before committing:"
-echo ""
-echo "  git diff .agent/"
-echo "  git add .agent/"
-echo "  git commit -m 'chore: upgrade spec-driven-docs v${CURRENT} → v${LATEST}'"
-echo ""