rigortype 0.2.5 → 0.2.7

data/skills/rigor-editor-setup/SKILL.md

@@ -29,6 +29,20 @@ This skill is the *workflow* around it (identify the editor → apply the
 manual's snippet → verify), so it does not duplicate (and cannot
 stale-out) the config details.
 
+## First: load the version-current copy
+
+The config details already come live from `rigor docs`; this section keeps
+the *workflow itself* current too. Prefer the copy of this skill that ships
+with the **installed** Rigor over any vendored or frozen copy of this file:
+
+```sh
+rigor skill --full rigor-editor-setup
+```
+
+If you already loaded this skill *via* `rigor skill` you have the current
+copy — just proceed. If `rigor` is not on `PATH`, this task needs it: run
+**`rigor-next-steps`** to install Rigor first, then come back.
+
 ## When to use
 
 - A developer wants Rigor feedback live in their editor, not just from

data/skills/rigor-mcp-setup/SKILL.md

@@ -31,6 +31,20 @@ This skill is the *workflow* around it (identify the client → apply the
 manual's snippet → verify the handshake), so it does not duplicate (and
 cannot stale-out) the config details.
 
+## First: load the version-current copy
+
+The config details already come live from `rigor docs`; this keeps the
+*workflow itself* current too. Prefer the copy of this skill that ships
+with the **installed** Rigor over any vendored or frozen copy of this file:
+
+```sh
+rigor skill --full rigor-mcp-setup
+```
+
+If you already loaded this skill *via* `rigor skill` you have the current
+copy — just proceed. If `rigor` is not on `PATH`, this task needs it: run
+**`rigor-next-steps`** to install Rigor first, then come back.
+
 ## When to use
 
 - A developer wants their AI agent to call Rigor's tools mid-session.

data/skills/rigor-monkeypatch-resolve/SKILL.md

