rubyn-code 0.5.0 → 0.7.0

data/lib/rubyn_code/chisel.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module RubynCode
+  # Chisel is rubyn-code's opt-in "write the minimum that works" enforcement
+  # layer. It is OFF by default and only changes the agent's behavior once a
+  # user turns it on (via `/chisel full` or the config key `chisel_mode`).
+  #
+  # The single source of truth for:
+  #   - which intensity modes exist (off/lite/full/ultra),
+  #   - which mode is currently active (env override → config → default),
+  #   - the ruleset text injected into the system prompt at each intensity.
+  #
+  # The decision ladder is adapted from the open-source `ponytail` plugin and
+  # rebuilt natively here; the safety floor (validation, error/data-loss
+  # handling, security, accessibility) is never on the chopping block.
+  module Chisel
+    # On-demand over-engineering audit shared by /chisel-review and /chisel-audit.
+    autoload :Inspection, 'rubyn_code/chisel/inspection'
+    # Harvests inline `chisel:` deferral markers for /chisel-debt and /chisel-gain.
+    autoload :Debt, 'rubyn_code/chisel/debt'
+
+    MODES = %w[off lite full ultra].freeze
+    DEFAULT_MODE = 'off'
+    ENV_KEY = 'RUBYN_CHISEL_MODE'
+    CONFIG_KEY = 'chisel_mode'
+
+    # The decision ladder — injected at every non-off intensity.
+    LADDER = <<~LADDER.strip
+      # Chisel — write the minimum that works
+
+      Before writing code, stop at the first rung that holds:
+      1. Does this need to exist? If not, don't write it. (YAGNI)
+      2. Does Ruby's stdlib already do it? Use it.
+      3. Does the framework or runtime already do it? Use it.
+      4. Does an already-installed gem do it? Use it — don't add a dependency.
+      5. Is it one line? Write one line.
+      6. Only then: the smallest change that fully solves the task.
+    LADDER
+
+    # Extra guidance layered on at `full` and above.
+    FULL_ADDENDUM = <<~FULL.strip
+      Prefer editing existing code over adding new files, classes, or layers of
+      indirection. Don't introduce an abstraction until a second concrete caller
+      exists — three similar lines beat a premature framework.
+    FULL
+
+    # Extra guidance layered on at `ultra` only.
+    ULTRA_ADDENDUM = <<~ULTRA.strip
+      Be aggressive: question every new method, parameter, option, and file. If
+      you can't name the second caller, inline it. When you finish, briefly note
+      what you deliberately chose NOT to build.
+    ULTRA
+
+    # The safety floor — appended at every non-off intensity, last so it is
+    # never overridden by the "delete more" guidance above it.
+    SAFETY_FLOOR = <<~SAFETY.strip
+      Lazy, not negligent. Never chisel away: input and trust-boundary
+      validation, error and data-loss handling, security, or accessibility.
+    SAFETY
+
+    module_function
+
+    # @param value [#to_s]
+    # @return [Boolean] whether the value is a recognized mode
+    def valid?(value)
+      MODES.include?(value.to_s)
+    end
+
+    # Resolve the active mode: env override → persisted config → default.
+    # Each layer is normalized (trimmed + downcased) the same way the
+    # `/chisel` command normalizes its argument, so `RUBYN_CHISEL_MODE=Full`
+    # and a hand-edited `chisel_mode: " Full "` both resolve cleanly. Any
+    # unrecognized value falls through rather than raising, so a typo can
+    # never break a turn.
+    #
+    # @return [String] one of MODES
+    def mode
+      normalize(ENV.fetch(ENV_KEY, nil)) ||
+        normalize(configured_mode) ||
+        DEFAULT_MODE
+    end
+
+    # Trim + downcase a candidate mode, returning it only if recognized,
+    # otherwise nil so the caller can fall through to the next layer.
+    #
+    # @param value [#to_s, nil]
+    # @return [String, nil]
+    def normalize(value)
+      return nil if value.nil?
+
+      candidate = value.to_s.strip.downcase
+      valid?(candidate) ? candidate : nil
+    end
+
+    # @return [Boolean]
+    def enabled?
+      mode != 'off'
+    end
+
+    # The text Chisel contributes to the system prompt for the active mode.
+    #
+    # @return [String] "" when off; otherwise ladder + intensity addenda +
+    #   safety floor.
+    def prompt_section
+      current = mode
+      return '' if current == 'off'
+
+      parts = [LADDER]
+      parts << FULL_ADDENDUM if %w[full ultra].include?(current)
+      parts << ULTRA_ADDENDUM if current == 'ultra'
+      parts << SAFETY_FLOOR
+      parts.join("\n\n")
+    end
+
+    # The persisted mode from config, or nil if unreadable. Isolated so prompt
+    # assembly never dies on a malformed config file.
+    #
+    # @return [String, nil]
+    def configured_mode
+      # No default needed — chisel_mode lives in Settings::DEFAULT_MAP, so an
+      # unset key already resolves to DEFAULT_MODE.
+      Config::Settings.new.get(CONFIG_KEY)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/rubyn_code/cli/app.rb

