specguard-ruby 0.3.29 → 0.3.31

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 887fc6d71732b1947cc48c34f27c68ac5b9b71c729f604cf95c41e508cc8d6af
-  data.tar.gz: e2f20dbc68a7324cc34381e204bc8ac0f5db262002d86ffc3bd24c8c2cfb3663
+  metadata.gz: 14818808e8ef3b696b1b3834ea590734fa398f5fabbef1c5646d03699e844d99
+  data.tar.gz: ccce2e2cf09f6b3401284c0f7f3f343185c86fa2d48bc43ca7bbd9e48575910e
 SHA512:
-  metadata.gz: e3d18c2b2d19c8d25b0c5a9277847767996ff27be06f7f5802b052c7a4dab7f20e7244214a339fc0a4bc0343103572ad842bd381f95ccd6efa670422da445edc
-  data.tar.gz: 9a2b14e04e71e6e957134e29ad38f11fdaad0aede17893907a048d9e6414d93affb7844f4a99e630194f5095c0bc945e271800871f39f71f325ed8b4805492ae
+  metadata.gz: a7612a5d841ecf6d7b1f675bfe362a5141948c1e227a89d7d90e449c9f3b802b650894e7cd3862bb37a897dcbc77ae6e0d627caa1b3cbde3275b54ebd41beb54
+  data.tar.gz: d78f0bea385d4a9ca63d1581648350c76662f7540b0c105dda6a0ebb15c7b3be1be98e7d2ca8f29b5536fac597a4ed155cb5b96f8ff8575e79bfde7292ff0034

data/README.md

