rail_verdict 1.3.0 → 1.8.2

data/lib/rail_verdict/cli.rb

@@ -3,6 +3,7 @@
 require "optparse"
 require "json"
 require "fileutils"
+require "open3"
 require "securerandom"
 
 module RailVerdict
@@ -10,6 +11,7 @@ module RailVerdict
     EXIT_OK = 0
     EXIT_POLICY_FAIL = 1
     EXIT_NO_GATE = 2
+    EXIT_REVIEW_REQUIRED = 3
     EXIT_INTERRUPTED = 130
 
     FORMATS = %w[console json sarif].freeze
@@ -22,13 +24,17 @@ module RailVerdict
         init             Write the default .railverdict.yml configuration
         doctor           Report configuration and analyzer observations
         check            Run verification and print the gate result
+        policy           Evaluate engineering policy requirements over the gate
         pr               Summarize one changed-scope verification for review
         baseline create  Deferred boundary; Phase 3 owns baseline writes
         findings         Print normalized findings from the evidence run
         explain          Explain a finding with optional AI
         investigate      Investigate top findings with optional AI
         repair           Build a deterministic repair packet for a finding
+        repair verify    Re-verify a repair packet against fresh evidence
+        review           Show the bounded review packet for a verification
         receipt          Create or verify a Verification Receipt
+        handoff          Create or verify a Verification Handoff (evidence reuse)
         mcp              MCP adapter (serve)
 
       Global options:
@@ -59,18 +65,22 @@ module RailVerdict
         command_check(argv.drop(1))
       when "pr"
         command_pr(argv.drop(1))
+      when "policy"
+        command_policy(argv.drop(1))
       when "baseline"
         command_baseline(argv.drop(1))
       when "findings"
         command_findings(argv.drop(1))
       when "explain"
         command_explain(argv.drop(1))
-      when "investigate"
-        command_investigate(argv.drop(1))
       when "repair"
         command_repair(argv.drop(1))
-      when "receipt"
+      when "review"
+        command_review(argv.drop(1))
+        when "receipt"
         command_receipt(argv.drop(1))
+      when "handoff"
+        command_handoff(argv.drop(1))
       when "mcp"
         command_mcp(argv.drop(1))
       else
@@ -130,15 +140,16 @@ module RailVerdict
     end
 
     def command_check(argv)
-      options = { config: DEFAULT_CONFIG_PATH, format: "console", changed: false, base: nil, baseline: nil, waiver: nil }
+      options = { config: DEFAULT_CONFIG_PATH, format: "console", changed: false, base: nil, baseline: nil, waiver: nil, handoff: nil }
       parser = OptionParser.new do |opts|
-        opts.banner = "Usage: railverdict check [--config PATH] [--format console|json|sarif] [--changed] [--base REV] [--baseline PATH] [--waiver PATH]"
+        opts.banner = "Usage: railverdict check [--config PATH] [--format console|json|sarif] [--changed] [--base REV] [--baseline PATH] [--waiver PATH] [--handoff PATH]"
         opts.on("--config PATH", String) { |value| options[:config] = value }
         opts.on("--format FORMAT", String) { |value| options[:format] = value }
         opts.on("--changed") { options[:changed] = true }
         opts.on("--base REV", String) { |value| options[:base] = value }
         opts.on("--baseline PATH", String) { |value| options[:baseline] = value }
         opts.on("--waiver PATH", String) { |value| options[:waiver] = value }
+        opts.on("--handoff PATH", String) { |value| options[:handoff] = value }
       end
       parse!(parser, argv)
       validate_format!(options[:format])
@@ -146,12 +157,144 @@ module RailVerdict
         raise RailVerdict::UsageError, "--base requires --changed"
       end
 
+      if options[:handoff]
+        return command_check_with_handoff(options)
+      end
+
       outcome, interrupted = execute_check(options)
       return EXIT_NO_GATE unless render_result(outcome.result, options[:format])
 
       exit_code_for(outcome.result, interrupted: interrupted)
     end
 
