insika 0.1.0 → 0.2.0

data/lib/insika/channels/web.rb

@@ -6,7 +6,7 @@ require "securerandom"
 
 module Insika
   module Channels
-    # The web widget (RFC-0011 §5) — the FIRST Shape A channel, and the adoption
+    # The web widget — the FIRST Shape A channel, and the adoption
     # claim behind the whole RFC: an adopter pastes one tag into their site and has
     # a working agent, with no backend of their own and no build step.
     #
@@ -17,7 +17,7 @@ module Insika
     # no outbox, no claim and no `deliver` here — the three routes and a static
     # asset are the entire surface:
     #
-    #   POST /channels/web/sessions      mint an opaque session id (the engine's, §4.3)
+    #   POST /channels/web/sessions      mint an opaque session id (the engine's)
     #   POST /channels/web/messages      the turn, answered as SSE on this connection
     #   GET  /channels/web/asset/widget.js
     #
@@ -29,7 +29,7 @@ module Insika
     #   · an AGENT allowlist — a visitor addresses the agents the operator published
     #     to the widget, not every agent in the deployment;
     #   · an ORIGIN allowlist — exact match, no wildcards, and no "allow all" value;
-    #   · a mandatory chat RATE LIMIT (§5.4) — the channel answers `:disabled`
+    #   · a mandatory chat RATE LIMIT — the channel answers `:disabled`
     #     until one is configured, because a public endpoint with an LLM behind it
     #     and no ceiling is an unmetered bill waiting to happen.
     #
@@ -49,7 +49,7 @@ module Insika
       # An unversioned URL cannot be cached for a year — the next release would
       # never reach a browser that already has it. Short max-age + an ETag instead:
       # the common case is a 304 with no body, and an upgrade lands within minutes.
-      # (A deliberate narrowing of §5.2's "long-cache versioned URL": the install
+      # (A deliberate narrowing of's "long-cache versioned URL": the install
       # snippet in the RFC has no version in it, so there is nothing to bust.)
       ASSET_CACHE_CONTROL = "public, max-age=300"
 
@@ -67,7 +67,7 @@ module Insika
         new(origins: origins, agents: agents, id: id, chat_rate_limit: chat_rate_limit)
       end
 
-      # The probe §5.4's gate needs, asked exactly the way `EdgeLimiter` asks it at
+      # The probe's gate needs, asked exactly the way `EdgeLimiter` asks it at
       # turn time: the per-agent override first, the platform default second. Built
       # here so both composition roots wire the gate identically, and returned as a
       # lambda so the channel itself stays store-free.
@@ -149,7 +149,7 @@ module Insika
         { agent: agent, session_id: session_id, message: message }
       end
 
-      # §4.3's hard rule for a public channel: the ENGINE issues the id and the
+      #'s hard rule for a public channel: the ENGINE issues the id and the
       # client never proposes one. A visitor-supplied session id on an anonymous
       # endpoint is session hijacking by enumeration, so there is no create-on-write
       # path — `POST /messages` with an unknown id is a 404, not a new conversation.
@@ -159,7 +159,7 @@ module Insika
       # protocol: what to type, what to say while a tool runs, and how it ended.
       #
       # `:intermediate` and `:thinking` are deliberately absent. `:content` is the
-      # ANSWER (P19) — the model's narration on the way there is internal, and a
+      # ANSWER — the model's narration on the way there is internal, and a
       # widget that rendered it would show the customer the engine thinking out loud.
       def frame_for(event)
         case event.type

