insika 0.1.0 → 0.2.0

data/lib/insika/provider_error_classifier.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Insika
+  # Classifies provider/transport failures by ACTION (B9). Four kinds —
+  # the hermes/openclaw structural rule: NON-retryable checked first, so an
+  # error we do not recognize defaults to :fatal (a retry would hammer a
+  # poisoned credential; a fatal is retried only after the operator fixes the
+  # cause):
+  #
+  #   :fatal              401/402/403/400 (auth, billing, permanent quota,
+  #                       bad request, context too long) — retrying does not help.
+  #   :retryable          5xx/529/socket/timeout — the same call may succeed
+  #                       moments later.
+  #   :rate_limited_short a 429 that says "back off briefly" (RPM-scale).
+  #   :rate_limited_long  a 429 with a long retry-after — quota-scale.
+  #
+  # The classification is STRING-based (class names, no constant references):
+  # the core loads without ruby_llm, and the smoke-shim's fake RubyLLM is a
+  # drop-in. `retry_after` is read from the provider's own Retry-After header
+  # when the error carries a response, else a per-kind default.
+  class ProviderErrorClassifier
+    Classification = Data.define(:kind, :retryable, :retry_after) do
+      # the additive envelope fields — compacted so a retry_after-less fatal
+      # never invents one.
+      def to_h
+        { kind: kind, retryable: retryable, retry_after: retry_after }.compact
+      end
+    end
+
+    KINDS = %i[fatal retryable rate_limited_short rate_limited_long].freeze
+
+    # Above this a 429 means quota, not RPM (this is what tells the two apart —
+    # a short 429 wants a quick retry; a long one is a billing event).
+    SHORT_RETRY_LIMIT = 60 # seconds
+
+    DEFAULTS = {
+      retryable: 5,
+      rate_limited_short: 10,
+      rate_limited_long: 300
+    }.freeze
+
+    # RubyLLM's taxonomy (error.rb), matched by class name so the core stays
+    # ruby_llm-free at load time.
+    FATAL_ERROR_NAMES = %w[
+      RubyLLM::ContextLengthExceededError RubyLLM::BadRequestError
+      RubyLLM::UnauthorizedError RubyLLM::PaymentRequiredError RubyLLM::ForbiddenError
+    ].freeze
+    RATE_LIMITED_ERROR_NAME = "RubyLLM::RateLimitError"
+    RETRYABLE_ERROR_NAMES = %w[
+      RubyLLM::ServerError RubyLLM::ServiceUnavailableError RubyLLM::OverloadedError
+    ].freeze
+    RUBY_LLM_ERROR_NAMES = (
+      FATAL_ERROR_NAMES + [RATE_LIMITED_ERROR_NAME] +
+      RETRYABLE_ERROR_NAMES + ["RubyLLM::Error"]
+    ).freeze
+
+    # Transport failures while talking to the provider: connection
+    # refused/reset, DNS, TLS, timeouts (Faraday wraps its own names; the
+    # stdlib ones surface from raw sockets).
+    TRANSPORT_NAME_PATTERNS = [
+      /\AFaraday::/,
+      /\ASocketError\z/,
+      /\AIOError\z/,
+      /\AErrno::/,
+      /\ANet::(Read|Open)Timeout\z/,
+      /\ATimeout::Error\z/,
+      /\AOpenSSL::SSL::SSLError\z/
+    ].freeze
+
+    class << self
+      # -> Classification
+      def classify(error)
+        names = class_names(error)
+
+        # Non-retryable first (the structural rule): a known fatal is NEVER
+        # retried, and an unknown error defaults to fatal — never to retry.
+        return fatal if (names & FATAL_ERROR_NAMES).any?
+
+        return rate_limited(error) if names.include?(RATE_LIMITED_ERROR_NAME)
+
+        return retryable if (names & RETRYABLE_ERROR_NAMES).any?
+        return retryable if transport?(names)
+
+        # A generic RubyLLM::Error (or a raw HTTP error) still carries the
+        # status: 429 and 5xx are retryable regardless of the wrapping class.
+        case http_status(error)
+        when 429      then rate_limited(error)
+        when 500..599 then retryable
+        else fatal
+        end
+      end
+
+      # True when the error came from the provider call itself (RubyLLM
+      # family or transport) — the executor routes these to the :ruby_llm
+      # stage with a wrapped classification instead of :unknown.
+      def provider_error?(error)
+        names = class_names(error)
+        (names & RUBY_LLM_ERROR_NAMES).any? || transport?(names)
+      end
+
+      # The typed ProviderError the executor stores and emits.
+      def wrap(error)
+        c = classify(error)
+        Insika::ProviderError.new(
+          error.message || error.class.name,
+          kind: c.kind, retryable: c.retryable, retry_after: c.retry_after
+        )
+      end
+
+      private
+
+      def fatal
+        Classification.new(kind: :fatal, retryable: false, retry_after: nil)
+      end
+
+      def retryable
+        Classification.new(kind: :retryable, retryable: true,
+                           retry_after: DEFAULTS[:retryable])
+      end
+
+      def rate_limited(error)
+        ra = retry_after_header(error)
+        if ra && ra > SHORT_RETRY_LIMIT
+          Classification.new(kind: :rate_limited_long, retryable: true, retry_after: ra)
+        else
+          Classification.new(kind: :rate_limited_short, retryable: true,
+                             retry_after: ra || DEFAULTS[:rate_limited_short])
+        end
+      end
+
+      def class_names(error)
+        ([error.class.name] + Array(error.class.ancestors).map(&:name)).compact
+      end
+
+      def transport?(names)
+        names.any? { |n| TRANSPORT_NAME_PATTERNS.any? { |p| p.match?(n) } }
+      end
+
+      # The provider's own Retry-After (seconds), when the error carries a
+      # response. All access guarded — a bare double must not raise.
+      def retry_after_header(error)
+        headers = response_headers(error)
+        value = headers && (headers["retry-after"] || headers["Retry-After"])
+        value = value.to_s.strip
+        value.match?(/\A\d+\z/) ? value.to_i : nil
+      end
+
+      def http_status(error)
+        response = error.respond_to?(:response) ? error.response : nil
+        status = response && response.respond_to?(:status) ? response.status : nil
+        status&.to_i
+      end
+
+      def response_headers(error)
+        response = error.respond_to?(:response) ? error.response : nil
+        response && response.respond_to?(:headers) ? response.headers : nil
+      end
+    end
+  end
+end

