cortexhawk 3.2.0 → 3.3.1

package/mcp/README.md

@@ -15,6 +15,7 @@ cp mcp/context7.json .mcp.json
 
 | Server | Purpose | Requires |
 |---|---|---|
+| `github.json` | GitHub API — PRs, issues, reviews, repos | npx + `GITHUB_PERSONAL_ACCESS_TOKEN` env |
 | `context7.json` | Library docs lookup via Context7 | npx |
 | `sequential-thinking.json` | Step-by-step reasoning for complex problems | npx |
 | `puppeteer.json` | Browser automation and testing | npx |
@@ -35,3 +36,38 @@ Create or edit `.mcp.json` at your project root:
 ```
 
 Then restart Claude Code to activate.
+
+## GitHub Token Setup
+
+`github.json` requires a `GITHUB_PERSONAL_ACCESS_TOKEN`. Options (pick one):
+
+**Option 1 — `gh auth token` (recommended, zero extra credentials)**
+```bash
+# ~/.zshrc or ~/.bashrc
+export GITHUB_PERSONAL_ACCESS_TOKEN=$(gh auth token)
+```
+Reuses existing `gh` CLI auth — nothing new to manage.
+
+**Option 2 — `.claude/settings.json` (project-level, gitignored)**
+```json
+{
+  "env": {
+    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
+  }
+}
+```
+
+**Option 3 — Shell profile (direct)**
+```bash
+export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxx
+```
+
+**Option 4 — `direnv` (`.envrc`, add to `.gitignore`)**
+```bash
+export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxx
+```
+
+**Option 5 — Password manager CLI**
+```bash
+export GITHUB_PERSONAL_ACCESS_TOKEN=$(op read "op://vault/github-pat/token")
+```

package/mcp/context7.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "context7": {
       "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp@latest"]
+      "args": ["-y", "@upstash/context7-mcp@2.1.1"]
     }
   }
 }

package/mcp/github.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github@2025.4.8"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
+    }
+  }
+}

package/mcp/puppeteer.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "puppeteer": {
       "command": "npx",
-      "args": ["-y", "@anthropic-ai/mcp-server-puppeteer"]
+      "args": ["-y", "@modelcontextprotocol/server-puppeteer@2025.5.12"]
     }
   }
 }

package/mcp/sequential-thinking.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "sequential-thinking": {
       "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking@2025.12.18"]
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortexhawk",
-  "version": "3.2.0",
+  "version": "3.3.1",
   "description": "Open-source development toolkit for Claude Code — optimized agents, skills, commands, hooks, and modes",
   "bin": {
     "cortexhawk": "./cortexhawk"

package/profiles/api.json

@@ -23,5 +23,6 @@
     "workflow/commit",
     "workflow/confidence-check",
     "workflow/pr-review-comments"
-  ]
+  ],
+  "mcp": ["github", "sequential-thinking"]
 }

package/profiles/fullstack.json

@@ -23,5 +23,6 @@
     "workflow/commit",
     "workflow/confidence-check",
     "workflow/pr-review-comments"
-  ]
+  ],
+  "mcp": ["github", "context7", "sequential-thinking"]
 }

package/scripts/autodetect-profile.sh

@@ -46,7 +46,7 @@ for skill_file in "$CORTEXHAWK_DIR"/skills/*/*/SKILL.md; do
 done
 
 # --- Generate JSON ---
-PROFILE_FILE="/tmp/cortexhawk-autodetect-$$.json"
+PROFILE_FILE=$(mktemp /tmp/cortexhawk-autodetect-XXXXXX)
 SKILL_JSON=$(echo "$SKILLS" | tr ',' '\n' | sed 's/.*/    "&"/' | paste -sd ',' - | sed 's/,/,\n/g')
 cat > "$PROFILE_FILE" << EOF
 {

package/scripts/doctor.sh

@@ -0,0 +1,164 @@
+#!/bin/bash
+# doctor.sh — CortexHawk installation health diagnostics
+# Sourced by install.sh when --doctor is used
+# Uses shared functions: get_version, green, yellow
+# Uses globals: GLOBAL, TARGET, SCRIPT_DIR
+
+do_doctor() {
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.claude"
+    else
+        TARGET="$(pwd)/.claude"
+    fi
+
+    local ok=0 warn=0 err=0
+    _doc_ok()   { echo "  [OK]   $1"; ok=$((ok+1)); }
+    _doc_warn() { echo "  [WARN] $1"; warn=$((warn+1)); }
+    _doc_err()  { echo "  [ERR]  $1"; err=$((err+1)); }
+
+    # Header
+    local version="" profile="" target_cli_name=""
+    if [ -f "$TARGET/.cortexhawk-manifest" ]; then
+        version=$(grep -o '"version": "[^"]*"' "$TARGET/.cortexhawk-manifest" | head -1 | cut -d'"' -f4)
+        profile=$(grep -o '"profile": "[^"]*"' "$TARGET/.cortexhawk-manifest" | head -1 | cut -d'"' -f4)
+        target_cli_name=$(grep -o '"target": "[^"]*"' "$TARGET/.cortexhawk-manifest" | head -1 | cut -d'"' -f4)
+    fi
+    echo "CortexHawk Doctor"
+    echo "==================="
+    echo "  Installation: $TARGET"
+    echo "  Version:      ${version:-unknown}"
+    echo "  Profile:      ${profile:-unknown}"
+    echo "  Target:       ${target_cli_name:-claude}"
+    echo ""
+    echo "Checks:"
+
+    # 1. Manifest
+    if [ -f "$TARGET/.cortexhawk-manifest" ]; then
+        _doc_ok "Manifest present"
+    else
+        _doc_err "Manifest missing — run install.sh to create an installation"
+    fi
+
+    # 2. settings.json valid JSON
+    if [ -f "$TARGET/settings.json" ]; then
+        if command -v python3 >/dev/null 2>&1; then
+            if python3 -c "import json,sys; json.load(open(sys.argv[1]))" "$TARGET/settings.json" 2>/dev/null; then
+                _doc_ok "settings.json valid JSON"
+            else
+                _doc_err "settings.json invalid JSON"
+            fi
+        else
+            _doc_warn "settings.json present (python3 not available for validation)"
+        fi
+    else
+        _doc_warn "settings.json not found"
+    fi
+
+    # 3. Component counts (compare installed vs source)
+    for comp in agents commands modes; do
+        local installed=0 source_count=0
+        installed=$(find "$TARGET/$comp" -name "*.md" -type f 2>/dev/null | wc -l)
+        source_count=$(find "$SCRIPT_DIR/$comp" -name "*.md" -type f 2>/dev/null | wc -l)
+        if [ "$installed" -eq "$source_count" ] 2>/dev/null; then
+            _doc_ok "$installed/$source_count $comp installed"
+        elif [ "$installed" -gt 0 ] 2>/dev/null; then
+            _doc_warn "$installed/$source_count $comp installed"
+        else
+            _doc_err "0/$source_count $comp installed"
+        fi
+    done
+
+    # 4. Skills (profile-dependent, just count what's there)
+    local skills_installed=0 skills_source=0
+    skills_installed=$(find "$TARGET/skills" -name "*.md" -type f 2>/dev/null | wc -l)
+    skills_source=$(find "$SCRIPT_DIR/skills" -name "*.md" -type f 2>/dev/null | wc -l)
+    if [ "$skills_installed" -gt 0 ] 2>/dev/null; then
+        _doc_ok "$skills_installed/$skills_source skills installed (profile: ${profile:-all})"
+    else
+        _doc_err "No skills installed"
+    fi
+
+    # 5. Hooks executable
+    local hooks_ok=0 hooks_total=0
+    for hook in "$TARGET/hooks/"*.sh; do
+        [ -f "$hook" ] || continue
+        hooks_total=$((hooks_total+1))
+        if [ -x "$hook" ]; then
+            hooks_ok=$((hooks_ok+1))
+        else
+            _doc_warn "Hook not executable: $(basename "$hook")"
+        fi
+    done
+    if [ "$hooks_total" -gt 0 ]; then
+        if [ "$hooks_ok" -eq "$hooks_total" ]; then
+            _doc_ok "$hooks_ok/$hooks_total hooks executable"
+        fi
+    else
+        _doc_warn "No hooks found"
+    fi
+
+    # 6. compose.yml vs settings.json coherence
+    if [ -f "$TARGET/../hooks/compose.yml" ] || [ -f "$SCRIPT_DIR/hooks/compose.yml" ]; then
+        _doc_ok "compose.yml present"
+    fi
+
+    # 7. MCP configs
+    if [ -d "$TARGET/mcp" ] && [ "$(find "$TARGET/mcp" -type f 2>/dev/null | wc -l)" -gt 0 ]; then
+        _doc_ok "MCP configs present"
+    elif [ -d "$TARGET/mcp" ]; then
+        _doc_warn "MCP directory exists but empty"
+    fi
+
+    # 8. docs/ workspace
+    local project_root
+    project_root="$(dirname "$TARGET")"
+    if [ -d "$project_root/docs" ]; then
+        _doc_ok "docs/ workspace exists"
+    else
+        _doc_warn "docs/ workspace missing"
+    fi
+
+    # 9. Broken symlinks in docs/plans/
+    local broken=0
+    if [ -d "$project_root/docs/plans" ]; then
+        while IFS= read -r link; do
+            [ -z "$link" ] && continue
+            _doc_warn "Broken symlink: $link"
+            broken=$((broken+1))
+        done < <(find "$project_root/docs/plans" -type l ! -exec test -e {} \; -print 2>/dev/null)
+        [ "$broken" -eq 0 ] && _doc_ok "No broken symlinks in docs/plans/"
+    fi
+
+    # 10. git-workflow.conf
+    if [ -f "$TARGET/git-workflow.conf" ]; then
+        _doc_ok "git-workflow.conf present"
+    else
+        _doc_warn "git-workflow.conf not found (run --init to configure)"
+    fi
+
+    # 11. CLAUDE.md at project root
+    if [ -f "$project_root/CLAUDE.md" ]; then
+        _doc_ok "CLAUDE.md present at project root"
+    else
+        _doc_warn "CLAUDE.md not found at project root"
+    fi
+
+    # 12. Version match source vs manifest
+    if [ -n "$version" ]; then
+        local source_version
+        source_version=$(get_version)
+        if [ "$version" = "$source_version" ]; then
+            _doc_ok "Version match: source $source_version = manifest $version"
+        else
+            _doc_warn "Version mismatch: source $source_version != manifest $version (run --update)"
+        fi
+    fi
+
+    # Summary
+    echo ""
+    echo "Summary: $ok OK, $warn WARN, $err ERR"
+
+    # Exit code: 1 if any errors
+    [ "$err" -gt 0 ] && exit 1
+    return 0
+}

package/scripts/install-claude.sh

@@ -0,0 +1,179 @@
+#!/bin/bash
+# install-claude.sh — CortexHawk installer for Claude Code
+# Sourced by install.sh for fresh Claude Code installations
+# Uses shared functions: copy_all_components, count_component_files, generate_hooks_config,
+#   write_manifest, create_docs_workspace, run_audit, update_gitignore, setup_templates,
+#   install_git_post_merge_hook, do_quickstart
+
+install_claude() {
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.claude"
+    else
+        TARGET="$(pwd)/.claude"
+    fi
+
+    if [ "$DRY_RUN" = true ]; then
+        echo "CortexHawk Dry Run (install)"
+        echo "=============================="
+        echo "  Target:  $TARGET"
+        echo "  Profile: ${PROFILE:-all}"
+        echo ""
+        echo "Would install:"
+        count_component_files "$SCRIPT_DIR"
+        echo "  settings.json"
+        [ ! -f "$(pwd)/CLAUDE.md" ] && echo "  CLAUDE.md"
+        echo ""
+        echo "No files were modified (dry run)."
+        return
+    fi
+
+    echo "Installing for Claude Code to project: $TARGET"
+
+    copy_all_components "$SCRIPT_DIR" "$TARGET" "$PROFILE"
+
+    # Copy agent personas from project root if present
+    local project_root
+    project_root="$(dirname "$TARGET")"
+    if [ -d "$project_root/.cortexhawk-agents" ]; then
+        cp -r "$project_root/.cortexhawk-agents/"*.md "$TARGET/agents/" 2>/dev/null || true
+        local persona_count
+        persona_count=$(find "$project_root/.cortexhawk-agents" -name "*.md" -type f 2>/dev/null | wc -l | tr -d ' ')
+        [ "$persona_count" -gt 0 ] && echo "  Loaded $persona_count agent persona(s) from .cortexhawk-agents/"
+    fi
+
+    local hooks_json
+    hooks_json=$(generate_hooks_config "$SCRIPT_DIR/hooks/compose.yml" ".claude/hooks")
+    if [ ! -f "$TARGET/settings.json" ]; then
+        # Fresh install: generate settings.json from scratch
+        if [ -n "$hooks_json" ] && [ "$hooks_json" != "{}" ]; then
+            echo "$hooks_json" | python3 -c "
+import json, sys
+hooks = json.load(sys.stdin)
+with open(sys.argv[1]) as f:
+    permissions = json.load(f).get('permissions', {})
+with open(sys.argv[2], 'w') as f:
+    json.dump({'permissions': permissions, 'hooks': hooks}, f, indent=2)
+    f.write('\n')
+" "$SCRIPT_DIR/settings.json" "$TARGET/settings.json"
+            echo "  Generated settings.json from hooks/compose.yml"
+        else
+            cp "$SCRIPT_DIR/settings.json" "$TARGET/settings.json"
+        fi
+    else
+        # Merge: preserve user customizations, add new hooks + permissions
+        if ! command -v python3 >/dev/null 2>&1; then
+            echo "  Warning: python3 not found — copying settings.json (merge skipped)"
+            cp "$SCRIPT_DIR/settings.json" "$TARGET/settings.json"
+        else
+        python3 -c "
+import json, sys, shutil, os
+
+raw = sys.stdin.read().strip()
+hooks = json.loads(raw) if raw else {}
+
+# Load current settings (tolerate corrupted JSON)
+try:
+    with open(sys.argv[1]) as f:
+        current = json.load(f)
+except Exception:
+    backup = sys.argv[1] + '.bak'
+    if os.path.isfile(sys.argv[1]):
+        shutil.copy2(sys.argv[1], backup)
+        print(f'  Warning: settings.json corrupted — backed up to {os.path.basename(backup)}', file=sys.stderr)
+    current = {}
+
+try:
+    with open(sys.argv[2]) as f:
+        source = json.load(f)
+except Exception:
+    source = {}
+
+changes = []
+
+# Merge hooks (regenerate from compose.yml)
+if hooks and hooks != {}:
+    current['hooks'] = hooks
+    changes.append('hooks regenerated')
+
+# Merge permissions (union: keep user additions + add new from source)
+src_perms = source.get('permissions', {})
+cur_perms = current.get('permissions', {})
+for key in ('allow', 'deny'):
+    src_list = src_perms.get(key, [])
+    cur_list = cur_perms.get(key, [])
+    added = [p for p in src_list if p not in cur_list]
+    if added:
+        cur_list.extend(added)
+        changes.append(f'{len(added)} new {key} permission(s)')
+    cur_perms[key] = cur_list
+current['permissions'] = cur_perms
+
+with open(sys.argv[1], 'w') as f:
+    json.dump(current, f, indent=2)
+    f.write('\n')
+
+if changes:
+    print('  Merged settings.json: ' + ', '.join(changes))
+else:
+    print('  settings.json up to date — no merge needed')
+" "$TARGET/settings.json" "$SCRIPT_DIR/settings.json" <<< "${hooks_json:-}"
+        fi
+    fi
+
+    PROJECT_ROOT="$(dirname "$TARGET")"
+    if [ ! -f "$PROJECT_ROOT/CLAUDE.md" ]; then
+        cp "$SCRIPT_DIR/CLAUDE.md" "$PROJECT_ROOT/CLAUDE.md"
+    else
+        echo "CLAUDE.md already exists — skipping"
+    fi
+
+    # Git workflow config (interactive in --init, defaults otherwise)
+    if [ "$GLOBAL" = false ]; then
+        if [ "$INIT_MODE" = true ]; then
+            source "$SCRIPT_DIR/scripts/git-workflow-init.sh" "$PROJECT_ROOT" "$TARGET"
+        elif [ ! -f "$TARGET/git-workflow.conf" ]; then
+            # Apply sensible defaults without asking
+            GIT_BRANCHING="direct-main"
+            GIT_COMMIT_CONVENTION="conventional"
+            GIT_PR_PREFERENCE="on-demand"
+            GIT_AUTO_PUSH="after-commit"
+            GIT_WORK_BRANCH=""
+            source "$SCRIPT_DIR/scripts/git-workflow-init.sh" "$PROJECT_ROOT" "$TARGET"
+        fi
+    fi
+
+    chmod +x "$TARGET/hooks/"*.sh 2>/dev/null || true
+
+    # Write manifest for future updates
+    write_manifest "$TARGET" "$PROFILE" "claude" false
+
+    # Create docs/ workspace for agent outputs (local only)
+    if [ "$GLOBAL" = false ]; then
+        create_docs_workspace "$(dirname "$TARGET")"
+    fi
+
+    run_audit "$(dirname "$TARGET")"
+    update_gitignore "$(dirname "$TARGET")" ".claude"
+    setup_templates "$(dirname "$TARGET")"
+
+    # Offer native git post-merge hook (opt-in, local only, interactive only)
+    if [ "$GLOBAL" = false ] && [ -d "$(pwd)/.git" ]; then
+        if [ -t 0 ]; then
+            echo ""
+            read -r -p "Install native git post-merge hook (auto-cleanup after merges)? [y/N]: " _hook_confirm
+            case "$_hook_confirm" in
+                [yY]*) install_git_post_merge_hook "$(pwd)" ;;
+                *) echo "  → post-merge hook skipped (run: cortexhawk install --post-merge-hook to add later)" ;;
+            esac
+        fi
+    fi
+
+    echo ""
+    echo "CortexHawk installed successfully for Claude Code!"
+    echo ""
+    echo "  35 commands | 20 agents | 36 skills | 11 hooks | 7 modes"
+    echo ""
+    do_quickstart
+    echo ""
+    echo "  To activate: exit Claude Code (ctrl+c) and relaunch 'claude' in this directory."
+}

package/scripts/interactive-init.sh

@@ -93,7 +93,7 @@ case "$skill_choice" in
         fi
 
         # Generate custom profile JSON
-        PROFILE_FILE="/tmp/cortexhawk-custom-$(date +%s).json"
+        PROFILE_FILE=$(mktemp /tmp/cortexhawk-custom-XXXXXX)
         SKILL_LINES=""
         SKILL_COUNT=0
         for category in $SELECTED_CATS; do
@@ -133,7 +133,8 @@ if [ -n "$SKILLSMP_KEY" ]; then
     else
         echo "SKILLSMP_API_KEY=$SKILLSMP_KEY" >> .env
     fi
-    green "  → saved to .env"
+    chmod 600 .env
+    green "  → saved to .env (permissions: owner-only)"
 else
     yellow "  → skipped (use --search with local REGISTRY.md only)"
 fi

package/scripts/lint-guard-runner.sh

@@ -0,0 +1,132 @@
+#!/bin/bash
+# lint-guard-runner.sh — Formatter/linter execution with detection cache + parallel linters
+# Called by hooks/lint-guard.sh
+# Formatters: sequential (git add must not race). Linters: parallel (check-only).
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+[ -z "$REPO_ROOT" ] && exit 0
+STAGED=$(git diff --cached --name-only 2>/dev/null)
+[ -z "$STAGED" ] && exit 0
+
+# Opt-out config
+CONF_FILE="$REPO_ROOT/.claude/git-workflow.conf"
+LINT_SKIP=$(grep '^LINT_SKIP=' "$CONF_FILE" 2>/dev/null | cut -d= -f2 | tr ',' '\n')
+
+lint_cfg() {
+  local key="$1" default="${2:-auto}"
+  if [ -f "$REPO_ROOT/.cortexhawk-lint.yml" ]; then
+    local val
+    val=$(grep -E "^\s+$key:" "$REPO_ROOT/.cortexhawk-lint.yml" 2>/dev/null \
+      | sed 's/.*: *//' | tr -d ' \r')
+    echo "${val:-$default}"
+  else
+    echo "$default"
+  fi
+}
+
+TIMEOUT_SECS=$(lint_cfg "timeout" "30")
+case "$TIMEOUT_SECS" in ''|*[!0-9]*|0) TIMEOUT_SECS=30 ;; esac
+FAIL_ON_FMT=$(lint_cfg "fail_on_formatter" "false")
+TIMEOUT_CMD=""
+command -v timeout  &>/dev/null && TIMEOUT_CMD="timeout $TIMEOUT_SECS"
+command -v gtimeout &>/dev/null && [ -z "$TIMEOUT_CMD" ] && TIMEOUT_CMD="gtimeout $TIMEOUT_SECS"
+
+# --- DETECTION CACHE (1hr TTL, safe key=value, no source) ---
+mkdir -p "$REPO_ROOT/.claude" 2>/dev/null || true
+CACHE="$REPO_ROOT/.claude/lint-guard-cache"
+_mtime() { stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null || date +%s; }
+[ -f "$CACHE" ] && [ $(( $(date +%s) - $(_mtime "$CACHE") )) -gt 3600 ] && rm -f "$CACHE"
+cache_get() { grep -m1 "^$1=" "$CACHE" 2>/dev/null | cut -d= -f2; }
+cache_set() { local _tmp; _tmp=$(mktemp "${CACHE}.XXXXXX"); { grep -v "^$1=" "$CACHE" 2>/dev/null; echo "$1=$2"; } > "$_tmp" && mv "$_tmp" "$CACHE" || rm -f "$_tmp"; }
+
+# --- TOOL DETECTION ---
+STAGED_JS=$(echo "$STAGED" | grep -E '\.(js|ts|jsx|tsx|mjs|cjs)$' || true)
+STAGED_CSS=$(echo "$STAGED" | grep -E '\.(css|scss|sass|less)$' || true)
+STAGED_PY=$(echo "$STAGED" | grep -E '\.py$' || true)
+STAGED_RS=$(echo "$STAGED" | grep -E '\.rs$' || true)
+STAGED_GO=$(echo "$STAGED" | grep -E '\.go$' || true)
+
+has_config() {
+  case "$1" in
+    prettier)  ls "$REPO_ROOT"/.prettierrc* "$REPO_ROOT"/prettier.config.* 2>/dev/null | grep -q . \
+               || grep -qs '"prettier"' "$REPO_ROOT/package.json" 2>/dev/null ;;
+    eslint)    ls "$REPO_ROOT"/.eslintrc* "$REPO_ROOT"/eslint.config.* 2>/dev/null | grep -q . ;;
+    black)     grep -qs '\[tool\.black\]' "$REPO_ROOT/pyproject.toml" 2>/dev/null ;;
+    flake8)    [ -f "$REPO_ROOT/.flake8" ] || grep -qs '\[flake8\]' "$REPO_ROOT/setup.cfg" 2>/dev/null ;;
+    mypy)      grep -qs '\[tool\.mypy\]' "$REPO_ROOT/pyproject.toml" 2>/dev/null || [ -f "$REPO_ROOT/mypy.ini" ] ;;
+    stylelint) ls "$REPO_ROOT"/.stylelintrc* "$REPO_ROOT"/stylelint.config.* 2>/dev/null | grep -q . ;;
+    rustfmt)   [ -f "$REPO_ROOT/rustfmt.toml" ] || [ -f "$REPO_ROOT/.rustfmt.toml" ] ;;
+    gofmt)     true ;;
+  esac
+}
+
+c_has_config() {
+  local key="HAS_$(echo "$1" | tr '[:lower:]' '[:upper:]')"
+  local cached; cached=$(cache_get "$key")
+  if [ -n "$cached" ]; then [ "$cached" = "1" ]; return $?; fi
+  if has_config "$1"; then cache_set "$key" "1"; return 0
+  else cache_set "$key" "0"; return 1; fi
+}
+
+is_enabled() {
+  echo "$LINT_SKIP" | grep -qx "$1" && return 1
+  local val; val=$(lint_cfg "$1"); [ "$val" != "false" ]
+}
+
+tool_ok() { command -v "$1" &>/dev/null; }
+
+# Pre-populate cache before parallel stage to avoid write races
+for _t in prettier eslint black flake8 mypy stylelint rustfmt gofmt; do
+  c_has_config "$_t" >/dev/null 2>&1
+done
+
+# --- FORMATTERS (sequential — git add must not race) ---
+run_formatter() {
+  local name="$1" cmd="$2" files="$3"
+  is_enabled "$name" || return 0
+  c_has_config "$name" || return 0
+  tool_ok "$name" || { echo "lint-guard: $name not in PATH, skipping"; return 0; }
+  [ -z "$files" ] && return 0
+  echo "lint-guard: $name (auto-fix)..."
+  # shellcheck disable=SC2086
+  if echo "$files" | tr '\n' '\0' | xargs -0 $TIMEOUT_CMD $cmd 2>/dev/null; then
+    echo "$files" | tr '\n' '\0' | xargs -0 git add 2>/dev/null || true
+  else
+    echo "lint-guard: $name formatter failed" >&2
+    [ "$FAIL_ON_FMT" = "true" ] && exit 2
+  fi
+}
+
+[ -n "$STAGED_JS" ]  && run_formatter "prettier"  "prettier --write" "$STAGED_JS"
+[ -n "$STAGED_CSS" ] && run_formatter "stylelint" "stylelint --fix"  "$STAGED_CSS"
+[ -n "$STAGED_PY" ]  && run_formatter "black"     "black"            "$STAGED_PY"
+[ -n "$STAGED_RS" ]  && run_formatter "rustfmt"   "rustfmt"          "$STAGED_RS"
+[ -n "$STAGED_GO" ]  && run_formatter "gofmt"     "gofmt -w"         "$STAGED_GO"
+
+# --- LINTERS (parallel — check-only, no file writes) ---
+ERR_DIR=$(mktemp -d)
+trap 'rm -rf "$ERR_DIR"' EXIT
+
+run_linter_bg() {
+  local name="$1" cmd="$2" files="$3"
+  is_enabled "$name" || return 0
+  c_has_config "$name" || return 0
+  tool_ok "$name" || { echo "lint-guard: $name not in PATH, skipping"; return 0; }
+  [ -z "$files" ] && return 0
+  echo "lint-guard: $name (check)..."
+  # shellcheck disable=SC2086
+  if ! echo "$files" | tr '\n' '\0' | xargs -0 $TIMEOUT_CMD $cmd 2>&1; then
+    echo "BLOCKED by lint-guard: $name errors found. Fix above, re-stage, and retry." >&2
+    touch "$ERR_DIR/$name"
+  fi
+}
+
+# Output from parallel linters may interleave on screen; ERR_DIR signals are reliable regardless.
+[ -n "$STAGED_JS" ] && run_linter_bg "eslint" "eslint --max-warnings=0" "$STAGED_JS" &
+[ -n "$STAGED_PY" ] && run_linter_bg "flake8" "flake8"                  "$STAGED_PY" &
+[ -n "$STAGED_PY" ] && run_linter_bg "mypy"   "mypy --no-error-summary" "$STAGED_PY" &
+wait
+
+ERRORS=$(find "$ERR_DIR" -type f 2>/dev/null | wc -l | tr -d ' ')
+[ "$ERRORS" -gt 0 ] && exit 2
+exit 0