rails-hyperdrive 0.7.0 → 0.9.0

data/lib/rails/hyperdrive/install_pipeline.rb

@@ -3,6 +3,7 @@ require "time"
 require "rails/hyperdrive/ancestor_locator"
 require "rails/hyperdrive/bundler_artifact_discovery"
 require "rails/hyperdrive/claude_md_import"
+require "rails/hyperdrive/config_file"
 require "rails/hyperdrive/drift_verdict"
 require "rails/hyperdrive/three_way_merge"
 require "rails/hyperdrive/eager_footprint"
@@ -16,7 +17,8 @@ module Rails
     # The application root is explicit and no Rails constant is touched, so any
     # process that can see the bundle can run this.
     class InstallPipeline
-      ARTIFACT_DESTINATIONS = (InstallLayout.dest_roots + [InstallLayout::LOCK_PATH]).freeze
+      ARTIFACT_DESTINATIONS =
+        (InstallLayout.dest_roots + [InstallLayout::LOCK_PATH, InstallLayout::CONFIG_PATH]).freeze
 
       WARN_LINES = 150
       WARN_TOKENS = 1_500
@@ -26,7 +28,10 @@ module Rails
       Result = Struct.new(:installed, :updated, :unchanged, :skipped, :orphaned, :removed, :merged, :sidecars,
         keyword_init: true)
 
-      def initialize(root:, shell:, artifacts:, mode: :preserve, report: BundlerArtifactDiscovery::Report.new)
+      Sidecar = Struct.new(:dest, :ancestor, :previous_source, keyword_init: true)
+
+      def initialize(root:, shell:, artifacts:, mode: :preserve, report: BundlerArtifactDiscovery::Report.new,
+                     config: nil)
         raise ArgumentError, "unknown mode #{mode.inspect}" unless MODES.include?(mode)
 
         @root = File.expand_path(root.to_s)
@@ -34,6 +39,7 @@ module Rails
         @artifacts = artifacts
         @mode = mode
         @report = report
