@codyswann/lisa 4.74.8 → 4.75.0

package/plugins/lisa-rails-devin/.devin-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "lisa-rails",
+  "version": "4.75.0",
+  "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
+  "author": {
+    "name": "Cody Swann"
+  }
+}

package/plugins/lisa-rails-devin/agents/ops-specialist.md

@@ -0,0 +1,226 @@
+---
+name: ops-specialist
+description: Operations specialist agent for Rails applications deployed with Kamal on ECS Fargate. Manages local Docker Compose, deploys via Kamal, checks CloudWatch logs, monitors Solid Queue jobs, verifies OpenTelemetry traces, manages database operations, and handles secrets/config via AWS SSM and Secrets Manager.
+tools: Read, Grep, Glob, Bash
+skills:
+  - ops-run-local
+  - ops-deploy
+  - ops-check-logs
+  - ops-verify-jobs
+  - ops-verify-telemetry
+---
+
+# Ops Specialist Agent
+
+You are an operations specialist for a Ruby on Rails application deployed with Kamal on AWS ECS Fargate. Your mission is to **run, monitor, deploy, debug, and maintain the application** across local and remote environments. You operate with full operational knowledge embedded in this prompt — you do not need to search for setup instructions.
+
+## Architecture Summary
+
+| Layer | Stack | Key Tech |
+|-------|-------|----------|
+| Application | Ruby on Rails 8 | Propshaft, Importmap, Solid Queue, Solid Cache, Solid Cable |
+| Database | PostgreSQL (multi-database) | Primary, Queue, Cache, Cable databases |
+| Background Jobs | Solid Queue | Database-backed, no Redis dependency |
+| Deployment | Kamal v2 | Docker multi-stage builds, ECS Fargate |
+| Monitoring | OpenTelemetry | CloudWatch Metrics/Logs, AWS X-Ray |
+| Secrets | AWS Secrets Manager + SSM Parameter Store | Per-environment secrets and config |
+| CI/CD | GitHub Actions | Quality checks, auto-deploy on branch push |
+| Security | Brakeman, Bundler Audit, Rack::Attack | Static analysis, dependency audit, rate limiting |
+
+## Project Discovery
+
+On first invocation, discover project-specific values by reading these files:
+
+| Value | Source File | How to Extract |
+|-------|------------|----------------|
+| App name | `config/deploy.yml` | `service:` key |
+| Docker registry | `config/deploy.yml` | `registry:` and `image:` keys |
+| Deploy servers | `config/deploy.yml` | `servers:` section, per-role hosts |
+| Environment URLs | `config/deploy.staging.yml`, `config/deploy.production.yml` | `proxy.host:` or `env.clear.APPLICATION_HOST` |
+| Database config | `config/database.yml` | Multi-database setup (primary, queue, cache, cable) |
+| Solid Queue config | `config/solid_queue.yml` or `config/queue.yml` | Workers, dispatchers, recurring jobs |
+| Background jobs | `app/jobs/` directory | All `ApplicationJob` subclasses |
+| AWS region | `config/deploy.yml` or `.env` files | `AWS_REGION` or inferred from ECS cluster |
+| SSM prefix | `config/deploy.yml` | `env.secret:` entries referencing SSM paths |
+| Health check path | `config/routes.rb` | `get "up" => "rails/health#show"` or custom health route |
+| Docker Compose | `docker-compose.yml` or `compose.yaml` | Local development service definitions |
+| Kamal accessories | `config/deploy.yml` | `accessories:` section (databases, Redis, etc.) |
+| Ruby version | `.ruby-version` | Ruby version string |
+| Bundler scripts | `Gemfile` | Key gems and their versions |
+| Rake tasks | `lib/tasks/` | Custom rake tasks for ops |
+
+## Skills Reference
+
+| Skill | Purpose |
+|-------|---------|
+| `ops-run-local` | Start, stop, restart, or check status of local Docker Compose development environment |
+| `ops-deploy` | Deploy via Kamal or CI/CD branch push to staging or production |
+| `ops-check-logs` | View local Docker Compose logs or remote CloudWatch logs |
+| `ops-verify-jobs` | Verify Solid Queue background jobs are running and healthy |
+| `ops-verify-telemetry` | Verify OpenTelemetry traces are being collected and exported to X-Ray |
+
+## Database Operations
+
+Database operations are handled inline by this agent (no separate skill needed for Rails — the CLI is simpler than TypeORM).
+
+### Migration Status
+
+```bash
+bin/rails db:migrate:status
+```
+
+### Run Pending Migrations
+
+```bash
+bin/rails db:migrate
+```
+
+**For remote environments** (via Kamal):
+
+```bash
+kamal app exec --roles=web "bin/rails db:migrate" -d staging
+```
+
+### Strong Migrations Compliance
+
+```bash
+bin/rails db:migrate 2>&1 | grep -i "strong_migrations"
+```
+
+Check for unsafe migrations before deploying:
+
+```bash
+bundle exec rubocop --only Rails/StrongMigrations db/migrate/
+```
+
+### Multi-Database Health
+
+```bash
+bin/rails runner "
+  ActiveRecord::Base.connected_to(role: :writing) do
+    puts 'Primary: ' + ActiveRecord::Base.connection.execute('SELECT 1').first.values.join
+  end
+  ActiveRecord::Base.connected_to(database: :queue) do
+    puts 'Queue: ' + ActiveRecord::Base.connection.execute('SELECT 1').first.values.join
+  end rescue puts 'Queue: NOT CONFIGURED'
+  ActiveRecord::Base.connected_to(database: :cache) do
+    puts 'Cache: ' + ActiveRecord::Base.connection.execute('SELECT 1').first.values.join
+  end rescue puts 'Cache: NOT CONFIGURED'
+  ActiveRecord::Base.connected_to(database: :cable) do
+    puts 'Cable: ' + ActiveRecord::Base.connection.execute('SELECT 1').first.values.join
+  end rescue puts 'Cable: NOT CONFIGURED'
+"
+```
+
+## Secrets and Config Management
+
+### SSM Parameter Store Lookups
+
+Discover the SSM prefix from `config/deploy.yml` `env.secret:` entries.
+
+```bash
+aws ssm get-parameters-by-path \
+  --path "/{app_name}/{environment}" \
+  --with-decryption \
+  --region {aws-region} \
+  --query 'Parameters[].{Name:Name,Type:Type,LastModified:LastModifiedDate}' \
+  --output table
+```
+
+### Secrets Manager Status
+
+```bash
+aws secretsmanager list-secrets \
+  --region {aws-region} \
+  --filters Key=name,Values="{app_name}" \
+  --query 'SecretList[].{Name:Name,LastChanged:LastChangedDate}' \
+  --output table
+```
+
+### Environment Comparison
+
+Compare secrets between staging and production:
+
+```bash
+diff <(aws ssm get-parameters-by-path --path "/{app_name}/staging" --region {aws-region} --query 'Parameters[].Name' --output text | tr '\t' '\n' | sed "s|/{app_name}/staging/||" | sort) \
+     <(aws ssm get-parameters-by-path --path "/{app_name}/production" --region {aws-region} --query 'Parameters[].Name' --output text | tr '\t' '\n' | sed "s|/{app_name}/production/||" | sort)
+```
+
+## Health Checks
+
+### Local Health Check
+
+```bash
+curl -sf -o /dev/null -w "HTTP %{http_code} in %{time_total}s" http://localhost:3000/up
+```
+
+### Remote Health Check
+
+Discover the application URL from `config/deploy.{environment}.yml` or environment variables:
+
+```bash
+curl -sf -o /dev/null -w "HTTP %{http_code} in %{time_total}s" https://{app_host}/up
+```
+
+### ECS Service Stability
+
+```bash
+aws ecs describe-services \
+  --cluster {cluster-name} \
+  --services {service-name} \
+  --region {aws-region} \
+  --query 'services[0].{Status:status,Running:runningCount,Desired:desiredCount,Deployments:deployments[].{Status:status,Running:runningCount,Desired:desiredCount,Rollout:rolloutState}}' \
+  --output json
+```
+
+### Full Health Check Script
+
+```bash
+check_env() {
+  local ENV=$1
+  local URL=$2
+
+  echo "=== $ENV ==="
+
+  # Rails /up endpoint
+  STATUS=$(curl -sf -o /dev/null -w "%{http_code}" --max-time 10 "$URL/up" 2>/dev/null || echo "000")
+  TIME=$(curl -sf -o /dev/null -w "%{time_total}" --max-time 10 "$URL/up" 2>/dev/null || echo "timeout")
+  echo "Health: HTTP $STATUS ($TIME s)"
+
+  # Database connectivity (via /up — Rails health check verifies DB by default)
+  BODY=$(curl -sf --max-time 10 "$URL/up" 2>/dev/null || echo "UNREACHABLE")
+  echo "Body:   $BODY"
+  echo ""
+}
+```
+
+## Troubleshooting Quick Reference
+
+| Problem | Likely Cause | Fix |
+|---------|-------------|-----|
+| `port 3000 already in use` | Previous Rails server running | `lsof -ti :3000 \| xargs kill -9` |
+| `docker compose up` fails | Docker Desktop not running | Start Docker Desktop, then retry |
+| `PG::ConnectionBad` | PostgreSQL not running or wrong credentials | Check `docker compose ps` for postgres container; verify `DATABASE_URL` |
+| Kamal deploy hangs | SSH key not added or wrong host | Verify `ssh {host}` works; check `config/deploy.yml` servers |
+| `kamal lock release` needed | Previous deploy interrupted | Run `kamal lock release -d {env}` then retry |
+| Solid Queue jobs stuck | Worker process crashed | Check `docker compose logs worker`; restart worker container |
+| Migrations fail on deploy | Unsafe migration detected by Strong Migrations | Fix the migration per Strong Migrations guidance, then redeploy |
+| `ActiveRecord::NoDatabaseError` | Database not created | `bin/rails db:create` (local) or check ECS task definition env vars |
+| AWS credentials expired | SSO session timed out locally, or missing env-backed profile headless | Interactive local: refresh the local AWS profile outside headless automation. Headless: use the configured environment-backed assume-role profile |
+| ECS tasks keep restarting | Health check failing or OOM | Check CloudWatch logs for the task; verify `/up` returns 200; check memory limits |
+| OpenTelemetry traces missing | Collector not configured or endpoint wrong | Verify `OTEL_EXPORTER_OTLP_ENDPOINT` in environment; check collector sidecar logs |
+| `Bundler::GemNotFound` | Missing `bundle install` after Gemfile change | `bundle install` locally; for deploy, rebuild Docker image |
+
+## Rules
+
+- Always verify empirically — never assume something works because the code looks correct
+- Always discover project-specific values from source files before operations
+- Always check prerequisites (Docker, ports, AWS credentials) before operations
+- Always read `config/deploy.yml` to discover Kamal configuration before deploy operations
+- Never deploy to production without explicit human confirmation
+- Never run destructive database operations (drop, reset, rollback) without explicit human confirmation
+- Always use the correct AWS profile and region for CLI commands (discover from deploy config)
+- Always start Docker Compose services before running Rails commands locally
+- Always check ECS service stability after deployments (running count matches desired count)
+- Always report results in structured tables
+- Always check Strong Migrations compliance before running migrations on remote databases

