rigortype 0.3.9 → 0.4.0

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

@@ -1,7 +1,9 @@
 ---
 name: rigor-ci-setup
-description: |
-  Wire Rigor type-checking into a project's CI pipeline: run it in its own isolated Ruby-4.0 job and surface diagnostics inline on the pull / merge request via a CI-native output format (SARIF, GitHub Actions annotations, GitLab Code Quality, Checkstyle, JUnit) or through reviewdog. Triggers: "add Rigor to CI", "run rigor in GitHub Actions / GitLab CI", "show Rigor errors on the PR", "set up reviewdog for rigor". NOT for first-time project configuration (use rigor-project-init to create `.rigor.yml` first) or reducing a baseline (use rigor-baseline-reduce).
+description: >-
+  Set up Rigor in a project's CI and surface diagnostics on pull or merge requests. Use when adding or
+  changing GitHub Actions, GitLab CI, SARIF, or reviewdog wiring; not for first-time Rigor configuration
+  or baseline reduction.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -31,7 +33,6 @@ Rigor is installed:
 ```sh
 rigor skill --full rigor-ci-setup   # this skill's current workflow, in one call
 rigor docs ci                       # the manual's CI chapter — the actual templates
-rigor docs --list manual | grep ci-templates   # ready-to-copy template files
 ```
 
 If you already loaded this skill *via* `rigor skill` you have the current
@@ -61,7 +62,7 @@ these markers from the project root and let them drive the platform choice:
 | `bitbucket-pipelines.yml` / `azure-pipelines.yml` / `.drone.yml` | that platform (generic recipe) |
 | none of the above | no CI yet — **ask** the user which platform they use |
 
-Concretely (the agent has file tools — use them):
+Concretely:
 
 - List `.github/workflows/*.yml` and `.gitlab-ci.yml`. **If
   `.github/workflows/rigor.yml` already exists, read it** — this is an
@@ -108,10 +109,8 @@ this is the *decision*:
 ## Phase 2 — Apply the matching template
 
 Take the template for your (platform, surface) choice from `rigor docs ci`
-— or copy a ready file listed by `rigor docs --list manual | grep
-ci-templates` (GitHub annotations / SARIF / reviewdog, and GitLab). Copy it
-in, adjust nothing but the trigger unless asked, and pin the version next
-(Phase 3).
+(GitHub annotations / SARIF / reviewdog, and GitLab). Copy it in, adjust
+nothing but the trigger unless asked, and pin the version next (Phase 3).
 
 **reviewdog is platform-specific.** It reads Rigor's `checkstyle`
 (preferred — light, no code scanning) or `sarif`, but the `-reporter` must
@@ -142,14 +141,11 @@ The exact recipe (the `BUNDLE_GEMFILE` wiring, the Dependabot entry) is in
 - **Determinism.** Add `--no-cache` in CI if you want each run independent
   of any persisted `.rigor/cache`.
 - **Cache persistence (opposite trade).** When the Rigor job's runtime
-  matters, persist `.rigor/cache` with the CI's cache facility. Current
-  Rigor detects CI and validates the restored cache by content hash
-  automatically (`cache.validation: auto`); on versions before the
-  `auto` default, **also set `RIGOR_STRICT_VALIDATION=1` on the job** —
-  without it a fresh checkout's regenerated stat tuples make the plugin
-  watch-glob cache slots read as stale on every run. A self-hosted
-  runner that reuses its workspace opts back into the faster stat check
-  with `cache.validation: stat`. Snippets: `rigor docs ci`
+  matters, persist `.rigor/cache` with the CI's cache facility. Rigor
+  detects CI and validates the restored cache by content hash
+  automatically (`cache.validation: auto`). A self-hosted runner that
+  reuses its workspace opts back into the faster stat check with
+  `cache.validation: stat`. Snippets: `rigor docs ci`
   § "Persisting the analysis cache across runs".
 
 ## Verify
