kettle-jem 7.1.28 → 7.1.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d376a29518ac65e717447c082905690ce8c35165dab1f2daa4f7d9ed39c6fafc
-  data.tar.gz: 4e1fce2ccfdcbe1359a51884c70a226b3727e0f035cd338ea9f8d4f29e5c386b
+  metadata.gz: cb5935979a968dd6116dca64f7103743cd61a7c4a82eba917a5fc10d96e6215f
+  data.tar.gz: fc3e4e4c387c415121b90fb92428951b360ef7e21166810e722a493f411495f4
 SHA512:
-  metadata.gz: a8935378edb64106770005344bb70bed79d6cfed2549021ab2dc9211b7b247be51558e22d65b2b51383e0c5b381307280beac7b67ff18742cde977046fac1dbd
-  data.tar.gz: e3f8a7616be8133fa86f75621fd435aed010144f71ad587b222dd0cd2fe311c773db06b0df8ade57f43b909ae42fdb9eda96fb268110f9b5f23bc6ac7e4e1580
+  metadata.gz: 538d11740a16375ad1db36a60a59aca480f1a6eb5f92be4c9e63008332f23d3dbd73414e7d0f3ecc815a0ea966ebe7064e25340097321eba1a0f26ec3292608a
+  data.tar.gz: cfcc8775260d2dfd62d4a71ca8d7f005bb7815a4de1e6cd2f69c545d2159abe100c213f5570b0051bdb721d444c44214062a64bcbd364bee34bb466ffff01313

data/CHANGELOG.md