data/lib/insika/channels/webhook.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insika
+  module Channels
+    # A webhook as a Shape B "channel": the recipient of operator ALERTS
+    # (WS6). One instance per configured URL, registered in the ChannelRegistry
+    # so ChannelDelivery's outbox+claim+retry pipeline delivers the alert the
+    # same way it delivers a chat answer — at-most-once, bounded retry, boot
+    # sweep. Deliberately NOT Slack/CRM/anything: it POSTs the event as JSON and
+    # the consumer interprets it (the engine transports, it does not integrate).
+    #
+    # The target URL is operator configuration, so the POST crosses the SAME
+    # egress guard the Relay applies: https-only (fails closed), private/
+    # loopback/metadata targets and DNS-rebindable hosts blocked. Without it the
+    # `alerts.webhook` URL is an SSRF vector — a URL pointed at cloud metadata
+    # or an internal API exfiltrates alert events out of the boundary (WS6).
+    class Webhook
+      def initialize(url, http:, allow_http: false, allow_private: false)
+        @http = http
+        @allow_http = allow_http
+        @allow_private = allow_private
+      end
+
+      # The ChannelDelivery contract: -> HTTP status (200..299 = delivered).
+      # Every failure becomes a DeliveryError so the bounded retry records it.
+      def deliver(payload, to:, delivery_id: nil)
+        if (reason = egress_violation(to))
+          raise Insika::DeliveryError, "webhook egress blocked for #{to}: #{reason}"
+        end
+
+        result = @http.request(
+          method: :post, url: to,
+          headers: { "content-type" => "application/json" },
+          body: JSON.generate(payload)
+        )
+        result[:status].to_i
+      rescue Insika::DeliveryError
+        raise
+      rescue StandardError => e
+        raise Insika::DeliveryError, "webhook: #{e.message}"
+      end
+
+      private
+
+      # Resolved on EVERY delivery, not once at registration: a host that
+      # answered a public address yesterday can answer 169.254.169.254 today,
+      # and this POST carries the operator's alerts.
+      def egress_violation(url)
+        Insika::EgressGuard.violation(url, allow_http: @allow_http,
+                                           allow_private: @allow_private)
+      rescue URI::InvalidURIError
+        "invalid URL"
+      end
+    end
+  end
+end

data/lib/insika/chat_builder.rb

@@ -13,7 +13,8 @@ module Insika
   # Executor, injected as the `emit` callable.
   class ChatBuilder
     def initialize(tool_registry:, skill_catalog:, checkpoint_store:, event_stream:,
-                   hooks:, tool_catalog: nil, memory_store: nil, subagent_runner: nil)
+                   hooks:, tool_catalog: nil, memory_store: nil, subagent_runner: nil,
+                   tool_trace_store: nil)
       @tool_registry = tool_registry
       @skill_catalog = skill_catalog
       @checkpoint_store = checkpoint_store
@@ -21,7 +22,9 @@ module Insika
       @hooks = hooks
       @tool_catalog = tool_catalog
       @memory_store = memory_store
-      # RFC-0010: the object exposing #run_subagent (the Executor). nil = the
+      # only to trace load_skill, which is not enveloped — nil = no trace (parity).
+      @tool_trace_store = tool_trace_store
+      # the object exposing #run_subagent (the Executor). nil = the
       # spawn_subagent system tool is never wired (parity for a builder used
       # without delegation, e.g. some unit stubs).
       @subagent_runner = subagent_runner
@@ -69,9 +72,16 @@ module Insika
 
       # load_skill is a system default (outside the allowlist), otherwise
       # progressive disclosure breaks. allowed_skills comes from the Resolution
-      # (policy).
-      skill_names = Array(state.allowed_skills).map { |s| s.respond_to?(:name) ? s.name : s.to_s }
-      tools << Tools::LoadSkill.new(@skill_catalog, skill_names) unless skill_names.empty?
+      # (policy), minus the EAGER ones: their bodies are already in the prompt, so a
+      # call could only pay for a duplicate. Nothing lazy left -> the tool is not
+      # wired at all. Keeping it for the discretionary skills is deliberate: that
+      # call is the only record of which skill the model actually reached for.
+      skill_names = lazy_skill_names(state)
+      unless skill_names.empty?
+        tools << Tools::LoadSkill.new(@skill_catalog, skill_names,
+                                      trace_recorder: @tool_trace_store, state: state,
+                                      agent: state.profile.id)
+      end
 
       # remember is the memory-write system tool — wired only with
       # @memory_store present AND profile.memory (a double gate). Never enveloped.
