rigortype 0.2.0 → 0.2.2

data/lib/rigor/cli/fused_protection_report.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Rigor
+  class CLI
+    # ADR-70 — aggregates per-file {Protection::MutationScanner::FusedFileResult}
+    # into a project-level **fused** protection report: how many type-visible
+    # breakages were caught by the type checker, how many of the *type-survivors*
+    # were caught by the test suite, and which sites neither axis caught — the
+    # ranked "add a type OR a test here" list.
+    #
+    # Framing (ADR-63 / ADR-62 Criterion A, extended): the payload is the
+    # **attribution** — which protection axis is missing — never raw survival.
+    # An unprotected site is "add protection here", never "your code is broken".
+    FusedFileProtection = Data.define(:path, :type_killed, :test_killed, :unprotected, :ratio)
+    UnprotectedBreakage = Data.define(:method_name, :count, :examples)
+
+    FusedProtectionReport = Data.define(:files, :unprotected, :parse_errors) do
+      def total_type_killed = files.sum(&:type_killed)
+      def total_test_killed = files.sum(&:test_killed)
+      def total_unprotected = files.sum(&:unprotected)
+      def grand_total = total_type_killed + total_test_killed + total_unprotected
+      def protected_total = total_type_killed + total_test_killed
+      def ratio = grand_total.zero? ? 1.0 : protected_total.to_f / grand_total
+
+      def to_h
+        {
+          "mode" => "protection-fused",
+          "type_killed" => total_type_killed,
+          "test_killed" => total_test_killed,
+          "unprotected" => total_unprotected,
+          "protected_ratio" => ratio.round(4),
+          "files" => files.map do |f|
+            { "path" => f.path, "type_killed" => f.type_killed, "test_killed" => f.test_killed,
+              "unprotected" => f.unprotected, "ratio" => f.ratio.round(4) }
+          end,
+          "add_protection_here" => unprotected.map do |m|
+            { "method" => m.method_name, "count" => m.count, "examples" => m.examples }
+          end,
+          "parse_errors" => parse_errors
+        }
+      end
+    end
+
+    class FusedProtectionAccumulator
+      def initialize
+        @files = []
+        @unprotected = Hash.new { |h, k| h[k] = { count: 0, examples: [] } }
+        @parse_errors = []
+      end
+
+      def absorb(file_result)
+        @files << FusedFileProtection.new(
+          path: file_result.path, type_killed: file_result.type_killed,
+          test_killed: file_result.test_killed, unprotected: file_result.unprotected,
+          ratio: file_result.ratio
+        )
+        file_result.sites.each do |site|
+          bucket = @unprotected[site.method_name]
+          bucket[:count] += 1
+          bucket[:examples] << "#{file_result.path}:#{site.line}" if bucket[:examples].size < 3
+        end
+      end
+
+      def record_parse_error(path, errors)
+        @parse_errors << { "path" => path, "errors" => errors.size }
+      end
+
+      def to_report
+        unprotected = @unprotected
+                      .map { |m, v| UnprotectedBreakage.new(method_name: m, count: v[:count], examples: v[:examples]) }
+                      .sort_by { |m| [-m.count, m.method_name] }
+        FusedProtectionReport.new(files: @files, unprotected: unprotected, parse_errors: @parse_errors)
+      end
+    end
+  end
+end

data/lib/rigor/cli/skill_command.rb

@@ -2,8 +2,6 @@
 
 require_relative "command"
 
-require "optparse"
-
 module Rigor
   class CLI
     # `rigor skill` — discover and print the SKILL.md files
@@ -17,59 +15,112 @@ module Rigor
     # gem checkout — the project being analysed has no copy, so an
     # AI agent has no a priori way to find them.
     #
-    # This command exposes the bundled skills via three subcommands:
+    # 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`         — table of name + absolute path.
-    # - `rigor skill print <name>` — short header (paths + how to use)
-    #                                followed by the SKILL.md body. This
-    #                                is the form AI agents should call;
-    #                                the inline body plus the header's
-    #                                absolute paths together let the
-    #                                agent act with or without a file
-    #                                reading tool.
-    # - `rigor skill path <name>`  — one-line absolute path, suitable
-    #                                as input to a Read tool.
+    # - `rigor skill`              — list bundled skills (the default).
+    # - `rigor skill <name>`       — print the SKILL.md body (header + body).
+    #                                This is the form AI agents call; the
+    #                                inline body plus the header's absolute
+    #                                paths let the agent act with or without
+    #                                a file-reading tool.
+    # - `rigor skill --path <name>`— one-line absolute path, for a Read tool.
+    # - `rigor skill --list`       — table of name + absolute path.
+    # - `rigor skill --describe`   — ADR-73's live entry point: a cheap
+    #                                project-state probe + the recommended
+    #                                next skill + every skill's current
+    #                                description. The `rigor-next-steps`
+    #                                SKILL routes off this so no
+    #                                version-coupled guidance is frozen into
+    #                                the SKILL. Also spelled `describe`, and
+    #                                surfaced top-level as `rigor describe`.
     #