@@ -30,6 +30,186 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [7.1.29] - 2026-10-11
+
+- TAG: [v7.1.29][7.1.29t]
+- COVERAGE: 93.49% -- 11342/12132 lines in 17 files
+- BRANCH COVERAGE: 77.26% -- 4907/6351 branches in 17 files
+- 19.68% documented
+
+### Added
+
+- Engine-incompatible dev-dependency detection (case 3 of the dev-dependency
+  conflict policy, GEMSPEC_DEV_DEPENDENCY_PLAN.md Phase 4): a direct
+  development dependency with a `KNOWN_GEM_CONFLICT_RESOLUTIONS`
+  `:engine_incompatible` entry now surfaces a `dependency_conflicts.resolve`
+  review entry when it doesn't support one or more of the project's declared
+  `engines:` and has no template-managed modular home. Pilot registry entry:
+  `sqlite3` (no `jruby`-platform release ever published). Shares the same
+  `dependency_conflicts.resolve` list, decision-matching, and review gate as
+  the existing template-managed (case 1) conflicts, and the same
+  auto-resolution path for any future entry in this category with
+  `force_review: false`.
+- `workflows.framework_matrix` gemfiles for gems tracked by kettle-rb's
+  `Kettle::Rb::GemFloors` (activemodel, activerecord, activesupport, sqlite3)
+  require the minor series' security floor when the version's requirement
+  still admits the series' first release (e.g.
+  `gem "activerecord", "~> 7.1.0", ">= 7.1.6"`), and carry a `# kettle-rb:`
+  warning comment when no release in the series fixes an advisory.
+
+- kettle-jem-template-20260913-001 - Templating now also surfaces a review
+  entry in `dependency_conflicts.resolve` when a direct development
+  dependency doesn't support one or more of this project's declared
+  `engines:` and has no template-managed modular home (e.g. `sqlite3` on
+  `jruby`). Review each entry and pick a resolution per the project's own
+  engine support needs.
+
+- Templating plan phases now prefetch the tree-sitter-language-pack grammars used by template merges (bash, go, html, json, json5, markdown, rbs, ruby, rust, toml, tsx, typescript, yaml) through the language pack's hot-load API before recipes run, so on-demand grammar downloads happen up front with attributable diagnostics instead of failing inside a merge. Configure via KJ_TSLP_PREFETCH_LANGUAGES (space/comma list, or false to disable).
+
+- kettle-jem-deps-floor: add FLOOR_HOLDS registry to exclude a dependency floor from automatic raising when a newer release would produce an unresolvable dependency set in generated projects. Held floors are skipped during planning and reported separately (held_floors in JSON, a 'held' line in text output) so the exclusion is auditable rather than silent. First entry: rubocop-minitest (0.41.0 needs rubocop >= 1.89, but standard ~> 1.56 caps rubocop at ~> 1.88).
+
+- Add Kettle::Rb::PlatformSupport: generated OS-platform support evidence for CI matrix generation. Introduces the CI OS-family vocabulary (linux, macos, windows) as a fourth, explicitly distinct platform vocabulary, with runner-label mapping and per-engine support claims that each carry a citation. TruffleRuby Windows support (zero Windows assets across all releases) and the RubyInstaller series (including ARM64 from 3.4) are derived from live APIs on regeneration; every other claim is documentation-sourced. Regenerate with rake kettle:rb:platform_support:generate.
+
+- kettle-jem: first-class OS-platform support for the CI matrix (spec slice 1038). A new documented `platforms:` config key (CI OS families linux/macos/windows; default linux+macos, Windows opt-in only) drives generation of the current.yml OS matrix from facts via new KJ|CI:OS_MATRIX_ENTRIES and KJ|CI:OS_TEST_STEPS tokens, and a generated KJ|README:PLATFORM_SUPPORT_TABLE tier table under Runtime and Platform Support. Re-templating a repo with existing Windows CI detects and preserves windows via workflow evidence, both in the injected config key and in the facts themselves, so first-run templating cannot silently drop Windows coverage. Platform evidence lives in Kettle::Rb::PlatformSupport (kettle-rb 0.1.17+), with per-claim citations.
+
+### Changed
+
+- Require kettle-rb `>= 0.1.14` (security floor data).
+- The `sqlite3` `KNOWN_GEM_CONFLICT_RESOLUTIONS` reason now points at a
+  `platforms: [:ruby]` modular gemfile (kettle-jem-appraisals generates
+  `gemfiles/modular/activerecord_support/*.gemfile`) instead of saying sqlite3
+  has no modular home.
+
+- [kc] kettle-jem-deps-floor: Update kettle-jem template dependency floors:
+  - gitmoji-regex (>= 2.0.13 -> >= 2.0.15)
+  - kettle-changelog (>= 1.0.8 -> >= 1.0.9)
+  - kettle-dev (>= 3.1.5 -> >= 3.1.10)
+  - kettle-drift (>= 1.0.15 -> >= 1.0.16)
+  - kettle-family (>= 1.3.3 -> >= 1.3.10)
+  - kettle-soup-cover (>= 3.0.11 -> >= 3.0.12)
+  - kettle-test (>= 2.0.23 -> >= 2.0.24)
+  - nomono (>= 1.1.6 -> >= 1.1.7)
+  - reek (>= 6.5.0 -> >= 6.6.0)
+  - rubocop-lts-rspec (>= 1.0.6 -> >= 1.0.7)
+  - rubocop-minitest (>= 0.40.0 -> >= 0.41.0)
+  - standard (>= 1.56.0 -> >= 1.57.0)
+  - turbo_tests2 (>= 3.2.12 -> >= 3.2.14)
+  - yaml-converter (>= 0.2.6 -> >= 0.2.7)
+  - yard-fence (>= 0.9.9 -> >= 0.9.10)
+  - yard-timekeeper (>= 0.2.7 -> >= 0.2.9)
+
+- [kc] kettle-jem-workflow-pins: Update pinned GitHub Actions in kettle-jem templates:
+  - actions/upload-artifact v7.0.1 (043fb46d1a93c77aae656e7c1c64a875d1fc6a0a) -> v7.0.2 (cf430e030ddbb5b0abf93d22962f4752f3646cd9)
+  - appraisal-rb/setup-ruby-flash v2.7 (b7ed1caf57f7986cedd2acca8624960b0820bc9a) -> v2.14 (6f8ad36ba7488db591541483afb5464d01e8861b)
+  - github/codeql-action/analyze v4.38.2 (2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2) -> v4.38.3 (24c54180a607b1449ed407dd24f251e4e9147c8d)
+  - github/codeql-action/autobuild v4.38.2 (2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2) -> v4.38.3 (24c54180a607b1449ed407dd24f251e4e9147c8d)
+  - github/codeql-action/init v4.38.2 (2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2) -> v4.38.3 (24c54180a607b1449ed407dd24f251e4e9147c8d)
+  - ruby/setup-ruby v1.327.0 (14594264cd68ce8a2345dd349bc3d138a4ef85c8) -> v1.328.0 (e81a8fa391b11a595c1b7ed84177cc0fe02faf83)
+
+- [kc] kettle-jem/prepare: updated 14 project files:
+  - dependencies (14)
+
+- [kc] kettle-jem/template: updated 12 project files:
+  - code and tests (1)
+  - other (1)
+  - workflows (10)
+
+- The templating workflow template now restores tree-sitter-language-pack grammar downloads from actions/cache keyed by the templating lockfiles, keeping the self-test off the network in the common case; a cache miss falls back to the in-run tslp_prefetch phase.
+
+- [kc] license-eye-workflow-retry: The generated `.github/workflows/license-eye.yml` retries the license check once before failing. The pinned `apache/skywalking-eyes/dependency` action is a composite that builds license-eye from source on every run, and its own dependency cache is broken upstream: `dependency/action.yml` passes `cache-dependency-path: ${{ github.action_path }}/go.sum`, but `go.sum` lives at the action's repository root rather than in `dependency/` (404 versus 200). setup-go therefore logs "Restore cache failed: Some specified paths were not resolved", the module cache never restores, and each run re-downloads roughly 35 Go modules and re-runs `make`. Every templated repository is consequently exposed to a transient `proxy.golang.org` error on every push; one such run failed with `stream error: stream ID 133; INTERNAL_ERROR; received from peer` after eleven consecutive successes. The retry uses the same `[Attempt 1]`/`[Attempt 2]` idiom as the generated Ruby matrix workflows, and the action pin is unchanged.
+
+- Drop TruffleRuby 23.0 and TruffleRuby HEAD from generated CI. Both deadlocked in the parallel test worker pool during the turbo_tests2 v3.2.14 release: 23.0 was cancelled after hitting its own 30-minute cap with orphan ruby processes terminated, and HEAD ran to GitHub's 6-hour ceiling before being cancelled. 23.0 already carried the serial-worker mitigation (TURBO_TESTS2_MAX_PROCESSES=1), and its log shows '1 processes for 13 specs' followed by 29 minutes of silence, so forcing a single worker did not resolve the deadlock. Removes the truffleruby-23.0 workflow and json gemfile templates, the truffleruby job from the heads workflow template, and the matching README compatibility badges and reference definitions. TruffleRuby 23.1, 24.2, 25.0, 33.0 and current all pass and remain generated; the heads workflow keeps its ruby-head and jruby-head jobs, which both succeed.
+
+- [kc] kettle-jem-deps-floor: Update kettle-jem template dependency floors:
+  - kettle-dev (>= 3.1.10 -> >= 3.1.11)
+
+### Removed
+
+- The `commonmarker-merge` and `kramdown-merge` runtime dependencies, and their
+  entries in the local sibling and `templating_local.gemfile` path lists.
+  kettle-jem merges Markdown with markly (via `ast-crispr-markdown-markly` and
+  `markly-merge`); other Markdown backends are still used when a project installs
+  them, but are no longer forced on every bundle. This also stops `commonmarker`'s
+  native extension from being compiled, which fails on ruby-head.
+
+### Fixed
+
+- The packaged `Gemfile` no longer overrides `git_source(:github)` with an SSH
+  URL. The override was recorded in `Gemfile.lock` as `git@github.com` remotes,
+  which CI runners cannot clone; Bundler's built-in HTTPS source is used again.
+  Templating now also removes existing overrides of Bundler's built-in git
+  sources (`git_source(:github)`, `:gist`, `:bitbucket`) from destination
+  Gemfiles, including the managed monorepo root Gemfile.
+
+- Generated Ruby 4 extracted-stdlib Gemfiles now include `ostruct` so suites
+  that require it can run on Rubies where it is no longer bundled by default.
+- Regenerate `sig/*.rbs` signature stubs from the template instead of merging them, preventing a duplicate top-level declaration when the detected namespace kind (module vs. class) changes between runs.
+- Gemspec `spec.files` merging now preserves a destination-only `enumerate_package_files.call("...")` splat for any project-specific directory, matching how `enumerate_package_glob.call(...)` splats were already preserved regardless of the glob pattern, instead of raising an unsupported-assignment error.
+
+- Generated current-MRI workflows now use setup-ruby-flash v2.7, which validates rv-installed bundles before Appraisal and repairs incomplete native-extension installs through Bundler.
+
+- Local template runs retain the released kettle-jem floor in remote templating Gemfiles.
+
+- Run duplicate drift detection after all template orchestration mutations, and generate shared nomono resolver options only once in local Gemfiles.
+
+- Template the bin/turbo_tests2 launcher required by Windows current-workflow tests.
+
+- Refresh locked StructuredMerge sibling gems during local template preparation so Bundler cannot retain stale registry versions.
+
+- Local template runs now preserve the released kettle-jem floor in gemspecs as well as remote Gemfiles.
+
+- Local Gemfile bootstraps now load nomono's Bundler DSL from the path source recorded in Gemfile.lock, avoiding activation of an older installed release during local templating.
+
+- Root and Kettle Changelog Gemfile bootstraps now load Nomono's Bundler DSL from a path-locked checkout instead of activating an installed Nomono release.
+
+- Nomono bootstrap normalization is now idempotent and removes duplicate generated loader blocks after repeated template preparation.
+
+- Kettle Changelog local Gemfile bootstraps now preserve their conditional block indentation when loading Nomono from a path-locked checkout.
+
+- Kettle Changelog's modular bootstrap now reads the project-root Gemfile.lock, so path-locked Nomono is not mistaken for an installed release.
+
+- Prevent commit hooks from resolving repository-local Bundler binstubs when checking commit messages.
+
+- Keep local template dependencies out of generated Appraisal bundles.
+
+- Use Kettle Dev's shared path identity logic when reconciling template and project paths.
+
+- Update the generated appraisal style-toolchain gate to Ruby 3.3 so Ruby 3.2 builds do not resolve unsupported lint dependencies.
+
+- Normalize local nomono bootstrap blocks as a single AST-bounded region, including Gemfiles whose local_gems assignment uses an array literal; keep appraisal style-gate comments attached to their Ruby-version condition.
+
+- Preserve destination Markdown link definitions referenced by README sections retained during templating.
+
+- Include files created by template orchestration steps in change accounting and maintenance changelog entries.
+
+- Local style Gemfiles now include the configured rubocop-packaging plugin, matching the generated RuboCop configuration.
+
+- Generated Gemfiles now include extracted standard-library dependencies on Windows, and only include rubocop-on-rbs on Ruby 3.3 and newer.
+
+- Generated GitHub Actions workflows now pin setup-ruby-flash v2.13 so Windows native gems receive the MSYS2 dependency prefixes required by Psych and OpenSSL.
+
+- Generated GitHub Actions workflows now pin setup-ruby-flash v2.14, which passes Windows-native MSYS2 prefixes and installs the CA trust bundle for OpenSSL.
+
+- Avoid duplicate rubocop-packaging declarations when local style Gemfiles are evaluated.
+
+- The StructuredMerge family link in generated READMEs now points to the consolidated StructuredMerge repository.
+
+- Hold template style.gemfile rubocop-minitest floor at 0.40: version 0.41.0 requires rubocop >= 1.89.0 while standard (~> 1.56) caps rubocop at ~> 1.88.0, making the generated style bundle unsatisfiable and breaking family re-templating (kettle-family template --execute).
+
+- Include modular dependency conflict decisions in template checksums so corrected Gemfile policies are reapplied.
+
+- [kc] deps-floor-changelog-carry-forward: kettle-jem-deps-floor dropped changelog records for dependency floors raised earlier in the same Unreleased cycle that the current run did not touch, because its consolidated [kc] entry was rebuilt from only the current run's changes while the keyed upserter replaces the prior entry wholesale. Existing ranges are now parsed and carried forward, so each floor keeps its earliest baseline and its newest target.
+
+- [kc] workflow-pins-changelog-carry-forward: kettle-jem-workflow-pins dropped changelog records for GitHub Actions re-pinned earlier in the same Unreleased cycle that the current run did not touch, for the same reason as kettle-jem-deps-floor. Existing pin ranges are now parsed and carried forward, keeping each action's earliest baseline ref and newest target ref.
+
+- [kc] git-add-path-escaping-symlinked-home: kettle-jem-deps-floor and kettle-jem-workflow-pins could pass a parent-directory escaping path to git add -- when the project root and the git worktree root were two valid spellings of the same directory, as on hosts where /home is a symlink to /var/home and TMPDIR reports the symlink spelling while git rev-parse --show-toplevel reports the realpath spelling. Both tools now relativize through Kettle::Jem::RelativePaths, which canonicalizes both sides before comparing and refuses to return an escaping path.
+
+- Always load the StructuredMerge sibling closure when `STRUCTUREDMERGE_DEV` is set, not only when `K_JEM_TEMPLATING` is set. StructuredMerge is no longer a templating-only concern: `kettle-changelog` reaches it at runtime through `ast-crispr-markdown-markly` -> `markdown-merge` -> `tree_haver`, so the test, lint, and release bundles resolve the family too. While the family is only partially released, the registry copies pin the last published version with an exact requirement, which cannot be satisfied next to a local lockstep version, and version solving failed for every command in the member bundle rather than only for lint. The generated main `Gemfile` and shim `Gemfile` now evaluate `gemfiles/modular/templating.gemfile` when either flag is set; neither flag set still skips it, so CI and released-mode resolution are unchanged.
+
+- The templated `gemfiles/modular/style_local.gemfile` passed `root: ["src", "rubocop-lts"]` to `eval_nomono_gems`, which nomono resolves through `join_home` to `$HOME/src/rubocop-lts`. The rubocop-lts family actually lives at `$HOME/src/my/rubocop-lts`, so `RUBOCOP_LTS_DEV=true` silently selected a stale sibling checkout when one existed and a missing tree otherwise. Now `["src", "my", "rubocop-lts"]`, matching the other sibling templates and nomono's own default root. Already-templated projects keep the stale root until re-templated.
+
+- kettle-jem: the packaged current.yml Windows test step hardcoded `bin/turbo_tests2`, correct for exactly one destination (and inconsistent even there, since its exec_cmd is kettle-test). The generated step now invokes the destination's own configured test command, resolved to its binstub from ci.exec_cmd. Also: the kettle-dev family local-gems wiring now includes kettle-rb, so destinations can develop against unreleased kettle-rb with KETTLE_DEV_DEV.
+
 ## [7.1.28] - 2026-09-10
 
 - TAG: [v7.1.28][7.1.28t]
