woods 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8991ef048ac039aafe41403a11c320333107ece6ad89da376765107820d27b9
-  data.tar.gz: 3fdc6630de8946e1d2ba074ca0b115588934ff965712f1d18d6d3abeb8c5c50b
+  metadata.gz: 6be4722cd45cc31537b12abfe0dfc48e211aeffc4cc5ff9d0a378b3c2130eb1d
+  data.tar.gz: ba720873764980d05cb85a8598218e7061fbad8df5a9f29fb091cface39dd500
 SHA512:
-  metadata.gz: fed6f9a4a26f68dcd5304bc5ab6ba8a99ead3e5ca872a4c466c8ceb9faa23345e16a8405c14397bccb5fb0290970503b6b5ccb62ffe4d041d583593a64bd619a
-  data.tar.gz: 10451e14fce82dd983d43b60875fac444dbb3eb08092c85f2085c08de79ebeeca7be80c3278de8145b88c841dae3f2cd909035899460dffd243cc85711523975
+  metadata.gz: 0273f5abb61b0cdf7ba2ee95bdc8632a7e31f717d2eb039ddea18f21085bd83dd5c158497c693ccdc59e5d480be1162629fcd3324b7a9457e607d91183c4a5dc
+  data.tar.gz: fa24e32b452eb7c9f3a64267f7c1cd45149e9211611ef87432ec6ce82ca9f2955813bfe778f76cf1003daf2e0cdbf76e3b6590067f1c5fa7cf8a93ff482a0aed

data/CHANGELOG.md

