openmoneta-dev-kit 1.9.0

package/hooks/check-plan-exists.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# preToolUse hook (Write|StrReplace|EditNotebook|Delete):
+# v1.7.0 Adaptive Planning Gate:
+# - Không có plan active → allow cho task thường.
+# - Không có plan active + file nhạy cảm → block, yêu cầu tạo plan Draft + user review.
+# - Có plan Draft → block code edit, yêu cầu user approve rồi đổi Status: In Progress.
+# - Có plan In Progress → enforce file scope theo "Files ảnh hưởng"/"Files thay đổi".
+# Trả permission: deny + agent_message để buộc AI tự correct.
+
+set -euo pipefail
+
+INPUT_JSON=$(cat 2>/dev/null || echo '{}')
+
+allow() {
+  echo '{"permission": "allow"}'
+  exit 0
+}
+
+deny() {
+  local msg="$1"
+  if command -v jq >/dev/null 2>&1; then
+    jq -n --arg msg "$msg" '{"permission": "deny", "agent_message": $msg}'
+  else
+    ESCAPED=$(printf '%s' "$msg" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))')
+    printf '{"permission": "deny", "agent_message": %s}\n' "$ESCAPED"
+  fi
+  exit 0
+}
+
+FILE_PATH=""
+WORKSPACE="."
+if command -v jq >/dev/null 2>&1; then
+  FILE_PATH=$(echo "$INPUT_JSON" | jq -r '.tool_input.path // .tool_input.file_path // .tool_input.target_notebook // ""' 2>/dev/null || echo "")
+  WORKSPACE=$(echo "$INPUT_JSON" | jq -r '.workspace_roots[0] // "."' 2>/dev/null || echo ".")
+fi
+
+[[ -z "$FILE_PATH" ]] && allow
+
+# Convert relative -> absolute
+if [[ "$FILE_PATH" == /* ]]; then
+  ABS_PATH="$FILE_PATH"
+else
+  ABS_PATH="$WORKSPACE/$FILE_PATH"
+fi
+
+# === Skip nếu file nằm ngoài workspace (vd: ~/.cursor/, /tmp/...) ===
+case "$ABS_PATH" in
+  "$WORKSPACE"/*) ;;
+  *) allow ;;
+esac
+
+REL_PATH="${ABS_PATH#$WORKSPACE/}"
+
+# === Whitelist: file không cần plan ===
+case "$REL_PATH" in
+  README.md|README|CHANGELOG.md|.gitignore|.env.example|AGENTS.md|LICENSE|LICENSE.md|LICENSE.txt)
+    allow
+    ;;
+  docs/*|plans/*|.cursor/*|.vscode/*)
+    allow
+    ;;
+  .github/*)
+    case "$REL_PATH" in
+      .github/workflows/*) ;;
+      *) allow ;;
+    esac
+    ;;
+  *.md)
+    case "$REL_PATH" in
+      src/*|lib/*|app/*|pages/*|components/*) ;;
+      *) allow ;;
+    esac
+    ;;
+esac
+
+# === Tìm plan active ===
+PLANS_DIR="$WORKSPACE/plans"
+if [[ ! -d "$PLANS_DIR" ]]; then
+  allow
+fi
+
+# Tìm plan theo trạng thái. Draft = đang chờ user review, In Progress = đã được approve để triển khai.
+DRAFT_PLANS=$(grep -liE "^\*{0,2}status\*{0,2}:?[[:space:]]*draft" "$PLANS_DIR"/*.md 2>/dev/null || true)
+IN_PROGRESS_PLANS=$(grep -liE "^\*{0,2}status\*{0,2}:?[[:space:]]*in progress" "$PLANS_DIR"/*.md 2>/dev/null || true)
+
+is_sensitive_path() {
+  local path_lc
+  path_lc=$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')
+  case "$path_lc" in
+    .env|.env.*|*auth*|*oauth*|*session*|*token*|*secret*|*credential*|*security*|*permission*|*rbac*|*role*|*admin*|*payment*|*billing*|*invoice*|*subscription*|*checkout*|*db*|*database*|*schema*|*migration*|*prisma*|*drizzle*|*sql*|*deploy*|*infra*|.github/workflows/*)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+if [[ -z "$IN_PROGRESS_PLANS" ]]; then
+  if [[ -n "$DRAFT_PLANS" ]]; then
+    PLAN_LIST=$(echo "$DRAFT_PLANS" | sed "s|$WORKSPACE/||g")
+    deny "Có plan Draft nhưng chưa được user approve, nên chưa được sửa code '$REL_PATH':
+$PLAN_LIST
+
+Quy trình đúng:
+1. Trình bày tóm tắt plan cho user review.
+2. Hỏi user approve / sửa plan / hủy plan.
+3. Chỉ khi user approve: đổi Status từ Draft → In Progress.
+4. Retry edit này.
+
+Lý do: Agent mode được phép tự tạo plan cho task lớn/rủi ro, nhưng KHÔNG được tự approve rồi triển khai."
+  fi
+
+  if is_sensitive_path "$REL_PATH"; then
+    deny "File '$REL_PATH' thuộc nhóm nhạy cảm/rủi ro cao nhưng chưa có plan được user approve.
+
+Nhóm cần plan trước khi code: auth/oauth/session/token/secret/security/permission/admin/payment/billing/db/schema/migration/deploy/infra.
+
+Quy trình:
+1. Tạo repo plan: plans/$(date +%Y-%m-%d)-<slug>.md với Status: Draft.
+2. Liệt kê '$REL_PATH' trong '## Files ảnh hưởng' hoặc '## Files thay đổi'.
+3. Trình bày plan cho user review.
+4. Khi user approve: đổi Status: In Progress.
+5. Retry edit này."
+  fi
+
+  # Adaptive mode: không có plan active và file không nhạy cảm → allow.
+  # Agent vẫn phải tự quyết định tạo plan nếu task lớn/rủi ro theo AGENTS.md + plan-writer.
+  allow
+fi
+
+# === Kiểm tra file có trong "Files ảnh hưởng" của ít nhất 1 plan active ===
+FOUND=0
+for plan in $IN_PROGRESS_PLANS; do
+  if awk '/^##[[:space:]]+(Files ảnh hưởng|Files thay đổi|Files changed|Files)[[:space:]]*$/{flag=1; next} /^##[[:space:]]/{flag=0} flag' "$plan" | grep -qF "$REL_PATH"; then
+    FOUND=1
+    break
+  fi
+done
+
+if [[ $FOUND -eq 0 ]]; then
+  PLAN_LIST=$(echo "$IN_PROGRESS_PLANS" | sed "s|$WORKSPACE/||g")
+  deny "File '$REL_PATH' KHÔNG nằm trong section '## Files ảnh hưởng' của plan(s) active:
+$PLAN_LIST
+
+Lựa chọn:
+A) Update plan hiện tại - thêm '$REL_PATH' vào section '## Files ảnh hưởng' hoặc '## Files thay đổi', rồi retry.
+B) Nếu đây là task khác, tạo plan mới với Status: Draft và xin user review trước khi code.
+C) Nếu file này thuộc whitelist (docs/plans/README/CHANGELOG/...), kiểm tra path có đúng không.
+
+KHÔNG được tự ý mở rộng scope mà không update plan."
+fi
+
+allow

package/hooks/enforce-docs-first.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# enforce-docs-first.sh — preToolUse hook (Read|Glob|Grep).
+# Block AI search/read source code nếu CHƯA đọc docs/INDEX.md trong session này.
+# Mục tiêu: enforce token-aware reading workflow của skill requirement-analysis.
+#
+# Marker: <workspace>/.cursor/.docs-index-read (created khi AI Read docs/INDEX.md).
+# Marker được clean ở sessionStart hook → mỗi session phải đọc lại 1 lần.
+
+set -euo pipefail
+
+INPUT_JSON=$(cat 2>/dev/null || echo '{}')
+
+allow() {
+  echo '{"permission": "allow"}'
+  exit 0
+}
+
+deny() {
+  local msg="$1"
+  if command -v jq >/dev/null 2>&1; then
+    jq -n --arg msg "$msg" '{"permission": "deny", "agent_message": $msg}'
+  else
+    ESCAPED=$(printf '%s' "$msg" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))')
+    printf '{"permission": "deny", "agent_message": %s}\n' "$ESCAPED"
+  fi
+  exit 0
+}
+
+WORKSPACE="."
+TOOL_NAME=""
+PATHS=""
+
+if command -v jq >/dev/null 2>&1; then
+  WORKSPACE=$(echo "$INPUT_JSON" | jq -r '.workspace_roots[0] // "."' 2>/dev/null || echo ".")
+  TOOL_NAME=$(echo "$INPUT_JSON" | jq -r '.tool_name // ""' 2>/dev/null || echo "")
+  PATHS=$(echo "$INPUT_JSON" | jq -r '
+    .tool_input // {} |
+    [.path, .file_path, .target_directory, .pattern, .glob_pattern, .glob] |
+    map(select(. != null and . != "")) |
+    join(" ")
+  ' 2>/dev/null || echo "")
+else
+  allow
+fi
+
+[[ -z "$TOOL_NAME" ]] && allow
+
+case "$TOOL_NAME" in
+  Read|Glob|Grep) ;;
+  *) allow ;;
+esac
+
+normalize_workspace() {
+  local ws="$1"
+  if [[ -d "$ws" ]]; then
+    (cd "$ws" && pwd -P) 2>/dev/null || printf '%s\n' "$ws"
+  else
+    printf '%s\n' "$ws"
+  fi
+}
+
+infer_workspace_from_paths() {
+  local raw p dir
+  for raw in $PATHS; do
+    case "$raw" in
+      */docs/INDEX.md)
+        printf '%s\n' "${raw%/docs/INDEX.md}"
+        return 0
+        ;;
+    esac
+
+    case "$raw" in
+      /*)
+        if [[ -d "$raw" ]]; then
+          dir="$raw"
+        else
+          dir=$(dirname "$raw")
+        fi
+
+        while [[ -n "$dir" && "$dir" != "/" && "$dir" != "." ]]; do
+          if [[ -f "$dir/docs/INDEX.md" ]]; then
+            printf '%s\n' "$dir"
+            return 0
+          fi
+          p=$(dirname "$dir")
+          [[ "$p" == "$dir" ]] && break
+          dir="$p"
+        done
+        ;;
+    esac
+  done
+}
+
+WORKSPACE=$(normalize_workspace "$WORKSPACE")
+INFERRED_WORKSPACE=$(infer_workspace_from_paths || true)
+if [[ -n "$INFERRED_WORKSPACE" && -f "$INFERRED_WORKSPACE/docs/INDEX.md" ]]; then
+  WORKSPACE=$(normalize_workspace "$INFERRED_WORKSPACE")
+fi
+
+INDEX_FILE="$WORKSPACE/docs/INDEX.md"
+[[ -f "$INDEX_FILE" ]] || allow
+
+MARKER="$WORKSPACE/.cursor/.docs-index-read"
+
+case "$PATHS" in
+  *"docs/INDEX.md"*)
+    mkdir -p "$WORKSPACE/.cursor"
+    touch "$MARKER"
+    allow
+    ;;
+esac
+
+case "$PATHS" in
+  *"docs/"*|*"plans/"*|*".cursor/"*|*".github/"*|*".vscode/"*) allow ;;
+  *"AGENTS.md"*|*"README"*|*"CHANGELOG"*|*"LICENSE"*) allow ;;
+  *"package.json"*|*"package-lock.json"*|*"pnpm-lock.yaml"*|*"yarn.lock"*) allow ;;
+  *"tsconfig"*|*"vite.config"*|*"playwright.config"*|*"biome.config"*|*"vitest.config"*|*"astro.config"*) allow ;;
+  *".env"*|*".gitignore"*|*".gitattributes"*|*"Dockerfile"*|*"docker-compose"*) allow ;;
+  tests/*|test/*|e2e/*|*/tests/*|*/test/*|*/e2e/*|*"__tests__"*) allow ;;
+  *"terraform/"*|*"infra/"*|*"k8s/"*|*"kubernetes/"*) allow ;;
+esac
+
+SHOULD_CHECK=0
+case "$PATHS" in
+  *"apps/"*|*"packages/"*|*"src/"*|*"lib/"*|*"components/"*|*"server/"*|*"modules/"*|*"pages/"*|" app/"*|*"/app/"*)
+    SHOULD_CHECK=1
+    ;;
+esac
+
+if [[ "$SHOULD_CHECK" -eq 0 ]]; then
+  case "$TOOL_NAME" in
+    Glob|Grep) SHOULD_CHECK=1 ;;
+  esac
+fi
+
+if [[ "$SHOULD_CHECK" -eq 1 ]]; then
+  if [[ ! -f "$MARKER" ]]; then
+    deny "Bạn đang $TOOL_NAME source code TRƯỚC khi đọc docs/INDEX.md. Vi phạm token-aware reading (skill requirement-analysis Bước 1).
+
+DEBUG:
+- Tool: $TOOL_NAME
+- Workspace hook đang dùng: $WORKSPACE
+- docs/INDEX.md expected: $INDEX_FILE
+- Marker expected: $MARKER
+- Tool input paths/patterns: $PATHS
+
+QUY TRÌNH ĐÚNG (BẮT BUỘC, theo thứ tự):
+1. Read $WORKSPACE/docs/INDEX.md TRƯỚC TIÊN.
+2. Tìm keyword task trong table 'Feature/Keyword → Module' để biết module liên quan.
+3. Read docs/modules/<matched-module>/README.md cho mỗi module liên quan (1-3 module thường đủ).
+4. CHỈ rồi mới Read/Glob/Grep source code của module đó.
+
+LÝ DO ENFORCE:
+- Skip docs/INDEX.md = lãng phí 30-50% token (đọc thừa file không liên quan).
+- Bỏ qua context module-level (Public API, dependencies, design rationale, anti-patterns).
+- Có thể vô tình vi phạm architecture rules.
+
+HÀNH ĐỘNG NGAY:
+→ Read $WORKSPACE/docs/INDEX.md, sau đó retry $TOOL_NAME này.
+
+LƯU Ý:
+- Nếu bạn đã đọc docs/INDEX.md bằng subagent thì parent agent vẫn phải Read docs/INDEX.md một lần để tạo marker trong session hiện tại.
+- Không delegate subagent chỉ để né hook. Subagent chỉ dùng khi task thật sự cần exploration/read-only isolation.
+
+(Hook này chỉ chạy 1 lần / session. Sau khi đọc docs/INDEX.md, marker .cursor/.docs-index-read được set và hook sẽ allow mọi tool call source-code khác trong session.)"
+  fi
+fi
+
+allow

package/hooks/inject-process-context.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# sessionStart hook: inject SUMMARY ngắn (~45 dòng) của quy trình 6 bước vào context.
+#
+# v1.7.0 Lean Mode: KHÔNG inject full AGENTS.md.tpl nữa (giảm ~1500 tokens/session).
+# AGENTS.md ở project root vẫn có đầy đủ chi tiết — AI đọc khi cần.
+#
+# Cũng check update từ remote git repo (cache 24h).
+
+set -euo pipefail
+
+INPUT_JSON=$(cat 2>/dev/null || echo '{}')
+
+# Reset docs-index marker mỗi session (force re-read INDEX.md)
+if command -v jq >/dev/null 2>&1; then
+  WORKSPACE_FROM_INPUT=$(echo "$INPUT_JSON" | jq -r '.workspace_roots[0] // ""' 2>/dev/null || echo "")
+  if [[ -n "$WORKSPACE_FROM_INPUT" && -d "$WORKSPACE_FROM_INPUT/.cursor" ]]; then
+    rm -f "$WORKSPACE_FROM_INPUT/.cursor/.docs-index-read" 2>/dev/null || true
+  fi
+fi
+
+# === Summary 6 bước (~45 dòng, ~650 tokens) ===
+SUMMARY='# OpenMoneta Dev Kit v1.7.0 — Quy trình 6 bước (Adaptive Planning)
+
+> Đây là context inject mỗi session. Chi tiết đầy đủ: `<workspace>/AGENTS.md`. Skills chi tiết: `~/.cursor/skills/<name>/SKILL.md`.
+
+## Nguyên tắc vàng
+1. Trả lời tiếng Việt.
+2. Đọc `docs/INDEX.md` ĐẦU TIÊN (hook `enforce-docs-first` chặn Read source nếu chưa đọc).
+3. Hỏi clarify TRƯỚC khi plan/code khi yêu cầu chưa rõ; nếu có plan thì ghi vào "## Hiểu yêu cầu".
+4. Surgical changes: mỗi dòng đổi trace về 1 task plan.
+5. Simplicity First: không abstraction/config dư thừa.
+6. Safe Push: khi user yêu cầu push, PHẢI sync remote ngay trước push; KHÔNG force-push shared branch.
+
+## 6 bước
+- **B1 Phân tích** (skill `requirement-analysis`): Read INDEX → match Token Routing → đọc README module candidate → đọc source → đặt câu hỏi critical để làm rõ yêu cầu, phân tích mọi trường hợp, phản biện và đề xuất phương án tối ưu nếu có (hoặc khai báo skip lý do).
+- **B2 Thiết kế** (skill `module-architect`): SRP 1 module 1 trách nhiệm. Feature mới có concept riêng → module mới (KHÔNG nhét utils/common/shared). Existing project: backfill `docs/modules/<slug>/README.md` 3 sections nếu thiếu. Module mới → thêm keyword vào Token Routing.
+- **B3 Adaptive Plan** (skill `plan-writer`): task nhỏ/rõ → không cần plan. Task lớn/rủi ro/mơ hồ → tạo repo plan `Status: Draft`, trình user review, chỉ code sau khi user approve và đổi `Status: In Progress`.
+- **B4 Triển khai**: nếu có plan active → chỉ edit file trong scope plan. Không plan → chỉ sửa đúng yêu cầu; nếu vượt ngưỡng/rủi ro → dừng tạo plan Draft.
+- **B5 Update doc + close** (hook `verify-completion` Check 6 enforce): sync module README (Public API + Dependencies). Plan → `Status: Done` + auto-archive `git mv plans/<f>.md plans/archive/`.
+- **B6 Pre-push Sync + Safe Push** (skill `safe-push`, CONDITIONAL): chỉ khi user yêu cầu push/commit+push. `git fetch` + rebase trước push, conflict code logic → hỏi user, verify lại, `git push` thường, retry ≤3, KHÔNG `--force` shared branch.
+
+## Sub-agents (delegate khi cần)
+- `requirement-analyst` (core, yêu cầu lớn).
+- `security-auditor`, `qa-autonomous`, `ui-tester` — **ON-DEMAND ONLY** (chỉ khi user yêu cầu explicit).
+
+## Skills on-demand (KHÔNG tự trigger)
+`security-checklist`, `test-strategy`, `automated-testing`, `auth-bypass-testing`, `ui-test-loop` — chỉ kích hoạt khi user yêu cầu rõ ("audit security X", "viết test cho Y", "Playwright UI test Z").
+
+## Skill core conditional
+`safe-push` — bắt buộc khi user yêu cầu push/đẩy code để tránh đè code người khác trong repo nhiều contributor.
+'
+
+# === Auto-check update (cache 24h) ===
+UPDATE_NOTICE=""
+VERSION_FILE="$HOME/.cursor/.openmoneta-version"
+REPO_FILE="$HOME/.cursor/.openmoneta-repo"
+CHECK_CACHE="$HOME/.cursor/.openmoneta-update-check"
+
+[[ -f "$VERSION_FILE" ]] || VERSION_FILE="$HOME/.cursor/.cursor-team-dev-version"
+[[ -f "$REPO_FILE" ]] || REPO_FILE="$HOME/.cursor/.cursor-team-dev-repo"
+
+check_update() {
+  [[ -f "$VERSION_FILE" && -f "$REPO_FILE" ]] || return 0
+
+  local current_version repo_dir
+  current_version=$(cat "$VERSION_FILE" 2>/dev/null || echo "")
+  repo_dir=$(cat "$REPO_FILE" 2>/dev/null || echo "")
+
+  [[ -n "$current_version" && -d "$repo_dir/.git" ]] || return 0
+
+  if [[ -f "$CHECK_CACHE" ]]; then
+    local last_check now diff
+    last_check=$(stat -f %m "$CHECK_CACHE" 2>/dev/null || stat -c %Y "$CHECK_CACHE" 2>/dev/null || echo 0)
+    now=$(date +%s)
+    diff=$((now - last_check))
+    if [[ $diff -lt 86400 ]]; then
+      if [[ -s "$CHECK_CACHE" ]]; then
+        UPDATE_NOTICE=$(cat "$CHECK_CACHE")
+      fi
+      return 0
+    fi
+  fi
+
+  > "$CHECK_CACHE"
+
+  command -v git >/dev/null 2>&1 || return 0
+  local remote_version branch
+  branch=$(git -C "$repo_dir" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
+
+  remote_version=$(timeout 5 git -C "$repo_dir" fetch origin "$branch" --quiet 2>/dev/null && \
+    git -C "$repo_dir" show "origin/$branch:VERSION" 2>/dev/null | tr -d '[:space:]' || echo "")
+
+  if [[ -n "$remote_version" && "$remote_version" != "$current_version" ]]; then
+    UPDATE_NOTICE="
+
+---
+> [!] **OPENMONETA DEV KIT UPDATE AVAILABLE**: v$current_version → v$remote_version
+> Chạy: \`bash $repo_dir/update.sh\` (macOS/Linux) hoặc \`pwsh $repo_dir/update.ps1\` (Windows). Restart Cursor sau update.
+---
+"
+    echo "$UPDATE_NOTICE" > "$CHECK_CACHE"
+  fi
+}
+
+check_update 2>/dev/null || true
+
+FULL_CONTEXT="${SUMMARY}${UPDATE_NOTICE}"
+
+if command -v jq >/dev/null 2>&1; then
+  jq -n --arg ctx "$FULL_CONTEXT" '{
+    "continue": true,
+    "additional_context": $ctx
+  }'
+else
+  ESCAPED=$(printf '%s' "$FULL_CONTEXT" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))')
+  printf '{"continue": true, "additional_context": %s}\n' "$ESCAPED"
+fi

package/hooks/track-changes.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# afterFileEdit hook: silent track file đã bị sửa trong session.
+# Append vào <workspace>/.cursor/.session-changes.json
+
+set -euo pipefail
+
+INPUT_JSON=$(cat 2>/dev/null || echo '{}')
+
+if ! command -v jq >/dev/null 2>&1; then
+  # Không có jq -> skip silent (không block agent)
+  echo '{"continue": true}'
+  exit 0
+fi
+
+WORKSPACE=$(echo "$INPUT_JSON" | jq -r '.workspace_roots[0] // "."' 2>/dev/null || echo ".")
+FILE_PATH=$(echo "$INPUT_JSON" | jq -r '.tool_input.path // .tool_input.file_path // .tool_input.target_notebook // ""' 2>/dev/null || echo "")
+
+[[ -z "$FILE_PATH" ]] && { echo '{"continue": true}'; exit 0; }
+
+# Convert path
+if [[ "$FILE_PATH" == /* ]]; then
+  REL_PATH="${FILE_PATH#$WORKSPACE/}"
+else
+  REL_PATH="$FILE_PATH"
+fi
+
+# Tạo .cursor/ nếu chưa có
+mkdir -p "$WORKSPACE/.cursor"
+TRACK_FILE="$WORKSPACE/.cursor/.session-changes.json"
+
+# Khởi tạo file nếu chưa có
+if [[ ! -f "$TRACK_FILE" ]]; then
+  echo "{\"started_at\": \"$(date -Iseconds)\", \"changes\": []}" > "$TRACK_FILE"
+fi
+
+# Append change entry
+TS=$(date -Iseconds)
+TOOL=$(echo "$INPUT_JSON" | jq -r '.tool_name // "unknown"' 2>/dev/null || echo "unknown")
+
+TMP=$(mktemp)
+jq --arg path "$REL_PATH" --arg ts "$TS" --arg tool "$TOOL" \
+  '.changes += [{"path": $path, "ts": $ts, "tool": $tool}]' \
+  "$TRACK_FILE" > "$TMP" && mv "$TMP" "$TRACK_FILE"
+
+# Silent - không block, không message
+echo '{"continue": true}'

package/hooks/verify-completion.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# stop hook: verify completion conditions trước khi cho session kết thúc.
+#
+# v1.7.0 Adaptive Planning — checks:
+#   5. Nếu có plan: Plan đánh dấu Status: Done + tất cả checkbox tick
+#   6. Module README synced (chỉ check README tồn tại, KHÔNG check changelog)
+#   7. Cross-module sprawl >3 module → WARN
+#   8. Token-aware reading marker tồn tại → WARN nếu thiếu
+#   9. Nếu có plan: section "## Hiểu yêu cầu" có nội dung không trống → BLOCK (audit clarify)
+#
+# Đã bỏ (so với v1.4.x):
+#   - Check 2 (test result file) — test giờ on-demand
+#   - Check 3 (UI screenshot) — test UI giờ on-demand
+#   - Check 4 (root CHANGELOG updated) — không enforce changelog dự án
+#
+# Graceful escape: nếu loop_count >= 4 -> exit, để user can thiệp.
+
+set -euo pipefail
+
+INPUT_JSON=$(cat 2>/dev/null || echo '{}')
+
+ok() { echo '{"continue": true}'; exit 0; }
+
+if ! command -v jq >/dev/null 2>&1; then
+  ok
+fi
+
+LOOP_COUNT=$(echo "$INPUT_JSON" | jq -r '.loop_count // 0' 2>/dev/null || echo 0)
+WORKSPACE=$(echo "$INPUT_JSON" | jq -r '.workspace_roots[0] // "."' 2>/dev/null || echo ".")
+
+LOOP_LIMIT=5
+if [[ "$LOOP_COUNT" -ge $((LOOP_LIMIT - 1)) ]]; then
+  echo "[verify-completion] loop_count=$LOOP_COUNT, graceful exit. Hãy review thủ công." >&2
+  ok
+fi
+
+PLANS_DIR="$WORKSPACE/plans"
+[[ -d "$PLANS_DIR" ]] || ok
+
+CHANGES_FILE="$WORKSPACE/.cursor/.session-changes.json"
+[[ -f "$CHANGES_FILE" ]] || ok
+
+NUM_CHANGES=$(jq '.changes | length' "$CHANGES_FILE" 2>/dev/null || echo 0)
+[[ "$NUM_CHANGES" -gt 0 ]] || ok
+
+# === Check 1 (gating): Có code change (file ngoài docs/plans/...) ===
+CODE_CHANGED=$(jq -r '.changes[] | .path' "$CHANGES_FILE" 2>/dev/null | grep -vE '^(docs/|plans/|README|\.gitignore|\.env\.example|AGENTS\.md|\.cursor/)' | head -1 || true)
+
+if [[ -z "$CODE_CHANGED" ]]; then
+  ok
+fi
+
+ISSUES=()
+WARNINGS=()
+
+# === Check 5: Nếu có plan active thì phải Done + checkbox ticked ===
+ACTIVE_PLANS=$(grep -liE "^\*{0,2}status\*{0,2}:?[[:space:]]*(in progress|draft)" "$PLANS_DIR"/*.md 2>/dev/null | grep -v INDEX || true)
+if [[ -n "$ACTIVE_PLANS" ]]; then
+  for plan in $ACTIVE_PLANS; do
+    PNAME=$(basename "$plan")
+    UNTICKED=$(grep -cE "^- \[ \]" "$plan" 2>/dev/null || true)
+    UNTICKED=${UNTICKED:-0}
+    if [[ "$UNTICKED" -gt 0 ]]; then
+      ISSUES+=("❌ Plan '$PNAME' còn $UNTICKED checkbox chưa tick. Hoàn thành các task hoặc chuyển sang plan khác.")
+    fi
+    if grep -qiE "^\*{0,2}status\*{0,2}:?[[:space:]]*draft" "$plan"; then
+      ISSUES+=("❌ Plan '$PNAME' vẫn ở trạng thái Draft. Plan Draft nghĩa là chưa được user approve; không nên có code change gắn với plan này.")
+    elif grep -qiE "^\*{0,2}status\*{0,2}:?[[:space:]]*in progress" "$plan"; then
+      ISSUES+=("❌ Plan '$PNAME' vẫn ở trạng thái In Progress. Đổi Status: Done sau khi hoàn tất Bước 5 + auto-archive sang plans/archive/.")
+    fi
+  done
+fi
+
+# === Check 9: Nếu có plan trong session thì phải có section "## Hiểu yêu cầu" ===
+# Audit trail clarify — đảm bảo AI đã hỏi user hoặc khai báo lý do skip.
+# Check áp dụng cho plan active hoặc plan đã sửa/tạo trong session (kể cả đã Done).
+CHANGED_PLANS=$(jq -r '.changes[] | .path' "$CHANGES_FILE" 2>/dev/null | grep -E '^plans/.*\.md$' | grep -v 'plans/INDEX.md' || true)
+ALL_RECENT_PLANS="$ACTIVE_PLANS"
+if [[ -n "$CHANGED_PLANS" ]]; then
+  while IFS= read -r rel_plan; do
+    [[ -z "$rel_plan" ]] && continue
+    ALL_RECENT_PLANS="$ALL_RECENT_PLANS"$'\n'"$WORKSPACE/$rel_plan"
+  done <<< "$CHANGED_PLANS"
+fi
+# Cũng check plan ở plans/archive/ nếu vừa archive
+if [[ -d "$PLANS_DIR/archive" ]]; then
+  ARCHIVED_RECENT=$(find "$PLANS_DIR/archive" -maxdepth 1 -name "*.md" -newer "$CHANGES_FILE" 2>/dev/null || true)
+  ALL_RECENT_PLANS="$ALL_RECENT_PLANS"$'\n'"$ARCHIVED_RECENT"
+fi
+ALL_RECENT_PLANS=$(printf '%s\n' "$ALL_RECENT_PLANS" | awk 'NF && !seen[$0]++')
+
+for plan in $ALL_RECENT_PLANS; do
+  [[ -z "$plan" || ! -f "$plan" ]] && continue
+  PNAME=$(basename "$plan")
+  # Phải có heading "## Hiểu yêu cầu"
+  if ! grep -qE "^##[[:space:]]+Hiểu yêu cầu" "$plan" 2>/dev/null; then
+    ISSUES+=("❌ Plan '$PNAME' THIẾU section '## Hiểu yêu cầu'. Đây là audit trail bắt buộc cho Bước 1 (clarify). Thêm câu hỏi đã hỏi user HOẶC 'Lý do skip clarify: ...'. Xem skill plan-writer template.")
+    continue
+  fi
+  # Phải có nội dung không trống dưới heading (≥1 dòng non-blank, non-comment trong 30 dòng tiếp theo)
+  CONTENT=$(awk '/^##[[:space:]]+Hiểu yêu cầu/{flag=1; next} flag && /^##[[:space:]]/{exit} flag {print}' "$plan" | grep -vE '^[[:space:]]*(>.*)?$' | head -5 || true)
+  if [[ -z "$(echo "$CONTENT" | tr -d '[:space:]')" ]]; then
+    ISSUES+=("❌ Plan '$PNAME' có section '## Hiểu yêu cầu' nhưng TRỐNG. Phải có 'Q: ... → A: ...' (đã hỏi user) HOẶC '**Lý do skip clarify**: ...' (task trivial).")
+  fi
+done
+
+# === Check 6: Module README synced (BLOCK strict) ===
+LIST_MODULES_SCRIPT="$HOME/.cursor/scripts/list-affected-modules.sh"
+AFFECTED=""
+if [[ -x "$LIST_MODULES_SCRIPT" || -f "$LIST_MODULES_SCRIPT" ]]; then
+  AFFECTED=$(bash "$LIST_MODULES_SCRIPT" "$CHANGES_FILE" 2>/dev/null || true)
+
+  if [[ -n "$AFFECTED" ]]; then
+    while IFS=$'\t' read -r slug docs_path source_path; do
+      [[ -z "$slug" ]] && continue
+      MODULE_README="$WORKSPACE/$docs_path/README.md"
+
+      if [[ ! -f "$MODULE_README" ]]; then
+        ISSUES+=("❌ Module '$slug' (source: $source_path) bị sửa nhưng chưa có '$docs_path/README.md'. Tạo README 3 sections (Trách nhiệm + Public API + Dependencies) theo skill module-architect Bước 2.2 + cập nhật bảng 'Modules hiện có' và 'Token Routing' trong docs/INDEX.md.")
+      fi
+    done <<< "$AFFECTED"
+
+    # === Check 7: Cross-module sprawl (WARN) ===
+    NUM_MODULES=$(echo "$AFFECTED" | awk -F'\t' 'NF >= 1 { print $1 }' | sort -u | wc -l | tr -d ' ')
+    if [[ "$NUM_MODULES" -gt 3 ]]; then
+      MODULE_LIST=$(echo "$AFFECTED" | awk -F'\t' 'NF >= 1 { print $1 }' | sort -u | tr '\n' ',' | sed 's/,$//')
+      WARNINGS+=("⚠️ Session đụng $NUM_MODULES module ($MODULE_LIST). Cross-module sprawl >3 module = red flag. Plan có giải thích 'Lý do cross-module' chưa? Cân nhắc tách thành nhiều plan nhỏ.")
+    fi
+  fi
+fi
+
+# === Check 8: Token-aware reading marker (WARN) ===
+if [[ -f "$WORKSPACE/docs/INDEX.md" && ! -f "$WORKSPACE/.cursor/.docs-index-read" ]]; then
+  WARNINGS+=("⚠️ Session có code change nhưng marker .cursor/.docs-index-read không tồn tại — AI có thể đã skip Bước 1 (Read docs/INDEX.md). Verify hook 'enforce-docs-first' đang chạy: cat ~/.cursor/hooks.json | jq '.hooks.preToolUse'. Nếu hook không chạy → restart Cursor sau khi cài v1.5.0.")
+fi
+
+# === Output ===
+WARN_STR=""
+if [[ ${#WARNINGS[@]} -gt 0 ]]; then
+  WARN_STR=$(printf '\n%s' "${WARNINGS[@]}")
+  WARN_STR="
+Cảnh báo (không block):$WARN_STR
+"
+fi
+
+if [[ ${#ISSUES[@]} -eq 0 ]]; then
+  rm -f "$CHANGES_FILE" 2>/dev/null || true
+  if [[ -n "$WARN_STR" ]]; then
+    echo "[Verify Completion] PASS với warnings:$WARN_STR" >&2
+  fi
+  ok
+fi
+
+ISSUES_STR=$(printf '%s\n' "${ISSUES[@]}")
+
+MSG="[Verify Completion v1.7.0] Session chưa thể kết thúc. Còn $((${#ISSUES[@]})) vấn đề:
+
+$ISSUES_STR
+$WARN_STR
+Hoàn tất các bước trên rồi thử kết thúc lại. Sau $((LOOP_LIMIT - 1 - LOOP_COUNT)) lần nhắc nữa, hệ thống sẽ ngừng nhắc."
+
+jq -n --arg msg "$MSG" '{
+  "continue": false,
+  "followup_message": $msg
+}'