rigortype 0.1.11 → 0.1.13

data/plugins/rigor-rails-routes/lib/rigor/plugin/rails_routes.rb

@@ -4,6 +4,7 @@ require "rigor/plugin"
 
 require_relative "rails_routes/helper_table"
 require_relative "rails_routes/routes_parser"
+require_relative "rails_routes/helper_discoverer"
 require_relative "rails_routes/analyzer"
 
 module Rigor
@@ -52,32 +53,104 @@ module Rigor
     class RailsRoutes < Rigor::Plugin::Base
       manifest(
         id: "rails-routes",
-        version: "0.1.0",
+        # Bumped 2026-05-28 — GitLab FOSS sweep adds: (a)
+        # `draw_all :name` support (action_dispatch-draw_all
+        # gem; single-file load semantics matching `draw :name`);
+        # (b) keyword-style `scope(path: ':project_id',
+        # as: :project)` — path read from the `:path` keyword,
+        # not only from the positional first arg; (c) detection
+        # of iterative `direct(name.sub(FROM, TO)) do ... end`
+        # alias-generation idiom — generates `<TO>_*` aliases
+        # for every registered `<FROM>_*` helper. GitLab uses
+        # this to shorten `namespace_project_*` → `project_*`.
+        version: "0.27.0",
         description: "Validates Rails route-helper calls against `config/routes.rb`.",
         config_schema: {
-          "routes_file" => :string
+          "routes_file" => :string,
+          "helper_paths" => :array
         },
         produces: [:helper_table]
       )
 
       DEFAULT_ROUTES_FILE = "config/routes.rb"
 
+      # The directories `HelperDiscoverer` walks for project-
+      # defined `*_path` / `*_url` methods. Default to the whole
+      # `app/` tree — the suffix filter inside the discoverer
+      # keeps the registered set tight, and real-world Rails
+      # apps routinely keep URL builders under `app/controllers`
+      # (private `def page_url`, `def callback_url` shapes),
+      # `app/lib` (Mastodon's `TranslationService::DeepL#base_url`),
+      # `app/services` (`SoftwareUpdateCheckService#api_url`),
+      # `app/serializers`, `app/presenters`, `app/decorators`,
+      # not only `app/helpers/`. Walking the whole tree is the
+      # honest answer to "does this `_path` / `_url` name exist
+      # anywhere in the project?"; the cost is a one-time Prism
+      # parse per file at startup, which is bounded.
+      DEFAULT_HELPER_PATHS = ["app"].freeze
+
       # Cached producer — reads `config/routes.rb` through
       # the trusted `IoBoundary` and parses through
       # {RoutesParser}. The descriptor's auto-collected
       # `FileEntry` digest invalidates the cache on routes-
       # file edits.
+      #
+      # Passes a `file_reader` lambda so the parser can follow
+      # `draw(:admin)` → `config/routes/admin.rb` partials.
       producer :helper_table do |_params|
+        routes_dir = "#{File.dirname(@routes_file)}/routes"
+        file_reader = lambda do |name|
+          io_boundary.read_file("#{routes_dir}/#{name}")
+        rescue StandardError
+          nil
+        end
         contents = io_boundary.read_file(@routes_file)
-        RoutesParser.parse(contents)
+        custom_helpers = discover_custom_helpers
+        RoutesParser.parse(contents, file_reader: file_reader, custom_helpers: custom_helpers)
       end
 
       def init(_services)
         @routes_file = config.fetch("routes_file", DEFAULT_ROUTES_FILE)
+        @helper_paths = Array(config.fetch("helper_paths", DEFAULT_HELPER_PATHS)).map(&:to_s)
         @helper_table = nil
         @load_error = nil
       end
 
