rigortype 0.2.7 → 0.2.8

data/lib/rigor/cli/skill_command.rb

@@ -4,20 +4,15 @@ require_relative "command"
 
 module Rigor
   class CLI
-    # `rigor skill` — discover and print the SKILL.md files
-    # bundled with the `rigortype` gem.
+    # `rigor skill` — discover and print the SKILL.md files bundled with the `rigortype` gem.
     #
-    # Rigor ships a small set of Agent Skills under `skills/` that
-    # walk an AI coding agent through onboarding (`rigor-project-init`),
-    # baseline reduction (`rigor-baseline-reduce`), and authoring a
-    # plugin (`rigor-plugin-author`). When Rigor is installed via
-    # `mise` / `gem install` / etc. the SKILL files live inside the
-    # gem checkout — the project being analysed has no copy, so an
-    # AI agent has no a priori way to find them.
+    # Rigor ships a small set of Agent Skills under `skills/` that walk an AI coding agent through onboarding
+    # (`rigor-project-init`), baseline reduction (`rigor-baseline-reduce`), and authoring a plugin
+    # (`rigor-plugin-author`). When Rigor is installed via `mise` / `gem install` / etc. the SKILL files live inside the
+    # gem checkout — the project being analysed has no copy, so an AI agent has no a priori way to find them.
     #
-    # Grammar (mirrors `rigor docs`): the positional slot is always a
-    # skill *name*; alternative outputs are flags, so a skill named
-    # `list` or `path` can never be shadowed by a verb.
+    # Grammar (mirrors `rigor docs`): the positional slot is always a skill *name*; alternative outputs are flags, so a
+    # skill named `list` or `path` can never be shadowed by a verb.
     #
     # - `rigor skill`              — list bundled skills (the default).
     # - `rigor skill <name>`       — print the SKILL.md body (header + body).
@@ -42,11 +37,9 @@ module Rigor
     #                                the SKILL. Also spelled `describe`, and
     #                                surfaced top-level as `rigor describe`.
     #
-    # The pre-v0.3.0 verb spellings `rigor skill list` / `print <name>` /
-    # `path <name>` still work but emit a stderr deprecation notice; they
-    # are removed in v0.3.0 (see docs/ROADMAP.md § "Scheduled CLI
-    # deprecations"). `describe` is a no-argument action, not a name-slot
-    # verb, so it stays first-class alongside `--describe`.
+    # The pre-v0.3.0 verb spellings `rigor skill list` / `print <name>` / `path <name>` still work but emit a stderr
+    # deprecation notice; they are removed in v0.3.0 (see docs/ROADMAP.md § "Scheduled CLI deprecations"). `describe` is
+    # a no-argument action, not a name-slot verb, so it stays first-class alongside `--describe`.
     class SkillCommand < Command
       USAGE = <<~USAGE
         Usage: rigor skill [<name>] [--full <name>] [--path <name>] [--list] [--describe]
@@ -74,13 +67,12 @@ module Rigor
           rigor skill path <name>    ->  rigor skill --path <name>
       USAGE
 
-      # The bundled skills live at `<gem_root>/skills/`. From
-      # `lib/rigor/cli/skill_command.rb` that is three directories up.
+      # The bundled skills live at `<gem_root>/skills/`. From `lib/rigor/cli/skill_command.rb` that is three directories
+      # up.
       SKILLS_ROOT = File.expand_path("../../../skills", __dir__)
 