+        @config = config
         @bundled_gems = Array(report.bundled_gems).map(&:to_s)
         @skipped_gems = Array(report.skipped_gems).map(&:to_s)
         @result = Result.new(
@@ -44,7 +50,8 @@ module Rails
       def call
         return halt_schema_ahead if old_lock.schema_ahead?
 
-        @new_lock = LockFile.new(abs(InstallLayout::LOCK_PATH)).carry_settings(old_lock)
+        report_settings_warnings
+        @new_lock = LockFile.new(abs(InstallLayout::LOCK_PATH)).carry_document(old_lock)
         @plan = plan
 
         report_collisions
@@ -56,6 +63,7 @@ module Rails
         carry_orphans
         eager_guidelines = write_index_md(guidelines)
         write_claude_md(guidelines)
+        clear_resolved_ancestors
         write_lock
         print_warnings
         print_notices
@@ -82,7 +90,19 @@ module Rails
       end
 
       def build_result
-        @build_result ||= InstallPlan.build(@artifacts, lock: old_lock)
+        @build_result ||= InstallPlan.build(@artifacts, config: config)
+      end
+
+      def config
+        @config ||= ConfigFile.load(abs(InstallLayout::CONFIG_PATH))
+      end
+
+      def report_settings_warnings
+        return if additive?
+
+        config.warnings.each { |warning| @shell.say_status :warn, warning, :yellow }
+        return unless old_lock.legacy_settings?
+        @shell.say_status :warn, old_lock.legacy_settings_message(InstallLayout::LOCK_PATH), :yellow
       end
 
       def old_lock
@@ -120,7 +140,7 @@ module Rails
 
       def report_disabled
         build_result.disabled.each do |entry|
-          @shell.say_status :disabled, "#{entry.type} '#{entry.final_name}' (listed in #{InstallLayout::LOCK_PATH})", :blue
+          @shell.say_status :disabled, "#{entry.type} '#{entry.final_name}' (listed in #{InstallLayout::CONFIG_PATH})", :blue
         end
       end
 
@@ -239,56 +259,101 @@ module Rails
       # Reconciliation for a locally-modified destination in :sidecar/:merge
       # mode. The lock records the newest upstream *delivered* — installed
       # live, merged in, or written as a sidecar — never the live file's own
-      # hash, so the same upstream version is offered exactly once.
+      # hash, so the same upstream version is offered exactly once. While a
+      # sidecar is pending the entry also records the *ancestor*: the upstream
+      # the live file's own edits descend from, which a later run needs as the
+      # merge base.
       def reconcile_edited(write, old, source_relpath:, final_name:)
         dest = write[:dest]
         sidecar = InstallLayout.sidecar_path(dest)
+        pending = File.exist?(abs(sidecar))
+        pristine = pending && delivered_sidecar?(sidecar, delivered_shas(write, old))
 
         if old && old.source_sha == write[:gem_sha]
-          skip_edited(write, old)
-          if File.exist?(abs(sidecar))
-            @shell.say_status :warn, "#{sidecar} (unresolved sidecar; reconcile it with #{dest}, then delete it)", :yellow
-          end
-          return
+          return retry_pending(write, old, sidecar, pending: pending, pristine: pristine, final_name: final_name)
         end
 
         # An edited sidecar is user work: leave it, and leave the lock at the
         # old upstream so this delivery is re-offered once the user clears it.
-        if File.exist?(abs(sidecar)) && !delivered_sidecar?(sidecar, delivered_shas(write, old))
+        if pending && !pristine
           @result.skipped << dest
           @shell.say_status :warn, "#{sidecar} (sidecar locally modified; resolve or delete it)", :yellow
           @new_lock.carry(old) if old
           return
         end
 
+        deliver(write, old, pending: pending, source_relpath: source_relpath, final_name: final_name)
+      end
+
+      # Nothing new to deliver: the pending sidecar is still the standing
+      # offer, so --merge attempts to complete it rather than re-offering it.
+      def retry_pending(write, old, sidecar, pending:, pristine:, final_name:)
         reason = nil
-        if merge_mode?
-          if File.exist?(abs(sidecar))
-            # A pending sidecar means the last delivered upstream never reached
-            # the live file, so the reconstructable ancestor is stale; merging
-            # over it would silently revert that delivery.
-            reason = "previous delivery still unresolved"
-          else
-            merged, reason = attempt_merge(write, old, source_relpath: source_relpath, final_name: final_name)
-            if merged
-              write_merged(write, merged)
-              sweep_sidecar(write, old)
-              return
-            end
+        if merge_mode? && pristine
+          ancestor = AncestorLocator.locate_recorded_ancestor(old, final_name: final_name)
+          merged, reason = ancestor ? merge_bodies(write, ancestor) : [nil, "ancestor unavailable"]
+          if merged
+            write_merged(write, merged)
+            sweep_sidecar(write, old)
+            return
           end
         end
 
-        write_sidecar(write, reason)
+        skip_edited(write, old)
+        return unless pending
+
+        message = "#{sidecar} (unresolved sidecar; reconcile it with #{write[:dest]}, then delete it"
+        message += "; #{reason}" if reason
+        @shell.say_status :warn, "#{message})", :yellow
       end
 
-      def attempt_merge(write, old, source_relpath:, final_name:)
-        return [nil, "no previous install recorded"] unless old
+      # The ancestor is the live file's own base, so a delivery landing on top
+      # of a pending one keeps the ancestor already recorded.
+      def deliver(write, old, pending:, source_relpath:, final_name:)
+        if pending
+          record = recorded_ancestor(old)
+          ancestor = AncestorLocator.locate_recorded_ancestor(old, final_name: final_name)
+          previous_source = old&.ancestor_label
+          reason = "ancestor unavailable" if merge_mode? && ancestor.nil?
+        else
+          record = fresh_ancestor(old, source_relpath)
+          ancestor = locate_ancestor(write, old, source_relpath: source_relpath, final_name: final_name)
+          previous_source = old&.source_label
+          reason = fresh_merge_reason(old, ancestor) if merge_mode?
+        end
 
-        ancestor = AncestorLocator.locate(
-          kind: write[:artifact_kind], relpath: source_relpath, lock_entry: old, final_name: final_name
-        )
-        return [nil, "#{old.source_label} not found in installed gems"] unless ancestor
+        if merge_mode? && ancestor
+          merged, reason = merge_bodies(write, ancestor)
+          if merged
+            write_merged(write, merged)
+            sweep_sidecar(write, old)
+            return
+          end
+        end
+
+        write_sidecar(write, reason, ancestor: ancestor, previous_source: previous_source, ancestor_record: record)
+      end
+
+      def fresh_merge_reason(old, ancestor)
+        return "no previous install recorded" unless old
+        return "#{old.source_label} not found in installed gems" unless ancestor
+        nil
+      end
 
+      # A fresh delivery always reads the ancestor off the entry's own source,
+      # never off ancestor keys left over from a window that already closed.
+      def fresh_ancestor(old, source_relpath)
+        return nil unless old && source_relpath
+        { gem: old.source_gem, version: old.source_version, sha: old.source_sha, relpath: source_relpath }
+      end
+
+      def recorded_ancestor(old)
+        return nil unless old&.ancestor?
+        { gem: old.ancestor_gem, version: old.ancestor_version, sha: old.ancestor_sha,
+          relpath: old.ancestor_relpath }
+      end
+
+      def merge_bodies(write, ancestor)
         ours = live_body(write)
         if ours.nil? || [ours, ancestor, write[:body]].any? { |b| ThreeWayMerge.binary?(b) }
           return [nil, "binary content"]
@@ -302,6 +367,16 @@ module Rails
         end
       end
 
+      # Reconstruction is sha-gated against the lock entry recorded before this
+      # run, so it must happen before the new upstream is locked.
+      def locate_ancestor(write, old, source_relpath:, final_name:)
+        return nil unless old
+
+        AncestorLocator.locate(
+          kind: write[:artifact_kind], relpath: source_relpath, lock_entry: old, final_name: final_name
+        )
+      end
+
       def live_body(write)
         file = abs(write[:dest])
         return File.binread(file) if write[:type] == :skill_support
@@ -320,14 +395,14 @@ module Rails
       # The sidecar is byte-identical to what a live install of the new
       # upstream would write, so `mv <dest>.new <dest>` accepts it wholesale
       # and the lock already verifies it.
-      def write_sidecar(write, reason)
+      def write_sidecar(write, reason, ancestor: nil, previous_source: nil, ancestor_record: nil)
         sidecar = InstallLayout.sidecar_path(write[:dest])
         @shell.create_file sidecar, write[:body]
-        @result.sidecars << write[:dest]
+        @result.sidecars << Sidecar.new(dest: write[:dest], ancestor: ancestor, previous_source: previous_source)
         message = "#{write[:dest]} (locally modified; new upstream delivered to #{sidecar}"
         message += "; #{reason}" if reason
         @shell.say_status :sidecar, "#{message})", :yellow
-        upsert_lock(write, Time.now.utc)
+        upsert_lock(write, Time.now.utc, ancestor: ancestor_record)
       end
 
       # Only a machine-pristine sidecar — one still hashing to a delivered
@@ -387,17 +462,33 @@ module Rails
         )
       end
 
