kaizo 0.7.0 → 0.9.2

data/README.md

@@ -1,198 +1,229 @@
 # Kaizo
 
+『スーパーマリオワールド　カイゾウ』
+
 A strict, punishing [RuboCop](https://rubocop.org) extension aimed at
-AI-agent-authored Ruby — holding generated code to a demanding design bar by
-bounding how many arguments a method declares, flagging class names that
-describe an action rather than the concept they model, flagging method calls
-nested too deeply in other calls' arguments, and treating comments and loose
-descriptions in specs as prose that should become structure.
+AI-agent-authored Ruby — holding generated code to a demanding design bar.
 
 _Kaizo_ (改造) — "remodeling", "modification": the ruleset keeps applying
-pressure until the code is remade into something better.
-
-A long argument list is a smell: it usually means a method is juggling loose
-primitives that want to be modeled as an object. By putting a ceiling on the
-number of arguments, these cops apply steady pressure toward naming the
-abstraction — an entity, a value object, a parameter object — instead of
-threading five primitives through a signature.
+pressure until the code is remade into something better. A long argument list
+is the canonical target — loose primitives that want to be modeled as an
+object:
 
 ```ruby
-# bad
+# bad — four loose primitives thread through the signature
 def calculate_volume(width, length, height, shape_type)
 end
 
-# good
+# good — the abstraction has a name
 def calculate_volume(shape)
 end
 ```
 
+```console
+$ rubocop --only Kaizo volume.rb
+volume.rb:1:5: C: Kaizo/PositionalArguments: Method has too many positional arguments. [4/1]
+def calculate_volume(width, length, height, shape_type)
+    ^^^^^^^^^^^^^^^^
+volume.rb:1:5: C: Kaizo/TotalArguments: Method has too many arguments. [4/2]
+def calculate_volume(width, length, height, shape_type)
+    ^^^^^^^^^^^^^^^^
+
+1 file inspected, 2 offenses detected
+```
+
+Every example in this README is executed against the shipped configuration by
+the test suite: `# bad` code really is flagged by the named cop, `# good` code
+really passes every cop, every YAML snippet is valid config, and the terminal
+output above is re-derived from the cops themselves. Where a section covers
+several cops, each bad example names the one that fires.
+
 ## Cops
 
-| Cop | Bounds | Counts |
-|-----|--------|--------|
-| `Kaizo/PositionalArguments` | positional params | `arg`, `optarg` |
-| `Kaizo/KeywordArguments` | keyword params | `kwarg`, `kwoptarg` |
-| `Kaizo/TotalArguments` | positional + keyword | all of the above |
-
-Each cop has a `Max` option. All three check `def`, `def self.`,
-`define_method`, and `define_singleton_method`.
-
-The three cops are independent and complementary — enable whichever dimensions
-you want to bound. `TotalArguments` alone is a single global cap; pairing
-`PositionalArguments` with `KeywordArguments` bounds each kind separately (so you
-can, for instance, forbid positional arguments while allowing a couple of keyword
-ones); running `TotalArguments` alongside them also catches methods that stay
-under each per-kind limit but exceed the total. A method that breaks more than
-one bound is reported once per cop it violates — by design — so enable the
-smallest set that expresses your rule.
-
-Beyond argument counts, the gem ships **`Kaizo/AgentNounClassName`**, which
-flags classes named after what they *do* (see [Class naming](#class-naming)),
-**`Kaizo/NestedMethodCalls`**, which flags calls buried too deeply in other
-calls' arguments (see [Nested method calls](#nested-method-calls)),
-**`Kaizo/SpecComment`**, which flags comments in spec files (see
-[Comments in specs](#comments-in-specs)), **`Kaizo/SpecDescriptionProse`**,
-which requires `it`/`context` descriptions to read as one-behavior prose (see
-[Spec description prose](#spec-description-prose)),
-**`Kaizo/FileUtilsInclusion`**, which asks you to `include`/`extend` `FileUtils`
-once its methods are used more than once (see
-[Including FileUtils](#including-fileutils)), **`Kaizo/PreferPathname`**, which
-prefers `Pathname` over `File` for the operations `Pathname` provides (see
-[Prefer Pathname](#prefer-pathname)), **`Kaizo/ExplicitBegin`**, which requires
-an explicit `begin` for method bodies that `rescue` or `ensure` (see
-[Explicit begin](#explicit-begin)), and **`Kaizo/NextInNonVoidEnumerable`**,
-which flags `next` used as control-flow-as-value inside `map`/`select`/`reduce`
-blocks (see [Next in value-returning blocks](#next-in-value-returning-blocks)).
+| Cop | Flags |
+|-----|-------|
+| [`Kaizo/PositionalArguments`](#argument-counts) | more than `Max` positional parameters |
+| [`Kaizo/KeywordArguments`](#argument-counts) | more than `Max` keyword parameters |
+| [`Kaizo/TotalArguments`](#argument-counts) | more than `Max` parameters in total |
+| [`Kaizo/AgentNounClassName`](#class-naming) | classes named for what they do, not what they model |
+| [`Kaizo/NestedMethodCalls`](#nested-method-calls) | calls buried in other calls' arguments |
+| [`Kaizo/SpecComment`](#comments-in-specs) | comments in spec files |
+| [`Kaizo/SpecDescriptionProse`](#spec-description-prose) | descriptions that are lists, conditions, or code |
+| [`Kaizo/SpecSubject`](#spec-subject) | the unit under test hidden in a `let` |
+| [`Kaizo/FileUtilsInclusion`](#including-fileutils) | repeated `FileUtils.` qualification |
+| [`Kaizo/PreferPathname`](#prefer-pathname) | `File` class methods `Pathname` already provides |
+| [`Kaizo/TempfileCreate`](#temp-files) | temp-file APIs with nondeterministic cleanup |
+| [`Kaizo/ExplicitBegin`](#explicit-begin) | `rescue`/`ensure` attached straight to `def` |
+| [`Kaizo/NextInNonVoidEnumerable`](#next-in-value-returning-blocks) | `next` as a value in `map`/`select`/`reduce` |
+| [`Kaizo/PluralCollectionName`](#plural-names-for-collections) | arrays returned under singular names |
+
+**Every cop ships enabled.** `plugins: [kaizo]` turns all fourteen on at
+their strict defaults — there is nothing to opt into and no pending status.
+Outside its own department kaizo touches two core cops: it disables
+`Style/RedundantBegin` ([Explicit begin](#explicit-begin)) and sets
+`Style/HashSyntax` to enforce Ruby 3.1's hash-value shorthand —
+`Session.new(table:)` over `Session.new(table: table)`.
+
+The three argument cops are independent dimensions — enable the smallest set
+that expresses your rule; a method breaking several bounds is reported once
+per cop. None of the cops autocorrect — every fix is a design decision — with
+one exception: `Kaizo/ExplicitBegin`, whose `begin`/`end` wrap is mechanical
+(`rubocop -a`).
 
 ## Installation
 
-Add to your `Gemfile`:
-
 ```ruby
 gem 'kaizo', require: false
 ```
 
-Enable the plugin in `.rubocop.yml`:
-
 ```yaml
 plugins:
   - kaizo
 ```
 
-(Requires RuboCop 1.72.2+ for the `lint_roller` plugin API.)
+Requires RuboCop 1.72.2+ for the `lint_roller` plugin API.
 
-## Configuration
+## Argument counts
 
-The defaults are deliberately strict — **at most one positional and one keyword
-argument** — to apply maximum pressure toward modeling. Loosen them if that is
-too aggressive for your codebase:
+The defaults are deliberately strict — at most one positional and one keyword
+argument. Loosen them, or set a `Max` to `0` to forbid that kind entirely:
 
 ```yaml
 Kaizo/PositionalArguments:
-  Max: 1        # default
+  Max: 1        # default; 0 forces every argument to be a keyword
 Kaizo/KeywordArguments:
   Max: 1        # default
 Kaizo/TotalArguments:
   Max: 2        # default (one positional + one keyword)
 ```
 
-Setting `Max: 0` forbids a kind of argument entirely — for example, banning
-positional arguments so that every parameter must be passed by keyword:
+All three check `def`, `def self.`, `define_method`, and
+`define_singleton_method`. Required and optional parameters count alike:
 
-```yaml
-Kaizo/PositionalArguments:
-  Max: 0        # every argument must be passed by keyword
+```ruby
+# bad — Kaizo/TotalArguments: two positional plus two keyword exceed Max 2
+def route(verb, path, to:, name: nil)
+end
+
+# bad — Kaizo/KeywordArguments: three keyword parameters exceed Max 1
+def connect(host:, port:, scheme:)
+end
+
+# good — Kaizo/KeywordArguments counts none of these: collectors are single
+# tokens, not lists of primitives
+def log(*messages, **context, &formatter)
+end
 ```
 
-### What is counted
+The keyword-counting cops skip `spec/` and `test/` trees entirely: wide
+keyword interfaces are the testing idiom — FactoryBot's `create`/`build`,
+custom builder helpers — and keywords communicate fine at any width there.
+Positional pressure is universal, because positional arguments communicate
+nothing unless they are solo:
 
-Only **named, individual** parameters count toward the limits:
+```ruby
+# good — spec/support/builders.rb: a wide keyword builder is normal test
+# infrastructure, so Kaizo/KeywordArguments and Kaizo/TotalArguments skip it
+def create_order(customer:, items:, coupon: nil, shipping: :standard)
+  Order.create(customer:, items:, coupon:, shipping:)
+end
 
-- Positional: required (`a`) and optional (`a = 1`).
-- Keyword: required (`a:`) and optional (`a: 1`).
+# bad — Kaizo/PositionalArguments: spec/support/builders.rb is not exempt
+# from positional pressure; three anonymous values say nothing
+def build_order(customer, items, coupon)
+  Order.create(customer:, items:, coupon:)
+end
+```
 
-The variadic collectors `*rest`, `**keyword_rest`, `&block`, and `...` are **not**
-counted — they are single tokens, not a list of primitives.
+Police tests like everything else by clearing the exclusion:
 
-### Exemptions
+```yaml
+Kaizo/KeywordArguments:
+  Exclude: []        # count keywords in tests too
+Kaizo/TotalArguments:
+  Exclude: []
+```
 
-The `initialize` of a `Struct.new` or `Data.define` block is exempt, because its
-parameters mirror the value object's attributes — which is exactly the modeling
-these cops are meant to encourage:
+Two shapes are structurally exempt:
 
 ```ruby
-# not flagged
-Data.define(:width, :height, :depth, :weight) do
-  def initialize(width:, height:, depth:, weight:)
+# good — a Struct/Data initialize mirrors the value object's attributes,
+# which is exactly the modeling these cops push toward
+Data.define(:width, :height, :depth) do
+  def initialize(width:, height:, depth:)
     super
   end
 end
+
+# good — operator arity is fixed by Ruby's syntax; there is no object to
+# extract (`[]`, `<=>`, `+`, `<<`, and the rest of the family likewise)
+def []=(row, column, value)
+  @cells[row][column] = value
+end
 ```
 
-There is intentionally **no autocorrection**: the fix is a design decision (what
-object should these arguments become?), and that belongs to a human.
+Beyond the structural exemptions, exempt methods by name or pattern:
 
-## Relationship to `Metrics/ParameterLists`
+```yaml
+Kaizo/KeywordArguments:
+  Max: 1
+  AllowedMethods:
+    - initialize     # constructors may gather collaborators
+Kaizo/PositionalArguments:
+  AllowedPatterns:
+    - '\Abuild_'     # or exempt a whole naming family
+```
 
-Core RuboCop's `Metrics/ParameterLists` enforces a single maximum on the whole
-parameter list. `kaizo` is more granular: it bounds positional and
-keyword arguments separately (and together), and is framed around domain
-modeling rather than method complexity. Use whichever fits; they can coexist.
+### `define_method` edge cases
 
-For the full rationale — why the counting is implemented here rather than reusing
-or configuring `Metrics/ParameterLists`, with reproducible evidence — see
-[docs/why-not-metrics-parameterlists.md](docs/why-not-metrics-parameterlists.md).
+```ruby
+# good — only the block form of define_method is inspected; a callable body
+# may be any object that responds to call, and is not statically countable
+define_method(:resize, ->(width, height) { @size = [width, height] })
+
+# good — numbered and `it` parameters are not a declared signature, so they
+# count as zero; spell parameters out if you want them counted
+define_method(:squared) { _1 * _1 }
+
+# bad — Kaizo/TotalArguments: a name computed at runtime is still checked;
+# the declared parameters matter, not how the name is spelled
+define_method(:"handle_#{event}") { |source, payload, context| dispatch(source) }
+```
 
-## Known limitations
+## Relationship to `Metrics/ParameterLists`
 
-- **The proc/lambda form of `define_method` is not inspected.** Only the block
-  form (`define_method(:foo) { |a, b| }`) is checked. When the body is supplied
-  as a callable — `define_method(:foo, ->(a, b) {})` or
-  `define_method(:foo, captured_method)` — it is left alone, because the argument
-  may be any object that responds to `call` and is not statically countable in
-  the general case.
-- **Numbered and `it` block parameters count as zero.**
-  `define_method(:squared) { _1 * _1 }` is treated as taking no arguments:
-  implicit block parameters are not part of a declared signature, which is what
-  these cops measure. Spell the parameters out if you want them counted.
+Core's `Metrics/ParameterLists` caps the whole parameter list; kaizo bounds
+positional and keyword arguments separately and is framed around domain
+modeling. They can coexist. Full rationale with reproducible evidence:
+[docs/why-not-metrics-parameterlists.md](docs/why-not-metrics-parameterlists.md).
 
 ## Class naming
 
 `Kaizo/AgentNounClassName` flags classes named as agent nouns — "doers" —
-rather than the domain concepts they model. A class whose name ends in `er`/`or`
-(`OrderManager`, `PaymentProcessor`, `RequestHandler`), or in a configured
-forbidden suffix like `Service`, usually means procedural behavior that wants a
-clearer name or a different home.
+rather than the domain concepts they model: names ending in `er`/`or`, or in
+a configured forbidden suffix like `Service`.
 
 ```ruby
-# bad
+# bad — an -er name describes behavior, not a concept
 class PaymentProcessor
 end
 
+# bad — Struct/Data/Class constant assignments are checked too
+RequestHandler = Data.define(:request)
+
 # good
 class Payment
 end
-```
-
-It checks `class` definitions and `Struct.new` / `Data.define` / `Class.new`
-constant assignments. Like the argument-count cops, there is **no autocorrection** — a
-rename is a design decision.
-
-### Tuning the lists
 
-Two suffix lists drive it, both fully configurable and matched against the last
-segment of a namespaced name (`Billing::InvoiceBuilder` is checked as
-`InvoiceBuilder`):
-
-- **`AllowedSuffixes`** — exempt these. Matched as a suffix, so `Controller`
-  clears `Controller` and `UsersController` alike. Ships with a broad default of
-  legitimate `-er`/`-or` words — domain nouns (`Order`, `User`, `Number`,
-  `Error`) and framework terms (`Controller`, `Serializer`, `Adapter`).
-- **`ForbiddenSuffixes`** — always flag these, even when they don't end in
-  `-er`/`-or` (default: `Service`, `Util`, `Utils`). This list **wins** over
-  `AllowedSuffixes`, so it doubles as the way to drop a default exemption.
+# good — ends in an allowed suffix
+class UsersController
+end
+```
 
-Extend either list without restating the default using RuboCop's `inherit_mode`:
+Two configurable suffix lists drive it, matched against the last segment of a
+namespaced name. `AllowedSuffixes` exempts legitimate `-er`/`-or` words and
+ships with a broad default (`Adapter`, `Controller`, `Error`, `User`, ...);
+`ForbiddenSuffixes` always wins, which is how a default exemption is dropped:
 
 ```yaml
 Kaizo/AgentNounClassName:
@@ -201,36 +232,32 @@ Kaizo/AgentNounClassName:
       - AllowedSuffixes
       - ForbiddenSuffixes
   AllowedSuffixes:
-    - Ledger      # OrderLedger now passes
+    - Voucher     # PaymentVoucher now passes
   ForbiddenSuffixes:
     - Server      # ApiServer now flagged, despite the default allowance
 ```
 
 ## Nested method calls
 
-`Kaizo/NestedMethodCalls` flags method calls nested too deeply in **argument**
-positions — `foo(SomeClass.new(another("bar").chain))` — on the principle that the
-intermediate results want names. Reaching for the right name (or extracting a
-method) almost always reads better, and is easier to debug, than peeling
-parentheses apart.
+`Kaizo/NestedMethodCalls` flags calls nested too deeply in **argument**
+positions — intermediate results want names.
 
 ```ruby
 # bad
 wrap(parse(read(io)))
 
-# good - name the intermediate result
-parsed = parse(read(io))
-wrap(parsed)
+# good — the name turns the step into its own documentation
+parsed_config = parse(read(io))
+wrap(parsed_config)
 
-# good - a single nested call is fine
+# good — a single nested call is fine at the default Max
 puts compute(value)
 ```
 
-Depth is bounded by `Max` (default `1` — one nested call is allowed). Only nesting
-through **arguments** is counted; a *receiver chain* such as
-`user.account.owner.name` is a separate concern (a dedicated chaining cop is
-planned). Operator methods (`a + b`, `arr[i]`) never count, block bodies are not
-traversed, and `AllowedMethods` exempts calls to named methods:
+A local called `result` or `tmp` satisfies the cop but not the reader — the
+point is the name. Only argument nesting counts: receiver chains
+(`user.account.owner`) are a separate concern, operator methods never count,
+and block bodies are not traversed.
 
 ```yaml
 Kaizo/NestedMethodCalls:
@@ -239,16 +266,11 @@ Kaizo/NestedMethodCalls:
     - expect        # e.g. don't count RSpec's expect(...) wrapper
 ```
 
-Like the other cops, there is **no autocorrection** — choosing the intermediate
-name is a design decision.
-
 ## Comments in specs
 
-`Kaizo/SpecComment` flags comments in spec files. A comment in a spec is almost
-always a sign that the spec is doing the job of its own description: if you need a
-sentence to explain what an example sets up or asserts, that sentence usually
-wants to be a `context`/`it` description, a clearer example name, or another
-example — not prose riding alongside the code.
+`Kaizo/SpecComment` flags comments in spec files: a sentence explaining an
+example usually wants to be a `context`/`it` description, a clearer example
+name, or another example.
 
 ```ruby
 # bad
@@ -265,17 +287,9 @@ it 'permits an admin to see everything' do
 end
 ```
 
-By default only `*_spec.rb` files are inspected. Magic comments
-(`# frozen_string_literal: true`, `# encoding: …`), RuboCop directives
-(any `# rubocop:` comment), and shebangs are never flagged. Like
-the other cops, there is **no autocorrection** — turning an explanation into a
-spec is a design decision.
-
-### Scope and escape hatches
-
-The cop is scoped through its `Include`, so broaden it to cover support files or a
-Minitest suite (using `inherit_mode: merge` to add to the default rather than
-replace it):
+Only `*_spec.rb` files are inspected; `spec/helpers/` and `spec/support/`
+hold infrastructure, not specs, and are excluded by default. Magic comments,
+`# rubocop:` directives, and shebangs are never flagged.
 
 ```yaml
 Kaizo/SpecComment:
@@ -285,69 +299,94 @@ Kaizo/SpecComment:
   Include:
     - '**/spec/**/*'     # spec_helper, support/, factories
     - '**/*_test.rb'     # Minitest / Test::Unit
-```
-
-Permit specific comments with `AllowedPatterns` — regexps matched against the
-full comment text, leading `#` included:
-
-```yaml
-Kaizo/SpecComment:
+  Exclude: []            # police spec/helpers and spec/support too
   AllowedPatterns:
-    - '\A#\s*@rbs'       # rbs-inline type annotations
-    - 'noqa'
+    - '\A#\s*@rbs'       # permit rbs-inline type annotations
 ```
 
 ## Spec description prose
 
-`Kaizo/SpecDescriptionProse` requires RSpec `it`/`context` descriptions to read
-as one-behavior prose specifications. Every rule is **structural** — it fires
-only when the wording signals that one example is really more than one, or that
-the assertion is leaking into the name.
-
-An `it`/`specify`/`example` description must not contain:
-
-- a **comma** — a list is several behaviors;
-- a **conjunction** (`and`, `or`, `so`, `when`, `if`, `unless`, … — the
-  `Conjunctions` list) — joined clauses are separate examples, and a condition
-  belongs in a `context`;
-- **code** — `_ : # = { } ! [ ]`, a backtick, or a nested quoted literal;
-  a description is prose, not identifiers or wire values.
-
-A `context` description must not contain code, and must open with a word from
-`ContextPrefixes` (`when`/`with`/`without`/`after`). `describe` strings name the
-unit under test and are exempt.
+`Kaizo/SpecDescriptionProse` requires `it`/`context` descriptions to read as
+one-behavior prose. Every rule is structural — it fires only when the wording
+signals that one example is really several, or that the assertion is leaking
+into the name.
 
 ```ruby
 # bad
-it "renders the name, image, and flag"
-it "omits the key when the role is unset"
-it "renders the :cpu member"
-context "the role is unset" do
+it "renders the name, image, and flag"     # a comma joins several behaviors
+it "omits the key when the role is unset"  # a condition belongs in a context
+it "renders the :cpu member"               # code is not prose
+context "the role is unset" do             # contexts open with when/with/without/after
 end
 
 # good
 it "renders the name"
 it "renders the cpu member"
+it "raises Timeout::Error"
 context "when the role is unset" do
   it "omits the key"
 end
 ```
 
-The defaults are deliberately curated, not exhaustive: `for` is dropped from the
-conjunctions (it is a preposition in nearly every description), and homographs
-like `even`/`given`/`regardless` are left out (they collide with `even numbers`
-and the like) — add them via `Conjunctions` if you want them. Pure **wording**
-preferences that don't change structure (e.g. `should` vs a present-tense verb)
-are out of scope — rubocop-rspec's `RSpec/ExampleWording` already covers those.
-There is no autocorrection: splitting an example, or extracting a condition into
-a `context`, is a modelling decision for a human.
+`describe` strings name the unit under test and are exempt. So is an error
+class name (`raises Timeout::Error` above) — the error is what the user
+ultimately sees, so it *is* the specified behavior. The `ForbiddenWords`
+defaults are curated, not exhaustive: `for` is a preposition in most
+descriptions, and homographs like `given` collide with prose, so they are
+left out — add them back if you want them:
+
+```yaml
+Kaizo/SpecDescriptionProse:
+  inherit_mode:
+    merge:
+      - ForbiddenWords
+      - AllowedPatterns
+  ForbiddenWords:
+    - given              # flag `given ...` descriptions too
+  AllowedPatterns:
+    - 'Foo::Widget'      # this one identifier is allowed anywhere
+```
+
+Before 0.9 these lists were named `Conjunctions` and `ContextPrefixes`; the
+old keys are no longer read.
+
+## Spec subject
+
+`Kaizo/SpecSubject` requires the unit under test to be declared with
+`subject`, not hidden in a `let` — `subject` is RSpec's name for the object
+being specified, and declaring it unlocks `is_expected` one-liners.
+
+```ruby
+# bad
+RSpec.describe Session::Pool do
+  let(:pool) { described_class.new }
+end
+
+# good
+RSpec.describe Session::Pool do
+  subject(:pool) { described_class.new }
+end
+```
+
+A `let` is flagged only when its block confidently builds the class under
+test: a `.new` of `described_class`, of the constant an enclosing
+`describe`/`context` names (full or short name), or of a constant matching
+the spec's filename (`pool_spec.rb` names `Pool`). Deliberate second
+instances are the escape hatch's job:
+
+```yaml
+Kaizo/SpecSubject:
+  AllowedMethods:
+    - other          # subject == other comparisons
+  AllowedPatterns:
+    - '\Aother_'
+```
 
 ## Including FileUtils
 
-`Kaizo/FileUtilsInclusion` flags repeated qualified `FileUtils.` calls within a
-class or module: once you reach for `FileUtils` more than once, `include` it (for
-instance-level use) or `extend` it (for class/singleton-level use) and call its
-methods unqualified.
+`Kaizo/FileUtilsInclusion` flags a class or module (reported once) that
+qualifies `FileUtils.` more than once: `include` it for instance-level use,
+`extend` it for class-level use, and call the methods unqualified.
 
 ```ruby
 # bad
@@ -369,17 +408,13 @@ class Backup
 end
 ```
 
-The class or module is reported once. A single qualified call is left alone, a
-namespace that already mixes `FileUtils` in is not flagged, and nested classes
-and modules are counted on their own (one call in an outer class and one in a
-nested class do not add up). As with most of the cops here, there is **no
-autocorrection** — whether to `include` or `extend`, and where the mixin belongs,
-is a design decision.
+A single qualified call is left alone, a namespace already mixing in
+`FileUtils` is not flagged, and nested classes are counted on their own.
+
 ## Prefer Pathname
 
-`Kaizo/PreferPathname` flags calls to `File` class methods that have a `Pathname`
-instance-method equivalent — `File.read`, `File.exist?`, `File.join`,
-`File.expand_path`, and the like. Once a path is a `Pathname`, calling the method
+`Kaizo/PreferPathname` flags `File` class methods with a `Pathname`
+instance-method equivalent — once a path is a `Pathname`, calling the method
 on it reads better than threading a string through `File`.
 
 ```ruby
@@ -394,12 +429,12 @@ path.exist?
 dir.join(name)
 ```
 
-The banned set is the intersection of `File`'s class methods and `Pathname`'s own
-public instance methods (so `File.new`, and `File.path` whose `Pathname#path`
-equivalent is protected, are left alone).
-The cop runs on `**/*.rb` and skips `exe/**/*` and `bin/**/*` by default —
-executables often work with raw path strings — which you can adjust with the
-standard `Include`/`Exclude` options:
+The banned set is the intersection of `File`'s class methods and `Pathname`'s
+public instance methods, so `File.new` is left alone. A few equivalents are
+not drop-in — `Pathname#join` treats an absolute segment as a reset,
+`Pathname#chmod` acts on one receiver where `File.chmod` is variadic — which
+is part of why there is no autocorrection. Executables often work with raw
+path strings, so `exe/**/*` and `bin/**/*` are skipped by default:
 
 ```yaml
 Kaizo/PreferPathname:
@@ -409,25 +444,29 @@ Kaizo/PreferPathname:
     - 'db/**/*'      # add your own
 ```
 
-Because the ban is broad, a few equivalents are not drop-in replacements:
-`Pathname#join` treats an absolute segment as a reset (`Pathname("a").join("/b")`
-is `/b`, where `File.join("a", "/b")` is `a/b`), `Pathname#chmod`/`chown`/`utime`
-act on the single receiver (where `File.chmod` is variadic over many paths), and
-`Pathname#split`/`rename` differ in return type and arity. The cop only points;
-mind those differences when you rewrite — part of why it does not autocorrect.
+## Temp files
 
-As with most of the cops here, there is **no autocorrection** — rewriting
-`File.read(path)` as `Pathname(path).read` changes the receiver and is a call for
-a human.
+`Kaizo/TempfileCreate` requires block-form `Tempfile.create` — the only
+temp-file API whose cleanup is deterministic.
+
+```ruby
+# bad
+file = Tempfile.new("report")     # removed in a GC finalizer, or never
+file = Tempfile.open("report")    # the same finalizer gamble
+file = Tempfile.create("report")  # a bare File that is never auto-removed
+
+# good — closed and removed when the block returns, however it returns
+Tempfile.create("report") do |file|
+  file.write(data)
+end
+```
 
 ## Explicit begin
 
 `Kaizo/ExplicitBegin` requires an explicit `begin`/`end` block when a method
-body attaches a `rescue` or `ensure` directly to the `def` — Ruby's "implicit
-begin". It is the inverse of core's `Style/RedundantBegin`. An explicit `begin`
-names the guarded region and keeps it bounded: it marks exactly what the
-`rescue`/`ensure` covers, so the method can grow other statements without
-silently widening what is rescued.
+body attaches `rescue`/`ensure` directly to the `def`: the `begin` marks
+exactly what is guarded, so the method can grow without silently widening
+what the `rescue` covers.
 
 ```ruby
 # bad
@@ -447,30 +486,30 @@ def foo
 end
 ```
 
-Modifier rescues (`foo rescue nil`) and endless method definitions are not
-flagged. Unlike the other cops, this one **does autocorrect** (`rubocop -a`) —
-wrapping a body in `begin`/`end` is a mechanical fix, not a design decision. The
-correction is skipped when the body does not sit on its own lines between `def`
-and `end` (a single-line definition, say), or contains a heredoc or other
-multiline string, symbol, or regexp literal, where re-indenting could change
-their contents.
+Modifier rescues (`foo rescue nil`) and endless definitions are not flagged.
+This is the one cop that autocorrects (`rubocop -a`); the correction skips
+single-line definitions and bodies holding heredocs or other multiline
+literals, where re-indenting could change their contents.
 
-Because `Style/RedundantBegin` enforces the exact opposite style, loading this
-plugin **disables it** by default — otherwise the two autocorrections would loop
-forever, each undoing the other. Re-enable it explicitly in your `.rubocop.yml`
-if you would rather not require explicit begins:
+Because core's `Style/RedundantBegin` enforces the exact opposite style,
+loading this plugin disables it — otherwise the two autocorrections would
+loop forever. To opt out of explicit begins, disable this cop — re-enabling
+`Style/RedundantBegin` alone would leave both cops on, each flagging the form
+the other mandates:
 
 ```yaml
+Kaizo/ExplicitBegin:
+  Enabled: false    # opt out of explicit begins
 Style/RedundantBegin:
-  Enabled: true     # opt back out of Kaizo/ExplicitBegin
+  Enabled: true     # optional: enforce the inverse style instead
 ```
 
 ## Next in value-returning blocks
 
 `Kaizo/NextInNonVoidEnumerable` flags `next` inside the block of a
-value-returning `Enumerable` method — `map`, `select`, `filter_map`, `reduce`,
-`sum`, `group_by`, the `*_by` methods, the `any?`/`all?`/`none?`/`one?`
-predicates, and so on — where `next` is being used as control-flow-as-value.
+value-returning `Enumerable` method — `map`, `select`, `filter_map`,
+`reduce`, `sum`, the `*_by` methods, the predicates — where `next` is
+control flow being used as a value.
 
 ```ruby
 # bad
@@ -479,40 +518,74 @@ array.map do |item|
   transform(item)
 end
 
-# bad - `next <value>` counts too
+# bad — `next <value>` counts too
 array.reduce(0) do |sum, item|
   next sum if skip?(item)
   sum + item
 end
 
-# good - void iteration method; `next` just skips the iteration
+# good — a void iteration method; `next` just skips the iteration
 array.each do |item|
   next if skip?(item)
   process(item)
 end
 
-# good - say what you mean
+# good — say what you mean
 array.filter_map { |item| transform(item) unless skip?(item) }
 ```
 
-Only *void* iteration methods — those whose block return value is ignored
-(`each`, `each_with_index`, `each_slice`, `each_with_object`, `reverse_each`,
-`cycle`, …) — are meant to use `next`, which is why they are absent from the
-flagged set. Non-`Enumerable` looping constructs (`loop`, `Integer#times`,
-`while`) are likewise never flagged. A `next` that binds to a nested block or
-loop is attributed to that inner scope, so an inner `each { next }` or
-`while … next … end` does not flag an outer `map`.
-
-As with most of the cops here, there is **no autocorrection** — the right fix
-depends on intent (a guard clause might become a ternary, a `select`/`reject`, a
-`filter_map`, or a restructured block). Exempt specific methods with
-`AllowedMethods` / `AllowedPatterns`:
+Void iteration methods (`each`, `each_with_object`, ...) and non-`Enumerable`
+loops (`loop`, `while`, `Integer#times`) are never flagged, and a `next`
+bound to a nested block or loop is attributed to that inner scope.
 
 ```yaml
 Kaizo/NextInNonVoidEnumerable:
   AllowedMethods:
-    - reduce        # allow `next <acc>` guards in reduce/inject
-  AllowedPatterns: []
+    - reduce        # permit `next <acc>` guards in reduce/inject
+```
+
+## Plural names for collections
+
+`Kaizo/PluralCollectionName` flags a method that hands back an array under a
+singular name — `users` tells the caller what they are getting; `user`
+actively misleads them.
+
+```ruby
+# bad
+def user
+  [first_match, second_match]
+end
+
+# good
+def users
+  [first_match, second_match]
+end
+
+# good — not confidently a collection (one branch is not an array), so the
+# cop deliberately errs toward silence
+def user
+  return nil if missing?
+
+  [first_match, second_match]
+end
+```
+
+A method is flagged only when every value it can return is unambiguously an
+array: a literal, or a call to an `ArrayMethods` entry. `select`/`reject` are
+absent from that default on purpose — on a `Hash` they return a `Hash`. A
+name counts as plural when it ends in `s` or appears in `IrregularPlurals`;
+predicates, writers, operators, and `initialize` are exempt.
+
+```yaml
+Kaizo/PluralCollectionName:
+  inherit_mode:
+    merge:
+      - ArrayMethods
+      - IrregularPlurals
+  ArrayMethods:
+    - fetch_all     # your own collection-returning helper
+  IrregularPlurals:
+    - alumni        # plural without a trailing `s`
 ```
 
 ## Development