/sota-ruby

name: sota-ruby
description: >-
  State-of-the-art Ruby engineering rules (supported Ruby releases) that Claude
  applies when writing or auditing Ruby. Covers modern idioms (frozen string literals,
  pattern matching, Data/Struct, RBS/Sorbet/Steep typing), security (SQL injection via
  ActiveRecord/Sequel, ERB/XSS escaping, mass assignment, CSRF, Marshal/YAML
  deserialization, command injection, ReDoS), framework-neutral web hardening
  (Rails/Sinatra/Hanami as neutral examples), supply chain and tooling (Bundler lockfile
  and checksums, bundler-audit, RuboCop/StandardRB, Brakeman, RSpec/Minitest, CI gates),
  and concurrency/performance (GVL, threads vs fibers vs Ractors, background-job
  idempotency, YJIT/ZJIT, GC and memory, N+1 queries). Trigger keywords: Ruby, gem,
  Gemfile, bundler, Rails, Sinatra, Hanami, Rack, ERB, ActiveRecord, Sequel, RSpec,
  minitest, RuboCop, Sorbet, RBS, Sidekiq, YJIT, Ractor, rake, ruby-lang. Use for BOTH
  building Ruby services/gems/CLIs and reviewing or auditing Ruby codebases.

SOTA Ruby (2026)

Expert-level rules for producing and auditing production Ruby. Baseline language line: **Ruby 3.4+**; Ruby 4.0 was released 2025-12-25 and is in normal maintenance (latest stable — verify at the branches page). Per the [official branches page](https://www.ruby-lang.org/en/downloads/branches/): 4.0 and 3.4 are in normal maintenance; 3.3 is security-maintenance only (expected EOL 2027-03); 3.2 and older are EOL (3.2 since 2026-04-01) — running them is itself a finding. Feature notes: `Data.define` and `Regexp.timeout` from 3.2, `it` block parameter and chilled-string warnings from 3.4, `Ractor::Port` and experimental ZJIT from 4.0 — noted where relevant. Every rules file ends with an audit checklist of grep/lint patterns.

Purpose

Two consumers, one source of truth:

• **BUILD mode** — generating new Ruby code: follow the rules as defaults, not

suggestions. Deviate only with an explicit comment justifying it.

• **AUDIT mode** — reviewing existing Ruby code: hunt violations using the

audit checklists, classify by severity, report in the finding format below.

BUILD mode

1. Before writing code, read the rules files relevant to the task (see index). A web endpoint touching the DB and a background job needs `02`, `03`, `05`. 2. Apply the **top-10 non-negotiables** (below) unconditionally. 3. Establish context first: `.ruby-version`, `Gemfile`/`Gemfile.lock`, RuboCop or StandardRB config, framework and test runner in use. Match the project's floor (no `it` block param on a 3.3 project). 4. New projects: pin the Ruby version (`.ruby-version`), commit `Gemfile.lock`, add RuboCop **or** StandardRB, `bundler-audit`, and the test suite to CI from day one (see [`rules/04`](rules/04-supply-chain-tooling.md)). Rails apps add Brakeman. 5. Security posture is non-optional even when unrequested: parameterized SQL, argv-form process spawning, `YAML.safe_load` semantics, `SecureRandom`, escaped output (see [`rules/02`](rules/02-security.md), [`rules/03`](rules/03-web-hardening.md)). 6. Write tests alongside the code (RSpec or Minitest — match the project). Anything with threads or jobs gets an idempotency/concurrency test. 7. When code must violate a rule for a legitimate reason, leave a `# NOTE(sota):` comment explaining the trade-off so auditors don't flag it.

AUDIT mode

**Coverage:** every `rules/` file's Audit checklist applies in AUDIT mode. Mark one *not applicable* only with its reason in the report — never skip a file because the thing it checks for is absent, since that absence may be the finding.

Work through each relevant rules file's audit checklist against the target repo. Run the listed grep/lint commands; confirm each hit manually before reporting (greps are recall-oriented, expect false positives). Useful mechanical sweeps: `bundle exec rubocop`, `bundler-audit check --update`, `brakeman -q` (Rails), plus the per-file greps.

Severity conventions

| Severity | Meaning | Examples | |---|---|---| | **CRITICAL** | Exploitable now, or data loss | SQL built with `#{}` interpolation, `Marshal.load`/`YAML.unsafe_load` on external data, command injection via backticks with user input, `html_safe` on user input | | **HIGH** | Exploitable with preconditions, or production-breaking | Missing CSRF protection on state-changing routes, `permit!`, `^`/`$` anchors in validation regexes, `rand` for tokens, `Timeout.timeout` around DB work, EOL Ruby in production | | **MEDIUM** | Correctness/maintenance hazard, latent bug | N+1 on a hot path, non-idempotent retried jobs, no `Gemfile.lock` in an app, mutable shared state across threads without a lock, `rescue Exception` | | **LOW** | Deviation from SOTA, friction | Missing frozen-string-literal comments, `Struct` where `Data` fits, stringly-typed booleans, unpinned dev tooling | | **INFO** | Worth knowing, no action forced | YJIT not enabled, typing (RBS/Sorbet) absent, newer-Ruby features available after a floor bump |

Finding format

file:line | rule violated (rules/NN §section) | severity | effort | fix

This is the router's canonical row; each finding carries the [`sota` rules/03](../sota/rules/03-audit-findings.md) §2 evidence block, and the report follows its §5 order.

Severity: Critical / High / Medium / Low / Info. Effort: trivial / small / medium / large. Borderline severities state the deciding assumption; unconfirmed findings are marked "needs verification", never asserted. Group findings by severity, CRITICAL first; end with counts per severity, the three highest-leverage fixes, and which checklists were run.

Rules index

| File | Read this when... | |---|---| | [`rules/01-language-idioms.md`](rules/01-language-idioms.md) | Choosing/verifying the Ruby version baseline; frozen string literals; pattern matching; `Data` vs `Struct`; exception design, **what `rescue => e` misses (`SystemStackError`, `NoMemoryError`) and JSON depth limits**; **`ni