@arthai/agents 1.0.0

package/dist/plugins/shield/hooks/pre-edit-guard.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+# PreToolUse hook (Edit, Write): Warn on edits to protected files.
+# Does NOT block — only injects warnings so Claude thinks twice.
+#
+# stdout is injected as context. Exit 0 always (warnings only).
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# Extract file path from tool input
+FILE_PATH="${CLAUDE_TOOL_INPUT_FILE_PATH:-}"
+if [ -z "$FILE_PATH" ] && [ -n "${CLAUDE_TOOL_INPUT:-}" ]; then
+    FILE_PATH=$(echo "$CLAUDE_TOOL_INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('file_path',''))" 2>/dev/null) || true
+fi
+
+[ -z "$FILE_PATH" ] && exit 0
+
+# Get just the filename and relative path
+filename=$(basename "$FILE_PATH")
+rel_path="${FILE_PATH#$PROJECT_DIR/}"
+
+# ---------------------------------------------------------------------------
+# Bug fix scope lock enforcement
+# ---------------------------------------------------------------------------
+# If /fix created a scope lock, enforce Fix Zone / Frozen Zone boundaries.
+# Files in the Fix Zone are allowed. Watch Zone files get a warning.
+# Frozen Zone files get a strong warning (not a hard block — hook can only warn).
+
+SCOPE_LOCK="$PROJECT_DIR/.claude/.fix-scope-lock.json"
+if [ -f "$SCOPE_LOCK" ]; then
+    # Check if the file being edited is in the fix zone
+    IN_FIX_ZONE=false
+    IN_WATCH_ZONE=false
+
+    FIX_ZONE=$(python3 -c "import json; print('\n'.join(json.load(open('$SCOPE_LOCK')).get('fix_zone',[])))" 2>/dev/null) || true
+    WATCH_ZONE=$(python3 -c "import json; print('\n'.join(json.load(open('$SCOPE_LOCK')).get('watch_zone',[])))" 2>/dev/null) || true
+    FROZEN_PATTERNS=$(python3 -c "import json; print('\n'.join(json.load(open('$SCOPE_LOCK')).get('frozen_zone_patterns',[])))" 2>/dev/null) || true
+
+    # Check fix zone
+    if [ -n "$FIX_ZONE" ]; then
+        echo "$FIX_ZONE" | while read zone_file; do
+            if [ "$rel_path" = "$zone_file" ] || echo "$rel_path" | grep -q "^$zone_file"; then
+                IN_FIX_ZONE=true
+            fi
+        done
+    fi
+
+    # Check watch zone
+    if ! $IN_FIX_ZONE && [ -n "$WATCH_ZONE" ]; then
+        echo "$WATCH_ZONE" | while read zone_file; do
+            if [ "$rel_path" = "$zone_file" ] || echo "$rel_path" | grep -q "^$zone_file"; then
+                IN_WATCH_ZONE=true
+            fi
+        done
+    fi
+
+    if $IN_FIX_ZONE; then
+        : # Allowed — in Fix Zone
+    elif $IN_WATCH_ZONE; then
+        echo "⚠️ SCOPE WARNING: ${rel_path} is in the WATCH ZONE for the current bug fix."
+        echo "This file is related to the fix but was not expected to need changes."
+        echo "Explain WHY this file needs modification before proceeding."
+    elif ! $IN_FIX_ZONE && ! $IN_WATCH_ZONE; then
+        BUG_DESC=$(python3 -c "import json; print(json.load(open('$SCOPE_LOCK')).get('bug','unknown'))" 2>/dev/null) || true
+        echo "🛑 SCOPE VIOLATION: ${rel_path} is in the FROZEN ZONE."
+        echo "Bug fix scope: ${BUG_DESC}"
+        echo "This file is NOT part of the fix and should NOT be modified."
+        echo "If you must modify it, remove .claude/.fix-scope-lock.json first and explain why the scope expanded."
+        echo "DO NOT edit this file unless the user explicitly approves the scope change."
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# Protected file patterns
+# ---------------------------------------------------------------------------
+
+# Dependency lock files (modifications should be intentional)
+case "$filename" in
+    requirements.txt)
+        echo "⚠️ Protected file: ${rel_path}"
+        echo "This file defines core dependencies. Removing packages can break the project."
+        echo "Only modify if explicitly asked by the user."
+        ;;
+    package-lock.json|yarn.lock|pnpm-lock.yaml)
+        echo "⚠️ Lock file: ${rel_path}"
+        echo "Lock files should be modified via npm/yarn/pnpm install, not directly."
+        ;;
+    Cargo.lock)
+        echo "⚠️ Lock file: ${rel_path}"
+        echo "Cargo.lock should be modified via cargo commands, not directly."
+        ;;
+esac
+
+# Environment files (may contain secrets)
+case "$filename" in
+    .env|.env.local|.env.production|.env.staging)
+        echo "⚠️ Environment file: ${rel_path}"
+        echo "May contain secrets. Never commit to git. Verify changes are intentional."
+        ;;
+esac
+
+# Migration files (should not be auto-edited)
+if echo "$rel_path" | grep -qE 'migrations/versions/|alembic/versions/|prisma/migrations/'; then
+    echo "⚠️ Migration file: ${rel_path}"
+    echo "Existing migrations should not be modified. Create a new migration instead."
+fi
+
+# CI/CD config files — match against rel_path for path-based patterns, filename for simple names
+if echo "$rel_path" | grep -qE '\.github/workflows/|\.gitlab-ci\.yml|Jenkinsfile'; then
+    echo "ℹ️ Infrastructure file: ${rel_path}"
+    echo "Changes may affect CI/CD pipelines or deployments."
+fi
+case "$filename" in
+    Dockerfile|docker-compose.yml|docker-compose.yaml)
+        echo "ℹ️ Infrastructure file: ${rel_path}"
+        echo "Changes may affect container builds or service topology."
+        ;;
+esac
+
+exit 0