+      # Walks every configured `helper_paths:` directory
+      # through the trusted `IoBoundary` and returns the set
+      # of project-defined `*_path` / `*_url` method names
+      # for {HelperDiscoverer}. Each file digest is captured
+      # by the boundary so editing a helper file invalidates
+      # the `:helper_table` cache automatically. Returns the
+      # empty set when nothing under `helper_paths:` exists —
+      # the routes table still works.
+      def discover_custom_helpers
+        contents_per_path = {}
+        each_helper_file do |path|
+          contents_per_path[path] = io_boundary.read_file(path)
+        rescue Plugin::AccessDeniedError, Errno::ENOENT
+          next
+        end
+        HelperDiscoverer.discover(contents_per_path)
+      end
+
+      def pre_read_helper_files
+        each_helper_file do |path|
+          io_boundary.read_file(path)
+        rescue Plugin::AccessDeniedError, Errno::ENOENT
+          next
+        end
+      end
+
+      def each_helper_file(&)
+        @helper_paths.each do |dir|
+          absolute = File.expand_path(dir)
+          next unless File.directory?(absolute)
+
+          Dir.glob(File.join(absolute, "**", "*.rb")).each(&)
+        end
+      end
+
       # Publishes the parsed table to the cross-plugin fact
       # store so future Tier 2 plugins (rigor-actionpack
       # Phase 4) can read it via `services.fact_store.read`.
@@ -122,8 +195,12 @@ module Rigor
         # Read first so the IoBoundary's FileEntry digest
         # captures into the descriptor before `cache_for`
         # snapshots it (the same pattern documented in
-        # rigor-routes / rigor-activerecord).
+        # rigor-routes / rigor-activerecord). Helper files are
+        # pre-read for the same reason — editing a file under
+        # `app/helpers/` MUST invalidate the helper_table cache
+        # so the new custom-helper set is picked up.
         io_boundary.read_file(@routes_file)
+        pre_read_helper_files
         @helper_table = cache_for(:helper_table, params: {}).call
       rescue Plugin::AccessDeniedError => e
         @load_error = "rigor-rails-routes: #{e.message}"

data/sig/rigor/scope.rbs

@@ -18,8 +18,22 @@ module Rigor
     attr_reader discovered_method_visibilities: Hash[String, Hash[Symbol, Symbol]]
     attr_reader discovered_superclasses: Hash[String, String]
     attr_reader discovered_includes: Hash[String, Array[String]]
+    attr_reader indexed_narrowings: Hash[IndexedKey, Type::t]
+    attr_reader method_chain_narrowings: Hash[ChainKey, Type::t]
     attr_reader source_path: String?
 
+    class IndexedKey
+      attr_reader receiver_kind: Symbol
+      attr_reader receiver_name: Symbol
+      attr_reader key: untyped
+    end
+
+    class ChainKey
+      attr_reader receiver_kind: Symbol
+      attr_reader receiver_name: Symbol
+      attr_reader method_name: Symbol
+    end
+
     def self.empty: (?environment: Environment, ?source_path: String?) -> Scope
 
     def initialize: (environment: Environment, locals: Hash[Symbol, Type::t], ?fact_store: Analysis::FactStore, ?self_type: Type::t?, ?declared_types: Hash[untyped, Type::t], ?ivars: Hash[Symbol, Type::t], ?cvars: Hash[Symbol, Type::t], ?globals: Hash[Symbol, Type::t], ?source_path: String?) -> void
@@ -44,12 +58,21 @@ module Rigor
     def with_discovered_def_nodes: (Hash[String, Hash[Symbol, untyped]] table) -> Scope
     def user_def_for: (String | Symbol class_name, String | Symbol method_name) -> untyped?
     def top_level_def_for: (String | Symbol method_name) -> untyped?
+    def toplevel?: () -> bool
     def with_discovered_method_visibilities: (Hash[String, Hash[Symbol, Symbol]] table) -> Scope
     def discovered_method_visibility: (String | Symbol class_name, String | Symbol method_name) -> Symbol?
     def superclass_of: (String | Symbol class_name) -> String?
     def with_discovered_superclasses: (Hash[String, String] table) -> Scope
     def includes_of: (String | Symbol class_name) -> Array[String]
     def with_discovered_includes: (Hash[String, Array[String]] table) -> Scope