@@ -80,24 +90,32 @@ module Insika
                                      event_stream: @event_stream, state: state)
       end
 
-      # spawn_subagent is the delegation system tool (RFC-0010) — wired only with a
+      # signal_stuck is the "I cannot proceed" system tool (WS5) — wired only
+      # when the agent opted in (`profile.stuck_signal`), never enveloped. It is a
+      # deterministic signal; the consumer decides what "stuck" means. Defensive
+      # read: a minimal profile double without the reader means off (nil = parity).
+      if state.profile.respond_to?(:stuck_signal) && state.profile.stuck_signal
+        tools << Tools::StuckSignal.new(state: state)
+      end
+
+      # spawn_subagent is the delegation system tool — wired only with a
       # runner present AND profile.subagents non-empty (a double gate, like
       # remember). Never enveloped: in the synchronous mode the child lives in the
       # parent's envelope. The runtime gate on WHICH agent is spawnable is the
       # parent's subagents allowlist, enforced in Executor#run_subagent.
       if @subagent_runner && !Array(state.profile.subagents).empty?
         tools << Tools::Subagent.new(runner: @subagent_runner, state: state)
-        # ...and its parallel sibling (RFC-0010 §A): fan-out N children at once.
+        # and its parallel sibling: fan-out N children at once.
         tools << Tools::Subagents.new(runner: @subagent_runner, state: state)
       end
 
       unless tools.empty?
-        # Item 30: the ONLY place the gem is told to run tool calls in parallel.
+        # the ONLY place the gem is told to run tool calls in parallel.
         # `:fibers` is not a preference but the only admissible mode — `:threads`
         # breaks ToolEnvelope's `Async::Task.current.with_timeout`, the SQLite
         # store's fiber semaphore, and the turn's own durability (mailbox,
         # approvals, cancellation are all expressed in fiber terms). The number
-        # the operator configured is OUR cap (D4, ToolAssembly#install_tool_gate);
+        # the operator configured is OUR cap (ToolAssembly#install_tool_gate);
         # the gem has none.
         if tool_concurrency_for(state)
           chat.with_tools(*tools, concurrency: :fibers)
@@ -109,9 +127,21 @@ module Insika
       chat
     end
 
+    # The skills the model still has to ask for: the Resolution's set minus the eager
+    # ones. Intersected by NAME against the catalog's own verdict (SkillCatalog#eager_for)
+    # so the tool and the level-1 list can never disagree about who is eager. A catalog
+    # without the reader (a unit stub) falls back to the whole set — parity.
+    def lazy_skill_names(state)
+      names = Array(state.allowed_skills).map { |s| s.respond_to?(:name) ? s.name : s.to_s }
+      return names unless @skill_catalog.respond_to?(:eager_for)
+
+      eager = @skill_catalog.eager_for(state.profile).map(&:name)
+      names - eager
+    end
+
     # The turn's effective tool concurrency (nil = serial), plus the ONE thing the
     # gate owes the operator: when the profile asked for parallel tool calls and
-    # this turn silently cannot have them (D3 — an approval-required tool would
+    # this turn silently cannot have them (an approval-required tool would
     # deadlock two fibers on the single per-task mailbox), say so once. Otherwise
     # the speedup just vanishes with no reason given. The rule itself lives in
     # TurnState; a state predating those readers (a unit stub) means off.
@@ -137,7 +167,7 @@ module Insika
                          ))
     end
 
-    # §11 R3: opt-in Anthropic prompt caching. When the agent enables
+    # R3: opt-in Anthropic prompt caching. When the agent enables
     # prompt_caching AND the resolved provider is Anthropic, wrap the system in
     # the provider's native Content helper with cache: true — ONE breakpoint at
     # the END of the system block. By Anthropic's prefix order
@@ -176,7 +206,7 @@ module Insika
     # History comes from the context/checkpoint. The {role:, content:} shape
     # tolerates string keys (JSON from the stores). `flatten(1)` dissolves the
     # Session provider's "eviction units" (an assistant+tool_results cycle grouped
-    # as one Array, §11 R1) back into a flat message stream.
+    # as one Array, R1) back into a flat message stream.
     #
     # tool_calls / tool_call_id are rehydrated ONLY when present, so a message
     # without them keeps the 2-arg shape the specs' FakeChat expects (no unknown
@@ -216,6 +246,14 @@ module Insika
       tool_calls = 0
       max_tool_calls = state.profile.limits[:max_tool_calls] || 50
 
+      # the loop detector. Needs #after_message + #add_message for the
+      # batch-boundary intervention; a chat without them (smoke shim, minimal
+      # double) stays bounded by max_tool_calls alone — never half-wired.
+      detector = if %i[after_message add_message].all? { |m| chat.respond_to?(m) }
+                   repeat = state.profile.limits[:max_tool_repeat] || Insika::AgentProfile::DEFAULT_LIMITS[:max_tool_repeat]
+                   Insika::LoopDetector.new(chat: chat, limit: repeat, emit: emit) if repeat >= 2
+                 end
+
       chat.before_tool_call do |tool_call|
         # call<->decorator correlation (side-effects/skip) — 1st line.
         state.current_tool_call = tool_call
@@ -224,9 +262,13 @@ module Insika
         tool_calls += 1
         if tool_calls > max_tool_calls
           raise Insika::TimeoutError.new("tool call limit exceeded (#{max_tool_calls})",
-                                          stage: :tool_limit)
+                                           stage: :tool_limit)
         end
 
+        # AFTER the count, BEFORE the call runs — a post-warning
+        # repeat raises here, so the stubborn loop pays for no extra call.
+        detector&.tool_call(tool_call.name, tool_call.arguments)
+
         # :tool pair: RubyLLM's callbacks are additive — the altered subject
         # feeds later hooks and the events, but does not rewrite the call the
         # model executes. A hook exception here aborts the turn.
@@ -246,9 +288,16 @@ module Insika
       end
 
       chat.after_tool_result do |result|
+        # the RAW result — the only place a Tool::Halt (halt_when) is
+        # still recognizable, and a halted batch must receive no intervention.
+        detector&.tool_result(result)
         result = @hooks.run_after(:tool, result)
         emit.call(:tool_result, { name: state.current_tool_name, result: result.to_s })
       end
+
+      # the intervention appends at the batch boundary (the Nth tool
+      # result closing) — never between two tool results of one batch.
+      chat.after_message { |message| detector.message_ended(message) } if detector
     end
   end
 end

data/lib/insika/circuit_state.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # The circuit breaker's durable state (WS3): one cell per
+  # (tenant, provider/model ref) holding the recent failures and when the
+  # circuit opened. The read-modify-write rides `@store.transaction` — the same
+  # discipline as the dispatch claim (A1): two concurrent failures of the same
+  # cell serialize, so the "10 failures in 60s" count is never lost to a race.
+  #
+  # States, standard semantics:
+  #   :closed    fewer than `after` failures in the `within` window — attempts flow.
+  #   :open      the window count is met AND the cooldown hasn't elapsed — the
+  #              edge FAIL-FASTS (no provider call) with retry_after = remaining
+  #              cooldown. Reached at the `after`-th failure, which stamps
+  #              opened_at.
+  #   :half_open the cooldown elapsed — the next attempt is the TRIAL: a success
+  #              closes (record_success clears the cell), a failure reopens
+  #              (a new failure count / opened_at).
+  class CircuitState
+    SCOPE = "circuit_state"
+
+    # Timestamps are pruned to COUNT_LIMIT — a pathological loop cannot grow the
+    # cell unboundedly (the window is 60s-wide; 100 reads and writes bounded).
+    COUNT_LIMIT = 100
+
+    Record = Data.define(:failures, :opened_at)
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # Records ONE failure for (tenant, ref). If this failure makes the window
+    # reach `after` and the circuit is not already open, it stamps opened_at
+    # (the instant the breaker trips). -> :closed (still closed) | :open (JUST
+    # tripped — closed->open, the ONLY transition that alerts) | :reopened (an
+    # already-tripped cell re-stamped: a half-open trial failed; the circuit is
+    # open again but the node already told the operator it is sick — no NEW
+    # alert (WS3)).
+    def record_failure(tenant:, ref:, after: 10, within: 60, now: Time.now)
+      key = key_for(tenant, ref)
+      @store.transaction do
+        record = load(key)
+        cutoff = (now.to_i - within)
+        retained = record.failures.select { |t| t > cutoff }.last(COUNT_LIMIT)
+        failures = (retained + [now.to_i]).last(COUNT_LIMIT)
+        opened_at = record.opened_at
+        tripped = :closed
+        if opened_at.nil?
+          if failures.size >= after
+            opened_at = now.to_i
+            tripped = :open
+          end
+        else
+          # the circuit was tripped before; a failure here can only be a HALF-OPEN
+          # trial that failed. Re-stamp opened_at so it RE-OPENS — a breaker that
+          # never restamps is one-shot: after the first cooldown every later turn
+          # is an unlocked half-open trial (WS3).
+          opened_at = now.to_i
+          tripped = :reopened
+        end
+        @store.set(SCOPE, key, { "failures" => failures, "opened_at" => opened_at })
+        tripped
+      end
+    end
+
+    # A successful attempt CLOSES the circuit: the cell is cleared so the
+    # failure window starts fresh (half-open trial success included).
+    def record_success(tenant:, ref:)
+      @store.delete(SCOPE, key_for(tenant, ref))
+    end
+
+    # -> :closed | :open | :half_open
+    def state(tenant:, ref:, after: 10, within: 60, cooldown: 300, now: Time.now)
+      record = load(key_for(tenant, ref))
+      opened = record.opened_at.to_i
+      # :closed needs BOTH doors shut: the window count is under `after` AND the
+      # circuit never tripped. A surviving opened_at tombstone keeps the circuit
+      # governed by the cooldown (open, then half-open) even after its original
+      # failures age out of the rolling window — only a SUCCESS clears it (WS3:
+      # a failed half-open trial must reopen, not silently close).
+      return :closed if record.failures.size < after && opened.zero?
+
+      return :open if opened.zero? || (now.to_i - opened) < cooldown
+
+      :half_open
+    end
+
+    # Seconds until the circuit can be retried (the remaining cooldown). nil
+    # while closed.
+    def retry_after(tenant:, ref:, cooldown: 300, now: Time.now)
+      record = load(key_for(tenant, ref))
+      return nil if record.failures.empty?
+
+      opened = record.opened_at.to_i
+      return nil if opened.zero?
+
+      remaining = cooldown - (now.to_i - opened)
+      remaining.positive? ? remaining : nil
+    end
+
+    private
+
+    def key_for(tenant, ref) = "#{tenant || 'platform'}:#{ref}"
+
+    def load(key)
+      record = @store.get(SCOPE, key)
+      return Record.new([], nil) if record.nil?
+
+      Record.new(Array(record["failures"]), record["opened_at"])
+    end
+  end
+end

data/lib/insika/coercion.rb

@@ -19,6 +19,14 @@ module Insika
     # Inverse of blank? — a usable, non-empty value.
     def present?(value) = !blank?(value)
 
+    # The operator-facing truthy: what a form checkbox ("1"), a JSON round-trip
+    # ("true") or the DSL (true) produce for an opt-in. One list, one reading —
+    # AgentProfile#stream_public?, SkillCatalog#blanket? and the Studio all consult
+    # it, so a value that opts in on one surface cannot opt out on another.
+    TRUTHY = [true, "true", "1", "yes", "on"].freeze
+
+    def truthy?(value) = TRUTHY.include?(value)
+
     # Bytes that come from outside the engine (sockets, pipes, subprocesses)
     # arrive tagged BINARY, or as UTF-8 carrying invalid sequences. Both break
     # `JSON.generate` the moment the text has an accent or an emoji — today a