package/dist/plugins/shield/hooks/session-bootstrap.sh

@@ -0,0 +1,379 @@
+#!/bin/bash
+# SessionStart hook: Gather project context and inject a compact briefing.
+# Runs once when Claude Code opens. Outputs 2-5 lines of context.
+# Non-blocking — degrades gracefully if tools are missing.
+#
+# stdout is injected as context into the conversation.
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# ---------------------------------------------------------------------------
+# Clear triage marker — forces full routing table on first message
+# ---------------------------------------------------------------------------
+rm -f "$PROJECT_DIR/.claude/.triage-full-emitted" 2>/dev/null || true
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+# Check if a command exists silently
+has_cmd() { command -v "$1" &>/dev/null; }
+
+# Run a command with timeout, return empty on failure
+# Uses perl fallback on macOS where GNU timeout doesn't exist
+safe_run() {
+    local timeout_s="${1:-3}"
+    shift
+    if command -v timeout &>/dev/null; then
+        timeout "$timeout_s" "$@" 2>/dev/null || true
+    else
+        # macOS fallback: run directly (no timeout protection, but at least it works)
+        "$@" 2>/dev/null || true
+    fi
+}
+
+# ---------------------------------------------------------------------------
+# 1. Project detection
+# ---------------------------------------------------------------------------
+
+project_name=$(basename "$PROJECT_DIR")
+claude_md_exists=false
+[ -f "$PROJECT_DIR/CLAUDE.md" ] && claude_md_exists=true
+
+# Detect greenfield vs brownfield
+is_greenfield=true
+if $claude_md_exists; then
+    is_greenfield=false
+elif [ -f "$PROJECT_DIR/package.json" ] || [ -f "$PROJECT_DIR/requirements.txt" ] || \
+     [ -f "$PROJECT_DIR/go.mod" ] || [ -f "$PROJECT_DIR/Cargo.toml" ] || \
+     [ -d "$PROJECT_DIR/src" ] || [ -d "$PROJECT_DIR/app" ]; then
+    is_greenfield=false
+fi
+
+# ---------------------------------------------------------------------------
+# 2. Git context (fast — local only)
+# ---------------------------------------------------------------------------
+
+branch=""
+uncommitted=0
+ahead_behind=""
+last_commit=""
+stash_count=0
+has_git=false
+
+if [ -d "$PROJECT_DIR/.git" ]; then
+    has_git=true
+    cd "$PROJECT_DIR"
+
+    branch=$(safe_run 2 git rev-parse --abbrev-ref HEAD)
+    uncommitted=$(safe_run 2 git status --short | wc -l | tr -d ' ')
+
+    # Ahead/behind remote
+    upstream=$(safe_run 2 git rev-parse --abbrev-ref '@{upstream}') || true
+    if [ -n "$upstream" ]; then
+        local_rev=$(safe_run 2 git rev-parse HEAD)
+        remote_rev=$(safe_run 2 git rev-parse "$upstream")
+        if [ "$local_rev" != "$remote_rev" ]; then
+            ahead=$(safe_run 2 git rev-list --count "$upstream..HEAD")
+            behind=$(safe_run 2 git rev-list --count "HEAD..$upstream")
+            parts=()
+            [ "${ahead:-0}" -gt 0 ] && parts+=("${ahead} ahead")
+            [ "${behind:-0}" -gt 0 ] && parts+=("${behind} behind")
+            if [ ${#parts[@]} -gt 0 ]; then
+                ahead_behind=$(IFS=', '; echo "${parts[*]}")
+            fi
+        fi
+    fi
+
+    # Last commit (short)
+    last_commit=$(safe_run 2 git log -1 --format='%s (%cr)' 2>/dev/null) || true
+
+    # Stash count
+    stash_count=$(safe_run 2 git stash list | wc -l | tr -d ' ')
+
+    cd - >/dev/null 2>&1 || true
+fi
+
+# ---------------------------------------------------------------------------
+# 3. Environment health (from CLAUDE.md + docker + alembic)
+# ---------------------------------------------------------------------------
+
+docker_status=""
+alembic_status=""
+mcp_status=""
+
+# Docker container health (if docker is available and CLAUDE.md mentions docker)
+if has_cmd docker && docker info &>/dev/null 2>&1; then
+    running_containers=$(safe_run 3 docker ps --format '{{.Names}}' | tr '\n' ' ')
+    # Check common DB containers
+    for svc in postgres redis mysql mongo; do
+        if echo "$running_containers" | grep -qi "$svc"; then
+            docker_status="${docker_status}${svc} ✓ "
+        else
+            # Only flag if the project likely uses this service
+            if [ -f "$PROJECT_DIR/docker-compose.yml" ] && grep -qi "$svc" "$PROJECT_DIR/docker-compose.yml" 2>/dev/null; then
+                docker_status="${docker_status}${svc} ✗ "
+            fi
+        fi
+    done
+    docker_status=$(echo "$docker_status" | sed 's/ $//')
+fi
+
+# Alembic migration status (if alembic dir exists)
+if [ -d "$PROJECT_DIR/backend/migrations" ] || [ -d "$PROJECT_DIR/migrations" ] || [ -d "$PROJECT_DIR/alembic" ]; then
+    # Find the venv
+    venv_activate=""
+    for v in "$PROJECT_DIR/backend/.venv/bin/activate" "$PROJECT_DIR/.venv/bin/activate" "$PROJECT_DIR/venv/bin/activate"; do
+        if [ -f "$v" ]; then
+            venv_activate="$v"
+            break
+        fi
+    done
+
+    if [ -n "$venv_activate" ]; then
+        alembic_dir=""
+        for d in "$PROJECT_DIR/backend" "$PROJECT_DIR"; do
+            if [ -f "$d/alembic.ini" ]; then
+                alembic_dir="$d"
+                break
+            fi
+        done
+
+        if [ -n "$alembic_dir" ]; then
+            current=$(cd "$alembic_dir" && source "$venv_activate" && safe_run 3 alembic current 2>/dev/null | head -1 | awk '{print $1}') || true
+            head_rev=$(cd "$alembic_dir" && source "$venv_activate" && safe_run 3 alembic heads 2>/dev/null | head -1 | awk '{print $1}') || true
+            if [ -n "$current" ] && [ -n "$head_rev" ]; then
+                if [ "$current" = "$head_rev" ]; then
+                    alembic_status="✓"
+                else
+                    alembic_status="⚠ pending migrations"
+                fi
+            fi
+        fi
+    fi
+fi
+
+# Railway MCP check (if configured)
+if has_cmd railway; then
+    railway_check=$(safe_run 3 railway whoami 2>&1) || true
+    if echo "$railway_check" | grep -qi "error\|not logged\|unauthenticated"; then
+        mcp_status="Railway: expired (run railway login)"
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# 4. GitHub context (if gh available — PRs, issues)
+# ---------------------------------------------------------------------------
+
+pr_summary=""
+issue_summary=""
+
+if has_cmd gh && $has_git; then
+    cd "$PROJECT_DIR"
+
+    # My open PRs
+    my_prs=$(safe_run 5 gh pr list --author @me --json number,title,reviewDecision,comments --limit 5 2>/dev/null) || true
+    if [ -n "$my_prs" ] && [ "$my_prs" != "[]" ]; then
+        pr_count=$(echo "$my_prs" | python3 -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null) || true
+        if [ "${pr_count:-0}" -gt 0 ]; then
+            pr_summary="${pr_count} open PR(s)"
+            # Check for unresolved review comments
+            needs_review=$(echo "$my_prs" | python3 -c "
+import json,sys
+prs=json.load(sys.stdin)
+needs=sum(1 for p in prs if p.get('reviewDecision') in ('CHANGES_REQUESTED',None) and p.get('comments',0)>0)
+if needs: print(f', {needs} need attention')
+" 2>/dev/null) || true
+            pr_summary="${pr_summary}${needs_review}"
+        fi
+    fi
+
+    # My assigned issues
+    my_issues=$(safe_run 5 gh issue list --assignee @me --json number,title --limit 5 2>/dev/null) || true
+    if [ -n "$my_issues" ] && [ "$my_issues" != "[]" ]; then
+        issue_count=$(echo "$my_issues" | python3 -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null) || true
+        if [ "${issue_count:-0}" -gt 0 ]; then
+            issue_summary="${issue_count} assigned issue(s)"
+        fi
+    fi
+
+    cd - >/dev/null 2>&1 || true
+fi
+
+# ---------------------------------------------------------------------------
+# 5. Active plans
+# ---------------------------------------------------------------------------
+
+active_plan=""
+if [ -d "$PROJECT_DIR/.claude/plans" ]; then
+    plan_files=$(find "$PROJECT_DIR/.claude/plans" -name "*.md" -newer "$PROJECT_DIR/.claude" 2>/dev/null | head -1) || true
+    if [ -n "$plan_files" ]; then
+        active_plan=$(basename "$plan_files")
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# 6. Session continuity (previous session detection)
+# ---------------------------------------------------------------------------
+
+session_hint=""
+
+# Check for existing session-state summary (written by /continue skill)
+if [ -f "$PROJECT_DIR/.claude/session-state/latest.md" ]; then
+    # Check if it's less than 7 days old
+    if [ "$(uname)" = "Darwin" ]; then
+        file_age=$(( $(date +%s) - $(stat -f%m "$PROJECT_DIR/.claude/session-state/latest.md") ))
+    else
+        file_age=$(( $(date +%s) - $(stat -c%Y "$PROJECT_DIR/.claude/session-state/latest.md") ))
+    fi
+    if [ "$file_age" -lt 604800 ]; then
+        # Extract first "What Was Done" bullet for a preview
+        preview=$(grep -m1 "^- " "$PROJECT_DIR/.claude/session-state/latest.md" 2>/dev/null | head -c 80) || true
+        if [ -n "$preview" ]; then
+            session_hint="Previous session: ${preview}... — /continue for details"
+        else
+            session_hint="Previous session summary available — /continue for details"
+        fi
+    fi
+fi
+
+# If no session-state, check for recent transcript JSONL
+if [ -z "$session_hint" ]; then
+    TRANSCRIPT_DIR_NAME=$(echo "$PROJECT_DIR" | sed 's|/|-|g')
+    TRANSCRIPT_DIR="$HOME/.claude/projects/${TRANSCRIPT_DIR_NAME}"
+    if [ -d "$TRANSCRIPT_DIR" ]; then
+        # Find the 2nd newest JSONL (newest is current session)
+        prev_transcript=$(ls -t "$TRANSCRIPT_DIR"/*.jsonl 2>/dev/null | sed -n '2p') || true
+        if [ -n "$prev_transcript" ]; then
+            # Check if it's less than 3 days old
+            if [ "$(uname)" = "Darwin" ]; then
+                t_age=$(( $(date +%s) - $(stat -f%m "$prev_transcript") ))
+            else
+                t_age=$(( $(date +%s) - $(stat -c%Y "$prev_transcript") ))
+            fi
+            if [ "$t_age" -lt 259200 ]; then
+                session_hint="Recent session detected — /continue to pick up where you left off"
+            fi
+        fi
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# 7. Output — compact briefing (max 6 lines)
+# ---------------------------------------------------------------------------
+
+# Line 1: Project + branch
+line1="📋 ${project_name}"
+if $is_greenfield; then
+    line1="${line1} — new project (no code detected)"
+elif $has_git && [ -n "$branch" ]; then
+    line1="${line1} — ${branch}"
+    [ -n "$ahead_behind" ] && line1="${line1} (${ahead_behind})"
+fi
+echo "$line1"
+
+# Line 2: Red flags (only if there are problems)
+flags=()
+[ -n "$docker_status" ] && echo "$docker_status" | grep -q "✗" && flags+=("Docker: ${docker_status}")
+[ "$alembic_status" = "⚠ pending migrations" ] && flags+=("Alembic: ${alembic_status}")
+[ -n "$mcp_status" ] && flags+=("⚠ ${mcp_status}")
+
+if [ ${#flags[@]} -gt 0 ]; then
+    echo "   $(IFS=' · '; echo "${flags[*]}")"
+fi
+
+# Line 3: Context (uncommitted, plan, last commit)
+context_parts=()
+[ "${uncommitted:-0}" -gt 0 ] && context_parts+=("${uncommitted} uncommitted files")
+[ -n "$active_plan" ] && context_parts+=("Plan: ${active_plan}")
+[ "${stash_count:-0}" -gt 0 ] && context_parts+=("${stash_count} stash(es)")
+
+if [ ${#context_parts[@]} -gt 0 ]; then
+    echo "   $(IFS=' · '; echo "${context_parts[*]}")"
+fi
+
+# Line 4: GitHub context (PRs, issues)
+gh_parts=()
+[ -n "$pr_summary" ] && gh_parts+=("$pr_summary")
+[ -n "$issue_summary" ] && gh_parts+=("$issue_summary")
+
+if [ ${#gh_parts[@]} -gt 0 ]; then
+    echo "   $(IFS=' · '; echo "${gh_parts[*]}")"
+fi
+
+# Line 5: Toolkit status (show what's active)
+toolkit_parts=()
+if [ -f "$PROJECT_DIR/.claude/hooks/triage-router.sh" ] || [ -L "$PROJECT_DIR/.claude/hooks/triage-router.sh" ]; then
+    toolkit_parts+=("Triage router: active")
+fi
+if [ -f "$PROJECT_DIR/.claude/hooks/pre-bash-guard.sh" ] || [ -L "$PROJECT_DIR/.claude/hooks/pre-bash-guard.sh" ]; then
+    toolkit_parts+=("Guard rails: on")
+fi
+if [ ${#toolkit_parts[@]} -gt 0 ]; then
+    echo "   $(IFS=' · '; echo "${toolkit_parts[*]}")"
+fi
+
+# Session continuity hint (if not greenfield)
+if ! $is_greenfield && [ -n "$session_hint" ]; then
+    echo "   $session_hint"
+fi
+
+# Greenfield hint
+if $is_greenfield; then
+    echo "   Tip: describe what you're building, or type /onboard for guided setup"
+fi
+
+# Calibration hint — show for brownfield projects that haven't been calibrated
+if ! $is_greenfield; then
+    if [ ! -f "$PROJECT_DIR/.claude/project-profile.md" ]; then
+        # Only show if calibrate skill is installed
+        if [ -d "$PROJECT_DIR/.claude/skills/calibrate" ] || [ -L "$PROJECT_DIR/.claude/skills/calibrate" ]; then
+            echo "   Tip: run /calibrate to deep-learn your project and configure MCP servers + agents"
+        fi
+    else
+        # Check knowledge base change detection for drift
+        CHANGE_DETECT="$PROJECT_DIR/.claude/knowledge/meta/change-detection.md"
+        if [ -f "$CHANGE_DETECT" ]; then
+            drift_found=false
+            for keyfile in package.json requirements.txt pyproject.toml docker-compose.yml Podfile Package.swift build.gradle pubspec.yaml; do
+                if [ -f "$PROJECT_DIR/$keyfile" ]; then
+                    current_hash=$(shasum -a 256 "$PROJECT_DIR/$keyfile" 2>/dev/null | cut -c1-8)
+                    stored_hash=$(grep "$keyfile" "$CHANGE_DETECT" 2>/dev/null | awk '{print $4}' | head -1)
+                    if [ -n "$stored_hash" ] && [ -n "$current_hash" ] && [ "$stored_hash" != "$current_hash" ]; then
+                        drift_found=true
+                        break
+                    fi
+                fi
+            done
+            if $drift_found; then
+                echo "   ⚠ Project files changed since last calibration — run /calibrate rescan"
+            fi
+        fi
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# 8. Write project state cache (other hooks read this instead of re-computing)
+# ---------------------------------------------------------------------------
+
+CACHE_FILE="$PROJECT_DIR/.claude/.project-state-cache.json"
+_cache_json=$(cat <<CACHE_EOF
+{
+  "timestamp": $(date +%s),
+  "project_name": "$project_name",
+  "is_greenfield": $is_greenfield,
+  "has_git": $has_git,
+  "branch": "${branch:-}",
+  "uncommitted": ${uncommitted:-0},
+  "ahead_behind": "${ahead_behind:-}",
+  "stash_count": ${stash_count:-0},
+  "docker_status": "${docker_status:-}",
+  "alembic_status": "${alembic_status:-}",
+  "mcp_status": "${mcp_status:-}",
+  "active_plan": "${active_plan:-}"
+}
+CACHE_EOF
+)
+echo "$_cache_json" > "$CACHE_FILE" 2>/dev/null || true