rubocop-kata 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d84b32b4beb311cd73ed3af609400cc07a4a1e7fb41258e813feab7a7477ae9
-  data.tar.gz: 3038bc491f3197c6623f30f68742fda4008c4519cbacc2c95dc36e0ebc10276c
+  metadata.gz: da7876f7f43029f7dfb90b0fb9527987fe9c50ee40336d0ba4fffdcc2cbad83f
+  data.tar.gz: 902e0c01d3cc5e71553d3c90c68a707b7f3a554cc3e6ec1228f0640ae8772d6a
 SHA512:
-  metadata.gz: b38144839ec596e2f646f89f2c28328978cf030d7bbc9c31deccad49fe94ad9775e75a2af69d51961cfed832f3acc7b49c32c43f0830fc98d300c8033cda1230
-  data.tar.gz: 5ab77b46b9eab5d756368860c1f40866111964217dc0fda9cda532c49574fc6472dc60fb2a091c1e3d54269b63266b956f4bfd9a900ad50528dae96a8a8dd3de
+  metadata.gz: 99fdeb3a9f112fbc7232f59da504bde048071f20d50e55ef367e5516119a307a68a4f071a371cdbbe7810248268ef526f5bbdec08c5e9068e14d17cee03661ca
+  data.tar.gz: 9603d8560c96c877a5cb8f614bf10cab2aabf63aa5aace3209cc0596b06dab7a0edd4372919068a5c345b48cff076c1964b453ba38caa1dd3d026a96ad6c8371

data/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## [0.8.0] - 2026-08-20
+
+- New `rubocop-kata plan` command: buckets the backlog into `structure`,
+  `naming`, `prose` and `rest`, and names the stage to take next. Kata's
+  structural cops create names and its naming cops charge for them, so the net
+  offense count moves the wrong way mid-refactor and cannot be read as progress.
+- New `rubocop-kata skill` command: prints an agent skill to stdout, so
+  redirecting it installs the skill wherever an agent reads them from. It works
+  the stage `plan` names one file at a time, checks every name it introduces
+  against the dictionary `Kata/RealWords` reads, and reports removed and
+  created separately.
+- `Kata/AgentNoun` no longer truncates a compound to its prefix. Truncation is
+  not injective — `EvidencePoller`, `EvidenceValidator` and `EvidenceWaiter`
+  were each told to become `Evidence` — and it lands on names that already
+  exist elsewhere, which a per-file cop cannot see. It now derives the agent
+  word and keeps the rest, so `EvidenceValidator` suggests
+  `EvidenceValidation`, and stays quiet when no derivation applies.
+- `Kata/AgentNoun` `AllowedNames` gains `Controller`, `Mailer` and
+  `Serializer`: suffixes a framework resolves a class by are contracts, not
+  naming choices.
+- `Kata/EnvDiscipline` no longer flags `ENV` as a parameter default.
+  `def enabled?(env = ENV)` is the injection the cop asks for: the parameter
+  is the seam, and the default is what the boot layer would pass anyway.
+- Every cop that excluded `spec/**/*` now excludes `test/**/*` too. Fifteen
+  cops shipped an RSpec-only exclusion, so a Minitest suite got the
+  production rules.
+- The boot layer that `Kata/EnvDiscipline`, `Kata/IoDiscipline` and
+  `Kata/ClockDiscipline` exempt now covers an application's, not only a gem's:
+  `config/`, `db/seeds.rb`, `db/seeds/`, `lib/tasks/`, `Rakefile` and
+  `*.rake`, alongside `bin/` and `exe/`.
+- `Kata/NoComments` now exempts `Gemfile` as it already exempts `*.gemspec`. A
+  dependency manifest cannot say why a dependency is pinned in code.
+- `Metrics/MethodLength` counts an array, hash, heredoc or method call that
+  spans lines as one line. `Max: 5` and `Layout/LineLength: 120` were
+  otherwise unsatisfiable together: wrapping a long line spent method budget.
+- `Layout/ArgumentAlignment` now uses `with_fixed_indentation`. Its default
+  aligns continuation arguments under the first argument's column, a step
+  `Elegant/MonotonicIndents` rejects.
+- `Layout/EmptyLinesAroundAttributeAccessor` is off. It requires a blank line
+  after `attr_reader` where `Elegant/NoEmptyLinesInBlocks` forbids one; inside
+  an `included do` block the two autocorrect in a loop.
+- `Lint/NumberConversion` is off. Its message names a replacement that
+  raises: `Integer(x, 10)` is only valid when `x` is a String, and a `.to_i`
+  receiver is usually a Time, a BigDecimal or an Integer.
+- The five bundled cops that exempt test files now also match Rails'
+  `foo_test.rb`, `foo_spec.rb`, and suites addressed by directory. Upstream
+  matched `**/*Test.rb` and `**/test_*.rb` only.
+- `Elegant/ClassInModule` is off. Its offenses cannot be cleared: it reports a
+  class nested in a class as global, and `Elegant/NoClassInModule` forbids the
+  module its message asks for, so the pair admits no shape. It also reads a
+  top-level constant as a defect, which is how Rails resolves one. Reported
+  upstream as yegor256/rubocop-elegant#75.
+- `Elegant/PairedBrackets` autocorrect is off. It inserts a newline beside a
+  bracket without taking the whitespace already there, so corrected lines drift
+  right and `Elegant/MonotonicIndents` then reports the line it just wrote. The
+  rule still reports; fix the brackets by hand. Reported upstream as
+  yegor256/rubocop-elegant#76.
+- Development runs against giacope/rubocop-elegant#fixes, the released gem plus
+  five open pull requests. A gemspec cannot name a git source, so consumers who
+  want the fixes rather than the workarounds add the same line to their own
+  Gemfile; the README says how.
+
 ## [0.7.0] - 2026-08-16
 
 - New `rubocop-kata doctor` command: reports `.rubocop.yml` entries that

