rubyn-code 0.5.1 → 0.8.0

data/lib/rubyn_code/agent/loop.rb

@@ -9,7 +9,7 @@ require_relative 'llm_caller'
 
 module RubynCode
   module Agent
-    class Loop
+    class Loop # rubocop:disable Metrics/ClassLength -- core agent loop: LLM calls, tool dispatch, recovery, hooks
       include SystemPromptBuilder
       include ResponseParser
       include ToolProcessor
@@ -18,6 +18,7 @@ module RubynCode
       include LlmCaller
 
       MAX_ITERATIONS = Config::Defaults::MAX_ITERATIONS
+      GOAL_MAX_ITERATIONS = Config::Defaults::GOAL_MAX_ITERATIONS
 
       # @param opts [Hash] keyword arguments for loop configuration
       # @option opts [LLM::Client]                    :llm_client
@@ -39,6 +40,7 @@ module RubynCode
         assign_dependencies(opts)
         assign_callbacks(opts)
         @plan_mode = false
+        @static_prompt_sections = nil
       end
 
       # @return [Boolean]
@@ -51,8 +53,11 @@ module RubynCode
       # response is produced or the iteration limit is reached.
       #
       # @param user_input [String]
+      # @param blocks [Array<Hash>, nil] extra content blocks to attach to the
+      #   user message (e.g. image blocks from @-mentions). When non-empty the
+      #   user message is stored as a mixed content array instead of a string.
       # @return [String] the final assistant text response
-      def send_message(user_input)
+      def send_message(user_input, blocks: nil)
         initialize_session!
         check_user_feedback(user_input)
         drain_background_notifications
@@ -60,20 +65,67 @@ module RubynCode
         @decision_compactor&.detect_topic_switch(user_input)
         @skill_ttl&.tick!
         autoload_triggered_skills(user_input)
-        @conversation.add_user_message(user_input)
+        append_user_message(user_input, blocks)
+        reset_system_prompt_cache!
         reset_iteration_state
 
-        MAX_ITERATIONS.times do |iteration|
+        iteration = 0
+        loop do
           result = run_iteration(iteration)
           return result if result
+
+          iteration += 1
+          break unless keep_iterating?(iteration)
         end
 
-        RubynCode::Debug.warn("Hit MAX_ITERATIONS (#{MAX_ITERATIONS})")
-        max_iterations_warning
+        RubynCode::Debug.warn("Hit iteration limit (#{iteration})")
+        max_iterations_warning(iteration)
+      end
+
+      # Append the user turn to the conversation. If image blocks were passed
+      # via `blocks:`, the message is stored as a mixed content array with a
+      # leading text block and the image blocks appended in order.
+      def append_user_message(user_input, blocks)
+        if blocks.is_a?(Array) && !blocks.empty?
+          content = [{ type: 'text', text: user_input.to_s }, *blocks]
+          @conversation.add_user_message(content)
+        else
+          @conversation.add_user_message(user_input)
+        end
+      end
+
+      # @return [Tools::TodoStore] shared checklist store, exposed for the REPL renderer
+      attr_reader :todo_store
+
+      # Apply a one-shot model override for the duration of the next LLM call.
+      # Used by `Context#with_optional_model` for custom-command frontmatter.
+      def model_override=(model_name)
+        stripped = model_name.to_s.strip
+        @model_override = stripped.empty? ? nil : stripped
+      end
+
+      # Restrict the available tool set for the next LLM call only.
+      # @param allowed [Array<String>, nil] tool names, or nil to clear the override.
+      def allowed_tools_override=(allowed)
+        @allowed_tools_override = allowed.is_a?(Array) && !allowed.empty? ? allowed : nil
       end
 
       private
 
+      # Overrides the region above. The internal helpers below are private.
+
+      # Decide whether the loop should run another iteration after `iteration`
+      # turns. Normally capped at MAX_ITERATIONS, but while a Stop hook (e.g. an
+      # active /goal) is keeping the agent alive we extend up to a hard ceiling
+      # — a goal can need more tool turns than a single request. The GoalHook's
+      # own max-attempts valve terminates an unsatisfiable goal; the ceiling is
+      # only a runaway guard.
+      def keep_iterating?(iteration)
+        return true if iteration < MAX_ITERATIONS
+
+        @stop_block_active && iteration < GOAL_MAX_ITERATIONS
+      end
+
       def assign_dependencies(opts)
         assign_required_deps(opts)
         assign_optional_deps(opts)
