rubik 0.1.0

data/lib/rubik/tools/builtins/task.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+require_relative "../output"
+require_relative "../../coeffects"
+
+module Rubik
+  module Tools
+    # Tool for controlling long-running asynchronous background processes
+    # (servers, test runners, compilers, watch modes) (Plan 93).
+    class ManageTaskTool < BaseTool
+      REQUIRES = [Rubik::Coeffects::TASK_MANAGER].freeze
+
+      attr_accessor :task_manager, :runtime_context
+
+      DECLARATION = Declaration.new(
+        name: "manage_task", aliases: ["task", "tasks", "background_task", "bg_task"],
+        description: "Manage asynchronous background processes (servers, builders, long test runs). " \
+                     "Actions: 'start', 'list', 'status', 'logs', 'send_input', 'kill'.",
+        risk: :execute, archetypes: [:coder], maestro_blocked: true, # gate scopes to action 'start'; orchestration actions stay direct
+        params_schema: {
+          type: "object",
+          properties: {
+            action: {
+              type: "string",
+              enum: ["start", "list", "status", "logs", "send_input", "kill"],
+              description: "Action to perform: 'start', 'list', 'status', 'logs', 'send_input', or 'kill'"
+            },
+            task_id: { type: "string", description: "The task ID (e.g. 'task-1'). Required for status, logs, send_input, kill." },
+            command: { type: "string", description: "The shell command to run. Required for 'start'." },
+            input: { type: "string", description: "Input text to send to stdin. Required for 'send_input'." },
+            tail: { type: "integer", description: "Number of lines to read for 'logs' (default: 50)." }
+          },
+          required: ["action"]
+        }
+      )
+      def initialize(task_manager: nil, guard: nil, runtime_context: nil)
+        super(DECLARATION)
+        @task_manager = task_manager
+        @guard = guard
+        @runtime_context = runtime_context
+      end
+
+      def execute(args = {})
+        action = (args["action"] || args[:action]).to_s.downcase.strip
+        task_mgr = resolve_task_manager
+        return ToolOutput.error("TaskManager is not available in the runtime context.") unless task_mgr
+
+        case action
+        when "start"
+          handle_start(task_mgr, args)
+        when "list"
+          handle_list(task_mgr)
+        when "status"
+          handle_status(task_mgr, args)
+        when "logs"
+          handle_logs(task_mgr, args)
+        when "send_input"
+          handle_send_input(task_mgr, args)
+        when "kill"
+          handle_kill(task_mgr, args)
+        else
+          ToolOutput.error("Unknown action '#{action}'. Allowed actions: start, list, status, logs, send_input, kill.")
+        end
+      rescue Rubik::Security::BlockedWriteError => e
+        require_relative "exec" unless defined?(Rubik::Tools::RunCommandTool)
+        ToolOutput.error(Rubik::Tools::RunCommandTool.blocked_guidance(e))
+      rescue StandardError => e
+        ToolOutput.error("manage_task error (#{action}): #{e.message}")
+      end
+
+      private
+
+      def resolve_task_manager
+        @task_manager || (@runtime_context.respond_to?(:get) ? Rubik::Coeffects.get(@runtime_context, Rubik::Coeffects::TASK_MANAGER) : nil)
+      end
+
+      def extract_task_id(args)
+        (args["task_id"] || args[:task_id] || args["taskId"] || args[:taskId]).to_s.strip
+      end
+
+      def extract_command(args)
+        (args["command"] || args[:command] || args["cmd"] || args[:cmd]).to_s.strip
+      end
+
+      def handle_start(task_mgr, args)
+        cmd = extract_command(args)
+        return ToolOutput.error("Missing required parameter 'command' for action 'start'.") if cmd.empty?
+
+        task = task_mgr.start(cmd, ctx: @runtime_context)
+        "Task started: #{task.id} (PID #{task.pid})\nCommand: #{task.command}\nStatus: #{task.status.to_s.upcase}"
+      end
+
+      def handle_list(task_mgr)
+        tasks = task_mgr.list.sort_by { |t| t.started_at || Time.at(0) }
+        return "No background tasks currently running or tracked." if tasks.empty?
+
+        lines = ["=== Background Tasks (#{tasks.size}) ==="]
+        tasks.each do |t|
+          dur = t.running? ? "up #{t.uptime.round(1)}s" : "exit #{t.exit_code}"
+          lines << "  • [#{t.id}] #{t.status.to_s.upcase} (PID #{t.pid}, #{dur}): #{t.command}"
+        end
+        lines.join("\n")
+      end
+
+      def handle_status(task_mgr, args)
+        task_id = extract_task_id(args)
+        return ToolOutput.error("Missing required parameter 'task_id' for action 'status'.") if task_id.empty?
+
+        task = task_mgr.get(task_id)
+        return ToolOutput.error("Task '#{task_id}' not found.") unless task
+
+        <<~STATUS.chomp
+          Task: #{task.id}
+          Status: #{task.status.to_s.upcase}
+          PID: #{task.pid}
+          Uptime: #{task.uptime.round(1)}s
+          Exit Code: #{task.exit_code.inspect}
+          Command: #{task.command}
+        STATUS
+      end
+
+      def handle_logs(task_mgr, args)
+        task_id = extract_task_id(args)
+        return ToolOutput.error("Missing required parameter 'task_id' for action 'logs'.") if task_id.empty?
+
+        tail = (args["tail"] || args[:tail] || 50).to_i
+        task = task_mgr.get(task_id)
+        return ToolOutput.error("Task '#{task_id}' not found.") unless task
+
+        lines = task.ring_buffer.tail(tail)
+        return "No logs recorded for task '#{task_id}' yet." if lines.empty?
+
+        "=== Logs for #{task.id} (last #{lines.size} lines) ===\n#{lines.join("\n")}"
+      end
+
+      def handle_send_input(task_mgr, args)
+        task_id = extract_task_id(args)
+        return ToolOutput.error("Missing required parameter 'task_id' for action 'send_input'.") if task_id.empty?
+
+        input = args["input"] || args[:input]
+        return ToolOutput.error("Missing required parameter 'input' for action 'send_input'.") if input.nil?
+
+        ok = task_mgr.send_input(task_id, input)
+        if ok
+          "Input sent to task '#{task_id}'."
+        else
+          ToolOutput.error("Failed to send input to task '#{task_id}'. Task may not be running or stdin is closed.")
+        end
+      end
+
+      def handle_kill(task_mgr, args)
+        task_id = extract_task_id(args)
+        return ToolOutput.error("Missing required parameter 'task_id' for action 'kill'.") if task_id.empty?
+
+        task = task_mgr.get(task_id)
+        return ToolOutput.error("Task '#{task_id}' not found.") unless task
+
+        if task.status == :running
+          task_mgr.kill(task_id)
+          "Task '#{task_id}' killed. (PID #{task.pid})"
+        else
+          "Task '#{task_id}' is already #{task.status.to_s.upcase} (exit code: #{task.exit_code.inspect})."
+        end
+      end
+    end
+  end
+end

