rubocop-legion 0.1.7 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd43ed49ee3f7013316b5650cfb288d60fd6e1807532acb1f8978865a39a519e
-  data.tar.gz: a620ac1fc4debec154a69eb72a75b5df1c0a2fb8f7974e5a29fbefed46604549
+  metadata.gz: 88034e8168ad8e5634a580f3a07ca2f030bd46be31b6c9607dbc64a28935bcd0
+  data.tar.gz: 353647b902a3271fe17809769674778b528eb3e97dda8704934addf80b69b397
 SHA512:
-  metadata.gz: bf447d4891c6c75429b9f0fe92a3f3fc441c11782d6bf97d9b57cc45c1ac77fbbf5314319f9aa2af9681701d4af99a609a8d56cddd63415a01db17bc6ae35ff3
-  data.tar.gz: 239ebbc2294b1ac2b366894ea17d7699a3c3532d672677d34cf8c562497bc2a51367ca6f01984af291d955d310df7fbb95bf257085bb5a37531fa10fb038ae7f
+  metadata.gz: 0b7d05703e9bd6762628d25f082a738fba9972f66eda2b650ab5e3c0dace6b3569df16c754f935f8f62caf861eaf3984018c3a4f3f73de01cc0871fcf91cfebd
+  data.tar.gz: d598e5090c4ba1242ec371fd2d3b935412f9fe8c4e24fe907a9e18bd6052999568bed0c252a983559e4b33e1c0502a724e02df5244db46b98c5cdad899f62e93

data/.rubocop.yml

@@ -9,6 +9,15 @@ Style/Documentation:
 Metrics/MethodLength:
   Max: 20
 
+Metrics/AbcSize:
+  Max: 35
+
+Metrics/CyclomaticComplexity:
+  Max: 20
+
+Metrics/PerceivedComplexity:
+  Max: 20
+
 Naming/FileName:
   Exclude:
     - 'lib/rubocop-legion.rb'

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.1.8] - 2026-06-16
+
+### Added
+- New cop `Legion/Framework/NoUnderscorePrefixedKwargs`: ban `_foo:` keyword arguments and `**_rest` splats; autocorrects to plain names / `**opts`
+- New cop `Legion/Framework/NoInlineSettingDefaults`: flag `Legion::Settings[...] || <literal>` and shadow-default patterns (tunables belong in `settings.rb`)
+- New cop `Legion/Framework/NoDirectDispatch`: ban `*_direct` methods on `Legion::LLM` modules (every pipeline exit must route through the governed pipeline)
+- New cop `Legion/Framework/NoShapeDuckTyping` (disabled by default): flag `respond_to?` on canonical shape methods and string-key fallback access on canonical bodies
+
 ## [0.1.7] - 2026-03-29
 
 ### Added

data/CLAUDE.md

@@ -1,98 +1,52 @@
 # rubocop-legion
 
-**Parent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
-
-## What is This?
-
-Custom RuboCop plugin gem for the LegionIO ecosystem. Provides 47 AST-based cops across 6 departments. Uses the new RuboCop Plugin API (1.72+, lint_roller-based) with auto-discovery via gemspec metadata.
-
-**GitHub**: https://github.com/LegionIO/rubocop-legion
-**RubyGems**: https://rubygems.org/gems/rubocop-legion
-**License**: MIT
+Custom RuboCop plugin gem for the LegionIO ecosystem. Provides 47 AST-based cops across 6 departments. Uses the RuboCop Plugin API (1.72+, lint_roller-based) with auto-discovery via gemspec metadata.
 
 ## Shared Config Profiles
 
-The gem ships shared `.rubocop.yml` profiles so repos don't duplicate config:
-
 - `config/base.yml` — all shared settings (AllCops, Layout, Metrics, Style, Naming, Performance, ThreadSafety)
-- `config/lex.yml` — inherits base, adds plugins (rubocop-legion + performance + thread_safety) + `ParameterLists Max: 8`
-- `config/core.yml` — inherits base, adds plugins (rubocop-legion + performance + thread_safety) + `ParameterLists Max: 10, CountKeywordArgs: false`
-
-### Bundled Plugins
+- `config/lex.yml` — inherits base, adds plugins + `ParameterLists Max: 8`
+- `config/core.yml` — inherits base, adds plugins + `ParameterLists Max: 10, CountKeywordArgs: false`
 
