woods 2.0.0.beta3 → 2.0.0.beta4

data/lib/woods/mcp/tool_contract.rb

@@ -27,7 +27,7 @@ module Woods
           text: { type: 'string' },
           data: {
             type: %w[object array string number boolean null],
-            description: 'Parsed JSON payload when the selected renderer emits JSON.'
+            description: 'Structured tool payload, including traversal data in every renderer; otherwise parsed JSON when available.'
           }
         },
         required: ['text'],

data/lib/woods/mcp/tool_response_renderer.rb

@@ -70,6 +70,22 @@ module Woods
 
       private
 
+      def traversal_coverage_lines(data)
+        coverage = fetch_key(data, :graph_coverage)
+        notice = fetch_key(coverage, :notice) if coverage.is_a?(Hash)
+        notice ? [notice] : []
+      end
+
+      def traversal_lower_bound_note(data, shown)
+        return unless fetch_key(data, :total_is_exact) == false
+
+        total = fetch_key(data, :nodes_total, shown)
+        offset = fetch_key(data, :nodes_offset, 0)
+        position = offset.positive? ? " from offset #{offset}" : ''
+        "Showing #{shown} of at least #{total}#{position} " \
+          "(total unknown: #{fetch_key(data, :partial_reason)})."
+      end
+
       def search_completeness_lines(data)
         evidence = fetch_key(data, :completeness)
         return [] unless evidence.is_a?(Hash)

data/lib/woods/mcp/traversal_evidence_text.rb

@@ -40,7 +40,7 @@ module Woods
         complete = value(witness, :typed_path_complete) ? 'yes' : 'no'
         context = value(witness, :context) ? 'yes' : 'no'
         "#{identifier}: #{value(witness, :impact)}; parent=#{parent}; edge=#{edge}; " \
-          "typed path complete=#{complete}; context only=#{context}"
+          "witness types unambiguous=#{complete}; context only=#{context}"
       end
 
       def self.value(hash, key)

data/lib/woods/mcp/traversal_response.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Woods
+  module MCP
+    # Response scope is independent of traversal evidence and page selection.
+    module TraversalResponse
+      COVERAGE = {
+        scope: 'published_relationships',
+        source_references: 'not_exhaustive',
+        notice: 'Graph coverage: published relationships only. Arbitrary method-body constant references ' \
+                'are not exhaustively captured; missing relationships do not prove no callers or dependencies.'
+      }.freeze
+
+      def self.annotate(result)
+        return if result[:found] == false
+
+        result[:graph_coverage] = COVERAGE
+        result[:total_is_exact] = !result[:partial]
+      end
+    end
+  end
+end

data/lib/woods/path_dispatcher.rb

@@ -16,10 +16,9 @@ module Woods
   #
   # * {.file_rules} — file-based extractors, whose per-file method can be
   #   pointed straight at the new path.
-  # * {.whole_app_rules} — extractors with no per-file entry point (routes,
-  #   middleware, engines, scheduled jobs, state machines, factories,
-  #   events, framework sources). Their trigger paths map to a wholesale
-  #   re-run of that extractor, which is cheap in an already-booted process.
+  # * {.whole_app_rules} — extractors needing the complete runtime or source
+  #   set (routes, middleware, merged Rake tasks, scheduled jobs, etc.). Their
+  #   trigger paths map to a wholesale re-run of that extractor.
   #
   # Class-based extractors (models, controllers, mailers, components,
   # channels) are deliberately *absent* here. They are reconciled against
@@ -161,7 +160,6 @@ module Woods
           file_rule(:graphql, :extract_graphql_file,
                     [ex::GraphQLExtractor::GRAPHQL_DIRECTORY], extensions: %w[.rb]),
           file_rule(:i18n, :extract_i18n_file, ex::I18nExtractor::I18N_DIRECTORIES, extensions: %w[.yml]),
-          file_rule(:rake_tasks, :extract_rake_file, ex::RakeTaskExtractor::RAKE_DIRECTORIES, extensions: %w[.rake]),
           file_rule(:view_templates, :extract_view_template_file,
                     ex::ViewTemplateExtractor::VIEW_DIRECTORIES, extensions: view_template_extensions),
           file_rule(:migrations, :extract_migration_file, %w[db/migrate], recursive: false),