data/lib/rubik/tools/builtins/unsynthesize.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+# UnsynthesizeTool: the delete twin of the synthesize pair (Plan 54 D-3 kept
+# synthesis.rb as the write side; this extraction keeps every builtin domain
+# file under the 350-line architectural guard while the builtin count grew).
+# Deletes a previously synthesized command or tool from both the live registry
+# and disk (project or global scope), restoring the previous value on context
+# dispose (revertible inverse, AGENTS.md §1.A).
+
+require_relative "../base"
+require_relative "../output"
+require_relative "../../runtime"
+
+module Rubik
+  module Tools
+    class UnsynthesizeTool < BaseTool
+      DECLARATION = Declaration.new(
+        name: "unsynthesize", aliases: ["delete_tool", "delete_command", "remove_tool", "remove_command"],
+        description: "Delete a previously synthesized command or tool from both the live registry and disk (project or global scope)",
+        risk: :write, maestro_blocked: false, # self-evolution plane (TOOLS.md maestro policy)
+        params_schema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Name of the command (without '!') or tool to delete" },
+            kind: { type: "string", enum: ["command", "tool"], description: "Whether to delete a command or a tool" },
+            scope: { type: "string", enum: ["session", "project", "global"],
+                     description: "Storage scope: session (live only), project (.rubik/...), global (~/.rubik/...)" }
+          },
+          required: ["name", "kind"]
+        }
+      )
+      def initialize(shell = nil, tool_registry = nil, overlay_storage = nil, legacy_runtime_manager = nil, runtime_manager: nil)
+        super(DECLARATION)
+        @shell = shell
+        @tool_registry = tool_registry
+        @overlay_storage = overlay_storage || Rubik::Runtime::OverlayStorage.new
+        @runtime_manager = runtime_manager || legacy_runtime_manager
+      end
+
+      def execute(args = {})
+        name = (args["name"] || args[:name]).to_s.strip.delete_prefix("!")
+        kind = (args["kind"] || args[:kind]).to_s.downcase.to_sym
+        scope = (args["scope"] || args[:scope] || "session").to_s.downcase.to_sym
+
+        return ToolOutput.error("Name cannot be empty") if name.empty?
+        return ToolOutput.error("kind must be 'command' or 'tool'") unless [:command, :tool].include?(kind)
+
+        kind == :command ? delete_command(name, scope) : delete_tool(name, scope)
+      end
+
+      private
+
+      def delete_command(name, scope)
+        clean = name.to_s.downcase.delete_prefix("!")
+        previous_meta = @shell&.commands&.[](clean)
+
+        # Fail-closed: never unsynthesize a built-in command (custom: false).
+        # Symmetric with the synthesize twin's refusal to shadow built-ins.
+        return ToolOutput.error("Cannot delete built-in command '!#{clean}'") if previous_meta && previous_meta[:custom] == false
+
+        @shell&.unregister_command(clean)
+
+        if [:project, :global].include?(scope)
+          res = @overlay_storage.delete_command(name, scope: scope)
+          return ToolOutput.error("Failed to delete command from disk: #{res[:error]}") unless res[:ok]
+        end
+
+        # Revertible inverse (AGENTS.md §1.A): restore the previous command on
+        # dispose if one existed before deletion.
+        if @runtime_manager&.context.is_a?(Rubik::Runtime::Context)
+          @runtime_manager.context.on_dispose do
+            if previous_meta
+              @shell.register_command(clean, description: previous_meta[:description],
+                                             custom: previous_meta[:custom], audience: previous_meta[:audience],
+                                      &previous_meta[:handler])
+            end
+          end
+        end
+
+        "Successfully deleted command '!#{clean}' [scope: #{scope}]."
+      end
+
+      def delete_tool(name, scope)
+        clean = name.to_s.downcase.gsub(/[^a-z0-9_]/, "_")
+
+        # Fail-closed: never unsynthesize a built-in tool. Symmetric with the
+        # synthesize twin's refusal to shadow built-ins.
+        return ToolOutput.error("Cannot delete built-in tool '#{clean}'") if @tool_registry&.origin(clean) == :builtin
+
+        previous_tool = @tool_registry&.get(clean)
+        previous_origin = previous_tool ? @tool_registry.origin(clean) : nil
+
+        @tool_registry&.unregister(clean)
+
+        if [:project, :global].include?(scope)
+          res = @overlay_storage.delete_tool(name, scope: scope)
+          return ToolOutput.error("Failed to delete tool from disk: #{res[:error]}") unless res[:ok]
+        end
+
+        # Revertible inverse (AGENTS.md §1.A): restore the previous tool on dispose.
+        if @runtime_manager&.context.is_a?(Rubik::Runtime::Context)
+          @runtime_manager.context.on_dispose do
+            @tool_registry.swap(clean, previous_tool, origin: previous_origin || :overlay) if previous_tool
+          end
+        end
+
+        "Successfully deleted tool '#{clean}' [scope: #{scope}]."
+      end
+    end
+  end
+end