@@ -100,6 +152,8 @@ module RubynCode
         @tool_wrapper       = opts[:tool_wrapper]
         @decision_compactor = build_decision_compactor
         @skill_ttl          = Skills::TtlManager.new
+        @todo_store         = opts.fetch(:todo_store, Tools::TodoStore.new)
+        @tool_executor.todo_store = @todo_store
         @session_initialized = false
       end
 
@@ -114,6 +168,7 @@ module RubynCode
       def initialize_session!
         return if @session_initialized || !@project_root
 
+        @todo_store&.clear
         @session_initialized = true
         build_project_profile!
         build_codebase_index!
@@ -148,13 +203,18 @@ module RubynCode
         @max_tokens_override   = nil
         @output_recovery_count = 0
         @task_budget_remaining = nil
+        @stop_block_active     = false # true while a Stop hook keeps us going
+        @allowed_tools_override = nil   # set by Context#with_allowed_tools
+        @model_override         = nil   # set by Context#with_optional_model
       end
 
       def run_iteration(iteration)
         log_iteration(iteration)
         @context_manager.advance_turn!
         compact_if_needed # ensure context is under threshold before LLM call
-        response   = call_llm
+        response = call_llm
+        return handle_refusal(response) if extract_stop_reason(response) == 'refusal'
+
         tool_calls = extract_tool_calls(response)
         log_response(response, tool_calls)
 
@@ -163,6 +223,20 @@ module RubynCode
         handle_tool_response(response, tool_calls, iteration)
       end
 