-    # `rigor skill` with no subcommand is an alias for `list`.
+    # 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 <subcommand> [args]
+        Usage: rigor skill [<name>] [--path <name>] [--list] [--describe]
+
+        With no argument, lists the bundled skills.
 
-        Subcommands:
-          list                  List bundled skills (default when no subcommand given)
-          print <name>          Print the SKILL.md body for <name> to stdout, with a header
-          path  <name>          Print the absolute path of the SKILL.md file for <name>
+          rigor skill                List bundled skills
+          rigor skill <name>         Print the SKILL.md body for <name> (with a header)
+          rigor skill --path <name>  Print the absolute path of the SKILL.md file for <name>
+          rigor skill --list         List bundled skills (name + absolute path)
+          rigor skill --describe     Report project state + recommend the next skill to run
 
         Examples:
-          rigor skill list
-          rigor skill print rigor-project-init
-          rigor skill path  rigor-baseline-reduce
+          rigor skill
+          rigor skill rigor-project-init
+          rigor skill --path rigor-baseline-reduce
+          rigor skill --describe        (also: rigor describe)
+
+        Deprecated (removed in v0.3.0) — use the forms above:
+          rigor skill list           ->  rigor skill --list
+          rigor skill print <name>   ->  rigor skill <name>
+          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.
       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.
+      LEGACY_VERB_REMOVAL = "v0.3.0"
+      LEGACY_VERBS = {
+        "list" => { old: "list",         advice: "--list", flag: "--list" },
+        "print" => { old: "print <name>", advice: "<name>", flag: "--print" },
+        "path" => { old: "path <name>", advice: "--path <name>", flag: "--path" }
+      }.freeze
+
       # @return [Integer] CLI exit status.
       def run
-        subcommand = @argv.shift || "list"
+        rewrite_legacy_verb!
 
-        case subcommand
-        when "list" then run_list
-        when "print" then run_print
-        when "path" then run_path
+        case @argv.first
+        when nil
+          run_list
         when "-h", "--help", "help"
           print_usage(@out)
           0
+        when "describe", "--describe"
+          @argv.shift
+          run_describe
+        when "--list"
+          @argv.shift
+          run_list
+        when "--path"
+          @argv.shift
+          run_path(@argv.shift)
+        when "--print"
+          @argv.shift
+          run_print(@argv.shift)
         else
-          @err.puts("Unknown subcommand: #{subcommand}")
-          print_usage(@err)
-          Rigor::CLI::EXIT_USAGE
+          run_print(@argv.shift)
         end
       end
 
       private
 
+      # 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
+
+        @err.puts(
+          "rigor skill: `#{spec.fetch(:old)}` is deprecated and will be removed in " \
+          "#{LEGACY_VERB_REMOVAL}; use `rigor skill #{spec.fetch(:advice)}` instead."
+        )
+        @argv[0] = spec.fetch(:flag)
+      end
+
       def run_list
         skills = discover_skills
         if skills.empty?
@@ -84,9 +135,8 @@ module Rigor
         0
       end
 
-      def run_print
-        name = @argv.shift
-        return usage_error("`print` requires a skill name") if name.nil?
+      def run_print(name)
+        return usage_error("a skill name is required") if name.nil?
 
         skill = find_skill(name)
         return name_error(name) if skill.nil?
@@ -97,9 +147,8 @@ module Rigor
         0
       end
 
-      def run_path
-        name = @argv.shift
-        return usage_error("`path` requires a skill name") if name.nil?
+      def run_path(name)
+        return usage_error("`--path` requires a skill name") if name.nil?
 
         skill = find_skill(name)
         return name_error(name) if skill.nil?
@@ -108,11 +157,24 @@ 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.
+      def run_describe
+        require_relative "skill_describe"
+
+        @out.puts(SkillDescribe.new(skills: discover_skills).render)
+        0
+      end
+
       # The header that precedes the SKILL.md body when an agent
-      # runs `rigor skill print <name>`. Kept as `# `-prefixed
-      # comment lines so the combined output remains parseable as
-      # markdown — anything below `---` (the SKILL frontmatter
-      # marker) is unchanged.
+      # 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)
@@ -147,7 +209,7 @@ module Rigor
 
       def name_error(name)
         @err.puts("Unknown skill: #{name}")
-        @err.puts("Available skills:")
+        @err.puts("Available skills (try `rigor skill --list`):")
         discover_skills.each { |s| @err.puts("  #{s.fetch(:name)}") }
         1
       end

