rigortype 0.1.12 → 0.1.14

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. |

data/skills/rigor-plugin-author/references/01-plan-and-scaffold.md

@@ -0,0 +1,195 @@
+# 01 — Package and scaffold
+
+Covers **Phase 1**. Output: a directory tree, a plugin class
+skeleton that registers itself, and an `.rigor.yml` that activates
+it.
+
+## Naming
+
+- **Plugin id** — kebab-case, starts with a letter, matches
+  `/\A[a-z][a-z0-9._-]*\z/`. Descriptive: `units`, `myapp-dsl`,
+  `legacy-macros`.
+- **Require name** — Rigor activates a plugin by `require`-ing the
+  name in the `.rigor.yml` `plugins:` entry. The convention is
+  `rigor-<id>`, and the file that name resolves to must, when
+  loaded, call `Rigor::Plugin.register`.
+- **Ruby class** — CamelCase under `Rigor::Plugin`, e.g.
+  `Rigor::Plugin::MyappDsl`.
+
+## Standalone gem layout
+
+```text
+rigor-<id>/                      # its own repository
+├── README.md
+├── rigor-<id>.gemspec
+├── Gemfile                      # gem "rigortype" (dev); gemspec
+├── lib/
+│   ├── rigor-<id>.rb            # require name → require_relative the class
+│   └── rigor/plugin/
+│       └── <id>.rb              # the plugin class + Rigor::Plugin.register
+│       └── <id>/                # only if it needs helpers
+│           └── analyzer.rb      # AST walker extracted out of the class
+├── sig/                         # optional — RBS for the DSL (Phase 2)
+└── spec/  or  test/             # fixture tests (Phase 3)
+```
+
+### Gemspec template
+
+```ruby
+# rigor-<id>.gemspec
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name        = "rigor-<id>"
+  spec.version     = "0.1.0"
+  spec.authors     = ["Your Name"]
+  spec.summary     = "Rigor plugin: <one line>."
+  spec.description = "<two sentences naming the DSL / API the plugin types>."
+  spec.license     = "MIT"        # your choice
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.files        = Dir.glob(%w[README.md lib/**/*.rb sig/**/*.rbs])
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "prism", ">= 1.0", "< 2.0"
+  # Pin tightly — the plugin contract is pre-1.0 (see SKILL.md).
+  spec.add_dependency "rigortype", ">= 0.1.0", "< 0.2.0"
+end
+```
+
+`prism` is Rigor's parser; a plugin walks `Prism::Node`s, so depend
+on it directly.
+
+## Project-private layout
+
+A project-private plugin lives inside the application repo and is
+never published. Two ways to make `require "rigor-<id>"` succeed:
+
+### Recommended — a path gem
+
+Keep the plugin in a subdirectory with its own gemspec, and reference
+it from the app's `Gemfile` by path:
+
+```text
+your-app/
+├── Gemfile
+├── rigor-plugin/                # the plugin, unpublished
+│   ├── rigor-myapp.gemspec
+│   └── lib/
+│       ├── rigor-myapp.rb
+│       └── rigor/plugin/myapp.rb
+└── .rigor.yml
+```
+
+```ruby
+# your-app/Gemfile
+gem "rigortype", "~> 0.1.0"
+gem "rigor-myapp", path: "rigor-plugin"
+```
+
+`bundle install` then puts `rigor-myapp` on the load path, so Rigor's
+`require "rigor-myapp"` resolves. This keeps the plugin versioned,
+testable, and trivially promotable to a real gem later.
+
+### Simplest — a bare file on the load path
+
+If you do not want a gemspec at all, drop `rigor-myapp.rb` somewhere
+and run `rigor` with that directory on `RUBYLIB`:
+
+```text
+your-app/rigor-ext/rigor-myapp.rb     # requires the plugin class
+```
+
+```sh
+RUBYLIB=rigor-ext rigor check
+```
+
+Workable, but the `RUBYLIB` has to be set on every invocation (CI
+included). Prefer the path gem unless the plugin is a throwaway.
+
+## The plugin class skeleton
+
+`lib/rigor-<id>.rb` — the require entry point:
+
+```ruby
+# frozen_string_literal: true
+
+require_relative "rigor/plugin/<id>"
+```
+
+`lib/rigor/plugin/<id>.rb` — the plugin class:
+
+```ruby
+# frozen_string_literal: true
+
+require "rigor/plugin"
+
+module Rigor
+  module Plugin
+    class MyappDsl < Rigor::Plugin::Base
+      manifest(
+        id: "<id>",
+        version: "0.1.0",
+        description: "<one line>",
+        # Optional: declare config keys the user may set under
+        # `.rigor.yml` plugins: [{ gem:, config: { … } }].
+        config_schema: {
+          # "module_name" => :string,
+          # "rules"       => :array,
+        }
+      )
+
+      # Called once at load time with the service container.
+      # Read config defaults here. `config` is the validated
+      # user config Hash.
+      def init(_services)
+        @module_name = config.fetch("module_name", "Default")
+      end
+
+      # Called per analysed file. `root` is the file's Prism AST,
+      # `scope` answers inferred-type queries. Return an Array of
+      # Rigor::Analysis::Diagnostic. See 02-walker-and-types.md.
+      def diagnostics_for_file(path:, scope:, root:)
+        []
+      end
+    end
+
+    Rigor::Plugin.register(MyappDsl)
+  end
+end
+```
+
+`Rigor::Plugin.register` at the bottom is mandatory — the loader
+`require`s the gem, then looks for a freshly-registered plugin
+class. A gem that registers nothing fails to load with a clear
+error.
+
+## Activate the plugin in `.rigor.yml`
+
+```yaml
+plugins:
+  - rigor-<id>
+
+# Hash form when the plugin takes config:
+# plugins:
+#   - gem: rigor-<id>
+#     config:
+#       module_name: MyApp
+```
+
+Confirm activation with the public CLI:
+
+```sh
+rigor check
+```
+
+A misconfigured plugin surfaces as a `plugin-loader` diagnostic
+rather than crashing the run — read that message if the plugin seems
+inert.
+
+## Output of this module
+
+A scaffolded plugin that loads (even if `diagnostics_for_file` still
+returns `[]`) and is activated in `.rigor.yml`. Proceed to Phase 2
+([`02-walker-and-types.md`](02-walker-and-types.md)) to make it
+actually analyse.