-      def upsert_lock(write, installed_at)
+      def upsert_lock(write, installed_at, ancestor: nil)
         @new_lock.upsert(
           path: write[:dest],
           kind: write[:artifact_kind],
           source_gem: write[:source_gem],
           source_version: write[:version],
           source_sha: write[:gem_sha],
-          installed_at: installed_at.iso8601
+          installed_at: installed_at.iso8601,
+          ancestor_gem: ancestor && ancestor[:gem],
+          ancestor_version: ancestor && ancestor[:version],
+          ancestor_sha: ancestor && ancestor[:sha],
+          ancestor_relpath: ancestor && ancestor[:relpath]
         )
       end
 
+      # Deleting <dest>.new is the only resolution signal, so a recorded
+      # ancestor stays until the run that finds the sidecar gone drops it.
+      def clear_resolved_ancestors
+        return if additive?
+
+        @new_lock.each_entry do |entry|
+          next unless entry.ancestor?
+          next if File.exist?(abs(InstallLayout.sidecar_path(entry.path)))
+          @new_lock.clear_ancestor(entry.path)
+        end
+      end
+
       # The pipeline's only delete path, so it is gated on the file still
       # matching the content the lock recorded: hand-edited work is reported and
       # left for its owner to remove. The dest's sidecar goes with it, since
