rails-hyperdrive 0.5.0 → 0.7.0

data/lib/rails/hyperdrive/gemspec_locator.rb

@@ -0,0 +1,38 @@
+module Rails
+  module Hyperdrive
+    # Resolves the gemspec of the companion gem repo a dev task is running in.
+    # Companion-repo dev tooling: problems raise rather than fail open.
+    module GemspecLocator
+      Error = Class.new(StandardError)
+
+      module_function
+
+      # Returns the loaded spec and the repo root its relative paths resolve
+      # against — the gemspec's own directory, not an installed gem path.
+      def load_spec(explicit, dir)
+        path = resolve(explicit, dir)
+        spec = Gem::Specification.load(path)
+        raise Error, "could not load gemspec #{path}" unless spec
+
+        [spec, File.dirname(File.expand_path(path))]
+      end
+
+      def resolve(explicit, dir)
+        if explicit && !explicit.to_s.strip.empty?
+          path = File.expand_path(explicit.to_s, dir)
+          raise Error, "gemspec not found: #{path}" unless File.file?(path)
+          return path
+        end
+
+        found = Dir.glob(File.join(dir, "*.gemspec"))
+        case found.size
+        when 1 then File.expand_path(found.first)
+        when 0 then raise Error, "no .gemspec found in #{dir}; pass an explicit path as the task " \
+                                 "argument, e.g. rake \"<task>[path/to/name.gemspec]\""
+        else raise Error, "multiple gemspecs found in #{dir} " \
+                          "(#{found.map { |f| File.basename(f) }.join(", ")}); pass an explicit path"
+        end
+      end
+    end
+  end
+end

data/lib/rails/hyperdrive/install_layout.rb

@@ -1,35 +1,171 @@
 module Rails
   module Hyperdrive
-    # The one place install paths and artifact names are built and parsed.
+    # The registry every artifact kind declares itself in, and the one place
+    # install paths and artifact names are built and parsed.
     # Must stay require-free: the MCP server loads it and must not drag in the
     # install machinery.
     module InstallLayout
       SKILLS_DIR = ".claude/skills".freeze
       HYPERDRIVE_DIR = ".claude/hyperdrive".freeze
+      AGENTS_DIR = ".claude/agents".freeze
+      COMMANDS_DIR = ".claude/commands".freeze
       INDEX_PATH = "#{HYPERDRIVE_DIR}/index.md".freeze
       LOCK_PATH = ".hyperdrive/lock.yml".freeze
 
-      ARTIFACT_TYPES = { "skill" => :skill, "skill_support" => :skill_support, "guideline" => :guideline }.freeze
+      DEFAULT_TARGET = :claude
 
-      module_function
+      # `root` is the directory a target tool reads the kind from; `path` builds
+      # one artifact's destination under it.
+      Dest = Struct.new(:root, :path, keyword_init: true)
+
+      # One kind's whole contract: how a companion ships it, how it is
+      # identified and validated, and where each target tool installs it.
+      Kind = Struct.new(
+        :type, :shape, :section, :key_label, :shipped_label, :dir_key, :prefix_key,
+        :convention_roots, :identity, :frontmatter, :install_body,
+        :collision_rewrites_name, :eager, :name_from_dest, :dests,
+        keyword_init: true
+      ) do
+        def lock_kind
+          type.to_s
+        end
+
+        # Only a directory-shaped kind ships supporting files, so it is the only
+        # one a manifest entry may gate per file.
+        def dir_shaped?
+          shape == :dir
+        end
+
+        def dest_for(final_name, target: DEFAULT_TARGET)
+          dests[target]&.path&.call(final_name)
+        end
+
+        def installed_name(dest)
+          name_from_dest.call(dest)
+        end
 
-      def dest_for(type, final_name)
-        case type
-        when :skill     then "#{SKILLS_DIR}/#{final_name}/SKILL.md"
-        when :guideline then "#{HYPERDRIVE_DIR}/guidelines/#{final_name}.md"
+        # Relative to the gem root; searched in the order given.
+        def roots_for(gem_name)
+          convention_roots ? convention_roots.call(gem_name) : []
         end
       end
 
