rail_verdict 1.3.0 → 1.8.2

data/lib/rail_verdict/mcp/tools/inspect_handoff.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module MCP
+    module Tools
+      class InspectHandoff
+        def initialize(server:)
+          @server = server
+        end
+
+        def tool_name
+          "inspect_handoff"
+        end
+
+        def tool_title
+          "Inspect verification handoff"
+        end
+
+        def tool_description
+          "Parse and validate a Verification Handoff. Bounded, deterministic, tamper-detected via handoff_id. Does not execute analyzers."
+        end
+
+        def tool_input_schema
+          {
+            type: "object",
+            properties: {
+              handoff: { type: "object", description: "Handoff document to inspect" },
+              handoff_json: { type: "string", description: "Handoff JSON string (alternative to handoff object)" }
+            },
+            additionalProperties: false
+          }
+        end
+
+        def tool_output_schema
+          {
+            type: "object",
+            properties: {
+              valid: { type: "boolean" },
+              handoff: { type: ["object", "null"] },
+              error: { type: "string" },
+              handoff_id: { type: "string" }
+            },
+            required: %w[valid]
+          }
+        end
+
+        def tool_annotations
+          { read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false, title: tool_title }
+        end
+
+        def call(handoff: nil, handoff_json: nil, **_rest)
+          text = if handoff_json && !handoff_json.to_s.strip.empty?
+                   handoff_json.to_s
+                 elsif handoff
+                   JSON.generate(handoff)
+                 else
+                   return Serializers.error_response("handoff or handoff_json is required", code: "invalid_arguments")
+                 end
+          return Serializers.error_response("handoff too large", code: "handoff_too_large") if text.bytesize > Handoff::MAX_DOCUMENT_BYTES
+          doc, err = Handoff.parse(text)
+          if doc
+            Serializers.tool_response({ "valid" => true, "handoff" => Serializers.scrub(doc), "handoff_id" => doc["handoff_id"] }, error: false)
+          else
+            Serializers.tool_response({ "valid" => false, "error" => err.to_s, "handoff" => nil }, error: false)
+          end
+        rescue StandardError => e
+          Serializers.error_response("inspect_handoff failed: #{e.message}", code: "internal_error")
+        end
+      end
+    end
+  end
+end