@@ -426,7 +517,7 @@ module Rails
           type = InstallLayout::ARTIFACT_TYPES[entry.kind]
           next unless type
           next if @new_lock.entry(entry.path)
-          next unless InstallPlan.disabled_dest?(old_lock, type, entry.path, source_gem: entry.source_gem)
+          next unless InstallPlan.disabled_dest?(config, type, entry.path, source_gem: entry.source_gem)
 
           remove_or_carry(entry) { "disabled but locally modified; delete it by hand" }
         end

data/lib/rails/hyperdrive/install_plan.rb

@@ -53,7 +53,7 @@ module Rails
       # disables every variant and a postfixed name disables just one. The
       # postfixed form is honored whether or not a collision exists today, so
       # the opt-out survives a collision appearing or resolving.
-      def build(artifacts, lock: nil)
+      def build(artifacts, config: nil)
         result = Result.new(entries: [], disabled: [])
         artifacts.group_by { |a| [a.artifact_type, a.name] }.each do |(type, name), group|
           collision = group.size > 1
@@ -66,8 +66,8 @@ module Rails
               dest: InstallLayout.dest_for(type, final_name),
               collision: collision
             )
-            dropped = lock && (lock.disabled?(type, name) ||
-                               lock.disabled?(type, InstallLayout.postfixed_name(name, artifact.source_gem)))
+            dropped = config && (config.disabled?(type, name) ||
+                                 config.disabled?(type, InstallLayout.postfixed_name(name, artifact.source_gem)))
             (dropped ? result.disabled : result.entries) << entry
           end
         end
@@ -77,13 +77,13 @@ module Rails
       # A supporting file is disabled through its owning skill's name. Given the
       # installing gem, a canonically-installed file also answers to the
       # postfixed name that disabled it while it was one of several variants.
-      def disabled_dest?(lock, type, dest, source_gem: nil)
+      def disabled_dest?(config, type, dest, source_gem: nil)
         name = InstallLayout.installed_name(type, dest)
         return false unless name
         lookup = type == :skill_support ? :skill : type
         base = InstallLayout.base_name(name)
-        return true if lock.disabled?(lookup, name) || lock.disabled?(lookup, base)
-        !source_gem.nil? && lock.disabled?(lookup, InstallLayout.postfixed_name(base, source_gem))
+        return true if config.disabled?(lookup, name) || config.disabled?(lookup, base)
+        !source_gem.nil? && config.disabled?(lookup, InstallLayout.postfixed_name(base, source_gem))
       end
     end
   end

data/lib/rails/hyperdrive/lock_file.rb

@@ -1,22 +1,36 @@
 require "yaml"
+require "rails/hyperdrive/install_layout"
 
 module Rails
   module Hyperdrive
     # installed_at is volatile metadata, never an input to any comparison.
     class LockFile
-      SCHEMA_VERSION = 2
+      SCHEMA_VERSION = 3
       STATE_PRESENT  = "present".freeze
       STATE_REMOVED  = "removed-by-user".freeze
 
-      DISABLED_KEYS = { skill: "skills", guideline: "guidelines", agent: "agents", command: "commands" }.freeze
-
       # In-memory form of one files: entry. On disk, source_gem and
       # source_version are a single "gem@version" string; the split/join lives
       # in this file only.
