👷 Improve CI config

Author: pboling

.github/COPILOT_INSTRUCTIONS.md

@@ -101,6 +101,34 @@ When `replace_string_in_file` fails with "Could not find matching text":
 
 ## API Conventions
 
+### Forward Compatibility with **options
+
+**CRITICAL DESIGN PRINCIPLE**: All constructors and public API methods that accept keyword arguments MUST include `**options` (or similar catch-all) as the final parameter to capture unknown options.
+
+✅ **CORRECT**:
+```ruby
+def initialize(source, freeze_token: DEFAULT, signature_generator: nil, **options)
+  @source = source
+  @freeze_token = freeze_token
+  @signature_generator = signature_generator
+  # **options captures future parameters for forward compatibility
+end
+```
+
+❌ **WRONG**:
+```ruby
+def initialize(source, freeze_token: DEFAULT, signature_generator: nil)
+  # This breaks when new parameters are added to the base class
+end
+```
+
+**Why**: When `SmartMergerBase` adds new standard options (like `node_typing`, `regions`, etc.), all `FileAnalysis` classes automatically support them without code changes. Without `**options`, every FileAnalysis would need updating whenever a new option is added.
+
+**Applies to**:
+- `FileAnalysis#initialize` in all gems
+- `SmartMerger#initialize` in all gems  
+- Any method that accepts a variable set of options
+
 ### SmartMergerBase API
 - `merge` - Returns a **String** (the merged content)
 - `merge_result` - Returns a **MergeResult** object
@@ -124,9 +152,15 @@ When `replace_string_in_file` fails with "Could not find matching text":
 
 ## Loading Vendor Gems in Scripts
 
-**IMPORTANT**: When writing standalone Ruby scripts to test vendor gems, you must use `bundler/setup` to properly load the gems.
+**IMPORTANT**: The approach depends on whether you're using the project's Gemfile or need standalone execution.
+
+### For Scripts Using Project Gemfile (bundler/setup)
+
+✅ **Use bundler/setup when**:
+- The script runs within the project context
+- The Gemfile already specifies all needed gems with `path:` options
+- You want to use the exact versions locked in Gemfile.lock
 
-✅ **CORRECT** - Use bundler/setup:
 ```ruby
 #!/usr/bin/env ruby
 # frozen_string_literal: true
@@ -137,22 +171,100 @@ require "prism/merge"
 # Now you can use Prism::Merge classes
 ```
 
+### For Standalone Scripts with Local Paths (bundler/inline)
+
+✅ **Use bundler/inline when**:
+- Creating standalone scripts in `bin/` that need specific gem paths
+- Testing with fixture gems or specific local paths
+- The script needs to specify its own dependencies independent of the project Gemfile
+- You need to load gems from vendor directories not in the main Gemfile
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/inline"
+
+gemfile do
+  source "https://rubygems.org"
+  gem "ast-merge", path: File.expand_path("..", __dir__)
+  gem "tree_haver", path: File.expand_path("../vendor/tree_haver", __dir__)
+  gem "markdown-merge", path: File.expand_path("../vendor/markdown-merge", __dir__)
+end
+
+# Now gems are loaded and ready to use
+require "markdown/merge"
+```
+
+**Why bundler/inline for standalone scripts:**
+1. The gemfile block creates an inline Gemfile with specified paths
+2. Bundler resolves dependencies and configures load paths
+3. Scripts become self-contained and portable
+4. No need to modify the project's main Gemfile
+
+**Common pitfall with bundler/inline:**
+- If a gem in your inline gemfile has unresolved dependencies, bundler will try to fetch them
+- Solution: Only include gems you actually need, or ensure all transitive dependencies are available
+
 ❌ **BROKEN** - These do NOT work:
 ```ruby
 # This doesn't load the gem properly:
 require_relative "lib/prism/merge"
 
 # This doesn't set up the load path:
-require "prism/merge"  # without bundler/setup first
+require "prism/merge"  # without bundler/setup or bundler/inline first
 ```
 
-The pattern `require "bundler/setup"` followed by `require "gem/name"` works because:
-1. `bundler/setup` configures the load path based on the Gemfile
-2. The vendor gems are specified in the Gemfile with `path:` option
-3. This allows standard `require` to find the gems
-
 ## Testing
 
+### kettle-test RSpec Helpers
+
+**IMPORTANT**: All spec files load `require "kettle/test/rspec"` which provides extensive RSpec helpers and configuration from the kettle-test gem. DO NOT recreate these helpers - they already exist.
+
+**Environment Variable Helpers** (from `rspec-stubbed_env` gem):
+- `stub_env(hash)` - Temporarily set environment variables in a block
+- `hide_env(*keys)` - Temporarily hide environment variables
+
+**Example usage**:
+They are not used with blocks, but can be used like this:
+```ruby
+before do
+   stub_env("MY_ENV_VAR" => "Bla Blah Blu")
+end
+it "should see MY_ENV_VAR" do
+   # code that reads ENV["MY_ENV_VAR"]
+end
+
+# hide_env("HOME", "USER")
+# is used the same way, but hides the variable so it acts as it if isn't set at all.
+```
+
+**Other Helpers** (loaded by kettle-test):
+- `block_is_expected` - Enhanced block expectations (from `rspec-block_is_expected`)
+- `capture` - Capture output during tests (from `silent_stream`)
+- Timecop integration for time manipulation
+
+**Where these come from**:
+- External gems loaded by `kettle/test/external.rb` in the kettle-test gem
+- `rspec/stubbed_env` - Provides `stub_env` and `hide_env`
+- `rspec/block_is_expected` - Enhanced block expectations
+- `silent_stream` - Output suppression
+- `timecop/rspec` - Time travel for tests
+
+**Other Helpers** (loaded by kettle-test):
+- `block_is_expected` - Enhanced block expectations (from `rspec-block_is_expected`)
+- `capture` - Capture output during tests (from `silent_stream`)
+- Timecop integration for time manipulation
+
+**Where these come from**:
+- External gems loaded by `kettle/test/external.rb` in the kettle-test gem
+- `rspec/stubbed_env` - Provides `stub_env` and `hide_env`
+- `rspec/block_is_expected` - Enhanced block expectations
+- `silent_stream` - Output suppression
+- `timecop/rspec` - Time travel for tests
+
+### Running Tests
+
 Run tests from the appropriate directory:
 ```bash
 # ast-merge tests
@@ -187,13 +299,15 @@ This runs tests with coverage instrumentation and generates detailed coverage re
 
 **How `run_in_terminal` works**:
 - The tool sends commands to a **single persistent Copilot terminal**
+- Use `isBackground=false` for `run_in_terminal`. Sometimes it works, but if it fails/hangs, use the file redirection method, and then read back with `read_file` tool.
 - Commands run in sequence in the same terminal session
 - Environment variables and working directory persist between calls
 - The first command in a session either does not run at all, or runs before the shell initialization (direnv, motd, etc.) so it should always be a noop, like `true`.
 
 **When things go wrong**:
 - If output shows only shell banner/motd without command results, the command most likely worked, but the tool has lost the ability to see terminal output. This happens FREQUENTLY.
-- EVERY TIME you do not see output, STOP and confirm output status with the user.
+- EVERY TIME you do not see output, STOP and confirm output status with the user, or switch immediately to file redirection, and read the file back with `read_file` tool.
+- **ALWAYS use project's `tmp/` directory for temporary files** - NEVER use `/tmp` or other system directories
 - Solution: Ask the user to share the output they see.
 
 **Best practices**:

.github/workflows/locked_deps.yml

@@ -25,8 +25,8 @@ env:
   #   because it would be redundant with the coverage workflow.
   # Also we can validate all output formats without breaking CodeCov,
   #   since we aren't submitting these reports anywhere.
-  K_SOUP_COV_MIN_BRANCH: 71
-  K_SOUP_COV_MIN_LINE: 86
+  K_SOUP_COV_MIN_BRANCH: 90
+  K_SOUP_COV_MIN_LINE: 90
   K_SOUP_COV_MIN_HARD: false
   K_SOUP_COV_FORMATTERS: "html,xml,rcov,lcov,json,tty"
   K_SOUP_COV_DO: true

.gitlab-ci.yml

@@ -22,7 +22,7 @@ variables:
   K_SOUP_COV_DEBUG: true
   K_SOUP_COV_DO: true
   K_SOUP_COV_HARD: true
-  K_SOUP_COV_MIN_BRANCH: 74
+  K_SOUP_COV_MIN_BRANCH: 90
   K_SOUP_COV_MIN_LINE: 90
   K_SOUP_COV_VERBOSE: true
   K_SOUP_COV_FORMATTERS: "tty"

Gemfile.lock

@@ -44,7 +44,7 @@ GEM
       thor (~> 1.0)
     concurrent-ruby (1.3.6)
     date (3.5.1)
-    debug (1.11.0)
+    debug (1.11.1)
       irb (~> 1.10)
       reline (>= 0.3.8)
     delegate (0.6.1)
@@ -140,15 +140,15 @@ GEM
       pdf-core (~> 0.10.0)
       ttfunk (~> 1.8)
     prettyprint (0.2.0)
-    prism (1.6.0)
+    prism (1.7.0)
     psych (5.3.1)
       date
       stringio
     public_suffix (7.0.0)
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.1)
-    rbs (3.9.5)
+    rbs (3.10.0)
       logger
     rdoc (6.17.0)
       erb