@@ -2049,7 +2229,9 @@ Please file a bug if you notice a violation of semantic versioning.
 - Released kettle-jem as part of the initial StructuredMerge Ruby 7.0.0 gem set.
 - Included packaged templates and parser-backed merge support for Ruby gem templating.
 
-[Unreleased]: https://github.com/structuredmerge/structuredmerge-ruby/compare/v7.1.28...HEAD
+[Unreleased]: https://github.com/structuredmerge/structuredmerge-ruby/compare/v7.1.29...HEAD
+[7.1.29]: https://github.com/structuredmerge/structuredmerge-ruby/compare/v7.1.28...v7.1.29
+[7.1.29t]: https://github.com/structuredmerge/structuredmerge-ruby/releases/tag/v7.1.29
 [7.1.28]: https://github.com/structuredmerge/structuredmerge-ruby/compare/v7.1.27...v7.1.28
 [7.1.28t]: https://github.com/structuredmerge/structuredmerge-ruby/releases/tag/v7.1.28
 [7.1.27]: https://github.com/structuredmerge/structuredmerge-ruby/compare/v7.1.26...v7.1.27

data/README.md

@@ -95,9 +95,25 @@ Merge analysis must enter parsing through `tree_haver`. Parser-specific gems reg
 [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
 
+### Runtime and Platform Support
+
+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 |
+|---------------------|-------|-------|---------|-------|
+| MRI 4.0-4.0 | Parallel support | Unsupported | Unsupported | Versioned Ruby workflows run on Linux. |
+| MRI current | Parallel support | Parallel support | Unsupported | Current Ruby workflow covers the declared OS platforms. |
+| MRI head | Parallel support | Unsupported | Unsupported | CI is allowed to fail while Ruby is in development. |
+| JRuby (all CI lanes) | Parallel support | Unsupported | Unsupported | Engine workflows run on Linux; macOS and Windows are not exercised by CI. |
+
 ### Federated DVCS
 
 <details markdown="1">
@@ -907,7 +923,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-12.030-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-12.132-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/structuredmerge/structuredmerge-ruby/blob/main/SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/kettle/jem/maintenance_changelog.rb

@@ -20,7 +20,7 @@ module Kettle
             path.start_with?("gemfiles/")
         },
         documentation: ->(path) { %w[README.md CONTRIBUTING.md SECURITY.md].include?(path) || path.start_with?("docs/") },
