rigortype 0.3.8 → 0.4.0

data/skills/rigor-project-init/references/03-baseline-and-bugs.md

@@ -75,12 +75,12 @@ Use the sections like this:
 | --- | --- | --- |
 | `activesupport-core-ext` | ActiveSupport core-class monkey-patches not loaded. | Go back to Phase 3/4: add `rigor-activesupport-core-ext` to `plugins:` (it is an RBS-bundle plugin), re-run triage. This is a config gap, not a bug. |
 | `gem-without-rbs` | A dependency ships no RBS. | If `rbs_collection.lock.yaml` was present and Phase 1 installed the collection, re-run `rigor triage` — the hint may shrink or disappear. Otherwise: Phase 8 escalation — `bundle exec rbs collection install`, or `dependencies.source_inference:`, or open a Rigor issue. |
-| `project-monkey-patch-known` | **High confidence.** The engine proved the called method *is* defined by a project file (a reopened core/stdlib/gem class) but is not applied cross-file. The hint **names the defining file(s)**. | Phase 7 escalation — copy the named file(s) straight into `pre_eval:`. No detective work needed; the diagnostic already found the source. |
-| `project-monkey-patch` | An in-project monkey-patch / refinement Rigor did not see, inferred from the *spread* of the same method across ≥3 files (no proven def site). | Phase 7 escalation — find the defining file (grep for `def <method>` / `class <Receiver>`), register it via `pre_eval:`, or (if it is a DSL) write a project plugin. |
-| `unresolved-toplevel` | Toplevel calls (outside any `def`/`class`/`module`) that resolve to nothing visible — usually a script relying on a monkey-patch or a `require`d helper Rigor did not walk (ADR-34). | Phase 7 escalation — if a project file defines these (toplevel `def`, or a patch on `Object`/`Kernel`), list it in `pre_eval:`. If nothing defines them, treat as genuine typos / missing requires (Phase 8). |
+| `project-monkey-patch-known` | **High confidence.** The engine proved the called method *is* defined by a project file (a reopened core/stdlib/gem class) but is not applied cross-file. The hint **names the defining file(s)**. | Phase 6a — copy the named file(s) straight into `pre_eval:`. No detective work needed; the diagnostic already found the source. |
+| `project-monkey-patch` | An in-project monkey-patch / refinement Rigor did not see, inferred from the *spread* of the same method across ≥3 files (no proven def site). | Phase 6a — find the defining file (grep for `def <method>` / `class <Receiver>`), register it via `pre_eval:`, or (if it is a DSL) write a project plugin. |
+| `unresolved-toplevel` | Toplevel calls (outside any `def`/`class`/`module`) that resolve to nothing visible — usually a script relying on a monkey-patch or a `require`d helper Rigor did not walk (ADR-34). | Phase 6a — if a project file defines these (toplevel `def`, or a patch on `Object`/`Kernel`), list it in `pre_eval:`. If nothing defines them, treat as genuine typos / missing requires (Phase 8). |
 | `activerecord-relation-misinference` | An ActiveRecord relation inferred as `Array`. | Ensure `rigor-activerecord` is enabled (Phase 3). If it persists, it is an engine gap — open a Rigor issue. |
 | `systemic-file-cluster` | One file × one rule, large count. | Acknowledge mode: a clean baseline bucket. Strict mode: a single fix may clear many — review that file first. |
-| `genuine-bugs` | Low-count rules scattered across files. | **Phase 7** — these are the localised bugs Rigor caught. Review first, in both modes. Note: the hint groups all low-count rules regardless of severity — filter for `error` severity when prioritising actionable items. |
+| `genuine-bugs` | Low-count rules scattered across files. | **Phase 8** — these are the localised bugs Rigor caught. Review first, in both modes. Note: the hint groups all low-count rules regardless of severity — filter for `error` severity when prioritising actionable items. |
 
 If triage flags `activesupport-core-ext` (or any config gap),
 **fix the config and re-run `rigor triage` before continuing**. The