@@ -188,6 +186,9 @@ module Woods
 
       def build_whole_app_rules
         [
+          # A task may combine definitions from several files; any change or
+          # deletion must reconcile the complete task set, not its primary file.
+          whole_app_rule(:rake_tasks, Woods::Extractors::RakeTaskExtractor::RAKE_DIRECTORIES, extensions: %w[.rake]),
           whole_app_rule(:routes, %w[config/routes], exact_paths: %w[config/routes.rb]),
           whole_app_rule(:engines, %w[config/routes], exact_paths: %w[config/routes.rb Gemfile.lock]),
           whole_app_rule(:middleware, %w[config/initializers config/environments],

data/lib/woods/published_index/typed_unit_reader.rb

@@ -21,10 +21,47 @@ module Woods
       # @return [Hash, nil] string-keyed unit, or nil when this type has no
       #   such identifier
       def self.call(payload_dir, reader, identifier, type)
-        dir = Woods::MCP::IndexReader::TYPE_TO_DIR[type]
+        dir = directory_for(type)
         return nil unless dir
-        return nil unless reader.list_units(type: type).any? { |entry| entry['identifier'] == identifier }
 
+        family = Woods::MCP::IndexReader::DIR_TO_TYPE.fetch(dir)
+        return nil unless reader.list_units(type: family).any? { |entry| entry['identifier'] == identifier }
+
+        unit = read_unit(payload_dir, dir, identifier)
+        unit if unit && (unit['type'] == type || type == family)
+      end
+
+      # Resolve actual published types as well as historical directory-family aliases.
+      #
+      # @param type [String]
+      # @return [String, nil]
+      def self.directory_for(type)
+        Woods::MCP::IndexReader::TYPE_TO_DIR[type] ||
+          Woods::MCP::IndexReader::UNIT_TYPES_BY_DIR.find { |_, types| types.include?(type) }&.first
+      end
+
+      # Preserve subtype identity in an index entry from a shared type directory.
+      #
+      # @param payload_dir [Pathname]
+      # @param entry [Hash] published index entry
+      # @param dir [String] type directory
+      # @param requested_type [String, nil] actual type or family alias
+      # @return [Hash, nil] entry with actual type, or nil when filtered out
+      def self.entry(payload_dir, entry, dir, requested_type)
+        family = Woods::MCP::IndexReader::DIR_TO_TYPE.fetch(dir)
+        actual_type = if Woods::MCP::IndexReader::UNIT_TYPES_BY_DIR.fetch(dir).size > 1
+                        read_unit(payload_dir, dir, entry['identifier'])&.fetch('type')
+                      else
+                        family
+                      end
+        return unless actual_type
+        return if requested_type && requested_type != family && requested_type != actual_type
+
+        entry.merge('type' => actual_type)
+      end
+
+      # Read a unit whose directory-index membership has already been established.
+      def self.read_unit(payload_dir, dir, identifier)
         path = payload_dir.join(dir, filename_for(identifier))
         return nil unless path.file?
 
@@ -42,7 +79,7 @@ module Woods
         "#{base}_#{digest}.json"
       end
 
-      private_class_method :filename_for
+      private_class_method :filename_for, :read_unit
     end
   end
 end

data/lib/woods/published_index.rb

@@ -167,14 +167,14 @@ module Woods
     # @return [Array<Hash>]
     def units(type: nil)
       dirs = if type
-               dir = Woods::MCP::IndexReader::TYPE_TO_DIR[type.to_s]
+               dir = TypedUnitReader.directory_for(type.to_s)
                dir ? [dir] : []
              else
                Woods::MCP::IndexReader::TYPE_DIRS
              end
       dirs.flat_map do |dir|
         @reader.list_units(type: Woods::MCP::IndexReader::DIR_TO_TYPE[dir])
-               .map { |entry| entry.merge('type' => Woods::MCP::IndexReader::DIR_TO_TYPE[dir]) }
+               .filter_map { |entry| TypedUnitReader.entry(@payload_dir, entry, dir, type&.to_s) }
       end
     end
 

data/lib/woods/rake_helpers.rb

@@ -183,11 +183,8 @@ module Woods
         woods_sweep_index_dir(output_dir, lock_name)
       end
 
-      # The lock was released (and its file removed) above; drop the guard so
-      # the directory can empty, then remove the now-empty directory. Another
-      # writer may legitimately have recreated content between release and here
-      # — a non-empty directory is left alone rather than forced.
-      woods_remove_if_empty(output_dir, lock_name)
+      # Retain the stable guard and directory: another writer may already hold
+      # the guard after release, before it has created its extraction.lock.
       :cleaned
     end
 
@@ -205,13 +202,6 @@ module Woods
       end
     end
 
-    def woods_remove_if_empty(output_dir, lock_name)
-      FileUtils.rm_f(output_dir.join(Woods::Coordination::PipelineLock.guard_filename(lock_name)))
-      Dir.rmdir(output_dir)
-    rescue SystemCallError
-      nil
-    end
-
     # The root containing the Rakefile that loaded this task file.
     #
     # `woods:watch_status` intentionally avoids Rails boot, so it cannot ask

data/lib/woods/retrieval/lexical_assembler.rb

@@ -16,9 +16,10 @@ module Woods
         SourceEvidence.validate_mode!(evidence)
         raise ArgumentError, 'budget must be a positive Integer' unless budget.is_a?(Integer) && budget.positive?
 
-        context = 'Mode: lexical (field-aware BM25; ranked top 20; token counts estimated).'
-        context += "\nNo lexical matches." if candidates.empty?
-        context = context[0, budget * 4]
+        # Reserve the largest included count before selecting evidence. Replacing
+        # it afterward can only shrink the text; do not refill or reorder sources.
+        notice = count_notice(candidates.size, candidates.size)
+        context = notice[0, budget * 4]
         sources = []
         candidates.each do |candidate|
           unit = candidate.metadata
@@ -50,12 +51,22 @@ module Woods
                        score: candidate.score, matched_fields: candidate.matched_fields, truncated: truncated }
           break if truncated
         end
+        body = context[notice.length..].to_s
+        context = (count_notice(candidates.size, sources.size) + body)[0, budget * 4]
         AssembledContext.new(context: context, tokens_used: estimate_tokens(context), budget: budget,
                              sources: sources, sections: [:primary], skipped_missing_metadata: 0)
       end
 
       private
 
+      def count_notice(candidates, included)
+        text = "Mode: lexical (field-aware BM25; sources included: #{included}; " \
+               "candidates considered: #{candidates}; candidate limit: #{LexicalIndex::DEFAULT_LIMIT}; " \
+               'token counts estimated).'
+        text += "\nNo lexical matches." if candidates.zero?
+        text
+      end
+
       def evidence_text(candidate)
         unit = candidate.metadata
         source = unit['source_code'].to_s

data/lib/woods/retrieval/lexical_index.rb

@@ -13,6 +13,7 @@ module Woods
       RUNTIME_FIELDS = %w[callbacks associations validations scopes concerns included_modules
                           methods instance_methods class_methods actions routes columns table_name
                           description purpose dependencies].freeze
+      DEFAULT_LIMIT = 20
       K1 = 1.2
       B = 0.75
       Document = Struct.new(:key, :unit, :fields, keyword_init: true)
@@ -36,7 +37,7 @@ module Woods
         @frequencies.freeze
       end
 
-      def execute(query:, limit: 20, type_filter: nil, exclude_types: nil)
+      def execute(query:, limit: DEFAULT_LIMIT, type_filter: nil, exclude_types: nil)
         terms = tokenize(query).uniq
         candidates = @documents.filter_map do |doc|
           next unless eligible?(doc.unit, type_filter, exclude_types)

data/lib/woods/session_tracer/file_store.rb

@@ -116,7 +116,8 @@ module Woods
       def clear(session_id)
         with_store_lock do
           FileUtils.rm_f(session_path(session_id))
-          FileUtils.rm_f(legacy_session_path(session_id))
+          legacy = legacy_session_path(session_id)
+          FileUtils.rm_f(legacy) if legacy
         end
       end
 
@@ -158,6 +159,10 @@ module Woods
       def migrate_legacy_session!(session_id)
         target = session_path(session_id)
         legacy = legacy_session_path(session_id)
+        # Expire each half before a merge or append can refresh its mtime.
+        [target, legacy].compact.each do |path|
+          FileUtils.rm_f(path) if File.exist?(path) && expired?(path)
+        end
         return target unless legacy && File.exist?(legacy)
 
         if File.exist?(target)

data/lib/woods/source_inputs/consumer_errors.rb

@@ -14,6 +14,10 @@ module Woods
         consumer.instance_variable_set(FLAG, true)
       end
 
+      def reset(consumer)
+        consumer.instance_variable_set(FLAG, false)
+      end
+
       def failed?(consumer)
         consumer && consumer.instance_variable_get(FLAG) == true
       end

data/lib/woods/storage/pgvector.rb

@@ -26,6 +26,7 @@ module Woods
       class Pgvector # rubocop:disable Metrics/ClassLength
         include Interface
 
+        MAX_HNSW_DIMENSIONS = 2000
         TABLE = 'woods_vectors'
         TABLE_NAME_PATTERN = /\A[a-z_][a-z0-9_]*\z/
 
@@ -219,9 +220,12 @@ module Woods
         private
 
         def normalize_dimensions(value)
-          return value if value.is_a?(Integer) && value.positive?
+          raise ArgumentError, 'dimensions must be a positive Integer' unless value.is_a?(Integer) && value.positive?
+          return value if value <= MAX_HNSW_DIMENSIONS
 
-          raise ArgumentError, 'dimensions must be a positive Integer'
+          raise ArgumentError,
+                "pgvector HNSW vector dimensions must be at most #{MAX_HNSW_DIMENSIONS}, got #{value}. " \
+                'Request a supported provider output width or choose another vector backend.'
         end
 
         def validate_identifier!(name, value, original)

data/lib/woods/temporal/json_snapshot_store.rb

@@ -22,7 +22,7 @@ module Woods
     #
     # Implements the same public interface as SnapshotStore so the MCP server
     # tools work identically.
-    # Malformed, non-object, or unreadable retained snapshots (including files
+    # Malformed, invalidly shaped, or unreadable retained snapshots (including files
     # removed during retention) are warned about and treated as absent:
     # +find+ returns nil, +diff+ returns an empty result, and history/list scans
     # omit the corrupt file.
@@ -95,7 +95,6 @@ module Woods
         snapshots = load_all_with_units
                     .sort_by { |s| s[:extracted_at] || '' }
                     .reverse
-                    .first(limit)
 
         entries = snapshots.flat_map do |snap|
           snap[:units].values.select { |unit| unit[:identifier] == identifier }.map do |unit|
@@ -150,10 +149,8 @@ module Woods
           sha = File.basename(path, '.json')
           next unless sha.match?(/\A[0-9a-f]+\z/i) && File.file?(path)
 
-          data = read_snapshot(path) || {}
-          timestamp = data['extracted_at']
-          valid = data['git_sha'] == sha && timestamp.is_a?(String)
-          { git_sha: sha, extracted_at: valid ? timestamp : '', corrupt: !valid }
+          data = read_snapshot(path)
+          { git_sha: sha, extracted_at: data&.[]('extracted_at') || '', corrupt: data.nil? }
         end
       end
 
@@ -280,7 +277,10 @@ module Woods
 
       def read_snapshot(path)
         data = JSON.parse(AtomicFile.read(path))
-        raise JSON::ParserError, 'expected a JSON object' unless data.is_a?(Hash)
+        validate_snapshot_shape!(data)
+        unless data['git_sha'] == File.basename(path, '.json')
+          raise JSON::ParserError, 'git_sha does not match the snapshot filename'
+        end
 
         data
       rescue JSON::ParserError => e
@@ -291,6 +291,34 @@ module Woods
         nil
       end
 
+      # Guard only shapes consumed by conversion, sorting, and the next capture.
+      # Legacy files can omit units/timestamps and optional per-unit hashes;
+      # bare unit keys still supply identifiers when the record does not.
+      def validate_snapshot_shape!(data)
+        raise JSON::ParserError, 'expected a JSON object' unless data.is_a?(Hash)
+
+        sha = data['git_sha']
+        unless sha.is_a?(String) && sha.match?(/\A[0-9a-f]+\z/i)
+          raise JSON::ParserError, 'expected git_sha to be a hexadecimal string'
+        end
+
+        timestamp = data['extracted_at']
+        unless timestamp.nil? || timestamp.is_a?(String)
+          raise JSON::ParserError, 'expected extracted_at to be a string or null'
+        end
+
+        validate_snapshot_units!(data['units'])
+      end
+
+      def validate_snapshot_units!(units)
+        return if units.nil?
+
+        raise JSON::ParserError, 'expected units to be an object or null' unless units.is_a?(Hash)
+        return if units.each_value.all?(Hash)
+
+        raise JSON::ParserError, 'expected every unit record to be an object'
+      end
+
       # @param exclude_sha [String, nil] SHA to leave out of the result
       # @return [Hash, nil]
       def find_latest(exclude_sha: nil)

data/lib/woods/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Woods
-  VERSION = '2.0.0.beta3'
+  VERSION = '2.0.0.beta4'
 end

data/lib/woods/watch/daemon.rb

@@ -583,7 +583,7 @@ module Woods
         return unless @catch_up
 
         carried = restore_pending
-        paths = (uncovered_paths + carried).uniq
+        paths = (uncovered_paths + carried + vanished_restart_paths).uniq
         boot_changes = @boot_snapshot ? @boot_snapshot.changed_paths : []
         enqueue(boot_changes) unless boot_changes.empty?
         prepare_startup_reconciliation(paths)
@@ -623,7 +623,8 @@ module Woods
       # graph knows every path it attributed a unit to; any of those gone from
       # disk means the extractor's sweep has reconciling to do.
       #
-      # The daemon only *detects*; it does not name the paths. Naming them
+      # Except for boot inputs handled by vanished_restart_paths, the daemon
+      # only detects; it does not name the paths. Naming them
       # would put them in the change set, whose deletions are authoritative for
       # any unit type — and some registered paths are nominal (on Rails < 7.1,
       # `ActiveRecord::SchemaMigration` registers a convention path no app
@@ -631,9 +632,22 @@ module Woods
       # still produces. An empty-change-set run reaches the same ghosts through
       # the sweep, which carries the bounds that make it safe.
       def stale_deletions?
-        root_prefix = "#{@root}/"
+        vanished_registered_paths.any?
+      end
+
+      # Deleted boot inputs have no mtime and are absent from a fresh snapshot.
+      # Preserve their restart obligation so a boot that already omitted them
+      # performs a full extraction. Do not promote nominal model paths to
+      # authoritative deletions, even when application reloading is disabled.
+      def vanished_restart_paths
+        vanished_registered_paths.select do |path|
+          @policy.classify(path.delete_prefix("#{@root}/")) == :restart
+        end
+      end
 
-        persisted_registered_paths.any? do |path|
+      def vanished_registered_paths
+        root_prefix = "#{@root}/"
+        persisted_registered_paths.select do |path|
           path.start_with?(root_prefix) && !File.exist?(path)
         end
       end

data/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "woods-plugin",
   "description": "Woods user guides for Claude Code: set up, upgrade, configure MCP servers for, investigate codebases with, enable a repository's agents on, and diagnose the Woods Rails code-intelligence gem.",
-  "version": "2.3.36",
+  "version": "2.3.47",
   "author": {
     "name": "lost-in-the"
   },

data/plugin/hooks/woods-input-rules.sh

@@ -75,10 +75,6 @@ woods_input_action() {
     case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
     return
   fi
-  if { { { [[ "$path" == *.rake ]]; } && { [[ "$path" == lib/tasks/* ]]; }; }; }; then
-    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
-    return
-  fi
   if { { { [[ "$path" == *.html.erb ]] || [[ "$path" == *.erb ]]; } && { [[ "$path" == app/views/* ]]; }; }; }; then
     case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
     return
@@ -115,6 +111,10 @@ woods_input_action() {
     case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
     return
   fi
+  if { { { [[ "$path" == *.rake ]]; } && { [[ "$path" == lib/tasks/* ]]; }; }; }; then
+    case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
+    return
+  fi
   if { [[ "$path" == config/routes.rb ]] || { { [[ "$path" == config/routes/* ]]; }; }; }; then
     case "$operation" in delete|move) printf full ;; *) printf incremental ;; esac
     return

data/plugin/skills/woods-agent-enable/SKILL.md

@@ -9,7 +9,7 @@ Installing the gem gives one operator an index; this skill gives every future ag
 
 ## Managed configuration availability
 
-`woods-agent-config` (#407) is unreleased after `2.0.0.beta2`. First record the
+`woods-agent-config` (#407) is available in Woods `2.0.0.beta3`. First record the
 installed version and test `bundle exec woods-agent-config --help` in the
 selected application bundle. When supported, use its saved setup/update/remove
 plan and explicit client/scope/root selection; apply the reviewed plan within
@@ -20,6 +20,12 @@ journals contain private configuration bytes. See the canonical
 for host/Compose preflight, actual Claude file locations, conflict recovery,
 and removal. Preserve manual setup for older installed versions.
 
+For concurrent configuration operations, wait for the active operation to
+finish and generate a fresh plan if the saved snapshots changed. Do not remove
+its lock or overwrite the other application's entry. Coordination across
+applications sharing user configuration is unreleased after `2.0.0.beta3`;
+check the installed revision before relying on it.
+
 ## Preflight
 
 Confirm Woods actually works before advertising it to every future session: