coatepec 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e0e730ee65e046252297e502039ca8db8b17b4d1774564f79cb708dbe4500b2
-  data.tar.gz: 66d1afbd32ef8ba95de436e046d5b8b90452578a5a1ee0af2a442f7a14f0054d
+  metadata.gz: 72a7dae3c61c36718da0a815ac037c9a50b1a2ae76e282e67d6533131d21c28f
+  data.tar.gz: 99c4c1bd193cffe81e49d711f6bedfebd5cb1552ab91f4455ab7b4d31fbabda5
 SHA512:
-  metadata.gz: b5168b16140e5199c41a11c4e9a73efee643d2acf80405090a7b1ff0ba32ab94432b1e02b396ca5456ba879960025ef640434fcc265ca19147633e00d0b47a88
-  data.tar.gz: 209b126ecc16dadfacad123098e06bcb9d53649f7f3a8b2eca7555a6d098d35f7307cc81b38b015ea0891b49ef088bbe55c3f33ea2de243e14e0212322e68ded
+  metadata.gz: 845750211ab96287bccd73b1108451357453925cd0113e92d4251dacca836437783cf78288fa8ca63de5fdbaa772e1ed1f1fc8ce2afbcb346ff9e2f55c1be85a
+  data.tar.gz: '04698525bb87f82b589a6d50a61a18edbbd4b8e1520fcdf41d3c9e682b75af664480e4dd5adc2cea54be1f8c6afbe71defc4d8157949e954e90c63d60d9e935c'

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,145 @@
 # Changelog
 
+## 0.9.0
+
+- `rails_spec_run` results always carry `execution_mode`: `fork` (Linux, or
+  a macOS guarded fork that ran), `spawn` (macOS with `macos_fork: false`),
+  `spawn_fallback` (the guard declined to fork) or `spawn_after_crash` (the
+  forked child crashed and the run was retried). The key used to appear
+  only when the guarded fork was in play.
+- Behaviour change on macOS: projects that never set `macos_fork: true` now
+  fork the warm worker by default, the way it always has on Linux, using
+  the guarded fork shipped in 0.7.0 (thread-count and gem-denylist checks,
+  a spawn retry if the child crashes). Set `macos_fork: false` in
+  `.coatepec.yml` to keep a fresh spawn per call. Measured on a Rails
+  8.2.0.alpha app: 966 ms saved per run, no fallbacks across nine runs.
+  `OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` is now a recommendation for
+  projects that see `spawn_after_crash`, not a requirement.
+- `.coatepec.yml` gains a `defaults` map: `spec_run.include_passing`,
+  `spec_run.include_stdout`, `spec_run.timeout_seconds` and `routes.engines`
+  set project-wide defaults for those inputs. A call argument always wins;
+  an omitted key means the built-in default; an unknown key or an
+  out-of-range value fails the call with `invalid_config` naming it. The
+  file is re-read on every call.
+- `rails_runtime_status` reports `spec_strategy` (`fork`, `guarded_fork` or
+  `spawn`), `fallbacks` (how many guarded-fork runs fell back to spawn in
+  this worker's lifetime; `null` unless the guarded fork is in use) and
+  `defaults` (the effective `rails_spec_run` and `rails_routes` defaults
+  after `.coatepec.yml`), so an agent can see every default in one call.
+  `fallbacks` also counts `rails_spec_flaky_check` rounds, which run through
+  the same strategy.
+
+## 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

data/README.md

@@ -57,9 +57,9 @@ 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)
-                                          Process.fork, guarded --> opt-in, see Configuration
+                              |-- Linux:  Process.fork  --> isolated RSpec/Minitest child
+                              `-- macOS:  Process.fork, guarded --> isolated RSpec/Minitest child (default)
+                                          Process.spawn --> fresh process, see Configuration (macos_fork: false)
 ```
 
 ## Configuration
@@ -68,23 +68,43 @@ An optional `.coatepec.yml` at the target Rails app's root enables
 per-project settings:
 
 ```yaml
-macos_fork: true                     # opt into forking on macOS (see below)
+macos_fork: false                    # opt out of forking on macOS (default true; see below)
 macos_fork_unsafe_gems: [some_gem]   # extends the built-in fork-unsafe denylist
+
+defaults:
+  spec_run:
+    include_passing: true            # true or false (default false)
+    include_stdout: always           # failures (default), always, never
+    timeout_seconds: 300             # 1..900 (default 120)
+  routes:
+    engines: include                 # include, exclude (default), only
 ```
 
 A missing file means every setting takes its default -- this file is never
 required.
 
-### macOS fork (experimental, opt-in)
+`defaults` sets project-wide values for those four inputs; a call argument
+always wins, an omitted key falls back to the built-in default, and an
+unknown key or value fails the call with `invalid_config` naming it. The
+file is re-read on every call, so edits apply immediately.
+`defaults.spec_run` applies to `rails_spec_run` only; `rails_spec_flaky_check`
+keeps its own per-round budget.
+
+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 (default since 0.9.0)
 
-On macOS, `rails_spec_run` normally spawns a fresh `bundle exec rspec`
-process per call, re-booting Rails every time -- the warm-worker speedup
-described above only applies on Linux by default. Setting `macos_fork:
-true` lets Coatepec attempt `Process.fork` on macOS too, reusing the warm
-boot the way Linux does.
+On macOS, `rails_spec_run` forks the warm worker for each call, reusing the
+boot the way it always has on Linux. Setting `macos_fork: false` in
+`.coatepec.yml` opts the project out: every call then spawns a fresh
+`bundle exec rspec` process and re-boots Rails, so only the Linux lane
+gets the warm-worker speedup described above.
 
