@damiangilgonzalez/harness 1.3.7

package/skills/rails/evals/README.md

@@ -0,0 +1,12 @@
+# Evals — rails
+
+`cases.yaml` is a routing/trigger fixture, not an automated test harness. Run it by
+hand (or via your router-eval tool): feed each `should_trigger` prompt to the skill
+router and confirm it selects `rails`; feed each `should_not_trigger` prompt and confirm
+it routes to the named sibling (`ruby`, `laravel`, `postgresdb`, `deployment`) instead.
+For the `capability` case, give the scenario to the agent with this skill loaded and
+check the produced Rails code satisfies every line in `must_include` — resourceful
+routes, an association + validation, strong params, `includes`-based eager loading, a
+Turbo Stream/morph live update, an `ApplicationSystemTestCase` test with auto-waiting
+assertions, and Solid Queue (never Sidekiq) for any async. No external services or
+network are required.

package/skills/rails/evals/cases.yaml

@@ -0,0 +1,47 @@
+skill: rails
+
+should_trigger:
+  - prompt: "Scaffold a blog with Posts and Comments and resourceful routes."
+    why: Core Rails MVC generation — models, controller, routes, views.
+  - prompt: "This index action is slow because of post.author in the loop, fix the N+1."
+    why: ActiveRecord eager-loading; the canonical Rails query footgun.
+  - prompt: "Make the comment list update live when someone posts a new comment."
+    why: Turbo Stream / model broadcast — Hotwire, the Rails default front-end.
+  - prompt: "Is this add_index migration safe to run on a 5M-row table in production?"
+    why: >
+      Non-obvious — reads like a database question, but it is the ActiveRecord
+      migration DSL and Rails migration-safety rules (disable_ddl_transaction!,
+      algorithm: :concurrently, strong_migrations).
+  - prompt: "My Capybara system test started failing randomly after I added a Turbo Frame."
+    why: >
+      Non-obvious Hotwire-timing flake; unmistakably Rails (ApplicationSystemTestCase
+      + Turbo), fixed by auto-waiting matchers / driver swap, not by sleeps.
+  - prompt: "Necesito un job en background con Solid Queue para enviar emails de aviso."
+    why: Spanish — Active Job on the Rails 8 default Solid Queue backend.
+  - prompt: "Aquesta migració amb add_column i default és segura en producció?"
+    why: Catalan — Rails migration safety on a live table.
+
+should_not_trigger:
+  - prompt: "Refactor this standalone Ruby parser script using Enumerable, no Rails involved."
+    route_to: ruby
+    why: Plain Ruby language work; nothing loads Rails or ActiveRecord.
+  - prompt: "Fix my Eloquent hasMany relationship in this Laravel controller."
+    route_to: laravel
+    why: Same MVC problem space, but PHP/Laravel — route by the actual framework.
+  - prompt: "Design the B-tree vs partial index strategy for a Postgres table, no ORM."
+    route_to: postgresdb
+    why: Engine-level index strategy expressed in raw SQL, not an AR migration.
+  - prompt: "Set up the Kamal host, Docker image, and CI runner to deploy the app."
+    route_to: deployment
+    why: Host/container/CI provisioning — infra mechanics, not Rails-side code.
+
+capability:
+  - scenario: "Build a Posts CRUD with Comments, a live-updating comment list, and tests."
+    must_include:
+      - "resourceful nested routes (resources :posts do resources :comments)"
+      - "has_many / belongs_to association plus at least one validation"
+      - "strong parameters via params.expect or require.permit"
+      - "eager loading with includes/preload to avoid N+1 on the comment list"
+      - "Turbo Stream or morphing for the live update (not hand-rolled JS/fetch)"
+      - "a system test using ApplicationSystemTestCase with auto-waiting assertions (assert_text / assert_selector, no sleep)"
+      - "Solid Queue (not Sidekiq/Redis) for any async work introduced"

package/skills/rails/references/activerecord.md