@@ -44,13 +44,26 @@ be assumed, require it explicitly before the run:
 bundle exec ruby -rminitest/specguard_plugin -e 'Minitest.extensions << "specguard"; load ARGV[0]' test/your_suite.rb
 ```
 
+Configure it from Ruby, if the environment is not the right place, through the framework-neutral
+`SpecGuard.configure` — in a `test_helper.rb`, before the run starts:
+
+```ruby
+SpecGuard.configure do |config|
+  config.branch = "release/2.0"
+end
+```
+
+`SpecGuard::RSpec.configure` is the same call under its RSpec-era spelling: both return the one
+configuration object the reporter and the formatter read, so either works from either framework.
+See [Shipping the run to SpecGuard](#shipping-the-run-to-specguard) for the settings.
+
 ## The linter — `specguard-lint`
 
 Validates `# @intent:` annotations in changed (or all) `*_spec.rb` files against the OpenTestIntent
 JSON Schema. Exits `1` on a malformed annotation — or a well-formed but unreachable one (stacked
 above another comment-form `@intent:` line, so the one-line lookback never claims it; separated
-from its `it` by one blank or ordinary comment line, which puts it out of the lookback's reach;
-directly above an `it` that carries its own trailing `@intent:`, which extraction prefers, so the
+from its example (`it`, `specify`, `xit`, `fit`, `example`, …) by one blank or ordinary comment line, which puts it out of the lookback's reach;
+directly above an example that carries its own trailing `@intent:`, which extraction prefers, so the
 comment is shadowed; or trailing on a `describe`/`context` group line, which no example's extraction can ever reach) — and
 **never** fails on a *missing* one (adoption is opt-in and gradual).
 
@@ -337,8 +350,8 @@ Every way the backend can fail — the binary is missing, will not execute, exit
 is not a verdict, or emits output that is not a report — is **exit 2**, the linter's "could not do
 my job" code. It never becomes exit 1, which means "an annotation is malformed" — or well-formed
 but unreachable: stacked above another comment-form `@intent:` line, so the one-line lookback
-never claims it, separated from its `it` by one blank or ordinary comment line, shadowed by its
-`it`'s own trailing `@intent:`, or trailing on a `describe`/`context` group line, which no example's extraction can ever reach — and nothing else.
+never claims it, separated from its example by one blank or ordinary comment line, shadowed by its
+example's own trailing `@intent:`, or trailing on a `describe`/`context` group line, which no example's extraction can ever reach — and nothing else.
 
 ## The formatter — `SpecGuard::RSpecFormatter`
 
@@ -441,8 +454,9 @@ the one on the next line.
 # SPECGUARD_SHARD_ID / SPECGUARD_OUTPUT_PATH / SPECGUARD_LOCAL_OUTPUT_PATH
 # override any of it.
 #
-# Assign a value here only when it is one neither source can know:
-SpecGuard::RSpec.configure do |config|
+# Assign a value here only when it is one neither source can know
+# (`SpecGuard::RSpec.configure` is the same call, under its RSpec-era name):
+SpecGuard.configure do |config|
   config.branch = "release/2.0"
 end
 ```
@@ -460,9 +474,18 @@ export SPECGUARD_API_KEY=…          # from your repository's settings
 export SPECGUARD_TIMEOUT=10         # optional; seconds, applied to connect and read
 ```
 
+**Using an `sga_` agent key? Also set `SPECGUARD_REPOSITORY_ID`.** An agent key
+covers a set of repositories, so the key cannot say which one a run belongs to;
+the request has to. With `SPECGUARD_REPOSITORY_ID=42` the run is POSTed to
+`<endpoint>/api/v1/repositories/42/ingest` instead of `<endpoint>/api/v1/ingest`
+(`config.repository_id` in Ruby). Under a repository `sgk_` key leave it unset —
+if you do set it, the server ignores it. The id may contain only letters, digits,
+`-` and `_`; anything else is refused before a request is made. A `404` with an
+id configured means no repository with that id is available to the key.
+
 ```ruby
 # ...or in Ruby, if you would rather not use the environment
-SpecGuard::RSpec.configure do |config|
+SpecGuard.configure do |config|
   config.endpoint = "https://specguard.example.com"
   config.api_key  = ENV["SPECGUARD_API_KEY"]
   config.timeout  = 10
@@ -474,7 +497,7 @@ is written to `log/test_results.local.jsonl` — the local development record,
 kept apart from the replay queue — so local development needs no opt-out, and a
 fork with no secret configured behaves like a laptop rather than like a broken
 build. The local file's name is configurable via `SPECGUARD_LOCAL_OUTPUT_PATH`
-(or `SpecGuard::RSpec.configure { |c| c.local_output_path = ... }`). The write
+(or `SpecGuard.configure { |c| c.local_output_path = ... }`). The write
 itself is silent when it succeeds — the ordinary case on any machine that can
 create `log/` — and it usually does.
 
@@ -501,6 +524,7 @@ offered to the endpoint and not accepted — so the run can be replayed later wi
 ```
 SpecGuard: could not deliver test telemetry (HTTP 401 — the API key was not
 accepted). Falling back to log/test_results.jsonl; the test run is unaffected.
+Once the delivery is fixed, replay this run with: bundle exec specguard-ingest log/test_results.jsonl
 ```
 
 **That line carries the endpoint's own words when it has any.** A `400` refusal
@@ -513,7 +537,8 @@ SpecGuard: could not deliver test telemetry (HTTP 400 — the endpoint rejected
 the payload — spec 3 (spec/orders_spec.rb:9): line_number is required and must
 be a positive integer; spec 7 (spec/orders_spec.rb:31): outcome must be one of
 passed, failed, pending). Falling back to log/test_results.jsonl; the test run
-is unaffected.
+is unaffected. Once the delivery is fixed, replay this run with: bundle exec
+specguard-ingest log/test_results.jsonl
 ```
 
 It stays **one** line whatever comes back. A systemic problem can have the
@@ -614,8 +639,9 @@ specguard-ingest: lines 1, 2 carried ci_run_id 17442 and each came back with
 test_run_id 41f2c9b8 — the endpoint folded them onto one run
 ```
 
-It reads the same `SPECGUARD_ENDPOINT`, `SPECGUARD_API_KEY` and
-`SPECGUARD_TIMEOUT` the formatter does, and sends each line through the same
+It reads the same `SPECGUARD_ENDPOINT`, `SPECGUARD_API_KEY`, `SPECGUARD_REPOSITORY_ID`
+(for `sga_` agent keys — a replay queue written under one is re-delivered to the same
+repository-scoped route) and `SPECGUARD_TIMEOUT` the formatter does, and sends each line through the same
 transport — so a run that was refused for a rotated key appears on the platform
 once the secret is fixed, with the shard folding described in
 [If you shard your suite](#if-you-shard-your-suite) applying exactly as it would
@@ -1198,9 +1224,11 @@ export SPECGUARD_ENDPOINT=https://specguard.internal.example.com
   nothing any other formatter wrote, is read or forwarded.
 - **No environment.** SpecGuard's own code reads a fixed list of variables and
   no others: the ones named in the envelope table above, which fill
-  `commit_sha`, `branch`, `ci_run_id` and `shard_id`; plus four that configure
+  `commit_sha`, `branch`, `ci_run_id` and `shard_id`; plus five that configure
   the gem itself rather than describing your suite — `SPECGUARD_ENDPOINT` (where
-  to send the run), `SPECGUARD_OUTPUT_PATH` (where to write the replay queue —
+  to send the run), `SPECGUARD_REPOSITORY_ID` (which repository an `sga_` agent
+  key's run belongs to — sent as a path segment of the request URL, nothing else),
+  `SPECGUARD_OUTPUT_PATH` (where to write the replay queue —
   runs the endpoint refused or could not be reached for), `SPECGUARD_LOCAL_OUTPUT_PATH`
   (where to write the local development record when there is no key),
   `SPECGUARD_TIMEOUT` (how long to wait), and

data/bin/specguard-ingest

@@ -9,13 +9,13 @@
 # the suite already finished, instead of re-running the suite.
 #
 # Exit codes are the contract, and they are `specguard-lint`'s reasoning
-# transferred (see SpecGuard::RSpec::IngestCLI):
+# transferred (see SpecGuard::Client::IngestCLI):
 #
 #   0  every line was accepted
 #   1  at least one line was refused by the endpoint
 #   2  this tool could not do its job — misuse, or the tool itself broken
 #
-# SpecGuard::RSpec::IngestCLI#run is written to *return* one of those three and
+# SpecGuard::Client::IngestCLI#run is written to *return* one of those three and
 # never to raise. The `require`s below are the one thing outside its reach, so
 # they get the same treatment here: a gem that cannot even load is the tool
 # being broken, which is a 2. Left bare, Ruby would exit 1 and report that the
@@ -23,18 +23,18 @@
 
 # Allow running from a source checkout without bundler by putting the local
 # lib/ on the load path. When the gem is installed (or run under
-# `bundle exec`), specguard/rspec resolves through the normal load path.
+# `bundle exec`), specguard/client resolves through the normal load path.
 source_lib = File.expand_path("../lib", __dir__)
 $LOAD_PATH.unshift(source_lib) unless $LOAD_PATH.include?(source_lib)
 
 begin
-  require "specguard/rspec"
+  require "specguard/client"
   # By its own path, deliberately. `net/http`, `uri` and `zlib` are not on the
   # linter's load chain and this command is the reason to pay for them.
-  require "specguard/rspec/ingest_cli"
+  require "specguard/client/ingest_cli"
 rescue ScriptError, StandardError => e
   warn "specguard-ingest: error: could not load specguard-ruby: #{e.class}: #{e.message}"
   exit 2
 end
 
-exit SpecGuard::RSpec::IngestCLI.new.run(ARGV)
+exit SpecGuard::Client::IngestCLI.new.run(ARGV)

data/bin/specguard-lint

@@ -11,7 +11,7 @@
 #   1  one or more annotations are malformed
 #   2  the linter could not do its job — misuse, or the tool itself broken
 #
-# SpecGuard::RSpec::CLI#run is written to *return* one of those three and never
+# SpecGuard::Client::CLI#run is written to *return* one of those three and never
 # to raise; see its class comment for why that takes deliberate effort in Ruby.
 # The `require` below is the one thing outside its reach, so it gets the same
 # treatment here: a gem that cannot even load is the linter being broken, which
@@ -20,15 +20,15 @@
 
 # Allow running from a source checkout without bundler by putting the local
 # lib/ on the load path. When the gem is installed (or run under
-# `bundle exec`), specguard/rspec resolves through the normal load path.
+# `bundle exec`), specguard/client resolves through the normal load path.
 source_lib = File.expand_path("../lib", __dir__)
 $LOAD_PATH.unshift(source_lib) unless $LOAD_PATH.include?(source_lib)
 
 begin
-  require "specguard/rspec"
+  require "specguard/client"
 rescue ScriptError, StandardError => e
   warn "specguard-lint: error: could not load specguard-ruby: #{e.class}: #{e.message}"
   exit 2
 end
 
-exit SpecGuard::RSpec::CLI.new.run(ARGV)
+exit SpecGuard::Client::CLI.new.run(ARGV)

data/lib/specguard/{rspec → client}/annotation_lookup.rb

@@ -4,7 +4,7 @@
 # with what?*
 #
 # It is the formatter's half of the annotation story. The linter's half already
-# exists and is not duplicated here — {SpecGuard::RSpec::Scanner} finds every
+# exists and is not duplicated here — {SpecGuard::Client::Scanner} finds every
 # `@intent:` in a file, captures its payload string-aware and parses it, and
 # the `validate-intent` binary decides whether the result is valid. This class
 # consumes both. Writing a second extractor would guarantee that the tool
@@ -12,14 +12,14 @@
 # platform eventually disagree about what an annotation *is*.
 #
 # Requiring the linter's chain from here is safe in the direction that matters:
-# `lib/specguard/rspec.rb` does not require `rspec/core`, so pulling it in from
+# `lib/specguard/client.rb` does not require `rspec/core`, so pulling it in from
 # the formatter's side keeps `bin/specguard-lint` loadable on a machine with no
 # RSpec installed. spec/specguard/rspec/formatter_loading_spec.rb pins that in
 # both directions.
-require_relative "../rspec"
+require_relative "../client"
 
 module SpecGuard
-  module RSpec
+  module Client
     # == The lookback rule (SPGD-12 §2)
     #
     # `example.metadata[:line_number]` is the line the `it` is on. An annotation

data/lib/specguard/{rspec → client}/annotation_scanner.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module SpecGuard
-  module RSpec
+  module Client
     # Finds `@intent:` annotations in test source and captures the object
     # literal that follows each one.
     #

data/lib/specguard/{rspec → client}/cli.rb

@@ -3,7 +3,7 @@
 require "optparse"
 
 module SpecGuard
-  module RSpec
+  module Client
     # `specguard-lint`'s command line, and the whole of the exit contract.
     #
     # == The contract, and the reason it needs defending
@@ -358,7 +358,7 @@ module SpecGuard
       end
 
       # The fence arm of the `:all` empty reason: every matching file the walk
-      # found was inside a {SpecGuard::RSpec::FileSelector::SKIPPED_DIRECTORIES}
+      # found was inside a {SpecGuard::Client::FileSelector::SKIPPED_DIRECTORIES}
       # directory, so the silence is the fence's, not the tree's.
       def all_fenced_reason(selection)
         n = selection.skipped

data/lib/specguard/{rspec → client}/configuration.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module SpecGuard
-  module RSpec
+  module Client
     # Where the checkout is sitting — which commit, and which branch — asked of
     # git directly.
     #
@@ -120,7 +120,7 @@ module SpecGuard
     # The escape hatch stays open on top of all of it, for a value neither
     # source can know:
     #
-    #   SpecGuard::RSpec.configure do |config|
+    #   SpecGuard.configure do |config|
     #     config.branch = "release/2.0"
     #   end
     #
@@ -318,6 +318,7 @@ module SpecGuard
       LOCAL_OUTPUT_PATH_KEYS = %w[SPECGUARD_LOCAL_OUTPUT_PATH].freeze
       ENDPOINT_KEYS = %w[SPECGUARD_ENDPOINT].freeze
       API_KEY_KEYS = %w[SPECGUARD_API_KEY].freeze
+      REPOSITORY_ID_KEYS = %w[SPECGUARD_REPOSITORY_ID].freeze
       TIMEOUT_KEYS = %w[SPECGUARD_TIMEOUT].freeze
 
       # The commit the suite ran against. `nil` when nothing said.
@@ -344,7 +345,9 @@ module SpecGuard
       attr_accessor :local_output_path
       # The SpecGuard installation to POST to, scheme and host only:
       # `https://specguard.example.com`. The `/api/v1/ingest` path is the
-      # platform's contract, not a setting. `nil` when nothing said.
+      # platform's contract, not a setting — with one exception: when
+      # {#repository_id} is set the path is `/api/v1/repositories/<id>/ingest`
+      # instead. `nil` when nothing said.
       attr_accessor :endpoint
       # The repository's SpecGuard API key. Present means "deliver over HTTP".
       #
@@ -354,6 +357,16 @@ module SpecGuard
       # nobody can retroactively fix. Send whatever is configured and let a 401
       # be the answer.
       attr_accessor :api_key
+      # The repository the run belongs to, sent as a path segment
+      # (`/api/v1/repositories/<id>/ingest`). Needed by an `sga_` agent key,
+      # which covers a set of repositories and so cannot name the run's
+      # repository itself; under an `sgk_` key the platform ignores it. `nil`
+      # when unset or blank, which keeps the plain `/api/v1/ingest` path.
+      #
+      # Deliberately **not** format-checked against the key prefix or a numeric
+      # shape (same reasoning as {#api_key}): the platform's 400/403/404 is the
+      # answer. {Transport} only refuses ids that are unsafe as a path segment.
+      attr_accessor :repository_id
       # Seconds, applied to opening the connection and to reading the response.
       attr_accessor :timeout
 
@@ -374,6 +387,7 @@ module SpecGuard
         @local_output_path = first_present(env, LOCAL_OUTPUT_PATH_KEYS) || DEFAULT_LOCAL_OUTPUT_PATH
         @endpoint = first_present(env, ENDPOINT_KEYS)
         @api_key = first_present(env, API_KEY_KEYS)
+        @repository_id = first_present(env, REPOSITORY_ID_KEYS)
         @timeout = seconds(first_present(env, TIMEOUT_KEYS)) || DEFAULT_TIMEOUT_SECONDS
       end
 
@@ -433,40 +447,5 @@ module SpecGuard
         parsed
       end
     end
-
-    class << self
-      # The process-wide formatter configuration.
-      #
-      # Built on first use rather than at load time so that a `configure` block
-      # in a `spec_helper.rb` and a variable exported by a CI job describe the
-      # same object regardless of which the interpreter reached first.
-      #
-      # @return [Configuration]
-      def configuration
-        @configuration ||= Configuration.new
-      end
-
-      # Configure the formatter.
-      #
-      #   SpecGuard::RSpec.configure do |config|
-      #     config.branch = "release/2.0"
-      #   end
-      #
-      # @yieldparam configuration [Configuration]
-      # @return [Configuration] the configuration, block or no block
-      def configure
-        yield configuration if block_given?
-        configuration
-      end
-
-      # Drop the memoized configuration so the next read re-seeds from ENV.
-      # Exists for tests, and for the rare caller that changes the environment
-      # after this file was loaded.
-      #
-      # @return [void]
-      def reset_configuration!
-        @configuration = nil
-      end
-    end
   end
 end

data/lib/specguard/{rspec → client}/file_selector.rb

@@ -3,7 +3,7 @@
 require "open3"
 
 module SpecGuard
-  module RSpec
+  module Client
     # Chooses which spec files the linter reads.
     #
     # Two modes: every Ruby test file under the working directory (the

data/lib/specguard/{rspec → client}/finding.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module SpecGuard
-  module RSpec
+  module Client
     # One `@intent:` annotation, located and (where possible) parsed.
     #
     # Exactly one of `intent` and `problem` is non-nil:
@@ -25,7 +25,7 @@ module SpecGuard
     #
     # NOTE: this is a subclass of an anonymous `Data.define` rather than a
     # `Data.define do ... end` block, because a constant assigned inside that
-    # block binds to the *lexically* enclosing module (SpecGuard::RSpec) rather
+    # block binds to the *lexically* enclosing module (SpecGuard::Client) rather
     # than to the value class — so KIND_EXTRACTION below would silently not be
     # `Finding::KIND_EXTRACTION`.
     class Finding < Data.define(:file, :line, :intent, :problem, :kind)

data/lib/specguard/{rspec → client}/ingest_cli.rb

@@ -3,21 +3,21 @@
 require "json"
 require "optparse"
 
-require_relative "../rspec"
+require_relative "../client"
 require_relative "ingest_reporter"
 require_relative "transport"
 
 # `specguard-ingest`'s command line — the other end of `log/test_results.jsonl`.
 #
-# == Why this file is not on `require "specguard/rspec"`'s chain
+# == Why this file is not on `require "specguard/client"`'s chain
 #
 # `specguard-lint` runs on machines that never make a network call, and putting
 # this file on the umbrella's chain would put `net/http`, `uri` and `zlib` on
 # the linter's load path to serve a command it never invokes. So it is loaded by
 # its own path, exactly as the formatter is and for the same reason —
-# `require "specguard/rspec/ingest_cli"`, which `bin/specguard-ingest` does.
+# `require "specguard/client/ingest_cli"`, which `bin/specguard-ingest` does.
 module SpecGuard
-  module RSpec
+  module Client
     # Replays a saved run: reads a `log/test_results.jsonl` back and re-delivers
     # each line through the {Transport} this gem already ships.
     #
@@ -740,7 +740,7 @@ module SpecGuard
         raise UsageError, "no API key is configured (set SPECGUARD_API_KEY)" if blank?(configuration.api_key)
 
         transport = Transport.new(endpoint: configuration.endpoint, api_key: configuration.api_key,
-                                  timeout: configuration.timeout)
+                                  timeout: configuration.timeout, repository_id: configuration.repository_id)
         # Asked once, here, so a malformed `SPECGUARD_ENDPOINT` is one exit 2
         # rather than N identical `:failed` lines. `Transport#deliver` would
         # otherwise swallow the same `ArgumentError` once per line and report a