data/lib/insika/commands/agent_payload.rb

@@ -10,9 +10,11 @@ module Insika
     module AgentPayload
       # Fields accepted by AgentProfile.build (order irrelevant).
       FIELDS = %i[id model provider base_prompt prompt_files tools_allow tools_deny
-                  tools_allow_groups skills context_providers workflows_allow policies
+                  tools_allow_groups skills skills_eager context_providers workflows_allow policies
                   prompt_refs limits approvals_required capabilities subagents tools_deferred
-                  memory params model_policy guardrails refinement capabilities_declared
+                  memory prompt_caching tool_output_compression budget reliability alerts
+                  stuck_signal
+                  params model_policy guardrails refinement capabilities_declared
                   edge_stream metadata].freeze
 
       module_function
@@ -25,7 +27,7 @@ module Insika
         out[:provider] = presence(out[:provider])&.to_sym if out.key?(:provider)
         out[:policies] = Array(out[:policies]).map(&:to_sym) if out.key?(:policies)
         out[:limits] = out[:limits].transform_keys(&:to_sym) if out[:limits].is_a?(Hash)
-        # generation params (v2, §10) consumed by symbol key (temperature/max_tokens/thinking).
+        # generation params consumed by symbol key (temperature/max_tokens/thinking).
         out[:params] = out[:params].transform_keys(&:to_sym) if out[:params].is_a?(Hash)
         out
       end

data/lib/insika/commands/create_agent.rb

@@ -17,13 +17,13 @@ module Insika
         attrs = AgentPayload.attrs(command.payload)
         id = AgentPayload.presence(attrs[:id])
         raise Insika::ValidationError, "id is required" if id.nil?
-        # model is OPTIONAL as of v2 (§10): omitted -> resolves the platform
+        # model is OPTIONAL as of v2: omitted -> resolves the platform
         # default_model (Settings) at turn start. An agent with neither its own
         # model nor a platform default fails clearly at the first turn.
         raise Insika::ValidationError, "agent '#{id}' already exists" if @profile_source.fetch(id)
 
         profile = Insika::AgentProfile.build(**attrs)
-        # RFC-0010 §4.4: definition-time cycle + depth check. Only a profile that
+        # definition-time cycle + depth check. Only a profile that
         # introduces edges (non-empty subagents) can create a violation — a
         # childless agent is always a safe leaf. Raises SubagentError (a
         # ValidationError) BEFORE persisting, so a bad graph never lands.

data/lib/insika/commands/create_session.rb

@@ -21,7 +21,7 @@ module Insika
         vars = command.payload[:vars] || command.payload["vars"] || {}
         raise Insika::ValidationError, "vars must be a Hash" unless vars.is_a?(Hash)
 
-        # Per-chat model pin (v2, §10): `model`/`provider` on the payload become a
+        # Per-chat model pin: `model`/`provider` on the payload become a
         # reserved, collision-safe slot in vars (never rendered in the prompt — the
         # Request provider skips "__"-prefixed vars). The ModelResolver reads it as
         # the highest-precedence layer (Chat > Agent > platform default).

data/lib/insika/commands/delete_llm_provider.rb

@@ -6,7 +6,7 @@ module Insika
   module Commands
     # Control command: removes an LLM provider from the
     # LLMProviderStore. Idempotent (`existed: false` if there was none). UNDOES the
-    # config in RubyLLM at runtime (§9.5): when the provider existed, calls
+    # config in RubyLLM at runtime: when the provider existed, calls
     # `configurator.unapply(api)` clearing the global key/base — without a restart. A provider
     # that RubyLLM does not recognize degrades gracefully (unapply: false, nothing to
     # undo). -> { existed: bool }.