@@ -0,0 +1,148 @@
+# ActiveRecord depth
+
+Patterns for when a model method or migration outgrows the SKILL.md basics.
+
+## Query objects
+
+When a query gets reused or spans several conditions/joins, extract a PORO instead of
+piling scopes or stuffing it in the controller.
+
+```ruby
+# app/queries/recent_active_posts_query.rb
+class RecentActivePostsQuery
+  def initialize(relation = Post.all)
+    @relation = relation
+  end
+
+  def call(since: 30.days.ago)
+    @relation
+      .where("published_at > ?", since)
+      .where(archived: false)
+      .includes(:author)
+      .order(published_at: :desc)
+  end
+end
+```
+
+Keep it returning a relation (not an array) so callers can chain or paginate.
+
+## strict_loading
+
+Make lazy loading raise instead of silently N+1-ing. Set it per-association, per-record,
+or app-wide.
+
+```ruby
+class Post < ApplicationRecord
+  has_many :comments, strict_loading: true
+end
+
+# Or per query:
+Post.strict_loading.find(id).comments   # raises unless preloaded
+```
+
+App-wide default in an environment file: `config.active_record.strict_loading_by_default
+= true`. Turn it on in CI to catch N+1 before production.
+
+## includes vs preload vs eager_load
+
+- `includes` — Rails decides: separate queries (preload) unless you reference the
+  association in a `where`/`order`, then it switches to a JOIN (eager_load).
+- `preload` — always separate queries (two `SELECT`s). Use when you don't filter on the
+  association.
+- `eager_load` — always a single `LEFT OUTER JOIN`. Use when you must filter/sort by the
+  association's columns.
+
+If you `includes(:author).where("users.name = ?", x)` without referencing the table in a
+string condition, add `.references(:author)` so Rails knows to JOIN.
+
+## Large datasets
+
+Never `Model.all.each` over a big table — it loads every row into memory. Batch it:
+
+```ruby
+Post.find_each(batch_size: 1000) do |post|   # loads 1000 at a time
+  post.recompute_score!
+end
+```
+
+For bulk updates with no callbacks needed, `update_all` issues one SQL statement.
+
+## Counter caches
+
+Avoid `COUNT(*)` on every render by caching the count on the parent.
+
+```ruby
+class Comment < ApplicationRecord
+  belongs_to :post, counter_cache: true   # maintains posts.comments_count
+end
+```
+
+Add the `comments_count` integer column; backfill it once with
+`Post.find_each { |p| Post.reset_counters(p.id, :comments) }`.
+
+## Composite primary keys
+
+Rails supports composite keys natively. Declare on the model when the table has a
+two-column PK:
+
+```ruby
+class TravelRoute < ApplicationRecord
+  self.primary_key = [:origin, :destination]
+end
+```
+
+`find` then takes an array: `TravelRoute.find(["NYC", "LON"])`.
+
+## Advisory locks
+
+Serialize a critical section across processes without a row lock, e.g. a singleton
+backfill:
+
+```ruby
+ApplicationRecord.with_advisory_lock("nightly-rollup") do
+  # only one process runs this block at a time
+end
+```
+
+(Via the `with_advisory_lock` gem; Solid Queue uses advisory locks internally for
+concurrency control.)
+
+## Safe migration recipes (per operation)
+
+Each recipe assumes a large live table. `strong_migrations` will flag the unsafe form.
+
+**Add a column** — modern Postgres + Rails handle `default:` without a table rewrite, but
+verify; if in doubt, add the column nullable, then set the default in a follow-up.
+
+```ruby
+add_column :posts, :views_count, :integer, default: 0, null: false
+```
+
+**Add an index** — always concurrent on a hot table:
+
+```ruby
+class AddIndex < ActiveRecord::Migration[8.1]
+  disable_ddl_transaction!
+  def change
+    add_index :posts, :slug, unique: true, algorithm: :concurrently
+  end
+end
+```
+
+**Rename a column/table** — never do it in place on a live app (old code still
+references the old name). Add the new column, dual-write in the app, backfill, switch
+reads, drop the old column in a later deploy.
+
+**Backfill** — never a single `UPDATE` of millions of rows in a migration (long lock,
+not reversible cleanly). Batch in a separate, idempotent task:
+
+```ruby
+Post.where(views_count: nil).in_batches do |batch|
+  batch.update_all(views_count: 0)
+end
+```
+
+**Add a NOT NULL constraint** — add it as `NOT VALID` then validate separately, or use
+a check constraint, to avoid a full-table scan under lock.
+
+Always confirm `change` is reversible; if not, write explicit `up`/`down`.

package/skills/rails/references/hotwire.md