@@ -165,12 +161,12 @@ The exact recipe (the `BUNDLE_GEMFILE` wiring, the Dependabot entry) is in
 
 - Manual: `rigor`'s CI chapter — the authoritative templates, severity
   mapping, and pinning recipe, **offline and version-matched** with
-  `rigor docs ci` (ready files: `rigor docs --list manual | grep
-  ci-templates`). Web fallback, before Rigor is installed:
-  <https://github.com/rigortype/rigor/blob/master/docs/manual/11-ci.md>.
-- [ADR-51](../../docs/adr/51-ci-diagnostic-output-formats.md)
+  `rigor docs ci`. Web fallback, before Rigor is installed:
+  <https://github.com/rigortype/rigor/blob/master/docs/manual/11-ci.md>
+  (ready-to-copy files in `docs/manual/ci-templates/` beside it).
+- [ADR-51](https://github.com/rigortype/rigor/blob/master/docs/adr/51-ci-diagnostic-output-formats.md)
   — the output-format surface (the severity / identifier contract).
-- [ADR-27](../../docs/adr/27-tool-distribution-model.md)
+- [ADR-27](https://github.com/rigortype/rigor/blob/master/docs/adr/27-tool-distribution-model.md)
   — why Rigor installs standalone and runs in its own job.
 - [reviewdog](https://github.com/reviewdog/reviewdog) /
   [action-setup](https://github.com/reviewdog/action-setup).

data/skills/rigor-doctor/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rigor-doctor
-description: |
-  Validate that a project's Rigor setup is actually healthy — config parses with no silently-inert values, every configured plugin loads, the baseline is not stale, and the bundled paths resolve — by running Rigor's existing validators and interpreting them. Triggers: "is my Rigor setup correct?", "check my rigor config", "rigor diagnostics look wrong / suspicious", "validate rigor setup", "why is rigor reporting nothing / everything?". NOT for first-time setup (use rigor-project-init) or for working real diagnostics down (use rigor-baseline-reduce).
+description: >-
+  Validate that a project's Rigor configuration, plugins, paths, and baseline are actually healthy. Use
+  when diagnostics are suspicious or setup behavior is wrong; not for first-time onboarding or reducing
+  ordinary diagnostics.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -11,12 +13,13 @@ metadata:
 # Rigor Doctor
 
 `rigor skill describe` reports what *exists* (presence checks). This skill
-goes a level deeper: it *runs* Rigor's own validators to confirm the setup
-is actually working — the difference between "a `.rigor.yml` is present"
-and "it parses, loads its plugins, and analyses the right files." Reach for
-it when the diagnostics look wrong (suspiciously zero, or suspiciously
-many) or after editing the config. It needs no special command — it
-orchestrates checks Rigor already ships and interprets the results.
+goes a level deeper: `rigor doctor` *runs* Rigor's own setup validators
+(config audit, RBS environment, plugin loading, baseline drift, plugin
+gaps, install layout) and this skill interprets the result — the
+difference between "a `.rigor.yml` is present" and "it parses, loads its
+plugins, and analyses the right files." Reach for it when the diagnostics
+look wrong (suspiciously zero, or suspiciously many) or after editing the
+config.
 
 ## First: load the version-current copy
 
@@ -44,25 +47,24 @@ header names). If `rigor` is not on `PATH`, this task needs it: run
 
 ## What it validates
 
-Four validators, each a check Rigor already ships. The exact commands and
-how to read each output live in the version-current
+`rigor doctor` runs the setup checks in one pass (`--format json` gives
+each finding's `checks[].id` and `status`) and exits non-zero when any
+check fails. It does not check whether the analysis sees the right
+files; that is a separate look at `stats.target_files` in
+`rigor check --format json`. What each check id means and how to act on
+it live in the version-current
 [`references/01-checks.md`](references/01-checks.md) (loaded per the
-directive above):
-
-1. **Config resolves with nothing silently inert** — no `config_warnings`.
-2. **Every configured plugin loads** — `rigor plugins --strict` is clean.
-3. **The baseline is not stale** (if one exists) — no large drift.
-4. **The analysis is actually seeing your code** — the source-file count
-   matches the project.
+directive above).
 
 ## Interpreting the result
 
-- **All clean** → the setup is healthy; any diagnostics are about the
-  code, not the configuration. Move on to `rigor-baseline-reduce` or
+- **All clean** (no `fail` or `warn` finding, and the file count matches
+  the project) → the setup is healthy; any diagnostics are about the code,
+  not the configuration. Move on to `rigor-baseline-reduce` or
   `rigor-protection-uplift`.
-- **A `config_warning` or a plugin failure** → that is the real problem;
-  fixing it usually clears a whole cluster of confusing downstream
-  diagnostics at once.
+- **A `config_audit`, `rbs_environment`, or `plugins` failure** → that is
+  the real problem; fixing it usually clears a whole cluster of confusing
+  downstream diagnostics at once.
 
 For deeper symptoms (hover shows `untyped` everywhere, completion empty,
 LSP silent) read the manual's troubleshooting chapter — offline and

data/skills/rigor-doctor/references/01-checks.md

@@ -1,52 +1,116 @@
-# 01 — The four checks
+# 01 — The checks
 
-Each check runs a validator Rigor already ships and interprets its
-output. Run them in order; the first failure is usually the root cause of
-a cluster of confusing downstream diagnostics.
-
-## 1. Config resolves with nothing silently inert
+## Run `rigor doctor`
 
 ```sh
-rigor check --format json   # read the `config_warnings` array
+rigor doctor                 # human-readable: [FAIL] / [WARN] / [PASS] lines
+rigor doctor --format json   # machine-readable
 ```
 
-`rigor check` audits the config and emits `config_warnings` for the typo
-class whose only symptom is a confusing downstream error: a
-`signature_paths:` that is missing / not a directory / holds no `.rbs`
-(which would turn every covered call into a false `call.undefined-method`
-at `evidence_tier: high`), a `libraries:` name RBS does not recognise, a
-`disable:` / `severity_overrides:` id naming no real rule, or a missing
-`bundler` / `rbs_collection` path. **Each warning here is a real
-misconfiguration — fix it.** None appearing is the healthy state.
-
-## 2. Every configured plugin loads
+It runs one scoped analysis, audits the config, loads the plugins, and
+checks baseline drift in a single pass, then prints a finding per
+problem with a hint. The JSON shape:
 
-```sh
-rigor plugins --strict
+```json
+{ "status": "issues_found",
+  "checks": [ { "id": "plugins", "status": "fail",
+                "message": "Plugin load errors: 1",
+                "hint": "Run `rigor plugins --strict` for the full per-plugin report." } ] }
 ```
 
-Reports the activation status of each plugin in `plugins:`; `--strict`
-exits non-zero on any failure. A failure is usually a misspelled id or a
+- Top-level `status` is `issues_found` when any check has `status: "fail"`,
+  otherwise `clean` — a run with only `warn` findings still reads `clean`,
+  so read the `checks` array too.
+- `checks[].status` is `fail`, `warn`, or `pass`. A check with nothing to
+  report is usually **absent**, not `pass`; only `rbs_environment` reports
+  a `pass` line.
+- The command exits non-zero when any check fails.
+
+Fix `fail` findings first, in the order below: an early failure is usually
+the root cause of a cluster of confusing downstream diagnostics.
+
+## The check ids
+
+### `config_audit` — config resolves with nothing silently inert
+
+`fail` with a count of configuration warnings. Doctor gives only the
+count; the individual warnings are in `rigor check --format json` under
+`config_warnings`. They cover the typo class whose only symptom is a
+confusing downstream error: a `signature_paths:` that is missing / not a
+directory / holds no `.rbs` (which would turn every covered call into a
+false `call.undefined-method` at `evidence_tier: high`), a `libraries:`
+name RBS does not recognise, a `disable:` / `severity_overrides:` id
+naming no real rule, or a missing `bundler` / `rbs_collection` path.
+**Each warning is a real misconfiguration — fix it.**
+
+### `rbs_environment` — the type universe loaded
+
+- `fail` — the RBS environment is empty (zero classes). It failed to build
+  or loaded no signatures: look for duplicate declarations across
+  `signature_paths:`, or run `rbs collection install` for gem signatures.
+- `warn` — degraded: one or more `signature_paths:` files did not parse
+  and were skipped. The run is quieter, not cleaner — the types those
+  files declare are gone. Run `rbs validate` on the `sig/` set and fix
+  the parse error.
+- `pass` — healthy, with the class count.
+
+### `plugins` — every configured plugin loads
+
+`fail` with a count of plugin load errors. Run `rigor plugins --strict`
+for the per-plugin report. A failure is usually a misspelled id or a
 plugin whose `signature_paths:` did not resolve. Fix it, or the plugin's
 type knowledge is silently absent.
 
-## 3. The baseline is not stale (if one exists)
+### `plugin_skew` — a bundled plugin came from another installation
 
-```sh
-rigor baseline drift
-```
+`warn` when a bundled plugin was loaded from a different `rigortype`
+installation than the engine. The engine and its bundled plugins are
+versioned together, so a mismatched copy can produce wrong diagnostics.
+Make sure a single `rigortype` is on the load path.
+
+### `baseline` — the baseline is not stale (if one exists)
+
+- `fail` — drift: some baseline buckets are over their recorded count,
+  cleared, or reducible. The hint is `rigor baseline regenerate`; before
+  regenerating, run `rigor baseline drift` to see which buckets moved, so
+  a regeneration does not bury a new catch (often after an upgrade — see
+  `rigor-upgrade`).
+- `warn` — the baseline file failed to load. Check the `baseline:` path
+  in the config.
+
+### `plugin_gap` — the stack has a plugin that is not enabled
+
+Read from the `DEPENDENCIES` section of `Gemfile.lock`.
+
+- `fail` — the project depends on gems that bundled plugins model, and
+  **none** of those plugins is enabled: framework calls will not resolve.
+  Add the plugins for the stack to `plugins:` (the `rigor-plugin-tune`
+  skill does this).
+- `warn` — one per plugin that models a direct dependency but is not
+  enabled. Enable it, or leave it out deliberately; declining a plugin is
+  a legitimate choice.
+
+### `gemfile_install` — Rigor is a project dependency
+
+`fail` when `rigortype` is resolved from a gem source in the project's
+`Gemfile.lock`. Rigor is a tool, not a library: remove it from the
+`Gemfile` and install it standalone (`rigor docs manual/01-installation`).
+
+### `bundle_layout` — gem-shipped signatures are not discovered
 
-Shows whether the live diagnostics have drifted from `.rigor-baseline.yml`
-— entries the baseline ignores that no longer occur (safe to prune) and
-new diagnostics outside the envelope. A large drift means the baseline
-needs regenerating (often after an upgrade — see `rigor-upgrade`).
+`warn` when a `Gemfile.lock` exists but Rigor cannot locate the installed
+bundle (the gems live in the active Ruby's default gem home). Gems that
+ship their own `sig/` are then not loaded. Point Rigor at the install
+root with `bundler.bundle_path:`, install into `vendor/bundle`, or supply
+signatures with `rbs collection install` instead.
 
-## 4. The analysis is actually seeing your code
+## Not covered by `rigor doctor`: is the analysis seeing your code?
 
 ```sh
-rigor check --format json   # check the "Ruby source files" count
+rigor check --no-cache --format json | jq '.stats.target_files'
 ```
 
-If the file count is `0` or far below your project size, `paths:` /
-`exclude:` are mis-scoped, or the command is running from the wrong
+`--no-cache` matters: a result served from the run cache carries no
+`stats`. If the file count is `0` or far below your project size, `paths:`
+/ `exclude:` are mis-scoped, or the command is running from the wrong
 directory. The analysis is only as good as the files it reads.

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

@@ -1,7 +1,9 @@
 ---
 name: rigor-editor-setup
-description: |
-  Wire Rigor's bundled language server (`rigor lsp`) into the developer's editor for live diagnostics, hover-to-type, outline, and type-aware completion. The per-editor config snippets live in the manual; this skill identifies the editor, applies the right one, and verifies the server attaches. Triggers: "set up Rigor in my editor", "rigor LSP / language server", "live Rigor diagnostics in VS Code / Neovim / Helix / Emacs", "hover types in my editor". NOT for CI integration (use rigor-ci-setup) or first-time project setup (use rigor-project-init).
+description: >-
+  Set up Rigor's bundled language server for live diagnostics, hover, outline, and completion in a
+  developer's editor. Use when wiring `rigor lsp` into VS Code, Neovim, Helix, Emacs, or another LSP
+  client; not for CI or first-time project setup.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -24,7 +26,7 @@ rigor docs editor-integration
 ```
 
 (Web fallback, only before Rigor is installed:
-**[Rigor LSP — Editor Integration](../../docs/manual/09-editor-integration.md)**.)
+**[Rigor LSP — Editor Integration](https://github.com/rigortype/rigor/blob/master/docs/manual/09-editor-integration.md)**.)
 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.
@@ -62,7 +64,7 @@ Every editor snippet simply launches **`rigor lsp`** (stdio) and needs
 **`rigor` on the editor's `PATH`** — the same executable `rigor check`
 uses. For GUI editors that do not inherit your shell, the `mise` shim
 path is the most reliable channel (see `rigor docs install`, or
-[Installing Rigor](../../docs/install.md)
+[Installing Rigor](https://github.com/rigortype/rigor/blob/master/docs/install.md)
 on the web). Do **not** add `rigortype` to the project's `Gemfile` — it
 is a tool, not a library.
 

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

@@ -1,7 +1,8 @@
 ---
 name: rigor-mcp-setup
-description: |
-  Wire Rigor's bundled MCP server (`rigor mcp`) into an AI coding agent (Claude Code, Claude Desktop, Cursor, Cline) so the agent can call Rigor's read-only analysis tools — rigor_check, rigor_type_of, rigor_triage, rigor_coverage, and more — during a session. The per-client config lives in the manual; this skill identifies the client, applies the right one, and verifies the handshake. Triggers: "set up rigor mcp", "give my AI agent Rigor tools", "wire Rigor into Claude Code / Cursor / Cline", "rigor MCP server". NOT for editor LSP integration (use rigor-editor-setup) or CI (use rigor-ci-setup).
+description: >-
+  Set up Rigor's bundled MCP server for an AI coding agent and verify the connection. Use when wiring
+  `rigor mcp` into Claude Code, Cursor, Cline, or another MCP client; not for editor LSP or CI setup.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -26,7 +27,7 @@ rigor docs mcp-server
 ```
 
 (Web fallback, only before Rigor is installed:
-**[Rigor MCP Server — AI Agent Integration](../../docs/manual/10-mcp-server.md)**.)
+**[Rigor MCP Server — AI Agent Integration](https://github.com/rigortype/rigor/blob/master/docs/manual/10-mcp-server.md)**.)
 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.
@@ -70,7 +71,7 @@ Every client config simply launches **`rigor mcp`** (stdio) and needs
 **`rigor` on the agent's `PATH`** — the same executable `rigor check`
 uses. For agents that do not inherit your shell, the `mise` shim path is
 the most reliable channel (see `rigor docs install`, or
-[Installing Rigor](../../docs/install.md)
+[Installing Rigor](https://github.com/rigortype/rigor/blob/master/docs/install.md)
 on the web). Do **not** add `rigortype` to the project's `Gemfile` — it
 is a tool, not a library.
 

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

@@ -1,7 +1,9 @@
 ---
 name: rigor-monkeypatch-resolve
-description: |
-  Resolve a cluster of `call.unresolved-toplevel` / `call.undefined-method` diagnostics that are really the project's own monkey-patches (core-extension files that add methods with literal `def`) by wiring them into `pre_eval:` so Rigor pre-evaluates them and learns the added methods. Triggers: "Rigor flags methods my core-ext adds", "undefined-method on my own monkey-patch", "set up pre_eval", "lots of unresolved-toplevel from my lib/core_ext". NOT for dynamically-generated methods (define_method / method_missing / class_eval heredocs) — those need a plugin (use rigor-plugin-author) — and NOT for an external gem with no RBS (use rigor-rbs-setup).
+description: >-
+  Resolve Rigor diagnostics caused by literal `def` methods in a project's own monkey-patches by wiring
+  their files into `pre_eval:`. Use when project core extensions cause undefined-method findings; not for
+  dynamic method generation or an external gem without RBS.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -14,7 +16,7 @@ When a project adds methods to existing classes in its own files — the
 classic `lib/core_ext/*.rb` `class String; def squish; …; end` pattern —
 Rigor does not see them unless told to, so every call to the added method
 fires `call.undefined-method` (or `call.unresolved-toplevel` for a
-top-level helper). `pre_eval:` ([ADR-17](../../docs/adr/17-monkey-patch-pre-evaluation.md))
+top-level helper). `pre_eval:` ([ADR-17](https://github.com/rigortype/rigor/blob/master/docs/adr/17-monkey-patch-pre-evaluation.md))
 fixes this: it pre-evaluates the listed project files and registers every
 method they define with a **literal** `def` / `def self.`.
 

data/skills/rigor-next-steps/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rigor-next-steps
-description: |
-  Route a project to its next Rigor step from a single entry point: resolve the `rigor` command (install it if missing), onboard the project if it has no Rigor config, then ask `rigor skill describe` what to do next and hand off to the matching skill. Triggers: "what should we do next with Rigor?", "I want to use Rigor on this project", "help me move this project forward with Rigor", "where do I start with Rigor?". NOT a replacement for the task-specific skills it routes to — it hands off to them.
+description: >-
+  Route a project to its next Rigor step, installing or onboarding Rigor when needed and then delegating
+  to `rigor skill describe`. Use when the user asks where to start or what to do next with Rigor; not
+  instead of a task-specific skill the route selects.
 license: MPL-2.0
 metadata:
   version: 0.1.0

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

@@ -1,7 +1,9 @@
 ---
 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).
+description: >-
+  Author a Rigor plugin in an adopting project or standalone `rigor-*` gem for a DSL, framework, or
+  metaprogramming pattern. Use when Rigor needs project-specific extension support; not for onboarding a
+  project, reducing a baseline, or editing Rigor's bundled plugins.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -43,21 +45,20 @@ 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)
+## The plugin contract is 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:
+Rigor's plugin contract (ADR-2) freezes at `rigortype` v1.0.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.
+- **Pin `rigortype` to the minor you built against** — `"~> X.Y.0"`
+  in your gemspec or Gemfile, where `X.Y` comes from `rigor --version`.
+- Expect to **revisit your plugin** when you move to the next minor.
+  The node-rule block signature, the `Diagnostic` shape, and the type
+  carriers may shift.
 
-Tell the user this up front. A plugin written today is a preview
-artefact, valuable but not yet on a stable foundation.
+Tell the user this up front: a plugin written today is valuable but
+not yet on a frozen foundation.
 
 ## Read a real plugin — `rigor plugin`
 
@@ -114,14 +115,9 @@ AST walk per file — hands every matching node to the block along with a
 `Rigor::Analysis::Diagnostic` (built via the `diagnostic` helper).
 Optionally the plugin also declares `dynamic_return(receivers:)` /
 `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; the old verb was removed in
-0.3.0, so `narrowing_facts` is the only spelling.)
-`#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` /
-`narrowing_facts`. See Phase 2.)
+for call sites the core analyzer types as `Dynamic`.
+`#diagnostics_for_file` is the file-rule surface for whole-file
+diagnostics a per-node walk can't express. See Phase 2.
 
 ## Phase outline
 
@@ -136,5 +132,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` / `narrowing_facts` return-type hooks (`narrowing_facts` was renamed from `type_specifier` in ADR-80, the 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. |
+| 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, 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/01-plan-and-scaffold.md

@@ -52,8 +52,9 @@ Gem::Specification.new do |spec|
   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"
+  # Pin to the minor you built against — the contract is pre-1.0
+  # (see SKILL.md). X.Y comes from `rigor --version`.
+  spec.add_dependency "rigortype", "~> X.Y.0"
 end
 ```
 
@@ -131,7 +132,7 @@ your-app/
 
 ```ruby
 # your-app/Gemfile
-gem "rigortype", "~> 0.1.0"
+gem "rigortype", "~> X.Y.0"   # the minor you built against
 gem "rigor-myapp", path: "rigor-plugin"
 ```
 
@@ -172,16 +173,16 @@ module Rigor
         # Optional: declare config keys the user may set under
         # `.rigor.yml` plugins: [{ gem:, config: { … } }].
         config_schema: {
-          # "module_name" => :string,
-          # "rules"       => :array,
+          "module_name" => { kind: :string, default: "Default" }
+          # "rules"     => :array,
         }
       )
 
       # Called once at load time with the service container.
-      # Read config defaults here. `config` is the validated
-      # user config Hash.
+      # `config` is the validated user config Hash, with declared
+      # defaults merged beneath it.
       def init(_services)
-        @module_name = config.fetch("module_name", "Default")
+        @module_name = config["module_name"]
       end
 
       # The engine owns the AST walk and hands every matching node to

data/skills/rigor-plugin-author/references/02-walker-and-types.md

@@ -165,20 +165,14 @@ Rigor::Plugin::Base.suggest(typo, known_names)  # nearest match, or nil
 
 ## 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
-> *type* are two independent checks. A return-type contribution sharpens
-> the type of a call the analyzer has **already resolved to a real
-> method** (turning a `Dynamic` return into something precise). It is
-> never consulted for a receiver/method the analyzer cannot find — that
-> fires `call.undefined-method` first, and a contribution does nothing
-> to silence it. **If your goal is to kill a `call.undefined-method`
-> cluster on a DSL-generated method (the common reason
-> `rigor-project-init` hands off to this skill), the fix is to make the
-> method *exist* in Rigor's view — ship RBS declaring it (see "Shipping
-> RBS for the DSL" below), not a return-type contribution.** Reach for
-> these only when the call already resolves and you want a *better
-> return type*.
+> **Prefer RBS to make a DSL method exist.** A `dynamic_return` answer
+> suppresses `call.undefined-method` only at the call sites where the
+> rule fires (its gated receiver kind and methods); RBS makes the method
+> defined for all of core inference — arity, argument types, every call
+> site. To clear a `call.undefined-method` cluster on DSL-generated
+> methods (the common reason `rigor-project-init` hands off to this
+> skill), ship RBS (see "Shipping RBS for the DSL" below). Reach for
+> these hooks when you want a better *return type* for a call.
 
 A plugin can do more than emit diagnostics: it can *supply* the
 inferred return type (or narrowing facts) for a call site the core
@@ -213,10 +207,6 @@ narrowing_facts methods: [:assert_kind_of] do |call_node, scope|
 end
 ```
 
-> **`narrowing_facts` was renamed from `type_specifier` in ADR-80.**
-> The old verb was removed in 0.3.0 — `narrowing_facts` is the only
-> spelling a plugin can declare.
-
 Build return types with `Rigor::Type::Combinator`:
 
 ```ruby
@@ -233,12 +223,9 @@ plugin is confident; a wrong contribution propagates downstream.
 `rigor plugins --capabilities` catalogue enumerates — run it to see
 exactly what each loaded plugin contributes.
 
-> **The removed fat hook.** The original `flow_contribution_for(call_node:,
-> scope:)` was **deleted pre-1.0 in ADR-52 WD3** — defining it now raises
-> `ArgumentError` at load time. The two shapes it used to cover are
-> expressed by `dynamic_return`'s callable gates: a **method-gated return
-> type** (an RSpec `let(:x) { … }` binding, a Sorbet `sig`-driven return —
-> keyed on the method, not a fixed receiver class) uses
+> **Callable gates.** A **method-gated return type** (an RSpec
+> `let(:x) { … }` binding, a Sorbet `sig`-driven return — keyed on the
+> method, not a fixed receiver class) uses
 > `dynamic_return methods: -> { [...] }` or `file_methods: ->(path) { [...] }`;
 > a **dynamic per-project receiver set** (ActiveStorage's `Attached::One`
 > on discovered model classes) uses `dynamic_return receivers: -> { [...] }`,
@@ -247,7 +234,7 @@ exactly what each loaded plugin contributes.
 > if the plugin genuinely needs to sharpen call-site types; a
 > diagnostics-only plugin skips them entirely.
 
-## Shipping RBS for the DSL — the way to suppress `call.undefined-method`
+## Shipping RBS for the DSL — making DSL methods exist
 
 If the DSL introduces methods or classes that Rigor cannot see (a
 `Money` class defined by metaprogramming, `Setting.<name>` accessors a

data/skills/rigor-plugin-author/references/03-test-and-ship.md

@@ -106,11 +106,12 @@ CLI tests for the end-to-end wiring.
 
 ## Version pinning — the pre-1.0 contract
 
-The plugin contract is **not frozen until `rigortype` v0.2.0** (see
+The plugin contract is **not frozen until `rigortype` v1.0.0** (see
 SKILL.md). Concretely:
 
-- Gemspec / Gemfile: `rigortype` `>= 0.1.0, < 0.2.0`. Never `>= 0.1`
-  alone — that floats across the contract-changing v0.2.0 boundary.
+- Gemspec / Gemfile: `rigortype` `~> X.Y.0` for the minor you tested
+  (`rigor --version`). Never an open `>=` range — that floats across
+  contract-changing minors.
 - Your plugin's own version is normal semver, independent of
   `rigortype`'s.
 - When you bump the `rigortype` pin to a new minor, **re-run the
@@ -120,9 +121,6 @@ SKILL.md). Concretely:
 - State the supported `rigortype` range in the README so users do
   not pair the plugin with an incompatible Rigor.
 
-When v0.2.0 lands, re-pin to the stable range and ordinary
-compatibility rules apply.
-
 ## README
 
 A plugin README should carry:
@@ -151,13 +149,13 @@ wired and the fixture tests run.
 Either way, if the plugin uncovered a gap that *should* be core
 Rigor behaviour — or if you hit a plugin-contract rough edge — report
 it: <https://github.com/rigortype/rigor/issues>. External plugin
-authors are the main source of pre-v0.2.0 contract feedback.
+authors are the main source of contract feedback before v1.0.
 
 ## Output of this module — plugin shipped
 
 - A test suite: fast unit tests + fixture-driven `rigor check`
   tests, in RSpec or Minitest.
-- A `rigortype` pin tight to `< 0.2.0`.
+- A `rigortype` pin tight to the tested minor.
 - A README stating the compatibility range.
 - The plugin published as a gem, or committed project-private with
   CI wired.