rail_verdict 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd73e695fc399f10d5e9dcde4f8f04294948160821c9f256234e79d6345bb8e0
-  data.tar.gz: dfb8a4b7ae5613ab75ef864dfbca00d3fa7c6241ad47937241e524aa5724b7ff
+  metadata.gz: 220003ceaeba89b1fb2f8f7082a8a2e6f6dcdcc070005221000602524e3b7576
+  data.tar.gz: 13fb2353b109fed755c762be216060174b3a89a59bbc6e443f06d133edbf0537
 SHA512:
-  metadata.gz: 9faf8ca3b218e240f87800727704caa02c588d5e88fa8a614a15f0862928ad4ccd36725bbd66300d89330c9994a4f16c2f7d63cd14df2c79899b8d4380bb95de
-  data.tar.gz: 05daa4f456785c207522f9c8be75066ee0a7c112ee5681b7ea311151b3e0b2180fee7008ff97e5b79f12f439751c115a43cefc7550a1a6e16c1637296d9415c5
+  metadata.gz: 7a58b08566a039a6c32fae4a4e4154be529a2c4e0567afc2ee7ac8b24c6e944e0b0555359eb8ea532c02f6143aa4e7594cce208c41bc284243d519d704f07d62
+  data.tar.gz: a79f0ce2a5eb249cd902f60f74b41318dba4f52112004109b42d394540f9ab8aac846a0e5e8d22c1cee009d649016fbf75dc8d715a2440fb498e61b3600247ee

data/README.md

@@ -78,18 +78,11 @@ The Lab exercises RailVerdict across realistic operational scenarios:
 - Exercising fail-closed behavior on missing or malformed analyzer output;
 - Testing release artifact installation from clean environments.
 
-### 21 / 21 External Validation Campaign
+### External Validation Campaign
 
