coatepec 0.5.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be24375e5f36c63e0511dc268bacecd57a54a33a94f5d44540925927c49f6655
-  data.tar.gz: 0e80f68351e4e814e9e4486f7e02d8d3f70512edaa7e9806c6baa3091111e779
+  metadata.gz: 9e0e730ee65e046252297e502039ca8db8b17b4d1774564f79cb708dbe4500b2
+  data.tar.gz: 66d1afbd32ef8ba95de436e046d5b8b90452578a5a1ee0af2a442f7a14f0054d
 SHA512:
-  metadata.gz: 297b7eb82d12ece3991893ed1052650648d37fb86b438356257e67e90f69260297b5c3f4b390a2ce25860e2e06a8487dc1597bb39219c3f13ac550901cc92e94
-  data.tar.gz: dbe1f843c872f42c20d7df9ee4226af83200b9c9457bb2a9b3aba185d22b7c5c8878fa3237a57dc4dfb4526c499e4c75cb1cb5c3135262aa24dd71fc4ea8805b
+  metadata.gz: b5168b16140e5199c41a11c4e9a73efee643d2acf80405090a7b1ff0ba32ab94432b1e02b396ca5456ba879960025ef640434fcc265ca19147633e00d0b47a88
+  data.tar.gz: 209b126ecc16dadfacad123098e06bcb9d53649f7f3a8b2eca7555a6d098d35f7307cc81b38b015ea0891b49ef088bbe55c3f33ea2de243e14e0212322e68ded

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.7.0
+
+- Add `rails_controller`: reports an `ActionController` controller's
+  actions, action callbacks, and included concerns. Admits
+  `ActionController::API` controllers as well as `ActionController::Base`
+  ones.
+  - Each action is cross-referenced against `Rails.application.routes`,
+    the same route table `rails_routes` reads: `actions[].routes` lists the
+    verb/path/route name reaching that action (`path` is Rails' raw route
+    spec, `(.:format)` suffix included, byte-identical to `rails_routes`'
+    own `path` for the same route); `unroutable_actions` lists action
+    methods no route reaches (probable dead code); `routes_without_action`
+    lists route action names the controller doesn't define -- a request to
+    one of those raises `AbstractController::ActionNotFound` in production,
+    making this the tool's most actionable output.
+  - `callbacks[]` reports each `before`/`after`/`around` filter's `only`/
+    `except` action restriction (an array, or `nil` if unrestricted -- `nil`
+    and `[]` are distinct and both preserved) and any remaining `if`/
+    `unless` condition (a symbol by name; a Proc reported as `"(block)"`,
+    never serialized directly, since `Proc#to_s` leaks the app's absolute
+    source path).
+  - `concerns` lists app-defined modules only, included directly or
+    inherited from a base class; framework modules are excluded.
+  - **Known limitations, both by design:** strong parameters
+    (`params.require(...).permit(...)`) are not reported -- they exist only
+    as code inside a method body, never as class metadata, and recovering
+    them would require source parsing, which this gem does not do. Only the
+    main app's route table is read, so a controller mounted inside an
+    engine has its actions reported as unroutable even where the engine's
+    own routes reach them -- the same boundary `rails_routes` already has.
+
+## 0.6.0
+
+- Add `rails_spec_flaky_check`: runs a spec selection multiple times with
+  independently random seeds (RSpec's `--seed` is equivalent to `--order
+  rand:SEED`) and reports which examples' pass/fail status was
+  inconsistent across runs -- separately from examples that failed every
+  run (`consistently_failing`, not flaky) and examples that passed every
+  run (omitted). Each round's seed is included in the response so a
+  specific divergence can be reproduced with a plain `rails_spec_run`
+  call. `rails_spec_run` itself is unchanged by this release.
+
 ## 0.5.2
 
 - Fix `WorkerManager` getting permanently stuck treating a dead worker as

data/README.md

@@ -130,6 +130,8 @@ a no-op.
 | `rails_runtime_restart` | `{}` | Unconditionally respawns the worker, discarding its warm boot |
 | `rails_routes` | `query?`, `limit?` (1..200, default 50), `offset?` | Case-insensitive filter across name/verb/path/controller/action |
 | `rails_model` | `name` (constant path, e.g. `Widget` or `Admin::Widget`) | ActiveRecord models only; columns, associations, validators, enums -- no row data |
+| `rails_controller` | `name` (constant path, e.g. `WidgetsController` or `Admin::ReportsController`) | Actions, action callbacks, concerns, and the routes reaching each action -- no request dispatch |
+| `rails_spec_flaky_check` | `paths`, `example?`, `timeout_seconds?` (per round, 1..900), `runs?` (2..20, default 5) | Runs the selection `runs` times with a fresh random seed each round; reports examples whose status was inconsistent across runs |
 
 ### Example queries
 
@@ -156,6 +158,77 @@ a no-op.
   rather than introspecting it (a nonexistent constant raises `model_not_found`
   instead) -- the tool only ever reflects on `ActiveRecord::Base` descendants.
 
+`rails_controller`:
+
+- "What actions does WidgetsController define, and what routes reach them?" --
+  `rails_controller(name: "WidgetsController")` -- see `actions[].routes`,
+  each with `verb`, `path` (Rails' raw route spec, `(.:format)` suffix
+  included -- byte-identical to the same route's `path` from `rails_routes`),
+  and `route_name`.
+- "Does this controller have dead code, or a route that will 500?" -- same
+  call -- see `unroutable_actions` (action methods no route reaches --
+  probably dead code) and `routes_without_action` (action names the route
+  table expects but the controller doesn't define -- a request to that route
+  raises `AbstractController::ActionNotFound` in production; this is the
+  tool's most actionable output).
+- "What before/after/around filters run on this controller's actions, and
+  under what conditions?" -- same call -- see `callbacks[]`: `kind`
+  (`"before"`/`"after"`/`"around"`), `filter` (the method name, or `"(block)"`
+  for a Proc), `only`/`except` (arrays of action names the filter is
+  restricted to/excluded from, or `nil` if unrestricted -- `nil` and `[]` mean
+  different things, so both are preserved: `nil` means no `only:`/`except:`
+  was given at all, while `[]` means one *was* given but names no action this
+  controller actually defines -- e.g. a typo or an action that was since
+  removed -- so `only: []` never runs and `except: []` never skips), and
+  `if`/`unless` (any remaining conditional, by symbol name or `"(block)"`).
+- "What concerns does this controller pull in?" -- same call -- see
+  `concerns`: app-defined modules only, whether included directly or
+  inherited from a base class; framework modules (`ActionController::Base`
+  and everything above it in the ancestor chain) are excluded.
+- `rails_controller` admits `ActionController::API` controllers as well as
+  `ActionController::Base` ones. A malformed constant name raises
+  `invalid_controller_name`; a name that doesn't resolve raises
+  `controller_not_found`; a name that resolves but isn't an
+  `ActionController` descendant (a plain class, a model) raises
+  `not_action_controller`.
+
+`rails_controller` has two deliberate limitations, matching a boundary
+`rails_routes` already has:
+
+- **Strong parameters are not reported.** `params.require(:widget).permit(:name,
+  :size)` exists only as code inside a private method body, never as
+  queryable class metadata -- the only way to recover a permit-list is to
+  parse source, which this gem does not do (see `ROADMAP.md`'s "Considered
+  and set aside" section for why source parsing is out of scope generally).
+- **Only the main app's route table is read.** A controller mounted inside an
+  engine will have its actions reported under `unroutable_actions` even where
+  the engine's own routes reach them -- `rails_routes` has the identical
+  boundary today.
+
+`rails_spec_flaky_check`:
+
+- "Is this spec flaky?" -- `rails_spec_flaky_check(paths: ["spec/models/widget_spec.rb"])`
+  runs it 5 times (default), each with an independently random seed
+  (equivalent to RSpec's `--order rand:SEED`), and reports any example
+  whose pass/fail status wasn't the same every time under `flaky_examples`
+  -- distinct from `consistently_failing` (fails every run: broken, not
+  flaky) and examples that passed every run (omitted -- nothing to report).
+- Each round's seed is included in the response (`rounds[].seed`), so a
+  specific divergence can be reproduced afterward with a plain
+  `rails_spec_run(seed: <that seed>)`.
+- `timeout_seconds` is a **per-round** budget, not a total; `runs *
+  timeout_seconds` is capped at 1800s combined (`flaky_check_budget_exceeded`
+  if exceeded) since this tool can run for a while.
+- Selections over 500 examples are capped per round (the same limit
+  `rails_spec_run` already has), and each round samples a different subset,
+  since execution order varies by design -- for suites this large, narrow
+  `paths`/`example` rather than passing a very broad directory selection.
+- `statuses[]` only aligns positionally with `rounds[]` when no round
+  crashed -- a round whose process itself failed contributes no entry to
+  `statuses[]` (though it still appears in `rounds[]`), so treat positional
+  correspondence as best-effort, not guaranteed, when a round's `status` in
+  `rounds[]` looks like an outright crash rather than a normal pass/fail.
+
 The warm test worker forces Rails' reload-checking on for its own boot,
 regardless of the target app's own `test.rb` setting (which disables it by
 default) -- so editing a model file takes effect on the next tool call
@@ -208,9 +281,10 @@ principle.
 Coatepec takes the opposite approach: there's no eval, console, or SQL
 tool to begin with. `rails_spec_run` only ever executes RSpec files that
 already exist under the app's own allowed spec roots, and `rails_routes`/
-`rails_model` only ever call structured, read-only Rails APIs
-(`Rails.application.routes.routes`, `ActiveRecord` reflection) -- never
-`eval`, `const_get` on unvalidated input, or arbitrary method dispatch. If
+`rails_model`/`rails_controller` only ever call structured, read-only Rails
+APIs (`Rails.application.routes.routes`, `ActiveRecord` reflection,
+`ActionController` callback/action-method metadata) -- never `eval`,
+`const_get` on unvalidated input, or arbitrary method dispatch. If
 you genuinely need a Rails console over MCP, Rails Active MCP is built for
 that; Coatepec is for teams who want an agent to run specs and read
 structure without ever handing it a REPL.

data/ROADMAP.md

@@ -0,0 +1,197 @@
+# Roadmap
+
+Ideas and known future work for Coatepec, roughly in the order they came up.
+Nothing here is committed to a release; this is a place to write things down
+before they're designed, not a promise.
+
+## Minitest support
+
+Every current tool (`rails_spec_run`, `rails_spec_flaky_check`, and the
+paused `rails_spec_profile` below) is built around RSpec: `Coatepec::Spec::Runner`
+shells out to `bundle exec rspec`/forks an RSpec process, and
+`Coatepec::Spec::PathPolicy` validates selectors against RSpec's own
+`*_spec.rb` convention. None of that carries over to a Rails app using
+Minitest instead.
+
+The shape of the fix should mirror what already exists rather than
+invent something new: a parallel `Coatepec::Minitest::Runner` (or
+similarly named) implementing the same "validate selectors, build CLI
+args, run via the platform strategy, return a structured result" contract
+`Spec::Runner` already does, reusing `ForkStrategy`/`SpawnStrategy`/`GuardedForkStrategy`
+as-is where their logic is genuinely test-framework-agnostic (they mostly
+just fork/spawn a command and reap it — the RSpec-specific parts are
+`Runner#build_args` and the `--format json` output parsing in
+`Coatepec::Spec::Result`, both of which would need Minitest equivalents:
+Minitest's own JSON/machine-readable reporter, or `minitest-reporters`
+gem output, would need to be identified before designing that half).
+
+**Framework auto-detection via the Gemfile is straightforward and doesn't
+need new machinery** — `Coatepec::Worker::RailsRuntime#loaded_gem_names`
+already exists and is exactly the mechanism `GuardedForkStrategy` uses
+today to check for fork-unsafe gems, and `Coatepec::Spec::FactoryProfRunner`
+(see below) uses to check for `test-prof`. The same `loaded_gem_names.include?("rspec-rails")`
+vs. `.include?("minitest")` check (a Rails app's default `Gemfile` already
+declares one or the other, sometimes both) is enough to route
+`rails_spec_run` (or a to-be-decided `rails_test_run`, if the two
+frameworks' capabilities diverge enough to warrant separate tool names
+rather than one dispatching tool) to the right runner. `Coatepec::Spec::Runner#require_rspec!`
+already anticipates the gap in spirit: it raises `:unsupported_test_framework`
+today when `rspec-rails` isn't loadable, rather than assuming RSpec
+unconditionally.
+
+Open questions for whenever this gets designed properly:
+- One tool name that dispatches by detected framework, or separate
+  `rails_spec_run`/`rails_minitest_run`-style tools? (Affects whether an
+  agent needs to know which framework a given app uses before calling the
+  right tool, vs. the tool figuring it out.)
+- What Minitest gives you for structured per-example output
+  (pass/fail/pending, id, file/line) equivalent to RSpec's `--format json`
+  — needed before `rails_spec_flaky_check`'s per-example flaky-detection
+  logic (`Coatepec::Spec::FlakyChecker`, framework-agnostic in principle
+  since it only depends on `Runner#run`'s result shape) could target
+  Minitest too.
+- Whether Minitest's own `--seed` (it has one; Minitest randomizes test
+  order by default too) is enough of an equivalent to RSpec's `--seed`
+  for `rails_spec_flaky_check` to reuse the same "rerun N times with a
+  fresh random seed" mechanism unchanged.
+
+## Get stats on a spec/test run (TestProf / FactoryProf) — designed, implemented, paused
+
+The general idea: a tool that runs a spec selection and comes back with
+more than pass/fail — profiling data about the run itself (factory
+creation counts/timing being the concrete first target, via
+[TestProf](https://test-prof.evilmartians.io/)'s FactoryProf profiler,
+which is the one TestProf profiler with real structured JSON output;
+others like EventProf are text-only and out of scope for now).
+
+A `rails_spec_profile` tool (runs a spec with TestProf's FactoryProf
+enabled, returning factory usage stats alongside normal pass/fail data)
+was fully designed and implemented, but paused before merging: TestProf's
+`FPROF` env var only activates at Ruby's `require` time, not at RSpec-run
+time as originally assumed, which makes it silently a no-op on
+`ForkStrategy` (Linux's default) — confirmed empirically, not just
+inferred. See `docs/superpowers/specs/2026-08-13-factory-prof-tool-design.md`
+(local-only, not committed — see that repo's `.gitignore`) for the full
+root-cause writeup and the fix options considered (forcing `SpawnStrategy`
+for profiled runs specifically, vs. detecting and raising a clear error on
+non-spawn strategies, vs. a Linux-only opt-out config knob). Paused
+specifically to wait for real signal on how coatepec is actually used
+(Linux vs. macOS, `macos_fork` adoption) before picking a fix, rather than
+guessing.
+
+## Run Rails 8.1's built-in CI (`bin/ci`)
+
+Rails 8.1 introduced `ActiveSupport::ContinuousIntegration`
+(`activesupport/lib/active_support/continuous_integration.rb`) as the
+engine behind a generated `bin/ci`/`config/ci.rb`: a small DSL (`step`,
+`group`) that a new app's `config/ci.rb` uses to declare, by default,
+`bin/setup`, `bin/rubocop`, `bin/bundler-audit`, `bin/importmap audit`
+(if using importmap), `bin/brakeman --quiet --no-pager --exit-on-warn
+--exit-on-error`, and the test suite -- the same steps the generated
+GitHub Actions workflow runs, since that workflow just calls `bin/ci`.
+A coatepec tool that ran this and reported back which steps
+passed/failed would cover security audits (Brakeman, bundler-audit,
+importmap audit) and style checks in one call, for any app that has
+adopted this (Rails 8.1+ only -- confirmed against the actual generator
+template and `ContinuousIntegration` source, not a blog summary).
+
+**The real design obstacle, found while researching this (not yet
+solved):** `ContinuousIntegration` has no structured output at all. Each
+`step` runs via plain `system(*command)` and writes colorized terminal
+text (`✅ Title passed in 1.2s` / `❌ Title failed in 1.2s`); the only
+machine-readable signal is the overall process exit code
+(`abort unless success?`). Two options for whenever this gets designed:
+scrape that text (fragile -- it's an internal, unversioned Rails string
+format, not a documented API), or require the target app's `config/ci.rb`
+in-process and read `ContinuousIntegration#results` (an array of
+`[success, title]` pairs) directly, intercepting the `abort` that
+normally follows a failure -- more work, but reads real data instead of
+parsing text designed for a terminal.
+
+Also worth deciding: whether this becomes its own tool (`rails_ci_run`?)
+or folds into an existing one, and whether "security audits" specifically
+(Brakeman/bundler-audit/importmap audit, independent of the rest of
+`bin/ci`) are worth exposing as a narrower, separate tool for apps that
+don't use Rails 8.1's `bin/ci` scaffold at all but do have those gems.
+
+## Controller introspection
+
+A `rails_controller`-style tool mirroring the existing `rails_model`
+(`Coatepec::Introspection::Model`) and `rails_routes`
+(`Coatepec::Introspection::Routes`) tools' shape: given a controller
+constant, return its actions, `before_action`/`around_action`/`after_action`
+filters (and which actions they apply to), strong-parameter method
+definitions, and included concerns -- via real Rails introspection APIs
+(`ActionController::Base` callback chains, not source parsing), the same
+trust boundary `rails_model` already holds to.
+
+## Background job introspection -- built, then parked (PR #14, closed unmerged)
+
+The original idea: a `rails_job`-style tool for `ActiveJob` classes --
+queue name, retry/discard configuration, and callbacks -- following the
+same bounded, read-only, real-API-not-source-parsing pattern as
+`rails_model`, since coatepec has no visibility into background jobs at
+all today.
+
+It was fully built and reviewed as `rails_job`
+(`Coatepec::Introspection::Job`), then **closed unmerged** in
+[PR #14](https://github.com/mogox/coatepec/pull/14) -- the diff and its
+review history stay there, so nothing needs re-deriving if this is picked
+back up.
+
+**Why it was parked:** the tool only sees `ActiveJob::Base` subclasses.
+That's not an implementation shortcut -- it's the trust boundary doing its
+job: the whole design reads real Rails introspection APIs
+(`_perform_callbacks`, `rescue_handlers`, the `queue_name`/`priority` class
+attributes) rather than parsing source, and those APIs exist only on
+ActiveJob. An app whose jobs are native Sidekiq (`include Sidekiq::Job`)
+or Delayed::Job classes gets `:not_active_job` and nothing else, because
+those classes genuinely aren't ActiveJob jobs. (Sidekiq used *as the
+ActiveJob queue adapter* is fine -- those jobs still subclass
+`ApplicationJob`; it's hand-written Sidekiq/delayed_job worker classes
+that fall outside.) Covering them would mean a second, adapter-specific
+introspection path per backend -- `sidekiq_options` for retry/queue/dead,
+`Delayed::Worker` config and `handle_asynchronously` for delayed_job --
+which is a materially bigger design than the ActiveJob one, not a small
+extension of it. Given a limited number of iterations to spend, that
+budget goes to features usable across more real apps first.
+
+Two constraints worth keeping if this is revisited:
+- Even within ActiveJob, `retry_on` / `discard_on` / plain `rescue_from`
+  are indistinguishable, and neither macro's `wait:`/`attempts:`/`queue:`/
+  `priority:` options are introspectable -- ActiveJob closes over them
+  inside a Proc rather than storing them as class metadata. Only the
+  *list* of rescued exception classes is genuinely queryable.
+- `queue_as { ... }` and `queue_with_priority { ... }` store unevaluated
+  app blocks. Reading them naively either executes app code at
+  introspection time or leaks the app's absolute source paths through
+  `Proc#to_s`. PR #14 has the fix for both; any future version needs the
+  same care.
+
+## Cross-file consistency validation
+
+Distinct from anything coatepec does today: a tool that checks for drift
+*across* files rather than introspecting one thing at a time -- a route
+pointing at a controller action that doesn't exist, a `belongs_to`/`has_many`
+referencing a column or table that isn't in the schema, that kind of thing.
+Surfaced while researching prior art (a competing tool does this via
+source-code parsing); would need its own design for how to do it via
+structured Rails APIs instead, consistent with how every other coatepec
+tool avoids parsing source directly.
+
+## Considered and set aside
+
+- **Environment variable / credentials discovery** (a prior-art tool
+  exposes this). Cuts directly against coatepec's "no credential access"
+  security boundary -- not a fit regardless of usefulness.
+- **AST-based code pattern analysis** (concerns, callbacks, service
+  objects, helper methods, by parsing source rather than calling real
+  Rails APIs). A meaningfully different, heavier, more fragile approach
+  than every existing coatepec tool takes. Not ruled out forever, but a
+  clear departure from the project's current trust model, not a natural
+  extension of it.
+- **Rails dev server lifecycle management** (start/stop/monitor `rails s`
+  via MCP -- a different tool in the ecosystem does exactly this). A
+  different category of feature (process lifecycle, not test/introspection)
+  from everything else on this list; noted here for completeness, not
+  actively being considered.

data/lib/coatepec/introspection/controller.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Introspection
+    # Returns bounded ActionController class metadata for a single controller,
+    # for the rails_controller MCP tool. Pure reflection over an already-loaded,
+    # already-gated class -- no request dispatch, no action execution, and no
+    # evaluation of app-authored callback conditions.
+    # rubocop:disable Metrics/ClassLength -- Task 3 (route cross-referencing)
+    # adds genuinely cohesive functionality: routes_by_action, grouped_routes,
+    # route_data, and rails_routes exist solely to serve this class's single
+    # responsibility (reflect on one controller). Splitting them into a
+    # separate collaborator class would fragment that one responsibility
+    # across files for no readability gain, only to satisfy a line count.
+    class Controller
+      NAME_PATTERN = /\A[A-Z]\w*(?:::[A-Z]\w*)*\z/
+      MAX_ITEMS = 200
+
+      # AbstractController::Callbacks::ActionFilter#match? reads exactly two
+      # things off the controller it is handed: `action_name`, and (Rails 7.1+)
+      # `raise_on_missing_callback_actions`. That second one must be false --
+      # when true, match? raises ActionNotFound for any action named in `only:`
+      # that the controller doesn't define, which is precisely the drift this
+      # tool exists to *report*, so it must never raise here. This Struct is
+      # the entire controller surface match? touches; nothing on it can
+      # execute application code.
+      CallbackProbe = Struct.new(:action_name, :raise_on_missing_callback_actions)
+
+      def initialize(name)
+        @name = name
+      end
+
+      def call
+        validate_name!
+        klass = resolve!
+        validate_action_controller!(klass)
+        build_metadata(klass)
+      end
+
+      private
+
+      def build_metadata(klass)
+        actions = action_names(klass)
+        routes = routes_by_action(klass)
+        {
+          name: klass.name, controller_path: klass.controller_path,
+          actions: actions.map { |action| { name: action, routes: routes.fetch(action, []) } },
+          unroutable_actions: actions.reject { |action| routes.key?(action) },
+          routes_without_action: routes_without_action(klass, routes),
+          callbacks: callbacks_for(klass, actions), concerns: concerns_for(klass)
+        }
+      end
+
+      def validate_name!
+        return if @name.is_a?(String) && NAME_PATTERN.match?(@name)
+
+        raise Coatepec::Error.new(:invalid_controller_name, "#{@name.inspect} is not a valid constant name")
+      end
+
+      def resolve!
+        ::ActiveSupport::Inflector.safe_constantize(@name) ||
+          raise(Coatepec::Error.new(:controller_not_found, "#{@name} could not be resolved"))
+      end
+
+      # Gate on Metal, not Base: an ActionController::API controller is not a
+      # Base descendant, so gating on Base would reject every API-only app.
+      def validate_action_controller!(klass)
+        unless defined?(::ActionController::Metal)
+          raise Coatepec::Error.new(:not_action_controller, "ActionController is not loaded in this app")
+        end
+        return if klass.is_a?(Class) && klass < ::ActionController::Metal
+
+        raise Coatepec::Error.new(:not_action_controller, "#{@name} is not an ActionController controller")
+      end
+
+      # action_methods is a Set of Strings. Sorted for stable output across
+      # runs. A public method contributed by a concern legitimately appears
+      # here -- Rails really would route to it, so surfacing it is the point,
+      # not a leak to filter out.
+      def action_names(klass)
+        klass.action_methods.to_a.map(&:to_s).sort.first(MAX_ITEMS)
+      end
+
+      # Slice the ancestor chain at the first ActionController::* class in it:
+      # ActionController::Base for a normal controller, ActionController::API
+      # for an API-only one. Everything before that point was inserted by the
+      # app, so this needs no denylist of the ~60 framework modules below it.
+      # Anonymous modules have a nil name and are dropped.
+      def concerns_for(klass)
+        base = framework_base(klass)
+        klass.ancestors
+             .take_while { |mod| mod != base }
+             .reject { |mod| mod.is_a?(Class) }
+             .filter_map(&:name)
+             .first(MAX_ITEMS)
+      end
+
+      def framework_base(klass)
+        klass.ancestors.find do |mod|
+          mod.is_a?(Class) && mod.name.to_s.start_with?("ActionController::")
+        end
+      end
+
+      # controller_path is the public, correctly-namespaced key Rails itself
+      # stores in a route's defaults (Admin::ReportsController =>
+      # "admin/reports"), so matching on it needs no name munging.
+      #
+      # Only Rails.application.routes is read, so a controller mounted inside
+      # an engine will report its actions as unroutable even though the
+      # engine's own route set reaches them. Introspection::Routes has exactly
+      # the same boundary today; it is documented in the README rather than
+      # silently absorbed.
+      # A route whose defaults[:action] is nil or empty (a mount or redirect)
+      # is skipped, not recorded under an empty-string action.
+      def routes_by_action(klass)
+        grouped_routes(klass).transform_values { |list| list.first(MAX_ITEMS).map { |route| route_data(route) } }
+      end
+
+      def grouped_routes(klass)
+        path = klass.controller_path
+        matching = self.class.rails_routes.select { |route| route.defaults[:controller].to_s == path }
+        matching.group_by { |route| route.defaults[:action].to_s }.reject { |action, _| action.empty? }
+      end
+
+      # Differenced against the controller's full action_methods set, not the
+      # (possibly truncated-to-MAX_ITEMS) displayed `actions` list -- a
+      # controller with more than MAX_ITEMS action methods would otherwise
+      # have every route whose action fell past the truncation point reported
+      # here as a false positive, in the field the README calls the tool's
+      # most actionable output. Bounded to MAX_ITEMS like every other
+      # collection in this payload; `grouped_routes` itself caps each route
+      # *list* but not its key count, so this is where that cap belongs.
+      def routes_without_action(klass, routes)
+        defined_actions = klass.action_methods.map(&:to_s)
+        (routes.keys - defined_actions).sort.first(MAX_ITEMS)
+      end
+
+      # path keeps Rails' raw spec, `(.:format)` suffix included, so a path
+      # string here is byte-identical to the same route as reported by
+      # rails_routes. Stripping it would make the two tools disagree about the
+      # same route.
+      def route_data(route)
+        { verb: route.verb.to_s, path: route.path.spec.to_s, route_name: route.name&.to_s }
+      end
+
+      # Isolated as a class method purely so unit tests can stub it without
+      # booting Rails -- Rails.application.routes.routes is otherwise only
+      # reachable with a real, booted application. Mirrors
+      # Introspection::Routes.rails_routes.
+      # rubocop:disable Lint/IneffectiveAccessModifier
+      def self.rails_routes
+        Rails.application.routes.routes
+      end
+      # rubocop:enable Lint/IneffectiveAccessModifier
+
+      # Gated on Metal, not Base/API, so a bare ActionController::Metal
+      # subclass -- which passes validate_action_controller!'s class gate but
+      # does not include AbstractController::Callbacks, unlike Base and API --
+      # gets an empty callback list instead of a NoMethodError.
+      def callbacks_for(klass, actions)
+        return [] unless klass.respond_to?(:_process_action_callbacks)
+
+        klass._process_action_callbacks.first(MAX_ITEMS).map do |callback|
+          conditions_for(callback, actions)
+            .merge(kind: callback.kind.to_s, filter: filter_description(callback.filter))
+        end
+      end
+
+      # only:/except: do not survive as readable options. Rails compiles both
+      # into an ActionFilter and distinguishes them purely by *placement*: the
+      # `only:` filter lands in the callback's @if chain, the `except:` one in
+      # its @unless chain. Intent is therefore recovered from which chain the
+      # object sits in, not from the object itself.
+      #
+      # Reaching those chains needs instance_variable_get: Callback exposes
+      # `kind` and `filter` publicly but has no reader for @if/@unless. That
+      # single private read is unavoidable; having taken it, the action set is
+      # then read through ActionFilter's *public* match? rather than a second
+      # private read of its @actions, so this keeps working if Rails changes
+      # how ActionFilter stores them.
+      def conditions_for(callback, actions)
+        ifs = Array(callback.instance_variable_get(:@if))
+        unlesses = Array(callback.instance_variable_get(:@unless))
+        {
+          only: matched_actions(ifs, actions, :all?),
+          except: matched_actions(unlesses, actions, :any?),
+          if: plain_conditions(ifs),
+          unless: plain_conditions(unlesses)
+        }
+      end
+
+      # nil (not []) when there is no ActionFilter at all: "this callback is
+      # unrestricted" and "this callback is restricted to no actions" are
+      # different facts and must not serialize identically.
+      #
+      # A chain routinely carries *more than one* ActionFilter: skip_callback
+      # (ActiveSupport::Callbacks::Callback#merge_conditional_options)
+      # concatenates a skip's normalized only:/except: onto the callback's
+      # existing @if/@unless chain rather than replacing it, so any
+      # `skip_before_action ..., only:`/`except:` leaves two ActionFilters
+      # behind. A callback only runs when *every* @if condition holds and
+      # *none* of its @unless conditions hold (ActiveSupport::Callbacks'
+      # run_callbacks ANDs @if and ANDs the negation of each @unless), so:
+      # only: is every @if ActionFilter's matches intersected (combinator
+      # :all? -- all must hold for the action to run the callback), and
+      # except: is every @unless ActionFilter's matches unioned (combinator
+      # :any? -- any one holding is enough to skip it). Keeping only the
+      # first ActionFilter in the chain (as a naive `find` would) silently
+      # drops every skip layered on top of it, which always biases toward
+      # over-reporting protection -- exactly backwards for a tool whose job is
+      # to answer "is this action protected?".
+      def matched_actions(conditions, actions, combinator)
+        filters = conditions.select { |condition| action_filter?(condition) }
+        return nil if filters.empty?
+
+        actions.select do |action|
+          filters.public_send(combinator) { |filter| filter.match?(CallbackProbe.new(action, false)) }
+        end
+      end
+
+      def action_filter?(condition)
+        defined?(::AbstractController::Callbacks::ActionFilter) &&
+          condition.is_a?(::AbstractController::Callbacks::ActionFilter)
+      end
+
+      # The conditions that are *not* only:/except: -- a real `if:`/`unless:`.
+      # A Symbol is a method reference and safe to name; a Proc must never be
+      # serialized (Proc#to_s leaks the app's absolute source path).
+      def plain_conditions(conditions)
+        conditions.reject { |condition| action_filter?(condition) }
+                  .map { |condition| filter_description(condition) }
+      end
+
+      # A Symbol filter (the method-reference form, e.g.
+      # `before_action :require_login`) is a method reference and safe to
+      # report by name; a Proc must never be serialized, because Proc#to_s
+      # leaks the app's absolute source path, so it is reduced to "(block)"
+      # instead. Introspection::SafeOptions guards the same class of leak
+      # elsewhere, by silently dropping Procs from an options hash rather than
+      # substituting a placeholder -- a different mechanism for the same rule.
+      def filter_description(filter)
+        case filter
+        when Symbol then filter.to_s
+        when Proc then "(block)"
+        else filter.class.name || "(anonymous filter class)"
+        end
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/coatepec/mcp/tools.rb

@@ -94,6 +94,47 @@ module Coatepec
       end
     end
 
+    # The `rails_spec_flaky_check` MCP tool: runs targeted RSpec examples
+    # multiple times with independently random seeds and reports which
+    # examples' pass/fail status was inconsistent across rounds. Separate
+    # tool from rails_spec_run for the same reason rails_spec_profile is --
+    # see docs/superpowers/specs/2026-08-13-flaky-spec-detection-design.md.
+    class FlakyCheckTool < ::MCP::Tool
+      tool_name "rails_spec_flaky_check"
+      description "Run targeted RSpec examples multiple times with random seeds to detect order-dependent or " \
+                  "intermittent flakiness, reporting which examples' status was inconsistent across runs"
+      annotations(read_only_hint: false, destructive_hint: true, idempotent_hint: false, open_world_hint: true)
+      input_schema(
+        properties: {
+          paths: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 100 },
+          example: { type: %w[string null] },
+          timeout_seconds: { type: "integer", minimum: 1, maximum: 900 },
+          runs: { type: "integer", minimum: 2, maximum: 20 }
+        },
+        required: ["paths"],
+        additionalProperties: false
+      )
+
+      class << self
+        def call(paths:, server_context:, example: nil, timeout_seconds: 120, runs: 5)
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          data = server_context[:worker_manager].check_flaky(
+            paths: paths, example: example, timeout_seconds: timeout_seconds, runs: runs
+          )
+          Response.ok(data: data, meta: meta_for(server_context, started_at))
+        rescue Coatepec::Error => e
+          Response.error(e)
+        end
+
+        private
+
+        def meta_for(server_context, started_at)
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+          { project_root: server_context[:project_root], environment: "test", duration_ms: duration_ms }
+        end
+      end
+    end
+
     # The `rails_routes` MCP tool: lists/filters/paginates the target
     # Rails app's routes.
     class RoutesTool < ::MCP::Tool
@@ -160,5 +201,38 @@ module Coatepec
         end
       end
     end
+
+    # The `rails_controller` MCP tool: returns a controller's actions, action
+    # callbacks, included concerns, and the routes reaching each action.
+    class ControllerTool < ::MCP::Tool
+      tool_name "rails_controller"
+      description "Return a Rails controller's actions, action callbacks, concerns, and the routes " \
+                  "reaching each action, including unroutable actions and routes with no matching action"
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
+      input_schema(
+        properties: {
+          name: { type: "string", pattern: '^[A-Z]\w*(?:::[A-Z]\w*)*$' }
+        },
+        required: ["name"],
+        additionalProperties: false
+      )
+
+      class << self
+        def call(name:, server_context:)
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          data = server_context[:worker_manager].controller(name: name)
+          Response.ok(data: data, meta: meta_for(server_context, started_at))
+        rescue Coatepec::Error => e
+          Response.error(e)
+        end
+
+        private
+
+        def meta_for(server_context, started_at)
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+          { project_root: server_context[:project_root], environment: "test", duration_ms: duration_ms }
+        end
+      end
+    end
   end
 end

data/lib/coatepec/mcp.rb

@@ -13,14 +13,15 @@ require_relative "mcp/tools"
 
 module Coatepec
   # Wires the `rails_spec_run`, `rails_runtime_status`, `rails_runtime_restart`,
-  # `rails_routes`, and `rails_model` tools into an `::MCP::Server` instance
-  # backed by the given project's worker manager.
+  # `rails_spec_flaky_check`, `rails_routes`, `rails_model`, and `rails_controller`
+  # tools into an `::MCP::Server` instance backed by the given project's worker manager.
   module MCP
     def self.build_server(project:, worker_manager:)
       ::MCP::Server.new(
         name: "coatepec",
         version: Coatepec::VERSION,
-        tools: [SpecRunTool, RuntimeStatusTool, RuntimeRestartTool, RoutesTool, ModelTool],
+        tools: [SpecRunTool, RuntimeStatusTool, RuntimeRestartTool, FlakyCheckTool, RoutesTool, ModelTool,
+                ControllerTool],
         server_context: { worker_manager: worker_manager, project_root: project.root }
       )
     end

data/lib/coatepec/spec/flaky_checker.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Coatepec
+  module Spec
+    # Runs a spec selection multiple times, each round with an
+    # independently random seed (RSpec's --seed N is equivalent to --order
+    # rand:N, confirmed against rspec-core's own option_parser.rb), and
+    # groups per-example pass/fail status across rounds by the example's
+    # own id -- stable regardless of execution order, since it's derived
+    # from declaration position/nesting, not from --order. Composes Runner
+    # unchanged, exactly like FactoryProfRunner: every round is a plain,
+    # ordinary Runner#run call with a different seed, no strategy override
+    # needed (unlike FactoryProfRunner, this feature has no load-time
+    # activation trick to fight -- see
+    # docs/superpowers/specs/2026-08-13-flaky-spec-detection-design.md).
+    class FlakyChecker
+      DEFAULT_RUNS = 5
+      MAX_TOTAL_SECONDS = 1800 # timeout_seconds * runs must not exceed this
+      MAX_ITEMS = 200 # same bound rails_model/FactoryProfRunner use elsewhere
+
+      def initialize(project_root, rails_runtime: nil)
+        @runner = Runner.new(project_root, rails_runtime: rails_runtime)
+      end
+
+      def call(paths:, example: nil, timeout_seconds: Runner::DEFAULT_TIMEOUT, runs: DEFAULT_RUNS)
+        validate_budget!(timeout_seconds, runs)
+        rounds = Array.new(runs) { run_one_round(paths, example, timeout_seconds) }
+        build_report(rounds)
+      end
+
+      private
+
+      def validate_budget!(timeout_seconds, runs)
+        return if timeout_seconds * runs <= MAX_TOTAL_SECONDS
+
+        raise Coatepec::Error.new(
+          :flaky_check_budget_exceeded,
+          "timeout_seconds (#{timeout_seconds}) * runs (#{runs}) exceeds the " \
+          "#{MAX_TOTAL_SECONDS}s combined budget -- lower one or both"
+        )
+      end
+
+      def run_one_round(paths, example, timeout_seconds)
+        seed = SecureRandom.random_number(65_536)
+        result = @runner.run(
+          paths: paths, example: example, seed: seed, fail_fast: false,
+          timeout_seconds: timeout_seconds
+        )
+        { seed: seed, status: result[:status], examples: result[:examples] }
+      end
+
+      def build_report(rounds)
+        by_id = group_examples_by_id(rounds)
+        {
+          runs: rounds.size,
+          rounds: rounds.map { |r| { seed: r[:seed], status: r[:status] } },
+          flaky_examples: classify(by_id) { |statuses| statuses.uniq.size > 1 },
+          consistently_failing: classify(by_id) { |statuses| statuses.uniq == ["failed"] }
+        }
+      end
+
+      # Rounds whose RSpec process itself crashed/timed out (not a specific
+      # example failing -- the whole run killed before its JSON summary was
+      # ever written) contribute no per-example data here. Excluded rather
+      # than counted as "every example failed", which would misrepresent a
+      # dead process as evidence against examples that never actually ran;
+      # the round itself is still visible in the `rounds:` summary.
+      def group_examples_by_id(rounds)
+        rounds.each_with_object({}) do |round, acc|
+          round[:examples].each { |ex| (acc[ex[:id]] ||= { meta: ex, statuses: [] })[:statuses] << ex[:status] }
+        end
+      end
+
+      def classify(by_id)
+        by_id.values.select { |v| yield(v[:statuses]) }.first(MAX_ITEMS).map do |v|
+          v[:meta].slice(:id, :description, :file_path, :line_number).merge(
+            statuses: v[:statuses],
+            pass_count: v[:statuses].count("passed"),
+            failure_count: v[:statuses].count("failed")
+          )
+        end
+      end
+    end
+  end
+end

data/lib/coatepec/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Coatepec
-  VERSION = "0.5.2"
+  VERSION = "0.7.0"
 end

data/lib/coatepec/worker/server.rb

@@ -42,8 +42,10 @@ module Coatepec
         case command
         when "status" then @runtime.status
         when "spec_run" then handle_spec_run(args)
+        when "flaky_check" then handle_flaky_check(args)
         when "routes" then handle_routes(args)
         when "model" then handle_model(args)
+        when "controller" then handle_controller(args)
         else
           raise Coatepec::Error.new(:internal_error, "Unknown command #{command}")
         end
@@ -53,6 +55,10 @@ module Coatepec
         Spec::Runner.new(@project_root, rails_runtime: @runtime).run(**args.transform_keys(&:to_sym))
       end
 
+      def handle_flaky_check(args)
+        Spec::FlakyChecker.new(@project_root, rails_runtime: @runtime).call(**args.transform_keys(&:to_sym))
+      end
+
       def handle_routes(args)
         Introspection::Routes.new(**args.transform_keys(&:to_sym)).call
       end
@@ -60,6 +66,10 @@ module Coatepec
       def handle_model(args)
         Introspection::Model.new(args.transform_keys(&:to_sym)[:name]).call
       end
+
+      def handle_controller(args)
+        Introspection::Controller.new(args.transform_keys(&:to_sym)[:name]).call
+      end
     end
   end
 end

data/lib/coatepec/worker_manager.rb

@@ -28,6 +28,18 @@ module Coatepec
       )
     end
 
+    def check_flaky(paths:, example:, timeout_seconds:, runs:)
+      dispatch(
+        "flaky_check",
+        { paths: paths, example: example, timeout_seconds: timeout_seconds, runs: runs },
+        # Each round costs timeout_seconds *plus* real per-round overhead (process
+        # termination/spawn/result-parsing -- roughly 0.6s+ per round from
+        # ProcessStrategy#terminate's own escalation sleeps alone), so the flat
+        # base slack below is scaled by an extra ~2s per round on top of it.
+        timeout: (timeout_seconds * runs) + (2 * runs) + 10
+      )
+    end
+
     def routes(query: nil, limit: 50, offset: 0)
       dispatch("routes", { query: query, limit: limit, offset: offset }, timeout: 30)
     end
@@ -36,6 +48,10 @@ module Coatepec
       dispatch("model", { name: name }, timeout: 30)
     end
 
+    def controller(name:)
+      dispatch("controller", { name: name }, timeout: 30)
+    end
+
     def stop
       @lock.synchronize { @client&.stop }
     end

data/lib/coatepec.rb

@@ -12,12 +12,14 @@ require_relative "coatepec/worker/rails_runtime"
 require_relative "coatepec/introspection/routes"
 require_relative "coatepec/introspection/safe_options"
 require_relative "coatepec/introspection/model"
+require_relative "coatepec/introspection/controller"
 require_relative "coatepec/spec/result"
 require_relative "coatepec/spec/process_strategy"
 require_relative "coatepec/spec/fork_strategy"
 require_relative "coatepec/spec/spawn_strategy"
 require_relative "coatepec/spec/guarded_fork_strategy"
 require_relative "coatepec/spec/runner"
+require_relative "coatepec/spec/flaky_checker"
 require_relative "coatepec/worker/server"
 require_relative "coatepec/worker_manager"
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: coatepec
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.7.0
 platform: ruby
 authors:
 - Enrique Mogollan
 bindir: exe
 cert_chain: []
-date: 2026-08-10 00:00:00.000000000 Z
+date: 2026-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -59,12 +59,14 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- ROADMAP.md
 - Rakefile
 - exe/coatepec
 - exe/coatepec-worker
 - lib/coatepec.rb
 - lib/coatepec/cli.rb
 - lib/coatepec/errors.rb
+- lib/coatepec/introspection/controller.rb
 - lib/coatepec/introspection/model.rb
 - lib/coatepec/introspection/routes.rb
 - lib/coatepec/introspection/safe_options.rb
@@ -74,6 +76,7 @@ files:
 - lib/coatepec/project.rb
 - lib/coatepec/project_config.rb
 - lib/coatepec/protocol.rb
+- lib/coatepec/spec/flaky_checker.rb
 - lib/coatepec/spec/fork_strategy.rb
 - lib/coatepec/spec/guarded_fork_strategy.rb
 - lib/coatepec/spec/path_policy.rb