rigortype 0.2.0 → 0.2.2

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.

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

@@ -0,0 +1,133 @@
+---
+name: rigor-protection-uplift
+description: |
+  Close the type-protection holes `rigor coverage --protection` surfaces: for each unprotected dispatch site, run `rigor sig-gen` first, hand-author only the minimal residual annotation, then verify with a double gate — the site becomes protected AND `rigor check` gains no new diagnostic. Triggers: "raise type protection", "add types where Rigor can't catch bugs", "act on coverage --protection / --mutation output", "make more of this code bug-catchable". NOT for Rigor's own `lib/` or the bundled plugins (use `rigor sig-gen` directly there and treat gaps as engine signal), and NOT for first-time setup (use rigor-project-init).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Protection Uplift
+
+`rigor coverage --protection` (Tier 1) and `rigor coverage --protection
+--mutation` (Tier 2) *surface* "add a type here" — they never author the
+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.
+
+## When to use
+
+- A user wants to raise how much of their code Rigor can actually catch
+  bugs in.
+- You have `coverage --protection` output (an "add a type here" list) and
+  want to close it.
+
+## When NOT to use
+
+- **Rigor's own `lib/`, or the bundled `plugins/` / `examples/`** — the
+  self-check tree. Hand-authoring types there collides with the
+  sig-gen-first ethos; run `rigor sig-gen` directly and treat residual
+  gaps as engine signal to report, not a private fix.
+- **"Make my code more precise" with no protection goal** — that is
+  `rigor coverage` (precision), not `--protection`.
+- **A project with no Rigor config yet** — onboard first with
+  `rigor-project-init`.
+
+## Load-bearing rules (read before touching a single type)
+
+1. **The signal prioritises and verifies; the contract sources the
+   type.** Never write the type the coverage/mutation signal "wants".
+   Write the type the code *actually has*, derived from the
+   implementation and its callers. A type guessed from the signal is a
+   false-confidence type — worse than no type.
+2. **sig-gen first.** A hand-written annotation is only the *residual*
+   `rigor sig-gen` cannot reach. Every residual is a sig-gen-improvement
+   to report, not just a private fix.
+3. **"Minimal" = annotation footprint, not minimal-to-kill-the-mutant.**
+   Optimising literally for mutant death games the metric. Add the
+   smallest *true* annotation that models the contract; if that also
+   kills the mutant, good.
+4. **Robustness (ADR-5).** Tighten returns, keep parameters lenient. An
+   over-tight param annotation breaks callers and breaches the
+   false-positive discipline.
+
+## Procedure
+
+### Phase 1 — surface the holes
+
+```sh
+rigor coverage --protection --format json PATHS
+```
+
+Read the ranked "add a type here" list (`count`, `method_name`,
+`examples`). Optionally confirm the highest-traffic ones actually buy
+catching power with the Tier 2 deep dive:
+
+```sh
+rigor coverage --protection --mutation --format json   # changed-files by default
+```
+
+### Phase 2 — sig-gen first
+
+```sh
+rigor sig-gen --diff PATHS      # inspect; --write to apply
+```
+
+Adopt every concrete inferred signature. Note where sig-gen emits
+`untyped` for a site on the "add a type here" list — that is the
+**residual** Phase 3 owns.
+
+### Phase 3 — author the residual (cheapest carrier per hole class)
+
+| Hole class                          | Cheapest carrier                              |
+| ----------------------------------- | --------------------------------------------- |
+| `Dynamic` method return             | annotate that method's return in `sig/…rbs`   |
+| `Dynamic[top] \| nil` ivar read     | `# @rbs @field: T` (ADR-58 territory)         |
+| untyped param feeding the receiver  | a *lenient* param annotation                  |
+
+Write the minimal true type. Prefer annotating the *upstream* source of
+the Dynamic (the method return / the ivar) over the call site itself.
+
+**Trap (carrier-additivity):** a sidecar `sig/…rbs` is NOT purely
+additive. Declaring a class there flips it from inference-mode to
+RBS-declared mode and *drops every member the RBS omits* — a lone
+`def formatted: () -> String` can make Rigor forget the inferred
+`initialize` and reject `Money.new(500)`. So either (1) adopt the full
+Phase-2 sig-gen base into the file and add the residual on top, or
+(2) use an in-place additive carrier (rbs-inline `#:` / a
+`%a{rigor:v1:…}` return-override) that annotates the method without
+re-declaring the class. "Minimal footprint" means the smallest *true*
+type, never the smallest *file*.
+
+### Phase 4 — double-gate verify (both must hold)
+
+```sh
+rigor coverage --protection PATHS   # (a) the site is now protected / ratio up
+rigor check PATHS                   # (b) no NEW diagnostic vs the post-sig-gen baseline
+```
+
+If (b) regresses, the annotation modeled the wrong contract — **revert
+it**, do not suppress the diagnostic. If (a) did not move, the carrier
+was wrong (often: you typed the call site, not the upstream Dynamic
+source). Gate (b) is a *diff* against the post-sig-gen state, not an
+absolute "zero diagnostics" — sig-gen itself can surface the
+acknowledge-mode FP envelope a project baseline absorbs; this skill owns
+only the increment it adds.
+
+### Phase 5 — feed the residual back
+
+File each Phase-3 residual as a sig-gen gap (what shape did inference
+miss?). The hand annotation is the stopgap; the durable fix is raising
+inference so the residual disappears.
+
+## Honest bounds
+
+Hand-RBS uplift is a finisher, not a path to 80% protection. The
+dominant remaining holes after this loop are intractable from
+annotation alone — external-gem Dynamic receivers, polymorphic value
+types, generic type parameters, dynamically-built classes. Those need
+parametric types / external RBS / engine folding (and are where the
+`rigor-plugin-author` escalation or a Rigor issue comes in), not another
+hand annotation. Expect a low-20s → low-30s% protection lift on a mature
+library, at zero diagnostic cost.