rigortype 0.3.8 → 0.4.0

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

@@ -0,0 +1,265 @@
+# 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 the configured `test_paths:` (unset: whichever of `spec/` and `test/` exist). |
+| `--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 (the JSON `classification` values): `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` has two catalogues.** A `sig.skipped.*` id is a sig-gen
+*skip reason*, not a diagnostic rule, but `rigor explain
+sig.skipped.untyped-return` answers it from a second catalogue (no
+severity, no profile, nothing to suppress). The table in
+[`03-gap-protocol.md`](03-gap-protocol.md) is the summary.
+
+## `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
+  reads the configured `test_paths:` (unset: whichever of `spec/` and
+  `test/` exist). To observe anything else, declare it in `test_paths:`
+  or use the CLI's `--observe`.
+
+`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,125 @@
+# 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.

data/skills/rigor-unused-adjudicate/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rigor-unused-adjudicate
-description: |
-  Find dead code in a Ruby project with `rigor unused` — establish what the report can see on THIS project first, then adjudicate every row before proposing any deletion. Use this whenever someone asks to find or remove dead code, unused classes, unused constants, or "code nobody calls", whenever they ask what a `rigor unused` report means or which rows are safe to delete, and whenever a dead-code cleanup, codebase inventory, or legacy audit comes up — even if they never say "rigor". The report is a review queue and not a defect list; on an adjudicated corpus target only 4 of 57 rows were genuinely dead, so acting on it directly produces mostly wrong deletions. NOT for deleting a specific class you already know is dead, and NOT for `rigor check` diagnostics (those are ordinary type errors).
+description: >-
+  Adjudicate a `rigor unused` report safely before proposing dead-code removal. Use when interpreting or
+  reviewing Rigor's unused classes/modules/constants, or when a cleanup is based on that report; not for
+  a specific deletion already known to be safe or for ordinary `rigor check` diagnostics.
 license: MPL-2.0
 metadata:
   version: 0.2.0
@@ -31,11 +33,14 @@ and skipping one is how a live class ends up on a deletion list.
 
 Run the report and answer these against the project in front of you.
 
-**Are framework roots actually supplied?** The summary prints
-`roots: N (M from plugins, …)`. On a framework application `0 from plugins`
-means nothing is naming your controllers, jobs or policies, so most of the
-report is noise. Stop and fix the plugin configuration — `rigor docs
-07-plugins` — rather than adjudicating hundreds of rows.
+**Are framework roots actually supplied?** When a plugin contributes roots, the
+summary's `roots:` line grows a parenthetical: `roots: N (M from plugins, K
+matched no declaration)`. The parenthetical is omitted entirely when no plugin
+contributed — so on a framework application, a bare `roots: N` with **no**
+`(… from plugins …)` note means nothing is naming your controllers, jobs or
+policies, and most of the report is noise. Stop and fix the plugin
+configuration — `rigor docs 07-plugins` — rather than adjudicating hundreds of
+rows.
 
 **Does the project ship signatures?** If `signature_paths:` is configured, also
 run with it emptied and compare:

data/skills/rigor-upgrade/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: rigor-upgrade
-description: |
-  Adopt a new Rigor version cleanly: after upgrading the `rigortype` gem, re-run the analysis, diff the diagnostics against the committed baseline, and sort the changes into genuine new catches (sharper inference), known sig-quality false positives, and the baseline you should regenerate. Triggers: "I upgraded Rigor, what changed?", "new diagnostics after gem update rigortype", "adopt the new Rigor version", "rigor baseline drifted after upgrade". NOT for first-time setup (use rigor-project-init) or routine baseline work unrelated to an upgrade (use rigor-baseline-reduce).
+description: >-
+  Adopt a new `rigortype` version by comparing its diagnostics with the committed baseline and separating
+  new catches from signature-quality false positives. Use after a Rigor gem upgrade; not for first-time
+  setup or routine baseline reduction.
 license: MPL-2.0
 metadata:
   version: 0.1.0
@@ -50,12 +52,15 @@ rigor --version
 ### Phase 2 — see the delta against the committed baseline
 
 ```sh
-rigor check
-rigor diff            # compare current diagnostics to the saved baseline JSON
+rigor check             # everything outside the committed baseline's envelope
+rigor baseline drift    # per-bucket movement against .rigor-baseline.yml
 ```
 
-`rigor diff` shows what is **new** relative to the baseline — that set is
-what the upgrade changed.
+With `baseline:` wired, `rigor check` already hides what the baseline
+covers, so what it prints is **new** relative to the baseline — that set
+is what the upgrade changed. `rigor baseline drift` adds the bucket view:
+buckets now over their recorded count, and buckets the new version
+cleared or shrank.
 
 ### Phase 3 — sort the new diagnostics
 
@@ -80,8 +85,8 @@ envelope so the regeneration does not bury what you just fixed:
 rigor baseline regenerate
 ```
 
-Commit the updated `.rigor-baseline.yml` together with any fixes, so the
-team adopts the same post-upgrade baseline.
+Recommend committing the updated `.rigor-baseline.yml` together with any
+fixes, so the team adopts the same post-upgrade baseline.
 
 ## Note