-This is opt-in because forking a process with native extensions loaded
-isn't universally safe. Before each fork, Coatepec checks the worker's
+The fork is guarded, because forking a process with native extensions
+loaded isn't universally safe. Before each fork, Coatepec checks the worker's
 live thread count against its post-boot baseline and its loaded gems
 against a denylist, falling back to a fresh spawn for that one call if
 either check looks risky. The built-in denylist ships empty -- no single
@@ -93,17 +113,17 @@ thread-count-only until a project adds its own
 `macos_fork_unsafe_gems`. If a fork is attempted and the child crashes
 anyway, Coatepec transparently retries via spawn and returns that result
 -- fork stays enabled for later calls. Every `rails_spec_run` result
-includes an `execution_mode` field (`fork`, `spawn_fallback`, or
-`spawn_after_crash`) so you can see which path actually ran for a given
+includes an `execution_mode` field (`fork`, `spawn`, `spawn_fallback`,
+or `spawn_after_crash`) so you can see which path actually ran for a given
 call; `spawn_after_crash` results also carry the crashed fork's own stderr
 under `crashed_fork_stderr` so the crash can be diagnosed.
 
-`macos_fork: true` also effectively requires
-`OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` in Coatepec's own environment.
-Without it, a forked child that touches an Objective-C-initialized class
-aborts -- Coatepec retries via spawn, so it degrades silently to the slow
-path (no crash, no error surfaced) rather than failing loudly, and you
-simply never get the speedup. Set it on the MCP server process itself:
+`OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` in Coatepec's own environment is
+recommended if you ever see `spawn_after_crash`. Without it, a forked child
+that touches an Objective-C-initialized class aborts -- Coatepec retries via
+spawn, so it degrades to the slow path for that call (no crash, no error
+surfaced) rather than failing loudly, and you simply never get the speedup.
+Set it on the MCP server process itself:
 
 ```json
 {
@@ -125,34 +145,78 @@ 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_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_run` | `paths: string[1..100]`, `example?`, `seed?`, `fail_fast?`, `timeout_seconds?` (1..900, default 120), `include_passing?`, `include_stdout?` (`failures` default, `always`, `never`) (all three default-able in `.coatepec.yml`) | 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); every result carries `execution_mode` (`fork`, `spawn`, `spawn_fallback`, `spawn_after_crash`) |
+| `rails_runtime_status` | `{}` | Reports Ruby/Rails versions, worker PID, boot_id, lifecycle state, the project root, `spec_strategy` (`fork`, `guarded_fork`, `spawn`), `fallbacks` (guarded-fork runs that fell back to spawn; `null` unless guarded) and `defaults` (the effective `rails_spec_run`/`rails_routes` defaults after `.coatepec.yml`) |
+| `rails_runtime_restart` | `{}` | Unconditionally respawns the worker, discarding its warm boot; returns the fresh worker's status, including `spec_strategy` and `fallbacks` |
+| `rails_routes` | `query?`, `limit?` (1..200, default 100), `offset?`, `engines?` (`exclude` default, `include`, `only`) (default-able in `.coatepec.yml`) | 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 examples whose status was inconsistent across runs |
+| `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.
+- `engines_excluded` is a correctness signal, not only a saving. Engine
+  routes print their paths relative to the mount point, so
+  `bin/rails routes -g admin` cannot find an admin engine's routes at all: it
+  matches the mount line and answers "one admin route" with no hint that
+  anything is missing. `rails_routes(query: "admin")` returns that one row
+  plus `engines_excluded: 243`, so the reader knows the rest exists.
+- Opting in is the expensive path, and it paginates. A broad query with
+  `engines: "include"` on an app with a mounted admin engine costs several
+  times the default response and can still stop at the 100-row page of a
+  larger match (`next_offset` says so), where the default returned the
+  application's routes complete. Reach for `engines: "only"` with the
+  engine's class name when the engine's routes are the question.
+- 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`
@@ -162,9 +226,10 @@ a no-op.
 
 - "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`.
+  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
@@ -185,6 +250,12 @@ a no-op.
   `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
@@ -192,18 +263,22 @@ a no-op.
   `ActionController` descendant (a plain class, a model) raises
   `not_action_controller`.
 
-`rails_controller` has two deliberate limitations, matching a boundary
-`rails_routes` already has:
+`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).
-- **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.
+
+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`:
 
@@ -223,6 +298,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
@@ -242,6 +319,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
@@ -262,11 +363,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
 
@@ -279,8 +381,8 @@ 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`/
+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`,
@@ -291,9 +393,10 @@ 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 (the lane that exercises the guarded-fork path above).
 
 ## Development
 

data/ROADMAP.md

@@ -4,56 +4,19 @@ 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.
+## 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
 
@@ -76,8 +39,9 @@ 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.
+(Linux vs. macOS, `macos_fork` adoption) -- `macos_fork` is the default from
+0.9.0, so the fork path is now the common case on both platforms -- before
+picking a fix, rather than guessing.
 
 ## Run Rails 8.1's built-in CI (`bin/ci`)
 
@@ -114,16 +78,16 @@ or folds into an existing one, and whether "security audits" specifically
 `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
+## Controller introspection -- shipped in 0.7.0
 
-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.
+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)
 
@@ -171,9 +135,12 @@ Two constraints worth keeping if this is revisited:
 ## 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.
+*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