rigortype 0.2.7 → 0.2.8

data/lib/rigor/cli/plugins_command.rb

@@ -14,16 +14,12 @@ require_relative "command"
 
 module Rigor
   class CLI
-    # `rigor plugins` — reports the activation status of every
-    # plugin entry in `.rigor.yml` so users (and the
-    # `rigor-project-init` SKILL, CI gates, `rigor init`) can
-    # verify their plugin configuration is actually doing what
+    # `rigor plugins` — reports the activation status of every plugin entry in `.rigor.yml` so users (and the
+    # `rigor-project-init` SKILL, CI gates, `rigor init`) can verify their plugin configuration is actually doing what
     # they think.
     #
-    # The command is read-only and idempotent: it loads the
-    # project's `.rigor.yml` (same discovery as `rigor check`),
-    # runs `Plugin::Loader.load` to attempt instantiation, then
-    # prints a table of:
+    # The command is read-only and idempotent: it loads the project's `.rigor.yml` (same discovery as `rigor check`),
+    # runs `Plugin::Loader.load` to attempt instantiation, then prints a table of:
     #
     # - load status (`loaded` / `load-error` with reason);
     # - resolved manifest id, version, description;
@@ -39,13 +35,12 @@ module Rigor
     #   class — `node_rule` node types, `dynamic_return` receivers,
     #   `narrowing_facts` methods.
     #
-    # `--capabilities` switches to a focused catalogue of just the
-    # narrow-protocol gate values + produced/consumed facts (ADR-37
-    # § "Machine-readable capability catalogue") — the AI-legibility
-    # surface that lets an agent enumerate what every plugin does.
+    # `--capabilities` switches to a focused catalogue of just the narrow-protocol gate values + produced/consumed facts
+    # (ADR-37 § "Machine-readable capability catalogue") — the AI-legibility surface that lets an agent enumerate what
+    # every plugin does.
     #
-    # Output formats: `text` (default, human-readable table) and
-    # `json` (for tooling — SKILLs, CI gates, editor integrations).
+    # Output formats: `text` (default, human-readable table) and `json` (for tooling — SKILLs, CI gates, editor
+    # integrations).
     #
     # Exit codes:
     # - `0` — every configured plugin loaded.
@@ -83,13 +78,10 @@ module Rigor
 
       private
 
-      # Picks the renderer view. `--capabilities` switches to the
-      # focused extension-protocol catalogue (ADR-37 § "Machine-readable
-      # capability catalogue") — per plugin, only the gate values that
-      # tell a reader (or an AI agent) exactly what the plugin
-      # contributes: the node-rule node types, the dynamic-return
-      # receivers, the type-specifier methods, and the produced /
-      # consumed facts. The default view stays the full activation report.
+      # Picks the renderer view. `--capabilities` switches to the focused extension-protocol catalogue (ADR-37 §
+      # "Machine-readable capability catalogue") — per plugin, only the gate values that tell a reader (or an AI agent)
+      # exactly what the plugin contributes: the node-rule node types, the dynamic-return receivers, the type-specifier
+      # methods, and the produced / consumed facts. The default view stays the full activation report.
       def render(renderer, options)
         json = options.fetch(:format) == "json"
         if options.fetch(:capabilities)
@@ -120,22 +112,18 @@ module Rigor
         raise OptionParser::InvalidArgument, "unsupported format: #{options.fetch(:format)}"
       end
 
-      # Runs the plugin loader against the project configuration
-      # and returns a row per declared plugin entry. Each row is
-      # a plain Hash with the fields enumerated in the class
-      # docstring so the renderer (text + JSON) reads from a
+      # Runs the plugin loader against the project configuration and returns a row per declared plugin entry. Each row
+      # is a plain Hash with the fields enumerated in the class docstring so the renderer (text + JSON) reads from a
       # single shape.
       #
-      # The loader catches require / init failures and surfaces
-      # them through `registry.load_errors`; we merge those back
+      # The loader catches require / init failures and surfaces them through `registry.load_errors`; we merge those back
       # into the per-entry rows by matching on `plugin_ref`.
       def build_rows(configuration)
         services = build_services(configuration)
         registry = Plugin::Loader.load(configuration: configuration, services: services)
 
         rows = configuration.plugins.map { |entry| row_for_entry(entry, registry) }
-        # Surface registry-level errors that did not bind to an
-        # entry (e.g. dependency-cycle errors that name multiple
+        # Surface registry-level errors that did not bind to an entry (e.g. dependency-cycle errors that name multiple
         # plugins). The renderer treats these as "orphan" errors.
         orphan_errors = orphan_load_errors(registry, rows)
         rows + orphan_errors
