rigortype 0.3.8 → 0.3.9

data/skills/rigor-type-oracle/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: rigor-type-oracle
+description: |
+  Before writing or asserting ANY Ruby type, get it from Rigor rather than from reading the code: `rigor type-of FILE:LINE:COL` / `rigor annotate FILE` for an expression, `rigor sig-gen --print FILE` for a method signature, call-site observation for a parameter. A type you did not obtain from Rigor is a guess, and a guessed type is never written anywhere. Triggers: writing RBS under `sig/`, an inline `#:` / `# @rbs` annotation, a Sorbet `sig do … end`, a YARD `@param` / `@return`, a type stated in a doc sentence or a review comment, a nil check / `is_a?` / `respond_to?` guard justified by "this should be an X", "add types to this class / file", "document this method", "what type is this / what does this return?". Applies to Rigor's own tree too. When Rigor answers `Dynamic[top]` or `untyped`, or `sig-gen` skips the method, report the gap — never fill it in from inference of your own. NOT for setting Rigor up (use rigor-next-steps) or working a baseline down (use rigor-baseline-reduce).
+license: MPL-2.0
+metadata:
+  version: 0.1.0
+  homepage: https://github.com/rigortype/rigor
+---
+
+# Rigor Type Oracle
+
+You are about to write a type. Stop and ask Rigor first.
+
+This project has a deterministic type oracle installed. Reading the
+source and concluding "`currency` is a String, `pattern` is a Regexp" is
+*plausible-guess* behaviour: it is right often enough to feel safe and
+wrong often enough to poison a signature file, a doc comment, or a
+reviewer's mental model. Rigor already knows the answer — for every
+expression, at every line, from the same engine that will check the code
+tomorrow. Asking it costs one command.
+
+**The rule: a type you did not obtain from Rigor is a guess, and a
+guessed type is never written anywhere.** Not in `sig/`, not in an inline
+annotation (`#:`, `# @rbs`), not in a Sorbet `sig`, not in a YARD tag,
+not in a doc sentence, not in a review comment, and not as the stated
+reason for a nil check or an `is_a?` guard.
+
+## First: load the version-current copy
+
+This skill's exact commands, flags, output spellings, and skip-reason 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-type-oracle   # this body + all its references/, inline
+```
+
+If you already loaded this skill *via* `rigor skill` you have the current
+copy — just proceed (read any `references/NN-*.md` from the directory the
+header names). If `rigor` is not on `PATH`, this task needs it: run
+**`rigor-next-steps`** to install Rigor first, then come back.
+
+## When to use
+
+Trigger on the *act*, not on the user saying the word "type". You are in
+scope the moment you are about to write or assert one:
+
+- Writing or editing RBS under `sig/`.
+- Writing an inline annotation — rbs-inline `#:`, `# @rbs`, a
+  `%a{rigor:v1:…}` override.
+- Writing a Sorbet `sig do … end`, or any other type DSL.
+- Writing a YARD / RDoc `@param` / `@return` / `@raise`, or any doc
+  sentence that names a type ("returns an Array of entries").
+- Stating a type in a review comment, a PR description, or a chat answer.
+- Justifying a nil check, an `is_a?` / `respond_to?` guard, or a
+  defensive `to_s` with "this should be an X".
+- Being asked "what type is this?", "what does this method return?",
+  "add types to this class", "document this file".
+
+It applies to **Rigor's own tree** as well: `lib/`, the bundled plugins,
+and the examples are held to the same rule, and a gap found there is
+engine signal worth more than the annotation you would have written.
+
+## When NOT to use
+
+- **Setting Rigor up on a project that has none** → `rigor-next-steps`
+  (which routes to `rigor-project-init`). You cannot ask an oracle that
+  is not installed.
+- **Working an existing `.rigor-baseline.yml` down** →
+  `rigor-baseline-reduce`. That is fixing diagnostics, not sourcing a
+  type.
+- **Raising type protection from a `coverage --protection` list** →
+  `rigor-protection-uplift`. It owns the "where should a type go, and how
+  do I verify it" loop; this skill owns "where does the type itself come
+  from".
+
+## The three allowed sources
+
+Every type you write comes from exactly one of these. There is no fourth.
+
+| What you need | Ask Rigor with | What you write |
+| --- | --- | --- |
+| The type of an **expression** at a point | `rigor type-of FILE:LINE:COL` — or `rigor annotate FILE` for every line at once | the `type:` it prints, verbatim |
+| The **signature of a method** | `rigor sig-gen --print FILE` | the RBS it prints, verbatim — never what you expected it to print |
+| A **parameter's intended type** | `rigor sig-gen --observe PATH --params=observed` (call-site derivation) | the observed type, *reviewed and widened*, kept only while `rigor check` stays green |
+
+The parameter row is the one genuine gap. Inference reads a method
+*body*, and a body does not state what its callers are allowed to pass —
+so Rigor spells parameters `untyped` by design ([ADR-5](https://github.com/rigortype/rigor/blob/master/docs/adr/5-robustness-principle.md):
+strict on returns, lenient on parameters). `--params=observed` derives
+them from the call sites instead, which is evidence rather than
+invention — but it is *narrow* evidence (it can emit literal types such
+as `("JPY")`), so it is the one place you review and widen before
+adopting, under the gate that `rigor check` gains no new diagnostic.
+
+Exact command forms, flags, position syntax, JSON shapes, and how to read
+each output: [`references/01-oracle-commands.md`](references/01-oracle-commands.md).
+
+## The gap protocol — a gap is a finding, not a blank to fill
+
+`Dynamic[top]`, `untyped`, and a `sig.skipped.*` classification are
+**answers**. They mean "Rigor cannot prove a type here", which is
+information about the project or about the engine. Filling that hole with
+your own reading converts a known unknown into a confident falsehood, and
+it does so in a file the next reader will trust.
+
+So when the oracle comes back empty:
+
+1. **Report it.** Give the exact command and its exact output.
+2. **Find out why**, when it matters: `rigor trace --format=json --line=N FILE`
+   replays how the type was built; `rigor explain <rule>` documents a
+   diagnostic that fired nearby.
+3. **Route it.** A project-side gap has a sibling skill that closes it
+   (missing gem RBS → `rigor-rbs-setup`; an unconfigured framework →
+   `rigor-plugin-tune`; the project's own monkey-patches →
+   `rigor-monkeypatch-resolve`; a project DSL → `rigor-plugin-author`).
+   An engine-side gap is a Rigor issue.
+
+Which output means which gap, the full routing table, and how to word the
+issue: [`references/03-gap-protocol.md`](references/03-gap-protocol.md).
+
+## Provenance — every type you state carries its command
+
+When you tell a human a type, tell them how to re-derive it. One line is
+enough:
+
+> `entries_matching` returns `Array[untyped] | []`
+> (`rigor sig-gen --print lib/demo/budget_ledger.rb`).
+
+This is not ceremony. It is the difference between an assertion the
+reader must trust and a claim they can re-run in three seconds — and it
+is what makes a wrong answer *findable* instead of permanent.
+
+## With the MCP server connected, use the tools
+
+If the Rigor MCP server is wired up (`rigor-mcp-setup`), `rigor_type_of`,
+`rigor_annotate`, `rigor_sig_gen`, `rigor_check`, and `rigor_explain` are
+the same oracle as tool calls — prefer them over shelling out, and treat
+their results exactly as this skill treats CLI output. Argument shapes:
+[`references/01-oracle-commands.md`](references/01-oracle-commands.md)
+§ "The MCP tools".
+
+## Worked example
+
+Asked to document `Demo::BudgetLedger`, the guessing path writes
+`@param currency [String]`, `@return [Numeric]`, `@param pattern
+[Regexp]`. Here is the oracle path.
+
+```sh
+rigor annotate lib/demo/budget_ledger.rb
+```
+
+```ruby
+    def initialize(currency, opening_balance: 0)   #=> Dynamic[top]
+      @currency = currency                         #=> Dynamic[top]
+      @entries = []                                #=> []
+    def balance(as_of: nil)                        #=> Dynamic[top]
+    def entries_matching(pattern)                  #=> Array[Dynamic[top]] | []
+```
+
+```sh
+rigor sig-gen --print lib/demo/budget_ledger.rb
+```
+
+```
+rigor sig-gen: skipped 2 method(s) it could not type or would not overwrite
+(sig.skipped.untyped-return: 2). Run with --format=json to see each one with
+its skip_reason.
+class Demo::BudgetLedger
+  def initialize: (untyped, ?opening_balance: untyped) -> void
+  def record: (untyped, ?memo: untyped, ?at: untyped) -> Demo::BudgetLedger
+  def entries_matching: (untyped) -> (Array[untyped] | [])
+end
+```
+
+What you now know, and may write: `record` returns
+`Demo::BudgetLedger`; `entries_matching` returns `Array[untyped] | []`.
+What you must **report rather than write**: `balance` and `overdrawn?`
+were skipped as `sig.skipped.untyped-return` — `@opening_balance` is
+`Dynamic[top]`, so the arithmetic proves nothing. `currency` is not
+`String` on any evidence Rigor has; it is `untyped`, and the YARD tag is
+`@param currency — the ledger's currency` with no type at all.
+
+Call-site derivation closes the parameter half where specs exist:
+
+```sh
+rigor sig-gen --print --params=observed --observe spec lib/demo/budget_ledger.rb
+#   def initialize: ("JPY", ?opening_balance: 100) -> void
+#   def entries_matching: (Regexp) -> (Array[untyped] | [])
+```
+
+`entries_matching: (Regexp)` is now *derived*, and adoptable. The
+`("JPY")` / `100` literals are the narrowness warned about above — widen
+them to `String` / `Integer` before adopting, and keep the change only
+while `rigor check` stays green.
+
+## When the user insists on a hand-written type anyway
+
+They may. It is their code, and a human can know an intended contract
+that no static reading can prove. Do not argue past one exchange:
+
+1. Say once what Rigor actually reports for that site, with the command.
+2. Write what they asked for.
+3. Run `rigor check` on the touched paths and report the result.
+4. **Say which lines the check covers.** A green `rigor check` proves
+   that the annotation contradicts nothing Rigor can currently see — it
+   does not prove the contract. Where the surrounding types are
+   `untyped`, there is nothing to contradict, and you must say so rather
+   than let a green run read as confirmation.
+
+If the check *does* go red, the annotation modeled the wrong contract:
+report it and revert, never suppress the diagnostic.
+
+The same holds for an inline annotation a human wrote as documentation —
+`#: void`, `#: :asc | :desc`, a parameter contract. It is their intent,
+checked by `rigor check`, not a guess for you to "correct" to what inference
+shows. Leave it; if the check finds a contradiction, report that.
+
+## Installing the rule in the project
+
+An agent that never loads this skill still guesses. The durable fix is
+one paragraph in the project's `AGENTS.md` / `CLAUDE.md`, so the rule is
+in context every session rather than only when a skill happens to
+trigger. The text to paste:
+[`references/02-agents-md-fragment.md`](references/02-agents-md-fragment.md).
+`rigor-project-init` installs it during onboarding.

data/skills/rigor-type-oracle/references/01-oracle-commands.md

@@ -0,0 +1,261 @@
+# 01 — The oracle commands, exactly
+
+Every command form here was taken from `rigor <cmd> --help` on the
+version this file ships with. If a flag below is missing from your
+`--help`, trust `--help`.
+
+All five commands are **read-only**: they analyse and print. None of them
+writes to your source tree. (`rigor sig-gen --write` does, and is the one
+form this skill never reaches for on its own — see § "Writing, not just
+reading".)
+
+## `rigor type-of` — the type of one expression
+
+```sh
+rigor type-of FILE:LINE[:COL] [FILE:LINE[:COL] ...]
+```
+
+| Option | Effect |
+| --- | --- |
+| `--format=text\|json` | `text` (default) or a JSON object per position. |
+| `--trace` | Also record fail-soft fallbacks via the tracer. |
+| `--config=PATH` | Explicit `.rigor.yml`. |
+| `--tmp-file=PATH` / `--instead-of=PATH` | Editor mode: analyse an unsaved buffer as if it were the project path. Paired. |
+
+**Position syntax.** `FILE:LINE:COL`, both **1-based**. The column may be
+omitted (`FILE:LINE`). Several positions in one invocation — that is the
+cheap way to ask about a whole method.
+
+Text output:
+
+```
+lib/demo/budget_ledger.rb:19:7
+node:    Prism::LocalVariableWriteNode
+type:    Array[Dynamic[top]]
+erased:  Array[untyped]
+```
+
+- `node` — the Prism node the position resolved to. Check it: if it is
+  not the expression you meant, your column is off, and the `type` below
+  it answers a different question.
+- `type` — Rigor's internal type. **This is the answer.**
+- `erased` — the same type spelled as RBS. **This is what you write into
+  a `.rbs` file or an annotation.** `Dynamic[top]` erases to `untyped`.
+
+JSON output is the same five fields:
+
+```json
+{ "file": "…", "line": 19, "column": 7,
+  "node": "Prism::LocalVariableWriteNode",
+  "type": "Array[Dynamic[top]]", "erased": "Array[untyped]" }
+```
+
+## `rigor annotate` — every line of a file at once
+
+```sh
+rigor annotate FILE
+```
+
+| Option | Effect |
+| --- | --- |
+| `--format=text\|json` | `text` (default), or JSON as a `{ line => type }` map. |
+| `--[no-]color` | Force / disable ANSI colour (auto-detects a tty; honours `NO_COLOR`). |
+| `--[no-]bat` | Force / disable highlighting through `bat`. |
+| `--config=PATH` | Explicit `.rigor.yml`. |
+
+Output is the source with each line's **last-expression type** appended
+after `#=>`:
+
+```ruby
+    def initialize(currency, opening_balance: 0)   #=> Dynamic[top]
+      @currency = currency                         #=> Dynamic[top]
+      @entries = []                                #=> []
+    end                                            #=> :initialize
+```
+
+Two reading rules that catch people out:
+
+- `#=>` is the type of the line's **last expression**, not of the
+  variable being assigned and not of the method being defined. A `def`
+  line's `#=>` is the *return* type of the method; the `end` line's
+  `#=>` is the symbol the `def` expression itself evaluates to
+  (`:initialize`) — that is Ruby, not a Rigor quirk. Ignore it.
+- One `#=>` per line. For a multi-expression line, or for a
+  sub-expression in the middle, go back to `type-of` with a column.
+
+Reach for `annotate` first when the task is "document this file" or "add
+types to this class": one call types everything, and the lines that come
+back `Dynamic[top]` are your gap list before you have written a word.
+
+## `rigor sig-gen` — the signature of a method
+
+```sh
+rigor sig-gen [paths]
+```
+
+| Option | Effect |
+| --- | --- |
+| `--print` | RBS to stdout. **Default** — you may omit it. |
+| `--diff` | Unified diff against the existing RBS. Read-only. |
+| `--write` | Write to `sig/<path>.rbs`. The only mode that touches the filesystem. |
+| `--overwrite` | Allow a tighter return to replace user-authored RBS. |
+| `--include-private` | Emit private / protected instance methods too (default: public only). |
+| `--params=untyped\|observed\|observed-strict` | Parameter policy. Default `untyped`. `observed-strict` is reserved and currently a usage error. |
+| `--observe=PATH` | Directory / file to scan for call-site observations. Repeatable. Defaults to `spec/` when present. |
+| `--new-files` / `--new-methods` / `--tighter-returns` | Emit only that classification. |
+| `--format=text\|json` | Text RBS, or the structured candidate report. |
+| `--config=PATH` | Explicit `.rigor.yml`. |
+
+Text output is RBS you paste as-is:
+
+```
+class Demo::BudgetLedger
+  # [new]
+  def record: (untyped, ?memo: untyped, ?at: untyped) -> Demo::BudgetLedger
+  # [new]
+  def entries_matching: (untyped) -> (Array[untyped] | [])
+end
+```
+
+**Read stderr.** A skip summary goes there, not to stdout:
+
+```
+rigor sig-gen: skipped 2 method(s) it could not type or would not overwrite
+(sig.skipped.untyped-return: 2). Run with --format=json to see each one with
+its skip_reason.
+```
+
+A method that is missing from the printed RBS was **skipped**, and a
+skip is a finding. `--format=json` names each one:
+
+```json
+{ "class": "Demo::BudgetLedger", "method": "balance", "kind": "instance",
+  "classification": "skipped", "skip_reason": "sig.skipped.untyped-return" }
+```
+
+Classifications: `new-file`, `new-method`, `tighter-return`, `equivalent`
+(nothing to tighten; silently dropped), `skipped`. Skip reasons and what
+each one means for you: [`03-gap-protocol.md`](03-gap-protocol.md).
+
+### Deriving a parameter type from call sites
+
+```sh
+rigor sig-gen --print --params=observed --observe spec lib/demo/budget_ledger.rb
+```
+
+`observed` collects argument types from every call site under the
+`--observe` paths, unions them per parameter position, and emits the
+union. The recogniser understands RSpec shapes — `RSpec.describe Foo`,
+bare `describe Foo`, `subject { … }` / `subject(:name) { … }`,
+`let(:name)` / `let!(:name)`, and `described_class.new(...)` — so a
+normal spec suite is already an observation corpus. No plugin needed.
+
+The result is *evidence*, and it is narrow evidence:
+
+```
+def initialize: ("JPY", ?opening_balance: 100) -> void
+def entries_matching: (Regexp) -> (Array[untyped] | [])
+```
+
+`(Regexp)` is a real derivation and adoptable. `("JPY")` and `100` are
+literal types — the union of what today's callers happen to pass, frozen
+as a contract. Widen those to the class before adopting
+(`String`, `Integer`), per [ADR-5](https://github.com/rigortype/rigor/blob/master/docs/adr/5-robustness-principle.md):
+lenient on parameters. The gate on any widening is that `rigor check`
+gains no new diagnostic.
+
+### Writing, not just reading
+
+This skill's job ends at *knowing* the type. `--write` is an edit to the
+project and belongs to whoever asked for it — propose `--diff` first, and
+run `rigor check` after. `--write` only ever writes inside the configured
+signature paths (`sig/` by default).
+
+## `rigor trace` — why the type is what it is
+
+```sh
+rigor trace FILE
+```
+
+| Option | Effect |
+| --- | --- |
+| `--format=text\|json` | `text` is an interactive animation; **use `json`** for the raw event stream. |
+| `--line=N` | Only replay events whose source range starts on line `N`. |
+| `--verbose` | Include every expression enter/result frame. |
+| `--delay=SECONDS` | Autoplay the text animation (default: step on key press). |
+| `--config=PATH` | Explicit `.rigor.yml`. |
+
+An agent wants `--format=json --line=N`: the text mode waits on
+keystrokes. Each event carries `kind`, `depth`, a `location`, the node
+`stack`, and a `data` payload — a `bind` event, for example, names the
+local and the type it received:
+
+```json
+{ "kind": "bind", "depth": 2,
+  "location": { "start_line": 20, "start_column": 25, "…": "…" },
+  "stack": ["CallNode", "CallNode"],
+  "data": { "name": "amount", "type": "Dynamic[top]" } }
+```
+
+Reach for it when `type-of` gave you `Dynamic[top]` and you need to name
+*where* the precision was lost before reporting the gap.
+
+## `rigor explain` — what a diagnostic rule means
+
+```sh
+rigor explain [<rule>]
+```
+
+| Option | Effect |
+| --- | --- |
+| `--format=text\|json` | Default `text`. |
+
+With no argument it lists every rule. With a rule id, a legacy alias, or
+a family prefix (`call`, `flow`, `assert`, `dump`, `def`) it prints the
+rule's firing conditions, the severity per profile, the evidence tier,
+and how to suppress it.
+
+**`explain` covers diagnostic rules only.** A `sig.skipped.*` id is a
+sig-gen *skip reason*, not a diagnostic rule — `rigor explain
+sig.skipped.untyped-return` answers `Unknown rule`. Skip reasons are
+documented in [`03-gap-protocol.md`](03-gap-protocol.md).
+
+## `rigor check` — the gate, not the oracle
+
+```sh
+rigor check [paths]
+```
+
+You need one flag family here: `--format=text|json|sarif|github|gitlab|checkstyle|junit|teamcity`,
+plus `--explain` to surface fail-soft fallback events as `:info`
+diagnostics. Everything else (`--baseline*`, `--workers`, `--incremental`,
+the cache flags) belongs to other skills.
+
+`check` never *sources* a type. Its role here is the verification half:
+after any annotation lands, `rigor check PATHS` must gain **no new
+diagnostic** versus before. Green is a non-contradiction proof, not a
+correctness proof — say which lines it actually covers.
+
+## The MCP tools
+
+With the Rigor MCP server wired up (`rigor-mcp-setup`), the same oracle
+is available as tool calls. Prefer them over shelling out; the results
+are the CLI's, so read them exactly as above.
+
+| Tool | Required arguments | Optional | Returns |
+| --- | --- | --- | --- |
+| `rigor_type_of` | `file` (string), `line` (integer, 1-based), `col` (integer, 1-based) | `config` | The inferred type at that location. |
+| `rigor_annotate` | `file` (string) | `config` | The source with each line's last-expression type appended. |
+| `rigor_sig_gen` | — (defaults to the configured paths) | `paths` (array of strings), `params` (`"untyped"` \| `"observed"`), `config` | The JSON candidate report — classifications, `rbs`, `inferred_return`, `skip_reason`. |
+| `rigor_check` | `paths` (array of strings) | `config` | The JSON diagnostic report. |
+| `rigor_explain` | — (omit `rule` to list every rule) | `rule` (string) | The rule catalogue entry, as JSON. |
+
+Two shape differences from the CLI worth knowing:
+
+- `rigor_sig_gen` returns the **JSON candidate report**, always — there
+  is no `--print` text mode and no `--diff`. Read `rbs` per candidate.
+- `rigor_sig_gen` exposes `params` but **not** `observe`; observation
+  falls back to `spec/` when present. Point it elsewhere from the CLI.
+
+`rigor_triage` and `rigor_coverage` are also served, and belong to
+`rigor-baseline-reduce` / `rigor-protection-uplift` rather than here.

data/skills/rigor-type-oracle/references/02-agents-md-fragment.md

@@ -0,0 +1,52 @@
+# 02 — The paragraph to keep in the project's agent contract
+
+A skill only binds an agent that loaded it. The rule below binds every
+session, because it lives in the file the agent reads at startup —
+`AGENTS.md`, or `CLAUDE.md` for Claude Code (which pulls `AGENTS.md` in
+with `@AGENTS.md` when both exist).
+
+Paste it verbatim. `rigor-project-init` installs it during onboarding; if
+the project is already onboarded, add it now.
+
+## Where it goes
+
+- **`AGENTS.md` exists** → append the section at the end. Do not
+  reorganise the file.
+- **Only `CLAUDE.md` exists** → append it there.
+- **Both exist** → put it in `AGENTS.md`; add `@AGENTS.md` to `CLAUDE.md`
+  only if it is not already pulled in.
+- **Neither exists** → create `AGENTS.md` with this as its first section.
+- **A "Types" / "Type checking" section already exists** → merge into it
+  rather than adding a second one, and keep the five bullets intact.
+
+Never overwrite unrelated content, and never rewrite a rule the project
+already wrote for itself — show the user the conflict instead.
+
+## The fragment
+
+```markdown
+## Types come from Rigor, not from reading code
+
+This project is type-checked by [Rigor](https://github.com/rigortype/rigor). A type you did not obtain from Rigor is a guess, and a guessed type is never written anywhere: not in `sig/`, not in an inline annotation (`#:`, `# @rbs`), not in a doc comment, not in a review comment, and not as the reason for a nil check or an `is_a?` guard.
+
+- The type of an expression: `rigor type-of FILE:LINE:COL`, or `rigor annotate FILE` for a whole file.
+- The signature of a method: `rigor sig-gen --print FILE`; paste what it prints, never what you expect.
+- A parameter type is the one thing inference does not give you: derive it from the call sites with `rigor sig-gen --observe PATH` and keep it only while `rigor check` stays green.
+- When Rigor answers `Dynamic[top]` or `untyped`, or `sig-gen` skips the method, do not fill the gap. Report the exact command and its output; the gap is the finding.
+- Every type you state to a human carries the command that produced it, so it can be re-run.
+
+The `rigor-type-oracle` skill (`rigor skill --full rigor-type-oracle`) has the full procedure. With the Rigor MCP server connected, `rigor_type_of`, `rigor_annotate`, and `rigor_sig_gen` are the same oracle as tool calls.
+```
+
+## Two notes for whoever installs it
+
+- **The single-long-line shape is deliberate.** Each bullet is one line,
+  however long. Some of these files are rendered as Markdown by tools
+  that turn a newline inside a paragraph into a line break, so a
+  column-wrapped bullet reads ragged. Do not re-wrap it to fit an editor
+  ruler.
+- **Tell the user it landed.** It is a change to the file that governs
+  every future agent session in the repo — it belongs in the "here is
+  what I created, and whether to commit it" report, not in a silent diff.
+  It should be committed: the point is that every contributor's agent
+  reads the same rule.

data/skills/rigor-type-oracle/references/03-gap-protocol.md

@@ -0,0 +1,128 @@
+# 03 — The gap protocol
+
+Rigor answering "I don't know" is not the oracle failing. It is the
+oracle telling you something the code alone would not have: precision is
+lost *here*, for *this* reason. That is worth more than the annotation
+you were about to write, and it is worth exactly nothing if you paper
+over it.
+
+**The rule: never convert a gap into a type.** Report it, locate it,
+route it.
+
+## Which output means which gap
+
+### `Dynamic[top]` (erased: `untyped`)
+
+Rigor has no class information for this expression at all. It is the
+top type, and it is contagious: a `Dynamic[top]` receiver makes every
+method call on it `Dynamic[top]` too, so one unresolved source can
+account for a whole file of "unknown".
+
+Common causes, in the order worth checking:
+
+- A **method parameter** — parameters are `untyped` by design unless RBS
+  or observation says otherwise. Not a defect; use call-site derivation.
+- An **ivar** assigned from a parameter (`@currency = currency`) — the
+  same gap, one hop later.
+- A call into a **gem with no RBS** — the dominant cause on a real
+  project.
+- A call into a **framework Rigor is not configured for** — Rails
+  without the Rails plugins enabled, say.
+- The project's **own monkey-patch or DSL**, which the analyzer never saw
+  defined.
+
+### `untyped` inside an otherwise-precise type
+
+`Array[untyped]`, `Hash[Symbol, untyped]`: the container is proven, the
+element is not. Write the container. Do **not** invent the element — an
+`Array[String]` you guessed is worse than the `Array[untyped]` Rigor
+proved, because it will be believed.
+
+### A method missing from `sig-gen` output — the `sig.skipped.*` reasons
+
+Read stderr for the count, `--format=json` for the per-method reason.
+
+| Reason | What it means | What you do |
+| --- | --- | --- |
+| `sig.skipped.untyped-return` | The body's last expression types as `Dynamic[top]`; emitting `untyped` would be noise. | The commonest gap. Trace the return expression back to its `Dynamic[top]` source and route *that*. Never write a return type here. |
+| `sig.skipped.user-authored` | An RBS declaration already exists and `--overwrite` was not given. | Not a gap. The hand-written type is the project's answer — read `sig/`, and if it disagrees with inference, raise the disagreement rather than silently retyping. |
+| `sig.skipped.unrenderable-rbs` | Rigor rendered a signature that does not parse as RBS, so it was dropped rather than written. | **A bug in Rigor**, not in the code. Report it with the method and the file. |
+| `sig.skipped.complex-shape` | Reserved; the generator does not produce it today. | If you ever see one, it is worth reporting as a surprise. |
+| `skipped_outside_sig_root` | A `--write` target outside the configured signature paths. | Configuration, not inference. |
+
+`rigor explain <id>` answers each of these ids directly (the command
+carries a second catalogue for the skip reasons alongside the
+diagnostic rules); this table is the summary.
+
+### `equivalent`, and silence
+
+A `tighter-return` candidate that never appears was classified
+`equivalent`: the inferred return is not a strict subtype of what `sig/`
+already declares. The existing declaration stands. Silence here means
+"nothing to change", not "nothing is known" — check `sig/` before calling
+it a gap.
+
+## Locating the gap before you report it
+
+Two commands turn "somewhere upstream" into a line number.
+
+```sh
+rigor annotate FILE          # walk the #=> column upward to the first Dynamic[top]
+rigor trace --format=json --line=N FILE
+```
+
+`annotate` is usually enough: the first line in the chain that reports
+`Dynamic[top]` is the source, and everything below it is cascade. Use
+`trace` when the loss happens *within* a line — its `bind` events name
+each local and the type it received, so you can see which argument
+arrived unknown.
+
+If a diagnostic fired near the site, `rigor explain <rule>` gives its
+firing conditions, which frequently name the cause outright.
+
+## Routing table — project-side gaps have an owner
+
+Once you know the source, the fix is almost never "write the type here".
+
+| The gap's source | Route to | Why |
+| --- | --- | --- |
+| A dependency gem ships no RBS | **`rigor-rbs-setup`** | `rbs collection install` brings in community RBS; this is the single biggest `Dynamic` reduction on most projects. |
+| A framework Rigor isn't configured for (Rails, RSpec, dry-rb…) | **`rigor-plugin-tune`** | The bundled plugin for it is probably just not enabled in `.rigor.dist.yml`. |
+| `undefined-method` on the project's own monkey-patches | **`rigor-monkeypatch-resolve`** | Wiring the defining files into `pre_eval:` makes them visible. |
+| The project's own DSL / `define_method` factory / `method_missing` | **`rigor-plugin-author`** | Rigor does not bundle per-application plugins; a project-owned plugin is the durable fix. |
+| The site is protected-coverage work, not a documentation task | **`rigor-protection-uplift`** | It owns the "minimal true annotation + double gate" loop. |
+| The setup itself looks wrong (zero RBS classes, config not taking) | **`rigor-doctor`** | Validate before concluding anything about inference. |
+| None of the above — Rigor should have inferred this | A Rigor issue | See below. |
+
+Offer the route; do not silently switch tasks. The user asked you to
+document a class, and "the reason I cannot is X, and here is the skill
+that fixes X" is the answer to that request.
+
+## Reporting an engine-side gap
+
+When the type is derivable from the source and Rigor still says
+`Dynamic[top]`, that is a completeness gap in the engine, and it is worth
+more to the project than any annotation. File it at
+<https://github.com/rigortype/rigor/issues> with these five parts:
+
+1. **The file and line** — the smallest reproduction you can get to,
+   ideally a standalone snippet rather than a pointer into a private
+   repo.
+2. **The exact command**, as run: `rigor type-of demo.rb:12:5`,
+   `rigor sig-gen --print demo.rb`.
+3. **The exact output**, pasted, including the stderr skip line.
+4. **What the correct type is, and what proves it** — the Ruby-level
+   reasoning a reader can verify. "`Array#sum` over `Integer` elements is
+   `Integer`", not "it should obviously be Integer".
+5. **What the report proves** — one sentence naming the *class* of gap,
+   not just the instance: "block-parameter destructuring loses the
+   element type", "a keyword default of `Time.now` does not seed the
+   parameter". This is the part that makes the issue actionable, because
+   it says what a fix would generalise to.
+
+Also say `rigor --version`, and note whether `sig/` and the relevant
+plugins were in play — a gap that only appears without community RBS is a
+different bug from one that survives it.
+
+Inside Rigor's own tree the same report is the deliverable: the gap is
+the reason not to hand-write the RBS there.