-      Entry = Struct.new(:path, :kind, :source_gem, :source_version, :source_sha, :installed_at, keyword_init: true) do
+      Entry = Struct.new(
+        :path, :kind, :source_gem, :source_version, :source_sha, :installed_at,
+        :ancestor_gem, :ancestor_version, :ancestor_sha, :ancestor_relpath,
+        keyword_init: true
+      ) do
         def source_label
           source_version ? "#{source_gem}@#{source_version}" : source_gem
         end
+
+        # The upstream the live file's edits descend from, recorded only while
+        # a sidecar delivery is pending.
+        def ancestor_label
+          return nil unless ancestor_gem
+          ancestor_version ? "#{ancestor_gem}@#{ancestor_version}" : ancestor_gem
+        end
+
+        def ancestor?
+          !ancestor_gem.nil? && !ancestor_sha.nil?
+        end
       end
 
       attr_reader :path, :schema_version
@@ -39,8 +53,7 @@ module Rails
         @claude_md_state = nil # nil = no lock has been written yet
         @files = {}            # path(String) => Entry
         @document = {}         # raw parsed YAML, kept so unknown keys survive
-        @disabled = empty_disabled
-        @enabled = []
+        @legacy_settings = false
         @schema_version = nil
       end
 
@@ -54,8 +67,7 @@ module Rails
         @schema_version = data["version"]
         claude_md = data["claude_md"]
         @claude_md_state = claude_md["state"] if claude_md.is_a?(Hash)
-        @disabled = parse_disabled(data["disabled"])
-        @enabled = parse_enabled(data["enabled"])
+        @legacy_settings = data.key?("disabled") || data.key?("enabled")
         Array(data["files"]).each do |raw|
           next unless raw.is_a?(Hash)
           entry = build_entry(raw)
@@ -79,6 +91,17 @@ module Rails
           "this installer supports #{SCHEMA_VERSION}); upgrade rails-hyperdrive"
       end
 
+      def legacy_settings?
+        @legacy_settings
+      end
+
+      def legacy_settings_message(display_path)
+        "#{display_path} carries disabled:/enabled:; those settings now live in " \
+          "#{InstallLayout::CONFIG_PATH} and are ignored here. Move them now: disabled " \
+          "artifacts install again, and artifacts from gems enabled only there are " \
+          "removed by the next init/sync"
+      end
+
       def entry(file_path)
         @files[file_path.to_s]
       end
@@ -91,35 +114,43 @@ module Rails
         @files.values.each(&block)
       end
 
-      def disabled?(type, name)
-        Array(@disabled[type.to_sym]).include?(name.to_s)
-      end
-
-      # Hand-editable list of gems the app opts into as companions.
-      def enabled_gems
-        @enabled
-      end
-
       # Adopt the state that is not derived from installed content, so
       # rewriting the file preserves it.
-      def carry_settings(other)
+      def carry_document(other)
         @document = other.document.dup
-        @disabled = other.disabled_lists.dup
-        @enabled = other.enabled_gems.dup
         self
       end
 
-      def upsert(path:, kind:, source_gem:, source_version:, source_sha:, installed_at:)
+      def upsert(path:, kind:, source_gem:, source_version:, source_sha:, installed_at:,
+                 ancestor_gem: nil, ancestor_version: nil, ancestor_sha: nil, ancestor_relpath: nil)
         @files[path.to_s] = Entry.new(
           path: path.to_s,
           kind: kind.to_s,
           source_gem: source_gem.to_s,
           source_version: source_version.to_s,
           source_sha: source_sha.to_s,
-          installed_at: installed_at.to_s
+          installed_at: installed_at.to_s,
+          ancestor_gem: ancestor_gem,
+          ancestor_version: ancestor_version,
+          ancestor_sha: ancestor_sha,
+          ancestor_relpath: ancestor_relpath
         )
       end
 