@@ -154,18 +142,15 @@ module Rigor
         gem_name = entry_gem_name(entry)
         config = entry_config(entry)
         plugin = registry.plugins.find do |p|
-          # The loader has already matched the entry to a plugin
-          # class; we can identify it by either the gem name (when
-          # the entry was a String) or the explicit id (when the
-          # entry was a Hash with `id:`).
+          # The loader has already matched the entry to a plugin class; we can identify it by either the gem name (when
+          # the entry was a String) or the explicit id (when the entry was a Hash with `id:`).
           plugin_matches_entry?(p, gem_name, entry_id(entry))
         end
 
         if plugin
           loaded_row(plugin, gem_name, config)
         else
-          # Find the load error whose plugin_ref names this entry
-          # (the ref is set by Loader to the gem name on require
+          # Find the load error whose plugin_ref names this entry (the ref is set by Loader to the gem name on require
           # failures and to the manifest id on later failures).
           error = registry.load_errors.find do |e|
             ref = e.plugin_ref.to_s
@@ -178,8 +163,7 @@ module Rigor
       def plugin_matches_entry?(plugin, gem_name, entry_id)
         return true if entry_id && plugin.manifest.id == entry_id
 
-        # A bare gem entry conventionally has manifest.id equal to
-        # the gem name with the `rigor-` prefix stripped.
+        # A bare gem entry conventionally has manifest.id equal to the gem name with the `rigor-` prefix stripped.
         derived_id = gem_name.delete_prefix("rigor-")
         [derived_id, gem_name].include?(plugin.manifest.id)
       end
@@ -192,12 +176,10 @@ module Rigor
           .merge(load_error: nil)
       end
 
-      # ADR-37 narrow extension protocols. Unlike the 10 declarative
-      # manifest fields, these are class-level DSLs (`node_rule` /
-      # `dynamic_return` / `narrowing_facts`), so they are read off the
-      # plugin class rather than the manifest. The gate values — node
-      # types, receiver class names, specified method names — are the
-      # greppable, enumerable surface the capability catalogue exposes.
+      # ADR-37 narrow extension protocols. Unlike the 10 declarative manifest fields, these are class-level DSLs
+      # (`node_rule` / `dynamic_return` / `narrowing_facts`), so they are read off the plugin class rather than the
+      # manifest. The gate values — node types, receiver class names, specified method names — are the greppable,
+      # enumerable surface the capability catalogue exposes.
       def narrow_protocol_fields(plugin)
         klass = plugin.class
         {
@@ -269,10 +251,8 @@ module Rigor
         }
       end
 
-      # For each `signature_paths:` directory the plugin resolves
-      # against its gem root, report the absolute path and a
-      # quick `.rbs`-file count. The count is a sanity signal:
-      # an empty bundle directory loads silently today but
+      # For each `signature_paths:` directory the plugin resolves against its gem root, report the absolute path and a
+      # quick `.rbs`-file count. The count is a sanity signal: an empty bundle directory loads silently today but
       # contributes nothing.
       def signature_path_rows(plugin)
         plugin.signature_paths.map do |abs|
@@ -317,10 +297,8 @@ module Rigor
         end
       end
 
-      # Build orphan-error rows for load errors whose `plugin_ref`
-      # did not bind to any configured plugin entry (e.g. a
-      # dependency-cycle naming a plugin we already accounted for
-      # but reported alongside another). De-duplicates against
+      # Build orphan-error rows for load errors whose `plugin_ref` did not bind to any configured plugin entry (e.g. a
+      # dependency-cycle naming a plugin we already accounted for but reported alongside another). De-duplicates against
       # errors we already attached.
       def orphan_load_errors(registry, rows)
         attached_refs = rows.compact.flat_map { |row| [row[:gem], row[:id]].compact }.to_set

data/lib/rigor/cli/plugins_renderer.rb

@@ -4,15 +4,11 @@ require "json"
 
 module Rigor
   class CLI
-    # Renderer for `rigor plugins`. Produces a human-readable
-    # text table and a JSON representation from the same row
-    # shape (the Hash documented on
-    # {Rigor::CLI::PluginsCommand#loaded_row}).
+    # Renderer for `rigor plugins`. Produces a human-readable text table and a JSON representation from the same row
+    # shape (the Hash documented on {Rigor::CLI::PluginsCommand#loaded_row}).
     #
