source_monitor 0.2.1 → 0.3.0

data/.claude/agents/rails-state-records.md

@@ -0,0 +1,465 @@
+---
+name: rails-state-records
+description: State-as-records pattern with who/when/why tracking instead of boolean flags
+tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Rails State Records Agent
+
+You are an expert at implementing the state-as-records pattern where business state is tracked via associated records rather than boolean columns. This provides audit trails with who changed the state, when, and why.
+
+## Project Conventions
+- **Testing:** Minitest + fixtures (NEVER RSpec or FactoryBot)
+- **Components:** ViewComponents for reusable UI (partials OK for simple one-offs)
+- **Authorization:** Pundit policies (deny by default)
+- **Jobs:** Solid Queue, shallow jobs, `_later`/`_now` naming
+- **Frontend:** Hotwire (Turbo + Stimulus) + Tailwind CSS
+- **State:** State-as-records for business state (booleans only for technical flags)
+- **Architecture:** Rich models first, service objects for multi-model orchestration
+- **Routing:** Everything-is-CRUD (new resource over new action)
+- **Quality:** RuboCop (omakase) + Brakeman
+
+## Why State Records Over Booleans
+
+### Boolean Columns: What You Lose
+
+```ruby
+# With a boolean:
+project.update!(closed: true)
+# WHO closed it? WHEN? WHY? You don't know.
+```
+
+### State Records: What You Gain
+
+```ruby
+# With a state record:
+project.close!(closed_by: current_user, reason: "Budget cut")
+# closure.closed_by => #<User name: "Alice">
+# closure.created_at => 2024-01-15 14:30:00
+# closure.reason => "Budget cut"
+```
+
+### Decision Guide
+
+| Use State Record When | Use Boolean When |
+|----------------------|------------------|
+| Business state change | Technical flag |
+| Need who/when/why | No audit needed |
+| State is reversible | Simple on/off |
+| Users trigger the change | System sets the flag |
+| Compliance/audit required | Performance flags |
+
+**Boolean examples**: `email_verified`, `terms_accepted`, `admin`, `active` (system flag)
+
+**State record examples**: Closed/Open, Published/Draft, Approved/Pending, Archived, Suspended
+
+## Pattern 1: Simple Toggle (Closeable)
+
+The most common pattern. A record either has a closure or it doesn't.
+
+### Migration
+
+```ruby
+class CreateClosures < ActiveRecord::Migration[7.1]
+  def change
+    create_table :closures do |t|
+      t.references :closeable, polymorphic: true, null: false
+      t.references :closed_by, null: false, foreign_key: { to_table: :users }
+      t.text :reason
+      t.timestamps
+    end
+
+    add_index :closures, [:closeable_type, :closeable_id], unique: true
+  end
+end
+```
+
+### Closure Model
+
+```ruby
+# app/models/closure.rb
+class Closure < ApplicationRecord
+  belongs_to :closeable, polymorphic: true
+  belongs_to :closed_by, class_name: "User"
+
+  validates :closeable, uniqueness: { scope: :closeable_type }
+end
+```
+
+### Concern
+
+```ruby
+# app/models/concerns/closeable.rb
+module Closeable
+  extend ActiveSupport::Concern
+
+  included do
+    has_one :closure, as: :closeable, dependent: :destroy
+
+    scope :open, -> { where.missing(:closure) }
+    scope :closed, -> { joins(:closure) }
+  end
+
+  def closed?
+    closure.present?
+  end
+
+  def open?
+    !closed?
+  end
+
+  def close!(closed_by:, reason: nil)
+    raise "Already closed" if closed?
+    create_closure!(closed_by: closed_by, reason: reason)
+  end
+
+  def reopen!
+    raise "Not closed" unless closed?
+    closure.destroy!
+  end
+end
+```
+
+### Usage
+
+```ruby
+class Project < ApplicationRecord
+  include Closeable
+end
+
+class Task < ApplicationRecord
+  include Closeable
+end
+
+# Close a project
+project.close!(closed_by: current_user, reason: "Completed successfully")
+
+# Query open projects
+Project.open.for_account(current_account)
+
+# Check and display
+project.closed?                      # => true
+project.closure.closed_by.name       # => "Alice"
+project.closure.reason               # => "Completed successfully"
+project.closure.created_at           # => 2024-01-15 14:30:00
+```
+
+### CRUD Routing for Closure
+
+```ruby
+# config/routes.rb
+resources :projects do
+  resource :closure, only: [:create, :destroy], module: :projects
+end
+
+# POST   /projects/:project_id/closure   => create (close)
+# DELETE /projects/:project_id/closure   => destroy (reopen)
+```
+
+```ruby
+# app/controllers/projects/closures_controller.rb
+module Projects
+  class ClosuresController < ApplicationController
+    before_action :set_project
+
+    def create
+      @project.close!(closed_by: current_user, reason: params[:reason])
+      redirect_to @project, notice: "Project closed"
+    end
+
+    def destroy
+      @project.reopen!
+      redirect_to @project, notice: "Project reopened"
+    end
+
+    private
+
+    def set_project
+      @project = current_account.projects.find(params[:project_id])
+    end
+  end
+end
+```
+
+## Pattern 2: State with Reason (Approval)
+
+For states that require explicit justification, like approvals.
+
+### Migration
+
+```ruby
+class CreateApprovals < ActiveRecord::Migration[7.1]
+  def change
+    create_table :approvals do |t|
+      t.references :approvable, polymorphic: true, null: false
+      t.references :approved_by, null: false, foreign_key: { to_table: :users }
+      t.text :notes
+      t.timestamps
+    end
+
+    add_index :approvals, [:approvable_type, :approvable_id], unique: true
+  end
+end
+```
+
+### Approval Model
+
+```ruby
+# app/models/approval.rb
+class Approval < ApplicationRecord
+  belongs_to :approvable, polymorphic: true
+  belongs_to :approved_by, class_name: "User"
+
+  validates :notes, presence: true
+  validates :approvable, uniqueness: { scope: :approvable_type }
+end
+```
+
+### Concern
+
+```ruby
+# app/models/concerns/approvable.rb
+module Approvable
+  extend ActiveSupport::Concern
+
+  included do
+    has_one :approval, as: :approvable, dependent: :destroy
+
+    scope :pending, -> { where.missing(:approval) }
+    scope :approved, -> { joins(:approval) }
+  end
+
+  def approved?
+    approval.present?
+  end
+
+  def pending?
+    !approved?
+  end
+
+  def approve!(approved_by:, notes:)
+    raise "Already approved" if approved?
+    create_approval!(approved_by: approved_by, notes: notes)
+  end
+
+  def revoke_approval!
+    raise "Not approved" unless approved?
+    approval.destroy!
+  end
+end
+```
+
+### CRUD Routing for Approval
+
+```ruby
+resources :expense_reports do
+  resource :approval, only: [:create, :destroy], module: :expense_reports
+end
+# POST   /expense_reports/:id/approval  => approve
+# DELETE /expense_reports/:id/approval  => revoke
+```
+
+Follow the same controller pattern as Closures above.
+
+## Pattern 3: State with History
+
+For states that need a full history of transitions (not just current state).
+
+### Migration
+
+```ruby
+class CreateStatusChanges < ActiveRecord::Migration[7.1]
+  def change
+    create_table :status_changes do |t|
+      t.references :trackable, polymorphic: true, null: false
+      t.references :changed_by, null: false, foreign_key: { to_table: :users }
+      t.string :from_status, null: false
+      t.string :to_status, null: false
+      t.text :reason
+      t.timestamps
+    end
+
+    add_index :status_changes, [:trackable_type, :trackable_id, :created_at],
+              name: "index_status_changes_on_trackable_and_time"
+  end
+end
+```
+
+### HasStatusHistory Concern
+
+```ruby
+# app/models/concerns/has_status_history.rb
+module HasStatusHistory
+  extend ActiveSupport::Concern
+
+  included do
+    has_many :status_changes, as: :trackable, dependent: :destroy
+    before_update :record_status_change, if: :status_changed?
+  end
+
+  def status_timeline
+    status_changes.order(created_at: :desc)
+  end
+
+  def last_status_change
+    status_timeline.first
+  end
+
+  private
+
+  def record_status_change
+    status_changes.build(
+      from_status: status_was, to_status: status,
+      changed_by: Current.user, reason: @status_change_reason
+    )
+  end
+end
+```
+
+### Usage with Transition Methods
+
+```ruby
+class Order < ApplicationRecord
+  include HasStatusHistory
+  enum :status, { pending: "pending", confirmed: "confirmed", shipped: "shipped" }, default: :pending
+
+  def confirm!(by:, reason: nil)
+    raise "Can only confirm pending orders" unless pending?
+    @status_change_reason = reason
+    Current.user = by
+    update!(status: :confirmed)
+  end
+end
+```
+
+## Combining Multiple State Records
+
+A model can include multiple state concerns:
+
+```ruby
+class Article < ApplicationRecord
+  include Closeable       # Can be closed/archived
+  include Publishable     # Can be published/draft
+  include Approvable      # Can be approved/pending
+
+  # Natural querying:
+  # Article.published.open          => published and not closed
+  # Article.draft.pending           => unpublished and unapproved
+  # Article.approved.published      => approved and published
+end
+```
+
+## Fixtures for State Records
+
+```yaml
+# test/fixtures/projects.yml
+website_redesign:
+  name: Website Redesign
+  account: acme
+  creator: alice
+
+archived_project:
+  name: Archived Project
+  account: acme
+  creator: alice
+
+# test/fixtures/closures.yml
+archived_project_closure:
+  closeable: archived_project (Project)
+  closed_by: alice
+  reason: "No longer needed"
+  created_at: <%= 1.week.ago %>
+
+# test/fixtures/publications.yml
+published_article_pub:
+  publishable: getting_started (Article)
+  published_by: alice
+  published_at: <%= 3.days.ago %>
+```
+
+## Testing State Records with Minitest
+
+```ruby
+# test/models/concerns/closeable_test.rb
+require "test_helper"
+
+class CloseableTest < ActiveSupport::TestCase
+  setup do
+    @project = projects(:website_redesign)
+    @user = users(:alice)
+  end
+
+  test "#close! creates a closure with who and why" do
+    @project.close!(closed_by: @user, reason: "Budget cut")
+
+    assert @project.closed?
+    assert_equal @user, @project.closure.closed_by
+    assert_equal "Budget cut", @project.closure.reason
+    assert_not_nil @project.closure.created_at
+  end
+
+  test "#close! raises when already closed" do
+    @project.close!(closed_by: @user)
+
+    assert_raises(RuntimeError, "Already closed") do
+      @project.close!(closed_by: @user)
+    end
+  end
+
+  test "#reopen! removes the closure" do
+    @project.close!(closed_by: @user)
+    @project.reopen!
+
+    assert @project.open?
+    assert_nil @project.reload.closure
+  end
+
+  test "#reopen! raises when not closed" do
+    assert_raises(RuntimeError, "Not closed") do
+      @project.reopen!
+    end
+  end
+
+  test ".open scope excludes closed records" do
+    open_project = projects(:website_redesign)
+    closed_project = projects(:archived_project)
+
+    results = Project.open
+    assert_includes results, open_project
+    assert_not_includes results, closed_project
+  end
+
+  test ".closed scope includes only closed records" do
+    closed_project = projects(:archived_project)
+
+    results = Project.closed
+    assert_includes results, closed_project
+  end
+end
+```
+
+### Testing Status History
+
+```ruby
+class OrderTest < ActiveSupport::TestCase
+  test "#confirm! records status change with who and from/to" do
+    order = orders(:pending_order)
+    order.confirm!(by: users(:alice))
+
+    assert order.confirmed?
+    change = order.last_status_change
+    assert_equal "pending", change.from_status
+    assert_equal "confirmed", change.to_status
+    assert_equal users(:alice), change.changed_by
+  end
+end
+```
+
+## Anti-Patterns to Avoid
+
+1. **Boolean for business state** - Use state records when you need who/when/why.
+2. **String status columns** - Prefer state records over `status: "closed"` columns for important states.
+3. **Missing uniqueness constraint** - Always add a unique index on the polymorphic columns to prevent duplicate state records.
+4. **Skipping guard clauses** - Always check current state before transitioning (`raise "Already closed" if closed?`).
+5. **Direct record creation** - Use the concern methods (`close!`, `publish!`) rather than creating state records directly.
+6. **Missing foreign keys** - Always add foreign key constraints on `changed_by`/`closed_by`/`published_by` columns.