+      # Replaces the entry rather than mutating it, so an entry carried from a
+      # lock read earlier in the run keeps the values that run compared against.
+      def clear_ancestor(file_path)
+        entry = @files[file_path.to_s]
+        return unless entry&.ancestor_gem || entry&.ancestor_sha || entry&.ancestor_relpath
+
+        @files[entry.path] = entry.dup.tap do |cleared|
+          cleared.ancestor_gem = nil
+          cleared.ancestor_version = nil
+          cleared.ancestor_sha = nil
+          cleared.ancestor_relpath = nil
+        end
+      end
+
       def carry(entry)
         return unless entry && entry.path
         @files[entry.path] = entry
@@ -132,14 +163,16 @@ module Rails
         document = @document.merge(
           "version"   => SCHEMA_VERSION,
           "claude_md" => carried.merge("state" => @claude_md_state),
-          "disabled"  => DISABLED_KEYS.each_with_object({}) { |(type, key), h| h[key] = @disabled[type] },
-          "enabled"   => @enabled,
           "files"     => @files.values.sort_by(&:path).map { |e| serialize_entry(e) }
         )
         # A nil state means no import line is being managed. Recording one anyway
         # would make the next run read the absent line as a deletion the user
         # made, and never add it back.
         document.delete("claude_md") if @claude_md_state.nil?
+        # Every other unknown key round-trips; these two must not, or a lock
+        # would keep asserting settings nothing reads.
+        document.delete("disabled")
+        document.delete("enabled")
         document.to_yaml
       end
 
@@ -149,39 +182,22 @@ module Rails
         @document
       end
 
-      def disabled_lists
-        @disabled
-      end
-
       private
 
-      def empty_disabled
-        DISABLED_KEYS.keys.each_with_object({}) { |type, h| h[type] = [] }
-      end
-
-      def parse_disabled(raw)
-        return empty_disabled unless raw.is_a?(Hash)
-
-        DISABLED_KEYS.each_with_object({}) do |(type, key), h|
-          h[type] = Array(raw[key]).map { |name| name.to_s.strip }.reject(&:empty?).uniq
-        end
-      end
-
-      def parse_enabled(raw)
-        return [] unless raw.is_a?(Array)
-
-        raw.map { |name| name.to_s.strip }.reject(&:empty?).uniq
-      end
-
       def build_entry(raw)
         source_gem, source_version = split_source(raw["source"])
+        ancestor_gem, ancestor_version = split_source(raw["ancestor_source"])
         Entry.new(
           path: raw["path"],
           kind: raw["artifact"],
           source_gem: source_gem,
           source_version: source_version,
           source_sha: raw["source_sha"],
-          installed_at: raw["installed_at"]
+          installed_at: raw["installed_at"],
+          ancestor_gem: ancestor_gem,
+          ancestor_version: ancestor_version,
+          ancestor_sha: raw["ancestor_sha"],
+          ancestor_relpath: raw["ancestor_relpath"]
         )
       end
 
@@ -195,13 +211,19 @@ module Rails
       end
 
       def serialize_entry(entry)