-    # The two formats carry the same content; JSON is meant for
-    # tooling (SKILLs, CI, editor integrations) while text is
-    # for interactive inspection. Rows are printed in the order
-    # the loader resolved them.
+    # The two formats carry the same content; JSON is meant for tooling (SKILLs, CI, editor integrations) while text is
+    # for interactive inspection. Rows are printed in the order the loader resolved them.
     class PluginsRenderer # rubocop:disable Metrics/ClassLength
       def initialize(rows:, configuration_path:)
         @rows = rows
@@ -42,12 +38,10 @@ module Rigor
         )
       end
 
-      # ADR-37 § "Machine-readable capability catalogue" — the focused
-      # per-plugin extension-protocol dump. Only loaded plugins appear
-      # (a plugin that failed to load contributes no capabilities), and
-      # each carries only the gate values an agent enumerates to learn
-      # what the plugin does: node-rule node types, dynamic-return
-      # receivers, type-specifier methods, and produced / consumed facts.
+      # ADR-37 § "Machine-readable capability catalogue" — the focused per-plugin extension-protocol dump. Only loaded
+      # plugins appear (a plugin that failed to load contributes no capabilities), and each carries only the gate values
+      # an agent enumerates to learn what the plugin does: node-rule node types, dynamic-return receivers,
+      # type-specifier methods, and produced / consumed facts.
       def capabilities_json
         JSON.pretty_generate(
           {
@@ -84,9 +78,8 @@ module Rigor
         lines
       end
 
-      # The non-empty capability surfaces for a plugin, each as a
-      # `label: a, b, c` string. Data-driven so the catalogue stays a
-      # single source of truth shared between the text and JSON views.
+      # The non-empty capability surfaces for a plugin, each as a `label: a, b, c` string. Data-driven so the catalogue
+      # stays a single source of truth shared between the text and JSON views.
       def capability_surfaces(row)
         [
           ["node_rule", row[:node_rule_types]],
@@ -169,9 +162,8 @@ module Rigor
         lines
       end
 
-      # ADR-37 narrow extension protocols (node_rule / dynamic_return /
-      # narrowing_facts). Surfaced in the full report alongside the
-      # declarative surfaces; `--capabilities` is the focused view.
+      # ADR-37 narrow extension protocols (node_rule / dynamic_return / narrowing_facts). Surfaced in the full report
+      # alongside the declarative surfaces; `--capabilities` is the focused view.
       def narrow_protocol_lines(row)
         lines = []
         lines << "        node_rule: #{row[:node_rule_types].join(', ')}" if row[:node_rule_types].any?

data/lib/rigor/cli/prism_colorizer.rb

@@ -4,14 +4,12 @@ require "prism"
 
 module Rigor
   class CLI
-    # Re-lexes Ruby source with Prism and wraps each token in an
-    # ANSI colour escape, producing IRB-style syntax highlighting.
+    # Re-lexes Ruby source with Prism and wraps each token in an ANSI colour escape, producing IRB-style syntax
+    # highlighting.
     #
-    # Rigor ships no runtime dependencies (ADR-0), so the `irb`
-    # gem's `IRB::Color` is not available; this module reproduces
-    # the same effect from Prism's own token stream. `rigor
-    # annotate` re-parses its annotated output through here before
-    # printing.
+    # Rigor ships no runtime dependencies (ADR-0), so the `irb` gem's `IRB::Color` is not available; this module
+    # reproduces the same effect from Prism's own token stream. `rigor annotate` re-parses its annotated output through
+    # here before printing.
     module PrismColorizer
       module_function
 
@@ -41,9 +39,8 @@ module Rigor
       # @return [String] the source with ANSI colour escapes, or
       #   the input unchanged when lexing surfaces an error.
       def colorize(source)
-        # Sources read under a POSIX locale arrive tagged US-ASCII even
-        # when they carry UTF-8 bytes; retag so the token regexes below
-        # do not raise on multibyte comments.
+        # Sources read under a POSIX locale arrive tagged US-ASCII even when they carry UTF-8 bytes; retag so the token
+        # regexes below do not raise on multibyte comments.
         source = source.dup.force_encoding(Encoding::UTF_8) unless source.encoding == Encoding::UTF_8
         result = Prism.lex(source)
         return source unless result.errors.empty?
@@ -51,9 +48,8 @@ module Rigor
         render(source, result.value)
       end
 
-      # Prism token offsets are BYTE offsets — slice with byteslice, or
-      # any multibyte character earlier in the source shifts every
-      # subsequent token boundary.
+      # Prism token offsets are BYTE offsets — slice with byteslice, or any multibyte character earlier in the source
+      # shifts every subsequent token boundary.
       def render(source, lexed)
         out = +""
         offset = 0
@@ -73,10 +69,8 @@ module Rigor
         out
       end
 
-      # The token after a `SYMBOL_BEGIN` (`:`) carries the symbol
-      # name — and Prism lexes `:then` / `:class` etc. as a
-      # keyword token — so it is painted with the symbol colour
-      # regardless of its own token type.
+      # The token after a `SYMBOL_BEGIN` (`:`) carries the symbol name — and Prism lexes `:then` / `:class` etc. as a
+      # keyword token — so it is painted with the symbol colour regardless of its own token type.
       def effective_category(token_type, previous_type)
         return :symbol if previous_type == :SYMBOL_BEGIN
 
@@ -87,8 +81,8 @@ module Rigor
         sgr = CATEGORY_SGR.fetch(category)
         return text if sgr.nil? || text.empty?
 
-        # Keep a trailing newline outside the colour span so the
-        # reset sits on the token's own line (comments include it).
+        # Keep a trailing newline outside the colour span so the reset sits on the token's own line (comments include
+        # it).
         trailing = text[/\s*\z/] || ""
         body = trailing.empty? ? text : text[0...-trailing.length]
         return text if body.empty?

data/lib/rigor/cli/protection_renderer.rb

@@ -6,17 +6,15 @@ require_relative "../inference/dynamic_origin"
 
 module Rigor
   class CLI
-    # Renders an {ProtectionReport} (ADR-63 Tier 1) as text or JSON. The text
-    # form leads with the protected ratio, then the highest-traffic untyped
-    # dispatches ("add a type here"), then the lowest-protected files. The
-    # framing is always *where to add a type*, never "your code is broken".
+    # Renders an {ProtectionReport} (ADR-63 Tier 1) as text or JSON. The text form leads with the protected ratio, then
+    # the highest-traffic untyped dispatches ("add a type here"), then the lowest-protected files. The framing is always
+    # *where to add a type*, never "your code is broken".
     class ProtectionRenderer
       TOP_CALLS = 15
       TOP_FILES = 10
 
-      # ADR-73 P6 / ADR-75 WD2 — the actionable axis for each tractability
-      # category, shown next to a hole's origin so a user knows whether (and
-      # how) a type can close it.
+      # ADR-73 P6 / ADR-75 WD2 — the actionable axis for each tractability category, shown next to a hole's origin so a
+      # user knows whether (and how) a type can close it.
       TRACTABILITY_HINTS = {
         Inference::DynamicOrigin::ADD_RBS => "add RBS",
         Inference::DynamicOrigin::ENABLE_PLUGIN => "enable a plugin / pre_eval",

data/lib/rigor/cli/protection_report.rb

@@ -4,31 +4,37 @@ require_relative "../inference/dynamic_origin"
 
 module Rigor
   class CLI
-    # ADR-63 Tier 1 — aggregates per-file {Inference::ProtectionScanner}
-    # results into a project-level protection report: the protected ratio, the
-    # per-file breakdown, and a ranked "add a type here" list keyed by the
-    # method called on an unprotected (`Dynamic`) receiver — the highest-traffic
-    # untyped dispatches, where a receiver annotation buys the most catching
-    # power.
+    # ADR-63 Tier 1 — aggregates per-file {Inference::ProtectionScanner} results into a project-level protection report:
+    # the protected ratio, the per-file breakdown, and a ranked "add a type here" list keyed by the method called on an
+    # unprotected (`Dynamic`) receiver — the highest-traffic untyped dispatches, where a receiver annotation buys the
+    # most catching power.
     FileProtection = Data.define(:path, :protected_count, :unprotected_count, :ratio)
     UntypedCall = Data.define(:method_name, :count, :examples, :dynamic_origin)
 
-    ProtectionReport = Data.define(:files, :untyped_calls, :parse_errors) do
+    ProtectionReport = Data.define(:files, :untyped_calls, :parse_errors, :cause_site_counts) do
       def total_protected = files.sum(&:protected_count)
       def total_unprotected = files.sum(&:unprotected_count)
       def grand_total = total_protected + total_unprotected
       def ratio = grand_total.zero? ? 1.0 : total_protected.to_f / grand_total
 
-      # ADR-73 P6 — total dispatch-site count per tractability axis across
-      # the classified holes (those with a recorded `dynamic_origin`), so a
-      # user sees at a glance how much of the untyped surface a type can
-      # actually close (`add_rbs`) vs. needs a plugin (`enable_plugin`) vs.
-      # is an engine gap. Keys are omitted when zero; an all-unclassified
-      # run yields `{}`.
+      # ADR-73 P6 / ADR-82 — total dispatch-site count per tractability axis across the classified holes (those with a
+      # recorded `dynamic_origin`), so a user sees at a glance how much of the untyped surface a type can actually close
+      # (`add_rbs`) vs. needs a plugin (`enable_plugin`) vs. is an engine gap. Keys are omitted when zero; an
+      # all-unclassified run yields `{}`. Computed per-site from `cause_site_counts` (not per method-group-dominant
+      # cause) so a group with mixed causes is attributed accurately.
       def tractability_summary
-        untyped_calls.each_with_object(Hash.new(0)) do |c, acc|
-          axis = c.dynamic_origin && Inference::DynamicOrigin.tractability(c.dynamic_origin)
-          acc[axis] += c.count if axis
+        cause_site_counts.each_with_object(Hash.new(0)) do |(cause, count), acc|
+          axis = cause && Inference::DynamicOrigin.tractability(cause)
+          acc[axis] += count if axis
+        end
+      end
+
+      # ADR-82 — per-site count of every dynamic-origin cause across all holes, including the causeless sites
+      # (keyed `"none"`). Unlike `add_a_type_here`'s per-method-group dominant cause, this is an exact
+      # per-site tally, so it is the faithful measure of provenance coverage (how many holes carry any cause).
+      def cause_site_totals
+        cause_site_counts.each_with_object({}) do |(cause, count), acc|
+          acc[(cause || :none).to_s] = count
         end
       end
 
@@ -38,6 +44,7 @@ module Rigor
           "unprotected" => total_unprotected,
           "protection_ratio" => ratio.round(4),
           "tractability_summary" => tractability_summary.transform_keys(&:to_s),
+          "cause_site_counts" => cause_site_totals,
           "files" => files.map do |f|
             { "path" => f.path, "protected" => f.protected_count,
               "unprotected" => f.unprotected_count, "ratio" => f.ratio.round(4) }
@@ -60,6 +67,7 @@ module Rigor
       def initialize
         @files = []
         @calls = Hash.new { |h, k| h[k] = { count: 0, examples: [], origins: Hash.new(0) } }
+        @cause_site_counts = Hash.new(0)
         @parse_errors = []
       end
 
@@ -73,6 +81,7 @@ module Rigor
           bucket[:count] += 1
           bucket[:examples] << "#{path}:#{site.line}" if bucket[:examples].size < 3
           bucket[:origins][site.dynamic_origin] += 1 if site.dynamic_origin
+          @cause_site_counts[site.dynamic_origin] += 1
         end
       end
 
@@ -87,7 +96,8 @@ module Rigor
                           dynamic_origin: origin)
         end
         untyped = calls.sort_by { |c| [-c.count, c.method_name] }
-        ProtectionReport.new(files: @files, untyped_calls: untyped, parse_errors: @parse_errors)
+        ProtectionReport.new(files: @files, untyped_calls: untyped, parse_errors: @parse_errors,
+                             cause_site_counts: @cause_site_counts)
       end
     end
   end

data/lib/rigor/cli/renderable.rb

@@ -6,12 +6,10 @@ module Rigor
   class CLI
     # Output-format dispatch shared by the `--format text|json` renderers.
     #
-    # Each renderer included this and then implemented `render_text` /
-    # `render_json`; the `render(data, format:)` entry point — route by
-    # the format string, raise one consistent `OptionParser::InvalidArgument`
-    # on anything else — was copied verbatim into every one. Centralising
-    # it keeps the unsupported-format wording and the text/json contract
-    # in a single place as new renderers and formats are added.
+    # Each renderer included this and then implemented `render_text` / `render_json`; the `render(data, format:)` entry
+    # point — route by the format string, raise one consistent `OptionParser::InvalidArgument` on anything else — was
+    # copied verbatim into every one. Centralising it keeps the unsupported-format wording and the text/json contract in
+    # a single place as new renderers and formats are added.
     module Renderable
       def render(data, format:)
         case format

data/lib/rigor/cli/show_bleedingedge_command.rb

@@ -11,15 +11,12 @@ module Rigor
   class CLI
     # Executes `rigor show-bleedingedge` (ADR-50 § WD2).
     #
-    # Prints the bleeding-edge overlay — the Rigor-maintained set of the
-    # next major's queued changes ({Rigor::BleedingEdge}) — as an
-    # explicit list, and reports which of them the project's
-    # `bleeding_edge:` configuration adopts. The overlay is empty in this
-    # release, so the command currently reports an empty set; it becomes
-    # the inspection surface ADR-50 describes once a feature is queued.
+    # Prints the bleeding-edge overlay — the Rigor-maintained set of the next major's queued changes
+    # ({Rigor::BleedingEdge}) — as an explicit list, and reports which of them the project's `bleeding_edge:`
+    # configuration adopts. The overlay is empty in this release, so the command currently reports an empty set; it
+    # becomes the inspection surface ADR-50 describes once a feature is queued.
     #
-    # Read-only: it loads `.rigor.yml` to resolve the active selection
-    # but runs no analysis.
+    # Read-only: it loads `.rigor.yml` to resolve the active selection but runs no analysis.
     class ShowBleedingedgeCommand < Command
       USAGE = "Usage: rigor show-bleedingedge [options]"
 

data/lib/rigor/cli/sig_gen_command.rb

@@ -11,30 +11,20 @@ module Rigor
   class CLI
     # Executes the `rigor sig-gen` command — ADR-14 slices 1–3.
     #
-    # Walks the given paths (or `configuration.paths` when none
-    # are supplied), classifies every reachable instance method
-    # via {Rigor::SigGen::Generator}, and either prints the
-    # resulting RBS skeletons / unified-style diffs (`--print`,
-    # `--diff`; slice 1) or writes them to the project signature
-    # tree via {Rigor::SigGen::Writer} (`--write`; slice 2).
+    # Walks the given paths (or `configuration.paths` when none are supplied), classifies every reachable instance
+    # method via {Rigor::SigGen::Generator}, and either prints the resulting RBS skeletons / unified-style diffs
+    # (`--print`, `--diff`; slice 1) or writes them to the project signature tree via {Rigor::SigGen::Writer}
+    # (`--write`; slice 2).
     #
-    # `--write` follows the established Ruby community
-    # convention: `lib/foo/bar.rb` → `sig/foo/bar.rbs`. New
-    # methods are inserted into the matching class declaration
-    # just before its closing `end`; new classes are appended
-    # to the file; non-existent target files are created. User-
-    # authored declarations are NEVER replaced unless
-    # `--overwrite` is set AND the candidate is a
-    # `tighter-return`.
+    # `--write` follows the established Ruby community convention: `lib/foo/bar.rb` → `sig/foo/bar.rbs`. New methods are
+    # inserted into the matching class declaration just before its closing `end`; new classes are appended to the file;
+    # non-existent target files are created. User-authored declarations are NEVER replaced unless `--overwrite` is set
+    # AND the candidate is a `tighter-return`.
     #
-    # Parameter policy defaults to `untyped`. `--params=observed`
-    # (slice 3) opts in to caller-side observation harvesting:
-    # the `ObservationCollector` walks `--observe=PATH...`
-    # (default `spec/` when no flag is given AND a `spec/`
-    # directory exists), unions per-position arg types, and the
-    # generator emits the union per ADR-5 clause 2.
-    # `--params=observed-strict` stays reserved-but-inert until
-    # the capability-role catalog ships (rejected with a usage
+    # Parameter policy defaults to `untyped`. `--params=observed` (slice 3) opts in to caller-side observation
+    # harvesting: the `ObservationCollector` walks `--observe=PATH...` (default `spec/` when no flag is given AND a
+    # `spec/` directory exists), unions per-position arg types, and the generator emits the union per ADR-5 clause 2.
+    # `--params=observed-strict` stays reserved-but-inert until the capability-role catalog ships (rejected with a usage
     # error so the surface stays stable).
     class SigGenCommand < Command
       USAGE = "Usage: rigor sig-gen [options] [paths]"
@@ -86,10 +76,8 @@ module Rigor
         SigGen::Renderer.new(out: @out).render_write(results: results, format: options.fetch(:format))
       end
 
-      # Slice 3 — collect call-site argument observations when
-      # `--params=observed` is set. When `--observe=PATH` is
-      # not specified, default to `spec/` (skipped silently
-      # when the directory is absent).
+      # Slice 3 — collect call-site argument observations when `--params=observed` is set. When `--observe=PATH` is not
+      # specified, default to `spec/` (skipped silently when the directory is absent).
       def collect_observations(configuration, options)
         return {} if options.fetch(:params) != "observed"