quality_gate 0.1.0

data/lib/quality_gate/installation.rb

@@ -0,0 +1,1577 @@
+# frozen_string_literal: true
+
+require "erb"
+require "fileutils"
+require "pathname"
+require "rbconfig"
+require "tempfile"
+
+module QualityGate
+  module Installation # rubocop:disable Metrics/ModuleLength
+    FILES = %w[
+      .quality_gate.yml
+      .rubocop.yml
+      config/initializers/bullet.rb
+      config/initializers/strong_migrations.rb
+      test/test_helper.rb
+      .claude/hooks/quality_gate_fast.rb
+      .claude/hooks/quality_gate_verify_stop.rb
+      .claude/settings.json
+      CLAUDE.md
+      AGENTS.md
+    ].freeze
+    MARKER_START = "# quality_gate coverage — start"
+    MARKER_END = "# quality_gate coverage — end"
+    AGENT_CONTRACT_START = "<!-- quality_gate agent contract — start -->"
+    AGENT_CONTRACT_END = "<!-- quality_gate agent contract — end -->"
+    AGENT_TEMPLATE_PATHS = {
+      ".claude/hooks/quality_gate_fast.rb" => "quality_gate_fast.rb.tt",
+      ".claude/hooks/quality_gate_verify_stop.rb" => "quality_gate_verify_stop.rb.tt",
+      ".claude/settings.json" => "claude_settings.json.tt"
+    }.freeze
+    AGENT_CONTRACT_PATHS = %w[CLAUDE.md AGENTS.md].freeze
+    PRIOR_CLAUDE_SETTINGS = [
+      <<~'JSON'.b.freeze
+        {
+          "hooks": {
+            "PostToolUse": [
+              {
+                "matcher": "Edit|Write",
+                "hooks": [
+                  {
+                    "type": "command",
+                    "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/quality_gate_fast.rb",
+                    "args": [],
+                    "timeout": 30
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      JSON
+    ].freeze
+    STRONG_MIGRATIONS_PROVENANCE = "# Generated by Quality Gate."
+    HOOK_MODE = 0o755
+    DEFAULT_AGENT_ARTIFACT_MODE = 0o644
+    TEMPFILE_MODE = 0o600
+    # Descriptor-relative filesystem wrappers used to avoid cwd-sensitive publication.
+    module DirectoryOperations # rubocop:disable Metrics/ModuleLength
+      extend self
+
+      class Unsupported < StandardError; end
+
+      IMPORTER_MUTEX = Mutex.new
+      BUNDLED_REQUIRE_MUTEX = Mutex.new
+      LINK_FLAGS = 0
+      UNLINK_FLAGS = 0
+      O_DIRECTORY = File.const_defined?(:DIRECTORY) ? File::DIRECTORY : 0
+      O_NONBLOCK = File.const_defined?(:NONBLOCK) ? File::NONBLOCK : 0
+      O_CLOEXEC = File.const_defined?(:CLOEXEC) ? File::CLOEXEC : 0
+      RENAME_EXCLUSIVE_FLAGS = if RUBY_PLATFORM.include?("darwin")
+                                 { name: :renameatx_np, value: 0x0004 }
+                               elsif RUBY_PLATFORM.include?("linux")
+                                 { name: :renameat2, value: 0x0001 }
+                               end
+
+      def open_file(directory_io, entry_name, flags, mode = 0)
+        fd = syscall(:openat, "int openat(int, const char*, int, int)", directory_io.fileno, entry_name, flags, mode)
+        File.for_fd(fd).tap do |io|
+          io.close_on_exec = true if io.respond_to?(:close_on_exec=)
+        end
+      end
+
+      def open_directory(directory_io, entry_name, flags)
+        open_file(directory_io, entry_name, flags | O_DIRECTORY)
+      end
+
+      def mkdir(directory_io, entry_name, mode)
+        syscall(:mkdirat, "int mkdirat(int, const char*, unsigned short)", directory_io.fileno, entry_name, mode)
+      end
+
+      def link(directory_io, source_name, destination_name)
+        syscall(
+          :linkat,
+          "int linkat(int, const char*, int, const char*, int)",
+          directory_io.fileno,
+          source_name,
+          directory_io.fileno,
+          destination_name,
+          LINK_FLAGS
+        )
+      end
+
+      def rename_noreplace(directory_io, source_name, destination_name)
+        rename_flags = RENAME_EXCLUSIVE_FLAGS or raise Unsupported, "exclusive rename unavailable"
+
+        syscall(
+          rename_flags.fetch(:name),
+          rename_signature(rename_flags.fetch(:name)),
+          directory_io.fileno,
+          source_name,
+          directory_io.fileno,
+          destination_name,
+          rename_flags.fetch(:value)
+        )
+      end
+
+      def unlink(directory_io, entry_name)
+        syscall(:unlinkat, "int unlinkat(int, const char*, int)", directory_io.fileno, entry_name, UNLINK_FLAGS)
+      end
+
+      def fsync(io)
+        syscall(:fsync, "int fsync(int)", io.fileno)
+      end
+
+      def fchmod(io, mode)
+        syscall(:fchmod, "int fchmod(int, unsigned short)", io.fileno, mode)
+      end
+
+      private
+
+      def rename_signature(function_name)
+        return "int renameatx_np(int, const char*, int, const char*, unsigned int)" if function_name == :renameatx_np
+
+        "int renameat2(int, const char*, int, const char*, unsigned int)"
+      end
+
+      def syscall(function_name, signature, *arguments)
+        bind(function_name, signature)
+        result = importer.public_send(function_name, *arguments)
+        return result unless result == -1
+
+        raise SystemCallError.new(function_name.to_s, Fiddle.last_error)
+      rescue Unsupported
+        raise
+      rescue Fiddle::DLError, NotImplementedError => e
+        raise Unsupported, e.message
+      end
+
+      def bind(function_name, signature)
+        return if importer.respond_to?(function_name)
+
+        importer.extern(signature)
+      end
+
+      def importer
+        return @importer if defined?(@importer) && @importer
+
+        IMPORTER_MUTEX.synchronize do
+          @importer ||= begin
+            load_fiddle_importer!
+            Module.new.tap do |mod|
+              mod.extend(Fiddle::Importer)
+              mod.dlload(Fiddle.dlopen(nil))
+            end
+          end
+        end
+      end
+
+      def load_fiddle_importer!
+        return if defined?(Fiddle::Importer)
+        return load_bundled_fiddle_importer! if ruby4_bundle_fiddle?
+
+        require "fiddle/import"
+      rescue LoadError => e
+        raise Unsupported, e.message
+      end
+
+      def ruby4_bundle_fiddle?
+        RUBY_VERSION.start_with?("4.") && defined?(Bundler)
+      end
+
+      def load_bundled_fiddle_importer!
+        with_bundled_fiddle_require { load(fiddle_feature_paths.fetch("fiddle/import")) }
+      end
+
+      def with_bundled_fiddle_require
+        BUNDLED_REQUIRE_MUTEX.synchronize do
+          original_require = Kernel.instance_method(:require)
+          original_verbose = $VERBOSE
+          feature_paths = fiddle_feature_paths
+          $VERBOSE = nil
+          Kernel.module_eval do
+            define_method(:require) do |feature|
+              path = feature_paths[feature]
+              if path
+                return false if $LOADED_FEATURES.include?(path)
+
+                loaded = path.end_with?(".rb") ? load(path) : original_require.bind_call(self, path)
+                $LOADED_FEATURES << path unless $LOADED_FEATURES.include?(path)
+                loaded || true
+              else
+                original_require.bind_call(self, feature)
+              end
+            end
+          end
+          yield
+        ensure
+          Kernel.module_eval { define_method(:require, original_require) } if original_require
+          $VERBOSE = original_verbose
+        end
+      end
+
+      def fiddle_feature_paths
+        root = bundled_fiddle_root
+        {
+          "fiddle" => File.join(root, "fiddle.rb"),
+          "fiddle.so" => File.join(bundled_fiddle_extension_root, "fiddle.#{RbConfig::CONFIG.fetch("DLEXT")}"),
+          "fiddle/closure" => File.join(root, "fiddle", "closure.rb"),
+          "fiddle/function" => File.join(root, "fiddle", "function.rb"),
+          "fiddle/version" => File.join(root, "fiddle", "version.rb"),
+          "fiddle/import" => File.join(root, "fiddle", "import.rb"),
+          "fiddle/struct" => File.join(root, "fiddle", "struct.rb"),
+          "fiddle/cparser" => File.join(root, "fiddle", "cparser.rb"),
+          "fiddle/types" => File.join(root, "fiddle", "types.rb"),
+          "fiddle/value" => File.join(root, "fiddle", "value.rb"),
+          "fiddle/pack" => File.join(root, "fiddle", "pack.rb")
+        }
+      end
+
+      def bundled_fiddle_root
+        Dir[File.join(RbConfig::CONFIG["prefix"], "lib/ruby/gems/**/gems/fiddle-*/lib")].max or
+          raise Unsupported, "fiddle support is unavailable"
+      end
+
+      def bundled_fiddle_extension_root
+        root = bundled_fiddle_root
+        extension = File.join(root, "fiddle.#{RbConfig::CONFIG.fetch("DLEXT")}")
+        return root if File.file?(extension)
+
+        gem_name = File.basename(File.dirname(root))
+        gem_home = File.expand_path("../../..", root)
+        extension_api = if defined?(Gem) && Gem.respond_to?(:extension_api_version)
+                          Gem.extension_api_version
+                        else
+                          RbConfig::CONFIG.fetch("ruby_version")
+                        end
+        pattern = File.join(gem_home, "extensions", RbConfig::CONFIG.fetch("arch"), extension_api, gem_name)
+        native_root = pattern if File.file?(File.join(pattern, "fiddle.#{RbConfig::CONFIG.fetch("DLEXT")}"))
+        native_root or raise Unsupported, "fiddle native extension is unavailable"
+      end
+    end
+    PreparedTempfile = Data.define(
+      :file,
+      :name,
+      :path,
+      :relative_path,
+      :leaf_name,
+      :directory_io,
+      :directory_relative_path
+    ) do
+      def binmode = file.binmode
+      def write(content) = file.write(content)
+      def flush = file.flush
+      def fsync = file.fsync
+      def chmod(mode) = file.chmod(mode)
+      def stat = file.stat
+      def close = file.close
+    end
+    private_constant :STRONG_MIGRATIONS_PROVENANCE
+    private_constant :PreparedTempfile
+    private_constant :DirectoryOperations
+    private_constant :AGENT_TEMPLATE_PATHS, :AGENT_CONTRACT_PATHS
+    private_constant :PRIOR_CLAUDE_SETTINGS
+    private_constant :AGENT_CONTRACT_START, :AGENT_CONTRACT_END
+    private_constant :HOOK_MODE, :DEFAULT_AGENT_ARTIFACT_MODE, :TEMPFILE_MODE
+
+    def create_settings_file
+      return unless invoke_behavior?
+
+      install_template("quality_gate.yml.tt", ".quality_gate.yml")
+    end
+
+    def create_rules_file
+      return unless invoke_behavior?
+
+      install_template("rubocop.yml.tt", ".rubocop.yml")
+    end
+
+    def create_initializers
+      return unless invoke_behavior?
+      return if options[:skip_initializers]
+
+      install_template("bullet.rb.tt", "config/initializers/bullet.rb")
+      install_template("strong_migrations.rb.tt", "config/initializers/strong_migrations.rb")
+    end
+
+    def inject_coverage
+      return unless invoke_behavior?
+      return if options[:skip_coverage]
+
+      relative_path = test_helper_path
+      path = safe_destination_path(relative_path)
+      return unless path
+      return skip_missing_test_helper unless File.file?(path)
+
+      install_coverage(path, relative_path)
+    end
+
+    def create_agent_integration
+      return unless invoke_behavior?
+
+      unless options[:agents]
+        record(:skipped, "agent integration (pass --agents to install Claude hooks and contracts)")
+        return
+      end
+
+      install_template("quality_gate_fast.rb.tt", ".claude/hooks/quality_gate_fast.rb", mode: HOOK_MODE)
+      install_template(
+        "quality_gate_verify_stop.rb.tt",
+        ".claude/hooks/quality_gate_verify_stop.rb",
+        mode: HOOK_MODE
+      )
+      install_template("claude_settings.json.tt", ".claude/settings.json")
+      install_agent_contract("CLAUDE.md")
+      install_agent_contract("AGENTS.md")
+    end
+
+    def print_summary
+      return print_unsupported_behavior unless invoke_behavior?
+
+      say "Quality Gate install summary:"
+      print_group("Written", :written)
+      print_group("Unchanged", :unchanged)
+      print_group("Needs a person", :needs_person)
+      print_group("Skipped", :skipped)
+      say "Next: bundle exec quality_gate fast"
+    end
+
+    private
+
+    def invoke_behavior?
+      behavior == :invoke
+    end
+
+    def print_unsupported_behavior
+      say "Automatic removal is not supported. See the README installation undo instructions for manual removal."
+    end
+
+    def install_template(template_name, relative_path, mode: nil)
+      path = safe_destination_path(relative_path)
+      return unless path
+
+      install_existing_or_new_template(path, template_name, relative_path, mode:)
+    rescue SystemCallError, IOError, NotImplementedError, DirectoryOperations::Unsupported => e
+      raise unless agent_template_path?(relative_path)
+
+      handle_agent_artifact_failure(relative_path, rendered_template(template_name), e)
+    end
+
+    def compare_existing_template(path, content, relative_path, existing_file:, mode: nil)
+      existing = existing_file.fetch(:content)
+      if existing == content.b
+        record_existing_template(path, relative_path, existing:, mode:, status: existing_file.fetch(:status))
+      elsif prior_claude_settings?(relative_path, existing)
+        return record_pretend_skip(relative_path) if options[:pretend]
+
+        replace_content(path, content, relative_path, expected: existing_file)
+      else
+        say manual_instructions(relative_path, content)
+        record(:needs_person, relative_path)
+      end
+    end
+
+    def strong_migrations_provenance
+      STRONG_MIGRATIONS_PROVENANCE
+    end
+
+    def prior_claude_settings?(relative_path, content)
+      relative_path == ".claude/settings.json" && PRIOR_CLAUDE_SETTINGS.include?(content)
+    end
+
+    def install_agent_contract(relative_path)
+      path = safe_destination_path(relative_path)
+      return unless path
+
+      install_existing_or_new_agent_contract(path, relative_path)
+    rescue SystemCallError, IOError, NotImplementedError, DirectoryOperations::Unsupported => e
+      raise unless agent_contract_path?(relative_path)
+
+      handle_agent_artifact_failure(relative_path, agent_contract_section, e)
+    end
+
+    def strong_migrations_baseline
+      existing = @strong_migrations_existing_content
+      return newest_migration_version unless existing
+
+      baseline = existing[
+        /^[ \t]*StrongMigrations\.start_after[ \t]*=[ \t]*([0-9]+(?:_[0-9]+)*)[ \t]*(?:#.*)?\r?$/,
+        1
+      ]
+      return baseline if baseline
+      return if quality_gate_provenance?(existing)
+
+      newest_migration_version
+    end
+
+    def quality_gate_provenance?(content)
+      generated_headers = [
+        "#{STRONG_MIGRATIONS_PROVENANCE}\n",
+        "require \"strong_migrations\"\n\n#{STRONG_MIGRATIONS_PROVENANCE}\n",
+        "# frozen_string_literal: true\n\nrequire 'strong_migrations'\n\n#{STRONG_MIGRATIONS_PROVENANCE}\n"
+      ]
+
+      generated_headers.any? { content.start_with?(_1) }
+    end
+
+    def migration_version_literal(version)
+      digits = Integer(version.to_s.delete("_"), 10).to_s
+
+      digits.reverse.scan(/\d{1,3}/).join("_").reverse
+    end
+
+    def install_coverage(path, relative_path)
+      original = File.binread(path)
+      return record(:unchanged, relative_path) if original.include?(MARKER_START.b)
+      return record_pretend_skip(relative_path) if options[:pretend]
+
+      content = content_with_coverage(original)
+      return unless replace_coverage(path, content, relative_path)
+
+      record_coverage_postcondition(path, content, relative_path)
+    end
+
+    def replace_coverage(path, content, relative_path)
+      begin
+        atomic_replace(path, content)
+      rescue SystemCallError, IOError, NotImplementedError, DirectoryOperations::Unsupported => e
+        say "Warning: #{relative_path} could not be replaced safely: #{e.message}"
+        record(:needs_person, relative_path)
+        return false
+      end
+
+      true
+    end
+
+    def atomic_replace(path, content, mode: nil, expected: nil)
+      publish_mode = mode || File.lstat(path).mode & 0o7777
+      return atomic_replace_file(path, content, publish_mode) unless expected
+
+      with_verified_existing_file(path, expected, lock: File::LOCK_EX) do |io|
+        atomic_replace_verified(path, content, publish_mode, expected, io)
+      end
+    end
+
+    def record_coverage_postcondition(path, content, relative_path)
+      if lstat(path)&.file? && File.binread(path) == content
+        record(:written, relative_path)
+      else
+        say "Warning: #{relative_path} could not be written safely."
+        record(:needs_person, relative_path)
+      end
+    end
+
+    def content_with_coverage(original)
+      newline = host_newline(original)
+      bom, body = split_utf8_bom(original)
+      prologue, remainder = split_coverage_prologue(body)
+
+      bom + prologue + coverage_separator(prologue, newline) + coverage_block(newline) + remainder
+    end
+
+    def host_newline(content)
+      content.include?("\r\n".b) ? "\r\n".b : "\n".b
+    end
+
+    def split_coverage_prologue(content)
+      offset = coverage_insertion_offset(content)
+      [content.byteslice(0, offset), content.byteslice(offset..)]
+    end
+
+    def coverage_separator(prologue, newline)
+      prologue.empty? || prologue.end_with?("\n".b) ? "".b : newline
+    end
+
+    def split_utf8_bom(content)
+      bom = "\xEF\xBB\xBF".b
+      content.start_with?(bom) ? [bom, content.byteslice(bom.bytesize..)] : ["".b, content]
+    end
+
+    def coverage_insertion_offset(content)
+      lines = content.lines
+      index = lines.first&.start_with?("#!".b) ? 1 : 0
+      index = next_prologue_index(lines, index) while lines[index] && prologue_construct?(lines, index)
+      lines.first(index).sum(&:bytesize)
+    end
+
+    def prologue_construct?(lines, index)
+      prologue_line?(lines[index]) || complete_embedded_document?(lines, index)
+    end
+
+    def next_prologue_index(lines, index)
+      return index + 1 if prologue_line?(lines[index])
+
+      embedded_document_end(lines, index) + 1
+    end
+
+    def prologue_line?(line)
+      line.match?(/\A[ \t]*(?:#|\r?\n?\z)/)
+    end
+
+    def complete_embedded_document?(lines, index)
+      embedded_document_start?(lines[index]) && embedded_document_end(lines, index)
+    end
+
+    def embedded_document_start?(line)
+      line.match?(/\A=begin(?:[ \t]|\r?\n|\z)/)
+    end
+
+    def embedded_document_end(lines, index)
+      ((index + 1)...lines.length).find { lines[_1].match?(/\A=end(?:[ \t]|\r?\n|\z)/) }
+    end
+
+    def coverage_block(newline)
+      template = rendered_template("simplecov.rb.tt").b.gsub("\n".b, newline)
+      "#{MARKER_START}#{newline}#{template}#{MARKER_END}#{newline}".b
+    end
+
+    def create_agent_contract(path, relative_path)
+      content = agent_contract_section
+      create_template(path, content, relative_path)
+    end
+
+    def update_agent_contract(path, relative_path, existing_file:)
+      original = existing_file.fetch(:content)
+      newline = host_newline(original)
+      section = agent_contract_section(newline)
+      markers = agent_contract_markers(original, newline)
+      return record(:unchanged, relative_path) if markers == :exact
+      if markers.is_a?(Array)
+        return replace_agent_contract_markers(path, relative_path, original, section, existing_file)
+      end
+
+      say manual_instructions(relative_path, section)
+      record(:needs_person, relative_path)
+    end
+
+    def replace_agent_contract_markers(path, relative_path, original, section, existing_file)
+      replace_or_append_agent_contract(
+        path,
+        relative_path,
+        original:,
+        section:,
+        status: existing_file.fetch(:status)
+      )
+    end
+
+    def replace_or_append_agent_contract(path, relative_path, original:, section:, status:)
+      content = if original.empty?
+                  section
+                elsif (marker = single_agent_contract_marker(original))
+                  replace_agent_contract_content(original, section, marker)
+                else
+                  append_agent_contract(original, section)
+                end
+      return record_pretend_skip(relative_path) if options[:pretend]
+
+      expected = { content: original, status: status }
+      replace_content(path, content, relative_path, manual_content: section, expected:)
+    end
+
+    def append_agent_contract(original, section)
+      newline = host_newline(original)
+      separator = original.end_with?(newline) ? newline : "#{newline}#{newline}"
+
+      original + separator + section
+    end
+
+    def replace_agent_contract_content(original, section, marker)
+      prefix = original.byteslice(0, marker.fetch(:start))
+      suffix = original.byteslice(marker.fetch(:finish), original.bytesize - marker.fetch(:finish))
+
+      prefix + section + suffix.to_s
+    end
+
+    def replace_content(path, content, relative_path, manual_content: content, expected: nil)
+      begin
+        replaced = atomic_replace(path, content, mode: replacement_mode(expected), expected:)
+      rescue SystemCallError, IOError, NotImplementedError, DirectoryOperations::Unsupported => e
+        say "Warning: #{relative_path} could not be replaced safely: #{e.message}"
+        say manual_instructions(relative_path, manual_content)
+        record(:needs_person, relative_path)
+        return
+      end
+
+      return report_changed_agent_artifact(relative_path, manual_content) if replaced == false
+
+      record_template_postcondition(path, content, relative_path, manual_content:)
+    end
+
+    def agent_contract_section(newline = "\n".b)
+      rendered_template("agents_section.md.tt").b.gsub("\n".b, newline)
+    end
+
+    def agent_contract_markers(content, newline)
+      markers = all_agent_contract_markers(content)
+      return [] if markers.empty?
+      return :invalid if markers == :invalid
+
+      current = agent_contract_section(newline)
+      return :exact if markers.length == 1 && markers.first.fetch(:block) == current
+      return markers if markers.length == 1
+
+      :invalid
+    end
+
+    def single_agent_contract_marker(content)
+      all_agent_contract_markers(content).then do |markers|
+        markers.is_a?(Array) && markers.length == 1 ? markers.first : nil
+      end
+    end
+
+    def all_agent_contract_markers(content)
+      starts = exact_line_markers(content, AGENT_CONTRACT_START)
+      finishes = exact_line_markers(content, AGENT_CONTRACT_END)
+      return [] if starts.empty? && finishes.empty?
+      return :invalid unless starts.length == 1 && finishes.length == 1
+
+      [build_agent_contract_marker(content, starts.first, finishes.first)]
+    rescue ArgumentError
+      :invalid
+    end
+
+    def build_agent_contract_marker(content, start_marker, finish_marker)
+      raise ArgumentError unless start_marker.fetch(:start) < finish_marker.fetch(:start)
+
+      block_end = finish_marker.fetch(:finish)
+      {
+        start: start_marker.fetch(:start),
+        finish: block_end,
+        block: content.byteslice(start_marker.fetch(:start), block_end - start_marker.fetch(:start))
+      }
+    end
+
+    def exact_line_markers(content, marker)
+      markers = []
+      offset = 0
+      content.lines.each do |line|
+        text = line.delete_suffix("\n".b).delete_suffix("\r".b)
+        markers << { start: offset, finish: offset + line.bytesize } if text == marker.b
+        offset += line.bytesize
+      end
+
+      markers
+    end
+
+    def skip_missing_test_helper
+      say "Warning: Minitest coverage wiring skipped; test/test_helper.rb is missing."
+      record(:skipped, "test/test_helper.rb (missing; Minitest coverage wiring skipped)")
+    end
+
+    def record_pretend_skip(relative_path)
+      record(:skipped, "#{relative_path} (pretend)")
+    end
+
+    def create_template(path, content, relative_path, mode: nil)
+      return record_pretend_skip(relative_path) if options[:pretend]
+      return create_agent_artifact(path, content, relative_path, mode:) if agent_artifact_path?(relative_path)
+
+      create_new_file(relative_path, content)
+      record_template_postcondition(path, content, relative_path, mode:)
+    end
+
+    def install_existing_or_new_template(path, template_name, relative_path, mode: nil)
+      status = lstat(path)
+      return unsafe_destination(relative_path) if status && !status.file?
+
+      existing_file = existing_template_file(path, relative_path, status)
+      return unless existing_file
+
+      content = rendered_template(template_name, existing_content: existing_file.fetch(:content))
+
+      return compare_existing_template(path, content, relative_path, existing_file:, mode:) if status
+
+      create_template(path, content, relative_path, mode:)
+    end
+
+    def install_existing_or_new_agent_contract(path, relative_path)
+      status = lstat(path)
+      return unsafe_destination(relative_path) if status && !status.file?
+      return create_agent_contract(path, relative_path) unless status
+
+      existing_file = read_existing_agent_artifact(path, relative_path, status, agent_contract_section)
+      return unless existing_file
+
+      update_agent_contract(path, relative_path, existing_file:)
+    end
+
+    def print_group(heading, status)
+      say "#{heading}:"
+      results.fetch(status, []).each { say "  - #{_1}" }
+    end
+
+    def hook_log_filesystem_source
+      File.binread(template_path("hook_log_filesystem.rb.tt"))
+    end
+
+    def rendered_template(template_name, existing_content: nil)
+      source = template_path(template_name)
+      @strong_migrations_existing_content = existing_content
+      ERB.new(File.binread(source), trim_mode: "-").result(binding)
+    ensure
+      remove_instance_variable(:@strong_migrations_existing_content)
+    end
+
+    def record(status, relative_path)
+      results[status] << relative_path
+    end
+
+    def lstat(path)
+      File.lstat(path)
+    rescue Errno::ENOENT, Errno::ENOTDIR
+      nil
+    end
+
+    def record_template_postcondition(path, content, relative_path, mode: nil, manual_content: content)
+      apply_mode(path, mode) if mode && !agent_artifact_path?(relative_path)
+
+      if safe_postcondition_match?(path, content, mode)
+        record(:written, relative_path)
+      else
+        report_postcondition_mismatch(relative_path, manual_content)
+      end
+    rescue SystemCallError, IOError, NotImplementedError, DirectoryOperations::Unsupported => e
+      raise unless agent_artifact_path?(relative_path)
+
+      handle_agent_artifact_failure(relative_path, manual_content, e)
+    end
+
+    def safe_destination_path(relative_path)
+      root = Pathname.new(destination_root).expand_path
+      return unsafe_destination(relative_path) unless lstat(root.to_s)&.directory?
+
+      candidate = root.join(relative_path).cleanpath
+      return unsafe_destination(relative_path) unless contained_by?(candidate, root)
+      return unsafe_destination(relative_path) unless safe_path_components?(root, relative_path)
+
+      candidate.to_s
+    rescue Errno::ELOOP, Errno::ENOENT, Errno::ENOTDIR
+      unsafe_destination(relative_path)
+    end
+
+    def contained_by?(path, root)
+      path == root || path.to_s.start_with?("#{root}#{File::SEPARATOR}")
+    end
+
+    def safe_path_components?(root, relative_path)
+      cursor = root
+      segments = Pathname.new(relative_path).each_filename.to_a
+      segments.each_with_index.all? do |segment, index|
+        cursor = cursor.join(segment)
+        valid_path_component?(lstat(cursor.to_s), destination: index == segments.length - 1)
+      end
+    end
+
+    def valid_path_component?(status, destination:)
+      !status || (!status.symlink? && (destination ? status.file? : status.directory?))
+    end
+
+    def unsafe_destination(relative_path)
+      say "Warning: #{relative_path} is not a safe path inside the destination root and was not changed."
+      record(:needs_person, relative_path)
+      nil
+    end
+
+    def record_existing_template(path, relative_path, existing:, mode: nil, status: nil)
+      return record(:unchanged, relative_path) unless mode_repair_needed?(status, mode)
+      return record_pretend_skip(relative_path) if options[:pretend]
+      return unless apply_mode_safely(path, mode, existing, status, relative_path)
+
+      return record(:written, relative_path) if mode_matches?(path, mode)
+
+      say "Warning: #{relative_path} could not be written safely."
+      record(:needs_person, relative_path)
+    rescue SystemCallError, IOError, NotImplementedError, DirectoryOperations::Unsupported => e
+      handle_agent_artifact_failure(relative_path, agent_template_content(relative_path), e)
+    end
+
+    def apply_mode_safely(path, mode, existing, status, relative_path)
+      expected = { content: existing, status: status }
+
+      verify_existing_content(
+        path,
+        relative_path,
+        agent_template_content(relative_path),
+        expected:,
+        lock: File::LOCK_EX
+      ) { repair_existing_mode(path, io: _1, mode:) }
+    end
+
+    def apply_mode(path, mode)
+      File.chmod(mode, path)
+    end
+
+    def mode_matches?(path, mode)
+      return true unless mode
+
+      (File.stat(path).mode & 0o777) == mode
+    end
+
+    def exact_mode?(status, mode)
+      status && (status.mode & 0o777) == mode
+    end
+
+    def verify_existing_content(path, relative_path, manual_content, expected:, lock: File::LOCK_SH)
+      matched = with_verified_existing_file(path, expected, lock:) do |io|
+        block_given? ? yield(io) : true
+      end
+      return matched unless matched == false
+
+      report_changed_agent_artifact(relative_path, manual_content)
+      false
+    rescue SystemCallError, IOError, NotImplementedError, DirectoryOperations::Unsupported => e
+      handle_agent_artifact_failure(relative_path, manual_content, e)
+      false
+    end
+
+    def with_verified_existing_file(path, expected, lock:)
+      context = verified_existing_context(path)
+      expected_content = expected.fetch(:content)
+      expected_status = expected.fetch(:status)
+
+      with_anchored_parent_directory(context, create_missing: false) do |anchored_context|
+        with_locked_verified_io(anchored_context, expected_content, expected_status, lock) do |io|
+          yield io if block_given?
+        end
+      end
+    rescue Errno::ENOENT, Errno::ENOTDIR, Errno::ELOOP
+      false
+    end
+
+    def verified_existing_context(path)
+      relative_path_from_destination(path)
+    end
+
+    def with_locked_verified_io(context, expected_content, expected_status, lock)
+      io = open_anchored_file(context, context.fetch(:leaf_name))
+      io.binmode
+      io.flock(lock)
+      return false unless verified_existing_file?(context, io, expected_content, expected_status)
+
+      block_given? ? yield(io) : true
+    ensure
+      unlock_file(io) if io
+      io&.close
+    end
+
+    def verify_read_flags
+      flags = File::RDONLY
+      flags |= File::NOFOLLOW if File.const_defined?(:NOFOLLOW)
+      flags |= DirectoryOperations::O_NONBLOCK
+      flags |= DirectoryOperations::O_CLOEXEC
+      flags
+    end
+
+    def same_file_identity?(*stats)
+      stats.all? { identity_target?(_1) } && stats.map { file_identity(_1) }.uniq.one?
+    end
+
+    def same_file_state?(status, expected_status)
+      file_state(status) == file_state(expected_status)
+    end
+
+    def file_identity(status)
+      [status.dev, status.ino]
+    end
+
+    def file_state(status)
+      [status.mode, status.size, status.mtime.to_r]
+    end
+
+    def handle_agent_artifact_failure(relative_path, manual_content, error)
+      say "Warning: #{relative_path} could not be read safely: #{error.message}"
+      say manual_instructions(relative_path, manual_content) if manual_content
+      record(:needs_person, relative_path)
+    end
+
+    def repair_existing_mode(path, io:, mode:)
+      directory_operations.fchmod(io, mode)
+      updated_status = io.stat
+      current_status = lstat(path)
+
+      same_file_identity?(updated_status, current_status) && exact_mode?(updated_status, mode)
+    end
+
+    def report_changed_agent_artifact(relative_path, manual_content)
+      say "Warning: #{relative_path} changed before it could be updated safely."
+      say manual_instructions(relative_path, manual_content)
+      record(:needs_person, relative_path)
+    end
+
+    def verified_existing_file?(context, io, expected_content, expected_status)
+      opened_status = io.stat
+      current_status = anchored_lstat(context, context.fetch(:leaf_name))
+
+      same_file_identity?(opened_status, current_status, expected_status) &&
+        same_file_state?(opened_status, expected_status) &&
+        io.tap(&:rewind).read == expected_content.b
+    end
+
+    def identity_target?(status)
+      status && (status.file? || status.directory?)
+    end
+
+    def read_existing_content(path, status)
+      File.binread(path) if status
+    end
+
+    def existing_template_file(path, relative_path, status)
+      unless status && agent_artifact_path?(relative_path)
+        return { content: read_existing_content(path, status), status: status }
+      end
+
+      read_existing_agent_artifact(path, relative_path, status, agent_template_content(relative_path))
+    end
+
+    def read_existing_agent_artifact(_path, relative_path, status, manual_content)
+      content = anchored_existing_agent_artifact_content(relative_path, status, manual_content)
+      { content:, status: } if content
+    rescue Errno::ENOENT, Errno::ENOTDIR, Errno::ELOOP
+      report_changed_agent_artifact(relative_path, manual_content)
+      nil
+    rescue SystemCallError, IOError, NotImplementedError, DirectoryOperations::Unsupported => e
+      handle_agent_artifact_failure(relative_path, manual_content, e)
+      nil
+    end
+
+    def anchored_existing_agent_artifact_content(relative_path, status, manual_content)
+      with_anchored_parent_directory(relative_path, create_missing: false) do |context|
+        read_existing_agent_artifact_content(context, relative_path, status, manual_content)
+      end
+    end
+
+    def read_existing_agent_artifact_content(context, relative_path, status, manual_content)
+      parent_status = context.fetch(:directory_io).stat
+      unless current_parent_matches?(context, parent_status)
+        return changed_agent_artifact(relative_path, manual_content)
+      end
+
+      read_existing_agent_file_content(context, relative_path, status, manual_content, parent_status)
+    end
+
+    def read_existing_agent_file_content(context, relative_path, status, manual_content, parent_status)
+      open_anchored_file(context, context.fetch(:leaf_name)) do |io|
+        io.binmode
+        content = io.tap(&:rewind).read
+        unless final_existing_agent_artifact_snapshot_valid?(context, io, content, status, parent_status)
+          return changed_agent_artifact(relative_path, manual_content)
+        end
+
+        content
+      end
+    end
+
+    def final_existing_agent_artifact_snapshot_valid?(context, io, content, status, parent_status)
+      current_parent_matches?(context, parent_status) &&
+        existing_agent_artifact_matches?(context, io, status) &&
+        io.tap(&:rewind).read == content.b
+    end
+
+    def existing_agent_artifact_matches?(context, io, status)
+      opened_status = io.stat
+      current_status = anchored_lstat(context, context.fetch(:leaf_name))
+
+      same_file_identity?(opened_status, current_status, status) && same_file_state?(opened_status, status)
+    end
+
+    def changed_agent_artifact(relative_path, manual_content)
+      report_changed_agent_artifact(relative_path, manual_content)
+      nil
+    end
+
+    def agent_template_content(relative_path)
+      rendered_template(AGENT_TEMPLATE_PATHS.fetch(relative_path))
+    end
+
+    def mode_repair_needed?(status, mode)
+      mode && !exact_mode?(status, mode)
+    end
+
+    def create_agent_artifact(path, content, relative_path, mode: nil)
+      created = atomic_create(path, content, relative_path, mode)
+      return report_postcondition_mismatch(relative_path, content) if created == false
+
+      record_template_postcondition(path, content, relative_path, mode:)
+    rescue SystemCallError, IOError, NotImplementedError, DirectoryOperations::Unsupported => e
+      handle_agent_artifact_write_failure(relative_path, content, e)
+    end
+
+    def atomic_create(path, content, relative_path, mode)
+      with_prepared_tempfile(path, content, relative_path, mode) do |tempfile|
+        return false unless current_parent_directory?(tempfile)
+
+        published = publish_new_tempfile(path, tempfile, relative_path, content)
+        return true if visible_postcondition_matches?(path, content, mode, tempfile.directory_io.stat)
+
+        cleanup_published_leaf(tempfile, published)
+        false
+      end
+    end
+
+    def atomic_replace_verified(path, content, mode, expected, io)
+      with_prepared_tempfile(path, content, relative_path_from_destination(path), mode) do |tempfile|
+        return claim_and_publish_existing_file(path, tempfile, expected, io, content, mode)
+      end
+    end
+
+    def with_prepared_tempfile(_path, content, relative_path, mode)
+      with_anchored_parent_directory(relative_path, create_missing: true) do |context|
+        tempfile = create_anchored_tempfile(context, relative_path)
+        prepare_tempfile(tempfile, content, relative_path, mode)
+        yield tempfile
+      ensure
+        cleanup_error = cleanup_tempfile(tempfile)
+        raise cleanup_error if cleanup_error && !$ERROR_INFO
+      end
+    end
+
+    def prepare_tempfile(tempfile, content, relative_path, mode)
+      tempfile.binmode
+      write_tempfile_content(tempfile, content, relative_path)
+      tempfile.flush
+      directory_operations.fsync(tempfile.file)
+      directory_operations.fchmod(tempfile.file, published_mode(mode))
+      directory_operations.fsync(tempfile.file)
+    end
+
+    def write_tempfile_content(tempfile, content, _relative_path)
+      tempfile.write(content)
+    end
+
+    def publish_new_tempfile(_path, tempfile, _relative_path, content)
+      linked = false
+      expected = prepared_entry_token(tempfile, content)
+      directory_operations.link(tempfile.directory_io, tempfile.name, tempfile.leaf_name)
+      linked = true
+      verify_published_leaf!(tempfile, expected)
+      directory_operations.fsync(tempfile.directory_io)
+      expected
+    rescue SystemCallError, IOError, NotImplementedError, DirectoryOperations::Unsupported
+      cleanup_published_leaf(tempfile, expected) if linked && expected
+      raise
+    end
+
+    def cleanup_tempfile(tempfile)
+      return unless tempfile
+
+      temp_status = nil
+      close_error = nil
+
+      begin
+        temp_status = tempfile.stat
+      rescue IOError, SystemCallError, NotImplementedError, DirectoryOperations::Unsupported
+        nil
+      ensure
+        begin
+          tempfile.close
+        rescue IOError, SystemCallError => e
+          close_error = e
+        end
+      end
+
+      safe_unlink_tempfile(tempfile, temp_status)
+      close_error
+    end
+
+    def safe_unlink_tempfile(tempfile, expected_status)
+      cleanup_owned_entry(
+        tempfile,
+        entry_name: tempfile.name,
+        expected: { status: expected_status },
+        restore_to: tempfile.name,
+        relative_path: tempfile.relative_path,
+        validate_identity: false,
+        result: nil,
+        report_failures: false
+      )
+    end
+
+    def atomic_replace_file(path, content, mode)
+      Tempfile.create([".quality_gate-", ".tmp"], File.dirname(path)) do |tempfile|
+        tempfile.binmode
+        tempfile.write(content)
+        tempfile.flush
+        tempfile.fsync
+        tempfile.chmod(mode)
+        File.rename(tempfile.path, path)
+      end
+    end
+
+    def replacement_mode(expected)
+      expected && (expected.fetch(:status).mode & 0o7777)
+    end
+
+    def safe_postcondition_match?(path, content, mode)
+      lstat(path)&.file? && File.binread(path) == content.b && mode_matches?(path, mode)
+    end
+
+    def report_postcondition_mismatch(relative_path, manual_content)
+      say "Warning: #{relative_path} could not be written safely."
+      say manual_instructions(relative_path, manual_content) if agent_artifact_path?(relative_path)
+      record(:needs_person, relative_path)
+    end
+
+    def handle_agent_artifact_write_failure(relative_path, manual_content, error)
+      say "Warning: #{relative_path} could not be written safely: #{error.message}"
+      say manual_instructions(relative_path, manual_content)
+      record(:needs_person, relative_path)
+    end
+
+    def claim_and_publish_existing_file(path, tempfile, expected, io, content, mode)
+      claim_name = claim_entry_name(tempfile.leaf_name)
+      claimed = false
+      return false unless current_parent_directory?(tempfile)
+
+      claimed = claim_current_leaf(tempfile, claim_name)
+      return false unless claimed_current_leaf?(tempfile, expected, claim_name)
+
+      published_status = publish_new_tempfile(path, tempfile, tempfile.relative_path, content)
+      if visible_postcondition_matches?(path, content, mode, tempfile.directory_io.stat)
+        return cleanup_claim(tempfile, claim_name, expected, true)
+      end
+
+      cleanup_published_leaf(tempfile, published_status)
+      rollback_claim(tempfile, claim_name, expected)
+    rescue Errno::EEXIST
+      rollback_claim(tempfile, claim_name, expected) if claimed
+    rescue SystemCallError, IOError, NotImplementedError, DirectoryOperations::Unsupported
+      rollback_claim(tempfile, claim_name, expected) if claimed
+      raise
+    ensure
+      io&.tap(&:rewind)
+    end
+
+    def claimed_current_leaf?(tempfile, expected, claim_name)
+      directory_operations.fsync(tempfile.directory_io)
+      unless claimed_entry_matches?(tempfile, claim_name, expected)
+        return restore_claimed_current_leaf(tempfile, claim_name)
+      end
+
+      return restore_claimed_current_leaf(tempfile, claim_name) unless current_parent_directory?(tempfile)
+
+      true
+    end
+
+    def claim_current_leaf(tempfile, claim_name)
+      directory_operations.rename_noreplace(tempfile.directory_io, tempfile.leaf_name, claim_name)
+      true
+    end
+
+    def rollback_claim(tempfile, claim_name, expected)
+      return retain_recovery_copy(tempfile, claim_name) unless current_parent_directory?(tempfile)
+      return retain_recovery_copy(tempfile, claim_name) if anchored_lstat(tempfile, tempfile.leaf_name)
+
+      quarantine_name = quarantine_entry_name(claim_name)
+      quarantine = quarantine_entry(tempfile, claim_name, quarantine_name)
+      return false unless quarantine
+      return retain_recovery_copy(tempfile, quarantine) unless entry_matches_expected?(tempfile, quarantine, expected)
+
+      restore_quarantined_entry(tempfile, quarantine, tempfile.leaf_name, tempfile.relative_path, report: false)
+    rescue SystemCallError, IOError, NotImplementedError, DirectoryOperations::Unsupported
+      retain_recovery_copy(tempfile, current_recovery_name(tempfile, quarantine_name, claim_name))
+    end
+
+    def cleanup_claim(tempfile, claim_name, expected, result)
+      cleanup_owned_entry(
+        tempfile,
+        entry_name: claim_name,
+        expected:,
+        restore_to: claim_name,
+        relative_path: tempfile.relative_path,
+        validate_identity: true,
+        result:,
+        report_failures: true
+      )
+    end
+
+    def restore_claimed_current_leaf(tempfile, claim_name)
+      current_name = claim_name
+      return retain_recovery_copy(tempfile, claim_name) unless current_parent_directory?(tempfile)
+      return retain_recovery_copy(tempfile, claim_name) if anchored_lstat(tempfile, tempfile.leaf_name)
+
+      directory_operations.rename_noreplace(tempfile.directory_io, claim_name, tempfile.leaf_name)
+      current_name = tempfile.leaf_name
+      directory_operations.fsync(tempfile.directory_io)
+      false
+    rescue Errno::EEXIST
+      retain_recovery_copy(tempfile, claim_name)
+    rescue IOError, SystemCallError, NotImplementedError, DirectoryOperations::Unsupported
+      retain_recovery_copy(tempfile, current_recovery_name(tempfile, current_name, claim_name))
+    end
+
+    def claimed_entry_matches?(tempfile, claim_name, expected)
+      claim_status = anchored_lstat(tempfile, claim_name)
+      return false unless same_file_identity?(claim_status, expected.fetch(:status))
+      return false unless same_file_state?(claim_status, expected.fetch(:status))
+
+      open_anchored_file(tempfile, claim_name) do |claim_io|
+        claim_io.binmode
+        claim_io.read == expected.fetch(:content).b
+      end
+    end
+
+    def current_parent_directory?(tempfile)
+      current = lstat(parent_directory_path(tempfile.directory_relative_path))
+      return false unless current&.directory?
+
+      same_file_identity?(current, tempfile.directory_io.stat)
+    end
+
+    def create_anchored_tempfile(context, relative_path)
+      temp_name = temporary_entry_name
+      file = directory_operations.open_file(
+        context.fetch(:directory_io),
+        temp_name,
+        tempfile_write_flags,
+        TEMPFILE_MODE
+      )
+      tempfile = PreparedTempfile.new(**anchored_tempfile_attributes(context, file, temp_name, relative_path))
+      directory_operations.fchmod(file, TEMPFILE_MODE)
+      tempfile
+    rescue SystemCallError, IOError, NotImplementedError, DirectoryOperations::Unsupported
+      cleanup_tempfile(tempfile) if tempfile
+      raise
+    end
+
+    def anchored_tempfile_attributes(context, file, temp_name, relative_path)
+      {
+        file:,
+        name: temp_name,
+        path: File.join(parent_directory_path(context.fetch(:directory_relative_path)), temp_name),
+        relative_path:,
+        leaf_name: context.fetch(:leaf_name),
+        directory_io: context.fetch(:directory_io),
+        directory_relative_path: context.fetch(:directory_relative_path)
+      }
+    end
+
+    def with_anchored_parent_directory(relative_path, create_missing:)
+      segments = Pathname.new(relative_path).each_filename.to_a
+      leaf_name = segments.pop
+
+      File.open(destination_root, directory_read_flags) do |root_io|
+        raise Errno::ENOTDIR, destination_root unless root_io.stat.directory?
+
+        traverse_anchored_directories(root_io, segments, create_missing:, traversed: []) do |directory_io, traversed|
+          yield({ directory_io:, directory_relative_path: traversed.join(File::SEPARATOR), leaf_name: })
+        end
+      end
+    end
+
+    def traverse_anchored_directories(directory_io, segments, create_missing:, traversed:, &block)
+      return yield(directory_io, traversed) if segments.empty?
+
+      next_segment = segments.first
+      child_io = open_or_create_child_directory(directory_io, next_segment, create_missing:)
+      traverse_next_anchored_directory(child_io, segments, create_missing:, traversed:, next_segment:, &block)
+    ensure
+      child_io&.close
+    end
+
+    def traverse_next_anchored_directory(child_io, segments, create_missing:, traversed:, next_segment:, &block)
+      traverse_anchored_directories(
+        child_io,
+        segments.drop(1),
+        create_missing:,
+        traversed: traversed + [next_segment],
+        &block
+      )
+    end
+
+    def open_or_create_child_directory(directory_io, segment, create_missing:)
+      directory_operations.open_directory(directory_io, segment, verify_read_flags)
+    rescue Errno::ENOENT
+      raise unless create_missing
+
+      directory_operations.mkdir(directory_io, segment, 0o755)
+      directory_operations.fsync(directory_io)
+      retry
+    end
+
+    def open_anchored_file(context, entry_name)
+      io = directory_operations.open_file(directory_io_for(context), entry_name, verify_read_flags)
+      return io unless block_given?
+
+      yield io
+    ensure
+      io&.close if block_given?
+    end
+
+    def anchored_lstat(context, entry_name)
+      open_anchored_file(context, entry_name, &:stat)
+    rescue Errno::ENOENT, Errno::ENOTDIR, Errno::ELOOP
+      nil
+    end
+
+    def parent_directory_path(relative_directory)
+      return destination_root if relative_directory.empty?
+
+      File.join(destination_root, relative_directory)
+    end
+
+    def relative_path_from_destination(path)
+      Pathname.new(path).relative_path_from(Pathname.new(destination_root)).to_s
+    end
+
+    def temporary_entry_name
+      ".quality_gate-#{Process.pid}-#{rand(1_000_000)}.tmp"
+    end
+
+    def claim_entry_name(leaf_name)
+      ".quality_gate-#{leaf_name.tr(File::SEPARATOR, "_")}-#{Process.pid}-#{rand(1_000_000)}.claim"
+    end
+
+    def directory_operations
+      DirectoryOperations
+    end
+
+    def directory_read_flags
+      verify_read_flags | DirectoryOperations::O_DIRECTORY
+    end
+
+    def tempfile_write_flags
+      flags = File::WRONLY | File::CREAT | File::EXCL
+      flags |= File::NOFOLLOW if File.const_defined?(:NOFOLLOW)
+      flags |= DirectoryOperations::O_CLOEXEC
+      flags
+    end
+
+    def published_mode(mode)
+      mode || DEFAULT_AGENT_ARTIFACT_MODE
+    end
+
+    def visible_postcondition_matches?(path, content, mode, expected_parent_status = nil)
+      current_parent_directory_for?(path, expected_parent_status) && safe_postcondition_match?(path, content, mode)
+    end
+
+    def current_parent_matches?(context, expected_parent_status)
+      current_status = lstat(parent_directory_path(context.fetch(:directory_relative_path)))
+      same_file_identity?(current_status, expected_parent_status)
+    end
+
+    def current_parent_directory_for?(path, expected_parent_status = nil)
+      current = lstat(File.dirname(path))
+      return false unless current&.directory?
+
+      expected_parent_status ? same_file_identity?(current, expected_parent_status) : true
+    end
+
+    def cleanup_published_leaf(tempfile, expected)
+      return unless expected
+
+      cleanup_owned_entry(
+        tempfile,
+        entry_name: tempfile.leaf_name,
+        expected:,
+        restore_to: tempfile.leaf_name,
+        relative_path: tempfile.relative_path,
+        validate_identity: true,
+        result: nil,
+        report_failures: true
+      )
+    end
+
+    def cleanup_owned_entry(
+      tempfile,
+      entry_name:,
+      expected:,
+      restore_to:,
+      relative_path:,
+      validate_identity:,
+      result:,
+      report_failures: true
+    )
+      quarantine_name = quarantine_entry_name(entry_name)
+      quarantine = quarantine_entry(tempfile, entry_name, quarantine_name)
+      return result unless quarantine
+      return unlink_quarantined_entry(tempfile, quarantine, relative_path, result) unless validate_identity
+
+      if entry_matches_expected?(tempfile, quarantine, expected)
+        return delete_quarantined_entry(tempfile, quarantine, expected, relative_path, result)
+      end
+
+      cleanup_identity_mismatch(
+        tempfile,
+        quarantine,
+        restore_to,
+        relative_path,
+        result
+      )
+    rescue Errno::ENOENT
+      result
+    rescue IOError, SystemCallError, NotImplementedError, DirectoryOperations::Unsupported => e
+      current_name = current_recovery_name(tempfile, quarantine_name, entry_name)
+      return handle_cleanup_failure(tempfile, current_name, relative_path, e, result, report_failures) if current_name
+
+      raise unless report_failures
+
+      report_cleanup_failure(relative_path, e)
+      cleanup_failure_result(result)
+    end
+
+    def cleanup_identity_mismatch(tempfile, quarantine, restore_to, relative_path, result)
+      restored = restore_quarantined_entry(tempfile, quarantine, restore_to, relative_path, report: false)
+      return cleanup_failure_result(result) if restored == false
+
+      restored
+    end
+
+    def quarantine_entry(tempfile, entry_name, quarantine_name = quarantine_entry_name(entry_name))
+      directory_operations.rename_noreplace(tempfile.directory_io, entry_name, quarantine_name)
+      directory_operations.fsync(tempfile.directory_io)
+      quarantine_name
+    rescue Errno::ENOENT
+      nil
+    end
+
+    def delete_quarantined_entry(tempfile, quarantine_name, expected, relative_path, result)
+      unless entry_matches_expected?(tempfile, quarantine_name, expected)
+        return retain_recovery_copy(tempfile, quarantine_name)
+      end
+
+      unlink_quarantined_entry(tempfile, quarantine_name, relative_path, result)
+    end
+
+    def unlink_quarantined_entry(tempfile, quarantine_name, _relative_path, result)
+      directory_operations.unlink(tempfile.directory_io, quarantine_name)
+      directory_operations.fsync(tempfile.directory_io)
+      result
+    end
+
+    def restore_quarantined_entry(tempfile, quarantine_name, restore_to, relative_path, report:)
+      current_name = quarantine_name
+      if anchored_lstat(tempfile, restore_to)
+        retain_recovery_copy(tempfile, quarantine_name)
+      else
+        directory_operations.rename_noreplace(tempfile.directory_io, quarantine_name, restore_to)
+        current_name = restore_to
+        directory_operations.fsync(tempfile.directory_io)
+        report_cleanup_failure(relative_path, RuntimeError.new("#{restore_to} changed before cleanup")) if report
+        false
+      end
+    rescue Errno::EEXIST
+      retain_recovery_copy(tempfile, quarantine_name)
+    rescue IOError, SystemCallError, NotImplementedError, DirectoryOperations::Unsupported
+      retain_recovery_copy(tempfile, current_recovery_name(tempfile, current_name, quarantine_name))
+    end
+
+    def entry_matches_expected?(context, entry_name, expected)
+      entry_status = anchored_lstat(context, entry_name)
+      return false unless same_file_identity?(entry_status, expected.fetch(:status))
+      return false unless same_file_state?(entry_status, expected.fetch(:status))
+      return true unless expected[:content]
+
+      open_anchored_file(context, entry_name) do |entry_io|
+        entry_io.binmode
+        entry_io.read == expected.fetch(:content).b
+      end
+    end
+
+    def entry_matches_expected_identity?(context, entry_name, expected_status)
+      entry_status = anchored_lstat(context, entry_name)
+      same_file_identity?(entry_status, expected_status)
+    end
+
+    def prepared_entry_token(tempfile, content)
+      { status: tempfile.stat, content: content.b }
+    end
+
+    def verify_published_leaf!(tempfile, expected)
+      return if entry_matches_expected?(tempfile, tempfile.leaf_name, expected)
+
+      raise IOError, "#{tempfile.relative_path} changed before it could be published safely"
+    end
+
+    def retain_recovery_copy(tempfile, claim_name)
+      status = anchored_lstat(tempfile, claim_name)
+      say recovery_warning(tempfile.relative_path, claim_name, status)
+      false
+    end
+
+    def current_recovery_name(tempfile, current_name, fallback_name)
+      return current_name if anchored_lstat(tempfile, current_name)
+
+      return fallback_name if anchored_lstat(tempfile, fallback_name)
+
+      nil
+    end
+
+    def handle_cleanup_failure(tempfile, current_name, relative_path, error, result, report_failures)
+      retain_recovery_copy(tempfile, current_name)
+      raise error unless report_failures
+
+      cleanup_failure_result(result)
+    rescue IOError, SystemCallError, NotImplementedError, DirectoryOperations::Unsupported
+      raise error unless report_failures
+
+      report_cleanup_failure(relative_path, error)
+      cleanup_failure_result(result)
+    end
+
+    def cleanup_failure_result(result)
+      result == true ? false : result
+    end
+
+    def recovery_warning(relative_path, claim_name, status)
+      identity = status ? " (dev=#{status.dev} ino=#{status.ino})" : ""
+      "Warning: recovery copy for #{relative_path} was retained as #{claim_name}#{identity}."
+    end
+
+    def report_cleanup_failure(relative_path, error)
+      say "Warning: temporary cleanup for #{relative_path} could not be completed safely: #{error.message}"
+      record(:needs_person, relative_path)
+    end
+
+    def quarantine_entry_name(entry_name)
+      ".quality_gate-#{entry_name.tr(File::SEPARATOR, "_")}-#{Process.pid}-#{rand(1_000_000)}.quarantine"
+    end
+
+    def directory_io_for(context)
+      context.respond_to?(:directory_io) ? context.directory_io : context.fetch(:directory_io)
+    end
+
+    def unlock_file(io)
+      io.flock(File::LOCK_UN)
+    rescue SystemCallError, IOError
+      nil
+    end
+
+    def agent_template_path?(relative_path)
+      AGENT_TEMPLATE_PATHS.key?(relative_path)
+    end
+
+    def agent_contract_path?(relative_path)
+      AGENT_CONTRACT_PATHS.include?(relative_path)
+    end
+
+    def agent_artifact_path?(relative_path)
+      agent_template_path?(relative_path) || agent_contract_path?(relative_path)
+    end
+
+    def manual_instructions(relative_path, content)
+      "Use these lines manually for #{relative_path}:\n#{content}"
+    end
+
+    def results
+      @results ||= Hash.new { |statuses, status| statuses[status] = [] }
+    end
+
+    def newest_migration_version
+      migration_directory = File.join(destination_root, "db/migrate")
+      versions = Dir.glob("*.rb", base: migration_directory).filter_map do |filename|
+        path = File.join(migration_directory, filename)
+        next unless File.file?(path)
+
+        prefix = filename[/\A(\d+)_/, 1]
+        Integer(prefix, 10) if prefix
+      end
+
+      versions.max
+    end
+
+    def template_path(template_name)
+      File.join(template_source_root, template_for(template_name))
+    end
+  end
+end