-The 1.0 release closeout validated **21 out of 21** external scenarios:
+The Lab independently validates the published gem as an external consumer. 1.0 closeout validated **21 / 21** scenarios; **1.2.0** certification validates **81 scenarios** (14 categories, see Lab README) including Verification Receipts and PR Intelligence. See [railverdict-lab](https://github.com/pedro-dalben/railverdict-lab) for the canonical campaign and results.
 
-| Category | Scenarios | Result |
-|---|---:|:---:|
-| **Core Verification** | 12 / 12 | PASS |
-| **Operational & CI** | 6 / 6 | PASS |
-| **Release Closeout** | 3 / 3 | PASS |
-| **Total** | **21 / 21** | **PASS** |
-
-These controlled validation scenarios represent rigorous external regression verification rather than a claim of mathematically bug-free software. During development, the Lab uncovered real defects — such as test failure scoping edge cases — which were fixed before the 1.0 release.
+These controlled validation scenarios represent rigorous external regression verification rather than a claim of mathematically bug-free software. During development, the Lab uncovered real defects — such as test failure scoping edge cases and the 1.2 dogfooding hardening — which were fixed before release.
 
 ---
 
@@ -236,11 +229,73 @@ an explicit value, including every analyzer in older configuration versions,
 continues to use 30 seconds. A timeout is incomplete evidence, never a normal
 finding: a required timeout produces `INCOMPLETE` and exit code `2`.
 
-RailVerdict 1.0.1 has no CLI timeout override; the versioned configuration is
+There is no CLI timeout override; the versioned configuration (`version: 1.5`) is
 the supported public surface. SimpleCov accepts the same setting for a uniform
 configuration contract, but reads a local coverage artifact rather than
 starting an analyzer process.
 
+### 30-Second Demonstration (real output)
+
+```console
+$ railverdict check
+
+RailVerdict Verification: PASS
+Policy: no_new_debt (complete)
+Analyzers: 5 run (5 complete)
+Findings: 0 introduced, 0 existing, 0 blocking
+Exit: 0
+```
+
+Introduce a controlled defect:
+
+```ruby
+# app/models/user.rb:42
+unused = "oops" # Lint/UselessAssignment
+```
+
+```console
+$ railverdict check
+
+RailVerdict Verification: FAIL
+Policy: no_new_debt (failed)
+Findings: 1 introduced (blocking), 0 existing
+  - [rubocop] Lint/UselessAssignment in app/models/user.rb:42 (introduced)
+Exit: 1
+```
+
+Fix it, rerun → `PASS`. See `docs/release/1.2-clean-room-rehearsal.md` for automated reproduction.
+
+### Why not just CI?
+
+CI answers **“did these jobs execute successfully?”** across fragmented outputs. RailVerdict answers **“given required evidence, repository state, baseline and policy, what is the deterministic verification decision for this change?”** — normalized findings, baseline-aware policy (`no_new_debt`), changed-scope (`--changed --base`), fail-closed `INCOMPLETE` on missing evidence, and machine contracts (JSON/SARIF/exits) plus Repository State Identity and Verification Receipts. It complements CI; the example in [GitHub Actions Integration](#github-actions-integration) runs RailVerdict inside CI.
+
+### Why not just RSpec + RuboCop?
+
+Those are the evidence. RailVerdict is the verifier:
+
+```
+RSpec says:       42 tests passed.
+RuboCop says:     3 offenses.
+SimpleCov says:   91.3% coverage.
+Git says:         these 7 lines changed.
+RailVerdict says: FAIL — this change introduced a blocking finding.
+```
+
+They produce facts; policy owns the gate. `rubocop` + `rspec` + `minitest` + `simplecov` + `bundler-audit` + `Git` are inputs; `PASS/WARN/FAIL/INCOMPLETE` is the `GateResult` (see `docs/contracts.md`).
+
+### Why this matters for AI agents
+
+An AI agent can write code, run tests, and declare itself finished — but it should not be the authority deciding whether its own work is acceptable.
+
+```
+Agent --modifies--> Repository --verify--> RailVerdict
+                                           |--> deterministic evidence
+                                           |--> GateResult
+                                           `--> Verification Receipt
+```
+
+The agent proposes; the verification system decides. Receipts let agents (and humans) prove `fresh` vs `stale` after any edit — see below. AI inside RailVerdict (`explain`/`investigate`) is advisory only and never changes `GateResult`.
+
 ---
 
 ## The Default Policy Model: No New Debt
@@ -339,12 +394,28 @@ exit code `2`.
 Verification is only meaningful for the exact state that was verified. RailVerdict 1.2 binds every guarded verification to a deterministic **Repository State Identity** (HEAD + Git index snapshot + worktree delta with content hashes + configuration/baseline/waiver digests) and issues a machine-readable **Verification Receipt**:
 
 ```console
-$ railverdict receipt create --format json > receipt.json
+$ railverdict check
+# => RailVerdict Verification: PASS (exit 0)
+$ railverdict receipt create > receipt.json
+# receipt_id = sha256:<64 hex>  (no created_at, no timestamps)
+
 $ railverdict receipt verify receipt.json --format json
-{"schema_version":"1.0","status":"fresh","reasons":[],"gate":"PASS", ...}
+{"schema_version":"1.0","status":"fresh","reasons":[],"gate":"PASS"}
+```
+
+Edit anything afterwards and the same receipt reports `stale`:
+
+```console
+$ echo "# changed after verification" >> app/models/user.rb
+$ railverdict receipt verify receipt.json --format json
+{"schema_version":"1.0","status":"stale","reasons":["worktree_changed"],"gate":"PASS"}
+# exit 2 — current state is not what was verified
+
+# Same for staged, config, baseline, waiver edits:
+# head_changed | index_changed | worktree_changed | configuration_changed | baseline_changed | waivers_changed
 ```
 
-Edit anything afterwards — source, staged index, untracked files, config, baseline, waivers — and the same receipt reports `stale` with a deterministic reason (`head_changed`, `index_changed`, `worktree_changed`, `configuration_changed`, `baseline_changed`, `waivers_changed`). If the repository mutates while analyzers run, receipt issuance fails closed with `repository_changed_during_verification`. Receipts exist for PASS, FAIL, and INCOMPLETE alike; they are deterministic integrity records, not signed attestations — a trusted CI remains the trust anchor when forgery is in scope. Coding agents follow the completion protocol in [docs/agent-verification.md](docs/agent-verification.md).
+If the repository mutates while analyzers run, receipt issuance fails closed with `repository_changed_during_verification`. Receipts exist for `PASS`, `FAIL`, and `INCOMPLETE`; they are deterministic integrity records — **not signed attestations** — a trusted CI remains the trust anchor when forgery is in scope. Full protocol in [docs/agent-verification.md](docs/agent-verification.md).
 
 ```
 Deterministic Verification → PR Intelligence → Verification Receipt → Agent Verification Protocol
@@ -364,7 +435,7 @@ All analyzers in RailVerdict are **external and owned by the target project**. R
 | **SimpleCov** | Code and changed-line coverage | `>= 1, < 2` | Ingests versioned public `coverage/coverage.json` v1 (never parses internal `.resultset.json`). |
 | **bundler-audit** | Gem dependency vulnerabilities | `>= 0.9.3, < 1` | Runs `bundle exec bundler-audit check --format json` (never runs automatic updates). Robustly extracts JSON when advisory-DB download notices precede the payload. |
 
-> **Brakeman Status:** Brakeman support is **not included** in 1.0 (on HOLD pending legal and licensing review). Third-party analyzers retain their respective upstream licenses.
+> **Brakeman Status:** Brakeman support is **not included** in 1.2.0 (on HOLD pending legal and licensing review). Third-party analyzers retain their respective upstream licenses.
 
 ---
 
@@ -450,7 +521,44 @@ See [`docs/ai.md`](docs/ai.md) and [`docs/privacy.md`](docs/privacy.md) for deta
 
 ## Coding Agents & The Repair Loop
 
-RailVerdict provides a structured verification loop for AI coding agents (such as Claude, Codex, or custom agents):
+### Agent Completion Protocol (copyable for AGENTS.md / CLAUDE.md / Codex)
+
+Before declaring any code-changing task complete:
+
+1. Run the required project tests.
+2. Run `bundle exec railverdict check` (or `check --changed --base <main>` in PRs).
+3. If `FAIL`: remediate findings and rerun until `PASS` or explicitly report the blocker.
+4. If `INCOMPLETE` (exit 2): do not claim verification succeeded — fix the evidence gap (missing analyzer, bad base, shallow history).
+5. After final `PASS`, create `bundle exec railverdict receipt create > receipt.json`.
+6. Do not modify repository state after receipt creation without reverifying — `receipt verify` must stay `fresh`.
+
+`FAIL` means remediation required. `INCOMPLETE` must never be represented as `PASS`. See `docs/agent-verification.md` for the formal contract.
+
+<details><summary>AGENTS.md snippet (paste into your repo)</summary>
+
+```markdown
+## Verification
+
+Before completing any code-changing task:
+
+bundle exec railverdict check
+
+A task may only be reported as verified when RailVerdict returns PASS (exit 0).
+
+FAIL (exit 1) means remediation is required.
+
+INCOMPLETE (exit 2) means required evidence could not be obtained and must never be represented as PASS.
+
+After the final PASS, create a verification receipt: bundle exec railverdict receipt create > receipt.json
+
+Do not modify repository state after receipt creation without reverifying (receipt verify must be fresh).
+```
+
+Validated against 1.2.0: `init`, `doctor`, `check`, `pr`, `baseline create`, `findings`, `repair`, `receipt create|verify`, `mcp serve`.
+
+</details>
+
+RailVerdict also provides a structured verification loop for AI coding agents (such as Claude, Codex, or custom agents):
 
 ```
 Agent modifies code
@@ -503,6 +611,8 @@ railverdict mcp serve
 | `verify_repair` | Reruns verification and classifies whether a repair succeeded or regressed. |
 | `explain` | Generates an advisory AI explanation for a finding. |
 | `investigate` | Investigates top blocking findings across the codebase. |
+| `get_verification_receipt` | Returns the Verification Receipt for the last `verify` without rerunning analyzers (refuses stale cache). |
+| `get_pr_intelligence` | Returns PR Intelligence derived from the last `verify`'s GateResult (no rerun). |
 
 ### MCP Security Properties
 
@@ -575,7 +685,7 @@ To maintain clear technical boundaries, RailVerdict is explicitly **NOT**:
 
 ## Project Status
 
-- **Release Version:** `1.0.1`
+- **Release Version:** `1.2.0`
 - **License:** [MIT](LICENSE) (see [NOTICE](NOTICE))
 - **Trademarks:** [TRADEMARKS.md](TRADEMARKS.md)
 - **Foundation & Legal:** [docs/foundation.md](docs/foundation.md) — preliminary screen found no obvious software/tool conflict; NOT LEGAL CLEARANCE; qualified trademark review NOT PERFORMED — NON-BLOCKING BY MAINTAINER DECISION 2026-08-19 (Pedro Dalben).
@@ -605,9 +715,32 @@ To maintain clear technical boundaries, RailVerdict is explicitly **NOT**:
 
 ---
 
+## Try RailVerdict Challenge (5 minutes)
+
+1. `bundle add rail_verdict --group development,test --require false && bundle install`
+2. `bundle exec railverdict init && bundle exec railverdict doctor`
+3. `bundle exec railverdict baseline create` (or skip for greenfield) → `bundle exec railverdict check` → first gate
+4. Introduce a controlled RuboCop offense, rerun → `FAIL`, fix → `PASS`, then `railverdict receipt create && railverdict receipt verify`
+
+Tell us where it confused (see `docs/troubleshooting.md` and `docs/launch/try-challenge.md`).
+
+## FAQ
+
+**Is RailVerdict a test framework? Does it replace RSpec/RuboCop/CI?** No — it consumes them; they are evidence, it is the verifier. Run it inside CI.
+
+**Does it upload source? Require AI? Does AI decide PASS?** No/no/no — offline by default, AI advisory only off by default (`trust: redacted`).
+
+**Legacy apps?** Yes — `no_new_debt` baseline.
+
+**INCOMPLETE vs FAIL?** `FAIL` = complete verification rejected new debt; `INCOMPLETE` = required evidence missing → no gate (exit 2), never PASS.
+
+**Baseline / waiver / receipt?** Baseline snapshots current debt; waiver is exact-fingerprint, UTC-expired exemption; receipt is an integrity record (`receipt_id = sha256:`) — **not signed**, forgeable via whole-file rewrite — trusted CI is the trust anchor. Mutating after `PASS` makes receipt `stale`.
+
+**Brakeman / Ruby / Rails?** Brakeman not in 1.2.0 (HOLD); Ruby `>=3.3`, Rails `>=8.0` bounded.
+
 ## Contributing & Issues
 
-Contributions and issue reports are welcome. Please open an issue on GitHub for:
+Contributions and issue reports are welcome. See `CONTRIBUTING.md` for “how to run tests / add regression”. Issue templates: Bug, Feature request, Compatibility report. Please open an issue on GitHub for:
 
 - Analyzer compatibility and version range feedback;
 - False positives or false negatives in evidence normalization;

data/lib/rail_verdict/analyzers/bundler_audit.rb

@@ -19,13 +19,14 @@ module RailVerdict
       end
 
       def probe(repository_root, runner: ProcessRunner, timeout_seconds: 15.0)
+        effective_timeout = [timeout_seconds.to_f, 5.0].min
         command = @command_resolver.call(repository_root)
         invocation = Shared.invocation_for(command, ["version"])
         result = runner.run(
           command.fetch(:executable),
           invocation.fetch("argv"),
           chdir: repository_root,
-          timeout_seconds: timeout_seconds
+          timeout_seconds: effective_timeout
         )
 
         return Probe.new(status: "unavailable", message: Shared.detail_for(result)) if result.status == :spawn_failed

data/lib/rail_verdict/analyzers/minitest.rb

@@ -21,13 +21,14 @@ module RailVerdict
       end
 
       def probe(repository_root, runner: ProcessRunner, timeout_seconds: 15.0)
+        effective_timeout = [timeout_seconds.to_f, 5.0].min
         command = @command_resolver.call(repository_root)
         probe_argv = probe_argv_for(command, repository_root)
         result = runner.run(
           command.fetch(:executable),
           probe_argv,
           chdir: repository_root,
-          timeout_seconds: timeout_seconds
+          timeout_seconds: effective_timeout
         )
 
         return Probe.new(status: "unavailable", message: Shared.detail_for(result)) if result.status == :spawn_failed
@@ -63,7 +64,7 @@ module RailVerdict
         end
 
         invocation = Shared.invocation_for(command, ["run"])
-        output_path = File.join(repository_root, ".railverdict-minitest-#{SecureRandom.hex(6)}.json")
+        output_path = File.join(Dir.tmpdir, "railverdict-minitest-#{SecureRandom.hex(8)}.json")
         env_reset_required = false
         previous_env = ENV["RAILVERDICT_MINITEST_OUTPUT"]
         begin
@@ -93,7 +94,25 @@ module RailVerdict
             return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
           end
 
-          analyzer_result = AnalyzerResult.new(
+          # Process exit reconciliation (RH-03):
+failures_and_errors = (summary["failures"] || 0) + (summary["errors"] || 0)
+if result.exit_code == 0
+  if failures_and_errors > 0 || !findings.empty?
+    return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: "Minitest exited with status 0 but reported #{failures_and_errors} failures/errors", tool_version: tool_version), []]
+  end
+elsif result.exit_code == 1
+  if failures_and_errors == 0 && findings.empty?
+    detail = Shared.detail_for(result)
+    msg = detail.strip.empty? ? "Minitest exited with status 1 but reported 0 failed tests" : detail
+    return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "failed", message: msg, tool_version: tool_version), []]
+  end
+else
+  detail = Shared.detail_for(result)
+  msg = detail.strip.empty? ? "Minitest exited with unexpected status #{result.exit_code}" : detail
+  return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "failed", message: msg, tool_version: tool_version), []]
+end
+
+analyzer_result = AnalyzerResult.new(
             analyzer: ANALYZER_ID,
             tool_version: tool_version,
             invocation: invocation,
@@ -141,16 +160,11 @@ module RailVerdict
 
       def resolve_reporter_path
         candidates = []
-        begin
-          specs = Gem::Specification.find_all_by_name("rail_verdict")
-          if specs.any?
-            best = specs.max_by(&:version)
-            candidates << File.join(best.full_gem_path, "exe", "railverdict-minitest-reporter.rb")
-          end
-        rescue StandardError
-          nil
-        end
         candidates << File.expand_path("../../../exe/railverdict-minitest-reporter.rb", __dir__)
+        if defined?(Gem) && Gem.respond_to?(:loaded_specs) && Gem.loaded_specs["rail_verdict"]
+          spec = Gem.loaded_specs["rail_verdict"]
+          candidates << File.join(spec.full_gem_path, "exe", "railverdict-minitest-reporter.rb")
+        end
         candidates.find { |path| File.file?(path) && File.readable?(path) }
       end
 
@@ -177,31 +191,30 @@ module RailVerdict
       end
 
       def load_reporter_document(output_path, run_result, invocation, tool_version)
-        if File.file?(output_path)
-          begin
-            bytes = File.binread(output_path)
-          rescue SystemCallError => error
-            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
-          end
-          if bytes.bytesize > 4 * 1024 * 1024
-            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "truncated", message: "Minitest reporter output exceeds 4 MiB", tool_version: tool_version), []]
-          end
-          text = bytes.dup.force_encoding(Encoding::UTF_8)
-          unless text.valid_encoding?
-            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "parse_failed", message: "Minitest reporter output is not valid UTF-8", tool_version: tool_version), []]
-          end
-          begin
-            return JSON.parse(text)
-          rescue JSON::ParserError => error
-            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "parse_failed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
-          end
+        unless File.file?(output_path)
+          detail = Shared.detail_for(run_result)
+          msg = detail.strip.empty? ? "Minitest reporter did not produce output" : detail
+          status = run_result.exit_code && run_result.exit_code != 0 ? "failed" : "malformed"
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: status, message: msg, tool_version: tool_version), []]
         end
-        stdout = run_result.stdout.to_s
-        if stdout.strip.empty?
-          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: "Minitest reporter did not produce output", tool_version: tool_version), []]
+
+        begin
+          bytes = File.binread(output_path)
+        rescue SystemCallError => error
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
         end
+
+        if bytes.bytesize > 4 * 1024 * 1024
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "truncated", message: "Minitest reporter output exceeds 4 MiB", tool_version: tool_version), []]
+        end
+
+        text = bytes.dup.force_encoding(Encoding::UTF_8)
+        unless text.valid_encoding?
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "parse_failed", message: "Minitest reporter output is not valid UTF-8", tool_version: tool_version), []]
+        end
+
         begin
-          JSON.parse(stdout)
+          JSON.parse(text)
         rescue JSON::ParserError => error
           [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "parse_failed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
         end

data/lib/rail_verdict/analyzers/rspec.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "json"
+require "tmpdir"
+require "securerandom"
 
 require_relative "_shared"
 
@@ -19,13 +21,16 @@ module RailVerdict
       end
 
       def probe(repository_root, runner: ProcessRunner, timeout_seconds: 15.0)
+        effective_timeout = [timeout_seconds.to_f, 5.0].min
         command = @command_resolver.call(repository_root)
-        invocation = Shared.invocation_for(command, ["--version"])
+        clean_prefix = clean_args_prefix(command.fetch(:args_prefix))
+        clean_command = command.merge(args_prefix: clean_prefix)
+        invocation = Shared.invocation_for(clean_command, ["--version"])
         result = runner.run(
-          command.fetch(:executable),
+          clean_command.fetch(:executable),
           invocation.fetch("argv"),
           chdir: repository_root,
-          timeout_seconds: timeout_seconds
+          timeout_seconds: effective_timeout
         )
 
         return Probe.new(status: "unavailable", message: Shared.detail_for(result)) if result.status == :spawn_failed
@@ -47,61 +52,136 @@ module RailVerdict
 
       def run(repository_root, runner: ProcessRunner, timeout_seconds: 30.0, probe_result: nil, configuration: nil)
         command = @command_resolver.call(repository_root)
+        clean_prefix = clean_args_prefix(command.fetch(:args_prefix))
+        clean_command = command.merge(args_prefix: clean_prefix)
         probe_result ||= probe(repository_root, runner: runner, timeout_seconds: timeout_seconds)
-        version_invocation = Shared.invocation_for(command, ["--version"])
+        version_invocation = Shared.invocation_for(clean_command, ["--version"])
 
         unless probe_result.status == "succeeded"
           return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: version_invocation, status: probe_result.status, message: probe_result.message, tool_version: probe_result.version), []]
         end
 
-        invocation = Shared.invocation_for(command, ["--format", "json"])
-        # Real-world large RSpec suites can exceed 4 MiB; use bounded but larger capture.
+        output_path = File.join(Dir.tmpdir, "railverdict-rspec-#{SecureRandom.hex(8)}.json")
+        public_invocation = Shared.invocation_for(clean_command, ["--format", "json"])
+        run_argv = clean_prefix.dup.concat(["--format", "json", "--out", output_path])
+
         max_stdout = resolve_stdout_limit(configuration, repository_root, 16 * 1024 * 1024)
-        result = runner.run(
-          command.fetch(:executable),
-          invocation.fetch("argv"),
-          chdir: repository_root,
-          timeout_seconds: timeout_seconds,
-          max_stdout_bytes: max_stdout
-        )
         tool_version = probe_result.version
 
-        return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "unavailable", message: Shared.detail_for(result), tool_version: tool_version), []] if result.status == :spawn_failed
-        return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "truncated", message: Shared.detail_for(result), tool_version: tool_version), []] if Shared.truncated?(result)
-        return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "timed_out", message: Shared.detail_for(result), tool_version: tool_version), []] if result.status == :timed_out
-        return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "signaled", message: Shared.detail_for(result), tool_version: tool_version), []] if result.status == :signaled
-
         begin
-          document = JSON.parse(result.stdout)
-        rescue JSON::ParserError => error
-          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "parse_failed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
+          result = runner.run(
+            clean_command.fetch(:executable),
+            run_argv,
+            chdir: repository_root,
+            timeout_seconds: timeout_seconds,
+            max_stdout_bytes: max_stdout
+          )
+
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "unavailable", message: Shared.detail_for(result), tool_version: tool_version), []] if result.status == :spawn_failed
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "truncated", message: Shared.detail_for(result), tool_version: tool_version), []] if Shared.truncated?(result)
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "timed_out", message: Shared.detail_for(result), tool_version: tool_version), []] if result.status == :timed_out
+          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "signaled", message: Shared.detail_for(result), tool_version: tool_version), []] if result.status == :signaled
+
+          unless File.file?(output_path)
+            detail = Shared.detail_for(result)
+            msg = detail.strip.empty? ? "RSpec did not produce structured output" : detail
+            status = result.exit_code && result.exit_code != 0 ? "failed" : "malformed"
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: status, message: msg, tool_version: tool_version), []]
+          end
+
+          begin
+            bytes = File.binread(output_path)
+          rescue SystemCallError => error
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "malformed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
+          end
+
+          if bytes.bytesize > max_stdout
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "truncated", message: "RSpec output exceeds #{max_stdout} bytes", tool_version: tool_version), []]
+          end
+
+          text = bytes.dup.force_encoding(Encoding::UTF_8)
+          unless text.valid_encoding?
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "parse_failed", message: "RSpec output is not valid UTF-8", tool_version: tool_version), []]
+          end
+
+          begin
+            document = JSON.parse(text)
+          rescue JSON::ParserError => error
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "parse_failed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
+          end
+
+          begin
+            summary, findings = normalize_document(document)
+          rescue MalformedOutput => error
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "malformed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
+          end
+
+          # Process exit reconciliation (RH-02):
+          # 0: all examples passed, 0 failures/errors
+          # 1: failed examples present (failures > 0 or findings non-empty)
+          # Any other exit code or contradiction: fail closed
+          failures_count = summary["failures"] || 0
+          if result.exit_code == 0
+            if failures_count > 0 || !findings.empty?
+              return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "malformed", message: "RSpec exited with status 0 but reported #{failures_count} failures", tool_version: tool_version), []]
+            end
+          elsif result.exit_code == 1
+            if failures_count == 0 && findings.empty?
+              detail = Shared.detail_for(result)
+              msg = detail.strip.empty? ? "RSpec exited with status 1 but reported 0 failed examples" : detail
+              return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "failed", message: msg, tool_version: tool_version), []]
+            end
+          else
+            detail = Shared.detail_for(result)
+            msg = detail.strip.empty? ? "RSpec exited with unexpected status #{result.exit_code}" : detail
+            return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: public_invocation, status: "failed", message: msg, tool_version: tool_version), []]
+          end
+
+          analyzer_result = AnalyzerResult.new(
+            analyzer: ANALYZER_ID,
+            tool_version: tool_version,
+            invocation: public_invocation,
+            execution_status: "succeeded",
+            finding_ids: findings.map(&:id),
+            evidence_summary: summary
+          )
+          [analyzer_result, findings]
+        ensure
+          begin
+            File.unlink(output_path) if output_path && File.exist?(output_path)
+          rescue StandardError
+            nil
+          end
         end
-
-        begin
-          summary, findings = normalize_document(document)
-        rescue MalformedOutput => error
-          return [Shared.failure_result(analyzer_id: ANALYZER_ID, invocation: invocation, status: "malformed", message: Shared.bounded_message(error.message), tool_version: tool_version), []]
-        end
-
-        analyzer_result = AnalyzerResult.new(
-          analyzer: ANALYZER_ID,
-          tool_version: tool_version,
-          invocation: invocation,
-          execution_status: "succeeded",
-          finding_ids: findings.map(&:id),
-          evidence_summary: summary
-        )
-        [analyzer_result, findings]
       end
 
       private
 
       def default_command(repository_root)
         if File.file?(File.join(repository_root, "Gemfile"))
-          { executable: "bundle", args_prefix: ["exec", "rspec", "--format", "json"] }
+          { executable: "bundle", args_prefix: ["exec", "rspec"] }
         else
-          { executable: "rspec", args_prefix: ["--format", "json"] }
+          { executable: "rspec", args_prefix: [] }
+        end
+      end
+
+      def clean_args_prefix(prefix)
+        cleaned = []
+        skip_next = false
+        Array(prefix).each_with_index do |arg, i|
+          if skip_next
+            skip_next = false
+            next
+          end
+          if arg == "--format" && Array(prefix)[i + 1] == "json"
+            skip_next = true
+            next
+          elsif arg == "--format=json"
+            next
+          end
+          cleaned << arg
         end
+        cleaned
       end
 
       def normalize_document(document)
@@ -142,7 +222,7 @@ module RailVerdict
         raw_msg = (example["exception"] && example["exception"]["message"]) || example["full_description"] || example["description"] || nil
         message = Shared.normalize_finding_message(ANALYZER_ID, raw_msg.nil? || raw_msg.to_s.strip.empty? ? "rspec example failed" : raw_msg)
 
-        rule_id = "rspec/example:#{example['id'] || id_for(example, index)}"
+        rule_id = "rspec/example:#{example[id] || id_for(example, index)}"
         path = normalize_path(example["file_path"] || example["file"] || "spec/unknown_spec.rb")
         failure_line, failure_path = failure_location(example, path)
         start_line = failure_line || example["line_number"] || extract_line(example["id"])
@@ -273,14 +353,12 @@ module RailVerdict
       end
 
       def resolve_stdout_limit(configuration, repository_root, default_bytes)
-        # Prefer explicit per-analyzer config if present (future-compatible), else default.
         raw_limit = nil
         if configuration
           sel = configuration.analyzers[ANALYZER_ID] rescue nil
           raw_limit = sel && sel["output_limit_bytes"]
         end
         raw_limit ||= default_bytes
-        # Clamp to safe ceiling
         limit = Integer(raw_limit) rescue default_bytes
         limit = default_bytes if limit <= 0
         max = RailVerdict::ProcessRunner::MAX_SAFE_STDOUT_BYTES

data/lib/rail_verdict/analyzers/rubocop.rb

@@ -27,13 +27,14 @@ module RailVerdict
       end
 
       def probe(repository_root, runner: ProcessRunner, timeout_seconds: 15.0)
+        effective_timeout = [timeout_seconds.to_f, 5.0].min
         command = @command_resolver.call(repository_root)
         invocation = invocation_for(command, ["--version"])
         result = runner.run(
           command.fetch(:executable),
           invocation.fetch("argv"),
           chdir: repository_root,
-          timeout_seconds: timeout_seconds
+          timeout_seconds: effective_timeout
         )
 
         return Probe.new(status: "unavailable", message: detail_for(result)) if result.status == :spawn_failed