-Both profiles load `rubocop-performance` (52 cops) and `rubocop-thread_safety` (6 cops) as runtime dependencies. ThreadSafety defaults tuned for LegionIO: `NewThread` excludes service/connection files, `ClassInstanceVariable` excludes singletons, `RackMiddlewareInstanceVariable` disabled, `DirChdir` allows block form.
+Both profiles load `rubocop-performance` (52 cops) and `rubocop-thread_safety` (6 cops) as runtime dependencies.
 
 **LEX repos**: `inherit_gem: { rubocop-legion: config/lex.yml }`
 **Core repos**: `inherit_gem: { rubocop-legion: config/core.yml }`
 
-Repo-specific overrides go below the `inherit_gem` directive. Version-locked with the gem — bump gem version = all repos get updated config.
-
-## Cop Scoping
-
-Cops are scoped by gem type — no per-repo configuration needed:
-
-- **Universal** (9 cops): Fire on all LegionIO gems
-- **Library-specific** (6 cops): Fire on all gems but only trigger when using Sequel, Sinatra, Thor, Faraday, or cache
-- **LEX-only** (31 cops): Scoped to `lib/legion/extensions/**/*.rb` via Include directive — never fire on core `legion-*` libraries
-
-## Departments and Cops
-
-### Universal — 10 cops
+## Cop Departments
 
-- **ConstantSafety** (4): `BareDataDefine`, `BareProcess`, `BareJson` (all error, auto-fix) — prefix with `::` inside `module Legion`. `InheritParam` (convention, auto-fix) — pass `false` to `const_defined?`/`const_get`.
-- **RescueLogging** (3): `BareRescue` (warning, auto-fix) — capture with `=> e`. `NoCapture` (convention, no auto-fix) — exception class without capture. `SilentCapture` (warning, no auto-fix) — captured but never logged/re-raised. Skips `_`-prefixed vars. All skip inline rescue modifiers.
-- **Singleton** (1): `UseInstance` (error, auto-fix) — `.instance` not `.new` for configurable singleton classes.
-- **Framework/MutexNestedSync** (1): Nested `synchronize` blocks risk deadlock.
-- **Framework/ModuleFunctionPrivate** (1): `private` after `module_function` resets visibility.
+| Department | Count | Scope |
+|------------|-------|-------|
+| ConstantSafety | 4 | Universal |
+| RescueLogging | 3 | Universal |
+| Singleton | 1 | Universal |
+| Framework | 8 | Universal + Library-specific |
+| HelperMigration | 13 | LEX-only |
+| Extension | 18 | LEX-only |
 
-### Library-Specific — 6 cops
-
-- `EagerSequelModel` — `Sequel::Model(:table)` at require time
-- `SinatraHostAuth` — Sinatra 4.0+ `set :host_authorization`
-- `ThorReservedRun` — Thor 1.5+ reserves `run`
-- `FaradayXmlMiddleware` — Faraday 2.0+ removed `:xml`
-- `CacheTimeCoercion` — Time→String after cache round-trip
-- `ApiStringKeys` — `Legion::JSON.load` returns symbol keys (scoped to `lib/legion/extensions/**/*.rb`)
-
-### LEX-Only — 29 cops
-
-- **HelperMigration** (13): `DirectLogging`, `OldLoggingMethods`, `DirectJson`, `DirectCache`, `DirectLocalCache`, `DirectCrypt`, `DirectData`, `DirectLlm`, `DirectTransport`, `DirectKnowledge`, `RequireDefinedGuard` (all auto-fix) — use per-extension helpers, not global singletons. `LoggingGuard` (no auto-fix) — remove unnecessary `respond_to?(:log_warn)` / `defined?(Legion::Logging)` guards. `DefinedTransportGuard` (no auto-fix) — use `transport_connected?` instead of `defined?(Legion::Transport)`.
-- **Extension** (18): `ActorSingularModule` (auto-fix), `RunnerPluralModule` (auto-fix), `CoreExtendGuard` (auto-fix), `RunnerMustBeModule`, `RunnerIncludeHelpers`, `ActorInheritance`, `EveryActorRequiresTime`, `SelfContainedActorRunnerClass`, `HookMissingRunnerClass`, `AbsorberMissingPattern`, `AbsorberMissingAbsorbMethod`, `DefinitionCallMismatched`, `RunnerReturnHash`, `SettingsKeyMethod` (auto-fix), `SettingsBracketMultiArg` (auto-fix), `LlmAskKwargs`, `ActorEnabledSideEffects`, `DataRequiredWithoutMigrations`.
+Cops are scoped by gem type — no per-repo configuration needed. LEX-only cops fire on `lib/legion/extensions/**/*.rb` via Include directive.
 
 ## Architecture
 
 ```
 rubocop-legion/
 ├── lib/
-│   ├── rubocop-legion.rb              # Entry point, requires all cops
+│   ├── rubocop-legion.rb              # Entry point
 │   └── rubocop/
-│       ├── legion.rb                  # Namespace declarations
 │       ├── legion/
-│       │   ├── version.rb
 │       │   └── plugin.rb             # LintRoller::Plugin (auto-discovery)
 │       └── cop/legion/
 │           ├── helper_migration/      # 13 cops (lex-only)
 │           ├── constant_safety/       # 4 cops (universal)
 │           ├── singleton/             # 1 cop  (universal)
 │           ├── rescue_logging/        # 3 cops (universal)
-│           ├── framework/             # 7 cops (universal + library-specific)
-│           └── extension/             # 17 cops (lex-only)
+│           ├── framework/             # 8 cops (universal + library-specific)
+│           └── extension/             # 18 cops (lex-only)
 ├── config/
 │   └── default.yml                    # All cop defaults, Include/Exclude scoping
 └── spec/                              # mirrors lib/ structure
 ```
 