@@ -170,8 +170,8 @@ bundle exec rbs collection install   # if rbs is in Gemfile
 # or: rbs collection install
 ```
 
-Re-run `rigor triage`. If the `gem-without-rbs` count drops,
-re-generate the baseline against the new number.
+Re-run `rigor triage`. If the `gem-without-rbs` count drops, carry
+the new, smaller count into Phase 7.
 
 ## Phase 7 — Generate the baseline (acknowledge mode only)
 
@@ -215,7 +215,8 @@ So ordinary coding cannot quietly grow the diagnostic count: the
 baseline is a ceiling, not a blanket. Reducing it later is the
 `rigor-baseline-reduce` skill's job.
 
-Commit `.rigor-baseline.yml` — it documents project state.
+Recommend committing `.rigor-baseline.yml` — it documents project
+state; list it in the Final step's file inventory.
 
 Print the suppression summary for the user: "N diagnostics recorded
 as baseline; M will surface on subsequent runs."
@@ -288,18 +289,17 @@ sig issue.
 
 #### `call.argument-type-mismatch` on regex capture variables (`$1`, `$~`)
 
-Rigor infers `$1`, `$~`, and similar capture variables as
-`String | nil` everywhere, even inside `gsub`/`match` blocks where
-they are guaranteed non-nil by the match condition. Diagnostics of
-the form:
+Rigor narrows `$1`, `$~`, and similar capture variables to non-nil
+after a successful `=~` match and inside a `when /re/` branch. Where
+the match is guaranteed by some other shape Rigor does not track, they
+stay `String | nil`, and a diagnostic of the form:
 
 ```
 expected String, got String | nil   (on $1 / $~)
 ```
 
-are **engine FPs** (ADR-24 WD3 / known limitation). Note them as
-noise rather than surfacing them as bugs. They belong in the
-baseline.
+is an **engine FP** (ADR-24 WD3 / known limitation). Note it as noise rather than
+surfacing it as a bug; it belongs in the baseline.
 
 ### Escalation path A — application-specific metaprogramming
 

data/skills/rigor-project-init/references/04-sig-uplift.md

@@ -28,7 +28,8 @@ rigor sig-gen lib        # adjust path to match the paths: key
 Typical output at this point: most `new_method` candidates have
 literal or concrete return types (`"hello"`, `42`, `:done`, `nil`).
 Methods whose return type cannot be inferred show up with
-`skip_reason: :untyped_return` — these are the sig precision targets.
+`skip_reason: "sig.skipped.untyped-return"` — these are the sig
+precision targets.
 
 To get a breakdown in JSON:
 
@@ -50,6 +51,12 @@ rigor sig-gen --format json lib | ruby -e '
 
 ## Step 5-b — Write the baseline sigs
 
+If the project's `Steepfile` reads inline annotations (`inline: true`
+beside `signature "sig"`), first add `sig_gen:` / `inline_declared: skip`
+to `.rigor.yml`. Otherwise sig-gen copies every `# @rbs` / `#:`
+declaration into `sig/`, and Steep reports each copied method as
+`DuplicatedMethodDefinition`.
+
 ```sh
 rigor sig-gen --write lib
 ```
@@ -63,12 +70,18 @@ head -40 sig/lib/your_class.rbs
 
 At this point, `attr_reader` and `attr_accessor` methods that rely on
 ivar types set from `initialize` parameters will likely still be
-absent (classified as `:untyped_return`). Step 5-c fixes that.
+absent (skipped as `sig.skipped.untyped-return`). Step 5-c fixes that.
+An `attr_writer` or `attr_accessor` stays skipped even then unless its
+ivar is assigned from an `initialize` parameter: the writer stores
+whatever its caller passes, so the ivar reads untyped. That covers
+`@count = 0` and `@logger = Logger.new` alike, and any other method
+that returns the ivar.
 
 ## Step 5-c — Precision uplift with --params=observed
 
 `--params=observed` tells sig-gen to collect observed argument types
-from every call site it processes during the analysis pass. The most
+from the call sites in the project's test roots — the `test_paths:`
+Phase 4 wrote (`--observe=PATH` overrides them for one run). The most
 important use case: **`attr_reader` / `attr_writer` / `attr_accessor`
 methods whose `@ivar` is assigned from an `initialize` parameter**.
 
@@ -88,7 +101,8 @@ Person.new("Alice", 30)
 Person.new("Bob",   25)
 ```
 
-Without observations: `attr_reader :name` → skipped as `:untyped_return`
+Without observations: `attr_reader :name` → skipped as
+`sig.skipped.untyped-return`
 (the ivar's type is unknown because the blank inference scope never
 sees the parameter values).
 
@@ -129,9 +143,9 @@ there are a few options depending on the cause:
 | Pattern | Cause | Fix |
 |---|---|---|
 | `attr_reader :x` with `@x` never set in `initialize` | ivar set from a DB query, config read, or side effect | Add a hand-written sig: create (or edit) `sig/your_class.rbs` with `attr_reader x: String` |
-| Deep method chains on untyped receivers | Cascade from a gem with no RBS | `rbs collection install`; Phase 7 escalation path B |
+| Deep method chains on untyped receivers | Cascade from a gem with no RBS | `rbs collection install`; Phase 8 escalation path B |
 | Recursive or mutually recursive methods | Return type not inferrable without a base case | Add a `# @rbs return: YourType` inline annotation, or a hand-written sig |
-| Dynamic methods (`define_method`, DSL) | Metaprogramming Rigor cannot follow | Phase 7 escalation path A (project plugin) |
+| Dynamic methods (`define_method`, DSL) | Metaprogramming Rigor cannot follow | Phase 8 escalation path A (project plugin) |
 
 Do not spend long on residual `untyped` methods at this stage — a
 handful of `untyped` returns in `sig/` does not block adoption. The
@@ -140,12 +154,10 @@ reach perfect sig coverage.
 
 ## Step 5-e — Commit the sig/ directory
 
-Once you are satisfied with the initial sig quality:
-
-```sh
-git add sig/
-git commit -m "Add initial RBS sigs from rigor sig-gen (--params=observed)"
-```
+Once you are satisfied with the initial sig quality, recommend
+committing `sig/`: list it in the Final step's file inventory
+(`SKILL.md` § "Final step") rather than committing it here — the user
+confirms every commit.
 
 A committed `sig/` is a first-class project artefact: it improves
 inference quality on every subsequent run and is maintained alongside
