reanimator 0.1.0

data/lib/reanimator/cohort.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # A suggested triage grouping for a repository during intake (specification
+  # section 04). Cohorts exist so a maintainer can accept sensible defaults in
+  # bulk while still seeing - and overriding - the intent behind each grouping.
+  # Crucially, the tool never preselects every repository; it recommends a
+  # small, high-confidence set that can reach a useful baseline quickly.
+  class Cohort
+    attr_reader :key, :title, :default_intent, :treatment
+
+    def initialize(key:, title:, default_intent:, treatment:)
+      @key = key
+      @title = title
+      @default_intent = default_intent
+      @treatment = treatment
+      freeze
+    end
+
+    # Whether repositories in this cohort are recommended for active
+    # onboarding (versus deferred, observed, or preserved).
+    def recommended_for_onboarding?
+      key == :active_original
+    end
+
+    ALL = {
+      active_original: new(
+        key: :active_original, title: "Active original repositories",
+        default_intent: :maintain, treatment: "Recommend for onboarding."
+      ),
+      recent_experiment: new(
+        key: :recent_experiment, title: "Recent experiments",
+        default_intent: :incubate, treatment: "Suggest incubate or monitor."
+      ),
+      readme_only: new(
+        key: :readme_only, title: "README-only concepts and presentations",
+        default_intent: :incubate, treatment: "Ask whether to incubate, preserve, or ignore."
+      ),
+      archived: new(
+        key: :archived, title: "Archived repositories",
+        default_intent: :preserve, treatment: "Suggest preserve or retire; never auto-modernize."
+      ),
+      old_unarchived: new(
+        key: :old_unarchived, title: "Old unarchived repositories",
+        default_intent: :monitor, treatment: "Flag intent ambiguity rather than assuming maintenance."
+      ),
+      fork_observation: new(
+        key: :fork_observation, title: "Forks",
+        default_intent: :upstream, treatment: "Upstream observation until unique-commit intent is confirmed."
+      ),
+      constrained: new(
+        key: :constrained, title: "Hardware or credential-dependent projects",
+        default_intent: :monitor, treatment: "Suggest a constrained-environment profile."
+      )
+    }.freeze
+
+    def self.fetch(key)
+      ALL.fetch(key.to_sym) { raise UnknownError, "Unknown cohort #{key.inspect}." }
+    end
+  end
+end

data/lib/reanimator/commissioning/fixture.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+
+module Reanimator
+  module Commissioning
+    # Builds a disposable fixture repository with a single, seeded defect
+    # (specification section 08 step 2: "run a synthetic repair against a
+    # disposable fixture repository"). The fixture ships an addition helper that
+    # wrongly subtracts and a required check that fails because of it, plus a
+    # protected verifier file the agent must not touch. Nothing here depends on
+    # Bundler, so commissioning is fast and hermetic.
+    module Fixture
+      BUGGY_LIB = <<~RUBY
+        # frozen_string_literal: true
+
+        module Calc
+          module_function
+
+          def add(a, b)
+            a - b
+          end
+        end
+      RUBY
+
+      CHECK = <<~RUBY
+        # frozen_string_literal: true
+
+        require "calc"
+
+        raise "add(2, 2) should be 4, got \#{Calc.add(2, 2)}" unless Calc.add(2, 2) == 4
+        puts "ok"
+      RUBY
+
+      CONTRACT = <<~YAML
+        version: 1
+        intent: maintain
+        profile: generic
+        acceptance:
+          protected_paths:
+            - check.rb
+          checks:
+            - id: arithmetic
+              claim: "add(2, 2) equals 4."
+              run: "ruby -Ilib check.rb"
+              required: true
+      YAML
+
+      module_function
+
+      # @return [String] path to a fresh disposable fixture
+      def build
+        dir = Dir.mktmpdir("reanimator-commission")
+        write(dir, "lib/calc.rb", BUGGY_LIB)
+        write(dir, "check.rb", CHECK)
+        write(dir, ".reanimator.yml", CONTRACT)
+        write(dir, "README.md", "# Commissioning fixture\n")
+        dir
+      end
+
+      def write(dir, relative, contents)
+        full = File.join(dir, relative)
+        FileUtils.mkdir_p(File.dirname(full))
+        File.write(full, contents)
+      end
+    end
+  end
+end