data/lib/rubik/tools/builtins/vakanuvis.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+require_relative "../output"
+require_relative "../../coeffects"
+require_relative "../../storage/vakanuvis"
+
+module Rubik
+  module Tools
+    # Talep düzlemi (plan 2026-10-04 §4.5, K7): maestro'nun kronikçi
+    # masası. Dört eylemin hepsi Vakanüvis::Harness'e delege olur — recall
+    # tamamen deterministiktir (LLM'siz), record/forget Düzlem 1 yazma
+    # disipliniyle (ref minting, upsert, supersede) yazar, digest asenkron
+    # kuyruklanır ve deterministik makbuz döner (maestro turn'ü asla LLM
+    # bekletilmez). Görünürlük: yalnız kök/maestro düzlemi (archetypes
+    # boş; ScopedRegistry ROOT_ONLY_TOOLS subagent kayıtlarına — self
+    # dahil — kopyalamaz).
+    class VakanuvisTool < BaseTool
+      # Registry#schemas, REQUIRES memnuniyetsizliğinde aracı gizler:
+      # kronikçi kapalıysa (subagents.vakanuvis.enabled=false ya da store
+      # yok) bu masa model yüzünde görünmez.
+      REQUIRES = [Rubik::Coeffects::VAKANUIS].freeze
+
+      DECLARATION = Declaration.new(
+        name: "vakanuvis", aliases: ["chronicler"],
+        description: "Ask the background chronicler (compiled knowledge in rubik://storage): " \
+                     "'recall' (deterministic digest over memory+wiki with source links — ask at task start " \
+                     "and after compaction), 'record' (persist durable knowledge as a memory card; the ONE " \
+                     "path for memory writes), 'forget' (supersede/purge a mem.* card or a note), 'digest' (queue an " \
+                     "async wiki compilation; returns a deterministic receipt, never blocks on the LLM), " \
+                     "'topics' (list recorded memory topics — orient before the first query), 'digest_status' " \
+                     "(is my queued digest pending, in flight, or done?). Notes (annal.*) are the chronicler's " \
+                     "evidence layer; memory cards are the durable conclusions you want recalled by default. " \
+                     "Hygiene: same topic, same session = one note — update it (or retire it with forget; " \
+                     "superseded rows keep a trace).",
+        risk: :write, archetypes: [], write_grant: false,
+        maestro_blocked: false, # storage emsali: kronikçi düzlemi kökte doğrudan
+        params_schema: {
+          type: "object",
+          properties: {
+            action: {
+              type: "string", enum: ["recall", "record", "forget", "digest", "topics", "digest_status"],
+              description: "Operation (default: 'recall')."
+            },
+            query: { type: "string",
+                     description: "recall/digest: knowledge query. Recall is keyword-AND — every space-separated " \
+                                  "term must literally appear; retry with other-language synonyms when empty." },
+            types: {
+              type: "array", items: { type: "string", enum: ["memory", "wiki", "note"] },
+              description: "recall: entity scopes to search (default: memory + wiki)."
+            },
+            topic: { type: "string", description: "record: card topic — mints ref mem.<topic-slug> (upsert by topic)." },
+            body: {
+              type: "string",
+              description: "record: card body (markdown; end it with a Keywords: line of 5-10 TR+EN synonyms so " \
+                           "keyword-AND recall can find the card — a missing Keywords: line is auto-extracted " \
+                           "from the body at write time)."
+            },
+            tags: {
+              type: "array", items: { type: "string" },
+              description: "record: optional recall tags (searched like body text; merged with the chronicler's vocabulary)."
+            },
+            links: {
+              type: "object", additionalProperties: { type: "string" },
+              description: "record: optional cross-references (e.g. {\"goal\": \"goal.1.<hash16>\"})."
+            },
+            ref: { type: "string", description: "forget: mem.* card or note ref (annal.*) — or id — to retire." }
+          }
+        }
+      )
+
+      def initialize(harness = nil, runtime_context: nil)
+        super(DECLARATION)
+        @harness = harness
+        @runtime_context = runtime_context
+      end
+
+      def execute(args = {})
+        action = (args["action"] || args[:action] || "recall").to_s
+        harness = Rubik::Coeffects.resolve(@runtime_context, Rubik::Coeffects::VAKANUIS, @harness)
+        unless harness
+          return ToolOutput.error("Vakanüvis chronicler is not available: disabled by config " \
+                                  "(subagents.vakanuvis.enabled=false) or no store wired.")
+        end
+
+        begin
+          case action
+          when "recall" then harness.recall(arg(args, "query"), types: arg(args, "types"))
+          when "record"
+            receipt = harness.record(topic: arg(args, "topic"), body: arg(args, "body"),
+                                     links: arg(args, "links") || {}, tags: tags_arg(args))
+            record_line(harness, receipt)
+          when "forget"
+            receipt = harness.forget(ref: arg(args, "ref"))
+            forget_line(harness, receipt)
+          when "digest" then harness.digest(arg(args, "query"))
+          when "topics" then harness.topics
+          when "digest_status" then harness.digest_status
+          else ToolOutput.error("Unknown vakanuvis action '#{action}' " \
+                                "(valid: recall, record, forget, digest, topics, digest_status).")
+          end
+        rescue ArgumentError => e
+          ToolOutput.error("vakanuvis #{action}: #{e.message}")
+        rescue StandardError => e
+          Rubik::Storage::Vakanuvis.log_via(harness.dmesg, :warn, "vakanuvis #{action} failed: #{e.class}: #{e.message}")
+          ToolOutput.error("vakanuvis #{action} failed: #{e.class}: #{e.message} — the store may be " \
+                           "unavailable; retry the call or inspect dmesg(subsystem: 'storage').")
+        end
+      end
+
+      private
+
+      def record_line(harness, receipt)
+        verb = receipt["skipped"] ? "unchanged (version #{receipt['version']} kept)" : "stored (version #{receipt['version']})"
+        uri = harness.store.uri_for("memory", receipt["id"])
+        line = "Recorded '#{receipt['ref']}': #{verb}.\nURI: #{uri}\nRecall it later: vakanuvis(action: 'recall', query: '...')"
+        if receipt["keywords_extracted"]
+          line += "\nKeywords auto-extracted from the body (no Keywords: line was present)."
+        elsif receipt["keywords_state"] == "none"
+          line += "\nWarning: no Keywords: line and none could be extracted — recall may miss this card; " \
+                  "append a Keywords: line manually."
+        end
+        line
+      end
+
+      # Etiket paramı anahtar-varlığıyla okunur (tags: false sessizce []
+      # düşmesin — review L3) ve dizi değilse storage aracıyla aynı virgül
+      # bölmesine düşer (review CR#4: "a,b" tek ölü etiket olmasın).
+      # Üst-seviye boolean/sayı ret edilir.
+      def tags_arg(args)
+        raw = if args.key?("tags") || args.key?(:tags)
+                args["tags"] || args[:tags]
+              else
+                []
+              end
+        unless raw.is_a?(Array) || raw.is_a?(String)
+          raise ArgumentError,
+                "record tags must be an array of strings or a comma-separated string — " \
+                "got #{raw.class} (#{raw.inspect})."
+        end
+
+        raw.is_a?(Array) ? raw : raw.to_s.split(",").map(&:strip)
+      end
+
+      def forget_line(harness, receipt)
+        return "Nothing to forget: no memory card or note resolves from '#{receipt['ref']}'." unless receipt["forgot"]
+
+        if receipt["mode"] == "purge"
+          "Forgot '#{receipt['ref']}': row purged (hard delete)."
+        else
+          uri = harness.store.uri_for(receipt["type"] || "memory", receipt["id"])
+          "Forgot '#{receipt['ref']}': superseded (status + trace link kept).\nURI: #{uri}"
+        end
+      end
+
+      def arg(args, key, default = nil)
+        args[key] || args[key.to_sym] || default
+      end
+    end
+  end
+end

