reanimator 0.1.0

data/lib/reanimator/detectors/operational_proof.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Detectors
+    # Detects high-value proof-of-life evaluators (specification section 06:
+    # Operational proof and Contracts). Health endpoints, doctor commands, and
+    # smoke scripts are the cheapest, most trustworthy evidence that software
+    # actually runs, so they are called out for promotion into acceptance
+    # criteria.
+    class OperationalProof < Base
+      SMOKE_SCRIPTS = ["bin/smoke", "bin/doctor", "script/smoke", "bin/health"].freeze
+      HEALTH_ROUTE = %r{(get\s+['"]/(up|health|healthz)['"]|/up\b)}
+
+      def detect
+        facts = []
+
+        if (script = SMOKE_SCRIPTS.find { |s| repository.exist?(s) })
+          facts << fact(:smoke_script, category: :operational_proof,
+            claim: "A smoke/doctor script is available: #{script}.",
+            value: script, confidence: :high, source: script, method: :file_present)
+        end
+
+        if health_endpoint?
+          facts << fact(:health_endpoint, category: :operational_proof,
+            claim: "Exposes a health endpoint suitable for a boot smoke test.",
+            confidence: :medium, source: "routes/config", method: :regex_match)
+        end
+
+        if repository.exist?("examples") || repository.any?("examples/**/*")
+          facts << fact(:examples, category: :contracts,
+            claim: "Ships runnable examples that can back behavioral claims.",
+            confidence: :medium, source: "examples/", method: :file_present)
+        end
+
+        facts
+      end
+
+      private
+
+      def health_endpoint?
+        candidates = repository.glob("config/routes.rb") +
+          repository.glob("config.ru") +
+          repository.glob("app.rb")
+        candidates.any? { |path| repository.read(path).to_s.match?(HEALTH_ROUTE) }
+      end
+    end
+  end
+end

data/lib/reanimator/detectors/rails_app.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Detectors
+    # Detects a Ruby on Rails application (specification section 06: Ecosystem
+    # and Deployment). The signal is a config/application.rb that boots Rails,
+    # optionally corroborated by a `rails` dependency and a bin/rails script.
+    # Deployment surfaces (Kamal, Docker, Compose) are recorded so the resolver
+    # can flag protected paths.
+    class RailsApp < Base
+      def detect
+        return [] unless rails?
+
+        facts = [
+          fact(:rails_app, category: :ecosystem,
+            claim: "A Ruby on Rails application.",
+            confidence: :high, source: "config/application.rb", method: :file_present)
+        ]
+
+        deployment_facts.each { |f| facts << f }
+        facts
+      end
+
+      private
+
+      def rails?
+        return false unless repository.exist?("config/application.rb")
+
+        body = repository.read("config/application.rb").to_s
+        body.include?("Rails::Application") || repository.exist?("bin/rails")
+      end
+
+      DEPLOYMENT_EVIDENCE = {
+        "config/deploy.yml" => "Kamal deployment",
+        "Dockerfile" => "Docker image build",
+        "docker-compose.yml" => "Docker Compose services",
+        "compose.yaml" => "Docker Compose services"
+      }.freeze
+
+      def deployment_facts
+        DEPLOYMENT_EVIDENCE.filter_map do |path, description|
+          next unless repository.exist?(path)
+
+          fact(:"deploy_#{File.basename(path, ".*").downcase}", category: :deployment,
+            claim: "Deployment surface: #{description}.",
+            confidence: :high, source: path, method: :file_present)
+        end
+      end
+    end
+  end
+end

data/lib/reanimator/detectors/relationships.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Detectors
+    # Detects cross-repository edges (specification section 06: Relationships,
+    # and section 10: repository families). Path dependencies, submodules, and
+    # documentation links are the seams where "keep connected projects alive
+    # together" begins - each edge is a candidate member of a repository
+    # family whose health must be evaluated jointly.
+    class Relationships < Base
+      GEM_PATH = /gem\s+['"]([^'"]+)['"].*\bpath:\s*['"]([^'"]+)['"]/
+      GITHUB_REF = %r{github\.com[:/]([\w.-]+/[\w.-]+?)(?:\.git|/|["')\s]|\z)}
+
+      def detect
+        facts = path_dependency_facts
+        facts.concat(submodule_facts)
+        facts
+      end
+
+      private
+
+      def path_dependency_facts
+        gemfile = repository.read("Gemfile")
+        return [] unless gemfile
+
+        gemfile.scan(GEM_PATH).map do |gem_name, local_path|
+          fact(:"path_dep_#{gem_name.gsub(/[^a-z0-9]+/i, "_")}", category: :relationships,
+            claim: "Depends on a local path gem: #{gem_name} (#{local_path}).",
+            value: {gem: gem_name, path: local_path}, confidence: :high,
+            source: "Gemfile", method: :manifest_parse, detail: local_path)
+        end
+      end
+
+      def submodule_facts
+        body = repository.read(".gitmodules")
+        return [] unless body
+
+        body.scan(GITHUB_REF).flatten.uniq.map do |full_name|
+          fact(:"submodule_#{full_name.gsub(%r{[^a-z0-9]+}i, "_")}", category: :relationships,
+            claim: "Includes submodule #{full_name}.",
+            value: full_name, confidence: :high, source: ".gitmodules", method: :manifest_parse, detail: full_name)
+        end
+      end
+    end
+  end
+end

data/lib/reanimator/detectors/ruby_gem.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Detectors
+    # Detects that a repository is packaged as a Ruby gem (specification
+    # section 06: Ecosystem). A gemspec is the single strongest signal that the
+    # ruby-gem vitality profile applies, so this fact is high-confidence and
+    # names the gemspec as its evidence.
+    class RubyGem < Base
+      def detect
+        gemspec = first_path("*.gemspec")
+        return [] unless gemspec
+
+        facts = [
+          fact(:ruby_gem, category: :ecosystem,
+            claim: "Packaged and released as a Ruby gem.",
+            confidence: :high, source: gemspec, method: :file_present)
+        ]
+
+        if (exe = executables).any?
+          facts << fact(:executables, category: :operational_proof,
+            claim: "Ships command-line executable(s): #{exe.join(", ")}.",
+            value: exe, confidence: :high, source: exe.first, method: :file_present)
+        end
+
+        facts
+      end
+
+      private
+
+      # Executables shipped in exe/ or bin/ (excluding the developer scripts
+      # bundler generates - setup and console are not product surface).
+      def executables
+        (repository.glob("exe/*") + repository.glob("bin/*"))
+          .reject { |p| %w[bin/setup bin/console].include?(p) }
+          .select { |p| File.file?(repository.absolute(p)) }
+      end
+    end
+  end
+end

data/lib/reanimator/detectors/security_controls.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Detectors
+    # Detects repository-level security controls that live outside CI
+    # (specification section 06: Security controls). A SECURITY.md, a
+    # Dependabot configuration, or a CODEOWNERS file are all existing evidence
+    # that should be credited rather than re-requested during onboarding.
+    class SecurityControls < Base
+      EVIDENCE = {
+        security_policy: {
+          globs: ["SECURITY.md", ".github/SECURITY.md", "docs/SECURITY.md"],
+          claim: "A security policy is published (SECURITY.md)."
+        },
+        dependabot: {
+          globs: [".github/dependabot.yml", ".github/dependabot.yaml"],
+          claim: "Automated dependency updates are configured (Dependabot)."
+        },
+        codeowners: {
+          globs: ["CODEOWNERS", ".github/CODEOWNERS", "docs/CODEOWNERS"],
+          claim: "Ownership is declared (CODEOWNERS)."
+        }
+      }.freeze
+
+      def detect
+        EVIDENCE.filter_map do |key, spec|
+          path = spec[:globs].find { |g| repository.exist?(g) }
+          next unless path
+
+          fact(key, category: :security_controls,
+            claim: spec[:claim], confidence: :high, source: path, method: :file_present)
+        end
+      end
+    end
+  end
+end

data/lib/reanimator/discovered_fact.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # A claim inferred from evidence - "RSpec exists", "Docker image builds in
+  # CI", "supported Ruby is 3.1-3.3" - carrying its source, confidence, and
+  # human-review status (specification sections 02 and 06). A discovered fact
+  # is a *proposal*, not a decision: it becomes declared policy only once a
+  # human accepts it.
+  class DiscoveredFact
+    # Detector categories from section 06. A fact always belongs to exactly one.
+    CATEGORIES = %i[
+      ecosystem commands support_matrix security_controls
+      deployment contracts relationships operational_proof
+    ].freeze
+
+    # Review lifecycle of a fact.
+    STATUSES = %i[proposed accepted rejected edited].freeze
+
+    # @return [Symbol] a stable identifier within its repository, e.g. :rspec
+    attr_reader :key
+    # @return [Symbol] one of {CATEGORIES}
+    attr_reader :category
+    # @return [String] human-readable claim
+    attr_reader :claim
+    # @return [Object] the machine-usable value behind the claim
+    attr_reader :value
+    # @return [Confidence]
+    attr_reader :confidence
+    # @return [Provenance]
+    attr_reader :provenance
+    # @return [Symbol] one of {STATUSES}
+    attr_reader :status
+
+    def initialize(key:, category:, claim:, provenance:, value: true, confidence: Confidence::MEDIUM, status: :proposed)
+      raise UnknownError, "Unknown detector category #{category.inspect}." unless CATEGORIES.include?(category.to_sym)
+      raise UnknownError, "Unknown fact status #{status.inspect}." unless STATUSES.include?(status.to_sym)
+
+      @key = key.to_sym
+      @category = category.to_sym
+      @claim = claim
+      @value = value
+      @confidence = Confidence[confidence]
+      @provenance = provenance
+      @status = status.to_sym
+    end
+
+    # Returns a copy accepted by a human. Acceptance is what turns an inference
+    # into declared policy (section 06 conflict resolution rule 4).
+    # @return [DiscoveredFact]
+    def accept
+      with(status: :accepted)
+    end
+
+    # Returns a copy the human explicitly rejected.
+    # @return [DiscoveredFact]
+    def reject
+      with(status: :rejected)
+    end
+
+    # Returns a copy with an edited value, recorded as human-edited.
+    # @return [DiscoveredFact]
+    def edit(new_value)
+      with(value: new_value, status: :edited)
+    end
+
+    def accepted? = status == :accepted
+
+    def rejected? = status == :rejected
+
+    # A fact "counts" toward the contract when a human has not rejected it.
+    def active? = status != :rejected
+
+    def to_h
+      {
+        key: key,
+        category: category,
+        claim: claim,
+        value: value,
+        confidence: confidence.to_sym,
+        status: status,
+        provenance: provenance.to_h
+      }
+    end
+
+    private
+
+    def with(**changes)
+      DiscoveredFact.new(
+        key: changes.fetch(:key, key),
+        category: changes.fetch(:category, category),
+        claim: changes.fetch(:claim, claim),
+        value: changes.fetch(:value, value),
+        confidence: changes.fetch(:confidence, confidence),
+        provenance: changes.fetch(:provenance, provenance),
+        status: changes.fetch(:status, status)
+      )
+    end
+  end
+end

data/lib/reanimator/discovery.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # Runs every detector over a repository and collects their discovered facts
+  # (specification section 06). Discovery is strictly read-only and never
+  # decides policy: it produces proposals, each with provenance and confidence,
+  # for a human to confirm during contract review.
+  class Discovery
+    # The default detector set, ordered roughly ecosystem-first so that later
+    # reporting reads naturally.
+    DEFAULT_DETECTORS = [
+      Detectors::Bundler,
+      Detectors::RubyGem,
+      Detectors::RailsApp,
+      Detectors::Commands,
+      Detectors::GitHubActions,
+      Detectors::SecurityControls,
+      Detectors::Fork,
+      Detectors::OperationalProof,
+      Detectors::Relationships
+    ].freeze
+
+    attr_reader :repository, :detectors
+
+    def initialize(repository, detectors: DEFAULT_DETECTORS)
+      @repository = repository
+      @detectors = detectors
+    end
+
+    # @return [DiscoveryResult]
+    def run
+      facts = detectors.flat_map do |klass|
+        klass.new(repository).call
+      rescue => e
+        # A misbehaving detector must never sink the whole observation; record
+        # the failure and keep going. Robustness over completeness here - but the
+        # failure is logged with its class and origin so a swallowed bug stays
+        # diagnosable rather than silently dropping facts.
+        Reanimator.logger.warn(
+          "#{klass} failed on #{repository.name}: #{e.class}: #{e.message} (at #{e.backtrace&.first})"
+        )
+        []
+      end
+
+      DiscoveryResult.new(repository: repository, facts: facts)
+    end
+  end
+end

data/lib/reanimator/discovery_result.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # The outcome of running discovery over one repository: the collected facts
+  # plus the profile they suggest. This is what the contract-review UI renders
+  # ("here is what we found, and why") and what the resolver consumes.
+  class DiscoveryResult
+    # The suggested profile with the reasoning behind it.
+    Suggestion = Struct.new(:profile, :confidence, :reason)
+
+    attr_reader :repository, :facts
+
+    def initialize(repository:, facts:)
+      @repository = repository
+      @facts = facts
+    end
+
+    # @return [DiscoveredFact, nil]
+    def [](key)
+      facts.find { |f| f.key == key.to_sym }
+    end
+
+    # @return [Boolean]
+    def fact?(key)
+      !self[key].nil?
+    end
+
+    # The machine value of a fact, or nil. Used to pull discovered command
+    # strings into acceptance criteria.
+    def value(key)
+      self[key]&.value
+    end
+
+    # @param category [Symbol]
+    # @return [Array<DiscoveredFact>]
+    def in_category(category)
+      facts.select { |f| f.category == category.to_sym }
+    end
+
+    # @return [Hash{Symbol=>Array<DiscoveredFact>}] facts grouped by category,
+    #   in the canonical category order
+    def by_category
+      DiscoveredFact::CATEGORIES.each_with_object({}) do |category, grouped|
+        found = in_category(category)
+        grouped[category] = found unless found.empty?
+      end
+    end
+
+    # The single source of truth mapping a profile criterion id to the
+    # discovered-command fact key that satisfies it. Note the ids and fact keys
+    # differ (e.g. :tests -> :test_command); this map keeps both
+    # {#discovered_commands} and provenance look-ups from drifting apart.
+    COMMAND_FACT_KEYS = {
+      tests: :test_command,
+      lint: :lint_command,
+      build: :build_command,
+      dependencies: :dependencies_command,
+      assets: :assets_command
+    }.freeze
+
+    # Map of discovered command facts -> command strings, keyed by the profile
+    # criterion they satisfy (:tests, :lint, :build, :dependencies, :assets).
+    # @return [Hash{Symbol=>String}]
+    def discovered_commands
+      COMMAND_FACT_KEYS.each_with_object({}) do |(criterion_id, fact_key), commands|
+        command = value(fact_key)
+        commands[criterion_id] = command if command
+      end
+    end
+
+    # The discovered-command fact backing a profile criterion, for provenance.
+    # @param criterion_id [Symbol]
+    # @return [DiscoveredFact, nil]
+    def command_fact(criterion_id)
+      fact_key = COMMAND_FACT_KEYS[criterion_id.to_sym]
+      fact_key && self[fact_key]
+    end
+
+    # @return [Suggestion]
+    def suggestion
+      @suggestion ||= ProfileInference.call(self)
+    end
+
+    # @return [Symbol] the suggested profile id
+    def suggested_profile
+      suggestion.profile
+    end
+  end
+end

data/lib/reanimator/drift_detector.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Reanimator
+  # Compares two contract snapshots and classifies every difference as either a
+  # policy change or a benign one (specification section 06).
+  #
+  # The classification rule is one question asked of each difference: *is less
+  # being proven than before?* A removed security gate, a narrowed runtime
+  # matrix, a dropped required obligation, a widened autonomy grant and a fresh
+  # waiver all answer yes, so they are policy changes and a human is asked to
+  # look. A renamed test command, an added check, a withdrawn waiver and a
+  # tightened matrix answer no - they are reported, but they do not interrupt
+  # anyone.
+  class DriftDetector
+    # A severity plus the sentence that justifies it. Every change carries the
+    # reasoning for its own classification, so nothing downstream has to guess
+    # why a difference did or did not require review.
+    Verdict = Struct.new(:severity, :explanation)
+
+    # Every judgement this detector can make, gathered in one place: "why did
+    # that need review?" is a question about policy, and the answer should not
+    # be scattered through the code that happened to notice the difference.
+    CHANGED_INTENT = Verdict.new(:policy, "A lifecycle decision changed; what the repository owes changes with it.")
+    CHANGED_PROFILE = Verdict.new(:policy, "The vitality profile changed, so the whole definition of healthy moved.")
+    CHANGED_POSTURE = Verdict.new(:policy, "The security posture changed, altering how strictly findings are treated.")
+    WIDENED_AUTONOMY = Verdict.new(:policy, "Autonomy was widened: the agent may now do more here than it could.")
+    NARROWED_AUTONOMY = Verdict.new(:benign, "Autonomy was narrowed; the agent may do less than it could.")
+    UNPROTECTED_PATH = Verdict.new(:policy, "A path lost its elevated review; changes there no longer need a human.")
+    PROTECTED_PATH = Verdict.new(:benign, "More of the repository is protected than before.")
+    NARROWED_MATRIX = Verdict.new(:policy, "The runtime matrix narrowed: a version that used to be exercised no longer is.")
+    WIDENED_MATRIX = Verdict.new(:benign, "The runtime matrix widened; more versions are exercised.")
+    REMOVED_CONTROL = Verdict.new(:policy, "A security gate was removed; it is no longer part of the proof.")
+    ADDED_CONTROL = Verdict.new(:benign, "A security gate was added.")
+    DROPPED_REQUIRED = Verdict.new(:policy, "A required obligation is gone; nothing proves it any more.")
+    DROPPED_OPTIONAL = Verdict.new(:benign, "An optional check is gone.")
+    ADDED_CRITERION = Verdict.new(:benign, "More is proven than before.")
+    RELAXED_OBLIGATION = Verdict.new(:policy, "An obligation stopped blocking; failing it no longer holds anything back.")
+    TIGHTENED_OBLIGATION = Verdict.new(:benign, "An obligation became blocking; more is required than before.")
+    MOVED_EVALUATOR = Verdict.new(:policy, "The way this obligation is proven changed, so old and new evidence are not comparable.")
+    # The specification's own example of drift that is *not* alarming: the
+    # obligation is identical, only the command spelling moved.
+    RENAMED_COMMAND = Verdict.new(:benign, "The same obligation is proven by a differently spelled command.")
+    ADDED_WAIVER = Verdict.new(:policy, "An obligation is now accepted as risk instead of proven.")
+    REMOVED_WAIVER = Verdict.new(:benign, "Accepted risk was withdrawn; the obligation is blocking again.")
+    EXTENDED_WAIVER = Verdict.new(:policy, "Accepted risk was extended, so the exception outlives the decision that made it.")
+    SHORTENED_WAIVER = Verdict.new(:benign, "Accepted risk was shortened.")
+    # Everything else here fails closed; an expiry nobody can read is not
+    # evidence that the risk got smaller, so it is not treated as if it were.
+    UNREADABLE_WAIVER = Verdict.new(:policy, "Accepted risk moved to an expiry that cannot be read, so it cannot be shown to be shorter.")
+
+    # Scalar fields whose value simply must not change unnoticed.
+    SCALAR_RULES = {
+      intent: CHANGED_INTENT,
+      profile: CHANGED_PROFILE,
+      security_posture: CHANGED_POSTURE
+    }.freeze
+
+    # How one set-valued part of a snapshot drifts. Membership changes are the
+    # same shape everywhere - something is in the old set, or the new one, or
+    # both - so the only thing that varies is what each direction means.
+    SetRule = Struct.new(:field, :subject, :on_removed, :on_added)
+
+    SET_RULES = [
+      SetRule.new(:protected_paths, "protected path", UNPROTECTED_PATH, PROTECTED_PATH),
+      SetRule.new(:support_matrix, "supported runtime", NARROWED_MATRIX, WIDENED_MATRIX),
+      SetRule.new(:security_controls, "security control", REMOVED_CONTROL, ADDED_CONTROL)
+    ].freeze
+
+    # One comparable field of a criterion that both snapshots record. Whether
+    # the difference matters can depend on its direction, so each rule judges
+    # its own before/after rather than exposing a severity outright.
+    CriterionRule = Struct.new(:field, :subject, :judge) do
+      def verdict(before, after) = judge.call(before, after)
+    end
+
+    CRITERION_RULES = [
+      CriterionRule.new(:required, "required", ->(before, _after) { before ? RELAXED_OBLIGATION : TIGHTENED_OBLIGATION }),
+      CriterionRule.new(:evaluator, "evaluator", ->(_before, _after) { MOVED_EVALUATOR }),
+      CriterionRule.new(:run, "command", ->(_before, _after) { RENAMED_COMMAND })
+    ].freeze
+
+    # How a waiver with no expiry reads in a report.
+    OPEN_ENDED = "open-ended"
+
+    # Autonomy is a grant, not a scale: anything other than :disabled is a
+    # grant, and :automatic grants it without a human in the loop.
+    AUTONOMY_RANKS = {disabled: 0, manual: 1, proposal: 1, automatic: 2}.freeze
+
+    # @param previous [ContractSnapshot] the contract as last recorded
+    # @param current [ContractSnapshot] the contract the evidence resolves to now
+    # @return [DriftReport]
+    def self.between(previous, current) = new(previous, current).call
+
+    def initialize(previous, current)
+      @previous = previous
+      @current = current
+    end
+
+    def call
+      ensure_same_repository
+
+      DriftReport.new(
+        repository: @current.repository, previous: @previous, current: @current,
+        changes: scalar_changes + autonomy_changes + set_changes + criteria_changes + waiver_changes
+      )
+    end
+
+    private
+
+    # Comparing two different repositories' snapshots would produce a report
+    # that reads plausibly and means nothing, and the dangerous direction is
+    # "no drift" - quietly reporting a repository unchanged that was never
+    # recorded. A git origin names a repository exactly, so it decides whenever
+    # both snapshots carry one; without it the recorded names are the only
+    # evidence there is, and two same-named local checkouts are
+    # indistinguishable.
+    def ensure_same_repository
+      recorded, current = identities
+      return if recorded.nil? || current.nil? || recorded == current
+
+      raise ContractError,
+        "Snapshot is for #{recorded}, not #{current}; drift is only meaningful within one repository."
+    end
+
+    def identities
+      if @previous.origin && @current.origin
+        [@previous.origin, @current.origin]
+      else
+        [@previous.repository, @current.repository]
+      end
+    end
+
+    def scalar_changes
+      SCALAR_RULES.filter_map do |field, verdict|
+        before = @previous.public_send(field)
+        after = @current.public_send(field)
+        next if before == after
+
+        change(field.to_s.tr("_", " "), :changed, verdict, from: before, to: after)
+      end
+    end
+
+    def autonomy_changes
+      (@previous.autonomy.keys | @current.autonomy.keys).filter_map do |rung|
+        before = @previous.autonomy[rung] || :disabled
+        after = @current.autonomy[rung] || :disabled
+        next if before == after
+
+        verdict = (rank(after) > rank(before)) ? WIDENED_AUTONOMY : NARROWED_AUTONOMY
+        change("autonomy #{rung}", :changed, verdict, from: before, to: after)
+      end
+    end
+
+    def rank(mode) = AUTONOMY_RANKS.fetch(mode.to_sym, 1)
+
+    def set_changes
+      SET_RULES.flat_map do |rule|
+        before = Array(@previous.public_send(rule.field))
+        after = Array(@current.public_send(rule.field))
+
+        (before - after).map { |value| change(rule.subject, :removed, rule.on_removed, from: value) } +
+          (after - before).map { |value| change(rule.subject, :added, rule.on_added, to: value) }
+      end
+    end
+
+    def criteria_changes
+      before_ids = @previous.criterion_ids
+      after_ids = @current.criterion_ids
+
+      (before_ids - after_ids).map { |id| dropped_criterion(id) } +
+        (after_ids - before_ids).map { |id| change("criterion", :added, ADDED_CRITERION, to: id) } +
+        (before_ids & after_ids).flat_map { |id| altered_criterion(id) }
+    end
+
+    def dropped_criterion(id)
+      verdict = @previous.requires?(id) ? DROPPED_REQUIRED : DROPPED_OPTIONAL
+      change("criterion", :removed, verdict, from: id)
+    end
+
+    def altered_criterion(id)
+      before = @previous.criterion(id)
+      after = @current.criterion(id)
+
+      CRITERION_RULES.filter_map do |rule|
+        was = before[rule.field]
+        now = after[rule.field]
+        next if was == now
+
+        change("criterion #{id} #{rule.subject}", :changed, rule.verdict(was, now), from: was, to: now)
+      end
+    end
+
+    def waiver_changes
+      before_targets = @previous.waiver_targets
+      after_targets = @current.waiver_targets
+
+      (after_targets - before_targets).map { |target| change("waiver", :added, ADDED_WAIVER, to: target) } +
+        (before_targets - after_targets).map { |target| change("waiver", :removed, REMOVED_WAIVER, from: target) } +
+        (before_targets & after_targets).filter_map { |target| rescheduled_waiver(target) }
+    end
+
+    def rescheduled_waiver(target)
+      before = @previous.waiver_expiry(target)
+      after = @current.waiver_expiry(target)
+      return if before == after
+
+      change("waiver #{target} expiry", :changed, expiry_verdict(before, after),
+        from: before || OPEN_ENDED, to: after || OPEN_ENDED)
+    end
+
+    # An open-ended waiver (no expiry) outlives every dated one.
+    def expiry_verdict(before, after)
+      return EXTENDED_WAIVER if after.nil?
+      return SHORTENED_WAIVER if before.nil?
+
+      (Time.parse(after) > Time.parse(before)) ? EXTENDED_WAIVER : SHORTENED_WAIVER
+    rescue ArgumentError, TypeError
+      UNREADABLE_WAIVER
+    end
+
+    def change(subject, kind, verdict, from: nil, to: nil)
+      DriftReport::Change.new(subject: subject, kind: kind, verdict: verdict, from: from, to: to)
+    end
+  end
+end