-## Key Implementation Details
-
-- Plugin entry point: `RuboCop::Legion::Plugin` (LintRoller-based, registered via gemspec metadata `default_lint_roller_plugin`)
-- All cops inherit from `RuboCop::Cop::Base`
-- Auto-correctable cops use `extend AutoCorrector`
-- AST matching via `def_node_matcher` and `def_node_search`
-- Specs use `RuboCop::RSpec::Support` with `:config` shared context and `expect_offense`/`expect_correction`
-- `BareRescue` and `NoCapture` skip rescue modifiers (inline `rescue`) to avoid syntax corruption
-- `NoCapture` has no auto-correct to prevent correction loop with `Lint/UselessAssignment`
-- `SilentCapture` skips `_`-prefixed variables (Ruby unused convention)
-
 ## Development
 
 ```bash
@@ -100,15 +54,3 @@ bundle install
 bundle exec rspec      # 350 specs
 bundle exec rubocop    # Self-linting
 ```
-
-## Common Per-Repo Overrides
-
-```yaml
-# Repos using Faraday JSON middleware (string keys, not Legion::JSON symbol keys)
-Legion/Framework/ApiStringKeys:
-  Enabled: false
-```
-
----
-
-**Maintained By**: Matthew Iverson (@Esity)

data/config/default.yml

@@ -336,3 +336,30 @@ Legion/Extension/DefinitionCallMismatched:
   Enabled: true
   Severity: error
   VersionAdded: '0.1.4'
+
+# Legion/Framework — N×N routing guard cops (Phase 6 enforcement)
+
+Legion/Framework/NoUnderscorePrefixedKwargs:
+  Description: 'Ban underscore-prefixed kwargs and `**_rest` splats. Use plain kwarg, defaulted kwarg, or `**opts`.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1.8'
+
+Legion/Framework/NoInlineSettingDefaults:
+  Description: 'Flag `Legion::Settings[...] || <literal>` and shadow-default patterns. Defaults belong in `settings.rb`.'
+  Enabled: true
+  Severity: warning
+  VersionAdded: '0.1.8'
+
+Legion/Framework/NoDirectDispatch:
+  Description: 'Ban `_direct` methods on `Legion::LLM` modules. All inference routes through the governed pipeline.'
+  Enabled: true
+  Severity: error
+  VersionAdded: '0.1.8'
+
+Legion/Framework/NoShapeDuckTyping:
+  Description: 'Flag `respond_to?` on canonical shape methods and string-key fallback access. Disabled by default.'
+  Enabled: false
+  Severity: convention
+  VersionAdded: '0.1.8'
+  Safe: false

data/lib/rubocop/cop/legion/extension/every_actor_requires_time.rb

@@ -59,7 +59,11 @@ module RuboCop
 
             node.body.each_node(:send).any? do |send_node|
               send_node.method_name == :time && send_node.receiver.nil?
-            end
+            end || defines_time_method?(node)
+          end
+
+          def defines_time_method?(node)
+            node.body.each_node(:def).any? { |def_node| def_node.method_name == :time }
           end
         end
       end

