claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/core/hooks/doc-check-on-commit.sh

@@ -0,0 +1,396 @@
+#!/bin/bash
+# doc-check-on-commit.sh — BLOCK commits when code changes lack doc updates
+# NOTE: bash case doesn't support ** globs — use in_dir() helper for any-depth matching
+
+# Helper: check if file is under a directory at ANY depth (no level limit)
+# Usage: in_dir "$file" "dirname"
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+in_dir() { echo "$1" | grep -q "/$2/"; }
+# Triggers on: PreToolUse(Bash) when command contains "git commit"
+# Profile: standard, strict
+#
+# Smart file-to-doc mapping: analyzes staged files and determines exactly
+# which documentation files must also be staged.
+#
+# EXIT CODES:
+#   0 = allow (docs present or no code changes requiring docs)
+#   2 = BLOCK (code changed, required docs missing)
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ]; then
+  exit 0
+fi
+
+# Read the tool input — Claude Code PreToolUse payload is:
+#   { "hook_event_name": "PreToolUse", "tool_name": "Bash",
+#     "tool_input": { "command": "…", "description": "…" } }
+# Historical bug: older versions read `.command` which is always null on
+# Bash PreToolUse, so the hook silently exited 0 and NEVER blocked any
+# commit. Accept both shapes for defence-in-depth.
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // .command // empty' 2>/dev/null)
+
+# Only trigger on git commit commands.
+# Also match `git -C <path> commit` — without this, the hook would run
+# `git diff --cached` in the wrong directory and see an empty STAGED,
+# silently exiting 0 while the real commit lands elsewhere.
+if ! echo "$COMMAND" | grep -qE 'git(\s+-[cC]\s+\S+)*\s+commit'; then
+  exit 0
+fi
+
+# Extract `-C <path>` target if present so we check staged files in the
+# actual target repo, not the shell cwd.
+GIT_TARGET_DIR=$(echo "$COMMAND" | sed -nE 's/.*git[[:space:]]+(-[cC][[:space:]]+([^[:space:]]+)).*/\2/p' | head -n1)
+if [ -n "$GIT_TARGET_DIR" ] && [ -d "$GIT_TARGET_DIR" ]; then
+  GIT_CMD_PREFIX="git -C $GIT_TARGET_DIR"
+else
+  GIT_CMD_PREFIX="git"
+fi
+
+# Get staged files (from the correct repo)
+STAGED=$($GIT_CMD_PREFIX diff --cached --name-only 2>/dev/null)
+if [ -z "$STAGED" ]; then
+  # Match `-a` / `--all` only as standalone flags — not as part of longer
+  # option names like `--allow-empty` or `--author`.
+  if echo "$COMMAND" | grep -qE '(^|[[:space:]])(-a|--all)([[:space:]]|$)'; then
+    STAGED=$($GIT_CMD_PREFIX diff --name-only 2>/dev/null)
+  fi
+fi
+
+if [ -z "$STAGED" ]; then
+  exit 0
+fi
+
+# ── Classify staged files ─────────────────────────────────────────────
+
+HAS_CODE=false
+ONLY_EXEMPT=true  # tests, configs, .claude/ files, docs
+
+# Track which doc categories are REQUIRED based on code changes
+NEED_DB_SCHEMA=false
+NEED_API_REF=false
+NEED_FRONTEND_DOCS=false
+NEED_BOT_DOCS=false
+NEED_MODERATION_DOCS=false
+NEED_AUTH_DOCS=false
+NEED_TREE_DOCS=false
+NEED_CLAUDE_MD=false
+NEED_PHOTO_DOCS=false
+NEED_FEED_DOCS=false
+NEED_ENTITLEMENTS_DOCS=false
+NEED_NOTIFICATION_DOCS=false
+NEED_BACKEND_LAYERS=false
+NEED_README=false
+
+# Track which docs ARE staged
+HAS_DB_SCHEMA=false
+HAS_API_REF=false
+HAS_OPENAPI=false
+HAS_FRONTEND_STATE=false
+HAS_FRONTEND_ONBOARDING=false
+HAS_BOT_MOD=false
+HAS_BOT_SUPPORT=false
+HAS_MODERATION=false
+HAS_AUTH=false
+HAS_TREE_DOCS=false
+HAS_CLAUDE_MD=false
+HAS_PHOTO_DOCS=false
+HAS_FEED_DOCS=false
+HAS_ENTITLEMENTS_DOCS=false
+HAS_NOTIFICATION_DOCS=false
+HAS_BACKEND_LAYERS=false
+HAS_README=false
+
+# Advisory warnings (non-blocking)
+ADVISORIES=""
+
+# Check for newly added files
+NEW_FILES=$(git diff --cached --diff-filter=A --name-only 2>/dev/null)
+if [ -n "$NEW_FILES" ]; then
+  # New files that aren't tests/configs/docs require tree updates
+  NON_TRIVIAL_NEW=$(echo "$NEW_FILES" | grep -E '\.(go|ts|tsx|sql|py|rs|js|jsx)$' | grep -v '_test\.\|\.test\.\|\.spec\.' || true)
+  if [ -n "$NON_TRIVIAL_NEW" ]; then
+    NEED_TREE_DOCS=true
+  fi
+fi
+
+while IFS= read -r file; do
+  # ── Non-architectural markdown — CANNOT satisfy architecture-doc requirements ──
+  # These files are meta-work (plans, memory, changelogs) and must NEVER be
+  # counted as evidence that architecture docs were updated. We continue early
+  # WITHOUT setting any HAS_* flag. Must be checked BEFORE the generic
+  # `docs/*|*.md` fallthrough below or the HAS_* pattern-name matches.
+  case "$file" in
+    docs/superpowers/plans/*|*/docs/superpowers/plans/*)
+      continue ;;
+    docs/superpowers/specs/*|*/docs/superpowers/specs/*)
+      continue ;;
+    docs/superpowers/research/*|*/docs/superpowers/research/*)
+      continue ;;
+    memory/*|*/memory/*)
+      continue ;;
+    CHANGELOG*|*/CHANGELOG*|*/HISTORY.md|HISTORY.md)
+      continue ;;
+    docs/active-plans-archive.md|*/docs/active-plans-archive.md)
+      continue ;;
+  esac
+
+  # ── Exempt file types (don't require docs) ──
+  case "$file" in
+    *_test.go|*test_*|*.test.ts|*.test.tsx|*.spec.ts|*.spec.tsx)
+      continue ;;
+    # Dependency files — check if NEW deps were added (not just version bumps)
+    go.mod|*/go.mod)
+      if git diff --cached -- "$file" 2>/dev/null | grep -qE '^\+\t[a-z].*v[0-9]' ; then
+        NEED_README=true
+        NEED_CLAUDE_MD=true
+      fi
+      continue ;;
+    package.json|*/package.json)
+      if git diff --cached -- "$file" 2>/dev/null | grep -qE '^\+.*"(dependencies|devDependencies)"' || \
+         git diff --cached -- "$file" 2>/dev/null | grep -qE '^\+\s+"[a-z@].*":' ; then
+        NEED_README=true
+      fi
+      continue ;;
+    # Config examples — README should document config changes
+    *config.example*|*config.sample*|*.env.example)
+      NEED_README=true
+      continue ;;
+    *.env*|*.json|*.yaml|*.yml|*.toml|*.cfg|*.ini)
+      # Exception: openapi.yaml counts as a doc
+      case "$file" in
+        *openapi*|*swagger*) HAS_OPENAPI=true ;;
+      esac
+      continue ;;
+    .claude/agents/*|.claude/rules/*|.claude/commands/*|.claude/hooks/*|.claude/skills/*|.claude/scripts/*)
+      ADVISORIES="${ADVISORIES}\n  [advisory] .claude/ config changed — consider syncing across repos if applicable"
+      continue ;;
+    # Detect staged doc files (generic glob patterns)
+    *database-schema*|*database_schema*) HAS_DB_SCHEMA=true; continue ;;
+    *api-reference*|*api_reference*|*backend-api*) HAS_API_REF=true; continue ;;
+    *frontend-state*|*frontend_state*) HAS_FRONTEND_STATE=true; continue ;;
+    *frontend-onboarding*|*frontend_onboarding*) HAS_FRONTEND_ONBOARDING=true; continue ;;
+    *bot-moderator*|*bot_moderator*) HAS_BOT_MOD=true; continue ;;
+    *bot-support*|*bot_support*) HAS_BOT_SUPPORT=true; continue ;;
+    *moderation-pipeline*|*moderation_pipeline*) HAS_MODERATION=true; continue ;;
+    *auth-and-sessions*|*auth_and_sessions*|*auth-sessions*) HAS_AUTH=true; continue ;;
+    *photo-pipeline*|*photo_pipeline*) HAS_PHOTO_DOCS=true; continue ;;
+    *feed-and-antiabuse*|*feed_antiabuse*|*feed-antiabuse*) HAS_FEED_DOCS=true; continue ;;
+    *entitlements-and-store*|*entitlements_store*|*entitlements-store*) HAS_ENTITLEMENTS_DOCS=true; continue ;;
+    *notification-system*|*notification_system*) HAS_NOTIFICATION_DOCS=true; continue ;;
+    *backend-layers*|*backend_layers*|*backend-arch*) HAS_BACKEND_LAYERS=true; continue ;;
+    docs/trees/*) HAS_TREE_DOCS=true; continue ;;
+    CLAUDE.md) HAS_CLAUDE_MD=true; continue ;;
+    README*|*/README*) HAS_README=true; continue ;;
+    docs/*|*.md|*openapi*|*swagger*) continue ;;
+  esac
+
+  # ── Code files — determine which docs are required ──
+  # Step 1: classify by extension (is it code at all?)
+  IS_CODE=false
+  case "$file" in
+    *.go|*.ts|*.tsx|*.js|*.jsx|*.py|*.rs|*.sql) IS_CODE=true ;;
+  esac
+
+  if [ "$IS_CODE" = false ]; then
+    continue
+  fi
+
+  HAS_CODE=true
+  ONLY_EXEMPT=false
+
+  # Step 2: determine doc requirements using grep-based in_dir() for any-depth matching
+  case "$file" in
+    # Migrations → database-schema docs + CLAUDE.md
+    */migrations/*.sql|*/migrate/*.sql|*/db/migrate/*)
+      NEED_DB_SCHEMA=true
+      NEED_CLAUDE_MD=true
+      ;;
+    *.sql) ;; # other SQL — no specific doc requirement
+  esac
+
+  case "$file" in
+    # HTTP handlers → API reference
+    */handlers/*.go|*/routes*.go|*/router*.go)
+      NEED_API_REF=true
+      ;;
+  esac
+
+  # Service-to-doc mappings (grep handles any nesting depth)
+  case "$file" in *.go)
+    if in_dir "$file" "services/moderation" || in_dir "$file" "service/moderation"; then
+      NEED_MODERATION_DOCS=true
+    elif in_dir "$file" "services/auth" || in_dir "$file" "service/auth"; then
+      NEED_AUTH_DOCS=true
+    elif in_dir "$file" "services/media" || in_dir "$file" "service/media"; then
+      NEED_PHOTO_DOCS=true
+    elif in_dir "$file" "services/feed" || in_dir "$file" "services/antiabuse" || in_dir "$file" "service/feed"; then
+      NEED_FEED_DOCS=true
+    elif in_dir "$file" "services/entitlements" || in_dir "$file" "services/store" || in_dir "$file" "services/payments"; then
+      NEED_ENTITLEMENTS_DOCS=true
+    elif in_dir "$file" "services/notifications" || in_dir "$file" "services/notification"; then
+      NEED_NOTIFICATION_DOCS=true
+    fi
+
+    # App wiring / middleware / background jobs / entry points → backend-layers docs.
+    # Tree docs only required if the file is NEW (added) — modifying existing
+    # middleware.go does not change the tree, so don't demand a tree update.
+    if in_dir "$file" "app" || echo "$file" | grep -q '/middleware' || \
+       in_dir "$file" "jobs" || in_dir "$file" "workers" || \
+       in_dir "$file" "cmd"; then
+      NEED_BACKEND_LAYERS=true
+      if echo "$NEW_FILES" | grep -qxF "$file"; then
+        NEED_TREE_DOCS=true
+      fi
+    fi
+
+    # New storage backend under */repo/** → tree docs (only for NEW files)
+    if in_dir "$file" "repo"; then
+      if echo "$NEW_FILES" | grep -qxF "$file"; then
+        NEED_TREE_DOCS=true
+      fi
+    fi
+
+    # Telegram bots → bot docs
+    if in_dir "$file" "bot_moderator" || in_dir "$file" "bot_support" || \
+       in_dir "$file" "tgbots" || in_dir "$file" "bots"; then
+      NEED_BOT_DOCS=true
+    fi
+    ;;
+  esac
+
+  # Frontend → frontend docs (any .ts/.tsx under src/ or onboarding paths)
+  case "$file" in *.ts|*.tsx)
+    if in_dir "$file" "src" || in_dir "$file" "pages/onboarding" || \
+       in_dir "$file" "app/flow" || echo "$file" | grep -q '/app/App\.tsx$'; then
+      NEED_FRONTEND_DOCS=true
+    fi
+    ;;
+  esac
+done <<< "$STAGED"
+
+# ── Skip if only exempt files (tests, configs, docs, .claude/) ─────
+if [ "$ONLY_EXEMPT" = true ] || [ "$HAS_CODE" = false ]; then
+  # Still print advisories if any
+  if [ -n "$ADVISORIES" ]; then
+    echo -e "$ADVISORIES"
+  fi
+  exit 0
+fi
+
+# ── Check each required doc category ──────────────────────────────────
+
+MISSING=""
+
+# Task 14: plan completion gate.
+# plan-completion-gate.sh places a marker when a superpowers plan skill
+# finishes. The next commit touching code MUST either stage
+# docs/architecture/* OR carry a [plan-docs-deferred: <id>: <reason>]
+# override. HAS_CODE is already true (we exited on line 272 otherwise).
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+SESSION_KEY="${SESSION_ID:-${CLAUDE_HOOK_PID:-$PPID}}"
+PLAN_MARKER="${TMPDIR:-/tmp}/claude-plan-docs-pending-${SESSION_KEY}"
+if [ -f "$PLAN_MARKER" ]; then
+  HAS_ARCH_DOC=false
+  while IFS= read -r f; do
+    case "$f" in
+      docs/architecture/*|*/docs/architecture/*) HAS_ARCH_DOC=true ;;
+    esac
+  done <<< "$STAGED"
+  HAS_DEFERRAL=$(echo "$COMMAND" | grep -oiE '\[plan-docs-deferred:[^]]{15,}\]' | head -1)
+
+  if [ "$HAS_ARCH_DOC" = false ] && [ -z "$HAS_DEFERRAL" ]; then
+    MISSING="${MISSING}\n  - Plan completion marker set but no docs/architecture/* file staged. Either stage an updated arch doc OR add [plan-docs-deferred: <plan-id>: <reason ≥15 chars>] to the commit message."
+  else
+    # marker satisfied — clear it so subsequent commits don't re-fire
+    rm -f "$PLAN_MARKER"
+  fi
+fi
+
+if [ "$NEED_DB_SCHEMA" = true ] && [ "$HAS_DB_SCHEMA" = false ]; then
+  MISSING="${MISSING}\n  - Migration staged but database schema docs NOT updated"
+fi
+
+if [ "$NEED_CLAUDE_MD" = true ] && [ "$HAS_CLAUDE_MD" = false ]; then
+  MISSING="${MISSING}\n  - Migration staged but CLAUDE.md NOT updated (migration counter)"
+fi
+
+if [ "$NEED_API_REF" = true ] && [ "$HAS_API_REF" = false ] && [ "$HAS_OPENAPI" = false ]; then
+  MISSING="${MISSING}\n  - Handler/route changed but neither API reference docs NOR OpenAPI spec updated"
+fi
+
+if [ "$NEED_FRONTEND_DOCS" = true ] && [ "$HAS_FRONTEND_STATE" = false ] && [ "$HAS_FRONTEND_ONBOARDING" = false ] && [ "$HAS_CLAUDE_MD" = false ]; then
+  MISSING="${MISSING}\n  - Frontend code changed but none of: frontend-state docs, frontend-onboarding docs, CLAUDE.md updated"
+fi
+
+if [ "$NEED_BOT_DOCS" = true ] && [ "$HAS_BOT_MOD" = false ] && [ "$HAS_BOT_SUPPORT" = false ] && [ "$HAS_CLAUDE_MD" = false ]; then
+  MISSING="${MISSING}\n  - Bot code changed but none of: bot-moderator docs, bot-support docs, CLAUDE.md updated"
+fi
+
+if [ "$NEED_MODERATION_DOCS" = true ] && [ "$HAS_MODERATION" = false ]; then
+  MISSING="${MISSING}\n  - Moderation service changed but moderation-pipeline docs NOT updated"
+fi
+
+if [ "$NEED_AUTH_DOCS" = true ] && [ "$HAS_AUTH" = false ]; then
+  MISSING="${MISSING}\n  - Auth service changed but auth-and-sessions docs NOT updated"
+fi
+
+if [ "$NEED_PHOTO_DOCS" = true ] && [ "$HAS_PHOTO_DOCS" = false ]; then
+  MISSING="${MISSING}\n  - Media service changed but photo-pipeline docs NOT updated"
+fi
+
+if [ "$NEED_FEED_DOCS" = true ] && [ "$HAS_FEED_DOCS" = false ]; then
+  MISSING="${MISSING}\n  - Feed/antiabuse service changed but feed-and-antiabuse docs NOT updated"
+fi
+
+if [ "$NEED_ENTITLEMENTS_DOCS" = true ] && [ "$HAS_ENTITLEMENTS_DOCS" = false ]; then
+  MISSING="${MISSING}\n  - Entitlements/store/payments service changed but entitlements-and-store docs NOT updated"
+fi
+
+if [ "$NEED_NOTIFICATION_DOCS" = true ] && [ "$HAS_NOTIFICATION_DOCS" = false ]; then
+  MISSING="${MISSING}\n  - Notifications service changed but notification-system docs NOT updated"
+fi
+
+if [ "$NEED_BACKEND_LAYERS" = true ] && [ "$HAS_BACKEND_LAYERS" = false ]; then
+  MISSING="${MISSING}\n  - App wiring/routes/middleware changed but backend-layers docs NOT updated"
+fi
+
+if [ "$NEED_TREE_DOCS" = true ] && [ "$HAS_TREE_DOCS" = false ]; then
+  MISSING="${MISSING}\n  - New files added but docs/trees/ NOT updated"
+fi
+
+if [ "$NEED_README" = true ] && [ "$HAS_README" = false ] && [ "$HAS_CLAUDE_MD" = false ]; then
+  MISSING="${MISSING}\n  - Dependencies or config changed but no README or CLAUDE.md updated (tech stack / project structure)"
+fi
+
+# ── Output result ─────────────────────────────────────────────────────
+
+if [ -n "$MISSING" ]; then
+  echo "" >&2
+  echo "BLOCKED: Required documentation not staged" >&2
+  echo "" >&2
+  echo -e "  Missing docs:${MISSING}" >&2
+  echo "" >&2
+  echo "  Fix: update the listed doc files and stage them before committing." >&2
+  echo "  If the change is a pure refactor with NO behavior change, stage" >&2
+  echo "  CLAUDE.md or a relevant .md file to acknowledge the check." >&2
+  echo "" >&2
+  if [ -n "$ADVISORIES" ]; then
+    echo -e "$ADVISORIES" >&2
+    echo "" >&2
+  fi
+  exit 2
+fi
+
+# Print advisories even on success (non-blocking warnings — still route to stderr so Claude Code surfaces them)
+if [ -n "$ADVISORIES" ]; then
+  echo -e "$ADVISORIES" >&2
+fi
+
+exit 0

package/packages/core/hooks/edit-streak-check.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# edit-streak-check.sh — detect 5+ edits without a verification run
+# Triggers on: PostToolUse(Edit|Write|MultiEdit|Bash)
+# Profile: standard, strict
+#
+# Pattern caught: Claude edits 5+ files in a row without running tests,
+# linters, or any Bash command between edits — a classic "progress stall"
+# signal where changes accumulate without verification.
+#
+# Advisory only (exit 0 with stderr warning). Reset on any Bash call.
+# Opt-out: CLAUDE_DISABLE_EDIT_STREAK=1
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+[ "${CLAUDE_DISABLE_EDIT_STREAK:-}" = "1" ] && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ -z "$TOOL_NAME" ] && exit 0
+
+SESSION_KEY=$(command -v superkit_session_key >/dev/null 2>&1 && superkit_session_key || printf '%s' "${SESSION_ID:-${CLAUDE_HOOK_PID:-$PPID}}")
+STREAK_FILE="${CLAUDE_EDIT_STREAK_FILE:-${TMPDIR:-/tmp}/claude-edit-streak-${SESSION_KEY}}"
+
+case "$TOOL_NAME" in
+  Bash)
+    # Any Bash call resets the streak — it counts as verification
+    rm -f "$STREAK_FILE"
+    exit 0
+    ;;
+  Edit|Write|MultiEdit)
+    count=$(cat "$STREAK_FILE" 2>/dev/null || echo 0)
+    count=$((count + 1))
+    echo "$count" > "$STREAK_FILE"
+
+    if [ "$count" -ge 5 ]; then
+      # Per-session throttle (Opus 4.8 self-flags). Key on a stable string
+      # (NOT the changing $count) so the same nudge isn't repeated every edit
+      # within the window. CLAUDE_NUDGE_WINDOW_MIN=0 disables throttling.
+      EMIT=1
+      if command -v superkit_should_emit_advisory >/dev/null 2>&1; then
+        superkit_should_emit_advisory "edit-streak-check: consecutive edits without verification" || EMIT=0
+      fi
+      if [ "$EMIT" = "1" ]; then
+        echo "" >&2
+        echo "⚠️  WARNING: edit streak — $count consecutive edits without a verification run." >&2
+        echo "   Consider running: tests, lint, build, or any Bash command." >&2
+        echo "   Set CLAUDE_DISABLE_EDIT_STREAK=1 to silence." >&2
+        echo "" >&2
+      fi
+    fi
+    ;;
+esac
+
+exit 0

package/packages/core/hooks/evolve-check.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+# evolve-check.sh — advisory check for documentation drift at session start
+# Triggers on: SessionStart
+# Profile: standard, strict
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ]; then
+  exit 0
+fi
+
+# Only check if superkit is installed
+if [ ! -f ".claude/commands/superkit-evolve.md" ] 2>/dev/null; then
+  exit 0
+fi
+
+# Rate limit: check at most once per 24h
+LAST_CHECK_FILE="$HOME/.claude/.superkit-evolve-last-check"
+NOW=$(date +%s)
+LAST=$(cat "$LAST_CHECK_FILE" 2>/dev/null || echo "0")
+DIFF=$((NOW - LAST))
+
+if [ "$DIFF" -lt 86400 ]; then
+  exit 0
+fi
+
+echo "$NOW" > "$LAST_CHECK_FILE"
+
+ISSUES=()
+
+# Check 1: Migration counter drift
+if [ -f "CLAUDE.md" ]; then
+  ACTUAL_MIGRATIONS=$(find . -path "*/migrations/*.up.sql" 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$ACTUAL_MIGRATIONS" -gt 0 ]; then
+    CLAIMED=$(grep -oE '000001\.\.[0-9]+' CLAUDE.md 2>/dev/null | grep -oE '[0-9]+$' | tr -d '0' | head -1)
+    if [ -n "$CLAIMED" ] && [ "$ACTUAL_MIGRATIONS" != "$CLAIMED" ]; then
+      ISSUES+=("Migration counter drift (CLAUDE.md: $CLAIMED, actual: $ACTUAL_MIGRATIONS)")
+    fi
+  fi
+fi
+
+# Check 2: Tree freshness (>20 new files since tree generation)
+if [ -d "docs/trees" ]; then
+  NEWEST_TREE=$(find docs/trees -name "*.md" -newer docs/trees -print -quit 2>/dev/null)
+  NEW_FILES=$(find . \( -name "*.go" -o -name "*.ts" -o -name "*.py" -o -name "*.rs" \) -newer docs/trees/ 2>/dev/null | grep -v node_modules | grep -v vendor | wc -l | tr -d ' ')
+  if [ "$NEW_FILES" -gt 20 ]; then
+    ISSUES+=("$NEW_FILES new code files since last tree generation")
+  fi
+fi
+
+# Check 3: Missing docs for detected components
+for dir in backend frontend adminpanel workers bots services; do
+  if [ -d "$dir" ] && [ ! -f "docs/architecture/${dir}-layers.md" ] && [ ! -f "docs/architecture/${dir}.md" ]; then
+    FILE_COUNT=$(find "$dir" \( -name "*.go" -o -name "*.ts" -o -name "*.py" \) 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$FILE_COUNT" -gt 5 ]; then
+      ISSUES+=("$dir/ has $FILE_COUNT code files but no architecture doc")
+    fi
+  fi
+done
+
+# Report
+if [ ${#ISSUES[@]} -gt 0 ]; then
+  echo ""
+  echo "⚠ superkit-evolve: detected ${#ISSUES[@]} documentation issues:"
+  for issue in "${ISSUES[@]}"; do
+    echo "  · $issue"
+  done
+  echo ""
+  echo "  Run /superkit-evolve to fix, or ignore if not needed."
+  echo ""
+fi
+
+exit 0