-      # The verb subcommands the flags superseded keep working with a
-      # stderr deprecation notice until this version drops them. Each maps
-      # to the canonical advice printed and the flag it rewrites to.
+      # The verb subcommands the flags superseded keep working with a stderr deprecation notice until this version drops
+      # them. Each maps to the canonical advice printed and the flag it rewrites to.
       LEGACY_VERB_REMOVAL = "v0.3.0"
       LEGACY_VERBS = {
         "list" => { old: "list",         advice: "--list", flag: "--list" },
@@ -120,8 +112,8 @@ module Rigor
 
       private
 
-      # Translate a deprecated verb spelling into its flag form, warning
-      # once on stderr, so the dispatch above only handles canonical forms.
+      # Translate a deprecated verb spelling into its flag form, warning once on stderr, so the dispatch above only
+      # handles canonical forms.
       def rewrite_legacy_verb!
         spec = LEGACY_VERBS[@argv.first]
         return unless spec
@@ -159,14 +151,11 @@ module Rigor
         0
       end
 
-      # `rigor skill --full <name>` — the whole current procedure in one
-      # call: the SKILL.md body followed by each `references/*.md` inline.
-      # This is what the thinned SKILL bodies point a *frozen* copy at — a
-      # vendored copy of a skill (installed via `npx skills`) may lag the
-      # gem, so re-fetching the complete body here guarantees the reader
-      # follows the version that shipped with the installed Rigor, without
-      # needing a file-reading tool or reading a possibly-stale co-located
-      # `references/`.
+      # `rigor skill --full <name>` — the whole current procedure in one call: the SKILL.md body followed by each
+      # `references/*.md` inline. This is what the thinned SKILL bodies point a *frozen* copy at — a vendored copy of a
+      # skill (installed via `npx skills`) may lag the gem, so re-fetching the complete body here guarantees the reader
+      # follows the version that shipped with the installed Rigor, without needing a file-reading tool or reading a
+      # possibly-stale co-located `references/`.
       def run_full(name)
         return usage_error("`--full` requires a skill name") if name.nil?
 
@@ -197,13 +186,10 @@ module Rigor
         0
       end
 
-      # `rigor skill --describe` (also spelled `describe`) — ADR-73's
-      # live "brain", delegated to {SkillDescribe}: it probes the current
-      # project's state with cheap presence checks (it never runs `rigor
-      # check`), recommends the next skill to run, and prints every
-      # bundled skill's current frontmatter description, so the
-      # `rigor-next-steps` SKILL can route without copying any
-      # version-coupled guidance into itself.
+      # `rigor skill --describe` (also spelled `describe`) — ADR-73's live "brain", delegated to {SkillDescribe}: it
+      # probes the current project's state with cheap presence checks (it never runs `rigor check`), recommends the next
+      # skill to run, and prints every bundled skill's current frontmatter description, so the `rigor-next-steps` SKILL
+      # can route without copying any version-coupled guidance into itself.
       def run_describe
         require_relative "skill_describe"
 
@@ -211,10 +197,9 @@ module Rigor
         0
       end
 
-      # The header that precedes the SKILL.md body when an agent
-      # runs `rigor skill <name>`. Kept as `# `-prefixed comment lines
-      # so the combined output remains parseable as markdown — anything
-      # below `---` (the SKILL frontmatter marker) is unchanged.
+      # The header that precedes the SKILL.md body when an agent runs `rigor skill <name>`. Kept as `# `-prefixed
+      # comment lines so the combined output remains parseable as markdown — anything below `---` (the SKILL frontmatter
+      # marker) is unchanged.
       def render_print_header(skill)
         references_dir = File.join(File.dirname(skill.fetch(:path)), "references")
         ref_line = if File.directory?(references_dir)
@@ -247,14 +232,12 @@ module Rigor
         discover_skills.find { |s| s.fetch(:name) == name }
       end
 
-      # The `references/*.md` files bundled alongside a skill, sorted so the
-      # `NN-` prefixes drive read order.
+      # The `references/*.md` files bundled alongside a skill, sorted so the `NN-` prefixes drive read order.
       def reference_files(skill)
         dir = File.join(File.dirname(skill.fetch(:path)), "references")
         return [] unless File.directory?(dir)
 
-        # `Dir.glob` returns lexicographically sorted paths (Ruby 3.0+),
-        # so the `NN-` prefixes already drive read order.
+        # `Dir.glob` returns lexicographically sorted paths (Ruby 3.0+), so the `NN-` prefixes already drive read order.
         Dir.glob(File.join(dir, "*.md"))
       end
 

data/lib/rigor/cli/skill_describe.rb

@@ -4,27 +4,21 @@ require "yaml"
 
 module Rigor
   class CLI
-    # The presence-only project-state probe behind `rigor skill describe`
-    # (ADR-73 WD2). It stats files and opens only config / CI / lockfiles
-    # — it runs no analysis — so it is cheap and side-effect-free, and an
-    # agent can run it freely at any point. Split from {SkillDescribe} so
-    # the routing/rendering class stays focused.
+    # The presence-only project-state probe behind `rigor skill describe` (ADR-73 WD2). It stats files and opens only
+    # config / CI / lockfiles — it runs no analysis — so it is cheap and side-effect-free, and an agent can run it
+    # freely at any point. Split from {SkillDescribe} so the routing/rendering class stays focused.
     class ProjectStateProbe
-      # Config / baseline filenames the probe stats for. `CONFIG_FILENAMES`
-      # mirrors `Configuration::DISCOVERY_ORDER` (developer-local override
-      # first, committed default second) so the probe agrees with what
-      # `rigor check` would auto-discover.
+      # Config / baseline filenames the probe stats for. `CONFIG_FILENAMES` mirrors `Configuration::DISCOVERY_ORDER`
+      # (developer-local override first, committed default second) so the probe agrees with what `rigor check` would
+      # auto-discover.
       CONFIG_FILENAMES = %w[.rigor.yml .rigor.dist.yml].freeze
       BASELINE_FILENAME = ".rigor-baseline.yml"
-      # `rbs collection install`'s lockfile — Rigor auto-detects it at the
-      # project root and feeds each gem's community RBS into the signature
-      # paths, so its presence is the signal that the gem-RBS gap has been
-      # addressed.
+      # `rbs collection install`'s lockfile — Rigor auto-detects it at the project root and feeds each gem's community
+      # RBS into the signature paths, so its presence is the signal that the gem-RBS gap has been addressed.
       RBS_COLLECTION_LOCKFILE = "rbs_collection.lock.yaml"
 
-      # `Gemfile.lock` substrings that mark a Rails app, and the bundled
-      # Rails-family plugin ids — used to spot a configured Rails project
-      # that has not enabled any Rails plugin (a `rigor-plugin-tune` cue).
+      # `Gemfile.lock` substrings that mark a Rails app, and the bundled Rails-family plugin ids — used to spot a
+      # configured Rails project that has not enabled any Rails plugin (a `rigor-plugin-tune` cue).
       RAILS_LOCK_MARKERS = %w[railties actionpack activerecord actioncable].freeze
       RAILS_PLUGIN_MARKERS = %w[
         rigor-activerecord rigor-actionpack rigor-actionmailer rigor-activejob
@@ -53,11 +47,9 @@ module Rigor
 
       private
 
-      # True when Rails is in `Gemfile.lock` but the (present) config
-      # enables no Rails plugin — so `rigor-plugin-tune` (wiring the
-      # ActiveRecord / routes / i18n plugins) buys more than community RBS
-      # would (the 20260620 field trial's strap case). Only fires on an
-      # already-configured project; an un-configured Rails app routes to
+      # True when Rails is in `Gemfile.lock` but the (present) config enables no Rails plugin — so `rigor-plugin-tune`
+      # (wiring the ActiveRecord / routes / i18n plugins) buys more than community RBS would (the 20260620 field trial's
+      # strap case). Only fires on an already-configured project; an un-configured Rails app routes to
       # `rigor-project-init`, which selects the plugins itself.
       def rails_unconfigured?(config)
         return false if config.nil?
@@ -75,8 +67,7 @@ module Rigor
         false
       end
 
-      # `:wired` (a CI config mentions `rigor`), `:unwired` (a CI config
-      # exists but does not), or `:none`.
+      # `:wired` (a CI config mentions `rigor`), `:unwired` (a CI config exists but does not), or `:none`.
       def ci_state
         files = ci_config_files
         return :none if files.empty?
@@ -84,11 +75,9 @@ module Rigor
         files.any? { |path| file_mentions_rigor?(path) } ? :wired : :unwired
       end
 
-      # Editor-LSP signal — `:wired` (a committed `.vscode/` config names
-      # `rigor`), `:unwired` (a `.vscode/` is present but does not), or
-      # `:none`. Only VS Code is detectable here: Neovim / Emacs / Helix
-      # configs live in the user's home, not the repo, so editor-setup is
-      # otherwise a catalogue-only destination.
+      # Editor-LSP signal — `:wired` (a committed `.vscode/` config names `rigor`), `:unwired` (a `.vscode/` is present
+      # but does not), or `:none`. Only VS Code is detectable here: Neovim / Emacs / Helix configs live in the user's
+      # home, not the repo, so editor-setup is otherwise a catalogue-only destination.
       def editor_state
         vscode = File.join(@root, ".vscode")
         return :none unless File.directory?(vscode)
@@ -99,11 +88,9 @@ module Rigor
         files.any? { |path| file_mentions_rigor?(path) } ? :wired : :unwired
       end
 
-      # MCP-client signal — `:wired` (a committed project MCP config names
-      # `rigor`), `:unwired` (one is present but does not), or `:none`.
-      # Only the project-scoped configs are detectable (`.mcp.json`,
-      # `.cursor/mcp.json`); user-level client configs live in $HOME, so
-      # mcp-setup is otherwise a catalogue-only destination.
+      # MCP-client signal — `:wired` (a committed project MCP config names `rigor`), `:unwired` (one is present but does
+      # not), or `:none`. Only the project-scoped configs are detectable (`.mcp.json`, `.cursor/mcp.json`); user-level
+      # client configs live in $HOME, so mcp-setup is otherwise a catalogue-only destination.
       def mcp_state
         files = [".mcp.json", File.join(".cursor", "mcp.json")]
                 .map { |rel| File.join(@root, rel) }
@@ -127,20 +114,16 @@ module Rigor
       end
     end
 
-    # Builds the `rigor skill describe` report (ADR-73): a {ProjectStateProbe}
-    # snapshot, a recommended next skill, and the live catalogue of bundled
-    # skills with their current frontmatter descriptions. Extracted from
-    # {SkillCommand} so the command stays a thin dispatcher and this — the
-    # "live brain" — owns the routing.
+    # Builds the `rigor skill describe` report (ADR-73): a {ProjectStateProbe} snapshot, a recommended next skill, and
+    # the live catalogue of bundled skills with their current frontmatter descriptions. Extracted from {SkillCommand} so
+    # the command stays a thin dispatcher and this — the "live brain" — owns the routing.
     class SkillDescribe
-      # The entry-point SKILL itself — excluded from the catalogue because
-      # it is the skill being run, not a destination.
+      # The entry-point SKILL itself — excluded from the catalogue because it is the skill being run, not a destination.
       ENTRY_POINT_SKILL = "rigor-next-steps"
 
-      # Adoption-journey order for the catalogue and the order the
-      # recommendation decision tree walks. `rigor-ask` sits last: it is
-      # the journey-agnostic "answer a question about Rigor" companion the
-      # agent can offer at any point, never a presence-recommended step.
+      # Adoption-journey order for the catalogue and the order the recommendation decision tree walks. `rigor-ask` sits
+      # last: it is the journey-agnostic "answer a question about Rigor" companion the agent can offer at any point,
+      # never a presence-recommended step.
       CATALOG_ORDER = %w[
         rigor-project-init
         rigor-rbs-setup
@@ -180,17 +163,16 @@ module Rigor
 
       private
 
-      # The skills offered as "what to do next", in adoption-journey order.
-      # The entry-point skill is excluded, and unknown skills sort after
-      # the known journey, alphabetically.
+      # The skills offered as "what to do next", in adoption-journey order. The entry-point skill is excluded, and
+      # unknown skills sort after the known journey, alphabetically.
       def catalog_skills
         @skills
           .reject { |skill| skill.fetch(:name) == ENTRY_POINT_SKILL }
           .sort_by { |skill| [CATALOG_ORDER.index(skill.fetch(:name)) || CATALOG_ORDER.size, skill.fetch(:name)] }
       end
 
-      # The decision tree (ADR-73 WD2). Returns `{ skill:, reason: }` for
-      # the recommended next step, or nil when no catalogue skill matches.
+      # The decision tree (ADR-73 WD2). Returns `{ skill:, reason: }` for the recommended next step, or nil when no
+      # catalogue skill matches.
       def recommend(state, catalog)
         name, reason = recommended_name_and_reason(state)
         skill = catalog.find { |candidate| candidate.fetch(:name) == name }
@@ -208,14 +190,11 @@ module Rigor
           ["rigor-rbs-setup", "your gems ship no community RBS yet — install it so Rigor stops typing them as Dynamic."]
         elsif state.fetch(:ci) != :wired
           ["rigor-ci-setup", "Rigor is configured but not wired into CI — lock in the regression guard."]
-        # A present baseline is deliberately NOT a recommendation trigger.
-        # A baseline is a healthy, finished onboarding state, not a problem to
-        # work off; pushing every baselined project to "reduce it" turns a
-        # working build into a chore and tempts scattering `# rigor:disable`
-        # through the code to make a number go down — means over ends.
-        # `rigor-baseline-reduce` stays in the catalogue for the intermediate
-        # user who *chooses* to invest in it; the headline routes to genuinely
-        # additive steps instead.
+        # A present baseline is deliberately NOT a recommendation trigger. A baseline is a healthy, finished onboarding
+        # state, not a problem to work off; pushing every baselined project to "reduce it" turns a working build into a
+        # chore and tempts scattering `# rigor:disable` through the code to make a number go down — means over ends.
+        # `rigor-baseline-reduce` stays in the catalogue for the intermediate user who *chooses* to invest in it; the
+        # headline routes to genuinely additive steps instead.
         elsif state.fetch(:editor) == :unwired
           ["rigor-editor-setup",
            "you have an editor config but no Rigor LSP — wire `rigor lsp` for live diagnostics and hover types."]
@@ -314,10 +293,8 @@ module Rigor
         PROMPT
       end
 
-      # The one-line essence of a skill's frontmatter `description`, read
-      # live from the SKILL.md so the catalogue can never go stale relative
-      # to the shipped skill. Drops the `Triggers:` / `NOT for` tail and
-      # caps the length.
+      # The one-line essence of a skill's frontmatter `description`, read live from the SKILL.md so the catalogue can
+      # never go stale relative to the shipped skill. Drops the `Triggers:` / `NOT for` tail and caps the length.
       def catalog_blurb(path)
         text = frontmatter(path).fetch("description", "").to_s.strip.tr("\n", " ").squeeze(" ")
         head = text.split(/\s*Triggers?:/, 2).first.to_s.strip
@@ -331,9 +308,8 @@ module Rigor
         "#{(text[0, limit] || '').rstrip}…"
       end
 
-      # Parse a SKILL.md's leading `---`-delimited YAML frontmatter. Returns
-      # {} on any missing or malformed block so the catalogue degrades to a
-      # name-only entry rather than raising.
+      # Parse a SKILL.md's leading `---`-delimited YAML frontmatter. Returns {} on any missing or malformed block so the
+      # catalogue degrades to a name-only entry rather than raising.
       def frontmatter(path)
         text = File.read(path)
         return {} unless text.start_with?("---\n")

data/lib/rigor/cli/trace_command.rb

@@ -15,22 +15,17 @@ require_relative "trace_renderer"
 
 module Rigor
   class CLI
-    # Executes the `rigor trace` command: re-runs the inference engine
-    # over one file under {Rigor::Inference::FlowTracer} and replays the
-    # recorded event stream — scope binds, union formation, method
-    # dispatch, and (with `--verbose`) every expression enter/result —
-    # as a step-through terminal animation. A teaching probe: it shows
-    # HOW Rigor arrives at a type, where `rigor type-of` shows only the
-    # answer.
+    # Executes the `rigor trace` command: re-runs the inference engine over one file under
+    # {Rigor::Inference::FlowTracer} and replays the recorded event stream — scope binds, union formation, method
+    # dispatch, and (with `--verbose`) every expression enter/result — as a step-through terminal animation. A teaching
+    # probe: it shows HOW Rigor arrives at a type, where `rigor type-of` shows only the answer.
     #
-    # The tracer is observational; this command never changes what
-    # `rigor check` would infer for the same file.
+    # The tracer is observational; this command never changes what `rigor check` would infer for the same file.
     class TraceCommand < Command
       USAGE = "Usage: rigor trace [options] FILE"
 
-      # Default frame kinds: the three teachable moments. :enter/:result
-      # add one frame per literal and drown the signal; `--verbose`
-      # opts into them.
+      # Default frame kinds: the three teachable moments. :enter/:result add one frame per literal and drown the signal;
+      # `--verbose` opts into them.
       DEFAULT_KINDS = %i[bind union dispatch].freeze
       VERBOSE_KINDS = (%i[enter result] + DEFAULT_KINDS).freeze
 
@@ -95,10 +90,8 @@ module Rigor
         0
       end
 
-      # Mirrors the single-file path `rigor type-of` takes: a
-      # project-aware environment, an empty seed scope, one
-      # statement-level evaluation of the whole program — but recorded
-      # under the FlowTracer.
+      # Mirrors the single-file path `rigor type-of` takes: a project-aware environment, an empty seed scope, one
+      # statement-level evaluation of the whole program — but recorded under the FlowTracer.
       def record_events(root, file, configuration)
         environment = Environment.for_project(
           libraries: configuration.libraries,

data/lib/rigor/cli/trace_renderer.rb

@@ -4,24 +4,19 @@ require_relative "prism_colorizer"
 
 module Rigor
   class CLI
-    # Replays a `Rigor::Inference::FlowTracer` event stream as a terminal
-    # animation for `rigor trace`. Each frame draws a box-drawn screen:
-    # the source panel (syntax-coloured, current node range underlined)
-    # side-by-side with the scope panel (locals accumulated from :bind
-    # events), and an event panel describing the current step and the
-    # expression stack.
+    # Replays a `Rigor::Inference::FlowTracer` event stream as a terminal animation for `rigor trace`. Each frame draws
+    # a box-drawn screen: the source panel (syntax-coloured, current node range underlined) side-by-side with the scope
+    # panel (locals accumulated from :bind events), and an event panel describing the current step and the expression
+    # stack.
     #
-    # The frame is fitted to the measured terminal: the source panel
-    # scrolls vertically (a window centred on the line under evaluation)
-    # instead of overflowing the screen height, over-long rows are
-    # clipped with an ellipsis instead of wrapping, and the event panel
-    # keeps a minimum height of {EVENT_PANE_MIN} rows so the narration
-    # never collapses to a sliver.
+    # The frame is fitted to the measured terminal: the source panel scrolls vertically (a window centred on the line
+    # under evaluation) instead of overflowing the screen height, over-long rows are clipped with an ellipsis instead of
+    # wrapping, and the event panel keeps a minimum height of {EVENT_PANE_MIN} rows so the narration never collapses to
+    # a sliver.
     #
-    # Pure ANSI + `io/console` (both stdlib) per ADR-0's zero-runtime-
-    # dependency policy. When the output is not a TTY the frames are
-    # printed sequentially without cursor control against a default
-    # 80×24 layout, which keeps the renderer deterministic under test.
+    # Pure ANSI + `io/console` (both stdlib) per ADR-0's zero-runtime-dependency policy. When the output is not a TTY
+    # the frames are printed sequentially without cursor control against a default 80×24 layout, which keeps the
+    # renderer deterministic under test.
     class TraceRenderer
       RESET = "\e[0m"
       DIM = "\e[90m"
@@ -68,9 +63,8 @@ module Rigor
 
       private
 
-      # `IO.console` reflects the controlling terminal even when stdout
-      # is, say, a StringIO under test — which is why the measured size
-      # is only used for interactive replays.
+      # `IO.console` reflects the controlling terminal even when stdout is, say, a StringIO under test — which is why
+      # the measured size is only used for interactive replays.
       def terminal_size
         require "io/console"
         size = IO.console&.winsize
@@ -81,9 +75,8 @@ module Rigor
         DEFAULT_SIZE
       end
 
-      # Replays :bind events into a per-frame snapshot of the locals
-      # panel, so frame N shows exactly the bindings visible after the
-      # first N events.
+      # Replays :bind events into a per-frame snapshot of the locals panel, so frame N shows exactly the bindings
+      # visible after the first N events.
       def accumulate_locals(events)
         locals = {}
         events.map do |event|
@@ -109,34 +102,31 @@ module Rigor
         @out.puts(bottom_border(left_width + right_width + 1))
       end
 
-      # Screen budget: borders (3 rows) + event pane + the key-hint row
-      # when stepping interactively; whatever remains belongs to the
-      # source/scope body, floored at {BODY_HEIGHT_MIN}.
+      # Screen budget: borders (3 rows) + event pane + the key-hint row when stepping interactively; whatever remains
+      # belongs to the source/scope body, floored at {BODY_HEIGHT_MIN}.
       def body_height_for(event_rows)
         chrome = 3 + event_rows + (@interactive ? 1 : 0)
         [@rows - chrome, BODY_HEIGHT_MIN].max
       end
 
-      # The event pane keeps at least {EVENT_PANE_MIN} rows (padding with
-      # blanks) so the bottom of the frame is visually stable across
-      # event kinds; over-long lines are clipped to the frame width.
+      # The event pane keeps at least {EVENT_PANE_MIN} rows (padding with blanks) so the bottom of the frame is visually
+      # stable across event kinds; over-long lines are clipped to the frame width.
       def event_pane_lines(event, max_width)
         lines = [describe_event(event), stack_line(event)].compact
         lines << "" while lines.size < EVENT_PANE_MIN
         lines.map { |line| clip(line, max_width) }
       end
 
-      # Source rows win the width contest; the scope column keeps its
-      # minimum and absorbs whatever the source does not need.
+      # Source rows win the width contest; the scope column keeps its minimum and absorbs whatever the source does not
+      # need.
       def column_widths(source_rows, inner)
         left_need = (source_rows.map { |raw, _| raw.length }.max || 0) + 1
         left_width = left_need.clamp(24, [inner - SCOPE_WIDTH_MIN, 24].max)
         [left_width, [inner - left_width, SCOPE_WIDTH_MIN].max]
       end
 
-      # Vertical scroll: when the panel is taller than the window, keep
-      # a slice centred on the row under evaluation (the `▶` row, which
-      # the marker row directly follows).
+      # Vertical scroll: when the panel is taller than the window, keep a slice centred on the row under evaluation (the
+      # `▶` row, which the marker row directly follows).
       def scroll_window(rows, height)
         return rows if rows.size <= height
 
@@ -149,15 +139,14 @@ module Rigor
         rows.map do |raw, painted|
           next [raw, painted] if raw.length <= width
 
-          # Re-paint from the clipped raw text — clipping the painted
-          # string directly would cut ANSI escapes in half.
+          # Re-paint from the clipped raw text — clipping the painted string directly would cut ANSI escapes in half.
           clipped = clip(raw, width)
           [clipped, repaint_clipped(clipped)]
         end
       end
 
-      # A clipped row loses its highlight/marker alignment guarantees, so
-      # it is repainted with plain syntax colouring (gutter dimmed).
+      # A clipped row loses its highlight/marker alignment guarantees, so it is repainted with plain syntax colouring
+      # (gutter dimmed).
       def repaint_clipped(clipped)
         gutter = clipped[0, 6]
         rest = clipped[6..] || ""
@@ -175,9 +164,8 @@ module Rigor
         "#{text[0, [width - 1, 0].max]}…"
       end
 
-      # Each row is `[raw_text, painted_text]` so width math runs on the
-      # escape-free string. The row under the event's source range gets a
-      # `▔▔▔` marker row injected after it.
+      # Each row is `[raw_text, painted_text]` so width math runs on the escape-free string. The row under the event's
+      # source range gets a `▔▔▔` marker row injected after it.
       def source_panel_rows(event)
         rows = []
         location = event.location
@@ -200,9 +188,8 @@ module Rigor
         [indent + ("▔" * width), indent + BOLD + ("▔" * width) + RESET]
       end
 
-      # Highlights the in-range slice with reverse video; everything else
-      # gets Prism syntax colouring. The highlight is applied on the raw
-      # slice (not the colorized string) so byte offsets stay honest.
+      # Highlights the in-range slice with reverse video; everything else gets Prism syntax colouring. The highlight is
+      # applied on the raw slice (not the colorized string) so byte offsets stay honest.
       def paint_line(line, location, number)
         return PrismColorizer.colorize(line) unless location && number == location[:start_line]
 
@@ -214,9 +201,8 @@ module Rigor
           PrismColorizer.colorize(after).chomp
       end
 
-      # Prism columns are BYTE columns — split the line with byteslice
-      # so a multibyte character earlier on the line cannot shift (or
-      # overrun) the highlight range. Returns `[before, slice, after]`.
+      # Prism columns are BYTE columns — split the line with byteslice so a multibyte character earlier on the line
+      # cannot shift (or overrun) the highlight range. Returns `[before, slice, after]`.
       def split_at_range(line, location)
         from = [location[:start_column], line.bytesize].min
         to = location[:end_line] == location[:start_line] ? [location[:end_column], line.bytesize].min : line.bytesize
@@ -262,8 +248,7 @@ module Rigor
         "┌#{pad_label("─ #{@file} ", left)}┬#{pad_label('─ scope ', right)}┐"
       end
 
-      # Pads `label` with `─` to exactly `width` cells (truncating an
-      # over-long label so the frame never breaks).
+      # Pads `label` with `─` to exactly `width` cells (truncating an over-long label so the frame never breaks).
       def pad_label(label, width)
         label = "#{label[0, width - 2]} " if label.length > width
         label + ("─" * [width - label.length, 0].max)
@@ -289,9 +274,8 @@ module Rigor
         "└#{'─' * width}┘"
       end
 
-      # Single-keystroke stepping via stdlib io/console; falls back to
-      # line-buffered Enter when raw mode is unavailable (e.g. pipes that
-      # still claim to be TTYs). Returns false when the user quits.
+      # Single-keystroke stepping via stdlib io/console; falls back to line-buffered Enter when raw mode is unavailable
+      # (e.g. pipes that still claim to be TTYs). Returns false when the user quits.
       def next_frame?
         @out.print("#{DIM}  [any key: next · q: quit]#{RESET}")
         key = read_key

data/lib/rigor/cli/triage_command.rb

@@ -14,12 +14,10 @@ module Rigor
   class CLI
     # ADR-23 — executes `rigor triage`.
     #
-    # Runs the same analysis as `rigor check`, then summarises the
-    # diagnostic stream (rule distribution, per-file hotspots,
-    # heuristic hints) instead of printing the raw per-line list.
-    # Read-only and advisory (WD4): never edits config, never
-    # writes a baseline. Always exits 0 — it is an inspection
-    # command, not a gate (`rigor check` remains the gate).
+    # Runs the same analysis as `rigor check`, then summarises the diagnostic stream (rule distribution, per-file
+    # hotspots, heuristic hints) instead of printing the raw per-line list. Read-only and advisory (WD4): never edits
+    # config, never writes a baseline. Always exits 0 — it is an inspection command, not a gate (`rigor check` remains
+    # the gate).
     class TriageCommand < Command
       USAGE = "Usage: rigor triage [options] [paths]"
       DEFAULT_SECTIONS = %i[distribution selectors hotspots hints].freeze
@@ -70,10 +68,8 @@ module Rigor
         raise OptionParser::InvalidArgument, "unsupported format: #{options.fetch(:format)}"
       end
 
-      # Sequential, cache-backed, no run-stats: triage only needs
-      # the diagnostic stream, and sequential keeps the rule
-      # distribution deterministic (the fork pool's cross-file
-      # divergence would skew the histogram).
+      # Sequential, cache-backed, no run-stats: triage only needs the diagnostic stream, and sequential keeps the rule
+      # distribution deterministic (the fork pool's cross-file divergence would skew the histogram).
       def analyze(configuration)
         runner = Analysis::Runner.new(
           configuration: configuration,

data/lib/rigor/cli/triage_renderer.rb

@@ -6,8 +6,7 @@ require_relative "../triage"
 
 module Rigor
   class CLI
-    # ADR-23 — renders a {Rigor::Triage::Report} as the `rigor
-    # triage` text report or as `--format json`.
+    # ADR-23 — renders a {Rigor::Triage::Report} as the `rigor triage` text report or as `--format json`.
     class TriageRenderer
       BAR_WIDTH = 24
       SELECTOR_ROWS = 15 # text-output cap; `--format json` carries the full list