data/lib/reanimator/commissioning/report.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Reanimator
+  module Commissioning
+    # The outcome of a commissioning test (specification section 08 step 6:
+    # "mark the profile ready, degraded, incompatible, or unavailable"), plus
+    # the observable facts step 5 requires: cost, latency, permissions, tool
+    # use, and any network destinations. Reanimator computes the verdict
+    # itself from independent evaluation; the agent never grades its own work.
+    class Report
+      attr_reader :provider, :readiness, :reason, :capabilities, :objective,
+        :pre_state, :post_state, :cost_usd, :latency_s, :tool_use, :network
+
+      def initialize(provider:, readiness:, reason: nil, capabilities: [], objective: nil,
+        pre_state: nil, post_state: nil, cost_usd: 0.0, latency_s: 0.0, tool_use: [], network: [])
+        @provider = provider
+        @readiness = readiness.to_sym
+        @reason = reason
+        @capabilities = capabilities
+        @objective = objective
+        @pre_state = pre_state
+        @post_state = post_state
+        @cost_usd = cost_usd
+        @latency_s = latency_s
+        @tool_use = tool_use
+        @network = network
+      end
+
+      def ready? = readiness == :ready
+
+      # The whole point of the slice: a profile can be proven ready without any
+      # repository write. Commissioning only ever touches disposable fixtures.
+      def proven_without_writes? = true
+
+      def to_h
+        {
+          provider: provider, readiness: readiness, reason: reason,
+          capabilities: capabilities, objective: objective,
+          pre_state: pre_state, post_state: post_state,
+          cost_usd: cost_usd, latency_s: latency_s, tool_use: tool_use, network: network
+        }.compact
+      end
+    end
+  end
+end

data/lib/reanimator/commissioning/test.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+
+module Reanimator
+  module Commissioning
+    # Runs the six-step commissioning test from specification section 08:
+    # validate credentials and capabilities, run a synthetic repair against a
+    # disposable fixture, require a structured plan and patch, evaluate the
+    # result *independently*, report the observable cost/latency/tools/network,
+    # and mark the profile ready/degraded/incompatible/unavailable.
+    #
+    # Verifier isolation (section 09) is structural here: the agent works in its
+    # own copy and returns a patch as data; the harness applies that patch to a
+    # *separate, clean* copy and grades it with Reanimator's own evaluators.
+    # A patch that reaches for a protected or verifier path is refused - the
+    # anti-gaming rule, enforced.
+    class Test
+      ALLOWED_EDIT_PATHS = ["lib/**", "*.rb"].freeze
+
+      def initialize(adapter, fixture: Fixture)
+        @adapter = adapter
+        @fixture = fixture
+      end
+
+      # @return [Commissioning::Report]
+      def run
+        return unavailable unless @adapter.available?
+
+        fixture_path = @fixture.build
+        scratch = [fixture_path]
+        begin
+          contract = contract_for(fixture_path)
+          pre = BaselineRunner.new(contract, execute: true).run
+          objective = pre.results.find { |r| r.required? && r.failed? }&.criterion
+          return incompatible("The fixture did not present a failing required objective.", pre: pre) unless objective
+
+          workspace = copy(fixture_path, scratch)
+          result = @adapter.repair(build_task(objective, workspace, contract, pre))
+          return incompatible("The agent returned no structured plan and patch.", pre: pre, result: result) unless result.structured?
+
+          if (violation = protected_violation(build_task(objective, workspace, contract, pre), result))
+            return incompatible(violation, pre: pre, result: result)
+          end
+
+          eval_dir = copy(fixture_path, scratch)
+          result.patch.apply(eval_dir)
+          post = BaselineRunner.new(contract_for(eval_dir), execute: true).run
+
+          verdict(objective, pre, post, result)
+        ensure
+          scratch.each { |dir| FileUtils.remove_entry(dir, true) }
+        end
+      end
+
+      private
+
+      def contract_for(path)
+        EffectivePolicyResolver.new(Repository.at(path)).resolve
+      end
+
+      def build_task(objective, workspace, contract, pre)
+        Agents::RepairTask.new(
+          objective: objective, workspace: workspace, evidence: pre,
+          constraints: Agents::Constraints.new(
+            allowed_paths: ALLOWED_EDIT_PATHS,
+            protected_paths: contract.protected_paths,
+            max_cost_usd: @adapter.connection.max_cost_usd,
+            code_egress: @adapter.code_egress
+          )
+        )
+      end
+
+      # Anti-gaming (section 09): a repair may not edit a protected or
+      # out-of-scope path. This is what stops a task from rewriting the rules of
+      # proof and then passing under the new rules.
+      def protected_violation(task, result)
+        bad = result.patch.paths.reject { |path| task.may_edit?(path) }
+        "The patch attempted to edit protected or out-of-scope paths: #{bad.join(", ")}." unless bad.empty?
+      end
+
+      def verdict(objective, pre, post, result)
+        target = post.results.find { |r| r.criterion.id == objective.id }
+        regressions = regressed(pre, post)
+        over_budget = result.cost_usd > @adapter.connection.max_cost_usd
+
+        if target&.verified? && regressions.empty? && !over_budget
+          report(:ready, pre: pre, post: post, result: result, objective: objective)
+        else
+          report(:degraded, pre: pre, post: post, result: result, objective: objective,
+            reason: degraded_reason(target, regressions, over_budget))
+        end
+      end
+
+      # Required criteria that were verified before the repair but are not
+      # after it - genuine regressions the patch must not introduce.
+      def regressed(pre, post)
+        proven = pre.results.select { |r| r.required? && r.verified? }.map { |r| r.criterion.id }
+        post.results.select { |r| proven.include?(r.criterion.id) && !r.verified? }.map { |r| r.criterion.id }
+      end
+
+      def degraded_reason(target, regressions, over_budget)
+        if target.nil? || !target.verified?
+          "The patch did not resolve the objective."
+        elsif over_budget
+          "The repair exceeded the connection budget."
+        else
+          "The repair regressed: #{regressions.join(", ")}."
+        end
+      end
+
+      def copy(source, scratch)
+        destination = Dir.mktmpdir("reanimator-ws")
+        FileUtils.cp_r(File.join(source, "."), destination)
+        scratch << destination
+        destination
+      end
+
+      def unavailable
+        report(:unavailable, reason: @adapter.unavailable_reason)
+      end
+
+      def incompatible(reason, **rest)
+        report(:incompatible, reason: reason, **rest)
+      end
+
+      def report(readiness, pre: nil, post: nil, result: nil, objective: nil, reason: nil)
+        Report.new(
+          provider: @adapter.provider,
+          readiness: readiness,
+          reason: reason,
+          capabilities: @adapter.capabilities,
+          objective: objective&.id,
+          pre_state: pre&.state&.to_sym,
+          post_state: post&.state&.to_sym,
+          cost_usd: result&.cost_usd || 0.0,
+          latency_s: result&.latency_s || 0.0,
+          tool_use: result&.tool_use || [],
+          network: result&.network || []
+        )
+      end
+    end
+  end
+end