-        configuration: ->(path) { path.start_with?(".structuredmerge/") || path == "mise.toml" || path == ".gitignore" },
+        configuration: ->(path) { path.start_with?(".structuredmerge/") || %w[.gitattributes .gitignore mise.toml].include?(path) },
         code_and_tests: ->(path) { path.start_with?("lib/", "spec/", "test/", "bin/") || path == "Rakefile" }
       }.freeze
       TEMPLATE_CHANGELOG_KEYS = {

data/lib/kettle/jem/relative_paths.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Kettle
+  module Jem
+    # Relativizes a path under a root directory using filesystem identity rather
+    # than lexical string comparison.
+    #
+    # Pathname#relative_path_from is purely lexical, so when the path and the root
+    # are two valid spellings of the same directory it walks up past the root and
+    # returns a parent-directory escape instead of raising. On hosts where /home
+    # is a symlink to /var/home (Fedora Silverblue/Aurora), Dir.mktmpdir and
+    # TMPDIR report "/home/..." while `git rev-parse --show-toplevel` reports
+    # "/var/home/...". The escape then reaches `git add --`, which fails with
+    # "is outside repository at".
+    #
+    # Both sides are canonicalized before relativizing. File.realpath is safe
+    # here, unlike in Kettle::Paths where the result must preserve the caller's
+    # spelling because callers stat those paths and spawn processes from that
+    # working directory: these values feed only `git add`, and git itself reports
+    # the realpath spelling, so the canonical form is the one git expects.
+    module RelativePaths
+      class << self
+        # Returns the path of +path+ relative to +root+, or nil when root is not
+        # an ancestor. Never returns an escaping "../../.." path.
+        #
+        # Falls back to lexical comparison when either side does not exist yet,
+        # because generated and planned paths have no filesystem identity.
+        #
+        # @param path [String, Pathname, nil]
+        # @param root [String, Pathname, nil]
+        # @return [String, nil]
+        def relative_path_under(path, root)
+          return nil if blank?(path) || blank?(root)
+
+          absolute = File.expand_path(path.to_s)
+          boundary = File.expand_path(root.to_s)
+          relative = relativize(absolute, boundary)
+          relative.start_with?("..") ? nil : relative
+        rescue ArgumentError
+          nil
+        end
+
+        private
+
+        def relativize(absolute, boundary)
+          if File.exist?(absolute) && File.exist?(boundary)
+            Pathname(File.realpath(absolute)).relative_path_from(Pathname(File.realpath(boundary))).to_s
+          else
+            Pathname(absolute).relative_path_from(Pathname(boundary)).to_s
+          end
+        end
+
+        def blank?(value)
+          value.nil? || value.to_s.strip.empty?
+        end
+      end
+    end
+  end
+end

data/lib/kettle/jem/tasks/install_task.rb

@@ -28,6 +28,7 @@ module Kettle
         def run(project_root: Dir.pwd, env: ENV, run_options: {}, command_runner: method(:run_system_command))
           effective_run_options = install_run_options(env, run_options)
           config_migration_step = kettle_config_migration_step(project_root)
+          effective_run_options = effective_run_options.merge(defer_drift_check: true)
           report = Kettle::Jem.apply_project(project_root, env: env, run_options: effective_run_options)
           report = followup_apply_after_config_bootstrap(project_root, env: env, run_options: effective_run_options, report: report)
           install_steps = []
@@ -68,6 +69,11 @@ module Kettle
             report: final_report,
             run_options: effective_run_options
           )