+    def indexed_narrowing: (Symbol receiver_kind, String | Symbol receiver_name, untyped key) -> Type::t?
+    def with_indexed_narrowing: (Symbol receiver_kind, String | Symbol receiver_name, untyped key, Type::t type) -> Scope
+    def without_indexed_narrowing: (Symbol receiver_kind, String | Symbol receiver_name, untyped key) -> Scope
+    def without_indexed_narrowings_for: (Symbol receiver_kind, String | Symbol receiver_name) -> Scope
+    def method_chain_narrowing: (Symbol receiver_kind, String | Symbol receiver_name, String | Symbol method_name) -> Type::t?
+    def with_method_chain_narrowing: (Symbol receiver_kind, String | Symbol receiver_name, String | Symbol method_name, Type::t type) -> Scope
+    def without_method_chain_narrowing: (Symbol receiver_kind, String | Symbol receiver_name, String | Symbol method_name) -> Scope
+    def without_method_chain_narrowings_for: (Symbol receiver_kind, String | Symbol receiver_name) -> Scope
     def with_fact: (Analysis::FactStore::Fact fact) -> Scope
     def with_self_type: (Type::t? type) -> Scope
     def with_declared_types: (Hash[untyped, Type::t] table) -> Scope

data/skills/rigor-baseline-reduce/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: rigor-baseline-reduce
+description: |
+  Work a Rigor project's `.rigor-baseline.yml` down rule by rule: prioritise with `rigor triage`, sample call sites, classify each as real bug / stylistic-safe / false positive, then fix, `# rigor:disable`, or open a Rigor issue — and regenerate the baseline. Triggers: "reduce the rigor baseline", "fix some baseline diagnostics", "what rigor issue should I fix next?". NOT for first-time setup (use rigor-project-init) or authoring a plugin (use rigor-plugin-author).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Baseline Reduce
+
+Opportunistic, session-bounded quality improvement for a project
+that already has a `.rigor-baseline.yml`. Each session picks a rule,
+walks its sites, and lands a mix of fixes, intentional suppressions,
+and issue reports — then refreshes the baseline so the gains stick.
+
+This skill is for **users improving their own project**. It uses the
+published `rigor` executable on `PATH` and references only public CLI
+flags and config keys.
+
+## Phase 0 — When to use this skill
+
+Trigger when the user says "reduce the rigor baseline", "fix some
+baseline diagnostics", "what should I fix next in rigor?", or asks to
+work down the diagnostics a previous onboarding parenthesised.
+
+**Precondition: the project is in acknowledge mode.** This skill
+operates on a `.rigor-baseline.yml` that `.rigor.yml` /
+`.rigor.dist.yml` declares via `baseline:`. A strict-mode project
+(`severity_profile: strict`, no baseline) has nothing for this skill
+to reduce — its diagnostics are already all live; fix them as
+ordinary `rigor check` output. If no baseline exists, the user wants
+`rigor-project-init`, not this skill.
+
+Do NOT trigger for:
+
+- **First-time onboarding** — no `.rigor.yml` yet → `rigor-project-init`.
+- **Writing a plugin** for the project's DSL → `rigor-plugin-author`.
+
+## What baseline reduction is
+
+`.rigor-baseline.yml` records `(file, rule, count)` buckets — the
+diagnostics that existed when the project adopted Rigor. They are
+suppressed while their count holds. Reduction means: go through them
+deliberately, decide what each one really is, and shrink the file.
+Three outcomes per site:
+
+- **Real bug** — Rigor caught a genuine defect. Fix the code.
+- **Stylistic / safe** — the static reading is worst-case-sound but
+  the site is fine in practice (an idiom the analyzer's narrowing
+  doesn't follow, a slot the project always initialises). Mark it
+  `# rigor:disable <rule>` with intent.
+- **False positive** — Rigor is wrong; the rule should narrow
+  further. Leave it baselined and open a Rigor issue.
+
+Shrinking the baseline is progress whichever outcome applies — the
+file gets smaller, and "reduce the baseline by N this sprint" is a
+trackable goal.
+
+## Phase outline
+
+| Phase | What | Reference |
+| --- | --- | --- |
+| 1 | Prioritise — `rigor triage --format json` + `rigor baseline dump` pick the rule to work. | [`references/01-classify.md`](references/01-classify.md) |
+| 2 | Per rule: sample 3–5 sites, classify each (real bug / stylistic / FP). | [`references/01-classify.md`](references/01-classify.md) |
+| 3 | Act — fix, `# rigor:disable`, or open a Rigor issue. | [`references/02-fix-or-suppress.md`](references/02-fix-or-suppress.md) |
+| 4 | Refresh — `rigor baseline drift`, then `rigor baseline regenerate`. | [`references/02-fix-or-suppress.md`](references/02-fix-or-suppress.md) |
+
+Phases 2–4 repeat per rule until a stop condition (below) fires.
+
+## Reading order — modules
+
+| Module | Read | Covers |
+| --- | --- | --- |
+| 1 | [`references/01-classify.md`](references/01-classify.md) | **Phases 1–2.** Priority order from the `rigor triage` hints + ascending bucket count. The sample-and-classify protocol; the three-way real-bug / stylistic / FP triage and how to tell them apart. |
+| 2 | [`references/02-fix-or-suppress.md`](references/02-fix-or-suppress.md) | **Phases 3–4.** Acting on each classification — fix patterns, `# rigor:disable` placement (per-line vs per-file), FP escalation as a Rigor GitHub issue. Refreshing the baseline with `drift` + `regenerate`. |
+
+## Stop conditions
+
+End the session — do not grind indefinitely — when any of these hit:
+
+- The user signals halt.
+- The next rule's site count exceeds the session budget (default:
+  ~20 sites). A 200-site rule is systemic; escalate it as a decision
+  (below), do not walk it site by site.
+- A wall-time budget is reached (default: ~60 minutes).
+
+Always finish with Phase 4 (refresh the baseline) before stopping, so
+the landed work is recorded.
+
+## Decision points to escalate to the user
+
+- "This rule has 200 sites across 14 files — it looks systemic. A
+  plugin or an engine fix would clear them in bulk; want me to
+  investigate that instead of walking sites one by one?"
+- "This file's diagnostics would be cleaner under one per-file
+  `# rigor:disable-file <rule>` than 30 per-line comments — switch?"
+- "The diagnostic wording changed between Rigor versions and the
+  baseline no longer matches cleanly — regenerate now?"