data/lib/reanimator/confidence.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # How strongly a discovered fact is believed, and - just as importantly -
+  # what the product is allowed to do with that belief (specification section
+  # 06). Confidence never silently becomes authority: even a high-confidence
+  # fact is only *preselected*, and it still asks for confirmation when it
+  # would affect permissions, cost, privacy, or action authority.
+  class Confidence
+    include Comparable
+
+    LEVELS = %i[low medium high].freeze
+
+    BEHAVIOR = {
+      high: "Preselect and ask for confirmation only when the fact affects " \
+            "permissions, cost, privacy, or action authority.",
+      medium: "Show as a suggestion with evidence and alternatives.",
+      low: "Use to prioritize a question; never convert directly into an obligation."
+    }.freeze
+
+    attr_reader :level
+
+    def initialize(level)
+      @level = level.to_sym
+      unless LEVELS.include?(@level)
+        raise UnknownError, "Unknown confidence #{level.inspect}. Known: #{LEVELS.join(", ")}."
+      end
+      freeze
+    end
+
+    HIGH = new(:high)
+    MEDIUM = new(:medium)
+    LOW = new(:low)
+
+    def self.[](level)
+      case level
+      when Confidence then level
+      when :high, "high" then HIGH
+      when :medium, "medium" then MEDIUM
+      when :low, "low" then LOW
+      else new(level)
+      end
+    end
+
+    # Product behavior mandated for this confidence level.
+    # @return [String]
+    def behavior = BEHAVIOR.fetch(level)
+
+    # High-confidence facts may be preselected in the review UI; lower ones may
+    # only be suggested or used to prioritize a question.
+    def preselectable? = level == :high
+
+    # A low-confidence fact must never be converted directly into an
+    # obligation - it can only shape a question.
+    def obligatable? = level != :low
+
+    def <=>(other)
+      return nil unless other.is_a?(Confidence)
+      LEVELS.index(level) <=> LEVELS.index(other.level)
+    end
+
+    def to_sym = level
+
+    def to_s = level.to_s
+  end
+end