+    def command_check_with_handoff(options)
+      handoff_path = options[:handoff]
+      begin
+        text = File.binread(handoff_path)
+      rescue StandardError => e
+        @stderr.puts "railverdict check --handoff: cannot read handoff: #{e.message}"
+        return EXIT_NO_GATE
+      end
+      handoff_doc, err = Handoff.parse(text)
+      unless handoff_doc
+        @stderr.puts "railverdict check --handoff: handoff invalid (#{err}); running full verification"
+        outcome, interrupted = execute_check(options.reject { |k, _| k == :handoff })
+        return EXIT_NO_GATE unless render_result(outcome.result, options[:format])
+        return exit_code_for(outcome.result, interrupted: interrupted)
+      end
+
+      # Independent observation
+      effective_paths = Check.effective_input_paths(root: @working_directory, config_path: resolved_override_path(options[:config], File.join(@working_directory, DEFAULT_CONFIG_PATH)), baseline_path_override: options[:baseline] && resolved_override_path(options[:baseline], nil), waiver_path_override: options[:waiver] && resolved_override_path(options[:waiver], nil))
+      before_state = RepositoryState.capture(repository_root: @working_directory, configuration_paths: effective_paths)
+      current_state = before_state
+      current_env_obj = VerificationEnvironment.capture(repository_root: @working_directory)
+      current_env = {
+        "ruby_engine" => current_env_obj.ruby_engine,
+        "ruby_version" => current_env_obj.ruby_version,
+        "railverdict_version" => current_env_obj.railverdict_version,
+        "analyzer_versions" => current_env_obj.analyzer_versions
+      }
+      config = Configuration.load(effective_paths[:config]) rescue nil
+      required = config ? config.analyzers.select { |_, s| s["enabled"] && s["required"] }.keys.map(&:to_s) : []
+      contract = { "required_analyzers" => required, "verification_mode" => handoff_doc.dig("source_scope", "verification_mode"), "changed_base" => handoff_doc.dig("source_scope", "changed_base") }
+      reuse_result = Reuse.evaluate(handoff_document: handoff_doc, current_repository_state: current_state, current_environment: current_env, current_contract: contract)
+      after_state = RepositoryState.capture(repository_root: @working_directory, configuration_paths: effective_paths)
+      if before_state && after_state && before_state.digest != after_state.digest
+        reuse_result = Reuse::Result.new(decision: Reuse::VERIFICATION_REQUIRED, reasons: reuse_result.reasons + ["reuse_toctou"], handoff_valid: reuse_result.handoff_valid, receipt_fresh: reuse_result.receipt_fresh)
+      end
+
+      if reuse_result.decision == Reuse::REUSABLE
+        # Whole-set reuse: re-derive GateResult from reused normalized evidence through current baseline/waivers/policy.
+        # This satisfies invariants 6-9: old GateResult never becomes second authority.
+        begin
+          # Reconstruct findings as observed (state observed) for reclassification
+          reused_finding_hashes = handoff_doc.dig("evidence_set", "analyzer_results")&.flat_map { |ar| ar["findings"] || [] } || []
+          reused_findings = reused_finding_hashes.map do |fh|
+            # fh is a Finding schema hash; convert to observed Finding
+            begin
+              Finding.new(
+                fingerprint: fh["fingerprint"],
+                origin: fh["origin"] || "deterministic",
+                analyzer: fh["analyzer"],
+                rule_id: fh["rule_id"],
+                category: fh["category"] || "lint",
+                severity: fh["severity"] || "medium",
+                confidence: fh["confidence"] || "high",
+                state: "observed",
+                evidence_ref: fh["evidence_ref"] || "native:#{fh['analyzer']}:#{fh['fingerprint'][0,8]}",
+                location: fh["location"] || { "path" => fh["path"] || "unknown.rb" },
+                message: fh["message"] || "reused"
+              )
+            rescue StandardError
+              nil
+            end
+          end.compact
+
+          # Reconstruct analyzer_results for policy (finding_ids derived from findings)
+          handoff_ars = handoff_doc.dig("evidence_set", "analyzer_results") || []
+          reused_analyzer_results = handoff_ars.map do |ar|
+            fid_map = reused_findings.select { |f| f.analyzer == ar["analyzer"] }.map(&:id)
+            # Also include fingerprint mapping for policy compatibility (GateResult uses finding_ids)
+            # Use fingerprint-based ids as in original
+            AnalyzerResult.new(
+              analyzer: ar["analyzer"],
+              invocation: { "executable" => ar["analyzer"], "argv" => [] },
+              execution_status: ar["execution_status"] == "succeeded" ? "succeeded" : "succeeded",
+              finding_ids: fid_map,
+              tool_version: ar["tool_version"]
+            )
+          rescue StandardError
+            nil
+          end.compact
+
+          # Load current baseline/waivers (respect effective paths)
+          cfg = Configuration.load(effective_paths[:config]) rescue nil
+          baseline_path = effective_paths[:baseline]
+          waiver_path = effective_paths[:waivers]
+          baseline = File.file?(baseline_path) ? (Baseline.read(baseline_path) rescue nil) : nil
+          waivers = WaiverStore.read_optional(waiver_path) rescue []
+          # Comparison
+          comparison = nil
+          classified = reused_findings
+          if baseline || waivers.any?
+            cmp = Comparison.classify(findings: reused_findings, baseline: baseline, waivers: waivers.map(&:to_h), clock: Time.now.utc)
+            comparison = { "counts" => cmp.counts, "introduced" => cmp.introduced.map(&:fingerprint).sort, "existing" => cmp.existing.map(&:fingerprint).sort, "resolved" => cmp.resolved.map { |e| e.fetch("fingerprint") }.sort, "changed" => cmp.changed.map(&:fingerprint).sort, "moved" => cmp.moved.map(&:fingerprint).sort, "waived" => cmp.counts.fetch("waived", 0) == 0 ? [] : cmp.classified_findings.select { |it| it.state == "waived" }.map(&:fingerprint).sort, "orphaned_waivers" => cmp.orphaned_waivers.map { |w| w["fingerprint"] || w[:fingerprint] }.compact.sort }
+            classified = cmp.classified_findings
+          end
+
+          # Policy evaluation with current config
+          policy_result = Verification::Policy.evaluate(configuration: cfg, analyzer_results: reused_analyzer_results, findings: classified, comparison: comparison, baseline_meta: baseline ? { "loaded" => true, "path" => baseline_path } : nil, git_context: nil)
+          # Build final GateResult (reuse policy_result but attach handoff metadata)
+          gate_result = policy_result
+          # Render with handoff_reuse envelope for machine output
+          if options[:format] == "json"
+            payload = gate_result.to_schema_h
+            payload["handoff_reuse"] = { "decision" => Reuse::REUSABLE, "reasons" => reuse_result.reasons, "handoff_id" => handoff_doc["handoff_id"], "receipt_id" => handoff_doc.dig("receipt", "receipt_id"), "receipt_fresh" => true }
+            @stdout.write(JSON.generate(payload) + "\n")
+          else
+            @stdout.puts "Handoff REUSABLE: #{handoff_doc['handoff_id']} (receipt #{handoff_doc.dig('receipt','receipt_id')})"
+            @stdout.puts "Gate: #{gate_result.gate} (reused evidence, policy re-evaluated, no analyzer execution)"
+          end
+          return gate_result.gate == "FAIL" ? EXIT_POLICY_FAIL : EXIT_OK
+        rescue StandardError => e
+          @stderr.puts "handoff reuse re-evaluation failed (#{e.class}: #{e.message}); falling back to full verification"
+          outcome, interrupted = execute_check(options.reject { |k, _| k == :handoff })
+          return EXIT_NO_GATE unless render_result(outcome.result, options[:format])
+          return exit_code_for(outcome.result, interrupted: interrupted)
+        end
+      else
+        @stderr.puts "Handoff #{reuse_result.decision}: #{reuse_result.reasons.join(', ')}; executing selective verification" if options[:format] != "json"
+        # Partial reuse / selective verification through VerificationPlan
+        outcome, interrupted = execute_check(options.reject { |k, _| k == :handoff }.merge(handoff_document: handoff_doc))
+        # Annotate result with reuse info when json
+        if options[:format] == "json" && outcome.result.respond_to?(:to_schema_h)
+          @stderr.puts JSON.generate({ "handoff_reuse" => { "decision" => reuse_result.decision, "reasons" => reuse_result.reasons } })
+        end
+        return EXIT_NO_GATE unless render_result(outcome.result, options[:format])
+        return exit_code_for(outcome.result, interrupted: interrupted)
+      end
+    end
+
     def command_pr(argv)
       options = { config: DEFAULT_CONFIG_PATH, format: "console", base: nil, baseline: nil, waiver: nil }
       parser = OptionParser.new do |opts|
