@slamb2k/mad-skills 2.0.7 → 2.0.8

package/hooks/session-guard.sh

@@ -1,22 +1,19 @@
 #!/usr/bin/env bash
 # session-guard.sh — Claude Code SessionStart hook
-# Validates Git repo, CLAUDE.md existence/freshness, and checks for staleness.
+# Validates Git repo, CLAUDE.md existence/freshness, Task List ID config,
+# and checks for staleness.
 #
-# Install: Add to ~/.claude/settings.json or .claude/settings.json:
-# {
-#   "hooks": {
-#     "SessionStart": [
-#       {
-#         "hooks": [
-#           {
-#             "type": "command",
-#             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-guard.sh"
-#           }
-#         ]
-#       }
-#     ]
-#   }
-# }
+# All user-facing questions instruct Claude to use the AskUserQuestion tool.
+#
+# Install globally in ~/.claude/settings.json:
+#   "command": "\"$HOME\"/.claude/hooks/session-guard.sh"
+#
+# Or per-project in .claude/settings.json:
+#   "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-guard.sh"
+#
+# TIMING NOTE: SessionStart hook output is silently injected and only surfaces
+# on the user's first prompt. Pair with session-guard-prompt.sh on
+# UserPromptSubmit for immediate feedback (see companion hook).
 
 # NOTE: We intentionally avoid `set -e` here. Many commands (grep, git, find,
 # jq, stat) return non-zero for perfectly normal reasons (no matches, not a
@@ -31,11 +28,12 @@ PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
 CLAUDE_MD="$PROJECT_DIR/CLAUDE.md"
 NOW=$(date +%s)
 STALENESS_THRESHOLD=3   # Accumulated score >= this triggers user prompt
+PENDING_DIR="${TMPDIR:-/tmp}/claude-session-guard"
 
 # ---------------------------------------------------------------------------
 # State
 # ---------------------------------------------------------------------------
-EARLY_CONTEXT_PARTS=()  # Git/CLAUDE.md warnings (emitted before staleness)
+EARLY_CONTEXT_PARTS=()
 STALENESS_SIGNALS=()
 STALENESS_SCORE=0
 
@@ -51,6 +49,22 @@ file_mtime() {
   stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null || echo "$NOW"
 }
 
+# ---------------------------------------------------------------------------
+# Dedup: prevent double-firing if configured at both global and project level
+# ---------------------------------------------------------------------------
+mkdir -p "$PENDING_DIR"
+GUARD_KEY=$(echo "$PROJECT_DIR" | md5sum 2>/dev/null | cut -d' ' -f1 || echo "default")
+LOCK_FILE="$PENDING_DIR/$GUARD_KEY.lock"
+
+if [[ -f "$LOCK_FILE" ]]; then
+  LOCK_AGE=$(( NOW - $(file_mtime "$LOCK_FILE") ))
+  if (( LOCK_AGE < 5 )); then
+    jq -n '{}'
+    exit 0
+  fi
+fi
+touch "$LOCK_FILE"
+
 # ---------------------------------------------------------------------------
 # 0) Git repository check
 # ---------------------------------------------------------------------------
@@ -60,24 +74,17 @@ if command -v git &>/dev/null; then
   GIT_ROOT=$(git -C "$PROJECT_DIR" rev-parse --show-toplevel 2>/dev/null) || true
 
   if [[ -z "$GIT_ROOT" ]]; then
-    # ---- Not inside any git repository ----------------------------------
     EARLY_CONTEXT_PARTS+=("[SESSION GUARD] ⚠️  This directory is NOT tracked by Git.")
     EARLY_CONTEXT_PARTS+=("")
-    EARLY_CONTEXT_PARTS+=("Please ask the user:")
-    EARLY_CONTEXT_PARTS+=("")
-    EARLY_CONTEXT_PARTS+=("\"This directory isn't inside a Git repository. Would you like me to:")
-    EARLY_CONTEXT_PARTS+=("")
-    EARLY_CONTEXT_PARTS+=("1. **Initialise Git** — I'll run \`git init\` to start tracking this project")
-    EARLY_CONTEXT_PARTS+=("2. **Skip** — Continue without version control")
-    EARLY_CONTEXT_PARTS+=("")
-    EARLY_CONTEXT_PARTS+=("What would you prefer?\"")
-    EARLY_CONTEXT_PARTS+=("")
-    EARLY_CONTEXT_PARTS+=("If the user chooses to initialise, run \`git init\` in the project directory, then suggest creating a .gitignore if one doesn't exist.")
-    EARLY_CONTEXT_PARTS+=("If the user chooses to skip, continue normally.")
+    EARLY_CONTEXT_PARTS+=("Use AskUserQuestion to prompt:")
+    EARLY_CONTEXT_PARTS+=("  Question: \"This directory isn't inside a Git repository. What would you like to do?\"")
+    EARLY_CONTEXT_PARTS+=("  Type: single_select")
+    EARLY_CONTEXT_PARTS+=("  Options:")
+    EARLY_CONTEXT_PARTS+=("    1. \"Initialise Git\" — run \`git init\` and suggest creating .gitignore")
+    EARLY_CONTEXT_PARTS+=("    2. \"Skip\" — continue without version control")
     EARLY_CONTEXT_PARTS+=("")
 
   elif [[ "$GIT_ROOT" != "$PROJECT_DIR" ]]; then
