woods 1.4.1 → 1.6.0

data/lib/woods/extractors/rake_task_extractor.rb

@@ -34,9 +34,7 @@ module Woods
       #
       # @return [Array<ExtractedUnit>] List of rake task units
       def extract_all
-        @directories.flat_map do |dir|
-          Dir[dir.join('**/*.rake')].flat_map { |file| extract_rake_file(file) }
-        end
+        find_files_in_directories(@directories, '**/*.rake').flat_map { |file| extract_rake_file(file) }
       end
 
       # Extract rake tasks from a single .rake file.
@@ -336,7 +334,7 @@ module Woods
           deps << { type: :rake_task, target: dep, via: :task_dependency }
         end
 
-        deps.uniq { |d| [d[:type], d[:target]] }
+        consolidate_dependencies(deps)
       end
     end
   end

data/lib/woods/extractors/serializer_extractor.rb

@@ -52,11 +52,9 @@ module Woods
         units = []
 
         # File-based discovery (catches everything in known directories)
-        @directories.each do |dir|
-          Dir[dir.join('**/*.rb')].each do |file|
-            unit = extract_serializer_file(file)
-            units << unit if unit
-          end
+        find_files_in_directories(@directories).each do |file|
+          unit = extract_serializer_file(file)
+          units << unit if unit
         end
 
         # Class-based discovery for loaded gems
@@ -332,7 +330,7 @@ module Woods
 
         deps.concat(scan_service_dependencies(source))
 
-        deps.uniq { |d| [d[:type], d[:target]] }
+        consolidate_dependencies(deps)
       end
     end
   end

data/lib/woods/extractors/service_extractor.rb

@@ -44,10 +44,8 @@ module Woods
       #
       # @return [Array<ExtractedUnit>] List of service units
       def extract_all
-        @directories.flat_map do |dir|
-          Dir[dir.join('**/*.rb')].filter_map do |file|
-            extract_service_file(file)
-          end
+        find_files_in_directories(@directories).filter_map do |file|
+          extract_service_file(file)
         end
       end
 
@@ -210,7 +208,7 @@ module Woods
           deps << { type: :infrastructure, target: :redis, via: :code_reference }
         end
 
-        deps.uniq { |d| [d[:type], d[:target]] }
+        consolidate_dependencies(deps)
       end
     end
   end

data/lib/woods/extractors/shared_dependency_scanner.rb

@@ -23,7 +23,7 @@ module Woods
     #     def extract_dependencies(source)
     #       deps = scan_common_dependencies(source)
     #       deps << { type: :custom, target: "Bar", via: :special }
-    #       deps.uniq { |d| [d[:type], d[:target]] }
+    #       consolidate_dependencies(deps)
     #     end
     #   end
     #
@@ -45,22 +45,27 @@ module Woods
       # @param via [Symbol] Relationship label (default: :code_reference)
       # @return [Array<Hash>] Dependency hashes with :type, :target, :via
       def scan_model_dependencies(source, via: :code_reference)
+        # Strip `#` line comments before scanning so references inside
+        # YARD docstrings / TODO comments don't generate ghost edges.
+        # Applied to ALL passes — a commented `Library::Book` should not
+        # produce an edge through the full-name pass. Stripping is
+        # string-literal-aware: a `#` inside a `"..."`/`'...'` literal is
+        # NOT a comment, so a line like `link_to "Tag #ruby", Article.recent`
+        # keeps its `Article` reference (a plain `#...` regex would have
+        # eaten the rest of the line and dropped the edge). String
+        # interpolation (`"Book: #{Library::Book.new}"`) is preserved for the
+        # same reason — the `#{...}` lives inside the literal.
+        scannable = strip_ruby_line_comments(source)
+
         targets = Set.new