@@ -184,6 +327,228 @@ module RailVerdict
       EXIT_NO_GATE
     end
 
+    def command_policy(argv)
+      options = { config: DEFAULT_CONFIG_PATH, format: "console", base: nil, baseline: nil, waiver: nil, receipt: nil, handoff: nil }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict policy [--config PATH] [--format console|json] [--base REV] [--baseline PATH] [--waiver PATH] [--receipt PATH] [--handoff PATH]"
+        opts.on("--config PATH", String) { |value| options[:config] = value }
+        opts.on("--format FORMAT", String) { |value| options[:format] = value }
+        opts.on("--base REV", String) { |value| options[:base] = value }
+        opts.on("--baseline PATH", String) { |value| options[:baseline] = value }
+        opts.on("--waiver PATH", String) { |value| options[:waiver] = value }
+        opts.on("--receipt PATH", String) { |value| options[:receipt] = value }
+        opts.on("--handoff PATH", String) { |value| options[:handoff] = value }
+      end
+      parse!(parser, argv)
+      unless %w[console json].include?(options[:format])
+        raise RailVerdict::UsageError, "invalid --format #{options[:format].inspect}; expected console or json"
+      end
+      if !options[:receipt].nil? && !options[:handoff].nil?
+        raise RailVerdict::UsageError, "only one of --receipt and --handoff may be given"
+      end
+
+      outcome, interrupted = execute_check(options.merge(changed: true))
+      return EXIT_INTERRUPTED if interrupted
+      receipt = load_policy_binding(path: options[:receipt], kind: "receipt")
+      handoff = load_policy_binding(path: options[:handoff], kind: "handoff")
+      envelope = EngineeringPolicy.evaluate(outcome: outcome, receipt: receipt, handoff: handoff)
+      if options[:format] == "json"
+        @stdout.write("#{CanonicalJSON.generate(envelope)}\n")
+      else
+        @stdout.write(Reporters::EngineeringPolicy.render(envelope))
+      end
+      exit_code_for_policy(envelope, outcome)
+    rescue RailVerdict::UsageError => error
+      @stderr.puts "railverdict policy: #{error.message}"
+      @stderr.puts USAGE
+      EXIT_NO_GATE
+    rescue RailVerdict::Error => error
+      @stderr.puts "railverdict policy: #{error.message}"
+      EXIT_NO_GATE
+    end
+
+    def load_policy_binding(path:, kind:)
+      return nil if path.nil?
+      text = begin
+        File.binread(path)
+      rescue StandardError
+        raise RailVerdict::Error, "cannot read #{kind}: #{path}"
+      end
+      document, error = kind == "receipt" ? Receipt.parse(text) : Handoff.parse(text)
+      raise RailVerdict::Error, "invalid #{kind}: #{error}" if document.nil?
+      document
+    end
+
+    def exit_code_for_policy(envelope, outcome)
+      return EXIT_INTERRUPTED if outcome.result.completion_status == "interrupted"
+      case envelope["decision"]
+      when "PASS" then EXIT_OK
+      when "FAIL" then EXIT_POLICY_FAIL
+      when "REVIEW_REQUIRED" then EXIT_REVIEW_REQUIRED
+      else EXIT_NO_GATE
+      end
+    end
+    def command_review(argv)
+      if argv.first.nil? || argv.first.start_with?("-")
+        return command_review_show(argv)
+      elsif %w[-h --help help].include?(argv.first)
+        @stdout.puts "Usage: railverdict review [show|observe|complete] [options]"
+        return EXIT_OK
+      end
+      sub = argv.first
+      if sub == "show"
+        command_review_show(argv.drop(1))
+      elsif sub == "observe"
+        command_review_observe(argv.drop(1))
+      elsif sub == "complete"
+        command_review_complete(argv.drop(1))
+      else
+        raise RailVerdict::UsageError, "review requires a subcommand: show, observe, or complete"
+      end
+    rescue RailVerdict::UsageError => error
+      @stderr.puts "railverdict review: #{error.message}"
+      @stderr.puts USAGE
+      EXIT_NO_GATE
+    rescue RailVerdict::Error => error
+      @stderr.puts "railverdict review: #{error.message}"
+      EXIT_NO_GATE
+    end
+
+    def command_review_show(argv)
+      options = { config: DEFAULT_CONFIG_PATH, format: "console", base: nil, baseline: nil, waiver: nil }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict review [show] [--config PATH] [--format console|json] [--base REV] [--baseline PATH] [--waiver PATH]"
+        opts.on("--config PATH", String) { |value| options[:config] = value }
+        opts.on("--format FORMAT", String) { |value| options[:format] = value }
+        opts.on("--base REV", String) { |value| options[:base] = value }
+        opts.on("--baseline PATH", String) { |value| options[:baseline] = value }
+        opts.on("--waiver PATH", String) { |value| options[:waiver] = value }
+      end
+      parse!(parser, argv)
+      unless %w[console json].include?(options[:format])
+        raise RailVerdict::UsageError, "invalid --format #{options[:format].inspect}; expected console or json"
+      end
+
+      outcome, interrupted = execute_check(options.merge(changed: true))
+      return EXIT_INTERRUPTED if interrupted
+      packet = ReviewPacket.build(outcome: outcome)
+      if options[:format] == "json"
+        @stdout.write("#{CanonicalJSON.generate(packet)}\n")
+      else
+        @stdout.write(Reporters::Review.render_packet(packet))
+      end
+      exit_code_for_policy(EngineeringPolicy.evaluate(outcome: outcome), outcome)
+    end
+
+    def command_review_observe(argv)
+      options = { config: DEFAULT_CONFIG_PATH, format: "console", observations: [] }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict review observe --observation PATH [--observation PATH] [--config PATH] [--format console|json]"
+        opts.on("--observation PATH", String) { |value| options[:observations] << value }
+        opts.on("--config PATH", String) { |value| options[:config] = value }
+        opts.on("--format FORMAT", String) { |value| options[:format] = value }
+      end
+      parse!(parser, argv)
+      raise RailVerdict::UsageError, "observe requires --observation PATH" if options[:observations].empty?
+      raise RailVerdict::UsageError, "too many observations (max 32)" if options[:observations].length > 32
+      unless %w[console json].include?(options[:format])
+        raise RailVerdict::UsageError, "invalid --format #{options[:format].inspect}; expected console or json"
+      end
+
+      current = observe_workflow_state(config_path: options[:config])
+      verdicts = options[:observations].map do |path|
+        document = read_bounded_json(path, "observation")
+        ReviewObservation.validate(observation: document, current: current)
+      end
+      if options[:format] == "json"
+        @stdout.write("#{CanonicalJSON.generate({ 'observations' => verdicts })}\n")
+      else
+        @stdout.write(Reporters::Review.render_observations(verdicts))
+      end
+      verdicts.all? { |verdict| verdict["status"] == "valid_bound" } ? EXIT_OK : EXIT_NO_GATE
+    end
+
+    def command_review_complete(argv)
+      options = { config: DEFAULT_CONFIG_PATH, format: "console", base: nil, baseline: nil, waiver: nil, observations: [] }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict review complete [--observation PATH] [--config PATH] [--format console|json] [--base REV] [--baseline PATH] [--waiver PATH]"
+        opts.on("--observation PATH", String) { |value| options[:observations] << value }
+        opts.on("--config PATH", String) { |value| options[:config] = value }
+        opts.on("--format FORMAT", String) { |value| options[:format] = value }
+        opts.on("--base REV", String) { |value| options[:base] = value }
+        opts.on("--baseline PATH", String) { |value| options[:baseline] = value }
+        opts.on("--waiver PATH", String) { |value| options[:waiver] = value }
+      end
+      parse!(parser, argv)
+      raise RailVerdict::UsageError, "too many observations (max 32)" if options[:observations].length > 32
+      unless %w[console json].include?(options[:format])
+        raise RailVerdict::UsageError, "invalid --format #{options[:format].inspect}; expected console or json"
+      end
+
+      outcome, interrupted = execute_check(options.merge(changed: true))
+      return EXIT_INTERRUPTED if interrupted
+      packet = ReviewPacket.build(outcome: outcome)
+      policy = EngineeringPolicy.evaluate(outcome: outcome)
+      current = {
+        "head" => packet["provenance"]["head"],
+        "configuration_digest" => packet["provenance"]["configuration_digest"],
+        "policy_digest" => policy["policy_digest"]
+      }
+      validated = options[:observations].map do |path|
+        document = read_bounded_json(path, "observation")
+        verdict = ReviewObservation.validate(observation: document, current: current)
+        { "observation_id" => verdict["observation_id"].to_s,
+          "author" => document.is_a?(Hash) ? document["author"].to_s : "unknown",
+          "binding" => verdict["status"] }
+      end
+      receipt = WorkflowReceipt.build(packet: packet, policy_decision: policy["decision"],
+        gate: outcome.result.gate, observations: validated)
+      if options[:format] == "json"
+        @stdout.write("#{CanonicalJSON.generate(receipt)}\n")
+      else
+        @stdout.write(Reporters::Review.render_workflow(receipt))
+      end
+      exit_code_for_readiness(receipt["readiness"])
+    end
+
+    def observe_workflow_state(config_path:)
+      configuration = Configuration.load(resolved_override_path(config_path, File.join(@working_directory, DEFAULT_CONFIG_PATH)))
+      head = begin
+        output, _, status = Open3.capture3("git", "rev-parse", "HEAD", chdir: @working_directory)
+        status.success? ? output.strip : nil
+      rescue StandardError
+        nil
+      end
+      {
+        "head" => head,
+        "configuration_digest" => configuration.digest,
+        "policy_digest" => EngineeringPolicy.policy_digest(EngineeringPolicy.effective_policy(configuration))
+      }
+    end
+
+    def read_bounded_json(path, kind)
+      text = begin
+        File.binread(path)
+      rescue StandardError
+        raise RailVerdict::Error, "cannot read #{kind}: #{path}"
+      end
+      raise RailVerdict::Error, "#{kind} exceeds 256 KiB: #{path}" if text.bytesize > 256 * 1024
+      begin
+        JSON.parse(text)
+      rescue JSON::ParserError
+        raise RailVerdict::Error, "invalid #{kind} JSON: #{path}"
+      end
+    end
+
+    def exit_code_for_readiness(readiness)
+      case readiness
+      when "ready" then EXIT_OK
+      when "blocked_by_gate" then EXIT_POLICY_FAIL
+      when "review_pending" then EXIT_REVIEW_REQUIRED
+      else EXIT_NO_GATE
+      end
+    end
+
     def command_baseline(argv)
       subcommand = argv.first
       raise RailVerdict::UsageError, "unknown baseline subcommand: #{subcommand.inspect}; only `baseline create` exists" unless subcommand == "create"
