coatepec 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddcc044bcc53590ba19d988b0db8ea0aea4efd7db102bd6718196e61ab9ab820
-  data.tar.gz: 1b8b779b5bb59068a7fdd5fc90e7d44b900d50f1918e1d68877a9ccad24bf1e7
+  metadata.gz: 550a60896b3c267b12b5db85b787c52d93b97dd2b95409c8bf78943ea63a27d0
+  data.tar.gz: '09c6cbbc7c00dd604d2cb5dfbabbb0101aea3cadf5d24070f3254a144bb45012'
 SHA512:
-  metadata.gz: 56fce0755730ab151c81fb43f88a28d6e081b242c3e9bb31fac71578c290e864efbc5e5313702a4c015b95a661cdd601f1701979c98dbbdae1a0cfa06e0be2fa
-  data.tar.gz: 4101b3595de972478ac414f3c019b413ec991cfe1d8ea0fbb251010fad6d699eaeb849818a1c4dbcfe813b47b41af220b68a7f971efe287dbbb8c598d8ff9763
+  metadata.gz: 484557dd0635d21f7669a12b6accab0684e4850e4ac91b6718b733bd23372aceaa5b903f387facb22fdc6b0c2d0a09dfb4805ace67e6b24c66f95c482240d69b
+  data.tar.gz: e3fcc83c1f752dfba27b1260584b2ee1d0df5707e36163d049015babe269290a2467b3018c0e3696d8d6c4d4fcaf5bf8b2e325a3792ac7d3bcb085cad433e73c

data/.rubocop.yml

@@ -15,6 +15,11 @@ Style/StringLiterals:
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
 
+Metrics/ParameterLists:
+  # Keyword-only signatures here mirror the MCP tools' input schemas, and a tool
+  # gaining an input shouldn't force a refactor; positional lists stay capped at 5.
+  CountKeywordArgs: false
+
 Metrics/BlockLength:
   # RSpec's describe/context/it DSL naturally produces long blocks; this is the
   # standard exclusion used by rubocop-rspec's own default config. inherit_mode

data/CHANGELOG.md

@@ -1,5 +1,147 @@
 # Changelog
 
