@arthai/agents 1.0.0

package/dist/plugins/scalpel/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/scalpel/skills/ci-fix/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: ci-fix
+description: "Auto-remediate CI, staging, and production failures. 3-attempt retry with investigation. Discord alert on exhaustion. Usage: /ci-fix [ci|staging|prod] [branch]"
+user-invocable: true
+arguments: "<mode> <branch>"
+---
+
+# /ci-fix — Unified Auto-Remediation
+
+Automatically diagnose and fix CI failures, staging deploy failures, and production deploy failures. Retries up to 3 times. Alerts on Discord `#deployments` if all attempts fail.
+
+## Project Context Discovery (Deep)
+
+Before attempting any fix, understand the FULL CI/CD landscape.
+
+### Step 1: Read existing context
+
+Read in this order (skip gracefully if missing):
+1. `CLAUDE.md` — Test Commands table, Infrastructure table
+2. `.claude/project-profile.md` — CI platform, test frameworks (from /calibrate)
+3. `.claude/knowledge/skills/ci-fix.md` — Past CI failures and patterns
+4. `.claude/qa-knowledge/incidents/` — Past incidents from CI failures
+5. `.claude/qa-knowledge/bug-patterns.md` — Known failure patterns
+
+### Step 2: Detect CI platform
+
+Don't assume GitHub Actions. Detect the actual CI system:
+
+| Signal | CI Platform | How to get logs | How to check status | How to retry |
+|--------|------------|----------------|--------------------|----|
+| `.github/workflows/*.yml` | GitHub Actions | `gh run view <id> --log-failed` | `gh run list --branch <b>` | `gh run rerun <id>` |
+| `.gitlab-ci.yml` | GitLab CI | `glab ci view --branch <b>` | `glab ci status` | `glab ci retry` |
+| `Jenkinsfile` | Jenkins | Jenkins API: `/job/<name>/lastBuild/consoleText` | Jenkins API: `/job/<name>/lastBuild/api/json` | Jenkins API: `/job/<name>/build` |
+| `.circleci/config.yml` | CircleCI | `circleci` CLI or API | `circleci` CLI | API trigger |
+| `bitbucket-pipelines.yml` | Bitbucket Pipelines | Bitbucket API | Bitbucket API | API trigger |
+| `.buildkite/pipeline.yml` | Buildkite | `buildkite-agent` or API | API | `bk build retry` |
+| `azure-pipelines.yml` | Azure Pipelines | `az pipelines runs show` | `az pipelines runs list` | `az pipelines run` |
+| `.travis.yml` | Travis CI | Travis API | Travis API | API trigger |
+| `Taskfile.yml` + CI wrapper | Task-based | Depends on wrapper CI | Depends | Depends |
+
+If MULTIPLE CI systems detected (e.g., GitHub Actions for CI + ArgoCD for deploy), document both.
+
+### Step 3: Detect test infrastructure
+
+Map the project's test stack so fixes target the right layer:
+
+| Signal | Test Layer | Fix Strategy |
+|--------|-----------|-------------|
+| `pytest.ini` / `pyproject.toml [tool.pytest]` | Python unit/integration | Fix Python code, run `pytest` locally |
+| `jest.config.*` / `vitest.config.*` | JS/TS unit tests | Fix JS/TS code, run `npm test` locally |
+| `playwright.config.*` / `cypress.config.*` | E2E tests | May need running services, check docker-compose |
+| `ruff.toml` / `.flake8` / `.eslintrc.*` | Linting | Auto-fix with `ruff check --fix` / `eslint --fix` |
+| `mypy.ini` / `tsconfig.json` | Type checking | Fix type annotations |
+| `Dockerfile` / `docker-compose.test.yml` | Containerized tests | Build container first, then run |
+| `tox.ini` | Multi-env Python testing | Run specific tox env |
+| `Makefile` with test targets | Make-based | Run `make test` |
+
+### Step 4: Detect environment requirements
+
+CI often fails because of environment differences. Check:
+
+```bash
+# What Python/Node/Go version does CI use?
+grep -r "python-version\|node-version\|go-version" .github/workflows/ .gitlab-ci.yml 2>/dev/null
+
+# What services does CI spin up? (postgres, redis, etc.)
+grep -r "services:" .github/workflows/ 2>/dev/null
+grep -r "image:" .gitlab-ci.yml 2>/dev/null
+
+# What env vars does CI set?
+grep -r "env:" .github/workflows/ 2>/dev/null | grep -v "#"
+
+# What secrets are used?
+grep -r "secrets\." .github/workflows/ 2>/dev/null
+```
+
+### Step 5: Check for known flaky patterns
+
+Before investigating a failure, check if it's a known issue:
+
+```bash
+# Check past CI fix incidents
+grep -l "ci-fix\|CI\|flaky" .claude/qa-knowledge/incidents/ 2>/dev/null
+
+# Check knowledge base for CI patterns
+cat .claude/knowledge/skills/ci-fix.md 2>/dev/null | grep -A3 "## Patterns"
+```
+
+If a known flaky test matches the failure, report it instead of debugging.
+
+### Step 6: Recommend CI improvements
+
+After every fix (or on first run), check for CI best practices:
+
+```
+CI recommendations for {project}:
+  ⚠ No dependency caching — CI runs will be slow
+    Add: actions/cache for node_modules / .venv / cargo
+  ⚠ No test parallelism — tests run sequentially
+    Add: pytest-xdist / jest --workers / go test -parallel
+  ⚠ No test timeout — flaky tests can hang forever
+    Add: timeout-minutes in workflow / pytest --timeout=30
+  ⚠ No retry for flaky tests — one flake fails the whole run
+    Add: pytest-rerunfailures / jest --retry
+  ⚠ Services not health-checked — tests may start before DB is ready
+    Add: health check options to service containers
+  ⚠ No artifact upload on failure — can't debug after the run
+    Add: actions/upload-artifact for test reports on failure
+```
+
+## Mode Detection
+
+Parse from arguments:
+- No argument / `ci` → **CI mode** — fix GitHub Actions lint/test/build failures
+- `staging` → **Staging mode** — investigate + fix staging deployment failures
+- `prod` / `production` → **Prod mode** — investigate + fix production deployment failures
+- Optional second arg: branch name (default: current branch)
+
+## Architecture
+
+```
+Failure detected → /ci-fix invoked
+  → Determine mode (CI / staging / prod)
+  → Attempt 1: diagnose → fix → verify → push/redeploy
+    → Green? DONE
+    → Still failing? Attempt 2 (different strategy)
+  → Attempt 2: re-diagnose → fix → verify → push/redeploy
+    → Green? DONE
+    → Still failing? Attempt 3 (escalate approach)
+  → Attempt 3: deep investigation → fix → verify → push/redeploy
+    → Green? DONE
+    → Still failing? → Discord alert + QA incident file
+```
+
+---
+
+## CI Mode (default)
+
+Fix GitHub Actions lint, type, test, and build failures.
+
+### Per-Attempt Steps
+
+#### Step 1: Identify the failure
+
+```bash
+BRANCH=$(git branch --show-current)
+gh run list --branch "$BRANCH" --limit 5 --json databaseId,conclusion,status,name
+```
+
+Get failed run logs:
+```bash
+gh run view <FAILED_RUN_ID> --log-failed 2>&1 | tail -200
+```
+
+#### Step 2: Classify and fix
+
+| Category | Indicators | Fix Strategy |
+|----------|-----------|--------------|
+| **Lint** | ruff/eslint errors | Auto-fix tools scoped to specific directories |
+| **Type errors** | tsc/mypy failures | Read error file:line, fix type annotation |
+| **Test failures** | pytest/jest failures | Read failing test + source, fix root cause |
+| **Build failures** | build errors | Read error, fix import/export/config |
+| **Migration** | Alembic/Django errors | Fix migration file |
+| **Dependency** | pip/npm install failures | Fix requirements/package.json |
+
+**Attempt escalation:**
+- Attempt 1: Apply the obvious fix (auto-fix tools, direct code fix)
+- Attempt 2: Read more context (surrounding code, related tests, recent commits)
+- Attempt 3: Deep investigation — read git log, compare against last green commit
+
+#### Step 3: Verify locally (MANDATORY before pushing)
+
+Run ONLY the checks that failed — use commands from CLAUDE.md Test Commands table.
+
+#### Step 4: Commit, push, wait for CI
+
+```bash
+git add <only_changed_files>
+git commit -m "$(cat <<'EOF'
+fix: <category> — <what was fixed>
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+git push
+```
+
+Wait for CI result:
+```bash
+sleep 90 && gh run list --branch "$BRANCH" --limit 1 --json conclusion,status
+```
+
+---
+
+## Staging Mode
+
+Investigate and fix staging deployment failures.
+
+1. **Diagnose**: Check deployment platform health endpoints (from CLAUDE.md), get deploy logs
+2. **Classify**: Migration failed, missing env var, health timeout, build error, runtime crash
+3. **Fix**: Code fix → verify locally → push. Env var fix → use platform tools.
+4. **Verify**: Wait for deploy, check all health endpoints
+
+---
+
+## Prod Mode
+
+Same as staging but with **extra caution**:
+- NEVER modify production database directly
+- NEVER run destructive commands against production
+- Fix code locally → push to main → platform auto-deploys
+- On attempt 3, consider rollback: `git revert HEAD --no-edit && git push`
+
+---
+
+## After 3 Failed Attempts (ALL MODES)
+
+### 1. Discord alert (if discord-ops is configured)
+
+```
+mcp__discord-mcp__send-message(
+  channel: "deployments",
+  message: "Auto-Fix Failed — 3 attempts exhausted\n\nMode: {mode}\nBranch: {branch}\nError: {last_error_summary}\n\nAction needed: Manual review required."
+)
+```
+
+### 2. Write QA incident
+
+Create `.claude/qa-knowledge/incidents/{date}-autofix-exhausted-{slug}.md` with root cause, how QA missed it, and regression test recommendation.
+
+### 3. Report to user
+
+```
+Auto-fix exhausted after 3 attempts ({mode} mode) on `{branch}`.
+QA incident logged.
+Manual review required.
+```
+
+---
+
+## Rules (ALL MODES)
+
+- **NEVER** run lint auto-fix on the entire repo — scope to specific directories
+- **NEVER** modify dependency files unless that's the actual failure
+- **NEVER** add `# type: ignore` or `# noqa` to suppress errors — fix them properly
+- **NEVER** delete or skip tests — fix the underlying issue
+- **NEVER** use `railway up` or equivalent — always push to git for auto-deploy
+- **ALWAYS** verify locally before pushing
+- **ALWAYS** scope fixes narrowly — only touch files that caused the failure
+- **ALWAYS** try a DIFFERENT strategy on each retry
+- Maximum 3 attempts. After that, alert humans.
+- If fix requires architectural changes → report and stop, don't attempt large refactors
+
+## Knowledge Base Integration
+
+### On every /ci-fix invocation:
+1. **Read** `.claude/knowledge/skills/ci-fix.md` for past failure patterns
+2. **Read** `.claude/qa-knowledge/incidents/` for similar past CI incidents
+3. **Match** current failure against known patterns before investigating
+
+### After every fix (success or exhaustion):
+1. **Append** to `.claude/knowledge/skills/ci-fix.md`:
+   ```
+   ### {date} — {failure type}
+   **CI Platform**: {platform}
+   **Category**: {lint | type | test | build | migration | dependency | flaky}
+   **Root cause**: {what was wrong}
+   **Fix**: {what was done}
+   **Attempts**: {N}
+   **Was it a known pattern?**: {yes — matched incident X | no — new pattern}
+   **Prevention**: {how to avoid next time}
+   ```
+
+2. If failure was a NEW pattern (not in knowledge base):
+   - Add to `.claude/qa-knowledge/bug-patterns.md` under CI section
+   - Consider: should this become a pre-push check?
+
+3. If fix took 3 attempts (exhaustion):
+   - Create incident: `.claude/qa-knowledge/incidents/{date}-ci-exhaust-{slug}.md`
+   - Flag as systemic if same category failed 3+ times in knowledge base
+
+### /calibrate Integration
+
+When `/calibrate` runs, it reads CI configuration to understand the project's test pipeline.
+The /ci-fix skill contributes:
+1. **CI platform detection** → /calibrate writes to project profile
+2. **Test infrastructure map** → /calibrate includes in profile "Testing Conventions" section
+3. **Environment requirements** → /calibrate notes version mismatches between local and CI
+4. **Flaky test inventory** → /calibrate includes in recommendations
+5. **CI improvement recommendations** → /calibrate includes in "Recommended Tools" section
+
+If `/calibrate` hasn't run, /ci-fix does its own discovery and recommends running `/calibrate`.
+If `/calibrate` has run, /ci-fix reads the profile instead of re-discovering.