+          final_report = Kettle::Jem.finalize_duplicate_drift(
+            project_root: project_root,
+            report: final_report,
+            run_options: effective_run_options
+          )
           bootstrap_commit = bootstrap_commit_step(project_root, run_options: effective_run_options)
           install_steps.concat(
             execute_orchestration_steps(
@@ -954,9 +960,7 @@ module Kettle
         end
 
         def same_path?(left, right)
-          File.realpath(left.to_s) == File.realpath(right.to_s)
-        rescue Errno::ENOENT
-          File.expand_path(left.to_s) == File.expand_path(right.to_s)
+          Kettle::Dev::Paths.same?(left.to_s, right.to_s)
         end
 
         def rubocop_lts_local_root(env)
@@ -1025,7 +1029,7 @@ module Kettle
           destination_bin = File.join(project_root.to_s, "bin")
           destination_binstubs = binstub_files(destination_bin)
           parent_root = git_toplevel(project_root)
-          parent_binstubs = if parent_root && File.expand_path(parent_root) != File.expand_path(project_root.to_s)
+          parent_binstubs = if parent_root && !same_path?(parent_root, project_root)
             binstub_files(File.join(parent_root, "bin"))
           else
             []
@@ -1788,7 +1792,7 @@ module Kettle
 
           bundle_gemfile = (env || {})["BUNDLE_GEMFILE"].to_s.strip
           project_gemfile = File.expand_path(File.join(project_root.to_s, "Gemfile"))
-          if !bundle_gemfile.empty? && File.expand_path(bundle_gemfile) == project_gemfile
+          if !bundle_gemfile.empty? && same_path?(bundle_gemfile, project_gemfile)
             return {
               name: "bundled_handoff",
               status: "already_bundled",

data/lib/kettle/jem/tasks/prepare_task.rb

@@ -28,7 +28,8 @@ module Kettle
           effective_run_options = Kettle::Jem::Tasks::TemplateTask.env_run_options(env || {}).merge(run_options || {})
           prepare_run_options = effective_run_options.merge(
             only: PREPARE_ONLY_PATHS,
-            skip_lock_normalization: true
+            skip_lock_normalization: true,
+            defer_drift_check: true
           )
           events = Kettle::Jem.event_stream_from_options(effective_run_options)
           report = Kettle::Jem.apply_project(project_root, env: env, run_options: prepare_run_options)
@@ -37,7 +38,7 @@ module Kettle
             Kettle::Jem.apply_project(project_root, env: env, run_options: prepare_run_options)
           end
           report = merge_supplemental_prepare_report(report, supplemental_report)
-          transition_step = reconcile_template_managed_dependencies_step(project_root, events: events)
+          transition_step = reconcile_template_managed_dependencies_step(project_root, env: env, events: events)
           nomono_bootstrap_step = normalize_existing_local_gemfile_bootstraps_step(project_root, events: events)
           setup_env = Kettle::Jem::Tasks::InstallTask.setup_command_env(project_root, env)
           setup_env["BUNDLE_DISABLE_CHECKSUM_VALIDATION"] = "true"
@@ -51,7 +52,7 @@ module Kettle
           )
           Kettle::Jem.emit_step_event(events, "command_step", reset_step, phase: "prepare")
           bootstrap_name = templating_bootstrap_step_name(project_root)
-          bootstrap_command = templating_bootstrap_command(project_root)
+          bootstrap_command = templating_bootstrap_command(project_root, env: setup_env)
           Kettle::Jem.emit_step_event(
             events,
             "command_step",
@@ -98,6 +99,11 @@ module Kettle
                 "updated critical templating gems, and ran bundle install."
             }]
           )
