drive 0.1.0

data/CLAUDE.md

@@ -0,0 +1,690 @@
+# Coding Guidelines
+
+**Scope:** This file is the authority for code style in this project. The
+baseline is standard community Ruby/Rails practice, plus the learned preferences
+recorded at the bottom.
+
+## Ruby
+
+- Two-space indentation, no tabs. No trailing whitespace; newline at EOF.
+- `snake_case` for methods/variables, `CamelCase` for classes/modules,
+  `SCREAMING_SNAKE_CASE` for constants.
+- Predicate methods end in `?`; mutating/dangerous variants end in `!`.
+- `do...end` for multi-line blocks, `{...}` for single-line blocks.
+- Guard clauses over nested conditionals. Return early.
+- Use `unless` for simple negatives; never `unless ... else`.
+- Prefer `&.`, `||=`, `Array()`, `Hash#fetch` with defaults, and keyword
+  arguments over positional args once there are more than two.
+- Keep methods short and single-purpose. Extract private methods freely.
+- Comment *why*, not *what*. Don't narrate the code.
+
+## Rails
+
+- **Follow the Rails Way.** Reach for framework features before writing
+  custom infrastructure.
+- Fat model / skinny controller. Controllers do routing, authorization,
+  params, and rendering — nothing else.
+- RESTful routes and the seven standard actions. Prefer nested resources or
+  new controllers over custom actions.
+- Use strong parameters; never pass raw `params` to a model.
+- Scopes for reusable queries; avoid query logic in controllers or views.
+- Guard against N+1 with `includes` / `preload` / `eager_load`.
+- Validations and DB constraints together — the database is the last line of
+  defense (null constraints, unique indexes, foreign keys).
+- Migrations are reversible; never edit a migration that has shipped.
+- Concerns for genuinely shared behavior, not as a dumping ground.
+- Background jobs (Active Job) for anything slow or external.
+- Secrets in credentials/ENV — never committed.
+- Views: partials and helpers over logic in ERB. No queries in views.
+- I18n for user-facing strings.
+
+## Testing
+
+- Never test another library. `validates :name, presence: true` is Rails'
+  behavior, already tested in Rails, so a test asserting a blank name is
+  invalid tests nothing of ours. Same for a unique index raising, or pagy
+  splitting 25 rows across two pages.
+- Test our data, our wiring, our own methods: what a backfill contains, what a
+  helper returns, what markup a view produces, how many queries a page costs.
+- Every behavior change comes with a test.
+- Test behavior and public interfaces, not private implementation details.
+- Descriptive test names that state the expected outcome.
+- Prefer fixtures/factories that are minimal and explicit.
+- Keep tests independent and order-agnostic.
+
+## Git
+
+- Small, focused commits. Imperative mood subject lines ("Add", not "Added").
+- Explain *why* in the body when the change isn't self-evident.
+
+---
+
+## Learned preferences
+
+Guidance from Claudio, recorded as it comes up. These override the baseline
+above when they conflict.
+
+Grouped under what each rule is *for*: performance, security, testing,
+maintainability, readability, internationalization. A new rule goes under the
+heading it serves, not at the end of the file, and a rule that could sit under
+two is filed under the one a reader would look in first.
+
+### PERFORMANCE
+
+#### PostgreSQL, always
+
+- When an app needs a database, it is PostgreSQL. Never MySQL, never SQLite —
+  including for test-only apps like `test/dummy`, and including cases where
+  SQLite would be less setup.
+- Running the test suite therefore needs a PostgreSQL server. `test/test_helper`
+  creates the database on first run, so `rake test` is still the only command
+  needed once the server is up.
+
+#### Cache a query or a fragment that repeats
+
+- Reach for `Rails.cache` wherever the same rows would be read or the same markup
+  re-rendered. An index table and the option list behind a combobox are both
+  cached; `/locations/new` costs six queries cold and three warm, and the
+  40,965-row `SELECT` behind its ZIP menu is one of the three that go.
+- Key a fragment on the *relation*, `cache recourses do`, never on a hand-rolled
+  string. Rails builds the key from a digest of the SQL — so a different page of
+  the same table is a different key — and pairs it with a version from the row
+  count and the newest `updated_at`, so nothing has to remember to expire it.
+- That version check is itself a `SELECT COUNT(*), MAX(updated_at)`, and it is the
+  price of never serving a stale menu. Keying on `recourses.cache_key` instead
+  skips it and queries nothing at all, at the cost of a list that never notices a
+  new row — only worth it behind an `expires_in`, and only for data that may lag.
+- The check is free where the relation is already loaded, which is why the index
+  costs nothing extra: `blank?` loads it before the table renders, so the version
+  is counted in Ruby. Another reason to prefer `blank?` over `empty?`.
+- Cache the table, not the pagination around it. The nav changes with the page and
+  is cheap to draw.
+- A cache that is off in tests is a cache nobody tests. The dummy app sets
+  `config.cache_store = :memory_store` for the test environment: caching stays on,
+  and the run leaves no files behind.
+
+#### Fewest SQL queries to render a page
+
+- Rendering a page should issue as few queries as it can. Treat an extra query
+  as a defect, not a detail.
+- When checking whether a relation has records *and then looping over them*, use
+  `present?` and `blank?`, never `any?` and `empty?`. `blank?` runs the
+  `SELECT "contacts".*` that the loop needs anyway and caches it; `empty?` runs a
+  separate `SELECT 1 ... LIMIT 1` first, so the page costs two queries instead of
+  one.
+- `any?` and `empty?` are still right when nothing will be looped over.
+- An index eager-loads every `belongs_to` its table can name, since each cell that
+  shows a referenced record would otherwise be a query of its own:
+  `resource_class.includes(*names)`. Twenty locations cost five queries rather than
+  forty-two, and the count no longer grows with the page.
+- Worth a test: assert the query count, so a later edit cannot quietly add one
+  back. `test_it_costs_one_count_and_one_select` does this by subscribing to
+  `sql.active_record`, and it is one of the two tests exempt from "as few tests
+  as coverage needs".
+
+#### Select only the columns a query displays
+
+- A query built to display something fetches those columns and no others.
+  The combobox of states shows a name per row and submits an id, so it reads
+  `State.select(:id, :name).order(:name)` — not `State.order(:name)`.
+- This sits alongside "fewest SQL queries to render a page": the count of
+  queries is one cost and the width of each is another.
+- It applies where the columns are known. A generic table hands the record to a
+  row partial that may touch anything, so it selects everything on purpose.
+
+#### Emails are citext
+
+- A plaintext email column is `citext`, never `string`. An address is
+  case-insensitive in practice, so `Ada@example.com` and `ada@example.com` are
+  the same one, and the column type is what makes comparison and a unique index
+  agree with that.
+- citext arrives with its extension, so a migration runs
+  `enable_extension 'citext'` before the first citext column is created.
+- Nothing else is then needed: no `LOWER(email)` expression index, and no
+  downcasing on the way in.
+- An *encrypted* email column is not citext — the same reasoning as the rest of
+  "Encrypt PII". What is stored is ciphertext, so a case-insensitive column
+  compares the wrong bytes and could reject two genuinely different addresses.
+  Normalize in Rails instead, always with both options:
+  `encrypts :email, deterministic: true, downcase: true`.
+- `deterministic: true` is not conditional on the column being unique or
+  queried *today*. An address is the natural handle for finding a record, so it
+  will be looked up eventually, and switching afterwards means re-encrypting
+  every row. `downcase: true` is what earns the case-insensitivity the citext
+  column would have given, and it is what keeps a unique index honest: without
+  it two spellings of one address encrypt to two different values.
+
+### SECURITY
+
+#### Encrypt PII
+
+- Personal data is stored with Active Record Encryption: `encrypts :phone`,
+  `:email`, `:surname`, `:street`. Suspect a column is personal? Ask before
+  storing it in the clear.
+- `name` is not PII and is not encrypted. A first name on its own does not
+  identify anyone; a surname does. Asked and settled — do not encrypt it.
+- A column that is queried or must stay unique needs
+  `encrypts :phone, deterministic: true`. Non-deterministic ciphertext differs
+  every write, which silently defeats both a unique index and a uniqueness
+  validation — they will pass while duplicates pile up.
+- Never constrain the *shape* of an encrypted value in the database. What is
+  stored is ciphertext, so only `null: false` and a unique index still mean
+  anything; the format belongs to the model.
+- Encrypted columns never appear in a generic table, so encrypting a column
+  removes it from the index page. That is intended — see `STYLE.md`.
+
+#### Phone numbers
+
+- A phone number is stored in a column named `phone`, holding exactly 10
+  digits.
+- The database enforces `null: false` and a unique index. It does not check the
+  ten-digit shape — a phone is PII, so it is encrypted, and no constraint can
+  read ciphertext.
+- Rails is where the shape is enforced: the model includes a `Phonable` concern
+  carrying both rules:
+
+      NORTH_AMERICAN_PHONES = /\A[2-9]\d{2}[2-9]\d{6}\z/
+
+      normalizes :phone, with: ->(phone) { phone.delete('^0-9').delete_prefix '1' }
+
+      with_options format: { with: NORTH_AMERICAN_PHONES, message: '...' } do
+        validates :phone, allow_nil: true
+      end
+
+- The concern's validation is `allow_nil`, so whether a phone is *required* is
+  the including model's decision — add `presence: true` there, not in the
+  concern.
+
+### TESTING
+
+#### Coverage stays at 100%
+
+- `simplecov` starts at the very top of `test/test_helper.rb`, before anything
+  else is required, with `minimum_coverage 100`. Below that the suite fails.
+- `skip '/test/'` leaves the dummy app out: it is a fixture, not shipped code.
+  Never `add_filter` — SimpleCov deprecated it in favour of `skip`, same
+  arguments and same behaviour, and it warns on every run until changed.
+- `lib/recourse/version.rb` is not measured, and that is expected rather than a
+  gap. The Gemfile's `gemspec` directive loads it during bundler setup, before
+  SimpleCov can start. Do not add `track_files` to pull it in — it would report
+  as uncovered when in fact it runs.
+
+#### As few tests as coverage needs
+
+- The suite exists to cover the code, so a test that can be deleted while
+  coverage stays at 100% is a test to delete. Write the smallest set that gets
+  there and stop.
+- Never add a test for lines the suite already covers, even to reach a *branch*
+  it misses. Line coverage is the whole budget.
+- Never test a migration. A backfill's row count, the values it wrote and the
+  invariants between them are data, and asserting them exercises no code of
+  ours. `TestState` was five such tests, so the whole class went, and
+  `TestCounty` and `TestZIP` with it.
+- A model that only declares validations, associations and encryption is in the
+  same position: nothing measured runs, so it gets no test file. That took
+  `TestPhonable` and `TestEmails` too.
+- This narrows the baseline's "every behavior change comes with a test": the
+  test comes with it only if it reaches a line nothing else does. The suite it
+  leaves is small on purpose — six tests for 146 lines.
+- Two kinds of assertion are exempt, because a covered line cannot stand in for
+  them. How many queries a page costs, and whether an encrypted column reaches
+  the page: both run exactly the same lines whether they hold or not, so
+  coverage stays green while the behavior breaks. The PII leak that prompted the
+  second exemption printed an address at 100%.
+- Nothing else is exempt. Markup, titles, breadcrumbs, icons, pagination links
+  and the order of the sidebar are all asserted by whichever test happens to
+  render the page, and no test is added to pin them down further.
+
+### MAINTAINABILITY
+
+#### No metaprogramming
+
+- Never call `send` or `public_send`. Reach the data directly instead:
+  `resource.attributes[column]`, not `resource.public_send column`.
+- No `define_method`, `method_missing`, `instance_variable_get` / `_set`,
+  `const_set`, `constantize`, or `eval` of any kind.
+- The single exception is an explicit instruction to use it. Never reach for
+  metaprogramming on your own initiative, and never treat the places that
+  already use it as permission to add another — ask instead.
+
+#### Trailing comma on a multiline hash
+
+- A multiline hash ends its last entry with a comma, so adding an entry touches
+  one line instead of two:
+
+      NAVIGATION_ICONS = {
+        'States' => 'geo', 'ZIPs' => 'geo-alt-fill',
+      }.freeze
+
+- Put the closing brace on its own line. With the brace trailing the last entry
+  the comma reads as `, }`, which is worse than either alternative.
+- Enforced by `Style/TrailingCommaInHashLiteral` with
+  `EnforcedStyleForMultiline: consistent_comma`. Not `comma` — that style
+  *forbids* the comma unless every entry sits on its own line, and ours share
+  lines.
+
+#### Keep render lines out of the logs
+
+- An app's log never carries Action View's `Rendering ...` and `Rendered ...`
+  lines. One line per partial buries the request that matters — a 20-row table
+  rendering a row partial produces 20 of them.
+- Set `config.action_view.logger = nil` in `config/application.rb`. Everything
+  else stays: the request, the SQL, and the `Completed 200 OK` timing line,
+  which still reports view time.
+- This is a rule for apps we write. The gem never touches a host's logging.
+
+#### Keep RuboCop current
+
+- `AllCops: NewCops: enable`. Cops added by a new RuboCop release are active
+  immediately rather than sitting pending; fix what they surface instead of
+  pinning the version.
+- `Gemspec/RequireMFA` is one of those, so the gemspec sets
+  `metadata['rubygems_mfa_required']` and publishing needs MFA on the RubyGems
+  account.
+- `AllCops: SuggestExtensions: false`. Every run was ending with a nine-line
+  advert for `rubocop-minitest` and `rubocop-rake`; we are declining both, not
+  postponing them, so the suggestion is off rather than merely ignored.
+
+#### Gemfile ordering and version constraints
+
+- List gems alphabetically, in one block — no blank lines splitting the list,
+  since those read as separate groups.
+- Never use `~>`. Use `>=` only where a minimum version is genuinely required,
+  and otherwise give no constraint at all.
+- Every gem carries a trailing comment on the same line saying why it is
+  there — what would break without it, not what the gem is.
+- The same applies to `add_dependency` in the gemspec.
+
+#### No code of conduct, no ideology
+
+- Never add a `CODE_OF_CONDUCT.md`, and never link to or mention one from the
+  README, gemspec, or any other file. Generators that create one (`bundle
+  gem`) have their output deleted.
+- Keep the codebase free of content about ethics, religion, or politics —
+  including comments, docs, error messages, test fixtures, and sample data.
+- `LICENSE.txt` is not covered by this: a license is a legal notice.
+
+#### Target Rails 8.1+
+
+- All Rails libraries are required at `>= 8.1`. Write against current Rails
+  APIs only.
+- Never add version checks, shims, or fallbacks for older Rails or Ruby.
+
+#### No static typing
+
+- Never write Ruby type signatures, and never add a strong-typing tool.
+- No RBS: no `sig/` directory, no `.rbs` files. `bundle gem` creates one —
+  delete it.
+- No Sorbet: no `# typed:` sigils, no `sig { ... }` blocks, no `T.let` /
+  `T.nilable` / `T.must`, no `srb` or `tapioca`.
+- Never add these gems: `sorbet`, `sorbet-runtime`, `rbs`, `steep`, `tapioca`.
+- Convey intent through clear names, short methods, and tests instead.
+
+#### Branch and commit per prompt
+
+- Before starting a code change, if the current branch is `main`, create a
+  branch first. Short name, lowercase words, underscores only — no dashes,
+  no slashes, no ticket prefixes (`git_conventions`, `dummy_app`).
+- If already on a branch other than `main`, keep working on it.
+- After completing the code change a prompt asked for, commit it. The subject
+  is a short summary of the prompt; the body is the full response given for
+  that prompt.
+- One prompt, one commit.
+
+#### Ask the validators, not the schema
+
+- What a value is allowed to be is the model's business, so read it from the
+  validators. A length validator gives a field its `maxlength` and `minlength`, a
+  format validator its `pattern`, a numericality validator its numeric keyboard.
+  Never reach into `columns_hash` for a `limit` or for a type.
+- The schema and the validators disagree more often than it looks. A `limit: 5`
+  column with no length validator accepts four characters; an encrypted column's
+  limit describes ciphertext. Following the model keeps the browser saying what
+  the server will actually enforce.
+- Where no validator can answer — which of `date`, `time` and `datetime` an
+  attribute is — ask the model anyway, through `type_for_attribute`. It reports
+  what the model declares, so an `attribute :opens_on, :date` override counts,
+  and `columns_hash` still never appears.
+- Corollary for the database: a constraint the model does not also state is a
+  constraint the browser cannot show. Add the validator too.
+
+#### Match Bootstrap with field_error_proc
+
+- Wherever Bootstrap is the CSS framework, set
+  `config.action_view.field_error_proc`. Rails' default wraps a rejected field in
+  `<div class='field_with_errors'>`, which Bootstrap styles not at all: no red
+  border, and the message nowhere on the page.
+- The proc adds `is-invalid` to the control and follows it with a
+  `<small class='invalid-feedback'>`, which is the pair Bootstrap needs — its
+  `.is-invalid ~ .invalid-feedback` reveals one only next to the other.
+- Guard on the control's class, not on the tag's type. A label carries
+  `form-label` and falls straight through, and so does anything else without a
+  `form-control`. Guarding on `instance.is_a? ActionView::Helpers::Tags::Label`
+  instead leaves `html_tag.index 'form-control'` returning nil for every other
+  kind of tag, and `insert nil` raises.
+- The proc is `instance_exec`'d on the view, so `tag` and `safe_join` are in
+  scope — no need to write markup as a string.
+- Which is just as well, because `insert` on a SafeBuffer escapes what it is
+  given: an attribute spliced in by hand arrives as `&#39;`. Build it with
+  `tag.attributes` and join it with `safe_join`.
+- A rule for apps we write. The gem never sets a host's Action View config, the
+  same line drawn for the logger and the time zone — so a control the gem draws
+  outside a form builder, like the combobox, carries this markup itself.
+
+#### Every model says how it is labelled
+
+- A model answers `recourse_label` with the column a combobox shows for one of its
+  records. `Recourse::Recoursive` supplies `:name`, and every Active Record model
+  is extended with it through `ActiveSupport.on_load :active_record`, so most
+  models need say nothing at all.
+- A model whose identity is not a `name` overrides it — `:code` for a ZIP, `:email`
+  for an Agent — but never in the model body. It `include`s its own `Recoursive`
+  concern, in `app/models/zip/recoursive.rb`, which overrides inside
+  `class_methods do`. The default arrives by `extend`, so only a class method can
+  replace it.
+- The label is what gets selected: `select(:id, label).order(label)`, per "select
+  only the columns a query displays". So it has to be a real column, not a method —
+  a method would not survive the `SELECT`.
+- Reading it back is `recourse.attributes[label]`, not `public_send`, which "no
+  metaprogramming" rules out.
+- Picking an encrypted column labels the option with its plaintext, since
+  `attributes` decrypts. That is a decision to make deliberately, not to fall into,
+  and it reaches further than a form: a foreign-key column in a *table* shows the
+  same label, so an encrypted one appears on the index of every model that
+  references it. `resource_columns` only keeps a model's own encrypted columns out.
+- `recourse_typed_label?` asks whether that label has a length validator, which is
+  what decides between typing a value and picking from a list. A length is the only
+  honest signal available: it says the value is bounded, so a person can type it.
+- A typed label is looked up on the way in — `ZIP.find_by code: '90210'` — and the
+  form asks for it under the foreign key's own name, so no host model needs a
+  virtual attribute and strong parameters need no special case.
+
+#### Vendor what a page cannot render without
+
+- A stylesheet or script a page cannot do without is vendored into the gem and
+  served from it, never linked to a CDN. A host that fails to reach the CDN gets
+  an unstyled page, and the Bootstrap 6 CSS in particular comes from a preview
+  host with no promise of staying put.
+- The files live in `vendor/recourse/`, and an engine initializer serves them with
+  `Rack::Static`. That is the framework's own middleware rather than a controller
+  action, and it assumes no asset pipeline, which a host may well not have.
+- Keep the slash on the prefix. `urls: %w[/recourse/]` matches on `start_with?`,
+  so `urls: %w[/recourse]` would answer `/recourses` with a 404 from the file
+  server before the router ever saw it — in this gem of all places.
+- Vendor whatever the vendored file itself asks for. `bootstrap-icons.min.css`
+  loads `fonts/bootstrap-icons.woff2` relative to itself, so the CSS without the
+  fonts renders every icon as a blank box.
+- Keep the copies byte-identical to what the CDN serves, so a later version can
+  be diffed against upstream. `git ls-files` puts them in the gem already.
+- Our own JavaScript is not vendored. It lives in `app/javascript/recourse/` and
+  is served at the same prefix: the first `Rack::Static` takes `cascade: true`, so
+  a path it has no file for falls through to the second rather than 404ing. That
+  keeps `vendor/` meaning "upstream's", which is what exempts it from the lint.
+- A Stimulus controller imports Stimulus by its served path, not by the bare
+  `@hotwired/stimulus` specifier. Resolving that name would need an import map,
+  and a host app may already ship one of its own.
+- Start the application in the `<head>`, and guard it with `window.Stimulus`.
+  Turbo re-runs body scripts on every visit, and a second application connects
+  every controller a second time.
+
+#### Seed data lives in migrations, so schema.rb cannot load a database
+
+- `config.active_record.dump_schema_after_migration = false`, so no `schema.rb`
+  is ever written. Gitignoring it is not enough: it regenerates on every migrate
+  and then Rails loads it into the next empty database, stamping every version at
+  or below its own as already migrated — silently skipping the backfills and
+  leaving the tables empty for the next foreign key to trip over.
+- Build a database with `db:migrate` from zero. Never `db:schema:load`, and be
+  wary of `db:prepare` for the same reason.
+- `db:drop` will not drop a database with open connections and reports success
+  anyway; `dropdb --force` is the reliable reset.
+
+#### Design lives in STYLE.md
+
+- Every decision about how a page looks — Bootstrap conventions, class choices,
+  markup structure — is documented in `STYLE.md`, not here. Read that file
+  before writing or editing any layout, view or partial.
+- This file stays the authority for code style. Where the two overlap, `STYLE.md`
+  wins on markup and `CLAUDE.md` wins on Ruby.
+
+### READABILITY
+
+#### Files at most 100 lines
+
+- No code file goes over 100 lines, counting blank and comment lines. When one
+  gets close, split it — extract a class, a concern, a partial, a second test
+  case.
+- Enforced by `rake file_length`, part of the default task. RuboCop has no
+  file-length cop; `Metrics/ClassLength` and friends measure a class body, not a
+  file, and skip comments and blanks by default.
+- `.md`, `.txt`, `.html` and `.erb` are exempt. Prose is not code, and a view
+  is markup whose length is driven by the page, not by design choices.
+- Anything under `db/migrate/` is exempt. A migration that backfills a table is
+  as long as the data it carries, and splitting one to satisfy a line count
+  would be worse than leaving it long.
+- So is anything under `vendor/`. Upstream's formatting is not ours to fix, and a
+  vendored font is not even text — `File.readlines` on a `.woff2` reports
+  thousands of lines that mean nothing.
+- The task reads `git ls-files`, so an untracked file is invisible to it. A green
+  run before `git add` proves nothing about what the commit will contain.
+
+#### Lines at most 100 characters
+
+- Hard limit of 100 characters per line, enforced by RuboCop's
+  `Layout/LineLength` (`Max: 100`, up from its default of 120).
+- Split long strings across lines with `\` continuations rather than letting a
+  line run over.
+- Views are exempt — `.html` and `.erb` files may run past 100 characters,
+  since a CDN URL or a long class list cannot be wrapped usefully. RuboCop does
+  not lint them anyway.
+- When a method call would need three lines and hanging indentation just to fit,
+  hoist the long arguments into a Rails `with_options` block instead. Still
+  three lines, but every line starts at a normal indent:
+
+      with_options format: { with: SOME_PATTERN, message: 'is invalid' } do
+        validates :phone, allow_nil: true
+      end
+
+#### Shared behavior becomes a concern
+
+- When two models declare the same behavior word for word, extract it into a
+  concern instead of leaving the copy in place.
+  `encrypts :email, deterministic: true, downcase: true` stood in both `Contact`
+  and `Agent`, so it became `Emailable`.
+- Name the concern after the feature it carries, not after the models that want
+  it: `Emailable`, `Phonable`.
+- Only what the models genuinely share moves. `Contact`'s email is optional and
+  `Agent`'s is required, so `presence: true` stays in each model — the same line
+  `Phonable` already draws for `phone`.
+- This sharpens the baseline's "concerns for genuinely shared behavior": a second
+  identical declaration is the threshold, and anticipating one is not.
+
+#### As few parentheses as possible
+
+- Omit parentheses on a method call's arguments; keep the inner ones, where
+  parsing needs them:
+
+      Object.const_set class_name, Class.new(RecoursesController)
+
+- Enforced by `Style/MethodCallWithArgsParentheses` with
+  `EnforcedStyle: omit_parentheses`. The cop is off by default, so it needs
+  `Enabled: true` as well as the style.
+
+#### List concerns alphabetically, on one line
+
+- Concerns are included in alphabetical order: `include Emailable, Phonable`,
+  never the other way round.
+- One `include` carries the whole list. Give each its own statement only when
+  the single line would not fit, and then keep the order.
+- Enforced by `Style/MixinGrouping` with `EnforcedStyle: grouped`. Its default
+  is `separated`, which demands the opposite, so the setting is not optional.
+- `include A, B` inserts them in reverse, so `A` ends up ahead of `B` in
+  `ancestors`. It only matters when both define the same method, which two
+  concerns that were extracted for being distinct features should not.
+
+#### Pass locals to partials explicitly
+
+- A partial never reads a controller's instance variables. Declare strict
+  locals on its first line — `<%# locals: (resources:, pagy:) %>` — and pass
+  them at the call site: `render 'table', resources: @resources, pagy: @pagy`.
+- A partial that takes no locals gets no comment at all. Never write
+  `<%# locals: () %>`.
+- A template rendered by an action may read instance variables. The rule is
+  about partials, which should not depend on who rendered them.
+- Rails enforces this: omit a declared local and the render raises instead of
+  quietly rendering a blank.
+- Where two branches need different locals, write `if`/`else` rather than
+  `render cond ? 'a' : 'b'` — a single call cannot pass the right locals to
+  both.
+- The row partial is the deliberate exception, and it breaks the rule twice.
+  Its record arrives under a name computed at runtime (`contact:`, `state:`),
+  so the gem's own `_row` cannot declare strict locals and reads
+  `local_assigns[resource_key]`. And whether it is drawing the header row or a
+  body row travels in `@recourse_headers`, set by `_table` before each render,
+  which `column` reads. Both were asked for; neither is a pattern to copy.
+- The fields partial is the second exception, for the same two reasons. It is
+  handed the record under the runtime name so a host's `_fields` can declare
+  `<%# locals: (contact:) -%>`, while the gem's own cannot; and the form builder
+  travels in `@recourse_form`, set by `_form`, because `field :phone` is the
+  call site the host writes and threading a form through it would spoil that.
+
+#### Spell acronyms as acronyms
+
+- An acronym is written in capitals wherever it appears: ZIP code, not Zip code;
+  PIN, not Pin. That covers prose, comments, class names and labels alike.
+- When a model or column names one, register it so Rails agrees:
+  `inflect.acronym 'ZIP'` in `config/initializers/inflections.rb`. Without it
+  `human_attribute_name` renders `Zip` and every heading and label is wrong.
+- Registering it also fixes `camelize`, so `zip_code` becomes `ZIPCode` rather
+  than `ZipCode` — worth knowing before naming a class after one.
+
+#### Name non-trivial regular expressions
+
+- A regular expression that is not obvious at a glance gets a named constant,
+  so the name explains the intent and the pattern is stated once.
+  `/\A[2-9]\d{2}[2-9]\d{6}\z/` becomes `NORTH_AMERICAN_PHONES`.
+- Put the constant on the class or module that owns the rule, and comment it
+  with what it accepts and rejects — the name says what, the comment says why
+  those bounds.
+- Trivial patterns used once, like `%r{\Aexe/}`, stay inline.
+
+#### Comment every public declaration
+
+- Never comment a private method. The rule below is for the public surface; a
+  private method earns its explanation from its name and its caller.
+- Never put a method in a controller that only a view calls, and never reach for
+  `helper_method` to expose one. If a view needs it, it belongs in a helper
+  module or inline in the template. A controller's private methods are for the
+  controller's own work.
+- Indent `private` to match its `class` or `module`, not the `def`s under it, so
+  it stands out as a divider. Enforced by
+  `Layout/AccessModifierIndentation: EnforcedStyle: outdent`.
+- Precede every public class, module, constant and method declaration with a
+  comment line saying what that object does. This narrows the baseline's
+  "comment why, not what" rule: declarations get a *what*, and the *why* rule
+  still governs comments inside method bodies.
+- Say what it is for, not what the code plainly shows. `# Raised for every
+  failure the gem reports` earns its place; `# The Error class` does not.
+- A module reopened purely as a namespace in another file is not redeclared —
+  document it where it is defined.
+- Enforced by RuboCop: `Style/Documentation` for classes and modules,
+  `Style/DocumentationMethod` (off by default) for methods. Both skip `test/`,
+  matching RuboCop's own default, so test cases stay uncommented — their names
+  state the expectation.
+- Constants have no cop; keep them commented by hand.
+- Keep these comments to a single line whenever possible. If one line cannot
+  carry it, cut the aside rather than the rule — the detail belongs in the
+  commit message. Multi-line is a last resort, not a default.
+
+#### Never freeze strings
+
+- Never write `# frozen_string_literal: true`. No file gets a magic comment,
+  including generated ones — strip it from generator output.
+- Never call `.freeze` on a string, constant or not. Array and hash constants
+  are still worth freezing by hand.
+- Where a constant only names something, prefer a symbol over a string — it is
+  immutable already, so the question does not arise.
+- Enforced by RuboCop: `Style/FrozenStringLiteralComment` is `never`, and
+  `Style/MutableConstant` is disabled because it demands `.freeze` on string
+  constants and cannot be told to skip them.
+
+#### Single quotes by default
+
+- Always use single-quoted strings.
+- Double quotes only when the string genuinely needs them: interpolation
+  (`"#{name}"`) or escape sequences (`"\n"`, `"\x0"`).
+- Enforced by RuboCop: `Style/StringLiterals` and
+  `Style/StringLiteralsInInterpolation` are both set to `single_quotes`.
+- This covers views too, `.html` and `.html.erb` included, and applies to HTML
+  attributes and CSS values as much as to Ruby: `<th scope='col'>`, not
+  `<th scope="col">`. RuboCop does not lint views, so this half is on us.
+- A Ruby string containing single quotes then *needs* double quotes, which is
+  why assertions on this markup read `"<table class='table table-hover'>"`.
+
+### INTERNATIONALIZATION
+
+#### Eastern time
+
+- `config.time_zone = 'Eastern Time (US & Canada)'`. That is what `Time.zone`
+  means, what a form reads, and what a timestamp renders as.
+- Storage stays UTC. Never touch `config.active_record.default_timezone` — the
+  database keeps UTC and Rails converts on the way in and out, so the app zone
+  is a display concern only.
+- A rule for apps we write. The gem never sets a host's time zone.
+
+#### I18n is deferred
+
+- User-facing strings stay plain English for now. This suspends the baseline's
+  "I18n for user-facing strings" rule until there are enough strings to be worth
+  a locale file — do not add one unprompted.
+
+#### The State model
+
+- A `State` model always represents the United States, and always has exactly
+  these three attributes, each non-null and unique: `code` (two capital
+  letters, `'CA'`), `fips` (two digits, `'06'`), `name` (`'California'`).
+- It always ships with a migration that creates the table *and* backfills it
+  from the official list, so an app never starts with an empty states table.
+  Source of truth: https://www2.census.gov/geo/docs/reference/state.txt
+- 51 rows: the 50 states plus the District of Columbia. Territories are not
+  states, so `PR`, `GU`, `VI`, `AS`, `MP` and `UM` are left out.
+- `fips` is a string, never an integer — `'06'` must keep its leading zero.
+- Enforce all of it in the database too: unique indexes, `null: false`,
+  `limit: 2`, and check constraints for the two-letter and two-digit shapes.
+
+#### The County model
+
+- A `County` has a unique non-null 5-digit `fips` string, a non-null `name`, and
+  belongs to a `state`. `name` is deliberately *not* unique — more than twenty
+  states have a Washington County.
+- Creating a counties table always comes with a migration that backfills all
+  3,143 counties of the 50 states plus DC, each joined to the right `states` row.
+  Source: https://www2.census.gov/geo/docs/reference/codes2020/national_county2020.txt
+- The first two digits of a county's `fips` are its state's `fips`. Check that
+  after backfilling, not just the row count — by hand, since a migration does
+  not get a test.
+- Territories are left out, matching the states table.
+- The 3,143 rows live in `db/counties.txt`, not inside the migration. Migrations
+  are exempt from the file-length rule, so this is a decision rather than a
+  workaround: leave the data in the file and do not inline it.
+- The database enforces it too: unique index on `fips`, `null: false`, a
+  five-digit check constraint, and a real foreign key to `states`.
+
+#### The ZIP model
+
+- A `ZIP` has a unique non-null 5-digit `code`, a non-null `city`, a non-null
+  `time_zone`, belongs to a `county`, and optionally belongs to a `market`.
+- The class is `ZIP`, not `Zip`, because the acronym is registered. Register the
+  plural too — `inflect.acronym 'ZIPs'` — or every heading reads `Zips`.
+- Registering the plural renames more than headings: Rails camelizes a migration
+  filename to find its class, so `create_zips.rb` must define `CreateZIPs`. It
+  only breaks on a migrate from zero, which is why a reset is the real test.
+- Creating a zips table always comes with a migration that backfills it: every
+  ZIP, matched to the county it mostly belongs to and the main city in it.
+- `time_zone` holds a Rails zone name, never an IANA identifier. The source mixes
+  both, so the backfill normalizes on the way in, matching each identifier by its
+  offset and DST rules: Detroit and the Kentucky zones to Eastern, Indiana's
+  Eastern zones to `Indiana (East)`, Knox and Tell_City to Central, Boise to
+  Mountain, Anchorage and Nome to Alaska, Honolulu to Hawaii. Nothing should
+  survive that `ActiveSupport::TimeZone::MAPPING` does not name — worth checking
+  by hand after a backfill, since a migration does not get a test.