data/lib/rigor/cli/skill_describe.rb

@@ -0,0 +1,346 @@
+# frozen_string_literal: true
+
+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.
+    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_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_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).
+      RAILS_LOCK_MARKERS = %w[railties actionpack activerecord actioncable].freeze
+      RAILS_PLUGIN_MARKERS = %w[
+        rigor-activerecord rigor-actionpack rigor-actionmailer rigor-activejob
+        rigor-rails-routes rigor-rails-i18n rigor-actioncable rigor-activestorage rigor-rails
+      ].freeze
+
+      def initialize(root)
+        @root = root
+      end
+
+      # @return [Hash] the presence-only state the recommendation routes on.
+      def to_h
+        config = CONFIG_FILENAMES.find { |name| File.file?(File.join(@root, name)) }
+        {
+          config: config,
+          baseline: File.file?(File.join(@root, BASELINE_FILENAME)),
+          sig: File.directory?(File.join(@root, "sig")),
+          gems: File.file?(File.join(@root, "Gemfile.lock")),
+          rbs_collection: File.file?(File.join(@root, RBS_COLLECTION_LOCKFILE)),
+          rails_unconfigured: rails_unconfigured?(config),
+          ci: ci_state,
+          editor: editor_state,
+          mcp: mcp_state
+        }
+      end
+
+      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
+      # `rigor-project-init`, which selects the plugins itself.
+      def rails_unconfigured?(config)
+        return false if config.nil?
+
+        lock = File.join(@root, "Gemfile.lock")
+        return false unless File.file?(lock) && file_mentions_any?(lock, RAILS_LOCK_MARKERS)
+
+        !file_mentions_any?(File.join(@root, config), RAILS_PLUGIN_MARKERS)
+      end
+
+      def file_mentions_any?(path, markers)
+        content = File.read(path)
+        markers.any? { |marker| content.include?(marker) }
+      rescue StandardError
+        false
+      end
+
+      # `: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?
+
+        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.
+      def editor_state
+        vscode = File.join(@root, ".vscode")
+        return :none unless File.directory?(vscode)
+
+        files = Dir.glob(File.join(vscode, "*.json"))
+        return :unwired if files.empty?
+
+        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.
+      def mcp_state
+        files = [".mcp.json", File.join(".cursor", "mcp.json")]
+                .map { |rel| File.join(@root, rel) }
+                .select { |path| File.file?(path) }
+        return :none if files.empty?
+
+        files.any? { |path| file_mentions_rigor?(path) } ? :wired : :unwired
+      end
+
+      def file_mentions_rigor?(path)
+        File.read(path).include?("rigor")
+      rescue StandardError
+        false
+      end
+
+      def ci_config_files
+        files = Dir.glob(File.join(@root, ".github", "workflows", "*.{yml,yaml}"))
+        gitlab = File.join(@root, ".gitlab-ci.yml")
+        files << gitlab if File.file?(gitlab)
+        files
+      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.
+    class SkillDescribe
+      # 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.
+      CATALOG_ORDER = %w[
+        rigor-project-init
+        rigor-rbs-setup
+        rigor-ci-setup
+        rigor-baseline-reduce
+        rigor-monkeypatch-resolve
+        rigor-editor-setup
+        rigor-mcp-setup
+        rigor-protection-uplift
+        rigor-plugin-tune
+        rigor-plugin-author
+        rigor-upgrade
+        rigor-doctor
+        rigor-ask
+      ].freeze
+
+      # @param skills [Array<Hash>] discovered skills, each `{name:, path:}`.
+      # @param root [String] project root to probe (defaults to the cwd).
+      def initialize(skills:, root: Dir.pwd)
+        @skills = skills
+        @root = root
+      end
+
+      # @return [String] the full describe report.
+      def render
+        catalog = catalog_skills
+        state = ProjectStateProbe.new(@root).to_h
+        recommendation = recommend(state, catalog)
+        [
+          title,
+          state_section(state),
+          recommendation_section(recommendation),
+          catalog_section(catalog),
+          agent_prompt(recommendation)
+        ].join("\n")
+      end
+
+      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.
+      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.
+      def recommend(state, catalog)
+        name, reason = recommended_name_and_reason(state)
+        skill = catalog.find { |candidate| candidate.fetch(:name) == name }
+        skill.nil? ? nil : { skill: skill, reason: reason }
+      end
+
+      def recommended_name_and_reason(state)
+        if state.fetch(:config).nil?
+          ["rigor-project-init", "this project has no Rigor configuration yet — start here."]
+        elsif state.fetch(:rails_unconfigured)
+          ["rigor-plugin-tune",
+           "Rails is in your Gemfile.lock but no Rails plugins are enabled — wire them so " \
+           "ActiveRecord / routes / i18n calls resolve (a bigger win here than community RBS)."]
+        elsif state.fetch(:gems) && !state.fetch(:rbs_collection)
+          ["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."]
+        elsif state.fetch(:baseline)
+          ["rigor-baseline-reduce", "a baseline is in place — work it down rule by rule."]
+        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."]
+        elsif state.fetch(:mcp) == :unwired
+          ["rigor-mcp-setup",
+           "an MCP client config is present without Rigor — wire `rigor mcp` so your AI agent can call Rigor's tools."]
+        else
+          ["rigor-protection-uplift", "the basics are in place — raise how much of your code Rigor can catch bugs in."]
+        end
+      end
+
+      def title
+        <<~TITLE
+          # Rigor — next steps for this project
+          #
+          # Generated live by rigortype #{Rigor::VERSION}; this guidance always
+          # reflects your installed version and the project's current state.
+        TITLE
+      end
+
+      def state_section(state)
+        ci = case state.fetch(:ci)
+             when :wired then "Rigor wired in"
+             when :unwired then "CI present, Rigor not wired"
+             else "not detected"
+             end
+        rbs = if state.fetch(:gems)
+                state.fetch(:rbs_collection) ? "collection installed" : "gems present, no collection"
+              else
+                "no Gemfile.lock"
+              end
+        editor = case state.fetch(:editor)
+                 when :wired then "Rigor LSP wired (.vscode)"
+                 when :unwired then ".vscode present, Rigor LSP not wired"
+                 else "not detected"
+                 end
+        mcp = case state.fetch(:mcp)
+              when :wired then "Rigor MCP wired"
+              when :unwired then "MCP config present, Rigor not wired"
+              else "not detected"
+              end
+        <<~STATE
+          ## Project state
+          - Config file:    #{state.fetch(:config) || 'none (no .rigor.yml / .rigor.dist.yml)'}
+          - Baseline:       #{state.fetch(:baseline) ? '.rigor-baseline.yml' : 'none'}
+          - Project sig/:   #{state.fetch(:sig) ? 'present' : 'none'}
+          - Community RBS:  #{rbs}
+          - CI integration: #{ci}
+          - Editor LSP:     #{editor}
+          - MCP server:     #{mcp}
+        STATE
+      end
+
+      def recommendation_section(recommendation)
+        return "## Recommended next step\n- (no bundled skill matched the current state)\n" if recommendation.nil?
+
+        name = recommendation.fetch(:skill).fetch(:name)
+        <<~REC
+          ## Recommended next step
+          → #{name} — #{recommendation.fetch(:reason)}
+            Load it: rigor skill #{name}
+        REC
+      end
+
+      def catalog_section(catalog)
+        lines = catalog.map do |skill|
+          name = skill.fetch(:name)
+          "- #{name} — #{catalog_blurb(skill.fetch(:path))}\n  rigor skill #{name}"
+        end
+        "## All skills you can run next\n#{lines.join("\n")}\n"
+      end
+
+      def agent_prompt(recommendation)
+        opener =
+          if recommendation.nil?
+            "Ask the user what they would like to do next"
+          else
+            "Present the recommended step above (or, if the user has a different goal, ask which they want)"
+          end
+        <<~PROMPT
+          ## For the agent
+          #{opener}, then run `rigor skill <name>` for the chosen skill and
+          follow its body top to bottom.
+
+          The recommendation above is from a presence-only probe — it does not run
+          `rigor check`. If you have run (or now run) `rigor check`, let its findings
+          refine the choice:
+          - errors present and no baseline yet → rigor-baseline-reduce
+          - a `call.unresolved-toplevel` / `call.undefined-method` cluster on the
+            project's own monkey-patches → rigor-monkeypatch-resolve
+          - framework calls (ActiveRecord, routes, i18n …) typing as Dynamic with no
+            matching plugins enabled → rigor-plugin-tune
+          - `RBS classes available: 0` or a `configuration-error` diagnostic → rigor-doctor
+
+          Re-run `rigor skill describe` whenever you need the next step — it always
+          reflects the project's current state.
+        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.
+      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
+        head = text if head.empty?
+        truncate(head, 200)
+      end
+
+      def truncate(text, limit)
+        return text if text.length <= limit
+
+        "#{(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.
+      def frontmatter(path)
+        text = File.read(path)
+        return {} unless text.start_with?("---\n")
+
+        closing = text.index("\n---\n", 4)
+        return {} if closing.nil?
+
+        data = YAML.safe_load(text[4...closing])
+        data.is_a?(Hash) ? data : {}
+      rescue StandardError
+        {}
+      end
+    end
+  end
+end