data/skills/rigor-baseline-reduce/references/01-classify.md

@@ -0,0 +1,107 @@
+# 01 — Prioritise and classify
+
+Covers **Phase 1** (pick the rule) and **Phase 2** (sample and
+classify its sites).
+
+## Phase 1 — Pick the rule to work
+
+Do not walk the baseline top to bottom. Two commands decide the
+order; run both.
+
+### `rigor triage --format json` — the priority signal
+
+```sh
+rigor triage --format json
+```
+
+`rigor triage` runs the analysis and returns a structured summary —
+a rule `distribution`, file `hotspots`, and a `hints` catalogue. It
+is the deterministic diagnosis layer; use it rather than counting the
+raw `rigor check` stream by hand. The `hints` array is the priority
+signal — each hint has an `id`:
+
+| Hint `id` | What it means for reduction | Priority |
+| --- | --- | --- |
+| `genuine-bugs` | Low-count, scattered rules — the localised bugs Rigor caught. | **Work these first.** Highest value per fix. |
+| `systemic-file-cluster` | One file × one rule, large count. | One fix may clear many — high leverage. Or escalate as systemic. |
+| `activesupport-core-ext`, `gem-without-rbs` | Config gaps, not code bugs. | **Not reduction work** — these are `rigor-project-init` territory (wire the RBS bundle). Flag to the user; do not walk site by site. |
+| `project-monkey-patch` | A DSL / monkey-patch Rigor can't see. | Escalate — a `pre_eval:` entry or a plugin clears the whole cluster. |
+| `activerecord-relation-misinference` | Likely an engine gap. | Treat sites as candidate false positives (Phase 2). |
+
+### `rigor baseline dump --format json` — the bucket list
+
+```sh
+rigor baseline dump --format json
+```
+
+This is the authoritative list of `(file, rule, count)` buckets in
+`.rigor-baseline.yml`. Within the priority tier the triage hints set,
+**sort rules by ascending total count** — the smallest rules first.
+A rule with 3 sites is either a quick win or a contained pattern;
+either way it is finishable in one session, and finishing a rule is
+more motivating than half-clearing a 200-site one.
+
+So the working order is: rules flagged `genuine-bugs` first, then the
+rest by ascending count, with config-gap hints handed back to the
+user instead of walked.
+
+## Phase 2 — Sample and classify
+
+Pick the chosen rule. Surface its actual diagnostics — run
+`rigor check` scoped to the affected files so the user sees real
+messages, not baseline rows:
+
+```sh
+rigor check app/models/account.rb app/services/feed_service.rb
+```
+
+(The baseline still suppresses these in a full run; naming the files
+and reading the stream shows them. `--no-baseline` also works if you
+want the whole project's live stream.)
+
+From the rule's sites, **sample 3–5 distinct ones** — different
+files, different shapes, not five copies of the same line. For each
+sampled site, read the code and classify it. Ask the user to confirm
+when the call is not clear-cut.
+
+### The three classifications
+
+**Real bug** — Rigor found a genuine defect.
+
+- A `possible-nil-receiver` where the value genuinely can be `nil` on
+  some path and the code would crash.
+- An `undefined-method` that is a real typo or a removed method.
+- An argument-type mismatch that would raise or misbehave.
+- Tell: trace the value's origin and you find a path that actually
+  produces the bad case.
+
+**Stylistic / safe** — the static reading is worst-case-sound, but
+the site is fine in practice.
+
+- `T | nil` where the slot is always initialised before this point
+  by code Rigor's narrowing doesn't follow (a memoised getter, a
+  framework lifecycle guarantee).
+- A dynamic `send` over a known-finite, known-safe tag set.
+- An idiom repeated across dozens of files — at that scale the
+  pattern *is* the project's style.
+- Tell: you can articulate *why* the bad case never reaches this
+  line, and that reason is a real invariant, not a hope.
+
+**False positive** — Rigor is simply wrong; a correct analyzer would
+not flag this site.
+
+- The narrowing should have followed an `&.` chain or an early
+  `return`/`raise` guard and didn't.
+- The receiver type is misinferred (e.g. an ActiveRecord relation
+  typed as `Array`).
+- Tell: the code is correct *and* a reasonable type checker should
+  see that it is correct — the gap is in Rigor, not the code.
+
+The distinction between "stylistic / safe" and "false positive"
+matters: stylistic-safe sites get a `# rigor:disable` (the code stays
+as is, the suppression is intentional); false positives get a Rigor
+issue (the analyzer should improve). Both stay out of the count, but
+only one of them is feedback Rigor's maintainers can act on.
+
+Carry the per-site classifications into Phase 3
+([`02-fix-or-suppress.md`](02-fix-or-suppress.md)).

data/skills/rigor-baseline-reduce/references/02-fix-or-suppress.md

@@ -0,0 +1,133 @@
+# 02 — Act on the classification, then refresh
+
+Covers **Phase 3** (act per site) and **Phase 4** (refresh the
+baseline). Input: the per-site classifications from
+[`01-classify.md`](01-classify.md).
+
+## Phase 3 — Act
+
+### Real bug → fix the code
+
+Propose the fix and offer to apply it. The fix is ordinary code work
+— the value is that Rigor surfaced a defect that was latent because
+the line is rarely exercised. Common shapes:
+
+- `possible-nil-receiver` → add the missing guard (`return unless x`,
+  `x&.method`, an early raise), or fix the upstream code so the value
+  is never `nil` here.
+- `undefined-method` typo → correct the method name.
+- argument-type mismatch → pass the right type, or fix the signature.
+
+After a real-bug fix the diagnostic is *gone*, not suppressed — the
+bucket count drops on its own.
+
+### Stylistic / safe → `# rigor:disable` with intent
+
+The code is staying as it is; the suppression is a deliberate,
+recorded decision. Place a per-line comment at the end of the
+offending line:
+
+```ruby
+config.fetch(:timeout)  # rigor:disable call.possible-nil-receiver — set in initializer
+```
+
+Placement rules:
+
+- **Per-line `# rigor:disable <rule>`** is the default. It keeps the
+  suppression visible exactly where it applies, and a future reader
+  sees the intent. Always name the specific rule, never `all`.
+- Add a short reason after the rule — *why* the site is safe. A bare
+  `# rigor:disable` rots; `# rigor:disable … — set in initializer`
+  survives review.
+- **Per-file `# rigor:disable-file <rule>`** only when one file has
+  many sites of the same rule and they are all the same safe idiom.
+  Escalate this to the user as a decision (it is coarser — it also
+  silences *future* sites of that rule in the file).
+
+A `# rigor:disable`d diagnostic is suppressed *before* the baseline
+filter, so once the comment is in place the site no longer counts
+toward its bucket.
+
+### False positive → open a Rigor issue
+
+Leave the site baselined (do not `# rigor:disable` it — that would
+imply the code is the thing to live with, when actually Rigor is).
+Open an issue on the Rigor project:
+
+<https://github.com/rigortype/rigor/issues>
+
+A useful issue includes:
+
+- The rule id and the exact diagnostic message.
+- A **minimal** code snippet that reproduces the false positive —
+  reduce it to the smallest shape that still mis-fires.
+- What the correct inference should be, and why.
+- The `rigor version` output.
+
+This is the feedback loop that makes the analyzer better — a false
+positive reported with a minimal repro is far more actionable than
+one buried in a baseline. While the issue is open the baseline keeps
+the site quiet.
+
+## Phase 4 — Refresh the baseline
+
+After working a rule (fixes applied, `# rigor:disable` comments
+added, issues filed), the live diagnostic count for the touched
+buckets has dropped below the recorded count. Make the baseline
+reflect reality.
+
+First, inspect the drift:
+
+```sh
+rigor baseline drift
+```
+
+This reports each bucket as `within` / `over` / `cleared` /
+`reducible`. After a reduction session you expect `cleared` (the
+bucket is now empty) and `reducible` (the bucket shrank but is not
+empty) rows.
+
+Then refresh:
+
+```sh
+rigor baseline regenerate
+```
+
+`regenerate` rewrites `.rigor-baseline.yml` from a fresh `rigor
+check` run — cleared buckets disappear, reducible buckets get their
+new lower counts. This is the command that *banks* the session's
+gains: until you regenerate, the baseline still records the old,
+higher numbers.
+
+`rigor baseline prune` is the narrower tool — it drops only the
+fully-`cleared` buckets and leaves reducible ones at their old count.
+Prefer `regenerate` at the end of a reduction session; it captures
+both kinds of progress in one step.
+
+Commit the updated `.rigor-baseline.yml` together with the code
+fixes and `# rigor:disable` comments, so the smaller baseline and the
+work that earned it land together.
+
+## Verifying the session
+
+Confirm the gains held:
+
+```sh
+rigor baseline drift   # expect "No drift detected" after regenerate
+rigor check            # the project's gate — should still pass
+```
+
+If the project's CI uses `rigor check --baseline-strict`, the run
+after `regenerate` should be clean — a stale baseline (numbers not
+refreshed) is exactly the deficit drift that gate fails on.
+
+## Output of this module — session complete
+
+- Code fixes for the real bugs.
+- Intentional, reasoned `# rigor:disable` comments for the
+  stylistic-safe sites.
+- Rigor issues filed for the false positives.
+- A regenerated, smaller `.rigor-baseline.yml`, committed with the
+  work.
+
+Run the skill again next session to take the next rule.

data/skills/rigor-plugin-author/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: rigor-plugin-author
+description: |
+  Author a Rigor plugin in your own repository — a standalone rigor-prefixed gem or a project-private plugin — to teach Rigor about an application DSL, framework, or metaprogramming pattern. Covers gemspec / Gemfile wiring, the plugin class and AST walker, return-type contributions, fixture-based testing (RSpec or Minitest), and version pinning against the pre-1.0 plugin contract. Triggers: "write a Rigor plugin for our DSL", "extend Rigor for X in this project", "make Rigor understand our macro". NOT for onboarding a project (use rigor-project-init) or reducing a baseline (use rigor-baseline-reduce).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Plugin Author (external)
+
+Author a Rigor plugin **in your own repository** — to teach Rigor a
+DSL, framework convention, or metaprogramming pattern its core
+analyzer cannot follow. The result is either a standalone
+`rigor-<id>` gem or a project-private plugin.
+
+This skill targets **external authors**: you depend on the published
+`rigortype` gem (`bundle add rigortype`) and use the public plugin
+API surface — `Rigor::Plugin::Base` and friends. It does not assume
+the rigor monorepo's `Makefile`, `spec/integration/` helpers, or Nix
+environment.
+
+> **Authoring inside the rigor monorepo instead?** If you are adding
+> a plugin to rigor's own `plugins/` or `examples/` tree, use the
+> contributor `rigor-plugin-author` skill bundled in that repo — it
+> covers the in-repo layout, `plugin_helpers.rb`, and `make verify`.
+> This skill is for plugins that live in *your* project.
+
+## Important — the plugin contract is a preview (pre-1.0)
+
+Rigor's plugin contract (ADR-2) is **not yet frozen**. It stabilises
+at `rigortype` v0.2.0. Until then, treat each `rigortype` minor
+release as potentially contract-changing:
+
+- **Pin `rigortype` tightly** — `>= 0.1.0, < 0.2.0` in your gemspec
+  or Gemfile. Do not float across the v0.2.0 boundary blind.
+- Expect to **revisit your plugin** when you bump `rigortype` to the
+  next minor. The walker hook signature, the `Diagnostic` shape, and
+  the type carriers may shift.
+- After v0.2.0 the contract is stable and ordinary semver applies.
+
+Tell the user this up front. A plugin written today is a preview
+artefact, valuable but not yet on a stable foundation.
+
+## Phase 0 — Standalone gem or project-private?
+
+Decide where the plugin lives before scaffolding anything.
+
+| Signal | Build it as |
+| --- | --- |
+| The DSL/library is reusable across projects, or you want to publish it | **Standalone `rigor-<id>` gem** — own repo, own gemspec, RubyGems-publishable |
+| The pattern is specific to *one* application's own code / in-house DSL | **Project-private plugin** — lives inside the app repo, never published |
+
+Both produce the same plugin class and walker; they differ only in
+packaging and activation (Phase 1). When unsure, default to
+**project-private** — it is less ceremony, and a plugin can always
+be extracted into a gem later.
+
+Do NOT use this skill for:
+
+- **Onboarding a project to Rigor** (writing `.rigor.yml`, choosing
+  plugins) → `rigor-project-init`.
+- **Reducing a baseline** → `rigor-baseline-reduce`.
+- **Editing an existing, already-working plugin** — that is ordinary
+  code work; modify the plugin class directly.
+
+## How a plugin works — the one-paragraph model
+
+A Rigor plugin is a Ruby class that subclasses `Rigor::Plugin::Base`,
+declares a `manifest(id:, version:, …)`, and calls
+`Rigor::Plugin.register(self)` at load time. When `.rigor.yml` lists
+the plugin under `plugins:`, Rigor `require`s it and, for every
+analysed file, calls the plugin's `#diagnostics_for_file(path:,
+scope:, root:)` — handing it the file's Prism AST (`root`) and a
+`scope` it can query for inferred types. The plugin walks the AST and
+returns an array of `Rigor::Analysis::Diagnostic`. Optionally it also
+implements `#flow_contribution_for(call_node:, scope:)` to *supply* a
+return type for call sites the core analyzer types as `Dynamic`.
+
+## Phase outline
+
+| Phase | What | Reference |
+| --- | --- | --- |
+| 1 | Package and scaffold — gem vs project-private layout, gemspec / Gemfile, the plugin class skeleton, `.rigor.yml` activation. | [`references/01-plan-and-scaffold.md`](references/01-plan-and-scaffold.md) |
+| 2 | The walker — `diagnostics_for_file`, building `Diagnostic`s, querying `scope.type_of`, optional `flow_contribution_for`, RBS for the DSL. | [`references/02-walker-and-types.md`](references/02-walker-and-types.md) |
+| 3 | Test and ship — fixture-based tests (RSpec / Minitest, no rigor internals), version pinning, README, publish or keep private. | [`references/03-test-and-ship.md`](references/03-test-and-ship.md) |
+
+## Reading order — modules
+
+| Module | Read | Covers |
+| --- | --- | --- |
+| 1 | [`references/01-plan-and-scaffold.md`](references/01-plan-and-scaffold.md) | **Phase 1.** The gem vs project-private packaging split, directory trees for both, gemspec template, project-private path-gem / `RUBYLIB` activation, the `Rigor::Plugin::Base` skeleton, `.rigor.yml` `plugins:` wiring. |
+| 2 | [`references/02-walker-and-types.md`](references/02-walker-and-types.md) | **Phase 2.** The `diagnostics_for_file` AST walk over Prism nodes, the `Diagnostic` constructor shape, asking the analyzer for inferred types via `scope.type_of`, the optional `flow_contribution_for` return-type hook, and shipping `sig/*.rbs` so the DSL's types are visible. |
+| 3 | [`references/03-test-and-ship.md`](references/03-test-and-ship.md) | **Phase 3.** Testing a plugin from outside the monorepo — fixture projects driven through `rigor check --format json`, plus pure unit tests of dispatch tables — with RSpec or Minitest. Version pinning against the pre-1.0 contract. README. Publishing to RubyGems or keeping the plugin private. |