data/lib/insika/commands/delete_skill.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: removes an authored skill from the SkillStore and RELOADS the
+    # catalog. -> { name, agent, deleted }.
+    #
+    # With `agent`, it deletes only that agent's SPECIALIZATION — the shared skill
+    # stays exactly where it was, and the agent falls back to it on the next turn.
+    # "Stop specializing this" is the inverse of the specialize action, and it must not
+    # be expressible as "delete the skill".
+    #
+    # Deleting a shared skill does NOT touch any allowlist: an agent left naming a
+    # skill that no longer exists sees nothing (the catalog resolves nothing), which is
+    # the same outcome as never having allowed it.
+    class DeleteSkill
+      def initialize(skill_store:, skill_catalog:, event_stream:)
+        @skill_store = skill_store
+        @skill_catalog = skill_catalog
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        name = AgentPayload.presence(p[:name])
+        agent = AgentPayload.presence(p[:agent])
+        raise Insika::ValidationError, "name is required" if name.nil?
+
+        deleted = @skill_store.delete(name, agent: agent)
+        raise Insika::NotFoundError, "skill '#{name}' not found#{" for agent '#{agent}'" if agent}" unless deleted
+
+        @skill_catalog.reload
+        @event_stream.emit(Insika::Event.new(
+                             type: :skill_deleted, data: { name: name, agent: agent }.compact,
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { name: name, agent: agent, deleted: true }
+      end
+    end
+  end
+end

data/lib/insika/commands/gate_refinement.rb

@@ -4,21 +4,21 @@ require "time"
 
 module Insika
   module Commands
-    # Control command (RFC-0013 phase C): takes a CANDIDATE for a completed
+    # Control command: takes a CANDIDATE for a completed
     # refinement run, validates it against the agent's write allowlist, and scores it
     # by actually running it — clone the agent, apply the edits to the clone, replay
-    # the golden set, compare to the accepted baseline (§3.5).
+    # the golden set, compare to the accepted baseline.
     #
     # Synchronous like `run_refinement`, and for the same reason: it is operator-paced
     # work with a human waiting on the answer. It is NOT cheap — the replay is a real
     # conversation per golden case — so it is fired deliberately, never on a timer
-    # (D8: the engine has no scheduler and this RFC does not add one).
+    # (the engine has no scheduler and this RFC does not add one).
     #
     # Payload:
     #   run_id     (required) a run in :completed — the evidence the candidate answers
     #   candidate  { proposer?, rationale?, edits: [ {file, op, anchor?, before, after,
     #              addresses?} ] } — or omit it and pass `propose: true` to have the
-    #              configured model(s) write one from the run's findings (§3.4).
+    #              configured model(s) write one from the run's findings.
     #   propose    truthy — write the candidate with the agent's proposer PANEL.
     #   tolerance  Float — overrides the configured judge-score tolerance for this gate
     #
@@ -30,14 +30,14 @@ module Insika
     # forgot the candidate should get an error, not a bill.
     #
     # Two refusals happen BEFORE anything is cloned, because both mean the operator
-    # has not actually enabled this: an agent still in `mode: report` (§3.8 — writing
+    # has not actually enabled this: an agent still in `mode: report` (writing
     # is opt-in and an absent config is report-only), and a candidate whose every edit
     # was dropped (stale, off-allowlist, over budget). Neither is worth a provider bill.
     #
-    # Phase D (§3.9) makes the proposal a PANEL and the run's spend a BUDGET. The
+    # makes the proposal a PANEL and the run's spend a BUDGET. The
     # command's shape does not change: N models write N candidates, the gate scores
     # each, and the best survivor is the one proposal a human is shown. A deployment
-    # with one proposer and no budget behaves exactly as phase C did.
+    # with one proposer and no budget behaves exactly as did.
     class GateRefinement
       WRITE_MODES = %w[propose auto_apply].freeze
 
@@ -49,7 +49,7 @@ module Insika
 
       # proposer_factory: ->(refinement_config) { [Refinement::Proposer] | Proposer | nil }.
       # Optional — a deployment with none can still gate a candidate that arrives from
-      # the API, which is exactly what phase C shipped before the proposer existed.
+      # the API, which is exactly what shipped before the proposer existed.
       # resolver: the :resolve_refinement handler, used ONLY for `mode: auto_apply`.
       # Reusing it rather than writing files here is what keeps auto-apply honest: it
       # goes through the same staleness re-check, the same versioned write and the
@@ -125,7 +125,7 @@ module Insika
       end
 
       # Editing an agent's instructions is opt-in, explicitly, per agent — the whole
-      # point of §3.1 is that the reachable surface is small and declared. An absent
+      # point of is that the reachable surface is small and declared. An absent
       # or `report` config is not "not configured yet", it is a NO.
       def require_write_mode!(config, agent_id)
         mode = Coercion.presence(config["mode"]) || "report"
@@ -148,7 +148,7 @@ module Insika
         raise ArgumentError, "run #{run.id} is #{run.status}, expected completed"
       end
 
-      # The model(s) write the candidates (§3.4/§3.9). Each is shown the run's findings
+      # The model(s) write the candidates. Each is shown the run's findings
       # and the CURRENT content of the allowlisted files only — the same allowlist the
       # builder then enforces, so a proposal cannot even name a file it may not touch.
       #
@@ -194,7 +194,7 @@ module Insika
         allow
       end
 
-      # `mode: auto_apply` (§3.6, D2) — the ONE path where a prompt changes with no
+      # `mode: auto_apply` — the ONE path where a prompt changes with no
       # human in the loop. Off by default and deliberately narrow: it needs the mode,
       # a gate PASS with zero regressions, and a diff under `auto_apply_max_edits`.
       # Everything else parks at :awaiting_approval, which is the product.
@@ -232,7 +232,7 @@ module Insika
       end
 
       # Counts and ids only, never file content: these events reach the operator
-      # stream and the same rule the findings follow applies here (§5).
+      # stream and the same rule the findings follow applies here.
       def emit(type, run, **data)
         @event_stream.emit(Insika::Event.new(
                              type: type,

data/lib/insika/commands/import_mcp_tools.rb

@@ -4,7 +4,7 @@ require "time"
 
 module Insika
   module Commands
-    # Control command: LIVE MCP ingestion (Phase 7, Step E). Receives the NAME of
+    # Control command: LIVE MCP ingestion. Receives the NAME of
     # an MCP instance, delegates to McpToolIngestor (discovers via an injectable client
     # -> builds the manifest -> reuses :import_tools: batch upsert + hot reload)
     # and returns the per-tool report in the shape of :import_tools, plus

data/lib/insika/commands/import_tools.rb

@@ -4,18 +4,18 @@ require "time"
 
 module Insika
   module Commands
-    # BATCH ingestion of data-tools from a manifest (Phase 7, Step B).
+    # BATCH ingestion of data-tools from a manifest.
     # Normalizes each tool (defaults + envelope adapter + endpoint→url + secret/
     # env) via ToolManifest, UPSERTs it into the ToolStore, and RELOADS the overlay +
-    # catalog ONCE at the end — takes effect without a restart (NF3). Idempotent
+    # catalog ONCE at the end — takes effect without a restart. Idempotent
     # (re-importing reconciles). Injects the deployment's `{{secret.*}}`/`{{env.*}}`
-    # resolvers (D6/open-q2): the secret NEVER comes in the manifest.
+    # resolvers: the secret NEVER comes in the manifest.
     #
     # ISOLATED PARTIAL FAILURE (R4): a malformed tool (invalid envelope, missing
     # endpoint, unconfigured secret, collision with a code tool, invalid url)
     # does NOT bring down the batch — it becomes an entry in `errors[]`. Only a STRUCTURAL error in the
     # manifest (defaults/tools of the wrong type) raises (transport -> 422).
-    # Per-tool report in the shape of the Phase 6 pack importer.
+    # Per-tool report in the shape of the pack importer.
     #   -> { version, created: [names], updated: [names], errors: [{tool,error}] }
     class ImportTools
       def initialize(tool_store:, registry:, tool_catalog:, event_stream:, secrets: ENV, env: ENV)