@@ -18,6 +18,21 @@ top-level helper). `pre_eval:` ([ADR-17](https://github.com/rigortype/rigor/blob
 fixes this: it pre-evaluates the listed project files and registers every
 method they define with a **literal** `def` / `def self.`.
 
+## First: load the version-current copy
+
+This skill's exact commands, flags, and config keys drift between Rigor
+releases, so follow the copy that ships with the **installed** Rigor rather
+than any vendored or frozen copy of this file. Get the complete current
+procedure in one call:
+
+```sh
+rigor skill --full rigor-monkeypatch-resolve
+```
+
+If you already loaded this skill *via* `rigor skill` you have the current
+copy — just proceed. If `rigor` is not on `PATH`, this task needs it: run
+**`rigor-next-steps`** to install Rigor first, then come back.
+
 ## When to use
 
 - `rigor triage` shows a cluster of `call.undefined-method` /

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

@@ -27,6 +27,22 @@ environment.
 > covers the in-repo layout, `plugin_helpers.rb`, and `make verify`.
 > This skill is for plugins that live in *your* project.
 
+## First: load the version-current copy
+
+The plugin contract is pre-1.0 and moving (see the next section), so this
+skill's step detail — in its `references/` files — is exactly the kind that
+drifts between releases. Follow the copy that ships with the **installed**
+Rigor rather than any vendored or frozen copy of this file. Get the complete
+current procedure (body + all references, inline) in one call:
+
+```sh
+rigor skill --full rigor-plugin-author
+```
+
+If you already loaded this skill *via* `rigor skill` you have the current
+copy — just proceed. If the `rigor` command is not available, run
+**`rigor-next-steps`** to install Rigor first, then come back.
+
 ## Important — the plugin contract is a preview (pre-1.0)
 
 Rigor's plugin contract (ADR-2) is **not yet frozen**. It stabilises
@@ -97,19 +113,22 @@ AST walk per file — hands every matching node to the block along with a
 `scope` it can query for inferred types. The block returns an array of
 `Rigor::Analysis::Diagnostic` (built via the `diagnostic` helper).
 Optionally the plugin also declares `dynamic_return(receivers:)` /
-`type_specifier(methods:)` to *supply* a return type or narrowing facts
-for call sites the core analyzer types as `Dynamic`. `#diagnostics_for_file`
+`narrowing_facts(methods:)` to *supply* a return type or narrowing facts
+for call sites the core analyzer types as `Dynamic`. (`narrowing_facts`
+was renamed from `type_specifier` in ADR-80; `type_specifier` remains as a
+deprecating alias removed in 0.3.0 — use `narrowing_facts` in new plugins.)
+`#diagnostics_for_file`
 is the file-rule surface for whole-file diagnostics a per-node walk can't
 express. (`flow_contribution_for` was removed pre-1.0 in ADR-52 WD3 —
 defining it now raises `ArgumentError`; use `dynamic_return` /
-`type_specifier`. See Phase 2.)
+`narrowing_facts`. See Phase 2.)
 
 ## 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 | Node rules — `node_rule` (engine-owned walk), building `Diagnostic`s via `Base#diagnostic`, querying `scope.type_of`, calling the target library directly instead of reimplementing it (ADR-39: `Plugin::Inflector`, `Base.suggest`), optional `dynamic_return` / `type_specifier`, RBS for the DSL. | [`references/02-walker-and-types.md`](references/02-walker-and-types.md) |
+| 2 | Node rules — `node_rule` (engine-owned walk), building `Diagnostic`s via `Base#diagnostic`, querying `scope.type_of`, calling the target library directly instead of reimplementing it (ADR-39: `Plugin::Inflector`, `Base.suggest`), optional `dynamic_return` / `narrowing_facts`, 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
@@ -117,5 +136,5 @@ defining it now raises `ArgumentError`; use `dynamic_return` /
 | 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 `node_rule` engine-owned AST walk over Prism nodes, the `Base#diagnostic` helper, asking the analyzer for inferred types via `scope.type_of`, two-pass / lexical context (`node_file_context` / `NodeContext`), the optional `dynamic_return` / `type_specifier` return-type hooks (`flow_contribution_for` was removed pre-1.0 in ADR-52 WD3), calling the target library's pure methods directly rather than reimplementing them (ADR-39: `Plugin::Inflector` over the real `ActiveSupport::Inflector`; `Base.suggest` for did-you-mean), and shipping `sig/*.rbs` so the DSL's types are visible. |
+| 2 | [`references/02-walker-and-types.md`](references/02-walker-and-types.md) | **Phase 2.** The `node_rule` engine-owned AST walk over Prism nodes, the `Base#diagnostic` helper, asking the analyzer for inferred types via `scope.type_of`, two-pass / lexical context (`node_file_context` / `NodeContext`), the optional `dynamic_return` / `narrowing_facts` return-type hooks (`narrowing_facts` was renamed from `type_specifier` in ADR-80, alias removed in 0.3.0; `flow_contribution_for` was removed pre-1.0 in ADR-52 WD3), calling the target library's pure methods directly rather than reimplementing them (ADR-39: `Plugin::Inflector` over the real `ActiveSupport::Inflector`; `Base.suggest` for did-you-mean), 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/02-walker-and-types.md

@@ -162,7 +162,7 @@ rather than hand-rolling Levenshtein:
 Rigor::Plugin::Base.suggest(typo, known_names)  # nearest match, or nil
 ```
 
-## Optional — contribute a return type with `dynamic_return` / `type_specifier`
+## Optional — contribute a return type with `dynamic_return` / `narrowing_facts`
 
 > **Critical — these hooks do NOT make a method "defined", so they do
 > NOT suppress `call.undefined-method`.** Method *existence* and call
@@ -197,11 +197,15 @@ end
 # Post-return NARROWING FACTS, gated on the call's method name.
 # Return an Array of facts (or nil). Used for assertion / predicate
 # narrowing (`assert_kind_of(Foo, x)` ⇒ x is Foo afterwards).
-type_specifier methods: [:assert_kind_of] do |call_node, scope|
+narrowing_facts methods: [:assert_kind_of] do |call_node, scope|
   # ... build and return the post-return facts ...
 end
 ```
 
+> **`narrowing_facts` was renamed from `type_specifier` in ADR-80.**
+> `type_specifier` remains as a deprecating alias, removed in 0.3.0 — use
+> `narrowing_facts` in new plugins.
+
 Build return types with `Rigor::Type::Combinator`:
 
 ```ruby
@@ -240,7 +244,7 @@ If the DSL introduces methods or classes that Rigor cannot see (a
 Rigor RBS declaring them so *core* inference — not just your plugin —
 treats them as **defined**. This is what removes the
 `call.undefined-method` diagnostics on those methods; nothing else
-(not a `node_rule`, not `dynamic_return` / `type_specifier`) makes a
+(not a `node_rule`, not `dynamic_return` / `narrowing_facts`) makes a
 method exist in Rigor's view.
 
 Two ways to wire the RBS, depending on how the plugin is packaged:
@@ -288,6 +292,6 @@ They compose — many plugins ship both.
 
 A plugin whose `node_rule`(s) recognise the DSL and emit diagnostics
 with correct severities and rule ids — optionally a `dynamic_return` /
-`type_specifier` and a `sig/` bundle. Verify by eye with `rigor check`;
+`narrowing_facts` and a `sig/` bundle. Verify by eye with `rigor check`;
 lock it down with tests in Phase 3
 ([`03-test-and-ship.md`](03-test-and-ship.md)).

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

@@ -0,0 +1,174 @@
+---
+name: rigor-plugin-review
+description: |
+  Review an existing Rigor plugin's source against the current authoring contract and produce a prioritized upgrade path — the modernization counterpart to rigor-plugin-author. Audits config-default declaration (ADR-40), the AST-walk model (node_rule vs a hand-rolled traversal), return-type / narrowing hooks (dynamic_return / narrowing_facts, not the removed flow_contribution_for or deprecated type_specifier), the ADR-60 WD4 authoring helpers (diagnostic / diagnostics_for / suggest / producer_value / read_fact), engine-collaboration vs reimplementation, cache-producer soundness, manifest-field hygiene, and doc freshness. Triggers: "review this Rigor plugin", "does my plugin follow best practices", "upgrade our rigor-prefixed plugin to the latest contract", "modernize this plugin", "is this plugin using the current API". NOT for authoring a new plugin (use rigor-plugin-author), enabling bundled plugins on a project (use rigor-plugin-tune), or tuning plugin config.
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Plugin Review
+
+Audit an **existing** Rigor plugin — a bundled one in the rigor
+monorepo (`plugins/` or `examples/`), or your own `rigor-<id>` gem —
+against the current `Rigor::Plugin::Base` authoring contract, and hand
+back a **prioritized upgrade path**. This is the review / upgrade
+counterpart to `rigor-plugin-author` (which creates new plugins).
+
+Plugins written before a contract addition keep working — the gate is
+compatibility, not currency — but they drift from the idiom other
+authors copy. The commonest drift, in rough order of how often it
+appears:
+
+1. **Config defaults** declared with a `DEFAULT_*` constant +
+   `config.fetch(k, DEFAULT)` instead of `config_schema {kind:,
+   default:}` (ADR-40).
+2. **Hand-rolled boilerplate** the ADR-60 WD4 authoring helpers now
+   own — a Levenshtein "did you mean", a `@table`/`@load_error` memo +
+   rescue, a `Diagnostic.new` where a node exists.
+3. **A hand-rolled AST walk** where the engine-owned `node_rule` now
+   fits (ADR-37 / ADR-52).
+4. **Removed / renamed hooks** still named — `flow_contribution_for`
+   (deleted, ADR-52 WD3) or `type_specifier` (deprecated alias for
+   `narrowing_facts`, ADR-80).
+5. **Stale docs** — archaeology about deleted hooks, pinned version
+   references that no longer mean anything.
+
+## First: load the version-current copy
+
+This skill audits against a contract that moves release to release (hook
+renames, new helpers, deprecations), so its checklist — in its
+`references/` files — is only as good as the Rigor it ships with. Follow
+the copy that ships with the **installed** Rigor rather than any vendored
+or frozen copy of this file. Get the complete current procedure (body + all
+references, inline) in one call:
+
+```sh
+rigor skill --full rigor-plugin-review
+```
+
+If you already loaded this skill *via* `rigor skill` you have the current
+copy — just proceed. If `rigor` is not on `PATH`, this task needs it: run
+**`rigor-next-steps`** to install Rigor first, then come back.
+
+## When to use / not use
+
+**Use it** when someone asks to review a plugin's quality, check it
+against best practices, or upgrade it to the current contract — whether
+it lives in the rigor monorepo or in an external repo.
+
+**Do not use it** for:
+
+- **Authoring a new plugin** → `rigor-plugin-author`.
+- **Choosing / enabling bundled plugins on a project** →
+  `rigor-plugin-tune`.
+- **A behavioural bug in a plugin** — that is ordinary debugging, not a
+  contract-conformance pass.
+
+## Read the plugin — and read the contract
+
+Rigor is installed on disk, so both the plugin under review and the
+worked-example plugins are readable source:
+
+```sh
+rigor plugin list                 # every bundled + example plugin, with paths
+rigor plugin print rigor-<id>     # a plugin's main source, inline
+rigor plugin path  rigor-<id>     # its directory, to browse
+```
+
+The **authoritative** authoring surface — the one this review scores
+against — is the internal spec, not this file:
+
+- [`docs/internal-spec/plugin.md`](https://github.com/rigortype/rigor/blob/master/docs/internal-spec/plugin.md)
+  — manifest, `node_rule` / `node_file_context`, `dynamic_return` /
+  `narrowing_facts`, the `#diagnostic` / `#diagnostics_for` / `.suggest`
+  / `#read_fact` author helpers, `config_schema` `{kind:, default:}`.
+- [`docs/internal-spec/plugin-cache-producers.md`](https://github.com/rigortype/rigor/blob/master/docs/internal-spec/plugin-cache-producers.md)
+  — `producer` / `#cache_for` / `#producer_value` / `#producer_error`,
+  ADR-60 WD3 record-and-validate.
+- [`docs/internal-spec/plugin-trust.md`](https://github.com/rigortype/rigor/blob/master/docs/internal-spec/plugin-trust.md)
+  — `TrustPolicy` / `IoBoundary`.
+
+When the checklist below and the spec disagree, **the spec binds** —
+it tracks the installed `rigor` version; this skill is a snapshot.
+
+## Procedure
+
+### Phase 1 — Inventory
+
+Read the plugin's `lib/**/*.rb`, its `README.md`, and its integration /
+unit spec. Note: the `manifest(...)` block, every `config.fetch` /
+`DEFAULT_*` constant, every `Rigor::Analysis::Diagnostic.new`, any
+hand-rolled `levenshtein` / `each_child` walk / cross-plugin `@*_resolved`
+flag, and every mention of `flow_contribution_for` / `type_specifier`.
+
+### Phase 2 — Score against the checklist
+
+Walk [`references/01-best-practices-checklist.md`](references/01-best-practices-checklist.md)
+concern by concern. For each finding, record: the smell, the modern
+replacement, the authoritative citation, and — critically — whether the
+change is **mechanical** (byte-identical diagnostics expected) or
+**design-level** (needs judgment / may change behaviour).
+
+### Phase 3 — Establish the oracle BEFORE changing anything
+
+The plugin's integration spec is the contract you must preserve. Run it
+green first, so you can prove each later step is a faithful refactor:
+
+```sh
+# external gem:
+bundle exec rspec spec/
+# in the rigor monorepo:
+nix … develop --command bundle exec rspec spec/integration/<plugins|examples>/<id>_plugin_spec.rb
+```
+
+If there is no spec, **write one first** (per `rigor-plugin-author`
+Phase 3) — a modernization with no oracle is a guess.
+
+### Phase 4 — Apply the upgrade path, mechanical first
+
+Order the work low-risk → high-risk, and **re-run the spec after every
+step**:
+
+1. **Mechanical (expect byte-identical diagnostics):** ADR-40 config
+   defaults · helper swaps (`suggest` / `producer_value` / `diagnostic`
+   / `diagnostics_for` / `read_fact`) · manifest-field renames (ADR-60
+   WD1/WD2) · doc freshness. A spec that changes here means the swap was
+   not faithful — fix it, do not re-baseline.
+2. **Design-level (may change behaviour — validate empirically):** an
+   AST-walk migration onto `node_rule`; an engine-collaboration refactor
+   that reads `Scope#type_of` instead of a hand-rolled binding map.
+   **Do not delete hand-rolled state before proving the engine gives you
+   the same information** — see the `rigor-units` trap in the checklist
+   (the diagnostics-side `Scope` is a *seed entry scope* without
+   flow-accumulated local bindings, so a cross-statement binding map can
+   be necessary, not redundant).
+
+### Phase 5 — Verify
+
+```sh
+rigor check <plugin>/lib        # ADR-43 contract self-check — MUST be clean
+rigor plugins --strict          # the plugin still loads
+rigor plugins --capabilities    # node-rule types / dynamic_return receivers look right
+bundle exec rspec …             # the oracle spec, still green
+```
+
+In the **rigor monorepo**, the gate is `make check-plugins` (runs
+`rigor check` over every `plugins/*/lib` + `examples/*/lib`) plus
+`make verify`; land the change as its own commit(s) with the spec as
+the byte-identical gate.
+
+## Output
+
+Hand the user a table — smell → replacement → authority → mechanical /
+design — ranked so the mechanical, oracle-gated wins land first, and
+call out any finding (like the units binding-map case) where the
+"obvious" modernization is actually wrong. If nothing is stale, say so
+plainly: a plugin that already tracks the current contract is a pass,
+not an occasion to invent churn.
+
+## Next step
+
+Re-run `rigor skill describe` for the next move, or `rigor-plugin-author`
+if the review surfaced a *new* capability the plugin should grow.

data/skills/rigor-plugin-review/references/01-best-practices-checklist.md

@@ -0,0 +1,214 @@
+# Plugin best-practices checklist
+
+Score a plugin concern by concern. Each row is **smell → modern
+replacement → authority**. The authority column names the binding
+surface (`docs/internal-spec/*` or the ADR); when it disagrees with
+this file, it wins.
+
+`M` = mechanical (byte-identical diagnostics expected; oracle-gated).
+`D` = design-level (may change behaviour; validate empirically).
+
+---
+
+## 1. Manifest & config defaults (ADR-40) — `M`
+
+**Smell:**
+
+```ruby
+DEFAULT_ROUTES_FILE = "config/routes.yml"
+config_schema: { "routes_file" => :string }
+# …
+@routes_file = config.fetch("routes_file", DEFAULT_ROUTES_FILE)
+```
+
+**Modern:**
+
+```ruby
+config_schema: { "routes_file" => { kind: :string, default: "config/routes.yml" } }
+# …
+@routes_file = config["routes_file"]   # default merged under user config
+```
+
+`Base#config` merges `manifest.config_defaults` beneath the user config,
+so the plugin reads the key directly and the `DEFAULT_*` constant goes
+away. Keep a constant only where a value needs *validation the merged
+default cannot express* (e.g. an allow-listed `severity` that must fall
+back when a user supplies a bad value).
+
+**Authority:** `docs/internal-spec/plugin.md` § "Declared config
+defaults — `config_schema` `{ kind:, default: }`".
+
+---
+
+## 2. AST-walk ownership (ADR-37 / ADR-52) — `D`
+
+**Smell:** a hand-rolled traversal for per-node checks —
+`root.compact_child_nodes.each { … }`, a bespoke `Walker` that recurses
+the tree, or a `#diagnostics_for_file` that re-walks to find call sites.
+
+**Modern:** declare `node_rule(Prism::CallNode) { |node, scope, path| … }`
+and let the engine own the single per-file walk. For a two-pass
+(collect-then-validate) plugin, add `node_file_context { |root, scope| … }`
+— it runs once before the node rules and threads a file-local value in
+as the rule block's fourth argument.
+
+**Keep `#diagnostics_for_file`** only for genuinely whole-file
+diagnostics a per-node walk cannot express — see concern 5 for the case
+where a stateful whole-file walk is *required*, not lazy.
+
+**"Genuinely whole-file" is a sharp line — apply it, don't defer to
+precedent.** A per-*class* or per-*def* contract check (does this class
+define `#get`? does its body return the contracted type?) IS
+node-expressible — migrate it to `node_rule(Prism::ClassNode)` /
+`node_rule(Prism::DefNode)`, even if a shipped production plugin still
+uses `#diagnostics_for_file` + a hand-rolled `class_nodes` walk for the
+same job (`rigor-hanami`'s ADR-28 check half does — an equivalent,
+older shape, not a reason to keep a new copy hand-rolled). The genuine
+whole-file case is a diagnostic whose *identity or count is not tied to
+any one node* — e.g. `rigor-routes`'s "routes file failed to load"
+warning, which must fire exactly once per file (or run) even on a file
+with zero matching nodes. That cannot be a node rule; a per-class check
+can.
+
+**Authority:** `docs/internal-spec/plugin.md` §§ "Node-scoped rules —
+`node_rule`", "`node_file_context`".
+
+---
+
+## 3. Return-type & narrowing hooks (ADR-37 / ADR-52 / ADR-80) — `M`/`D`
+
+**Smell:** `flow_contribution_for` (deleted in ADR-52 WD3 — *defining it
+now raises `ArgumentError`*), or `type_specifier` (the pre-ADR-80 name).
+
+**Modern:** `dynamic_return(receivers:/methods:/file_methods:)` to
+*supply* a return type, `narrowing_facts(methods:)` to supply
+post-return narrowing facts. `type_specifier` survives as a
+deprecating alias removed in 0.3.0 — rename to `narrowing_facts`.
+
+The gate resolves after `#init` when passed a callable
+(`methods: -> { [@method_name] }`), so config-derived method names work.
+
+**Authority:** `docs/internal-spec/plugin.md` § "Return-type and
+narrowing contributions". `M` for the pure rename; `D` if you are adding
+a contribution the plugin did not have.
+
+---
+
+## 4. Authoring helpers (ADR-37 / ADR-60 WD4) — `M`
+
+The single richest source of drift. Each helper replaces a hand-rolled
+shape and is expected to be diagnostics-preserving.
+
+| Smell | Modern | Authority |
+| --- | --- | --- |
+| `Rigor::Analysis::Diagnostic.new(line:, column: loc.start_column + 1, …)` where a node exists | `#diagnostic(node, path:, message:, severity:, rule:)` (or `location: node.message_loc` for a sub-span) | plugin.md § "Positioning a diagnostic — `#diagnostic`" |
+| `violations.map { |v| diagnostic(node, message: v.message, …) }` | `#diagnostics_for(violations, path:, node:)` — duck-types `#message` / `#node` / `#severity` / `#rule` / `#location` | plugin.md § author helpers (ADR-60 WD4) |
+| A hand-rolled `levenshtein` / `closest_*` "did you mean" | `Rigor::Plugin::Base.suggest(name, candidates)` (`DidYouMean::SpellChecker`) — a **class** method, callable from an `Analyzer` too | plugin.md § "`Base.suggest`" |
+| `@table ||= cache_for(id).call` + a multi-`rescue` ladder + an `@load_error` ivar | `#producer_value(id, params:)` (memoised incl. nil) + `#producer_error(id)` (the rescued exception, for a tailored message) | plugin-cache-producers.md § "Invalidation contract" |
+| `@x_resolved` flag guarding `services.fact_store.read` | `#read_fact(plugin_id:, name:)` — nil-inclusive memo, retires the flag | plugin.md § author helpers (ADR-60 WD4) |
+| Hand-parsing a `Prism::SymbolNode#value` / string literal | `Rigor::Source::Literals` | plugin.md § "Extracting argument literals" |
+| A private reimplementation of a target library (own inflector, own pure helper) | Call the library's safe methods directly — `Plugin::Inflector` over real `ActiveSupport::Inflector` (ADR-39) | plugin.md § "Target-library invocation" |
+
+**Note on tailored load-error messages:** `#producer_value` rescues
+every `StandardError` into `#producer_error`, so a plugin that wants
+class-specific messages ("not found" vs "failed to parse" vs
+access-denied) switches on `producer_error(id)`'s class when building
+the load-error diagnostic — cleaner than an inline rescue ladder and
+still message-preserving. A *file-level* load-error (line 1, no node)
+legitimately keeps a direct `Diagnostic.new` — `#diagnostic` needs a
+node to position at.
+
+---
+
+## 5. Engine collaboration vs reimplementation — `D` (read the trap)
+
+**Principle (rigor-pattern):** do not re-implement a fact the engine
+already computes. If you need "is this a literal string?" / "what type
+did inference give this expression?", read `Scope#type_of(node)` rather
+than tracking it yourself. `rigor-pattern` reads the engine's
+`LiteralStringFolding` result back instead of propagating strings by
+hand.
+
+**The trap (rigor-units) — when a hand-rolled binding map is NOT
+redundant:** the `Scope` handed to the **diagnostics** side
+(`#diagnostics_for_file` / a `node_rule`) is the **seed entry scope**.
+`Scope#type_of` re-evaluates a *self-contained* expression on demand
+(`scope.type_of(100.kilometers)` folds through the plugin's own
+`dynamic_return`), but it carries **no flow-accumulated local
+bindings**: for `speed = distance / time`, `scope.type_of(distance)` is
+`untyped`, because the entry scope never bound the earlier assignment.
+Only the **flow scope** handed to a `dynamic_return` block resolves such
+locals. So a diagnostics-side check that must follow a dimension /
+type across statements legitimately keeps its own single-pass binding
+map — deleting it and reaching for `scope.type_of` collapses
+cross-statement propagation.
+
+**How to tell which case you are in:** if the value you need lives *at
+the call site you are inspecting* (a literal argument, a self-contained
+sub-expression) → read `Scope#type_of`. If it lives *in an earlier
+statement's local binding* and you are on the diagnostics side → the
+engine will not hand it to you; keep the binding map, and document why.
+**Validate empirically before deleting state:** run the integration
+spec after the change; a wave of failures on multi-statement fixtures is
+this trap.
+
+**Authority:** the reasoning is recorded in
+`docs/notes/20260704-examples-plugin-modernization-survey.md` (the
+`rigor-units` section) and the `rigor-units` class comment itself.
+
+---
+
+## 6. Cache producers (ADR-60 WD3) — `M`/`D`
+
+**Smell:** a "prime the read before `cache_for` so the digest is
+captured" comment, or a producer that globs a directory but does not
+declare `watch:`.
+
+**Modern:** record-and-validate — the `io_boundary.read_file` inside the
+`producer` block is captured into the dependency descriptor *after* the
+block runs, so there is nothing to prime. A producer that reads a *set*
+of files by glob declares `watch:` so file *additions* invalidate too.
+
+**Authority:** `docs/internal-spec/plugin-cache-producers.md` §§
+"Invalidation contract", "`producer(... watch:)`".
+
+---
+
+## 7. Manifest-field hygiene (ADR-60 WD1 / WD2) — `M`
+
+**Smell:** `external_files:` (never wired — removed in ADR-60 WD1);
+`BlockAsMethod verbs:` (renamed → `method_names:`); `NestedClassTemplate
+name_arg_position:` (renamed → `symbol_arg_position:`).
+
+**Modern:** drop `external_files:`; use the renamed keys.
+
+**Authority:** `docs/internal-spec/plugin.md` § "`Rigor::Plugin::Manifest`"
+and `macro-substrate.md`.
+
+---
+
+## 8. Documentation freshness — `M`
+
+**Smell:** "the former `flow_contribution_for` hook was removed"
+archaeology in a README / class comment (a reader who never knew the
+deleted hook does not need it named); pinned version references that no
+longer carry meaning ("introduced in v0.0.9").
+
+**Modern:** describe the *current* mechanism directly. Keep a historical
+note only where a reader migrating an old plugin genuinely needs it —
+and put that in a CHANGELOG / migration note, not the class docstring.
+
+---
+
+## 9. Verification (ADR-43) — always
+
+- `rigor check <plugin>/lib` — the ADR-43 contract self-check resolves
+  the plugin's inherited `Plugin::Base` calls and warns on contract
+  misuse. MUST be clean; fix the cause, never disable the rule.
+- `rigor plugins --strict` — the plugin still activates.
+- `rigor plugins --capabilities` — `node_rule_types` /
+  `dynamic_return_receivers` / `type_specifier_methods` reflect the
+  declarations.
+- The integration / unit spec — green, and byte-identical across every
+  mechanical step.
+- In the monorepo: `make check-plugins` + `make verify`.

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

@@ -20,6 +20,21 @@ All `rigor-*` plugins ship **bundled inside the `rigortype` gem** — no
 separate install. Enabling one is just adding its id to `plugins:` in
 `.rigor.dist.yml`.
 
+## First: load the version-current copy
+
+This skill's exact commands, flags, and config keys drift between Rigor
+releases, so follow the copy that ships with the **installed** Rigor rather
+than any vendored or frozen copy of this file. Get the complete current
+procedure in one call:
+
+```sh
+rigor skill --full rigor-plugin-tune
+```
+
+If you already loaded this skill *via* `rigor skill` you have the current
+copy — just proceed. If `rigor` is not on `PATH`, this task needs it: run
+**`rigor-next-steps`** to install Rigor first, then come back.
+
 ## When to use
 
 - The project added (or removed) a gem since it was onboarded.
@@ -43,9 +58,13 @@ dependencies in `Gemfile.lock`.
 ### Phase 2 — match against the bundled catalogue
 
 The authoritative, current list of bundled plugins (the count drifts as
-new ones land) is the catalogue:
+new ones land) comes from the **installed** Rigor itself — read it there,
+not from a web page that may describe a different version:
 
-<https://github.com/rigortype/rigor/blob/master/plugins/README.md>
+```sh
+rigor docs manual/plugins/README   # the catalogue of every bundled plugin, offline
+rigor plugins                      # what is enabled in THIS project right now
+```
 
 For each Gemfile.lock dependency, check whether a bundled `rigor-<gem>`
 plugin exists and is **not** already in `plugins:`. Common matches:

data/skills/rigor-project-init/SKILL.md

@@ -23,6 +23,22 @@ chapter for the install channels (`mise` recommended). This skill
 references only public CLI flags and config keys — the same surface
 `rigor --help` documents.
 
+## First: load the version-current copy
+
+This skill's step detail lives in its `references/` files, and its exact
+commands, flags, and config keys drift between Rigor releases — so follow
+the copy that ships with the **installed** Rigor rather than any vendored
+or frozen copy of this file. Get the complete current procedure (body + all
+references, inline) in one call:
+
+```sh
+rigor skill --full rigor-project-init
+```
+
+If you already loaded this skill *via* `rigor skill` you have the current
+copy — just proceed. If `rigor` is not on `PATH`, this task needs it: run
+**`rigor-next-steps`** to install Rigor first, then come back.
+
 ## Phase 0 — When to use this skill
 
 Trigger when the user says "set up Rigor here", "configure rigor for

data/skills/rigor-protection-uplift/SKILL.md

@@ -16,6 +16,21 @@ type. This skill *acts* on that surfacing under the discipline that keeps
 Rigor false-positive-safe: protection goes up, and not one line of
 working code starts reporting a new diagnostic.
 
+## First: load the version-current copy
+
+This skill's exact commands, flags, carrier syntax, and rule ids drift
+between Rigor releases, so follow the copy that ships with the **installed**
+Rigor rather than any vendored or frozen copy of this file. Get the
+complete current procedure in one call:
+
+```sh
+rigor skill --full rigor-protection-uplift
+```
+
+If you already loaded this skill *via* `rigor skill` you have the current
+copy — just proceed. If `rigor` is not on `PATH`, this task needs it: run
+**`rigor-next-steps`** to install Rigor first, then come back.
+
 ## When to use
 
 - A user wants to raise how much of their code Rigor can actually catch

data/skills/rigor-rbs-setup/SKILL.md

@@ -18,6 +18,21 @@ community RBS collection at
 [`ruby/gem_rbs_collection`](https://github.com/ruby/gem_rbs_collection);
 this skill wires it into the project.
 
+## First: load the version-current copy
+
+This skill's exact commands, flags, and config keys drift between Rigor
+releases, so follow the copy that ships with the **installed** Rigor rather
+than any vendored or frozen copy of this file. Get the complete current
+procedure in one call:
+
+```sh
+rigor skill --full rigor-rbs-setup
+```
+
+If you already loaded this skill *via* `rigor skill` you have the current
+copy — just proceed. If `rigor` is not on `PATH`, this task needs it: run
+**`rigor-next-steps`** to install Rigor first, then come back.
+
 ## When to use
 
 - `rigor check` ends with `info: N gem(s) in Gemfile.lock have no RBS