@@ -64,7 +64,7 @@ module RubynCode
         '--auth' => :auth, '--setup' => :setup
       }.freeze
       BOOLEAN_FLAGS = { '--yolo' => :yolo, '--debug' => :debug, '--skip-setup' => :skip_setup, '--ide' => :ide }.freeze
-      VALUE_FLAGS = { '--permission-mode' => :permission_mode }.freeze
+      VALUE_FLAGS = { '--permission-mode' => :permission_mode, '--dir' => :workspace_dir }.freeze
       DAEMON_INT_FLAGS = { '--max-runs' => :max_runs, '--idle-timeout' => :idle_timeout,
                            '--poll-interval' => :poll_interval }.freeze
       DAEMON_STR_FLAGS = { '--name' => :agent_name, '--role' => :role }.freeze
@@ -209,7 +209,7 @@ module RubynCode
 
       def run_ide
         mode = resolve_permission_mode
-        IDE::Server.new(permission_mode: mode).run
+        IDE::Server.new(permission_mode: mode, workspace_path: @options[:workspace_dir]).run
       end
 
       def run_daemon

data/lib/rubyn_code/cli/commands/agents.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module CLI
+    module Commands
+      # `/agents` — list the sub-agent types available to spawn_agent: the
+      # built-in explore/worker plus any custom agents defined in
+      # .rubyn-code/agents/*.md or ~/.rubyn-code/agents/*.md.
+      class Agents < Base
+        def self.command_name = '/agents'
+        def self.description  = 'List available sub-agent types (built-in + custom)'
+
+        def execute(_args, ctx)
+          catalog = RubynCode::SubAgents::Catalog.new(project_root: ctx.project_root)
+          ctx.renderer.info('Available sub-agent types:')
+          catalog.all.each do |agent|
+            tag = agent.custom? ? '(custom)' : '(built-in)'
+            access = agent.read_only? ? 'read-only' : 'read/write'
+            puts "  #{agent.name.ljust(18)} #{tag} [#{access}] — #{agent.description}"
+          end
+          puts
+          ctx.renderer.info('Define your own in .rubyn-code/agents/<name>.md') if catalog.custom_names.empty?
+          nil
+        rescue StandardError => e
+          ctx.renderer.error("Could not list agents: #{e.message}")
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/cli/commands/chisel.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module CLI
+    module Commands
+      # Set or report the Chisel intensity. Chisel is the opt-in "write the
+      # minimum that works" enforcement layer; it is off by default and only
+      # changes the agent's behavior once turned on here.
+      class Chisel < Base
+        def self.command_name = '/chisel'
+        def self.description = 'Set or show Chisel intensity (off|lite|full|ultra)'
+
+        def execute(args, ctx)
+          arg = args.first
+          return report(ctx) if arg.nil? || arg.strip.empty?
+
+          mode = arg.strip.downcase
+          return reject(mode, ctx) unless RubynCode::Chisel.valid?(mode)
+
+          persist(mode, ctx)
+        end
+
+        private
+
+        def report(ctx)
+          current = RubynCode::Chisel.mode
+          ctx.renderer.info("Chisel: #{current}")
+          ctx.renderer.info("Modes: #{RubynCode::Chisel::MODES.join(' | ')}")
+          ctx.renderer.info('Set with: /chisel full')
+        end
+
+        def persist(mode, ctx)
+          settings = Config::Settings.new
+          settings.set(RubynCode::Chisel::CONFIG_KEY, mode)
+          settings.save!
+          ctx.renderer.info(confirmation(mode))
+        end
+
+        def confirmation(mode)
+          return 'Chisel off — agent behaves normally.' if mode == 'off'
+
+          "Chisel set to #{mode} — the agent will favor writing the minimum that works."
+        end
+
+        def reject(mode, ctx)
+          ctx.renderer.warning("Unknown Chisel mode: #{mode}")
+          ctx.renderer.info("Valid modes: #{RubynCode::Chisel::MODES.join(', ')}")
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/cli/commands/chisel_audit.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module CLI
+    module Commands
+      # `/chisel-audit` — sweep the repo (or a path) for accumulated
+      # over-engineering and report a ranked deletion list. Read-only.
+      class ChiselAudit < Base
+        def self.command_name = '/chisel-audit'
+        def self.description = 'Find over-engineering across the repo (/chisel-audit [path])'
+
+        def execute(args, ctx)
+          path = args.first
+          ctx.send_message(RubynCode::Chisel::Inspection.prompt(scope: :repo, target: path))
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/cli/commands/chisel_debt.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module CLI
+    module Commands
+      # `/chisel-debt` — harvest inline `chisel:` deferral markers from the
+      # codebase into a ledger view so postponed simplifications aren't lost.
+      class ChiselDebt < Base
+        def self.command_name = '/chisel-debt'
+        def self.description = 'List deferred `chisel:` markers in the codebase'
+
+        def execute(_args, ctx)
+          items = RubynCode::Chisel::Debt.scan(ctx.project_root)
+          return ctx.renderer.info('No chisel: debt markers found — clean.') if items.empty?
+
+          ctx.renderer.info("Chisel debt — #{items.size} deferred #{pluralize(items.size, 'simplification')}:")
+          items.each { |item| ctx.renderer.info("  #{item.file}:#{item.line} — #{item.note}") }
+        end
+
+        private
+
+        def pluralize(count, word)
+          count == 1 ? word : "#{word}s"
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/cli/commands/chisel_gain.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module CLI
+    module Commands
+      # `/chisel-gain` — quick read on Chisel's status and what it buys you.
+      class ChiselGain < Base
+        def self.command_name = '/chisel-gain'
+        def self.description = 'Show Chisel status and reference impact'
+
+        # Measured on a real open-source repo for the approach Chisel is built on;
+        # shown as an attributed reference, not fabricated per-user metrics (which
+        # rubyn-code does not instrument).
+        REFERENCE_IMPACT = 'Reference benchmark for this approach (real FastAPI + React repo): ' \
+                           '~54% less code, ~20% cheaper, ~27% faster.'
+
+        def execute(_args, ctx)
+          mode = RubynCode::Chisel.mode
+          debt = RubynCode::Chisel::Debt.scan(ctx.project_root).size
+
+          ctx.renderer.info("Chisel mode: #{mode}")
+          ctx.renderer.info('Turn it on with /chisel full.') if mode == 'off'
+          ctx.renderer.info("Outstanding chisel: debt markers: #{debt}")
+          ctx.renderer.info(REFERENCE_IMPACT)
+          ctx.renderer.info('Run /chisel-review for concrete cuts in your current diff.')
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/cli/commands/chisel_review.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module CLI
+    module Commands
+      # `/chisel-review` — audit the current branch's changes for
+      # over-engineering and report a ranked deletion list. Read-only.
+      class ChiselReview < Base
+        def self.command_name = '/chisel-review'
+        def self.description = 'Find over-engineering in the current diff (/chisel-review [base])'
+
+        def execute(args, ctx)
+          # Inspection owns the 'main' default so it lives in exactly one place.
+          ctx.send_message(RubynCode::Chisel::Inspection.prompt(scope: :diff, target: args.first))
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/cli/commands/command_template.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module RubynCode
+  module CLI
+    module Commands
+      # Renders a user-defined slash-command body into a prompt, mirroring
+      # Claude Code's command templating:
+      #
+      #   $ARGUMENTS   → all args, space-joined
+      #   $1 .. $9     → positional args
+      #   !`shell cmd` → replaced with the command's (combined) output
+      #
+      # Bash substitution runs the user's own command file, so it carries the
+      # same trust as user hooks. Output is captured defensively and capped.
+      class CommandTemplate
+        BANG = /!`([^`]+)`/
+        POSITIONAL = /\$([1-9])/
+        MAX_BASH_OUTPUT = 16 * 1024
+
+        def initialize(body)
+          @body = body.to_s
+        end
+
+        # @param args [Array<String>] arguments passed after the command name
+        # @return [String] the rendered prompt
+        def render(args = [])
+          text = substitute_bash(@body)
+          text = text.gsub('$ARGUMENTS', args.join(' '))
+          text.gsub(POSITIONAL) { args[Regexp.last_match(1).to_i - 1].to_s }
+        end
+
+        private
+
+        def substitute_bash(text)
+          text.gsub(BANG) { run(Regexp.last_match(1)) }
+        end
+
+        def run(cmd)
+          out, = Open3.capture2e(cmd)
+          out = "#{out.byteslice(0, MAX_BASH_OUTPUT)}\n… [truncated]" if out.bytesize > MAX_BASH_OUTPUT
+          out.strip
+        rescue StandardError => e
+          "[command failed: #{e.message}]"
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/cli/commands/context.rb

@@ -21,7 +21,9 @@ module RubynCode
         :background_worker,
         :permission_tier,
         :plan_mode,
-        :message_handler
+        :message_handler,
+        :hook_registry,
+        :checkpoint_manager
       ) do
         # Convenience: return a new Context with a message handler attached.
         # Used by commands like /review that delegate to the LLM.

data/lib/rubyn_code/cli/commands/custom_command.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module CLI
+    module Commands
+      # A slash command defined by a user markdown file (loaded by
+      # CustomLoader). Unlike the built-in commands — which are registered as
+      # classes — this is a ready instance: the Registry dispatches it directly.
+      #
+      # Executing it renders the template (argument / bash substitution) and
+      # sends the result to the agent as a normal prompt.
+      class CustomCommand
+        # @return [String] command name without the leading slash
+        attr_reader :name
+        # @return [String] one-line description for /help
+        attr_reader :description
+        # @return [String, nil] originating file path
+        attr_reader :source
+
+        def initialize(name:, description:, body:, source: nil)
+          @name = name
+          @description = description
+          @template = CommandTemplate.new(body)
+          @source = source
+        end
+
+        def command_name = "/#{@name}"
+        def aliases = [].freeze
+        def hidden? = false
+        def all_names = [command_name].freeze
+
+        # @param args [Array<String>]
+        # @param ctx [Commands::Context]
+        # @return [nil]
+        def execute(args, ctx)
+          ctx.send_message(@template.render(args))
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/cli/commands/custom_loader.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module RubynCode
+  module CLI
+    module Commands
+      # Discovers user-defined slash commands from markdown files, mirroring
+      # Claude Code's `.claude/commands/*.md`:
+      #
+      #   <project>/.rubyn-code/commands/*.md   (project-local, takes priority)
+      #   ~/.rubyn-code/commands/*.md           (user-global)
+      #
+      # Each `deploy.md` becomes `/deploy`. Optional YAML frontmatter supplies
+      # the `description`; otherwise the first non-empty line is used. The body
+      # is the prompt template (see CommandTemplate for substitutions).
+      module CustomLoader
+        FRONTMATTER = /\A---\s*\n(.+?\n)---\s*\n(.*)\z/m
+        NAME = /\A[a-z0-9][a-z0-9_-]*\z/i
+
+        class << self
+          # @return [Array<CustomCommand>] unique commands (project overrides user)
+          def load_all(project_root:, home_dir: Config::Defaults::HOME_DIR)
+            dirs = [
+              project_root && File.join(project_root, '.rubyn-code', 'commands'),
+              File.join(home_dir, 'commands')
+            ].compact
+            dirs.flat_map { |dir| load_dir(dir) }.uniq(&:command_name)
+          end
+
+          def load_dir(dir)
+            return [] unless Dir.exist?(dir)
+
+            Dir.glob(File.join(dir, '*.md')).filter_map { |path| build(path) }
+          end
+
+          private
+
+          def build(path)
+            name = File.basename(path, '.md').strip
+            return nil unless name.match?(NAME)
+
+            description, body = parse(File.read(path))
+            description = "Custom command: /#{name}" if description.to_s.strip.empty?
+            CustomCommand.new(name: name, description: description, body: body, source: path)
+          rescue StandardError => e
+            RubynCode::Debug.warn("Failed to load custom command #{path}: #{e.message}")
+            nil
+          end
+
+          def parse(content)
+            if (match = FRONTMATTER.match(content))
+              frontmatter = YAML.safe_load(match[1]) || {}
+              [frontmatter['description'].to_s, match[2].to_s.strip]
+            else
+              body = content.to_s.strip
+              [first_line(body), body]
+            end
+          end
+
+          def first_line(body)
+            line = body.lines.first.to_s.strip
+            line.sub(/\A#+\s*/, '')[0, 80]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/cli/commands/goal.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module CLI
+    module Commands
+      # `/goal` — set a session goal that Rubyn keeps working toward until it
+      # is met. Installs a Stop hook (Hooks::GoalHook) that blocks the agent
+      # from finishing while the goal is unmet; the goal auto-clears once an
+      # evaluator judges it satisfied.
+      #
+      #   /goal <condition>   set a goal and start working toward it
+      #   /goal               show the current goal (if any)
+      #   /goal clear         cancel the active goal early
+      class Goal < Base
+        def self.command_name = '/goal'
+        def self.description  = 'Set a goal Rubyn works toward until met (/goal clear to cancel)'
+
+        CLEAR_WORDS = %w[clear cancel off stop].freeze
+
+        def execute(args, ctx)
+          first = args.first&.strip&.downcase
+          return clear_goal(ctx) if CLEAR_WORDS.include?(first)
+
+          condition = args.join(' ').strip
+          return show_status(ctx) if condition.empty?
+
+          set_goal(ctx, condition)
+        end
+
+        private
+
+        def set_goal(ctx, condition)
+          deactivate_existing(ctx)
+          evaluator = RubynCode::Goal::Evaluator.new(llm_client: ctx.llm_client)
+          ctx.hook_registry.on(:stop, Hooks::GoalHook.new(condition: condition, evaluator: evaluator), priority: 10)
+
+          ctx.renderer.info("🎯 Goal set: #{condition}")
+          ctx.renderer.info("Rubyn will keep working until it's met. /goal clear to cancel.")
+          ctx.send_message(kickoff_prompt(condition))
+          nil
+        end
+
+        def clear_goal(ctx)
+          if deactivate_existing(ctx).positive?
+            ctx.renderer.info('Goal cleared. ✌️')
+          else
+            ctx.renderer.info('No active goal to clear.')
+          end
+          nil
+        end
+
+        def show_status(ctx)
+          active = active_goals(ctx)
+          if active.empty?
+            ctx.renderer.info('No active goal. Set one with: /goal <what you want done>')
+          else
+            ctx.renderer.info("🎯 Active goal: #{active.first.condition}")
+          end
+          nil
+        end
+
+        # Deactivate any active GoalHook(s) on the registry.
+        # @return [Integer] number of goals deactivated
+        def deactivate_existing(ctx)
+          active_goals(ctx).each(&:clear!).size
+        end
+
+        def active_goals(ctx)
+          return [] unless ctx.hook_registry
+
+          ctx.hook_registry.hooks_for(:stop).select do |hook|
+            hook.is_a?(Hooks::GoalHook) && hook.active?
+          end
+        end
+
+        def kickoff_prompt(condition)
+          <<~PROMPT.strip
+            New session goal: #{condition}
+
+            Start working toward this goal now. Keep going until it is genuinely
+            met — don't stop to ask what to do next.
+          PROMPT
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/cli/commands/learning.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module CLI
+    module Commands
+      # `/learning` — inspect and move the instincts Rubyn learns across
+      # sessions. Continuous learning runs automatically at the end of each
+      # session; this command lets you carry those learnings to another machine.
+      #
+      #   /learning                       show learning stats
+      #   /learning export [path]         export all instincts to a JSON file
+      #   /learning import <path> [--here] import instincts (--here = remap to this project)
+      class Learning < Base
+        def self.command_name = '/learning'
+        def self.description  = 'Show, export, or import learned instincts (/learning export|import)'
+
+        DEFAULT_FILE = 'rubyn-learnings.json'
+
+        def execute(args, ctx)
+          case args.first
+          when 'export' then export(ctx, args[1])
+          when 'import' then import(ctx, args[1..])
+          when nil      then stats(ctx)
+          else
+            ctx.renderer.info('Usage: /learning [export [path] | import <path> [--here]]')
+          end
+          nil
+        rescue RubynCode::Learning::Porter::Error => e
+          ctx.renderer.error("Learning: #{e.message}")
+          nil
+        end
+
+        private
+
+        def stats(ctx)
+          summary = RubynCode::Learning::Porter.stats(ctx.db)
+          ctx.renderer.info("🧠 #{summary[:count]} instinct(s) learned across #{summary[:projects]} project(s).")
+          ctx.renderer.info('Move them with: /learning export  →  /learning import <file> --here')
+        end
+
+        def export(ctx, path)
+          dest = File.expand_path(path || DEFAULT_FILE, ctx.project_root)
+          count = RubynCode::Learning::Porter.export(db: ctx.db, path: dest)
+          ctx.renderer.info("📤 Exported #{count} instinct(s) to #{dest}")
+        end
+
+        def import(ctx, rest)
+          args = Array(rest)
+          here = args.delete('--here')
+          path = args.first
+          return ctx.renderer.info('Usage: /learning import <path> [--here]') unless path
+
+          remap = here ? ctx.project_root : nil
+          result = RubynCode::Learning::Porter.import(
+            db: ctx.db, path: File.expand_path(path, ctx.project_root), remap_project: remap
+          )
+          ctx.renderer.info("📥 Imported #{result[:imported]} instinct(s) (#{result[:skipped]} skipped as duplicates).")
+        end
+      end
+    end
+  end
+end