data/lib/insika/queue_policy.rb

@@ -3,7 +3,7 @@
 require_relative "coercion"
 
 module Insika
-  # RFC-0015 §4 — what happens to an inbound message for a session that is ALREADY
+  # what happens to an inbound message for a session that is ALREADY
   # busy. Today the engine has exactly one answer, "it waits in line"; this names
   # that answer `followup` and adds three others:
   #
@@ -32,7 +32,7 @@ module Insika
   # `turn_timeout` because they are bounds on the same thing — how much work one
   # turn is allowed to absorb.
   class QueuePolicy
-    # All four of RFC-0015 are delivered, so there is no "specified but unshipped"
+    # All four of are delivered, so there is no "specified but unshipped"
     # tier any more — a mode outside this set is a typo, and it is refused rather than
     # approximated. Treating an unknown mode as `followup` would look exactly like a
     # mode that never fires.

data/lib/insika/recovery.rb

@@ -17,7 +17,7 @@ module Insika
   class Recovery
     SWEEP_SCOPE = "recovery"
 
-    # The per-boot-generation sweep claim (RFC-0016 E2). N workers share one
+    # The per-boot-generation sweep claim. N workers share one
     # store, and the sweep's "orphaned :running" test is per-process: a worker
     # booting while a sibling holds a live turn would see it as an orphan and
     # re-run it. So the TASK sweep runs once per boot generation — the first
@@ -52,27 +52,59 @@ module Insika
     # -> { resumed: [ids], failed: [ids] }
     # The initial sweep runs OUTSIDE the per-task rescue: a StoreError here
     # aborts the boot.
-    def run
+    #
+    # stale_after (seconds): the periodic tick's semantics instead of
+    # boot's. Only :queued/:running tasks untouched for longer than that are
+    # candidates — :waiting/:paused are idle by nature (a human wait), so
+    # staleness cannot tell a live one from a dead one, and they stay boot
+    # recovery's. The threshold exists because a live :running turn is bounded
+    # by turn_timeout: anything older cannot be alive.
+    def run(stale_after: nil)
       resumed = []
       failed = []
       # Ordered by created_at: tasks from the SAME session are reprocessed
       # in their original order. Global time ordering is harmless for standalone tasks.