data/lib/rail_verdict/mcp/tools/verify_handoff.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module MCP
+    module Tools
+      class VerifyHandoff
+        def initialize(server:)
+          @server = server
+        end
+
+        def tool_name
+          "verify_handoff"
+        end
+
+        def tool_title
+          "Verify handoff reuse"
+        end
+
+        def tool_description
+          "Evaluate whether a Verification Handoff is REUSABLE under current repository state/environment. Re-observes state/environment independently, never trusts Handoff. Returns REUSABLE or VERIFICATION_REQUIRED with reasons. Does not execute analyzers."
+        end
+
+        def tool_input_schema
+          {
+            type: "object",
+            properties: {
+              handoff: { type: "object", description: "Handoff document" },
+              handoff_json: { type: "string", description: "Handoff JSON string" },
+              config_path: { type: "string" },
+              baseline_path: { type: "string" },
+              waiver_path: { type: "string" }
+            },
+            additionalProperties: false
+          }
+        end
+
+        def tool_output_schema
+          {
+            type: "object",
+            properties: {
+              handoff_valid: { type: "boolean" },
+              receipt_fresh: { type: "boolean" },
+              decision: { type: "string", enum: %w[REUSABLE VERIFICATION_REQUIRED INVALID UNAVAILABLE] },
+              reasons: { type: "array" },
+              handoff_id: { type: "string" },
+              receipt_id: { type: "string" }
+            },
+            required: %w[decision]
+          }
+        end
+
+        def tool_annotations
+          { read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false, title: tool_title }
+        end
+
+        def call(handoff: nil, handoff_json: nil, config_path: nil, baseline_path: nil, waiver_path: nil, **_rest)
+          text = if handoff_json && !handoff_json.to_s.strip.empty?
+                   handoff_json.to_s
+                 elsif handoff
+                   JSON.generate(handoff)
+                 else
+                   return Serializers.error_response("handoff or handoff_json required", code: "invalid_arguments")
+                 end
+          return Serializers.error_response("handoff too large", code: "handoff_too_large") if text.bytesize > Handoff::MAX_DOCUMENT_BYTES
+          doc, err = Handoff.parse(text)
+          unless doc
+            return Serializers.tool_response({ "handoff_valid" => false, "receipt_fresh" => false, "decision" => Reuse::INVALID, "reasons" => [err.to_s] }, error: false)
+          end
+
+          root = @server.repository_root
+          effective_paths = Check.effective_input_paths(root: File.realpath(root), config_path: resolve_config_path(config_path), baseline_path_override: resolve_contained_path(baseline_path, "baseline_path"), waiver_path_override: resolve_contained_path(waiver_path, "waiver_path"))
+          before_state = RepositoryState.capture(repository_root: root, configuration_paths: effective_paths)
+          current_env_obj = VerificationEnvironment.capture(repository_root: root)
+          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" => doc.dig("source_scope", "verification_mode"), "changed_base" => doc.dig("source_scope", "changed_base") }
+          result = Reuse.evaluate(handoff_document: doc, current_repository_state: before_state, current_environment: current_env, current_contract: contract)
+          after_state = RepositoryState.capture(repository_root: root, 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
+          Serializers.tool_response({ "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") }, error: false)
+        rescue ArgumentError => e
+          Serializers.error_response(e.message, code: "invalid_arguments")
+        rescue StandardError => e
+          Serializers.error_response("verify_handoff failed: #{e.message}", code: "internal_error")
+        end
+
+        private
+
+        def resolve_contained_path(raw_path, field_name)
+          return nil if raw_path.nil? || raw_path.to_s.strip.empty?
+          raw = raw_path.to_s.strip
+          raise ArgumentError, "#{field_name} contains NUL byte" if raw.include?("\u0000")
+          expanded = File.expand_path(raw, @server.repository_root)
+          raise ArgumentError, "#{field_name} escapes repository root" unless RepositoryRoot.contained?(@server.repository_root, expanded)
+          expanded
+        end
+
+        def resolve_config_path(config_path)
+          return File.join(@server.repository_root, ".railverdict.yml") if config_path.nil? || config_path.to_s.strip.empty?
+          raw = config_path.to_s.strip
+          raise ArgumentError, "config_path contains NUL byte" if raw.include?("\u0000")
+          expanded = File.expand_path(raw, @server.repository_root)
+          raise ArgumentError, "config_path escapes repository root" unless RepositoryRoot.contained?(@server.repository_root, expanded)
+          expanded
+        end
+      end
+    end
+  end
+end

data/lib/rail_verdict/mcp/tools/verify_review_observation.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "../serializers"
+
+module RailVerdict
+  module MCP
+    module Tools
+      # Validate an outside observation against freshly re-observed state.
+      # Gate-neutral by construction: proves reference to a state, never
+      # correctness of the conclusion, and alters nothing.
+      class VerifyReviewObservation
+        MAX_OBSERVATION_BYTES = 256 * 1024
+
+        def initialize(server:)
+          @server = server
+        end
+
+        def tool_name
+          "verify_review_observation"
+        end
+
+        def tool_title
+          "Verify review observation"
+        end
+
+        def tool_description
+          "Validate a review observation document against the current repository state, configuration, and policy. Returns valid_bound, stale, untrusted, invalid, or unavailable. Validation never changes any gate, requirement, finding, receipt, or handoff."
+        end
+
+        def tool_input_schema
+          {
+            type: "object",
+            properties: {
+              observation: { type: "object" }
+            },
+            required: %w[observation],
+            additionalProperties: false
+          }
+        end
+
+        def tool_output_schema
+          {
+            type: "object",
+            properties: {
+              status: { type: "string", enum: %w[valid_bound stale untrusted invalid unavailable] },
+              observation_id: { type: ["string", "null"] },
+              code: { type: "string" },
+              message: { type: "string" }
+            },
+            required: %w[status]
+          }
+        end
+
+        def tool_annotations
+          { read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false, title: tool_title }
+        end
+
+        def call(observation: nil, **_rest)
+          unless observation.is_a?(Hash)
+            return Serializers.tool_response(
+              { "status" => "invalid", "code" => "observation_malformed",
+                "message" => "observation must be an object" }, error: false)
+          end
+          begin
+            normalized = JSON.parse(JSON.generate(observation))
+          rescue StandardError
+            return Serializers.tool_response(
+              { "status" => "invalid", "code" => "observation_malformed",
+                "message" => "observation is not JSON-serializable" }, error: false)
+          end
+          if JSON.generate(normalized).bytesize > MAX_OBSERVATION_BYTES
+            return Serializers.tool_response(
+              { "status" => "invalid", "code" => "observation_too_large",
+                "message" => "observation exceeds 256 KiB" }, error: false)
+          end
+          observation = normalized
+
+          root = @server.repository_root
+          outcome = begin
+            @server.cache.fetch_outcome
+          rescue StandardError
+            nil
+          end
+          configuration = outcome&.configuration
+          if configuration.nil?
+            begin
+              configuration = RailVerdict::Configuration.load(File.join(File.realpath(root), ".railverdict.yml"))
+            rescue StandardError
+              configuration = nil
+            end
+          end
+          if configuration.nil?
+            return Serializers.tool_response(
+              { "status" => "unavailable", "code" => "observation_configuration_unavailable",
+                "message" => "observation binding requires a readable configuration file" }, error: false)
+          end
+
+          effective_paths = begin
+            RailVerdict::Check.effective_input_paths(root: File.realpath(root), config_path: File.join(File.realpath(root), ".railverdict.yml"))
+          rescue StandardError
+            nil
+          end
+          current_state = RailVerdict::RepositoryState.capture(repository_root: root, configuration_paths: effective_paths)
+          components = current_state.projection&.fetch("components", nil)
+          head = components.is_a?(Hash) ? components["head"] : nil
+          current = {
+            "head" => head,
+            "configuration_digest" => configuration.digest,
+            "policy_digest" => RailVerdict::EngineeringPolicy.policy_digest(
+              RailVerdict::EngineeringPolicy.effective_policy(configuration))
+          }
+          verdict = RailVerdict::ReviewObservation.validate(observation: observation, current: current)
+          Serializers.tool_response(Serializers.scrub(verdict), error: false)
+        rescue StandardError => e
+          Serializers.error_response("verify_review_observation failed: #{e.message}", code: "internal_error")
+        end
+      end
+    end
+  end
+end

