📝 Use root changelog for html-merge

.kettle-family.yml

@@ -1,9 +1,43 @@
 ---
 family:
   name: structuredmerge-ruby
+  mode: monorepo
+  local_path_env: STRUCTUREDMERGE_DEV
   members_root: gems
 
 members:
+  roots:
+    - gems/tree_haver
+    - gems/ast-merge
+    - gems/ast-crispr
+    - gems/ast-crispr-ruby-prism
+    - gems/ast-crispr-markdown-markly
+    - gems/ast-merge-git
+    - gems/plain-merge
+    - gems/bash-merge
+    - gems/dotenv-merge
+    - gems/rbs-merge
+    - gems/html-merge
+    - gems/json-merge
+    - gems/yaml-merge
+    - gems/toml-merge
+    - gems/markdown-merge
+    - gems/ruby-merge
+    - gems/go-merge
+    - gems/rust-merge
+    - gems/typescript-merge
+    - gems/ast-template
+    - gems/binary-merge
+    - gems/zip-merge
+    - gems/psych-merge
+    - gems/citrus-toml-merge
+    - gems/parslet-toml-merge
+    - gems/commonmarker-merge
+    - gems/kramdown-merge
+    - gems/markly-merge
+    - gems/prism-merge
+    - gems/smorg-rb
+    - gems/kettle-jem
   exclude:
     - "**/benchmarks/**"
   order:
@@ -115,6 +149,8 @@ install:
 release:
   build_command: bundle exec rake build
   publish_command: bundle exec kettle-release
+  disable_local_path_env:
+    - TSLP_DEV
   env:
     GALTZO_FLOSS_DEV: false
     KETTLE_DEV_DEV: false

CHANGELOG.md

@@ -22,6 +22,16 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - `ast-crispr` now provides `Ast::Crispr::DeleteBatch` for deleting matches from
   multiple structural selectors through one parsed document context.
+- `zip-merge` now registers a Kaitai-backed `TreeHaver.parser_for(:zip)` path
+  for ZIP inventory analysis.
+- `plain-merge` now registers `TreeHaver.parser_for(:text)` and
+  `TreeHaver.parser_for(:plain)` line-backed parser paths for normalized text
+  block analysis.
+- `dotenv-merge` now registers `TreeHaver.parser_for(:dotenv)` and
+  `TreeHaver.parser_for(:env)` line-backed parser paths built on the
+  `plain-merge` line substrate.
+- `zip-merge` now depends on `binary-merge` for shared Kaitai/binary-family
+  report and diagnostic construction.
 - Added `html-merge` as a StructuredMerge Ruby family member with TreeHaver
   HTML parsing, feature profile reporting, and an initial ast-crispr-backed HTML
   structural edit adapter.
@@ -33,6 +43,16 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Changed
 
+- Documented the StructuredMerge Ruby merge-gem family model, including
+  substrate/provider behavior sharing and the requirement that partial document
+  insertion, replacement, and removal flow through `ast-crispr` instead of
+  parser-specific object round-trips.
+- Clarified that `zip-merge` is a Kaitai-family binary AST integration and
+  should not be categorized with byte or line oriented merge gems.
+- Clarified that `binary-merge` is the Kaitai/binary-family substrate for
+  concrete schema parser gems such as `zip-merge`.
+- The `smorg-rb` executable now supports `-v` / `--version` and prints a
+  standard startup header on normal runs.
 - `kettle-jem` now migrates existing SimpleCov bootstrap files for packaged
   monorepo subgems even when the selected template profile does not otherwise
   manage per-gem harness files.
@@ -50,6 +70,8 @@ Please file a bug if you notice a violation of semantic versioning.
 - `kettle-jem` main Gemfile templating now removes repeated direct sibling
   execution blocks left behind by older `nomono` bootstrap output while applying
   the simplified `require "nomono/bundler"` loader.
+- `html-merge` now follows the shared root changelog used by the other
+  monorepo `*-merge` gems instead of carrying a member-local changelog.
 - `smorg-rb` diff-driver output now appends a unified review hunk with exact
   removed and added source text after the semantic structured-diff summary.
 - Retemplated generated project metadata, support documentation, CI workflows,
@@ -102,6 +124,15 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Fixed
 
+- `prism-merge` now preserves template-owned trailing comment lines attached to
+  matched Ruby statements, including comments adjacent to generated `require`
+  calls during template merges.
+- `kettle-jem` local Gemfile templating now removes obsolete nomono activation
+  ceremony from existing destination files while retaining the simple
+  `require "nomono/bundler"` loader.
+- `kettle-jem` bootstrap commits can now be serialized by monorepo family
+  templating, preventing concurrent member template jobs from racing while
+  updating the shared `HEAD`.
 - TreeHaver now smoke-tests `tree_sitter_language_pack` parser execution for the
   requested language before registering the TSLP backend, so broken native gem
   artifacts fail closed with a useful reason instead of surfacing parser
