insika 0.2.0 → 0.3.0

data/lib/insika/harvest/gate.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Insika
+  module Harvest
+    # C7 — the eval half of the double gate (D7). Scores ONE candidate by
+    # RUNNING it — the Refinement::Gate mechanism, with the skill's apply:
+    #
+    #   1. clone the agent into `<agent>-harvest-<run8>`,
+    #   2. copy its instruction files, write the candidate skill into the
+    #      clone's AGENT-scoped SkillStore and enable it on the clone's
+    #      allowlist (the clone's catalog then serves it — the skill is gated
+    #      by being *usable*, not by prose),
+    #   3. replay the golden set against the clone over the ordinary public
+    #      surface, compare to the accepted baseline,
+    #   4. ANY regression disqualifies,
+    #   5. destroy the clone in an `ensure`.
+    #
+    # Judges are MANDATORY in exactly the three refusal shapes the refined
+    # gate already encodes (no baseline / all-red baseline / judged baseline
+    # without a judge) — the P18 stamp. A skill that regresses ANY golden case
+    # is rejected — this gate is a veto, never a score to argue with.
+    class Gate
+      # The verdict for one candidate. `passed` is the only field the caller
+      # acts on; the rest is what an operator reads.
+      Report = Data.define(:candidate_id, :passed, :reason, :cases, :passed_cases,
+                           :baseline_cases, :regressions, :report, :tokens, :cached) do
+        def to_h
+          { "candidate_id" => candidate_id, "passed" => passed, "reason" => reason,
+            "cases" => cases, "passed_cases" => passed_cases, "baseline_cases" => baseline_cases,
+            "regressions" => regressions, "report" => report, "tokens" => tokens,
+            "cached" => cached }
+        end
+      end
+
+      DEFAULT_TOLERANCE = 0.05
+
+      # skill_catalog: the graph's catalog (overlays the SkillStore) — the
+      # apply writes into the store then RELOADS it, so the clone's next
+      # dispatch serves the skill. judge_factory: the settings["evals"] panel
+      # (the same one the refinement gate receives).
+      def initialize(profiles:, agent_files:, goldens:, baselines:, skill_store:,
+                     skill_catalog:, transport_factory:, capabilities_factory: nil,
+                     judge_factory: nil, tolerance: DEFAULT_TOLERANCE)
+        @profiles = profiles
+        @agent_files = agent_files
+        @goldens = goldens
+        @baselines = baselines
+        @skill_store = skill_store
+        @skill_catalog = skill_catalog
+        @transport_factory = transport_factory
+        @capabilities_factory = capabilities_factory
+        @judge_factory = judge_factory
+        @tolerance = tolerance
+      end
+
+      # skill: the candidate's { name:, description:, body:, triggers: }.
+      # -> Report. Never raises for an ordinary refusal (no cases, no
+      # baseline, a replay that blew up).
+      def score(agent_id:, skill:, run_id:)
+        cases = @goldens.for_agent(agent_id)
+        return refusal(skill, "the agent has no golden cases — nothing to gate against") if cases.empty?
+
+        baseline = @baselines.get(agent_id)
+        if baseline.nil?
+          return refusal(skill, "no recorded baseline for '#{agent_id}' — " \
+                                "run `insika evals:baseline import` or record one before gating")
+        end
+
+        if passing_cases(baseline).zero?
+          return refusal(skill, "the recorded baseline for '#{agent_id}' has no PASSING case " \
+                                "(#{baseline_size(baseline)} recorded, all failing) — nothing could " \
+                                "regress, so every candidate would pass. Fix the agent or the cases, " \
+                                "then re-record the baseline from a green run")
+        end
+
+        judge = @judge_factory&.call
+        if judge.nil? && judged?(baseline)
+          return refusal(skill, "the recorded baseline for '#{agent_id}' carries judge scores but no " \
+                                "judge is configured — a rubric'd case with no verdict counts as a " \
+                                "PASS, so every candidate would beat it. Configure the judge panel " \
+                                "(Studio → Settings → Evals, or `settings[\"evals\"][\"judges\"]`) or " \
+                                "re-record the baseline without one")
+        end
+
+        clone_id = clone_id_for(agent_id, run_id)
+        begin
+          build_clone(agent_id, clone_id, skill)
+          ran = replay(cases, clone_id, judge)
+          verdict(skill, ran, baseline, @tolerance)
+        rescue StandardError => e
+          refusal(skill, "gate failed to run: #{e.class}: #{e.message}")
+        ensure
+          destroy_clone(clone_id)
+        end
+      end
+
+      def clone_id_for(agent_id, run_id) = "#{agent_id}-harvest-#{run_id.to_s.delete('-')[0, 8]}"
+
+      def passing_cases(baseline)
+        (baseline["cases"] || {}).count { |_id, entry| entry.is_a?(Hash) && entry["pass"] }
+      end
+
+      def judged?(baseline)
+        (baseline["cases"] || {}).any? { |_id, entry| entry.is_a?(Hash) && !entry["score"].nil? }
+      end
+
+      private
+
+      def baseline_size(baseline) = (baseline["cases"] || {}).size
+
+      # Same profile, same tools, same guardrails — only the id and the skill
+      # differ. Copying the profile rather than editing the real one is what
+      # makes this safe to run against production: the live agent is never
+      # touched, not even for a moment.
+      def build_clone(agent_id, clone_id, skill)
+        profile = @profiles.fetch(agent_id) ||
+                  (raise Insika::NotFoundError, "agent '#{agent_id}' not configured")
+
+        @profiles.put(profile.with(id: clone_id))
+        current_files(agent_id).each { |name, body| @agent_files.write(clone_id, name, body) }
+
+        # D7: the skill lands into the clone's AGENT-scoped SkillStore (the
+        # store position IS the identity), and the clone's profile `skills`
+        # gains the name — so the clone's catalog serves it and the model can
+        # load_skill it.
+        name = skill["name"].to_s
+        @skill_store.write(name, skill["body"].to_s, agent: clone_id)
+        enabled = profile.skills.nil? ? nil : (Array(profile.skills).map(&:to_s) | [name])
+        @profiles.put(profile.with(id: clone_id, skills: enabled))
+        @skill_catalog.reload
+      end
+
+      def current_files(agent_id)
+        @agent_files.list(agent_id).each_with_object({}) do |name, acc|
+          acc[name] = @agent_files.read(agent_id, name).to_s
+        end
+      end
+
+      def replay(cases, clone_id, judge)
+        retargeted = cases.map { |g| g.class.new(**g.to_h.merge(agent: clone_id)) }
+        runner = Insika::Evals::Runner.new(transport: @transport_factory.call, judge: judge,
+                                           capabilities: @capabilities_factory&.call)
+        runner.run(retargeted)
+      end
+
+      def verdict(skill, ran, baseline, tolerance)
+        results = ran.map(&:result)
+        regressions = Insika::Evals::Baseline.compare(results, baseline, tolerance: tolerance)
+        passed = results.count(&:pass?)
+        graded = results.reject(&:skipped?).size
+        spent = ran.filter_map(&:tokens)
+        cached = ran.filter_map(&:cached)
+
+        Report.new(
+          candidate_id: skill["name"], passed: regressions.empty?,
+          reason: regressions.empty? ? nil : regression_reason(regressions),
+          cases: graded, passed_cases: passed,
+          baseline_cases: (baseline["cases"] || {}).size,
+          regressions: regressions.map { |r| { "id" => r.id, "kind" => r.kind, "detail" => r.detail } },
+          report: Insika::Evals::Report.to_h(results, at: Time.now.utc.iso8601),
+          tokens: spent.empty? ? nil : spent.sum,
+          cached: cached.empty? ? nil : cached.sum
+        )
+      end
+
+      def regression_reason(regressions)
+        "#{regressions.size} regression(s): " +
+          regressions.first(3).map { |r| "#{r.id} (#{r.kind})" }.join(", ")
+      end
+
+      def refusal(skill, reason)
+        Report.new(candidate_id: skill["name"], passed: false, reason: reason,
+                   cases: 0, passed_cases: 0, baseline_cases: 0, regressions: [], report: nil,
+                   tokens: nil, cached: nil)
+      end
+
+      # Both halves tolerant of a missing one; runs in an `ensure` after a
+      # failure that may have happened before either was created.
+      def destroy_clone(clone_id)
+        @agent_files.list(clone_id).each { |name| @agent_files.delete(clone_id, name) }
+        begin
+          Array(@skill_store.names(agent: clone_id)).each do |name|
+            @skill_store.delete(name, agent: clone_id)
+          end
+        rescue StandardError
+          nil # a leftover skill record is clutter, never servable without the profile
+        end
+        @profiles.delete(clone_id)
+      rescue StandardError => e
+        warn "[harvest] could not delete the gate clone '#{clone_id}': #{e.class}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/insika/harvest/negative_list.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Insika
+  module Harvest
+    # C3 — the versioned negative list : things the harvester must
+    # never propose. Pure value object — never touches a store, never authors
+    # a rule (D4: the engine applies it, the forge authors it). `parse`
+    # accepts BOTH the markdown file shape (frontmatter + rule bullets) and
+    # the pack-data array shape ({ rule, pattern, note } hashes), so a rule
+    # cannot exist in one and not the other (E2's drift guard).
+    #
+    # A rule is a phrase or a regex. Phrases match case/accent-folded at WORD
+    # boundaries (the   hygiene — "NÃO DEVOLVEMOS" is the same
+    # word as "não devolvemos"); regexes match the raw OR the folded text (the
+    # author may write either spelling, `/…/flags` honored). `matches_name` is
+    # the stricter SUBSTRING reading the CI spec uses on skill names.
+    class NegativeList
+      Rule = Data.define(:rule, :pattern, :note, :regexp)
+
+      # The pt-BR vowel fold — stdlib only, no UnicodeUtils. Both sides of a
+      # phrase match are folded through this map.
+      FOLD = {
+        "á" => "a", "à" => "a", "ã" => "a", "â" => "a",
+        "é" => "e", "ê" => "e",
+        "í" => "i",
+        "ó" => "o", "õ" => "o", "ô" => "o",
+        "ú" => "u", "ü" => "u",
+        "ç" => "c"
+      }.freeze
+      FOLD_RE = Regexp.union(FOLD.keys)
+
+      attr_reader :rules
+
+      # A file line: "- `rule-id` — <phrase-or-/regex/> — <note>" (the note
+      # may be empty; a phrase may be quoted — `"concorrente"` — and the
+      # quotes are not part of the pattern, matching the pack-array shape). A
+      # malformed line refuses the WHOLE list — a half-parsed list silently
+      # admits what the store banned.
+
+      def self.parse(raw)
+        parse!(raw)
+      rescue Insika::ValidationError
+        nil
+      end
+
+      # -> NegativeList. Raises Insika::ValidationError naming the defect —
+      # the E2 seed path (`insika harvest:negative import`) uses THIS one.
+      def self.parse!(raw)
+        new(rules: parse_rules(raw))
+      end
+
+      def self.parse_rules(raw)
+        return [] if raw.nil?
+
+        case raw
+        when String
+          file_rules(raw)
+        when Array
+          array_rules(raw)
+        else
+          raise Insika::ValidationError, "negative list must be file text or an array of rules"
+        end
+      end
+      private_class_method :parse_rules
+
+      def self.file_rules(text)
+        text.each_line.with_index(1).filter_map do |line, index|
+          next if line.strip.empty? || line.strip.start_with?("#")
+
+          id_match = /\A`([^`]+)`\s+—\s*/.match(line.strip.delete_prefix("- "))
+          raise Insika::ValidationError, "negative list line #{index} is malformed — " \
+                                         "expected `- \\`rule-id\\` — <phrase-or-/regex/> — <note>`" if id_match.nil?
+
+          rest = line.strip.delete_prefix("- ").sub(/\A`[^`]+`\s+—\s*/, "")
+          # a trailing bare " —" (an empty note) is presentation, not content
+          rest = rest.sub(/\s+—\s*\z/, "") if rest.match?(/\s+—\s*\z/)
+          pattern, note = rest.split(" — ", 2)
+          build_rule(rule: id_match[1], pattern: strip_quotes(pattern.to_s.strip),
+                     note: note.to_s.strip, line: index)
+        end
+      end
+      private_class_method :file_rules
+
+      # The file shape quotes a phrase (`"concorrente"`); the quotes are
+      # presentation, not part of the pattern — the pack-array shape has none.
+      def self.strip_quotes(pattern)
+        return pattern[1...-1] if pattern.start_with?('"') && pattern.end_with?('"') && pattern.length >= 2
+
+        pattern
+      end
+      private_class_method :strip_quotes
+
+      def self.array_rules(entries)
+        entries.each_with_index.map do |entry, i|
+          unless entry.is_a?(Hash)
+            raise Insika::ValidationError, "negative list entry ##{i + 1} is not a { rule, pattern } hash"
+          end
+
+          h = Coercion.deep_stringify(entry)
+          rule = Coercion.presence(h["rule"])
+          pattern = Coercion.presence(h["pattern"])
+          raise Insika::ValidationError, "negative list entry ##{i + 1} is missing a rule id" if rule.nil?
+          raise Insika::ValidationError, "negative list rule '#{rule}' is missing a pattern" if pattern.nil?
+
+          build_rule(rule: rule, pattern: pattern, note: h["note"].to_s.strip, line: i + 1)
+        end
+      end
+      private_class_method :array_rules
+
+      def self.build_rule(rule:, pattern:, note:, line:)
+        Rule.new(rule: rule, pattern: pattern, note: note, regexp: compile_regexp(pattern, rule, line))
+      end
+      private_class_method :build_rule
+
+      # "/…/flags" -> Regexp; anything else is a literal phrase (regexp nil).
+      def self.compile_regexp(pattern, rule, line)
+        return nil unless pattern.start_with?("/")
+
+        closing = pattern.rindex("/")
+        unless closing && closing > 0
+          raise Insika::ValidationError, "negative list rule '#{rule}' (line #{line}) has a malformed regex: #{pattern.inspect}"
+        end
+
+        source = pattern[1...closing]
+        flags = pattern[(closing + 1)..].to_s
+        Regexp.new(source, regexp_flags(flags, rule, line))
+      rescue RegexpError => e
+        raise Insika::ValidationError,
+              "negative list rule '#{rule}' (line #{line}) has a regex that does not compile: #{e.message}"
+      end
+      private_class_method :compile_regexp
+
+      def self.regexp_flags(flags, rule, line)
+        i = flags.include?("i")
+        m = flags.include?("m")
+        x = flags.include?("x")
+        unknown = flags.delete("i").delete("m").delete("x")
+        unless unknown.empty?
+          raise Insika::ValidationError,
+                "negative list rule '#{rule}' (line #{line}) has unsupported regex flags: #{unknown.inspect}"
+        end
+
+        (i ? Regexp::IGNORECASE : 0) | (m ? Regexp::MULTILINE : 0) | (x ? Regexp::EXTENDED : 0)
+      end
+      private_class_method :regexp_flags
+
+      def initialize(rules:)
+        @rules = rules
+      end
+
+      # -> [Rule] every rule whose pattern matched the text (word-boundary,
+      # case + accent folded for phrases; raw-or-folded for regexes). Empty =
+      # clean.
+      def matches(text)
+        haystack = text.to_s
+        folded = fold(haystack)
+        @rules.select { |r| rule_match?(r, haystack, folded) }
+      end
+
+      # -> [Rule] every rule whose pattern appears as a SUBSTRING (the stricter
+      # reading the CI spec uses on skill NAMES — a name containing a banned
+      # token is banned even mid-word).
+      def matches_name(name)
+        haystack = name.to_s
+        folded = fold(haystack)
+        @rules.select { |r| name_match?(r, haystack, folded) }
+      end
+
+      # -> Hash { rule => count } — what the run log records.
+      def reject_counts(text)
+        matches(text).each_with_object({}) { |r, acc| acc[r.rule] = (acc[r.rule] || 0) + 1 }
+      end
+
+      private
+
+      def rule_match?(rule, raw, folded)
+        if rule.regexp
+          rule.regexp.match?(raw) || rule.regexp.match?(folded)
+        else
+          pattern = fold(rule.pattern)
+          folded.match?(/(?:\A|\W)#{Regexp.escape(pattern)}(?:\W|\z)/i)
+        end
+      end
+
+      def name_match?(rule, raw, folded)
+        if rule.regexp
+          rule.regexp.match?(raw) || rule.regexp.match?(folded)
+        else
+          folded.include?(fold(rule.pattern))
+        end
+      end
+
+      # Case + accent fold for the pt-BR vowels — stdlib only.
+      def fold(text)
+        text.to_s.downcase.gsub(FOLD_RE, FOLD)
+      end
+    end
+  end
+end

data/lib/insika/harvest.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insika
+  # the one place harvest asks a model for anything.
+  #
+  # The engine's generic prompt (what a harvestable skill is, the answer
+  # shape, the provenance + grounding rules — "only reference IDs you saw in
+  # the evidence; never invent a product"). A pack `harvest.prompt` REPLACES
+  # this wholesale (the forge's half).
+  module Harvest
+    DEFAULT_PROMPT = <<~PROMPT.freeze
+      You are mining SKILLS from finished customer-service conversations of ONE
+      store agent, for a playbook the agent loads on demand. A skill is a
+      reusable procedure: WHEN to load it and the exact steps to follow. It is
+      NOT a fact about one customer, and NOT a rewrite of the agent's
+      instructions.
+
+      Answer with a single JSON array and NOTHING else. No prose, no fences.
+
+      Each element is an object with:
+      - "name" — the skill's key, short (max 64 chars), lowercase,
+        underscore-separated;
+      - "description" — one line (max 300 chars): what the skill is for;
+      - "body" — the SKILL.md body (max 6000 chars): the procedure itself;
+      - "triggers" — optional, up to 10 short words or phrases that should
+        surface this skill;
+      - "rationale" — optional, one line: what problem the skill solves;
+      - "evidence_turns" — optional, the message indexes in the conversations
+        that support it.
+
+      Rules:
+      - Reference products by their ID only — an ID you saw in the evidence.
+        Never invent a SKU or a product name; the engine rejects anything it
+        cannot verify (grounding).
+      - Never include a session id, a customer id or a tenant — the engine
+        stamps the origin itself.
+      - A skill every good agent already does is not a skill worth proposing.
+      - Fewer, better skills beat filling a quota.
+    PROMPT
+
+    # The safe-subset JSON Schema (array of objects — Workflow::Schema's
+    # subset, the house zero-dep validator). The miner rejects any key OUTSIDE
+    # this set and counts the drop: a model-authored `origin`/`agent` would be
+    # a provenance lie — the schema refuses it by not having the key, and the
+    # engine stamps origin itself.
+    SKILL_SCHEMA = Insika::Workflow::Schema.coerce({
+      "type" => "array",
+      "items" => {
+        "type" => "object",
+        "properties" => {
+          "name" => { "type" => "string" },
+          "description" => { "type" => "string" },
+          "body" => { "type" => "string" },
+          "triggers" => { "type" => "array", "items" => { "type" => "string" } },
+          "rationale" => { "type" => "string" },
+          "evidence_turns" => { "type" => "array", "items" => { "type" => "integer" } }
+        },
+        "required" => %w[name description body]
+      }
+    })
+
+    # The per-SKILL half (an item of SKILL_SCHEMA) — validated per element.
+    ITEM_SCHEMA = Insika::Workflow::Schema.coerce(SKILL_SCHEMA.json_schema["items"])
+
+    # The model's raw skills, filtered into data the command then filters
+    # (negative list, grounding, dedup — C6) and a human then gates.
+    # Pure over an injected `ask` — the Refinement::Proposer shape.
+    class Miner
+      # A model that answers with prose instead of JSON produces NOTHING,
+      # loudly — empty output must not read as "the traffic is clean".
+      class Unusable < Insika::ValidationError; end
+
+      MAX_NAME = 64
+      MAX_DESCRIPTION = 300
+      MAX_BODY = 6000
+      MAX_TRIGGERS = 10
+      MAX_TRIGGER = 80
+      MAX_RATIONALE = 500
+      MAX_EVIDENCE_TURNS = 20
+      # The window cap the RUN applies (C6): a candidate whose origin sessions
+      # are a lie of provenance must never be stamped from a window of 50.
+      MAX_SESSIONS = 5
+
+      ALLOWED_KEYS = %w[name description body triggers rationale evidence_turns].freeze
+      DROP_KEYS = %w[schema unknown_key oversized bad_turns duplicate capped].freeze
+      # The A/B audit counters: the distinct drops a run records and the
+      # first-10 audit reads back.
+
+      # ask:   ->(prompt) { "<raw model text>" } | something answering #content
+      #        (+ #input_tokens/#output_tokens/#cached_tokens for cost).
+      # model: the ref recorded as the candidate's `proposer` ("utility_model"
+      #        default).
+      attr_reader :model
+
+      def initialize(ask:, model: "utility_model")
+        @ask = ask
+        @model = model.to_s
+      end
+
+      # -> { skills: [ raw candidate hashes ],
+      #      dropped: { "schema" => N, "unknown_key" => N, "oversized" => N,
+      #                 "bad_turns" => N, "duplicate" => N, "capped" => N },
+      #      cost: { "spent" => N, "cached" => N } | nil }
+      # prompt: the pack prompt or DEFAULT_PROMPT (the caller resolved it).
+      # message_counts: the origin sessions' transcript sizes, in prompt order,
+      #   so `evidence_turns` indexes are validated against the sessions they
+      #   name (an index is valid if it fits at least one session).
+      # max_proposals: cap on surviving raw skills. Drops counted, never fixed.
+      def mine(prompt:, message_counts:, max_proposals: 10)
+        answer = @ask.call(prompt)
+        raw = parse(text_of(answer))
+        skills = []
+        dropped = DROP_KEYS.to_h { |k| [k, 0] }
+        seen = {}
+        raw.each do |item|
+          verdict, reason = classify(item, message_counts)
+          case verdict
+          when :keep
+            tuple = [item["name"].to_s, item["description"].to_s, item["body"].to_s]
+            if seen[tuple]
+              dropped["duplicate"] += 1
+            elsif skills.size >= max_proposals
+              dropped["capped"] += 1
+            else
+              seen[tuple] = true
+              skills << normalize(item)
+            end
+          when :drop
+            dropped[reason] += 1
+          end
+        end
+        { skills: skills, dropped: dropped, cost: cost_of(answer) }
+      end
+
+      private
+
+      def text_of(answer) = (answer.respond_to?(:content) ? answer.content : answer).to_s
+
+      # nil when the provider said nothing — never 0 (the Proposer's
+      # discipline). The cached prefix is INCLUDED in the spent total (E1: the
+      # run's cost is the harvest's only side spend).
+      def cost_of(answer)
+        return nil unless answer.respond_to?(:input_tokens) && answer.respond_to?(:output_tokens)
+
+        input = answer.input_tokens.to_i
+        output = answer.output_tokens.to_i
+        cached = answer.respond_to?(:cached_tokens) ? answer.cached_tokens.to_i : 0
+        spent = input + output + cached
+        spent.positive? ? { "spent" => spent, "cached" => cached } : nil
+      end
+
+      # Fences stripped, parsed STRICTLY (the Proposer's discipline): a model
+      # that improvises a schema fails here instead of producing half a skill.
+      def parse(raw)
+        body = raw.strip.gsub(/\A```(?:json)?\s*|\s*```\z/, "")
+        parsed = JSON.parse(body)
+        raise Unusable, "the miner's answer is not an array" unless parsed.is_a?(Array)
+
+        parsed
+      rescue JSON::ParserError => e
+        raise Unusable, "the miner's answer is not valid JSON: #{e.message}"
+      end
+
+      # -> [:keep, nil] | [:drop, drop_key]. The safety order: unknown keys
+      # first (a model-authored `origin` is a provenance lie), then the
+      # evidence bounds, then the schema, then the length caps.
+      def classify(item, message_counts)
+        return [:drop, "schema"] unless item.is_a?(Hash)
+        return [:drop, "unknown_key"] unless (item.keys.map(&:to_s) - ALLOWED_KEYS).empty?
+
+        turns = item["evidence_turns"]
+        if turns
+          return [:drop, "bad_turns"] if !turns.is_a?(Array) || turns.size > MAX_EVIDENCE_TURNS
+          span = Array(message_counts).map(&:to_i).max.to_i
+          return [:drop, "bad_turns"] if turns.any? { |t| !t.is_a?(Integer) || t.negative? || (span.positive? && t >= span) }
+        end
+
+        unless ITEM_SCHEMA.call(item).success?
+          return [:drop, "schema"]
+        end
+
+        return [:drop, "oversized"] if oversized?(item)
+
+        [:keep, nil]
+      end
+
+      def oversized?(item)
+        item["name"].to_s.length > MAX_NAME ||
+          item["description"].to_s.length > MAX_DESCRIPTION ||
+          item["body"].to_s.length > MAX_BODY ||
+          item["rationale"].to_s.length > MAX_RATIONALE ||
+          Array(item["triggers"]).size > MAX_TRIGGERS ||
+          Array(item["triggers"]).any? { |t| t.to_s.length > MAX_TRIGGER }
+      end
+
+      # The SAFE subset only — anything the model smuggled in has already
+      # dropped the skill.
+      def normalize(item)
+        item.slice(*ALLOWED_KEYS)
+      end
+    end
+
+    # Resolves WHICH model mines, and builds the ask. Profile -> platform
+    # utility_model -> nil (D12 — nil means "feature inert", never a guess).
+    # `ask_factory`/`llm` injectable (specs).
+    module MinerFactory
+      module_function
+
+      # config: the agent's `harvest` hash. -> Miner | nil
+      def build(config, utility_model: nil, ask_factory: nil, llm: nil)
+        ref = Coercion.presence(config && config.dig("miner", "model")) || Coercion.presence(utility_model)
+        return nil if ref.nil?
+
+        provider, model = split_ref(ref)
+        factory = ask_factory || ->(m, p) { ruby_llm_ask(m, p, llm: llm) }
+        Miner.new(ask: factory.call(model, provider), model: ref)
+      end
+
+      # "provider/model" -> [provider, model]; "model" -> [nil, model] — the
+      # ProposerFactory reading, one syntax for "which model" across features.
+      def split_ref(ref)
+        prov, name = ref.to_s.split("/", 2)
+        name ? [prov, name] : [nil, prov]
+      end
+
+      # Temperature 0: a rejected skill must be re-proposable deterministically.
+      # `ruby_llm` is required lazily so nothing loads a provider gem until a
+      # miner is actually configured (load_guard stays green).
+      def ruby_llm_ask(model, provider, llm: nil)
+        require "ruby_llm"
+        llm ||= RubyLLM
+        lambda do |prompt|
+          llm.chat(model: model, provider: provider, assume_model_exists: true)
+             .with_temperature(0).ask(prompt)
+        end
+      end
+    end
+  end
+end