+      KINDS = {
+        skill: Kind.new(
+          type: :skill,
+          shape: :dir,
+          section: "skills",
+          key_label: "skill relpath",
+          shipped_label: "skill directory",
+          dir_key: "skills_dir",
+          prefix_key: nil,
+          convention_roots: ->(gem_name) { [File.join("lib", gem_name, "hyperdrive", "skills"), "skills"] },
+          identity: :frontmatter,
+          frontmatter: :required,
+          install_body: :verbatim,
+          collision_rewrites_name: true,
+          eager: false,
+          name_from_dest: ->(dest) { File.basename(File.dirname(dest)) },
+          dests: { claude: Dest.new(root: SKILLS_DIR, path: ->(name) { "#{SKILLS_DIR}/#{name}/SKILL.md" }) }
+        ),
+        skill_support: Kind.new(
+          type: :skill_support,
+          shape: nil,
+          install_body: :verbatim,
+          collision_rewrites_name: false,
+          eager: false,
+          name_from_dest: ->(dest) { dest.split("/")[2] }, # .claude/skills/<name>/<relpath>
+          dests: {}
+        ),
+        guideline: Kind.new(
+          type: :guideline,
+          shape: :flat,
+          section: "guidelines",
+          key_label: "guideline filename",
+          shipped_label: "guideline",
+          dir_key: nil,
+          prefix_key: nil,
+          convention_roots: ->(gem_name) { [File.join("lib", gem_name, "hyperdrive", "guidelines")] },
+          identity: :frontmatter,
+          frontmatter: :required,
+          install_body: :strip_frontmatter,
+          collision_rewrites_name: false,
+          eager: true,
+          name_from_dest: ->(dest) { File.basename(dest, ".md") },
+          dests: {
+            claude: Dest.new(
+              root: HYPERDRIVE_DIR,
+              path: ->(name) { "#{HYPERDRIVE_DIR}/guidelines/#{name}.md" }
+            )
+          }
+        ),
+        agent: Kind.new(
+          type: :agent,
+          shape: :flat,
+          section: "agents",
+          key_label: "agent filename",
+          shipped_label: "agent",
+          dir_key: "agents_dir",
+          prefix_key: nil,
+          convention_roots: ->(_gem_name) { ["agents"] },
+          identity: :frontmatter,
+          frontmatter: :required,
+          install_body: :verbatim,
+          collision_rewrites_name: true,
+          eager: false,
+          name_from_dest: ->(dest) { File.basename(dest, ".md") },
+          dests: { claude: Dest.new(root: AGENTS_DIR, path: ->(name) { "#{AGENTS_DIR}/#{name}.md" }) }
+        ),
+        command: Kind.new(
+          type: :command,
+          shape: :flat,
+          section: "commands",
+          key_label: "command filename",
+          shipped_label: "command",
+          dir_key: "commands_dir",
+          prefix_key: "command_prefix",
+          convention_roots: ->(_gem_name) { ["commands"] },
+          identity: :filename_stem,
+          frontmatter: :optional,
+          install_body: :verbatim,
+          collision_rewrites_name: false,
+          eager: false,
+          name_from_dest: ->(dest) { File.basename(dest, ".md") },
+          dests: { claude: Dest.new(root: COMMANDS_DIR, path: ->(name) { "#{COMMANDS_DIR}/#{name}.md" }) }
+        )
+      }.freeze
+
+      ARTIFACT_TYPES = KINDS.each_with_object({}) { |(type, kind), h| h[kind.lock_kind] = type }.freeze
+
+      module_function
+
+      def kind(type)
+        KINDS[type]
+      end
+
+      # The kinds a companion gem ships, in install order.
+      def content_kinds
+        KINDS.values.select(&:section)
+      end
+
+      def dir_keys
+        content_kinds.filter_map(&:dir_key)
+      end
+
+      def dest_roots(target: DEFAULT_TARGET)
+        content_kinds.filter_map { |kind| kind.dests[target]&.root }.uniq
+      end
+
+      def dest_for(type, final_name, target: DEFAULT_TARGET)
+        KINDS[type]&.dest_for(final_name, target: target)
+      end
+
       def sidecar_path(dest)
         "#{dest}.new"
       end
 
       def installed_name(type, dest)
-        case type
-        when :skill         then File.basename(File.dirname(dest))
-        when :skill_support then dest.split("/")[2] # .claude/skills/<name>/<relpath>
-        when :guideline     then File.basename(dest, ".md")
-        end
+        KINDS[type]&.installed_name(dest)
       end
 
       def skill_dir_of(dest)

data/lib/rails/hyperdrive/install_pipeline.rb

@@ -1,3 +1,4 @@
+require "set"
 require "time"
 require "rails/hyperdrive/ancestor_locator"
 require "rails/hyperdrive/bundler_artifact_discovery"