-      # 1) interrupted (crash mid-flight) -> resume from the checkpoint.
-      @task_store.running_or_interrupted.sort_by(&:created_at).each { |task| process(task, resumed, failed) }
+      # 1) interrupted (crash mid-flight) -> resume from the checkpoint. Tick mode
+      #    narrows this to :running — the only mid-flight state staleness can judge.
+      running = stale_after ? @task_store.with_status(:running) : @task_store.running_or_interrupted
+      sweep(running, stale_after).each { |task| process(task, resumed, failed, tick: !stale_after.nil?) }
       # 2) queued but never started (turn in the SessionActor queue at crash time)
       #    -> re-run from scratch (the same resume_task handles :queued). Without
       #    this, a :queued turn in the volatile queue would be lost on kill -9.
-      @task_store.queued.sort_by(&:created_at).each { |task| process(task, resumed, failed) }
+      sweep(@task_store.queued, stale_after).each { |task| process(task, resumed, failed, tick: !stale_after.nil?) }
       log(:info, "recovery finished: #{resumed.size} resumed, #{failed.size} failed")
       { resumed: resumed, failed: failed }
     end
 
     private
 
+    # Boot mode (stale_after nil) takes the candidate list as-is; tick mode keeps
+    # only tasks untouched past the threshold — the liveness gate of.
+    def sweep(tasks, stale_after)
+      tasks = tasks.sort_by(&:created_at)
+      return tasks unless stale_after
+
+      cutoff = Time.now.utc - stale_after
+      tasks.select { |task| stale?(task, cutoff) }
+    end
+
+    def stale?(task, cutoff)
+      Time.iso8601(task.updated_at.to_s) < cutoff
+    rescue ArgumentError
+      true # an unreadable timestamp is not proof of life — treat as stale
+    end
+
     # Failing to resume ONE task does not bring down the boot: a non-store
     # dispatch/latest error -> mark :failed and continue. StoreError -> propagate
     # (aborts the boot).
-    def process(task, resumed, failed)
+    #
+    # tick: true flips ONE rescue: a ValidationError from the dispatch
+    # is ResumeTask's local liveness check ("task is running") — someone alive
+    # owns it, the normal case on a timer, so the task is SKIPPED for the next
+    # tick. At boot a ValidationError means corruption (nothing may be alive),
+    # so it still fails the task there. This is the trap defused in-process:
+    # the tick must never murder a live turn with its own recovery.
+    def process(task, resumed, failed, tick: false)
       # :queued never started (no checkpoint) but IS recoverable — ResumeTask
       # re-runs from the Command. An interrupted task requires a checkpoint;
       # without one, it is unrecoverable.
@@ -88,6 +120,15 @@ module Insika
       end
     rescue Insika::StoreError
       raise
+    rescue Insika::ValidationError => e
+      # Boot keeps the old contract (corruption -> :failed); the tick skips.
+      if tick
+        log(:info, "skipped (alive elsewhere): #{task.id} — #{e.message}")
+      else
+        fail_task(task.id, class_name: e.class.name, message: e.message, stage: "recovery")
+        failed << task.id unless failed.include?(task.id)
+        log(:warn, "failed to resume #{task.id}: #{e.class}: #{e.message}")
+      end
     rescue StandardError => e
       fail_task(task.id, class_name: e.class.name, message: e.message, stage: "recovery")
       failed << task.id unless failed.include?(task.id)

data/lib/insika/refinement/candidate.rb

@@ -4,7 +4,7 @@ require "securerandom"
 
 module Insika
   module Refinement
-    # ONE proposed change to an agent's instruction files (RFC-0013 §3.4). Data, not
+    # ONE proposed change to an agent's instruction files. Data, not
     # a diff of free text, and that is the load-bearing decision of the whole phase:
     #
     #   · an ANCHORED edit is reviewable — the operator reads three lines, not a
@@ -40,7 +40,7 @@ module Insika
 
     # A dropped edit and why. Kept ON the candidate rather than logged: "the model
     # proposed four things and one was stale" is exactly what an operator reviewing
-    # the loop's usefulness needs, and §10 asks them to judge precisely that.
+    # the loop's usefulness needs, and asks them to judge precisely that.
     Dropped = Data.define(:file, :op, :reason) do
       def to_h = { "file" => file, "op" => op, "reason" => reason }
     end
@@ -63,7 +63,7 @@ module Insika
                    "edits" => edits.map(&:to_h), "dropped" => dropped.map(&:to_h) }
     end
 
