kettle-jem 7.1.28 → 7.1.30

data/lib/kettle/jem.rb

@@ -23,9 +23,12 @@ require "rbs"
 require "kettle/dev"
 require "kettle/changelog"
 require "kettle/rb/compat_matrix"
+require "kettle/rb/gem_floors"
+require "kettle/rb/platform_support"
 require_relative "jem/version"
 require_relative "jem/license_txt_migrator"
 require_relative "jem/maintenance_changelog"
+require_relative "jem/relative_paths"
 
 begin
   require "kettle/drift"
@@ -51,17 +54,18 @@ module Kettle
     MANAGED_BLOCK_OPEN = "# <<kettle-jem:generated>> do not edit below this line"
     MANAGED_BLOCK_CLOSE = "# <</kettle-jem:generated>>"
     GEMSPEC_DEPENDENCY_MINIMUM_REQUIREMENTS = {
-      "rspec-stubbed_env" => ">= 1.0.6"
+      "rspec-stubbed_env" => ">= 1.0.17"
     }.freeze
     # Template dependency transitions are location-independent. Prepare finds
     # declarations in the destination and reconciles their complete requirement
     # set in place before Bundler is allowed to evaluate that destination.
     TEMPLATE_MANAGED_DEPENDENCIES = [
-      {name: "nomono", requirements: ["~> 1.1", ">= 1.1.5"], bootstrap: true},
-      {name: "kettle-dev", requirements: ["~> 3.1", ">= 3.1.0"], bootstrap: true},
+      {name: PACKAGE_NAME, requirements: ["~> 7.1", ">= 7.1.28"], bootstrap: false},
+      {name: "nomono", requirements: ["~> 1.1", ">= 1.1.7"], bootstrap: true},
+      {name: "kettle-dev", requirements: ["~> 3.1", ">= 3.1.13"], bootstrap: true},
       {
         name: "kettle-changelog",
-        requirements: ["~> 1.0", ">= 1.0.7"],
+        requirements: ["~> 1.0", ">= 1.0.10"],
         bootstrap: true,
         ruby_requirement: ">= 4.0.0"
       }
@@ -89,14 +93,99 @@ module Kettle
       "kettle-test -I ../spec --options ../.rspec ../spec"
     ].freeze
     DEFAULT_ENGINES = %w[ruby jruby truffleruby].freeze
+    # CI OS families a destination supports when it declares no `platforms:` key.
+    # Windows is opt-in only: Windows CI is materially slower and most gems do
+    # not need it, so a destination that wants it must declare it. The values
+    # are Kettle::Rb::PlatformSupport OS families, not Gem::Platform strings.
+    DEFAULT_PLATFORMS = %w[linux macos].freeze
+    # Matches GitHub Windows runner labels (windows-latest, windows-2022,
+    # windows-11-arm, ...) anywhere in a workflow file, which covers both a
+    # direct `runs-on:` and the `matrix.os` indirection. Validated against the
+    # packaged templates: their only Windows token is windows-latest, and
+    # `runs-on:` only ever appears as `${{ matrix.os }}` or an ubuntu label.
+    WINDOWS_RUNNER_LABEL_PATTERN = /windows-(?:latest|\d+)/i
+    # Documentation injected with `platforms:` by #migrate_platforms_config.
+    # Kept in sync with the packaged config template
+    # (templates/.structuredmerge/kettle-jem.yml.example).
+    PLATFORMS_CONFIG_DOCUMENTATION = [
+      "# List the OS platforms this project's CI exercises. kettle-jem uses this to",
+      "# generate the current.yml OS matrix and the README platform tier table.",
+      "# Windows applies only when declared: the `if: matrix.os` guards and the",
+      "# Windows-only test step are emitted solely for destinations that opt in.",
+      "#",
+      "# Supported values: linux, macos, windows",
+      "# Default (when key is absent): linux, macos",
+      "# These are CI OS families, a distinct vocabulary from Gem::Platform strings",
+      "# and Gemfile DSL platform symbols; never reuse them for",
+      "# `bundle lock --add-platform`."
+    ].freeze
     DEFAULT_OPENCOLLECTIVE_ORG = "galtzo-floss"
     # These tools remain active, but their dependency ownership belongs to the
     # generated modular Gemfiles rather than a destination gemspec.
     EXTERNALIZED_GEMSPEC_DEVELOPMENT_DEPENDENCIES = %w[kettle-drift kettle-soup-cover rubocop-rspec yard-junk].freeze
-    # These legacy release tools must not be retained in any managed dependency
-    # declaration. Kettle Dev owns release workflows.
-    PROHIBITED_GEMSPEC_DEPENDENCIES = %w[gem-release].freeze
+    # Gems superseded by a template-provided replacement, wrong everywhere
+    # regardless of whether the template places a replacement anywhere for
+    # this destination (case 2 of the dev-dependency conflict policy):
+    # unconditional removal, no review needed. gem-release is a legacy
+    # release tool - Kettle Dev owns release workflows. appraisal and
+    # turbo_tests were replaced by appraisal2 and turbo_tests2.
+    PROHIBITED_GEMSPEC_DEPENDENCIES = %w[gem-release appraisal turbo_tests].freeze
     PROHIBITED_GEMFILE_DEPENDENCIES = PROHIBITED_GEMSPEC_DEPENDENCIES.freeze
+    # Git sources Bundler already defines. A Gemfile override (for example an
+    # SSH `git_source(:github)`) replaces Bundler's own HTTPS source and is
+    # recorded in Gemfile.lock, where CI cannot clone it: unconditional removal.
+    BUNDLER_BUILTIN_GIT_SOURCES = %w[github gist bitbucket].freeze
+    STRUCTUREDMERGE_GEMS = %w[
+      ast-crispr ast-crispr-markdown-markly ast-crispr-ruby-prism ast-merge ast-merge-git
+      ast-template bash-merge binary-merge citrus-toml-merge commonmarker-merge dotenv-merge
+      go-merge html-merge json-merge kettle-jem kramdown-merge markdown-merge markly-merge
+      parslet-toml-merge plain-merge prism-merge psych-merge rbs-merge ruby-merge rust-merge
+      smorg-rb toml-merge tree_haver typescript-merge yaml-merge zip-merge
+    ].freeze
+    # Canonical resolutions for development-dependency gems whose handling is
+    # already known ahead of any specific destination project. Two
+    # categories today:
+    #
+    # :template_managed - the gem is always owned by a template modular
+    #   Gemfile; a direct declaration is always a stale duplicate. Detected
+    #   the same way as any other modular_dependency_conflicts entry (a
+    #   direct declaration plus a modular declaration of the same gem
+    #   name); when a newly surfaced conflict's gem matches one of these
+    #   (and force_review isn't set), the real decided entry is written
+    #   straight to dependency_conflicts.resolve instead of a placeholder
+    #   "review" entry.
+    #
+    # :engine_incompatible - the gem doesn't support every engine the
+    #   destination declares (config["engines"], falling back to
+    #   DEFAULT_ENGINES) and has no template-managed modular home (below the
+    #   template's inclusion threshold). Detected by #engine_dependency_conflicts, a
+    #   separate engine-declaration-based check (comparing supported_engines
+    #   against the destination's declared engines) rather than by
+    #   modular_dependency_conflicts, since there's no modular-side
+    #   declaration to match against. sqlite3 (the pilot entry) sets
+    #   force_review: true because there's no single correct action across
+    #   destinations - only the destination's own declared engines: decide
+    #   it. A future entry in this category with force_review: false would
+    #   auto-resolve via #engine_dependency_conflicts the same way
+    #   :template_managed does via modular_dependency_conflicts (both
+    #   funnel into the same auto_resolvable_known_gem_conflict? gate); its
+    #   registry action would need to make sense with no modular
+    #   counterpart to defer to, e.g. an unconditional removal.
+    KNOWN_GEM_CONFLICT_RESOLUTIONS = {
+      "debug" => {
+        category: :template_managed,
+        action: "remove_direct_gem",
+        reason: "debug is template-managed via gemfiles/modular/debug.gemfile (platform :mri); it ships a native C extension with no jruby/truffleruby release.",
+        force_review: false
+      }.freeze,
+      "sqlite3" => {
+        category: :engine_incompatible,
+        action: "review",
+        reason: "sqlite3 has no jruby-platform release on rubygems.org and is not template-managed; declare it in a modular gemfile with platforms: [:ruby] instead of a direct dependency (kettle-jem-appraisals generates gemfiles/modular/activerecord_support/*.gemfile, with the JDBC adapter on JRuby), or resolve per destination based on declared engines.",
+        supported_engines: %w[ruby].freeze,
+        force_review: true
+      }.freeze
+    }.freeze
     FILE_DELETION_PRIMITIVES = %w[
       supplied_obsolete_file_deletion
       supplied_opt_in_workflow_deletion
@@ -423,7 +512,6 @@ module Kettle
     TEMPLATE_SOURCE_APPLICATION_RECIPE = /\Atemplate_source_application_/
     DECISION_NO_WRITE_ACTIONS = %w[keep skip].freeze
     RUBY_TEMPLATE_POLICY_FILE_TYPES = %i[gemfile gemspec appraisals].freeze
-    GEMFILE_POLICY_SELF_DEPENDENCIES = %w[appraisal].freeze
     TEMPLATE_CONTENT_PRIMITIVES = %w[
       supplied_kettle_config_bootstrap
       supplied_template_source_preference
@@ -484,6 +572,7 @@ module Kettle
       KJ|MIN_RUBY
       KJ|KETTLE_CHANGELOG_GEMFILE_DEPENDENCY
       KJ|OPENCOLLECTIVE_ORG
+      KJ|RAKE:TOP_LEVEL_DOCS_TASK
       KJ|README:COPYRIGHT_NOTICE
       KJ|README:CORPORATE_SPONSORS
       KJ|README:FAMILY_INTRO_BACKEND_MATRIX
@@ -533,39 +622,10 @@ module Kettle
       }
     ])
     README_TOP_LOGO_TYPES = %w[related_org ruby language org project affiliated_project].freeze
-    APPRAISAL_NAME_PREFIX = "kja"
-    APPRAISAL_GEM_ABBREVIATIONS = {
-      "activerecord" => "ar",
-      "actionmailer" => "am",
-      "actionpack" => "ap",
-      "activesupport" => "as",
-      "activejob" => "aj",
-      "actioncable" => "ac",
-      "actionview" => "av",
-      "activestorage" => "ast",
-      "actionmailbox" => "amb",
-      "actiontext" => "at",
-      "omniauth" => "oa",
-      "mongoid" => "mo",
-      "sequel" => "sq",
-      "couch_potato" => "cp",
-      "rom" => "rom",
-      "rom-sql" => "rsql"
-    }.freeze
-    APPRAISAL_WORKFLOW_LIFECYCLE_RANGES = Ractor.make_shareable({
-      "current" => {min: Gem::Version.new("3.4"), max: Gem::Version.new("3.99")},
-      "supported" => {min: Gem::Version.new("3.2"), max: Gem::Version.new("3.3")},
-      "legacy" => {min: Gem::Version.new("3.0"), max: Gem::Version.new("3.1")},
-      "unsupported" => {min: Gem::Version.new("2.6"), max: Gem::Version.new("2.7")},
-      "ancient" => {min: Gem::Version.new("2.3"), max: Gem::Version.new("2.5")}
-    })
-    APPRAISAL_ALWAYS_EXCLUDED_GEMS = %w[version_gem].freeze
-    APPRAISAL_VERSION_SELECTION_MODES = %w[major minor patch minor-minmax semver].freeze
     DEFAULT_TEST_MINIMUM_RUBY = Gem::Version.new("2.4")
     REQUIRE_RELATIVE_MIN_RUBY = Gem::Version.new("2.2").freeze
     ANONYMOUS_VERSION_LOADER_MIN_RUBY = Gem::Version.new("2.2").freeze
     MODERN_GEMSPEC_VERSION_LOADER_MIN_RUBY = Gem::Version.new("3.1").freeze
-    APPRAISAL_DEFAULT_FRESHNESS_TTL = 604_800
     DECISION_ACTIONS = %w[create merge replace keep delete skip].freeze
     DECISION_SEVERITIES = %w[advisory warning fatal].freeze
 
@@ -2609,6 +2669,74 @@ module Kettle
       require "ast/crispr/ruby/prism"
       @runtime_dependencies_loaded = true
     end
+
+    # Grammars templating merges through tree_sitter_language_pack. Prefetching
+    # them through TSLP's hot-load API downloads and loads the grammars up
+    # front so the on-demand download cannot transiently fail inside a merge
+    # and surface as a misleading "No parser registered" abort.
+    TSLP_PREFETCH_LANGUAGES = %w[
+      bash
+      go
+      html
+      json
+      json5
+      markdown
+      rbs
+      ruby
+      rust
+      toml
+      tsx
+      typescript
+      yaml
+    ].freeze
+
+    def tslp_prefetch_languages(env)
+      override = env["KJ_TSLP_PREFETCH_LANGUAGES"]
+      return TSLP_PREFETCH_LANGUAGES if override.nil? || override.to_s.strip.empty?
+
+      override.to_s.split(/[\s,]+/).map(&:downcase).uniq
+    end
+
+    def prefetch_tslp_grammars(env: ENV, events: nil)
+      override = env["KJ_TSLP_PREFETCH_LANGUAGES"]
+      if DecisionPolicy.value_to_boolean(override) == false
+        return {attempted: false, reason: "disabled via KJ_TSLP_PREFETCH_LANGUAGES"}
+      end
+
+      languages = tslp_prefetch_languages(env)
+      report = TreeHaver.prefetch_languages(languages)
+      report[:languages] = languages
+      if events
+        emit_event(events, "diagnostic", {
+          severity: report.fetch(:failures, {}).empty? ? "advisory" : "warning",
+          category: "tslp_prefetch",
+          message: tslp_prefetch_message(report)
+        })
+      end
+      report
+    rescue => error
+      if events
+        emit_event(events, "diagnostic", {
+          severity: "warning",
+          category: "tslp_prefetch",
+          message: "TSLP grammar prefetch failed: #{error.class}: #{error.message}"
+        })
+      end
+      {attempted: false, reason: "#{error.class}: #{error.message}"}
+    end
+
+    def tslp_prefetch_message(report)
+      return "TSLP grammar prefetch skipped: #{report[:reason]}" unless report.fetch(:attempted, false)
+
+      prefetched = Array(report[:prefetched])
+      failures = report.fetch(:failures, {})
+      message = "TSLP grammar prefetch loaded #{prefetched.length} grammar(s): #{prefetched.sort.join(", ")}"
+      unless failures.empty?
+        detail = failures.sort.map { |name, reason| "#{name}: #{reason}" }.join("; ")
+        message += "; #{failures.length} failure(s): #{detail}"
+      end
+      message
+    end
     # rubocop:enable ThreadSafety/ClassInstanceVariable
 
     def display_path(path)
@@ -2650,546 +2778,6 @@ module Kettle
       load(File.expand_path("jem/tasks.rb", __dir__))
     end
 