+## 0.8.0
+
+- Tool responses are now compact JSON rather than pretty-printed (22-32%
+  smaller on measured payloads); set `COATEPEC_PRETTY=1` on the server
+  process to restore indentation.
+- `rails_spec_run` now omits passing examples from `examples` by default --
+  a 49-test green run drops from ~3,700 tokens to ~160 -- and `summary` gains
+  `pending_count`. Pass the new `include_passing: true` input to get the full
+  roster back (still capped at 500 examples). `rails_spec_flaky_check` is
+  unaffected: it still sees every example.
+- `examples[].description` (and `flaky_examples[].description`) is omitted
+  when it would only repeat `id`, which is always the case for Minitest.
+- `rails_routes` (with `engines: "include"`) and `rails_controller` now
+  include the routes of engines mounted in the application, expanded one
+  level deep (an engine mounted inside another engine stays an opaque mount
+  route, the same boundary `bin/rails routes` draws). Paths carry the mount
+  point, so `/widget_admin/audits` is what both tools report, and a
+  controller living inside an engine no longer has all of its actions listed
+  under `unroutable_actions`.
+- `rails_routes` gains an `engine` column and `rails_controller`'s
+  `actions[].routes` entries an `engine` field: `null` for an application
+  route, the engine's class name otherwise. `rails_routes`' `query` matches
+  against it like every other column, so `query: "Avo::Engine"` with
+  `engines: "include"` or `"only"` returns exactly that engine's routes.
+  Application routes are listed before engine routes.
+- An engine route's `name` (`route_name` in `rails_controller`) is relative
+  to its engine: it is reached through the mount's helper,
+  `<mount name>.<name>_path`, where the mount name is the `name` of the mount
+  route itself -- never as a top-level url helper.
+- `rails_routes` and `rails_controller` now omit routes Rails marks
+  `internal` -- its own `/rails/info` and friends -- matching
+  `bin/rails routes`. This is a behaviour change for callers that relied on
+  seeing them.
+- Add Minitest support to `rails_spec_run` and `rails_spec_flaky_check`:
+  selectors under a `test/` root ending in `_test.rb` run through Rails'
+  Minitest runner in the same warm worker, with the same
+  `example`/`seed`/`fail_fast`/`timeout_seconds` inputs and the same result
+  shape (`id` is `ClassName#test_method`; a skip is `"pending"`, an error is
+  `"failed"`). The framework is chosen per call from the selector paths --
+  an app that has both `spec/` and `test/` works without configuration; one
+  call may not mix the two (`mixed_test_frameworks`).
+- The Minitest child sets `PARALLEL_WORKERS=1`, so a selection above Rails'
+  parallelization threshold runs serially under the call's single timeout
+  instead of forking a worker tree.
+- `file:LINE` selection is implemented by Coatepec itself rather than relying
+  on Rails' line filtering, which is absent in apps generated with
+  `--skip-test` and targets a method Minitest 6 no longer calls on Rails 7.1.
+- Path validation now runs before the framework is required, so an invalid
+  path on a Minitest-only app reports `invalid_spec_path` instead of
+  `unsupported_test_framework`. `invalid_spec_path` keeps its code for both
+  frameworks.
+- `rails_model` collapses validators with identical name, attributes and
+  options into one entry (a concern and the model body declaring the same
+  validation used to appear twice); the 200-item cap now counts distinct
+  validators.
+- `rails_routes` defaults to 100 routes per page (was 50 -- engine expansion
+  roughly doubled route counts when engines are included) and returns
+  `next_offset` for the follow-up call, `null` on the last page.
+- `rails_spec_run`: when several tests fail with the same error text (a
+  broken layout erroring every controller test, say), `stdout` keeps the
+  first failure block and replaces each repeat with one roll-up line
+  naming the other tests -- a 5-error controller run drops from ~4,850 B to
+  roughly a third of that. Backtrace frames and RSpec's `Failure/Error:`
+  source line are ignored when deciding that two blocks match.
+- `rails_spec_run` gains `include_stdout` (`failures`, the default; `always`;
+  `never`). A passing run's `stdout` is `null` by default -- its progress
+  dots and summary line only repeat `summary` -- and a failing run's is
+  returned; `always` and `never` override that either way. The key stays so
+  the result shape is uniform. `stderr` is always returned.
+- `rails_routes` returns application routes only by default and gains
+  `engines` to change that: `include` lists the routes of mounted engines
+  too -- the routes 0.8.0 added by expanding engines -- and `only` lists just
+  those; the default matches pre-0.8.0 output (application routes, the mount
+  route included). Every response carries `engines` (the filter applied) and
+  `engines_excluded` (how many routes matching `query` were withheld), so the
+  omission is stated, never silent. The filter applies after `query` and
+  before paging, so `matched` and `next_offset` describe the kept set; an
+  engine's mount route counts as an application route. Measured on an app
+  with a mounted admin engine, six typical route queries cost 57% less
+  context with engine routes withheld.
+- `rails_model` cuts an array-valued validator option longer than 20 entries
+  to its first 20 and adds `<option>_count` (the full length) and
+  `<option>_truncated: true` beside it -- a 249-code `inclusion` list no
+  longer costs 1.4 KB per model. Shorter lists are unchanged and carry no
+  sibling keys.
+- Every tool response's `meta` is now just `duration_ms`; `project_root` is
+  reported once by `rails_runtime_status` (beside `environment`) instead of
+  on every call.
+- `rails_spec_run` results carry `child_pid`, `signaled`, `termsig`,
+  `stopsig` and `coredump` only when the child did not exit normally (a
+  timeout kill or a crash); a normal run reports `status`, `exit_code` and
+  the output fields alongside the usual `summary` and `examples`.
+- `rails_model` returns `name`, `table_name`, `primary_key`, `abstract_class`
+  and `counts` (the size of each of its four lists, after validator
+  de-duplication and the 200-item caps) by default, and gains `fields`, an
+  array of `columns`/`associations`/`validators`/`enums` naming the lists to
+  include; omitted or `[]` means counts only. Callers that read the lists
+  must now ask for them -- the default response is roughly an order of
+  magnitude smaller than the full one on a typical model.
+- `rails_routes` returns `columns` (`name`, `verb`, `path`, `controller`,
+  `action`, `engine`) and `rows` instead of one object per route -- the six
+  key names were a third of every item's bytes -- and both `rails_routes`
+  and `rails_controller` report paths without the `(.:format)` suffix Rails
+  appends to most routes.
+- `rails_spec_run`'s `summary` gains `error_count` (how many of
+  `failure_count` were errors rather than assertion failures) and
+  `assertion_count` (Minitest's assertion total), so a green run answers
+  "how many assertions ran?" without `stdout` and a failing run's counts
+  match the `0 failures, 5 errors` line beside them. Both are `null` for
+  RSpec, which reports neither.
+
+## 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

data/README.md

@@ -57,8 +57,8 @@ MCP client
     v
 Coatepec parent (Rails-free)
     `-- private NDJSON --> test worker (Rails "test", booted lazily, kept warm)
-                              |-- Linux:  Process.fork  --> isolated RSpec child
-                              `-- macOS:  Process.spawn --> fresh RSpec process (default)
+                              |-- Linux:  Process.fork  --> isolated RSpec/Minitest child
+                              `-- macOS:  Process.spawn --> fresh RSpec/Minitest process (default)
                                           Process.fork, guarded --> opt-in, see Configuration
 ```
 
@@ -75,6 +75,11 @@ macos_fork_unsafe_gems: [some_gem]   # extends the built-in fork-unsafe denylist
 A missing file means every setting takes its default -- this file is never
 required.
 
+Tool responses are compact JSON -- no indentation, nothing downstream reads
+it. Set `COATEPEC_PRETTY=1` in the MCP server's `env` (the same place as
+`OBJC_DISABLE_INITIALIZE_FORK_SAFETY` in the JSON example below) to
+pretty-print them when you are reading the sidecar by hand.
+
 ### macOS fork (experimental, opt-in)
 
 On macOS, `rails_spec_run` normally spawns a fresh `bundle exec rspec`