@@ -15,8 +16,7 @@ module Rails
     # The application root is explicit and no Rails constant is touched, so any
     # process that can see the bundle can run this.
     class InstallPipeline
-      ARTIFACT_DESTINATIONS =
-        [InstallLayout::SKILLS_DIR, InstallLayout::HYPERDRIVE_DIR, InstallLayout::LOCK_PATH].freeze
+      ARTIFACT_DESTINATIONS = (InstallLayout.dest_roots + [InstallLayout::LOCK_PATH]).freeze
 
       WARN_LINES = 150
       WARN_TOKENS = 1_500
@@ -26,30 +26,33 @@ module Rails
       Result = Struct.new(:installed, :updated, :unchanged, :skipped, :orphaned, :removed, :merged, :sidecars,
         keyword_init: true)
 
-      def initialize(root:, shell:, artifacts:, mode: :preserve, warnings: [], notices: [])
+      def initialize(root:, shell:, artifacts:, mode: :preserve, report: BundlerArtifactDiscovery::Report.new)
         raise ArgumentError, "unknown mode #{mode.inspect}" unless MODES.include?(mode)
 
         @root = File.expand_path(root.to_s)
         @shell = shell
         @artifacts = artifacts
         @mode = mode
-        @warnings = warnings
-        @notices = notices
+        @report = report
+        @bundled_gems = Array(report.bundled_gems).map(&:to_s)
+        @skipped_gems = Array(report.skipped_gems).map(&:to_s)
         @result = Result.new(
           installed: [], updated: [], unchanged: [], skipped: [], orphaned: [], removed: [], merged: [], sidecars: []
         )
       end
 
       def call
+        return halt_schema_ahead if old_lock.schema_ahead?
+
         @new_lock = LockFile.new(abs(InstallLayout::LOCK_PATH)).carry_settings(old_lock)
         @plan = plan
 
         report_collisions
         report_disabled
-        install_skills
-        guidelines = install_guidelines
+        guidelines = install_artifacts
         remove_disabled
         remove_stale_support_files
+        remove_stale_dests
         carry_orphans
         eager_guidelines = write_index_md(guidelines)
         write_claude_md(guidelines)
@@ -71,6 +74,13 @@ module Rails
 
       private
 
+      # The backstop for callers that do not check the lock themselves: nothing
+      # is written, in every mode including :additive.
+      def halt_schema_ahead
+        @shell.say_status :warn, old_lock.schema_ahead_message(InstallLayout::LOCK_PATH), :yellow
+        @result
+      end
+
       def build_result
         @build_result ||= InstallPlan.build(@artifacts, lock: old_lock)
       end
@@ -114,33 +124,36 @@ module Rails
         end
       end
 
-      def install_skills
-        @plan.select { |e| e.type == :skill }.each do |entry|
-          skill_relpath = source_relpath_for(entry.artifact)
-          support_base = support_relpath_base(entry.artifact, skill_relpath)
-          install_file(entry: entry, type: :skill, install_ready_body: entry.install_ready_body,
-            source_relpath: skill_relpath, final_name: entry.final_name)
-          entry.support_files.each do |file|
-            install_file(
-              dest: file[:dest],
-              type: :skill_support,
-              install_ready_body: file[:body],
-              source_gem: entry.source_gem,
-              version: entry.version,
-              artifact_kind: "skill_support",
-              source_relpath: support_base && File.join(support_base, file[:path])
-            )
+      # Returns the eager artifacts: the ones the index and the CLAUDE.md
+      # import line are built from.
+      def install_artifacts
+        eager = []
+        InstallLayout.content_kinds.each do |kind|
+          @plan.select { |e| e.type == kind.type }.each do |entry|
+            relpath = source_relpath_for(entry.artifact)
+            body = entry.install_ready_body
+            warn_if_oversize(entry.dest, body) if kind.eager
+            install_file(entry: entry, type: kind.type, install_ready_body: body,
+              source_relpath: relpath, final_name: entry.final_name)
+            install_support_files(entry, relpath) if kind.dir_shaped?
+            eager << { base: "#{entry.final_name}.md", dest: entry.dest, body: body } if kind.eager
           end
         end