data/lib/specguard/{rspec → client}/ingest_reporter.rb

@@ -3,7 +3,7 @@
 require "json"
 
 module SpecGuard
-  module RSpec
+  module Client
     # `specguard-ingest --json`: the machine-readable renderer over the same
     # per-line facts the human report is built from.
     #

data/lib/specguard/{rspec → client}/json_reporter.rb

@@ -3,7 +3,7 @@
 require "json"
 
 module SpecGuard
-  module RSpec
+  module Client
     # `specguard-lint --json`: the machine-readable renderer over the same
     # `Array<Linter::Result>` the text report is built from.
     #

data/lib/specguard/{rspec → client}/linter.rb

@@ -3,7 +3,7 @@
 require "json"
 
 module SpecGuard
-  module RSpec
+  module Client
     # The shared verdict shape both renderers and the exit code derive from.
     #
     # == Where this sits after SPGD-867 (the cutover)

data/lib/specguard/{rspec → client}/payload_normalizer.rb

@@ -3,7 +3,7 @@
 require "json"
 
 module SpecGuard
-  module RSpec
+  module Client
     # Relaxes PROTOCOL.md §1's permissive annotation syntax into strict JSON.
     #
     # §1 promises "the linter normalizes before validating" and lists three

data/lib/specguard/{rspec → client}/scanner.rb