data/lib/rubocop/cop/legion/framework/no_direct_dispatch.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module Framework
+        # Bans defining methods matching `/_direct\z/` on `Legion::LLM` modules.
+        # Per G16, all pipeline bypasses (`chat_direct`, `embed_direct`,
+        # `structured_direct`) are removed — internal callers route through the
+        # governed pipeline with an appropriate profile.
+        #
+        # No auto-correct is provided because the fix requires routing through
+        # the inference pipeline.
+        #
+        # @example
+        #   # bad
+        #   module Legion::LLM
+        #     def chat_direct(message:)
+        #       # bypasses metering, audit, ledger
+        #     end
+        #   end
+        #
+        #   # bad
+        #   module Legion::LLM
+        #     def self.embed_direct(text:)
+        #     end
+        #   end
+        #
+        #   # good
+        #   module Legion::LLM
+        #     def chat(message:)
+        #       # routes through pipeline
+        #     end
+        #   end
+        class NoDirectDispatch < Base
+          MSG = 'Method `%<name>s` matches `/_direct\\z/` on a `Legion::LLM` module. ' \
+                'Pipeline bypasses are not allowed — route through the governed pipeline.'
+
+          DIRECT_PATTERN = /_direct\z/
+
+          def on_def(node)
+            return unless node.method_name.to_s.match?(DIRECT_PATTERN)
+            return unless inside_legion_llm?(node)
+
+            add_offense(node.loc.name, message: format(MSG, name: node.method_name))
+          end
+
+          def on_defs(node)
+            return unless node.method_name.to_s.match?(DIRECT_PATTERN)
+            return unless inside_legion_llm?(node)
+
+            add_offense(node.loc.name, message: format(MSG, name: node.method_name))
+          end
+
+          private
+
+          def inside_legion_llm?(node)
+            node.each_ancestor(:module, :class).any? do |ancestor|
+              legion_llm_module?(ancestor)
+            end
+          end
+
+          def legion_llm_module?(mod_node)
+            return false unless mod_node.module_type?
+
+            # Check compact form: Legion::LLM or Legion::LLM::Something
+            ident = mod_node.identifier
+            return true if compact_legion_llm?(ident)
+
+            # Check nested form: module Legion; module LLM; ...
+            # The identifier is just `LLM` but parent is `module Legion`
+            return true if nested_legion_llm?(mod_node)
+
+            false
+          end
+
+          def compact_legion_llm?(ident)
+            parts = const_parts(ident)
+            parts.length >= 2 && parts[0] == :Legion && parts[1] == :LLM
+          end
+
+          def nested_legion_llm?(mod_node)
+            return false unless mod_node.identifier.const_type?
+            return false unless mod_node.identifier.children.last == :LLM
+
+            # Check if parent module is `Legion`
+            parent = mod_node.parent
+            return false unless parent&.module_type?
+            return false unless parent&.identifier&.const_type?
+
+            parent.identifier.children.last == :Legion
+          end
+
+          def const_parts(node)
+            return [] unless node&.const_type?
+
+            child = node.children.first
+            name = node.children.last
+            if child&.const_type?
+              const_parts(child) + [name]
+            else
+              [name]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/legion/framework/no_inline_setting_defaults.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module Framework
+        # Detects `Legion::Settings[...]` reads combined with inline literal
+        # fallbacks (`|| <literal>`) or shadow-default patterns
+        # (`x = N unless x.positive?`). Per G13, all defaults belong in
+        # `settings.rb` — inline fallbacks are dead code after
+        # `register_defaults!` merge.
+        #
+        # No auto-correct is provided because the fix requires moving the
+        # literal into the appropriate `*_defaults` group in settings.rb.
+        #
+        # @example
+        #   # bad
+        #   max_retries = Legion::Settings[:llm][:max_retries] || 3
+        #   timeout = Legion::Settings[:timeout] || 30
+        #
+        #   # bad (shadow default)
+        #   max_retries = Legion::Settings[:llm][:max_retries]
+        #   max_retries = 200 unless max_retries.positive?
+        #
+        #   # good
+        #   max_retries = Legion::Settings[:llm][:max_retries]
+        class NoInlineSettingDefaults < Base
+          MSG_OR = 'Inline default `%<default>s` after `Legion::Settings` read. ' \
+                   'Move the default into `settings.rb` instead.'
+          MSG_SHADOW = 'Shadow-default pattern after `Legion::Settings` read. ' \
+                       'Move the default into `settings.rb` instead.'
+
+          def on_or(node)
+            left = node.children.first
+            right = node.children.last
+            return unless settings_read?(left)
+            return unless right && literal?(right)
+
+            add_offense(node, message: format(MSG_OR, default: right.source))
+          end
+
+          def on_if(node)
+            cond = node.condition
+            return unless cond&.send_type?
+
+            receiver = cond.receiver
+            return unless receiver&.lvar_type?
+
+            method_name = cond.method_name
+            return unless %i[positive? nil? zero? empty? blank?].include?(method_name)
+
+            var_name = receiver.children.first
+            return unless preceded_by_settings_read?(node, var_name)
+
+            add_offense(node, message: MSG_SHADOW)
+          end
+
+          private
+
+          def settings_read?(node)
+            return false unless node&.send_type?
+            return true if direct_settings_access?(node)
+            return true if nested_settings_access?(node)
+
+            false
+          end
+
+          def direct_settings_access?(node)
+            node.method_name == :[] &&
+              node.receiver&.const_type? &&
+              node.receiver.children.last == :Settings &&
+              legion_const?(node.receiver.children.first)
+          end
+
+          def nested_settings_access?(node)
+            node.method_name == :[] &&
+              node.receiver&.send_type? &&
+              node.receiver.method_name == :[] &&
+              direct_settings_access?(node.receiver)
+          end
+
+          def legion_const?(node)
+            return true if node.nil?
+            return false unless node.const_type?
+
+            node.children.last == :Legion
+          end
+
+          def literal?(node)
+            %i[str int float sym].include?(node.type)
+          end
+
+          def preceded_by_settings_read?(if_node, var_name)
+            parent = if_node.parent
+            return false unless parent&.begin_type?
+
+            idx = parent.children.index(if_node)
+            return false unless idx&.positive?
+
+            prev = parent.children[idx - 1]
+            return false unless prev&.lvasgn_type?
+            return false unless prev.children.first == var_name
+
+            settings_read?(prev.children.last)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/legion/framework/no_shape_duck_typing.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module Framework
+        # Flags `respond_to?` checks for canonical response shape methods
+        # (`thinking`, `tool_calls`, `content`, `stop_reason`) and string-key
+        # fallback access (`x[:k] || x['k']`). Per R10, downstream consumers
+        # of canonical types should rely on the struct interface, not duck-type.
+        #
+        # Ships **disabled by default**. Enable per-repo or per-directory once
+        # the canonical migration is complete.
+        #
+        # @example
+        #   # bad
+        #   response.respond_to?(:thinking)
+        #   response.respond_to?(:tool_calls)
+        #   tc[:name] || tc['name']
+        #
+        #   # good
+        #   response.thinking
+        #   response.tool_calls
+        #   tc[:name]
+        class NoShapeDuckTyping < Base
+          MSG_RESPOND = 'Use canonical struct access instead of `respond_to?(:%<method>s)`. ' \
+                        'Downstream of translators, the shape is guaranteed.'
+          MSG_FALLBACK = 'String-key fallback `%<key>s` suggests duck-typed access. ' \
+                         'Use canonical struct access or symbol keys consistently.'
+
+          CANONICAL_METHODS = %w[thinking tool_calls content stop_reason].freeze
+
+          def on_send(node)
+            check_respond_to(node)
+          end
+
+          def on_or(node)
+            check_string_key_fallback(node)
+          end
+
+          private
+
+          def check_respond_to(node)
+            return unless node.method_name == :respond_to?
+            return unless node.arguments.length == 1
+
+            arg = node.arguments.first
+            method_name = case arg.type
+                          when :sym then arg.value.to_s
+                          when :str then arg.value
+                          else return
+                          end
+
+            return unless CANONICAL_METHODS.include?(method_name)
+
+            add_offense(node, message: format(MSG_RESPOND, method: method_name))
+          end
+
+          def check_string_key_fallback(node)
+            left = node.children.first
+            right = node.children.last
+            return unless left&.send_type? && right&.send_type?
+            return unless left.method_name == :[] && right.method_name == :[]
+
+            # Both must access the same receiver
+            left_recv = left.receiver
+            right_recv = right.receiver
+            return unless left_recv && right_recv
+            return unless same_receiver?(left_recv, right_recv)
+
+            # One must be sym, the other str
+            left_key = left.arguments.first
+            right_key = right.arguments.first
+            return unless left_key && right_key
+
+            has_sym = left_key.sym_type? || right_key.sym_type?
+            has_str = left_key.str_type? || right_key.str_type?
+            return unless has_sym && has_str
+
+            # Extract the key name from the symbol side
+            key_node = left_key.sym_type? ? left_key : right_key
+            return unless key_node
+
+            add_offense(node, message: format(MSG_FALLBACK, key: key_node.value))
+          end
+
+          def same_receiver?(left, right)
+            # Both lvars with same name
+            return true if left.lvar_type? && right.lvar_type? && left.children.first == right.children.first
+
+            # Both sends with same method name and no receiver (bare identifier)
+            left.send_type? && right.send_type? &&
+              left.receiver.nil? && right.receiver.nil? &&
+              left.method_name == right.method_name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/legion/framework/no_underscore_prefixed_kwargs.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module Framework
+        # Bans underscore-prefixed keyword arguments and `**_rest`/`**_` splat
+        # parameters in method definitions. The N×N routing design requires
+        # explicit kwarg signatures: required → plain kwarg, optional → defaulted
+        # kwarg, passthrough → `**opts` at the end.
+        #
+        # @example
+        #   # bad
+        #   def foo(_bar:); end
+        #   def foo(**_rest); end
+        #   def foo(**_); end
+        #
+        #   # good
+        #   def foo(bar:); end
+        #   def foo(bar: nil); end
+        #   def foo(**opts); end
+        class NoUnderscorePrefixedKwargs < Base
+          extend AutoCorrector
+
+          MSG_KWARG = 'Underscore-prefixed kwarg `%<name>s` is not allowed. ' \
+                      'Use plain kwarg (required), defaulted kwarg (optional), ' \
+                      'or `**opts` for passthrough.'
+          MSG_SPLAT = 'Underscore-prefixed kwarg splat `%<name>s` is not allowed. ' \
+                      'Use `**opts` for passthrough.'
+
+          def on_def(node)
+            check_params(node)
+          end
+
+          def on_defs(node)
+            check_params(node)
+          end
+
+          private
+
+          def check_params(method_node)
+            args = method_node.arguments
+            return unless args
+
+            args.each_child_node do |arg|
+              case arg.type
+              when :kwarg, :kwoptarg
+                check_kwarg(arg)
+              when :kwrestarg
+                check_kwrestarg(arg)
+              end
+            end
+          end
+
+          def check_kwarg(arg)
+            name = arg.children.first
+            return unless name.is_a?(Symbol)
+            return unless name.to_s.start_with?('_')
+
+            add_offense(arg, message: format(MSG_KWARG, name: name)) do |corrector|
+              corrected = name.to_s.sub(/\A_+/, '')
+              corrected = 'arg' if corrected.empty?
+              corrector.replace(arg.source_range, kwarg_replacement(corrected, arg))
+            end
+          end
+
+          def check_kwrestarg(arg)
+            name = arg.children.first
+            return unless name.is_a?(Symbol)
+            return unless name.to_s.start_with?('_')
+
+            add_offense(arg, message: format(MSG_SPLAT, name: name)) do |corrector|
+              corrector.replace(arg.source_range, '**opts')
+            end
+          end
+
+          def kwarg_replacement(name, arg)
+            if arg.kwoptarg_type?
+              default = arg.children.last
+              "#{name}: #{default.source}"
+            else
+              "#{name}:"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/legion/llm/no_loop_do.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module Llm
+        # Flags `loop do` in legion-llm production code. Unbounded loops have caused
+        # runaway threads and hard-to-debug hangs. Use `N.times`, `each`, or a
+        # `while` with an explicit counter instead.
+        #
+        # No auto-correct is provided — the fix requires choosing the correct bound.
+        #
+        # @example
+        #   # bad
+        #   loop do
+        #     attempt = dispatch_request
+        #     break if attempt.success?
+        #   end
+        #
+        #   # good
+        #   MAX_ATTEMPTS.times do
+        #     attempt = dispatch_request
+        #     break if attempt.success?
+        #   end
+        class NoLoopDo < Base
+          MSG = '`loop do` is prohibited — use bounded iteration (`N.times`, `each`, ' \
+                'or `while` with an explicit decrement) instead.'
+
+          def on_block(node)
+            return unless node.send_node.method_name == :loop
+            return unless node.send_node.receiver.nil?
+
+            add_offense(node.send_node)
+          end
+
+          alias on_numblock on_block
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/legion/llm/rescue_log_level.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module Llm
+        # Flags `handle_exception(e, level: :debug)` in rescue blocks. Exception
+        # handlers must use at least `:warn` so that errors are visible in
+        # production logs without enabling debug mode.
+        #
+        # @example
+        #   # bad
+        #   rescue StandardError => e
+        #     handle_exception(e, level: :debug, operation: 'foo')
+        #   end
+        #
+        #   # good
+        #   rescue StandardError => e
+        #     handle_exception(e, level: :warn, operation: 'foo')
+        #   end
+        class RescueLogLevel < Base
+          MSG = '`handle_exception` called with `level: :debug` in a rescue. ' \
+                'Minimum log level for exceptions is `:warn`.'
+
+          DEBUG_LEVELS = %i[debug trace verbose].freeze
+
+          def on_send(node)
+            return unless node.method_name == :handle_exception
+            return unless inside_rescue?(node)
+            return unless debug_level?(node)
+
+            add_offense(node)
+          end
+
+          private
+
+          def debug_level?(node)
+            pairs = node.arguments.flat_map do |arg|
+              if arg.hash_type?
+                arg.children
+              elsif arg.pair_type?
+                [arg]
+              else
+                []
+              end
+            end
+            pairs.any? do |pair|
+              key, val = pair.children
+              key.sym_type? && key.value == :level &&
+                val.sym_type? && DEBUG_LEVELS.include?(val.value)
+            end
+          end
+
+          def inside_rescue?(node)
+            node.each_ancestor(:resbody).any?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/legion/llm/settings_access_path.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module Llm
+        # Flags direct write-path access to `Legion::Settings.loader.settings[...][...]`
+        # outside test files. Production code must use `Legion::Settings.dig(...)` so all
+        # reads go through the typed, validated accessor.
+        #
+        # @example
+        #   # bad
+        #   Legion::Settings.loader.settings[:extensions][:llm][:default_model] = 'gemma-12b'
+        #   Legion::Settings.loader.settings[:llm][:timeout]
+        #
+        #   # good
+        #   Legion::Settings.dig(:extensions, :llm, :default_model)
+        class SettingsAccessPath < Base
+          MSG = 'Use `Legion::Settings.dig(...)` instead of ' \
+                '`Legion::Settings.loader.settings[...][...]`.'
+
+          def on_send(node)
+            return unless loader_settings_chain?(node)
+
+            add_offense(node)
+          end
+
+          private
+
+          def loader_settings_chain?(node)
+            return false unless %i[[] []=].include?(node.method_name)
+
+            # For []=, the second index arg and the value are children[1] and [2]
+            # The receiver of the outer []= is the inner [] node
+            receiver = node.receiver
+            return false unless receiver&.send_type? && receiver.method_name == :[]
+
+            # receiver.receiver should be Legion::Settings.loader.settings
+            inner = receiver.receiver
+            return false unless inner&.send_type? && inner.method_name == :settings
+
+            loader_recv = inner.receiver
+            return false unless loader_recv&.send_type? && loader_recv.method_name == :loader
+
+            settings_const?(loader_recv.receiver)
+          end
+
+          def settings_const?(node)
+            return false unless node&.const_type?
+            return false unless node.children.last == :Settings
+
+            parent = node.children.first
+            return true if parent.nil?
+            return false unless parent.const_type? && parent.children.last == :Legion
+
+            parent.children.first.nil?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/legion/llm/taxonomy_enum.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Legion
+      module Llm
+        # Validates lane field literals against the LegionIO taxonomy enums.
+        # Flags `:tier`, `:type`, and `:circuit_state` literals that are not in
+        # the known-valid sets, catching typos at lint time.
+        #
+        # Valid values (from Inventory::DEFAULT_PROVIDER_TIERS and the SSOT design):
+        #   tier:          :local, :fleet, :cloud, :frontier, :direct
+        #   type:          :inference, :embedding, :moderation, :rerank, :image
+        #   circuit_state: :closed, :open, :half_open
+        #
+        # @example
+        #   # bad  (typo)
+        #   { tier: :fronteir }
+        #   health[:circuit_state] = :half_opened
+        #
+        #   # good
+        #   { tier: :frontier }
+        #   health[:circuit_state] = :half_open
+        class TaxonomyEnum < Base
+          VALID_TIERS          = %i[local fleet cloud frontier direct].freeze
+          VALID_TYPES          = %i[inference embedding moderation rerank image].freeze
+          VALID_CIRCUIT_STATES = %i[closed open half_open].freeze
+
+          MSG_TIER    = 'Unknown tier `%<val>s`. Valid: %<valid>s.'
+          MSG_TYPE    = 'Unknown type `%<val>s`. Valid: %<valid>s.'
+          MSG_CIRCUIT = 'Unknown circuit_state `%<val>s`. Valid: %<valid>s.'
+
+          def on_pair(node)
+            key, value = node.children
+            return unless key.sym_type? && value.sym_type?
+
+            check_taxonomy(key.value, value, node)
+          end
+
+          def on_send(node)
+            # health[:circuit_state] = :bad_value
+            return unless node.method_name == :[]=
+            return unless node.arguments.size == 2
+
+            key_node, val_node = node.arguments
+            return unless key_node.sym_type? && val_node.sym_type?
+
+            check_taxonomy(key_node.value, val_node, node)
+          end
+
+          private
+
+          def check_taxonomy(key, val_node, parent_node)
+            val = val_node.value
+            case key
+            when :tier
+              unless VALID_TIERS.include?(val)
+                add_offense(parent_node,
+                            message: format(MSG_TIER, val: val, valid: VALID_TIERS.join(', ')))
+              end
+            when :type
+              unless VALID_TYPES.include?(val)
+                add_offense(parent_node,
+                            message: format(MSG_TYPE, val: val, valid: VALID_TYPES.join(', ')))
+              end
+            when :circuit_state
+              unless VALID_CIRCUIT_STATES.include?(val)
+                msg = format(MSG_CIRCUIT, val: val, valid: VALID_CIRCUIT_STATES.join(', '))
+                add_offense(parent_node, message: msg)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/legion/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module Legion
-    VERSION = '0.1.7'
+    VERSION = '0.1.9'
   end
 end