-      end
-
-      def install_guidelines
-        @plan.select { |e| e.type == :guideline }.map do |entry|
-          body = entry.install_ready_body
-          warn_if_oversize(entry.dest, body)
-          install_file(entry: entry, type: :guideline, install_ready_body: body,
-            source_relpath: source_relpath_for(entry.artifact), final_name: entry.final_name)
-          { base: "#{entry.final_name}.md", dest: entry.dest, body: body }
+        eager
+      end
+
+      def install_support_files(entry, relpath)
+        support_base = support_relpath_base(entry.artifact, relpath)
+        entry.support_files.each do |file|
+          install_file(
+            dest: file[:dest],
+            type: :skill_support,
+            install_ready_body: file[:body],
+            source_gem: entry.source_gem,
+            version: entry.version,
+            artifact_kind: "skill_support",
+            source_relpath: file[:source_relpath] || (support_base && File.join(support_base, file[:path]))
+          )
         end
       end
 
@@ -241,7 +254,7 @@ module Rails
 
         # An edited sidecar is user work: leave it, and leave the lock at the
         # old upstream so this delivery is re-offered once the user clears it.
-        if File.exist?(abs(sidecar)) && !sidecar_pristine?(sidecar, write, old)
+        if File.exist?(abs(sidecar)) && !delivered_sidecar?(sidecar, delivered_shas(write, old))
           @result.skipped << dest
           @shell.say_status :warn, "#{sidecar} (sidecar locally modified; resolve or delete it)", :yellow
           @new_lock.carry(old) if old
@@ -319,18 +332,25 @@ module Rails
 
       # Only a machine-pristine sidecar — one still hashing to a delivered
       # upstream — may be refreshed or removed; anything else is user work.
-      def sidecar_pristine?(sidecar, write, old)
-        sha = DriftVerdict.disk_sha(abs(sidecar))
-        [old&.source_sha, write[:gem_sha]].compact.include?(sha)
+      def delivered_sidecar?(sidecar, shas)
+        Array(shas).compact.include?(DriftVerdict.disk_sha(abs(sidecar)))
       rescue StandardError
         false
       end
 
+      def delivered_shas(write, old)
+        [old&.source_sha, write[:gem_sha]]
+      end
+
       def sweep_sidecar(write, old)
-        sidecar = InstallLayout.sidecar_path(write[:dest])
+        sweep_sidecar_at(write[:dest], delivered_shas(write, old))
+      end
+
+      def sweep_sidecar_at(dest, shas)
+        sidecar = InstallLayout.sidecar_path(dest)
         return unless File.exist?(abs(sidecar))
 
-        if sidecar_pristine?(sidecar, write, old)
+        if delivered_sidecar?(sidecar, shas)
           @shell.remove_file sidecar
           @result.removed << sidecar
         else
@@ -380,8 +400,25 @@ module Rails
 
       # The pipeline's only delete path, so it is gated on the file still
       # matching the content the lock recorded: hand-edited work is reported and
-      # left for its owner to remove. Runs before orphans are carried, or a
-      # removed file would read as one.
+      # left for its owner to remove. The dest's sidecar goes with it, since
+      # nothing would reference or clean it afterwards.
+      def remove_or_carry(entry)
+        file = abs(entry.path)
+        return unless File.exist?(file)
+
+        if DriftVerdict.unedited?(file, lock_entry: entry)
+          @shell.remove_file entry.path
+          @result.removed << entry.path
+          sweep_sidecar_at(entry.path, [entry.source_sha])
+          prune_empty_dirs(entry.path)
+        else
+          @result.skipped << entry.path
+          @shell.say_status :skip, "#{entry.path} (#{yield entry})", :yellow
+          @new_lock.carry(entry)
+        end
+      end
+
+      # Runs before orphans are carried, or a removed file would read as one.
       def remove_disabled
         return if additive?
 
@@ -389,54 +426,62 @@ module Rails
           type = InstallLayout::ARTIFACT_TYPES[entry.kind]
           next unless type
           next if @new_lock.entry(entry.path)
+          next unless InstallPlan.disabled_dest?(old_lock, type, entry.path, source_gem: entry.source_gem)
 
-          next unless InstallPlan.disabled_dest?(old_lock, type, entry.path)
-
-          file = abs(entry.path)
-          next unless File.exist?(file)
-
-          if DriftVerdict.unedited?(file, lock_entry: entry)
-            @shell.remove_file entry.path
-            @result.removed << entry.path
-            prune_empty_dirs(entry.path)
-          else
-            @result.skipped << entry.path
-            @shell.say_status :skip,
-              "#{entry.path} (disabled but locally modified; delete it by hand)", :yellow
-            @new_lock.carry(entry)
-          end
+          remove_or_carry(entry) { "disabled but locally modified; delete it by hand" }
         end
       end
 