-    def appraisal_gem_abbreviation(gem_name)
-      APPRAISAL_GEM_ABBREVIATIONS.fetch(gem_name.to_s, gem_name.to_s)
-    end
-
-    def appraisal_format_version(version)
-      version.to_s.tr(".", "-")
-    end
-
-    def appraisal_name(tier1_gem:, tier1_version:, ruby_series:, tier2_gem: nil, tier2_version: nil)
-      parts = [
-        APPRAISAL_NAME_PREFIX,
-        appraisal_gem_abbreviation(tier1_gem),
-        appraisal_format_version(tier1_version)
-      ]
-      unless tier2_gem.to_s.empty?
-        parts << appraisal_gem_abbreviation(tier2_gem)
-        parts << appraisal_format_version(tier2_version)
-      end
-      parts << ruby_series.to_s
-      parts.join("-")
-    end
-
-    def appraisal_modular_gemfile_path(gem_name:, version:, ruby_series:)
-      File.join("gemfiles", "modular", gem_name.to_s, ruby_series.to_s, "v#{version}.gemfile")
-    end
-
-    def appraisal_modular_gemfile_content(gem_name:, version:, sub_dependencies: {})
-      lines = [
-        "# frozen_string_literal: true",
-        "",
-        "# Generated by kettle-jem",
-        "",
-        %(gem "#{gem_name}", "#{appraisal_version_requirement(version)}")
-      ]
-      sub_dependencies.each do |name, requirement|
-        lines << %(gem "#{name}", "~> #{requirement}")
-      end
-      ensure_trailing_newline(lines.join("\n"))
-    end
-
-    def appraisal_version_requirement(version)
-      segments = version.to_s.split(".")
-      (segments.length >= 3) ? "~> #{version}" : "~> #{version}.0"
-    end
-
-    def appraisal_file_content(matrix_entries)
-      lines = [
-        "# frozen_string_literal: true",
-        "",
-        "# Generated by kettle-jem",
-        "# Do not edit directly; regenerate from Kettle/Jem appraisal matrix metadata.",
-        ""
-      ]
-      matrix_entries.each do |entry|
-        lines << %(appraise "#{entry.fetch(:name)}" do)
-        lines << %(  eval_gemfile "#{appraisal_eval_gemfile_path(entry.fetch(:tier1_gemfile))}") if entry[:tier1_gemfile]
-        lines << %(  eval_gemfile "#{appraisal_eval_gemfile_path(entry.fetch(:tier2_gemfile))}") if entry[:tier2_gemfile]
-        lines << %(  eval_gemfile "#{appraisal_eval_gemfile_path(entry.fetch(:x_std_libs_gemfile))}") if entry[:x_std_libs_gemfile]
-        lines << "end"
-        lines << ""
-      end
-      lines.pop while lines.last == ""
-      ensure_trailing_newline(lines.join("\n"))
-    end
-
-    def appraisal_eval_gemfile_path(path)
-      path.to_s.delete_prefix("gemfiles/")
-    end
-
-    def appraisal_workflow_groups(matrix_entries, bucket_ranges:, exec_cmd: "kettle-test")
-      grouped = Hash.new { |hash, key| hash[key] = [] }
-      normalized_ranges = bucket_ranges.transform_values do |range|
-        {
-          floor: Gem::Version.new((range[:floor] || range["floor"]).to_s),
-          ceiling: Gem::Version.new((range[:ceiling] || range["ceiling"]).to_s)
-        }
-      end
-      matrix_entries.each do |entry|
-        ruby_series = entry[:ruby_series] || entry["ruby_series"]
-        range = normalized_ranges[ruby_series]
-        next unless range
-
-        lifecycle = appraisal_workflow_lifecycle(range.fetch(:floor))
-        grouped[lifecycle] << {
-          ruby: appraisal_workflow_ruby(range.fetch(:floor), lifecycle),
-          appraisal: entry[:name] || entry["name"],
-          exec_cmd: exec_cmd,
-          rubygems: "latest",
-          bundler: "latest"
-        }
-      end
-      grouped.transform_values { |entries| entries.sort_by { |entry| entry.fetch(:appraisal).to_s } }
-    end
-
-    def appraisal_workflow_yaml_snippets(matrix_entries, bucket_ranges:, exec_cmd: "kettle-test")
-      appraisal_workflow_groups(matrix_entries, bucket_ranges: bucket_ranges, exec_cmd: exec_cmd).transform_values do |entries|
-        lines = ["strategy:", "  matrix:", "    include:"]
-        entries.each do |entry|
-          lines << %(      - ruby: "#{entry.fetch(:ruby)}")
-          lines << %(        appraisal: "#{entry.fetch(:appraisal)}")
-          lines << %(        exec_cmd: "#{entry.fetch(:exec_cmd)}")
-          lines << %(        rubygems: "#{entry.fetch(:rubygems)}")
-          lines << %(        bundler: "#{entry.fetch(:bundler)}")
-        end
-        lines.join("\n")
-      end
-    end
-
-    def appraisal_workflow_lifecycle(ruby_floor)
-      APPRAISAL_WORKFLOW_LIFECYCLE_RANGES.each do |name, range|
-        return name if ruby_floor.between?(range.fetch(:min), range.fetch(:max))
-      end
-      (ruby_floor < APPRAISAL_WORKFLOW_LIFECYCLE_RANGES.fetch("ancient").fetch(:min)) ? "ancient" : "current"
-    end
-
-    def appraisal_workflow_ruby(ruby_floor, lifecycle)
-      return "ruby" if lifecycle == "current"
-
-      segments = ruby_floor.segments
-      "#{segments[0]}.#{segments[1] || 0}"
-    end
-
-    def appraisal_x_stdlib_exclusions(template_content)
-      gems = ruby_call_records(template_content, :eval_gemfile).filter_map do |call|
-        path = ruby_string_argument(call).to_s
-        next unless path.start_with?("../")
-
-        path.delete_prefix("../").split("/").first
-      end
-      (gems + APPRAISAL_ALWAYS_EXCLUDED_GEMS).uniq.sort
-    end
-
-    def appraisal_select_versions(version_metadata, mode:, requirements: nil)
-      mode = mode.to_s
-      raise ArgumentError, "invalid appraisal version selection mode: #{mode}" unless APPRAISAL_VERSION_SELECTION_MODES.include?(mode)
-
-      versions = appraisal_filtered_versions(version_metadata, requirements: requirements)
-      return versions if mode == "patch"
-
-      by_major = appraisal_minor_versions_by_major(versions)
-      return [] if by_major.empty?
-
-      current_major = by_major.last.fetch(:major)
-      case mode
-      when "major"
-        by_major.map { |entry| entry.fetch(:minors).last }
-      when "minor"
-        by_major.flat_map { |entry| entry.fetch(:minors) }
-      when "minor-minmax"
-        by_major.flat_map do |entry|
-          minors = entry.fetch(:minors)
-          (entry.fetch(:major) < current_major) ? [minors.first, minors.last].uniq : minors
-        end
-      when "semver"
-        by_major.flat_map do |entry|
-          (entry.fetch(:major) < current_major) ? [entry.fetch(:minors).last] : entry.fetch(:minors)
-        end
-      end
-    end
-
-    def appraisal_matrix_entries(tier1_gems:, tier2_gems: [])
-      entries = []
-      tier1_gems.each do |tier1|
-        tier1_name = tier1[:name] || tier1["name"]
-        assignments = tier1[:assignments] || tier1["assignments"] || []
-        assignments.each do |assignment|
-          tier1_version = assignment[:version] || assignment["version"]
-          ruby_series = assignment[:bucket] || assignment["bucket"] || assignment[:ruby_series] || assignment["ruby_series"]
-          if tier2_gems.empty?
-            entries << appraisal_matrix_entry(
-              tier1_name: tier1_name,
-              tier1_version: tier1_version,
-              ruby_series: ruby_series
-            )
-          else
-            tier2_gems.each do |tier2|
-              tier2_name = tier2[:name] || tier2["name"]
-              Array(tier2[:versions] || tier2["versions"]).each do |tier2_version|
-                entries << appraisal_matrix_entry(
-                  tier1_name: tier1_name,
-                  tier1_version: tier1_version,
-                  ruby_series: ruby_series,
-                  tier2_name: tier2_name,
-                  tier2_version: tier2_version
-                )
-              end
-            end
-          end
-        end
-      end
-      entries
-    end
-
-    def appraisal_matrix_entry(tier1_name:, tier1_version:, ruby_series:, tier2_name: nil, tier2_version: nil)
-      {
-        name: appraisal_name(
-          tier1_gem: tier1_name,
-          tier1_version: tier1_version,
-          tier2_gem: tier2_name,
-          tier2_version: tier2_version,
-          ruby_series: ruby_series
-        ),
-        tier1_gemfile: appraisal_modular_gemfile_path(gem_name: tier1_name, version: tier1_version, ruby_series: ruby_series),
-        tier2_gemfile: tier2_name ? appraisal_modular_gemfile_path(gem_name: tier2_name, version: tier2_version, ruby_series: ruby_series) : nil,
-        x_std_libs_gemfile: File.join("gemfiles", "modular", "x_std_libs", ruby_series.to_s, "libs.gemfile"),
-        ruby_series: ruby_series.to_s
-      }
-    end
-
-    def appraisal_filtered_versions(version_metadata, requirements:)
-      requirement = requirements ? Gem::Requirement.new(Array(requirements)) : nil
-      version_metadata.filter_map do |entry|
-        number = entry[:number] || entry["number"]
-        next if number.to_s.empty?
-        next if entry[:prerelease] || entry["prerelease"]
-        next if requirement && !requirement.satisfied_by?(Gem::Version.new(number))
-
-        number.to_s
-      end.sort_by { |version| Gem::Version.new(version) }
-    end
-
-    def appraisal_minor_versions_by_major(versions)
-      versions.map do |version|
-        gem_version = Gem::Version.new(version)
-        segments = gem_version.segments
-        {
-          major: segments[0],
-          minor: "#{segments[0]}.#{segments[1] || 0}"
-        }
-      end.uniq.group_by { |entry| entry.fetch(:major) }.map do |major, entries|
-        {
-          major: major,
-          minors: entries.map { |entry| entry.fetch(:minor) }.sort_by { |minor| Gem::Version.new(minor) }
-        }
-      end.sort_by { |entry| entry.fetch(:major) }
-    end
-
-    def appraisal_find_ruby_seams(version_metadata)
-      minors = appraisal_latest_patch_by_minor(version_metadata)
-      seams = []
-      previous = nil
-      minors.sort_by { |minor, _entry| Gem::Version.new(minor) }.each do |minor, entry|
-        min_ruby = Gem::Version.new((entry[:min_ruby] || entry["min_ruby"]).to_s)
-        min_ruby = [min_ruby, DEFAULT_TEST_MINIMUM_RUBY].max
-        if previous.nil? || min_ruby > previous
-          seams << {version: minor, min_ruby: min_ruby}
-        end
-        previous = min_ruby
-      end
-      seams
-    end
-
-    def appraisal_ruby_series(version_metadata, project_min_ruby: nil)
-      floors = appraisal_find_ruby_seams(version_metadata).map { |seam| seam.fetch(:min_ruby) }
-      if project_min_ruby
-        floor = Gem::Version.new(project_min_ruby.to_s)
-        floors.reject! { |version| version < floor }
-        floors << floor unless floors.include?(floor)
-      end
-      floors = [Gem::Version.new("3.2")] if floors.empty?
-      appraisal_minor_versions_to_buckets(floors.map { |version| appraisal_minor_key(version) }.uniq.sort)
-    end
-
-    def appraisal_assign_version_buckets(selected_versions:, seams:, buckets:, bucket_ranges:, all_versions:)
-      return [] if selected_versions.empty? || buckets.empty?
-
-      normalized_ranges = appraisal_normalized_bucket_ranges(bucket_ranges)
-      version_min_rubies = appraisal_version_min_ruby_map(all_versions, seams)
-      assignments = selected_versions.sort_by { |version| Gem::Version.new(version) }.filter_map do |version|
-        min_ruby = version_min_rubies[version]
-        next unless min_ruby
-
-        next_seam = appraisal_next_seam_ruby(version, min_ruby, all_versions, version_min_rubies)
-        bucket = next_seam ? appraisal_bucket_below(next_seam, buckets, normalized_ranges) : buckets.last
-        {version: version, bucket: bucket} if bucket
-      end
-      appraisal_fill_bucket_gaps(assignments, buckets, normalized_ranges, version_min_rubies, all_versions)
-    end
-
-    def appraisal_latest_patch_by_minor(version_metadata)
-      version_metadata.each_with_object({}) do |entry, latest|
-        number = (entry[:number] || entry["number"]).to_s
-        next if number.empty?
-
-        version = Gem::Version.new(number)
-        minor = "#{version.segments[0]}.#{version.segments[1] || 0}"
-        current = latest[minor]
-        latest[minor] = entry if current.nil? || version > Gem::Version.new((current[:number] || current["number"]).to_s)
-      end
-    end
-
-    def appraisal_minor_versions_to_buckets(minor_versions)
-      by_major = minor_versions.group_by { |minor| minor.split(".").first.to_i }
-      buckets = []
-      ranges = {}
-      by_major.each do |major, minors|
-        sorted = minors.sort_by { |minor| Gem::Version.new(minor) }
-        sorted.each_with_index do |minor, index|
-          bucket = (index == sorted.length - 1) ? "r#{major}" : "r#{major}.#{[sorted[index + 1].split(".").last.to_i - 1, minor.split(".").last.to_i].max}"
-          next if ranges.key?(bucket)
-
-          buckets << bucket
-          ceiling = if index == sorted.length - 1
-            "#{major}.99"
-          else
-            bucket.split(".").last ? "#{major}.#{bucket.split(".").last}" : "#{major}.99"
-          end
-          ranges[bucket] = {floor: Gem::Version.new(minor), ceiling: Gem::Version.new(ceiling)}
-        end
-      end
-      {buckets: buckets.sort_by { |bucket| appraisal_bucket_sort_key(bucket) }, bucket_ranges: ranges}
-    end
-
-    def appraisal_minor_key(version)
-      segments = Gem::Version.new(version.to_s).segments
-      "#{segments[0]}.#{segments[1] || 0}"
-    end
-
-    def appraisal_bucket_sort_key(bucket)
-      match = bucket.to_s.match(/\Ar(\d+)(?:\.(\d+))?\z/)
-      [match[1].to_i, match[2] ? match[2].to_i : 999]
-    end
-
-    def appraisal_normalized_bucket_ranges(bucket_ranges)
-      bucket_ranges.transform_values do |range|
-        {
-          floor: Gem::Version.new((range[:floor] || range["floor"]).to_s),
-          ceiling: Gem::Version.new((range[:ceiling] || range["ceiling"]).to_s)
-        }
-      end
-    end
-
-    def appraisal_version_min_ruby_map(all_versions, seams)
-      sorted_seams = seams.sort_by { |seam| Gem::Version.new(seam[:version] || seam["version"]) }
-      seam_index = 0
-      current = nil
-      all_versions.sort_by { |version| Gem::Version.new(version) }.each_with_object({}) do |version, map|
-        while seam_index < sorted_seams.length && Gem::Version.new(sorted_seams[seam_index][:version] || sorted_seams[seam_index]["version"]) <= Gem::Version.new(version)
-          current = Gem::Version.new((sorted_seams[seam_index][:min_ruby] || sorted_seams[seam_index]["min_ruby"]).to_s)
-          current = [current, DEFAULT_TEST_MINIMUM_RUBY].max
-          seam_index += 1
-        end
-        map[version] = current if current
-      end
-    end
-
-    def appraisal_next_seam_ruby(version, min_ruby, all_versions, version_min_rubies)
-      found = false
-      all_versions.sort_by { |candidate| Gem::Version.new(candidate) }.each do |candidate|
-        found ||= Gem::Version.new(candidate) >= Gem::Version.new(version)
-        next unless found
-
-        candidate_ruby = version_min_rubies[candidate]
-        return candidate_ruby if candidate_ruby && candidate_ruby > min_ruby
-      end
-      nil
-    end
-
-    def appraisal_bucket_below(ruby_floor, buckets, bucket_ranges)
-      buckets.filter_map do |bucket|
-        range = bucket_ranges[bucket]
-        next unless range && range.fetch(:ceiling) < ruby_floor
-
-        [bucket, range.fetch(:ceiling)]
-      end.max_by(&:last)&.first
-    end
-
-    def appraisal_fill_bucket_gaps(assignments, buckets, bucket_ranges, version_min_rubies, all_versions)
-      covered = assignments.map { |assignment| assignment.fetch(:bucket) }
-      (buckets - covered).each do |bucket|
-        range = bucket_ranges[bucket]
-        next unless range
-
-        filler = all_versions.sort_by { |version| Gem::Version.new(version) }.reverse.find do |version|
-          ruby = version_min_rubies[version]
-          ruby&.between?(range.fetch(:floor), range.fetch(:ceiling))
-        end
-        filler ||= all_versions.sort_by { |version| Gem::Version.new(version) }.reverse.find do |version|
-          ruby = version_min_rubies[version]
-          ruby && ruby <= range.fetch(:ceiling)
-        end
-        assignments << {version: filler, bucket: bucket, filler: true} if filler
-      end
-      assignments.sort_by { |assignment| bucket_ranges.fetch(assignment.fetch(:bucket)).fetch(:floor) }
-    end
-
-    def appraisal_resolve_sub_dependencies(parent_gem:, parent_version:, parent_versions:, dependency_versions:, ruby_min: nil, excluded_gems: [])
-      parent = appraisal_latest_version_matching(parent_versions, parent_version)
-      return {} unless parent
-
-      ruby_floor = Gem::Version.new(ruby_min.to_s) unless ruby_min.to_s.empty?
-      excluded = excluded_gems.map(&:to_s)
-      Array(parent[:runtime_dependencies] || parent["runtime_dependencies"]).each_with_object({}) do |dependency, resolved|
-        name = (dependency[:name] || dependency["name"]).to_s
-        next if name.empty? || excluded.include?(name)
-
-        requirement = begin
-          Gem::Requirement.new(dependency[:requirements] || dependency["requirements"] || ">= 0")
-        rescue ArgumentError
-          Gem::Requirement.default
-        end
-        selected = appraisal_select_dependency_version(
-          Array(dependency_versions[name] || dependency_versions[name.to_sym]),
-          requirement: requirement,
-          ruby_min: ruby_floor
-        )
-        resolved[name] = selected if selected
-      end
-    end
-
-    def appraisal_latest_version_matching(version_metadata, requested_version)
-      prefix = "#{requested_version}."
-      version_metadata.select do |entry|
-        number = (entry[:number] || entry["number"]).to_s
-        number == requested_version.to_s || number.start_with?(prefix)
-      end.max_by { |entry| Gem::Version.new((entry[:number] || entry["number"]).to_s) }
-    end
-
-    def appraisal_select_dependency_version(version_metadata, requirement:, ruby_min:)
-      compatible = version_metadata.select do |entry|
-        number = (entry[:number] || entry["number"]).to_s
-        !number.empty? && requirement.satisfied_by?(Gem::Version.new(number))
-      end.sort_by { |entry| Gem::Version.new((entry[:number] || entry["number"]).to_s) }
-      return if compatible.empty?
-
-      if ruby_min
-        selected = compatible.reverse.find do |entry|
-          min_ruby = entry[:min_ruby] || entry["min_ruby"]
-          min_ruby.to_s.empty? || Gem::Version.new(min_ruby.to_s) <= ruby_min
-        end
-        return (selected || compatible.first).then { |entry| entry[:number] || entry["number"] }
-      end
-      compatible.last.then { |entry| entry[:number] || entry["number"] }
-    end
-
-    def appraisal_stale_gemfile_paths(existing_paths:, current_entries:)
-      current_names = current_entries.map { |entry| (entry[:name] || entry["name"]).to_s }.to_set
-      existing_paths.map(&:to_s).select do |path|
-        basename = File.basename(path, ".gemfile")
-        path.start_with?("gemfiles/#{APPRAISAL_NAME_PREFIX}-") &&
-          path.end_with?(".gemfile") &&
-          !current_names.include?(basename)
-      end.sort
-    end
-
-    def appraisal_extract_runtime_dependencies(gemspec_content)
-      gemspec_dependency_records(gemspec_content)
-        .reject { |record| record.fetch(:kind) == "add_development_dependency" }
-        .map { |record| record.fetch(:name) }
-        .uniq
-    end
-
-    def appraisal_scaffold_config(gemspec_content:, existing_config: {}, exclusions: [], default_mode: "semver", freshness_ttl: APPRAISAL_DEFAULT_FRESHNESS_TTL)
-      excluded = exclusions.map(&:to_s).to_set
-      runtime_dependencies = appraisal_extract_runtime_dependencies(gemspec_content)
-      tier1 = runtime_dependencies.reject { |name| excluded.include?(name) }.map { |name| {"name" => name} }
-      config = deep_string_key_hash(existing_config)
-      matrix = config["appraisal_matrix"] || {}
-      gems = matrix["gems"] || {}
-
-      matrix["mode"] ||= default_mode
-      matrix["freshness_ttl"] ||= freshness_ttl
-      gems["tier1"] = tier1
-      gems["tier2"] ||= []
-      matrix["gems"] = gems
-      config["appraisal_matrix"] = matrix
-      config
-    end
-
-    def appraisal_matrix_has_versions?(matrix)
-      gems = deep_string_key_hash(matrix || {}).fetch("gems", {})
-      %w[tier1 tier2].any? do |tier|
-        Array(gems[tier]).any? { |gem_config| Array(gem_config["versions"]).any? }
-      end
-    end
-
-    def appraisal_matrix_fresh?(matrix, now: Time.now.to_i)
-      resolved_at = (matrix || {})[:resolved_at] || (matrix || {})["resolved_at"]
-      return false unless resolved_at
-
-      ttl = (matrix || {})[:freshness_ttl] || (matrix || {})["freshness_ttl"] || APPRAISAL_DEFAULT_FRESHNESS_TTL
-      (now.to_i - resolved_at.to_i) < ttl.to_i
-    end
-
-    def appraisal_time_ago(timestamp, now: Time.now.to_i)
-      return "unknown" unless timestamp
-
-      seconds = now.to_i - timestamp.to_i
-      return "#{seconds / 60}m" if seconds < 3600
-      return "#{seconds / 3600}h" if seconds < 86_400
-
-      "#{seconds / 86_400}d"
-    end
-
-    def appraisal_all_versions_for(resolver:, gem_name:, mode:, requirements: nil, include_versions: nil, exclude_versions: nil)
-      base_versions = if mode.to_s == "patch"
-        resolver.versions(gem_name, requirements: requirements).map { |entry| entry[:number] || entry["number"] }
-      else
-        resolver.minor_versions_by_major(gem_name, requirements: requirements).flat_map { |entry| entry[:minors] || entry["minors"] }
-      end
-      appraisal_finalize_versions(base_versions, include_versions: include_versions, exclude_versions: exclude_versions)
-    end
-
-    def appraisal_finalize_versions(base_versions, include_versions: nil, exclude_versions: nil)
-      merged = appraisal_sort_versions(Array(base_versions) + Array(include_versions))
-      excluded = Array(exclude_versions).map(&:to_s).to_set
-      return merged if excluded.empty?
-
-      appraisal_sort_versions(merged.reject { |version| excluded.include?(version) })
-    end
-
-    def appraisal_compatible_version_for_bucket?(resolver:, gem_name:, version:, ruby_series:, bucket_ranges:)
-      range = bucket_ranges[ruby_series] || bucket_ranges[ruby_series.to_s]
-      return true unless range
-
-      ceiling = Gem::Version.new((range[:ceiling] || range["ceiling"]).to_s)
-      exact_version = appraisal_latest_minor_patch(resolver: resolver, gem_name: gem_name, version: version)
-      min_ruby = resolver.min_ruby_version(gem_name, exact_version)
-      min_ruby.nil? || Gem::Version.new(min_ruby.to_s) <= ceiling
-    rescue
-      true
-    end
-
-    def appraisal_latest_minor_patch(resolver:, gem_name:, version:)
-      all_versions = resolver.versions(gem_name)
-      prefix = "#{version}."
-      matching = all_versions.select do |entry|
-        number = (entry[:number] || entry["number"]).to_s
-        number == version.to_s || number.start_with?(prefix)
-      end
-      return version.to_s if matching.empty?
-
-      latest = matching.max_by { |entry| Gem::Version.new((entry[:number] || entry["number"]).to_s) }
-      (latest[:number] || latest["number"]).to_s
-    end
-
-    def appraisal_sort_versions(values)
-      values.compact.map(&:to_s).reject(&:empty?).uniq.sort_by { |version| Gem::Version.new(version) }
-    end
-
     def deep_string_key_hash(value)
       case value
       when Hash