+      # Claude's safety classifiers declined the request outright (HTTP 200,
+      # stop_reason: "refusal"). Surface a clear message instead of falling
+      # through to text/empty-response handling, which would misread the
+      # empty or partial content as "waiting on background jobs".
+      def handle_refusal(response)
+        details = extract_stop_details(response)
+        category = details.is_a?(Hash) ? (details['category'] || details[:category]) : nil
+        RubynCode::Debug.llm("Refusal: category=#{category || 'unknown'}")
+
+        message = "Claude's safety system declined this request (category: #{category || 'unknown'})."
+        @conversation.add_assistant_message([{ type: 'text', text: message }])
+        message
+      end
+
       def log_iteration(iteration)
         RubynCode::Debug.loop_tick(
           "iteration=#{iteration} messages=#{@conversation.length} " \
@@ -199,6 +273,13 @@ module RubynCode
 
         @conversation.add_assistant_message(response_content(response))
 
+        # Stop hook: a hook may block stopping (e.g. an active /goal). When
+        # blocked, the reason is injected as user feedback and the loop keeps
+        # iterating instead of returning the final text. While blocked, the
+        # loop is allowed to run past MAX_ITERATIONS (see #keep_iterating?).
+        @stop_block_active = stop_blocked?(text)
+        return nil if @stop_block_active
+
         # Decision-based compaction (topic switch, milestone)
         @decision_compactor&.check!(@conversation)
 
@@ -208,6 +289,19 @@ module RubynCode
         text
       end
 
+      # Fires the :stop hook. If a hook blocks (returns { block: true }), the
+      # reason is appended as a user message so the next iteration acts on it.
+      #
+      # @return [Boolean] true if stopping was blocked (keep iterating)
+      def stop_blocked?(text)
+        decision = @hook_runner.fire(:stop, conversation: @conversation, response_text: text)
+        return false unless decision.is_a?(Hash) && decision[:block]
+
+        RubynCode::Debug.agent('Stop blocked by hook — continuing')
+        @conversation.add_user_message(decision[:reason])
+        true
+      end
+
       # Empty LLM response (0 content blocks). Common after dispatching
       # background_run — the LLM has nothing to say until results arrive.
       # Wait briefly for jobs, then either continue or accept the empty response.
@@ -243,15 +337,15 @@ module RubynCode
       # after text responses — mirrors Claude Code's "pause for compaction"
       # behavior that keeps context manageable in long sessions.
       def compact_if_needed
-        return unless @context_manager.needs_compaction?(@conversation.messages)
+        return unless @context_manager.needs_compaction?(@conversation)
 
-        est = @context_manager.estimated_tokens(@conversation.messages)
+        est = @context_manager.estimated_tokens(@conversation)
         RubynCode::Debug.token(
           "Context over threshold (#{est}) — running compaction"
         )
         @context_manager.check_compaction!(@conversation)
 
-        after = @context_manager.estimated_tokens(@conversation.messages)
+        after = @context_manager.estimated_tokens(@conversation)
         RubynCode::Debug.token("Compacted: #{est} → #{after} tokens")
       rescue StandardError => e
         RubynCode::Debug.warn("Compaction failed: #{e.message}")
@@ -266,8 +360,8 @@ module RubynCode
         @max_tokens_override = Config::Defaults::ESCALATED_MAX_OUTPUT_TOKENS
       end
 
-      def max_iterations_warning
-        warning = "Reached maximum iteration limit (#{MAX_ITERATIONS}). " \
+      def max_iterations_warning(limit = MAX_ITERATIONS)
+        warning = "Reached maximum iteration limit (#{limit}). " \
                   'The conversation may be incomplete. Please review the ' \
                   'current state and continue if needed.'
         @conversation.add_assistant_message([{ type: 'text', text: warning }])

data/lib/rubyn_code/agent/response_parser.rb

@@ -61,6 +61,14 @@ module RubynCode
         end
       end
 
+      def extract_stop_details(response)
+        if response.respond_to?(:stop_details)
+          response.stop_details
+        elsif response.is_a?(Hash)
+          response[:stop_details] || response['stop_details']
+        end
+      end
+
       def recover_truncated_response(response)
         @max_tokens_override ||= Config::Defaults::ESCALATED_MAX_OUTPUT_TOKENS
         @conversation.add_assistant_message(response_content(response))

data/lib/rubyn_code/agent/system_prompt_builder.rb

@@ -10,7 +10,7 @@ module RubynCode
     module SystemPromptBuilder # rubocop:disable Metrics/ModuleLength -- heavily extracted, residual 3 lines over
       include Prompts
 
-      INSTRUCTION_FILES = %w[RUBYN.md CLAUDE.md AGENT.md].freeze
+      INSTRUCTION_FILES = %w[RUBYN.md CLAUDE.md AGENTS.md AGENT.md].freeze
 
       private
 
@@ -19,16 +19,49 @@ module RubynCode
         parts << PLAN_MODE_PROMPT if @plan_mode
         parts << "Working directory: #{@project_root}" if @project_root
         append_response_mode(parts)
+        static = static_prompt_sections
+        parts << static unless static.empty?
+        parts.join("\n")
+      end
+
+      # The static sections hit SQLite (memories, instincts) and walk the
+      # filesystem (instruction files, profile), so they're assembled once
+      # per user turn instead of on every iteration of the tool loop. Only
+      # the plan-mode flag and response-mode line vary mid-turn, and those
+      # stay in build_system_prompt.
+      def static_prompt_sections
+        @static_prompt_sections ||= build_static_prompt_sections
+      end
+
+      def build_static_prompt_sections
+        parts = []
         append_project_profile(parts)
         append_codebase_index(parts)
         append_memories(parts)
         append_project_instructions(parts)
         append_instincts(parts)
         append_skills(parts)
+        append_chisel_ruleset(parts)
         append_deferred_tools(parts)
         parts.join("\n")
       end
 
+      # Chisel's "write the minimum that works" ruleset, injected only when the
+      # user has turned it on (chisel_mode != off). Guarded so a config or
+      # resolution error never breaks prompt assembly.
+      def append_chisel_ruleset(parts)
+        section = Chisel.prompt_section
+        parts << "\n#{section}" unless section.empty?
+      rescue StandardError
+        nil
+      end
+
+      # Called at the start of each user turn so memory, instruction, and
+      # tool changes made between turns show up in the next prompt.
+      def reset_system_prompt_cache!
+        @static_prompt_sections = nil
+      end
+
       def append_response_mode(parts)
         text = last_user_text
         return if text.empty?
@@ -68,6 +101,9 @@ module RubynCode
         return unless index&.nodes&.any?
 
         parts << "\n## #{index.to_structural_summary}"
+        parts << 'This project has a code graph. To locate or understand code, call `code_graph` FIRST — ' \
+                 'it returns matching symbols with source, callers, and callees in one call. ' \
+                 'Fall back to grep/glob only when code_graph finds nothing.'
       rescue StandardError
         nil
       end
@@ -182,7 +218,9 @@ module RubynCode
 
         db = DB::Connection.instance
         search = Memory::Search.new(db, project_path: @project_root)
-        recent = search.recent(limit: 20)
+        # touch: false — assembling the prompt is not a memory "access";
+        # touching here would issue a SQLite write and inflate access counts.
+        recent = search.recent(limit: 20, touch: false)
         return '' if recent.empty?
 
         recent.map { |m| format_memory(m) }.join("\n")

data/lib/rubyn_code/agent/tool_processor.rb

@@ -52,6 +52,16 @@ module RubynCode
         Tools::Registry.all.select { |t| PLAN_MODE_RISK_LEVELS.include?(t::RISK_LEVEL) }.map(&:to_schema)
       end
 
+      # Tool definitions for the next LLM call: plan mode narrows to
+      # read-only tools; a per-turn allowed-tools override (custom-command
+      # frontmatter, set via Loop#allowed_tools_override=) narrows by name.
+      def filtered_tool_definitions
+        defs = @plan_mode ? read_only_tool_definitions : tool_definitions
+        return defs unless @allowed_tools_override
+
+        DynamicToolSchema.filter(defs, active_names: @allowed_tools_override)
+      end
+
       # -- tool dispatch with budget + signals
       def process_tool_calls(tool_calls)
         aggregate_chars = 0
@@ -116,7 +126,9 @@ module RubynCode
 
       def execute_tool(tool_name, tool_input)
         discover_tool(tool_name)
-        @hook_runner.fire(:pre_tool_use, tool_name: tool_name, tool_input: tool_input)
+        pre_decision = @hook_runner.fire(:pre_tool_use, tool_name: tool_name, tool_input: tool_input)
+        raise RubynCode::UserDeniedError, pre_decision[:reason] if pre_decision.is_a?(Hash) && pre_decision[:deny]
+
         result = dispatch_tool(tool_name, tool_input)
         @hook_runner.fire(:post_tool_use, tool_name: tool_name, tool_input: tool_input, result: result)
         signal_decision_compactor(tool_name, tool_input, result)

data/lib/rubyn_code/auth/oauth.rb

@@ -3,7 +3,6 @@
 require 'securerandom'
 require 'digest'
 require 'base64'
-require 'faraday'
 require 'json'
 
 module RubynCode
@@ -163,6 +162,7 @@ module RubynCode
       end
 
       def http_client
+        require 'faraday'
         @http_client ||= Faraday.new do |f|
           f.options.timeout = 30
           f.options.open_timeout = 10

data/lib/rubyn_code/auth/token_store.rb

@@ -11,13 +11,27 @@ module RubynCode
       EXPIRY_BUFFER_SECONDS = 300 # 5 minutes
       KEYCHAIN_SERVICE = 'Claude Code-credentials'
 
+      # Strategy chain: each method returns a token hash or nil.
+      # First non-nil result wins. Adding a new auth source is a one-line entry.
+      LOAD_STRATEGIES = %i[
+        load_from_keychain
+        load_from_credentials_file
+        load_from_file
+        load_from_env
+      ].freeze
+
       class << self
         # Load tokens with fallback chain:
         # 1. macOS Keychain (Claude Code's OAuth token)
-        # 2. Local YAML file (~/.rubyn-code/tokens.yml)
-        # 3. ANTHROPIC_API_KEY environment variable
+        # 2. Claude Code credentials file (~/.claude/.credentials.json)
+        # 3. Local YAML file (~/.rubyn-code/tokens.yml)
+        # 4. ANTHROPIC_API_KEY environment variable
         def load
-          load_from_keychain || load_from_file || load_from_env
+          LOAD_STRATEGIES.each do |strategy|
+            result = send(strategy)
+            return result if result
+          end
+          nil
         end
 
         # Load API key for a given provider. Anthropic uses the full fallback chain.
@@ -68,7 +82,12 @@ module RubynCode
         end
 
         def valid?
-          tokens = self.load
+          valid_tokens?(self.load)
+        end
+
+        # Validate an already-loaded token hash without re-reading the
+        # keychain — lets callers cache the result of `load`.
+        def valid_tokens?(tokens)
           return false unless tokens&.fetch(:access_token, nil)
           return true if tokens[:type] == :api_key
           return true unless tokens[:expires_at]
@@ -88,6 +107,7 @@ module RubynCode
           default
         end
 
+        # macOS only: read from Keychain Services
         def load_from_keychain
           return nil unless RUBY_PLATFORM.include?('darwin')
 
@@ -102,6 +122,21 @@ module RubynCode
           nil
         end
 
+        # Linux/other: Claude Code stores OAuth in a plain JSON file
+        def load_from_credentials_file
+          path = Config::Defaults::CLAUDE_CREDENTIALS_FILE
+          return nil unless File.exist?(path)
+
+          warn_insecure_permissions(path)
+
+          oauth = JSON.parse(File.read(path))['claudeAiOauth']
+          return nil unless oauth&.dig('accessToken')
+
+          build_keychain_tokens(oauth)
+        rescue StandardError
+          nil
+        end
+
         def build_keychain_tokens(oauth)
           {
             access_token: oauth['accessToken'],
@@ -137,6 +172,16 @@ module RubynCode
           { access_token: api_key, refresh_token: nil, expires_at: nil, type: :api_key, source: :env }
         end
 
+        # Warn when credentials file has loose permissions (no system ACLs on Linux)
+        def warn_insecure_permissions(path)
+          mode = File.stat(path).mode & 0o777
+          return if mode == 0o600
+
+          warn "[rubyn-code] WARNING: #{path} has mode #{format('%04o', mode)}, expected 0600"
+        rescue StandardError
+          nil # best-effort — don't fail a token load over a stat
+        end
+
         def write_tokens_file(data)
           File.write(tokens_path, YAML.dump(data))
           File.chmod(0o600, tokens_path)

data/lib/rubyn_code/autonomous/daemon.rb

@@ -212,7 +212,7 @@ module RubynCode
         tokens = extract_token_counts(cm)
         return if tokens.values.all?(&:zero?)
 
-        model = @llm_client.respond_to?(:model) ? @llm_client.model : 'claude-sonnet-4-6'
+        model = @llm_client.respond_to?(:model) ? @llm_client.model : 'claude-sonnet-5'
         @total_cost += Observability::CostCalculator.calculate(model: model, **tokens)
       rescue StandardError
         # Non-critical — cost tracking is best-effort

data/lib/rubyn_code/checkpoint/hook.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Checkpoint
+    # A :pre_tool_use hook that snapshots a file's original contents into the
+    # current checkpoint just before a mutating tool changes it. Only the
+    # file-mutating tools are watched; everything else is ignored.
+    class Hook
+      MUTATING_TOOLS = %w[write_file edit_file].freeze
+
+      # @param manager [Checkpoint::Manager]
+      def initialize(manager:)
+        @manager = manager
+      end
+
+      # @return [nil] never blocks the tool (returns no deny decision)
+      def call(tool_name:, tool_input: {}, **_kwargs)
+        return nil unless MUTATING_TOOLS.include?(tool_name.to_s)
+
+        path = tool_input[:path] || tool_input['path']
+        @manager.record_file(path) if path
+        nil
+      end
+    end
+  end
+end

data/lib/rubyn_code/checkpoint/manager.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module RubynCode
+  # Checkpoints let a user rewind a session, mirroring Claude Code's /rewind.
+  # A checkpoint is taken at the start of each user turn and captures:
+  #   - the conversation state (so chat can be rolled back), and
+  #   - the original contents of every file mutated during that turn (so code
+  #     can be restored).
+  #
+  # File contents are captured lazily by Checkpoint::Hook on :pre_tool_use,
+  # just before a mutating tool runs, so only files that actually change are
+  # snapshotted.
+  module Checkpoint
+    # Marker stored for a path that did not exist when first touched, so a
+    # rewind deletes it rather than recreating empty content.
+    ABSENT = :absent
+
+    class Manager
+      MAX_CHECKPOINTS = 30
+
+      def initialize(project_root:)
+        @project_root = project_root
+        @checkpoints = []
+        @seq = 0
+        @current = nil
+      end
+
+      # Open a new checkpoint for a user turn. Captures the conversation as it
+      # stands before the agent acts.
+      #
+      # @param label [String] short description (usually the user's message)
+      # @param conversation [Agent::Conversation]
+      # @return [Integer] the checkpoint id
+      def checkpoint!(label:, conversation:)
+        @seq += 1
+        @current = {
+          id: @seq,
+          label: summarize(label),
+          messages: Array(conversation.messages).dup,
+          files: {}
+        }
+        @checkpoints << @current
+        @checkpoints.shift while @checkpoints.size > MAX_CHECKPOINTS
+        @seq
+      end
+
+      # Record a file's original contents before it is mutated (once per
+      # checkpoint per path). No-op when no checkpoint is open.
+      #
+      # @param path [String] absolute or project-relative path
+      # @return [void]
+      def record_file(path)
+        return unless @current && path
+
+        abs = File.expand_path(path.to_s, @project_root)
+        return if @current[:files].key?(abs)
+
+        @current[:files][abs] = File.file?(abs) ? File.read(abs) : ABSENT
+      rescue StandardError => e
+        RubynCode::Debug.warn("Checkpoint capture failed for #{path}: #{e.message}")
+      end
+
+      # @return [Array<Hash>] {id:, label:, files:} newest last
+      def list
+        @checkpoints.map { |c| { id: c[:id], label: c[:label], files: c[:files].size } }
+      end
+
+      def empty? = @checkpoints.empty?
+
+      def latest_id = @checkpoints.last&.fetch(:id)
+
+      # Restore a checkpoint. Scope :both (default), :code, or :chat.
+      # Checkpoints newer than the restored one are discarded.
+      #
+      # @return [Hash, nil] summary { id:, files_restored: } or nil if not found
+      def restore(id, conversation, scope: :both)
+        checkpoint = @checkpoints.find { |c| c[:id] == id }
+        return nil unless checkpoint
+
+        restored_files = restore_files(checkpoint) if %i[both code].include?(scope)
+        conversation.replace!(checkpoint[:messages].dup) if %i[both chat].include?(scope)
+
+        @checkpoints.reject! { |c| c[:id] > id }
+        @current = nil
+        { id: id, files_restored: restored_files || 0 }
+      end
+
+      private
+
+      def restore_files(checkpoint)
+        checkpoint[:files].each do |abs, content|
+          if content == ABSENT
+            FileUtils.rm_f(abs)
+          else
+            File.write(abs, content)
+          end
+        end
+        checkpoint[:files].size
+      end
+
+      def summarize(label)
+        text = label.to_s.tr("\n", ' ').strip
+        text.length > 60 ? "#{text[0, 57]}…" : text
+      end
+    end
+  end
+end

data/lib/rubyn_code/chisel/debt.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Chisel
+    # Harvests inline deferral markers from the codebase. A marker is a code
+    # comment whose text begins with the lowercase tag "chisel:" and records a
+    # simplification you consciously postponed (e.g. a comment reading
+    # "chisel: collapse this adapter once a second caller exists").
+    #
+    # Finding them is a deterministic grep — stdlib does it, so there's no LLM
+    # round-trip here (Chisel's own ladder, applied to Chisel).
+    module Debt
+      Item = Data.define(:file, :line, :note)
+
+      # The whole line must be a comment whose first token is the lowercase tag:
+      # optional indentation, a `#` or `//` leader, then `chisel:`, then the note.
+      # Anchoring to line-start means a `chisel:` substring inside a string
+      # literal or a trailing code comment is NOT harvested — only a marker on its
+      # own comment line is. Case-sensitive on purpose, so a descriptive comment
+      # that merely starts with "Chisel:" is not a marker.
+      MARKER = %r{\A\s*(?:#|//)\s*chisel:\s*(\S.*)}
+
+      SCAN_EXTENSIONS = %w[.rb .rake .erb .ru .gemspec].freeze
+      SKIP_DIRS = %w[.git node_modules vendor coverage tmp log].freeze
+
+      module_function
+
+      # @param root [String, nil] project root to scan
+      # @return [Array<Item>] markers found, in file/line order
+      def scan(root)
+        return [] unless root
+
+        base = File.expand_path(root)
+        return [] unless Dir.exist?(base)
+
+        source_files(base).flat_map { |path| scan_file(base, path) }
+      end
+
+      # @param base [String] expanded project root (no trailing slash)
+      # @return [Array<String>] absolute paths of scannable source files
+      def source_files(base)
+        pattern = File.join(base, '**', "*{#{SCAN_EXTENSIONS.join(',')}}")
+        Dir.glob(pattern).reject { |path| skip?(base, path) }.sort
+      end
+
+      def skip?(base, path)
+        rel = path.delete_prefix("#{base}/")
+        SKIP_DIRS.any? { |dir| rel == dir || rel.start_with?("#{dir}/") || rel.include?("/#{dir}/") }
+      end
+
+      # @return [Array<Item>] markers in a single file ([] if it can't be read)
+      def scan_file(base, path)
+        rel = path.delete_prefix("#{base}/")
+        items = []
+        File.foreach(path).with_index(1) do |line, number|
+          match = MARKER.match(line)
+          items << Item.new(file: rel, line: number, note: match[1].strip) if match
+        end
+        items
+      rescue StandardError
+        []
+      end
+    end
+  end
+end