@@ -125,38 +130,129 @@ a no-op.
 
 | Tool | Input | Notes |
 |---|---|---|
-| `rails_spec_run` | `paths: string[1..100]`, `example?`, `seed?`, `fail_fast?`, `timeout_seconds?` (1..900, default 120) | Isolated per run; output capped at 256 KiB per stream |
-| `rails_runtime_status` | `{}` | Reports Ruby/Rails versions, worker PID, boot_id, lifecycle state |
+| `rails_spec_run` | `paths: string[1..100]`, `example?`, `seed?`, `fail_fast?`, `timeout_seconds?` (1..900, default 120), `include_passing?`, `include_stdout?` (`failures` default, `always`, `never`) | RSpec (`spec/**/*_spec.rb`) or Minitest (`test/**/*_test.rb`), chosen from the paths; isolated per run; output capped at 256 KiB per stream; failure blocks in `stdout` that repeat an earlier block's error verbatim are replaced by a roll-up line naming the tests; returns `summary` counts (`example_count`, `failure_count`, `error_count`, `pending_count`, `assertion_count`, `duration`; the error and assertion counts come from Minitest and are `null` for RSpec) plus only the failed/pending `examples`, pass `include_passing: true` for the full roster (still capped at 500 examples); `stdout` is returned only for failing runs by default; `include_stdout: "always"` keeps it for green runs, `"never"` drops it always (the key stays, `null`); `stderr` is always returned; `child_pid`/`signaled`/`termsig`/`stopsig`/`coredump` appear only when the child did not exit normally (a timeout kill or a crash) |
+| `rails_runtime_status` | `{}` | Reports Ruby/Rails versions, worker PID, boot_id, lifecycle state, and the project root (`project_root`) |
 | `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_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 |
+| `rails_routes` | `query?`, `limit?` (1..200, default 100), `offset?`, `engines?` (`exclude` default, `include`, `only`) | Returns `columns` (`name`, `verb`, `path`, `controller`, `action`, `engine`) and `rows` in that order; paths omit the `(.:format)` suffix Rails appends. Case-insensitive filter across name/verb/path/controller/action/engine. Application routes only by default; `engines: "include"` adds the routes of mounted engines (one level deep, paths prefixed with the mount point, `engine` naming the engine class; `null` for an application route), `"only"` returns just those. Every response carries `engines` (the filter applied) and `engines_excluded` (how many routes matching `query` the filter withheld), so nothing is hidden silently. The filter applies after `query` and before paging, so `matched`/`next_offset` describe the kept set. The engine's mount route counts as an application route. Routes Rails marks `internal` are omitted, like `bin/rails routes`. `next_offset` is the offset of the next page, or `null` on the last one |
+| `rails_model` | `name` (constant path, e.g. `Widget` or `Admin::Widget`), `fields?` (any of `columns`, `associations`, `validators`, `enums`; omitted or `[]` means none) | Returns `name`, `table_name`, `primary_key`, `abstract_class` and `counts` (the size of each of the four lists, each capped at 200) by default and only the lists named in `fields` -- so a how-many question costs a few dozen bytes and `fields: ["columns"]` asks for the one list you need; ActiveRecord models only; columns, associations, validators, enums -- no row data; validators are de-duplicated by class, attributes and options (a concern and the model body declaring the same validation count once), so the count can be lower than `klass.validators.size`; an array-valued validator option longer than 20 entries (a country-code `inclusion` list, say) is cut to its first 20 with `<option>_count` and `<option>_truncated: true` beside it |
+| `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 tests whose status was inconsistent across runs; RSpec or Minitest, chosen from the paths |
 
 ### Example queries
 
 `rails_routes`:
 