data/README.md

@@ -53,13 +53,58 @@ bundle exec rubocop
 
 That's it. The plugin loads the bundled extensions and the shared defaults, so your `.rubocop.yml` keeps only what's specific to your project. Requires Ruby >= 3.4 and RuboCop ~> 1.75.
 
+### The bundled rubocop-elegant
+
+The released `rubocop-elegant` 0.7.1 has four defects this project reported
+upstream: `NoRedundantVariable` autocorrect corrupts Ruby 3.1 shorthand
+([#74](https://github.com/yegor256/rubocop-elegant/issues/74)), `ClassInModule`
+reports a class nested in a class as global
+([#75](https://github.com/yegor256/rubocop-elegant/issues/75)),
+`PairedBrackets` autocorrect drifts the indent
+([#76](https://github.com/yegor256/rubocop-elegant/issues/76)), and the
+test-file exclusions never match a Rails or RSpec suite
+([#77](https://github.com/yegor256/rubocop-elegant/issues/77)).
+
+The defaults here neutralise all four. `Elegant/ClassInModule` is off, because
+its offences cannot be cleared: the cop it ships beside forbids the module it
+asks for. The two broken correctors are set to report only, because their
+offences can be cleared, by hand. The exclusions are widened. Nothing corrupts
+your code out of the box, and nothing reports a defect you cannot fix.
+
+A gemspec cannot name a git source, so to take the fixes themselves rather than
+the workarounds, add this to your own `Gemfile`:
+
+```ruby
+gem "rubocop-elegant", github: "giacope/rubocop-elegant", branch: "fixes"
+```
+
+That branch is the released gem plus the five pull requests, with the version
+pinned so Bundler resolves it. With it in place you can turn the two correctors
+back on:
+
+```yaml
+Elegant/NoRedundantVariable:
+  AutoCorrect: true
+
+Elegant/PairedBrackets:
+  AutoCorrect: true
+
+Elegant/ClassInModule:
+  Enabled: true
+```
+
+Drop all three once upstream releases the fixes. On a Rails codebase, consider
+leaving `Elegant/ClassInModule` off for good: it wants every class inside a
+module, and Zeitwerk resolves `class Account` from `app/models/account.rb` as a
+top-level constant by design.
+
 ## The cops
 
 | Cop | Default | What it enforces |
 | --- | --- | --- |
 | `Kata/AgentNoun` | on | Classes named for what they are, not `-er`/`-or` doers. Suggests the better name when it can derive one. `AllowedNames` matches a whole name or a trailing segment, so `Error` covers `UsageError`. |
 | `Kata/NoComments` | on | No prose comments; say it in the code. Magic comments, linter directives, and licence headers survive. Autocorrects. |
-| `Kata/IoDiscipline` | on | No bare `puts`/`warn`/`pp`/`p` outside specs/scripts; write through an injected `@io` or an explicit receiver. |
+| `Kata/IoDiscipline` | on | No bare `puts`/`warn`/`pp`/`p` outside the test suite and the boot layer; write through an injected `@io` or an explicit receiver. |
 | `Kata/ProsePlacement` | off | Sentence-length strings belong in the presentation layer. Enable with an `Include`/`Exclude` matching your layering. |
 | `Kata/NoUtilName` | on | No junk-drawer names (`Util`, `Helper`, `Manager`, `Service`, …). Tune via `BannedNames`. |
 | `Kata/RealWords` | on | Every name segment is a word the shipped dictionary knows — `errorcount` (smash) and `cfg` (abbreviation) both fail, with no word list to maintain. Tune via `Terms`/`BannedWords`/`AllowedNames`. |
@@ -71,7 +116,7 @@ That's it. The plugin loads the bundled extensions and the shared defaults, so y
 | `Kata/NoClassMethodLogic` | on | Class methods construct (`build`, `parse`, `of`, `from_*`); instances do the work. |
 | `Kata/NoHashAsObject` | on | A hash with `MaxKeys`+ keys (default 4) wants to be an object. Keyword-argument call sites exempt. |
 | `Kata/ClockDiscipline` | on | No bare `Time.now`/`Date.today`/`.current`; inject a clock. |
-| `Kata/EnvDiscipline` | on | `ENV` reads only in the boot layer (`config/`, `bin/`, `exe/`). |
+| `Kata/EnvDiscipline` | on | `ENV` reads only in the boot layer (`config/`, `db/seeds*`, `lib/tasks/`, rake files, `bin/`, `exe/`) — or as a parameter default, which is the seam the cop asks for. |
 
 ## Dead configuration
 
@@ -92,6 +137,42 @@ lib/registry.rb:44: the directive names `Elegant/GoodMethodName`, which is not e
 
 It exits non-zero when it finds something, so it can gate CI.
 
+## Adoption order
+
+Kata's structural cops create names and its naming cops charge for them, so a
+structural refactor removes offenses and adds more. A single total cannot tell
+progress from regression. `plan` buckets the backlog into the stages that cause
+each other and names the one to take next.
+
+```sh
+bundle exec rubocop-kata plan            # or: plan path/to/project
+```
+
+```
+structure     184  Kata/ConstructorDiscipline 92, Kata/NoHashAsObject 48, Kata/EnvDiscipline 44
+naming        263  Kata/RealWords 141, Kata/GoodVariableName 88, Kata/AgentNoun 34
+prose          57  Kata/NoComments 57
+rest          412  Elegant/PairedBrackets 300, Layout/LineLength 112
+next: structure — 184 offenses in 61 files; these mint the names `naming` then prices, so take them first
+densest: app/models/account.rb (14)
+```
+
+Structure before naming, because doing naming first means renaming things the
+structural pass is about to move.
+
+The gem also ships an agent skill that runs this loop: it works the stage `plan`
+names, checks every name it introduces against the same dictionary
+`Kata/RealWords` reads, and reports removed and created separately instead of a
+net total.
+
+```sh
+mkdir -p .claude/skills/rubocop-kata
+bundle exec rubocop-kata skill > .claude/skills/rubocop-kata/SKILL.md
+```
+
+It writes to stdout, so the same command installs it anywhere an agent reads
+skills from — a project, `~/.claude/skills/`, or a plugin.
+
 ## The defaults
 
 Double-quoted strings, `Metrics/MethodLength: 5`, `Metrics/ClassLength: 100`,

data/config/default.yml

@@ -14,20 +14,28 @@ Kata/AgentNoun:
   Description: >-
     Name classes for the thing they are, not the work they do. `AllowedNames`
     entries match a whole name or a trailing segment of one, so `Error` also
-    exempts `UsageError`.
+    exempts `UsageError`. The default list holds the suffixes a framework
+    resolves a class by, which are contracts rather than naming choices.
   Enabled: true
   VersionAdded: "0.1"
-  VersionChanged: "0.7"
+  VersionChanged: "0.8"
   AllowedNames:
     - Error
+    - Controller
+    - Mailer
+    - Serializer
 
 Kata/NoComments:
   Description: "Say it in the code; keep only comments the machine or the law reads."
   Enabled: true
   VersionAdded: "0.1"
+  VersionChanged: "0.8"
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
     - "*.gemspec"
+    - "Gemfile"
+    - "**/Gemfile"
 
 Kata/GoodMethodName:
   Description: >-
@@ -145,11 +153,18 @@ Kata/IoDiscipline:
   Description: "Write through an injected io, not bare puts/warn/pp/p."
   Enabled: true
   VersionAdded: "0.1"
+  VersionChanged: "0.8"
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
     - "bin/**/*"
     - "exe/**/*"
+    - "config/**/*"
+    - "db/seeds.rb"
+    - "db/seeds/**/*"
+    - "lib/tasks/**/*"
     - "Rakefile"
+    - "**/*.rake"
     - "*.gemspec"
 
 Kata/ProsePlacement:
@@ -221,6 +236,7 @@ Kata/NoBooleanFlag:
   VersionAdded: "0.3"
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
 
 Kata/ConstructorDiscipline:
   Description: "Constructors assign; they do not compute."
@@ -228,6 +244,7 @@ Kata/ConstructorDiscipline:
   VersionAdded: "0.3"
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
 
 Kata/NoClassMethodLogic:
   Description: "Classes construct; instances work."
@@ -235,6 +252,7 @@ Kata/NoClassMethodLogic:
   VersionAdded: "0.3"
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
   AllowedNames:
     - build
     - parse
@@ -247,27 +265,43 @@ Kata/NoHashAsObject:
   MaxKeys: 4
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
     - "config/**/*"
 
 Kata/ClockDiscipline:
   Description: "Read time from an injected clock, not the ambient one."
   Enabled: true
   VersionAdded: "0.3"
+  VersionChanged: "0.8"
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
     - "bin/**/*"
     - "exe/**/*"
+    - "config/**/*"
+    - "db/seeds.rb"
+    - "db/seeds/**/*"
+    - "lib/tasks/**/*"
+    - "Rakefile"
+    - "**/*.rake"
+    - "*.gemspec"
 
 Kata/EnvDiscipline:
   Description: "ENV belongs in the boot layer; pass configuration in."
   Enabled: true
   VersionAdded: "0.3"
+  VersionChanged: "0.8"
   Exclude:
     - "spec/**/*"
-    - "config/**/*"
+    - "test/**/*"
     - "bin/**/*"
     - "exe/**/*"
+    - "config/**/*"
+    - "db/seeds.rb"
+    - "db/seeds/**/*"
+    - "lib/tasks/**/*"
     - "Rakefile"
+    - "**/*.rake"
     - "*.gemspec"
 
 Style/Documentation:
@@ -314,26 +348,42 @@ Layout/LineEndStringConcatenationIndentation:
 Metrics/BlockLength:
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
     - "*.gemspec"
 
 Metrics/ClassLength:
   Max: 100
+  Exclude:
+    - "spec/**/*"
+    - "test/**/*"
+    - "**/*_test.rb"
 
 Metrics/ModuleLength:
   Max: 100
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
+    - "**/*_test.rb"
 
+# A wrapped call reads as one line, so it costs one; otherwise Max and
+# Layout/LineLength cannot both be satisfied.
 Metrics/MethodLength:
   Max: 5
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+    - method_call
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
 
 Metrics/ParameterLists:
   Max: 4
   CountKeywordArgs: true
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
 
 RSpec/ExampleLength:
   CountAsOne:
@@ -345,10 +395,12 @@ RSpec/VerifiedDoubles:
 Elegant/NoEmptyLinesInBlocks:
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
 
 Elegant/NoEmptyLinesInMethods:
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
 
 Elegant/NoComments:
   Enabled: false
@@ -370,6 +422,16 @@ Layout/ClosingParenthesisIndentation:
 Layout/FirstArgumentIndentation:
   Enabled: false
 
+# Its default aligns continuation arguments under the first argument's column,
+# an arbitrary step Elegant/MonotonicIndents rejects; a fixed step is +2.
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+# Requires a blank line after `attr_reader` where Elegant/NoEmptyLinesInBlocks
+# forbids one; inside an `included do` block the two loop.
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: false
+
 Layout/MultilineMethodCallBraceLayout:
   Enabled: false
 
@@ -396,15 +458,21 @@ Style/DisableCopsWithinSourceCodeDirective:
 Elegant/NoRedundantVariable:
   AutoCorrect: false
 
+# Inserts a newline beside a bracket without taking the whitespace already
+# there, so every corrected line drifts right and MonotonicIndents then
+# reports the line it just wrote.
+Elegant/PairedBrackets:
+  AutoCorrect: false
+
 # Rewrites reopened classes into modules, clashing with the primary
 # class definition at boot.
 Style/StaticClass:
   AutoCorrect: false
 
-# Turns lenient `.to_i` into strict Integer(x, 10), which raises on
-# nils/Integers call sites legitimately receive.
+# Its message names a replacement that raises: Integer(x, 10) is only
+# valid when x is a String, and most `.to_i` receivers are not.
 Lint/NumberConversion:
-  AutoCorrect: false
+  Enabled: false
 
 # Alphabetizing requires breaks load-order-dependent boot sequences.
 Style/RequireOrder:
@@ -413,3 +481,39 @@ Style/RequireOrder:
 ThreadSafety/DirChdir:
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
+
+# --- Elegant's test-file exclusions never match Rails' `foo_test.rb`, nor a
+# suite addressed by directory.
+# Off until upstream ships: it reports a class nested in a class as global, and
+# Elegant/NoClassInModule forbids the module the message asks for, so the pair
+# admits no shape. It also reads a top-level constant as a defect, which is how
+# Rails resolves one. https://github.com/yegor256/rubocop-elegant/issues/75
+Elegant/ClassInModule:
+  Enabled: false
+  inherit_mode:
+    merge:
+      - Exclude
+  Exclude:
+    - "**/*_test.rb"
+    - "test/**/*"
+    - "spec/**/*"
+
+Elegant/NoClassInModule:
+  inherit_mode:
+    merge:
+      - Exclude
+  Exclude:
+    - "**/*_test.rb"
+    - "test/**/*"
+    - "spec/**/*"
+
+Elegant/OneClassPerFile:
+  inherit_mode:
+    merge:
+      - Exclude
+  Exclude:
+    - "**/*_test.rb"
+    - "test/**/*"
+    - "spec/**/*"
+

data/exe/rubocop-kata

@@ -3,7 +3,12 @@
 
 require "rubocop-kata"
 require "rubocop/kata/checkup"
+require "rubocop/kata/plan"
+require "rubocop/kata/kit"
 
-abort("usage: rubocop-kata doctor [path]") unless ARGV.first == "doctor"
+COMMANDS = { "doctor" => RuboCop::Kata::Checkup, "plan" => RuboCop::Kata::Plan, "skill" => RuboCop::Kata::Kit }.freeze
 
-exit(RuboCop::Kata::Checkup.new(ARGV.fetch(1, Dir.pwd)).run)
+command = COMMANDS[ARGV.first]
+abort("usage: rubocop-kata #{COMMANDS.keys.join("|")} [path]") if command.nil?
+
+exit(command.new(ARGV.fetch(1, Dir.pwd)).run)

data/lib/rubocop/cop/kata/agent_noun.rb

@@ -26,9 +26,13 @@ class RuboCop::Cop::Kata::AgentNoun < RuboCop::Cop::Base
   end
 
   def suggestion(name)
+    head, tail = split(name)
+    DERIVATIONS.filter_map { proposal(head + tail.sub(it.first, it.last)) }.first
+  end
+
+  def split(name)
     segments = name.scan(SEGMENT)
-    return proposal(segments[0..-2].join) if segments.length > 1
-    DERIVATIONS.filter_map { proposal(name.sub(it.first, it.last)) }.first
+    [segments[0..-2].join, segments.last.to_s]
   end
 
   def proposal(name)

data/lib/rubocop/cop/kata/env_discipline.rb

@@ -6,6 +6,11 @@ class RuboCop::Cop::Kata::EnvDiscipline < RuboCop::Cop::Base
   def on_const(node)
     return unless node.short_name == :ENV
     return unless node.namespace.nil? || node.namespace.cbase_type?
+    return if seam?(node)
     add_offense(node, message: MSG)
   end
+
+  private
+
+  def seam?(node) = node.each_ancestor(:optarg, :kwoptarg).any?
 end

data/lib/rubocop/kata/kit.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class RuboCop::Kata::Kit
+  SOURCE = File.expand_path("../../../skills/rubocop-kata/SKILL.md", __dir__)
+  MISSING = "the gem ships no skill at %s"
+
+  def initialize(_root, io: $stdout)
+    @io = io
+  end
+
+  def run
+    return missing unless File.file?(SOURCE)
+    @io.print(File.read(SOURCE))
+    0
+  end
+
+  private
+
+  def missing
+    @io.puts(format(MISSING, SOURCE))
+    1
+  end
+end

data/lib/rubocop/kata/plan.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "json"
+require "tempfile"
+
+class RuboCop::Kata::Plan
+  STAGES = {
+    "structure" => %w[
+      Kata/ConstructorDiscipline Kata/NoClassMethodLogic Kata/NoHashAsObject
+      Kata/NoBooleanFlag Kata/IoDiscipline Kata/ClockDiscipline Kata/EnvDiscipline
+    ],
+    "naming" => %w[
+      Kata/RealWords Kata/GoodMethodName Kata/GoodVariableName Kata/AgentNoun
+      Kata/BuilderNoun Kata/NoUtilName
+    ],
+    "prose" => %w[Kata/NoComments Kata/ProsePlacement]
+  }.freeze
+  REST = "rest"
+  ROW = "%-10s %6d  %s"
+  NEXT = "next: %s — %d offense%s in %d file%s%s"
+  MINTS = "; these mint the names `naming` then prices, so take them first"
+  DENSE = "densest: %s (%d)"
+  CLEAN = "clean"
+
+  def initialize(root, io: $stdout)
+    @root = root
+    @io = io
+  end
+
+  def run
+    found = offenses
+    return clean if found.empty?
+    STAGES.keys.push(REST).each { row(it, found) }
+    advise(found)
+    1
+  end
+
+  private
+
+  def clean
+    @io.puts(CLEAN)
+    0
+  end
+
+  def row(stage, found)
+    picked = within(found, stage)
+    return if picked.empty?
+    @io.puts(format(ROW, stage, picked.length, breakdown(picked)))
+  end
+
+  def breakdown(picked)
+    picked.group_by { it.fetch("cop") }
+      .sort_by { |_, list| -list.length }
+      .first(3)
+      .map { |cop, list| "#{cop} #{list.length}" }
+      .join(", ")
+  end
+
+  def advise(found)
+    picked = within(found, upcoming(found))
+    @io.puts(headline(upcoming(found), picked))
+    @io.puts(format(DENSE, *hottest(picked)))
+  end
+
+  def upcoming(found) = STAGES.keys.find { |stage| within(found, stage).any? } || REST
+
+  def headline(stage, picked)
+    files = picked.map { it.fetch("path") }.uniq
+    format(NEXT, stage, picked.length, plural(picked), files.length, plural(files), note(stage))
+  end
+
+  def note(stage) = stage == REST ? "" : MINTS
+
+  def hottest(picked) = picked.map { it.fetch("path") }.tally.max_by(&:last)
+
+  def plural(list) = list.one? ? "" : "s"
+
+  def within(found, stage) = found.select { it.fetch("stage") == stage }
+
+  def offenses = report.fetch("files", []).flat_map { rows(it) }
+
+  def rows(file)
+    file.fetch("offenses", []).map do
+      { "path" => file.fetch("path"), "cop" => it.fetch("cop_name"), "stage" => stage(it.fetch("cop_name")) }
+    end
+  end
+
+  def stage(cop) = STAGES.find { |_, cops| cops.include?(cop) }&.first || REST
+
+  def report = @_report ||= JSON.parse(inspection)
+
+  def inspection = Dir.chdir(@root) { sweep }
+
+  def sweep
+    Tempfile.create("rubocop-kata-plan") do |sink|
+      RuboCop::CLI.new.run(["--format", "json", "--out", sink.path, "."])
+      File.read(sink.path)
+    end
+  end
+end

data/lib/rubocop/kata/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module Kata
-    VERSION = "0.7.0"
+    VERSION = "0.8.0"
   end
 end

data/skills/rubocop-kata/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: rubocop-kata
+description: >-
+  Adopt rubocop-kata's rules on an existing codebase without the offense count going
+  the wrong way. Kata's structural cops (ConstructorDiscipline, NoHashAsObject,
+  Io/Clock/EnvDiscipline, NoClassMethodLogic, NoBooleanFlag) create names, and its naming
+  cops (RealWords, GoodMethodName, GoodVariableName, AgentNoun, BuilderNoun, NoUtilName)
+  charge for every name created — so a structural refactor removes offenses and adds more,
+  and a single total cannot tell progress from regression. This skill sequences the work by
+  stage, picks names that are already clean by checking them against the dictionary the cops
+  read, and reports removed and created separately. Use when adopting rubocop-kata, working
+  down a large kata backlog, deciding what to fix next, or when kata offenses went up after a
+  refactor. Triggers on "rubocop-kata", "kata offenses", "kata offences", "kata backlog",
+  "adopt kata".
+---
+
+# rubocop-kata adoption
+
+> The count goes up mid-refactor because the refactor is doing its job. Stop reading the
+> total; read the two numbers underneath it.
+
+## The problem this solves
+
+Move a collaborator out of a constructor and you satisfy `Kata/ConstructorDiscipline`. You
+also mint a parameter, an ivar, and probably a reader — three names, each priced by
+`Kata/RealWords`, `Kata/GoodVariableName`, and `Kata/BuilderNoun`. Net offenses can rise
+while the code strictly improves. There is no configuration that fixes this, because the
+names are real and someone has to choose them.
+
+So choose them well the first time. Every name is checkable *before* it is written, against
+the same dictionary the cops read. Do that and the naming debt is never created.
+
+## Procedure
+
+### 1. Clear dead configuration first
+
+```
+rubocop-kata doctor
+```
+
+It reports `.rubocop.yml` entries for cops the inherited config already disables, and
+`rubocop:disable` comments naming a cop that is not enabled where the comment sits. RuboCop
+reports neither. Delete what it names — it is free, and it stops you tuning knobs that are
+not connected to anything.
+
+### 2. Read the plan
+
+```
+rubocop-kata plan
+```
+
+It buckets every offense into four stages and names the one to work:
+
+- **structure** — the cops that change the shape of the code, and in doing so mint names.
+- **naming** — the cops that price names.
+- **prose** — `NoComments`, `ProsePlacement`.
+- **rest** — bundled and core cops; mostly mechanical, mostly autocorrectable.
+
+Work the stage `plan` names, in that order. Structure before naming is the whole point: doing
+naming first means renaming things the structural pass is about to move or delete.
+
+### 3. Work one file at a time
+
+Take the file `plan` calls densest. Fix its offenses for the **current stage only** — leave
+the other stages' offenses alone even when they are on the line you are editing. Mixing
+stages is what makes a diff unreviewable and a count unreadable.
+
+For `rest`, prefer `rubocop -a` (safe corrections). Do not run `-A` (unsafe) across a
+codebase; kata turns off the correctors known to rewrite code wrongly, but unsafe correctors
+outside that list still change behaviour.
+
+### 4. Check every name before you write it
+
+This is the step that keeps the count honest. Kata's naming rules, condensed:
+
+| rule | cop |
+| --- | --- |
+| one word, lowercase, ≤16 chars | `GoodMethodName`, `GoodVariableName` |
+| a second word only via a role prefix (`after_fork`), a role suffix (`file_of`), or a reviewed `Terms` entry | same |
+| never smash the underscore out — `errorcount` fails too | `RealWords` |
+| every segment is a real word; no `cfg`, `ctx`, `msg`, `tmp`, … | `RealWords` |
+| classes are not `-er`/`-or` doers | `AgentNoun` |
+| no `Util`, `Helper`, `Manager`, `Service`, `Common`, `Shared` | `NoUtilName` |
+| a method that returns something is named for what it returns, not `get_`/`calculate_`/`compute_` | `BuilderNoun` |
+| memoization ivars are `@_name` | `Naming/MemoizedInstanceVariableName` |
+
+Check a candidate against the shipped dictionary before committing to it:
+
+```
+ruby -rrubocop-kata -e 'puts ARGV.map { |w| "#{w}: #{RuboCop::Kata::Dictionary::ENTRIES.include?(w.downcase)}" }' clock sink cursor
+```
+
+If a word the domain genuinely needs is not in the dictionary, that is a `Terms` entry in
+`.rubocop.yml`, not a reason to pick a worse name — but add it deliberately, one at a time,
+and say why in the commit.
+
+When a name is genuinely two words and neither the prefix nor the suffix list fits, that is
+usually the cop telling you an object is missing. `evidence_poller` wants to be
+`Evidence#poll` or an `EvidenceValidation`. Prefer extracting the object over adding a
+`Terms` entry.
+
+### 5. Re-run `plan` and report two numbers
+
+```
+rubocop-kata plan
+```
+
+Report the delta as **removed** and **created**, never as a net total:
+
+> structure 184 → 142 (−42). naming 263 → 263 (+0 created, 21 names introduced, all clean).
+
+A rising `naming` number after a structural pass means step 4 was skipped, not that the
+refactor was wrong. Go back and fix the names you just wrote — it is cheaper now than after
+they spread.
+
+## Rules of engagement
+
+- **Never `rubocop --auto-gen-config` to make a stage disappear.** A todo file converts a
+  backlog you can see into one you cannot. If a cop is genuinely wrong for this codebase,
+  turn it off in `.rubocop.yml` with a comment saying why; `doctor` will tell you later if
+  that entry stops meaning anything.
+- **Never widen `AllowedNames`/`Terms` in bulk.** One entry, one reviewed reason.
+- **One stage per commit.** The reviewer needs to see a structural move as a structural move.
+- **Stop and ask** when a fix requires a decision you cannot verify from the code: what a
+  domain word means, whether a class is part of a public API, whether a framework resolves a
+  class by its name. Guessing on those creates rework that lints clean.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-kata
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Giacomo GK
@@ -112,7 +112,9 @@ description: Bundles a curated RuboCop stack (rspec, performance, elegant, packa
   and adds fifteen cops of its own — naming (GoodMethodName, GoodVariableName, dictionary-backed
   RealWords, AgentNoun, BuilderNoun, NoUtilName), discipline (IoDiscipline, ClockDiscipline,
   EnvDiscipline, ConstructorDiscipline, NoClassMethodLogic), and shape (NoComments,
-  NoBooleanFlag, NoHashAsObject, ProsePlacement).
+  NoBooleanFlag, NoHashAsObject, ProsePlacement). The rubocop-kata command reports
+  dead configuration (doctor), buckets a backlog into the stages that cause each other
+  (plan), and prints an agent skill for working it (skill).
 email:
 - giaco@hey.com
 executables:
@@ -148,8 +150,11 @@ files:
 - lib/rubocop/cop/kata/real_words.rb
 - lib/rubocop/kata/checkup.rb
 - lib/rubocop/kata/dictionary.rb
+- lib/rubocop/kata/kit.rb
+- lib/rubocop/kata/plan.rb
 - lib/rubocop/kata/plugin.rb
 - lib/rubocop/kata/version.rb
+- skills/rubocop-kata/SKILL.md
 homepage: https://github.com/giacope/rubocop-kata
 licenses:
 - MIT