@@ -0,0 +1,139 @@
+# Hotwire worked examples
+
+Turbo 8 + Stimulus, the Rails 8 default front-end. Reach for the lightest layer that
+solves the problem: Drive → Frame → Stream → morph, and Stimulus only for behavior.
+
+## Turbo Frame — scoped replacement
+
+A frame replaces just its own contents on navigation/submit. Wrap the region and give
+matching IDs.
+
+```erb
+<%# app/views/posts/show.html.erb %>
+<turbo-frame id="post_title">
+  <h1><%= @post.title %></h1>
+  <%= link_to "Edit", edit_post_path(@post) %>
+</turbo-frame>
+```
+
+```erb
+<%# edit.html.erb — same frame id, so only this swaps in %>
+<turbo-frame id="post_title">
+  <%= form_with model: @post do |f| %>
+    <%= f.text_field :title %>
+    <%= f.submit %>
+  <% end %>
+</turbo-frame>
+```
+
+## Turbo Stream — targeted multi-element update
+
+After a create/destroy, return a `.turbo_stream` template to append/replace/remove
+specific DOM nodes. The controller responds to the format:
+
+```ruby
+def create
+  @comment = @post.comments.create!(comment_params)
+  respond_to do |format|
+    format.turbo_stream
+    format.html { redirect_to @post }
+  end
+end
+```
+
+```erb
+<%# create.turbo_stream.erb %>
+<%= turbo_stream.append "comments", @comment %>
+<%= turbo_stream.update "comments_count", @post.comments.count %>
+```
+
+## Broadcasting from a model
+
+Push updates to every subscribed browser over Solid Cable — no controller round-trip.
+
+```ruby
+class Comment < ApplicationRecord
+  belongs_to :post
+  broadcasts_to ->(comment) { [comment.post, :comments] }
+end
+```
+
+```erb
+<%# in show.html.erb, subscribe the page %>
+<%= turbo_stream_from @post, :comments %>
+<div id="comments"><%= render @post.comments %></div>
+```
+
+`broadcasts_to` fires append-on-create / replace-on-update / remove-on-destroy to that
+stream automatically.
+
+## Morphing — full refresh, kept scroll
+
+Turbo 8 can re-render the whole page and morph the DOM diff while preserving scroll and
+focus. Enable it in the layout:
+
+```erb
+<%= turbo_refreshes_with method: :morph, scroll: :preserve %>
+```
+
+Now a plain `redirect_to` / page refresh updates in place without bespoke Stream
+choreography. Use an explicit Stream only when morphing can't infer the change (e.g.
+prepend a row from a background broadcast).
+
+## Stimulus — values, targets, outlets, actions
+
+```javascript
+// app/javascript/controllers/filter_controller.js
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["query", "results"]
+  static values  = { url: String, debounce: { type: Number, default: 300 } }
+  static outlets  = ["toast"]
+
+  connect() { this.timer = null }
+
+  search() {
+    clearTimeout(this.timer)
+    this.timer = setTimeout(() => this.#fetch(), this.debounceValue)
+  }
+
+  async #fetch() {
+    const res = await fetch(`${this.urlValue}?q=${this.queryTarget.value}`)
+    this.resultsTarget.innerHTML = await res.text()
+    this.toastOutlet?.show("Updated")   // call another controller via outlet
+  }
+}
+```
+
+```erb
+<div data-controller="filter" data-filter-url-value="<%= search_path %>">
+  <input data-filter-target="query" data-action="input->filter#search">
+  <div data-filter-target="results"></div>
+</div>
+```
+
+- **values** — typed, reactive config from data attributes.
+- **targets** — element references inside the controller's scope.
+- **outlets** — call methods on another controller's instance.
+- **actions** — `event->controller#method` wiring.
+
+## System-testing Turbo interactions
+
+Capybara matchers auto-wait, so they survive Turbo's async DOM updates. Never `sleep`.
+
+```ruby
+class CommentsTest < ApplicationSystemTestCase
+  test "comment appears live" do
+    visit post_path(posts(:one))
+    fill_in "Comment", with: "Nice post"
+    click_on "Post comment"
+    assert_text "Nice post"          # retries until the Stream lands
+    assert_selector "#comments .comment", count: 1
+  end
+end
+```
+
+If the page uses broadcasts, ensure the test driver runs the Action Cable/Solid Cable
+connection (default config does). For driver choice and flake-hardening, see
+`testing.md`.

package/skills/rails/references/testing.md