-      # Deletion is gated on the recorded sha, so a user-edited copy is never
-      # removed.
       def remove_stale_support_files
         return if additive?
 
-        planned_skill_dirs = @plan.select { |e| e.type == :skill }.map { |e| File.dirname(e.dest) }
+        planned_skill_dirs = @plan.select { |e| e.type == :skill }.map { |e| File.dirname(e.dest) }.to_set
 
         old_lock.each_entry do |entry|
           next unless entry.kind == "skill_support"
           next if @new_lock.entry(entry.path)
           next unless planned_skill_dirs.include?(InstallLayout.skill_dir_of(entry.path))
 
-          file = abs(entry.path)
-          next unless File.exist?(file)
+          remove_or_carry(entry) do |e|
+            "no longer shipped by #{e.source_label} but locally modified; delete it by hand"
+          end
+        end
+      end
 
-          if DriftVerdict.unedited?(file, lock_entry: entry)
-            @shell.remove_file entry.path
-            @result.removed << entry.path
-            prune_empty_dirs(entry.path)
-          else
-            @result.skipped << entry.path
-            @shell.say_status :skip,
-              "#{entry.path} (no longer shipped by #{entry.source_label} but locally modified; delete it by hand)",
-              :yellow
-            @new_lock.carry(entry)
+      # An artifact that moved — renamed, or flipped between its canonical and
+      # postfixed destination — leaves a byte-duplicate copy at the old
+      # destination. Removal also requires the source gem to be bundled and to
+      # have lost nothing to a discovery skip, so a broken companion release or
+      # a version fence never removes a good install.
+      def remove_stale_dests
+        return if additive?
+
+        planned = @plan.flat_map { |e| [e.dest, *e.support_files.map { |f| f[:dest] }] }.to_set
+
+        old_lock.each_entry do |entry|
+          next unless InstallLayout::ARTIFACT_TYPES[entry.kind]
+          next if planned.include?(entry.path)
+          next if @new_lock.entry(entry.path)
+          next if already_removed?(entry.path)
+          next unless source_gem_converged?(entry)
+
+          remove_or_carry(entry) do |e|
+            "#{e.source_gem} no longer installs this path but it is locally modified; delete it by hand"
           end
         end
       end
 
+      def source_gem_converged?(entry)
+        name = entry.source_gem.to_s
+        @bundled_gems.include?(name) && !@skipped_gems.include?(name)
+      end
+
+      # A dry run deletes nothing, so a path an earlier removal step already
+      # claimed is still on disk and must not be reported a second time.
+      def already_removed?(path)
+        @result.removed.include?(path)
+      end
+
       # Skill directories go only once empty; any user file keeps the whole
       # chain alive. The just-removed entry is subtracted because a dry run
       # deletes nothing from disk.
@@ -455,19 +500,27 @@ module Rails
       end
 
       def carry_orphans
-        planned = @plan.map(&:dest)
+        planned = @plan.map(&:dest).to_set
         old_lock.each_entry do |entry|
           next if planned.include?(entry.path)
           next if @new_lock.entry(entry.path)
+          next if already_removed?(entry.path)
           next unless DriftVerdict.verdict(file: abs(entry.path), lock_entry: entry, gem_sha: nil) == :orphaned
 
           @result.orphaned << entry.path
-          @shell.say_status :orphan,
-            "#{entry.path} (no longer shipped by #{entry.source_label}; left in place)", :yellow
+          @shell.say_status :orphan, "#{entry.path} (#{orphan_reason(entry)}; left in place)", :yellow
           @new_lock.carry(entry)
         end
       end
 
+      def orphan_reason(entry)
+        LockFile.orphan_reason(
+          source_label: entry.source_label,
+          source_gem: entry.source_gem,
+          bundled: @bundled_gems.include?(entry.source_gem.to_s)
+        )
+      end
+
       # Returns the eager set: the guidelines index.md ends up including.
       def write_index_md(guidelines)
         return amend_index_md(guidelines) if additive?
@@ -536,17 +589,28 @@ module Rails
         @shell.create_file InstallLayout::LOCK_PATH, @new_lock.to_yaml
       end
 
+      # A skip dropped shipped content — a whole artifact, or one supporting
+      # file of one; an advisory names a manifest problem that changed nothing
+      # about what installed.
       def print_warnings