data/lib/rail_verdict/mcp.rb

@@ -5,3 +5,15 @@ require_relative "mcp/validators"
 require_relative "mcp/serializers"
 require_relative "mcp/cache"
 require_relative "mcp/server"
+require_relative "mcp/tools/verify"
+require_relative "mcp/tools/list_findings"
+require_relative "mcp/tools/get_finding"
+require_relative "mcp/tools/build_repair_packet"
+require_relative "mcp/tools/verify_repair"
+require_relative "mcp/tools/explain"
+require_relative "mcp/tools/investigate"
+require_relative "mcp/tools/get_verification_receipt"
+require_relative "mcp/tools/get_pr_intelligence"
+require_relative "mcp/tools/create_handoff"
+require_relative "mcp/tools/inspect_handoff"
+require_relative "mcp/tools/verify_handoff"

data/lib/rail_verdict/pr_intelligence.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "change_surfaces"
+require_relative "change_intelligence"
 
 module RailVerdict
   module PRIntelligence
-    SCHEMA_VERSION = "1.0"
+    SCHEMA_VERSION = "1.1"
+    PREVIOUS_SCHEMA_VERSION = "1.0"
     MAX_SIGNAL_EVIDENCE = 20
     SIGNALS = {
       "database_change" => lambda { |path| path == "db/schema.rb" || path == "db/structure.sql" || path.start_with?("db/migrate/") },
@@ -23,10 +26,25 @@ module RailVerdict
 
     module_function
 
+    # Canonical change intelligence model. v1.0 keys are unchanged; v1.1
+    # appends surfaces, review signals/risk, verification scope,
+    # missing evidence, and review focus. Read-only over the outcome:
+    # GateResult authority is never touched here.
     def document(outcome)
       result = outcome.result
       git_context = outcome.context&.git_context
       git = result.git || {}
+      paths = ChangeIntelligence.changed_paths(git_context)
+      available = !git_context.nil?
+      review_config = outcome.respond_to?(:configuration) ? outcome.configuration&.review_config : nil
+      review_config = {} unless review_config.is_a?(Hash)
+      surfaces = ChangeSurfaces.detect(paths, available: available)
+      project_areas = ChangeSurfaces.project_sensitive(
+        paths, review_config["sensitive_paths"], available: available
+      )
+      change_signals = review_signals(surfaces, project_areas)
+      scope = verification_scope(outcome, git_context)
+      missing = ChangeIntelligence.missing_evidence(outcome, surfaces, scope)
 
       document = {
         "schema_version" => SCHEMA_VERSION,
@@ -34,6 +52,13 @@ module RailVerdict
         "gate_result" => gate_result(result),
         "change" => change(git_context),
         "signals" => signals(git_context),
+        "surfaces" => surfaces,
+        "project_sensitive_areas" => project_areas,
+        "review_signals" => change_signals,
+        "review_risk" => ChangeIntelligence.review_risk(change_signals, review_config["risk"]),
+        "verification_scope" => scope,
+        "missing_evidence" => missing,
+        "review_focus" => ChangeIntelligence.review_focus(surfaces, project_areas, available ? paths : []),
         "quality_delta" => quality_delta(result),
         "analyzer_evidence" => analyzer_evidence(result),
         "test_intelligence" => test_intelligence(result),
@@ -74,6 +99,19 @@ module RailVerdict
       end
     end
 
+    def review_signals(surfaces, project_areas)
+      ChangeIntelligence.review_signals(surfaces, project_areas)
+    end
+    private_class_method :review_signals
+
+    def verification_scope(outcome, git_context)
+      context = outcome.context
+      root = context.respond_to?(:repository_root) ? context.repository_root : nil
+      ChangeIntelligence.verification_scope(outcome.result, repository_root: root, git_context: git_context)
+    end
+    private_class_method :verification_scope
+
+
     def provenance(outcome, git_context, git)
       context = outcome.context
       {

data/lib/rail_verdict/rails_context/resolvers/test_candidates.rb

@@ -5,7 +5,7 @@ module RailVerdict
     module Resolvers
       module TestCandidates
         def self.for(repository_root:, kind:, path:)
-          basename = File.basename(path, ".rb")
+          basename = File.basename(path, ".*")
           dir = File.dirname(path)
           candidates = []
 
@@ -20,6 +20,7 @@ module RailVerdict
             candidates << candidate_path(repository_root, "test", "controllers", relative, basename)
             candidates << candidate_path(repository_root, "spec", "requests", relative, clean)
             candidates << candidate_path(repository_root, "spec", "controllers", relative, basename)
+            candidates << candidate_path(repository_root, "spec", "requests", relative, "#{clean}_spec")
           when "job"
             relative = dir.delete_prefix("app/jobs").delete_prefix("/")
             candidates << candidate_path(repository_root, "test", "jobs", relative, basename)
@@ -36,19 +37,52 @@ module RailVerdict
             relative = dir.delete_prefix("app/services").delete_prefix("/")
             candidates << candidate_path(repository_root, "test", "services", relative, basename)
             candidates << candidate_path(repository_root, "spec", "services", relative, basename)
+          when "policy"
+            clean = basename.delete_suffix("_policy")
+            relative = dir.delete_prefix("app/policies").delete_prefix("/")
+            candidates << candidate_path(repository_root, "test", "policies", relative, basename)
+            candidates << candidate_path(repository_root, "spec", "policies", relative, basename)
+            candidates << candidate_path(repository_root, "spec", "policies", relative, clean)
+          when "component"
+            clean = basename.delete_suffix("_component")
+            relative = dir.delete_prefix("app/components").delete_prefix("/")
+            candidates << candidate_path(repository_root, "test", "components", relative, basename)
+            candidates << candidate_path(repository_root, "spec", "components", relative, basename)
+            candidates << candidate_path(repository_root, "spec", "components", relative, clean)
+          when "view"
+            relative = dir.delete_prefix("app/views").delete_prefix("/")
+            controller_dir = relative.split("/").first
+            candidates << candidate_path(repository_root, "spec", "views", relative, basename)
+            candidates << candidate_path(repository_root, "spec", "system", controller_dir || "", "#{controller_dir}_spec") if controller_dir
+            candidates << candidate_path(repository_root, "spec", "requests", controller_dir || "", "#{controller_dir}_spec") if controller_dir
+          when "lib"
+            relative = dir.delete_prefix("lib").delete_prefix("/")
+            candidates << candidate_path(repository_root, "spec", "lib", relative, basename)
+            candidates << candidate_path(repository_root, "spec", "", relative, basename)
+            candidates << candidate_path(repository_root, "test", "lib", relative, basename)
+            candidates << candidate_path(repository_root, "test", "", relative, basename)
+          when "spec"
+            if path.end_with?("_spec.rb") && safe_exists?(repository_root, File.join(repository_root, path))
+              candidates << { path: path, exists: true }
+            end
+          when "test"
+            if path.end_with?("_test.rb") && safe_exists?(repository_root, File.join(repository_root, path))
+              candidates << { path: path, exists: true }
+            end
           else
             return []
           end
 
-          candidates.compact.select { |entry| entry[:exists] }.first(2).map do |entry|
+          candidates.compact.select { |entry| entry[:exists] }.map do |entry|
             { "path" => entry[:path], "relationship" => "related_test", "confidence" => "conventional", "provenance" => "file_exists:#{entry[:path]}" }
           end
         end
 
         def self.candidate_path(root, framework, kind_dir, relative, basename)
           rel = relative.empty? ? "" : "#{relative}/"
-          filename = framework == "test" ? "#{basename}_test.rb" : "#{basename}_spec.rb"
-          repo_relative = "#{framework}/#{kind_dir}/#{rel}#{filename}".gsub(%r{//+}, "/")
+          clean_base = basename.delete_suffix("_spec").delete_suffix("_test")
+          filename = framework == "test" ? "#{clean_base}_test.rb" : "#{clean_base}_spec.rb"
+          repo_relative = "#{framework}/#{kind_dir}/#{rel}#{filename}".gsub(%r{//+}, "/").delete_prefix("/")
           full = File.join(root, repo_relative)
           exists = safe_exists?(root, full)
           return nil unless exists

data/lib/rail_verdict/repair/verification_plan.rb

@@ -6,7 +6,39 @@ module RailVerdict
       def self.build(outcome:, repository_root: nil, base_revision: nil)
         required = [required_check(base_revision: base_revision)]
         suggested = suggested_commands(outcome)
-        { "required" => required, "suggested" => suggested }
+        plan = { "required" => required, "suggested" => suggested }
+        observed = observed_execution(outcome)
+        plan["execution"] = observed[:execution] unless observed[:execution].nil?
+        plan["requirements"] = observed[:requirements] unless observed[:requirements].nil?
+        plan["reasons"] = observed[:reasons] unless observed[:reasons].nil?
+        plan
+      end
+
+      # Observed facts about the verification that produced this packet: which
+      # analyzers executed, per-framework test scope, and policy requirement
+      # statuses. Never a prediction; re-running `required` re-plans via the
+      # canonical engine. Best-effort: absent on outcomes that cannot project.
+      def self.observed_execution(outcome)
+        document = PRIntelligence.document(outcome)
+        policy = EngineeringPolicy.evaluate(outcome: outcome, pr_document: document)
+        scope = document["verification_scope"].is_a?(Hash) ? document["verification_scope"] : {}
+        frameworks = scope["frameworks"].is_a?(Hash) ? scope["frameworks"] : {}
+        evidence = Array(document["analyzer_evidence"])
+        {
+          execution: {
+            "analyzers_executed" => evidence.select { |entry| entry["evidence_status"] == "complete" }
+              .map { |entry| entry["analyzer"].to_s }.sort,
+            "test_scope" => frameworks.to_h do |name, entry|
+              [name.to_s, { "executed" => entry["executed"] == true, "scope" => entry["scope"].to_s }]
+            end
+          },
+          requirements: Array(policy["requirements"]).map do |entry|
+            { "id" => entry["id"], "status" => entry["status"] }
+          end.sort_by { |entry| entry["id"] },
+          reasons: Array(policy["reason_codes"]).sort
+        }
+      rescue RailVerdict::Error, ArgumentError, NoMethodError
+        {}
       end
 
       def self.required_check(base_revision: nil)

data/lib/rail_verdict/reporters/console.rb

@@ -88,6 +88,8 @@ module RailVerdict
             sanitize(rc["scope"] || "unknown"))
         end
 
+        append_change_intelligence(lines, result)
+
         lines << ""
         lines << "Gate: #{result.gate}"
         lines << "Policy: #{result.policy_status}"
@@ -102,6 +104,44 @@ module RailVerdict
         value.to_s.gsub(/[[:cntrl:]]/) { |character| character == "\n" ? " " : "?" }
       end
       private_class_method :sanitize
+
+      # Compact reviewer summary for changed-scope runs. Path-derived only;
+      # verification scope reflects executed analyzer evidence.
+      def append_change_intelligence(lines, result)
+        git = result.git
+        return unless git.is_a?(Hash) && git["error"].nil?
+
+        paths = Array(git["changed_files"]).map { |file| file["path"] }.compact
+        surfaces = RailVerdict::ChangeSurfaces.detect(paths, available: true)
+        signals = RailVerdict::ChangeIntelligence.review_signals(surfaces, [])
+        risk = RailVerdict::ChangeIntelligence.review_risk(signals, {})
+        lines << ""
+        lines << "Review risk: #{risk.fetch('level')}"
+        lines << "  reasons: #{risk.fetch('reasons').join(', ')}" unless risk.fetch("reasons").empty?
+        sensitive = surfaces.select { |_, entry| entry["changed"] && entry["sensitive"] }
+        lines << "Sensitive surfaces: #{sensitive.empty? ? 'none' : sensitive.map { |id, _| sanitize(RailVerdict::ChangeSurfaces::SURFACES[id]['label']) }.join(', ')}"
+        scopes = executed_test_scopes(result)
+        lines << "Tests: #{scopes.empty? ? 'no test evidence' : scopes.join('; ')}"
+        focus = RailVerdict::ChangeIntelligence.review_focus(surfaces, [], paths)
+        unless focus.empty?
+          lines << "Reviewer focus:"
+          focus.first(3).each { |item| lines << "  #{item.fetch('rank')}. #{sanitize(item.fetch('title'))}" }
+        end
+        nil
+      end
+      private_class_method :append_change_intelligence
+
+
+      def executed_test_scopes(result)
+        result.analyzer_results.filter_map do |analyzer|
+          next unless %w[rspec minitest].include?(analyzer.analyzer)
+
+          summary = analyzer.evidence_summary
+          scope = summary.is_a?(Hash) ? summary["test_scope"] : nil
+          "#{analyzer.analyzer} #{scope || analyzer.execution_status}"
+        end
+      end
+      private_class_method :executed_test_scopes
     end
   end
 end

data/lib/rail_verdict/reporters/engineering_policy.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module Reporters
+    # Bounded console projection of an engineering-policy-v1 envelope.
+    # Presentation only: requirement identity lives in the JSON document.
+    module EngineeringPolicy
+      MAX_OBSERVED = 5
+
+      module_function
+
+      def render(document)
+        lines = []
+        lines << "Engineering policy: #{document['decision']} (gate #{document['gate']})"
+        lines << "Policy: #{short(document['policy_digest'])}  Config: #{short(document['configuration_digest'])}"
+        requirements = document["requirements"] || []
+        if requirements.empty?
+          lines << "Requirements: none configured; decision mirrors the deterministic gate."
+        else
+          lines << "Requirements:"
+          requirements.each do |entry|
+            lines << "  [#{entry['status']}] #{entry['id']} — #{entry['trigger']}"
+            observed = Array(entry["observed_evidence"])
+            unless observed.empty?
+              head = observed.first(MAX_OBSERVED)
+              head.each { |line| lines << "      #{truncate(line.to_s)}" }
+              extra = observed.length - head.length
+              lines << "      (+#{extra} more)" if extra.positive?
+            end
+            lines << "      recovery: #{entry['recovery_action']}" if entry["recovery_action"]
+          end
+        end
+        drift = document["drift"]
+        lines << "Policy drift: #{drift['status']} (#{drift['code']})" if drift.is_a?(Hash)
+        lines << "Reason codes: #{Array(document['reason_codes']).join(', ')}"
+        "#{lines.join("\n")}\n"
+      end
+
+      def short(digest)
+        digest.is_a?(String) ? digest[0, 12] : "unknown"
+      end
+      private_class_method :short
+
+      def truncate(text)
+        text.length > 160 ? "#{text[0, 157]}..." : text
+      end
+      private_class_method :truncate
+    end
+  end
+end

data/lib/rail_verdict/reporters/github_annotations.rb

@@ -21,7 +21,12 @@ module RailVerdict
           file_part = "file=#{escape_property(path)}"
           line_part = line ? ",line=#{line}" : ""
           col_part = col ? ",col=#{col}" : ""
-          title = escape_data("#{analyzer}:#{rule_id}")
+          title_rule = if rule_id.to_s.start_with?("#{analyzer}:") || rule_id.to_s.start_with?("#{analyzer}/")
+                         rule_id.to_s
+                       else
+                         "#{analyzer}:#{rule_id}"
+                       end
+          title = escape_data(title_rule)
           msg = escape_data("#{message} [#{finding['state'] || finding[:state] || 'observed'}]")
           lines << "::#{level} #{file_part}#{line_part}#{col_part},title=#{title}::#{msg}"
         end