rigortype 0.2.1 → 0.2.2

data/skills/rigor-doctor/SKILL.md

@@ -0,0 +1,87 @@
+---
+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).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Doctor
+
+`rigor skill describe` reports what *exists* (presence checks). This skill
+goes a level deeper: it *runs* Rigor's 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." Use 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.
+
+## Checks
+
+### 1. Config resolves with nothing silently inert
+
+```sh
+rigor check --format json   # read the `config_warnings` array
+```
+
+`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
+
+```sh
+rigor plugins --strict
+```
+
+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
+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)
+
+```sh
+rigor baseline drift
+```
+
+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`).
+
+### 4. The analysis is actually seeing your code
+
+```sh
+rigor check --format json   # check the "Ruby source files" count
+```
+
+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.
+
+## 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
+  `rigor-protection-uplift`.
+- **A `config_warning` or a plugin failure** → that is the real problem;
+  fixing it usually resolves a whole cluster of confusing downstream
+  diagnostics at once.
+
+For deeper symptoms (hover shows `untyped` everywhere, completion empty,
+LSP silent) see the manual's troubleshooting:
+<https://github.com/rigortype/rigor/blob/master/docs/manual/13-troubleshooting.md>
+
+## Next step
+
+Re-run `rigor skill describe` for the recommended next move.

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

