rigortype 0.1.11 → 0.1.13

data/skills/rigor-project-init/references/01-detect.md

@@ -0,0 +1,101 @@
+# 01 — Detect the project shape & select plugins
+
+Covers **Phase 1** (detect) and **Phase 3** (plugin selection). Run
+Phase 2 — the mode choice — from `SKILL.md` between them.
+
+## Phase 1 — Detect
+
+Read two files at the project root. Do not run code; just parse them.
+
+### `Gemfile` — framework family
+
+Scan the `gem "…"` lines for the markers below. A project can match
+more than one row (a Rails app with RSpec and Sidekiq matches three).
+
+| Marker gems | Family |
+| --- | --- |
+| `rails`, `railties`, `actionpack`, `activerecord` | Rails |
+| `sinatra` | Sinatra |
+| `dry-types`, `dry-struct`, `dry-schema`, `dry-validation` | dry-rb |
+| `rspec`, `rspec-core` | RSpec test suite |
+| `sorbet`, `sorbet-runtime` | Sorbet-typed |
+| none of the above | plain Ruby |
+
+Also note per-gem markers that have their own plugin: `devise`,
+`pundit`, `sidekiq`.
+
+### `Gemfile.lock` — versions & RBS state
+
+- Read the **locked versions** of the framework gems — a plugin
+  recommendation can depend on a major version.
+- Check for `rbs_collection.lock.yaml` at the project root AND whether
+  `.gem_rbs_collection/` exists alongside it.
+  - **Lockfile present, `.gem_rbs_collection/` present** → the collection
+    is installed; Rigor will auto-detect and consume it via
+    `rbs_collection.auto_detect: true` (the default).
+  - **Lockfile present, `.gem_rbs_collection/` absent** → the lockfile
+    was generated but the gems were never downloaded. Rigor loads the
+    lockfile but finds no RBS files. Note this for Phase 6: if triage
+    reports `gem-without-rbs` hints for gems that appear in
+    `rbs_collection.yaml`, run `rbs collection install` first and
+    re-run triage.
+  - **Both absent** → note it; Phase 6's triage may recommend
+    `rbs collection install` if `gem-without-rbs` hints appear.
+
+### Path scope
+
+Note the conventional source roots so Phase 4 can set `paths:`:
+
+- Rails → `app`, `lib`.
+- gem / library → `lib`.
+- plain app → `lib`, or the directory holding the code.
+
+`spec/` and `test/` are normally **excluded** from `paths:` — they
+are checked differently and inflate the diagnostic count. `vendor/`
+and `tmp/` are always excluded.
+
+## Phase 3 — Plugin selection
+
+Propose a plugin set from the detected families. Present it to the
+user as a list they can trim — do not silently enable everything.
+
+| Family | Recommended plugins |
+| --- | --- |
+| Rails | `rigor-actionpack`, `rigor-activerecord`, `rigor-actionmailer`, `rigor-rails-routes`, `rigor-rails-i18n`, plus `rigor-activesupport-core-ext` (almost always needed — see below) |
+| dry-rb | `rigor-dry-types`, `rigor-dry-struct`, and `rigor-dry-schema` / `rigor-dry-validation` when those gems are present |
+| Sinatra | `rigor-sinatra` |
+| RSpec | `rigor-rspec` |
+| Devise / Pundit / Sidekiq present | `rigor-devise` / `rigor-pundit` / `rigor-sidekiq` |
+| Sorbet present | `rigor-sorbet` (ingests existing `sig` blocks / RBI as type sources) |
+| plain Ruby | none required — the core analyzer covers it |
+
+The current production-plugin catalogue is the authority for which
+plugins exist and how each is named / installed:
+<https://github.com/rigortype/rigor/blob/master/plugins/README.md>.
+The set drifts as new plugins land — consult that page rather than
+treating the table above as exhaustive.
+
+### `rigor-activesupport-core-ext` — the common Rails gap
+
+ActiveSupport monkey-patches the core classes (`3.days`,
+`5.minutes`, `"x".squish`, `Time.current`, …). Without the
+`rigor-activesupport-core-ext` bundle, every such call reports
+`call.undefined-method` — on a real Rails app this is the single
+largest diagnostic cluster (a measured Mastodon run: ~365 of 489
+diagnostics were exactly this). Phase 5's `rigor triage` flags it as
+hint `activesupport-core-ext`.
+
+`rigor-activesupport-core-ext` is a **plugin** (an RBS-bundle plugin
+— it contributes signatures, not diagnostics). Activate it like any
+other: list it under `plugins:`. No `signature_paths:` wiring is
+needed — the plugin ships its own `sig/`. Include it for any
+Rails-family project.
+
+## Output of this module
+
+- A framework-family list.
+- A proposed, user-trimmed plugin set.
+- The `paths:` / `exclude:` scope for Phase 4.
+- Whether an RBS collection already exists.
+
+Carry these into Phase 4 ([`02-configure.md`](02-configure.md)).