-        source.scan(ModelNameCache.model_names_regex).each { |m| targets << m }
-        extract_constantize_targets(source).each { |t| targets << t }
+        scannable.scan(ModelNameCache.model_names_regex).each { |m| targets << m }
+        extract_constantize_targets(scannable).each { |t| targets << t }
 
         # Short-name + constantize resolution are additive passes guarded
         # by `respond_to?` so partial test doubles that only stub
         # `model_names_regex` still work. Real extraction runs always
         # have the full API.
         if ModelNameCache.respond_to?(:short_names_regex) && ModelNameCache.respond_to?(:resolve_short_name)
-          # Strip `#` line comments before scanning so references inside
-          # YARD docstrings / TODO comments don't generate ghost edges.
-          # The negative lookahead `(?!\{)` keeps Ruby's `#{...}` string
-          # interpolation intact — stripping blindly would eat every model
-          # reference inside `"Book: #{Library::Book.new}"` etc., which
-          # is a common ERB/Phlex/string pattern.
-          scannable = source.gsub(/#(?!\{)[^\n]*/, '')
           scannable.scan(ModelNameCache.short_names_regex).each do |short|
             resolved = ModelNameCache.resolve_short_name(short)
             targets << resolved if resolved
@@ -70,6 +75,58 @@ module Woods
         targets.map { |model_name| { type: :model, target: model_name, via: via } }
       end
 
+      # Remove `#` line comments from Ruby source without touching `#`
+      # characters that sit inside single- or double-quoted string literals.
+      #
+      # A naive `gsub(/#.*/, '')` truncates lines like
+      # `redirect "/posts#comments"; Post.touch` at the in-string `#`,
+      # silently dropping the `Post` reference. This scanner walks each line
+      # tracking quote state so only a genuine (unquoted) `#` starts a
+      # comment. Escapes (`\"`, `\'`) inside literals are honored. Heredocs,
+      # `%`-literals, and character literals whose char is a quote (`?'`,
+      # `?"`) are not modeled — these are rare in the constant-bearing code
+      # this scans, and mis-reading one only risks a spurious edge (a comment
+      # left unstripped) or a missed edge, never a crash or a dropped-but-real
+      # reference outside those constructs.
+      #
+      # @param source [String] Ruby source code
+      # @return [String] source with unquoted `#` comments removed
+      def strip_ruby_line_comments(source)
+        source.each_line.map { |line| strip_line_comment(line) }.join
+      end
+
+      # Strip a trailing `#` comment from a single line, ignoring `#` inside
+      # string literals. Preserves the line's trailing newline.
+      #
+      # @param line [String]
+      # @return [String]
+      def strip_line_comment(line)
+        in_single = false
+        in_double = false
+        i = 0
+        len = line.length
+        while i < len
+          ch = line[i]
+          if (in_single || in_double) && ch == '\\'
+            i += 2 # skip escaped char inside a literal
+            next
+          elsif in_single
+            in_single = false if ch == "'"
+          elsif in_double
+            in_double = false if ch == '"'
+          elsif ch == "'"
+            in_single = true
+          elsif ch == '"'
+            in_double = true
+          elsif ch == '#'
+            trailing = line[i..].end_with?("\n") ? "\n" : ''
+            return line[0...i] + trailing
+          end
+          i += 1
+        end
+        line
+      end
+
       # Extract string-literal arguments passed to `.constantize` or
       # `const_get(...)`. Matches both `"Library::Book".constantize`
       # and `Object.const_get("Library::Book")` / `const_get("...")`.
@@ -137,12 +194,27 @@ module Woods
       # @param source [String] Ruby source code to scan
       # @return [Array<Hash>] Deduplicated dependency hashes
       def scan_common_dependencies(source)
-        deps = []
-        deps.concat(scan_model_dependencies(source))
-        deps.concat(scan_service_dependencies(source))
-        deps.concat(scan_job_dependencies(source))
-        deps.concat(scan_mailer_dependencies(source))
-        deps.uniq { |d| [d[:type], d[:target]] }
+        consolidate_dependencies(
+          scan_model_dependencies(source),
+          scan_service_dependencies(source),
+          scan_job_dependencies(source),
+          scan_mailer_dependencies(source)
+        )
+      end
+
+      # Merge dependency arrays and deduplicate by +[type, target]+.
+      #
+      # Centralizes the `deps.uniq { |d| [d[:type], d[:target]] }` chain
+      # duplicated at the end of most extractors' +extract_dependencies+
+      # methods. Arrays are flattened one level and nils removed; the first
+      # occurrence of each +[type, target]+ pair wins, so the first +:via+
+      # label recorded is preserved — identical to the inline chains this
+      # replaces.
+      #
+      # @param dependency_arrays [Array<Array<Hash>>] One or more dependency arrays
+      # @return [Array<Hash>] Flattened, nil-free, deduplicated dependency hashes
+      def consolidate_dependencies(*dependency_arrays)
+        dependency_arrays.flatten(1).compact.uniq { |d| [d[:type], d[:target]] }
       end
 
       # Match _path/_url route helpers anywhere in source.

data/lib/woods/extractors/shared_utility_methods.rb

@@ -20,6 +20,20 @@ module Woods
     #   end
     #
     module SharedUtilityMethods
+      # Glob files matching a pattern across a list of directories.
+      #
+      # Centralizes the `Dir[dir.join('**/*.rb')]` loop duplicated across
+      # the directory-scanning extractors. Directories are globbed in order
+      # and the per-directory results concatenated, matching the original
+      # per-directory iteration semantics.
+      #
+      # @param directories [Array<Pathname>] Directories to glob
+      # @param pattern [String] Glob pattern relative to each directory
+      # @return [Array<String>] Matching file paths
+      def find_files_in_directories(directories, pattern = '**/*.rb')
+        directories.flat_map { |dir| Dir[dir.join(pattern).to_s] }
+      end
+
       # Check whether a path points to application source (under app_root, but
       # not inside vendor/ or node_modules/ directories).
       #

data/lib/woods/extractors/state_machine_extractor.rb

@@ -36,9 +36,7 @@ module Woods
       #
       # @return [Array<ExtractedUnit>] List of state machine units
       def extract_all
-        @directories.flat_map do |dir|
-          Dir[dir.join('**/*.rb')].flat_map { |file| extract_model_file(file) }
-        end
+        find_files_in_directories(@directories).flat_map { |file| extract_model_file(file) }
       end
 
       # Extract state machine definitions from a single model file.
@@ -391,7 +389,7 @@ module Woods
         deps = [{ type: :model, target: class_name, via: :state_machine }]
         deps.concat(scan_service_dependencies(source, via: :state_machine_callback))
         deps.concat(scan_job_dependencies(source, via: :state_machine_callback))
-        deps.uniq { |d| [d[:type], d[:target]] }
+        consolidate_dependencies(deps)
       end
     end
   end

data/lib/woods/extractors/validator_extractor.rb

@@ -41,10 +41,8 @@ module Woods
       #
       # @return [Array<ExtractedUnit>] List of validator units
       def extract_all
-        @directories.flat_map do |dir|
-          Dir[dir.join('**/*.rb')].filter_map do |file|
-            extract_validator_file(file)
-          end
+        find_files_in_directories(@directories).filter_map do |file|
+          extract_validator_file(file)
         end
       end
 
@@ -204,7 +202,7 @@ module Woods
           deps << { type: :validator, target: validator, via: :code_reference }
         end
 
-        deps.uniq { |d| [d[:type], d[:target]] }
+        consolidate_dependencies(deps)
       end
     end
   end

data/lib/woods/extractors/view_component_extractor.rb

@@ -315,7 +315,7 @@ module Woods
           deps << { type: :route, target: route, via: :url_helper }
         end
 
-        deps.uniq { |d| [d[:type], d[:target]] }
+        consolidate_dependencies(deps)
       end
     end
   end

data/lib/woods/filename_utils.rb

@@ -8,12 +8,41 @@ module Woods
   # Used by Extractor (writing) and IndexValidator (reading) to ensure
   # filename generation is consistent across both sides.
   module FilenameUtils
+    # Normalize a single identifier segment for use in a filename: replace
+    # `::` with `__` and every other non-`[a-zA-Z0-9_-]` character with `_`.
+    # This is the one character transform shared by {#safe_filename},
+    # {#collision_safe_filename}, and the precomputed-flow reader/writer
+    # (via {.flow_filename}) so the sides of each filename contract cannot
+    # drift. Also usable as a module method (`FilenameUtils.safe_segment`)
+    # for callers that don't mix the module in.
+    #
+    # @param identifier [String]
+    # @return [String]
+    def self.safe_segment(identifier)
+      identifier.to_s.gsub('::', '__').gsub(/[^a-zA-Z0-9_-]/, '_')
+    end
+
+    # Filename for a precomputed request-flow document, combining the
+    # controller identifier and action name — each normalized via
+    # {.safe_segment}. Used by both {Woods::FlowPrecomputer} (writing) and the
+    # MCP server's `trace_flow` (reading) so a name containing an
+    # out-of-charset character is written and looked up under the SAME file
+    # (the writer previously left the action raw while the reader allow-listed
+    # it, so such flows were written under one name and never found).
+    #
+    # @param controller_id [String] e.g. "Admin::UsersController"
+    # @param action [String] e.g. "index"
+    # @return [String] e.g. "Admin__UsersController_index.json"
+    def self.flow_filename(controller_id, action)
+      "#{safe_segment(controller_id)}_#{safe_segment(action)}.json"
+    end
+
     # Convert an identifier to a safe filename (legacy format).
     #
     # @param identifier [String] The unit identifier (e.g., "Admin::UsersController")
     # @return [String] A filesystem-safe filename (e.g., "Admin__UsersController.json")
     def safe_filename(identifier)
-      "#{identifier.gsub('::', '__').gsub(/[^a-zA-Z0-9_-]/, '_')}.json"
+      "#{FilenameUtils.safe_segment(identifier)}.json"
     end
 
     # Convert an identifier to a collision-safe filename (current format).
@@ -24,7 +53,7 @@ module Woods
     # @param identifier [String] The unit identifier
     # @return [String] Collision-safe filename (e.g., "Admin__UsersController_a1b2c3d4.json")
     def collision_safe_filename(identifier)
-      base = identifier.gsub('::', '__').gsub(/[^a-zA-Z0-9_-]/, '_')
+      base = FilenameUtils.safe_segment(identifier)
       digest = Digest::SHA256.hexdigest(identifier)[0, 8]
       "#{base}_#{digest}.json"
     end

data/lib/woods/flow_assembler.rb

@@ -60,19 +60,26 @@ module Woods
 
     # Recursively expand a unit into flow steps.
     #
+    # A cycle is a re-encounter on the CURRENT recursion path (tracked in
+    # +path+, popped on exit — the gray set of a DFS). A unit already
+    # expanded via a sibling branch (a DAG diamond: two services calling
+    # the same model) is plain dedup, not a cycle — it is skipped silently
+    # rather than mislabeled with a cycle marker.
+    #
     # @param identifier [String] Unit identifier (may include #method)
     # @param steps [Array<Hash>] Accumulator for step hashes
-    # @param visited [Set<String>] Visited unit identifiers for cycle detection
+    # @param visited [Set<String>] Already-expanded unit identifiers (dedup)
     # @param depth [Integer] Current recursion depth
     # @param max_depth [Integer] Maximum recursion depth
-    def expand(identifier, steps, visited, depth:, max_depth:)
+    # @param path [Set<String>] Identifiers on the current recursion path
+    def expand(identifier, steps, visited, depth:, max_depth:, path: Set.new)
       return if depth > max_depth
 
       # Parse identifier into unit name and optional method
       unit_id, method_name = parse_identifier(identifier)
 
-      if visited.include?(unit_id)
-        # Cycle detected - emit a marker step
+      if path.include?(unit_id)
+        # Genuine cycle — the unit is an ancestor of itself on this path.
         steps << {
           unit: unit_id,
           type: 'cycle',
@@ -81,34 +88,44 @@ module Woods
         return
       end
 
+      # Already expanded through another branch — dedup, not a cycle.
+      return if visited.include?(unit_id)
+
       visited.add(unit_id)
+      path.add(unit_id)
 
-      # Load the unit data from disk
-      unit_data = load_unit(unit_id)
-      return unless unit_data
+      begin
+        # Load the unit data from disk
+        unit_data = load_unit(unit_id)
+        return unless unit_data
 
-      source_code = unit_data[:source_code]
-      return unless source_code && !source_code.empty?
+        source_code = unit_data[:source_code]
+        return unless source_code && !source_code.empty?
 
-      metadata = unit_data[:metadata] || {}
-      unit_type = unit_data[:type]&.to_s
-      file_path = unit_data[:file_path]
+        metadata = unit_data[:metadata] || {}
+        unit_type = unit_data[:type]&.to_s
+        file_path = unit_data[:file_path]
 
-      # Extract operations from the relevant method
-      operations = extract_operations(source_code, method_name, metadata, unit_type)
+        # Extract operations from the relevant method
+        operations = extract_operations(source_code, method_name, metadata, unit_type)
 
-      step = {
-        unit: identifier,
-        type: unit_type,
-        file_path: file_path,
-        operations: operations
-      }
+        step = {
+          unit: identifier,
+          type: unit_type,
+          file_path: file_path,
+          operations: operations
+        }
 
-      steps << step
+        steps << step
 
-      # Recursively expand targets that resolve to known units
-      operations.each do |op|
-        expand_operation(op, identifier, steps, visited, depth: depth, max_depth: max_depth)
+        # Recursively expand targets that resolve to known units
+        operations.each do |op|
+          expand_operation(op, identifier, steps, visited, depth: depth, max_depth: max_depth, path: path)
+        end
+      ensure
+        # Pop on every exit (including the early returns above) — a unit
+        # left on the path would make sibling branches report false cycles.
+        path.delete(unit_id)
       end
     end
 
@@ -178,7 +195,7 @@ module Woods
     # @param visited [Set<String>] Visited unit identifiers for cycle detection
     # @param depth [Integer] Current recursion depth
     # @param max_depth [Integer] Maximum recursion depth
-    def expand_operation(op, current_unit, steps, visited, depth:, max_depth:)
+    def expand_operation(op, current_unit, steps, visited, depth:, max_depth:, path: Set.new)
       case op[:type]
       when :call, :async
         target = op[:target]
@@ -187,14 +204,14 @@ module Woods
         candidate = resolve_target(target)
         return unless candidate
 
-        expand(candidate, steps, visited, depth: depth + 1, max_depth: max_depth)
+        expand(candidate, steps, visited, depth: depth + 1, max_depth: max_depth, path: path)
       when :transaction
         (op[:nested] || []).each do |nested_op|
-          expand_operation(nested_op, current_unit, steps, visited, depth: depth, max_depth: max_depth)
+          expand_operation(nested_op, current_unit, steps, visited, depth: depth, max_depth: max_depth, path: path)
         end
       when :conditional
         ((op[:then_ops] || []) + (op[:else_ops] || [])).each do |branch_op|
-          expand_operation(branch_op, current_unit, steps, visited, depth: depth, max_depth: max_depth)
+          expand_operation(branch_op, current_unit, steps, visited, depth: depth, max_depth: max_depth, path: path)
         end
       end
     end

data/lib/woods/flow_precomputer.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'fileutils'
+require_relative 'filename_utils'
 require_relative 'flow_assembler'
 
 module Woods
@@ -80,7 +81,7 @@ module Woods
     def assemble_and_write(assembler, entry_point, controller_id, action)
       flow = assembler.assemble(entry_point, max_depth: @max_depth)
 
-      filename = "#{controller_id.gsub('::', '__')}_#{action}.json"
+      filename = Woods::FilenameUtils.flow_filename(controller_id, action)
       flow_path = File.join(@flows_dir, filename)
 
       File.write(flow_path, canonical_json(flow.to_h))

data/lib/woods/git_provenance.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Woods
+  # Resolves git provenance (branch + commit SHA) for the extracted codebase,
+  # correctly handling linked git worktrees where +.git+ is a *file* containing a
+  # +gitdir:+ pointer rather than a directory.
+  #
+  # The reported failure (#137): in a worktree, +.git+ points at a real git
+  # directory that may be an absolute host path. When extraction runs somewhere
+  # that path cannot be resolved — e.g. inside a container where the host path is
+  # not mounted — plain +git rev-parse+ fails silently and the manifest used to
+  # fall back to a baked-in +GIT_BRANCH+/+GIT_SHA+ build arg, reporting a stale,
+  # misleading branch.
+  #
+  # Resolution precedence:
+  #
+  # 1. +git -C <root> rev-parse+ — independent of the process working directory,
+  #    and resolves a worktree's +.git+-file pointer when the target git directory
+  #    is reachable. This covers normal checkouts and reachable worktrees.
+  # 2. If that fails, {fallback} decides:
+  #    - A +.git+ entry exists at the root but git couldn't resolve the ref (an
+  #      unmounted worktree gitdir, a corrupted repo): emit {UNKNOWN}. A working
+  #      tree whose ref can't be determined must not be papered over with a
+  #      possibly-stale build arg — that is the #137 bug.
+  #    - No +.git+ at the root at all (a source tarball, or a Docker +COPY+ that
+  #      excludes +.git+), or no +git+ binary: the +GIT_BRANCH+/+GIT_SHA+ env vars
+  #      are the only provenance signal, so honor them if set, else {UNKNOWN}.
+  #
+  # @example
+  #   provenance = Woods::GitProvenance.new(root: Rails.root)
+  #   provenance.branch  # => "main" (or "unknown")
+  #   provenance.sha     # => "a1b2c3..." (or "unknown")
+  class GitProvenance
+    # Sentinel emitted when provenance cannot be determined, in preference to a
+    # stale or misleading fallback value.
+    UNKNOWN = 'unknown'
+
+    # @param root [String, Pathname] repository root (typically +Rails.root+)
+    # @param env [Hash] environment source (default +ENV+; overridable in specs)
+    def initialize(root:, env: ENV)
+      @root = root.to_s
+      @env = env
+    end
+
+    # @return [String] current branch name, or {UNKNOWN}
+    def branch
+      from_git = rev_parse('--abbrev-ref', 'HEAD')
+      # 'HEAD' means detached — not a branch name.
+      return from_git if present?(from_git) && from_git != 'HEAD'
+
+      fallback('GIT_BRANCH')
+    end
+
+    # @return [String] current commit SHA, or {UNKNOWN}
+    def sha
+      from_git = rev_parse('HEAD')
+      return from_git if present?(from_git)
+
+      fallback('GIT_SHA')
+    end
+
+    # @return [Hash{Symbol => String}] +{ git_branch:, git_sha: }+ for the manifest
+    def to_h
+      { git_branch: branch, git_sha: sha }
+    end
+
+    private
+
+    def present?(value)
+      value && !value.empty?
+    end
+
+    # Run git rooted at +@root+ so the result is independent of the process
+    # working directory and resolves a worktree's +.git+-file pointer when the
+    # target git directory is reachable.
+    #
+    # @return [String] stripped output, or empty string on any failure
+    def rev_parse(*args)
+      out, status = Open3.capture2('git', '-C', @root, 'rev-parse', *args)
+      status.success? ? out.strip : ''
+    rescue StandardError
+      ''
+    end
+
+    # Decide what to emit when git resolution produced nothing. A baked +GIT_*+
+    # env var is honored only when this checkout is not a git working tree (no
+    # +.git+ at the root) or git is unavailable. When git is present AND a +.git+
+    # exists but the ref couldn't be resolved (unmounted worktree gitdir), emit
+    # {UNKNOWN} rather than a possibly-stale value (#137).
+    def fallback(env_key)
+      return UNKNOWN if git_available? && git_working_tree?
+
+      value = @env[env_key]
+      present?(value) ? value : UNKNOWN
+    end
+
+    # True when the +git+ command itself can run, independent of any repository.
+    # Memoized — probed at most once per instance even though both +branch+ and
+    # +sha+ may reach {fallback}.
+    def git_available?
+      return @git_available if defined?(@git_available)
+
+      @git_available = begin
+        _out, status = Open3.capture2('git', '--version')
+        status.success?
+      rescue StandardError
+        false
+      end
+    end
+
+    # True when +<root>/.git+ exists — a directory for a normal checkout, or a
+    # file for a linked worktree. Distinguishes "git couldn't resolve this
+    # working tree" (emit UNKNOWN) from "there is no working tree here" (the
+    # env-var build-arg path is legitimate).
+    def git_working_tree?
+      File.exist?(File.join(@root, '.git'))
+    end
+  end
+end

data/lib/woods/index_artifact.rb

@@ -57,9 +57,9 @@ module Woods
     # Returns true when the artifact has never been populated — +woods.json+
     # is absent AND the +dumps/latest+ pointer does not exist.
     #
-    # Once either file is present the artifact is considered non-fresh; the
-    # Bootstrapper uses this to decide whether to raise {Woods::MCP::MissingArtifact}
-    # or proceed with loading.
+    # Once either file is present the artifact is considered non-fresh and the
+    # Bootstrapper loads from it. A fresh artifact boots in pattern-only mode by
+    # default, raising {Woods::MCP::MissingArtifact} only under WOODS_REQUIRE_INDEX=1.
     #
     # @return [Boolean]
     def fresh?
@@ -127,7 +127,11 @@ module Woods
       target_real = target.exist? ? target.realpath.to_s : ''
       # Resolve symlinks on both sides before comparing (handles macOS /tmp → /private/var)
       root_resolved = Pathname.new(root_real).exist? ? Pathname.new(root_real).realpath.to_s : root_real
-      unless target.exist? && target_real.start_with?(root_resolved)
+      # Prefix must end at a path boundary — a bare start_with? would accept
+      # sibling directories like "dumps-backup" or "dumpsevil", and the
+      # basename-only pointer written below would then name a directory that
+      # doesn't exist under dumps_root.
+      unless target.exist? && target_real.start_with?("#{root_resolved}#{File::SEPARATOR}")
         raise ArgumentError,
               'dump_dir must exist inside dumps_root. ' \
               "Got: #{dump_dir.inspect}, dumps_root: #{dumps_root}"

data/lib/woods/mcp/bootstrapper.rb

@@ -84,9 +84,10 @@ module Woods
       #
       # Flow:
       #   1. Wrap output_dir in an IndexArtifact (owns path semantics).
-      #   2. If woods.json is present, resolve config from it; otherwise
-      #      either raise MissingArtifact or, if WOODS_ALLOW_AUTODETECT=1,
-      #      fall back to env-var auto-detect (deprecated path).
+      #   2. If woods.json is present, resolve config from it; otherwise fall
+      #      back to env-var auto-detect by default (pattern/structural mode when
+      #      nothing is found). Set WOODS_REQUIRE_INDEX=1 to fail closed instead
+      #      (raise MissingArtifact). See #138.
       #   3. Build provider + stores from config (no mutation of
       #      Woods.configuration — the host's initializer stays intact).
       #   4. Hydrate in-memory stores from dumps (stubs in PR 2; real in PR 3).
@@ -103,8 +104,8 @@ module Woods
       #   When nil, uses Woods.configuration.output_dir.
       # @return [Array(Woods::Retriever, Woods::MCP::BootstrapState)]
       # @raise [Woods::MCP::BootstrapError] on config-invalid (missing
-      #   credentials, dimension mismatch, unsupported artifact, missing
-      #   artifact with autodetect off).
+      #   credentials, dimension mismatch, unsupported artifact, or a missing
+      #   artifact under WOODS_REQUIRE_INDEX=1).
       def self.build_retriever(index_dir: nil)
         state = BootstrapState.new
         state.mark(:hydrating)