@@ -139,6 +170,8 @@ Please file a bug if you notice a violation of semantic versioning.
   integrations in the current process.
 - Ast-merge changed-gem CI no longer times out or fails when exercising
   isolated fixture integrations that require Prism-backed Ruby merging.
+- TreeHaver's Prism parser backend no longer depends on the removed upstream
+  `Prism.available?` API, allowing Prism 1.9+ to parse during templating.
 - Changed-gem CI suites now pass in isolated gem bundles by loading required
   adapter gems explicitly, avoiding Ruby 4 `Pathname#find` assumptions, and
   keeping Prism merge tests on the local TreeHaver capability registry.

CONTRIBUTING.md

@@ -112,6 +112,58 @@ Git diff driver setup
 K_JEM_TEMPLATING=true kettle-jem install
 ```
 
+## Merge gem architecture
+
+Merge gems are parser-backed, but merge behavior must not call parser libraries
+directly. Parsing enters through `tree_haver`; structural edits enter through
+`ast-crispr`; common merge orchestration enters through `ast-merge`.
+
+Language and format families have a substrate gem that owns shared merge
+behavior for that family. A substrate gem may also register the tree-sitter
+grammar interface for the same format. Provider gems register an alternate AST
+backend and delegate family behavior back to the substrate gem.
+
+Do not infer backend registration from the behavior role. A substrate often does
+register a TSLP/tree-sitter grammar, and may still share behavior with provider
+gems that register native or Ruby parser backends.
+
+Examples:
+
+- `markdown-merge` registers the tree-sitter Markdown path and owns shared
+  Markdown merge behavior. `commonmarker-merge`, `kramdown-merge`, and
+  `markly-merge` provide backend-specific AST integrations and share that
+  Markdown behavior.
+- `yaml-merge` is the YAML substrate. It registers the tree-sitter YAML path and
+  should own shared YAML merge behavior, including key-path partial merge
+  semantics. `psych-merge` provides the Psych-backed YAML AST integration and
+  should share those YAML behaviors.
+- `ruby-merge` registers the tree-sitter Ruby path and owns shared Ruby merge
+  behavior. `prism-merge` provides the Prism-backed Ruby AST integration.
+- `toml-merge` registers the tree-sitter TOML path and owns shared TOML merge
+  behavior. `citrus-toml-merge` and `parslet-toml-merge` provide alternate TOML
+  parser integrations.
+- `rbs-merge` intentionally registers both the official RBS parser backend and
+  the tree-sitter RBS grammar in one gem.
+- `zip-merge` is a Kaitai-family binary AST integration. It registers and
+  consumes a `parser_for(:zip)` Kaitai path so ZIP analysis enters through the
+  normalized TreeHaver API, and depends on `binary-merge` for shared
+  binary-family report and renderer-planning behavior.
+- `binary-merge` is the Kaitai/binary substrate. It hosts common byte-range,
+  preservation, unsafe-diagnostic, render-policy, and nested-dispatch vocabulary
+  for concrete schema parser gems such as `zip-merge`.
+- `plain-merge` is the line/text substrate. It registers `:text` and `:plain`
+  parser paths through the `:line` backend.
+- `dotenv-merge` builds dotenv assignment and comment ownership on top of the
+  plain line substrate, and registers `:dotenv` and `:env` parser paths through
+  the same `:line` backend family.
+
+Partial document insertion, replacement, and removal are `ast-crispr` work.
+`PartialTemplateMerger` should normalize the API used by merge gems and route
+those operations through structural owners and source-preserving edit plans. Do
+not implement partial merges by converting documents to native Ruby objects and
+serializing them back out; that bypasses owner identity, comments, layout, and
+backend diagnostics.
+
 Troubleshooting Git diffs
 - Use `git diff --no-ext-diff` to compare against Git's built-in diff output.
 - Use `git diff --no-textconv` when a textconv projection obscures the raw file bytes you need to inspect.

Gemfile

@@ -73,7 +73,7 @@ gem "bundler-audit", "~> 0.9.3"
 if kettle_dev_dev.casecmp("false").zero?
   gem "kettle-dev", "~> 2.2", ">= 2.2.25"
 
-  gem "kettle-family", ">= 1.0.4"
+  gem "kettle-family", ">= 1.1.9"
 
   gem "kettle-test", "~> 2.0", ">= 2.0.11"
 end