@@ -3,7 +3,7 @@
 require "json"
 
 module SpecGuard
-  module RSpec
+  module Client
     # Runs the discovery pipeline over source files and returns {Finding}s.
     #
     # Pipeline, per `@intent:` token:
@@ -354,6 +354,18 @@ module SpecGuard
       # example on the NEXT line may claim ({AnnotationLookup::COMMENT_LINE}).
       COMMENT_INTENT_LINE = /\A\s*#.*@intent:/
 
+      # The one source of the example-call vocabulary, shared by
+      # {EXAMPLE_LINE} and {EXAMPLE_ON_LINE}. `it`/`specify` are matched on
+      # `\b` alone; the other eight keywords also carry a `(?![:.])`
+      # lookahead, which is load-bearing: `example.run` (the around-hook
+      # idiom), `example.metadata[:x]` and `focus: true` are not example
+      # definitions and must never anchor. (`\b` already excludes `fitness`
+      # and `example_group`, a GROUP_LINE keyword.) `skip` and `pending` are
+      # deliberately EXCLUDED: at line start they are the runtime call inside
+      # an example body, not an example definition.
+      EXAMPLE_CALL_SOURCE =
+        "(?:(?:it|specify)\\b|(?:example|focus|fexample|fit|fspecify|xexample|xit|xspecify)\\b(?![:.]))"
+
       # The line an annotation run may be claimed from: the first example
       # keyword. The lookback rule is `example.metadata[:line_number] - 1`, so
       # only the comment form on the line immediately above an example is
@@ -367,7 +379,14 @@ module SpecGuard
       # example: stacked lines above it (SPGD-897), the trailing form on
       # a group line directly above it (SPGD-1510), and a comment-form run
       # separated from it by one blank/comment line (SPGD-1554).
-      EXAMPLE_LINE = /\A\s*(?:it|specify)\b/
+      #
+      # The vocabulary is every example method RSpec core defines
+      # (`example focus fexample fit fspecify xexample xit xspecify`, besides
+      # `it`/`specify`): lookup is keyed by `example.metadata[:line_number]`, so
+      # an annotation stacked/separated/shadowed above `xit` is exactly as dead
+      # as one above `it`. Both this anchor and {EXAMPLE_ON_LINE} are built
+      # from {EXAMPLE_CALL_SOURCE}, so anchor and exemption cannot drift.
+      EXAMPLE_LINE = /\A\s*#{EXAMPLE_CALL_SOURCE}/
 
       # A blank (whitespace-only) line — one of the two interleaves the
       # separated pass reads. `\n` is whitespace, so a `text.lines` element
@@ -574,7 +593,7 @@ module SpecGuard
       # only ever a missed flag: prose can turn the exemption ON, never a
       # real example OFF. The one-line example's own payload is never
       # consulted, so a payload can never exempt anything.