-        return if Array(@warnings).empty?
+        skips = Array(@report.skips)
+        advisories = @report.advisories
+        print_warning_group skips, "discovery skipped #{skips.size} item(s):"
+        print_warning_group advisories, "discovery reported #{advisories.size} advisory warning(s):"
+      end
+
+      def print_warning_group(lines, header)
+        return if lines.empty?
         @shell.say ""
-        @shell.say_status :warn, "discovery skipped #{@warnings.size} artifact(s):", :yellow
-        @warnings.each { |w| @shell.say "    - #{w}" }
+        @shell.say_status :warn, header, :yellow
+        lines.each { |line| @shell.say "    - #{line}" }
       end
 
       def print_notices
-        return if additive? || Array(@notices).empty?
+        notices = Array(@report.notices)
+        return if additive? || notices.empty?
         @shell.say ""
-        @notices.each { |n| @shell.say_status :info, n, :blue }
+        notices.each { |n| @shell.say_status :info, n, :blue }
       end
 
       def print_footprint(guidelines:)

data/lib/rails/hyperdrive/install_plan.rb

@@ -7,19 +7,20 @@ module Rails
     # shipped by several installs every variant, postfixed --<source_gem>.
     module InstallPlan
       Entry = Struct.new(:type, :artifact, :final_name, :dest, :collision, keyword_init: true) do
-        # The renamed name: is part of the hashed body, so a postfixed skill
+        # The renamed name: is part of the hashed body, so a postfixed artifact
         # hashes to a stable value.
         def install_ready_body
           body = BundlerArtifactDiscovery.install_ready_body(artifact)
-          return body unless type == :skill && final_name != artifact.name
+          return body unless kind&.collision_rewrites_name && final_name != artifact.name
           body.sub(/^name:\s*.+$/, "name: #{final_name}")
         end
 
         def support_files
-          return [] unless type == :skill
+          return [] unless kind&.dir_shaped?
           dir = File.dirname(dest)
           Array(artifact.support_files).map do |file|
-            { path: file[:path], body: file[:body], dest: "#{dir}/#{file[:path]}" }
+            { path: file[:path], body: file[:body], dest: "#{dir}/#{file[:path]}",
+              source_relpath: file[:source_relpath] }
           end
         end
 
@@ -38,6 +39,10 @@ module Rails
         def artifact_kind
           type.to_s
         end
+
+        def kind
+          InstallLayout.kind(type)
+        end
       end
 
       Result = Struct.new(:entries, :disabled, keyword_init: true)
@@ -45,7 +50,9 @@ module Rails
       module_function
 
       # A collision installs under a postfixed name, so the shipped name
-      # disables every variant and a postfixed name disables just one.
+      # disables every variant and a postfixed name disables just one. The
+      # postfixed form is honored whether or not a collision exists today, so
+      # the opt-out survives a collision appearing or resolving.
       def build(artifacts, lock: nil)
         result = Result.new(entries: [], disabled: [])
         artifacts.group_by { |a| [a.artifact_type, a.name] }.each do |(type, name), group|
@@ -59,19 +66,24 @@ module Rails
               dest: InstallLayout.dest_for(type, final_name),
               collision: collision
             )
-            dropped = lock && (lock.disabled?(type, name) || (collision && lock.disabled?(type, final_name)))
+            dropped = lock && (lock.disabled?(type, name) ||
+                               lock.disabled?(type, InstallLayout.postfixed_name(name, artifact.source_gem)))
             (dropped ? result.disabled : result.entries) << entry
           end
         end
         result
       end
 
-      # A supporting file is disabled through its owning skill's name.
-      def disabled_dest?(lock, type, dest)
+      # A supporting file is disabled through its owning skill's name. Given the
+      # installing gem, a canonically-installed file also answers to the
+      # postfixed name that disabled it while it was one of several variants.
+      def disabled_dest?(lock, type, dest, source_gem: nil)
         name = InstallLayout.installed_name(type, dest)
         return false unless name
         lookup = type == :skill_support ? :skill : type
-        lock.disabled?(lookup, name) || lock.disabled?(lookup, InstallLayout.base_name(name))
+        base = InstallLayout.base_name(name)
+        return true if lock.disabled?(lookup, name) || lock.disabled?(lookup, base)
+        !source_gem.nil? && lock.disabled?(lookup, InstallLayout.postfixed_name(base, source_gem))
       end
     end
   end