data/skills/rigor-project-init/references/02-configure.md

@@ -0,0 +1,185 @@
+# 02 — Write the configuration
+
+Covers **Phase 4**. Inputs: the plugin set + path scope from
+[`01-detect.md`](01-detect.md), and the adoption mode chosen in
+Phase 2.
+
+## `.rigor.dist.yml` vs `.rigor.yml`
+
+Rigor reads both. The convention:
+
+- **`.rigor.dist.yml`** — the committed, shared project config. This
+  skill writes this file.
+- **`.rigor.yml`** — an optional, gitignored per-developer override.
+  Leave it for individuals to create; do not write one here.
+
+When both exist, `.rigor.yml` takes precedence. Writing the shared
+config as `.rigor.dist.yml` lets a contributor opt out locally (for
+example, run without the baseline) without touching the committed
+file.
+
+## Severity profile — follows the mode
+
+The `severity_profile:` key re-stamps every rule's severity. Set it
+from the Phase 2 mode:
+
+| Mode | `severity_profile` | Why |
+| --- | --- | --- |
+| Acknowledge, >100 errors on first run | `lenient` | Most rules become warnings; the baseline carries the residue. The point is the regression guard, not a wall of errors. |
+| Acknowledge, small project | `balanced` | The default. Errors stay errors; the baseline is small enough to live with. |
+| Strict | `strict` | Promotes borderline rules to errors. Paired with no baseline, every diagnostic is a live gate. |
+
+`balanced` is the built-in default — omit the key to get it.
+
+## No separate installation needed
+
+All plugins ship **bundled inside the `rigortype` gem**. The
+`plugins:` list in the config is all that is needed to activate
+them — the plugin loader runs `require "rigor-<id>"` from within
+the gem's own load path. No Gemfile entry, no `bundle install`,
+no separate gem channel.
+
+**The `rigortype` gem itself stays out of the project's
+`Gemfile`** — install it standalone per the manual's
+[Installing Rigor](../../docs/manual/01-installation.md) chapter
+(`mise use gem:rigortype` is the recommended channel). The
+project's Gemfile is untouched by this workflow.
+
+## The template
+
+Write `.rigor.dist.yml` at the project root. A Rails app in
+acknowledge mode looks like:
+
+```yaml
+# .rigor.dist.yml — Rigor configuration (committed; shared).
+# Generated by the rigor-project-init workflow.
+
+# Match the Ruby version in .ruby-version or the Gemfile `ruby "x.y"` line.
+# Rigor defaults to 4.0; set this explicitly if the project targets Ruby < 4.0.
+target_ruby: "3.4"
+
+paths:
+  - app
+  - lib
+
+exclude:
+  - vendor
+  - tmp
+
+plugins:
+  - rigor-actionpack
+  - rigor-activerecord
+  - rigor-actionmailer
+  - rigor-rails-routes
+  - rigor-rails-i18n
+  # An RBS-bundle plugin — ships ActiveSupport core_ext signatures,
+  # no signature_paths: wiring needed (see 01-detect.md).
+  - rigor-activesupport-core-ext
+
+severity_profile: lenient
+
+# Phase 6 (acknowledge mode) appends this line after generating the
+# baseline. Strict mode leaves it out entirely.
+# baseline: .rigor-baseline.yml
+```
+
+### Existing `sig/` directory
+
+If the project already has a `sig/` directory (from Steep, `rbs_rails`,
+or handwritten annotations), wire it into `signature_paths:` so Rigor
+consumes it. Phase 5 (sig uplift) can be skipped, but the paths must
+still be declared — Rigor does not auto-detect `sig/`:
+
+```yaml
+signature_paths:
+  - sig/handwritten   # adjust to the layout in your project
+  - sig/generated
+```
+
+List only directories that contain `.rbs` files or subdirectories of
+them. Rigor walks each path recursively. If the sig layout is a single
+flat `sig/` directory, use `- sig` instead.
+
+A strict-mode plain-Ruby gem is shorter:
+
+```yaml
+paths:
+  - lib
+severity_profile: strict
+```
+
+### Key reference
+
+Only the keys this skill needs. `rigor --help` and the project
+handbook document the full surface.
+
+| Key | Meaning |
+| --- | --- |
+| `paths:` | Directories Rigor analyses. Source roots only — not `spec/` / `test/`. |
+| `exclude:` | Paths removed from the `paths:` walk. |
+| `plugins:` | Plugin ids to activate (the Phase 3 set). |
+| `signature_paths:` | Extra RBS source **directories** (paths, not gem names; resolved relative to the config file). Use it for the project's own local `sig/` if it has one. RBS-bundle *plugins* like `rigor-activesupport-core-ext` ship their own `sig/` and need no entry here — list them under `plugins:`. |
+| `severity_profile:` | `lenient` / `balanced` / `strict`. See the table above. |
+| `severity_overrides:` | Per-rule severity tweaks. Leave empty at init; the baseline-reduce workflow tunes it later. |
+| `baseline:` | Path to the baseline file. **Only acknowledge mode sets it**, and only in Phase 6 *after* the file exists. Per Rigor's no-magic rule, a `.rigor-baseline.yml` on disk does nothing until this key names it. |
+| `pre_eval:` | Project files Rigor walks before per-file inference — used to register in-project monkey-patches. Leave empty at init; Phase 7 may suggest it. |
+| `dependencies.source_inference:` | Opt-in inference for gems shipping no RBS. Leave empty at init; Phase 7 may suggest it. |
+
+## Do not write the baseline yet
+
+Phase 4 writes the config with the `baseline:` line **commented out
+or absent**. The baseline file does not exist until Phase 6, and a
+`baseline:` pointing at a missing file is an error. Phase 6 writes
+the file and uncomments / appends the line in one step.
+
+Strict mode never adds `baseline:` at all.
+
+## Verify plugin activation (`rigor plugins`)
+
+Before proceeding to sig uplift, **run `rigor plugins`** from the
+project root to confirm every entry under `plugins:` actually
+loaded. The activation surface is the part of the configuration
+most prone to silent failure — a typoed gem name, a missing
+third-party plugin gem, or running rigor from a different cwd
+(so a different `.rigor.yml` is discovered) all leave plugins
+inert, which the per-file diagnostic stream then attributes to
+"missing types" rather than to a config gap.
+
+```sh
+rigor plugins
+```
+
+Expected: every entry shows `[OK ]`, the `loaded: N` count
+matches the entries in `plugins:`, and `load-error: 0`. The
+report also lists each plugin's `signature_paths:` (with a
+per-directory `.rbs` file count) and any `open_receivers:` /
+`owns_receivers:` / `produces:` / `consumes:` / macro substrate
+contributions — useful for confirming the plugin is contributing
+what you expect.
+
+If any entry shows `[ERR]`, read the `load error:` line:
+
+| Error fragment | Cause | Fix |
+| --- | --- | --- |
+| `could not load plugin gem "rigor-foo"` | The gem is not on the load path. Either misspelled in `plugins:`, or a third-party plugin (per ADR-31 WD4) that is not installed in the rigor runtime environment. | Check spelling against the catalogue in `01-detect.md`; for third-party plugins, install via the same channel that installed `rigortype` (mise / gem install). |
+| `did not register any plugin via Rigor::Plugin.register` | The require succeeded but the gem did not call `Rigor::Plugin.register`. Usually a version mismatch (older / forked rigor-foo) or a partial install. | Reinstall the plugin gem; verify the version matches `rigortype`'s. |
+| `signature path "..." is not a directory` | The bundled `sig/` directory is missing — a packaging bug in the plugin gem. | File an issue against the plugin gem's repo. |
+| `plugin "foo" config invalid: ...` | The `config:` block under the plugin entry has a typo or wrong value type. | Compare against the plugin's documented `config_schema:`. |
+
+Re-run `rigor plugins` until `load-error: 0`. Add `--strict` to
+the invocation when you want it to exit 1 (the canonical CI gate
+shape):
+
+```sh
+rigor plugins --strict
+```
+
+## Output of this module
+
+A committed `.rigor.dist.yml` with `paths:`, `exclude:`,
+`plugins:`, and `severity_profile:` set — and no active
+`baseline:` line. `rigor plugins` reports every entry loaded,
+zero load errors. No Gemfile changes; plugins are bundled inside
+`rigortype`.
+
+Proceed to Phase 5 ([`04-sig-uplift.md`](04-sig-uplift.md)).

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