data/lib/rubik/tools/builtins.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Domain-grouped home of the 34 built-in agent tools (Plan 54 D-3, Plan 92, Plan 93,
+# storage-show-surface 2026-09-30, vakanuvis-chronicler 2026-10-04, context-pruner
+# 2026-10-09, following the repl/commands/*.rb loader pattern). This file is only the
+# loader; every tool class lives in the file matching its domain (subagent_lifecycle
+# holds the action modules consumed by ManageSubagentsTool, not a tool class).
+
+require_relative "uri_resolver"
+require_relative "builtins/files"
+require_relative "builtins/grep"
+require_relative "builtins/symbols"
+require_relative "builtins/lsp"
+require_relative "builtins/skill"
+require_relative "builtins/exec"
+require_relative "builtins/task"
+require_relative "builtins/synthesis"
+require_relative "builtins/unsynthesize"
+require_relative "builtins/runtime"
+require_relative "builtins/lifecycle"
+require_relative "builtins/interactive"
+require_relative "builtins/subagent"
+require_relative "builtins/send_message"
+require_relative "builtins/subagent_lifecycle"
+require_relative "builtins/dmesg"
+require_relative "builtins/storage"
+require_relative "builtins/vakanuvis"
+require_relative "builtins/pruner"
+require_relative "builtins/goal_ledger"
+require_relative "builtins/show_file"

data/lib/rubik/tools/catalog.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "declaration"
+require_relative "builtins"
+
+module Rubik
+  module Tools
+    # Frozen load-time projection over the builtin DECLARATIONs: the single
+    # place archetype allowlists, the spawn set, the custom-type write gate,
+    # the maestro gate and doc tables derive from (architecture review
+    # 2026-10-01, candidate 1). Membership pins "a class that exists is
+    # registered, and vice versa"; ORDER mirrors Registry.build_default
+    # registration order exactly (both directions invariant-tested).
+    #
+    # This is a load-time constant module — the same class of thing as
+    # Rubik::Coeffects, not a registry. Dynamically registered tools (MCP,
+    # plugins, synthesis) cannot join it; they use Registry#register's
+    # per-instance path unchanged.
+    module Catalog
+      BUILTINS = [
+        ReadFileTool, ReplaceFileContentTool, WriteFileTool, ListFilesTool, GrepSearchTool,
+        SearchSymbolsTool, GetOutlineTool, FindReferencesTool, GetSymbolTool,
+        LSPDiagnosticsTool, LSPHoverTool, LSPDefinitionTool, RunTestsTool, RunCommandTool,
+        ManageTaskTool, ExecReplCommandTool, SynthesizeCommandTool, SynthesizeToolTool,
+        UnsynthesizeTool, InspectRuntimeTool, ProvideServiceTool, RepairRuntimeTool,
+        ApplyBufferTool, AskQuestionTool, InvokeSubagentTool, ManageSubagentsTool,
+        SendMessageTool, DefineSubagentTool, DmesgTool, StorageTool, VakanuvisTool, PruneContextTool,
+        UpdateGoalLedgerTool, ShowFileTool, FinishTool
+      ].freeze
+
+      # Tools registered outside build_default (dynamically, each with its own
+      # ctx inverse) that still carry a canonical DECLARATION.
+      DYNAMIC = [SkillTool].freeze
+
+      # PERF: Pre-compute and freeze load-time projections to avoid re-filtering,
+      # re-sorting, array allocations, and linear scans on hot query paths.
+      DECLARATIONS = BUILTINS.filter_map { |k| k.const_defined?(:DECLARATION, false) ? k::DECLARATION : nil }.freeze
+      DYNAMIC_DECLARATIONS = DYNAMIC.filter_map { |k| k.const_defined?(:DECLARATION, false) ? k::DECLARATION : nil }.freeze
+      NAMES = DECLARATIONS.map(&:name).freeze
+      DECLARATIONS_BY_NAME = DECLARATIONS.to_h { |d| [d.name, d] }.freeze
+      RESEARCH_TOOLS = DECLARATIONS.select { |d| d.archetypes.include?(:research) }.map(&:name).sort.freeze
+      CODER_TOOLS = DECLARATIONS.select { |d| d.archetypes.include?(:coder) }.map(&:name).sort.freeze
+      SPAWN_TOOLS = DECLARATIONS.select(&:spawn?).map(&:name).sort.freeze
+      WRITE_GRANT_TOOLS = DECLARATIONS.select(&:write_grant?).map(&:name).sort.freeze
+      MAESTRO_BLOCKED_TOOLS = DECLARATIONS.select(&:maestro_blocked?).map(&:name).sort.freeze
+
+      module_function
+
+      def declarations = DECLARATIONS
+
+      def dynamic_declarations = DYNAMIC_DECLARATIONS
+
+      def names = NAMES
+
+      def [](name) = DECLARATIONS_BY_NAME[name.to_s]
+
+      def research_tools = RESEARCH_TOOLS
+
+      def coder_tools = CODER_TOOLS
+
+      def spawn_tools = SPAWN_TOOLS
+
+      def write_grant_tools = WRITE_GRANT_TOOLS
+
+      def maestro_blocked_tools = MAESTRO_BLOCKED_TOOLS
+
+      def maestro_blocked?(name) = MAESTRO_BLOCKED_TOOLS.include?(name.to_s)
+    end
+  end
+end

data/lib/rubik/tools/declaration.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Tools
+    # One tool, one declaration (architecture review 2026-10-01, candidate 1):
+    # the COMPLETE interface + policy of a tool as a single frozen literal in
+    # the tool's domain file. Registry order, archetype allowlists, the
+    # maestro gate, the custom-type write gate, TOOLS.md and prompt teachings
+    # all derive from this object via Tools::Catalog.
+    #
+    # Policy fields are orchestrator-plane facts. They NEVER leak into the
+    # LLM schema surface: BaseTool#to_h keeps emitting exactly
+    # name/description/risk/parameters (invariant-pinned by
+    # test_tool_declaration_catalog).
+    Declaration = Struct.new(
+      :name, :aliases, :description, :risk, :params_schema,
+      :allow_additional_properties,
+      :archetypes,      # Array<Symbol> subset of [:research, :coder] — subagent allowlists
+      :subagent_spawn,  # bool — member of the spawn set (self-archetype recursion guard)
+      :write_grant,     # bool — denied to custom types lacking enable_write_tools
+      :maestro_blocked, # true | false | nil — gate class; MUST be explicit for :write/:execute
+      keyword_init: true
+    ) do
+      def initialize(name:, description:, risk: :read, params_schema: {}, aliases: [],
+                     allow_additional_properties: true, archetypes: [], subagent_spawn: false,
+                     write_grant: false, maestro_blocked: nil)
+        clean_name = name.to_s
+        # Leading digits are tolerated (not required) for legacy dynamic
+        # tools: synthesis/overlay normalize to lowercase snake but do not
+        # strip a leading digit, and LLM provider tool-name rules allow
+        # digits — rejecting them would drop tools that loaded before the
+        # Declaration seam existed.
+        unless clean_name.match?(/\A[a-z0-9_]+\z/)
+          raise ArgumentError,
+                "tool name '#{clean_name}' must be lowercase snake_case (a-z, 0-9, _) — canonical names are the registry keys"
+        end
+
+        risk_key = risk.to_s.to_sym
+        unless [:read, :write, :execute].include?(risk_key)
+          raise ArgumentError,
+                "tool '#{clean_name}' risk must be one of read, write, execute (got #{risk.inspect})"
+        end
+
+        archetype_keys = Array(archetypes).map { |a| a.to_s.to_sym }
+        unknown = archetype_keys - [:research, :coder]
+        if unknown.any?
+          raise ArgumentError,
+                "tool '#{clean_name}' archetypes must be a subset of research, coder (got #{unknown.join(', ')}) — " \
+                "empty means orchestrator-plane only"
+        end
+
+        # Members are shared by every instance of the class (the DECLARATION
+        # constant): freeze aliases and the schema's outer hash so no caller
+        # can corrupt the projection source for the whole process.
+        # (to_h dups before injecting additionalProperties, so the frozen
+        # schema never blocks the LLM payload path.)
+        schema = params_schema.is_a?(Hash) ? params_schema.freeze : params_schema
+        super(
+          name: clean_name,
+          description: description.to_s,
+          risk: risk_key,
+          params_schema: schema,
+          aliases: Array(aliases).map(&:to_s).freeze,
+          allow_additional_properties: allow_additional_properties,
+          archetypes: archetype_keys.freeze,
+          subagent_spawn: subagent_spawn ? true : false,
+          write_grant: write_grant ? true : false,
+          maestro_blocked: if maestro_blocked.nil?
+                             nil
+                           else
+                             (maestro_blocked ? true : false)
+                           end
+        )
+        freeze
+      end
+
+      # Derived copy with overrides (e.g. invoke_subagent's supervisor-derived
+      # schema) — states a near-declaration instead of splatting to_h by hand.
+      def with(**overrides)
+        Declaration.new(**to_h, **overrides)
+      end
+
+      def maestro_blocked? = maestro_blocked == true
+
+      def spawn? = subagent_spawn == true
+
+      def write_grant? = write_grant == true
+    end
+  end
+end