@@ -0,0 +1,114 @@
+---
+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).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Editor Setup
+
+`rigor lsp` is the in-process Language Server bundled with the
+`rigortype` gem. It speaks LSP over stdio and turns Rigor's analyzer
+into a live editor experience: diagnostics as you type, hover-to-type,
+an outline view, and type-aware completion. This skill wires it into the
+developer's editor.
+
+The authoritative, per-editor configuration lives in the manual. With
+Rigor installed, read it **offline** with no network round-trip:
+
+```sh
+rigor docs editor-integration
+```
+
+(Web fallback, only before Rigor is installed:
+**[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.
+
+## When to use
+
+- A developer wants Rigor feedback live in their editor, not just from
+  `rigor check` on the command line.
+- A project commits a shared editor config (e.g. `.vscode/`) and you want
+  to add Rigor's LSP to it so the whole team gets it.
+
+## When NOT to use
+
+- Wiring Rigor into CI — that is `rigor-ci-setup`.
+- The project has no Rigor config yet — run `rigor-project-init` first
+  (the LSP uses the same `.rigor.yml` discovery as `rigor check`).
+
+## The one stable fact
+
+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](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.
+
+## Procedure
+
+### Phase 1 — confirm the analyzer works from the CLI first
+
+```sh
+rigor check <a-file-or-dir>
+```
+
+The LSP shares `rigor check`'s config discovery and analysis. If `check`
+works from the project root, the LSP will too; if it fails, fix that
+first — the editor would only surface the same failure.
+
+### Phase 2 — identify the editor
+
+Ask the developer which editor they use, or detect it (a committed
+`.vscode/`, a Neovim `init.lua`, `~/.config/helix/`, an Emacs config).
+The manual chapter covers:
+
+- **Neovim** (nvim-lspconfig)
+- **VS Code** (generic LSP-client wrapper / minimal extension)
+- **Helix** (`languages.toml`)
+- **Emacs** (Eglot and lsp-mode)
+
+### Phase 3 — apply the matching config
+
+Open the manual's **Editor wiring** section and apply the snippet for
+the developer's editor verbatim:
+
+```sh
+rigor docs editor-integration
+```
+
+(or, pre-install, the web copy:
+<https://github.com/rigortype/rigor/blob/master/docs/manual/09-editor-integration.md>)
+
+All snippets invoke `rigor lsp` directly. (Only if the project still
+uses a legacy bundler-local install do you swap in
+`bundle exec rigor lsp` — the manual notes this per editor.)
+
+If the project commits a shared editor config (e.g. `.vscode/`), add the
+Rigor LSP wiring there and commit it, so every contributor gets the same
+setup rather than configuring it individually.
+
+### Phase 4 — verify
+
+Open a Ruby file inside a Rigor-configured project and confirm:
+
+- diagnostics appear (on save / as you type), and
+- hover over a method or local shows its inferred type.
+
+If the server starts but nothing appears, work the manual's
+**Troubleshooting** section (most often: `rigor` not on the editor's
+PATH, or no `.rigor.yml` at the project root). Capture the LSP log with
+`rigor lsp --log=/tmp/rigor-lsp.log` when filing an issue.
+
+## Next step
+
+Re-run `rigor skill describe` for the next move — with live feedback in
+the editor, raising protection (`rigor-protection-uplift`) or reducing a
+baseline (`rigor-baseline-reduce`) is a tighter loop.

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

@@ -0,0 +1,117 @@
+---
+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).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor MCP Setup
+
+`rigor mcp` is the Model Context Protocol server bundled with the
+`rigortype` gem. It exposes Rigor's analysis as JSON-RPC tool calls over
+stdio, so an AI coding agent can call Rigor directly during a session —
+check types before a refactor, look up the type at a cursor, or triage a
+project's diagnostics as review context. All tools are **read-only**
+(write-side commands like `rigor init` / `sig-gen --write` are
+deliberately excluded — modifying files stays the developer's call).
+
+The authoritative, per-client configuration lives in the manual. With
+Rigor installed, read it **offline** with no network round-trip:
+
+```sh
+rigor docs mcp-server
+```
+
+(Web fallback, only before Rigor is installed:
+**[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.
+
+## When to use
+
+- A developer wants their AI agent to call Rigor's tools mid-session.
+- A project commits a shared MCP config (`.mcp.json`, `.cursor/mcp.json`)
+  and you want to add Rigor to it for the whole team.
+
+## When NOT to use
+
+- Editor (human) integration — that is `rigor-editor-setup` (`rigor lsp`).
+- The project has no Rigor config yet — run `rigor-project-init` first
+  (the MCP tools use the same `.rigor.yml` discovery as `rigor check`).
+
+## The tools you are wiring in
+
+`rigor_check`, `rigor_type_of`, `rigor_triage`, `rigor_annotate`,
+`rigor_sig_gen`, `rigor_explain`, `rigor_coverage` — each the JSON form
+of the matching `rigor` CLI command. See the manual's **Tool reference**
+for inputs and outputs.
+
+## The one stable fact
+
+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](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.
+
+## Procedure
+
+### Phase 1 — confirm the analyzer works from the CLI first
+
+```sh
+rigor check <a-file-or-dir>
+```
+
+The MCP tools share `rigor check`'s config discovery. If `check` works
+from the project root, the tools will too.
+
+### Phase 2 — identify the client and apply the config
+
+Ask the developer which agent they use, or detect a committed config
+(`.mcp.json`, `.cursor/mcp.json`, `.claude/settings.json`). Apply the
+matching snippet from the manual's **Client wiring** section verbatim —
+it covers Claude Desktop, Claude Code CLI, Cursor, Cline, and a generic
+stdio client:
+
+```sh
+rigor docs mcp-server
+```
+
+(or, pre-install, the web copy:
+<https://github.com/rigortype/rigor/blob/master/docs/manual/10-mcp-server.md>)
+
+Each snippet is the same shape — `{"command": "rigor", "args": ["mcp"]}`.
+If the project commits a shared MCP config, add the Rigor entry there and
+commit it so every contributor gets it.
+
+**Working-directory gotcha (from the manual's Troubleshooting):** the
+server discovers config from the directory it is launched in. If the
+client starts `rigor mcp` from `$HOME` or a temp dir, no `.rigor.yml` is
+found and tools return an empty set. Pin it with
+`"args": ["mcp", "--config=/abs/path/.rigor.yml"]`, or pass absolute
+`paths` in the tool call.
+
+### Phase 3 — verify the handshake
+
+Confirm `rigor mcp` answers the MCP `initialize` request:
+
+```sh
+echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}' | rigor mcp
+```
+
+A JSON `result` with `serverInfo.name: "rigor"` means it works; nothing
+or a shell error means `rigor` is not on the PATH the client uses. Then
+restart the client and confirm the `rigor_*` tools appear in its tool
+palette.
+
+## Next step
+
+Re-run `rigor skill describe` for the next move — with the agent able to
+call Rigor's tools, raising protection (`rigor-protection-uplift`) or
+reducing a baseline (`rigor-baseline-reduce`) is a tighter loop.

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

@@ -0,0 +1,79 @@
+---
+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).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Monkeypatch Resolve
+
+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](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.`.
+
+## When to use
+
+- `rigor triage` shows a cluster of `call.undefined-method` /
+  `call.unresolved-toplevel` whose receiver is a core class the project
+  monkey-patches (or a top-level helper the project defines).
+
+## When NOT to use
+
+- The methods are **generated dynamically** (`define_method` with a
+  computed name, `method_missing`, a `class_eval <<~RUBY … def #{name}`
+  heredoc). `pre_eval:` walks for *literal* `def`s and will not find
+  them — that residue is a `rigor-plugin-author` job.
+- The cluster is on a **third-party gem** with no RBS — that is
+  `rigor-rbs-setup`.
+
+## Procedure
+
+### Phase 1 — confirm it is a monkey-patch cluster
+
+```sh
+rigor triage --format json
+```
+
+Look at the `selectors` / `hotspots`: a cluster keyed on a core receiver
+(`String#squish`, `Integer#…`) or a top-level helper, all pointing back
+to a file in your project that defines them. Open that file and confirm
+the methods are written as literal `def` / `def self.`.
+
+### Phase 2 — wire the file(s) into `pre_eval:`
+
+Add the defining file paths to `pre_eval:` in `.rigor.dist.yml` (paths
+are resolved relative to the config file):
+
+```yaml
+pre_eval:
+  - lib/core_ext/string.rb
+  - lib/core_ext/integer.rb
+```
+
+List the **files that contain the `def`s**, not the call sites.
+
+### Phase 3 — verify the cluster cleared
+
+```sh
+rigor check
+```
+
+The `call.undefined-method` cluster on those methods should be gone. If
+some survive, those specific methods are almost certainly
+**dynamically generated** — `pre_eval:` cannot reach them, and the
+durable fix is a project plugin (hand off to `rigor-plugin-author`). A
+genuine typo (a real undefined method) correctly keeps firing — do not
+add it to `pre_eval:`.
+
+## Next step
+
+Re-run `rigor skill describe`. With the monkey-patch noise gone, the
+remaining diagnostics are a cleaner target for `rigor-baseline-reduce`
+or `rigor-protection-uplift`.

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

@@ -0,0 +1,113 @@
+---
+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.
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Next Steps
+
+The single entry point for "what should we do next with Rigor on this
+project?" This skill is deliberately **thin**: it only does the
+bootstrap that must happen before `rigor` can speak for itself, then it
+hands the decision to the installed `rigor` binary via
+`rigor skill describe`. That keeps the advice **current to the
+installed version** — the routing intelligence lives in the gem, not
+frozen in this file (ADR-73).
+
+Work top to bottom. Stop at the first step that is not yet satisfied,
+complete it, then continue.
+
+## Step 1 — Resolve the `rigor` command
+
+```sh
+rigor --version
+```
+
+If it prints a version (`rigor 0.x.y`), `rigor` is installed — go to
+**Step 3**. If the command is not found, go to **Step 2**.
+
+## Step 2 — Install Rigor (only if Step 1 failed)
+
+Rigor is a standalone tool, **not** a project dependency — do not add it
+to the `Gemfile`. Fetch and follow the install guide, which is written
+for an AI agent and picks the right channel (mise / asdf / gem / Docker)
+for the environment:
+
+- <https://raw.githubusercontent.com/rigortype/rigor/master/docs/install.md>
+
+Follow it until `rigor --version` succeeds, then continue to Step 3.
+
+(This is the one step that cannot be driven by `rigor skill describe` —
+there is no binary to ask yet. It is the only install knowledge this
+skill carries, kept as a pointer rather than a copy so it does not go
+stale.)
+
+## Step 3 — Set the project up if it has no Rigor config
+
+Check the project root for `.rigor.yml` or `.rigor.dist.yml`. If
+**neither** exists, the project has never been onboarded — set it up
+first:
+
+```sh
+rigor skill rigor-project-init
+```
+
+Follow that skill's body top to bottom (it detects the stack, picks
+plugins, writes `.rigor.dist.yml`, and snapshots a baseline if needed),
+then come back to Step 4.
+
+## Step 4 — Ask `rigor skill describe` what to do next
+
+Once `rigor` is installed and the project is configured, let the live
+command pick the next move:
+
+```sh
+rigor skill describe
+```
+
+Its output reports the project's current state (config / baseline /
+`sig/` / CI), names a **recommended next skill** with a one-line reason,
+and lists every skill you can run next with its current description.
+
+## Step 5 — Route and act
+
+Read the `## Recommended next step` and `## For the agent` sections of
+the `describe` output, then:
+
+- **Present the recommendation to the user proactively** — e.g. "Rigor
+  is set up but not wired into CI; I suggest the `rigor-ci-setup` skill
+  to lock in the regression guard. Shall I?" — rather than only asking
+  an open question.
+- If the user has a different goal, ask which skill they want from the
+  listed catalog.
+- Then load the chosen skill and follow it:
+
+  ```sh
+  rigor skill <chosen-skill>
+  ```
+
+Re-run `rigor skill describe` any time you want the next step again — it
+always reflects the project's current state, so this skill stays useful
+across the whole adoption journey, not just the first run.
+
+## Reading the docs offline
+
+Once Rigor is installed (Step 1 succeeded), the full manual **and
+handbook** ship inside the gem — read any chapter **without the
+network**:
+
+```sh
+rigor docs                 # the offline doc index (what's available)
+rigor docs <name>          # a chapter, e.g. `rigor docs editor-integration`
+rigor docs --list          # name + absolute path for every bundled doc
+rigor docs --list handbook # just the handbook chapters
+```
+
+Prefer this over fetching the same page from the web: it is the exact
+copy that shipped with the installed `rigor`, so it always matches the
+binary's behaviour. (The web copy at <https://rigor.typedduck.fail/llms.txt>
+is for the contributor-facing corpus and for reading before install.)

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

@@ -0,0 +1,79 @@
+---
+name: rigor-plugin-tune
+description: |
+  Re-scan a configured project's Gemfile.lock against Rigor's bundled plugin catalogue and enable the plugins that match its current dependencies (Rails, RSpec, dry-rb, Sidekiq, Devise, …), then verify they all load. Run it after adding a gem, or when an onboarding predates a dependency the project now uses. Triggers: "enable the right Rigor plugins", "I added gem X, does Rigor have a plugin?", "which rigor plugins should this project use?", "rigor plugins for my stack". NOT for first-time onboarding (use rigor-project-init, which does the initial selection) and NOT for authoring a new plugin (use rigor-plugin-author).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Plugin Tune
+
+`rigor-project-init` selects plugins once, at onboarding. Dependencies
+drift afterward — a project adds Sidekiq, adopts dry-rb, brings in
+shoulda-matchers — and the bundled Rigor plugin that understands the new
+gem is not enabled until someone wires it. This skill is the recurring
+"re-match plugins to the current Gemfile.lock" pass.
+
+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`.
+
+## When to use
+
+- The project added (or removed) a gem since it was onboarded.
+- `rigor check` is missing framework knowledge (e.g. ActiveRecord
+  relation methods, RSpec matchers) that a bundled plugin would supply.
+
+## When NOT to use
+
+- First-time setup — `rigor-project-init` does the initial selection.
+- A gem with **no** bundled plugin and no RBS — that is
+  `rigor-rbs-setup` (community RBS) or, for your own DSL,
+  `rigor-plugin-author`.
+
+## Procedure
+
+### Phase 1 — list what is enabled vs what is installed
+
+Read the current `plugins:` in `.rigor.dist.yml`, and the project's
+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:
+
+<https://github.com/rigortype/rigor/blob/master/plugins/README.md>
+
+For each Gemfile.lock dependency, check whether a bundled `rigor-<gem>`
+plugin exists and is **not** already in `plugins:`. Common matches:
+`activerecord`/`actionpack` → the Rails plugins, `rspec` → `rigor-rspec`,
+`dry-*` → the dry-rb plugins, `devise`, `sidekiq`, `sorbet`, etc. Add the
+missing ones to `plugins:`.
+
+### Phase 3 — verify every plugin loads
+
+```sh
+rigor plugins --strict
+```
+
+`rigor plugins` reports the activation status of every configured plugin;
+`--strict` exits non-zero on any activation failure (ideal as a CI gate).
+Fix any failure it reports (a misspelled id, a missing `signature_paths:`)
+before moving on.
+
+### Phase 4 — re-check
+
+```sh
+rigor check
+```
+
+The framework calls the newly-enabled plugins understand should now
+resolve. If enabling a plugin surfaced new diagnostics, treat the diff as
+usual (baseline regenerate in acknowledge mode, or fix genuine findings).
+
+## Next step
+
+Re-run `rigor skill describe` for the next move.