+          final_report = Kettle::Jem.finalize_duplicate_drift(
+            project_root: project_root,
+            report: final_report,
+            run_options: effective_run_options
+          )
           Kettle::Jem.emit_summary_event(events, final_report)
           final_report
         end
@@ -139,7 +145,7 @@ module Kettle
           step
         end
 
-        def reconcile_template_managed_dependencies_step(project_root, events:)
+        def reconcile_template_managed_dependencies_step(project_root, events:, env: ENV)
           paths = [
             File.join(project_root.to_s, "Gemfile"),
             *Dir.glob(File.join(project_root.to_s, "*.gemfile")),
@@ -148,11 +154,12 @@ module Kettle
           ].select { |path| File.file?(path) }.sort
           changed_files = paths.filter_map do |path|
             before = File.read(path)
-            after = Kettle::Jem.reconcile_template_managed_dependencies(before)
+            relative_path = Pathname.new(path).relative_path_from(Pathname.new(project_root.to_s)).to_s
+            after = Kettle::Jem.reconcile_template_managed_dependencies(before, env: env)
             next if after == before
 
             File.write(path, after)
-            Pathname.new(path).relative_path_from(Pathname.new(project_root.to_s)).to_s
+            relative_path
           end
           step = {
             name: "reconcile_template_managed_dependencies",
@@ -217,14 +224,26 @@ module Kettle
           end
         end
 
-        def bundle_update_templating_bootstrap_command(project_root = Dir.pwd)
-          %w[bundle update] + managed_bootstrap_gems(project_root) + locked_templating_gems(project_root)
+        def bundle_update_templating_bootstrap_command(project_root = Dir.pwd, env: ENV)
+          # Bundler can retain registry resolutions for sibling gems even when
+          # the local path Gemfile is active; refresh the locked family graph.
+          local_structuredmerge_gems = if Kettle::Jem.local_structuredmerge_path_mode?(env)
+            Kettle::Jem::STRUCTUREDMERGE_GEMS & locked_gem_names(project_root)
+          else
+            []
+          end
+          (
+            %w[bundle update] +
+              managed_bootstrap_gems(project_root) +
+              locked_templating_gems(project_root) +
+              local_structuredmerge_gems
+          ).uniq
         end
 
-        def templating_bootstrap_command(project_root = Dir.pwd)
+        def templating_bootstrap_command(project_root = Dir.pwd, env: ENV)
           return %w[bundle install] unless templating_bootstrap_lockfile_ready?(project_root)
 
-          bundle_update_templating_bootstrap_command(project_root)
+          bundle_update_templating_bootstrap_command(project_root, env: env)
         end
 
         def templating_bootstrap_step_name(project_root = Dir.pwd)

data/lib/kettle/jem/tasks/template_task.rb

@@ -18,7 +18,7 @@ module Kettle
               recipe_reports: []
             }
           else