-    # ---- Git root is an ancestor folder ---------------------------------
     DEPTH=0
     CHECK_DIR="$PROJECT_DIR"
     while [[ "$CHECK_DIR" != "$GIT_ROOT" && "$CHECK_DIR" != "/" ]]; do
@@ -85,14 +92,11 @@ if command -v git &>/dev/null; then
       DEPTH=$((DEPTH + 1))
     done
 
-    # Gather monorepo signals at the git root
     MONOREPO_SIGNALS=()
 
-    # Workspace configs
     if [[ -f "$GIT_ROOT/package.json" ]] && command -v jq &>/dev/null; then
-      if jq -e '.workspaces // empty' "$GIT_ROOT/package.json" &>/dev/null; then
+      jq -e '.workspaces // empty' "$GIT_ROOT/package.json" &>/dev/null && \
         MONOREPO_SIGNALS+=("package.json has 'workspaces' field")
-      fi
     fi
     [[ -f "$GIT_ROOT/pnpm-workspace.yaml" ]] && MONOREPO_SIGNALS+=("pnpm-workspace.yaml exists")
     [[ -f "$GIT_ROOT/lerna.json" ]]          && MONOREPO_SIGNALS+=("lerna.json exists")
@@ -100,98 +104,69 @@ if command -v git &>/dev/null; then
     [[ -f "$GIT_ROOT/turbo.json" ]]          && MONOREPO_SIGNALS+=("turbo.json exists")
     [[ -f "$GIT_ROOT/rush.json" ]]           && MONOREPO_SIGNALS+=("rush.json exists")
 
-    # Common monorepo directory patterns
     for d in packages apps services libs modules projects; do
       [[ -d "$GIT_ROOT/$d" ]] && MONOREPO_SIGNALS+=("'$d/' directory exists at git root")
     done
 
-    # Multiple package.json files (strong monorepo indicator)
     PKG_COUNT=$(find "$GIT_ROOT" -maxdepth 3 -name "package.json" -not -path "*/node_modules/*" 2>/dev/null | wc -l | tr -d ' ')
-    (( PKG_COUNT > 2 )) && MONOREPO_SIGNALS+=("${PKG_COUNT} package.json files found within the repo")
+    (( PKG_COUNT > 2 )) && MONOREPO_SIGNALS+=("${PKG_COUNT} package.json files found")
 
-    # Multiple CLAUDE.md files (intentional per-package setup)
     CLAUDE_MD_COUNT=$(find "$GIT_ROOT" -maxdepth 3 -name "CLAUDE.md" 2>/dev/null | wc -l | tr -d ' ')