@@ -7,6 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-06-23
+
+### Added
+
+- **Rails 6.0 support: the `railties` floor is lowered from `>= 6.1` to `>= 6.0`**
+  (#135). Woods runs cleanly on the Rails 6.0 series — extraction and index-MCP
+  serving need no 6.1-only API. The only 6.1-introduced calls touched
+  (`connection_db_config`, `has_many_inversing`) are `respond_to?`-guarded and
+  degrade on 6.0; a regression spec locks that in.
+- **CI now runs a Rails version matrix plus a booted-app extraction test** (#136).
+  `Appraisals` + `gemfiles/rails_*.gemfile` exercise Rails 6.0, 6.1, 7.0, 7.1,
+  7.2, and 8.0; the matrix excludes invalid Ruby×Rails pairs (e.g. Rails 6.0 only
+  on Ruby 3.0) and adds a **Ruby 4.0** lane. A new booted-app test
+  (`spec/integration/booted_extraction_spec.rb`, against the minimal `spec/dummy`
+  app) boots Rails in-process and runs a real end-to-end extraction, asserting a
+  non-zero unit count and the expected models/associations — gating the
+  version-sensitive introspection path the unit suite (which stubs Rails) can't.
+
+### Changed
+
+- **The Index Server now boots in pattern-only mode by default when no embedding
+  index is present** (#138). Since 1.3.0, `woods-mcp` raised `MissingArtifact` at
+  boot unless `woods.json` existed or `WOODS_ALLOW_AUTODETECT=1` was set — which
+  surprised the most common setup: `rake woods:extract` with no embedding
+  provider, where pattern/regex/structural search works perfectly. The server now
+  auto-detects by default: it serves all always-on tools (`lookup`, `search`,
+  `dependencies`, `structure`, `graph_analysis`, `pagerank`, …) with no env var,
+  and `codebase_retrieve` (semantic search) activates automatically once an
+  embedding provider is configured. Set `WOODS_REQUIRE_INDEX=1` to restore
+  fail-closed behavior (raise `MissingArtifact` when `woods.json` is absent).
+  `WOODS_ALLOW_AUTODETECT` is retained as a no-op for backward compatibility.
+
+### Fixed
+
+- **`manifest.json` no longer reports a stale `git_branch`/`git_sha` in a git
+  worktree** (#137). In a linked worktree, `.git` is a file pointing at the real
+  git directory (often an absolute host path). When that directory couldn't be
+  resolved — e.g. inside a container where the host path isn't mounted — git
+  enrichment failed silently and the branch/SHA fell back to a baked
+  `GIT_BRANCH`/`GIT_SHA` build arg, reporting an unrelated branch. A new
+  `Woods::GitProvenance` resolves provenance with worktree-aware plumbing
+  (`git -C <root> rev-parse`), and emits `"unknown"` when a `.git` is present but
+  the ref can't be resolved (the worktree case) rather than a misleading value.
+  The `GIT_BRANCH`/`GIT_SHA` env vars are honored only when there is **no** `.git`
+  at the root at all (a non-repo checkout — e.g. a Docker `COPY` that excludes
+  `.git` — with build args supplying the SHA) or git is unavailable. Temporal
+  snapshots skip an `"unknown"` SHA so it can't key or collide a snapshot.
+
+## [1.4.1] - 2026-06-10
+
+### Fixed
+
+- **Unblocked sync: multiple units sharing one file no longer collide on a single
+  URI** (#130). A document's URI derives from `file_path`, so a file defining
+  several extracted units (nested/namespaced classes, STI subclasses, multiple
+  classes in one `.rb`) mapped every unit to the same URI — the remote document
+  was overwritten per unit (only the last survived) and, under the content-hash
+  manifest, those units re-pushed on every run. The exporter now detects files
+  shared by more than one synced unit and disambiguates: the lexically-first
+  identifier keeps the bare blob URL, siblings get a `?unit=<identifier>` suffix.
+  Solo files (the overwhelming majority) are untouched. Sibling of the
+  no-`file_path` guard shipped in 1.4.0.
+
 ## [1.4.0] - 2026-06-10
 
 ### Added — Incremental Unblocked sync (PR #128)

data/CONTRIBUTING.md

@@ -49,6 +49,39 @@ Woods has two test suites:
 
 All new features need tests. Bug fixes should include a regression test.
 
+### Rails version matrix
+
+The gem supports `railties >= 6.0`. Coverage is split across two CI jobs:
+
+- The base unit `test` job runs `rake spec` across **Ruby 3.0–4.0** on the
+  default (newest) Rails. The unit specs stub Rails, so they run once on the base
+  Gemfile rather than per Rails version.
+- The `rails-matrix` job runs the **booted-app extraction test**
+  (`spec/integration/booted_extraction_spec.rb` against `spec/dummy`) under each
+  supported Rails — 6.0, 6.1, 7.0, 7.1, 7.2, 8.0 — using per-version gemfiles
+  under `gemfiles/`. This is the version-sensitive gate: it boots a real Rails
+  app in-process and runs an extraction. (The booted spec is tagged `:booted_app`
+  and excluded from the default `rake spec`; `WOODS_RUN_BOOTED_APP=1` opts it in,
+  and it must run in its own process — it can't share one with the unit suite.)
+
+The Rails pins live in `Appraisals`; the gemfiles are hand-maintained
+(`eval_gemfile`-ing the base `Gemfile` and pinning Rails) because Appraisal can't
+generate from the conditional base Gemfile. To run a single Rails row locally:
+
+```bash
+BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile bundle install
+WOODS_RUN_BOOTED_APP=1 BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile \
+  bundle exec rspec spec/integration/booted_extraction_spec.rb
+```
+
+When adding a Rails line: add it to both `Appraisals` and `gemfiles/`, and add a
+valid Ruby×Rails pair to the `rails-matrix` job in `.github/workflows/ci.yml`.
+**For a row below Rails 7.1**, the gemfile must set `ENV['WOODS_SQLITE3_REQ'] =
+'~> 1.4'` *before* `eval_gemfile` (those Rails versions pin `sqlite3 ~> 1.4` in
+their adapter at load time) and pin `concurrent-ruby '< 1.3.5'` (1.3.5 dropped
+the implicit `require "logger"` those releases rely on under Ruby 3.x) — copy an
+existing `gemfiles/rails_6.0.gemfile` as the template.
+
 ## Code Style
 
 - `frozen_string_literal: true` on every file

data/README.md

@@ -573,8 +573,10 @@ See [Architecture](docs/ARCHITECTURE.md) for the deep dive — extraction phases
 
 ## Requirements
 
-- Ruby >= 3.0
-- Rails >= 6.1
+- Ruby >= 3.0 (through Ruby 4.0)
+- Rails >= 6.0
+
+CI exercises Rails 6.0, 6.1, 7.0, 7.1, 7.2, and 8.0 across Ruby 3.0–4.0 — see the supported-version table in [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md).
 
 Works with MySQL, PostgreSQL, and SQLite. No additional infrastructure required for basic extraction — embedding and vector search are optional add-ons.
 

data/lib/woods/extractor.rb

@@ -10,6 +10,7 @@ require 'set'
 require_relative 'filename_utils'
 require_relative 'extracted_unit'
 require_relative 'dependency_graph'
+require_relative 'git_provenance'
 require_relative 'extractors/model_extractor'
 require_relative 'extractors/controller_extractor'
 require_relative 'extractors/phlex_extractor'
@@ -745,6 +746,12 @@ module Woods
     end
 
     def write_manifest
+      # Worktree-aware git provenance. In a linked worktree +.git+ is a file
+      # pointing at the real git dir; when that dir is unreachable (e.g. an
+      # unmounted host path inside a container) this resolves to "unknown"
+      # rather than a stale GIT_BRANCH/GIT_SHA build arg. See GitProvenance (#137).
+      provenance = GitProvenance.new(root: Rails.root).to_h
+
       manifest = {
         extracted_at: Time.current.iso8601,
         rails_version: Rails.version,
@@ -757,10 +764,9 @@ module Woods
         total_units: @results.values.sum(&:size),
         total_chunks: @results.sum { |_, units| units.sum { |u| u.chunks.size } },
 
-        # Git info — fall back to env vars for Docker/worktree environments
-        # where the git repo may not be directly accessible
-        git_sha: run_git('rev-parse', 'HEAD').presence || ENV['GIT_SHA'].presence,
-        git_branch: run_git('rev-parse', '--abbrev-ref', 'HEAD').presence || ENV['GIT_BRANCH'].presence,
+        # Git provenance (branch/sha), or "unknown" when unresolvable
+        git_sha: provenance[:git_sha],
+        git_branch: provenance[:git_branch],
 
         # For change detection
         gemfile_lock_sha: gemfile_lock_sha,
@@ -787,7 +793,10 @@ module Woods
       return unless manifest_path.exist?
 
       manifest = JSON.parse(File.read(manifest_path))
-      return unless manifest['git_sha']
+      # Snapshots are keyed on the commit SHA — an unresolvable provenance
+      # ("unknown", see GitProvenance/#137) must not key or collide a snapshot.
+      git_sha = manifest['git_sha']
+      return if git_sha.nil? || git_sha == Woods::GitProvenance::UNKNOWN
 
       store = build_snapshot_store
       return unless store

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?

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)

data/lib/woods/mcp/config_resolver.rb

@@ -23,9 +23,12 @@ module Woods
     #    compatible via {ResolvedConfig#assert_compatible!}.
     # 2. +woods.json+ snapshot alone (MCP server running without a host initializer).
     #    The stored config is used to populate +config+ in place.
-    # 3. Environment-variable auto-detect (deprecated, opt-in via
-    #    +WOODS_ALLOW_AUTODETECT=1+). Mutates +config+ to set provider and stores.
-    # 4. If none of the above applies, raises {MissingArtifact}.
+    # 3. Environment-variable auto-detect (the default when +woods.json+ is
+    #    absent and no host provider is set). Wires semantic search if
+    #    +OPENAI_API_KEY+ or a reachable Ollama is found; otherwise leaves the
+    #    provider nil so the server boots in pattern/structural-only mode.
+    # 4. +WOODS_REQUIRE_INDEX=1+ overrides (3) to fail closed, raising
+    #    {MissingArtifact} when +woods.json+ is absent.
     #
     # @example Typical Bootstrapper usage
     #   config, source = ConfigResolver.resolve(Woods.configuration, artifact: artifact)
@@ -43,10 +46,11 @@ module Woods
       # When +woods.json+ is absent and the host already has a provider
       # configured, the host config is trusted and used as-is.
       #
-      # When +woods.json+ is absent and the host has no provider configured:
-      # - If +WOODS_ALLOW_AUTODETECT+ is +1+, falls through to env-var
-      #   auto-detect (deprecated, emits a structured warning).
-      # - Otherwise raises {MissingArtifact}.
+      # When +woods.json+ is absent and the host has no provider configured,
+      # auto-detect runs by default: pattern/structural tools always work, and
+      # semantic search wires up only if +OPENAI_API_KEY+ or a reachable Ollama
+      # is found. Set +WOODS_REQUIRE_INDEX=1+ to fail closed and raise
+      # {MissingArtifact} instead.
       #
       # @param config [Woods::Configuration] the live host configuration object.
       #   May be mutated in the auto-detect path.
@@ -61,7 +65,7 @@ module Woods
       #   where +source+ is one of +:snapshot+, +:host_config+, +:autodetect+,
       #   or +:none+. The config is the same object passed in, possibly mutated.
       # @raise [Woods::MCP::MissingArtifact] when +woods.json+ is absent, the
-      #   host has no provider configured, and +WOODS_ALLOW_AUTODETECT+ is unset.
+      #   host has no provider configured, and +WOODS_REQUIRE_INDEX=1+ is set.
       # @raise [Woods::MCP::UnsupportedArtifact] when +woods.json+ has an
       #   unsupported +schema_version+.
       # @raise [Woods::MCP::DimensionMismatch] when stored and live provider
@@ -201,36 +205,53 @@ module Woods
 
       # Handle the no-artifact, no-host-provider case.
       #
-      # Raises {MissingArtifact} unless +WOODS_ALLOW_AUTODETECT=1+ opts in to
-      # the deprecated env-var auto-detect path.
+      # Extract-only hosts — those that ran +woods:extract+ but never
+      # +woods:embed+ and configured no embedding provider — boot in
+      # pattern/structural mode by default. The env-var auto-detect path runs,
+      # wiring semantic search only if +OPENAI_API_KEY+ or a reachable Ollama
+      # instance is found. With neither, +config+ comes back with a nil provider
+      # and {Bootstrapper.build_retriever} returns a nil retriever, leaving the
+      # always-on pattern/regex/structural tools fully functional.
+      #
+      # Set +WOODS_REQUIRE_INDEX=1+ to fail closed instead: demand a real
+      # +woods.json+ and raise {MissingArtifact} when it is absent.
+      # +WOODS_ALLOW_AUTODETECT+ is retained for backward compatibility but no
+      # longer changes behaviour — auto-detect is now the default.
       #
       # @param config [Woods::Configuration]
       # @param artifact [Woods::IndexArtifact, nil]
       # @param env [Hash]
       # @param ollama_probe [#call, nil]
-      # @return [Woods::Configuration]
-      # @raise [Woods::MCP::MissingArtifact]
+      # @return [Array(Woods::Configuration, Symbol)]
+      # @raise [Woods::MCP::MissingArtifact] only when +WOODS_REQUIRE_INDEX=1+.
       def self.resolve_without_artifact(config, artifact:, env:, ollama_probe:)
-        if env['WOODS_ALLOW_AUTODETECT'] != '1'
+        if env['WOODS_REQUIRE_INDEX'] == '1'
           raise MissingArtifact.new(
-            'No woods.json found and WOODS_ALLOW_AUTODETECT is unset. ' \
-            'Run `bundle exec rake woods:extract` in your host app, or set ' \
-            'WOODS_ALLOW_AUTODETECT=1 to probe env vars (deprecated).',
+            'No woods.json found and WOODS_REQUIRE_INDEX=1 demands a real index. ' \
+            'Run `bundle exec rake woods:extract` (then `woods:embed` for semantic ' \
+            'search) in your host app, or unset WOODS_REQUIRE_INDEX to boot in ' \
+            'pattern-only mode.',
             details: { output_dir: artifact&.output_dir&.to_s }
           )
         end
 
-        warn '[woods-mcp] deprecated_autodetect: falling back to env-var auto-detect (no woods.json found)'
-        [autodetect_from_env(config, env: env, ollama_probe: ollama_probe), :autodetect]
+        resolved = autodetect_from_env(config, env: env, ollama_probe: ollama_probe)
+        unless resolved.embedding_provider
+          warn '[woods-mcp] no woods.json and no embedding provider — serving ' \
+               'pattern/structural tools only. Run `rake woods:embed`, or set ' \
+               'OPENAI_API_KEY / run Ollama, to enable semantic search.'
+        end
+        [resolved, :autodetect]
       end
       private_class_method :resolve_without_artifact
 
       # Probe environment variables for provider credentials and configure
       # +config+ accordingly.
       #
-      # Only reachable when +WOODS_ALLOW_AUTODETECT=1+ and no +woods.json+
-      # is present. Mutates +config+ to set provider and stores when a
-      # credential or reachable Ollama instance is found.
+      # Reached by default when no +woods.json+ is present and the host
+      # configured no provider (unless +WOODS_REQUIRE_INDEX=1+). Mutates
+      # +config+ to set provider and stores when a credential or reachable
+      # Ollama instance is found; leaves the provider nil otherwise.
       #
       # @param config [Woods::Configuration]
       # @param env [Hash]

data/lib/woods/mcp/errors.rb

@@ -72,9 +72,11 @@ module Woods
     #   )
     class UnsupportedArtifact < BootstrapError; end
 
-    # Raised when +woods.json+ is absent from +output_dir+ and the env flag
-    # +WOODS_ALLOW_AUTODETECT+ is not set. Hosts that have never run an embed
-    # see a clear failure message rather than silent degradation.
+    # Raised when +woods.json+ is absent from +output_dir+ and the operator has
+    # opted into strict mode with +WOODS_REQUIRE_INDEX=1+. By default an absent
+    # artifact is *not* an error — the server boots in pattern/structural-only
+    # mode (see {ConfigResolver.resolve_without_artifact}). Strict mode exists
+    # for deployments that want to fail closed when an index is missing.
     #
     # @example
     #   raise Woods::MCP::MissingArtifact.new(

data/lib/woods/temporal/json_snapshot_store.rb

@@ -29,7 +29,10 @@ module Woods
 
       def capture(manifest, unit_hashes)
         git_sha = mget(manifest, 'git_sha')
-        return nil unless git_sha
+        # Snapshots are keyed by commit SHA — skip a missing or non-SHA value
+        # (e.g. the "unknown" provenance sentinel, #137) rather than letting it
+        # reach snapshot_path, which raises ArgumentError on a non-hex SHA.
+        return nil unless git_sha.is_a?(String) && git_sha.match?(/\A[0-9a-f]+\z/i)
 
         previous = find_latest
         snapshot = build_snapshot(manifest, git_sha, unit_hashes)

data/lib/woods/temporal/snapshot_store.rb

@@ -85,7 +85,10 @@ module Woods
       # @return [Hash] Snapshot record with diff stats
       def capture(manifest, unit_hashes)
         git_sha = mget(manifest, 'git_sha')
-        return nil unless git_sha
+        # Snapshots are keyed by commit SHA — skip a missing or non-SHA value
+        # (e.g. the "unknown" provenance sentinel, #137) so it can't key or
+        # collide a snapshot row. Mirrors JsonSnapshotStore's path validation.
+        return nil unless git_sha.is_a?(String) && git_sha.match?(/\A[0-9a-f]+\z/i)
 
         previous = find_latest
         upsert_snapshot(manifest, git_sha, unit_hashes.size)

data/lib/woods/unblocked/exporter.rb

@@ -2,6 +2,7 @@
 
 require 'set'
 require 'digest'
+require 'uri'
 require 'woods'
 require_relative 'client'
 require_relative 'rate_limiter'
@@ -83,6 +84,9 @@ module Woods
         # sync_type_partial methods work standalone (track_uri needs them).
         @current_uris = Set.new
         @budget_exhausted = false
+        # base URI => identifier that keeps the bare URI (only populated for
+        # URIs shared by >1 unit). Rebuilt per sync_all run.
+        @uri_primary = {}
       end
 
       # Sync all configured unit types to the Unblocked collection.
@@ -91,6 +95,7 @@ module Woods
       def sync_all
         @current_uris = Set.new
         @budget_exhausted = false
+        build_uri_index
         reconcile_from_remote if @manifest.empty?
 
         synced = 0
@@ -232,6 +237,11 @@ module Woods
         # ping-pong the manifest hash forever. Skip them.
         return :skipped unless unit_data['file_path']
 
+        # When several units share one file they share one base URI; only one
+        # keeps it, the rest get a `?unit=` suffix so each is a distinct remote
+        # document (and a distinct manifest key).
+        uri = effective_uri(unit_data)
+
         doc = @builder.build(unit_data)
         # An empty body means the credential scrub failed closed (the builders
         # always emit at least a header). Upserting it would overwrite a good
@@ -241,16 +251,16 @@ module Woods
         end
 
         hash = fingerprint(doc)
-        return :skipped if !@force_full && @manifest.unchanged?(doc[:uri], hash)
+        return :skipped if !@force_full && @manifest.unchanged?(uri, hash)
 
         response = @client.put_document(
           collection_id: @collection_id,
           title: doc[:title],
           body: doc[:body],
-          uri: doc[:uri]
+          uri: uri
         )
-        document_id = (response['id'] if response.is_a?(Hash)) || @manifest.document_id_for(doc[:uri])
-        @manifest.record(uri: doc[:uri], hash: hash, document_id: document_id)
+        document_id = (response['id'] if response.is_a?(Hash)) || @manifest.document_id_for(uri)
+        @manifest.record(uri: uri, hash: hash, document_id: document_id)
         :synced
       end
 
@@ -360,7 +370,47 @@ module Woods
         # stale repo-root document from before this guard should purge.
         return unless unit_data['file_path']
 
-        @current_uris << @builder.uri_for(unit_data)
+        # Must match the URI push_document actually uses, or a colliding unit's
+        # disambiguated document would look stale and be purged.
+        @current_uris << effective_uri(unit_data)
+      end
+
+      # The URI a unit's document is stored under. Normally the file's blob URL;
+      # when several units share that file, all but the lexically-first
+      # identifier get a `?unit=` suffix so each keeps a distinct document
+      # rather than overwriting the others (see #build_uri_index).
+      def effective_uri(unit_data)
+        base = @builder.uri_for(unit_data)
+        primary = @uri_primary[base]
+        return base if primary.nil? || primary == unit_data['identifier']
+
+        "#{base}?unit=#{URI.encode_www_form_component(unit_data['identifier'])}"
+      end
+
+      # One cheap pass over the type indexes (entries already carry file_path,
+      # and read_index is cached) to find files that define more than one synced
+      # unit. For each such base URI, the lexically-smallest identifier — the
+      # outer/top-level class — keeps the bare URI; siblings are suffixed. Solo
+      # files (the overwhelming majority) are absent from the map and unchanged,
+      # so this introduces no churn for them.
+      def build_uri_index
+        groups = Hash.new { |h, k| h[k] = [] }
+        synced_types.each do |type|
+          @reader.list_units(type: type).each do |entry|
+            next unless entry['file_path']
+
+            groups[@builder.uri_for(entry)] << entry['identifier']
+          end
+        end
+
+        @uri_primary = groups.each_with_object({}) do |(uri, identifiers), primary|
+          unique = identifiers.uniq
+          primary[uri] = unique.min if unique.size > 1
+        end
+      end
+
+      def synced_types
+        FULL_SYNC_TYPES + PARTIAL_SYNC_TYPES.map(&:first)
       end
 
       def fingerprint(doc)

data/lib/woods/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Woods
-  VERSION = '1.4.0'
+  VERSION = '1.5.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: woods
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Leah Armstrong
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-10 00:00:00.000000000 Z
+date: 2026-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mcp
@@ -64,14 +64,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '6.0'
 description: |
   Woods extracts structured data from Rails applications for use in
   AI-assisted development tooling. It provides version-specific context by
@@ -233,6 +233,7 @@ files:
 - lib/woods/formatting/generic_adapter.rb
 - lib/woods/formatting/gpt_adapter.rb
 - lib/woods/formatting/human_adapter.rb
+- lib/woods/git_provenance.rb
 - lib/woods/graph_analyzer.rb
 - lib/woods/index_artifact.rb
 - lib/woods/mcp/bearer_auth.rb