Rails app rules

# AGENTS.md: Rails app

Ruby on Rails app. Check `Gemfile.lock` for the Rails version before using newer APIs; these rules assume Rails 8.

## Commands
- Tests: `bin/rails test` (and `bin/rails test:system` if system tests exist). Single file:
  `bin/rails test test/models/order_test.rb`.
- Lint: `bin/rubocop` (rubocop-rails-omakase in new apps). Security: `bin/brakeman --no-pager`.
- Migrations: `bin/rails db:migrate`, then confirm `bin/rails db:rollback` and migrate again work.
- Done means: tests green, rubocop clean, brakeman shows no new warnings, `db/schema.rb` changed only by migrations.

## Models and the database
- Every schema change is a migration generated with `bin/rails generate migration`. Never edit `db/schema.rb` by hand.
- Migrations are reversible (`change` with reversible operations, or `up` and `down`). No data backfills in schema
  migrations on large tables; write a separate task or job.
- Constraints in the database as well as the model: `null: false`, foreign keys, unique indexes behind
  `validates ... uniqueness`.
- If `strong_migrations` is in the Gemfile, follow its advice instead of silencing it.
- Avoid N+1 queries: `includes` or `preload` for associations used in loops. Prove it with `assert_queries_count`.
- Money in integer minor units or `decimal`, never `float`.
- New model or column: use the `rails-model-change` skill.

## Controllers and views
- Strong parameters with `params.expect(order: [:title, :quantity])` (Rails 8) or `require`/`permit`. Never
  `permit!`.
- Keep controllers to the seven REST actions where possible; add a new controller rather than custom actions.
- Escape output: no `html_safe` or `raw` on user content. Use `sanitize` with an allow-list if HTML is required.
- Authorise every record lookup through the current user (`current_user.orders.find(params[:id])`).

## Secrets and config
- Credentials live in `config/credentials.yml.enc`, edited with `bin/rails credentials:edit`. Never commit
  `config/master.key` or print credentials.
- Do not run commands against production (`RAILS_ENV=production`, `kamal`, `cap`) unless the user asks.

## Dependencies
- Ask before adding a gem. Add it with `bundle add <gem> --version "~> x.y"` and commit `Gemfile.lock`.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `rails-model-change`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Rails app rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/rails-app/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `rails-model-change`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Rails app rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/rails-app/ -->

---
name: rails-model-change
description: Add or change a Rails model with a reversible migration, database constraints, validations, an N+1-safe query scope and a model test. Use for new tables, new columns and new associations.
---

# Rails model change

Examples: `references/20261017120000_create_orders.rb`, `references/order.rb`, `references/order_test.rb`.

1. Generate, do not hand-write the file name: `bin/rails generate migration CreateOrders` (or `AddXToY`).
2. In the migration:
   - `null: false` on required columns, with a default where it makes sense.
   - `t.references ... foreign_key: true` for associations.
   - A unique index for anything validated as unique.
   - Money as integer pence (`price_pence`) or `decimal` with precision and scale.
3. Run `bin/rails db:migrate`, then `bin/rails db:rollback` and `bin/rails db:migrate` again. Both directions must work.
   Commit the `db/schema.rb` change the migration produced.
4. Model: validations that mirror the constraints, associations with `dependent:` chosen on purpose, and scopes that
   preload what callers will use.
5. Test in `test/models/`: one test per validation, one for each scope, and an `assert_queries_count` test for any
   scope that should avoid N+1 queries.
6. Run `bin/rails test test/models/<model>_test.rb`, then the full suite and `bin/rubocop`.

class CreateOrders < ActiveRecord::Migration[8.1]
  def change
    create_table :customers do |t|
      t.string :email, null: false
      t.timestamps
    end
    add_index :customers, :email, unique: true

    create_table :orders do |t|
      t.references :customer, null: false, foreign_key: true
      t.string :reference, null: false
      t.integer :total_pence, null: false, default: 0
      t.string :status, null: false, default: "pending"
      t.timestamps
    end
    add_index :orders, :reference, unique: true
  end
end

class Customer < ApplicationRecord
  has_many :orders, dependent: :restrict_with_error

  normalizes :email, with: ->(email) { email.strip.downcase }
  validates :email, presence: true, uniqueness: true
end

class Order < ApplicationRecord
  STATUSES = %w[pending paid refunded].freeze

  belongs_to :customer

  validates :reference, presence: true, uniqueness: true, format: { with: /\AORD-\d{6}\z/ }
  validates :total_pence, numericality: { only_integer: true, greater_than_or_equal_to: 0 }
  validates :status, inclusion: { in: STATUSES }

  scope :paid, -> { where(status: "paid") }
  scope :with_customer, -> { includes(:customer) }

  def total
    format("£%.2f", total_pence / 100.0)
  end
end

require "test_helper"

class OrderTest < ActiveSupport::TestCase
  setup do
    @customer = Customer.create!(email: "  Ada@Example.com ")
  end

  test "normalises customer email" do
    assert_equal "ada@example.com", @customer.email
  end

  test "requires a well-formed, unique reference" do
    Order.create!(customer: @customer, reference: "ORD-000001", total_pence: 1250)
    duplicate = Order.new(customer: @customer, reference: "ORD-000001")
    assert_not duplicate.valid?
    assert_includes duplicate.errors[:reference], "has already been taken"
    assert_not Order.new(customer: @customer, reference: "123").valid?
  end

  test "rejects negative totals and unknown statuses" do
    order = Order.new(customer: @customer, reference: "ORD-000002", total_pence: -1, status: "lost")
    assert_not order.valid?
    assert order.errors.key?(:total_pence)
    assert order.errors.key?(:status)
  end

  test "formats the total in pounds" do
    assert_equal "£12.50", Order.new(total_pence: 1250).total
  end

  test "paid scope filters by status" do
    paid = Order.create!(customer: @customer, reference: "ORD-000003", status: "paid")
    Order.create!(customer: @customer, reference: "ORD-000004")
    assert_equal [ paid ], Order.paid.to_a
  end

  test "with_customer avoids N+1 queries" do
    3.times { |i| Order.create!(customer: Customer.create!(email: "c#{i}@example.com"), reference: format("ORD-1%05d", i)) }
    assert_queries_count(2) do
      Order.with_customer.each { |order| order.customer.email }
    end
  end
end