-            Kettle::Jem.apply_project(project_root, env: env, run_options: effective_run_options)
+            Kettle::Jem.apply_project(project_root, env: env, run_options: effective_run_options.merge(defer_drift_check: true))
           end
           setup_env = Kettle::Jem::Tasks::InstallTask.setup_command_env(project_root, env)
           hook_step = Kettle::Jem::Tasks::InstallTask.hook_templates_step(project_root, effective_run_options)
@@ -33,7 +33,22 @@ module Kettle
             command_runner: command_runner,
             event_phase: "template"
           )
-          final_report = report.merge(mode: "template", template_steps: template_steps)
+          orchestration_changed_files = template_steps.flat_map do |step|
+            Array(step[:changed_files] || step["changed_files"])
+          end
+          changed_files = (Array(report[:changed_files]) + orchestration_changed_files).map(&:to_s).uniq.sort
+          final_report = report.merge(
+            mode: "template",
+            template_steps: template_steps,
+            changed_files: changed_files
+          )
+          if report.key?(:duplicate_drift)
+            final_report = Kettle::Jem.finalize_duplicate_drift(
+              project_root: project_root,
+              report: final_report,
+              run_options: effective_run_options
+            )
+          end
           Kettle::Jem.emit_summary_event(Kettle::Jem.event_stream_from_options(effective_run_options), final_report)
           final_report
         end
@@ -90,7 +105,7 @@ module Kettle
           return standalone_limit unless wave_jobs
 
           available_per_member = (cpu_count - wave_jobs) / wave_jobs
-          [standalone_limit, [available_per_member, 1].max].min
+          available_per_member.clamp(1, standalone_limit)
         end
 
         def family_wave_jobs(env)

data/lib/kettle/jem/templates/.git-hooks/prepare-commit-msg.example

@@ -3,7 +3,6 @@
 # Fail on error and unset variables
 set -eu
 
-# Run the generated wrapper directly so hook execution does not depend on shell activation.
-# We are not using direnv exec here because mise and direnv can result in conflicting PATH settings:
-# See: https://mise.jdx.dev/direnv.html
-exec "kettle-commit-msg" "$@"
+# Resolve the installed gem executable through RubyGems, not a repository-local
+# Bundler binstub that may select a temporarily inconsistent project lockfile.
+exec env RUBYOPT= ruby -e 'require "rubygems"; load Gem.bin_path("kettle-dev", "kettle-commit-msg")' "$@"

data/lib/kettle/jem/templates/.github/workflows/coverage.yml.example

@@ -59,7 +59,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup Ruby & RubyGems
-        uses: appraisal-rb/setup-ruby-flash@925395edf973d2dc0a629919f407f3547a03d4b5 # v2.1 compatibility bundle installation
+        uses: appraisal-rb/setup-ruby-flash@6f8ad36ba7488db591541483afb5464d01e8861b # v2.14 compatibility bundle installation
         with:
           ruby-version: "${{ matrix.ruby }}"
           rubygems: "${{ matrix.rubygems }}"

data/lib/kettle/jem/templates/.github/workflows/current.yml.example

@@ -29,19 +29,15 @@ concurrency:
 jobs:
   test:
     if: "github.event_name != 'push' || (!contains(github.event.head_commit.message, '[ci skip]') && !contains(github.event.head_commit.message, '[skip ci]'))"
-    name: Specs ${{ matrix.ruby }}@${{ matrix.appraisal }}
-    runs-on: ubuntu-latest
+    name: Specs ${{ matrix.os }} ${{ matrix.ruby }}@${{ matrix.appraisal }}
+    runs-on: ${{ matrix.os }}
     env: # $BUNDLE_GEMFILE must be set at job level, so it is set for all steps
       BUNDLE_GEMFILE: ${{ github.workspace }}/Appraisal.root.gemfile
     strategy:
       matrix:
         include:
           # Ruby 4.0
-          - ruby: "ruby"
-            appraisal: "current"
-            exec_cmd: "{KJ|CI:EXEC_CMD}"
-            rubygems: latest
-            bundler: latest
+{KJ|CI:OS_MATRIX_ENTRIES}
 
     steps:
       - name: Checkout
@@ -50,7 +46,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup Ruby & RubyGems
-        uses: appraisal-rb/setup-ruby-flash@925395edf973d2dc0a629919f407f3547a03d4b5 # v2.1 compatibility bundle installation
+        uses: appraisal-rb/setup-ruby-flash@6f8ad36ba7488db591541483afb5464d01e8861b # v2.14 bundle validation and compatibility installation
         with:
           ruby-version: ${{ matrix.ruby }}
           rubygems: ${{ matrix.rubygems }}
@@ -77,10 +73,9 @@ jobs:
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: .rspec_status
-          key: rspec-status-current-${{matrix.ruby}}-${{matrix.appraisal}}-${{hashFiles('**/Gemfile.lock','Appraisal.root.gemfile','gemfiles/**/*.gemfile')}}-${{github.run_id}}-${{github.run_attempt}}
+          key: rspec-status-current-${{matrix.os}}-${{matrix.ruby}}-${{matrix.appraisal}}-${{hashFiles('**/Gemfile.lock','Appraisal.root.gemfile','gemfiles/**/*.gemfile')}}-${{github.run_id}}-${{github.run_attempt}}
           restore-keys: |