data/lib/reanimator/configuration.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Reanimator
+  # Process-wide configuration. Everything here has a safe, quiet default so
+  # the library is useful with zero setup - configuration is for tightening,
+  # not for enabling basic behavior.
+  class Configuration
+    # The file a repository owner may commit to declare intent and overrides.
+    DEFAULT_CONTRACT_FILENAME = ".reanimator.yml"
+
+    # @return [Symbol] the security posture applied when a repository does not
+    #   declare one (:strict, :balanced, :local, :custom). Section 20 sets
+    #   :balanced for public repositories as the v1 default.
+    attr_accessor :security_posture
+
+    # @return [String] the filename scanned for a repository-owned contract.
+    attr_accessor :contract_filename
+
+    # @return [Integer] wall-clock ceiling, in seconds, for any single check
+    #   executed during a baseline. Baselines are bounded by construction.
+    attr_accessor :command_timeout
+
+    # @return [Boolean] whether baseline checks may execute at all. Even when
+    #   true, execution is opt-in per run; when false the runner only ever
+    #   plans, never spawns a process.
+    attr_accessor :allow_execution
+
+    def initialize
+      @security_posture = (ENV["REANIMATOR_SECURITY_POSTURE"] || "balanced").to_sym
+      @contract_filename = ENV["REANIMATOR_CONTRACT_FILE"] || DEFAULT_CONTRACT_FILENAME
+      @command_timeout = Integer(ENV["REANIMATOR_COMMAND_TIMEOUT"] || 900)
+      @allow_execution = ENV["REANIMATOR_ALLOW_EXECUTION"] != "false"
+    end
+  end
+end

data/lib/reanimator/contract_file.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "date"
+
+module Reanimator
+  # Reads and writes the optional, repository-owned .reanimator.yml
+  # (specification section 07). The target for ordinary configuration is tiny -
+  # "one lifecycle decision and one reusable profile" - but the same file can
+  # carry the full resolved schema for advanced owners. Export must round-trip
+  # without semantic loss, so this class is the single reader and writer for
+  # that format.
+  class ContractFile
+    CURRENT_VERSION = 1
+
+    # @return [Hash] the parsed document with symbol keys
+    attr_reader :data
+    # @return [String, nil] path the document was loaded from
+    attr_reader :source_path
+
+    def initialize(data, source_path: nil)
+      @data = normalize(data)
+      @source_path = source_path
+      validate!
+    end
+
+    # Loads the contract file from a repository root, or returns nil when the
+    # owner has not committed one (the common, YAML-free case).
+    #
+    # @param root [String]
+    # @param filename [String]
+    # @return [ContractFile, nil]
+    def self.load(root, filename = Reanimator.configuration.contract_filename)
+      full = File.join(root, filename)
+      return nil unless File.file?(full)
+
+      # Date/Time are permitted so a waiver's `expires:` can be a bare date
+      # literal; no other non-primitive classes are allowed to load.
+      raw = YAML.safe_load_file(full, permitted_classes: [Date, Time], aliases: false) || {}
+      new(raw, source_path: full)
+    rescue Psych::SyntaxError => e
+      raise ContractError, "#{filename} is not valid YAML: #{e.message}"
+    end
+
+    # Serializes a contract hash (typically {EffectiveContract#to_contract_hash})
+    # back to YAML. Keys are stringified and ordered for a stable, diff-friendly
+    # export.
+    #
+    # @param hash [Hash]
+    # @return [String]
+    def self.dump(hash)
+      YAML.dump(stringify(hash)).sub(/\A---\n/, "")
+    end
+
+    def version = data.fetch(:version, CURRENT_VERSION)
+
+    # @return [Symbol, nil]
+    def intent
+      value = data[:intent]
+      value&.to_sym
+    end
+
+    # @return [Symbol, nil]
+    def profile
+      value = data[:profile]
+      value&.to_sym
+    end
+
+    def agents = data[:agents] || {}
+
+    def acceptance = data[:acceptance] || {}
+
+    def security = data[:security] || {}
+
+    def autonomy = data[:autonomy] || {}
+
+    def upgrades = data[:upgrades] || {}
+
+    def notifications = data[:notifications] || {}
+
+    def waivers = data[:waivers] || []
+
+    def family = data[:family]
+
+    def to_yaml = ContractFile.dump(data)
+
+    private
+
+    def validate!
+      unless version.is_a?(Integer)
+        raise ContractError, "Contract version must be an integer, got #{version.inspect}."
+      end
+      if intent && !LifecycleIntent.valid?(intent)
+        raise ContractError, "Unknown lifecycle intent #{intent.inspect} in contract."
+      end
+    end
+
+    def normalize(value)
+      case value
+      when Hash then value.each_with_object({}) { |(k, v), h| h[k.to_sym] = normalize(v) }
+      when Array then value.map { |v| normalize(v) }
+      else value
+      end
+    end
+
+    def self.stringify(value)
+      case value
+      when Hash then value.each_with_object({}) { |(k, v), h| h[k.to_s] = stringify(v) }
+      when Array then value.map { |v| stringify(v) }
+      when Symbol then value.to_s
+      else value
+      end
+    end
+    private_class_method :stringify
+  end
+end