-- "What are all the routes in this app?" -- `rails_routes()`
+- "What are all the routes in this app?" -- `rails_routes()`, the
+  application's own; add `engines: "include"` for the mounted engines' too.
 - "What's the URL for widgets?" -- `rails_routes(query: "widget")`. `query` is a
   case-insensitive substring match across name, verb, path, controller, *and*
   action -- not just the path -- so a resource name alone typically returns
   every route for that resource (index/create/new/...); narrow further with
-  something like `query: "new_widget"` to hit one route by name.
+  something like `query: "new_widget"` to hit one route by name. The call
+  already leaves out the admin engine's scaffolding, which is often two thirds
+  of every match; the response's `engines_excluded` says how many engine routes
+  it held back. Pass `engines: "include"` to see them too, or
+  `engines: "only"` for just the engine's.
 - "Which routes accept POST?" -- `rails_routes(query: "POST")`, the same
   substring match applied to the verb column.
+- "Which routes does the Avo engine add?" --
+  `rails_routes(query: "Avo::Engine", engines: "only")` -- the substring match
+  covers the `engine` column too, so an engine's class name returns exactly the
+  routes mounted from it. Application routes always sort before engine routes,
+  so an unfiltered listing (with `engines: "include"`) reads the way
+  `bin/rails routes` does.
+- An engine route's `name` is relative to its engine, not a top-level url
+  helper: the row `["audits", "GET", "/widget_admin/audits",
+  "widget_admin/audits", "index", "WidgetAdmin::Engine"]` is reached as
+  `widget_admin.audits_path` -- `<mount name>.<name>_path`, where the mount
+  name is the `name` of the mount route itself -- and `audits_path` alone
+  does not exist on the application.
+- An engine mounted at two paths is listed under both mount points, once per
+  prefixed path, whenever engine routes are in scope, since each of those
+  paths is a real, reachable URL.
+  `bin/rails routes` keys engines by endpoint and so lists such an engine
+  only once.
+- Paging: when `next_offset` is not `null`, call again with
+  `offset: next_offset` to get the next page.
 
 `rails_model`:
 
 - "What columns does Widget have, and which are nullable?" --
-  `rails_model(name: "Widget")` -- see `columns[].null`, `columns[].sql_type`,
-  `columns[].default`.
-- "What validations and associations does Widget enforce?" -- same call --
+  `rails_model(name: "Widget", fields: ["columns"])` -- see `columns[].null`,
+  `columns[].sql_type`, `columns[].default`.
+- "What validations and associations does Widget enforce?" --
+  `rails_model(name: "Widget", fields: ["validators", "associations"])` --
   see `validators` and `associations`.