-        {
+        raw = {
           "path"         => entry.path,
           "artifact"     => entry.kind,
           "source"       => entry.source_label,
-          "source_sha"   => entry.source_sha,
-          "installed_at" => entry.installed_at
+          "source_sha"   => entry.source_sha
         }
+        # installed_at is re-added after the optional keys so their absence
+        # leaves an entry's key order untouched.
+        raw["ancestor_source"] = entry.ancestor_label if entry.ancestor_label
+        raw["ancestor_sha"] = entry.ancestor_sha if entry.ancestor_sha
+        raw["ancestor_relpath"] = entry.ancestor_relpath if entry.ancestor_relpath
+        raw["installed_at"] = entry.installed_at
+        raw
       end
     end
   end

data/lib/rails/hyperdrive/manifest_lint.rb

@@ -102,9 +102,14 @@ module Rails
         entries.each do |key, entry|
           next if Array(kind.prefix_key).include?(key)
 
+          face = BundlerArtifactDiscovery.target_path(key)
           unless shipped.include?(key)
             problems << "#{kind.section} entry '#{key}' names no shipped #{kind.shipped_label}"
           end
+          if face != key && entries.key?(face)
+            problems << "#{kind.section} entry '#{key}': '#{face}' keys the same file; keep one spelling"
+          end
+
           unless entry.is_a?(Hash)
             problems << "#{kind.section} entry '#{key}' must be a map of gating keys"
             next
@@ -218,8 +223,9 @@ module Rails
         end
       end
 
+      # Both spellings of a template-shipped file, since either gates it.
       def shipped_flat(repo_spec, kind, manifest)
-        BundlerArtifactDiscovery.flat_paths(repo_spec, kind, manifest: manifest).map { |p| File.basename(p) }
+        BundlerArtifactDiscovery.flat_keys(repo_spec, kind, manifest: manifest)
       end
 
       private_class_method :missing_manifest, :problems_in, :parse_root, :each_entry, :check_section_settings,

data/lib/rails/hyperdrive/resolve/prompt.md.erb

@@ -0,0 +1,47 @@
+You are resolving one file for the rails-hyperdrive installer.
+
+The file is a rails-hyperdrive-managed file of kind `<%= kind %>`; the new
+upstream version is shipped by <%= source %>.<% if previous_source && !previous_source.empty? %> The version the project
+last received came from <%= previous_source %>.<% end %> The project has edited its copy
+locally, so the local edits and the new upstream version have to be reconciled
+by hand.
+
+Inputs:
+
+- LOCAL:  <%= local %>
+  The project's current copy, including its local edits.
+- REMOTE: <%= remote %>
+  The new upstream copy, exactly as <%= source %> ships it. It contains none of
+  the local edits.
+<% if base -%>
+- BASE:   <%= base %>
+  The common ancestor: the upstream copy the local edits were made on top of.
+  Anything that differs between BASE and LOCAL is a local edit; anything that
+  differs between BASE and REMOTE is an upstream change.
+<% else -%>
+- BASE:   not available. There is no common ancestor to compare against, so
+  decide which differences are local edits by reading LOCAL and REMOTE.
+<% end -%>
+
+Write the reconciled file to:
+
+- MERGED: <%= merged %>
+  This is the same path as LOCAL, so you are editing the project's copy in
+  place.
+
+Rules:
+
+- Take every upstream change from REMOTE.
+- Keep every local customisation from LOCAL.
+- Where an upstream change and a local edit touch the same thing, keep the
+  local intent and express it in terms of the new upstream text.
+- Write a complete, valid file. No conflict markers, no commentary about the
+  merge, no placeholders, and nothing invented that appears in neither input.
+<% if kind == "skill" || kind == "agent" -%>
+- Keep the YAML frontmatter valid, and leave the `name:` line exactly as REMOTE
+  has it.
+<% end -%>
+- If you are not confident the result is correct, change nothing and exit with a
+  non-zero status.
+
+Exit 0 only when MERGED holds the reconciled file.

data/lib/rails/hyperdrive/resolve_prompt.rb

@@ -0,0 +1,42 @@
+require "erb"
+
+module Rails
+  module Hyperdrive
+    # Renders the text bound to $PROMPT for the resolver command. The binding
+    # is an ordinary object rather than a sandbox: a user-supplied template
+    # runs arbitrary Ruby with the privileges of whoever ran the sync.
+    module ResolvePrompt
+      DEFAULT_PATH = File.expand_path("resolve/prompt.md.erb", __dir__).freeze
+
+      KNOBS = %i[local remote base merged source previous_source kind].freeze
+
+      class Context
+        attr_reader(*KNOBS)
+
+        def initialize(local:, remote:, base:, merged:, source:, previous_source:, kind:)
+          @local = local
+          @remote = remote
+          @base = base
+          @merged = merged
+          @source = source
+          @previous_source = previous_source
+          @kind = kind
+        end
+
+        def template_binding
+          binding
+        end
+      end
+
+      module_function
+
+      def render(template, **knobs)
+        ERB.new(template, trim_mode: "-").result(Context.new(**knobs).template_binding)
+      end
+
+      def default_template
+        File.read(DEFAULT_PATH)
+      end
+    end
+  end
+end