-    # The bounds, all config (§3.4). Defaults are deliberately small: what makes a
+    # The bounds, all config. Defaults are deliberately small: what makes a
     # diff reviewable is that it is short, and what keeps the gate's signal readable
     # is that a run changed few things.
     DEFAULT_LIMITS = { "max_edits" => 3, "max_bytes" => 1200, "max_total_growth" => 0.15 }.freeze
@@ -75,7 +75,7 @@ module Insika
 
       # raw:       { "proposer" =>, "rationale" =>, "edits" => [ … ] } (string keys)
       # allowlist: the agent's `refinement.files`. EMPTY MEANS NOTHING IS WRITABLE —
-      #            report-only (§3.1/§3.8), so every edit drops. Not "no restriction":
+      #            report-only, so every edit drops. Not "no restriction":
       #            an unset allowlist that meant "anything" would turn a missing
       #            config into the most permissive setting there is.
       # contents:  name => current content, for staleness and growth.

data/lib/insika/refinement/evidence_collector.rb

@@ -5,7 +5,7 @@ require "time"
 
 module Insika
   module Refinement
-    # RFC-0013 phase A. Reads a window of an agent's real traffic and emits RANKED
+    # Reads a window of an agent's real traffic and emits RANKED
     # FINDINGS — "here is what broke, how often, and in which conversations". No
     # model runs here and nothing is written to the agent: this is the evidence half
     # of the loop, and it is deliberately useful on its own.
@@ -17,7 +17,7 @@ module Insika
     #   ToolTraceStore  — per-session tool calls with ok/args/result (already masked
     #                     and clipped by the store itself)
     #
-    # Two signals of RFC-0013 §3.3 are NOT computed here, and that is a finding about
+    # Two signals of are NOT computed here, and that is a finding about
     # the engine rather than about an agent: guardrail decisions and edge-limit hits
     # are emitted as EVENTS and never persisted, so the only durable footprint they
     # leave is the canned safe reply in the transcript — which is exactly what the
@@ -42,7 +42,7 @@ module Insika
       # result delivered as a new turn — is persisted with `role: user` like any
       # other, because it is what the model saw. Counting those as the customer
       # repeating themselves turned the first production run into 219 false positives,
-      # every one of them the engine reading its own `<cacau_cep_obrigatorio>` back.
+      # every one of them the engine reading its own `<store_cep_required>` back.
       #
       # `MessageOrigin` is the structural answer and is preferred whenever a message
       # carries it. This regex stays for everything written before that field existed
@@ -188,12 +188,12 @@ module Insika
       # of an instruction the agent is not following. Heuristic on purpose (token overlap,
       # no model call); the snippet is PII-redacted.
       #
-      # "After the agent answered" is the load-bearing half, and RFC-0015 is what forced
+      # "After the agent answered" is the load-bearing half, and is what forced
       # it to be said out loud. Two customer messages in a row is now ORDINARY: `collect`
       # merges the fragments a person types into one turn and `steer` appends one into a
       # run in flight, so a turn legitimately holds two of them. Someone still typing is
       # not someone repeating themselves — and a steered message cannot be told apart in
-      # the transcript, because it correctly declares no origin (§7). The structure is the
+      # the transcript, because it correctly declares no origin. The structure is the
       # only honest signal: a reply has to sit between the two.
       def repetition_findings(session_ids)
         hits = session_ids.flat_map do |sid|
@@ -320,7 +320,7 @@ module Insika
 
       def words(text) = text.to_s.downcase.scan(/[[:alnum:]]+/).uniq
 
-      # Every reply the deployment may emit INSTEAD of a real answer: the RFC-0009
+      # Every reply the deployment may emit INSTEAD of a real answer: the
       # defaults, the agent's own overrides, and the edge limiter's reply (per-agent
       # first, then the platform setting).
       def canned_replies(profile)

data/lib/insika/refinement/gate.rb

@@ -2,8 +2,8 @@
 
 module Insika
   module Refinement
-    # Scores a candidate by RUNNING it (RFC-0013 §3.5). Not by asking a model whether
-    # the edit looks good — that measures nothing, and D3 says so in one line.
+    # Scores a candidate by RUNNING it. Not by asking a model whether
+    # the edit looks good — that measures nothing, and says so in one line.
     #
     #   1. clone the agent into a throwaway id (`<agent>-cand-<run8>`)
     #   2. copy its instruction files, apply the candidate's edits to the COPY