-    (( CLAUDE_MD_COUNT > 1 )) && MONOREPO_SIGNALS+=("${CLAUDE_MD_COUNT} CLAUDE.md files found (suggests per-package setup)")
+    (( CLAUDE_MD_COUNT > 1 )) && MONOREPO_SIGNALS+=("${CLAUDE_MD_COUNT} CLAUDE.md files found (per-package setup)")
 
     RELATIVE_PATH="${PROJECT_DIR#"$GIT_ROOT/"}"
 
     if (( ${#MONOREPO_SIGNALS[@]} >= 2 )); then
-      # ---- Likely a legitimate monorepo ---------------------------------
-      EARLY_CONTEXT_PARTS+=("[SESSION GUARD] ℹ️  Git root is ${DEPTH} level(s) above the current directory.")
+      EARLY_CONTEXT_PARTS+=("[SESSION GUARD] ℹ️  Git root is ${DEPTH} level(s) above CWD.")
       EARLY_CONTEXT_PARTS+=("  Git root:    $GIT_ROOT")
       EARLY_CONTEXT_PARTS+=("  Working dir: $PROJECT_DIR")
+      EARLY_CONTEXT_PARTS+=("  Monorepo signals: ${MONOREPO_SIGNALS[*]}")
       EARLY_CONTEXT_PARTS+=("")
-      EARLY_CONTEXT_PARTS+=("This appears to be a **monorepo** based on these signals:")
-      for sig in "${MONOREPO_SIGNALS[@]}"; do
-        EARLY_CONTEXT_PARTS+=("  • $sig")
-      done
-      EARLY_CONTEXT_PARTS+=("")
-      EARLY_CONTEXT_PARTS+=("Briefly let the user know:")
-      EARLY_CONTEXT_PARTS+=("")
-      EARLY_CONTEXT_PARTS+=("\"I notice the Git repository root is at \`$GIT_ROOT\`, which looks like a monorepo. I'm working in the \`${RELATIVE_PATH}\` package. Just confirming — is this the right context, or did you mean to open Claude Code at the repo root?\"")
-      EARLY_CONTEXT_PARTS+=("")
-      EARLY_CONTEXT_PARTS+=("This is a low-priority confirmation — don't block on it. Continue with the session regardless.")
+      EARLY_CONTEXT_PARTS+=("Use AskUserQuestion (low priority, don't block):")
+      EARLY_CONTEXT_PARTS+=("  Question: \"Git root is at \`$GIT_ROOT\` (monorepo). Working in \`${RELATIVE_PATH}\`. Correct context?\"")
+      EARLY_CONTEXT_PARTS+=("  Type: single_select")
+      EARLY_CONTEXT_PARTS+=("  Options:")
+      EARLY_CONTEXT_PARTS+=("    1. \"Yes, correct package\"")
+      EARLY_CONTEXT_PARTS+=("    2. \"No, switch to repo root\"")
       EARLY_CONTEXT_PARTS+=("")
 
     else
-      # ---- Ancestor may be incorrectly initialised ----------------------
       GIT_ROOT_FILE_COUNT=$(find "$GIT_ROOT" -maxdepth 1 -not -name '.*' 2>/dev/null | wc -l | tr -d ' ')
 
-      EARLY_CONTEXT_PARTS+=("[SESSION GUARD] ⚠️  Git root is ${DEPTH} level(s) above the current directory and does NOT look like a monorepo.")
-      EARLY_CONTEXT_PARTS+=("  Git root:    $GIT_ROOT")
+      EARLY_CONTEXT_PARTS+=("[SESSION GUARD] ⚠️  Git root is ${DEPTH} level(s) above CWD — does NOT look like a monorepo.")
+      EARLY_CONTEXT_PARTS+=("  Git root:    $GIT_ROOT (${GIT_ROOT_FILE_COUNT} files)")
       EARLY_CONTEXT_PARTS+=("  Working dir: $PROJECT_DIR")
-      EARLY_CONTEXT_PARTS+=("  Files at git root: ~${GIT_ROOT_FILE_COUNT}")
-      EARLY_CONTEXT_PARTS+=("")
-
       if (( ${#MONOREPO_SIGNALS[@]} > 0 )); then
-        EARLY_CONTEXT_PARTS+=("Weak signals found (not enough for monorepo classification):")
-        for sig in "${MONOREPO_SIGNALS[@]}"; do
-          EARLY_CONTEXT_PARTS+=("  • $sig")
-        done
-        EARLY_CONTEXT_PARTS+=("")
+        EARLY_CONTEXT_PARTS+=("  Weak signals: ${MONOREPO_SIGNALS[*]}")
       fi
-
-      EARLY_CONTEXT_PARTS+=("This may indicate that an ancestor directory was accidentally initialised with \`git init\`.")
-      EARLY_CONTEXT_PARTS+=("")
-      EARLY_CONTEXT_PARTS+=("Please ask the user:")
       EARLY_CONTEXT_PARTS+=("")
-      EARLY_CONTEXT_PARTS+=("\"I notice the Git repository root is at \`$GIT_ROOT\`, which is ${DEPTH} level(s) above your current working directory. This doesn't look like a monorepo setup, so the Git repo at that level may have been created accidentally.")
-      EARLY_CONTEXT_PARTS+=("")
-      EARLY_CONTEXT_PARTS+=("A few options:")
-      EARLY_CONTEXT_PARTS+=("1. **It's correct** — The repo root at \`$GIT_ROOT\` is intentional, carry on")
-      EARLY_CONTEXT_PARTS+=("2. **Initialise here instead** — I'll run \`git init\` in this directory to create a separate repo")
-      EARLY_CONTEXT_PARTS+=("3. **Investigate** — I'll look at the git root structure to help you decide")
-      EARLY_CONTEXT_PARTS+=("")
-      EARLY_CONTEXT_PARTS+=("What would you prefer?\"")
-      EARLY_CONTEXT_PARTS+=("")
-      EARLY_CONTEXT_PARTS+=("If 'correct': continue normally.")
-      EARLY_CONTEXT_PARTS+=("If 'initialise here': run \`git init\` in the project directory. Warn the user that the ancestor .git will still exist and they may want to remove it later.")
-      EARLY_CONTEXT_PARTS+=("If 'investigate': list the git root contents and recent commits to help the user understand what's tracked.")
+      EARLY_CONTEXT_PARTS+=("Use AskUserQuestion to resolve:")
+      EARLY_CONTEXT_PARTS+=("  Question: \"Git root is at \`$GIT_ROOT\` (${DEPTH} levels up), which doesn't look like a monorepo. May have been created accidentally.\"")
+      EARLY_CONTEXT_PARTS+=("  Type: single_select")
+      EARLY_CONTEXT_PARTS+=("  Options:")
+      EARLY_CONTEXT_PARTS+=("    1. \"It's correct\" — continue normally")
+      EARLY_CONTEXT_PARTS+=("    2. \"Initialise here instead\" — run \`git init\` here (warn ancestor .git still exists)")
+      EARLY_CONTEXT_PARTS+=("    3. \"Investigate\" — list git root contents and recent commits")
       EARLY_CONTEXT_PARTS+=("")
     fi
   fi
-  # else: GIT_ROOT == PROJECT_DIR — all good, no action needed
 fi
 
 # ---------------------------------------------------------------------------
 # 1) CLAUDE.md existence check
 # ---------------------------------------------------------------------------
 if [[ ! -f "$CLAUDE_MD" ]]; then
-  EARLY_CONTEXT_PARTS+=("[SESSION GUARD] No CLAUDE.md was found in the project root.")
-  EARLY_CONTEXT_PARTS+=("")
-  EARLY_CONTEXT_PARTS+=("This directory has not been initialised for Claude Code. Please ask the user:")
-  EARLY_CONTEXT_PARTS+=("")
-  EARLY_CONTEXT_PARTS+=("\"I notice this directory doesn't have a CLAUDE.md file, so it isn't set up as a Claude Code project yet. Would you like me to:")
-  EARLY_CONTEXT_PARTS+=("")
-  EARLY_CONTEXT_PARTS+=("1. **Initialise it** — I'll run \`/init\` to scaffold a CLAUDE.md with project context")
-  EARLY_CONTEXT_PARTS+=("2. **Skip for now** — Continue without one (you may lose project-specific context)")
+  EARLY_CONTEXT_PARTS+=("[SESSION GUARD] ⚠️  No CLAUDE.md found in project root.")
   EARLY_CONTEXT_PARTS+=("")
-  EARLY_CONTEXT_PARTS+=("What would you prefer?\"")
+  EARLY_CONTEXT_PARTS+=("Use AskUserQuestion to prompt:")
+  EARLY_CONTEXT_PARTS+=("  Question: \"No CLAUDE.md found. Want me to set up this project for Claude Code?\"")
+  EARLY_CONTEXT_PARTS+=("  Type: single_select")
+  EARLY_CONTEXT_PARTS+=("  Options:")
+  EARLY_CONTEXT_PARTS+=("    1. \"Initialise\" — run \`/init\` to scaffold CLAUDE.md")
+  EARLY_CONTEXT_PARTS+=("    2. \"Skip\" — continue without one")
   EARLY_CONTEXT_PARTS+=("")
-  EARLY_CONTEXT_PARTS+=("If the user chooses to initialise, run the /init slash command.")
-  EARLY_CONTEXT_PARTS+=("If the user chooses to skip, continue normally.")
 
-  # Emit everything collected (git warnings + CLAUDE.md missing) and exit
+  # Emit and write pending flag, then exit early
   CONTEXT=$(printf '%s\n' "${EARLY_CONTEXT_PARTS[@]}")
   jq -n --arg ctx "$CONTEXT" '{
     hookSpecificOutput: {
@@ -199,98 +174,126 @@ if [[ ! -f "$CLAUDE_MD" ]]; then
       additionalContext: $ctx
     }
   }'
+  PENDING_FILE="$PENDING_DIR/$GUARD_KEY.pending"
+  echo "$CONTEXT" > "$PENDING_FILE"
   exit 0
 fi
 
 # ---------------------------------------------------------------------------
-# 2) Staleness evaluation
+# 2) Task List ID check
+# ---------------------------------------------------------------------------
+TASK_LIST_CONFIGURED=false
+SETTINGS_FILE="$PROJECT_DIR/.claude/settings.json"
+
+[[ -n "${CLAUDE_CODE_TASK_LIST_ID:-}" ]] && TASK_LIST_CONFIGURED=true
+
+if [[ "$TASK_LIST_CONFIGURED" == false ]] && command -v jq &>/dev/null; then
+  for CFG_FILE in "$SETTINGS_FILE" "$HOME/.claude/settings.json"; do
+    if [[ -f "$CFG_FILE" ]]; then
+      TASK_ID=$(jq -r '.env.CLAUDE_CODE_TASK_LIST_ID // empty' "$CFG_FILE" 2>/dev/null) || true
+      if [[ -n "$TASK_ID" ]]; then
+        TASK_LIST_CONFIGURED=true
+        break
+      fi
+    fi
+  done
+fi
+
+if [[ "$TASK_LIST_CONFIGURED" == false && -n "$GIT_ROOT" ]]; then
+  COMMIT_COUNT=$(git -C "$PROJECT_DIR" rev-list --count HEAD 2>/dev/null) || COMMIT_COUNT=0
+  FILE_COUNT=$(git -C "$PROJECT_DIR" ls-files 2>/dev/null | wc -l | tr -d ' ') || FILE_COUNT=0
+
+  if (( COMMIT_COUNT > 20 || FILE_COUNT > 30 )); then
+    REPO_NAME=$(basename "$GIT_ROOT")
+    EARLY_CONTEXT_PARTS+=("[SESSION GUARD] ℹ️  No persistent Task List ID configured.")
+    EARLY_CONTEXT_PARTS+=("  Project: ${COMMIT_COUNT} commits, ${FILE_COUNT} tracked files.")
+    EARLY_CONTEXT_PARTS+=("")
+    EARLY_CONTEXT_PARTS+=("Use AskUserQuestion (low priority, don't block):")
+    EARLY_CONTEXT_PARTS+=("  Question: \"No persistent Task List ID configured. For a project this size, tasks won't survive across sessions. Add one?\"")
+    EARLY_CONTEXT_PARTS+=("  Type: single_select")
+    EARLY_CONTEXT_PARTS+=("  Options:")
+    EARLY_CONTEXT_PARTS+=("    1. \"Yes\" — add {\"env\": {\"CLAUDE_CODE_TASK_LIST_ID\": \"${REPO_NAME}\"}} to .claude/settings.json")
+    EARLY_CONTEXT_PARTS+=("    2. \"Skip\" — continue without persistent tasks")
+    EARLY_CONTEXT_PARTS+=("")
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# 3) Staleness evaluation
 # ---------------------------------------------------------------------------
 CLAUDE_MD_MTIME=$(file_mtime "$CLAUDE_MD")
 CLAUDE_MD_AGE_DAYS=$(( (NOW - CLAUDE_MD_MTIME) / 86400 ))
-CLAUDE_MD_CONTENT=$(cat "$CLAUDE_MD")
 
-# --- 3a) Age-based check ---------------------------------------------------
+# --- Age-based --------------------------------------------------------------
 if (( CLAUDE_MD_AGE_DAYS > 14 )); then
-  add_staleness "CLAUDE.md was last modified ${CLAUDE_MD_AGE_DAYS} days ago" 2
+  add_staleness "CLAUDE.md last modified ${CLAUDE_MD_AGE_DAYS} days ago" 2
 elif (( CLAUDE_MD_AGE_DAYS > 7 )); then
-  add_staleness "CLAUDE.md was last modified ${CLAUDE_MD_AGE_DAYS} days ago" 1
+  add_staleness "CLAUDE.md last modified ${CLAUDE_MD_AGE_DAYS} days ago" 1
 fi
 
-# --- 3b) Directory structure drift ------------------------------------------
+# --- Directory structure drift ----------------------------------------------
 if command -v tree &>/dev/null; then
   CURRENT_TREE=$(tree -L 2 -d -I 'node_modules|.git|__pycache__|.venv|venv|dist|build|.next|.nuxt|coverage|.claude' --noreport "$PROJECT_DIR" 2>/dev/null) || true
   if [[ -n "$CURRENT_TREE" ]]; then
-    # Strip box-drawing characters, pipes, dashes, whitespace to get clean dir names
     TREE_DIRS=$(echo "$CURRENT_TREE" | tail -n +2 \
       | sed 's/[│├└─┬┤┼┐┘┌┏┗┓┛]//g; s/[|`]//g; s/--*//g' \
       | sed 's/^[[:space:]]*//' | { grep -v '^$' || true; } | sort -u)
     MISSING_DIRS=()
     while IFS= read -r dir; do
       [[ -z "$dir" ]] && continue
-      if ! grep -qi "$dir" "$CLAUDE_MD" 2>/dev/null; then
-        MISSING_DIRS+=("$dir")
-      fi
+      grep -qi "$dir" "$CLAUDE_MD" 2>/dev/null || MISSING_DIRS+=("$dir")
     done <<< "$TREE_DIRS"
     if (( ${#MISSING_DIRS[@]} > 2 )); then
-      add_staleness "Directories not mentioned in CLAUDE.md: ${MISSING_DIRS[*]}" 2
+      add_staleness "Directories not in CLAUDE.md: ${MISSING_DIRS[*]}" 2
     elif (( ${#MISSING_DIRS[@]} > 0 )); then
-      add_staleness "Directories not mentioned in CLAUDE.md: ${MISSING_DIRS[*]}" 1
+      add_staleness "Directories not in CLAUDE.md: ${MISSING_DIRS[*]}" 1
     fi
   fi
 fi
 
-# --- 3c) package.json dependency drift --------------------------------------
+# --- package.json drift -----------------------------------------------------
 if [[ -f "$PROJECT_DIR/package.json" ]]; then
   PKG_MTIME=$(file_mtime "$PROJECT_DIR/package.json")
 
-  # Check if package.json is newer than CLAUDE.md
   if (( PKG_MTIME > CLAUDE_MD_MTIME )); then
     PKG_DELTA=$(( (PKG_MTIME - CLAUDE_MD_MTIME) / 86400 ))
-    add_staleness "package.json was modified ${PKG_DELTA} day(s) after CLAUDE.md" 1
+    add_staleness "package.json modified ${PKG_DELTA} day(s) after CLAUDE.md" 1
   fi
 
-  # Count dependencies vs what's documented
   if command -v jq &>/dev/null; then
     DEP_COUNT=$(jq '[(.dependencies // {} | length), (.devDependencies // {} | length)] | add' "$PROJECT_DIR/package.json" 2>/dev/null) || DEP_COUNT="0"
-    # Look for numbers near "dependenc" in CLAUDE.md (e.g. "23 dependencies")
     DOCUMENTED_COUNT=$(grep -oiP '\d+\s*(dependencies|deps)' "$CLAUDE_MD" 2>/dev/null | head -1 | grep -oP '\d+') || true
     if [[ -n "$DOCUMENTED_COUNT" && -n "$DEP_COUNT" ]]; then
       DRIFT=$(( DEP_COUNT - DOCUMENTED_COUNT ))
       DRIFT_ABS=${DRIFT#-}
       if (( DRIFT_ABS > 5 )); then
-        add_staleness "Dependency count drifted: CLAUDE.md says ~${DOCUMENTED_COUNT}, actual is ${DEP_COUNT} (Δ${DRIFT})" 2
+        add_staleness "Dep count drift: CLAUDE.md ~${DOCUMENTED_COUNT}, actual ${DEP_COUNT} (Δ${DRIFT})" 2
       elif (( DRIFT_ABS > 0 )); then
-        add_staleness "Dependency count drifted slightly: CLAUDE.md says ~${DOCUMENTED_COUNT}, actual is ${DEP_COUNT}" 1
+        add_staleness "Dep count drift: CLAUDE.md ~${DOCUMENTED_COUNT}, actual ${DEP_COUNT}" 1
       fi
     fi
 
-    # Check for key dependencies not documented
     KEY_DEPS=$(jq -r '(.dependencies // {}) | keys[]' "$PROJECT_DIR/package.json" 2>/dev/null) || true
-    UNDOCUMENTED_KEY_DEPS=()
+    UNDOCUMENTED=()
     while IFS= read -r dep; do
       [[ -z "$dep" ]] && continue
-      if ! grep -qi "$dep" "$CLAUDE_MD" 2>/dev/null; then
-        UNDOCUMENTED_KEY_DEPS+=("$dep")
-      fi
+      grep -qi "$dep" "$CLAUDE_MD" 2>/dev/null || UNDOCUMENTED+=("$dep")
     done <<< "$KEY_DEPS"
-    if (( ${#UNDOCUMENTED_KEY_DEPS[@]} > 5 )); then
-      SAMPLE="${UNDOCUMENTED_KEY_DEPS[*]:0:5}"
-      add_staleness "Multiple production deps not in CLAUDE.md (${#UNDOCUMENTED_KEY_DEPS[@]} total, e.g. ${SAMPLE})" 2
+    if (( ${#UNDOCUMENTED[@]} > 5 )); then
+      add_staleness "${#UNDOCUMENTED[@]} production deps not in CLAUDE.md (e.g. ${UNDOCUMENTED[*]:0:5})" 2
     fi
   fi
 fi
 
-# --- 3d) pyproject.toml / requirements.txt drift ----------------------------
+# --- Python dependency drift ------------------------------------------------
 for PYFILE in "$PROJECT_DIR/pyproject.toml" "$PROJECT_DIR/requirements.txt" "$PROJECT_DIR/setup.py"; do
   if [[ -f "$PYFILE" ]]; then
     PY_MTIME=$(file_mtime "$PYFILE")
-    if (( PY_MTIME > CLAUDE_MD_MTIME )); then
-      add_staleness "$(basename "$PYFILE") was modified after CLAUDE.md" 1
-    fi
+    (( PY_MTIME > CLAUDE_MD_MTIME )) && add_staleness "$(basename "$PYFILE") modified after CLAUDE.md" 1
   fi
 done
 
-# --- 3e) Key config files newer than CLAUDE.md ------------------------------
+# --- Key config files -------------------------------------------------------
 for CFG in "$PROJECT_DIR/tsconfig.json" \
            "$PROJECT_DIR/.env.example" \
            "$PROJECT_DIR/docker-compose.yml" \
@@ -300,15 +303,12 @@ for CFG in "$PROJECT_DIR/tsconfig.json" \
            "$PROJECT_DIR/go.mod"; do
   if [[ -f "$CFG" ]]; then
     CFG_MTIME=$(file_mtime "$CFG")
-    if (( CFG_MTIME > CLAUDE_MD_MTIME )); then
-      add_staleness "$(basename "$CFG") modified after CLAUDE.md" 1
-    fi
+    (( CFG_MTIME > CLAUDE_MD_MTIME )) && add_staleness "$(basename "$CFG") modified after CLAUDE.md" 1
   fi
 done
 
-# --- 3f) Git-based checks ---------------------------------------------------
+# --- Git-based checks -------------------------------------------------------
 if command -v git &>/dev/null && [[ -n "$GIT_ROOT" ]]; then
-  # Convert CLAUDE.md mtime to ISO date for git
   CLAUDE_MD_DATE=$(date -d "@$CLAUDE_MD_MTIME" --iso-8601=seconds 2>/dev/null) \
     || CLAUDE_MD_DATE=$(date -r "$CLAUDE_MD_MTIME" +%Y-%m-%dT%H:%M:%S 2>/dev/null) \
     || CLAUDE_MD_DATE=""
@@ -316,24 +316,21 @@ if command -v git &>/dev/null && [[ -n "$GIT_ROOT" ]]; then
   if [[ -n "$CLAUDE_MD_DATE" ]]; then
     COMMITS_SINCE=$(git -C "$PROJECT_DIR" rev-list --count --since="$CLAUDE_MD_DATE" HEAD 2>/dev/null) || COMMITS_SINCE="0"
     if (( COMMITS_SINCE > 50 )); then
-      add_staleness "${COMMITS_SINCE} commits since CLAUDE.md was last updated" 2
+      add_staleness "${COMMITS_SINCE} commits since CLAUDE.md updated" 2
     elif (( COMMITS_SINCE > 20 )); then
-      add_staleness "${COMMITS_SINCE} commits since CLAUDE.md was last updated" 1
+      add_staleness "${COMMITS_SINCE} commits since CLAUDE.md updated" 1
     fi
 
-    # Check for structural file additions/deletions
     CHANGED_FILES=$(git -C "$PROJECT_DIR" diff --name-only --diff-filter=AD HEAD~20..HEAD 2>/dev/null | head -20) || true
     NEW_TOP_LEVEL=$(echo "$CHANGED_FILES" | { grep -v '/' || true; } | { grep -v '^\.' || true; } | sort -u)
     if [[ -n "$NEW_TOP_LEVEL" ]]; then
       NEW_COUNT=$(echo "$NEW_TOP_LEVEL" | wc -l | tr -d ' ')
-      if (( NEW_COUNT > 3 )); then
-        add_staleness "Multiple top-level files added/removed since last update (${NEW_COUNT} files)" 1
-      fi
+      (( NEW_COUNT > 3 )) && add_staleness "${NEW_COUNT} top-level files added/removed recently" 1
     fi
   fi
 fi
 
-# --- 3g) Lock file drift (structural indicator) -----------------------------
+# --- Lock file drift --------------------------------------------------------
 for LOCK in "$PROJECT_DIR/package-lock.json" \
             "$PROJECT_DIR/yarn.lock" \
             "$PROJECT_DIR/pnpm-lock.yaml" \
@@ -344,7 +341,7 @@ for LOCK in "$PROJECT_DIR/package-lock.json" \
     LOCK_DELTA=$(( (LOCK_MTIME - CLAUDE_MD_MTIME) / 86400 ))
     if (( LOCK_DELTA > 7 )); then
       add_staleness "$(basename "$LOCK") is ${LOCK_DELTA} days newer than CLAUDE.md" 1
-      break  # Only flag once for lock files
+      break
     fi
   fi
 done
@@ -354,42 +351,43 @@ done
 # ---------------------------------------------------------------------------
 OUTPUT_PARTS=()
 
-# Include any git warnings collected earlier (monorepo / suspect ancestor)
+# --- Welcome banner ---------------------------------------------------------
+SKILL_COUNT=$(find "$PROJECT_DIR/skills" -maxdepth 1 -mindepth 1 -type d 2>/dev/null | wc -l | tr -d ' ') || SKILL_COUNT=0
+if (( SKILL_COUNT > 0 )); then
+  OUTPUT_PARTS+=("[MAD SKILLS] Active — ${SKILL_COUNT} skills loaded")
+fi
+
 for part in "${EARLY_CONTEXT_PARTS[@]+"${EARLY_CONTEXT_PARTS[@]}"}"; do
   OUTPUT_PARTS+=("$part")
 done
 
-# Confirm CLAUDE.md found
 OUTPUT_PARTS+=("[SESSION GUARD] ✅ CLAUDE.md found in: $PROJECT_DIR")
 
 if (( STALENESS_SCORE >= STALENESS_THRESHOLD )); then
   OUTPUT_PARTS+=("")
-  OUTPUT_PARTS+=("[SESSION GUARD] ⚠️  CLAUDE.md appears to be STALE (staleness score: ${STALENESS_SCORE}/${STALENESS_THRESHOLD} threshold)")
+  OUTPUT_PARTS+=("[SESSION GUARD] ⚠️  CLAUDE.md appears STALE (score: ${STALENESS_SCORE}/${STALENESS_THRESHOLD})")
   OUTPUT_PARTS+=("")
-  OUTPUT_PARTS+=("Staleness signals detected:")
+  OUTPUT_PARTS+=("Signals:")
   for sig in "${STALENESS_SIGNALS[@]}"; do
     OUTPUT_PARTS+=("  $sig")
   done
   OUTPUT_PARTS+=("")
-  OUTPUT_PARTS+=("Please inform the user with something like:")
+  OUTPUT_PARTS+=("Use AskUserQuestion to prompt:")
+  OUTPUT_PARTS+=("  Question: \"CLAUDE.md appears out of date (${#STALENESS_SIGNALS[@]} signals detected). What would you like to do?\"")
+  OUTPUT_PARTS+=("  Type: single_select")
+  OUTPUT_PARTS+=("  Options:")
+  OUTPUT_PARTS+=("    1. \"Update it\" — review project structure, deps, recent changes and update CLAUDE.md (preserve user-written notes)")
+  OUTPUT_PARTS+=("    2. \"Show signals\" — list what's drifted before deciding")
+  OUTPUT_PARTS+=("    3. \"Skip\" — continue with current CLAUDE.md")
   OUTPUT_PARTS+=("")
-  OUTPUT_PARTS+=("\"I've detected that your CLAUDE.md may be out of date based on these signals:")
-  for sig in "${STALENESS_SIGNALS[@]}"; do
-    OUTPUT_PARTS+=("- ${sig#⚠ }")
-  done
-  OUTPUT_PARTS+=("")
-  OUTPUT_PARTS+=("Would you like me to review and update CLAUDE.md to reflect the current state of the project?\"")
-  OUTPUT_PARTS+=("")
-  OUTPUT_PARTS+=("If the user agrees, read the current CLAUDE.md, analyse the project structure, dependencies, and recent changes, then update CLAUDE.md accordingly. Preserve any user-written notes or conventions that are still accurate.")
 elif (( ${#STALENESS_SIGNALS[@]} > 0 )); then
   OUTPUT_PARTS+=("")
-  OUTPUT_PARTS+=("[SESSION GUARD] ℹ️  Minor drift detected (score: ${STALENESS_SCORE}/${STALENESS_THRESHOLD} threshold) — not flagging to user:")
+  OUTPUT_PARTS+=("[SESSION GUARD] ℹ️  Minor drift (score: ${STALENESS_SCORE}/${STALENESS_THRESHOLD}) — not flagging:")
   for sig in "${STALENESS_SIGNALS[@]}"; do
     OUTPUT_PARTS+=("  $sig")
   done
 fi
 
-# Join and emit
 CONTEXT=$(printf '%s\n' "${OUTPUT_PARTS[@]}")
 
 jq -n --arg ctx "$CONTEXT" '{
@@ -399,4 +397,10 @@ jq -n --arg ctx "$CONTEXT" '{
   }
 }'
 
+# ---------------------------------------------------------------------------
+# 5) Write pending flag for UserPromptSubmit companion hook
+# ---------------------------------------------------------------------------
+PENDING_FILE="$PENDING_DIR/$GUARD_KEY.pending"
+echo "$CONTEXT" > "$PENDING_FILE"
+
 exit 0

package/package.json

@@ -1,19 +1,14 @@
 {
   "name": "@slamb2k/mad-skills",
-  "version": "2.0.7",
-  "description": "Claude Code skills collection with CI/CD and npx installer",
+  "version": "2.0.8",
+  "description": "Claude Code skills collection — planning, development and governance tools",
   "type": "module",
-  "bin": {
-    "claude-skills": "./src/cli.js"
-  },
   "repository": {
     "type": "git",
     "url": "https://github.com/slamb2k/mad-skills"
   },
   "files": [
-    "src/",
     "skills/",
-    "commands/",
     "agents/",
     "hooks/",
     ".claude-plugin/"