data/lib/rubocop-legion.rb

@@ -44,6 +44,10 @@ require 'rubocop/cop/legion/framework/module_function_private'
 require 'rubocop/cop/legion/framework/cache_time_coercion'
 require 'rubocop/cop/legion/framework/api_string_keys'
 require 'rubocop/cop/legion/framework/mutex_nested_sync'
+require 'rubocop/cop/legion/framework/no_underscore_prefixed_kwargs'
+require 'rubocop/cop/legion/framework/no_inline_setting_defaults'
+require 'rubocop/cop/legion/framework/no_direct_dispatch'
+require 'rubocop/cop/legion/framework/no_shape_duck_typing'
 
 # Legion/Extension
 require 'rubocop/cop/legion/extension/actor_singular_module'
@@ -64,3 +68,9 @@ require 'rubocop/cop/legion/extension/absorber_missing_pattern'
 require 'rubocop/cop/legion/extension/absorber_missing_absorb_method'
 require 'rubocop/cop/legion/extension/definition_call_mismatched'
 require 'rubocop/cop/legion/extension/actor_enabled_side_effects'
+
+# Legion/Llm
+require 'rubocop/cop/legion/llm/settings_access_path'
+require 'rubocop/cop/legion/llm/no_loop_do'
+require 'rubocop/cop/legion/llm/rescue_log_level'
+require 'rubocop/cop/legion/llm/taxonomy_enum'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-legion
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.9
 platform: ruby
 authors:
 - Esity