@@ -290,6 +655,7 @@ module RailVerdict
       execute_options[:baseline_path_override] = options[:output] if options.key?(:output) && options[:output]
       execute_options[:changed] = options[:changed] if options.key?(:changed)
       execute_options[:base] = options[:base] if options.key?(:base)
+      execute_options[:handoff_document] = options[:handoff_document] if options.key?(:handoff_document) && options[:handoff_document]
       outcome = Check.execute(**execute_options)
       [outcome, interrupted]
     ensure
@@ -444,6 +810,7 @@ module RailVerdict
     end
 
     def command_repair(argv)
+      return command_repair_verify(argv.drop(1)) if argv.first == "verify"
       finding_ref = argv.first
       raise RailVerdict::UsageError, "repair requires a finding id or fingerprint" unless finding_ref && !finding_ref.start_with?("-")
 
@@ -483,6 +850,64 @@ module RailVerdict
       EXIT_NO_GATE
     end
 
+    def command_repair_verify(argv)
+      options = { config: DEFAULT_CONFIG_PATH, format: "console", packet: nil, changed: false, base: nil, baseline: nil, waiver: nil }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict repair verify --packet PATH [--config PATH] [--format console|json] [--changed] [--base REV] [--baseline PATH] [--waiver PATH]"
+        opts.on("--packet PATH", String) { |v| options[:packet] = v }
+        opts.on("--config PATH", String) { |v| options[:config] = v }
+        opts.on("--format FORMAT", String) { |v| options[:format] = v }
+        opts.on("--changed") { options[:changed] = true }
+        opts.on("--base REV", String) { |v| options[:base] = v }
+        opts.on("--baseline PATH", String) { |v| options[:baseline] = v }
+        opts.on("--waiver PATH", String) { |v| options[:waiver] = v }
+      end
+      parse!(parser, argv)
+      raise RailVerdict::UsageError, "repair verify requires --packet PATH" if options[:packet].nil?
+      raise RailVerdict::UsageError, "--base requires --changed" if options[:base] && !options[:changed]
+      unless %w[console json].include?(options[:format])
+        raise RailVerdict::UsageError, "invalid --format #{options[:format].inspect}; expected console or json"
+      end
+
+      packet = read_bounded_json(options[:packet], "repair packet")
+      raise RailVerdict::Error, "invalid repair packet: not a document" unless packet.is_a?(Hash)
+      errors = SchemaValidator.validate_repair_packet(packet)
+      raise RailVerdict::Error, "invalid repair packet: #{errors.first}" unless errors.empty?
+
+      outcome, interrupted = execute_check(options.merge(changed: options[:changed] || !options[:base].nil?))
+      return EXIT_INTERRUPTED if interrupted
+      result = Repair::Verifier.verify(packet: packet, new_outcome: outcome)
+      if options[:format] == "json"
+        @stdout.write("#{CanonicalJSON.generate(verifier_result_h(result))}\n")
+      else
+        @stdout.write(Reporters::Review.render_repair_verify(result))
+      end
+      case result.overall_status
+      when "successful" then EXIT_OK
+      when "unsuccessful" then EXIT_POLICY_FAIL
+      else EXIT_NO_GATE
+      end
+    rescue RailVerdict::UsageError => error
+      @stderr.puts "railverdict repair verify: #{error.message}"
+      @stderr.puts USAGE
+      EXIT_NO_GATE
+    rescue RailVerdict::Error => error
+      @stderr.puts "railverdict repair verify: #{error.message}"
+      EXIT_NO_GATE
+    end
+
+    def verifier_result_h(result)
+      {
+        "target_status" => result.target_status,
+        "gate" => result.gate,
+        "completion_status" => result.completion_status,
+        "new_blocking_findings" => result.new_blocking_findings,
+        "verification_boundary_changed" => result.verification_boundary_changed,
+        "regressed" => result.regressed,
+        "overall_status" => result.overall_status
+      }
+    end
+
     def command_receipt(argv)
       sub = argv.first
       raise RailVerdict::UsageError, "receipt requires a subcommand: create or verify" unless %w[create verify].include?(sub)