@@ -27,7 +27,7 @@ module Insika
       # it — nil when no turn carried usage. `cached` is how much of that came from
       # the prompt cache, kept separate because it is what explains one candidate
       # costing 8× another over the same cases. `tokens` is what the panel's budget
-      # (§3.9) spends and what the operator reads on the run: a gate is the expensive
+      # spends and what the operator reads on the run: a gate is the expensive
       # half of refinement and a loop whose cost is invisible is one nobody can decide
       # to keep.
       Report = Data.define(:candidate_id, :passed, :reason, :cases, :passed_cases,
@@ -48,9 +48,9 @@ module Insika
       # credential the operator can rotate.
       # capabilities_factory: -> an `Evals::HttpCapabilities` for the clone, or nil.
       # Without it a case whose `requires` the agent cannot satisfy RUNS and fails
-      # (RFC-0014 §3.2 says it must skip) — and then the gate and `evals/run.rb`, the
+      # (says it must skip) — and then the gate and `evals/run.rb`, the
       # two callers of the one evaluator, disagree about what the corpus even
-      # measures. §3.7 exists to prevent exactly that.
+      # measures. exists to prevent exactly that.
       def initialize(profiles:, agent_files:, goldens:, baselines:, transport_factory:,
                      capabilities_factory: nil, judge_factory: nil, tolerance: DEFAULT_TOLERANCE)
         @profiles = profiles
@@ -68,7 +68,7 @@ module Insika
       # not gate is more useful than an exception in a log.
       def score(agent_id:, candidate:, run_id:, tolerance: nil)
         cases = @goldens.for_agent(agent_id)
-        return refusal(candidate, "the agent has no golden cases — nothing to gate against (RFC-0013 D4)") if cases.empty?
+        return refusal(candidate, "the agent has no golden cases — nothing to gate against") if cases.empty?
 
         baseline = @baselines.get(agent_id)
         # Without an accepted state, `Baseline.compare` compares nothing and reports
@@ -109,7 +109,7 @@ module Insika
         # Measured, not reasoned: gating the real pilot agent with `settings["evals"]`
         # unset reported **6/6, no regression** against a baseline the same corpus had
         # just scored **2/6** — `produto-sem-cep` was judged 0.0 and "passed". Both
-        # candidates on the panel cleared. That is §3.7's failure exactly: the CLI and
+        # candidates on the panel cleared. That is's failure exactly: the CLI and
         # the gate, the two callers of the one evaluator, disagreeing about what the
         # corpus measures.
         judge = @judge_factory&.call

data/lib/insika/refinement/panel.rb

@@ -2,7 +2,7 @@
 
 module Insika
   module Refinement
-    # What a refinement run is allowed to SPEND (RFC-0013 §3.9, phase D).
+    # What a refinement run is allowed to SPEND.
     #
     # A panel of 3 proposers over a 7-case golden set is 3 model calls plus 21
     # replayed conversations, each a real turn with real tools. That is the honest
@@ -52,15 +52,15 @@ module Insika
                    "unmetered" => @unmetered }
     end
 
-    # The proposer PANEL (RFC-0013 §3.9 / §3.5): N models write N independent
+    # The proposer PANEL: N models write N independent
     # candidates, the gate scores each one by replaying the golden set, and the best
     # SURVIVOR becomes the proposal a human is asked about.
     #
     # Independent, not consensus-seeking. Two models agreeing on wording is weak
-    # evidence and a golden case passing is strong evidence (D7), so convergence only
+    # evidence and a golden case passing is strong evidence, so convergence only
     # ever breaks a tie between candidates the gate already ranked equal.
     #
-    # A panel of one is phase C unchanged, which is why there is no second code path:
+    # A panel of one is unchanged, which is why there is no second code path:
     # `refinement.proposer` (a single ref) resolves to a one-element panel.
     class Panel
       # One member of the panel: the candidate, WHO wrote it (more than one model when
@@ -80,7 +80,7 @@ module Insika
       # gate:      a Refinement::Gate (anything answering #score).
       # proposers: [Refinement::Proposer], already resolved by ProposerFactory.panel.
       # budget:    a Budget. The default is unlimited — a deployment that configured
-      #            none gets phase C's behaviour, which had no ceiling either.
+      #            none gets behaviour, which had no ceiling either.
       def initialize(gate:, proposers: [], budget: Budget.new, fan_out: nil)
         @gate = gate
         @proposers = Array(proposers)