@@ -3274,6 +2862,7 @@ module Kettle
       }
       bootstrap = kettle_config_bootstrap_facts(project_root, env, template_selection: template_selection)
       bootstrap[:licenses] = configured_or_detected_licenses if bootstrap && !configured_or_detected_licenses.empty?
+      bootstrap[:platforms] = detected_os_platforms(project_root) if bootstrap && !detected_os_platforms(project_root).empty?
       facts[:kettle_config_bootstrap] = bootstrap if bootstrap
       facts[:author] = author unless author.empty?
       facts[:copyright] = copyright unless copyright.empty?
@@ -3521,12 +3110,21 @@ module Kettle
       facts[:version_gem] = version_gem_facts unless version_gem_facts.empty?
       facts[:shim] = shim unless shim.empty?
       facts[:repository] = repository unless repository.empty?
-      generated_blocks = generated_blocks_facts(gemspec_metadata, facts.merge(project_root: File.expand_path(project_root)), run_options)
+      # facts[:ci] itself isn't assembled until later in this method, but
+      # shunted_gemfile_block needs the project's effective CI test floor
+      # (already resolved into project_runtime, above) rather than the
+      # gemspec's own, often much older, required_ruby_version.
+      generated_blocks = generated_blocks_facts(
+        gemspec_metadata,
+        facts.merge(project_root: File.expand_path(project_root), ci: {test_min_ruby: project_runtime.fetch(:test_min_ruby).to_s}),
+        run_options
+      )
       facts[:generated_blocks] = generated_blocks unless generated_blocks.empty?
       bootstrap = kettle_config_bootstrap_facts(project_root, env, template_selection: template_selection)
       if bootstrap
         min_ruby_token = minimum_ruby_token(min_ruby)
         bootstrap[:licenses] = gemspec_license_spdx unless gemspec_license_spdx.empty?
+        bootstrap[:platforms] = detected_os_platforms(project_root) unless detected_os_platforms(project_root).empty?
         bootstrap[:gemspec_path] = File.basename(gemspec_path) if gemspec_path
         bootstrap[:min_ruby] = min_ruby_token unless min_ruby_token.empty?
         bootstrap[:test_min_ruby] = config_test_min_ruby(kettle_config, min_ruby).to_s
@@ -3593,6 +3191,7 @@ module Kettle
         default_branch: "main",
         exec_cmd: github_actions_exec_cmd(kettle_config, env),
         engine_exec_cmds: github_actions_engine_exec_cmds(kettle_config),
+        platforms: ci_os_platforms_facts(kettle_config, project_root),
         recording: project_recording_enabled?(project_root, kettle_config),
         ruby_versions: github_actions_ruby_versions(project_runtime.fetch(:test_min_ruby)),
         test_min_ruby: project_runtime.fetch(:test_min_ruby).to_s,
@@ -3882,7 +3481,7 @@ module Kettle
       dependencies = extract_gemspec_development_dependencies(gemspec)
       return if dependencies.empty?
 
-      floor = shunted_effective_floor(facts.dig(:rubygems, :min_ruby))
+      floor = shunted_effective_floor(facts.dig(:ci, :test_min_ruby) || facts.dig(:rubygems, :min_ruby))
       project_root = facts[:project_root] || facts["project_root"] || run_options[:project_root] || run_options["project_root"]
       shunted = dependencies.filter_map do |dependency|
         next if shunted_dependency_has_modular_override?(project_root, dependency)
@@ -3951,11 +3550,11 @@ module Kettle
 
     def shunted_effective_floor(min_ruby)
       floor = minimum_ruby_token(min_ruby)
-      versions = [Gem::Version.new("2.3")]
+      versions = [DEFAULT_TEST_MINIMUM_RUBY]
       versions << Gem::Version.new(floor) unless floor.to_s.empty?
       versions.max
     rescue ArgumentError
-      Gem::Version.new("2.3")
+      DEFAULT_TEST_MINIMUM_RUBY
     end
 
     def shunted_gemfile_managed_block(dependencies)
@@ -3978,6 +3577,7 @@ module Kettle
       events = event_stream_from_options(run_options)
       emit_event(events, "run_start", mode: "plan", project_root: project_root.to_s)
       with_event_phase(events, "runtime_dependencies") { ensure_runtime_dependencies! }
+      with_event_phase(events, "tslp_prefetch") { prefetch_tslp_grammars(env: env, events: events) }
       with_event_phase(events, "preflight") { preflight_project!(project_root) }
       template_selection = with_event_phase(events, "template_selection") { template_selection_for(env, run_options) }
       checksum_mode = with_event_phase(events, "checksum_mode") { checksum_mode_for(env, run_options) }
@@ -4194,6 +3794,10 @@ module Kettle
       # Config migrations are implemented during template application. They must
       # run even when the template source and destination checksums still match.
       return false if report.fetch(:relative_path, "").to_s == KETTLE_CONFIG_PATH
+      # Appraisal.root.gemfile has facts-dependent structural normalization in
+      # its accepted-template finalizer, so matching source/destination hashes
+      # do not prove that the final output is already normalized.
+      return false if report.fetch(:relative_path, "").to_s == "Appraisal.root.gemfile"
 
       primitive = report.dig(:request_envelope, :request, :recipe_name).to_s
       primitive == "supplied_template_source_application"
@@ -4227,6 +3831,12 @@ module Kettle
       if template_file_type_for_relative_path(report.fetch(:relative_path).to_s) == :appraisals
         payload[:appraisals_template_policy_fingerprint_version] = APPRAISALS_TEMPLATE_POLICY_FINGERPRINT_VERSION
       end
+      if report.fetch(:relative_path).to_s.start_with?("gemfiles/modular/")
+        conflict_policy = modular_dependency_conflict_decisions(
+          kettle_jem_config(project_root)
+        ).select { |decision| decision.fetch("modular") == report.fetch(:relative_path).to_s }
+        payload[:modular_dependency_conflict_policy] = conflict_policy
+      end
       if template_file_type_for_relative_path(report.fetch(:relative_path).to_s) == :gemspec
         payload[:gemspec_template_policy_fingerprint_version] = GEMSPEC_TEMPLATE_POLICY_FINGERPRINT_VERSION
       end
@@ -4721,19 +4331,11 @@ module Kettle
       report[:changed_files] = (report.fetch(:changed_files, []) + report.fetch(:post_apply_steps).flat_map do |step|
         reported_post_apply_changed_files(step)
       end).uniq.sort
-      report[:duplicate_drift] = with_event_phase(events, "duplicate_drift") do
-        if DecisionPolicy.value_to_boolean((run_options || {})[:skip_drift_check])
-          {
-            available: false,
-            skipped: true,
-            reason: "skip_drift_check"
-          }
-        else
-          duplicate_drift_report(
-            project_root: project_root,
-            template_root: template_root_path(project_root, config: kettle_jem_config(project_root)),
-            run_options: run_options
-          )
+      report[:duplicate_drift] = if DecisionPolicy.value_to_boolean((run_options || {})[:defer_drift_check])
+        {available: false, skipped: true, reason: "deferred_until_postprocessing"}
+      else
+        with_event_phase(events, "duplicate_drift") do
+          duplicate_drift_check_result(project_root: project_root, run_options: run_options)
         end
       end
       report[:phase_timings] = events.phase_timings if events.respond_to?(:phase_timings)
@@ -4741,6 +4343,25 @@ module Kettle
       report
     end
 
+    def finalize_duplicate_drift(project_root:, report:, run_options: {})
+      events = event_stream_from_options(run_options)
+      drift = with_event_phase(events, "duplicate_drift") do
+        duplicate_drift_check_result(project_root: project_root, run_options: run_options)
+      end
+      report.merge(duplicate_drift: drift, phase_timings: events.phase_timings)
+    end
+
+    def duplicate_drift_check_result(project_root:, run_options: {})
+      return {available: false, skipped: true, reason: "skip_drift_check"} if
+        DecisionPolicy.value_to_boolean((run_options || {})[:skip_drift_check])
+
+      duplicate_drift_report(
+        project_root: project_root,
+        template_root: template_root_path(project_root, config: kettle_jem_config(project_root)),
+        run_options: run_options
+      )
+    end
+
     def event_stream(io, types: nil)
       Kettle::Ndjson.event_stream(
         io,
@@ -5483,6 +5104,7 @@ module Kettle
         ensure_trailing_newline(content.to_s.empty? ? %(source "https://gem.coop"\n) : content.to_s).dup
       )
       updated = remove_gemfile_dependency_blocks(updated, PROHIBITED_GEMFILE_DEPENDENCIES)
+      updated = remove_gemfile_builtin_git_source_overrides(updated).dup
       monorepo_root_gemfile_dependency_lines.each do |line|
         next if gemfile_declares_gem?(updated, line.fetch(:name))
 
@@ -5494,17 +5116,17 @@ module Kettle
 
     def monorepo_root_gemfile_dependency_lines
       [
-        {name: "appraisal2", source: %(gem "appraisal2", "~> 3.2", ">= 3.2.3"\n)},
+        {name: "appraisal2", source: %(gem "appraisal2", "~> 3.2", ">= 3.2.5"\n)},
         {name: "bundler-audit", source: %(gem "bundler-audit", "~> 0.9.3"\n)},
-        {name: "kettle-dev", source: %(gem "kettle-dev", "~> 3.1", ">= 3.1.0"\n)},
-        {name: "kettle-drift", source: %(gem "kettle-drift", "~> 1.0", ">= 1.0.13"\n)},
-        {name: "kettle-family", source: %(gem "kettle-family", "~> 1.3", ">= 1.3.1"\n)},
+        {name: "kettle-dev", source: %(gem "kettle-dev", "~> 3.1", ">= 3.1.13"\n)},
+        {name: "kettle-drift", source: %(gem "kettle-drift", "~> 1.0", ">= 1.0.16"\n)},
+        {name: "kettle-family", source: %(gem "kettle-family", "~> 1.3", ">= 1.3.10"\n)},
         {name: PACKAGE_NAME, source: kettle_jem_dependency_source},
-        {name: "kettle-test", source: %(gem "kettle-test", "~> 2.0", ">= 2.0.21"\n)},
+        {name: "kettle-test", source: %(gem "kettle-test", "~> 2.0", ">= 2.0.25"\n)},
         {name: "rake", source: %(gem "rake", "~> 13.0"\n)},
         {name: "rspec", source: %(gem "rspec", "~> 3.0"\n)},
-        {name: "stone_checksums", source: %(gem "stone_checksums", "~> 1.0", ">= 1.0.8"\n)},
-        {name: "turbo_tests2", source: %(gem "turbo_tests2", "~> 3.2", ">= 3.2.7"\n)}
+        {name: "stone_checksums", source: %(gem "stone_checksums", "~> 1.0", ">= 1.0.9"\n)},
+        {name: "turbo_tests2", source: %(gem "turbo_tests2", "~> 4.0", ">= 4.0.0"\n)}
       ].freeze
     end
 