@@ -0,0 +1,168 @@
+# 03 — Triage, baseline, and surfacing real bugs
+
+Covers **Phase 6** (triage), **Phase 7** (baseline — acknowledge mode
+only), and **Phase 8** (real bugs + escalation).
+
+## Phase 6 — Triage the diagnostic stream
+
+Do **not** read the raw `rigor check` output to decide what to do. A
+mature codebase's raw stream is hundreds of lines and reads as
+hundreds of unrelated problems — it is the wrong first artefact. Run
+the triage command instead:
+
+```sh
+rigor triage --format json
+```
+
+`rigor triage` runs the same analysis as `rigor check`, then returns
+a structured summary instead of the per-line dump. It is read-only
+and advisory — it never edits config and never writes a baseline.
+The JSON shape:
+
+```json
+{
+  "summary":      { "total": 489, "error": 480, "warning": 9, "info": 0 },
+  "distribution": [ { "rule": "call.undefined-method", "count": 437 } ],
+  "hotspots":     [ { "file": "app/models/status.rb", "count": 42,
+                      "by_rule": { "call.undefined-method": 40 } } ],
+  "hints": [
+    { "id": "activesupport-core-ext", "confidence": "likely",
+      "diagnostic_count": 365, "summary": "...", "action": "..." }
+  ]
+}
+```
+
+Use the three sections like this:
+
+- **`summary` / `distribution`** — the scale, and which rules
+  dominate. Decides nothing on its own; feeds the mode sanity-check
+  (>100 errors → acknowledge mode is the right default).
+- **`hotspots`** — files carrying the most diagnostics. A single hot
+  file is often one structural cause, not many bugs.
+- **`hints`** — the heuristic catalogue. Each hint names a *likely
+  cause* and a *suggested action*. They are signal, not verdicts —
+  the `confidence` field is `likely` or `possible`; verify before
+  acting.
+
+### Hint catalogue → what to do
+
+| Hint `id` | Cause | Where this skill handles it |
+| --- | --- | --- |
+| `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. | Phase 7 escalation — `rbs collection install`, or `dependencies.source_inference:`, or open a Rigor issue. |
+| `project-monkey-patch` | An in-project monkey-patch / refinement Rigor did not see. | Phase 7 escalation — register the defining file via `pre_eval:`, or (if it is a DSL) write a project plugin. |
+| `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. |
+
+If triage flags `activesupport-core-ext` (or any config gap),
+**fix the config and re-run `rigor triage` before continuing**. The
+baseline and the real-bug review should both run against the
+post-config diagnostic set, not the inflated one.
+
+## Phase 7 — Generate the baseline (acknowledge mode only)
+
+**Strict mode skips this phase entirely.** A strict project has no
+baseline; every diagnostic stays live.
+
+In acknowledge mode, snapshot today's diagnostics:
+
+```sh
+rigor baseline generate
+```
+
+This writes `.rigor-baseline.yml` at the project root — one
+`(file, rule, count)` bucket per cluster. The command refuses to
+overwrite an existing baseline without `--force`.
+
+Then **wire it into the config**. Per Rigor's no-magic rule, the
+baseline file does nothing until `.rigor.dist.yml` names it. Add (or
+uncomment) the line written in Phase 4:
+
+```yaml
+baseline: .rigor-baseline.yml
+```
+
+`rigor baseline generate` prints a note reminding you of this if the
+config does not yet declare `baseline:`. Do both edits — generate and
+wire — in one step so the user never has a generated baseline that
+silently does nothing.
+
+How the baseline behaves afterwards (acknowledge mode's whole point):
+
+- A `(file, rule)` bucket is silenced while its live count stays at
+  or below the recorded number.
+- If a commit pushes a bucket *over* its recorded count, **every**
+  diagnostic in that bucket surfaces — the bucket is now a regression
+  to review.
+- New `(file, rule)` pairs that were not in the baseline surface
+  immediately.
+
+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.
+
+Print the suppression summary for the user: "N diagnostics recorded
+as baseline; M will surface on subsequent runs."
+
+## Phase 8 — Surface real bugs & offer escalation
+
+The triage `genuine-bugs` hint (and any low-count, scattered rule in
+`distribution`) points at the diagnostics most likely to be **actual
+bugs** — a `nil`-receiver crash on a rarely-exercised line, a typo'd
+method. In **both modes**, surface 2–3 of these to the user and offer
+to walk them: a small, scattered rule is rarely systemic.
+
+In acknowledge mode these still went into the baseline — that is
+fine; the baseline is a starting envelope, not a verdict that the
+bug is acceptable. Recommend the user run the `rigor-baseline-reduce`
+skill next to work them down.
+
+### Escalation path A — application-specific metaprogramming
+
+If triage reports `project-monkey-patch`, or a `call.undefined-method`
+cluster lands on the project's own DSL / `define_method` factory /
+in-house macro, Rigor cannot follow it by default. Two answers,
+cheapest first:
+
+1. **A plain monkey-patch in a known file** (e.g.
+   `lib/core_ext/string_extensions.rb`) — register it via `pre_eval:`
+   in `.rigor.dist.yml`. Rigor walks those files before per-file
+   inference, so the added methods become visible.
+2. **A genuine project DSL** — the durable fix is a **project-private
+   Rigor plugin** that teaches Rigor the DSL's shape. Offer to hand
+   off to the `rigor-plugin-author` skill. The plugin can live under
+   the project's own `lib/` (loaded without a gemspec) or as a
+   separate `rigor-<name>` gem.
+
+### Escalation path B — an unsupported external gem
+
+If triage reports `gem-without-rbs`, a dependency ships no type
+information and Rigor has no built-in coverage. In order:
+
+1. `rbs collection install` — pulls community RBS for the gem if it
+   exists. Re-run triage afterwards.
+2. `dependencies.source_inference:` in `.rigor.dist.yml` — opt the
+   gem into Rigor inferring `Dynamic`-typed returns from its source.
+3. If the gem is widely used and genuinely warrants first-class
+   support, **open an issue on the Rigor project** so the maintainers
+   can ship a plugin or RBS bundle:
+   <https://github.com/rigortype/rigor/issues>. Include the gem name,
+   version, and a sample of the diagnostics.
+
+Neither escalation is mandatory — offer them when triage points at
+the cause; the user decides whether to act now or defer.
+
+## Output of this module — onboarding complete
+
+- A committed `.rigor.dist.yml`.
+- Acknowledge mode: a committed `.rigor-baseline.yml` + an active
+  `baseline:` line. Strict mode: neither.
+- The user has seen the likely real bugs and knows the two escalation
+  paths.
+
+Next sessions: `rigor-baseline-reduce` to work the baseline down
+(acknowledge mode), or `rigor-plugin-author` if escalation path A
+applies.

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

@@ -0,0 +1,171 @@
+# 04 — Generate initial RBS sigs and uplift precision
+
+Covers **Phase 5**. Inputs: the configured `.rigor.dist.yml` from
+Phase 4 and the detected source paths.
+
+## Why generate sigs before triaging
+
+Rigor's inference engine uses RBS signatures from `sig/` to sharpen
+its type flow. Without them, whole chains of methods fall back to
+`untyped`. Running `rigor triage` against an uninitialized `sig/`
+inflates the diagnostic count with cascade noise that sigs would
+eliminate. Generating sigs first means Phase 6's `rigor triage`
+report is as signal-rich as possible — the `genuine-bugs` hint
+counts bugs, not sig gaps.
+
+This phase is **optional if the project already has a `sig/`
+directory** with handwritten RBS annotations. In that case skip
+straight to Phase 6.
+
+## Step 5-a — Dry-run sig-gen
+
+Inspect what sig-gen would produce without writing anything:
+
+```sh
+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.
+
+To get a breakdown in JSON:
+
+```sh
+rigor sig-gen --format json lib | ruby -e '
+  require "json"
+  data = JSON.parse($stdin.read)["candidates"]
+  puts "=== classification breakdown ==="
+  data.group_by { |c| c["classification"] }
+      .sort_by { |k, _| k }
+      .each { |k, v| puts "  #{k}: #{v.size}" }
+  skipped = data.select { |c| c["classification"] == "skipped" }
+  puts "\n=== skip reasons ==="
+  skipped.group_by { |c| c["skip_reason"] }
+         .sort_by { |_, v| -v.size }
+         .each { |r, v| puts "  #{r}: #{v.size}" }
+'
+```
+
+## Step 5-b — Write the baseline sigs
+
+```sh
+rigor sig-gen --write lib
+```
+
+This creates `sig/**/*.rbs` with one method signature per inferred
+method. Check in a few files:
+
+```sh
+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.
+
+## 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
+important use case: **`attr_reader` / `attr_writer` / `attr_accessor`
+methods whose `@ivar` is assigned from an `initialize` parameter**.
+
+### Example
+
+```ruby
+class Person
+  attr_reader :name, :age
+
+  def initialize(name, age)
+    @name = name
+    @age  = age
+  end
+end
+
+Person.new("Alice", 30)
+Person.new("Bob",   25)
+```
+
+Without observations: `attr_reader :name` → skipped as `:untyped_return`
+(the ivar's type is unknown because the blank inference scope never
+sees the parameter values).
+
+With `--params=observed`: sig-gen accumulates `name → "Alice" | "Bob"`,
+`age → 25 | 30` from the `Person.new(...)` call sites, then propagates:
+`@name: ("Alice" | "Bob")` → `def name: () -> ("Alice" | "Bob")`.
+
+Run:
+
+```sh
+rigor sig-gen --params=observed --write lib
+```
+
+The cascade effect is significant: a single resolved `attr_reader`
+can unlock dozens of downstream methods whose precision depends on it.
+
+### Measuring the uplift
+
+```sh
+rigor sig-gen --format json lib | ruby -e '
+  require "json"
+  data = JSON.parse($stdin.read)["candidates"]
+  new_m = data.select { |c| c["classification"] == "new_method" }
+  untyped  = new_m.count { |c| (c["inferred_return"] || "").include?("untyped") }
+  concrete = new_m.count { |c| !(c["rbs"] || "").include?("untyped") }
+  puts "new_method: #{new_m.size} | still-untyped return: #{untyped} | concrete: #{concrete}"
+'
+```
+
+Run this before and after `--params=observed` to see how many methods
+resolved.
+
+## Step 5-d — Handle remaining untyped methods
+
+For methods still showing `untyped` return after `--params=observed`,
+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 |
+| 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) |
+
+Do not spend long on residual `untyped` methods at this stage — a
+handful of `untyped` returns in `sig/` does not block adoption. The
+objective is to reduce the false-positive count before triage, not to
+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)"
+```
+
+A committed `sig/` is a first-class project artefact: it improves
+inference quality on every subsequent run and is maintained alongside
+the source (add new sig files when adding classes; update sigs with
+`rigor sig-gen --write lib` when method signatures change).
+
+## Quick reference — sig-gen flags used in this phase
+
+| Flag | Effect |
+|---|---|
+| *(no flags)* | Print candidates to stdout; nothing written |
+| `--write` | Write `sig/**/*.rbs` files |
+| `--params=observed` | Collect observed argument types from call sites; used to resolve attr_reader / attr_accessor / attr_writer ivar types from initialize observations |
+| `--format json` | Output structured JSON (for scripted analysis) |
+| `--diff` | Show what would change vs. existing sigs (useful for incremental updates) |
+
+## Output of this module
+
+A committed `sig/` directory with RBS skeletons for all statically
+inferrable methods. Remaining `: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)).