@@ -112,7 +112,7 @@ module Insika
       # -> the best SURVIVOR, or nil when none passed.
       #
       # Highest graded score first; ties broken by the fewest edits (a smaller diff is
-      # a smaller bet), then by how many proposers converged on it (§3.5). `min_by`
+      # a smaller bet), then by how many proposers converged on it. `min_by`
       # over a negated tuple keeps the comparison in one place and stays stable, so
       # two genuinely indistinguishable candidates resolve to the first proposer the
       # operator listed rather than to whichever fiber finished first.
@@ -131,7 +131,7 @@ module Insika
 
       private
 
-      # All proposers at once, bounded by the RFC-0010 fan-out cap (§3.9 says the
+      # All proposers at once, bounded by the fan-out cap (says the
       # panel reuses it). Each is one blocking HTTP call to a provider, so the
       # wall-clock is the slowest model rather than their sum.
       #

data/lib/insika/refinement/proposer.rb

@@ -4,7 +4,7 @@ require "json"
 
 module Insika
   module Refinement
-    # Writes a CANDIDATE from a run's findings (RFC-0013 §3.4, phase C / PR 3b) — the
+    # Writes a CANDIDATE from a run's findings — the
     # one place in refinement where a model is asked for anything.
     #
     # It is deliberately the WEAKEST link and it is built that way: everything this
@@ -180,8 +180,8 @@ module Insika
 
     # Resolves WHICH model(s) write the candidate, and builds the ask.
     #
-    #   refinement.proposers  on the agent  (phase D: a PANEL, RFC-0013 §3.9)
-    #   -> refinement.proposer  ("deepseek/deepseek-chat" | "deepseek-chat")
+    #   refinement.proposers  on the agent  (a PANEL)
+    #   -> refinement.proposer  ("deepseek/deepseek-v4-flash" | "deepseek-v4-flash")
     #   -> the platform utility_model
     #   -> nothing, and the caller refuses. There is no default model here on purpose:
     #      guessing one spends an operator's provider budget without being asked.
@@ -189,17 +189,17 @@ module Insika
       module_function
 
       # config: the agent's `refinement` hash. -> Proposer | nil (the FIRST of the
-      # panel — phase C's single-proposer entry point, kept because a deployment that
+      # panel — single-proposer entry point, kept because a deployment that
       # never configured a panel is a panel of one).
       def build(config, utility_model: nil, ask_factory: nil, llm: nil)
         panel(config, utility_model: utility_model, ask_factory: ask_factory, llm: llm).first
       end
 
       # -> [Proposer], in configured order, DEDUPED by model ref and capped at the
-      # RFC-0010 fan-out (§3.9 says the panel reuses it). Two entries naming the same
+      # fan-out (says the panel reuses it). Two entries naming the same
       # model are one proposer: asking the same model twice at temperature 0 measures
-      # its variance, which is exactly what D6 rejected for the judges.
-      # `llm` (RFC-0017 A2): the graph's own RubyLLM context; nil = the global
+      # its variance, which is exactly what rejected for the judges.
+      # `llm`: the graph's own RubyLLM context; nil = the global
       # constant. Today only the deployment root builds a panel, and a deployment
       # is one graph per process — the seam exists so an embedded graph that ever
       # gains the refinement commands proposes on its own credentials.
@@ -213,7 +213,7 @@ module Insika
         end
       end
 
-      # `proposers` accepts either syntax — a bare ref ("deepseek/deepseek-chat") or
+      # `proposers` accepts either syntax — a bare ref ("deepseek/deepseek-v4-flash") or
       # the RFC's `{ "model" =>, "provider"? => }` — because the two already coexist in
       # this config (`proposer` is a bare ref, `judges` are hashes) and refusing one of
       # them would only teach operators which page they were reading.
@@ -248,7 +248,7 @@ module Insika
       # is actually configured.
       #
       # Returns the MESSAGE, not `.content`: the token counts ride on it and the
-      # budget (§3.9) is what spends them. `Proposer` reads either shape.
+      # budget is what spends them. `Proposer` reads either shape.
       def ruby_llm_ask(model, provider, llm: nil)
         require "ruby_llm"
         llm ||= RubyLLM

data/lib/insika/refinement_store.rb

@@ -4,7 +4,7 @@ require "securerandom"
 require "time"
 
 module Insika
