axel-setup 0.2.0

package/hooks/memory-extractor.sh

@@ -0,0 +1,218 @@
+#!/bin/bash
+# Extract key decisions and learnings from session and persist to memory.
+# Runs async from Stop hook. Uses Sonnet for quality extraction.
+#
+# Ghost-session cleanup: Claude Code v2.1.x has a bug where
+# --no-session-persistence does NOT prevent the JSONL from being written to
+# ~/.claude/projects/. The workaround is to run the subprocess from a temporary
+# cwd (so its JSONL lands in a bucket unique to this hook) and rm -rf both the
+# tmp cwd and its projects/ bucket when done. Memory output still lands in
+# ~/.claude/memory/, which is completely unaffected.
+
+set -e
+
+# Guard: prevent recursive invocation. This script spawns `claude -p`, which
+# fires Stop hooks again when it finishes. Without this guard the hook loops
+# infinitely (each ghost session triggering another extraction).
+if [ -n "$CLAUDE_MEMORY_EXTRACTOR" ]; then
+  exit 0
+fi
+
+# Rate limit: debounce consecutive commits — skip if run within last 5 minutes.
+LAST_RUN_FILE="$HOME/.claude/memory/.last_extraction"
+if [ -f "$LAST_RUN_FILE" ]; then
+  LAST_TS=$(stat -f %m "$LAST_RUN_FILE" 2>/dev/null || stat -c %Y "$LAST_RUN_FILE" 2>/dev/null)
+  NOW_TS=$(date +%s)
+  if [ -n "$LAST_TS" ] && [ $((NOW_TS - LAST_TS)) -lt 300 ]; then
+    exit 0
+  fi
+fi
+mkdir -p "$HOME/.claude/memory"
+touch "$LAST_RUN_FILE"
+
+# Bootstrap substitutes these placeholders at install time via --user-context
+# and --language flags. The `case` fallback kicks in when the script runs
+# without bootstrap: sed never replaced the token, so it still starts with
+# `{{` and ends with `}}`. (We cannot compare against the literal token here
+# — bootstrap's sed would rewrite both sides of the comparison at install.)
+USER_CONTEXT="{{USER_CONTEXT}}"
+case "$USER_CONTEXT" in "{{"*"}}"|"") USER_CONTEXT="a software engineer" ;; esac
+ASSISTANT_LANGUAGE="{{ASSISTANT_LANGUAGE}}"
+case "$ASSISTANT_LANGUAGE" in "{{"*"}}"|"") ASSISTANT_LANGUAGE="english" ;; esac
+
+INPUT=$(cat)
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty')
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
+
+MEMORY_DIR="$HOME/.claude/memory"
+DECISIONS_DIR="$MEMORY_DIR/decisions"
+TIMESTAMP=$(date +%Y-%m-%d)
+
+mkdir -p "$DECISIONS_DIR"
+
+# Extract conversation from transcript if available
+CONVERSATION=""
+if [ -n "$TRANSCRIPT" ] && [ -f "$TRANSCRIPT" ]; then
+  CONVERSATION=$(cat "$TRANSCRIPT" | \
+    jq -r 'select(.type == "human" or .type == "assistant") |
+      if .type == "human" then "USER: " + (.message // .content // "" | tostring)[:500]
+      elif .type == "assistant" then "CLAUDE: " + (.message // .content // "" | tostring)[:500]
+      else empty end' 2>/dev/null | tail -60 | head -c 25000)
+fi
+
+# Fallback: use checkpoints + latest session summary
+if [ -z "$CONVERSATION" ] || [ ${#CONVERSATION} -lt 200 ]; then
+  PROJECT_NAME=$(basename "${CWD:-$(pwd)}")
+  SESSION_DIR="$HOME/.claude/sessions"
+  CHECKPOINT_DIR="$SESSION_DIR/checkpoints"
+  TODAY=$(date +%Y-%m-%d)
+
+  CHECKPOINTS=""
+  if [ -d "$CHECKPOINT_DIR" ]; then
+    for f in $(ls -t "$CHECKPOINT_DIR"/${PROJECT_NAME}_${TODAY}*.md 2>/dev/null | head -10); do
+      CP_CONTENT=$(sed -n '/^---$/,/^---$/!p' "$f" 2>/dev/null)
+      if [ -n "$CP_CONTENT" ]; then
+        CHECKPOINTS="$CHECKPOINTS
+$CP_CONTENT
+---
+"
+      fi
+    done
+  fi
+
+  LATEST_SUMMARY=""
+  LATEST_FILE=$(ls -t "$SESSION_DIR"/${PROJECT_NAME}_${TODAY}*.md 2>/dev/null | head -1)
+  if [ -n "$LATEST_FILE" ] && [ -f "$LATEST_FILE" ]; then
+    LATEST_SUMMARY=$(cat "$LATEST_FILE" | head -c 10000)
+  fi
+
+  CONVERSATION="$CHECKPOINTS
+$LATEST_SUMMARY"
+fi
+
+# Skip if no meaningful content
+if [ -z "$CONVERSATION" ] || [ ${#CONVERSATION} -lt 200 ]; then
+  exit 0
+fi
+
+# Read current MEMORY.md for dedup context
+CURRENT_MEMORY=""
+if [ -f "$MEMORY_DIR/MEMORY.md" ]; then
+  CURRENT_MEMORY=$(cat "$MEMORY_DIR/MEMORY.md")
+fi
+
+# Use Sonnet to extract decisions worth remembering
+{
+  PROMPT=$(printf 'You are an intelligent memory extractor for a programming assistant. Analyze the session conversation and determine if there is valuable information that should persist in memory for future sessions. Respond in %s.
+
+The user is %s.
+
+MEMORY TYPES:
+- user: info about the user (role, preferences, skills, personal context)
+- feedback: corrections or confirmations about how to work (dos and donts)
+- project: technical decisions, architecture changes, project state, team info
+- reference: where to find info in external systems (URLs, IDs, channels)
+
+STRICT RULES:
+- Only extract NON-OBVIOUS information that cannot be derived by reading the code.
+- DEDUPLICATION: walk the full MEMORY.md index before creating anything. If a topic is already covered by an existing memory — even under a different name, or as part of a consolidated entry — do NOT create a new one. What matters is whether the INFORMATION is already captured, not whether the filename matches.
+- For feedback and project types, include **Why:** and **How to apply:** lines.
+- If nothing significant to persist, respond EXACTLY: NOTHING
+- If something exists, respond in JSON array format (max 2 entries per session).
+- Filenames must be descriptive: type_topic.md (e.g.: project_people_finder_v2.md).
+- Keep index_line descriptions under 60 characters.
+
+JSON format when there is something:
+[{"filename": "type_topic.md", "name": "Descriptive name", "description": "One line for MEMORY.md index", "type": "user|feedback|project|reference", "content": "Full memory content", "index_line": "- [Name](type_topic.md) — short description"}]
+
+Current memory (to avoid duplicates):
+%s
+
+Session conversation:
+%s' "$ASSISTANT_LANGUAGE" "$USER_CONTEXT" "$CURRENT_MEMORY" "$CONVERSATION")
+
+  HOOK_TMP=$(mktemp -d 2>/dev/null)
+  HOOK_TMP_REAL=$(cd "$HOOK_TMP" 2>/dev/null && pwd -P)
+  EXTRACTION=$(cd "$HOOK_TMP" 2>/dev/null && printf '%s' "$PROMPT" | CLAUDE_MEMORY_EXTRACTOR=1 claude -p --model sonnet 2>/dev/null)
+
+  # Cleanup the ghost session JSONL bucket that claude -p created.
+  # Claude slugifies the cwd by replacing any non-alphanumeric char with '-',
+  # so use pwd -P (resolved physical path) and the same regex to reconstruct it.
+  if [ -n "$HOOK_TMP_REAL" ]; then
+    GHOST_SLUG=$(echo "$HOOK_TMP_REAL" | sed 's|[^a-zA-Z0-9]|-|g')
+    rm -rf "$HOOK_TMP" "$HOME/.claude/projects/${GHOST_SLUG}" 2>/dev/null
+  fi
+
+  if [ -z "$EXTRACTION" ] || echo "$EXTRACTION" | grep -qi "NOTHING"; then
+    exit 0
+  fi
+
+  # Extract JSON from response
+  JSON_EXTRACTION=$(echo "$EXTRACTION" | sed -n '/^\[/,/^\]/p' | head -c 10000)
+  if [ -z "$JSON_EXTRACTION" ]; then
+    JSON_EXTRACTION=$(echo "$EXTRACTION" | sed -n '/```json/,/```/p' | sed '1d;$d' | head -c 10000)
+  fi
+  if [ -z "$JSON_EXTRACTION" ]; then
+    JSON_EXTRACTION="$EXTRACTION"
+  fi
+
+  # Validate JSON
+  if ! echo "$JSON_EXTRACTION" | jq '.' >/dev/null 2>&1; then
+    exit 0
+  fi
+
+  # Process each memory entry
+  ENTRIES=$(echo "$JSON_EXTRACTION" | jq -r 'length')
+  for i in $(seq 0 $((ENTRIES - 1))); do
+    FILENAME=$(echo "$JSON_EXTRACTION" | jq -r ".[$i].filename")
+    NAME=$(echo "$JSON_EXTRACTION" | jq -r ".[$i].name")
+    DESC=$(echo "$JSON_EXTRACTION" | jq -r ".[$i].description")
+    TYPE=$(echo "$JSON_EXTRACTION" | jq -r ".[$i].type")
+    CONTENT=$(echo "$JSON_EXTRACTION" | jq -r ".[$i].content")
+    INDEX_LINE=$(echo "$JSON_EXTRACTION" | jq -r ".[$i].index_line")
+
+    if [ -z "$FILENAME" ] || [ "$FILENAME" = "null" ]; then
+      continue
+    fi
+
+    FILEPATH="$MEMORY_DIR/$FILENAME"
+
+    # Don't overwrite manually curated memory files
+    if [ -f "$FILEPATH" ] && [[ "$FILENAME" != decisions/* ]]; then
+      continue
+    fi
+
+    cat > "$FILEPATH" << ENDOFFILE
+---
+name: $NAME
+description: $DESC
+type: $TYPE
+auto_extracted: true
+date: $TIMESTAMP
+session_id: $SESSION_ID
+---
+
+$CONTENT
+ENDOFFILE
+
+    # Add to MEMORY.md index if not already there
+    if [ -f "$MEMORY_DIR/MEMORY.md" ]; then
+      if ! grep -qF "$FILENAME" "$MEMORY_DIR/MEMORY.md"; then
+        echo "$INDEX_LINE" >> "$MEMORY_DIR/MEMORY.md"
+      fi
+    fi
+  done
+
+  # Cleanup: keep only last 20 decision files
+  if [ -d "$DECISIONS_DIR" ]; then
+    ls -t "$DECISIONS_DIR"/*.md 2>/dev/null | tail -n +21 | xargs rm -f 2>/dev/null
+  fi
+
+  # Run dedup check
+  QUIET=true zsh "$HOME/.claude/hooks/memory-dedup.sh" 2>/dev/null || true
+
+} &
+
+exit 0

package/hooks/post-commit-memory-trigger.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Trigger memory-extractor.sh after a real git commit.
+# Runs from PostToolUse Bash hook (async).
+# memory-extractor.sh has an internal 5-minute rate limit to batch consecutive commits.
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+# Only trigger after a real `git commit` (not git log, diff, status, etc.)
+if ! echo "$COMMAND" | grep -qE '(^|[[:space:]&;|(])git[[:space:]]+commit([[:space:]]|$)'; then
+  exit 0
+fi
+
+# Forward the full hook payload to the extractor
+echo "$INPUT" | bash "$HOME/.claude/hooks/memory-extractor.sh"
+exit 0

package/hooks/post-commit-verify.sh

@@ -0,0 +1,41 @@
+#!/bin/zsh
+# PostToolUse hook: After a git commit, outputs a reminder for AXEL to
+# launch excelsior-verifier on the committed files.
+# This is a lightweight trigger — the actual verification runs as a subagent.
+
+# Only trigger on Bash tool calls that contain 'git commit'
+TOOL_INPUT="${TOOL_INPUT:-}"
+if [[ "$TOOL_INPUT" != *"git commit"* ]]; then
+  exit 0
+fi
+
+# Check if the commit actually succeeded (exit code 0 from the tool)
+TOOL_IS_ERROR="${TOOL_RESULT_IS_ERROR:-0}"
+if [[ "$TOOL_IS_ERROR" == "1" ]] || [[ "$TOOL_IS_ERROR" == "true" ]]; then
+  exit 0
+fi
+
+# Get the files from the last commit
+CHANGED_FILES=$(git diff-tree --no-commit-id --name-only -r HEAD 2>/dev/null | head -20)
+if [ -z "$CHANGED_FILES" ]; then
+  exit 0
+fi
+
+FILE_COUNT=$(echo "$CHANGED_FILES" | wc -l | tr -d ' ')
+COMMIT_MSG=$(git log --oneline -1 2>/dev/null)
+
+# Only trigger for non-trivial commits (2+ files or test/feature commits)
+if [[ "$FILE_COUNT" -lt 2 ]] && [[ "$COMMIT_MSG" != *"feat"* ]] && [[ "$COMMIT_MSG" != *"fix"* ]]; then
+  exit 0
+fi
+
+# Output advisory to AXEL to launch verifier
+cat << EOF
+Post-commit verification advisory: Commit "$COMMIT_MSG" modified $FILE_COUNT files:
+$(echo "$CHANGED_FILES" | sed 's/^/  - /')
+
+Consider launching excelsior-verifier as a background agent to verify this commit.
+Command: Agent({ subagent_type: "excelsior-verifier", run_in_background: true, prompt: "Verify commit: $COMMIT_MSG. Files: $CHANGED_FILES" })
+EOF
+
+exit 0

package/hooks/post-edit-lint.sh

@@ -0,0 +1,43 @@
+#!/bin/zsh
+# PostToolUse hook: Auto-lint/fix files after Edit or Write.
+# Uses HOOK_TOOL_INPUT (JSON stdin) for richer context when available,
+# falls back to TOOL_INPUT_FILE_PATH env var.
+
+# Try to extract file path from JSON stdin first, then env var
+FILE=""
+if [ -n "$TOOL_INPUT_FILE_PATH" ]; then
+  FILE="$TOOL_INPUT_FILE_PATH"
+elif [ -n "$HOOK_TOOL_INPUT" ]; then
+  FILE=$(echo "$HOOK_TOOL_INPUT" | python3 -c "import sys,json; print(json.loads(sys.stdin.read()).get('file_path',''))" 2>/dev/null)
+fi
+
+if [ -z "$FILE" ] || [ ! -f "$FILE" ]; then
+  exit 0
+fi
+
+# Ruby files — rubocop autocorrect
+if [[ "$FILE" == *.rb ]] && [[ -f Gemfile ]]; then
+  bundle exec rubocop --autocorrect "$FILE" --format simple 2>/dev/null | tail -5
+
+# TypeScript/JavaScript — eslint fix
+elif [[ "$FILE" == *.ts ]] || [[ "$FILE" == *.tsx ]] || [[ "$FILE" == *.js ]] || [[ "$FILE" == *.jsx ]]; then
+  if [[ -f node_modules/.bin/eslint ]]; then
+    npx eslint --fix "$FILE" 2>/dev/null | tail -5
+  fi
+
+# Python — ruff fix (fast, modern linter)
+elif [[ "$FILE" == *.py ]]; then
+  if command -v ruff >/dev/null 2>&1; then
+    ruff check --fix "$FILE" 2>/dev/null | tail -5
+  elif command -v autopep8 >/dev/null 2>&1; then
+    autopep8 --in-place "$FILE" 2>/dev/null
+  fi
+
+# ERB templates — erb lint
+elif [[ "$FILE" == *.erb ]] && [[ -f Gemfile ]]; then
+  if bundle show erb_lint >/dev/null 2>&1; then
+    bundle exec erblint --autocorrect "$FILE" 2>/dev/null | tail -3
+  fi
+fi
+
+exit 0

package/hooks/precompact-save-context.sh

@@ -0,0 +1,124 @@
+#!/bin/zsh
+# PreCompact hook: saves rich context before compaction discards messages.
+# Extracts key files, pending work, decisions, and timeline.
+# Pattern inspired by claw-code compact.rs — preserve what matters.
+
+PROJECT_NAME=$(basename "$(pwd)")
+CONTEXT_DIR="$HOME/.claude/sessions/context"
+TIMESTAMP=$(date +%Y-%m-%d_%H%M%S)
+
+mkdir -p "$CONTEXT_DIR"
+
+# Read stdin for compaction context
+INPUT=$(cat)
+COMPACT_TYPE=$(echo "$INPUT" | python3 -c "import sys,json; print(json.loads(sys.stdin.read()).get('type','auto'))" 2>/dev/null || echo "auto")
+
+CONTEXT_FILE="$CONTEXT_DIR/${PROJECT_NAME}_${TIMESTAMP}.md"
+
+# --- Git state ---
+GIT_STATE=""
+if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  BRANCH=$(git branch --show-current 2>/dev/null)
+  RECENT_COMMITS=$(git log --oneline -10 2>/dev/null)
+  MODIFIED=$(git diff --name-only 2>/dev/null | head -20)
+  STAGED=$(git diff --cached --name-only 2>/dev/null | head -20)
+  GIT_STATE="Branch: $BRANCH
+Recent commits:
+$RECENT_COMMITS
+Modified files: $MODIFIED
+Staged files: $STAGED"
+fi
+
+# --- Key files referenced in session ---
+KEY_FILES=""
+LOG_FILE="/tmp/claude-session-log-${PROJECT_NAME}.md"
+if [ -f "$LOG_FILE" ]; then
+  # Extract file paths mentioned in the session log (pattern: paths with extensions)
+  KEY_FILES=$(grep -oE '[a-zA-Z0-9_/.-]+\.(rb|ts|tsx|js|jsx|py|rs|json|yml|yaml|md|sql|erb|rake)' "$LOG_FILE" 2>/dev/null | sort -u | head -15)
+fi
+
+# --- Pending work / TODOs ---
+PENDING_WORK=""
+if [ -f "$LOG_FILE" ]; then
+  PENDING_WORK=$(grep -iE '(todo|next|pending|follow.up|remaining|fixme|hack|later)' "$LOG_FILE" 2>/dev/null | tail -10)
+fi
+
+# --- Recent session actions ---
+SESSION_LOG=""
+if [ -f "$LOG_FILE" ]; then
+  SESSION_LOG=$(tail -40 "$LOG_FILE")
+fi
+
+# --- Active tasks (if GSD is running) ---
+ACTIVE_TASKS=""
+PLANNING_DIR="$(pwd)/.planning"
+if [ -d "$PLANNING_DIR" ]; then
+  # Find current phase
+  CURRENT_PHASE=$(ls -d "$PLANNING_DIR"/phase-* 2>/dev/null | tail -1)
+  if [ -n "$CURRENT_PHASE" ]; then
+    ACTIVE_TASKS="Current phase: $(basename "$CURRENT_PHASE")"
+    if [ -f "$CURRENT_PHASE/PLAN.md" ]; then
+      # Extract incomplete tasks from plan
+      INCOMPLETE=$(grep -E '^\s*-\s*\[ \]' "$CURRENT_PHASE/PLAN.md" 2>/dev/null | head -10)
+      if [ -n "$INCOMPLETE" ]; then
+        ACTIVE_TASKS="$ACTIVE_TASKS
+Incomplete tasks:
+$INCOMPLETE"
+      fi
+    fi
+  fi
+fi
+
+# --- Decisions made (look for patterns in session) ---
+DECISIONS=""
+if [ -f "$LOG_FILE" ]; then
+  DECISIONS=$(grep -iE '(decided|decision|chose|picked|went with|selected|agreed|confirmed)' "$LOG_FILE" 2>/dev/null | tail -5)
+fi
+
+# --- Memory files modified this session ---
+MEMORY_CHANGES=""
+MEMORY_DIR="$HOME/.claude/memory"
+if [ -d "$MEMORY_DIR" ]; then
+  # Files modified in the last 2 hours
+  MEMORY_CHANGES=$(find "$MEMORY_DIR" -name "*.md" -mmin -120 -type f 2>/dev/null | while read f; do basename "$f"; done | head -10)
+fi
+
+cat > "$CONTEXT_FILE" << ENDOFFILE
+---
+project: $PROJECT_NAME
+compact_type: $COMPACT_TYPE
+date: $(date +%Y-%m-%d)
+time: $(date +%H:%M)
+---
+
+# Pre-compact context snapshot
+
+## Git state
+$GIT_STATE
+
+## Key files referenced
+$KEY_FILES
+
+## Pending work / TODOs
+$PENDING_WORK
+
+## Active tasks
+$ACTIVE_TASKS
+
+## Decisions made
+$DECISIONS
+
+## Memory files updated
+$MEMORY_CHANGES
+
+## Recent actions (last 40)
+$SESSION_LOG
+ENDOFFILE
+
+# Keep only last 5 context snapshots per project
+ls -t "$CONTEXT_DIR"/${PROJECT_NAME}_*.md 2>/dev/null | tail -n +6 | xargs rm -f 2>/dev/null
+
+# Output message to Claude about context being saved
+echo '{"hookSpecificOutput":{"hookEventName":"PreCompact","additionalContext":"Se guardó un snapshot enriquecido del contexto antes de compactación en '"$CONTEXT_FILE"'. Incluye: archivos clave, trabajo pendiente, decisiones, tareas activas, y estado git. La memoria persistente en ~/.claude/memory/ sigue intacta."}}'
+
+exit 0

package/hooks/priority-map-staleness.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# SessionStart hook — warns if priority-map.md is stale (>14 days) or missing.
+# Output is injected into the session's initial context.
+
+PRIORITY_MAP="$HOME/.claude/memory/priority-map.md"
+MAX_AGE_DAYS=14
+
+if [[ ! -f "$PRIORITY_MAP" ]]; then
+  echo "⚠️  priority-map.md does not exist at ~/.claude/memory/ — skills like sprint-status/daily/eod-review will run without it"
+  exit 0
+fi
+
+if [[ "$(uname)" == "Darwin" ]]; then
+  FILE_MTIME=$(stat -f %m "$PRIORITY_MAP")
+else
+  FILE_MTIME=$(stat -c %Y "$PRIORITY_MAP")
+fi
+
+NOW=$(date +%s)
+AGE_SECONDS=$((NOW - FILE_MTIME))
+AGE_DAYS=$((AGE_SECONDS / 86400))
+
+if (( AGE_DAYS > MAX_AGE_DAYS )); then
+  echo "⚠️  priority-map.md is ${AGE_DAYS} days old (threshold: ${MAX_AGE_DAYS}). Review and refresh current-sprint P0/P1 before running /daily or /sprint-status."
+elif (( AGE_DAYS >= 7 )); then
+  echo "ℹ️  priority-map.md is ${AGE_DAYS} days old — consider a refresh if sprint focus changed."
+fi
+
+exit 0

package/hooks/proactive-resolver.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+# Excelsior Proactive Resolver — PostToolUse hook for Bash
+# Philosophy: ANY failure that can be auto-resolved SHOULD be auto-resolved.
+# This hook handles the fast, known patterns. For everything else,
+# the CLAUDE.md Excelsior principle tells the model to investigate and resolve.
+
+TOOL_OUTPUT="${TOOL_OUTPUT:-}"
+EXIT_CODE="${TOOL_EXIT_CODE:-0}"
+
+# Only act on failures
+[ "$EXIT_CODE" = "0" ] && exit 0
+
+RESOLVED=""
+
+# === SERVICE DETECTION & AUTO-START ===
+
+# Docker (any Docker-related error)
+if echo "$TOOL_OUTPUT" | grep -qiE "docker daemon|Cannot connect to the Docker|docker\.sock|Is the docker daemon running|docker:.*command not found"; then
+  if [ "$(uname)" = "Darwin" ] && ! docker info >/dev/null 2>&1; then
+    open -a "Docker" 2>/dev/null
+    for i in $(seq 1 15); do docker info >/dev/null 2>&1 && break; sleep 1; done
+    if docker info >/dev/null 2>&1; then
+      RESOLVED="Docker Desktop started automatically."
+    else
+      RESOLVED="HINT: Docker Desktop is launching. Wait a few seconds and retry."
+    fi
+  fi
+fi
+
+# PostgreSQL (any PG connection error)
+if echo "$TOOL_OUTPUT" | grep -qiE "PG::|postgresql.*refused|could not connect.*5432\|could not connect.*5433\|connection to server.*failed.*postgres"; then
+  if [ "$(uname)" = "Darwin" ]; then
+    brew services start postgresql@16 2>/dev/null || brew services start postgresql 2>/dev/null
+    STOPPED_PG=$(docker ps -a --filter "ancestor=postgres" --filter "status=exited" --format "{{.Names}}" 2>/dev/null | head -1)
+    [ -n "$STOPPED_PG" ] && docker start "$STOPPED_PG" 2>/dev/null
+    RESOLVED="PostgreSQL restart attempted."
+  fi
+fi
+
+# Redis
+if echo "$TOOL_OUTPUT" | grep -qiE "Redis.*refused|ECONNREFUSED.*6379|Redis::CannotConnectError|redis.*not connect"; then
+  brew services start redis 2>/dev/null && RESOLVED="Redis started via Homebrew."
+fi
+
+# MySQL
+if echo "$TOOL_OUTPUT" | grep -qiE "mysql.*refused|ECONNREFUSED.*3306|Access denied for user.*mysql"; then
+  brew services start mysql 2>/dev/null && RESOLVED="MySQL started via Homebrew."
+fi
+
+# === DEPENDENCY RESOLUTION ===
+
+# Node modules missing
+if echo "$TOOL_OUTPUT" | grep -qiE "Cannot find module|MODULE_NOT_FOUND|ERR_MODULE_NOT_FOUND" && [ -f "package.json" ]; then
+  if [ -f "pnpm-lock.yaml" ]; then
+    RESOLVED="HINT: Run 'pnpm install' — missing node_modules detected."
+  elif [ -f "yarn.lock" ]; then
+    RESOLVED="HINT: Run 'yarn install' — missing node_modules detected."
+  elif [ -f "package-lock.json" ]; then
+    RESOLVED="HINT: Run 'npm install' — missing node_modules detected."
+  fi
+fi
+
+# Ruby gems missing
+if echo "$TOOL_OUTPUT" | grep -qiE "Could not find gem|Bundler::GemNotFound|bundle install|Gem::MissingSpecError"; then
+  RESOLVED="HINT: Run 'bundle install' — missing gems detected."
+fi
+
+# Python deps missing
+if echo "$TOOL_OUTPUT" | grep -qiE "ModuleNotFoundError|No module named|ImportError.*No module"; then
+  if [ -f "requirements.txt" ]; then
+    RESOLVED="HINT: Run 'pip install -r requirements.txt' — missing Python module."
+  elif [ -f "pyproject.toml" ]; then
+    RESOLVED="HINT: Run 'pip install -e .' or 'poetry install' — missing Python module."
+  fi
+fi
+
+# === ENVIRONMENT ISSUES ===
+
+# Port in use — identify the blocker
+if echo "$TOOL_OUTPUT" | grep -qiE "EADDRINUSE|Address already in use|port.*already.*use|bind.*address already"; then
+  PORT=$(echo "$TOOL_OUTPUT" | grep -oE "[0-9]{4,5}" | head -1)
+  [ -n "$PORT" ] && PID=$(lsof -ti ":$PORT" 2>/dev/null | head -1)
+  [ -n "$PID" ] && PROC=$(ps -p "$PID" -o comm= 2>/dev/null)
+  [ -n "$PROC" ] && RESOLVED="HINT: Port $PORT blocked by $PROC (PID $PID). Kill with: kill $PID"
+fi
+
+# Database not created
+if echo "$TOOL_OUTPUT" | grep -qiE "database.*does not exist|Unknown database|FATAL.*database.*not exist"; then
+  DB=$(echo "$TOOL_OUTPUT" | grep -oE '"[^"]*"' | head -1 | tr -d '"')
+  RESOLVED="HINT: Database '$DB' doesn't exist. Create it: rails db:create or createdb $DB"
+fi
+
+# Migrations pending
+if echo "$TOOL_OUTPUT" | grep -qiE "Migrations are pending|pending migration|migrate.*first"; then
+  RESOLVED="HINT: Pending migrations. Run: rails db:migrate RAILS_ENV=test"
+fi
+
+# === OUTPUT ===
+if [ -n "$RESOLVED" ]; then
+  echo "PROACTIVE: $RESOLVED Retry your command." >&2
+fi
+
+# Always exit 0 — this hook advises, never blocks
+exit 0