@@ -711,6 +1136,216 @@ module RailVerdict
       end
     end
 
+    def command_handoff(argv)
+      sub = argv.first
+      raise RailVerdict::UsageError, "handoff requires a subcommand: create, inspect, or verify" unless %w[create inspect verify].include?(sub)
+
+      case sub
+      when "create" then command_handoff_create(argv.drop(1))
+      when "inspect" then command_handoff_inspect(argv.drop(1))
+      when "verify" then command_handoff_verify(argv.drop(1))
+      end
+    rescue RailVerdict::UsageError => e
+      @stderr.puts "railverdict handoff: #{e.message}"
+      @stderr.puts handoff_usage
+      EXIT_NO_GATE
+    end
+
+    def handoff_usage
+      <<~USAGE
+        Usage: railverdict handoff create [options]
+               railverdict handoff inspect PATH [options]
+               railverdict handoff verify PATH [options]
+
+        Create options:
+          --config PATH, --format console|json, --output PATH
+          --changed --base REV --baseline PATH --waiver PATH
+
+        Inspect options:
+          --format console|json
+
+        Verify options:
+          --format console|json
+          --config PATH, --baseline PATH, --waiver PATH
+      USAGE
+    end
+
+    def command_handoff_create(argv)
+      options = { config: DEFAULT_CONFIG_PATH, format: "json", output: nil, changed: false, base: nil, baseline: nil, waiver: nil }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict handoff create [--config PATH] [--format console|json] [--output PATH] [--changed] [--base REV] [--baseline PATH] [--waiver PATH]"
+        opts.on("--config PATH", String) { |v| options[:config] = v }
+        opts.on("--format FORMAT", String) { |v| options[:format] = v }
+        opts.on("--output PATH", String) { |v| options[:output] = v }
+        opts.on("--changed") { options[:changed] = true }
+        opts.on("--base REV", String) { |v| options[:base] = v }
+        opts.on("--baseline PATH", String) { |v| options[:baseline] = v }
+        opts.on("--waiver PATH", String) { |v| options[:waiver] = v }
+      end
+      parse!(parser, argv)
+      raise RailVerdict::UsageError, "--base requires --changed" if options[:base] && !options[:changed]
+      unless %w[console json].include?(options[:format])
+        raise RailVerdict::UsageError, "invalid --format #{options[:format].inspect}; expected console or json"
+      end
+      options[:config] = resolved_override_path(options[:config], File.join(@working_directory, DEFAULT_CONFIG_PATH))
+      options[:baseline] = resolved_override_path(options[:baseline], nil) if options[:baseline]
+      options[:waiver] = resolved_override_path(options[:waiver], nil) if options[:waiver]
+
+      outcome, interrupted = execute_check_with_guard(options)
+      return EXIT_INTERRUPTED if interrupted || outcome.result.completion_status == "interrupted"
+
+      receipt = Receipt.build(outcome: outcome, pr_intelligence_document: pr_intelligence_document_for(outcome))
+      evidence_set = {
+        "analyzer_results" => outcome.result.analyzer_results.map do |ar|
+          h = { "analyzer" => ar.analyzer, "execution_status" => ar.execution_status, "tool_version" => ar.tool_version }
+          # Include normalized findings for reuse (bounded) — use canonical Finding hashes
+          findings = outcome.findings.select { |f| f.analyzer == ar.analyzer }.map(&:to_schema_h).sort_by { |ff| ff["fingerprint"] }
+          h["findings"] = findings if findings.any?
+          h
+        end
+      }
+      provenance = { "analyzer_versions" => outcome.context&.analyzer_versions || {} }
+      scope = {
+        "verification_mode" => outcome.result.git ? "changed" : "full",
+        "changed_base" => outcome.result.git && outcome.result.git["base"],
+        "changed_merge_base" => outcome.result.git && outcome.result.git["merge_base"]
+      }
+      handoff = Handoff.build(receipt: receipt, evidence_set: evidence_set, evidence_provenance: provenance, source_scope: scope)
+      write_handoff_file(handoff, options[:output]) if options[:output]
+      render_handoff(handoff, options[:format], output_path: options[:output])
+      exit_code_for(outcome.result, interrupted: interrupted)
+    rescue Handoff::BuildError, Receipt::BuildError => e
+      payload = { "status" => "unavailable", "reasons" => ["#{e.code}: #{e.message}"] }
+      render_handoff_unavailable(payload, options && options[:format])
+      EXIT_NO_GATE
+    end
+
+    def command_handoff_inspect(argv)
+      options = { format: "json" }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict handoff inspect PATH [--format console|json]"
+        opts.on("--format FORMAT", String) { |v| options[:format] = v }
+      end
+      rest = begin parser.parse(argv.dup) rescue raise RailVerdict::UsageError, $!.message end
+      path = rest.first
+      raise RailVerdict::UsageError, "inspect requires the handoff file path" if path.nil?
+      unless %w[console json].include?(options[:format])
+        raise RailVerdict::UsageError, "invalid --format #{options[:format].inspect}"
+      end
+      text = begin File.binread(path) rescue (@stderr.puts "railverdict handoff inspect: cannot read handoff: #{$!.message}"; return EXIT_NO_GATE) end
+      doc, err = Handoff.parse(text)
+      if doc
+        render_handoff(doc, options[:format])
+        EXIT_OK
+      else
+        payload = { "status" => "invalid", "reasons" => [err.to_s] }
+        render_handoff_unavailable(payload, options[:format])
+        EXIT_NO_GATE
+      end
+    end
+
+    def command_handoff_verify(argv)
+      options = { format: "json", config: DEFAULT_CONFIG_PATH, baseline: nil, waiver: nil }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: railverdict handoff verify PATH [--format console|json] [--config PATH] [--baseline PATH] [--waiver PATH]"
+        opts.on("--format FORMAT", String) { |v| options[:format] = v }
+        opts.on("--config PATH", String) { |v| options[:config] = v }
+        opts.on("--baseline PATH", String) { |v| options[:baseline] = v }
+        opts.on("--waiver PATH", String) { |v| options[:waiver] = v }
+      end
+      rest = begin parser.parse(argv.dup) rescue raise RailVerdict::UsageError, $!.message end
+      path = rest.first
+      raise RailVerdict::UsageError, "verify requires the handoff file path" if path.nil?
+      unless %w[console json].include?(options[:format])
+        raise RailVerdict::UsageError, "invalid --format #{options[:format].inspect}"
+      end
+      text = begin File.binread(path) rescue (@stderr.puts "railverdict handoff verify: cannot read handoff: #{$!.message}"; return EXIT_NO_GATE) end
+      doc, err = Handoff.parse(text)
+      unless doc
+        payload = { "handoff_valid" => false, "receipt_fresh" => false, "decision" => Reuse::INVALID, "reasons" => [err.to_s] }
+        render_handoff_verify(payload, options[:format])
+        return EXIT_NO_GATE
+      end
+      effective_paths = Check.effective_input_paths(root: @working_directory, config_path: resolved_override_path(options[:config], File.join(@working_directory, DEFAULT_CONFIG_PATH)), baseline_path_override: options[:baseline] && resolved_override_path(options[:baseline], nil), waiver_path_override: options[:waiver] && resolved_override_path(options[:waiver], nil))
+      before_state = RepositoryState.capture(repository_root: @working_directory, configuration_paths: effective_paths)
+      current_state = before_state
+      current_env_obj = VerificationEnvironment.capture(repository_root: @working_directory)
+      current_env = {
+        "ruby_engine" => current_env_obj.ruby_engine,
+        "ruby_version" => current_env_obj.ruby_version,
+        "railverdict_version" => current_env_obj.railverdict_version,
+        "analyzer_versions" => current_env_obj.analyzer_versions
+      }
+      # Evaluate via canonical Reuse
+      config = Configuration.load(effective_paths[:config]) rescue nil
+      required = config ? config.analyzers.select { |_, s| s["enabled"] && s["required"] }.keys.map(&:to_s) : []
+      contract = { "required_analyzers" => required, "verification_mode" => doc.dig("source_scope", "verification_mode"), "changed_base" => doc.dig("source_scope", "changed_base") }
+      result = Reuse.evaluate(handoff_document: doc, current_repository_state: current_state, current_environment: current_env, current_contract: contract)
+      # TOCTOU guard: re-observe repository state
+      after_state = RepositoryState.capture(repository_root: @working_directory, configuration_paths: effective_paths)
+      if before_state && after_state && before_state.digest != after_state.digest
+        result = Reuse::Result.new(decision: Reuse::VERIFICATION_REQUIRED, reasons: result.reasons + ["reuse_toctou"], handoff_valid: result.handoff_valid, receipt_fresh: result.receipt_fresh)
+      end
+      payload = { "handoff_valid" => result.handoff_valid, "receipt_fresh" => result.receipt_fresh, "decision" => result.decision, "reasons" => result.reasons, "handoff_id" => doc["handoff_id"], "receipt_id" => doc.dig("receipt", "receipt_id") }
+      render_handoff_verify(payload, options[:format])
+      result.decision == Reuse::REUSABLE ? EXIT_OK : EXIT_NO_GATE
+    end
+
+    def capture_current_env
+      # Minimal env capture for reuse freshness — reuse VerificationEnvironment where possible
+      begin
+        VerificationEnvironment.capture(repository_root: @working_directory)
+      rescue StandardError
+        { "ruby_engine" => RUBY_ENGINE, "ruby_version" => RUBY_VERSION, "railverdict_version" => RailVerdict::VERSION, "analyzer_versions" => {} }
+      end
+    end
+
+    def write_handoff_file(document, path)
+      dir = File.dirname(File.expand_path(path))
+      FileUtils.mkdir_p(dir)
+      tmp = File.join(dir, ".#{File.basename(path)}.tmp.#{Process.pid}.#{SecureRandom.hex(8)}")
+      begin
+        File.open(tmp, "wb", 0o600) do |file|
+          file.write(JSON.generate(document) + "\n")
+          file.flush
+          file.fsync
+        end
+        File.rename(tmp, path)
+      ensure
+        File.unlink(tmp) if File.exist?(tmp)
+      end
+    end
+
+    def render_handoff(document, format, output_path: nil)
+      if format == "json"
+        @stdout.write(JSON.generate(document) + "\n")
+      else
+        @stdout.puts "Handoff: #{document['handoff_id']}"
+        @stdout.puts "Receipt: #{document.dig('receipt', 'receipt_id')}"
+        @stdout.puts "Evidence analyzers: #{Array(document.dig('evidence_set', 'analyzer_results')).map { |ar| ar['analyzer'] }.join(', ')}"
+        @stdout.puts "Written to #{output_path}" if output_path
+      end
+    end
+
+    def render_handoff_unavailable(payload, format)
+      if format == "json"
+        @stdout.write(JSON.generate(payload) + "\n")
+      else
+        @stdout.puts "Handoff unavailable: #{payload['reasons'].join('; ')}"
+      end
+    end
+
+    def render_handoff_verify(payload, format)
+      if format == "json"
+        @stdout.write(JSON.generate(payload) + "\n")
+      else
+        @stdout.puts "Handoff: #{payload['handoff_id']} valid=#{payload['handoff_valid']}"
+        @stdout.puts "Receipt fresh: #{payload['receipt_fresh']}"
+        @stdout.puts "Decision: #{payload['decision']}"
+        @stdout.puts "Reasons: #{payload['reasons'].join(', ')}" unless payload["reasons"].empty?
+      end
+    end
+
     def command_mcp(argv)
       sub = argv.first
       raise RailVerdict::UsageError, "mcp requires subcommand: serve" unless sub == "serve"