@@ -164,8 +176,9 @@ the source (add new sig files when adding classes; update sigs with
 
 ## Output of this module
 
-A committed `sig/` directory with RBS skeletons for all statically
-inferrable methods. Remaining `:untyped_return` methods are noted for
+A `sig/` directory, ready to commit, with RBS skeletons for all
+statically inferrable methods. Remaining `sig.skipped.untyped-return`
+methods are noted for
 potential manual annotation; they do not block Phase 6.
 
 Proceed to Phase 6 ([`03-baseline-and-bugs.md`](03-baseline-and-bugs.md)).

data/skills/rigor-project-init/references/06-agent-contract.md

@@ -0,0 +1,67 @@
+# 06 — Install the agent type-contract into AGENTS.md / CLAUDE.md
+
+Covers **Phase 8a**. Input: an onboarded project (config written, sigs
+generated, baseline decided). Output: one section in the file the
+project's coding agents read at startup.
+
+## Why this is part of onboarding
+
+Everything the earlier phases produced — `sig/`, the baseline, the
+severity profile — is a record of what Rigor *proved*. The moment an AI
+agent starts contributing to the project, it can write types that Rigor
+never proved: a `@param currency [String]` in a doc comment, an
+rbs-inline `#:` that Rigor then ingests as a live contract. Those enter
+the same files, look identical to derived types, and are believed.
+
+The fix is not a tool. It is one paragraph in the project's agent
+contract, so the rule is in context every session rather than only when
+a skill happens to trigger: **a type not obtained from Rigor is a guess,
+and a guessed type is never written.**
+
+## The text
+
+The canonical fragment is served by the installed Rigor, so it stays
+current with the CLI it names:
+
+```sh
+rigor skill --full rigor-type-oracle
+```
+
+Its `references/02-agents-md-fragment.md` section carries the paragraph
+and the five bullets. Copy that block **verbatim** — including its
+single-long-line shape, which is deliberate (some renderers turn a
+newline inside a paragraph into a line break).
+
+Do not paraphrase it from memory, and do not shorten it: the five bullets
+are the load-bearing part — expression, method signature, parameter,
+the gap rule, and provenance.
+
+## Where it goes
+
+| Project state | What to do |
+| --- | --- |
+| `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; keep the five bullets intact. Never write a second, competing rule. |
+
+Never overwrite unrelated content. If the project already states a rule
+about type authorship that contradicts this one, stop and show the user
+the conflict — the project's own rule wins until they say otherwise.
+
+## Report it in the final step
+
+This is a change to the file that governs every future agent session in
+the repo, so it belongs in Phase 9's file inventory, not in a silent
+diff. Recommend committing it: the point is that every contributor's
+agent reads the same rule.
+
+## When to skip
+
+- The project has no coding-agent contract file **and** the user has said
+  they do not use AI agents on it. Offer once, accept "no".
+- The user declined it earlier in this session.
+
+Otherwise install it — an unonboarded agent is the one contributor that
+cannot be trained by review.

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

@@ -1,7 +1,9 @@
 ---
 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).
+description: >-
+  Close the protection gaps reported by `rigor coverage --protection`, using generated signatures before
+  minimal residual annotations and a no-new-diagnostics gate. Use when increasing bug-catching coverage
+  in an adopting project; not for Rigor's own tree, bundled plugins, or first-time setup.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -40,10 +42,6 @@ copy — just proceed. If `rigor` is not on `PATH`, this task needs it: run
 
 ## 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

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

@@ -1,7 +1,9 @@
 ---
 name: rigor-rbs-setup
-description: |
-  Install community RBS for the project's gems with `rbs collection install`, so Rigor stops typing calls into RBS-less dependencies as `Dynamic` and gains real coverage (and real bug-catching) on them. Rigor auto-detects the resulting `rbs_collection.lock.yaml` — no Rigor config change needed. Triggers: "set up rbs collection", "my gems type as Dynamic", "rigor check says N gems have no RBS available", "reduce false positives from untyped gems". NOT for first-time Rigor setup (use rigor-project-init first) and NOT for a gem that has no entry in the community collection (that needs rigor-plugin-author or a Rigor issue).
+description: >-
+  Install community RBS for a project's gems so Rigor can type dependencies that currently become
+  `Dynamic`. Use when `rbs collection` is missing or untyped gems limit coverage; not for first-time
+  Rigor setup or a gem with no community RBS entry.
 license: MPL-2.0
 metadata:
   version: 0.1.0

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

@@ -0,0 +1,226 @@
+---
+name: rigor-type-oracle
+description: >-
+  Obtain a Ruby type from Rigor before writing or asserting it, using `type-of`, `annotate`, or `sig-gen`
+  as appropriate. Use when adding RBS, inline annotations, Sorbet/YARD types, type-shaped docs, or
+  type-justified guards; not for Rigor setup or baseline reduction.
+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".
+
+## 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.