@@ -0,0 +1,110 @@
+# Rails testing
+
+Minitest + fixtures is the framework default and what fresh apps ship with. RSpec-rails
+is the popular alternative. Pick one per app; don't mix.
+
+## Minitest layout (default)
+
+```text
+test/
+  models/         ActiveSupport::TestCase
+  integration/    ActionDispatch::IntegrationTest
+  controllers/    ActionDispatch::IntegrationTest
+  system/         ApplicationSystemTestCase
+  jobs/           ActiveJob::TestCase
+  fixtures/       *.yml — loaded once per suite
+```
+
+Run: `bin/rails test` (unit/integration), `bin/rails test:system` (browser). Parallel
+execution is on by default via `parallelize(workers: :number_of_processors)` in
+`test_helper.rb`.
+
+## RSpec-rails setup
+
+```ruby
+# Gemfile (test group)
+gem "rspec-rails", "~> 8.0"
+gem "capybara"
+```
+
+```bash
+bundle exec rails generate rspec:install   # creates spec/ + spec_helper
+```
+
+Specs live under `spec/{models,requests,system,jobs}`. Prefer **request specs** over
+controller specs (the Rails team's guidance) — they hit the full middleware stack.
+
+## Fixtures vs factories
+
+- **Fixtures** (default): YAML rows loaded once into the test DB. Fast, but every test
+  shares the same data, so they drift toward a tangled global fixture set.
+- **Factories** (FactoryBot): build objects per test. More expressive for per-test
+  variation, slower if you `create` when `build`/`build_stubbed` would do.
+
+Default to fixtures; introduce FactoryBot when fixture sprawl makes intent unclear.
+
+```yaml
+# test/fixtures/posts.yml
+one:
+  title: First post
+  author: alice          # references users.yml by label, resolves the FK
+  published_at: <%= 2.days.ago %>
+```
+
+Gotcha: fixture labels become stable IDs via a hash — reference associations by label,
+never by hard-coded integer ID.
+
+## System-test driver config
+
+Default driver is Selenium + headless Chrome. It's the flakiest with Turbo. Swap to
+**Cuprite** (CDP, no Selenium) or **Playwright** to cut timing flake and speed up CI.
+
+```ruby
+# test/application_system_test_case.rb (Cuprite example)
+require "capybara/cuprite"
+
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  driven_by :cuprite, screen_size: [1400, 1400], options: { headless: true }
+end
+```
+
+Hardening rules:
+- Use auto-waiting matchers (`assert_selector`, `assert_text`, `assert_no_selector`,
+  `has_no_text?`) — they retry up to Capybara's default wait. Never `sleep N`.
+- Assert the *absence* of the old state with `assert_no_*` (also auto-waits) rather than
+  asserting presence too early.
+- Keep one logical interaction per assertion block so a failure points at the step.
+
+## Testing jobs
+
+```ruby
+class CommentNotificationJobTest < ActiveJob::TestCase
+  test "enqueues on comment create" do
+    assert_enqueued_with(job: CommentNotificationJob) do
+      posts(:one).comments.create!(body: "hi")
+    end
+  end
+
+  test "performs idempotently when comment is gone" do
+    assert_nothing_raised { CommentNotificationJob.perform_now(-1) }
+  end
+end
+```
+
+Use `perform_enqueued_jobs` / `assert_enqueued_jobs` to control whether jobs run inline
+or just enqueue.
+
+## Testing broadcasts
+
+```ruby
+assert_broadcasts [post, :comments], 1 do
+  post.comments.create!(body: "live")
+end
+```
+
+## What to test
+
+Behavior through the public surface: a request returns the right status/redirect/body;
+a model method changes state correctly; a job enqueues and is idempotent. Do **not**
+test private methods — they're implementation, and locking tests to them turns every
+refactor into a test rewrite.

package/skills/rails/scripts/verify.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+#
+# verify.sh - read-only static gate for a Rails 8 app.
+#
+# Usage:
+#   cd <rails-app-root>
+#   /path/to/verify.sh [TARGET_DIR]      # TARGET_DIR defaults to .
+#
+# Checks, all guarded so a clean/empty/non-Rails target still passes:
+#   1. RuboCop  - only if rubocop is installed AND a .rubocop.yml is present.
+#                 Report-only; style is advisory, never fatal here.
+#   2. bin/rails zeitwerk:check - autoload-path sanity, only if bin/rails exists.
+#   3. grep banlist for statically-detectable anti-patterns (HARD failures):
+#        a. Sidekiq / `gem "redis"` in an app that ships the Solid stack default.
+#        b. `.all.each` mass loads in app/.
+#        c. `add_index ... concurrently` without `disable_ddl_transaction!` in
+#           the same migration file.
+#
+# Read-only: never writes, formats, or mutates your source.
+# Exit codes: 0 = clean OR nothing to check OR only advisory issues;
+#             1 = a hard banlist violation.
+# Portable to stock macOS bash 3.2 (no mapfile, no associative arrays).
+
+set -euo pipefail
+
+target="${1:-.}"
+
+if [ -t 1 ]; then
+  YELLOW=$'\033[33m'; RED=$'\033[31m'; GREEN=$'\033[32m'; RESET=$'\033[0m'
+else
+  YELLOW=''; RED=''; GREEN=''; RESET=''
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; }
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+
+if [ ! -d "$target" ]; then
+  printf '%serror:%s target dir not found: %s\n' "$RED" "$RESET" "$target" >&2
+  exit 2
+fi
+
+# Is this even a Rails-ish tree? If not, pass cleanly (nothing to gate).
+if [ ! -d "$target/app" ] && [ ! -f "$target/config/routes.rb" ] \
+   && [ ! -f "$target/bin/rails" ] && [ ! -d "$target/db/migrate" ]; then
+  skip "no app/ , config/routes.rb , bin/rails or db/migrate under $target - nothing to check"
+  exit 0
+fi
+
+failed=0
+
+# ---- 1. RuboCop (report-only, advisory) ------------------------------------
+if [ -f "$target/.rubocop.yml" ] && have rubocop; then
+  printf -- '----- rubocop (report only)\n'
+  ( cd "$target" && rubocop ) || skip "rubocop reported style issues (non-fatal)"
+else
+  skip "rubocop or .rubocop.yml absent - skipping lint"
+fi
+
+# ---- 2. zeitwerk autoload check --------------------------------------------
+if [ -x "$target/bin/rails" ]; then
+  printf -- '----- bin/rails zeitwerk:check\n'
+  if ( cd "$target" && bin/rails zeitwerk:check ) >/dev/null 2>&1; then
+    ok "zeitwerk:check passed"
+  else
+    skip "zeitwerk:check did not pass cleanly (boot/env may be unavailable here) - non-fatal"
+  fi
+else
+  skip "bin/rails absent - skipping zeitwerk:check"
+fi
+
+# ---- 3. Static banlist (hard failures) -------------------------------------
+
+# 3a. Sidekiq / redis gem in a Solid-default app.
+gemfile="$target/Gemfile"
+if [ -f "$gemfile" ]; then
+  if grep -Eq '^\s*gem\s+["'\'']sidekiq["'\'']' "$gemfile" \
+     || grep -Eq '^\s*gem\s+["'\'']redis["'\'']' "$gemfile"; then
+    if grep -Eq '^\s*gem\s+["'\'']solid_queue["'\'']' "$gemfile"; then
+      fail "Gemfile pulls Sidekiq/redis alongside solid_queue - drop it unless a real throughput need is stated"
+      failed=1
+    else
+      skip "Gemfile references sidekiq/redis but no solid_queue - not a Rails-8-default app, leaving it"
+    fi
+  else
+    ok "no Sidekiq/redis gem in Gemfile"
+  fi
+fi
+
+# 3b. .all.each mass loads in app/.
+if [ -d "$target/app" ]; then
+  hits=$(grep -rEn '\.all\.each\b' "$target/app" --include='*.rb' 2>/dev/null || true)
+  if [ -n "$hits" ]; then
+    fail ".all.each mass load found - use find_each / includes:"
+    printf '%s\n' "$hits" | sed 's/^/      /'
+    failed=1
+  else
+    ok "no .all.each mass loads in app/"
+  fi
+fi
+
+# 3c. Concurrent add_index without disable_ddl_transaction!.
+if [ -d "$target/db/migrate" ]; then
+  bad=""
+  for f in "$target"/db/migrate/*.rb; do
+    [ -e "$f" ] || continue
+    if grep -Eq 'add_index.*:concurrently' "$f" \
+       && ! grep -q 'disable_ddl_transaction!' "$f"; then
+      bad="$bad $f"
+    fi
+  done
+  if [ -n "$bad" ]; then
+    fail "concurrent add_index without disable_ddl_transaction! :"
+    for f in $bad; do printf '      %s\n' "$f"; done
+    failed=1
+  else
+    ok "concurrent indexes (if any) declare disable_ddl_transaction!"
+  fi
+fi
+
+if [ "$failed" -ne 0 ]; then
+  printf '%sverify failed:%s hard violations above.\n' "$RED" "$RESET" >&2
+  exit 1
+fi
+
+printf '%sverify ok: no hard violations.%s\n' "$GREEN" "$RESET"
+exit 0