-  # REFINEMENT DOMAIN store (RFC-0013, phase A). One record per refinement RUN:
+  # REFINEMENT DOMAIN store. One record per refinement RUN:
   # the window that was read, the ranked findings the EvidenceCollector produced,
   # and the run's outcome. RUNTIME data (it is derived from sessions/tasks/traces),
   # so it takes the raw `store:` like SessionStore/TaskStore — not the ConfigStore.
@@ -15,8 +15,8 @@ module Insika
   # Store contract orders lexicographically) and `latest_for` is its last element.
   # An agent id containing ":" would break that split, so it is rejected on write.
   #
-  # Phase A wrote no edits anywhere — a Run was a REPORT and every non-collecting
-  # status was terminal. Phase C (RFC-0013 §3.2) adds the rest of the lifecycle on
+  # wrote no edits anywhere — a Run was a REPORT and every non-collecting
+  # status was terminal. adds the rest of the lifecycle on
   # the SAME record, additively: a gated candidate and the operator's decision.
   #
   #   collecting ─▶ completed ─▶ gating ─▶ awaiting_approval ─▶ applied
@@ -24,13 +24,13 @@ module Insika
   #             ╰─▶ failed                    or the operator did)
   #
   # **The approval lives here, not in `PendingActionStore`** — a deliberate deviation
-  # from §3.6. That store is coupled to a suspended TURN: `ApproveAction` resolves
+  # from That store is coupled to a suspended TURN: `ApproveAction` resolves
   # the record and then calls `executor.approve(task_id)` to wake a fiber. A
   # refinement proposal has no turn and no fiber, so reusing it would mean inventing
   # a task id, a fake `tool` name, and a wake-up that must never do anything — and
   # the operator's approvals inbox would fill with rows that are not tool calls. The
-  # property §3.6 actually wanted is durability across a `kill -9`, and this store
-  # has had it since phase A.
+  # property actually wanted is durability across a `kill -9`, and this store
+  # has had it since.
   class RefinementStore
     include Coercion
 
@@ -42,7 +42,7 @@ module Insika
 
     # OPEN means "this run will change without anyone asking": work is in flight
     # (`collecting`, `gating`) or a human owes it an answer (`awaiting_approval`).
-    # Everything else is terminal — INCLUDING `completed`, which phase A already
+    # Everything else is terminal — INCLUDING `completed`, which already
     # treated that way and which stays true: a report is finished, and gating one is
     # a new deliberate action, not a continuation. (Widening `terminal?` here is what
     # the Studio's "latest report" lookup reads, so getting it wrong hides the report.)
@@ -50,7 +50,7 @@ module Insika
 
     # `candidate`/`gate` are the WINNER — the one proposal a human is asked about, and
     # the only thing `ResolveRefinement` ever applies. `candidates` is the whole panel
-    # (RFC-0013 §3.9, phase D): every candidate that was built, who wrote it, and how
+    # every candidate that was built, who wrote it, and how
     # it scored, including the ones that lost and the ones the budget never gated. A
     # phase-C run recorded one candidate and no panel; it still reads back correctly,
     # because a panel of one is the same shape.
@@ -118,7 +118,7 @@ module Insika
       end
     end
 
-    # -- phase C: the proposal's lifecycle -------------------------------
+    # the proposal's lifecycle -------------------------------
 
     # Attaches the candidate(s) under gate and moves the run to :gating. Only a
     # `completed` run can be gated: a report with no findings has nothing to propose
@@ -145,15 +145,15 @@ module Insika
     end
 
     # Records the gate's verdict. A PASS parks the run at :awaiting_approval — a
-    # human still has to say yes, which is the product and not a formality (D2). A
+    # human still has to say yes, which is the product and not a formality. A
     # FAIL is terminal as :rejected, with the gate report as the stated reason: the
     # same finding must re-surface with new evidence before anything is proposed
-    # again, so there is no silent retry loop (§3.6).
+    # again, so there is no silent retry loop.
     #
     # `report` is the WINNER's (or, when nothing survived, the most informative
     # refusal). `panel` is every scored entry — the store attaches it as-is and picks
     # the winning candidate out of it by id. Which candidate WON is the caller's
-    # ranking decision (§3.5); this store does not rank, it records. -> Run.
+    # ranking decision; this store does not rank, it records. -> Run.
     def gated(id, report:, panel: nil, cost: nil)
       update(id) do |record|
         unless record["status"] == "gating"