@@ -144,6 +144,10 @@ files:
 - lib/rubocop/cop/legion/framework/faraday_xml_middleware.rb
 - lib/rubocop/cop/legion/framework/module_function_private.rb
 - lib/rubocop/cop/legion/framework/mutex_nested_sync.rb
+- lib/rubocop/cop/legion/framework/no_direct_dispatch.rb
+- lib/rubocop/cop/legion/framework/no_inline_setting_defaults.rb
+- lib/rubocop/cop/legion/framework/no_shape_duck_typing.rb
+- lib/rubocop/cop/legion/framework/no_underscore_prefixed_kwargs.rb
 - lib/rubocop/cop/legion/framework/sinatra_host_auth.rb
 - lib/rubocop/cop/legion/framework/thor_reserved_run.rb
 - lib/rubocop/cop/legion/helper_migration/defined_transport_guard.rb
@@ -159,6 +163,10 @@ files:
 - lib/rubocop/cop/legion/helper_migration/logging_guard.rb
 - lib/rubocop/cop/legion/helper_migration/old_logging_methods.rb
 - lib/rubocop/cop/legion/helper_migration/require_defined_guard.rb
+- lib/rubocop/cop/legion/llm/no_loop_do.rb
+- lib/rubocop/cop/legion/llm/rescue_log_level.rb
+- lib/rubocop/cop/legion/llm/settings_access_path.rb
+- lib/rubocop/cop/legion/llm/taxonomy_enum.rb
 - lib/rubocop/cop/legion/rescue_logging/bare_rescue.rb
 - lib/rubocop/cop/legion/rescue_logging/no_capture.rb
 - lib/rubocop/cop/legion/rescue_logging/silent_capture.rb
@@ -191,7 +199,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 3.6.9
 specification_version: 4
 summary: LegionIO code quality cops for RuboCop
 test_files: []