-      EXAMPLE_ON_LINE = /(?:\bdo\b|\{|;)\s*(?:it|specify)\b/
+      EXAMPLE_ON_LINE = /(?:\bdo\b|\{|;)\s*#{EXAMPLE_CALL_SOURCE}/
 
       # @param text [String] source of one file
       # @param file [String] path to record on each Finding

data/lib/specguard/{rspec → client}/transport.rb

@@ -9,7 +9,7 @@ require_relative "configuration"
 require_relative "../version"
 
 module SpecGuard
-  module RSpec
+  module Client
     # The one HTTP call this gem makes: `POST <endpoint>/api/v1/ingest`,
     # carrying a whole run.
     #
@@ -127,6 +127,21 @@ module SpecGuard
       # Part of the platform's contract, so it is not configurable — the
       # `endpoint` setting is the installation's address and nothing more.
       PATH = "/api/v1/ingest"
+
+      # The repository-scoped form of the same endpoint (`post "ingest"` nested
+      # under `resources :repositories`). It exists because an `sga_` agent key
+      # covers a SET of repositories, so the credential cannot name the run's
+      # repository and the request has to, as a path segment. `%s` is only ever
+      # filled with an id that passed {REPOSITORY_ID_PATTERN}. Under an `sgk_`
+      # key the server ignores the segment, so {PATH} stays the default.
+      REPOSITORY_PATH = "/api/v1/repositories/%s/ingest"
+
+      # What a repository id may look like before it becomes a path segment.
+      # Deliberately not "digits": the platform's ids are numeric today and the
+      # gem must not bake that in. Dots are excluded outright, which is what
+      # refuses `..` (percent-escaping would not neutralise a dot segment), and
+      # `/`, `?`, `#` can never survive as path structure.
+      REPOSITORY_ID_PATTERN = /\A[0-9A-Za-z_-]+\z/
       CONTENT_TYPE = "application/json"
       USER_AGENT = "specguard-ruby/#{SpecGuard::VERSION}"
       CONTENT_ENCODING = "gzip"
@@ -167,7 +182,12 @@ module SpecGuard
       # same reason turned around: a 202 whose body will not parse is still an
       # acceptance, and relabelling it would tell the operator something untrue
       # about a run the platform has already stored. See {#test_run_id}.
-      Result = Struct.new(:outcome, :code, :error, :reasons, :body, keyword_init: true) do
+      #
+      # `repository_scoped` is true when the request went to the repository-
+      # scoped route. It only changes the 404 sentence: under that route a 404
+      # means no repository with that id is available to this key, not a wrong
+      # URL. Nil/false (every pre-existing `Result.new`) keeps today's wording.
+      Result = Struct.new(:outcome, :code, :error, :reasons, :body, :repository_scoped, keyword_init: true) do
         # The status codes worth spelling out, because each implies a different
         # thing for the reader to *do*. A 401 means "rotate or fix the key"; a
         # 400 means "the payload this gem built was refused", which is a bug
@@ -193,6 +213,10 @@ module SpecGuard
         # tells the reader how widespread it is.
         MAX_RENDERED_REASONS = 3
 
+        # The 404 sentence when a repository id was sent. See `repository_scoped`.
+        REPOSITORY_NOT_FOUND_ADVICE =
+          "no repository with that id is available to this API key — check SPECGUARD_REPOSITORY_ID"
+
         # Ceiling on the spelled-out reasons, before the `and N more` tail,
         # which is appended afterwards so the count can never be the thing that
         # gets truncated away.
@@ -224,13 +248,19 @@ module SpecGuard
         def reason
           case outcome
           when :success then nil
-          when :rejected then [+"HTTP #{code}", ADVICE[code], rendered_reasons].compact.join(" — ")
+          when :rejected then [+"HTTP #{code}", advice, rendered_reasons].compact.join(" — ")
           else "#{error.class}: #{error.message}"
           end
         end
 
         private
 
+        def advice
+          return REPOSITORY_NOT_FOUND_ADVICE if code == 404 && repository_scoped
+
+          ADVICE[code]
+        end
+
         # The refusal, bounded and flattened to fit on the one line. `nil` when
         # there is nothing readable to add, which is what keeps the bare
         # `HTTP 400 — the endpoint rejected the payload` intact for every body
@@ -270,9 +300,15 @@ module SpecGuard
       # @param timeout [Numeric, String, nil] seconds. Anything that is not a
       #   positive finite number falls back to the default rather than raising:
       #   a typo in `SPECGUARD_TIMEOUT` must not be able to fail a suite.
-      def initialize(endpoint:, api_key:, timeout: Configuration::DEFAULT_TIMEOUT_SECONDS)
+      # @param repository_id [String, Integer, nil] when present, POST to the
+      #   repository-scoped route an `sga_` agent key needs. nil/blank keeps the
+      #   `sgk_` path byte-identical. An id outside {REPOSITORY_ID_PATTERN} makes
+      #   {#uri} raise `ArgumentError`.
+      def initialize(endpoint:, api_key:, timeout: Configuration::DEFAULT_TIMEOUT_SECONDS, repository_id: nil)
         @endpoint = endpoint
         @api_key = api_key
+        @repository_id = repository_id.to_s.strip
+        @repository_id = nil if @repository_id.empty?
         @timeout = sanitize_timeout(timeout)
       end
 
@@ -301,7 +337,8 @@ module SpecGuard
         return Result.new(outcome: :success, code: code, body: success_body(response)) if
           response.is_a?(Net::HTTPSuccess)
 
-        Result.new(outcome: :rejected, code: code, reasons: refusal_reasons(response))
+        Result.new(outcome: :rejected, code: code, reasons: refusal_reasons(response),
+                   repository_scoped: !@repository_id.nil?)
       rescue ScriptError, StandardError => e
         # Connection refused, DNS failure, TLS failure, open/read timeout, a
         # malformed endpoint — one family, one shape. `ScriptError` is in the
@@ -427,7 +464,7 @@ module SpecGuard
         base = @endpoint.to_s.strip
         raise ArgumentError, "no endpoint is configured (set SPECGUARD_ENDPOINT)" if base.empty?
 
-        parsed = URI.parse(base.sub(%r{/+\z}, "") + PATH)
+        parsed = URI.parse(base.sub(%r{/+\z}, "") + ingest_path)
         # `URI::HTTPS < URI::HTTP`, so this admits both and rejects the
         # scheme-less `specguard.example.com` that `URI.parse` happily returns
         # as a `URI::Generic` with a nil host — which `Net::HTTP` would then
@@ -438,6 +475,17 @@ module SpecGuard
         parsed
       end
 
+      def ingest_path
+        return PATH if @repository_id.nil?
+
+        unless REPOSITORY_ID_PATTERN.match?(@repository_id)
+          raise ArgumentError,
+                "SPECGUARD_REPOSITORY_ID must contain only letters, digits, '-' and '_', got #{@repository_id.inspect}"
+        end
+
+        format(REPOSITORY_PATH, @repository_id)
+      end
+
       def sanitize_timeout(value)
         parsed = Float(value, exception: false)
         return Configuration::DEFAULT_TIMEOUT_SECONDS unless parsed&.finite? && parsed.positive?

data/lib/specguard/{rspec → client}/validator_backend.rb

@@ -7,7 +7,7 @@ require "net/http"
 require "open3"
 
 module SpecGuard
-  module RSpec
+  module Client
     # The Go validator backend: `validate-intent --source --json`, and since
     # SPGD-867 the ONLY validator `specguard-lint` has.
     #
@@ -36,7 +36,7 @@ module SpecGuard
     # consumers are `Formatter` and `Transport`, and `CLI` does not reference
     # it at all — so threading the lint backend through it would make the
     # linter depend on the telemetry object solely to read one env var. It also
-    # memoizes process-wide (`SpecGuard::RSpec.configuration`), with
+    # memoizes process-wide (`SpecGuard.configuration`), with
     # `reset_configuration!` existing only for tests, which is a poor fit for
     # something a spec wants to vary per example. {CLI} takes an `env:` instead
     # and asks this module, so the seam is one hash away in a test and one

data/lib/specguard/client.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "version"
+
+module SpecGuard
+  module Client
+    # The Ruby client for SpecGuard.
+    #
+    # The linter is complete end to end: it finds `@intent:` annotations in
+    # spec files, captures each payload string-aware, normalizes PROTOCOL.md
+    # §1's permissive syntax into strict JSON, validates the result against the
+    # vendored OpenTestIntent schema, and reports violations in the reference
+    # tool's own grammar under the 0/1/2 exit contract (see {CLI}).
+    #
+    # Everything under `SpecGuard::Client` is framework-free: the RSpec
+    # formatter and the Minitest reporter are the framework halves of the
+    # client and both build on it. Neither is required from here — `rspec`
+    # is a development dependency of this gem, not a runtime one, and
+    # `bin/specguard-lint` loads this file on machines that may have no RSpec
+    # at all. Requiring `rspec/core` from this chain would turn a missing test
+    # framework into a broken linter. Load the formatter by its own path when
+    # you want it — `require "specguard/rspec/formatter"` — and see that file
+    # for the opt-in wiring.
+    class Error < StandardError; end
+
+    # A source line could not be scanned (unterminated string or object
+    # literal). Internal to the scanner: it is caught and turned into a
+    # {Finding}'s `problem` rather than reaching a caller.
+    class ScanError < Error; end
+
+    # The tool was invoked in a way that cannot work — `--changed` outside a git
+    # repository, say. Distinct from "the annotations are bad": the exit-code
+    # contract makes this a 2, and it is typed here so the CLI can map it
+    # without re-deriving the distinction from an error message.
+    class UsageError < Error; end
+
+    # The Go validator backend could not produce a verdict — the binary named
+    # by `SPECGUARD_VALIDATE_INTENT`, or the default binary the backend
+    # resolves when that is blank, is missing, will not execute, exited with a
+    # code that is not a verdict, or emitted something this cannot read as a
+    # report.
+    #
+    # Typed separately from {UsageError} because the two are different
+    # accusations ("you invoked me wrongly" vs "the tool I was told to use is
+    # broken"), and rescued *beside* it in {CLI#run} because the answer to both
+    # is the same and non-negotiable: exit 2, never 1. See {ValidatorBackend}.
+    class ValidatorError < Error; end
+
+    # The vendored canonical OpenTestIntent schema, copied byte-for-byte from
+    # open-test-intent so this gem has **no cross-repo runtime dependency**.
+    # It ships packaged (it lives under `lib/`, which the gemspec includes);
+    # the spec fixtures deliberately do not, so nothing here may be
+    # load-bearing at runtime.
+    #
+    # Since the SPGD-867 cutover nothing VALIDATES against this copy — every
+    # verdict comes from the `validate-intent` binary's own compiled-in
+    # schema. It survives because {ValidatorBackend}'s schema-contract check
+    # digests it at runtime and refuses a binary that would enforce different
+    # bytes: the two halves of the seam must keep meeting somewhere, and this
+    # file is where the gem's half lives.
+    SCHEMA_PATH = File.expand_path("client/schemas/open-test-intent.v1.json", __dir__).freeze
+  end
+end
+
+module SpecGuard
+  class << self
+    # The process-wide client configuration — one object shared by the RSpec
+    # formatter, the Minitest reporter and the CLIs, whatever framework a
+    # consumer runs.
+    #
+    # Built on first use rather than at load time so that a `configure` block
+    # in a `spec_helper.rb` / `test_helper.rb` and a variable exported by a CI
+    # job describe the same object regardless of which the interpreter reached
+    # first.
+    #
+    # {SpecGuard::RSpec.configure} (the documented RSpec entry point) delegates
+    # here and returns this same object — there is exactly one configuration,
+    # not one per entry point.
+    #
+    # @return [Client::Configuration]
+    def configuration
+      # Loaded here, not at the top of this file: the linter's chain
+      # (`require "specguard/client"`) must stay free of the formatter's
+      # configuration/transport half — formatter_loading_spec pins it.
+      require_relative "client/configuration"
+      @configuration ||= Client::Configuration.new
+    end
+
+    # Configure the client.
+    #
+    #   SpecGuard.configure do |config|
+    #     config.branch = "release/2.0"
+    #   end
+    #
+    # @yieldparam configuration [Client::Configuration]
+    # @return [Client::Configuration] the configuration, block or no block
+    def configure
+      yield configuration if block_given?
+      configuration
+    end
+
+    # Drop the memoized configuration so the next read re-seeds from ENV.
+    # Exists for tests, and for the rare caller that changes the environment
+    # after this file was loaded.
+    #
+    # @return [void]
+    def reset_configuration!
+      @configuration = nil
+    end
+  end
+end
+
+require_relative "client/finding"
+require_relative "client/annotation_scanner"
+require_relative "client/payload_normalizer"
+require_relative "client/scanner"
+require_relative "client/file_selector"
+require_relative "client/linter"
+require_relative "client/json_reporter"
+require_relative "client/validator_backend"
+require_relative "client/cli"

data/lib/specguard/minitest/reporter.rb

@@ -4,11 +4,11 @@ require "json"
 require "fileutils"
 
 # Configuration and Transport are the framework-free halves of the client
-# (env resolution, wire delivery, the never-raise contract); both live under
-# the rspec namespace because rspec shipped first, neither contains any RSpec.
-# Required here rather than assumed because nothing else loads them on a
-# minitest-only consumer's machine.
-require_relative "../rspec/configuration"
+# (env resolution, wire delivery, the never-raise contract), under
+# `SpecGuard::Client`. Required here rather than assumed because nothing else
+# loads them on a minitest-only consumer's machine.
+require_relative "../client"
+require_relative "../client/configuration"
 
 # The annotation lookup is the third framework-free half: what counts as a
 # test's annotation is a property of the source line, not of the framework
@@ -17,20 +17,19 @@ require_relative "../rspec/configuration"
 # already warns that a second extractor guarantees scanner and reporter
 # eventually disagree about what an annotation is). Requiring it pulls the
 # linter's chain — the same direction-safe require the formatter itself makes;
-# `specguard/rspec` does not require `rspec/core`, so a minitest-only machine
+# `specguard/client` does not require `rspec/core`, so a minitest-only machine
 # stays loadable.
-require_relative "../rspec/annotation_lookup"
+require_relative "../client/annotation_lookup"
 
 # The Minitest half of `specguard-ruby`. Everything the RSpec formatter knows
 # about the platform — the envelope's field names, the transport's
 # never-raise contract, the switch that a missing key is — is framework-free
-# knowledge that already lives in `SpecGuard::RSpec::Configuration` and
-# `SpecGuard::RSpec::Transport` (both named for the framework that happened to
-# ship first, neither containing any RSpec). This adapter contributes only the
+# knowledge that already lives in `SpecGuard::Client::Configuration` and
+# `SpecGuard::Client::Transport`. This adapter contributes only the
 # part that is genuinely Minitest's: turning `Minitest::Result` objects into
 # the same row shape the RSpec formatter emits, at the moment Minitest hands
 # them to a reporter — and attaching each test's annotation the same way the
-# formatter does, through the shared {SpecGuard::RSpec::AnnotationLookup} and
+# formatter does, through the shared {SpecGuard::Client::AnnotationLookup} and
 # its one-line lookback (SPGD-12 §2), so a Minitest row carries the same
 # `status` / `intent` pair a RSpec row does.
 #
@@ -78,7 +77,7 @@ module SpecGuard
         end
       end
 
-      def initialize(configuration: SpecGuard::RSpec.configuration,
+      def initialize(configuration: SpecGuard.configuration,
                      transport: nil, output: $stderr,
                      annotations: nil,
                      clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
@@ -108,7 +107,7 @@ module SpecGuard
         # binds one root, hands it to the default lookup, and pins rspec-core's
         # lazily memoized relativization regex to the same moment.)
         root = self.class.repo_root
-        @annotations = annotations || SpecGuard::RSpec::AnnotationLookup.new(root: root)
+        @annotations = annotations || SpecGuard::Client::AnnotationLookup.new(root: root)
         @clock = clock
         @rows = []
         @started_at = nil
@@ -244,11 +243,12 @@ module SpecGuard
       end
 
       def transport_for
-        require_relative "../rspec/transport"
-        SpecGuard::RSpec::Transport.new(
+        require_relative "../client/transport"
+        SpecGuard::Client::Transport.new(
           endpoint: @configuration.endpoint,
           api_key: @configuration.api_key,
-          timeout: @configuration.timeout
+          timeout: @configuration.timeout,
+          repository_id: @configuration.repository_id
         )
       end
 
@@ -406,12 +406,21 @@ module SpecGuard
       # Report, not promise — see `#fall_back` for why that is the whole of
       # this slice, and why the order above it did not move.
       def sink_clause(path, error)
-        return "Falling back to the replay queue. The test run is unaffected." if error.nil?
+        return replay_clause(path) if error.nil?
 
         "The replay queue #{path} could not be written either " \
           "(#{error.class}: #{error.message}), so this run's telemetry was lost."
       end
 
+      # The success arm (SPGD-1139): names the configured path (the one
+      # `#append` just wrote) and the replay command, word-for-word the
+      # formatter's clause. The lost-run arm names no command — nothing to
+      # replay.
+      def replay_clause(path)
+        "Falling back to #{path}; the test run is unaffected. " \
+          "Once the delivery is fixed, replay this run with: bundle exec specguard-ingest #{path}"
+      end
+
       # Once per process, like the formatter's `warn_once`: fifty failing
       # deliveries is one problem, not fifty lines of it.
       def warn_once(message)

data/lib/specguard/rspec/formatter.rb

@@ -40,13 +40,19 @@ require "rspec/core/formatters/base_formatter"
 require "json"
 require "fileutils"
 
-require_relative "configuration"
-require_relative "transport"
+# `specguard/rspec` is what defines `SpecGuard::RSpec` — the namespace whose
+# existence is the shadowing hazard documented below, and the home of the
+# documented `SpecGuard::RSpec.configure` entry point. It is required here so
+# that both stay true however this file is reached, now that the client chain
+# no longer pulls it in.
+require_relative "../rspec"
+require_relative "../client/configuration"
+require_relative "../client/transport"
 # Brings the linter's discovery chain with it (Scanner, Finding, Schema). That
 # direction is safe — `specguard/rspec` does not require `rspec/core`, so the
 # linter stays loadable without RSpec; it is only the reverse that would break
 # packaging.
-require_relative "annotation_lookup"
+require_relative "../client/annotation_lookup"
 
 module SpecGuard
   # == A NOTE ON CONSTANT RESOLUTION — read this before editing
@@ -338,7 +344,7 @@ module SpecGuard
       root = self.class.repo_root
       ::RSpec::Core::Metadata.relative_path_regex
       @error_stream = error_stream
-      @annotations = annotations || SpecGuard::RSpec::AnnotationLookup.new(root: root)
+      @annotations = annotations || SpecGuard::Client::AnnotationLookup.new(root: root)
       @specs = []
       @warned = false
       # Stamped here rather than from a `start` hook on purpose. `:start` is not
@@ -1031,10 +1037,11 @@ module SpecGuard
     end
 
     def transport_for(configuration)
-      SpecGuard::RSpec::Transport.new(
+      SpecGuard::Client::Transport.new(
         endpoint: configuration.endpoint,
         api_key: configuration.api_key,
-        timeout: configuration.timeout
+        timeout: configuration.timeout,
+        repository_id: configuration.repository_id
       )
     end
 
@@ -1196,12 +1203,22 @@ module SpecGuard
     # which of the two things actually happened — see {#fall_back} for why that
     # is the whole of this slice, and why the order above it did not move.
     def sink_clause(path, error)
-      return "Falling back to #{path}; the test run is unaffected." if error.nil?
+      return replay_clause(path) if error.nil?
 
       "The replay queue #{path} could not be written either " \
         "(#{error.class}: #{error.message}), so this run's telemetry was lost."
     end
 
+    # The success arm (SPGD-1139): where the run sits AND the command that gets
+    # it back, fix-the-delivery first and replay after — the order the ingest
+    # CLI's own doctrine describes. The lost-run arm above deliberately names no
+    # command: with no queue written there is nothing to replay. Kept
+    # word-for-word identical to the Minitest reporter's clause.
+    def replay_clause(path)
+      "Falling back to #{path}; the test run is unaffected. " \
+        "Once the delivery is fixed, replay this run with: bundle exec specguard-ingest #{path}"
+    end
+
     def emit_warning(line)
       return if @warned
 

data/lib/specguard/rspec.rb

@@ -1,72 +1,41 @@
 # frozen_string_literal: true
 
 require_relative "rspec/version"
+require_relative "client"
 
 module SpecGuard
+  # The RSpec-facing entry point of the gem.
+  #
+  # The framework-free client — scanner, linter, CLIs, configuration,
+  # transport — lives under {SpecGuard::Client}; the one component that is
+  # genuinely RSpec's is {SpecGuard::RSpecFormatter}
+  # (`require "specguard/rspec/formatter"`). What remains here is the
+  # documented `SpecGuard::RSpec.configure` entry point, kept working for
+  # anybody who configures the client from a `spec_helper.rb`.
+  #
+  # It is a thin delegate, not a second configuration: all three methods
+  # forward to {SpecGuard.configure} / {SpecGuard.configuration} /
+  # {SpecGuard.reset_configuration!}, so `SpecGuard::RSpec.configure` and
+  # `SpecGuard.configure` return the very same {Client::Configuration} object.
+  # A Minitest consumer has no reason to say `RSpec` and should configure
+  # through `SpecGuard.configure`.
   module RSpec
-    # The Ruby client for SpecGuard.
-    #
-    # The linter is complete end to end: it finds `@intent:` annotations in
-    # spec files, captures each payload string-aware, normalizes PROTOCOL.md
-    # §1's permissive syntax into strict JSON, validates the result against the
-    # vendored OpenTestIntent schema, and reports violations in the reference
-    # tool's own grammar under the 0/1/2 exit contract (see {CLI}).
-    #
-    # The RSpec formatter (`SpecGuard::RSpecFormatter`) is the other half of
-    # the client, and it is deliberately **not** required from here: `rspec` is
-    # a development dependency of this gem, not a runtime one, and
-    # `bin/specguard-lint` loads this file on machines that may have no RSpec
-    # at all. Requiring `rspec/core` from this chain would turn a missing test
-    # framework into a broken linter. Load it by its own path when you want it
-    # — `require "specguard/rspec/formatter"` — and see that file for the
-    # opt-in wiring.
-    class Error < StandardError; end
+    class << self
+      # @yieldparam configuration [Client::Configuration]
+      # @return [Client::Configuration] the same object {SpecGuard.configure} returns
+      def configure(&)
+        SpecGuard.configure(&)
+      end
 
-    # A source line could not be scanned (unterminated string or object
-    # literal). Internal to the scanner: it is caught and turned into a
-    # {Finding}'s `problem` rather than reaching a caller.
-    class ScanError < Error; end
+      # @return [Client::Configuration]
+      def configuration
+        SpecGuard.configuration
+      end
 
-    # The tool was invoked in a way that cannot work — `--changed` outside a git
-    # repository, say. Distinct from "the annotations are bad": the exit-code
-    # contract makes this a 2, and it is typed here so the CLI can map it
-    # without re-deriving the distinction from an error message.
-    class UsageError < Error; end
-
-    # The Go validator backend could not produce a verdict — the binary named
-    # by `SPECGUARD_VALIDATE_INTENT`, or the default binary the backend
-    # resolves when that is blank, is missing, will not execute, exited with a
-    # code that is not a verdict, or emitted something this cannot read as a
-    # report.
-    #
-    # Typed separately from {UsageError} because the two are different
-    # accusations ("you invoked me wrongly" vs "the tool I was told to use is
-    # broken"), and rescued *beside* it in {CLI#run} because the answer to both
-    # is the same and non-negotiable: exit 2, never 1. See {ValidatorBackend}.
-    class ValidatorError < Error; end
-
-    # The vendored canonical OpenTestIntent schema, copied byte-for-byte from
-    # open-test-intent so this gem has **no cross-repo runtime dependency**.
-    # It ships packaged (it lives under `lib/`, which the gemspec includes);
-    # the spec fixtures deliberately do not, so nothing here may be
-    # load-bearing at runtime.
-    #
-    # Since the SPGD-867 cutover nothing VALIDATES against this copy — every
-    # verdict comes from the `validate-intent` binary's own compiled-in
-    # schema. It survives because {ValidatorBackend}'s schema-contract check
-    # digests it at runtime and refuses a binary that would enforce different
-    # bytes: the two halves of the seam must keep meeting somewhere, and this
-    # file is where the gem's half lives.
-    SCHEMA_PATH = File.expand_path("rspec/schemas/open-test-intent.v1.json", __dir__).freeze
+      # @return [void]
+      def reset_configuration!
+        SpecGuard.reset_configuration!
+      end
+    end
   end
 end
-
-require_relative "rspec/finding"
-require_relative "rspec/annotation_scanner"
-require_relative "rspec/payload_normalizer"
-require_relative "rspec/scanner"
-require_relative "rspec/file_selector"
-require_relative "rspec/linter"
-require_relative "rspec/json_reporter"
-require_relative "rspec/validator_backend"
-require_relative "rspec/cli"

data/lib/specguard/version.rb

@@ -7,5 +7,5 @@
 # framework-scoped version constant a lie, so the number moved here and the
 # rspec module now points at it for back-compat.
 module SpecGuard
-  VERSION = "0.3.29"
+  VERSION = "0.3.31"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: specguard-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.29
+  version: 0.3.31
 platform: ruby
 authors:
 - specguard Agent
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -47,24 +47,25 @@ files:
 - bin/specguard-ingest
 - bin/specguard-lint
 - lib/minitest/specguard_plugin.rb
+- lib/specguard/client.rb
+- lib/specguard/client/annotation_lookup.rb
+- lib/specguard/client/annotation_scanner.rb
+- lib/specguard/client/cli.rb
+- lib/specguard/client/configuration.rb
+- lib/specguard/client/file_selector.rb
+- lib/specguard/client/finding.rb
+- lib/specguard/client/ingest_cli.rb
+- lib/specguard/client/ingest_reporter.rb
+- lib/specguard/client/json_reporter.rb
+- lib/specguard/client/linter.rb
+- lib/specguard/client/payload_normalizer.rb
+- lib/specguard/client/scanner.rb
+- lib/specguard/client/schemas/open-test-intent.v1.json
+- lib/specguard/client/transport.rb
+- lib/specguard/client/validator_backend.rb
 - lib/specguard/minitest/reporter.rb
 - lib/specguard/rspec.rb
-- lib/specguard/rspec/annotation_lookup.rb
-- lib/specguard/rspec/annotation_scanner.rb
-- lib/specguard/rspec/cli.rb
-- lib/specguard/rspec/configuration.rb
-- lib/specguard/rspec/file_selector.rb
-- lib/specguard/rspec/finding.rb
 - lib/specguard/rspec/formatter.rb
-- lib/specguard/rspec/ingest_cli.rb
-- lib/specguard/rspec/ingest_reporter.rb
-- lib/specguard/rspec/json_reporter.rb
-- lib/specguard/rspec/linter.rb
-- lib/specguard/rspec/payload_normalizer.rb
-- lib/specguard/rspec/scanner.rb
-- lib/specguard/rspec/schemas/open-test-intent.v1.json
-- lib/specguard/rspec/transport.rb
-- lib/specguard/rspec/validator_backend.rb
 - lib/specguard/rspec/version.rb
 - lib/specguard/version.rb
 - script/bump-version.sh