+- "How many columns, associations, validators and enums does Event have?" --
+  `rails_model(name: "Event")` -- see `counts`; ask for the lists with
+  `fields` when you need them.
+- A long allow-list is summarised, not enumerated: `validates :country_code,
+  inclusion: { in: ISO_CODES }` with 249 codes comes back as `"in"` holding
+  the first 20, `"in_count": 249` and `"in_truncated": true`. A list of 20 or
+  fewer has no `_count`/`_truncated` siblings.
 - "What happens if I ask about a non-model class, like a controller?" --
   `rails_model(name: "ApplicationController")` raises `not_active_record_model`
   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` (without the `(.:format)` suffix -- byte-identical
+  to the same route's `path` from `rails_routes`), `route_name`, and `engine`
+  (`null` for an application route, the engine's class name for a route that
+  reaches this controller through a mount).
+- "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.
+- Unlike `concerns`, `callbacks[]` is *not* filtered to app code: it is the
+  controller's full callback chain, so callbacks Rails itself installs show
+  up too -- `verify_authenticity_token` / `verify_same_origin_request` from
+  the default forgery protection, and a `"(block)"` entry for macros like
+  `allow_browser` that register a Proc. Read the list as "everything that
+  runs around an action", not "everything this app wrote".
+- `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 one deliberate limitation:
+
+- **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).
+
+Routes drawn by an engine mounted in the application are cross-referenced
+like any other, with the mount point on the path and the engine's class name
+in `engine` -- so a controller that lives inside an engine reports its real
+routes rather than listing every action as unroutable. Their `route_name` is
+engine-local, reached as `<mount name>.<route_name>_path`, exactly as in
+`rails_routes`. Expansion goes one level deep: an engine mounted inside
+another engine stays an opaque mount route, the same boundary `bin/rails
+routes` (and therefore `rails_routes`) draws.
+
 `rails_spec_flaky_check`:
 
 - "Is this spec flaky?" -- `rails_spec_flaky_check(paths: ["spec/models/widget_spec.rb"])`
@@ -175,6 +271,8 @@ a no-op.
   `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.
+- `description` is only present when it differs from `id` (RSpec); Minitest
+  entries carry `id` only.
 - `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
@@ -194,6 +292,30 @@ worker). For most apps this is invisible, but if you ever see behavior differ
 between Coatepec and your own `bundle exec rspec`, this is the first thing to
 suspect.
 
+Minitest through `rails_spec_run`:
+
+- "Run this Minitest file" -- `rails_spec_run(paths: ["test/models/widget_test.rb"])`;
+  the framework is decided by the path, and there is no separate
+  Minitest-named tool. `test/models/widget_test.rb:12` runs the one test
+  whose definition spans line 12, and a directory runs every `_test.rb`
+  under it.
+- `example:` is a substring match on the test's method name
+  (`example: "reaches the"` matches `test_reaches_the_database`), passed to
+  Minitest as an escaped regex.
+- Results use RSpec's vocabulary so the shape is identical: a Minitest skip
+  is `"pending"`, an error is `"failed"` and counts toward
+  `summary.failure_count` -- which is why that number can exceed the
+  `failures` Minitest prints in `stdout`; `summary.error_count` says how many
+  of them were errors, and `summary.assertion_count` is the assertion total
+  Minitest prints; `id` is `ClassName#test_method`.
+- One call may not mix `spec/` and `test/` paths (`mixed_test_frameworks`).
+- Rails' parallel testing is disabled in the child (`PARALLEL_WORKERS=1`), so
+  a large directory selection runs serially under the one timeout budget
+  rather than forking a worker tree.
+- `file:LINE` works even when the app was generated with `--skip-test` (no
+  `rails/test_unit/railtie`) or runs Rails 7.1 with Minitest 6, both of which
+  break Rails' own line filtering; Coatepec installs its own.
+
 ### Restarts
 
 If any tool call fails with `sidecar_restart_required`, the target app's
@@ -214,11 +336,12 @@ it always respawns, even if the current worker looks healthy.
 ## Security boundary
 
 No eval, console, SQL/record access, shell, Rake, or file-write tool. Spec
-selectors must resolve inside an allowed spec root (`spec/`, `packs/*/spec/`,
-`engines/*/spec/`, `gems/*/spec/`); absolute paths, `..`, symlink escapes,
-non-`_spec.rb` files, and more than 100 selectors are rejected. RSpec still
-executes application-controlled code; only run Coatepec against a trusted
-checkout.
+selectors must resolve inside an allowed spec or test root (`spec/`, `test/`,
+and the `packs/*/`, `engines/*/`, `gems/*/` variants of each); absolute
+paths, `..`, symlink escapes, files that are neither `_spec.rb` under a spec
+root nor `_test.rb` under a test root, and more than 100 selectors are
+rejected. RSpec and Minitest still execute application-controlled code; only
+run Coatepec against a trusted checkout.
 
 ### Compared to Rails Active MCP
 
@@ -231,20 +354,22 @@ sophisticated bypasses of a denylist like that are always possible in
 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
+tool to begin with. `rails_spec_run` only ever executes RSpec or Minitest
+files that already exist under the app's own allowed spec/test roots, and `rails_routes`/
+`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.
 
 ## Compatibility
 
-Ruby `>= 3.2`, Rails `>= 7.1, < 8.2`. CI tests three lanes: Rails 8.1 on
-Linux (primary), Rails 7.1 on Linux (compat), and Rails 8.1 on macOS (which
-is where the guarded-fork path above actually forks).
+Ruby `>= 3.2`, Rails `>= 7.1, < 8.2`, Minitest 5.x and 6.x (the fixture
+apps pin 6.0.6; the 5.x name-filter flag is unit-tested). CI tests three
+lanes: Rails 8.1 on Linux (primary), Rails 7.1 on Linux (compat), and Rails
+8.1 on macOS (which is where the guarded-fork path above actually forks).
 
 ## Development
 

data/ROADMAP.md

@@ -0,0 +1,163 @@
+# 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 -- shipped in 0.8.0
+
+Shipped through the existing `rails_spec_run`/`rails_spec_flaky_check`
+tools. The open questions resolved as: one tool, dispatching by
+*selector shape* (`test/**/*_test.rb` vs `spec/**/*_spec.rb`) rather
+than by Gemfile, since that is per-request and unambiguous for apps
+with both; structured per-test output comes from an in-process
+`Minitest::AbstractReporter` writing RSpec's JSON shape, so
+`Spec::Result` and `FlakyChecker` were reused unchanged; and Minitest's
+`--seed` is a direct equivalent (16-bit, random order by default), so
+the flaky checker works as-is. See
+`docs/superpowers/specs/2026-09-05-minitest-support-design.md` (local-only)
+for the design and the line-filtering finding.
+
+## 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 -- shipped in 0.7.0
+
+Shipped as `rails_controller` (`Coatepec::Introspection::Controller`) in
+0.7.0: actions, `before`/`after`/`around` callbacks with their `only`/`except`
+restrictions and `if`/`unless` conditions, included concerns, and a
+cross-reference of every action against `Rails.application.routes`
+(`unroutable_actions` / `routes_without_action`). Strong parameters were
+deliberately left out: a `permit` list exists only as code inside a method
+body, and recovering it would mean source parsing (see "Considered and set
+aside" below). See the README and CHANGELOG for the full contract.
+
+## 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
+`belongs_to`/`has_many` referencing a column or table that isn't in the
+schema, that kind of thing. (The route-to-missing-action case is already
+covered per controller by `rails_controller`'s `routes_without_action`,
+shipped in 0.7.0; an app-wide sweep of the whole route table would be the
+cross-file version of that same check.)
+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/bounded_options.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Coatepec
+  module Introspection
+    # Caps the array-valued entries of a sanitized validator options hash (see SafeOptions) for rails_model output:
+    # 249 country codes just say "allow-list", and the count plus flag beside a cut list keep it self-describing.
+    module BoundedOptions
+      module_function
+
+      def call(options, max)
+        options.each_with_object({}) do |(key, value), bounded|
+          bounded[key] = value
+          next unless value.is_a?(Array) && value.size > max
+
+          bounded[key] = value.first(max)
+          bounded["#{key}_count"] = value.size
+          bounded["#{key}_truncated"] = true
+        end
+      end
+    end
+  end
+end