-            rspec-status-current-${{matrix.ruby}}-${{matrix.appraisal}}-${{hashFiles('**/Gemfile.lock','Appraisal.root.gemfile','gemfiles/**/*.gemfile')}}-
-            rspec-status-current-${{matrix.ruby}}-${{matrix.appraisal}}-
+            rspec-status-current-${{matrix.os}}-${{matrix.ruby}}-${{matrix.appraisal}}-${{hashFiles('**/Gemfile.lock','Appraisal.root.gemfile','gemfiles/**/*.gemfile')}}-
+            rspec-status-current-${{matrix.os}}-${{matrix.ruby}}-${{matrix.appraisal}}-
 
-      - name: Tests for ${{ matrix.ruby }} via ${{ matrix.exec_cmd }}
-        run: bundle exec appraisal ${{ matrix.appraisal }} bundle exec ${{ matrix.exec_cmd }}
+{KJ|CI:OS_TEST_STEPS}

data/lib/kettle/jem/templates/.github/workflows/dep-heads.yml.example

@@ -61,7 +61,7 @@ jobs:
 
       - name: Setup Ruby & RubyGems
         if: ${{ !env.ACT }}
-        uses: appraisal-rb/setup-ruby-flash@925395edf973d2dc0a629919f407f3547a03d4b5 # v2.1 compatibility bundle installation
+        uses: appraisal-rb/setup-ruby-flash@6f8ad36ba7488db591541483afb5464d01e8861b # v2.14 compatibility bundle installation
         with:
           ruby-version: ${{ matrix.ruby }}
           rubygems: ${{ matrix.rubygems }}
@@ -102,7 +102,7 @@ jobs:
         run: bundle exec ${{ matrix.exec_cmd }}
 
   truffleruby:
-    if: "(github.event_name != 'push' || (!contains(github.event.head_commit.message, '[ci skip]') && !contains(github.event.head_commit.message, '[skip ci]'))) && (github.event_name != 'pull_request' || startsWith(github.head_ref, 'engines/') || startsWith(github.head_ref, 'truffleruby/') || startsWith(github.head_ref, 'feature/release'))"
+    if: "(github.event_name != 'push' || (!contains(github.event.head_commit.message, '[ci skip]') && !contains(github.event.head_commit.message, '[skip ci]'))) && (github.event_name != 'pull_request' || startsWith(github.head_ref, 'engines/') || startsWith(github.head_ref, 'truffleruby/') || startsWith(github.head_ref, 'feature/release') || startsWith(github.event.pull_request.title, 'Release '))"
     name: Specs truffleruby@dep-heads
     runs-on: ubuntu-latest
     continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }}
@@ -134,7 +134,7 @@ jobs:
 
       - name: Setup Ruby & RubyGems
         if: ${{ !env.ACT }}
-        uses: appraisal-rb/setup-ruby-flash@925395edf973d2dc0a629919f407f3547a03d4b5 # v2.1 compatibility bundle installation
+        uses: appraisal-rb/setup-ruby-flash@6f8ad36ba7488db591541483afb5464d01e8861b # v2.14 compatibility bundle installation
         with:
           ruby-version: ${{ matrix.ruby }}
           rubygems: ${{ matrix.rubygems }}
@@ -175,7 +175,7 @@ jobs:
         run: bundle exec ${{ matrix.exec_cmd }}
 
   jruby:
-    if: "(github.event_name != 'push' || (!contains(github.event.head_commit.message, '[ci skip]') && !contains(github.event.head_commit.message, '[skip ci]'))) && (github.event_name != 'pull_request' || startsWith(github.head_ref, 'engines/') || startsWith(github.head_ref, 'jruby/') || startsWith(github.head_ref, 'feature/release'))"
+    if: "(github.event_name != 'push' || (!contains(github.event.head_commit.message, '[ci skip]') && !contains(github.event.head_commit.message, '[skip ci]'))) && (github.event_name != 'pull_request' || startsWith(github.head_ref, 'engines/') || startsWith(github.head_ref, 'jruby/') || startsWith(github.head_ref, 'feature/release') || startsWith(github.event.pull_request.title, 'Release '))"
     name: Specs jruby@dep-heads
     runs-on: ubuntu-latest
     continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }}
@@ -208,7 +208,7 @@ jobs:
 
       - name: Setup Ruby & RubyGems
         if: ${{ !env.ACT }}
-        uses: appraisal-rb/setup-ruby-flash@925395edf973d2dc0a629919f407f3547a03d4b5 # v2.1 compatibility bundle installation
+        uses: appraisal-rb/setup-ruby-flash@6f8ad36ba7488db591541483afb5464d01e8861b # v2.14 compatibility bundle installation
         with:
           ruby-version: ${{ matrix.ruby }}
           rubygems: ${{ matrix.rubygems }}

data/lib/kettle/jem/templates/.github/workflows/framework-ci.yml.example

@@ -58,7 +58,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup Ruby & RubyGems
-        uses: appraisal-rb/setup-ruby-flash@925395edf973d2dc0a629919f407f3547a03d4b5 # v2.1 compatibility bundle installation
+        uses: appraisal-rb/setup-ruby-flash@6f8ad36ba7488db591541483afb5464d01e8861b # v2.14 compatibility bundle installation
         with:
           ruby-version: "${{ matrix.ruby }}"
           rubygems: "${{ matrix.rubygems }}"