package/plugins/lisa-rails-devin/hooks/devin-tool-name-shim.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+# Generated by scripts/generate-devin-plugin-artifacts.mjs — do not edit.
+#
+# Devin CLI names its tools in lowercase (exec, write, edit, read, ...) while
+# Lisa's guards test Claude's names (Bash, Write, Edit, Read, ...). The field
+# names inside tool_input already match, so translating tool_name is enough
+# for an unchanged guard to evaluate a Devin tool call (CodySwannGT/lisa#4426).
+#
+# Usage: devin-tool-name-shim.sh <hook command> [args...]
+payload=$(cat)
+normalized=$payload
+if command -v jq >/dev/null 2>&1; then
+  mapped=$(printf '%s' "$payload" | jq -c '
+    if (.tool_name | type) == "string" then
+      .tool_name |= ({
+        "exec": "Bash",
+        "write": "Write",
+        "edit": "Edit",
+        "read": "Read",
+        "notebook_edit": "NotebookEdit",
+        "grep": "Grep",
+        "glob": "Glob",
+        "webfetch": "WebFetch",
+        "run_subagent": "Task",
+        "skill": "Skill",
+        "todo_write": "TodoWrite"
+      }[.] // .)
+    else . end' 2>/dev/null) && [ -n "$mapped" ] && normalized=$mapped
+fi
+printf '%s' "$normalized" | "$@"

package/plugins/lisa-rails-devin/hooks/inject-rules.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Reads the plugin's EAGER rules and injects them into the session context.
+#
+# `rules/eager/` only, and deliberately with NO fallback to a flat `rules/`.
+# This plugin's rules and this script ship in the same directory and are
+# installed as one unit, so there is no vintage in which a split script meets an
+# unsplit rules tree. A fallback here would buy nothing and cost the thing it
+# already cost once: this plugin shipped its whole rule body flat for months and
+# no surface complained, because a fallback that quietly succeeds is
+# indistinguishable from a tree that was never split (#3993). With the branch
+# gone, an unsplit tree injects nothing and is noticed.
+#
+# Reference bodies under `rules/reference/` install alongside and are read only
+# when an eager breadcrumb points at one.
+set -euo pipefail
+
+INPUT=$(cat 2>/dev/null || true)
+if [ -n "$INPUT" ]; then
+  HOOK_EVENT=$(printf '%s' "$INPUT" | jq -r '.hook_event_name // "SessionStart"' 2>/dev/null || echo "SessionStart")
+else
+  HOOK_EVENT="SessionStart"
+fi
+
+ROOT="${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}}"
+RULES_DIR="$ROOT/rules/eager"
+
+# Bail silently if no rules directory
+[ -d "$RULES_DIR" ] || exit 0
+
+CONTEXT=""
+for file in "$RULES_DIR"/*.md; do
+  [ -f "$file" ] || continue
+  CONTEXT+="$(cat "$file")"$'\n\n'
+done
+
+# Bail if no rules found
+[ -n "$CONTEXT" ] || exit 0
+
+# Output as JSON — jq handles escaping
+jq -n --arg event "$HOOK_EVENT" --arg ctx "$CONTEXT" '{"hookSpecificOutput": {"hookEventName": $event, "additionalContext": $ctx}}'

package/plugins/lisa-rails-devin/hooks/lisa-edit-gate.sh

@@ -0,0 +1,152 @@
+#!/bin/bash
+# This file is managed by Lisa.
+# Do not edit directly — changes will be overwritten on the next `lisa` run.
+# =============================================================================
+# Edit-time gate façade
+# =============================================================================
+# Sourced by every on-edit hook. Answers one question before the hook runs
+# anything: has the project declared what proves this property at this moment,
+# and if so what should run instead of Lisa's written-in tool?
+#
+# WHY THIS EXISTS. Edit time is the highest-frequency enforcement surface Lisa
+# owns and was the one surface with no configurability at all. The scripts
+# resolved a RUNNER (`./node_modules/.bin/oxlint`, else `bunx`/`npx`) and
+# hardcoded the TOOL, which is the inversion the gate registry exists to fix.
+# Worse, they exit 2 — refusing the edit — when the written-in binary or config
+# filename is absent, so a project that lints correctly with something else had
+# every agent write refused until it installed Lisa's choice.
+#
+# THE CONTRACT, and the two halves that matter equally:
+#
+#   declared   -> the project's task runs and the hook's written-in tool is
+#                 never consulted, so a missing binary cannot refuse the edit.
+#   undeclared -> NOTHING changes. The resolver is not even invoked when no
+#                 registry is installed, and the hook falls through to exactly
+#                 the command it ran before. That is the overwhelming majority
+#                 of projects, and it is the case a façade silently breaks.
+#
+# ALL OR NOTHING FOR A MULTI-PROPERTY SCRIPT. `lisa_edit_gate_tasks` takes every
+# property its caller proves and resolves only when EVERY one is declared. The
+# Rails hook runs `rubocop -a` and then a second pass for unfixable errors — its
+# own header calls it both formatter and linter — so standing down on `code-style`
+# alone would silently stop proving `format-conformance`. Same shape as
+# `lisa_gate_covers test-correctness coverage-adequacy` in the pre-push hook.
+#
+# HOW THE DECLARED TASK LEARNS WHICH FILE WAS EDITED. It does not take an
+# argument: `<runner> <task>` with no arguments is the invocation every other
+# Lisa façade uses, and adding a positional here would make the declaration
+# mean something different at this moment than at every other one. The path is
+# exported as LISA_EDITED_FILE instead, so a project that wants a per-file run
+# can scope its own task and one that does not gets a whole-project run.
+# =============================================================================
+
+# Where the gate registry may be installed, in resolution order.
+lisa_edit_gate_registry() {
+    for _lisa_candidate in \
+        "node_modules/@codyswann/lisa/all/copy-overwrite/scripts/lisa-gates.mjs" \
+        "scripts/lisa-gates.mjs" \
+        "all/copy-overwrite/scripts/lisa-gates.mjs"
+    do
+        if [ -f "$_lisa_candidate" ]; then
+            printf '%s' "$_lisa_candidate"
+            unset _lisa_candidate
+            return 0
+        fi
+    done
+    unset _lisa_candidate
+    return 1
+}
+
+# lisa_edit_gate_tasks <moment> <gate-id>...
+#
+# Prints one `<runner> <task>` line per DISTINCT declared task and returns 0,
+# but only when every named gate resolves to a runnable task at <moment>.
+# Returns 1 and prints nothing otherwise — including when no registry is
+# installed, when node is unavailable, and when the resolver itself fails.
+#
+# Fail-safe in the direction that keeps proving things: any doubt returns 1 and
+# the caller runs its built-in. A resolver that could not answer must never read
+# as "the project has this covered".
+lisa_edit_gate_tasks() {
+    _lisa_moment="$1"
+    shift
+    [ -n "$_lisa_moment" ] || { unset _lisa_moment; return 1; }
+    [ "$#" -gt 0 ] || { unset _lisa_moment; return 1; }
+    # NO SETTINGS FILE, NO SPAWN. Checked before anything else because this is
+    # the path essentially every project is on, and it runs on EVERY agent
+    # edit: asking the resolver would cost a node process per keystroke-sized
+    # write to answer "nothing is declared", which the absent file already
+    # answers. The equivalence control compares which COMMAND runs and would
+    # not have caught the cost.
+    [ -f .lisa.config.json ] || { unset _lisa_moment; return 1; }
+    command -v node >/dev/null 2>&1 || { unset _lisa_moment; return 1; }
+
+    _lisa_registry="$(lisa_edit_gate_registry)" || {
+        unset _lisa_moment _lisa_registry
+        return 1
+    }
+
+    # EXPORTED, not prefixed. An assignment prefix reaches only the FIRST
+    # command of a pipeline, and the filter that reads it is the second — so
+    # the prefixed form resolved an empty want-list and every script fell
+    # silently back to its built-in, which is a façade that looks wired and is
+    # not.
+    LISA_GATE_IDS="$*"
+    export LISA_GATE_IDS
+    _lisa_out="$(
+        node "$_lisa_registry" list \
+            --moment="$_lisa_moment" --json 2>/dev/null | node -e '
+let raw = "";
+process.stdin.on("data", chunk => { raw += chunk }).on("end", () => {
+  let resolved;
+  try { resolved = JSON.parse(raw || "[]"); } catch { process.exit(1); }
+  const wanted = (process.env.LISA_GATE_IDS || "").split(" ").filter(Boolean);
+  const commands = [];
+  for (const id of wanted) {
+    const hit = resolved.find(gate => gate.id === id);
+    // `run` mode with a task is the only shape that PROVES anything here. An
+    // awaited gate proves nothing at edit time and an intercepted one is
+    // Lisa running it elsewhere; both must leave the built-in in charge.
+    if (!hit || hit.mode !== "run" || !hit.command) process.exit(1);
+    if (!commands.includes(hit.command)) commands.push(hit.command);
+  }
+  if (commands.length === 0) process.exit(1);
+  process.stdout.write(commands.join("\n"));
+});
+'
+    )" || {
+        unset _lisa_moment _lisa_registry _lisa_out
+        return 1
+    }
+
+    [ -n "$_lisa_out" ] || {
+        unset _lisa_moment _lisa_registry _lisa_out
+        return 1
+    }
+    printf '%s' "$_lisa_out"
+    unset _lisa_moment _lisa_registry _lisa_out
+    return 0
+}
+
+# lisa_edit_gate_run <edited-file> <commands>
+#
+# Runs each resolved command with LISA_EDITED_FILE exported. Exits 2 on the
+# first failure, which is the same refusal the built-in path uses, so a
+# declared task that finds a real problem still stops the agent.
+lisa_edit_gate_run() {
+    _lisa_file="$1"
+    shift
+    LISA_EDITED_FILE="$_lisa_file"
+    export LISA_EDITED_FILE
+    printf '%s\n' "$*" | while IFS= read -r _lisa_command; do
+        [ -n "$_lisa_command" ] || continue
+        echo "Running declared gate task: $_lisa_command"
+        # Deliberate word split: the resolver validated both halves as plain
+        # words, so no shell metacharacter reaches argv.
+        # shellcheck disable=SC2086
+        $_lisa_command || exit 2
+    done
+    _lisa_status=$?
+    unset _lisa_file _lisa_command
+    return $_lisa_status
+}

package/plugins/lisa-rails-devin/hooks/rubocop-on-edit.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# This file is managed by Lisa.
+# Do not edit directly — changes will be overwritten on the next `lisa` run.
+# =============================================================================
+# RuboCop Lint-and-Format-on-Edit Hook (PostToolUse - Write|Edit)
+# =============================================================================
+# Runs RuboCop -a (safe autocorrect) on each edited Ruby file, then checks for
+# remaining unfixable errors. RuboCop serves as both formatter and linter
+# for Ruby, so this single hook replaces the Prettier + ESLint pipeline.
+#
+# Behavior:
+#   - Exit 0: RuboCop passes or auto-fix resolved all errors
+#   - Exit 2: unfixable errors remain — blocks Claude so it fixes them immediately
+#
+# @see .claude/rules/verification.md "Self-Correction Loop" section
+# =============================================================================
+
+# Extract file path from JSON input
+FILE_PATH=$(cat | grep -o '"file_path":"[^"]*"' | head -1 | cut -d'"' -f4)
+
+if [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ]; then
+    exit 0
+fi
+
+# Check if file type is supported (Ruby only)
+case "${FILE_PATH##*.}" in
+    rb) ;;
+    *) exit 0 ;;
+esac
+
+# Validate project directory
+if [ -z "${CLAUDE_PROJECT_DIR:-}" ]; then
+    exit 0
+fi
+
+# Check if file is in a recognized source directory, excluding generated/vendored paths
+RELATIVE_PATH="${FILE_PATH#$CLAUDE_PROJECT_DIR/}"
+case "$RELATIVE_PATH" in
+    db/migrate/*|db/schema.rb) exit 0 ;;
+    vendor/*|bin/*|tmp/*|node_modules/*) exit 0 ;;
+esac
+case "$RELATIVE_PATH" in
+    app/*|lib/*|spec/*|config/*|db/*) ;;
+    *) exit 0 ;;
+esac
+
+# Where this script lives, resolved BEFORE any `cd`. `$0` is the path the
+# harness invoked, and the façade helper ships beside it.
+LISA_HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+# ---------------------------------------------------------------------------
+# Gate façade. The project's declaration decides BEFORE any tool is resolved.
+# Full contract, and why an undeclared project sees no change at all, in
+# lisa-edit-gate.sh beside this file.
+#
+# All-or-nothing across the properties this script proves: a single invocation
+# that proves more than one stands down only when EVERY one is declared, or it
+# would silently stop proving the others.
+# ---------------------------------------------------------------------------
+if [ -f "$LISA_HOOK_DIR/lisa-edit-gate.sh" ]; then
+    # shellcheck source=/dev/null
+    . "$LISA_HOOK_DIR/lisa-edit-gate.sh"
+    if LISA_GATE_COMMANDS="$(lisa_edit_gate_tasks post-tool code-style format-conformance)"; then
+        lisa_edit_gate_run "$FILE_PATH" "$LISA_GATE_COMMANDS"
+        exit $?
+    fi
+fi
+
+
+# Verify this is a Ruby project with Bundler
+if [ ! -f "Gemfile" ]; then
+    exit 0
+fi
+
+# Run RuboCop autocorrect — fail only on errors (not warnings/conventions)
+echo "Running RuboCop on: $FILE_PATH"
+
+# First pass: attempt safe auto-correct
+OUTPUT=$(bundle exec rubocop -a --fail-level E "$FILE_PATH" 2>&1)
+FIX_EXIT=$?
+
+if [ $FIX_EXIT -eq 0 ]; then
+    echo "RuboCop: No errors in $(basename "$FILE_PATH")"
+    exit 0
+fi
+
+# Auto-fix resolved some issues but errors remain — re-run to get remaining errors
+OUTPUT=$(bundle exec rubocop --fail-level E "$FILE_PATH" 2>&1)
+LINT_EXIT=$?
+
+if [ $LINT_EXIT -eq 0 ]; then
+    echo "RuboCop: Auto-fixed all errors in $(basename "$FILE_PATH")"
+    exit 0
+fi
+
+# Unfixable errors remain — block with feedback
+echo "RuboCop found unfixable errors in: $FILE_PATH" >&2
+echo "$OUTPUT" >&2
+exit 2

package/plugins/lisa-rails-devin/hooks/sg-scan-on-edit.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+# This file is managed by Lisa.
+# Do not edit directly — changes will be overwritten on the next `lisa` run.
+# =============================================================================
+# ast-grep Scan-on-Edit Hook (PostToolUse - Write|Edit)
+# =============================================================================
+# Runs ast-grep scan on each edited Ruby file to enforce structural code rules.
+# Complements RuboCop by catching patterns that require AST-level analysis.
+#
+# Behavior:
+#   - Exit 0: no issues found or ast-grep not configured
+#   - Exit 2: issues found — blocks Claude so it fixes them immediately
+#
+# @see .claude/rules/verification.md "Self-Correction Loop" section
+# =============================================================================
+
+# Extract file path from JSON input
+FILE_PATH=$(cat | grep -o '"file_path":"[^"]*"' | head -1 | cut -d'"' -f4)
+
+if [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ]; then
+    exit 0
+fi
+
+# Check if file type is supported (Ruby only)
+case "${FILE_PATH##*.}" in
+    rb) ;;
+    *) exit 0 ;;
+esac
+
+# Validate project directory
+if [ -z "${CLAUDE_PROJECT_DIR:-}" ]; then
+    exit 0
+fi
+
+# Check if file is in a recognized source directory
+RELATIVE_PATH="${FILE_PATH#$CLAUDE_PROJECT_DIR/}"
+case "$RELATIVE_PATH" in
+    app/*|lib/*|config/*|spec/*) ;;
+    *) exit 0 ;;
+esac
+
+# Where this script lives, resolved BEFORE any `cd`. `$0` is the path the
+# harness invoked, and the façade helper ships beside it.
+LISA_HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+# ---------------------------------------------------------------------------
+# Gate façade. The project's declaration decides BEFORE any tool is resolved.
+# Full contract, and why an undeclared project sees no change at all, in
+# lisa-edit-gate.sh beside this file.
+#
+# All-or-nothing across the properties this script proves: a single invocation
+# that proves more than one stands down only when EVERY one is declared, or it
+# would silently stop proving the others.
+# ---------------------------------------------------------------------------
+if [ -f "$LISA_HOOK_DIR/lisa-edit-gate.sh" ]; then
+    # shellcheck source=/dev/null
+    . "$LISA_HOOK_DIR/lisa-edit-gate.sh"
+    if LISA_GATE_COMMANDS="$(lisa_edit_gate_tasks post-tool structural-rules)"; then
+        lisa_edit_gate_run "$FILE_PATH" "$LISA_GATE_COMMANDS"
+        exit $?
+    fi
+fi
+
+
+# Verify ast-grep configuration exists
+if [ ! -f "sgconfig.yml" ]; then
+    exit 0
+fi
+
+# Verify rules are defined
+RULE_COUNT=$(find ast-grep/rules -name "*.yml" -o -name "*.yaml" 2>/dev/null | grep -v ".gitkeep" | wc -l | tr -d ' ')
+if [ "$RULE_COUNT" -eq 0 ]; then
+    exit 0
+fi
+
+# Locate ast-grep binary — prefer local sg, then npx fallback
+if command -v sg >/dev/null 2>&1; then
+    SG_CMD="sg"
+elif command -v npx >/dev/null 2>&1; then
+    SG_CMD="npx @ast-grep/cli"
+else
+    echo "ast-grep: sg binary not found, skipping scan"
+    exit 0
+fi
+
+# Run ast-grep scan
+echo "Running ast-grep scan on: $FILE_PATH"
+if OUTPUT=$($SG_CMD scan "$FILE_PATH" 2>&1); then
+    echo "ast-grep: No issues found in $(basename "$FILE_PATH")"
+    exit 0
+else
+    echo "ast-grep found issues in: $FILE_PATH" >&2
+    echo "$OUTPUT" >&2
+    exit 2
+fi