@@ -5546,6 +5168,24 @@ module Kettle
       end.sort
     end
 
+    # CI OS families evidenced by the destination's existing workflows. The
+    # heuristic exists so re-templating a repo that already runs Windows CI
+    # does not silently drop that coverage when the `platforms:` key is
+    # injected or generated from. It only ever ADDS windows to the default:
+    # the key's absent-means-default semantics already cover linux and macos,
+    # and every packaged workflow is Linux-only except current.yml, which the
+    # template always ships with ubuntu and macos lanes. Returns [] when the
+    # destination has no workflow directory, so callers fall back cleanly.
+    def detected_os_platforms(project_root)
+      workflows_dir = File.join(project_root.to_s, ".github", "workflows")
+      return [] unless Dir.exist?(workflows_dir)
+
+      windows = Dir.glob(File.join(workflows_dir, "*.{yml,yaml}")).any? do |path|
+        File.read(path).match?(WINDOWS_RUNNER_LABEL_PATTERN)
+      end
+      windows ? DEFAULT_PLATFORMS + ["windows"] : DEFAULT_PLATFORMS.dup
+    end
+
     def spdx_from_basename(basename)
       return "LicenseRef-Big-Time-Public-License" if basename.to_s == "Big-Time-Public-License"
 
@@ -5985,6 +5625,7 @@ module Kettle
     def readme_template_tokens(facts)
       {
         "KJ|CB:USER" => "",
+        "KJ|DEFAULT_TEST_MINIMUM_RUBY" => DEFAULT_TEST_MINIMUM_RUBY.to_s,
         "KJ|FUNDING:BUYMEACOFFEE" => "",
         "KJ|FUNDING:KOFI" => "",
         "KJ|FUNDING:LIBERAPAY" => "",
@@ -6960,7 +6601,7 @@ module Kettle
     def gemfile_policy_operations(template_content, original, final, request)
       package_name = runtime_context_value(request, :package, :name).to_s
       deleted = gemfile_dependency_names("#{template_content}\n#{original}") - gemfile_dependency_names(final)
-      expected = GEMFILE_POLICY_SELF_DEPENDENCIES.dup
+      expected = PROHIBITED_GEMFILE_DEPENDENCIES.dup
       expected << package_name unless package_name.empty?
       [
         {
@@ -7213,7 +6854,11 @@ module Kettle
           destination_content: original
         )
         return with_readme_timing("readme.append_used_link_definitions") do
-          appended = append_used_markdown_link_definitions(processed, resolved)
+          appended = append_used_markdown_link_definitions(
+            processed,
+            resolved,
+            fallback_definition_source: original
+          )
           postprocess_readme_content(
             appended,
             facts,
@@ -7225,7 +6870,7 @@ module Kettle
       if strategy.empty? || strategy == "merge"
         merged = merge_config_template_source(recipe, resolved, original, facts: facts, env: env)
         merged = preserve_mise_project_settings(recipe, merged, original, project_root: project_root, facts: facts) if template_file_type(recipe) == :toml
-        return finalize_template_source_content(recipe, sync_kettle_config_env_overrides(merged, env)) if recipe.fetch(:target_path) == KETTLE_CONFIG_PATH
+        return finalize_template_source_content(recipe, sync_kettle_config_env_overrides(merged, env, project_root: project_root)) if recipe.fetch(:target_path) == KETTLE_CONFIG_PATH
 
         merged = postprocess_funding_markdown_content(merged, facts) if recipe.fetch(:target_path) == "FUNDING.md"
 
@@ -7240,7 +6885,7 @@ module Kettle
       if strategy == "accept_template"
         accepted = finalize_accepted_template_source(recipe, resolved, original, facts: facts, project_root: project_root)
         accepted = preserve_github_workflow_project_settings(recipe, accepted, original, project_root: project_root) if github_workflow_template_recipe?(recipe)
-        accepted = sync_kettle_config_env_overrides(accepted, env) if recipe.fetch(:target_path) == KETTLE_CONFIG_PATH
+        accepted = sync_kettle_config_env_overrides(accepted, env, project_root: project_root) if recipe.fetch(:target_path) == KETTLE_CONFIG_PATH
         accepted = postprocess_funding_markdown_content(accepted, facts) if recipe.fetch(:target_path) == "FUNDING.md"
         if github_workflow_template_recipe?(recipe)
           accepted = finalize_github_workflow_template(accepted, facts)
@@ -7297,7 +6942,12 @@ module Kettle
       when :gemfile
         finalize_gemfile_template_source(recipe, content, destination_content, facts: facts, template_content: content)
       when :appraisals
-        merge_appraisals_template_policy(content, facts: facts)
+        merged = merge_appraisals_template_policy(content, facts: facts)
+        if recipe.fetch(:target_path).to_s == "Appraisal.root.gemfile"
+          normalize_appraisal_root_templating_gate(merged, facts)
+        else
+          merged
+        end
       when :gemspec
         package_name = facts.dig(:package, :name).to_s if facts
         receiver = gemspec_block_param(content) || "spec"
@@ -7788,12 +7438,14 @@ module Kettle
       [content.to_s.rstrip, "", missing_sources.join.rstrip, ""].join("\n")
     end
 
-    def append_used_markdown_link_definitions(content, definition_source)
+    def append_used_markdown_link_definitions(content, definition_source, fallback_definition_source: nil)
       owners = ReadmePostProcessor.markdown_structural_owners(content, :link_definitions, :inline_references)
       existing = owners.fetch(:link_definitions).map { |owner| owner.label.to_s }.to_set
       referenced = owners.fetch(:inline_references).flat_map(&:labels).map(&:to_s).to_set
-      available = ReadmePostProcessor.markdown_link_definition_owners(definition_source).to_h do |owner|
-        [owner.label.to_s, owner]
+      available = [fallback_definition_source, definition_source].compact.each_with_object({}) do |source, definitions|
+        ReadmePostProcessor.markdown_link_definition_owners(source).each do |owner|
+          definitions[owner.label.to_s] = owner
+        end
       end
       missing = referenced.filter_map do |label|
         next if existing.include?(label)
@@ -8075,6 +7727,10 @@ module Kettle
           preserve_self_word_entries: local_gemfile_template_recipe?(recipe)
         )
       end
+      output = remove_gemfile_builtin_git_source_overrides(output)
+      if recipe.fetch(:target_path).to_s == "Appraisal.root.gemfile"
+        output = normalize_appraisal_root_templating_gate(output, facts)
+      end
       if recipe.fetch(:target_path).to_s == "Gemfile"
         # A merged Gemfile retains its project-specific source; an accepted
         # template owns the complete source declaration.
@@ -8243,27 +7899,147 @@ module Kettle
         block_ifs.drop(1).each do |block_if|
           records << {start_line: block_if.location.start_line, end_line: block_if.location.end_line}
         end
-      end
-    end
+      end
+    end
+
+    def guard_main_gemfile_runtime_workspace_overrides(content)
+      content = collapse_nested_templating_guards(content)
+      content = normalize_templating_guard_indentation(content)
+      records = runtime_workspace_override_records(content)
+      return content if records.empty?
+
+      output = content.to_s
+      records.sort_by { |record| -record.fetch(:start_line) }.each do |record|
+        source = output.lines[(record.fetch(:start_line) - 1)..(record.fetch(:end_line) - 1)].join
+        guarded = [
+          %(unless ENV.fetch("K_JEM_TEMPLATING", "false").casecmp("true").zero?),
+          indent_source(source, 2).rstrip,
+          "end",
+          ""
+        ].join("\n")
+        output = replace_source_range_lines(output, record.fetch(:start_line), record.fetch(:end_line), guarded)
+      end
+      output
+    end
+
+    def normalize_appraisal_root_templating_gate(content, facts)
+      has_structuredmerge_dependency = package_runtime_dependency_names(facts).any? do |name|
+        STRUCTUREDMERGE_GEMS.include?(name.to_s)
+      end
+      result = prism_parse_success(content)
+      return content unless result
+
+      nodes = []
+      result.value.breadth_first_search_all { |node| nodes << node }
+      template_eval = nodes.find do |node|
+        node.is_a?(::Prism::CallNode) &&
+          node.name == :eval_gemfile &&
+          ruby_string_argument(node) == "gemfiles/modular/templating.gemfile"
+      end
+      template_gate = nodes.find do |node|
+        node.is_a?(::Prism::IfNode) &&
+          node.location.slice.to_s.include?("K_JEM_TEMPLATING") &&
+          template_eval &&
+          template_eval.location.start_offset > node.location.start_offset &&
+          template_eval.location.end_offset < node.location.end_offset
+      end
+      generator_only = nodes.find do |node|
+        node.is_a?(::Prism::CallNode) && node.name == :generator_only && node.block
+      end
+      style_comment = "# The style toolchain includes dependencies that require Ruby 3.3 or newer."
+      style_gate_anchor = nodes.find do |node|
+        gemfile_conditional_node?(node) && node.location.slice.to_s.include?("Gem::Version")
+      end
+      style_comment_attached = if style_gate_anchor
+        content.lines[style_gate_anchor.location.start_line - 2].to_s.strip == style_comment
+      else
+        false
+      end
+
+      if has_structuredmerge_dependency
+        template_gate_is_nested = template_gate && generator_only &&
+          template_gate.location.start_offset > generator_only.block.location.start_offset &&
+          template_gate.location.end_offset < generator_only.block.location.end_offset
+        if template_gate_is_nested
+          return content if style_comment_attached
+
+          comment_line_index = content.lines.index { |line| line.strip == style_comment }
+          return content unless comment_line_index
+
+          content = replace_source_range_lines(content, comment_line_index + 1, comment_line_index + 1, "")
+          result = prism_parse_success(content)
+          nodes = []
+          result&.value&.breadth_first_search_all { |node| nodes << node }
+          anchor = nodes.find do |node|
+            gemfile_conditional_node?(node) && node.location.slice.to_s.include?("Gem::Version")
+          end
+          return content unless anchor
+
+          return insert_lines_before(content, anchor.location.start_line, "#{style_comment}\n")
+        end
+
+        if template_gate
+          content = replace_source_range_lines(
+            content,
+            template_gate.location.start_line,
+            expand_line_range_through_following_blanks(content, ruby_node_source_end_line(template_gate)),
+            ""
+          )
+        elsif template_eval
+          content = replace_source_range_lines(
+            content,
+            template_eval.location.start_line,
+            ruby_node_source_end_line(template_eval),
+            ""
+          )
+        end
+
+        result = prism_parse_success(content)
+        return content unless result
+
+        nodes = []
+        result.value.breadth_first_search_all { |node| nodes << node }
+        gate = <<~RUBY
+          if respond_to?(:generator_only)
+            generator_only do
+              if ENV.fetch("K_JEM_TEMPLATING", "false").casecmp("true").zero?
+                eval_gemfile "gemfiles/modular/templating.gemfile"
+              end
+            end
+          end
+        RUBY
+        anchor = nodes.find do |node|
+          gemfile_conditional_node?(node) && node.location.slice.to_s.include?("Gem::Version")
+        end
+        return content unless anchor
 
-    def guard_main_gemfile_runtime_workspace_overrides(content)
-      content = collapse_nested_templating_guards(content)
-      content = normalize_templating_guard_indentation(content)
-      records = runtime_workspace_override_records(content)
-      return content if records.empty?
+        lines = content.lines
+        anchor_line_index = anchor.location.start_line - 1
+        preceding_line = lines[anchor_line_index - 1]
+        if preceding_line&.strip == style_comment
+          comment_start = lines.take(anchor_line_index - 1).sum(&:bytesize)
+          replace_source_offsets(content, [{
+            start_offset: comment_start,
+            end_offset: anchor.location.start_offset,
+            replacement: "#{gate}#{preceding_line}"
+          }])
+        else
+          replace_source_offsets(content, [{
+            start_offset: anchor.location.start_offset,
+            end_offset: anchor.location.start_offset,
+            replacement: gate
+          }])
+        end
+      else
+        return content unless template_gate
 
-      output = content.to_s
-      records.sort_by { |record| -record.fetch(:start_line) }.each do |record|
-        source = output.lines[(record.fetch(:start_line) - 1)..(record.fetch(:end_line) - 1)].join
-        guarded = [
-          %(unless ENV.fetch("K_JEM_TEMPLATING", "false").casecmp("true").zero?),
-          indent_source(source, 2).rstrip,
-          "end",
+        replace_source_range_lines(
+          content,
+          template_gate.location.start_line,
+          expand_line_range_through_following_blanks(content, ruby_node_source_end_line(template_gate)),
           ""
-        ].join("\n")
-        output = replace_source_range_lines(output, record.fetch(:start_line), record.fetch(:end_line), guarded)
+        )
       end
-      output
     end
 
     def ensure_main_gemfile_nomono_bootstrap(content, template_content)
@@ -8976,6 +8752,19 @@ module Kettle
     def normalize_local_gemfile_nomono_bootstrap(content)
       output = remove_obsolete_local_gemfile_nomono_activation(content)
       bootstrap = "#{local_gemfile_nomono_bootstrap(nil)}\n\n"
+      marker = local_gemfile_nomono_bootstrap_marker(output)
+      activation_assignments = prism_descendants(output).select do |node|
+        node.is_a?(::Prism::LocalVariableWriteNode) && node.name == :nomono_activation_requirements
+      end
+      if marker && activation_assignments.any?
+        first_line = activation_assignments.map { |node| node.location.start_line }.min
+        first_line = preceding_comment_block_start_line(output.lines, first_line)
+        output = replace_source_range_lines(output, first_line, marker.fetch(:start_line) - 1, bootstrap) if first_line < marker.fetch(:start_line)
+        output = remove_local_gemfile_nomono_loader_blocks_after_marker(output)
+        output = remove_redundant_nomono_bundler_requires_after_marker(output)
+        return ensure_trailing_newline(output.rstrip)
+      end
+
       require_records = ruby_call_records(output, :require).filter_map do |call|
         next unless ruby_string_argument(call) == "nomono/bundler"
 
@@ -8999,6 +8788,82 @@ module Kettle
       end
     end
 
+    def local_gemfile_nomono_bootstrap_marker(content)
+      result = prism_parse_success(content)
+      body = result&.value&.statements&.body || []
+      local_gems_assignment = body.find do |node|
+        node.is_a?(::Prism::LocalVariableWriteNode) && %i[local_gems structuredmerge_local_gems].include?(node.name)
+      end
+      [
+        local_gems_assignment_record(content),
+        local_gems_assignment && {start_line: local_gems_assignment.location.start_line},
+        word_array_assignment_record(content, :structuredmerge_local_gems)
+      ].compact.min_by { |record| record.fetch(:start_line) }
+    end
+
+    def remove_local_gemfile_nomono_loader_blocks_after_marker(content)
+      marker = local_gemfile_nomono_bootstrap_marker(content)
+      return content unless marker
+
+      result = prism_parse_success(content)
+      body = result&.value&.statements&.body || []
+      ranges = body.each_with_index.filter_map do |node, index|
+        next unless node.is_a?(::Prism::LocalVariableWriteNode) && %i[nomono_activation_requirements nomono_local_loader].include?(node.name)
+        next unless node.location.start_line > marker.fetch(:start_line)
+
+        loader = if node.name == :nomono_local_loader
+          node
+        else
+          loader_index = (index + 1...body.length).find do |candidate_index|
+            candidate = body[candidate_index]
+            candidate.is_a?(::Prism::LocalVariableWriteNode) && candidate.name == :nomono_local_loader
+          end
+          loader_index && body[loader_index]
+        end
+        next unless loader
+        next if node.name == :nomono_local_loader && body[0...index].any? do |candidate|
+          candidate.is_a?(::Prism::LocalVariableWriteNode) && candidate.name == :nomono_activation_requirements &&
+            candidate.location.start_line > marker.fetch(:start_line)
+        end
+
+        following = body[(body.index(loader) + 1)..].to_a.find do |candidate|
+          candidate.is_a?(::Prism::IfNode) && prism_descendants(candidate.slice).any? do |descendant|
+            descendant.is_a?(::Prism::CallNode) && descendant.name == :require
+          end
+        end
+        {
+          start_line: (node.name == :nomono_activation_requirements) ?
+            preceding_comment_block_start_line(content.to_s.lines, node.location.start_line) : node.location.start_line,
+          end_line: ruby_node_source_end_line(following || loader)
+        }
+      end
+      ranges.sort_by { |range| -range.fetch(:start_line) }.reduce(content.to_s) do |output, range|
+        replace_source_range_lines(output, range.fetch(:start_line), range.fetch(:end_line), "")
+      end
+    end
+
+    def remove_redundant_nomono_bundler_requires_after_marker(content)
+      marker = local_gemfile_nomono_bootstrap_marker(content)
+      return content unless marker
+
+      records = ruby_call_records(content, :require).filter_map do |call|
+        next unless ruby_string_argument(call) == "nomono/bundler"
+        next unless call.location.start_line > marker.fetch(:start_line)
+
+        {start_line: call.location.start_line, end_line: ruby_node_source_end_line(call)}
+      end
+      records.sort_by { |record| -record.fetch(:start_line) }.reduce(content.to_s) do |output, record|
+        replace_source_range_lines(output, record.fetch(:start_line), record.fetch(:end_line), "")
+      end
+    end
+
+    def prism_descendants(content)
+      result = prism_parse_success(content)
+      return [] unless result
+
+      result.value.breadth_first_search_all { true }
+    end
+
     def remove_obsolete_local_gemfile_nomono_activation(content)
       records = obsolete_local_gemfile_nomono_activation_records(content)
       return content if records.empty?
@@ -9414,7 +9279,7 @@ module Kettle
 
     def merge_gemfile_template_policy(content, facts:, template_content: nil, preserve_self_word_entries: false)
       package_name = facts.dig(:package, :name).to_s if facts
-      removable_gems = ["appraisal", *PROHIBITED_GEMFILE_DEPENDENCIES]
+      removable_gems = [*PROHIBITED_GEMFILE_DEPENDENCIES]
       removable_gems << package_name unless package_name.to_s.empty?
       removable_gems.concat(package_runtime_dependency_names(facts))
       removable_gems << "version_gem" unless version_gem_enabled?(facts)
@@ -9431,7 +9296,16 @@ module Kettle
 
     def package_runtime_dependency_names(facts)
       dependencies = facts.to_h.dig(:package, :runtime_dependencies)
-      Array(dependencies).map(&:to_s).reject(&:empty?).uniq
+      Array(dependencies).filter_map do |dependency|
+        name = if dependency.respond_to?(:name)
+          dependency.name
+        elsif dependency.is_a?(Hash)
+          dependency[:name] || dependency["name"]
+        else
+          dependency
+        end
+        name.to_s unless name.to_s.empty?
+      end.uniq
     end
 
     def inject_main_gemfile_recording_eval(content, facts)
@@ -9652,6 +9526,22 @@ module Kettle
       ensure_trailing_newline(lines.each_with_index.reject { |_line, index| remove_indexes.include?(index) }.map(&:first).join.gsub(/\n{3,}/, "\n\n"))
     end
 
+    # Bundler already provides these git sources; see BUNDLER_BUILTIN_GIT_SOURCES.
+    def remove_gemfile_builtin_git_source_overrides(content)
+      remove_indexes = Set.new
+      ruby_call_records(content, :git_source).each do |call|
+        argument = call.arguments&.arguments&.first
+        next unless argument.is_a?(::Prism::SymbolNode)
+        next unless BUNDLER_BUILTIN_GIT_SOURCES.include?(argument.unescaped.to_s)
+
+        (call.location.start_line..ruby_node_source_end_line(call)).each { |line_number| remove_indexes << (line_number - 1) }
+      end
+      return content if remove_indexes.empty?
+
+      lines = content.to_s.lines.each_with_index.reject { |_line, index| remove_indexes.include?(index) }.map(&:first)
+      ensure_trailing_newline(lines.join.sub(/\A\n+/, "").gsub(/\n{3,}/, "\n\n"))
+    end
+
     def gemfile_gem_call_records(content)
       ruby_call_records(content, :gem).filter_map do |call|
         name = ruby_string_argument(call)
@@ -9669,21 +9559,54 @@ module Kettle
     # A dependency owned directly by the project must not also be introduced by
     # a generated modular Gemfile. On first bootstrap, write a reviewable
     # resolution list; later runs require an explicit removal operation.
+    #
+    # Also surfaces case 3 of the dev-dependency conflict policy (engine
+    # incompatibility, e.g. sqlite3 on jruby): see #engine_dependency_conflicts.
+    # Both conflict sources share the same dependency_conflicts.resolve list,
+    # decision-matching, and review gate.
     def validate_modular_dependency_conflicts!(project_root, recipe_reports)
-      conflicts = modular_dependency_conflicts(project_root, recipe_reports)
+      validate_stale_modular_dependency_conflicts!(project_root)
+      config = kettle_jem_config(project_root)
+      conflicts = modular_dependency_conflicts(project_root, recipe_reports) +
+        engine_dependency_conflicts(project_root, recipe_reports, config)
       return if conflicts.empty?
 
-      config = kettle_jem_config(project_root)
       decisions = modular_dependency_conflict_decisions(config)
       unresolved = conflicts.reject { |conflict| modular_dependency_conflict_decided?(decisions, conflict) }
       if unresolved.empty?
         return
       end
 
+      # A conflict is "newly surfaced" only if no entry exists yet in
+      # dependency_conflicts.resolve for its exact gem/direct/modular triple
+      # (regardless of whether that entry's action/reason are filled in or
+      # valid). Newly surfaced conflicts get a placeholder entry written for
+      # review and do not block this run. A conflict that already has an
+      # entry but is still undecided (e.g. the placeholder was never
+      # completed, or reviewed was never flipped to true) has already had
+      # its chance to be reviewed, so it blocks the run instead of silently
+      # regenerating the same placeholder forever.
+      surfaced_entries = modular_dependency_conflict_entries(config)
+      newly_surfaced, previously_surfaced = unresolved.partition do |conflict|
+        !modular_dependency_conflict_previously_surfaced?(surfaced_entries, conflict)
+      end
+
+      # Among newly surfaced conflicts, gems with a canonical, pre-decided
+      # resolution (KNOWN_GEM_CONFLICT_RESOLUTIONS) don't need a human in
+      # the loop: write the real decided entry straight away instead of a
+      # placeholder "review" entry. Everything else still goes through the
+      # placeholder/review flow.
+      canonical_surfaced, review_needed_surfaced = newly_surfaced.partition do |conflict|
+        auto_resolvable_known_gem_conflict?(conflict)
+      end
+
       bootstrap_report = recipe_reports.find { |report| report.fetch(:relative_path, "").to_s == KETTLE_CONFIG_PATH }
-      if bootstrap_report && !modular_dependency_conflicts_reviewed?(config)
-        bootstrap_report[:final_content] = add_dependency_conflict_review_list(bootstrap_report.fetch(:final_content, ""), conflicts)
-        return
+      if bootstrap_report && newly_surfaced.any?
+        content = bootstrap_report.fetch(:final_content, "")
+        content = add_dependency_conflict_resolved_entries(content, canonical_surfaced) if canonical_surfaced.any?
+        content = add_dependency_conflict_review_list(content, review_needed_surfaced) if review_needed_surfaced.any?
+        bootstrap_report[:final_content] = content
+        return if previously_surfaced.empty?
       end
 
       details = unresolved.sort_by { |conflict| conflict.values_at(:name, :direct, :modular) }.map do |conflict|
@@ -9692,13 +9615,60 @@ module Kettle
       raise Error,
         "direct dependencies also declared by templated modular Gemfiles: #{details}. " \
           "Review dependency_conflicts.resolve in #{KETTLE_CONFIG_PATH}; each entry needs gem, direct, modular, action, and reason. " \
-        "Supported actions: remove_modular_gem, remove_x_std_lib_eval, keep_both. " \
+        "Supported actions: remove_modular_gem, remove_x_std_lib_eval, remove_direct_gem, keep_both. " \
         "keep_both is valid only when the direct and modular requirements overlap."
     end
 
+    # A remove_modular_gem / remove_x_std_lib_eval / remove_direct_gem entry
+    # that cites a gemspec as its direct side claims the gemspec declares the
+    # gem ("the gemspec owns the dependency"). When the gemspec has since
+    # stopped declaring it, the entry is stale: every templating run strips a
+    # modular declaration the template would otherwise maintain, and downstream
+    # bundles quietly lose the gem (observed: appraisal2-rubocop failing with
+    # "Unable to find gem rubocop-lts" because .rubocop.yml inherit_gem needed
+    # a gem the conflict entry had been deleting). These are warnings, not
+    # errors — some stale entries are intentional deactivations (e.g. a member
+    # deliberately disabling the yard-junk task) — but each one deserves a
+    # human look, because the recorded reason no longer describes reality.
+    def validate_stale_modular_dependency_conflicts!(project_root)
+      config = kettle_jem_config(project_root)
+      decisions = modular_dependency_conflict_decisions(config)
+      return if decisions.empty?
+
+      gemspec_paths = Dir.glob(File.join(project_root.to_s, "*.gemspec"))
+      gemspec_content = gemspec_paths.filter_map { |path| File.read(path) if File.readable?(path) }.join("\n")
+      return if gemspec_paths.empty?
+
+      stale = decisions.select do |decision|
+        next false unless decision.fetch("direct", "").end_with?(".gemspec")
+        next false unless %w[remove_modular_gem remove_x_std_lib_eval].include?(decision.fetch("action"))
+
+        gem_name = decision.fetch("gem")
+        !gemspec_dependency_records(gemspec_content).any? { |record| record.fetch(:name) == gem_name }
+      end
+      return if stale.empty?
+
+      details = stale.map do |decision|
+        "#{decision.fetch("gem")} (#{decision.fetch("direct")} vs #{decision.fetch("modular")})"
+      end.join(", ")
+      warn(
+        "kettle-jem: stale dependency_conflicts entries — the gemspec no longer declares: #{details}. " \
+          "If the removal is intentional, update the reason in #{KETTLE_CONFIG_PATH} to say so; " \
+          "otherwise remove the entry so the template maintains the modular declaration."
+      )
+    end
+
+    # Paths of a project's own directly-authored dependency manifests: the
+    # root Gemfile plus any gemspec, whether already on disk or only present
+    # as a pending recipe report (not yet written) for this templating run.
+    def direct_dependency_paths(project_root, recipe_reports)
+      report_paths = recipe_reports.map { |report| report.fetch(:relative_path, "").to_s }
+      ["Gemfile", *Dir.glob(File.join(project_root.to_s, "*.gemspec")).map { |path| File.basename(path) }, *report_paths.select { |path| path.end_with?(".gemspec") }]
+    end
+
     def modular_dependency_conflicts(project_root, recipe_reports)
       report_paths = recipe_reports.map { |report| report.fetch(:relative_path, "").to_s }
-      paths = ["Gemfile", *Dir.glob(File.join(project_root.to_s, "*.gemspec")).map { |path| File.basename(path) }, *report_paths.select { |path| path.end_with?(".gemspec") }]
+      paths = direct_dependency_paths(project_root, recipe_reports)
       direct = dependency_file_contents(project_root, recipe_reports, paths)
       modular_paths = [
         *Dir.glob(File.join(project_root.to_s, "gemfiles/modular/**/*.gemfile")).map do |path|
@@ -9716,6 +9686,12 @@ module Kettle
         relative = path.delete_prefix("gemfiles/modular/")
         !relative.include?("/") || relative.start_with?("x_std_libs/")
       end
+      # shunted.gemfile is derived from the gemspec's own dependencies
+      # (#shunted_gemfile_block): it's expected to redeclare a gem the
+      # gemspec already declares, so it isn't a real direct-vs-modular
+      # authoring conflict. Every other consumer of the packaged modular
+      # gemfile list excludes it the same way.
+      modular_paths = modular_paths.reject { |path| path == "gemfiles/modular/shunted.gemfile" }
       modular = dependency_file_contents(project_root, recipe_reports, modular_paths)
       direct.flat_map do |direct_path, content|
         direct_records = dependency_records_for(direct_path, content)
@@ -9736,6 +9712,41 @@ module Kettle
       end
     end
 
+    # Case 3 of the dev-dependency conflict policy: a direct dependency whose
+    # KNOWN_GEM_CONFLICT_RESOLUTIONS entry is :engine_incompatible and
+    # doesn't support one or more of the destination's declared engines
+    # (config["engines"], falling back to DEFAULT_ENGINES — see
+    # #enabled_ruby_engines). Unlike #modular_dependency_conflicts, this
+    # needs no modular-side declaration to match against: these are gems
+    # below the template's inclusion threshold with no template-managed
+    # modular home (sqlite3 is the pilot; see KNOWN_GEM_CONFLICT_RESOLUTIONS), so the
+    # incompatibility itself — not a direct-vs-modular duplicate — is the
+    # conflict. The :modular field is a fixed, human-readable placeholder
+    # (there is no modular file to name) rather than the specific
+    # unsupported-engine list, so a decision stays matched across runs even
+    # if the destination's declared engines change without actually
+    # resolving the incompatibility.
+    def engine_dependency_conflicts(project_root, recipe_reports, config)
+      declared_engines = enabled_ruby_engines(config)
+      paths = direct_dependency_paths(project_root, recipe_reports)
+      direct = dependency_file_contents(project_root, recipe_reports, paths)
+      direct.flat_map do |direct_path, content|
+        dependency_records_for(direct_path, content).filter_map do |record|
+          resolution = known_gem_conflict_resolution(record.fetch(:name))
+          next unless resolution && resolution.fetch(:category) == :engine_incompatible
+          next if (declared_engines - resolution.fetch(:supported_engines, [])).empty?
+
+          {
+            name: record.fetch(:name),
+            direct: direct_path,
+            modular: "(engine-incompatible; no modular home)",
+            direct_requirements: record.fetch(:requirements, []),
+            modular_requirements: []
+          }
+        end
+      end
+    end
+
     def dependency_records_for(path, content)
       if path == "Gemfile" || path.end_with?(".gemfile")
         gemfile_gem_call_records(content)
@@ -9771,13 +9782,34 @@ module Kettle
       config.dig("dependency_conflicts", "reviewed") == true
     end
 
+    # Every entry currently in dependency_conflicts.resolve, keyed loosely
+    # (unlike #modular_dependency_conflict_decisions, incomplete entries such
+    # as an unfinished "action: review" placeholder are included) so callers
+    # can tell "this conflict was already surfaced for review" apart from
+    # "this conflict has never been seen before".
+    def modular_dependency_conflict_entries(config)
+      Array(config.dig("dependency_conflicts", "resolve")).filter_map do |entry|
+        next unless entry.is_a?(Hash)
+
+        entry.each_with_object({}) { |(key, value), result| result[key.to_s] = value.to_s }
+      end
+    end
+
+    def modular_dependency_conflict_previously_surfaced?(entries, conflict)
+      entries.any? do |entry|
+        entry["gem"] == conflict.fetch(:name) &&
+          entry["direct"] == conflict.fetch(:direct) &&
+          entry["modular"] == conflict.fetch(:modular)
+      end
+    end
+
     def modular_dependency_conflict_decided?(decisions, conflict)
       decisions.any? do |decision|
         decision.fetch("gem") == conflict.fetch(:name) &&
           decision.fetch("direct") == conflict.fetch(:direct) &&
           decision.fetch("modular") == conflict.fetch(:modular) &&
           case decision.fetch("action")
-          when "remove_modular_gem", "remove_x_std_lib_eval"
+          when "remove_modular_gem", "remove_x_std_lib_eval", "remove_direct_gem"
             true
           when "keep_both"
             compatible_dependency_requirements?(conflict.fetch(:direct_requirements), conflict.fetch(:modular_requirements))
@@ -9807,38 +9839,118 @@ module Kettle
       false
     end
 
+    # A gem qualifies for automatic (no-human-review) resolution when it has
+    # a KNOWN_GEM_CONFLICT_RESOLUTIONS entry in
+    # AUTO_RESOLVABLE_KNOWN_GEM_CONFLICT_CATEGORIES and not explicitly
+    # flagged force_review — see #auto_resolvable_known_gem_conflict? below.
+    def known_gem_conflict_resolution(name)
+      KNOWN_GEM_CONFLICT_RESOLUTIONS[name.to_s]
+    end
+
+    AUTO_RESOLVABLE_KNOWN_GEM_CONFLICT_CATEGORIES = %i[template_managed engine_incompatible].freeze
+
+    def auto_resolvable_known_gem_conflict?(conflict)
+      resolution = known_gem_conflict_resolution(conflict.fetch(:name))
+      return false unless resolution
+
+      AUTO_RESOLVABLE_KNOWN_GEM_CONFLICT_CATEGORIES.include?(resolution.fetch(:category)) &&
+        !resolution.fetch(:force_review, false)
+    end
+
+    def dependency_conflict_entry_lines(conflict, action:, reason:)
+      [
+        "    - gem: #{conflict.fetch(:name)}\n",
+        "      direct: #{conflict.fetch(:direct)}\n",
+        "      modular: #{conflict.fetch(:modular)}\n",
+        "      action: #{action}\n",
+        "      reason: #{reason.to_s.empty? ? "\"\"" : reason.to_s.inspect}\n"
+      ]
+    end
+
+    # Writes a placeholder "action: review" entry for each newly surfaced
+    # conflict. When dependency_conflicts: already exists, this only adds
+    # entries for these specific conflicts and resets reviewed: to false
+    # (a new, unreviewed conflict invalidates a prior reviewed: true) —
+    # existing entries, including ones a human already wrote, are left
+    # exactly as they are.
     def add_dependency_conflict_review_list(content, conflicts)
+      return content if conflicts.empty?
+
+      new_entry_lines = conflicts.sort_by { |conflict| conflict.values_at(:name, :direct, :modular) }.flat_map do |conflict|
+        dependency_conflict_entry_lines(conflict, action: "review", reason: "")
+      end
+
+      insert_dependency_conflict_resolve_entries(content, new_entry_lines, reset_reviewed: true)
+    end
+
+    # Writes a fully decided entry (real action + reason, straight from
+    # KNOWN_GEM_CONFLICT_RESOLUTIONS) for each newly surfaced conflict whose
+    # gem is canonical. Unlike add_dependency_conflict_review_list, these
+    # need no human decision, so reviewed: is left exactly as it already is
+    # instead of being reset to false.
+    def add_dependency_conflict_resolved_entries(content, conflicts)
+      return content if conflicts.empty?
+
+      new_entry_lines = conflicts.sort_by { |conflict| conflict.values_at(:name, :direct, :modular) }.flat_map do |conflict|
+        resolution = known_gem_conflict_resolution(conflict.fetch(:name))
+        dependency_conflict_entry_lines(conflict, action: resolution.fetch(:action), reason: resolution.fetch(:reason))
+      end
+
+      insert_dependency_conflict_resolve_entries(content, new_entry_lines, reset_reviewed: false)
+    end
+
+    # Shared splicing logic behind both writers above: finds (or creates)
+    # the dependency_conflicts: block and appends new_entry_lines under
+    # resolve:, optionally resetting reviewed: to false along the way.
+    def insert_dependency_conflict_resolve_entries(content, new_entry_lines, reset_reviewed:)
       lines = content.to_s.lines
       index = lines.index { |line| line.match?(/\Adependency_conflicts:\s*\z/) }
       unless index
         lines << "\n" unless lines.empty? || lines.last.strip.empty?
-        lines.concat(["dependency_conflicts:\n", "  # Review each entry and choose a supported action.\n", "  resolve:\n"])
-        index = lines.length - 3
+        lines.concat([
+          "dependency_conflicts:\n",
+          "  # Review each entry and choose a supported action.\n",
+          "  # keep_both is for a broad direct requirement plus a compatible modular narrowing.\n",
+          "  reviewed: false\n",
+          "  resolve:\n",
+          *new_entry_lines
+        ])
+        return ensure_trailing_newline(lines.join)
       end
 
       block_end = (index + 1...lines.length).find { |line_index| lines[line_index].match?(/\A\S/) } || lines.length
-      replacement = [
-        "dependency_conflicts:\n",
-        "  # Review each entry and choose a supported action.\n",
-        "  # keep_both is for a broad direct requirement plus a compatible modular narrowing.\n",
-        "  reviewed: false\n",
-        "  resolve:\n"
-      ]
-      conflicts.sort_by { |conflict| conflict.values_at(:name, :direct, :modular) }.each do |conflict|
-        replacement.concat([
-          "    - gem: #{conflict.fetch(:name)}\n",
-          "      direct: #{conflict.fetch(:direct)}\n",
-          "      modular: #{conflict.fetch(:modular)}\n",
-          "      action: review\n",
-          "      reason: \"\"\n"
-        ])
+      block_lines = lines[index...block_end]
+
+      if reset_reviewed
+        reviewed_index = block_lines.index { |line| line.match?(/\A\s*reviewed:\s*\S/) }
+        if reviewed_index
+          block_lines[reviewed_index] = block_lines[reviewed_index].sub(/reviewed:\s*\S+/, "reviewed: false")
+        else
+          insert_at = 1
+          insert_at += 1 while block_lines[insert_at]&.match?(/\A\s*#/)
+          block_lines.insert(insert_at, "  reviewed: false\n")
+        end
+      end
+
+      resolve_index = block_lines.index { |line| line.match?(/\A\s*resolve:\s*(\[\s*\])?\s*\z/) }
+      if resolve_index
+        if block_lines[resolve_index].match?(/\[\s*\]\s*\z/)
+          indent = block_lines[resolve_index][/\A\s*/]
+          block_lines[resolve_index] = "#{indent}resolve:\n"
+        end
+        block_lines.insert(resolve_index + 1, *new_entry_lines)
+      else
+        block_lines << "  resolve:\n"
+        block_lines.concat(new_entry_lines)
       end
-      ensure_trailing_newline([*lines[0...index], *replacement, *lines[block_end..].to_a].join)
+
+      ensure_trailing_newline([*lines[0...index], *block_lines, *lines[block_end..].to_a].join)
     end
 
     def apply_modular_dependency_conflict_resolutions(project_root, decisions)
       decisions.each_with_object([]) do |decision, changed_files|
-        path = File.join(project_root.to_s, decision.fetch("modular"))
+        relative_path = (decision.fetch("action") == "remove_direct_gem") ? decision.fetch("direct") : decision.fetch("modular")
+        path = File.join(project_root.to_s, relative_path)
         next unless File.file?(path)
 
         before = File.read(path)
@@ -9847,13 +9959,33 @@ module Kettle
           remove_gemfile_dependency_blocks(before, [decision.fetch("gem")])
         when "remove_x_std_lib_eval"
           remove_x_std_lib_eval_for_gem(before, decision.fetch("gem"))
+        when "remove_direct_gem"
+          remove_dependency_conflict_direct_declaration(before, relative_path, decision.fetch("gem"))
         when "keep_both"
           before
         end
         next if after == before
 
         File.write(path, after)
-        changed_files << decision.fetch("modular")
+        changed_files << relative_path
+      end
+    end
+
+    # The "direct" side of a dependency_conflicts entry is either a Gemfile
+    # (or a modular .gemfile) or a .gemspec, mirroring the same dispatch
+    # #dependency_records_for uses to detect the conflict in the first
+    # place. The gemspec branch has to discover its own receiver (the
+    # Gem::Specification.new block's parameter name) since, unlike the
+    # gemspec-merge pipeline, there's no already-known template_receiver
+    # here — this runs standalone, against whatever's on disk.
+    def remove_dependency_conflict_direct_declaration(content, relative_path, gem_name)
+      if relative_path == "Gemfile" || relative_path.end_with?(".gemfile")
+        remove_gemfile_dependency_blocks(content, [gem_name])
+      else
+        receiver = gemspec_block_param(content)
+        return content unless receiver
+
+        remove_gemspec_dependency_lines(content, receiver: receiver, names: [gem_name])
       end
     end
 
@@ -9958,12 +10090,23 @@ module Kettle
       TEMPLATE_MANAGED_DEPENDENCIES.find { |dependency| dependency.fetch(:name) == name.to_s }
     end
 
-    def template_managed_dependency_requirements(name, version_module: Version)
-      return kettle_jem_dependency_requirements(version_module: version_module) if name.to_s == PACKAGE_NAME
+    def template_managed_dependency_requirements(name, env: ENV, version_module: Version)
+      return kettle_jem_template_dependency_requirements(env: env, version_module: version_module) if name.to_s == PACKAGE_NAME
 
       template_managed_dependency(name)&.fetch(:requirements)
     end
 
+    def kettle_jem_template_dependency_requirements(env: ENV, version_module: Version)
+      return kettle_jem_dependency_requirements(version_module: version_module) unless local_structuredmerge_path_mode?(env)
+
+      template_managed_dependency(PACKAGE_NAME).fetch(:requirements)
+    end
+
+    def local_structuredmerge_path_mode?(env)
+      value = (env || {}).fetch("STRUCTUREDMERGE_DEV", "false").to_s.strip
+      value != "" && !DecisionPolicy.falsey?(value)
+    end
+
     def template_managed_dependency_names(bootstrap: nil, ruby_version: RUBY_VERSION)
       TEMPLATE_MANAGED_DEPENDENCIES.filter_map do |dependency|
         next if !bootstrap.nil? && dependency.fetch(:bootstrap) != bootstrap
@@ -9984,12 +10127,12 @@ module Kettle
       Gem::Requirement.new(requirement).satisfied_by?(Gem::Version.new(ruby_version))
     end
 
-    def reconcile_template_managed_dependencies(source)
+    def reconcile_template_managed_dependencies(source, env: ENV)
       replacements = ruby_call_records(source, nil).filter_map do |call|
         next unless template_managed_dependency_call?(call)
 
         name = ruby_string_argument(call)
-        requirements = template_managed_dependency_requirements(name)
+        requirements = template_managed_dependency_requirements(name, env: env)
         next unless requirements
 
         requirement_nodes = Array(call.arguments&.arguments).drop(1).reject do |argument|
@@ -11128,14 +11271,59 @@ module Kettle
 
     def remove_gemspec_dependency_lines(content, receiver:, names:, runtime_only: false, development_only: false)
       wanted = names.map(&:to_s).to_set
-      records_by_line = gemspec_dependency_records(content, receiver: receiver)
-        .select { |record| wanted.include?(record.fetch(:name)) }
-        .select { |record| !runtime_only || record.fetch(:kind) != "add_development_dependency" }
-        .select { |record| !development_only || record.fetch(:kind) == "add_development_dependency" }
-        .to_h { |record| [record.fetch(:start_line), record.merge(replacement: "")] }
-      return content if records_by_line.empty?
+      return content if wanted.empty?
 
-      ensure_trailing_newline(replace_record_ranges(content, records_by_line).gsub(/\n{3,}/, "\n\n"))
+      allowed_kinds = gemspec_dependency_call_kinds(runtime_only: runtime_only, development_only: development_only)
+      targets = wanted.map do |name|
+        ast_crispr_gemspec_dependency_delete_target(receiver: receiver, name: name, allowed_kinds: allowed_kinds)
+      end
+
+      result = Ast::Crispr::DeleteBatch.call(content: content, targets: targets, source_label: "gemspec")
+      return content unless result.changed
+
+      ensure_trailing_newline(result.updated_content.gsub(/\n{3,}/, "\n\n"))
+    end
+
+    def gemspec_dependency_call_kinds(runtime_only: false, development_only: false)
+      kinds = %w[add_dependency add_runtime_dependency add_development_dependency]
+      kinds = kinds.reject { |kind| kind == "add_development_dependency" } if runtime_only
+      kinds = kinds.select { |kind| kind == "add_development_dependency" } if development_only
+      kinds.map(&:to_sym)
+    end
+
+    # Removes a single named gemspec dependency call, along with its owned
+    # leading comment (if any) — matching by call name and the same
+    # receiver, kind, and first-argument matching #gemspec_dependency_records
+    # uses, but locating the call anywhere in the tree via the :all_statements
+    # owner scope (not just the top level), and deleting it with
+    # Ast::Crispr::DeleteBatch instead of raw line-range replacement so its
+    # owned comments come with it rather than being left dangling.
+    def ast_crispr_gemspec_dependency_delete_target(receiver:, name:, allowed_kinds:)
+      Ast::Crispr::Ruby::Prism::Selectors.owner_filter(
+        id: "remove_gemspec_dependency_#{receiver}_#{name}",
+        owner_scope: :all_statements,
+        limit: {none_or_one: true}
+      ) do |context, owner|
+        next false unless owner.respond_to?(:receiver) && owner.respond_to?(:name)
+        next false unless owner.receiver&.slice == receiver.to_s
+        next false unless allowed_kinds.include?(owner.name)
+
+        argument = owner.arguments&.arguments&.first
+        next false unless ruby_static_string_value(argument) == name
+
+        leading = context.comment_regions_for(owner, region: :leading, owner_scope: :all_statements)
+        start_line = leading.any? ? leading.map { |comment| comment.location.start_line }.min : owner.location.start_line
+        Ast::Crispr::Match.new(
+          node: owner,
+          start_line: start_line,
+          end_line: owner.location.end_line,
+          metadata: {
+            start_boundary: (leading.any? ? :comment_region_start : :owner_start),
+            end_boundary: :owner_end,
+            payload_kind: :structural_owner_body
+          }
+        )
+      end
     end
 
     def remove_ruby_comment_lines_containing(content, text)
@@ -11667,8 +11855,8 @@ module Kettle
 
       case expression.receiver&.slice
       when "enumerate_package_files"
-        argument = Array(expression.arguments&.arguments).first
-        %w[lib exe certs sig].include?(ruby_static_string_value(argument))
+        arguments = Array(expression.arguments&.arguments)
+        arguments.length == 1 && !ruby_static_string_value(arguments.first).nil?
       when "enumerate_package_glob"
         generated_gemspec_package_glob_call?(expression)
       else
@@ -12495,11 +12683,13 @@ module Kettle
       content = resolve_template_tokens(content, tokens, scan_unresolved: false)
       bootstrap_licenses = Array(recipe[:bootstrap_licenses]).map(&:to_s).reject(&:empty?)
       content = replace_kettle_config_bootstrap_licenses(content, bootstrap_licenses) unless bootstrap_licenses.empty?
+      bootstrap_platforms = Array(recipe[:bootstrap_platforms]).map(&:to_s).reject(&:empty?)
+      content = replace_kettle_config_bootstrap_platforms(content, bootstrap_platforms) unless bootstrap_platforms.empty?
       content = replace_kettle_config_bootstrap_project_emoji(content, recipe[:bootstrap_project_emoji]) unless recipe[:bootstrap_project_emoji].to_s.empty?
       content = replace_kettle_config_bootstrap_rubyforum(content, recipe[:bootstrap_rubyforum]) if recipe[:bootstrap_rubyforum].is_a?(Hash)
       content = apply_kettle_config_bootstrap_profile(content, recipe[:bootstrap_template_profile], recipe[:bootstrap_gemspec_path])
       content = add_shim_bootstrap_config(content, recipe[:bootstrap_shim]) if recipe[:bootstrap_shim].is_a?(Hash)
-      assert_no_unresolved_template_tokens_in_yaml_values(sync_kettle_config_env_overrides(content, env), KETTLE_CONFIG_PATH)
+      assert_no_unresolved_template_tokens_in_yaml_values(sync_kettle_config_env_overrides(content, env, project_root: project_root), KETTLE_CONFIG_PATH)
     end
 
     def replace_kettle_config_bootstrap_project_emoji(content, emoji)
@@ -12517,6 +12707,14 @@ module Kettle
       raise Error, "Could not replace licenses block in .kettle-jem.yml bootstrap template"
     end
 
+    def replace_kettle_config_bootstrap_platforms(content, platforms)
+      platform_block = ["platforms:", *platforms.map { |platform| "  - #{platform}" }].join("\n")
+      updated = replace_yaml_node_lines(content, "platforms", "#{platform_block}\n")
+      return updated unless updated == content
+
+      raise Error, "Could not replace platforms block in .kettle-jem.yml bootstrap template"
+    end
+
     def replace_kettle_config_bootstrap_rubyforum(content, rubyforum)
       updated = content
       family_tag = rubyforum[:family_tag].to_s
@@ -12556,7 +12754,7 @@ module Kettle
       nil
     end
 
-    def sync_kettle_config_env_overrides(content, env)
+    def sync_kettle_config_env_overrides(content, env, project_root: nil)
       synced = KETTLE_CONFIG_ENV_SYNC_PATHS.reduce(content.to_s) do |updated, (path, env_key)|
         value = env_sync_value(env, env_key)
         next updated unless present_template_token_value?(value)
@@ -12568,9 +12766,36 @@ module Kettle
       synced = sync_kettle_config_internal_values(synced)
       synced = migrate_readme_logo_config(synced)
       synced = prune_legacy_kettle_config_keys(synced)
+      synced = migrate_platforms_config(synced, project_root) if project_root
       sync_kettle_config_documentation_comments(synced)
     end
 
+    # Injects the `platforms:` key into a pre-existing config that predates it.
+    # The injected value is computed from repo evidence (existing Windows CI)
+    # rather than defaulted, so a destination that already runs Windows CI does
+    # not silently lose that coverage on its next re-template. Mirrors the
+    # licenses bootstrap: config wins when present, evidence only fills an
+    # absent key. The block lands adjacent to `engines:`, which it documents by
+    # analogy, and carries its own documentation because the packaged config
+    # documents every key with a preceding comment block.
+    def migrate_platforms_config(content, project_root)
+      config = YAML.safe_load(content.to_s, permitted_classes: [], aliases: true) || {}
+      return content if config.key?("platforms")
+
+      platforms = detected_os_platforms(project_root)
+      platforms = DEFAULT_PLATFORMS if platforms.empty?
+      block = [
+        *PLATFORMS_CONFIG_DOCUMENTATION,
+        "platforms:",
+        *platforms.map { |platform| "  - #{platform}" },
+        ""
+      ].join("\n")
+
+      insert_yaml_block_after_top_level_key(content, "engines", block)
+    rescue Psych::Exception
+      content
+    end
+
     def normalize_kettle_config_optional_scalars(content)
       config = YAML.safe_load(content.to_s, permitted_classes: [], aliases: true) || {}
       return content unless config.key?("min_divergence_threshold")
@@ -12950,6 +13175,26 @@ module Kettle
       content
     end
 
+    # Inserts a pre-indented block (comment lines plus a key with a block
+    # sequence) immediately after the given top-level key's value span, so an
+    # injected key lands adjacent to the analogous key it documents by
+    # analogy. Falls back to appending at end of file when the anchor key is
+    # absent. Only column-zero keys match: a nested key of the same name under
+    # `files:` must not become the anchor.
+    def insert_yaml_block_after_top_level_key(content, key, block)
+      lines = content.to_s.lines
+      yaml_mapping_nodes(content).each do |mapping|
+        mapping.children.each_slice(2) do |key_node, value_node|
+          next unless key_node.is_a?(Psych::Nodes::Scalar) && key_node.value.to_s == key.to_s
+          next unless key_node.start_column.zero?
+
+          end_line = value_node.end_line
+          return [*lines[0...end_line], block, *lines[end_line..].to_a].join
+        end
+      end
+      "#{content.to_s.sub(/\n*\z/, "\n")}\n#{block}"
+    end
+
     def apply_kettle_config_bootstrap_profile(content, profile, gemspec_path)
       return content if profile.to_s.empty?
       return replace_yaml_scalar_path(content, %w[templates profile], FULL_TEMPLATE_PROFILE) if profile.to_s == FULL_TEMPLATE_PROFILE
@@ -13601,6 +13846,13 @@ module Kettle
       engines.map { |engine| engine.to_s.strip.downcase }.reject(&:empty?).uniq
     end
 
+    def os_platforms_config(config)
+      platforms = config["platforms"]
+      return unless platforms.is_a?(Array)
+
+      platforms.map { |platform| platform.to_s.strip.downcase }.reject(&:empty?).uniq
+    end
+
     def funding_urls(project_root, package_name, funding_uri: nil, opencollective_disabled: false, open_collective_org: nil, enabled_platforms: nil)
       urls = [funding_uri]
       path = File.join(project_root, ".github", "FUNDING.yml")
@@ -14419,6 +14671,10 @@ module Kettle
           package.fetch(:name).to_s
         ),
         "KJ|CI:EXEC_CMD" => facts.dig(:ci, :exec_cmd).to_s,
+        "KJ|CI:OS_MATRIX_ENTRIES" => github_actions_current_os_matrix_entries(facts),
+        "KJ|CI:OS_TEST_STEPS" => github_actions_current_os_test_steps(facts),
+        "KJ|README:PLATFORM_SUPPORT_TABLE" => readme_platform_support_table(facts),
+        "KJ|RAKE:TOP_LEVEL_DOCS_TASK" => rake_top_level_docs_task_token(facts).rstrip,
         "KJ|GITHUB_ACTIONS:COVERAGE_UPLOAD_STEPS" => github_actions_coverage_steps(disabled_integrations: facts.dig(:integrations, :disabled))
       }.merge(
         rubocop_template_tokens(rubygems[:min_ruby], ruby_style: facts.fetch(:ruby_style, {}))
@@ -14459,27 +14715,27 @@ module Kettle
     def kettle_changelog_gemfile_dependency_token(package_name)
       return "" if package_name == "kettle-changelog"
 
-      <<~RUBY.chomp
-        # Release lockfile/build commands set this dependency-specific switch so
-        # the development tool cannot pull unpublished family gems into resolution.
-        kettle_changelog_skip = ENV.fetch("KETTLE_DEV_SKIP_CHANGELOG_DEPENDENCY", "false").downcase
-        kettle_changelog_skip = %w[true 1 yes on].include?(kettle_changelog_skip)
-        kettle_changelog_local = ENV.fetch("KETTLE_DEV_DEV", "false").downcase
-        kettle_changelog_local = !%w[false 0 no off].include?(kettle_changelog_local)
-        unless kettle_changelog_skip
-          if kettle_changelog_local
-            require "nomono/bundler"
-            eval_nomono_gems(
-              gems: ["kettle-changelog"],
-              prefix: "KETTLE_DEV",
-              path_env: "KETTLE_DEV_DEV",
-              root: ["src", "my", "kettle-dev"]
-            )
-          elsif Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("4.0.0")
-            gem "kettle-changelog", #{template_managed_dependency("kettle-changelog").fetch(:requirements).map(&:inspect).join(", ")}
-          end
-        end
-      RUBY
+      [
+        "# Release lockfile/build commands set this dependency-specific switch so",
+        "# the development tool cannot pull unpublished family gems into resolution.",
+        "kettle_changelog_skip = ENV.fetch(\"KETTLE_DEV_SKIP_CHANGELOG_DEPENDENCY\", \"false\").downcase",
+        "kettle_changelog_skip = %w[true 1 yes on].include?(kettle_changelog_skip)",
+        "kettle_changelog_local = ENV.fetch(\"KETTLE_DEV_DEV\", \"false\").downcase",
+        "kettle_changelog_local = !%w[false 0 no off].include?(kettle_changelog_local)",
+        "unless kettle_changelog_skip",
+        "  if kettle_changelog_local",
+        indent_source(nomono_bundler_bootstrap("../../Gemfile.lock"), 4),
+        "    eval_nomono_gems(",
+        "      gems: [\"kettle-changelog\"],",
+        "      prefix: \"KETTLE_DEV\",",
+        "      path_env: \"KETTLE_DEV_DEV\",",
+        "      root: [\"src\", \"my\", \"kettle-dev\"]",
+        "    )",
+        "  elsif Gem::Version.new(RUBY_VERSION) >= Gem::Version.new(\"4.0.0\")",
+        %(    gem "kettle-changelog", #{template_managed_dependency("kettle-changelog").fetch(:requirements).map(&:inspect).join(", ")}),
+        "  end",
+        "end"
+      ].join("\n")
     end
 
     def readme_title_token(package, rubygems)
@@ -14492,6 +14748,68 @@ module Kettle
       "#{package_name} / #{namespace}"
     end
 
+    # The README platform tier table, generated from the same facts that drive
+    # the workflows, so it cannot drift from CI again (spec slice 1038). Rows
+    # mirror the generated workflow set: versioned MRI workflows are Linux-only,
+    # the current.yml OS matrix covers the declared platforms for MRI current,
+    # and every engine lane outside current.yml is Linux-only. Engine capability
+    # notes come from Kettle::Rb::PlatformSupport and carry their citation.
+    def readme_platform_support_table(facts)
+      engines = facts.dig(:rubygems, :engines)
+      engines = DEFAULT_ENGINES if engines.nil? || engines.empty?
+      platforms = facts.dig(:ci, :platforms)
+      platforms = DEFAULT_PLATFORMS if platforms.nil? || platforms.empty?
+      ruby_versions = facts.dig(:ci, :ruby_versions).to_a.map(&:to_s).reject(&:empty?)
+
+      parallel = "Parallel support"
+      unsupported = "Unsupported"
+      rows = []
+
+      unless ruby_versions.empty?
+        rows << [
+          "MRI #{ruby_versions.first}-#{ruby_versions.last}",
+          parallel, unsupported, unsupported,
+          "Versioned Ruby workflows run on Linux."
+        ]
+      end
+      rows << [
+        "MRI current",
+        parallel,
+        platforms.include?("macos") ? parallel : unsupported,
+        platforms.include?("windows") ? parallel : unsupported,
+        "Current Ruby workflow covers the declared OS platforms."
+      ]
+      rows << [
+        "MRI head",
+        parallel, unsupported, unsupported,
+        "CI is allowed to fail while Ruby is in development."
+      ]
+
+      (engines - ["ruby"]).each do |engine|
+        label = (engine == "jruby") ? "JRuby" : "TruffleRuby"
+        windows_entry = Kettle::Rb::PlatformSupport.engine_os_entry(engine, "windows")
+        note = if windows_entry && windows_entry.support == "unsupported"
+          "#{windows_entry.note} ([source](#{windows_entry.citation}))"
+        else
+          "Engine workflows run on Linux; macOS and Windows are not exercised by CI."
+        end
+        rows << ["#{label} (all CI lanes)", parallel, unsupported, unsupported, note]
+      end
+
+      [
+        "Support tiers describe what this project's CI actually exercises, not what may",
+        "work in an untested environment:",
+        "",
+        "- **Parallel support**: CI runs the test suite with multiple workers available.",
+        "- **Unsupported**: the engine/platform combination is not covered by CI and is",
+        "  not a project compatibility claim.",
+        "",
+        "| Ruby engine/version | Linux | macOS | Windows | Notes |",
+        "|---------------------|-------|-------|---------|-------|",
+        *rows.map { |row| "| #{row.join(" | ")} |" }
+      ].join("\n")
+    end
+
     def readme_dev_test_stack_table(package_name)
       rows = README_DEV_TEST_STACK_GEMS.reject { |gem| gem.fetch(:name) == package_name.to_s }.map do |gem|
         name = gem.fetch(:name)
@@ -14761,7 +15079,7 @@ module Kettle
         "[sm-family-fixtures]: https://github.com/structuredmerge/structuredmerge-fixtures",
         "[sm-family-go]: https://github.com/structuredmerge/structuredmerge-go",
         "[sm-family-ruby]: https://github.com/structuredmerge/structuredmerge-ruby",
-        "[sm-family-rust]: https://github.com/structuredmerge/structuredmerge-rust",
+        "[sm-family-rust]: https://github.com/structuredmerge/structuredmerge",
         "[sm-family-typescript]: https://github.com/structuredmerge/structuredmerge-typescript"
       ].join("\n")
     end
@@ -15170,7 +15488,7 @@ module Kettle
       compact_hash(
         freeze_token: config.dig("defaults", "freeze_token").to_s.empty? ? "kettle-jem" : config.dig("defaults", "freeze_token").to_s,
         kettle_jem_version: VERSION,
-        kettle_jem_dependency_arguments: kettle_jem_dependency_requirements.map(&:inspect).join(", "),
+        kettle_jem_dependency_arguments: kettle_jem_template_dependency_requirements(env: env).map(&:inspect).join(", "),
         template_run_date: run_timestamp.strftime("%Y-%m-%d"),
         template_run_year: run_timestamp.year.to_s,
         kettle_dev_local_gems: kettle_dev_local_gems(config),
@@ -15314,7 +15632,7 @@ module Kettle
       dev_env = "#{prefix}_DEV"
       root_literal = ruby_array_literal(direct_sibling_nomono_root_parts(workspace_slug, repository))
       word_array = names.map { |name| "  #{name}" }.join("\n")
-      nomono_loader = %(require "nomono/bundler")
+      nomono_bootstrap = nomono_bundler_bootstrap("Gemfile.lock")
 
       blocks << <<~RUBY.rstrip
         # Direct sibling dependencies (env-switched via #{dev_env})
@@ -15331,7 +15649,7 @@ module Kettle
               ENV.fetch("K_JEM_TEMPLATING", "false").casecmp("true").zero?)
           direct_sibling_dev_was_set = ENV.key?("#{dev_env}")
           direct_sibling_dev_original = ENV.fetch("#{dev_env}", nil)
-          #{nomono_loader}
+          #{nomono_bootstrap}
           begin
             ENV["#{dev_env}"] = File.expand_path("..", __dir__) if direct_sibling_templating && !direct_sibling_local
 
@@ -15518,7 +15836,7 @@ module Kettle
     end
 
     def kettle_dev_local_gems(config)
-      gems = %w[kettle-dev kettle-family kettle-test kettle-soup-cover kettle-changelog]
+      gems = %w[kettle-dev kettle-family kettle-rb kettle-test kettle-soup-cover kettle-changelog]
       plugin_names = PluginLoader.normalize_plugin_names(plugin_names_from_config(config))
       gems.concat(plugin_names.select { |plugin_name| plugin_name.start_with?("kettle-") })
       gems.uniq.join(" ")
@@ -15527,7 +15845,7 @@ module Kettle
     def main_gemfile_kettle_family_gem(package_name)
       return "" if package_name.to_s == "kettle-family"
 
-      %(gem "kettle-family", "~> 1.3", ">= 1.3.1"\n)
+      %(gem "kettle-family", "~> 1.3", ">= 1.3.10"\n)
     end
 
     def main_gemfile_nomono_bootstrap(package_name)
@@ -15540,25 +15858,40 @@ module Kettle
     end
 
     def nomono_gemfile_declaration
-      %(gem "nomono", "~> 1.1", ">= 1.1.5", require: false # ruby >= 3.2.0)
+      %(gem "nomono", "~> 1.1", ">= 1.1.7", require: false # ruby >= 3.2.0)
     end
 
     def local_gemfile_nomono_bootstrap(_package_name)
+      nomono_bundler_bootstrap("../../Gemfile.lock")
+    end
+
+    def nomono_bundler_bootstrap(lockfile_path)
       <<~RUBY.rstrip
         # Bootstrapping nomono here cannot rely on a plain `gem "nomono", ...` line.
         # Bundler records that dependency during Gemfile evaluation, but it does not
         # activate that exact version before the immediate `require "nomono/bundler"`.
-        nomono_activation_requirements = ["~> 1.1", ">= 1.1.5"]
+        nomono_activation_requirements = ["~> 1.1", ">= 1.1.7"]
         nomono_requirement = Gem::Requirement.new(nomono_activation_requirements)
         nomono_already_activated = Gem.loaded_specs["nomono"]
-        nomono_lockfile = File.expand_path("../../Gemfile.lock", __dir__)
-        if !nomono_already_activated || !nomono_requirement.satisfied_by?(nomono_already_activated.version)
+        nomono_lockfile = File.expand_path(#{lockfile_path.inspect}, __dir__)
+        nomono_locked_spec = nil
+        if File.file?(nomono_lockfile)
           require "bundler"
-          if File.file?(nomono_lockfile)
-            nomono_locked_spec = Bundler::LockfileParser
-              .new(Bundler.read_file(nomono_lockfile))
-              .specs
-              .find { |spec| spec.name == "nomono" }
+          nomono_locked_spec = Bundler::LockfileParser
+            .new(Bundler.read_file(nomono_lockfile))
+            .specs
+            .find { |spec| spec.name == "nomono" }
+        end
+        nomono_local_loader = if nomono_locked_spec && nomono_locked_spec.source.is_a?(Bundler::Source::Path)
+          File.expand_path(
+            File.join(nomono_locked_spec.source.path, "lib", "nomono", "bundler"),
+            File.dirname(nomono_lockfile)
+          )
+        end
+        if nomono_local_loader && File.file?("\#{nomono_local_loader}.rb")
+          require nomono_local_loader
+        else
+          if !nomono_already_activated || !nomono_requirement.satisfied_by?(nomono_already_activated.version)
             nomono_locked_installed = nomono_locked_spec &&
               Gem::Specification.find_all_by_name("nomono").any? { |spec| spec.version == nomono_locked_spec.version }
             nomono_locked = nomono_locked_spec &&
@@ -15566,9 +15899,9 @@ module Kettle
               nomono_requirement.satisfied_by?(nomono_locked_spec.version)
             nomono_activation_requirements = ["= \#{nomono_locked_spec.version}"] if nomono_locked
           end
+          Kernel.send(:gem, "nomono", *nomono_activation_requirements)
+          require "nomono/bundler"
         end
-        Kernel.send(:gem, "nomono", *nomono_activation_requirements)
-        require "nomono/bundler"
       RUBY
     end
 
@@ -15791,7 +16124,10 @@ module Kettle
         next false if argument.to_s.empty?
 
         if call.name == :require_relative
-          File.expand_path(File.join(project_root, File.dirname(entrypoint_path), "#{argument}.rb")) == version_absolute_path
+          Kettle::Dev::Paths.same?(
+            File.join(project_root, File.dirname(entrypoint_path), "#{argument}.rb"),
+            version_absolute_path
+          )
         else
           argument == version_require_path
         end
@@ -17440,6 +17776,38 @@ module Kettle
       }
     end
 
+    # Top-level `docs` task, emitted only for the profiles that need it.
+    #
+    # The gate is inverted from the obvious reading. At a monorepo root the
+    # `family` namespace loads (the root has a `gems/` directory) and
+    # `family:docs` exists, and there is no `docs/` directory, so `rake docs`
+    # fails loudly with "Don't know how to build task 'docs'". That is an honest
+    # error which points the reader at `family:docs`; adding a delegating task
+    # there would only create a second path to behavior the family task already
+    # owns.
+    #
+    # Everywhere else the failure is silent, and that is what this fixes. A
+    # generated `docs/` directory makes Rake resolve the bare name `docs` as an
+    # implicit file task whose target already exists, so `rake docs` exits 0
+    # having regenerated nothing. Verified per profile: standalone and
+    # monorepo-subgem both have `docs/` and no top-level `docs` task;
+    # monorepo-root has neither.
+    #
+    # Document generation is owned by `yard`, which kettle-dev installs and
+    # registers as a `default` prerequisite, so this delegates rather than
+    # reimplementing it.
+    def rake_top_level_docs_task_token(facts)
+      return "" if monorepo_root_template_profile?(facts)
+
+      <<~RAKE
+        # Without this, a generated docs/ directory makes Rake resolve the bare
+        # name `docs` as an up-to-date file task, so `rake docs` exits 0 having
+        # regenerated nothing.
+        desc "Generate YARD documentation"
+        task docs: "yard"
+      RAKE
+    end
+
     def gemspec_template_facts(config)
       includes = Array(config.dig("gemspec", "package_files", "include"))
         .map { |path| path.to_s.strip }
@@ -18637,6 +19005,7 @@ module Kettle
         "KJ|RUBYFORUM:PROJECT_TAG" => bootstrap.dig(:rubyforum, :project_tag).to_s
       }
       recipe[:bootstrap_licenses] = Array(bootstrap[:licenses]).map(&:to_s).reject(&:empty?)
+      recipe[:bootstrap_platforms] = Array(bootstrap[:platforms]).map(&:to_s).reject(&:empty?)
       recipe[:bootstrap_template_profile] = bootstrap[:template_profile].to_s unless bootstrap[:template_profile].to_s.empty?
       recipe[:bootstrap_gemspec_path] = bootstrap[:gemspec_path].to_s unless bootstrap[:gemspec_path].to_s.empty?
       recipe[:bootstrap_project_emoji] = bootstrap[:project_emoji].to_s unless bootstrap[:project_emoji].to_s.empty?
@@ -18956,6 +19325,27 @@ module Kettle
       (engines.nil? || engines.empty?) ? DEFAULT_ENGINES : engines
     end
 
+    # CI OS families the destination supports, from the `platforms:` config key,
+    # falling back to DEFAULT_PLATFORMS when the key is absent or empty. Named
+    # to stay clear of the funding-platforms vocabulary (#funding_platform_enabled?).
+    def enabled_os_platforms(config)
+      platforms = os_platforms_config(config)
+      (platforms.nil? || platforms.empty?) ? DEFAULT_PLATFORMS : platforms
+    end
+
+    # Configured → detected → default. Facts are computed BEFORE the config
+    # migration runs in the same templating pass, so a missing `platforms:` key
+    # must fold repo evidence in here: generating from the default alone would
+    # silently drop existing Windows CI coverage on the first run, even though
+    # the migration writes the correct key in that same run. Mirrors
+    # configured_or_detected_licenses.
+    def ci_os_platforms_facts(kettle_config, project_root)
+      platforms = os_platforms_config(kettle_config)
+      platforms = detected_os_platforms(project_root) if platforms.nil? || platforms.empty?
+      platforms = DEFAULT_PLATFORMS if platforms.nil? || platforms.empty?
+      platforms
+    end
+
     def config_min_ruby(config)
       value = config.dig("rubygems", "min_ruby") || config["min_ruby"]
       version = value.to_s[/\d+\.\d+(?:\.\d+)?/]
@@ -19053,6 +19443,7 @@ module Kettle
         }
         gemfile_entry[:default] = true if entry[:default]
         gemfile_entry[:replaces] = entry[:replaces] unless entry.fetch(:replaces, []).empty?
+        gemfile_entry.merge!(framework_matrix_security(framework_gem, entry))
         gemfile_entry
       end.uniq { |entry| entry.fetch(:path) }
       default_gemfiles = gemfiles.select { |entry| entry[:default] }
@@ -19238,6 +19629,32 @@ module Kettle
       "~> #{normalized}"
     end
 
+    # Security data from kettle-rb (Kettle::Rb::GemFloors) for a framework
+    # matrix version of a tracked gem. The series' security floor is added
+    # when the version's requirement still admits the series' first release,
+    # and advisories that no release in the series fixes are recorded so the
+    # generated gemfile can warn about them.
+    def framework_matrix_security(gem_name, entry)
+      return {} unless Kettle::Rb::GemFloors.tracked?(gem_name)
+
+      series = Kettle::Rb::GemFloors.series_for(entry.fetch(:label))
+      return {} unless series
+
+      security = {}
+      first_release = Gem::Version.new("#{series}.0")
+      floor = Kettle::Rb::GemFloors.floor(gem_name, series)
+      requirement = Gem::Requirement.new(*entry.fetch(:requirement).split(/\s*,\s*/))
+      if floor && Gem::Version.new(floor) > first_release && requirement.satisfied_by?(first_release)
+        security[:security_floor] = floor
+      end
+      unpatched = Kettle::Rb::GemFloors.unpatched_advisories(gem_name, series)
+      security[:unpatched_advisories] = unpatched unless unpatched.empty?
+      security[:security_series] = series unless security.empty?
+      security
+    rescue ArgumentError
+      {}
+    end
+
     def github_actions_coverage_config(config, env = ENV)
       workflows = config["workflows"]
       return {} unless workflows.is_a?(Hash)
@@ -19263,6 +19680,19 @@ module Kettle
       )
     end
 
+    # The binstub the generated Windows-only test step invokes. The step
+    # bypasses Appraisal and runs under gemfiles/current.gemfile, but the
+    # command itself is the destination's own configured test command
+    # (ci.exec_cmd) resolved to its binstub -- never a hardcoded binstub of
+    # any one repo. The packaged template once hardcoded bin/turbo_tests2,
+    # which was correct for exactly one destination and inconsistent even
+    # there, since that destination's own exec_cmd is kettle-test.
+    def github_actions_windows_exec_binstub(exec_cmd)
+      token = exec_cmd.to_s.strip.split(/\s+/).last.to_s
+      token = token.sub(%r{\Abin/}, "")
+      token.empty? ? "kettle-test" : token
+    end
+
     # A generated workflow normally uses one command for every matrix entry.
     # Legacy engines occasionally need a narrower command while retaining the
     # rest of the generated workflow (setup, retries, cache keys, and pins).
@@ -19709,7 +20139,7 @@ module Kettle
     def github_actions_setup_ruby_steps(indent:)
       yaml = <<~YAML
         - name: Setup Ruby & RubyGems
-          uses: appraisal-rb/setup-ruby-flash@925395edf973d2dc0a629919f407f3547a03d4b5 # v2.1
+          uses: appraisal-rb/setup-ruby-flash@6f8ad36ba7488db591541483afb5464d01e8861b # v2.14
           with:
             ruby-version: "${{ matrix.ruby }}"
             rubygems: "${{ matrix.rubygems }}"
@@ -19758,7 +20188,13 @@ module Kettle
         lines << %(ENV[#{key.inspect}] = #{value.inspect})
       end
       lines << ""
-      lines << %(gem #{gemfile.fetch(:gem).inspect}, #{gemfile.fetch(:requirement).inspect})
+      unpatched = gemfile.fetch(:unpatched_advisories, [])
+      unless unpatched.empty?
+        lines << "# kettle-rb: no #{gemfile.fetch(:gem)} #{gemfile.fetch(:security_series)} release fixes #{unpatched.join(", ")}"
+      end
+      requirements = [gemfile.fetch(:requirement)]
+      requirements << ">= #{gemfile.fetch(:security_floor)}" if gemfile[:security_floor]
+      lines << %(gem #{[gemfile.fetch(:gem), *requirements].map(&:inspect).join(", ")})
       "#{lines.join("\n")}\n"
     end
 
@@ -19821,7 +20257,7 @@ module Kettle
         "        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1",
         "",
         "      - name: Setup Ruby & RubyGems",
-        "        uses: appraisal-rb/setup-ruby-flash@925395edf973d2dc0a629919f407f3547a03d4b5 # v2.1",
+        "        uses: appraisal-rb/setup-ruby-flash@6f8ad36ba7488db591541483afb5464d01e8861b # v2.14",
         "        with:",
         "          ruby-version: \"${{ matrix.ruby }}\"",
         "          rubygems: \"${{ matrix.rubygems }}\"",
@@ -19873,6 +20309,61 @@ module Kettle
       update_github_actions_pins(updated)
     end
 
+    # The current.yml OS matrix entries, generated from the destination's
+    # declared CI OS families (facts[:ci][:platforms]). current.yml is
+    # strategy: accept_template, so it is replaced wholesale and the matrix
+    # must be generated from facts rather than pruned from a destination file
+    # (spec slice 1038). Runner labels come from Kettle::Rb::PlatformSupport,
+    # and an unknown family raises rather than silently dropping a lane, since
+    # a typo'd family would otherwise produce no CI for that platform at all.
+    def github_actions_current_os_matrix_entries(facts)
+      platforms = facts.dig(:ci, :platforms)
+      platforms = DEFAULT_PLATFORMS if platforms.nil? || platforms.empty?
+      exec_cmd = facts.dig(:ci, :exec_cmd).to_s
+
+      platforms.map do |platform|
+        label = Kettle::Rb::PlatformSupport.runner_label(platform)
+        raise Error, "Unknown CI OS family in platforms config: #{platform.inspect} (expected one of #{Kettle::Rb::PlatformSupport::OS_FAMILIES.join(", ")})" unless label
+
+        [
+          %(          - ruby: "ruby"),
+          %(            appraisal: "current"),
+          %(            os: #{label}),
+          %(            exec_cmd: "#{exec_cmd}"),
+          "            rubygems: latest",
+          "            bundler: latest"
+        ].join("\n")
+      end.join("\n")
+    end
+
+    # The current.yml test steps, generated from the same platforms facts. The
+    # Windows-only guard and step exist only when windows is declared, so no
+    # tautological `if:` survives in a linux+macos destination (spec slice
+    # 1038). The Windows step bypasses Appraisal and invokes the destination's
+    # own configured test command, resolved to its binstub from
+    # facts[:ci][:exec_cmd] -- never a hardcoded binstub of any one repo.
+    def github_actions_current_os_test_steps(facts)
+      platforms = facts.dig(:ci, :platforms)
+      platforms = DEFAULT_PLATFORMS if platforms.nil? || platforms.empty?
+      windows = platforms.include?("windows")
+      windows_label = Kettle::Rb::PlatformSupport.runner_label("windows")
+
+      lines = ["      - name: Tests for ${{ matrix.os }} ${{ matrix.ruby }} via ${{ matrix.exec_cmd }}"]
+      lines << %(        if: matrix.os != '#{windows_label}') if windows
+      lines << "        run: bundle exec appraisal ${{ matrix.appraisal }} ${{ matrix.exec_cmd }}"
+      return lines.join("\n") unless windows
+
+      binstub = github_actions_windows_exec_binstub(facts.dig(:ci, :exec_cmd))
+      (lines + [
+        "",
+        "      - name: Tests for #{windows_label} ${{ matrix.ruby }} via ruby bin/#{binstub}",
+        %(        if: matrix.os == '#{windows_label}'),
+        "        env:",
+        "          BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/current.gemfile",
+        "        run: ruby -rbundler/setup bin/#{binstub}"
+      ]).join("\n")
+    end
+
     def github_actions_push_branches_yaml(content, default_branch:, indent: "              ")
       github_actions_push_branches(content, default_branch: default_branch).map do |branch|
         "#{indent}- #{branch.inspect}"
@@ -19970,7 +20461,7 @@ module Kettle
         steps << <<~YAML
           - name: Upload coverage to QLTY
             if: ${{ !env.ACT }}
-            uses: qltysh/qlty-action/coverage@08a0a862c159eae9b9003081da6663d96efef637 # v2.3.0
+            uses: qltysh/qlty-action/coverage@c9b09987143d1e4ac955f4803c7bea742102feb5 # v2.4.0
             with:
               oidc: true
               files: coverage/lcov.info
@@ -19984,7 +20475,7 @@ module Kettle
         steps << <<~YAML
           - name: Upload coverage to CodeCov
             if: ${{ !env.ACT }}
-            uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+            uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
             with:
               use_oidc: true
               disable_search: true
@@ -20264,19 +20755,19 @@ module Kettle
       {
         "actions/checkout" => "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1",
         "actions/cache" => "actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0",
-        "appraisal-rb/setup-ruby-flash" => "appraisal-rb/setup-ruby-flash@925395edf973d2dc0a629919f407f3547a03d4b5 # v2.1",
-        "ruby/setup-ruby" => "ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1.321.0",
+        "appraisal-rb/setup-ruby-flash" => "appraisal-rb/setup-ruby-flash@6f8ad36ba7488db591541483afb5464d01e8861b # v2.14",
+        "ruby/setup-ruby" => "ruby/setup-ruby@651ff0d62c5c79bed6d53ec518387aae20e72c1a # v1.329.0",
         "coverallsapp/github-action" => "coverallsapp/github-action@8d6379e14d29928660c4ba802d8e85393440b329 # v2.3.8",
-        "qltysh/qlty-action/coverage" => "qltysh/qlty-action/coverage@08a0a862c159eae9b9003081da6663d96efef637 # v2.3.0",
-        "codecov/codecov-action" => "codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0",
+        "qltysh/qlty-action/coverage" => "qltysh/qlty-action/coverage@c9b09987143d1e4ac955f4803c7bea742102feb5 # v2.4.0",
+        "codecov/codecov-action" => "codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1",
         "irongut/CodeCoverageSummary" => "irongut/CodeCoverageSummary@51cc3a756ddcd398d447c044c02cb6aa83fdae95 # v1.3.0",
         "marocchino/sticky-pull-request-comment" => "marocchino/sticky-pull-request-comment@5770ad5eb8f42dd2c4f34da00c94c5381e49af88 # v3.0.5",
-        "actions/upload-artifact" => "actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1",
+        "actions/upload-artifact" => "actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2",
         "amancevice/setup-code-climate" => "amancevice/setup-code-climate@0daf2985a225e8ac15975b4d233010e94d65b76a # v2",
         "actions/dependency-review-action" => "actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0",
-        "github/codeql-action/init" => "github/codeql-action/init@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0",
-        "github/codeql-action/autobuild" => "github/codeql-action/autobuild@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0",
-        "github/codeql-action/analyze" => "github/codeql-action/analyze@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0",
+        "github/codeql-action/init" => "github/codeql-action/init@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3",
+        "github/codeql-action/autobuild" => "github/codeql-action/autobuild@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3",
+        "github/codeql-action/analyze" => "github/codeql-action/analyze@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3",
         "pozil/auto-assign-issue" => "pozil/auto-assign-issue@af6beea6bdf1e8eb373f061c5bc168681fc6d011 # v4.0.1",
         "apache/skywalking-eyes/dependency" => "apache/skywalking-eyes/dependency@a196742f472feaffafea537ce5a2a4c3c53a8de4 # v0.9.0",
         "sarisia/actions-status-discord" => "sarisia/actions-status-discord@eb045afee445dc055c18d3d90bd0f244fd062708 # v1.16.0"